@moretea-labs/forge 1.8.0 → 1.8.2

package/src/runtime/root/controller-progression-composition.ts

@@ -0,0 +1,254 @@
+import {
+  beginControllerRoundRelayAfterRelease,
+  bindControllerSessionToCurrentRuntime,
+  controllerRoundBlockerClass,
+  controllerSessionPrincipalId,
+  getControllerRoundRelay,
+  getControllerWorkBinding,
+  getRetainedControllerSession,
+  prepareControllerRoundOccurrence,
+  resumeControllerRoundOccurrence,
+  type ControllerBinding,
+  type ControllerHost,
+  type ControllerSession,
+} from '../../../packages/kernel/controller/api/index';
+import { getWorkContract, semanticWorkState } from '../../../packages/kernel/work/api/index';
+import {
+  controllerHostForScheduledBinding,
+  ensureScheduledControllerBindingForWork,
+} from './scheduled-controller-composition';
+import {
+  ensureWorkflowSupervisorEnrollmentForWork,
+  wakeWorkflowSupervisorScheduledTaskForWork,
+  type WorkflowSupervisorEnrollmentStatus,
+} from './workflow-supervisor-composition';
+import { getRuntimeWriteClaim } from './write-fence';
+
+export interface ControllerProgressionInput {
+  workId: string;
+  occurrenceId: string;
+  relayScopeId?: string;
+  continuationHint?: string;
+  allowSemanticWaitRecovery?: boolean;
+  scheduleName?: string;
+  scheduleId?: string;
+  scheduleOccurrenceId?: string;
+  bindingArgs?: Record<string, unknown>;
+}
+
+export interface ControllerProgressionDependencies {
+  ensureBinding?: typeof ensureScheduledControllerBindingForWork;
+  hostForBinding?: typeof controllerHostForScheduledBinding;
+  prepareOccurrence?: typeof prepareControllerRoundOccurrence;
+  resumeOccurrence?: typeof resumeControllerRoundOccurrence;
+  ensureSupervisorEnrollment?: typeof ensureWorkflowSupervisorEnrollmentForWork;
+  wakeScheduledSupervisorTask?: typeof wakeWorkflowSupervisorScheduledTaskForWork;
+}
+
+export type ControllerProgressionResult =
+  | { status: 'terminal_or_missing'; reason: string }
+  | { status: 'retained_session_missing'; reason: string }
+  | { status: 'human_controller'; reason: string }
+  | { status: 'semantic_wait'; reason?: string; binding: ControllerBinding }
+  | { status: 'wait_for_user'; reason?: string; binding: ControllerBinding }
+  | { status: 'rejected'; reason?: string; binding: ControllerBinding }
+  | {
+      status: 'chatgpt_enrolled';
+      binding: ControllerBinding;
+      relayScopeId: string;
+      reused: boolean;
+      supervisorEnrollment: {
+        status: WorkflowSupervisorEnrollmentStatus;
+        taskId?: string;
+        effectId?: string;
+        reason?: string;
+      };
+    }
+  | {
+      status: 'scheduled_supervisor_woken';
+      binding: ControllerBinding;
+      taskId: string;
+      effectId: string;
+    }
+  | {
+      status: 'chatgpt_not_enrolled';
+      binding: ControllerBinding;
+      relayScopeId: string;
+      reused: boolean;
+      supervisorEnrollment: {
+        status: WorkflowSupervisorEnrollmentStatus;
+        taskId?: string;
+        effectId?: string;
+        reason?: string;
+      };
+    }
+  | {
+      status: 'provider_dispatched';
+      binding: ControllerBinding;
+      relayScopeId: string;
+      reused: boolean;
+      providerDispatchReceiptId?: string;
+    };
+
+/**
+ * Stateless composition for one already-authorized Controller progression
+ * occurrence. It owns no persistence and introduces no lifecycle state.
+ *
+ * Work decides semantic terminality. ControllerSession/ControllerRound provide
+ * retained execution identity and one mechanical occurrence. Workflow Supervisor
+ * exclusively reserves and delivers Work-bound ChatGPT effects. Non-ChatGPT
+ * ControllerHost remains the direct provider boundary.
+ */
+function rebindRetainedSessionToCurrentRuntime(
+  options: { controllerHome: string; repoId: string },
+  session: ControllerSession,
+): ControllerSession {
+  const currentRuntimeInstanceId = getRuntimeWriteClaim()?.runtimeInstanceId?.trim();
+  if (!currentRuntimeInstanceId || currentRuntimeInstanceId === session.controllerInstanceId?.trim()) return session;
+  return bindControllerSessionToCurrentRuntime({
+    controllerHome: options.controllerHome,
+    repoId: options.repoId,
+  }, {
+    workId: session.workId,
+    controllerId: session.controllerId,
+    controllerType: session.controllerType,
+    sessionId: session.sessionId,
+    principalId: controllerSessionPrincipalId(session),
+    controllerInstanceId: currentRuntimeInstanceId,
+    currentRuntimeInstanceId,
+    allowClaimIfMissing: true,
+  });
+}
+
+export async function reconcileControllerProgression(
+  options: { controllerHome: string; repoId: string; repoRoot: string },
+  input: ControllerProgressionInput,
+  dependencies: ControllerProgressionDependencies = {},
+): Promise<ControllerProgressionResult> {
+  const store = { controllerHome: options.controllerHome, repoId: options.repoId };
+  const work = getWorkContract(store, input.workId);
+  if (!work || semanticWorkState(work) !== 'open') {
+    return { status: 'terminal_or_missing', reason: work ? `WORK_TERMINAL:${semanticWorkState(work)}` : 'WORK_NOT_FOUND' };
+  }
+
+  const retainedSession = getRetainedControllerSession(store, input.workId);
+  if (!retainedSession) return { status: 'retained_session_missing', reason: 'CONTROLLER_SESSION_NOT_RETAINED' };
+  if (retainedSession.controllerType === 'human') return { status: 'human_controller', reason: 'HUMAN_CONTROLLER' };
+
+  let existingRound = retainedSession.controllerType === 'chatgpt'
+    ? getControllerRoundRelay(store, input.workId)
+    : undefined;
+  if (existingRound?.status === 'pending_release') {
+    // The release fence belongs to the previous Controller epoch. Consume it
+    // before migrating the retained session to the new Runtime epoch.
+    existingRound = beginControllerRoundRelayAfterRelease(store, {
+      workId: input.workId,
+      releasedSession: retainedSession,
+    }) ?? getControllerRoundRelay(store, input.workId);
+  }
+  const session = rebindRetainedSessionToCurrentRuntime(store, retainedSession);
+
+  const ensureBinding = dependencies.ensureBinding ?? ensureScheduledControllerBindingForWork;
+  const existingBinding = getControllerWorkBinding(store, input.workId)?.binding;
+  const binding = existingBinding ?? ensureBinding(store, {
+    workId: input.workId,
+    session,
+    scheduleName: input.scheduleName,
+    args: input.bindingArgs ?? {},
+  });
+
+  if (session.controllerType === 'chatgpt' && input.scheduleId && input.scheduleOccurrenceId) {
+    const wakeScheduledSupervisorTask = dependencies.wakeScheduledSupervisorTask ?? wakeWorkflowSupervisorScheduledTaskForWork;
+    const wake = await wakeScheduledSupervisorTask(
+      store, input.workId, input.scheduleId, input.scheduleOccurrenceId,
+    );
+    if (wake.status === 'woken' && wake.taskId && wake.effectId) {
+      return {
+        status: 'scheduled_supervisor_woken',
+        binding,
+        taskId: wake.taskId,
+        effectId: wake.effectId,
+      };
+    }
+  }
+
+  if (session.controllerType === 'chatgpt') {
+    const ensureSupervisorEnrollment = dependencies.ensureSupervisorEnrollment ?? ensureWorkflowSupervisorEnrollmentForWork;
+    let controllerRoundOccurrenceId = input.occurrenceId;
+    if (existingRound?.status === 'pending_release') {
+      // The semantic turn already chose continue_immediately. Once its exact
+      // ControllerSession lease has been released, reopen that same durable
+      // ControllerRound for dispatch before reserving another Supervisor effect.
+      // Schedule occurrence ids are trigger evidence, not a replacement
+      // ControllerRound identity for an already-open continuation chain.
+      existingRound = beginControllerRoundRelayAfterRelease(store, {
+        workId: input.workId,
+        releasedSession: retainedSession,
+      }) ?? getControllerRoundRelay(store, input.workId);
+    }
+    // An already-open recoverable ControllerRound keeps its durable occurrence
+    // identity across Scheduler wake attempts. A fresh ScheduleOccurrence is
+    // trigger/evidence identity only; replacing the round occurrence here would
+    // manufacture a second open round and permanently self-block continuation.
+    if (existingRound?.occurrenceId?.trim()
+      && ['dispatching', 'dispatched', 'claimed'].includes(existingRound.status)) {
+      controllerRoundOccurrenceId = existingRound.occurrenceId.trim();
+    }
+    if (existingRound?.status === 'blocked'
+      && controllerRoundBlockerClass(existingRound) === 'provider_dispatch_outcome_unknown') {
+      const supervisorEnrollment = await ensureSupervisorEnrollment(store, input.workId, input.scheduleId, input.scheduleOccurrenceId);
+      return {
+        status: supervisorEnrollment.status === 'enrolled' ? 'chatgpt_enrolled' : 'chatgpt_not_enrolled',
+        binding,
+        relayScopeId: existingRound.relayScopeId,
+        reused: true,
+        supervisorEnrollment,
+      };
+    }
+
+    const prepareOccurrence = dependencies.prepareOccurrence ?? prepareControllerRoundOccurrence;
+    const prepared = prepareOccurrence(store, {
+      occurrenceId: controllerRoundOccurrenceId,
+      workId: input.workId,
+      controllerBindingId: binding.bindingId,
+      relayScopeId: input.relayScopeId,
+      continuationHint: input.continuationHint,
+      allowSemanticWaitRecovery: input.allowSemanticWaitRecovery,
+    });
+    if (prepared.outcome === 'semantic_wait') return { status: 'semantic_wait', reason: prepared.reason, binding };
+    if (prepared.outcome === 'wait_for_user') return { status: 'wait_for_user', reason: prepared.reason, binding };
+    if (prepared.outcome === 'rejected') return { status: 'rejected', reason: prepared.reason, binding };
+
+    const supervisorEnrollment = await ensureSupervisorEnrollment(store, input.workId, input.scheduleId, input.scheduleOccurrenceId);
+    return {
+      status: supervisorEnrollment.status === 'enrolled' ? 'chatgpt_enrolled' : 'chatgpt_not_enrolled',
+      binding,
+      relayScopeId: prepared.relay.relayScopeId,
+      reused: prepared.reused,
+      supervisorEnrollment,
+    };
+  }
+
+  const hostForBinding = dependencies.hostForBinding ?? controllerHostForScheduledBinding;
+  const host: ControllerHost = hostForBinding(options, binding);
+  const resumeOccurrence = dependencies.resumeOccurrence ?? resumeControllerRoundOccurrence;
+  const resumed = await resumeOccurrence(store, {
+    occurrenceId: input.occurrenceId,
+    workId: input.workId,
+    controllerBindingId: binding.bindingId,
+    relayScopeId: input.relayScopeId,
+    continuationHint: input.continuationHint,
+    allowSemanticWaitRecovery: input.allowSemanticWaitRecovery,
+  }, host);
+
+  if (resumed.outcome === 'semantic_wait') return { status: 'semantic_wait', reason: resumed.reason, binding };
+  if (resumed.outcome === 'wait_for_user') return { status: 'wait_for_user', reason: resumed.reason, binding };
+  if (resumed.outcome === 'rejected') return { status: 'rejected', reason: resumed.reason, binding };
+  return {
+    status: 'provider_dispatched',
+    binding,
+    relayScopeId: resumed.relay.relayScopeId,
+    reused: resumed.reused,
+    providerDispatchReceiptId: resumed.providerDispatchReceiptId,
+  };
+}

package/src/runtime/root/controller-round-composition.ts

@@ -3,6 +3,11 @@ import type { AssistantContextSnapshot, ControllerRoundRelayRecord } from '../..
 import { prepareAssistantWorkContext } from '../context/assistant-work-context';
 import { renderAssistantContext, type AssistantContextResolution } from '../context/assistant-context';
 import { getChatgptWorkConversationBinding } from '../../../adapters/chatgpt/work-conversation-binding-store';
+import {
+  chatgptControllerProviderBindingId,
+  upsertChatgptControllerBinding,
+  type ChatgptControllerBindingPayload,
+} from '../../../adapters/chatgpt/controller-binding-store';
 import {
   buildChatgptControllerRoundPrompt,
   chatgptControllerRoundBindingAuthorizesRecovery,
@@ -22,6 +27,18 @@ export interface ChatgptControllerRoundBindingSnapshot {
   bindingId?: string;
   browserSessionId?: string;
   conversationUrl?: string;
+  authorizationGrantRefs?: string[];
+}
+
+export function chatgptControllerRoundBindingId(workId: string): string {
+  return chatgptControllerProviderBindingId(workId);
+}
+
+export function upsertChatgptControllerRoundTransportBinding(
+  store: ControllerRoundCompositionStore,
+  input: Omit<ChatgptControllerBindingPayload, 'schemaVersion' | 'bindingId' | 'repoId' | 'createdAt' | 'updatedAt'>,
+) {
+  return upsertChatgptControllerBinding(store, input);
 }
 
 export function chatgptControllerRoundBinding(
@@ -34,6 +51,7 @@ export function chatgptControllerRoundBinding(
     bindingId: binding.bindingId,
     browserSessionId: binding.latestBrowserSessionId,
     conversationUrl: binding.conversationUrl,
+    authorizationGrantRefs: [...(binding.authorizationGrantRefs ?? [])],
   };
 }
 
@@ -65,6 +83,7 @@ export function recordChatgptControllerRoundTabSettlement(
     relayScopeId: string;
     status: ChatgptControllerRoundSettlementStatus;
     error?: string;
+    attemptIdentity?: string;
   },
 ): void {
   recordChatgptControllerRoundSettlement(store, input);
@@ -79,7 +98,7 @@ function controllerAssistantContextSnapshot(resolution: AssistantContextResoluti
     sourceRevision: item.provenance.sourceRevision,
   }));
   const identity = {
-    projectId: resolution.projectId,
+    ...(resolution.projectId ? { projectId: resolution.projectId } : {}),
     items,
     gaps: resolution.gaps,
     missingRequiredSources: resolution.missingRequiredSources,

package/src/runtime/root/deployment-topology.ts

@@ -0,0 +1,106 @@
+export type RuntimeRemoteControllerKind = 'chatgpt' | 'mcp';
+
+export interface RuntimeDeploymentTopology {
+  schemaVersion: 1;
+  remoteControllers: RuntimeRemoteControllerKind[];
+  capabilityIntents: string[];
+  persistentRuntimeRequired: boolean;
+  components: {
+    workflowSupervisor: boolean;
+    workflowSupervisorNativeBrowser: boolean;
+  };
+}
+
+const REMOTE_CONTROLLERS = new Set<RuntimeRemoteControllerKind>(['chatgpt', 'mcp']);
+
+function normalizeCapabilityIntent(value: string): string {
+  const normalized = value.trim().toLowerCase();
+  if (!/^[-a-z0-9_.]{3,128}$/.test(normalized)) throw new Error(`RUNTIME_TOPOLOGY_CAPABILITY_INTENT_INVALID: ${value}`);
+  return normalized;
+}
+
+function normalizedRemoteControllers(values: readonly string[] | undefined): RuntimeRemoteControllerKind[] {
+  return Array.from(new Set(
+    (values ?? [])
+      .map((value) => value.trim().toLowerCase())
+      .filter((value): value is RuntimeRemoteControllerKind => REMOTE_CONTROLLERS.has(value as RuntimeRemoteControllerKind)),
+  )).sort();
+}
+
+export function deriveRuntimeDeploymentTopology(input: {
+  controllers?: readonly string[];
+  capabilityIntents?: readonly string[];
+}): RuntimeDeploymentTopology {
+  const remoteControllers = normalizedRemoteControllers(input.controllers);
+  const capabilityIntents = Array.from(new Set(
+    (input.capabilityIntents ?? []).map(normalizeCapabilityIntent),
+  )).sort();
+  const chatgpt = remoteControllers.includes('chatgpt');
+  return {
+    schemaVersion: 1,
+    remoteControllers,
+    capabilityIntents,
+    persistentRuntimeRequired: remoteControllers.length > 0,
+    components: {
+      // Requirement-level ChatGPT continuation uses Supervisor Core as its
+      // outer-turn authority. Generic remote MCP transport does not.
+      workflowSupervisor: chatgpt,
+      // ChatGPT Work has one controlled outer-turn executor: the Supervisor's
+      // Computer adapter. It owns exact-conversation delivery and its durable
+      // effect ledger; Scheduler must never fall back to direct Browser delivery.
+      workflowSupervisorNativeBrowser: chatgpt,
+    },
+  };
+}
+
+/**
+ * Missing topology means an installation predates this contract. Preserve the
+ * complete ChatGPT Supervisor composition during upgrade.
+ */
+export function legacyRuntimeDeploymentTopology(): RuntimeDeploymentTopology {
+  return deriveRuntimeDeploymentTopology({ controllers: ['chatgpt'] });
+}
+
+export function normalizeRuntimeDeploymentTopology(value: unknown): RuntimeDeploymentTopology {
+  if (value === undefined || value === null) return legacyRuntimeDeploymentTopology();
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('RUNTIME_TOPOLOGY_INVALID');
+  const record = value as Record<string, unknown>;
+  if (record.schemaVersion !== 1) throw new Error('RUNTIME_TOPOLOGY_VERSION_UNSUPPORTED');
+  if (!Array.isArray(record.remoteControllers)
+    || record.remoteControllers.some((entry) => typeof entry !== 'string' || !REMOTE_CONTROLLERS.has(entry as RuntimeRemoteControllerKind))) {
+    throw new Error('RUNTIME_TOPOLOGY_REMOTE_CONTROLLERS_INVALID');
+  }
+  if (!Array.isArray(record.capabilityIntents)
+    || record.capabilityIntents.some((entry) => typeof entry !== 'string')) {
+    throw new Error('RUNTIME_TOPOLOGY_CAPABILITY_INTENTS_INVALID');
+  }
+  const remoteControllers = normalizedRemoteControllers(record.remoteControllers as string[]);
+  const capabilityIntents = Array.from(new Set(
+    (record.capabilityIntents as string[]).map(normalizeCapabilityIntent),
+  )).sort();
+  const canonical = deriveRuntimeDeploymentTopology({ controllers: remoteControllers, capabilityIntents });
+  const components = record.components;
+  if (!components || typeof components !== 'object' || Array.isArray(components)) throw new Error('RUNTIME_TOPOLOGY_COMPONENTS_REQUIRED');
+  const componentRecord = components as Record<string, unknown>;
+  if (typeof componentRecord.workflowSupervisor !== 'boolean'
+    || typeof componentRecord.workflowSupervisorNativeBrowser !== 'boolean') {
+    throw new Error('RUNTIME_TOPOLOGY_COMPONENTS_INVALID');
+  }
+  if (componentRecord.workflowSupervisor !== canonical.components.workflowSupervisor
+    || record.persistentRuntimeRequired !== canonical.persistentRuntimeRequired) {
+    throw new Error('RUNTIME_TOPOLOGY_DERIVATION_MISMATCH');
+  }
+  // The flag is derived, so stale persisted topology cannot disable the sole
+  // autonomous delivery owner or reintroduce an alternate Browser path.
+  return canonical;
+}
+
+export function parseRuntimeDeploymentTopologyArgument(value: string | undefined): RuntimeDeploymentTopology {
+  if (!value?.trim()) return legacyRuntimeDeploymentTopology();
+  try {
+    return normalizeRuntimeDeploymentTopology(JSON.parse(value));
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`RUNTIME_TOPOLOGY_ARGUMENT_INVALID: ${detail}`);
+  }
+}

package/src/runtime/root/entry.ts

@@ -3,6 +3,7 @@ import { resolve } from 'path';
 import { pathToFileURL } from 'url';
 import { Command } from 'commander';
 import { CanonicalForgeRuntime } from './runtime';
+import { parseRuntimeDeploymentTopologyArgument } from './deployment-topology';
 
 interface CliOptions {
   controllerHome: string;
@@ -11,7 +12,7 @@ interface CliOptions {
   host: string;
   port: string;
   authTokenFile: string;
-  exclusiveWorkId?: string;
+  deploymentTopology?: string;
 }
 
 function readAuthToken(path: string): string {
@@ -29,7 +30,7 @@ export async function runCanonicalRuntimeCli(argv = process.argv): Promise<void>
     .requiredOption('--host <host>', 'MCP listener host')
     .requiredOption('--port <port>', 'MCP listener port')
     .requiredOption('--auth-token-file <path>', 'Bearer token file')
-    .option('--exclusive-work-id <id>', 'Persistently admit only this P0 Work while migration is active');
+    .option('--deployment-topology <json>', 'Normalized product-level Runtime deployment topology');
   command.parse(argv);
   const options = command.opts<CliOptions>();
   const port = Number(options.port);
@@ -40,8 +41,8 @@ export async function runCanonicalRuntimeCli(argv = process.argv): Promise<void>
     releaseManifestPath: resolve(options.releaseManifest),
     host: options.host,
     port,
+    topology: parseRuntimeDeploymentTopologyArgument(options.deploymentTopology),
     authToken: readAuthToken(options.authTokenFile),
-    exclusiveWorkId: options.exclusiveWorkId,
   });
   await runtime.start();
   process.stderr.write(`${JSON.stringify({

package/src/runtime/root/known-good-recovery.ts

@@ -0,0 +1,184 @@
+import { createHash } from 'crypto';
+import { closeSync, existsSync, openSync, readFileSync, readSync, realpathSync } from 'fs';
+import { basename, dirname, join, relative, resolve } from 'path';
+import { inspectControlPlaneDatabaseFile, type ControlPlaneDatabaseInspection } from '../control-plane/persistence/sqlite-store';
+import { loadRuntimeReleaseManifest } from './release-manifest';
+import { forgeRuntimeServicePaths, validateForgeRuntimeServiceConfig, type ForgeRuntimeServiceConfig } from './service';
+
+/**
+ * A Recovery-owned, bounded restore point.  The release is immutable Runtime
+ * authority; the SQLite copy and service contract are the state and bootstrap
+ * material needed to make that release useful after the Kernel is dead.
+ */
+export interface KnownGoodRecoveryBundle {
+  schemaVersion: 1;
+  attestationId: string;
+  root: string;
+  database: {
+    path: string;
+    sha256: string;
+    schemaVersion: number;
+    recordCount: number;
+    auditEventCount: number;
+  };
+  serviceContract: {
+    path: string;
+    sha256: string;
+  };
+  createdAt: string;
+}
+
+export interface KnownGoodReleaseIdentity {
+  path: string;
+  revision: string;
+  artifactIdentity: string;
+  manifestSha256: string;
+  workerProtocolVersion: number;
+  controllerHome?: string;
+  recoveryBundle?: KnownGoodRecoveryBundle;
+}
+
+export interface InspectedKnownGoodRecoveryBundle {
+  releaseRoot: string;
+  database: ControlPlaneDatabaseInspection;
+  serviceConfig: ForgeRuntimeServiceConfig;
+}
+
+const SHA256_FILE_CHUNK_BYTES = 1024 * 1024;
+
+/** Hash arbitrarily large Recovery artifacts without allocating the whole file. */
+export function sha256FileBounded(path: string): string {
+  const descriptor = openSync(path, 'r');
+  const hash = createHash('sha256');
+  const buffer = Buffer.allocUnsafe(SHA256_FILE_CHUNK_BYTES);
+  try {
+    for (;;) {
+      const bytesRead = readSync(descriptor, buffer, 0, buffer.length, null);
+      if (bytesRead === 0) break;
+      hash.update(buffer.subarray(0, bytesRead));
+    }
+    return hash.digest('hex');
+  } finally {
+    closeSync(descriptor);
+  }
+}
+
+function canonical(path: string): string {
+  try { return realpathSync(path); }
+  catch { return resolve(path); }
+}
+
+function directChild(root: string, path: string): boolean {
+  return canonical(dirname(path)) === canonical(root);
+}
+
+function inside(root: string, path: string): boolean {
+  const value = relative(canonical(root), canonical(path));
+  return value === '' || (!value.startsWith('..') && value !== '..');
+}
+
+function requiredText(value: unknown, code: string): string {
+  if (typeof value !== 'string' || !value.trim()) throw new Error(code);
+  return value.trim();
+}
+
+function requiredPositiveInteger(value: unknown, code: string): number {
+  if (!Number.isInteger(value) || Number(value) < 1) throw new Error(code);
+  return Number(value);
+}
+
+function validateRecoveryBundleShape(entry: KnownGoodReleaseIdentity, controllerHome: string): KnownGoodRecoveryBundle {
+  const bundle = entry.recoveryBundle;
+  if (!bundle || bundle.schemaVersion !== 1) throw new Error('KNOWN_GOOD_RECOVERY_BUNDLE_MISSING');
+  const home = resolve(controllerHome);
+  const root = resolve(bundle.root);
+  const expectedBundlesRoot = resolve(home, 'recovery', 'bundles', 'known-good');
+  const attestationId = requiredText(bundle.attestationId, 'KNOWN_GOOD_RECOVERY_BUNDLE_ID_INVALID');
+  if (basename(root) !== attestationId || !directChild(expectedBundlesRoot, root)) {
+    throw new Error('KNOWN_GOOD_RECOVERY_BUNDLE_OUTSIDE_AUTHORITY');
+  }
+  if (!/^[-a-zA-Z0-9_]{8,160}$/.test(attestationId)) throw new Error('KNOWN_GOOD_RECOVERY_BUNDLE_ID_INVALID');
+  if (!inside(root, bundle.database.path) || basename(resolve(bundle.database.path)) !== 'controller.sqlite') {
+    throw new Error('KNOWN_GOOD_RECOVERY_DATABASE_PATH_INVALID');
+  }
+  if (!inside(root, bundle.serviceContract.path) || basename(resolve(bundle.serviceContract.path)) !== 'service-contract.json') {
+    throw new Error('KNOWN_GOOD_RECOVERY_SERVICE_CONTRACT_PATH_INVALID');
+  }
+  requiredText(bundle.database.sha256, 'KNOWN_GOOD_RECOVERY_DATABASE_HASH_INVALID');
+  requiredText(bundle.serviceContract.sha256, 'KNOWN_GOOD_RECOVERY_SERVICE_CONTRACT_HASH_INVALID');
+  requiredPositiveInteger(bundle.database.schemaVersion, 'KNOWN_GOOD_RECOVERY_DATABASE_SCHEMA_INVALID');
+  return {
+    ...bundle,
+    attestationId,
+    root,
+    database: { ...bundle.database, path: resolve(bundle.database.path) },
+    serviceContract: { ...bundle.serviceContract, path: resolve(bundle.serviceContract.path) },
+  };
+}
+
+/**
+ * Validate the exact three-way restore invariant used by both Recovery and
+ * release retention.  Legacy evidence without a Recovery bundle is historical
+ * audit data only: it must never be promoted to recoverable authority.
+ */
+export function inspectKnownGoodRecoveryBundle(
+  controllerHome: string,
+  entry: KnownGoodReleaseIdentity,
+): InspectedKnownGoodRecoveryBundle {
+  const home = resolve(controllerHome);
+  if (entry.controllerHome && canonical(entry.controllerHome) !== canonical(home)) {
+    throw new Error('KNOWN_GOOD_RECOVERY_CONTROLLER_HOME_MISMATCH');
+  }
+  const manifestPath = resolve(requiredText(entry.path, 'KNOWN_GOOD_RELEASE_MANIFEST_PATH_INVALID'));
+  const releasesRoot = resolve(home, 'runtime', 'releases');
+  const releaseRoot = dirname(manifestPath);
+  if (
+    basename(manifestPath) !== 'manifest.json'
+    || basename(releaseRoot) !== entry.revision
+    || !directChild(releasesRoot, releaseRoot)
+    || !existsSync(manifestPath)
+  ) throw new Error('KNOWN_GOOD_RELEASE_OUTSIDE_AUTHORITY');
+  const manifest = loadRuntimeReleaseManifest(manifestPath, home);
+  if (
+    manifest.releaseId !== entry.revision
+    || manifest.artifactIdentity !== entry.artifactIdentity
+    || manifest.workerProtocolVersion !== entry.workerProtocolVersion
+    || sha256FileBounded(manifestPath) !== entry.manifestSha256
+  ) throw new Error('KNOWN_GOOD_RELEASE_IDENTITY_MISMATCH');
+
+  const bundle = validateRecoveryBundleShape(entry, home);
+  if (!existsSync(bundle.database.path)) throw new Error('KNOWN_GOOD_RECOVERY_DATABASE_MISSING');
+  if (sha256FileBounded(bundle.database.path) !== bundle.database.sha256) throw new Error('KNOWN_GOOD_RECOVERY_DATABASE_HASH_MISMATCH');
+  const database = inspectControlPlaneDatabaseFile(bundle.database.path);
+  if (
+    database.schemaVersion !== bundle.database.schemaVersion
+    || database.recordCount !== bundle.database.recordCount
+    || database.auditEventCount !== bundle.database.auditEventCount
+  ) throw new Error('KNOWN_GOOD_RECOVERY_DATABASE_INSPECTION_MISMATCH');
+
+  if (!existsSync(bundle.serviceContract.path)) throw new Error('KNOWN_GOOD_RECOVERY_SERVICE_CONTRACT_MISSING');
+  if (sha256FileBounded(bundle.serviceContract.path) !== bundle.serviceContract.sha256) {
+    throw new Error('KNOWN_GOOD_RECOVERY_SERVICE_CONTRACT_HASH_MISMATCH');
+  }
+  let rawContract: unknown;
+  try { rawContract = JSON.parse(readFileSync(bundle.serviceContract.path, 'utf8')); }
+  catch { throw new Error('KNOWN_GOOD_RECOVERY_SERVICE_CONTRACT_INVALID'); }
+  if (!rawContract || typeof rawContract !== 'object' || Array.isArray(rawContract)) {
+    throw new Error('KNOWN_GOOD_RECOVERY_SERVICE_CONTRACT_INVALID');
+  }
+  const contract = rawContract as Record<string, unknown>;
+  if (contract.schemaVersion !== 1 || !contract.serviceConfig || typeof contract.serviceConfig !== 'object' || Array.isArray(contract.serviceConfig)) {
+    throw new Error('KNOWN_GOOD_RECOVERY_SERVICE_CONTRACT_INVALID');
+  }
+  const serviceConfig = validateForgeRuntimeServiceConfig(contract.serviceConfig as ForgeRuntimeServiceConfig);
+  if (canonical(serviceConfig.controllerHome) !== canonical(home)) throw new Error('KNOWN_GOOD_RECOVERY_SERVICE_HOME_MISMATCH');
+  const expectedConfigPath = forgeRuntimeServicePaths(home).configPath;
+  if (canonical(requiredText(contract.configPath, 'KNOWN_GOOD_RECOVERY_SERVICE_PATH_INVALID')) !== canonical(expectedConfigPath)) {
+    throw new Error('KNOWN_GOOD_RECOVERY_SERVICE_PATH_INVALID');
+  }
+  return { releaseRoot, database, serviceConfig };
+}
+
+export function knownGoodRecoveryBundleRoot(controllerHome: string): string {
+  return join(resolve(controllerHome), 'recovery', 'bundles', 'known-good');
+}

package/src/runtime/root/local-bridge.ts

@@ -35,7 +35,6 @@ export async function startConfiguredRuntimeLocalBridge(input: {
     controllerHome: input.controllerHome,
     host: local.host ?? '127.0.0.1',
     port: local.port ?? 8766,
-    openBrowser: local.autoOpen === true,
     mode: 'embedded',
   });
   const generation = readRuntimeGeneration(input.controllerHome)?.generation;