diff --git a/specs/issues/FIX-2160/DECISIONS.md b/specs/issues/FIX-2160/DECISIONS.md new file mode 100644 index 0000000000..517c4780bf --- /dev/null +++ b/specs/issues/FIX-2160/DECISIONS.md @@ -0,0 +1,175 @@ +# FIX-2160 · Decisions + +[Spec](SPEC.md) · **Decisions** + +The epic decided the model ([FIX-2070](../../epics/FIX-2070/DECISIONS.md)): `{ task }` lands in +the task's session, `{ session }` is checked within the sender's tenant before anything is +written (ER-2, ER-3); FIX-2238 decided the coder hears only in its tasks' sessions and moved its +talk turn here. Two facts on `main` shape what is left. A task row lives at +`tasks//`, so a bare task id finds no row without its partition +(`orchestration/tasks/collection/partition.ts`). And no block can read another session's record: +the dispatch guards read it and only refuse (`engine/context/create-request-host.ts`). D1 and D2 +answer those; D3 is the coder's open task. + +## The tree + +```mermaid +flowchart TD + I["FIX-2160"] --> D1["D1 · the ledger finds a task row by id · the send reads its run link"] + D1 -.->|"rejected"| X1["list every task row the user has, per send"] + D1 -.->|"rejected"| X6["a Workforce copy of where each task runs · stale on a retry"] + D1 -.->|"rejected"| X2["find a session by its taskId marker · misses ongoing, routed and follow-up tasks"] + I --> D2["D2 · one request-host read checks a session before the row"] + D2 -.->|"rejected"| X3["the recipient checks itself · after the row"] + D2 -.->|"rejected"| X4["a Workforce index of conversations · a second session record"] + I --> D3["D3 · the coder's open task refuses a message · task_running"] + D3 -.->|"rejected"| X5["resume the coding session between runs · a quiet steer"] +``` + +Solid edges are what you're signing. Dashed edges lost, and the label says why. + + +## D1 · The task ledger finds a row by id across conversations; the send reads its run link + +*An engineering call that adds a lookup to orchestration, so it is on the sign-off.* + +| | | +|---|---| +| **Instead of** | Listing the user's whole task ledger and keeping the row with that id; finding a session whose readonly `taskId` marker names it; or a Workforce index that copies where each task runs | +| **Because** | The list loads every row of every conversation on each send (BP-033), and grows with the user's history. The marker misses three kinds of task: one filed `session: "ongoing"` (the delegate's session has no `taskId`), one routed to a workstream session, and a follow-up (its session carries the root's id). A Workforce copy of `run.sessionId` is a second record that a retry in a new session leaves stale. The run link on the row already names the session for every dispatched task, from its one writer, the claim gate. What is missing is only finding the row: the ledger stores it at `tasks//`. So the ledger learns to find a row by id, and nothing about where a task runs is copied | +| **How** | The partitioned ledger keeps, at the owner's scope, which partitions hold each task id, written in its own add, the one path every filing passes (a piece, a retry, a follow-up, a replan, a scheduled filing). Generic: orchestration knows no conversation. The send finds the row, reads `run.sessionId` and the row's status, then checks that session with D2's read, as a `{ session }` is checked. No row, no run link (not started, or an inline plan step), an id held in more than one partition (ids a caller picks are unique per partition only), or another user's: `no_task_session`, one answer, so a refusal tells nothing of another user's tasks. This is FIX-2255's ask, built here | +| **Locks in** | A lookup by id on a partitioned ledger; the refusal `no_task_session` | + +**What would change my mind:** task ids becoming unique per user at filing. Then the index can be +the ledger's key and the "more than one" refusal goes. + +![D1: the ledger finding a row by id, chosen, beside listing every task row the user has; decided by one send's cost. The price: an id index the ledger keeps](figures/d1-task-index.svg) + +It comes down to one send's cost: one read by id, or every row the user has. + + +## D2 · The server checks a `{ session }` with one new request-host read + +*A product call: it widens the engine seam its header calls "closed at seven verbs", and says +an eighth is a reviewed decision.* + +| | | +|---|---| +| **Instead of** | Letting the recipient's `onMessageReceived` check its own session's markers, after the row is written and the message dispatched; or a Workforce index of every conversation | +| **Because** | Epic ER-3 checks a target "before anything is written", so a refusal pays nothing and leaves no row. The markers, the worker and the org are on the target session's record, which only the engine reads today. A Workforce index would be a second record of every session, written at every create. The engine already has the rule: its dispatch guards refuse another user's or tenant's session as not found, and another flow's or org's as not addressable. Exposed as a read, the rule stays in one place ([tenet 2](../../../docs/philosophy.md)) | +| **How** | `requestHost.sessions.read(id)` returns `{ flowKind, flowId, state }` for a session of the running user, in the running tenant and org, with `state` cut to the flow's readonly fields (the rule the HTTP session list's state filter already keeps); `undefined` for any other or a missing one. The org and tenant rule is the guards' own (`matchesOrgFilter`), inside the engine, so it stays in one place and no capability sees another org's session. Identity is closed over. Layer 1 stays generic: Workforce reads the markers. The seam's header gains the verb, and its "neither is a session id" line names the dispatch `{ id }` target as the precedent | +| **Locks in** | The verb `sessions.read`, the request host's eighth; Workforce's refusals for `{ session }` (below) | + +**What would change my mind:** a lab that needs `{ session }` across a host that can't read its +sessions. Then `{ session }` is refused on that host, as a call is without a wait gate. + +![D2: a request-host read of the user's own session, chosen, beside the recipient's entry checking itself; decided by when a bad target is refused. The price: an eighth verb on a closed seam](figures/d2-session-read.svg) + +It comes down to when a bad target is refused: at the send, before the row, or after it. + + +## D3 · A message to the coder's open task is refused `task_running` + +*A product call: the epic says a message to an open task is conversation in its session, and the +coder can only talk by resuming a coding session its next attempt also resumes.* + +| | | +|---|---| +| **Instead of** | Resuming the task's coding session with the message between runs, once the checkout's lease frees | +| **Because** | The coder's talk is a coding-agent run in the task's checkout (`session-door.ts`), which can change the files the task is working on, and the next attempt resumes the same coding session (`harness-manager/manager.ts`, LAB-154). So a message would act on the work itself, and a message never steers (rule 21). An agent worker's turn also reads its session's history, but a message's turn there changes no checkout and runs after the task's turn. A person who means to steer types in the session, and the door makes that a steer on the row. A finished task has no next attempt | +| **How** | The send reads the recipient's `hears` and the rows that run in the task's session: the task and its follow-ups, as the door's `sessionRow` reads them. `hears: "task-sessions"` and any of them open: refused `task_running`, before the row, naming `getTask` and the task's ending. A finished row: delivered, and `harnessTalkTurn` resumes the coding session once, outside any attempt, as the door's talk does; its reply is the answer in that session | +| **Locks in** | `task_running`; `harnessTalkTurn` as the door's talk half, shared | + +**What would change my mind:** a lab where workers must ask a running coder what it is doing. Then +a read-only status turn answers from the run record, without resuming the coding session. + +![D3: refuse a message to the coder's open task, chosen, beside resuming its coding session between runs; decided by what the next attempt resumes. The price: running work can't be asked about by message](figures/d3-coder-open-task.svg) + +It comes down to what the next attempt resumes: the work's own history, or a message in it. + +## Decided, not asked + +- **`{ task }` to an agent worker's open task** is delivered, and runs after the task's turn, by + the entry's existing `defer` concurrency (FIX-2238 keeps it). Nothing reads the row for it. +- **A `{ task }` that resolves to the sending session is refused `not_yourself`**, as a worker's own + name is (rule 21). This settles Codex's question on #3789. +- **`{ session }`'s refusals, in order:** the read returns nothing (missing, another user's, + another org's or tenant's) → `no_session` (one answer, so it tells nothing of another's sessions); a + `taskId` or `filingSessionId` marker → `not_a_conversation`, naming `{ task }`; no `workerId`, or a + worker not on the roster now → `no_worker`; the session's flow isn't the worker's flow now → + `worker_unavailable`; the sending session's own id → `not_yourself`. A workstream's session and a + project's conversation are conversations, and are reached. The recipient's `hears` applies as + for a name: the coder has no conversation, so any `{ session }` to it is `not_a_conversation`. +- **Where the checks run:** in the send, after the text check and before the budget, the one + convergence point every send passes (FIX-2238's `sendMessage` server function). The tool's + description gains the two targets; its list of workers is unchanged. +- **The row** gains the target kind FIX-2238 added (`worker`, `task`, `session`) and, for + `{ task }`, the task id, so the Messages view can say "to Researcher's task". `to` stays the + recipient worker's id. +- **A `{ task }`'s session gets every `{ session }` check but the markers:** D2's read (so another + org's task, which the user-scoped ledger would find, is refused before the row), the worker on the + roster now, and its flow. A plan board's steps are on a ledger of their own; the lookup serves the + conversation ledger, and a step's id is `no_task_session` (an inline step has no run anyway). +- **`harnessTalkTurn`** takes the door's board and harness options, finds the session's row + (`sessionRow`), and refuses with the door's own reasons if the row has no coding session + (`cannot-continue`). The door's talk calls it, so there is one talk path. +- **No lookup tool**: the user pastes the id (rule 21's first version). +- **`task_running` is decided before any queueing.** It is a send-time refusal, so a call to a + running coder task is refused, never queued behind it as a busy session (FIX-2239's queue). +- **The goal's legs:** FIX-2160 owns legs 6, 7 and 8 of `workers-message-each-other`; FIX-2240 and + FIX-2239, stacked after it, number theirs from 9. + +## Considered and dropped + +- **Task ids that carry their partition.** Every task id a model sees today is bare; changing the + format moves every tool, notice and screen for one lookup. +- **A dispatch "check only" mode instead of a read.** It widens the dispatch seam just as much, + and still can't answer the marker questions, which are Workforce's. +- **Refusing every `{ task }` to an open task.** An agent worker's open task already runs a + message after its turn without touching the work; only the coder's resume is a steer. + +## Open / Settled + +**Open: none.** + +No counted facts rest on hand derivation. The three places FIX-2160 builds on (the partition key, +the guards' rule, the run link's one writer) were each found by search on `main` at `9cc15c3`; +the implementer re-runs them. + +## How it got here + +- **Draft** — framed as the addressing child of FIX-2070 on FIX-2238's send path. Research on + `main` found that a task id has no lookup across conversations and no block reads another + session; D1 and D2 add the smallest piece for each, and D3 keeps a message from steering a coding + run. +- **Analysis fold** — D1 moves from a Workforce index of where tasks run to the ledger's own lookup + by id (FIX-2255, absorbed); every `{ task }` passes the session read; the read owns the org rule. + +## Analysis + +2026-10-27, a fresh reviewer at spec altitude, with `reuse-review` on Builds on / Adds, on the +draft at `9cc15c3`. Verdict: the right work; D1 reshaped. Reuse: the lookup extends the +partitioned ledger (it is FIX-2255); `sessions.read` extends the dispatch guards' predicates; +`harnessTalkTurn` is extracted from the door. Folded: D1 keeps only id → partition in the ledger and +reads the run link, instead of a Workforce copy that a retry makes stale; a `{ task }`'s session +passes D2's read too, since the user-scoped ledger crosses orgs; the read refuses another org +itself and returns only readonly state; D3's open check covers the session's follow-ups. Recorded +below. + +## Notes from review + +- **Cursor simplify review (#4000), approved; recorded for the implementer:** one `sessions.read` + result serves every check on a `{ task }` (org, markers, roster, flow), never two reads; keep the + read's return to what the refusals need, and a later lookup tool extends this verb rather than + adding a ninth; write the ledger's id index in the row's own add, as the schedule index derives its + key, rather than a new indexing pattern; an ordered table of the refusals, with a column for which + apply to a `{ task }`, belongs in the implementation's tests and the messaging page. Dropped: + probing each conversation's partition (no server read lists a user's conversations), and moving + the goal's signal list out of `SPEC.md` (the template keeps it there). +- **FSD Architect (#4000), folded inline:** the goal-leg numbering and `task_running` before a call's + queue, both in *Decided, not asked*. No fork. + +- **Analysis, recorded:** D3's reason is the checkout, not history alone (folded into the card). The + request host's header lines on session ids and records change with the verb (BP-034). A caller can + pick a task id, so the same id can sit in two partitions; the lookup must keep both, never + overwrite one with the other. diff --git a/specs/issues/FIX-2160/SPEC.md b/specs/issues/FIX-2160/SPEC.md new file mode 100644 index 0000000000..dc69dd8c12 --- /dev/null +++ b/specs/issues/FIX-2160/SPEC.md @@ -0,0 +1,172 @@ +# FIX-2160 · A message addresses a task or one of the user's conversations + +**Spec** · [Decisions](DECISIONS.md) + +## Six people, before and after + +| Someone who… | Today (with FIX-2238) | After | +|---|---|---| +| **builds a worker that asks about another worker's task** | Can only `sendMessage({ to: "researcher" })`. The question lands in Researcher's default conversation, away from the task's history | `sendMessage({ to: { task: id } })` lands in the session working that task, open or finished, and `onMessageReceived` runs there with the task's history. On an open task it runs after the task's turn. The task doesn't change | +| **pastes one of their conversations into another worker's chat** | Has no way to point a worker at a second conversation with Researcher, or at the Shift Coordinator's conversation for a project | `sendMessage({ to: { session: id } })` reaches that conversation, checked by the server before anything is written | +| **sends to a session that isn't theirs, or isn't a conversation** | (no such target) | Refused before the row: another user's or org's session reads as not found; a task's or a delegate's session is refused naming `{ task }`; a fired or moved worker's session is refused | +| **asks the coder about a finished coding task** | Refused `task_sessions_only` by name, with nowhere else to send it | `{ task }` reaches the task's coding session: one harness run resumes it with the message, outside any attempt, and its reply is the answer there (a call, FIX-2239, returns it) | +| **asks the coder about a coding task still running** | (no such target) | Refused `task_running` before the row: a message never steers, and the next attempt resumes that coding session ([D3](DECISIONS.md#d3)) | +| **messages a task that hasn't started, or its own task** | (no such target) | Refused before the row: `no_task_session` (file a message with `updateTask` instead), or `not_yourself` when the task's session is the sender's own | + +Answers come back as FIX-2238 says: `inReplyTo` lands in the session that sent the original. + +## The goal, and how we'll know it's met + +**A worker reaches the session working any task of its user's, or any one of its user's own +conversations, by id, with every target checked by the server before anything is written, and the +coder answers a message about a finished coding task from that task's coding session.** + +| Is it the right goal? | | +|---|---| +| **The real need** | The epic's "a worker can message any worker, task or conversation of its user … in the session it is about" ([epic SPEC](../../epics/FIX-2070/SPEC.md)), the `{ task }` and `{ session }` half: [ER-2](../../epics/FIX-2070/DECISIONS.md#who-owns-what)'s `{ task }` leg and [ER-3](../../epics/FIX-2070/DECISIONS.md#who-owns-what). Stories M-09 and M-10, and rule 21 | +| **Smaller, and rejected** | "`{ task }` only for the sender's own board's tasks." It is a lookup the board already has, while M-09's "coder can message researcher's task though it neither filed it nor shares its board" fails, and `{ session }` stays unchecked | +| **Bigger, and not this issue's** | A tool that looks up a user's sessions (rule 21's later step) · a call that waits (FIX-2239) · delivery that survives a crash (FIX-2240) | +| **Not done if** | A `{ task }` message lands anywhere but the session the task's run named · a finished task's status, output or attempts change · an open task's message runs during its turn · another user's task or session is reached, or its existence shows in the refusal · a task or delegate session is reached by `{ session }` · another org's or tenant's session is reached · a fired or moved worker's session is reached · a refused target leaves a log row or spends budget · the coder's finished task isn't answered from its coding session · an open coder task's coding session is resumed by a message | + +```mermaid +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"] +``` + +The check reads the recipients' stored session items, the turns' tool outputs, the task rows and the message log, through Alice's and Bob's own clients. + +| How we verify | | +|---|---| +| **Goal check** | `goals/shift-manager/workers-message-each-other/`, amended with legs 6, 7 and 8, as FIX-2238 left it. Real model, run by the implementer at completion with `GOAL_LEGS=6,7,8 pnpm tsx goals/shift-manager/workers-message-each-other/run.mts`; PASS is every leg in 3 of 3 runs; verdict in the implementation PR. The model-free checks (each refusal, the lookup by id, the read) are also `packages/workforce` and `packages/engine` CI tests | +| **Signal** | `6:lands-in-task-session` Helper A's `{ task }` message to Researcher's open task is a received item in that task's session, and its `onMessageReceived` turn starts after the task's turn ended; `6:finished-keeps-history` to the same task once finished, the turn runs there and its model input holds the task's earlier lines; `6:task-unchanged` the row's status, output and attempts are the same before and after; `6:not-started` a message to a pending task is refused `no_task_session` and writes no row; `6:bobs-task` Bob's task id is refused exactly as an unknown id; `6:own-task` a task session's message to its own task is refused `not_yourself`; `6:other-org` Alice's task in her second org, sent from her first, is refused as an unknown id and writes no row. `7:second-conversation` a message to Alice's second conversation with Researcher, from Researcher's default one, lands there; `7:project-conversation` one to the coordinator's conversation for one of Alice's projects lands there; `7:refusals` Bob's session, Alice's session in her second org, a task session, a delegate session, a fired worker's session, a moved worker's session and the sending session each are refused and write no row. `8:finished-answered` a message to the coder's finished task is answered by one harness run that resumes the task's coding session, as an item there, with the row unchanged; `8:running-refused` one to its running task is refused `task_running` and writes no row | +| **Input** | DevTeam's workers as the goal hires them, plus Alice's second conversation with Researcher (`ensureWorkerSession` is not it: a second session opened through the session client), a project with its coordinator conversation, a second org for Alice, `fired-helper` hired then fired, `moved-helper` hired then moved to another flow. The coder's task is an answer task (no issue, no phase). Ids are picked at run time and pasted into the workers' lines | +| **Anti-game** | Landings read from the recipients' stored items; refusals from each turn's own tool output; "no row" from the Messages view's list; the task's fields from its row before and after. Nothing seeded | +| **Control that must fail** | FIX-2238's head (the stack's base): every leg fails, `6:lands-in-task-session` first (`to` takes a worker name only). `GOAL_CONTROL=task-to-conversation` (a `{ task }` lands in the assignee's default conversation) fails `6:lands-in-task-session`. `no-kind-check` (the `{ session }` markers unread) fails `7:refusals`. `no-org-check` fails `7:refusals` on the second org. `coder-resumes-open` (the talk turn resumes an open task) fails `8:running-refused`. The PR shows each FAIL before the PASS | + +## What changes + +```mermaid +flowchart LR + subgraph today ["Today, with FIX-2238"] + T1["sendMessage · to a worker name"] --> T2["the worker's default conversation"] + end + subgraph after ["After"] + A1["sendMessage · to a worker"] --> A2["default conversation"] + A3["to { task }"] -->|"the ledger finds the row by id"| A4["the session the task's run named"] + A4 -->|"requestHost.sessions.read · checked"| A6 + A5["to { session }"] -->|"requestHost.sessions.read · checked"| A6["the checked session"] + A4 -->|"the coder's finished task"| A7["harnessTalkTurn · resumes the coding session"] + end +``` + +Two new targets, each resolved and checked by the server before the row: a task through a lookup by +id the task ledger gains, then the session its run named; both through one new engine read. + +A worker's model calls the same tool with a new `to`: + +```diff +- sendMessage({ to: "researcher", text: "Does the CSV have a month column?" }) ++ sendMessage({ to: { task: "task_2026…" }, text: "Does the CSV have a month column?" }) ++ sendMessage({ to: { session: "wks_…" }, text: "Alice wants this in her other thread too." }) +``` + +The coder's flow gains its turn (FIX-2238 left it out): + +```diff + [MESSAGE_RECEIVED_ENTRY]: messageReceivedEntry({ + installation, flowKind: CODER_FLOW, hears: "task-sessions", ++ turn: harnessTalkTurn({ name: "coder", harness: options.harness, board }), + }), +``` + +**Docs:** update `apps/docs/docs/workforce/messaging-workers.md` (the two targets, what each lands +in, the refusals `no_task_session`, `task_running`, `not_a_conversation`, and pasting a session +id); `packages/workforce/README.md` → Worker messages; `packages/harness-manager/README.md` +(`harnessTalkTurn`); `packages/orchestration/README.md` (finding a task by id); `docs/architecture/dispatched-work.md` (the request host's eighth verb, +`sessions.read`); `packages/core/README.md` if it lists the request host's verbs. No new page. A +changeset for `@flow-state-dev/core`, `@flow-state-dev/engine`, `@flow-state-dev/orchestration`, +`@flow-state-dev/workforce` and `@flow-state-dev/harness-manager`. + +## How a target resolves + +```mermaid +flowchart LR + S["sendMessage · to"] --> K{"which target"} + K -->|"a worker name"| W["FIX-2238's rules"] + K -->|"task"| I["the ledger's row by id · user scope"] + I -->|"none · no run link · more than one"| R1["no_task_session"] + I --> T["the run link's session · the recipient's hears"] + T -->|"an open row in that session · hears task-sessions"| R2["task_running"] + T --> H + K -->|"session"| H["sessions.read · this user, org and tenant"] + H -->|"missing · marker · off roster · other flow"| R3["refused by name"] + H --> B["budget · row · dispatch"] +``` + +Every refusal is decided before the budget is paid or the row is written. + +## What stays as it is + +- FIX-2238's send path, budget, landing rules and refusals for a worker name. The new targets + join its checks before the budget, as the epic's seam table says. +- The coder's door (`harnessSessionDoor`): a person's line still steers an open task and talks to + a finished one. `harnessTalkTurn` is its talk half, shared, not a copy. +- The dispatch seam's `{ id }` guards: the delivery still passes them. +- The task ledger's partitions and key layout. + +## What's already here, and the debt + +| Already here | What this does with it | +|---|---| +| Ways a worker reaches a session of its user's, from searches of `packages/*/src` for `dispatchThroughSeam`, `SessionTarget`, `run.sessionId` and `findWorkerSession`: a task's hand-over (board), a notice to the filer (`{ from }`), FIX-2238's send to a worker's default conversation, and a person's own session client. None targets a task's session or a pasted id from a worker | **Extends** the send: two targets on the one tool, no new tool. Still three ways to reach a worker (FIX-2238's count) | +| FIX-2238 ([D1](../FIX-2238/DECISIONS.md#d1)): the coder hears only in its tasks' sessions, `hears: "task-sessions"`, with no turn | **Builds on**: adds `harnessTalkTurn`, and reads `hears` for the open-task refusal | +| The run link (`run.sessionId`, written once by the claim gate, `orchestration/task-board/task-entry.ts`) | **Kept** as the one truth of where a task runs; the send reads it off the row ([D1](DECISIONS.md#d1)) | +| The partitioned ledger (`orchestration/tasks/collection/partition.ts`): a row at `tasks//`, read one partition at a time | **Extended**: it finds a row by id across its partitions, through an id index it writes in its own add ([D1](DECISIONS.md#d1)). FIX-2255 asked for it and is closed into this issue | +| The dispatch guards (`engine/context/create-request-host.ts`, `resolveExistingSession`): another user's or tenant's session is `session-not-found`, another flow's or org's `session-not-addressable` | **Reused** as the read's rule: the read returns what the guards would let through ([D2](DECISIONS.md#d2)) | +| A session's readonly markers (`taskId`, `filingSessionId`, `workerId`) | **Read** for `{ session }`'s refusals, as the gaps file says | +| `harnessSessionDoor`'s talk path (`harness-manager/session-door.ts`) | **Extracted** into `harnessTalkTurn`; the door calls it | +| FIX-2152's rule 21 amendment (#3797) and the architect's shape on this issue | **Kept**; the `{ task }`-to-self question Codex raised on #3789 is settled: refused `not_yourself` | + +| Builds on / Adds | Existing piece considered | Why that doesn't fit, or how this is composed | +|---|---|---| +| The ledger's lookup by id across partitions | Listing the user's whole `tasks` ledger (`list()` over `tasks/**`), as Shift Manager does; a Workforce index of where each task runs | The list loads every row of every conversation per send (BP-033); a Workforce copy of `run.sessionId` can go stale on a retry. The ledger's own index holds only id → partition, written by the one add every filing passes, so it never goes stale ([D1](DECISIONS.md#d1)) | +| `requestHost.sessions.read(id)` | The dispatch seam's guards; the store's `session.get` reached only by hosts (`devteam/host.mts`) | The guards refuse but never return the record, and a block can't reach the store. The read is the guards' rule, exposed ([D2](DECISIONS.md#d2)) | +| `harnessTalkTurn` | `harnessSessionDoor` | **Extracted** from it, not a second talk path | + +| The debt | | +|---|---| +| **Removes** | Nothing beyond FIX-2238 | +| **Adds** | The ledger's id index: one key per task, growing with the ledger it indexes and never moving, since a row never changes partition. Permanent by design. An eighth request-host verb, `sessions.read`: permanent by design, the generic read a later session lookup tool also needs; its header's "neither is a session id" line is amended with the dispatch `{ id }` target as precedent | +| **Leaves** | A worker learns a session id only when pasted (rule 21's lookup comes later) | + +**Net: up a little.** Two targets earn their place on the one tool; the ledger gains a lookup it +lacked, with no second record of where a task runs; the read widens a closed engine seam by one +reviewed verb. + +## Sign off + +**[The goal](#the-goal-and-how-well-know-its-met), at that size:** any task or own conversation +of the user's, by id, checked before the row, and the coder answering a finished task. If wrong: +the epic wraps with `{ task }` reaching only a sender's own board. + +**[The debt](#whats-already-here-and-the-debt): up a little.** Adds a ledger lookup by id and one +engine verb. If wrong: the engine verb becomes a session reader capabilities lean on for more than checks. + +1. **[D1](DECISIONS.md#d1) · The task ledger finds a row by id across conversations; the send reads its run link.** + If wrong: an orchestration index nobody else uses. +2. **[D2](DECISIONS.md#d2) · The server checks a `{ session }` with one new request-host read.** + The one to weigh: it widens a seam its header calls closed. If wrong: a session reader any + capability can call. +3. **[D3](DECISIONS.md#d3) · A message to the coder's open task is refused `task_running`.** If + wrong: workers can't ask a running coder anything by message. + +**Open: none.** Engineering calls: [DECISIONS.md → Decided, not asked](DECISIONS.md#decided-not-asked). + +Feature · `core`, `engine`, `orchestration`, `workforce`, `harness-manager`, `shift-manager` + docs · medium (two targets, a ledger lookup by id, one engine read, the coder's talk turn; one goal amended) · 1 PR, stacked on FIX-2238 · epic FIX-2070 diff --git a/specs/issues/FIX-2160/figures/d1-task-index.svg b/specs/issues/FIX-2160/figures/d1-task-index.svg new file mode 100644 index 0000000000..7a0369d409 --- /dev/null +++ b/specs/issues/FIX-2160/figures/d1-task-index.svg @@ -0,0 +1,85 @@ + + + + + D1 · THE CALL + How does { task: id } find the session working the task? + + CHOSEN + The ledger finds the row by id + + INSTEAD OF + List every task row the user has + + + ONE SEND'S COST + ▸ DECIDES IT + + + One read, by the task id + then the run link on the row + − + Every row of every conversation + loaded and dropped on each send + + WHAT IT ADDS + − + An id index in the ledger + one key per task, never moves + + + Nothing stored + the run link is already on the row + + A TASK NOT + STARTED YET + = + Refused, no_task_session + before anything is written + = + The same + no run link, no session + + + LOCKS IN + A lookup by id on a partitioned ledger + refusal no_task_session + + FLIPS IF + Task ids become unique per user at filing + then the index is the ledger's own key + diff --git a/specs/issues/FIX-2160/figures/d2-session-read.svg b/specs/issues/FIX-2160/figures/d2-session-read.svg new file mode 100644 index 0000000000..879b03d8ae --- /dev/null +++ b/specs/issues/FIX-2160/figures/d2-session-read.svg @@ -0,0 +1,86 @@ + + + + + D2 · THE CALL + How does the server check a { session } before anything is written? + + CHOSEN + A request-host read of the user's session + + INSTEAD OF + The recipient's entry checks itself + + + WHEN A BAD TARGET + IS REFUSED + ▸ DECIDES IT + + + At the send, before the row + pays nothing, as epic ER-3 says + − + After the row and the dispatch + a refused row the sender can't hear + + THE ENGINE SEAM + − + An eighth request-host verb + a reviewed widening of a closed seam + + + No change to the seam + the dispatch guards stay the reader + + WHOSE SESSION + IT CAN READ + = + The running user's, this tenant + the dispatch guards' own rule + = + The same + the dispatch guards decide + + + LOCKS IN + requestHost.sessions.read(id) + flow, org and state, or nothing + + FLIPS IF + A session lookup tool is built (rule 21) + then the read is that tool's server half + diff --git a/specs/issues/FIX-2160/figures/d3-coder-open-task.svg b/specs/issues/FIX-2160/figures/d3-coder-open-task.svg new file mode 100644 index 0000000000..88ad229d83 --- /dev/null +++ b/specs/issues/FIX-2160/figures/d3-coder-open-task.svg @@ -0,0 +1,86 @@ + + + + + D3 · THE CALL + What does the coder do with a message to a task that is still open? + + CHOSEN + Refuse it before the row, task_running + + INSTEAD OF + Resume the coding session between runs + + + WHAT THE NEXT + ATTEMPT RESUMES + ▸ DECIDES IT + + + Its brief and its steers only + a message never changes the work + − + The talk, in the same session + a message acts as a quiet steer + + ASKING ABOUT + RUNNING WORK + − + Not by message + getTask, or wait for the ending + + + Answered after the run + the checkout lease queues it + + A FINISHED TASK + = + The coding session answers + harnessTalkTurn, the door's path + = + The same + harnessTalkTurn + + + LOCKS IN + task_running, at the send, before the row + for a worker that hears task-sessions only + + FLIPS IF + A lab asks a running coder what it is doing + then a read-only status turn, not a resume +