@algosuite/vo-mcp 0.2.0-beta.28 → 0.2.0-beta.30

package/dist/cli.js

@@ -1399,13 +1399,713 @@ var init_safe_memory_file = __esm({
   }
 });
 
+// src/tools/memory/sync-lock-liveness.ts
+import { statSync as statSync4, readFileSync as readFileSync8 } from "node:fs";
+function defaultIsProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EPERM";
+  }
+}
+function toPayload(parsed) {
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+  const record = parsed;
+  const token = record["token"];
+  const host = record["hostname"];
+  if (typeof token !== "string" || token.length === 0) return null;
+  const pid = record["pid"];
+  const acquiredAtMs = record["acquiredAtMs"];
+  return {
+    pid: typeof pid === "number" && Number.isInteger(pid) && pid > 0 ? pid : 0,
+    hostname: typeof host === "string" ? host : "",
+    sessionId: typeof record["sessionId"] === "string" ? record["sessionId"] : null,
+    token,
+    acquiredAt: typeof record["acquiredAt"] === "string" ? record["acquiredAt"] : "",
+    acquiredAtMs: typeof acquiredAtMs === "number" && Number.isFinite(acquiredAtMs) ? acquiredAtMs : Number.NaN
+  };
+}
+function readLockRecord(path3) {
+  let raw;
+  try {
+    raw = readFileSync8(path3, "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    return { raw, payload: toPayload(JSON.parse(raw)) };
+  } catch {
+    return { raw, payload: null };
+  }
+}
+function lockAgeMs(record, path3, nowMs) {
+  let startedMs = Number.NaN;
+  if (record.payload) {
+    if (Number.isFinite(record.payload.acquiredAtMs)) {
+      startedMs = record.payload.acquiredAtMs;
+    } else if (record.payload.acquiredAt) {
+      startedMs = Date.parse(record.payload.acquiredAt);
+    }
+  }
+  if (!Number.isFinite(startedMs)) {
+    try {
+      startedMs = statSync4(path3).mtimeMs;
+    } catch {
+      return null;
+    }
+  }
+  const age = nowMs - startedMs;
+  return Number.isFinite(age) && age >= 0 ? age : null;
+}
+function classifyHolderLiveness(record, isProcessAlive, thisHost) {
+  const payload = record.payload;
+  if (payload === null) return "unknown";
+  if (payload.pid <= 0) return "unknown";
+  if (thisHost.length === 0) return "unknown";
+  if (payload.hostname !== thisHost) return "unknown";
+  return isProcessAlive(payload.pid) ? "alive" : "dead";
+}
+function isLockAbandoned(record, ageMs, ttlMs, isProcessAlive, thisHost) {
+  const liveness = classifyHolderLiveness(record, isProcessAlive, thisHost);
+  if (liveness === "alive") return false;
+  if (liveness === "dead") return true;
+  return ageMs !== null && ageMs > ttlMs;
+}
+var init_sync_lock_liveness = __esm({
+  "src/tools/memory/sync-lock-liveness.ts"() {
+    "use strict";
+  }
+});
+
+// src/tools/memory/sync-lock.ts
+import { closeSync as closeSync2, mkdirSync as mkdirSync5, openSync as openSync3, readFileSync as readFileSync9, unlinkSync as unlinkSync2, writeFileSync as writeFileSync4 } from "node:fs";
+import { hostname } from "node:os";
+import { join as join8 } from "node:path";
+import { randomUUID as randomUUID2 } from "node:crypto";
+function positiveOr(value, fallback) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : fallback;
+}
+function createExclusive2(path3, contents) {
+  let fd;
+  try {
+    fd = openSync3(path3, "wx");
+  } catch (err) {
+    const code = err.code;
+    return { ok: false, exists: code === "EEXIST", message: err instanceof Error ? err.message : String(err) };
+  }
+  try {
+    writeFileSync4(fd, contents, "utf8");
+  } catch (err) {
+    closeSync2(fd);
+    try {
+      unlinkSync2(path3);
+    } catch {
+    }
+    return { ok: false, exists: false, message: err instanceof Error ? err.message : String(err) };
+  }
+  closeSync2(fd);
+  return { ok: true };
+}
+function removeAbandoned(path3, expectedRaw) {
+  let current;
+  try {
+    current = readFileSync9(path3, "utf8");
+  } catch {
+    return;
+  }
+  if (current !== expectedRaw) return;
+  try {
+    unlinkSync2(path3);
+  } catch {
+  }
+}
+function makeRelease(path3, token) {
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    let raw;
+    try {
+      raw = readFileSync9(path3, "utf8");
+    } catch {
+      return;
+    }
+    let stillOurs;
+    try {
+      stillOurs = toPayload(JSON.parse(raw))?.token === token;
+    } catch {
+      stillOurs = false;
+    }
+    if (!stillOurs) return;
+    try {
+      unlinkSync2(path3);
+    } catch {
+    }
+  };
+}
+function describeHolder(record) {
+  const payload = record?.payload;
+  if (!payload) return "an unreadable lock file";
+  return `pid ${payload.pid} on ${payload.hostname || "(unknown host)"} (session ${payload.sessionId ?? "unknown"}, held since ${payload.acquiredAt || "unknown"})`;
+}
+async function acquireMemorySyncLock(options) {
+  const waitMs = positiveOr(options.waitMs, DEFAULT_LOCK_WAIT_MS);
+  const ttlMs = positiveOr(options.ttlMs, DEFAULT_LOCK_TTL_MS);
+  const now = options.now ?? Date.now;
+  const sleep = options.sleep ?? ((ms) => new Promise((resolve3) => {
+    setTimeout(resolve3, ms);
+  }));
+  const isProcessAlive = options.isProcessAlive ?? defaultIsProcessAlive;
+  const thisHost = hostname();
+  const path3 = join8(options.memoryDir, MEMORY_SYNC_LOCK_FILE);
+  if (options.createDir === true) mkdirSync5(options.memoryDir, { recursive: true });
+  const deadline = now() + waitMs;
+  let backoffMs = INITIAL_BACKOFF_MS;
+  let tookOverFrom = null;
+  let holderDescription = "another session";
+  for (; ; ) {
+    const acquiredAtMs = now();
+    const payload = {
+      pid: process.pid,
+      hostname: thisHost,
+      sessionId: options.sessionId ?? null,
+      token: randomUUID2(),
+      acquiredAt: new Date(acquiredAtMs).toISOString(),
+      acquiredAtMs
+    };
+    const created = createExclusive2(path3, `${JSON.stringify(payload, null, 2)}
+`);
+    if (created.ok) {
+      return { path: path3, payload, tookOverFrom, release: makeRelease(path3, payload.token) };
+    }
+    if (!created.exists) {
+      throw new Error(
+        `memory sync lock ${path3} could not be created (${created.message}) \u2014 refusing to sync without exclusion`
+      );
+    }
+    const record = readLockRecord(path3);
+    let reclaimed = false;
+    if (record) {
+      holderDescription = describeHolder(record);
+      const age = lockAgeMs(record, path3, now());
+      if (isLockAbandoned(record, age, ttlMs, isProcessAlive, thisHost)) {
+        tookOverFrom = record.payload;
+        removeAbandoned(path3, record.raw);
+        reclaimed = true;
+      }
+    }
+    if (now() >= deadline) {
+      throw new Error(
+        `memory sync lock ${path3} is held by ${holderDescription}; waited ${waitMs}ms \u2014 refusing to sync unlocked (concurrent memory writes corrupt the shared index). If that holder is provably gone, delete the lock file.`
+      );
+    }
+    if (reclaimed) backoffMs = INITIAL_BACKOFF_MS;
+    await sleep(Math.max(1, Math.min(backoffMs, deadline - now())));
+    if (!reclaimed) backoffMs = Math.min(MAX_BACKOFF_MS, Math.ceil(backoffMs * BACKOFF_FACTOR));
+  }
+}
+async function withMemorySyncLock(options, fn) {
+  const handle = await acquireMemorySyncLock(options);
+  try {
+    return await fn(handle);
+  } finally {
+    handle.release();
+  }
+}
+var MEMORY_SYNC_LOCK_FILE, DEFAULT_LOCK_TTL_MS, DEFAULT_LOCK_WAIT_MS, INITIAL_BACKOFF_MS, MAX_BACKOFF_MS, BACKOFF_FACTOR;
+var init_sync_lock = __esm({
+  "src/tools/memory/sync-lock.ts"() {
+    "use strict";
+    init_sync_lock_liveness();
+    init_sync_lock_liveness();
+    MEMORY_SYNC_LOCK_FILE = ".memory-sync.lock";
+    DEFAULT_LOCK_TTL_MS = 15 * 6e4;
+    DEFAULT_LOCK_WAIT_MS = 1e4;
+    INITIAL_BACKOFF_MS = 25;
+    MAX_BACKOFF_MS = 500;
+    BACKOFF_FACTOR = 1.6;
+  }
+});
+
+// src/tools/memory/memory-index-merge.ts
+function isMemoryIndexFile(fileName) {
+  return fileName.toUpperCase() === MEMORY_INDEX_FILE.toUpperCase();
+}
+function indexRowKey(line) {
+  const match = INDEX_ROW_RE.exec(line);
+  if (!match) return null;
+  let target = match[1].trim();
+  if (target.startsWith("<") && target.endsWith(">")) target = target.slice(1, -1).trim();
+  target = target.replace(/\s+(["'])[\s\S]*\1$/, "").trim();
+  if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(target)) {
+    target = target.replace(/\\/g, "/").replace(/\/{2,}/g, "/");
+    target = target.replace(/^(?:\.\/)+/, "");
+  }
+  return target.length > 0 ? target.toLowerCase() : null;
+}
+function mergeMemoryIndex(localContent, cloudContent) {
+  if (typeof cloudContent !== "string" || cloudContent.trim().length === 0) {
+    return { content: localContent, addedFromCloud: [] };
+  }
+  const eol = localContent.includes("\r\n") ? "\r\n" : "\n";
+  const localLines = localContent.split(/\r?\n/);
+  const localKeys = /* @__PURE__ */ new Set();
+  let lastLocalRowIndex = -1;
+  for (let i = 0; i < localLines.length; i++) {
+    const key = indexRowKey(localLines[i]);
+    if (key === null) continue;
+    localKeys.add(key);
+    lastLocalRowIndex = i;
+  }
+  const addedFromCloud = [];
+  const seenCloudKeys = /* @__PURE__ */ new Set();
+  for (const rawLine of cloudContent.split(/\r?\n/)) {
+    const key = indexRowKey(rawLine);
+    if (key === null) continue;
+    if (localKeys.has(key) || seenCloudKeys.has(key)) continue;
+    seenCloudKeys.add(key);
+    addedFromCloud.push(rawLine.replace(/\r$/, ""));
+  }
+  if (addedFromCloud.length === 0) {
+    return { content: localContent, addedFromCloud: [] };
+  }
+  const merged = lastLocalRowIndex >= 0 ? [...localLines.slice(0, lastLocalRowIndex + 1), ...addedFromCloud, ...localLines.slice(lastLocalRowIndex + 1)] : [...localLines, ...addedFromCloud];
+  return { content: merged.join(eol), addedFromCloud };
+}
+var MEMORY_INDEX_FILE, INDEX_ROW_RE;
+var init_memory_index_merge = __esm({
+  "src/tools/memory/memory-index-merge.ts"() {
+    "use strict";
+    MEMORY_INDEX_FILE = "MEMORY.md";
+    INDEX_ROW_RE = /^\s*[-*]\s+\[[^\]]*\]\(([^)]+)\)/;
+  }
+});
+
+// src/tools/memory/bounded-sync.ts
+function createSyncDeadline(budgetMs = SYNC_DEADLINE_MS, now = Date.now) {
+  const startedAt = now();
+  return {
+    check() {
+      const elapsed = now() - startedAt;
+      if (elapsed > budgetMs) throw new SyncDeadlineExceededError(elapsed, budgetMs);
+    },
+    remainingMs() {
+      return Math.max(0, budgetMs - (now() - startedAt));
+    }
+  };
+}
+async function withRequestTimeout(url, run, budgetMs = REQUEST_TIMEOUT_MS) {
+  let timer;
+  try {
+    return await Promise.race([
+      run(),
+      new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(new RequestTimeoutError(url, budgetMs)), budgetMs);
+        timer.unref?.();
+      })
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+async function mapWithConcurrency(items, limit, fn) {
+  const results = new Array(items.length);
+  const width = Math.max(1, Math.min(limit, items.length));
+  let next = 0;
+  async function worker() {
+    for (; ; ) {
+      const index = next++;
+      if (index >= items.length) return;
+      try {
+        results[index] = { ok: true, value: await fn(items[index], index) };
+      } catch (error) {
+        results[index] = { ok: false, error };
+      }
+    }
+  }
+  await Promise.all(Array.from({ length: width }, () => worker()));
+  return results;
+}
+var REQUEST_TIMEOUT_MS, SYNC_DEADLINE_MS, PUSH_CONCURRENCY, SyncDeadlineExceededError, RequestTimeoutError;
+var init_bounded_sync = __esm({
+  "src/tools/memory/bounded-sync.ts"() {
+    "use strict";
+    REQUEST_TIMEOUT_MS = 15e3;
+    SYNC_DEADLINE_MS = 12e4;
+    PUSH_CONCURRENCY = 6;
+    SyncDeadlineExceededError = class extends Error {
+      constructor(elapsedMs, budgetMs) {
+        super(
+          `memory sync exceeded its ${budgetMs}ms deadline after ${elapsedMs}ms \u2014 aborting so the lock is released instead of held indefinitely`
+        );
+        this.name = "SyncDeadlineExceededError";
+      }
+    };
+    RequestTimeoutError = class extends Error {
+      constructor(url, budgetMs) {
+        super(`memory sync request to ${url} exceeded ${budgetMs}ms`);
+        this.name = "RequestTimeoutError";
+      }
+    };
+  }
+});
+
+// src/tools/memory/memory-push-cache.ts
+import { createHash as createHash3 } from "node:crypto";
+import { readFileSync as readFileSync10, writeFileSync as writeFileSync5 } from "node:fs";
+import { join as join9 } from "node:path";
+function sha256(content) {
+  return createHash3("sha256").update(content, "utf8").digest("hex");
+}
+function statePath(memoryDir) {
+  return join9(memoryDir, MEMORY_SYNC_STATE_FILE);
+}
+function readPushCache(memoryDir, controlPlaneUrl) {
+  const empty = { controlPlaneUrl, entries: /* @__PURE__ */ new Map(), knowledgeSweptAtMs: null };
+  let raw;
+  try {
+    raw = readFileSync10(statePath(memoryDir), "utf8");
+  } catch {
+    return empty;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return empty;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return empty;
+  const obj = parsed;
+  if (obj["version"] !== STATE_VERSION) return empty;
+  if (obj["controlPlaneUrl"] !== controlPlaneUrl) return empty;
+  const files = obj["entries"];
+  if (typeof files !== "object" || files === null || Array.isArray(files)) return empty;
+  const entries = /* @__PURE__ */ new Map();
+  for (const [name, value] of Object.entries(files)) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) continue;
+    const row = value;
+    const memoryHash = typeof row["memoryHash"] === "string" ? row["memoryHash"] : void 0;
+    const knowledgeHash = typeof row["knowledgeHash"] === "string" ? row["knowledgeHash"] : void 0;
+    if (memoryHash === void 0 && knowledgeHash === void 0) continue;
+    entries.set(name, {
+      ...memoryHash !== void 0 ? { memoryHash } : {},
+      ...knowledgeHash !== void 0 ? { knowledgeHash } : {}
+    });
+  }
+  const sweptAt = obj["knowledgeSweptAtMs"];
+  return {
+    controlPlaneUrl,
+    entries,
+    // An unreadable/absent sweep stamp reads as NEVER SWEPT, which forces a full
+    // sweep — the fail-closed direction (more upserts, never fewer).
+    knowledgeSweptAtMs: typeof sweptAt === "number" && Number.isFinite(sweptAt) ? sweptAt : null
+  };
+}
+function writePushCache(memoryDir, cache) {
+  const entries = {};
+  for (const [name, value] of cache.entries) entries[name] = value;
+  try {
+    writeFileSync5(
+      statePath(memoryDir),
+      `${JSON.stringify(
+        {
+          version: STATE_VERSION,
+          controlPlaneUrl: cache.controlPlaneUrl,
+          knowledgeSweptAtMs: cache.knowledgeSweptAtMs,
+          entries
+        },
+        null,
+        2
+      )}
+`,
+      "utf8"
+    );
+  } catch {
+  }
+}
+function recordMemoryPush(cache, fileName, payloadHash) {
+  cache.entries.set(fileName, { ...cache.entries.get(fileName), memoryHash: payloadHash });
+}
+function recordKnowledgePush(cache, fileName, contentHash) {
+  cache.entries.set(fileName, { ...cache.entries.get(fileName), knowledgeHash: contentHash });
+}
+function pruneMissing(cache, presentFileNames) {
+  const present = new Set(presentFileNames);
+  for (const name of [...cache.entries.keys()]) {
+    if (!present.has(name)) cache.entries.delete(name);
+  }
+}
+function needsMemoryPush(cache, fileName, payloadHash, serverHasEntry) {
+  if (!serverHasEntry) return true;
+  return cache.entries.get(fileName)?.memoryHash !== payloadHash;
+}
+function knowledgeSweepDue(cache, nowMs = Date.now()) {
+  const swept = cache.knowledgeSweptAtMs;
+  if (swept === null || !Number.isFinite(swept)) return true;
+  const age = nowMs - swept;
+  return !(age >= 0 && age < KNOWLEDGE_FULL_SWEEP_MS);
+}
+function needsKnowledgePush(cache, fileName, contentHash, sweepDue = false) {
+  if (sweepDue) return true;
+  return cache.entries.get(fileName)?.knowledgeHash !== contentHash;
+}
+var MEMORY_SYNC_STATE_FILE, STATE_VERSION, KNOWLEDGE_FULL_SWEEP_MS;
+var init_memory_push_cache = __esm({
+  "src/tools/memory/memory-push-cache.ts"() {
+    "use strict";
+    MEMORY_SYNC_STATE_FILE = ".memory-sync-state.json";
+    STATE_VERSION = 1;
+    KNOWLEDGE_FULL_SWEEP_MS = 24 * 60 * 6e4;
+  }
+});
+
+// src/tools/memory/memory-sync-http.ts
+import { existsSync as existsSync5, mkdirSync as mkdirSync6, readFileSync as readFileSync11, writeFileSync as writeFileSync6, readdirSync as readdirSync4 } from "node:fs";
+async function pullMemory(controlPlaneUrl, token, memoryDir, fetchFn) {
+  const url = `${controlPlaneUrl}/api/v1/agent-config/memory/me`;
+  const response = await withRequestTimeout(
+    url,
+    () => fetchFn(url, {
+      method: "GET",
+      headers: {
+        authorization: `Bearer ${token}`
+      }
+    })
+  );
+  if (response.status !== 200) {
+    const text = await response.text();
+    throw new Error(`GET /api/v1/agent-config/memory/me returned HTTP ${response.status}: ${text.slice(0, 200)}`);
+  }
+  const data = JSON.parse(await response.text());
+  if (!data.ok || !Array.isArray(data.entries)) {
+    throw new Error("GET /api/v1/agent-config/memory/me response missing ok=true or entries array");
+  }
+  const writes = data.entries.map((entry) => ({
+    entry,
+    filePath: resolveMemoryFilePath(memoryDir, entry.file_name)
+  }));
+  mkdirSync6(memoryDir, { recursive: true });
+  const files = [];
+  for (const { entry, filePath } of writes) {
+    writeFileSync6(filePath, entry.content, "utf8");
+    files.push(entry.file_name);
+  }
+  return { pulled: data.entries.length, files };
+}
+function listPushableFiles(memoryDir) {
+  return readdirSync4(memoryDir).filter((f) => f.endsWith(".md") && f !== MEMORY_SYNC_LOCK_FILE);
+}
+async function uploadOne(item, controlPlaneUrl, token, sessionId, fetchFn, deadline) {
+  deadline.check();
+  if (item.memoryId !== null) {
+    const updateUrl = `${controlPlaneUrl}/api/v1/agent-config/memory/${item.memoryId}`;
+    const updateBody = { content: item.content, session_id: sessionId };
+    const updateResponse = await withRequestTimeout(
+      updateUrl,
+      () => fetchFn(updateUrl, {
+        method: "PUT",
+        headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+        body: JSON.stringify(updateBody)
+      })
+    );
+    if (updateResponse.status !== 200) {
+      const text = await updateResponse.text();
+      throw new Error(
+        `PUT /api/v1/agent-config/memory/${item.memoryId} returned HTTP ${updateResponse.status}: ${text.slice(0, 200)}`
+      );
+    }
+    const updateData = JSON.parse(await updateResponse.text());
+    if (!updateData.ok) throw new Error(`PUT /api/v1/agent-config/memory/${item.memoryId} returned ok=false`);
+    return "updated";
+  }
+  const createUrl = `${controlPlaneUrl}/api/v1/agent-config/memory/me`;
+  const createBody = {
+    entry_type: item.entryType,
+    file_name: item.fileName,
+    content: item.content,
+    session_id: sessionId
+  };
+  const createResponse = await withRequestTimeout(
+    createUrl,
+    () => fetchFn(createUrl, {
+      method: "POST",
+      headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+      body: JSON.stringify(createBody)
+    })
+  );
+  if (createResponse.status !== 200 && createResponse.status !== 201) {
+    const text = await createResponse.text();
+    throw new Error(
+      `POST /api/v1/agent-config/memory/me returned HTTP ${createResponse.status}: ${text.slice(0, 200)}`
+    );
+  }
+  const createData = JSON.parse(await createResponse.text());
+  if (!createData.ok) throw new Error("POST /api/v1/agent-config/memory/me returned ok=false");
+  return "created";
+}
+async function pushMemory(controlPlaneUrl, token, memoryDir, sessionId, fetchFn, options = {}) {
+  const empty = { pushed: 0, created: 0, updated: 0, skipped: 0, indexRowsPreserved: 0 };
+  if (!existsSync5(memoryDir)) {
+    return empty;
+  }
+  const localFiles = listPushableFiles(memoryDir).map((f) => ({
+    file_name: f,
+    content: readFileSync11(resolveMemoryFilePath(memoryDir, f), "utf8"),
+    entry_type: isMemoryIndexFile(f) ? "index" : "topic"
+  }));
+  if (localFiles.length === 0) {
+    return empty;
+  }
+  const deadline = options.deadline ?? createSyncDeadline();
+  const cache = options.cache ?? readPushCache(memoryDir, controlPlaneUrl);
+  deadline.check();
+  const getUrl = `${controlPlaneUrl}/api/v1/agent-config/memory/me`;
+  const getResponse = await withRequestTimeout(
+    getUrl,
+    () => fetchFn(getUrl, { method: "GET", headers: { authorization: `Bearer ${token}` } })
+  );
+  const existingMap = /* @__PURE__ */ new Map();
+  if (getResponse.status === 200) {
+    const getData = JSON.parse(await getResponse.text());
+    if (getData.ok && Array.isArray(getData.entries)) {
+      for (const entry of getData.entries) {
+        existingMap.set(entry.file_name, {
+          memoryId: entry.memory_id,
+          content: typeof entry.content === "string" ? entry.content : ""
+        });
+      }
+    }
+  }
+  const toUpload = [];
+  let skipped = 0;
+  for (const localFile of localFiles) {
+    const existing = existingMap.get(localFile.file_name);
+    let content = localFile.content;
+    let rowsPreserved = 0;
+    if (localFile.entry_type === "index") {
+      const merged = mergeMemoryIndex(localFile.content, existing?.content);
+      content = merged.content;
+      rowsPreserved = merged.addedFromCloud.length;
+    }
+    const payloadHash = sha256(content);
+    if (!needsMemoryPush(cache, localFile.file_name, payloadHash, existing !== void 0)) {
+      skipped++;
+      continue;
+    }
+    toUpload.push({
+      fileName: localFile.file_name,
+      entryType: localFile.entry_type,
+      content,
+      payloadHash,
+      memoryId: existing?.memoryId ?? null,
+      rowsPreserved
+    });
+  }
+  const outcomes = await mapWithConcurrency(
+    toUpload,
+    options.concurrency ?? PUSH_CONCURRENCY,
+    (item) => uploadOne(item, controlPlaneUrl, token, sessionId, fetchFn, deadline)
+  );
+  let created = 0;
+  let updated = 0;
+  let indexRowsPreserved = 0;
+  let firstError;
+  for (let i = 0; i < outcomes.length; i++) {
+    const outcome = outcomes[i];
+    const item = toUpload[i];
+    if (outcome.ok) {
+      if (outcome.value === "created") created++;
+      else updated++;
+      indexRowsPreserved += item.rowsPreserved;
+      recordMemoryPush(cache, item.fileName, item.payloadHash);
+    } else if (firstError === void 0) {
+      firstError = outcome.error;
+    }
+  }
+  pruneMissing(cache, localFiles.map((f) => f.file_name));
+  if (options.persistCache ?? options.cache === void 0) writePushCache(memoryDir, cache);
+  if (firstError !== void 0) throw firstError;
+  return { pushed: created + updated, created, updated, skipped, indexRowsPreserved };
+}
+var init_memory_sync_http = __esm({
+  "src/tools/memory/memory-sync-http.ts"() {
+    "use strict";
+    init_safe_memory_file();
+    init_sync_lock();
+    init_memory_index_merge();
+    init_bounded_sync();
+    init_memory_push_cache();
+  }
+});
+
+// src/tools/memory/sync-kill-switch.ts
+import { existsSync as existsSync6, readFileSync as readFileSync12 } from "node:fs";
+import { homedir as homedir6 } from "node:os";
+import { join as join10 } from "node:path";
+function memorySyncSentinelPath(home) {
+  return join10(home, ".claude", MEMORY_SYNC_DISABLE_SENTINEL);
+}
+function isKillSwitchValueOn(raw) {
+  if (raw === void 0 || raw === null) return false;
+  const v = raw.trim().toLowerCase();
+  if (v === "") return false;
+  return !NEGATIONS.has(v);
+}
+function clip(raw) {
+  const v = raw.trim();
+  return v.length > MAX_LOGGED_VALUE ? `${v.slice(0, MAX_LOGGED_VALUE)}\u2026` : v;
+}
+function evaluateMemorySyncKillSwitch(deps = {}) {
+  const env = deps.env ?? process.env;
+  const home = deps.home ?? homedir6();
+  const fileExists = deps.fileExists ?? existsSync6;
+  const readFile3 = deps.readFile ?? ((p) => readFileSync12(p, "utf8"));
+  const fired = [];
+  const rawEnv = env[MEMORY_SYNC_DISABLE_ENV];
+  if (isKillSwitchValueOn(rawEnv)) {
+    fired.push(`env ${MEMORY_SYNC_DISABLE_ENV}=${clip(rawEnv)}`);
+  }
+  const sentinel = memorySyncSentinelPath(home);
+  let sentinelPresent;
+  try {
+    sentinelPresent = fileExists(sentinel);
+  } catch {
+    sentinelPresent = false;
+  }
+  if (sentinelPresent) {
+    let contents = "";
+    let readable = true;
+    try {
+      contents = readFile3(sentinel);
+    } catch {
+      readable = false;
+    }
+    if (!readable || isKillSwitchValueOn(contents) || contents.trim() === "") {
+      fired.push(`sentinel file ${sentinel}`);
+    }
+  }
+  if (fired.length === 0) return { disabled: false, reason: null };
+  return { disabled: true, reason: `memory sync DISABLED by ${fired.join(" + ")}` };
+}
+var MEMORY_SYNC_DISABLE_ENV, MEMORY_SYNC_DISABLE_SENTINEL, NEGATIONS, MAX_LOGGED_VALUE;
+var init_sync_kill_switch = __esm({
+  "src/tools/memory/sync-kill-switch.ts"() {
+    "use strict";
+    MEMORY_SYNC_DISABLE_ENV = "VO_MCP_DISABLE_MEMORY_SYNC";
+    MEMORY_SYNC_DISABLE_SENTINEL = "vo-memory-sync-disabled";
+    NEGATIONS = /* @__PURE__ */ new Set(["0", "false", "no"]);
+    MAX_LOGGED_VALUE = 32;
+  }
+});
+
 // src/tools/memory/memory-knowledge-bridge.ts
 var memory_knowledge_bridge_exports = {};
 __export(memory_knowledge_bridge_exports, {
   extractMemoryTitle: () => extractMemoryTitle,
   upsertMemoryFilesAsKnowledge: () => upsertMemoryFilesAsKnowledge
 });
-import { existsSync as existsSync5, readdirSync as readdirSync4, readFileSync as readFileSync7 } from "node:fs";
+import { existsSync as existsSync7, readdirSync as readdirSync5, readFileSync as readFileSync13 } from "node:fs";
 function extractMemoryTitle(fileName, content) {
   const frontmatter = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
   if (frontmatter) {
@@ -1417,13 +2117,13 @@ function extractMemoryTitle(fileName, content) {
   return fileName;
 }
 async function upsertMemoryFilesAsKnowledge(options) {
-  const { controlPlaneUrl, token, memoryDir, fetchFn } = options;
+  const { controlPlaneUrl, token, memoryDir, fetchFn, cache, deadline } = options;
   let files;
   try {
-    if (!existsSync5(memoryDir)) {
-      return { attempted: 0, upserted: 0, failed: 0, failures: [] };
+    if (!existsSync7(memoryDir)) {
+      return { attempted: 0, upserted: 0, failed: 0, skipped: 0, failures: [] };
     }
-    files = readdirSync4(memoryDir).filter(
+    files = readdirSync5(memoryDir).filter(
       (f) => f.endsWith(".md") && f.toUpperCase() !== "MEMORY.MD"
     );
   } catch (err) {
@@ -1431,54 +2131,81 @@ async function upsertMemoryFilesAsKnowledge(options) {
       attempted: 0,
       upserted: 0,
       failed: 1,
+      skipped: 0,
       failures: [`memory dir scan: ${err instanceof Error ? err.message : String(err)}`]
     };
   }
-  let upserted = 0;
+  const sweepDue = cache ? knowledgeSweepDue(cache) : true;
+  const candidates = [];
   const failures = [];
+  let skipped = 0;
   for (const fileName of files) {
     try {
-      const content = readFileSync7(resolveMemoryFilePath(memoryDir, fileName), "utf8");
+      const content = readFileSync13(resolveMemoryFilePath(memoryDir, fileName), "utf8");
       if (content.length > CONTENT_HARD_LIMIT) {
         failures.push(`${fileName}: ${content.length} chars exceeds the ${CONTENT_HARD_LIMIT} server limit \u2014 split the memory file`);
         continue;
       }
-      const title = extractMemoryTitle(fileName, content);
-      const base = {
-        knowledge_class: "memory",
-        source_path: `memory/${fileName}`,
-        title,
-        content
-      };
-      const post = (body) => fetchFn(`${controlPlaneUrl}/api/v1/knowledge/private`, {
-        method: "POST",
-        headers: {
-          authorization: `Bearer ${token}`,
-          "content-type": "application/json"
-        },
-        body: JSON.stringify(body)
-      });
-      let response = await post({
-        ...base,
-        provenance: { written_by: "memory-bridge", source_kind: "operator_memory" }
-      });
-      if (response.status === 400) {
-        response = await post(base);
-      }
-      if (response.status >= 200 && response.status < 300) {
-        upserted += 1;
-      } else {
-        const text = await response.text();
-        failures.push(`${fileName}: HTTP ${response.status} ${text.slice(0, 80)}`);
+      const hash = sha256(content);
+      if (cache && !needsKnowledgePush(cache, fileName, hash, sweepDue)) {
+        skipped += 1;
+        continue;
       }
+      candidates.push({ fileName, content, hash });
     } catch (err) {
       failures.push(`${fileName}: ${err instanceof Error ? err.message : String(err)}`);
     }
   }
+  const url = `${controlPlaneUrl}/api/v1/knowledge/private`;
+  const outcomes = await mapWithConcurrency(candidates, options.concurrency ?? PUSH_CONCURRENCY, async (candidate) => {
+    deadline?.check();
+    const base = {
+      knowledge_class: "memory",
+      source_path: `memory/${candidate.fileName}`,
+      title: extractMemoryTitle(candidate.fileName, candidate.content),
+      content: candidate.content
+    };
+    const post = (body) => withRequestTimeout(url, () => fetchFn(url, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${token}`,
+        "content-type": "application/json"
+      },
+      body: JSON.stringify(body)
+    }));
+    let response = await post({
+      ...base,
+      provenance: { written_by: "memory-bridge", source_kind: "operator_memory" }
+    });
+    if (response.status === 400) {
+      response = await post(base);
+    }
+    if (response.status >= 200 && response.status < 300) return true;
+    const text = await response.text();
+    throw new Error(`HTTP ${response.status} ${text.slice(0, 80)}`);
+  });
+  let upserted = 0;
+  for (let i = 0; i < outcomes.length; i++) {
+    const outcome = outcomes[i];
+    const candidate = candidates[i];
+    if (outcome.ok) {
+      upserted += 1;
+      if (cache) recordKnowledgePush(cache, candidate.fileName, candidate.hash);
+    } else {
+      const error = outcome.error;
+      failures.push(`${candidate.fileName}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  if (cache && sweepDue && failures.length === 0) {
+    cache.knowledgeSweptAtMs = Date.now();
+  }
   return {
+    // Every memory file this run considered. `attempted === upserted + skipped
+    // + failed` holds, so a caller can tell "nothing to do" from "nothing ran".
     attempted: files.length,
     upserted,
     failed: failures.length,
+    skipped,
     failures: failures.slice(0, 5)
   };
 }
@@ -1487,6 +2214,8 @@ var init_memory_knowledge_bridge = __esm({
   "src/tools/memory/memory-knowledge-bridge.ts"() {
     "use strict";
     init_safe_memory_file();
+    init_bounded_sync();
+    init_memory_push_cache();
     CONTENT_HARD_LIMIT = 5e5;
   }
 });
@@ -1503,9 +2232,9 @@ __export(sync_config_exports, {
   isNoopSyncReason: () => isNoopSyncReason,
   runMemorySync: () => runMemorySync
 });
-import { homedir as homedir5 } from "node:os";
-import { join as join7 } from "node:path";
-import { existsSync as existsSync6, mkdirSync as mkdirSync4, readFileSync as readFileSync8, writeFileSync as writeFileSync3, readdirSync as readdirSync5 } from "node:fs";
+import { existsSync as existsSync8 } from "node:fs";
+import { homedir as homedir7 } from "node:os";
+import { join as join11 } from "node:path";
 function isToolInput22(v) {
   if (typeof v !== "object" || v === null) return false;
   const o = v;
@@ -1518,129 +2247,17 @@ function deriveProjectSlug(cwd) {
 }
 function getMemoryDir(cwd) {
   const slug = deriveProjectSlug(cwd);
-  return join7(homedir5(), ".claude", "projects", slug, "memory");
-}
-async function pullMemory(controlPlaneUrl, token, memoryDir, fetchFn) {
-  const url = `${controlPlaneUrl}/api/v1/agent-config/memory/me`;
-  const response = await fetchFn(url, {
-    method: "GET",
-    headers: {
-      authorization: `Bearer ${token}`
-    }
-  });
-  if (response.status !== 200) {
-    const text = await response.text();
-    throw new Error(`GET /api/v1/agent-config/memory/me returned HTTP ${response.status}: ${text.slice(0, 200)}`);
-  }
-  const data = JSON.parse(await response.text());
-  if (!data.ok || !Array.isArray(data.entries)) {
-    throw new Error("GET /api/v1/agent-config/memory/me response missing ok=true or entries array");
-  }
-  const writes = data.entries.map((entry) => ({
-    entry,
-    filePath: resolveMemoryFilePath(memoryDir, entry.file_name)
-  }));
-  mkdirSync4(memoryDir, { recursive: true });
-  const files = [];
-  for (const { entry, filePath } of writes) {
-    writeFileSync3(filePath, entry.content, "utf8");
-    files.push(entry.file_name);
-  }
-  return { pulled: data.entries.length, files };
-}
-async function pushMemory(controlPlaneUrl, token, memoryDir, sessionId, fetchFn) {
-  if (!existsSync6(memoryDir)) {
-    return { pushed: 0, created: 0, updated: 0 };
-  }
-  const localFiles = readdirSync5(memoryDir).filter((f) => f.endsWith(".md")).map((f) => ({
-    file_name: f,
-    content: readFileSync8(resolveMemoryFilePath(memoryDir, f), "utf8"),
-    entry_type: f === "MEMORY.md" ? "index" : "topic"
-  }));
-  if (localFiles.length === 0) {
-    return { pushed: 0, created: 0, updated: 0 };
-  }
-  const getUrl = `${controlPlaneUrl}/api/v1/agent-config/memory/me`;
-  const getResponse = await fetchFn(getUrl, {
-    method: "GET",
-    headers: {
-      authorization: `Bearer ${token}`
-    }
-  });
-  const existingMap = /* @__PURE__ */ new Map();
-  if (getResponse.status === 200) {
-    const getData = JSON.parse(await getResponse.text());
-    if (getData.ok && Array.isArray(getData.entries)) {
-      for (const entry of getData.entries) {
-        existingMap.set(entry.file_name, entry.memory_id);
-      }
-    }
-  }
-  let created = 0;
-  let updated = 0;
-  for (const localFile of localFiles) {
-    const memoryId = existingMap.get(localFile.file_name);
-    if (memoryId) {
-      const updateUrl = `${controlPlaneUrl}/api/v1/agent-config/memory/${memoryId}`;
-      const updateBody = {
-        content: localFile.content,
-        session_id: sessionId
-      };
-      const updateResponse = await fetchFn(updateUrl, {
-        method: "PUT",
-        headers: {
-          authorization: `Bearer ${token}`,
-          "content-type": "application/json"
-        },
-        body: JSON.stringify(updateBody)
-      });
-      if (updateResponse.status !== 200) {
-        const text = await updateResponse.text();
-        throw new Error(
-          `PUT /api/v1/agent-config/memory/${memoryId} returned HTTP ${updateResponse.status}: ${text.slice(0, 200)}`
-        );
-      }
-      const updateData = JSON.parse(await updateResponse.text());
-      if (!updateData.ok) {
-        throw new Error(`PUT /api/v1/agent-config/memory/${memoryId} returned ok=false`);
-      }
-      updated++;
-    } else {
-      const createUrl = `${controlPlaneUrl}/api/v1/agent-config/memory/me`;
-      const createBody = {
-        entry_type: localFile.entry_type,
-        file_name: localFile.file_name,
-        content: localFile.content,
-        session_id: sessionId
-      };
-      const createResponse = await fetchFn(createUrl, {
-        method: "POST",
-        headers: {
-          authorization: `Bearer ${token}`,
-          "content-type": "application/json"
-        },
-        body: JSON.stringify(createBody)
-      });
-      if (createResponse.status !== 200 && createResponse.status !== 201) {
-        const text = await createResponse.text();
-        throw new Error(
-          `POST /api/v1/agent-config/memory/me returned HTTP ${createResponse.status}: ${text.slice(0, 200)}`
-        );
-      }
-      const createData = JSON.parse(await createResponse.text());
-      if (!createData.ok) {
-        throw new Error("POST /api/v1/agent-config/memory/me returned ok=false");
-      }
-      created++;
-    }
-  }
-  return { pushed: localFiles.length, created, updated };
+  return join11(homedir7(), ".claude", "projects", slug, "memory");
 }
 function isNoopSyncReason(reason) {
   if (!reason) return false;
-  return /not set|No auth configured|Failed to obtain auth token/.test(reason);
+  return /not set|No auth configured|Failed to obtain auth token|DISABLED by/.test(reason);
 }
-async function runMemorySync(action, cwd, sessionId, fetchFn = globalThis.fetch) {
+async function runMemorySync(action, cwd, sessionId, fetchFn = globalThis.fetch, lockOptions = {}) {
+  const killSwitch = evaluateMemorySyncKillSwitch();
+  if (killSwitch.disabled) {
+    return { synced: false, reason: killSwitch.reason };
+  }
   const controlPlaneUrl = process.env["VO_CONTROL_PLANE_URL"];
   if (!controlPlaneUrl) {
     return { synced: false, reason: "VO_CONTROL_PLANE_URL not set \u2014 cloud mode disabled" };
@@ -1657,39 +2274,79 @@ async function runMemorySync(action, cwd, sessionId, fetchFn = globalThis.fetch)
   }
   const memoryDir = getMemoryDir(cwd);
   const baseUrl = controlPlaneUrl.replace(/\/+$/, "");
-  try {
-    if (action === "pull") {
-      const result2 = await pullMemory(baseUrl, token, memoryDir, fetchFn);
-      return { synced: true, action: "pull", pulled: result2.pulled, files: result2.files, memory_dir: memoryDir };
-    }
-    const result = await pushMemory(baseUrl, token, memoryDir, sessionId, fetchFn);
-    let bridge = { upserted: 0, failed: 0, failures: [] };
-    try {
-      const { upsertMemoryFilesAsKnowledge: upsertMemoryFilesAsKnowledge2 } = await Promise.resolve().then(() => (init_memory_knowledge_bridge(), memory_knowledge_bridge_exports));
-      bridge = await upsertMemoryFilesAsKnowledge2({
-        controlPlaneUrl: baseUrl,
-        token,
-        memoryDir,
-        fetchFn
-      });
-    } catch (err) {
-      bridge = {
-        upserted: 0,
-        failed: 1,
-        failures: [`bridge unavailable: ${err instanceof Error ? err.message : String(err)}`]
-      };
-    }
+  if (action === "push" && !existsSync8(memoryDir)) {
     return {
       synced: true,
       action: "push",
-      pushed: result.pushed,
-      created: result.created,
-      updated: result.updated,
-      memory_dir: memoryDir,
-      knowledge_upserted: bridge.upserted,
-      knowledge_failed: bridge.failed,
-      ...bridge.failed > 0 ? { knowledge_failures: bridge.failures } : {}
+      pushed: 0,
+      created: 0,
+      updated: 0,
+      skipped: 0,
+      index_rows_preserved: 0,
+      knowledge_upserted: 0,
+      knowledge_failed: 0,
+      memory_dir: memoryDir
     };
+  }
+  try {
+    return await withMemorySyncLock({ ...lockOptions, memoryDir, sessionId, createDir: action === "pull" }, async (lock) => {
+      const takeover = lock.tookOverFrom ? { lock_taken_over_from_pid: lock.tookOverFrom.pid } : {};
+      if (action === "pull") {
+        const result2 = await pullMemory(baseUrl, token, memoryDir, fetchFn);
+        return {
+          synced: true,
+          action: "pull",
+          pulled: result2.pulled,
+          files: result2.files,
+          memory_dir: memoryDir,
+          ...takeover
+        };
+      }
+      const deadline = createSyncDeadline();
+      const cache = readPushCache(memoryDir, baseUrl);
+      let result;
+      try {
+        result = await pushMemory(baseUrl, token, memoryDir, sessionId, fetchFn, { cache, deadline });
+      } catch (err) {
+        writePushCache(memoryDir, cache);
+        throw err;
+      }
+      let bridge;
+      try {
+        const { upsertMemoryFilesAsKnowledge: upsertMemoryFilesAsKnowledge2 } = await Promise.resolve().then(() => (init_memory_knowledge_bridge(), memory_knowledge_bridge_exports));
+        bridge = await upsertMemoryFilesAsKnowledge2({
+          controlPlaneUrl: baseUrl,
+          token,
+          memoryDir,
+          fetchFn,
+          cache,
+          deadline
+        });
+      } catch (err) {
+        bridge = {
+          upserted: 0,
+          failed: 1,
+          skipped: 0,
+          failures: [`bridge unavailable: ${err instanceof Error ? err.message : String(err)}`]
+        };
+      }
+      writePushCache(memoryDir, cache);
+      return {
+        synced: true,
+        action: "push",
+        pushed: result.pushed,
+        created: result.created,
+        updated: result.updated,
+        skipped: result.skipped,
+        index_rows_preserved: result.indexRowsPreserved,
+        memory_dir: memoryDir,
+        knowledge_upserted: bridge.upserted,
+        knowledge_failed: bridge.failed,
+        knowledge_skipped: bridge.skipped,
+        ...bridge.failed > 0 ? { knowledge_failures: bridge.failures } : {},
+        ...takeover
+      };
+    });
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     return { synced: false, reason: `Sync failed: ${message}` };
@@ -1711,7 +2368,11 @@ var init_sync_config = __esm({
   "src/tools/memory/sync-config.ts"() {
     "use strict";
     init_common();
-    init_safe_memory_file();
+    init_memory_sync_http();
+    init_bounded_sync();
+    init_memory_push_cache();
+    init_sync_lock();
+    init_sync_kill_switch();
     TOOL_NAME22 = "vo_sync_config";
     inputSchema22 = {
       type: "object",
@@ -1729,19 +2390,19 @@ var init_sync_config = __esm({
       required: ["action"],
       additionalProperties: false
     };
-    description22 = "Syncs memory entries between local ~/.claude/projects/<slug>/memory/ and cloud control-plane /api/v1/agent-config/memory/me. Requires operator auth (vo-mcp login). Actions: pull (cloud\u2192local), push (local\u2192cloud). Idempotent; push creates/updates as needed.";
+    description22 = "Syncs memory entries between local ~/.claude/projects/<slug>/memory/ and cloud control-plane /api/v1/agent-config/memory/me. Requires operator auth (vo-mcp login). Actions: pull (cloud\u2192local), push (local\u2192cloud). Idempotent; push creates/updates as needed. Serialized across concurrent sessions by an exclusive lock in the memory dir.";
   }
 });
 
 // src/cli.ts
-import { homedir as homedir6, hostname } from "node:os";
-import { randomUUID as randomUUID5 } from "node:crypto";
-import { join as join10 } from "node:path";
+import { homedir as homedir8, hostname as hostname2 } from "node:os";
+import { randomUUID as randomUUID6 } from "node:crypto";
+import { join as join14 } from "node:path";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/server.ts
 init_common();
-import { randomUUID as randomUUID2 } from "node:crypto";
+import { randomUUID as randomUUID3 } from "node:crypto";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import {
   CallToolRequestSchema,
@@ -5394,9 +6055,324 @@ async function handleReportSessionState(deps, rawInput, _signal) {
 // src/tools/session/spawn-successor.ts
 init_common();
 import { spawn } from "node:child_process";
+import { homedir as homedir5 } from "node:os";
+import { join as join7 } from "node:path";
+import { existsSync as existsSync4, mkdirSync as mkdirSync4, openSync as openSync2, readFileSync as readFileSync7, readdirSync as readdirSync3, statSync as statSync3 } from "node:fs";
+
+// src/swarm/tier-binding.ts
+var SWARM_TIERS = Object.freeze([
+  "tier1_subscription",
+  "tier1_local",
+  "tier2_user_key",
+  "tier3_platform_key",
+  "refused",
+  "unresolved"
+]);
+var TIER_ADMITS_SPAWN = /* @__PURE__ */ new Set([
+  "tier1_subscription",
+  "tier1_local",
+  "tier2_user_key",
+  "tier3_platform_key"
+]);
+var SWARM_TIER_BINDING_ENV = "VO_SWARM_TIER_BINDING";
+var MAX_BOUND_SUBAGENTS = 20;
+function isPositiveCap(cap) {
+  return typeof cap === "number" && Number.isFinite(cap) && cap > 0;
+}
+function unresolvedBinding(swarmId, nowIso, reason) {
+  return {
+    schema_version: 1,
+    swarm_id: swarmId,
+    tier: "unresolved",
+    agent: null,
+    reason,
+    exhausted_agents: [],
+    subagent_budget: 0,
+    spend_cap_usd: null,
+    resolved_at: nowIso
+  };
+}
+function serializeSwarmTierBinding(binding) {
+  return JSON.stringify(binding);
+}
+function parseSwarmTierBinding(raw, nowIso) {
+  if (typeof raw !== "string" || raw.trim().length === 0) {
+    return unresolvedBinding("", nowIso, "no swarm tier binding present in the environment");
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return unresolvedBinding("", nowIso, "swarm tier binding is not valid JSON");
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return unresolvedBinding("", nowIso, "swarm tier binding is not an object");
+  }
+  const o = parsed;
+  const swarmId = typeof o["swarm_id"] === "string" ? o["swarm_id"] : "";
+  if (o["schema_version"] !== 1) {
+    return unresolvedBinding(swarmId, nowIso, "swarm tier binding has an unsupported schema_version");
+  }
+  const tier = o["tier"];
+  if (typeof tier !== "string" || !SWARM_TIERS.includes(tier)) {
+    return unresolvedBinding(swarmId, nowIso, "swarm tier binding names an unknown tier");
+  }
+  const budget = o["subagent_budget"];
+  const cap = o["spend_cap_usd"];
+  const capNum = isPositiveCap(cap) ? cap : null;
+  if (tier === "tier3_platform_key" && capNum === null) {
+    return unresolvedBinding(
+      swarmId,
+      nowIso,
+      "inherited tier3_platform_key binding carries no positive numeric spend cap \u2014 refusing an uncapped platform-billed fan-out"
+    );
+  }
+  return {
+    schema_version: 1,
+    swarm_id: swarmId,
+    tier,
+    agent: typeof o["agent"] === "string" ? o["agent"] : null,
+    reason: typeof o["reason"] === "string" ? o["reason"] : "inherited binding carried no reason",
+    exhausted_agents: Array.isArray(o["exhausted_agents"]) ? o["exhausted_agents"].filter((v) => typeof v === "string") : [],
+    subagent_budget: typeof budget === "number" && Number.isFinite(budget) && budget > 0 ? Math.min(Math.floor(budget), MAX_BOUND_SUBAGENTS) : 0,
+    spend_cap_usd: capNum,
+    resolved_at: typeof o["resolved_at"] === "string" ? o["resolved_at"] : nowIso
+  };
+}
+function inheritSwarmTierBinding(env, nowIso) {
+  return parseSwarmTierBinding(env[SWARM_TIER_BINDING_ENV], nowIso);
+}
+function bindingEnvFragment(binding) {
+  return { [SWARM_TIER_BINDING_ENV]: serializeSwarmTierBinding(binding) };
+}
+function childBindingEnvFragment(binding, allocatedCapUsd = null) {
+  return bindingEnvFragment(childBinding(binding, allocatedCapUsd));
+}
+function admitSubagentSpawn(binding, spawnsSoFar = 0) {
+  if (!TIER_ADMITS_SPAWN.has(binding.tier)) {
+    return { allowed: false, reason: `tier '${binding.tier}' admits no spawn: ${binding.reason}` };
+  }
+  if (binding.tier === "tier3_platform_key" && !isPositiveCap(binding.spend_cap_usd)) {
+    return {
+      allowed: false,
+      reason: `swarm ${binding.swarm_id} is tier3_platform_key with no positive spend cap \u2014 refusing to spend the platform owner's money uncapped`
+    };
+  }
+  if (!Number.isFinite(spawnsSoFar) || spawnsSoFar < 0) {
+    return { allowed: false, reason: "spawn counter is not a finite non-negative number" };
+  }
+  if (spawnsSoFar >= binding.subagent_budget) {
+    return {
+      allowed: false,
+      reason: `swarm ${binding.swarm_id} exhausted its bound subagent budget (${binding.subagent_budget})`
+    };
+  }
+  return { allowed: true, reason: `admitted under tier '${binding.tier}'` };
+}
+function childBinding(binding, allocatedCapUsd = null) {
+  const allocated = isPositiveCap(allocatedCapUsd) ? allocatedCapUsd : null;
+  const parentCap = isPositiveCap(binding.spend_cap_usd) ? binding.spend_cap_usd : null;
+  return {
+    ...binding,
+    subagent_budget: Math.max(0, binding.subagent_budget - 1),
+    // A child never carries more than its parent, whatever the ledger says: a
+    // forged or hand-edited pool cannot inflate a descendant above the binding
+    // it descends from.
+    spend_cap_usd: allocated === null || parentCap === null ? null : Math.min(allocated, parentCap)
+  };
+}
+function agentBindingRefusal(binding, requestedAgent) {
+  const requested = typeof requestedAgent === "string" ? requestedAgent.trim() : "";
+  if (requested.length === 0) return null;
+  if (binding.agent !== null && requested === binding.agent) return null;
+  return `swarm '${binding.swarm_id}' is bound to agent '${binding.agent ?? "none"}' under tier '${binding.tier}'; a caller-supplied agent '${requested}' would move this fan-out onto a different payer \u2014 refusing (the tier is decided once, at admission, and an inherited binding cannot be renegotiated)`;
+}
+
+// src/swarm/successor-launch.ts
+var AGENT_LAUNCH_SHAPES = Object.freeze({
+  claude: {
+    bin: "claude",
+    baseArgs: ["-p", "--permission-mode", "acceptEdits"],
+    enforcesMaxTurns: true,
+    maxTurnsFlag: "--max-turns",
+    windowsShellSafe: true
+  },
+  codex: {
+    bin: "codex",
+    baseArgs: ["exec", "--json", "-c", 'approval_policy="never"', "--sandbox", "workspace-write", "--skip-git-repo-check"],
+    enforcesMaxTurns: false,
+    // `-` makes codex read the prompt from stdin (injection-safe), matching how
+    // codex-runner.mjs already spawns it.
+    trailingArgs: ["-"],
+    // `approval_policy="never"` carries embedded quotes; cmd.exe re-parsing is
+    // unverified, so win32 refuses rather than risking a mangled sandbox flag.
+    windowsShellSafe: false
+  }
+});
+function resolveSuccessorLaunch(input) {
+  const agent = typeof input.agent === "string" ? input.agent.trim() : "";
+  if (!agent) {
+    return { ok: false, reason: "no agent bound for this spawn \u2014 refusing rather than defaulting to claude" };
+  }
+  const shape = AGENT_LAUNCH_SHAPES[agent];
+  if (!shape) {
+    const known = Object.keys(AGENT_LAUNCH_SHAPES).join(", ");
+    return {
+      ok: false,
+      reason: `no known headless launch shape for agent '${agent}' (known: ${known}) \u2014 refusing rather than guessing its argv`
+    };
+  }
+  const wantsMaxTurns = Number.isInteger(input.maxTurns) && input.maxTurns > 0;
+  if (wantsMaxTurns && !shape.enforcesMaxTurns) {
+    return {
+      ok: false,
+      reason: `agent '${agent}' cannot enforce a max_turns cap \u2014 refusing rather than spawning it unbounded`
+    };
+  }
+  const platform = input.platform ?? process.platform;
+  if (platform === "win32" && !shape.windowsShellSafe) {
+    return {
+      ok: false,
+      reason: `agent '${agent}' has an argv whose behaviour under Windows cmd.exe re-parsing is unverified \u2014 refusing rather than emitting a command line that may mean something else`
+    };
+  }
+  const args = [...shape.baseArgs];
+  if (wantsMaxTurns && shape.maxTurnsFlag) {
+    args.push(shape.maxTurnsFlag, String(input.maxTurns));
+  }
+  if (shape.trailingArgs) args.push(...shape.trailingArgs);
+  return { ok: true, agent, bin: shape.bin, args };
+}
+
+// src/swarm/spawn-ledger.ts
+import { mkdirSync as mkdirSync3, openSync, closeSync, readFileSync as readFileSync6, writeFileSync as writeFileSync3 } from "node:fs";
 import { homedir as homedir4 } from "node:os";
 import { join as join6 } from "node:path";
-import { existsSync as existsSync4, mkdirSync as mkdirSync3, openSync, readFileSync as readFileSync6, readdirSync as readdirSync3, statSync as statSync3 } from "node:fs";
+var SWARM_LEDGER_DIR_ENV = "VO_SWARM_LEDGER_DIR";
+function resolveLedgerDir(env) {
+  const override = env[SWARM_LEDGER_DIR_ENV];
+  if (typeof override === "string" && override.trim().length > 0) return override.trim();
+  return join6(homedir4(), ".vo", "swarm-ledger");
+}
+function sanitizeSwarmId(raw) {
+  if (typeof raw !== "string") return null;
+  const id = raw.trim();
+  if (id.length === 0 || id.length > 128) return null;
+  if (!/^[A-Za-z0-9._-]+$/u.test(id)) return null;
+  if (id === "." || id === "..") return null;
+  return id;
+}
+var CEILING_FILE = "ceiling.json";
+function createExclusive(path3, contents) {
+  let fd;
+  try {
+    fd = openSync(path3, "wx");
+  } catch {
+    return false;
+  }
+  try {
+    writeFileSync3(fd, contents, "utf8");
+  } finally {
+    closeSync(fd);
+  }
+  return true;
+}
+function capToCents(cap) {
+  return isPositiveCap(cap) ? Math.round(cap * 100) : 0;
+}
+function readOrRecordLedgerHead(swarmDir, proposedCeiling, proposedCapCents, nowIso) {
+  const path3 = join6(swarmDir, CEILING_FILE);
+  const head = JSON.stringify({
+    ceiling: proposedCeiling,
+    cap_cents: proposedCapCents,
+    recorded_at: nowIso
+  });
+  if (createExclusive(path3, head)) {
+    return { ceiling: proposedCeiling, capCents: proposedCapCents };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync6(path3, "utf8"));
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+  const record = parsed;
+  const recorded = record["ceiling"];
+  if (typeof recorded !== "number" || !Number.isFinite(recorded) || recorded < 1) return null;
+  const recordedCap = record["cap_cents"];
+  const capCents = typeof recordedCap === "number" && Number.isFinite(recordedCap) && recordedCap > 0 ? Math.floor(recordedCap) : 0;
+  return { ceiling: Math.min(Math.floor(recorded), MAX_BOUND_SUBAGENTS), capCents };
+}
+var claimSpawnSlot = ({ swarmId, proposedCeiling, proposedCapUsd, dir, nowIso }) => {
+  const id = sanitizeSwarmId(swarmId);
+  if (id === null) {
+    return {
+      ok: false,
+      reason: `swarm id ${JSON.stringify(swarmId)} is absent or unusable as a ledger key \u2014 refusing a spawn that cannot be counted against a fan-out ceiling`
+    };
+  }
+  const proposed = Number.isFinite(proposedCeiling) ? Math.floor(proposedCeiling) : 0;
+  if (proposed < 1) {
+    return { ok: false, reason: `swarm '${id}' proposes a ceiling of ${proposed} \u2014 no allowance to claim` };
+  }
+  const swarmDir = join6(dir, id);
+  try {
+    mkdirSync3(swarmDir, { recursive: true });
+  } catch (err) {
+    return {
+      ok: false,
+      reason: `swarm '${id}' ledger directory is unwritable (${err instanceof Error ? err.message : String(err)}) \u2014 refusing rather than spawning uncounted`
+    };
+  }
+  const wantedCents = capToCents(proposedCapUsd);
+  const head = readOrRecordLedgerHead(swarmDir, Math.min(proposed, MAX_BOUND_SUBAGENTS), wantedCents, nowIso);
+  if (head === null) {
+    return { ok: false, reason: `swarm '${id}' ledger carries no readable ceiling \u2014 refusing rather than spawning uncounted` };
+  }
+  const { ceiling, capCents } = head;
+  const shareCents = capCents > 0 ? Math.floor(capCents / ceiling) : 0;
+  if (wantedCents > 0 && shareCents < 1) {
+    return {
+      ok: false,
+      reason: `swarm '${id}' has no spend allowance left to debit (recorded pool $${(capCents / 100).toFixed(2)} across a ceiling of ${ceiling} leaves under one cent per spawn) \u2014 refusing a platform-billed spawn it cannot fund`
+    };
+  }
+  for (let slot = 0; slot < ceiling; slot++) {
+    const debitedCents = shareCents;
+    const remainingCents = capCents > 0 ? capCents - (slot + 1) * shareCents : 0;
+    const claimed = createExclusive(
+      join6(swarmDir, `slot-${slot}.json`),
+      JSON.stringify({
+        slot,
+        ceiling,
+        pid: process.pid,
+        claimed_at: nowIso,
+        // The debit record. Durable and atomic with the claim: this file is
+        // created with O_EXCL, so exactly one claimant ever writes this line.
+        cap_cents_pool: capCents,
+        cap_cents_debited: debitedCents,
+        cap_cents_remaining: remainingCents
+      })
+    );
+    if (claimed) {
+      return {
+        ok: true,
+        slot,
+        ceiling,
+        remaining: ceiling - slot - 1,
+        capUsd: debitedCents > 0 ? debitedCents / 100 : null,
+        capRemainingUsd: capCents > 0 ? remainingCents / 100 : null
+      };
+    }
+  }
+  return {
+    ok: false,
+    reason: `swarm '${id}' has spent its whole fan-out ceiling (${ceiling} spawns across every generation) \u2014 refusing`
+  };
+};
+
+// src/tools/session/spawn-successor.ts
 var TOOL_NAME20 = "vo_spawn_successor";
 var MAX_HANDOFF_BYTES = 64e3;
 var inputSchema20 = {
@@ -5417,11 +6393,16 @@ var inputSchema20 = {
     max_turns: {
       type: "number",
       description: "Optional --max-turns bound for the successor."
+    },
+    agent: {
+      type: "string",
+      description: `Which agent to spawn ('claude' | 'codex'). Normally omitted: the agent comes from the swarm tier binding inherited via ${SWARM_TIER_BINDING_ENV}. When a binding IS inherited this may only RESTATE the bound agent \u2014 an agent that contradicts the binding is REFUSED, because a different agent is a different payer and the payer was decided once, at admission.`
     }
   },
   required: [],
   additionalProperties: false
 };
+var RETIRED_COUNTER_INPUT = "spawns_so_far";
 var description20 = "Mode B auto-handoff (roadmap \xA73.4): spawn a DETACHED headless `claude -p` successor with a handoff doc pre-injected into its prompt. Defaults to the newest handoff in ~/.vo/handoffs/. Returns {spawned, pid, log_path, handoff_path}. The successor works under the same gates as any session (ADR-001: verify-before-act, human merge approval) \u2014 this tool never fires autonomously.";
 function isToolInput20(v) {
   if (typeof v !== "object" || v === null) return false;
@@ -5430,12 +6411,18 @@ function isToolInput20(v) {
   if (o["goal"] !== void 0 && typeof o["goal"] !== "string") return false;
   if (o["cwd"] !== void 0 && typeof o["cwd"] !== "string") return false;
   if (o["max_turns"] !== void 0 && typeof o["max_turns"] !== "number") return false;
+  if (o["agent"] !== void 0 && typeof o["agent"] !== "string") return false;
   return true;
 }
-function newestHandoff(dir = join6(homedir4(), ".vo", "handoffs")) {
+function retiredCounterRefusal(v) {
+  if (typeof v !== "object" || v === null) return null;
+  if (!(RETIRED_COUNTER_INPUT in v)) return null;
+  return `\`${RETIRED_COUNTER_INPUT}\` is no longer accepted: a spawn counter supplied by the process being bounded bounds nothing, and an absent one read as zero. The fan-out ceiling is now enforced by the durable per-swarm spawn ledger; remove the field.`;
+}
+function newestHandoff(dir = join7(homedir5(), ".vo", "handoffs")) {
   try {
-    const entries = readdirSync3(dir).filter((f) => f.endsWith(".md")).map((f) => ({ f, m: statSync3(join6(dir, f)).mtimeMs })).sort((a, b) => b.m - a.m);
-    return entries.length > 0 && entries[0] ? join6(dir, entries[0].f) : null;
+    const entries = readdirSync3(dir).filter((f) => f.endsWith(".md")).map((f) => ({ f, m: statSync3(join7(dir, f)).mtimeMs })).sort((a, b) => b.m - a.m);
+    return entries.length > 0 && entries[0] ? join7(dir, entries[0].f) : null;
   } catch {
     return null;
   }
@@ -5479,9 +6466,87 @@ function buildSuccessorArgs(maxTurns) {
   }
   return args;
 }
+function resolveSpawnPlan(env, input, nowIso, platform = process.platform, claim = claimSpawnSlot) {
+  const rawBinding = env[SWARM_TIER_BINDING_ENV];
+  const hasBinding = typeof rawBinding === "string" && rawBinding.trim().length > 0;
+  if (!hasBinding) {
+    const explicit = input.agent?.trim();
+    if (explicit) {
+      const resolved2 = resolveSuccessorLaunch({ agent: explicit, maxTurns: input.max_turns, platform });
+      if (!resolved2.ok) return { ok: false, reason: resolved2.reason, tier: "unbound" };
+      return {
+        ok: true,
+        bin: resolved2.bin,
+        args: resolved2.args,
+        agent: resolved2.agent,
+        tier: "unbound",
+        bound: false,
+        env: {},
+        slot: null,
+        capUsd: null,
+        capRemainingUsd: null
+      };
+    }
+    return {
+      ok: true,
+      bin: "claude",
+      args: buildSuccessorArgs(input.max_turns),
+      agent: "claude",
+      tier: "unbound",
+      bound: false,
+      env: {},
+      slot: null,
+      capUsd: null,
+      capRemainingUsd: null
+    };
+  }
+  const binding = inheritSwarmTierBinding(env, nowIso);
+  const admission = admitSubagentSpawn(binding);
+  if (!admission.allowed) {
+    return { ok: false, reason: admission.reason, tier: binding.tier };
+  }
+  const agentRefusal = agentBindingRefusal(binding, input.agent);
+  if (agentRefusal !== null) return { ok: false, reason: agentRefusal, tier: binding.tier };
+  const resolved = resolveSuccessorLaunch({
+    agent: binding.agent,
+    maxTurns: input.max_turns,
+    platform
+  });
+  if (!resolved.ok) return { ok: false, reason: resolved.reason, tier: binding.tier };
+  const slot = claim({
+    swarmId: binding.swarm_id,
+    proposedCeiling: binding.subagent_budget,
+    // The spend-cap POOL, recorded once per swarm exactly like the ceiling. The
+    // child's cap is DEBITED from it below, not recomputed from this binding.
+    proposedCapUsd: binding.spend_cap_usd,
+    dir: resolveLedgerDir(env),
+    nowIso
+  });
+  if (!slot.ok) return { ok: false, reason: slot.reason, tier: binding.tier };
+  return {
+    ok: true,
+    bin: resolved.bin,
+    args: resolved.args,
+    agent: resolved.agent,
+    tier: binding.tier,
+    bound: true,
+    // Re-export the same TIER with a DECREMENTED budget and the spend cap the
+    // ledger just DEBITED. Exporting the binding verbatim (what this did before
+    // #9312) meant the child re-read the full budget and every generation
+    // restarted at zero. Recomputing the cap from THIS binding (what #9312 did)
+    // bounded a chain but not a tree: three siblings each re-halved the parent's
+    // untouched $50 and walked away with $75 between them.
+    env: childBindingEnvFragment(binding, slot.capUsd),
+    slot: slot.slot,
+    capUsd: slot.capUsd,
+    capRemainingUsd: slot.capRemainingUsd
+  };
+}
 async function handleSpawnSuccessor(_deps, rawInput, _signal, spawnImpl = spawn) {
+  const retired = retiredCounterRefusal(rawInput);
+  if (retired !== null) throw invalidParams(TOOL_NAME20, retired);
   if (!isToolInput20(rawInput)) {
-    throw invalidParams(TOOL_NAME20, "invalid input. Optional: { handoff_path, goal, cwd, max_turns }.");
+    throw invalidParams(TOOL_NAME20, "invalid input. Optional: { handoff_path, goal, cwd, max_turns, agent }.");
   }
   const handoffPath = rawInput.handoff_path?.trim() || newestHandoff();
   if (!handoffPath || !existsSync4(handoffPath)) {
@@ -5494,20 +6559,37 @@ async function handleSpawnSuccessor(_deps, rawInput, _signal, spawnImpl = spawn)
       }
     });
   }
-  const handoff = readFileSync6(handoffPath, "utf8").slice(0, MAX_HANDOFF_BYTES);
+  const handoff = readFileSync7(handoffPath, "utf8").slice(0, MAX_HANDOFF_BYTES);
   const prompt = buildSuccessorPrompt(handoff, rawInput.goal);
-  const logDir = process.env["VO_MCP_SUCCESSOR_LOG_DIR"]?.trim() || join6(homedir4(), ".vo", "successors");
-  mkdirSync3(logDir, { recursive: true });
-  const logPath = join6(logDir, `successor-${Date.now()}.log`);
-  const logFd = openSync(logPath, "a");
-  const child = spawnImpl("claude", buildSuccessorArgs(rawInput.max_turns), {
+  const plan = resolveSpawnPlan(process.env, rawInput, (/* @__PURE__ */ new Date()).toISOString());
+  if (!plan.ok) {
+    return jsonContent({
+      tool: TOOL_NAME20,
+      schema_version: 1,
+      payload: {
+        spawned: false,
+        reason: `swarm tier binding refused this spawn: ${plan.reason}`,
+        tier: plan.tier,
+        handoff_path: handoffPath
+      }
+    });
+  }
+  const logDir = process.env["VO_MCP_SUCCESSOR_LOG_DIR"]?.trim() || join7(homedir5(), ".vo", "successors");
+  mkdirSync4(logDir, { recursive: true });
+  const logPath = join7(logDir, `successor-${Date.now()}.log`);
+  const logFd = openSync2(logPath, "a");
+  const child = spawnImpl(plan.bin, [...plan.args], {
     cwd: rawInput.cwd?.trim() || process.cwd(),
     detached: true,
     stdio: ["pipe", logFd, logFd],
-    // Windows: `claude` is a .cmd shim — needs a shell to resolve. The prompt
-    // goes via STDIN below, never argv, so the shell never sees it.
+    // Windows: the agent CLIs are .cmd shims — they need a shell to resolve.
+    // The prompt goes via STDIN below, never argv, so the shell never sees it.
     shell: process.platform === "win32",
-    windowsHide: true
+    windowsHide: true,
+    // Carry the SAME binding to the child. Without this the successor inherits
+    // no tier and re-resolves its own — which is the split-payer defect one
+    // generation down.
+    ...plan.bound ? { env: { ...process.env, ...plan.env } } : {}
   });
   let spawnError = null;
   child.on("error", (e) => {
@@ -5523,7 +6605,20 @@ async function handleSpawnSuccessor(_deps, rawInput, _signal, spawnImpl = spawn)
   return jsonContent({
     tool: TOOL_NAME20,
     schema_version: 1,
-    payload: spawnError ? { spawned: false, reason: `spawn failed: ${spawnError}`, handoff_path: handoffPath } : { spawned: true, pid: child.pid ?? null, log_path: logPath, handoff_path: handoffPath }
+    payload: spawnError ? { spawned: false, reason: `spawn failed: ${spawnError}`, agent: plan.agent, tier: plan.tier, handoff_path: handoffPath } : {
+      spawned: true,
+      pid: child.pid ?? null,
+      log_path: logPath,
+      handoff_path: handoffPath,
+      agent: plan.agent,
+      tier: plan.tier,
+      tier_bound: plan.bound,
+      ledger_slot: plan.slot,
+      // The debit, surfaced so an operator can reconcile a fan-out's spend
+      // against the pool without reading the ledger directory by hand.
+      ledger_cap_usd: plan.capUsd,
+      ledger_cap_remaining_usd: plan.capRemainingUsd
+    }
   });
 }
 
@@ -5885,12 +6980,12 @@ async function handleHqWhiteboardRead(_deps, rawInput, signal) {
 }
 
 // src/tools/skills/skill-corpus.ts
-import { existsSync as existsSync7, statSync as statSync5 } from "node:fs";
-import { dirname as dirname5, isAbsolute, join as join9, resolve as resolve2 } from "node:path";
+import { existsSync as existsSync9, statSync as statSync6 } from "node:fs";
+import { dirname as dirname5, isAbsolute, join as join13, resolve as resolve2 } from "node:path";
 
 // ../skill-registry/src/loader.ts
-import { readdirSync as readdirSync6, readFileSync as readFileSync9, statSync as statSync4 } from "node:fs";
-import { join as join8 } from "node:path";
+import { readdirSync as readdirSync6, readFileSync as readFileSync14, statSync as statSync5 } from "node:fs";
+import { join as join12 } from "node:path";
 var InvalidSkillFrontmatterError = class extends Error {
   constructor(skillFile, reason) {
     super(`Invalid frontmatter in ${skillFile}: ${reason}`);
@@ -5943,18 +7038,18 @@ function loadSkillsFromDir(skillsDir) {
   const entries = readdirSync6(skillsDir);
   const skills = [];
   for (const entry of entries) {
-    const entryPath = join8(skillsDir, entry);
+    const entryPath = join12(skillsDir, entry);
     let stat;
     try {
-      stat = statSync4(entryPath);
+      stat = statSync5(entryPath);
     } catch {
       continue;
     }
     if (!stat.isDirectory()) continue;
-    const skillFile = join8(entryPath, "SKILL.md");
+    const skillFile = join12(entryPath, "SKILL.md");
     let raw;
     try {
-      raw = readFileSync9(skillFile, "utf8");
+      raw = readFileSync14(skillFile, "utf8");
     } catch {
       continue;
     }
@@ -5996,12 +7091,12 @@ function resolveSkillsDir(env = process.env, startDir = process.cwd()) {
   const override = env.VO_SKILLS_DIR;
   if (typeof override === "string" && override.length > 0) {
     const abs = isAbsolute(override) ? override : resolve2(startDir, override);
-    return existsSync7(abs) && statSync5(abs).isDirectory() ? abs : null;
+    return existsSync9(abs) && statSync6(abs).isDirectory() ? abs : null;
   }
   let dir = resolve2(startDir);
   for (let i = 0; i < MAX_WALK_UP_LEVELS; i += 1) {
-    const candidate = join9(dir, ".claude", "skills");
-    if (existsSync7(candidate) && statSync5(candidate).isDirectory()) return candidate;
+    const candidate = join13(dir, ".claude", "skills");
+    if (existsSync9(candidate) && statSync6(candidate).isDirectory()) return candidate;
     const parent = dirname5(dir);
     if (parent === dir) break;
     dir = parent;
@@ -6312,7 +7407,7 @@ function buildToolRegistry() {
   };
 }
 function createServer(options) {
-  const sessionId = options.sessionId ?? randomUUID2();
+  const sessionId = options.sessionId ?? randomUUID3();
   const mode = createLocalMode();
   const now = options.now ?? (() => /* @__PURE__ */ new Date());
   const server = new Server(
@@ -6361,8 +7456,8 @@ function createServer(options) {
 }
 
 // src/cache/sqlite-cache.ts
-import { createHash as createHash3 } from "node:crypto";
-import { chmodSync as chmodSync3, mkdirSync as mkdirSync5 } from "node:fs";
+import { createHash as createHash4 } from "node:crypto";
+import { chmodSync as chmodSync3, mkdirSync as mkdirSync7 } from "node:fs";
 import { dirname as dirname6 } from "node:path";
 import { DatabaseSync } from "node:sqlite";
 
@@ -6408,7 +7503,7 @@ function normalizeString(s) {
 function createSqliteCache(options) {
   const fileBacked = options.dbPath !== ":memory:";
   if (fileBacked) {
-    mkdirSync5(dirname6(options.dbPath), { recursive: true, mode: 448 });
+    mkdirSync7(dirname6(options.dbPath), { recursive: true, mode: 448 });
   }
   const versionNamespace = options.cacheVersionNamespace ?? "";
   const db = new DatabaseSync(options.dbPath);
@@ -6439,7 +7534,7 @@ function createSqliteCache(options) {
   return {
     keyFor(toolName, input, opts) {
       const canonical = canonicalize(input, opts);
-      const hash = createHash3("sha256");
+      const hash = createHash4("sha256");
       if (versionNamespace.length > 0) {
         hash.update(versionNamespace);
         hash.update("|");
@@ -6534,7 +7629,7 @@ function createStubRatchetClient() {
         let m;
         while ((m = pat.regex.exec(req.source)) !== null) {
           findings.push({
-            line_excerpt: clip(m[0], 80),
+            line_excerpt: clip2(m[0], 80),
             severity: pat.severity,
             code: pat.code,
             message: pat.message
@@ -6566,7 +7661,7 @@ function createStubRatchetClient() {
     }
   };
 }
-function clip(s, n) {
+function clip2(s, n) {
   return s.length <= n ? s : s.slice(0, n) + "\u2026";
 }
 function buildSummary2(args) {
@@ -6577,7 +7672,7 @@ function buildSummary2(args) {
 // src/consensus/engine-client.ts
 init_events_writer();
 init_common();
-import { randomUUID as randomUUID3 } from "node:crypto";
+import { randomUUID as randomUUID4 } from "node:crypto";
 
 // src/consensus/null-client.ts
 var NULL_CLIENT_DEFAULT_REASON = "consensus-engine-package-pending";
@@ -7037,7 +8132,7 @@ function tryCreateEngineConsensusClientFromEnv(options = {}) {
 }
 
 // src/consensus/moat-client.ts
-import { randomUUID as randomUUID4 } from "node:crypto";
+import { randomUUID as randomUUID5 } from "node:crypto";
 
 // src/consensus/client.ts
 var CANCELLED_REASON = "cancelled";
@@ -7089,7 +8184,7 @@ function createMoatConsensusClient(opts) {
       request.signal?.addEventListener("abort", onAbort, { once: true });
       const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
       const body = JSON.stringify({
-        task_id: randomUUID4(),
+        task_id: randomUUID5(),
         gate_type: request.gate_type,
         excerpt: request.prompt,
         ...request.system_prompt ? { question: request.system_prompt } : {},
@@ -7410,7 +8505,7 @@ init_common();
 function defaultCacheDbPath() {
   const env = process.env["VO_MCP_DB_PATH"];
   if (env && env.length > 0) return env;
-  return join10(homedir6(), ".claude", "vo-mcp-cache.db");
+  return join14(homedir8(), ".claude", "vo-mcp-cache.db");
 }
 async function probeEngineVersion() {
   try {
@@ -7537,7 +8632,7 @@ async function main() {
 }
 if (process.argv[2] === "login") {
   const controlPlaneUrl = process.env["VO_CONTROL_PLANE_URL"]?.trim();
-  const credentialLabel = `vo-mcp-cli@${hostname()}`.slice(0, 200);
+  const credentialLabel = `vo-mcp-cli@${hostname2()}`.slice(0, 200);
   runLogin(
     controlPlaneUrl ? {
       exchange: (refreshToken, apiKey) => exchangeForVoCredential({ refreshToken, apiKey, controlPlaneUrl, label: credentialLabel })
@@ -7553,26 +8648,29 @@ if (process.argv[2] === "login") {
 } else if (process.argv[2] === "sync") {
   const action = process.argv[3];
   if (action !== "push" && action !== "pull") {
-    console.error("[vo-mcp] usage: vo-mcp sync <push|pull> [--cwd <path>]");
+    console.error("[vo-mcp] usage: vo-mcp sync <push|pull> [--cwd <path>] [--lock-wait-ms <n>]");
     process.exit(2);
   }
   const cwdFlag = process.argv.indexOf("--cwd");
   const cwd = cwdFlag >= 0 && typeof process.argv[cwdFlag + 1] === "string" ? process.argv[cwdFlag + 1] : process.cwd();
-  const sessionId = randomUUID5();
+  const waitFlag = process.argv.indexOf("--lock-wait-ms");
+  const parsedWait = waitFlag >= 0 ? Number(process.argv[waitFlag + 1]) : Number.NaN;
+  const lockOptions = Number.isFinite(parsedWait) && parsedWait >= 0 ? { waitMs: parsedWait } : {};
+  const sessionId = randomUUID6();
   const appendSyncLog = async (line) => {
     try {
-      const { appendFileSync: appendFileSync2, mkdirSync: mkdirSync6 } = await import("node:fs");
-      const { join: join11 } = await import("node:path");
-      const { homedir: homedir7 } = await import("node:os");
-      const dir = join11(homedir7(), ".claude");
-      mkdirSync6(dir, { recursive: true });
-      appendFileSync2(join11(dir, "vo-mcp-sync.log"), `${line}
+      const { appendFileSync: appendFileSync2, mkdirSync: mkdirSync8 } = await import("node:fs");
+      const { join: join15 } = await import("node:path");
+      const { homedir: homedir9 } = await import("node:os");
+      const dir = join15(homedir9(), ".claude");
+      mkdirSync8(dir, { recursive: true });
+      appendFileSync2(join15(dir, "vo-mcp-sync.log"), `${line}
 `, "utf8");
     } catch {
     }
   };
   Promise.resolve().then(() => (init_sync_config(), sync_config_exports)).then(async ({ runMemorySync: runMemorySync2, isNoopSyncReason: isNoopSyncReason2 }) => {
-    const r = await runMemorySync2(action, cwd, sessionId);
+    const r = await runMemorySync2(action, cwd, sessionId, void 0, lockOptions);
     const stamp = `${sessionId} ${action}`;
     if (r.synced) {
       console.error(`[vo-mcp] sync ${action} ok: ${JSON.stringify(r)}`);