@kynver-app/runtime 0.1.91 → 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,3 +1,4 @@
-export declare function normalizeWorkerPoolBoxKind(raw: string | null | undefined): "ghost" | "forge";
+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-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-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-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-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-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`). */