@moretea-labs/forge 1.8.0 → 1.8.2

package/scripts/smoke-workflow-supervisor-restart-recovery.ts

@@ -0,0 +1,150 @@
+import { strict as assert } from 'node:assert';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { WorkflowSupervisorControlPlane } from '../supervisor/control-plane';
+import { SUPERVISOR_BLOCK_END, SUPERVISOR_BLOCK_START } from '../supervisor/protocol';
+import { WORKFLOW_SUPERVISOR_MIN_TURN_INTERVAL_MS, WorkflowSupervisorStore } from '../supervisor/store';
+
+const home = mkdtempSync(join(tmpdir(), 'forge-supervisor-recovery-'));
+let mechanicalNowMs = Date.now();
+const TURN_ADVANCE_MS = WORKFLOW_SUPERVISOR_MIN_TURN_INTERVAL_MS + 1_000;
+const validators = { completionContract: async () => ({ valid: true, reason: 'ok' }), userBlockerPolicy: async () => ({ valid: true, reason: 'ok' }) };
+const control = () => new WorkflowSupervisorControlPlane(new WorkflowSupervisorStore(home, { now: () => mechanicalNowMs }), validators);
+const block = (
+  action: 'CONTINUE' | 'DONE',
+  effectId: string,
+  checkpoint: string,
+  conversationId: string,
+  taskId: string,
+) => `${SUPERVISOR_BLOCK_START}\n${JSON.stringify({
+  action,
+  source_effect_id: effectId,
+  checkpoint,
+  reason: action === 'DONE' ? 'complete' : 'continue',
+  evidence: ['recovery-smoke'],
+  conversation_id: conversationId,
+  task_id: taskId,
+  supervisor_state: action === 'DONE' ? 'done' : 'running',
+  active_scope: `goal:${taskId}`,
+})}\n${SUPERVISOR_BLOCK_END}`;
+
+try {
+  let supervisor = control();
+  const conversationId = '99999999-8888-7777-6666-555555555555';
+  const conversationUrl = `https://chatgpt.com/c/${conversationId}`;
+  supervisor.registerTask({ taskId: 'recovery-task', conversationId, conversationUrl, objective: 'Prove restart recovery.', completionContract: {}, continuationPolicy: {}, userBlockerPolicy: {} });
+  const enrollment = supervisor.reserveEnrollment('recovery-task');
+  let poll = supervisor.browserPoll({ conversationId, conversationUrl });
+  assert.equal(poll.command?.mode, 'send'); assert.equal(poll.command?.dispatchGeneration, 1);
+  assert.equal(supervisor.browserBeginEffect({ conversationId, conversationUrl, effectId: enrollment.effectId, dispatchId: 'enroll-g1', dispatchGeneration: 1, evidence: { latest_user_text: 'before enrollment', latest_assistant_response: 'existing assistant text' } }).started, true);
+
+  supervisor = control();
+  assert.throws(() => supervisor.observeEffect({ effectId: enrollment.effectId, observationId: 'forged-not-applied', outcome: 'not_applied', evidence: { latest_user_text: 'forged' } }), /NOT_APPLIED_PROOF_REQUIRED/);
+  poll = supervisor.browserPoll({ conversationId, conversationUrl });
+  assert.equal(poll.command?.mode, 'reconcile'); assert.equal(poll.command?.dispatchGeneration, 1);
+  supervisor.browserObserveEffect({ conversationId, conversationUrl, effectId: enrollment.effectId, observationId: 'enroll-not-applied', outcome: 'not_applied', evidence: { latest_user_text: 'before enrollment', latest_assistant_response: 'existing assistant text', target_marker_present: false, provider_surface_rendered: true, reason: 'composer_proven_empty' } });
+  mechanicalNowMs += 30_000;
+  poll = supervisor.browserPoll({ conversationId, conversationUrl });
+  assert.equal(poll.command?.mode, 'reconcile'); assert.equal(poll.command?.dispatchGeneration, 1); assert.equal(poll.command?.effectId, enrollment.effectId);
+  assert.equal(supervisor.store.effectDispatchBudget(enrollment.effectId).generations, 1);
+  supervisor.browserObserveEffect({ conversationId, conversationUrl, effectId: enrollment.effectId, observationId: 'enroll-applied', outcome: 'applied', evidence: { exact_user_message: true } });
+  const response1 = block('CONTINUE', enrollment.effectId, 'checkpoint-1', conversationId, 'recovery-task');
+  const turn1 = await supervisor.browserObserveAssistant({ conversationId, conversationUrl, responseText: response1 });
+  const continuation = turn1.successorEffect!;
+
+  mechanicalNowMs += TURN_ADVANCE_MS;
+  poll = supervisor.browserPoll({ conversationId, conversationUrl });
+  assert.equal(poll.command?.effectId, continuation.effectId); assert.equal(poll.command?.dispatchGeneration, 1);
+  assert.equal(supervisor.browserBeginEffect({ conversationId, conversationUrl, effectId: continuation.effectId, dispatchId: 'continue-g1', dispatchGeneration: 1, evidence: { latest_user_text: enrollment.prompt, latest_assistant_response: response1 } }).started, true);
+  supervisor = control();
+  poll = supervisor.browserPoll({ conversationId, conversationUrl }); assert.equal(poll.command?.mode, 'reconcile');
+  supervisor.browserObserveEffect({ conversationId, conversationUrl, effectId: continuation.effectId, observationId: 'bad-proof', outcome: 'not_applied', evidence: { latest_user_text: 'conversation drifted', latest_assistant_response: response1, target_marker_present: false, provider_surface_rendered: true, reason: 'composer_proven_empty' } });
+  poll = supervisor.browserPoll({ conversationId, conversationUrl }); assert.equal(poll.command?.mode, 'reconcile'); assert.equal(poll.command?.dispatchGeneration, 1);
+  // Even the exact pre-send baseline on a rendered page can be stale. A
+  // reopened observer cannot turn provider outcome uncertainty into a resend.
+  supervisor.browserObserveEffect({ conversationId, conversationUrl, effectId: continuation.effectId, observationId: 'stale-baseline-observation', outcome: 'not_applied', evidence: { latest_user_text: enrollment.prompt, latest_assistant_response: response1, target_marker_present: false, provider_surface_rendered: true, reason: 'composer_proven_empty' } });
+  mechanicalNowMs += 30_000;
+  poll = supervisor.browserPoll({ conversationId, conversationUrl }); assert.equal(poll.command?.mode, 'reconcile'); assert.equal(poll.command?.dispatchGeneration, 1); assert.equal(poll.command?.effectId, continuation.effectId);
+  assert.equal(supervisor.browserBeginEffect({ conversationId, conversationUrl, effectId: continuation.effectId, dispatchId: 'continue-g1-duplicate', dispatchGeneration: 1, evidence: { latest_user_text: enrollment.prompt, latest_assistant_response: response1 } }).started, false);
+  assert.equal(supervisor.store.effectDispatchBudget(continuation.effectId).generations, 1);
+  supervisor.browserObserveEffect({ conversationId, conversationUrl, effectId: continuation.effectId, observationId: 'continue-applied', outcome: 'applied', evidence: { exact_user_message: true } });
+
+  const response2 = block('CONTINUE', continuation.effectId, 'checkpoint-2', conversationId, 'recovery-task');
+  const turn2a = await supervisor.browserObserveAssistant({ conversationId, conversationUrl, responseText: response2 });
+  const turn2b = await supervisor.browserObserveAssistant({ conversationId, conversationUrl, responseText: response2 });
+  assert.equal(turn2a.successorEffect?.effectId, turn2b.successorEffect?.effectId); assert.equal(turn2b.deduplicated, true);
+  const terminalEffect = turn2a.successorEffect!;
+  mechanicalNowMs += TURN_ADVANCE_MS;
+  poll = supervisor.browserPoll({ conversationId, conversationUrl });
+  assert.equal(supervisor.browserBeginEffect({ conversationId, conversationUrl, effectId: terminalEffect.effectId, dispatchId: 'terminal-g1', dispatchGeneration: poll.command!.dispatchGeneration, evidence: { latest_user_text: continuation.prompt, latest_assistant_response: response2 } }).started, true);
+  supervisor.browserObserveEffect({ conversationId, conversationUrl, effectId: terminalEffect.effectId, observationId: 'terminal-applied', outcome: 'applied', evidence: { exact_user_message: true } });
+  const done = await supervisor.browserObserveAssistant({ conversationId, conversationUrl, responseText: block('DONE', terminalEffect.effectId, 'done', conversationId, 'recovery-task') });
+  assert.equal(done.terminal, true);
+  supervisor = control();
+  assert.equal(supervisor.browserTasks().length, 0);
+  const terminalPoll = supervisor.browserPoll({ conversationId, conversationUrl });
+  assert.equal(terminalPoll.terminal, 'DONE'); assert.equal(terminalPoll.command, undefined);
+
+  // Prove the unattended contract across repeated supervisor process/repository
+  // re-openings. Every round reconstructs the control plane from durable state,
+  // applies exactly one effect, emits CONTINUE, and must publish exactly one
+  // successor effect without a user-authored "continue" turn.
+  const unattendedTaskId = 'unattended-ten-round-task';
+  const unattendedConversationId = 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee';
+  const unattendedConversationUrl = `https://chatgpt.com/c/${unattendedConversationId}`;
+  supervisor.registerTask({
+    taskId: unattendedTaskId,
+    conversationId: unattendedConversationId,
+    conversationUrl: unattendedConversationUrl,
+    objective: 'Complete ten autonomous continuation rounds across supervisor restart.',
+    completionContract: {}, continuationPolicy: {}, userBlockerPolicy: {},
+  });
+  let effect = supervisor.reserveEnrollment(unattendedTaskId);
+  const observedEffectIds = new Set<string>();
+  for (let round = 1; round <= 10; round += 1) {
+    supervisor = control();
+    assert.equal(observedEffectIds.has(effect.effectId), false);
+    observedEffectIds.add(effect.effectId);
+    supervisor.observeEffect({
+      effectId: effect.effectId,
+      observationId: `unattended-applied-${round}`,
+      outcome: 'applied',
+      evidence: { exact_user_message: true },
+    });
+    const responseText = block('CONTINUE', effect.effectId, `unattended-checkpoint-${round}`, unattendedConversationId, unattendedTaskId);
+    const advanced = await supervisor.observeAssistantTurn({
+      taskId: unattendedTaskId,
+      conversationId: unattendedConversationId,
+      responseText,
+    });
+    assert.equal(advanced.terminal, false);
+    assert.ok(advanced.successorEffect);
+    const replay = await supervisor.observeAssistantTurn({
+      taskId: unattendedTaskId,
+      conversationId: unattendedConversationId,
+      responseText,
+    });
+    assert.equal(replay.deduplicated, true);
+    assert.equal(replay.successorEffect?.effectId, advanced.successorEffect.effectId);
+    effect = advanced.successorEffect;
+  }
+  assert.equal(observedEffectIds.size, 10);
+  supervisor = control();
+  supervisor.observeEffect({
+    effectId: effect.effectId,
+    observationId: 'unattended-terminal-applied',
+    outcome: 'applied',
+    evidence: { exact_user_message: true },
+  });
+  const unattendedDone = await supervisor.observeAssistantTurn({
+    taskId: unattendedTaskId,
+    conversationId: unattendedConversationId,
+    responseText: block('DONE', effect.effectId, 'unattended-done', unattendedConversationId, unattendedTaskId),
+  });
+  assert.equal(unattendedDone.terminal, true);
+  supervisor = control();
+  assert.equal(supervisor.browserPoll({ conversationId: unattendedConversationId, conversationUrl: unattendedConversationUrl }).terminal, 'DONE');
+
+  console.log('[workflow-supervisor-restart-recovery-smoke] OK');
+} finally { rmSync(home, { recursive: true, force: true }); }

package/scripts/smoke-workflow-supervisor.ts

@@ -0,0 +1,103 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { strict as assert } from 'node:assert';
+import { createConnection } from 'node:net';
+import { createRequirement, updateRequirement } from '../src/runtime/control-plane/persistence/requirement-store';
+import {
+  registerWorkflowSupervisorTask,
+  reserveWorkflowSupervisorEnrollment,
+} from '../supervisor/client';
+import { WorkflowSupervisorControlPlane } from '../supervisor/control-plane';
+import { forgeWorkflowSupervisorValidators } from '../supervisor/forge-validators';
+import { workflowSupervisorSocketPath } from '../supervisor/paths';
+import { renderSupervisorReceipt } from '../supervisor/protocol';
+import { WorkflowSupervisorStore, workflowSupervisorDatabasePath } from '../supervisor/store';
+import { createWorkflowSupervisorServer } from '../supervisor/server';
+
+const home = mkdtempSync(join(tmpdir(), 'forge-workflow-supervisor-'));
+try {
+  assert.equal(workflowSupervisorDatabasePath(home), join(home, 'supervisor', 'supervisor.sqlite'));
+  let allowDone = false;
+  const control = new WorkflowSupervisorControlPlane(new WorkflowSupervisorStore(home), {
+    completionContract: async () => ({ valid: allowDone, reason: allowDone ? 'verified' : 'missing_goal_evidence' }),
+    userBlockerPolicy: async () => ({ valid: false, reason: 'not_user_only' }),
+  });
+  const taskInput = { taskId: 'task-smoke', conversationId: 'conv-smoke', conversationUrl: 'https://chatgpt.com/c/conv-smoke', objective: 'finish smoke goal', completionContract: {}, continuationPolicy: { active_scope: 'goal:task-smoke' }, userBlockerPolicy: {} };
+  control.registerTask(taskInput);
+  assert.throws(() => control.registerTask({ ...taskInput, completionContract: { changed: true } }), /WORKFLOW_SUPERVISOR_TASK_ID_CONFLICT/);
+  const enrollment = control.reserveEnrollment('task-smoke');
+  assert.match(enrollment.prompt, new RegExp(enrollment.effectId));
+  control.observeEffect({ effectId: enrollment.effectId, observationId: 'obs-1', outcome: 'applied' });
+  const response = (effect: string, action: 'CONTINUE'|'DONE') => renderSupervisorReceipt(taskInput, effect, action);
+  const first = await control.observeAssistantTurn({ taskId: 'task-smoke', conversationId: 'conv-smoke', responseText: response(enrollment.effectId, 'CONTINUE') });
+  assert(first.successorEffect); assert.equal(first.terminal, false);
+  const duplicate = await control.observeAssistantTurn({ taskId: 'task-smoke', conversationId: 'conv-smoke', responseText: response(enrollment.effectId, 'CONTINUE') });
+  assert.equal(duplicate.successorEffect?.effectId, first.successorEffect.effectId); assert.equal(duplicate.deduplicated, true);
+  assert.throws(() => control.registerTask({ taskId: 'task-smoke', conversationId: 'conv-smoke', conversationUrl: 'https://chatgpt.com/c/conv-smoke', objective: 'changed objective', completionContract: {}, continuationPolicy: {}, userBlockerPolicy: {} }), /WORKFLOW_SUPERVISOR_TASK_ID_CONFLICT/);
+  control.observeEffect({ effectId: first.successorEffect.effectId, observationId: 'obs-2', outcome: 'applied' });
+  const rejected = await control.observeAssistantTurn({ taskId: 'task-smoke', conversationId: 'conv-smoke', responseText: response(first.successorEffect.effectId, 'DONE') });
+  assert.equal(rejected.terminal, false); assert.equal(rejected.validation?.valid, false); assert(rejected.successorEffect);
+  control.observeEffect({ effectId: rejected.successorEffect.effectId, observationId: 'obs-3', outcome: 'applied' });
+  allowDone = true;
+  const done = await control.observeAssistantTurn({ taskId: 'task-smoke', conversationId: 'conv-smoke', responseText: response(rejected.successorEffect.effectId, 'DONE') });
+  assert.equal(done.terminal, true); assert.equal(done.successorEffect, undefined);
+
+  const socketPath = workflowSupervisorSocketPath(home);
+  const server = createWorkflowSupervisorServer({ controlPlane: control, socketPath });
+  await new Promise<void>((resolve) => server.once('listening', resolve));
+  const health = await new Promise<Record<string, any>>((resolve, reject) => {
+    const socket = createConnection(socketPath);
+    let buffer = '';
+    socket.once('error', reject);
+    socket.on('data', (chunk) => {
+      buffer += chunk.toString('utf8');
+      const newline = buffer.indexOf('\n');
+      if (newline < 0) return;
+      socket.end();
+      resolve(JSON.parse(buffer.slice(0, newline)) as Record<string, any>);
+    });
+    socket.once('connect', () => socket.write(`${JSON.stringify({ id: 'health-1', method: 'health', params: {} })}\n`));
+  });
+  assert.equal(health.ok, true); assert.equal(health.result.status, 'ready');
+
+  const rpcTaskInput = {
+    taskId: 'task-rpc-smoke', conversationId: 'conv-rpc-smoke', conversationUrl: 'https://chatgpt.com/c/conv-rpc-smoke', objective: 'rpc enrollment smoke',
+    completionContract: { kind: 'smoke' }, continuationPolicy: { kind: 'smoke' }, userBlockerPolicy: { kind: 'smoke' },
+  };
+  const rpcTask = await registerWorkflowSupervisorTask(home, rpcTaskInput);
+  assert.equal(rpcTask.taskId, rpcTaskInput.taskId);
+  const rpcEnrollment = await reserveWorkflowSupervisorEnrollment(home, rpcTask.taskId);
+  const rpcEnrollmentReplay = await reserveWorkflowSupervisorEnrollment(home, rpcTask.taskId);
+  assert.equal(rpcEnrollmentReplay.effectId, rpcEnrollment.effectId);
+
+  const controllerHome = join(home, 'controller');
+  const validators = forgeWorkflowSupervisorValidators();
+  createRequirement({ controllerHome }, { requirementId: 'REQ-SUPERVISOR-DONE', title: 'Supervisor done validator', outcomeStatement: 'Validate canonical semantic completion.' });
+  updateRequirement({ controllerHome }, { requirementId: 'REQ-SUPERVISOR-DONE', action: 'smoke_activate', mutate: (current) => ({ ...current, state: 'active' }) });
+  const doneTask = {
+    ...rpcTaskInput,
+    taskId: 'task-validator-done',
+    completionContract: { kind: 'forge_requirement_done', controller_home: controllerHome, requirement_id: 'REQ-SUPERVISOR-DONE' },
+    userBlockerPolicy: { kind: 'forge_requirement_waiting_for_user', controller_home: controllerHome, requirement_id: 'REQ-SUPERVISOR-DONE' },
+    createdAt: new Date().toISOString(),
+  };
+  assert.equal((await validators.completionContract(doneTask, { action: 'DONE', sourceEffectId: 'fx_smokevalidator', checkpoint: 'done', reason: 'done', evidence: [] })).valid, false);
+  updateRequirement({ controllerHome }, {
+    requirementId: 'REQ-SUPERVISOR-DONE', action: 'smoke_semantic_acceptance',
+    mutate: (current) => ({ ...current, state: 'done', semanticAcceptance: { reviewer: 'smoke', rationale: 'validated', planIds: [], acceptedAt: new Date().toISOString() } }),
+  });
+  assert.equal((await validators.completionContract(doneTask, { action: 'DONE', sourceEffectId: 'fx_smokevalidator', checkpoint: 'done', reason: 'done', evidence: [] })).valid, true);
+
+  createRequirement({ controllerHome }, { requirementId: 'REQ-SUPERVISOR-USER', title: 'Supervisor user validator', outcomeStatement: 'Validate genuine user-only wait.' });
+  updateRequirement({ controllerHome }, { requirementId: 'REQ-SUPERVISOR-USER', action: 'smoke_activate', mutate: (current) => ({ ...current, state: 'active' }) });
+  updateRequirement({ controllerHome }, {
+    requirementId: 'REQ-SUPERVISOR-USER', action: 'smoke_user_wait',
+    mutate: (current) => ({ ...current, state: 'waiting_for_user', needsAttention: true, attentionSummary: 'User authorization is required.' }),
+  });
+  const userTask = { ...doneTask, taskId: 'task-validator-user', completionContract: { kind: 'forge_requirement_done', controller_home: controllerHome, requirement_id: 'REQ-SUPERVISOR-USER' }, userBlockerPolicy: { kind: 'forge_requirement_waiting_for_user', controller_home: controllerHome, requirement_id: 'REQ-SUPERVISOR-USER' } };
+  assert.equal((await validators.userBlockerPolicy(userTask, { action: 'NEEDS_USER', sourceEffectId: 'fx_smokevalidator', checkpoint: 'user', reason: 'user action', evidence: [] })).valid, true);
+
+  await new Promise<void>((resolve) => server.close(() => resolve()));
+  console.log('[workflow-supervisor-smoke] OK');
+} finally { rmSync(home, { recursive: true, force: true }); }

package/scripts/sync-generated-authority.mjs

@@ -92,7 +92,6 @@ function shellCompatibilityWrapper(name) {
 }
 
 const MODULE_HELPERS = new Set([
-  'check-skill-version.ts',
   'workflow-contract.ts',
   'inspect-project-state.ts',
   'migrate-workflow-docs.ts',

package/scripts/verify-forge-runtime.sh

@@ -11,11 +11,12 @@ command -v bun >/dev/null 2>&1 || {
 
 TEST_FILES=(
   "tests/runtime/facade-contracts.test.ts"
-  "tests/runtime/route-policy.test.ts"
   "tests/runtime/forge-runtime-service.test.ts"
   "tests/cli/local-bridge.test.ts"
   "tests/runtime/thin-harness-gateway-routing.test.ts"
   "tests/runtime/runtime-observability.test.ts"
+  "tests/runtime/release-session.test.ts"
+  "tests/runtime/local-recovery-plugin.test.ts"
   "tests/unit/test-governance.test.ts"
 )
 

package/src/cli/agent-jobs/executor-health.ts

@@ -1,6 +1,6 @@
 import type { GitHubStatus } from "../github/contracts";
-import type { McpAgentRunnerName } from "../mcp/types";
-import type { ControllerAgent, ControllerTask } from "../controller/types";
+import type { McpAgentRunnerName } from "../../../adapters/mcp/types";
+import type { ControllerAgent } from "../controller/types";
 
 export type ExecutorHealthStatus =
   | "available"
@@ -24,7 +24,6 @@ export type ExecutorHealthReason =
   | "unknown";
 
 export type ExecutorHealthFallback =
-  | "use_direct_edit"
   | "enable_local_agent"
   | "run_gh_auth_login"
   | "enable_copilot_coding_agent"
@@ -64,19 +63,6 @@ function normalize(value: string): string {
   return value.toLowerCase().replace(/\s+/g, " ").trim();
 }
 
-function isSmallScopedTask(task: Pick<ControllerTask, "allowedPaths"> | undefined): boolean {
-  return Array.isArray(task?.allowedPaths) && task.allowedPaths.length > 0 && task.allowedPaths.length <= 3;
-}
-
-function localUnavailableMessage(base: string, task?: Pick<ControllerTask, "allowedPaths">): string {
-  if (!isSmallScopedTask(task)) return base;
-  return `${base} Use begin_edit_session/apply_patch/run_check instead of retrying unavailable agents.`;
-}
-
-function localUnavailableFallback(task?: Pick<ControllerTask, "allowedPaths">): ExecutorHealthFallback {
-  return isSmallScopedTask(task) ? "use_direct_edit" : "enable_local_agent";
-}
-
 export function executorHealthCode(health: ExecutorHealth): string {
   switch (health.reason) {
     case "local_dev_runner_disabled":
@@ -104,19 +90,15 @@ export function executorHealthCode(health: ExecutorHealth): string {
 export function classifyLocalExecutorHealth(
   agent: Exclude<ControllerAgent, "github-copilot">,
   policy: LocalExecutorPolicy,
-  task?: Pick<ControllerTask, "allowedPaths">,
 ): ExecutorHealth | null {
   if (!policy.agentRunner) {
     return {
       agent,
       status: "disabled",
       reason: "local_dev_runner_disabled",
-      message: localUnavailableMessage(
-        `Local ${agent} runs are disabled because the dev runner is not enabled.`,
-        task,
-      ),
+      message: `Local ${agent} runs are disabled because the dev runner is not enabled.`,
       remediation: "Enable the controller dev runner before dispatching local Codex or Claude runs.",
-      fallback: localUnavailableFallback(task),
+      fallback: "enable_local_agent",
     };
   }
   if (!policy.allowedAgents.includes(agent)) {
@@ -124,12 +106,9 @@ export function classifyLocalExecutorHealth(
       agent,
       status: "disabled",
       reason: "local_agent_disabled",
-      message: localUnavailableMessage(
-        `Local agent is not enabled: ${agent}.`,
-        task,
-      ),
+      message: `Local agent is not enabled: ${agent}.`,
       remediation: `Enable ${agent} in the controller dev-runner allowedAgents list before retrying.`,
-      fallback: localUnavailableFallback(task),
+      fallback: "enable_local_agent",
     };
   }
   return null;
@@ -137,7 +116,6 @@ export function classifyLocalExecutorHealth(
 
 export function classifyGitHubCopilotPreflight(
   status: GitHubStatus,
-  task?: Pick<ControllerTask, "allowedPaths">,
 ): ExecutorHealth | null {
   if (!status.available) {
     return {
@@ -146,7 +124,7 @@ export function classifyGitHubCopilotPreflight(
       reason: "github_cli_unavailable",
       message: "GitHub CLI (gh) is unavailable, so GitHub Copilot cloud sessions cannot start.",
       remediation: "Install GitHub CLI and ensure `gh --version` works in this repository environment.",
-      fallback: isSmallScopedTask(task) ? "use_direct_edit" : "install_github_cli",
+      fallback: "install_github_cli",
     };
   }
   if (!status.authenticated) {
@@ -175,7 +153,6 @@ export function classifyGitHubCopilotPreflight(
 export function classifyExecutorFailure(
   agent: ControllerAgent,
   message: string,
-  task?: Pick<ControllerTask, "allowedPaths">,
 ): ExecutorHealth | null {
   const text = normalize(message);
   if (!text) return null;
@@ -193,7 +170,7 @@ export function classifyExecutorFailure(
         reason: "copilot_cca_disabled",
         message: "GitHub Copilot cloud agent is not enabled for this account or repository.",
         remediation: "Enable GitHub Copilot Coding Agent / CCA for the account and repository before retrying cloud sessions.",
-        fallback: isSmallScopedTask(task) ? "use_direct_edit" : "enable_copilot_coding_agent",
+        fallback: "enable_copilot_coding_agent",
       };
     }
     return null;
@@ -207,7 +184,7 @@ export function classifyExecutorFailure(
         reason: "codex_insufficient_balance",
         message: "Codex execution is unavailable because the configured API account has insufficient balance.",
         remediation: "Restore API balance or correct the Codex base URL/account configuration before retrying.",
-        fallback: isSmallScopedTask(task) ? "use_direct_edit" : "fix_codex_api_balance_or_base_url",
+        fallback: "fix_codex_api_balance_or_base_url",
       };
     }
     if (text.includes("usage limit")) {
@@ -217,7 +194,7 @@ export function classifyExecutorFailure(
         reason: "codex_usage_limit",
         message: "Codex execution is unavailable because the configured account has reached a usage limit.",
         remediation: "Raise or wait for the Codex usage limit, or correct the API account/base URL configuration before retrying.",
-        fallback: isSmallScopedTask(task) ? "use_direct_edit" : "fix_codex_api_balance_or_base_url",
+        fallback: "fix_codex_api_balance_or_base_url",
       };
     }
     if (
@@ -232,7 +209,7 @@ export function classifyExecutorFailure(
         reason: "codex_auth_required",
         message: "Codex execution is unavailable because authentication is required.",
         remediation: "Authenticate the Codex executor or correct the configured credentials/base URL before retrying.",
-        fallback: isSmallScopedTask(task) ? "use_direct_edit" : "authenticate_codex",
+        fallback: "authenticate_codex",
       };
     }
   }
@@ -243,7 +220,7 @@ export function classifyExecutorFailure(
     reason: "unknown",
     message: `${agent} execution failed for an unclassified reason.`,
     remediation: "Inspect the bounded run error and executor configuration before retrying.",
-    fallback: isSmallScopedTask(task) ? "use_direct_edit" : "inspect_executor_configuration",
+    fallback: "inspect_executor_configuration",
   };
 }
 

package/src/cli/agent-jobs/integration.ts

@@ -13,14 +13,11 @@ import {
   type EditOperation,
   type EditSession,
 } from "../editing/edit-session";
-import { getIssue, updateTask } from "../controller/issue-store";
-import { readTaskRunEvidence } from "../controller/run-evidence";
-import { resolveEffectiveTaskState } from "../controller/task-status-resolver";
-import { resolveMcpPath } from "../mcp/paths";
-import type { McpPolicy } from "../mcp/types";
+import { resolveMcpPath } from "../../../adapters/mcp/paths";
+import type { McpPolicy } from "../../../adapters/mcp/types";
 import { getAgentJob, markAgentJobClosure, markAgentJobIntegrated, markAgentJobIntegrationReview } from "./job-manager";
 import type { AgentJobMeta, AgentJobPreservationReason } from "./types";
-import { assertRuntimeMayWriteOrThrow } from "../../runtime/root/write-fence";
+import { assertRuntimeMayWriteOrThrow, isRuntimeWriteFenceError } from "../../runtime/root/write-fence";
 
 type IntegrationChangeOutcome = "changed" | "already_integrated";
 
@@ -509,21 +506,22 @@ export function integrateAgentJob(
       ?? undefined;
     assertRuntimeMayWriteOrThrow('integrate_worktree', controllerHome);
   } catch (error) {
-    if (error instanceof Error && error.message.startsWith('WRITER_FENCED:')) throw error;
+    if (isRuntimeWriteFenceError(error)) throw error;
     /* unbound legacy single-runtime */
   }
   let run: AgentJobMeta = getAgentJob(repoRoot, runId);
-  const autoFinalizing = run.status === "running" &&
-    run.autoIntegrate === true &&
-    run.executionMode === "worktree" &&
-    (run.progress?.phase === "finalizing" || run.closureState === "ready_to_integrate");
-  const userResolvableIntegration = run.status === "waiting_for_user" &&
-    run.autoIntegrate === true &&
-    run.executionMode === "worktree" &&
-    Boolean(run.autoIntegrationError);
-  if (run.status !== "succeeded" && !autoFinalizing && !userResolvableIntegration)
+  // Integration is an explicit decision, so an ordinary Run must have finished
+  // successfully. One state is still integrable: a Run that a previous explicit
+  // integration attempt preserved after a failure or a required review. That
+  // preserved worktree is the durable product of that attempt, and refusing to
+  // retry it stranded the isolated work with no path forward.
+  const preservedIntegrationRetry = run.status === "waiting_for_user"
+    && run.executionMode === "worktree"
+    && (run.closureState === "preserved" || run.closureState === "integration_blocked")
+    && Boolean(run.autoIntegrationError || run.preservationReason);
+  if (run.status !== "succeeded" && !preservedIntegrationRetry)
     throw new Error(
-      `only succeeded, auto-finalizing, or preserved waiting_for_user Runs can be integrated (current: ${run.status})`,
+      `only a succeeded Run (or an explicitly preserved integration attempt) can be integrated (current: ${run.status})`,
     );
   if (run.provider !== "local")
     throw new Error(
@@ -531,7 +529,7 @@ export function integrateAgentJob(
     );
   if (run.worktree === repoRoot || !run.branch || !run.baseRevision)
     throw new Error(
-      "Run did not use an isolated Git worktree; its changes are already in the main working tree",
+      "Run did not use an isolated Git worktree; its changes are already in the dispatch checkout",
     );
   if (run.integratedSessionId) {
     const existing = getEditSession(repoRoot, run.integratedSessionId);
@@ -548,28 +546,12 @@ export function integrateAgentJob(
 
   run = markAgentJobClosure(repoRoot, runId, {
     state: "integrating",
-    details: "Applying isolated Run changes to the canonical workspace.",
+    details: "Applying isolated Run changes to the dispatch checkout.",
   });
 
-  const issue = getIssue(repoRoot, run.issueId);
-  const task = issue.tasks.find((entry) => entry.id === run.taskId);
-  if (!task) throw new Error(`task not found: ${run.issueId}/${run.taskId}`);
-  const state = resolveEffectiveTaskState({ issue, task, runs: readTaskRunEvidence(repoRoot, task) });
-  const taskReady = autoFinalizing || userResolvableIntegration
-    ? !state.terminal && !state.inactive && ["review", "ready_to_integrate", "integrating", "integration_blocked", "integrated", "verified"].includes(task.status)
-    : !state.terminal && !state.inactive && ["review", "ready_to_integrate", "integrating", "integration_blocked", "verified"].includes(state.effectiveStatus);
-  if (!taskReady)
-    throw new Error(
-      `task must be active and in review before integration (declared: ${task.status}, effective: ${state.effectiveStatus})`,
-    );
-
   const initialPlan = planFromCurrentWorkspace(repoRoot, run, policy);
   if (initialPlan.changedPaths.length === 0)
     throw new Error("task worktree has no changes to integrate");
-  if (initialPlan.changedPaths.length > 25)
-    throw new Error(
-      `task changed ${initialPlan.changedPaths.length} files; split or manually integrate work larger than 25 files`,
-    );
   if (initialPlan.conflicts.length > 0)
     throw createReviewPacket(
       repoRoot,
@@ -578,10 +560,9 @@ export function integrateAgentJob(
       initialPlan.conflicts,
     );
 
-  const allowedPaths =
-    task.allowedPaths.length > 0
-      ? task.allowedPaths
-      : initialPlan.changedPaths;
+  const allowedPaths = run.allowedPaths?.length
+    ? run.allowedPaths
+    : initialPlan.changedPaths;
   if (initialPlan.operations.length === 0) {
     const applied = finalizeAlreadyIntegratedSession(
       repoRoot,
@@ -592,10 +573,6 @@ export function integrateAgentJob(
       changedFiles: initialPlan.changedPaths,
       changeOutcome: "already_integrated",
     });
-    updateTask(repoRoot, run.issueId, run.taskId, {
-      status: "integrated",
-      note: `${runId} already matched the main workspace and was recorded through edit session ${applied.sessionId}; run focused checks and record verification before acceptance.`,
-    });
     return {
       session: applied,
       changedPaths: initialPlan.changedPaths,
@@ -644,10 +621,6 @@ export function integrateAgentJob(
           changedFiles: refreshedPlan.changedPaths,
           changeOutcome: "already_integrated",
         });
-        updateTask(repoRoot, run.issueId, run.taskId, {
-          status: "integrated",
-          note: `${runId} became already integrated while finish was running and was recorded through edit session ${alreadyIntegrated.sessionId}; run focused checks and record verification before acceptance.`,
-        });
         return {
           session: alreadyIntegrated,
           changedPaths: refreshedPlan.changedPaths,
@@ -683,10 +656,6 @@ export function integrateAgentJob(
     changedFiles: initialPlan.operations.map((operation) => operation.path),
     changeOutcome: "changed",
   });
-  updateTask(repoRoot, run.issueId, run.taskId, {
-    status: "integrated",
-    note: `${runId} integrated through edit session ${applied.sessionId}; run focused checks and record verification before acceptance.`,
-  });
   return {
     session: applied,
     changedPaths: initialPlan.operations.map((operation) => operation.path),

package/src/cli/agent-jobs/job-manager.ts

@@ -122,7 +122,10 @@ function normalizeAgentMeta(
       : meta.worktree === repoRoot
         ? "workspace"
         : "worktree");
-  meta.autoIntegrate = meta.autoIntegrate ?? meta.executionMode === "worktree";
+  // Integration is an explicit model decision. Historical worktree Runs may
+  // retain this field for read compatibility, but a missing value must never
+  // turn a completed execution into a workflow transition.
+  meta.autoIntegrate = meta.autoIntegrate ?? false;
   meta.closureState = meta.closureState ?? (
     meta.provider === "local" && meta.executionMode === "worktree"
       ? meta.worktreeCleanedAt
@@ -1105,7 +1108,7 @@ function attachExecutorFailureHealth(meta: AgentJobMeta, stdoutTail?: string, st
   }
   if (meta.executorHealth) return meta;
   const message = executorFailureMessage(meta, stdoutTail, stderrTail);
-  const health = classifyExecutorFailure(meta.agent, message, { allowedPaths: meta.allowedPaths ?? [] });
+  const health = classifyExecutorFailure(meta.agent, message);
   if (health) meta.executorHealth = health;
   return meta;
 }
@@ -1261,7 +1264,8 @@ function baseMeta(
     eventsPath: relative(opts.repoRoot, paths.eventsPath).replace(/\\/g, "/"),
     timeoutMs: opts.timeoutMs,
     startupDeadlineAt: new Date(Date.now() + agentStartupTimeoutMs()).toISOString(),
-    autoIntegrate: executionMode === "worktree",
+    // A worktree contains concurrent writes; it does not authorize delivery.
+    autoIntegrate: false,
     progress: {
       phase: "starting",
       currentActivity: "已受理，等待异步启动",

package/src/cli/chatgpt-browser/file-policy.ts

@@ -1,8 +1,8 @@
 import { createHash } from 'crypto';
 import { existsSync, readFileSync, statSync } from 'fs';
 import { isAbsolute, resolve } from 'path';
-import { resolveMcpPath } from '../mcp/paths';
-import type { McpPolicy } from '../mcp/types';
+import { resolveMcpPath } from '../../../adapters/mcp/paths';
+import type { McpPolicy } from '../../../adapters/mcp/types';
 import type { BrowserWriteOutputPolicy, PromptBundleFile } from './types';
 
 const READ_ALLOW_GLOBS = [