@kynver-app/runtime 0.1.62 → 0.1.69

package/README.md

@@ -41,10 +41,11 @@ Set once in `kynver setup --provider claude|cursor` (stored in `~/.kynver/config
 
 | Provider | CLI | Auth |
 | --- | --- | --- |
-| `claude` (default) | `claude` on PATH | `claude login` (OAuth). `ANTHROPIC_API_KEY` is stripped from worker env so OAuth wins. |
-| `cursor` | `agent` on PATH ([Cursor Agent CLI](https://cursor.com/docs/cli/headless)) | `agent login` (OAuth) **or** `CURSOR_API_KEY` for headless runners. |
+| `cursor` (default) | `agent` on PATH ([Cursor Agent CLI](https://cursor.com/docs/cli/headless)) | `agent login` (OAuth) **or** `CURSOR_API_KEY` for headless runners. |
+| `codex` (BYO OAuth, low-cost orchestration) | `codex` on PATH ([Codex CLI](https://developers.openai.com/codex/)) | `codex login` (OAuth) **or** `CODEX_API_KEY` for headless runners. Kynver never stores raw OAuth tokens — binding is local-only with fingerprint audit. Low-risk orchestration routes here when bound; privileged actions escalate to Cursor. |
+| `claude` (operator override) | `claude` on PATH | `claude login` (OAuth). Use `--provider claude` on dispatch/worker start, or set `executorRef: provider:claude` / `[worker-provider: claude]` on the board task. Legacy `workerProvider: "claude"` in config is normalized to Cursor at dispatch. |
 
-Override per invocation: `kynver worker start ... --provider cursor`
+Override per invocation: `kynver worker start ... --provider claude` (requires operator intent; default dispatches stay on Cursor)
 
 Install Cursor CLI (Windows PowerShell): `irm 'https://cursor.com/install?win32=true' | iex`
 

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

@@ -0,0 +1,2 @@
+export declare function resolveBoxKindFromEnv(env?: NodeJS.ProcessEnv): string;
+export declare function defaultBoxId(boxKind: string, hostLabel?: string | null): string;

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

@@ -0,0 +1,45 @@
+import type { RunnerResourceGateShape } from "./resource-gate.js";
+export interface RuntimeBoxResourceSnapshot {
+    boxId: string;
+    boxKind: string;
+    displayName?: string | null;
+    hostLabel?: string | null;
+    observedAt: string;
+    totalMemBytes: number;
+    freeMemBytes: number;
+    activeWorkers: number;
+    maxConcurrentWorkers: number;
+    autoCap: number;
+    slotsAvailable: number;
+    harnessRunId?: string | null;
+    queuedTasks?: number | null;
+    reason?: string | null;
+    prEvidence?: RuntimeBoxResourceSnapshotPrEvidence[];
+}
+export interface RuntimeBoxResourceSnapshotPrEvidence {
+    prUrl: string;
+    headSha?: string | null;
+    mergeable?: string | null;
+    observedAt: string;
+    source: "heartbeat" | "operator_tick" | "completion" | "handoff";
+}
+export declare function buildBoxResourceSnapshotFromGate(gate: RunnerResourceGateShape, input?: {
+    boxKind?: string | null;
+    boxId?: string | null;
+    displayName?: string | null;
+    hostLabel?: string | null;
+    harnessRunId?: string | null;
+    queuedTasks?: number | null;
+    prEvidence?: RuntimeBoxResourceSnapshotPrEvidence[];
+    observedAt?: string;
+}): RuntimeBoxResourceSnapshot;
+export interface HeartbeatLineInput {
+    ts?: string;
+    phase: string;
+    summary: string;
+    changedFiles?: string[];
+    blocker?: string | null;
+    boxResourceSnapshot?: RuntimeBoxResourceSnapshot;
+    prEvidence?: RuntimeBoxResourceSnapshotPrEvidence[];
+}
+export declare function formatHeartbeatLine(input: HeartbeatLineInput): string;

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

@@ -0,0 +1,14 @@
+export interface ActiveWorktreeGuardSnapshot {
+    /** Resolved worktree paths that must keep dependency caches. */
+    activeWorktreePaths: Set<string>;
+    /** `${harnessRoot}\0${runId}` keys for runs with at least one live worker. */
+    liveRunKeys: Set<string>;
+}
+/** Collect worktrees/runs that still have live worker processes (current-run guard). */
+export declare function collectActiveWorktreeGuards(harnessRoots: string[]): 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;
+export declare function runsDirForRoot(harnessRoot: string): string;
+export declare function harnessRootExists(harnessRoot: string): boolean;
+export declare function listWorktreeRunIds(worktreesDir: string): string[];

package/dist/cleanup-build-cache-paths.d.ts

@@ -0,0 +1,5 @@
+/** Generated install/build trees safe to delete under a harness worktree. */
+export declare const HARNESS_BUILD_CACHE_RELATIVE_PATHS: readonly [".next", ".turbo", "dist", "build", ".cache", "node_modules/.cache"];
+export type HarnessBuildCacheRelativePath = (typeof HARNESS_BUILD_CACHE_RELATIVE_PATHS)[number];
+/** True when a porcelain path is only generated build/install noise. */
+export declare function isGeneratedHarnessPath(pathPart: string): boolean;

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

@@ -0,0 +1,12 @@
+import type { CleanupCandidate } from "./cleanup-types.js";
+import type { IndexedWorktree } from "./cleanup-worktree-index.js";
+export interface ScanDependencyCacheOptions {
+    harnessRoot: string;
+    worktreesDir: string;
+    nodeModulesAgeMs: number;
+    runIdFilter?: string;
+    index: Map<string, IndexedWorktree>;
+    now: number;
+}
+/** Scan indexed + on-disk worktrees for generated dependency caches. */
+export declare function scanDependencyCacheCandidates(opts: ScanDependencyCacheOptions): CleanupCandidate[];

package/dist/cleanup-disk-pressure.d.ts

@@ -0,0 +1,15 @@
+import type { DispatchNextDiskGateShape } from "./callbacks.js";
+import { type ObserveDiskGateInput } from "./disk-gate.js";
+import type { ResolvedHarnessRetention } from "./cleanup-retention-config.js";
+export interface CleanupDiskPressureShape {
+    diskGate: DispatchNextDiskGateShape;
+    /** Root filesystem (or override) is at/above the guard threshold. */
+    pressured: boolean;
+    maxUsedPercent: number;
+}
+export declare function observeCleanupDiskPressure(input?: ObserveDiskGateInput): CleanupDiskPressureShape;
+/**
+ * Under disk pressure, reclaim generated dependency caches aggressively while
+ * keeping source worktrees and stricter worktree deletion rules unchanged.
+ */
+export declare function applyDiskPressureToRetention(retention: ResolvedHarnessRetention, pressure: CleanupDiskPressureShape): ResolvedHarnessRetention;

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

@@ -0,0 +1,7 @@
+import type { CleanupCandidate } from "./cleanup-types.js";
+import type { ScanHarnessOptions } from "./cleanup-scan.js";
+/**
+ * Secondary git worktrees under the harness layout that are clean but not indexed
+ * (aborted duplicate attempts). Uses `git worktree remove` during execute.
+ */
+export declare function scanDuplicateWorktreeCandidates(opts: ScanHarnessOptions): CleanupCandidate[];

package/dist/cleanup-execute.d.ts

@@ -1,4 +1,8 @@
 import type { CleanupAction, CleanupCandidate, CleanupSkipReason } from "./cleanup-types.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 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-helpers.d.ts

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

package/dist/cleanup-guards.d.ts

@@ -29,4 +29,17 @@ export interface NodeModulesGuardInput {
     nodeModulesAgeMs: number;
     ageMs: number;
 }
+export interface DependencyCacheGuardInput extends NodeModulesGuardInput {
+    worktreePath: string;
+    activeWorktreePaths: Set<string>;
+    diskPressure?: boolean;
+}
+/**
+ * Dependency caches (`node_modules`, `.next`) are safe to drop when the worker
+ * process is dead and source files remain — even if the board still shows
+ * completion/landing/PR blockers. Whole-worktree removal stays strict.
+ */
+export declare function skipDependencyCacheRemoval(input: DependencyCacheGuardInput): CleanupSkipReason | null;
+/** Build caches (`.turbo`, `dist`, etc.) use the same relaxed guards as dependency caches. */
+export declare function skipBuildCacheRemoval(input: DependencyCacheGuardInput): CleanupSkipReason | null;
 export declare function skipNodeModulesRemoval(input: NodeModulesGuardInput): CleanupSkipReason | null;

package/dist/cleanup-harness-roots.d.ts

@@ -0,0 +1,6 @@
+/** Operator-known harness trees that accumulate stale dependency caches. */
+export declare const WELL_KNOWN_HARNESS_SCAN_ROOTS: readonly ["/var/tmp/kynver-harness", string];
+export declare function resolveHarnessScanRoots(options?: {
+    harnessRoot?: string;
+    scanWellKnown?: boolean;
+}): string[];

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

@@ -1,3 +1,4 @@
+import type { DispatchNextDiskGateShape } from "./callbacks.js";
 import { type HarnessCleanupOptions } from "./cleanup-types.js";
 export interface ResolvedHarnessRetention {
     execute: boolean;
@@ -7,6 +8,8 @@ export interface ResolvedHarnessRetention {
     includeOrphans: boolean;
     runIdFilter?: string;
     accountBytes: boolean;
+    diskPressure?: boolean;
+    diskGate?: DispatchNextDiskGateShape;
 }
 /** Merge CLI options with operator env defaults (pipeline + `kynver cleanup`). */
 export declare function resolveHarnessRetention(options?: HarnessCleanupOptions): ResolvedHarnessRetention;

package/dist/cleanup-scan.d.ts

@@ -11,4 +11,5 @@ export interface ScanHarnessOptions {
     now: number;
 }
 export declare function scanNodeModulesCandidates(opts: ScanHarnessOptions): CleanupCandidate[];
+export declare function scanBuildCacheCandidates(opts: ScanHarnessOptions): CleanupCandidate[];
 export declare function scanWorktreeCandidates(opts: ScanHarnessOptions): CleanupCandidate[];

package/dist/cleanup-types.d.ts

@@ -1,4 +1,4 @@
-export type CleanupActionKind = "remove_node_modules" | "remove_worktree";
+export type CleanupActionKind = "remove_node_modules" | "remove_next_cache" | "remove_build_cache" | "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"
 /** AgentOS / operator lifecycle overlay blocked removal (see `detail`). */
  | "board_lifecycle_blocked";
@@ -6,6 +6,7 @@ export interface CleanupCandidate {
     kind: CleanupActionKind;
     path: string;
     bytes: number | null;
+    harnessRoot?: string;
     runId?: string;
     worker?: string;
     repo?: string;
@@ -33,11 +34,21 @@ export interface HarnessStorageSnapshotShape {
 }
 export interface HarnessCleanupSummary {
     harnessRoot: string;
+    /** Every harness tree scanned (primary + well-known extras). */
+    scanRoots: string[];
     dryRun: boolean;
     execute: boolean;
     nodeModulesAgeMs: number;
     worktreesAgeMs: number;
     includeOrphans: boolean;
+    diskPressure?: boolean;
+    diskGate?: {
+        ok: boolean;
+        path: string;
+        freeBytes: number;
+        usedPercent: number;
+        reason: string | null;
+    };
     scannedAt: string;
     finalizedRuns: RunFinalizeSummary[];
     actions: CleanupAction[];

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

@@ -1,6 +1,7 @@
 import { type HarnessRunRecord } from "./run-store.js";
 import { type HarnessWorkerRecord, type RawHarnessWorkerStatus } from "./status.js";
 export interface IndexedWorktree {
+    harnessRoot?: string;
     worktreePath: string;
     runId: string;
     workerName: string;
@@ -9,5 +10,6 @@ export interface IndexedWorktree {
     status: RawHarnessWorkerStatus;
 }
 export declare function buildWorktreeIndex(): Map<string, IndexedWorktree>;
+export declare function buildWorktreeIndexAt(harnessRoot: string): Map<string, IndexedWorktree>;
 /** Load worker when index miss but path is known from disk layout. */
 export declare function loadIndexedWorker(runId: string, workerName: string): HarnessWorkerRecord | null;