specrails-core 5.2.2 → 5.3.0

package/dist/installer/util/paths.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Paths the installer MUST NOT create, modify, or delete. These hold
+ * user / team state that survives re-runs (profile JSON authored by
+ * specrails-desktop, custom agents authored by the user). Breaking this
+ * contract silently destroys user work.
+ *
+ * Audited by vitest spec `reserved-paths.test.ts`.
+ */
+export declare const RESERVED_PATHS: readonly [".specrails/profiles/", ".claude/agents/custom-", ".kimi-code/skills/custom-", ".kimi-code/skills/rails/custom-"];
+/**
+ * Returns true when a repo-relative path falls inside a reserved
+ * region. Accepts both POSIX (/) and Windows (\) separators; the
+ * check normalises internally so callers can pass a value straight
+ * from `path.relative()` without worrying about host platform.
+ */
+export declare function isReservedPath(relPath: string): boolean;
+/**
+ * Joins segments and forces POSIX separators. Use when a generated
+ * string is destined for a cross-platform artefact (JSON manifest,
+ * YAML config) rather than the local filesystem.
+ */
+export declare function toPosix(...segments: string[]): string;
+/**
+ * Joins segments using the host platform's separator. Use when the
+ * result goes directly to `fs.*` / `child_process.*` calls.
+ */
+export declare function toNative(...segments: string[]): string;
+/**
+ * Repository-relative representation of an absolute path. Returns a
+ * POSIX-style path so callers can store it in manifests without OS
+ * contamination. If `absPath` is outside `repoRoot`, returns the
+ * original absolute path unchanged (POSIX-normalised).
+ */
+export declare function repoRelative(repoRoot: string, absPath: string): string;

package/dist/installer/util/prompts.d.ts

@@ -0,0 +1,23 @@
+export interface TextOptions {
+    message: string;
+    /** Value used when stdin is non-TTY. Absence here in non-TTY mode throws. */
+    default?: string;
+    /** Returns error message when invalid, or `true` / undefined when valid. */
+    validate?: (value: string) => string | true | undefined;
+}
+export declare function text(opts: TextOptions): Promise<string>;
+export interface ConfirmOptions {
+    message: string;
+    default?: boolean;
+}
+export declare function confirmYesNo(opts: ConfirmOptions): Promise<boolean>;
+export interface SelectOptions<T> {
+    message: string;
+    choices: Array<{
+        name: string;
+        value: T;
+        description?: string;
+    }>;
+    default?: T;
+}
+export declare function chooseOne<T>(opts: SelectOptions<T>): Promise<T>;

package/dist/installer/util/registry.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Shared artifact registry — the contract that lets specrails-core place,
+ * and specrails-desktop read, a repo's relocated artifacts OUTSIDE the repo,
+ * under `$HOME/.specrails/projects/<slug>/workspace`.
+ *
+ * Single source of truth: `$HOME/.specrails/registry.json`, an inspectable,
+ * schema-versioned JSON file keyed by the **canonical realpath of the repo**.
+ * specrails-desktop is the primary writer (a projection of its `desktop.sqlite`);
+ * specrails-core reads it and, when run standalone, allocates its own entry.
+ *
+ * Design contract: `docs/internals/global-artifacts-alignment-contract.md`
+ * (in the specrails-desktop repo). The slug algorithm, canonical-key rule,
+ * atomic-write rule and lock protocol here MUST stay byte-identical to the
+ * desktop-side implementation — the correctness of the cross-tool contract
+ * depends on both tools resolving the same repo to the same paths.
+ *
+ * Everything in this module is synchronous to fit the installer's sync flow.
+ */
+/** Registry schema version. A reader that sees a higher value MUST treat all
+ *  entries as absent (legacy fallback), never mis-parse. */
+export declare const REGISTRY_SCHEMA_VERSION = 1;
+/** Who owns/allocated an entry. Encodes the single-writer-at-a-time rule. */
+export type RegistrySource = 'desktop' | 'core-standalone';
+/** One repo's relocated-artifact locations. All paths are absolute and in the
+ *  host platform's native separator; consumers treat them as opaque. */
+export interface ProjectEntry {
+    /** The canonical realpath of the repo (mirror of the map key). */
+    repoPath: string;
+    /** Shared slug — MUST equal desktop.sqlite `projects.slug` for the same repo. */
+    slug: string;
+    /** `$HOME/.specrails/projects/<slug>/workspace` — root of all relocated artifacts. */
+    workspaceDir: string;
+    /** The dir core treats as its `.specrails`/install root instead of repoRoot (= workspaceDir). */
+    artifactRoot: string;
+    /** Always the repo (= repoPath); carries the `openspec/**` + worktree carve-outs. */
+    codeRoot: string;
+    /** Runtime-state base (agent-memory, pipeline-state, …). Injected as SPECRAILS_STATE_DIR. */
+    stateDir: string;
+    /** Absolute path to the relocated local-tickets.json. Injected as SPECRAILS_TICKETS_PATH. */
+    ticketsPath: string;
+    /** Absolute path to backlog-config.json (Jira read-only switch). Injected as SPECRAILS_BACKLOG_CONFIG_PATH. */
+    backlogConfigPath: string;
+    /** Relocated `.specrails/profiles/`. Injected as SPECRAILS_PROFILES_DIR. */
+    profilesDir: string;
+    /** Relocated `.specrails/plugins/` (desktop-only; present for inspectability). */
+    pluginsStateDir: string;
+    /** Relocated `.specrails/file-summaries/` (desktop-only). */
+    fileSummariesDir: string;
+    /** Installed providers; mirror of desktop.sqlite `projects.providers`. */
+    providers: string[];
+    /** providers[0]; mirror of desktop.sqlite `projects.provider`. */
+    primaryProvider: string;
+    /** The `specrails-version` pin (name/format frozen; only location moved). */
+    coreVersion?: string;
+    createdAt?: string;
+    lastInstallAt?: string;
+    /** Single-owner-at-a-time marker; governs reconciliation. */
+    source: RegistrySource;
+    /** desktop.sqlite projects.id when source='desktop', for robust repo-move re-link. */
+    desktopProjectId?: string;
+}
+/** On-disk shape of `registry.json`. */
+export interface RegistryFile {
+    schemaVersion: number;
+    generator?: string;
+    updatedAt?: string;
+    /** Map: canonical-repo-key -> ProjectEntry. */
+    projects: Record<string, ProjectEntry>;
+}
+/** The flattened result both tools consume. */
+export interface Resolution {
+    /** Normalized map key. */
+    key: string;
+    repoPath: string;
+    slug: string;
+    workspaceDir: string;
+    artifactRoot: string;
+    codeRoot: string;
+    stateDir: string;
+    ticketsPath: string;
+    backlogConfigPath: string;
+    profilesDir: string;
+    pluginsStateDir: string;
+    fileSummariesDir: string;
+    providers: string[];
+    primaryProvider: string;
+    source: RegistrySource | 'legacy';
+    /** True when there is no registry entry and we fell back to the in-repo layout. */
+    isLegacy: boolean;
+}
+export interface ResolveOptions {
+    /** When true, allocate + persist an entry if none exists. Readers pass false. */
+    allocate?: boolean;
+    /** Who is allocating (only consulted when allocate=true). Default 'core-standalone'. */
+    allocator?: RegistrySource;
+    /** Override `$HOME` (tests). Default `os.homedir()`. */
+    home?: string;
+    /** Providers to record on allocation. Default ['claude']. */
+    providers?: string[];
+    coreVersion?: string;
+    desktopProjectId?: string;
+    /** Override timestamp (tests). */
+    now?: string;
+}
+/**
+ * Slug derivation — byte-identical to specrails-desktop's `slugify`
+ * (`server/desktop-router.ts`). Do not "improve" it; parity is the contract.
+ */
+export declare function slugify(name: string): string;
+/** `$HOME` for the registry, overridable for tests. */
+export declare function resolveHome(home?: string): string;
+/** Absolute path to `registry.json`. */
+export declare function registryPath(home?: string): string;
+/**
+ * Absolute path to the versioned framework store
+ * (`<home>/.specrails/framework`). The bundled-framework split materializes the
+ * provider-invariant subtree to `<frameworkDir>/<version>/<providerDir>/` once
+ * and every workspace symlinks `<frameworkDir>/current/<providerDir>/...`. Shares
+ * the SAME home as the registry so framework, registry, and workspaces co-locate
+ * (and tests pinning `SPECRAILS_REGISTRY_HOME` redirect all three together).
+ */
+export declare function frameworkRoot(home?: string): string;
+/** Absolute path to the advisory lock file. */
+export declare function lockPath(home?: string): string;
+/** `fs.realpathSync` that falls back to the resolved-but-unreal path on error
+ *  (the path may not exist yet, or be on a volume that rejects realpath). */
+export declare function realpathSafe(abs: string): string;
+/** Case-fold the key on case-insensitive platforms (macOS, Windows) so two
+ *  spellings of the same path map to one entry. The stored `repoPath` keeps
+ *  its canonical case; only the index key is folded. */
+export declare function normalizeKey(canon: string): string;
+/** Canonical repo path: resolve to absolute, then realpath (collapses symlinks). */
+export declare function canonicalizeRepoPath(repoPathInput: string): string;
+/** The per-project sub-path layout under a workspace dir. Single source of the
+ *  layout so writer and (allocation) reader never disagree. */
+export declare function workspaceLayout(home: string, slug: string, canon: string, primaryProvider?: string): Omit<ProjectEntry, 'providers' | 'primaryProvider' | 'coreVersion' | 'createdAt' | 'lastInstallAt' | 'source' | 'desktopProjectId'>;
+/** The in-repo layout, used when there is no registry entry (legacy fallback). */
+export declare function legacyResolution(canon: string): Resolution;
+/** Flatten a stored entry into a Resolution. */
+export declare function entryToResolution(key: string, entry: ProjectEntry): Resolution;
+/**
+ * Total, fail-open read. A missing file, a parse error, or a `schemaVersion`
+ * greater than we understand all yield an empty registry, so a caller treats
+ * it as "no entry" and (if allocating) writes a fresh, understood entry rather
+ * than crashing. Biases toward availability over strict consistency — correct
+ * for a local, inspectable file.
+ */
+export declare function readRegistryOrEmpty(home?: string): RegistryFile;
+/** Write `data` to `filePath` atomically: temp file in the same dir, fsync,
+ *  rename. A reader (even without the lock) only ever sees a complete old or
+ *  new file — the lock serialises writers, the rename protects readers. */
+export declare function atomicWrite(filePath: string, data: string): void;
+/**
+ * Run `fn` while holding an advisory lock over the registry. Mutual exclusion
+ * is an exclusive-create lock file (`open(..., 'wx')`) with bounded spin-retry
+ * and stale-lock breaking (a lock whose mtime exceeds the TTL is reclaimed —
+ * covers a crashed writer). Read-only callers never take the lock.
+ */
+export declare function withFileLock<T>(home: string | undefined, fn: () => T): T;
+/** Deterministic slug allocation: basename-derived, `-N` dedup suffix. Both
+ *  tools implement this identically so they only ever diverge on the suffix,
+ *  which read-before-allocate resolves. */
+export declare function allocateSlug(canon: string, existing: ReadonlySet<string>): string;
+/**
+ * The shared resolver both tools run. Given a repo path, returns where that
+ * repo's artifacts live. With `allocate:true`, creates + persists an entry when
+ * none exists (under the lock, with a re-read double-check); readers pass
+ * `allocate:false` and fall back to the in-repo legacy layout when absent.
+ */
+export declare function resolveArtifacts(repoPathInput: string, opts?: ResolveOptions): Resolution;
+/** Commit version metadata only after successful materialization and assembly.
+ * Desktop-owned entries remain the host's responsibility; never claim ownership.
+ */
+export declare function recordSuccessfulInstall(repoPath: string, opts: Pick<ResolveOptions, 'home' | 'providers' | 'coreVersion' | 'now'>): void;

package/dist/installer/util/template.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Small in-house template renderer. Replaces the bash heredocs the
+ * retired install.sh / update.sh used to emit manifests and config
+ * files.
+ *
+ * Syntax (intentionally minimal):
+ *   ${VAR_NAME}                  — value interpolation
+ *   {{#if FLAG}}block{{/if}}     — conditional block, rendered when
+ *                                  FLAG is truthy in the context
+ *   {{#ifnot FLAG}}block{{/ifnot}} — conditional block when FLAG is falsy
+ *
+ * Nested blocks are NOT supported. If a template outgrows this
+ * capability we switch to mustache — but every heredoc we've audited
+ * fits inside these three forms.
+ */
+export type TemplateContext = Record<string, string | boolean | number | null | undefined>;
+/**
+ * Renders `template` by evaluating its directives against `context`.
+ * Missing interpolation variables render as the empty string rather
+ * than throwing — the bash scripts behaved the same way (`${X:-}` in
+ * a heredoc). Unknown flags in an `{{#if}}` are treated as falsy.
+ */
+export declare function render(template: string, context: TemplateContext): string;

package/docs/README.md

@@ -18,6 +18,7 @@ Welcome to the SpecRails docs. This guide will take you from zero to a fully aut
 | [Plugin Architecture](plugin-architecture.md) | Plugin vs scaffold, what lives where, how updates work |
 | [Agents](agents.md) | Every agent explained — role, when it runs, why it exists |
 | [Workflows & Commands](workflows.md) | How to use `/specrails:implement`, `/specrails:get-backlog-specs`, and more |
+| [Programmatic Agent Runtime](agent-runtime.md) | LangGraph phases, Claude/Codex/Gemini/Kimi and local providers, CLI/API configuration, recovery and host delivery |
 | [Customization](customization.md) | Adapt agents, rules, personas, and conventions to your project |
 | [Updating](updating.md) | Keep SpecRails up to date without losing your customizations |
 

package/docs/agent-runtime.md

@@ -0,0 +1,268 @@
+# Programmatic agent runtime
+
+Core can execute implementation as a local TypeScript workflow:
+
+```text
+architect → developer → verify → reviewer → archive
+    │           ↑          │         │
+    │           └──────────┴─────────┘  bounded corrections
+    └─ investigate once, then ask (or proceed on stated assumptions)
+```
+
+The workflow is a [LangGraph](https://docs.langchain.com/oss/javascript/langgraph/overview) state graph. LangGraph owns the traversal, the typed state and its reducers, the checkpoint history, dynamic interrupts (approvals and questions) and time travel; Core owns the role instructions, the structured artifacts, the verification subprocesses, the acceptance evidence, the receipts, budgets, leases and interrupted-write recovery. Provider adapters execute one role; they do not invoke a platform's implementation prompt or skill.
+
+The developer role has the same autonomy the legacy Implement step had: it edits files and runs commands inside its CLI's own sandbox (Claude `--tools default --dangerously-skip-permissions` with nested agents and skills disallowed, Codex `workspace-write`, Gemini `--yolo`, Kimi print mode), so it can run the project's tests before handing off. Architect and reviewer roles stay read-only. Claude roles load only project settings (`--setting-sources project,local`), so `CLAUDE.md` and `.claude/rules` apply while the user's global memory and plugins do not.
+
+This page describes the current source implementation, **runtime API 1**, workflow version 3, checkpoint envelope format 2. An older published Core package can have the same major version and lack this export. Build the paired checkout when developing this feature; do not assume `@latest` contains unreleased changes.
+
+## Requirements and ownership
+
+- Node.js **20.19.0+** and Git on macOS or Windows. Individual provider CLIs may require a newer Node release.
+- Installed and authenticated Claude, Codex, Gemini or Kimi CLIs for whichever roles use them; alternatively, a reachable OpenAI-compatible endpoint with tool support.
+- A frozen execution context and a new change name. Verification commands are optional: configured commands run as given, the architect proposes the project's own checks for repositories that have none, and a repository with no automated check is admitted and recorded as unverified in the receipt.
+- `ownership.git: "host"`. The runtime implements and archives; its caller owns worktrees, commits, pushes, pull requests and backlog delivery. It rejects Core-owned Git delivery rather than reporting success while shipping remains pending.
+
+Specrails, LangGraph and the runtime infrastructure are open source and require no paid orchestration service, tracing backend, Python daemon or database server. Model inference, hardware and existing provider CLIs retain their own costs and license terms. No model download or provider subscription is included.
+
+## Configure providers and roles
+
+Save this as `.specrails/agent-runtime.json`, adapting the verification command to your repository:
+
+```json
+{
+  "schemaVersion": 1,
+  "enabled": true,
+  "providers": [
+    { "id": "claude", "kind": "cli", "cli": "claude" },
+    { "id": "codex", "kind": "cli", "cli": "codex" },
+    { "id": "gemini", "kind": "cli", "cli": "gemini" },
+    { "id": "kimi", "kind": "cli", "cli": "kimi" },
+    {
+      "id": "local",
+      "kind": "openai-compatible",
+      "baseUrl": "http://127.0.0.1:11434/v1"
+    }
+  ],
+  "agents": {
+    "architect": { "provider": "claude", "maxTurns": 24 },
+    "developer": { "provider": "codex", "maxTurns": 24 },
+    "reviewer": { "provider": "gemini", "maxTurns": 24 }
+  },
+  "limits": { "maxAttempts": 3, "timeoutMs": 900000 },
+  "verification": [
+    { "repositoryId": "app", "command": "node", "args": ["--test"] }
+  ],
+  "review": { "minScore": 80, "aspects": { "security": 85 } },
+  "architect": { "onLowConfidence": "ask" },
+  "approvalBeforeArchive": false
+}
+```
+
+`verification` may be an empty array. At run time Core builds the effective plan from the configured commands plus the architect's proposals for uncovered repositories; the plan is frozen in the graph state and reused by every verification and resume. When the plan covers no repository at all, the run still passes through task completion and review, and the receipt lists those repositories under `unverifiedRepositories`.
+
+`review` tightens the review gate. Core's own gate is the floor: overall score at least 70, `security` at least 75, every other aspect at least 60. A lower value is rejected by validation, because the pipeline journal enforces the floor regardless of configuration. The reviewer is told the effective thresholds.
+
+`architect.onLowConfidence` decides what happens when the architect still reports low confidence after its investigation pass (see [Questions and approvals](#questions-and-approvals)): `ask` (default) pauses the run with the architect's question; `proceed` continues on the assumptions the architect stated, recording `design-confidence.json` as `medium` with `assumed: true` and the original `reportedConfidence`.
+
+Set any role's `provider` to `kimi` to use Kimi. A CLI role's optional `model` is passed to that provider; omitting it uses the CLI's default. Provider IDs are aliases, so you can configure several endpoints or replace an executor without changing workflow code.
+
+To use the local endpoint, set the desired role to `{"provider":"local","model":"your-installed-model-id","maxTurns":24}`. The endpoint must support `POST <baseUrl>/chat/completions`, OpenAI-style function tool calls and a final assistant result. Its model must actually be able to use these tools; a chat-only endpoint is insufficient for the developer role. The example port is a placeholder for your own running server.
+
+For an authenticated endpoint, add `"apiKeyEnv":"MY_MODEL_API_KEY"` to its provider configuration and set that variable in the process launching Core. Omit `apiKeyEnv` when no key is required. URLs cannot contain credentials, query parameters or fragments. Verification commands inherit process credentials; do not put secrets into their persisted `env` overrides.
+
+The configuration schema is [agent-runtime.schema.json](../schemas/agent-runtime.schema.json). `validateRuntimeConfig()` also checks relationships such as role-to-provider references and the review floors. Runtime configuration is separate from the existing [profile v1 schema](../schemas/profile.v1.json); it does not translate legacy profile routing into programmatic phases.
+
+## Run from the CLI
+
+Use an installed Core package that exposes runtime API 1. For a source checkout, run `npm ci` and `npm run build` in Core, then replace `specrails-core` below with `node /path/to/specrails-core/bin/specrails-core.mjs`.
+
+Desktop constructs the execution context automatically. For standalone use, create a context JSON with absolute paths:
+
+```json
+{
+  "schemaVersion": 1,
+  "runId": "feature-navigation-01",
+  "backlogRoot": "/absolute/path/to/app",
+  "artifactRoot": "/absolute/path/to/app",
+  "artifactRepositoryId": "app",
+  "repositories": [
+    { "id": "app", "name": "App", "path": "/absolute/path/to/app" }
+  ],
+  "ownership": { "git": "host", "backlog": "host", "worktrees": "host" },
+  "specs": [
+    {
+      "id": "navigation",
+      "title": "Keyboard navigation",
+      "description": "Implement the agreed keyboard navigation behavior.",
+      "repositoryIds": ["app"],
+      "acceptanceCriteria": ["Every setting can be reached using the keyboard."]
+    }
+  ]
+}
+```
+
+On Windows use absolute paths such as `C:/work/app` or JSON-escaped `C:\\work\\app`. Repository paths must identify existing Git repositories. Multi-repository contexts list every selected repository; `artifactRoot` must be the path of `artifactRepositoryId`. Choose a fresh, portable run ID and a new kebab-case change name. Every acceptance criterion (or the description when a spec has none) becomes a frozen requirement the reviewer must certify.
+
+```sh
+specrails-core runtime api
+specrails-core runtime validate --config .specrails/agent-runtime.json
+specrails-core runtime run --context .specrails/context.json --config .specrails/agent-runtime.json --change keyboard-navigation
+specrails-core runtime status --context .specrails/context.json
+specrails-core runtime resume --context .specrails/context.json --answer "Keep the existing shortcut map"
+specrails-core runtime resume --context .specrails/context.json --approve archive
+```
+
+The commands work in macOS shells and PowerShell; quote paths and answers containing spaces. Verification uses `command` plus an `args` array, not a shell command string. Prefer portable Node/npm commands over Bash scripts when the project supports Windows.
+
+Run and resume emit JSON lines: `workflow-event` (the durable ledger events), `agent-event` (role narration and tool activity), `verification-output`, `span` (one per finished role attempt, with `traceId`, `spanId`, timing, status and usage, ready for an OpenTelemetry bridge) and a final `runtime-result`. The direct runtime entry point is `dist/agent-runtime/cli.js`; it also emits JSON errors. The main package CLI can report command-validation errors on stderr. Exit codes are `0` for success, `2` for a pause (approval or question pending), and `1` for failure, blocking or cancellation. A successful Core result means implementation, verification, review, acceptance evidence and archive completed; host delivery remains separate.
+
+`runtime api` returns `{type:"runtime-api",apiVersion:1,coreVersion:"..."}` without invoking providers. Hosts can send a JSON configuration through stdin to `runtime validate --stdin` (maximum 2 MiB), avoiding temporary files and platform-specific shell quoting. It is mutually exclusive with `--config`. Use `runtime status --context <file> --compact` for process/UI integration: it retains the run and trace identities, phase status and visits, `pendingApproval`, `pendingQuestion`, usage, the completion verdict and the acceptance summary while omitting accumulated outputs, history and frozen context. Omit `--compact` for full inspection.
+
+## Questions and approvals
+
+The graph pauses through LangGraph interrupts; the host resumes it with the matching answer.
+
+- **Low design confidence.** When the architect reports `low`, Core first asks the same architect session to investigate the code once more and decide from evidence. If confidence is still low, the run pauses with the architect's single blocking question (`pendingQuestion`), the draft proposal is left on disk for inspection, and `resume --answer <text>` re-runs the architect with the answer as authoritative input. With `architect.onLowConfidence: "proceed"` the run continues on the stated assumptions instead of pausing.
+- **Archive approval.** With `approvalBeforeArchive: true` the run pauses before archive (`pendingApproval`); `resume --approve archive` grants it. The default is no approval, so a fully autonomous run implements, verifies, reviews and archives without a human in the loop.
+
+A resumed node collects its answer before doing any work, so the pass that asked the question is never repeated. Approvals and answers are persisted; a granted approval survives interruption, but invalidated candidate evidence clears it.
+
+## Recovery and durable state
+
+State lives below `<backlogRoot>/.specrails/pipeline/<runId>/`:
+
+| File | Purpose |
+| --- | --- |
+| `state.json` and `receipts/` | Authoritative Core gates, verification and acceptance evidence |
+| `agent-runtime-request.json` | Frozen CLI change name and runtime configuration |
+| `agent-workflow/<runId>/checkpoint.json` | One atomic envelope: the host ledger (attempts, receipts, usage, ordered events, pending interrupts) and the complete LangGraph checkpoint history |
+| `agent-workflow/<runId>/.lease/` | Exclusive runtime process ownership |
+
+Resume uses the saved configuration and change. It rejects a different frozen input, Core/instruction identity or workflow definition. Valid completed phases are retained; stale evidence invalidates the affected phase and everything declared after it, and the graph travels back in time to the checkpoint taken right before that phase last ran, so its predecessors' state is exactly what it saw then. The ledger is authoritative for which node runs next: if LangGraph's own position disagrees after a crash, traversal follows the ledger. Once archived, changed evidence requires a new run.
+
+Correction loops stay cheap: when verification or review sends work back, the developer's previous provider session is resumed with a short correction prompt (Claude `--resume`, Codex `exec resume`, Gemini `--resume`, Kimi `--session`), so the code it wrote and the reasons behind it are already in context. If the session is gone the developer starts a fresh full turn with the same feedback. Unchecked tasks in `tasks.md` are returned to the developer as feedback, not treated as a workflow failure. A run blocked at `limits.maxAttempts` can be resumed explicitly: the resume grants a fresh attempt budget and transition ceiling; visits and history keep the complete record.
+
+Architect and reviewer replies are validated against a JSON Schema (Claude `--json-schema`, Codex `--output-schema`; other providers are parsed leniently, accepting fenced or prefixed objects). The developer finishes with a structured summary (files, tests, verification run, incomplete tasks) validated the same way; a provider that returns prose instead is recorded as such rather than repaired. An unusable architect or reviewer reply gets one repair turn inside the same session before the phase fails.
+
+```sh
+# Retry a reported failure with the same frozen configuration.
+specrails-core runtime resume --context .specrails/context.json
+
+# After inspecting partial edits, explicitly allow an interrupted write to run again.
+specrails-core runtime resume --context .specrails/context.json --recover developer
+
+# Recheck evidence explicitly; this also invalidates downstream review/archive.
+specrails-core runtime resume --context .specrails/context.json --invalidate verify
+```
+
+Inspect the saved phase and worktree before using `--recover`; it authorizes repeating an effect whose completion was not durably recorded. Dead local process leases can be reclaimed. Live, remote or unverifiable leases are never silently stolen. Do not delete a lease while its process may still be running.
+
+Cancellation propagates to owned provider and verification processes. Programmatic callbacks must cooperate with `AbortSignal` and finish subprocess cleanup before returning; the engine retains its lease until they settle. A write step that settles after cancellation is recorded as interrupted and requires explicit recovery.
+
+## Acceptance evidence
+
+Core 5.2 requires acceptance evidence before a change can be archived. The runtime produces it without a separate role:
+
+- The reviewer receives every frozen acceptance criterion with stable coordinates (`specId`, `criterionIndex`) and certifies each one as `met`, `exception`, `blocked` or `pending` with concrete evidence. A reviewer may only accept a non-material exception itself; material scope changes stay `blocked`.
+- Core records the verification commands it actually ran as required checks (passed or failed by exit code, with the receipt id as evidence), repositories admitted without a check as unavailable checks, and the reviewer's own inspections as supplementary, never required, checks.
+- The report is validated against the frozen scope inside the reviewer turn (a malformed report gets the repair turn), then bound to the exact candidate before the reviewer verdict is recorded. Unresolved requirements or a failed required check block review and archive; the CLI status exposes the reasons.
+
+## Budgets and provider capability differences
+
+| Setting | Behavior |
+| --- | --- |
+| `agents.<role>.maxTurns` | Bounded role/tool interaction, default 24; provider transports enforce their available turn/tool events |
+| `limits.maxAttempts` | Maximum development visits per invocation, including correction cycles, default 3; an explicit resume starts a fresh budget |
+| `limits.timeoutMs` | Workflow duration limit and provider timeout; default provider timeout is 15 minutes when omitted |
+| `limits.maxTokens` | Rejects missing required usage or an observed overrun; CLI accounting may arrive only after a call |
+| `limits.maxCostUsd` | Accepted by the built-in Claude executor through its native dollar limit; rejected by built-in Codex, Gemini, Kimi and OpenAI-compatible executors |
+
+Do not configure `maxCostUsd` for a mixed-provider run unless every selected custom executor can enforce the requested cap. An observed token limit cannot guarantee that an opaque CLI stops before spending those tokens. Provider spend is accounted the moment each call returns, so a pause or failure after a call never loses it. Unknown usage stays `null`; known spend is tracked as a lower bound, never fabricated as zero. Local endpoints can report zero cost, but absent billing data remains unknown.
+
+Kimi read-only roles use an enforced custom agent when the CLI exposes `--agent-file`; the Kimi 0.27 fallback uses ACP plan mode with scoped reads and denied writes/terminal operations. Unsupported ACP modes or multi-repository capabilities fail explicitly. Kimi lacks authoritative token accounting, so its built-in executor rejects token and dollar caps. Configure another provider for a role when its installed Kimi version cannot expose the required repository scope.
+
+Gemini architect/reviewer roles require a CLI that advertises `--admin-policy` (verified with Gemini 0.49). Core supplies a temporary admin policy allowing only file reads, listing, glob and grep; all other tools are denied, including shell, writes and mode changes. This policy applies even if user settings disable plan mode or previously approve write tools. Gemini ignores per-run admin policies when system policy files exist, so Core rejects those managed environments before invoking a read-only role; select another provider for these roles or arrange a compatible environment with the system administrator. Older Gemini versions without this policy capability also fail explicitly. Gemini developer roles retain their existing `auto_edit` execution.
+
+## Embed and extend
+
+Import the public ESM entry point; TypeScript declarations are included:
+
+```ts
+import { readFileSync } from 'node:fs'
+import { runCoreWorkflow, validateRuntimeConfig } from 'specrails-core/agent-runtime'
+
+const context = JSON.parse(readFileSync('.specrails/context.json', 'utf8'))
+const config = validateRuntimeConfig(JSON.parse(readFileSync('.specrails/agent-runtime.json', 'utf8')))
+const controller = new AbortController()
+const state = await runCoreWorkflow({
+  context, config, change: 'keyboard-navigation', signal: controller.signal,
+  onEvent: event => process.stdout.write(JSON.stringify(event) + '\n'),
+  onSpan: span => process.stdout.write(JSON.stringify(span) + '\n'),
+})
+console.log(state.status, state.nextStep, state.pendingQuestion?.question)
+```
+
+Programmatic hosts retain their input/config and supply the same values with `resume: true`, plus `approve`, `answer`, `recoverInterrupted` or `invalidate` as needed. The CLI additionally creates the frozen request file for you.
+
+Register an executor directly to add a provider in code. This example registers a private local endpoint with no CLI installation:
+
+```ts
+import {
+  ExecutorRegistry, OpenAICompatibleExecutor, runCoreWorkflow,
+  type RuntimeConfig,
+} from 'specrails-core/agent-runtime'
+
+const registry = new ExecutorRegistry().register('on-prem',
+  new OpenAICompatibleExecutor({
+    id: 'on-prem', kind: 'openai-compatible', baseUrl: 'http://127.0.0.1:8080/v1',
+  }),
+)
+const config: RuntimeConfig = {
+  schemaVersion: 1, enabled: true, providers: [],
+  agents: {
+    architect: { provider: 'on-prem', model: 'your-installed-model-id' },
+    developer: { provider: 'on-prem', model: 'your-installed-model-id' },
+    reviewer: { provider: 'on-prem', model: 'your-installed-model-id' },
+  },
+  verification: [{ repositoryId: 'app', command: 'node', args: ['--test'] }],
+}
+// context is the frozen JSON object from the preceding example.
+await runCoreWorkflow({ context, config, registry, change: 'local-navigation' })
+```
+
+A custom executor implements `AgentExecutor.execute(request): Promise<AgentResult>`. The request contains role, central instructions, allowed roots, model, limits and signal. Return final text and honest `{inputTokens, outputTokens, costUsd}` usage; use `null` for unavailable values. The executor must enforce role permissions and supported limits, own its tool/process cleanup, and throw on incomplete results. `createExecutorRegistry(config, {executors: {alias: executor}})` can replace or supplement configured providers.
+
+An optional, side-effect-free `validateLimits({maxTokens, maxCostUsd})` method rejects unsupported limits before any role runs. Built-in executors provide this preflight; custom registrations own their capabilities. Core also validates the complete verification command plan against the frozen repository scope before creating a run or invoking providers.
+
+For a different host workflow, use `runWorkflow()` with a LangGraph state schema and typed nodes:
+
+```ts
+import { Annotation } from '@langchain/langgraph'
+import { runWorkflow } from 'specrails-core/agent-runtime'
+
+const State = Annotation.Root({ notes: Annotation<string[]>({ reducer: (a, b) => [...a, ...b], default: () => [] }) })
+await runWorkflow<typeof State.State>({
+  directory, runId, input: { change }, workflow: {
+    id: 'my-host', version: '1', schema: State, entry: 'plan',
+    nodes: {
+      plan: { ends: ['build'], run: async () => ({ status: 'succeeded', update: { notes: ['planned'] } }) },
+      build: { effect: 'write', ends: ['plan'], run: async (state, context) => {
+        context.reportUsage({ costUsd: 0.1, inputTokens: 10, outputTokens: 5 })
+        if (state.notes.length < 2) return { status: 'succeeded', next: 'plan' }
+        context.interrupt({ kind: 'approval', reason: 'Ship it?' })
+        return { status: 'succeeded', next: null }
+      } },
+    },
+  },
+})
+```
+
+Each node declares its `effect`, optional retry bounds, its possible successors (`ends`) and `run(state, context)`. A result supplies `status`, an optional graph `update` (merged through the schema's reducers), an optional ledger `output` and an optional `next` for conditional routing; `null` completes the workflow. Node names must not collide with state channel names. Nodes pause with `context.interrupt()` and report provider spend with `context.reportUsage()` as it happens. Write retries require `retrySafe: true`; interrupted writes still require explicit recovery. `readWorkflowState(directory, runId)` is read-only. Observer exceptions cannot replay a committed step. The Core nodes themselves are exported as `coreNodes(deps)` for hosts that want to reuse a phase inside another graph.
+
+## Tools, specifications and compatibility
+
+The OpenAI-compatible tool executor exposes scoped file listing/reading and developer-only writing. It rejects traversal, symlink escapes and protected runtime metadata. It has no model-accessible shell tool; only the host's configured verification commands run as subprocesses. This is a tool policy, not an operating-system sandbox for arbitrary custom executors or external CLIs.
+
+Architect and reviewer responses are structured JSON. The architect's `specs[].content` is the **complete intended main specification**, including unchanged requirements. Archive replaces `openspec/specs/<name>/spec.md` with that reviewed document. It does not interpret a partial OpenSpec delta as a merge instruction. The developer may update task checkboxes, but changing approved design, task descriptions or specification content invalidates the gates.
+
+Legacy provider workflows and profile v1 remain available. Missing/disabled runtime configuration keeps Desktop's legacy path; an admitted programmatic run remains bound to its frozen runtime request even if the project's settings are later disabled. See the [integration contract](../integration-contract.json) for runtime API and artifact paths, and Desktop's programmatic runtime guide for release pairing and continuation/delivery behavior.