chati-dev 4.5.15 → 4.5.27

package/src/terminal/run-agent.js

@@ -14,8 +14,12 @@
  */
 
 import { fileURLToPath } from 'url';
+import { randomUUID } from 'node:crypto';
+import { closeSync, constants, existsSync, fstatSync, lstatSync, openSync, readSync, realpathSync, rmSync } from 'fs';
+import { isAbsolute, relative, resolve } from 'path';
 import { buildAgentPrompt } from './prompt-builder.js';
 import { isTransientFailure, spawnTerminalWithRetry } from './spawner.js';
+import { getWriteScope } from './isolation.js';
 import { parseAgentOutput } from './handoff-parser.js';
 import { checkProviderReadiness } from './provider-preflight.js';
 import { createCostTracker } from './cost-tracker.js';
@@ -23,6 +27,37 @@ import { getRateLimiter } from './rate-limiter.js';
 import { initCollector, track as telemetryTrack, flush as telemetryFlush } from '../telemetry/collector.js';
 import { sendEvents } from '../telemetry/sender.js';
 import { getTelemetryConfig, isEnabled as isTelemetryEnabled } from '../telemetry/config.js';
+import {
+  recordPendingInteraction, clearPendingInteraction,
+  claimPendingInteraction, releasePendingInteraction,
+  loadSession, startAgentExecution, holdAgentExecutionForAdvance, releaseAgentExecution,
+} from '../orchestrator/session-manager.js';
+import { recordEvent, EventType } from '../intelligence/timeline.js';
+import {
+  assertRuntimeCommandV2, loadRuntimeInstallationV2, resolveRuntimeExecutableBindingV2,
+} from '../orchestrator/runtime-installation-v2.js';
+
+const RUN_AGENT_SECURITY_TEST_HOOKS = Symbol.for('chati.run-agent.security-test-hooks');
+const ADDITIONAL_CONTEXT_MAX_BYTES = 256 * 1024;
+const ADDITIONAL_CONTEXT_MAX_BYTES_BIGINT = BigInt(ADDITIONAL_CONTEXT_MAX_BYTES);
+
+function runSecurityTestHook(name, detail) {
+  const hook = globalThis[RUN_AGENT_SECURITY_TEST_HOOKS]?.[name];
+  if (typeof hook === 'function') hook(detail);
+}
+
+function sameAdditionalContextSnapshot(left, right) {
+  return Boolean(left && right
+    && left.dev === right.dev
+    && left.ino === right.ino
+    && left.mode === right.mode
+    && left.uid === right.uid
+    && left.gid === right.gid
+    && left.nlink === right.nlink
+    && left.size === right.size
+    && left.mtimeNs === right.mtimeNs
+    && left.ctimeNs === right.ctimeNs);
+}
 
 // ---------------------------------------------------------------------------
 // CLI argument parsing (no external deps)
@@ -35,7 +70,12 @@ function parseArgs(argv) {
     if (arg.startsWith('--')) {
       const key = arg.slice(2);
       const next = argv[i + 1];
-      if (next && !next.startsWith('--')) {
+      if (key === 'additional-context' && next !== undefined && !next.startsWith('--')) {
+        args[key] = next;
+        i++;
+      } else if (key === 'additional-context') {
+        args[key] = null;
+      } else if (next && !next.startsWith('--')) {
         args[key] = next;
         i++;
       } else {
@@ -66,21 +106,106 @@ async function main() {
   const projectDir = args['project-dir'] || process.cwd();
   const timeout = parseInt(args.timeout, 10) || 600_000; // default 10 minutes
 
+  const runtimeRoute = validateRuntimeCommand(projectDir, args);
+  if (!runtimeRoute.ok) {
+    if (args['execution-claim-id']) {
+      releaseAgentExecution(projectDir, { agent: args.agent, claimId: args['execution-claim-id'] });
+    }
+    outputResult({
+      status: 'error',
+      code: runtimeRoute.code,
+      error: runtimeRoute.error,
+      agent: args.agent,
+      wait_for_user: false,
+    });
+    process.exit(1);
+  }
+
+  // A fresh dispatch uses the one-shot execution claim. A resumed interactive
+  // relay carries an interaction identity and is serialized separately by
+  // claimPendingInteraction after the response file is validated.
+  if (runtimeRoute.artifact && !args['interaction-id']) {
+    const execution = startAgentExecution(projectDir, {
+      agent: args.agent,
+      claimId: args['execution-claim-id'] || null,
+    });
+    if (!execution.saved || !execution.started) {
+      outputResult({
+        status: 'error',
+        code: execution.code || 'SESSION_WRITE_FAILED',
+        error: execution.error,
+        agent: args.agent,
+        wait_for_user: false,
+      });
+      process.exit(1);
+    }
+    process.once('exit', () => {
+      releaseAgentExecution(projectDir, {
+        agent: args.agent,
+        claimId: args['execution-claim-id'],
+      });
+    });
+  }
+
+  const responseFile = loadAdditionalContextFile(projectDir, args);
+  if (!responseFile.ok) {
+    outputResult({
+      status: 'error',
+      code: responseFile.code,
+      error: responseFile.error,
+      agent: args.agent,
+      wait_for_user: true,
+    });
+    process.exit(1);
+  }
+  if (responseFile.response !== null) args['additional-context'] = responseFile.response;
+
+  // A session awaiting user input is a local state gate, not a provider
+  // preflight concern. Check it before looking for a CLI so a missing or
+  // empty relay response cannot be masked by a host-specific CLI absence.
+  if (typeof args['additional-context'] !== 'string' || !args['additional-context'].trim()) {
+    const pendingGuard = claimPendingInteraction(projectDir, {
+      interactionId: args['interaction-id'] || null,
+      agent: args.agent,
+      taskId: args['task-id'],
+      provider: args.provider || null,
+      providerId: args['provider-id'] || null,
+      model: args.model || null,
+      reasoningConfiguration: args['reasoning-configuration'] || null,
+      catalogSnapshotRef: args['catalog-snapshot-ref'] || null,
+      response: args['additional-context'],
+      reasoningEscalation: args['reasoning-escalation'] === 'true',
+    });
+    if (!pendingGuard.saved || !pendingGuard.allowed) {
+      outputResult({
+        status: 'error',
+        code: pendingGuard.code || 'SESSION_WRITE_FAILED',
+        error: pendingGuard.error,
+        agent: args.agent,
+        wait_for_user: true,
+      });
+      process.exit(1);
+    }
+  }
+
   // Initialize telemetry for this process
   initCollector(isTelemetryEnabled(projectDir));
 
   // Load session state if available
   let sessionState = {};
-  try {
-    const { existsSync, readFileSync } = await import('fs');
-    const { join } = await import('path');
-    const sessionPath = join(projectDir, '.chati', 'session.yaml');
-    if (existsSync(sessionPath)) {
-      const raw = readFileSync(sessionPath, 'utf-8');
-      sessionState = parseSimpleYaml(raw);
-    }
-  } catch (err) {
-    process.stderr.write(`[chati] run-agent session-parse: ${err.message}\n`);
+  const loadedSession = loadSession(projectDir);
+  if (loadedSession.loaded) {
+    sessionState = loadedSession.session || {};
+  } else if (existsSync(resolve(projectDir, '.chati', 'session.yaml'))
+    || !['Session file not found', 'Session directory not found'].includes(loadedSession.error)) {
+    outputResult({
+      status: 'error',
+      code: 'INVALID_SESSION_PATH',
+      error: loadedSession.error,
+      agent: args.agent,
+      wait_for_user: false,
+    });
+    process.exit(1);
   }
 
   // Build the agent prompt
@@ -99,6 +224,11 @@ async function main() {
       strictProvider: args['strict-provider'] === 'true',
     });
   } catch (err) {
+    const relayState = releasePendingForFailedRelay(projectDir, args);
+    if (!relayState.saved) {
+      outputResult({ status: 'error', code: 'SESSION_WRITE_FAILED', error: relayState.error, cause: err.message });
+      process.exit(1);
+    }
     outputError(`Failed to build prompt: ${err.message}`);
     process.exit(1);
   }
@@ -106,11 +236,23 @@ async function main() {
   // Wait for rate limit slot before spawning
   const spawnProvider = promptResult.provider || args.provider;
   if (!spawnProvider) {
+    const relayState = releasePendingForFailedRelay(projectDir, args);
+    if (!relayState.saved) {
+      outputResult({ status: 'error', code: 'SESSION_WRITE_FAILED', error: relayState.error, cause: 'PROVIDER_MISSING' });
+      process.exit(1);
+    }
     outputError('No routed provider was supplied for agent execution');
     process.exit(1);
   }
-  const readiness = checkProviderReadiness(spawnProvider, { workingDir: projectDir });
+  const readiness = checkProviderReadiness(spawnProvider, {
+    workingDir: projectDir, executableBinding: runtimeRoute.executableBinding || undefined,
+  });
   if (!readiness.ready) {
+    const relayState = releasePendingForFailedRelay(projectDir, args);
+    if (!relayState.saved) {
+      outputResult({ status: 'error', code: 'SESSION_WRITE_FAILED', error: relayState.error, cause: readiness.code });
+      process.exit(1);
+    }
     outputResult({ status: 'error', error: readiness.detail, code: readiness.code, provider: spawnProvider });
     process.exit(1);
   }
@@ -126,6 +268,34 @@ async function main() {
     });
   }
 
+  // Reserve the relay only after local preparation and rate limiting. The
+  // lease therefore covers provider execution, not unbounded queue time.
+  const pendingClaim = claimPendingInteraction(projectDir, {
+    interactionId: args['interaction-id'] || null,
+    agent: args.agent,
+    taskId: args['task-id'],
+    provider: args.provider || null,
+    providerId: args['provider-id'] || null,
+    model: args.model || null,
+    reasoningConfiguration: args['reasoning-configuration'] || null,
+    catalogSnapshotRef: args['catalog-snapshot-ref'] || null,
+    response: args['additional-context'],
+    reasoningEscalation: args['reasoning-escalation'] === 'true',
+    leaseExpiresAt: new Date(Date.now() + (timeout * 2) + 5 * 60 * 1000).toISOString(),
+  });
+  if (!pendingClaim.saved || !pendingClaim.allowed) {
+    cleanupRejectedResponseFile(responseFile.filePath, pendingClaim);
+    outputResult({
+      status: 'error',
+      code: pendingClaim.code || 'SESSION_WRITE_FAILED',
+      error: pendingClaim.error,
+      agent: args.agent,
+      wait_for_user: true,
+    });
+    process.exit(1);
+  }
+  if (pendingClaim.claimed) args['relay-claim-id'] = pendingClaim.claimId;
+
   // Spawn the agent terminal
   const startTime = Date.now();
   let handle;
@@ -143,17 +313,34 @@ async function main() {
       providerId: args['provider-id'] || null,
       reasoningConfiguration: args['reasoning-configuration'] || null,
       catalogSnapshotRef: args['catalog-snapshot-ref'] || null,
+      providerExecutableBinding: runtimeRoute.executableBinding || undefined,
+      ...(runtimeRoute.artifact ? {
+        writeScope: getWriteScope(args.agent, projectDir),
+        authorityContext: {
+          authority_kind: 'planning_execution',
+          invocation_id: `planning:${args.agent}:${args['task-id']}:${randomUUID()}`,
+          launch_nonce: randomUUID(),
+          provider_id: runtimeRoute.invocation.provider_id,
+        },
+      } : {}),
     };
     handle = await spawnTerminalWithRetry(spawnConfig, {
       maxRetries: 1,
       baseDelay: 500,
-      enableModelFallback: args['strict-provider'] !== 'true',
+      // The orchestrator must execute the routed model exactly. A silent
+      // downgrade would make the persisted binding and cost record false.
+      enableModelFallback: false,
       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) {
+    const relayState = releasePendingForFailedRelay(projectDir, args);
+    if (!relayState.saved) {
+      outputResult({ status: 'error', code: 'SESSION_WRITE_FAILED', error: relayState.error, cause: err.message });
+      process.exit(1);
+    }
     outputError(`Failed to spawn terminal: ${err.message}`);
     process.exit(1);
   }
@@ -213,8 +400,14 @@ async function main() {
 
   // Parse the handoff from stdout
   const parsed = parseAgentOutput(stdout);
+  const recovered = recoverInteractiveHandoff(args.agent, stdout, handle.exitCode);
 
   if (handle.exitCode !== 0 && /not logged in|not authenticated/i.test(providerOutput)) {
+    const relayState = releasePendingForFailedRelay(projectDir, args);
+    if (!relayState.saved) {
+      outputResult({ status: 'error', code: 'SESSION_WRITE_FAILED', error: relayState.error, cause: 'PROVIDER_AUTH_STATE_MISMATCH' });
+      process.exit(1);
+    }
     outputResult({
       status: 'error',
       code: 'PROVIDER_AUTH_STATE_MISMATCH',
@@ -226,7 +419,46 @@ async function main() {
     process.exit(1);
   }
 
+  // A syntactically valid handoff is not a successful execution when the
+  // provider process itself failed. In particular, a resumed relay must keep
+  // both its pending interaction and response file intact so the exact user
+  // answer can be retried. Persisting a trailing `complete` block from a failed
+  // process would clear that state and make the next CLI redispatch from zero.
+  if (handle.exitCode !== 0) {
+    const relayState = releasePendingForFailedRelay(projectDir, args);
+    if (!relayState.saved) {
+      outputResult({ status: 'error', code: 'SESSION_WRITE_FAILED', error: relayState.error, cause: 'PROVIDER_EXECUTION_FAILED' });
+      process.exit(1);
+    }
+    outputResult({
+      status: 'error',
+      code: 'PROVIDER_EXECUTION_FAILED',
+      error: `${spawnProvider} exited unsuccessfully; its handoff was not committed`,
+      provider: spawnProvider,
+      exitCode: handle.exitCode,
+      retryCount: handle.retryCount || 0,
+      agent: args.agent,
+    });
+    process.exit(1);
+  }
+
   if (parsed.found && parsed.valid) {
+    const persistence = persistInteractiveState(projectDir, args, parsed.handoff, promptResult.model, spawnProvider);
+    if (!persistence.saved) {
+      outputResult({ status: 'error', code: 'SESSION_WRITE_FAILED', error: persistence.error, agent: args.agent });
+      process.exit(1);
+    }
+    if (parsed.handoff.status !== 'needs_input' && handle.exitCode === 0) {
+      const held = holdAgentExecutionForAdvance(projectDir, {
+        agent: args.agent,
+        claimId: args['interaction-id'] ? null : (args['execution-claim-id'] || null),
+      });
+      if (!held.saved || !held.held) {
+        outputResult({ status: 'error', code: held.code || 'SESSION_WRITE_FAILED', error: held.error, agent: args.agent });
+        process.exit(1);
+      }
+    }
+    cleanupResponseFile(responseFile.filePath);
     outputResult({
       status: parsed.handoff.status,
       agent: args.agent,
@@ -235,20 +467,30 @@ async function main() {
       reasoningConfiguration: args['reasoning-configuration'] || null,
       exitCode: handle.exitCode,
       handoff: parsed.handoff,
+      ...(parsed.handoff.status === 'needs_input' && parsed.handoff.needs_input_question
+        ? { needs_input_question: parsed.handoff.needs_input_question }
+        : {}),
       elapsed,
       costEstimate,
     });
-  } else if (recoverInteractiveHandoff(args.agent, stdout, handle.exitCode)) {
+  } else if (recovered) {
     // 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.
+    const persistence = persistInteractiveState(projectDir, args, recovered, promptResult.model, spawnProvider);
+    if (!persistence.saved) {
+      outputResult({ status: 'error', code: 'SESSION_WRITE_FAILED', error: persistence.error, agent: args.agent });
+      process.exit(1);
+    }
+    cleanupResponseFile(responseFile.filePath);
     outputResult({
       status: 'needs_input',
       agent: args.agent,
       model: promptResult.model,
       provider: spawnProvider,
       exitCode: handle.exitCode,
-      handoff: recoverInteractiveHandoff(args.agent, stdout, handle.exitCode),
+      handoff: recovered,
+      needs_input_question: recovered.needs_input_question,
       contractRecovery: 'interactive_output_wrapped',
       elapsed,
       costEstimate,
@@ -256,6 +498,11 @@ async function main() {
   } else {
     // A non-interactive agent that omits the handoff violated the execution
     // contract and cannot be treated as successful or partially complete.
+    const relayState = releasePendingForFailedRelay(projectDir, args);
+    if (!relayState.saved) {
+      outputResult({ status: 'error', code: 'SESSION_WRITE_FAILED', error: relayState.error, cause: parsed.found ? 'INVALID_HANDOFF' : 'MISSING_HANDOFF' });
+      process.exit(1);
+    }
     outputResult({
       status: 'error',
       code: parsed.found ? 'INVALID_HANDOFF' : 'MISSING_HANDOFF',
@@ -275,6 +522,177 @@ async function main() {
   process.exit(handle.exitCode === 0 ? 0 : 1);
 }
 
+function cleanupResponseFile(filePath) {
+  if (!filePath) return { removed: false, error: null };
+  try {
+    rmSync(filePath);
+    return { removed: true, error: null };
+  } catch (err) {
+    if (err.code === 'ENOENT') return { removed: false, error: null };
+    process.stderr.write(`[chati] response-file cleanup failed: ${err.message}\n`);
+    return { removed: false, error: err.message };
+  }
+}
+
+export function cleanupRejectedResponseFile(filePath, claim = {}) {
+  if (claim.code !== 'PENDING_INTERACTION_NOT_FOUND') {
+    return { removed: false, preserved: Boolean(filePath), error: null };
+  }
+  return cleanupResponseFile(filePath);
+}
+
+function persistInteractiveState(projectDir, args, handoff, model, provider) {
+  if (handoff?.status === 'needs_input' && handoff.needs_input_question) {
+    const result = recordPendingInteraction(projectDir, {
+      agent: args.agent,
+      taskId: args['reasoning-escalation'] === 'true'
+        ? `${args['task-id']}-post-escalation`
+        : args['task-id'],
+      question: handoff.needs_input_question,
+      provider,
+      providerId: args['provider-id'] || null,
+      model,
+      reasoningConfiguration: args['reasoning-configuration'] || null,
+      catalogSnapshotRef: args['catalog-snapshot-ref'] || null,
+      advanceRelay: Boolean(args['additional-context']?.trim()),
+    });
+    recordEvent(projectDir, EventType.AGENT_WAITING_FOR_INPUT, args.agent, {
+      task_id: args['task-id'],
+    });
+    return result;
+  }
+  return clearPendingInteraction(projectDir, {
+    agent: args.agent,
+    taskId: args['task-id'],
+    interactionId: args['interaction-id'] || null,
+    claimId: args['relay-claim-id'] || null,
+  });
+}
+
+export function loadAdditionalContextFile(projectDir, args = {}) {
+  const fileArg = args['additional-context-file'];
+  if (!fileArg) return { ok: true, response: null, filePath: null };
+  if (typeof fileArg !== 'string') {
+    return { ok: false, code: 'INVALID_ADDITIONAL_CONTEXT_FILE', error: '--additional-context-file requires a path value.' };
+  }
+  if (args['additional-context'] !== undefined && args['additional-context'] !== null) {
+    return { ok: false, code: 'AMBIGUOUS_ADDITIONAL_CONTEXT', error: 'Use either --additional-context-file or --additional-context, not both.' };
+  }
+  const projectRoot = resolve(projectDir);
+  const chatiRoot = resolve(projectRoot, '.chati');
+  const runtimeRoot = resolve(chatiRoot, 'runtime');
+  const filePath = resolve(fileArg);
+  if (!existsSync(chatiRoot) || lstatSync(chatiRoot).isSymbolicLink() || !lstatSync(chatiRoot).isDirectory()) {
+    return { ok: false, code: 'INVALID_ADDITIONAL_CONTEXT_FILE', error: 'The .chati directory must be a real directory.' };
+  }
+  if (!existsSync(runtimeRoot) || lstatSync(runtimeRoot).isSymbolicLink() || !lstatSync(runtimeRoot).isDirectory()) {
+    return { ok: false, code: 'INVALID_ADDITIONAL_CONTEXT_FILE', error: 'The .chati/runtime directory must be a real directory.' };
+  }
+  const realProjectRoot = realpathSync(projectRoot);
+  const realChatiRoot = realpathSync(chatiRoot);
+  const chatiRel = relative(realProjectRoot, realChatiRoot);
+  if (!chatiRel || chatiRel.startsWith('..') || isAbsolute(chatiRel)) {
+    return { ok: false, code: 'INVALID_ADDITIONAL_CONTEXT_FILE', error: 'The .chati directory must remain inside the project.' };
+  }
+  const realRuntimeRoot = realpathSync(runtimeRoot);
+  const runtimeRel = relative(realChatiRoot, realRuntimeRoot);
+  if (!runtimeRel || runtimeRel.startsWith('..') || isAbsolute(runtimeRel)) {
+    return { ok: false, code: 'INVALID_ADDITIONAL_CONTEXT_FILE', error: 'The runtime directory must remain inside .chati.' };
+  }
+  const realFilePath = existsSync(filePath) ? realpathSync(filePath) : filePath;
+  const rel = relative(realRuntimeRoot, realFilePath);
+  if (!rel || rel.startsWith('..') || isAbsolute(rel)) {
+    return { ok: false, code: 'INVALID_ADDITIONAL_CONTEXT_FILE', error: 'Response file must be inside .chati/runtime.' };
+  }
+  if (!existsSync(filePath)) {
+    return { ok: false, code: 'ADDITIONAL_CONTEXT_FILE_MISSING', error: 'Pending response file does not exist.' };
+  }
+  const pathStat = lstatSync(filePath, { bigint: true });
+  if (!pathStat.isFile() || pathStat.isSymbolicLink()) {
+    return { ok: false, code: 'INVALID_ADDITIONAL_CONTEXT_FILE', error: 'Pending response path must be a regular file.' };
+  }
+  if (pathStat.size > ADDITIONAL_CONTEXT_MAX_BYTES_BIGINT) {
+    return { ok: false, code: 'ADDITIONAL_CONTEXT_FILE_TOO_LARGE', error: 'Pending response exceeds the 256 KiB limit.', filePath };
+  }
+  let fd;
+  try {
+    fd = openSync(
+      filePath,
+      constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0),
+    );
+    const openedStat = fstatSync(fd, { bigint: true });
+    if (!openedStat.isFile() || openedStat.nlink !== 1n
+      || !sameAdditionalContextSnapshot(pathStat, openedStat)) {
+      return { ok: false, code: 'INVALID_ADDITIONAL_CONTEXT_FILE', error: 'Pending response changed while it was being validated.', filePath };
+    }
+    if (openedStat.size > ADDITIONAL_CONTEXT_MAX_BYTES_BIGINT) {
+      return { ok: false, code: 'ADDITIONAL_CONTEXT_FILE_TOO_LARGE', error: 'Pending response exceeds the 256 KiB limit.', filePath };
+    }
+    runSecurityTestHook('afterAdditionalContextStat', { path: filePath });
+    const bytes = Buffer.allocUnsafe(ADDITIONAL_CONTEXT_MAX_BYTES + 1);
+    let total = 0;
+    while (total < bytes.length) {
+      const bytesRead = readSync(fd, bytes, total, bytes.length - total, null);
+      if (bytesRead === 0) break;
+      total += bytesRead;
+    }
+    if (total > ADDITIONAL_CONTEXT_MAX_BYTES) {
+      return { ok: false, code: 'ADDITIONAL_CONTEXT_FILE_TOO_LARGE', error: 'Pending response exceeds the 256 KiB limit.', filePath };
+    }
+    const finalStat = fstatSync(fd, { bigint: true });
+    const finalPathStat = lstatSync(filePath, { bigint: true });
+    if (!sameAdditionalContextSnapshot(openedStat, finalStat)
+      || !sameAdditionalContextSnapshot(finalStat, finalPathStat)) {
+      return { ok: false, code: 'INVALID_ADDITIONAL_CONTEXT_FILE', error: 'Pending response changed while it was being read.', filePath };
+    }
+    const payload = JSON.parse(bytes.subarray(0, total).toString('utf8'));
+    if (typeof payload?.response !== 'string' || !payload.response.trim()) {
+      return { ok: false, code: 'EMPTY_ADDITIONAL_CONTEXT', error: 'Pending response must contain a non-empty JSON string field named response.', filePath };
+    }
+    return { ok: true, response: payload.response, filePath };
+  } catch {
+    return { ok: false, code: 'INVALID_ADDITIONAL_CONTEXT_FILE', error: 'Could not parse the pending response JSON.', filePath };
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+export function validateRuntimeCommand(projectDir, args = {}) {
+  try {
+    const artifact = loadRuntimeInstallationV2(projectDir);
+    if (!artifact) return { ok: true, artifact: null };
+    const invocation = assertRuntimeCommandV2({
+      artifact,
+      agent: args.agent,
+      reasoning_escalation: args['reasoning-escalation'] === 'true',
+      command: {
+        provider_id: args['provider-id'],
+        harness_id: args.provider,
+        model_id: args.model,
+        reasoning_configuration: args['reasoning-configuration'],
+        catalog_snapshot_ref: args['catalog-snapshot-ref'],
+        strict_provider: args['strict-provider'] === 'true',
+      },
+    });
+    const executableBinding = resolveRuntimeExecutableBindingV2({
+      artifact,
+      provider_id: invocation.provider_id,
+      harness_id: invocation.harness_id,
+    });
+    return { ok: true, artifact, invocation, executableBinding };
+  } catch (error) {
+    return { ok: false, code: error.code || 'RUNTIME_ROUTE_BINDING_INVALID', error: error.message };
+  }
+}
+
+export function releasePendingForFailedRelay(projectDir, args) {
+  if (!args?.['relay-claim-id']) return { saved: true, released: false };
+  return releasePendingInteraction(projectDir, {
+    claimId: args['relay-claim-id'],
+    interactionId: args['interaction-id'] || null,
+  });
+}
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -400,4 +818,4 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
   });
 }
 
-export { parseArgs, waitForExit, parseSimpleYaml };
+export { cleanupResponseFile, parseArgs, waitForExit, parseSimpleYaml };

package/src/terminal/run-parallel.js

@@ -22,6 +22,7 @@ import { collectResults, mergeHandoffs, buildConsolidatedHandoff } from './colle
 import { parseAgentOutput } from './handoff-parser.js';
 import { estimateTokens, COST_PER_1K } from './cost-tracker.js';
 import { getRateLimiter } from './rate-limiter.js';
+import { loadRuntimeInstallationV2 } from '../orchestrator/runtime-installation-v2.js';
 
 // ---------------------------------------------------------------------------
 // CLI argument parsing
@@ -86,6 +87,10 @@ async function main() {
   }
 
   const projectDir = args['project-dir'] || process.cwd();
+  if (loadRuntimeInstallationV2(projectDir)) {
+    outputError('Runtime v2 requires individually signed planning commands. The legacy parallel runner is disabled.');
+    process.exit(1);
+  }
   const previousAgent = args['previous-agent'] || null;
   const timeout = parseInt(args.timeout, 10) || 900_000; // default 15 minutes