chati-dev 4.5.28 → 4.5.29

package/src/terminal/run-agent.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { withUpgradeMaintenance } from '../upgrade/maintenance.js';
 /**
  * CLI runner for single-agent terminal execution.
  *
@@ -18,9 +19,12 @@ 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 { getTerminalAttemptDiagnostics, isTransientFailure, spawnTerminalWithRetry } from './spawner.js';
 import { getWriteScope } from './isolation.js';
-import { parseAgentOutput } from './handoff-parser.js';
+import { normalizePlanningQaOutcome, parseAgentOutput } from './handoff-parser.js';
+import { getQaThreshold } from '../orchestrator/pipeline-manager.js';
+import { pinPlanningContractRevisionInputs, pinPlanningQaSubject } from '../orchestrator/council-gate-runtime.js';
+import { AGENT_RETRY_DELAY_MS, createAgentAttemptBudget, parseAgentTimeout } from './agent-attempt-budget.js';
 import { checkProviderReadiness } from './provider-preflight.js';
 import { createCostTracker } from './cost-tracker.js';
 import { getRateLimiter } from './rate-limiter.js';
@@ -30,7 +34,7 @@ import { getTelemetryConfig, isEnabled as isTelemetryEnabled } from '../telemetr
 import {
   recordPendingInteraction, clearPendingInteraction,
   claimPendingInteraction, releasePendingInteraction,
-  loadSession, startAgentExecution, holdAgentExecutionForAdvance, releaseAgentExecution,
+  loadSession, startAgentExecution, holdAgentExecutionForAdvance, releaseAgentExecution, validateInitialTaskContext,
 } from '../orchestrator/session-manager.js';
 import { recordEvent, EventType } from '../intelligence/timeline.js';
 import {
@@ -92,7 +96,11 @@ function parseArgs(argv) {
 
 async function main() {
   const args = parseArgs(process.argv);
+  const projectDir = args['project-dir'] || process.cwd();
+  return withUpgradeMaintenance(projectDir, () => runUnderMaintenance(args, projectDir));
+}
 
+async function runUnderMaintenance(args, projectDir) {
   // Validate required args
   if (!args.agent) {
     outputError('Missing required argument: --agent');
@@ -103,8 +111,14 @@ async function main() {
     process.exit(1);
   }
 
-  const projectDir = args['project-dir'] || process.cwd();
-  const timeout = parseInt(args.timeout, 10) || 600_000; // default 10 minutes
+  let timeout;
+  try { timeout = parseAgentTimeout(args.timeout, args.agent); }
+  catch (error) {
+    outputResult({ status: 'error', code: error.code, error: error.message, agent: args.agent });
+    process.exit(1);
+  }
+  let executionDeadline = null;
+  let contentReviewContext = null;
 
   const runtimeRoute = validateRuntimeCommand(projectDir, args);
   if (!runtimeRoute.ok) {
@@ -128,6 +142,10 @@ async function main() {
     const execution = startAgentExecution(projectDir, {
       agent: args.agent,
       claimId: args['execution-claim-id'] || null,
+      taskId: args['task-id'],
+      binding: { provider: args.provider || null, provider_id: args['provider-id'] || null,
+        model: args.model || null, reasoning_configuration: args['reasoning-configuration'] || null,
+        catalog_snapshot_ref: args['catalog-snapshot-ref'] || null },
     });
     if (!execution.saved || !execution.started) {
       outputResult({
@@ -139,6 +157,8 @@ async function main() {
       });
       process.exit(1);
     }
+    executionDeadline = execution.expiresAt;
+    contentReviewContext = execution.contentReviewContext;
     process.once('exit', () => {
       releaseAgentExecution(projectDir, {
         agent: args.agent,
@@ -159,11 +179,21 @@ async function main() {
     process.exit(1);
   }
   if (responseFile.response !== null) args['additional-context'] = responseFile.response;
+  // Extra task context belongs to this already validated fresh v2 claim. It
+  // is not an answer to a pending question and cannot authenticate a relay.
+  const freshTaskContext = Boolean(runtimeRoute.artifact && !args['interaction-id']);
+  if (freshTaskContext) {
+    try { validateInitialTaskContext(args['additional-context']); }
+    catch (error) {
+      outputResult({ status: 'error', code: error.code, error: error.message, agent: args.agent });
+      process.exit(1);
+    }
+  }
 
   // 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()) {
+  if (freshTaskContext || typeof args['additional-context'] !== 'string' || !args['additional-context'].trim()) {
     const pendingGuard = claimPendingInteraction(projectDir, {
       interactionId: args['interaction-id'] || null,
       agent: args.agent,
@@ -173,7 +203,7 @@ async function main() {
       model: args.model || null,
       reasoningConfiguration: args['reasoning-configuration'] || null,
       catalogSnapshotRef: args['catalog-snapshot-ref'] || null,
-      response: args['additional-context'],
+      response: freshTaskContext ? undefined : args['additional-context'],
       reasoningEscalation: args['reasoning-escalation'] === 'true',
     });
     if (!pendingGuard.saved || !pendingGuard.allowed) {
@@ -208,28 +238,32 @@ async function main() {
     process.exit(1);
   }
 
-  // Build the agent prompt
+  const promptConfig = {
+    agent: args.agent, taskId: args['task-id'], projectDir,
+    previousAgent: args['previous-agent'] || null, workflow: args.workflow || null,
+    sessionState, additionalContext: args['additional-context'] || null,
+    provider: args.provider || null, model: args.model || null,
+    providerId: args['provider-id'] || null,
+    reasoningConfiguration: args['reasoning-configuration'] || null,
+    catalogSnapshotRef: args['catalog-snapshot-ref'] || null,
+    interactionId: args['interaction-id'] || null,
+    strictProvider: args['strict-provider'] === 'true',
+    executionClaimId: args['execution-claim-id'] || null,
+    contentReviewContext,
+  };
+
+  // Local preparation resolves the route, but never injects unclaimed history.
   let promptResult;
   try {
-    promptResult = buildAgentPrompt({
-      agent: args.agent,
-      taskId: args['task-id'],
-      projectDir,
-      previousAgent: args['previous-agent'] || null,
-      workflow: args.workflow || null,
-      sessionState,
-      additionalContext: args['additional-context'] || null,
-      provider: args.provider || null,
-      model: args.model || null,
-      strictProvider: args['strict-provider'] === 'true',
-    });
+    promptResult = buildAgentPrompt(promptConfig);
   } 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}`);
+    outputResult({ status: 'error', code: err.code || 'PROMPT_BUILD_FAILED',
+      error: `Failed to build prompt: ${err.message}`, agent: args.agent });
     process.exit(1);
   }
 
@@ -270,6 +304,7 @@ async function main() {
 
   // Reserve the relay only after local preparation and rate limiting. The
   // lease therefore covers provider execution, not unbounded queue time.
+  const relayDeadline = new Date(Date.now() + (timeout * 2) + 5 * 60 * 1000).toISOString();
   const pendingClaim = claimPendingInteraction(projectDir, {
     interactionId: args['interaction-id'] || null,
     agent: args.agent,
@@ -279,9 +314,9 @@ async function main() {
     model: args.model || null,
     reasoningConfiguration: args['reasoning-configuration'] || null,
     catalogSnapshotRef: args['catalog-snapshot-ref'] || null,
-    response: args['additional-context'],
+    response: freshTaskContext ? undefined : args['additional-context'],
     reasoningEscalation: args['reasoning-escalation'] === 'true',
-    leaseExpiresAt: new Date(Date.now() + (timeout * 2) + 5 * 60 * 1000).toISOString(),
+    leaseExpiresAt: relayDeadline,
   });
   if (!pendingClaim.saved || !pendingClaim.allowed) {
     cleanupRejectedResponseFile(responseFile.filePath, pendingClaim);
@@ -295,12 +330,43 @@ async function main() {
     process.exit(1);
   }
   if (pendingClaim.claimed) args['relay-claim-id'] = pendingClaim.claimId;
+  if (pendingClaim.claimed) {
+    try {
+      // The claim atomically validates the entire binding and snapshots its
+      // conversation. A pre-claim session read is not relay authority.
+      promptResult = buildAgentPrompt({ ...promptConfig, relayContext: pendingClaim.relayContext,
+        executionClaimId: pendingClaim.claimId, contentReviewContext: pendingClaim.contentReviewContext });
+    } catch (error) {
+      const released = releasePendingForFailedRelay(projectDir, args);
+      outputResult({ status: 'error', code: released.saved ? (error.code || 'RELAY_PROMPT_INVALID') : 'SESSION_WRITE_FAILED',
+        error: released.saved ? error.message : released.error, agent: args.agent });
+      process.exit(1);
+    }
+  }
 
   // Spawn the agent terminal
   const startTime = Date.now();
   let handle;
+  let retryBudgetExhausted = false;
+  let qaSubject;
 
   try {
+    const recoveryContext = pendingClaim.claimed ? pendingClaim.contentReviewContext : contentReviewContext;
+    const revalidation = recoveryContext?.planning_reconciliation || recoveryContext?.council_revalidation;
+    const contractRevision = recoveryContext?.planning_contract_revision;
+    if (contractRevision) {
+      // The executing owner may replace only its own output. Keep every other
+      // Planning input descriptor frozen across retries, interaction and hold.
+      qaSubject = pinPlanningContractRevisionInputs(projectDir, args.agent, contractRevision.execution_subject);
+      process.once('exit', () => qaSubject.close());
+    } else if (revalidation) {
+      // Retain the same input descriptors for the entire provider lifetime,
+      // including retries and final persistence. Hashes at two endpoints alone
+      // cannot detect a writer changing and restoring an input during review.
+      qaSubject = pinPlanningQaSubject(projectDir, revalidation.artifacts, { inputsOnly: true, excludeQaReport: true });
+      process.once('exit', () => qaSubject.close());
+    }
+    const budget = createAgentAttemptBudget(timeout, pendingClaim.claimed ? relayDeadline : executionDeadline);
     const spawnConfig = {
       agent: args.agent,
       taskId: args['task-id'],
@@ -326,22 +392,32 @@ async function main() {
     };
     handle = await spawnTerminalWithRetry(spawnConfig, {
       maxRetries: 1,
-      baseDelay: 500,
+      baseDelay: AGENT_RETRY_DELAY_MS,
+      // This also runs after backoff, so a scheduler pause cannot turn an
+      // earlier admission decision into an expired claim launching a child.
+      beforeAttempt: () => { budget.assertCanStart(); qaSubject?.assertCurrent(); },
       // 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);
+        const retryable = isTransientFailure(exitCode, combined) || /not logged in|not authenticated/i.test(combined);
+        if (retryable && !budget.canStart(AGENT_RETRY_DELAY_MS)) {
+          retryBudgetExhausted = true;
+          return false;
+        }
+        return retryable;
       },
     });
+    qaSubject?.assertCurrent();
   } catch (err) {
     const relayState = releasePendingForFailedRelay(projectDir, args);
+    const diagnostic = { elapsed: Date.now() - startTime, execution_diagnostics: getTerminalAttemptDiagnostics(err) };
     if (!relayState.saved) {
-      outputResult({ status: 'error', code: 'SESSION_WRITE_FAILED', error: relayState.error, cause: err.message });
+      outputResult({ status: 'error', code: 'SESSION_WRITE_FAILED', error: relayState.error, cause: err.message, ...diagnostic });
       process.exit(1);
     }
-    outputError(`Failed to spawn terminal: ${err.message}`);
+    outputResult({ status: 'error', code: err.code || 'TERMINAL_SPAWN_FAILED', error: `Failed to spawn terminal: ${err.message}`, agent: args.agent, ...diagnostic });
     process.exit(1);
   }
 
@@ -399,7 +475,7 @@ async function main() {
   await flushAndSend(projectDir);
 
   // Parse the handoff from stdout
-  const parsed = parseAgentOutput(stdout);
+  const parsed = parseAgentOutput(stdout, { strict: args.agent === 'qa-planning' });
   const recovered = recoverInteractiveHandoff(args.agent, stdout, handle.exitCode);
 
   if (handle.exitCode !== 0 && /not logged in|not authenticated/i.test(providerOutput)) {
@@ -415,6 +491,8 @@ async function main() {
       provider: spawnProvider,
       exitCode: handle.exitCode,
       retryCount: handle.retryCount || 0,
+      elapsed,
+      execution_diagnostics: getTerminalAttemptDiagnostics(handle),
     });
     process.exit(1);
   }
@@ -438,25 +516,58 @@ async function main() {
       exitCode: handle.exitCode,
       retryCount: handle.retryCount || 0,
       agent: args.agent,
+      elapsed,
+      execution_diagnostics: getTerminalAttemptDiagnostics(handle),
+      ...(retryBudgetExhausted ? { retry_suppressed: 'AGENT_EXECUTION_BUDGET_EXHAUSTED' } : {}),
     });
     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 });
+    if (!['complete', 'needs_input'].includes(parsed.handoff.status)) {
+      // A zero OS exit is not a successful agent result. Keep the pending
+      // question and exact response recoverable, just as for process failure.
+      const relayState = releasePendingForFailedRelay(projectDir, args);
+      if (!relayState.saved) {
+        outputResult({ status: 'error', code: 'SESSION_WRITE_FAILED', error: relayState.error, cause: 'AGENT_RESULT_INCOMPLETE' });
+        process.exit(1);
+      }
+      outputResult({ status: 'error', code: 'AGENT_RESULT_INCOMPLETE',
+        error: `Agent returned ${parsed.handoff.status}; no successful result was held.`,
+        agent: args.agent, provider: spawnProvider, model: promptResult.model,
+        exitCode: handle.exitCode, handoff: parsed.handoff, elapsed, costEstimate });
       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 });
+    let qaResult;
+    if (args.agent === 'qa-planning' && parsed.handoff.status === 'complete') {
+      const normalized = normalizePlanningQaOutcome(parsed.handoff, getQaThreshold(args.agent, projectDir));
+      if (!normalized.ok) {
+        const released = releasePendingForFailedRelay(projectDir, args);
+        outputResult({ status: 'error', code: released.saved ? normalized.code : 'SESSION_WRITE_FAILED',
+          error: released.saved ? normalized.error : released.error, agent: args.agent });
         process.exit(1);
       }
+      qaResult = normalized.outcome;
+    }
+    const persistence = parsed.handoff.status === 'complete'
+      ? holdAgentExecutionForAdvance(projectDir, {
+        agent: args.agent, taskId: args['task-id'], resultStatus: parsed.handoff.status,
+        interactionId: args['interaction-id'] || null,
+        claimId: args['interaction-id'] ? args['relay-claim-id'] : (args['execution-claim-id'] || null),
+        binding: { provider: spawnProvider, provider_id: args['provider-id'] || null, model: promptResult.model,
+          reasoning_configuration: args['reasoning-configuration'] || null,
+          catalog_snapshot_ref: args['catalog-snapshot-ref'] || null },
+        ...(qaResult ? { qaResult } : {}),
+        ...(qaSubject ? { verifySubject: () => qaSubject.assertCurrent() } : {}),
+      })
+      : persistInteractiveState(projectDir, args, parsed.handoff, promptResult.model, spawnProvider);
+    if (!persistence.saved) {
+      outputResult({ status: 'error', code: persistence.code || 'SESSION_WRITE_FAILED', error: persistence.error, agent: args.agent });
+      process.exit(1);
+    }
+    if (parsed.handoff.status === 'complete' && !persistence.held) {
+      outputResult({ status: 'error', code: persistence.code || 'SESSION_WRITE_FAILED', error: persistence.error, agent: args.agent });
+      process.exit(1);
     }
     cleanupResponseFile(responseFile.filePath);
     outputResult({
@@ -517,6 +628,9 @@ async function main() {
       elapsed,
       costEstimate,
     });
+    // The provider's zero exit does not satisfy the handoff contract. Keep
+    // the relay/response recoverable, but report runner failure to its caller.
+    process.exit(1);
   }
 
   process.exit(handle.exitCode === 0 ? 0 : 1);
@@ -554,11 +668,18 @@ function persistInteractiveState(projectDir, args, handoff, model, provider) {
       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'],
+      advanceRelay: Boolean(args['interaction-id'] && args['relay-claim-id']),
+      initialTaskContext: args['interaction-id'] ? undefined : args['additional-context'],
+      interactionId: args['interaction-id'] || null,
+      claimId: args['relay-claim-id'] || null,
     });
+    if (!result.saved) {
+      // Keep the original response recoverable on a rejected/failed commit.
+      // Exact claim ownership prevents this release from touching a newer relay.
+      releasePendingForFailedRelay(projectDir, args);
+      return result;
+    }
+    recordEvent(projectDir, EventType.AGENT_WAITING_FOR_INPUT, args.agent, { task_id: args['task-id'] });
     return result;
   }
   return clearPendingInteraction(projectDir, {
@@ -566,6 +687,7 @@ function persistInteractiveState(projectDir, args, handoff, model, provider) {
     taskId: args['task-id'],
     interactionId: args['interaction-id'] || null,
     claimId: args['relay-claim-id'] || null,
+    requireClaim: Boolean(args['interaction-id']),
   });
 }