@moretea-labs/forge 1.5.0-rc.1

package/src/runtime/recovery/patch-handoff.ts

@@ -0,0 +1,50 @@
+import { createHash } from 'crypto';
+import type { PatchHandoffArtifact } from './types';
+
+export interface BuildPatchHandoffArtifactInput {
+  issueId?: string;
+  taskId?: string;
+  baseHead: string;
+  branch: string;
+  diff: string;
+  touchedPaths: string[];
+  checks?: PatchHandoffArtifact['checks'];
+  actor: string;
+  source: string;
+  conflicts?: string[];
+  notes?: string[];
+  createdAt?: string;
+}
+
+export function buildPatchHandoffArtifact(input: BuildPatchHandoffArtifactInput): PatchHandoffArtifact {
+  const createdAt = input.createdAt ?? new Date().toISOString();
+  const diffHash = createHash('sha256').update(input.diff).digest('hex');
+  const conflicts = [...new Set(input.conflicts ?? [])].sort();
+  return {
+    schemaVersion: 1,
+    id: `PATCH-${diffHash.slice(0, 16)}`,
+    createdAt,
+    issueId: input.issueId,
+    taskId: input.taskId,
+    baseHead: input.baseHead,
+    branch: input.branch,
+    touchedPaths: [...new Set(input.touchedPaths)].sort(),
+    diffHash,
+    checks: input.checks ?? [],
+    provenance: {
+      actor: input.actor,
+      workspace: 'isolated_worktree',
+      source: input.source,
+    },
+    integration: {
+      safeToApply: conflicts.length === 0,
+      conflicts,
+      notes: input.notes ?? [],
+    },
+  };
+}
+
+export function detectDirtyPathConflicts(touchedPaths: readonly string[], dirtyPaths: readonly string[]): string[] {
+  const dirty = new Set(dirtyPaths);
+  return [...new Set(touchedPaths)].filter((path) => dirty.has(path)).sort();
+}

package/src/runtime/recovery/probe.ts

@@ -0,0 +1,308 @@
+import { RECOVERY_ACTIONS } from './actions';
+import { classifyFailure, dominantRecoveryClass } from './classifier';
+import type {
+  CapabilityRecoveryInput,
+  CapabilityRecoverySnapshot,
+  CapabilityState,
+  CapabilityStatus,
+  RecoveryActionDescriptor,
+  RecoveryClass,
+  RecoveryEvidence,
+} from './types';
+import type { ComponentHealth, RuntimeHealthEvaluation } from '../health';
+
+const SCHEDULER_STALE_MS = 10_000;
+
+function evidence(source: string, message: string, at: string, details?: Record<string, unknown>): RecoveryEvidence[] {
+  return [{ source, message, at, details }];
+}
+
+function capability(
+  at: string,
+  id: string,
+  label: string,
+  state: CapabilityState,
+  recoveryClass: RecoveryClass,
+  reason: string,
+  suggestedActions: RecoveryActionDescriptor[] = [],
+  details?: Record<string, unknown>,
+): CapabilityStatus {
+  return { id, label, state, class: recoveryClass, reason, suggestedActions, evidence: evidence(id, reason, at, details) };
+}
+
+function dedupeActions(actions: RecoveryActionDescriptor[]): RecoveryActionDescriptor[] {
+  const seen = new Set<string>();
+  return actions.filter((action) => {
+    if (seen.has(action.id)) return false;
+    seen.add(action.id);
+    return true;
+  });
+}
+
+function countStates(capabilities: CapabilityStatus[]): Record<CapabilityState, number> {
+  return capabilities.reduce<Record<CapabilityState, number>>((counts, item) => {
+    counts[item.state] += 1;
+    return counts;
+  }, { ready: 0, degraded: 0, blocked: 0, unavailable: 0, unknown: 0 });
+}
+
+function classifyRecentErrors(input: CapabilityRecoveryInput): RecoveryClass {
+  return dominantRecoveryClass((input.recentErrors ?? []).map(classifyFailure));
+}
+
+function failingJobClass(input: CapabilityRecoveryInput): RecoveryClass {
+  const messages = [
+    ...(input.localJobs ?? []).flatMap((job) => job.error ? [job.error] : []),
+    ...(input.executionJobs ?? []).flatMap((job) => job.error ? [typeof job.error === 'string' ? job.error : JSON.stringify(job.error)] : []),
+  ];
+  return dominantRecoveryClass(messages.map(classifyFailure));
+}
+
+function suggestedActionsForClass(recoveryClass: RecoveryClass): RecoveryActionDescriptor[] {
+  if (recoveryClass === 'platform_blocked' || recoveryClass === 'dirty_worktree_conflict') return [RECOVERY_ACTIONS.createPatchHandoff];
+  if (recoveryClass === 'auth_required') return [RECOVERY_ACTIONS.workspaceAuthLoginPrepare];
+  if (recoveryClass === 'browser_domain_grant_required') return [RECOVERY_ACTIONS.browserDomainAccessPreview];
+  if (recoveryClass === 'external_filesystem_grant_required') return [RECOVERY_ACTIONS.externalFilesystemGrantPreview];
+  if (recoveryClass === 'agent_runtime_failure') return [RECOVERY_ACTIONS.reconcileJobs];
+  if (recoveryClass === 'source_defect_suspected' || recoveryClass === 'external_lifecycle_required') return [];
+  if (['runtime_storage_not_ready', 'local_jobs_legacy_active', 'local_jobs_unreadable', 'local_jobs_reconciliation_required', 'maintenance_executor_required'].includes(recoveryClass)) {
+    return [RECOVERY_ACTIONS.localJobsReconcile, RECOVERY_ACTIONS.finalizeRuntimeStorageRelocation];
+  }
+  return [RECOVERY_ACTIONS.probeAgain];
+}
+
+function runtimeStorageClass(input: CapabilityRecoveryInput): RecoveryClass {
+  return dominantRecoveryClass((input.runtimeStorageWarnings ?? []).map(classifyFailure));
+}
+
+function runtimeStorageActions(recoveryClass: RecoveryClass): RecoveryActionDescriptor[] {
+  if (recoveryClass === 'local_jobs_unreadable') return [RECOVERY_ACTIONS.quarantineUnreadableLocalJobs, RECOVERY_ACTIONS.localJobsReconcile, RECOVERY_ACTIONS.finalizeRuntimeStorageRelocation];
+  if (recoveryClass === 'local_jobs_legacy_active') return [RECOVERY_ACTIONS.localJobsReconcile, RECOVERY_ACTIONS.finalizeRuntimeStorageRelocation];
+  if (recoveryClass === 'runtime_storage_not_ready') return [RECOVERY_ACTIONS.localJobsReconcile, RECOVERY_ACTIONS.finalizeRuntimeStorageRelocation];
+  return [RECOVERY_ACTIONS.localJobsReconcile, RECOVERY_ACTIONS.finalizeRuntimeStorageRelocation];
+}
+
+function commandExecuteActions(recoveryClass: RecoveryClass): RecoveryActionDescriptor[] {
+  if (['runtime_storage_not_ready', 'local_jobs_legacy_active', 'local_jobs_unreadable', 'local_jobs_reconciliation_required'].includes(recoveryClass)) {
+    return runtimeStorageActions(recoveryClass);
+  }
+  return suggestedActionsForClass(recoveryClass);
+}
+
+function capabilityFromSharedHealth(
+  at: string,
+  id: string,
+  label: string,
+  componentHealth: ComponentHealth,
+  recoveryClass: RecoveryClass,
+  suggestedActions: RecoveryActionDescriptor[] = [],
+): CapabilityStatus {
+  const evidenceItem = componentHealth.activeBlockers[0] ?? componentHealth.warnings[0];
+  if (!evidenceItem || componentHealth.state === 'disabled') {
+    return capability(at, id, label, 'ready', 'unknown', componentHealth.state === 'disabled' ? `${label} is disabled by configuration.` : `${label} is healthy.`, [], {
+      sharedHealthState: componentHealth.state,
+    });
+  }
+  return capability(
+    at,
+    id,
+    label,
+    componentHealth.state === 'unavailable' ? 'unavailable' : componentHealth.ready ? 'ready' : 'degraded',
+    recoveryClass,
+    evidenceItem.message,
+    componentHealth.ready ? [] : suggestedActions,
+    { sharedHealthCode: evidenceItem.code, sharedHealthState: componentHealth.state, ...evidenceItem.details },
+  );
+}
+
+export function buildCapabilityRecoverySnapshot(input: CapabilityRecoveryInput): CapabilityRecoverySnapshot {
+  const at = input.generatedAt ?? new Date().toISOString();
+  const capabilities: CapabilityStatus[] = [];
+  const queueDepth = input.queueDepth ?? 0;
+  const runningWorkers = input.runningWorkers ?? 0;
+  const activeLeases = input.activeLeases ?? 0;
+  const sharedHealth = input.runtimeHealth;
+  if (sharedHealth) {
+    capabilities.push(
+      capabilityFromSharedHealth(at, 'forge.runtime', 'Forge Runtime', sharedHealth.components.daemon, 'external_lifecycle_required'),
+      capabilityFromSharedHealth(at, 'durable.scheduler', 'Durable scheduler', sharedHealth.components.scheduler, 'stale_runtime_state', [RECOVERY_ACTIONS.reconcileJobs]),
+      capabilityFromSharedHealth(at, 'worker.loop', 'Worker loop', sharedHealth.components.workers, 'stale_runtime_state', [RECOVERY_ACTIONS.reconcileJobs]),
+      capabilityFromSharedHealth(at, 'local.bridge', 'Local bridge', sharedHealth.components.localBridge, 'local_recoverable', [RECOVERY_ACTIONS.probeAgain]),
+      capabilityFromSharedHealth(at, 'runtime.projection', 'Runtime projection', sharedHealth.components.projection, 'stale_runtime_state', [RECOVERY_ACTIONS.rebuildProjection]),
+      capabilityFromSharedHealth(at, 'runtime.storage', 'Runtime storage', sharedHealth.components.runtimeStorage, 'runtime_storage_not_ready', runtimeStorageActions('runtime_storage_not_ready')),
+    );
+  } else {
+    const daemonReady = input.daemonStatus === undefined || input.daemonStatus === 'ready';
+    capabilities.push(daemonReady
+      ? capability(at, 'forge.runtime', 'Forge Runtime', 'ready', 'unknown', 'Forge Runtime is ready.', [], { status: input.daemonStatus ?? 'unknown' })
+      : capability(at, 'forge.runtime', 'Forge Runtime', 'unavailable', 'external_lifecycle_required', `Forge Runtime is ${input.daemonStatus ?? 'unknown'}; lifecycle recovery belongs to the external owner of the existing single Runtime service.`, [], { status: input.daemonStatus, error: input.daemonError }));
+
+    const schedulerAge = input.schedulerHeartbeatAgeMs;
+    const schedulerStale = typeof schedulerAge === 'number' && schedulerAge > SCHEDULER_STALE_MS;
+    capabilities.push(schedulerStale || input.schedulerStatus === 'degraded' || input.schedulerStatus === 'not_ready'
+      ? capability(at, 'durable.scheduler', 'Durable scheduler', 'degraded', 'stale_runtime_state', 'Scheduler heartbeat is stale or degraded.', [RECOVERY_ACTIONS.reconcileJobs], { schedulerStatus: input.schedulerStatus, schedulerHeartbeatAgeMs: schedulerAge })
+      : capability(at, 'durable.scheduler', 'Durable scheduler', 'ready', 'unknown', 'Scheduler heartbeat is healthy.', [], { schedulerStatus: input.schedulerStatus, schedulerHeartbeatAgeMs: schedulerAge }));
+
+    const queueStalled = queueDepth > 0 && runningWorkers === 0;
+    capabilities.push(queueStalled || activeLeases > 0 && runningWorkers === 0
+      ? capability(at, 'worker.loop', 'Worker loop', 'degraded', 'stale_runtime_state', 'Queued work or leases may be stuck without active workers.', [RECOVERY_ACTIONS.reconcileJobs], { queueDepth, runningWorkers, activeLeases })
+      : capability(at, 'worker.loop', 'Worker loop', 'ready', 'unknown', 'Worker loop has no stuck queue evidence.', [], { queueDepth, runningWorkers, activeLeases }));
+
+    capabilities.push(input.localBridgeRunning === false
+      ? capability(at, 'local.bridge', 'Local bridge', 'unavailable', 'local_recoverable', 'Local bridge is not running. Component restart recovery is not a supported Runtime action.', [RECOVERY_ACTIONS.probeAgain], { error: input.localBridgeError })
+      : capability(at, 'local.bridge', 'Local bridge', 'ready', 'unknown', 'Local bridge is available.', [], { running: input.localBridgeRunning }));
+  }
+
+  capabilities.push(input.connectorHealthy === false
+    ? capability(at, 'chatgpt.connector', 'ChatGPT connector', 'degraded', 'local_recoverable', 'Connector runtime state does not match the expected tool surface.', [RECOVERY_ACTIONS.probeAgain], { mismatch: input.connectorMismatch })
+    : input.connectorHealthy === true
+      ? capability(at, 'chatgpt.connector', 'ChatGPT connector', 'ready', 'unknown', 'Connector runtime state matches expected configuration.', [], { healthy: true })
+      : capability(at, 'chatgpt.connector', 'ChatGPT connector', 'unknown', 'unknown', 'Connector schema has not been verified by live MCP discovery.', [RECOVERY_ACTIONS.probeAgain]));
+
+  if (input.runtimeSourceCoherence) {
+    const source = input.runtimeSourceCoherence;
+    capabilities.push(source.ready
+      ? capability(at, 'runtime.source_coherence', 'Runtime source coherence', 'ready', 'unknown', source.summary ?? 'Runtime source snapshot matches the current Runtime source.', [], { code: source.code, reasons: source.reasons ?? [] })
+      : capability(at, 'runtime.source_coherence', 'Runtime source coherence', 'blocked', 'external_lifecycle_required', source.summary ?? 'Runtime source snapshot is missing or stale. The running Runtime cannot repair or restart its own lifecycle.', [], { code: source.code, reasons: source.reasons ?? [], lifecycleOwner: 'external_runtime_lifecycle' }));
+  }
+
+  if (!sharedHealth) {
+    capabilities.push(input.runtimeProjectionStale === true || input.runtimeProjectionPersisted === false
+      ? capability(at, 'runtime.projection', 'Runtime projection', 'degraded', 'stale_runtime_state', 'Runtime projection is stale or missing from persisted state.', [RECOVERY_ACTIONS.rebuildProjection], { stale: input.runtimeProjectionStale, persisted: input.runtimeProjectionPersisted })
+      : capability(at, 'runtime.projection', 'Runtime projection', 'ready', 'unknown', 'Runtime projection is available.', [], { stale: input.runtimeProjectionStale, persisted: input.runtimeProjectionPersisted }));
+  }
+
+  capabilities.push(input.contextProjectionStale === true
+    ? capability(at, 'context.projection', 'Context projection', 'degraded', 'stale_runtime_state', 'Controller context projection source identity is behind the current runtime projection.', [RECOVERY_ACTIONS.rebuildProjection], { stale: true, ageIsNotFailure: true })
+    : capability(at, 'context.projection', 'Context projection', 'ready', 'unknown', 'Controller context projection is usable; cache age is not a health failure.', [], { stale: input.contextProjectionStale, ageIsNotFailure: true }));
+
+  const storageClass = runtimeStorageClass(input);
+  if (input.runtimeStorageReady === false || (input.runtimeStorageWarnings ?? []).length > 0) {
+    const classifiedStorage = storageClass === 'unknown' ? 'runtime_storage_not_ready' : storageClass;
+    capabilities.push(capability(
+      at,
+      'runtime.storage',
+      'Runtime storage',
+      'blocked',
+      classifiedStorage,
+      'Runtime storage is not ready; ordinary execution may be unable to create or dispatch Local Jobs.',
+      runtimeStorageActions(classifiedStorage),
+      { ready: input.runtimeStorageReady, warnings: input.runtimeStorageWarnings ?? [] },
+    ));
+  }
+
+  capabilities.push(input.commandPreviewAvailable === false
+    ? capability(at, 'tool.command_preview', 'Command preview', 'blocked', 'policy_denied', 'Command preview is blocked or unavailable.', [RECOVERY_ACTIONS.probeAgain])
+    : capability(at, 'tool.command_preview', 'Command preview', 'ready', 'unknown', 'Command preview is available.'));
+
+  const recentClass = classifyRecentErrors(input);
+  capabilities.push(input.commandExecuteAvailable === false
+    ? capability(
+      at,
+      'tool.command_execute',
+      'Command execute',
+      'blocked',
+      recentClass === 'platform_blocked' ? 'platform_blocked' : recentClass === 'unknown' ? 'policy_denied' : recentClass,
+      recentClass === 'platform_blocked'
+        ? 'Command execute appears blocked before reaching forge. Do not restart-loop local services.'
+        : ['runtime_storage_not_ready', 'local_jobs_legacy_active', 'local_jobs_unreadable', 'local_jobs_reconciliation_required'].includes(recentClass)
+          ? 'Command execute is blocked by forge runtime storage; use the maintenance executor instead of repository_command_execute.'
+          : 'Command execute is blocked, denied, or unavailable.',
+      commandExecuteActions(recentClass),
+    )
+    : capability(at, 'tool.command_execute', 'Command execute', 'ready', 'unknown', 'Command execute is available.'));
+
+  capabilities.push(input.issueToolsAvailable === false
+    ? capability(at, 'tool.issue', 'Issue tools', 'blocked', recentClass, 'Issue tooling is blocked or unavailable.', suggestedActionsForClass(recentClass))
+    : capability(at, 'tool.issue', 'Issue tools', 'ready', 'unknown', 'Issue tooling is available.'));
+
+  capabilities.push(input.jobToolsAvailable === false
+    ? capability(at, 'tool.jobs', 'Job tools', 'blocked', recentClass, 'Job tooling is blocked or unavailable.', suggestedActionsForClass(recentClass))
+    : capability(at, 'tool.jobs', 'Job tools', 'ready', 'unknown', 'Job tooling is available.'));
+
+  const jobClass = failingJobClass(input);
+  if (jobClass !== 'unknown') {
+    capabilities.push(capability(at, 'recent.failures', 'Recent failures', 'degraded', jobClass, `Recent job failures classify as ${jobClass}.`, suggestedActionsForClass(jobClass), { localJobs: input.localJobs?.length ?? 0, executionJobs: input.executionJobs?.length ?? 0 }));
+  }
+
+  for (const plugin of input.pluginStates ?? []) {
+    const state = plugin.healthState ?? (plugin.ready ? 'ready' : plugin.enabled ? 'degraded' : 'disabled');
+    if (plugin.enabled === false) {
+      capabilities.push(capability(at, `plugin.${plugin.pluginId}`, `${plugin.pluginId} plugin`, 'degraded', 'user_action_required', 'Plugin is disabled.', [], { state }));
+    } else if (plugin.ready === true || state === 'ready') {
+      capabilities.push(capability(at, `plugin.${plugin.pluginId}`, `${plugin.pluginId} plugin`, 'ready', 'unknown', 'Plugin is ready.', [], { state }));
+    } else if ((plugin.errors ?? []).some((error) => classifyFailure(error) === 'auth_required')) {
+      capabilities.push(capability(at, `plugin.${plugin.pluginId}`, `${plugin.pluginId} plugin`, 'degraded', 'auth_required', 'Plugin requires authorization or token refresh.', [RECOVERY_ACTIONS.workspaceAuthLoginPrepare], { state, errors: plugin.errors }));
+    } else {
+      capabilities.push(capability(at, `plugin.${plugin.pluginId}`, `${plugin.pluginId} plugin`, 'degraded', 'plugin_configuration_error', 'Plugin is enabled but not healthy.', [], { state, errors: plugin.errors, warnings: plugin.warnings }));
+    }
+  }
+
+  if ((input.dirtyPaths ?? []).length > 0) {
+    capabilities.push(capability(at, 'worktree.dirty_paths', 'Dirty path conflict guard', 'degraded', 'dirty_worktree_conflict', 'Main worktree has dirty paths. Integration must not overwrite them.', [], { dirtyPaths: input.dirtyPaths }));
+  }
+
+  capabilities.push(capability(at, 'assistant.monitor', 'Assistant monitor', 'ready', 'unknown', 'Assistant monitor data is available for the local GUI.', [], input.assistant));
+
+  const states = countStates(capabilities);
+  const recommendedActions = dedupeActions(capabilities.flatMap((item) => item.suggestedActions));
+  const classes = capabilities.map((item) => item.class);
+  const platformBlocked = classes.includes('platform_blocked');
+  const topRisks = [...new Set(classes.filter((item) => item !== 'unknown'))].slice(0, 5);
+  const overallState: CapabilityState = states.blocked > 0
+    ? 'blocked'
+    : states.unavailable > 0
+      ? 'unavailable'
+      : states.degraded > 0
+        ? 'degraded'
+        : 'ready';
+  const externalLifecycleCapability = capabilities.find((item) => item.class === 'external_lifecycle_required' && item.state !== 'ready');
+  const externalLifecycleHandoff = externalLifecycleCapability ? {
+    owner: 'external_runtime_lifecycle' as const,
+    target: 'forge-runtime' as const,
+    reasonCode: input.runtimeSourceCoherence?.ready === false
+      ? input.runtimeSourceCoherence.code ?? 'RUNTIME_SOURCE_COHERENCE_FAILED'
+      : 'RUNTIME_LIFECYCLE_EXTERNAL_ACTION_REQUIRED',
+    summary: externalLifecycleCapability.reason,
+    requiredAction: 'restart_existing_single_runtime' as const,
+    constraints: [
+      'Operate on the existing single forge-runtime service only.',
+      'Do not start a second Runtime, component Runtime, restart coordinator, or rollout slot.',
+      'Do not mutate the source checkout as part of lifecycle recovery.',
+      'The currently running Runtime must not attempt to own its own restart.',
+    ],
+    verification: [
+      'The restarted Runtime publishes ready=true.',
+      'A startup Runtime source snapshot exists under Controller Home.',
+      'Runtime source coherence reports no drift against the current configured Runtime source.',
+      'Runtime/release ownership evidence identifies one active Runtime.',
+    ],
+  } : undefined;
+
+  return {
+    schemaVersion: 1,
+    generatedAt: at,
+    overallState,
+    fallbackRequired: platformBlocked || externalLifecycleHandoff !== undefined,
+    platformBlocked,
+    capabilities,
+    recommendedActions,
+    summary: {
+      ready: states.ready,
+      degraded: states.degraded,
+      blocked: states.blocked,
+      unavailable: states.unavailable,
+      unknown: states.unknown,
+      topRisks,
+      nextBestAction: recommendedActions[0],
+    },
+    externalLifecycleHandoff,
+    notes: externalLifecycleHandoff
+      ? ['Runtime lifecycle action is required outside the running Runtime. Use the existing single forge-runtime service only; no rollout, second Runtime, component restart, or source mutation.']
+      : platformBlocked
+        ? ['One or more calls appear blocked before reaching forge. Use patch handoff or narrower typed tools; do not infer a local Runtime lifecycle failure.']
+        : (input.runtimeStorageReady === false ? ['Runtime storage is not ready. Use runtime_maintenance_status/runtime_maintenance_apply; do not try to repair repository_command_execute with repository_command_execute.'] : []),
+    runtimeHealth: sharedHealth,
+    runtimeOperationalView: input.runtimeOperationalView,
+  };
+}

package/src/runtime/recovery/store.ts

@@ -0,0 +1,35 @@
+import { mkdirSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { repositoryControllerRoot } from '../../cli/repositories/controller-home';
+import { readJsonFile, sanitizeFileComponent, writeJsonAtomic } from '../shared/json-files';
+import type { RecoveryAuditRecord } from './types';
+
+function recoveryRoot(controllerHome: string, repoId: string): string {
+  const root = join(repositoryControllerRoot(controllerHome, repoId), 'recovery');
+  mkdirSync(root, { recursive: true });
+  return root;
+}
+
+function auditRoot(controllerHome: string, repoId: string): string {
+  const root = join(recoveryRoot(controllerHome, repoId), 'audit');
+  mkdirSync(root, { recursive: true });
+  return root;
+}
+
+export function writeRecoveryAuditRecord(controllerHome: string, repoId: string, record: RecoveryAuditRecord): RecoveryAuditRecord {
+  writeJsonAtomic(join(auditRoot(controllerHome, repoId), `${sanitizeFileComponent(record.id)}.json`), record);
+  return record;
+}
+
+export function listRecoveryAuditRecords(controllerHome: string, repoId: string, limit = 20): RecoveryAuditRecord[] {
+  const root = auditRoot(controllerHome, repoId);
+  return readdirSync(root)
+    .filter((name) => name.endsWith('.json'))
+    .sort()
+    .reverse()
+    .slice(0, Math.max(1, Math.min(Math.trunc(limit), 100)))
+    .flatMap((name) => {
+      try { return [readJsonFile<RecoveryAuditRecord>(join(root, name))]; }
+      catch { return []; }
+    });
+}

package/src/runtime/recovery/types.ts

@@ -0,0 +1,175 @@
+export type CapabilityState = 'ready' | 'degraded' | 'blocked' | 'unavailable' | 'unknown';
+
+export type RecoveryClass =
+  | 'local_recoverable'
+  | 'auth_required'
+  | 'policy_denied'
+  | 'platform_blocked'
+  | 'dirty_worktree_conflict'
+  | 'stale_runtime_state'
+  | 'external_lifecycle_required'
+  | 'runtime_storage_not_ready'
+  | 'browser_domain_grant_required'
+  | 'external_filesystem_grant_required'
+  | 'local_jobs_legacy_active'
+  | 'local_jobs_unreadable'
+  | 'local_jobs_reconciliation_required'
+  | 'maintenance_executor_required'
+  | 'agent_runtime_failure'
+  | 'plugin_configuration_error'
+  | 'source_defect_suspected'
+  | 'transient_probe_timeout'
+  | 'user_action_required'
+  | 'unknown';
+
+export type RecoveryRisk = 'readonly' | 'low' | 'medium' | 'high' | 'destructive';
+export type RecoveryConfirmation = 'none' | 'authorization' | 'strong_confirmation';
+import type { RuntimeHealthEvaluation, RuntimeOperationalView } from '../health';
+
+export interface RecoveryEvidence {
+  source: string;
+  message: string;
+  at: string;
+  details?: Record<string, unknown>;
+}
+
+export interface RecoveryActionDescriptor {
+  id: string;
+  title: string;
+  description: string;
+  class: RecoveryClass;
+  risk: RecoveryRisk;
+  confirmation: RecoveryConfirmation;
+  localOnly: boolean;
+  boundedTo: string[];
+}
+
+export interface CapabilityStatus {
+  id: string;
+  label: string;
+  state: CapabilityState;
+  class: RecoveryClass;
+  reason: string;
+  evidence: RecoveryEvidence[];
+  suggestedActions: RecoveryActionDescriptor[];
+}
+
+export interface RuntimeSourceCoherenceEvidence {
+  ready: boolean;
+  code?: string;
+  reasons?: string[];
+  summary?: string;
+}
+
+export interface ExternalRuntimeLifecycleHandoff {
+  owner: 'external_runtime_lifecycle';
+  target: 'forge-runtime';
+  reasonCode: string;
+  summary: string;
+  requiredAction: 'restart_existing_single_runtime';
+  constraints: string[];
+  verification: string[];
+}
+
+export interface CapabilityRecoveryInput {
+  generatedAt?: string;
+  daemonStatus?: string;
+  daemonError?: string;
+  schedulerStatus?: string;
+  schedulerHeartbeatAgeMs?: number;
+  schedulerDispatchHeartbeatAgeMs?: number;
+  queueDepth?: number;
+  runningWorkers?: number;
+  activeLeases?: number;
+  localBridgeRunning?: boolean;
+  localBridgeError?: string;
+  connectorHealthy?: boolean;
+  connectorMismatch?: string;
+  runtimeProjectionStale?: boolean;
+  runtimeProjectionPersisted?: boolean;
+  runtimeSourceCoherence?: RuntimeSourceCoherenceEvidence;
+  contextProjectionStale?: boolean;
+  /** Shared health classification used by lifecycle/MCP/recovery consumers. */
+  runtimeHealth?: RuntimeHealthEvaluation;
+  /** Shared current-attention/history view; persisted jobs and handoffs remain authoritative. */
+  runtimeOperationalView?: RuntimeOperationalView;
+  commandPreviewAvailable?: boolean;
+  commandExecuteAvailable?: boolean;
+  issueToolsAvailable?: boolean;
+  jobToolsAvailable?: boolean;
+  checksAvailable?: boolean;
+  runtimeStorageReady?: boolean;
+  runtimeStorageWarnings?: string[];
+  pluginStates?: Array<{ pluginId: string; enabled: boolean; healthState?: string; ready?: boolean; errors?: string[]; warnings?: string[] }>;
+  recentErrors?: string[];
+  dirtyPaths?: string[];
+  localJobs?: Array<{ status?: string; error?: string; updatedAt?: string }>;
+  executionJobs?: Array<{ status?: string; error?: unknown; updatedAt?: string; operation?: string }>;
+  assistant?: {
+    inboxCount?: number;
+    routineCount?: number;
+    memoryCount?: number;
+  };
+}
+
+export interface CapabilityRecoverySummary {
+  ready: number;
+  degraded: number;
+  blocked: number;
+  unavailable: number;
+  unknown: number;
+  topRisks: RecoveryClass[];
+  nextBestAction?: RecoveryActionDescriptor;
+}
+
+export interface CapabilityRecoverySnapshot {
+  schemaVersion: 1;
+  generatedAt: string;
+  overallState: CapabilityState;
+  fallbackRequired: boolean;
+  platformBlocked: boolean;
+  capabilities: CapabilityStatus[];
+  recommendedActions: RecoveryActionDescriptor[];
+  summary: CapabilityRecoverySummary;
+  externalLifecycleHandoff?: ExternalRuntimeLifecycleHandoff;
+  notes: string[];
+  runtimeHealth?: RuntimeHealthEvaluation;
+  runtimeOperationalView?: RuntimeOperationalView;
+}
+
+export interface RecoveryAuditRecord {
+  schemaVersion: 1;
+  id: string;
+  at: string;
+  actor: string;
+  actionId: string;
+  risk: RecoveryRisk;
+  confirmation: RecoveryConfirmation;
+  result: 'planned' | 'skipped' | 'succeeded' | 'failed';
+  reason: string;
+  affectedPaths: string[];
+  evidence: RecoveryEvidence[];
+}
+
+export interface PatchHandoffArtifact {
+  schemaVersion: 1;
+  id: string;
+  createdAt: string;
+  issueId?: string;
+  taskId?: string;
+  baseHead: string;
+  branch: string;
+  touchedPaths: string[];
+  diffHash: string;
+  checks: Array<{ id: string; status: 'passed' | 'failed' | 'skipped'; summary?: string }>;
+  provenance: {
+    actor: string;
+    workspace: 'isolated_worktree' | 'sandbox';
+    source: string;
+  };
+  integration: {
+    safeToApply: boolean;
+    conflicts: string[];
+    notes: string[];
+  };
+}

package/src/runtime/release/identity.ts

@@ -0,0 +1,101 @@
+import { existsSync, readFileSync, realpathSync } from 'fs';
+import { resolve } from 'path';
+import { repositoryIdentity } from '../../cli/controller/runtime-config';
+import { stableCheckoutId } from '../../cli/repositories/identity';
+
+export interface ReleaseIdentityBinding {
+  releasePath: string;
+  releaseId?: string;
+  releaseRevision?: string;
+  sourceCommit?: string;
+  cleanWorkspace: boolean;
+}
+
+interface ReleaseManifestIdentity {
+  releaseId?: string;
+  releaseRevision?: string;
+  sourceCommit?: string;
+  cleanWorkspace?: boolean;
+}
+
+function text(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+function readManifest(releasePath: string): ReleaseManifestIdentity | undefined {
+  const path = resolve(releasePath, 'manifest.json');
+  if (!existsSync(path)) return undefined;
+  try {
+    const manifest = JSON.parse(readFileSync(path, 'utf8')) as Record<string, unknown>;
+    return {
+      releaseId: text(manifest.releaseId),
+      releaseRevision: text(manifest.releaseRevision),
+      sourceCommit: text(manifest.sourceCommit),
+      cleanWorkspace: typeof manifest.cleanWorkspace === 'boolean' ? manifest.cleanWorkspace : undefined,
+    };
+  } catch {
+    throw new Error(`RUNTIME_RELEASE_MANIFEST_INVALID: ${path}`);
+  }
+}
+
+export function readReleaseIdentityBindingFromEnv(env: NodeJS.ProcessEnv = process.env): ReleaseIdentityBinding | undefined {
+  const configuredPath = env.FORGE_RELEASE_PATH?.trim();
+  if (!configuredPath) return undefined;
+  const releasePath = existsSync(configuredPath) ? realpathSync(configuredPath) : resolve(configuredPath);
+  const manifest = readManifest(releasePath);
+  return {
+    releasePath,
+    releaseId: env.FORGE_RELEASE_ID?.trim() || manifest?.releaseId,
+    releaseRevision: env.FORGE_RELEASE_REVISION?.trim() || manifest?.releaseRevision || env.FORGE_RELEASE_ID?.trim(),
+    sourceCommit: env.FORGE_RELEASE_SOURCE_COMMIT?.trim() || manifest?.sourceCommit,
+    cleanWorkspace: env.FORGE_RELEASE_CLEAN_WORKSPACE
+      ? env.FORGE_RELEASE_CLEAN_WORKSPACE !== 'false'
+      : manifest?.cleanWorkspace !== false,
+  };
+}
+
+export function resolveManagedRuntimeSourceIdentity(options: {
+  runtimeRoot: string;
+  env?: NodeJS.ProcessEnv;
+}): {
+  repoId: string;
+  checkoutId: string;
+  repoRoot: string;
+  canonicalRoot: string;
+  branch: null;
+  commit?: string;
+  releaseRevision?: string;
+  defaultBranch: string;
+  defaultBranchCommit?: string;
+  dirty: boolean;
+  observedAt: string;
+} | undefined {
+  const binding = readReleaseIdentityBindingFromEnv(options.env ?? process.env);
+  if (!binding) return undefined;
+  let requestedRoot: string;
+  try {
+    requestedRoot = existsSync(options.runtimeRoot) ? realpathSync(options.runtimeRoot) : resolve(options.runtimeRoot);
+  } catch {
+    requestedRoot = resolve(options.runtimeRoot);
+  }
+  // An inherited FORGE_RELEASE_* binding describes the hosting immutable
+  // Runtime, not every arbitrary source/repository path inspected by that
+  // process or its children. Only apply the binding when the caller is
+  // explicitly collecting identity for that exact release root.
+  if (requestedRoot !== binding.releasePath) return undefined;
+  const canonicalRoot = binding.releasePath;
+  const repoId = `repo_${repositoryIdentity(canonicalRoot)}`;
+  return {
+    repoId,
+    checkoutId: stableCheckoutId(repoId, canonicalRoot),
+    repoRoot: canonicalRoot,
+    canonicalRoot,
+    branch: null,
+    commit: binding.sourceCommit,
+    releaseRevision: binding.releaseRevision,
+    defaultBranch: 'main',
+    defaultBranchCommit: binding.sourceCommit,
+    dirty: !binding.cleanWorkspace,
+    observedAt: new Date().toISOString(),
+  };
+}