Skip to content

spec(FIX-2160): a message addresses a task or one of the user's conversations - #4000

Merged
jhoffner merged 3 commits into
mainfrom
spec/FIX-2160
Oct 27, 2026
Merged

jhoffner merged 3 commits into
mainfrom
spec/FIX-2160

Conversation

@jhoffner

Copy link
Copy Markdown
Collaborator

Requested by Jake · project thread

spec(FIX-2160): a message addresses a task or one of the user's conversations

Someone who… Today (with FIX-2238) After
asks about the task of another worker Sends to the worker name. The message goes to the default conversation, away from the task history sendMessage({ to: { task: id } }) goes to the session that works the task, open or finished. On an open task, it runs after the task turn. The task does not change
pastes one of their conversations Cannot point a worker at a second conversation sendMessage({ to: { session: id } }) goes to that conversation. The server checks it before it writes
sends to a session that is not theirs, or not a conversation (no such target) The server refuses it before the row. Another user, org or tenant reads as "not found"
asks the coder about a finished coding task Refused by name One harness run resumes the coding session of the task, and its reply is the answer
asks the coder about a coding task that runs (no such target) Refused task_running before the row. A message never steers

Goal: a worker reaches the session that works any task of its user, or any conversation of its user, by id. The server checks each target before it writes anything. The coder answers a message about a finished coding task from the coding session of that task.

flowchart LR
  A["Shift Manager DevTeam · real model · fresh SQLite store"] --> L6["leg 6 · to a task · open, finished, not started, Bob's"]
  A --> L7["leg 7 · to a session · second conversation, project conversation, every refusal"]
  A --> L8["leg 8 · to the coder's task · finished, running"]
  L6 -->|"in the task's session, after its turn, task unchanged"| P["PASS"]
  L7 -->|"reached, or refused with no row"| P
  L8 -->|"the coding session answers · running refused"| P
  C["control · FIX-2238's head"] -.-> L6
  L6 -.->|"under the control"| F["must FAIL · to accepts a worker name only"]
Loading

The check reads the stored items of the recipients, the tool outputs and the message log. Check: goals/shift-manager/workers-message-each-other/ legs 6, 7 and 8, real model. The control is the head of FIX-2238, where every leg must fail. Each leg also has its own control.

How: the task ledger finds a row by id across conversations, and the send reads the run link on the row. One new engine read checks the target session (user, org, tenant, flow, readonly markers) before the budget and the row. The coder gets harnessTalkTurn, the talk half of its session door.

Sign off

The goal, at that size. If wrong: the epic ends with { task } only for tasks on the board of the sender.

The debt: up a little. Adds a ledger lookup by id and one engine verb. Removes nothing more than FIX-2238 removes. If wrong: the engine verb becomes a session reader that capabilities use for more than checks.

The task ledger finds a row by id across conversations · D1

The ledger finds the row by id, chosen, beside a list of every task row of the user. Decides it: the cost of one send. Price: an id index in the ledger

It comes down to the cost of one send: one read by id, or every row of the user. If wrong: an orchestration index that nothing else uses.

One new request-host read checks a session before the row · D2 · the one to weigh

A request-host read of the session of the user, chosen, beside the recipient entry that checks itself. Decides it: when a bad target is refused. Price: an eighth verb on a closed seam

It comes down to when the server refuses a bad target: before the row (epic ER-3), or after. The seam header says it is closed at seven verbs, and an eighth needs review. If wrong: a session reader that any capability can call.

A message to an open coder task is refused · D3

Refuse a message to an open coder task, chosen, beside a resume of its coding session between runs. Decides it: what the next attempt resumes. Price: no message about work that runs

It comes down to what the next attempt resumes. The coder talk is a coding run in the checkout of the task, so it would steer the work. If wrong: workers cannot ask a coder about running work by message.

All three are in DECISIONS.md. Open: none.

Analysis: right work. It changed D1 from a Workforce copy of the task session to a ledger lookup by id (FIX-2255 is closed into this issue). Every { task } now also goes through the session read, because the ledger crosses orgs. (Analysis)

Reviewers · look here

  1. DECISIONS.md D2: is a new request-host read correct, or does the engine already give a block a way to check a session before it writes?
  2. DECISIONS.md D1: does the lookup by id cover every task a { task } must reach (ongoing, routed, follow-ups)?
  3. SPEC.md → What's already here: a way to reach a session of the user that the table does not name.

Not here: the build plan and the docs prose (the implementer does them).

SPEC.md · DECISIONS.md · FIX-2160 · epic FIX-2070 · builds on FIX-2238 · Merge after approval and required checks; the merge is the approval.

How to review this

This is a direction set, not an implementation and not a build plan. Reviewing it well means
answering one question: is this the right approach?

In scope to challenge:

  • The goal and the problem framing in SPEC.md — is the goal the real need at full size,
    for the people named, or a smaller goal that would let us call this done early? Would the
    named check fail if the goal were not met?
  • The approach — will it work, does it fit the architecture and docs/philosophy.md?
  • Any numbered decision in DECISIONS.md — that's the sign-off surface.
  • The debt in SPEC.md → What's already here, and the debt — an existing primitive,
    method or prior design the change overlaps and doesn't name; something it adds that is debt
    and isn't listed; a net verdict the tables don't support.
  • Builds on / Adds in that same section — an Adds item that does not name the existing
    piece it considered, or that is a second mechanism for something we already have
    (orchestration.md).
  • A case a person would hit that the people table misses, when it would invalidate the
    design.
  • Scope — a deliverable that shouldn't ship, or one that's missing.

Out of scope — deliberately unsettled here, and owned by the implementing agent:

  • The build plan. Order, file-level changes, the test list, the PR split. The set has no
    plan on purpose: the implementer works it out against the real code.
  • Names, signatures, file paths, and module layout, beyond the few a decision locks.
  • Local structure: which helper, how a function is decomposed, error-message wording.
  • Edge cases that don't change the approach. The implementer's tests own them.
  • Documentation wording. It is written at implementation, against what shipped.
  • Micro-optimizations and style preferences.
  • The figures, at the pixel level. A figure is right when it reads right. A misplaced label
    or a colour you'd have chosen differently is not a finding; a figure that shows a shape the
    decisions don't say is.
  • POC implementation polish. Experiments under the owning spec's poc/ are retained,
    not production code. Read them for directional evidence, not production completeness.
    Their isolation from production/default discovery and absence of secrets or generated
    dependencies are in scope; retention is not permission to weaken repository checks.

One request, if you are an automated reviewer: the two lists above are the whole difference
between a useful review of this document and a long one. Volume is not signal here — a single
finding above the line is worth more than twenty below it.

Feedback in the second list is welcome and gets recorded verbatim in
DECISIONS.md → Notes from review
for the implementer to weigh against real code. It will not
be argued with, and it will not be folded into the design prose. Please don't re-raise it: one
mention is enough.

The one exception is the POC. Line-level feedback on it is dropped, not recorded — there
is nothing for an implementer to weigh about code that isn't shipping. Feedback about its
direction is not line-level and is treated like any other above-the-bar finding.

Direction approval does not waive merge-time required checks, approvals or thread policy.
Optional comments do not require another design round merely to reach zero comments.

Engineering calls
  • A { task } that resolves to the sending session is refused not_yourself (the Codex question on FIX-2160: messages can address one of your own conversations #3789).
  • A task not started, a task of another user, and an unknown id all get one refusal, no_task_session.
  • { session } refusals: no_session, not_a_conversation (task or delegate session), no_worker, worker_unavailable (moved), not_yourself.
  • A message to an open task of an agent worker runs after the task turn, through the existing defer policy.
  • harnessTalkTurn is extracted from harnessSessionDoor; there is one talk path.
  • No lookup tool: the user pastes the id (rule 21).

Generated by Claude Code

…rsations

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiD7QxMPGxa4XV4dZEF
@vercel

vercel Bot commented Oct 27, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Oct 27, 2026 9:34pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 27, 2026 9:34pm UTC
flow-state-dev-ui Ignored Ignored Preview Oct 27, 2026 9:34pm UTC

Request Review

@jhoffner jhoffner added the spec label Oct 27, 2026 — with Claude
@linear-code

linear-code Bot commented Oct 27, 2026

Copy link
Copy Markdown

FIX-2160

@jhoffner jhoffner self-assigned this Oct 27, 2026
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 27, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-27T21:36:14.836301Z df5f0af New commits
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Architect coherence check: no fork. This matches epic FIX-2070's FIX-2160 row ({ task } and { session }, rule 21 via #3797), builds on FIX-2238's send path and onMessageReceived, and closes FIX-2255 into D1 without a second record of where a task runs. D2's eighth request-host verb is correctly flagged as the one for Jake to weigh. I don't see another in-flight spec widening that seam.

Two non-blocking sibling notes:

  1. The goal legs collide. All three stacked siblings amend goals/shift-manager/workers-message-each-other/ under the same leg number. This PR uses legs 6, 7 and 8 (signals 6:…, 7:…, 8:…). spec(FIX-2240): a message lands once #3999 (FIX-2240) uses leg 6 (6:crash-after-row, …), and spec(FIX-2239): a call waits for the recipient's result until its deadline #3997 (FIX-2239) uses legs 6, 6b and 6c. The epic stacks the implementations FIX-2160, then FIX-2240, then FIX-2239, so this PR keeps 6–8 and the other two should renumber after it. Please add a note to DECISIONS that FIX-2160 owns legs 6–8 of that goal, so the siblings can renumber against it.
  2. A call to a running coder task. D3 refuses task_running before the row. FIX-2239 (spec(FIX-2239): a call waits for the recipient's result until its deadline #3997) queues a call behind a busy recipient. The call goes through this send path, so the refusal should come first. A one-line note that task_running is decided before any call queueing would stop FIX-2239's implementer from reading a running coder task as "busy, so queue".

— FSD Architect

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass (spec direction only)

Read SPEC.md and DECISIONS.md, and spot-checked the claims against main (partition.ts, create-request-host.ts). The direction holds. { task }/{ session } as two targets on the one tool, the run link kept as the single truth of where a task runs, and harnessTalkTurn extracted from the door (one talk path) are all the lean choices. Findings, ranked:

Above the bar

  1. D1's id index has no story for rows that predate it (BP-030). The index is "written in its own add", so every task filed before this ships has no entry. { task } to any of them returns no_task_session, which is indistinguishable from "not started" or "not yours". The most likely first use is a user pasting the id of a task from before the deploy, so this lands in the demo path. DECISIONS should say one of: (a) a miss falls back to a bounded partition scan, then writes the entry, (b) a one-time backfill, or (c) a deliberate "new tasks only" with the refusal naming it. I'd lean (a): it also covers an index write that failed or was lost, and it keeps the index an optimization, not a second source of truth.
  2. The index is a shared read-modify-write key. "Which partitions hold each task id" is a set per id, and the review note already says two partitions can hold the same id and the lookup must keep both. Two concurrent filings of the same id in different partitions can overwrite each other unless the entry is one key per (id, partition) or the write is a conditional append (BP-035 concurrent path). The spec says "one key per task", which is the shape that loses the second writer. Pin the shape in D1: per-(id, partition) keys, then "more than one" falls out of a prefix list for free.
  3. Index lifetime. What does the index do when a row is pruned, archived, or the partition is recreated under a new lineageId? A stale entry gives a row read that misses, which should map to no_task_session rather than throw. One sentence in D1 closes it.

Worth weighing (the architecture side)

  1. D2 could be narrower than a generic sessions.read. wakes (sixth verb) already receives stores.session and checks the target session's flow inside the engine without ever returning the record. sessions.read returns { flowKind, flowId, state }, and "state cut to readonly fields" is a new projection a later caller can lean on. The spec names that risk ("a session reader any capability can call") and also lists it as a benefit ("the generic read a later lookup tool also needs"). That is the contradiction in the debt table: pick one. If Workforce only ever needs the markers plus worker/flow identity, the verb could return exactly { flowId, workerId, taskId, filingSessionId } and no free-form state. That keeps the seam closed in spirit, and a later lookup tool can widen it in its own reviewed change. I'd do that now. This is the answer to reviewer question 1: the engine has no block-facing way to check a session, but it does have the pattern (wakes) of a verb that checks inside the engine.
  2. not_yourself vs no_task_session ordering. For { task } the order of checks (own session, then org/tenant read, then worker roster) decides what a different-org task id leaks. The spec orders { session } refusals but not { task }. State it, so the read comes first and not_yourself can only fire for the sender's own tenant.
  3. D3's task_running is correct but its open-row check is a second reading of "open". It reads the task and its follow-ups "as the door's sessionRow reads them". Say that the send calls the same function the door uses, not a parallel predicate, or the two drift (tenet 2). harnessTalkTurn is the natural home for it.

Notes for the implementer (not requesting a design round)

  • Docs list includes packages/core/README.md "if it lists the verbs". Run the grep for the header lines in create-request-host.ts and dispatched-work.md that say "seven" (BP-034).
  • The goal's control list is long (five controls across three legs). Fine, but the model-free CI tests should carry the refusals so the real-model run is only the landing and coder legs.

No objection to merging once 1 and 2 are settled in DECISIONS.md; 3–6 can ride as notes.


Generated by Claude Code

Copy link
Copy Markdown
Collaborator Author

Both notes are folded in 265c807, under DECISIONS.md → Decided, not asked. FIX-2160 owns legs 6, 7 and 8 of workers-message-each-other. FIX-2240 and FIX-2239 number their legs from 9. task_running is a refusal at send time, so a call to a running coder task is refused. It never waits in FIX-2239's queue as a busy session.


Generated by Claude Code

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Confirmed at 265c807: both notes match what I asked. FIX-2160 owns legs 6, 7 and 8 of workers-message-each-other, and task_running is a send-time refusal decided before FIX-2239's call queue. Resolved, no fork. I'll ask #3999 and #3997 to renumber from 9.

— FSD Architect

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Simplify review (spec altitude)

Verdict: Direction looks right for ER-2/ER-3 (“checked before anything is written”) and the partitioned ledger layout on main. I would approve the spec direction; the residual risk is implementation surface (refusal ordering, asymmetric open-task rules), not picking the wrong backbone.

Did the approach go too far?

Mostly no, with two infrastructure bets bundled into one messaging issue:

  1. D1 (ledger id index) — Rejecting user-wide list() per send is correct (BP-033). The index is the standard fix for tasks/<partition>/<id>. A lighter v0 the spec does not explore: partition-scoped point reads (probe tasks/<partition>/<id> for each known conversation partition) is O(conversations), not O(all tasks). For early labs with few conversations that might defer permanent index growth until measured; at DevTeam scale the index is the cleaner long-term bet. Absorbing FIX-2255 here is coherent.

  2. D2 (sessions.read) — Widening the “closed at seven verbs” seam is real debt, but recipient-side checks after the row violate the epic, and a Workforce session index duplicates guards. Exposing resolveExistingSession’s rule as a read is the smallest seam extension that still enables { session } and { task } org checks. Suggestion (implementation): return the minimum Workforce needs (readonly markers + flowKind/flowId), not a general session peek, and reuse one read result on the { task } path (row → run.sessionId → checks) to avoid double session.get.

  3. D3 (task_running + harnessTalkTurn) — Asymmetric but justified: agent open tasks defer; coder open tasks would resume checkout work. Refusing task_running is simpler than between-run resume. Finished-task answers are inherently harness-heavy; no lookup tuning fixes that.

Cleaner change shape (if you wanted less in one PR)

Not necessarily better for the epic, but for complexity budgeting: stack D1 + { task } to agent workers first (no coder turn), then D2 + { session }, then coder finished path + D3. The spec’s single PR is defensible because goal legs 6–8 need the full story; just flag that implementers inherit three sub-deliverables.

What I’d simplify in the artifact (no product fork)

  • Collapse overlapping mermaid in SPEC (“What changes” vs “How a target resolves”).
  • Add one ordered refusal table (engine read empty → markers → roster → flow → self) with a column for which steps apply on { task } after ledger resolution — “Decided, not asked” is complete but easy to mis-implement.
  • Trim or relocate the dense Signal matrix to the goal runner; keep 2–3 invariants per leg in SPEC.
  • Clarify shift-manager touch is goal-only unless you expect app wiring beyond amended legs.

Third-party / reuse

No obvious off-the-shelf package replaces a user-scoped id index or engine-guarded session read; the schedule index pattern (derived key on resource hook) is the closest in-repo precedent for D1 maintenance semantics.

Performance notes for implementers

  • Co-locate index write with row create (same failure domain).
  • D3 open detection: partition-scoped list/filter (door sessionRow pattern), never user-wide ledger scan.
  • Index grows with lifetime tasks (accepted permanent debt); monitor if heavy users matter later.

Checks: Read SPEC.md, DECISIONS.md, and grounded against partition.ts / create-request-host.ts on this branch; did not run goal legs or CI (spec-only PR).

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/issues/FIX-2160/DECISIONS.md Resolved
Comment thread specs/issues/FIX-2160/DECISIONS.md Resolved
Comment thread specs/issues/FIX-2160/DECISIONS.md Resolved
Comment thread specs/issues/FIX-2160/SPEC.md Resolved
Comment thread specs/issues/FIX-2160/SPEC.md Resolved
@jhoffner
jhoffner merged commit 4096327 into main Oct 27, 2026
7 checks passed
@jhoffner
jhoffner deleted the spec/FIX-2160 branch October 27, 2026 21:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants