Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
59 commits
Select commit Hold shift + click to select a range
4eb29cb
refactor(workforce): rename worker messages to sendMessage and onMess…
claude Oct 27, 2026
86f9091
feat(workforce): a received message is its own item, and nothing is r…
claude Oct 27, 2026
f201a3e
FIX-2238: landing rules, task-sessions refusal and one budget
claude Oct 27, 2026
0a814fe
refactor(orchestration): lift the take rule and resend backoff into p…
claude Oct 27, 2026
cdc1107
refactor(orchestration): lift the take rule and resend backoff into p…
claude Oct 27, 2026
874afbf
feat(workforce): a worker message lands once (FIX-2240)
claude Oct 27, 2026
dbd9e84
feat(workforce): a taken message is never ended for its age; sends re…
claude Oct 27, 2026
b1b86b4
feat(shift-manager): a message reads on its way until taken, and coul…
claude Oct 27, 2026
6b3a3bb
docs(workforce): a message lands once: delivery, statuses, the late-f…
claude Oct 27, 2026
393f159
Merge remote-tracking branch 'origin/claude/project-thread-3uc91a' in…
claude Oct 27, 2026
dd932cb
chore(workforce): say user, not person, in the delivery comments (FIX…
claude Oct 27, 2026
9413821
FIX-2238: every worker flow on an installation hears a message
claude Oct 27, 2026
933dc2f
feat(orchestration,engine): a task id finds its partition, and a bloc…
claude Oct 27, 2026
ddd8a9b
feat(harness-manager): harnessTalkTurn, the session door's talk half,…
claude Oct 27, 2026
a30cfd9
feat(workforce): sendMessage takes { task } and { session }, checked …
claude Oct 27, 2026
c8f0c0c
fix(workforce): name a message row's target field addressedBy
claude Oct 27, 2026
ce4902a
docs(workforce): leave FIX-2238's renames to its own PR (FIX-2240)
claude Oct 27, 2026
b42660c
feat(shift-manager): the coder answers a message to its finished task…
claude Oct 27, 2026
1feba42
FIX-2238: docs, changeset, goal amended, epic seams updated
claude Oct 27, 2026
77f3584
Merge FIX-2160 into FIX-2240 for the stack
claude Oct 27, 2026
85da1aa
spec(FIX-2240): record the three seams folded while building
claude Oct 27, 2026
d94227d
feat(orchestration,engine): a task id finds its partition, and a bloc…
claude Oct 27, 2026
aa3852c
feat(harness-manager): harnessTalkTurn, the session door's talk half,…
claude Oct 27, 2026
dfd7fe1
feat(workforce): sendMessage takes { task } and { session }, checked …
claude Oct 27, 2026
c3e3cb6
fix(workforce): name a message row's target field addressedBy
claude Oct 27, 2026
cf5e871
feat(shift-manager): the coder answers a message to its finished task…
claude Oct 27, 2026
ae2bb6b
test(goals): legs 6-8 message a task, a conversation and the coder's …
claude Oct 27, 2026
0979138
test(workforce): a taker that dies after the take is resent and lands…
claude Oct 27, 2026
b03e4fe
Merge main into FIX-2238; review fixes
claude Oct 27, 2026
759d851
docs: message a task or a conversation by id; harnessTalkTurn; the le…
claude Oct 27, 2026
c6d6191
test(goals): leg 6 opens a delegate session for leg 7; goal.md names …
claude Oct 27, 2026
39b85ea
fix: parse id-index markers with their schema; the request host is cl…
claude Oct 27, 2026
0b01f18
Merge FIX-2160 (#4012) into FIX-2240 for the stack
claude Oct 27, 2026
acdd330
FIX-2238: one chain for a task filed held; drop the dead messaged-wor…
claude Oct 27, 2026
b5a893e
Merge FIX-2238's branch (main merged) into FIX-2160
claude Oct 27, 2026
a0149c2
spec(FIX-2160): notes from the cross-spec review, recorded at impleme…
claude Oct 27, 2026
973404f
fix(workforce): a { task } target counts only partitions that hold th…
claude Oct 27, 2026
dd83e61
Merge FIX-2160 (#4012, with main) into FIX-2240
claude Oct 27, 2026
e088b23
chore(workforce): keep undeliveredLine module-private (FIX-2240)
claude Oct 27, 2026
752d290
FIX-2238: a received message's budget is what its chain has left
claude Oct 27, 2026
0961e69
fix(goals): type leg 8's setWorkProject call (FIX-2160)
claude Oct 27, 2026
c748982
Merge FIX-2160 (#4012) into FIX-2240
claude Oct 27, 2026
367eb69
FIX-2238: an answer reaches a worker that hears only in its tasks' se…
claude Oct 27, 2026
5d7ca95
FIX-2238 goal: the ring's own hand-offs aren't stray rows; the herald…
claude Oct 27, 2026
bfbae4c
FIX-2238 goal: 3:budget-left grades what the chain had left when heard
claude Oct 27, 2026
fa37e7d
fix(workforce): record a message delivered only once its items are st…
claude Oct 27, 2026
d19f32a
spec(FIX-2240): record the accepted fast-path loss window
claude Oct 27, 2026
0776b40
refactor(workforce): one close step in the message pass; parse the ow…
claude Oct 27, 2026
67b7ee5
Merge FIX-2238's latest into FIX-2160
claude Oct 27, 2026
18268d2
refactor(workforce): the take answers the row or nothing; one refusal…
claude Oct 27, 2026
00fef9e
Merge FIX-2160 (#4012) into FIX-2240
claude Oct 27, 2026
6b3987d
fix(workforce): a worker's other conversation can answer it (FIX-2160)
claude Oct 27, 2026
594fd76
fix(workforce): a resent answer keeps the send's answering exception …
claude Oct 27, 2026
7b5466b
fix(workforce): a taken message whose destination is gone ends past t…
claude Oct 27, 2026
3aecb45
fix(workforce): a repeat of a refused send answers the refusal (FIX-2…
claude Oct 27, 2026
5efdc4d
fix(workforce): a resend to a task refuses once the task moved sessio…
claude Oct 27, 2026
ac6d701
Merge remote-tracking branch 'origin/claude/project-thread-i68jr1' in…
claude Oct 27, 2026
eec5d61
Merge main (FIX-2238 #4010 and FIX-2160 #4012 landed) into FIX-2240
claude Oct 27, 2026
6123c83
fix(engine): a failed item write rejects the filesystem store's flush…
claude Oct 27, 2026
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
Prev Previous commit
Next Next commit
feat(harness-manager): harnessTalkTurn, the session door's talk half,…
… shared (FIX-2160)

The door's talk runs as a block of its own that a coder can also run for a
message: it resumes a finished task's coding session once and answers
{ reply, taskId }, and refuses a task still open (task-running), since a
message never steers. rowsInSession, in orchestration, is the one reader of
the rows that run in a session.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiD7QxMPGxa4XV4dZEF
  • Loading branch information
claude committed Oct 27, 2026
commit ddd8a9bcfe739fb36b5dcb4f0a372dd52e7cae67
7 changes: 6 additions & 1 deletion packages/harness-manager/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,8 @@
* - {@link harnessManager} and its options, including the `harness` slot.
* - `harnessSessionDoor`, the door a coding flow declares for a line typed
* in a run's session: a steer while its task is open, talk once it has
* finished.
* finished. `harnessTalkTurn` is its talk half, which a coder also runs for
* a message about a finished task.
* - `upgradeKeptTurns`, the upgrade's one-off step that writes a line the
* coding door kept before FIX-2086 onto its task as a steer.
* - `runOwnerDispatcher`, for a board kept per organization: a run belongs to
Expand Down Expand Up @@ -82,10 +83,14 @@ export {
// ── A line typed in a run's session: a steer, or talk once finished ─────────
export {
harnessSessionDoor,
harnessTalkTurn,
harnessTalkInputSchema,
harnessTalkOutputSchema,
sessionDoorInputSchema,
sessionDoorOutputSchema,
SessionDoorRefused,
type HarnessSessionDoorOptions,
type HarnessTalkTurnOptions,
type SessionDoorBoard,
type SessionDoorRefusalReason,
} from "./session-door";
Expand Down
175 changes: 117 additions & 58 deletions packages/harness-manager/src/session-door.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,12 +14,17 @@
*
* A refusal fails the request, so a composer never reads it as delivered;
* the line stays in the session with the refusal after it.
*
* The talk half is {@link harnessTalkTurn}, one block the door runs for a
* finished task and a coder runs for a message about one (FIX-2160): there is
* one talk path. A message never steers, so the turn refuses an open task.
*/
import { defineCapability, handler, sequencer, type DefinedCapability } from "@flow-state-dev/core";
import type { BlockContext, HarnessBlock } from "@flow-state-dev/core/types";
import {
isTerminalStatus,
LINE_STEER_REFUSALS,
rowsInSession,
steerFromLine,
type LineSteerRefusal,
type Task,
Expand All @@ -40,17 +45,25 @@ export const sessionDoorOutputSchema = z.union([
z.object({ reply: z.string().nullable(), taskId: z.string() }),
]);

/** Why the door refused, in stable terms. */
/** What a talk turn takes: the text the coding session is resumed with. */
export const harnessTalkInputSchema = z.object({ message: z.string() });

/** What a talk turn answers: the coding session's reply, and the task it was about. */
export const harnessTalkOutputSchema = z.object({ reply: z.string().nullable(), taskId: z.string() });

/**
* Why the door refused a line. The steer refusals (`steer-limit`, `finished`,
* `not-supported`) read as they do on every door that takes a line.
* `task-running` is a talk turn's alone: a message about a task still open,
* which never steers it.
*/
export type SessionDoorRefusalReason = "not-started" | "cannot-continue" | LineSteerRefusal;
export type SessionDoorRefusalReason = "not-started" | "cannot-continue" | "task-running" | LineSteerRefusal;

/** What a person reads for each refusal. */
const REFUSAL_TEXT: Record<SessionDoorRefusalReason, string> = {
"not-started": "This task hasn't started here, so there's no session to write into.",
"cannot-continue": "This run's harness confirmed no coding session, so it can't take a message once finished.",
"task-running": "This task is still running, so a message can't reach its coding session until it finishes.",
...LINE_STEER_REFUSALS,
};

Expand All @@ -70,9 +83,9 @@ export interface SessionDoorBoard {
readonly runOf: (row: Task) => { issue: string; phase: string } | undefined;
}

/** How a host builds the door. */
export interface HarnessSessionDoorOptions {
/** Names the door's blocks. Default `"harness-manager"`. */
/** How a host builds a talk turn: the door's options but the steer's. */
export interface HarnessTalkTurnOptions {
/** Names the turn's blocks. Default `"harness-manager"`. */
readonly name?: string;
/**
* The board the calling session's run is on, resolved per request from
Expand All @@ -81,13 +94,7 @@ export interface HarnessSessionDoorOptions {
readonly board: (ctx: BlockContext) => Promise<SessionDoorBoard | undefined>;
/** The harness, as the managers behind the door are given it: talk resumes the coding session with it. */
readonly harness: HarnessSlot;
/**
* Called after a steer that left the task waiting on it (it was running
* nothing): start the turn the steer is owed. A Workforce host passes
* `startOwedSteerTurn`.
*/
readonly onSteered?: (ctx: BlockContext, row: Task) => Promise<void>;
/** Capabilities the door's blocks hold, for the board ledgers `board` resolves. */
/** Capabilities the turn's blocks hold, for the board ledgers `board` resolves. */
readonly uses?: readonly DefinedCapability[];
/**
* How long one talk run may take, in ms, which also sizes the hold on the
Expand All @@ -96,6 +103,16 @@ export interface HarnessSessionDoorOptions {
readonly talkTimeoutMs?: number;
}

/** How a host builds the door. */
export interface HarnessSessionDoorOptions extends HarnessTalkTurnOptions {
/**
* Called after a steer that left the task waiting on it (it was running
* nothing): start the turn the steer is owed. A Workforce host passes
* `startOwedSteerTurn`.
*/
readonly onSteered?: (ctx: BlockContext, row: Task) => Promise<void>;
}

/** The newest of `rows`, by filing time, then attempts. */
function newest(rows: readonly Task[]): Task {
return rows.reduce((last, task) =>
Expand All @@ -111,26 +128,22 @@ function newest(rows: readonly Task[]): Task {
* the latest that ran here, whose coding session talk resumes.
*/
function sessionRow(tasks: TaskCollectionRef, sessionId: string): Task | undefined {
const rows = tasks.list() as Task[];
const rows = rowsInSession(tasks, sessionId);
const linked = rows.filter((task) => task.run?.sessionId === sessionId);
if (linked.length === 0) return undefined;
const roots = new Set(linked.map((task) => task.followUpOf ?? task.id));
const open = rows.filter((task) => roots.has(task.followUpOf ?? task.id) && !isTerminalStatus(task.status));
const open = rows.filter((task) => !isTerminalStatus(task.status));
const here = open.filter((task) => task.run?.sessionId === sessionId);
return newest(here.length > 0 ? here : open.length > 0 ? open : linked);
}

/** The default bound on one talk run. */
const DEFAULT_TALK_TIMEOUT_MS = 10 * 60_000;

/** What the decide step hands on: a steer done, or the talk to run. */
const decidedSchema = z.union([
z.object({ steered: z.string() }),
z.object({ talk: z.object({ prompt: z.string(), cwd: z.string(), resume: z.string(), taskId: z.string() }) }),
]);
/** What the talk's first step hands on: the prompt the harness resumes the coding session with. */
const talkPromptSchema = z.object({ prompt: z.string() });

/** The door's per-request values: where the talk runs and what it resumes. */
const doorStateSchema = z.object({
/** The talk's per-request values: where it runs and what it resumes. */
const talkStateSchema = z.object({
cwd: z.string().nullable().default(null),
resume: z.string().nullable().default(null),
taskId: z.string().nullable().default(null),
Expand All @@ -140,30 +153,38 @@ const doorStateSchema = z.object({
});

/**
* A coding run's door: declare it as the coding flow's action,
* `actions: { message: harnessSessionDoor({ board, harness }) }`.
* The talk half of a coding run's door, as a block of its own (FIX-2160): one
* harness run resumes the coding session of this session's finished task with
* the message, outside any attempt, and its final text is the reply. The task,
* its output and its attempts don't change. The door runs it for a person's
* line; a coder's `onMessageReceived` runs it as its turn for a message.
*
* @returns The action entry.
* Refuses, failing the request, when the session has no task
* (`not-started`), when its task is still open (`task-running`: a message
* never steers), and when the run confirmed no coding session
* (`cannot-continue`).
*
* @returns A block taking `{ message }` and answering `{ reply, taskId }`.
*/
export function harnessSessionDoor(options: HarnessSessionDoorOptions) {
export function harnessTalkTurn(options: HarnessTalkTurnOptions) {
const name = options.name ?? "harness-manager";
const capability = defineCapability({
name: `harness-manager-session-door:${name}`,
name: `harness-manager-talk:${name}`,
// The usage record a talk's harness writes its windows into, as a run's does.
resources: { [RUNS]: runRecordCollection, [HARNESS_USAGE]: harnessUsageCollection },
}) as unknown as DefinedCapability;
const uses = [capability, ...(options.uses ?? [])];
const talkTimeoutMs = options.talkTimeoutMs ?? DEFAULT_TALK_TIMEOUT_MS;
const { ownership } = resolveOwnership({ runTimeoutMs: talkTimeoutMs });
const stateOf = (ctx: { sequencer?: { state?: unknown } }) => (ctx.sequencer?.state ?? {}) as z.infer<typeof talkStateSchema>;
const releaseTalkLease = (ctx: { sequencer?: { state?: unknown } }) => {
const state = stateOf(ctx);
if (state.lockPath != null && state.leaseToken != null) releaseCheckout({ lockPath: state.lockPath, token: state.leaseToken });
};

// The talk's harness, fed from this door's own state: the checkout the
// The talk's harness, fed from this turn's own state: the checkout the
// finished run worked in and the session it confirmed. Outside any
// attempt, so it records no session of its own.
const stateOf = (ctx: { sequencer?: { state?: unknown } }) => (ctx.sequencer?.state ?? {}) as z.infer<typeof doorStateSchema>;
const talkHarness: HarnessBlock = options.harness({
cwd: (ctx) => stateOf(ctx as never).cwd ?? "",
resume: (ctx) => stateOf(ctx as never).resume,
Expand All @@ -174,24 +195,17 @@ export function harnessSessionDoor(options: HarnessSessionDoorOptions) {
},
});

const decide = handler({
name: `${name}-session-door`,
inputSchema: sessionDoorInputSchema,
outputSchema: decidedSchema,
sequencerStateSchema: doorStateSchema,
const find = handler({
name: `${name}-talk`,
inputSchema: harnessTalkInputSchema,
outputSchema: talkPromptSchema,
sequencerStateSchema: talkStateSchema,
uses,
execute: async (input, ctx: BlockContext) => {
const board = await options.board(ctx);
const row = board === undefined ? undefined : sessionRow(board.tasks, ctx.session.identity.id);
if (board === undefined || row === undefined) throw new SessionDoorRefused("not-started");
if (!isTerminalStatus(row.status)) {
const refused = await steerFromLine(board.tasks, row.id, input.message, ctx as never);
if (refused !== undefined) throw new SessionDoorRefused(refused);
const after = board.tasks.get(row.id);
// A line that answered the task's last open question owes it its turn too (FIX-2133).
if (after?.waitingOn === "steer" || after?.turnOwed === true) await options.onSteered?.(ctx, after);
return { steered: row.id };
}
if (!isTerminalStatus(row.status)) throw new SessionDoorRefused("task-running");
const identity = board.runOf(row);
const record =
identity === undefined
Expand All @@ -208,46 +222,91 @@ export function harnessSessionDoor(options: HarnessSessionDoorOptions) {
lockPath: lease.lockPath,
leaseToken: lease.token,
});
return { talk: { prompt: input.message, cwd: record.workspacePath, resume: record.sessionId, taskId: row.id } };
return { prompt: input.message };
},
});

const reply = handler({
name: `${name}-session-door-reply`,
name: `${name}-talk-reply`,
inputSchema: z.unknown(),
outputSchema: sessionDoorOutputSchema,
sequencerStateSchema: doorStateSchema,
outputSchema: harnessTalkOutputSchema,
sequencerStateSchema: talkStateSchema,
execute: async (value, ctx) => {
releaseTalkLease(ctx as never);
const handle = value as { finalMessage?: string | null; steered?: string };
if (typeof handle.steered === "string") return { steered: handle.steered };
const handle = value as { finalMessage?: string | null };
return { reply: handle.finalMessage ?? null, taskId: stateOf(ctx as never).taskId ?? "" };
},
});

const block = sequencer({ name: `${name}-session-door`, inputSchema: sessionDoorInputSchema, stateSchema: doorStateSchema })
.step(decide)
.stepIf(
(decided: z.infer<typeof decidedSchema>) => "talk" in decided,
(decided: z.infer<typeof decidedSchema>) => ({ prompt: (decided as { talk: { prompt: string } }).talk.prompt }),
talkHarness,
{ abortSignal: () => AbortSignal.timeout(talkTimeoutMs) },
)
return sequencer({ name: `${name}-talk`, inputSchema: harnessTalkInputSchema, stateSchema: talkStateSchema })
.step(find)
.step(talkHarness, { abortSignal: () => AbortSignal.timeout(talkTimeoutMs) })
.step(reply)
.rescue([
{
block: handler({
name: `${name}-session-door-release`,
name: `${name}-talk-release`,
inputSchema: z.unknown(),
outputSchema: z.unknown(),
sequencerStateSchema: doorStateSchema,
sequencerStateSchema: talkStateSchema,
execute: (error: unknown, ctx) => {
releaseTalkLease(ctx as never);
throw error;
},
}),
},
]);
}

/** What the door's first step hands on: a steer done, or the line to talk with. */
const decidedSchema = z.union([z.object({ steered: z.string() }), z.object({ talk: z.string() })]);

/**
* A coding run's door: declare it as the coding flow's action,
* `actions: { message: harnessSessionDoor({ board, harness }) }`.
*
* @returns The action entry.
*/
export function harnessSessionDoor(options: HarnessSessionDoorOptions) {
const name = options.name ?? "harness-manager";
const talk = harnessTalkTurn(options);

// An open task takes the line as a steer; a finished one hands it to the
// talk turn, which reads the row again and refuses what changed meanwhile.
const decide = handler({
name: `${name}-session-door`,
inputSchema: sessionDoorInputSchema,
outputSchema: decidedSchema,
uses: options.uses ?? [],
execute: async (input, ctx: BlockContext) => {
const board = await options.board(ctx);
const row = board === undefined ? undefined : sessionRow(board.tasks, ctx.session.identity.id);
if (board === undefined || row === undefined) throw new SessionDoorRefused("not-started");
if (isTerminalStatus(row.status)) return { talk: input.message };
const refused = await steerFromLine(board.tasks, row.id, input.message, ctx as never);
if (refused !== undefined) throw new SessionDoorRefused(refused);
const after = board.tasks.get(row.id);
// A line that answered the task's last open question owes it its turn too (FIX-2133).
if (after?.waitingOn === "steer" || after?.turnOwed === true) await options.onSteered?.(ctx, after);
return { steered: row.id };
},
});

const block = sequencer({ name: `${name}-session-door`, inputSchema: sessionDoorInputSchema })
.step(decide)
.stepIf(
(decided: z.infer<typeof decidedSchema>) => "talk" in decided,
(decided: z.infer<typeof decidedSchema>) => ({ message: (decided as { talk: string }).talk }),
talk,
)
.step(
handler({
name: `${name}-session-door-reply`,
inputSchema: z.unknown(),
outputSchema: sessionDoorOutputSchema,
execute: (value) => value as z.infer<typeof sessionDoorOutputSchema>,
}),
);

return {
block,
Expand Down
3 changes: 2 additions & 1 deletion packages/harness-manager/test/claim-host.ts
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ import type { BlockContext, BlockDefinition, HarnessBlock } from "@flow-state-de
import { createFlowState, inMemoryStores, runAction } from "@flow-state-dev/engine";
import {
defineTaskCollection,
taskLedgerResources,
getOrCreateTaskCollection,
openRowHolds,
resolveResourceCollection,
Expand Down Expand Up @@ -219,7 +220,7 @@ export function claimHost(options: HostOptions) {

const ledgerResources = defineCapability({
name: "claim-host-ledgers",
resources: { [FIXED_BOARD]: fixedLedger, [CONVERSATIONS]: conversations },
resources: { [FIXED_BOARD]: fixedLedger, ...taskLedgerResources(conversations) },
});

// File a row and claim it, as a board's drain would before dispatching it.
Expand Down
Loading