@kynver-app/runtime 0.1.56 → 0.1.60

package/dist/callbacks.d.ts

@@ -1,3 +1,17 @@
+/** WSL host disk snapshot — present only when the runner is under WSL.
+ * The field is optional/nullable so older runners (no probe) and non-WSL
+ * runners both serialize as `wslHost: null` for the dispatch-next server. */
+export interface DispatchNextWslHostShape {
+    ok: boolean;
+    path: string;
+    freeBytes: number;
+    totalBytes: number;
+    usedPercent: number;
+    warnBelowBytes: number;
+    criticalBelowBytes: number;
+    reason: string | null;
+    probeError: string | null;
+}
 export interface DispatchNextDiskGateShape {
     ok: boolean;
     path: string;
@@ -9,6 +23,9 @@ export interface DispatchNextDiskGateShape {
     maxUsedPercent: number;
     hardMaxUsedPercent: number;
     reason: string | null;
+    /** Windows host disk under WSL (`/mnt/c` by default). `null` on non-WSL
+     * hosts and when the probe was opted out via `skipWslHostCheck`. */
+    wslHost?: DispatchNextWslHostShape | null;
 }
 export interface DispatchNextResourceGateShape {
     ok: boolean;

package/dist/cleanup-guards-helpers.d.ts

@@ -0,0 +1,2 @@
+/** Strip generated install trees from porcelain — they are what cleanup removes. */
+export declare function materialWorktreeChanges(changedFiles: string[]): string[];

package/dist/cleanup-guards.d.ts

@@ -1,17 +1,28 @@
-import type { CleanupSkipReason } from "./cleanup-types.js";
+import type { CleanupSkipReason, WorktreeRemovalGuardHook } from "./cleanup-types.js";
 import type { IndexedWorktree } from "./cleanup-worktree-index.js";
 import type { RawHarnessWorkerStatus } from "./status.js";
+export { materialWorktreeChanges } from "./cleanup-guards-helpers.js";
 /** Blocks whole-worktree removal when commits are not landed or tree is dirty. */
 export declare function isPrOrUnmergedWork(status: RawHarnessWorkerStatus): boolean;
-/** Strip generated install trees from porcelain — they are what cleanup removes. */
-export declare function materialWorktreeChanges(changedFiles: string[]): string[];
 export interface WorktreeGuardInput {
     indexed: IndexedWorktree | null;
+    /** Resolved worktree directory (required for overlay guards on orphans). */
+    worktreePath: string;
     includeOrphans: boolean;
     worktreesAgeMs: number;
     ageMs: number;
+    /**
+     * Filesystem-derived skip reason for orphan candidates (computed by
+     * `assessOrphanWorktreeSafety`). Used only when `indexed` is null.
+     */
+    orphanSafety?: CleanupSkipReason | null;
+    worktreeRemovalGuard?: WorktreeRemovalGuardHook;
 }
-export declare function skipWorktreeRemoval(input: WorktreeGuardInput): CleanupSkipReason | null;
+export type WorktreeGuardSkip = CleanupSkipReason | {
+    reason: CleanupSkipReason;
+    detail?: string;
+};
+export declare function skipWorktreeRemoval(input: WorktreeGuardInput): WorktreeGuardSkip | null;
 export interface NodeModulesGuardInput {
     indexed: IndexedWorktree | null;
     includeOrphans: boolean;

package/dist/cleanup-orphan-safety.d.ts

@@ -0,0 +1,17 @@
+import type { CleanupSkipReason } from "./cleanup-types.js";
+export interface OrphanSafetyInput {
+    worktreePath: string;
+    harnessRoot: string;
+    runId?: string;
+    workerName?: string;
+    heartbeatFreshMs?: number;
+    now?: number;
+}
+/**
+ * Inspect filesystem signals for an orphan worktree (no run/worker.json index entry).
+ *
+ * Returns a `CleanupSkipReason` when removal is unsafe, or `null` when the orphan
+ * appears safe to delete. Conservative on errors — any unreadable git state or
+ * unexpected layout returns `pr_or_unmerged_commits` so genuine work is preserved.
+ */
+export declare function assessOrphanWorktreeSafety(input: OrphanSafetyInput): CleanupSkipReason | null;

package/dist/cleanup-types.d.ts

@@ -1,5 +1,7 @@
 export type CleanupActionKind = "remove_node_modules" | "remove_worktree";
-export type CleanupSkipReason = "dry_run" | "below_age_threshold" | "active_worker" | "dirty_worktree" | "landing_blocked" | "pr_or_unmerged_commits" | "completion_blocked" | "run_still_active" | "path_outside_harness" | "worktrees_disabled" | "orphan_without_flag" | "missing_worktree" | "remove_failed";
+export type CleanupSkipReason = "dry_run" | "below_age_threshold" | "active_worker" | "dirty_worktree" | "landing_blocked" | "pr_or_unmerged_commits" | "completion_blocked" | "run_still_active" | "path_outside_harness" | "worktrees_disabled" | "orphan_without_flag" | "missing_worktree" | "remove_failed"
+/** AgentOS / operator lifecycle overlay blocked removal (see `detail`). */
+ | "board_lifecycle_blocked";
 export interface CleanupCandidate {
     kind: CleanupActionKind;
     path: string;
@@ -20,6 +22,15 @@ export interface RunFinalizeSummary {
     from: string;
     to: string;
 }
+export interface HarnessStorageSnapshotShape {
+    harnessRoot: string;
+    worktreesDir: string;
+    worktreesBytes: number | null;
+    runCount: number;
+    workerCount: number;
+    oldestRunAt: string | null;
+    scannedAt: string;
+}
 export interface HarnessCleanupSummary {
     harnessRoot: string;
     dryRun: boolean;
@@ -43,7 +54,21 @@ export interface HarnessCleanupSummary {
         skippedPaths: number;
         skipReasons: Partial<Record<CleanupSkipReason, number>>;
     };
+    /** Disk-pressure evidence — present when bytes accounting is enabled. */
+    storage?: HarnessStorageSnapshotShape;
+}
+export interface WorktreeRemovalGuardInput {
+    worktreePath: string;
+    /** True when `buildWorktreeIndex()` has a worker.json entry for this path. */
+    indexed: boolean;
+    runId?: string;
+    worker?: string;
 }
+/** Optional overlay (e.g. AgentOS board + lease checks) evaluated after runtime salvage gates. */
+export type WorktreeRemovalGuardHook = (input: WorktreeRemovalGuardInput) => {
+    reason: CleanupSkipReason;
+    detail?: string;
+} | null;
 export interface HarnessCleanupOptions {
     harnessRoot?: string;
     /** When false (default), only report candidates. */
@@ -61,6 +86,8 @@ export interface HarnessCleanupOptions {
     /** When set, only consider workers for this harness run (pipeline tick scope). */
     runIdFilter?: string;
     now?: number;
+    /** When set, invoked for each worktree candidate after built-in salvage guards. */
+    worktreeRemovalGuard?: WorktreeRemovalGuardHook;
 }
 /** Conservative default aligned with 2026-05-27 manual harness cleanup (6h). */
 export declare const DEFAULT_NODE_MODULES_AGE_MS: number;