@davesheffer/hunch 1.33.0 → 1.36.0

package/README.md

@@ -23,6 +23,9 @@ hunch init
 hunch backfill --since 90d   # optional: draft memory from recent history
 ```
 
+If the shell reports that `hunch` is not found, initialize without a global binary from the
+repository directory: `npx -y @davesheffer/hunch@latest init`.
+
 Reload your assistant, then ask:
 
 > Why is this built this way, and what should I preserve when changing it?
@@ -78,8 +81,13 @@ From each repository that uses Hunch:
 hunch update
 ```
 
+If the shell reports that `hunch` is not found, run
+`npx -y @davesheffer/hunch@latest update` from the repository instead.
+
 Or ask your agent to **“update Hunch.”** The command installs the latest release, aligns configured integration pins, repairs known legacy launch commands, and refreshes Hunch instructions. It preserves unrelated settings and intentionally disabled hooks.
 
+Installed interactive CLI commands can also show a cached update notice. At most once every 24 hours, a detached worker asks npm for the package's public `latest` version; hooks, MCP, CI, servers, the updater, non-interactive commands, and source checkouts skip that request. Set `HUNCH_NO_UPDATE_CHECK=1` or `NO_UPDATE_NOTIFIER=1` to disable it.
+
 - A standalone npm project keeps Hunch in its existing dependency section at an exact version. Without a repository dependency, the global CLI is updated. Add `--global` to update both.
 - For other package managers or workspaces, update the dependency with that package manager, then run `hunch integrations repair-pins`.
 - Restart or reconnect active assistants. In Codex, open `/hooks` to review and trust changed commands, then start a new session. A changed version pin changes the command and requires renewed trust.
@@ -178,7 +186,7 @@ Profiles retain their revision, sources, confidence, and freshness. [Project DNA
 - [Review memory](docs/review-memory.md)
 - [Agent-origin handling](docs/agent-origin.md)
 - [Autonomy ladder](docs/autonomy-ladder.md)
-- [Autonomous development](docs/autonomous-development.md)
+- [Autonomous development](https://github.com/davesheffer/hunch-private/blob/main/projects/hunch/docs/autonomous-development.md)
 - [Changelog](CHANGELOG.md) · [Roadmap](ROADMAP.md)
 - [VS Code extension](vscode-extension/README.md)
 - [Architecture benchmark](bench/architectural-conformance.md)

package/dist/cli/index.js

@@ -66,6 +66,7 @@ import { scaffoldProviders, regenerateGrounding, refreshExistingGrounding, refre
 import { healClaudeConfigCaseSplit } from "../integrations/claudeConfig.js";
 import { formatSearchHit, formatStructure } from "../core/format.js";
 import { isStateKind, renderStateLine, stateSupplements } from "../core/stateDelivery.js";
+import { taskSupplements } from "../core/taskDelivery.js";
 import { diagnoseIssueCorrectionStage, formatCorrectionStageDiagnostic } from "../core/correctionStage.js";
 import { compileVerifiedEvidenceMap, formatVerifiedEvidenceMap } from "../core/evidenceMap.js";
 import { collectCorrectionStageSources } from "../extractors/correctionSources.js";
@@ -85,7 +86,7 @@ import { recordServed, servedSummary } from "../core/served.js";
 import { recordTaskDelivery, reportActivity, reportPresentationEnabled, unseenLessons } from "../core/taskReport.js";
 import { snapshotDeliveredRecords } from "../core/taskReportEvidence.js";
 import { renderRecalledLine } from "../core/taskReportRender.js";
-import { hookReportTaskId, startHookReport, stopHookReport, observeHookDenial } from "../core/taskReportHook.js";
+import { hookReportTaskId, nativeHookCwd, startHookReport, stopHookReport, observeHookDenial } from "../core/taskReportHook.js";
 import { recordHookObservation } from "../core/hookObservations.js";
 import { contextHookOutput, denyHookOutput, hookProvider, normalizeHookEvent, stopHookOutput } from "../core/agenthook.js";
 import { PIPELINE_LOOP, armExecutionObligations, beforeEditProbeVerdict, compileExecutableProbes, environmentExecutableProbes, environmentExecutionObligations, executionObligationBrief, isProductPath, loadPipelineState, onCommand, onEdit, onPrompt, onSkill, pipelineEnabled, proofCheckpoint, savePipelineState, stopVerdict, unverifiedNag, } from "../core/pipeline.js";
@@ -131,6 +132,7 @@ import { ENTITY_KINDS } from "../core/types.js";
 import { planCompaction } from "../store/compact.js";
 import { repairDecisionReference } from "../core/refrepair.js";
 import { resolveInvocation, dim, synthesisStatusLines, maybeWarnOllamaContext } from "./invocation.js";
+import { formatUpdateNotice, scheduleUpdateCheck, shouldCheckForUpdate } from "../core/updatecheck.js";
 const program = new Command();
 program.name("hunch").description("Hunch — engineering memory and a deterministic Change Gate for AI-assisted codebases.").version(HUNCH_VERSION);
 program.option("--initiator <name>", "bind agent launches to the originating CLI (Claude, Codex, Kimi, or a configured adapter)")
@@ -200,6 +202,29 @@ registerReviewMemoryCommands(program, (records, repository, privateOnly) => {
     return { root, existing: store.captureHome(privateOnly) === "private"
             ? store.recs("constraints") : store.json.loadAll("constraints") };
 });
+// Read an already-known update and schedule any registry refresh in a detached
+// worker. No network handle is opened in this command's process, so the
+// advisory cannot delay command completion or process exit.
+program.hook("preAction", (_thisCommand, actionCommand) => {
+    try {
+        const path = [actionCommand.name()];
+        for (let parent = actionCommand.parent; parent && parent !== program; parent = parent.parent)
+            path.unshift(parent.name());
+        const gate = {
+            commandName: path.join(" "),
+            isTTY: process.stderr.isTTY === true,
+            installed: resolveInvocation().installed,
+        };
+        if (!shouldCheckForUpdate(gate))
+            return;
+        const result = scheduleUpdateCheck();
+        if (result)
+            console.error(dim(formatUpdateNotice(result)));
+    }
+    catch {
+        // Never let the update-check advisory abort the command it's piggybacking on.
+    }
+});
 let openStore = null;
 function openTeamStore(root, opts = {}) {
     // A committed team.json is an explicit declaration that this checkout belongs
@@ -4186,14 +4211,14 @@ program
         decisionCorpus: store.recs("decisions"),
         historical: !!asOf,
         profile: opts.profile,
-        supplements: stateGrounding,
+        supplements: [...stateGrounding, ...(asOf ? [] : taskSupplements(store.tasksFor(target, 3), target))],
     });
     process.stdout.write(envelope.text);
     if (opts.task) {
         try {
             const records = asOf ? [] : snapshotDeliveredRecords(store, envelope);
             const recalled = renderRecalledLine(unseenLessons(root, opts.task, records));
-            const occurrence = recordTaskDelivery(root, opts.task, envelope, records);
+            const occurrence = recordTaskDelivery(root, opts.task, envelope, records, undefined, target);
             console.log(`\n${recalled ? `${recalled}\n` : ""}Task evidence: ${opts.task} · occurrence ${occurrence}`);
         }
         catch {
@@ -4582,6 +4607,12 @@ program
             // explorers get the indexed shape, planners get live decisions + what
             // was already rejected, everyone else gets the invariant digest. Public
             // store only; cheap reads.
+            const routedCwd = nativeHookCwd(root, provider, evt);
+            // A native host that supplied cwd made an explicit scope claim. If it is
+            // malformed or names another checkout, serving this process root's memory
+            // would cross worktrees; stay silent instead of guessing which side is right.
+            if ((provider === "claude" || provider === "codex") && evt.cwd !== undefined && !routedCwd)
+                return;
             const s = new HunchStore(paths);
             try {
                 const clip1 = (text, max) => {
@@ -4591,11 +4622,19 @@ program
                 const type = (evt.agent_type ?? "").toLowerCase();
                 const L = [];
                 const served = [];
+                const route = routedCwd
+                    ? `Worktree routing: call hunch_context first with cwd: ${JSON.stringify(routedCwd)}, and pass the same cwd to hunch_task, hunch_report, and every Hunch capture/write call in this delegated task.`
+                    : null;
+                const activeProvider = provider;
+                const emitRouteOnly = () => { if (route)
+                    emitContext(activeProvider, "SubagentStart", route); };
                 if (/explore|search|investigat/.test(type)) {
                     // Orient from the graph, not grep rounds: the component map IS the shape.
                     const components = s.advisoryRecs("components").filter((c) => c.status === "active");
-                    if (!components.length)
+                    if (!components.length) {
+                        emitRouteOnly();
                         return;
+                    }
                     L.push(`🧠 Hunch — repo shape for a delegated explorer: ${components.length} component(s).`);
                     for (const c of components.slice(0, 12)) {
                         const line = `- ${c.name}${c.paths.length ? ` (${c.paths.slice(0, 2).join(", ")})` : ""}${c.responsibility ? ` — ${clip1(c.responsibility, 90)}` : ""}`;
@@ -4611,8 +4650,10 @@ program
                     const decisions = s.advisoryRecs("decisions")
                         .filter((d) => d.status === "accepted")
                         .sort((a, b) => (a.date < b.date ? 1 : -1));
-                    if (!decisions.length)
+                    if (!decisions.length) {
+                        emitRouteOnly();
                         return;
+                    }
                     L.push(`🧠 Hunch — live decisions for a delegated planner (${decisions.length} in force; plans must not re-propose the rejected).`);
                     for (const d of decisions.slice(0, 6)) {
                         const line = `- ${d.title} (${d.id})${d.alternatives_rejected.length ? ` — rejected: ${clip1(d.alternatives_rejected[0], 80)}` : ""}`;
@@ -4626,8 +4667,10 @@ program
                     const constraints = s.advisoryRecs("constraints")
                         .filter((c) => c.status === "active")
                         .sort((a, b) => sevRank[a.severity] - sevRank[b.severity]);
-                    if (!constraints.length)
+                    if (!constraints.length) {
+                        emitRouteOnly();
                         return;
+                    }
                     L.push(`🧠 Hunch — delegated agent grounding: ${constraints.length} invariant(s) in force in this repo.`);
                     for (const c of constraints.slice(0, 8)) {
                         const line = `- [${c.severity}] ${clip1(c.statement, 140)}${c.scope.length ? ` (scope: ${c.scope.slice(0, 3).join(", ")})` : ""}`;
@@ -4638,6 +4681,8 @@ program
                         L.push(`…and ${constraints.length - 8} more — hunch_check_constraints(scope) for your files.`);
                     L.push("Before editing: hunch_check_constraints(scope) · hunch_why(target). Orient: hunch_context(task).");
                 }
+                if (route)
+                    L.push(route);
                 // No dedup here: the hook event carries the PARENT session id, but each
                 // spawned agent is a fresh empty context — deduping would ground the
                 // first Explore and silently starve every later one.
@@ -4836,6 +4881,7 @@ program
         // from this file. No diff exists yet, so this is context — "don't re-add X" —
         // not a block; the commit-time `hunch check` does the actual gating.
         const retired = store.retiredForFile(target).filter((r) => r.symbols.length || r.deps.length);
+        const recentTasks = taskSupplements(store.tasksFor(target, 3), target);
         const hasContent = ctx.constraints.length ||
             ctx.decisions.length ||
             ctx.bugs.length ||
@@ -4844,6 +4890,7 @@ program
             ctx.landscape?.resources.length ||
             ctx.landscape?.relationships.length ||
             retired.length ||
+            recentTasks.length ||
             docGround;
         if (!hasContent)
             return; // no noise on files Hunch hasn't learned yet
@@ -4861,6 +4908,7 @@ program
                         text: `⚠ Deliberately RETIRED from this file — do not re-introduce without cause: ${retired.map((r) => `${[...r.symbols, ...r.deps].join(", ")} (${r.decision})`).join("; ")}.`,
                     }] : []),
                 ...(docGround ? [{ id: "doc-grounding", kind: "doc-grounding", priority: 100, text: docGround }] : []),
+                ...recentTasks,
             ],
         });
         const text = envelope.text.trim();
@@ -4900,7 +4948,7 @@ program
                 // The first time a lesson reaches this prompt's task, tell the USER in one
                 // line (systemMessage); repeats of the same revision stay silent.
                 recalled = reportPresentationEnabled(root) ? renderRecalledLine(unseenLessons(root, reportTaskId, snapshots)) : null;
-                const occurrence = recordTaskDelivery(root, reportTaskId, envelope, snapshots);
+                const occurrence = recordTaskDelivery(root, reportTaskId, envelope, snapshots, undefined, target);
                 reportNotice = `\n\nHunch task ${reportTaskId} · delivery ${occurrence}. Inspect exact application references with hunch_report(task_id).`;
             }
             catch {

package/dist/cli/invocation.d.ts

@@ -7,6 +7,9 @@ export interface ResolvedInvocation {
     agentHookShell: string;
     /** Structured command/args for .mcp.json (subcommand appended by the writer). */
     mcp: Invocation;
+    /** True only when running from an installed/published copy (global, local,
+     * or npx cache), never from a source checkout. */
+    installed: boolean;
 }
 export declare function dim(s: string): string;
 /** Portable invocation written into committed MCP/provider configuration.
@@ -32,4 +35,9 @@ export declare function synthesisStatusLines(resolution: ProviderResolution, env
  *  separate from synthesisStatusLines (sync, already fully covered) because
  *  this one makes a best-effort network call. */
 export declare function maybeWarnOllamaContext(providerName: string, env: NodeJS.ProcessEnv): Promise<string | null>;
+/** Classify the entry path without faking import.meta.url in tests. */
+export declare function classifyEntry(entry: string): {
+    isDev: boolean;
+    installed: boolean;
+};
 export declare function resolveInvocation(): ResolvedInvocation;

package/dist/cli/invocation.js

@@ -77,27 +77,32 @@ export async function maybeWarnOllamaContext(providerName, env) {
         return null;
     return probeOllamaNumCtx(env.HUNCH_SYNTH_BASE_URL ?? "", env.HUNCH_SYNTH_MODEL ?? "");
 }
+/** Classify the entry path without faking import.meta.url in tests. */
+export function classifyEntry(entry) {
+    const isDev = entry.endsWith(".ts");
+    const installed = !isDev && entry.replace(/\\/g, "/").includes("/node_modules/");
+    return { isDev, installed };
+}
 export function resolveInvocation() {
     const entry = fileURLToPath(import.meta.url).replace(/invocation\.(js|ts)$/, "index.$1");
-    const isDev = entry.endsWith(".ts");
+    const { isDev, installed } = classifyEntry(entry);
     // JSON.stringify yields a double-quoted, backslash-escaped token /bin/sh
     // accepts — so install paths with spaces don't break the hook command.
     const q = (s) => JSON.stringify(s);
-    // Running from an installed copy (global, local, or npx cache — i.e. NOT a
-    // source checkout we're hacking on). The MCP/provider config files we write
-    // are committed and shared across a team via git, so they must NOT embed this
-    // machine's absolute path or OS-specific separators. Reference the exact
-    // published Hunch package instead, which `npx` resolves the same on any OS
-    // and any clone without floating to a newer release. The git hook lives in
-    // per-machine .git/hooks (never committed), so it keeps the PATH-robust
-    // absolute-node invocation below.
-    const installed = !isDev && entry.replace(/\\/g, "/").includes("/node_modules/");
+    // The MCP/provider config files we write are committed and shared across a
+    // team via git, so they must NOT embed this machine's absolute path or
+    // OS-specific separators. Reference the exact published Hunch package
+    // instead, which `npx` resolves the same on any OS and any clone without
+    // floating to a newer release. The git hook lives in per-machine
+    // .git/hooks (never committed), so it keeps the PATH-robust absolute-node
+    // invocation below.
     if (installed) {
         const mcp = publishedMcpInvocation();
         return {
             shell: `${q(process.execPath)} ${q(entry)}`,
             agentHookShell: shellInvocation(mcp),
             mcp,
+            installed,
         };
     }
     if (isDev) {
@@ -106,6 +111,7 @@ export function resolveInvocation() {
             shell: `npx tsx ${q(entry)}`,
             agentHookShell: shellInvocation(mcp),
             mcp,
+            installed,
         };
     }
     // Source-checkout dist run (e.g. `node dist/cli/index.js`, npm link): inherently
@@ -116,6 +122,7 @@ export function resolveInvocation() {
         shell: `${q(process.execPath)} ${q(entry)}`,
         agentHookShell: shellInvocation(mcp),
         mcp,
+        installed,
     };
 }
 //# sourceMappingURL=invocation.js.map

package/dist/cli/taskReport.js

@@ -7,6 +7,7 @@ import { DEFAULT_CHECK_TIMEOUT_MS, MAX_CHECK_TIMEOUT_MS, reportSourceSnapshot, r
 import { renderTaskReport, writeTaskReportHtml } from "../core/taskReportRender.js";
 import { assertReportPath } from "../core/taskReportPaths.js";
 import { publicTaskReport } from "../core/taskReportPublic.js";
+import { mergeDurableTaskSummaries, persistTaskRecord } from "../core/taskRecord.js";
 export function registerTaskReportCommands(program, openStore) {
     const task = program.command("task").description("Record an explicit task lifecycle for Hunch contribution reports");
     task.command("start <title>").option("--id <id>", "retry an exact existing task identity")
@@ -39,14 +40,44 @@ export function registerTaskReportCommands(program, openStore) {
             catch { /* disclosed as unverified */ }
         }
         finishReportTask(root, id, opts.interrupted ? "interrupted" : "completed");
-        console.log(renderTaskReport(readTaskReport(root, id, reportSourceSnapshot(root).hash)));
+        // The finished task becomes graph memory (.hunch/tasks/) through the normal
+        // capture path. A failed write is disclosed, never a reason to lose the card.
+        let graph = "";
+        try {
+            const opened = openStore();
+            try {
+                const saved = persistTaskRecord(opened.root, opened.store, id);
+                graph = saved
+                    ? `\nGraph     ${saved.changed ? "saved" : "already saved"} as ${saved.record.id} (${saved.home}${saved.flushed ? `, ${saved.flushed}` : ""})`
+                    : "\nGraph     nothing to keep (no observation, or task records disabled)";
+            }
+            finally {
+                opened.store.close();
+            }
+        }
+        catch (error) {
+            graph = `\nGraph     not saved: ${error.message}`;
+        }
+        console.log(renderTaskReport(readTaskReport(root, id, reportSourceSnapshot(root).hash)) + graph);
     });
     task.command("list").description("Recent tasks observed in this repository with what Hunch delivered, saved, guarded, and checked")
         .option("--limit <n>", "how many recent tasks (max 30)", "30")
         .option("--json", "machine-readable summaries (consumed by the VS Code Contribution view)")
         .action((opts) => {
         const root = findRoot();
-        const summaries = listTaskSummaries(root, Number(opts.limit) || 30, reportSourceSnapshot(root).hash);
+        const limit = Number(opts.limit) || 30;
+        let summaries = listTaskSummaries(root, limit, reportSourceSnapshot(root).hash);
+        // Graph records (this machine's or a teammate's) join the local ledger view.
+        try {
+            const opened = openStore();
+            try {
+                summaries = mergeDurableTaskSummaries(opened.store, summaries, limit);
+            }
+            finally {
+                opened.store.close();
+            }
+        }
+        catch { /* ledger-only view when the store is unavailable */ }
         if (opts.json) {
             console.log(JSON.stringify(summaries, null, 2));
             return;
@@ -56,7 +87,7 @@ export function registerTaskReportCommands(program, openStore) {
             return;
         }
         for (const s of summaries)
-            console.log(`${s.task.started_at.slice(0, 16).replace("T", " ")}  ${s.task.task_id}  ${s.task.state.padEnd(11)} ${renderTaskStatusLine(s) || "nothing observed"}`);
+            console.log(`${s.task.started_at.slice(0, 16).replace("T", " ")}  ${s.task.task_id}  ${s.task.state.padEnd(11)} ${renderTaskStatusLine(s) || "nothing observed"}${s.durable ? `  [graph: ${s.durable.home}]` : ""}`);
     });
     task.command("stats").description("Adherence over a window: how many prompts Hunch reached (delivery), checked, saved, or guarded — from the ledger, never from agent claims")
         .option("--days <days>", "window in days", "7")
@@ -188,7 +219,24 @@ export function registerTaskReportCommands(program, openStore) {
             console.log(JSON.stringify(publicTaskReport(root, id), null, 2));
             return;
         }
-        const report = readTaskReport(root, id, reportSourceSnapshot(root).hash);
+        let report;
+        try {
+            report = readTaskReport(root, id, reportSourceSnapshot(root).hash);
+        }
+        catch (error) {
+            // Not in this machine's ledger: the graph record (if any) is what remains.
+            const opened = openStore();
+            try {
+                const record = opened.store.getRec("tasks", id);
+                if (!record)
+                    throw error;
+                console.log(opts.json ? JSON.stringify(record, null, 2) : `Task ${record.id} · ${record.state} · ${record.title}\nGraph record only (no local observation ledger for it here): ${record.lessons.length} lesson(s), ${record.applied.length} applied, ${record.saved.length} saved, ${record.checks.length} check(s), ${record.refusals} denied. Files: ${record.files.join(", ") || "none recorded"}.`);
+                return;
+            }
+            finally {
+                opened.store.close();
+            }
+        }
         console.log(opts.json ? JSON.stringify(report, null, 2) : renderTaskReport(report));
     });
 }

package/dist/cli/update.js

@@ -2,7 +2,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { findRoot } from "../core/paths.js";
-const PACKAGE = "@davesheffer/hunch";
+import { HUNCH_PACKAGE_NAME } from "../core/version.js";
 /** Arguments come only from fixed commands and a validated registry version.
  * Windows needs the shell to resolve npm.cmd; cwd is never interpolated. */
 export function runNpm(root, args, capture = false) {
@@ -26,24 +26,24 @@ export function updateHunch(root, opts = {}, run = (args, capture) => runNpm(roo
     const manifest = existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : {};
     if (!manifest || typeof manifest !== "object" || Array.isArray(manifest))
         throw new Error("package.json must contain an object");
-    if (manifest.name === PACKAGE)
+    if (manifest.name === HUNCH_PACKAGE_NAME)
         throw new Error("Run hunch update in a consumer repository, not Hunch's own source checkout.");
     const sections = ["dependencies", "devDependencies", "optionalDependencies"];
     const declared = sections.filter(section => {
         const deps = manifest[section];
         if (deps !== undefined && (!deps || typeof deps !== "object" || Array.isArray(deps)))
             throw new Error(`invalid ${section} in package.json`);
-        return deps && Object.hasOwn(deps, PACKAGE);
+        return deps && Object.hasOwn(deps, HUNCH_PACKAGE_NAME);
     });
     if (declared.length > 1)
         throw new Error("Hunch is declared in multiple dependency sections; resolve the duplicate before updating.");
     if (declared.length && (manifest.workspaces || (manifest.packageManager && !/^npm@/.test(manifest.packageManager)) || ["pnpm-lock.yaml", "yarn.lock", "bun.lock", "bun.lockb"].some(name => existsSync(join(root, name))))) {
         throw new Error("Automatic dependency updates currently support standalone npm projects. Update Hunch to an exact version with your package manager, then run hunch integrations repair-pins.");
     }
-    const version = JSON.parse(run(["view", `${PACKAGE}@latest`, "version", "--json"], true));
+    const version = JSON.parse(run(["view", `${HUNCH_PACKAGE_NAME}@latest`, "version", "--json"], true));
     if (typeof version !== "string" || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(version))
         throw new Error("npm returned an invalid Hunch version");
-    const spec = `${PACKAGE}@${version}`;
+    const spec = `${HUNCH_PACKAGE_NAME}@${version}`;
     const commands = [];
     if (declared.length) {
         const flag = { dependencies: "--save-prod", devDependencies: "--save-dev", optionalDependencies: "--save-optional" }[declared[0]];

package/dist/client/state.d.ts

@@ -178,7 +178,7 @@ export declare function createStateClient(opts: StateClientOptions): {
         schema: "nuryel.state.write/1";
         record_id: string;
         record_hash: string;
-        durability: "committed" | "pushed" | "local";
+        durability: "local" | "committed" | "pushed";
         outcome: "updated" | "superseded" | "created" | "replayed";
         conflict: {
             incumbent_id: string;
@@ -190,7 +190,7 @@ export declare function createStateClient(opts: StateClientOptions): {
         schema: "nuryel.state.write/1";
         record_id: string;
         record_hash: string;
-        durability: "committed" | "pushed" | "local";
+        durability: "local" | "committed" | "pushed";
         outcome: "updated" | "superseded" | "created" | "replayed";
         conflict: {
             incumbent_id: string;
@@ -207,7 +207,7 @@ export declare function createStateClient(opts: StateClientOptions): {
                 schema: "nuryel.state.write/1";
                 record_id: string;
                 record_hash: string;
-                durability: "committed" | "pushed" | "local";
+                durability: "local" | "committed" | "pushed";
                 outcome: "updated" | "superseded" | "created" | "replayed";
                 conflict: {
                     incumbent_id: string;
@@ -228,7 +228,7 @@ export declare function createStateClient(opts: StateClientOptions): {
                 schema: "nuryel.state.write/1";
                 record_id: string;
                 record_hash: string;
-                durability: "committed" | "pushed" | "local";
+                durability: "local" | "committed" | "pushed";
                 outcome: "updated" | "superseded" | "created" | "replayed";
                 conflict: {
                     incumbent_id: string;

package/dist/constitution/schema.d.ts

@@ -370,13 +370,13 @@ export declare const PolicyStateSchema: z.ZodEnum<{
     proposed: "proposed";
     rejected: "rejected";
     superseded: "superseded";
+    repaired: "repaired";
+    active_advisory: "active_advisory";
+    active_blocking: "active_blocking";
     compiled: "compiled";
+    validating: "validating";
     uncompilable: "uncompilable";
     drafted: "drafted";
-    validating: "validating";
-    active_advisory: "active_advisory";
-    active_blocking: "active_blocking";
-    repaired: "repaired";
 }>;
 export type PolicyState = z.infer<typeof PolicyStateSchema>;
 export declare const PolicySelectorSchema: z.ZodObject<{
@@ -470,8 +470,8 @@ export declare const PolicyAuditEventSchema: z.ZodObject<{
         retired: "retired";
         withdrawn: "withdrawn";
         rejected: "rejected";
-        compiled: "compiled";
         repaired: "repaired";
+        compiled: "compiled";
         enriched: "enriched";
         linked_exception: "linked_exception";
         proved: "proved";
@@ -518,13 +518,13 @@ export declare const PolicySpecSchema: z.ZodObject<{
         proposed: "proposed";
         rejected: "rejected";
         superseded: "superseded";
+        repaired: "repaired";
+        active_advisory: "active_advisory";
+        active_blocking: "active_blocking";
         compiled: "compiled";
+        validating: "validating";
         uncompilable: "uncompilable";
         drafted: "drafted";
-        validating: "validating";
-        active_advisory: "active_advisory";
-        active_blocking: "active_blocking";
-        repaired: "repaired";
     }>;
     statement: z.ZodString;
     rationale: z.ZodDefault<z.ZodString>;
@@ -610,10 +610,10 @@ export declare const PolicySpecSchema: z.ZodObject<{
     }>>;
     surfaces: z.ZodDefault<z.ZodArray<z.ZodEnum<{
         ci: "ci";
-        pre_edit: "pre_edit";
-        pre_commit: "pre_commit";
         mcp: "mcp";
         cli: "cli";
+        pre_edit: "pre_edit";
+        pre_commit: "pre_commit";
     }>>>;
     authority: z.ZodDefault<z.ZodNullable<z.ZodObject<{
         kind: z.ZodLiteral<"human">;
@@ -663,8 +663,8 @@ export declare const PolicySpecSchema: z.ZodObject<{
             retired: "retired";
             withdrawn: "withdrawn";
             rejected: "rejected";
-            compiled: "compiled";
             repaired: "repaired";
+            compiled: "compiled";
             enriched: "enriched";
             linked_exception: "linked_exception";
             proved: "proved";

package/dist/core/spawnCommand.d.ts

@@ -0,0 +1,14 @@
+export interface ResolvedSpawn {
+    file: string;
+    args: string[];
+    /** Set when a batch launcher runs through cmd.exe and the line is pre-quoted. */
+    windowsVerbatimArguments?: boolean;
+    how: "direct" | "npm-cli" | "pathext" | "cmd-shim";
+}
+export interface SpawnResolveOptions {
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    execPath?: string;
+    exists?: (path: string) => boolean;
+}
+export declare function resolveSpawnCommand(command: readonly string[], options?: SpawnResolveOptions): ResolvedSpawn;

package/dist/core/spawnCommand.js

@@ -0,0 +1,61 @@
+/** Resolve a user-supplied argv into something `spawn` can run without a shell.
+ *
+ * On POSIX the argv is already right. On Windows, `spawn("npx", ...)` with
+ * `shell: false` fails: the launcher is `npx.cmd`, and Node refuses to run
+ * `.cmd`/`.bat` files directly. The verification runner used to swallow that
+ * as `exit_code: null`, so every contribution card on Windows said "no
+ * independent command result". This keeps `shell: false` for real
+ * executables and only routes batch launchers through `cmd.exe`, with the
+ * npm/npx launchers run as plain Node scripts (no shell at all). */
+import { existsSync } from "node:fs";
+import { posix, win32 } from "node:path";
+/** cmd.exe quoting for one argument: wrap when it has whitespace or shell
+ * metacharacters; double embedded quotes. Good for test/build commands; a
+ * deliberately hostile argument still cannot escape because the whole line is
+ * passed as one `/s /c "..."` token. */
+function quoteForCmd(arg) {
+    if (arg === "")
+        return '""';
+    if (!/[\s"&|<>^()%!]/.test(arg))
+        return arg;
+    return `"${arg.replace(/"/g, '""')}"`;
+}
+export function resolveSpawnCommand(command, options = {}) {
+    const platform = options.platform ?? process.platform;
+    const [cmd = "", ...args] = command;
+    if (platform !== "win32")
+        return { file: cmd, args, how: "direct" };
+    const env = options.env ?? process.env;
+    const exists = options.exists ?? existsSync;
+    const execPath = options.execPath ?? process.execPath;
+    // Resolve Windows paths with Windows semantics even when the resolution is
+    // exercised (tested) on another platform; the host's default `path` is POSIX there.
+    const { join, dirname } = platform === "win32" ? win32 : posix;
+    // npm / npx: run the CLI script with this same Node. No shim, no shell.
+    if (/^(npm|npx)$/i.test(cmd)) {
+        const script = join(dirname(execPath), "node_modules", "npm", "bin", `${cmd.toLowerCase()}-cli.js`);
+        if (exists(script))
+            return { file: execPath, args: [script, ...args], how: "npm-cli" };
+    }
+    // A path or an explicit executable extension: spawn as given.
+    if (/[\\/]/.test(cmd) || /\.(exe|com)$/i.test(cmd))
+        return { file: cmd, args, how: "direct" };
+    const pathExt = (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").map((e) => e.trim()).filter(Boolean);
+    const dirs = (env.PATH ?? env.Path ?? "").split(";").map((d) => d.trim()).filter(Boolean);
+    for (const dir of dirs) {
+        for (const ext of ["", ...pathExt]) {
+            const candidate = join(dir, cmd + ext);
+            if (!exists(candidate))
+                continue;
+            if (/\.(cmd|bat)$/i.test(candidate)) {
+                const line = [candidate, ...args].map(quoteForCmd).join(" ");
+                return { file: env.ComSpec ?? "cmd.exe", args: ["/d", "/s", "/c", `"${line}"`], windowsVerbatimArguments: true, how: "cmd-shim" };
+            }
+            if (ext === "" && !/\.(exe|com)$/i.test(candidate))
+                continue; // an extensionless file is not runnable on Windows
+            return { file: candidate, args, how: "pathext" };
+        }
+    }
+    return { file: cmd, args, how: "direct" };
+}
+//# sourceMappingURL=spawnCommand.js.map

package/dist/core/stateContract.d.ts

@@ -780,9 +780,9 @@ export declare const WriteResultSchema: z.ZodObject<{
     record_id: z.ZodString;
     record_hash: z.ZodString;
     durability: z.ZodEnum<{
+        local: "local";
         committed: "committed";
         pushed: "pushed";
-        local: "local";
     }>;
     outcome: z.ZodEnum<{
         updated: "updated";
@@ -807,9 +807,9 @@ export declare const CaptureBatchResultSchema: z.ZodObject<{
             record_id: z.ZodString;
             record_hash: z.ZodString;
             durability: z.ZodEnum<{
+                local: "local";
                 committed: "committed";
                 pushed: "pushed";
-                local: "local";
             }>;
             outcome: z.ZodEnum<{
                 updated: "updated";
@@ -837,9 +837,9 @@ export declare const CaptureBatchResultSchema: z.ZodObject<{
             record_id: z.ZodString;
             record_hash: z.ZodString;
             durability: z.ZodEnum<{
+                local: "local";
                 committed: "committed";
                 pushed: "pushed";
-                local: "local";
             }>;
             outcome: z.ZodEnum<{
                 updated: "updated";

package/dist/core/taskDelivery.d.ts

@@ -0,0 +1,15 @@
+/** Recent finished tasks as delivered context.
+ *
+ * Task records (`.hunch/tasks/`) say what earlier agent work did around a file:
+ * which lessons it received, what it applied, saved and checked, and whether a
+ * rule was violated. Delivering the newest few next to the invariants lets the
+ * next agent build on verified work instead of rediscovering it. Supplements
+ * share the brief's budget and are advisory: a task line is history, never a
+ * rule, and never an instruction to repeat or skip anything. */
+import type { DeliverySupplement } from "./delivery.js";
+import type { TaskRecord } from "./types.js";
+export declare const TASK_SUPPLEMENT_LIMIT = 3;
+/** One bounded line for a task: identity, when, what reached it, what it did. */
+export declare function describeTaskRecord(t: TaskRecord): string;
+/** Newest first, bounded. Empty input yields no supplement at all (no header noise). */
+export declare function taskSupplements(tasks: readonly TaskRecord[], target: string, limit?: number): DeliverySupplement[];