@davesheffer/hunch 1.32.8 → 1.35.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?
@@ -41,7 +44,9 @@ Hunch works with Claude Code, Codex, Cursor, VS Code/Copilot, Windsurf, Antigrav
 | Check the rules your team chose | Evaluates supported constraints and code relationships without a model in the blocking path. |
 | See what happened during a task | Separates delivered memory, the agent's reported use, rule results, and observed command results in a contribution report. |
 | Share project memory with teammates | Keeps repository memory in Git, with an optional dedicated private memory repository. |
-| Share work state across agents | Serves authorized records for decisions, actions, commitments, entities, and relationships through HTTP, MCP, and a typed client. |
+| Share work state across agents | Serves authorized records through HTTP, MCP, the state CLI, and typed TypeScript and Python clients. |
+| Inspect what the agents know | A read-only browser view shows current records, commitments, completed work and writer-supplied citations. |
+| Keep access and conventions explicit | Optional per-record audiences, key-bound credentials and sourced conventions use the same state contract. |
 
 For example, a team fixes a logout bug by keeping sessions on the server. Months later, an agent proposes removing that code. Hunch can surface the original reason and rejected alternative before the edit. A supported, trusted rule can flag the conflict; strict mode can block it. Recording the lesson and configuring the integration are what make this possible.
 
@@ -76,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.
@@ -124,13 +134,17 @@ This shares a project's engineering memory. The state server below adds authenti
 
 A coding agent needs to know why a module exists. An operations agent may need to know whether a customer action was completed or who owes the next follow-up. Both need a maintained record they can check.
 
-Hunch already ships `hunch serve`: a self-hosted HTTP service for organization, team, user, and repository records. A configured identity determines which scopes an agent may access. The same state contract is available through MCP and the `@davesheffer/hunch/state` client.
+Hunch ships `hunch serve`: a self-hosted HTTP service for organization, team, user, and repository records. A configured identity determines which scopes an agent may access. Optional record audiences further restrict access; optional key-bound credentials require proof from the configured private key on each request.
+
+Open `/operator` on your server to inspect current records, completed work and commitments in a read-only browser view. Writer-supplied citations can point to an exact summary field or text passage and its recorded sources. They show traceability; they do not prove that a source supports a claim.
+
+Agents can use the same contract through MCP, `hunch state read|write|records|subscribe`, the `@davesheffer/hunch/state` TypeScript client, or the [Python client](docs/python-state-client.md). The Python package is built and tested from this repository; it is not yet published to PyPI. [Scoped conventions](docs/scoped-conventions.md) let a person record sourced user, team or organization preferences. Those preferences remain advisory and do not silently become blocking rules.
 
 Records can describe decisions, action outcomes, commitments, entities, relationships, and summaries that name their dependencies. Actions retain their status, including unknown or unverified outcomes. Repeated writes have stable identities, conflicting current decisions are refused, and confirmed human records receive protections against agent overwrites. These are defined checks on structured records; Hunch cannot establish every fact in the outside world on its own.
 
 This is what **deterministic state** means here: explicit rules govern the stored record, rather than having each agent reconstruct it from scratch. Git holds the durable data; SQLite is a rebuildable index. The server binds to loopback and requires deployment and agent integration by its operator. Hunch does not provide a managed CRM or email connector service.
 
-[Set up and understand the state server](docs/deterministic-state.md) · [State contract and client reference](docs/nuryel-state-contract.md)
+[Set up and understand the state server](docs/deterministic-state.md) · [State contract and client reference](docs/nuryel-state-contract.md) · [Upgrade to 1.33](docs/upgrade-1.33.md)
 
 ### The vision, and what is still being tested
 
@@ -172,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

@@ -26,6 +26,7 @@ import { looksLikeCorrection, CORRECTION_NUDGE } from "../core/correction.js";
 import { HUNCH_VERSION } from "../core/version.js";
 import { registerIntegrationCommands } from "./integrations.js";
 import { registerTaskReportCommands } from "./taskReport.js";
+import { registerStateCommands } from "./state.js";
 import { registerServeCommands } from "./serve.js";
 import { registerUpdateCommand } from "./update.js";
 import { registerReviewMemoryCommands } from "./reviewMemory.js";
@@ -84,7 +85,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";
@@ -130,6 +131,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)")
@@ -164,6 +166,7 @@ registerIntegrationCommands(program, () => {
 });
 registerTaskReportCommands(program, () => { const { store, root } = storeFor(); return { store, root }; });
 registerServeCommands(program);
+registerStateCommands(program);
 registerUpdateCommand(program);
 registerReviewMemoryCommands(program, (records, repository, privateOnly) => {
     const { store, root } = storeFor();
@@ -198,6 +201,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
@@ -4191,7 +4217,7 @@ program
         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 {
@@ -4580,6 +4606,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) => {
@@ -4589,11 +4621,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)}` : ""}`;
@@ -4609,8 +4649,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)}` : ""}`;
@@ -4624,8 +4666,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(", ")})` : ""}`;
@@ -4636,6 +4680,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.
@@ -4898,7 +4944,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/serve.js

@@ -1,6 +1,8 @@
+import { readFileSync, statSync } from 'node:fs';
+import { proofPublicKey } from '../core/stateProof.js';
 import { resolve } from "node:path";
 import { createServeApp } from "../serve/app.js";
-import { initServeConfig, partitionFor, readServeConfig } from "../serve/config.js";
+import { initServeConfig, partitionFor, readServeConfig, writeServeConfig } from "../serve/config.js";
 import { compactLedger } from "../store/changeLedger.js";
 import { HunchStore } from "../store/hunchStore.js";
 import { hunchPaths } from "../core/paths.js";
@@ -32,11 +34,23 @@ export function registerServeCommands(program) {
         // reverse proxy that terminates TLS and auth of its own. Folded-in decision from Hunch Memory.
         app.listen(port, "127.0.0.1", () => {
             console.log(`hunch ${HUNCH_VERSION} serving nuryel.state/1 on http://127.0.0.1:${port} — ${config.partitions.map((p) => scopePath(p.scope)).join(", ")} (${config.principals.length} principal(s))`);
+            console.log(`Shared state view: http://127.0.0.1:${port}/operator`);
         });
         const stop = () => { app.close(() => { app.closeStores(); process.exit(0); }); };
         process.on("SIGINT", stop);
         process.on("SIGTERM", stop);
     });
+    serve.command("revoke")
+        .description("Revoke a principal credential; current servers reload the config before each request")
+        .requiredOption("--principal <id>", "principal whose credential to revoke")
+        .action((opts) => {
+        const { file, ...config } = readServeConfig(resolve(serve.opts().config ?? DEFAULT_CONFIG));
+        if (!config.principals.some(p => p.id === opts.principal))
+            throw new Error('principal is not configured');
+        config.principals = config.principals.filter(p => p.id !== opts.principal);
+        writeServeConfig(file, config);
+        console.log(JSON.stringify({ revoked: opts.principal }));
+    });
     serve.command("compact")
         .description("Compact a served partition's change ledger: keep the newest N events, move the floor up; subscribers below the floor resynchronize")
         .requiredOption("--partition <kind:id>", "the partition whose ledger to compact")
@@ -105,6 +119,8 @@ export function registerServeCommands(program) {
         .requiredOption("--root <dir>", "directory whose .hunch/ holds the partition (created if missing)")
         .option("--config <file>", `serve config to create or extend; default ${DEFAULT_CONFIG}`)
         .option("--principal <id>", "principal to add or rotate, granted this partition")
+        .option("--proof-key-file <file>", "bind this token to an Ed25519 public PEM or JWK key")
+        .option("--public-origin <origin>", "external HTTPS origin of the reverse proxy; required for key-bound tokens")
         .option("--kind <kind>", "principal kind: human | agent | service", "agent")
         .option("--grant <kind:id...>", "additional partitions to grant the principal (must be served by this config)")
         .option("--port <n>", "port to record in a new config")
@@ -120,10 +136,20 @@ export function registerServeCommands(program) {
         const port = parent.port ?? opts.port;
         const scope = parseScopeArg(opts.partition);
         const grants = [scope, ...(opts.grant ?? []).map(parseScopeArg)];
+        let proofKey;
+        if (opts.proofKeyFile) {
+            if (!opts.principal)
+                throw new Error('--proof-key-file requires --principal');
+            const stat = statSync(opts.proofKeyFile);
+            if (!stat.isFile() || stat.size > 8192)
+                throw new Error('public proof key must be a regular file of at most 8 KiB');
+            proofKey = proofPublicKey(readFileSync(opts.proofKeyFile, 'utf8'));
+        }
         const result = initServeConfig({
             file: configFile, scope, root: resolve(opts.root),
-            ...(opts.principal ? { principal: { id: opts.principal, kind: opts.kind, grants } } : {}),
+            ...(opts.principal ? { principal: { id: opts.principal, kind: opts.kind, grants, proofKey } } : {}),
             ...(port ? { port: Number(port) } : {}),
+            ...(opts.publicOrigin ? { publicOrigin: opts.publicOrigin } : {}),
         });
         if (opts.json) {
             console.log(JSON.stringify({ config: configFile, partition: result.partition, token: result.token }));

package/dist/cli/state.d.ts

@@ -0,0 +1,3 @@
+/** JSON CLI over the existing HTTP client. The server owns authorization and state rules. */
+import type { Command } from 'commander';
+export declare function registerStateCommands(program: Command): void;

package/dist/cli/state.js

@@ -0,0 +1,150 @@
+import { createStateProofSigner } from '../client/stateProof.js';
+import { readFileSync, statSync } from 'node:fs';
+import { z } from 'zod';
+import { createStateClient, StateClientError } from '../client/state.js';
+import { ReadRequestSchema, WriteRequestSchema, SubscribeRequestSchema, RecordsRequestSchema, ScopeSchema, STATE_FIELD_PROVENANCE_VERSION, STATE_RECORD_VISIBILITY_VERSION } from '../core/stateContract.js';
+const MAX_INPUT_BYTES = 1024 * 1024;
+function scopeFrom(value) {
+    const match = /^([a-z]+):(.+)$/.exec(value ?? '');
+    if (!match)
+        throw new Error('pass --scope kind:id, or supply scope in --input JSON');
+    return ScopeSchema.parse({ kind: match[1], id: match[2] });
+}
+async function inputObject(file) {
+    let text;
+    if (file !== '-') {
+        const stat = statSync(file);
+        if (!stat.isFile() || stat.size > MAX_INPUT_BYTES)
+            throw new Error('input must be a regular JSON file of at most 1 MiB');
+        text = readFileSync(file, 'utf8');
+    }
+    else {
+        if (process.stdin.isTTY)
+            throw new Error('pipe a JSON request or pass --input <file>');
+        const chunks = [];
+        let length = 0;
+        for await (const chunk of process.stdin) {
+            const bytes = Buffer.from(chunk);
+            length += bytes.length;
+            if (length > MAX_INPUT_BYTES)
+                throw new Error('input exceeds 1 MiB');
+            chunks.push(bytes);
+        }
+        text = Buffer.concat(chunks).toString('utf8');
+    }
+    if (Buffer.byteLength(text) > MAX_INPUT_BYTES)
+        throw new Error('input exceeds 1 MiB');
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        throw new Error('input must be valid JSON');
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('input must be a JSON request object');
+    return value;
+}
+function connection(options) {
+    const timeoutMs = Number(options.timeout);
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 300_000)
+        throw new Error('--timeout must be 1..300000 milliseconds');
+    const url = new URL(options.url);
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash)
+        throw new Error('--url must be an HTTP(S) base URL without credentials, query or fragment');
+    let token = process.env.HUNCH_STATE_TOKEN?.trim();
+    if (options.tokenFile) {
+        const stat = statSync(options.tokenFile);
+        if (!stat.isFile() || stat.size > 8192)
+            throw new Error('token file must be a regular file of at most 8 KiB');
+        token = readFileSync(options.tokenFile, 'utf8').trim();
+    }
+    if (!token)
+        throw new Error('set HUNCH_STATE_TOKEN or pass --token-file; tokens are not accepted as command arguments');
+    let proof;
+    if (options.proofKeyFile) {
+        const stat = statSync(options.proofKeyFile);
+        if (!stat.isFile() || stat.size > 8192)
+            throw new Error('proof key must be a regular private-key file of at most 8 KiB');
+        proof = createStateProofSigner(readFileSync(options.proofKeyFile, 'utf8'));
+    }
+    return createStateClient({ baseUrl: options.url, token, timeoutMs, proof });
+}
+export function registerStateCommands(program) {
+    const state = program.command('state').description('Read and write a served workspace using the state contract; JSON output')
+        .option('--url <url>', 'server base URL (or HUNCH_STATE_URL)', process.env.HUNCH_STATE_URL || 'http://127.0.0.1:7474')
+        .option('--token-file <file>', 'read a bearer token from a file; otherwise use HUNCH_STATE_TOKEN')
+        .option('--proof-key-file <file>', 'Ed25519 private PEM or JWK file for a key-bound token')
+        .option('--timeout <ms>', 'timeout for each HTTP request', '15000')
+        .option('--pretty', 'indent JSON output');
+    const run = (work) => async () => {
+        try {
+            const options = state.opts(), result = await work(connection(options));
+            process.stdout.write(JSON.stringify(result, null, options.pretty ? 2 : undefined) + '\n');
+        }
+        catch (error) {
+            const problem = error instanceof StateClientError ? error.problem : {
+                type: 'about:blank', title: error instanceof z.ZodError ? 'malformed' : 'client-error', status: 0,
+                detail: error instanceof z.ZodError ? error.issues.map(issue => `${issue.path.join('.')}: ${issue.message}`).join('; ') : error instanceof Error ? error.message : 'state request failed',
+            };
+            process.stderr.write(JSON.stringify(problem) + '\n');
+            process.exitCode = 1;
+        }
+    };
+    state.command('capabilities').description('Show the authenticated principal and supported contract capabilities')
+        .option('--scope <kind:id>', 'partition to negotiate; defaults to the token’s first grant')
+        .action((options) => run(client => client.capabilities(options.scope ? scopeFrom(options.scope) : undefined))());
+    for (const verb of ['read', 'write', 'records', 'subscribe']) {
+        const command = state.command(verb).description(verb === 'subscribe' ? 'Poll changes once; use head_seq as the next after_seq and honor resync' : `${verb} using the authenticated state contract`)
+            .option('--input <file>', 'complete request JSON; - reads stdin (default for write)');
+        if (verb !== 'write')
+            command.option('--scope <kind:id>', 'partition when using shortcut options');
+        if (verb === 'read')
+            command.option('--subject <subject>', 'exact subject or record key').option('--task <text>', 'task phrase for memory delivery');
+        if (verb === 'records')
+            command.option('--ids <id...>', 'exact record IDs');
+        if (verb === 'subscribe')
+            command.option('--after <seq>', 'last observed sequence; defaults to zero');
+        command.action((options) => run(async (client) => {
+            const shortcut = options.scope || options.subject || options.task || options.ids || options.after;
+            if (options.input && shortcut)
+                throw new Error('use either --input JSON or shortcut options, not both');
+            const raw = options.input || verb === 'write' ? await inputObject(options.input ?? '-') : {
+                scope: scopeFrom(options.scope),
+                ...(options.subject !== undefined ? { subject: options.subject } : {}),
+                ...(options.task !== undefined ? { task: options.task } : {}),
+                ...(verb === 'records' ? { ids: options.ids } : {}),
+                ...(verb === 'subscribe' ? { after_seq: Number(options.after ?? 0) } : {}),
+            };
+            const schemas = {
+                read: ReadRequestSchema.omit({ schema: true, principal: true }),
+                write: WriteRequestSchema.omit({ schema: true, principal: true }),
+                records: RecordsRequestSchema.omit({ schema: true, principal: true }),
+                subscribe: SubscribeRequestSchema.omit({ schema: true, principal: true }),
+            };
+            const request = schemas[verb].parse(raw);
+            const caps = await client.capabilities(request.scope);
+            const required = [`nuryel.state.${verb}/1`];
+            if ('record' in request) {
+                if (request.record.field_provenance !== undefined)
+                    required.push(STATE_FIELD_PROVENANCE_VERSION);
+                if (request.record.visibility !== undefined)
+                    required.push(STATE_RECORD_VISIBILITY_VERSION);
+                if (typeof request.record.schema === 'string')
+                    required.push(request.record.schema);
+            }
+            const missing = required.filter(capability => !caps.capabilities.includes(capability));
+            if (missing.length)
+                throw new StateClientError(400, 'unsupported', { type: 'about:blank', title: 'unsupported', status: 400, detail: 'server lacks required capabilities: ' + missing.join(', ') });
+            // The chosen request schema matches the verb; state semantics remain server-owned.
+            if (verb === 'read')
+                return client.read(request);
+            if (verb === 'write')
+                return client.write(request);
+            if (verb === 'records')
+                return client.records(request);
+            return client.subscribe(request);
+        })());
+    }
+}
+//# sourceMappingURL=state.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));
     });
 }