@moretea-labs/forge 1.8.1 → 1.8.2

package/supervisor/control-plane.ts

@@ -1,8 +1,11 @@
 import { randomUUID } from 'node:crypto';
 import { parseChatgptConversationIdentity } from './chatgpt-conversation';
-import { parseSupervisorCompletion, renderEffectMarker, renderSupervisorPrompt, sha256, validateEffectId } from './protocol';
+import { parseSupervisorCompletion, renderEffectMarker, renderSupervisorPrompt, sha256, validateEffectId, validateSupervisorObjective } from './protocol';
 import { WorkflowSupervisorStore } from './store';
-import type { WorkflowAssistantObservation, WorkflowAssistantObservationResult, WorkflowContractValidation, WorkflowEffectKind, WorkflowSupervisorAutomationStatus, WorkflowSupervisorBrowserPollResult, WorkflowSupervisorBrowserTask, WorkflowSupervisorCompletion, WorkflowSupervisorDiscoveredConversation, WorkflowSupervisorEffect, WorkflowSupervisorLifecycleHooks, WorkflowSupervisorProjectScope, WorkflowSupervisorTask, WorkflowSupervisorTaskInput, WorkflowSupervisorTerminalState, WorkflowSupervisorValidators } from './types';
+import { getWorkContract } from '../packages/kernel/work/api/index';
+import { readRequirement } from '../src/runtime/control-plane/persistence/requirement-store';
+import { resolveWorkflowSupervisorForgeHome } from './paths';
+import type { WorkflowAssistantObservation, WorkflowAssistantObservationResult, WorkflowContractValidation, WorkflowEffectKind, WorkflowSupervisorBrowserPollResult, WorkflowSupervisorBrowserTask, WorkflowSupervisorCompletion, WorkflowSupervisorDiscoveredConversation, WorkflowSupervisorEffect, WorkflowSupervisorLifecycleHooks, WorkflowSupervisorProjectScope, WorkflowSupervisorTask, WorkflowSupervisorTaskInput, WorkflowSupervisorTerminalState, WorkflowSupervisorValidators, WorkflowSupervisorPreflightComposerObservation } from './types';
 
 function compactProjectIdentity(value: string): string {
   return value.normalize('NFKC').toLocaleLowerCase().replace(/[^\p{L}\p{N}]+/gu, '');
@@ -65,13 +68,47 @@ export class WorkflowSupervisorControlPlane {
     expectedObjectiveSha256: string;
     requestId: string;
     authorizedBy?: string;
-  }): { task: WorkflowSupervisorTask; changed: boolean; deduplicated: boolean; objectiveSha256: string; refreshedEffect?: WorkflowSupervisorEffect } {
+    workId?: string;
+    requirementId?: string;
+    expectedCompletionContractSha256?: string;
+  }): { task: WorkflowSupervisorTask; changed: boolean; deduplicated: boolean; objectiveSha256: string; completionContractSha256: string; semanticBindingChanged: boolean; refreshedEffect?: WorkflowSupervisorEffect } {
     const task = this.requireTask(input.taskId);
     requireNonTerminalTask(this.store, task.taskId);
-    const objective = input.objective.trim();
-    if (!objective || objective.length > 8_000) throw new Error('WORKFLOW_SUPERVISOR_OBJECTIVE_INVALID');
+    const objective = validateSupervisorObjective(input.objective);
     if (!/^[0-9a-f]{64}$/i.test(input.expectedObjectiveSha256)) throw new Error('WORKFLOW_SUPERVISOR_OBJECTIVE_REVISION_EXPECTED_SHA_INVALID');
     if (!input.requestId.trim()) throw new Error('WORKFLOW_SUPERVISOR_OBJECTIVE_REVISION_REQUEST_REQUIRED');
+    const workId = input.workId?.trim() || undefined;
+    const requirementId = input.requirementId?.trim() || undefined;
+    if (workId && requirementId) throw new Error('WORKFLOW_SUPERVISOR_SEMANTIC_BINDING_TARGET_INVALID');
+    if ((workId || requirementId) && !input.expectedCompletionContractSha256) {
+      throw new Error('WORKFLOW_SUPERVISOR_COMPLETION_CONTRACT_REVISION_EXPECTED_SHA_REQUIRED');
+    }
+    if (!workId && !requirementId && input.expectedCompletionContractSha256) {
+      throw new Error('WORKFLOW_SUPERVISOR_COMPLETION_CONTRACT_REVISION_TARGET_REQUIRED');
+    }
+    let semanticBinding: { workId?: string; requirementId?: string; expectedCompletionContractSha256: string } | undefined;
+    if (workId || requirementId) {
+      if (task.completionContract.kind !== 'model_semantic_completion') {
+        throw new Error('WORKFLOW_SUPERVISOR_SEMANTIC_BINDING_REVISION_KIND_UNSUPPORTED');
+      }
+      const controllerHome = typeof task.completionContract.controller_home === 'string' ? task.completionContract.controller_home.trim() : '';
+      const repoId = typeof task.completionContract.repo_id === 'string' ? task.completionContract.repo_id.trim() : '';
+      if (!controllerHome || !repoId
+        || resolveWorkflowSupervisorForgeHome(controllerHome) !== resolveWorkflowSupervisorForgeHome(this.store.forgeHome)) {
+        throw new Error('WORKFLOW_SUPERVISOR_SEMANTIC_BINDING_CONTEXT_REQUIRED');
+      }
+      if (workId && !getWorkContract({ controllerHome, scopeKey: repoId }, workId)) {
+        throw new Error('WORKFLOW_SUPERVISOR_SEMANTIC_BINDING_WORK_NOT_FOUND');
+      }
+      if (requirementId && !readRequirement({ controllerHome }, requirementId)?.value) {
+        throw new Error('WORKFLOW_SUPERVISOR_SEMANTIC_BINDING_REQUIREMENT_NOT_FOUND');
+      }
+      semanticBinding = {
+        ...(workId ? { workId } : {}),
+        ...(requirementId ? { requirementId } : {}),
+        expectedCompletionContractSha256: input.expectedCompletionContractSha256!,
+      };
+    }
     const pending = this.store.currentUnappliedEffect(task.taskId);
     let refreshEffect: { effectId: string; expectedPrompt: string; prompt: string } | undefined;
     if (pending && !this.store.latestEffectDispatch(pending.effectId)) {
@@ -89,6 +126,7 @@ export class WorkflowSupervisorControlPlane {
       expectedObjectiveSha256: input.expectedObjectiveSha256.toLowerCase(),
       requestId: input.requestId.trim(),
       authorizedBy: input.authorizedBy?.trim() || 'operator',
+      ...(semanticBinding ? { semanticBinding } : {}),
       ...(refreshEffect ? { refreshEffect } : {}),
     });
   }
@@ -134,6 +172,14 @@ export class WorkflowSupervisorControlPlane {
       throw new Error('WORKFLOW_SUPERVISOR_RECOVERY_SOURCE_CHANGED');
     }
     if (pending) {
+      if (this.store.effectDispatchBudget(pending.effectId).generations === 0) {
+        // Browser provider was repaired independently of Forge's source release.
+        // The old enrollment text and effect identity remain authoritative;
+        // rearm a single preparation without manufacturing a provider send.
+        this.store.authorizeOperatorPreflightRetry({ effectId: pending.effectId, requestId: input.requestId,
+          reason: input.reason, authorizedBy });
+        return { recoveryEffect: pending, action: 'retry_authorized' };
+      }
       // Read-only reclassification first: a dispatch-owner pre-send return is a
       // stronger fact than any operator decision and makes the effect retryable
       // through the normal mechanical path.
@@ -236,6 +282,31 @@ export class WorkflowSupervisorControlPlane {
     const tasks = this.store.listTasks();
     return activeOnly ? tasks.filter((task) => !this.store.terminalAction(task.taskId)) : tasks;
   }
+  /**
+   * Completed/blocked/stopped history is a read-only projection of canonical
+   * terminal events. It never archives the ChatGPT conversation or rewrites Work.
+   */
+  listTerminalTasks(): Array<{ task: WorkflowSupervisorTask; terminal: WorkflowSupervisorTerminalState }> {
+    return this.store.listTasks().flatMap((task) => {
+      const terminal = this.store.terminalAction(task.taskId);
+      return terminal ? [{ task, terminal }] : [];
+    });
+  }
+  /** Reconcile Work-owned task closure after a crash or a direct Work writer.
+   * Independent Requirement and standalone Goals are intentionally excluded.
+   */
+  reconcileTerminalWorkBoundTasks(): string[] {
+    if (!this.hooks.terminalWorkStopReasonForTask) return [];
+    const stopped: string[] = [];
+    for (const task of this.store.listTasks()) {
+      if (this.store.terminalAction(task.taskId)) continue;
+      const reason = this.hooks.terminalWorkStopReasonForTask(task);
+      if (!reason) continue;
+      const result = this.store.stopTask(task.taskId, reason);
+      if (!result.deduplicated) stopped.push(task.taskId);
+    }
+    return stopped;
+  }
   stopTask(taskId: string, reason = 'Stopped by operator request.'): { taskId: string; terminal: 'STOPPED'; deduplicated: boolean } {
     return this.store.stopTask(taskId, reason);
   }
@@ -251,6 +322,51 @@ export class WorkflowSupervisorControlPlane {
     return task;
   }
   getEffect(id: string): WorkflowSupervisorEffect | undefined { return this.store.getEffect(validateEffectId(id)); }
+  preSendComposerObservation(effectId: string): WorkflowSupervisorPreflightComposerObservation | undefined {
+    return this.store.preSendComposerObservation(validateEffectId(effectId));
+  }
+  /** Bind the one canonical Scheduler occurrence lane to an exact Work-owned Supervisor task. */
+  bindScheduledWake(input: { taskId: string; repoId: string; workId: string; scheduleId: string }) {
+    const task = this.requireTask(input.taskId);
+    requireNonTerminalTask(this.store, task.taskId);
+    const bound = this.store.bindScheduledWake(input);
+    const pending = this.store.currentUnappliedEffect(task.taskId);
+    if (pending && !this.store.latestEffectDispatch(pending.effectId) && !this.store.effectApplied(pending.effectId)) {
+      const source = pending.sourceCompletionFingerprint ? this.store.getCompletion(pending.sourceCompletionFingerprint) : undefined;
+      const checkpoint = source?.proposal.reason === 'compact_receipt' ? undefined : source?.proposal.checkpoint;
+      this.store.refreshUndispatchedEffectPrompt({
+        taskId: task.taskId,
+        effectId: pending.effectId,
+        expectedPrompt: pending.prompt,
+        prompt: this.renderPrompt(bound.task, pending.effectId, pending.kind, checkpoint),
+      });
+    }
+    return bound;
+  }
+  /** Consume a completed WAIT receipt exactly once for one exact Scheduler occurrence. */
+  wakeScheduledTask(input: { taskId: string; scheduleId: string; occurrenceId: string }): { effect: WorkflowSupervisorEffect; deduplicated: boolean } {
+    const task = this.requireTask(input.taskId);
+    if (task.continuationPolicy.scheduled_wake_schedule_id !== input.scheduleId) {
+      throw new Error('WORKFLOW_SUPERVISOR_SCHEDULE_BINDING_MISMATCH');
+    }
+    const originKey = `scheduled-wake:${input.scheduleId}:${input.occurrenceId}`;
+    const id = stableEffectId(originKey);
+    const prior = this.store.getEffectByOriginKey(originKey);
+    if (prior) {
+      if (prior.taskId !== task.taskId || prior.effectId !== id || prior.kind !== 'continuation' || !prior.sourceCompletionFingerprint) {
+        throw new Error('WORKFLOW_SUPERVISOR_SCHEDULED_WAKE_IDENTITY_CONFLICT');
+      }
+      return { effect: prior, deduplicated: true };
+    }
+    requireNonTerminalTask(this.store, task.taskId);
+    return this.store.reserveScheduledWake({
+      taskId: task.taskId,
+      scheduleId: input.scheduleId,
+      occurrenceId: input.occurrenceId,
+      effectId: id,
+      prompt: this.renderPrompt(task, id, 'continuation', `scheduled wake ${input.scheduleId} occurrence ${input.occurrenceId}`),
+    });
+  }
   /** Read-only stall classification for one task; no lifecycle authority. */
   taskStall(taskId: string): ReturnType<WorkflowSupervisorStore['taskStall']> { return this.store.taskStall(this.requireTask(taskId).taskId); }
   /**
@@ -407,39 +523,41 @@ export class WorkflowSupervisorControlPlane {
     if (!task.conversationId.startsWith('bootstrap:')) throw new Error('WORKFLOW_SUPERVISOR_BOOTSTRAP_NOT_PENDING');
     const terminal = this.store.terminalAction(task.taskId);
     if (terminal === 'STOPPED') return { authorized: true, task: browserTask(task), terminal };
-    const pending = this.store.nextBrowserEffect(task.taskId);
-    if (pending) {
+    // While identity is still bootstrap, reconcile the latest applied leaf
+    // before dispatching any successor. An unstarted recovery child must not
+    // send from a Project/new-composer surface while the source conversation
+    // is still unbound. The existing effect ledger owns observation cooldown.
+    const applied = this.store.latestAppliedLeafEffectWithoutCompletion(task.taskId);
+    if (applied) {
+      if (!this.store.bootstrapAppliedReconcileDue(applied.effectId)) {
+        return { authorized: true, task: browserTask(task) };
+      }
+      const dispatch = this.store.latestEffectDispatch(applied.effectId);
       return {
         authorized: true,
         task: browserTask(task),
         command: {
-          mode: pending.mode,
-          effectId: pending.effect.effectId,
-          kind: pending.effect.kind,
-          prompt: pending.effect.prompt,
-          dispatchGeneration: pending.generation,
+          mode: 'reconcile',
+          effectId: applied.effectId,
+          kind: applied.kind,
+          prompt: applied.prompt,
+          dispatchGeneration: dispatch?.generation ?? 1,
           conversationId: task.conversationId,
           conversationUrl: task.conversationUrl,
         },
       };
     }
-    // Provider application and bootstrap identity binding are separate facts.
-    // A confirmed send may already be applied while ChatGPT has only just
-    // canonicalized the new /c/<conversation> route. Keep one read-only
-    // reconciliation command for that applied effect so the exact conversation
-    // can be bound without manufacturing another provider generation.
-    const applied = this.store.latestAppliedEffectWithoutCompletion(task.taskId);
-    if (!applied) return { authorized: true, task: browserTask(task) };
-    const dispatch = this.store.latestEffectDispatch(applied.effectId);
+    const pending = this.store.nextBrowserEffect(task.taskId);
+    if (!pending) return { authorized: true, task: browserTask(task) };
     return {
       authorized: true,
       task: browserTask(task),
       command: {
-        mode: 'reconcile',
-        effectId: applied.effectId,
-        kind: applied.kind,
-        prompt: applied.prompt,
-        dispatchGeneration: dispatch?.generation ?? 1,
+        mode: pending.mode,
+        effectId: pending.effect.effectId,
+        kind: pending.effect.kind,
+        prompt: pending.effect.prompt,
+        dispatchGeneration: pending.generation,
         conversationId: task.conversationId,
         conversationUrl: task.conversationUrl,
       },
@@ -468,13 +586,17 @@ export class WorkflowSupervisorControlPlane {
       const pending = this.store.nextBrowserEffect(task.taskId);
       const dispatch = this.store.latestEffectDispatch(effect.effectId);
       if (!pending || pending.effect.effectId !== effect.effectId || pending.mode !== 'reconcile'
-        || !dispatch || pending.generation !== dispatch.generation) {
+        || !dispatch || pending.generation !== dispatch.generation
+        || dispatch.evidence.surface !== 'computer-bootstrap'
+        || input.evidence?.dispatch_mutation !== 'not_attempted'
+        || input.evidence?.send_clicked !== false) {
         throw new Error('WORKFLOW_SUPERVISOR_BOOTSTRAP_NOT_APPLIED_PROOF_INVALID');
       }
       this.store.recordEffectNotAppliedProof(effect.effectId, input.observationId, {
-        surface: 'computer-bootstrap',
+        surface: 'computer-bootstrap', send_clicked: false,
         dispatch_generation: dispatch.generation,
         pre_send_rejection: true,
+        attestation: 'local_computer_dispatch_returned_without_send',
       });
       return;
     }
@@ -482,12 +604,12 @@ export class WorkflowSupervisorControlPlane {
     this.observeEffect({ effectId: effect.effectId, observationId: input.observationId, outcome: input.outcome, evidence });
     if (input.outcome === 'applied') this.hooks.effectApplied?.(task, effect, { observationId: input.observationId, evidence });
   }
-  /** Local Computer preparation returned before Send intent; persist in the existing effect ledger. */
-  recordProviderPreparationFailure(input: { taskId: string; effectId: string; reasonCode: string }): void {
+  /** Persist a bounded preflight rejection; started generations require an exact no-click proof first. */
+  recordProviderPreparationFailure(input: { taskId: string; effectId: string; reasonCode: string; composerObservation?: WorkflowSupervisorPreflightComposerObservation }): void {
     const task = this.requireTask(input.taskId);
     const effect = this.store.getEffect(input.effectId);
     if (effect?.taskId !== task.taskId) throw new Error('WORKFLOW_SUPERVISOR_PRE_SEND_EFFECT_TASK_MISMATCH');
-    this.store.recordEffectPreparationFailure(input.effectId, input.reasonCode);
+    this.store.recordEffectPreparationFailure(input.effectId, input.reasonCode, input.composerObservation);
   }
 
   browserBeginEffect(input: { conversationId: string; conversationUrl: string; effectId: string; dispatchId: string; dispatchGeneration: number; evidence?: Record<string, unknown> }): { started: boolean; mode: 'send' | 'reconcile'; generation: number } {
@@ -543,17 +665,25 @@ export class WorkflowSupervisorControlPlane {
     if (dispatch?.generation !== input.dispatchGeneration) throw new Error('WORKFLOW_SUPERVISOR_DISPATCH_GENERATION_CHANGED');
     this.store.recordEffectNotAppliedProof(input.effectId, input.observationId, {
       surface: input.surface?.trim().slice(0, 128) || 'macos-native', reason: input.reason, send_clicked: false, dispatch_generation: input.dispatchGeneration,
-      // This call is the dispatch owner's own mechanical return, produced before
-      // any Send click. Marking it as a pre-send rejection is what lets the one
-      // bounded budget refund apply, exactly as the bootstrap path does; without
-      // it a purely local obstacle permanently exhausted the effect.
+      // This call is the dispatch owner's exact mechanical return before any
+      // Send click. The store refunds this generation once; the existing preflight
+      // gate bounds ordinary repeats without spending actual send budget.
       pre_send_rejection: true,
     });
+    const recoveryStopPending = effect.kind === 'recovery' && input.reason.trim() === 'provider_recovery_stop_pending';
+    if (!recoveryStopPending) {
+      this.recordProviderPreparationFailure({ taskId: task.taskId, effectId: effect.effectId, reasonCode: input.reason });
+    }
   }
   browserObserveProviderTurn(input: { conversationId: string; conversationUrl: string; generating: boolean; latestAssistantResponse: string; providerActivityText?: string; providerFailureCode?: string; receiptMissing?: boolean; observedAtMs: number; graceMs: number }): { state: 'inactive' | 'none' | 'generating' | 'idle_pending' | 'recovery_reserved' | 'exhausted'; recoveryEffect?: WorkflowSupervisorEffect } {
     const task = this.requireBrowserTask(input.conversationId, input.conversationUrl);
     if (!this.browserTaskActiveForExternalEffect(task)) return { state: 'inactive' };
-    const sourceEffect = this.store.latestAppliedEffectWithoutCompletion(task.taskId);
+    // Exhaustion stops new recovery mutations, not read-only observation of the exhausted applied leaf.
+    let sourceEffect = this.store.latestAppliedEffectWithoutCompletion(task.taskId);
+    if (!sourceEffect) {
+      const exhaustedLeaf = this.store.latestAppliedLeafEffectWithoutCompletion(task.taskId);
+      if (exhaustedLeaf && this.store.providerResumeExhausted(exhaustedLeaf.effectId)) sourceEffect = exhaustedLeaf;
+    }
     if (!sourceEffect) return { state: 'none' };
     const recoveryId = stableEffectId(`provider-recovery:${sourceEffect.effectId}`);
     const providerFailureCode = input.providerFailureCode?.trim();
@@ -613,8 +743,8 @@ export class WorkflowSupervisorControlPlane {
         if (committed.successorEffect) reconciled += 1;
         continue;
       }
-      const validator = latest.action === 'DONE' ? this.validators.completionContract : this.validators.userBlockerPolicy;
-      const validation = await validator(task, latest.proposal);
+      if (latest.action === 'WAIT') continue;
+      const validation = await this.validateTerminalProposal(task, latest.proposal);
       const correctionId = validation.valid ? undefined : stableEffectId(`completion:${latest.completionFingerprint}`);
       this.store.resolveTerminal({
         completionFingerprint: latest.completionFingerprint,
@@ -646,9 +776,10 @@ export class WorkflowSupervisorControlPlane {
     // original effect context for idempotent duplicate observation.
     const priorCompletion = expectedEffect ? undefined : this.store.getCompletionByResponseSha256(task.taskId, responseSha256);
     const expectedEffectId = expectedEffect?.effectId ?? priorCompletion?.sourceEffectId;
+    const receiptEffect = expectedEffect ?? (expectedEffectId ? this.store.getEffect(expectedEffectId) : undefined);
     const parsed = parseSupervisorCompletion(
       input.responseText,
-      expectedEffectId ? { task, effectId: expectedEffectId } : undefined,
+      expectedEffectId ? { task, effectId: expectedEffectId, prompt: receiptEffect?.prompt } : undefined,
     );
     const sourceEffect = this.store.getEffect(parsed.proposal.sourceEffectId);
     if (!sourceEffect || sourceEffect.taskId !== task.taskId || !this.store.effectApplied(sourceEffect.effectId)) throw new Error('WORKFLOW_SUPERVISOR_CAUSAL_EFFECT_NOT_APPLIED');
@@ -675,81 +806,19 @@ export class WorkflowSupervisorControlPlane {
       const committed = this.reserveContinuation(task, completion);
       return { action: 'CONTINUE', completionFingerprint, terminal: false, successorEffect: committed.successorEffect!, deduplicated: committed.deduplicated };
     }
+    if (parsed.proposal.action === 'WAIT') {
+      const committed = this.store.commitCompletion(completion);
+      return { action: 'WAIT', completionFingerprint, terminal: false, deduplicated: committed.deduplicated };
+    }
     const committed = this.store.commitCompletion(completion);
 
-    const validator = parsed.proposal.action === 'DONE' ? this.validators.completionContract : this.validators.userBlockerPolicy;
-    const validation = await validator(task, parsed.proposal);
+    const validation = await this.validateTerminalProposal(task, parsed.proposal);
     const correctionId = validation.valid ? undefined : stableEffectId(`completion:${completionFingerprint}`);
     const resolved = this.store.resolveTerminal({ completionFingerprint, taskId: task.taskId, action: parsed.proposal.action, accepted: validation.valid, reason: validation.reason,
       ...(correctionId ? { correction: { effectId: correctionId, prompt: this.renderPrompt(task, correctionId, 'correction', parsed.proposal.reason === 'compact_receipt' ? undefined : parsed.proposal.checkpoint, validation.reason) } } : {}) });
     return { action: parsed.proposal.action, completionFingerprint, terminal: validation.valid, ...(resolved.successorEffect ? { successorEffect: resolved.successorEffect } : {}), validation, deduplicated: committed.deduplicated || resolved.deduplicated };
   }
 
-  /**
-   * The autonomous transport records its final state through the Forge tool
-   * call, not through text rendered in the ChatGPT page.  The exact task and
-   * applied effect are derived locally; callers cannot select a different
-   * conversation or effect by supplying model-authored identifiers.
-   */
-  async observeAutomationReceipt(input: {
-    taskId: string;
-    conversationId: string;
-    status: WorkflowSupervisorAutomationStatus;
-    receiptId: string;
-  }): Promise<WorkflowAssistantObservationResult | { recorded: true }> {
-    if (input.status === 'working') return { recorded: true };
-    const task = this.requireTask(input.taskId);
-    if (task.conversationId !== input.conversationId) throw new Error('WORKFLOW_SUPERVISOR_CONVERSATION_MISMATCH');
-    const terminal = this.store.terminalAction(task.taskId);
-    if (terminal) throw new Error(`WORKFLOW_SUPERVISOR_TASK_TERMINAL:${terminal}`);
-    const expectedEffect = this.store.latestAppliedEffectWithoutCompletion(task.taskId)
-      ?? this.store.latestAppliedLeafEffectWithoutCompletion(task.taskId);
-    // A provider can reuse one tool name/status in successive outer turns.
-    // Include the locally selected effect in the durable receipt identity so a
-    // later `continue` cannot replay the first effect's completion.
-    const replayCompletion = expectedEffect ? undefined : this.store.getLatestCompletion(task.taskId);
-    if (!expectedEffect && (!replayCompletion
-      || replayCompletion.proposal.checkpoint !== `automation:${input.receiptId}:${replayCompletion.sourceEffectId}`)) {
-      throw new Error('WORKFLOW_SUPERVISOR_CAUSAL_EFFECT_NOT_APPLIED');
-    }
-    const receiptForEffect = `${input.receiptId}:${expectedEffect?.effectId ?? replayCompletion!.sourceEffectId}`;
-    const responseText = `automation:${input.status}:${receiptForEffect}`;
-    const responseSha256 = sha256(responseText);
-    const priorCompletion = expectedEffect ? undefined : this.store.getCompletionByResponseSha256(task.taskId, responseSha256);
-    const sourceEffect = expectedEffect ?? (priorCompletion ? this.store.getEffect(priorCompletion.sourceEffectId) : undefined);
-    if (!sourceEffect || sourceEffect.taskId !== task.taskId || !this.store.effectApplied(sourceEffect.effectId)) {
-      throw new Error('WORKFLOW_SUPERVISOR_CAUSAL_EFFECT_NOT_APPLIED');
-    }
-    const action = input.status === 'continue' ? 'CONTINUE' : input.status === 'done' ? 'DONE' : 'NEEDS_USER';
-    const proposal = {
-      action: action as 'CONTINUE' | 'DONE' | 'NEEDS_USER',
-      sourceEffectId: sourceEffect.effectId,
-      checkpoint: `automation:${receiptForEffect}`,
-      reason: 'automation_tool_receipt',
-      evidence: [],
-      conversationId: task.conversationId,
-      taskId: task.taskId,
-      supervisorState: action === 'CONTINUE' ? 'running' as const : action === 'DONE' ? 'done' as const : 'needs_user' as const,
-    };
-    const controlBlockSha256 = sha256(responseText);
-    const completionFingerprint = sha256(jsonIdentity(task.taskId, task.conversationId, sourceEffect.effectId, responseSha256, controlBlockSha256));
-    const completion: WorkflowSupervisorCompletion = { completionFingerprint, taskId: task.taskId, sourceEffectId: sourceEffect.effectId, action: proposal.action, responseSha256, controlBlockSha256, proposal, committedAt: new Date().toISOString() };
-    if (proposal.action === 'CONTINUE') {
-      const committed = this.reserveContinuation(task, completion);
-      return { action: 'CONTINUE', completionFingerprint, terminal: false, successorEffect: committed.successorEffect!, deduplicated: committed.deduplicated };
-    }
-    const committed = this.store.commitCompletion(completion);
-    const validation = proposal.action === 'DONE'
-      ? await this.validators.completionContract(task, proposal)
-      : await this.validators.userBlockerPolicy(task, proposal);
-    const correctionId = validation.valid ? undefined : stableEffectId(`completion:${completionFingerprint}`);
-    const resolved = this.store.resolveTerminal({
-      completionFingerprint, taskId: task.taskId, action: proposal.action, accepted: validation.valid, reason: validation.reason,
-      ...(correctionId ? { correction: { effectId: correctionId, prompt: this.renderPrompt(task, correctionId, 'correction', proposal.checkpoint, validation.reason) } } : {}),
-    });
-    return { action: proposal.action, completionFingerprint, terminal: validation.valid, ...(resolved.successorEffect ? { successorEffect: resolved.successorEffect } : {}), validation, deduplicated: committed.deduplicated || resolved.deduplicated };
-  }
-
   /** Model CONTINUE and its causal successor commit in the same authority transaction. */
   private reserveContinuation(task: WorkflowSupervisorTask, completion: WorkflowSupervisorCompletion) {
     const nextId = stableEffectId(`completion:${completion.completionFingerprint}`);
@@ -765,6 +834,32 @@ export class WorkflowSupervisorControlPlane {
     });
   }
 
+  private async validateTerminalProposal(
+    task: WorkflowSupervisorTask,
+    proposal: WorkflowSupervisorCompletion['proposal'],
+  ): Promise<WorkflowContractValidation> {
+    const validator = proposal.action === 'DONE' ? this.validators.completionContract : this.validators.userBlockerPolicy;
+    const validation = await validator(task, proposal);
+    if (typeof task.continuationPolicy.scheduled_wake_schedule_id !== 'string') return validation;
+    if (proposal.action === 'DONE') {
+      return {
+        ...validation,
+        valid: false,
+        reason: validation.valid ? 'scheduled_work_must_wait' : validation.reason,
+        evidence: [...(validation.evidence ?? []), 'A Work-bound recurring Schedule owns the next run; use WAIT instead of terminal DONE.'],
+      };
+    }
+    if (proposal.action === 'NEEDS_USER') {
+      return {
+        ...validation,
+        valid: false,
+        reason: validation.valid ? 'scheduled_work_must_remain_open' : validation.reason,
+        evidence: [...(validation.evidence ?? []), 'Persist the exact user blocker and use WAIT; a recurring scheduled Work must remain open.'],
+      };
+    }
+    return validation;
+  }
+
   private renderPrompt(
     task: WorkflowSupervisorTask,
     effectId: string,
@@ -801,18 +896,18 @@ export class WorkflowSupervisorControlPlane {
     if (!effect.sourceCompletionFingerprint) return true;
     const completion = this.store.getCompletion(effect.sourceCompletionFingerprint);
     if (!completion || completion.taskId !== task.taskId) return false;
-    // Text-parsed completions are causally anchored to the exact assistant page
-    // response that produced the Supervisor receipt. Automation tool receipts are
-    // different: their responseSha256 hashes the synthetic durable receipt carrier,
-    // not text rendered in ChatGPT. The page can also collapse the prior automated
-    // prompt to ordinary visible prose, so neither the response hash nor its effect
-    // marker is a valid prerequisite for delivering the already-reserved successor.
-    // The durable receipt has already bound task, conversation, and source effect;
-    // retain that local causal fence and skip only the unavailable page-text proof.
-    const automationToolReceipt = completion.proposal.reason === 'automation_tool_receipt';
+    // A compact completion is committed only after observing the provider's
+    // finished assistant reply and checking its causal challenge. ChatGPT may
+    // subsequently collapse that historical reply or its original user marker;
+    // requiring the bytes to remain in the DOM would strand a valid successor.
+    // Persisted legacy tool receipts are read-only migration evidence; the MCP
+    // receipt writer has been retired. In both cases the committed completion,
+    // not a new heuristic, is the one authority for the successor.
+    const durableReceipt = completion.proposal.reason === 'compact_receipt'
+      || completion.proposal.reason === 'automation_tool_receipt';
     const sourceEffect = this.store.getEffect(completion.sourceEffectId);
     if (!sourceEffect || sourceEffect.taskId !== task.taskId) return false;
-    if (automationToolReceipt) return true;
+    if (durableReceipt) return true;
     if (sha256(snapshot.latestAssistantResponse) !== completion.responseSha256) return false;
     return normalizeBrowserText(snapshot.latestUserText) === normalizeBrowserText(sourceEffect.prompt)
       || browserTextHasEffect(snapshot.latestUserText, sourceEffect.effectId);

package/supervisor/forge-validators.ts

@@ -1,5 +1,6 @@
 import { isLegacyMachineRequirementWait, readRequirement } from '../src/runtime/control-plane/persistence/requirement-store';
-import { getWorkContract, isTerminalSemanticWorkState } from '../packages/kernel/work/api/index';
+import { getWorkContract, isTerminalSemanticWorkState, readWorkContractLineageSnapshot, type SemanticWorkState } from '../packages/kernel/work/api/index';
+import { SEMANTIC_SCOPE_KEY } from '../src/cli/repositories/controller-home';
 import type { WorkflowContractValidation, WorkflowSupervisorProposal, WorkflowSupervisorTask, WorkflowSupervisorValidators } from './types';
 
 function contractText(task: WorkflowSupervisorTask, key: string): string | undefined {
@@ -11,8 +12,8 @@ function requirementFor(task: WorkflowSupervisorTask, proposal?: WorkflowSupervi
   const controllerHome = contractText(task, 'controller_home');
   const repoId = contractText(task, 'repo_id');
   const workId = contractText(task, 'work_id');
-  const workRequirementId = controllerHome && repoId && workId
-    ? getWorkContract({ controllerHome, repoId }, workId)?.requirementId
+  const workRequirementId = controllerHome && workId
+    ? getWorkContract({ controllerHome, scopeKey: repoId ?? SEMANTIC_SCOPE_KEY }, workId)?.requirementId
     : undefined;
   // activeScope is legacy read compatibility only. New receipts never make model
   // output authoritative for Requirement identity.
@@ -28,37 +29,103 @@ function workFor(task: WorkflowSupervisorTask) {
   const controllerHome = contractText(task, 'controller_home');
   const repoId = contractText(task, 'repo_id');
   const workId = contractText(task, 'work_id');
-  return controllerHome && repoId && workId ? getWorkContract({ controllerHome, repoId }, workId) : undefined;
+  return controllerHome && workId
+    ? getWorkContract({ controllerHome, scopeKey: repoId ?? SEMANTIC_SCOPE_KEY }, workId) : undefined;
+}
+
+
+function boundWorkLineage(task: WorkflowSupervisorTask, requirementId?: string): WorkflowContractValidation | undefined {
+  const controllerHome = contractText(task, 'controller_home');
+  const repoId = contractText(task, 'repo_id');
+  const workId = requirementId ? undefined : contractText(task, 'work_id');
+  if (!controllerHome || (!workId && !requirementId)) return undefined;
+  // Repository rows are compatibility evidence; portable semantic rows win by identity.
+  const scopes = repoId ? [repoId, SEMANTIC_SCOPE_KEY] : [SEMANTIC_SCOPE_KEY];
+  const byId = new Map<string, { workId: string; requirementId?: string; parentWorkId?: string;
+    semanticParentWorkId?: string; dependsOnWorkIds?: string[]; predecessorWorkId?: string;
+    supersedes?: string[]; supersededBy?: string; semanticState?: SemanticWorkState; error?: string }>();
+  for (const scopeKey of new Set(scopes)) {
+    const snapshot = readWorkContractLineageSnapshot({ controllerHome, scopeKey });
+    if (snapshot.contracts.length + snapshot.invalid.length >= 5_000) return unsupported('work_lineage_read_limit');
+    for (const work of [...snapshot.contracts, ...snapshot.invalid]) byId.set(work.workId, work);
+  }
+  const relevant = new Set<string>(workId ? [workId] : [...byId.values()]
+    .filter((work) => work.requirementId === requirementId).map((work) => work.workId));
+  let expanded = true;
+  while (expanded) {
+    expanded = false;
+    for (const work of byId.values()) {
+      if (relevant.has(work.parentWorkId ?? '') || relevant.has(work.semanticParentWorkId ?? '')
+        || relevant.has(work.predecessorWorkId ?? '') || (work.supersedes ?? []).some((id) => relevant.has(id))) {
+        if (!relevant.has(work.workId)) { relevant.add(work.workId); expanded = true; }
+      }
+      if (relevant.has(work.workId)) {
+        for (const dependency of [...(work.dependsOnWorkIds ?? []), ...(work.supersededBy ? [work.supersededBy] : [])]) {
+          if (!relevant.has(dependency)) { relevant.add(dependency); expanded = true; }
+        }
+      }
+    }
+  }
+  const blockers = [...relevant].filter((id) => {
+    const work = byId.get(id);
+    return !work || Boolean(work.error) || !work.semanticState || !isTerminalSemanticWorkState(work.semanticState);
+  }).sort();
+  return blockers.length > 0
+    ? { valid: false, reason: 'bound_work_lineage_not_terminal', evidence: blockers.slice(0, 8) }
+    : undefined;
+}
+
+function validateWorkCompletion(task: WorkflowSupervisorTask): WorkflowContractValidation {
+  const work = workFor(task);
+  return work && work.semanticState === 'completed'
+    ? boundWorkLineage(task) ?? { valid: true, reason: 'work_terminal_committed' }
+    : unsupported('work_not_completed');
+}
+
+function validateRequirementCompletion(task: WorkflowSupervisorTask, proposal: WorkflowSupervisorProposal): WorkflowContractValidation {
+  const requirement = requirementFor(task, proposal);
+  if (!requirement) return unsupported('requirement_not_found');
+  if (requirement.state !== 'done' || !requirement.semanticAcceptance) {
+    return { valid: false, reason: 'requirement_not_semantically_done:' + requirement.state, evidence: requirement.auditRefs.slice(-8) };
+  }
+  return boundWorkLineage(task, requirement.requirementId)
+    ?? { valid: true, reason: 'requirement_semantic_acceptance_committed', evidence: requirement.auditRefs.slice(-8) };
 }
 
 /**
- * Workflow Supervisor validates only the already-authoritative Forge Goal state.
- * It never re-derives Work/Plan completion and never turns infrastructure failure
- * into a user blocker on its own.
+ * A standalone task may intentionally have no semantic target. When it names a
+ * Work or Requirement, DONE must use the same committed semantic proof as the
+ * corresponding typed completion contract. Repository provenance alone is not
+ * a semantic binding, and proposal text never creates one.
  */
+function validateSemanticCompletionBinding(task: WorkflowSupervisorTask, proposal: WorkflowSupervisorProposal): WorkflowContractValidation {
+  const workId = contractText(task, 'work_id');
+  const requirementId = contractText(task, 'requirement_id');
+  if (workId && requirementId) return unsupported('semantic_completion_binding_ambiguous');
+  if (workId) return validateWorkCompletion(task);
+  if (requirementId) return validateRequirementCompletion(task, proposal);
+  return { valid: true, reason: 'model_semantic_completion' };
+}
+
+/** Read committed semantic Goal and explicit Work lineage without changing either authority. */
 export function forgeWorkflowSupervisorValidators(): WorkflowSupervisorValidators {
   return {
     completionContract: async (task, proposal) => {
       if (task.completionContract.kind === 'model_semantic_completion') {
-        return { valid: true, reason: 'model_semantic_completion' };
-      }
-      if (task.completionContract.kind === 'forge_work_done') {
-        const work = workFor(task);
-        return work && isTerminalSemanticWorkState(work.semanticState)
-          ? { valid: true, reason: 'work_terminal_committed' }
-          : unsupported('work_not_terminal');
+        return validateSemanticCompletionBinding(task, proposal);
       }
+      if (task.completionContract.kind === 'forge_work_done') return validateWorkCompletion(task);
       if (!['forge_requirement_done', 'forge_dynamic_requirement_done'].includes(String(task.completionContract.kind ?? ''))) return unsupported('completion_contract_kind_unsupported');
-      const requirement = requirementFor(task, proposal);
-      if (!requirement) return unsupported('requirement_not_found');
-      if (requirement.state !== 'done' || !requirement.semanticAcceptance) {
-        return { valid: false, reason: `requirement_not_semantically_done:${requirement.state}`, evidence: requirement.auditRefs.slice(-8) };
-      }
-      return { valid: true, reason: 'requirement_semantic_acceptance_committed', evidence: requirement.auditRefs.slice(-8) };
+      return validateRequirementCompletion(task, proposal);
     },
     userBlockerPolicy: async (task, proposal) => {
       if (task.userBlockerPolicy.kind === 'model_semantic_user_blocker') {
-        return { valid: true, reason: 'model_semantic_user_blocker' };
+        // Tool visibility is a provider failure, not a decision or permission
+        // only the user can supply. Use the immutable completion evidence;
+        // do not add another task state or rely on transient browser text.
+        return proposal.evidence.includes('NO_TOOL_RECEIPT')
+          ? { valid: false, reason: 'tool_unavailable_not_user_blocker' }
+          : { valid: true, reason: 'model_semantic_user_blocker' };
       }
       if (task.userBlockerPolicy.kind === 'forge_work_waiting_for_user') {
         const work = workFor(task);