kith-coord 0.1.2 → 0.1.3

package/dist/cli/index.js

@@ -1,8 +1,13 @@
 #!/usr/bin/env node
 
+// src/cli/index.ts
+import fs22 from "fs";
+import path19 from "path";
+import { spawn } from "child_process";
+
 // src/version.ts
-var KITH_VERSION = "0.1.2";
-var KITH_PROTOCOL_VERSION = "1.1.0";
+var KITH_VERSION = "0.1.3";
+var KITH_PROTOCOL_VERSION = "1.2.0";
 
 // src/cli/setup-ledger.ts
 import fs2 from "fs";
@@ -55,6 +60,9 @@ function repositoryFile(root, file) {
 }
 function discoverRepository(input) {
   const directory = fs.realpathSync.native(input);
+  if (directory === path.parse(directory).root) {
+    throw new Error("Cannot coordinate a filesystem root; select an explicit project with --repo.");
+  }
   if (!fs.statSync(directory).isDirectory()) throw new Error(`Not a directory: ${input}`);
   const git2 = (...args) => execFileSync("git", ["rev-parse", ...args], {
     cwd: directory,
@@ -988,6 +996,7 @@ var FencingAndAgentManager = class _FencingAndAgentManager {
   static DEFAULT_LEASE_MS = 5 * 60 * 1e3;
   capabilities = /* @__PURE__ */ new Map();
   static ownWindowsStart = null;
+  static inspectionFailure = null;
   static validateLease(duration) {
     if (!Number.isSafeInteger(duration) || duration < 100 || duration > 864e5) {
       throw new Error("Lease duration must be an integer between 100 and 86400000 milliseconds");
@@ -996,6 +1005,7 @@ var FencingAndAgentManager = class _FencingAndAgentManager {
   }
   /** A real kernel process identity; tests must not supply liveness sentinels. */
   static getProcessStartTime(pid) {
+    this.inspectionFailure = null;
     if (!Number.isSafeInteger(pid) || pid <= 0) return null;
     try {
       if (process.platform === "linux") {
@@ -1013,9 +1023,12 @@ var FencingAndAgentManager = class _FencingAndAgentManager {
             "-Command",
             `(Get-Process -Id ${pid} -ErrorAction Stop).StartTime.ToUniversalTime().Ticks.ToString([System.Globalization.CultureInfo]::InvariantCulture)`
           ],
-          { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5e3, windowsHide: true }
+          { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 15e3, windowsHide: true }
         ).trim();
-        if (!/^\d+$/.test(ticks)) return null;
+        if (!/^\d+$/.test(ticks)) {
+          this.inspectionFailure = "invalid kernel creation-time response";
+          return null;
+        }
         const identity = `windows:${ticks}`;
         if (pid === process.pid) this.ownWindowsStart = identity;
         return identity;
@@ -1027,7 +1040,9 @@ var FencingAndAgentManager = class _FencingAndAgentManager {
         env: { ...process.env, LC_ALL: "C" }
       }).trim();
       return out || null;
-    } catch {
+    } catch (error) {
+      const failure = error;
+      this.inspectionFailure = [failure.code, failure.status === void 0 ? null : `exit ${failure.status}`, failure.signal].filter(Boolean).join(", ") || "inspection unavailable";
       return null;
     }
   }
@@ -1057,7 +1072,7 @@ var FencingAndAgentManager = class _FencingAndAgentManager {
       if (params.sessionToken !== void 0) throw new SessionOwnershipError(params.id);
       const pid = params.pid ?? process.pid;
       const start = _FencingAndAgentManager.getProcessStartTime(pid);
-      if (!start) throw new Error(`Cannot determine start time of live session owner PID ${pid}`);
+      if (!start) throw new Error(`Cannot determine start time of live session owner PID ${pid} (${_FencingAndAgentManager.inspectionFailure ?? "inspection unavailable"})`);
       const now = Date.now();
       const epoch = this.coordDb.nextFencingToken();
       const token = crypto2.randomBytes(32).toString("base64url");
@@ -3917,73 +3932,105 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import fs16 from "fs";
 import path15 from "path";
-function createKithMcpServer(repoRoot = process.cwd()) {
-  const engine = new KithEngine(repoRoot);
+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. 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. " + (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 tokenFor = (args) => args.sessionToken ?? (process.env.KITH_AGENT_ID === args.agentId ? process.env.KITH_SESSION_TOKEN : void 0);
-  const owned = /* @__PURE__ */ new Set();
-  const register = (args) => {
-    const result = engine.fencing.registerAgent({
-      id: args.agentId,
-      client: args.client ?? "mcp",
-      sessionToken: tokenFor(args),
-      leaseDurationMs: args.leaseDurationMs
-    });
-    if (result.agent.pid === process.pid) owned.add(args.agentId);
-    return result;
-  };
-  const authorize = (args) => {
-    const token = tokenFor(args);
-    if (token) engine.fencing.resumeSession(args.agentId, token);
-    engine.fencing.heartbeat(args.agentId);
-  };
+  }, { 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.") });
   const disconnected = new AbortController();
   const commands = /* @__PURE__ */ new Set();
-  const cleanup = () => {
-    for (const id of owned) {
-      try {
-        engine.fencing.abandonAgentSession(id);
-      } catch {
+  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 register = (args) => {
+      const result = engine2.fencing.registerAgent({
+        id: args.agentId,
+        client: args.client ?? "mcp",
+        sessionToken: tokenFor(args),
+        leaseDurationMs: args.leaseDurationMs
+      });
+      if (result.agent.pid === process.pid) owned.add(args.agentId);
+      return result;
+    };
+    const authorize = (args) => {
+      const token = tokenFor(args);
+      if (token) engine2.fencing.resumeSession(args.agentId, token);
+      engine2.fencing.heartbeat(args.agentId);
+    };
+    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 };
+    };
+    const close = () => {
+      for (const id of owned) {
+        try {
+          engine2.fencing.abandonAgentSession(id);
+        } catch {
+        }
       }
-    }
-    engine.close();
+      engine2.close();
+    };
+    return { engine: engine2, register, authorize, formatReply, close };
+  };
+  const contexts = /* @__PURE__ */ new Map();
+  const contextFor = (repository) => {
+    if (repository !== void 0 && !path15.isAbsolute(repository)) throw new Error("repository must be an absolute Git checkout path.");
+    const target = repository ?? repoRoot;
+    if (!target) throw new Error("No project selected. Pass repository with the absolute Git checkout path for this task.");
+    const layout = discoverRepository(target);
+    if (pinnedRoot && layout.checkoutRoot !== pinnedRoot) throw new Error("This connection is pinned with --repo. Use a global connection to select another repository.");
+    if (!pinned && !layout.commonGitDir) throw new Error("Global connections require a Git checkout; do not use HOME or a parent directory as a project.");
+    let context = contexts.get(layout.checkoutRoot);
+    if (!context) {
+      context = createContext(layout.checkoutRoot, layout.checkoutRoot === (pinnedRoot ?? repoRoot));
+      contexts.set(layout.checkoutRoot, context);
+    }
+    return context;
+  };
+  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.") };
+    server.tool(
+      name,
+      description,
+      inputSchema,
+      async (args, extra) => {
+        const { repository, ...input } = args;
+        return handler(input, extra, contextFor(repository));
+      }
+    );
   };
   let closing = false;
   server.server.onclose = () => {
     if (closing) return;
     closing = true;
     disconnected.abort();
+    const cleanup = () => {
+      for (const context of contexts.values()) context.close();
+      contexts.clear();
+    };
     if (commands.size) void Promise.allSettled([...commands]).then(cleanup);
     else cleanup();
   };
-  const formatReply = (agentId, payload) => {
-    const delta = agentId ? engine.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
-    };
-  };
-  server.tool("kith_start_session", "Create a capability-owned session or resume one with its token.", {
+  tool("kith_start_session", "Create a capability-owned session or resume one with its token.", {
     agentId: z.string(),
     sessionToken: z.string().optional(),
     leaseDurationMs: z.number().optional()
-  }, async (args) => formatReply(void 0, { ok: true, ...register(args) }));
-  server.tool("kith_heartbeat", "Renew an active, owned session. Expired sessions cannot be revived.", {
+  }, async (args, extra, { engine: engine2, register, authorize, formatReply }) => formatReply(void 0, { ok: true, ...register(args) }));
+  tool("kith_heartbeat", "Renew an active, owned session. Expired sessions cannot be revived.", {
     agentId: z.string(),
     sessionToken: z.string().optional()
-  }, async (args) => {
+  }, async (args, extra, { engine: engine2, register, authorize, formatReply }) => {
     authorize(args);
-    return formatReply(args.agentId, { ok: true, agent: engine.fencing.getAgent(args.agentId) });
+    return formatReply(args.agentId, { ok: true, agent: engine2.fencing.getAgent(args.agentId) });
   });
-  server.tool(
+  tool(
     "kith_begin_work",
     "Register an agent session, verify no scope lock conflicts exist with sibling agents, acquire monotonic fencing-token locks, and optionally create an isolated Git worktree.",
     {
@@ -3995,19 +4042,19 @@ function createKithMcpServer(repoRoot = process.cwd()) {
       scopeGlobs: z.array(z.string()).describe('File paths or glob patterns this agent will edit (e.g. ["src/auth/**"])'),
       isolateWorktree: z.boolean().optional().describe("Recommended: true, giving each parallel agent a separate Git worktree")
     },
-    async (args) => {
+    async (args, extra, { engine: engine2, register, authorize, formatReply }) => {
       const reg = register(args);
-      const intentRes = engine.beginWork({
+      const intentRes = engine2.beginWork({
         agentId: args.agentId,
         title: args.title,
         intentSummary: args.intentSummary,
         scopeGlobs: args.scopeGlobs,
         isolateWorktree: args.isolateWorktree
       });
-      const contracts = engine.depGraph.listContracts().slice(0, 30);
+      const contracts = engine2.depGraph.listContracts().slice(0, 30);
       return formatReply(args.agentId, {
         ok: intentRes.ok,
-        agent: engine.fencing.getAgent(args.agentId),
+        agent: engine2.fencing.getAgent(args.agentId),
         sessionToken: reg.sessionToken,
         fencingToken: intentRes.fencingToken,
         task: intentRes.task,
@@ -4019,7 +4066,7 @@ function createKithMcpServer(repoRoot = process.cwd()) {
       });
     }
   );
-  server.tool(
+  tool(
     "kith_claim_next_task",
     "Atomically claim the highest-priority unblocked task from the DAG task queue and lock its declared file scope.",
     {
@@ -4027,13 +4074,13 @@ function createKithMcpServer(repoRoot = process.cwd()) {
       sessionToken: z.string().optional(),
       client: z.string().optional()
     },
-    async (args) => {
+    async (args, extra, { engine: engine2, register, authorize, formatReply }) => {
       const session = register(args);
-      const res = engine.intents.claimNextTask(args.agentId);
+      const res = engine2.intents.claimNextTask(args.agentId);
       return formatReply(args.agentId, { ...res, sessionToken: session.sessionToken });
     }
   );
-  server.tool(
+  tool(
     "kith_add_task",
     "Add a task to the orchestrated DAG queue with optional task dependencies and file scope globs.",
     {
@@ -4044,12 +4091,12 @@ function createKithMcpServer(repoRoot = process.cwd()) {
       dependsOn: z.array(z.string()).optional(),
       scopeGlobs: z.array(z.string()).optional()
     },
-    async (args) => {
-      const task = engine.intents.addTask(args);
+    async (args, extra, { engine: engine2, register, authorize, formatReply }) => {
+      const task = engine2.intents.addTask(args);
       return formatReply(void 0, { ok: true, task });
     }
   );
-  server.tool(
+  tool(
     "kith_check_and_lock_files",
     "Acquire exclusive or shared fencing-token locks on file paths, globs, or symbols.",
     {
@@ -4059,13 +4106,13 @@ function createKithMcpServer(repoRoot = process.cwd()) {
       mode: z.enum(["exclusive", "shared"]).optional(),
       reason: z.string().optional()
     },
-    async (args) => {
+    async (args, extra, { engine: engine2, register, authorize, formatReply }) => {
       authorize(args);
-      const res = engine.locks.acquireLocks(args);
+      const res = engine2.locks.acquireLocks(args);
       return formatReply(args.agentId, res);
     }
   );
-  server.tool(
+  tool(
     "kith_record_file_edit",
     "Analyze a modified file for supported contract signatures, flag exact name/kind matches in other files as non-blocking reuse hints, check transitive import blast radius, and run a live dirty-tree git merge-tree conflict check.",
     {
@@ -4074,9 +4121,9 @@ function createKithMcpServer(repoRoot = process.cwd()) {
       filePath: z.string(),
       content: z.string().optional()
     },
-    async (args) => {
+    async (args, extra, { engine: engine2, register, authorize, formatReply }) => {
       authorize(args);
-      const res = engine.processPostFileEdit({
+      const res = engine2.processPostFileEdit({
         agentId: args.agentId,
         filePath: args.filePath,
         content: args.content
@@ -4084,7 +4131,7 @@ function createKithMcpServer(repoRoot = process.cwd()) {
       return formatReply(args.agentId, res);
     }
   );
-  server.tool(
+  tool(
     "kith_publish_contract",
     "Explicitly publish a shared interface, function signature, API route, or schema to the Contract Blackboard.",
     {
@@ -4096,13 +4143,13 @@ function createKithMcpServer(repoRoot = process.cwd()) {
       signature: z.string(),
       docComment: z.string().optional()
     },
-    async (args) => {
+    async (args, extra, { engine: engine2, register, authorize, formatReply }) => {
       authorize(args);
-      const contract = engine.depGraph.publishExplicitContract(args);
+      const contract = engine2.depGraph.publishExplicitContract(args);
       return formatReply(args.agentId, { ok: true, contract });
     }
   );
-  server.tool(
+  tool(
     "kith_acquire_port",
     "Reserve a local TCP port among cooperating Kith clients; start the service promptly and handle unrelated bind races.",
     {
@@ -4111,13 +4158,13 @@ function createKithMcpServer(repoRoot = process.cwd()) {
       serviceName: z.string(),
       basePort: z.number().optional()
     },
-    async (args) => {
+    async (args, extra, { engine: engine2, register, authorize, formatReply }) => {
       authorize(args);
-      const portRes = await engine.broker.acquirePort(args);
+      const portRes = await engine2.broker.acquirePort(args);
       return formatReply(args.agentId, portRes);
     }
   );
-  server.tool(
+  tool(
     "kith_run_with_mutex",
     "Run an argv command under a renewable named mutex, using the MCP server process permissions. Useful when a sandboxed client shell cannot inspect process identities. Requires an owned session. Cancellation or connection loss stops the supervised command before release. This is command execution, not a filesystem sandbox.",
     {
@@ -4131,15 +4178,15 @@ function createKithMcpServer(repoRoot = process.cwd()) {
       commandTimeoutMs: z.number().int().min(1).max(6e5).optional(),
       maxOutputBytes: z.number().int().min(1).max(1048576).optional()
     },
-    async (args, extra) => {
+    async (args, extra, { engine: engine2, register, authorize, formatReply }) => {
       authorize(args);
-      const root = fs16.realpathSync(engine.fencing.getAgent(args.agentId)?.worktree_path ?? engine.coordDb.repoRoot);
+      const root = fs16.realpathSync(engine2.fencing.getAgent(args.agentId)?.worktree_path ?? engine2.coordDb.repoRoot);
       const cwd = fs16.realpathSync(path15.resolve(root, args.cwd ?? "."));
       const relative = path15.relative(root, cwd);
       if (relative === ".." || relative.startsWith(".." + path15.sep) || path15.isAbsolute(relative)) {
         throw new Error("Command cwd must be inside the registered worktree or repository");
       }
-      const execution = engine.broker.executeWithMutex({
+      const execution = engine2.broker.executeWithMutex({
         agentId: args.agentId,
         mutexName: args.mutexName,
         command: args.command,
@@ -4159,7 +4206,7 @@ function createKithMcpServer(repoRoot = process.cwd()) {
       }
     }
   );
-  server.tool(
+  tool(
     "kith_get_status",
     "Retrieve coordination state, FIFO waiters and guarded commands, plus worktree paths, actual branches, dirty-file overlaps, commit age and ahead/behind against the current integration target HEAD. Normal engine startup may reap expired ownership.",
     {
@@ -4167,9 +4214,9 @@ function createKithMcpServer(repoRoot = process.cwd()) {
       sessionToken: z.string().optional(),
       includeContracts: z.boolean().optional().describe("Include the full contract registry. Default false keeps frequent status polls compact; contractCount always reports its size.")
     },
-    async (args) => {
+    async (args, extra, { engine: engine2, register, authorize, formatReply }) => {
       if (args.agentId) authorize({ ...args, agentId: args.agentId });
-      const state = engine.getStatus();
+      const state = engine2.getStatus();
       return formatReply(args.agentId, {
         ...state,
         contracts: args.includeContracts ? state.contracts : [],
@@ -4178,16 +4225,16 @@ function createKithMcpServer(repoRoot = process.cwd()) {
       });
     }
   );
-  server.tool(
+  tool(
     "kith_preview_integrate",
     "Preview exact Git conflict paths for a committed registered worktree against the current integration target. Refuses dirty inputs; never checkpoints or changes source/target files. A clean preview does not run project verification.",
     { agentId: z.string(), sessionToken: z.string().optional() },
-    async (args) => {
+    async (args, extra, { engine: engine2, register, authorize, formatReply }) => {
       authorize(args);
-      return formatReply(args.agentId, engine.previewIntegration(args.agentId));
+      return formatReply(args.agentId, engine2.previewIntegration(args.agentId));
     }
   );
-  server.tool(
+  tool(
     "kith_complete_work",
     "Complete an agent task, optionally run the Speculative Merge Train to verify and merge its worktree branch, and release all locks and resources.",
     {
@@ -4198,16 +4245,25 @@ function createKithMcpServer(repoRoot = process.cwd()) {
       mergeBranch: z.string().optional().describe("Source branch to integrate, not the destination. Defaults to the registered agent branch; destination is the selected repository checkout current branch. Omit for claims-only work without a registered branch."),
       verificationCmd: z.string().optional().describe('Command to run in speculative merge tree (e.g. "npm run typecheck")')
     },
-    async (args) => {
+    async (args, extra, { engine: engine2, register, authorize, formatReply }) => {
       authorize(args);
-      const result = engine.completeWork(args);
+      const result = engine2.completeWork(args);
       return formatReply(result.ok ? void 0 : args.agentId, result);
     }
   );
   return { server, engine };
 }
-async function runKithMcpStdioServer(repoRoot = process.cwd()) {
-  const { server } = createKithMcpServer(repoRoot);
+async function runKithMcpStdioServer(repoRoot = process.cwd(), pinned = true) {
+  let defaultRoot = repoRoot;
+  if (!pinned) {
+    try {
+      const layout = discoverRepository(repoRoot);
+      defaultRoot = layout.commonGitDir ? layout.checkoutRoot : void 0;
+    } catch {
+      defaultRoot = void 0;
+    }
+  }
+  const { server } = buildKithMcpServer(defaultRoot, pinned);
   const transport = new StdioServerTransport();
   let closing = false;
   const close = () => {
@@ -4642,6 +4698,356 @@ esac
   return report;
 }
 
+// src/core/watcher.ts
+import fs19 from "fs";
+import path17 from "path";
+import { createHash } from "crypto";
+import { execFile, execFileSync as execFileSync10 } from "child_process";
+import { promisify } from "util";
+var execFileAsync = promisify(execFile);
+function contentIdentity(repo, file) {
+  const target = path17.join(repo, file);
+  let stat;
+  try {
+    stat = fs19.lstatSync(target);
+  } catch (error) {
+    if (error.code === "ENOENT") return "absent";
+    throw error;
+  }
+  const parent = fs19.realpathSync(path17.dirname(target));
+  const relative = path17.relative(repo, parent);
+  if (relative === ".." || relative.startsWith(`..${path17.sep}`) || path17.isAbsolute(relative)) throw new Error(`Path redirected outside checkout: ${file}`);
+  if (stat.isSymbolicLink()) return `link:${fs19.readlinkSync(target)}`;
+  if (!stat.isFile() || stat.size > 8 * 1024 * 1024) return null;
+  const fd = fs19.openSync(target, fs19.constants.O_RDONLY | (fs19.constants.O_NOFOLLOW ?? 0));
+  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 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));
+      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")}`;
+  } finally {
+    fs19.closeSync(fd);
+  }
+}
+var PassiveConflictWatcher = class _PassiveConflictWatcher {
+  constructor(rootDir, options = {}) {
+    this.rootDir = rootDir;
+    this.options = options;
+    if (options.intervalMs !== void 0 && (!Number.isFinite(options.intervalMs) || options.intervalMs < 100)) throw new Error("Watch interval must be at least 100ms.");
+  }
+  rootDir;
+  options;
+  isWatching = false;
+  watchTimer = null;
+  recentEdits = /* @__PURE__ */ new Map();
+  activeCollisions = /* @__PURE__ */ new Map();
+  repositories = /* @__PURE__ */ new Map();
+  errors = [];
+  static notifyMac(title, message) {
+    if (process.platform !== "darwin") return;
+    try {
+      execFileSync10("osascript", ["-e", "on run argv\ndisplay notification (item 2 of argv) with title (item 1 of argv)\nend run", title, message], { stdio: "ignore", timeout: 2e3 });
+    } catch {
+    }
+  }
+  discoverGitRepos() {
+    this.errors = [];
+    this.repositories.clear();
+    const candidates = [];
+    const marker = (dir) => {
+      try {
+        fs19.lstatSync(path17.join(dir, ".git"));
+        return true;
+      } catch (error) {
+        if (error.code === "ENOENT") return false;
+        throw error;
+      }
+    };
+    try {
+      const root = fs19.realpathSync(this.rootDir);
+      if (marker(root)) candidates.push(root);
+      for (const entry of fs19.readdirSync(root, { withFileTypes: true })) {
+        if (entry.isDirectory() && !entry.name.startsWith(".") && entry.name !== "node_modules") {
+          const sub = path17.join(root, entry.name);
+          if (marker(sub)) candidates.push(sub);
+        }
+      }
+    } catch (error) {
+      this.errors.push({ repository: this.rootDir, message: `Cannot discover repositories: ${error instanceof Error ? error.message : String(error)}` });
+    }
+    const inspected = /* @__PURE__ */ new Set();
+    for (const candidate of candidates) {
+      try {
+        const layout = discoverRepository(candidate);
+        if (!layout.commonGitDir) throw new Error("Git repository unavailable");
+        this.repositories.set(layout.checkoutRoot, layout.commonGitDir);
+        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"] });
+        for (const record of listing.split("\0")) if (record.startsWith("worktree ")) {
+          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);
+        }
+      } catch (error) {
+        this.errors.push({ repository: candidate, message: `Cannot inspect repository: ${error instanceof Error ? error.message : String(error)}` });
+      }
+    }
+    if (!candidates.length && !this.errors.length) this.errors.push({ repository: this.rootDir, message: "No Git repositories found in this directory or its immediate children." });
+    return [...this.repositories.keys()];
+  }
+  async scanOnce() {
+    const repos = this.discoverGitRepos();
+    const now = Date.now();
+    const seen = /* @__PURE__ */ new Set();
+    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 records = stdout.split("\0");
+        const dirty = /* @__PURE__ */ new Map();
+        for (let i = 0; i < records.length; i++) {
+          const record = records[i];
+          if (!record) continue;
+          const status = record.slice(0, 2);
+          dirty.set(record.slice(3), status);
+          if (/[RC]/.test(status)) dirty.set(records[++i], status);
+        }
+        for (const [file, status] of dirty) {
+          if (!file || file === ".coord" || file.startsWith(".coord/")) continue;
+          const key = JSON.stringify([repo, file]);
+          seen.add(key);
+          let modified = now, fingerprint = status;
+          try {
+            const stat = fs19.lstatSync(path17.join(repo, file));
+            modified = Math.min(now, stat.mtimeMs);
+            fingerprint += `:${stat.mtimeMs}:${stat.size}`;
+          } catch (error) {
+            if (error.code !== "ENOENT") throw error;
+          }
+          const previous = this.recentEdits.get(key);
+          if (!previous || previous.fingerprint !== fingerprint) {
+            this.recentEdits.set(key, { repo, fingerprint, timestamp: modified });
+            this.options.onFileChange?.({ repoPath: repo, filePath: file, timestamp: modified });
+          }
+          const identity = JSON.stringify([this.repositories.get(repo), file]);
+          const overlap = overlaps.get(identity) ?? { file, repos: [] };
+          overlap.repos.push(repo);
+          overlaps.set(identity, overlap);
+        }
+      } catch (error) {
+        this.errors.push({ repository: repo, message: `Git scan unavailable: ${error instanceof Error ? error.message : String(error)}` });
+      }
+    }
+    if (!this.errors.length) {
+      for (const key of this.recentEdits.keys()) if (!seen.has(key)) this.recentEdits.delete(key);
+    }
+    const current = /* @__PURE__ */ new Map();
+    for (const [id, overlap] of overlaps) if (overlap.repos.length > 1) {
+      let identical = false;
+      try {
+        const identities = overlap.repos.map((repo) => contentIdentity(repo, overlap.file));
+        identical = identities.every((value) => value !== null && value === identities[0]);
+      } catch (error) {
+        this.errors.push({ repository: overlap.repos.join(", "), message: `Cannot compare ${overlap.file}: ${error instanceof Error ? error.message : String(error)}` });
+      }
+      if (identical) continue;
+      const previous = this.activeCollisions.get(id);
+      const alert = {
+        id,
+        filePath: overlap.file,
+        repos: overlap.repos,
+        severity: "collision",
+        timestamp: previous?.timestamp ?? now,
+        message: `Shared dirty path '${overlap.file}' has different or unverified contents in linked worktrees: ${overlap.repos.join(", ")}. This is not a proven merge conflict.`
+      };
+      current.set(id, alert);
+      if (!previous) {
+        this.options.onCollision?.(alert);
+        if (this.options.notify) _PassiveConflictWatcher.notifyMac("Kith worktree overlap", alert.message);
+      }
+    }
+    this.activeCollisions = this.errors.length ? new Map([...this.activeCollisions, ...current]) : current;
+    if (this.errors.length) this.options.onScanError?.(this.errors);
+    return this.getActiveCollisions();
+  }
+  start() {
+    if (this.isWatching) return;
+    this.isWatching = true;
+    const tick = async () => {
+      try {
+        await this.scanOnce();
+      } catch (error) {
+        this.errors = [{ repository: this.rootDir, message: String(error) }];
+        this.options.onScanError?.(this.errors);
+      }
+      if (this.isWatching) this.watchTimer = setTimeout(tick, this.options.intervalMs ?? 3e3);
+    };
+    void tick();
+  }
+  stop() {
+    this.isWatching = false;
+    if (this.watchTimer) clearTimeout(this.watchTimer);
+    this.watchTimer = null;
+  }
+  getScanState() {
+    return { complete: this.errors.length === 0, errors: [...this.errors], repos: [...this.repositories.keys()] };
+  }
+  getActiveCollisions() {
+    return [...this.activeCollisions.values()];
+  }
+  getRecentEdits() {
+    const now = Date.now();
+    return [...this.recentEdits].map(([key, value]) => ({ key: `${value.repo}/${JSON.parse(key)[1]}`, repo: value.repo, ageSec: Math.max(0, Math.round((now - value.timestamp) / 1e3)) })).filter((value) => value.ageSec < 300).sort((a, b) => a.ageSec - b.ageSec);
+  }
+};
+
+// src/cli/setup-auto.ts
+import fs21 from "fs";
+import path18 from "path";
+import os2 from "os";
+import { parse as parseToml3, stringify as stringifyToml2 } from "smol-toml";
+
+// src/cli/runtime.ts
+import fs20 from "fs";
+import { fileURLToPath as fileURLToPath3 } from "url";
+function installedCliPath() {
+  for (const relative of ["./index.js", "../../dist/cli/index.js"]) {
+    const file = fileURLToPath3(new URL(relative, import.meta.url));
+    if (fs20.existsSync(file)) return fs20.realpathSync(file);
+  }
+  throw new Error("Build or install Kith before configuring clients.");
+}
+
+// src/cli/setup-auto.ts
+function object2(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object; no configuration was written.`);
+  return value;
+}
+function ownedLauncher(value) {
+  if (value.type !== void 0 && value.type !== "stdio") return false;
+  if (typeof value.command !== "string" || !/^node(?:\.exe)?$/i.test(path18.basename(value.command)) || !Array.isArray(value.args) || value.args[1] !== "mcp" || ![2, 4].includes(value.args.length) || value.args.length === 4 && value.args[2] !== "--repo") return false;
+  try {
+    const entry = fs21.realpathSync(value.args[0]);
+    return path18.basename(entry) === "index.js" && path18.basename(path18.dirname(entry)) === "cli" && JSON.parse(fs21.readFileSync(path18.resolve(entry, "../../../package.json"), "utf8")).name === "kith-coord";
+  } catch {
+    return false;
+  }
+}
+function autoConfigureAllClients(targetWorkspace = process.cwd(), home = os2.homedir(), options = {}) {
+  const target = physicalPath(targetWorkspace);
+  const layout = target === path18.parse(target).root ? void 0 : discoverRepository(target);
+  const workspace = layout?.checkoutRoot ?? target;
+  home = physicalPath(home);
+  const server = { command: process.execPath, args: [installedCliPath(), "mcp"] };
+  const projectServer = { ...server, args: [...server.args, "--repo", workspace] };
+  const results = [];
+  const groups = /* @__PURE__ */ new Map();
+  const warnings = [];
+  const queue = (root, file, content) => {
+    if (!isWithin(root, file)) throw new Error(`Configuration is outside its setup root: ${file}`);
+    if (fs21.existsSync(file) && fs21.readFileSync(file, "utf8") === content) return;
+    const group = groups.get(root) ?? { coordDir: root === workspace && layout ? layout.coordDir : path18.join(root, ".coord"), plan: /* @__PURE__ */ new Map() };
+    if (physicalPath(group.coordDir) !== group.coordDir) throw new Error("Setup backup directory must not be redirected.");
+    group.plan.set(path18.relative(root, file), { content, mode: 384 });
+    groups.set(root, group);
+  };
+  const safePath = (file) => {
+    if (physicalPath(file) !== file) throw new Error(`Configuration path is redirected: ${file}; no configuration was written.`);
+  };
+  const jsonClient = (clientName, file, root, found, projectScoped = false) => {
+    const selectedServer = projectScoped ? projectServer : server;
+    if (!found) {
+      results.push({ clientName, configPath: file, found: false, configured: false, notes: "No existing client configuration found" });
+      return;
+    }
+    safePath(file);
+    const cfg = fs21.existsSync(file) ? object2(JSON.parse(fs21.readFileSync(file, "utf8")), file) : {};
+    const servers = object2(cfg.mcpServers ?? {}, `${file} mcpServers`);
+    const previous = servers.kith === void 0 ? void 0 : object2(servers.kith, `${file} kith`);
+    const exact = previous?.command === selectedServer.command && JSON.stringify(previous.args) === JSON.stringify(selectedServer.args);
+    if (previous && !exact && !ownedLauncher(previous)) {
+      results.push({ clientName, configPath: file, found: true, configured: false, notes: "Custom Kith server preserved; review its repository and launcher manually" });
+      return;
+    }
+    cfg.mcpServers = { ...servers, kith: { ...previous, ...selectedServer } };
+    queue(root, file, JSON.stringify(cfg, null, 2) + "\n");
+    results.push({ clientName, configPath: file, found: true, configured: true, notes: `${options.dryRun ? "Would configure" : "Configured"} Kith ${projectScoped ? `for ${workspace}` : "for per-task repository selection"}; existing settings preserved` });
+  };
+  const desktop = process.platform === "win32" ? path18.join(process.env.APPDATA ?? path18.join(home, "AppData/Roaming"), "Claude/claude_desktop_config.json") : process.platform === "darwin" ? path18.join(home, "Library/Application Support/Claude/claude_desktop_config.json") : path18.join(home, ".config/Claude/claude_desktop_config.json");
+  jsonClient("Claude Desktop App", desktop, home, fs21.existsSync(desktop));
+  jsonClient(
+    "Claude Code CLI",
+    path18.join(home, ".claude.json"),
+    home,
+    fs21.existsSync(path18.join(home, ".claude.json")) || fs21.existsSync(path18.join(home, ".claude"))
+  );
+  const codex = path18.join(home, ".codex/config.toml");
+  if (fs21.existsSync(path18.dirname(codex))) {
+    safePath(codex);
+    const original = fs21.existsSync(codex) ? fs21.readFileSync(codex, "utf8") : "";
+    const cfg = parseToml3(original), servers = object2(cfg.mcp_servers ?? {}, "Codex MCP servers");
+    const previous = servers.kith === void 0 ? void 0 : object2(servers.kith, "Codex Kith server");
+    let content = original;
+    let configured = true;
+    const exact = previous?.command === server.command && JSON.stringify(previous.args) === JSON.stringify(server.args);
+    if (!previous) {
+      content += (content && !content.endsWith("\n") ? "\n" : "") + "\n" + stringifyToml2({ mcp_servers: { kith: { ...server, env_vars: ["KITH_AGENT_ID", "KITH_SESSION_TOKEN"] } } });
+    } else if (!exact) {
+      const block = /(^\[mcp_servers\.kith\][^\S\r\n]*\r?\n)([\s\S]*?)(?=^\[|$(?![\s\S]))/m;
+      const match = original.match(block);
+      if (ownedLauncher(previous) && match && /^command\s*=\s*"(?:[^"\\\r\n]|\\.)*"\s*$/m.test(match[2]) && /^args\s*=\s*\[[^\r\n]*\]\s*$/m.test(match[2])) {
+        const fields = [`command = ${JSON.stringify(server.command)}`, `args = ${JSON.stringify(server.args)}`];
+        const updated = match[2].replace(/^command\s*=.*$/m, fields[0]).replace(/^args\s*=.*$/m, fields[1]);
+        content = original.replace(block, () => match[1] + updated);
+      } else configured = false;
+    }
+    parseToml3(content);
+    if (configured) queue(home, codex, content);
+    results.push({
+      clientName: "Codex",
+      found: true,
+      configPath: codex,
+      configured,
+      notes: configured ? `${options.dryRun ? "Would configure" : "Configured"} Kith for per-task repository selection; other TOML preserved` : "Custom Kith server preserved; review its repository and launcher manually"
+    });
+  }
+  jsonClient("Cursor", path18.join(workspace, ".cursor/mcp.json"), workspace, Boolean(layout?.commonGitDir), true);
+  const antigravity = path18.join(home, ".gemini/config/mcp_config.json");
+  jsonClient("Antigravity", antigravity, home, fs21.existsSync(path18.dirname(antigravity)));
+  for (const [root] of groups) {
+    if (!fs21.existsSync(path18.join(root, ".git"))) continue;
+    const file = path18.join(root, ".gitignore");
+    safePath(file);
+    const original = fs21.existsSync(file) ? fs21.readFileSync(file, "utf8") : "";
+    if (!original.split(/\r?\n/).some((line) => [".coord/", "/.coord/"].includes(line.trim()))) {
+      queue(root, file, original + (original && !original.endsWith("\n") ? "\n" : "") + "\n# Kith private setup backups\n.coord/\n");
+    }
+  }
+  if (!options.dryRun && groups.size) {
+    const engine = layout?.commonGitDir ? new KithEngine(workspace) : void 0;
+    try {
+      for (const [root, group] of groups) {
+        fs21.mkdirSync(group.coordDir, { recursive: true, mode: 448 });
+        applySetupPlan(root, group.coordDir, group.plan, warnings);
+      }
+    } finally {
+      engine?.close();
+    }
+  }
+  for (const warning of warnings) results.push({ clientName: "Setup backup", found: true, configured: false, configPath: "", notes: warning });
+  return results;
+}
+
 // src/cli/index.ts
 function parseFlags(argv) {
   const dashDashIdx = argv.indexOf("--");
@@ -4658,7 +5064,7 @@ function parseFlags(argv) {
       } else {
         const key = arg.slice(2);
         const next = mainArgs[i + 1];
-        if (!["worktree", "raw", "dry-run", "help", "version", "shell", "new", "mcp-only", "offline"].includes(key) && next && !next.startsWith("--")) {
+        if (!["worktree", "raw", "dry-run", "help", "version", "shell", "new", "mcp-only", "offline", "once", "json", "quiet", "no-notify"].includes(key) && next && !next.startsWith("--")) {
           flags[key] = next;
           i++;
         } else {
@@ -4675,7 +5081,8 @@ async function main() {
   const { positional, flags, passthroughCmd } = parseFlags(process.argv.slice(2));
   const cmd = positional[0] ?? "help";
   const subCmd = positional[1];
-  const repoRoot = typeof flags.repo === "string" ? flags.repo : process.cwd();
+  const targetFromPositional = ["init", "setup", "watch", "menubar", "bar", "tray", "doctor", "recover"].includes(cmd) && positional[1] ? path19.resolve(positional[1]) : void 0;
+  const repoRoot = typeof flags.repo === "string" ? path19.resolve(flags.repo) : targetFromPositional ?? (cmd === "mcp" ? process.env.CLAUDE_PROJECT_DIR : void 0) ?? process.cwd();
   if (flags.version || cmd === "version") {
     console.log(KITH_VERSION);
     return;
@@ -4699,7 +5106,7 @@ async function main() {
     return;
   }
   if (cmd === "mcp") {
-    await runKithMcpStdioServer(repoRoot);
+    await runKithMcpStdioServer(repoRoot, typeof flags.repo === "string");
     return;
   }
   if (cmd === "uninstall") {
@@ -4720,6 +5127,102 @@ async function main() {
     process.exitCode = state.state === "unavailable" ? 1 : 0;
     return;
   }
+  if (cmd === "setup" || cmd === "auto-detect") {
+    const targetDir = positional[1] ? path19.resolve(positional[1]) : repoRoot;
+    const results = autoConfigureAllClients(targetDir, void 0, { dryRun: Boolean(flags["dry-run"]) });
+    console.log(`
+\u2728 Kith Auto-Detect & Setup for ${targetDir}
+`);
+    for (const r of results) {
+      const statusIcon = r.configured ? "\u2713" : r.found ? "!" : "\u2717";
+      console.log(`  ${statusIcon} ${r.clientName.padEnd(24)} -> ${r.notes}`);
+    }
+    if (results.some((r) => r.found && !r.configured)) process.exitCode = 1;
+    console.log("\nExisting hooks and permissions are unchanged. Restart configured clients; review any skipped entries.\n");
+    return;
+  }
+  if (cmd === "menubar" || cmd === "bar" || cmd === "tray") {
+    const targetDir = positional[1] ? path19.resolve(positional[1]) : repoRoot;
+    if (process.platform !== "darwin") throw new Error("The menu-bar view requires macOS. Use kith watch on this platform.");
+    const menubarBin = path19.resolve(path19.dirname(installedCliPath()), "../../bin/kith-menubar");
+    if (!fs22.existsSync(menubarBin)) throw new Error("Menu-bar binary is missing; reinstall the package or run pnpm build:menubar in the source checkout.");
+    await new Promise((resolve, reject) => {
+      const child = spawn(menubarBin, [fs22.realpathSync(targetDir), process.execPath, installedCliPath()], { detached: true, stdio: "ignore" });
+      child.once("error", reject);
+      child.once("spawn", () => {
+        child.unref();
+        resolve();
+      });
+    });
+    console.log(`Kith menu-bar view launched for ${targetDir}.`);
+    return;
+  }
+  if (cmd === "watch" || cmd === "monitor") {
+    const targetDir = positional[1] ? path19.resolve(positional[1]) : repoRoot;
+    const notify = flags.notify !== "false" && !flags["no-notify"];
+    const intervalMs = typeof flags.interval === "string" ? Number(flags.interval) : 2500;
+    const isRaw = Boolean(flags.raw || flags.json);
+    let lastScanError = "";
+    const watcher = new PassiveConflictWatcher(targetDir, {
+      intervalMs,
+      notify: !isRaw && notify,
+      onScanError: (errors) => {
+        const message = errors.map((error) => `${error.repository}: ${error.message}`).join("\n");
+        if (!flags.once && message !== lastScanError) console.error(`Scan unavailable:
+${message}`);
+        lastScanError = message;
+      },
+      onCollision: (alert) => {
+        if (!isRaw) {
+          console.log(`
+\u26A0\uFE0F [WORKTREE OVERLAP] ${alert.message}`);
+        }
+      },
+      onFileChange: (e) => {
+        if (!flags.quiet && !isRaw) {
+          console.log(`\u{1F4DD} [EDIT] ${path19.basename(e.repoPath)}/${e.filePath}`);
+        }
+      }
+    });
+    if (flags.once) {
+      const alerts = await watcher.scanOnce();
+      const state = watcher.getScanState();
+      const repos = state.repos;
+      const edits = watcher.getRecentEdits();
+      if (!state.complete) process.exitCode = 1;
+      if (flags.raw || flags.json) {
+        console.log(JSON.stringify({ ...state, recentEdits: edits, collisions: alerts }, null, 2));
+        return;
+      }
+      console.log(`
+\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}`);
+      if (!state.complete) {
+        console.error(`Scan unavailable:
+${state.errors.map((error) => error.message).join("\n")}`);
+      } else if (alerts.length === 0) {
+        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}):`);
+        for (const a of alerts) {
+          console.log(`   \u26A0\uFE0F ${a.message}`);
+          console.log(`      Files: ${a.filePath}`);
+        }
+        console.log("");
+      }
+      return;
+    }
+    console.log(`
+\u{1F440} Kith Passive Conflict Radar watching: ${targetDir}`);
+    console.log(`   Read-only overlap observations; this does not identify agents or verify compatibility. Press Ctrl+C to stop.
+`);
+    watcher.start();
+    await new Promise(() => {
+    });
+    return;
+  }
   const commands = ["session", "status", "begin", "complete", "heartbeat", "task", "lock", "contract", "worktree", "port", "mutex", "hook"];
   if (!commands.includes(cmd)) throw new Error(`Unknown command '${cmd}'. Run kith help.`);
   const subcommands = {
@@ -5036,7 +5539,10 @@ Usage:
   kith uninstall [--dry-run]                      Restore unchanged tracked setup files; retain work and recovery state
   kith doctor                                     Check runtime, PATH, configuration, sessions and worktree health without writes
   kith recover                                    Inspect retained work, expired claims and recovery records offline
-  kith mcp                                        Start stdio MCP server
+  kith setup [checkout] [--dry-run]                Configure detected clients; preserve hooks and custom settings
+  kith watch [checkout] [--once --json]            Observe linked-worktree path overlaps without enforcement
+  kith menubar [checkout]                         Optional read-only macOS view
+  kith mcp --repo <checkout>                      Start stdio MCP server bound to a project
   kith begin --agent <id> --title <t> --scope <g> Declare intent, check overlaps, lock scope
   kith complete --agent <id> [--merge <branch>]   Run Speculative Merge Train & release locks
   kith task add|claim|list                        Manage orchestrated DAG task queue