opensquid 0.5.395

package/dist/setup/cli/doctor.js

@@ -0,0 +1,314 @@
+/**
+ * `opensquid doctor hooks` — health check for Claude Code hook wiring (G.2).
+ *
+ * Reads `~/.claude/settings.json` + `<cwd>/.claude/settings.json`, finds
+ * opensquid-managed hook entries (regex `/opensquid-hook|opensquid.*anti-drift/`),
+ * spawns each with a canonical Claude Code event payload, checks STDERR for
+ * the `[opensquid-dispatch]` marker. Marker absence = silent-no-op (the G.1
+ * root-cause failure mode). Exit 0 if all green, 1 if any red (CI-friendly).
+ *
+ * Security gate: NEVER spawns a command the shared ownership predicate
+ * (`isOpensquidHookCommand`, settings-writer.ts) doesn't claim —
+ * non-matching entries SKIPPED with note ("not opensquid-managed").
+ * D9-guard prompt-type hooks SKIPPED ("non-spawnable hook type").
+ *
+ * Engine-vocabulary discipline: consumer-side file — knows about Claude
+ * Code's settings.json + hook events. Runtime stays harness-agnostic.
+ *
+ * Imported by: src/cli.ts.
+ */
+import { spawn } from 'node:child_process';
+import { readFile, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { computeMemoryDrift, renderMemoryDrift } from '../migrate/memory_drift.js';
+import { makeMemoryStore } from '../migrate/memory_store_handle.js';
+import { readSettingsHooks } from '../wizard/settings-reader.js';
+import { OPENSQUID_BIN_FOR_EVENT, isOpensquidHookCommand, isOpensquidHookEntry, } from '../wizard/settings-writer.js';
+/** `/`→`-`, matching Claude Code's auto-memory dir naming. Mirrors the inline
+ * copies in `memory.ts` / `memory_reconcile.ts` (stable one-liner; no shared
+ * import to avoid a cli→hooks layering edge). */
+function encodeProjectPath(projectPath) {
+    return projectPath.replace(/\//g, '-');
+}
+// T-FIX-WIZARD-HOOK-RECOGNITION: the spawn/managed gate now uses the SHARED
+// ownership predicate `isOpensquidHookCommand` (settings-writer.ts) — the old
+// local substring regex was one of three divergent classifiers and could both
+// miss real entries and spawn lookalikes (`opensquid-hook-typo-not-ours`).
+/** Maps Claude Code event names → canonical event-kind label + minimal
+ * snake_case stdin payload satisfying each hook bin's parser. */
+const PROBE_PAYLOADS = {
+    PreToolUse: {
+        kind: 'tool_call',
+        stdin: JSON.stringify({
+            tool_name: 'Bash',
+            tool_input: { command: 'echo probe' },
+            session_id: 'doctor-probe',
+        }),
+    },
+    UserPromptSubmit: {
+        kind: 'prompt_submit',
+        stdin: JSON.stringify({ prompt: 'doctor-probe', session_id: 'doctor-probe' }),
+    },
+    Stop: {
+        kind: 'stop',
+        stdin: JSON.stringify({ assistant_text: 'doctor-probe', session_id: 'doctor-probe' }),
+    },
+    SessionEnd: { kind: 'session_end', stdin: JSON.stringify({ session_id: 'doctor-probe' }) },
+    // T-POSTPUSH POSTPUSH.1 — PostToolUse is in OPENSQUID_BIN_FOR_EVENT, so a
+    // setup re-run installs it; doctor must have a probe so it greens instead
+    // of red-flagging "no probe payload registered".
+    PostToolUse: {
+        kind: 'post_tool_call',
+        stdin: JSON.stringify({
+            tool_name: 'Bash',
+            tool_input: { command: 'echo probe' },
+            tool_result: { exit_code: 0 },
+            session_id: 'doctor-probe',
+        }),
+    },
+    // T-HANDOFF-HARDENING HH6.1 — SessionStart probe MUST use a dispatching
+    // source (startup), not clear/compact, so the dispatch marker is emitted
+    // and the probe greens.
+    SessionStart: {
+        kind: 'session_start',
+        stdin: JSON.stringify({ session_id: 'doctor-probe', source: 'startup' }),
+    },
+};
+/** CHS.1 — the codex-hooks section lines (pure in the path argument). */
+export async function checkCodexHooks(path) {
+    let raw;
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch {
+        return [
+            '[INFO]   codex shell: not installed (optional) — `opensquid setup wizard codex-hooks`',
+        ];
+    }
+    let marked = 0;
+    try {
+        const parsed = JSON.parse(raw);
+        for (const groups of Object.values(parsed.hooks ?? {})) {
+            for (const g of groups) {
+                marked += (g.hooks ?? []).filter((h) => isOpensquidHookEntry(h)).length;
+            }
+        }
+    }
+    catch {
+        return [
+            `[RED]    codex shell: ${path} is not valid JSON — re-run \`opensquid setup wizard codex-hooks\``,
+        ];
+    }
+    return [
+        marked > 0
+            ? `[GREEN]  codex shell: ${String(marked)} opensquid hook entr${marked === 1 ? 'y' : 'ies'} in hooks.json`
+            : `[INFO]   codex shell: hooks.json present but no opensquid entries — \`opensquid setup wizard codex-hooks\``,
+        '         trust state lives in codex user-config hashes (not inspectable here) — verify via /hooks in codex',
+    ];
+}
+/** Pure runner — disk + spawn injectable for tests. */
+export async function runDoctorHooks(opts) {
+    const probe = opts.spawnProbe ?? defaultSpawnProbe;
+    const results = [];
+    const scopes = [
+        ['user', opts.userSettingsPath],
+        ['project', opts.projectSettingsPath],
+    ];
+    for (const [scope, path] of scopes) {
+        let entries;
+        try {
+            entries = await readSettingsHooks(path);
+        }
+        catch (e) {
+            results.push(mk(scope, '-', path, 'red', `could not parse ${path}: ${String(e)}`));
+            continue;
+        }
+        if (entries.length === 0) {
+            results.push(mk(scope, '-', path, 'skipped', `no hooks at ${path}`));
+            continue;
+        }
+        for (const entry of entries)
+            results.push(await probeEntry(scope, entry, probe));
+        // FC.5 coverage: a scope that manages opensquid hooks must register the FULL
+        // canonical set — flag any OPENSQUID_BIN_FOR_EVENT event ENTIRELY ABSENT (a
+        // present-but-broken event is already RED via probeEntry, so no double-count).
+        // A scope with zero opensquid hooks is exempt (project scope is optional).
+        const managed = entries.filter((e) => e.type === 'command' && isOpensquidHookCommand(e.command));
+        if (managed.length > 0) {
+            const present = new Set(managed.map((e) => e.event));
+            for (const [event, command] of Object.entries(OPENSQUID_BIN_FOR_EVENT)) {
+                if (!present.has(event)) {
+                    results.push(mk(scope, event, command, 'red', 'not registered in settings.json — run `opensquid setup wizard hooks`'));
+                }
+            }
+        }
+    }
+    return results;
+}
+function mk(scope, event, command, status, reason) {
+    return { scope, event, command, status, reason };
+}
+async function probeEntry(scope, entry, probe) {
+    // D9-guard prompt-type → not a subprocess; cannot probe.
+    if (entry.type === 'prompt') {
+        return mk(scope, entry.event, entry.prompt, 'skipped', 'non-spawnable hook type (inline prompt)');
+    }
+    // Security gate: only spawn commands the shared ownership predicate claims.
+    if (!isOpensquidHookCommand(entry.command)) {
+        return mk(scope, entry.event, entry.command, 'skipped', 'not opensquid-managed');
+    }
+    const probePayload = PROBE_PAYLOADS[entry.event];
+    if (!probePayload) {
+        return mk(scope, entry.event, entry.command, 'red', `unknown event "${entry.event}" — no probe payload registered`);
+    }
+    let result;
+    try {
+        result = await probe(entry.command, probePayload.stdin);
+    }
+    catch (e) {
+        return mk(scope, entry.event, entry.command, 'red', `spawn failed: ${String(e)}`);
+    }
+    const expectedMarker = `[opensquid-dispatch] event=${probePayload.kind}`;
+    if (!result.stderr.includes(expectedMarker)) {
+        return mk(scope, entry.event, entry.command, 'red', `marker absent (expected "${expectedMarker}"), likely silent no-op (G.1 broken-path bug); exit=${String(result.exitCode)}`);
+    }
+    return mk(scope, entry.event, entry.command, 'green', 'marker present');
+}
+/** Default subprocess probe — spawn `sh -c <command>` so PATH-resolved bin
+ * names work the same way Claude Code itself spawns them. Times out after
+ * 10s so a misbehaving hook can't hang the doctor CLI. */
+function defaultSpawnProbe(command, stdin) {
+    return new Promise((res, rej) => {
+        // OPENSQUID_DISPATCH_TRACE forced on for the probe — the user may have it
+        // off in their normal env, but doctor MUST see the marker to assess.
+        const env = { ...process.env, OPENSQUID_DISPATCH_TRACE: '1' };
+        const p = spawn(command, {
+            shell: true,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env,
+        });
+        let stderr = '';
+        const timer = setTimeout(() => {
+            p.kill('SIGKILL');
+            rej(new Error('probe timeout (10s)'));
+        }, 10_000);
+        p.stderr.on('data', (b) => (stderr += b.toString('utf8')));
+        p.on('error', (err) => {
+            clearTimeout(timer);
+            rej(err);
+        });
+        p.on('close', (code) => {
+            clearTimeout(timer);
+            res({ exitCode: code ?? -1, stderr });
+        });
+        p.stdin.write(stdin);
+        p.stdin.end();
+    });
+}
+/** Pretty-print to stdout. Returns the number of RED results (caller maps to
+ * process exit code). */
+export function printReport(results) {
+    let red = 0;
+    for (const r of results) {
+        const tag = r.status === 'green' ? '[GREEN]  ' : r.status === 'red' ? '[RED]    ' : '[SKIPPED]';
+        if (r.status === 'red')
+            red += 1;
+        const cmdTrunc = r.command.length > 60 ? r.command.slice(0, 57) + '...' : r.command;
+        process.stdout.write(`${tag} ${r.scope}/${r.event}: ${cmdTrunc}\n`);
+        if (r.reason)
+            process.stdout.write(`           reason: ${r.reason}\n`);
+    }
+    process.stdout.write(`\nsummary: ${String(results.filter((r) => r.status === 'green').length)} green, ${String(red)} red, ${String(results.filter((r) => r.status === 'skipped').length)} skipped\n`);
+    return red;
+}
+export function registerDoctor(program) {
+    const doc = program.command('doctor').description('Health checks for opensquid configuration');
+    doc
+        .command('hooks')
+        .description('Check that configured Claude Code hooks actually dispatch (G.2)')
+        .action(async () => {
+        const userPath = resolve(process.env.HOME ?? '', '.claude/settings.json');
+        const projectPath = join(process.cwd(), '.claude/settings.json');
+        const results = await runDoctorHooks({
+            userSettingsPath: userPath,
+            projectSettingsPath: projectPath,
+        });
+        const red = printReport(results);
+        process.exit(red === 0 ? 0 : 1);
+    });
+    // CHS.1 — the codex host shell section: file presence + marked-entry
+    // count. Trust state lives in codex's user-config hashes (not inspectable
+    // here) — the report always points at /hooks in codex. Absent ~/.codex or
+    // hooks.json = INFO, not RED (codex is optional).
+    doc
+        .command('codex-hooks')
+        .description('Check the codex host shell (~/.codex/hooks.json presence + opensquid entries)')
+        .action(async () => {
+        const lines = await checkCodexHooks(join(process.env.HOME ?? '', '.codex', 'hooks.json'));
+        for (const l of lines)
+            process.stdout.write(`${l}\n`);
+        process.exit(0);
+    });
+    doc
+        .command('memory')
+        .description('Check the auto-memory ↔ engine-RAG store are in sync (MAU.4)')
+        .action(async () => {
+        // The doctor CLI runs in the project dir, so cwd resolves the auto-memory
+        // dir directly (unlike the SessionEnd hook, which needs the recorded cwd).
+        const dir = join(homedir(), '.claude', 'projects', encodeProjectPath(process.cwd()), 'memory');
+        try {
+            await stat(dir);
+        }
+        catch {
+            process.stdout.write(`memory: no auto-memory dir for this project (${dir})\n`);
+            process.exit(0);
+        }
+        const store = await makeMemoryStore();
+        try {
+            const drift = await computeMemoryDrift(dir, store);
+            process.stdout.write(renderMemoryDrift(drift) + '\n');
+            if (!drift.inSync) {
+                if (drift.missing.length > 0)
+                    process.stdout.write(`  missing:  ${drift.missing.join(', ')}\n`);
+                if (drift.stale.length > 0)
+                    process.stdout.write(`  stale:    ${drift.stale.join(', ')}\n`);
+                if (drift.orphaned.length > 0)
+                    process.stdout.write(`  orphaned: ${drift.orphaned.join(', ')}\n`);
+            }
+            process.exit(drift.inSync ? 0 : 1); // non-zero on drift → fail loud for CI/wrappers
+        }
+        catch (e) {
+            // FAIL-LOUD: a probe failure must never read as "in sync".
+            process.stderr.write(`memory: drift check FAILED — ${String(e)}\n`);
+            process.exit(1);
+        }
+        finally {
+            await store.close();
+        }
+    });
+    doc
+        .command('git-hooks')
+        .description('Check the opensquid git pre-commit/pre-push hooks are installed (GF.2)')
+        .action(async () => {
+        const { gitRoot } = await import('./gate.js');
+        const { checkGitHooks } = await import('../wizard/git-hooks.js');
+        const root = await gitRoot(process.cwd());
+        if (root === null) {
+            process.stdout.write('[SKIPPED] git-hooks: not inside a git work tree\n');
+            process.exit(0);
+        }
+        const res = await checkGitHooks(root);
+        for (const h of res) {
+            const tag = h.state === 'installed' ? 'GREEN' : h.state === 'foreign' ? 'WARN' : 'RED';
+            process.stdout.write(`[${tag}]\t${h.name}: ${h.state}\n`);
+        }
+        const incomplete = res.some((h) => h.state !== 'installed');
+        if (incomplete)
+            process.stdout.write('remediation: opensquid gate install\n');
+        // `unreachable` (a dead managed block below a foreign exec/exit) is as absent as
+        // `missing` — the gate never runs. Both are RED + exit 1.
+        process.exit(res.some((h) => h.state === 'missing' || h.state === 'unreachable') ? 1 : 0);
+    });
+}
+//# sourceMappingURL=doctor.js.map

package/dist/setup/cli/doctor.js.map

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

package/dist/setup/cli/gate.d.ts

@@ -0,0 +1,71 @@
+/**
+ * `opensquid gate commit|push` — the owned-boundary EXECUTE gate (GF.2 — F2 + F3 + F4).
+ *
+ * Invoked by the opensquid-managed git `pre-commit` / `pre-push` hooks. Instead of
+ * pattern-matching tool calls (a denylist over an unbounded input — the F2/F3/F4 hole),
+ * enforcement moves to the boundary git OWNS: git runs these hooks on EVERY commit/push
+ * unconditionally and the gate reads the REAL changed files (ground truth — no
+ * path-guessing) plus the same session FSM / phase / active-task state, and blocks there.
+ *
+ * Contract (total):
+ *   - NON-gated repo (no `.opensquid/active.json` opting into `coding-flow`) → ALLOW (0).
+ *     Never block an unrelated commit on the machine.
+ *   - No changed files, or a docs-only change (flow artifacts: pre-research / spec /
+ *     CHANGELOG live under docs/) → ALLOW (0).
+ *   - GATED repo with code changes: FAIL CLOSED — block (2) unless the live session has an
+ *     active task whose FSM reached `phases_complete` with a complete 7-phase ledger. A
+ *     terminal `phases_complete` is unreachable without SCOPE (guess-audit) + AUTHOR
+ *     (spec-audit) having passed, so this one check transitively enforces all three stages.
+ *   - No resolvable session in a gated repo → block (cannot prove the flow ran).
+ *
+ * The only honest escape is `git commit --no-verify`, a single closed opt-out token a
+ * narrow PreToolUse detector covers (GF.3). Session resolution out-of-band:
+ * `resolveMcpSessionId` (CLAUDE_PROJECT_DIR → project-scoped pointer → global).
+ *
+ * Imported by: src/cli.ts (registerGate); the installed git hooks (`exec opensquid gate …`).
+ */
+import type { Command } from 'commander';
+/** GDC.2 — is this invocation gated? The gate binds to the AGENT, not to a
+ *  location (user directive 2026-06-11: "all agents in any harness; git on
+ *  the terminal behaves normally"): `coding-flow` in the USER scope
+ *  (~/.opensquid/active.json — the agent's own config) gates the agent in
+ *  EVERY repo; a project-scope opt-in still works too (e.g. a team gating
+ *  one repo for all agents). Humans pass upstream regardless
+ *  (isAgentInvocation, GDC.1). */
+export declare function isGatedRepo(cwd: string): Promise<boolean>;
+/** GDC.1 — the flow protects CODE: the same boundary set the in-session write
+ *  gates arm on (scope-lifecycle/skill.yaml:284 — keep the two lists in sync;
+ *  the drift pin in gate.test.ts enforces it). Those matchers are deliberately
+ *  loose substrings; THIS layer is "the precise boundary" (skill.yaml's own
+ *  framing), so startsWith over git's repo-relative paths is the exact form.
+ *  A change touching NONE of these is not the flow's subject (README, banner,
+ *  docs/, LICENSE, CI config…) → allowed, attested under the existing
+ *  `docs_only` wire reason (now meaning "non-code"). [] still fails closed
+ *  (commitFiles' git-error contract). */
+export declare const PROTECTED_PREFIXES: readonly ["src/", "packs/", "test/"];
+/** GDC.1 — the gate's subject is the AGENT, never the human (user directive
+ *  2026-06-11: "I should be able to use the commands naturally"). Agent hosts
+ *  mark their spawned shells (live-probed: Claude Code sets CLAUDECODE +
+ *  AI_AGENT; codex exec sets CODEX_THREAD_ID + AI_AGENT); a human terminal
+ *  sets none. Env-scrubbing evasion is the --no-verify class — policed
+ *  in-session (GF.3), not here. Seam injectable for tests. */
+export declare const AGENT_ENV_MARKERS: readonly ["AI_AGENT", "CLAUDECODE", "CODEX_THREAD_ID"];
+export declare const isAgentInvocation: (env?: NodeJS.ProcessEnv) => boolean;
+/** Does the LIVE session prove a completed flow / docs-only change right now?
+ *  Shared by the commit boundary (block decision) and the attest boundary (record
+ *  decision) so the two can never diverge. Null = not allowed. */
+export declare function commitAllowedNow(sid: string | null, files: string[], env?: NodeJS.ProcessEnv): Promise<{
+    allowed: true;
+    reason: 'docs_only' | 'flow_complete' | 'human';
+} | null>;
+/** The gate decision. Returns the process exit code (0 allow, 2 block). */
+export declare function runGate(boundary: 'commit' | 'push', cwd: string, env?: NodeJS.ProcessEnv): Promise<number>;
+/** PGB.2 — the attest boundary (post-commit hook + `opensquid gate attest` CLI):
+ *  record provenance for HEAD when the live session can prove it RIGHT NOW. Never
+ *  blocks, never throws — recording is best-effort; an unattested commit simply
+ *  falls back to the session check at push time (fail-closed preserved). */
+export declare function runAttest(cwd: string, env?: NodeJS.ProcessEnv): Promise<number>;
+/** Resolve the git work-tree root for `cwd`, or null if not in a repo. */
+export declare function gitRoot(cwd: string): Promise<string | null>;
+export declare function registerGate(program: Command): void;
+//# sourceMappingURL=gate.d.ts.map

package/dist/setup/cli/gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../../../src/setup/cli/gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAOH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAazC;;;;;;kCAMkC;AAClC,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAa/D;AAyBD;;;;;;;;yCAQyC;AACzC,eAAO,MAAM,kBAAkB,sCAAuC,CAAC;AAIvE;;;;;8DAK8D;AAC9D,eAAO,MAAM,iBAAiB,wDAAyD,CAAC;AACxF,eAAO,MAAM,iBAAiB,GAAI,MAAK,MAAM,CAAC,UAAwB,KAAG,OACnB,CAAC;AAOvD;;kEAEkE;AAClE,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,GAAG,IAAI,EAClB,KAAK,EAAE,MAAM,EAAE,EACf,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAAC;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,WAAW,GAAG,eAAe,GAAG,OAAO,CAAA;CAAE,GAAG,IAAI,CAAC,CAWpF;AAoCD,2EAA2E;AAC3E,wBAAsB,OAAO,CAC3B,QAAQ,EAAE,QAAQ,GAAG,MAAM,EAC3B,GAAG,EAAE,MAAM,EACX,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAAC,MAAM,CAAC,CA8CjB;AAYD;;;4EAG4E;AAC5E,wBAAsB,SAAS,CAC7B,GAAG,EAAE,MAAM,EACX,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAAC,MAAM,CAAC,CAsBjB;AAED,0EAA0E;AAC1E,wBAAsB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAOjE;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAqCnD"}