opensquid 0.5.395

package/dist/runtime/hooks/session_id.js

@@ -0,0 +1,186 @@
+/**
+ * Session-id resolution for hook binaries + the `.current-session` pointer.
+ *
+ * ROOT-CAUSE FIX (2026-05-26): the `stop` / `user-prompt-submit` /
+ * `pre-tool-use` hooks previously read the session id ONLY from
+ * `process.env.CLAUDE_SESSION_ID`, which Claude Code does not reliably set —
+ * it delivers `session_id` in the hook's stdin JSON payload (per the CC hook
+ * contract). The result: every session collapsed to the literal `'unknown'`
+ * bucket, so per-session state (the automation flag, the per-turn tool ledger)
+ * never keyed on the real session. `session-end.ts` was the only hook reading
+ * stdin correctly. `extractSessionId` centralizes the correct precedence:
+ * stdin `session_id` (snake) → `sessionId` (camel) → `CLAUDE_SESSION_ID` env
+ * (last-resort) → `'unknown'`.
+ *
+ * `.current-session` (at `OPENSQUID_HOME()/.current-session`) lets an
+ * out-of-band process — notably the `opensquid automation on|off` CLI run from
+ * a terminal that never receives the hook stdin — discover the live session id.
+ * The `user-prompt-submit` hook records it every turn (best-effort).
+ *
+ * Imports from: node:fs/promises, node:path, ../paths.js.
+ * Imported by: hooks/{stop,user-prompt-submit,pre-tool-use}.ts (resolve +
+ *   record); setup/cli/automation.ts (read).
+ */
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { OPENSQUID_HOME, projectCurrentSessionPath, resolveProjectUuid } from '../paths.js';
+/**
+ * Resolve the session id from a hook's raw stdin string. Precedence:
+ * stdin `session_id` → stdin `sessionId` → `CLAUDE_SESSION_ID` env → `'unknown'`.
+ * Never throws: a malformed/empty payload falls straight through to the env /
+ * `'unknown'` fallback so the calling hook stays fail-open.
+ */
+export function extractSessionId(raw) {
+    let obj = {};
+    try {
+        obj = JSON.parse(raw);
+    }
+    catch {
+        // fall through to env / 'unknown'
+    }
+    if (typeof obj.session_id === 'string' && obj.session_id !== '')
+        return obj.session_id;
+    if (typeof obj.sessionId === 'string' && obj.sessionId !== '')
+        return obj.sessionId;
+    const env = process.env.CLAUDE_SESSION_ID;
+    if (env !== undefined && env !== '')
+        return env;
+    return 'unknown';
+}
+/** Absolute path of the live-session pointer file. */
+export const currentSessionPath = () => join(OPENSQUID_HOME(), '.current-session');
+/**
+ * Record the live session id so out-of-band processes (the automation CLI) can
+ * target the session the hooks actually see. Best-effort: never throws, and
+ * never records the `'unknown'` sentinel (that would mislead the CLI).
+ */
+export async function recordCurrentSession(sessionId, cwd) {
+    // GF.2 — never record the synthetic sentinels: `unknown`/`''` (no real session) and
+    // `doctor-probe` (the id `opensquid doctor hooks` spawns its probe events with — it would
+    // otherwise CLOBBER the live `.current-session` pointer the git gate resolves against).
+    if (sessionId === 'unknown' || sessionId === '' || sessionId === 'doctor-probe')
+        return;
+    try {
+        await mkdir(OPENSQUID_HOME(), { recursive: true });
+        // Global pointer — back-compat for the automation CLI + lessons.ts (which
+        // read it without a project context). Last-writer-wins across all sessions.
+        await writeFile(currentSessionPath(), sessionId, 'utf-8');
+        // FU.3: project-scoped pointer — the race-free authority the MCP server
+        // reads. A concurrent session in ANOTHER project writes a different uuid's
+        // pointer and can't clobber this one. Skipped (no error) for a cwd that
+        // isn't inside a uuid-bound project (`.opensquid/project.json` absent).
+        if (cwd !== undefined && cwd !== '') {
+            const uuid = await resolveProjectUuid({ cwd });
+            if (uuid !== null) {
+                const scoped = projectCurrentSessionPath(uuid);
+                await mkdir(dirname(scoped), { recursive: true });
+                await writeFile(scoped, sessionId, 'utf-8');
+            }
+        }
+    }
+    catch {
+        // best-effort: a write failure must never break the hook
+    }
+}
+/** Read the global live session id, or `null` if absent/unreadable/empty. */
+export async function readCurrentSession() {
+    try {
+        const raw = (await readFile(currentSessionPath(), 'utf-8')).trim();
+        return raw === '' ? null : raw;
+    }
+    catch {
+        return null;
+    }
+}
+/** Read the project-scoped live session id, or `null` if absent/unreadable/empty. */
+export async function readProjectCurrentSession(projectUuid) {
+    try {
+        const raw = (await readFile(projectCurrentSessionPath(projectUuid), 'utf-8')).trim();
+        return raw === '' ? null : raw;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * FU.7 — does `sessions/<id>/` exist? The existence of the per-session dir
+ * (created by the session's own hooks when they first write state) is the
+ * signal that an id is a REAL persisted session, not a stale/`--resume` env id.
+ * Fail-false on any stat error (absent dir → ENOENT → false).
+ */
+async function sessionDirExists(id) {
+    try {
+        return (await stat(join(OPENSQUID_HOME(), 'sessions', id))).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Session resolution for MCP tools (the MCP server is a separate process from
+ * the hooks, so it can't read hook stdin).
+ *
+ * T-RJ-FOLLOWUPS FU.3 (2026-06-01) — CORRECTION to MS.1. MS.1 assumed Claude
+ * Code sets `CLAUDE_SESSION_ID` in the MCP server's env; it does NOT — that
+ * exact name is never set, so the env step never fired and resolution always
+ * fell through to the GLOBAL `.current-session`, which any concurrent session in
+ * any project clobbers (last-writer-wins) — silently breaking this session's
+ * `log_phase` mid-task.
+ *
+ * FU.4 correction: CC DOES expose a session-id env var to stdio MCP servers —
+ * `CLAUDE_CODE_SESSION_ID` (plus `CLAUDE_PROJECT_DIR`). But it is NOT safe to key
+ * on: under `--resume` it holds a NEW id that differs from the persisted /
+ * transcript / hook-stdin id the state actually lives under (observed live:
+ * env `6c7527de…` while state + transcript were under `1200bc00…`, whose
+ * `sessions/<id>/` dir is the real one). So resolving by the env session id
+ * would point at an EMPTY session under resume. The project-scoped pointer is
+ * correct precisely because the UPS hook writes it with the hook-stdin id — the
+ * same id the state uses. (Using `CLAUDE_CODE_SESSION_ID` *guarded by
+ * `sessions/<id>/` existence* to also kill the same-project race is FU.7.)
+ *
+ * Fix: resolve via the PROJECT-SCOPED pointer, keyed by `CLAUDE_PROJECT_DIR`
+ * (which CC DOES provide) → `resolveProjectUuid`. A concurrent session in
+ * another repo writes a different project's pointer and can't clobber this one.
+ *
+ * ⚠️ Residual (documented, not solved here): two concurrent CC sessions in the
+ * SAME project still share one project pointer and race. Rare; a
+ * most-recently-active-task tiebreak is a follow-up.
+ *
+ * Precedence:
+ *   1. `process.env.CLAUDE_SESSION_ID` (kept — harmless if CC ever sets it)
+ *   2. `process.env.OPENSQUID_SESSION_ID` (override / test seam)
+ *   3. `process.env.CLAUDE_CODE_SESSION_ID` GUARDED by `sessions/<id>/` existence
+ *      (FU.7) — CC's per-process id. When its session dir exists it is a real
+ *      persisted session, which disambiguates two concurrent sessions in the
+ *      SAME repo (distinct per-process ids → distinct dirs). Under `--resume`
+ *      the env id is NEW and has no dir → the guard fails → fall through (safe).
+ *   4. project-scoped pointer via `CLAUDE_PROJECT_DIR`→`resolveProjectUuid`
+ *      (race-free across projects — the real fix)
+ *   5. global `.current-session` (back-compat: single-session / no-project cwd)
+ */
+export async function resolveMcpSessionId() {
+    const env = process.env;
+    const fromClaudeEnv = env.CLAUDE_SESSION_ID;
+    if (fromClaudeEnv !== undefined && fromClaudeEnv.length > 0)
+        return fromClaudeEnv;
+    const fromOpensquidEnv = env.OPENSQUID_SESSION_ID;
+    if (fromOpensquidEnv !== undefined && fromOpensquidEnv.length > 0)
+        return fromOpensquidEnv;
+    // FU.7 — CC's per-process id, but ONLY when its session dir exists on disk
+    // (proves it's the id state actually lives under). Dir-less → --resume's new
+    // id → ignore, fall through to the project pointer.
+    const ccEnv = env.CLAUDE_CODE_SESSION_ID;
+    if (ccEnv !== undefined && ccEnv.length > 0 && (await sessionDirExists(ccEnv)))
+        return ccEnv;
+    const projectDir = env.CLAUDE_PROJECT_DIR;
+    if (projectDir !== undefined && projectDir.length > 0) {
+        const uuid = await resolveProjectUuid({ cwd: projectDir, env });
+        if (uuid !== null) {
+            const scoped = await readProjectCurrentSession(uuid);
+            if (scoped !== null)
+                return scoped;
+        }
+    }
+    return readCurrentSession();
+}
+//# sourceMappingURL=session_id.js.map

package/dist/runtime/hooks/session_id.js.map

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

package/dist/runtime/hooks/session_liveness.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Plausibility probe for a session id resolved from a stale-prone source
+ * (`.current-session` pointer). Stat-driven freshness check over the files
+ * the live PreToolUse hook continuously updates — `<home>/sessions/<id>/
+ * active-task.json` (mirror) and `state/tool-ledger.json` (per-tool append).
+ * Either one modified within `FRESH_MS` = live; both absent / older = stale.
+ *
+ * Caller (`automation.ts:resolveSessionId`) hard-fails on stale unless the
+ * user passes `--force` — the escape hatch for cases where the CLI is run
+ * before the first hook fires (otherwise legitimate; the `automation on` /
+ * `--session-id <id>` paths already bypass this probe entirely).
+ *
+ * The probe NEVER throws: an unreadable file is treated as "absent" so the
+ * loud-warn path catches a corrupted state dir too. It is also pure —
+ * no writes, no side effects, no env reads beyond `FRESH_MS()`.
+ *
+ * Imports from: node:fs/promises, ../paths.js.
+ * Imported by: src/setup/cli/automation.ts (the gate that uses it).
+ */
+/** Default freshness window: 30 minutes (`1_800_000` ms). */
+export declare const DEFAULT_FRESH_MS = 1800000;
+/**
+ * Resolve the freshness threshold from env, falling back to `DEFAULT_FRESH_MS`
+ * for unset / non-positive / non-numeric values. Read on every call (cheap,
+ * lets a wrapper script tune the window mid-session without re-import).
+ */
+export declare function FRESH_MS(): number;
+export interface PlausibilityResult {
+    /** `true` iff at least one probed file was modified within the window. */
+    plausible: boolean;
+    /** Most-recent mtime ms across probed files, or `null` if none readable. */
+    newestMtimeMs: number | null;
+    /** Absolute paths probed — surfaced in the CLI's stderr for actionability. */
+    probedFiles: string[];
+}
+export interface PlausibilityOpts {
+    /** Injected clock (tests). Defaults to `Date.now`. */
+    nowMs?: () => number;
+    /** Override the freshness window for one call (tests). Defaults to `FRESH_MS()`. */
+    freshMs?: number;
+}
+/**
+ * "Was this session id alive within the freshness window?" — yes iff any of
+ * the probed files has mtime within `freshMs` of `now`. Files missing or
+ * unreadable count as absent (NOT as errors); they just don't contribute a
+ * mtime.
+ */
+export declare function isSessionPlausible(sessionId: string, opts?: PlausibilityOpts): Promise<PlausibilityResult>;
+//# sourceMappingURL=session_liveness.d.ts.map

package/dist/runtime/hooks/session_liveness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session_liveness.d.ts","sourceRoot":"","sources":["../../../src/runtime/hooks/session_liveness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH,6DAA6D;AAC7D,eAAO,MAAM,gBAAgB,UAAY,CAAC;AAE1C;;;;GAIG;AACH,wBAAgB,QAAQ,IAAI,MAAM,CAKjC;AAED,MAAM,WAAW,kBAAkB;IACjC,0EAA0E;IAC1E,SAAS,EAAE,OAAO,CAAC;IACnB,4EAA4E;IAC5E,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,8EAA8E;IAC9E,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;IACrB,oFAAoF;IACpF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE,gBAAqB,GAC1B,OAAO,CAAC,kBAAkB,CAAC,CAqB7B"}

package/dist/runtime/hooks/session_liveness.js

@@ -0,0 +1,65 @@
+/**
+ * Plausibility probe for a session id resolved from a stale-prone source
+ * (`.current-session` pointer). Stat-driven freshness check over the files
+ * the live PreToolUse hook continuously updates — `<home>/sessions/<id>/
+ * active-task.json` (mirror) and `state/tool-ledger.json` (per-tool append).
+ * Either one modified within `FRESH_MS` = live; both absent / older = stale.
+ *
+ * Caller (`automation.ts:resolveSessionId`) hard-fails on stale unless the
+ * user passes `--force` — the escape hatch for cases where the CLI is run
+ * before the first hook fires (otherwise legitimate; the `automation on` /
+ * `--session-id <id>` paths already bypass this probe entirely).
+ *
+ * The probe NEVER throws: an unreadable file is treated as "absent" so the
+ * loud-warn path catches a corrupted state dir too. It is also pure —
+ * no writes, no side effects, no env reads beyond `FRESH_MS()`.
+ *
+ * Imports from: node:fs/promises, ../paths.js.
+ * Imported by: src/setup/cli/automation.ts (the gate that uses it).
+ */
+import { stat } from 'node:fs/promises';
+import { activeTaskFile, sessionStateFile } from '../paths.js';
+/** Default freshness window: 30 minutes (`1_800_000` ms). */
+export const DEFAULT_FRESH_MS = 1_800_000;
+/**
+ * Resolve the freshness threshold from env, falling back to `DEFAULT_FRESH_MS`
+ * for unset / non-positive / non-numeric values. Read on every call (cheap,
+ * lets a wrapper script tune the window mid-session without re-import).
+ */
+export function FRESH_MS() {
+    const raw = process.env.OPENSQUID_SESSION_FRESH_MS;
+    if (raw === undefined || raw === '')
+        return DEFAULT_FRESH_MS;
+    const n = Number.parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : DEFAULT_FRESH_MS;
+}
+/**
+ * "Was this session id alive within the freshness window?" — yes iff any of
+ * the probed files has mtime within `freshMs` of `now`. Files missing or
+ * unreadable count as absent (NOT as errors); they just don't contribute a
+ * mtime.
+ */
+export async function isSessionPlausible(sessionId, opts = {}) {
+    const now = (opts.nowMs ?? Date.now)();
+    const fresh = opts.freshMs ?? FRESH_MS();
+    // `tool-ledger` is written via `sessionStateFile` (suffix `.json`) per
+    // `runtime/session_state.ts:50,88` (LEDGER_KEY). It is NOT a JSONL log —
+    // do not reach for `sessionLogFile`, that would resolve to `.jsonl` and
+    // miss the real file.
+    const probedFiles = [activeTaskFile(sessionId), sessionStateFile(sessionId, 'tool-ledger')];
+    let newestMtimeMs = null;
+    for (const f of probedFiles) {
+        try {
+            const st = await stat(f);
+            const m = st.mtimeMs;
+            if (newestMtimeMs === null || m > newestMtimeMs)
+                newestMtimeMs = m;
+        }
+        catch {
+            // ENOENT / EACCES / etc. — treat as absent.
+        }
+    }
+    const plausible = newestMtimeMs !== null && now - newestMtimeMs < fresh;
+    return { plausible, newestMtimeMs, probedFiles };
+}
+//# sourceMappingURL=session_liveness.js.map

package/dist/runtime/hooks/session_liveness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session_liveness.js","sourceRoot":"","sources":["../../../src/runtime/hooks/session_liveness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAExC,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/D,6DAA6D;AAC7D,MAAM,CAAC,MAAM,gBAAgB,GAAG,SAAS,CAAC;AAE1C;;;;GAIG;AACH,MAAM,UAAU,QAAQ;IACtB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,0BAA0B,CAAC;IACnD,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,EAAE;QAAE,OAAO,gBAAgB,CAAC;IAC7D,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACnC,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC;AAC5D,CAAC;AAkBD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,SAAiB,EACjB,OAAyB,EAAE;IAE3B,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;IACvC,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,IAAI,QAAQ,EAAE,CAAC;IACzC,uEAAuE;IACvE,yEAAyE;IACzE,wEAAwE;IACxE,sBAAsB;IACtB,MAAM,WAAW,GAAG,CAAC,cAAc,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC,CAAC;IAE5F,IAAI,aAAa,GAAkB,IAAI,CAAC;IACxC,KAAK,MAAM,CAAC,IAAI,WAAW,EAAE,CAAC;QAC5B,IAAI,CAAC;YACH,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC;YACzB,MAAM,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC;YACrB,IAAI,aAAa,KAAK,IAAI,IAAI,CAAC,GAAG,aAAa;gBAAE,aAAa,GAAG,CAAC,CAAC;QACrE,CAAC;QAAC,MAAM,CAAC;YACP,4CAA4C;QAC9C,CAAC;IACH,CAAC;IACD,MAAM,SAAS,GAAG,aAAa,KAAK,IAAI,IAAI,GAAG,GAAG,aAAa,GAAG,KAAK,CAAC;IACxE,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,WAAW,EAAE,CAAC;AACnD,CAAC"}

package/dist/runtime/hooks/stop.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=stop.d.ts.map

package/dist/runtime/hooks/stop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stop.d.ts","sourceRoot":"","sources":["../../../src/runtime/hooks/stop.ts"],"names":[],"mappings":""}

package/dist/runtime/hooks/stop.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+/**
+ * Claude Code `Stop` hook binary.
+ *
+ * Fires when the assistant emits a stop turn (end of an assistant message).
+ * Payload carries the assistant's final text — used by destination-check
+ * rules to evaluate "did the agent stay on the goal."
+ *
+ * Wired in `~/.claude/settings.json`:
+ *
+ *   { "hooks": { "Stop": [{ "hooks": [{ "type": "command",
+ *     "command": "opensquid-hook-stop" }] }] } }
+ *
+ * stdin = stop event JSON. exit 0 = allow (continue session normally),
+ * exit 2 = block (in practice this surfaces a warning to the agent; the
+ * stop itself can't be "blocked"). Stderr messages are shown.
+ *
+ * Fail-open on any internal error — see `main().catch()` below.
+ */
+import { buildRegistry, loadActivePacks } from '../bootstrap.js';
+import { Event } from '../types.js';
+import { dispatchEvent } from './dispatch.js';
+import { extractSessionId } from './session_id.js';
+import { emitDriftStderrAndExit, squidPrefix } from './hook_output.js';
+import { claimUmbrellaLeaseForSession } from '../chat/claim_lease.js';
+import { maybeDriveInbound, maybePeekInbound, extractCwd } from './stop_drive.js';
+import { maybeStreamOutput } from './stop_stream.js';
+import { readLastAssistantText } from './transcript.js';
+function parsePayload(raw) {
+    const obj = JSON.parse(raw);
+    return {
+        kind: 'stop',
+        // Claude Code's Stop payload field name isn't 100% pinned across versions;
+        // accept camelCase, snake_case, or a generic `message` field.
+        assistantText: obj.assistantText ?? obj.assistant_text ?? obj.message ?? '',
+    };
+}
+/** Extract the transcript `.jsonl` path from a Stop payload (snake/camel). */
+function extractTranscriptPath(raw) {
+    try {
+        const obj = JSON.parse(raw);
+        const p = obj.transcript_path ?? obj.transcriptPath;
+        return typeof p === 'string' && p.length > 0 ? p : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function readStdin() {
+    let data = '';
+    for await (const chunk of process.stdin)
+        data += chunk;
+    return data;
+}
+async function main() {
+    const raw = await readStdin();
+    if (!raw.trim()) {
+        process.stderr.write('opensquid: empty Stop payload — proceeding\n');
+        process.exit(0);
+    }
+    let normalized;
+    try {
+        normalized = parsePayload(raw);
+    }
+    catch (e) {
+        process.stderr.write(`opensquid: invalid Stop JSON — ${String(e)}\n`);
+        process.exit(0);
+    }
+    const parsed = Event.safeParse(normalized);
+    if (!parsed.success) {
+        process.stderr.write('opensquid: invalid Stop payload schema\n');
+        process.exit(0);
+    }
+    // HH7.1: Claude Code omits the assistant response text from Stop stdin, so
+    // `assistantText` is empty here. Recover the last assistant message from the
+    // transcript `.jsonl` (CC always provides `transcript_path`) so Stop-event
+    // gates that read assistantText (honesty-ledger, phase-logging) see what was
+    // written instead of an empty string. Fail-open: a transcript-read failure
+    // leaves assistantText '' (pre-fix behavior), never crashes the hook.
+    // ⚠️ SG.3 caveat: this is off-by-one (returns the PRIOR response if the
+    // triggering one isn't flushed yet) — see transcript.ts. recall-consumed was
+    // removed for relying on this to judge its own triggering response.
+    if (parsed.data.kind === 'stop' && parsed.data.assistantText === '') {
+        const transcriptPath = extractTranscriptPath(raw);
+        if (transcriptPath !== null) {
+            parsed.data.assistantText = await readLastAssistantText(transcriptPath);
+        }
+    }
+    const sessionId = extractSessionId(raw);
+    const packs = await loadActivePacks(sessionId);
+    const registry = await buildRegistry();
+    const { exitCode, stderr } = await dispatchEvent(parsed.data, packs, registry, sessionId);
+    const cwd = extractCwd(raw);
+    // A drift BLOCK (exit≠0) still takes precedence — the run is NOT driven mid-run, so the
+    // no-pause discipline holds. But SURFACE any pending inbound in the drift stderr so a
+    // mid-run user message is never invisible (T-CHAT-INBOUND-SURFACE-MIDRUN). The peek is
+    // READ-ONLY (unacked), so the same message still DRIVES a proper response turn at the next
+    // clean stop (maybeDriveInbound below) — surfacing loses nothing.
+    if (exitCode !== 0) {
+        const peek = await maybePeekInbound(sessionId, cwd);
+        emitDriftStderrAndExit(exitCode, peek === null ? stderr : `${stderr}\n\n${peek}`);
+    }
+    // Interactive responder: this live session claims its umbrella's chat lease
+    // (acquire-if-free) so the drive below owns the turn + the headless stands
+    // down. No-op in `responder: headless` mode or when another session holds it.
+    await claimUmbrellaLeaseForSession(sessionId, cwd);
+    // CAT.3 — "see": if THIS just-completed turn was chat-driven (CAT.2 left the
+    // marker), stream the agent's answer back to the source topic automatically
+    // (reply-to-source; the agent never picks the channel). No-op otherwise.
+    const assistantText = parsed.data.kind === 'stop' ? parsed.data.assistantText : '';
+    await maybeStreamOutput(sessionId, cwd, assistantText);
+    // CAT.2 — "drive": if this session holds the umbrella's chat lease and has
+    // unacked inbound, block the stop and feed the inbound as the next turn so a
+    // chat message DRIVES a turn without a keystroke (the remote-terminal "drive").
+    const driveReason = await maybeDriveInbound(sessionId, cwd);
+    if (driveReason !== null) {
+        if (stderr.length > 0)
+            process.stderr.write(squidPrefix(stderr) + '\n');
+        process.stdout.write(JSON.stringify({ decision: 'block', reason: driveReason }) + '\n');
+        process.exit(0);
+    }
+    emitDriftStderrAndExit(0, stderr);
+}
+main().catch((e) => {
+    process.stderr.write(`opensquid hook crash (stop): ${String(e)}\n`);
+    process.exit(0);
+});
+//# sourceMappingURL=stop.js.map

package/dist/runtime/hooks/stop.js.map

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

package/dist/runtime/hooks/stop_drive.d.ts

@@ -0,0 +1,37 @@
+/**
+ * CAT.2 — Stop-hook inbound drive (extracted from the `stop.ts` bin so it is
+ * unit-testable; the bin self-runs `main()` on import).
+ *
+ * `maybeDriveInbound` decides whether a finished turn should be turned back
+ * into a new turn by an inbound chat message: it returns the block `reason`
+ * (the umbrella inbox envelope) when THIS session holds its umbrella's chat
+ * lease AND has unacked inbound; null otherwise. The Stop bin, on a clean
+ * (no-drift) stop, emits `{decision:'block', reason}` when this returns
+ * non-null — blocking the stop and feeding the inbound as the next turn.
+ *
+ * Lease gate (invariant #6): only the umbrella's live (lease-holding) session
+ * drives — a second same-umbrella session stays local-only, so a chat message
+ * drives exactly one session. The drain ACKS-BEFORE-RETURN, so a driven message
+ * never re-drives (the durable loop guard). Fail-open: null on any error.
+ *
+ * Imports from: ../../channels/routing, ../chat/inbox_drain, ../chat/session_routing.
+ * Imported by: src/runtime/hooks/stop.ts + tests.
+ */
+/** Extract the session cwd from a Stop payload (Claude Code provides `cwd`). */
+export declare function extractCwd(raw: string): string;
+/**
+ * Return the inbound envelope to drive a turn on (block `reason`), or null.
+ * See the module header for the lease + ack semantics.
+ */
+export declare function maybeDriveInbound(sessionId: string, cwd: string): Promise<string | null>;
+/**
+ * READ-ONLY twin of {@link maybeDriveInbound} (T-CHAT-INBOUND-SURFACE-MIDRUN SF.2).
+ * Returns the umbrella inbox envelope for the lease-holding session WITHOUT acking and
+ * WITHOUT marking the turn chat-driven — for the Stop hook's drift branch to SURFACE a
+ * mid-run user message in the drift stderr while the run continues. Because it does not ack,
+ * the message still DRIVES a proper response turn at the next clean stop (via
+ * `maybeDriveInbound`). Lease-gated like the drive (only the live session surfaces, so a
+ * second same-umbrella session never double-surfaces). Fail-open: null on any error.
+ */
+export declare function maybePeekInbound(sessionId: string, cwd: string): Promise<string | null>;
+//# sourceMappingURL=stop_drive.d.ts.map

package/dist/runtime/hooks/stop_drive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stop_drive.d.ts","sourceRoot":"","sources":["../../../src/runtime/hooks/stop_drive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAQH,gFAAgF;AAChF,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAO9C;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiB9F;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAa7F"}

package/dist/runtime/hooks/stop_drive.js

@@ -0,0 +1,86 @@
+/**
+ * CAT.2 — Stop-hook inbound drive (extracted from the `stop.ts` bin so it is
+ * unit-testable; the bin self-runs `main()` on import).
+ *
+ * `maybeDriveInbound` decides whether a finished turn should be turned back
+ * into a new turn by an inbound chat message: it returns the block `reason`
+ * (the umbrella inbox envelope) when THIS session holds its umbrella's chat
+ * lease AND has unacked inbound; null otherwise. The Stop bin, on a clean
+ * (no-drift) stop, emits `{decision:'block', reason}` when this returns
+ * non-null — blocking the stop and feeding the inbound as the next turn.
+ *
+ * Lease gate (invariant #6): only the umbrella's live (lease-holding) session
+ * drives — a second same-umbrella session stays local-only, so a chat message
+ * drives exactly one session. The drain ACKS-BEFORE-RETURN, so a driven message
+ * never re-drives (the durable loop guard). Fail-open: null on any error.
+ *
+ * Imports from: ../../channels/routing, ../chat/inbox_drain, ../chat/session_routing.
+ * Imported by: src/runtime/hooks/stop.ts + tests.
+ */
+import { loadChannelsConfig, resolveUmbrellaForCwd } from '../../channels/routing.js';
+import { drainUmbrellaInbox, peekUmbrellaInbox } from '../chat/inbox_drain.js';
+import { resolveLiveSessionId } from '../chat/session_routing.js';
+import { markChatDriven } from './stop_stream.js';
+/** Extract the session cwd from a Stop payload (Claude Code provides `cwd`). */
+export function extractCwd(raw) {
+    try {
+        const obj = JSON.parse(raw);
+        return typeof obj.cwd === 'string' && obj.cwd.length > 0 ? obj.cwd : process.cwd();
+    }
+    catch {
+        return process.cwd();
+    }
+}
+/**
+ * Return the inbound envelope to drive a turn on (block `reason`), or null.
+ * See the module header for the lease + ack semantics.
+ */
+export async function maybeDriveInbound(sessionId, cwd) {
+    try {
+        const cfg = await loadChannelsConfig().catch(() => null);
+        const umbrellaId = cfg === null ? null : resolveUmbrellaForCwd(cfg, cwd);
+        if (umbrellaId === null || umbrellaId === '')
+            return null;
+        // Lease holder = delivery target. Only the umbrella's live session drives.
+        const live = await resolveLiveSessionId(umbrellaId);
+        if (live !== sessionId)
+            return null;
+        const envelope = await drainUmbrellaInbox(sessionId, cwd);
+        if (envelope.length === 0)
+            return null;
+        // CAT.3: mark this umbrella's turn chat-driven so the NEXT Stop streams the
+        // agent's answer back to the source topic.
+        await markChatDriven(umbrellaId, sessionId);
+        return envelope;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * READ-ONLY twin of {@link maybeDriveInbound} (T-CHAT-INBOUND-SURFACE-MIDRUN SF.2).
+ * Returns the umbrella inbox envelope for the lease-holding session WITHOUT acking and
+ * WITHOUT marking the turn chat-driven — for the Stop hook's drift branch to SURFACE a
+ * mid-run user message in the drift stderr while the run continues. Because it does not ack,
+ * the message still DRIVES a proper response turn at the next clean stop (via
+ * `maybeDriveInbound`). Lease-gated like the drive (only the live session surfaces, so a
+ * second same-umbrella session never double-surfaces). Fail-open: null on any error.
+ */
+export async function maybePeekInbound(sessionId, cwd) {
+    try {
+        const cfg = await loadChannelsConfig().catch(() => null);
+        const umbrellaId = cfg === null ? null : resolveUmbrellaForCwd(cfg, cwd);
+        if (umbrellaId === null || umbrellaId === '')
+            return null;
+        // Lease holder = delivery target. Only the umbrella's live session surfaces.
+        const live = await resolveLiveSessionId(umbrellaId);
+        if (live !== sessionId)
+            return null;
+        const envelope = await peekUmbrellaInbox(sessionId, cwd);
+        return envelope.length === 0 ? null : envelope;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=stop_drive.js.map

package/dist/runtime/hooks/stop_drive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stop_drive.js","sourceRoot":"","sources":["../../../src/runtime/hooks/stop_drive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AACtF,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC/E,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAElE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,gFAAgF;AAChF,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAqB,CAAC;QAChD,OAAO,OAAO,GAAG,CAAC,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC;IACrF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAC,GAAG,EAAE,CAAC;IACvB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,SAAiB,EAAE,GAAW;IACpE,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,kBAAkB,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;QACzD,MAAM,UAAU,GAAG,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,qBAAqB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACzE,IAAI,UAAU,KAAK,IAAI,IAAI,UAAU,KAAK,EAAE;YAAE,OAAO,IAAI,CAAC;QAC1D,2EAA2E;QAC3E,MAAM,IAAI,GAAG,MAAM,oBAAoB,CAAC,UAAU,CAAC,CAAC;QACpD,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QACpC,MAAM,QAAQ,GAAG,MAAM,kBAAkB,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;QAC1D,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QACvC,4EAA4E;QAC5E,2CAA2C;QAC3C,MAAM,cAAc,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;QAC5C,OAAO,QAAQ,CAAC;IAClB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,SAAiB,EAAE,GAAW;IACnE,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,kBAAkB,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;QACzD,MAAM,UAAU,GAAG,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,qBAAqB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACzE,IAAI,UAAU,KAAK,IAAI,IAAI,UAAU,KAAK,EAAE;YAAE,OAAO,IAAI,CAAC;QAC1D,6EAA6E;QAC7E,MAAM,IAAI,GAAG,MAAM,oBAAoB,CAAC,UAAU,CAAC,CAAC;QACpD,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QACpC,MAAM,QAAQ,GAAG,MAAM,iBAAiB,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;QACzD,OAAO,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC;IACjD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/runtime/hooks/stop_stream.d.ts

@@ -0,0 +1,32 @@
+/**
+ * CAT.3 — stream a chat-driven turn's OUTPUT back to its source topic.
+ *
+ * The symmetric half of CAT.2's drive. When CAT.2 drives a turn from an inbound
+ * chat message it leaves a marker (`markChatDriven`); when that turn completes,
+ * the Stop hook calls `maybeStreamOutput`, which — if the marker matches THIS
+ * session — sends the assistant's final text to the umbrella's outbound Telegram
+ * target (`resolveOutbound`, reply-to-source — the agent never picks the
+ * channel) and consumes the marker. Terminal-driven turns leave no marker, so
+ * they don't stream (chat-IN → chat-OUT; terminal-IN stays terminal — no flood).
+ *
+ * Outbound goes through the SAME daemon `send` RPC as `chat_send`
+ * (`defaultDaemonSend`), so it honors the one transport + the border invariant.
+ * Fail-open: any error / no umbrella / no marker / empty text → no send.
+ *
+ * Imports from: node:fs/promises, ../../channels/routing, ../paths,
+ *   ../agent_bridge/tools/chat_send (the daemon-send seam).
+ * Imported by: src/runtime/hooks/{stop,stop_drive}.ts + tests.
+ */
+import type { DaemonSendFn } from '../agent_bridge/tools/chat_send.js';
+/**
+ * Mark that the lease-holding `sessionId` just had a turn DRIVEN from chat for
+ * `umbrellaId`; the next Stop will stream that turn's output back. Best-effort.
+ */
+export declare function markChatDriven(umbrellaId: string, sessionId: string): Promise<void>;
+/**
+ * If this session's just-completed turn was chat-driven, stream `assistantText`
+ * to the umbrella's source topic and consume the marker. Returns true iff it
+ * sent. `send` is injectable for tests (defaults to the daemon RPC).
+ */
+export declare function maybeStreamOutput(sessionId: string, cwd: string, assistantText: string, send?: DaemonSendFn): Promise<boolean>;
+//# sourceMappingURL=stop_stream.d.ts.map

package/dist/runtime/hooks/stop_stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stop_stream.d.ts","sourceRoot":"","sources":["../../../src/runtime/hooks/stop_stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAUH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAIvE;;;GAGG;AACH,wBAAsB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQzF;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,aAAa,EAAE,MAAM,EACrB,IAAI,GAAE,YAAgC,GACrC,OAAO,CAAC,OAAO,CAAC,CA4BlB"}