opensquid 0.5.395

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

@@ -0,0 +1,65 @@
+/**
+ * MM.2 — Pure-function resolver for `next_action.profession` directives.
+ *
+ * Given a directive whose `next_action.profession` names a pack + the loaded
+ * pack registry + a pre-staged `teamsByPack` map, validates that the pack
+ * exists, is profession-usage, and has at least one role defined in its
+ * team.yaml. Returns a tagged result.
+ *
+ * **opensquid never invokes `spawn_subagent` itself** per
+ * [[project_opensquid_no_agent_loop]] — this resolver only validates the
+ * directive is well-formed before the dispatcher aggregates it onto the
+ * UserPromptSubmit envelope. The AGENT then calls `spawn_subagent` on the
+ * profession pack named by the directive.
+ *
+ * Fail-open in the SAFE direction: an invalid profession → directive DROPPED
+ * (not emitted to the agent) + a warning is logged at the caller. Emitting a
+ * directive for a non-existent / misconfigured profession would mislead the
+ * agent.
+ *
+ * Imports: types only (zero I/O). Imported by: `src/runtime/hooks/dispatch.ts`
+ * + tests.
+ */
+import type { Team } from '../../packs/schemas/team.js';
+import type { NextAction, Pack } from '../types.js';
+export type ProfessionResolutionError = {
+    code: 'unknown-pack';
+    packName: string;
+} | {
+    code: 'wrong-usage';
+    packName: string;
+    actualUsage: string;
+} | {
+    code: 'missing-team';
+    packName: string;
+} | {
+    code: 'no-roles';
+    packName: string;
+} | {
+    code: 'role-not-found';
+    packName: string;
+    requestedRole: string;
+};
+export type ProfessionResolution = {
+    ok: true;
+    pack: Pack;
+    team: Team;
+    role: Team['roles'][number];
+} | {
+    ok: false;
+    reason: ProfessionResolutionError;
+};
+/**
+ * Validate a profession directive against the loaded pack registry +
+ * pre-staged team map. Pure function — no I/O.
+ *
+ * Phase 2 leaf-node-profession discipline: roles[0] is returned. Phase 4+
+ * multi-role lookup will accept a `role:` name in `nextAction.args`.
+ */
+export declare function resolveProfessionDirective(nextAction: NextAction, packs: readonly Pack[], teamsByPack: ReadonlyMap<string, Team>): ProfessionResolution;
+/**
+ * Render a `ProfessionResolutionError` to a human-scannable string. Used by
+ * the dispatcher to log to stderr + violations.log.
+ */
+export declare function formatProfessionError(err: ProfessionResolutionError): string;
+//# sourceMappingURL=profession_resolver.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"profession_resolver.d.ts","sourceRoot":"","sources":["../../../src/runtime/hooks/profession_resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,6BAA6B,CAAC;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAEpD,MAAM,MAAM,yBAAyB,GACjC;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC9D;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC;AAExE,MAAM,MAAM,oBAAoB,GAC5B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAA;CAAE,GACjE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,yBAAyB,CAAA;CAAE,CAAC;AAErD;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,UAAU,EACtB,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,GACrC,oBAAoB,CAsCtB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,yBAAyB,GAAG,MAAM,CAa5E"}

package/dist/runtime/hooks/profession_resolver.js

@@ -0,0 +1,86 @@
+/**
+ * MM.2 — Pure-function resolver for `next_action.profession` directives.
+ *
+ * Given a directive whose `next_action.profession` names a pack + the loaded
+ * pack registry + a pre-staged `teamsByPack` map, validates that the pack
+ * exists, is profession-usage, and has at least one role defined in its
+ * team.yaml. Returns a tagged result.
+ *
+ * **opensquid never invokes `spawn_subagent` itself** per
+ * [[project_opensquid_no_agent_loop]] — this resolver only validates the
+ * directive is well-formed before the dispatcher aggregates it onto the
+ * UserPromptSubmit envelope. The AGENT then calls `spawn_subagent` on the
+ * profession pack named by the directive.
+ *
+ * Fail-open in the SAFE direction: an invalid profession → directive DROPPED
+ * (not emitted to the agent) + a warning is logged at the caller. Emitting a
+ * directive for a non-existent / misconfigured profession would mislead the
+ * agent.
+ *
+ * Imports: types only (zero I/O). Imported by: `src/runtime/hooks/dispatch.ts`
+ * + tests.
+ */
+/**
+ * Validate a profession directive against the loaded pack registry +
+ * pre-staged team map. Pure function — no I/O.
+ *
+ * Phase 2 leaf-node-profession discipline: roles[0] is returned. Phase 4+
+ * multi-role lookup will accept a `role:` name in `nextAction.args`.
+ */
+export function resolveProfessionDirective(nextAction, packs, teamsByPack) {
+    if (nextAction.profession === undefined) {
+        return { ok: false, reason: { code: 'unknown-pack', packName: '<undefined>' } };
+    }
+    const packName = nextAction.profession;
+    const pack = packs.find((p) => p.name === packName);
+    if (pack === undefined) {
+        return { ok: false, reason: { code: 'unknown-pack', packName } };
+    }
+    const usage = pack.usage ?? 'active';
+    if (usage !== 'profession' && usage !== 'both') {
+        return {
+            ok: false,
+            reason: { code: 'wrong-usage', packName, actualUsage: usage },
+        };
+    }
+    const team = teamsByPack.get(packName);
+    if (team === undefined) {
+        return { ok: false, reason: { code: 'missing-team', packName } };
+    }
+    if (team.roles.length === 0) {
+        return { ok: false, reason: { code: 'no-roles', packName } };
+    }
+    const requestedRole = typeof nextAction.args?.role === 'string' ? nextAction.args.role : undefined;
+    if (requestedRole !== undefined) {
+        const match = team.roles.find((r) => r.name === requestedRole);
+        if (match === undefined) {
+            return {
+                ok: false,
+                reason: { code: 'role-not-found', packName, requestedRole },
+            };
+        }
+        return { ok: true, pack, team, role: match };
+    }
+    // Phase 2: leaf-node profession — first role wins.
+    const role = team.roles[0];
+    return { ok: true, pack, team, role };
+}
+/**
+ * Render a `ProfessionResolutionError` to a human-scannable string. Used by
+ * the dispatcher to log to stderr + violations.log.
+ */
+export function formatProfessionError(err) {
+    switch (err.code) {
+        case 'unknown-pack':
+            return `directive references profession "${err.packName}" but no pack with that name is loaded`;
+        case 'wrong-usage':
+            return `directive references profession "${err.packName}" but its usage is "${err.actualUsage}" — must be "profession" or "both"`;
+        case 'missing-team':
+            return `directive references profession "${err.packName}" but the pack has no loadable team.yaml`;
+        case 'no-roles':
+            return `directive references profession "${err.packName}" but its team.yaml declares zero roles`;
+        case 'role-not-found':
+            return `directive references profession "${err.packName}" + role "${err.requestedRole}" — role not found in team.yaml`;
+    }
+}
+//# sourceMappingURL=profession_resolver.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"profession_resolver.js","sourceRoot":"","sources":["../../../src/runtime/hooks/profession_resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAgBH;;;;;;GAMG;AACH,MAAM,UAAU,0BAA0B,CACxC,UAAsB,EACtB,KAAsB,EACtB,WAAsC;IAEtC,IAAI,UAAU,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QACxC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,QAAQ,EAAE,aAAa,EAAE,EAAE,CAAC;IAClF,CAAC;IACD,MAAM,QAAQ,GAAG,UAAU,CAAC,UAAU,CAAC;IACvC,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;IACpD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,QAAQ,EAAE,EAAE,CAAC;IACnE,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,QAAQ,CAAC;IACrC,IAAI,KAAK,KAAK,YAAY,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;QAC/C,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE;SAC9D,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACvC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,QAAQ,EAAE,EAAE,CAAC;IACnE,CAAC;IACD,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,EAAE,CAAC;IAC/D,CAAC;IACD,MAAM,aAAa,GACjB,OAAO,UAAU,CAAC,IAAI,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IAC/E,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;QAChC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,aAAa,CAAC,CAAC;QAC/D,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,MAAM,EAAE,EAAE,IAAI,EAAE,gBAAgB,EAAE,QAAQ,EAAE,aAAa,EAAE;aAC5D,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IAC/C,CAAC;IACD,mDAAmD;IACnD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC;IAC5B,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACxC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAA8B;IAClE,QAAQ,GAAG,CAAC,IAAI,EAAE,CAAC;QACjB,KAAK,cAAc;YACjB,OAAO,oCAAoC,GAAG,CAAC,QAAQ,wCAAwC,CAAC;QAClG,KAAK,aAAa;YAChB,OAAO,oCAAoC,GAAG,CAAC,QAAQ,uBAAuB,GAAG,CAAC,WAAW,oCAAoC,CAAC;QACpI,KAAK,cAAc;YACjB,OAAO,oCAAoC,GAAG,CAAC,QAAQ,0CAA0C,CAAC;QACpG,KAAK,UAAU;YACb,OAAO,oCAAoC,GAAG,CAAC,QAAQ,yCAAyC,CAAC;QACnG,KAAK,gBAAgB;YACnB,OAAO,oCAAoC,GAAG,CAAC,QAAQ,aAAa,GAAG,CAAC,aAAa,iCAAiC,CAAC;IAC3H,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,32 @@
+/**
+ * `SCOPE_INTENT_REGEX` (T-ASC, ASC.1).
+ *
+ * Single-source regex for detecting scope-authoring intent in a
+ * UserPromptSubmit prompt. Used by:
+ *   - ASC.1 UserPromptSubmit chain-state writer — transitions the chain
+ *     from 'idle' to 'scoping' when the prompt matches.
+ *   - ASC.4 audit step asserting the personal-pack `scope-intent-nudge`
+ *     rule's patterns (verified via `scope-decomposer/skill.yaml:28-50`)
+ *     are a SUBSET of this regex's matches.
+ *
+ * SUPERSET-of-pack-patterns by design (T-ASC ASC.1 spec, lock L4 sibling):
+ *   - false positives are acceptable here (an extra 'scoping' transition
+ *     that the agent doesn't act on; the chain self-corrects on the next
+ *     real research/spec write);
+ *   - false negatives are NOT acceptable (a missed scope-authoring intent
+ *     would leave the chain stuck at 'idle' so subsequent stage-gated
+ *     handoff rules never fire).
+ *
+ * The pack's `scope-intent-nudge` patterns are stricter (each anchors on
+ * a direction object — `\bspec\s+(?:out|this|the)\b`, etc.) for the
+ * narrower job of triggering a nudge verdict. This regex is broader so
+ * the chain transitions reliably even when the user's phrasing differs
+ * slightly from the pack's anchors. As long as the pack patterns are a
+ * subset of this regex (verified by scope_intent.test.ts), the chain
+ * transition is guaranteed to fire whenever the nudge does.
+ *
+ * Word-boundary anchored so `specifically`, `prescriptive`, etc. do not
+ * false-positive on `spec` / `prescribe`. Case-insensitive.
+ */
+export declare const SCOPE_INTENT_REGEX: RegExp;
+//# sourceMappingURL=scope_intent.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scope_intent.d.ts","sourceRoot":"","sources":["../../../src/runtime/hooks/scope_intent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,kBAAkB,QAC8E,CAAC"}

package/dist/runtime/hooks/scope_intent.js

@@ -0,0 +1,32 @@
+/**
+ * `SCOPE_INTENT_REGEX` (T-ASC, ASC.1).
+ *
+ * Single-source regex for detecting scope-authoring intent in a
+ * UserPromptSubmit prompt. Used by:
+ *   - ASC.1 UserPromptSubmit chain-state writer — transitions the chain
+ *     from 'idle' to 'scoping' when the prompt matches.
+ *   - ASC.4 audit step asserting the personal-pack `scope-intent-nudge`
+ *     rule's patterns (verified via `scope-decomposer/skill.yaml:28-50`)
+ *     are a SUBSET of this regex's matches.
+ *
+ * SUPERSET-of-pack-patterns by design (T-ASC ASC.1 spec, lock L4 sibling):
+ *   - false positives are acceptable here (an extra 'scoping' transition
+ *     that the agent doesn't act on; the chain self-corrects on the next
+ *     real research/spec write);
+ *   - false negatives are NOT acceptable (a missed scope-authoring intent
+ *     would leave the chain stuck at 'idle' so subsequent stage-gated
+ *     handoff rules never fire).
+ *
+ * The pack's `scope-intent-nudge` patterns are stricter (each anchors on
+ * a direction object — `\bspec\s+(?:out|this|the)\b`, etc.) for the
+ * narrower job of triggering a nudge verdict. This regex is broader so
+ * the chain transitions reliably even when the user's phrasing differs
+ * slightly from the pack's anchors. As long as the pack patterns are a
+ * subset of this regex (verified by scope_intent.test.ts), the chain
+ * transition is guaranteed to fire whenever the nudge does.
+ *
+ * Word-boundary anchored so `specifically`, `prescriptive`, etc. do not
+ * false-positive on `spec` / `prescribe`. Case-insensitive.
+ */
+export const SCOPE_INTENT_REGEX = /\b(spec(?:c?ing|ced)?|scope|new\s+(?:task|track)|add\s+(?:a\s+|another\s+)?(?:task|track)|design|plan)\b/i;
+//# sourceMappingURL=scope_intent.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scope_intent.js","sourceRoot":"","sources":["../../../src/runtime/hooks/scope_intent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAC7B,2GAA2G,CAAC"}

package/dist/runtime/hooks/session-end.d.ts

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

package/dist/runtime/hooks/session-end.d.ts.map

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

package/dist/runtime/hooks/session-end.js

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+/**
+ * Claude Code `SessionEnd` hook binary.
+ *
+ * Fires when a session terminates — entry point for context-clearing
+ * lessons (Task 4.x). The dispatcher still runs in case a pack registers
+ * a `session_end` rule (e.g. flushing a violations buffer).
+ *
+ * Wired in `~/.claude/settings.json`:
+ *
+ *   { "hooks": { "SessionEnd": [{ "hooks": [{ "type": "command",
+ *     "command": "opensquid-hook-sessionend" }] }] } }
+ *
+ * stdin = session-end JSON. exit code is informational here — Claude Code
+ * is already closing the session — but we follow the same 0/2 convention
+ * for consistency with the other hooks.
+ *
+ * Fail-open on any internal error.
+ */
+import { buildRegistry, loadActivePacks } from '../bootstrap.js';
+import { clearFsmState } from '../fsm_state.js';
+import { runCompression } from '../compression_orchestrator.js';
+import { makeConsolidateRunner } from '../wedge/compression_deps.js';
+import { emitProbe, groupFromTask } from '../satisfaction_probe.js';
+import { archiveActiveTask, readActiveTask } from '../session_state.js';
+import { Event } from '../types.js';
+import { dispatchEvent } from './dispatch.js';
+import { reconcileMemoryOnSessionEnd } from './memory_reconcile.js';
+function parsePayload(raw) {
+    const obj = JSON.parse(raw);
+    return {
+        kind: 'session_end',
+        sessionId: obj.sessionId ?? obj.session_id ?? process.env.CLAUDE_SESSION_ID ?? 'unknown',
+    };
+}
+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 SessionEnd payload — proceeding\n');
+        process.exit(0);
+    }
+    let normalized;
+    try {
+        normalized = parsePayload(raw);
+    }
+    catch (e) {
+        process.stderr.write(`opensquid: invalid SessionEnd JSON — ${String(e)}\n`);
+        process.exit(0);
+    }
+    const parsed = Event.safeParse(normalized);
+    if (!parsed.success) {
+        process.stderr.write('opensquid: invalid SessionEnd payload schema\n');
+        process.exit(0);
+    }
+    // Stdin-first session id (parsePayload already applied the correct precedence,
+    // matching the stop/pre-tool-use/user-prompt-submit hooks post-2026-05-26 fix).
+    const sessionId = parsed.data.kind === 'session_end' ? parsed.data.sessionId : 'unknown';
+    const packs = await loadActivePacks(sessionId);
+    const registry = await buildRegistry();
+    const { exitCode, stderr } = await dispatchEvent(parsed.data, packs, registry, sessionId);
+    if (stderr)
+        process.stderr.write(stderr + '\n');
+    // MAU.3 — flush authored memories to the long-term RAG at the session boundary.
+    await reconcileMemoryOnSessionEnd(sessionId);
+    // CMP.2 — emit a satisfaction probe for the just-closed task's feature
+    // group (async, append-only, deduped per group). The user answers at a
+    // natural boundary; a "satisfied" answer later gates the compression
+    // orchestrator (CMP.4). Read the active task BEFORE archiving it.
+    // Best-effort + fail-open: a probe-emit failure must never affect the
+    // session-end exit code.
+    try {
+        const active = await readActiveTask(sessionId);
+        const group = groupFromTask(active);
+        if (group)
+            await emitProbe(sessionId, group);
+    }
+    catch (e) {
+        process.stderr.write(`opensquid: satisfaction-probe emit skipped — ${String(e)}\n`);
+    }
+    // T-CTX-LOOP CTX.5 (2026-05-29) — wire the CMP.4 compression orchestrator at
+    // the session boundary. The orchestrator is satisfaction-gated (D1: no
+    // probe answered "satisfied" → no-op); when satisfied, it reads CMP.3
+    // candidate windows + runs the TS consolidate (RES-4c, engine-free) per window:
+    // compress + recall-replay verify + force-delete ONLY non-user-cited predecessors
+    // that the verify gate passes. consolidate NEVER-deletes for unverified or
+    // user-cited memories — opensquid is pure policy. Fail-open per the hook contract;
+    // a compression failure must not block session-end.
+    try {
+        const active = await readActiveTask(sessionId);
+        const group = groupFromTask(active);
+        if (group) {
+            const runner = await makeConsolidateRunner();
+            try {
+                const outcomes = await runCompression(sessionId, group, runner.run);
+                if (outcomes.length > 0) {
+                    process.stderr.write(`opensquid: compression — ${String(outcomes.length)} window(s) for group ${group}\n`);
+                }
+            }
+            finally {
+                await runner.close();
+            }
+        }
+    }
+    catch (e) {
+        process.stderr.write(`opensquid: compression skipped — ${String(e)}\n`);
+    }
+    // T-AUTO-HANDOFF — the SessionEnd BACKUP writer. MUST run BEFORE
+    // archiveActiveTask/clearFsmState below: those destroy the exact state the
+    // deterministic dump reads (active-task signal + FSM file). Best-effort —
+    // a handoff failure never blocks session close.
+    // AHO.3 SUBSTANCE GATE: trivial sessions (every codex exec probe and hook
+    // subprocess carries a session id) left 26+ junk docs/issues in one day and
+    // clobbered the MEMORY.md resume block. Back up ONLY when the dying session
+    // holds resumable state; the explicit command and the SessionStart lazy
+    // generator are unaffected.
+    try {
+        // AHO.4: ONE substance predicate shared with the tier-3 lazy generator
+        // (the AHO.3 FSM-exists probe passed for scope-intent trivia whose FSM
+        // this very hook then deleted — the evidence self-erased).
+        const { hasResumableState } = await import('../handoff/substance.js');
+        if (await hasResumableState(sessionId)) {
+            const { runHandoff } = await import('../handoff/index.js');
+            const result = await runHandoff(sessionId, process.cwd());
+            process.stderr.write(`opensquid: auto-handoff written — ${result.docPath}\n`);
+        }
+        else {
+            process.stderr.write('opensquid: auto-handoff skipped — no resumable state\n');
+        }
+    }
+    catch (e) {
+        process.stderr.write(`opensquid: auto-handoff skipped — ${String(e)}\n`);
+    }
+    // AP.2 / rule #16 — archive (not delete) the active-task signal at session
+    // close, so an abandoned in-progress task leaves a trace. Best-effort.
+    await archiveActiveTask(sessionId);
+    // Clear the coding-flow lifecycle state on session close — a session-scoped
+    // machine that starts fresh each session (cross-session resume is a separate
+    // product question, deferred). ENOENT swallowed by the helper. (T-FSM-UNIFY:
+    // one unified pack now, so this single clear covers the whole lifecycle —
+    // incidentally fixing the old never-cleared FSM-state leak.)
+    try {
+        await clearFsmState(sessionId, 'coding-flow');
+    }
+    catch (e) {
+        process.stderr.write(`opensquid: coding-flow clear failed — ${String(e)}\n`);
+    }
+    process.exit(exitCode);
+}
+main().catch((e) => {
+    process.stderr.write(`opensquid hook crash (session-end): ${String(e)}\n`);
+    process.exit(0);
+});
+//# sourceMappingURL=session-end.js.map

package/dist/runtime/hooks/session-end.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-end.js","sourceRoot":"","sources":["../../../src/runtime/hooks/session-end.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACjE,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAChE,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACxE,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEpC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AAOpE,SAAS,YAAY,CAAC,GAAW;IAC/B,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAsB,CAAC;IACjD,OAAO;QACL,IAAI,EAAE,aAAa;QACnB,SAAS,EAAE,GAAG,CAAC,SAAS,IAAI,GAAG,CAAC,UAAU,IAAI,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,SAAS;KACzF,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,SAAS;IACtB,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,OAAO,CAAC,KAAK;QAAE,IAAI,IAAI,KAAe,CAAC;IACjE,OAAO,IAAI,CAAC;AACd,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,GAAG,GAAG,MAAM,SAAS,EAAE,CAAC;IAC9B,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC;QAChB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,oDAAoD,CAAC,CAAC;QAC3E,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,IAAI,UAAmB,CAAC;IACxB,IAAI,CAAC;QACH,UAAU,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;IACjC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,wCAAwC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC5E,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,MAAM,GAAG,KAAK,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;IAC3C,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,gDAAgD,CAAC,CAAC;QACvE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,+EAA+E;IAC/E,gFAAgF;IAChF,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,KAAK,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;IACzF,MAAM,KAAK,GAAG,MAAM,eAAe,CAAC,SAAS,CAAC,CAAC;IAC/C,MAAM,QAAQ,GAAG,MAAM,aAAa,EAAE,CAAC;IACvC,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,aAAa,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;IAC1F,IAAI,MAAM;QAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAEhD,gFAAgF;IAChF,MAAM,2BAA2B,CAAC,SAAS,CAAC,CAAC;IAE7C,uEAAuE;IACvE,uEAAuE;IACvE,qEAAqE;IACrE,kEAAkE;IAClE,sEAAsE;IACtE,yBAAyB;IACzB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,SAAS,CAAC,CAAC;QAC/C,MAAM,KAAK,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;QACpC,IAAI,KAAK;YAAE,MAAM,SAAS,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IAC/C,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,gDAAgD,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACtF,CAAC;IAED,6EAA6E;IAC7E,uEAAuE;IACvE,sEAAsE;IACtE,gFAAgF;IAChF,kFAAkF;IAClF,2EAA2E;IAC3E,mFAAmF;IACnF,oDAAoD;IACpD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,SAAS,CAAC,CAAC;QAC/C,MAAM,KAAK,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;QACpC,IAAI,KAAK,EAAE,CAAC;YACV,MAAM,MAAM,GAAG,MAAM,qBAAqB,EAAE,CAAC;YAC7C,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,MAAM,cAAc,CAAC,SAAS,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;gBACpE,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBACxB,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,4BAA4B,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,wBAAwB,KAAK,IAAI,CACrF,CAAC;gBACJ,CAAC;YACH,CAAC;oBAAS,CAAC;gBACT,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;YACvB,CAAC;QACH,CAAC;IACH,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,oCAAoC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAC1E,CAAC;IAED,iEAAiE;IACjE,2EAA2E;IAC3E,0EAA0E;IAC1E,gDAAgD;IAChD,0EAA0E;IAC1E,4EAA4E;IAC5E,4EAA4E;IAC5E,wEAAwE;IACxE,4BAA4B;IAC5B,IAAI,CAAC;QACH,uEAAuE;QACvE,uEAAuE;QACvE,2DAA2D;QAC3D,MAAM,EAAE,iBAAiB,EAAE,GAAG,MAAM,MAAM,CAAC,yBAAyB,CAAC,CAAC;QACtE,IAAI,MAAM,iBAAiB,CAAC,SAAS,CAAC,EAAE,CAAC;YACvC,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,MAAM,CAAC,qBAAqB,CAAC,CAAC;YAC3D,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,SAAS,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;YAC1D,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,qCAAqC,MAAM,CAAC,OAAO,IAAI,CAAC,CAAC;QAChF,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,wDAAwD,CAAC,CAAC;QACjF,CAAC;IACH,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,qCAAqC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAC3E,CAAC;IAED,2EAA2E;IAC3E,uEAAuE;IACvE,MAAM,iBAAiB,CAAC,SAAS,CAAC,CAAC;IAEnC,4EAA4E;IAC5E,6EAA6E;IAC7E,6EAA6E;IAC7E,0EAA0E;IAC1E,6DAA6D;IAC7D,IAAI,CAAC;QACH,MAAM,aAAa,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;IAChD,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,yCAAyC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAC/E,CAAC;IAED,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;AACzB,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,CAAU,EAAE,EAAE;IAC1B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,uCAAuC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAC3E,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/runtime/hooks/session-start.d.ts

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

package/dist/runtime/hooks/session-start.d.ts.map

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

package/dist/runtime/hooks/session-start.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/**
+ * Claude Code `SessionStart` hook binary (T-HANDOFF-HARDENING HH6.1).
+ *
+ * Fires ONCE when a session begins — the enforcement point opensquid was
+ * missing (it previously registered only PreToolUse / UserPromptSubmit / Stop
+ * / SessionEnd, so "check chat connections / start chat watch at session
+ * start" was a convention with nowhere to hang). Claude Code delivers a
+ * `source` discriminator: `startup` (new), `resume` (--resume/--continue/
+ * /resume), `clear` (/clear), `compact` (auto/manual compaction). This bin
+ * acts only on `startup`/`resume` — `clear`/`compact` fire MID-session and
+ * would re-inject session-start noise after the connection was established.
+ *
+ * Wired in `~/.claude/settings.json` (installed by `opensquid setup` via
+ * src/setup/wizard/settings-writer.ts):
+ *
+ *   { "hooks": { "SessionStart": [{ "hooks": [{ "type": "command",
+ *     "command": "opensquid-hook-sessionstart" }] }] } }
+ *
+ * stdin = SessionStart JSON ({session_id, transcript_path, cwd, source,
+ * model}). Output: VERIFIED 2026-05-24 — Claude Code 2.x silently DISCARDS
+ * raw stdout from a hook; ONLY `hookSpecificOutput.additionalContext` (with
+ * the matching `hookEventName`) injects context. So this bin emits the JSON
+ * envelope, never plain stdout. Modeled 1:1 on user-prompt-submit.ts.
+ *
+ * Fail-open on any internal error: a SessionStart hook must NEVER block the
+ * session from starting (exit 0 throughout; main().catch → exit 0).
+ *
+ * The mechanism ships with ZERO rules subscribed; the first consumer is the
+ * connection-check pack rule (HH6.2). Until a pack rule emits an
+ * inject_context on `session_start`, this bin produces no stdout.
+ */
+import { buildRegistry, loadActivePacks } from '../bootstrap.js';
+import { claimUmbrellaLeaseForSession } from '../chat/claim_lease.js';
+import { Event } from '../types.js';
+import { dispatchEvent } from './dispatch.js';
+import { extractSessionId } from './session_id.js';
+function parsePayload(raw) {
+    const obj = JSON.parse(raw);
+    return {
+        kind: 'session_start',
+        // CC always supplies `source`; default to 'startup' if a future/edge
+        // payload omits it so the event still parses (Event.safeParse enforces
+        // the enum — an unknown source value fails parse → fail-open exit 0).
+        source: obj.source ?? 'startup',
+        cwd: obj.cwd ?? process.cwd(),
+    };
+}
+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 SessionStart payload — proceeding\n');
+        process.exit(0);
+    }
+    let normalized;
+    try {
+        normalized = parsePayload(raw);
+    }
+    catch (e) {
+        process.stderr.write(`opensquid: invalid SessionStart JSON — ${String(e)}\n`);
+        process.exit(0);
+    }
+    const parsed = Event.safeParse(normalized);
+    if (!parsed.success) {
+        process.stderr.write('opensquid: invalid SessionStart payload schema\n');
+        process.exit(0);
+    }
+    // HH6.1 L3: only act on a genuine session begin. `clear`/`compact` fire
+    // mid-session; re-running session-start discipline there would re-inject
+    // the connection report after the connection was already established.
+    if (parsed.data.kind === 'session_start' &&
+        (parsed.data.source === 'clear' || parsed.data.source === 'compact')) {
+        process.exit(0);
+    }
+    const sessionId = extractSessionId(raw);
+    // Interactive responder (chat mirrors the live session): the moment a session
+    // opens for an umbrella it claims that umbrella's chat lease (acquire-if-free)
+    // so a chat message drives THIS session + the headless stands down — even
+    // before the first keystroke. No-op in `responder: headless` mode / no umbrella.
+    const startCwd = parsed.data.kind === 'session_start' ? parsed.data.cwd : process.cwd();
+    // T-CHAT-REALTIME: a session START is the user's deliberate "route chat HERE" signal —
+    // the session changes even when the project doesn't, so TAKE OVER the umbrella lease
+    // (newest-session-wins) rather than defer to a possibly-dead prior holder. The
+    // mid-session UPS/Stop heartbeat keeps the default acquire-if-free.
+    await claimUmbrellaLeaseForSession(sessionId, startCwd, { forceTakeover: true });
+    const packs = await loadActivePacks(sessionId);
+    const registry = await buildRegistry();
+    const { exitCode, stderr, contextInjections } = await dispatchEvent(parsed.data, packs, registry, sessionId);
+    // HH6.1 L2: emit the additionalContext envelope when any rule contributed
+    // an inject_context payload (the dispatcher aggregates inject_context for
+    // session_start per the HH6.1 widening). Raw stdout is silently discarded
+    // by Claude Code 2.x — the JSON envelope is the ONLY channel that injects.
+    if (contextInjections.length > 0) {
+        const envelope = {
+            hookSpecificOutput: {
+                hookEventName: 'SessionStart',
+                additionalContext: contextInjections.join('\n\n'),
+            },
+        };
+        process.stdout.write(JSON.stringify(envelope));
+    }
+    if (stderr)
+        process.stderr.write(stderr + '\n');
+    process.exit(exitCode);
+}
+main().catch((e) => {
+    process.stderr.write(`opensquid hook crash (session-start): ${String(e)}\n`);
+    process.exit(0);
+});
+//# sourceMappingURL=session-start.js.map

package/dist/runtime/hooks/session-start.js.map

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

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

@@ -0,0 +1,86 @@
+/**
+ * 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).
+ */
+/**
+ * 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 declare function extractSessionId(raw: string): string;
+/** Absolute path of the live-session pointer file. */
+export declare const currentSessionPath: () => string;
+/**
+ * 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 declare function recordCurrentSession(sessionId: string, cwd?: string): Promise<void>;
+/** Read the global live session id, or `null` if absent/unreadable/empty. */
+export declare function readCurrentSession(): Promise<string | null>;
+/** Read the project-scoped live session id, or `null` if absent/unreadable/empty. */
+export declare function readProjectCurrentSession(projectUuid: string): Promise<string | null>;
+/**
+ * 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 declare function resolveMcpSessionId(): Promise<string | null>;
+//# sourceMappingURL=session_id.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session_id.d.ts","sourceRoot":"","sources":["../../../src/runtime/hooks/session_id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAYH;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAYpD;AAED,sDAAsD;AACtD,eAAO,MAAM,kBAAkB,QAAO,MAAoD,CAAC;AAE3F;;;;GAIG;AACH,wBAAsB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAyBzF;AAED,6EAA6E;AAC7E,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAOjE;AAED,qFAAqF;AACrF,wBAAsB,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAO3F;AAgBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAoBlE"}