kith-coord 0.1.3 → 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

@@ -543,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;
@@ -587,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;
@@ -699,6 +715,7 @@ interface PostFileEditHookResult {
     warnings: string[];
 }
 declare class KithEngine {
+    private activeClaimWaits;
     readonly coordDb: CoordDatabase;
     readonly fencing: FencingAndAgentManager;
     readonly locks: LockEngine;
@@ -786,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;
@@ -979,7 +1019,7 @@ declare function recoveryReport(directory?: string): {
     error: string | undefined;
 };
 
-declare const KITH_VERSION = "0.1.3";
-declare const KITH_PROTOCOL_VERSION = "1.2.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.3";
-var KITH_PROTOCOL_VERSION = "1.2.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";
@@ -643,7 +674,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();
@@ -1386,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) {
@@ -1520,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);
@@ -1566,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.");
@@ -1608,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)));
         }
@@ -1635,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)));
           }
@@ -1684,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--;
@@ -3425,6 +3498,7 @@ var CoWWorktreeManager = class _CoWWorktreeManager {
 
 // src/core/engine.ts
 var KithEngine = class {
+  activeClaimWaits = 0;
   coordDb;
   fencing;
   locks;
@@ -3577,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);
@@ -3597,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();
   }