@moretea-labs/forge 1.8.0 → 1.8.2

package/src/runtime/workflow/schedules/work-continuation.ts

@@ -1,10 +1,11 @@
 import { createHash } from 'crypto';
-import { getWorkContract, isTerminalWorkContractStatus, type WorkContract } from '../../../../packages/kernel/work/api/index';
-import { getRetainedControllerSession, type ControllerRoundRelayRecord, type ControllerType } from '../../../../packages/kernel/controller/api/index';
+import { getWorkContract, semanticWorkState, type WorkContract } from '../../../../packages/kernel/work/api/index';
+import { getControllerRoundRelay, getRetainedControllerSession, rearmControllerRoundAfterProviderUserAction, type ControllerRoundRelayRecord, type ControllerType } from '../../../../packages/kernel/controller/api/index';
 import { ensureScheduledControllerBinding } from '../../root/scheduled-controller-composition';
 import { resolveHandoffItem } from '../../control-plane/facade/handoff-inbox-store';
 import type { HandoffItem } from '../../control-plane/facade/types';
 import { readWorkHandle, type WorkHandleState } from '../../control-plane/execution/work-handle-store';
+import { touchSchedulerWakeSignal } from '../../control-plane/global-scheduler/wake-signal';
 
 import { assertAutomatedOperationAllowed } from '../../control-plane/governance/external-effects';
 import { evaluateSchedule } from './engine';
@@ -27,10 +28,19 @@ import type {
 export type ContinuationControllerType = Exclude<ControllerType, 'human'>;
 export type WorkScheduleMode = 'continuation' | 'browser_watch' | 'browser_keepalive';
 
+const CONTROLLER_PROGRESSION_OPERATION = 'controller_progression';
+const LEGACY_EXTERNAL_CONTROLLER_WAKE_OPERATION = 'external_controller_wake';
+
+function isWorkContinuationOperation(operation: string): boolean {
+  return operation === CONTROLLER_PROGRESSION_OPERATION || operation === LEGACY_EXTERNAL_CONTROLLER_WAKE_OPERATION;
+}
+
 export interface WorkContinuationScheduleInput {
   workId?: string;
   scheduleMode?: WorkScheduleMode;
   controllerType?: ContinuationControllerType;
+  /** Exact interactive Browser grants to carry into the scheduled Controller binding. */
+  authorizationGrantRefs?: string[];
   executable?: string;
   launchArgs?: string[];
   launchReservationMs?: number;
@@ -85,12 +95,12 @@ function requiredWork(controllerHome: string, repoId: string, workId: string): W
 
 function activeWork(controllerHome: string, repoId: string, workId: string): WorkContract {
   const work = requiredWork(controllerHome, repoId, workId);
-  if (isTerminalWorkContractStatus(work.status)) throw new Error(`WORK_ALREADY_TERMINAL: ${work.workId}:${work.status}`);
+  if (semanticWorkState(work) !== 'open') throw new Error(`WORK_ALREADY_TERMINAL: ${work.workId}:${semanticWorkState(work)}`);
   return work;
 }
 
 function continuationSchedule(schedule: RepositorySchedule): RepositorySchedule {
-  if (!['external_controller_wake', 'browser_probe'].includes(schedule.action.operation)) {
+  if (!isWorkContinuationOperation(schedule.action.operation) && schedule.action.operation !== 'browser_probe') {
     throw new Error(`SCHEDULE_NOT_WORK_CONTINUATION: ${schedule.scheduleId}`);
   }
   return schedule;
@@ -116,6 +126,9 @@ function providerSeedArguments(input: WorkContinuationScheduleInput, controllerT
   return {
     ...(workId ? { work_id: workId } : {}),
     controller_type: controllerType,
+    ...(input.authorizationGrantRefs?.length
+      ? { authorization_grant_refs: [...new Set(input.authorizationGrantRefs.map(String).map(value => value.trim()).filter(Boolean))] }
+      : {}),
     ...(input.executable?.trim() ? { executable: input.executable.trim() } : {}),
     ...(input.launchArgs ? { launch_args: input.launchArgs.map(String) } : {}),
     ...(input.launchReservationMs !== undefined ? { launch_reservation_ms: input.launchReservationMs } : {}),
@@ -188,7 +201,7 @@ export function createWorkContinuationSchedule(
   }
   if (!requestedWorkId && scheduleMode === 'browser_keepalive' && controllerType !== 'chatgpt') throw new Error('STANDALONE_BROWSER_KEEPALIVE_CHATGPT_REQUIRED');
   const trigger = normalizedTrigger(input);
-  const operation = scheduleMode === 'continuation' ? 'external_controller_wake' : 'browser_probe';
+  const operation = scheduleMode === 'continuation' ? CONTROLLER_PROGRESSION_OPERATION : 'browser_probe';
   const name = input.scheduleName?.trim()
     || (scheduleMode === 'browser_watch' ? `Watch external state for Work ${work!.workId}`
       : scheduleMode === 'browser_keepalive'
@@ -234,7 +247,7 @@ export function createWorkContinuationSchedule(
   // Work may legitimately observe several independent external targets.
   if (scheduleMode === 'continuation') {
     const existing = listSchedules(controllerHome, repoId)
-      .filter((candidate) => candidate.action.operation === 'external_controller_wake')
+      .filter((candidate) => isWorkContinuationOperation(candidate.action.operation))
       .filter((candidate) => candidate.action.arguments?.work_id === work!.workId);
     const authoritative = [...existing].reverse().find((candidate) => candidate.enabled) ?? existing.at(-1);
     if (authoritative) {
@@ -296,7 +309,7 @@ export function listWorkContinuationSchedules(
   options: WorkContinuationScheduleListOptions = {},
 ): { schedules: RepositorySchedule[]; occurrences?: ScheduleOccurrence[] } {
   const schedules = listSchedules(controllerHome, repoId)
-    .filter((entry) => ['external_controller_wake', 'browser_probe'].includes(entry.action.operation))
+    .filter((entry) => isWorkContinuationOperation(entry.action.operation) || entry.action.operation === 'browser_probe')
     .filter((entry) => !options.workId || entry.action.arguments?.work_id === options.workId);
   if (!options.includeOccurrences) return { schedules };
   const scheduleIds = new Set(schedules.map((entry) => entry.scheduleId));
@@ -336,6 +349,44 @@ export function resumeWorkContinuationSchedule(controllerHome: string, repoId: s
   const schedule = continuationSchedule(getSchedule(controllerHome, repoId, scheduleId));
   const workId = typeof schedule.action.arguments?.work_id === 'string' ? schedule.action.arguments.work_id : '';
   activeWork(controllerHome, repoId, workId);
+  if (schedule.action.operation === LEGACY_EXTERNAL_CONTROLLER_WAKE_OPERATION) {
+    const trigger = schedule.trigger;
+    const migrated = createWorkContinuationSchedule(controllerHome, repoId, {
+      workId,
+      scheduleName: schedule.name,
+      controllerType: typeof schedule.action.arguments?.controller_type === 'string'
+        ? schedule.action.arguments.controller_type as ContinuationControllerType
+        : undefined,
+      continuationPrompt: typeof schedule.action.arguments?.continuation_hint === 'string'
+        ? schedule.action.arguments.continuation_hint
+        : typeof schedule.action.arguments?.continuation_prompt === 'string'
+          ? schedule.action.arguments.continuation_prompt
+          : undefined,
+      triggerType: trigger.type,
+      everyMinutes: trigger.everyMinutes,
+      cronExpression: trigger.cronExpression,
+      timezone: trigger.timezone,
+      catchUpMinutes: trigger.catchUpMinutes,
+      calendarAt: trigger.calendarAt,
+      condition: trigger.condition,
+      eventName: trigger.eventName,
+      dependencyJobIds: trigger.dependencyJobIds,
+      maxFailures: schedule.policy.maxFailures,
+      cooldownMinutes: schedule.policy.cooldownMinutes,
+      dailyBudgetMinutes: schedule.policy.dailyBudgetMinutes,
+      shadowMode: schedule.policy.shadowMode,
+      backoffBaseMinutes: schedule.policy.backoffBaseMinutes,
+      backoffMaxMinutes: schedule.policy.backoffMaxMinutes,
+      stopConditions: schedule.stopConditions,
+    }).schedule;
+    return saveSchedule(controllerHome, {
+      ...migrated,
+      enabled: true,
+      pausedReason: undefined,
+      consecutiveFailures: 0,
+      nextEligibleAt: undefined,
+    });
+  }
   return saveSchedule(controllerHome, {
     ...schedule,
     enabled: true,
@@ -372,7 +423,7 @@ export async function triggerWorkContinuationRepositoryEvent(
 ): Promise<Array<{ scheduleId: string; occurrenceId?: string; status?: string }>> {
   const schedules = listWorkContinuationSchedules(controllerHome, repoId, { workId: input.workId }).schedules
     .filter((schedule) => schedule.enabled)
-    .filter((schedule) => schedule.action.operation === 'external_controller_wake')
+    .filter((schedule) => isWorkContinuationOperation(schedule.action.operation))
     .filter((schedule) => schedule.trigger.type === 'repository-event' && schedule.trigger.eventName === eventName);
   const triggered: Array<{ scheduleId: string; occurrenceId?: string; status?: string }> = [];
   for (const schedule of schedules) {
@@ -398,7 +449,7 @@ export function eventDrivenContinuationSchedule(
 ): RepositorySchedule {
   const workSchedules = listWorkContinuationSchedules(controllerHome, repoId, { workId: input.workId }).schedules;
   const existing = workSchedules
-    .filter((schedule) => schedule.action.operation === 'external_controller_wake')
+    .filter((schedule) => isWorkContinuationOperation(schedule.action.operation))
     .reverse()
     .find((schedule) => schedule.enabled)
     ?? workSchedules.at(-1);
@@ -456,14 +507,47 @@ export async function resolveHandoffAndTriggerContinuation(
   input: { decision: string; resolver: string },
 ): Promise<{ item: HandoffItem; continuationOccurrences: Array<{ scheduleId: string; occurrenceId?: string; status?: string }> }> {
   const item = resolveHandoffItem({ controllerHome, repoId }, handoffId, input);
+  const continuationOccurrences = await triggerResolvedHandoffContinuation(controllerHome, repoId, item);
+  return { item, continuationOccurrences };
+}
+
+/**
+ * The Inbox application resolves persistence before it calls its continuation
+ * port. Keep the post-resolution transition here so every transport re-arms
+ * the exact ControllerRound before it can wake its Work schedule.
+ */
+export async function triggerResolvedHandoffContinuation(
+  controllerHome: string,
+  repoId: string,
+  item: HandoffItem,
+): Promise<Array<{ scheduleId: string; occurrenceId?: string; status?: string }>> {
+  const relay = item.workId ? getControllerRoundRelay({ controllerHome, repoId }, item.workId) : undefined;
+  const rearmedRelay = item.workId && relay?.status === 'waiting_for_user' && relay.blockedReason === 'provider_user_action_required' && relay.handoffId === item.id
+    ? rearmControllerRoundAfterProviderUserAction({ controllerHome, repoId }, { workId: item.workId, handoffId: item.id })
+    : undefined;
+  if (rearmedRelay) {
+    // The ControllerRound itself is the continuation authority. A repository-event
+    // Schedule is optional policy, not the wake mechanism for an already rearmed
+    // provider dispatch. Wake the canonical Scheduler immediately so a resolved
+    // provider blocker resumes the same occurrence even when no Schedule exists.
+    touchSchedulerWakeSignal(controllerHome, `provider-user-action-resolved:${item.workId}`);
+  }
   const continuationOccurrences = item.workId
     ? await triggerWorkContinuationRepositoryEvent(
         controllerHome,
         repoId,
         handoffResolvedContinuationEventName(item.id),
         `handoff:${item.id}:${item.updatedAt}`,
-        { workId: item.workId, data: { handoffId: item.id, status: item.status, decision: item.decision } },
+        {
+          workId: item.workId,
+          data: {
+            handoffId: item.id,
+            status: item.status,
+            decision: item.decision,
+            ...(rearmedRelay?.occurrenceId ? { controllerRoundOccurrenceId: rearmedRelay.occurrenceId } : {}),
+          },
+        },
       )
     : [];
-  return { item, continuationOccurrences };
+  return continuationOccurrences;
 }

package/src/runtime/workflows/runtime.ts

@@ -1,6 +1,5 @@
 import { withControllerLock, withControllerLockAsync } from '../../cli/repositories/locks';
-import { getWorkContract, isTerminalWorkContractStatus } from '../../../packages/kernel/work/api/index';
-import { getControllerSession, getControllerRoundRelay, controllerSessionAuthorityMatches } from '../../../packages/kernel/controller/api/index';
+import { getWorkContract, semanticWorkState } from '../../../packages/kernel/work/api/index';
 import { readRequirement } from '../control-plane/persistence/requirement-store';
 import { createHash } from 'crypto';
 import type { RepositoryRecord } from '../../cli/repositories/types';
@@ -56,7 +55,8 @@ export interface ExecuteRegisteredWorkflowInput {
   repository: RepositoryRecord;
   executionIdentity: ResolvedExecutionIdentity;
   workId: string;
-  controller: { controllerId: string; authorityId: string };
+  /** Legacy provenance only. Workflow execution authority comes from typed Work/target/effect identities, not Controller ownership. */
+  controller?: { controllerId: string; authorityId: string };
   runId: string;
   registryScope: WorkflowRegistryScope;
   workflowId: string;
@@ -64,20 +64,16 @@ export interface ExecuteRegisteredWorkflowInput {
   timeoutMs?: number;
 }
 
-function assertWorkflowController(input: ExecuteRegisteredWorkflowInput, reconciliation = false): void {
+function assertWorkflowExecutionScope(input: ExecuteRegisteredWorkflowInput, reconciliation = false): void {
   const store = { controllerHome: input.controllerHome, repoId: input.repository.repoId };
   const work = getWorkContract(store, input.workId);
-  if (!work || isTerminalWorkContractStatus(work.status) || work.supersededBy
-    || (!reconciliation && !['open', 'running'].includes(work.status))) throw new Error('WORKFLOW_WORK_NOT_EXECUTABLE');
+  if (!work || work.supersededBy || (!reconciliation && semanticWorkState(work) !== 'open')) {
+    throw new Error('WORKFLOW_WORK_NOT_EXECUTABLE');
+  }
   if (work.repoId !== input.executionIdentity.repositoryId || work.checkoutId !== input.executionIdentity.checkoutId
     || input.executionIdentity.workId !== work.workId) throw new Error('WORKFLOW_EXECUTION_IDENTITY_MISMATCH');
   if (input.registryScope.kind === 'project' && (work.scopeRef?.kind !== 'project' || work.scopeRef.id !== input.registryScope.projectId)
     && work.engineeringContext?.projectContractReceipt?.projectId !== input.registryScope.projectId) throw new Error('WORKFLOW_PROJECT_MISMATCH');
-  const owner = getControllerSession(store, input.workId);
-  if (!input.controller || !owner || owner.controllerId !== input.controller.controllerId) throw new Error('WORKFLOW_CONTROLLER_NOT_OWNER');
-  const relay = getControllerRoundRelay(store, input.workId);
-  if (relay ? relay.status !== 'claimed' || relay.authorityId !== input.controller.authorityId || relay.claimGeneration !== owner.claimGeneration
-    : !controllerSessionAuthorityMatches(owner, input.controller.authorityId)) throw new Error('WORKFLOW_CONTROLLER_AUTHORITY_STALE');
   if (!reconciliation && work.requirementId) {
     const requirement = readRequirement({ controllerHome: input.controllerHome }, work.requirementId)?.value;
     if (!requirement || !['planned', 'active'].includes(requirement.state)) throw new Error('WORKFLOW_REQUIREMENT_NOT_ACTIVE');
@@ -152,7 +148,7 @@ async function completedCommandResult(
 
 /** Hold the existing Work resource lock across read, dispatch and checkpoint, including distinct run IDs. */
 export async function executeRegisteredWorkflow(input: ExecuteRegisteredWorkflowInput, dependencies: WorkflowRuntimeExecutionDependencies = {}): Promise<WorkflowRunResult> {
-  assertWorkflowController(input);
+  assertWorkflowExecutionScope(input);
   return withControllerLockAsync(input.controllerHome, { scope: 'task', repoId: input.repository.repoId, taskId: `workflow:${input.workId}` },
     `workflow:${input.runId}`, () => executeRegisteredWorkflowLocked(input, dependencies), undefined, 0);
 }
@@ -163,7 +159,7 @@ async function executeRegisteredWorkflowLocked(
 ): Promise<WorkflowRunResult> {
   if (!input.workId.trim()) throw new Error('WORKFLOW_RUNTIME_WORK_ID_REQUIRED');
   if (!input.runId.trim()) throw new Error('WORKFLOW_RUNTIME_RUN_ID_REQUIRED');
-  assertWorkflowController(input);
+  assertWorkflowExecutionScope(input);
   const registry = readWorkflowRegistryEntry(input.controllerHome, input.registryScope, input.workflowId);
   if (!registry) throw new Error(`WORKFLOW_REGISTRY_ENTRY_REQUIRED: ${input.workflowId}`);
   if (registry.value.status !== 'active') throw new Error(`WORKFLOW_REGISTRY_ENTRY_NOT_ACTIVE: ${input.workflowId}`);
@@ -242,7 +238,7 @@ async function executeRegisteredWorkflowLocked(
       if (JSON.stringify(canonicalOutput) !== JSON.stringify(output)) throw new Error(`WORKFLOW_RETAINED_OUTPUT_MISMATCH: ${step.stepId}`);
     },
     executeCapability: async ({ step, arguments: args }) => {
-      assertWorkflowController(input);
+      assertWorkflowExecutionScope(input);
       const binding = capabilityBinding(registry.value.bindings, step.capabilityId);
       try {
         const submitted = await submitPluginAction(input.controllerHome, input.repository, {
@@ -266,7 +262,7 @@ async function executeRegisteredWorkflowLocked(
       }
     },
     executeScript: async ({ step, script, arguments: args }) => {
-      assertWorkflowController(input);
+      assertWorkflowExecutionScope(input);
       try {
         const process = await executeCommand({
           controllerHome: input.controllerHome,
@@ -320,7 +316,7 @@ export async function reconcileRegisteredWorkflow(
   input: ExecuteRegisteredWorkflowInput & { reconciliationRequestId?: string },
   dependencies: WorkflowRuntimeExecutionDependencies = {},
 ): Promise<WorkflowRunRecord> {
-  assertWorkflowController(input, true);
+  assertWorkflowExecutionScope(input, true);
   return withControllerLockAsync(
     input.controllerHome,
     { scope: 'task', repoId: input.repository.repoId, taskId: `workflow:${input.workId}` },
@@ -335,7 +331,7 @@ async function reconcileRegisteredWorkflowLocked(
   input: ExecuteRegisteredWorkflowInput & { reconciliationRequestId?: string },
   dependencies: WorkflowRuntimeExecutionDependencies = {},
 ): Promise<WorkflowRunRecord> {
-  assertWorkflowController(input, true);
+  assertWorkflowExecutionScope(input, true);
   const stored = readWorkflowRun(input.controllerHome, input.workId, input.runId);
   if (!stored || !(stored.value.inFlightStepId || stored.value.status === 'reconcile_required')) throw new Error('WORKFLOW_RECONCILIATION_NOT_REQUIRED');
   const registry = readWorkflowRegistryEntry(input.controllerHome, input.registryScope, input.workflowId);
@@ -447,13 +443,13 @@ export async function observeAndReconcileRegisteredWorkflow(
   dependencies: WorkflowRuntimeExecutionDependencies = {},
 ): Promise<WorkflowRunRecord> {
   if (!input.reconciliationRequestId.trim()) throw new Error('WORKFLOW_RECONCILIATION_REQUEST_ID_REQUIRED');
-  assertWorkflowController(input, true);
+  assertWorkflowExecutionScope(input, true);
   return withControllerLockAsync(
     input.controllerHome,
     { scope: 'task', repoId: input.repository.repoId, taskId: `workflow:${input.workId}` },
     `workflow-reconcile-observe:${input.runId}`,
     async () => {
-      assertWorkflowController(input, true);
+      assertWorkflowExecutionScope(input, true);
       const stored = readWorkflowRun(input.controllerHome, input.workId, input.runId);
       if (!stored || !(stored.value.inFlightStepId || stored.value.status === 'reconcile_required')) throw new Error('WORKFLOW_RECONCILIATION_NOT_REQUIRED');
       const registry = readWorkflowRegistryEntry(input.controllerHome, input.registryScope, input.workflowId);

package/src/testing/test-governance.ts

@@ -324,7 +324,11 @@ export function selectTests(
     files: selected,
     reason: explicitTestFiles.length > 0
       ? 'explicit test files'
-      : noChanges ? 'no changes detected; core smoke only' : `changed paths mapped to ${[...changedModules].sort().join(', ')}`,
+      : gate === 'full' ? 'full non-destructive suite'
+      : gate === 'infrastructure' ? 'infrastructure suite'
+      : gate === 'fault' ? 'fault-injection suite'
+      : noChanges ? 'no changes detected; core smoke only'
+      : `changed paths mapped to ${[...changedModules].sort().join(', ')}`,
   };
 }
 

package/supervisor/chatgpt-conversation.ts

@@ -0,0 +1,23 @@
+import { parseCanonicalChatgptConversationIdentity } from '../packages/plugin-runtime/computer';
+
+export interface ChatgptConversationIdentity {
+  conversationId: string;
+  canonicalUrl: string;
+}
+
+export function parseChatgptConversationIdentity(value: string): ChatgptConversationIdentity {
+  try {
+    const identity = parseCanonicalChatgptConversationIdentity(value);
+    let decodedConversationId = identity.conversationId;
+    try { decodedConversationId = decodeURIComponent(identity.conversationId); } catch { /* keep raw identity for validation below */ }
+    if (decodedConversationId.startsWith('local-chatgpt:')) {
+      throw new Error('CHATGPT_CONVERSATION_ID_INVALID');
+    }
+    return { conversationId: identity.conversationId, canonicalUrl: identity.conversationUrl };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message === 'CHATGPT_CONVERSATION_URL_INVALID') throw new Error('WORKFLOW_SUPERVISOR_CHATGPT_URL_INVALID');
+    if (message === 'CHATGPT_CONVERSATION_ID_MISSING') throw new Error('WORKFLOW_SUPERVISOR_CHATGPT_CONVERSATION_URL_REQUIRED');
+    throw new Error('WORKFLOW_SUPERVISOR_CHATGPT_CONVERSATION_ID_INVALID');
+  }
+}

package/supervisor/client.ts

@@ -0,0 +1,218 @@
+import { randomUUID } from 'node:crypto';
+import { createConnection } from 'node:net';
+import { workflowSupervisorSocketPath } from './paths';
+import type { WorkflowSupervisorConsumerStatus, WorkflowSupervisorContinuationProof, WorkflowSupervisorDiscoveredConversation, WorkflowSupervisorEffect, WorkflowSupervisorTask, WorkflowSupervisorTaskInput, WorkflowSupervisorTaskStall, WorkflowSupervisorTerminalState } from './types';
+
+interface RpcResponse<T> { id: string; ok: boolean; result?: T; error?: { code?: string; message?: string } }
+
+// The Supervisor daemon is single-threaded and shares its event loop with the
+// canonical Runtime's own scheduler/maintenance passes. A short read budget is
+// enough for cheap lookups, but a mutating call must not be reported as failed
+// merely because the Runtime was busy for a moment: `task_register` and the
+// reservation calls are idempotent upserts, and treating ordinary contention as
+// failure stranded ControllerRounds in `dispatching`
+// (live evidence: `WORKFLOW_SUPERVISOR_RPC_TIMEOUT:task_register` in the Runtime
+// stderr while the daemon was healthy). Keep both budgets bounded.
+const SUPERVISOR_RPC_READ_TIMEOUT_MS = 2_000;
+const SUPERVISOR_RPC_MUTATION_TIMEOUT_MS = 15_000;
+
+async function rpc<T>(forgeHome: string, method: string, params: Record<string, unknown>, timeoutMs = SUPERVISOR_RPC_READ_TIMEOUT_MS): Promise<T> {
+  const socketPath = workflowSupervisorSocketPath(forgeHome);
+  return await new Promise<T>((resolve, reject) => {
+    const socket = createConnection(socketPath);
+    const id = `forge-${randomUUID()}`;
+    let buffer = '';
+    let settled = false;
+    const finish = (error?: Error, value?: T): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket.destroy();
+      if (error) reject(error); else resolve(value as T);
+    };
+    const timer = setTimeout(() => finish(new Error(`WORKFLOW_SUPERVISOR_RPC_TIMEOUT:${method}`)), timeoutMs);
+    socket.once('error', (error) => finish(error instanceof Error ? error : new Error(String(error))));
+    socket.on('data', (chunk) => {
+      buffer += chunk.toString('utf8');
+      const newline = buffer.indexOf('\n');
+      if (newline < 0) return;
+      let response: RpcResponse<T>;
+      try { response = JSON.parse(buffer.slice(0, newline)) as RpcResponse<T>; }
+      catch { finish(new Error('WORKFLOW_SUPERVISOR_RPC_RESPONSE_INVALID')); return; }
+      if (response.id !== id) { finish(new Error('WORKFLOW_SUPERVISOR_RPC_RESPONSE_ID_MISMATCH')); return; }
+      if (!response.ok) { finish(new Error(response.error?.message ?? response.error?.code ?? 'WORKFLOW_SUPERVISOR_RPC_FAILED')); return; }
+      finish(undefined, response.result as T);
+    });
+    socket.once('connect', () => socket.write(`${JSON.stringify({ id, method, params })}\n`));
+  });
+}
+
+export async function getWorkflowSupervisorConsumerStatus(forgeHome: string): Promise<WorkflowSupervisorConsumerStatus> {
+  return await rpc<WorkflowSupervisorConsumerStatus>(forgeHome, 'consumer_status', {});
+}
+
+export async function getWorkflowSupervisorCurrentConversation(forgeHome: string): Promise<WorkflowSupervisorDiscoveredConversation | undefined> {
+  const result = await rpc<{ conversation?: WorkflowSupervisorDiscoveredConversation }>(forgeHome, 'browser_current_conversation', {});
+  return result.conversation;
+}
+
+export async function getWorkflowSupervisorTask(forgeHome: string, taskId: string): Promise<WorkflowSupervisorTask | undefined> {
+  const task = await rpc<WorkflowSupervisorTask | null>(forgeHome, 'task_get', { task_id: taskId });
+  return task ?? undefined;
+}
+
+export async function reviseWorkflowSupervisorTaskObjective(forgeHome: string, input: {
+  taskId: string; objective: string; expectedObjectiveSha256: string; requestId: string; authorizedBy?: string;
+  workId?: string; requirementId?: string; expectedCompletionContractSha256?: string;
+}): Promise<{ task: WorkflowSupervisorTask; changed: boolean; deduplicated: boolean; objectiveSha256: string; completionContractSha256: string; semanticBindingChanged: boolean; refreshedEffect?: WorkflowSupervisorEffect }> {
+  return await rpc(forgeHome, 'task_revise_objective', {
+    task_id: input.taskId,
+    objective: input.objective,
+    expected_objective_sha256: input.expectedObjectiveSha256,
+    request_id: input.requestId,
+    ...(input.workId?.trim() ? { work_id: input.workId.trim() } : {}),
+    ...(input.requirementId?.trim() ? { requirement_id: input.requirementId.trim() } : {}),
+    ...(input.expectedCompletionContractSha256?.trim() ? { expected_completion_contract_sha256: input.expectedCompletionContractSha256.trim() } : {}),
+    ...(input.authorizedBy?.trim() ? { authorized_by: input.authorizedBy.trim() } : {}),
+  }, SUPERVISOR_RPC_MUTATION_TIMEOUT_MS);
+}
+
+export async function getWorkflowSupervisorTaskByConversationId(
+  forgeHome: string,
+  conversationId: string,
+): Promise<{ task: WorkflowSupervisorTask; terminal?: WorkflowSupervisorTerminalState } | undefined> {
+  const result = await rpc<{ task: WorkflowSupervisorTask; terminal?: WorkflowSupervisorTerminalState } | null>(
+    forgeHome,
+    'task_get_by_conversation',
+    { conversation_id: conversationId },
+  );
+  return result ?? undefined;
+}
+
+export async function listWorkflowSupervisorTasks(forgeHome: string, activeOnly = false): Promise<WorkflowSupervisorTask[]> {
+  const result = await rpc<{ tasks: WorkflowSupervisorTask[] }>(forgeHome, 'task_list', { active_only: activeOnly });
+  return result.tasks;
+}
+/** Explicit read-only terminal history. Native ChatGPT archive is not inferred. */
+export async function listWorkflowSupervisorTerminalTasks(forgeHome: string): Promise<Array<{ task: WorkflowSupervisorTask; terminal: WorkflowSupervisorTerminalState }>> {
+  const result = await rpc<{ terminalTasks: Array<{ task: WorkflowSupervisorTask; terminal: WorkflowSupervisorTerminalState }> }>(
+    forgeHome, 'task_list', { terminal_only: true },
+  );
+  return result.terminalTasks;
+}
+/** Operator-only recovery; never exposed to the browser Native Messaging host. */
+export async function recoverWorkflowSupervisorTask(forgeHome: string, input: { taskId: string; sourceEffectId?: string; requestId: string; reason: string; supersedeUnknown?: boolean; authorizedBy?: string }): Promise<{ recoveryEffect: WorkflowSupervisorEffect; action: 'retry_authorized' | 'recovery_reserved' | 'unknown_superseded' }> {
+  return await rpc(forgeHome, 'task_recover', {
+    task_id: input.taskId,
+    ...(input.sourceEffectId?.trim() ? { source_effect_id: input.sourceEffectId.trim() } : {}),
+    request_id: input.requestId,
+    reason: input.reason,
+    ...(input.supersedeUnknown === true ? { supersede_unknown: true } : {}),
+    ...(input.authorizedBy?.trim() ? { authorized_by: input.authorizedBy.trim() } : {}),
+  }, SUPERVISOR_RPC_MUTATION_TIMEOUT_MS);
+}
+
+/** Read-only stall classification; derived from the effect ledger, not new state. */
+export async function getWorkflowSupervisorTaskStall(forgeHome: string, taskId: string): Promise<WorkflowSupervisorTaskStall> {
+  return await rpc<WorkflowSupervisorTaskStall>(forgeHome, 'task_stall', { task_id: taskId });
+}
+
+/** One-way binding of a Work-owned Supervisor task to its canonical Scheduler lane. */
+export async function bindWorkflowSupervisorScheduledWake(forgeHome: string, input: {
+  taskId: string; repoId: string; workId: string; scheduleId: string;
+}): Promise<{ task: WorkflowSupervisorTask; changed: boolean; deduplicated: boolean }> {
+  return await rpc(forgeHome, 'task_bind_scheduled_wake', {
+    task_id: input.taskId, repo_id: input.repoId, work_id: input.workId, schedule_id: input.scheduleId,
+  }, SUPERVISOR_RPC_MUTATION_TIMEOUT_MS);
+}
+
+/** Scheduler occurrence is the idempotency identity; an unknown send outcome is never replayed. */
+export async function wakeWorkflowSupervisorScheduledTask(forgeHome: string, input: {
+  taskId: string; scheduleId: string; occurrenceId: string;
+}): Promise<{ effect: WorkflowSupervisorEffect; deduplicated: boolean }> {
+  return await rpc(forgeHome, 'task_wake_scheduled', {
+    task_id: input.taskId, schedule_id: input.scheduleId, occurrence_id: input.occurrenceId,
+  }, SUPERVISOR_RPC_MUTATION_TIMEOUT_MS);
+}
+
+/**
+ * Operator-only conversation migration for a standalone Supervisor task whose
+ * exact conversation became permanently unusable. It is explicit and bounded by
+ * design: it is never triggered automatically by provider backpressure.
+ */
+export async function migrateWorkflowSupervisorConversation(forgeHome: string, input: {
+  taskId: string; expectedConversationId: string; requestId: string; reason: string; authorizedBy?: string;
+} & ({ conversationId: string; conversationUrl: string; fresh?: false } | { fresh: true; conversationId?: never; conversationUrl?: never })
+): Promise<{ taskId: string; conversationId: string; conversationUrl: string; migrated: boolean; freshConversation?: boolean }> {
+  return await rpc(forgeHome, 'task_migrate_conversation', {
+    task_id: input.taskId,
+    expected_conversation_id: input.expectedConversationId,
+    ...(input.fresh === true ? { fresh: true } : { conversation_id: input.conversationId, conversation_url: input.conversationUrl }),
+    request_id: input.requestId,
+    reason: input.reason,
+    ...(input.authorizedBy?.trim() ? { authorized_by: input.authorizedBy.trim() } : {}),
+  }, SUPERVISOR_RPC_MUTATION_TIMEOUT_MS);
+}
+
+export async function stopWorkflowSupervisorTask(
+  forgeHome: string,
+  taskId: string,
+  reason = 'Stopped by operator request.',
+): Promise<{ taskId: string; terminal: 'STOPPED'; deduplicated: boolean }> {
+  return await rpc(forgeHome, 'task_stop', { task_id: taskId, reason }, SUPERVISOR_RPC_MUTATION_TIMEOUT_MS);
+}
+
+export async function registerWorkflowSupervisorTask(forgeHome: string, input: WorkflowSupervisorTaskInput): Promise<WorkflowSupervisorTask> {
+  return await rpc<WorkflowSupervisorTask>(forgeHome, 'task_register', {
+    task_id: input.taskId,
+    conversation_id: input.conversationId,
+    conversation_url: input.conversationUrl,
+    objective: input.objective,
+    completion_contract: input.completionContract,
+    continuation_policy: input.continuationPolicy,
+    user_blocker_policy: input.userBlockerPolicy,
+  }, SUPERVISOR_RPC_MUTATION_TIMEOUT_MS);
+}
+
+export async function bindWorkflowSupervisorBootstrapConversation(
+  forgeHome: string,
+  input: { taskId: string; conversationId: string; conversationUrl: string },
+): Promise<WorkflowSupervisorTask> {
+  return await rpc<WorkflowSupervisorTask>(forgeHome, 'bootstrap_bind_conversation', {
+    task_id: input.taskId,
+    conversation_id: input.conversationId,
+    conversation_url: input.conversationUrl,
+  }, SUPERVISOR_RPC_MUTATION_TIMEOUT_MS);
+}
+
+export async function reserveWorkflowSupervisorEnrollment(forgeHome: string, taskId: string, canonicalEffectId?: string): Promise<WorkflowSupervisorEffect> {
+  return await rpc<WorkflowSupervisorEffect>(forgeHome, 'reserve_enrollment', {
+    task_id: taskId,
+    ...(canonicalEffectId?.trim() ? { effect_id: canonicalEffectId.trim() } : {}),
+  }, SUPERVISOR_RPC_MUTATION_TIMEOUT_MS);
+}
+
+export interface WorkflowSupervisorEffectDispatchBudget {
+  effectId: string;
+  generations: number;
+  maxGenerations: number;
+  lastDispatchedAtMs?: number;
+  retryDelayMs?: number;
+  exhausted: boolean;
+}
+
+export async function getWorkflowSupervisorEffectDispatchBudget(
+  forgeHome: string,
+  effectId: string,
+): Promise<WorkflowSupervisorEffectDispatchBudget> {
+  return await rpc<WorkflowSupervisorEffectDispatchBudget>(forgeHome, 'effect_dispatch_budget', { effect_id: effectId });
+}
+
+export async function getWorkflowSupervisorContinuationProof(forgeHome: string, input: { repoId?: string; activeReleaseId: string; notBefore: string }): Promise<WorkflowSupervisorContinuationProof | undefined> {
+  const proof = await rpc<WorkflowSupervisorContinuationProof | null>(forgeHome, 'continuation_proof', {
+    ...(input.repoId?.trim() ? { repo_id: input.repoId.trim() } : {}),
+    active_release_id: input.activeReleaseId,
+    not_before: input.notBefore,
+  });
+  return proof ?? undefined;
+}