specrails-core 5.6.0 → 6.0.0

package/dist/agent-runtime/openai-executor.d.ts

@@ -9,15 +9,6 @@ export interface OpenAICompatibleOptions {
     idleTimeoutMs?: number;
 }
 export declare function parseStructuredText(text: string): Record<string, unknown> | undefined;
-/** The agent loop an openai-compatible provider runs: compact host-driven pipelines by default. */
-/** The OpenAI `reasoning_effort` tiers a compatible endpoint accepts. */
-export declare const OPENAI_EFFORTS: readonly ["low", "medium", "high"];
-export declare function resolveAgentLoop(provider: ApiProvider): 'compact' | 'free';
-/** Compact runs: abort when NOTHING happens for this long (no tool call, reply or usage) — the real hang detector now that the wall clock is per task group. A non-streaming 16k reply at 20 tok/s is ~13 min, hence the margin. */
-export declare const IDLE_TIMEOUT_MS: number;
-export declare function resolveContextWindow(provider: ApiProvider): number;
-/** The per-turn output budget the connection declares; undefined keeps the loop's default. */
-export declare function resolveOutputBudget(provider: ApiProvider): number | undefined;
 /** No SDK, gateway, tracing backend, paid probe, or mandatory key. */
 export declare class OpenAICompatibleExecutor implements AgentExecutor {
     private readonly provider;

package/dist/agent-runtime/openai-executor.js

@@ -1,4 +1,4 @@
-import { readVerificationEvidence } from '../installer/runtime/pipeline-state.js';
+import { readVerificationEvidence } from '../pipeline/pipeline-state.js';
 import { assertEffortSupported, unknownCapabilities } from './capabilities.js';
 import { OpenSpecTools, OPENSPEC_TOOL_DEFINITION, openSpecPrompt } from './openspec.js';
 import { AgentExecutionError, unknownUsage, validateAgentRequest } from './executor-types.js';
@@ -19,13 +19,13 @@ export function parseStructuredText(text) {
 }
 /** The agent loop an openai-compatible provider runs: compact host-driven pipelines by default. */
 /** The OpenAI `reasoning_effort` tiers a compatible endpoint accepts. */
-export const OPENAI_EFFORTS = ['low', 'medium', 'high'];
-export function resolveAgentLoop(provider) { return provider.agentLoop ?? 'compact'; }
+const OPENAI_EFFORTS = ['low', 'medium', 'high'];
+function resolveAgentLoop(provider) { return provider.agentLoop ?? 'compact'; }
 /** Compact runs: abort when NOTHING happens for this long (no tool call, reply or usage) — the real hang detector now that the wall clock is per task group. A non-streaming 16k reply at 20 tok/s is ~13 min, hence the margin. */
-export const IDLE_TIMEOUT_MS = 20 * 60_000;
-export function resolveContextWindow(provider) { return provider.contextWindowTokens ?? DEFAULT_CONTEXT_WINDOW_TOKENS; }
+const IDLE_TIMEOUT_MS = 20 * 60_000;
+function resolveContextWindow(provider) { return provider.contextWindowTokens ?? DEFAULT_CONTEXT_WINDOW_TOKENS; }
 /** The per-turn output budget the connection declares; undefined keeps the loop's default. */
-export function resolveOutputBudget(provider) { return provider.maxOutputTokens; }
+function resolveOutputBudget(provider) { return provider.maxOutputTokens; }
 /** No SDK, gateway, tracing backend, paid probe, or mandatory key. */
 export class OpenAICompatibleExecutor {
     provider;
@@ -134,4 +134,3 @@ export class OpenAICompatibleExecutor {
         }
     }
 }
-//# sourceMappingURL=openai-executor.js.map

package/dist/agent-runtime/openspec-tool-server.js

@@ -1,4 +1,4 @@
-import { readVerificationEvidence } from '../installer/runtime/pipeline-state.js';
+import { readVerificationEvidence } from '../pipeline/pipeline-state.js';
 import { readFileSync } from 'node:fs';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
@@ -34,4 +34,3 @@ if (context.evidenceScope && context.role !== 'architect')
         }
     });
 await server.connect(new StdioServerTransport());
-//# sourceMappingURL=openspec-tool-server.js.map

package/dist/agent-runtime/openspec.d.ts

@@ -62,7 +62,6 @@ export declare const IMPLEMENTATION_PROGRESS_SCHEMA: z.ZodObject<{
     }, z.core.$strict>>;
     blockers: z.ZodArray<z.ZodString>;
 }, z.core.$strict>;
-export declare function renderProgressHandoff(context: OpenSpecRoleContext): string;
 export declare function hash(text: string): string;
 export declare function resolveOpenSpecCli(): string;
 export declare function runOpenSpec(cli: string, root: string, args: string[], signal?: AbortSignal): Promise<string>;
@@ -98,7 +97,6 @@ export declare class OpenSpecTools {
     assertParticipation(after?: number): void;
     assertReady(): Promise<OpenSpecApply>;
 }
-export declare const OPENSPEC_BRIDGE_ENTRY: string;
 export declare const OPENSPEC_TOOL_ACTIONS: readonly ["load_skill", "new", "status", "instructions", "validate", "write_artifact", "read_progress", "write_progress"];
 export declare const OPENSPEC_TOOL_DEFINITION: {
     type: string;

package/dist/agent-runtime/openspec.js

@@ -36,10 +36,6 @@ function readProgress(context) {
         return { notice: PROGRESS_NOTICE + ' Saved progress is unavailable or invalid; inspect the current diff and tasks before continuing.', record: null };
     }
 }
-export function renderProgressHandoff(context) {
-    const saved = readProgress(context);
-    return saved.record ? `\n## Saved implementation progress\n${saved.notice}\n${JSON.stringify(saved.record)}\n` : saved.notice.includes('unavailable') ? '\n' + saved.notice + '\n' : '';
-}
 function writeProgress(context, input) {
     if (context.role !== 'developer')
         throw new Error('Only the developer may write implementation progress');
@@ -301,7 +297,7 @@ export class OpenSpecTools {
         return apply;
     }
 }
-export const OPENSPEC_BRIDGE_ENTRY = fileURLToPath(new URL('./openspec-tool-server.js', import.meta.url));
+const OPENSPEC_BRIDGE_ENTRY = fileURLToPath(new URL('./openspec-tool-server.js', import.meta.url));
 export const OPENSPEC_TOOL_ACTIONS = ['load_skill', 'new', 'status', 'instructions', 'validate', 'write_artifact', 'read_progress', 'write_progress'];
 export const OPENSPEC_TOOL_DEFINITION = { type: 'function', function: { name: 'openspec_workflow', description: 'Run the official OpenSpec role workflow. Load the skill first (developer/reviewer also receive real status, apply context and saved progress), then use its CLI instructions and write artifacts within the fixed change. Developer may save a bounded advisory handoff with write_progress; read_progress refreshes it. Progress never substitutes for verification.', parameters: { type: 'object', additionalProperties: false, required: ['action'], properties: { action: { type: 'string', enum: OPENSPEC_TOOL_ACTIONS }, artifact: { type: 'string' }, path: { type: 'string' }, content: { type: 'string' }, progress: {
                     type: 'object', additionalProperties: false, required: ['summary', 'completedTasks', 'nextTasks', 'checks', 'blockers'], properties: {
@@ -327,4 +323,3 @@ export function openSpecRepairPrompt(context) {
     return `The previous ${context.role} result cannot be accepted because you omitted the required official OpenSpec workflow. Do not merely resend the JSON. Continue this same role with the work already available. Load ${ROLE_SKILLS[context.role]} using the scoped workflow tool (action=load_skill), consult status and instructions ${context.role === 'architect' ? 'tasks' : 'apply'}, and execute the complete returned skill procedure against the current artifacts and code. Reconcile your previous conclusions with that procedure; correct your report if necessary. Do not rerun the implementation or the host verification commands. ${context.role === 'reviewer' ? 'Stay read-only; do not modify code or artifacts.' : 'Keep already-correct work and respect the same frozen scope.'} Finish with the originally requested JSON report.
 `;
 }
-//# sourceMappingURL=openspec.js.map

package/dist/agent-runtime/prompts.d.ts

@@ -1,5 +1,5 @@
 import type { AgentRole } from './executor-types.js';
-import type { PipelineContext, VerificationCommand } from '../installer/runtime/pipeline-state.js';
+import type { PipelineContext, VerificationCommand } from '../pipeline/pipeline-state.js';
 import { type ReviewPolicy } from './graph/review-policy.js';
 import type { DeveloperRecord } from './graph/state.js';
 /** Bump whenever the wording changes: the version is part of the frozen run identity. */
@@ -15,7 +15,7 @@ export interface FrozenCriterion {
     requirement: string;
 }
 /** Roles with an editable definition: the three pipeline agents plus the FIXER stance the developer role takes on a correction round. */
-export type PromptRole = AgentRole | 'fixer';
+type PromptRole = AgentRole | 'fixer';
 export interface RoleInstructionOptions {
     definition?: string;
     /** `fixer`: the developer invocation is a correction round on the fixer stance (own definition, no plan dump). */
@@ -39,7 +39,7 @@ export declare const DEVELOPER_OUTPUT_SCHEMA: Record<string, unknown>;
 export declare const REVIEW_OUTPUT_SCHEMA: Record<string, unknown>;
 /** Actual editable task definitions; dynamic scope and output contracts are assembled separately. */
 export declare function rolePromptDefaults(): Record<PromptRole, string>;
-export interface ReReviewContext {
+interface ReReviewContext {
     changes: Array<{
         repositoryId: string;
         path: string;
@@ -61,3 +61,4 @@ export declare function correctionInstructions(role: AgentRole, feedback: RoleFe
 export declare function deepenInstructions(question: string | undefined): string;
 /** Asks a structured role to resend a malformed reply without repeating its work. */
 export declare function repairInstructions(role: AgentRole, problem: string): string;
+export {};

package/dist/agent-runtime/prompts.js

@@ -357,4 +357,3 @@ export function deepenInstructions(question) {
 export function repairInstructions(role, problem) {
     return `Your previous reply could not be used: ${problem}\n\nDo not redo the ${role} work. Reply again with exactly one JSON object matching the output contract, with no prose before or after it and no Markdown fence.\n`;
 }
-//# sourceMappingURL=prompts.js.map

package/dist/agent-runtime/provider-diagnostic.js

@@ -1,4 +1,4 @@
-import { redactRuntimeText } from '../installer/runtime/pipeline-state.js';
+import { redactRuntimeText } from '../pipeline/pipeline-state.js';
 import { stripVTControlCharacters } from 'node:util';
 /** Keep provider errors visible without dumping full output, prompts or credentials. */
 export function providerDiagnostic(stdout, stderr, env = process.env) {
@@ -22,4 +22,3 @@ export function providerDiagnostic(stdout, stderr, env = process.env) {
     message = stripVTControlCharacters(message);
     return redactRuntimeText(message, env).replace(/\s+/g, ' ').slice(0, 1200).trim();
 }
-//# sourceMappingURL=provider-diagnostic.js.map

package/dist/agent-runtime/recovery.js

@@ -6,7 +6,7 @@ import { WorkspaceTools } from './workspace-tools.js';
 import { artifactPath, hash, resolveOpenSpecCli, runOpenSpec } from './openspec.js';
 import { write } from './graph/artifacts.js';
 import { expandedPlanCommands, readVerificationPlan } from './verification-plan.js';
-import { inspectPipeline, pipelineStateDirectory, validatePipelineContext, verifyPipeline } from '../installer/runtime/pipeline-state.js';
+import { inspectPipeline, pipelineStateDirectory, validatePipelineContext, verifyPipeline } from '../pipeline/pipeline-state.js';
 const file = { repositoryId: z.string().min(1).max(128), path: z.string().min(1).max(1024) };
 const operation = { operationId: z.string().uuid(), reason: z.string().trim().min(1).max(2000), acknowledgeInterrupted: z.boolean().optional(), changedPrecondition: z.string().trim().min(1).max(2000).optional() };
 export const recoveryRequestSchema = z.discriminatedUnion('action', [
@@ -167,4 +167,3 @@ export async function runRecovery(contextInput, input, signal) {
         await release();
     }
 }
-//# sourceMappingURL=recovery.js.map

package/dist/agent-runtime/repository-context.d.ts

@@ -1,4 +1,4 @@
-import type { PipelineContext } from '../installer/runtime/pipeline-state.js';
+import type { PipelineContext } from '../pipeline/pipeline-state.js';
 /** Small, provider-independent map of facts from the admitted checkout. Never
  * follows a documentation link out of scope or invents verification commands. */
 export interface RepositoryContextEntry {

package/dist/agent-runtime/repository-context.js

@@ -124,4 +124,3 @@ export function renderRepositoryContext(current, previous) {
     ].join('\n\n');
 }
 export function repositoryContext(context) { return renderRepositoryContext(repositoryContextSnapshot(context)); }
-//# sourceMappingURL=repository-context.js.map

package/dist/agent-runtime/review-context.d.ts

@@ -1,4 +1,4 @@
-import type { CandidateManifest } from '../installer/runtime/pipeline-state.js';
+import type { CandidateManifest } from '../pipeline/pipeline-state.js';
 export interface ReviewManifest extends CandidateManifest {
     truncated: boolean;
 }

package/dist/agent-runtime/review-context.js

@@ -38,4 +38,3 @@ export function reviewChanges(previous, current) {
     const transversal = changes.some(change => TRANSVERSAL.test(change.path));
     return { mode: transversal ? 'full' : 'incremental', reason: transversal ? 'A shared contract, build, dependency or security input changed' : 'Changes since the previous reviewed candidate', changes };
 }
-//# sourceMappingURL=review-context.js.map

package/dist/agent-runtime/role-routing.js

@@ -27,4 +27,3 @@ export function selectRoleRoute(role, selected, kind, checkpoint, previous) {
             ...(selected.escalation.effort === undefined ? {} : { effort: selected.escalation.effort }),
         } };
 }
-//# sourceMappingURL=role-routing.js.map

package/dist/agent-runtime/role-state.js

@@ -21,4 +21,3 @@ export function writeRoleState(directory, data) {
         throw new Error('Role execution state exceeds its size limit');
     write(path.join(directory, 'role-execution.json'), content);
 }
-//# sourceMappingURL=role-state.js.map

package/dist/agent-runtime/runtime-identity.js

@@ -21,7 +21,7 @@ export function runtimePackageIntegrity(root = fileURLToPath(new URL('../../', i
         else
             throw new Error('Runtime package contains a nonregular file: ' + relative);
     };
-    for (const entry of ['package.json', 'dist', 'bin', 'templates', 'schemas', 'commands', 'integration-contract.json', 'pinned-versions.json']) {
+    for (const entry of ['package.json', 'dist', 'bin', 'templates', 'schemas', 'integration-contract.json', 'pinned-versions.json']) {
         if (existsSync(path.join(root, entry)))
             visit(entry);
     }
@@ -30,4 +30,3 @@ export function runtimePackageIntegrity(root = fileURLToPath(new URL('../../', i
 export function sameRuntimeIdentity(left, right) {
     return ['packageVersion', 'workflowVersion', 'instructionsVersion', 'packageIntegrity', 'apiVersion'].every(key => left[key] === right[key]);
 }
-//# sourceMappingURL=runtime-identity.js.map

package/dist/agent-runtime/tool-event.js

@@ -21,4 +21,3 @@ export function toolEvent(tool, input) {
     const cwd = args.workdir ?? args.cwd;
     return { kind: 'tool-start', tool, ...(detail ? { detail } : {}), ...(targetPaths.length ? { targetPaths } : {}), ...(typeof cwd === 'string' ? { cwd } : {}) };
 }
-//# sourceMappingURL=tool-event.js.map

package/dist/agent-runtime/verification-plan.d.ts

@@ -1,4 +1,4 @@
-import { type PipelineContext, type VerificationCommand } from '../installer/runtime/pipeline-state.js';
+import { type PipelineContext, type VerificationCommand } from '../pipeline/pipeline-state.js';
 export interface ProposedCheck {
     kind: 'command' | 'harness';
     key: string;
@@ -14,12 +14,12 @@ export interface ProposedCheck {
         content: string;
     }>;
 }
-export interface HarnessSource {
+interface HarnessSource {
     path: string;
     hash: string;
     byteCount: number;
 }
-export interface PlanEntry {
+interface PlanEntry {
     id: string;
     key: string;
     label: string;
@@ -31,7 +31,7 @@ export interface PlanEntry {
         sources: HarnessSource[];
     };
 }
-export interface VerificationPlan {
+interface VerificationPlan {
     schemaVersion: 1;
     runId: string;
     revision: number;
@@ -53,3 +53,4 @@ export declare function addDeveloperChecks(context: PipelineContext, proposals:
 export declare function expandedPlanCommands(context: PipelineContext, plan: VerificationPlan): VerificationCommand[];
 /** Bind the exact manifest and every source to lifecycle gates. */
 export declare function bindPlan(context: PipelineContext, plan: VerificationPlan): void;
+export {};

package/dist/agent-runtime/verification-plan.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
-import { bindVerificationPlan, pipelineStateDirectory, validateVerificationRequest } from '../installer/runtime/pipeline-state.js';
+import { bindVerificationPlan, pipelineStateDirectory, validateVerificationRequest } from '../pipeline/pipeline-state.js';
 import { fingerprint } from './durable-store.js';
 import { child, write } from './graph/artifacts.js';
 const SAFE_ID = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/;
@@ -203,4 +203,3 @@ export function bindPlan(context, plan) {
         }
     bindVerificationPlan(context, plan.planHash, files);
 }
-//# sourceMappingURL=verification-plan.js.map

package/dist/agent-runtime/workflow-types.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=workflow-types.js.map

package/dist/agent-runtime/workflow.js

@@ -633,4 +633,3 @@ export async function runWorkflow(options) {
         await release();
     }
 }
-//# sourceMappingURL=workflow.js.map

package/dist/agent-runtime/workspace-tools.d.ts

@@ -1,5 +1,5 @@
 import type { AgentRole } from './executor-types.js';
-export interface WorkspaceToolDefinition {
+interface WorkspaceToolDefinition {
     type: 'function';
     function: {
         name: string;
@@ -7,7 +7,6 @@ export interface WorkspaceToolDefinition {
         parameters: Record<string, unknown>;
     };
 }
-export declare function isWithinRoot(root: string, file: string): boolean;
 export declare function canonicalWorkspace(cwd: string, allowedRoots: string[]): {
     cwd: string;
     roots: string[];
@@ -27,3 +26,4 @@ export declare class WorkspaceTools {
     private search;
     private diff;
 }
+export {};

package/dist/agent-runtime/workspace-tools.js

@@ -18,7 +18,7 @@ function integer(value, fallback, max) {
     return value;
 }
 function digest(text) { return createHash('sha256').update(text).digest('hex'); }
-export function isWithinRoot(root, file) {
+function isWithinRoot(root, file) {
     const relative = path.relative(root, file);
     return relative === '' || (!path.isAbsolute(relative) && relative !== '..' && !relative.startsWith('..' + path.sep));
 }
@@ -279,4 +279,3 @@ export class WorkspaceTools {
         return JSON.stringify({ untracked: false, diff: '', truncated: false });
     }
 }
-//# sourceMappingURL=workspace-tools.js.map

package/dist/installer/cli.d.ts

@@ -1,35 +1,6 @@
 /**
- * specrails-core CLI entry point (Node / TypeScript).
- *
- * Replaces the legacy bash-dispatch path in `bin/specrails-core.js`.
- * During the port, `bin/specrails-core.js` keeps shelling out to the
- * shell scripts while this module carries the in-progress Node
- * implementation. Once Phases 2–4 ship the command handlers and
- * Phase 5 deletes the shell scripts, the `bin/` dispatcher collapses
- * to a single `import { main } from './dist/installer/cli.js'` call.
+ * specrails-core CLI: the installer and runtime entry points Desktop drives.
+ * `bin/specrails-core.mjs` and a direct `node dist/installer/cli.js` run both
+ * land in {@link main}.
  */
-export interface ParsedArgs {
-    subcommand: string | null;
-    flags: Record<string, string | boolean>;
-    positionals: string[];
-}
-/**
- * Minimal arg parser, no external dep. Handles:
- *   subcommand                (first bare positional)
- *   --flag                    (boolean true)
- *   --flag=value              (string)
- *   --flag value              (string, consumes next token)
- *   -h / --help               (help alias)
- *   -v / --version            (version alias)
- *   positionals               (everything else)
- */
-export declare function parseArgs(argv: string[]): ParsedArgs;
-/**
- * Sentinel exit code used during the port: when a Node command is not
- * yet implemented, the CLI exits with this code and the outer bash
- * dispatcher (bin/specrails-core.js) may choose to fall through to
- * the shell path. Removed entirely in Phase 5 when no shell scripts
- * remain.
- */
-export declare const NOT_IMPLEMENTED = 2;
 export declare function main(argv?: string[]): Promise<number>;

package/dist/installer/cli.js

@@ -1,100 +1,35 @@
 /**
- * specrails-core CLI entry point (Node / TypeScript).
- *
- * Replaces the legacy bash-dispatch path in `bin/specrails-core.js`.
- * During the port, `bin/specrails-core.js` keeps shelling out to the
- * shell scripts while this module carries the in-progress Node
- * implementation. Once Phases 2–4 ship the command handlers and
- * Phase 5 deletes the shell scripts, the `bin/` dispatcher collapses
- * to a single `import { main } from './dist/installer/cli.js'` call.
+ * specrails-core CLI: the installer and runtime entry points Desktop drives.
+ * `bin/specrails-core.mjs` and a direct `node dist/installer/cli.js` run both
+ * land in {@link main}.
  */
 import { readFileSync, realpathSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { runDoctor } from './commands/doctor.js';
 import { runAssemble, runInstallFramework, runSwapCurrent, } from './commands/framework.js';
 import { runInit } from './commands/init.js';
-import { runUpdate } from './commands/update.js';
-import { runPipelineCommand } from './runtime/pipeline-state.js';
+import { runPipelineCommand } from '../pipeline/pipeline-state.js';
+import { parseArgs } from '../shared/args.js';
 import { isInstallerError } from './util/errors.js';
 import { fatal } from './util/logger.js';
-/**
- * Minimal arg parser, no external dep. Handles:
- *   subcommand                (first bare positional)
- *   --flag                    (boolean true)
- *   --flag=value              (string)
- *   --flag value              (string, consumes next token)
- *   -h / --help               (help alias)
- *   -v / --version            (version alias)
- *   positionals               (everything else)
- */
-export function parseArgs(argv) {
-    const flags = {};
-    const positionals = [];
-    let subcommand = null;
-    for (let i = 0; i < argv.length; i++) {
-        const token = argv[i];
-        if (token.startsWith('--')) {
-            const rest = token.slice(2);
-            const eq = rest.indexOf('=');
-            if (eq >= 0) {
-                flags[rest.slice(0, eq)] = rest.slice(eq + 1);
-            }
-            else {
-                const peek = argv[i + 1];
-                if (peek !== undefined && !peek.startsWith('-')) {
-                    flags[rest] = peek;
-                    i++;
-                }
-                else {
-                    flags[rest] = true;
-                }
-            }
-        }
-        else if (token === '-h') {
-            flags.help = true;
-        }
-        else if (token === '-v') {
-            flags.version = true;
-        }
-        else if (token.startsWith('-') && token.length > 1) {
-            flags[token.slice(1)] = true;
-        }
-        else {
-            if (subcommand === null) {
-                subcommand = token;
-            }
-            else {
-                positionals.push(token);
-            }
-        }
-    }
-    return { subcommand, flags, positionals };
-}
 function usageText() {
     return [
         '',
-        'specrails-core — Provider-independent AI agent workflow system',
+        'specrails-core — agent workflow engine for specrails-desktop',
         '',
         'Usage:',
         '  specrails-core <command> [options]',
         '',
         'Commands:',
-        '  init                Install specrails into a repository',
-        '  update              Update an existing specrails installation',
-        '  pipeline            Inspect and execute durable implementation phases',
-        '  runtime             Run, inspect and resume programmatic agents',
-        '  doctor              Diagnose the health of an existing installation',
+        '  init                Install specrails into a repository (claude, codex, gemini, or kimi)',
         '  install-framework   Materialize the versioned framework (offline)',
         '  swap-current        Point framework/current at a version (offline)',
-        '  assemble            Symlink the framework into a workspace (offline)',
+        '  assemble            Link the framework into a project workspace (offline)',
+        '  pipeline            Inspect and verify durable implementation phases',
+        '  runtime             Run, inspect and resume programmatic agents',
         '  help                Show this help message',
         '  version             Print the installed version',
         '',
-        'Global options:',
-        '  -h, --help     Show this help',
-        '  -v, --version  Print version',
-        '',
     ].join('\n');
 }
 function readVersion() {
@@ -113,30 +48,15 @@ function readVersion() {
         return 'unknown';
     }
 }
-/**
- * Sentinel exit code used during the port: when a Node command is not
- * yet implemented, the CLI exits with this code and the outer bash
- * dispatcher (bin/specrails-core.js) may choose to fall through to
- * the shell path. Removed entirely in Phase 5 when no shell scripts
- * remain.
- */
-export const NOT_IMPLEMENTED = 2;
-async function dispatch(subcommand, flags, _positionals) {
+async function dispatch(subcommand, flags, positionals) {
     switch (subcommand) {
         case 'init':
             await runInit(flags);
             return 0;
-        case 'update':
-            await runUpdate(flags);
-            return 0;
         case 'pipeline':
-            return runPipelineCommand(flags, _positionals);
+            return runPipelineCommand(flags, positionals);
         case 'runtime':
-            return (await import('../agent-runtime/cli.js')).runRuntimeCommand(flags, _positionals);
-        case 'doctor': {
-            const result = await runDoctor(flags);
-            return result.failed === 0 ? 0 : 1;
-        }
+            return (await import('../agent-runtime/cli.js')).runRuntimeCommand(flags, positionals);
         case 'install-framework':
             await runInstallFramework(flags);
             return 0;
@@ -147,7 +67,6 @@ async function dispatch(subcommand, flags, _positionals) {
             await runAssemble(flags);
             return 0;
         case 'help':
-        case '':
             process.stdout.write(usageText());
             return 0;
         case 'version':
@@ -161,16 +80,23 @@ async function dispatch(subcommand, flags, _positionals) {
 }
 export async function main(argv = process.argv.slice(2)) {
     const { subcommand, flags, positionals } = parseArgs(argv);
-    if (flags.help === true) {
+    // `--version` is global only before a command: `swap-current --version <v>`
+    // names a framework version.
+    if (subcommand === null) {
+        if (flags.version === true || flags.V === true) {
+            process.stdout.write(`${readVersion()}\n`);
+            return 0;
+        }
         process.stdout.write(usageText());
         return 0;
     }
-    if (flags.version === true) {
-        process.stdout.write(`${readVersion()}\n`);
+    // `init --help` must print help, never install.
+    if (flags.help === true && subcommand !== 'runtime') {
+        process.stdout.write(usageText());
         return 0;
     }
     try {
-        return await dispatch(subcommand ?? '', flags, positionals);
+        return await dispatch(subcommand, flags, positionals);
     }
     catch (err) {
         if (isInstallerError(err)) {
@@ -187,8 +113,8 @@ export async function main(argv = process.argv.slice(2)) {
  * (`node dist/installer/cli.js <subcommand>`), run `main()` and propagate its
  * exit code. specrails-desktop's bundled-core path (server/framework-manager.ts)
  * spawns `node <core>/dist/installer/cli.js install-framework|assemble …` and
- * relies on this — the legacy bin dispatcher (bin/specrails-core.mjs) imports
- * `main` and is unaffected (it never executes this file as argv[1]).
+ * relies on this — `bin/specrails-core.mjs` imports `main` and is unaffected
+ * (it never executes this file as argv[1]).
  *
  * Comparing `import.meta.url` against `process.argv[1]` keeps the guard inert on
  * import (so unit tests that `import { main }` never trigger a process.exit).
@@ -219,4 +145,3 @@ if (isDirectRun) {
         process.exitCode = code;
     });
 }
-//# sourceMappingURL=cli.js.map

package/dist/installer/commands/framework.d.ts

@@ -40,7 +40,7 @@ export interface AssembleFlags {
     /** Comma-separated per-project agent allow-list (links a subset of the superset). */
     'selected-agents'?: string | boolean;
 }
-export interface InstallFrameworkOutcome {
+interface InstallFrameworkOutcome {
     frameworkDir: string;
     provider: Provider;
     version: string;
@@ -48,13 +48,13 @@ export interface InstallFrameworkOutcome {
     /** True when `current` was swapped to `<version>` this call. */
     swapped: boolean;
 }
-export interface SwapCurrentOutcome {
+interface SwapCurrentOutcome {
     frameworkDir: string;
     version: string;
     /** Complete provider set validated before the pointer was moved. */
     providers: Provider[];
 }
-export interface AssembleOutcome {
+interface AssembleOutcome {
     workspace: string;
     frameworkDir: string;
     provider: Provider;
@@ -83,3 +83,4 @@ export declare function runSwapCurrent(flags: SwapCurrentFlags): Promise<SwapCur
 export declare function runAssemble(flags: AssembleFlags): Promise<AssembleOutcome>;
 /** Read the package version (the version the desktop should materialize). */
 export declare function readPackageVersion(scriptDir?: string): string;
+export {};

package/dist/installer/commands/framework.js

@@ -186,4 +186,3 @@ export function readPackageVersion(scriptDir) {
         return 'unknown';
     }
 }
-//# sourceMappingURL=framework.js.map