@izagood/avcs 0.20.0 → 0.22.0

package/dist/mcp/context.js

@@ -0,0 +1,148 @@
+// Phase 16 M3 (docs/18 §M3) — ContextPack.
+//
+// Without this an agent reconstructs its working context by hand — blame here, history
+// there, decisions somewhere else — and pays a round trip for each. context.build assembles
+// the whole picture once, under a byte budget.
+//
+// Two decisions shape it:
+//
+//  - **No content.** Symbols carry provenance and a blobOid, never the file text. Text is
+//    the one thing an agent can fetch precisely (object.show with lines/maxBytes), so
+//    spending the pack's budget on it would crowd out the things it cannot cheaply derive.
+//
+//  - **Deterministic truncation.** Section priority is fixed, ordering inside a section is
+//    fixed, and the greedy fill measures compact serialization bytes. The same input
+//    therefore yields byte-identical output — the same determinism AVCS demands of reduce,
+//    applied to context. What was dropped is recorded in `budget.truncated`, never silently
+//    missing: an agent that cannot tell a thin repo from a truncated pack will make
+//    confident decisions on partial information.
+import { keysOf } from "../reducer/reducer.js";
+/** Section fill order = priority order. Risks first: a pack that omits "someone else holds
+ *  a lease on this key" is worse than no pack, because it reads as an all-clear. History is
+ *  last because it is the most reconstructible from other tools. */
+const SECTIONS = ["risks", "decisions", "policies", "symbols", "evidence", "history", "suggestedOps"];
+export async function buildContextPack(repo, args) {
+    const view = args.view ?? "main";
+    const maxBytes = Math.max(1, Math.floor(args.maxBytes ?? 8192));
+    const keys = await resolveScope(repo, args);
+    if (!keys.length) {
+        throw new Error("context.build needs a scope: pass intentOid, entityKeys or paths. " +
+            "Refusing to pack the whole repo — an unbounded context is the problem this tool exists to solve.");
+    }
+    const res = await repo.materialize(view);
+    const [leases, policies, quarantined] = await Promise.all([
+        repo.activeLeases(),
+        repo.learnedPolicies(),
+        repo.quarantinedOps(view).catch(() => []),
+    ]);
+    const quarantinedSet = new Set(quarantined);
+    const symbols = [];
+    const decisions = [];
+    const risks = [];
+    const history = [];
+    const evidence = [];
+    for (const key of keys) {
+        const blame = await repo.blame(key, view);
+        if (blame) {
+            symbols.push({
+                key,
+                blobOid: res.tree.get(key.replace(/^file:/, "")) ?? null,
+                owner: blame.actor.id,
+                intent: blame.intentTitle ?? null,
+                purpose: blame.purpose,
+            });
+        }
+        for (const d of await repo.recallDecisions(key)) {
+            decisions.push({ key, reason: d.reason, futurePolicy: d.futurePolicy ?? null, by: d.decidedBy });
+        }
+        // Recency-first, then oid — a total order, so the greedy fill is reproducible.
+        const hist = (await repo.historyOf(key)).slice(-3).reverse();
+        for (const op of hist) {
+            history.push({ key, op: op.oid, actor: op.actor.id, purpose: op.declaredPurpose });
+            if (quarantinedSet.has(op.oid)) {
+                risks.push({ kind: "quarantine", key, detail: `op ${String(op.oid).slice(0, 16)} is quarantined pending review` });
+            }
+        }
+        for (const c of res.conflicts) {
+            if (c.key === key)
+                risks.push({ kind: "conflict", key, detail: c.reason });
+        }
+        for (const l of leases) {
+            if (l.writeScopes.some((s) => s === key)) {
+                risks.push({ kind: "lease", key, detail: `held by ${l.actor.id} until ${l.expiresAt}` });
+            }
+        }
+    }
+    // Byte sizes must be read off the same tree the pack is pinned to.
+    const files = await repo.materializedBytes(res).catch(() => []);
+    const sizeOf = new Map(files.map((f) => [f.path, f.bytes.length]));
+    for (const s of symbols)
+        s.bytes = sizeOf.get(String(s.key).replace(/^file:/, "")) ?? null;
+    // v1 is deliberately thin (docs/18 §3.1): derived from learned policies and failed
+    // evidence, not invented. A confident wrong suggestion is worse than none.
+    const suggestedOps = policies.map((p) => `learned policy: ${p}`);
+    const built = {
+        risks: dedupe(risks),
+        decisions,
+        policies,
+        symbols,
+        evidence,
+        history,
+        suggestedOps,
+    };
+    // Greedy fill in priority order over COMPACT bytes — the same serialization the transport
+    // will send, so the budget means what it says.
+    const out = { v: 1, view, treeHash: res.treeHash };
+    const truncated = [];
+    const envelopeCost = JSON.stringify({ ...out, budget: { maxBytes, usedBytes: maxBytes, truncated: SECTIONS } }).length;
+    let used = envelopeCost;
+    for (const name of SECTIONS) {
+        const cost = JSON.stringify(built[name]).length + name.length + 4;
+        if (used + cost <= maxBytes) {
+            out[name] = built[name];
+            used += cost;
+        }
+        else {
+            out[name] = [];
+            if (built[name].length)
+                truncated.push(name);
+        }
+    }
+    out.budget = { maxBytes, usedBytes: JSON.stringify(out).length, truncated };
+    return out;
+}
+/** Resolve the requested scope to entity keys, sorted for a stable fill order. */
+async function resolveScope(repo, args) {
+    const keys = new Set(args.entityKeys ?? []);
+    for (const p of args.paths ?? [])
+        keys.add(`file:${p}`);
+    if (args.intentOid) {
+        // The intent's declared scopes, plus what its sessions' ops ACTUALLY touched — the
+        // declaration is the plan, the ops are the reality, and an agent needs both.
+        const intent = await repo.readIntent(args.intentOid).catch(() => null);
+        for (const s of intent?.allowedScopes ?? [])
+            keys.add(String(s));
+        const sessions = await repo.store.collect("session");
+        const mine = new Set(sessions.filter((s) => s.intentOid === args.intentOid).map((s) => s.oid));
+        for (const op of await repo.store.collect("operation")) {
+            if (op.sessionOid && mine.has(op.sessionOid))
+                for (const k of keysOf(op))
+                    keys.add(k);
+        }
+    }
+    return [...keys].sort();
+}
+/** Stable de-dup preserving first occurrence — two sources can report the same risk. */
+function dedupe(rows) {
+    const seen = new Set();
+    const out = [];
+    for (const r of rows) {
+        const k = JSON.stringify(r);
+        if (seen.has(k))
+            continue;
+        seen.add(k);
+        out.push(r);
+    }
+    return out;
+}
+//# sourceMappingURL=context.js.map

package/dist/mcp/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/mcp/context.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAC3C,EAAE;AACF,uFAAuF;AACvF,4FAA4F;AAC5F,+CAA+C;AAC/C,EAAE;AACF,0BAA0B;AAC1B,EAAE;AACF,0FAA0F;AAC1F,sFAAsF;AACtF,2FAA2F;AAC3F,EAAE;AACF,2FAA2F;AAC3F,qFAAqF;AACrF,2FAA2F;AAC3F,4FAA4F;AAC5F,oFAAoF;AACpF,iDAAiD;AAEjD,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAY/C;;oEAEoE;AACpE,MAAM,QAAQ,GAAG,CAAC,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,cAAc,CAAU,CAAC;AAG/G,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAU,EAAE,IAAqB;IACtE,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,MAAM,CAAC;IACjC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,CAAC,CAAC;IAEhE,MAAM,IAAI,GAAG,MAAM,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC5C,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CACb,oEAAoE;YAClE,kGAAkG,CACrG,CAAC;IACJ,CAAC;IAED,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;IACzC,MAAM,CAAC,MAAM,EAAE,QAAQ,EAAE,WAAW,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QACxD,IAAI,CAAC,YAAY,EAAE;QACnB,IAAI,CAAC,eAAe,EAAE;QACtB,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAc,CAAC;KACtD,CAAC,CAAC;IACH,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,WAAW,CAAC,CAAC;IAE5C,MAAM,OAAO,GAA8B,EAAE,CAAC;IAC9C,MAAM,SAAS,GAA8B,EAAE,CAAC;IAChD,MAAM,KAAK,GAA8B,EAAE,CAAC;IAC5C,MAAM,OAAO,GAA8B,EAAE,CAAC;IAC9C,MAAM,QAAQ,GAA8B,EAAE,CAAC;IAE/C,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAC1C,IAAI,KAAK,EAAE,CAAC;YACV,OAAO,CAAC,IAAI,CAAC;gBACX,GAAG;gBACH,OAAO,EAAE,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,IAAI,IAAI;gBACxD,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,EAAE;gBACrB,MAAM,EAAE,KAAK,CAAC,WAAW,IAAI,IAAI;gBACjC,OAAO,EAAE,KAAK,CAAC,OAAO;aACvB,CAAC,CAAC;QACL,CAAC;QACD,KAAK,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC;YAChD,SAAS,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC,YAAY,IAAI,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC;QACnG,CAAC;QACD,+EAA+E;QAC/E,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;QAC7D,KAAK,MAAM,EAAE,IAAI,IAAI,EAAE,CAAC;YACtB,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,OAAO,EAAE,EAAE,CAAC,eAAe,EAAE,CAAC,CAAC;YACnF,IAAI,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC,GAAa,CAAC,EAAE,CAAC;gBACzC,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,gCAAgC,EAAE,CAAC,CAAC;YACrH,CAAC;QACH,CAAC;QACD,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;YAC9B,IAAI,CAAC,CAAC,GAAG,KAAK,GAAG;gBAAE,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;QAC7E,CAAC;QACD,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;YACvB,IAAI,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC;gBACzC,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;YAC3F,CAAC;QACH,CAAC;IACH,CAAC;IAED,mEAAmE;IACnE,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAuC,CAAC,CAAC;IACrG,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IACnE,KAAK,MAAM,CAAC,IAAI,OAAO;QAAE,CAAC,CAAC,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,IAAI,IAAI,CAAC;IAE3F,mFAAmF;IACnF,2EAA2E;IAC3E,MAAM,YAAY,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,mBAAmB,CAAC,EAAE,CAAC,CAAC;IAEjE,MAAM,KAAK,GAA+B;QACxC,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC;QACpB,SAAS;QACT,QAAQ;QACR,OAAO;QACP,QAAQ;QACR,OAAO;QACP,YAAY;KACb,CAAC;IAEF,0FAA0F;IAC1F,+CAA+C;IAC/C,MAAM,GAAG,GAA4B,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,CAAC;IAC5E,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,MAAM,YAAY,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,GAAG,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC;IACvH,IAAI,IAAI,GAAG,YAAY,CAAC;IACxB,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;QAClE,IAAI,IAAI,GAAG,IAAI,IAAI,QAAQ,EAAE,CAAC;YAC5B,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;YACxB,IAAI,IAAI,IAAI,CAAC;QACf,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;YACf,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM;gBAAE,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IACD,GAAG,CAAC,MAAM,GAAG,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC;IAC5E,OAAO,GAAG,CAAC;AACb,CAAC;AAED,kFAAkF;AAClF,KAAK,UAAU,YAAY,CAAC,IAAU,EAAE,IAAqB;IAC3D,MAAM,IAAI,GAAG,IAAI,GAAG,CAAS,IAAI,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC;IACpD,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,KAAK,IAAI,EAAE;QAAE,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IAExD,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;QACnB,mFAAmF;QACnF,6EAA6E;QAC7E,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAqB,CAAC,CAAC;QACxF,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,aAAa,IAAI,EAAE;YAAE,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QACjE,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU,SAAS,CAAC,CAAC;QAC9D,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAa,CAAC,CAAC,CAAC;QACzG,KAAK,MAAM,EAAE,IAAI,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAY,WAAW,CAAC,EAAE,CAAC;YAClE,IAAI,EAAE,CAAC,UAAU,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,UAAU,CAAC;gBAAE,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,EAAE,CAAC;oBAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACxF,CAAC;IACH,CAAC;IACD,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;AAC1B,CAAC;AAED,wFAAwF;AACxF,SAAS,MAAM,CAAC,IAA+B;IAC7C,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,GAAG,GAA8B,EAAE,CAAC;IAC1C,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,MAAM,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;QAC5B,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,SAAS;QAC1B,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACZ,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACd,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

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

@@ -1 +1 @@
-{"version":3,"file":"guide.d.ts","sourceRoot":"","sources":["../../src/mcp/guide.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAuC5E,4FAA4F;AAC5F,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAqBpF"}
+{"version":3,"file":"guide.d.ts","sourceRoot":"","sources":["../../src/mcp/guide.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAsC5E,4FAA4F;AAC5F,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAqBpF"}

package/dist/mcp/guide.js

@@ -14,12 +14,11 @@ import { RECOVERY } from "./respond.js";
  * tool that does not exist teaches the agent to fail, and unlike prose an agent would skim,
  * a step it is told to run fails for certain. A test pins this against the live table.
  *
- * Phase 16 M3 inserts `avcs.context.build` after intent.read.
  */
 const LOOP = [
     { step: 1, tool: "avcs.intent.read", why: "learn the declared goal and the scopes you may touch" },
     { step: 2, tool: "avcs.session.start", why: "bind your work to that intent under your actor identity" },
-    { step: 3, tool: "avcs.contention.check", why: "see other actors' live work on your keys before you edit, not at finalize" },
+    { step: 3, tool: "avcs.context.build", why: "get provenance, prior decisions and live risks for your scope in one bounded call" },
     { step: 4, tool: "avcs.lease.request", why: "claim the scopes you are about to write" },
     { step: 5, tool: "avcs.operation.propose", why: "submit the change as an operation; never write final files yourself" },
     { step: 6, tool: "avcs.validate.run", why: "produce evidence; a behaviour change is not acceptable without it" },

package/dist/mcp/guide.js.map

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

package/dist/mcp/prompts.d.ts

@@ -0,0 +1,15 @@
+import type { Repo } from "../api/repo.ts";
+import type { ToolDef } from "./server.ts";
+export interface PromptDef {
+    name: string;
+    description: string;
+    arguments: {
+        name: string;
+        description: string;
+        required?: boolean;
+    }[];
+}
+export declare const PROMPTS: PromptDef[];
+/** Render a prompt with its facts already resolved. Throws on an unknown name. */
+export declare function buildPrompt(repo: Repo, name: string, args: Record<string, unknown>, tools?: ToolDef[]): Promise<string>;
+//# sourceMappingURL=prompts.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../src/mcp/prompts.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;CACxE;AAED,eAAO,MAAM,OAAO,EAAE,SAAS,EA2B9B,CAAC;AAEF,kFAAkF;AAClF,wBAAsB,WAAW,CAC/B,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,KAAK,GAAE,OAAO,EAAO,GACpB,OAAO,CAAC,MAAM,CAAC,CAuDjB"}

package/dist/mcp/prompts.js

@@ -0,0 +1,89 @@
+// Phase 16 M4.2 (docs/18 §4.2) — MCP prompts.
+//
+// A prompt is a client-invocable template that arrives with its facts already inlined. The
+// point is round trips: `avcs.propose-change` carries the intent's own constraints in the
+// text, so the agent does not have to fetch them and then remember to honour them. The
+// constraint an agent never read is a constraint it will break.
+import { buildGuide } from "./guide.js";
+export const PROMPTS = [
+    {
+        name: "avcs.onboard",
+        description: "Teach the AVCS loop, rules and error recovery — the guide, inlined.",
+        arguments: [],
+    },
+    {
+        name: "avcs.propose-change",
+        description: "Draft a change under an intent, with that intent's constraints and scopes inlined.",
+        arguments: [
+            { name: "intentOid", description: "the intent to work under", required: true },
+            { name: "paths", description: "comma-separated paths you expect to touch" },
+        ],
+    },
+    {
+        name: "avcs.resolve-repair",
+        description: "Repair operations whose validation failed, with the repair packet inlined.",
+        arguments: [{ name: "ops", description: "comma-separated operation oids", required: true }],
+    },
+    {
+        name: "avcs.review-change",
+        description: "Review a checkpoint: changed paths, evidence and the view's protection, inlined.",
+        arguments: [
+            { name: "view", description: "view name; default main" },
+            { name: "checkpointOid", description: "the checkpoint under review" },
+        ],
+    },
+];
+/** Render a prompt with its facts already resolved. Throws on an unknown name. */
+export async function buildPrompt(repo, name, args, tools = []) {
+    switch (name) {
+        case "avcs.onboard":
+            return [
+                "You are working in an AVCS repository. Follow this loop and these rules.",
+                JSON.stringify(buildGuide(tools), null, 2),
+            ].join("\n\n");
+        case "avcs.propose-change": {
+            const intent = await repo.readIntent(String(args.intentOid));
+            const lines = [
+                `Intent: ${intent.title}`,
+                intent.constraints?.length ? `Constraints (do not violate):\n${intent.constraints.map((c) => `  - ${c}`).join("\n")}` : "",
+                intent.successCriteria?.length ? `Success criteria:\n${intent.successCriteria.map((c) => `  - ${c}`).join("\n")}` : "",
+                intent.allowedScopes?.length ? `Allowed scopes:\n${intent.allowedScopes.map((s) => `  - ${s}`).join("\n")}` : "",
+                typeof args.paths === "string" && args.paths ? `Paths you expect to touch: ${args.paths}` : "",
+                "",
+                "Start with avcs.context.build on this intent. Author changes with avcs.operation.propose —",
+                "never write final files yourself. Declare effects honestly. Land with avcs.sync.land.",
+            ];
+            return lines.filter(Boolean).join("\n");
+        }
+        case "avcs.resolve-repair": {
+            const ops = String(args.ops ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+            const packet = await repo.repairContext(ops);
+            return [
+                "These operations failed validation. Repair them, then re-run avcs.validate.run.",
+                JSON.stringify(packet, null, 2),
+            ].join("\n\n");
+        }
+        case "avcs.review-change": {
+            const view = typeof args.view === "string" ? args.view : "main";
+            const [protection, head, res] = await Promise.all([
+                repo.getProtection(view),
+                repo.protectedHead(view),
+                repo.materialize(view),
+            ]);
+            const cp = typeof args.checkpointOid === "string" ? args.checkpointOid : head;
+            const approvals = cp ? await repo.approvalsFor(cp) : [];
+            return [
+                `Review of view "${view}" (head ${head ?? "none"}, tree ${res.treeHash}).`,
+                `Protection: ${JSON.stringify(protection)}`,
+                `Approvals so far: ${JSON.stringify(approvals)}`,
+                `Open conflicts: ${res.conflicts.length}`,
+                "",
+                "Read the diff with avcs.diff format:patch, check evidence, then record a verdict",
+                "with avcs.approval.record.",
+            ].join("\n");
+        }
+        default:
+            throw new Error(`unknown prompt: ${name}`);
+    }
+}
+//# sourceMappingURL=prompts.js.map

package/dist/mcp/prompts.js.map

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

package/dist/mcp/resources.d.ts

@@ -0,0 +1,17 @@
+import type { Repo } from "../api/repo.ts";
+import type { ToolDef } from "./server.ts";
+export interface ResourceDef {
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: string;
+}
+/** Advertised resources. `{view}` is a template segment filled by the client. */
+export declare const RESOURCES: ResourceDef[];
+/**
+ * Read one resource. Returns the serialized body; throws on an unknown URI rather than
+ * returning an empty document — a client that asked for something that does not exist has
+ * a bug, and an empty body would read as "nothing here", which is a different fact.
+ */
+export declare function readResource(repo: Repo, uri: string, tools?: ToolDef[]): Promise<string>;
+//# sourceMappingURL=resources.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../../src/mcp/resources.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAE3C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,iFAAiF;AACjF,eAAO,MAAM,SAAS,EAAE,WAAW,EAyBlC,CAAC;AAEF;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,GAAE,OAAO,EAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAgClG"}

package/dist/mcp/resources.js

@@ -0,0 +1,80 @@
+// Phase 16 M4.1 (docs/18 §4.1) — MCP resources.
+//
+// Tools are the parameterized main path. Resources exist for one thing tools cannot do:
+// be SUBSCRIBED to. A client that subscribes to `avcs://view/main/head` is told when the
+// head moves instead of asking every few seconds.
+//
+// Every read goes through the same repo calls the equivalent tool uses, so a resource can
+// never disagree with the tool that backs it — one source of truth, two doors to it.
+import { buildGuide } from "./guide.js";
+import { buildContextPack } from "./context.js";
+import { keysOf } from "../reducer/reducer.js";
+/** Advertised resources. `{view}` is a template segment filled by the client. */
+export const RESOURCES = [
+    {
+        uri: "avcs://view/{view}/head",
+        name: "view head",
+        description: "The protected head of a view and the tree it resolves to. Subscribe to learn when it advances.",
+        mimeType: "application/json",
+    },
+    {
+        uri: "avcs://view/{view}/conflicts",
+        name: "open conflicts",
+        description: "Conflicts awaiting a human decision on a view. Subscribe to learn when one opens.",
+        mimeType: "application/json",
+    },
+    {
+        uri: "avcs://view/{view}/context",
+        name: "view context",
+        description: "A default ContextPack scoped to the keys currently in play on the view.",
+        mimeType: "application/json",
+    },
+    {
+        uri: "avcs://guide",
+        name: "guide",
+        description: "The canonical loop, agent rules, tool index and error recovery.",
+        mimeType: "application/json",
+    },
+];
+/**
+ * Read one resource. Returns the serialized body; throws on an unknown URI rather than
+ * returning an empty document — a client that asked for something that does not exist has
+ * a bug, and an empty body would read as "nothing here", which is a different fact.
+ */
+export async function readResource(repo, uri, tools = []) {
+    if (uri === "avcs://guide")
+        return JSON.stringify(buildGuide(tools));
+    const m = /^avcs:\/\/view\/([^/]+)\/(head|conflicts|context)$/.exec(uri);
+    if (!m)
+        throw new Error(`unknown resource uri: ${uri}`);
+    const view = decodeURIComponent(m[1]);
+    switch (m[2]) {
+        case "head": {
+            const [head, res] = await Promise.all([repo.protectedHead(view), repo.materialize(view)]);
+            return JSON.stringify({ view, head, treeHash: res.treeHash });
+        }
+        case "conflicts": {
+            const res = await repo.materialize(view);
+            return JSON.stringify(res.conflicts);
+        }
+        default: {
+            // context.build refuses an unscoped call by design, so a VIEW-level pack has to name
+            // its own scope: the keys actually in play — anything contended, plus what the most
+            // recent operations touched. That is the set an agent arriving at this view needs.
+            const res = await repo.materialize(view);
+            const keys = new Set(res.conflicts.map((c) => c.key));
+            const ops = await repo.store.collect("operation");
+            const recent = ops
+                .filter((o) => (o.line ?? "main") === view)
+                .sort((a, b) => a.lamport - b.lamport || String(a.oid).localeCompare(String(b.oid)))
+                .slice(-20);
+            for (const op of recent)
+                for (const k of keysOf(op))
+                    keys.add(k);
+            if (!keys.size)
+                return JSON.stringify({ v: 1, view, treeHash: res.treeHash, budget: { maxBytes: 8192, usedBytes: 0, truncated: [] }, symbols: [], decisions: [], policies: [], risks: [], evidence: [], history: [], suggestedOps: [] });
+            return JSON.stringify(await buildContextPack(repo, { entityKeys: [...keys], view, maxBytes: 8192 }));
+        }
+    }
+}
+//# sourceMappingURL=resources.js.map

package/dist/mcp/resources.js.map

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

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;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"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAuBtC,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,EAmvB1B,CAAC;AAEF;;;;;GAKG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAkLpD"}

package/dist/mcp/server.js

@@ -23,6 +23,10 @@ import { serializeResult, errorEnvelope, boundedLimit } from "./respond.js";
 import { unifiedDiff } from "../query/diff.js";
 import { buildGuide } from "./guide.js";
 import { land } from "./land.js";
+import { buildContextPack } from "./context.js";
+import { RESOURCES, readResource } from "./resources.js";
+import { PROMPTS, buildPrompt } from "./prompts.js";
+import { RepoWatcher, watchIntervalMs } from "./watch.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) {
@@ -179,6 +183,83 @@ export const TOOLS = [
         },
         handler: async (_repo, i) => buildGuide(TOOLS, typeof i.topic === "string" ? i.topic : undefined),
     },
+    {
+        // ── M4 governance/review subset (docs/18 §4.4) ──
+        name: "avcs.governance.status",
+        description: "Read-only review state for a view: protection rules, head, your role, and the effective approvals.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                view: { type: "string", description: "default 'main'" },
+                as: { type: "string", description: "actor id whose role to report" },
+                checkpointOid: { type: "string", description: "report approvals for this checkpoint instead of the head" },
+            },
+        },
+        handler: async (repo, i) => {
+            const view = i.view ?? "main";
+            const [protection, head] = await Promise.all([repo.getProtection(view), repo.protectedHead(view)]);
+            const me = i.as ?? (await repo.localActorId());
+            const target = i.checkpointOid ?? head;
+            return {
+                view,
+                protection,
+                head,
+                myRole: me ? await repo.roleOf(me) : null,
+                approvals: target ? await repo.approvalsFor(target) : [],
+            };
+        },
+    },
+    {
+        name: "avcs.approval.record",
+        description: "Record a reviewer verdict on a checkpoint, signed with the reviewer's local key. Requires role >= reviewer.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                checkpointOid: { type: "string" },
+                verdict: { type: "string", enum: ["approve", "request_changes"] },
+                by: { type: "string", description: "reviewer actor id" },
+                reason: { type: "string" },
+            },
+            required: ["checkpointOid", "by"],
+        },
+        // No human elicitation gate here, unlike decision.record: an approval is already gated
+        // downstream by role and signature, so a reviewer bot holding a key is the intended user.
+        handler: async (repo, i) => repo.approve(String(i.checkpointOid), String(i.by), i.verdict ?? "approve", typeof i.reason === "string" ? { reason: i.reason } : {}),
+    },
+    {
+        // ── M3 ContextPack (docs/18 §M3) ──
+        name: "avcs.context.build",
+        description: "Assemble working context for a scope under a byte budget: provenance, decisions, risks, history. Deterministic truncation.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                intentOid: { type: "string", description: "scope = the intent's allowed scopes plus what its sessions actually touched" },
+                entityKeys: { type: "array", items: { type: "string" }, description: "explicit keys, e.g. ['file:src/a.ts']" },
+                paths: { type: "array", items: { type: "string" }, description: "file paths, resolved to file: keys" },
+                view: { type: "string", description: "default 'main'" },
+                maxBytes: { type: "number", description: "budget for the compact response; default 8192. Dropped sections are listed in budget.truncated." },
+            },
+        },
+        handler: (repo, i) => buildContextPack(repo, {
+            intentOid: i.intentOid,
+            entityKeys: i.entityKeys,
+            paths: i.paths,
+            view: i.view,
+            maxBytes: i.maxBytes,
+        }),
+    },
+    {
+        name: "avcs.decision.recall",
+        description: "Prior human decisions for a conflict key plus the policies they taught. Read precedent before re-deciding.",
+        inputSchema: {
+            type: "object",
+            properties: { conflictKey: { type: "string", description: "entity key, e.g. 'file:src/a.ts'" } },
+        },
+        handler: async (repo, i) => ({
+            decisions: typeof i.conflictKey === "string" ? await repo.recallDecisions(i.conflictKey) : [],
+            policies: await repo.learnedPolicies(),
+        }),
+    },
     {
         // ── M2 sync surface (docs/18 §M2): an agent never pulls by hand ──
         name: "avcs.sync.pull",
@@ -850,7 +931,9 @@ export async function startMcpServer() {
         process.exit(1);
     }
     const bootVersion = readPackageVersion();
-    const server = new sdk.Server({ name: "avcs", version: bootVersion ?? "0.0.0" }, { capabilities: { tools: {} } });
+    // Phase 16 M4: resources are advertised as subscribable so a client can be TOLD the head
+    // moved instead of polling for it; prompts carry their facts pre-inlined.
+    const server = new sdk.Server({ name: "avcs", version: bootVersion ?? "0.0.0" }, { capabilities: { tools: {}, resources: { subscribe: true }, prompts: {} } });
     server.setRequestHandler(typesMod.ListToolsRequestSchema, async () => ({
         tools: TOOLS.map((t) => ({
             name: t.name,
@@ -920,12 +1003,59 @@ export async function startMcpServer() {
             },
         };
         try {
-            return await runTool(tool, repo, argsIn, ctx);
+            const out = await runTool(tool, repo, argsIn, ctx);
+            // Phase 16 M4.3: what this client authored on IS the hot set worth interrupting it
+            // for. A stdio server is one process per client, so this scope is exactly right.
+            if (!out.isError && tool.name === "avcs.operation.propose" && typeof argsIn.path === "string") {
+                watchers.get(await resolveRepoDir(callCwd, clientRoots))?.trackKeys([`file:${argsIn.path}`]);
+            }
+            return out;
         }
         finally {
             inFlight--;
         }
     });
+    // ── M4.1/4.2: resources (subscribable) and prompts ──
+    server.setRequestHandler(typesMod.ListResourcesRequestSchema, async () => ({ resources: RESOURCES }));
+    server.setRequestHandler(typesMod.ReadResourceRequestSchema, async (req) => {
+        const repo = await openRepo(undefined);
+        return { contents: [{ uri: req.params.uri, mimeType: "application/json", text: await readResource(repo, req.params.uri, TOOLS) }] };
+    });
+    server.setRequestHandler(typesMod.ListPromptsRequestSchema, async () => ({ prompts: PROMPTS }));
+    server.setRequestHandler(typesMod.GetPromptRequestSchema, async (req) => {
+        const repo = await openRepo(undefined);
+        const text = await buildPrompt(repo, req.params.name, req.params.arguments ?? {}, TOOLS);
+        return { messages: [{ role: "user", content: { type: "text", text } }] };
+    });
+    // ── M4.3: local watcher → notifications ──
+    // Polling is the correctness path (fs.watch drops events per-platform, and a missed head
+    // advance is the failure this prevents). Set AVCS_MCP_WATCH_MS=0 to disable.
+    const watchers = new Map();
+    const watchMs = watchIntervalMs();
+    if (watchMs > 0) {
+        const tick = setInterval(() => {
+            void (async () => {
+                for (const [dir, repo] of repos) {
+                    let w = watchers.get(dir);
+                    if (!w) {
+                        w = new RepoWatcher(repo);
+                        watchers.set(dir, w);
+                    }
+                    for (const ev of await w.poll()) {
+                        // Subscribed clients get the resource-updated signal; everyone else still sees
+                        // the event as a log message, so a client without subscriptions is not blind.
+                        const uri = ev.type === "head-advanced" ? `avcs://view/${ev.view}/head`
+                            : ev.type === "conflict-opened" ? `avcs://view/main/conflicts`
+                                : null;
+                        if (uri)
+                            server.notification({ method: "notifications/resources/updated", params: { uri } }).catch(() => { });
+                        server.notification({ method: "notifications/message", params: { level: "info", logger: "avcs", data: ev } }).catch(() => { });
+                    }
+                }
+            })();
+        }, watchMs);
+        tick.unref?.();
+    }
     // Reload-on-update: a long-lived stdio server holds the code it was spawned with, so
     // an `npm i -g @izagood/avcs@latest` (or any update) does not reach a running process.
     // We can't hot-swap the loaded module, so instead we watch the installed package