@flyingrobots/graft 0.6.1 → 0.7.1

package/dist/warp/warp-structural-log.js

@@ -0,0 +1,104 @@
+// ---------------------------------------------------------------------------
+// WARP-based Structural Log — replaces git log SHA walking
+// ---------------------------------------------------------------------------
+import { observeGraph } from "./context.js";
+/**
+ * Produce a structural log entirely from the WARP graph.
+ *
+ * Walks commit nodes in reverse tick order (most recent first),
+ * traverses outgoing adds/changes/removes edges per commit to
+ * collect symbol changes. Zero git subprocess calls.
+ */
+export async function structuralLogFromGraph(ctx, options) {
+    const limit = options?.limit ?? 20;
+    const pathFilter = options?.path;
+    // Query all commit nodes
+    const obs = await observeGraph(ctx, {
+        match: ["commit:*", "sym:*"],
+        expose: ["sha", "tick", "message", "author", "date", "name", "kind", "signature", "exported"],
+    });
+    const commitResult = await obs.query()
+        .match("commit:*")
+        .select(["id", "props"])
+        .run();
+    const commits = [];
+    for (const node of commitResult.nodes) {
+        if (node.id === undefined)
+            continue;
+        const props = node.props ?? {};
+        commits.push({
+            id: node.id,
+            sha: typeof props["sha"] === "string" ? props["sha"] : node.id.slice("commit:".length),
+            tick: typeof props["tick"] === "number" ? props["tick"] : 0,
+            message: typeof props["message"] === "string" ? props["message"] : "",
+            author: typeof props["author"] === "string" ? props["author"] : "",
+            date: typeof props["date"] === "string" ? props["date"] : "",
+        });
+    }
+    if (commits.length === 0)
+        return [];
+    // Sort by tick descending (most recent first)
+    commits.sort((a, b) => b.tick - a.tick);
+    const scoped = commits.slice(0, limit);
+    // For each commit, traverse edges to get symbol changes
+    const edgeLabels = [
+        { label: "adds", key: "added" },
+        { label: "changes", key: "changed" },
+        { label: "removes", key: "removed" },
+    ];
+    const entries = [];
+    for (const commit of scoped) {
+        const added = [];
+        const changed = [];
+        const removed = [];
+        for (const { label, key } of edgeLabels) {
+            const symIds = await obs.traverse.bfs(commit.id, {
+                dir: "out",
+                labelFilter: label,
+                maxDepth: 1,
+            });
+            for (const symId of symIds) {
+                if (!symId.startsWith("sym:"))
+                    continue;
+                const withoutPrefix = symId.slice("sym:".length);
+                const lastColon = withoutPrefix.lastIndexOf(":");
+                if (lastColon === -1)
+                    continue;
+                const filePath = withoutPrefix.slice(0, lastColon);
+                const symbolName = withoutPrefix.slice(lastColon + 1);
+                if (pathFilter !== undefined && !filePath.startsWith(pathFilter))
+                    continue;
+                const symProps = await obs.getNodeProps(symId);
+                const kind = typeof symProps?.["kind"] === "string" ? symProps["kind"] : "unknown";
+                const signature = typeof symProps?.["signature"] === "string" ? symProps["signature"] : undefined;
+                const exported = typeof symProps?.["exported"] === "boolean" ? symProps["exported"] : false;
+                const change = {
+                    name: symbolName,
+                    kind,
+                    signature,
+                    exported,
+                    filePath,
+                };
+                if (key === "added")
+                    added.push(change);
+                else if (key === "changed")
+                    changed.push(change);
+                else
+                    removed.push(change);
+            }
+        }
+        const totalChanges = added.length + changed.length + removed.length;
+        entries.push({
+            sha: commit.sha,
+            author: commit.author,
+            date: commit.date,
+            message: commit.message,
+            symbols: { added, removed, changed },
+            summary: totalChanges === 0
+                ? "No structural changes."
+                : `${String(added.length)} added, ${String(changed.length)} changed, ${String(removed.length)} removed.`,
+        });
+    }
+    return entries;
+}
+//# sourceMappingURL=warp-structural-log.js.map

package/dist/warp/warp-structural-log.js.map

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

package/docs/CLI.md

@@ -8,9 +8,12 @@ flowchart LR
     A --> C[Namespaces]
     B --> B1[init]
     B --> B2[serve]
-    B --> B3[daemon]
-    B --> B4[index]
-    B --> B5[migrate local-history]
+    B --> B3[serve --runtime daemon]
+    B --> B4[daemon]
+    B --> B5[daemon status]
+    B --> B6[index]
+    B --> B7[migrate local-history]
+    B --> B8[enhance]
     C --> C1[read]
     C --> C2[struct]
     C --> C3[symbol]
@@ -19,28 +22,45 @@ flowchart LR
 
 ## What it is for
 - bootstrap and setup via `graft init`
+- repo-local stdio MCP via `graft serve`
+- daemon-backed stdio MCP via `graft serve --runtime daemon`
+- read-only daemon status inspection via `graft daemon status`
+- bounded, lazy WARP refresh via `graft index --path <path>`
 - one-time legacy import via `graft migrate local-history`
+- Git-facing structural review summaries via `git graft enhance`
 - local debugging and dogfooding of MCP peer commands
 - human-facing inspection of bounded state such as:
   - `graft diag activity`
   - `graft diag local-history-dag`
   - `graft diag doctor`
+  - `graft doctor --sludge`
   - `graft diag stats`
+  - `graft symbol difficulty`
 
 ## Core namespaces
 - `read` — bounded reads and change checks
 - `struct` — structural diff / since / map
-- `symbol` — precision show / find
+- `symbol` — precision show / find / blame / difficulty
 - `diag` — activity, local-history-dag, doctor, explain, stats, capture
 
 ## Release-facing commands
 ```bash
+graft serve
+graft serve --runtime daemon
+graft daemon status
+graft daemon status --socket /path/to/mcp.sock
+graft index --path src/app.ts --json
 graft migrate local-history --json
 graft diag activity --json
 graft diag local-history-dag --json
 graft diag doctor --json
+graft doctor --sludge --json
 graft symbol find 'create*' --json
+graft symbol difficulty createUser --path src/users.ts --json
 graft struct diff --json
+git graft enhance --since HEAD~1
+git-graft enhance --since HEAD~1
+git-graft enhance --since HEAD~1 --json
 ```
 
 ## Repo-local invocation
@@ -53,10 +73,54 @@ pnpm graft diag activity
 
 Bare `graft ...` only works when the package is installed or linked onto your `PATH`.
 
+`git graft enhance --since <ref> [--head <ref>] [--json]` is the
+installed Git external-command form for the release-facing structural
+review aggregator. `git-graft enhance --since <ref>` is the direct
+package binary form. Both route through the same top-level `enhance`
+parser path. The command composes the shipped structural-since and
+export-surface facts into a concise review summary; it does not wrap
+arbitrary Git subcommands or expand into provenance, blame, reference, or
+write-tool behavior.
+
 `graft diag activity` is the current human-facing between-commit surface. It reports bounded local `artifact_history`, not canonical provenance, and now renders a textual operator summary by default. Use `--json` when you want the structured machine-readable form.
 
 `graft diag local-history-dag` is a CLI-only debug surface over the repo-local WARP graph. It renders a bounded event-centric DAG for local history through Bijou's `dag()` component. In interactive terminals that means the Bijou DAG layout; in pipes or non-TTY contexts it degrades to Bijou's truthful pipe-mode graph listing.
 
+`graft daemon status` is the read-only daemon status surface. It connects
+to an already-running daemon, builds a deterministic status model from
+existing daemon read tools, and renders daemon health, sessions,
+workspace posture, monitors, scheduler pressure, and worker pressure.
+Use `--socket <path>` to inspect a non-default daemon socket. This first
+slice does not authorize, revoke, bind, rebind, pause, resume, start, or
+stop daemon resources.
+
+`graft index` follows the lazy-index policy. Use `--path <path>` to refresh a
+specific tracked source file at `HEAD`; read/search surfaces also opportunistically
+refresh the files they touch. Unbounded whole-repo indexing is guarded and returns
+a structured refusal when the request would write too many file patches at once.
+
+## MCP Runtime Selection
+
+`graft serve` is repo-local stdio MCP. The launched process owns one
+repo-local workspace rooted at the current checkout.
+
+`graft serve --runtime daemon` is daemon-backed stdio MCP. The launched
+process is a bridge to the local daemon `/mcp` surface. If the daemon is
+not already healthy, the bridge starts it and waits for readiness. Add
+`--no-autostart` to fail instead of starting a daemon, and add
+`--socket <path>` to target a non-default daemon socket.
+
+Generated MCP config uses the same distinction:
+
+```bash
+graft init --write-codex-mcp
+graft init --mcp-runtime daemon --write-codex-mcp
+```
+
+The first command emits `args = ["-y", "@flyingrobots/graft", "serve"]`.
+The second emits
+`args = ["-y", "@flyingrobots/graft", "serve", "--runtime", "daemon"]`.
+
 ## Related docs
 - [README](../README.md)
 - [Setup Guide](./SETUP.md)

package/docs/MCP.md

@@ -27,6 +27,25 @@ This is the default repo-local MCP posture. The current checkout is the
 active workspace, so there is no separate daemon authorization or
 binding step.
 
+### Daemon-backed stdio MCP
+```bash
+npx @flyingrobots/graft serve --runtime daemon
+```
+
+This keeps compatibility with MCP clients that can launch only a stdio
+command while routing MCP traffic to the local daemon `/mcp` surface.
+The bridge auto-starts the daemon when it is missing, waits for
+`/healthz`, then proxies stdio traffic to the daemon. Use
+`--no-autostart` to require an already-running daemon:
+
+```bash
+npx @flyingrobots/graft serve --runtime daemon --no-autostart
+```
+
+Daemon-backed sessions start unbound. Repository-scoped tools fail
+until the session is authorized and bound through the workspace control
+plane.
+
 ### Local Daemon
 ```bash
 npx @flyingrobots/graft daemon
@@ -43,13 +62,17 @@ flow:
 
 ## Key Tool Groups
 - **Bounded Reads**: `safe_read`, `file_outline`, `read_range`, `changed_since`
+- **Governed Edits**: `graft_edit`
 - **Structural History**: `graft_diff`, `graft_since`, `graft_map`
+- **Structural Metrics**: `graft_churn`, `graft_difficulty`
 - **Precision**: `code_show`, `code_find`, `code_refs`
 - **Activity & Footing**: `activity_view`, `causal_status`, `causal_attach`, `doctor`
 - **Daemon Control Plane**: `workspace_authorizations`, `workspace_authorize`, `workspace_bind`, `workspace_status`, `workspace_rebind`, `workspace_revoke`, `daemon_status`, `daemon_repos`, `daemon_sessions`, `daemon_monitors`, `monitor_*`
 
 ## Current Truth
 - MCP is the primary agent surface.
+- `graft serve` is repo-local stdio; `graft serve --runtime daemon` is
+  the daemon-backed stdio bridge.
 - Responses carry versioned `_schema` metadata and `_receipt` decision data.
 - `activity_view` provides bounded local `artifact_history` anchored to Git `HEAD`.
 

package/docs/SETUP.md

@@ -29,10 +29,9 @@ has a repo-local instruction layer alongside the MCP config.
 
 Idempotent — safe to run again without duplicating entries.
 
-`init` bootstraps repo-local files and client config. It does not make a
-daemon session implicitly bound later; daemon mode still requires
-explicit authorization and workspace binding through MCP control-plane
-tools.
+`init` bootstraps repo-local files and client config. The default MCP
+runtime is repo-local stdio. Use `--mcp-runtime daemon` only when you
+want generated MCP config to launch the daemon-backed stdio bridge.
 
 ## Choose Your Setup Path
 
@@ -48,9 +47,10 @@ whole setup guide front-to-back.
 | Continue MCP in this repo | `npx @flyingrobots/graft init --write-continue-mcp` | Writes or merges `.continue/config.json` |
 | Cline MCP in this repo | `npx @flyingrobots/graft init --write-cline-mcp` | Writes or merges `.vscode/cline_mcp_settings.json` |
 | Codex MCP in this repo | `npx @flyingrobots/graft init --write-codex-mcp` | Writes or merges `.codex/config.toml` and seeds `AGENTS.md` |
+| Daemon-backed MCP in this repo | `npx @flyingrobots/graft init --mcp-runtime daemon --write-*-mcp` | Writes or merges client config that launches `graft serve --runtime daemon` |
 | Manual review before any config file write | `npx @flyingrobots/graft init` | Scaffolds repo files and prints the manual MCP / hook snippets |
-| Global config instead of project-local config | Edit your client's global MCP settings manually | Use the `npx @flyingrobots/graft serve` command + args shown below |
-| Another MCP-compatible client | Add graft manually to that client's MCP config | Use `command = npx`, `args = ["-y", "@flyingrobots/graft", "serve"]` |
+| Global config instead of project-local config | Edit your client's global MCP settings manually | Use the repo-local or daemon-backed `serve` args shown below |
+| Another MCP-compatible client | Add graft manually to that client's MCP config | Use `command = npx` with either `serve` or `serve --runtime daemon` |
 
 ## Governed Read Posture By Client
 
@@ -75,8 +75,8 @@ distinct runtime paths:
   Windows named pipe, with `/mcp` for MCP traffic and `/healthz` for
   liveness
 
-The daemon is intentionally not the default editor bootstrap story yet.
-It uses a stricter contract:
+The daemon is available as an explicit opt-in MCP bootstrap runtime. It
+is not the default because it uses a stricter contract:
 
 - daemon sessions start unbound
 - workspace binding requires prior authorization through the daemon
@@ -103,14 +103,63 @@ Daemon control-plane inspection now exists through MCP tools:
 - `workspace_rebind`
 - `workspace_revoke`
 
-Practical daemon first-use sequence:
+Human operators can inspect the same read-side daemon posture without
+opening raw MCP JSON:
 
-1. start `npx @flyingrobots/graft daemon`
-2. connect your MCP client to the daemon surface
+```bash
+npx @flyingrobots/graft daemon status
+npx @flyingrobots/graft daemon status --socket /path/to/mcp.sock
+```
+
+`daemon status` is read-only. It shows daemon health, session counts,
+workspace authorization/bind posture, monitor summary, scheduler
+pressure, and worker pressure. It does not authorize, revoke, bind,
+rebind, pause, resume, start, or stop daemon resources.
+
+Practical daemon-backed MCP first-use sequence:
+
+1. configure your MCP client with `graft serve --runtime daemon`
+2. let the bridge auto-start the daemon, or start `npx @flyingrobots/graft daemon`
 3. call `workspace_authorize` with the target `cwd`
 4. call `workspace_bind` with the target `cwd`
 5. then use repository-scoped tools such as `safe_read` or `graft_map`
 
+### MCP runtime selection
+
+Repo-local stdio is the default and remains the simplest path:
+
+```json
+{
+  "mcpServers": {
+    "graft": {
+      "command": "npx",
+      "args": ["-y", "@flyingrobots/graft", "serve"]
+    }
+  }
+}
+```
+
+Daemon-backed stdio keeps the same MCP client shape but changes the
+runtime:
+
+```json
+{
+  "mcpServers": {
+    "graft": {
+      "command": "npx",
+      "args": ["-y", "@flyingrobots/graft", "serve", "--runtime", "daemon"]
+    }
+  }
+}
+```
+
+Use repo-local stdio when you want one MCP server bound directly to the
+current checkout. Use daemon-backed stdio when you want daemon-only
+capabilities such as shared worker pools, persistent monitors, and
+daemon control-plane inspection. Daemon-backed sessions start unbound;
+repository-scoped tools require `workspace_authorize` and
+`workspace_bind`.
+
 ### One-step bootstrap
 
 Write project-local client config directly when you want `init` to do
@@ -125,8 +174,20 @@ npx @flyingrobots/graft init --write-cline-mcp
 npx @flyingrobots/graft init --write-codex-mcp
 ```
 
+Add `--mcp-runtime daemon` before a `--write-*-mcp` flag to generate
+daemon-backed stdio config instead of the default repo-local stdio
+config:
+
+```bash
+npx @flyingrobots/graft init --mcp-runtime daemon --write-codex-mcp
+```
+
 Supported write flags:
 
+- `--mcp-runtime repo-local` -> generate repo-local `graft serve` MCP
+  config; this is the default
+- `--mcp-runtime daemon` -> generate `graft serve --runtime daemon` MCP
+  config
 - `--write-claude-mcp` -> writes or merges `.mcp.json`
 - `--write-claude-hooks` -> writes or merges `.claude/settings.json`
 - `--write-cursor-mcp` -> writes or merges `.cursor/mcp.json`
@@ -143,7 +204,7 @@ For automation, CLI commands support `--json`:
 
 ```bash
 npx @flyingrobots/graft init --json
-npx @flyingrobots/graft index --json
+npx @flyingrobots/graft index --path src/app.ts --json
 npx @flyingrobots/graft read safe src/app.ts --json
 npx @flyingrobots/graft struct diff --json
 npx @flyingrobots/graft symbol find 'create*' --json
@@ -155,7 +216,7 @@ Grouped CLI namespaces:
 
 - `read` — `safe`, `outline`, `range`, `changed`
 - `struct` — `diff`, `since`, `map`
-- `symbol` — `show`, `find`
+- `symbol` — `show`, `find`, `blame`, `difficulty`
 - `diag` — `activity`, `doctor`, `explain`, `stats`, `capture`
 
 ## MCP Configuration
@@ -163,6 +224,24 @@ Grouped CLI namespaces:
 Graft runs as an MCP server over stdio. Add it to your editor or
 agent's MCP configuration.
 
+The default runtime is repo-local:
+
+```bash
+npx @flyingrobots/graft serve
+```
+
+The daemon-backed runtime is explicit:
+
+```bash
+npx @flyingrobots/graft serve --runtime daemon
+```
+
+When the daemon-backed bridge cannot reach a daemon, it attempts to
+start one and waits for `/healthz`. Use `--no-autostart` when you want
+startup to fail instead of launching the daemon. Once connected,
+daemon sessions remain unbound until authorized and bound through the
+daemon workspace tools.
+
 ### Claude Code
 
 Add to `.mcp.json` in your project root (per-project) or
@@ -345,7 +424,7 @@ Add to `.claude/settings.json` in your project root:
         "hooks": [
           {
             "type": "command",
-            "command": "node --import tsx node_modules/@flyingrobots/graft/src/hooks/pretooluse-read.ts"
+            "command": "node node_modules/@flyingrobots/graft/dist/hooks/pretooluse-read.js"
           }
         ]
       }
@@ -356,7 +435,7 @@ Add to `.claude/settings.json` in your project root:
         "hooks": [
           {
             "type": "command",
-            "command": "node --import tsx node_modules/@flyingrobots/graft/src/hooks/posttooluse-read.ts"
+            "command": "node node_modules/@flyingrobots/graft/dist/hooks/posttooluse-read.js"
           }
         ]
       }
@@ -371,12 +450,16 @@ Project-local shortcut:
 npx @flyingrobots/graft init --write-claude-hooks
 ```
 
-If developing graft itself, replace the `node_modules/...` paths
-with local paths:
+Rerunning this command also upgrades generated v0.7.0 hook commands
+that pointed at `src/hooks/*.ts` to the published `dist/hooks/*.js`
+entry points.
 
-```
-src/hooks/pretooluse-read.ts    (PreToolUse)
-src/hooks/posttooluse-read.ts   (PostToolUse)
+If developing graft itself, run `pnpm build` and replace the
+`node_modules/...` paths with local paths:
+
+```text
+dist/hooks/pretooluse-read.js    (PreToolUse)
+dist/hooks/posttooluse-read.js   (PostToolUse)
 ```
 
 ### PreToolUse — ban enforcement
@@ -452,9 +535,10 @@ add to `.claude/settings.local.json`:
 | `graft_map` | Structural directory map of files and symbols under a path, with explicit denied-file reporting. |
 | `code_show` | Focus on a symbol by name and return its source with line metadata. |
 | `code_find` | Search symbols across the project by approximate name or glob pattern, with optional kind/path filter. |
+| `graft_difficulty` | Refactor difficulty score for a symbol. Combines WARP churn curvature with reference-edge friction and returns the scalar plus the underlying factors. |
 | `code_refs` | Search import sites, callsites, property access, or literal text references with explicit text-fallback provenance, pattern, and scope. |
 | `activity_view` | Bounded between-commit activity for the active workspace, including commit anchor, grouped recent activity, and degraded posture. |
-| `doctor` | Runtime health check including layered-worldline repo state and burden summary. |
+| `doctor` | Runtime health check including layered-worldline repo state and burden summary. Accepts an opt-in `sludge` scan for parser-backed structural smell signals. |
 | `stats` | Decision metrics for the current server session, including burden by tool kind. |
 | `explain` | Human-readable meaning and recommended action for a reason code. |
 | `run_capture` | Execute a shell command and return the last N lines of output (default 60). This tool is outside graft's bounded-read policy contract, responses include an explicit `policyBoundary` marker, log persistence can be disabled, and persisted output is redacted for obvious secrets by default. |
@@ -464,7 +548,7 @@ add to `.claude/settings.local.json`:
 MCP responses include versioned `_schema` metadata and `_receipt`
 fields. CLI peer commands also return versioned `_schema` metadata;
 the declared contracts live in `src/contracts/output-schemas.ts`.
-| `doctor` | Runtime health check. Shows project root, parser status, active thresholds, session depth, message count, and a compact burden summary. |
+| `doctor` | Runtime health check. Shows project root, parser status, active thresholds, session depth, message count, and a compact burden summary. With `sludge: true`, reports parser-backed structural smell signals. |
 | `set_budget` | Declare a session byte budget. Graft tightens read thresholds as the budget drains — no single read may consume more than 5% of remaining budget. Call once at session start. |
 | `explain` | Explain a graft reason code. Returns human-readable meaning and recommended next action for any code (e.g., `BINARY`, `BUDGET_CAP`). Case-insensitive. |
 | `stats` | Decision metrics for the current session. Total reads, outlines, refusals, cache hits, bytes avoided, and returned-byte burden by tool kind. |
@@ -479,8 +563,8 @@ Declared output contracts live in `src/contracts/output-schemas.ts`.
 
 ## What the agent sees
 
-Once configured, the agent gains 17 MCP tools. Here's what
-happens when it uses them:
+Once configured, the agent gains the MCP tool surface. Here's what
+happens when it uses those tools:
 
 ### Reading files
 
@@ -512,9 +596,10 @@ and its symbols (function signatures, class shapes, exports) in
 one call. Denied files are surfaced explicitly instead of silently
 disappearing.
 
-Both tools work on the current working tree. For persistent
-structural indexing across git history, use `graft index` from the
-CLI.
+Both tools work on the current working tree. Persistent structural indexing is
+lazy: use `graft index --path <path>` from the CLI to refresh one tracked source
+file at `HEAD`, or let read/search surfaces opportunistically refresh the files
+they touch. Unbounded whole-repo eager indexing is guarded.
 
 ### Structural navigation
 

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "@flyingrobots/graft",
-  "version": "0.6.1",
+  "version": "0.7.1",
   "description": "Context governor and between-commit activity surface for coding agents",
   "type": "module",
   "packageManager": "pnpm@10.30.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "sideEffects": [
+    "dist/parser/runtime.js",
+    "dist/operations/structured-buffer-model.js"
+  ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -20,7 +24,6 @@
   "files": [
     "bin/",
     "dist/",
-    "src/",
     "ADVANCED_GUIDE.md",
     "ARCHITECTURE.md",
     "CHANGELOG.md",
@@ -37,14 +40,17 @@
     "graft": "node ./bin/graft.js",
     "build": "tsc -p tsconfig.build.json",
     "prepack": "pnpm build",
-    "test": "vitest run",
+    "prepublishOnly": "pnpm release:check",
+    "test": "tsx scripts/run-isolated-tests.ts",
+    "test:local": "vitest run",
     "test:watch": "vitest",
     "lint": "eslint .",
     "typecheck": "tsc --noEmit",
     "pack:check": "pnpm pack --dry-run",
+    "guard:agent-worktrees": "tsx scripts/check-agent-worktree-hygiene.ts",
     "security:check": "tsx scripts/check-release-security.ts",
     "release:surface-gate": "vitest run --run test/unit/release/package-library-surface.test.ts test/unit/release/three-surface-capability-posture.test.ts",
-    "release:check": "pnpm lint && pnpm typecheck && pnpm release:surface-gate && pnpm test && pnpm security:check && pnpm pack:check"
+    "release:check": "pnpm guard:agent-worktrees && pnpm lint && pnpm typecheck && pnpm release:surface-gate && pnpm test && pnpm security:check && pnpm pack:check"
   },
   "engines": {
     "node": ">=20.11.0"
@@ -85,7 +91,6 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "picomatch": "^4.0.4",
     "tree-sitter-wasms": "0.1.13",
-    "tsx": "^4.21.0",
     "web-tree-sitter": "^0.20.8",
     "zod": "4.3.6"
   },
@@ -95,6 +100,7 @@
     "@types/picomatch": "^4.0.2",
     "eslint": "^10.1.0",
     "globals": "^17.4.0",
+    "tsx": "^4.21.0",
     "typescript": "^6.0.2",
     "typescript-eslint": "^8.58.0",
     "vite": "^8.0.5",
@@ -104,7 +110,8 @@
     "onlyBuiltDependencies": [],
     "overrides": {
       "vite": "^8.0.5",
-      "hono": ">=4.12.14"
+      "hono": ">=4.12.14",
+      "postcss": "8.5.12"
     }
   }
 }

package/dist/ports/warp.d.ts

@@ -1,45 +0,0 @@
-export interface WarpObserverLens {
-    readonly match: string | readonly string[];
-    readonly expose?: readonly string[] | undefined;
-    readonly redact?: readonly string[] | undefined;
-}
-export interface WarpObserverOptions {
-    readonly source?: {
-        readonly kind: "live";
-        readonly ceiling: number | null;
-    } | undefined;
-}
-export interface WarpEdge {
-    readonly from: string;
-    readonly to: string;
-    readonly label: string;
-}
-export interface WarpObserver {
-    getNodes(): Promise<string[]>;
-    getNodeProps(nodeId: string): Promise<Record<string, unknown> | null>;
-    getEdges(): Promise<readonly WarpEdge[]>;
-}
-export interface WarpPatchBuilder {
-    addNode(id: string): unknown;
-    setProperty(id: string, key: string, value: unknown): unknown;
-    addEdge(from: string, to: string, label: string): unknown;
-    removeNode(id: string): unknown;
-    removeEdge(from: string, to: string, label: string): unknown;
-}
-export interface WarpMaterializeReceiptOp {
-    readonly op: string;
-    readonly result: string;
-    readonly target: string;
-}
-export interface WarpMaterializeReceipt {
-    readonly lamport: number;
-    readonly ops: readonly WarpMaterializeReceiptOp[];
-}
-export interface WarpHandle {
-    hasNode(nodeId: string): Promise<boolean>;
-    observer(lens: WarpObserverLens, options?: WarpObserverOptions): Promise<WarpObserver>;
-    patch(build: (patch: WarpPatchBuilder) => void | Promise<void>): Promise<string>;
-    materialize(): Promise<void>;
-    materializeReceipts(): Promise<readonly WarpMaterializeReceipt[]>;
-}
-//# sourceMappingURL=warp.d.ts.map

package/dist/ports/warp.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"warp.d.ts","sourceRoot":"","sources":["../../src/ports/warp.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IAChD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CACjD;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;KACjC,GAAG,SAAS,CAAC;CACf;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC9B,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;IACtE,QAAQ,IAAI,OAAO,CAAC,SAAS,QAAQ,EAAE,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAC7B,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;IAC9D,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1D,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAChC,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC9D;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,SAAS,wBAAwB,EAAE,CAAC;CACnD;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1C,QAAQ,CAAC,IAAI,EAAE,gBAAgB,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IACvF,KAAK,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACjF,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,mBAAmB,IAAI,OAAO,CAAC,SAAS,sBAAsB,EAAE,CAAC,CAAC;CACnE"}

package/dist/ports/warp.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"warp.js","sourceRoot":"","sources":["../../src/ports/warp.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,4DAA4D;AAC5D,8EAA8E"}

package/dist/warp/identity-resolver.d.ts

@@ -1,14 +0,0 @@
-/**
- * WARP Identity Resolver — creates an IdentityResolver backed by
- * the WARP graph. Reads symbol identityId properties through the
- * observer lens system.
- */
-import type { WarpHandle } from "../ports/warp.js";
-import type { IdentityResolver } from "../operations/diff-identity.js";
-/**
- * Create an IdentityResolver that queries WARP for canonical symbol
- * identities. Each call reads the current frontier snapshot — the
- * resolver is stateless between calls.
- */
-export declare function createWarpIdentityResolver(warp: WarpHandle): IdentityResolver;
-//# sourceMappingURL=identity-resolver.d.ts.map