specrails-core 6.0.0 → 6.1.0

package/README.md

@@ -6,7 +6,7 @@
 
 The agent workflow engine behind [Specrails Desktop](https://github.com/fjpulidop/specrails-desktop). Core does two things:
 
-1. **Installs** the specrails workflow into a project for Claude Code, Codex CLI, Gemini CLI or Kimi Code: three roles (architect, developer, reviewer), the `implement` / `batch-implement` / `retry` entry points and the official OpenSpec skills.
+1. **Installs** the specrails workflow into a project for Claude Code, Codex CLI, Gemini CLI or Kimi Code: three roles (architect, developer, reviewer), the `implement` and `retry` entry points (`implement` runs one ticket or several tickets as one aggregate run) and the official OpenSpec skills.
 2. **Runs** implementations through the [programmatic agent runtime](docs/agent-runtime.md): a LangGraph workflow (architect → developer → verify → reviewer → archive) with per-role providers, deterministic verification, durable recovery and OpenAI-compatible local models.
 
 Desktop bundles a pinned Core package and owns everything around it: worktrees, commits, pull requests, backlog and the user interface. Core never ships code on its own; it prepares a reviewed candidate for the host.

package/dist/agent-runtime/capabilities.js

@@ -1,3 +1,4 @@
+import { resolveRoleDescriptor, roleIds } from './config.js';
 import { readFileSync, statSync } from 'node:fs';
 import { homedir, tmpdir } from 'node:os';
 import path from 'node:path';
@@ -71,7 +72,8 @@ export async function configuredCapabilities(config, registry) {
         return probes.get(key);
     };
     const roles = [];
-    for (const [role, selected] of Object.entries(config.agents)) {
+    for (const role of roleIds(config)) {
+        const selected = resolveRoleDescriptor(config, role);
         for (const [tier, choice] of [['base', selected], ...(selected.escalation ? [['escalation', selected.escalation]] : [])]) {
             roles.push({ role, tier, provider: selected.provider, model: choice.model ?? null, requestedEffort: choice.effort ?? null, ...await probe(selected.provider, choice.model) });
         }

package/dist/agent-runtime/change-scope.d.ts

@@ -0,0 +1,63 @@
+import { type PipelineContext, type PipelineRepository } from '../pipeline/pipeline-state.js';
+export interface ChangedFile {
+    path: string;
+    status: 'added' | 'modified' | 'deleted';
+}
+export interface RepositoryChangeSet {
+    repositoryId: string;
+    scope?: string[];
+    files: ChangedFile[];
+    truncated: boolean;
+}
+/** An out-of-scope edit Core undid after a role turn. */
+export interface DiscardedEdit {
+    repositoryId: string;
+    path: string;
+    restored: 'base' | 'previous' | 'removed';
+}
+/** A command without `cwd` runs in its repository's scope directory, never at the root of a larger checkout. */
+export declare function withScopeDefault<T extends {
+    repositoryId: string;
+    cwd?: string;
+}>(context: PipelineContext, command: T): T;
+/** Model-proposed checks stay inside the repository scope: they prove the change, not the whole checkout. */
+export declare function assertProposalInScope(context: PipelineContext, command: {
+    repositoryId: string;
+    cwd?: string;
+}, what?: string): void;
+/** Base commit per repository id; the first call records it. */
+export declare function changeBases(context: PipelineContext): Record<string, string>;
+/** Every path that differs from the base: tracked edits (staged or not), deletions and new untracked files. */
+export declare function repositoryChanges(context: PipelineContext, repository: PipelineRepository, base: string, change?: string): ChangedFile[];
+/** What this run changed, per repository and bounded: untracked files that predate the run are not part of it. */
+export declare function changeSet(context: PipelineContext, change?: string, limit?: number): RepositoryChangeSet[];
+/** Changes outside the repository scope (none when the whole checkout is the repository). */
+export declare function outOfScope(repository: PipelineRepository, files: readonly ChangedFile[]): ChangedFile[];
+interface SavedState {
+    fingerprint: string;
+    content?: Buffer;
+    mode?: number;
+    link?: string;
+}
+/** The out-of-scope state before a role turn: the host undoes only what that turn did. */
+export interface ScopeGuard {
+    change?: string;
+    repositories: Array<{
+        id: string;
+        base: string;
+        before: Map<string, SavedState>;
+    }>;
+}
+export declare function captureOutOfScope(context: PipelineContext, change?: string): ScopeGuard;
+/**
+ * Undoes every out-of-scope edit made since `guard` was captured. A path the
+ * turn changed outside the scope returns to its state before the turn: its
+ * base content, its earlier out-of-scope content, or absence. In-scope work,
+ * ignored files and out-of-scope state that predates the turn stay untouched.
+ */
+export declare function discardOutOfScopeEdits(context: PipelineContext, guard: ScopeGuard): DiscardedEdit[];
+/** Bounded prompt lines for a change set; repository ids prefix the paths only when several repositories are in scope. */
+export declare function renderChangeSet(sets: readonly RepositoryChangeSet[], limit?: number): string[];
+/** One human line naming discarded edits, bounded. */
+export declare function describeDiscarded(edits: readonly DiscardedEdit[], multiple: boolean, limit?: number): string;
+export {};

package/dist/agent-runtime/change-scope.js

@@ -0,0 +1,297 @@
+// The change a run makes, measured by the host from git rather than taken from
+// a role's own summary, and the boundary it must stay inside.
+//
+// Observed (a monorepo app registered as the repository, busuu-courses inside
+// busuu-web): the configured `yarn test` ran at the checkout root and fanned
+// out to every workspace; the fixer then "repaired" .yarnrc.yml, the root
+// package.json and two other apps, the reviewer rejected those unrelated
+// edits, the fixer reverted them, verification failed again — a loop that
+// never converged. A repository scope makes the boundary explicit: commands
+// default to the package, reviews see the exact change set, and edits outside
+// the scope are undone by the host before anyone verifies or reviews them.
+import { spawnSync } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { lstatSync, mkdirSync, readFileSync, readlinkSync, renameSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { pipelineStateDirectory, withinRepositoryScope } from '../pipeline/pipeline-state.js';
+/** Git's empty tree: the base of a repository without commits. */
+const EMPTY_TREE = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
+/** Files whose change inside the scope legitimately refreshes a lockfile of an enclosing workspace. */
+const MANIFESTS = new Set(['package.json', 'Cargo.toml', 'go.mod', 'pyproject.toml', 'Pipfile', 'Gemfile', 'composer.json', 'requirements.txt']);
+const LOCKFILES = new Set(['package-lock.json', 'npm-shrinkwrap.json', 'yarn.lock', 'pnpm-lock.yaml', 'bun.lock', 'bun.lockb', 'Cargo.lock', 'go.sum', 'go.work.sum', 'poetry.lock', 'uv.lock', 'Pipfile.lock', 'Gemfile.lock', 'composer.lock', '.pnp.cjs', '.pnp.loader.mjs', '.pnp.data.json']);
+const AGENT_MEMORY = ['.claude', '.codex', '.gemini', '.kimi-code'].map(root => root + '/agent-memory');
+const GENERATED = new Set(['node_modules', 'coverage', '.nyc_output', '.jest-cache', '__pycache__', '.pytest_cache', '.mypy_cache', '.ruff_cache', '.venv', 'venv', '.tox', '.gradle', '.cache', '.turbo']);
+/** Bounded memory for restoring a previous out-of-scope state byte for byte; beyond it the base is restored. */
+const RESTORE_FILE_LIMIT = 8 * 1024 * 1024;
+const RESTORE_TOTAL_LIMIT = 64 * 1024 * 1024;
+/** Untracked files present when the run started are host/user state (overlays, local files), not the change. */
+const PREEXISTING_LIMIT = 20_000;
+function gitEnv() {
+    // An inherited GIT_DIR/GIT_WORK_TREE/GIT_INDEX_FILE must not redirect the inspection.
+    const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.toUpperCase().startsWith('GIT_')));
+    return { ...env, GIT_OPTIONAL_LOCKS: '0', GIT_LITERAL_PATHSPECS: '1', GIT_TERMINAL_PROMPT: '0' };
+}
+function git(root, args, allowFailure = false) {
+    const result = spawnSync('git', ['-c', 'core.quotePath=false', '-c', 'core.fsmonitor=false', '-C', root, ...args], { env: gitEnv(), encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, windowsHide: true });
+    const overflow = result.error?.code === 'ENOBUFS';
+    const ok = !result.error && result.status === 0;
+    if (!ok && !allowFailure)
+        throw new Error(`git ${args[0]} failed in ${root}: ${String(result.error?.message ?? result.stderr ?? '').trim().slice(0, 400)}`);
+    return { ok, stdout: result.stdout ?? '', overflow };
+}
+const posix = (file) => file.split(path.sep).join('/');
+/** A command without `cwd` runs in its repository's scope directory, never at the root of a larger checkout. */
+export function withScopeDefault(context, command) {
+    if (command.cwd !== undefined)
+        return command;
+    const scope = context.repositories.find(repo => repo.id === command.repositoryId)?.scope;
+    return scope?.length ? { ...command, cwd: scope[0] } : command;
+}
+/** Model-proposed checks stay inside the repository scope: they prove the change, not the whole checkout. */
+export function assertProposalInScope(context, command, what = 'verification proposal') {
+    const repository = context.repositories.find(repo => repo.id === command.repositoryId);
+    if (!repository?.scope?.length || command.cwd === undefined)
+        return;
+    const relative = posix(path.relative(repository.path, path.resolve(repository.path, command.cwd)));
+    if (relative === '..' || relative.startsWith('../') || path.isAbsolute(relative) || !withinRepositoryScope(repository, relative)) {
+        throw new Error(`Invalid ${what} cwd ${JSON.stringify(command.cwd)}: it runs outside the repository scope (${repository.scope.join(', ')}). Omit cwd to run in ${repository.scope[0]}, or name a directory inside the scope.`);
+    }
+}
+/** Untracked, non-ignored paths; a checkout with an enormous untracked tree reports directories instead of files. */
+function untracked(root) {
+    const files = git(root, ['ls-files', '--others', '--exclude-standard', '-z'], true);
+    if (files.ok)
+        return files.stdout.split('\0').filter(Boolean);
+    if (!files.overflow)
+        git(root, ['ls-files', '--others', '--exclude-standard', '-z']);
+    return git(root, ['ls-files', '--others', '--exclude-standard', '--directory', '-z']).stdout.split('\0').filter(Boolean);
+}
+function baseFile(context) { return path.join(pipelineStateDirectory(context), 'change-base.json'); }
+/**
+ * The commit each repository's change is measured against — the host's frozen
+ * base when it declared one, otherwise HEAD the first time Core asks (before
+ * any role edits) — plus the untracked files that already existed then.
+ * Recorded once, so every later turn measures the same change.
+ */
+function baseRecords(context) {
+    const file = baseFile(context);
+    let recorded = {};
+    try {
+        const value = JSON.parse(readFileSync(file, 'utf8'));
+        if (value.schemaVersion === 1 && value.repositories && typeof value.repositories === 'object')
+            recorded = value.repositories;
+    }
+    catch { /* first use */ }
+    let changed = false;
+    for (const repository of context.repositories) {
+        const known = recorded[repository.id];
+        if (known && typeof known.base === 'string' && /^[a-f0-9]{40,64}$/.test(known.base))
+            continue;
+        let base = repository.baseSha;
+        if (!base) {
+            const head = git(repository.path, ['rev-parse', '--verify', '--quiet', 'HEAD^{commit}'], true);
+            base = head.ok && /^[a-f0-9]{40,64}$/.test(head.stdout.trim()) ? head.stdout.trim() : EMPTY_TREE;
+        }
+        let present;
+        try {
+            present = untracked(repository.path);
+        }
+        catch { /* not a git checkout: the change cannot be measured */ }
+        recorded[repository.id] = { base, ...(present && present.length <= PREEXISTING_LIMIT ? { preexisting: present } : {}) };
+        changed = true;
+    }
+    if (changed) {
+        mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+        const temp = file + '.' + randomUUID() + '.tmp';
+        try {
+            writeFileSync(temp, JSON.stringify({ schemaVersion: 1, repositories: recorded }) + '\n', { flag: 'wx', mode: 0o600 });
+            renameSync(temp, file);
+        }
+        finally {
+            rmSync(temp, { force: true });
+        }
+    }
+    return recorded;
+}
+/** Base commit per repository id; the first call records it. */
+export function changeBases(context) {
+    return Object.fromEntries(Object.entries(baseRecords(context)).map(([id, record]) => [id, record.base]));
+}
+/** Host and runtime state, the change's own OpenSpec artifacts and generated trees are never part of the code change. */
+function ignored(context, repository, change, file, fresh) {
+    if (file === '.specrails' || file.startsWith('.specrails/'))
+        return true;
+    if (repository.id === context.artifactRepositoryId && change && (file === 'openspec/changes/' + change || file.startsWith('openspec/changes/' + change + '/')))
+        return true;
+    if (!fresh)
+        return false;
+    return AGENT_MEMORY.some(root => file === root || file.startsWith(root + '/')) || file.split('/').some(segment => GENERATED.has(segment));
+}
+/** Every path that differs from the base: tracked edits (staged or not), deletions and new untracked files. */
+export function repositoryChanges(context, repository, base, change) {
+    const files = new Map();
+    const diff = git(repository.path, ['diff', '--name-status', '-z', '--no-renames', '--ignore-submodules=all', base, '--']).stdout.split('\0');
+    for (let i = 0; i + 1 < diff.length; i += 2) {
+        const status = diff[i], file = diff[i + 1];
+        if (!status || !file || ignored(context, repository, change, file, false))
+            continue;
+        files.set(file, status.startsWith('A') ? 'added' : status.startsWith('D') ? 'deleted' : 'modified');
+    }
+    for (const file of untracked(repository.path)) {
+        const relative = file.replace(/\/$/, '');
+        if (!files.has(relative) && !ignored(context, repository, change, relative, true))
+            files.set(file, 'added');
+    }
+    return [...files].map(([file, status]) => ({ path: file, status })).sort((a, b) => a.path.localeCompare(b.path));
+}
+/** What this run changed, per repository and bounded: untracked files that predate the run are not part of it. */
+export function changeSet(context, change, limit = 5000) {
+    const records = baseRecords(context);
+    return context.repositories.map(repository => {
+        const record = records[repository.id];
+        const preexisting = new Set(record.preexisting ?? []);
+        const files = repositoryChanges(context, repository, record.base, change).filter(file => !(file.status === 'added' && preexisting.has(file.path)));
+        return { repositoryId: repository.id, ...(repository.scope ? { scope: repository.scope } : {}), files: files.slice(0, limit), truncated: files.length > limit };
+    });
+}
+function dependencyFileForScope(repository, file) {
+    // A dependency change in the package legitimately refreshes the lockfile (or
+    // Yarn's install artifacts) of a workspace that encloses the scope.
+    const enclosing = (directory) => (repository.scope ?? []).some(scope => directory === '.' || directory === '' || scope === directory || scope.startsWith(directory + '/'));
+    if (LOCKFILES.has(path.posix.basename(file)))
+        return enclosing(path.posix.dirname(file));
+    const yarn = /^(?:(.*)\/)?\.yarn\/(?:cache\/|install-state\.gz$)/.exec(file);
+    return yarn !== null && enclosing(yarn[1] ?? '.');
+}
+/** Changes outside the repository scope (none when the whole checkout is the repository). */
+export function outOfScope(repository, files) {
+    if (!repository.scope?.length)
+        return [];
+    const manifestChanged = files.some(file => withinRepositoryScope(repository, file.path) && MANIFESTS.has(path.posix.basename(file.path)));
+    return files.filter(file => !withinRepositoryScope(repository, file.path.replace(/\/$/, '')) && !(manifestChanged && dependencyFileForScope(repository, file.path)));
+}
+function fingerprintOf(file) {
+    const stat = lstatSync(file, { throwIfNoEntry: false });
+    if (!stat)
+        return { fingerprint: 'missing' };
+    if (stat.isSymbolicLink()) {
+        const link = readlinkSync(file);
+        return { fingerprint: 'link:' + link, link };
+    }
+    if (!stat.isFile())
+        return { fingerprint: 'other' };
+    const content = readFileSync(file);
+    return { fingerprint: `file:${stat.mode & 0o777}:${createHash('sha256').update(content).digest('hex')}`, content, mode: stat.mode & 0o777 };
+}
+export function captureOutOfScope(context, change) {
+    const scoped = context.repositories.filter(repository => repository.scope?.length);
+    if (!scoped.length)
+        return { change, repositories: [] };
+    const bases = changeBases(context);
+    let budget = 0;
+    return {
+        change,
+        repositories: scoped.map(repository => {
+            const base = bases[repository.id];
+            const before = new Map();
+            for (const file of outOfScope(repository, repositoryChanges(context, repository, base, change))) {
+                const { content, ...saved } = fingerprintOf(path.join(repository.path, file.path));
+                const keep = content && content.length <= RESTORE_FILE_LIMIT && budget + content.length <= RESTORE_TOTAL_LIMIT;
+                if (keep)
+                    budget += content.length;
+                before.set(file.path, keep ? { ...saved, content } : saved);
+            }
+            return { id: repository.id, base, before };
+        }),
+    };
+}
+function restoreFromBase(repository, base, files) {
+    const restored = [];
+    for (let i = 0; i < files.length; i += 100) {
+        const batch = files.slice(i, i + 100);
+        const tracked = base === EMPTY_TREE ? new Set() : new Set(git(repository.path, ['ls-tree', '-r', '-z', '--name-only', '--full-tree', base, '--', ...batch.map(file => file.replace(/\/$/, ''))]).stdout.split('\0').filter(Boolean));
+        const existing = batch.filter(file => tracked.has(file));
+        if (existing.length)
+            git(repository.path, ['restore', '--source=' + base, '--staged', '--worktree', '--', ...existing]);
+        const added = batch.filter(file => !tracked.has(file));
+        if (added.length)
+            git(repository.path, ['rm', '-r', '-q', '--cached', '--ignore-unmatch', '--', ...added.map(file => file.replace(/\/$/, ''))], true);
+        for (const file of added)
+            rmSync(path.join(repository.path, file), { recursive: true, force: true });
+        restored.push(...existing.map(file => ({ repositoryId: repository.id, path: file, restored: 'base' })), ...added.map(file => ({ repositoryId: repository.id, path: file.replace(/\/$/, ''), restored: 'removed' })));
+    }
+    return restored;
+}
+function restorePrevious(repository, file, saved) {
+    const target = path.join(repository.path, file);
+    rmSync(target, { recursive: true, force: true });
+    if (saved.fingerprint === 'missing')
+        return;
+    mkdirSync(path.dirname(target), { recursive: true });
+    if (saved.link !== undefined)
+        symlinkSync(saved.link, target);
+    else
+        writeFileSync(target, saved.content, { mode: saved.mode ?? 0o644 });
+}
+/**
+ * Undoes every out-of-scope edit made since `guard` was captured. A path the
+ * turn changed outside the scope returns to its state before the turn: its
+ * base content, its earlier out-of-scope content, or absence. In-scope work,
+ * ignored files and out-of-scope state that predates the turn stay untouched.
+ */
+export function discardOutOfScopeEdits(context, guard) {
+    const discarded = [];
+    for (const entry of guard.repositories) {
+        const repository = context.repositories.find(repo => repo.id === entry.id);
+        const now = outOfScope(repository, repositoryChanges(context, repository, entry.base, guard.change)).map(file => file.path);
+        const changedNow = new Set(now);
+        // A tracked file the turn returned to its base content leaves the change smaller: that clean-up stays.
+        const settled = [...entry.before.keys()].filter(file => !changedNow.has(file));
+        const tracked = settled.length && entry.base !== EMPTY_TREE ? new Set(git(repository.path, ['ls-tree', '-r', '-z', '--name-only', '--full-tree', entry.base, '--', ...settled]).stdout.split('\0').filter(Boolean)) : new Set();
+        const toBase = [];
+        for (const file of new Set([...now, ...entry.before.keys()])) {
+            const saved = entry.before.get(file);
+            if (!saved) {
+                toBase.push(file);
+                continue;
+            }
+            if (saved.fingerprint === fingerprintOf(path.join(repository.path, file)).fingerprint)
+                continue;
+            if (!changedNow.has(file) && tracked.has(file))
+                continue;
+            if (saved.fingerprint === 'missing' || saved.link !== undefined || saved.content) {
+                restorePrevious(repository, file, saved);
+                discarded.push({ repositoryId: repository.id, path: file, restored: 'previous' });
+            }
+            else
+                toBase.push(file);
+        }
+        discarded.push(...restoreFromBase(repository, entry.base, toBase));
+    }
+    return discarded.sort((a, b) => a.repositoryId.localeCompare(b.repositoryId) || a.path.localeCompare(b.path));
+}
+/** Bounded prompt lines for a change set; repository ids prefix the paths only when several repositories are in scope. */
+export function renderChangeSet(sets, limit = 150) {
+    const multiple = sets.length > 1;
+    const lines = [];
+    let hidden = 0;
+    for (const set of sets) {
+        for (const file of set.files) {
+            if (lines.length >= limit) {
+                hidden++;
+                continue;
+            }
+            lines.push(`- ${multiple ? '`' + set.repositoryId + '` ' : ''}\`${file.path}\` (${file.status})`);
+        }
+        if (set.truncated)
+            hidden++;
+    }
+    if (hidden)
+        lines.push(`- … ${hidden}${sets.some(set => set.truncated) ? '+' : ''} more not listed; compare against the base with git to see them.`);
+    return lines;
+}
+/** One human line naming discarded edits, bounded. */
+export function describeDiscarded(edits, multiple, limit = 12) {
+    const names = edits.map(edit => (multiple ? edit.repositoryId + ':' : '') + edit.path);
+    return names.slice(0, limit).join(', ') + (names.length > limit ? ` and ${names.length - limit} more` : '');
+}

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

@@ -21,6 +21,9 @@ interface CliInvocationOptions {
  * developer that cannot run tests iterates blind and fails verification.
  */
 export declare function buildCliInvocation(provider: CliProvider, request: AgentRequest, options?: CliInvocationOptions): CliInvocation;
+/** Native commands are data rendered for the selected provider; never shell text. */
+export declare function renderNativeCommand(provider: Exclude<CliProvider, 'kimi'>, command: NonNullable<AgentRequest['nativeCommand']>): string;
+export declare function kimiNativeSkill(id: string): string;
 interface ParsedCliResult extends AgentResult {
     terminal: boolean;
     failed: boolean;

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

@@ -2,13 +2,13 @@ import { codexOutputSchema, restoreOptionalFields } from './codex-schema.js';
 import { assertEffortSupported, cliCapabilities } from './capabilities.js';
 import { providerDiagnostic } from './provider-diagnostic.js';
 import { toolEvent } from './tool-event.js';
-import { openSpecPrompt, writeOpenSpecBridge } from './openspec.js';
+import { openSpecPrompt, openSpecPolicy, writeOpenSpecBridge } from './openspec.js';
 import { existsSync, readFileSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { sumCacheUsage } from './efficiency-types.js';
 import { normalizeKimiCliModel } from './kimi-model.js';
-import { AgentExecutionError, unknownUsage, validateAgentRequest } from './executor-types.js';
+import { AgentExecutionError, unknownUsage, normalizeAgentRequest, requestPolicy, isBuiltinRole } from './executor-types.js';
 import { runCliProcess } from './cli-process.js';
 import { canonicalWorkspace } from './workspace-tools.js';
 import { parseStructuredText } from './openai-executor.js';
@@ -23,22 +23,29 @@ const CLAUDE_DEVELOPER_DISALLOWED = 'Agent,Task,Skill';
  * developer that cannot run tests iterates blind and fails verification.
  */
 export function buildCliInvocation(provider, request, options = {}) {
-    const readOnly = request.role !== 'developer';
+    if (!isBuiltinRole(request.role) || request.access !== undefined || request.nativeCommand)
+        request = normalizeAgentRequest(request);
+    if (request.nativeCommand) {
+        if (provider === 'kimi')
+            throw new AgentExecutionError('Kimi commands require skill rendering before invocation', 'native_command_unsupported');
+        request = { ...request, prompt: renderNativeCommand(provider, request.nativeCommand) };
+    }
+    const readOnly = requestPolicy(request).access === 'read';
     // Pin the product alias; explicit IDs remain reproducible across releases.
     const modelId = provider === 'claude' && request.model === 'opus' ? 'claude-opus-5-5' : request.model;
     const model = modelId ? ['--model', modelId] : [];
     const extraRoots = request.allowedRoots.filter(root => root !== request.cwd);
     const resume = request.resumeSessionId;
     switch (provider) {
-        case 'claude': return { command: 'claude', stdin: request.prompt, args: [
-                '-p', '--output-format', 'stream-json', '--verbose', '--max-turns', String(request.maxTurns ?? 100), ...model,
+        case 'claude': return { command: 'claude', ...(request.nativeCommand ? {} : { stdin: request.prompt }), args: [
+                '-p', ...(request.nativeCommand ? [request.prompt] : []), '--output-format', 'stream-json', '--verbose', '--max-turns', String(request.maxTurns ?? 100), ...model,
                 ...(request.effort === undefined ? [] : ['--effort', request.effort]),
                 // Project instructions and rules stay visible; the user's global config,
                 // memory and plugins never leak into an autonomous role.
                 '--setting-sources', 'project,local',
                 ...(readOnly
-                    ? ['--tools', options.mcpConfigFile ? 'Read,Grep,Glob,ToolSearch' : 'Read,Grep,Glob', '--permission-mode', options.mcpConfigFile ? 'dontAsk' : 'plan', '--strict-mcp-config', ...(options.mcpConfigFile ? ['--allowedTools', 'Read,Grep,Glob,ToolSearch,mcp__specrails_openspec__workflow,mcp__specrails_openspec__read_verification_evidence'] : [])]
-                    : ['--tools', 'default', '--disallowedTools', CLAUDE_DEVELOPER_DISALLOWED, '--dangerously-skip-permissions']),
+                    ? ['--tools', request.nativeCommand ? 'Read,Grep,Glob,Skill' : options.mcpConfigFile ? 'Read,Grep,Glob,ToolSearch' : 'Read,Grep,Glob', '--permission-mode', options.mcpConfigFile ? 'dontAsk' : 'plan', '--strict-mcp-config', ...(options.mcpConfigFile ? ['--allowedTools', 'Read,Grep,Glob,ToolSearch,mcp__specrails_openspec__workflow,mcp__specrails_openspec__read_verification_evidence'] : [])]
+                    : ['--tools', 'default', '--disallowedTools', request.nativeCommand ? 'Agent,Task' : CLAUDE_DEVELOPER_DISALLOWED, '--dangerously-skip-permissions']),
                 ...(options.mcpConfigFile ? ['--mcp-config', options.mcpConfigFile] : []),
                 ...(request.outputSchema ? ['--json-schema', JSON.stringify(request.outputSchema)] : []),
                 ...(request.maxCostUsd === undefined ? [] : ['--max-budget-usd', String(request.maxCostUsd)]),
@@ -63,8 +70,8 @@ export function buildCliInvocation(provider, request, options = {}) {
         case 'gemini': {
             if (readOnly && !options.geminiPolicyFile)
                 throw new AgentExecutionError('Gemini architect/reviewer roles require --admin-policy support for an enforced read-only tool allowlist. Upgrade Gemini CLI or select another provider for this role.', 'provider_capability_unsupported');
-            return { command: 'gemini', stdin: request.prompt, args: [
-                    '-p', 'Execute the task supplied on stdin.', '--output-format', 'stream-json', ...model,
+            return { command: 'gemini', ...(request.nativeCommand ? {} : { stdin: request.prompt }), args: [
+                    '-p', request.nativeCommand ? request.prompt : 'Execute the task supplied on stdin.', '--output-format', 'stream-json', ...model,
                     // Headless Gemini cannot answer shell approvals; the developer runs with
                     // auto-approval exactly as the legacy Implement step did.
                     ...(readOnly ? ['--approval-mode', 'plan'] : ['--yolo']),
@@ -86,6 +93,34 @@ export function buildCliInvocation(provider, request, options = {}) {
         }
     }
 }
+/** Native commands are data rendered for the selected provider; never shell text. */
+export function renderNativeCommand(provider, command) {
+    return (provider === 'codex' ? '$' : '/') + command.id + (command.args ? ' ' + command.args : '');
+}
+export function kimiNativeSkill(id) {
+    const openspec = { 'opsx:ff': 'openspec-ff-change', 'opsx:apply': 'openspec-apply-change', 'opsx:verify': 'openspec-verify-change' };
+    const skill = openspec[id] ?? (id.startsWith('specrails:') ? id.replace('specrails:', 'specrails-') : id);
+    if (!/^[a-z][a-z0-9-]{0,63}$/.test(skill))
+        throw new AgentExecutionError('Kimi native command is unsupported', 'native_command_unsupported');
+    return skill;
+}
+async function renderKimiRequest(request, options) {
+    const skill = kimiNativeSkill(request.nativeCommand.id);
+    const runnerPath = path.join(request.cwd, '.kimi-code', 'specrails', 'run-skill.mjs');
+    if (!existsSync(runnerPath))
+        throw new AgentExecutionError('Kimi managed skill runner is not installed', 'native_command_unsupported');
+    const result = await (options.runProcess ?? runCliProcess)({ command: process.execPath, args: [runnerPath, '--skill', skill, '--model', request.model ?? 'kimi-for-coding', '--args', request.nativeCommand.args ?? '', ...(request.resumeSessionId ? ['--session', request.resumeSessionId] : []), '--render-only'] }, { cwd: request.cwd, signal: request.signal, timeoutMs: 10000, env: options.env });
+    if (result.exitCode !== 0)
+        throw new AgentExecutionError('Kimi native skill cannot be rendered', 'native_command_unsupported');
+    let prompt;
+    try {
+        prompt = JSON.parse(result.stdout).prompt;
+    }
+    catch { /* Invalid runner output cannot become a provider prompt. */ }
+    if (typeof prompt !== 'string' || !prompt.trim() || prompt.includes('\0') || Buffer.byteLength(prompt) > 1_048_576)
+        throw new AgentExecutionError('Invalid Kimi native skill prompt', 'native_command_unsupported');
+    return { ...request, prompt, nativeCommand: undefined };
+}
 function object(value) { return value && typeof value === 'object' && !Array.isArray(value) ? value : {}; }
 function number(value) { return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : null; }
 function textBlocks(value) {
@@ -244,7 +279,7 @@ export class CliExecutor {
     capabilities(model) { return cliCapabilities(this.provider, model, this.options); }
     capabilityChecks = new Map();
     async validateOpenSpec(context) {
-        const key = context.role === 'developer' ? 'write' : 'read';
+        const key = openSpecPolicy(context).access;
         let checked = this.capabilityChecks.get(key);
         if (!checked) {
             checked = (async () => {
@@ -266,11 +301,13 @@ export class CliExecutor {
             throw new AgentExecutionError('Kimi does not report authoritative token usage. Remove the token cap or select another provider for this role.', 'usage_unavailable');
     }
     async execute(request) {
-        validateAgentRequest(request);
+        request = normalizeAgentRequest(request);
         if (request.effort !== undefined)
             assertEffortSupported(request, await this.capabilities(request.model));
         this.validateLimits(request);
         const scope = canonicalWorkspace(request.cwd, request.allowedRoots);
+        if (this.provider === 'kimi' && request.nativeCommand)
+            request = await renderKimiRequest(request, this.options);
         const normalized = { ...request, prompt: (request.openspec ? openSpecPrompt(request.openspec) : '') + request.prompt, cwd: scope.cwd, allowedRoots: scope.roots };
         const runner = this.options.runProcess ?? runCliProcess;
         let temporary, kimiAgentFile, geminiPolicyFile, codexSchemaFile, stream = '', turns = 0, observedSession;
@@ -295,7 +332,7 @@ export class CliExecutor {
                 if (this.provider === 'kimi')
                     return await executeKimiReadonlyAcp(normalized, { ...this.options, openspecBridge });
             }
-            if (this.provider === 'gemini' && request.role !== 'developer') {
+            if (this.provider === 'gemini' && requestPolicy(request).access === 'read') {
                 assertGeminiAdminPolicyAvailable();
                 const help = await runner({ command: 'gemini', args: ['--help'] }, { cwd: scope.cwd, signal: request.signal, timeoutMs: 10_000, env: this.options.env });
                 if (help.exitCode !== 0 || !help.stdout.includes('--admin-policy'))
@@ -303,7 +340,7 @@ export class CliExecutor {
                 geminiPolicyFile = path.join(scratch(), 'readonly.toml');
                 writeFileSync(geminiPolicyFile, (openspecBridge ? '[[rule]]\nmcpName = "specrails_openspec"\ntoolName = "workflow"\ndecision = "allow"\npriority = 1000\n\n[[rule]]\nmcpName = "specrails_openspec"\ntoolName = "read_verification_evidence"\ndecision = "allow"\npriority = 1000\n\n' : '') + GEMINI_READONLY_POLICY, { mode: 0o600 });
             }
-            if (this.provider === 'kimi' && request.role !== 'developer') {
+            if (this.provider === 'kimi' && requestPolicy(request).access === 'read') {
                 const help = await runner({ command: 'kimi', args: ['--help'] }, { cwd: scope.cwd, signal: request.signal, timeoutMs: 10_000, env: this.options.env });
                 if (help.exitCode !== 0)
                     throw new AgentExecutionError('Cannot detect Kimi CLI capabilities', 'provider_capability_unsupported');

package/dist/agent-runtime/cli-process.js

@@ -62,6 +62,10 @@ export function cliProcessEnvironment(base, platform = process.platform) {
 export const runCliProcess = async (raw, options) => {
     if (options.signal?.aborted)
         throw new AgentExecutionError('Agent cancelled', 'aborted');
+    for (const value of [options.timeoutMs, options.idleTimeoutMs]) {
+        if (value !== undefined && (!Number.isSafeInteger(value) || value < 0 || value > 2_147_483_647))
+            throw new AgentExecutionError('Invalid process timeout', 'invalid_limit');
+    }
     const env = cliProcessEnvironment(options.env ?? process.env);
     const invocation = process.platform === 'win32' && raw.command === 'kimi' ? windowsKimiInvocation(raw, { env }) : raw;
     return new Promise((resolve, reject) => {
@@ -93,12 +97,12 @@ export const runCliProcess = async (raw, options) => {
         };
         const fail = (error) => { failure ??= error; terminate(); };
         const abort = () => fail(new AgentExecutionError('Agent cancelled', 'aborted'));
-        const timer = setTimeout(() => fail(new AgentExecutionError(`Agent reached the total execution limit (${options.timeoutMs} ms)`, 'timeout')), options.timeoutMs);
+        const timer = options.timeoutMs > 0 ? setTimeout(() => fail(new AgentExecutionError(`Agent reached the total execution limit (${options.timeoutMs} ms)`, 'timeout')), options.timeoutMs) : undefined;
         let idleTimer;
         const activity = () => {
             if (idleTimer)
                 clearTimeout(idleTimer);
-            if (options.idleTimeoutMs !== undefined && !failure)
+            if (options.idleTimeoutMs !== undefined && options.idleTimeoutMs > 0 && !failure)
                 idleTimer = setTimeout(() => fail(new AgentExecutionError(`Agent produced no output for ${options.idleTimeoutMs} ms (idle timeout)`, 'idle_timeout')), options.idleTimeoutMs);
         };
         activity();

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

@@ -1,4 +1,16 @@
 import type { WorkflowState } from './workflow-types.js';
+/** Both runtime entry points emit the same machine-readable fatal result. */
+export declare function runtimeFailure(error: unknown): {
+    type: string;
+    status: string;
+    error: string | {
+        details?: import("./workflow-types.js").JsonValue | undefined;
+        code: string;
+        message: string;
+    };
+};
+/** Machine operations are mirrored in integration-contract.json; help is presentation-only. */
+export declare const RUNTIME_CLI_OPERATIONS: readonly ["api", "validate", "run", "status", "resume", "prompts", "capabilities", "evidence", "recovery", "evaluate", "workflows", "fork", "signal", "cancel", "help"];
 /** The host-facing summary: phase status, pending interrupts and usage without accumulated outputs. */
 export declare function compactState(state: WorkflowState | null): {
     runId: string;
@@ -44,4 +56,7 @@ export declare function compactState(state: WorkflowState | null): {
     }[];
     metrics: import("./efficiency-types.js").RuntimeEfficiency;
 } | null;
+/** Engines this package can launch: the legacy built-in pipeline (1) and workflow definitions (2).
+ * Core 7 advertises [2] so hosts refuse unconverted legacy loops before admission. */
+export declare const RUNTIME_ENGINES: readonly number[];
 export declare function runRuntimeCommand(flags: Record<string, string | boolean>, positionals: string[], emit?: (value: unknown) => void): Promise<number>;