@kynver-app/runtime 0.2.4 → 0.2.13

package/dist/local-run-store/store-lifecycle.d.ts

@@ -0,0 +1,38 @@
+import type { LocalRunStore } from "./local-run-store.js";
+import type { ClassifyOptions } from "./sqlite/sqlite-filesystem-policy.js";
+interface LifecycleTestOverrides {
+    classifyOptions?: ClassifyOptions;
+}
+/** Test-only: inject filesystem-policy classification (cross-platform temp dirs). */
+export declare function __setLocalRunStoreLifecycleTestOverrides(overrides: LifecycleTestOverrides): void;
+export interface LocalRunStoreLifecycleStatus {
+    /** `open` — handle live; `unavailable` — open failed (reason set); `unopened` — not yet requested. */
+    state: "open" | "unavailable" | "unopened";
+    harnessRoot: string | null;
+    databasePath: string | null;
+    schemaVersion: number | null;
+    /** True when open had to quarantine a corrupt db and rebuild fresh. */
+    recovered: boolean;
+    quarantinedTo: string | null;
+    /** Failure classification when unavailable (message, no payloads). */
+    reason: string | null;
+    /** Total open attempts this process (retry churn indicator). */
+    openAttempts: number;
+}
+/** Backoff window before an unavailable store is re-probed (D1a precondition). */
+export declare const LOCAL_RUN_STORE_OPEN_RETRY_MS: number;
+/**
+ * The process-wide store handle, or `null` when the store cannot open.
+ * Never throws. A changed harness root (tests, reconfiguration) re-opens; a
+ * transient open failure is retried after the backoff window.
+ */
+export declare function getLocalRunStore(nowMs?: number): LocalRunStore | null;
+/** Lifecycle status without forcing an open (state `unopened` before first use). */
+export declare function getLocalRunStoreLifecycleStatus(): LocalRunStoreLifecycleStatus;
+/** Open (if needed) and report status in one call — the doctor/tick probe. */
+export declare function probeLocalRunStore(): LocalRunStoreLifecycleStatus;
+/** Close and forget the handle (tests, daemon shutdown). Never throws. */
+export declare function closeLocalRunStore(): void;
+/** Test-only: full reset including the process open-attempt counter. */
+export declare function __resetLocalRunStoreLifecycleForTests(): void;
+export {};

package/dist/local-run-store/surface-flags.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Durable-harness D0 — per-surface migration flags for the local run store.
+ *
+ * Every surface migrates independently through `off` (default — today's
+ * behavior, byte-identical) → `shadow` (store written alongside the existing
+ * path; existing path authoritative; divergences counted) → `enforce` (store
+ * authoritative for the LOCAL decision). Unknown/empty values resolve to
+ * `off` with a recorded warning — a typo must never silently enable a mode.
+ *
+ * D0 lands the parser only; no surface consults its flag yet.
+ */
+export type LocalRunStoreSurfaceMode = "off" | "shadow" | "enforce";
+export type LocalRunStoreSurfaceKey = "dispatchReceipts" | "admission" | "planOutbox" | "keeper" | "meshLease" | "quota";
+export interface LocalRunStoreSurfaceDefinition {
+    key: LocalRunStoreSurfaceKey;
+    env: string;
+    /** Plan milestone that wires the surface (operator orientation). */
+    milestone: string;
+}
+export declare const LOCAL_RUN_STORE_SURFACES: readonly LocalRunStoreSurfaceDefinition[];
+export type LocalRunStoreSurfaceFlags = Record<LocalRunStoreSurfaceKey, LocalRunStoreSurfaceMode>;
+/** Where each surface's effective mode came from (confirmation loop). */
+export type LocalRunStoreSurfaceFlagSource = "env" | "server" | "default";
+export interface ResolvedLocalRunStoreSurfaceFlags {
+    flags: LocalRunStoreSurfaceFlags;
+    sources: Record<LocalRunStoreSurfaceKey, LocalRunStoreSurfaceFlagSource>;
+    /** One entry per env var whose value was set but not a recognized mode. */
+    warnings: string[];
+}
+export declare function parseLocalRunStoreSurfaceMode(raw: string | undefined | null): {
+    mode: LocalRunStoreSurfaceMode;
+    unknown: boolean;
+};
+/**
+ * Effective per-surface modes with precedence
+ * env (explicitly set) > server-delivered policy > default `off`.
+ *
+ * The env var is the host-level override and local emergency brake; on the
+ * normal box (env unset everywhere) the server-delivered policy governs —
+ * boxes are administered from the backend, never by shell access
+ * (`remote-surface-flags.ts`). An UNKNOWN env value still wins the
+ * precedence as `off` (a typo must fail safe, not silently fall through to
+ * a server-delivered `enforce`).
+ */
+export declare function resolveLocalRunStoreSurfaceFlags(env?: NodeJS.ProcessEnv): ResolvedLocalRunStoreSurfaceFlags;
+/** True when any surface is past `off` (store activity expected on this host). */
+export declare function anyLocalRunStoreSurfaceActive(flags: LocalRunStoreSurfaceFlags): boolean;

package/dist/local-run-store/tick-posture.d.ts

@@ -0,0 +1,27 @@
+import { type LocalRunStoreSurfaceFlags } from "./surface-flags.js";
+export interface LocalRunStoreTickPosture {
+    contractVersion: 1;
+    observedAt: string;
+    /** `open` | `unavailable` (a tick posture always probes, so never `unopened`). */
+    state: "open" | "unavailable" | "unopened";
+    schemaVersion: number | null;
+    /** True when this open had to quarantine a corrupt db and rebuild. */
+    recovered: boolean;
+    /** Failure class when unavailable (error name only — no message payload). */
+    unavailableClass: string | null;
+    flags: LocalRunStoreSurfaceFlags;
+    /** Where each effective mode came from — env override, server policy, or default. */
+    flagSources: Record<string, "env" | "server" | "default">;
+    flagWarningCount: number;
+    /** Per-surface shadow divergence counters (D1+; empty in D0). */
+    divergenceCounters: Record<string, number>;
+}
+export declare function buildLocalRunStoreTickPosture(options?: {
+    env?: NodeJS.ProcessEnv;
+    now?: () => Date;
+    /** Liveness probe for the stranded-claim scan (injected to avoid run-store cycles). */
+    hasLiveWorker?: (intent: {
+        runId: string;
+        workerName: string;
+    }) => boolean;
+}): LocalRunStoreTickPosture;

package/dist/plan-persist/index.d.ts

@@ -2,7 +2,7 @@ export type { PlanPersistUserStatus, PlanPersistOperation, PlanOutboxItem, Persi
 export { hashPlanBody, hashSummary } from "./body-hash.js";
 export { persistPlan } from "./persist.js";
 export { drainPlanOutbox, loadOutboxById } from "./drain.js";
-export { listOutboxItems, findOutboxByIdempotencyKey } from "./outbox-store.js";
+export { listOutboxItems, findOutboxByIdempotencyKey, writeOutboxItem } from "./outbox-store.js";
 export { formatPlanOutboxHandoffBlock, extractPlanOutboxFromTask, } from "./handoff.js";
 export { isTmpOnlyPath, planOutboxDir } from "./paths.js";
 export { PlanPersistError } from "./errors.js";

package/dist/plan-persist/outbox-durability.d.ts

@@ -0,0 +1,31 @@
+import type { LocalRunStoreSurfaceMode } from "../local-run-store/surface-flags.js";
+export declare function planOutboxMode(env?: NodeJS.ProcessEnv): LocalRunStoreSurfaceMode;
+/**
+ * A corrupt spool file was sighted. `shadow`: count only (caller keeps
+ * today's behavior). `enforce`: quarantine by rename (never delete) and tell
+ * the caller to continue. Returns true when the file was quarantined.
+ */
+export declare function handleCorruptOutboxFile(paths: string[], now?: () => Date): boolean;
+/**
+ * Per-item drain serialization. `enforce`: only the reservation winner may
+ * drain the item (crash backstop = TTL). `shadow`: a lost race is counted,
+ * the caller proceeds as today. Never throws.
+ */
+export declare function tryAcquireDrainSlot(itemId: string, owner: string): {
+    proceed: boolean;
+    deduplicated: boolean;
+};
+export declare function releaseDrainSlot(itemId: string, owner: string): void;
+/** Record the verified persist on the item's existing idempotency key. */
+export declare function recordPlanPersistedReceipt(idempotencyKey: string, planId: string | null): void;
+/** Archive intent receipt — recorded BEFORE the two renames (enforce). */
+export declare function recordArchiveIntentReceipt(itemId: string): void;
+/**
+ * ENFORCE-mode drain preamble: an item whose archive-intent receipt exists is
+ * a crash between the archive renames — complete the renames instead of
+ * re-persisting. Returns true when the item was (re)archived away.
+ */
+export declare function completeHalfArchiveIfIntended(itemId: string, renameRemaining: () => void): boolean;
+/** Counters snapshot for the operator-tick posture (surface active only). */
+export declare function planOutboxCounters(): Record<string, number>;
+export declare function __resetPlanOutboxCountersForTests(): void;

package/dist/plan-persist/outbox-store.d.ts

@@ -10,6 +10,24 @@ export declare function writeOutboxItem(input: PersistPlanInput, opts: {
 }): PlanOutboxItem;
 export declare function saveOutboxItem(item: PlanOutboxItem): void;
 export declare function archiveOutboxItem(item: PlanOutboxItem): void;
+/**
+ * The bare renames (idempotent — each guarded by existsSync). ORDER MATTERS
+ * (D3 review N-1): the BODY moves first, the `.json` last, so the state a
+ * crash between the renames leaves behind is a LISTED item (json still in
+ * the outbox) with an archived body — which the next drain detects via the
+ * archive-intent receipt and completes. The reverse order left an invisible
+ * json-less orphan body no drain could ever see.
+ */
+export declare function archiveOutboxItemFiles(item: PlanOutboxItem): void;
+/**
+ * Filesystem-evidence archive completion (re-review N-7, ALL modes): the
+ * body sitting at its id-derived ARCHIVE destination can only mean a
+ * post-verified-persist archive began and crashed (or hit a transient json
+ * rename error) between the renames — the plan is already persisted. Finish
+ * the json rename so the item cannot wedge the drain (off/shadow have no
+ * receipt to consult; the fs state alone is proof). Store-free by design.
+ */
+export declare function completeArchiveFromFilesystemEvidence(item: PlanOutboxItem): boolean;
 export declare function outboxItemPaths(item: PlanOutboxItem): {
     jsonPath: string;
     bodyPath: string;

package/dist/plan-persist/types.d.ts

@@ -83,9 +83,13 @@ export interface DrainOutboxResult {
     succeeded: number;
     stillQueued: number;
     failed: number;
+    /** D3 enforce: items skipped because another drainer holds the lease. */
+    deduplicated?: number;
     results: Array<{
         outboxId: string;
         userStatus: PlanPersistUserStatus;
         lastError?: string;
+        /** True when this row reports a skip, not a persist attempt. */
+        skipped?: boolean;
     }>;
 }

package/dist/repo-search.d.ts

@@ -17,10 +17,23 @@ export declare function normalizeRgArgv(argv: string[]): {
     argv: string[];
     changed: boolean;
 };
+/** Peel `bash -lc '…'` / `sh -c "…"` wrappers so rg normalization sees the inner script. */
+export declare function unwrapShellWrapperCommand(command: string): {
+    command: string;
+    wrapped: boolean;
+};
 export declare function normalizeRepoSearchCommand(command: string): {
     command: string;
     changed: boolean;
 };
+export declare function isRgLikeCommand(command: string): boolean;
+/** Ripgrep exit 1 with no error text is a successful read-only search (no matches), not a shell failure. */
+export declare function shouldTreatRgNoMatchAsSuccess(input: {
+    command: string;
+    exitCode?: number;
+    stderr?: string;
+    interleaved?: string;
+}): boolean;
 export declare function extractSearchMeta(meta: string): {
     pattern?: string;
     target?: string;

package/dist/resource-gate.d.ts

@@ -58,6 +58,15 @@ export declare function countActiveWorkers(runId: string): number;
  * infinity, never N" bug). This machine-wide count is what the gate must use.
  */
 export declare function countActiveWorkersGlobal(): number;
+/**
+ * Identities of every active worker machine-wide (durable-harness D2a: the
+ * admission-shadow reconcile refreshes/releases slot reservations against
+ * exactly the records the gate counts).
+ */
+export declare function listActiveWorkerIdentitiesGlobal(): Array<{
+    runId: string;
+    workerName: string;
+}>;
 /**
  * Compute how many workers this host can run and how many dispatch slots remain.
  * Uses total RAM for steady-state capacity and free RAM as a hard safety gate.