Skip to content

Commit ac9031f

Browse files
brentkellybrentkellyclaude
authored
fix(board): human-in-the-loop steps auto-advance; messaging an agent no longer flips human-in-the-loop (pingdotgg#200)
* fix(board): a queued run steered in or deleted no longer reads as a human Stop Co-Authored-By: Claude Opus 5.5 <[email protected]> * fix(board): human-in-the-loop steps auto-advance; Stop no longer flips human-in-the-loop A succeeded human-in-the-loop step now honours its stage's autoAdvance like an unattended one, and a human Stop pauses the step without touching the card's human-in-the-loop stance. Co-Authored-By: Claude Opus 5.5 <[email protected]> * docs(board): Stop pauses only and human-in-the-loop no longer blocks auto-advance Co-Authored-By: Claude Opus 5.5 <[email protected]> * test(board): a drag-back re-entry conversation auto-advances on completion Pins the behaviour removing the human-in-the-loop guard gave re-entry conversations, documents it, and names the queued-run memory in the signal reader's warm-up limit. Co-Authored-By: Claude Opus 5.5 <[email protected]> * fix(board): a queued run that fails to start still reads as turn-start-failed Co-Authored-By: Claude Opus 5.5 <[email protected]> * docs(board): toRole comment no longer limits autoAdvance to unattended runs Co-Authored-By: Claude Opus 5.5 <[email protected]> --------- Co-authored-by: brentkelly <[email protected]> Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent 35087a3 commit ac9031f

14 files changed

Lines changed: 422 additions & 94 deletions

‎apps/server/src/board/ThreadGatewayV2.test.ts‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -278,6 +278,48 @@ describe("makeSignalReader", () => {
278278
);
279279
});
280280

281+
it("reads a queued run steered in, deleted or archived away as neither a Stop nor a turn end", () => {
282+
// Promote-to-steer, a queue delete and an archive all cancel the queued run
283+
// under the human's own command id, never started — the shape a start-up
284+
// Stop has. Seeing it queued first is what tells them apart (T3O-76).
285+
for (const created of ["run.created", "run.updated"]) {
286+
const read = makeSignalReader();
287+
read(stored(created, run("queued", null, { queuePosition: 1 }), CLIENT_COMMAND_ID));
288+
assert.deepStrictEqual(
289+
read(
290+
stored("run.updated", run("cancelled", null, { queuePosition: null }), CLIENT_COMMAND_ID),
291+
),
292+
[],
293+
created,
294+
);
295+
}
296+
});
297+
298+
it("still reads a queued run that failed to start as a turn that never began", () => {
299+
// v2's failQueuedRunStart takes a queued run straight to failed when it
300+
// cannot start; the board must still hear it, or the step holds its slot.
301+
const read = makeSignalReader();
302+
read(stored("run.created", run("queued", null, { queuePosition: 1 }), CLIENT_COMMAND_ID));
303+
assert.deepStrictEqual(
304+
read(stored("run.updated", run("failed", null, { queuePosition: null }))).map(
305+
(signal) => signal.type,
306+
),
307+
["turn-start-failed"],
308+
);
309+
});
310+
311+
it("still reads a human's Stop on a run that left the queue and was starting", () => {
312+
const read = makeSignalReader();
313+
read(stored("run.created", run("queued", null, { queuePosition: 1 }), CLIENT_COMMAND_ID));
314+
assert.deepStrictEqual(read(stored("run.updated", run("starting", null))), []);
315+
assert.deepStrictEqual(
316+
read(stored("run.updated", run("interrupted", null), CLIENT_COMMAND_ID)).map(
317+
(signal) => signal.type,
318+
),
319+
["interrupt-requested", "turn-ended"],
320+
);
321+
});
322+
281323
it("does not repeat a Stop the engine already recorded as an interrupt request", () => {
282324
const read = makeSignalReader();
283325
const item = {

‎apps/server/src/board/ThreadGatewayV2.ts‎

Lines changed: 33 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -263,6 +263,27 @@ export const makeSignalReader = () => {
263263
string,
264264
{ readonly run: OrchestrationV2Run; readonly commandId: CommandId | null }
265265
>();
266+
// Runs whose latest status was `queued` (T3O-76). v2 cancels a queued run
267+
// straight out of the queue when a human promotes its message to a steer,
268+
// deletes it from the queue, or archives the thread, under that human's
269+
// command id and with `startedAt` null — the same shape as a Stop during
270+
// start-up. Nothing in the cancelled payload tells them apart (`queuePosition`
271+
// is null either way, and a queued run already owns its root node and
272+
// attempt), so the reader remembers the one fact that does: the status it
273+
// last saw. A run with no remembered status keeps the Stop reading.
274+
const queuedRuns = new Set<string>();
275+
const noteRunStatus = (run: OrchestrationV2Run): boolean => {
276+
const key = String(run.id);
277+
const wasQueued = queuedRuns.delete(key);
278+
if (run.status === "queued") {
279+
queuedRuns.add(key);
280+
if (queuedRuns.size > SEEN_LIMIT) {
281+
const oldest = queuedRuns.values().next().value;
282+
if (oldest !== undefined) queuedRuns.delete(oldest);
283+
}
284+
}
285+
return wasQueued;
286+
};
266287

267288
return (stored: OrchestrationV2StoredEvent): ReadonlyArray<ThreadSignal> => {
268289
const event = stored.event;
@@ -275,6 +296,7 @@ export const makeSignalReader = () => {
275296
// the run's message decides the rest; v2 commits that message right
276297
// after the run, in the same command, so the run waits for it.
277298
const run = event.payload;
299+
noteRunStatus(run);
278300
if (isBoardMintedCommandId(stored.commandId)) {
279301
return [
280302
{
@@ -313,8 +335,15 @@ export const makeSignalReader = () => {
313335
}
314336
case "run.updated": {
315337
const run = event.payload;
338+
const wasQueued = noteRunStatus(run);
316339
const outcome = turnOutcomeOf(run.status);
317340
if (outcome === null || !firstTime(`run:${run.id}`)) return [];
341+
// A run cancelled without ever leaving the queue was never a turn: its
342+
// message was steered into the live turn, deleted, or dropped with the
343+
// thread. It is neither a Stop nor an ending the board should read. A
344+
// queued run that FAILED to start (v2's failQueuedRunStart) still is a
345+
// turn that never began, and reads as one below.
346+
if (wasQueued && run.status === "cancelled") return [];
318347
// A run that failed without ever starting is a turn that never began
319348
// (t3o-30, D2) — workspace preparation, or the provider refusing it.
320349
if (outcome === "failed" && run.startedAt === null) {
@@ -433,7 +462,10 @@ export const followStoredEvents = (
433462
/** How far before a resume cursor `readSignalLog` starts reading, so the reader
434463
holds most of the memory it would have had at the cursor. A bounded best
435464
effort: a live reader remembers a run until its message says who wrote it,
436-
so a resume whose run started further back than this loses that memory. */
465+
and which runs are still queued (`queuedRuns`), so a resume whose run
466+
started further back than this loses that memory. A queued run forgotten
467+
that way and later cancelled out of the queue falls back to the Stop
468+
reading, and pauses its card. */
437469
export const SIGNAL_READER_WARMUP_EVENTS = 4096;
438470

439471
/**

‎apps/server/src/board/decider.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4212,8 +4212,8 @@ export const decideBoardCommand = Effect.fn("decideBoardCommand")(function* ({
42124212
yield* requireActiveBoardCard({ board, command });
42134213
const current = yield* requireLiveStepState({ board, command, stepId: command.stepId });
42144214
// Slot, worktree and thread are untouched (D5) — only the frozen
4215-
// human-in-the-loop stance changes, so drop-monitoring and auto-advance
4216-
// honour the new value.
4215+
// human-in-the-loop stance changes, so drop-monitoring honours the new
4216+
// value.
42174217
const state: BoardCardStepState = {
42184218
...current,
42194219
humanInLoop: command.humanInLoop,
Lines changed: 226 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,226 @@
1+
/**
2+
* T3O-76 — human-in-the-loop is the human's toggle and nothing else's.
3+
*
4+
* Two bugs, one rule. A human-in-the-loop step that reached
5+
* `board_complete_step` sat in its stage forever, because `advanceStage`
6+
* skipped every human-in-the-loop run; it now honours the stage's
7+
* `autoAdvance` exactly as an unattended run does. And a human messaging a
8+
* running board agent flipped the card to human-in-the-loop and paused it:
9+
* the queued message they steered in read as a Stop at the gateway, and a Stop
10+
* flipped the card. Both halves are covered here through the live reactor.
11+
*/
12+
import {
13+
BOARD_SEED_STAGE_IDS,
14+
BoardCardId,
15+
boardCardStepState,
16+
CommandId,
17+
EventId,
18+
MessageId,
19+
RunId,
20+
type BoardState,
21+
type OrchestrationV2StoredEvent,
22+
type ThreadId,
23+
} from "@t3tools/contracts";
24+
import { assert, it } from "@effect/vitest";
25+
import * as DateTime from "effect/DateTime";
26+
import * as Effect from "effect/Effect";
27+
28+
import { makeSignalReader } from "./ThreadGatewayV2.ts";
29+
import {
30+
buildingCard,
31+
cardMoved,
32+
cardStage,
33+
codexStep,
34+
makeBoardCard,
35+
movedToBuilding,
36+
settingsWith,
37+
stepCompleted,
38+
stepStatus,
39+
withGovernor,
40+
} from "./supervisorHarness.testkit.ts";
41+
42+
const cardHumanInLoop = (board: BoardState, id: BoardCardId) =>
43+
board.cards.find((candidate) => candidate.id === id)?.humanInLoop;
44+
45+
// ── Bug 1: a finished human-in-the-loop step advances ─────────────────────
46+
47+
it.effect("a human-in-the-loop build that completes moves on to Code review", () =>
48+
withGovernor(
49+
{
50+
board: { cards: [buildingCard("hitl", "m", true)], nextCardNumberByProject: {} },
51+
settings: settingsWith({ building: [codexStep], globalMaxConcurrent: 3 }),
52+
},
53+
({ pumpDomain, board }) =>
54+
Effect.gen(function* () {
55+
const id = BoardCardId.make("hitl");
56+
yield* pumpDomain(movedToBuilding(buildingCard("hitl", "m", true), 1));
57+
assert.isTrue(boardCardStepState(yield* board, id)?.humanInLoop);
58+
59+
yield* pumpDomain(stepCompleted(id, "succeeded", 2));
60+
61+
assert.strictEqual(cardStage(yield* board, id), BOARD_SEED_STAGE_IDS.review);
62+
}),
63+
),
64+
);
65+
66+
it.effect("a human-in-the-loop build stays put when Building's auto-advance is off", () =>
67+
withGovernor(
68+
{
69+
board: { cards: [buildingCard("held", "m", true)], nextCardNumberByProject: {} },
70+
settings: settingsWith({
71+
building: [codexStep],
72+
globalMaxConcurrent: 3,
73+
buildAutoAdvance: false,
74+
}),
75+
},
76+
({ pumpDomain, board }) =>
77+
Effect.gen(function* () {
78+
const id = BoardCardId.make("held");
79+
yield* pumpDomain(movedToBuilding(buildingCard("held", "m", true), 1));
80+
yield* pumpDomain(stepCompleted(id, "succeeded", 2));
81+
82+
const after = yield* board;
83+
assert.strictEqual(stepStatus(after, id), "succeeded");
84+
assert.strictEqual(cardStage(after, id), BOARD_SEED_STAGE_IDS.building);
85+
}),
86+
),
87+
);
88+
89+
// A drag-back re-entry conversation (D7) is always human-in-the-loop with no
90+
// prompt. It finishes the stage exactly as any other step does: a human who
91+
// talked the work through to `board_complete_step` wants the card moved on, and
92+
// a stage that should hold for them ships with `autoAdvance` off.
93+
it.effect("a drag-back re-entry conversation that completes moves on like any other step", () => {
94+
const card = buildingCard("again", "m");
95+
const priorBuild = {
96+
cardId: card.id,
97+
stepId: String(BOARD_SEED_STAGE_IDS.building),
98+
outcome: "succeeded" as const,
99+
summary: "built it",
100+
payload: null,
101+
threadId: null,
102+
completedAt: "2026-01-01T00:00:00.000Z",
103+
};
104+
return withGovernor(
105+
{
106+
board: { cards: [card], stepCompletions: [priorBuild], nextCardNumberByProject: {} },
107+
settings: settingsWith({ building: [codexStep], globalMaxConcurrent: 3 }),
108+
},
109+
({ pumpDomain, board }) =>
110+
Effect.gen(function* () {
111+
yield* pumpDomain(cardMoved(card, "review", "building", 1));
112+
const reentry = boardCardStepState(yield* board, card.id);
113+
assert.isTrue(reentry?.humanInLoop);
114+
assert.strictEqual(reentry?.prompt, "");
115+
assert.strictEqual(cardStage(yield* board, card.id), BOARD_SEED_STAGE_IDS.building);
116+
117+
yield* pumpDomain(stepCompleted(card.id, "succeeded", 2));
118+
assert.strictEqual(cardStage(yield* board, card.id), BOARD_SEED_STAGE_IDS.review);
119+
}),
120+
);
121+
});
122+
123+
const planningCard = () => makeBoardCard({ id: "plan", stage: "planning", orderKey: "m" });
124+
125+
const completePlanning = (planningAutoAdvance: boolean, expectedStage: string) =>
126+
withGovernor(
127+
{
128+
board: { cards: [planningCard()], nextCardNumberByProject: {} },
129+
settings: settingsWith({
130+
building: [codexStep],
131+
planning: codexStep,
132+
planningHumanInLoop: true,
133+
planningAutoAdvance,
134+
globalMaxConcurrent: 3,
135+
}),
136+
},
137+
({ pumpDomain, board }) =>
138+
Effect.gen(function* () {
139+
const id = BoardCardId.make("plan");
140+
yield* pumpDomain(cardMoved(planningCard(), "sprint", "planning", 1));
141+
assert.isTrue(boardCardStepState(yield* board, id)?.humanInLoop);
142+
143+
yield* pumpDomain(stepCompleted(id, "succeeded", 2, String(BOARD_SEED_STAGE_IDS.planning)));
144+
assert.strictEqual(cardStage(yield* board, id), expectedStage);
145+
}),
146+
);
147+
148+
it.effect("a human-in-the-loop planning step advances when Planning opts into it", () =>
149+
completePlanning(true, BOARD_SEED_STAGE_IDS.ready),
150+
);
151+
152+
it.effect("a human-in-the-loop planning step waits for a human by default", () =>
153+
completePlanning(false, BOARD_SEED_STAGE_IDS.planning),
154+
);
155+
156+
// ── Bug 2: messaging a running agent changes nothing on the card ──────────
157+
158+
const CLIENT_COMMAND_ID = "8c7f0f0e-6d2b-4a5e-9a1d-0f2b3c4d5e6f";
159+
const t0 = DateTime.makeUnsafe("2026-10-20T00:00:00.000Z");
160+
let sequence = 0;
161+
const stored = (
162+
threadId: ThreadId,
163+
type: string,
164+
payload: object,
165+
commandId: string | null,
166+
): OrchestrationV2StoredEvent =>
167+
({
168+
sequence: (sequence += 1),
169+
commandId: commandId === null ? null : CommandId.make(commandId),
170+
event: { type, id: EventId.make(`evt-${sequence}`), threadId, occurredAt: t0, payload },
171+
}) as unknown as OrchestrationV2StoredEvent;
172+
173+
/** What v2 records when a human types into a busy thread and then promotes the
174+
queued message to a steer (or deletes it): the queued run and its message,
175+
then that run cancelled straight out of the queue under the human's command. */
176+
const queuedThenSteered = (threadId: ThreadId) => {
177+
const messageId = MessageId.make("message-queued");
178+
const run = (status: string, queuePosition: number | null) => ({
179+
id: RunId.make("run-queued"),
180+
threadId,
181+
status,
182+
queuePosition,
183+
userMessageId: messageId,
184+
requestedAt: t0,
185+
startedAt: null,
186+
});
187+
return [
188+
stored(threadId, "run.created", run("queued", 1), CLIENT_COMMAND_ID),
189+
stored(
190+
threadId,
191+
"message.updated",
192+
{ id: messageId, role: "user", createdBy: "user", creationSource: "web" },
193+
CLIENT_COMMAND_ID,
194+
),
195+
stored(threadId, "run.updated", run("cancelled", null), "a1b2c3d4-0000-4000-8000-000000000000"),
196+
];
197+
};
198+
199+
it.effect("a message steered into a running unattended build leaves the card as it was", () =>
200+
withGovernor(
201+
{
202+
board: { cards: [buildingCard("steered", "m")], nextCardNumberByProject: {} },
203+
settings: settingsWith({ building: [codexStep], globalMaxConcurrent: 3 }),
204+
},
205+
({ pumpDomain, board }) =>
206+
Effect.gen(function* () {
207+
const id = BoardCardId.make("steered");
208+
yield* pumpDomain(movedToBuilding(buildingCard("steered", "m"), 1));
209+
const running = boardCardStepState(yield* board, id);
210+
assert.strictEqual(running?.status, "running");
211+
assert.isFalse(running?.humanInLoop);
212+
213+
// Through the real signal reader, so this covers the gateway's reading
214+
// of the cancelled queued run as well as the reactor's handling of it.
215+
const read = makeSignalReader();
216+
for (const event of queuedThenSteered(running!.threadId!)) {
217+
for (const signal of read(event)) yield* pumpDomain(signal);
218+
}
219+
220+
const after = yield* board;
221+
assert.strictEqual(stepStatus(after, id), "running");
222+
assert.isNull(cardHumanInLoop(after, id));
223+
assert.isFalse(boardCardStepState(after, id)?.humanInLoop);
224+
}),
225+
),
226+
);

0 commit comments

Comments
 (0)