@davesheffer/hunch 1.26.0 → 1.26.2

package/dist/cli/index.js

@@ -20,7 +20,7 @@ import { join, relative, dirname, basename, resolve, isAbsolute } from "node:pat
 import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
-import { hunchPaths, hunchPathsForDir, findRoot, toPosixTarget } from "../core/paths.js";
+import { hunchPaths, hunchPathsForDir, findRoot, toPosixTarget, isDir } from "../core/paths.js";
 import { writeFileAtomic } from "../core/io.js";
 import { looksLikeCorrection, CORRECTION_NUDGE } from "../core/correction.js";
 import { HUNCH_VERSION } from "../core/version.js";
@@ -5160,8 +5160,16 @@ function printAutoReviewPlan(plan) {
 program
     .command("mcp")
     .description("Start the MCP server over stdio (Claude Code connects here).")
-    .action(async () => {
+    .option("--root <dir>", "serve exactly this store or served partition and ignore the client's workspace roots and cwd hints")
+    .action(async (opts) => {
     const { startServer } = await import("../mcp/server.js");
+    if (opts.root) {
+        const pinned = resolve(opts.root);
+        if (!isDir(join(pinned, ".hunch")))
+            throw new Error(`--root ${pinned} has no .hunch/ store`);
+        await startServer(pinned, { pinned: true });
+        return;
+    }
     await startServer(process.cwd());
 });
 // ---- migrate (schema versioning) ------------------------------------------

package/dist/cli/serve.js

@@ -11,12 +11,13 @@ function parseScopeArg(value) {
     return parsed.data;
 }
 export function registerServeCommands(program) {
+    const DEFAULT_CONFIG = "hunch-serve.json";
     const serve = program.command("serve")
         .description("Serve nuryel.state/1 over HTTP for organization / team / user / repository partitions (binds 127.0.0.1; put it behind SSH or a reverse proxy)")
-        .option("--config <file>", "serve config (nuryel.serve-config/1)", "hunch-serve.json")
+        .option("--config <file>", `serve config (nuryel.serve-config/1); default ${DEFAULT_CONFIG}`)
         .option("--port <n>", "override the configured port")
         .action((opts) => {
-        const config = readServeConfig(resolve(opts.config));
+        const config = readServeConfig(resolve(opts.config ?? DEFAULT_CONFIG));
         const port = opts.port ? Number(opts.port) : config.port;
         if (!Number.isInteger(port) || port < 1 || port > 65535)
             throw new Error(`invalid port ${opts.port}`);
@@ -34,7 +35,7 @@ export function registerServeCommands(program) {
         .description("Declare a partition directory and mint a principal token (printed once; only its hash is stored)")
         .requiredOption("--partition <kind:id>", "the scope this directory IS, e.g. user:david or organization:ylm")
         .requiredOption("--root <dir>", "directory whose .hunch/ holds the partition (created if missing)")
-        .option("--config <file>", "serve config to create or extend", "hunch-serve.json")
+        .option("--config <file>", `serve config to create or extend; default ${DEFAULT_CONFIG}`)
         .option("--principal <id>", "principal to add or rotate, granted this partition")
         .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)")
@@ -43,22 +44,28 @@ export function registerServeCommands(program) {
         .action((opts) => {
         if (!["human", "agent", "service"].includes(opts.kind))
             throw new Error("--kind must be human, agent or service");
+        // `serve` and `serve init` both take --config; Commander hands an option written after
+        // `init` to whichever command claims it first, and that was the parent — so 1.26.0's
+        // `serve init --config X` silently wrote the default file into the cwd. Read both.
+        const parent = serve.opts();
+        const configFile = resolve(parent.config ?? opts.config ?? DEFAULT_CONFIG);
+        const port = parent.port ?? opts.port;
         const scope = parseScopeArg(opts.partition);
         const grants = [scope, ...(opts.grant ?? []).map(parseScopeArg)];
         const result = initServeConfig({
-            file: resolve(opts.config), scope, root: resolve(opts.root),
+            file: configFile, scope, root: resolve(opts.root),
             ...(opts.principal ? { principal: { id: opts.principal, kind: opts.kind, grants } } : {}),
-            ...(opts.port ? { port: Number(opts.port) } : {}),
+            ...(port ? { port: Number(port) } : {}),
         });
         if (opts.json) {
-            console.log(JSON.stringify({ config: resolve(opts.config), partition: result.partition, token: result.token }));
+            console.log(JSON.stringify({ config: configFile, partition: result.partition, token: result.token }));
             return;
         }
         console.log(`partition ${scopePath(scope)} → ${result.partition.root}`);
-        console.log(`config: ${resolve(opts.config)} (${result.config.partitions.length} partition(s), ${result.config.principals.length} principal(s))`);
+        console.log(`config: ${configFile} (${result.config.partitions.length} partition(s), ${result.config.principals.length} principal(s))`);
         if (result.token)
             console.log(`token for ${opts.principal} (shown once — only its sha256 is stored): ${result.token}`);
-        console.log(`start: hunch serve --config ${opts.config}`);
+        console.log(`start: hunch serve --config ${configFile}`);
     });
 }
 //# sourceMappingURL=serve.js.map

package/dist/core/stateContract.js

@@ -88,6 +88,9 @@ export const ReadResponseSchema = z.object({
     state_of_record: StateOfRecordSchema.nullable(),
     /** Scopes the principal asked about but is not granted — named, never silently dropped. */
     denied_scopes: z.array(ScopeSchema).max(64).default([]),
+    /** The records behind every ref in `state_of_record`, by id, so a consumer can answer from
+     *  the drawer without a second lookup. Additive; absent when there is no subject. */
+    records: z.record(z.string(), z.record(z.string(), z.unknown())).optional(),
 }).strict();
 export const WriteRequestSchema = z.object({
     schema: z.literal(STATE_WRITE_VERSION),

package/dist/extractors/git.js

@@ -818,7 +818,11 @@ function stagedMemoryPaths(hunchDir, env, allowMemoryDeletions = false) {
 function isDerivedStoreArtifact(relativeName) {
     return /^[^/]+\.sqlite[^/]*$/i.test(relativeName)
         || relativeName.split("/").some((segment) => segment.includes(".tmp"))
-        || relativeName === "events.log";
+        || relativeName === "events.log"
+        // `hunch serve` flushes INSIDE its cross-process write lock, so the lock file is always
+        // staged alongside the record; treating it as a violation made every served write skip
+        // the commit quietly and report durability "local" forever (1.26.0/1.26.1).
+        || relativeName === "write.lock";
 }
 /** Enumerate ordinary JSON files already contained under an overlay. Push-capable
  * stores force-add this exact allowlist so remote .gitignore, info/exclude, or an

package/dist/mcp/server.js

@@ -22,6 +22,7 @@ import { knownRepoDeps } from "../synthesis/tripwires.js";
 import { refreshExistingGrounding } from "../integrations/providers.js";
 import { revParse, asOfDate, revExists, lastChangeDate, rangeFiles, rangeDiff, commitFiles, commitDiff, stagedFiles, stagedDiff, workingFiles, workingDiff, pullHunchStatus, sameRemoteUrl, currentBranch } from "../extractors/git.js";
 import { flushCapture, flushMemoryHome, pinSharedRemote } from "../integrations/sync.js";
+import { withWriteLock } from "../serve/writelock.js";
 import { advertisedTeamRemoteContract, ensureTeamOverlay, overlayMatchesTeamRemote, readTeamConfig, teamRemoteContract, teamSharedRef } from "../integrations/team.js";
 import { formatStructure } from "../core/format.js";
 import { diagnoseIssueCorrectionStage, formatCorrectionStageDiagnostic } from "../core/correctionStage.js";
@@ -517,7 +518,8 @@ function prepareRoot(root, explicitOverlay, requireIndex) {
         throw error;
     }
 }
-export function buildServerWithRootControl(initialRoot) {
+export function buildServerWithRootControl(initialRoot, options = {}) {
+    const pinned = options.pinned === true;
     const explicitOverlay = !!process.env.HUNCH_PRIVATE_DIR?.trim();
     const initial = prepareRoot(initialRoot, explicitOverlay, false);
     let root = initial.root;
@@ -670,7 +672,9 @@ export function buildServerWithRootControl(initialRoot) {
         // sole in-flight request — re-homing under a concurrent request would tear its
         // root/store out from under it, so that case is refused rather than risked.
         const cwdHint = extractCwdHint(args[0]);
-        if (cwdHint !== undefined) {
+        // A pinned root is the whole point of `hunch mcp --root`: a served partition must not
+        // follow the caller's working directory into some other checkout.
+        if (cwdHint !== undefined && !pinned) {
             const target = canonicalRootPath(findRoot(cwdHint));
             if (target !== canonicalRootPath(root)) {
                 if (activeRequests) {
@@ -1710,7 +1714,31 @@ export function buildServerWithRootControl(initialRoot) {
                 ? `subject ${sor.subject}: current ${sor.current.length} · in force ${sor.in_force.length} · done ${sor.done.length} · depends on ${sor.depends_on.length} · invalidated by ${sor.invalidated_by.length}`
                 : "no subject — delivery envelope only";
             const deniedNote = response.denied_scopes.length ? `\ndenied scopes: ${response.denied_scopes.map((s) => `${s.kind}/${s.id}`).join(", ")}` : "";
-            return stateResult(`${response.receipt_id} · ${summary}${deniedNote}\n\n${envelope.text}`, response);
+            // Render the state of record itself, not only its refs: a consumer answers from this text.
+            const line = (label, ref) => {
+                const r = (response.records ?? {})[ref.id] ?? {};
+                const g = (k) => { const v = r[k]; return typeof v === "string" ? v : v == null ? "" : JSON.stringify(v); };
+                if (ref.facet === "derived")
+                    return `- ${label} derived ${ref.id} · computed ${g("computed_at")} · ${r.dependencies?.length ?? 0} dependencies\n    ${g("content").slice(0, 1200)}`;
+                if (ref.facet === "commitments")
+                    return `- ${label} commitment ${ref.id} · ${g("status")} · due ${g("due")} · owner ${g("owner")}: ${g("title")}`;
+                if (ref.facet === "receipts") {
+                    const t = (r.target ?? {});
+                    return `- ${label} receipt ${ref.id} · ${g("action_kind")} on ${String(t.system ?? "")} ${String(t.object_type ?? "")}:${String(t.object_key ?? "")} · ${g("state")} at ${g("occurred_at")} by ${g("actor")}`;
+                }
+                if (ref.facet === "decisions")
+                    return `- ${label} decision ${ref.id} · ${g("status")}: ${g("title")}`;
+                if (ref.facet === "constraints")
+                    return `- ${label} constraint ${ref.id} · ${g("severity")}: ${g("statement")}`;
+                if (ref.facet === "entities")
+                    return `- ${label} entity ${ref.id} · ${g("kind")} ${g("name")} · ${g("lifecycle")}`;
+                return `- ${label} ${ref.facet} ${ref.id}`;
+            };
+            const stateText = sor
+                ? [...sor.current.map((r) => line("current", r)), ...sor.in_force.map((r) => line("in force", r)), ...sor.done.map((r) => line("done", r)),
+                    ...(sor.invalidated_by.length ? [`- invalidated by: ${sor.invalidated_by.join(", ")}`] : [])].join("\n") || "(nothing on record for this subject)"
+                : "";
+            return stateResult(`${response.receipt_id} · ${summary}${deniedNote}${stateText ? `\n\nState of record:\n${stateText}` : ""}\n\n${envelope.text}`, response);
         }
         catch (e) {
             return stateRefusal(e);
@@ -1723,9 +1751,11 @@ export function buildServerWithRootControl(initialRoot) {
         outputSchema: WriteResultSchema.shape,
     }, async ({ cwd: _cwd, ...input }) => {
         try {
-            const result = writeState(store, { schema: STATE_WRITE_VERSION, ...input }, {
+            // Same cross-process lock `hunch serve` takes: a second agent writing over stdio must
+            // not race the HTTP server between the ledger read and the record write.
+            const result = await withWriteLock(hunchPaths(root).hunch, () => writeState(store, { schema: STATE_WRITE_VERSION, ...input }, {
                 flush: (isPrivate, message) => flushCapture(store, hunchPaths(root).hunch, isPrivate, message, startupTeamRoute ?? undefined),
-            });
+            }));
             return stateResult(`${result.outcome} ${result.record_id} (${result.durability}) ${result.record_hash}`, result);
         }
         catch (e) {
@@ -2290,7 +2320,9 @@ export function buildServerWithRootControl(initialRoot) {
     return {
         server,
         getRoot: () => root,
-        setRoot,
+        setRoot: (next) => { if (!pinned)
+            setRoot(next); },
+        pinned,
         cancelPendingRoot: () => { pendingRoot = null; },
     };
 }
@@ -2309,6 +2341,8 @@ function provLine(record) {
 /** Query client roots after initialization and follow later list changes.
  *  Generation ordering prevents a slow stale roots/list response from winning. */
 export function wireClientRoots(control, fallback) {
+    if (control.pinned)
+        return; // `hunch mcp --root`: the client's workspace is not this server's store
     let generation = 0;
     const syncRoots = async () => {
         const mine = ++generation;
@@ -2346,12 +2380,14 @@ export function wireClientRoots(control, fallback) {
     control.server.server.setNotificationHandler(RootsListChangedNotificationSchema, async () => { await syncRoots(); });
 }
 /** Start the stdio server (called by `hunch mcp`). */
-export async function startServer(cwd = process.cwd()) {
-    const fallback = findRoot(cwd);
-    const control = buildServerWithRootControl(fallback);
+export async function startServer(cwd = process.cwd(), options = {}) {
+    const fallback = options.pinned ? cwd : findRoot(cwd);
+    const control = buildServerWithRootControl(fallback, options);
     wireClientRoots(control, fallback);
     const transport = new StdioServerTransport();
     await control.server.connect(transport);
-    console.error(`[hunch-mcp] serving Hunch over stdio (spawn root ${control.getRoot()}; resolving client roots…)`);
+    console.error(control.pinned
+        ? `[hunch-mcp] serving Hunch over stdio (pinned root ${control.getRoot()}; client roots ignored)`
+        : `[hunch-mcp] serving Hunch over stdio (spawn root ${control.getRoot()}; resolving client roots…)`);
 }
 //# sourceMappingURL=server.js.map

package/dist/serve/config.js

@@ -34,6 +34,11 @@ export const ServeConfigSchema = z.object({
     partitions: z.array(PartitionConfigSchema).min(1).max(256),
     principals: z.array(PrincipalConfigSchema).max(1024).default([]),
 }).strict();
+export const PARTITION_GITIGNORE = [
+    "# hunch serve partition — derived runtime artifacts (regenerable from .hunch/*.json)",
+    ".hunch/*.sqlite", ".hunch/*.sqlite-shm", ".hunch/*.sqlite-wal", ".hunch/*.sqlite-journal",
+    ".hunch/**/*.tmp*", ".hunch/write.lock", ".hunch/.hunch-commit.lock", ".hunch/local.json", ".hunch/events.log", "",
+].join("\n");
 export function hashToken(token) {
     return createHash("sha256").update(token, "utf8").digest("hex");
 }
@@ -104,6 +109,11 @@ export function initServeConfig(opts) {
     const manifest = resolve(hunchDir, "manifest.json");
     if (!existsSync(manifest))
         writeFileAtomic(manifest, JSON.stringify({ schema_version: 3 }, null, 2) + "\n");
+    // A served partition is meant to be its own git repository: keep the derived index, temp
+    // files and locks out of it so every auto-commit is records + ledger only.
+    const ignore = resolve(root, ".gitignore");
+    if (!existsSync(ignore))
+        writeFileAtomic(ignore, PARTITION_GITIGNORE);
     const partitions = existing ? existing.partitions.filter((p) => scopePath(p.scope) !== scopePath(opts.scope)) : [];
     const partition = { scope: opts.scope, root };
     partitions.push(partition);

package/dist/store/stateBinding.js

@@ -118,6 +118,7 @@ export function readState(store, input) {
         profile: request.profile ?? "builder",
     });
     let stateOfRecord = null;
+    const records = {};
     const denied = new Map();
     if (request.subject !== undefined) {
         const subject = request.subject;
@@ -135,6 +136,10 @@ export function readState(store, input) {
             }
             return scope;
         };
+        const keep = (facet, record, scope) => {
+            records[record.id] = record;
+            return refOf(facet, record, scope);
+        };
         if (facets.has("decisions"))
             for (const d of store.recs("decisions")) {
                 if (d.topic !== subject && d.id !== subject)
@@ -143,7 +148,7 @@ export function readState(store, input) {
                 if (!scope)
                     continue;
                 if (isLive(d))
-                    current.push(refOf("decisions", d, scope));
+                    current.push(keep("decisions", d, scope));
             }
         if (facets.has("constraints"))
             for (const c of store.recs("constraints")) {
@@ -153,7 +158,7 @@ export function readState(store, input) {
                 if (!scope)
                     continue;
                 if (c.status === "active" && c.valid_to == null)
-                    inForce.push(refOf("constraints", c, scope));
+                    inForce.push(keep("constraints", c, scope));
             }
         if (facets.has("receipts"))
             for (const r of store.recs("receipts")) {
@@ -164,7 +169,7 @@ export function readState(store, input) {
                 if (!scope)
                     continue;
                 if (r.state === "succeeded" || r.state === "verified")
-                    done.push(refOf("receipts", r, scope));
+                    done.push(keep("receipts", r, scope));
                 if (r.invalidates.includes(subject))
                     invalidatedBy.add(r.id);
             }
@@ -176,7 +181,7 @@ export function readState(store, input) {
                 if (!scope)
                     continue;
                 if ((c.status === "open" || c.status === "waiting") && c.valid_to == null)
-                    inForce.push(refOf("commitments", c, scope));
+                    inForce.push(keep("commitments", c, scope));
             }
         if (facets.has("derived"))
             for (const d of store.recs("derived")) {
@@ -186,7 +191,7 @@ export function readState(store, input) {
                 if (!scope)
                     continue;
                 if (d.state === "current" && d.valid_to == null) {
-                    current.push(refOf("derived", d, scope));
+                    current.push(keep("derived", d, scope));
                     dependsOn.push(...d.dependencies);
                 }
             }
@@ -198,7 +203,7 @@ export function readState(store, input) {
                 if (!scope)
                     continue;
                 if (e.lifecycle === "active")
-                    current.push(refOf("entities", e, scope));
+                    current.push(keep("entities", e, scope));
             }
         if (facets.has("relationships"))
             for (const r of store.recs("relationships")) {
@@ -207,7 +212,7 @@ export function readState(store, input) {
                 const scope = admit("relationships", r);
                 if (!scope)
                     continue;
-                current.push(refOf("relationships", r, scope));
+                current.push(keep("relationships", r, scope));
             }
         stateOfRecord = { subject, current, in_force: inForce, done, depends_on: dependsOn, invalidated_by: [...invalidatedBy].sort() };
     }
@@ -217,6 +222,7 @@ export function readState(store, input) {
         scope: request.scope,
         state_of_record: stateOfRecord,
         denied_scopes: [...denied.values()],
+        ...(stateOfRecord ? { records } : {}),
     });
     assertReadWithinGrants(request.principal, response);
     return { response, envelope };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.26.0",
+  "version": "1.26.2",
   "mcpName": "io.github.davesheffer/hunch",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",

package/server.json

@@ -7,13 +7,13 @@
     "source": "github"
   },
   "websiteUrl": "https://www.hunchmemory.com",
-  "version": "1.26.0",
+  "version": "1.26.2",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@davesheffer/hunch",
-      "version": "1.26.0",
+      "version": "1.26.2",
       "runtimeHint": "npx",
       "packageArguments": [
         {