opensquid 0.5.395

package/dist/setup/wizard/settings-reader.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Parser for Claude Code's `settings.json` hook block (G.2 — doctor + writer
+ * share this parser so they can't drift on the JSON shape).
+ *
+ * Produces a flat `ParsedHookEntry[]` from the nested
+ * `hooks.<EventName>[].hooks[]` shape. Each entry carries:
+ *   - `event`: the Claude Code event name (PreToolUse, Stop, ...)
+ *   - `type`: 'command' | 'prompt' (D9-guard prompt-type hooks aren't
+ *     subprocess commands and MUST be filtered out before any spawn loop)
+ *   - `command`: the command string (only set when type === 'command')
+ *   - `prompt`: the prompt text (only set when type === 'prompt')
+ *   - `matcher`: optional matcher (e.g. "Bash" for PreToolUse)
+ *   - `opensquidMarker`: true if the inner entry carried `@opensquid: true`
+ *
+ * ENOENT (file doesn't exist) → returns `[]`. All other read / parse errors
+ * propagate — doctor wraps them and surfaces "could not read X" notes
+ * rather than crashing.
+ *
+ * Engine-vocabulary discipline: this file knows about Claude Code's
+ * settings.json format because it's a consumer-side parser. The runtime
+ * (`dispatch.ts`, `bootstrap.ts`) stays harness-agnostic.
+ *
+ * Imported by: `src/setup/cli/doctor.ts`. Sibling to `settings-writer.ts`
+ * (writer + reader share the same JSON shape; kept in separate files because
+ * the writer's projection logic is heavy and ownership-aware while the
+ * reader is pure parse + flatten).
+ */
+interface RawHookCommandEntry {
+    type?: string;
+    command?: string;
+    prompt?: string;
+    '@opensquid'?: boolean;
+    [k: string]: unknown;
+}
+interface RawHookGroup {
+    matcher?: string;
+    hooks?: RawHookCommandEntry[];
+    [k: string]: unknown;
+}
+interface RawSettingsJson {
+    hooks?: Record<string, RawHookGroup[]>;
+    [k: string]: unknown;
+}
+export type HookEntryType = 'command' | 'prompt';
+export interface ParsedHookEntry {
+    /** Claude Code event name verbatim (PreToolUse, UserPromptSubmit, ...). */
+    event: string;
+    /** 'command' = spawnable subprocess; 'prompt' = D9-guard inline text. */
+    type: HookEntryType;
+    /** Set when type === 'command'. Empty string otherwise. */
+    command: string;
+    /** Set when type === 'prompt'. Empty string otherwise. */
+    prompt: string;
+    /** Optional Claude Code matcher (tool name regex, etc.). */
+    matcher: string | undefined;
+    /** True if the entry carried `@opensquid: true` (writer-owned). */
+    opensquidMarker: boolean;
+}
+/**
+ * Read settings.json, return flat list of hook entries.
+ *
+ * ENOENT → `[]` (no file = no hooks configured here). Callers (doctor) MUST
+ * still report informational note about ENOENT so the user knows it skipped
+ * the project scope — that lives in the caller, not here.
+ *
+ * Throws on JSON parse failure: doctor catches and surfaces "could not parse
+ * <path>: <err>" as a RED entry rather than crashing the CLI.
+ */
+export declare function readSettingsHooks(settingsPath: string): Promise<ParsedHookEntry[]>;
+/** Pure flatten — exported for unit tests so they can drive the projection
+ * without round-tripping to disk. */
+export declare function flatten(json: RawSettingsJson): ParsedHookEntry[];
+export {};
+//# sourceMappingURL=settings-reader.d.ts.map

package/dist/setup/wizard/settings-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-reader.d.ts","sourceRoot":"","sources":["../../../src/setup/wizard/settings-reader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,UAAU,mBAAmB;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AACD,UAAU,YAAY;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAC9B,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AACD,UAAU,eAAe;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC;IACvC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEjD,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,IAAI,EAAE,aAAa,CAAC;IACpB,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,mEAAmE;IACnE,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAUxF;AAED;qCACqC;AACrC,wBAAgB,OAAO,CAAC,IAAI,EAAE,eAAe,GAAG,eAAe,EAAE,CAyBhE"}

package/dist/setup/wizard/settings-reader.js

@@ -0,0 +1,81 @@
+/**
+ * Parser for Claude Code's `settings.json` hook block (G.2 — doctor + writer
+ * share this parser so they can't drift on the JSON shape).
+ *
+ * Produces a flat `ParsedHookEntry[]` from the nested
+ * `hooks.<EventName>[].hooks[]` shape. Each entry carries:
+ *   - `event`: the Claude Code event name (PreToolUse, Stop, ...)
+ *   - `type`: 'command' | 'prompt' (D9-guard prompt-type hooks aren't
+ *     subprocess commands and MUST be filtered out before any spawn loop)
+ *   - `command`: the command string (only set when type === 'command')
+ *   - `prompt`: the prompt text (only set when type === 'prompt')
+ *   - `matcher`: optional matcher (e.g. "Bash" for PreToolUse)
+ *   - `opensquidMarker`: true if the inner entry carried `@opensquid: true`
+ *
+ * ENOENT (file doesn't exist) → returns `[]`. All other read / parse errors
+ * propagate — doctor wraps them and surfaces "could not read X" notes
+ * rather than crashing.
+ *
+ * Engine-vocabulary discipline: this file knows about Claude Code's
+ * settings.json format because it's a consumer-side parser. The runtime
+ * (`dispatch.ts`, `bootstrap.ts`) stays harness-agnostic.
+ *
+ * Imported by: `src/setup/cli/doctor.ts`. Sibling to `settings-writer.ts`
+ * (writer + reader share the same JSON shape; kept in separate files because
+ * the writer's projection logic is heavy and ownership-aware while the
+ * reader is pure parse + flatten).
+ */
+import { promises as fs } from 'node:fs';
+/**
+ * Read settings.json, return flat list of hook entries.
+ *
+ * ENOENT → `[]` (no file = no hooks configured here). Callers (doctor) MUST
+ * still report informational note about ENOENT so the user knows it skipped
+ * the project scope — that lives in the caller, not here.
+ *
+ * Throws on JSON parse failure: doctor catches and surfaces "could not parse
+ * <path>: <err>" as a RED entry rather than crashing the CLI.
+ */
+export async function readSettingsHooks(settingsPath) {
+    let raw;
+    try {
+        raw = await fs.readFile(settingsPath, 'utf-8');
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return [];
+        throw e;
+    }
+    const json = JSON.parse(raw);
+    return flatten(json);
+}
+/** Pure flatten — exported for unit tests so they can drive the projection
+ * without round-tripping to disk. */
+export function flatten(json) {
+    const out = [];
+    const hooks = json.hooks ?? {};
+    for (const [event, groups] of Object.entries(hooks)) {
+        if (!Array.isArray(groups))
+            continue;
+        for (const group of groups) {
+            const inner = group.hooks ?? [];
+            for (const h of inner) {
+                // Normalize the type field. Claude Code uses 'command' for
+                // subprocess hooks and 'prompt' for D9-guard inline-text hooks.
+                // Anything unrecognized defaults to 'command' so future-added
+                // subprocess hook variants don't get silently skipped by doctor.
+                const type = h.type === 'prompt' ? 'prompt' : 'command';
+                out.push({
+                    event,
+                    type,
+                    command: typeof h.command === 'string' ? h.command : '',
+                    prompt: typeof h.prompt === 'string' ? h.prompt : '',
+                    matcher: typeof group.matcher === 'string' ? group.matcher : undefined,
+                    opensquidMarker: h['@opensquid'] === true,
+                });
+            }
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=settings-reader.js.map

package/dist/setup/wizard/settings-reader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-reader.js","sourceRoot":"","sources":["../../../src/setup/wizard/settings-reader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AAoCzC;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,YAAoB;IAC1D,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;IACjD,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAK,CAA2B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,EAAE,CAAC;QAC9D,MAAM,CAAC,CAAC;IACV,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAoB,CAAC;IAChD,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC;AACvB,CAAC;AAED;qCACqC;AACrC,MAAM,UAAU,OAAO,CAAC,IAAqB;IAC3C,MAAM,GAAG,GAAsB,EAAE,CAAC;IAClC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;IAC/B,KAAK,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACpD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;YAAE,SAAS;QACrC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC;YAChC,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;gBACtB,2DAA2D;gBAC3D,gEAAgE;gBAChE,8DAA8D;gBAC9D,iEAAiE;gBACjE,MAAM,IAAI,GAAkB,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;gBACvE,GAAG,CAAC,IAAI,CAAC;oBACP,KAAK;oBACL,IAAI;oBACJ,OAAO,EAAE,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE;oBACvD,MAAM,EAAE,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE;oBACpD,OAAO,EAAE,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;oBACtE,eAAe,EAAE,CAAC,CAAC,YAAY,CAAC,KAAK,IAAI;iBAC1C,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/setup/wizard/settings-writer.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Idempotent writer for Claude Code's `settings.json` hook block (G.1 Part B).
+ *
+ * Writes opensquid's anti-drift hook entries (one per event in
+ * `OPENSQUID_BIN_FOR_EVENT`: PreToolUse, PostToolUse, UserPromptSubmit, Stop,
+ * SessionEnd, SessionStart) while preserving every non-opensquid hook entry
+ * verbatim.
+ *
+ * Three recognition rules identify entries the writer OWNS (all three live in
+ * `isOpensquidHookEntry` — the ONE ownership predicate, also consumed by
+ * doctor's managed-filter + spawn gate and the flow-health check):
+ *   1. `'@opensquid': true` marker on the inner hook entry — every entry the
+ *      writer adds carries this.
+ *   2. `LEGACY_OPENSQUID_PATTERN` regex — the broken ancient
+ *      `node <abs>/opensquid/dist/index.js anti-drift <event>` shape (G.1).
+ *   3. Bin-name basename match (`isOpensquidHookCommand`) — bare modern
+ *      `opensquid-hook-*` commands written before the marker contract existed
+ *      (T-FIX-WIZARD-HOOK-RECOGNITION: these used to be "preserved" as
+ *      third-party, so every wizard re-run DUPLICATED every hook).
+ *
+ * A `.bak` snapshot is written before any mutation. The marker contract is
+ * the FIRST line of defense; .bak is the last. Audit phase MUST verify
+ * every opensquid-written entry carries the marker.
+ *
+ * Engine-vocabulary discipline: this module is the ONLY G.1 file that names
+ * Claude Code's hook event types. `discovery.ts` + `bootstrap.ts` are
+ * harness-agnostic.
+ *
+ * Imported by: src/setup/cli/hooks.ts.
+ */
+export declare const OPENSQUID_BIN_FOR_EVENT: {
+    readonly PreToolUse: "opensquid-hook-pretooluse";
+    readonly PostToolUse: "opensquid-hook-posttooluse";
+    readonly UserPromptSubmit: "opensquid-hook-userpromptsubmit";
+    readonly Stop: "opensquid-hook-stop";
+    readonly SessionEnd: "opensquid-hook-sessionend";
+    readonly SessionStart: "opensquid-hook-sessionstart";
+};
+export type ClaudeEvent = keyof typeof OPENSQUID_BIN_FOR_EVENT;
+export declare const PRETOOLUSE_HOOK_TIMEOUT_S = 360;
+interface HookCommandEntry {
+    type: string;
+    command?: string;
+    '@opensquid'?: boolean;
+    [k: string]: unknown;
+}
+interface HookGroup {
+    matcher?: string;
+    hooks?: HookCommandEntry[];
+    [k: string]: unknown;
+}
+interface SettingsJson {
+    hooks?: Partial<Record<string, HookGroup[]>>;
+    [k: string]: unknown;
+}
+export declare const LEGACY_OPENSQUID_PATTERN: RegExp;
+/** Is this command string one of opensquid's hook binaries (any path, any era)? */
+export declare const isOpensquidHookCommand: (command: string) => boolean;
+/** Is this inner hook entry opensquid-owned (marker OR command shape)? */
+export declare const isOpensquidHookEntry: (h: HookCommandEntry) => boolean;
+export interface WriteResult {
+    /** Number of fresh opensquid entries added — one per `OPENSQUID_BIN_FOR_EVENT` key. */
+    added: number;
+    /**
+     * Number of groups that had opensquid-owned entries removed — wholly-owned
+     * groups dropped OR owned entries excised from a mixed group (a mixed group
+     * increments BOTH `replaced` and `preserved`: ours left, the group survived).
+     */
+    replaced: number;
+    /** Number of hook groups preserved (verbatim, or minus excised owned entries). */
+    preserved: number;
+    /** Path to the `.bak` snapshot written before mutation. */
+    backupPath: string;
+}
+/**
+ * Pure projection — disk-untouched. Used by both the writer and `--dry-run`.
+ * Input JSON is deep-cloned (JSON round-trip; safe because settings.json
+ * never contains Date/Set/Map/functions), so callers' objects don't mutate.
+ */
+export declare function projectOpensquidHooks(input: SettingsJson): {
+    output: SettingsJson;
+    added: number;
+    replaced: number;
+    preserved: number;
+};
+/**
+ * Write opensquid's hook entries to `settingsPath`. Creates a `.bak` snapshot
+ * (`{}` if the file didn't exist). Same 2-space JSON indentation as the live
+ * file so `diff <file>.bak <file>` highlights only the hook changes.
+ */
+export declare function writeOpensquidHooks(settingsPath: string): Promise<WriteResult>;
+/** ENOENT → `{}` (first-run case). All other errors propagate. */
+export declare function readSettingsJson(settingsPath: string): Promise<SettingsJson>;
+export {};
+//# sourceMappingURL=settings-writer.d.ts.map

package/dist/setup/wizard/settings-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-writer.d.ts","sourceRoot":"","sources":["../../../src/setup/wizard/settings-writer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAUH,eAAO,MAAM,uBAAuB;;;;;;;CAW1B,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,uBAAuB,CAAC;AAS/D,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAI7C,UAAU,gBAAgB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AACD,UAAU,SAAS;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC3B,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AACD,UAAU,YAAY;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC;IAC7C,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAKD,eAAO,MAAM,wBAAwB,QAAuD,CAAC;AAU7F,mFAAmF;AACnF,eAAO,MAAM,sBAAsB,GAAI,SAAS,MAAM,KAAG,OAIxD,CAAC;AAEF,0EAA0E;AAC1E,eAAO,MAAM,oBAAoB,GAAI,GAAG,gBAAgB,KAAG,OACuC,CAAC;AAEnG,MAAM,WAAW,WAAW;IAC1B,uFAAuF;IACvF,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,YAAY,GAAG;IAC1D,MAAM,EAAE,YAAY,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,CA8CA;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CASpF;AAED,kEAAkE;AAClE,wBAAsB,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAQlF"}

package/dist/setup/wizard/settings-writer.js

@@ -0,0 +1,154 @@
+/**
+ * Idempotent writer for Claude Code's `settings.json` hook block (G.1 Part B).
+ *
+ * Writes opensquid's anti-drift hook entries (one per event in
+ * `OPENSQUID_BIN_FOR_EVENT`: PreToolUse, PostToolUse, UserPromptSubmit, Stop,
+ * SessionEnd, SessionStart) while preserving every non-opensquid hook entry
+ * verbatim.
+ *
+ * Three recognition rules identify entries the writer OWNS (all three live in
+ * `isOpensquidHookEntry` — the ONE ownership predicate, also consumed by
+ * doctor's managed-filter + spawn gate and the flow-health check):
+ *   1. `'@opensquid': true` marker on the inner hook entry — every entry the
+ *      writer adds carries this.
+ *   2. `LEGACY_OPENSQUID_PATTERN` regex — the broken ancient
+ *      `node <abs>/opensquid/dist/index.js anti-drift <event>` shape (G.1).
+ *   3. Bin-name basename match (`isOpensquidHookCommand`) — bare modern
+ *      `opensquid-hook-*` commands written before the marker contract existed
+ *      (T-FIX-WIZARD-HOOK-RECOGNITION: these used to be "preserved" as
+ *      third-party, so every wizard re-run DUPLICATED every hook).
+ *
+ * A `.bak` snapshot is written before any mutation. The marker contract is
+ * the FIRST line of defense; .bak is the last. Audit phase MUST verify
+ * every opensquid-written entry carries the marker.
+ *
+ * Engine-vocabulary discipline: this module is the ONLY G.1 file that names
+ * Claude Code's hook event types. `discovery.ts` + `bootstrap.ts` are
+ * harness-agnostic.
+ *
+ * Imported by: src/setup/cli/hooks.ts.
+ */
+import { promises as fs } from 'node:fs';
+// Maps opensquid's supported Claude Code hook events to the bin entries
+// declared in package.json (resolve to `dist/runtime/hooks/*.js` binaries
+// that already wire `loadActivePacks` + `dispatchEvent`).
+// T-POSTPUSH POSTPUSH.1 (2026-05-29) added PostToolUse; T-HANDOFF-HARDENING
+// HH6.1 (2026-05-31) added SessionStart. Existing users need to re-run
+// `opensquid setup` to register newly-added hooks in their settings.json.
+export const OPENSQUID_BIN_FOR_EVENT = {
+    PreToolUse: 'opensquid-hook-pretooluse',
+    PostToolUse: 'opensquid-hook-posttooluse',
+    UserPromptSubmit: 'opensquid-hook-userpromptsubmit',
+    Stop: 'opensquid-hook-stop',
+    SessionEnd: 'opensquid-hook-sessionend',
+    // T-HANDOFF-HARDENING HH6.1 (2026-05-31) — SessionStart is the 6th entry.
+    // Like POSTPUSH.1's PostToolUse, existing users must re-run `opensquid
+    // setup` to register the new hook in their settings.json (the same re-run
+    // reconciles any prior-added-but-uninstalled event, e.g. PostToolUse).
+    SessionStart: 'opensquid-hook-sessionstart',
+};
+// T-AUDIT-SPAWN-FIX (2026-06-10): the PreToolUse hook hosts the BLOCKING
+// coding-flow audits (claude -p reasoning calls measured to 268s under
+// subscription contention; inner audit window 340s). Without an explicit
+// timeout the host's default hook cap (≈60s) kills the hook before any audit
+// can finish — fresh installs were broken out of the box. Only PreToolUse
+// carries the cap; the other five events keep host defaults. Existing users
+// pick it up by re-running `opensquid setup` (same convention as POSTPUSH.1).
+export const PRETOOLUSE_HOOK_TIMEOUT_S = 360;
+// Legacy detector — deliberately specific to avoid false positives on
+// user-authored commands that mention "opensquid" elsewhere (e.g. a custom
+// audit script). Matches: `node <abs>/opensquid<...>/dist/index.js anti-drift`.
+export const LEGACY_OPENSQUID_PATTERN = /node\s+\S*opensquid\S*dist\/index\.js\s+anti-drift/;
+// T-FIX-WIZARD-HOOK-RECOGNITION: the ONE hook-ownership predicate, shared by
+// the writer's surgery below AND doctor's managed-filter + spawn security
+// gate. Ownership classification used to live in three divergent forms
+// (marker+legacy here, a broader substring regex in doctor) — pre-marker
+// installs carrying the bare modern bin name matched neither writer arm, so
+// a wizard re-run "preserved" them as third-party and DUPLICATED every hook.
+const OPENSQUID_BIN_NAMES = new Set(Object.values(OPENSQUID_BIN_FOR_EVENT));
+/** Is this command string one of opensquid's hook binaries (any path, any era)? */
+export const isOpensquidHookCommand = (command) => {
+    if (LEGACY_OPENSQUID_PATTERN.test(command))
+        return true;
+    const first = command.trim().split(/\s+/)[0] ?? '';
+    return OPENSQUID_BIN_NAMES.has(first.slice(first.lastIndexOf('/') + 1));
+};
+/** Is this inner hook entry opensquid-owned (marker OR command shape)? */
+export const isOpensquidHookEntry = (h) => h['@opensquid'] === true || (typeof h.command === 'string' && isOpensquidHookCommand(h.command));
+/**
+ * Pure projection — disk-untouched. Used by both the writer and `--dry-run`.
+ * Input JSON is deep-cloned (JSON round-trip; safe because settings.json
+ * never contains Date/Set/Map/functions), so callers' objects don't mutate.
+ */
+export function projectOpensquidHooks(input) {
+    const output = JSON.parse(JSON.stringify(input));
+    output.hooks ??= {};
+    let added = 0;
+    let replaced = 0;
+    let preserved = 0;
+    for (const event of Object.keys(OPENSQUID_BIN_FOR_EVENT)) {
+        const groups = (output.hooks[event] ??= []);
+        // Per-ENTRY surgery (T-FIX-WIZARD-HOOK-RECOGNITION): a wholly-owned group
+        // is dropped (incl. the DECLARED matcher convergence — canonical entries
+        // are matcher-less; opensquid bins receive every event of their type and
+        // self-filter); a MIXED group keeps its matcher + foreign siblings (the
+        // module's preservation contract) with only the owned entries excised.
+        const filtered = [];
+        for (const group of groups) {
+            const inner = group.hooks ?? [];
+            const owned = inner.filter((h) => isOpensquidHookEntry(h));
+            if (owned.length === 0) {
+                filtered.push(group);
+                preserved += 1;
+                continue;
+            }
+            if (owned.length === inner.length) {
+                replaced += 1; // wholly ours — drop; canonical append below
+                continue;
+            }
+            // MIXED: excise ours, keep the group (matcher + foreign hooks intact).
+            filtered.push({ ...group, hooks: inner.filter((h) => !isOpensquidHookEntry(h)) });
+            replaced += 1; // ...for the excised owned entr(ies)
+            preserved += 1; // ...for the surviving foreign group
+        }
+        filtered.push({
+            hooks: [
+                {
+                    type: 'command',
+                    command: OPENSQUID_BIN_FOR_EVENT[event],
+                    '@opensquid': true,
+                    ...(event === 'PreToolUse' ? { timeout: PRETOOLUSE_HOOK_TIMEOUT_S } : {}),
+                },
+            ],
+        });
+        added += 1;
+        output.hooks[event] = filtered;
+    }
+    return { output, added, replaced, preserved };
+}
+/**
+ * Write opensquid's hook entries to `settingsPath`. Creates a `.bak` snapshot
+ * (`{}` if the file didn't exist). Same 2-space JSON indentation as the live
+ * file so `diff <file>.bak <file>` highlights only the hook changes.
+ */
+export async function writeOpensquidHooks(settingsPath) {
+    const input = await readSettingsJson(settingsPath);
+    const backupPath = `${settingsPath}.bak`;
+    await fs.writeFile(backupPath, JSON.stringify(input, null, 2));
+    const { output, added, replaced, preserved } = projectOpensquidHooks(input);
+    await fs.writeFile(settingsPath, JSON.stringify(output, null, 2));
+    return { added, replaced, preserved, backupPath };
+}
+/** ENOENT → `{}` (first-run case). All other errors propagate. */
+export async function readSettingsJson(settingsPath) {
+    try {
+        const raw = await fs.readFile(settingsPath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return {};
+        throw e;
+    }
+}
+//# sourceMappingURL=settings-writer.js.map

package/dist/setup/wizard/settings-writer.js.map

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

package/dist/storage/atomic_file.d.ts

@@ -0,0 +1,3 @@
+export declare function safeRecordId(id: string): string;
+export declare function atomicWriteFile(path: string, content: string): Promise<void>;
+//# sourceMappingURL=atomic_file.d.ts.map

package/dist/storage/atomic_file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic_file.d.ts","sourceRoot":"","sources":["../../src/storage/atomic_file.ts"],"names":[],"mappings":"AAeA,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAK/C;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKlF"}

package/dist/storage/atomic_file.js

@@ -0,0 +1,27 @@
+/**
+ * Shared atomic single-file write (T-WORKGRAPH-EVENTSOURCED slice 1d). Extracted so both the
+ * per-file lessons source (src/rag/backends/perfile_source.ts) and the work-graph op-log
+ * (src/workgraph) share ONE atomic-write primitive instead of duplicating temp+rename.
+ *
+ * `atomicWriteFile` writes a `.tmp` then `rename()`s it into place — atomic on POSIX, so a reader
+ * never sees a partial/corrupt file and a crash mid-write leaves the previous file intact.
+ * `safeRecordId` rejects ids that could escape the target dir (record ids are content hashes,
+ * never paths).
+ *
+ * Imports from: node:fs/promises, node:path.
+ */
+import { mkdir, rename, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+export function safeRecordId(id) {
+    if (id.length === 0 || id.includes('/') || id.includes('\\') || id.includes('..')) {
+        throw new Error(`atomic_file: unsafe record id: ${JSON.stringify(id)}`);
+    }
+    return id;
+}
+export async function atomicWriteFile(path, content) {
+    await mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    await writeFile(tmp, content, 'utf8');
+    await rename(tmp, path); // atomic on POSIX → readers never see a partial file
+}
+//# sourceMappingURL=atomic_file.js.map

package/dist/storage/atomic_file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic_file.js","sourceRoot":"","sources":["../../src/storage/atomic_file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,MAAM,UAAU,YAAY,CAAC,EAAU;IACrC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAClF,MAAM,IAAI,KAAK,CAAC,kCAAkC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAC1E,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAY,EAAE,OAAe;IACjE,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAChD,MAAM,GAAG,GAAG,GAAG,IAAI,MAAM,CAAC;IAC1B,MAAM,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IACtC,MAAM,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,qDAAqD;AAChF,CAAC"}

package/dist/system-export.d.ts

@@ -0,0 +1,65 @@
+/**
+ * `opensquid export / import` — entire ~/.opensquid/ state bundle.
+ *
+ * Used to back up everything the engine writes (codexes, lessons,
+ * memories with .vec sidecars, hooks state under sessions/, project
+ * ID cards, engine config) into a single portable archive. Re-import
+ * on a fresh machine restores identical state.
+ *
+ * Format: tar.gz via system `tar` (bsdtar on macOS / Windows 10+,
+ * GNU tar on Linux — all support `-czf` / `-xzf`). Reasoning: zero
+ * new dependency, deterministic byte layout, easy to inspect via
+ * `tar tzf`. Encryption deferred — pass through gpg externally for
+ * now (`gpg -c <archive>`).
+ *
+ * Round-trip semantics:
+ * - export writes tar.gz containing the entire ~/.opensquid/ tree
+ *   relative to $HOME so paths remain portable across machines
+ * - import accepts --merge (default — extracts on top of existing
+ *   ~/.opensquid/, last-write-wins per file) or --replace (wipe
+ *   ~/.opensquid/ first then extract). Vector index .vec sidecars
+ *   carry through; engine rehydrates the in-memory HNSW on next
+ *   spawn from those sidecars.
+ *
+ * Failure modes:
+ * - missing tar binary → throw with install-tar hint
+ * - existing output path → refuse without --force
+ * - tar exit non-zero → propagate stderr
+ * - --replace on non-empty ~/.opensquid/ + missing input archive → no
+ *   data loss because we extract to a tmp dir first then atomic rename
+ */
+export declare class SystemExportError extends Error {
+    readonly hint?: string | undefined;
+    constructor(message: string, hint?: string | undefined);
+}
+export interface ExportOptions {
+    /** Output archive path. Defaults to `./opensquid-<timestamp>.tar.gz`. */
+    output?: string;
+    /** Overwrite existing output path. */
+    force?: boolean;
+    /** Override the source data root (default: `LOOP_HOME` or `~/.opensquid/`). */
+    dataRoot?: string;
+}
+export interface ExportResult {
+    output: string;
+    size_bytes: number;
+}
+export declare function exportSystem(opts?: ExportOptions): Promise<ExportResult>;
+export interface ImportOptions {
+    /** Source archive path. */
+    input: string;
+    /**
+     * `merge` (default): extract on top of existing data root, last-write
+     * -wins per file. `replace`: wipe data root first then extract.
+     */
+    mode?: "merge" | "replace";
+    /** Override the destination data root. */
+    dataRoot?: string;
+}
+export interface ImportResult {
+    input: string;
+    data_root: string;
+    mode: "merge" | "replace";
+}
+export declare function importSystem(opts: ImportOptions): Promise<ImportResult>;
+//# sourceMappingURL=system-export.d.ts.map

package/dist/system-export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-export.d.ts","sourceRoot":"","sources":["../src.legacy/system-export.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAOH,qBAAa,iBAAkB,SAAQ,KAAK;aAGxB,IAAI,CAAC,EAAE,MAAM;gBAD7B,OAAO,EAAE,MAAM,EACC,IAAI,CAAC,EAAE,MAAM,YAAA;CAKhC;AAaD,MAAM,WAAW,aAAa;IAC5B,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wBAAsB,YAAY,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,CAAC,CA+ClF;AAED,MAAM,WAAW,aAAa;IAC5B,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3B,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,OAAO,GAAG,SAAS,CAAC;CAC3B;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CA0D7E"}