tickmarkr 2.5.6 → 2.5.7

package/dist/run/git.js

@@ -214,11 +214,43 @@ const SHELL_REAP_GRACE_MS = 2000;
 export function shell(cmd, cwd, timeoutMs, login = false, options = {}) {
     const inherited = executionSignal();
     const signal = inherited && options.signal ? AbortSignal.any([inherited, options.signal]) : inherited ?? options.signal;
-    signal?.throwIfAborted();
-    return withCommandLease(cmd, () => executeShell(cmd, cwd, timeoutMs, login, { ...options, signal }));
+    let attribution;
+    let confirmedStart = false;
+    let terminal = false;
+    const begin = (invocation) => {
+        attribution = options.receiptAttribution?.(invocation);
+        confirmedStart = false;
+        terminal = false;
+    };
+    const emit = (receipt) => {
+        if (terminal)
+            return;
+        if (receipt.outcome === "started")
+            confirmedStart = true;
+        else
+            terminal = true;
+        // Observational callbacks must not change process cleanup, retries or cancellation.
+        try {
+            options.onReceipt?.({ ...receipt, confirmedStart, ...(attribution ? { attribution: { ...attribution } } : {}) });
+        }
+        catch { /* receipt sinks are observational */ }
+    };
+    const checkAbort = () => {
+        if (signal?.aborted)
+            emit({ outcome: "cancelled", exitCode: null, signal: null });
+        signal?.throwIfAborted();
+    };
+    begin(1);
+    checkAbort();
+    return withCommandLease(cmd, () => executeShell(cmd, cwd, timeoutMs, login, { ...options, signal }, { begin, emit, checkAbort }))
+        .catch((error) => {
+        if (signal?.aborted)
+            emit({ outcome: "cancelled", exitCode: null, signal: null });
+        throw error;
+    });
 }
-function executeShell(cmd, cwd, timeoutMs, login, options) {
-    options.signal?.throwIfAborted();
+function executeShell(cmd, cwd, timeoutMs, login, options, observation) {
+    observation.checkAbort();
     // OBS-74: scrub tickmarkr's own routing env seams from every child — a daemon carrying
     // TICKMARKR_QUALITY leaked it into baseline/gate/tip-verify children, turning a dogfood
     // repo's route() tests red inside the gates. Scrub a copy at this one choke point so
@@ -245,13 +277,22 @@ function executeShell(cmd, cwd, timeoutMs, login, options) {
         // detached: bash gets its own process group so a timeout can kill the whole tree —
         // SIGKILLing bash alone orphans grandchildren (codex/pi) that hold the stdio pipes
         // open, so "close" never fires and the promise wedges forever (v1.33.1 init hang).
-        const p = (spawnChild ?? spawn)("bash", [login ? "-lc" : "-c", cmd], { cwd, env, stdio: ["ignore", "pipe", "pipe"], detached: true });
+        let p;
+        try {
+            p = (spawnChild ?? spawn)("bash", [login ? "-lc" : "-c", cmd], { cwd, env, stdio: ["ignore", "pipe", "pipe"], detached: true });
+        }
+        catch (error) {
+            observation.emit({ outcome: "spawn-failed", exitCode: null, signal: null, error: String(error) });
+            throw error;
+        }
         let stdout = "", stderr = "";
         const stdoutDecoder = new StringDecoder("utf8");
         const stderrDecoder = new StringDecoder("utf8");
         let timedOut = false, reapedGroup = false, done = false, started = false, outputSeen = false;
         let reapError, exitedCode;
         let signalExit = false;
+        let exitSignal = null;
+        let spawnError;
         let reapTimer;
         let drainTimer;
         const finish = (code, err) => {
@@ -264,6 +305,12 @@ function executeShell(cmd, cwd, timeoutMs, login, options) {
             options.signal?.removeEventListener("abort", abort);
             stdout += stdoutDecoder.end();
             stderr += stderrDecoder.end();
+            observation.emit({
+                outcome: options.signal?.aborted ? "cancelled" : timedOut ? "timed-out" : spawnError ? "spawn-failed" : "completed",
+                pid: p.pid, exitCode: signalExit || spawnError ? null : code,
+                signal: exitSignal, ...(spawnError ? { error: spawnError } : {}),
+                durationMs: Date.now() - startedAt,
+            });
             resolve({
                 code,
                 ...(signalExit ? { signalExit: true } : {}),
@@ -316,7 +363,7 @@ function executeShell(cmd, cwd, timeoutMs, login, options) {
         options.onSpawn?.(p.pid);
         if (options.signal?.aborted)
             abort();
-        p.on("spawn", () => { started = true; }); // the command exists from here on — never retryable past it
+        p.on("spawn", () => { started = true; observation.emit({ outcome: "started", pid: p.pid }); }); // the command exists from here on — never retryable past it
         // OBS-716: one stateful decoder per stream carries an incomplete UTF-8 sequence into that
         // stream's next pipe chunk; decoding each chunk through string concatenation corrupts bytes at
         // kernel-chosen boundaries. A deterministic fixture proves this decoder correct rather than
@@ -333,21 +380,24 @@ function executeShell(cmd, cwd, timeoutMs, login, options) {
             stderr += stderrDecoder.write(d);
         });
         p.on("error", (e) => {
+            spawnError = String(e);
             if (!done && !started && !outputSeen && e.code === RETRYABLE_SPAWN_CODE) {
                 done = true;
                 clearTimeout(timer);
                 options.signal?.removeEventListener("abort", abort);
+                observation.emit({ outcome: "spawn-failed", exitCode: null, signal: null, error: String(e), durationMs: Date.now() - startedAt });
                 resolve({ refused: e });
                 return;
             }
             finish(127, String(e));
         });
-        p.on("close", (code) => { signalExit = code === null; finish(code ?? 1); });
+        p.on("close", (code, signal) => { signalExit = code === null; exitSignal = signal; finish(code ?? 1); });
         // "close" waits for stdio to drain. Once bash exits normally, give descendants a bounded grace
         // to exit with it; a survivor still in bash's detached group is then reaped so its inherited pipe
         // cannot hold this promise until the command ceiling. A real timeout wins first and is never
         // reclassified as a grace reap.
-        p.on("exit", (code) => {
+        p.on("exit", (code, signal) => {
+            exitSignal = signal;
             signalExit = code === null;
             exitedCode = code ?? 1;
             // Allow a short pipe drain after killing, bounded even for an escaped descendant.
@@ -373,7 +423,9 @@ function executeShell(cmd, cwd, timeoutMs, login, options) {
     return (async () => {
         const startedAt = Date.now();
         for (let n = 1;; n++) {
-            options.signal?.throwIfAborted();
+            if (n > 1)
+                observation.begin(n);
+            observation.checkAbort();
             const r = await attempt();
             if (!("refused" in r))
                 return r;
@@ -386,8 +438,8 @@ function executeShell(cmd, cwd, timeoutMs, login, options) {
         }
     })();
 }
-export function sh(cmd, cwd, timeoutMs = DEFAULT_SHELL_TIMEOUT_MS) {
-    return shell(cmd, cwd, timeoutMs, true);
+export function sh(cmd, cwd, timeoutMs = DEFAULT_SHELL_TIMEOUT_MS, options = {}) {
+    return shell(cmd, cwd, timeoutMs, true, options);
 }
 // Git plumbing never needs an operator profile; skip login-shell startup and its side effects.
 export function shGit(cmd, cwd, timeoutMs = DEFAULT_SHELL_TIMEOUT_MS) {

package/dist/run/journal.d.ts

@@ -144,8 +144,11 @@ export declare function pendingRechecks(events: JournalEvent[]): Set<string>;
  * `task-dispatch`: everything between the two — worktree recreation, setup, prompt write, slot
  * allocation, the launch itself — can still die with no worker having read a word, and clearing at
  * task-dispatch meant `--retry-failed` after exactly that death rebuilt the prompt without the gate
- * failures OR the delivery failure that preceded it. `task-approved` also clears (an operator approval
- * retires the findings it settled — the uphold case re-derives its own brief separately).
+ * failures OR the delivery failure that preceded it. Of the approvals, only a WAIVE clears (the operator
+ * retired the findings by fiat — the uphold case re-derives its own brief separately). OBS-1074: a
+ * plain approve, a scope grant or a recheck re-funds an attempt that must still see why the last one
+ * parked, plus the operator's stated reason — v2.5.7's T11 looped four times on one hygiene oracle
+ * because every approval erased exactly the finding the fresh attempt was funded to fix.
  */
 export declare function journaledFailureBrief(events: JournalEvent[], taskId: string): string[];
 /**
@@ -300,6 +303,13 @@ export declare function gateResultJournalData(gate: string, pass: boolean, detai
     signalQuality: number;
 } & Record<string, unknown>;
 export declare function recordedGraphDefinitionHash(events: JournalEvent[]): string | undefined;
+/**
+ * OBS-1073 residual: the `--graph-changed` release belongs to the ENGAGEMENT, not to the launch call. The
+ * daemon writes it on the run-resume row; every replay that runs inside that engagement from another
+ * process (the approve CLI) reads it back here. Without it the first in-run approval after a released
+ * launch re-ran the whole-graph asserts the launch had waived and killed the daemon (v2.5.7 run …152220).
+ */
+export declare function engagementReleased(events: JournalEvent[]): boolean;
 /** An approval is the durable authority; graph.json is only its materialized projection. */
 export declare const ScopeAmendmentSchema: z.ZodObject<{
     from: z.ZodString;
@@ -307,10 +317,16 @@ export declare const ScopeAmendmentSchema: z.ZodObject<{
     beforeFiles: z.ZodArray<z.ZodString>;
     files: z.ZodArray<z.ZodString>;
     parkLine: z.ZodNumber;
+    definition: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
-export declare function replayScopeAmendments(graph: RunGraph, events: JournalEvent[]): RunGraph;
+/**
+ * `release` is the operator's audited `--graph-changed`. `approvedDefinitions` supplies, per amended task,
+ * the definition fingerprint the amendment was granted against when the row itself carries none (rows
+ * older than v2.5.7): the caller reads it from the run's materialized graph snapshot.
+ */
+export declare function replayScopeAmendments(graph: RunGraph, events: JournalEvent[], release?: boolean, approvedDefinitions?: ReadonlyMap<string, string>): RunGraph;
 /** Publish/recover the audit before dispatch, even after a crash between approval and rehash. */
-export declare function applyScopeAmendments(graph: RunGraph, journal: Journal, auditReplay?: boolean): RunGraph;
+export declare function applyScopeAmendments(graph: RunGraph, journal: Journal, auditReplay?: boolean, release?: boolean): RunGraph;
 export type EngagementCompare = {
     comparable: true;
     recorded: string;

package/dist/run/journal.js

@@ -4,7 +4,7 @@ import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from
 import { join } from "node:path";
 import { z } from "zod";
 import { channelKey, shq, TokenUsageSchema } from "../adapters/types.js";
-import { graphDefinitionHash, stateDirName, taskContentDigest, tickmarkrDir } from "../graph/graph.js";
+import { graphDefinitionHash, stateDirName, taskContentDigest, taskDefinitionFingerprint, tickmarkrDir } from "../graph/graph.js";
 import { GATE_NAMES, TIERS } from "../graph/schema.js";
 import { channelRouteIdentity } from "../route/preference.js";
 import { buildProfile, classify } from "../route/profile.js";
@@ -656,16 +656,25 @@ function decisionForNextDispatch(events, taskId, event) {
  * `task-dispatch`: everything between the two — worktree recreation, setup, prompt write, slot
  * allocation, the launch itself — can still die with no worker having read a word, and clearing at
  * task-dispatch meant `--retry-failed` after exactly that death rebuilt the prompt without the gate
- * failures OR the delivery failure that preceded it. `task-approved` also clears (an operator approval
- * retires the findings it settled — the uphold case re-derives its own brief separately).
+ * failures OR the delivery failure that preceded it. Of the approvals, only a WAIVE clears (the operator
+ * retired the findings by fiat — the uphold case re-derives its own brief separately). OBS-1074: a
+ * plain approve, a scope grant or a recheck re-funds an attempt that must still see why the last one
+ * parked, plus the operator's stated reason — v2.5.7's T11 looped four times on one hygiene oracle
+ * because every approval erased exactly the finding the fresh attempt was funded to fix.
  */
 export function journaledFailureBrief(events, taskId) {
     let rows = [];
     for (const e of events) {
         if (e.taskId !== taskId)
             continue;
-        if (e.event === "worker-launch" || e.event === "task-approved")
+        if (e.event === "worker-launch")
             rows = [];
+        else if (e.event === "task-approved") {
+            if (e.data.release === GATE_SATISFIED_RELEASE)
+                rows = [];
+            else if (typeof e.data.reason === "string" && e.data.reason.trim())
+                rows.push(`approval: ${e.data.reason.trim()}`);
+        }
         else if (e.event === "gate-result" && e.data.pass === false && e.data.skipped !== true
             && typeof e.data.details === "string")
             rows.push(`${e.data.gate}: ${e.data.details}`);
@@ -983,12 +992,37 @@ export function recordedGraphDefinitionHash(events) {
     }
     return recorded ?? undefined;
 }
+/**
+ * OBS-1073 residual: the `--graph-changed` release belongs to the ENGAGEMENT, not to the launch call. The
+ * daemon writes it on the run-resume row; every replay that runs inside that engagement from another
+ * process (the approve CLI) reads it back here. Without it the first in-run approval after a released
+ * launch re-ran the whole-graph asserts the launch had waived and killed the daemon (v2.5.7 run …152220).
+ */
+export function engagementReleased(events) {
+    const engagement = events.filter((e) => e.event === "run-start" || e.event === "run-resume").at(-1);
+    return engagement?.data.graphChanged === true;
+}
+/** The run's own graph.json (copied by the daemon at every start/resume) — the definitions the last engagement ran on. */
+function snapshotDefinitions(journal) {
+    const path = join(journal.dir, "graph.json");
+    if (!existsSync(path))
+        return new Map();
+    const snapshot = JSON.parse(readFileSync(path, "utf8"));
+    return new Map((snapshot.tasks ?? []).map((t) => [t.id, taskDefinitionFingerprint(t)]));
+}
 /** An approval is the durable authority; graph.json is only its materialized projection. */
 export const ScopeAmendmentSchema = z.object({
     from: z.string(), to: z.string(), beforeFiles: z.array(z.string()), files: z.array(z.string()),
     parkLine: z.number().int().positive(),
+    /** OBS-1073: the amended task's definition minus files[] at approval; absent on rows older than v2.5.7. */
+    definition: z.string().optional(),
 });
-export function replayScopeAmendments(graph, events) {
+/**
+ * `release` is the operator's audited `--graph-changed`. `approvedDefinitions` supplies, per amended task,
+ * the definition fingerprint the amendment was granted against when the row itself carries none (rows
+ * older than v2.5.7): the caller reads it from the run's materialized graph snapshot.
+ */
+export function replayScopeAmendments(graph, events, release = false, approvedDefinitions = new Map()) {
     const amendments = events.filter((e) => e.event === "task-approved" && e.data.release === "scope-request")
         .map((event) => ({ event, amendment: ScopeAmendmentSchema.parse(event.data.amendment) }));
     if (!amendments.length)
@@ -1007,20 +1041,37 @@ export function replayScopeAmendments(graph, events) {
         }
         result = { ...result, tasks: result.tasks.map((t) => t.id === id ? { ...t, files: original } : t) };
     }
+    // OBS-1073: `from`/`to` bind the WHOLE graph, so a later spec repair of ANOTHER task (a pin-sweep miss
+    // found mid-run, D-57) makes them unmatchable forever and `--graph-changed` — applied only after this
+    // replay — never reaches its own release. Under that audited release the amended task's files[]
+    // recognition above still holds and the caller journals the rehash; only the whole-graph identity
+    // asserts are waived. Without the release nothing changes: fail closed.
     for (const { event, amendment } of amendments) {
-        if (graphDefinitionHash(result) !== amendment.from) {
+        if (release) {
+            // The release waives the WHOLE-GRAPH identity (another task may lawfully have moved), never the
+            // amended task's own definition: goal, acceptance, deps, floor must still be what was approved.
+            const approved = amendment.definition ?? approvedDefinitions.get(event.taskId ?? "");
+            const current = result.tasks.find((t) => t.id === event.taskId);
+            if (approved === undefined || current === undefined) {
+                throw new Error(`refusing scope amendment replay under --graph-changed: no approved definition fingerprint for ${event.taskId}`);
+            }
+            if (taskDefinitionFingerprint(current) !== approved) {
+                throw new Error(`refusing scope amendment replay: ${event.taskId} definition changed beyond the approved amendment (goal, acceptance, deps or routing)`);
+            }
+        }
+        if (!release && graphDefinitionHash(result) !== amendment.from) {
             throw new Error(`refusing scope amendment replay: graph task definition changed beyond approval for ${event.taskId}`);
         }
         result = { ...result, tasks: result.tasks.map((t) => t.id === event.taskId ? { ...t, files: amendment.files } : t) };
-        if (graphDefinitionHash(result) !== amendment.to)
+        if (!release && graphDefinitionHash(result) !== amendment.to)
             throw new Error("refusing invalid scope amendment hash");
     }
     return result;
 }
 /** Publish/recover the audit before dispatch, even after a crash between approval and rehash. */
-export function applyScopeAmendments(graph, journal, auditReplay = false) {
+export function applyScopeAmendments(graph, journal, auditReplay = false, release = false) {
     const events = journal.read();
-    const result = replayScopeAmendments(graph, events); // validate all before moving any identity
+    const result = replayScopeAmendments(graph, events, release, release ? snapshotDefinitions(journal) : new Map()); // validate all before moving any identity
     const approvals = events.filter((e) => e.event === "task-approved" && e.data.release === "scope-request");
     for (const approval of approvals) {
         const amendment = ScopeAmendmentSchema.parse(approval.data.amendment);

package/dist/run/operator-page-summary.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Pure operator-page grouping over the `operator-page` rows the daemon journals (one row per
+ * delivered page, carrying the producer's `suppressed` count). This module consumes that count and
+ * never throttles a second time: it only coalesces EQUIVALENT rows for display while keeping every
+ * source line, both evidence timestamps, and the producer's suppressed count separate from what was
+ * actually observed. Folding is incremental and pure; `fold(fold(empty, a), b)` equals
+ * `fold(empty, [...a, ...b])` and no journal byte is touched.
+ */
+import type { JournalEvent } from "./journal.js";
+export interface OperatorPageRow {
+    /** Source reference (journal line number or any stable locator). */
+    readonly line: number;
+    readonly ts: string;
+    readonly runId: string;
+    readonly taskId: string;
+    /** Current park identity (e.g. park kind + attempt); part of the group key. */
+    readonly park: string;
+    /** Decision state (e.g. blocked / idle / failed / resolved); part of the group key. */
+    readonly status: string;
+    /** Producer-suppressed page count; absent on rows written before suppression metadata existed. */
+    readonly suppressed?: number;
+    readonly blocker?: string;
+    readonly owner?: string;
+    readonly requiredAction?: string;
+    readonly permittedActions?: readonly string[];
+}
+export interface OperatorPageGroup {
+    readonly key: string;
+    readonly runId: string;
+    readonly taskId: string;
+    readonly park: string;
+    readonly status: string;
+    readonly blocker?: string;
+    readonly owner?: string;
+    readonly requiredAction?: string;
+    readonly permittedActions: readonly string[];
+    readonly firstEvidenceAt: string;
+    readonly lastEvidenceAt: string;
+    /** Rows actually present in the journal. */
+    readonly observedCount: number;
+    /** Sum of the producer's `suppressed` counts; never added to observedCount. */
+    readonly suppressedCount: number;
+    /** True when at least one row lacked suppression metadata (pre-metadata journal). */
+    readonly rawOnly: boolean;
+    readonly lines: readonly number[];
+}
+export interface OperatorPageSummary {
+    readonly groups: readonly OperatorPageGroup[];
+}
+export declare const EMPTY_OPERATOR_PAGE_SUMMARY: OperatorPageSummary;
+/** Projects a journal event onto a row; returns undefined for anything that is not an operator page. */
+export declare function operatorPageRow(event: JournalEvent, line: number, runId: string): OperatorPageRow | undefined;
+/** Folds rows into a summary. Pure: returns a new summary, never mutates inputs. */
+export declare function foldOperatorPages(prior: OperatorPageSummary, rows: readonly OperatorPageRow[]): OperatorPageSummary;
+/** Full replay from journal events. */
+export declare function summarizeOperatorPages(events: readonly JournalEvent[], runId: string): OperatorPageSummary;

package/dist/run/operator-page-summary.js

@@ -0,0 +1,68 @@
+export const EMPTY_OPERATOR_PAGE_SUMMARY = { groups: [] };
+const str = (v) => (typeof v === "string" ? v : undefined);
+/** Projects a journal event onto a row; returns undefined for anything that is not an operator page. */
+export function operatorPageRow(event, line, runId) {
+    if (event.event !== "operator-page" || event.taskId === undefined)
+        return undefined;
+    const d = event.data;
+    const permitted = Array.isArray(d.permittedActions) ? d.permittedActions.filter((a) => typeof a === "string") : undefined;
+    return {
+        line, ts: event.ts, runId, taskId: event.taskId,
+        park: str(d.park) ?? `${str(d.slot) ?? ""}#${typeof d.attempt === "number" ? d.attempt : ""}`,
+        status: str(d.status) ?? "unknown",
+        ...(typeof d.suppressed === "number" ? { suppressed: d.suppressed } : {}),
+        ...(str(d.blocker) !== undefined ? { blocker: str(d.blocker) } : {}),
+        ...(str(d.owner) !== undefined ? { owner: str(d.owner) } : {}),
+        ...(str(d.requiredAction) !== undefined ? { requiredAction: str(d.requiredAction) } : {}),
+        ...(permitted !== undefined ? { permittedActions: permitted } : {}),
+    };
+}
+const groupKey = (r) => [r.runId, r.taskId, r.park, r.status].join("\u0000");
+const openKey = (r) => `${r.runId}\u0000${r.taskId}`;
+/** Permitted actions compare as a SET: order and duplicates never open a new group. */
+const actionSet = (a) => [...new Set(a ?? [])].sort().join("\u0000");
+const sameDecision = (g, r) => g.key === groupKey(r)
+    && g.blocker === r.blocker && g.owner === r.owner && g.requiredAction === r.requiredAction
+    && actionSet(g.permittedActions) === actionSet(r.permittedActions);
+/** Folds rows into a summary. Pure: returns a new summary, never mutates inputs. */
+export function foldOperatorPages(prior, rows) {
+    const groups = [...prior.groups];
+    // One open group per run/task: ANY change in park, status or decision closes it, so a later
+    // transition can never merge backward into an earlier group across an intervening change.
+    const open = new Map();
+    groups.forEach((g, i) => open.set(openKey(g), i));
+    for (const row of rows) {
+        const key = groupKey(row);
+        const idx = open.get(openKey(row));
+        const g = idx === undefined ? undefined : groups[idx];
+        if (g !== undefined && sameDecision(g, row)) {
+            groups[idx] = {
+                ...g,
+                firstEvidenceAt: row.ts < g.firstEvidenceAt ? row.ts : g.firstEvidenceAt,
+                lastEvidenceAt: row.ts > g.lastEvidenceAt ? row.ts : g.lastEvidenceAt,
+                observedCount: g.observedCount + 1,
+                suppressedCount: g.suppressedCount + (row.suppressed ?? 0),
+                rawOnly: g.rawOnly || row.suppressed === undefined,
+                lines: [...g.lines, row.line],
+            };
+            continue;
+        }
+        groups.push({
+            key, runId: row.runId, taskId: row.taskId, park: row.park, status: row.status,
+            ...(row.blocker !== undefined ? { blocker: row.blocker } : {}),
+            ...(row.owner !== undefined ? { owner: row.owner } : {}),
+            ...(row.requiredAction !== undefined ? { requiredAction: row.requiredAction } : {}),
+            permittedActions: [...(row.permittedActions ?? [])],
+            firstEvidenceAt: row.ts, lastEvidenceAt: row.ts,
+            observedCount: 1, suppressedCount: row.suppressed ?? 0,
+            rawOnly: row.suppressed === undefined, lines: [row.line],
+        });
+        open.set(openKey(row), groups.length - 1);
+    }
+    return { groups };
+}
+/** Full replay from journal events. */
+export function summarizeOperatorPages(events, runId) {
+    const rows = events.flatMap((e, i) => { const r = operatorPageRow(e, i + 1, runId); return r ? [r] : []; });
+    return foldOperatorPages(EMPTY_OPERATOR_PAGE_SUMMARY, rows);
+}

package/dist/run/operator-summary.d.ts

@@ -0,0 +1,69 @@
+/** Labels describe blockers, not journal park kinds or commands. */
+export declare const BLOCKER_KINDS: readonly ["human-decision", "retry", "cooldown", "dependency-wait", "stale-receipt", "missing-capability", "unknown"];
+export type BlockerKind = (typeof BLOCKER_KINDS)[number];
+/**
+ * Structural boundary: callers compute park with newestPark and verbs with
+ * permittedDecisionVerbs in cli/commands/approve. RunDecision also fits this
+ * shape. This module neither imports a surface nor repeats its decision table.
+ * Supply only current parks, from the same snapshot as the task statuses.
+ */
+export interface OperatorDecisionSnapshot {
+    readonly taskId: string;
+    readonly park: {
+        readonly kind: string | undefined;
+        readonly tombstone: boolean;
+        readonly reason?: string;
+    };
+    readonly verbs: readonly string[];
+    readonly diagnostic?: string;
+}
+export interface RecordedResponsibility {
+    readonly role?: string;
+    readonly agent?: string;
+}
+/**
+ * Current, already-reduced evidence supplied by the reader. Optional facts stay
+ * absent: a wait duration is not a wake timestamp, a channel is not an owner,
+ * and elapsed wall time alone cannot establish that a receipt is stale.
+ */
+export interface OperatorSummaryTask {
+    readonly id: string;
+    readonly status: string;
+    readonly deps: readonly string[];
+    readonly phase?: string;
+    readonly lastEvidenceAt?: string;
+    readonly responsible?: RecordedResponsibility;
+    readonly wait?: {
+        readonly kind: "retry" | "cooldown";
+        readonly wakeAt?: string;
+        readonly diagnostic?: string;
+    };
+    readonly staleReceipt?: {
+        readonly diagnostic: string;
+    };
+    readonly missingCapability?: {
+        readonly capability: string;
+        readonly diagnostic?: string;
+    };
+}
+export interface OperatorBlocker {
+    kind: BlockerKind;
+    permittedActions: string[];
+    humanInterventionRequired: boolean;
+    decisionRequired: boolean;
+    diagnostic?: string;
+    nextAction: string | null;
+    prerequisites?: string[];
+    wakeAt?: string;
+    capability?: string;
+}
+export interface OperatorTaskSummary {
+    taskId: string;
+    phase: string | null;
+    lastEvidenceAt: string | null;
+    /** null explicitly means unknown; never inferred from a park or wait. */
+    responsible: RecordedResponsibility | null;
+    blocker: OperatorBlocker | null;
+}
+/** Pure projection in current-task order; no clock, host access, or retained state. */
+export declare function projectOperatorSummary(tasks: readonly OperatorSummaryTask[], decisions: readonly OperatorDecisionSnapshot[]): OperatorTaskSummary[];

package/dist/run/operator-summary.js

@@ -0,0 +1,77 @@
+/** Labels describe blockers, not journal park kinds or commands. */
+export const BLOCKER_KINDS = [
+    "human-decision", "retry", "cooldown", "dependency-wait", "stale-receipt",
+    "missing-capability", "unknown",
+];
+const SETTLED = new Set(["done", "completed", "merged"]);
+const emptyBlocker = (kind) => ({
+    kind, permittedActions: [], humanInterventionRequired: false,
+    decisionRequired: false, nextAction: null,
+});
+/** Pure projection in current-task order; no clock, host access, or retained state. */
+export function projectOperatorSummary(tasks, decisions) {
+    const statuses = new Map(tasks.map(task => [task.id, task.status]));
+    const parks = new Map(decisions.map(decision => [decision.taskId, decision]));
+    return tasks.map(task => {
+        let blocker = null;
+        const decision = task.status === "human" ? parks.get(task.id) : undefined;
+        const terminal = SETTLED.has(task.status) || task.status === "failed";
+        if (decision) {
+            const { park, verbs, diagnostic } = decision;
+            blocker = {
+                ...emptyBlocker(park.tombstone ? "unknown" : "human-decision"),
+                permittedActions: [...verbs],
+                humanInterventionRequired: !park.tombstone,
+                decisionRequired: verbs.length > 0,
+                ...(diagnostic !== undefined || park.reason !== undefined
+                    ? { diagnostic: diagnostic ?? park.reason } : {}),
+                nextAction: verbs.length > 0 ? `Choose a decision: ${verbs.join(", ")}` : null,
+            };
+            if (!park.tombstone && park.kind === "infra" && task.missingCapability) {
+                const { capability, diagnostic: capabilityDiagnostic } = task.missingCapability;
+                blocker.kind = "missing-capability";
+                blocker.capability = capability;
+                blocker.nextAction = `Diagnose host capability: ${capability}`;
+                if (diagnostic === undefined && capabilityDiagnostic !== undefined)
+                    blocker.diagnostic = capabilityDiagnostic;
+            }
+        }
+        else if (task.status === "human") {
+            // Missing decision evidence must not make a parked task look automatic.
+            blocker = { ...emptyBlocker("unknown"), humanInterventionRequired: true };
+        }
+        else if (!terminal) {
+            const unmet = task.status === "pending" ? task.deps.filter(id => !SETTLED.has(statuses.get(id))) : [];
+            if (unmet.length > 0) {
+                blocker = {
+                    ...emptyBlocker("dependency-wait"), prerequisites: unmet,
+                    nextAction: `Wait for prerequisites: ${unmet.join(", ")}`,
+                };
+            }
+            else if (task.staleReceipt) {
+                blocker = {
+                    ...emptyBlocker("stale-receipt"), diagnostic: task.staleReceipt.diagnostic,
+                    nextAction: "Inspect the stale receipt and refresh its evidence",
+                };
+            }
+            else if (task.wait) {
+                blocker = {
+                    ...emptyBlocker(task.wait.kind),
+                    ...(task.wait.diagnostic === undefined ? {} : { diagnostic: task.wait.diagnostic }),
+                    ...(task.wait.wakeAt === undefined ? {} : { wakeAt: task.wait.wakeAt }),
+                };
+            }
+            else if (task.status === "blocked" || task.status === "unknown") {
+                blocker = emptyBlocker("unknown");
+            }
+        }
+        const owner = task.responsible;
+        return {
+            taskId: task.id, phase: task.phase ?? null, lastEvidenceAt: task.lastEvidenceAt ?? null,
+            responsible: owner?.role !== undefined || owner?.agent !== undefined
+                ? { ...(owner.role === undefined ? {} : { role: owner.role }),
+                    ...(owner.agent === undefined ? {} : { agent: owner.agent }) } : null,
+            blocker,
+        };
+    });
+}

package/dist/run/protocol.d.ts

@@ -1,6 +1,77 @@
 import { z } from "zod";
 import { type GateName } from "../graph/schema.js";
 import { type GateOutcome } from "./outcome.js";
+/** Shared lifecycle vocabulary for shell evidence and later build-result emitters. */
+export declare const COMMAND_RECEIPT_OUTCOMES: readonly ["started", "completed", "spawn-failed", "timed-out", "cancelled", "reused-result", "skipped", "refused"];
+export declare const CommandReceiptAttributionSchema: z.ZodObject<{
+    runId: z.ZodString;
+    taskId: z.ZodString;
+    attempt: z.ZodNumber;
+    gateRound: z.ZodNumber;
+    invocation: z.ZodString;
+}, z.core.$strict>;
+export type CommandReceiptAttribution = z.infer<typeof CommandReceiptAttributionSchema>;
+export declare const ShellReceiptSchema: z.ZodObject<{
+    outcome: z.ZodEnum<{
+        skipped: "skipped";
+        started: "started";
+        completed: "completed";
+        "spawn-failed": "spawn-failed";
+        "timed-out": "timed-out";
+        cancelled: "cancelled";
+        "reused-result": "reused-result";
+        refused: "refused";
+    }>;
+    confirmedStart: z.ZodBoolean;
+    attribution: z.ZodOptional<z.ZodObject<{
+        runId: z.ZodString;
+        taskId: z.ZodString;
+        attempt: z.ZodNumber;
+        gateRound: z.ZodNumber;
+        invocation: z.ZodString;
+    }, z.core.$strict>>;
+    pid: z.ZodOptional<z.ZodNumber>;
+    exitCode: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    signal: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    error: z.ZodOptional<z.ZodString>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type ShellReceipt = z.infer<typeof ShellReceiptSchema>;
+/** A task-build row must carry the entire caller-owned correlation, even before spawn. */
+export declare const CommandReceiptSchema: z.ZodObject<{
+    outcome: z.ZodEnum<{
+        skipped: "skipped";
+        started: "started";
+        completed: "completed";
+        "spawn-failed": "spawn-failed";
+        "timed-out": "timed-out";
+        cancelled: "cancelled";
+        "reused-result": "reused-result";
+        refused: "refused";
+    }>;
+    confirmedStart: z.ZodBoolean;
+    pid: z.ZodOptional<z.ZodNumber>;
+    exitCode: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    signal: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    error: z.ZodOptional<z.ZodString>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+    attribution: z.ZodObject<{
+        runId: z.ZodString;
+        taskId: z.ZodString;
+        attempt: z.ZodNumber;
+        gateRound: z.ZodNumber;
+        invocation: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type CommandReceipt = z.infer<typeof CommandReceiptSchema>;
+export declare function readCommandReceipt(raw: unknown): {
+    kind: "receipt";
+    receipt: CommandReceipt;
+} | {
+    kind: "protocol-issue";
+    issues: string[];
+    raw: unknown;
+};
 /** The T31 outcome vocabulary, made executable and strict at the persistence boundary. */
 export declare const GateOutcomeSchema: z.ZodType<GateOutcome>;
 export declare const ROLE_INVOCATION_ROLES: readonly ["worker", "judge", "review", "consult"];