kith-coord 0.1.2 → 0.1.4

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.4";
+var KITH_PROTOCOL_VERSION = "1.3.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,
@@ -235,6 +243,7 @@ function uninstallKith(directory = process.cwd(), dryRun = false) {
 // src/cli/doctor.ts
 import fs5 from "fs";
 import path5 from "path";
+import os2 from "os";
 import { execFileSync as execFileSync3 } from "child_process";
 import { parse as parseToml } from "smol-toml";
 
@@ -887,7 +896,7 @@ function recoveryReport(directory = process.cwd()) {
 }
 
 // src/cli/doctor.ts
-function doctorReport(directory = process.cwd()) {
+function doctorReport(directory = process.cwd(), home = os2.homedir()) {
   const state = readCoordinationState(directory), root = state.repository.root;
   const checks = [];
   const check = (name, ok, detail) => checks.push({ name, ok, detail });
@@ -912,24 +921,42 @@ function doctorReport(directory = process.cwd()) {
       }
     });
   };
+  const desktop = process.platform === "win32" ? path5.join(home === os2.homedir() ? process.env.APPDATA ?? path5.join(home, "AppData/Roaming") : path5.join(home, "AppData/Roaming"), "Claude/claude_desktop_config.json") : process.platform === "darwin" ? path5.join(home, "Library/Application Support/Claude/claude_desktop_config.json") : path5.join(home, ".config/Claude/claude_desktop_config.json");
+  const files = [
+    ["claude", path5.join(root, ".mcp.json"), false, root],
+    ["cursor", path5.join(root, ".cursor/mcp.json"), false, root],
+    ["codex", path5.join(root, ".codex/config.toml"), true, root],
+    ["claude-global", path5.join(home, ".claude.json"), false, home],
+    ["claude-desktop", desktop, false, path5.dirname(desktop)],
+    ["codex-global", path5.join(home, ".codex/config.toml"), true, home],
+    ["antigravity", path5.join(home, ".gemini/config/mcp_config.json"), false, home]
+  ];
   let configured = 0;
-  for (const [client, file] of [["claude", ".mcp.json"], ["cursor", ".cursor/mcp.json"], ["codex", ".codex/config.toml"]]) {
-    const target = path5.join(root, file);
-    if (!fs5.existsSync(target)) continue;
+  const inspected = /* @__PURE__ */ new Set();
+  for (const [client, target, toml, base] of files) {
+    if (inspected.has(target) || !fs5.existsSync(target)) continue;
+    inspected.add(target);
     try {
-      if (!isWithin(root, physicalPath(target))) throw new Error("Configuration is redirected outside the checkout");
+      if (!isWithin(physicalPath(base), physicalPath(target))) throw new Error("Configuration is redirected outside its setup root");
       const text = fs5.readFileSync(target, "utf8");
-      const config = client === "codex" ? parseToml(text) : JSON.parse(text);
-      const server = client === "codex" ? config.mcp_servers?.kith : config.mcpServers?.kith;
+      const config = toml ? parseToml(text) : JSON.parse(text);
+      const server = toml ? config.mcp_servers?.kith : config.mcpServers?.kith;
       if (!server) continue;
       configured++;
-      check(`${client}-mcp`, typeof server.command === "string" && Array.isArray(server.args) && executable(server.command), "Kith stdio launcher must be executable by absolute path or PATH; native client trust and MCP discovery require client validation");
-    } catch {
-      check(`${client}-mcp`, false, `Cannot parse ${file}; existing configuration was preserved`);
+      if (typeof server.command !== "string" || !Array.isArray(server.args) || !server.args.every((a) => typeof a === "string") || !executable(server.command))
+        throw new Error("Kith launcher is missing or not executable; rerun setup from the installed version");
+      if (/^node(?:\.exe)?$/i.test(path5.basename(server.command)) && (!server.args[0] || !fs5.existsSync(server.args[0]) || !fs5.statSync(server.args[0]).isFile()))
+        throw new Error("Kith CLI entry is missing; rerun setup after moving or reinstalling Node/Kith");
+      const pin = server.args.indexOf("--repo");
+      if (pin >= 0 && (typeof server.args[pin + 1] !== "string" || !path5.isAbsolute(server.args[pin + 1]) || physicalPath(server.args[pin + 1]) !== root))
+        throw new Error("Kith launcher is pinned to a different checkout; use that checkout or review its setup");
+      check(`${client}-mcp`, true, "Launcher files are present; native connection, project trust and tool approval are not verified by doctor");
+    } catch (error) {
+      check(`${client}-mcp`, false, `${target}: ${error instanceof Error ? error.message : String(error)}; configuration preserved`);
     }
   }
-  check("mcp-configuration", configured > 0, "Configure the clients you use with kith init; diagnostics do not change client settings");
-  check("coordination-state", state.state === "ready", state.state === "ready" ? "Schema and counters validated on a private snapshot" : state.error ?? "No coordination state; run kith init before starting agents");
+  check("mcp-configuration", configured > 0, "Use global kith setup or project kith init for your client; configuration alone does not establish a connection");
+  check("coordination-state", state.state !== "unavailable", state.state === "ready" ? "Schema and counters validated on a private snapshot" : state.error ?? "No project state yet; the first owned task initializes it. No state was created by doctor");
   let nativeGuards = false;
   for (const [file, event] of [[".claude/settings.json", "PreToolUse"], [".cursor/hooks.json", "preToolUse"]]) {
     const target = path5.join(root, file);
@@ -988,6 +1015,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 +1024,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") {
@@ -1011,11 +1040,14 @@ var FencingAndAgentManager = class _FencingAndAgentManager {
             "-NoProfile",
             "-NonInteractive",
             "-Command",
-            `(Get-Process -Id ${pid} -ErrorAction Stop).StartTime.ToUniversalTime().Ticks.ToString([System.Globalization.CultureInfo]::InvariantCulture)`
+            `([System.Diagnostics.Process]::GetProcessById(${pid})).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 +1059,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 +1091,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");
@@ -1186,6 +1220,37 @@ var FencingAndAgentManager = class _FencingAndAgentManager {
   }
 };
 
+// src/core/claim-wait.ts
+async function waitForClaim(params) {
+  const { waitTimeoutMs, signal } = params;
+  if (!Number.isSafeInteger(waitTimeoutMs) || waitTimeoutMs < 0 || waitTimeoutMs > 6e5) {
+    throw new Error("waitTimeoutMs must be an integer between 0 and 600000");
+  }
+  const started = performance.now();
+  let previous;
+  for (; ; ) {
+    signal?.throwIfAborted();
+    const elapsed = Math.round(performance.now() - started);
+    if (previous && elapsed >= waitTimeoutMs) return { ...previous, waitedMs: elapsed, waitTimedOut: true };
+    params.heartbeat();
+    const result = params.attempt();
+    const waitedMs = Math.round(performance.now() - started);
+    if (result.ok || waitedMs >= waitTimeoutMs) return { ...result, waitedMs, waitTimedOut: !result.ok };
+    previous = result;
+    await new Promise((resolve, reject) => {
+      const abort = () => {
+        clearTimeout(timer);
+        reject(signal.reason);
+      };
+      const timer = setTimeout(() => {
+        signal?.removeEventListener("abort", abort);
+        resolve();
+      }, Math.min(100, waitTimeoutMs - waitedMs));
+      signal?.addEventListener("abort", abort, { once: true });
+    });
+  }
+}
+
 // src/core/engine.ts
 import fs15 from "fs";
 import path14 from "path";
@@ -2104,6 +2169,7 @@ var ResourceBroker = class _ResourceBroker {
     const leaseMs = FencingAndAgentManager.validateLease(params.leaseDurationMs ?? FencingAndAgentManager.DEFAULT_LEASE_MS);
     const now = Date.now();
     const expiresAt = now + leaseMs;
+    if (!Number.isInteger(basePort) || basePort < 1 || basePort > 65535) throw new Error("basePort must be an integer between 1 and 65535");
     const resourceKey = `${params.agentId}:${params.serviceName}`;
     const existing = this.getResource("port", resourceKey);
     if (existing && existing.expires_at > now) {
@@ -2238,8 +2304,44 @@ var ResourceBroker = class _ResourceBroker {
       return true;
     });
   }
+  /** Launch on the allocated port, without interpreting arguments as shell code. */
+  async executeWithPort(params) {
+    if (!params.command.length || !params.command[0]) throw new Error("A command is required");
+    if (!params.serviceName || params.serviceName.length > 128) throw new Error("serviceName must contain 1 to 128 characters");
+    const mutexName = `dev-port:${params.agentId}:${params.serviceName}`;
+    let allocation;
+    const leaseMs = FencingAndAgentManager.validateLease(params.leaseDurationMs ?? FencingAndAgentManager.DEFAULT_LEASE_MS);
+    const result = await this.executeGuarded({ ...params, mutexName }, {
+      prepare: async () => {
+        allocation = await this.acquirePort({ ...params, basePort: params.basePort ?? 3e3 });
+        params.onPort?.(allocation.port);
+        return {
+          command: params.command.map((arg) => arg.replaceAll("{port}", String(allocation.port))),
+          env: { PORT: String(allocation.port), KITH_PORT: String(allocation.port) }
+        };
+      },
+      renew: () => {
+        if (!allocation) return;
+        this.coordDb.withTransaction(() => {
+          this.fencing.assertSession(params.agentId);
+          const resource = this.getResource("port", `${params.agentId}:${params.serviceName}`);
+          if (!resource || resource.fencing_token !== allocation.fencingToken || resource.expires_at <= Date.now()) {
+            throw new Error("Dev server port lease lost");
+          }
+          this.coordDb.db.prepare("UPDATE resources SET expires_at=? WHERE id=?").run(Date.now() + leaseMs, resource.id);
+        });
+      },
+      release: () => {
+        if (allocation) this.coordDb.db.prepare("DELETE FROM resources WHERE type='port' AND name=? AND fencing_token=?").run(`${params.agentId}:${params.serviceName}`, allocation.fencingToken);
+      }
+    });
+    return { ...result, port: allocation.port };
+  }
   /** Renew leases while a detached, recorded process group runs; stop it before releasing. */
-  async executeWithMutex(params) {
+  executeWithMutex(params) {
+    return this.executeGuarded(params);
+  }
+  async executeGuarded(params, lifecycle) {
     if (process.platform === "win32") throw new Error("Supervised mutex commands currently require macOS or Linux process groups");
     if (!params.command.length) throw new Error("A command is required");
     const leaseMs = FencingAndAgentManager.validateLease(params.leaseDurationMs ?? FencingAndAgentManager.DEFAULT_LEASE_MS);
@@ -2284,6 +2386,8 @@ var ResourceBroker = class _ResourceBroker {
         await delay(Math.min(50, Math.max(10, leaseMs / 4)));
       }
       const waitedMs = Date.now() - started;
+      const prepared = await lifecycle?.prepare();
+      if (params.signal?.aborted) throw abortError();
       const candidates = ["./command-worker.js", "../command-worker.js", "../../dist/command-worker.js"].map((name) => fileURLToPath(new URL(name, import.meta.url)));
       const script = candidates.find((name) => fs10.existsSync(name));
       if (!script) throw new Error("Missing command worker. Build Kith before running supervised commands.");
@@ -2326,6 +2430,7 @@ var ResourceBroker = class _ResourceBroker {
         try {
           this.fencing.heartbeat(params.agentId);
           this.renewMutex({ ...params, fencingToken: run.fencing_token });
+          lifecycle?.renew();
         } catch (err) {
           stop(err instanceof Error ? err : new Error(String(err)));
         }
@@ -2353,8 +2458,9 @@ var ResourceBroker = class _ResourceBroker {
               run.worker_start = identity;
               workerIdentity = identity;
               this.renewMutex({ ...params, fencingToken: run.fencing_token });
+              lifecycle?.renew();
             });
-            worker.send({ command: params.command, cwd: params.cwd ?? this.coordDb.repoRoot, mutexName: params.mutexName });
+            worker.send({ command: prepared?.command ?? params.command, env: prepared?.env, cwd: params.cwd ?? this.coordDb.repoRoot, mutexName: params.mutexName });
           } catch (err) {
             stop(err instanceof Error ? err : new Error(String(err)));
           }
@@ -2402,6 +2508,7 @@ var ResourceBroker = class _ResourceBroker {
           this.coordDb.db.prepare("DELETE FROM mutex_waiters WHERE mutex_name=? AND request_id=? AND session_epoch=?").run(params.mutexName, requestId, epoch);
           if (run && !this.runIsAlive(run)) this.clearRun(run);
           if (run && run.worker_pid === null) this.clearRun(run);
+          if (!this.getRun(params.mutexName)) lifecycle?.release();
         });
       } finally {
         this.activeExecutions--;
@@ -3734,6 +3841,7 @@ var CoWWorktreeManager = class _CoWWorktreeManager {
 
 // src/core/engine.ts
 var KithEngine = class {
+  activeClaimWaits = 0;
   coordDb;
   fencing;
   locks;
@@ -3886,6 +3994,22 @@ ${lines.join("\n")}` : "";
     const worktree = intent.ok && params.isolateWorktree ? this.worktrees.spawnWorktree({ agentId: params.agentId }) : null;
     return { ...intent, worktree };
   }
+  async beginWorkWhenAvailable(params) {
+    return this.waitForOwnedClaim(params, () => this.beginWork(params));
+  }
+  async acquireLocksWhenAvailable(params) {
+    return this.waitForOwnedClaim(params, () => this.locks.acquireLocks(params));
+  }
+  async waitForOwnedClaim(params, attempt) {
+    this.activeClaimWaits++;
+    try {
+      return await waitForClaim({ ...params, attempt, heartbeat: () => {
+        this.fencing.heartbeat(params.agentId);
+      } });
+    } finally {
+      this.activeClaimWaits--;
+    }
+  }
   completeWork(params) {
     this.fencing.assertSession(params.agentId);
     const agent = this.fencing.getAgent(params.agentId);
@@ -3906,6 +4030,7 @@ ${lines.join("\n")}` : "";
     return { ok: true, completedTasks, mergeResult };
   }
   close() {
+    if (this.activeClaimWaits) throw new Error("Await or cancel active file claim waits before closing Kith");
     if (this.broker.hasActiveCommands()) throw new Error("Await or cancel active mutex commands before closing Kith");
     this.coordDb.close();
   }
@@ -3917,73 +4042,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.",
     {
@@ -3993,21 +4150,34 @@ function createKithMcpServer(repoRoot = process.cwd()) {
       title: z.string().describe("Short title of the task or intent"),
       intentSummary: z.string().optional().describe("Detailed description of what will be built or modified"),
       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")
+      isolateWorktree: z.boolean().optional().describe("Recommended: true, giving each parallel agent a separate Git worktree"),
+      waitTimeoutMs: z.number().int().min(0).max(6e5).optional().describe("Wait up to this many milliseconds for the whole scope; default fail-fast, not a FIFO file queue")
     },
-    async (args) => {
+    async (args, extra, { engine: engine2, register, authorize, formatReply }) => {
       const reg = register(args);
-      const intentRes = engine.beginWork({
+      const options = {
         agentId: args.agentId,
         title: args.title,
         intentSummary: args.intentSummary,
         scopeGlobs: args.scopeGlobs,
         isolateWorktree: args.isolateWorktree
+      };
+      const execution = args.waitTimeoutMs === void 0 ? void 0 : engine2.beginWorkWhenAvailable({
+        ...options,
+        waitTimeoutMs: args.waitTimeoutMs,
+        signal: AbortSignal.any([disconnected.signal, extra.signal])
       });
-      const contracts = engine.depGraph.listContracts().slice(0, 30);
+      if (execution) commands.add(execution);
+      let intentRes;
+      try {
+        intentRes = execution ? await execution : engine2.beginWork(options);
+      } finally {
+        if (execution) commands.delete(execution);
+      }
+      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,
@@ -4015,11 +4185,12 @@ function createKithMcpServer(repoRoot = process.cwd()) {
         worktree: intentRes.worktree,
         lockConflicts: intentRes.lockConflicts,
         activeSiblingIntents: intentRes.activeSiblingIntents,
+        ..."waitedMs" in intentRes && "waitTimedOut" in intentRes ? { waitedMs: intentRes.waitedMs, waitTimedOut: intentRes.waitTimedOut } : {},
         publishedContracts: contracts
       });
     }
   );
-  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 +4198,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 +4215,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.",
     {
@@ -4057,15 +4228,25 @@ function createKithMcpServer(repoRoot = process.cwd()) {
       sessionToken: z.string().optional(),
       patterns: z.array(z.string()),
       mode: z.enum(["exclusive", "shared"]).optional(),
-      reason: z.string().optional()
+      reason: z.string().optional(),
+      waitTimeoutMs: z.number().int().min(0).max(6e5).optional()
     },
-    async (args) => {
+    async (args, extra, { engine: engine2, register, authorize, formatReply }) => {
       authorize(args);
-      const res = engine.locks.acquireLocks(args);
-      return formatReply(args.agentId, res);
+      const execution = args.waitTimeoutMs === void 0 ? void 0 : engine2.acquireLocksWhenAvailable({
+        ...args,
+        waitTimeoutMs: args.waitTimeoutMs,
+        signal: AbortSignal.any([disconnected.signal, extra.signal])
+      });
+      if (execution) commands.add(execution);
+      try {
+        return formatReply(args.agentId, execution ? await execution : engine2.locks.acquireLocks(args));
+      } finally {
+        if (execution) commands.delete(execution);
+      }
     }
   );
-  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 +4255,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 +4265,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 +4277,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 +4292,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 +4312,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 +4340,46 @@ function createKithMcpServer(repoRoot = process.cwd()) {
       }
     }
   );
-  server.tool(
+  tool(
+    "kith_run_dev_server",
+    "Run a literal argv command with an allocated port in PORT/KITH_PORT and substituted {port} arguments. Renews the lease while running; cancellation/disconnect stops the process group before release. Uses coordinator permissions. Requires macOS/Linux; no implicit shell or readiness guarantee.",
+    {
+      agentId: z.string(),
+      sessionToken: z.string().optional(),
+      serviceName: z.string().min(1).max(128),
+      command: z.array(z.string()).min(1),
+      basePort: z.number().int().min(1).max(65535).optional(),
+      cwd: z.string().optional(),
+      leaseDurationMs: z.number().int().min(100).max(864e5).optional(),
+      commandTimeoutMs: z.number().int().min(1).max(6e5).optional(),
+      maxOutputBytes: z.number().int().min(1).max(1048576).optional()
+    },
+    async (args, extra, { engine: engine2, authorize, formatReply }) => {
+      authorize(args);
+      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 = engine2.broker.executeWithPort({
+        ...args,
+        cwd,
+        basePort: args.basePort ?? 3e3,
+        commandTimeoutMs: args.commandTimeoutMs ?? 6e4,
+        maxOutputBytes: args.maxOutputBytes ?? 65536,
+        signal: AbortSignal.any([disconnected.signal, extra.signal])
+      });
+      commands.add(execution);
+      try {
+        const result = await execution;
+        return formatReply(args.agentId, { ok: result.exitCode === 0, ...result });
+      } finally {
+        commands.delete(execution);
+      }
+    }
+  );
+  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 +4387,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 +4398,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 +4418,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 = () => {
@@ -4557,7 +4786,7 @@ Instruction protocol: ${KITH_PROTOCOL_VERSION}.
 
 Use Kith MCP to claim work, isolate changes in worktrees, share local resources and verify integration. Keep one isolated worktree per parallel agent and keep the owning MCP connection open.
 
-1. Call \`kith_begin_work\` with a unique \`agentId\`, an explicit \`scopeGlobs\` array and \`isolateWorktree: true\`.
+1. Select the absolute Git repository path for this task. Include \`repository\` on calls from a global desktop connection; a pinned connection must stay in its configured checkout. Call \`kith_begin_work\` with a unique \`agentId\`, an explicit \`scopeGlobs\` array and \`isolateWorktree: true\`.
 2. Edit only the returned \`worktree.worktreePath\`. Report changed files through \`kith_record_file_edit\` on that connection.
 3. Run serialized commands with \`kith_run_with_mutex\`: pass a literal executable/argument array. Its cwd defaults to the registered worktree. Commands run with server permissions and require client approval.
 4. Renew idle sessions with \`kith_heartbeat\` before their lease expires (every two minutes for the default five-minute lease; sooner for a shorter lease). Inspect \`kith_get_status\`.
@@ -4572,7 +4801,7 @@ If Claude/Cursor edit hooks or CLI commands are also enabled, launch the client
     }
     content = content.includes("<!-- KITH:START -->") ? content.replace(/<!-- KITH:START -->[\s\S]*?<!-- KITH:END -->/, () => block) : content.trimEnd() + "\n\n" + block + "\n";
     add("AGENTS.md", content);
-    add(".agent/skills/kith/SKILL.md", '---\nname: kith\ndescription: Coordinate parallel coding work through Kith MCP and isolated worktrees.\n---\n\nPrefer the Kith MCP tools on one persistent connection. Begin with kith_begin_work using a unique agentId, explicit scopeGlobs and isolateWorktree:true. Edit the returned worktreePath, report files with kith_record_file_edit, run literal command arrays with kith_run_with_mutex, heartbeat before expiry and finish with kith_complete_work plus a project verificationCmd. Inspect kith_get_status. Keep capabilities private. If CLI or native hooks are enabled, first launch the client from a persistent shell with the same KITH_AGENT_ID/KITH_SESSION_TOKEN and --owner-pid "$$". Stateless shell calls cannot retain that setup. Locks require cooperating clients.\n');
+    add(".agent/skills/kith/SKILL.md", '---\nname: kith\ndescription: Coordinate parallel coding work through Kith MCP and isolated worktrees.\n---\n\nPrefer the Kith MCP tools on one persistent connection. Begin with kith_begin_work using a unique agentId, explicit scopeGlobs and isolateWorktree:true. Edit the returned worktreePath, report files with kith_record_file_edit, run literal command arrays with kith_run_with_mutex, heartbeat before expiry and finish with kith_complete_work plus a project verificationCmd. Inspect kith_get_status. Keep capabilities private. If CLI or native hooks are enabled, first launch the client from a persistent shell with the same KITH_AGENT_ID/KITH_SESSION_TOKEN and --owner-pid "$$". Stateless shell calls cannot retain that setup. For global desktop connections, include the absolute Git repository in each call; never guess from the server startup directory. Configured tools do not establish ownership until begin-work succeeds. Locks require cooperating clients.\n');
   }
   if (selected.has("git")) {
     try {
@@ -4642,6 +4871,357 @@ 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, fingerprint = status;
+          try {
+            const stat = fs19.lstatSync(path17.join(repo, file));
+            if (Number.isFinite(stat.mtimeMs) && stat.mtimeMs <= now) modified = stat.mtimeMs;
+            fingerprint += `:${stat.mtimeMs}:${stat.size}`;
+          } catch (error) {
+            if (error.code !== "ENOENT") throw error;
+          }
+          const previous = this.recentEdits.get(key);
+          if (modified === void 0) this.recentEdits.delete(key);
+          else 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 os3 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 = os3.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 +5238,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", "wait", "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 {
@@ -4671,11 +5251,40 @@ function parseFlags(argv) {
   }
   return { positional, flags, passthroughCmd };
 }
+async function interruptible(run) {
+  const controller = new AbortController();
+  let interrupted;
+  const sigint = () => {
+    interrupted = "SIGINT";
+    controller.abort();
+  };
+  const sigterm = () => {
+    interrupted = "SIGTERM";
+    controller.abort();
+  };
+  process.on("SIGINT", sigint);
+  process.on("SIGTERM", sigterm);
+  try {
+    return await run(controller.signal);
+  } catch (err) {
+    if (!interrupted) throw err;
+    process.exitCode = interrupted === "SIGINT" ? 130 : 143;
+  } finally {
+    process.off("SIGINT", sigint);
+    process.off("SIGTERM", sigterm);
+  }
+}
 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 claimWaitTimeout = () => {
+    const value = flags["wait-ms"];
+    if (value !== void 0 && typeof value !== "string") throw new Error("--wait-ms requires a millisecond value");
+    return value === void 0 ? 6e4 : Number(value);
+  };
+  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 +5308,7 @@ async function main() {
     return;
   }
   if (cmd === "mcp") {
-    await runKithMcpStdioServer(repoRoot);
+    await runKithMcpStdioServer(repoRoot, typeof flags.repo === "string");
     return;
   }
   if (cmd === "uninstall") {
@@ -4720,7 +5329,103 @@ async function main() {
     process.exitCode = state.state === "unavailable" ? 1 : 0;
     return;
   }
-  const commands = ["session", "status", "begin", "complete", "heartbeat", "task", "lock", "contract", "worktree", "port", "mutex", "hook"];
+  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; retained overlaps may be stale:
+${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} [FILE MTIME] ${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", "dev", "mutex", "hook"];
   if (!commands.includes(cmd)) throw new Error(`Unknown command '${cmd}'. Run kith help.`);
   const subcommands = {
     session: ["start", "end"],
@@ -4743,7 +5448,7 @@ async function main() {
   const register = () => engine.fencing.registerAgent({
     id: agentId,
     client: String(flags.client ?? "cli"),
-    pid: typeof flags["owner-pid"] === "string" ? Number(flags["owner-pid"]) : cmd === "mutex" && !sessionToken ? process.pid : process.ppid,
+    pid: typeof flags["owner-pid"] === "string" ? Number(flags["owner-pid"]) : ["mutex", "dev"].includes(cmd) && !sessionToken ? process.pid : process.ppid,
     sessionToken,
     leaseDurationMs: typeof flags["lease-ms"] === "string" ? Number(flags["lease-ms"]) : void 0
   });
@@ -4782,13 +5487,22 @@ export KITH_SESSION_TOKEN=${quote(session.sessionToken)}`);
       const scopeRaw = typeof flags.scope === "string" ? flags.scope : "";
       const scopeGlobs = scopeRaw ? scopeRaw.split(",").map((s) => s.trim()) : ["**"];
       const session = register();
-      const res = engine.beginWork({
+      const options = {
         agentId,
         title,
         intentSummary: typeof flags.summary === "string" ? flags.summary : title,
         scopeGlobs,
         isolateWorktree: Boolean(flags.worktree)
-      });
+      };
+      const res = flags.wait || flags["wait-ms"] !== void 0 ? await interruptible((signal) => engine.beginWorkWhenAvailable({
+        ...options,
+        signal,
+        waitTimeoutMs: claimWaitTimeout()
+      })) : engine.beginWork(options);
+      if (!res) {
+        if (!sessionToken) engine.fencing.abandonAgentSession(agentId);
+        return;
+      }
       console.log(JSON.stringify({ ...res, sessionToken: session.sessionToken }, null, 2));
       process.exitCode = res.ok ? 0 : 1;
       return;
@@ -4834,7 +5548,16 @@ export KITH_SESSION_TOKEN=${quote(session.sessionToken)}`);
       if (subCmd === "acquire") {
         const patterns = String(flags.patterns ?? flags.scope ?? "").split(",").map((s) => s.trim()).filter(Boolean);
         const session = register();
-        const res = engine.locks.acquireLocks({ agentId, patterns });
+        const res = flags.wait || flags["wait-ms"] !== void 0 ? await interruptible((signal) => engine.acquireLocksWhenAvailable({
+          agentId,
+          patterns,
+          signal,
+          waitTimeoutMs: claimWaitTimeout()
+        })) : engine.locks.acquireLocks({ agentId, patterns });
+        if (!res) {
+          if (!sessionToken) engine.fencing.abandonAgentSession(agentId);
+          return;
+        }
         console.log(JSON.stringify({ ...res, sessionToken: session.sessionToken }, null, 2));
         process.exitCode = res.ok ? 0 : 1;
         return;
@@ -4902,9 +5625,10 @@ export KITH_SESSION_TOKEN=${quote(session.sessionToken)}`);
       }
       return;
     }
-    if (cmd === "mutex") {
+    if (cmd === "mutex" || cmd === "dev") {
       const mutexName = String(flags.name ?? "default-mutex");
       const commandToRun = passthroughCmd.length ? passthroughCmd : String(flags.cmd ?? "");
+      if (cmd === "dev" && (!passthroughCmd.length || !passthroughCmd[0])) throw new Error("Provide a literal command after `--` for kith dev");
       if (!commandToRun) {
         console.error("Error: provide a command after `--` for `kith mutex`");
         process.exitCode = 1;
@@ -4922,17 +5646,24 @@ export KITH_SESSION_TOKEN=${quote(session.sessionToken)}`);
       process.on("SIGINT", sigint);
       process.on("SIGTERM", sigterm);
       try {
-        const res = await engine.broker.executeWithMutex({
+        const shared = {
           agentId,
-          mutexName,
-          command: commandToRun,
           signal: controller.signal,
           leaseDurationMs: typeof flags["lease-ms"] === "string" ? Number(flags["lease-ms"]) : void 0,
           timeoutMs: typeof flags["wait-ms"] === "string" ? Number(flags["wait-ms"]) : void 0,
           commandTimeoutMs: typeof flags["timeout-ms"] === "string" ? Number(flags["timeout-ms"]) : void 0,
           onStdout: (chunk) => process.stdout.write(chunk),
           onStderr: (chunk) => process.stderr.write(chunk)
-        });
+        };
+        const res = cmd === "dev" ? await engine.broker.executeWithPort({
+          ...shared,
+          command: passthroughCmd,
+          serviceName: String(flags.service ?? "web"),
+          basePort: flags.base === void 0 ? 3e3 : Number(flags.base),
+          cwd: path19.resolve(engine.fencing.getAgent(agentId)?.worktree_path ?? engine.coordDb.repoRoot, typeof flags.cwd === "string" ? flags.cwd : "."),
+          onPort: (port) => process.stderr.write(`Kith: ${String(flags.service ?? "web")} allocated port ${port} (PORT, KITH_PORT, {port})
+`)
+        }) : await engine.broker.executeWithMutex({ ...shared, mutexName, command: commandToRun });
         process.exitCode = res.exitCode;
       } catch (err) {
         if (interrupted) process.exitCode = interrupted === "SIGINT" ? 130 : 143;
@@ -5036,14 +5767,19 @@ 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
   kith lock acquire|release|list                  Manage fencing-token file/glob locks
   kith contract publish|list                      Manage Contract Blackboard
   kith worktree spawn|remove|list|preview                 Manage isolated Git worktrees
-  kith port --agent <id> --service <name>         Lease collision-free TCP port
+  kith port --agent <id> --service <name>         Reserve an available TCP port
+  kith dev --agent <id> -- <cmd>                Run with PORT and {port} argument substitution
+  kith begin/lock acquire ... --wait --wait-ms 60000  Wait for a scope claim (bounded, cancellable)
   kith mutex --agent <id> --name <m> -- <cmd>     Serialize commands via mutex
   kith hook pre|post|pre-commit                   Tool & git hook handlers
 `);