glm-coding-router 1.1.2 → 2.1.0

package/dist/events/claude-adapter.js

@@ -0,0 +1,416 @@
+import { logger, redact } from "../core/logging.js";
+/**
+ * Claude Code `--output-format stream-json` adapter (specs/v2-architecture.md,
+ * Phase A).
+ *
+ * Maps NDJSON stdout lines — and retry-looking stderr lines — onto the
+ * canonical event model as UNSTAMPED `EventInput[]`: the bus is the only
+ * authority for `runId`/`taskId`/`provider`/`role`/`seq`/`ts`, so a producer
+ * physically cannot forge a sequence number.
+ *
+ * The stream-json schema is not a stable public API (A0), so the mapper is
+ * defensive by construction: any unrecognized `type`, missing field or wrong
+ * shape yields zero events plus one debug log — never a throw. A malformed
+ * line must not kill a run; that is the single most important property of
+ * this file, and even an adapter bug degrades the same way (see the
+ * try/catch in {@link adaptClaudeMessage}).
+ */
+/** The only tool detail allowed past this boundary (contract C3). */
+const SUMMARY_MAX_CHARS = 120;
+/**
+ * 83–88% of stream lines are `thinking_tokens` counters (A0). One Heartbeat
+ * per second is the cap that keeps `events.jsonl` from being ~85% counter
+ * spam while still proving the run is alive.
+ */
+const HEARTBEAT_MIN_INTERVAL_MS = 1000;
+/**
+ * A command counts as validation only when a runner starts one of its
+ * segments. The pattern used to match anywhere in the string, so
+ * `ls eslint.config.* vitest.config.*` was reported as a test run purely
+ * because a FILENAME contained "vitest" (seen live on 2026-09-20).
+ */
+const VALIDATION_SEGMENT = /^(npm|pnpm|yarn) (run )?(test|lint|typecheck)\b|^npx \s*(vitest|jest)\b|^(vitest|jest|pytest|tsc)\b|^go test\b|^cargo test\b|^python3? (-m (pytest|unittest)\b|\S*test\S*\.py)/;
+/** Shell operators that separate one executed command from the next. */
+const SEGMENT_SPLIT = /&&|\|\||;|\|/;
+/** True when any segment of the command line starts with a test/lint runner. */
+function isValidationCommand(command) {
+    return command
+        .split(SEGMENT_SPLIT)
+        .some((segment) => VALIDATION_SEGMENT.test(segment.trim()));
+}
+/** Tools whose ok completion changes a file, and therefore emits `FileChanged`. */
+const FILE_TOOLS = new Set(["Edit", "Write", "MultiEdit"]);
+/**
+ * Matched explicitly, never loosely: stderr also carries structured
+ * diagnostics such as `[claude-code:unrecognized_model] {"model":…}` on
+ * perfectly successful runs, and classifying those as retries would corrupt
+ * the retry counters the estimator feeds on (A0).
+ */
+const RETRY_LINE = /\bretr(?:y|ying|ies)\b|\brate[ _-]?limit|\boverload|too many requests|service unavailable|api error:?\s*\b(?:429|500|502|503|504|529)\b/i;
+/**
+ * The adapter is I/O-free, so it has no secret list of its own to strip.
+ * Summaries still pass through `redact()` so the boundary exists here — when
+ * the spawn path (Phase D) can thread real secrets in, this is the one place
+ * they apply.
+ */
+const NO_SECRETS = [];
+export function createAdapterState(cwd) {
+    return {
+        turn: 0,
+        pending: new Map(),
+        // 0 means "never beaten": any wall clock is already past it, so the first
+        // counter line of a run establishes liveness immediately.
+        lastHeartbeatMs: 0,
+        cwd,
+        sawResultSinceLastToolUse: false,
+        filesChanged: new Set(),
+    };
+}
+/**
+ * Pure: same input + state produces the same events. Mutates `state` (that is
+ * its job — pending tools, turn counter, heartbeat throttle), but touches no
+ * clock, file or network besides the injected `now`.
+ */
+export function adaptClaudeMessage(raw, state, now) {
+    try {
+        return mapMessage(raw, state, now ?? Date.now);
+    }
+    catch (error) {
+        // The mappers below already shape-check everything; this catch is for
+        // adapter bugs, so the "malformed line must not kill a run" property
+        // holds even when the bug is ours.
+        const message = error instanceof Error ? error.message : String(error);
+        logger.debug(`claude-adapter: dropping message that failed to map: ${message}`);
+        return [];
+    }
+}
+/**
+ * Wraps the pure mapper with NDJSON line buffering (partial chunks, `\r\n`,
+ * blank lines) and the stderr retry sink. One adapter instance per run: the
+ * buffered tail and the state it carries are per-stream.
+ */
+export function createStreamAdapter(cwd, deps) {
+    const state = createAdapterState(cwd);
+    const now = deps?.now;
+    let buffered = "";
+    const consumeLine = (line) => {
+        const trimmed = line.replace(/\r$/, "").trim();
+        if (trimmed === "") {
+            return [];
+        }
+        try {
+            return adaptClaudeMessage(JSON.parse(trimmed), state, now);
+        }
+        catch {
+            logger.debug("claude-adapter: stdout line is not valid JSON");
+            return [];
+        }
+    };
+    return {
+        onStdoutLine(line) {
+            return consumeLine(line);
+        },
+        // Only `\n`-terminated lines are consumed — the `\r` of a `\r\n` pair
+        // rides along in the line and is stripped — so a JSON object split
+        // across two chunks still parses exactly once, when complete.
+        onStdoutChunk(chunk) {
+            buffered += chunk;
+            const events = [];
+            let newlineAt = buffered.indexOf("\n");
+            while (newlineAt >= 0) {
+                const line = buffered.slice(0, newlineAt);
+                buffered = buffered.slice(newlineAt + 1);
+                events.push(...consumeLine(line));
+                newlineAt = buffered.indexOf("\n");
+            }
+            return events;
+        },
+        onStderrLine(line) {
+            return mapStderrLine(line);
+        },
+    };
+}
+function mapMessage(raw, state, now) {
+    if (!isRecord(raw)) {
+        logger.debug("claude-adapter: ignoring non-object stream line");
+        return [];
+    }
+    switch (raw.type) {
+        case "system":
+            return mapSystemMessage(raw, state, now);
+        case "assistant":
+            return mapAssistantMessage(raw, state, now);
+        case "user":
+            return mapUserMessage(raw, state, now);
+        case "result":
+            return mapResultMessage(raw, state);
+        default:
+            logger.debug(`claude-adapter: unrecognized stream message type ${JSON.stringify(raw.type)}`);
+            return [];
+    }
+}
+function mapSystemMessage(raw, state, now) {
+    switch (raw.subtype) {
+        case "init":
+            return mapInit(raw, state);
+        case "thinking_tokens":
+            return mapThinkingTokens(state, now);
+        case "permission_denied":
+            return mapPermissionDenied(raw, state);
+        // User hooks fire inside the stream (A0); they are neither tool activity
+        // nor errors, so they are recognized and dropped without a log line.
+        case "hook_started":
+        case "hook_response":
+            return [];
+        default:
+            logger.debug(`claude-adapter: unrecognized system subtype ${JSON.stringify(raw.subtype)}`);
+            return [];
+    }
+}
+function mapInit(raw, state) {
+    const sessionId = asString(raw.session_id);
+    const model = asString(raw.model);
+    if (sessionId === undefined || model === undefined) {
+        logger.debug("claude-adapter: system/init missing session_id or model");
+        return [];
+    }
+    state.sessionId = sessionId;
+    const tools = Array.isArray(raw.tools)
+        ? raw.tools.filter((tool) => typeof tool === "string")
+        : [];
+    return [{ type: "AgentInitialized", sessionId, model, tools }];
+}
+function mapThinkingTokens(state, now) {
+    const at = now();
+    if (at - state.lastHeartbeatMs < HEARTBEAT_MIN_INTERVAL_MS) {
+        return [];
+    }
+    state.lastHeartbeatMs = at;
+    return [{ type: "Heartbeat", state: "working", turn: state.turn }];
+}
+function mapPermissionDenied(raw, state) {
+    const toolUseId = asString(raw.tool_use_id);
+    const tool = asString(raw.tool_name);
+    const reason = asString(raw.decision_reason) ?? asString(raw.message);
+    if (toolUseId === undefined || tool === undefined || reason === undefined) {
+        logger.debug("claude-adapter: system/permission_denied missing tool_use_id, tool_name or reason");
+        return [];
+    }
+    // The denied tool never ran: drop the pending entry so the error
+    // tool_result that follows maps to nothing instead of a bogus ToolCompleted.
+    state.pending.delete(toolUseId);
+    return [{ type: "ToolDenied", turn: state.turn, toolUseId, tool, reason: sanitize(reason) }];
+}
+function mapAssistantMessage(raw, state, now) {
+    const message = raw.message;
+    if (!isRecord(message) || !Array.isArray(message.content)) {
+        logger.debug("claude-adapter: assistant message without a content array");
+        return [];
+    }
+    const events = [];
+    for (const block of message.content) {
+        if (!isRecord(block)) {
+            continue;
+        }
+        switch (block.type) {
+            // Raw model reasoning: dropped at the boundary, never summarized,
+            // never persisted (contract C3, A0).
+            case "thinking":
+                break;
+            // Final answer text is the spawn path's business (stdout, contract C1);
+            // no event ever carries an LLM response body.
+            case "text":
+                break;
+            case "tool_use":
+                events.push(...mapToolUse(block, state, now));
+                break;
+            default:
+                logger.debug(`claude-adapter: unrecognized assistant content block ${JSON.stringify(block.type)}`);
+                break;
+        }
+    }
+    return events;
+}
+function mapToolUse(block, state, now) {
+    const toolUseId = asString(block.id);
+    const tool = asString(block.name);
+    if (toolUseId === undefined || tool === undefined) {
+        logger.debug("claude-adapter: tool_use block without id or name");
+        return [];
+    }
+    const input = isRecord(block.input) ? block.input : {};
+    const command = asString(input.command);
+    const summary = summarizeToolUse(tool, input, state.cwd);
+    const isValidation = tool === "Bash" && command !== undefined && isValidationCommand(command);
+    const events = [];
+    // Turn derivation (A0): one turn per tool_result → next tool_use cycle.
+    // A TurnStarted per assistant message would roughly double every count,
+    // because the stream emits thinking / tool_use / text as separate messages.
+    if (state.turn === 0 || state.sawResultSinceLastToolUse) {
+        state.turn += 1;
+        state.sawResultSinceLastToolUse = false;
+        events.push({ type: "TurnStarted", turn: state.turn });
+    }
+    if (isValidation) {
+        events.push({ type: "ValidationStarted", turn: state.turn, command: summary });
+    }
+    events.push({ type: "ToolStarted", turn: state.turn, toolUseId, tool, summary });
+    state.pending.set(toolUseId, { tool, summary, startedMs: now(), isValidation, turn: state.turn });
+    return events;
+}
+function mapUserMessage(raw, state, now) {
+    const message = raw.message;
+    if (!isRecord(message) || !Array.isArray(message.content)) {
+        logger.debug("claude-adapter: user message without a content array");
+        return [];
+    }
+    const events = [];
+    for (const block of message.content) {
+        if (!isRecord(block) || block.type !== "tool_result") {
+            continue;
+        }
+        // Any tool_result closes a turn's tool cycle — even one with no matching
+        // pending entry — so the next tool_use still opens a new turn.
+        state.sawResultSinceLastToolUse = true;
+        events.push(...mapToolResult(block, state, now));
+    }
+    return events;
+}
+function mapToolResult(block, state, now) {
+    const toolUseId = asString(block.tool_use_id);
+    if (toolUseId === undefined) {
+        logger.debug("claude-adapter: tool_result block without tool_use_id");
+        return [];
+    }
+    const pending = state.pending.get(toolUseId);
+    if (pending === undefined) {
+        // Expected right after a permission_denied dropped the entry, or on
+        // schema drift; either way there is nothing truthful to report.
+        logger.debug(`claude-adapter: tool_result for unknown tool_use_id ${toolUseId}`);
+        return [];
+    }
+    state.pending.delete(toolUseId);
+    const ok = block.is_error !== true;
+    const durationMs = Math.max(0, now() - pending.startedMs);
+    const events = [
+        { type: "ToolCompleted", turn: pending.turn, toolUseId, tool: pending.tool, ok, durationMs },
+    ];
+    if (pending.isValidation) {
+        events.push({ type: "ValidationCompleted", turn: pending.turn, command: pending.summary, ok, durationMs });
+    }
+    if (ok && FILE_TOOLS.has(pending.tool)) {
+        // The summary for these tools *is* the repo-relative path, which is why
+        // PendingTool needs no copy of the raw input (C3).
+        events.push({
+            type: "FileChanged",
+            turn: pending.turn,
+            path: pending.summary,
+            op: pending.tool === "Write" ? "write" : "edit",
+        });
+        state.filesChanged.add(pending.summary);
+    }
+    return events;
+}
+function mapResultMessage(raw, state) {
+    if (raw.subtype === "success") {
+        const turns = asFiniteNumber(raw.num_turns);
+        const durationMs = asFiniteNumber(raw.duration_ms);
+        if (turns === undefined || durationMs === undefined) {
+            logger.debug("claude-adapter: success result missing num_turns or duration_ms");
+            return [];
+        }
+        const usage = isRecord(raw.usage) ? raw.usage : {};
+        // Token counts are real (they come from the API response).
+        // `total_cost_usd` / `modelUsage[].costUSD` are deliberately never read:
+        // Claude Code computes them with Anthropic's price table for a model it
+        // does not know, so for this stack they are fiction (A0). GLM bills in
+        // plan credits; the quota delta stays the only cost truth.
+        return [
+            {
+                type: "RunCompleted",
+                turns,
+                durationMs,
+                filesChanged: state.filesChanged.size,
+                tokensIn: asFiniteNumber(usage.input_tokens) ?? 0,
+                tokensOut: asFiniteNumber(usage.output_tokens) ?? 0,
+            },
+        ];
+    }
+    return [
+        {
+            type: "RunFailed",
+            reason: sanitize(asString(raw.terminal_reason) ?? asString(raw.subtype) ?? "unknown"),
+            exitCode: 1,
+        },
+    ];
+}
+function mapStderrLine(line) {
+    const trimmed = line.trim();
+    if (trimmed === "" || !RETRY_LINE.test(trimmed)) {
+        // Everything else is a passthrough diagnostic for the spawn path to
+        // forward, not an event.
+        return [];
+    }
+    const attempt = /\battempt (\d+)\b/i.exec(trimmed);
+    return attempt === null
+        ? [{ type: "ApiRetry", reason: sanitize(trimmed) }]
+        : [{ type: "ApiRetry", attempt: Number(attempt[1]), reason: sanitize(trimmed) }];
+}
+function summarizeToolUse(tool, input, cwd) {
+    let text;
+    switch (tool) {
+        case "Read":
+        case "Edit":
+        case "Write":
+        case "MultiEdit": {
+            const filePath = asString(input.file_path);
+            text = filePath === undefined ? tool : toRepoRelative(filePath, cwd);
+            break;
+        }
+        case "Bash": {
+            const command = asString(input.command);
+            text = command === undefined ? tool : firstLine(command);
+            break;
+        }
+        case "Grep":
+        case "Glob": {
+            const pattern = asString(input.pattern);
+            text = pattern === undefined ? tool : pattern;
+            break;
+        }
+        default:
+            text = tool;
+    }
+    return sanitize(text);
+}
+/**
+ * Repo-relative when the path is under the cwd, untouched otherwise. A plain
+ * prefix check rather than `path.relative`, so the POSIX paths in the
+ * captured fixtures and Windows paths on a live run behave identically and
+ * the adapter stays platform-free.
+ */
+function toRepoRelative(filePath, cwd) {
+    for (const sep of ["/", "\\"]) {
+        const prefix = cwd.endsWith(sep) ? cwd : cwd + sep;
+        if (filePath.startsWith(prefix)) {
+            return filePath.slice(prefix.length);
+        }
+    }
+    return filePath;
+}
+function firstLine(command) {
+    return command.split(/\r?\n/)[0];
+}
+/** Every user-facing string from the adapter is redacted and short (C3). */
+function sanitize(text) {
+    return redact(text, NO_SECRETS).slice(0, SUMMARY_MAX_CHARS);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function asFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}

package/dist/events/types.js

@@ -0,0 +1,9 @@
+/**
+ * The canonical v2 event model (specs/v2-architecture.md, Phase A).
+ *
+ * One discriminated union feeds every v2 consumer — run store, stderr
+ * renderer, checkpoint builder, drain controller — so these shapes are the
+ * contract the whole observability stack is built on. Types only: there is
+ * deliberately no runtime code in this file.
+ */
+export {};

package/dist/handoff/bundle.js

@@ -0,0 +1,203 @@
+import fs from "node:fs";
+import path from "node:path";
+import { logger } from "../core/logging.js";
+import { gitTopLevel, runGit } from "../core/git.js";
+import { atomicWriteFile } from "../project/atomic-write.js";
+import { CHECKPOINT_FILE_NAME, writeCheckpoint } from "../runs/checkpoint.js";
+/** Where the bundle lands: `<runDir>/handoff/` (doc §17). */
+export const HANDOFF_DIR_NAME = "handoff";
+/** The one provider v2 knows (H2/D5), hardcoded into the H5 handoff block. */
+const ZAI_PROVIDER = "zai.zcode";
+/** H5: v3 §18's cross-provider handoff targets the orchestrator, by name. */
+const ORCHESTRATOR_PROVIDER = "anthropic.claude-code";
+/**
+ * Writes the handoff bundle (doc §17): `checkpoint.json`, `diff.patch`,
+ * `handoff.md`, `handoff.json` under `<runDir>/handoff/`.
+ *
+ * **Never fails the run.** Returns null only when the bundle directory itself
+ * cannot be created; every git call and every file write is individually
+ * guarded, so one degraded section (no diff, no branch, a lost file) becomes a
+ * debug log while the rest of the bundle still reaches disk. The caller prints
+ * the bundle path and carries on regardless — the work on disk is the thing
+ * being rescued here, and it is already safe.
+ *
+ * `diff.patch` is plain `git diff` — tracked changes only, never `git add`
+ * (this repo's no-automatic-git rule is exactly why untracked files get their
+ * own heading in `handoff.md` instead of being staged into the diff). Plain
+ * `git diff` rather than `git diff HEAD` deliberately: the router never stages
+ * anything, and on an unborn HEAD `git diff` still exits 0 where `HEAD` would
+ * fail and needlessly drop the diff section.
+ *
+ * C3: every task-derived string here (title, completed lines, validation
+ * commands, file paths) comes from the checkpoint, whose fields were already
+ * redacted and capped upstream. No prompt body, tool result or LLM response is
+ * ever read, and nothing from the environment is written.
+ */
+export async function writeHandoffBundle(input) {
+    const dir = path.join(input.runDir, HANDOFF_DIR_NAME);
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    catch (error) {
+        logger.debug(`handoff bundle: creating ${dir} failed: ${errorMessage(error)}`);
+        return null;
+    }
+    const handoffMd = path.join(dir, "handoff.md");
+    const handoffJson = path.join(dir, "handoff.json");
+    const checkpointJson = path.join(dir, CHECKPOINT_FILE_NAME);
+    const diffFile = path.join(dir, "diff.patch");
+    const git = input.runGit ?? runGit;
+    const workspace = await workspaceInfo(input.cwd, git);
+    const diff = workspace.isRepo ? await trackedDiff(input.cwd, git) : null;
+    const diffPatch = diff !== null && guardedWrite(diffFile, diff) ? diffFile : null;
+    // Reuses the never-throwing writer so the bundle's copy is byte-identical to
+    // the one the run directory itself may already hold.
+    writeCheckpoint(dir, input.checkpoint);
+    guardedWrite(handoffMd, renderMarkdown(input, workspace, diffPatch !== null));
+    guardedWrite(handoffJson, JSON.stringify({
+        // Doc §18's shape, verbatim in key order...
+        status: "handoff_required",
+        run_id: input.runId,
+        reason: input.reason,
+        completed: input.checkpoint.completed,
+        pending: input.checkpoint.pending,
+        handoff_path: handoffMd,
+        // ...then hedge H5: v3 §17's from/to and v4 §20's workspace block, so
+        // a v2 bundle stays readable by v3/v4 without a migration pass.
+        from: { provider: ZAI_PROVIDER, role: input.role },
+        to: { provider: ORCHESTRATOR_PROVIDER, role: "orchestrator" },
+        workspace: { repo: workspace.repo, worktree: workspace.worktree, branch: workspace.branch },
+        bundle: { checkpoint: checkpointJson, diff: diffPatch, markdown: handoffMd },
+    }, null, 2) + "\n");
+    return { dir, handoffMd, handoffJson, checkpointJson, diffPatch };
+}
+/**
+ * Everything C3 allows a human to read: the title (the checkpoint's first
+ * pending entry), the run id and reason, done/remaining/files/validation from
+ * the checkpoint, and the git facts. Untracked files get their OWN heading
+ * because they are invisible to `diff.patch` — a reader who assumes the patch
+ * is the whole story silently loses them.
+ */
+function renderMarkdown(input, workspace, diffWritten) {
+    const checkpoint = input.checkpoint;
+    const title = checkpoint.pending.length > 0 ? checkpoint.pending[0] : "continue the task";
+    const workspaceLine = workspace.isRepo
+        ? `${workspace.repo ?? "?"} on ${workspace.branch ?? "(detached HEAD)"} — ${workspace.worktree ?? input.cwd}`
+        : "not a git repository";
+    const lines = [
+        `# Handoff: ${title}`,
+        "",
+        `- Run: ${input.runId}`,
+        `- Reason: ${input.reason}`,
+        `- Role: ${input.role} (model ${input.model})`,
+        `- Workspace: ${workspaceLine}`,
+        "",
+        "## Done",
+        ...bullets(checkpoint.completed, "(no completed turns recorded)"),
+        "",
+        "## Remaining",
+        ...bullets(checkpoint.pending, "(nothing recorded — see the run's events)"),
+        "",
+        "## Files changed",
+        ...bullets(checkpoint.filesChanged, "(none)"),
+    ];
+    if (workspace.isRepo) {
+        // The heading is the warning: these files are NOT inside diff.patch.
+        lines.push("", "## Untracked files (not in diff.patch)", ...bullets(workspace.untracked, "(none)"));
+    }
+    lines.push("", "## Validation still owed", ...bullets(checkpoint.validationPending, "(none)"), "", "## Diff");
+    if (!workspace.isRepo) {
+        lines.push("Not a git repository — no `diff.patch` was written.");
+    }
+    else if (!diffWritten) {
+        lines.push("Tracked changes could not be captured — `diff.patch` was not written. Run `git diff` yourself.");
+    }
+    else {
+        lines.push("Tracked changes are in `diff.patch`. Untracked files are the ones listed above, not in the patch.");
+    }
+    lines.push("", "## Next step", "", `Continue the task in the same worktree (\`${input.cwd}\`) — pick up from "Remaining" above instead of re-running the worker from scratch.`, "");
+    return lines.join("\n");
+}
+function bullets(items, empty) {
+    return items.length > 0 ? items.map((item) => `- ${item}`) : [`- ${empty}`];
+}
+/** One guard per git question, so a broken answer degrades alone. */
+async function workspaceInfo(cwd, git) {
+    let topLevel;
+    try {
+        // gitTopLevel rejects (rather than resolving) when git itself is missing,
+        // so even repo detection is inside the guard.
+        topLevel = await gitTopLevel(cwd, git);
+    }
+    catch (error) {
+        logger.debug(`handoff bundle: repo detection in ${cwd} failed: ${errorMessage(error)}`);
+        topLevel = undefined;
+    }
+    if (topLevel === undefined) {
+        return { isRepo: false, repo: null, worktree: null, branch: null, untracked: [] };
+    }
+    const branch = await currentBranch(cwd, git);
+    const untracked = await untrackedFiles(cwd, git);
+    return { isRepo: true, repo: path.basename(topLevel), worktree: topLevel, branch, untracked };
+}
+async function currentBranch(cwd, git) {
+    try {
+        const result = await git(["branch", "--show-current"], cwd);
+        if (result.code !== 0) {
+            logger.debug(`handoff bundle: branch lookup in ${cwd} exited ${result.code}`);
+            return null;
+        }
+        // Empty output is a detached HEAD — truthful as null, not as "".
+        const branch = result.stdout.trim();
+        return branch.length > 0 ? branch : null;
+    }
+    catch (error) {
+        logger.debug(`handoff bundle: branch lookup in ${cwd} failed: ${errorMessage(error)}`);
+        return null;
+    }
+}
+async function untrackedFiles(cwd, git) {
+    try {
+        const result = await git(["status", "--porcelain", "-z"], cwd);
+        if (result.code !== 0) {
+            logger.debug(`handoff bundle: status in ${cwd} exited ${result.code}`);
+            return [];
+        }
+        // -z: NUL-terminated, unquoted — spaces in filenames survive intact.
+        return result.stdout
+            .split("\0")
+            .filter((entry) => entry.startsWith("?? "))
+            .map((entry) => entry.slice(3));
+    }
+    catch (error) {
+        logger.debug(`handoff bundle: status in ${cwd} failed: ${errorMessage(error)}`);
+        return [];
+    }
+}
+async function trackedDiff(cwd, git) {
+    try {
+        const result = await git(["diff"], cwd);
+        if (result.code !== 0) {
+            logger.debug(`handoff bundle: git diff in ${cwd} exited ${result.code}`);
+            return null;
+        }
+        return result.stdout;
+    }
+    catch (error) {
+        logger.debug(`handoff bundle: git diff in ${cwd} failed: ${errorMessage(error)}`);
+        return null;
+    }
+}
+function guardedWrite(file, content) {
+    try {
+        atomicWriteFile(file, content);
+        return true;
+    }
+    catch (error) {
+        logger.debug(`handoff bundle: writing ${file} failed: ${errorMessage(error)}`);
+        return false;
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/handoff/parent-handoff.js

@@ -0,0 +1,48 @@
+import { ExitCode } from "../core/errors.js";
+import { logger } from "../core/logging.js";
+/**
+ * Emit a handoff to the parent session and return its exit code (D2).
+ *
+ * **stdout carries the JSON and nothing else.** Contract C1 reserves stdout
+ * for the run's final answer, and a handed-off run has none — it did not
+ * finish. Printing a partial answer next to the JSON would give an
+ * orchestrator two things to parse and no way to tell which is authoritative,
+ * so the JSON *is* the output of a run that ends this way.
+ *
+ * 41 and 42 differ only in what already happened: 41 is a preflight refusal
+ * that spawned nothing, 42 a live run stopped at a safe boundary with its work
+ * preserved in a bundle. Neither is a crash, which is exactly what the
+ * orchestrator templates now say.
+ */
+export function writeHandoffResult(streams, result, humanSummary, exitCode = ExitCode.HandoffRequired) {
+    streams.stdout.write(JSON.stringify(result) + "\n");
+    try {
+        streams.stderr.write(humanSummary.join("\n") + "\n");
+    }
+    catch (error) {
+        // The machine-readable half already landed; losing the prose must not
+        // change the exit code the parent reads.
+        logger.debug(`parent handoff: writing the human summary failed: ${errorMessage(error)}`);
+    }
+    return exitCode;
+}
+/** The `[Router]` block a human reads on stderr when a live run hands off (doc §14, §18). */
+export function handoffSummaryLines(input) {
+    const lines = [
+        `[Router] handing the task back to the parent session (${input.reason}).`,
+        `[Router] run ${input.runId} stopped at a safe boundary; its work is on disk.`,
+    ];
+    if (input.completed.length > 0) {
+        lines.push("[Router] done so far:", ...input.completed.map((entry) => `[Router]   ${entry}`));
+    }
+    if (input.pending.length > 0) {
+        lines.push("[Router] still to do:", ...input.pending.map((entry) => `[Router]   ${entry}`));
+    }
+    lines.push(input.bundlePath === null
+        ? "[Router] no bundle was written (nothing had changed on disk yet)."
+        : `[Router] bundle: ${input.bundlePath}`, "[Router] continue in the SAME worktree; do not re-run the worker until quota resets.");
+    return lines;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}