@edspencer/paddock 0.0.1 → 0.56.0

package/packages/server/dist/ws.js

@@ -0,0 +1,1024 @@
+import { createSDKMessageHandler } from "@herdctl/chat";
+import { extractSubagentLaunches, subagentLaunchFields, } from "./subagents.js";
+import { keeperAgentName, keeperSlugFromAgent, } from "./herdctl.js";
+import { consumeResumedTurn } from "./resume-drain.js";
+import { isKnownModel, getContextLimit, DEFAULT_MODEL, isKnownDriveMode, } from "./models.js";
+import { SessionHub } from "./session-hub.js";
+import { resolveAttachmentsConfig } from "./attachments-config.js";
+import { wrapAttachments, inferAttachmentKind } from "./attachments-hint.js";
+import { sendFileServerDef, SEND_FILE_SERVER_KEY } from "./send-file-mcp.js";
+import { SELF_MCP_SERVER_KEY } from "./self-mcp.js";
+import { HUMAN_ROOT } from "./run-provenance.js";
+import { resolveRecoveryConfig } from "./recovery-config.js";
+import { noticeFromMessage, errorNotice, messageProducedReply, suppressNoticeAfterReply, turnEffectivelySucceeded, } from "./turn-notice.js";
+import { resolveHooksMcpEnabled } from "./hook-config.js";
+// --- protocol + usage math (extracted #403) ---------------------------------
+// The wire protocol (message interfaces + unions + `isClientMessage`) and the
+// per-turn token/usage helpers now live in ws-protocol.ts. Re-export the whole
+// surface so external importers (and tests) that `import … from "./ws.js"`
+// resolve unchanged, then pull in the handful this module uses directly.
+export * from "./ws-protocol.js";
+// forkKickoffPrompt + buildSelfMcpServerDef now live in ws-self-mcp.ts; re-export
+// forkKickoffPrompt so external importers (and its test) resolve it via ws.js.
+export { forkKickoffPrompt } from "./ws-self-mcp.js";
+import { buildSelfMcpServerDef } from "./ws-self-mcp.js";
+import { makeTurnEngine, isSidechainMessage } from "./ws-turn.js";
+// RECOVERY_NUDGE now lives in ws-turn.ts; re-export so its test resolves via ws.js.
+export { RECOVERY_NUDGE } from "./ws-turn.js";
+import { extractLocalCommandOutput, initTurnUsage, foldTurnUsage, resolveTurnUsage, isClientMessage, } from "./ws-protocol.js";
+/**
+ * Register the /ws route handler. Pure transport: it validates messages,
+ * resolves the target agent, and streams a real trigger back to the socket.
+ */
+// Server-side keepalive: how often to ping each client and, if the previous
+// ping went unanswered, reap the dead socket. Protocol-level ping frames also
+// keep intermediaries (proxies/NAT) from evicting an otherwise-idle connection.
+// See issue #46.
+const SERVER_PING_INTERVAL_MS = 30_000;
+// Separator in a composite in-memory key; a NUL can't occur in an agent name or
+// a UUID. Spelled as an escape, never a raw 0x00 byte — a literal NUL makes
+// ripgrep/grep treat this file as binary and skip it during directory traversal
+// (silently, exit 1, indistinguishable from "no matches"). See issue #570.
+const KEY_SEP = "\u0000";
+export function makeChatHandler(deps) {
+    // ONE hub shared across every socket this handler serves: it tracks each
+    // session's in-flight turn and fans its frames out to whichever socket(s) are
+    // currently attached, so a turn survives the death of the socket that started
+    // it (issue #54). See session-hub.ts.
+    const hub = new SessionHub();
+    // Per-session marker of the last queued message the server has already drained
+    // (#245), keyed `agent \0 sessionId` and stamped with that message's client
+    // timestamp. Lets an idle-drain skip a message it already sent — e.g. a stale
+    // localStorage copy a reloaded client re-asserts — instead of double-sending.
+    // In-memory (shared across this handler's sockets); a rare double-send only
+    // survives a server restart, when the persisted store is already empty anyway.
+    const lastFlushedTs = new Map();
+    // Every currently-connected socket, so a turn's start/stop transition can be
+    // broadcast to all clients — powering the per-chat sidebar streaming dots that
+    // must update even for chats whose pane isn't mounted (issue #53).
+    const clients = new Set();
+    const activeFrame = (info) => ({
+        type: "chat:active",
+        payload: {
+            projectSlug: info.projectSlug,
+            sessionId: info.sessionId,
+            jobId: info.jobId,
+            running: info.running,
+        },
+    });
+    hub.onActive = (info) => {
+        const data = JSON.stringify(activeFrame(info));
+        for (const c of clients) {
+            if (c.readyState === c.OPEN) {
+                try {
+                    c.send(data);
+                }
+                catch {
+                    /* a socket that throws on send is effectively gone */
+                }
+            }
+        }
+    };
+    // Drive scheduler-fired session wakes onto the hub (Paddock#111 gap 3). When a
+    // keeper scheduled a `ScheduleWakeup` / `/loop`, herdctl reaps the idle session
+    // and later resumes it at fire time, handing us the live (managed) session with
+    // NO client watching. We stream it exactly like a human turn — same translator,
+    // same hub — so the autonomous work lands in the transcript, drives the sidebar
+    // streaming dot (via `hub.onActive`), and is replayable by a client that opens
+    // the chat later. We do NOT close the session: it's managed, so the reaper tears
+    // it down when it goes idle again (and re-captures any fresh wakeups).
+    deps.herdctl.onSessionWake(async (session, entry) => {
+        // Only KEEPER agents own chats. A wake from a sweeper/trigger/hook agent has
+        // no chat to drive, so there is nothing to route.
+        const slug = keeperSlugFromAgent(entry.agent);
+        // `null` = not a keeper. `""` = the ROOT workspace's own key, so this must
+        // stay an explicit null check or every root chat's wake is dropped.
+        if (slug === null)
+            return;
+        let resolvedSession = entry.sessionId ?? null;
+        const turn = hub.startTurn(slug, null, entry.sessionId);
+        // #353: DON'T stamp a creation origin here. A session wake is a *resume*, not
+        // a *creation* — `onSessionWake` only ever resumes an already-existing chat
+        // (a human's, or a spawn's, that armed a `ScheduleWakeup`/`/loop`), it never
+        // creates one. Genuinely schedule-*created* chats are already stamped
+        // `scheduled` at creation by `fireTriggerForProject` → `startAgentTurn`, so
+        // dropping the wake stamp loses nothing for them. The old
+        // `stampIfAbsent(SCHEDULED_ROOT)` here was a category error: a chat that
+        // predates provenance stamping (empty slot) and later arms a ScheduleWakeup
+        // would get falsely labelled `scheduled` on its first wake — mislabelling a
+        // human-rooted chat. Leaving a legacy/blank chat unstamped renders no badge
+        // (the correct outcome for a human chat) instead of a wrong one.
+        const routing = () => ({
+            projectSlug: slug,
+            sessionId: resolvedSession,
+            jobId: turn.jobId,
+        });
+        // #429: sub-agent launches recovered live from the tool_use input, keyed by
+        // toolUseId, so the wake turn's launching card renders enriched + expandable
+        // without a refresh (see subagentLaunchFields).
+        const wakeLaunches = new Map();
+        const translate = createSDKMessageHandler({
+            onText: (chunk) => {
+                if (chunk)
+                    turn.emit({ type: "chat:response", payload: { ...routing(), chunk } });
+            },
+            onBoundary: () => {
+                turn.emit({ type: "chat:message_boundary", payload: routing() });
+            },
+            onToolStart: (start) => {
+                turn.emit({
+                    type: "chat:tool_start",
+                    payload: {
+                        ...routing(),
+                        toolName: start.toolName,
+                        inputSummary: start.inputSummary,
+                        toolUseId: start.toolUseId,
+                        parentToolUseId: start.parentToolUseId,
+                        ...subagentLaunchFields(wakeLaunches, start.toolName, start.toolUseId),
+                    },
+                });
+            },
+            onToolCall: (call) => {
+                turn.emit({
+                    type: "chat:tool_call",
+                    payload: {
+                        ...routing(),
+                        toolName: call.toolName,
+                        inputSummary: call.inputSummary,
+                        output: call.output,
+                        isError: call.isError,
+                        durationMs: call.durationMs,
+                        toolUseId: call.toolUseId,
+                        ...subagentLaunchFields(wakeLaunches, call.toolName, call.toolUseId),
+                    },
+                });
+            },
+        });
+        // #329: surface a dead-end (usage limit / max-turns / error) on this wake
+        // turn too, at most once. Same rationale as the interactive path.
+        // #380/#394: once the turn has shown the user real prose, an error/max_turns
+        // dead-end is a false alarm — suppress it (matching the history path).
+        // `wakeProducedReply` is OR-accumulated across every message (a tool-heavy
+        // turn's prose rides on a `tool_use` message, not the terminal one). A
+        // `usage_limit` still surfaces.
+        let wakeNoticeEmitted = false;
+        let wakeProducedReply = false;
+        const emitWakeNotice = (notice) => {
+            if (wakeNoticeEmitted)
+                return;
+            if (suppressNoticeAfterReply(notice, wakeProducedReply))
+                return;
+            wakeNoticeEmitted = true;
+            turn.emit({ type: "chat:notice", payload: { ...routing(), notice } });
+        };
+        // Per-message wake handling, shared by the fast path and the drain path.
+        const onWakeSessionId = (id) => {
+            resolvedSession = id;
+            turn.setSession(id);
+            // #353: no provenance stamp on wake — see the note at the top of this
+            // handler. A resume must never write a creation origin.
+        };
+        const onWakeMessage = async (m) => {
+            // A sub-agent's nested steps never render top-level ({@link isSidechainMessage}).
+            if (isSidechainMessage(m))
+                return;
+            if (messageProducedReply(m))
+                wakeProducedReply = true;
+            const notice = noticeFromMessage(m);
+            if (notice)
+                emitWakeNotice(notice);
+            // #429: recover any Task/Agent launch before translate fires onToolStart.
+            for (const l of extractSubagentLaunches(m))
+                wakeLaunches.set(l.toolUseId, l);
+            await translate(m);
+        };
+        try {
+            // Resume self-interrupt fix. A woken session that still holds a stale
+            // async-input backlog replays it as its OWN turn ahead of the wake turn; the
+            // old break-after-first-result then closed the CLI on the backlog turn's
+            // result, killing the wake turn. A wake is always a resume, so consume with
+            // the queue-drain break rule — break on a `result` only once the async queue
+            // has drained (after the LAST/real wake turn). No backlog → breaks after the
+            // first result (fast). See ./resume-drain.ts.
+            if (entry.sessionId) {
+                await consumeResumedTurn(session, {
+                    residueProbe: () => deps.herdctl.residueDepthFor(entry.agent, entry.sessionId),
+                    onMessage: onWakeMessage,
+                    onSessionId: onWakeSessionId,
+                    log: (msg) => 
+                    // eslint-disable-next-line no-console
+                    console.log(`[resume-drain] wake ${entry.agent} (${entry.sessionId}): ${msg}`),
+                });
+            }
+            else {
+                for await (const m of session.messages) {
+                    if (m.session_id)
+                        onWakeSessionId(m.session_id);
+                    await onWakeMessage(m);
+                    if (m.type === "result")
+                        break;
+                }
+            }
+            turn.emit({
+                type: "chat:complete",
+                payload: { ...routing(), sessionId: resolvedSession, success: true },
+            });
+        }
+        catch (err) {
+            const error = err instanceof Error ? err.message : String(err);
+            emitWakeNotice(errorNotice(error));
+            turn.emit({ type: "chat:complete", payload: { ...routing(), success: false, error } });
+        }
+        finally {
+            turn.end();
+        }
+        // Post-wake curation sweep, same as a human turn. Fires for EVERY workspace,
+        // the root included (its sweeper is `sweeper-_root`, registered at boot) — the
+        // emit is unconditional and skips nothing. T5: routed through the `afterTurn`
+        // event so the folded-in curator dispatches once.
+        emitAfterTurn(slug, resolvedSession ?? null);
+    });
+    // Turn-execution engine (ws-turn.ts, #403): the mutually-recursive core —
+    // trigger cluster, self-MCP injection context, per-turn injected-MCP builders +
+    // wake cache, the shared startAgentTurn engine, and Layer-2/3 recovery. Relocated
+    // as one scope so its cross-references stay intact; the socket layer below
+    // consumes the returned surface.
+    const engine = makeTurnEngine({ deps, hub });
+    const { startAgentTurn, wakeInjection, selfMcpCtx, injectRecoveryNudge, recoveryEngine, emitAfterTurn, composePreloadedPrompt, fireTrigger, makeBackgroundTurnSink, } = engine;
+    const handle = async function handle(socket) {
+        const send = (m) => {
+            if (socket.readyState === socket.OPEN)
+                socket.send(JSON.stringify(m));
+        };
+        // Register this socket for active-turn broadcasts, and immediately catch it
+        // up on which sessions are currently running (so the sidebar dots and a
+        // returning pane's Stop button reflect reality from the first paint).
+        clients.add(socket);
+        for (const info of hub.runningSessions())
+            send(activeFrame(info));
+        // Heartbeat: browsers auto-answer protocol ping frames with a pong, so a
+        // client whose TCP has silently died (idle drop, sleep) fails to pong and is
+        // terminated on the next tick — freeing server resources and letting the
+        // client's own reconnect take over. Cleared when the socket closes.
+        let isAlive = true;
+        socket.on("pong", () => {
+            isAlive = true;
+        });
+        const heartbeat = setInterval(() => {
+            if (!isAlive) {
+                socket.terminate();
+                return;
+            }
+            isAlive = false;
+            try {
+                socket.ping();
+            }
+            catch {
+                socket.terminate();
+            }
+        }, SERVER_PING_INTERVAL_MS);
+        socket.on("close", () => {
+            clearInterval(heartbeat);
+            // Drop this socket from every session fan-out set so the hub stops trying
+            // to write to it (a running turn keeps going for other attached sockets).
+            hub.unsubscribeSocket(socket);
+            clients.delete(socket);
+        });
+        socket.on("message", (raw) => {
+            let parsed;
+            try {
+                parsed = JSON.parse(raw.toString());
+            }
+            catch {
+                send({ type: "chat:error", payload: { projectSlug: "?", error: "Invalid JSON" } });
+                return;
+            }
+            if (!isClientMessage(parsed)) {
+                send({ type: "chat:error", payload: { projectSlug: "?", error: "Unknown message" } });
+                return;
+            }
+            if (parsed.type === "ping") {
+                send({ type: "pong" });
+                return;
+            }
+            if (parsed.type === "chat:cancel") {
+                void deps.herdctl.cancel(parsed.payload.jobId).catch(() => undefined);
+                return;
+            }
+            if (parsed.type === "chat:subscribe") {
+                onSubscribe(parsed);
+                return;
+            }
+            if (parsed.type === "chat:set_queue") {
+                void onSetQueue(parsed);
+                return;
+            }
+            if (parsed.type === "chat:command") {
+                void onChatCommand(parsed);
+                return;
+            }
+            if (parsed.type === "chat:continue") {
+                void onChatContinue(parsed);
+                return;
+            }
+            void onChatSend(parsed);
+        });
+        /**
+         * Manual keeper recovery (issue #301, Layer 2). Re-drive a hung keeper whose
+         * background task was killed at the turn boundary by injecting the recovery
+         * nudge into its still-alive session via {@link startAgentTurn} — the same
+         * workhorse the self-MCP `send_message` / schedule fires use, so the injected
+         * turn streams live, lists in the sidebar, and is attributable
+         * (`sender: recovery`). Server-authoritative gate: no-op unless the resolved
+         * `recovery.surfaceKilledTask` is on for this project, so a stale/rogue client
+         * can't re-drive when the operator disabled Layer 2.
+         */
+        const onChatContinue = async (msg) => {
+            // `""` addresses the ROOT workspace, so only a MISSING key is a no-op.
+            const slug = msg.payload.projectSlug;
+            if (slug === undefined || slug === null)
+                return;
+            const sessionId = msg.payload.sessionId;
+            if (!sessionId)
+                return;
+            let project;
+            try {
+                project = await deps.projects.get(slug);
+            }
+            catch {
+                return; // unknown project — nothing to recover
+            }
+            // Gate on the resolved Layer 2 flag (per-project override else instance).
+            const recovery = resolveRecoveryConfig(project.recovery, deps.cfg.recovery);
+            if (!recovery.surfaceKilledTask)
+                return;
+            // Re-drive via the shared recovery path (also used by Layer 3 auto-recovery).
+            await injectRecoveryNudge(project, sessionId).catch((err) => {
+                send({
+                    type: "chat:error",
+                    payload: { projectSlug: slug, error: `Recovery failed: ${String(err)}` },
+                });
+            });
+        };
+        const onSubscribe = (msg) => {
+            const { sessionId, wantReplay, lastSeq } = msg.payload;
+            const result = hub.attach(sessionId, socket, {
+                wantReplay: wantReplay === true,
+                afterSeq: typeof lastSeq === "number" ? lastSeq : -1,
+            });
+            if (result.status === "resync") {
+                send({
+                    type: "chat:resync",
+                    payload: { projectSlug: result.projectSlug, sessionId },
+                });
+            }
+            // Tell a (re)attaching pane whether its session has a live turn, so a chat
+            // the user navigated back to restores its Stop button + jobId and streaming
+            // indicator immediately — not only once the next frame happens to arrive
+            // (issues #52/#53).
+            const active = hub.activeInfo(sessionId);
+            if (active)
+                send(activeFrame(active));
+        };
+        // Server-authoritative queue drain (#245): auto-send a persisted queued
+        // message as the next turn, exactly once. Called (a) when a turn completes
+        // successfully and (b) when a queue is set while the session is idle — a queue
+        // that arrived (e.g. via the reconnect outbox) after the turn it was meant to
+        // follow already ended. `take` makes the read+clear atomic so the two callers
+        // can never both send it; the `lastFlushedTs` marker skips a message already
+        // drained (a stale client re-assert on reload) so it isn't sent twice.
+        const drainQueue = async (slug, sessionId) => {
+            if (!deps.queuedMessage)
+                return;
+            const agent = keeperAgentName(slug);
+            const queued = await deps.queuedMessage.take(agent, sessionId).catch(() => null);
+            if (!queued?.text)
+                return;
+            const markerKey = `${agent}${KEY_SEP}${sessionId}`;
+            const already = (lastFlushedTs.get(markerKey) ?? 0) >= queued.createdAtMs;
+            // Tell every attached client (origin + reconnected sockets) to clear its copy
+            // of this message. When we're really sending it, carry the text so the client
+            // renders the sent bubble in-transcript; on a stale re-assert we only clear.
+            hub.broadcast(sessionId, {
+                type: "chat:queued_flushed",
+                payload: {
+                    projectSlug: slug,
+                    sessionId,
+                    ...(already ? {} : { text: queued.text }),
+                },
+            });
+            if (already)
+                return;
+            lastFlushedTs.set(markerKey, queued.createdAtMs);
+            // Broadcast the flush frame BEFORE kicking the turn so the user bubble renders
+            // above the reply. Run it detached, like a human send. A leading-slash queued
+            // message is a slash command (e.g. "/compact"): route it through the command
+            // path so the CLI dispatches it — matching how the composer sends one live.
+            if (queued.text.startsWith("/")) {
+                void onChatCommand({
+                    type: "chat:command",
+                    payload: { projectSlug: slug, command: queued.text, sessionId },
+                });
+            }
+            else {
+                void onChatSend({
+                    type: "chat:send",
+                    payload: { projectSlug: slug, sessionId, message: queued.text },
+                });
+            }
+        };
+        const onSetQueue = async (msg) => {
+            if (!deps.queuedMessage)
+                return; // feature disabled
+            // `""` addresses the ROOT workspace, so only a MISSING key is a no-op.
+            const slug = msg.payload.projectSlug;
+            if (slug === undefined || slug === null)
+                return;
+            const sessionId = msg.payload.sessionId ?? null;
+            const text = msg.payload.text ?? null;
+            // Every chat belongs to a workspace keeper.
+            const agent = keeperAgentName(slug);
+            if (!sessionId) {
+                // New chat: queue isn't stored until the session id exists. The client
+                // re-asserts it (with the same ts) once the id resolves, so it persists then.
+                return;
+            }
+            // Store or clear the queued message.
+            if (text && text.trim().length > 0) {
+                await deps.queuedMessage
+                    .set(agent, sessionId, { text, createdAtMs: msg.payload.ts ?? Date.now() })
+                    .catch(() => undefined);
+                // If no turn is running, this queue arrived after the turn it was meant to
+                // follow already ended — drain it now rather than wait for a completion
+                // that won't come (the reported stranding bug, #245).
+                if (!hub.isRunning(sessionId))
+                    await drainQueue(slug, sessionId);
+            }
+            else {
+                await deps.queuedMessage.set(agent, sessionId, null).catch(() => undefined);
+            }
+        };
+        const onChatSend = async (msg) => {
+            const slug = msg.payload.projectSlug;
+            const { message, sessionId, preloadContext, attachments: sentAttachments } = msg.payload;
+            const isNewChat = sessionId === undefined || sessionId === null;
+            // A genuine human message resets this session's Layer 3 recovery guard (issue
+            // #301) and cancels any in-flight watch, so the retry cap counts auto re-drives
+            // BETWEEN human messages and a later real hang is recovered fresh.
+            if (sessionId)
+                recoveryEngine.onHumanMessage(sessionId);
+            let jobId = null;
+            let resolvedSession = sessionId ?? null;
+            // One-shot guard: a brand-new chat is attributed to its agent the instant
+            // its session id first streams back, so it lists in the sidebar mid-turn
+            // instead of only after the turn completes (issue #100). Resumed chats are
+            // already attributed, so this only runs for a new chat.
+            let attributed = false;
+            // Track this turn in the session hub so its frames fan out to whichever
+            // socket(s) are attached — not just this one — and a reconnecting client
+            // can re-attach + replay the missed gap (issue #54). A resumed chat's id is
+            // known now (re-attachable from frame 0); a new chat registers once the id
+            // arrives mid-stream (see turn.setSession below).
+            const turn = hub.startTurn(slug, socket, sessionId ?? null);
+            // Per-turn usage + model captured off the SDK stream (last non-null wins).
+            // Held on a mutable record (not bare `let`s) so the values assigned inside
+            // the streaming callback are visible to control-flow analysis afterwards.
+            const seen = initTurnUsage();
+            // The model the turn will run on; resolved below once we know the target.
+            let effectiveModel = DEFAULT_MODEL;
+            // How this turn is driven (Paddock#111): the global default unless the
+            // workspace overrides it (resolved in the workspace branch below).
+            let driveMode = deps.cfg.driveMode;
+            // The agent's working directory, so the send_file tool can resolve a real
+            // `file_path` (and sandbox it). Resolved alongside the agent below.
+            let sendFileWorkingDir;
+            const routing = () => ({
+                projectSlug: slug,
+                sessionId: resolvedSession,
+                jobId,
+            });
+            // #329: surface a turn dead-end (usage limit / max-turns / error) inline, at
+            // most once per turn — a synthetic session-limit reply repeats several times,
+            // and a failed turn can carry both an error `result` and a `success:false`
+            // completion. Emit the first, suppress the rest.
+            let noticeEmitted = false;
+            // #380: whether a COMPLETE assistant reply already streamed this turn. In
+            // session mode the SDK's terminal `result` (streamed live, never persisted)
+            // can carry an `error_*` subtype / `success:false` AFTER a good `end_turn`
+            // reply, painting a false "turn failed" banner beneath the answer. Once a
+            // reply is seen we suppress the error/max_turns dead-end — the same guard the
+            // history path (`scanTranscriptNotice`) already applies on reload. A
+            // `usage_limit` dead-end still surfaces (a session-limit stop is real).
+            let producedReply = false;
+            const emitNotice = (notice) => {
+                if (noticeEmitted)
+                    return;
+                if (suppressNoticeAfterReply(notice, producedReply))
+                    return;
+                noticeEmitted = true;
+                turn.emit({ type: "chat:notice", payload: { ...routing(), notice } });
+            };
+            // #429: sub-agent launches recovered live from the tool_use input, keyed by
+            // toolUseId, so a launching card shows the real type/title + is expandable into
+            // its (streaming) steps without a refresh. Populated in onMessage before each
+            // translate; read by the onToolStart/onToolCall closures via subagentLaunchFields.
+            const subagentLaunches = new Map();
+            // @herdctl/chat's shared translator turns the SDKMessage stream into the
+            // three UI events we forward over the socket. Created fresh per turn (it
+            // holds per-turn tool-pairing state).
+            const translate = createSDKMessageHandler({
+                onText: (chunk) => {
+                    if (chunk)
+                        turn.emit({ type: "chat:response", payload: { ...routing(), chunk } });
+                },
+                onBoundary: () => {
+                    turn.emit({ type: "chat:message_boundary", payload: routing() });
+                },
+                onToolStart: (start) => {
+                    turn.emit({
+                        type: "chat:tool_start",
+                        payload: {
+                            ...routing(),
+                            toolName: start.toolName,
+                            inputSummary: start.inputSummary,
+                            toolUseId: start.toolUseId,
+                            parentToolUseId: start.parentToolUseId,
+                            ...subagentLaunchFields(subagentLaunches, start.toolName, start.toolUseId),
+                        },
+                    });
+                },
+                onToolCall: (call) => {
+                    turn.emit({
+                        type: "chat:tool_call",
+                        payload: {
+                            ...routing(),
+                            toolName: call.toolName,
+                            inputSummary: call.inputSummary,
+                            output: call.output,
+                            isError: call.isError,
+                            durationMs: call.durationMs,
+                            toolUseId: call.toolUseId,
+                            ...subagentLaunchFields(subagentLaunches, call.toolName, call.toolUseId),
+                        },
+                    });
+                },
+            });
+            try {
+                // Every workspace key resolves to a keeper (`keeper-<slug>`), including
+                // the root's `keeper-_root` (its key is `""`, encoded via `agentKeyFor`).
+                let agentName;
+                // Effective prompt — may be augmented with the project overview below.
+                let prompt = message;
+                // Whether this project agent gets the T3 unified trigger-management tools
+                // (resolved from the project's REUSED hooks-MCP `hooksMcpEnabled` override
+                // else the instance default).
+                let includeTriggers = false;
+                const requested = msg.payload.model;
+                {
+                    // Verifies the project exists (throws if not); we keep the object so
+                    // we can resolve its model + re-register the keeper for an override.
+                    const project = await deps.projects.get(slug);
+                    agentName = keeperAgentName(slug);
+                    sendFileWorkingDir = project.dir;
+                    // Project chat: a valid override wins, else the project's model. Then
+                    // ensure the (shared) keeper is registered at that model before the
+                    // trigger. NOTE single-user last-write-wins caveat (see herdctl.ts).
+                    effectiveModel =
+                        requested && isKnownModel(requested) ? requested : project.model;
+                    await deps.herdctl.ensureAgentModel(project, effectiveModel);
+                    // Per-project driveMode override wins over the global default
+                    // (Paddock#111). An absent/invalid value inherits the global.
+                    driveMode =
+                        project.driveMode && isKnownDriveMode(project.driveMode)
+                            ? project.driveMode
+                            : deps.cfg.driveMode;
+                    // T3 trigger-management gate (REUSES the hooks-MCP gate): the per-project
+                    // override wins, else the instance default. Only takes effect when the
+                    // write tools are also on (the trigger tools live in the write block).
+                    includeTriggers =
+                        deps.cfg.selfMcpWriteEnabled &&
+                            resolveHooksMcpEnabled(project.hooksMcpEnabled, deps.cfg.hooksMcpEnabled);
+                    // Composer attachments (issue #328): validate the uploaded files against
+                    // this project's effective attachment config, then prepend a
+                    // `<paddock-attachments>` hint block pointing the keeper's Read tool at
+                    // the stored files' absolute paths. Wrapped BEFORE preload so the whole
+                    // thing nests inside the preload block. Invalid/missing/over-count
+                    // attachments are dropped (defensive — the endpoint already gated them).
+                    if (sentAttachments && sentAttachments.length > 0) {
+                        const acfg = resolveAttachmentsConfig(project.attachments, deps.cfg.attachments);
+                        if (acfg.enabled) {
+                            const promptAtts = [];
+                            for (const a of sentAttachments.slice(0, acfg.maxFilesPerMessage)) {
+                                const abs = deps.attachments.absolutePath(a.id);
+                                if (!abs || !(await deps.attachments.exists(a.id)))
+                                    continue;
+                                promptAtts.push({
+                                    id: a.id,
+                                    filename: a.filename,
+                                    kind: inferAttachmentKind(a.filename),
+                                    path: abs,
+                                });
+                            }
+                            prompt = wrapAttachments(promptAtts, prompt);
+                        }
+                    }
+                    // Context preload (issues #1/#188): only for a NEW chat, only when
+                    // asked. Shared with the self-MCP create_chat path (C2 / #264):
+                    // injects BOTH OVERVIEW.md and CHANGELOG.md when the project has
+                    // curated state, else leaves the prompt untouched. Wraps the (possibly
+                    // attachment-wrapped) `prompt`, not the bare `message`.
+                    if (isNewChat && preloadContext) {
+                        prompt = await composePreloadedPrompt(slug, prompt);
+                    }
+                }
+                // Inject the Paddock send_file MCP tool for this turn. The tool returns a
+                // JSON envelope as its result `output`; the web renders it off the tool
+                // call itself (live + on reload), so no bespoke WS frame is needed. The
+                // working dir resolves a relative `file_path`; a real file's bytes are
+                // copied into the attachment store at send time (immutable snapshot).
+                const sendFile = sendFileServerDef({
+                    workingDirectory: sendFileWorkingDir,
+                    saveAttachment: (bytes, name) => deps.attachments.save(bytes, name),
+                });
+                const injectedMcpServers = {
+                    [SEND_FILE_SERVER_KEY]: sendFile,
+                };
+                // Self-management MCP (issue #214): only on keeper turns, and only when
+                // the instance opts in via PADDOCK_SELF_MCP. A HUMAN turn is
+                // the ROOT of any spawn tree (origin human, depth 0), so its children are
+                // depth 1 — the same builder the spawned path uses, just seeded with
+                // HUMAN_ROOT. Write tools follow the instance write opt-in (B1 #262: the
+                // shared builder is extracted so both paths agree). Depth-0 human gating is
+                // unchanged from before B1 — the depth bound governs the spawned path only.
+                if (deps.cfg.selfMcpEnabled) {
+                    injectedMcpServers[SELF_MCP_SERVER_KEY] = buildSelfMcpServerDef(selfMcpCtx, {
+                        currentProjectSlug: slug,
+                        currentSessionId: () => resolvedSession ?? sessionId ?? null,
+                        parentProvenance: HUMAN_ROOT,
+                        includeWrite: deps.cfg.selfMcpWriteEnabled,
+                        includeTriggers,
+                        // Project provisioning (#467) rides on the write block behind its own
+                        // instance flag — no per-project override, so nothing to resolve here.
+                        includeProjects: deps.cfg.selfMcpWriteEnabled && deps.cfg.selfMcpProjectsEnabled,
+                    });
+                }
+                // Session mode drives a persistent, herdctl-managed openChatSession so
+                // cross-turn autonomy (ScheduleWakeup / `/loop`) survives the turn
+                // boundary; batch mode keeps the legacy one-shot trigger. Both stream
+                // through the identical onMessage/onJobCreated contract (Paddock#111).
+                const drive = driveMode === "session"
+                    ? deps.herdctl.chatSession.bind(deps.herdctl)
+                    : deps.herdctl.chat.bind(deps.herdctl);
+                // Gap B sink (session mode): one persistent sink groups every background
+                // re-invocation onto a single hub turn (skipping sidechain sub-agent
+                // steps). Built once so its turn/translator state spans the stream.
+                const bgSink = driveMode === "session" ? makeBackgroundTurnSink(slug) : null;
+                const result = await drive(agentName, {
+                    prompt,
+                    // omit -> agent-level fallback; explicit null -> new chat; id -> resume.
+                    resume: sessionId ?? null,
+                    triggerType: "web",
+                    injectedMcpServers,
+                    // Gap B: deliver autonomous background-completion turns live (session
+                    // mode only; batch `chat` ignores this). The human turn holds the
+                    // session open when it launches background work; the persistent sink
+                    // renders each later re-invocation onto ONE hub turn (skipping sidechain
+                    // sub-agent steps).
+                    onBackgroundMessage: bgSink?.onMessage,
+                    onBackgroundDone: bgSink?.onDone,
+                    onJobCreated: (id) => {
+                        jobId = id;
+                        turn.setJobId(id);
+                    },
+                    onMessage: async (m) => {
+                        // A FOREGROUND sub-agent streams its nested steps INLINE on this very
+                        // stream, tagged `parent_tool_use_id`. They belong inside the sub-agent
+                        // card (served by the subagents endpoint), never as top-level rows of
+                        // the parent transcript — see {@link isSidechainMessage}. This is the
+                        // human `chat:send` path, so it is where the duplication was actually
+                        // seen. Skipping also keeps a sub-agent's context out of the parent's
+                        // live meter (`foldTurnUsage` below would latch its max — the #398 shape).
+                        if (isSidechainMessage(m))
+                            return;
+                        // Capture the session id as it arrives mid-stream (the translator
+                        // only surfaces text/boundary/tool events, not routing metadata).
+                        // Registering it with the hub makes the turn re-attachable by session.
+                        if (m.session_id) {
+                            resolvedSession = m.session_id;
+                            // #390: remember this human turn's injected servers so a wake this
+                            // chat self-schedules can replay them (the common flap scenario).
+                            wakeInjection.remember(m.session_id, injectedMcpServers);
+                            // For a NEW chat, attribute the session to its agent BEFORE the
+                            // hub broadcasts `chat:active`, so any client refetching its chat
+                            // list in response is guaranteed to see the now-listed chat — it
+                            // no longer waits for the turn to complete (issue #100). Awaited
+                            // once (a quick local job-record write); never fatal to the turn.
+                            if (isNewChat && !attributed) {
+                                attributed = true;
+                                // Non-fatal: on failure the chat simply falls back to appearing
+                                // once its turn completes (the prior behavior), never breaking
+                                // the live stream.
+                                await deps.herdctl
+                                    .attributeRunningSession(m.session_id, agentName)
+                                    .catch(() => undefined);
+                                // A1 (#261): a human-started chat is the ROOT of any spawn tree —
+                                // origin human, depth 0. Stamped once at creation; later turns on
+                                // this chat never change its recorded provenance.
+                                await deps.runProvenance?.stamp(m.session_id, HUMAN_ROOT).catch(() => undefined);
+                            }
+                            turn.setSession(m.session_id);
+                        }
+                        // Capture per-turn usage + model defensively. Assistant blocks feed
+                        // the context snapshot (keeping the largest — issue #165); the terminal
+                        // `result` block's CUMULATIVE usage is stashed separately so it can't
+                        // inflate the live context meter (#398).
+                        foldTurnUsage(seen, m);
+                        // #329: surface a dead-end BEFORE translating — a synthetic usage-limit
+                        // message or a terminal error/`error_max_turns` result. The translator
+                        // silently drops every synthetic message (which is exactly why these
+                        // turns look dead); `noticeFromMessage` returns null for ordinary output
+                        // and for suppressed "No response requested." placeholders.
+                        // #380: track a completed reply so a trailing error/max_turns result
+                        // (which races in AFTER the reply in session mode) is suppressed below.
+                        if (messageProducedReply(m))
+                            producedReply = true;
+                        const notice = noticeFromMessage(m);
+                        if (notice)
+                            emitNotice(notice);
+                        // #429: recover any Task/Agent launch from this message's tool_use input
+                        // so the enriched card renders live — before translate fires onToolStart.
+                        for (const l of extractSubagentLaunches(m))
+                            subagentLaunches.set(l.toolUseId, l);
+                        // @herdctl/core's SDKMessage types `message` as `unknown` (wider);
+                        // @herdctl/chat's translator declares a structurally narrower
+                        // SDKMessage. Same runtime object — cast across the package boundary.
+                        // (@herdctl/chat@0.4.1 pairs CLI tool results, so no shim needed.)
+                        await translate(m);
+                    },
+                });
+                // #404: session-mode turns that produced a real reply routinely end with a
+                // trailing `error_*` / `success:false` result frame (the #380/#394 banner
+                // asymmetry). Raw `result.success` is reply-unaware, so gating the post-turn
+                // side effects below on it silently strands a queued follow-up, skips the
+                // sweep, and drops the recovery arm. Trust the same `producedReply` signal
+                // the banner already does — a real reply supersedes a benign trailing failure.
+                const effectiveSuccess = turnEffectivelySucceeded(result.success, producedReply);
+                // Post-turn sweep (issues #2/#6): on a successful USER turn, enqueue a
+                // coalesced/debounced curation sweep. Out of band — never blocks or breaks
+                // chat, and can't recurse (the sweep uses a separate agent triggered off
+                // the user-chat path). Turn success is the ONLY gate: every workspace is
+                // swept, the root included (`sweeper-_root`).
+                // T5: routed through the `afterTurn` event so the folded-in `curate-overview`
+                // trigger is the single dispatch (no double-curation).
+                if (effectiveSuccess)
+                    emitAfterTurn(slug, result.sessionId ?? resolvedSession ?? null);
+                // Force a session-list refresh so a brand-new chat surfaces immediately
+                // (rather than waiting out the discovery cache). Non-fatal.
+                try {
+                    deps.herdctl.invalidateSessions(agentName);
+                }
+                catch {
+                    /* non-fatal: stale-by-30s at worst */
+                }
+                // Surface the model + usage so the UI can render the context meter.
+                // Omit both if no usage was observed this turn (§7).
+                const completeModel = seen.model ?? effectiveModel;
+                const seenUsage = resolveTurnUsage(seen);
+                const completeUsage = seenUsage
+                    ? {
+                        inputTokens: seenUsage.inputTokens,
+                        outputTokens: seenUsage.outputTokens,
+                        cacheReadTokens: seenUsage.cacheReadTokens,
+                        cacheCreationTokens: seenUsage.cacheCreationTokens,
+                        contextTokens: seenUsage.inputTokens +
+                            seenUsage.cacheReadTokens +
+                            seenUsage.cacheCreationTokens,
+                        contextLimit: getContextLimit(completeModel),
+                    }
+                    : undefined;
+                // Ensure the turn is keyed under its final session id before the terminal
+                // frame, so a client re-attaching right at the end gets the completion.
+                const finalSession = effectiveSuccess ? (result.sessionId ?? resolvedSession) : resolvedSession;
+                if (finalSession)
+                    turn.setSession(finalSession);
+                // #329: a turn that failed WITHOUT a terminal error `result` reaching the
+                // stream (a thrown/rejected drive: network reset, process crash) never hit
+                // noticeFromMessage. Surface it inline so the failure is visible — before
+                // chat:complete flips streaming off (deduped against any notice already sent).
+                if (!result.success)
+                    emitNotice(errorNotice(result.error?.message));
+                turn.emit({
+                    type: "chat:complete",
+                    payload: {
+                        ...routing(),
+                        sessionId: finalSession,
+                        jobId: result.jobId ?? jobId,
+                        success: result.success,
+                        error: result.error?.message,
+                        ...(completeUsage ? { model: completeModel, usage: completeUsage } : {}),
+                    },
+                });
+                turn.end();
+                // After a SUCCESSFUL turn, auto-send any queued follow-up (#197/#245). A
+                // Stop/failed turn holds the queue for the user (no drain). drainQueue owns
+                // the take + client notify + next-turn kickoff, shared with the idle path.
+                if (effectiveSuccess && finalSession) {
+                    await drainQueue(slug, finalSession);
+                }
+                // Layer 3 (issue #301): arm a post-turn recovery watch for a session-mode
+                // keeper turn. If this turn launched a background task that the runtime kills
+                // at the turn boundary (herdctl#374) and the keeper doesn't wake on its own,
+                // the engine auto-injects the recovery nudge — gated on the resolved
+                // `recovery.autoReDrive` (default OFF), a debounce window, and a retry cap.
+                if (effectiveSuccess && finalSession && driveMode === "session") {
+                    recoveryEngine.armWatch({ slug, sessionId: finalSession });
+                }
+            }
+            catch (err) {
+                const error = err instanceof Error ? err.message : String(err);
+                // The origin socket always gets the plain chat:error (its shape predates
+                // the hub and existing clients/tests rely on it). If the turn had already
+                // resolved a session, ALSO emit a terminal chat:complete through the hub
+                // so a client that re-attached after a mid-turn socket drop stops showing
+                // "streaming" instead of hanging with no terminal frame.
+                send({ type: "chat:error", payload: { projectSlug: slug, error } });
+                if (resolvedSession) {
+                    // #329: also surface the failure as an inline notice on the hub so a
+                    // re-attached client renders WHY the turn died (not just the origin
+                    // socket's chat:error toast).
+                    emitNotice(errorNotice(error));
+                    turn.emit({
+                        type: "chat:complete",
+                        payload: { ...routing(), success: false, error },
+                    });
+                }
+                turn.end();
+            }
+        };
+        /**
+         * Handle a slash command (`chat:command`) by driving herdctl's streaming
+         * session. Output is streamed back over the same events as a normal turn;
+         * a `compact_boundary` is surfaced as a synthetic assistant note so the UI
+         * shows a visible confirmation, and post-command usage refreshes the meter.
+         */
+        const onChatCommand = async (msg) => {
+            const slug = msg.payload.projectSlug;
+            const { command, sessionId } = msg.payload;
+            let resolvedSession = sessionId ?? null;
+            const seen = initTurnUsage();
+            // Same hub-tracked turn as onChatSend so a slash-command turn also survives
+            // a mid-turn socket drop (issue #54). A command always targets an existing
+            // session, so it's re-attachable from its first frame.
+            const turn = hub.startTurn(slug, socket, sessionId ?? null);
+            const routing = () => ({
+                projectSlug: slug,
+                sessionId: resolvedSession,
+                jobId: null,
+            });
+            // #429: sub-agent launches recovered live from the tool_use input (a command
+            // like a custom slash-command can still spawn a Task/Agent), keyed by toolUseId.
+            const subagentLaunches = new Map();
+            const translate = createSDKMessageHandler({
+                onText: (chunk) => {
+                    if (chunk)
+                        turn.emit({ type: "chat:response", payload: { ...routing(), chunk } });
+                },
+                onBoundary: () => {
+                    turn.emit({ type: "chat:message_boundary", payload: routing() });
+                },
+                onToolStart: (start) => {
+                    turn.emit({
+                        type: "chat:tool_start",
+                        payload: {
+                            ...routing(),
+                            toolName: start.toolName,
+                            inputSummary: start.inputSummary,
+                            toolUseId: start.toolUseId,
+                            parentToolUseId: start.parentToolUseId,
+                            ...subagentLaunchFields(subagentLaunches, start.toolName, start.toolUseId),
+                        },
+                    });
+                },
+                onToolCall: (call) => {
+                    turn.emit({
+                        type: "chat:tool_call",
+                        payload: {
+                            ...routing(),
+                            toolName: call.toolName,
+                            inputSummary: call.inputSummary,
+                            output: call.output,
+                            isError: call.isError,
+                            durationMs: call.durationMs,
+                            toolUseId: call.toolUseId,
+                            ...subagentLaunchFields(subagentLaunches, call.toolName, call.toolUseId),
+                        },
+                    });
+                },
+            });
+            try {
+                // Commands need an existing chat to act on; the slug resolves to its
+                // project's keeper (verifying the project exists).
+                await deps.projects.get(slug); // throws if the project is unknown
+                const agentName = keeperAgentName(slug);
+                const { sessionId: finalSession } = await deps.herdctl.runCommand(agentName, {
+                    command,
+                    resume: resolvedSession,
+                    onMessage: async (m) => {
+                        // A slash-command turn can spawn a Task too; its nested steps never
+                        // render top-level ({@link isSidechainMessage}).
+                        if (isSidechainMessage(m))
+                            return;
+                        if (m.session_id) {
+                            resolvedSession = m.session_id;
+                            turn.setSession(m.session_id);
+                        }
+                        // Keep the largest context snapshot from assistant blocks (issue #165);
+                        // the terminal `result` block's CUMULATIVE usage is stashed separately
+                        // so it can't inflate the live context meter (#398).
+                        foldTurnUsage(seen, m);
+                        // Surface a compaction as a visible assistant note (the SDK reports
+                        // it as a system/compact_boundary, which the text translator skips).
+                        if (m.type === "system" && m.subtype === "compact_boundary") {
+                            const pre = m.compact_metadata?.pre_tokens;
+                            const detail = typeof pre === "number" ? ` (was ${pre.toLocaleString()} tokens)` : "";
+                            turn.emit({
+                                type: "chat:response",
+                                payload: { ...routing(), chunk: `🗜️ Context compacted${detail}.` },
+                            });
+                            turn.emit({ type: "chat:message_boundary", payload: routing() });
+                            return;
+                        }
+                        // Surface a client-local command's output (`/context`, `/usage`, …). CC
+                        // returns it as a `model:"<synthetic>"` assistant message the translator
+                        // drops as a placeholder (and, on disk, a `system`/`local_command` entry
+                        // the history parser drops), so re-emit its text as an assistant note
+                        // (issue #158) instead of the turn reading as a silent no-op. Trivial
+                        // placeholders (e.g. `/compact`'s "No response requested.") are filtered out.
+                        const localOut = extractLocalCommandOutput(m);
+                        if (localOut) {
+                            turn.emit({ type: "chat:response", payload: { ...routing(), chunk: localOut } });
+                            turn.emit({ type: "chat:message_boundary", payload: routing() });
+                            return;
+                        }
+                        // #429: recover any Task/Agent launch before translate fires onToolStart.
+                        for (const l of extractSubagentLaunches(m))
+                            subagentLaunches.set(l.toolUseId, l);
+                        await translate(m);
+                    },
+                });
+                if (finalSession)
+                    resolvedSession = finalSession;
+                // Refresh the session list (a command can change history) — non-fatal.
+                try {
+                    deps.herdctl.invalidateSessions(agentName);
+                }
+                catch {
+                    /* non-fatal */
+                }
+                const completeModel = seen.model ?? DEFAULT_MODEL;
+                const seenUsage = resolveTurnUsage(seen);
+                const completeUsage = seenUsage
+                    ? {
+                        inputTokens: seenUsage.inputTokens,
+                        outputTokens: seenUsage.outputTokens,
+                        cacheReadTokens: seenUsage.cacheReadTokens,
+                        cacheCreationTokens: seenUsage.cacheCreationTokens,
+                        contextTokens: seenUsage.inputTokens + seenUsage.cacheReadTokens + seenUsage.cacheCreationTokens,
+                        contextLimit: getContextLimit(completeModel),
+                    }
+                    : undefined;
+                if (resolvedSession)
+                    turn.setSession(resolvedSession);
+                turn.emit({
+                    type: "chat:complete",
+                    payload: {
+                        ...routing(),
+                        success: true,
+                        ...(completeUsage ? { model: completeModel, usage: completeUsage } : {}),
+                    },
+                });
+                turn.end();
+            }
+            catch (err) {
+                const error = err instanceof Error ? err.message : String(err);
+                send({ type: "chat:error", payload: { projectSlug: slug, error } });
+                if (resolvedSession) {
+                    turn.emit({ type: "chat:complete", payload: { ...routing(), success: false, error } });
+                }
+                turn.end();
+            }
+        };
+    };
+    // The socket handler PLUS the manual trigger-fire entrypoint: a "trigger now"
+    // action fires a schedule-type trigger on demand through the exact same hub path a
+    // cron fire uses, so the resulting chat is indistinguishable from a scheduled one.
+    //
+    // `managementOpsContext` (#312 M1) completes the hoist: it is the SAME shared
+    // context the in-process self-MCP is built from (deps + hub + startAgentTurn +
+    // composePreloadedPrompt + fireTrigger), handed out so a NON-socket caller can
+    // build the management ops for itself — the `/mcp` transport in M2, and the
+    // turn-spawning REST endpoints in #465. Exposing the CONTEXT rather than a
+    // pre-built ops bag is deliberate: ops are built PER CALLER, because they close
+    // over that caller's project/session/provenance and its policy principal.
+    return { handle, fireTrigger, managementOpsContext: selfMcpCtx };
+}