@bridge_gpt/mcp-server 0.2.60 → 0.2.65

package/build/executor/required-work-ledger.js

@@ -0,0 +1,1121 @@
+/**
+ * The required-work ledger and closure supervisor (BAPI-1301, D4a, plan Step 5).
+ *
+ * A covered Claude attempt runs with `--input-format stream-json` and its stdin
+ * HELD OPEN, so the CLI stays idle between turns instead of exiting and killing
+ * background work. This module reads that stream line by line and decides two
+ * things from executor-observed lifecycle events only:
+ *
+ *  1. WHEN stdin may be closed (the closure rule), and
+ *  2. WHAT the terminal completion-evidence envelope says (the verdict).
+ *
+ * Why a ledger and not the exit code or the result text: the BAPI-1292 probe
+ * measured that a clean exit and a `result` event both happen while delegated or
+ * background work is still running (or was just killed by CLI teardown). Only
+ * the per-task lifecycle, keyed by the FULL `tool_use_id`, says whether the work
+ * the worker started actually finished.
+ *
+ * Two places deliberately differ from the probe reducer (`reducer-v2.mjs`), on
+ * the user-approved ticket's terms:
+ *  - A REQUIRED task that ended `failed`, `stopped`, or `withdrawn` (the worker
+ *    ran its own `TaskStop`) stays UNRESOLVED. The probe counted a worker
+ *    withdrawal as complete; a worker giving up on required work is not success.
+ *  - A denial links to an obligation only on the exact OPERATION and TARGET (for
+ *    example the prepared branch on `origin`), never on the effect class alone.
+ *
+ * Purity: no I/O, no real timers (the supervisor takes injected timer deps), no
+ * retained prompt, command, argument, URL, or path. Tool inputs and denial
+ * targets are kept only as SHA-256 digests.
+ */
+import { MAX_DENIALS, MAX_EVENT_BYTES, MAX_TASKS, TASK_RESOLVING_STATES, boundEnvelope, boundedIdentifier, deriveCompletionCause, digestStructured, runtimeMatchesSupported, successRefusalReason, COMPLETION_CONTRACT_VERSION, COMPLETION_CONTRACT_VERSION_V2, } from "./completion-contract.js";
+// ---------------------------------------------------------------------------
+// Bounds and small pure helpers
+// ---------------------------------------------------------------------------
+/** Tool-use index bound. Oldest entries are evicted; a denial on an evicted id resolves to `unknown`. */
+export const MAX_TOOL_USE_INDEX = MAX_TASKS * 8;
+/** Resolved (`succeeded`) obligations evicted to make room are remembered this far, for duplicate/contradiction and replacement checks. */
+const MAX_EVICTED = MAX_TASKS * 4;
+const MAX_WORKER_STOPS = MAX_TASKS * 2;
+/**
+ * The digest an obligation's input is identified by, for optional-watcher
+ * matching and exact re-issue replacement.
+ *
+ * BAPI-1301: the top-level `description` is dropped before hashing. It is a
+ * worker-authored label, not the work: a server-owned watcher declaration could
+ * never predict it, and "similar description" must never decide identity. Every
+ * other field (the command, `run_in_background`, the agent prompt) is hashed
+ * exactly, so only a byte-identical re-issue of the same work matches.
+ */
+export function obligationInputDigest(input) {
+    if (input && typeof input === "object" && !Array.isArray(input)) {
+        const { description: _label, ...rest } = input;
+        return digestStructured(rest);
+    }
+    return digestStructured(input ?? null);
+}
+function isRecord(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+/** Real stream-json nests content under `message`; the recorded fixtures flatten it. Accept both. */
+function contentOf(e) {
+    const msg = e["message"];
+    if (isRecord(msg) && "content" in msg)
+        return msg["content"];
+    return e["content"];
+}
+/** A `tool_result` block's text, from either `text` or `content` (string or text blocks). Never retained. */
+function toolResultText(b) {
+    if (typeof b["text"] === "string")
+        return b["text"];
+    const c = b["content"];
+    if (typeof c === "string")
+        return c;
+    if (Array.isArray(c)) {
+        return c
+            .map((x) => (isRecord(x) && typeof x["text"] === "string" ? x["text"] : ""))
+            .join("\n");
+    }
+    return "";
+}
+/** The measured PreToolUse hook denial and permission-denied shapes (reducer-v2 R8). */
+const DENIAL_TEXT_RE = /^PreToolUse:\S+ hook error|permission to use .* (was|has been) denied|denied by/i;
+/**
+ * A minimal, conservative shell-word splitter. Any expansion, substitution,
+ * redirection, compound operator, glob, or escape makes the command
+ * non-structured (null): its target is then unresolved, never guessed.
+ */
+function plainShellWords(cmd) {
+    const words = [];
+    let cur = "";
+    let inWord = false;
+    let i = 0;
+    while (i < cmd.length) {
+        const c = cmd[i];
+        if (c === "'") {
+            const j = cmd.indexOf("'", i + 1);
+            if (j < 0)
+                return null;
+            cur += cmd.slice(i + 1, j);
+            inWord = true;
+            i = j + 1;
+            continue;
+        }
+        if (c === '"') {
+            let j = i + 1;
+            while (j < cmd.length && cmd[j] !== '"') {
+                if (cmd[j] === "$" || cmd[j] === "`" || cmd[j] === "\\")
+                    return null;
+                j++;
+            }
+            if (j >= cmd.length)
+                return null;
+            cur += cmd.slice(i + 1, j);
+            inWord = true;
+            i = j + 1;
+            continue;
+        }
+        if (c === " " || c === "\t") {
+            if (inWord) {
+                words.push(cur);
+                cur = "";
+                inWord = false;
+            }
+            i++;
+            continue;
+        }
+        if (/[;&|<>()$`\\\n\r*?{}[\]~#!]/.test(c))
+            return null;
+        cur += c;
+        inWord = true;
+        i++;
+    }
+    if (inWord)
+        words.push(cur);
+    return words;
+}
+const REF_NAME_RE = /^[A-Za-z0-9._/-]+$/;
+function normalizeRef(ref) {
+    const r = ref.trim();
+    if (!r || r === "HEAD" || !REF_NAME_RE.test(r))
+        return null;
+    return r.startsWith("refs/") ? r : `refs/heads/${r}`;
+}
+function normalizeBranch(name) {
+    let n = name.trim();
+    // `gh pr create --head owner:branch` names the branch after the owner prefix.
+    const colon = n.lastIndexOf(":");
+    if (colon >= 0)
+        n = n.slice(colon + 1);
+    if (n.startsWith("refs/heads/"))
+        n = n.slice("refs/heads/".length);
+    if (!n || n === "HEAD" || !REF_NAME_RE.test(n))
+        return null;
+    return n;
+}
+function normalizeRepository(repo) {
+    let r = repo.trim().toLowerCase();
+    r = r.replace(/^https?:\/\//, "").replace(/\.git$/, "").replace(/^github\.com\//, "");
+    return /^[a-z0-9._-]+\/[a-z0-9._-]+$/.test(r) ? r : null;
+}
+function pushLinkKey(remote, ref) {
+    return digestStructured({ operation: "push", remote, ref });
+}
+function prLinkKey(head, base, repository) {
+    return repository === null
+        ? digestStructured({ operation: "pr_create", head, base })
+        : digestStructured({ operation: "pr_create", head, base, repository });
+}
+const PUSH_TARGET_NEUTRAL_FLAGS = new Set(["-u", "--set-upstream", "--no-verify", "-q", "--quiet"]);
+/** `git push <remote> <refspec>` with at most target-neutral flags; anything else is unresolved. */
+function resolvePushTarget(words) {
+    if (!words || words[0] !== "git" || words[1] !== "push")
+        return null;
+    const positional = [];
+    for (const w of words.slice(2)) {
+        if (w.startsWith("-")) {
+            if (!PUSH_TARGET_NEUTRAL_FLAGS.has(w))
+                return null;
+            continue;
+        }
+        positional.push(w);
+    }
+    // Bare `git push` (or remote-only) pushes an implicit upstream: unresolved.
+    if (positional.length !== 2)
+        return null;
+    const [remote, refspecRaw] = positional;
+    const refspec = refspecRaw.startsWith("+") ? refspecRaw.slice(1) : refspecRaw;
+    const colon = refspec.indexOf(":");
+    let dst;
+    if (colon >= 0) {
+        if (colon === 0)
+            return null; // `:ref` deletes a ref — not the push obligation.
+        dst = refspec.slice(colon + 1);
+    }
+    else {
+        dst = refspec;
+    }
+    const ref = normalizeRef(dst);
+    if (!ref || !remote)
+        return null;
+    return { remote, ref };
+}
+/** `gh pr create` with explicit `--head` and `--base` (and optional `--repo`). */
+function resolvePrTarget(words) {
+    if (!words || words[0] !== "gh" || words[1] !== "pr" || words[2] !== "create")
+        return null;
+    const found = {
+        head: undefined,
+        base: undefined,
+        repo: undefined,
+    };
+    const flagFor = (w) => w === "--head" || w === "-H" ? "head" : w === "--base" || w === "-B" ? "base" : w === "--repo" || w === "-R" ? "repo" : null;
+    for (let i = 3; i < words.length; i++) {
+        const w = words[i];
+        let key = null;
+        let value;
+        const eq = w.indexOf("=");
+        if (w.startsWith("--") && eq > 0) {
+            key = flagFor(w.slice(0, eq));
+            value = w.slice(eq + 1);
+        }
+        else {
+            key = flagFor(w);
+            if (key) {
+                value = words[i + 1];
+                i++;
+            }
+        }
+        if (!key)
+            continue;
+        if (value === undefined || value.startsWith("-"))
+            return null;
+        if (found[key] !== undefined)
+            return null; // repeated flag: ambiguous.
+        found[key] = value;
+    }
+    if (found.head === undefined || found.base === undefined)
+        return null;
+    const head = normalizeBranch(found.head);
+    const base = normalizeBranch(found.base);
+    if (!head || !base)
+        return null;
+    let repository = null;
+    if (found.repo !== undefined) {
+        repository = normalizeRepository(found.repo);
+        if (!repository)
+            return null;
+    }
+    return { head, base, repository };
+}
+/**
+ * Resolve a tool use's denial operation and target from its STRUCTURED input.
+ * The raw command is read here and then discarded; only digests are returned.
+ */
+function resolveDenialOperation(name, input) {
+    if (name === "Agent" || name === "Task")
+        return { operation: "delegate", targetDigest: null, linkKeys: [] };
+    if (name !== "Bash")
+        return { operation: "other", targetDigest: null, linkKeys: [] };
+    const command = isRecord(input) && typeof input["command"] === "string" ? input["command"] : "";
+    const words = plainShellWords(command.trim());
+    if (/\bgit\b[^;&|\n]*?\bpush\b/.test(command)) {
+        const t = resolvePushTarget(words);
+        if (!t)
+            return { operation: "push", targetDigest: null, linkKeys: [] };
+        const key = pushLinkKey(t.remote, t.ref);
+        return { operation: "push", targetDigest: key, linkKeys: [key] };
+    }
+    if (/\bgh\s+pr\s+create\b/.test(command)) {
+        const t = resolvePrTarget(words);
+        if (!t)
+            return { operation: "pr_create", targetDigest: null, linkKeys: [] };
+        const noRepo = prLinkKey(t.head, t.base, null);
+        if (t.repository === null)
+            return { operation: "pr_create", targetDigest: noRepo, linkKeys: [noRepo] };
+        const full = prLinkKey(t.head, t.base, t.repository);
+        // A call naming a repository also satisfies an obligation that declared none.
+        return { operation: "pr_create", targetDigest: full, linkKeys: [full, noRepo] };
+    }
+    if (/\bcurl\b[^|;&\n]*-X\s*(POST|PUT|PATCH|DELETE)\b/i.test(command) ||
+        /\bgh\s+api\b[^|;&\n]*(-X|--method)\s*(POST|PUT|PATCH|DELETE)\b/i.test(command)) {
+        return { operation: "external_mutation", targetDigest: null, linkKeys: [] };
+    }
+    return { operation: "other", targetDigest: null, linkKeys: [] };
+}
+function normalizeObligation(o) {
+    if (o.operation === "push") {
+        const ref = normalizeRef(o.target.ref);
+        const remote = typeof o.target.remote === "string" ? o.target.remote.trim() : "";
+        if (!ref || !remote)
+            return { linkKey: "", satisfactionKey: "", valid: false };
+        const linkKey = pushLinkKey(remote, ref);
+        return {
+            linkKey,
+            satisfactionKey: digestStructured({ linkKey, head: o.target.head ?? null }),
+            valid: true,
+        };
+    }
+    const head = normalizeBranch(o.target.head);
+    const base = normalizeBranch(o.target.base);
+    const repository = o.target.repository === undefined ? null : normalizeRepository(o.target.repository);
+    if (!head || !base || (o.target.repository !== undefined && repository === null)) {
+        return { linkKey: "", satisfactionKey: "", valid: false };
+    }
+    const linkKey = prLinkKey(head, base, repository);
+    return { linkKey, satisfactionKey: linkKey, valid: true };
+}
+const TERMINAL_STATES = new Set([
+    "succeeded",
+    "failed",
+    "stopped",
+    "withdrawn",
+    "conflict",
+]);
+const KNOWN_TASK_STATUSES = new Set(["pending", "running", "completed", "failed", "stopped", "killed"]);
+export function createRequiredWorkLedger(init) {
+    const binding = { ...init.binding };
+    const lifecycleSupported = init.lifecycleSupported === true;
+    const optionalWatchers = (init.optionalWatchers ?? []).slice(0, 16).map((w) => ({ ...w }));
+    // An obligation whose target cannot be normalized links nothing: a denial of
+    // it then reads `unlinked`/`ambiguous`, and unmet finalization still refuses
+    // success on its own, so dropping it can never manufacture a success.
+    const declared = (init.obligations ?? []).slice(0, 8).map(normalizeObligation).filter((d) => d.valid);
+    let sessionId = null;
+    let sawInit = false;
+    const insufficient = new Set();
+    const obligations = new Map();
+    const evicted = new Map();
+    const toolUses = new Map();
+    const workerStops = new Set();
+    const denials = [];
+    let latestSnapshot = null;
+    let materialSeq = 0;
+    let activitySeq = 0;
+    let orderSeq = 0;
+    let resultsSeen = 0;
+    let lastResultSeq = -1;
+    /** No material event since the latest result. */
+    let latestIsResult = false;
+    /** An init/assistant/user turn event arrived after the latest result. */
+    let turnOpen = false;
+    let stdinClosed = false;
+    let streamEnd = null;
+    let processExit = null;
+    const isOptional = (kind, inputDigest) => inputDigest !== null && optionalWatchers.some((w) => w.kind === kind && w.input_digest === inputDigest);
+    // --- obligation tracking --------------------------------------------------
+    /** Evict the oldest resolved obligation to make room. Unresolved obligations are never evicted. */
+    const evictOneResolved = () => {
+        if (evicted.size >= MAX_EVICTED)
+            return false;
+        for (const o of obligations.values()) {
+            if (o.state !== "succeeded")
+                continue;
+            if (latestSnapshot?.includes(o.taskId ?? "\u0000"))
+                continue;
+            evicted.set(o.key, { state: o.state, taskId: o.taskId, kind: o.kind, inputDigest: o.inputDigest, order: o.order });
+            obligations.delete(o.key);
+            return true;
+        }
+        return false;
+    };
+    const track = (key, spec) => {
+        const existing = obligations.get(key);
+        if (existing)
+            return existing;
+        if (evicted.has(key))
+            return null; // already resolved and remembered.
+        if (obligations.size >= MAX_TASKS && !evictOneResolved()) {
+            insufficient.add("ledger_capacity_exhausted");
+            return null;
+        }
+        const o = {
+            key,
+            state: "pending",
+            order: ++orderSeq,
+            ...spec,
+            required: spec.required ?? !isOptional(spec.kind, spec.inputDigest),
+        };
+        obligations.set(key, o);
+        return o;
+    };
+    const findByTaskId = (taskId) => {
+        for (const o of obligations.values())
+            if (o.taskId === taskId && !o.placeholder)
+                return o;
+        return obligations.get(`t:${taskId}`);
+    };
+    /** Apply a terminal state. Identical duplicates are idempotent; a contradiction is `conflict`. */
+    const applyTerminal = (o, next) => {
+        if (!TERMINAL_STATES.has(o.state)) {
+            o.state = next;
+            return "applied";
+        }
+        if (o.state === next || o.state === "conflict")
+            return o.state === "conflict" ? "conflict" : "applied";
+        // A stop (CLI teardown or worker TaskStop) after the task already ended is
+        // measured noise (reducer-v2 R3), not a contradiction of the recorded end.
+        if ((next === "stopped" || next === "withdrawn") && (o.state === "succeeded" || o.state === "failed"))
+            return "applied";
+        // A killed foreground call reports `stopped` and then its own error
+        // tool_result (measured C5k, "Exit code 137"): one ending, not two.
+        if (next === "failed" && (o.state === "stopped" || o.state === "withdrawn"))
+            return "applied";
+        // `stopped` then `withdrawn` for the same stop (task_updated `killed` then a
+        // notification after the worker's TaskStop) describe one event.
+        if ((o.state === "stopped" && next === "withdrawn") || (o.state === "withdrawn" && next === "stopped")) {
+            o.state = "withdrawn";
+            return "applied";
+        }
+        o.state = "conflict";
+        insufficient.add("event_conflict");
+        return "conflict";
+    };
+    /** Fold a placeholder (snapshot-only or orphan terminal keyed by task id) into the real obligation. */
+    const mergePlaceholder = (real, taskId) => {
+        const ph = obligations.get(`t:${taskId}`);
+        if (!ph || ph === real)
+            return "applied";
+        obligations.delete(ph.key);
+        if (TERMINAL_STATES.has(ph.state))
+            return applyTerminal(real, ph.state);
+        return "applied";
+    };
+    const terminalOnEvicted = (key, next) => {
+        const ev = evicted.get(key);
+        if (!ev)
+            return "ignored";
+        if (ev.state === next || next === "stopped" || next === "withdrawn")
+            return "applied";
+        insufficient.add("event_conflict");
+        return "conflict";
+    };
+    // --- denials --------------------------------------------------------------
+    const addDenial = (toolUseId, seq, viaResult) => {
+        const existing = denials.find((d) => d.toolUseId === toolUseId);
+        if (existing) {
+            if (viaResult)
+                existing.viaResult = true;
+            return;
+        }
+        if (denials.length >= MAX_DENIALS) {
+            insufficient.add("denial_capacity_exhausted");
+            return;
+        }
+        const entry = toolUses.get(toolUseId);
+        const resolution = entry
+            ? entry.denial
+            : { operation: "unknown", targetDigest: null, linkKeys: [] };
+        denials.push({ toolUseId, resolution, seq, viaResult });
+    };
+    /** A denied tracked obligation never ran: it is `failed` (and stays unresolved if required). */
+    const failDeniedObligation = (toolUseId) => {
+        const o = obligations.get(toolUseId);
+        if (o)
+            applyTerminal(o, "failed");
+    };
+    // --- event handlers -------------------------------------------------------
+    const onTurnEvent = () => {
+        turnOpen = true;
+        if (stdinClosed)
+            insufficient.add("late_activity_after_close");
+    };
+    const handleInit = (e) => {
+        const sid = boundedIdentifier(e["session_id"]);
+        onTurnEvent();
+        if (!sid) {
+            insufficient.add("event_unknown");
+            return "unknown_shape";
+        }
+        sawInit = true;
+        return "applied";
+    };
+    const handleAssistant = (e) => {
+        onTurnEvent();
+        const content = contentOf(e);
+        if (!Array.isArray(content)) {
+            // A string or absent content carries no tool use; only a non-array object is malformed.
+            if (content === undefined || typeof content === "string")
+                return "applied";
+            insufficient.add("event_unknown");
+            return "unknown_shape";
+        }
+        let outcome = "applied";
+        for (const b of content) {
+            if (!isRecord(b) || b["type"] !== "tool_use")
+                continue;
+            const id = boundedIdentifier(b["id"]);
+            const name = typeof b["name"] === "string" ? b["name"] : null;
+            if (!id || !name) {
+                insufficient.add("event_unknown");
+                outcome = "unknown_shape";
+                continue;
+            }
+            const input = b["input"];
+            const inputDigest = obligationInputDigest(input);
+            // Bounded index; the input itself is dropped here, only digests remain.
+            if (!toolUses.has(id)) {
+                if (toolUses.size >= MAX_TOOL_USE_INDEX) {
+                    const oldest = toolUses.keys().next().value;
+                    if (oldest !== undefined)
+                        toolUses.delete(oldest);
+                }
+                toolUses.set(id, { name, inputDigest, denial: resolveDenialOperation(name, input) });
+            }
+            const bg = isRecord(input) && input["run_in_background"] === true;
+            if (name === "Agent" || name === "Task") {
+                track(id, { toolUseId: id, taskId: null, kind: bg ? "delegate_bg" : "delegate", inputDigest, background: bg, placeholder: false });
+            }
+            else if (name === "Bash" && bg) {
+                track(id, { toolUseId: id, taskId: null, kind: "bash_bg", inputDigest, background: true, placeholder: false });
+            }
+            else if (name === "Monitor") {
+                track(id, { toolUseId: id, taskId: null, kind: "monitor", inputDigest, background: true, placeholder: false });
+            }
+            else if (name === "TaskStop") {
+                // R13: the worker's OWN stop request. It turns a later stop into
+                // `withdrawn` for the record — still unresolved when the task was required.
+                const tid = isRecord(input) ? boundedIdentifier(input["task_id"]) : null;
+                if (tid && workerStops.size < MAX_WORKER_STOPS)
+                    workerStops.add(tid);
+            }
+            // Synchronous foreground Bash and every other tool are exploratory: not
+            // obligations. Their denials are still recorded from the tool_result.
+        }
+        return outcome;
+    };
+    const handleUser = (e, seq) => {
+        onTurnEvent();
+        const content = contentOf(e);
+        if (!Array.isArray(content))
+            return "applied"; // a plain user text message.
+        let outcome = "applied";
+        for (const b of content) {
+            if (!isRecord(b) || b["type"] !== "tool_result")
+                continue;
+            const id = boundedIdentifier(b["tool_use_id"]);
+            if (!id) {
+                insufficient.add("event_unknown");
+                outcome = "unknown_shape";
+                continue;
+            }
+            const isError = b["is_error"] === true;
+            const denied = isError && DENIAL_TEXT_RE.test(toolResultText(b));
+            if (denied) {
+                addDenial(id, seq, false);
+                failDeniedObligation(id);
+                continue;
+            }
+            const o = obligations.get(id);
+            if (!o || o.background)
+                continue; // background: a launch acknowledgement, not a result.
+            const r = applyTerminal(o, isError ? "failed" : "succeeded"); // foreground delegate result.
+            if (r === "conflict")
+                outcome = "conflict";
+        }
+        return outcome;
+    };
+    const handleTaskStarted = (e) => {
+        onTurnEvent();
+        const taskId = boundedIdentifier(e["task_id"]);
+        if (!taskId) {
+            insufficient.add("event_unknown");
+            return "unknown_shape";
+        }
+        const toolUseId = e["tool_use_id"] === undefined || e["tool_use_id"] === null ? null : boundedIdentifier(e["tool_use_id"]);
+        if (e["tool_use_id"] !== undefined && e["tool_use_id"] !== null && !toolUseId) {
+            insufficient.add("event_unknown");
+            return "unknown_shape";
+        }
+        const bg = e["is_backgrounded"] === true;
+        const kind = e["task_type"] === "local_agent" ? (bg ? "delegate_bg" : "delegate") : e["owned_by_subagent"] === true ? "subagent_bash" : "bash_task";
+        if (!toolUseId) {
+            track(`t:${taskId}`, { toolUseId: taskId, taskId, kind, inputDigest: null, background: bg, placeholder: true, required: true });
+            return "applied";
+        }
+        const entry = toolUses.get(toolUseId);
+        const o = track(toolUseId, {
+            toolUseId,
+            taskId,
+            kind,
+            inputDigest: entry?.inputDigest ?? null,
+            background: bg,
+            placeholder: false,
+        });
+        if (!o)
+            return "applied";
+        if (o.taskId !== null && o.taskId !== taskId) {
+            insufficient.add("event_conflict");
+            return "conflict";
+        }
+        o.taskId = taskId;
+        return mergePlaceholder(o, taskId);
+    };
+    const handleTaskTerminal = (e, status) => {
+        const taskId = boundedIdentifier(e["task_id"]);
+        if (!taskId || typeof status !== "string") {
+            insufficient.add("event_unknown");
+            return "unknown_shape";
+        }
+        if (!KNOWN_TASK_STATUSES.has(status)) {
+            insufficient.add("event_unknown");
+            return "unknown_shape";
+        }
+        let next = status === "completed" ? "succeeded" : status === "failed" ? "failed" : status === "stopped" || status === "killed" ? "stopped" : null;
+        if (next === null)
+            return "applied"; // pending/running: non-terminal progress.
+        if (next === "stopped" && workerStops.has(taskId))
+            next = "withdrawn";
+        const rawToolUse = e["tool_use_id"];
+        const toolUseId = rawToolUse === undefined || rawToolUse === null ? null : boundedIdentifier(rawToolUse);
+        if (rawToolUse !== undefined && rawToolUse !== null && !toolUseId) {
+            insufficient.add("event_unknown");
+            return "unknown_shape";
+        }
+        let o;
+        if (toolUseId) {
+            const byTask = findByTaskId(taskId);
+            if (byTask && !byTask.placeholder && byTask.key !== toolUseId) {
+                insufficient.add("event_conflict");
+                return "conflict";
+            }
+            if (evicted.has(toolUseId))
+                return terminalOnEvicted(toolUseId, next);
+            // R4: a terminal without a start is retained, not dropped.
+            o = track(toolUseId, {
+                toolUseId,
+                taskId,
+                kind: "task",
+                inputDigest: toolUses.get(toolUseId)?.inputDigest ?? null,
+                background: true,
+                placeholder: false,
+            });
+            if (!o)
+                return "applied";
+            if (o.taskId === null)
+                o.taskId = taskId;
+            const merged = mergePlaceholder(o, taskId);
+            if (merged === "conflict")
+                return merged;
+        }
+        else {
+            o = findByTaskId(taskId);
+            if (!o) {
+                for (const [k, ev] of evicted)
+                    if (ev.taskId === taskId)
+                        return terminalOnEvicted(k, next);
+                o = track(`t:${taskId}`, { toolUseId: taskId, taskId, kind: "task", inputDigest: null, background: true, placeholder: true, required: true });
+                if (!o)
+                    return "applied";
+            }
+        }
+        return applyTerminal(o, next);
+    };
+    const handleSnapshot = (e) => {
+        const tasks = e["tasks"];
+        if (!Array.isArray(tasks)) {
+            insufficient.add("event_unknown");
+            return "unknown_shape";
+        }
+        const ids = [];
+        let outcome = "applied";
+        for (const t of tasks.slice(0, MAX_TASKS * 2)) {
+            const tid = isRecord(t) ? boundedIdentifier(t["task_id"]) : null;
+            if (!tid) {
+                insufficient.add("event_unknown");
+                outcome = "unknown_shape";
+                continue;
+            }
+            ids.push(tid);
+        }
+        if (tasks.length > MAX_TASKS * 2)
+            insufficient.add("ledger_capacity_exhausted");
+        latestSnapshot = ids; // latest wins.
+        // A task the snapshot lists but no start/tool use explains yet is an
+        // UNKNOWN obligation, required until a lifecycle event resolves it.
+        for (const tid of ids) {
+            if (findByTaskId(tid))
+                continue;
+            let wasEvicted = false;
+            for (const ev of evicted.values())
+                if (ev.taskId === tid)
+                    wasEvicted = true;
+            if (wasEvicted)
+                continue;
+            track(`t:${tid}`, { toolUseId: tid, taskId: tid, kind: "task", inputDigest: null, background: true, placeholder: true, required: true });
+        }
+        return outcome;
+    };
+    const handleResult = (e, seq) => {
+        resultsSeen++;
+        lastResultSeq = seq;
+        turnOpen = false;
+        const pd = e["permission_denials"];
+        if (pd === undefined || pd === null)
+            return "applied";
+        if (!Array.isArray(pd)) {
+            insufficient.add("event_unknown");
+            return "unknown_shape";
+        }
+        let outcome = "applied";
+        for (const d of pd) {
+            const id = isRecord(d) ? boundedIdentifier(d["tool_use_id"]) : null;
+            if (!id) {
+                insufficient.add("event_unknown");
+                outcome = "unknown_shape";
+                continue;
+            }
+            // The result that reports the denial is itself a completed turn after it.
+            addDenial(id, seq, true);
+            failDeniedObligation(id);
+        }
+        return outcome;
+    };
+    const dispatch = (e) => {
+        const type = e["type"];
+        const subtype = e["subtype"];
+        const material = type === "assistant" ||
+            type === "user" ||
+            type === "result" ||
+            (type === "system" &&
+                (subtype === "init" ||
+                    subtype === "task_started" ||
+                    subtype === "task_notification" ||
+                    subtype === "task_updated" ||
+                    subtype === "background_tasks_changed"));
+        if (!material)
+            return "not_material";
+        // Session binding: one session per attempt. A different session id is a
+        // stream that does not belong to this binding.
+        const sidRaw = e["session_id"];
+        if (sidRaw !== undefined && sidRaw !== null) {
+            const sid = boundedIdentifier(sidRaw);
+            if (!sid) {
+                insufficient.add("event_unknown");
+                return "unknown_shape";
+            }
+            if (sessionId === null && type === "system" && subtype === "init")
+                sessionId = sid;
+            else if (sessionId !== null && sid !== sessionId) {
+                insufficient.add("event_conflict");
+                return "conflict";
+            }
+        }
+        const seq = ++materialSeq;
+        latestIsResult = type === "result";
+        if (type === "result")
+            return handleResult(e, seq);
+        if (type === "assistant")
+            return handleAssistant(e);
+        if (type === "user")
+            return handleUser(e, seq);
+        switch (subtype) {
+            case "init":
+                return handleInit(e);
+            case "task_started":
+                return handleTaskStarted(e);
+            case "task_notification":
+                return handleTaskTerminal(e, e["status"]);
+            case "task_updated": {
+                const patch = e["patch"];
+                if (!isRecord(patch)) {
+                    insufficient.add("event_unknown");
+                    return "unknown_shape";
+                }
+                // A patch without a status (end_time, progress) is not a lifecycle change.
+                if (patch["status"] === undefined)
+                    return "applied";
+                return handleTaskTerminal(e, patch["status"]);
+            }
+            case "background_tasks_changed":
+                return handleSnapshot(e);
+            default:
+                return "ignored";
+        }
+    };
+    // --- derived views --------------------------------------------------------
+    const isLive = (o) => o.state === "pending";
+    /** Task ids in the latest snapshot that no terminal lifecycle event has resolved. */
+    const liveSnapshotIds = () => {
+        const required = [];
+        const optional = [];
+        for (const tid of latestSnapshot ?? []) {
+            const o = findByTaskId(tid);
+            if (!o) {
+                let evictedResolved = false;
+                for (const ev of evicted.values())
+                    if (ev.taskId === tid)
+                        evictedResolved = true;
+                if (!evictedResolved)
+                    required.push(tid);
+                continue;
+            }
+            if (!isLive(o))
+                continue;
+            (o.required ? required : optional).push(tid);
+        }
+        return { required, optional };
+    };
+    /** Effective states with exact re-issue replacement applied (never mutates the record). */
+    const effectiveTasks = () => {
+        const all = [...obligations.values()];
+        const succeededLater = (o) => {
+            if (o.inputDigest === null)
+                return false;
+            for (const other of all) {
+                if (other !== o && other.kind === o.kind && other.inputDigest === o.inputDigest && other.state === "succeeded" && other.order > o.order)
+                    return true;
+            }
+            for (const ev of evicted.values()) {
+                if (ev.kind === o.kind && ev.inputDigest === o.inputDigest && ev.state === "succeeded" && ev.order > o.order)
+                    return true;
+            }
+            return false;
+        };
+        return all.map((o) => {
+            // Only a terminal non-success is replaceable: live work is not superseded,
+            // and a `conflict` is contradictory evidence, not a failure to retry.
+            const replaceable = o.state === "failed" || o.state === "stopped" || o.state === "withdrawn";
+            return { o, state: replaceable && succeededLater(o) ? "replaced" : o.state };
+        });
+    };
+    // --- public API -----------------------------------------------------------
+    const ingestLine = (line) => {
+        if (typeof line !== "string" || line.trim().length === 0)
+            return "blank";
+        activitySeq++;
+        if (Buffer.byteLength(line, "utf8") > MAX_EVENT_BYTES) {
+            // Never parsed: an event this large cannot be trusted to be complete.
+            insufficient.add("stream_oversize");
+            latestIsResult = false;
+            return "oversize";
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            insufficient.add("stream_parse_error");
+            latestIsResult = false;
+            return "parse_error";
+        }
+        if (!isRecord(parsed) || typeof parsed["type"] !== "string") {
+            insufficient.add("stream_parse_error");
+            latestIsResult = false;
+            return "parse_error";
+        }
+        try {
+            const r = dispatch(parsed);
+            return r === "not_material" ? "ignored" : r;
+        }
+        catch {
+            // A reducer defect must degrade to "not proven", never to success.
+            insufficient.add("event_unknown");
+            latestIsResult = false;
+            return "unknown_shape";
+        }
+    };
+    const closureState = () => {
+        const liveRequired = [];
+        const liveOptional = [];
+        for (const o of obligations.values()) {
+            if (!isLive(o))
+                continue;
+            if (o.required)
+                liveRequired.push(o.toolUseId);
+            else
+                liveOptional.push(o.taskId ?? o.toolUseId);
+        }
+        const snap = liveSnapshotIds();
+        // A snapshot id whose obligation is already listed (by its tool_use_id or as
+        // a placeholder) is the same work: list it once, not under both handles.
+        for (const tid of snap.required)
+            if (!liveRequired.includes(tid) && !findByTaskId(tid))
+                liveRequired.push(tid);
+        for (const tid of snap.optional)
+            if (!liveOptional.includes(tid))
+                liveOptional.push(tid);
+        const readyToClose = resultsSeen > 0 && latestIsResult && !turnOpen && liveRequired.length === 0 && snap.required.length === 0;
+        return { readyToClose, liveRequired, liveOptional, activitySeq, latestIsResult };
+    };
+    const buildEnvelope = (facts) => {
+        const reasons = new Set(insufficient);
+        if (!lifecycleSupported || !runtimeMatchesSupported(facts.runtime))
+            reasons.add("unsupported_runtime");
+        if (!sawInit || sessionId === null)
+            reasons.add("no_init_event");
+        if (resultsSeen === 0)
+            reasons.add("no_result_turn");
+        else if (turnOpen)
+            reasons.add("active_turn_at_close");
+        if (streamEnd === null || streamEnd === "drain_deadline")
+            reasons.add("stdout_not_read_to_eof");
+        else if (streamEnd === "stream_error")
+            reasons.add("stream_lost");
+        if (processExit === null)
+            reasons.add("no_process_exit");
+        else if (processExit.signal === "SIGKILL")
+            reasons.add("forced_kill_no_cli_teardown");
+        const effective = effectiveTasks();
+        // R6: a required task with no terminal after the stream ended is missing evidence.
+        if (effective.some(({ o, state }) => o.required && state === "pending"))
+            reasons.add("live_required_work");
+        // R6b: a stale snapshot, or a snapshot-only task nothing ever explained.
+        const snap = liveSnapshotIds();
+        const unexplainedPlaceholder = effective.some(({ o, state }) => o.placeholder && state === "pending");
+        if (snap.required.length > 0 || unexplainedPlaceholder)
+            reasons.add("stale_task_snapshot");
+        const sufficient = reasons.size === 0;
+        const unresolvedRequired = effective.some(({ o, state }) => o.required && !TASK_RESOLVING_STATES.has(state));
+        const anyConflict = effective.some(({ state }) => state === "conflict");
+        let execution = unresolvedRequired || anyConflict || snap.required.length > 0 || unexplainedPlaceholder ? "incomplete" : "complete";
+        if (!sufficient && execution === "complete")
+            execution = "unknown";
+        const tasks = effective.slice(0, MAX_TASKS).map(({ o, state }) => ({
+            tool_use_id: o.toolUseId,
+            task_id: o.taskId,
+            kind: o.kind,
+            // A task still pending when the verdict is taken never reached a terminal.
+            state: state === "pending" ? "unknown" : state,
+            required: o.required,
+            input_digest: o.inputDigest,
+        }));
+        const satisfied = new Set((facts.satisfiedObligations ?? [])
+            .map(normalizeObligation)
+            .filter((n) => n.valid)
+            .map((n) => n.satisfactionKey));
+        const denialRows = denials.map((d) => {
+            const { operation, targetDigest, linkKeys } = d.resolution;
+            let state;
+            if (operation === "unknown" || ((operation === "push" || operation === "pr_create") && linkKeys.length === 0)) {
+                // The target cannot be established from structure: it may or may not be
+                // the required effect. Never guessed into blocking or historical.
+                state = "ambiguous";
+            }
+            else {
+                const linked = declared.filter((n) => linkKeys.includes(n.linkKey));
+                if (linked.length === 0)
+                    state = "unlinked";
+                else if (linked.some((n) => !satisfied.has(n.satisfactionKey)))
+                    state = "blocking";
+                else
+                    state = "historical";
+            }
+            return {
+                tool_use_id: d.toolUseId,
+                operation,
+                target_digest: targetDigest,
+                state,
+                result_after_denial: d.viaResult || lastResultSeq > d.seq,
+            };
+        });
+        const candidate = {
+            evidence_version: facts.verificationFacts ? COMPLETION_CONTRACT_VERSION_V2 : COMPLETION_CONTRACT_VERSION,
+            runtime: { ...facts.runtime },
+            binding: { ...binding, final_head_sha: facts.finalHeadSha },
+            session_id: sessionId,
+            evidence: sufficient ? "sufficient" : "insufficient",
+            insufficient_reasons: [...reasons],
+            execution,
+            verification: facts.verification,
+            finalization: facts.finalization,
+            cleanup: { ...facts.cleanup, reasons: [...facts.cleanup.reasons], residual_not_covered: [...facts.cleanup.residual_not_covered] },
+            tasks,
+            denials: denialRows,
+            missing_capabilities: [...facts.missingCapabilities],
+            results_seen: resultsSeen,
+            ...(facts.verificationFacts ? { verification_facts: facts.verificationFacts } : {}),
+        };
+        const withNullCause = { ...candidate, cause: null };
+        const cause = successRefusalReason(withNullCause) === null ? null : deriveCompletionCause(candidate);
+        return boundEnvelope({ ...candidate, cause });
+    };
+    return {
+        ingestLine,
+        closureState,
+        recordStdinClosed: () => {
+            stdinClosed = true;
+        },
+        recordStreamEnd: (outcome) => {
+            // The first non-clean outcome wins; a later clean EOF cannot repair a lost stream.
+            if (streamEnd === null || (streamEnd === "eof" && outcome !== "eof"))
+                streamEnd = outcome;
+        },
+        recordProcessExit: (exit) => {
+            if (processExit === null)
+                processExit = { code: exit.code, signal: exit.signal };
+        },
+        recordTransportFailure: (beforeWork) => {
+            insufficient.add(beforeWork ? "transport_failed_before_work" : "transport_failed_after_progress");
+        },
+        recordAllowanceExhausted: () => {
+            insufficient.add("allowance_exhausted");
+        },
+        recordDeclarationRefused: () => {
+            insufficient.add("declaration_refused");
+        },
+        buildEnvelope,
+    };
+}
+/** The measured settle window after the closure rule first holds (BAPI-1292 C6an-hold2). */
+export const CLOSURE_DEBOUNCE_MS = 1500;
+/**
+ * Hold stdin open until the closure rule holds for a full debounce window, then
+ * close it exactly once.
+ *
+ * Why the debounce: the first probe rule closed stdin the moment a result
+ * arrived and cut off a notification-triggered turn that was about to start.
+ * Every new activity resets the window, and closing is never the verdict: the
+ * caller drains to EOF and the ledger recomputes, so a late turn still
+ * invalidates the apparent closure (`late_activity_after_close`).
+ *
+ * The nudge: at most one, only when a turn ended while ONLY server-declared
+ * optional watchers are live. It is never sent while required work is live and
+ * never asks for a broad stop — cancelling required work is not the executor's
+ * call.
+ */
+export function createClosureSupervisor(opts) {
+    const { ledger, deps } = opts;
+    const debounceMs = opts.debounceMs ?? CLOSURE_DEBOUNCE_MS;
+    let closed = false;
+    let closedReason = null;
+    let nudged = false;
+    let nudgeAwaitingReply = false;
+    let disposed = false;
+    let debounceTimer = null;
+    let armedSeq = -1;
+    let pending = Promise.resolve();
+    const clearDebounce = () => {
+        if (debounceTimer !== null)
+            deps.clearTimer(debounceTimer);
+        debounceTimer = null;
+        armedSeq = -1;
+    };
+    const close = (reason) => {
+        if (closed || disposed)
+            return;
+        closed = true;
+        closedReason = reason;
+        clearDebounce();
+        if (deadlineTimer !== null)
+            deps.clearTimer(deadlineTimer);
+        deadlineTimer = null;
+        ledger.recordStdinClosed();
+        pending = pending.then(async () => {
+            try {
+                await opts.closeStdin();
+            }
+            catch {
+                // A failed close is observed by the caller as a missing EOF; the ledger
+                // then reports `stdout_not_read_to_eof`, never success.
+            }
+        });
+    };
+    let deadlineTimer = deps.setTimer(() => {
+        deadlineTimer = null;
+        close("deadline");
+    }, Math.max(0, opts.deadlineAtMs - deps.now()));
+    const onActivity = () => {
+        if (closed || disposed)
+            return;
+        const s = ledger.closureState();
+        if (armedSeq !== s.activitySeq)
+            clearDebounce();
+        if (!s.latestIsResult) {
+            // The nudge was answered (or other activity began): the next result decides again.
+            nudgeAwaitingReply = false;
+            return;
+        }
+        if (!s.readyToClose)
+            return;
+        if (!nudged && s.liveOptional.length > 0) {
+            nudged = true;
+            nudgeAwaitingReply = true;
+            const line = opts.buildNudge([...s.liveOptional]);
+            pending = pending.then(async () => {
+                let ok = false;
+                try {
+                    ok = (await opts.writeMessage(line)).ok;
+                }
+                catch {
+                    ok = false;
+                }
+                // An undelivered nudge will never be answered: fall back to the rule.
+                if (!ok && !closed && !disposed) {
+                    nudgeAwaitingReply = false;
+                    onActivity();
+                }
+            });
+            return;
+        }
+        // While the worker has a delivered nudge to answer, do not close under it;
+        // the absolute deadline still bounds the wait.
+        if (nudgeAwaitingReply)
+            return;
+        if (debounceTimer !== null)
+            return;
+        armedSeq = s.activitySeq;
+        const seqAtArm = s.activitySeq;
+        debounceTimer = deps.setTimer(() => {
+            debounceTimer = null;
+            armedSeq = -1;
+            if (closed || disposed)
+                return;
+            const now = ledger.closureState();
+            if (now.readyToClose && now.activitySeq === seqAtArm)
+                close("rule");
+        }, debounceMs);
+    };
+    return {
+        onActivity,
+        abort: () => close("abort"),
+        state: () => ({ closed, closedReason, nudged }),
+        settled: () => pending,
+        dispose: () => {
+            clearDebounce();
+            if (deadlineTimer !== null)
+                deps.clearTimer(deadlineTimer);
+            deadlineTimer = null;
+            disposed = true;
+        },
+    };
+}