kith-coord 0.1.4 → 0.1.6

package/dist/cli/index.js

@@ -6,8 +6,8 @@ import path19 from "path";
 import { spawn } from "child_process";
 
 // src/version.ts
-var KITH_VERSION = "0.1.4";
-var KITH_PROTOCOL_VERSION = "1.3.0";
+var KITH_VERSION = "0.1.6";
+var KITH_PROTOCOL_VERSION = "1.4.0";
 
 // src/cli/setup-ledger.ts
 import fs2 from "fs";
@@ -343,7 +343,7 @@ var CoordDatabase = class _CoordDatabase {
     }
     if (!tables.some((table) => table.name === "meta")) throw new Error("Missing coordination schema metadata. Preserve the database before repair.");
     const row = db.prepare("SELECT value FROM meta WHERE key='schema_version'").get();
-    if (row?.value !== "1" && row?.value !== "2") {
+    if (row?.value !== "1" && row?.value !== "2" && row?.value !== "3") {
       throw new Error(`Unsupported coordination schema version: ${String(row?.value)}. Preserve the database before upgrading or repairing it.`);
     }
     const version = Number(row.value);
@@ -358,7 +358,8 @@ var CoordDatabase = class _CoordDatabase {
       "resources",
       "quarantine",
       "events",
-      ...version === 2 ? ["agent_sessions", "mutex_waiters", "mutex_runs"] : []
+      ...version >= 2 ? ["agent_sessions", "mutex_waiters", "mutex_runs"] : [],
+      ...version >= 3 ? ["mcp_operations"] : []
     ];
     if (required.some((name) => !tables.some((table) => table.name === name))) {
       throw new Error("Incomplete coordination schema. Preserve the database before repair.");
@@ -368,11 +369,12 @@ var CoordDatabase = class _CoordDatabase {
       tasks: "status,owner_agent_id,fencing_token,scope_globs_json,depends_on_json",
       locks: "owner_agent_id,pattern,mode,fencing_token,expires_at",
       resources: "type,name,owner_agent_id,fencing_token,expires_at",
-      ...version === 2 ? {
+      ...version >= 2 ? {
         agent_sessions: "agent_id,token_hash,epoch",
         mutex_waiters: "ticket,mutex_name,request_id,owner_agent_id,session_epoch,waiter_pid,waiter_start,expires_at",
         mutex_runs: "mutex_name,run_id,owner_agent_id,session_epoch,fencing_token,supervisor_pid,supervisor_start,worker_pid,worker_start"
-      } : {}
+      } : {},
+      ...version >= 3 ? { mcp_operations: "operation_key,request_hash,agent_id,session_epoch,capability_hash,owner_pid,owner_start,result_json,created_at" } : {}
     };
     for (const [table, fields] of Object.entries(columns)) {
       try {
@@ -387,7 +389,8 @@ var CoordDatabase = class _CoordDatabase {
       "SELECT fencing_token FROM tasks",
       "SELECT fencing_token FROM resources",
       "SELECT fencing_token FROM merge_queue",
-      ...version === 2 ? ["SELECT epoch FROM agent_sessions", "SELECT session_epoch FROM mutex_waiters", "SELECT fencing_token FROM mutex_runs"] : []
+      ...version >= 2 ? ["SELECT epoch FROM agent_sessions", "SELECT session_epoch FROM mutex_waiters", "SELECT fencing_token FROM mutex_runs"] : [],
+      ...version >= 3 ? ["SELECT session_epoch FROM mcp_operations"] : []
     ];
     if (db.prepare(`SELECT 1 FROM (${tokens.join(" UNION ALL ")}) WHERE token IS NOT NULL AND (typeof(token)!='integer' OR token<0 OR token>?) LIMIT 1`).get(epoch)) {
       throw new Error("Invalid or regressed fencing counter. Preserve the database before repair.");
@@ -565,6 +568,14 @@ var CoordDatabase = class _CoordDatabase {
           worker_pid INTEGER, worker_start TEXT
         );
       `);
+      this.db.exec(`
+        CREATE TABLE IF NOT EXISTS mcp_operations (
+          operation_key TEXT PRIMARY KEY, request_hash TEXT NOT NULL,
+          agent_id TEXT NOT NULL, session_epoch INTEGER NOT NULL, capability_hash TEXT NOT NULL,
+          owner_pid INTEGER NOT NULL, owner_start TEXT NOT NULL,
+          result_json TEXT, created_at INTEGER NOT NULL
+        );
+      `);
       if (version < 2) {
         this.db.exec(`
           UPDATE tasks SET status='queued', owner_agent_id=NULL, fencing_token=NULL
@@ -576,6 +587,7 @@ var CoordDatabase = class _CoordDatabase {
           UPDATE meta SET value='2' WHERE key='schema_version';
         `);
       }
+      this.db.exec("UPDATE meta SET value='3' WHERE key='schema_version'");
     });
   }
   /**
@@ -793,7 +805,7 @@ function previewIntegration(repoRoot, agent) {
 
 // src/core/observation.ts
 var { DatabaseSync: DatabaseSync2 } = createRequire2(import.meta.url)("node:sqlite");
-function readCoordinationState(directory = process.cwd()) {
+function readCoordinationState(directory = process.cwd(), options = {}) {
   const layout = discoverRepository(directory), observedAt = Date.now();
   const empty = {
     protocolVersion: KITH_PROTOCOL_VERSION,
@@ -849,9 +861,13 @@ function readCoordinationState(directory = process.cwd()) {
     if (JSON.stringify(before) !== JSON.stringify(files.map(identity))) throw new Error("Coordination state changed during snapshot; stop writers or retry");
     db = new DatabaseSync2(path4.join(scratch, "state.db"), { readOnly: true });
     db.exec("PRAGMA query_only=ON; PRAGMA busy_timeout=1000; BEGIN");
-    if (CoordDatabase.inspectSchema(db) !== 2) throw new Error("Offline observation requires schema 2; preserve state and upgrade with clients stopped");
+    if (CoordDatabase.inspectSchema(db) < 2) throw new Error("Offline observation requires schema 2 or newer; preserve state and upgrade with clients stopped");
     const all = (sql) => db.prepare(sql).all();
     const agents = all("SELECT * FROM agents ORDER BY registered_at DESC");
+    if (options.ownersOnly) {
+      db.exec("COMMIT");
+      return { ...empty, state: "ready", agents };
+    }
     const state = {
       ...empty,
       state: "ready",
@@ -1618,10 +1634,10 @@ var LockEngine = class _LockEngine {
   static normalizePattern(repoRoot, rawPattern) {
     if (rawPattern.startsWith("file:")) return _LockEngine.literalScope(_LockEngine.normalizeFile(repoRoot, rawPattern.slice(5)));
     if (rawPattern.startsWith("symbol:")) {
-      const hash = rawPattern.indexOf("#");
-      const name = rawPattern.slice(hash + 1);
-      if (hash < 0 || !/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name)) throw new Error("Symbol scope must include #symbolName");
-      const file = _LockEngine.normalizeFile(repoRoot, rawPattern.slice(7, hash));
+      const hash2 = rawPattern.indexOf("#");
+      const name = rawPattern.slice(hash2 + 1);
+      if (hash2 < 0 || !/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name)) throw new Error("Symbol scope must include #symbolName");
+      const file = _LockEngine.normalizeFile(repoRoot, rawPattern.slice(7, hash2));
       return `symbol:${file}#${name}`;
     }
     if (!rawPattern || /[\\\x00-\x1f\x7f]/u.test(rawPattern)) throw new Error(`Invalid repository scope: ${rawPattern}`);
@@ -1876,9 +1892,9 @@ var LockEngine = class _LockEngine {
         return !this.pathCase.get(root);
       });
       const fold = (scope) => {
-        const hash = scope.startsWith("symbol:") ? scope.lastIndexOf("#") : -1;
-        const file = hash < 0 ? scope : scope.slice(0, hash);
-        return file.normalize("NFC").toLowerCase().replace(/ς/g, "\u03C3") + (hash < 0 ? "" : scope.slice(hash));
+        const hash2 = scope.startsWith("symbol:") ? scope.lastIndexOf("#") : -1;
+        const file = hash2 < 0 ? scope : scope.slice(0, hash2);
+        return file.normalize("NFC").toLowerCase().replace(/ς/g, "\u03C3") + (hash2 < 0 ? "" : scope.slice(hash2));
       };
       const overlap = (a, b) => _LockEngine.patternsOverlap(a, b) || insensitive && _LockEngine.patternsOverlap(fold(a), fold(b));
       return overlap(requested, existing) || overlap(requested, normalized) || this.wildcardHasAliases(requested) || this.wildcardHasAliases(normalized);
@@ -2477,7 +2493,7 @@ var ResourceBroker = class _ResourceBroker {
           worker.once("error", reject);
         }), stopped]);
         if (params.signal?.aborted) failure ??= abortError();
-        if (failure) throw failure;
+        if (failure) throw Object.assign(failure, { stdout: Buffer.concat(stdout).toString(), stderr: Buffer.concat(stderr).toString() });
         if (!outcome) throw new Error("Command worker exited without a result");
         if (outcome.error) throw new Error(outcome.error);
         return { stdout: Buffer.concat(stdout).toString(), stderr: Buffer.concat(stderr).toString(), exitCode: outcome.exitCode, waitedMs };
@@ -4042,25 +4058,188 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import fs16 from "fs";
 import path15 from "path";
+
+// src/mcp/retries.ts
+import crypto11 from "crypto";
+var RetryError = class extends Error {
+  constructor(code, message, retryable = false) {
+    super(message);
+    this.code = code;
+    this.retryable = retryable;
+  }
+  code;
+  retryable;
+};
+function failureData(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  let code = "OPERATION_FAILED", retryable = false;
+  if (error instanceof RetryError) {
+    code = error.code;
+    retryable = error.retryable;
+  } else if (error instanceof SessionOwnershipError) code = "SESSION_OWNERSHIP";
+  else if (error instanceof StaleFencingTokenError) code = "STALE_FENCING_TOKEN";
+  else if (error instanceof Error && error.name === "AbortError") code = "CANCELLED";
+  else if (message.startsWith("Timed out waiting for mutex ")) {
+    code = "MUTEX_WAIT_TIMEOUT";
+    retryable = true;
+  } else if (message === "Mutex command execution timed out") code = "COMMAND_TIMEOUT";
+  else if (message === "Mutex command output limit exceeded") code = "COMMAND_OUTPUT_LIMIT";
+  else if (/SQLITE_BUSY|database is locked/.test(message)) code = "DATABASE_BUSY";
+  else if (/schema|coordination database|fencing counter|recovery state/i.test(message)) code = "STATE_UNAVAILABLE";
+  else if (/repository|checkout path|project selected|connection is pinned|Command cwd|Invalid agent ID|Lease duration|Unsupported.*pattern/i.test(message)) code = "INVALID_REQUEST";
+  const details = error;
+  return {
+    ok: false,
+    error: message,
+    failure: {
+      code,
+      message,
+      retryable,
+      ...retryable ? { retryAfterMs: 100 } : {}
+    },
+    ...typeof details?.stdout === "string" ? { stdout: details.stdout } : {},
+    ...typeof details?.stderr === "string" ? { stderr: details.stderr } : {}
+  };
+}
+function classifyResult(data) {
+  if (data.ok !== false || data.failure) return data;
+  if (data.mergeResult) return { ...data, failure: {
+    code: "INTEGRATION_FAILED",
+    retryable: false,
+    message: "Inspect mergeResult.diagnostics and repair or preserve the source worktree before a new completion attempt."
+  } };
+  if (Array.isArray(data.lockConflicts) || Array.isArray(data.conflicts)) return { ...data, failure: {
+    code: data.waitTimedOut ? "CLAIM_WAIT_TIMEOUT" : "CLAIM_CONFLICT",
+    retryable: true,
+    retryAfterMs: 100,
+    message: "Scope is owned by another session. Back off before a new attempt (with a new operationKey if used)."
+  } };
+  if (typeof data.exitCode === "number") return { ...data, failure: {
+    code: "COMMAND_FAILED",
+    retryable: false,
+    message: "Inspect stdout, stderr and exitCode; commands may have partial effects. Repair before a new attempt."
+  } };
+  return { ...data, failure: {
+    code: "OPERATION_FAILED",
+    retryable: false,
+    message: typeof data.error === "string" ? data.error : "Inspect the result before a new attempt."
+  } };
+}
+function toolReply(data, footer = []) {
+  data = classifyResult(data);
+  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }, ...footer], structuredContent: data, isError: data.ok === false };
+}
+var hash = (text) => crypto11.createHash("sha256").update(text).digest("hex");
+function canonical(value) {
+  if (Array.isArray(value)) return "[" + value.map(canonical).join(",") + "]";
+  if (value && typeof value === "object") return "{" + Object.entries(value).filter(([, v]) => v !== void 0).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => JSON.stringify(k) + ":" + canonical(v)).join(",") + "}";
+  return JSON.stringify(value);
+}
+var OperationJournal = class _OperationJournal {
+  constructor(db) {
+    this.db = db;
+  }
+  db;
+  static undurable = /* @__PURE__ */ new Set();
+  async execute(params) {
+    const { operationKey: _key, sessionToken: _token, ...input } = params.input;
+    const localKey = this.db.dbPath + ":" + params.key;
+    const requestHash = hash(canonical({ tool: params.tool, checkout: this.db.repoRoot, input }));
+    const operation = (state, replayed) => ({ key: params.key, state, replayed });
+    const previous = this.db.withTransaction(() => {
+      const row = this.db.db.prepare("SELECT * FROM mcp_operations WHERE operation_key=?").get(params.key);
+      if (row) {
+        const token = params.token();
+        if (!token || row.agent_id !== params.agentId || hash(token) !== row.capability_hash) throw new SessionOwnershipError(params.agentId ?? "");
+        if (row.request_hash !== requestHash) throw new RetryError("OPERATION_KEY_REUSED", "operationKey already identifies a different tool, checkout or input. Use a new key for new work.");
+        return row;
+      }
+      const identity = params.authorize();
+      const start = FencingAndAgentManager.getProcessStartTime(process.pid);
+      if (!start) throw new RetryError("STATE_UNAVAILABLE", "Cannot identify operation owner; no operation was started.");
+      this.db.db.prepare(`INSERT INTO mcp_operations
+        (operation_key,request_hash,agent_id,session_epoch,capability_hash,owner_pid,owner_start,result_json,created_at)
+        VALUES (?,?,?,?,?,?,?,NULL,?)`).run(
+        params.key,
+        requestHash,
+        identity.agentId,
+        identity.sessionEpoch,
+        hash(identity.token),
+        process.pid,
+        start,
+        Date.now()
+      );
+      return void 0;
+    });
+    if (previous) {
+      if (previous.result_json !== null) {
+        let saved2;
+        try {
+          saved2 = JSON.parse(previous.result_json);
+          if (!saved2.data || typeof saved2.data !== "object" || Array.isArray(saved2.data) || typeof saved2.grantsToken !== "boolean") throw new Error();
+        } catch {
+          throw new RetryError("STATE_UNAVAILABLE", "Unreadable operation result. Preserve coordination state before repair.");
+        }
+        return toolReply({ ...saved2.data, ...saved2.grantsToken ? { sessionToken: params.token() } : {}, operation: operation("completed", true) });
+      }
+      const alive = !_OperationJournal.undurable.has(localKey) && FencingAndAgentManager.isProcessAlive(previous.owner_pid, previous.owner_start);
+      return toolReply({
+        ...failureData(new RetryError(
+          alive ? "OPERATION_IN_PROGRESS" : "OPERATION_OUTCOME_UNKNOWN",
+          alive ? "Operation has not returned a durable result. Retry this same key after backoff; do not start a duplicate." : "Operation result was not recorded after its owner stopped or persistence failed. Inspect status, worktrees and external effects before deliberately starting new work with a new key.",
+          alive
+        )),
+        operation: operation(alive ? "running" : "unknown", true)
+      });
+    }
+    let reply;
+    try {
+      reply = await params.run();
+    } catch (error) {
+      reply = toolReply(failureData(error));
+    }
+    const data = reply.structuredContent;
+    const { sessionToken, ...saved } = data;
+    try {
+      const result = this.db.db.prepare("UPDATE mcp_operations SET result_json=? WHERE operation_key=? AND result_json IS NULL").run(JSON.stringify({ data: saved, grantsToken: typeof sessionToken === "string" }), params.key);
+      if (Number(result.changes) !== 1) throw new Error("Operation result was not recorded");
+    } catch {
+      _OperationJournal.undurable.add(localKey);
+      return toolReply({
+        ...failureData(new RetryError(
+          "OPERATION_OUTCOME_UNKNOWN",
+          "The operation may have completed but its result could not be recorded. Preserve state and inspect effects; do not repeat it automatically."
+        )),
+        operation: operation("unknown", false)
+      });
+    }
+    return toolReply({ ...data, operation: operation("completed", false) }, reply.content.slice(1));
+  }
+};
+
+// src/mcp/server.ts
 function buildKithMcpServer(repoRoot, pinned) {
   const pinnedRoot = pinned ? discoverRepository(repoRoot).checkoutRoot : void 0;
   const server = new McpServer({
     name: "kith-coordinator",
     version: KITH_VERSION
-  }, { instructions: "Kith coordinates work claims, isolated worktrees, local resources and verified integration for cooperating coding agents. State stays local; no hosted service or model API key is required. The optional repository argument selects an absolute Git checkout for each call on a global connection. Keep passing the original checkout, even while editing its returned worktree. If no project context is available, ask for a repository path; never substitute HOME or a filesystem root. Each call is routed independently; there is no shared current project. Recommended workflow: one isolated worktree per parallel agent. Call kith_begin_work with isolateWorktree:true and explicit scopeGlobs; edit only the returned worktreePath, call kith_record_file_edit, run literal argv with kith_run_with_mutex, and finish with kith_complete_work plus a project verificationCmd. Heartbeat before the session expires. " + (repoRoot && process.env.KITH_AGENT_ID ? `This server shares a session with CLI/hooks. Use agentId '${process.env.KITH_AGENT_ID}'. Its inherited capability is handled internally; do not request or log it.` : "Start with kith_begin_work or kith_start_session and a unique agentId. This connection retains its granted capability. Omit sessionToken on subsequent calls on this connection; only another connection needs it to resume that ID. Initial grant/resume replies contain the token and client transcripts may record it. Keep transcripts private.") });
+  }, { instructions: "Kith coordinates work claims, isolated worktrees, local resources and verified integration for cooperating coding agents. State stays local; no hosted service or model API key is required. The optional repository argument selects an absolute Git checkout for each call on a global connection. Keep passing the original checkout, even while editing its returned worktree. If no project context is available, ask for a repository path; never substitute HOME or a filesystem root. Each call is routed independently; there is no shared current project. Recommended workflow: one isolated worktree per parallel agent. Call kith_begin_work with isolateWorktree:true and explicit scopeGlobs; edit only the returned worktreePath, call kith_record_file_edit, run literal argv with kith_run_with_mutex, and finish with kith_complete_work plus a project verificationCmd. Heartbeat before the session expires. For mutations, generate a unique operationKey and reuse it only to recover that exact attempt after a timeout. Replay is a historical result, never a renewed claim. Inspect failure.code and failure.retryable; an unknown command outcome requires inspection, not automatic re-execution. " + (repoRoot && process.env.KITH_AGENT_ID ? `This server shares a session with CLI/hooks. Use agentId '${process.env.KITH_AGENT_ID}'. Its inherited capability is handled internally; do not request or log it.` : "Start with kith_begin_work or kith_start_session and a unique agentId. This connection retains its granted capability. Omit sessionToken on subsequent calls on this connection; only another connection needs it to resume that ID. Initial grant/resume replies contain the token and client transcripts may record it. Keep transcripts private.") });
   const disconnected = new AbortController();
   const commands = /* @__PURE__ */ new Set();
   const createContext = (root, inheritCapability) => {
     const engine2 = new KithEngine(root);
     const owned = /* @__PURE__ */ new Set();
-    const tokenFor = (args) => args.sessionToken ?? (inheritCapability && process.env.KITH_AGENT_ID === args.agentId ? process.env.KITH_SESSION_TOKEN : void 0);
+    const capabilities = /* @__PURE__ */ new Map();
+    const journal = new OperationJournal(engine2.coordDb);
+    const tokenFor = (args) => args.sessionToken ?? (inheritCapability && process.env.KITH_AGENT_ID === args.agentId ? process.env.KITH_SESSION_TOKEN : capabilities.get(args.agentId));
     const register = (args) => {
       const result = engine2.fencing.registerAgent({
         id: args.agentId,
         client: args.client ?? "mcp",
-        sessionToken: tokenFor(args),
+        sessionToken: args.sessionToken ?? (inheritCapability && process.env.KITH_AGENT_ID === args.agentId ? process.env.KITH_SESSION_TOKEN : void 0),
         leaseDurationMs: args.leaseDurationMs
       });
+      capabilities.set(args.agentId, result.sessionToken);
       if (result.agent.pid === process.pid) owned.add(args.agentId);
       return result;
     };
@@ -4072,10 +4251,7 @@ function buildKithMcpServer(repoRoot, pinned) {
     const formatReply = (agentId, payload) => {
       const delta = agentId ? engine2.consumeAgentDelta(agentId).formattedFooter : "";
       const data = payload;
-      return { content: [
-        { type: "text", text: JSON.stringify(data, null, 2) },
-        ...delta ? [{ type: "text", text: delta }] : []
-      ], structuredContent: data, isError: data.ok === false };
+      return toolReply(data, delta ? [{ type: "text", text: delta }] : []);
     };
     const close = () => {
       for (const id of owned) {
@@ -4086,7 +4262,7 @@ function buildKithMcpServer(repoRoot, pinned) {
       }
       engine2.close();
     };
-    return { engine: engine2, register, authorize, formatReply, close };
+    return { engine: engine2, register, authorize, formatReply, close, journal, tokenFor };
   };
   const contexts = /* @__PURE__ */ new Map();
   const contextFor = (repository) => {
@@ -4105,14 +4281,48 @@ function buildKithMcpServer(repoRoot, pinned) {
   };
   const engine = pinned ? contextFor().engine : void 0;
   const tool = (name, description, schema, handler) => {
-    const inputSchema = { ...schema, repository: z.string().optional().describe("Absolute Git checkout path. Required on global connections without project context. Always use the same original checkout for a task.") };
+    const keyed = !["kith_get_status", "kith_preview_integrate", "kith_heartbeat"].includes(name);
+    const inputSchema = { ...schema, ...keyed ? { operationKey: z.string().min(1).max(128).optional().describe("Unique client-generated key for this exact mutation. Reuse only to recover its result; never an ownership credential. Retried failures are snapshots; use a new key after repair or backoff.") } : {}, repository: z.string().optional().describe("Absolute Git checkout path. Required on global connections without project context. Always use the same original checkout for a task.") };
     server.tool(
       name,
       description,
       inputSchema,
       async (args, extra) => {
         const { repository, ...input } = args;
-        return handler(input, extra, contextFor(repository));
+        const execution = (async () => {
+          try {
+            const context = contextFor(repository);
+            const run = async () => {
+              extra.signal.throwIfAborted();
+              return handler(input, extra, context);
+            };
+            if (!keyed || input.operationKey === void 0) return await run();
+            const identity = input;
+            return await context.journal.execute({
+              key: input.operationKey,
+              tool: name,
+              input,
+              agentId: identity.agentId,
+              token: () => identity.agentId ? context.tokenFor({ ...identity, agentId: identity.agentId }) : void 0,
+              authorize: () => {
+                if (!identity.agentId) throw new RetryError("INVALID_REQUEST", "Keyed mutations require agentId and an owned session. Start a session first.");
+                const args2 = { ...identity, agentId: identity.agentId };
+                if (["kith_start_session", "kith_begin_work", "kith_claim_next_task"].includes(name)) context.register(args2);
+                else context.authorize(args2);
+                return { agentId: identity.agentId, sessionEpoch: context.engine.fencing.assertSession(identity.agentId), token: context.tokenFor(args2) };
+              },
+              run
+            });
+          } catch (error) {
+            return toolReply(failureData(error));
+          }
+        })();
+        commands.add(execution);
+        try {
+          return await execution;
+        } finally {
+          commands.delete(execution);
+        }
       }
     );
   };
@@ -4209,6 +4419,8 @@ function buildKithMcpServer(repoRoot, pinned) {
     "Add a task to the orchestrated DAG queue with optional task dependencies and file scope globs.",
     {
       id: z.string().optional(),
+      agentId: z.string().optional().describe("Required for operationKey; identifies an already owned session."),
+      sessionToken: z.string().optional(),
       title: z.string(),
       intentSummary: z.string().optional(),
       priority: z.number().optional(),
@@ -4216,6 +4428,7 @@ function buildKithMcpServer(repoRoot, pinned) {
       scopeGlobs: z.array(z.string()).optional()
     },
     async (args, extra, { engine: engine2, register, authorize, formatReply }) => {
+      if (args.agentId) authorize({ ...args, agentId: args.agentId });
       const task = engine2.intents.addTask(args);
       return formatReply(void 0, { ok: true, task });
     }
@@ -4896,17 +5109,17 @@ function contentIdentity(repo, file) {
   try {
     const before = fs19.fstatSync(fd);
     if (before.ino !== stat.ino || before.dev !== stat.dev || before.size !== stat.size || before.mtimeMs !== stat.mtimeMs) throw new Error(`File changed during comparison: ${file}`);
-    const hash = createHash("sha256");
+    const hash2 = createHash("sha256");
     const buffer = Buffer.allocUnsafe(64 * 1024);
     for (let offset = 0; offset < before.size; ) {
       const count = fs19.readSync(fd, buffer, 0, Math.min(buffer.length, before.size - offset), offset);
       if (!count) throw new Error(`File changed during comparison: ${file}`);
-      hash.update(buffer.subarray(0, count));
+      hash2.update(buffer.subarray(0, count));
       offset += count;
     }
     const after = fs19.fstatSync(fd);
     if (before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error(`File changed during comparison: ${file}`);
-    return `file:${before.mode & 73}:${hash.digest("hex")}`;
+    return `file:${before.mode & 73}:${hash2.digest("hex")}`;
   } finally {
     fs19.closeSync(fd);
   }
@@ -4925,6 +5138,8 @@ var PassiveConflictWatcher = class _PassiveConflictWatcher {
   activeCollisions = /* @__PURE__ */ new Map();
   repositories = /* @__PURE__ */ new Map();
   errors = [];
+  primaryRoots = /* @__PURE__ */ new Map();
+  worktrees = [];
   static notifyMac(title, message) {
     if (process.platform !== "darwin") return;
     try {
@@ -4935,6 +5150,7 @@ var PassiveConflictWatcher = class _PassiveConflictWatcher {
   discoverGitRepos() {
     this.errors = [];
     this.repositories.clear();
+    this.primaryRoots.clear();
     const candidates = [];
     const marker = (dir) => {
       try {
@@ -4963,6 +5179,7 @@ var PassiveConflictWatcher = class _PassiveConflictWatcher {
         const layout = discoverRepository(candidate);
         if (!layout.commonGitDir) throw new Error("Git repository unavailable");
         this.repositories.set(layout.checkoutRoot, layout.commonGitDir);
+        if (!layout.isLinkedWorktree) this.primaryRoots.set(layout.commonGitDir, layout.checkoutRoot);
         if (inspected.has(layout.commonGitDir)) continue;
         inspected.add(layout.commonGitDir);
         const listing = execFileSync10("git", ["worktree", "list", "--porcelain", "-z"], { cwd: layout.checkoutRoot, encoding: "utf8", timeout: 4e3, maxBuffer: 4 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] });
@@ -4970,6 +5187,7 @@ var PassiveConflictWatcher = class _PassiveConflictWatcher {
           const linked = discoverRepository(record.slice(9));
           if (linked.commonGitDir !== layout.commonGitDir) throw new Error("Worktree repository identity changed during discovery");
           this.repositories.set(linked.checkoutRoot, layout.commonGitDir);
+          if (!linked.isLinkedWorktree) this.primaryRoots.set(layout.commonGitDir, linked.checkoutRoot);
         }
       } catch (error) {
         this.errors.push({ repository: candidate, message: `Cannot inspect repository: ${error instanceof Error ? error.message : String(error)}` });
@@ -4982,10 +5200,11 @@ var PassiveConflictWatcher = class _PassiveConflictWatcher {
     const repos = this.discoverGitRepos();
     const now = Date.now();
     const seen = /* @__PURE__ */ new Set();
+    const dirtyCounts = /* @__PURE__ */ new Map();
     const overlaps = /* @__PURE__ */ new Map();
     for (const repo of repos) {
       try {
-        const { stdout } = await execFileAsync("git", ["-c", "core.fsmonitor=false", "status", "--porcelain=v1", "-z", "--untracked-files=all"], { cwd: repo, timeout: 4e3, maxBuffer: 4 * 1024 * 1024 });
+        const { stdout } = await execFileAsync("git", ["-c", "core.fsmonitor=false", "status", "--porcelain=v1", "-z", "--untracked-files=all"], { cwd: repo, timeout: 4e3, maxBuffer: 4 * 1024 * 1024, env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" } });
         const records = stdout.split("\0");
         const dirty = /* @__PURE__ */ new Map();
         for (let i = 0; i < records.length; i++) {
@@ -4995,6 +5214,7 @@ var PassiveConflictWatcher = class _PassiveConflictWatcher {
           dirty.set(record.slice(3), status);
           if (/[RC]/.test(status)) dirty.set(records[++i], status);
         }
+        dirtyCounts.set(repo, [...dirty.keys()].filter((file) => file && file !== ".coord" && !file.startsWith(".coord/")).length);
         for (const [file, status] of dirty) {
           if (!file || file === ".coord" || file.startsWith(".coord/")) continue;
           const key = JSON.stringify([repo, file]);
@@ -5051,6 +5271,39 @@ var PassiveConflictWatcher = class _PassiveConflictWatcher {
       }
     }
     this.activeCollisions = this.errors.length ? new Map([...this.activeCollisions, ...current]) : current;
+    const states = /* @__PURE__ */ new Map();
+    this.worktrees = repos.map((repo) => {
+      const common = this.repositories.get(repo);
+      const primary = this.primaryRoots.get(common);
+      const row = {
+        path: repo,
+        label: `${path17.basename(primary ?? path17.dirname(common))} / ${repo === primary ? "primary" : path17.basename(repo)}`,
+        activity: "unknown",
+        agentIds: [],
+        detail: "Ownership unavailable; inspect kith status --offline before recovery.",
+        dirtyFiles: dirtyCounts.get(repo) ?? null,
+        sharedDirtyPaths: [...this.activeCollisions.values()].filter((alert) => alert.repos.includes(repo)).length
+      };
+      try {
+        let state = states.get(common);
+        if (!state) {
+          state = readCoordinationState(primary ?? repo, { ownersOnly: true });
+          states.set(common, state);
+        }
+        if (state.state === "unavailable") {
+          row.detail += ` ${state.error}`;
+          return row;
+        }
+        const owners = state.agents.filter((agent) => agent.worktree_path ? physicalPath(agent.worktree_path) === repo : repo === primary);
+        const active = owners.filter((agent) => agent.status === "active" && Number.isFinite(agent.lease_expires_at) && agent.lease_expires_at > state.observedAt);
+        row.agentIds = (active.length ? active : owners).map((agent) => agent.id);
+        row.activity = active.length ? "active" : owners.length ? "retained" : "unregistered";
+        row.detail = active.length ? "Current recorded Kith lease; does not identify file writers." : owners.length ? `Recorded ${[...new Set(owners.map((agent) => agent.status === "active" ? "expired lease" : agent.status))].join(", ")}; preserve work and inspect before cleanup.` : "No recorded Kith session; activity and ownership outside Kith are unknown.";
+      } catch (error) {
+        row.detail += ` ${error instanceof Error ? error.message : String(error)}`;
+      }
+      return row;
+    });
     if (this.errors.length) this.options.onScanError?.(this.errors);
     return this.getActiveCollisions();
   }
@@ -5074,7 +5327,7 @@ var PassiveConflictWatcher = class _PassiveConflictWatcher {
     this.watchTimer = null;
   }
   getScanState() {
-    return { complete: this.errors.length === 0, errors: [...this.errors], repos: [...this.repositories.keys()] };
+    return { complete: this.errors.length === 0, errors: [...this.errors], repos: [...this.repositories.keys()], ownershipComplete: this.worktrees.every((row) => row.activity !== "unknown"), worktrees: this.worktrees.map((row) => ({ ...row, agentIds: [...row.agentIds] })) };
   }
   getActiveCollisions() {
     return [...this.activeCollisions.values()];
@@ -5375,13 +5628,13 @@ ${message}`);
         lastScanError = message;
       },
       onCollision: (alert) => {
-        if (!isRaw) {
+        if (!isRaw && !flags.once) {
           console.log(`
 \u26A0\uFE0F [WORKTREE OVERLAP] ${alert.message}`);
         }
       },
       onFileChange: (e) => {
-        if (!flags.quiet && !isRaw) {
+        if (!flags.quiet && !isRaw && !flags.once) {
           console.log(`\u{1F4DD} [FILE MTIME] ${path19.basename(e.repoPath)}/${e.filePath}`);
         }
       }
@@ -5400,6 +5653,12 @@ ${message}`);
 \u{1F4E1} Kith Passive Radar: ${targetDir}`);
       console.log(`   Repositories (${repos.length}): ${repos.map((r) => path19.basename(r)).join(", ")}`);
       console.log(`   Recent Modified Files: ${edits.length}`);
+      for (const row of state.worktrees) {
+        const activity = { active: "Active Kith lease", retained: "Retained", unregistered: "No Kith session", unknown: "Ownership unavailable" }[row.activity];
+        console.log(`   ${row.label} \u2014 ${activity}; ${row.dirtyFiles ?? "unknown"} Git changes; ${row.sharedDirtyPaths} shared dirty paths`);
+        console.log(`      ${row.path}${row.agentIds.length ? ` (${row.agentIds.join(", ")})` : ""}
+      ${row.detail}`);
+      }
       if (!state.complete) {
         console.error(`Scan unavailable:
 ${state.errors.map((error) => error.message).join("\n")}`);
@@ -5407,10 +5666,9 @@ ${state.errors.map((error) => error.message).join("\n")}`);
         console.log("\nNo differing or unverified shared dirty paths observed. Identical copies are excluded; compatibility is not verified.\n");
       } else {
         console.log(`
-  \u26A0\uFE0F  Observed worktree overlaps (${alerts.length}):`);
+  \u26A0\uFE0F  Review before integration: ${alerts.length} shared dirty paths:`);
         for (const a of alerts) {
           console.log(`   \u26A0\uFE0F ${a.message}`);
-          console.log(`      Files: ${a.filePath}`);
         }
         console.log("");
       }