@kynver-app/runtime 0.1.39 → 0.1.47

package/README.md

@@ -50,6 +50,21 @@ Install Cursor CLI (Windows PowerShell): `irm 'https://cursor.com/install?win32=
 
 Default Cursor model: `composer-2.5`. Override with `--model` on dispatch/worker start.
 
+### Targeted dispatch (after creating a board task)
+
+Broad `lane:any` dispatch still sweeps the ready queue (review lane first, then priority/age). To start **one specific task** you just created — without admitting an older ready row — pass the task id:
+
+```bash
+kynver run dispatch --run <runId> --agent-os-id <id> --execute \
+  --target-task-id <taskId> --max-starts 1
+```
+
+The server `dispatch-next` body field is `targetTaskId` (same semantics). When set, no candidate pages are scanned; the response includes `targetTaskMiss: true` if the row is missing or belongs to another workspace.
+
+### PR-ready handoff
+
+`ensurePrReadyHandoff` resolves `owner/repo` from `git remote get-url origin` via URL parsing (repo names with dots, e.g. `Totalsolutionsync/Kynver`, are no longer truncated).
+
 ## Tests
 
 ```bash

package/dist/auto-complete.d.ts

@@ -0,0 +1,60 @@
+export interface AutoCompleteArgs {
+    run: string;
+    name: string;
+    agentOsId?: string;
+    pollMs?: number;
+    maxTotalMs?: number;
+    completeAttempts?: number;
+    completeBackoffMs?: number;
+    baseUrl?: string;
+    secret?: string;
+}
+export interface AutoCompleteOutcome {
+    worker: string;
+    runId: string;
+    /** "completed" → finished + completion call returned ok. "blocked" → finished + completion replay refused (structural blocker set). "timed_out" → never finished within the cap. */
+    outcome: "completed" | "blocked" | "timed_out" | "missing_link";
+    httpStatus?: number;
+    attempts: number;
+    reason?: string;
+}
+/**
+ * Sidecar body: poll the worker until it finishes, then POST completion (with a
+ * small retry budget). Pure logic — the CLI just adapts `--`-args in/out.
+ */
+export declare function autoCompleteWorker(raw: Record<string, string | boolean>): Promise<AutoCompleteOutcome>;
+/** CLI entry: write outcome JSON to stdout. Exit code 0 on completed/blocked (both record state); 1 on missing_link / timed_out. */
+export declare function autoCompleteWorkerCli(raw: Record<string, string | boolean>): Promise<void>;
+export interface SpawnSidecarOptions {
+    runId: string;
+    workerName: string;
+    workerDir: string;
+    /** Override the CLI script the sidecar invokes. Tests inject this. */
+    cliPath?: string;
+    /** Override the node executable. Tests inject this. */
+    nodeExecutable?: string;
+    /**
+     * Carry the agentOsId on the command line so the sidecar still resolves
+     * its callback target even if `worker.json` is rewritten/relocated.
+     */
+    agentOsId?: string;
+    /**
+     * Pass-through for callers that want a non-default base URL/secret (e.g.
+     * tests or operator overrides). Production reads them from env.
+     */
+    baseUrl?: string;
+    secret?: string;
+}
+export interface SpawnedSidecar {
+    pid?: number;
+    logPath: string;
+    cliPath: string;
+}
+/**
+ * Detach a per-worker completion sidecar that owns the worker's
+ * finalResult → AgentTask attribution. Returns the spawned pid (or undefined if
+ * `dryRun`). Failures here MUST NOT crash `worker start`: the worker is already
+ * running; missing the sidecar just means a daemon/watchdog has to replay
+ * completion later.
+ */
+export declare function spawnCompletionSidecar(opts: SpawnSidecarOptions): SpawnedSidecar | undefined;

package/dist/bounded-build/admission.d.ts

@@ -0,0 +1,30 @@
+export interface BuildAdmissionConfig {
+    perBuildBudgetBytes: number;
+    reserveBytes: number;
+}
+export interface BuildAdmissionVerdict {
+    admitted: boolean;
+    memAvailableBytes: number;
+    requiredBytes: number;
+    activeBuilds: number;
+    reason: string | null;
+}
+export declare function resolveBuildAdmissionConfig(config?: import("../config.js").KynverUserConfig): BuildAdmissionConfig;
+export declare function getActiveBuildCount(): number;
+/** Reset active build counter (tests). */
+export declare function resetActiveBuildCountForTests(): void;
+export declare function registerBuildStart(): void;
+export declare function registerBuildEnd(): void;
+/**
+ * RAM-aware admission: start another worktree build only when MemAvailable ≥
+ * per-build budget + reserve. Does not serialize — parallel builds proceed when
+ * the host has headroom.
+ */
+export declare function assessBuildAdmission(opts?: Partial<BuildAdmissionConfig> & {
+    memAvailableBytes?: number;
+}): BuildAdmissionVerdict;
+export declare function sleepMs(ms: number): void;
+/** Poll admission until admitted or timeout (ms). Returns last verdict. */
+export declare function waitForBuildAdmission(timeoutMs: number, pollMs?: number, opts?: Partial<BuildAdmissionConfig> & {
+    memAvailableBytes?: () => number;
+}): BuildAdmissionVerdict;

package/dist/bounded-build/constants.d.ts

@@ -0,0 +1,10 @@
+/** Per-build RAM budget for admission (aligns with Hermes autopipeline worker sizing). */
+export declare const DEFAULT_BUILD_MEM_BUDGET_BYTES: number;
+/** Headroom reserved for OS / gateway before admitting another build. */
+export declare const DEFAULT_BUILD_MEM_RESERVE_BYTES: number;
+/** Node heap cap for npm/tsc build/check subprocesses unless overridden. */
+export declare const DEFAULT_NODE_OLD_SPACE_SIZE_MB = 1024;
+/** systemd scope MemoryMax for build/check subprocesses. */
+export declare const DEFAULT_SYSTEMD_MEMORY_MAX = "1.5G";
+/** systemd scope MemorySwapMax for build/check subprocesses. */
+export declare const DEFAULT_SYSTEMD_MEMORY_SWAP_MAX = "2G";

package/dist/bounded-build/exec.d.ts

@@ -0,0 +1,26 @@
+import { type BuildAdmissionVerdict } from "./admission.js";
+export interface BoundedBuildExecResult {
+    ok: boolean;
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    admitted: boolean;
+    wrappedWithSystemd: boolean;
+    nodeOptionsFlag: string;
+    admission: BuildAdmissionVerdict;
+    command: string;
+}
+export interface RunBoundedBuildCheckInput {
+    cwd: string;
+    /** Shell command line (e.g. `npm run typecheck`). */
+    command: string;
+    env?: NodeJS.ProcessEnv;
+    /** Max ms to wait for RAM admission (0 = fail fast). Default 600_000. */
+    waitForAdmissionMs?: number;
+    timeoutMs?: number;
+}
+/**
+ * Run an expensive build/check command with NODE_OPTIONS heap cap, optional
+ * systemd-run memory scope, and RAM-aware admission (parallel-safe).
+ */
+export declare function runBoundedBuildCheck(input: RunBoundedBuildCheckInput): BoundedBuildExecResult;

package/dist/bounded-build/index.d.ts

@@ -0,0 +1,6 @@
+export { DEFAULT_BUILD_MEM_BUDGET_BYTES, DEFAULT_BUILD_MEM_RESERVE_BYTES, DEFAULT_NODE_OLD_SPACE_SIZE_MB, DEFAULT_SYSTEMD_MEMORY_MAX, DEFAULT_SYSTEMD_MEMORY_SWAP_MAX, } from "./constants.js";
+export { readMemAvailableBytes } from "./meminfo.js";
+export { formatNodeOptionsFlag, mergeNodeOptionsForBuildCheck, resolveNodeOldSpaceSizeMb, } from "./node-options.js";
+export { buildSystemdRunArgv, isSystemdRunAvailable, type SystemdWrapOptions, } from "./systemd-wrap.js";
+export { assessBuildAdmission, getActiveBuildCount, registerBuildEnd, registerBuildStart, resetActiveBuildCountForTests, resolveBuildAdmissionConfig, waitForBuildAdmission, type BuildAdmissionConfig, type BuildAdmissionVerdict, } from "./admission.js";
+export { runBoundedBuildCheck, type BoundedBuildExecResult, type RunBoundedBuildCheckInput } from "./exec.js";

package/dist/bounded-build/meminfo.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Truly-usable memory. On Linux, prefer /proc/meminfo MemAvailable; fall back to
+ * os.freemem() elsewhere (same semantics as resource-gate).
+ */
+export declare function readMemAvailableBytes(meminfoText?: string): number;

package/dist/bounded-build/node-options.d.ts

@@ -0,0 +1,9 @@
+/** Resolved Node old-space cap in MiB (env override, else default 1024). */
+export declare function resolveNodeOldSpaceSizeMb(): number;
+/**
+ * Merge NODE_OPTIONS for build/check subprocesses: set --max-old-space-size unless
+ * the caller already set one in NODE_OPTIONS or KYNVER_NODE_OLD_SPACE_SIZE_MB=0
+ * disables injection.
+ */
+export declare function mergeNodeOptionsForBuildCheck(baseEnv?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function formatNodeOptionsFlag(mb?: number): string;

package/dist/bounded-build/systemd-wrap.d.ts

@@ -0,0 +1,17 @@
+export interface SystemdWrapOptions {
+    memoryMax?: string;
+    memorySwapMax?: string;
+    cwd?: string;
+    /** argv after `--` (no shell). */
+    command: string[];
+    env?: NodeJS.ProcessEnv;
+}
+/** Clear cached systemd probe (tests). */
+export declare function resetSystemdAvailabilityCacheForTests(): void;
+/** True when `systemd-run --version` succeeds (Linux hosts with systemd). */
+export declare function isSystemdRunAvailable(): boolean;
+/**
+ * Build argv for `systemd-run --scope` with memory properties, then `-- command…`.
+ * Does not execute the command.
+ */
+export declare function buildSystemdRunArgv(opts: SystemdWrapOptions): string[];

package/dist/callback-headers.d.ts

@@ -0,0 +1,2 @@
+/** Build callback auth headers for AgentOS by-id harness routes. */
+export declare function buildHarnessCallbackHeaders(secret: string): Record<string, string>;

package/dist/callbacks.d.ts

@@ -0,0 +1,38 @@
+export interface DispatchNextDiskGateShape {
+    ok: boolean;
+    path: string;
+    freeBytes: number;
+    totalBytes: number;
+    usedPercent: number;
+    warnBelowBytes: number;
+    criticalBelowBytes: number;
+    maxUsedPercent: number;
+    hardMaxUsedPercent: number;
+    reason: string | null;
+}
+export interface DispatchNextResourceGateShape {
+    ok: boolean;
+    totalMemBytes: number;
+    freeMemBytes: number;
+    memReserveBytes: number;
+    perWorkerMemBytes: number;
+    configuredMaxWorkers: number | null;
+    capacityWorkers: number;
+    maxConcurrentWorkers: number;
+    activeWorkers: number;
+    slotsAvailable: number;
+    reason: string | null;
+}
+export interface PostJsonResult {
+    ok: boolean;
+    status: number;
+    response: unknown;
+    refreshedAuth?: boolean;
+    authRefreshFailure?: string;
+}
+export declare function postJson(url: string, secret: string, body: unknown): Promise<PostJsonResult>;
+export declare function postJsonWithCredentialRefresh(url: string, secret: string, body: unknown, opts: {
+    agentOsId: string;
+    baseUrl?: string;
+}): Promise<PostJsonResult>;
+export declare function getJson(url: string, secret: string): Promise<PostJsonResult>;

package/dist/cleanup-cli.d.ts

@@ -0,0 +1 @@
+export declare function runCleanupCli(args: Record<string, string | boolean>): void;

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

@@ -0,0 +1,4 @@
+/**
+ * Best-effort directory size. Returns null when entry cap is exceeded (huge trees).
+ */
+export declare function directorySizeBytes(root: string, maxEntries?: number): number | null;

package/dist/cleanup-execute.d.ts

@@ -0,0 +1,4 @@
+import type { CleanupAction, CleanupCandidate, CleanupSkipReason } from "./cleanup-types.js";
+export declare function removeNodeModules(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;

package/dist/cleanup-guards.d.ts

@@ -0,0 +1,18 @@
+import type { CleanupSkipReason } from "./cleanup-types.js";
+import type { IndexedWorktree } from "./cleanup-worktree-index.js";
+import type { RawHarnessWorkerStatus } from "./status.js";
+export declare function isPrOrUnmergedWork(status: RawHarnessWorkerStatus): boolean;
+export interface WorktreeGuardInput {
+    indexed: IndexedWorktree | null;
+    includeOrphans: boolean;
+    worktreesAgeMs: number;
+    ageMs: number;
+}
+export declare function skipWorktreeRemoval(input: WorktreeGuardInput): CleanupSkipReason | null;
+export interface NodeModulesGuardInput {
+    indexed: IndexedWorktree | null;
+    includeOrphans: boolean;
+    nodeModulesAgeMs: number;
+    ageMs: number;
+}
+export declare function skipNodeModulesRemoval(input: NodeModulesGuardInput): CleanupSkipReason | null;

package/dist/cleanup-scan.d.ts

@@ -0,0 +1,14 @@
+import type { CleanupCandidate } from "./cleanup-types.js";
+import { type IndexedWorktree } from "./cleanup-worktree-index.js";
+export interface ScanHarnessOptions {
+    harnessRoot: string;
+    worktreesDir: string;
+    nodeModulesAgeMs: number;
+    worktreesAgeMs: number;
+    includeOrphans: boolean;
+    runIdFilter?: string;
+    index: Map<string, IndexedWorktree>;
+    now: number;
+}
+export declare function scanNodeModulesCandidates(opts: ScanHarnessOptions): CleanupCandidate[];
+export declare function scanWorktreeCandidates(opts: ScanHarnessOptions): CleanupCandidate[];

package/dist/cleanup-types.d.ts

@@ -0,0 +1,56 @@
+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 interface CleanupCandidate {
+    kind: CleanupActionKind;
+    path: string;
+    bytes: number | null;
+    runId?: string;
+    worker?: string;
+    repo?: string;
+    ageMs: number;
+}
+export interface CleanupAction extends CleanupCandidate {
+    executed: boolean;
+    skipped: boolean;
+    skipReason?: CleanupSkipReason;
+    error?: string;
+}
+export interface HarnessCleanupSummary {
+    harnessRoot: string;
+    dryRun: boolean;
+    execute: boolean;
+    nodeModulesAgeMs: number;
+    worktreesAgeMs: number;
+    includeOrphans: boolean;
+    scannedAt: string;
+    actions: CleanupAction[];
+    skips: Array<{
+        path: string;
+        reason: CleanupSkipReason;
+        detail?: string;
+    }>;
+    totals: {
+        candidateBytes: number;
+        removedBytes: number;
+        removedPaths: number;
+        skippedPaths: number;
+    };
+}
+export interface HarnessCleanupOptions {
+    harnessRoot?: string;
+    /** When false (default), only report candidates. */
+    execute?: boolean;
+    /** Minimum age before removing generated `node_modules` (default 6h). */
+    nodeModulesAgeMs?: number;
+    /** When 0 or unset, worktree removal is disabled. */
+    worktreesAgeMs?: number;
+    /** Allow cleaning `node_modules` under worktrees with no worker index entry. */
+    includeOrphans?: boolean;
+    /** When set, only consider workers for this harness run (pipeline tick scope). */
+    runIdFilter?: string;
+    now?: number;
+}
+/** Conservative default aligned with 2026-05-27 manual harness cleanup (6h). */
+export declare const DEFAULT_NODE_MODULES_AGE_MS: number;
+/** Seven days — only used when worktree cleanup is explicitly enabled. */
+export declare const DEFAULT_WORKTREES_AGE_MS: number;

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

@@ -0,0 +1,13 @@
+import { type HarnessRunRecord } from "./run-store.js";
+import { type HarnessWorkerRecord, type RawHarnessWorkerStatus } from "./status.js";
+export interface IndexedWorktree {
+    worktreePath: string;
+    runId: string;
+    workerName: string;
+    run: HarnessRunRecord;
+    worker: HarnessWorkerRecord;
+    status: RawHarnessWorkerStatus;
+}
+export declare function buildWorktreeIndex(): 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;

package/dist/cleanup.d.ts

@@ -0,0 +1,5 @@
+import { type HarnessCleanupOptions, type HarnessCleanupSummary } from "./cleanup-types.js";
+export declare function runHarnessCleanup(options?: HarnessCleanupOptions): HarnessCleanupSummary;
+/** Pipeline-safe defaults: node_modules only, dry-run unless execute env is set. */
+export declare function runPipelineHarnessCleanup(runId?: string): HarnessCleanupSummary;
+export declare function isPipelineCleanupEnabled(): boolean;

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export declare function usage(code?: number): never;
+export declare function main(argv?: string[]): Promise<void>;