@davesheffer/hunch 1.38.0 → 1.39.0

package/dist/integrations/workspaceLedger.js

@@ -0,0 +1,201 @@
+/**
+ * Workspace ledger wiring (docs/workspace-ledger.md, Phase 2): the ONE code path every
+ * surface uses to read the ledger (CLI `workspaces` / `branches`, the `hunch_workspaces`
+ * MCP tool, `hunch now`, `doctor`) and to record this machine's snapshot (CLI `snapshot`,
+ * `hunch worktree`, the git hooks, and the MCP server's session-start refresh).
+ *
+ * This machine is always read LIVE from git and never from a stored record; stored
+ * records (other machines) are display-only. A snapshot writes through the same capture
+ * funnel as every other record: the overlay when one is configured, the public .hunch/
+ * only when `workspaces.publish_public` opts in, nothing otherwise.
+ */
+import { execFileSync } from "node:child_process";
+import { createInterface } from "node:readline";
+import { foreignRepoEnv, mainWorktreeRoot } from "../extractors/git.js";
+import { hunchPaths } from "../core/paths.js";
+import { readConfig, workspacesConfig } from "../core/config.js";
+import { loadOrCreateMachine } from "../core/machine.js";
+import { ago, branchRows, isSafeBranchName, latestPerMachine, isUnverified, planPrune, sameWorkspaceContent, withPublishMode, worktreeRows, } from "../core/workspace.js";
+import { snapshotWorkspace } from "../extractors/workspaces.js";
+import { flushCapture } from "./sync.js";
+export function workspaceLedgerView(store, root, opts = {}) {
+    const machine = loadOrCreateMachine();
+    const config = workspacesConfig(readConfig(hunchPaths(root)));
+    const live = snapshotWorkspace(root, { machine, publish: "full", fetch: !!opts.fetch });
+    const others = store.recs("workspaces").filter((r) => r.machine.id !== machine.id);
+    return { machine, live, records: [live, ...others], config };
+}
+/** Record this machine's snapshot. Honors `workspaces.publish`, skips a write when the
+ *  content is unchanged and the stored record is under a day old (an idle machine's hooks
+ *  must not commit a record per checkout), and reports exactly what happened. */
+export function recordWorkspaceSnapshot(store, root, opts = {}) {
+    const config = workspacesConfig(readConfig(hunchPaths(root)));
+    if (config.publish === "off")
+        return { status: "off" };
+    const machine = loadOrCreateMachine();
+    // A caller that already took a live snapshot (a ledger read) publishes THAT observation
+    // rather than paying for a second pass over git.
+    const record = opts.live && !opts.fetch
+        ? withPublishMode(opts.live, config.publish)
+        : snapshotWorkspace(root, { machine, publish: config.publish, fetch: !!opts.fetch });
+    if (opts.dryRun)
+        return { status: "dry-run", record };
+    const isPrivate = store.hasPrivate;
+    if (!isPrivate && !config.publish_public)
+        return { status: "no-home", record };
+    const previous = store.getRec("workspaces", record.id);
+    if (previous && Date.now() - Date.parse(previous.observed_at) < 86_400_000 && sameWorkspaceContent(previous, record)) {
+        return { status: "unchanged", record, previous };
+    }
+    try {
+        store.putCapture("workspaces", record, isPrivate);
+    }
+    catch (error) {
+        const reason = error.message;
+        if (/already exists in the other memory home/.test(reason))
+            return { status: "collision", record, reason };
+        throw error;
+    }
+    const flushed = flushCapture(store, hunchPaths(root).hunch, isPrivate, `hunch: workspace snapshot ${machine.label}`);
+    return { status: "written", record, home: isPrivate ? "private" : "public", flushed };
+}
+/** Whether a snapshot could land anywhere on this root — used to skip work that would
+ *  write nothing. */
+export function snapshotHasHome(store, root) {
+    const config = workspacesConfig(readConfig(hunchPaths(root)));
+    return config.publish !== "off" && (store.hasPrivate || config.publish_public);
+}
+// ---- rendering (shared by the CLI and the MCP tool) -----------------------------------------
+export function padTable(header, rows) {
+    const all = [header, ...rows];
+    const widths = header.map((_, i) => Math.max(...all.map((r) => (r[i] ?? "").length)));
+    return all.map((r) => r.map((c, i) => (i === r.length - 1 ? c ?? "" : (c ?? "").padEnd(widths[i]))).join("  ").trimEnd()).join("\n");
+}
+export function renderWorktreeTable(view, rows, now = new Date()) {
+    const table = padTable(["MACHINE", "WORKTREE", "BRANCH", "DIRTY", "LAST COMMIT", "SEEN"], rows.map((r) => [
+        r.machine + (r.machine === view.machine.label ? " (this)" : ""),
+        r.path ?? "yes",
+        r.branch ?? `(detached ${r.head.slice(0, 10)})`,
+        r.dirty === null ? "?" : r.dirty ? "yes" : "-",
+        r.last_commit_at ? ago(r.last_commit_at, now) : "-",
+        (r.machine === view.machine.label ? "live" : ago(r.seen_at, now)) + (r.unverified ? " (unverified)" : "") + (r.prunable ? " (path missing)" : "") + (r.locked ? " (locked)" : ""),
+    ]));
+    return `${table}\n\n${rows.length} worktree(s) · this machine is ${view.machine.label} · ${view.records.length - 1} other machine(s) in memory`;
+}
+export function describeUpstream(r) {
+    if (r.upstream === null)
+        return "never pushed";
+    if (r.upstream_gone)
+        return "gone";
+    return [r.ahead ? `ahead ${r.ahead}` : "", r.behind ? `behind ${r.behind}` : ""].filter(Boolean).join(", ") || "synced";
+}
+export function renderBranchTable(view, rows) {
+    const table = padTable(["BRANCH", "MACHINES", "WORKTREE", "UPSTREAM", "MERGED", "ACTION"], rows.map((r) => [
+        r.name,
+        r.machines.join(","),
+        r.worktree_on.length ? r.worktree_on.join(",") + (r.dirty_on.length ? " (dirty)" : "") : "-",
+        describeUpstream(r),
+        r.merged.status === "merged" ? `yes (${r.merged.method}${r.merged.pr ? `, PR #${r.merged.pr}` : ""})` : r.merged.status === "unmerged" ? "no" : "unknown",
+        r.action,
+    ]));
+    const deletable = rows.filter((r) => r.action.startsWith("delete local")).length;
+    const warn = view.live.default_branch === null ? "\n  ⚠ no default branch resolved (origin/HEAD, origin/main|master, main|master) — merge verdicts are unknown" : "";
+    return `${table}\n\n${rows.length} branch(es) · ${deletable} deletable · this machine is ${view.machine.label}${warn}`;
+}
+/** One line for `hunch now` / `hunch_now`, from STORED records only (no git, so the hot
+ *  view stays fast); null when memory holds no workspace record. */
+export function workspaceSummaryLine(records, config, now = new Date()) {
+    const latest = latestPerMachine(records);
+    if (!latest.length)
+        return null;
+    const opts = { staleAfterDays: config.stale_after_days, now };
+    const worktrees = worktreeRows(latest, opts);
+    const branches = branchRows(latest, opts);
+    const unverified = latest.filter((r) => isUnverified(r, opts)).length;
+    const deletable = branches.filter((b) => b.action.startsWith("delete local")).length;
+    const dirty = worktrees.filter((w) => w.dirty === true).length;
+    return `🗂 Workspaces in memory: ${latest.length} machine(s)${unverified ? ` (${unverified} unverified)` : ""} · ${worktrees.length} worktree(s)${dirty ? ` (${dirty} dirty)` : ""} · ${branches.length} branch(es), ${deletable} deletable — \`hunch branches\` for the verdicts`;
+}
+export { branchRows, worktreeRows };
+// ---- prune (Phase 3) ------------------------------------------------------------------------
+//
+// `--apply` acts on THIS machine only, from a snapshot taken moments ago (never a stored
+// record), with `git worktree remove` (no --force) and `git branch -d` (no -D), so git itself
+// re-checks "clean" and "merged" as a second line of defense. Nothing here touches a remote
+// or another machine; their commands are printed for a human to run there.
+export function prunePlanFor(view) {
+    return planPrune(view.live, view.records);
+}
+/** Execute the local steps of a plan. Each command is a fixed argv; the branch name was
+ *  validated by the record schema and is passed after `--`; the worktree path comes from
+ *  `git worktree list` on this machine. A failure stops that step, never the others. */
+export function applyPrune(root, steps) {
+    const main = mainWorktreeRoot(root);
+    const env = foreignRepoEnv(process.env);
+    const git = (args) => execFileSync("git", args, { cwd: main, env, encoding: "utf8", timeout: 60_000, stdio: ["ignore", "pipe", "pipe"] }).trim();
+    const results = [];
+    for (const step of steps) {
+        if (!isSafeBranchName(step.branch)) {
+            results.push({ step, outcome: "failed", detail: "refused: unsafe branch name" });
+            continue;
+        }
+        try {
+            const detail = [];
+            if (step.worktree?.path) {
+                git(["worktree", "remove", "--", step.worktree.path]);
+                detail.push(`removed worktree ${step.worktree.path}`);
+            }
+            else if (step.worktree) {
+                results.push({ step, outcome: "failed", detail: "refused: the worktree's path is not known on this machine" });
+                continue;
+            }
+            git(["branch", "-d", "--", step.branch]);
+            detail.push(`deleted branch ${step.branch} (was ${step.head.slice(0, 12)})`);
+            results.push({ step, outcome: "deleted", detail: detail.join("; ") });
+        }
+        catch (error) {
+            const stderr = error.stderr?.toString().trim().split("\n")[0] ?? error.message;
+            results.push({ step, outcome: "failed", detail: `git refused: ${stderr}` });
+        }
+    }
+    return results;
+}
+/** Interactive yes/no; false when stdin is not a terminal (the caller then needs --yes). */
+export async function confirmPrune(question) {
+    if (!process.stdin.isTTY)
+        return false;
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        const answer = await new Promise((resolve) => rl.question(`${question} [y/N] `, resolve));
+        return /^y(es)?$/i.test(answer.trim());
+    }
+    finally {
+        rl.close();
+    }
+}
+export function renderPrunePlan(view, plan) {
+    const L = [];
+    L.push(`This machine (${view.machine.label}) — ${plan.local.length} branch(es) provably merged and safe to delete:`);
+    if (!plan.local.length)
+        L.push("  (nothing)");
+    for (const step of plan.local) {
+        L.push(`  ${step.branch}  — ${step.why}`);
+        for (const c of step.commands)
+            L.push(`    ${c}`);
+    }
+    if (plan.skipped.length) {
+        L.push("", "Merged but left alone on this machine:");
+        for (const s of plan.skipped)
+            L.push(`  ${s.branch}  — ${s.reason}`);
+    }
+    for (const [label, steps] of Object.entries(plan.others)) {
+        const record = view.records.find((r) => r.machine.label === label);
+        const stale = record && isUnverified(record, { staleAfterDays: view.config.stale_after_days }) ? " (unverified — the record is old)" : "";
+        L.push("", `On ${label}${stale} — run there, from that machine's stored record (never executed from here):`);
+        for (const step of steps)
+            for (const c of step.commands)
+                L.push(`  ${c}`);
+    }
+    return L.join("\n");
+}
+//# sourceMappingURL=workspaceLedger.js.map

package/dist/mcp/server.js

@@ -26,6 +26,8 @@ import { decisionId, findingId } from "../core/ids.js";
 import { buildCorrectionConstraint } from "../core/correction.js";
 import { knownRepoDeps } from "../synthesis/tripwires.js";
 import { refreshExistingGrounding } from "../integrations/providers.js";
+import { workspaceLedgerView, renderWorktreeTable, renderBranchTable, workspaceSummaryLine, snapshotHasHome, recordWorkspaceSnapshot, branchRows, worktreeRows } from "../integrations/workspaceLedger.js";
+import { workspacesConfig } from "../core/config.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";
@@ -1231,6 +1233,12 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             L.push(`  • ${r.title} (${r.id}${r.topic ? `, ${r.topic}` : ""}, since ${r.date})\n      ${r.note}`);
         if (pendingReview > 0)
             L.push("", `${pendingReview} legacy un-vouched draft(s) — \`hunch adopt-drafts\` auto-trusts them as advisory (new captures land trusted automatically).`);
+        // Workspace ledger, from stored PUBLIC records only (same jurisdiction rule as the rest
+        // of this view; no git, so the hot view stays fast). Machine labels are user-chosen
+        // and the default is anonymous, so the line is publishable by construction.
+        const ws = workspaceSummaryLine(store.json.loadAll("workspaces"), workspacesConfig(readConfig(hunchPaths(root))));
+        if (ws)
+            L.push("", ws);
         const escalations = pendingEscalations(store.advisoryRecs("decisions"));
         escalations.push(...premiseEscalations(store.advisoryRecs("decisions"), { now: new Date().toISOString(), exists: (p) => existsSync(join(root, p)) }));
         // liveness checked against the full store (repair-provenance reads the
@@ -1248,6 +1256,52 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
         }
         return ok(L.join("\n"));
     });
+    // -- hunch_workspaces (the workspace ledger: worktrees + branches across machines) --
+    // READ-ONLY by design (docs/workspace-ledger.md): an agent can see what is prunable but
+    // can only act through the CLI, where a human confirms. This machine is read live from
+    // git; other machines come from stored records, which are display-only.
+    server.registerTool("hunch_workspaces", {
+        title: "Worktrees and branches across machines",
+        description: "The workspace ledger: which git worktrees are open on which machine, and every local branch with a deterministic verdict — merged (ancestry / squash / rebase), never pushed, upstream gone, dirty worktree — plus a recommended action per branch. Call this INSTEAD of running git branch / git worktree list / git log to answer 'what is open, what is stale, what can be deleted'. This machine is read live; other machines from memory (a machine older than the staleness window is marked unverified). Read-only: it never deletes anything. Not for design rationale (hunch_why) or code structure (hunch_structure).",
+        inputSchema: {
+            view: z.enum(["inventory", "branches"]).optional().describe("inventory = one row per worktree (default); branches = one row per branch with its verdict and action."),
+            machine: z.string().optional().describe("Only this machine label."),
+            branch: z.string().optional().describe("Only this branch name."),
+            merged_only: z.boolean().optional().describe("branches view: only branches proven merged."),
+        },
+    }, async ({ view, machine, branch, merged_only }) => {
+        const ledger = workspaceLedgerView(store, root);
+        // Publish the observation this read just took, so the machines that ask about the
+        // ledger are also the machines visible IN it — the one moment the data provably
+        // matters, with no timer and no child process (a detached snapshot child held a
+        // Windows clone directory open and broke an unrelated test's teardown). The git
+        // hooks remain the normal path; this covers a host that has none yet. Best effort:
+        // the read never fails because memory could not be written.
+        // HUNCH_WORKSPACE_REFRESH=0 opts out entirely.
+        if (process.env.HUNCH_WORKSPACE_REFRESH !== "0" && snapshotHasHome(store, root)) {
+            try {
+                recordWorkspaceSnapshot(store, root, { live: ledger.live });
+            }
+            catch { /* the ledger is a side effect of the read, never its blocker */ }
+        }
+        const opts = { staleAfterDays: ledger.config.stale_after_days };
+        if (view === "branches") {
+            let rows = branchRows(ledger.records, opts);
+            if (machine)
+                rows = rows.filter((r) => r.machines.includes(machine));
+            if (branch)
+                rows = rows.filter((r) => r.name === branch);
+            if (merged_only)
+                rows = rows.filter((r) => r.merged.status === "merged");
+            return { content: [{ type: "text", text: renderBranchTable(ledger, rows) }], structuredContent: { machine: ledger.machine.label, branches: rows } };
+        }
+        let rows = worktreeRows(ledger.records, opts);
+        if (machine)
+            rows = rows.filter((r) => r.machine === machine);
+        if (branch)
+            rows = rows.filter((r) => r.branch === branch);
+        return { content: [{ type: "text", text: renderWorktreeTable(ledger, rows) }], structuredContent: { machine: ledger.machine.label, worktrees: rows } };
+    });
     // -- hunch_escalations (the inline "ask the human" surface) -----------------
     // Captured memory auto-trusts; this returns ONLY what the graph can't resolve
     // itself, framed as questions to raise in conversation: topic conflicts, plus the

package/dist/mcp/taskReportTools.d.ts

@@ -193,4 +193,13 @@ export declare function boundedTaskReportForHost(report: ReturnType<typeof readT
     };
     full_report: string;
 };
+/** `metaUrl` is the module running (a `.ts` source checkout needs the tsx
+ * loader; a published `.js` build needs nothing) and `resolve` is that
+ * module's `import.meta.resolve`. The loader is resolved ONLY on the source
+ * path: `import.meta.resolve` throws for a package that is not installed, and
+ * `tsx` is a devDependency absent from every published install (#261). */
+export declare function verificationLauncherFor(metaUrl: string, resolve: (specifier: string) => string): {
+    argv: string[];
+    shell: string;
+};
 export declare function registerTaskReportTools(server: McpServer, getRoot: () => string, getStore: () => HunchStore): void;

package/dist/mcp/taskReportTools.js

@@ -51,13 +51,21 @@ export function boundedTaskReportForHost(report) {
 /** Reuse the MCP server's installation, not a potentially stale global binary.
  * Structured argv is authoritative; the shell hint uses literal quoting. */
 function verificationLauncher() {
-    const dev = import.meta.url.endsWith(".ts");
-    const entry = fileURLToPath(new URL(`../cli/index.${dev ? "ts" : "js"}`, import.meta.url));
+    return verificationLauncherFor(import.meta.url, (specifier) => import.meta.resolve(specifier));
+}
+/** `metaUrl` is the module running (a `.ts` source checkout needs the tsx
+ * loader; a published `.js` build needs nothing) and `resolve` is that
+ * module's `import.meta.resolve`. The loader is resolved ONLY on the source
+ * path: `import.meta.resolve` throws for a package that is not installed, and
+ * `tsx` is a devDependency absent from every published install (#261). */
+export function verificationLauncherFor(metaUrl, resolve) {
+    const dev = metaUrl.endsWith(".ts");
+    const entry = fileURLToPath(new URL(`../cli/index.${dev ? "ts" : "js"}`, metaUrl));
     // `--import` takes a URL. Converting the resolved loader to a path made Node on
     // Windows reject it ("Received protocol 'c:'"), so every verification launched
     // from a source checkout there failed before running and cards showed no check.
-    const loader = import.meta.resolve("tsx");
-    const argv = [process.execPath, ...(dev ? ["--import", loader.startsWith("file:") ? loader : pathToFileURL(loader).href] : []), entry];
+    const loader = dev ? resolve("tsx") : null;
+    const argv = [process.execPath, ...(loader ? ["--import", loader.startsWith("file:") ? loader : pathToFileURL(loader).href] : []), entry];
     const quote = (s) => process.platform === "win32" ? `'${s.replace(/'/g, "''")}'` : `'${s.replace(/'/g, "'\\''")}'`;
     return { argv, shell: `${process.platform === "win32" ? "& " : ""}${argv.map(quote).join(" ")}` };
 }
@@ -91,7 +99,7 @@ export function registerTaskReportTools(server, getRoot, getStore) {
                     task = readTaskReport(root, task_id, reportSourceSnapshot(root).hash).task;
                 }
                 const launcher = verificationLauncher();
-                return { content: [{ type: "text", text: `Task ${task.task_id} · ${task.state}. Pass task_id to every hunch_context and decision/correction/finding capture call. Before the final response, finish with hunch_task and include its contribution card. For checks use this exact installation (the global hunch binary may be stale): ${launcher.shell} task verify ${task.task_id} -- <command> [arguments]. The default budget is 2 minutes; add --timeout <seconds> before -- for a long suite.` }], structuredContent: { task, verification_argv: [...launcher.argv, "task", "verify", task.task_id, "--"] } };
+                return { content: [{ type: "text", text: `Task ${task.task_id} · ${task.state}. Pass task_id to every hunch_context and decision/correction/finding capture call. Before the final response, finish with hunch_task and include its contribution card. For checks use this exact installation (the global hunch binary may be stale): ${launcher.shell} task verify ${task.task_id} -- <command> [arguments]. The default budget is 15 minutes; add --timeout <seconds> before -- for a longer suite.` }], structuredContent: { task, verification_argv: [...launcher.argv, "task", "verify", task.task_id, "--"] } };
             }
             if (!task_id)
                 throw new Error("finish requires the exact task_id");

package/dist/serve/app.d.ts

@@ -13,6 +13,8 @@
  *   POST /nuryel/v1/write             → writeState (under the partition's write lock)
  *   POST /nuryel/v1/subscribe         → subscribeState
  *   POST /nuryel/v1/records           → recordsState (by id, grants first)
+ *   POST /nuryel/v1/mcp               → the same verbs as nuryel_* tools over MCP streamable HTTP
+ *                                       (src/serve/mcpHttp.ts), through the same dispatcher
  * Request bodies are the contract's request schemas minus `schema` and `principal`.
  */
 import { type Server } from "node:http";

package/dist/serve/app.js

@@ -16,6 +16,8 @@ import { STATE_PROOF_CAPABILITY } from '../core/stateProof.js';
  *   POST /nuryel/v1/write             → writeState (under the partition's write lock)
  *   POST /nuryel/v1/subscribe         → subscribeState
  *   POST /nuryel/v1/records           → recordsState (by id, grants first)
+ *   POST /nuryel/v1/mcp               → the same verbs as nuryel_* tools over MCP streamable HTTP
+ *                                       (src/serve/mcpHttp.ts), through the same dispatcher
  * Request bodies are the contract's request schemas minus `schema` and `principal`.
  */
 import { createServer } from "node:http";
@@ -30,7 +32,9 @@ import { HUNCH_VERSION } from "../core/version.js";
 import { captureState, captureBatchState } from "../store/stateCapture.js";
 import { STATE_CAPTURE_VERSION, STATE_CAPTURE_BATCH_VERSION } from "../core/stateContract.js";
 import { operatorHtml, operatorCss, operatorJs } from "./operator.js";
+import { MCP_PATH, handleMcpRequest } from "./mcpHttp.js";
 export const BODY_LIMIT_BYTES = 1024 * 1024;
+const POST_ROUTES = new Map([["/nuryel/v1/read", "read"], ["/nuryel/v1/write", "write"], ["/nuryel/v1/capture", "capture"], ["/nuryel/v1/capture-batch", "capture-batch"], ["/nuryel/v1/subscribe", "subscribe"], ["/nuryel/v1/records", "records"]]);
 export const PROBLEM_TYPE = "https://www.hunchmemory.com/problems/nuryel.state/1/";
 export class HttpProblem extends Error {
     status;
@@ -119,8 +123,87 @@ export function createServeApp(config, opts = {}) {
         res.writeHead(status, { "content-type": `${type}; charset=utf-8`, "content-length": Buffer.byteLength(text), "cache-control": "no-store", "x-hunch-version": version });
         res.end(text);
     };
-    const sendProblem = (res, p) => {
-        send(res, p.status, { type: `${PROBLEM_TYPE}${p.code}`, title: p.code, status: p.status, detail: p.message, ...p.extra }, "application/problem+json");
+    const problemBody = (p) => ({ type: `${PROBLEM_TYPE}${p.code}`, title: p.code, status: p.status, detail: p.message, ...p.extra });
+    const sendProblem = (res, p) => { send(res, p.status, problemBody(p), "application/problem+json"); };
+    /** Anything thrown → problem. Shared by REST (problem+json) and MCP (tool error results). */
+    const problemOf = (error) => {
+        if (error instanceof HttpProblem)
+            return error;
+        if (error instanceof StateRefusal)
+            return problem(REFUSAL_STATUS[error.code], error.code, error.message, error.conflict ? { conflict: error.conflict } : {});
+        if (error instanceof WriteLockTimeout)
+            return problem(503, "write-lock-timeout", error.message, { "retry-after": 1 });
+        if (error && typeof error === "object" && error.name === "ZodError") {
+            const issues = (error.issues ?? []).map((i) => `${i.path.join(".") || "request"}: ${i.message}`);
+            return problem(400, "malformed", `request is malformed: ${issues.join("; ")}`, { issues });
+        }
+        return problem(500, "internal", error.message);
+    };
+    /** One authenticated state verb. The REST routes and the MCP tools both call this, so every
+     *  rule — grants, the write lock, flushes, refusals — is the same whichever transport carried it. */
+    const dispatch = async (route, principal, body, activeConfig) => {
+        const requestStore = (scope) => storeFor(scope, activeConfig);
+        const isGranted = (s) => principal.grants.some((g) => scopePath(g) === scopePath(s));
+        if (route === "capabilities") {
+            let scope = principal.grants[0];
+            if (body.scope !== undefined) {
+                const parsed = ScopeSchema.safeParse(body.scope);
+                if (!parsed.success)
+                    throw problem(400, "invalid-scope", "scope must be { kind, id }");
+                scope = parsed.data;
+            }
+            if (!isGranted(scope))
+                throw problem(403, "outside-grants", `scope ${scopePath(scope)} is outside the principal's grants`);
+            const offered = capabilities(requestStore(scope).store);
+            return { status: 200, payload: { ...offered, capabilities: [...offered.capabilities, STATE_PROOF_CAPABILITY], principal: { id: principal.id, kind: principal.kind, grants: principal.grants } } };
+        }
+        // The body never names the principal: the credential did.
+        delete body.principal;
+        delete body.schema;
+        const scope = requireScope(principal, body);
+        // Only authenticated grants select stores for cross-partition source visibility.
+        const accessOptions = { additionalStores: principal.grants.map(grant => requestStore(grant).store) };
+        const { store, root } = requestStore(scope);
+        const flush = (isPrivate, message) => flushCapture(store, hunchPaths(root).hunch, isPrivate, message);
+        if (route === "read") {
+            if (body.observed_page !== undefined && body.scopes !== undefined)
+                throw problem(400, 'malformed', 'observation pages require a single partition without scopes');
+            if (body.scopes === undefined) {
+                const { response, envelope } = readState(store, { schema: STATE_READ_VERSION, principal, ...body }, accessOptions);
+                return { status: 200, payload: { ...response, envelope } };
+            }
+            // Union read. The primary `scope` was gated above as always; every extra scope is
+            // either granted (read from ITS partition — 404 no-partition if this server lacks it)
+            // or named in denied_scopes. One ungranted extra never refuses the whole call.
+            const requested = ReadScopesSchema.safeParse(body.scopes);
+            if (!requested.success)
+                throw problem(400, "invalid-scope", "scopes must be 1..64 entries of { kind, id }");
+            const { scopes: _scopes, ...rest } = body;
+            const ungranted = requested.data.filter((s) => !isGranted(s));
+            const others = new Map();
+            for (const s of requested.data)
+                if (isGranted(s) && scopePath(s) !== scopePath(scope) && !others.has(scopePath(s)))
+                    others.set(scopePath(s), s);
+            const primary = readState(store, { schema: STATE_READ_VERSION, principal, ...rest, scope }, accessOptions);
+            const merged = mergeReadResponses(primary.response, [...others.values()].map((other) => readState(requestStore(other).store, { schema: STATE_READ_VERSION, principal, ...rest, scope: other }, accessOptions).response), ungranted);
+            return { status: 200, payload: { ...merged, envelope: primary.envelope } };
+        }
+        if (route === "write" || route === "capture" || route === "capture-batch") {
+            const { hunchDir } = stateHomeFor(store, scope);
+            const opts = { ...accessOptions, flush };
+            if (route === "write") {
+                const result = await withWriteLock(hunchDir, () => writeState(store, { schema: STATE_WRITE_VERSION, principal, ...body }, opts));
+                return { status: result.outcome === "created" ? 201 : 200, payload: result };
+            }
+            if (route === "capture") {
+                const result = await withWriteLock(hunchDir, () => captureState(store, { schema: STATE_CAPTURE_VERSION, principal, ...body }, opts));
+                return { status: result.outcome === "created" ? 201 : 200, payload: result };
+            }
+            return { status: 200, payload: await withWriteLock(hunchDir, () => captureBatchState(store, { schema: STATE_CAPTURE_BATCH_VERSION, principal, ...body }, opts)) };
+        }
+        if (route === "subscribe")
+            return { status: 200, payload: subscribeState(store, { schema: STATE_SUBSCRIBE_VERSION, principal, ...body }, accessOptions) };
+        return { status: 200, payload: recordsState(store, { schema: STATE_RECORDS_VERSION, principal, ...body }, accessOptions) };
     };
     const server = createServer(async (req, res) => {
         try {
@@ -131,7 +214,6 @@ export function createServeApp(config, opts = {}) {
             catch {
                 throw problem(503, 'configuration-unavailable', 'server configuration is unavailable; authentication is refused');
             }
-            const requestStore = (scope) => storeFor(scope, activeConfig);
             const url = new URL(req.url ?? "/", "http://127.0.0.1");
             // Public shell only: all workspace data still uses the authenticated state routes below.
             const asset = new Map([["/operator", [operatorHtml, "text/html"]], ["/operator/", [operatorHtml, "text/html"]], ["/operator.css", [operatorCss, "text/css"]], ["/operator.js", [operatorJs, "text/javascript"]]]).get(url.pathname);
@@ -171,101 +253,34 @@ export function createServeApp(config, opts = {}) {
                 throw problem(401, 'invalid_dpop_proof', 'credential is not bound to a proof key');
             const principal = { id: credential.id, kind: credential.kind, grants: credential.grants, ...(credential.display ? { display: credential.display } : {}) };
             if (url.pathname === "/nuryel/v1/capabilities" && req.method === "GET") {
-                const scope = parseScopeParam(url.searchParams.get("scope")) ?? principal.grants[0];
-                if (!principal.grants.some((g) => scopePath(g) === scopePath(scope)))
-                    throw problem(403, "outside-grants", `scope ${scopePath(scope)} is outside the principal's grants`);
-                const { store } = requestStore(scope);
-                const offered = capabilities(store);
-                return send(res, 200, { ...offered, capabilities: [...offered.capabilities, STATE_PROOF_CAPABILITY], principal: { id: principal.id, kind: principal.kind, grants: principal.grants } });
+                const scope = parseScopeParam(url.searchParams.get("scope"));
+                const { status, payload } = await dispatch("capabilities", principal, scope ? { scope } : {}, activeConfig);
+                return send(res, status, payload);
             }
-            if (req.method !== "POST")
-                throw problem(405, "method-not-allowed", `${req.method} is not allowed on ${url.pathname}`);
-            const body = await readBody(req);
-            // The body never names the principal: the token did.
-            delete body.principal;
-            delete body.schema;
-            // Only authenticated grants select stores for cross-partition source visibility.
-            const accessOptions = { additionalStores: principal.grants.map(grant => requestStore(grant).store) };
-            if (url.pathname === "/nuryel/v1/read") {
-                const scope = requireScope(principal, body);
-                if (body.observed_page !== undefined && body.scopes !== undefined)
-                    throw problem(400, 'malformed', 'observation pages require a single partition without scopes');
-                const { store } = requestStore(scope);
-                if (body.scopes === undefined) {
-                    const { response, envelope } = readState(store, { schema: STATE_READ_VERSION, principal, ...body }, accessOptions);
-                    return send(res, 200, { ...response, envelope });
+            if (url.pathname === MCP_PATH) {
+                // Stateless MCP: no server-initiated stream to open (GET) and no session to end (DELETE).
+                if (req.method !== "POST") {
+                    res.setHeader("allow", "POST");
+                    throw problem(405, "method-not-allowed", `${req.method} is not allowed on ${url.pathname}; MCP here is stateless POST`);
                 }
-                // Union read. The primary `scope` was gated above as always; every extra scope is
-                // either granted (read from ITS partition — 404 no-partition if this server lacks it)
-                // or named in denied_scopes. One ungranted extra never refuses the whole call.
-                const requested = ReadScopesSchema.safeParse(body.scopes);
-                if (!requested.success)
-                    throw problem(400, "invalid-scope", "scopes must be 1..64 entries of { kind, id }");
-                const { scopes: _scopes, ...rest } = body;
-                const isGranted = (s) => principal.grants.some((g) => scopePath(g) === scopePath(s));
-                const ungranted = requested.data.filter((s) => !isGranted(s));
-                const others = new Map();
-                for (const s of requested.data)
-                    if (isGranted(s) && scopePath(s) !== scopePath(scope) && !others.has(scopePath(s)))
-                        others.set(scopePath(s), s);
-                const primary = readState(store, { schema: STATE_READ_VERSION, principal, ...rest, scope }, accessOptions);
-                const merged = mergeReadResponses(primary.response, [...others.values()].map((other) => readState(requestStore(other).store, { schema: STATE_READ_VERSION, principal, ...rest, scope: other }, accessOptions).response), ungranted);
-                return send(res, 200, { ...merged, envelope: primary.envelope });
-            }
-            if (url.pathname === "/nuryel/v1/write") {
-                const scope = requireScope(principal, body);
-                const { store, root } = requestStore(scope);
-                const { hunchDir } = stateHomeFor(store, scope);
-                const result = await withWriteLock(hunchDir, () => writeState(store, { schema: STATE_WRITE_VERSION, principal, ...body }, {
-                    ...accessOptions,
-                    flush: (isPrivate, message) => flushCapture(store, hunchPaths(root).hunch, isPrivate, message),
-                }));
-                return send(res, result.outcome === "created" ? 201 : 200, result);
-            }
-            if (url.pathname === "/nuryel/v1/capture") {
-                const scope = requireScope(principal, body);
-                const { store, root } = requestStore(scope);
-                const { hunchDir } = stateHomeFor(store, scope);
-                const result = await withWriteLock(hunchDir, () => captureState(store, { schema: STATE_CAPTURE_VERSION, principal, ...body }, {
-                    ...accessOptions,
-                    flush: (isPrivate, message) => flushCapture(store, hunchPaths(root).hunch, isPrivate, message),
-                }));
-                return send(res, result.outcome === "created" ? 201 : 200, result);
-            }
-            if (url.pathname === "/nuryel/v1/capture-batch") {
-                const scope = requireScope(principal, body);
-                const { store, root } = requestStore(scope);
-                const { hunchDir } = stateHomeFor(store, scope);
-                const result = await withWriteLock(hunchDir, () => captureBatchState(store, { schema: STATE_CAPTURE_BATCH_VERSION, principal, ...body }, {
-                    ...accessOptions,
-                    flush: (isPrivate, message) => flushCapture(store, hunchPaths(root).hunch, isPrivate, message),
-                }));
-                return send(res, 200, result);
+                const message = await readBody(req);
+                return await handleMcpRequest(req, res, message, (route, body) => dispatch(route, principal, body, activeConfig), (error) => problemBody(problemOf(error)), version);
             }
-            if (url.pathname === "/nuryel/v1/subscribe") {
-                const scope = requireScope(principal, body);
-                const { store } = requestStore(scope);
-                return send(res, 200, subscribeState(store, { schema: STATE_SUBSCRIBE_VERSION, principal, ...body }, accessOptions));
-            }
-            if (url.pathname === "/nuryel/v1/records") {
-                const scope = requireScope(principal, body);
-                const { store } = requestStore(scope);
-                return send(res, 200, recordsState(store, { schema: STATE_RECORDS_VERSION, principal, ...body }, accessOptions));
-            }
-            throw problem(404, "not-found", `${url.pathname} is not a nuryel.state/1 route`);
+            if (req.method !== "POST")
+                throw problem(405, "method-not-allowed", `${req.method} is not allowed on ${url.pathname}`);
+            const route = POST_ROUTES.get(url.pathname);
+            if (!route)
+                throw problem(404, "not-found", `${url.pathname} is not a nuryel.state/1 route`);
+            const { status, payload } = await dispatch(route, principal, await readBody(req), activeConfig);
+            return send(res, status, payload);
         }
         catch (error) {
-            if (error instanceof HttpProblem)
-                return sendProblem(res, error);
-            if (error instanceof StateRefusal)
-                return sendProblem(res, problem(REFUSAL_STATUS[error.code], error.code, error.message, error.conflict ? { conflict: error.conflict } : {}));
-            if (error instanceof WriteLockTimeout)
-                return sendProblem(res, problem(503, "write-lock-timeout", error.message, { "retry-after": 1 }));
-            if (error && typeof error === "object" && error.name === "ZodError") {
-                const issues = (error.issues ?? []).map((i) => `${i.path.join(".") || "request"}: ${i.message}`);
-                return sendProblem(res, problem(400, "malformed", `request is malformed: ${issues.join("; ")}`, { issues }));
+            // An MCP response may already be on the wire; a second status line would corrupt it.
+            if (res.headersSent) {
+                res.end();
+                return;
             }
-            return sendProblem(res, problem(500, "internal", error.message));
+            return sendProblem(res, problemOf(error));
         }
     });
     const closeStores = () => { for (const store of stores.values())

package/dist/serve/mcpHttp.d.ts

@@ -0,0 +1,27 @@
+/**
+ * MCP over streamable HTTP for `hunch serve` — the nuryel.state/1 tools behind the same
+ * authenticated server, so an HTTP MCP client (an agent gateway, a remote orchestrator) can
+ * add the state layer as a tool target without a stdio process or a wrapper.
+ *
+ * A binding of the served routes, never a second implementation: every tool call goes through
+ * the dispatcher `createServeApp` uses for REST, so grants, the write lock, flushes and refusals
+ * are identical. The credential already resolved the principal before this runs; no tool
+ * accepts one. Stateless (a fresh server and transport per request, no session id) with JSON
+ * responses, because every verb is a single request/response.
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+export declare const MCP_PATH = "/nuryel/v1/mcp";
+export type StateRoute = "capabilities" | "read" | "write" | "capture" | "capture-batch" | "subscribe" | "records";
+export type StateDispatch = (route: StateRoute, body: Record<string, unknown>) => Promise<{
+    status: number;
+    payload: unknown;
+}>;
+export interface ProblemShape {
+    type: string;
+    title: string;
+    status: number;
+    detail: string;
+    [extra: string]: unknown;
+}
+/** Serve one authenticated MCP POST. The caller has already authenticated and parsed the body. */
+export declare function handleMcpRequest(req: IncomingMessage, res: ServerResponse, body: unknown, dispatch: StateDispatch, problemOf: (error: unknown) => ProblemShape, version: string): Promise<void>;