@moretea-labs/forge 1.8.0 → 1.8.2

package/supervisor/server.ts

@@ -0,0 +1,412 @@
+import { chmodSync, existsSync, lstatSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { createConnection, createServer, type Server, type Socket } from 'node:net';
+import { dirname } from 'node:path';
+import { mkdirSync } from 'node:fs';
+import type { WorkflowSupervisorControlPlane } from './control-plane';
+import { parseChatgptConversationIdentity } from './chatgpt-conversation';
+import type { WorkflowSupervisorConsumerStatus, WorkflowSupervisorDiscoverySnapshot, WorkflowSupervisorDiscoveredConversation } from './types';
+import type { ComputerChatgptExtensionBrokerRpc, ComputerChatgptExtensionCommandResult, ComputerChatgptExtensionHeartbeat } from '../packages/plugin-runtime/computer';
+import { chatgptProviderPageFailure } from '../adapters/chatgpt/provider-delivery';
+
+interface RpcRequest { id: string; method: string; params: Record<string, unknown> }
+const MAX_REQUEST_BYTES = 1024 * 1024;
+const MAX_DISCOVERED_CONVERSATIONS = 512;
+const MAX_DISCOVERY_TITLE_CHARS = 512;
+
+/** Ephemeral socket binding to the Canonical Runtime's durable incarnation. */
+export interface WorkflowSupervisorWriterIdentity {
+  runtimeInstanceId: string;
+  fencingGeneration: number;
+  pid: number;
+}
+
+export interface WorkflowSupervisorSocketOwner extends WorkflowSupervisorWriterIdentity {
+  schemaVersion: 1;
+  recordedAt: string;
+}
+
+export function workflowSupervisorSocketOwnerPath(socketPath: string): string {
+  return `${socketPath}.owner.json`;
+}
+
+function writeSocketOwner(socketPath: string, identity: WorkflowSupervisorWriterIdentity): void {
+  const path = workflowSupervisorSocketOwnerPath(socketPath);
+  const temporary = `${path}.${process.pid}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify({ schemaVersion: 1, ...identity, recordedAt: new Date().toISOString() } satisfies WorkflowSupervisorSocketOwner)}\n`, { encoding: 'utf8', mode: 0o600 });
+  renameSync(temporary, path);
+}
+
+export function readWorkflowSupervisorSocketOwner(socketPath: string): WorkflowSupervisorSocketOwner | undefined {
+  const path = workflowSupervisorSocketOwnerPath(socketPath);
+  if (!existsSync(path)) return undefined;
+  try {
+    const value = JSON.parse(readFileSync(path, 'utf8')) as WorkflowSupervisorSocketOwner;
+    if (value.schemaVersion !== 1 || !value.runtimeInstanceId || !Number.isInteger(value.fencingGeneration) || value.fencingGeneration < 1 || !Number.isInteger(value.pid) || value.pid < 1) return undefined;
+    return value;
+  } catch { return undefined; }
+}
+
+function sameWriterIdentity(left: WorkflowSupervisorWriterIdentity, right: WorkflowSupervisorWriterIdentity): boolean {
+  return left.runtimeInstanceId === right.runtimeInstanceId
+    && left.fencingGeneration === right.fencingGeneration
+    && left.pid === right.pid;
+}
+
+function writerProcessStillAlive(writer: WorkflowSupervisorWriterIdentity): boolean {
+  try {
+    process.kill(writer.pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code !== 'ESRCH';
+  }
+}
+
+async function socketAcceptsConnections(socketPath: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = createConnection(socketPath);
+    socket.once('connect', () => { socket.destroy(); resolve(true); });
+    socket.once('error', () => { socket.destroy(); resolve(false); });
+  });
+}
+
+
+export interface WorkflowSupervisorSocketInspection {
+  exists: boolean;
+  isSocket: boolean;
+  acceptsConnections: boolean;
+  owner?: WorkflowSupervisorSocketOwner;
+}
+
+export async function inspectWorkflowSupervisorSocket(socketPath: string): Promise<WorkflowSupervisorSocketInspection> {
+  if (!existsSync(socketPath)) {
+    return { exists: false, isSocket: false, acceptsConnections: false };
+  }
+  let isSocket = false;
+  try { isSocket = lstatSync(socketPath).isSocket(); } catch { /* raced with cleanup */ }
+  if (!isSocket) {
+    return {
+      exists: existsSync(socketPath),
+      isSocket: false,
+      acceptsConnections: false,
+      owner: readWorkflowSupervisorSocketOwner(socketPath),
+    };
+  }
+  return {
+    exists: true,
+    isSocket: true,
+    acceptsConnections: await socketAcceptsConnections(socketPath),
+    owner: readWorkflowSupervisorSocketOwner(socketPath),
+  };
+}
+
+/**
+ * Recovery uses this only after the Runtime service and Runtime ownership have
+ * been proven stopped. It never removes a live socket. The owner sidecar is
+ * forensic evidence, not independent lifecycle authority.
+ */
+export async function reconcileStoppedWorkflowSupervisorSocket(socketPath: string): Promise<{
+  ok: boolean;
+  changed: boolean;
+  detail: string;
+  inspection: WorkflowSupervisorSocketInspection;
+}> {
+  const inspection = await inspectWorkflowSupervisorSocket(socketPath);
+  if (!inspection.exists) {
+    return { ok: true, changed: false, detail: 'Workflow Supervisor socket is already quiescent', inspection };
+  }
+  if (!inspection.isSocket) {
+    return { ok: false, changed: false, detail: 'WORKFLOW_SUPERVISOR_SOCKET_PATH_OCCUPIED', inspection };
+  }
+  if (inspection.acceptsConnections) {
+    return { ok: false, changed: false, detail: 'WORKFLOW_SUPERVISOR_WRITER_STILL_LIVE', inspection };
+  }
+  try { unlinkSync(socketPath); } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+  }
+  try { unlinkSync(workflowSupervisorSocketOwnerPath(socketPath)); } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+  }
+  return { ok: true, changed: true, detail: 'stale Workflow Supervisor socket authority was reconciled after Runtime shutdown', inspection };
+}
+
+/**
+ * A stale socket is removable only after it rejects a connection and its
+ * recorded writer is not the incoming incarnation. A live socket remains a
+ * hard conflict; this is fencing/reconciliation, not a retry special case.
+ */
+export async function reconcileWorkflowSupervisorSocket(input: {
+  socketPath: string;
+  incoming: WorkflowSupervisorWriterIdentity;
+}): Promise<void> {
+  if (!existsSync(input.socketPath)) return;
+  if (!lstatSync(input.socketPath).isSocket()) throw new Error('WORKFLOW_SUPERVISOR_SOCKET_PATH_OCCUPIED');
+  if (await socketAcceptsConnections(input.socketPath)) throw new Error('WORKFLOW_SUPERVISOR_WRITER_ALREADY_PRESENT');
+  const owner = readWorkflowSupervisorSocketOwner(input.socketPath);
+  if (owner && sameWriterIdentity(owner, input.incoming)) {
+    throw new Error('WORKFLOW_SUPERVISOR_SOCKET_STALE_FOR_CURRENT_INCARNATION');
+  }
+  if (owner && writerProcessStillAlive(owner)) {
+    throw new Error('WORKFLOW_SUPERVISOR_WRITER_PROCESS_STILL_LIVE');
+  }
+  try { unlinkSync(input.socketPath); } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+  }
+  try { unlinkSync(workflowSupervisorSocketOwnerPath(input.socketPath)); } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+  }
+}
+export class WorkflowSupervisorEphemeralDiscovery {
+  private readonly bySource = new Map<string, WorkflowSupervisorDiscoveredConversation[]>();
+  private readonly currentBySource = new Map<string, { conversationId: string; observedAtMs: number }>();
+  update(value: unknown, source = 'browser-extension'): WorkflowSupervisorDiscoverySnapshot {
+    if (!Array.isArray(value) || value.length > MAX_DISCOVERED_CONVERSATIONS) throw new Error('WORKFLOW_SUPERVISOR_DISCOVERY_INVALID');
+    const seen = new Set<string>();
+    const conversations: WorkflowSupervisorDiscoveredConversation[] = [];
+    let currentConversationId: string | undefined;
+    for (const entry of value) {
+      if (!entry || typeof entry !== 'object' || Array.isArray(entry)) throw new Error('WORKFLOW_SUPERVISOR_DISCOVERY_INVALID');
+      const record = entry as Record<string, unknown>;
+      const identity = parseChatgptConversationIdentity(String(record.canonical_url ?? ''));
+      if (String(record.conversation_id ?? '') !== identity.conversationId) throw new Error('WORKFLOW_SUPERVISOR_DISCOVERY_IDENTITY_MISMATCH');
+      if (seen.has(identity.conversationId)) continue;
+      seen.add(identity.conversationId);
+      const rawTitle = typeof record.title === 'string' ? record.title.trim() : '';
+      const rawProjectTitle = typeof record.project_title === 'string' ? record.project_title.trim() : '';
+      const rawProjectUrl = typeof record.project_url === 'string' ? record.project_url.trim() : '';
+      if (record.is_current === true) {
+        if (currentConversationId && currentConversationId !== identity.conversationId) {
+          throw new Error('WORKFLOW_SUPERVISOR_DISCOVERY_CURRENT_AMBIGUOUS');
+        }
+        currentConversationId = identity.conversationId;
+      }
+      let projectUrl: string | undefined;
+      if (rawProjectUrl) {
+        let parsed: URL;
+        try { parsed = new URL(rawProjectUrl); } catch { throw new Error('WORKFLOW_SUPERVISOR_DISCOVERY_PROJECT_URL_INVALID'); }
+        if (parsed.protocol !== 'https:' || parsed.hostname !== 'chatgpt.com') throw new Error('WORKFLOW_SUPERVISOR_DISCOVERY_PROJECT_URL_INVALID');
+        parsed.hash = '';
+        projectUrl = parsed.toString();
+      }
+      conversations.push({
+        conversationId: identity.conversationId,
+        canonicalUrl: identity.canonicalUrl,
+        ...(rawTitle ? { title: rawTitle.slice(0, MAX_DISCOVERY_TITLE_CHARS) } : {}),
+        ...(rawProjectTitle ? { projectTitle: rawProjectTitle.slice(0, MAX_DISCOVERY_TITLE_CHARS) } : {}),
+        ...(projectUrl ? { projectUrl } : {}),
+      });
+    }
+    this.bySource.set(source, conversations);
+    if (currentConversationId) this.currentBySource.set(source, { conversationId: currentConversationId, observedAtMs: Date.now() });
+    else this.currentBySource.delete(source);
+    return this.get();
+  }
+  currentConversation(source?: string, maxAgeMs = 90_000): WorkflowSupervisorDiscoveredConversation | undefined {
+    const now = Date.now();
+    const freshCurrent = (candidateSource: string): { conversationId: string; observedAtMs: number } | undefined => {
+      const current = this.currentBySource.get(candidateSource);
+      return current && now - current.observedAtMs <= maxAgeMs ? current : undefined;
+    };
+    const conversationFor = (candidateSource: string, conversationId: string): WorkflowSupervisorDiscoveredConversation | undefined => {
+      const conversation = (this.bySource.get(candidateSource) ?? []).find(entry => entry.conversationId === conversationId);
+      return conversation ? structuredClone(conversation) : undefined;
+    };
+
+    if (source) {
+      const current = freshCurrent(source);
+      return current ? conversationFor(source, current.conversationId) : undefined;
+    }
+
+    // The extension observes the active ChatGPT tab in the user's ChatGPT browser
+    // surface and refreshes on tab/window activity. Native discovery observes the
+    // system-frontmost browser and can legitimately disagree after the user moves
+    // focus while a provider turn is still running. Treating those two observation
+    // semantics as peer votes made exact current-conversation enrollment disappear.
+    // Prefer a fresh extension observation; native/other sources remain the fallback.
+    const extensionCurrent = freshCurrent('chrome-extension');
+    if (extensionCurrent) {
+      const extensionConversation = conversationFor('chrome-extension', extensionCurrent.conversationId);
+      if (extensionConversation) return extensionConversation;
+    }
+
+    const sources = [...this.currentBySource.keys()].filter(candidateSource => candidateSource !== 'chrome-extension');
+    const currentIds = new Set<string>();
+    for (const candidateSource of sources) {
+      const current = freshCurrent(candidateSource);
+      if (current) currentIds.add(current.conversationId);
+    }
+    if (currentIds.size !== 1) return undefined;
+    const conversationId = [...currentIds][0]!;
+    for (const candidateSource of sources) {
+      if (freshCurrent(candidateSource)?.conversationId !== conversationId) continue;
+      const conversation = conversationFor(candidateSource, conversationId);
+      if (conversation) return conversation;
+    }
+    return undefined;
+  }
+  sourceConversations(source: string): WorkflowSupervisorDiscoveredConversation[] {
+    return structuredClone(this.bySource.get(source) ?? []);
+  }
+  get(): WorkflowSupervisorDiscoverySnapshot {
+    const byConversation = new Map<string, WorkflowSupervisorDiscoveredConversation>();
+    for (const conversations of this.bySource.values()) for (const conversation of conversations) {
+      const current = byConversation.get(conversation.conversationId);
+      if (!current) byConversation.set(conversation.conversationId, conversation);
+      else if (!current.projectTitle && conversation.projectTitle) byConversation.set(conversation.conversationId, { ...current, ...conversation });
+    }
+    return { observedAt: this.bySource.size > 0 ? new Date().toISOString() : '', conversations: [...byConversation.values()] };
+  }
+}
+
+function request(value: unknown): RpcRequest {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('WORKFLOW_SUPERVISOR_RPC_INVALID');
+  const record = value as Record<string, unknown>;
+  if (typeof record.id !== 'string' || !record.id || typeof record.method !== 'string' || !/^[a-z][a-z0-9_]{0,127}$/.test(record.method)) throw new Error('WORKFLOW_SUPERVISOR_RPC_INVALID');
+  return { id: record.id, method: record.method, params: record.params && typeof record.params === 'object' && !Array.isArray(record.params) ? record.params as Record<string, unknown> : {} };
+}
+function text(params: Record<string, unknown>, key: string): string { const value = params[key]; if (typeof value !== 'string' || !value.trim()) throw new Error(`WORKFLOW_SUPERVISOR_RPC_${key.toUpperCase()}_REQUIRED`); return value.trim(); }
+function reply(socket: Socket, id: string, result: unknown): void { socket.write(`${JSON.stringify({ id, ok: true, result })}\n`); }
+function fail(socket: Socket, id: string, error: unknown): void { const message = error instanceof Error ? error.message : String(error); socket.write(`${JSON.stringify({ id, ok: false, error: { code: message.split(':')[0], message } })}\n`); }
+
+export function createWorkflowSupervisorServer(input: { controlPlane: WorkflowSupervisorControlPlane; socketPath: string; discovery?: WorkflowSupervisorEphemeralDiscovery; writer?: WorkflowSupervisorWriterIdentity; browserAdapterEnabled?: boolean; browserConsumerStatus?: () => WorkflowSupervisorConsumerStatus; computerExtensionBroker?: ComputerChatgptExtensionBrokerRpc }): Server {
+  const discovery = input.discovery ?? new WorkflowSupervisorEphemeralDiscovery();
+  const server = createServer((socket) => {
+    let buffer = Buffer.alloc(0); let chain = Promise.resolve();
+    socket.on('data', (chunk: Buffer) => {
+      buffer = Buffer.concat([buffer, chunk]);
+      if (buffer.length > MAX_REQUEST_BYTES) { socket.destroy(new Error('WORKFLOW_SUPERVISOR_RPC_TOO_LARGE')); return; }
+      let newline = buffer.indexOf(0x0a);
+      while (newline >= 0) {
+        const raw = buffer.subarray(0, newline).toString('utf8'); buffer = buffer.subarray(newline + 1);
+        chain = chain.then(async () => {
+          let id = 'invalid';
+          try { const req = request(JSON.parse(raw)); id = req.id; reply(socket, id, await dispatch(input.controlPlane, discovery, req, input.browserAdapterEnabled !== false, input.browserConsumerStatus, input.computerExtensionBroker)); } catch (error) { fail(socket, id, error); }
+        });
+        newline = buffer.indexOf(0x0a);
+      }
+    });
+  });
+  server.once('listening', () => {
+    chmodSync(input.socketPath, 0o600);
+    if (input.writer) writeSocketOwner(input.socketPath, input.writer);
+  });
+  server.once('close', () => {
+    const owner = readWorkflowSupervisorSocketOwner(input.socketPath);
+    if (input.writer && (!owner || !sameWriterIdentity(owner, input.writer))) return;
+    if (existsSync(input.socketPath)) unlinkSync(input.socketPath);
+    const ownerPath = workflowSupervisorSocketOwnerPath(input.socketPath);
+    if (existsSync(ownerPath)) unlinkSync(ownerPath);
+  });
+  mkdirSync(dirname(input.socketPath), { recursive: true, mode: 0o700 });
+  // The socket path is the daemon's local single-writer fence. Never unlink an
+  // existing socket speculatively: it may belong to a live Supervisor writer.
+  // Evidence-based stale-socket recovery belongs to the restart-recovery step.
+  if (existsSync(input.socketPath)) {
+    if (!lstatSync(input.socketPath).isSocket()) throw new Error('WORKFLOW_SUPERVISOR_SOCKET_PATH_OCCUPIED');
+    throw new Error('WORKFLOW_SUPERVISOR_WRITER_ALREADY_PRESENT');
+  }
+  server.listen(input.socketPath);
+  return server;
+}
+
+async function dispatch(control: WorkflowSupervisorControlPlane, discovery: WorkflowSupervisorEphemeralDiscovery, req: RpcRequest, browserAdapterEnabled = true, browserConsumerStatus?: () => WorkflowSupervisorConsumerStatus, computerExtensionBroker?: ComputerChatgptExtensionBrokerRpc): Promise<unknown> {
+  const p = req.params;
+  if (req.method === 'health') return { status: 'ready', writer: 'workflow-supervisor-daemon' };
+  if (req.method === 'computer_extension_heartbeat') {
+    if (!computerExtensionBroker) throw new Error('COMPUTER_CHATGPT_EXTENSION_BROKER_UNAVAILABLE');
+    computerExtensionBroker.heartbeat(p as unknown as ComputerChatgptExtensionHeartbeat);
+    return { recorded: true };
+  }
+  if (req.method === 'computer_extension_claim') {
+    if (!computerExtensionBroker) throw new Error('COMPUTER_CHATGPT_EXTENSION_BROKER_UNAVAILABLE');
+    return { command: computerExtensionBroker.claim(text(p, 'provider_instance_id')) ?? null };
+  }
+  if (req.method === 'computer_extension_complete') {
+    if (!computerExtensionBroker) throw new Error('COMPUTER_CHATGPT_EXTENSION_BROKER_UNAVAILABLE');
+    return { recorded: computerExtensionBroker.complete(text(p, 'provider_instance_id'), text(p, 'command_id'), object(p.result) as unknown as ComputerChatgptExtensionCommandResult) };
+  }
+  if (req.method === 'consumer_status') return browserConsumerStatus?.() ?? {
+    enabled: browserAdapterEnabled,
+    running: false,
+    observedAt: new Date().toISOString(),
+    transportFailureStreak: 0,
+    providerBackpressureMs: 0,
+    stalled: false,
+  } satisfies WorkflowSupervisorConsumerStatus;
+  if (!browserAdapterEnabled && req.method === 'browser_tasks') return { tasks: [] };
+  if (!browserAdapterEnabled && req.method.startsWith('browser_')) throw new Error('WORKFLOW_SUPERVISOR_BROWSER_ADAPTER_DISABLED');
+  if (req.method === 'browser_discovery') return control.browserDiscoverySnapshot();
+  if (req.method === 'browser_current_conversation') return { conversation: discovery.currentConversation() };
+  if (req.method === 'browser_discovery_update') {
+    const source = typeof p.source === 'string' && p.source.trim() ? p.source.trim() : 'chrome-extension';
+    discovery.update(p.conversations, source);
+    return control.recordBrowserDiscovery(source, discovery.sourceConversations(source));
+  }
+  if (req.method === 'browser_project_scopes') return { projects: control.browserProjectScopes() };
+  if (req.method === 'browser_tasks') return { tasks: control.browserTasks() };
+  if (req.method === 'browser_poll') return control.browserPoll({ conversationId: text(p, 'conversation_id'), conversationUrl: text(p, 'conversation_url') });
+  if (req.method === 'bootstrap_poll') return control.bootstrapPoll(text(p, 'task_id'));
+  if (req.method === 'bootstrap_project_url') return { project_url: control.bootstrapProjectUrl(text(p, 'task_id')) };
+  if (req.method === 'bootstrap_begin_effect') return { started: control.bootstrapBeginEffect({ taskId: text(p, 'task_id'), effectId: text(p, 'effect_id'), dispatchId: text(p, 'dispatch_id'), dispatchGeneration: positiveInteger(p, 'dispatch_generation') }) };
+  if (req.method === 'bootstrap_observe_effect') { const outcome = text(p, 'outcome'); if (!['applied','unknown'].includes(outcome)) throw new Error('WORKFLOW_SUPERVISOR_RPC_OUTCOME_INVALID'); control.bootstrapObserveEffect({ taskId: text(p, 'task_id'), effectId: text(p, 'effect_id'), observationId: text(p, 'observation_id'), outcome: outcome as 'applied'|'unknown', evidence: object(p.evidence) }); return { recorded: true }; }
+  if (req.method === 'browser_begin_effect') return control.browserBeginEffect({ conversationId: text(p, 'conversation_id'), conversationUrl: text(p, 'conversation_url'), effectId: text(p, 'effect_id'), dispatchId: text(p, 'dispatch_id'), dispatchGeneration: positiveInteger(p, 'dispatch_generation'), evidence: object(p.evidence) });
+  if (req.method === 'browser_observe_effect') { const outcome = text(p, 'outcome'); if (!['applied','not_applied','unknown'].includes(outcome)) throw new Error('WORKFLOW_SUPERVISOR_RPC_OUTCOME_INVALID'); return control.browserObserveEffect({ conversationId: text(p, 'conversation_id'), conversationUrl: text(p, 'conversation_url'), effectId: text(p, 'effect_id'), observationId: text(p, 'observation_id'), outcome: outcome as 'applied'|'not_applied'|'unknown', evidence: object(p.evidence) }); }
+  // A generic observer cannot attest that a provider dispatch returned before Send.
+  // Only the in-process Computer dispatch owner may write a negative proof.
+  if (req.method === 'browser_observe_dispatch_failure') throw new Error('WORKFLOW_SUPERVISOR_RPC_DISPATCH_OWNER_ONLY');
+  if (req.method === 'browser_observe_provider_turn') return control.browserObserveProviderTurn({ conversationId: text(p, 'conversation_id'), conversationUrl: text(p, 'conversation_url'), generating: p.generating === true, latestAssistantResponse: stringValue(p.latest_assistant_response), providerActivityText: stringValue(p.provider_activity_text), providerFailureCode: chatgptProviderPageFailure(stringValue(p.provider_failure_text)), observedAtMs: safeInteger(p, 'observed_at_ms'), graceMs: positiveInteger(p, 'grace_ms') });
+  if (req.method === 'browser_observe_assistant') return control.browserObserveAssistant({ conversationId: text(p, 'conversation_id'), conversationUrl: text(p, 'conversation_url'), responseText: text(p, 'response_text') });
+  if (req.method === 'task_register') return control.registerTask({ taskId: text(p, 'task_id'), conversationId: text(p, 'conversation_id'), conversationUrl: text(p, 'conversation_url'), objective: text(p, 'objective'), completionContract: object(p.completion_contract), continuationPolicy: object(p.continuation_policy), userBlockerPolicy: object(p.user_blocker_policy) });
+  if (req.method === 'task_revise_objective') return control.reviseTaskObjective({
+    taskId: text(p, 'task_id'),
+    objective: text(p, 'objective'),
+    expectedObjectiveSha256: text(p, 'expected_objective_sha256'),
+    requestId: text(p, 'request_id'),
+    ...(typeof p.work_id === 'string' && p.work_id.trim() ? { workId: p.work_id.trim() } : {}),
+    ...(typeof p.requirement_id === 'string' && p.requirement_id.trim() ? { requirementId: p.requirement_id.trim() } : {}),
+    ...(typeof p.expected_completion_contract_sha256 === 'string' && p.expected_completion_contract_sha256.trim() ? { expectedCompletionContractSha256: p.expected_completion_contract_sha256.trim() } : {}),
+    ...(typeof p.authorized_by === 'string' && p.authorized_by.trim() ? { authorizedBy: p.authorized_by.trim() } : {}),
+  });
+  if (req.method === 'task_list') return p.terminal_only === true
+    ? { tasks: [], terminalTasks: control.listTerminalTasks() }
+    : { tasks: control.listTasks(p.active_only === true) };
+  if (req.method === 'task_stop') return control.stopTask(text(p, 'task_id'), typeof p.reason === 'string' && p.reason.trim() ? p.reason.trim() : 'Stopped by operator request.');
+  if (req.method === 'task_recover') return control.recoverTask({
+    taskId: text(p, 'task_id'),
+    ...(typeof p.source_effect_id === 'string' && p.source_effect_id.trim() ? { sourceEffectId: p.source_effect_id.trim() } : {}),
+    requestId: text(p, 'request_id'),
+    reason: text(p, 'reason'),
+    ...(p.supersede_unknown === true ? { supersedeUnknown: true } : {}),
+    ...(typeof p.authorized_by === 'string' && p.authorized_by.trim() ? { authorizedBy: p.authorized_by.trim() } : {}),
+  });
+  if (req.method === 'task_stall') return control.taskStall(text(p, 'task_id'));
+  if (req.method === 'task_bind_scheduled_wake') return control.bindScheduledWake({
+    taskId: text(p, 'task_id'), repoId: text(p, 'repo_id'), workId: text(p, 'work_id'), scheduleId: text(p, 'schedule_id'),
+  });
+  if (req.method === 'task_wake_scheduled') return control.wakeScheduledTask({
+    taskId: text(p, 'task_id'), scheduleId: text(p, 'schedule_id'), occurrenceId: text(p, 'occurrence_id'),
+  });
+  if (req.method === 'task_migrate_conversation') return control.migrateConversation({
+    taskId: text(p, 'task_id'),
+    expectedConversationId: text(p, 'expected_conversation_id'),
+    ...(typeof p.conversation_id === 'string' && p.conversation_id.trim() ? { conversationId: p.conversation_id.trim() } : {}),
+    ...(typeof p.conversation_url === 'string' && p.conversation_url.trim() ? { conversationUrl: p.conversation_url.trim() } : {}),
+    ...(p.fresh === true ? { fresh: true } : {}),
+    requestId: text(p, 'request_id'),
+    reason: text(p, 'reason'),
+    ...(typeof p.authorized_by === 'string' && p.authorized_by.trim() ? { authorizedBy: p.authorized_by.trim() } : {}),
+  });
+  if (req.method === 'bootstrap_bind_conversation') return control.bindBootstrapConversation({ taskId: text(p, 'task_id'), conversationId: text(p, 'conversation_id'), conversationUrl: text(p, 'conversation_url') });
+  if (req.method === 'reserve_enrollment') return control.reserveEnrollment(text(p, 'task_id'), typeof p.effect_id === 'string' ? p.effect_id : undefined);
+  if (req.method === 'observe_effect') { const outcome = text(p, 'outcome'); if (!['applied','unknown'].includes(outcome)) throw new Error('WORKFLOW_SUPERVISOR_RPC_OUTCOME_INVALID'); control.observeEffect({ effectId: text(p, 'effect_id'), observationId: text(p, 'observation_id'), outcome: outcome as 'applied'|'unknown', evidence: object(p.evidence) }); return { recorded: true }; }
+  if (req.method === 'observe_assistant') return control.observeAssistantTurn({ taskId: text(p, 'task_id'), conversationId: text(p, 'conversation_id'), responseText: text(p, 'response_text') });
+  if (req.method === 'task_get') return control.getTask(text(p, 'task_id')) ?? null;
+  if (req.method === 'task_get_by_conversation') return control.getTaskByConversationId(text(p, 'conversation_id')) ?? null;
+  if (req.method === 'effect_get') return control.getEffect(text(p, 'effect_id')) ?? null;
+  if (req.method === 'effect_dispatch_budget') return control.effectDispatchBudget(text(p, 'effect_id'));
+  if (req.method === 'continuation_proof') return control.continuationProof({ repoId: typeof p.repo_id === 'string' && p.repo_id.trim() ? p.repo_id.trim() : undefined, activeReleaseId: text(p, 'active_release_id'), notBefore: text(p, 'not_before') }) ?? null;
+  throw new Error('WORKFLOW_SUPERVISOR_RPC_METHOD_UNKNOWN');
+}
+function object(value: unknown): Record<string, unknown> { return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {}; }
+function stringValue(value: unknown): string { return typeof value === 'string' ? value : ''; }
+function safeInteger(params: Record<string, unknown>, key: string): number { const value = Number(params[key]); if (!Number.isSafeInteger(value) || value < 0) throw new Error(`WORKFLOW_SUPERVISOR_RPC_${key.toUpperCase()}_INVALID`); return value; }
+function positiveInteger(params: Record<string, unknown>, key: string): number { const value = Number(params[key]); if (!Number.isInteger(value) || value < 1 || value > 1_000_000) throw new Error(`WORKFLOW_SUPERVISOR_RPC_${key.toUpperCase()}_INVALID`); return value; }