@moretea-labs/forge 1.6.0 → 1.7.0

package/src/runtime/execution/process-runtime/command-facade.ts

@@ -1,19 +1,26 @@
 /**
- * repository_command_execute → Unified Process Runtime.
+ * repository_command_execute → three explicit execution lanes.
  *
- * Short readonly / focused commands: Direct (wait briefly, return result).
- * Longer local build/test: Managed (same spawn, return handle).
- * release / remote / non-idempotent: Durable (caller keeps ExecutionJob path).
+ * - Ephemeral Direct: bounded ordinary reads and commands that finish inside
+ *   the interactive budget.
+ * - Lightweight Managed: the same local command remains alive in memory and
+ *   returns a bounded handle, without SQLite, Lease, or recovery membership.
+ * - Durable: explicit Work/external/release boundaries only.
  */
 
 import type { RepositoryRecord } from '../../../cli/repositories/types';
-import { classifyRepositoryCommand } from '../../../cli/repositories/command-classifier';
+import { repositoryGitStatus } from '../../../cli/repositories/structured-git';
+import { classifyRepositoryCommand, fixedShellWrapperCommand } from '../../../cli/repositories/command-classifier';
 import {
   executeRepositoryCommandAsync,
   executeRepositoryReadOnlyCommandDirect,
   type RepositoryCommandExecution,
 } from '../../../cli/repositories/command-executor';
 import { normalizeRepositoryCommand } from '../../../cli/repositories/command-normalization';
+import {
+  assertRepositoryCommandNoPluginExecutionBypass,
+  assertRepositoryCommandStableHostIdentity,
+} from '../../../cli/repositories/command-scope';
 import { claimsForRepositoryCommand, scopeResourceClaims, toProcessClaims } from './resource-claims';
 import {
   spawnManagedProcess,
@@ -27,6 +34,15 @@ import { DEFAULT_INTERACTIVE_WAIT_MS } from './types';
 import { durationAwareInteractiveWaitMs } from './interactive-admission';
 import { isFocusedCheckCommand } from '../thin-harness/execution-router';
 import { assertExecutionIdentity, type ResolvedExecutionIdentity } from '../../control-plane/execution/execution-identity';
+import { readWorkHandle, transitionWorkHandle } from '../../control-plane/execution/work-handle-store';
+import {
+  cancelLightweightProcess,
+  getLightweightProcessHandle,
+  isLightweightProcessId,
+  readLightweightProcessLogs,
+  startLightweightRepositoryCommand,
+  waitForLightweightProcess,
+} from './lightweight-managed';
 
 export type RepositoryCommandRoute =
   | 'process_direct'
@@ -76,6 +92,19 @@ export interface RepositoryCommandProcessResult {
     projectionUpdateCount: number;
   };
   suggestedOperation?: string;
+  externalEffect?: {
+    outcome: 'not_started' | 'outcome_unknown';
+    replayPolicy: 'never_auto_retry';
+    reconciliation: string;
+  };
+  executionMetrics?: {
+    lane: 'ephemeral_direct' | 'lightweight_managed' | 'durable_process' | 'durable_external';
+    preSpawnHarnessMs?: number;
+    childDurationMs?: number;
+    interactiveReturnMs?: number;
+    durableWrites: number;
+    leaseOperations: number;
+  };
 }
 
 const emptyEffects = {
@@ -85,6 +114,154 @@ const emptyEffects = {
   projectionUpdateCount: 0,
 };
 
+export type WorkHeadSettlementReason =
+  | 'settled'
+  | 'no_work'
+  | 'command_not_successful'
+  | 'work_handle_missing'
+  | 'identity_mismatch'
+  | 'terminal_handle'
+  | 'branch_changed'
+  | 'head_unavailable'
+  | 'head_unchanged'
+  | 'concurrent_lifecycle_write';
+
+export interface WorkHeadSettlementResult {
+  settled: boolean;
+  reason: WorkHeadSettlementReason;
+  previousHead?: string;
+  currentHead?: string;
+}
+
+/**
+ * Settle the one legitimate post-command Work HEAD transition without weakening
+ * the pre-command execution identity fence. The command has already been
+ * admitted only if repo/checkout/branch/expectedHead matched the WorkHandle.
+ * After success, adopt the exact current HEAD only while the same checkout and
+ * branch still own the Work. CAS failure is a bounded no-op: finalization keeps
+ * failing closed instead of accepting a concurrent lifecycle writer.
+ */
+export function settleWorkHandleExpectedHeadAfterRepositoryCommand(input: {
+  controllerHome: string;
+  repository: RepositoryRecord;
+  executionIdentity: ResolvedExecutionIdentity;
+  workId?: string;
+  ok?: boolean;
+  cancelled?: boolean;
+  timedOut?: boolean;
+}): WorkHeadSettlementResult {
+  const workId = input.workId?.trim();
+  if (!workId) return { settled: false, reason: 'no_work' };
+  if (input.ok !== true || input.cancelled === true || input.timedOut === true) {
+    return { settled: false, reason: 'command_not_successful' };
+  }
+  const handle = readWorkHandle(input.controllerHome, input.repository.repoId, workId);
+  if (!handle) return { settled: false, reason: 'work_handle_missing' };
+  if (
+    handle.repositoryId !== input.executionIdentity.repositoryId
+    || handle.checkoutId !== input.executionIdentity.checkoutId
+    || handle.workId !== input.executionIdentity.workId
+  ) return { settled: false, reason: 'identity_mismatch' };
+  if (handle.state === 'merged' || handle.state === 'cleaned' || handle.state === 'failed_terminal_cleanup') {
+    return { settled: false, reason: 'terminal_handle' };
+  }
+  const status = repositoryGitStatus(input.repository);
+  if (!status.branch || status.branch !== handle.branch) {
+    return { settled: false, reason: 'branch_changed', previousHead: handle.expectedHead, currentHead: status.head ?? undefined };
+  }
+  const currentHead = status.head?.trim();
+  if (!currentHead) return { settled: false, reason: 'head_unavailable', previousHead: handle.expectedHead };
+  if (currentHead === handle.expectedHead) {
+    return { settled: false, reason: 'head_unchanged', previousHead: handle.expectedHead, currentHead };
+  }
+  try {
+    transitionWorkHandle(input.controllerHome, handle, handle.state, { expectedHead: currentHead });
+    return { settled: true, reason: 'settled', previousHead: handle.expectedHead, currentHead };
+  } catch (error) {
+    if (error instanceof Error && error.message.includes('CONTROL_PLANE_REVISION_CONFLICT')) {
+      return { settled: false, reason: 'concurrent_lifecycle_write', previousHead: handle.expectedHead, currentHead };
+    }
+    throw error;
+  }
+}
+
+const STANDALONE_RECOVERY_LIFECYCLE_COMMANDS = new Set([
+  'restart-runtime',
+  'bootstrap-cutover',
+  'restart-connector',
+  'stage-and-activate-runtime',
+  'recover',
+  'rollback',
+  'restart',
+  'activate-runtime',
+  'install',
+]);
+
+function commandBasename(value: string): string {
+  return value.split(/[\\/]/).pop()?.toLowerCase() ?? '';
+}
+
+function recoveryLifecycleFromArgv(executable: string, args: readonly string[]): string | undefined {
+  const executableName = commandBasename(executable);
+  let recoveryArgs: readonly string[];
+  if (executableName === 'forge' || executableName === 'forge.mjs') {
+    recoveryArgs = args;
+  } else if (['bun', 'node', 'nodejs'].includes(executableName)) {
+    const scriptIndex = args.findIndex((arg) => {
+      const name = commandBasename(arg);
+      return name === 'forge' || name === 'forge.mjs';
+    });
+    if (scriptIndex < 0) return undefined;
+    recoveryArgs = args.slice(scriptIndex + 1);
+  } else {
+    return undefined;
+  }
+  if (recoveryArgs[0] !== 'recovery') return undefined;
+  const subcommand = recoveryArgs[1]?.toLowerCase();
+  return subcommand && STANDALONE_RECOVERY_LIFECYCLE_COMMANDS.has(subcommand) ? subcommand : undefined;
+}
+
+function recoveryLifecycleFromShell(shellCommand: string): string | undefined {
+  const match = /^\s*(?:exec\s+)?(?:(?:\S*[\\/])?(?:bun|node|nodejs)\s+)?(?:\S*[\\/])?forge(?:\.mjs)?\s+recovery\s+([a-z-]+)\b/i.exec(shellCommand);
+  const subcommand = match?.[1]?.toLowerCase();
+  return subcommand && STANDALONE_RECOVERY_LIFECYCLE_COMMANDS.has(subcommand) ? subcommand : undefined;
+}
+
+function repositoryCommandRecoveryLifecycle(command: string | readonly string[]): string | undefined {
+  const normalized = normalizeRepositoryCommand(command);
+  if (normalized.kind === 'shell') return recoveryLifecycleFromShell(normalized.shellCommand ?? '');
+  const direct = recoveryLifecycleFromArgv(normalized.executable ?? '', normalized.args ?? []);
+  if (direct) return direct;
+  const argv = normalized.value as string[];
+  const wrapped = fixedShellWrapperCommand(argv);
+  return wrapped ? recoveryLifecycleFromShell(wrapped) : undefined;
+}
+
+function rawGitCommitRequiresExplicitPathScope(command: string | readonly string[]): boolean {
+  const normalized = normalizeRepositoryCommand(command);
+  if (normalized.kind === 'shell') {
+    return /(?:^|[;&|]\s*)\s*git\s+commit\b/i.test(normalized.shellCommand ?? '');
+  }
+  const executable = commandBasename(normalized.executable ?? '');
+  const args = [...(normalized.args ?? [])];
+  if (executable !== 'git') {
+    const wrapped = fixedShellWrapperCommand(normalized.value as string[]);
+    return wrapped ? /(?:^|[;&|]\s*)\s*git\s+commit\b/i.test(wrapped) : false;
+  }
+  let index = 0;
+  while (index < args.length && args[index]?.startsWith('-')) {
+    const option = args[index]!;
+    if (['-c', '-C', '--git-dir', '--work-tree', '--namespace'].includes(option)) index += 2;
+    else index += 1;
+  }
+  if (args[index]?.toLowerCase() !== 'commit') return false;
+  const commitArgs = args.slice(index + 1);
+  const pathSeparator = commitArgs.indexOf('--');
+  const hasExplicitOnly = commitArgs.includes('--only') || commitArgs.includes('-o');
+  const paths = pathSeparator >= 0 ? commitArgs.slice(pathSeparator + 1).filter(Boolean) : [];
+  return !(hasExplicitOnly && paths.length > 0);
+}
+
 function toProcessCommand(command: string | readonly string[], cwd: string): ProcessCommandSpec {
   const normalized = normalizeRepositoryCommand(command);
   if (normalized.kind === 'argv') {
@@ -113,37 +290,53 @@ export function classifyRepositoryCommandRoute(
     timeoutMs?: number;
   } = {},
 ): { route: RepositoryCommandRoute; reason: string } {
+  if (repositoryCommandRecoveryLifecycle(command)) {
+    return { route: 'reject', reason: 'standalone_recovery_lifecycle_required' };
+  }
+  if (rawGitCommitRequiresExplicitPathScope(command)) {
+    return { route: 'reject', reason: 'git_commit_requires_explicit_path_scope' };
+  }
   if (options.forceDurable) {
     return { route: 'durable', reason: 'force_durable_or_async' };
   }
   const classification = classifyRepositoryCommand(command, options.defaultBranch);
-  // ExecutionJobs are retired. Authorized local destructive/remote-risk commands
-  // still execute through Process Runtime; SuperController owns retry/replay policy.
+  const text = Array.isArray(command) ? command.join(' ') : String(command);
+  // Classification chooses scheduling/receipt granularity only; it does not
+  // decide whether a scoped repository command is allowed to run. Known remote
+  // or broadly effectful commands use managed Process Runtime so existing
+  // resource claims and receipts can serialize/reconcile them. Unknown commands
+  // still execute instead of requiring a new allow rule.
   if (classification.risk === 'remote_write' || classification.risk === 'destructive') {
-    return {
-      route: 'process_managed',
-      reason: `risk_${classification.risk}_via_process_runtime`,
-    };
+    return { route: 'process_managed', reason: 'effectful_command_managed' };
   }
-  // release / rollback style commands
-  const text = Array.isArray(command) ? command.join(' ') : String(command);
-  if (/\b(?:gh\s+release\s+(?:create|delete|edit|upload)|git\s+push|npm\s+publish)\b/i.test(text)) {
-    return { route: 'durable', reason: 'release_or_remote_mutation' };
+  const argv = Array.isArray(command) ? command : [];
+  const executable = argv[0]?.split(/[\\/]/).pop()?.toLowerCase();
+  const shellWrapped = Boolean(executable
+    && ['bash', 'sh', 'zsh', 'fish', 'dash', 'cmd', 'powershell', 'pwsh'].includes(executable)
+    && argv.slice(1).some((arg) => ['-c', '-lc', '/c', '-Command'].includes(arg)));
+  const wrappedShellCommand = shellWrapped ? fixedShellWrapperCommand(argv) : undefined;
+  const wrapsInlineInterpreter = Boolean(wrappedShellCommand
+    && /^\s*(?:exec\s+)?(?:node|nodejs|bun|deno|ruby|perl|python\d*)\b[^\n]*(?:\s-c\b|\s-e\b|\s--eval\b)/i.test(wrappedShellCommand));
+  const wrapsObviousExternalIo = Boolean(wrappedShellCommand
+    && /\b(?:curl|wget|ssh|scp|sftp|ftp|telnet|nc|ncat)\b|https?:\/\//i.test(wrappedShellCommand));
+  if (shellWrapped && classification.risk !== 'readonly') {
+    if (wrapsObviousExternalIo && !wrapsInlineInterpreter) {
+      return { route: 'process_managed', reason: 'shell_wrapper_requires_managed_boundary' };
+    }
+    return { route: 'process_direct', reason: 'lightweight_local_shell_wrapper' };
+  }
+  if (executable && ['node', 'nodejs', 'bun', 'deno', 'ruby', 'perl', 'python', 'python3'].includes(executable)
+    && argv.slice(1).some((arg) => ['-c', '-e', '--eval'].includes(arg))) {
+    return { route: 'process_direct', reason: 'lightweight_local_inline_interpreter' };
   }
   if (classification.risk === 'readonly') {
-    // Short readonly → direct. Only an *explicit* long timeout upgrades to managed.
-    if (typeof options.timeoutMs === 'number' && options.timeoutMs > 30_000) {
-      return { route: 'process_managed', reason: 'readonly_long_timeout' };
-    }
     return { route: 'process_direct', reason: 'readonly_fast_path' };
   }
   // workspace_write / build-test
   if (isFocusedCheckCommand(command) || /\b(?:test|typecheck|lint|build|check)\b/i.test(text)) {
-    return { route: 'process_managed', reason: 'local_build_or_test' };
+    return { route: 'process_direct', reason: 'ephemeral_local_build_or_test' };
   }
-  // Unknown mutating local command remains one local Managed Process. Timeout is
-  // a process lifecycle budget and must never select a different architecture.
-  return { route: 'process_managed', reason: 'local_workspace_mutation' };
+  return { route: 'process_direct', reason: 'ephemeral_local_workspace_mutation' };
 }
 
 /**
@@ -153,18 +346,38 @@ export function classifyRepositoryCommandRoute(
 export async function executeRepositoryCommandViaProcessRuntime(
   input: RepositoryCommandProcessInput,
 ): Promise<RepositoryCommandProcessResult> {
+  // Process Runtime intentionally supports some command forms that the legacy
+  // repository executor rejects (for example bounded typed eval). Keep that
+  // surface, but fail closed before routing any macOS TCC-sensitive host tool:
+  // a release-specific forge-runtime executable must never own those grants.
+  assertRepositoryCommandStableHostIdentity(input.command);
+  assertRepositoryCommandNoPluginExecutionBypass(input.command);
   const decision = classifyRepositoryCommandRoute(input.command, {
     forceDurable: input.forceDurable,
+    // Work identity is continuity/audit metadata only. It must not change the
+    // execution lane of an otherwise ordinary local repository command.
     defaultBranch: input.repository.defaultBranch,
     timeoutMs: input.timeoutMs,
   });
-
-  if (decision.route === 'durable' || decision.route === 'reject') {
+  // Only explicit lifecycle/delivery rejection or a caller-requested durable
+  // mode stops here. Ordinary command effects, including remote writes, execute
+  // through Process Runtime; classification does not become an authorization gate.
+  if (decision.route === 'reject' || decision.route === 'durable') {
     return {
       route: decision.route,
       reason: decision.reason,
       durableSideEffects: emptyEffects,
-      suggestedOperation: 'repository_command_execute via Durable Work / Local Job',
+      suggestedOperation: decision.reason === 'standalone_recovery_lifecycle_required'
+        ? 'Use the standalone Forge Recovery connector for canonical Runtime/connector lifecycle operations.'
+        : 'repository_command_execute via Durable Work / Local Job',
+      externalEffect: decision.route === 'durable'
+        ? {
+            outcome: 'not_started',
+            replayPolicy: 'never_auto_retry',
+            reconciliation: 'If a separate external controller later loses the result after dispatch, report outcome_unknown and inspect remote state before any retry.',
+          }
+        : undefined,
+      executionMetrics: { lane: 'durable_external', durableWrites: 0, leaseOperations: 0 },
     };
   }
 
@@ -191,12 +404,12 @@ export async function executeRepositoryCommandViaProcessRuntime(
     };
   }
 
-  // A short readonly command owns no durable Process/Lease state. Validate the
-  // same immutable repository identity first, then execute with the bounded
-  // non-persistent reader. This keeps reads available while a stale/passive
-  // Runtime remains correctly fenced from Controller writes.
+  // Ordinary local commands own no durable Process/Lease state. Validate the
+  // immutable repository identity first, then execute through the authorized
+  // non-persistent repository executor. Runtime/release durability is not a
+  // command-execution tax.
   const canonicalCommand = normalizeRepositoryCommand(input.command);
-  if (decision.route === 'process_direct' && canonicalCommand.kind === 'argv') {
+  if (decision.route === 'process_direct') {
     assertExecutionIdentity({
       controllerHome: input.controllerHome,
       identity: executionIdentity,
@@ -204,14 +417,68 @@ export async function executeRepositoryCommandViaProcessRuntime(
       requestedRepoId: input.repository.repoId,
       requestedCheckoutId: input.repository.activeCheckoutId,
     });
-    const direct = await executeRepositoryReadOnlyCommandDirect(input.repository, {
+    const directInput = {
       command: input.command,
       cwd: input.cwd,
-      timeoutMs: Math.min(input.timeoutMs ?? 30_000, 30_000),
+      timeoutMs: input.timeoutMs,
       maxOutputBytes: input.maxOutputBytes,
       signal: input.signal,
       allowNonGitWorkspace: executionIdentity.authority === 'ephemeral_workspace',
-    });
+      allowOpaqueLocalScript: decision.reason === 'lightweight_local_shell_wrapper'
+        || decision.reason === 'lightweight_local_inline_interpreter',
+    };
+    const readonly = canonicalCommand.kind === 'argv'
+      && classifyRepositoryCommand(input.command, input.repository.defaultBranch).risk === 'readonly';
+    if (!readonly) {
+      const deferLongPreparation = decision.reason === 'ephemeral_local_build_or_test';
+      const interactiveWaitMs = deferLongPreparation
+        ? 0
+        : durationAwareInteractiveWaitMs(
+            input.command,
+            input.returnHandleImmediately ? 0 : input.interactiveWaitMs,
+            Math.min(DEFAULT_INTERACTIVE_WAIT_MS, 250),
+          );
+      const timeoutMs = Math.max(
+        interactiveWaitMs + 1,
+        Math.min(input.timeoutMs ?? 15 * 60_000, 24 * 60 * 60_000),
+      );
+      const lightweight = await startLightweightRepositoryCommand({
+        controllerHome: input.controllerHome,
+        repository: input.repository,
+        execution: directInput,
+        interactiveWaitMs,
+        timeoutMs,
+        maxOutputBytes: input.maxOutputBytes,
+        workId: input.workId,
+        commandId: input.commandId ?? input.requestId,
+        deferStart: deferLongPreparation,
+        reuseActiveEquivalent: deferLongPreparation,
+        onCompleted: (result) => {
+          settleWorkHandleExpectedHeadAfterRepositoryCommand({
+            controllerHome: input.controllerHome,
+            repository: input.repository,
+            executionIdentity,
+            workId: input.workId,
+            ok: result.ok,
+            cancelled: result.cancelled,
+            timedOut: result.timedOut,
+          });
+        },
+      });
+      const handle = lightweight.handle;
+      return {
+        route: handle.completed ? 'process_direct' : 'process_managed',
+        reason: handle.completed ? decision.reason : 'interactive_budget_exceeded_lightweight_handle',
+        process: handle,
+        ok: handle.ok,
+        exitCode: handle.exitCode,
+        stdout: handle.stdout,
+        stderr: handle.stderr,
+        durableSideEffects: emptyEffects,
+        executionMetrics: lightweight.metrics,
+      };
+    }
+    const direct = await executeRepositoryReadOnlyCommandDirect(input.repository, directInput);
     return {
       route: 'process_direct',
       reason: decision.reason,
@@ -224,6 +491,7 @@ export async function executeRepositoryCommandViaProcessRuntime(
       authorizationDecision: direct.authorizationDecision,
       approvalRequestId: direct.approvalRequestId,
       durableSideEffects: emptyEffects,
+      executionMetrics: { lane: 'ephemeral_direct', durableWrites: 0, leaseOperations: 0 },
     };
   }
 
@@ -313,12 +581,49 @@ export async function executeRepositoryCommandViaProcessRuntime(
     stdout: handle.stdout,
     stderr: handle.stderr,
     durableSideEffects: handle.durableSideEffects,
+    executionMetrics: {
+      lane: 'durable_process',
+      interactiveReturnMs: interactiveWaitMs,
+      durableWrites: 1,
+      leaseOperations: claims.length,
+    },
   };
 }
 
-export {
-  getProcessHandle as getRepositoryCommandProcess,
-  waitForProcess as waitRepositoryCommandProcess,
-  cancelProcess as cancelRepositoryCommandProcess,
-  readProcessLogs as readRepositoryCommandProcessLogs,
-};
+export function getRepositoryCommandProcess(controllerHome: string, repoId: string, processId: string): ProcessHandle | undefined {
+  return isLightweightProcessId(processId)
+    ? getLightweightProcessHandle(controllerHome, repoId, processId)
+    : getProcessHandle(controllerHome, repoId, processId);
+}
+
+export function waitRepositoryCommandProcess(
+  controllerHome: string,
+  repoId: string,
+  processId: string,
+  options?: Parameters<typeof waitForProcess>[3],
+): Promise<ProcessHandle> {
+  return isLightweightProcessId(processId)
+    ? waitForLightweightProcess(controllerHome, repoId, processId, options)
+    : waitForProcess(controllerHome, repoId, processId, options);
+}
+
+export function cancelRepositoryCommandProcess(
+  controllerHome: string,
+  repoId: string,
+  processId: string,
+): Promise<ProcessHandle> {
+  return isLightweightProcessId(processId)
+    ? cancelLightweightProcess(controllerHome, repoId, processId)
+    : cancelProcess(controllerHome, repoId, processId);
+}
+
+export function readRepositoryCommandProcessLogs(
+  controllerHome: string,
+  repoId: string,
+  processId: string,
+  maxBytes?: number,
+) {
+  return isLightweightProcessId(processId)
+    ? readLightweightProcessLogs(controllerHome, repoId, processId, maxBytes)
+    : readProcessLogs(controllerHome, repoId, processId, maxBytes);
+}

package/src/runtime/execution/process-runtime/gc.ts

@@ -9,8 +9,9 @@
 import { existsSync, readFileSync, readdirSync, unlinkSync, statSync } from 'fs';
 import { join } from 'path';
 import { ensureRepositoryControllerLayout, repositoryControllerRoot } from '../../../cli/repositories/controller-home';
-import { listActiveProcessIds } from './store';
-import type { ProcessRuntimeStatus } from './types';
+import { getProcessRecord, listActiveProcessIds } from './store';
+import { reconcileStaleManagedProcessForMaintenance } from './runtime';
+import { isManagedProcessActive, type ProcessRuntimeStatus } from './types';
 import { assertRuntimeMayWrite } from '../../root/write-fence';
 import { isProcessAlive } from '../../shared/process-tree';
 
@@ -21,6 +22,7 @@ const TERMINAL: ReadonlySet<ProcessRuntimeStatus> = new Set([
   'cancelled',
   'orphaned',
   'completed_unknown',
+  'unknown',
 ]);
 
 export interface ProcessGcOptions {
@@ -32,6 +34,10 @@ export interface ProcessGcOptions {
   maxTerminalRecords?: number;
   /** Also delete associated log/receipt files. */
   deleteLogs?: boolean;
+  /** Minimum age before an active record is eligible for evidence-based stale reconciliation (default 5m). */
+  staleActiveMinAgeMs?: number;
+  /** Max stale active records to reconcile in one selected-repository GC pass (default 100). */
+  maxStaleReconciliations?: number;
 }
 
 export interface ProcessGcResult {
@@ -39,6 +45,7 @@ export interface ProcessGcResult {
   removedRecords: number;
   removedLogs: number;
   skippedActive: number;
+  reconciledStaleActive: number;
   /** Legacy/corrupt records without enough terminal proof are preserved. */
   skippedInvalid?: number;
   error?: string;
@@ -125,28 +132,52 @@ export function gcTerminalProcesses(options: ProcessGcOptions): ProcessGcResult
         removedRecords: 0,
         removedLogs: 0,
         skippedActive: 0,
+        reconciledStaleActive: 0,
         error: `writer_fenced:${fence.reason ?? 'denied'}`,
       };
     }
 
     const maxAgeMs = options.maxAgeMs ?? 7 * 24 * 60 * 60_000;
     const maxTerminal = options.maxTerminalRecords ?? 500;
+    const staleActiveMinAgeMs = Math.max(1_000, options.staleActiveMinAgeMs ?? 5 * 60_000);
+    const maxStaleReconciliations = Math.max(0, options.maxStaleReconciliations ?? 100);
     const root = processesDir(options.controllerHome, options.repoId);
     if (!existsSync(root)) {
-      return { ok: true, removedRecords: 0, removedLogs: 0, skippedActive: 0 };
+      return { ok: true, removedRecords: 0, removedLogs: 0, skippedActive: 0, reconciledStaleActive: 0 };
     }
 
     const active = new Set(listActiveProcessIds(options.controllerHome, options.repoId));
     const terminal: Array<{ processId: string; finishedAt: number; path: string; reusableCheckEvidence: boolean }> = [];
     let skippedActive = 0;
     let skippedInvalid = 0;
+    let reconciledStaleActive = 0;
+    const nowMs = Date.now();
 
     for (const name of readdirSync(root)) {
       if (!name.endsWith('.json') || name === 'active-index.json') continue;
       const processId = name.slice(0, -'.json'.length);
       if (active.has(processId)) {
-        skippedActive += 1;
-        continue;
+        let record = getProcessRecord(options.controllerHome, options.repoId, processId);
+        if (!record) {
+          skippedActive += 1;
+          continue;
+        }
+        if (isManagedProcessActive(record) && reconciledStaleActive < maxStaleReconciliations) {
+          const reconciled = reconcileStaleManagedProcessForMaintenance(
+            options.controllerHome,
+            options.repoId,
+            processId,
+            { nowMs, minAgeMs: staleActiveMinAgeMs },
+          );
+          if (reconciled) {
+            if (isManagedProcessActive(record) && !isManagedProcessActive(reconciled)) reconciledStaleActive += 1;
+            record = reconciled;
+          }
+        }
+        if (isManagedProcessActive(record)) {
+          skippedActive += 1;
+          continue;
+        }
       }
       const metadata = readProcessGcMetadata(join(root, name));
       if (!metadata?.status) {
@@ -194,13 +225,14 @@ export function gcTerminalProcesses(options: ProcessGcOptions): ProcessGcResult
       }
     }
 
-    return { ok: true, removedRecords, removedLogs, skippedActive, skippedInvalid };
+    return { ok: true, removedRecords, removedLogs, skippedActive, reconciledStaleActive, skippedInvalid };
   } catch (error) {
     return {
       ok: false,
       removedRecords: 0,
       removedLogs: 0,
       skippedActive: 0,
+      reconciledStaleActive: 0,
       error: error instanceof Error ? error.message : String(error),
     };
   }