@spexcode/spec-cli 0.6.7 → 0.7.0-next.0

package/templates/spec/project/.plugins/core/stop-gate/spec.md

@@ -18,6 +18,6 @@ The block text is where the declaration ritual is taught, so it is written to be
 
 The clean-done eval nudge is advisory only and must never corrupt the Stop hook protocol. Claude-family hooks can receive it as `hookSpecificOutput.additionalContext`; Codex Stop allows are silent because Codex treats unsupported non-block stdout as invalid hook JSON. Blocking decisions stay shared across harnesses through `{"decision":"block"}` plus the dispatcher’s Codex stderr bridge.
 
-Both gates act ONLY on a GOVERNED (dashboard-launched) session: the gate resolves the session's record in the global store from the payload's `session_id`, and on a non-governed (user-self-launched) record — or none — it exits 0 SILENTLY. A self-launched agent has no board to feed, so the declare-demand must never misfire on it. Its own state writes go through `spex session … --session <id>`, passing the id explicitly since there is no worktree file to read it from.
+Both gates act ONLY on a GOVERNED (dashboard-launched) session: the gate resolves the session's record in the global store from the payload's `session_id`, and on a non-governed (user-self-launched) record — or none — it exits 0 SILENTLY. A self-launched agent has no board to feed, so the declare-demand must never misfire on it. The forced-continuation fallback writes `asking` through `spex internal session-state --session <id>` — the canonical writer, with no delivery or build side effects — passing the id explicitly since there is no worktree file to read it from. Porcelain declarations remain agent-facing; the hook never invokes them to repair its own stop.
 
 It is the enforcement edge of [[core]]: nothing leaves a session except as committed work under a truthful declaration. The freshness it reads is set by [[mark-active]].

package/templates/spec/project/.plugins/core/stop-gate/stop-gate.sh

@@ -11,28 +11,20 @@
 #                                          without inventing a completion state.
 # $SPEX is the PATH-independent CLI invocation (abs tsx + cli) injected by settingsArg, so the gate's own
 # auto-default AND the command it shows the agent both work even when `spex` is absent from PATH.
-# @@@ global store + governed gate - state lives in the per-session GLOBAL record session.json (keyed by the
-# harness session_id from the payload, grouped per-project — mirrors spec-cli/src/layout.ts). The gate acts
-# ONLY on a GOVERNED (dashboard-launched) session: a user-self-launched agent has no board to feed, so an
-# undeclared stop is none of our business — we exit 0 SILENTLY (the bug this fixes: the declare-demand
-# misfiring on a self-launched codex/claude). cwd = the session worktree (resolves the project key + the
-# commit-gate's git); state writes go through `$SPEX session … --session <id>` (TS owns the JSON).
+# @@@ governed gate - the session id comes from the payload. The gate acts ONLY on a GOVERNED
+# (dashboard-launched) session: a user-self-launched agent has no board to feed, so an undeclared stop is
+# none of our business. Lifecycle status/proposal come from the canonical session application through one
+# CLI read; this shell never treats runtime.json as a second lifecycle database.
 . "${SPEXCODE_HARNESS_LIB:?harness.sh not exported by dispatch.sh}"
 S="${SPEX:-spex}"
 input=$(cat 2>/dev/null || true)
 sid=$(hp_session_id "$input"); [ -n "$sid" ] || exit 0
 sdir=$(hp_store_dir "$sid") || exit 0
-rec="$sdir/session.json"
-# non-governed (or no record) → silently let the stop through. THIS is the self-launch fix.
-grep -q '^[[:space:]]*"governed"[[:space:]]*:[[:space:]]*true,\?$' "$rec" 2>/dev/null || exit 0
-
-# read a CLOSED-VOCABULARY field (status / proposal) off its OWN line. The record is one-field-per-line from
-# the single writer ([[sessions-core]]), so anchoring to the line start is what keeps a neighbouring note's
-# escaped quote from being read as this field's value — the read half of the same rule that stops shell from
-# ever composing the record.
-jget() { sed -n "s/^[[:space:]]*\"$1\"[[:space:]]*:[[:space:]]*\"\([^\"]*\)\",\?$/\1/p" "$rec" 2>/dev/null | head -1; }
-status=$(jget status)
-proposal=$(jget proposal)
+# non-governed (or no record) → silently let the stop through. THIS is the self-launch fix. The CLI response
+# is governed<TAB>status<TAB>proposal; status/proposal are canonical, while governed is identity metadata.
+hook_state=$($S internal session-hook-state --session "$sid" 2>/dev/null) || exit 0
+IFS=$'\t' read -r governed status proposal <<< "$hook_state"
+[ "$governed" = 1 ] || exit 0
 
 # the value of the payload's structured `stop_hook_active` field (true on the hook-forced continuation),
 # read by field name rather than substring-sniffing the JSON blob. ([a-z]* captures true/false portably —
@@ -91,7 +83,10 @@ if [ "${status:-active}" = awaiting ] && { [ "$proposal" = merge ] || [ "$propos
     exit 0   # work is committed and ahead of main -> the proposal is honest, let it stop.
   fi
   if [ "$cont" = true ]; then
-    $S session ask --session "$sid" --note "stopped with uncommitted work — commit your spec+code on the node branch, then re-declare done" >/dev/null 2>&1 || true
+    # The hook is a thin boundary.  Do not call the porcelain declaration here: it may trigger
+    # delivery/build work and can remain running after the harness has already accepted the stop.
+    # The internal writer is the same canonical lifecycle path, with no dispatch side effects.
+    $S internal session-state asking --session "$sid" --note "stopped with uncommitted work — commit your spec+code on the node branch, then re-declare done" >/dev/null 2>&1 || true
     exit 0
   fi
   reason=$($S internal hook-prompt stop-gate --variant commit --reason "$gatemsg" --cli "$S" --propose "$proposal") || exit 1
@@ -106,13 +101,15 @@ fi
 if [ "$cont" = true ]; then
   # The forced continuation also stopped without declaring. Escape into asking: no default may invent a
   # completed lane, and the stopped agent now needs a human prompt to choose merge, close, ask, or park.
-  $S session ask --session "$sid" --note "auto: stopped without declaring — choose merge, close, ask, or park; done --propose nothing records no state" >/dev/null 2>&1 || true
+  # Keep this fallback inside the hook/CLI boundary.  The porcelain `session ask` command can wait on
+  # delivery and workspace builds; a stop hook must settle the canonical state independently of those paths.
+  $S internal session-state asking --session "$sid" --note "auto: stopped without declaring — choose merge, close, ask, or park; done --propose nothing records no state" >/dev/null 2>&1 || true
   exit 0
 fi
 
 # first stop in an undeclared state -> block. The FULL teaching text prints ONCE per session; every later
 # undeclared stop gets a ONE-LINE version (a heavy session hits this gate 15-20x a night — re-printing the
-# full menu each time is pure token noise). The once-sentinel is a plain file beside session.json in the
+# full menu each time is pure token noise). The once-sentinel is a plain file beside runtime.json in the
 # session's global store dir — the same per-session-sentinel mechanism as the CLI's note-echo-taught; $sdir
 # is already alias-resolved here, so a codex thread id lands on the same file, and an unwritable dir just
 # teaches again (never blocks the block). The terse line must stay SELF-EXPLANATORY: an agent whose context

package/templates/spec/project/.plugins/skills/merge/spec.md

@@ -0,0 +1,33 @@
+---
+title: merge
+surface: skill, command
+status: active
+hue: 130
+desc: Land this session's completed branch into the repository's source-of-truth branch as one verified no-ff merge, preserve unrelated dirty work, push it, and settle the session honestly. Use when the user says /merge, asks to merge or land this session, or when a supervisor dispatches a merge.
+kind: mutating
+---
+# merge
+
+Land the current SpexCode session's branch; do not dispatch another merge request back to yourself.
+
+1. Inspect the current session, branch, worktree, source-of-truth checkout, and live Git status. Treat every
+   pre-existing dirty or untracked path as user-owned. Record its exact status and diff fingerprint; never
+   discard it, fold it into your commit, or hide it behind an unverified stash.
+2. Commit this session's intended spec and code first. In this worktree, merge the latest source-of-truth
+   head into the session branch. Resolve conflicts here, then rerun the focused proof, build, `spex spec lint`,
+   and `spex eval lint --changed` required by the changed behavior.
+3. Immediately before landing, verify
+   `git merge-base --is-ancestor <source-head> <session-head>`. If it fails, sync again. A clean textual merge
+   is not product proof.
+4. In the source-of-truth checkout, make one `--no-ff` merge of the already-synced session tip. Do not resolve
+   conflicts there. If unrelated dirty work prevents the merge, preserve it byte-for-byte and report the exact
+   overlap rather than forcing, resetting, or committing it.
+5. Verify the source checkout has no `MERGE_HEAD`, the session tip is its ancestor, unrelated dirty
+   fingerprints are unchanged, and the post-merge gates pass. Push the source-of-truth branch only after
+   those checks.
+6. Stop test-owned processes and publish any evidence a human must inspect. If the work is fully landed and
+   no decision remains, run `spex session done --propose close` as the final action. Never close your own
+   session directly. If a real decision or external wake-up remains, declare the truthful alternative instead.
+
+`spex session merge <SEL>` is the supervisor-facing dispatcher that sends this workflow to another session.
+Inside the target session, execute the workflow above; do not call `spex session merge .` recursively.

package/templates/spec/project/.plugins/skills/spec.md

@@ -11,9 +11,5 @@ where an agent invokes them on demand, each carrying `surface: skill`. Grouping
 legible at a glance — the skill plugins on this shelf, the command presets on [[commands]], the auxiliary
 system contracts on [[prompts]], with [[core]] a flat child beside them.
 
-This node is a **shelf, not a surface** (the [[prompts]] shape): it declares no `surface` field and
-gathers nothing itself. Discovery is recursive and field-driven (surface), so a resident plugs in
-exactly as it would at the root. A plugin that serves BOTH surfaces — [[distill]] is skill and command —
-shelves here by its primary (skill) identity and still gathers as a command through its field. The init
-templates mirror this layout. The shelf stays pure presentation: moving a resident beneath it changes
-neither that plugin's identity nor the surfaces gathered from its frontmatter.
+This node is a **shelf, not a surface**. Its routing and relocation invariant is owned once by
+[[.plugins]]'s shelf invariant; this node only describes skill-specific materialization and invocation.

package/templates/spec/project/.plugins/spec.md

@@ -21,3 +21,10 @@ materialized into the agent's contract.
 Which plugins `spex init` ships is the init-preset rule. `seed: false` excludes a plugin subtree; shared
 plugins have one body and one helper set — there is no separately authored adopter variant. Dogfood eval
 scenarios/readings remain with the implementation and git history they measure.
+
+## shelf invariant
+
+Grouping shelves (`[[commands]]`, `[[skills]]`, `[[review]]`, and `[[prompts]]`) are presentation parents, not
+surfaces. Discovery is recursive and field-driven, so moving a resident under a shelf changes neither its
+identity nor the surfaces gathered from its frontmatter. Each shelf therefore states only its surface-specific
+purpose; it must not copy this routing invariant.

package/dist/execution-trace.d.ts

@@ -1,26 +0,0 @@
-export type ExecutionTurn = Readonly<{
-    token: string;
-    acceptedAt: string;
-}>;
-export type ExecutionStepKind = 'command' | 'read' | 'write' | 'search' | 'tool';
-export type ExecutionStep = Readonly<{
-    id: string;
-    kind: ExecutionStepKind;
-    label: string;
-    detail?: string;
-    state: 'running' | 'done';
-}>;
-export type ExecutionTrace = Readonly<{
-    revision: string;
-    turnId: string | null;
-    workingNote: string | null;
-    steps: readonly ExecutionStep[];
-}>;
-type ExportLoader = (threadId: string) => string;
-export declare function codexRolloutPath(threadId: string, root?: string): string | null;
-export declare function readCodexExecutionTrace(threadId: string, turn: ExecutionTurn | null, root?: string): ExecutionTrace;
-export declare function readProjectJsonlExecutionTrace(threadId: string, turn: ExecutionTurn | null, root?: string): ExecutionTrace;
-export declare function readSessionJsonlExecutionTrace(threadId: string, turn: ExecutionTurn | null, root?: string): ExecutionTrace;
-export declare function readLocalStoreExecutionTrace(threadId: string, turn: ExecutionTurn | null, root?: string, load?: ExportLoader): ExecutionTrace;
-export declare const noExecutionTrace: (_threadId: string, _turn: ExecutionTurn | null) => ExecutionTrace | null;
-export {};

package/dist/execution-trace.js

@@ -1,475 +0,0 @@
-import { execFileSync } from 'node:child_process';
-import { closeSync, openSync, readFileSync, readSync, readdirSync, statSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
-const cache = new Map();
-const sessionJsonlPaths = new Map();
-const localStoreCache = new Map();
-const emptyTrace = (turn, revision = '0') => ({
-    revision: `${turn?.token ?? '0'}:${revision}`,
-    turnId: turn?.token ?? null,
-    workingNote: null,
-    steps: [],
-});
-const object = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : null;
-const items = (value) => Array.isArray(value) ? value : [];
-const text = (value) => typeof value === 'string' && value.trim() ? value.trim() : null;
-const field = (value, ...names) => {
-    for (const name of names) {
-        const found = text(value[name]);
-        if (found)
-            return found;
-    }
-    return null;
-};
-const children = (dir) => { try {
-    return readdirSync(dir).sort().reverse();
-}
-catch {
-    return [];
-} };
-const sensitive = /(token|secret|password|authorization|bearer|cookie|credential|api[_-]?key|private[ _-]?key)/i;
-const detailFields = [
-    ['cmd', 'cmd'], ['command', 'command'], ['path', 'path'], ['file_path', 'path'],
-    ['query', 'query'], ['pattern', 'pattern'], ['url', 'url'], ['workdir', 'in'],
-];
-function toolKind(name) {
-    const normalized = name.toLowerCase();
-    if (/(search|browse|web)/.test(normalized))
-        return 'search';
-    if (/(read|list|find|grep|glob|stat)/.test(normalized))
-        return 'read';
-    if (/(write|edit|patch|create|delete|move|rename)/.test(normalized))
-        return 'write';
-    if (/(exec|shell|command|terminal|bash|npm|git)/.test(normalized))
-        return 'command';
-    return 'tool';
-}
-function toolLabel(name, kind) {
-    const labels = {
-        command: 'Run command', read: 'Read files', write: 'Update files', search: 'Search', tool: 'Use tool',
-    };
-    return name.trim() || labels[kind];
-}
-function recordInput(value) {
-    if (value && typeof value === 'object' && !Array.isArray(value))
-        return value;
-    if (typeof value !== 'string')
-        return null;
-    try {
-        const parsed = JSON.parse(value);
-        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
-    }
-    catch {
-        return null;
-    }
-}
-function sensitiveInput(value) {
-    if (typeof value === 'string')
-        return sensitive.test(value);
-    if (Array.isArray(value))
-        return value.some(sensitiveInput);
-    if (value && typeof value === 'object')
-        return Object.entries(value)
-            .some(([key, entry]) => sensitive.test(key) || sensitiveInput(entry));
-    return false;
-}
-function compactValue(key, value) {
-    const compact = String(value).trim().replace(/\s+/g, ' ');
-    if (key === 'path' || key === 'file_path' || key === 'workdir') {
-        const parts = compact.replace(/\\/g, '/').split('/').filter(Boolean);
-        return parts.slice(-2).join('/') || compact;
-    }
-    return compact.length > 96 ? `${compact.slice(0, 95)}...` : compact;
-}
-function detailFromInput(value) {
-    const input = recordInput(value);
-    if (!input || sensitiveInput(input))
-        return undefined;
-    const details = [];
-    for (const [key, title] of detailFields) {
-        const value = input[key];
-        if (typeof value !== 'string' && typeof value !== 'number' && typeof value !== 'boolean')
-            continue;
-        details.push(`${title}: ${compactValue(key, value)}`);
-        if (details.length === 2)
-            break;
-    }
-    const lineStart = input.line_start;
-    const lineEnd = input.line_end;
-    if (details.length < 2 && (typeof lineStart === 'number' || typeof lineEnd === 'number')) {
-        details.push(`lines: ${typeof lineStart === 'number' ? lineStart : 1}-${typeof lineEnd === 'number' ? lineEnd : lineStart}`);
-    }
-    return details.length ? details.join(' · ') : undefined;
-}
-function displayableNote(value) {
-    const note = text(value)?.replace(/\s+/g, ' ');
-    return note ? (note.length > 240 ? `${note.slice(0, 239)}...` : note) : null;
-}
-function stepFromInput(id, name, input, state) {
-    const kind = toolKind(name);
-    const detail = detailFromInput(input);
-    return { id, kind, label: toolLabel(name, kind), ...(detail ? { detail } : {}), state };
-}
-function timestamp(value) {
-    if (typeof value === 'number' && Number.isFinite(value))
-        return value;
-    if (typeof value !== 'string' || !value.trim())
-        return null;
-    const number = Number(value);
-    if (Number.isFinite(number))
-        return number;
-    const parsed = Date.parse(value);
-    return Number.isFinite(parsed) ? parsed : null;
-}
-function identities(...values) {
-    const result = new Set();
-    for (const value of values)
-        for (const key of ['id', 'uuid', 'message_id', 'messageId', 'client_id', 'clientId', 'client_user_message_id', 'clientUserMessageId', 'promptId']) {
-            const id = field(value || {}, key);
-            if (id)
-                result.add(id);
-        }
-    return [...result];
-}
-function at(value) {
-    for (const key of ['timestamp', 'created_at', 'createdAt', 'created', 'time']) {
-        const found = timestamp(value[key]);
-        if (found !== null)
-            return found;
-    }
-    return null;
-}
-function isPrompt(content) {
-    if (typeof content === 'string')
-        return !!content.trim();
-    const blocks = items(content);
-    return blocks.some((block) => object(block)?.type !== 'tool_result');
-}
-function project(events, sourceRevision, turn) {
-    let start = -1;
-    if (!turn) {
-        for (const [index, event] of events.entries())
-            if (event.type === 'boundary')
-                start = index;
-    }
-    else {
-        const acceptedAt = timestamp(turn.acceptedAt);
-        const exact = events.flatMap((event, index) => event.type === 'boundary' && event.ids.includes(turn.token) ? [index] : []);
-        start = exact.length === 1 ? exact[0] : -1;
-        if (start < 0 && exact.length === 0 && acceptedAt !== null) {
-            const candidates = events.flatMap((event, index) => event.type === 'boundary' && event.at !== null && event.at >= acceptedAt
-                ? [{ index, at: event.at }] : []);
-            const earliest = candidates.reduce((value, candidate) => value === null || candidate.at < value ? candidate.at : value, null);
-            const matches = earliest === null ? [] : candidates.filter((candidate) => candidate.at === earliest);
-            if (matches.length === 1)
-                start = matches[0].index;
-        }
-    }
-    if (turn && start < 0)
-        return emptyTrace(turn, sourceRevision);
-    let note = null;
-    let steps = [];
-    for (let index = start + 1; index < events.length; index++) {
-        const event = events[index];
-        if (event.type === 'boundary')
-            return emptyTrace(turn, sourceRevision);
-        if (event.type === 'note') {
-            note = event.text;
-            steps = [];
-            continue;
-        }
-        if (event.type === 'call') {
-            if (note)
-                steps.push(event.step);
-            continue;
-        }
-        const step = steps.find((value) => value.id === event.id);
-        if (step)
-            steps[steps.indexOf(step)] = { ...step, state: 'done' };
-    }
-    return note
-        ? { revision: `${turn?.token ?? '0'}:${sourceRevision}`, turnId: turn?.token ?? null, workingNote: note, steps }
-        : emptyTrace(turn, sourceRevision);
-}
-function applyRolloutEvent(value, ordinal) {
-    const event = object(value);
-    const payload = object(event?.payload);
-    if (!event || !payload)
-        return [];
-    const result = [];
-    const type = field(payload, 'type');
-    if ((event.type === 'event_msg' && type === 'user_message')
-        || (event.type === 'response_item' && (type === 'message' || type === 'input_message') && payload.role === 'user')) {
-        result.push({ type: 'boundary', ids: identities(payload, event), at: at(payload) ?? at(event) });
-    }
-    if (event.type === 'event_msg' && type === 'agent_message' && payload.phase === 'commentary') {
-        const note = displayableNote(payload.message ?? payload.text);
-        if (note)
-            result.push({ type: 'note', text: note });
-    }
-    if (event.type === 'response_item' && (type === 'custom_tool_call' || type === 'function_call')) {
-        const name = field(payload, 'name', 'tool_name') || 'tool';
-        const id = field(payload, 'call_id', 'id') || `tool-${ordinal}`;
-        result.push({ type: 'call', step: stepFromInput(id, name, payload.input ?? payload.arguments ?? payload.args, 'running') });
-    }
-    if (event.type === 'response_item' && (type === 'custom_tool_call_output' || type === 'function_call_output')) {
-        const id = field(payload, 'call_id', 'id');
-        if (id)
-            result.push({ type: 'done', id });
-    }
-    if (event.type === 'event_msg' && type === 'web_search_end') {
-        result.push({ type: 'call', step: stepFromInput(field(payload, 'id', 'call_id') || `search-${ordinal}`, 'Search', payload, 'done') });
-    }
-    return result;
-}
-function applyProjectJsonlEvent(value, ordinal) {
-    const entry = object(value);
-    const message = object(entry?.message);
-    if (!entry || !message)
-        return [];
-    const result = [];
-    if (entry.type === 'user' && message.role === 'user' && isPrompt(message.content))
-        result.push({ type: 'boundary', ids: identities(entry, message), at: at(entry) ?? at(message) });
-    if (entry.type === 'assistant' && message.role === 'assistant')
-        for (const blockValue of items(message.content)) {
-            const block = object(blockValue);
-            if (block?.type === 'text') {
-                const note = displayableNote(block.text);
-                if (note)
-                    result.push({ type: 'note', text: note });
-            }
-            if (block?.type === 'tool_use') {
-                const id = field(block, 'id') || `tool-${ordinal}`;
-                result.push({ type: 'call', step: stepFromInput(id, field(block, 'name') || 'tool', block.input, 'running') });
-            }
-        }
-    if (entry.type === 'user' && message.role === 'user')
-        for (const blockValue of items(message.content)) {
-            const block = object(blockValue);
-            if (block?.type === 'tool_result') {
-                const id = field(block, 'tool_use_id');
-                if (id)
-                    result.push({ type: 'done', id });
-            }
-        }
-    return result;
-}
-function applySessionJsonlEvent(value, ordinal) {
-    const entry = object(value);
-    const message = object(entry?.message);
-    if (!entry || entry.type !== 'message' || !message)
-        return [];
-    const result = [];
-    if (message.role === 'user' && isPrompt(message.content))
-        result.push({ type: 'boundary', ids: identities(entry, message), at: at(entry) ?? at(message) });
-    if (message.role === 'assistant')
-        for (const blockValue of items(message.content)) {
-            const block = object(blockValue);
-            if (block?.type === 'text') {
-                const note = displayableNote(block.text);
-                if (note)
-                    result.push({ type: 'note', text: note });
-            }
-            if (block?.type === 'toolCall') {
-                const id = field(block, 'id') || `tool-${ordinal}`;
-                result.push({ type: 'call', step: stepFromInput(id, field(block, 'name') || 'tool', block.arguments, 'running') });
-            }
-        }
-    if (message.role === 'toolResult') {
-        const id = field(message, 'toolCallId');
-        if (id)
-            result.push({ type: 'done', id });
-    }
-    return result;
-}
-function completeLines(buffer) {
-    const lines = [];
-    let start = 0;
-    for (let index = 0; index < buffer.length; index++) {
-        if (buffer[index] !== 10)
-            continue;
-        if (index > start)
-            lines.push(buffer.subarray(start, index));
-        start = index + 1;
-    }
-    return { lines, remainder: buffer.subarray(start) };
-}
-function readFrom(path, start) {
-    let fd = null;
-    try {
-        const size = statSync(path).size;
-        if (size <= start)
-            return Buffer.alloc(0);
-        const chunk = Buffer.allocUnsafe(size - start);
-        fd = openSync(path, 'r');
-        readSync(fd, chunk, 0, chunk.length, start);
-        return chunk;
-    }
-    catch {
-        return null;
-    }
-    finally {
-        if (fd !== null)
-            closeSync(fd);
-    }
-}
-function readIncremental(path, apply, turn) {
-    if (!path)
-        return emptyTrace(turn);
-    let size;
-    try {
-        size = statSync(path).size;
-    }
-    catch {
-        return emptyTrace(turn);
-    }
-    const prior = cache.get(path);
-    const trace = prior && prior.size <= size
-        ? { ...prior, events: [...prior.events] }
-        : { size: 0, remainder: Buffer.alloc(0), events: [] };
-    const appended = readFrom(path, trace.size);
-    if (appended === null)
-        return emptyTrace(turn);
-    const { lines, remainder } = completeLines(Buffer.concat([trace.remainder, appended]));
-    for (const [index, line] of lines.entries()) {
-        try {
-            trace.events.push(...apply(JSON.parse(line.toString('utf8')), trace.size + index));
-        }
-        catch { /* malformed native data is ignored */ }
-    }
-    trace.size = size;
-    trace.remainder = remainder;
-    cache.set(path, trace);
-    return project(trace.events, String(size), turn);
-}
-const codexSessionsDir = () => join(process.env.CODEX_HOME || join(homedir(), '.codex'), 'sessions');
-export function codexRolloutPath(threadId, root = codexSessionsDir()) {
-    for (const year of children(root))
-        for (const month of children(join(root, year)))
-            for (const day of children(join(root, year, month))) {
-                const dir = join(root, year, month, day);
-                const file = children(dir).find((name) => name.includes(threadId));
-                if (file)
-                    return join(dir, file);
-            }
-    return null;
-}
-export function readCodexExecutionTrace(threadId, turn, root = codexSessionsDir()) {
-    return readIncremental(codexRolloutPath(threadId, root), applyRolloutEvent, turn);
-}
-const projectTranscriptRoot = () => join(process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude'), 'projects');
-function projectJsonlPath(threadId, root = projectTranscriptRoot()) {
-    for (const project of children(root)) {
-        const path = join(root, project, `${threadId}.jsonl`);
-        try {
-            if (statSync(path).isFile())
-                return path;
-        }
-        catch { /* try next */ }
-    }
-    return null;
-}
-export function readProjectJsonlExecutionTrace(threadId, turn, root = projectTranscriptRoot()) {
-    return readIncremental(projectJsonlPath(threadId, root), applyProjectJsonlEvent, turn);
-}
-const sessionJsonlRoot = () => join(process.env.SPEXCODE_PI_AGENT_DIR || join(homedir(), '.pi', 'agent'), 'sessions');
-function sessionJsonlPath(threadId, root = sessionJsonlRoot()) {
-    const key = `${root}:${threadId}`;
-    const cached = sessionJsonlPaths.get(key);
-    if (cached) {
-        try {
-            if (statSync(cached).isFile())
-                return cached;
-        }
-        catch {
-            sessionJsonlPaths.delete(key);
-        }
-    }
-    for (const directory of children(root))
-        for (const file of children(join(root, directory))) {
-            if (!file.endsWith('.jsonl'))
-                continue;
-            const path = join(root, directory, file);
-            try {
-                const header = object(JSON.parse(readFileSync(path, 'utf8').split('\n', 1)[0]));
-                if (header?.type === 'session' && header.id === threadId) {
-                    sessionJsonlPaths.set(key, path);
-                    return path;
-                }
-            }
-            catch { /* unreadable entries are not a match */ }
-        }
-    return null;
-}
-export function readSessionJsonlExecutionTrace(threadId, turn, root = sessionJsonlRoot()) {
-    return readIncremental(sessionJsonlPath(threadId, root), applySessionJsonlEvent, turn);
-}
-const localStoreRoot = () => process.env.SPEXCODE_OPENCODE_DATA_DIR
-    || join(process.env.XDG_DATA_HOME || join(homedir(), '.local', 'share'), 'opencode');
-function readLocalExport(threadId) {
-    return execFileSync(process.env.SPEXCODE_OPENCODE_CMD || 'opencode', ['export', threadId, '--sanitize'], {
-        encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
-    });
-}
-function localStoreRevision(root) {
-    try {
-        const database = statSync(join(root, 'opencode.db'));
-        let writeAheadLog = '0:0';
-        try {
-            const stat = statSync(join(root, 'opencode.db-wal'));
-            writeAheadLog = `${stat.size}:${Math.floor(stat.mtimeMs)}`;
-        }
-        catch { /* a checkpointed database has no separate write-ahead log */ }
-        return `${database.size}:${Math.floor(database.mtimeMs)}:${writeAheadLog}`;
-    }
-    catch {
-        return null;
-    }
-}
-function localStoreEvents(value) {
-    const events = [];
-    for (const messageValue of items(object(value)?.messages)) {
-        const message = object(messageValue);
-        const info = object(message?.info);
-        if (!message || !info)
-            continue;
-        if (info.role === 'user')
-            events.push({ type: 'boundary', ids: identities(info, message), at: at(object(info.time) || info) });
-        if (info.role !== 'assistant')
-            continue;
-        for (const partValue of items(message.parts)) {
-            const part = object(partValue);
-            if (part?.type === 'text') {
-                const note = displayableNote(part.text);
-                if (note)
-                    events.push({ type: 'note', text: note });
-            }
-            if (part?.type === 'tool') {
-                const state = object(part.state);
-                const status = field(state || {}, 'status')?.toLowerCase() || '';
-                const id = field(part, 'callID', 'id') || `tool-${events.length}`;
-                events.push({ type: 'call', step: stepFromInput(id, field(part, 'tool') || 'tool', state?.input, /completed|error|cancelled/.test(status) ? 'done' : 'running') });
-            }
-        }
-    }
-    return events;
-}
-export function readLocalStoreExecutionTrace(threadId, turn, root = localStoreRoot(), load = readLocalExport) {
-    const revision = localStoreRevision(root);
-    if (!revision)
-        return emptyTrace(turn);
-    const key = `${root}:${threadId}`;
-    let cached = localStoreCache.get(key);
-    if (!cached || cached.revision !== revision) {
-        try {
-            cached = { revision, events: localStoreEvents(JSON.parse(load(threadId))) };
-            localStoreCache.set(key, cached);
-        }
-        catch {
-            return emptyTrace(turn, revision);
-        }
-    }
-    return project(cached.events, revision, turn);
-}
-export const noExecutionTrace = (_threadId, _turn) => null;

package/dist/session-execution.d.ts

@@ -1,10 +0,0 @@
-import type { Context } from 'hono';
-import type { ExecutionStep } from './execution-trace.js';
-export type SessionExecution = Readonly<{
-    revision: string;
-    turnId: string | null;
-    workingNote: string | null;
-    steps: readonly ExecutionStep[];
-}>;
-export declare function readSessionExecution(id: string): SessionExecution | null;
-export declare function sessionExecutionStream(c: Context): Promise<Response>;