specrails-core 5.2.3 → 5.4.0

package/dist/installer/util/install-transaction.d.ts

@@ -0,0 +1,29 @@
+export declare const frameworkLifecycleLockPath: (frameworkDir: string) => string;
+export declare function withFrameworkLifecycleLock<T>(frameworkDir: string, apply: () => T | Promise<T>): Promise<T>;
+/**
+ * A surface the transaction protects.
+ *
+ * `snapshotContents: false` marks a surface whose CONTENTS must not be copied:
+ * the versioned framework store, which `installFramework` already rebuilds from
+ * a content-hash stamp and stages through a temp directory. Rollback still
+ * removes such a surface when the install CREATED it, and leaves a pre-existing
+ * one exactly as it stands — copying it bought no safety and cost a full copy of
+ * the framework store on every install.
+ */
+export type ProtectedSurface = string | {
+    path: string;
+    snapshotContents: boolean;
+};
+/** Snapshot only installer-owned surfaces; never follow links into a shared framework.
+ * Backups survive a failed rollback and their location is reported for recovery.
+ *
+ * Snapshotting requires NO filesystem privilege: links are recorded by target
+ * rather than recreated (see `snapshotTree`), so a protected surface that is —
+ * or contains — a Windows junction no longer fails the install on an account
+ * without SeCreateSymbolicLinkPrivilege.
+ */
+export declare function withInstallRollback<T>(paths: ProtectedSurface[], apply: () => Promise<T>): Promise<T>;
+export declare function compareCoreVersions(left: string, right: string): number | null;
+/** Refuse an implicit downgrade. Explicit swap-current is the rollback interface. */
+export declare function assertNoCoreDowngrade(current: string | null, target: string): void;
+export declare function currentFrameworkVersion(frameworkDir: string): string | null;

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

@@ -0,0 +1,31 @@
+/**
+ * Coloured output helpers for the installer. The emoji prefixes match
+ * what the retired bash scripts printed (`✓ ⚠ ✗ →`) so existing user
+ * bug reports and screenshots still read the same.
+ *
+ * The logger writes to stdout by default; callers may override via
+ * {@link setLoggerStreams} (useful in tests that capture output).
+ */
+interface Streams {
+    out: NodeJS.WritableStream;
+    err: NodeJS.WritableStream;
+}
+export declare function setLoggerStreams(next: Partial<Streams>): void;
+/** Restore logger to process.stdout/stderr. */
+export declare function resetLoggerStreams(): void;
+/** Section heading — bold, no prefix, leading blank line. */
+export declare function step(title: string): void;
+/** Success line. Prefix: `  ✓ ` in green. */
+export declare function ok(msg: string): void;
+/** Warning line. Prefix: `  ⚠ ` in yellow. */
+export declare function warn(msg: string): void;
+/** Failure line, routed to stderr. Prefix: `  ✗ ` in red. */
+export declare function fail(msg: string): void;
+/** Info line. Prefix: `  → ` in blue. */
+export declare function info(msg: string): void;
+/** Print a fatal error and its hint, routed to stderr. */
+export declare function fatal(message: string, hint?: string): void;
+/** Primitive write for cases where the caller owns formatting. */
+export declare function rawOut(text: string): void;
+export declare function rawErr(text: string): void;
+export {};

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-efficiency.md

@@ -0,0 +1,65 @@
+# Efficient programmatic implementation
+
+New runs use workflow 5 and instructions 7. Architect, developer and reviewer keep their official OpenSpec workflow: fast-forward, apply and verify. Verification remains deterministic Core execution, not a fourth AI agent. Custom role text does not replace the mandatory scope, response or OpenSpec protocol.
+
+## Configuration
+
+Optional schema-version-1 settings:
+
+```json
+{
+  "efficiency": {
+    "schemaVersion": 1,
+    "contextMode": "incremental",
+    "reviewMode": "incremental",
+    "planning": "proportional",
+    "acceptDeveloperChecks": true,
+    "verification": { "maxConcurrency": 1 }
+  }
+}
+```
+
+These defaults are normalized once at admission and frozen. `full` disables the corresponding adaptive policy. Incremental context requires a compatible session and a transport that explicitly guarantees continuation. Built-in CLI transports currently report continuation as unknown; stateless API and Kimi transports cannot receive a partial packet. They receive full context. A smaller prompt in the offline continuation fixture does **not** imply the same saving on every provider.
+
+Each role optionally accepts `effort` and one `escalation: { model, effort? }` within the same provider. Query actual installed support with `specrails-core runtime capabilities --config config.json`; this never runs inference. Unknown effort support rejects an explicit value at admission. Omitting effort leaves the provider default. No economic tier is selected automatically.
+
+Architect escalation is limited to the existing deepen pass. Developer escalation can begin on the third permitted candidate, after two failed outcomes; it adds no attempt to the configured limit. Reviewer escalation repairs malformed responses only, never a valid code rejection. Selected tiers and role session identities persist across interruption. All calls, including repairs, consume the existing budgets.
+
+## Checks and evidence
+
+Host and architect checks form an immutable baseline. Developers can add up to 20 checks per response, with at most 100 effective checks. Reusing a developer key replaces that addition's active revision; omitted additions remain required. A harness contains at most eight UTF-8 source files, 64 KiB each and 256 KiB per proposal. Sources live outside delivery under the run's state directory, not in the product repository. The runtime expands a structured command and exports `SPECRAILS_CHECK_REPO_ROOT` for locating repository files.
+
+Receipts, acceptance and archive approval bind the candidate and complete verification plan. Source changes, interrupted checks or a newer failure cannot reuse an older green result. A nonterminal continuation rechecks and asks the reviewer to certify the current acceptance criteria; terminal reads do not execute checks. Previously granted archive consent only survives when the candidate, plan and acceptance decisions remain identical.
+
+Checks default to `policy.reuse: "never"`. Host-only `snapshot-local` reuse requires explicit deterministic/read-only declarations, complete input/toolchain/dependency contents and a proven executable identity. Ignored installed dependencies must be declared; an unchanged lockfile is insufficient. Unknown inputs rerun. Concurrency defaults to one, with a maximum of four. Only contiguous checks in the same host-declared independence group, on distinct repositories with explicit nonoverlapping resources, run together. Missing resources mean unknown; an explicit empty array means no shared resources.
+
+Read recorded evidence without invoking agents:
+
+```sh
+specrails-core runtime evidence --context desktop-context.json --limit 25
+specrails-core runtime evidence --context desktop-context.json --id EVIDENCE_ID --section stdout
+specrails-core runtime evidence --context desktop-context.json --id EVIDENCE_ID --section source --source-id SOURCE_ID
+```
+
+List responses discover opaque evidence/source IDs and bound pagination cursors. Output pages are bounded; stdout/stderr captures retain at most 1 MiB each, with redaction, hashes and truncation markers. Historical source snapshots remain readable after worktree removal. They describe that execution, not current validity. The same scoped resolver is available to developer/reviewer through API and MCP tools.
+
+## Reproducible evaluation
+
+Build first, then run the actual offline command:
+
+```sh
+npm run build
+node bin/specrails-core.mjs runtime evaluate --output /tmp/specrails-efficiency-evaluation
+```
+
+Five fixed cases cover static Tetris-like logic, a local feature, a cross-repository contract, verification correction and review correction. Each independent oracle must accept its reference implementation and reject deliberately defective variants. Full and optimized modes use fresh repositories/sessions and identical acceptance gates. The fixed long-context correction must shrink at least 40% without extra invocations. Reports record task, oracle, repository, configuration and runtime identities, failures, sample variation and independent acceptance.
+
+Offline tokens and zero fixture cost are synthetic. The initial offline run accepted 5/5 cases in both modes and reduced its fixed correction prompt from 4,774 to 1,777 bytes (62.8%). It did not demonstrate lower monetary cost or faster real-provider execution. Repeat after implementation changes; the report records the tested package identity.
+
+Real evaluation is opt-in only: `runtime evaluate --real --config EXPLICIT_MODELS.json --max-cost-usd BUDGET --output OUTPUT`. Select all models and authorize the aggregate spend first. Unsupported spend limits prevent launch; incomplete billing stops further calls. The report distinguishes same-model from configured routing experiments and evaluates the descriptive target of 20% lower aggregate cost per independently accepted output. Small samples and uncontrolled provider caches do not establish universal quality or savings.
+
+## Compatibility and rollback
+
+A v4 checkpoint requires its original runtime. Never rewrite checksums or substitute a newly installed package. Desktop retains an immutable package and dependency closure per admitted run. Restoring that proven package is the recovery path; an unknown original package cannot be inferred from matching workflow inputs alone. New runtime configuration or package changes affect new runs only.
+
+This source tree is a development package. Publishing Core and updating Desktop's exact version/integrity lock are separate coordinated release steps; local assembly is not proof that a new version has been published.