kith-coord 0.1.3 → 0.1.4

package/dist/cli/index.js

@@ -6,8 +6,8 @@ import path19 from "path";
 import { spawn } from "child_process";
 
 // src/version.ts
-var KITH_VERSION = "0.1.3";
-var KITH_PROTOCOL_VERSION = "1.2.0";
+var KITH_VERSION = "0.1.4";
+var KITH_PROTOCOL_VERSION = "1.3.0";
 
 // src/cli/setup-ledger.ts
 import fs2 from "fs";
@@ -243,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";
 
@@ -895,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 });
@@ -920,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);
@@ -1021,7 +1040,7 @@ 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: 15e3, windowsHide: true }
         ).trim();
@@ -1201,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";
@@ -2119,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) {
@@ -2253,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);
@@ -2299,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.");
@@ -2341,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)));
         }
@@ -2368,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)));
           }
@@ -2417,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--;
@@ -3749,6 +3841,7 @@ var CoWWorktreeManager = class _CoWWorktreeManager {
 
 // src/core/engine.ts
 var KithEngine = class {
+  activeClaimWaits = 0;
   coordDb;
   fencing;
   locks;
@@ -3901,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);
@@ -3921,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();
   }
@@ -4040,17 +4150,30 @@ function buildKithMcpServer(repoRoot, pinned) {
       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, extra, { engine: engine2, register, authorize, formatReply }) => {
       const reg = register(args);
-      const intentRes = engine2.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])
       });
+      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,
@@ -4062,6 +4185,7 @@ function buildKithMcpServer(repoRoot, pinned) {
         worktree: intentRes.worktree,
         lockConflicts: intentRes.lockConflicts,
         activeSiblingIntents: intentRes.activeSiblingIntents,
+        ..."waitedMs" in intentRes && "waitTimedOut" in intentRes ? { waitedMs: intentRes.waitedMs, waitTimedOut: intentRes.waitTimedOut } : {},
         publishedContracts: contracts
       });
     }
@@ -4104,12 +4228,22 @@ function buildKithMcpServer(repoRoot, pinned) {
       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, extra, { engine: engine2, register, authorize, formatReply }) => {
       authorize(args);
-      const res = engine2.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);
+      }
     }
   );
   tool(
@@ -4206,6 +4340,45 @@ function buildKithMcpServer(repoRoot, pinned) {
       }
     }
   );
+  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.",
@@ -4613,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\`.
@@ -4628,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 {
@@ -4826,16 +4999,17 @@ var PassiveConflictWatcher = class _PassiveConflictWatcher {
           if (!file || file === ".coord" || file.startsWith(".coord/")) continue;
           const key = JSON.stringify([repo, file]);
           seen.add(key);
-          let modified = now, fingerprint = status;
+          let modified, fingerprint = status;
           try {
             const stat = fs19.lstatSync(path17.join(repo, file));
-            modified = Math.min(now, stat.mtimeMs);
+            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 (!previous || previous.fingerprint !== fingerprint) {
+          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 });
           }
@@ -4914,7 +5088,7 @@ var PassiveConflictWatcher = class _PassiveConflictWatcher {
 // src/cli/setup-auto.ts
 import fs21 from "fs";
 import path18 from "path";
-import os2 from "os";
+import os3 from "os";
 import { parse as parseToml3, stringify as stringifyToml2 } from "smol-toml";
 
 // src/cli/runtime.ts
@@ -4943,7 +5117,7 @@ function ownedLauncher(value) {
     return false;
   }
 }
-function autoConfigureAllClients(targetWorkspace = process.cwd(), home = os2.homedir(), options = {}) {
+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;
@@ -5064,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", "once", "json", "quiet", "no-notify"].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 {
@@ -5077,10 +5251,38 @@ 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 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") {
@@ -5168,7 +5370,7 @@ async function main() {
       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:
+        if (!flags.once && message !== lastScanError) console.error(`Scan unavailable; retained overlaps may be stale:
 ${message}`);
         lastScanError = message;
       },
@@ -5180,7 +5382,7 @@ ${message}`);
       },
       onFileChange: (e) => {
         if (!flags.quiet && !isRaw) {
-          console.log(`\u{1F4DD} [EDIT] ${path19.basename(e.repoPath)}/${e.filePath}`);
+          console.log(`\u{1F4DD} [FILE MTIME] ${path19.basename(e.repoPath)}/${e.filePath}`);
         }
       }
     });
@@ -5223,7 +5425,7 @@ ${state.errors.map((error) => error.message).join("\n")}`);
     });
     return;
   }
-  const commands = ["session", "status", "begin", "complete", "heartbeat", "task", "lock", "contract", "worktree", "port", "mutex", "hook"];
+  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"],
@@ -5246,7 +5448,7 @@ ${state.errors.map((error) => error.message).join("\n")}`);
   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
   });
@@ -5285,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;
@@ -5337,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;
@@ -5405,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;
@@ -5425,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;
@@ -5549,7 +5777,9 @@ Usage:
   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
 `);