kith-coord 0.1.2 → 0.1.4

package/dist/command-worker.js

@@ -13,7 +13,7 @@ process.once("message", (message) => {
   if (started) return;
   started = true;
   let finished = false;
-  const env = { ...process.env, ...message.mutexName === "package-install" ? { KITH_PACKAGE_INSTALL_GUARDED: "1" } : {} };
+  const env = { ...process.env, ...message.env, ...message.mutexName === "package-install" ? { KITH_PACKAGE_INSTALL_GUARDED: "1" } : {} };
   const child = Array.isArray(message.command) ? spawn(message.command[0], message.command.slice(1), { cwd: message.cwd, env, stdio: ["ignore", "inherit", "inherit"] }) : spawn(message.command, { cwd: message.cwd, env, stdio: ["ignore", "inherit", "inherit"], shell: true });
   child.once("error", (err) => {
     if (finished) return;

package/dist/command-worker.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/core/command-worker.ts"],"sourcesContent":["// A detached process-group leader. The command cannot start until its supervisor\n// has durably recorded this group and sent the start message over private IPC.\nimport os from 'node:os';\nimport { spawn } from 'node:child_process';\n\nlet started = false;\nprocess.on('disconnect', () => {\n  try { process.kill(-process.pid, 'SIGKILL'); } catch { process.exit(1); }\n});\nprocess.once('message', (message: { command: string | string[]; cwd: string; mutexName: string }) => {\n  if (started) return;\n  started = true;\n  let finished = false;\n  const env = { ...process.env, ...(message.mutexName === 'package-install' ? { KITH_PACKAGE_INSTALL_GUARDED: '1' } : {}) };\n  const child = Array.isArray(message.command)\n    ? spawn(message.command[0], message.command.slice(1), { cwd: message.cwd, env, stdio: ['ignore', 'inherit', 'inherit'] })\n    : spawn(message.command, { cwd: message.cwd, env, stdio: ['ignore', 'inherit', 'inherit'], shell: true });\n  child.once('error', (err) => {\n    if (finished) return;\n    finished = true;\n    process.send?.({ error: err.message }, () => process.exit(1));\n  });\n  child.once('close', (code, signal) => {\n    if (finished) return;\n    finished = true;\n    if (process.connected) process.send?.({ exitCode: code ?? (signal ? 128 + (os.constants.signals[signal] ?? 1) : 1), signal }, () => process.exit(0));\n  });\n});\nprocess.send?.({ ready: true });\n"],"mappings":";AAEA,OAAO,QAAQ;AACf,SAAS,aAAa;AAEtB,IAAI,UAAU;AACd,QAAQ,GAAG,cAAc,MAAM;AAC7B,MAAI;AAAE,YAAQ,KAAK,CAAC,QAAQ,KAAK,SAAS;AAAA,EAAG,QAAQ;AAAE,YAAQ,KAAK,CAAC;AAAA,EAAG;AAC1E,CAAC;AACD,QAAQ,KAAK,WAAW,CAAC,YAA4E;AACnG,MAAI,QAAS;AACb,YAAU;AACV,MAAI,WAAW;AACf,QAAM,MAAM,EAAE,GAAG,QAAQ,KAAK,GAAI,QAAQ,cAAc,oBAAoB,EAAE,8BAA8B,IAAI,IAAI,CAAC,EAAG;AACxH,QAAM,QAAQ,MAAM,QAAQ,QAAQ,OAAO,IACvC,MAAM,QAAQ,QAAQ,CAAC,GAAG,QAAQ,QAAQ,MAAM,CAAC,GAAG,EAAE,KAAK,QAAQ,KAAK,KAAK,OAAO,CAAC,UAAU,WAAW,SAAS,EAAE,CAAC,IACtH,MAAM,QAAQ,SAAS,EAAE,KAAK,QAAQ,KAAK,KAAK,OAAO,CAAC,UAAU,WAAW,SAAS,GAAG,OAAO,KAAK,CAAC;AAC1G,QAAM,KAAK,SAAS,CAAC,QAAQ;AAC3B,QAAI,SAAU;AACd,eAAW;AACX,YAAQ,OAAO,EAAE,OAAO,IAAI,QAAQ,GAAG,MAAM,QAAQ,KAAK,CAAC,CAAC;AAAA,EAC9D,CAAC;AACD,QAAM,KAAK,SAAS,CAAC,MAAM,WAAW;AACpC,QAAI,SAAU;AACd,eAAW;AACX,QAAI,QAAQ,UAAW,SAAQ,OAAO,EAAE,UAAU,SAAS,SAAS,OAAO,GAAG,UAAU,QAAQ,MAAM,KAAK,KAAK,IAAI,OAAO,GAAG,MAAM,QAAQ,KAAK,CAAC,CAAC;AAAA,EACrJ,CAAC;AACH,CAAC;AACD,QAAQ,OAAO,EAAE,OAAO,KAAK,CAAC;","names":[]}
+{"version":3,"sources":["../src/core/command-worker.ts"],"sourcesContent":["// A detached process-group leader. The command cannot start until its supervisor\n// has durably recorded this group and sent the start message over private IPC.\nimport os from 'node:os';\nimport { spawn } from 'node:child_process';\n\nlet started = false;\nprocess.on('disconnect', () => {\n  try { process.kill(-process.pid, 'SIGKILL'); } catch { process.exit(1); }\n});\nprocess.once('message', (message: { command: string | string[]; cwd: string; mutexName: string; env?: Record<string, string> }) => {\n  if (started) return;\n  started = true;\n  let finished = false;\n  const env = { ...process.env, ...message.env, ...(message.mutexName === 'package-install' ? { KITH_PACKAGE_INSTALL_GUARDED: '1' } : {}) };\n  const child = Array.isArray(message.command)\n    ? spawn(message.command[0], message.command.slice(1), { cwd: message.cwd, env, stdio: ['ignore', 'inherit', 'inherit'] })\n    : spawn(message.command, { cwd: message.cwd, env, stdio: ['ignore', 'inherit', 'inherit'], shell: true });\n  child.once('error', (err) => {\n    if (finished) return;\n    finished = true;\n    process.send?.({ error: err.message }, () => process.exit(1));\n  });\n  child.once('close', (code, signal) => {\n    if (finished) return;\n    finished = true;\n    if (process.connected) process.send?.({ exitCode: code ?? (signal ? 128 + (os.constants.signals[signal] ?? 1) : 1), signal }, () => process.exit(0));\n  });\n});\nprocess.send?.({ ready: true });\n"],"mappings":";AAEA,OAAO,QAAQ;AACf,SAAS,aAAa;AAEtB,IAAI,UAAU;AACd,QAAQ,GAAG,cAAc,MAAM;AAC7B,MAAI;AAAE,YAAQ,KAAK,CAAC,QAAQ,KAAK,SAAS;AAAA,EAAG,QAAQ;AAAE,YAAQ,KAAK,CAAC;AAAA,EAAG;AAC1E,CAAC;AACD,QAAQ,KAAK,WAAW,CAAC,YAA0G;AACjI,MAAI,QAAS;AACb,YAAU;AACV,MAAI,WAAW;AACf,QAAM,MAAM,EAAE,GAAG,QAAQ,KAAK,GAAG,QAAQ,KAAK,GAAI,QAAQ,cAAc,oBAAoB,EAAE,8BAA8B,IAAI,IAAI,CAAC,EAAG;AACxI,QAAM,QAAQ,MAAM,QAAQ,QAAQ,OAAO,IACvC,MAAM,QAAQ,QAAQ,CAAC,GAAG,QAAQ,QAAQ,MAAM,CAAC,GAAG,EAAE,KAAK,QAAQ,KAAK,KAAK,OAAO,CAAC,UAAU,WAAW,SAAS,EAAE,CAAC,IACtH,MAAM,QAAQ,SAAS,EAAE,KAAK,QAAQ,KAAK,KAAK,OAAO,CAAC,UAAU,WAAW,SAAS,GAAG,OAAO,KAAK,CAAC;AAC1G,QAAM,KAAK,SAAS,CAAC,QAAQ;AAC3B,QAAI,SAAU;AACd,eAAW;AACX,YAAQ,OAAO,EAAE,OAAO,IAAI,QAAQ,GAAG,MAAM,QAAQ,KAAK,CAAC,CAAC;AAAA,EAC9D,CAAC;AACD,QAAM,KAAK,SAAS,CAAC,MAAM,WAAW;AACpC,QAAI,SAAU;AACd,eAAW;AACX,QAAI,QAAQ,UAAW,SAAQ,OAAO,EAAE,UAAU,SAAS,SAAS,OAAO,GAAG,UAAU,QAAQ,MAAM,KAAK,KAAK,IAAI,OAAO,GAAG,MAAM,QAAQ,KAAK,CAAC,CAAC;AAAA,EACrJ,CAAC;AACH,CAAC;AACD,QAAQ,OAAO,EAAE,OAAO,KAAK,CAAC;","names":[]}

package/dist/index.d.ts

@@ -74,6 +74,7 @@ declare class FencingAndAgentManager {
     static readonly DEFAULT_LEASE_MS: number;
     private readonly capabilities;
     private static ownWindowsStart;
+    private static inspectionFailure;
     constructor(coordDb: CoordDatabase);
     static validateLease(duration: number): number;
     /** A real kernel process identity; tests must not supply liveness sentinels. */
@@ -542,6 +543,19 @@ interface ResourceRecord {
     acquired_at: number;
     expires_at: number;
 }
+interface SupervisedCommandOptions {
+    agentId: string;
+    command: string | string[];
+    cwd?: string;
+    timeoutMs?: number;
+    commandTimeoutMs?: number;
+    leaseDurationMs?: number;
+    killGraceMs?: number;
+    signal?: AbortSignal;
+    maxOutputBytes?: number;
+    onStdout?: (chunk: Buffer) => void;
+    onStderr?: (chunk: Buffer) => void;
+}
 declare class ResourceBroker {
     private readonly coordDb;
     private readonly fencing;
@@ -586,26 +600,29 @@ declare class ResourceBroker {
         mutexName: string;
         fencingToken: number;
     }): boolean;
+    /** Launch on the allocated port, without interpreting arguments as shell code. */
+    executeWithPort(params: Omit<SupervisedCommandOptions, 'command'> & {
+        command: string[];
+        serviceName: string;
+        basePort?: number;
+        onPort?: (port: number) => void;
+    }): Promise<{
+        port: number;
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+        waitedMs: number;
+    }>;
     /** Renew leases while a detached, recorded process group runs; stop it before releasing. */
-    executeWithMutex(params: {
-        agentId: string;
+    executeWithMutex(params: SupervisedCommandOptions & {
         mutexName: string;
-        command: string | string[];
-        cwd?: string;
-        timeoutMs?: number;
-        commandTimeoutMs?: number;
-        leaseDurationMs?: number;
-        killGraceMs?: number;
-        signal?: AbortSignal;
-        maxOutputBytes?: number;
-        onStdout?: (chunk: Buffer) => void;
-        onStderr?: (chunk: Buffer) => void;
     }): Promise<{
         stdout: string;
         stderr: string;
         exitCode: number;
         waitedMs: number;
     }>;
+    private executeGuarded;
     private getRun;
     private runIsAlive;
     private clearRun;
@@ -698,6 +715,7 @@ interface PostFileEditHookResult {
     warnings: string[];
 }
 declare class KithEngine {
+    private activeClaimWaits;
     readonly coordDb: CoordDatabase;
     readonly fencing: FencingAndAgentManager;
     readonly locks: LockEngine;
@@ -785,6 +803,29 @@ declare class KithEngine {
         lockConflicts: LockConflict[];
         activeSiblingIntents: TaskRecord[];
     };
+    beginWorkWhenAvailable(params: Parameters<KithEngine['beginWork']>[0] & {
+        waitTimeoutMs: number;
+        signal?: AbortSignal;
+    }): Promise<{
+        worktree: SpawnedWorktree | null;
+        ok: boolean;
+        task: TaskRecord | null;
+        fencingToken: number;
+        locks: LockRecord[];
+        lockConflicts: LockConflict[];
+        activeSiblingIntents: TaskRecord[];
+    } & {
+        waitedMs: number;
+        waitTimedOut: boolean;
+    }>;
+    acquireLocksWhenAvailable(params: Parameters<LockEngine['acquireLocks']>[0] & {
+        waitTimeoutMs: number;
+        signal?: AbortSignal;
+    }): Promise<AcquireLockResult & {
+        waitedMs: number;
+        waitTimedOut: boolean;
+    }>;
+    private waitForOwnedClaim;
     completeWork(params: {
         agentId: string;
         taskId?: string;
@@ -978,7 +1019,7 @@ declare function recoveryReport(directory?: string): {
     error: string | undefined;
 };
 
-declare const KITH_VERSION = "0.1.2";
-declare const KITH_PROTOCOL_VERSION = "1.1.0";
+declare const KITH_VERSION = "0.1.4";
+declare const KITH_PROTOCOL_VERSION = "1.3.0";
 
-export { type AcquireLockResult, type AgentRecord, type AgentUnreadDelta, AstAnalyzer, type BashGuardPostReport, BashMerkleGuard, type BlastRadiusAlert, CoWWorktreeManager, type ConflictRecord, type ContractRecord, CoordDatabase, type CoordEvent, type DeclareIntentResult, DependencyAndContractEngine, type DirtyMergeProbeResult, type ExtractedImport, type ExtractedSymbol, FencingAndAgentManager, type FileAstAnalysis, type FileModificationReport, type FileSnapshotEntry, IntentAndTaskEngine, KITH_PROTOCOL_VERSION, KITH_VERSION, KithEngine, type LockConflict, LockEngine, type LockRecord, type MergeTrainEntry, type PostFileEditHookResult, type QuarantineRecord, type RepositoryLayout, ResourceBroker, type ResourceRecord, SessionOwnershipError, type SessionRegistration, ShadowGitEngine, type SpawnedWorktree, type SpeculativeMergeResult, SpeculativeMergeTrain, StaleFencingTokenError, type SymbolKind, type TaskRecord, type WorkspaceObservation, type WorktreeChange, caseSensitivePaths, discoverRepository, isWithin, observeWorkspaces, physicalPath, previewIntegration, readCoordinationState, recoveryReport, repositoryFile, worktreeChanges };
+export { type AcquireLockResult, type AgentRecord, type AgentUnreadDelta, AstAnalyzer, type BashGuardPostReport, BashMerkleGuard, type BlastRadiusAlert, CoWWorktreeManager, type ConflictRecord, type ContractRecord, CoordDatabase, type CoordEvent, type DeclareIntentResult, DependencyAndContractEngine, type DirtyMergeProbeResult, type ExtractedImport, type ExtractedSymbol, FencingAndAgentManager, type FileAstAnalysis, type FileModificationReport, type FileSnapshotEntry, IntentAndTaskEngine, KITH_PROTOCOL_VERSION, KITH_VERSION, KithEngine, type LockConflict, LockEngine, type LockRecord, type MergeTrainEntry, type PostFileEditHookResult, type QuarantineRecord, type RepositoryLayout, ResourceBroker, type ResourceRecord, SessionOwnershipError, type SessionRegistration, ShadowGitEngine, type SpawnedWorktree, type SpeculativeMergeResult, SpeculativeMergeTrain, StaleFencingTokenError, type SupervisedCommandOptions, type SymbolKind, type TaskRecord, type WorkspaceObservation, type WorktreeChange, caseSensitivePaths, discoverRepository, isWithin, observeWorkspaces, physicalPath, previewIntegration, readCoordinationState, recoveryReport, repositoryFile, worktreeChanges };

package/dist/index.js

@@ -1,6 +1,37 @@
+// 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/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/core/workspace-observation.ts
 import { execFileSync as execFileSync2, spawnSync } from "child_process";
@@ -51,6 +82,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,
@@ -615,6 +649,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");
@@ -623,6 +658,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") {
@@ -638,11 +674,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;
@@ -654,7 +693,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;
     }
   }
@@ -684,7 +725,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");
@@ -1376,6 +1417,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) {
@@ -1510,8 +1552,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);
@@ -1556,6 +1634,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) => fs6.existsSync(name));
       if (!script) throw new Error("Missing command worker. Build Kith before running supervised commands.");
@@ -1598,6 +1678,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)));
         }
@@ -1625,8 +1706,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)));
           }
@@ -1674,6 +1756,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--;
@@ -3415,6 +3498,7 @@ var CoWWorktreeManager = class _CoWWorktreeManager {
 
 // src/core/engine.ts
 var KithEngine = class {
+  activeClaimWaits = 0;
   coordDb;
   fencing;
   locks;
@@ -3567,6 +3651,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);
@@ -3587,6 +3687,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();
   }