@kynver-app/runtime 0.1.172 → 0.2.1

package/dist/landing/land-pr-check-classify.d.ts

@@ -0,0 +1,11 @@
+export declare function checkName(check: Record<string, unknown>): string;
+/** Collapse rollup to the latest run per check name so stale failures do not block landing. */
+export declare function collapseCheckRollupByName(statusCheckRollup: unknown[] | undefined): Record<string, unknown>[];
+export declare function isGitHubActionsCheck(check: Record<string, unknown>): boolean;
+export declare function classifyChecks(statusCheckRollup: unknown[] | undefined): {
+    pending: string[];
+    failed: string[];
+    ignoredActions: string[];
+};
+export declare function vercelCheckSuccess(statusCheckRollup: unknown[] | undefined): boolean;
+export declare function mergeStateReadinessError(mergeStateStatus: string, checks: ReturnType<typeof classifyChecks>): string | null;

package/dist/model-routing.d.ts

@@ -31,7 +31,7 @@ export declare function resolveClaudeFactoryModel(roleLane: string, ref: string,
  * pass an explicit `--model`. Explicit CLI/model args always win.
  */
 export declare function inferModelRoutingFromTask(task: Record<string, unknown>): ModelRoutingDecision;
-/** Resolve launch parameters: explicit CLI wins, then task inference, then global default. */
+/** Resolve launch parameters: explicit CLI wins, then executorRef intent, then task inference. */
 export declare function resolveWorkerLaunch(input: {
     explicitModel?: string;
     explicitProvider?: string;

package/dist/node-runtime-policy.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Node 24 migration N2b — the ONE shared semantic-version policy contract.
+ *
+ * The comparator takes the engine range as a parameter: one comparison
+ * engine, two contracts. Published CLI/MCP artifacts use the unbounded
+ * range; the private root app is bounded per-major. Do NOT duplicate this
+ * comparison logic anywhere (N2d wraps it; the server diagnostic imports
+ * it). During N2b the policy is report-only: callers may classify, but
+ * nothing gates startup on the verdict.
+ */
+export declare const KYNVER_NODE_PATCH_FLOOR = "24.11.0";
+/** Engine contract for published runtime-coupled packages (unbounded). */
+export declare const PUBLISHED_NODE_RANGE = ">=24.11.0";
+/** Engine contract for the private root app (bounded per qualified major). */
+export declare const PRIVATE_ROOT_NODE_RANGE = ">=24.11.0 <25";
+export type NodeRuntimePolicyStatus = "compatible" | "upgrade_required" | "unsupported_major" | "invalid_version";
+export interface NodeRuntimePolicyVerdict {
+    status: NodeRuntimePolicyStatus;
+    /** Normalized (no leading `v`) version that was evaluated, or the raw input when invalid. */
+    currentVersion: string;
+    requiredRange: string;
+    /** Bounded operator guidance; never environment values or paths. */
+    remediation: string | null;
+}
+export declare function evaluateNodeRuntimePolicy(rawVersion: string, requiredRange?: string): NodeRuntimePolicyVerdict;

package/dist/node-runtime-policy.js

@@ -0,0 +1 @@
+var a="24.11.0",l=">=24.11.0",d=">=24.11.0 <25";function s(r){let e=r.trim().replace(/^v/,""),o=/^(\d+)\.(\d+)\.(\d+)$/.exec(e);return o?{major:Number(o[1]),minor:Number(o[2]),patch:Number(o[3])}:null}function u(r,e){return r.major!==e.major?r.major-e.major:r.minor!==e.minor?r.minor-e.minor:r.patch-e.patch}function c(r){let e=r.trim().split(/\s+/),o=null,i=null;for(let t of e)if(t.startsWith(">="))o=s(t.slice(2));else if(t.startsWith("<")){let n=t.slice(1);i=s(n)??(/^\d+$/.test(n)?{major:Number(n),minor:0,patch:0}:null)}if(!o)throw new Error(`Unsupported node policy range: ${r}`);return{floor:o,below:i}}function m(r,e=l){let{floor:o,below:i}=c(e),t=s(r);if(!t)return{status:"invalid_version",currentVersion:r.trim(),requiredRange:e,remediation:`Node version could not be parsed as X.Y.Z (prereleases are unsupported). Install Node ${a} or a later release within the supported range.`};let n=`${t.major}.${t.minor}.${t.patch}`;return u(t,o)<0?{status:"upgrade_required",currentVersion:n,requiredRange:e,remediation:`Upgrade Node to >=${a}. See docs/runbooks/node-24-fleet-migration.md for the per-host procedure.`}:i&&u(t,i)>=0?{status:"unsupported_major",currentVersion:n,requiredRange:e,remediation:`Node ${t.major}.x is newer than this artifact's qualified range (${e}). Use a qualified Node major or wait for the next runtime qualification.`}:{status:"compatible",currentVersion:n,requiredRange:e,remediation:null}}export{a as KYNVER_NODE_PATCH_FLOOR,d as PRIVATE_ROOT_NODE_RANGE,l as PUBLISHED_NODE_RANGE,m as evaluateNodeRuntimePolicy};

package/dist/paths.d.ts

@@ -4,7 +4,7 @@
  * Server mirror: agent-os.harness-root.ts
  */
 export declare function normalizeHarnessRoot(root: string): string;
-/** Canonical harness root for CLI/workers. */
+/** Canonical harness root for CLI/workers (box-scoped when identity is known). */
 export declare function resolveHarnessRoot(): string;
 export declare function harnessRunsDir(harnessRoot: string): string;
 export declare function harnessWorktreesDir(harnessRoot: string): string;

package/dist/prompt.d.ts

@@ -1,4 +1,5 @@
-export declare function buildPrompt(input: {
+import { type ContextBudgetReceiptSurface, type ContextEnvelopeMode, type RuntimeContextBudgetReceiptV2 } from "./context-budget-receipt.js";
+export type BuildPromptInput = {
     task: string;
     ownedPaths: string[];
     worktreePath: string;
@@ -19,4 +20,37 @@ export declare function buildPrompt(input: {
     model?: string;
     repairTargetPrUrl?: string;
     repairTargetBranch?: string;
-}): string;
+    agentOsId?: string | null;
+    personaSlug?: string | null;
+    mode?: ContextEnvelopeMode;
+    /**
+     * Package-safe kill-switch gate (PR3): when true, the hard-cap engine is
+     * active and `budgetSatisfied` on the receipt reflects live enforcement.
+     * Callers read `KYNVER_CONTEXT_BUDGET_ENFORCEMENT` server-side and pass
+     * the resolved boolean so the runtime package stays env-free.
+     * Defaults to false (shadow mode: measure and report, never truncate).
+     */
+    enforcementEnabled?: boolean;
+    /** Operator steer overlay from dispatch-next harnessWorkerContext. */
+    steerOverlayMarkdown?: string | null;
+    reviewOnly?: boolean;
+};
+export declare function buildPrompt(input: BuildPromptInput): string;
+export declare function buildPromptWithReceipt(input: BuildPromptInput & {
+    surface?: ContextBudgetReceiptSurface;
+    generatedAt?: string;
+}): {
+    prompt: string;
+    receipt: RuntimeContextBudgetReceiptV2;
+};
+/**
+ * Prompt hard-cap constants exposed for tests and diagnostics (PR3).
+ * All measurements are in chars (runtime prompt is built as a JS string).
+ * Pass `enforcementEnabled: true` in BuildPromptInput to activate enforcement;
+ * callers read KYNVER_CONTEXT_BUDGET_ENFORCEMENT server-side — do not read
+ * env vars inside the runtime package (package-safe contract).
+ */
+export declare const RUNTIME_PROMPT_ENFORCEMENT: {
+    readonly hardCapChars: 200000;
+    readonly safeFloorChars: 500;
+};

package/dist/providers/claude.d.ts

@@ -1,6 +1,8 @@
 import type { WorkerProvider } from "./types.js";
+import type { WorkerProviderStartOptions } from "./types.js";
 /** Provider default when no explicit model is passed — Sonnet, not Opus. */
 export declare const CLAUDE_DEFAULT_MODEL = "claude-sonnet-4-6";
 /** Model for review/gate/critique lanes when dispatched on the claude provider. */
 export declare const CLAUDE_REVIEW_MODEL = "claude-opus-4-8";
 export declare const claudeProvider: WorkerProvider;
+export declare function buildClaudeProviderArgs(opts: Pick<WorkerProviderStartOptions, "executionMode" | "prompt">, model: string): string[];

package/dist/providers/cursor.d.ts

@@ -1,4 +1,5 @@
 import type { WorkerProvider } from "./types.js";
+import type { WorkerProviderStartOptions } from "./types.js";
 export interface CursorSpawnTarget {
     executable: string;
     prefixArgs: string[];
@@ -9,3 +10,4 @@ export interface CursorSpawnTarget {
 /** Resolve a headless Windows spawn target (node.exe + index.js), never agent.cmd via shell. */
 export declare function resolveCursorSpawn(agentBin: string): CursorSpawnTarget;
 export declare const cursorProvider: WorkerProvider;
+export declare function buildCursorProviderArgs(opts: Pick<WorkerProviderStartOptions, "executionMode" | "worktreePath" | "prompt">, model: string, prefixArgs?: string[]): string[];

package/dist/providers/types.d.ts

@@ -11,6 +11,10 @@ export interface WorkerProviderStartOptions {
     heartbeatPath: string;
     /** Fully built agent prompt passed to the provider CLI. */
     prompt: string;
+    /** Expert/security review lane — spawn env blocks prod DB resolution (LB1). */
+    reviewWorker?: boolean;
+    /** Provider-enforced worker capability mode. */
+    executionMode?: import("../worker-execution-mode.js").WorkerExecutionMode;
 }
 export interface WorkerProviderStartResult {
     pid: number;

package/dist/review-head-reconcile.d.ts

@@ -0,0 +1,17 @@
+export interface ReviewHeadReconcileResponse {
+    ok?: boolean;
+    dispatchable?: boolean;
+    outcome?: string;
+    reason?: string | null;
+    reviewTaskId?: string;
+    activeReviewTaskId?: string | null;
+    reviewTargetSha?: string | null;
+    merged?: boolean;
+}
+export declare function taskLooksLikeReviewDispatch(task: Record<string, unknown>): boolean;
+export declare function reconcileReviewHeadBeforeWorkerStart(input: {
+    agentOsId: string;
+    taskId: string;
+    baseUrl: string;
+    secret: string;
+}): Promise<ReviewHeadReconcileResponse | null>;

package/dist/run-store.d.ts

@@ -11,6 +11,12 @@ export interface HarnessRunRecord {
         workerDir: string;
         statusPath: string;
     }>;
+    /** Physical pool that owns this run (`ghost` | `forge`). */
+    boxKind?: string;
+    /** Stable runner id that claimed this run namespace. */
+    runnerId?: string;
+    /** Harness root path isolating this run from other pools. */
+    harnessRoot?: string;
 }
 export declare function getPaths(): {
     harnessRoot: string;

package/dist/runner-boundary/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./runner-boundary.types.js";
+export * from "./runner-boundary.harness-root.js";
+export * from "./runner-boundary.resolve.js";
+export * from "./runner-boundary.run-guard.js";
+export * from "./runner-boundary.dispatch-guard.js";
+export * from "./runner-boundary.forge-legacy-migration.js";

package/dist/runner-boundary/runner-boundary.dispatch-guard.d.ts

@@ -0,0 +1,4 @@
+import type { RunnerBoundaryIdentity, RunnerBoundaryValidation } from "./runner-boundary.types.js";
+export declare function validateInteractiveDispatchBoundary(env?: NodeJS.ProcessEnv): RunnerBoundaryValidation;
+export declare function formatRunnerBoundaryFailure(validation: RunnerBoundaryValidation): string;
+export declare function assertInteractiveDispatchBoundaryOrThrow(env?: NodeJS.ProcessEnv): RunnerBoundaryIdentity;

package/dist/runner-boundary/runner-boundary.forge-legacy-migration.d.ts

@@ -0,0 +1,23 @@
+export type ForgeLegacyMigrationVerdict = {
+    action: "none";
+} | {
+    action: "migrate";
+} | {
+    action: "blocked";
+    blocker: string;
+};
+/** True when the forge box-scoped root has no harness layout yet. */
+export declare function isForgeScopedHarnessRootEmpty(forgeRoot: string): boolean;
+/** True when the legacy shared harness root still has run records on disk. */
+export declare function legacySharedHarnessHasRuns(sharedRoot: string): boolean;
+/**
+ * Ghost is co-hosted when a ghost pool namespace exists or shared runs are
+ * attributed to ghost — moving forge legacy content would orphan ghost work.
+ */
+export declare function isGhostCoHostedAtHarnessRoot(sharedRoot: string): boolean;
+export declare function assessForgeLegacyHarnessMigration(input: {
+    sharedRoot: string;
+    forgeRoot: string;
+}): ForgeLegacyMigrationVerdict;
+/** Move legacy shared runs/worktrees into the empty forge box-scoped root. */
+export declare function executeForgeLegacyHarnessMigration(sharedRoot: string, forgeRoot: string): void;

package/dist/runner-boundary/runner-boundary.harness-root.d.ts

@@ -0,0 +1,17 @@
+import type { WorkerPoolBoxKind } from "../box-identity.js";
+import type { HarnessRootResolution } from "./runner-boundary.types.js";
+/** Strip mistaken trailing `runs` / `worktrees` segments from a harness root path. */
+export declare function normalizeHarnessRootPath(root: string): string;
+/** Per-pool namespace under ~/.kynver/harness/{ghost|forge}. */
+export declare function boxScopedHarnessRoot(boxKind: WorkerPoolBoxKind, env?: NodeJS.ProcessEnv): string;
+/**
+ * Resolve the on-disk harness root for a runner boundary.
+ * Order: env → config.harnessRoot → box-scoped dir → legacy shared (ghost only).
+ */
+export declare function resolveHarnessRootForRunnerBoundary(input: {
+    boxKind: WorkerPoolBoxKind;
+    configuredHarnessRoot?: string | null;
+    env?: NodeJS.ProcessEnv;
+    /** When false, assess migration but do not move on-disk layout (tests). */
+    allowForgeLegacyMigration?: boolean;
+}): HarnessRootResolution;

package/dist/runner-boundary/runner-boundary.resolve.d.ts

@@ -0,0 +1,4 @@
+import type { KynverUserConfig } from "../config.js";
+import type { RunnerBoundaryResolveOptions, RunnerBoundaryValidation } from "./runner-boundary.types.js";
+export declare function deriveDefaultRunnerId(boxKind: string, hostname: string): string;
+export declare function resolveRunnerBoundary(config?: KynverUserConfig, env?: NodeJS.ProcessEnv, options?: RunnerBoundaryResolveOptions): RunnerBoundaryValidation;

package/dist/runner-boundary/runner-boundary.run-guard.d.ts

@@ -0,0 +1,12 @@
+import type { HarnessRunRecord } from "../run-store.js";
+import type { RunnerBoundaryIdentity } from "./runner-boundary.types.js";
+export interface RunBoundaryGuardResult {
+    ok: boolean;
+    reason?: string;
+    stamped?: boolean;
+}
+/**
+ * Ensure a harness run belongs to the active runner boundary.
+ * Legacy runs without stamps are migrated in-place on first dispatch.
+ */
+export declare function assertRunMatchesRunnerBoundary(run: HarnessRunRecord, boundary: RunnerBoundaryIdentity): RunBoundaryGuardResult;

package/dist/runner-boundary/runner-boundary.types.d.ts

@@ -0,0 +1,31 @@
+import type { BoxKindSource, WorkerPoolBoxKind } from "../box-identity.js";
+import type { WorkerCapSource } from "../worker-cap-source.js";
+export type HarnessRootSource = "env" | "config" | "box_scoped" | "legacy_shared" | "legacy_migrated";
+export interface HarnessRootResolution {
+    harnessRoot: string;
+    source: HarnessRootSource;
+    /** Set when Forge legacy migration is required but blocked pending operator sign-off. */
+    migrationBlocker?: string;
+}
+export interface RunnerBoundaryIdentity {
+    boxKind: WorkerPoolBoxKind;
+    boxKindSource: BoxKindSource;
+    runnerId: string;
+    runnerIdSource: "config" | "env" | "derived";
+    maxConcurrentWorkers: number;
+    workerCapSource: WorkerCapSource;
+    harnessRoot: string;
+    harnessRootSource: HarnessRootSource;
+}
+export interface RunnerBoundaryValidation {
+    ok: boolean;
+    identity: RunnerBoundaryIdentity | null;
+    errors: string[];
+    warnings: string[];
+}
+export interface RunnerBoundaryResolveOptions {
+    /** Interactive dispatch always requires explicit box kind (config or env). */
+    requireExplicitBoxKind?: boolean;
+    /** Treat slug-only env as a hard error (daemon strict mode). */
+    strict?: boolean;
+}

package/dist/runner-config-backfill.d.ts

@@ -0,0 +1,18 @@
+import { type KynverUserConfig } from "./config.js";
+export interface RunnerConfigBackfillResult {
+    updated: boolean;
+    fields: string[];
+    skippedAmbiguous: string[];
+}
+/**
+ * Safe migration/backfill of ~/.kynver/config.json from env and scoped credentials.
+ * Never adopts ambiguous workspace identity or writes raw tokens.
+ */
+export declare function buildRunnerConfigBackfillUpdates(config: KynverUserConfig, env?: NodeJS.ProcessEnv): {
+    updates: Partial<KynverUserConfig>;
+    fields: string[];
+    skippedAmbiguous: string[];
+};
+export declare function backfillRunnerConfigFromLegacySources(opts?: {
+    dryRun?: boolean;
+}): RunnerConfigBackfillResult;

package/dist/runtime-identity.d.ts

@@ -0,0 +1,9 @@
+export interface RuntimeIdentityV1 {
+    contractVersion: 1;
+    nodeVersion: string;
+    runtimePackageVersion: string;
+    buildIdentity: string | null;
+    platform: NodeJS.Platform;
+    arch: string;
+}
+export declare function buildRuntimeIdentity(): RuntimeIdentityV1;

package/dist/runtime-memory-envelope.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Dependency-free runtime-memory-envelope v2 schema + flag helpers for harness hosts.
+ */
+export declare const AGENT_RUNTIME_ENVELOPE_SCHEMA_VERSION: "runtime-memory-envelope.v1";
+export declare const AGENT_RUNTIME_ENVELOPE_SCHEMA_VERSION_V2: "runtime-memory-envelope.v2";
+export declare const AGENT_RUNTIME_ENVELOPE_SCHEMA_VERSIONS: readonly ["runtime-memory-envelope.v1", "runtime-memory-envelope.v2"];
+export type AgentRuntimeEnvelopeSchemaVersion = (typeof AGENT_RUNTIME_ENVELOPE_SCHEMA_VERSIONS)[number];
+export declare function runtimeEnvelopeV2Enabled(): boolean;
+export type RuntimeEnvelopeFlagSource = "env_explicit_on" | "env_explicit_off" | "default_off";
+export interface RuntimeEnvelopeWriterConfig {
+    schemaVersion: AgentRuntimeEnvelopeSchemaVersion;
+    v2WriterEnabled: boolean;
+    effectiveSource: RuntimeEnvelopeFlagSource;
+}
+export declare function resolveRuntimeEnvelopeWriterConfig(): RuntimeEnvelopeWriterConfig;
+export declare function isAgentRuntimeEnvelopeSchemaVersion(value: string): value is AgentRuntimeEnvelopeSchemaVersion;

package/dist/security-review-environment.d.ts

@@ -0,0 +1,27 @@
+/**
+ * LB1 — review workers must not receive unrestricted production DB credentials.
+ * Spawn sets KYNVER_NO_PROD_DB_CREDENTIALS; db-credential-resolver refuses when set.
+ */
+/** Truthy when the worker is a source-only / expert review lane (no prod DB). */
+export declare const KYNVER_NO_PROD_DB_CREDENTIALS_ENV = "KYNVER_NO_PROD_DB_CREDENTIALS";
+/** Extra env keys stripped for review workers (operator file pointers). */
+export declare const REVIEW_WORKER_EXTRA_FORBIDDEN_ENV_KEYS: readonly ["KYNVER_ENV_FILE"];
+export declare function isNoProdCredentialReviewEnvironment(env: NodeJS.ProcessEnv): boolean;
+export interface BuildWorkerSpawnEnvOptions {
+    reviewWorker?: boolean;
+}
+export declare function buildWorkerSpawnEnv(hostEnv: NodeJS.ProcessEnv, opts?: BuildWorkerSpawnEnvOptions): NodeJS.ProcessEnv;
+export declare class ProductionDatabaseCredentialBlockedError extends Error {
+    constructor();
+}
+export declare function assertProductionDatabaseResolutionAllowed(env: NodeJS.ProcessEnv): void;
+export interface ReviewWorkerCredentialScopeAudit {
+    reviewMode: boolean;
+    noProdFlagPresent: boolean;
+    forbiddenKeysAfterScrub: string[];
+    productionDbKeysAbsent: boolean;
+    envFilePointerStripped: boolean;
+    safe: boolean;
+}
+/** Audit credential scope for diagnostics and security-boundary proofs (no secret values). */
+export declare function auditReviewWorkerCredentialScope(env: NodeJS.ProcessEnv, opts?: BuildWorkerSpawnEnvOptions): ReviewWorkerCredentialScopeAudit;