@kynver-app/runtime 0.1.50 → 0.1.56

package/dist/finalize.d.ts

@@ -1,8 +1,17 @@
+import { type HarnessRunRecord } from "./run-store.js";
 export interface RunFinalizeResult {
     runId: string;
     from: string;
     to: string;
 }
+/** Run statuses we treat as "not yet terminal" and therefore candidates for finalization. */
+export declare const ACTIVE_RUN_STATUSES: Set<string>;
+export declare const TERMINAL_RUN_STATUSES: Set<string>;
+/**
+ * Decide the terminal status for a run, or null if it should stay active.
+ * A run is terminal once none of its workers are still alive-and-unfinished.
+ */
+export declare function deriveTerminalRunStatus(run: HarnessRunRecord): string | null;
 /**
  * Finalize runs that are still marked active but have no live workers.
  *

package/dist/index.js

@@ -4930,8 +4930,15 @@ import path24 from "node:path";
 
 // src/finalize.ts
 import path23 from "node:path";
-var ACTIVE_RUN_STATUSES = /* @__PURE__ */ new Set(["running", "dispatching", "pending", "queued"]);
-function terminalStatusFor(run) {
+var ACTIVE_RUN_STATUSES = /* @__PURE__ */ new Set([
+  "running",
+  "dispatching",
+  "pending",
+  "queued",
+  "needs_attention"
+]);
+var TERMINAL_RUN_STATUSES = /* @__PURE__ */ new Set(["completed", "failed", "cancelled", "done"]);
+function deriveTerminalRunStatus(run) {
   const names = Object.keys(run.workers || {});
   if (names.length === 0) return "failed";
   let anyAlive = false;
@@ -4969,7 +4976,7 @@ function finalizeStaleRuns() {
   const finalized = [];
   for (const run of listRunRecords()) {
     if (!ACTIVE_RUN_STATUSES.has(run.status)) continue;
-    const next = terminalStatusFor(run);
+    const next = deriveTerminalRunStatus(run);
     if (!next || next === run.status) continue;
     const from = run.status;
     run.status = next;
@@ -5161,13 +5168,26 @@ async function fetchWorkspaceRuntimePreferences(agentOsId, args) {
 // src/cleanup.ts
 import path30 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-run-liveness.ts
+function isWorkerProcessLive(indexed) {
+  if (indexed.status.alive) return true;
+  if (indexed.worker.status === "running") return true;
+  return false;
+}
+function isRunStaleActive(indexed) {
+  if (TERMINAL_RUN_STATUSES.has(indexed.run.status)) return false;
+  return deriveTerminalRunStatus(indexed.run) !== null;
+}
+function runBlocksWorktreeRemoval(indexed) {
+  if (isWorkerProcessLive(indexed)) return true;
+  if (indexed.worker.completionBlocker) return true;
+  if (TERMINAL_RUN_STATUSES.has(indexed.run.status)) return false;
+  if (isRunStaleActive(indexed)) return false;
+  if (!isFinishedWorkerStatus(indexed.status)) return true;
+  return deriveTerminalRunStatus(indexed.run) === null;
+}
 
 // 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);
@@ -5189,18 +5209,29 @@ function isPrOrUnmergedWork(status) {
   if (status.changedFiles.length > 0 && status.finalResult) return true;
   return false;
 }
+function materialWorktreeChanges(changedFiles) {
+  return changedFiles.filter((line) => {
+    const trimmed = line.trim();
+    const pathPart = trimmed.startsWith("??") ? trimmed.slice(2).trim() : trimmed.length > 3 ? trimmed.slice(3).trim() : trimmed;
+    return pathPart !== "node_modules" && !pathPart.startsWith("node_modules/");
+  });
+}
+function hasUnrestorableWorktreeChanges(status) {
+  if (materialWorktreeChanges(status.changedFiles).length > 0) return true;
+  if (status.gitAncestry?.relation === "diverged") 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 (isWorkerProcessLive(indexed)) return "active_worker";
   if (indexed.worker.completionBlocker) return "completion_blocked";
+  if (runBlocksWorktreeRemoval(indexed)) return "run_still_active";
+  if (!isFinishedWorkerStatus(indexed.status)) return "run_still_active";
   if (isPrOrUnmergedWork(indexed.status)) return "pr_or_unmerged_commits";
-  if (indexed.status.changedFiles.length > 0) return "dirty_worktree";
+  if (materialWorktreeChanges(indexed.status.changedFiles).length > 0) return "dirty_worktree";
   const landing = assessWorkerLanding({
     finalResult: indexed.status.finalResult,
     changedFiles: indexed.status.changedFiles,
@@ -5214,18 +5245,19 @@ 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 (isWorkerProcessLive(indexed)) 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";
+  if (!isFinishedWorkerStatus(indexed.status)) return "run_still_active";
+  if (hasUnrestorableWorktreeChanges(indexed.status)) 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";
+  if (landing.blocked && materialWorktreeChanges(indexed.status.changedFiles).length > 0) {
+    return "landing_blocked";
+  }
   return null;
 }
 
@@ -5452,48 +5484,98 @@ function buildWorktreeIndex() {
   return index;
 }
 
-// src/cleanup.ts
-function resolveOptions(options = {}) {
-  const harnessRoot = options.harnessRoot ? resolveUserPath(options.harnessRoot) : resolveHarnessRoot();
-  const { worktreesDir } = options.harnessRoot ? { worktreesDir: path30.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();
+// 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-retention-config.ts
+function envFlag(name) {
+  const v = process.env[name];
+  return v === "1" || v === "true" || v === "yes";
+}
+function envMs(name, fallback) {
+  const raw = process.env[name];
+  if (!raw) return fallback;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 0 ? n : fallback;
+}
+function resolveHarnessRetention(options = {}) {
+  const execute = options.execute === true || options.execute !== false && envFlag("KYNVER_CLEANUP_EXECUTE");
+  const finalizeStaleRuns2 = options.finalizeStaleRuns !== false && !envFlag("KYNVER_CLEANUP_SKIP_FINALIZE");
+  const nodeModulesAgeMs = options.nodeModulesAgeMs ?? envMs("KYNVER_CLEANUP_NODE_MODULES_AGE_MS", DEFAULT_NODE_MODULES_AGE_MS);
+  const worktreesAgeMs = options.worktreesAgeMs ?? envMs("KYNVER_CLEANUP_WORKTREES_AGE_MS", 0);
+  const includeOrphans = options.includeOrphans === true || envFlag("KYNVER_CLEANUP_INCLUDE_ORPHANS");
+  const scopeAll = envFlag("KYNVER_CLEANUP_SCOPE_ALL") || process.env.KYNVER_CLEANUP_SCOPE === "all";
+  const runIdFilter = scopeAll ? options.runIdFilter : options.runIdFilter ?? (process.env.KYNVER_CLEANUP_RUN_ID || void 0);
+  const accountBytes = options.accountBytes !== false && !envFlag("KYNVER_CLEANUP_SKIP_BYTE_ACCOUNTING");
   return {
-    harnessRoot,
-    worktreesDir,
     execute,
-    dryRun: !execute,
+    finalizeStaleRuns: finalizeStaleRuns2,
     nodeModulesAgeMs,
-    worktreesAgeMs,
+    worktreesAgeMs: worktreesAgeMs > 0 ? worktreesAgeMs : 0,
     includeOrphans,
-    runIdFilter,
-    now
+    runIdFilter: runIdFilter ? String(runIdFilter) : void 0,
+    accountBytes
   };
 }
+function resolvePipelineHarnessRetention(runId) {
+  const scopeAll = process.env.KYNVER_CLEANUP_SCOPE === "all";
+  const envWorktrees = Number(process.env.KYNVER_CLEANUP_WORKTREES_AGE_MS);
+  const worktreesAgeMs = scopeAll ? Number.isFinite(envWorktrees) && envWorktrees > 0 ? envWorktrees : DEFAULT_WORKTREES_AGE_MS : Number.isFinite(envWorktrees) && envWorktrees > 0 ? envWorktrees : 0;
+  return resolveHarnessRetention({
+    runIdFilter: scopeAll ? void 0 : runId,
+    worktreesAgeMs,
+    finalizeStaleRuns: true,
+    accountBytes: true
+  });
+}
+
+// src/cleanup.ts
+function resolvePaths(options = {}) {
+  const harnessRoot = options.harnessRoot ? resolveUserPath(options.harnessRoot) : resolveHarnessRoot();
+  const { worktreesDir } = options.harnessRoot ? { worktreesDir: path30.join(harnessRoot, "worktrees") } : getHarnessPaths();
+  const now = options.now ?? Date.now();
+  return { harnessRoot, worktreesDir, now };
+}
 function recordSkip(skips, pathValue, reason, detail) {
   skips.push({ path: pathValue, reason, ...detail ? { detail } : {} });
 }
+function attachCandidateBytes(candidate, accountBytes) {
+  if (!accountBytes || candidate.bytes != null) return candidate;
+  return { ...candidate, bytes: directorySizeBytes(candidate.path) };
+}
+function tallySkipReasons(actions, skips) {
+  const counts = {};
+  for (const skip of skips) {
+    counts[skip.reason] = (counts[skip.reason] ?? 0) + 1;
+  }
+  for (const action of actions) {
+    if (action.skipReason) {
+      counts[action.skipReason] = (counts[action.skipReason] ?? 0) + 1;
+    }
+  }
+  return counts;
+}
 function runHarnessCleanup(options = {}) {
-  const resolved = resolveOptions(options);
+  const retention = resolveHarnessRetention(options);
+  const paths = resolvePaths(options);
+  const finalizedRuns = retention.finalizeStaleRuns ? finalizeStaleRuns().map((f) => ({ runId: f.runId, from: f.from, to: f.to })) : [];
   const index = buildWorktreeIndex();
   const scanOpts = {
-    harnessRoot: resolved.harnessRoot,
-    worktreesDir: resolved.worktreesDir,
-    nodeModulesAgeMs: resolved.nodeModulesAgeMs,
-    worktreesAgeMs: resolved.worktreesAgeMs,
-    includeOrphans: resolved.includeOrphans,
-    runIdFilter: resolved.runIdFilter,
+    harnessRoot: paths.harnessRoot,
+    worktreesDir: paths.worktreesDir,
+    nodeModulesAgeMs: retention.nodeModulesAgeMs,
+    worktreesAgeMs: retention.worktreesAgeMs,
+    includeOrphans: retention.includeOrphans,
+    runIdFilter: retention.runIdFilter,
     index,
-    now: resolved.now
+    now: paths.now
   };
   const skips = [];
   const actions = [];
-  for (const candidate of scanNodeModulesCandidates(scanOpts)) {
-    const pathSkip = isHarnessNodeModulesPath(candidate.path, resolved.harnessRoot, resolved.worktreesDir);
+  for (const raw of scanNodeModulesCandidates(scanOpts)) {
+    const candidate = attachCandidateBytes(raw, retention.accountBytes);
+    const pathSkip = isHarnessNodeModulesPath(candidate.path, paths.harnessRoot, paths.worktreesDir);
     if (pathSkip) {
       recordSkip(skips, candidate.path, pathSkip);
       actions.push({ ...candidate, executed: false, skipped: true, skipReason: pathSkip });
@@ -5503,8 +5585,8 @@ function runHarnessCleanup(options = {}) {
     const indexed = index.get(worktreePath) ?? null;
     const guardReason = skipNodeModulesRemoval({
       indexed,
-      includeOrphans: resolved.includeOrphans,
-      nodeModulesAgeMs: resolved.nodeModulesAgeMs,
+      includeOrphans: retention.includeOrphans,
+      nodeModulesAgeMs: retention.nodeModulesAgeMs,
       ageMs: candidate.ageMs
     });
     if (guardReason) {
@@ -5512,14 +5594,15 @@ function runHarnessCleanup(options = {}) {
       actions.push({ ...candidate, executed: false, skipped: true, skipReason: guardReason });
       continue;
     }
-    actions.push(removeNodeModules(candidate, resolved.execute));
+    actions.push(removeNodeModules(candidate, retention.execute));
   }
-  for (const candidate of scanWorktreeCandidates(scanOpts)) {
+  for (const raw of scanWorktreeCandidates(scanOpts)) {
+    const candidate = attachCandidateBytes(raw, retention.accountBytes);
     const indexed = index.get(path30.resolve(candidate.path)) ?? null;
     const guardReason = skipWorktreeRemoval({
       indexed,
-      includeOrphans: resolved.includeOrphans,
-      worktreesAgeMs: resolved.worktreesAgeMs,
+      includeOrphans: retention.includeOrphans,
+      worktreesAgeMs: retention.worktreesAgeMs,
       ageMs: candidate.ageMs
     });
     if (guardReason) {
@@ -5527,51 +5610,55 @@ function runHarnessCleanup(options = {}) {
       actions.push({ ...candidate, executed: false, skipped: true, skipReason: guardReason });
       continue;
     }
-    actions.push(removeWorktree(candidate, resolved.execute));
+    actions.push(removeWorktree(candidate, retention.execute));
   }
   let candidateBytes = 0;
+  let reclaimableBytes = 0;
   let removedBytes = 0;
   let removedPaths = 0;
   let skippedPaths = 0;
   for (const action of actions) {
     if (action.bytes) candidateBytes += action.bytes;
+    if (!action.skipped && !action.executed && action.bytes) reclaimableBytes += action.bytes;
     if (action.executed) {
       removedPaths += 1;
       removedBytes += action.bytes ?? 0;
     } else if (action.skipped) {
       skippedPaths += 1;
+      if (action.skipReason === "dry_run" && action.bytes) reclaimableBytes += action.bytes;
     }
   }
   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(),
+    harnessRoot: paths.harnessRoot,
+    dryRun: !retention.execute,
+    execute: retention.execute,
+    nodeModulesAgeMs: retention.nodeModulesAgeMs,
+    worktreesAgeMs: retention.worktreesAgeMs,
+    includeOrphans: retention.includeOrphans,
+    scannedAt: new Date(paths.now).toISOString(),
+    finalizedRuns,
     actions,
     skips,
     totals: {
       candidateBytes,
+      reclaimableBytes,
       removedBytes,
       removedPaths,
-      skippedPaths
+      skippedPaths,
+      skipReasons: tallySkipReasons(actions, skips)
     }
   };
 }
 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";
+  const retention = resolvePipelineHarnessRetention(runId);
   return runHarnessCleanup({
-    execute,
-    nodeModulesAgeMs,
-    worktreesAgeMs,
-    includeOrphans,
-    runIdFilter: scopeAll ? void 0 : runId
+    execute: retention.execute,
+    finalizeStaleRuns: retention.finalizeStaleRuns,
+    accountBytes: retention.accountBytes,
+    nodeModulesAgeMs: retention.nodeModulesAgeMs,
+    worktreesAgeMs: retention.worktreesAgeMs,
+    includeOrphans: retention.includeOrphans,
+    runIdFilter: retention.runIdFilter
   });
 }
 function isPipelineCleanupEnabled() {
@@ -6238,12 +6325,14 @@ async function runPlanOutboxDrain(args) {
 // src/cleanup-cli.ts
 function runCleanupCli(args) {
   const execute = args.execute === true || args.execute === "true";
+  const skipFinalize = args.skipFinalize === true || args.skipFinalize === "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,
+    finalizeStaleRuns: !skipFinalize,
     nodeModulesAgeMs: Number.isFinite(nodeModulesAgeMs) ? nodeModulesAgeMs : DEFAULT_NODE_MODULES_AGE_MS,
     worktreesAgeMs: Number.isFinite(worktreesAgeMs) ? worktreesAgeMs : 0,
     includeOrphans,
@@ -7362,7 +7451,7 @@ function usage(code = 0) {
       "  kynver plan persist --operation create|add_version|update_metadata --title TITLE (--body-file PATH | --body TEXT) [--slug SLUG] [--plan PLAN_ID] [--summary TEXT] [--failure-kind approval_guard|auth|network|server|tool_interruption]",
       "  kynver plan outbox list",
       "  kynver plan outbox drain [--max N] [--id OUTBOX_ID]",
-      "  kynver cleanup [--execute] [--node-modules-age-ms MS] [--worktrees-age-ms MS] [--harness-root PATH] [--include-orphans]",
+      "  kynver cleanup [--execute] [--node-modules-age-ms MS] [--worktrees-age-ms MS] [--harness-root PATH] [--include-orphans] [--skip-finalize]",
       "  kynver monitor start --run RUN_ID [--name worker] [--agent-os-id AOS_ID] [--poll-ms MS]",
       "  kynver monitor status [--run RUN_ID] [--name worker] [--tick]",
       "  kynver monitor stop --run RUN_ID [--name worker]",