opensquid 0.5.395

package/dist/runtime/fsm.js

@@ -0,0 +1,92 @@
+/**
+ * T-PACK-FSM-STANDARDIZATION slice A — the generic total-transition FSM engine.
+ *
+ * The capstone thesis is that a pack's lifecycle is an EXPLICIT TOTAL-TRANSITION
+ * FSM. Today the only "FSM" (`chain_state.ts`) is a single global stage tracker
+ * whose `transitionChainStage` accepts ANY target with no legality matrix — it
+ * is NOT total and cannot loop back. This module is the generic engine that
+ * replaces that: a pure, pack-declarable FSM with validated transitions.
+ *
+ * Two pure pieces:
+ *   - `validateFsm(fsm)` — load-time checks: `initial` and every transition's
+ *     `from`/`to` reference a declared state; no transition targets an
+ *     undefined state. Returns the list of errors (empty = valid). This is what
+ *     makes the machine TOTAL-by-construction: every reachable transition lands
+ *     on a real state, and the runner defines an outcome for EVERY (state,event)
+ *     pair (a matching transition, else an explicit stay).
+ *   - `step(fsm, current, event, evalWhen?)` — the transition function. Total:
+ *     returns a defined next-state for every input. No I/O; the optional
+ *     `when` guard is evaluated through an injected `evalWhen` (the caller wires
+ *     the expression engine) so this module stays pure + testable.
+ *
+ * Unlike `chain_state`, transitions here are DECLARED data, support `*` (any
+ * source) and a `when` guard, and can LOOP BACK (e.g. `researching --guess-->
+ * researching`) — the edge the scope guess-prevention gate (slice C) needs.
+ *
+ * Imports: zod only. Imported by: slice A2 (runtime integration), slice C
+ * (scope FSM), tests.
+ */
+import { z } from 'zod';
+/** A wildcard `from` matching any current state. */
+export const ANY_STATE = '*';
+export const Transition = z
+    .object({
+    /** Source state name, or `*` to match any current state. */
+    from: z.string().min(1),
+    /** Event name that fires this transition. */
+    on: z.string().min(1),
+    /** Target state — MUST be a declared state (validateFsm enforces). */
+    to: z.string().min(1),
+    /** Optional `if:`-expression guard; evaluated via the injected evalWhen. */
+    when: z.string().min(1).optional(),
+})
+    .strict();
+export const Fsm = z
+    .object({
+    initial: z.string().min(1),
+    states: z.array(z.string().min(1)).min(1),
+    transitions: z.array(Transition).default([]),
+})
+    .strict();
+/**
+ * Load-time validation. Returns a (possibly empty) list of human-readable
+ * errors. The machine is TOTAL by construction once these pass: the runner
+ * defines an outcome for every (state, event), and every declared transition
+ * lands on a real state.
+ */
+export function validateFsm(fsm) {
+    const errors = [];
+    const states = new Set(fsm.states);
+    if (!states.has(fsm.initial)) {
+        errors.push(`initial state "${fsm.initial}" is not in states [${fsm.states.join(', ')}]`);
+    }
+    fsm.transitions.forEach((t, i) => {
+        if (t.from !== ANY_STATE && !states.has(t.from)) {
+            errors.push(`transition[${String(i)}] from "${t.from}" is not a declared state`);
+        }
+        if (!states.has(t.to)) {
+            errors.push(`transition[${String(i)}] to "${t.to}" is not a declared state`);
+        }
+    });
+    return errors;
+}
+/**
+ * The transition function — TOTAL: returns a defined next-state for every
+ * (current, event). Finds the FIRST transition whose `from` matches (exact or
+ * `*`), whose `on` equals `event`, and whose `when` guard (if any) holds.
+ * No match → stay in `current` (the explicit default — no implicit/undefined
+ * state). `evalWhen` evaluates a guard expression; omitted → guards are treated
+ * as satisfied (caller opted out of guard evaluation).
+ */
+export function step(fsm, current, event, evalWhen) {
+    for (let i = 0; i < fsm.transitions.length; i++) {
+        const t = fsm.transitions[i];
+        if ((t.from === current || t.from === ANY_STATE) && t.on === event) {
+            if (t.when === undefined || evalWhen === undefined || evalWhen(t.when)) {
+                return { next: t.to, transitioned: t.to !== current, via: i };
+            }
+        }
+    }
+    return { next: current, transitioned: false, via: null };
+}
+//# sourceMappingURL=fsm.js.map

package/dist/runtime/fsm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fsm.js","sourceRoot":"","sources":["../../src/runtime/fsm.ts"],"names":[],"mappings":"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"}

package/dist/runtime/fsm_state.d.ts

@@ -0,0 +1,42 @@
+import { type Fsm, type StepResult } from './fsm.js';
+export interface FsmHistoryEntry {
+    state: string;
+    /** ISO-8601 timestamp the machine ENTERED this state. */
+    at: string;
+}
+export interface FsmStateFile {
+    state: string;
+    /** ISO timestamp the machine entered the CURRENT state. */
+    started_at: string;
+    /** Append-only audit trail of every state entered. */
+    history: FsmHistoryEntry[];
+}
+/**
+ * Read the persisted current state for `(session, pack)`. Defaults to
+ * `fsm.initial` when absent/unreadable/malformed, OR when the persisted state
+ * is no longer a declared state (the pack's FSM changed) — a self-healing
+ * no-throw read matching `readChainStage`.
+ */
+export declare function readFsmState(sessionId: string, packName: string, fsm: Fsm): Promise<string>;
+/**
+ * Advance `(session, pack)`'s FSM on `event`. Reads the current state, runs the
+ * total `step`, and — ONLY when the state actually transitions — persists the
+ * new state + appends to history. A no-op event (no matching transition, or a
+ * guard that fails) leaves the file untouched and returns `transitioned:false`.
+ * Returns the full `StepResult` so the caller can react to `via`/`transitioned`.
+ *
+ * `now` (ISO string) is supplied by the caller for determinism; `evalWhen`
+ * evaluates a transition's `when` guard (caller wires the expression engine).
+ */
+export declare function advanceFsmState(sessionId: string, packName: string, fsm: Fsm, event: string, now: string, evalWhen?: (expr: string) => boolean): Promise<StepResult>;
+/**
+ * Read the persisted state string for `(session, pack)` WITHOUT needing the
+ * pack's FSM definition — for CROSS-PACK reads where one pack's rule queries
+ * another pack's lifecycle state (e.g. a pack gating on the workflow stage).
+ * Returns null when the machine hasn't started (file absent) or is unreadable,
+ * so the caller distinguishes "no state yet" from any concrete state.
+ */
+export declare function readFsmStateRaw(sessionId: string, packName: string): Promise<string | null>;
+/** Remove a pack's FSM-state file (SessionEnd cleanup). ENOENT swallowed. */
+export declare function clearFsmState(sessionId: string, packName: string): Promise<void>;
+//# sourceMappingURL=fsm_state.d.ts.map

package/dist/runtime/fsm_state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fsm_state.d.ts","sourceRoot":"","sources":["../../src/runtime/fsm_state.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,KAAK,GAAG,EAAE,KAAK,UAAU,EAAQ,MAAM,UAAU,CAAC;AAG3D,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B;AAYD;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,CAWjG;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,GAAG,EACR,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GACnC,OAAO,CAAC,UAAU,CAAC,CAuBrB;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CASjG;AAED,6EAA6E;AAC7E,wBAAsB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMtF"}

package/dist/runtime/fsm_state.js

@@ -0,0 +1,114 @@
+/**
+ * T-PACK-FSM-STANDARDIZATION slice A3 — per-session pack-FSM runtime state.
+ *
+ * The generic, total-transition counterpart to `chain_state.ts`: instead of one
+ * hardcoded global stage tracker with a permissive `transitionChainStage`, this
+ * persists the current state of ANY pack's declared FSM (`Pack.fsm`, slice A2)
+ * per (session, pack) and advances it through the validated `step` function
+ * (slice A1) — so an advance can ONLY move along a declared transition, and a
+ * loop-back edge is honored.
+ *
+ * Persistence mirrors `chain_state` exactly (sessionStateFile + atomicWriteFile
+ * + no-throw reads), keyed `fsm-<packName>` so multiple packs' machines coexist
+ * in one session. Pure where it can be: `step` does the transition logic;
+ * `advanceFsmState` only adds I/O (read current → step → persist-if-moved) and
+ * takes `now`/`evalWhen` as params so it stays deterministic + testable.
+ *
+ * Imported by: slice A3b primitives (`read_fsm_state` / `advance_fsm`) + the
+ * SessionEnd cleanup; tests.
+ */
+import { readFile, unlink } from 'node:fs/promises';
+import { atomicWriteFile } from './atomic_write.js';
+import { step } from './fsm.js';
+import { sessionStateFile } from './paths.js';
+function fsmKey(packName) {
+    return `fsm-${packName}`;
+}
+function isFsmStateFile(o) {
+    if (o === null || typeof o !== 'object')
+        return false;
+    const obj = o;
+    return typeof obj.state === 'string' && Array.isArray(obj.history);
+}
+/**
+ * Read the persisted current state for `(session, pack)`. Defaults to
+ * `fsm.initial` when absent/unreadable/malformed, OR when the persisted state
+ * is no longer a declared state (the pack's FSM changed) — a self-healing
+ * no-throw read matching `readChainStage`.
+ */
+export async function readFsmState(sessionId, packName, fsm) {
+    try {
+        const raw = await readFile(sessionStateFile(sessionId, fsmKey(packName)), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (isFsmStateFile(parsed) && fsm.states.includes(parsed.state)) {
+            return parsed.state;
+        }
+    }
+    catch {
+        // ENOENT / parse error → fall through to initial.
+    }
+    return fsm.initial;
+}
+/**
+ * Advance `(session, pack)`'s FSM on `event`. Reads the current state, runs the
+ * total `step`, and — ONLY when the state actually transitions — persists the
+ * new state + appends to history. A no-op event (no matching transition, or a
+ * guard that fails) leaves the file untouched and returns `transitioned:false`.
+ * Returns the full `StepResult` so the caller can react to `via`/`transitioned`.
+ *
+ * `now` (ISO string) is supplied by the caller for determinism; `evalWhen`
+ * evaluates a transition's `when` guard (caller wires the expression engine).
+ */
+export async function advanceFsmState(sessionId, packName, fsm, event, now, evalWhen) {
+    const current = await readFsmState(sessionId, packName, fsm);
+    const result = step(fsm, current, event, evalWhen);
+    if (result.transitioned) {
+        let history = [];
+        try {
+            const raw = await readFile(sessionStateFile(sessionId, fsmKey(packName)), 'utf8');
+            const parsed = JSON.parse(raw);
+            if (isFsmStateFile(parsed))
+                history = parsed.history;
+        }
+        catch {
+            // no prior file — fresh history.
+        }
+        const next = {
+            state: result.next,
+            started_at: now,
+            history: [...history, { state: result.next, at: now }],
+        };
+        await atomicWriteFile(sessionStateFile(sessionId, fsmKey(packName)), JSON.stringify(next, null, 2));
+    }
+    return result;
+}
+/**
+ * Read the persisted state string for `(session, pack)` WITHOUT needing the
+ * pack's FSM definition — for CROSS-PACK reads where one pack's rule queries
+ * another pack's lifecycle state (e.g. a pack gating on the workflow stage).
+ * Returns null when the machine hasn't started (file absent) or is unreadable,
+ * so the caller distinguishes "no state yet" from any concrete state.
+ */
+export async function readFsmStateRaw(sessionId, packName) {
+    try {
+        const raw = await readFile(sessionStateFile(sessionId, fsmKey(packName)), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (isFsmStateFile(parsed))
+            return parsed.state;
+    }
+    catch {
+        // absent / parse error → null
+    }
+    return null;
+}
+/** Remove a pack's FSM-state file (SessionEnd cleanup). ENOENT swallowed. */
+export async function clearFsmState(sessionId, packName) {
+    try {
+        await unlink(sessionStateFile(sessionId, fsmKey(packName)));
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+    }
+}
+//# sourceMappingURL=fsm_state.js.map

package/dist/runtime/fsm_state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fsm_state.js","sourceRoot":"","sources":["../../src/runtime/fsm_state.ts"],"names":[],"mappings":"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"}

package/dist/runtime/handoff/collect.d.ts

@@ -0,0 +1,64 @@
+/**
+ * T-AUTO-HANDOFF — deterministic state collection (the dump IS the handoff).
+ *
+ * Reads EVERY resumable-state source for a session from DISK (user-locked:
+ * "hand-off needs all the information"; generators read disk state, never a
+ * session's narrative — the 2026-06-10 "v4 on disk" false-claim precedent).
+ * Every probe is bounded: a missing/corrupt source renders as an
+ * `<unreadable: …>` marker instead of aborting — totality over completeness.
+ *
+ * Imports from: node:crypto, node:fs/promises, node:child_process,
+ *   ../paths.js, ../session_state.js, ../phase_ledger.js,
+ *   ../../channels/routing.js, ../../workgraph/store.js.
+ * Imported by: handoff/index.ts, handoff/render.ts (types).
+ */
+import { basename } from 'node:path';
+import { type ActiveTask } from '../session_state.js';
+export interface HandoffArtifact {
+    kind: 'pre_research' | 'spec';
+    path: string;
+    sha8: string | null;
+}
+export interface HandoffGitRepo {
+    repo: string;
+    statusShort: string;
+    unpushed: string;
+}
+export interface HandoffState {
+    sessionId: string;
+    generatedAt: string;
+    cwd: string;
+    umbrellaRoot: string;
+    fsm: Record<string, unknown> | string;
+    activeTask: ActiveTask | null | string;
+    phaseSet: Record<string, unknown> | string;
+    phaseLedger: {
+        phase: string;
+        note: string;
+    }[] | string;
+    guessAuditHead: string;
+    specAuditHead: string;
+    spawnLedgerTail: string[];
+    attestationsTail: string[];
+    artifacts: HandoffArtifact[];
+    git: HandoffGitRepo[];
+    openIssues: {
+        id: string;
+        title: string;
+    }[] | string;
+}
+/** The umbrella ROOT for a cwd: pick the umbrella ROW by longest member
+ *  prefix (correct row when rows nest), then return that row's SHORTEST
+ *  member containing the cwd — the umbrella root, not the sub-repo (live
+ *  spike finding: loop lists both `…/loop` and `…/loop/opensquid` as
+ *  members; docs + MEMORY.md belong at the loop root). Falls back to cwd. */
+export declare function umbrellaRootFor(cwd: string): Promise<string>;
+export declare function collectHandoffState(sessionId: string, cwd: string): Promise<HandoffState>;
+/** Stable doc path for a session's handover — keyed on sid ONLY (AHO.3:
+ *  date-keying minted a second doc for the same session across midnight and
+ *  broke the tier-3 staleness probe; generatedAt rides inside the doc). */
+export declare function handoverDocPath(umbrellaRoot: string, sessionId: string): string;
+/** Re-export for callers building ids/labels. */
+export declare function shortSid(sessionId: string): string;
+export { basename as _basename };
+//# sourceMappingURL=collect.d.ts.map

package/dist/runtime/handoff/collect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collect.d.ts","sourceRoot":"","sources":["../../../src/runtime/handoff/collect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,EAAE,QAAQ,EAAQ,MAAM,WAAW,CAAC;AAY3C,OAAO,EAAE,KAAK,UAAU,EAAkB,MAAM,qBAAqB,CAAC;AAItE,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,cAAc,GAAG,MAAM,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC;IACtC,UAAU,EAAE,UAAU,GAAG,IAAI,GAAG,MAAM,CAAC;IACvC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC;IAC3C,WAAW,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,GAAG,MAAM,CAAC;IACxD,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,GAAG,EAAE,cAAc,EAAE,CAAC;IACtB,UAAU,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,GAAG,MAAM,CAAC;CACtD;AAkED;;;;6EAI6E;AAC7E,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA4BlE;AAwBD,wBAAsB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CA2E/F;AAED;;2EAE2E;AAC3E,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAE/E;AAED,iDAAiD;AACjD,wBAAgB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,OAAO,EAAE,QAAQ,IAAI,SAAS,EAAE,CAAC"}

package/dist/runtime/handoff/collect.js

@@ -0,0 +1,211 @@
+/**
+ * T-AUTO-HANDOFF — deterministic state collection (the dump IS the handoff).
+ *
+ * Reads EVERY resumable-state source for a session from DISK (user-locked:
+ * "hand-off needs all the information"; generators read disk state, never a
+ * session's narrative — the 2026-06-10 "v4 on disk" false-claim precedent).
+ * Every probe is bounded: a missing/corrupt source renders as an
+ * `<unreadable: …>` marker instead of aborting — totality over completeness.
+ *
+ * Imports from: node:crypto, node:fs/promises, node:child_process,
+ *   ../paths.js, ../session_state.js, ../phase_ledger.js,
+ *   ../../channels/routing.js, ../../workgraph/store.js.
+ * Imported by: handoff/index.ts, handoff/render.ts (types).
+ */
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { promisify } from 'node:util';
+import { loadChannelsConfig } from '../../channels/routing.js';
+import { workGraphStore } from '../../workgraph/store.js';
+import { readPhaseLedger } from '../phase_ledger.js';
+import { OPENSQUID_HOME, resolveProjectScopeRoot, sessionLogFile, sessionStateFile, } from '../paths.js';
+import { readActiveTask } from '../session_state.js';
+const execFileP = promisify(execFile);
+async function bounded(probe) {
+    try {
+        return await probe();
+    }
+    catch (e) {
+        return `<unreadable: ${e instanceof Error ? e.message : String(e)}>`;
+    }
+}
+async function readJsonState(sessionId, key) {
+    return bounded(async () => JSON.parse(await readFile(sessionStateFile(sessionId, key), 'utf8')));
+}
+/** First N chars of a cached audit verdict (or an absent/unreadable marker). */
+async function auditHead(sessionId, key, n = 600) {
+    const parsed = await readJsonState(sessionId, key);
+    if (typeof parsed === 'string')
+        return parsed; // <unreadable: …>
+    const verdict = parsed.verdict;
+    return typeof verdict === 'string' ? verdict.slice(0, n) : '<no verdict field>';
+}
+async function tailLines(path, n) {
+    try {
+        const raw = await readFile(path, 'utf8');
+        return raw.trim().split('\n').slice(-n);
+    }
+    catch {
+        return [];
+    }
+}
+/** A tracked artifact path + its content hash (null when unreadable — the
+ *  successor then knows the artifact is NOT on disk, the 87ccd846 lesson). */
+async function artifactOf(sessionId, key, kind) {
+    const parsed = await readJsonState(sessionId, key);
+    if (typeof parsed !== 'string' && typeof parsed === 'object' && parsed !== null) {
+        // state files store the bare path as a JSON string; readJsonState parses it
+    }
+    const path = typeof parsed === 'string' && !parsed.startsWith('<unreadable') ? parsed : null;
+    const fromJson = typeof parsed === 'string' ? null : parsed;
+    const p = path ?? (typeof fromJson === 'string' ? fromJson : null);
+    if (p === null)
+        return null;
+    try {
+        const sha8 = createHash('sha256')
+            .update(await readFile(p, 'utf8'))
+            .digest('hex')
+            .slice(0, 8);
+        return { kind, path: p, sha8 };
+    }
+    catch {
+        return { kind, path: p, sha8: null };
+    }
+}
+/** The umbrella ROOT for a cwd: pick the umbrella ROW by longest member
+ *  prefix (correct row when rows nest), then return that row's SHORTEST
+ *  member containing the cwd — the umbrella root, not the sub-repo (live
+ *  spike finding: loop lists both `…/loop` and `…/loop/opensquid` as
+ *  members; docs + MEMORY.md belong at the loop root). Falls back to cwd. */
+export async function umbrellaRootFor(cwd) {
+    try {
+        const cfg = await loadChannelsConfig();
+        if (cfg !== null) {
+            let bestRow = null;
+            let bestLen = -1;
+            for (const u of cfg.umbrellas) {
+                for (const m of u.members) {
+                    if ((cwd === m || cwd.startsWith(`${m}/`)) && m.length > bestLen) {
+                        bestRow = u;
+                        bestLen = m.length;
+                    }
+                }
+            }
+            if (bestRow !== null) {
+                let root = null;
+                for (const m of bestRow.members) {
+                    if ((cwd === m || cwd.startsWith(`${m}/`)) && (root === null || m.length < root.length)) {
+                        root = m;
+                    }
+                }
+                if (root !== null)
+                    return root;
+            }
+        }
+    }
+    catch {
+        /* fall through */
+    }
+    return cwd;
+}
+async function gitRepo(dir) {
+    try {
+        const { stdout: status } = await execFileP('git', ['status', '--short'], {
+            cwd: dir,
+            timeout: 10_000,
+        });
+        let unpushed = '';
+        try {
+            const { stdout } = await execFileP('git', ['log', '--oneline', '@{u}..'], {
+                cwd: dir,
+                timeout: 10_000,
+            });
+            unpushed = stdout.trim();
+        }
+        catch {
+            unpushed = '<no upstream>';
+        }
+        return { repo: dir, statusShort: status.trimEnd(), unpushed };
+    }
+    catch {
+        return null; // not a git repo / git unavailable — skip silently
+    }
+}
+export async function collectHandoffState(sessionId, cwd) {
+    const umbrellaRoot = await umbrellaRootFor(cwd);
+    const activeRaw = await bounded(async () => readActiveTask(sessionId));
+    const activeTask = activeRaw;
+    const taskId = activeTask !== null && typeof activeTask === 'object' ? (activeTask.taskId ?? null) : null;
+    const phaseLedger = taskId === null
+        ? '<no active task>'
+        : await bounded(async () => {
+            const ledger = await readPhaseLedger(taskId);
+            return ledger.entries.map((e) => ({
+                phase: e.phase,
+                note: typeof e.note === 'string' ? e.note : '',
+            }));
+        });
+    const artifacts = (await Promise.all([
+        artifactOf(sessionId, 'coding-flow-pre-research-path', 'pre_research'),
+        artifactOf(sessionId, 'coding-flow-spec-path', 'spec'),
+    ])).filter((a) => a !== null);
+    // Git sweep: umbrella members (when channels.json names them) else just cwd.
+    const memberDirs = new Set([umbrellaRoot]);
+    try {
+        const cfg = await loadChannelsConfig();
+        for (const u of cfg?.umbrellas ?? []) {
+            for (const m of u.members) {
+                if (m === umbrellaRoot || m.startsWith(`${umbrellaRoot}/`))
+                    memberDirs.add(m);
+            }
+        }
+    }
+    catch {
+        /* cwd-only sweep */
+    }
+    // Known sub-repos: direct children of the umbrella root that are git repos
+    // are NOT auto-discovered (bounded sweep) — members + root only.
+    const git = (await Promise.all([...memberDirs].map(gitRepo))).filter((g) => g !== null);
+    const scopeRoot = await resolveProjectScopeRoot(cwd);
+    const attestationsTail = scopeRoot === null ? [] : await tailLines(join(scopeRoot, 'attestations.jsonl'), 5);
+    const openIssues = await bounded(async () => {
+        const store = workGraphStore({
+            dbUrl: `file:${join(OPENSQUID_HOME(), 'workgraph.db')}`,
+            sourceDir: join(OPENSQUID_HOME(), 'store', 'issues'),
+        });
+        await store.init();
+        const issues = await store.listIssues();
+        return issues.filter((i) => i.status !== 'closed').map((i) => ({ id: i.id, title: i.title }));
+    });
+    return {
+        sessionId,
+        generatedAt: new Date().toISOString(),
+        cwd,
+        umbrellaRoot,
+        fsm: await readJsonState(sessionId, 'fsm-coding-flow'),
+        activeTask,
+        phaseSet: await readJsonState(sessionId, 'workflow.phases_logged'),
+        phaseLedger,
+        guessAuditHead: await auditHead(sessionId, 'coding-flow-guess-audit-cache'),
+        specAuditHead: await auditHead(sessionId, 'coding-flow-spec-audit-cache'),
+        spawnLedgerTail: await tailLines(sessionLogFile(sessionId, 'audit-spawn-ledger'), 5),
+        attestationsTail,
+        artifacts,
+        git,
+        openIssues,
+    };
+}
+/** Stable doc path for a session's handover — keyed on sid ONLY (AHO.3:
+ *  date-keying minted a second doc for the same session across midnight and
+ *  broke the tier-3 staleness probe; generatedAt rides inside the doc). */
+export function handoverDocPath(umbrellaRoot, sessionId) {
+    return join(umbrellaRoot, 'docs', `handover-session-${sessionId.slice(0, 8)}-auto.md`);
+}
+/** Re-export for callers building ids/labels. */
+export function shortSid(sessionId) {
+    return sessionId.slice(0, 8);
+}
+export { basename as _basename };
+//# sourceMappingURL=collect.js.map

package/dist/runtime/handoff/collect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collect.js","sourceRoot":"","sources":["../../../src/runtime/handoff/collect.ts"],"names":[],"mappings":"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"}

package/dist/runtime/handoff/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * T-AUTO-HANDOFF — orchestration: collect → write all four surfaces.
+ *
+ * Three triggers share this one entry:
+ *   1. `opensquid handoff` (cli.ts) — primary.
+ *   2. SessionEnd hook — automatic backup (best-effort, after existing work).
+ *   3. SessionStart lazy generation (handoff_session_start function) — the
+ *      wedge-proof safety net for sessions that died without either trigger.
+ *
+ * Imports from: ./collect.js, ./write.js.
+ * Imported by: src/cli.ts, src/runtime/hooks/session-end.ts,
+ *   src/functions/handoff_session_start.ts.
+ */
+import { type WriteHandoffResult } from './write.js';
+export { handoverDocPath, umbrellaRootFor } from './collect.js';
+export { renderInjection } from './render.js';
+export type { WriteHandoffResult } from './write.js';
+export declare function runHandoff(sessionId: string, cwd: string, opts?: {
+    narrate?: boolean;
+}): Promise<WriteHandoffResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/handoff/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/runtime/handoff/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,EAAE,KAAK,kBAAkB,EAAwB,MAAM,YAAY,CAAC;AAE3E,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,wBAAsB,UAAU,CAC9B,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAC/B,OAAO,CAAC,kBAAkB,CAAC,CAW7B"}

package/dist/runtime/handoff/index.js

@@ -0,0 +1,33 @@
+/**
+ * T-AUTO-HANDOFF — orchestration: collect → write all four surfaces.
+ *
+ * Three triggers share this one entry:
+ *   1. `opensquid handoff` (cli.ts) — primary.
+ *   2. SessionEnd hook — automatic backup (best-effort, after existing work).
+ *   3. SessionStart lazy generation (handoff_session_start function) — the
+ *      wedge-proof safety net for sessions that died without either trigger.
+ *
+ * Imports from: ./collect.js, ./write.js.
+ * Imported by: src/cli.ts, src/runtime/hooks/session-end.ts,
+ *   src/functions/handoff_session_start.ts.
+ */
+import { collectHandoffState } from './collect.js';
+import { narrateHandoff } from './narrate.js';
+import { renderHandoverDoc } from './render.js';
+import { writeHandoffSurfaces } from './write.js';
+export { handoverDocPath, umbrellaRootFor } from './collect.js';
+export { renderInjection } from './render.js';
+export async function runHandoff(sessionId, cwd, opts = {}) {
+    const state = await collectHandoffState(sessionId, cwd);
+    // AHO.2 — explicit-command-only narrative; ANY model failure → skip with a
+    // note. The SessionEnd backup + SessionStart lazy-gen call runHandoff
+    // WITHOUT opts and stay fully deterministic.
+    if (opts.narrate === true) {
+        const n = await narrateHandoff(renderHandoverDoc(state));
+        if (n !== null)
+            return writeHandoffSurfaces(state, { narrative: n });
+        process.stderr.write('opensquid handoff: narrative skipped (model unavailable)\n');
+    }
+    return writeHandoffSurfaces(state);
+}
+//# sourceMappingURL=index.js.map

package/dist/runtime/handoff/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/runtime/handoff/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAA2B,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAE3E,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG9C,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,SAAiB,EACjB,GAAW,EACX,OAA8B,EAAE;IAEhC,MAAM,KAAK,GAAG,MAAM,mBAAmB,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IACxD,2EAA2E;IAC3E,sEAAsE;IACtE,6CAA6C;IAC7C,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;QAC1B,MAAM,CAAC,GAAG,MAAM,cAAc,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAC;QACzD,IAAI,CAAC,KAAK,IAAI;YAAE,OAAO,oBAAoB,CAAC,KAAK,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC;QACrE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,4DAA4D,CAAC,CAAC;IACrF,CAAC;IACD,OAAO,oBAAoB,CAAC,KAAK,CAAC,CAAC;AACrC,CAAC"}

package/dist/runtime/handoff/narrate.d.ts

@@ -0,0 +1,19 @@
+/**
+ * T-AUTO-HANDOFF AHO.2 — the narrative layer (NEVER load-bearing).
+ *
+ * One bounded model call over the deterministic dump; ANY failure (unknown
+ * alias, spawn error, timeout, empty output) returns null and the handoff
+ * proceeds without narrative — the dump is the load-bearing record
+ * (user-locked). Explicit-command-only: the SessionEnd backup and the
+ * SessionStart lazy generator never call this (spawn exhaustion is exactly
+ * when automatic handoffs happen).
+ *
+ * Imports from: ../../models/dispatcher.js, ../../models/load_config.js.
+ * Imported by: handoff/index.ts.
+ */
+export declare function narrateHandoff(docBody: string, opts?: {
+    alias?: string;
+    timeoutMs?: number;
+    strategyCall?: (prompt: string) => Promise<string>;
+}): Promise<string | null>;
+//# sourceMappingURL=narrate.d.ts.map

package/dist/runtime/handoff/narrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"narrate.d.ts","sourceRoot":"","sources":["../../../src/runtime/handoff/narrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAeH,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;IACJ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CAC/C,GACL,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAgBxB"}