@kynver-app/runtime 0.1.24 → 0.1.27

package/dist/index.js

@@ -422,12 +422,12 @@ var DEFAULT_CRITICAL_FREE_BYTES = 15 * 1024 * 1024 * 1024;
 var DEFAULT_MAX_USED_PERCENT = 80;
 var DEFAULT_HARD_MAX_USED_PERCENT = 90;
 function observeRunnerDiskGate(input = {}) {
-  const path18 = input.diskPath?.trim() || "/";
+  const path23 = input.diskPath?.trim() || "/";
   const warnBelowBytes = input.diskFreeWarnBytes ?? DEFAULT_WARN_FREE_BYTES;
   const criticalBelowBytes = input.diskFreeCriticalBytes ?? DEFAULT_CRITICAL_FREE_BYTES;
   const maxUsedPercent = input.diskMaxUsedPercent ?? DEFAULT_MAX_USED_PERCENT;
   const hardMaxUsedPercent = input.diskHardMaxUsedPercent ?? DEFAULT_HARD_MAX_USED_PERCENT;
-  const stats = statfsSync(path18);
+  const stats = statfsSync(path23);
   const freeBytes = Number(stats.bavail) * Number(stats.bsize);
   const totalBytes = Number(stats.blocks) * Number(stats.bsize);
   const usedPercent = totalBytes > 0 ? (totalBytes - freeBytes) / totalBytes * 100 : 100;
@@ -447,7 +447,7 @@ function observeRunnerDiskGate(input = {}) {
   }
   return {
     ok,
-    path: path18,
+    path: path23,
     freeBytes,
     totalBytes,
     usedPercent,
@@ -1700,7 +1700,7 @@ async function tryCompleteWorker(args) {
   let secret = await resolveCallbackSecretWithMint(explicitSecret, agentOsId, { baseUrl: base });
   const url = `${base}/api/agent-os/by-id/${encodeURIComponent(agentOsId)}/harness/completion`;
   const body = {
-    source: "openclaw-harness",
+    source: "kynver-harness",
     agentOsId,
     runId: worker.runId,
     workerName: worker.name,
@@ -2190,7 +2190,7 @@ function spawnWorkerProcess(run, opts) {
   }
   return worker;
 }
-function startWorker(args) {
+async function startWorker(args) {
   const run = loadRun(String(args.run));
   const name = typeof args.name === "string" ? args.name.trim() : "";
   if (!name) {
@@ -2202,8 +2202,10 @@ function startWorker(args) {
     console.error("missing --task or --task-file");
     process.exit(1);
   }
+  const wait = args.wait === true || args.wait === "true";
+  let worker;
   try {
-    const worker = spawnWorkerProcess(run, {
+    worker = spawnWorkerProcess(run, {
       name,
       task,
       ownedPaths: args.owned ? String(args.owned).split(",").map((s) => s.trim()).filter(Boolean) : [],
@@ -2231,6 +2233,18 @@ function startWorker(args) {
     console.error(`worker start failed: ${error.message}`);
     process.exit(1);
   }
+  if (!wait || !worker) return;
+  const outcome = await autoCompleteWorker({
+    run: String(args.run),
+    name: worker.name,
+    ...worker.agentOsId ? { agentOsId: worker.agentOsId } : {},
+    ...args.baseUrl ? { baseUrl: String(args.baseUrl) } : {},
+    ...args.secret ? { secret: String(args.secret) } : {}
+  });
+  console.error(JSON.stringify({ event: "start_wait_outcome", ...outcome }));
+  if (outcome.outcome === "timed_out") {
+    process.exitCode = 1;
+  }
 }
 
 // src/dispatch.ts
@@ -2254,7 +2268,7 @@ async function dispatchRun(args) {
     const secret = await resolveCallbackSecretWithMint(args.secret ? String(args.secret) : void 0, agentOsId, { baseUrl: base });
     const execute = args.execute === true || args.execute === "true";
     const dryRun = !execute;
-    const leaseOwner = `openclaw-harness:${run.id}`;
+    const leaseOwner = `kynver-harness:${run.id}`;
     const runnerDiskGate = args.diskPath ? observeRunnerDiskGate({ diskPath: String(args.diskPath) }) : observeRunnerDiskGate({ diskPath: run.repo });
     const runnerResourceGate = observeRunnerResourceGate({ runId: run.id });
     const requestedStarts = Number(args.maxStarts) > 0 ? Math.floor(Number(args.maxStarts)) : 1;
@@ -2503,7 +2517,7 @@ async function sweepRun(args) {
     const agentOsId = String(required(String(args.agentOsId || ""), "--agent-os-id"));
     const base = resolveBaseUrl(args.baseUrl ? String(args.baseUrl) : void 0);
     const secret = await resolveCallbackSecretWithMint(args.secret ? String(args.secret) : void 0, agentOsId, { baseUrl: base });
-    const leaseOwner = `openclaw-harness:${run.id}`;
+    const leaseOwner = `kynver-harness:${run.id}`;
     const snapshotPublished = await publishHarnessBoardSnapshot({ run: run.id, agentOsId, ...args }, "run_sweep");
     const releasedLocalOrphans = [];
     for (const name of Object.keys(run.workers || {})) {
@@ -2555,7 +2569,7 @@ import { mkdirSync as mkdirSync5, realpathSync } from "node:fs";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 
 // src/pipeline-tick.ts
-import path17 from "node:path";
+import path22 from "node:path";
 
 // src/stale-reconcile.ts
 import path15 from "node:path";
@@ -2758,13 +2772,433 @@ async function fetchWorkspaceRuntimePreferences(agentOsId, args) {
   }
 }
 
+// src/cleanup.ts
+import path21 from "node:path";
+
+// src/cleanup-types.ts
+var DEFAULT_NODE_MODULES_AGE_MS = 6 * 60 * 60 * 1e3;
+var DEFAULT_WORKTREES_AGE_MS = 7 * 24 * 60 * 60 * 1e3;
+
+// src/cleanup-guards.ts
+var ACTIVE_RUN_STATUSES2 = /* @__PURE__ */ new Set(["running", "dispatching", "pending", "queued", "needs_attention"]);
+var TERMINAL_RUN_STATUSES = /* @__PURE__ */ new Set(["completed", "failed", "cancelled"]);
+function prUrlFromFinalResult(finalResult) {
+  if (typeof finalResult === "string") {
+    const match = finalResult.match(/https:\/\/github\.com\/[^\s]+\/pull\/\d+/i);
+    return match?.[0] ?? null;
+  }
+  if (finalResult && typeof finalResult === "object") {
+    const obj = finalResult;
+    for (const key of ["prUrl", "pr_url", "pullRequestUrl"]) {
+      const value = obj[key];
+      if (typeof value === "string" && value.trim()) return value.trim();
+    }
+  }
+  return null;
+}
+function isPrOrUnmergedWork(status) {
+  if (prUrlFromFinalResult(status.finalResult)) return true;
+  const relation = status.gitAncestry?.relation;
+  if (relation === "ahead" || relation === "diverged") return true;
+  if (status.changedFiles.length > 0 && status.finalResult) return true;
+  return false;
+}
+function skipWorktreeRemoval(input) {
+  const { indexed, includeOrphans, worktreesAgeMs, ageMs } = input;
+  if (worktreesAgeMs <= 0) return "worktrees_disabled";
+  if (ageMs < worktreesAgeMs) return "below_age_threshold";
+  if (!indexed) return includeOrphans ? null : "orphan_without_flag";
+  if (ACTIVE_RUN_STATUSES2.has(indexed.run.status)) return "run_still_active";
+  if (!TERMINAL_RUN_STATUSES.has(indexed.run.status)) return "run_still_active";
+  if (indexed.status.alive) return "active_worker";
+  if (indexed.worker.status === "running") return "active_worker";
+  if (indexed.worker.completionBlocker) return "completion_blocked";
+  if (isPrOrUnmergedWork(indexed.status)) return "pr_or_unmerged_commits";
+  if (indexed.status.changedFiles.length > 0) return "dirty_worktree";
+  const landing = assessWorkerLanding({
+    finalResult: indexed.status.finalResult,
+    changedFiles: indexed.status.changedFiles,
+    gitAncestry: indexed.status.gitAncestry,
+    prUrl: prUrlFromFinalResult(indexed.status.finalResult)
+  });
+  if (landing.blocked) return "landing_blocked";
+  return null;
+}
+function skipNodeModulesRemoval(input) {
+  const { indexed, includeOrphans, nodeModulesAgeMs, ageMs } = input;
+  if (ageMs < nodeModulesAgeMs) return "below_age_threshold";
+  if (!indexed) return includeOrphans ? null : "orphan_without_flag";
+  if (indexed.status.alive) return "active_worker";
+  if (indexed.worker.status === "running") return "active_worker";
+  if (indexed.worker.completionBlocker) return "completion_blocked";
+  if (isPrOrUnmergedWork(indexed.status)) return "pr_or_unmerged_commits";
+  if (indexed.status.changedFiles.length > 0) return "dirty_worktree";
+  const landing = assessWorkerLanding({
+    finalResult: indexed.status.finalResult,
+    changedFiles: indexed.status.changedFiles,
+    gitAncestry: indexed.status.gitAncestry,
+    prUrl: prUrlFromFinalResult(indexed.status.finalResult)
+  });
+  if (landing.blocked) return "landing_blocked";
+  return null;
+}
+
+// src/cleanup-execute.ts
+import { existsSync as existsSync13, rmSync } from "node:fs";
+import path18 from "node:path";
+
+// src/cleanup-dir-size.ts
+import { existsSync as existsSync12, readdirSync as readdirSync4, statSync as statSync2 } from "node:fs";
+import path17 from "node:path";
+function directorySizeBytes(root, maxEntries = 5e4) {
+  if (!existsSync12(root)) return 0;
+  let total = 0;
+  let seen = 0;
+  const stack = [root];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    let entries;
+    try {
+      entries = readdirSync4(current);
+    } catch {
+      continue;
+    }
+    for (const name of entries) {
+      if (seen++ > maxEntries) return null;
+      const full = path17.join(current, name);
+      let st;
+      try {
+        st = statSync2(full);
+      } catch {
+        continue;
+      }
+      if (st.isDirectory()) stack.push(full);
+      else total += st.size;
+    }
+  }
+  return total;
+}
+
+// src/cleanup-execute.ts
+function removeNodeModules(candidate, execute) {
+  if (!existsSync13(candidate.path)) {
+    return {
+      ...candidate,
+      executed: false,
+      skipped: true,
+      skipReason: "missing_worktree"
+    };
+  }
+  if (!execute) {
+    return { ...candidate, executed: false, skipped: true, skipReason: "dry_run" };
+  }
+  try {
+    const bytesBefore = candidate.bytes ?? directorySizeBytes(candidate.path);
+    rmSync(candidate.path, { recursive: true, force: true });
+    return {
+      ...candidate,
+      bytes: bytesBefore,
+      executed: true,
+      skipped: false
+    };
+  } catch (error) {
+    return {
+      ...candidate,
+      executed: false,
+      skipped: true,
+      skipReason: "remove_failed",
+      error: error.message
+    };
+  }
+}
+function removeWorktree(candidate, execute) {
+  if (!existsSync13(candidate.path)) {
+    return {
+      ...candidate,
+      executed: false,
+      skipped: true,
+      skipReason: "missing_worktree"
+    };
+  }
+  if (!execute) {
+    return { ...candidate, executed: false, skipped: true, skipReason: "dry_run" };
+  }
+  const repo = candidate.repo;
+  try {
+    const bytesBefore = candidate.bytes ?? directorySizeBytes(candidate.path);
+    if (repo) {
+      git(repo, ["worktree", "remove", "--force", candidate.path], { allowFailure: true });
+    }
+    if (existsSync13(candidate.path)) {
+      rmSync(candidate.path, { recursive: true, force: true });
+    }
+    return {
+      ...candidate,
+      bytes: bytesBefore,
+      executed: true,
+      skipped: false
+    };
+  } catch (error) {
+    return {
+      ...candidate,
+      executed: false,
+      skipped: true,
+      skipReason: "remove_failed",
+      error: error.message
+    };
+  }
+}
+function isHarnessNodeModulesPath(targetPath, harnessRoot, worktreesDir) {
+  const resolved = path18.resolve(targetPath);
+  const nm = resolved.endsWith(`${path18.sep}node_modules`) ? resolved : null;
+  if (!nm) return "path_outside_harness";
+  const rel = path18.relative(worktreesDir, nm);
+  if (rel.startsWith("..") || path18.isAbsolute(rel)) return "path_outside_harness";
+  const parts = rel.split(path18.sep);
+  if (parts.length < 3 || parts[parts.length - 1] !== "node_modules") return "path_outside_harness";
+  if (!resolved.startsWith(path18.resolve(harnessRoot))) return "path_outside_harness";
+  return null;
+}
+
+// src/cleanup-scan.ts
+import { existsSync as existsSync14, readdirSync as readdirSync5, statSync as statSync3 } from "node:fs";
+import path19 from "node:path";
+function pathAgeMs(target, now) {
+  try {
+    const mtime = statSync3(target).mtimeMs;
+    return Math.max(0, now - mtime);
+  } catch {
+    return 0;
+  }
+}
+function isPathInside(child, parent) {
+  const rel = path19.relative(parent, child);
+  return rel === "" || !rel.startsWith("..") && !path19.isAbsolute(rel);
+}
+function scanNodeModulesCandidates(opts) {
+  const candidates = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const entry of opts.index.values()) {
+    if (opts.runIdFilter && entry.runId !== opts.runIdFilter) continue;
+    const nm = path19.join(entry.worktreePath, "node_modules");
+    if (!existsSync14(nm)) continue;
+    const resolved = path19.resolve(nm);
+    if (seen.has(resolved)) continue;
+    seen.add(resolved);
+    candidates.push({
+      kind: "remove_node_modules",
+      path: resolved,
+      bytes: null,
+      runId: entry.runId,
+      worker: entry.workerName,
+      repo: entry.run.repo,
+      ageMs: pathAgeMs(resolved, opts.now)
+    });
+  }
+  if (!opts.includeOrphans || !existsSync14(opts.worktreesDir)) return candidates;
+  for (const runEntry of readdirSync5(opts.worktreesDir, { withFileTypes: true })) {
+    if (!runEntry.isDirectory()) continue;
+    const runPath = path19.join(opts.worktreesDir, runEntry.name);
+    for (const workerEntry of readdirSync5(runPath, { withFileTypes: true })) {
+      if (!workerEntry.isDirectory()) continue;
+      const worktreePath = path19.join(runPath, workerEntry.name);
+      const nm = path19.join(worktreePath, "node_modules");
+      if (!existsSync14(nm)) continue;
+      const resolved = path19.resolve(nm);
+      if (seen.has(resolved)) continue;
+      if (!isPathInside(resolved, opts.harnessRoot)) continue;
+      seen.add(resolved);
+      candidates.push({
+        kind: "remove_node_modules",
+        path: resolved,
+        bytes: null,
+        runId: runEntry.name,
+        worker: workerEntry.name,
+        ageMs: pathAgeMs(resolved, opts.now)
+      });
+    }
+  }
+  return candidates;
+}
+function scanWorktreeCandidates(opts) {
+  if (opts.worktreesAgeMs <= 0) return [];
+  const candidates = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const entry of opts.index.values()) {
+    if (opts.runIdFilter && entry.runId !== opts.runIdFilter) continue;
+    const resolved = entry.worktreePath;
+    if (!existsSync14(resolved)) continue;
+    if (seen.has(resolved)) continue;
+    seen.add(resolved);
+    candidates.push({
+      kind: "remove_worktree",
+      path: resolved,
+      bytes: null,
+      runId: entry.runId,
+      worker: entry.workerName,
+      repo: entry.run.repo,
+      ageMs: pathAgeMs(resolved, opts.now)
+    });
+  }
+  return candidates;
+}
+
+// src/cleanup-worktree-index.ts
+import path20 from "node:path";
+function buildWorktreeIndex() {
+  const index = /* @__PURE__ */ new Map();
+  for (const run of listRunRecords()) {
+    for (const name of Object.keys(run.workers || {})) {
+      const workerPath = path20.join(runDirectory(run.id), "workers", safeSlug(name), "worker.json");
+      const worker = readJson(workerPath, void 0);
+      if (!worker?.worktreePath) continue;
+      const status = computeWorkerStatus(worker, { base: run.base, baseCommit: run.baseCommit });
+      index.set(path20.resolve(worker.worktreePath), {
+        worktreePath: path20.resolve(worker.worktreePath),
+        runId: run.id,
+        workerName: name,
+        run,
+        worker,
+        status
+      });
+    }
+  }
+  return index;
+}
+
+// src/cleanup.ts
+function resolveOptions(options = {}) {
+  const harnessRoot = options.harnessRoot ? path21.resolve(options.harnessRoot) : resolveHarnessRoot();
+  const { worktreesDir } = options.harnessRoot ? { worktreesDir: path21.join(harnessRoot, "worktrees") } : getHarnessPaths();
+  const execute = options.execute === true;
+  const nodeModulesAgeMs = options.nodeModulesAgeMs ?? DEFAULT_NODE_MODULES_AGE_MS;
+  const worktreesAgeMs = options.worktreesAgeMs ?? 0;
+  const includeOrphans = options.includeOrphans === true;
+  const runIdFilter = options.runIdFilter ? String(options.runIdFilter) : void 0;
+  const now = options.now ?? Date.now();
+  return {
+    harnessRoot,
+    worktreesDir,
+    execute,
+    dryRun: !execute,
+    nodeModulesAgeMs,
+    worktreesAgeMs,
+    includeOrphans,
+    runIdFilter,
+    now
+  };
+}
+function recordSkip(skips, pathValue, reason, detail) {
+  skips.push({ path: pathValue, reason, ...detail ? { detail } : {} });
+}
+function runHarnessCleanup(options = {}) {
+  const resolved = resolveOptions(options);
+  const index = buildWorktreeIndex();
+  const scanOpts = {
+    harnessRoot: resolved.harnessRoot,
+    worktreesDir: resolved.worktreesDir,
+    nodeModulesAgeMs: resolved.nodeModulesAgeMs,
+    worktreesAgeMs: resolved.worktreesAgeMs,
+    includeOrphans: resolved.includeOrphans,
+    runIdFilter: resolved.runIdFilter,
+    index,
+    now: resolved.now
+  };
+  const skips = [];
+  const actions = [];
+  for (const candidate of scanNodeModulesCandidates(scanOpts)) {
+    const pathSkip = isHarnessNodeModulesPath(candidate.path, resolved.harnessRoot, resolved.worktreesDir);
+    if (pathSkip) {
+      recordSkip(skips, candidate.path, pathSkip);
+      actions.push({ ...candidate, executed: false, skipped: true, skipReason: pathSkip });
+      continue;
+    }
+    const worktreePath = path21.resolve(candidate.path, "..");
+    const indexed = index.get(worktreePath) ?? null;
+    const guardReason = skipNodeModulesRemoval({
+      indexed,
+      includeOrphans: resolved.includeOrphans,
+      nodeModulesAgeMs: resolved.nodeModulesAgeMs,
+      ageMs: candidate.ageMs
+    });
+    if (guardReason) {
+      recordSkip(skips, candidate.path, guardReason);
+      actions.push({ ...candidate, executed: false, skipped: true, skipReason: guardReason });
+      continue;
+    }
+    actions.push(removeNodeModules(candidate, resolved.execute));
+  }
+  for (const candidate of scanWorktreeCandidates(scanOpts)) {
+    const indexed = index.get(path21.resolve(candidate.path)) ?? null;
+    const guardReason = skipWorktreeRemoval({
+      indexed,
+      includeOrphans: resolved.includeOrphans,
+      worktreesAgeMs: resolved.worktreesAgeMs,
+      ageMs: candidate.ageMs
+    });
+    if (guardReason) {
+      recordSkip(skips, candidate.path, guardReason);
+      actions.push({ ...candidate, executed: false, skipped: true, skipReason: guardReason });
+      continue;
+    }
+    actions.push(removeWorktree(candidate, resolved.execute));
+  }
+  let candidateBytes = 0;
+  let removedBytes = 0;
+  let removedPaths = 0;
+  let skippedPaths = 0;
+  for (const action of actions) {
+    if (action.bytes) candidateBytes += action.bytes;
+    if (action.executed) {
+      removedPaths += 1;
+      removedBytes += action.bytes ?? 0;
+    } else if (action.skipped) {
+      skippedPaths += 1;
+    }
+  }
+  return {
+    harnessRoot: resolved.harnessRoot,
+    dryRun: resolved.dryRun,
+    execute: resolved.execute,
+    nodeModulesAgeMs: resolved.nodeModulesAgeMs,
+    worktreesAgeMs: resolved.worktreesAgeMs,
+    includeOrphans: resolved.includeOrphans,
+    scannedAt: new Date(resolved.now).toISOString(),
+    actions,
+    skips,
+    totals: {
+      candidateBytes,
+      removedBytes,
+      removedPaths,
+      skippedPaths
+    }
+  };
+}
+function runPipelineHarnessCleanup(runId) {
+  const nodeModulesAgeMs = Number(process.env.KYNVER_CLEANUP_NODE_MODULES_AGE_MS) || DEFAULT_NODE_MODULES_AGE_MS;
+  const worktreesAgeMs = Number(process.env.KYNVER_CLEANUP_WORKTREES_AGE_MS) || 0;
+  const execute = process.env.KYNVER_CLEANUP_EXECUTE === "1";
+  const includeOrphans = process.env.KYNVER_CLEANUP_INCLUDE_ORPHANS === "1";
+  const scopeAll = process.env.KYNVER_CLEANUP_SCOPE === "all";
+  return runHarnessCleanup({
+    execute,
+    nodeModulesAgeMs,
+    worktreesAgeMs,
+    includeOrphans,
+    runIdFilter: scopeAll ? void 0 : runId
+  });
+}
+function isPipelineCleanupEnabled() {
+  return process.env.KYNVER_PIPELINE_CLEANUP !== "0";
+}
+
 // src/pipeline-tick.ts
 async function completeFinishedWorkers(runId, args) {
   const run = loadRun(runId);
   const outcomes = [];
   for (const name of Object.keys(run.workers || {})) {
     const worker = readJson(
-      path17.join(runDirectory(run.id), "workers", safeSlug(name), "worker.json"),
+      path22.join(runDirectory(run.id), "workers", safeSlug(name), "worker.json"),
       void 0
     );
     if (!worker?.taskId) continue;
@@ -2813,6 +3247,7 @@ async function runPipelineTick(args) {
   const operatorTick = await postOperatorTick(agentOsId, runId, resourceGate, args);
   const completedWorkers = await completeFinishedWorkers(runId, args);
   const staleReconcile = reconcileStaleWorkers();
+  const harnessCleanup = isPipelineCleanupEnabled() ? runPipelineHarnessCleanup(runId) : void 0;
   const planProgressSync = await syncActiveWorkerPlanProgress(runId, args);
   let maxStarts = resourceGate.slotsAvailable;
   const tickBody = operatorTick;
@@ -2848,6 +3283,7 @@ async function runPipelineTick(args) {
     resourceGate,
     completedWorkers,
     staleReconcile,
+    harnessCleanup,
     planProgressSync,
     operatorTick,
     sweep,
@@ -2986,6 +3422,26 @@ async function verifyPlan(args) {
   console.log(JSON.stringify(parsed, null, 2));
 }
 
+// src/cleanup-cli.ts
+function runCleanupCli(args) {
+  const execute = args.execute === true || args.execute === "true";
+  const nodeModulesAgeMs = args.nodeModulesAgeMs ? Number(args.nodeModulesAgeMs) : DEFAULT_NODE_MODULES_AGE_MS;
+  const worktreesAgeMs = args.worktreesAgeMs ? Number(args.worktreesAgeMs) : 0;
+  const includeOrphans = args.includeOrphans === true || args.includeOrphans === "true";
+  const harnessRoot = args.harnessRoot ? String(args.harnessRoot) : void 0;
+  const summary = runHarnessCleanup({
+    execute,
+    nodeModulesAgeMs: Number.isFinite(nodeModulesAgeMs) ? nodeModulesAgeMs : DEFAULT_NODE_MODULES_AGE_MS,
+    worktreesAgeMs: Number.isFinite(worktreesAgeMs) ? worktreesAgeMs : 0,
+    includeOrphans,
+    harnessRoot
+  });
+  console.log(JSON.stringify(summary, null, 2));
+  if (execute && summary.totals.removedPaths === 0 && summary.actions.length === 0) {
+    process.exitCode = 0;
+  }
+}
+
 // src/cli.ts
 function isHelpFlag(arg) {
   return arg === "help" || arg === "--help" || arg === "-h";
@@ -3009,14 +3465,15 @@ function usage(code = 0) {
       "  kynver run status --run RUN_ID",
       "  kynver run dispatch --run RUN_ID --agent-os-id AOS_ID [--base-url URL] [--secret SECRET] [--execute] [--lane any|implementation|review|landing] [--executor harness] [--max-starts 1] [--lease-ms MS] [--owned path[,path]] [--model claude-opus-4-7] [--disk-path /]",
       "  kynver run sweep --run RUN_ID --agent-os-id AOS_ID [--base-url URL] [--secret SECRET] [--grace-ms MS]",
-      '  kynver worker start --run RUN_ID --name worker --task "..." [--owned path[,path]] [--model MODEL] [--provider claude|cursor] [--agent-os-id AOS_ID] [--task-id TASK_ID]',
+      '  kynver worker start --run RUN_ID --name worker --task "..." [--owned path[,path]] [--model MODEL] [--provider claude|cursor] [--agent-os-id AOS_ID] [--task-id TASK_ID] [--wait]',
       "  kynver worker status --run RUN_ID --name worker",
       "  kynver worker tail --run RUN_ID --name worker [--lines 40] [--raw]",
       "  kynver worker stop --run RUN_ID --name worker",
       "  kynver worker complete --run RUN_ID --name worker [--agent-os-id AOS_ID] [--task-id TASK_ID] [--base-url URL] [--secret SECRET]",
       "  kynver worker auto-complete --run RUN_ID --name worker [--agent-os-id AOS_ID] [--poll-ms 5000] [--max-total-ms 21600000] [--complete-attempts 3] [--complete-backoff-ms 5000] [--base-url URL] [--secret SECRET]",
       "  kynver plan progress --plan PLAN_ID --row ROW_KEY --role ROLE --status STATUS [--task TASK_ID] [--note NOTE] [--evidence type:value] [--agent-os-id AOS_ID]",
-      "  kynver plan verify --plan PLAN_ID [--worktree PATH] [--task TASK_ID] [--human-override]"
+      "  kynver plan verify --plan PLAN_ID [--worktree PATH] [--task TASK_ID] [--human-override]",
+      "  kynver cleanup [--execute] [--node-modules-age-ms MS] [--worktrees-age-ms MS] [--harness-root PATH] [--include-orphans]"
     ].join("\n")
   );
   process.exit(code);
@@ -3043,12 +3500,13 @@ async function main(argv = process.argv.slice(2)) {
   if (scope === "daemon") return void await runDaemon(args);
   if (scope === "plan" && action === "progress") return void await emitPlanProgress(args);
   if (scope === "plan" && action === "verify") return void await verifyPlan(args);
+  if (scope === "cleanup") return runCleanupCli(args);
   if (scope === "run" && action === "create") return createRun(args);
   if (scope === "run" && action === "list") return listRuns();
   if (scope === "run" && action === "status") return runStatus(args);
   if (scope === "run" && action === "dispatch") return void await dispatchRun(args);
   if (scope === "run" && action === "sweep") return void await sweepRun(args);
-  if (scope === "worker" && action === "start") return startWorker(args);
+  if (scope === "worker" && action === "start") return void await startWorker(args);
   if (scope === "worker" && action === "status") return workerStatus(args);
   if (scope === "worker" && action === "tail") return tailWorker(args);
   if (scope === "worker" && action === "stop") return stopWorker(args);