@izagood/avcs 0.17.0 → 0.19.0

package/dist/hub/syncWatch.js

@@ -0,0 +1,186 @@
+// Phase 15.2 (docs/17 §15.2): the live-convergence daemon behind `avcs sync --watch`.
+//
+// Loop: long-poll the hub's GET /events (the objlog cursor shared with /sync) → on a
+// wake, one incremental sync (cursor pull + redaction propagation + governance-ref
+// adoption, then push local deltas) → early conflict warning when an incoming op's keys
+// cross local work (Phase 15.3) → structured log. Network errors back off with jitter;
+// a hub without /events (pre-v4) degrades to plain periodic polling.
+//
+// Exactly ONE watcher per repo: the loop runs under the cross-process "syncd" lock,
+// kept fresh by the lock heartbeat so a live daemon is never reclaimed as stale while
+// a crashed one frees the lock via the normal stale path.
+import { keysOf } from "../reducer/reducer.js";
+/** Abortable sleep that never rejects — an abort just wakes it early. */
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve();
+            return;
+        }
+        const done = () => { clearTimeout(t); signal?.removeEventListener("abort", done); resolve(); };
+        const t = setTimeout(done, ms);
+        signal?.addEventListener("abort", done, { once: true });
+    });
+}
+/** The client side of the shared objlog cursor: what pullFromHub last recorded. */
+async function readCursor(repo, url) {
+    const raw = await repo.store.readAux("sync-cursors.json");
+    if (!raw)
+        return 0;
+    try {
+        const cursors = JSON.parse(raw.toString("utf8"));
+        return cursors[url] ?? 0;
+    }
+    catch {
+        return 0;
+    }
+}
+async function longPoll(base, since, timeoutMs, signal) {
+    const res = await fetch(`${base}/events?since=${since}&timeoutMs=${timeoutMs}`, signal ? { signal } : {});
+    if (!res.ok)
+        throw new Error(`GET /events failed: ${res.status} ${res.statusText}`);
+    return (await res.json());
+}
+/** Local protected-head refs, view → checkpoint oid. */
+async function headRefs(repo) {
+    const out = new Map();
+    for (const [name, oid] of await repo.store.listRefs()) {
+        if (name.startsWith("head:"))
+            out.set(name.slice("head:".length), oid);
+    }
+    return out;
+}
+/**
+ * Run the live-convergence loop until `opts.signal` aborts. Throws immediately when
+ * another watcher already holds this repo's "syncd" lock — one instance per repo.
+ */
+export async function runSyncWatch(repo, opts = {}) {
+    const remote = opts.remote ?? "origin";
+    const url = await repo.remoteUrl(remote);
+    try {
+        await repo.store.withLock("syncd", () => watchLoop(repo, remote, url, opts), 
+        // The heartbeat keeps the live daemon's stamp fresh; a crashed daemon stops
+        // stamping and is reclaimed after staleMs by the next starter.
+        { maxWaitMs: 100, staleMs: 60_000, heartbeatMs: 10_000 });
+    }
+    catch (e) {
+        if (/lock timeout/.test(String(e.message))) {
+            throw new Error('sync --watch is already running for this repo (lock "syncd" is held) — one watcher per repo');
+        }
+        throw e;
+    }
+}
+async function watchLoop(repo, remote, url, opts) {
+    const signal = opts.signal;
+    const timeoutMs = opts.timeoutMs ?? 30_000;
+    const minBackoff = opts.minBackoffMs ?? 500;
+    const maxBackoff = opts.maxBackoffMs ?? 30_000;
+    const emit = (ev) => {
+        repo.logger.info(`watch.${ev.type}`, ev);
+        opts.onEvent?.(ev);
+    };
+    // Capability detection: a pre-v4 hub has no /events — degrade to periodic polling.
+    let live = false;
+    try {
+        const v = (await (await fetch(`${url}/version`, signal ? { signal } : {})).json());
+        live = v.events === true;
+    }
+    catch { /* unreachable /version → the loop's error path will report and back off */ }
+    emit({ type: "started", remote, url, legacyPolling: !live });
+    let backoff = minBackoff;
+    let lastHeads = new Map();
+    // Initial full convergence — also seeds the shared objlog cursor for the long-poll.
+    try {
+        const r = await repo.sync(remote, { as: opts.as });
+        emit({ type: "synced", pulled: r.pulled, pushed: r.pushed });
+        lastHeads = await headRefs(repo);
+        for (const [view, cp] of lastHeads)
+            emit({ type: "head", view, checkpoint: cp });
+    }
+    catch (e) {
+        emit({ type: "error", error: String(e.message), backoffMs: backoff });
+        await sleep(backoff + Math.floor(Math.random() * backoff), signal);
+        backoff = Math.min(backoff * 2, maxBackoff);
+    }
+    while (!signal?.aborted) {
+        let payload = null;
+        if (live) {
+            const since = await readCursor(repo, url);
+            try {
+                payload = await longPoll(url, since, timeoutMs, signal);
+                backoff = minBackoff;
+            }
+            catch (e) {
+                if (signal?.aborted)
+                    break;
+                emit({ type: "error", error: String(e.message), backoffMs: backoff });
+                await sleep(backoff + Math.floor(Math.random() * backoff), signal);
+                backoff = Math.min(backoff * 2, maxBackoff);
+                continue;
+            }
+            // Heartbeat (nothing new, no head movement) — just park again.
+            const headsMoved = Object.entries(payload.refs).some(([name, oid]) => name.startsWith("head:") && lastHeads.get(name.slice("head:".length)) !== oid);
+            if (!payload.oids.length && !headsMoved) {
+                emit({ type: "heartbeat", cursor: payload.cursor });
+                continue;
+            }
+        }
+        else {
+            await sleep(timeoutMs, signal);
+            if (signal?.aborted)
+                break;
+        }
+        // Which of the announced oids are genuinely new HERE? Decided before the pull so
+        // the contention pass below only inspects actual arrivals (not our own echoes).
+        const incoming = [];
+        if (payload)
+            for (const oid of payload.oids)
+                if (!(await repo.store.has(oid)))
+                    incoming.push(oid);
+        try {
+            const r = await repo.sync(remote, { as: opts.as });
+            emit({ type: "synced", pulled: r.pulled, pushed: r.pushed });
+            backoff = minBackoff;
+            const heads = await headRefs(repo);
+            for (const [view, cp] of heads)
+                if (lastHeads.get(view) !== cp)
+                    emit({ type: "head", view, checkpoint: cp });
+            lastHeads = heads;
+            // Early conflict warning (Phase 15.3): an incoming op landed on a key that has
+            // live local work by someone else — "agent B's op arrived on your key K", raised
+            // at ARRIVAL time instead of at finalize. Perspective is the incoming actor's, so
+            // `theirs` is exactly the local work the arrival did not build on.
+            for (const oid of incoming) {
+                if (!(await repo.store.has(oid)))
+                    continue; // announced but not transferred (raced eviction)
+                const obj = await repo.store.get(oid);
+                if (obj.type !== "operation")
+                    continue;
+                const op = obj;
+                if (op.private)
+                    continue;
+                const warnings = await repo.contention({ keys: keysOf(op), actorId: op.actor.id, line: op.line });
+                for (const w of warnings) {
+                    if (!w.theirs.length)
+                        continue;
+                    emit({
+                        type: "contention",
+                        key: w.key,
+                        incomingOp: oid,
+                        incomingActor: op.actor.id,
+                        localOps: w.theirs.map((t) => ({ op: t.op, actor: t.actor, purpose: t.purpose })),
+                    });
+                }
+            }
+        }
+        catch (e) {
+            if (signal?.aborted)
+                break;
+            emit({ type: "error", error: String(e.message), backoffMs: backoff });
+            await sleep(backoff + Math.floor(Math.random() * backoff), signal);
+            backoff = Math.min(backoff * 2, maxBackoff);
+        }
+    }
+    emit({ type: "stopped", reason: signal?.aborted ? "aborted" : "loop-exit" });
+}
+//# sourceMappingURL=syncWatch.js.map

package/dist/hub/syncWatch.js.map

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

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { Repo } from "./api/repo.ts";
-export type { GitMode, RemoteConfig } from "./api/repo.ts";
+export type { GitMode, RemoteConfig, ContentionWarning } from "./api/repo.ts";
 export { canonicalize, computeOid, sha256hex } from "./core/canonical.ts";
 export { reduce, snapshotReduce, reduceIncremental, keysOf, conflictIdFor, detectFileConflicts } from "./reducer/reducer.ts";
 export type { ReduceInput, ReductionResult, ReduceSnapshot, Conflict, AutoDecision } from "./reducer/reducer.ts";
@@ -10,6 +10,8 @@ export { startHub, HUB_PROTOCOL_VERSION } from "./hub/hubServer.ts";
 export type { HubHandle } from "./hub/hubServer.ts";
 export { pushToHub, pullFromHub, finalizeOnHub } from "./hub/hubClient.ts";
 export type { HubSigner } from "./hub/hubClient.ts";
+export { runSyncWatch } from "./hub/syncWatch.ts";
+export type { SyncWatchEvent, SyncWatchOpts } from "./hub/syncWatch.ts";
 export { buildAuthHeader, parseAuthHeader, verifyAuth, canonicalRequest, NonceCache, AUTH_SCHEME, DEFAULT_AUTH_WINDOW_MS } from "./hub/transportAuth.ts";
 export type { AuthCredential, AuthResult, PublicKeyResolver } from "./hub/transportAuth.ts";
 export { Keyring, generateKeypair, signMessage, verifyMessage } from "./core/identity.ts";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AACrC,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAO3D,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAG1E,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC7H,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,cAAc,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAKjH,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAGtF,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACzE,YAAY,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAGzD,OAAO,EAAE,QAAQ,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AACpE,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAC3E,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAGpD,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,UAAU,EAAE,gBAAgB,EAAE,UAAU,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AACzJ,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAG5F,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAC1F,YAAY,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAGxE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAC1E,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,YAAY,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AACrC,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAO9E,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAG1E,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC7H,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,cAAc,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAKjH,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAGtF,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACzE,YAAY,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAGzD,OAAO,EAAE,QAAQ,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AACpE,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAC3E,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGxE,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,UAAU,EAAE,gBAAgB,EAAE,UAAU,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AACzJ,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAG5F,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAC1F,YAAY,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAGxE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAC1E,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,YAAY,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -23,6 +23,8 @@ export { ObjectStore, CorruptObjectError } from "./store/objectStore.js";
 // Hub (server + client) — the replication / trust boundary avcshub productionizes
 export { startHub, HUB_PROTOCOL_VERSION } from "./hub/hubServer.js";
 export { pushToHub, pullFromHub, finalizeOnHub } from "./hub/hubClient.js";
+// Live convergence (Phase 15): the sync-watch daemon behind `avcs sync --watch`.
+export { runSyncWatch } from "./hub/syncWatch.js";
 // SSH-style transport auth: embedders (e.g. a hosted hub) inject `resolvePublicKey` into
 // startHub({ auth }); these helpers also let a client build/verify the credential directly.
 export { buildAuthHeader, parseAuthHeader, verifyAuth, canonicalRequest, NonceCache, AUTH_SCHEME, DEFAULT_AUTH_WINDOW_MS } from "./hub/transportAuth.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,EAAE;AACF,mFAAmF;AACnF,yFAAyF;AACzF,wFAAwF;AACxF,iFAAiF;AAEjF,+BAA+B;AAC/B,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAGrC,mFAAmF;AACnF,uFAAuF;AACvF,sFAAsF;AACtF,wFAAwF;AACxF,6EAA6E;AAC7E,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAE1E,uEAAuE;AACvE,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAG7H,iFAAiF;AACjF,qFAAqF;AACrF,yDAAyD;AACzD,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAEtF,6BAA6B;AAC7B,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAGzE,kFAAkF;AAClF,OAAO,EAAE,QAAQ,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAEpE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAE3E,yFAAyF;AACzF,4FAA4F;AAC5F,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,UAAU,EAAE,gBAAgB,EAAE,UAAU,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAGzJ,8DAA8D;AAC9D,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAG1F,uEAAuE;AACvE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAE1E,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,EAAE;AACF,mFAAmF;AACnF,yFAAyF;AACzF,wFAAwF;AACxF,iFAAiF;AAEjF,+BAA+B;AAC/B,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAGrC,mFAAmF;AACnF,uFAAuF;AACvF,sFAAsF;AACtF,wFAAwF;AACxF,6EAA6E;AAC7E,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAE1E,uEAAuE;AACvE,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAG7H,iFAAiF;AACjF,qFAAqF;AACrF,yDAAyD;AACzD,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAEtF,6BAA6B;AAC7B,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAGzE,kFAAkF;AAClF,OAAO,EAAE,QAAQ,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAEpE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAE3E,iFAAiF;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,yFAAyF;AACzF,4FAA4F;AAC5F,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,UAAU,EAAE,gBAAgB,EAAE,UAAU,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAGzJ,8DAA8D;AAC9D,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAG1F,uEAAuE;AACvE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAE1E,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/mcp/guide.d.ts

@@ -0,0 +1,5 @@
+import type { ToolDef } from "./server.ts";
+export type GuideTopic = "workflow" | "tools" | "sync" | "rules" | "errors";
+/** Build the guide. `tools` is the live table so the index is generated, never restated. */
+export declare function buildGuide(tools: ToolDef[], topic?: string): Record<string, unknown>;
+//# sourceMappingURL=guide.d.ts.map

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

@@ -0,0 +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;AAqC5E,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

@@ -0,0 +1,67 @@
+// Phase 16 M1.3 (docs/18 §1.3) — avcs.guide: on-demand self-onboarding.
+//
+// The economics this exists for: a tool's `description` is paid on EVERY session, by every
+// agent, whether or not it needs teaching. A guide is paid only when called. So the
+// teaching moves here and descriptions shrink to identification — which nets out smaller
+// even after adding tools (§1.2's description-slimming pass is the other half of the deal).
+//
+// The hazard with any hand-written guide is drift: it describes a server that no longer
+// exists. Everything derivable is therefore GENERATED from the live tables — the tool index
+// from TOOLS, the error map from RECOVERY — so the guide cannot disagree with the server.
+import { RECOVERY } from "./respond.js";
+/**
+ * The canonical loop an agent runs. Every `tool` here must be REGISTERED — a loop naming a
+ * tool that does not exist teaches the agent to fail. Phase 16 M2/M3 insert
+ * `avcs.context.build` after intent.read and collapse the closing three steps into
+ * `avcs.sync.land`; until those ship, this is the loop that actually works.
+ */
+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: 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" },
+    { step: 7, tool: "avcs.evidence.attach", why: "bind that evidence to the ops it justifies" },
+    { step: 8, tool: "avcs.view.materialize", why: "check the work actually merges, and read any open conflicts" },
+    { step: 9, tool: "avcs.checkpoint.create", why: "package the accepted state for submission" },
+    { step: 10, tool: "avcs.integration.submit", why: "land it; the queue re-reduces for you, so you are never told to pull and redo" },
+];
+/** The agent obligations from docs/06, in a form a machine can carry in a system prompt. */
+const RULES = [
+    "Never write final files directly — submit avcs.operation.propose.",
+    "Declare effects (changesBehavior / breaksPublicApi) honestly.",
+    "A behaviour change cannot be accepted without passing-test evidence.",
+    "On a conflict, produce options for a human; do not silently overwrite.",
+    "Stay inside the intent's allowed scopes; widen the intent instead of exceeding it.",
+    "Read a failure's nextActions and follow them; do not improvise recovery from the message text.",
+];
+const SYNC = [
+    "avcs.integration.submit lands work; a moved head is re-reduced for you, not bounced back.",
+    "avcs.integration.status re-reads a ticket; the verdict is advanced | conflict | needs_evidence | queued.",
+    "A conflict verdict needs a human decision — avcs.conflict.list then avcs.decision.record.",
+];
+/** Build the guide. `tools` is the live table so the index is generated, never restated. */
+export function buildGuide(tools, topic) {
+    const base = { v: 1 };
+    switch (topic) {
+        case "tools":
+            // One line per tool, straight off the server's own table.
+            return { ...base, tools: tools.map((t) => ({ name: t.name, description: t.description })) };
+        case "rules":
+            return { ...base, rules: RULES };
+        case "sync":
+            return { ...base, sync: SYNC };
+        case "errors":
+            return {
+                ...base,
+                errors: RECOVERY.map((r) => ({ when: r.re.source, hint: r.hint, nextActions: r.nextActions })),
+            };
+        case "workflow":
+        default:
+            // No topic (or an unknown one) answers with the canonical loop rather than erroring:
+            // an agent guessing a topic name should still get the thing it most likely wanted.
+            return { ...base, loop: LOOP, rules: RULES, topics: ["workflow", "tools", "sync", "rules", "errors"] };
+    }
+}
+//# sourceMappingURL=guide.js.map

package/dist/mcp/guide.js.map

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

package/dist/mcp/respond.d.ts

@@ -0,0 +1,32 @@
+/** The serialized form of a failed tool call. `nextActions` are tool calls or commands, in
+ *  the order worth trying; absent when the failure class is unrecognized (never invented). */
+export interface ErrorEnvelope {
+    error: string;
+    hint?: string;
+    nextActions?: string[];
+}
+/** A known failure class and the way out of it. */
+export interface RecoveryRule {
+    re: RegExp;
+    hint?: string;
+    nextActions: string[];
+}
+/**
+ * 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 declare const RECOVERY: RecoveryRule[];
+/**
+ * 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 declare function boundedLimit(raw: unknown, fallback: number): number;
+/** Serialize a successful tool result. Compact unless a human asked for readability. */
+export declare function serializeResult(result: unknown, opts?: {
+    verbose?: boolean;
+}): string;
+/** Translate a thrown value into the failure envelope the transport sends. */
+export declare function errorEnvelope(e: unknown): ErrorEnvelope;
+//# sourceMappingURL=respond.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"respond.d.ts","sourceRoot":"","sources":["../../src/mcp/respond.ts"],"names":[],"mappings":"AAcA;8FAC8F;AAC9F,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,mDAAmD;AACnD,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;;GAIG;AACH,eAAO,MAAM,QAAQ,EAAE,YAAY,EAiClC,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGnE;AAED,wFAAwF;AACxF,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,CAErF;AAED,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,GAAG,aAAa,CAKvD"}

package/dist/mcp/respond.js

@@ -0,0 +1,74 @@
+// 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 Phase 14 integration queue exists precisely so a submit is never told to pull
+        // and redo; naming it turns the one error an agent used to flail on into a call.
+        re: /head moved|not up to date|stale (parent|head)/i,
+        hint: "the view's head advanced while you worked; the integration queue re-reduces for you",
+        nextActions: ["avcs.integration.submit", "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,oFAAoF;QACpF,iFAAiF;QACjF,EAAE,EAAE,gDAAgD;QACpD,IAAI,EAAE,qFAAqF;QAC3F,WAAW,EAAE,CAAC,yBAAyB,EAAE,yBAAyB,CAAC;KACpE;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,EAuc1B,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;AAMtC,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,EAqkB1B,CAAC;AAEF;;;;;GAKG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CA6HpD"}