chati-dev 4.5.16 → 4.5.27

package/src/terminal/adapters/claude-adapter.js

@@ -18,7 +18,9 @@
  * @returns {{ command: string, args: string[], stdinPrompt: string|null }}
  */
 export function buildCommand(config, provider) {
-  const args = [...provider.baseArgs];
+  const readOnly = Array.isArray(config.writeScope) && config.writeScope.length === 0;
+  const args = provider.baseArgs.filter((argument) => !(readOnly && argument === '--dangerously-skip-permissions'));
+  if (readOnly) args.push('--permission-mode', 'plan', '--no-session-persistence');
   let effectiveModel = null;
 
   if (config.model) {

package/src/terminal/adapters/codex-adapter.js

@@ -14,6 +14,8 @@
  */
 export function buildCommand(config, provider) {
   const args = [...provider.baseArgs];
+  const readOnly = Array.isArray(config.writeScope) && config.writeScope.length === 0;
+  if (readOnly) args.push('-s', 'read-only', '--ephemeral');
   let effectiveModel = null;
 
   if (config.model) {

package/src/terminal/adapters/grok-adapter.js

@@ -1,12 +1,14 @@
 /**
  * Grok Build CLI adapter.
  *
- * Grok's supported headless form is `grok -p <prompt> -m <model>`. The prompt
- * deliberately remains an argument here because `-p` is the documented
- * non-interactive interface. This adapter does not silently select a model.
+ * Grok accepts a prompt file for headless execution. The spawner replaces the
+ * private-file marker with a descriptor-bound path, so prompt material never
+ * enters process arguments. This adapter does not silently select a model.
  */
 export function buildCommand(config, provider) {
   const args = [...provider.baseArgs];
+  const readOnly = Array.isArray(config.writeScope) && config.writeScope.length === 0;
+  if (readOnly) args.push('--permission-mode', 'plan', '--no-subagents', '--disable-web-search');
   let effectiveModel = null;
   if (config.model) {
     effectiveModel = provider.modelMap[config.model] || config.model;
@@ -15,11 +17,12 @@ export function buildCommand(config, provider) {
   if (config.reasoningConfiguration) {
     args.push('--reasoning-effort', config.reasoningConfiguration);
   }
-  args.push('-p', config.prompt || '');
+  args.push('--prompt-file', '<chati-private-prompt-file>');
   return {
     command: provider.command,
     args,
     stdinPrompt: null,
+    promptFile: config.prompt || '',
     effectiveModel,
     effectiveReasoningConfiguration: config.reasoningConfiguration || null,
   };

package/src/terminal/handoff-parser.js

@@ -9,6 +9,7 @@
  */
 
 import { validateSchema, HANDOFF_SCHEMA } from '../utils/schema-validator.js';
+import * as yaml from 'js-yaml';
 
 /**
  * Valid status values for handoff blocks.
@@ -81,9 +82,16 @@ export function validateHandoff(handoff) {
     }
   }
 
+  const missingInputQuestion = handoff.status === 'needs_input'
+    && (typeof handoff.needs_input_question !== 'string' || !handoff.needs_input_question.trim());
+  if (missingInputQuestion) {
+    warnings.push('needs_input status requires one non-empty needs_input_question');
+  }
+
   // A handoff is valid if there are no errors (warnings are OK)
   const hasErrors = schemaResult.errors.length > 0 ||
-    (handoff.status && !VALID_STATUSES.includes(handoff.status));
+    (handoff.status && !VALID_STATUSES.includes(handoff.status)) ||
+    missingInputQuestion;
 
   return { valid: !hasErrors, warnings };
 }
@@ -117,6 +125,14 @@ function parseHandoffFields(content) {
   };
 
   const lines = content.split('\n');
+  let yamlQuestion;
+  try {
+    const document = yaml.load(content, { schema: yaml.JSON_SCHEMA });
+    if (document && typeof document === 'object' && !Array.isArray(document)
+      && typeof document.needs_input_question === 'string') {
+      yamlQuestion = document.needs_input_question;
+    }
+  } catch { /* retain the permissive legacy field parser for malformed blocks */ }
   let currentKey = null;
   let currentType = null; // 'list' | 'map'
 
@@ -199,5 +215,7 @@ function parseHandoffFields(content) {
     }
   }
 
+  if (yamlQuestion !== undefined) result.needs_input_question = yamlQuestion === '' ? null : yamlQuestion;
+
   return result;
 }

package/src/terminal/prompt-builder.js

@@ -19,6 +19,7 @@ import { resolveProviderForAgent } from './cli-registry.js';
 import { buildCompactGotchasSummary } from '../memory/gotchas-injector.js';
 import { estimateTokens } from './cost-tracker.js';
 import { resolveContextLimit } from '../utils/provider-limits.js';
+import { V2_PLANNING_AGENTS } from '../orchestrator/runtime-installation-v2.js';
 
 // Import AGENT_MODELS from model-governance (safe — named export,
 // does not trigger main() which is guarded by fileURLToPath check).
@@ -131,7 +132,7 @@ export function buildToolMeshSection(agent) {
  * @property {string} projectDir      - Project root (absolute path)
  * @property {string} [previousAgent] - Agent that produced the handoff
  * @property {string} [workflow]      - Active workflow name
- * @property {object} [sessionState]  - Parsed session.yaml fields
+ * @property {object} [sessionState]  - Canonical session fields loaded by the session manager
  * @property {string[]} [writeScope]  - Override write scope
  * @property {string} [additionalContext] - Extra context (e.g. user answer to needs_input)
  * @property {string} [provider] - Active CLI provider (for overlay resolution)
@@ -153,6 +154,12 @@ export function buildAgentPrompt(config) {
     throw new Error('buildAgentPrompt requires config.projectDir');
   }
   const runtimeV2 = existsSync(join(config.projectDir, '.chati', 'v2', 'installation.json'));
+  if (runtimeV2 && !V2_PLANNING_AGENTS.includes(config.agent)) {
+    throw Object.assign(
+      new Error(`Runtime v2 does not expose the legacy ${config.agent} agent; implementation and release must use RAIL`),
+      { code: 'V2_RAIL_EXECUTION_REQUIRED' },
+    );
+  }
   if (runtimeV2 && (!config.provider || !config.model)) {
     throw new Error('Runtime v2 requires an exact routed provider and model binding');
   }
@@ -247,6 +254,7 @@ function buildSpawnAuthoritySection(config) {
 
 This process was launched by the active Chati.dev orchestrator for agent \`${config.agent}\`.
 Execute the assigned work now. Do not ask the user to activate Chati.dev, switch CLI, authenticate a provider, or restart the session.
+The canonical session context in this prompt is the only session state you may consume. Never read, parse, write, reconstruct, or edit \`.chati/session.yaml\` directly. Return state changes in the structured handoff so the parent router and session manager can persist them.
 If essential user information is missing, return status \`needs_input\` with exactly one concrete question in \`needs_input_question\`.
 Never claim that this spawned session is paused. The parent orchestrator owns user interaction and will relay your structured handoff.`;
 }

package/src/terminal/provider-preflight.js

@@ -3,8 +3,10 @@
  * execution. These checks never mutate provider configuration.
  */
 import { spawnSync } from 'node:child_process';
+import { closeSync } from 'node:fs';
 import { getProvider } from './cli-registry.js';
 import { cleanParentEnv } from './spawner.js';
+import { openPinnedProviderExecutable } from '../installer-v2/provider-executable.js';
 
 const CHECKS = {
   claude: { args: ['auth', 'status'], validate: validateClaude },
@@ -23,20 +25,52 @@ export function checkProviderReadiness(providerName, options = {}) {
   }
 
   const check = CHECKS[providerName] || { args: ['--version'], validate: validateExit };
+  let pinnedExecutable;
+  let command = provider.command;
+  let descriptorStdio;
+  try {
+    if (options.executableBinding) {
+      pinnedExecutable = openPinnedProviderExecutable(options.executableBinding, {
+        harnessId: providerName,
+        projectDir: options.workingDir,
+      });
+      // A readiness probe must target the exact binding selected by the signed
+      // installation. On Linux map the still-open descriptor to a fixed child
+      // FD and execute through it. A direct /proc/self/fd/<parent-fd> path is
+      // not sufficient because Node closes arbitrary parent descriptors in
+      // the child before exec. Other platforms retain the validated pathname.
+      if (process.platform === 'linux') {
+        command = '/proc/self/fd/3';
+        descriptorStdio = ['ignore', 'pipe', 'pipe', pinnedExecutable.descriptor];
+      } else {
+        command = pinnedExecutable.binding.executable_path;
+      }
+    }
+  } catch (error) {
+    return {
+      ready: false,
+      code: error?.code || 'PROVIDER_EXECUTABLE_BINDING_INVALID',
+      provider: providerName,
+      detail: error.message,
+    };
+  }
   let result;
   try {
-    result = runner(provider.command, check.args, {
+    result = runner(command, check.args, {
       cwd: options.workingDir || process.cwd(),
       env: cleanParentEnv(process.env),
       encoding: 'utf8',
       timeout: options.timeout || 30_000,
+      ...(descriptorStdio ? { stdio: descriptorStdio } : {}),
     });
   } catch (error) {
     return { ready: false, code: 'PROVIDER_PREFLIGHT_FAILED', provider: providerName, detail: error.message };
+  } finally {
+    if (pinnedExecutable) closeSync(pinnedExecutable.descriptor);
   }
 
   if (result?.error?.code === 'ENOENT') {
-    return { ready: false, code: 'PROVIDER_CLI_MISSING', provider: providerName, detail: `${provider.command} is not installed` };
+    return { ready: false, code: 'PROVIDER_CLI_MISSING', provider: providerName, detail: `${command} is not installed` };
   }
   return check.validate(result, providerName);
 }
@@ -75,4 +109,3 @@ function validateGrok(result, provider) {
   // that the CLI can load the trusted project and its effective config.
   return validateExit(result, provider);
 }
-

package/src/terminal/rail-execution-worktree.js

@@ -0,0 +1,213 @@
+import { execFileSync } from 'node:child_process';
+import { lstatSync, readFileSync, realpathSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { sha256 } from '@chati/core';
+
+const MAX_GIT_OUTPUT_BYTES = 128 * 1024 * 1024;
+const GIT_TIMEOUT_MS = 30_000;
+const CONTROL_PLANE_EXCLUDES = Object.freeze([
+  ':(exclude).chati',
+  ':(exclude).chati/**',
+  ':(exclude).chati.dev',
+  ':(exclude).chati.dev/**',
+]);
+
+function fail(code, message, details = {}) {
+  const error = new Error(message);
+  error.code = code;
+  error.details = details;
+  throw error;
+}
+
+function trustedGitEnvironment() {
+  const environment = { ...process.env };
+  for (const key of Object.keys(environment)) {
+    if (key.startsWith('GIT_')) delete environment[key];
+  }
+  return {
+    ...environment,
+    GIT_OPTIONAL_LOCKS: '0',
+    GIT_CONFIG_NOSYSTEM: '1',
+    GIT_CONFIG_GLOBAL: process.platform === 'win32' ? 'NUL' : '/dev/null',
+    GIT_TERMINAL_PROMPT: '0',
+  };
+}
+
+function git(projectDir, args, { encoding = 'utf8', timeout = GIT_TIMEOUT_MS } = {}) {
+  try {
+    return execFileSync('git', [
+      '-c', 'core.fsmonitor=false',
+      '-c', 'core.hooksPath=/dev/null',
+      '-C', projectDir,
+      ...args,
+    ], {
+      encoding,
+      timeout,
+      maxBuffer: MAX_GIT_OUTPUT_BYTES,
+      env: trustedGitEnvironment(),
+    });
+  } catch (error) {
+    return fail('RAIL_EXECUTION_GIT_STATE_UNAVAILABLE', 'cannot prove the Git state of the authorized execution worktree', {
+      cause: error.message,
+    });
+  }
+}
+
+function directoryIdentity(path) {
+  const stat = lstatSync(path);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) {
+    fail('RAIL_EXECUTION_REPOSITORY_INVALID', 'execution Git storage must resolve to a real directory');
+  }
+  return Object.freeze({
+    path: realpathSync(path),
+    dev: stat.dev,
+    ino: stat.ino,
+    uid: stat.uid,
+    gid: stat.gid,
+    mode: stat.mode,
+  });
+}
+
+function repositoryIdentity(projectDir) {
+  const root = realpathSync(resolve(projectDir));
+  const topLevel = realpathSync(git(root, ['rev-parse', '--show-toplevel']).trim());
+  if (topLevel !== root) {
+    fail('RAIL_EXECUTION_REPOSITORY_INVALID', 'authorized execution must run at the exact Git worktree root');
+  }
+  const gitEntryPath = resolve(root, '.git');
+  const gitEntryStat = lstatSync(gitEntryPath);
+  let gitEntry;
+  if (gitEntryStat.isDirectory() && !gitEntryStat.isSymbolicLink()) {
+    gitEntry = Object.freeze({
+      type: 'directory', dev: gitEntryStat.dev, ino: gitEntryStat.ino,
+      uid: gitEntryStat.uid, gid: gitEntryStat.gid, mode: gitEntryStat.mode,
+    });
+  } else if (gitEntryStat.isFile() && !gitEntryStat.isSymbolicLink() && gitEntryStat.size <= 4096) {
+    gitEntry = Object.freeze({
+      type: 'file', dev: gitEntryStat.dev, ino: gitEntryStat.ino,
+      uid: gitEntryStat.uid, gid: gitEntryStat.gid, mode: gitEntryStat.mode,
+      digest: sha256(readFileSync(gitEntryPath)),
+    });
+  } else {
+    fail('RAIL_EXECUTION_REPOSITORY_INVALID', 'execution .git entry must be a real directory or bounded regular worktree pointer');
+  }
+  const absoluteGitDir = git(root, ['rev-parse', '--absolute-git-dir']).trim();
+  const commonGitDirRaw = git(root, ['rev-parse', '--git-common-dir']).trim();
+  const commonGitDir = isAbsolute(commonGitDirRaw) ? commonGitDirRaw : resolve(root, commonGitDirRaw);
+  const rootStat = lstatSync(root);
+  return Object.freeze({
+    root: Object.freeze({
+      path: root, dev: rootStat.dev, ino: rootStat.ino,
+      uid: rootStat.uid, gid: rootStat.gid, mode: rootStat.mode,
+    }),
+    git_entry: gitEntry,
+    git_dir: directoryIdentity(absoluteGitDir),
+    common_git_dir: directoryIdentity(commonGitDir),
+  });
+}
+
+function worktreeStatus(projectDir) {
+  return git(projectDir, [
+    'status', '--porcelain=v1', '--untracked-files=all', '--', '.', ...CONTROL_PLANE_EXCLUDES,
+  ]);
+}
+
+function preexistingCommits(projectDir) {
+  const output = git(projectDir, [
+    'cat-file', '--batch-all-objects', '--batch-check=%(objectname) %(objecttype)',
+  ]);
+  const commits = output.split('\n').filter(Boolean).flatMap((line) => {
+    const [objectId, type, extra] = line.trim().split(/\s+/);
+    if (extra !== undefined || !/^[a-f0-9]{40,64}$/.test(objectId || '') || !type) {
+      fail('RAIL_EXECUTION_GIT_STATE_UNAVAILABLE', 'Git returned a malformed object inventory');
+    }
+    return type === 'commit' ? [objectId] : [];
+  });
+  return Object.freeze([...new Set(commits)].sort());
+}
+
+export function captureRailExecutionWorktree({ projectDir, baseCommitRef } = {}) {
+  if (!/^[a-f0-9]{40,64}$/.test(baseCommitRef || '')) {
+    fail('RAIL_EXECUTION_BASE_COMMIT_REQUIRED', 'authorized execution requires one full lowercase base commit id');
+  }
+  const root = realpathSync(resolve(projectDir));
+  const repository = repositoryIdentity(root);
+  const head = git(root, ['rev-parse', '--verify', 'HEAD^{commit}']).trim();
+  if (head !== baseCommitRef) {
+    fail('RAIL_EXECUTION_BASE_HEAD_MISMATCH', 'execution worktree HEAD must equal the exact authorized base commit', {
+      expected: baseCommitRef,
+      actual: head,
+    });
+  }
+  const status = worktreeStatus(root);
+  if (status !== '') {
+    fail('RAIL_EXECUTION_WORKTREE_DIRTY', 'execution worktree must be clean outside the protected CHATI control plane');
+  }
+  const commits = preexistingCommits(root);
+  if (!commits.includes(baseCommitRef)) {
+    fail('RAIL_EXECUTION_BASE_COMMIT_REQUIRED', 'authorized base commit is absent from the execution repository');
+  }
+  return Object.freeze({
+    schema_version: 1,
+    project_dir: root,
+    base_commit_ref: baseCommitRef,
+    launch_head_ref: head,
+    repository_identity: repository,
+    repository_identity_digest: sha256(repository),
+    preexisting_commits: commits,
+    preexisting_commits_digest: sha256(commits),
+  });
+}
+
+export function assertRailExecutionWorktreeBaselineUnchanged(baseline) {
+  const current = captureRailExecutionWorktree({
+    projectDir: baseline?.project_dir,
+    baseCommitRef: baseline?.base_commit_ref,
+  });
+  if (sha256(current) !== sha256(baseline)) {
+    fail('RAIL_EXECUTION_BASELINE_CHANGED', 'execution Git state changed between authority capture and provider launch');
+  }
+  return current;
+}
+
+export function verifyRailExecutionWorktreeResult({ baseline, resultCommitRef } = {}) {
+  if (!baseline || !/^[a-f0-9]{40,64}$/.test(resultCommitRef || '')) {
+    fail('RAIL_EXECUTION_OUTPUT_INVALID', 'execution worktree proof requires one full lowercase result commit id');
+  }
+  const repository = repositoryIdentity(baseline.project_dir);
+  if (sha256(repository) !== baseline.repository_identity_digest) {
+    fail('RAIL_EXECUTION_REPOSITORY_CHANGED', 'execution replaced or redirected its Git repository storage');
+  }
+  if (baseline.preexisting_commits.includes(resultCommitRef)) {
+    fail('RAIL_EXECUTION_RESULT_PREEXISTED', 'execution may not claim a commit that existed before its authorized launch');
+  }
+  const head = git(baseline.project_dir, ['rev-parse', '--verify', 'HEAD^{commit}']).trim();
+  if (head !== resultCommitRef) {
+    fail('RAIL_EXECUTION_RESULT_HEAD_MISMATCH', 'reported result commit must be the exact final execution worktree HEAD', {
+      reported: resultCommitRef,
+      actual: head,
+    });
+  }
+  try {
+    git(baseline.project_dir, ['merge-base', '--is-ancestor', baseline.base_commit_ref, resultCommitRef]);
+  } catch (error) {
+    if (error?.code === 'RAIL_EXECUTION_GIT_STATE_UNAVAILABLE') {
+      fail('RAIL_EXECUTION_RESULT_NOT_DESCENDANT', 'final execution HEAD must descend from the authorized base commit');
+    }
+    throw error;
+  }
+  if (worktreeStatus(baseline.project_dir) !== '') {
+    fail('RAIL_EXECUTION_WORKTREE_DIRTY', 'successful execution must commit every change outside the protected CHATI control plane');
+  }
+  return Object.freeze({
+    schema_version: 1,
+    base_commit_ref: baseline.base_commit_ref,
+    launch_head_ref: baseline.launch_head_ref,
+    result_commit_ref: resultCommitRef,
+    result_head_ref: head,
+    repository_identity_digest: baseline.repository_identity_digest,
+    preexisting_commits_digest: baseline.preexisting_commits_digest,
+    result_preexisted: false,
+    worktree_clean: true,
+  });
+}

package/src/terminal/rail-prompts.js

@@ -0,0 +1,169 @@
+import { resolve } from 'node:path';
+
+const RAIL_LANGUAGE_CONTRACTS = Object.freeze({
+  en: 'Visible-language contract: write all user-visible prose in English. Keep required machine-readable JSON keys, tags, identifiers and code unchanged.',
+  pt: 'Visible-language contract: write all user-visible prose in Brazilian Portuguese (pt-BR). Keep required machine-readable JSON keys, tags, identifiers and code unchanged.',
+  es: 'Visible-language contract: write all user-visible prose in Spanish. Keep required machine-readable JSON keys, tags, identifiers and code unchanged.',
+  fr: 'Visible-language contract: write all user-visible prose in French. Keep required machine-readable JSON keys, tags, identifiers and code unchanged.',
+});
+
+export function railLanguageContract(language = 'en') {
+  const contract = RAIL_LANGUAGE_CONTRACTS[language];
+  if (!contract) {
+    throw Object.assign(new Error(`Unsupported canonical RAIL language: ${language}`), { code: 'RAIL_SESSION_LANGUAGE_INVALID' });
+  }
+  return contract;
+}
+
+export function buildRailTaskPrompt({ projectDir, stored, task, invocation, browserManifest = null, language = invocation?.language ?? 'en' }) {
+  return [
+    'You are the execution operator for one immutable Chati.dev RAIL task.',
+    `Project root: ${resolve(projectDir)}`,
+    `Sealed handoff: ${stored.path}`,
+    `Task id: ${task.task_id}`,
+    '',
+    'The provider, model and reasoning configuration were selected by the signed installation and are immutable for this attempt.',
+    `Provider binding: ${invocation.provider_id}/${invocation.harness_id}`,
+    `Model pin: ${invocation.model_pin.model_id}`,
+    `Reasoning: ${invocation.model_pin.reasoning_configuration}`,
+    `Launch nonce: ${invocation.launch_nonce}`,
+    railLanguageContract(language),
+    '',
+    'Execute only the task below. Read the referenced project artifacts before editing. Do not expand scope, deploy, publish, or substitute another model.',
+    JSON.stringify({
+      task_id: task.task_id,
+      dependency_ids: task.dependency_ids,
+      execution_scope_ref: task.execution_scope_ref,
+      acceptance_criteria_refs: task.acceptance_criteria_refs,
+      routing_constraints_ref: task.routing_constraints_ref,
+      requires_browser: task.requires_browser === true,
+      browser_policy: task.browser_policy ?? null,
+      source_artifacts: stored.handoff.source_artifacts,
+      task_graph_ref: stored.handoff.task_graph_ref,
+      browser_delegation_manifest: browserManifest,
+    }, null, 2),
+    '',
+    `Sealed base commit: ${stored.handoff.seal.git_commit_ref}`,
+    'When finished, commit the complete task result as a new descendant of the sealed base commit. Then return exactly one machine-readable result envelope:',
+    '<CHATI_RAIL_EXECUTION>',
+    `{"result_commit_ref":"FULL_LOWERCASE_GIT_OBJECT_ID","launch_nonce":"${invocation.launch_nonce}"}`,
+    '</CHATI_RAIL_EXECUTION>',
+    'Outside the envelope you may report files changed, checks executed, remaining risks and evidence references. RAIL review and completion are separate canonical steps.',
+  ].join('\n');
+}
+
+export function buildRailReviewPrompt({ projectDir, context, invocation, reviewSubject, round }) {
+  return [
+    'You are an independent clean-context reviewer for one immutable Chati.dev RAIL attempt.',
+    `Project root: ${resolve(projectDir)}`,
+    `Handoff id: ${context.handoff.handoff_id}`,
+    `Task id: ${context.task.task_id}`,
+    `Attempt id: ${context.attempt.attempt_id}`,
+    `Review round: ${round}`,
+    `Sealed base commit: ${reviewSubject.base_commit_ref}`,
+    `Immutable result commit under review: ${reviewSubject.result_commit_ref}`,
+    ...(reviewSubject.workspace_digest ? [`Immutable review workspace digest: ${reviewSubject.workspace_digest}`] : []),
+    `Builder: ${context.task.execution_binding.provider_id}/${context.task.execution_binding.model_id}`,
+    `Reviewer pin: ${invocation.provider_id}/${invocation.model_pin.model_id}/${invocation.model_pin.reasoning_configuration}`,
+    `Launch nonce: ${invocation.launch_nonce}`,
+    railLanguageContract(invocation?.language ?? context?.language ?? 'en'),
+    '',
+    'Read the changed files and referenced artifacts yourself. The complete immutable delta is CHATI_RAIL_REVIEW.diff, including files omitted by Git archive metadata. Validate scope, acceptance criteria, architecture, tests, regressions and security. Do not edit files.',
+    'Use evidence-backed findings only. A valid issue uses disposition "accepted"; a disproven suspicion uses "rejected". If any accepted finding exists, verdict must be "rework".',
+    'Return exactly one JSON object between the tags below and no other tagged envelope:',
+    '<CHATI_RAIL_REVIEW>',
+    JSON.stringify({
+      findings: [{ finding_id: 'finding-unique', severity: 'critical|high|medium|low', location_ref: 'file://path:line', evidence_refs: ['evidence://specific'], disposition: 'accepted|rejected|unresolved', disposition_reason_ref: 'evidence://reason', root_cause_taxonomy: 'implementation|specification|architecture|security|test' }],
+      verdict: 'accept|rework|required-human-decision|blocked',
+      impasse: { kind: 'none|technical', evidence_ref: 'required only for technical' },
+      authority_reason: 'scope|security|privacy|cost|external-action only when verdict is required-human-decision',
+      authority_reason_ref: 'evidence ref only when required-human-decision',
+    }, null, 2),
+    '</CHATI_RAIL_REVIEW>',
+    '',
+    'Canonical task material:',
+    JSON.stringify({
+      execution_scope_ref: context.task.execution_scope_ref,
+      acceptance_criteria_refs: context.task.acceptance_criteria_refs,
+      routing_constraints_ref: context.task.routing_constraints_ref,
+      source_artifacts: context.handoff.source_artifacts,
+      task_graph_ref: context.handoff.task_graph_ref,
+    }, null, 2),
+  ].join('\n');
+}
+
+export function buildRailReworkPrompt({ projectDir, context, sourceReview, sourceAdjudication = null, executionHistory, baseCommitRef, invocation }) {
+  return [
+    'You are correcting one immutable Chati.dev RAIL attempt after an independent review.',
+    `Project root: ${resolve(projectDir)}`,
+    `Handoff id: ${context.handoff.handoff_id}`,
+    `Task id: ${context.task.task_id}`,
+    `Attempt id: ${context.attempt.attempt_id}`,
+    `Launch nonce: ${invocation.launch_nonce}`,
+    railLanguageContract(invocation?.language ?? context?.language ?? 'en'),
+    '',
+    'Use the exact original provider, model and reasoning binding. Address every accepted finding without expanding scope, deploying or publishing.',
+    'Read the referenced files and evidence yourself. Preserve unrelated user changes. Run the checks needed to prove each correction.',
+    '',
+    'Canonical accepted review:',
+    JSON.stringify(sourceReview, null, 2),
+    ...(sourceAdjudication ? [
+      '',
+      'Canonical adjudication and selected-council evidence:',
+      JSON.stringify(sourceAdjudication, null, 2),
+    ] : []),
+    '',
+    'Prior immutable execution evidence:',
+    JSON.stringify(executionHistory, null, 2),
+    '',
+    'Sealed task material:',
+    JSON.stringify({
+      execution_scope_ref: context.task.execution_scope_ref,
+      acceptance_criteria_refs: context.task.acceptance_criteria_refs,
+      routing_constraints_ref: context.task.routing_constraints_ref,
+      source_artifacts: context.handoff.source_artifacts,
+      task_graph_ref: context.handoff.task_graph_ref,
+    }, null, 2),
+    '',
+    `Bound rework base commit: ${baseCommitRef}`,
+    'When finished, commit the complete corrected result as a new descendant of that bound base. Then return exactly one machine-readable result envelope:',
+    '<CHATI_RAIL_EXECUTION>',
+    `{"result_commit_ref":"FULL_LOWERCASE_GIT_OBJECT_ID","launch_nonce":"${invocation.launch_nonce}"}`,
+    '</CHATI_RAIL_EXECUTION>',
+    'Outside the envelope you may report corrected findings, files changed, checks executed, remaining risks and evidence references. A new independent review is mandatory.',
+  ].join('\n');
+}
+
+export function buildRailAdjudicationPrompt({ projectDir, context, plan, invocation, reviews, executions, priorDecisions, round, reviewSubject = null }) {
+  return [
+    'You are one selected top-tier adjudicator for a Chati.dev RAIL technical impasse.',
+    `Project root: ${resolve(projectDir)}`,
+    `Handoff id: ${context.handoff.handoff_id}`,
+    `Task id: ${context.task.task_id}`,
+    `Attempt id: ${context.attempt.attempt_id}`,
+    `Adjudication round: ${round}`,
+    ...(reviewSubject?.result_commit_ref ? [`Immutable result commit under adjudication: ${reviewSubject.result_commit_ref}`] : []),
+    ...(reviewSubject?.workspace_digest ? [`Immutable adjudication workspace digest: ${reviewSubject.workspace_digest}`] : []),
+    `Exact model pin: ${invocation.provider_id}/${invocation.model_pin.model_id}/${invocation.model_pin.reasoning_configuration}`,
+    `Launch nonce: ${invocation.launch_nonce}`,
+    railLanguageContract(invocation?.language ?? context?.language ?? 'en'),
+    '',
+    'Read the project evidence yourself. Do not edit files, deploy, publish or widen scope.',
+    'Choose only: bounded-correction for a technically local correction, handoff-revision when sealed planning must change, or blocked-authority only for scope, security, privacy, cost or external-action authority.',
+    priorDecisions?.length ? 'The previous independent decisions disagreed. Reconcile them using evidence, not majority or vendor preference.' : '',
+    'Return exactly one JSON object inside the required tags:',
+    '<CHATI_RAIL_ADJUDICATION>',
+    JSON.stringify({
+      outcome: 'bounded-correction|handoff-revision|blocked-authority',
+      decision_ref: 'evidence://adjudicator/decision',
+      correction_ref: 'evidence://correction (bounded-correction only)',
+      handoff_revision_ref: 'evidence://handoff-revision (handoff-revision only)',
+      authority_reason: 'scope|security|privacy|cost|external-action (blocked-authority only)',
+      authority_reason_ref: 'evidence://authority (blocked-authority only)',
+    }, null, 2),
+    '</CHATI_RAIL_ADJUDICATION>',
+    '',
+    'Canonical review decision and evidence:',
+    JSON.stringify({ plan, reviews, executions, prior_decisions: priorDecisions || [] }, null, 2),
+  ].filter(Boolean).join('\n');
+}