chati-dev 4.5.11 → 4.5.13

package/src/installer/templates.js

@@ -175,14 +175,14 @@ export function generateConfigYaml(config) {
     model_fallback: true,
     frustration_detection: true,
     bash_security_checks: true,
-    // Agent Teams (Article XXI) — default ON in v4.2.2.
+    // Agent Teams are planning-only in runtime v2.
     // Only effective when the active session runs in Claude (gated in cli.js
     // isAgentTeamsEnabled). Gemini and Codex always fall back to sequential
     // pipeline silently. See plan: was previously false for "safe rollout"
     // but the v4.2.0 launch never actually shipped, so this is a fresh start.
     agent_teams: true,
     team_planning_size: 4,
-    team_build_size: 2,
+    ...(config.runtimeVersion === 2 ? {} : { team_build_size: 2 }),
     team_echo_threshold: 0.92,
     team_correction_cycles_max: 2,
   };
@@ -229,12 +229,42 @@ name: chati
 description: >
   Use this skill when the user wants to start or continue a Chati.dev session.
   This activates the orchestrator which routes to the correct agent in the pipeline.
-  Invoke when the user mentions chati, /chati, wants to plan, build, or deploy a project.
+  Invoke when the user mentions chati, /chati, or wants to discover, plan, execute, or release a project.
   Do NOT use for general coding questions unrelated to the Chati.dev pipeline.
 ---
 
 # Chati.dev Orchestrator
 
+## STEP 0 — Run the deterministic router (MUST be the first action)
+
+Use the shell in the current project directory and run:
+
+\`\`\`bash
+node .chati.dev/orchestrator/chati-router.js
+\`\`\`
+
+Do not infer provider authentication, session state, model availability, or the
+next pipeline action from files or prior messages. The router output is the
+source of truth. Do not tell the user to log in unless the router or the exact
+routed spawn command returns a provider authentication error.
+
+Parse the JSON output before responding:
+
+- If \`ok\` is \`false\`, report the exact \`error\` and relevant detail, then stop.
+- If \`ok\` is \`true\`, use \`session.language\` for every response.
+- Follow the returned \`action\` in the adapted orchestrator.
+- When the action includes \`pipeline.spawn_command\`, execute that exact command.
+  Never replace it with an inferred provider check or a manually constructed command.
+- A router-provided spawn command starts an external provider CLI. Execute it
+  with native escalated execution: set \`sandbox_permissions\` to
+  \`require_escalated\`, preserve the exact command and working directory, and
+  offer the narrow reusable prefix
+  \`["node", "<absolute path from spawn_command to run-agent.js>"]\`.
+- Do not run that provider command inside the workspace sandbox first. A
+  \`PROVIDER_NOT_READY\` or \`PROVIDER_NOT_AUTHENTICATED\` result from a sandboxed
+  attempt is not proof that the user is logged out. Rerun it once with native
+  escalation before reporting an authentication failure.
+
 ## CRITICAL: Language Override
 
 Read \`.chati/session.yaml\` field \`language\` BEFORE anything else.

package/src/installer/validator.js

@@ -17,6 +17,7 @@ function resolveFrameworkDir(targetDir) {
  * Checks all primary agents, constitution, session, schemas, etc.
  */
 export async function validateInstallation(targetDir) {
+  const isRuntimeV2 = existsSync(join(targetDir, '.chati', 'v2', 'installation.json'));
   const results = {
     agents: { pass: false, details: [] },
     constitution: { pass: false, details: [] },
@@ -35,7 +36,7 @@ export async function validateInstallation(targetDir) {
   };
 
   // Check all primary agents (orchestrator + 12 specialized, sub-agents validated by managers)
-  const agentFiles = [
+  const planningAgentFiles = [
     'orchestrator/chati.md',
     'agents/discover/greenfield-wu.md',
     'agents/discover/brownfield-wu.md',
@@ -46,10 +47,15 @@ export async function validateInstallation(targetDir) {
     'agents/plan/phases.md',
     'agents/plan/tasks.md',
     'agents/quality/qa-planning.md',
+  ];
+  const legacyExecutionAgentFiles = [
     'agents/quality/qa-implementation.md',
     'agents/build/dev.md',
     'agents/deploy/devops.md',
   ];
+  const agentFiles = isRuntimeV2
+    ? planningAgentFiles
+    : [...planningAgentFiles, ...legacyExecutionAgentFiles];
 
   let agentCount = 0;
   for (const file of agentFiles) {
@@ -64,7 +70,7 @@ export async function validateInstallation(targetDir) {
       results.agents.details.push({ file, exists: false, hasProtocols: false });
     }
   }
-  results.agents.pass = agentCount === 13;
+  results.agents.pass = agentCount === agentFiles.length;
   results.total += 1;
   if (results.agents.pass) results.passed += 1;
 

package/src/intelligence/registry-manager.js

@@ -158,21 +158,28 @@ export function runHealthCheck(targetDir) {
   }
 
   // 4. Agent check
-  const agentPaths = [
+  const planningAgentPaths = [
     'orchestrator/chati.md',
     'agents/discover/greenfield-wu.md', 'agents/discover/brownfield-wu.md',
     'agents/discover/brief.md', 'agents/plan/detail.md',
     'agents/plan/architect.md', 'agents/plan/ux.md',
     'agents/plan/phases.md', 'agents/plan/tasks.md',
-    'agents/quality/qa-planning.md', 'agents/quality/qa-implementation.md',
+    'agents/quality/qa-planning.md',
+  ];
+  const legacyExecutionAgentPaths = [
+    'agents/quality/qa-implementation.md',
     'agents/build/dev.md', 'agents/deploy/devops.md',
   ];
+  const isRuntimeV2 = existsSync(join(targetDir, '.chati', 'v2', 'installation.json'));
+  const agentPaths = isRuntimeV2
+    ? planningAgentPaths
+    : [...planningAgentPaths, ...legacyExecutionAgentPaths];
   let foundAgents = 0;
   for (const p of agentPaths) {
     if (existsSync(join(targetDir, fwDir, p))) foundAgents++;
   }
-  checks.agents.pass = foundAgents === 13;
-  checks.agents.details = `${foundAgents}/13 present`;
+  checks.agents.pass = foundAgents === agentPaths.length;
+  checks.agents.details = `${foundAgents}/${agentPaths.length} present`;
 
   // 5. Entity validation (registry vs filesystem)
   const entityResult = validateEntities(targetDir);

package/src/orchestrator/cli.js

@@ -79,6 +79,8 @@ const LOCK_START = '<!-- chati-lock:start -->';
 const LOCK_END = '<!-- chati-lock:end -->';
 const STATE_START = '<!-- chati-state:start -->';
 const STATE_END = '<!-- chati-state:end -->';
+const PAUSE_START = '<!-- chati-pause:start -->';
+const PAUSE_END = '<!-- chati-pause:end -->';
 
 const RESUME_MESSAGES = {
   en: 'Session saved. Type /chati anytime to resume.',
@@ -700,9 +702,32 @@ function replaceBlock(content, startMarker, endMarker, newInner) {
   return content.trimEnd() + '\n\n' + block + '\n';
 }
 
+function sessionLockTargets(projectDir) {
+  const frameworkDir = resolveFrameworkDir(projectDir);
+  return [
+    { path: join(projectDir, 'CLAUDE.local.md'), invocation: '/chati', provider: 'claude' },
+    { path: join(projectDir, 'AGENTS.override.md'), invocation: '$chati', provider: 'codex' },
+    { path: join(projectDir, '.grok', 'session-lock.md'), invocation: '/chati', provider: 'grok' },
+    { path: join(projectDir, '.gemini', 'session-lock.md'), invocation: '/chati', provider: 'gemini' },
+  ].map(target => ({
+    ...target,
+    orchestratorPath: existsSync(join(projectDir, frameworkDir, '.adapted', target.provider, 'orchestrator', 'chati.md'))
+      ? `${frameworkDir}/.adapted/${target.provider}/orchestrator/chati.md`
+      : `${frameworkDir}/orchestrator/chati.md`,
+  })).filter(({ path }) => path.endsWith('CLAUDE.local.md') || existsSync(path));
+}
+
+function removeLegacyPauseSection(content) {
+  let clean = content.replace(
+    /\n*<!-- chati-pause:start -->[\s\S]*?<!-- chati-pause:end -->\n*/g,
+    '\n'
+  );
+  // Migrate the unmarked block emitted by releases before 4.5.12.
+  clean = clean.replace(/\n+## Session Paused\n+[\s\S]*?(?=\n## |\n---|$)/g, '\n');
+  return clean;
+}
+
 function writeSessionLock(projectDir, currentAgent, stateInfo = {}) {
-  const localMdPath = join(projectDir, 'CLAUDE.local.md');
-  let content = existsSync(localMdPath) ? readFileSync(localMdPath, 'utf-8') : '';
 
   // Phase display is authoritatively driven by session.mode on disk. Callers
   // previously passed stateInfo.phase derived from transient intermediate
@@ -715,50 +740,51 @@ function writeSessionLock(projectDir, currentAgent, stateInfo = {}) {
     if (loaded && session?.mode) authoritativePhase = session.mode;
   } catch { /* non-fatal — fall back to stateInfo */ }
 
-  const lockInner = `## Session Lock -- ACTIVE
-
-**Chati.dev session is ACTIVE.** Follow these rules for EVERY message:
-
-1. Read \`${resolveFrameworkDir(projectDir)}/orchestrator/chati.md\` and follow its routing logic
-2. Route ALL user messages through the current agent: \`${currentAgent}\`
-3. NEVER respond outside of the Chati.dev system
-4. The ONLY way to exit is via \`/chati exit\`, \`/chati stop\`, or \`/chati quit\``;
-
   const stateInner = `## Current State
 - **Agent**: ${currentAgent || 'None'}
 - **Phase**: ${authoritativePhase || stateInfo.phase || 'discover'}
 - **Pipeline**: ${stateInfo.position ?? 0}/${stateInfo.total ?? '?'} (${stateInfo.progress ?? 0}%)
 - **Mode**: ${stateInfo.mode || 'interactive'}`;
 
-  content = replaceBlock(content, LOCK_START, LOCK_END, lockInner);
-  content = replaceBlock(content, STATE_START, STATE_END, stateInner);
-  writeFileSync(localMdPath, content, 'utf-8');
+  for (const target of sessionLockTargets(projectDir)) {
+    let content = removeLegacyPauseSection(existsSync(target.path) ? readFileSync(target.path, 'utf-8') : '');
+    const lockInner = `## Session Lock: ACTIVE
+
+**Chati.dev session is ACTIVE.** Follow these rules for EVERY message:
+
+1. Read \`${target.orchestratorPath}\` and follow its routing logic
+2. Route ALL user messages through the current agent: \`${currentAgent}\`
+3. NEVER respond outside of the Chati.dev system
+4. The ONLY way to exit is via \`${target.invocation} exit\`, \`${target.invocation} stop\`, or \`${target.invocation} quit\``;
+    content = replaceBlock(content, LOCK_START, LOCK_END, lockInner);
+    content = replaceBlock(content, STATE_START, STATE_END, stateInner);
+    writeFileSync(target.path, content.trimEnd() + '\n', 'utf-8');
+  }
 }
 
 /**
  * Remove session lock block from CLAUDE.local.md.
  */
 function removeSessionLock(projectDir, resumeMsg) {
-  const localMdPath = join(projectDir, 'CLAUDE.local.md');
-  if (!existsSync(localMdPath)) return;
-
-  let content = readFileSync(localMdPath, 'utf-8');
-
-  const lockInner = `## Session Lock
-**Status: INACTIVE** — Type \`/chati\` to activate.`;
   const stateInner = `## Current State
 - **Agent**: None (ready to start)
 - **Pipeline**: Pre-start
 - **Mode**: interactive`;
 
-  content = replaceBlock(content, LOCK_START, LOCK_END, lockInner);
-  content = replaceBlock(content, STATE_START, STATE_END, stateInner);
-
-  if (resumeMsg) {
-    content = content.trimEnd() + `\n\n## Session Paused\n\n${resumeMsg}\n`;
+  for (const target of sessionLockTargets(projectDir)) {
+    let content = removeLegacyPauseSection(existsSync(target.path) ? readFileSync(target.path, 'utf-8') : '');
+    const lockInner = `## Session Lock
+**Status: INACTIVE**: Type \`${target.invocation}\` to activate.`;
+    content = replaceBlock(content, LOCK_START, LOCK_END, lockInner);
+    content = replaceBlock(content, STATE_START, STATE_END, stateInner);
+
+    if (resumeMsg) {
+      const providerMessage = resumeMsg.replaceAll('/chati', target.invocation);
+      const pauseBlock = `${PAUSE_START}\n## Session Paused\n\n${providerMessage}\n${PAUSE_END}`;
+      content = content.trimEnd() + `\n\n${pauseBlock}\n`;
+    }
+    writeFileSync(target.path, content.trimEnd() + '\n', 'utf-8');
   }
-
-  writeFileSync(localMdPath, content.trimEnd() + '\n', 'utf-8');
 }
 
 // ---------------------------------------------------------------------------

package/src/terminal/handoff-parser.js

@@ -14,7 +14,15 @@ import { validateSchema, HANDOFF_SCHEMA } from '../utils/schema-validator.js';
  * Valid status values for handoff blocks.
  * @type {string[]}
  */
-const VALID_STATUSES = ['APPROVED', 'NEEDS_REVISION', 'BLOCKED', 'unknown'];
+const VALID_STATUSES = [
+  'complete', 'partial', 'needs_input', 'error', 'unknown',
+  'APPROVED', 'NEEDS_REVISION', 'BLOCKED',
+];
+const LEGACY_STATUS_ALIASES = {
+  APPROVED: 'complete',
+  NEEDS_REVISION: 'partial',
+  BLOCKED: 'needs_input',
+};
 
 /**
  * Parse the <chati-handoff> block from agent stdout.
@@ -36,6 +44,7 @@ export function parseAgentOutput(output) {
 
   const content = match[1].trim();
   const handoff = parseHandoffFields(content);
+  handoff.status = LEGACY_STATUS_ALIASES[handoff.status] || handoff.status;
 
   // Validate the parsed handoff
   const { valid, warnings } = validateHandoff(handoff);
@@ -114,10 +123,11 @@ function parseHandoffFields(content) {
   for (const line of lines) {
     const trimmed = line.trim();
     if (!trimmed) continue;
+    const indentation = line.length - line.trimStart().length;
 
     // Check if this is a list item (  - value)
     const listMatch = trimmed.match(/^-\s+(.+)/);
-    if (listMatch && currentKey && currentType === 'list') {
+    if (indentation > 0 && listMatch && currentKey && currentType === 'list') {
       if (Array.isArray(result[currentKey])) {
         result[currentKey].push(listMatch[1].trim());
       }
@@ -126,7 +136,7 @@ function parseHandoffFields(content) {
 
     // Check if this is a map item (  key: value) under a map key
     const mapMatch = trimmed.match(/^(\w[\w_-]*):\s+(.+)/);
-    if (mapMatch && currentKey && currentType === 'map') {
+    if (indentation > 0 && mapMatch && currentKey && currentType === 'map') {
       if (typeof result[currentKey] === 'object' && !Array.isArray(result[currentKey])) {
         result[currentKey][mapMatch[1]] = mapMatch[2].trim();
       }
@@ -145,7 +155,10 @@ function parseHandoffFields(content) {
         currentType = 'list';
         // If value is inline (not empty), treat as single item
         if (value && value !== '') {
-          result[key] = [value];
+          if (value === '[]') result[key] = [];
+          else if (value.startsWith('[') && value.endsWith(']')) {
+            result[key] = value.slice(1, -1).split(',').map(item => item.trim()).filter(Boolean);
+          } else result[key] = [value];
           currentKey = null;
           currentType = null;
         }
@@ -154,6 +167,12 @@ function parseHandoffFields(content) {
 
       // Known map keys
       if (['decisions'].includes(key)) {
+        if (value === '{}') {
+          result[key] = {};
+          currentKey = null;
+          currentType = null;
+          continue;
+        }
         currentKey = key;
         currentType = 'map';
         continue;

package/src/terminal/prompt-builder.js

@@ -212,7 +212,11 @@ export function buildAgentPrompt(config) {
   // 9. Anti-laziness reinforcement (proven remediation techniques)
   sections.push(buildAntiLazinessSection(config.agent));
 
-  // 10. Output format instructions (handoff template — includes provider/model for audit)
+  // 10. Spawn authority. This late prompt section wins over stale provider
+  // context that may have been loaded before the synchronized session lock.
+  sections.push(buildSpawnAuthoritySection(config));
+
+  // 11. Output format instructions (handoff template — includes provider/model for audit)
   sections.push(buildOutputInstructions({ provider: resolvedProvider, model }));
 
   const prompt = sections.join('\n\n---\n\n');
@@ -233,6 +237,16 @@ export function buildAgentPrompt(config) {
   };
 }
 
+function buildSpawnAuthoritySection(config) {
+  return `<!-- SPAWN AUTHORITY -->
+## Active Orchestrator Assignment
+
+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.
+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.`;
+}
+
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------

package/src/terminal/provider-preflight.js

@@ -0,0 +1,78 @@
+/**
+ * Deterministic provider readiness checks used immediately before a routed
+ * execution. These checks never mutate provider configuration.
+ */
+import { spawnSync } from 'node:child_process';
+import { getProvider } from './cli-registry.js';
+import { cleanParentEnv } from './spawner.js';
+
+const CHECKS = {
+  claude: { args: ['auth', 'status'], validate: validateClaude },
+  codex: { args: ['login', 'status'], validate: validateCodex },
+  grok: { args: ['inspect'], validate: validateGrok },
+  gemini: { args: ['--version'], validate: validateExit },
+};
+
+export function checkProviderReadiness(providerName, options = {}) {
+  const runner = options.runner || spawnSync;
+  let provider;
+  try {
+    provider = getProvider(providerName);
+  } catch (error) {
+    return { ready: false, code: 'PROVIDER_UNKNOWN', provider: providerName, detail: error.message };
+  }
+
+  const check = CHECKS[providerName] || { args: ['--version'], validate: validateExit };
+  let result;
+  try {
+    result = runner(provider.command, check.args, {
+      cwd: options.workingDir || process.cwd(),
+      env: cleanParentEnv(process.env),
+      encoding: 'utf8',
+      timeout: options.timeout || 30_000,
+    });
+  } catch (error) {
+    return { ready: false, code: 'PROVIDER_PREFLIGHT_FAILED', provider: providerName, detail: error.message };
+  }
+
+  if (result?.error?.code === 'ENOENT') {
+    return { ready: false, code: 'PROVIDER_CLI_MISSING', provider: providerName, detail: `${provider.command} is not installed` };
+  }
+  return check.validate(result, providerName);
+}
+
+function outputOf(result) {
+  return `${result?.stdout || ''}\n${result?.stderr || ''}`.trim();
+}
+
+function validateExit(result, provider) {
+  return result?.status === 0
+    ? { ready: true, code: 'PROVIDER_READY', provider }
+    : { ready: false, code: 'PROVIDER_NOT_READY', provider, detail: outputOf(result).slice(0, 500) };
+}
+
+function validateClaude(result, provider) {
+  if (result?.status !== 0) return validateExit(result, provider);
+  try {
+    const status = JSON.parse(result.stdout || '{}');
+    return status.loggedIn === true
+      ? { ready: true, code: 'PROVIDER_READY', provider }
+      : { ready: false, code: 'PROVIDER_NOT_AUTHENTICATED', provider, detail: 'Claude CLI reports loggedIn=false' };
+  } catch {
+    return { ready: false, code: 'PROVIDER_PREFLIGHT_INVALID', provider, detail: 'Claude CLI returned an invalid auth status' };
+  }
+}
+
+function validateCodex(result, provider) {
+  if (result?.status !== 0) return validateExit(result, provider);
+  return /logged in/i.test(outputOf(result))
+    ? { ready: true, code: 'PROVIDER_READY', provider }
+    : { ready: false, code: 'PROVIDER_NOT_AUTHENTICATED', provider, detail: 'Codex CLI did not confirm an authenticated session' };
+}
+
+function validateGrok(result, provider) {
+  // Grok currently exposes no stable auth-status command. `inspect` proves
+  // that the CLI can load the trusted project and its effective config.
+  return validateExit(result, provider);
+}
+

package/src/terminal/run-agent.js

@@ -15,8 +15,9 @@
 
 import { fileURLToPath } from 'url';
 import { buildAgentPrompt } from './prompt-builder.js';
-import { spawnTerminal } from './spawner.js';
+import { isTransientFailure, spawnTerminalWithRetry } from './spawner.js';
 import { parseAgentOutput } from './handoff-parser.js';
+import { checkProviderReadiness } from './provider-preflight.js';
 import { createCostTracker } from './cost-tracker.js';
 import { getRateLimiter } from './rate-limiter.js';
 import { initCollector, track as telemetryTrack, flush as telemetryFlush } from '../telemetry/collector.js';
@@ -104,6 +105,11 @@ async function main() {
 
   // Wait for rate limit slot before spawning
   const spawnProvider = promptResult.provider || args.provider || 'claude';
+  const readiness = checkProviderReadiness(spawnProvider, { workingDir: projectDir });
+  if (!readiness.ready) {
+    outputResult({ status: 'error', error: readiness.detail, code: readiness.code, provider: spawnProvider });
+    process.exit(1);
+  }
   const limiter = getRateLimiter(spawnProvider);
   if (!limiter.canSpawn()) {
     const rateLimitStart = Date.now();
@@ -121,7 +127,7 @@ async function main() {
   let handle;
 
   try {
-    handle = spawnTerminal({
+    const spawnConfig = {
       agent: args.agent,
       taskId: args['task-id'],
       model: promptResult.model,
@@ -133,31 +139,25 @@ async function main() {
       providerId: args['provider-id'] || null,
       reasoningConfiguration: args['reasoning-configuration'] || null,
       catalogSnapshotRef: args['catalog-snapshot-ref'] || null,
+    };
+    handle = await spawnTerminalWithRetry(spawnConfig, {
+      maxRetries: 1,
+      baseDelay: 500,
+      enableModelFallback: args['strict-provider'] !== 'true',
+      shouldRetry(exitCode, output) {
+        const combined = Array.isArray(output) ? output.join('') : String(output || '');
+        return isTransientFailure(exitCode, combined) || /not logged in|not authenticated/i.test(combined);
+      },
     });
   } catch (err) {
     outputError(`Failed to spawn terminal: ${err.message}`);
     process.exit(1);
   }
 
-  // Wait for the process to complete
-  try {
-    await waitForExit(handle, timeout);
-  } catch (err) {
-    telemetryTrack('error_occurred', {
-      errorType: 'agent_failure',
-      agent: args.agent,
-      provider: promptResult.provider || args.provider || 'claude',
-      reasoningConfiguration: args['reasoning-configuration'] || null,
-      phase: sessionState?.phase || 'unknown',
-    });
-    await flushAndSend(projectDir);
-    outputError(`Terminal execution failed: ${err.message}`);
-    process.exit(2);
-  }
-
   const elapsed = Date.now() - startTime;
   const stdout = handle.stdout.join('');
   const stderr = handle.stderr.join('');
+  const providerOutput = `${stdout}\n${stderr}`;
 
   // Track cost metrics
   const tracker = createCostTracker();
@@ -186,7 +186,7 @@ async function main() {
     model: costRecord.model,
     duration: elapsed,
     score: null, // Score is determined by the gate, not the agent
-    retryCount: 0,
+    retryCount: handle.retryCount || 0,
     pipelineType: sessionState?.isQuickFlow ? 'quick-flow' : 'standard',
   });
 
@@ -210,7 +210,19 @@ async function main() {
   // Parse the handoff from stdout
   const parsed = parseAgentOutput(stdout);
 
-  if (parsed.found) {
+  if (handle.exitCode !== 0 && /not logged in|not authenticated/i.test(providerOutput)) {
+    outputResult({
+      status: 'error',
+      code: 'PROVIDER_AUTH_STATE_MISMATCH',
+      error: `${spawnProvider} passed preflight but rejected the spawned execution`,
+      provider: spawnProvider,
+      exitCode: handle.exitCode,
+      retryCount: handle.retryCount || 0,
+    });
+    process.exit(1);
+  }
+
+  if (parsed.found && parsed.valid) {
     outputResult({
       status: parsed.handoff.status,
       agent: args.agent,
@@ -222,15 +234,33 @@ async function main() {
       elapsed,
       costEstimate,
     });
+  } else if (recoverInteractiveHandoff(args.agent, stdout, handle.exitCode)) {
+    // Interactive discovery models sometimes answer with the user-facing
+    // question but omit the machine block. Preserve the exact question while
+    // restoring the deterministic relay contract for the parent orchestrator.
+    outputResult({
+      status: 'needs_input',
+      agent: args.agent,
+      model: promptResult.model,
+      provider: promptResult.provider || args.provider || 'claude',
+      exitCode: handle.exitCode,
+      handoff: recoverInteractiveHandoff(args.agent, stdout, handle.exitCode),
+      contractRecovery: 'interactive_output_wrapped',
+      elapsed,
+      costEstimate,
+    });
   } else {
-    // No handoff block found — return raw output
+    // A non-interactive agent that omits the handoff violated the execution
+    // contract and cannot be treated as successful or partially complete.
     outputResult({
-      status: handle.exitCode === 0 ? 'partial' : 'error',
+      status: 'error',
+      code: parsed.found ? 'INVALID_HANDOFF' : 'MISSING_HANDOFF',
       agent: args.agent,
       model: promptResult.model,
       provider: promptResult.provider || args.provider || 'claude',
       exitCode: handle.exitCode,
-      handoff: null,
+      handoff: parsed.handoff,
+      handoffWarnings: parsed.warnings,
       rawOutput: stdout.slice(0, 5000), // Truncate to avoid huge JSON
       stderr: stderr.slice(0, 2000),
       elapsed,
@@ -306,6 +336,19 @@ function outputError(message) {
   process.stdout.write(JSON.stringify({ status: 'error', error: message }) + '\n');
 }
 
+export function recoverInteractiveHandoff(agent, stdout, exitCode) {
+  if (exitCode !== 0 || !['greenfield-wu', 'brownfield-wu', 'brief'].includes(agent) || !stdout?.trim()) return null;
+  return {
+    status: 'needs_input',
+    score: null,
+    summary: 'Interactive agent requested user input.',
+    outputs: [],
+    decisions: {},
+    blockers: [],
+    needs_input_question: stdout.trim(),
+  };
+}
+
 /**
  * Minimal YAML parser for session.yaml (handles flat and one-level nested keys).
  */

package/src/terminal/spawner.js

@@ -579,11 +579,13 @@ export async function spawnTerminalWithRetry(config, retryOptions = {}) {
 
     // Success — return immediately
     if (handle.exitCode === 0) {
+      handle.retryCount = attempt;
       return handle;
     }
 
     // Check if failure is transient and retries remain
-    if (attempt < maxRetries && shouldRetry(handle.exitCode, handle.stderr)) {
+    const combinedOutput = [...(handle.stdout || []), ...(handle.stderr || [])];
+    if (attempt < maxRetries && shouldRetry(handle.exitCode, combinedOutput, handle)) {
       const delay = baseDelay * Math.pow(2, attempt);
       await new Promise(resolve => setTimeout(resolve, delay));
       continue;
@@ -617,9 +619,11 @@ export async function spawnTerminalWithRetry(config, retryOptions = {}) {
         timestamp: new Date().toISOString(),
       };
 
+      fallbackHandle.retryCount = maxRetries;
       return fallbackHandle;
     }
   }
 
+  if (lastHandle) lastHandle.retryCount = lastHandle.retryCount ?? maxRetries;
   return lastHandle;
 }

package/src/utils/schema-validator.js

@@ -169,7 +169,7 @@ export const SESSION_SCHEMA = {
   properties: {
     project: { type: 'string', required: true, minLength: 1 },
     language: { type: 'string', required: true, default: 'en' },
-    pipeline_phase: { type: 'string', enum: ['discover', 'plan', 'build', 'deploy', 'completed'] },
+    pipeline_phase: { type: 'string', enum: ['discover', 'plan', 'rail', 'release', 'build', 'validate', 'deploy', 'completed'] },
     current_agent: { type: 'string' },
     governance_mode: { type: 'string', enum: ['planning', 'build', 'deploy'] },
     execution_mode: { type: 'string', enum: ['interactive', 'autonomous'] },
@@ -201,7 +201,10 @@ export const CONFIG_SCHEMA = {
 export const HANDOFF_SCHEMA = {
   required: ['status'],
   properties: {
-    status: { type: 'string', required: true, enum: ['APPROVED', 'NEEDS_REVISION', 'BLOCKED', 'unknown'] },
+    status: { type: 'string', required: true, enum: [
+      'complete', 'partial', 'needs_input', 'error', 'unknown',
+      'APPROVED', 'NEEDS_REVISION', 'BLOCKED',
+    ] },
     score: { type: 'number', min: 0, max: 100 },
     summary: { type: 'string', maxLength: 2000 },
     outputs: { type: 'array' },

package/src/wizard/index.js

@@ -185,6 +185,7 @@ export async function runWizard(targetDir, options = {}) {
       modelSelections,
       targetDir,
       version: VERSION,
+      runtimeVersion: 2,
     };
     v2InstallationInput = buildWizardV2InstallationInput({
       projectName,