@kynver-app/runtime 0.1.90 → 0.1.92

package/dist/box-identity.d.ts

@@ -0,0 +1,19 @@
+import type { KynverUserConfig } from "./config.js";
+export type WorkerPoolBoxKind = "ghost" | "forge";
+export type BoxKindSource = "config" | "env" | "default";
+export interface ResolvedBoxIdentity {
+    boxKind: WorkerPoolBoxKind;
+    source: BoxKindSource;
+    /** True when identity would have been inferred from KYNVER_AGENT_OS_SLUG without an explicit box kind. */
+    slugInferenceBlocked: boolean;
+    warnings: string[];
+}
+/** Normalize host/box labels to ghost | forge for worker-pool attribution. */
+export declare function normalizeWorkerPoolBoxKind(raw: string | null | undefined): WorkerPoolBoxKind;
+/**
+ * Resolve physical box identity for capacity snapshots and daemon policy.
+ * Never maps AgentOS workspace slug alone to box kind — Forge installs must set
+ * `boxKind` in ~/.kynver/config.json or `KYNVER_BOX_KIND`.
+ */
+export declare function resolveBoxIdentity(env?: NodeJS.ProcessEnv, config?: Pick<KynverUserConfig, "boxKind">): ResolvedBoxIdentity;
+export declare function resolveBoxKindFromConfig(config?: Pick<KynverUserConfig, "boxKind">, env?: NodeJS.ProcessEnv): WorkerPoolBoxKind;

package/dist/box-resource-snapshot-shared.d.ts

@@ -1,2 +1,4 @@
+export { normalizeWorkerPoolBoxKind, resolveBoxIdentity } from "./box-identity.js";
+/** @deprecated Prefer resolveBoxIdentity — kept for callers that only need the kind string. */
 export declare function resolveBoxKindFromEnv(env?: NodeJS.ProcessEnv): string;
 export declare function defaultBoxId(boxKind: string, hostLabel?: string | null): string;

package/dist/cleanup-active-worktrees.d.ts

@@ -5,7 +5,7 @@ export interface ActiveWorktreeGuardSnapshot {
     liveRunKeys: Set<string>;
 }
 /** Collect worktrees/runs that still have live worker processes (current-run guard). */
-export declare function collectActiveWorktreeGuards(harnessRoots: string[]): ActiveWorktreeGuardSnapshot;
+export declare function collectActiveWorktreeGuards(harnessRoots: string[], now?: number): ActiveWorktreeGuardSnapshot;
 /** True when a worktree path still exists under a live run (belt-and-suspenders). */
 export declare function isWorktreeOnLiveRun(worktreePath: string, harnessRoot: string, runId: string | undefined, liveRunKeys: Set<string>): boolean;
 export declare function worktreesDirForRoot(harnessRoot: string): string;

package/dist/cleanup-dependency-scan.d.ts

@@ -4,6 +4,7 @@ export interface ScanDependencyCacheOptions {
     harnessRoot: string;
     worktreesDir: string;
     nodeModulesAgeMs: number;
+    includeOrphans?: boolean;
     runIdFilter?: string;
     index: Map<string, IndexedWorktree>;
     now: number;

package/dist/cleanup-dir-size.d.ts

@@ -1,4 +1,5 @@
 /**
- * Best-effort directory size. Returns null when entry cap is exceeded (huge trees).
+ * Best-effort directory size. Prefers `du -sb` (fast on large `node_modules`);
+ * falls back to a capped walk. Returns null when entry cap is exceeded.
  */
 export declare function directorySizeBytes(root: string, maxEntries?: number): number | null;

package/dist/cleanup-execute.d.ts

@@ -1,9 +1,7 @@
-import type { CleanupAction, CleanupCandidate, CleanupSkipReason } from "./cleanup-types.js";
+import type { CleanupAction, CleanupCandidate } from "./cleanup-types.js";
+export { isHarnessBuildCachePath, isHarnessNextCachePath, isHarnessNodeModulesPath } from "./cleanup-harness-path-validate.js";
 export declare function removeNodeModules(candidate: CleanupCandidate, execute: boolean): CleanupAction;
 export declare function removeNextCache(candidate: CleanupCandidate, execute: boolean): CleanupAction;
 export declare function removeBuildCache(candidate: CleanupCandidate, execute: boolean): CleanupAction;
 export declare function removeRunDirectory(candidate: CleanupCandidate, execute: boolean): CleanupAction;
 export declare function removeWorktree(candidate: CleanupCandidate, execute: boolean): CleanupAction;
-export declare function isHarnessNodeModulesPath(targetPath: string, harnessRoot: string, worktreesDir: string): CleanupSkipReason | null;
-export declare function isHarnessNextCachePath(targetPath: string, harnessRoot: string, worktreesDir: string): CleanupSkipReason | null;
-export declare function isHarnessBuildCachePath(targetPath: string, harnessRoot: string, worktreesDir: string): CleanupSkipReason | null;

package/dist/cleanup-guards.d.ts

@@ -1,7 +1,11 @@
 import type { CleanupSkipReason, WorktreeRemovalGuardHook } from "./cleanup-types.js";
 import type { IndexedWorktree } from "./cleanup-worktree-index.js";
+import type { CleanupRunLivenessContext } from "./cleanup-run-liveness.js";
+import type { GitAncestry } from "./git.js";
 import type { RawHarnessWorkerStatus } from "./status.js";
 export { materialWorktreeChanges } from "./cleanup-guards-helpers.js";
+/** True when git ancestry shows the worker branch is fully landed on the run base. */
+export declare function isLandedGitAncestry(ancestry: GitAncestry | null | undefined): boolean;
 /** Blocks whole-worktree removal when commits are not landed or tree is dirty. */
 export declare function isPrOrUnmergedWork(status: RawHarnessWorkerStatus): boolean;
 export interface WorktreeGuardInput {
@@ -19,6 +23,7 @@ export interface WorktreeGuardInput {
      */
     orphanSafety?: CleanupSkipReason | null;
     worktreeRemovalGuard?: WorktreeRemovalGuardHook;
+    liveness?: CleanupRunLivenessContext;
 }
 export type WorktreeGuardSkip = CleanupSkipReason | {
     reason: CleanupSkipReason;

package/dist/cleanup-harness-path-validate.d.ts

@@ -0,0 +1,5 @@
+import type { CleanupSkipReason } from "./cleanup-types.js";
+export declare function isHarnessNodeModulesPath(targetPath: string, harnessRoot: string, worktreesDir: string): CleanupSkipReason | null;
+export declare function isHarnessNextCachePath(targetPath: string, harnessRoot: string, worktreesDir: string): CleanupSkipReason | null;
+export declare function isHarnessBuildCachePath(targetPath: string, harnessRoot: string, worktreesDir: string): CleanupSkipReason | null;
+export declare function isHarnessGeneratedCachePath(targetPath: string, harnessRoot: string, worktreesDir: string): boolean;

package/dist/cleanup-index-status.d.ts

@@ -0,0 +1,9 @@
+import { type RawHarnessWorkerStatus } from "./status.js";
+import type { IndexedWorktree } from "./cleanup-worktree-index.js";
+/** Lazily compute worker status — avoids git/stream work for every indexed worker up front. */
+export declare function indexedWorktreeStatus(entry: IndexedWorktree): RawHarnessWorkerStatus;
+/**
+ * Porcelain-only dirty probe for dependency-cache guards. Skips ancestry/stream
+ * work that whole-worktree removal needs but `node_modules` GC does not.
+ */
+export declare function indexedWorktreeHasMaterialChanges(entry: IndexedWorktree): boolean;

package/dist/cleanup-path-ownership.d.ts

@@ -0,0 +1,9 @@
+export interface PathOwnershipInfo {
+    uid: number;
+    gid: number;
+    /** True when the entry is not owned by the current process user/group. */
+    foreign: boolean;
+}
+export declare function readPathOwnership(targetPath: string): PathOwnershipInfo | null;
+/** Shallow scan for foreign-owned entries (dependency caches are usually uniform). */
+export declare function pathHasForeignOwnedEntry(targetPath: string, maxEntries?: number): boolean;

package/dist/cleanup-privileged-remove.d.ts

@@ -0,0 +1,13 @@
+export type PrivilegedCleanupMode = "off" | "auto" | "force";
+export declare function resolvePrivilegedCleanupMode(): PrivilegedCleanupMode;
+export interface PrivilegedReclaimResult {
+    ok: boolean;
+    method?: "chown_then_rm" | "sudo_rm";
+    error?: string;
+}
+/**
+ * Reclaim a harness generated cache directory that is not owned by the daemon user.
+ * Only operates on validated `worktrees/<run>/<worker>/{node_modules,.next,...}` paths.
+ */
+export declare function tryPrivilegedReclaimHarnessCache(targetPath: string, harnessRoot: string, worktreesDir: string): PrivilegedReclaimResult;
+export declare const HARNESS_ROOT_OWNED_CACHE_RUNBOOK = "Root-owned harness caches require operator reclaim: configure passwordless sudo for chown/rm under ~/.kynver/harness/worktrees, or run `node scripts/reclaim-harness-root-owned-cache.mjs --execute` as the harness owner with sudo available. See docs/runbooks/harness-root-owned-cache-reclaim.md.";

package/dist/cleanup-progress.d.ts

@@ -0,0 +1,2 @@
+/** stderr progress lines so broad cleanup scans do not appear hung before JSON output. */
+export declare function emitCleanupProgress(phase: string, detail?: string): void;

package/dist/cleanup-remove-path.d.ts

@@ -0,0 +1,17 @@
+import { rmSync } from "node:fs";
+import type { CleanupCandidate, CleanupSkipReason } from "./cleanup-types.js";
+import { pathHasForeignOwnedEntry } from "./cleanup-path-ownership.js";
+export interface RemoveHarnessPathOutcome {
+    executed: boolean;
+    skipped: boolean;
+    skipReason?: CleanupSkipReason;
+    error?: string;
+    bytes?: number;
+    privilegedReclaim?: boolean;
+}
+interface RemoveHarnessGeneratedPathDeps {
+    removePath?: typeof rmSync;
+    hasForeignOwnedEntry?: typeof pathHasForeignOwnedEntry;
+}
+export declare function removeHarnessGeneratedPath(candidate: CleanupCandidate, execute: boolean, deps?: RemoveHarnessGeneratedPathDeps): RemoveHarnessPathOutcome;
+export {};

package/dist/cleanup-retention-config.d.ts

@@ -11,6 +11,10 @@ export interface ResolvedHarnessRetention {
     includeOrphans: boolean;
     runIdFilter?: string;
     accountBytes: boolean;
+    /** Cap filesystem walk depth per run dir in `harnessStorageSnapshot` (0 = counts only). */
+    storagePerRunEntryCap: number | null;
+    /** Per-candidate walk cap when `du` is unavailable (default 2k). */
+    byteAccountingEntryCap: number;
     diskPressure?: boolean;
     diskGate?: DispatchNextDiskGateShape;
 }

package/dist/cleanup-run-liveness.d.ts

@@ -1,13 +1,17 @@
 import type { IndexedWorktree } from "./cleanup-worktree-index.js";
+import type { CleanupRunTerminalCache } from "./cleanup-run-terminal-cache.js";
+export interface CleanupRunLivenessContext {
+    runTerminalCache: CleanupRunTerminalCache;
+}
 /** True when the worker process is still live or marked running in worker.json. */
 export declare function isWorkerProcessLive(indexed: IndexedWorktree): boolean;
 /**
  * Run record still marked active but every worker is finished — safe to treat as
  * terminal for GC after `finalizeStaleRuns()` (or when deriveTerminalRunStatus is set).
  */
-export declare function isRunStaleActive(indexed: IndexedWorktree): boolean;
+export declare function isRunStaleActive(indexed: IndexedWorktree, ctx?: CleanupRunLivenessContext): boolean;
 /**
  * Whether the harness run still has unfinished work that should block whole-worktree removal.
  * Does not block per-worker `node_modules` when only this worker is finished.
  */
-export declare function runBlocksWorktreeRemoval(indexed: IndexedWorktree): boolean;
+export declare function runBlocksWorktreeRemoval(indexed: IndexedWorktree, ctx?: CleanupRunLivenessContext): boolean;

package/dist/cleanup-run-terminal-cache.d.ts

@@ -0,0 +1,6 @@
+import type { HarnessRunRecord } from "./run-store.js";
+/** Per-sweep memo so worktree guards do not re-derive terminal status for every worker in a run. */
+export declare class CleanupRunTerminalCache {
+    private readonly cache;
+    derive(run: HarnessRunRecord): string | null;
+}

package/dist/cleanup-summary.d.ts

@@ -0,0 +1,29 @@
+import type { CleanupActionKind, HarnessCleanupSummary, HarnessStorageSnapshotShape } from "./cleanup-types.js";
+export interface CleanupCompactSummary {
+    harnessRoot: string;
+    scanRoots: string[];
+    dryRun: boolean;
+    execute: boolean;
+    scannedAt: string;
+    finalizedRuns: number;
+    actionCount: number;
+    actionKinds: Partial<Record<CleanupActionKind, number>>;
+    totals: HarnessCleanupSummary["totals"];
+    storage?: HarnessStorageSnapshotShape;
+    preservedLivePaths?: HarnessCleanupSummary["preservedLivePaths"];
+    removedRunDirectories?: number;
+    sampleActions: Array<{
+        kind: CleanupActionKind;
+        path: string;
+        skipReason?: string;
+        bytes?: number | null;
+        runId?: string;
+        worker?: string;
+    }>;
+    sampleSkips: HarnessCleanupSummary["skips"];
+}
+/** Operator-facing rollup — bounded samples, no per-path megabyte JSON dumps. */
+export declare function buildCleanupCompactSummary(summary: HarnessCleanupSummary, options?: {
+    maxSampleActions?: number;
+    maxSampleSkips?: number;
+}): CleanupCompactSummary;

package/dist/cleanup-types.d.ts

@@ -1,5 +1,7 @@
 export type CleanupActionKind = "remove_node_modules" | "remove_next_cache" | "remove_build_cache" | "remove_worktree" | "remove_run_directory";
 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"
+/** Generated cache owned by another user (often root); daemon cannot unlink without privileged reclaim. */
+ | "foreign_owner"
 /** Harness `runs/` metadata must never be removed by worktree GC. */
  | "run_metadata_protected"
 /** AgentOS / operator lifecycle overlay blocked removal (see `detail`). */
@@ -77,6 +79,8 @@ export interface HarnessCleanupSummary {
     }>;
     /** Empty harness worktree run directories removed after worker worktrees were reclaimed. */
     removedRunDirectories?: number;
+    /** Bounded operator rollup (always attached; use `kynver cleanup --compact` to emit alone). */
+    compactSummary?: import("./cleanup-summary.js").CleanupCompactSummary;
 }
 export interface WorktreeRemovalGuardInput {
     worktreePath: string;
@@ -96,8 +100,12 @@ export interface HarnessCleanupOptions {
     execute?: boolean;
     /** When true (default), call `finalizeStaleRuns()` before scanning. */
     finalizeStaleRuns?: boolean;
-    /** When true (default), estimate candidate bytes in dry-run summaries. */
+    /** When true, estimate candidate bytes for guard-passing removals only. CLI defaults false. */
     accountBytes?: boolean;
+    /** Per-run entry cap for storage snapshot byte totals (`0` = counts only). */
+    storagePerRunEntryCap?: number | null;
+    /** Per-candidate filesystem walk cap when `du` is unavailable. */
+    byteAccountingEntryCap?: number;
     /** Minimum age before removing generated `node_modules` (default 6h). */
     nodeModulesAgeMs?: number;
     /** When 0 or unset, worktree removal is disabled. */

package/dist/cleanup-worktree-index.d.ts

@@ -1,5 +1,5 @@
 import { type HarnessRunRecord } from "./run-store.js";
-import { type HarnessWorkerRecord, type RawHarnessWorkerStatus } from "./status.js";
+import type { HarnessWorkerRecord, RawHarnessWorkerStatus } from "./status.js";
 export interface IndexedWorktree {
     harnessRoot?: string;
     worktreePath: string;
@@ -7,7 +7,8 @@ export interface IndexedWorktree {
     workerName: string;
     run: HarnessRunRecord;
     worker: HarnessWorkerRecord;
-    status: RawHarnessWorkerStatus;
+    /** Populated lazily via `indexedWorktreeStatus()` during guard evaluation. */
+    status?: RawHarnessWorkerStatus;
 }
 export declare function buildWorktreeIndex(): Map<string, IndexedWorktree>;
 export declare function buildWorktreeIndexAt(harnessRoot: string): Map<string, IndexedWorktree>;