@kynver-app/runtime 0.1.42 → 0.1.47

package/dist/installed-package-versions.d.ts

@@ -0,0 +1,6 @@
+export type InstalledPackageVersionMap = Record<string, {
+    version: string;
+    observedAt: string;
+    path: string;
+}>;
+export declare function collectInstalledPackageVersions(observedAt?: string): Promise<InstalledPackageVersionMap>;

package/dist/landing-contract-gate.d.ts

@@ -0,0 +1,24 @@
+import type { WorkerLandingSnapshot } from "./landing-gate.js";
+export type TargetPrOutcome = "merged" | "skipped" | "blocked";
+export interface TargetPrReconciliation {
+    prUrl: string;
+    outcome: TargetPrOutcome;
+    mergeCommit?: string | null;
+    reason?: string | null;
+}
+export interface WorkerLandingContract {
+    landingOnly: boolean;
+    targetPrUrls: string[];
+}
+export type WorkerLandingContractBlockReason = "unrelated_implementation_pr" | "missing_target_pr_reconciliation" | "incomplete_target_pr_landing";
+export interface WorkerLandingContractVerdict {
+    blocked: boolean;
+    reason?: WorkerLandingContractBlockReason;
+    detail?: string;
+}
+export declare function assessWorkerLandingContract(input: {
+    contract: WorkerLandingContract;
+    snapshot: WorkerLandingSnapshot;
+    finalResult?: unknown;
+}): WorkerLandingContractVerdict;
+export declare function landingContractAttentionReason(verdict: WorkerLandingContractVerdict): string | undefined;

package/dist/landing-gate.d.ts

@@ -0,0 +1,24 @@
+import type { GitAncestry } from "./git.js";
+export type WorkerLandingBlockReason = "dirty_worktree_no_pr";
+export interface WorkerLandingSnapshot {
+    finalResult: unknown;
+    changedFiles: string[];
+    headCommit?: string | null;
+    prUrl?: string | null;
+    artifactBundlePath?: string | null;
+    patchPath?: string | null;
+    gitAncestry?: GitAncestry | null;
+}
+export interface WorkerLandingVerdict {
+    /** When true, do not treat the worker as cleanly landed/done. */
+    blocked: boolean;
+    reason?: WorkerLandingBlockReason;
+    /** Human-readable attention reason for boards and completion payloads. */
+    detail?: string;
+}
+/**
+ * Hard landing gate: a recorded final result is not sufficient when the worker
+ * left uncommitted code and has no commit/PR/patch/bundle landing path.
+ */
+export declare function assessWorkerLanding(snapshot: WorkerLandingSnapshot): WorkerLandingVerdict;
+export declare function landingAttentionReason(verdict: WorkerLandingVerdict): string | undefined;

package/dist/lease-renewal.d.ts

@@ -0,0 +1,15 @@
+export interface RenewActiveLeasesResult {
+    renewed: string[];
+    failed: Array<{
+        worker: string;
+        reason: string;
+    }>;
+    skipped: string[];
+}
+/**
+ * Renew leases for board-linked workers whose process is still alive.
+ * Prevents dispatch/reaper from reclaiming a task while a local worker runs.
+ */
+export declare function renewActiveTaskLeases(runId: string, args: Record<string, string | boolean>): Promise<RenewActiveLeasesResult>;
+/** True when this run already has a live worker bound to the same board task. */
+export declare function hasLiveWorkerForTask(runId: string, taskId: string): boolean;

package/dist/model-routing-task-enrich.d.ts

@@ -0,0 +1,8 @@
+/** Enrich dispatch task metadata with `roleLane` when the board row omits it. */
+/**
+ * Best-effort plan role lane from persona, title, and executorRef.
+ * Returns undefined when nothing confident matches.
+ */
+export declare function inferRoleLaneFromTask(task: Record<string, unknown>): string | undefined;
+/** Attach inferred `roleLane` so `inferModelRoutingFromTask` can use plan-lane rules. */
+export declare function enrichTaskForModelRouting(task: Record<string, unknown>): Record<string, unknown>;

package/dist/model-routing.d.ts

@@ -0,0 +1,29 @@
+import { type KynverUserConfig } from "./config.js";
+/** Conservative default — Sonnet for ordinary harness work (not Opus). */
+export declare const GLOBAL_DEFAULT_MODEL = "claude-sonnet-4-6";
+export declare const CURSOR_DEFAULT_MODEL = "composer-2.5";
+export interface ModelRoutingDecision {
+    /** Model id passed to the provider CLI (undefined → provider default). */
+    model?: string;
+    /** Worker provider key (`claude` | `cursor`). */
+    provider: string;
+    /** Audit trail for Command Center / worker.json. */
+    rule: string;
+    /** Original task/board model request when inferred from metadata. */
+    requestedModel?: string;
+}
+/** Resolve global default: config → env → Sonnet. */
+export declare function resolveGlobalDefaultModel(config?: KynverUserConfig): string;
+/**
+ * Infer model + provider from AgentOS task metadata when the dispatcher did not
+ * 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. */
+export declare function resolveWorkerLaunch(input: {
+    explicitModel?: string;
+    explicitProvider?: string;
+    task?: Record<string, unknown>;
+}): ModelRoutingDecision;
+/** Fallback chain tail after provider start — never hard-code Opus here. */
+export declare function resolveModelFallback(startedModel: string | undefined, launchModel: string | undefined, providerDefault: string | undefined): string;

package/dist/monitor/index.d.ts

@@ -0,0 +1,7 @@
+export type { AutoCompleteAssessment, MonitorListEntry, MonitorSessionRecord, MonitorTickResult, TaskLeaseSnapshot, WorkerHealthClass, WorkerMonitorView, } from "./monitor.types.js";
+export { classifyWorkerHealth, type WorkerHealthClassification } from "./monitor.classify.js";
+export { assessAutoCompleteEligibility } from "./monitor.terminal.js";
+export { getMonitorStatus, listMonitors, monitorAutoCompleteCli, runMonitorTick, stopMonitor, } from "./monitor.service.js";
+export { spawnMonitorSidecar, type SpawnedMonitor, type SpawnMonitorOptions } from "./monitor-spawn.js";
+export { runMonitorLoop } from "./monitor-loop.js";
+export { deleteMonitorSession, loadMonitorSession, monitorIdFor, saveMonitorSession, } from "./monitor.store.js";

package/dist/monitor/monitor-cli.d.ts

@@ -0,0 +1,9 @@
+import { getMonitorStatus, listMonitors, monitorAutoCompleteCli, runMonitorTick, stopMonitor } from "./monitor.service.js";
+import type { StartMonitorResult } from "./monitor.service.js";
+export declare function startMonitorCli(args: Record<string, string | boolean>): Promise<StartMonitorResult>;
+export declare function monitorStatusCli(args: Record<string, string | boolean>): Promise<void>;
+export declare function monitorStopCli(args: Record<string, string | boolean>): void;
+export declare function monitorListCli(): void;
+export declare function monitorRunLoopCli(args: Record<string, string | boolean>): Promise<void>;
+export declare function monitorTickCli(args: Record<string, string | boolean>): Promise<void>;
+export { monitorAutoCompleteCli, startMonitorCli as startMonitor, getMonitorStatus, listMonitors, runMonitorTick, stopMonitor, };

package/dist/monitor/monitor-loop.d.ts

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

package/dist/monitor/monitor-spawn.d.ts

@@ -0,0 +1,18 @@
+import type { MonitorSessionRecord } from "./monitor.types.js";
+export interface SpawnMonitorOptions {
+    runId: string;
+    workerName?: string;
+    agentOsId?: string;
+    pollMs?: number;
+    cliPath?: string;
+    nodeExecutable?: string;
+    baseUrl?: string;
+    secret?: string;
+}
+export interface SpawnedMonitor {
+    monitorId: string;
+    pid?: number;
+    logPath: string;
+    session: MonitorSessionRecord;
+}
+export declare function spawnMonitorSidecar(opts: SpawnMonitorOptions): SpawnedMonitor | undefined;

package/dist/monitor/monitor.classify.d.ts

@@ -0,0 +1,15 @@
+import { type HarnessWorkerRecord, type RawHarnessWorkerStatus } from "../status.js";
+import type { TaskLeaseSnapshot, WorkerHealthClass } from "./monitor.types.js";
+export interface WorkerHealthClassification {
+    health: WorkerHealthClass;
+    reason: string;
+}
+/**
+ * Classify harness worker disk state vs optional board lease snapshot.
+ * `running` on AgentTask means live executor lease — not plan-row `in_progress`.
+ */
+export declare function classifyWorkerHealth(input: {
+    worker: HarnessWorkerRecord;
+    status: RawHarnessWorkerStatus;
+    taskLease?: TaskLeaseSnapshot | null;
+}): WorkerHealthClassification;

package/dist/monitor/monitor.service.d.ts

@@ -0,0 +1,17 @@
+import type { MonitorListEntry, MonitorSessionRecord, MonitorTickResult } from "./monitor.types.js";
+/** One monitor poll: classify workers, renew leases, auto-complete when verified terminal. */
+export declare function runMonitorTick(args: Record<string, string | boolean>): Promise<MonitorTickResult>;
+export declare function getMonitorStatus(args: Record<string, string | boolean>): MonitorTickResult;
+export declare function listMonitors(): MonitorListEntry[];
+export interface StartMonitorResult {
+    monitorId: string;
+    session: MonitorSessionRecord;
+    spawned: boolean;
+    pid?: number;
+}
+export declare function stopMonitor(args: Record<string, string | boolean>): {
+    monitorId: string;
+    stopped: boolean;
+    pid?: number;
+};
+export declare function monitorAutoCompleteCli(args: Record<string, string | boolean>): Promise<void>;

package/dist/monitor/monitor.store.d.ts

@@ -0,0 +1,6 @@
+import type { MonitorListEntry, MonitorSessionRecord } from "./monitor.types.js";
+export declare function monitorIdFor(runId: string, workerName?: string): string;
+export declare function loadMonitorSession(monitorId: string): MonitorSessionRecord | undefined;
+export declare function saveMonitorSession(session: MonitorSessionRecord): void;
+export declare function deleteMonitorSession(monitorId: string): boolean;
+export declare function listMonitorSessions(): MonitorListEntry[];

package/dist/monitor/monitor.task-lease.d.ts

@@ -0,0 +1,11 @@
+import type { TaskLeaseSnapshot } from "./monitor.types.js";
+/**
+ * Best-effort board lease snapshot for monitor classification. Failures return
+ * an empty map — local disk classification still runs without server data.
+ */
+export declare function fetchTaskLeasesForWorkers(input: {
+    agentOsId?: string;
+    taskIds: string[];
+    baseUrl?: string;
+    secret?: string;
+}): Promise<Map<string, TaskLeaseSnapshot>>;

package/dist/monitor/monitor.terminal.d.ts

@@ -0,0 +1,11 @@
+import { type HarnessWorkerRecord, type RawHarnessWorkerStatus } from "../status.js";
+import type { AutoCompleteAssessment } from "./monitor.types.js";
+/**
+ * Auto-complete may only run when the worker has reached a verified terminal
+ * condition and no structural blocker is present. Never paper over heartbeat
+ * blockers, landing gates, or completion replay failures.
+ */
+export declare function assessAutoCompleteEligibility(input: {
+    worker: HarnessWorkerRecord;
+    status: RawHarnessWorkerStatus;
+}): AutoCompleteAssessment;

package/dist/monitor/monitor.types.d.ts

@@ -0,0 +1,74 @@
+import type { RawHarnessWorkerStatus } from "../status.js";
+/** Local worker health — distinct from AgentTask `running` (live executor lease). */
+export type WorkerHealthClass = "healthy" | "stale" | "orphaned";
+export interface TaskLeaseSnapshot {
+    taskId: string;
+    /** AgentTask.status — `running` means a live executor lease on the board. */
+    status: string;
+    leaseOwner: string | null;
+    leaseExpiresAt: string | null;
+    heartbeatAt: string | null;
+    blocker: string | null;
+}
+export interface MonitorSessionRecord {
+    monitorId: string;
+    runId: string;
+    workerName?: string;
+    agentOsId?: string;
+    pid?: number;
+    startedAt: string;
+    stoppedAt?: string;
+    pollMs: number;
+    logPath: string;
+}
+export interface WorkerMonitorView {
+    runId: string;
+    worker: string;
+    health: WorkerHealthClass;
+    healthReason: string;
+    workerStatus: string;
+    attentionState: string;
+    attentionReason: string;
+    alive: boolean;
+    taskId?: string;
+    leaseOwner?: string;
+    taskStatus?: string;
+    autoComplete: AutoCompleteAssessment;
+    status: RawHarnessWorkerStatus;
+}
+export interface AutoCompleteAssessment {
+    eligible: boolean;
+    terminalVerified: boolean;
+    terminalReason?: string;
+    blockers: string[];
+}
+export interface MonitorTickResult {
+    runId: string;
+    agentOsId?: string;
+    workers: WorkerMonitorView[];
+    leaseRenewal?: {
+        renewed: string[];
+        failed: Array<{
+            worker: string;
+            reason: string;
+        }>;
+        skipped: string[];
+    };
+    autoCompleted: Array<{
+        worker: string;
+        outcome: string;
+        ok: boolean;
+        reason?: string;
+    }>;
+}
+export interface MonitorListEntry {
+    monitorId: string;
+    runId: string;
+    workerName?: string;
+    agentOsId?: string;
+    pid?: number;
+    alive: boolean;
+    startedAt: string;
+    pollMs: number;
+    logPath: string;
+}

package/dist/package-version.d.ts

@@ -0,0 +1,5 @@
+export declare function readOwnPackageVersion(moduleUrl?: string): string;
+export declare const PACKAGE_VERSION: string;
+export declare function wantsCliVersion(argv: string[]): boolean;
+export declare function printCliVersionAndExit(version: string, binName?: string): never;
+export declare function handleCliVersionFlag(argv: string[], moduleUrl?: string, binName?: string): boolean;

package/dist/path-values.d.ts

@@ -0,0 +1,5 @@
+export declare function expandHomePath(value: string): string;
+export declare function resolveUserPath(value: string): string;
+export declare function redactHomePath(value: string): string;
+/** User-facing path strings (doctor JSON, setup output). */
+export declare function displayUserPath(value: string): string;

package/dist/paths.d.ts

@@ -0,0 +1,7 @@
+export declare function resolveHarnessRoot(): string;
+export declare function getHarnessPaths(): {
+    harnessRoot: string;
+    runsDir: string;
+    worktreesDir: string;
+};
+export declare function runDir(runsDir: string, id: string): string;

package/dist/pipeline-dispatch.d.ts

@@ -0,0 +1,7 @@
+/** Drop CLI max-starts so pipeline ticks always use the resource-gate slot budget. */
+export declare function stripCliMaxStarts(args: Record<string, string | boolean>): Record<string, string | boolean>;
+/**
+ * Two-pass daemon dispatch: reserve one start for the review lane, then fill
+ * remaining slots from the mixed queue (review-first ordering on the server).
+ */
+export declare function runPipelineDispatch(args: Record<string, string | boolean>, slots: number): Promise<Record<string, unknown>>;

package/dist/pipeline-tick.d.ts

@@ -0,0 +1,45 @@
+import type { ReconcileStaleWorkersResult } from "./stale-reconcile.js";
+import { type RunnerResourceGateShape } from "./resource-gate.js";
+import { renewActiveTaskLeases } from "./lease-renewal.js";
+import type { HarnessCleanupSummary } from "./cleanup-types.js";
+export interface PipelineTickResult {
+    runId: string;
+    agentOsId: string;
+    execute: boolean;
+    resourceGate: RunnerResourceGateShape;
+    leaseRenewal?: Awaited<ReturnType<typeof renewActiveTaskLeases>>;
+    completedWorkers: Array<{
+        worker: string;
+        ok: boolean;
+        taskId?: string | null;
+        skipped?: boolean;
+    }>;
+    staleReconcile: ReconcileStaleWorkersResult;
+    planProgressSync: Array<{
+        worker: string;
+        phase: string;
+        ok: boolean;
+        skipped?: boolean;
+    }>;
+    completionAckSync: Array<{
+        worker: string;
+        taskId: string;
+        taskStatus: string;
+    }>;
+    harnessCleanup?: HarnessCleanupSummary;
+    operatorTick: unknown;
+    sweep: unknown;
+    dispatch: unknown;
+    idle: boolean;
+}
+export declare function completeFinishedWorkers(runId: string, args: Record<string, string | boolean>): Promise<Array<{
+    worker: string;
+    ok: boolean;
+    taskId?: string | null;
+    skipped?: boolean;
+}>>;
+/**
+ * One operator/dispatcher cycle (M10 / D7 pull-first):
+ * refresh status → complete finished workers → ingest operator tick → sweep leases → dispatch up to slot cap.
+ */
+export declare function runPipelineTick(args: Record<string, string | boolean>): Promise<PipelineTickResult>;

package/dist/plan-persist/agentos-api.d.ts

@@ -0,0 +1,28 @@
+import type { PersistPlanInput } from "./types.js";
+export interface AgentOsPlanGetPayload {
+    plan: {
+        id: string;
+        title: string;
+        summary: string | null;
+        currentVersionId: string | null;
+    };
+    currentVersion: {
+        id: string;
+        versionNumber: number;
+        title: string;
+        body: string;
+        summary: string | null;
+    } | null;
+}
+export interface AgentOsWriteResult {
+    planId: string;
+    versionId: string | null;
+    versionNumber: number | null;
+}
+export interface AgentOsApiDeps {
+    baseUrl?: string;
+    apiKey?: string;
+    fetchFn?: typeof fetch;
+}
+export declare function agentOsGetPlan(slug: string, planId: string, deps?: AgentOsApiDeps): Promise<AgentOsPlanGetPayload>;
+export declare function agentOsWritePlan(input: PersistPlanInput, deps?: AgentOsApiDeps): Promise<AgentOsWriteResult>;

package/dist/plan-persist/body-hash.d.ts

@@ -0,0 +1,3 @@
+/** Stable hash for readback verification (normalized trailing whitespace). */
+export declare function hashPlanBody(body: string): string;
+export declare function hashSummary(summary: string | null | undefined): string | null;

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

@@ -0,0 +1,7 @@
+import { type PersistPlanDeps } from "./persist.js";
+import type { DrainOutboxResult, PlanOutboxItem } from "./types.js";
+export declare function drainPlanOutbox(opts?: {
+    max?: number;
+    outboxId?: string;
+}, deps?: PersistPlanDeps): Promise<DrainOutboxResult>;
+export declare function loadOutboxById(outboxId: string): PlanOutboxItem | null;

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

@@ -0,0 +1,9 @@
+import type { PlanPersistFailureKind } from "./types.js";
+export declare class PlanPersistError extends Error {
+    readonly kind: PlanPersistFailureKind;
+    readonly httpStatus?: number;
+    constructor(kind: PlanPersistFailureKind, message: string, httpStatus?: number);
+}
+export declare function classifyHttpFailure(status: number, message: string): PlanPersistError;
+export declare function classifyFetchFailure(err: unknown): PlanPersistError;
+export declare function isRetryableFailure(kind: PlanPersistFailureKind): boolean;

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

@@ -0,0 +1,7 @@
+import type { PlanOutboxItem } from "./types.js";
+export declare function formatPlanOutboxHandoffBlock(item: PlanOutboxItem): string;
+export declare function extractPlanOutboxFromTask(task: Record<string, unknown>): {
+    outboxId?: string;
+    jsonPath?: string;
+    bodyPath?: string;
+} | null;

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

@@ -0,0 +1,2 @@
+import type { PersistPlanInput } from "./types.js";
+export declare function buildPlanPersistIdempotencyKey(input: PersistPlanInput): string;

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

@@ -0,0 +1,8 @@
+export type { PlanPersistUserStatus, PlanPersistOperation, PlanOutboxItem, PersistPlanInput, PersistPlanResult, DrainOutboxResult, } from "./types.js";
+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 { formatPlanOutboxHandoffBlock, extractPlanOutboxFromTask, } from "./handoff.js";
+export { isTmpOnlyPath, planOutboxDir } from "./paths.js";
+export { PlanPersistError } from "./errors.js";

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

@@ -0,0 +1,18 @@
+import type { PlanOutboxItem, PersistPlanInput } from "./types.js";
+export declare function listOutboxItems(): PlanOutboxItem[];
+export declare function findOutboxByIdempotencyKey(key: string): PlanOutboxItem | null;
+export declare function readOutboxItem(jsonPath: string): PlanOutboxItem | null;
+export declare function readOutboxBody(item: PlanOutboxItem): string;
+export declare function writeOutboxItem(input: PersistPlanInput, opts: {
+    lastError: string;
+    lastFailureKind: PlanOutboxItem["lastFailureKind"];
+    existing?: PlanOutboxItem;
+}): PlanOutboxItem;
+export declare function saveOutboxItem(item: PlanOutboxItem): void;
+export declare function archiveOutboxItem(item: PlanOutboxItem): void;
+export declare function outboxItemPaths(item: PlanOutboxItem): {
+    jsonPath: string;
+    bodyPath: string;
+};
+export declare function removeOutboxItem(item: PlanOutboxItem): void;
+export declare function outboxInputFromItem(item: PlanOutboxItem, body: string): PersistPlanInput;

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

@@ -0,0 +1,8 @@
+export declare function resolveKynverStateRoot(): string;
+export declare function planOutboxDir(): string;
+export declare function planOutboxArchiveDir(): string;
+export declare function ensurePlanOutboxDirs(): {
+    outboxDir: string;
+    archiveDir: string;
+};
+export declare function isTmpOnlyPath(filePath: string): boolean;

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

@@ -0,0 +1,10 @@
+import type { AgentOsApiDeps } from "./agentos-api.js";
+import { agentOsWritePlan } from "./agentos-api.js";
+import { verifyPlanReadback } from "./readback.js";
+import type { PersistPlanInput, PersistPlanResult } from "./types.js";
+export interface PersistPlanDeps extends AgentOsApiDeps {
+    /** When set, skip live HTTP (tests). */
+    writePlan?: typeof agentOsWritePlan;
+    verifyReadback?: typeof verifyPlanReadback;
+}
+export declare function persistPlan(input: PersistPlanInput, deps?: PersistPlanDeps): Promise<PersistPlanResult>;

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

@@ -0,0 +1,17 @@
+import { type AgentOsApiDeps } from "./agentos-api.js";
+import type { PlanPersistReadbackEvidence, PersistPlanInput } from "./types.js";
+export interface ReadbackExpectation {
+    planId: string;
+    title: string;
+    summary: string | null;
+    body: string;
+    bodyHash: string;
+    versionId?: string | null;
+    versionNumber?: number | null;
+}
+export declare function verifyPlanReadback(slug: string, expectation: ReadbackExpectation, deps?: AgentOsApiDeps): Promise<PlanPersistReadbackEvidence>;
+export declare function buildReadbackExpectation(input: PersistPlanInput, write: {
+    planId: string;
+    versionId: string | null;
+    versionNumber: number | null;
+}): ReadbackExpectation;

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

@@ -0,0 +1,91 @@
+/** User-facing persistence outcome — never imply AgentOS success from local files alone. */
+export type PlanPersistUserStatus = "persisted and read back" | "queued for retry" | "failed and needs action";
+export type PlanPersistOperation = "create" | "add_version" | "update_metadata";
+export type PlanOutboxQueueStatus = "queued" | "draining" | "archived" | "failed";
+export type PlanPersistFailureKind = "approval_guard" | "auth" | "network" | "server" | "tool_interruption" | "verification_failed" | "permanent";
+export interface PlanPersistSourceRefs {
+    model?: string;
+    source?: string;
+    [key: string]: unknown;
+}
+export interface PlanPersistReadbackEvidence {
+    planId: string;
+    currentVersionId: string | null;
+    versionNumber: number | null;
+    title: string;
+    summary: string | null;
+    bodyHash: string;
+    readAt: string;
+}
+export interface PlanOutboxItem {
+    id: string;
+    idempotencyKey: string;
+    operation: PlanPersistOperation;
+    agentOsSlug: string;
+    planId: string | null;
+    planSlug: string | null;
+    title: string;
+    summary: string | null;
+    /** Relative to outbox dir when body is large; inline when small. */
+    bodyPath: string;
+    bodyHash: string;
+    author: string | null;
+    model: string | null;
+    sourceRefs: PlanPersistSourceRefs | null;
+    changeSummary: string | null;
+    markCurrent: boolean | null;
+    createdAt: string;
+    updatedAt: string;
+    retryCount: number;
+    maxRetries: number;
+    lastError: string | null;
+    lastFailureKind: PlanPersistFailureKind | null;
+    queueStatus: PlanOutboxQueueStatus;
+    userStatus: PlanPersistUserStatus;
+    /** Set after a successful drain for audit. */
+    readbackEvidence: PlanPersistReadbackEvidence | null;
+}
+export interface PersistPlanInput {
+    operation: PlanPersistOperation;
+    agentOsSlug: string;
+    title: string;
+    body: string;
+    summary?: string | null;
+    planId?: string | null;
+    planSlug?: string | null;
+    changeSummary?: string | null;
+    author?: string | null;
+    model?: string | null;
+    sourceRefs?: PlanPersistSourceRefs | null;
+    markCurrent?: boolean;
+    maxRetries?: number;
+    /** When the immediate AgentOS/MCP write failed before reaching the server. */
+    immediateFailure?: {
+        kind: PlanPersistFailureKind;
+        message: string;
+    };
+    /** Optional path hint — `/tmp`-only paths must not count as durable persistence. */
+    bodyPathHint?: string;
+}
+export interface PersistPlanResult {
+    userStatus: PlanPersistUserStatus;
+    outboxId?: string;
+    outboxPath?: string;
+    bodyPath?: string;
+    planId?: string;
+    versionId?: string;
+    readbackEvidence?: PlanPersistReadbackEvidence;
+    lastError?: string;
+    idempotencyKey?: string;
+}
+export interface DrainOutboxResult {
+    processed: number;
+    succeeded: number;
+    stillQueued: number;
+    failed: number;
+    results: Array<{
+        outboxId: string;
+        userStatus: PlanPersistUserStatus;
+        lastError?: string;
+    }>;
+}

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

@@ -0,0 +1,3 @@
+export declare function runPlanPersist(args: Record<string, string | boolean>): Promise<void>;
+export declare function runPlanOutboxList(): Promise<void>;
+export declare function runPlanOutboxDrain(args: Record<string, string | boolean>): Promise<void>;

package/dist/plan-progress-daemon-sync.d.ts

@@ -0,0 +1,7 @@
+/** Push heartbeat blockers to the server orchestrator (deduped per worker). */
+export declare function syncActiveWorkerPlanProgress(runId: string, args: Record<string, string | boolean>): Promise<Array<{
+    worker: string;
+    phase: string;
+    ok: boolean;
+    skipped?: boolean;
+}>>;

package/dist/plan-progress-sync.d.ts

@@ -0,0 +1,21 @@
+export type PlanProgressSyncPhase = "worker_dispatched" | "worker_completed" | "heartbeat_blocker";
+export interface PlanProgressSyncArtifact {
+    branch?: string;
+    worktreePath?: string;
+    prUrl?: string;
+    headCommit?: string;
+    changedFiles?: string[];
+}
+export declare function syncPlanProgress(args: {
+    agentOsId: string;
+    taskId: string;
+    phase: PlanProgressSyncPhase;
+    blocker?: string;
+    artifact?: PlanProgressSyncArtifact;
+    baseUrl?: string;
+    secret?: string;
+}): Promise<{
+    ok: boolean;
+    status: number;
+    response: unknown;
+}>;