Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
96 changes: 96 additions & 0 deletions specs/issues/FIX-2241/DECISIONS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
# FIX-2241 · Decisions

[Spec](SPEC.md) · **Decisions**

The epic decided the model ([FIX-2070](../../epics/FIX-2070/DECISIONS.md)): the question goes as a
message from the task's session to the filer's `onMessageReceived`, through `sendMessage`'s server
path and never the model tool; the hold stays the record and the Inbox the answer's home (seam
table, PR-3); the server's question is exempt from the budget (ER-6); it lands in the session that
filed the task (ER-2). The answer itself is FIX-2133's (ER-4). What is left is engineering, so
this spec carries no decision card.

## Decided, not asked

- **The convergence point is `askMidway`.** Every midway ask, `askQuestion` and `harness-manager`'s
coding-run ask alike, goes through it and then through the collection's one `ask` write; after
the ask it calls the ledger's declared `questionAsked(ctx, row, holds)`. A test pins both callers. Orchestration names no message (Layer 1 boundary).
- **Once, a replay included.** The message is built from the row, not from the ask's return: after
Comment thread
jhoffner marked this conversation as resolved.
Resolved
the ask, `askMidway` reads the committed row's open midway holds and calls the hook with those (while one
is open no other turn runs the task, so they are the ones this turn asked). Their ids are stored on the row, so a durable turn that crashed after
the hold write and replays (its ask now declined, the lease gone) finds the same holds and sends
the same ids. A question answered before the replay is closed and needs no message, and a later
turn's open question picked up by the replay is one that turn tells anyway, so the id dedupes it.
The message id is derived from the task and the hold (for example
`q:<taskId>:<holdId>`), and the receiver's dedupe drops any repeat. After the message row,
FIX-2240's delivery takes over. On a host without durable execution a crash before the row loses
the message, as the epic's D2 leaves every send; the Inbox item stands.
- **One message per hold**, so each names the one question id the filer answers.
- **Who is told.** The row's filer session (`Task.filer`), whatever its result setting
(`resultTo: "conversation"` included: the question is the filer's to hear, the ending the
conversation's). A task filed by a screen or a schedule (no filer session) and a board without
the hook send nothing. Plan steps are never held (`plan.ts`), so no plan row asks. A filer
session that is gone refuses the send; the refusal is logged and the Inbox item stands.
- **A filer waiting on the task hears it at once.** A wait is a suspension on the engine's wait
gate, and a suspended request gives its place back (epic ER-4: only a person's suspension holds
admission), so the filer's `onMessageReceived` runs beside its parked wait. Its steer lets the
task go on, and the wait then resumes with the result. No change to a wait's outcomes.
- **Sender, server-set.** `from` is the row's assignee and the sending session is the task's,
both read from the row, never from input (BP-031). `call` is false: the task never waits on the
Comment thread
jhoffner marked this conversation as resolved.
Resolved
answer through the message.
- **Budget.** The send skips every budget check and pays nothing (epic ER-6): the chain's 6, the
per-request 3 and the hop reservation, so an ask with several holds is never refused; the filer's
`onMessageReceived` is told the budget the task's chain has left, so its own sends count there.
- **Routed tasks are told too** (concept rule 11: "also messaged to the filer"), with text that
says the user answers it from the Inbox. The text is the server's, built from the row; a confirm
says to answer with `done`.
- **No new field on `onMessageReceived`'s input.** The task id and question id ride the text the
model reads; epic ER-1's input stays as FIX-2238 ships it.
- **Answered, cancelled or past its deadline before the filer's turn**: the turn's `updateTask`
is refused as today (`question_answered`, finished); nothing is recalled.

## Considered and dropped

- **A filer waiting on the task hears it only once its wait ends** (the first draft's D1). Its
premise, that a message queues behind a waiting request, was wrong: a wait gives its place back.

- **Bring back the park's notice** (removed by FIX-2131 in `043be81`): a question marker on the
row, paid by the notice's wake. Durable from the hold's own write, but it lands on
`onTaskSettled`, the entry for endings, and the epic chose a message. It would also make a
question count as an owed notice in the filer's done check.
- **Send from the `askQuestion` tool.** Misses the coding run's question (the smaller goal).
- **Structured `about: { task, question }` on the received message.** Changes ER-1's input for one
sender; the text carries the ids the model needs.

## Open

None.

## Settled

No POC: every premise is a read of `main` (the two `askMidway` callers and the collection's `ask`,
whose hold ids are minted before its write; `DeclaredDelivery` filled by `conversationDelivery`;
`answerQuestion`'s routed refusal; a wait gate as a suspension, `resume-wait-gate.ts`).

## Notes for the implementer

- **Order.** The exempt send edits FIX-2238's send path, which FIX-2160, FIX-2240 and FIX-2239 stack
on. This lands after FIX-2238, stacked on its PR while that is open, and rebases on whichever of
the others merged first; it touches only the send's budget check.
- **Renames.** `DeclaredDelivery.questionAsked` and the server-written text that teaches
`updateTask({ id, question, message })` are in FIX-2183's scope (#3985 hands it the meanings of
*hold* and `updateTask`'s `question`), so its codemod changes the name and the text together.
- `DeclaredDelivery`'s doc says `questionAsked` is not the notice pipeline (no marker, no
`noticeEntry`): same declaration, a different moment. Whether the hook takes the holds or reads
them from the row is the implementer's call.
- `answerQuestion` checks the caller reaches the row, not that it is the filing session; nothing
here relies on that.

## How it got here

- 2026-10-27, initial draft, on `main` after FIX-2238's spec merged (#3986). The research found
that FIX-2131 removed a park's question notice a day earlier, so today no midway question
reaches a filer, and that `askMidway` is the one point both ask paths share.
- Same day, an independent review against `main`, folded: D1 dropped (a wait gives its place
back, so a waiting filer hears at once); "once" rebuilt on the row's stored holds, since a
replay's ask is declined; who is told with `resultTo: "conversation"` and a gone session; plan
steps never ask; the goal's Lab gains a workstream and a model-filed coding task.
149 changes: 149 additions & 0 deletions specs/issues/FIX-2241/SPEC.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,149 @@
# FIX-2241 · A task's midway question reaches its filer as a message

**Spec** · [Decisions](DECISIONS.md)

## Five people, before and after

| Someone who… | Today | After |
|---|---|---|
| **files work for a worker**, a worker's model | Hears nothing when its task asks a question midway. It finds out only if it happens to read the row with `getTask` | Hears it on `onMessageReceived`, in the session that filed the task, as a message from the task's worker naming the task and the question. It may answer it with `updateTask({ id, question, message })` or leave it to the user |
| **filed a task that was routed to a workstream** | Hears nothing | Hears it the same way, told that the user answers it from the Inbox. Its own answer is still refused `question_is_the_users` |
| **filed a coding task** | Hears nothing when the coding run's question ends the run | Hears it the same way: the coding run's question is a midway question too |
| **is the user** | Sees one Inbox item for the question | Sees the same one item. The filer's answer, if it comes first, closes it; the message is never a second item (PR-3) |
| **runs a ring of workers that is out of budget** | n/a | The question still reaches the filer: the server's question costs no budget (epic ER-6) |

The answer half is already on `main` (FIX-2133 ER-4, FIX-2131): a filer may answer its task's
midway question by a steer, unless the task is routed. Until yesterday a park's question reached
the filer as a task notice; FIX-2131 retired the park and left the telling to this issue.

## The goal, and how we'll know it's met

**When a task a worker filed asks a question midway, by its model or by its coding run, the filer
hears it on `onMessageReceived` in the session that filed the task, once, at no cost to the budget,
and can answer it there with a steer that lets the task go on, while the user's one Inbox item
stays the only stop.**

| Is it the right goal? | |
|---|---|
| **The real need** | The issue: "a question a task asks midway reaches its filer as a message from the task's session … The filer may answer it with a steer unless the task is routed, or leave it to the user." Concept rule 11 and the epic's leg e: "the midway question arrives at the filer's `onMessageReceived` in the session that filed the task; its steer releases the hold" ([epic SPEC](../../epics/FIX-2070/SPEC.md)) |
| **Smaller, and rejected** | "The `askQuestion` tool sends a message." A coding run's question (`harness-manager`'s ask step) would stay silent, and a filer would hear only the questions one tool asks |
| **Bigger, and not this issue's** | Delivery that survives a crash after the message row (FIX-2240) |
| **Not done if** | A coding run's question doesn't reach the filer · the filer's model has to call `getTask` to learn the question or its id · a question is told twice, a durable replay included · the question spends budget, or is refused at a spent one · a routed task's filer is told it may answer · the message opens a second Inbox item · a crash and a replay of the asking turn loses or doubles the message · the filer's answer doesn't let the task go on, on the same attempt |

```mermaid
flowchart LR
A["Shift Manager desk Lab · real model · file-backed host"] --> J["leg j1 · desk.front files for desk.asker, told the answer up front"]
J --> Q["the asker's task asks midway"]
Q -->|"a received item in desk.front's conversation · its own turn steers"| P["PASS · completed, attempt 1, no user line between"]
A --> K["leg j1b · the coder's run asks"]
K -->|"a received item in the filing session"| P
C["control · no-question-message"] -.-> Q
Q -.->|"under the control"| F["must FAIL · j1:filer-hears"]
```

The check reads desk.front's stored conversation items and the task row, as Alice, through her clients.

| How we verify | |
|---|---|
| **Goal check** | `goals/shift-manager/every-stop-is-one-inbox-item/`, leg j1 amended in place (FIX-2058's ground, as the epic says). Real model, run by the implementer at completion; PASS is j1 green in 3 of 3 runs; verdict in the implementation PR. Model-free: `packages/workforce` and `packages/harness-manager` CI tests for both ask paths, the once, the budget and the routed text |
Comment thread
jhoffner marked this conversation as resolved.
Resolved
| **Signal** | `j1:filer-hears` desk.front's conversation gains exactly one received-message item from `desk.asker` whose text names the task's id and the question's id, and an `onMessageReceived` request runs there. `j1:filer-answers-own` (kept, stronger) that request's `updateTask` steer carries the question's id, `from: "filer"`, and the task ends `completed` on attempt 1 with no line from Alice after the filing. `j1:routed-told` a routed task's filer receives the question with the Inbox wording, and its `updateTask` is refused `question_is_the_users`. `j1b:coder-heard` eng.coder's coding question reaches its filer's session as one received item. `j1:one-item` the Inbox lists one item per question throughout |
| **Input** | Alice files with desk.front: "File one task for desk.asker… If it asks you anything about tone, the answer is: formal." The words are picked at run time (`pickWords`); any question and answer pass the same way. The Lab gains what j1 needs: a workstream desk.front routes to (for `j1:routed-told`), and desk.front's model filing eng.coder's task (today's coder legs file from a screen, with no filer session) |
| **Anti-game** | Today's j1 has Alice tell desk.front the question exists; that line goes. Receipt is read from stored items, the answer from the row's steers; nothing seeded |
| **Control that must fail** | Today's `main`: `j1:filer-hears` (nothing is sent). `GOAL_CONTROL=no-question-message` (the hook not called) fails `j1:filer-hears`. `ask-tool-only` (only `askQuestion` sends) fails `j1b:coder-heard`. `question-pays` (the send charged to the budget) fails the CI test of a spent chain. The PR shows each FAIL before the PASS |

## What changes

```mermaid
flowchart LR
subgraph today ["Today"]
T1["askQuestion · coding run's ask"] --> T2["askMidway · hold on the row"]
T2 --> T3["Inbox item"]
T2 -.->|"nothing"| T4["filer"]
end
subgraph after ["After"]
A1["askQuestion · coding run's ask"] --> A2["askMidway · hold on the row"]
A2 --> A3["Inbox item · still the one stop"]
A2 -->|"the board's declared hook · once per hold"| A4["sendMessage's server path · exempt from budget"]
A4 --> A5["filer's onMessageReceived · in the filing session"]
end
```

`askMidway` is the one write every midway ask passes through; after it, the board's declared
Comment thread
jhoffner marked this conversation as resolved.
Resolved
delivery tells the filer, and a Workforce board declares it as a message. The hook is called with the
open midway holds read from the committed row, also when a durable replay's ask comes back
declined, so a crash after the hold write still tells the filer.

Nothing a person types changes. The surface is the board's delivery declaration, which Workforce
already fills for its endings:

```diff
// workforce/src/conversation-board/delivery.ts
export function conversationDelivery(ledgerId: string): DeclaredDelivery {
return {
passEntry: DISPATCH_ENTRY,
noticeEntry: () => TASK_SETTLED_ENTRY,
...
+ // a midway question, told to the filer through sendMessage's server path
+ questionAsked: (ctx, row, holds) => sendQuestionToFiler(ctx, row, holds),
Comment thread
jhoffner marked this conversation as resolved.
Resolved
};
}
```

What the filer's model reads (the received item's text, server-written):

```text
Your task "Write the gala greeting" (t7) asks: "Formal or casual?"
Answer it with updateTask({ id: "t7", question: "h1", message }), or leave it to the user, who sees it in their Inbox.
```

**Docs:** update `apps/docs/docs/workforce/messaging-workers.md` (a task's question arrives as a
message; answer with `updateTask`, not a reply) and `apps/docs/docs/orchestration/task-board.md` →
the midway ask (a board's `questionAsked` delivery; without one the filer reads it with `getTask`);
`packages/workforce/README.md` and `packages/orchestration/README.md`. A changeset for
`@flow-state-dev/orchestration` (`DeclaredDelivery.questionAsked`) and `@flow-state-dev/workforce`.

## What stays as it is

- **The hold is the record** (FIX-2133). `getTask` and `listTasks` show the open question; the
Inbox item is read from it, and the first answer, from the user or the filer, closes it.
- **Who may answer** (FIX-2133 ER-4): the filer, only a midway question, only on a task not routed.
- **A message never steers.** Replying with `sendMessage` and `inReplyTo` talks in the task's
session; it answers nothing.
- **A board without the hook** (an orchestration-only board) tells no one, as today.

## What's already here, and the debt

| Already here | What this does with it |
|---|---|
| Ways to tell a filer about its task, from searches of `packages/*/src` for `recordEnding`, `noticeText`, `sendWorkerMessage`, `onTaskSettled` and `askMidway`: the task notice (endings, durable on the row), the message (FIX-2238), and `getTask`. Before FIX-2131 a fourth: a park's notice (`043be81`, `"parked"` ending) | **Builds on** the message, as the epic decided (seam table). Does not bring the park's notice back: a question is not an ending, and the notice path would deliver it on `onTaskSettled` |
| `askMidway` (`orchestration/task-board/task-request.ts`), called by `askQuestion` and `harness-manager`'s ask step | **Extends**: the convergence point; after a successful ask it calls the board's hook once per opened hold |
| `DeclaredDelivery` (`orchestration/tasks/notice/delivery.ts`), the board-declared delivery Workforce fills (`conversationDelivery`) | **Extends** with one optional hook; Layer 1 knows no message (architecture rule) |
Comment thread
jhoffner marked this conversation as resolved.
Resolved
| FIX-2238's send server path and landing rule "a message to the worker that filed your task lands in the session that filed it" | **Builds on**, with `from` and the sending session read from the row, and the budget exemption FIX-2238 left to this issue |
| FIX-2133 ER-4's answer (`answerQuestion`, `question_is_the_users`) and FIX-2058's j1 leg | **Kept**; the leg is amended so the filer hears instead of being told |

| Builds on / Adds | Existing piece considered | Why that doesn't fit, or how this is composed |
|---|---|---|
| `DeclaredDelivery.questionAsked` | `onUndeliverable`, the same declaration's hook | **Extends** the declaration a Workforce board already fills; no second registry |
| `sendQuestionToFiler` | `sendMessage`'s server function | **Composes**: one call with a server-set sender and an exemption flag; no second delivery path |
| A message id per hold | The receiver's dedupe by id | **Reuses** it: the id is derived from the task and the hold, so any repeat lands once |

| The debt | |
|---|---|
| **Removes** | The concept's and docs' "until then the filer reads it with `getTask`" |
| **Adds** | One optional hook on `DeclaredDelivery`; one budget-exempt send, permanent by design (epic ER-6) |
| **Leaves** | On a host without durable execution, a crash between the hold write and the message row loses the message (the Inbox item stands), as the epic's D2 leaves for every send. On a durable host the replay sends it, once |

**Net: flat.** One hook and one send, against a rule the code doesn't keep today.

## Sign off

**[The goal](#the-goal-and-how-well-know-its-met), at that size:** every midway question, the
coding run's included, reaches its filer once, free, and the filer's steer lets the task go on.
If wrong: a filer that could answer leaves the user to.

**[The debt](#whats-already-here-and-the-debt): flat.** Adds one hook and one exempt send. If
wrong: a second way to tell a filer grows beside the notice.

**No decision cards:** the epic decided the model, and FIX-2133 the answer. **Open: none.** The engineering calls: [DECISIONS.md → Decided, not asked](DECISIONS.md#decided-not-asked).

Feature · `orchestration`, `workforce`, `harness-manager` (tests only) + docs · small (one hook, one send, one goal leg) · 1 PR, after FIX-2238's (stacked on it while it is open) · epic FIX-2070
Loading