@izagood/avcs 0.18.0 → 0.20.0

package/dist/mcp/respond.js

@@ -0,0 +1,75 @@
+// Phase 16 M1.1 (docs/18 §1.1) — the MCP response layer.
+//
+// Tokens are a budget (docs/18 §2 principle 2). Two consequences live here:
+//
+//  - Serialization is COMPACT by default. Pretty-printing costs indentation tokens on
+//    every call an agent ever makes, for a reader that is not human. `verbose` restores
+//    it for the times a person is actually looking.
+//  - Every failure becomes a machine-readable envelope carrying `nextActions`, so an
+//    agent recovers by following a list instead of parsing prose and flailing (§1 gap 6).
+//
+// What this layer deliberately does NOT do: wrap success shapes. Existing consumers and
+// tests parse the raw shape, so compatibility is absolute — additive fields only
+// (§2 principle 1, and the second recorded risk in §5).
+/**
+ * Known failure classes → what to do about them. Every dotted `avcs.*` name here must be a
+ * REGISTERED tool — a hint pointing at a tool that does not exist is worse than prose,
+ * because the agent follows it and fails. A test pins this against the live tool list.
+ */
+export const RECOVERY = [
+    {
+        // The one error an agent used to flail on becomes a single call: land re-pushes,
+        // re-checks the merge, re-checkpoints and re-integrates, and the queue behind it
+        // re-reduces the frontier union rather than bouncing the submission back.
+        re: /head moved|not up to date|stale (parent|head)/i,
+        hint: "the view's head advanced while you worked; landing absorbs that for you",
+        nextActions: ["avcs.sync.land", "avcs.integration.status"],
+    },
+    {
+        re: /no local signing key|signing key|keystore/i,
+        hint: "this action must be signed by an actor key held locally",
+        nextActions: ["avcs key provision <actor-id>", "avcs key ls"],
+    },
+    {
+        re: /not an AVCS repo|no \.avcs/i,
+        hint: "the resolved directory has no .avcs/ at or above it",
+        nextActions: ["pass cwd: <repo dir> with the call", "avcs init <dir>"],
+    },
+    {
+        re: /open conflict|conflicts? remain|unresolved conflict/i,
+        hint: "a human decision is required; do not retry through it",
+        nextActions: ["avcs.conflict.list", "avcs.decision.record"],
+    },
+    {
+        re: /lease|held by/i,
+        hint: "another actor holds a write lease overlapping your scope",
+        nextActions: ["avcs.contention.check", "avcs.lease.request"],
+    },
+    {
+        re: /validation failed|checks? failed|evidence/i,
+        hint: "the gate wants passing evidence bound to this tree",
+        nextActions: ["avcs.validate.run", "avcs.evidence.attach", "avcs.repair.context"],
+    },
+];
+/**
+ * Normalize a caller-supplied limit against a default (Phase 16 M1.2). A missing, negative,
+ * zero, or non-finite value falls back to the default rather than returning nothing or
+ * everything — an unbounded read is the failure mode this layer exists to prevent.
+ */
+export function boundedLimit(raw, fallback) {
+    const n = typeof raw === "number" ? raw : Number(raw);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback;
+}
+/** Serialize a successful tool result. Compact unless a human asked for readability. */
+export function serializeResult(result, opts) {
+    return opts?.verbose ? JSON.stringify(result, null, 2) : JSON.stringify(result);
+}
+/** Translate a thrown value into the failure envelope the transport sends. */
+export function errorEnvelope(e) {
+    const error = e instanceof Error ? e.message : String(e);
+    const rule = RECOVERY.find((r) => r.re.test(error));
+    if (!rule)
+        return { error };
+    return { error, hint: rule.hint, nextActions: rule.nextActions };
+}
+//# sourceMappingURL=respond.js.map

package/dist/mcp/respond.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"respond.js","sourceRoot":"","sources":["../../src/mcp/respond.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,EAAE;AACF,4EAA4E;AAC5E,EAAE;AACF,sFAAsF;AACtF,wFAAwF;AACxF,oDAAoD;AACpD,qFAAqF;AACrF,0FAA0F;AAC1F,EAAE;AACF,wFAAwF;AACxF,iFAAiF;AACjF,wDAAwD;AAiBxD;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAmB;IACtC;QACE,iFAAiF;QACjF,iFAAiF;QACjF,0EAA0E;QAC1E,EAAE,EAAE,gDAAgD;QACpD,IAAI,EAAE,yEAAyE;QAC/E,WAAW,EAAE,CAAC,gBAAgB,EAAE,yBAAyB,CAAC;KAC3D;IACD;QACE,EAAE,EAAE,4CAA4C;QAChD,IAAI,EAAE,yDAAyD;QAC/D,WAAW,EAAE,CAAC,+BAA+B,EAAE,aAAa,CAAC;KAC9D;IACD;QACE,EAAE,EAAE,6BAA6B;QACjC,IAAI,EAAE,qDAAqD;QAC3D,WAAW,EAAE,CAAC,oCAAoC,EAAE,iBAAiB,CAAC;KACvE;IACD;QACE,EAAE,EAAE,sDAAsD;QAC1D,IAAI,EAAE,uDAAuD;QAC7D,WAAW,EAAE,CAAC,oBAAoB,EAAE,sBAAsB,CAAC;KAC5D;IACD;QACE,EAAE,EAAE,gBAAgB;QACpB,IAAI,EAAE,0DAA0D;QAChE,WAAW,EAAE,CAAC,uBAAuB,EAAE,oBAAoB,CAAC;KAC7D;IACD;QACE,EAAE,EAAE,4CAA4C;QAChD,IAAI,EAAE,oDAAoD;QAC1D,WAAW,EAAE,CAAC,mBAAmB,EAAE,sBAAsB,EAAE,qBAAqB,CAAC;KAClF;CACF,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,GAAY,EAAE,QAAgB;IACzD,MAAM,CAAC,GAAG,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACtD,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;AAChE,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,eAAe,CAAC,MAAe,EAAE,IAA4B;IAC3E,OAAO,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;AAClF,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,aAAa,CAAC,CAAU;IACtC,MAAM,KAAK,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IACzD,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACpD,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC5B,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC;AACnE,CAAC"}

package/dist/mcp/server.d.ts

@@ -17,6 +17,25 @@ export interface ToolDef {
     handler: (repo: Repo, input: Record<string, unknown>, ctx?: ToolCtx) => Promise<unknown>;
 }
 export declare function actorOf(input: Record<string, unknown>): Actor;
+/** The schema advertised to clients: the tool's own inputs plus the universal `cwd` and
+ *  `verbose`. Returns a fresh object — the ToolDef's own schema is never mutated. */
+export declare function advertisedSchema(t: ToolDef): Record<string, unknown>;
+/**
+ * Run one tool call and render it for the transport (Phase 16 M1.1, docs/18 §1.1).
+ * Exported so the layer is testable without booting the SDK, the same way the handlers are.
+ *
+ * Success keeps its raw shape — only the serialization changes (§2 principle 1). Failure
+ * becomes `{ error, hint?, nextActions? }` so the agent recovers from a list instead of
+ * parsing prose; it is returned with `isError`, not thrown, because a thrown error reaches
+ * the agent as an opaque transport failure and loses the recovery hints entirely.
+ */
+export declare function runTool(tool: ToolDef, repo: Repo, args: Record<string, unknown>, ctx?: ToolCtx): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: boolean;
+}>;
 /**
  * Resolve which AVCS repo a tool call targets, returning its `.avcs` root dir.
  *

package/dist/mcp/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAGtC,OAAO,KAAK,EAAE,KAAK,EAAmB,MAAM,qBAAqB,CAAC;AAuBlE,8EAA8E;AAC9E,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,wFAAwF;AACxF,MAAM,WAAW,OAAO;IACtB,kEAAkE;IAClE,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;CAChG;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,OAAO,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1F;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,CAG7D;AAuBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,SAAS,EAAE,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC,GACjC,OAAO,CAAC,MAAM,CAAC,CA4BjB;AAED,eAAO,MAAM,KAAK,EAAE,OAAO,EAke1B,CAAC;AAEF;;;;;GAKG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAiIpD"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAmBtC,OAAO,KAAK,EAAE,KAAK,EAAmB,MAAM,qBAAqB,CAAC;AAuBlE,8EAA8E;AAC9E,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,wFAAwF;AACxF,MAAM,WAAW,OAAO;IACtB,kEAAkE;IAClE,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;CAChG;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,OAAO,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1F;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,CAG7D;AA+BD;qFACqF;AACrF,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASpE;AAED;;;;;;;;GAQG;AACH,wBAAsB,OAAO,CAC3B,IAAI,EAAE,OAAO,EACb,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,CAAC,EAAE,OAAO,GACZ,OAAO,CAAC;IAAE,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC,CAQ3E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,SAAS,EAAE,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC,GACjC,OAAO,CAAC,MAAM,CAAC,CA4BjB;AAED,eAAO,MAAM,KAAK,EAAE,OAAO,EA+pB1B,CAAC;AAEF;;;;;GAKG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CA6HpD"}

package/dist/mcp/server.js

@@ -19,6 +19,23 @@ import { dirname, join } from "node:path";
 import { Repo } from "../api/repo.js";
 import { isBinary } from "../core/bytes.js";
 import { ObjectStore } from "../store/objectStore.js";
+import { serializeResult, errorEnvelope, boundedLimit } from "./respond.js";
+import { unifiedDiff } from "../query/diff.js";
+import { buildGuide } from "./guide.js";
+import { land } from "./land.js";
+/** The hub's governance refs (`head:<view>`, policy, …). Empty when unreachable — a head
+ *  comparison is informational, so a dead hub degrades the answer instead of failing it. */
+async function fetchHubRefs(url) {
+    try {
+        const res = await fetch(`${url.replace(/\/$/, "")}/refs`);
+        if (!res.ok)
+            return {};
+        return (await res.json()).refs ?? {};
+    }
+    catch {
+        return {};
+    }
+}
 /**
  * Read the installed package version off disk. Works for both the type-stripped
  * source layout (src/mcp/server.ts) and the built layout (dist/mcp/server.js):
@@ -61,6 +78,44 @@ const cwdSchema = {
         "owning AVCS repo (.avcs). Optional — defaults to the client's workspace root, then the " +
         "server's own cwd. Ignored when the server is pinned via AVCS_REPO.",
 };
+/** Universal formatting switch (Phase 16 M1.1). Responses are compact by default because
+ *  indentation is whitespace the agent pays for on every call; this restores pretty-print
+ *  for the times a human is reading. Consumed by the dispatch layer, never by a handler. */
+const verboseSchema = {
+    type: "boolean",
+    description: "Pretty-print the response for human reading. Default false (compact, fewer tokens).",
+};
+/** The schema advertised to clients: the tool's own inputs plus the universal `cwd` and
+ *  `verbose`. Returns a fresh object — the ToolDef's own schema is never mutated. */
+export function advertisedSchema(t) {
+    return {
+        ...t.inputSchema,
+        properties: {
+            ...(t.inputSchema.properties ?? {}),
+            cwd: cwdSchema,
+            verbose: verboseSchema,
+        },
+    };
+}
+/**
+ * Run one tool call and render it for the transport (Phase 16 M1.1, docs/18 §1.1).
+ * Exported so the layer is testable without booting the SDK, the same way the handlers are.
+ *
+ * Success keeps its raw shape — only the serialization changes (§2 principle 1). Failure
+ * becomes `{ error, hint?, nextActions? }` so the agent recovers from a list instead of
+ * parsing prose; it is returned with `isError`, not thrown, because a thrown error reaches
+ * the agent as an opaque transport failure and loses the recovery hints entirely.
+ */
+export async function runTool(tool, repo, args, ctx) {
+    const verbose = args.verbose === true;
+    try {
+        const result = await tool.handler(repo, args, ctx);
+        return { content: [{ type: "text", text: serializeResult(result, { verbose }) }] };
+    }
+    catch (e) {
+        return { content: [{ type: "text", text: serializeResult(errorEnvelope(e), { verbose }) }], isError: true };
+    }
+}
 /**
  * Resolve which AVCS repo a tool call targets, returning its `.avcs` root dir.
  *
@@ -108,6 +163,113 @@ export async function resolveRepoDir(callCwd, listRoots) {
         "or run `avcs init`.");
 }
 export const TOOLS = [
+    {
+        // First in the list on purpose: it is the tool that explains the rest.
+        name: "avcs.guide",
+        description: "How to use AVCS: the canonical loop, agent rules, tool index, error recovery. Call this first.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                topic: {
+                    type: "string",
+                    enum: ["workflow", "tools", "sync", "rules", "errors"],
+                    description: "omit for the canonical loop",
+                },
+            },
+        },
+        handler: async (_repo, i) => buildGuide(TOOLS, typeof i.topic === "string" ? i.topic : undefined),
+    },
+    {
+        // ── M2 sync surface (docs/18 §M2): an agent never pulls by hand ──
+        name: "avcs.sync.pull",
+        description: "Pull objects from the hub (conflict-free gossip). dryRun reports what would arrive without importing.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                hub: { type: "string", description: "remote name or hub URL; default the persisted 'origin'" },
+                dryRun: { type: "boolean", description: "report the would-pull count and head comparison, import nothing" },
+            },
+        },
+        handler: async (repo, i) => {
+            const remote = typeof i.hub === "string" ? i.hub : "origin";
+            const url = await repo.remoteUrl(remote);
+            const hubRefs = await fetchHubRefs(url);
+            const view = "main";
+            const hubHead = hubRefs[`head:${view}`] ?? null;
+            if (i.dryRun === true) {
+                // Count what the hub holds and we lack, without importing any of it.
+                const have = (await (await fetch(`${url}/have`)).json());
+                let missing = 0;
+                for (const oid of have)
+                    if (!(await repo.store.has(oid)))
+                        missing++;
+                const local = await repo.protectedHead(view);
+                return { pulled: missing, dryRun: true, head: { local, hub: hubHead }, converged: local === hubHead };
+            }
+            const { pulled } = await repo.pullHub(url);
+            const local = await repo.protectedHead(view);
+            return { pulled, head: { local, hub: hubHead }, converged: local === hubHead };
+        },
+    },
+    {
+        name: "avcs.sync.push",
+        description: "Push local objects to the hub. Returns how many were accepted and how many the gate rejected.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                hub: { type: "string", description: "remote name or hub URL; default the persisted 'origin'" },
+                as: { type: "string", description: "actor id whose key signs the writes" },
+            },
+        },
+        handler: async (repo, i) => {
+            const url = await repo.remoteUrl(typeof i.hub === "string" ? i.hub : "origin");
+            return repo.pushHub(url, typeof i.as === "string" ? { as: i.as } : undefined);
+        },
+    },
+    {
+        name: "avcs.sync.land",
+        description: "Land work on a protected head in one call: push, merge-check, checkpoint, integrate. Result is landed or a conflict packet.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                view: { type: "string", description: "default 'main'" },
+                summary: { type: "string", description: "checkpoint summary" },
+                by: { type: "string", description: "actor id landing the work" },
+                hub: { type: "string", description: "remote name or hub URL; omit for the persisted 'origin', or a local-only repo" },
+                maxAttempts: { type: "number", description: "bounded contention retries; default 5. Conflicts are never retried." },
+                workspace: { type: "string", description: "land this workspace onto the base line first" },
+            },
+            required: ["by"],
+        },
+        handler: (repo, i) => land(repo, {
+            view: i.view,
+            summary: i.summary,
+            by: String(i.by),
+            hub: i.hub,
+            maxAttempts: i.maxAttempts,
+            workspace: i.workspace,
+        }),
+    },
+    {
+        name: "avcs.workspace.project",
+        description: "Write a view to a directory on disk, so build/test loops outside validate.run need no CLI.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                out: { type: "string", description: "absolute target directory" },
+                view: { type: "string", description: "default 'main'" },
+                name: { type: "string", description: "project this workspace's isolated ops too" },
+            },
+            required: ["out"],
+        },
+        handler: async (repo, i) => {
+            const view = i.view ?? "main";
+            const workspace = typeof i.name === "string" ? i.name : undefined;
+            const files = await repo.checkoutInto(String(i.out), view, workspace ? { workspace } : undefined);
+            const res = await repo.materialize(view, workspace ? { workspace } : undefined);
+            return { dir: String(i.out), fileCount: files.length, treeHash: res.treeHash };
+        },
+    },
     {
         name: "avcs.intent.create",
         description: "Open an intent: the goal + constraints + allowed scopes for a unit of work. Agents must work within an intent.",
@@ -134,9 +296,12 @@ export const TOOLS = [
     },
     {
         name: "avcs.intent.list",
-        description: "List all intents in the repo.",
-        inputSchema: { type: "object", properties: {} },
-        handler: (repo) => repo.listIntents(),
+        description: "List intents in the repo. Bounded: limit (default 50).",
+        inputSchema: {
+            type: "object",
+            properties: { limit: { type: "number", description: "max intents to return; default 50" } },
+        },
+        handler: async (repo, i) => (await repo.listIntents()).slice(0, boundedLimit(i.limit, 50)),
     },
     {
         name: "avcs.session.start",
@@ -155,7 +320,7 @@ export const TOOLS = [
     },
     {
         name: "avcs.operation.propose",
-        description: "Propose a semantic change. MVP supports file writes. DECLARE EFFECTS honestly (changesBehavior, breaksPublicApi) — policy gates on them. Pass baseText or baseBlobOid to author a base-relative edit_file (3-way-mergeable with concurrent edits); omit both for a whole-file put_file.",
+        description: "Propose a semantic change (MVP: file writes). Declare effects honestly — policy gates on them. baseText/baseBlobOid authors a 3-way-mergeable edit_file.",
         inputSchema: {
             type: "object",
             properties: {
@@ -215,7 +380,7 @@ export const TOOLS = [
     },
     {
         name: "avcs.contention.check",
-        description: "Early conflict warning (Phase 15.3): for each entity key, other actors' LIVE concurrent operations (outside your causal closure, not rejected, not superseded) and active lease holders whose scope overlaps. Check BEFORE/WHILE editing so overlap is discovered at authoring time, not at finalize. Perspective: pass sessionOid (its actor + ops), or actor (all their keys), or explicit keys.",
+        description: "Other actors' live concurrent ops and overlapping lease holders for given keys. Run while editing, so overlap surfaces before finalize.",
         inputSchema: {
             type: "object",
             properties: {
@@ -234,7 +399,7 @@ export const TOOLS = [
     },
     {
         name: "avcs.workspace.land",
-        description: "Land a workspace onto its base line (docs/16): its isolated ops join the base view and merge there via the normal 3-way reduce — disjoint edits auto-merge, overlaps surface as conflicts. Idempotent. Returns the current landed set.",
+        description: "Land a workspace onto its base line: its isolated ops join the base view and merge there. Idempotent.",
         inputSchema: { type: "object", properties: { name: { type: "string" } }, required: ["name"] },
         handler: async (repo, i) => {
             await repo.landWorkspace(String(i.name));
@@ -249,7 +414,7 @@ export const TOOLS = [
     },
     {
         name: "avcs.line.create",
-        description: "Fork a long-lived line (e.g. 'v1.x') from another line at its current state. The new line inherits history up to the fork and then diverges — same entity can hold different content per line with no conflict (Phase 8).",
+        description: "Fork a long-lived line (e.g. 'v1.x') from another at its current state. It inherits history to the fork, then diverges.",
         inputSchema: {
             type: "object",
             properties: { name: { type: "string" }, fromLine: { type: "string" }, atCheckpointOid: { type: "string" } },
@@ -265,7 +430,7 @@ export const TOOLS = [
     },
     {
         name: "avcs.operation.backport",
-        description: "Port (cherry-pick / backport) an operation onto another line: mints a new op on the target line carrying the source's change, with derivedFrom provenance. Does not affect the source line.",
+        description: "Cherry-pick an operation onto another line: mints a new op carrying the change, with derivedFrom provenance. Source line untouched.",
         inputSchema: {
             type: "object",
             properties: { sourceOpOid: { type: "string" }, targetLine: { type: "string" }, actor: actorSchema },
@@ -304,7 +469,7 @@ export const TOOLS = [
     },
     {
         name: "avcs.view.materialize",
-        description: "Reduce the operation graph for a view into a code tree + per-op status + open conflicts. This is how an agent checks whether its work merges. Pass includeStatuses (e.g. ['accepted','needs_decision']) to ALSO project gated/pending ops so their computed 3-way merge can be inspected before acceptance; `dropped` lists ops NOT in the tree (status outside includeStatuses) so omissions are never silent (issue #13).",
+        description: "Reduce a view's operation graph into a tree, per-op status and open conflicts — how an agent checks that its work merges.",
         inputSchema: {
             type: "object",
             properties: {
@@ -314,6 +479,8 @@ export const TOOLS = [
                     items: { type: "string", enum: ["proposed", "validating", "accepted", "rejected", "superseded", "needs_decision", "quarantined"] },
                     description: "op statuses to project into the tree; default ['accepted']",
                 },
+                filesLimit: { type: "number", description: "max paths to list; default 500. treeHash/status/conflicts/dropped are never bounded." },
+                pathsOnlyUnder: { type: "string", description: "list only paths under this prefix (e.g. 'src/')" },
             },
         },
         handler: async (repo, i) => {
@@ -328,9 +495,16 @@ export const TOOLS = [
             const dropped = Object.entries(status)
                 .filter(([, s]) => !projected.has(s))
                 .map(([oid, s]) => ({ oid, status: s }));
+            // Only the FILE LISTING is bounded (Phase 16 M1.2). treeHash, status, conflicts and
+            // dropped are correctness data — bounding them would make a wrong answer look right.
+            const under = typeof i.pathsOnlyUnder === "string" ? i.pathsOnlyUnder : undefined;
+            const all = [...res.tree.keys()].sort().filter((p) => (under ? p.startsWith(under) : true));
+            const filesLimit = boundedLimit(i.filesLimit, 500);
             return {
                 treeHash: res.treeHash,
-                files: [...res.tree.keys()].sort(),
+                files: all.slice(0, filesLimit),
+                filesTotal: all.length,
+                filesTruncated: all.length > filesLimit,
                 status,
                 conflicts: res.conflicts,
                 dropped,
@@ -345,7 +519,7 @@ export const TOOLS = [
     },
     {
         name: "avcs.decision.record",
-        description: "Record a HUMAN/owner resolution of a conflict. Chosen ops are accepted, rejected ops dropped — and the rationale becomes reusable history. The agent CANNOT forge this: the owner is asked to confirm via MCP elicitation, and the decision is then signed with the owner's LOCAL private key (which the agent never holds). Unsigned/forged decisions are dropped by the reducer's trust gate (issue #15). Requires actor.kind 'human', an elicitation-capable client, and a provisioned local owner key.",
+        description: "Record a human owner's conflict resolution. Owner-confirmed and signed with their local key; an agent cannot forge it.",
         inputSchema: {
             type: "object",
             properties: {
@@ -401,7 +575,7 @@ export const TOOLS = [
     },
     {
         name: "avcs.integration.submit",
-        description: "Submit a draft checkpoint to a remote hub's integration queue (Phase 14, docs/17). NEVER pull-and-redo: the result is always a verdict to act on — `advanced` (done: the hub re-reduced the frontier union and moved the head), `conflict` (a minimal repair packet with counterpart ops + prior decisions: decide via avcs.decision.record, then resubmit), `needs_evidence` (run avcs.validate.run ONCE against the returned integrated tree — the needed delta objects were already pulled — attach evidence, resubmit the SAME ticketId), `queued` (retry after retryAfterMs), or `rejected` (hard gate). Omit `checkpoint` to checkpoint the view automatically.",
+        description: "Submit a checkpoint to the integration queue. Verdict is advanced, conflict, needs_evidence or queued — never 'pull and redo'.",
         inputSchema: {
             type: "object",
             properties: {
@@ -464,7 +638,7 @@ export const TOOLS = [
     },
     {
         name: "avcs.validate.run",
-        description: "Run validation commands against a view and attach treeHash-bound Evidence (docs/16 §8). By default materializes into a fresh temp dir. Pass `dir` (e.g. your working tree, which already has the build env like node_modules) to run there without avcs owning install — the fix for Node/pnpm (issue #11); with `dir` it runs in place unless `project:true`. Use `workspace` to validate a workspace view. Evidence trusts author≠signer, so pass a ciActor distinct from the op authors.",
+        description: "Run validation commands against a view and attach treeHash-bound evidence. Pass dir to reuse an existing build environment.",
         inputSchema: {
             type: "object",
             properties: {
@@ -511,7 +685,7 @@ export const TOOLS = [
     },
     {
         name: "avcs.repair.context",
-        description: "Get a MINIMAL repair packet for ops whose validation failed (the failing output + related prior decisions + a fix instruction). Use instead of re-reading the whole repo.",
+        description: "Minimal repair packet for ops whose validation failed: failing output, related decisions, a fix instruction. Cheaper than re-reading the repo.",
         inputSchema: { type: "object", properties: { ops: { type: "array", items: { type: "string" } } }, required: ["ops"] },
         handler: (repo, i) => repo.repairContext(i.ops),
     },
@@ -529,19 +703,56 @@ export const TOOLS = [
     },
     {
         name: "avcs.history",
-        description: "History of one entity in causal order (the ops that touched a file/symbol, each with actor/intent/purpose). O(ops-on-entity) via the entity index.",
-        inputSchema: { type: "object", properties: { entityKey: { type: "string" } }, required: ["entityKey"] },
-        handler: async (repo, i) => (await repo.historyOf(String(i.entityKey))).map((o) => ({ op: o.oid, actor: o.actor.id, purpose: o.declaredPurpose, at: o.createdAt, line: o.line ?? "main" })),
+        description: "History of one entity in causal order. Paged: limit (default 20) + cursor.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                entityKey: { type: "string" },
+                limit: { type: "number", description: "max ops to return; default 20. A full page means there may be more." },
+                cursor: { type: "string", description: "opaque: the last op oid of the previous page; returns what follows it." },
+            },
+            required: ["entityKey"],
+        },
+        // Stays an ARRAY: success shapes are never wrapped (docs/18 §2 principle 1, §5), so the
+        // page-size signal is the standard "short page = end" rather than an added total field.
+        handler: async (repo, i) => {
+            const all = await repo.historyOf(String(i.entityKey));
+            const from = i.cursor ? all.findIndex((o) => o.oid === i.cursor) + 1 : 0;
+            const limit = boundedLimit(i.limit, 20);
+            return all.slice(from, from + limit).map((o) => ({ op: o.oid, actor: o.actor.id, purpose: o.declaredPurpose, at: o.createdAt, line: o.line ?? "main" }));
+        },
     },
     {
         name: "avcs.diff",
-        description: "Diff two views/lines: added/removed/modified paths.",
-        inputSchema: { type: "object", properties: { viewA: { type: "string" }, viewB: { type: "string" } }, required: ["viewA", "viewB"] },
-        handler: (repo, i) => repo.diff(String(i.viewA), String(i.viewB)),
+        description: "Diff two views/lines. format 'paths' (default) or 'patch' (unified diff).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                viewA: { type: "string" },
+                viewB: { type: "string" },
+                format: { type: "string", enum: ["paths", "patch"], description: "'paths' (default, unchanged shape) or 'patch' for unified diffs" },
+                path: { type: "string", description: "restrict a patch to this single path" },
+            },
+            required: ["viewA", "viewB"],
+        },
+        handler: async (repo, i) => {
+            const paths = await repo.diff(String(i.viewA), String(i.viewB));
+            if (i.format !== "patch")
+                return paths; // default shape is unchanged (compatibility)
+            const [a, b] = await Promise.all([repo.materialize(String(i.viewA)), repo.materialize(String(i.viewB))]);
+            const only = typeof i.path === "string" ? i.path : undefined;
+            const changed = [...paths.added, ...paths.removed, ...paths.modified].sort().filter((p) => (only ? p === only : true));
+            // Go through materializedFiles, NOT readBlob: a merged path's tree entry can be a
+            // synth oid derived from the merge result, which was never stored as a blob.
+            const [fa, fb] = await Promise.all([repo.materializedFiles(a), repo.materializedFiles(b)]);
+            const textOf = (files, p) => files.find((f) => f.path === p)?.content ?? "";
+            const patches = changed.map((p) => ({ path: p, patch: unifiedDiff(textOf(fa, p), textOf(fb, p)) }));
+            return { ...paths, patches };
+        },
     },
     {
         name: "avcs.release.cut",
-        description: "Cut a Release: a verified (conflict-free) checkpoint + its evidence + an SBOM of what shipped + artifact references. Refuses if the view has open or semantic conflicts.",
+        description: "Cut a release: a conflict-free checkpoint plus evidence, SBOM and artifact references. Refuses if the view has open conflicts.",
         inputSchema: {
             type: "object",
             properties: {
@@ -566,16 +777,51 @@ export const TOOLS = [
     },
     {
         name: "avcs.object.show",
-        description: "Read an object by oid — the MCP equivalent of CLI `show`. For a blob, returns the decoded content (utf8 `text`, or `base64` if binary); for an operation/intent/etc., the structured object. Lets a pure-MCP agent inspect another agent's authored content, or fetch a base blob to declare as baseBlobOid on an edit_file propose (issue #12).",
-        inputSchema: { type: "object", properties: { oid: { type: "string" } }, required: ["oid"] },
+        description: "Read an object by oid. Blobs return decoded content (utf8 text or base64); other types return the structured object.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                oid: { type: "string" },
+                maxBytes: { type: "number", description: "cap on returned blob content; default 65536. `bytes` always reports the FULL size." },
+                lines: {
+                    type: "object",
+                    properties: { start: { type: "number" }, end: { type: "number" } },
+                    description: "1-based inclusive line range of a text blob to return instead of the whole thing",
+                },
+            },
+            required: ["oid"],
+        },
         handler: async (repo, i) => {
             const oid = String(i.oid);
             const obj = await repo.store.get(oid);
             if (obj.type === "blob") {
                 const buf = await repo.readBlob(oid);
-                return isBinary(buf)
-                    ? { oid, kind: "blob", encoding: "base64", binary: true, bytes: buf.length, data: buf.toString("base64") }
-                    : { oid, kind: "blob", encoding: "utf8", binary: false, bytes: buf.length, text: buf.toString("utf8") };
+                const bytes = buf.length; // ALWAYS the full size, even when the payload is a slice
+                if (isBinary(buf)) {
+                    const maxBytes = boundedLimit(i.maxBytes, 65_536);
+                    const slice = buf.subarray(0, maxBytes);
+                    return { oid, kind: "blob", encoding: "base64", binary: true, bytes, truncated: bytes > maxBytes, data: slice.toString("base64") };
+                }
+                let text = buf.toString("utf8");
+                let truncated = false;
+                // A line range is the cheaper ask: slice first, then still honour maxBytes.
+                const range = i.lines;
+                if (range && (range.start !== undefined || range.end !== undefined)) {
+                    const all = text.split("\n");
+                    const trailing = text.endsWith("\n");
+                    const body = trailing ? all.slice(0, -1) : all;
+                    const start = Math.max(1, Math.floor(range.start ?? 1));
+                    const end = Math.min(body.length, Math.floor(range.end ?? body.length));
+                    const picked = body.slice(start - 1, end);
+                    truncated = picked.length < body.length;
+                    text = picked.length ? picked.join("\n") + "\n" : "";
+                }
+                const maxBytes = boundedLimit(i.maxBytes, 65_536);
+                if (Buffer.byteLength(text, "utf8") > maxBytes) {
+                    text = Buffer.from(text, "utf8").subarray(0, maxBytes).toString("utf8");
+                    truncated = true;
+                }
+                return { oid, kind: "blob", encoding: "utf8", binary: false, bytes, truncated, text };
             }
             return { oid, kind: obj.type ?? "object", object: obj };
         },
@@ -609,11 +855,8 @@ export async function startMcpServer() {
         tools: TOOLS.map((t) => ({
             name: t.name,
             description: t.description,
-            // Advertise the universal optional `cwd` so per-call repo targeting is discoverable.
-            inputSchema: {
-                ...t.inputSchema,
-                properties: { ...(t.inputSchema.properties ?? {}), cwd: cwdSchema },
-            },
+            // Advertise the universal optional `cwd` and `verbose` so both are discoverable.
+            inputSchema: advertisedSchema(t),
         })),
     }));
     // Ask the MCP client for its workspace roots (the protocol-blessed way to learn where the
@@ -677,8 +920,7 @@ export async function startMcpServer() {
             },
         };
         try {
-            const result = await tool.handler(repo, argsIn, ctx);
-            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+            return await runTool(tool, repo, argsIn, ctx);
         }
         finally {
             inFlight--;