@moretea-labs/forge 1.8.1 → 1.8.2

package/src/runtime/plugins/local-system-adapter.ts

@@ -43,10 +43,6 @@ import type {
   AssistantPluginPermissionScope,
 } from './types';
 import { AssistantPluginError } from './errors';
-import {
-  classifyRepositoryCommand,
-  classifyRepositoryCommandReplay,
-} from '../../cli/repositories/command-classifier';
 import {
   assertCommandPathOperandsStayInRepository,
   assertRepositoryCommandInputAllowed,
@@ -58,7 +54,6 @@ const PLUGIN_ID = 'local_system';
 const MAX_OUTPUT_BYTES = 64 * 1024;
 const MAX_TEXT_CHARS = 100_000;
 const MAX_DIRECTORY_ENTRIES = 200;
-const TARGET_SAFE_FILESYSTEM_MUTATORS = new Set(['touch', 'mkdir', 'cp', 'mv', 'install', 'tee', 'truncate']);
 const PROJECT_SCRIPT_RUNTIMES = new Set(['node', 'bun', 'python3', 'ruby', 'bash', 'sh']);
 const AUTO_OPEN_DENIED_EXTENSIONS = new Set([
   '.command', '.sh', '.bash', '.zsh', '.fish', '.tool',
@@ -140,14 +135,6 @@ function optionalString(args: Record<string, unknown>, key: string): string | un
   return value || undefined;
 }
 
-function requiredStringArray(args: Record<string, unknown>, key: string): string[] {
-  const value = args[key];
-  if (!Array.isArray(value) || value.length === 0 || value.some((entry) => typeof entry !== 'string' || !entry.trim())) {
-    throw new AssistantPluginError('PLUGIN_ACTION_ARGUMENT_INVALID', `${key} must be a non-empty string array.`, { retryable: false });
-  }
-  return value.map((entry) => String(entry));
-}
-
 function optionalStringArray(args: Record<string, unknown>, key: string): string[] {
   const value = args[key];
   if (value === undefined) return [];
@@ -831,7 +818,6 @@ function actions(): AssistantPluginActionDescriptor[] {
     { actionId: 'delete_file', title: 'Delete file', description: 'Delete one exact regular file below an authorized read-write target. Arbitrary recursive or directory deletion is never exposed.', readOnly: false, risk: 'destructive', confirmation: 'strong_confirmation', requiredConfirmationText: 'delete-local-system-file', defaultTimeoutMs: 15_000, cancellable: true, idempotent: false, scopes: ['local-system.files.write'], resourceClaims: controllerWrite, argumentsSchema: { type: 'object', properties: targetProperties, required: ['target_key', 'path'], additionalProperties: false } },
     { actionId: 'delete_empty_directory', title: 'Delete empty directory', description: 'Delete one exact empty directory below an authorized read-write target. Target roots and recursive directory deletion are never allowed.', readOnly: false, risk: 'destructive', confirmation: 'strong_confirmation', requiredConfirmationText: 'delete-local-system-empty-directory', defaultTimeoutMs: 15_000, cancellable: true, idempotent: false, scopes: ['local-system.files.write'], resourceClaims: controllerWrite, argumentsSchema: { type: 'object', properties: targetProperties, required: ['target_key', 'path'], additionalProperties: false } },
     { actionId: 'initialize_git', title: 'Initialize local Git repository', description: 'Run only git init inside an authorized read-write target without registering it in Repository Registry.', readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 30_000, cancellable: true, idempotent: true, scopes: ['local-system.files.write'], resourceClaims: controllerWrite, argumentsSchema: { type: 'object', properties: { target_key: { type: 'string' }, cwd: { type: 'string' }, initial_branch: { type: 'string' } }, required: ['target_key'], additionalProperties: false } },
-    { actionId: 'execute_command', title: 'Execute target command', description: 'Execute one bounded typed-argv command inside an authorized filesystem target. This is the narrow target-scoped alternative to broad ForgeInstance process_exec: shell strings, target escapes, destructive/remote writes, and Git mutations other than the dedicated initialize_git action are denied.', readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 30_000, cancellable: true, idempotent: false, scopes: ['local-system.files.read', 'local-system.files.write'], resourceClaims: controllerWrite, argumentsSchema: { type: 'object', properties: { target_key: { type: 'string' }, command: { type: 'array', items: { type: 'string' } }, cwd: { type: 'string' }, max_output_bytes: { type: 'number' } }, required: ['target_key', 'command'], additionalProperties: false } },
     { actionId: 'execute_project_script', title: 'Execute verified project script', description: 'Execute one exact script below an authorized read-write target through a fixed interpreter after its SHA-256 digest and strong confirmation match. Eval flags and shell command strings are never accepted.', readOnly: false, risk: 'destructive', confirmation: 'strong_confirmation', requiredConfirmationText: 'execute-local-system-project-script', defaultTimeoutMs: 30_000, cancellable: true, idempotent: false, scopes: ['local-system.files.read', 'local-system.files.write'], resourceClaims: controllerWrite, argumentsSchema: { type: 'object', properties: { target_key: { type: 'string' }, runtime: { type: 'string', enum: ['node', 'bun', 'python3', 'ruby', 'bash', 'sh'] }, script_path: { type: 'string' }, expected_sha256: { type: 'string' }, arguments: { type: 'array', items: { type: 'string' } }, cwd: { type: 'string' }, max_output_bytes: { type: 'number' } }, required: ['target_key', 'runtime', 'script_path', 'expected_sha256'], additionalProperties: false } },
     { actionId: 'create_directory', title: 'Create directory', description: 'Create a directory below an authorized target without leaving that root.', readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 15_000, cancellable: true, idempotent: true, scopes: ['local-system.files.write'], resourceClaims: controllerWrite, argumentsSchema: { type: 'object', properties: targetProperties, required: ['target_key', 'path'], additionalProperties: false } },
     { actionId: 'copy_file', title: 'Copy file', description: 'Copy a file between authorized targets without overwriting.', readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 30_000, cancellable: true, idempotent: false, scopes: ['local-system.files.write'], resourceClaims: controllerWrite, argumentsSchema: { type: 'object', properties: { source_target_key: { type: 'string' }, source_path: { type: 'string' }, destination_target_key: { type: 'string' }, destination_path: { type: 'string' } }, required: ['source_target_key', 'source_path', 'destination_target_key', 'destination_path'], additionalProperties: false } },
@@ -879,7 +865,7 @@ function capabilities(): AssistantPluginCapability[] {
     { capabilityId: 'local-system-recovery-tunnel-repair', title: 'Managed standalone Recovery tunnel repair', description: 'Repair only the installed Recovery public tunnel through the existing Recovery tunnel repair authority when the Recovery transport itself is unreachable.', scopes: ['local-system.process'], actions: ['repair_standalone_recovery_tunnel'] },
     { capabilityId: 'local-system-workflow-supervisor-browser-adapter', title: 'Workflow Supervisor browser adapter', description: 'Inspect or install the stateless Chrome adapter projection used by the Goal-level Workflow Supervisor authority.', scopes: ['local-system.browser-adapter'], actions: ['workflow_supervisor_browser_adapter_status', 'install_workflow_supervisor_browser_adapter'] },
     { capabilityId: 'local-system-open', title: 'Open local applications and files', description: 'Open applications and authorized files without arbitrary shell access.', scopes: ['local-system.open'], actions: ['open_application', 'reveal_in_finder', 'open_file'] },
-    { capabilityId: 'local-system-files', title: 'Authorized local files', description: 'Use expiring target grants for bounded local file operations and typed-argv commands without repository registration.', scopes: ['local-system.files.read', 'local-system.files.write'], actions: ['list_targets', 'authorize_target', 'revoke_target', 'list_directory', 'read_text', 'write_text', 'delete_file', 'delete_empty_directory', 'initialize_git', 'execute_command', 'execute_project_script', 'create_directory', 'copy_file', 'move_file', 'rename_file'] },
+    { capabilityId: 'local-system-files', title: 'Authorized local files', description: 'Use expiring target grants for bounded local file operations without repository registration; terminal commands use the single execute_command MCP tool.', scopes: ['local-system.files.read', 'local-system.files.write'], actions: ['list_targets', 'authorize_target', 'revoke_target', 'list_directory', 'read_text', 'write_text', 'delete_file', 'delete_empty_directory', 'initialize_git', 'execute_project_script', 'create_directory', 'copy_file', 'move_file', 'rename_file'] },
   ];
 }
 
@@ -1093,90 +1079,6 @@ export async function executeLocalSystemPluginAction(input: AssistantPluginActio
         return { initialized: true, targetKey: resolved.target.targetKey, workspaceId: resolved.target.workspaceId, cwd: resolved.relativePath || '.', repositoryRegistered: false, command, stdout: executed.stdout, stderr: executed.stderr };
       });
     }
-    case 'execute_command': {
-      const targetKey = requiredString(input.args, 'target_key');
-      const argv = requiredStringArray(input.args, 'command');
-      const canonical = assertRepositoryCommandInputAllowed(argv);
-      if (canonical.kind !== 'argv') {
-        throw new AssistantPluginError('LOCAL_SYSTEM_COMMAND_TYPED_ARGV_REQUIRED', 'Target commands must use typed argv and cannot use a shell string.', { retryable: false });
-      }
-      const classification = classifyRepositoryCommand(canonical);
-      if (classification.risk === 'remote_write' || classification.risk === 'destructive') {
-        throw new AssistantPluginError('LOCAL_SYSTEM_COMMAND_RISK_DENIED', `Target command risk ${classification.risk} is not supported without repository registration.`, { retryable: false });
-      }
-      const executable = canonical.executable!.split(/[\\/]/).at(-1)?.toLowerCase() ?? '';
-      if (executable === 'git' && classification.risk !== 'readonly') {
-        throw new AssistantPluginError('LOCAL_SYSTEM_GIT_MUTATION_REQUIRES_REPOSITORY', 'Git mutations require a registered repository/checkout so refs and worktree ownership remain fenced.', { retryable: false });
-      }
-      if (classification.risk === 'workspace_write') {
-        const replay = classifyRepositoryCommandReplay(canonical);
-        const boundedFilesystemMutation = TARGET_SAFE_FILESYSTEM_MUTATORS.has(executable);
-        if (!boundedFilesystemMutation && !replay.replayable) {
-          throw new AssistantPluginError(
-            'LOCAL_SYSTEM_COMMAND_REPOSITORY_REQUIRED',
-            `Target command ${executable || '<unknown>'} has unbounded or unclassified side effects; register/promote the target before executing it.`,
-            { retryable: false },
-          );
-        }
-      }
-      const operation: WorkspaceTargetOperation = classification.risk === 'readonly' ? 'read' : 'write';
-      const execute = async () => {
-        let resolved;
-        try {
-          resolved = resolveWorkspaceTargetCwd(
-            input.controllerHome,
-            targetKey,
-            requestOwnerScope(input),
-            optionalString(input.args, 'cwd') ?? '.',
-            operation,
-            currentDate(),
-          );
-        } catch (error) {
-          return rethrowTargetError(error);
-        }
-        assertCommandPathOperandsStayInRepository(canonical, resolved.path, resolved.root, []);
-        const maxOutputBytes = Math.max(1_024, Math.min(Math.trunc(Number(input.args.max_output_bytes ?? MAX_OUTPUT_BYTES)), 1024 * 1024));
-        const timeoutMs = Math.max(1_000, Math.min(Math.trunc(input.timeoutMs ?? 30_000), 30_000));
-        const executed = await runCanonicalCommand(canonical, resolved.path, timeoutMs, maxOutputBytes, { signal: input.signal });
-        if (!executed.ok) {
-          const code = executed.timedOut
-            ? 'LOCAL_SYSTEM_COMMAND_TIMED_OUT'
-            : executed.cancelled
-              ? 'LOCAL_SYSTEM_COMMAND_CANCELLED'
-              : 'LOCAL_SYSTEM_COMMAND_FAILED';
-          const message = executed.stderr.trim()
-            || executed.stdout.trim()
-            || `Target command exited with code ${executed.exitCode}.`;
-          throw new AssistantPluginError(code, bounded(message, maxOutputBytes).content, {
-            retryable: executed.timedOut,
-            details: {
-              command: argv,
-              exitCode: executed.exitCode,
-              timedOut: executed.timedOut,
-              cancelled: executed.cancelled,
-            },
-          });
-        }
-        return {
-          targetKey: resolved.target.targetKey,
-          workspaceId: resolved.target.workspaceId,
-          identityFingerprint: resolved.target.identityFingerprint,
-          repositoryRegistered: false,
-          cwd: resolved.relativePath || '.',
-          command: argv,
-          classification,
-          ok: executed.ok,
-          exitCode: executed.exitCode,
-          timedOut: executed.timedOut,
-          cancelled: executed.cancelled,
-          stdout: executed.stdout,
-          stderr: executed.stderr,
-        };
-      };
-      return operation === 'write'
-        ? await withTargetMutation(input, [targetKey], execute)
-        : await execute();
-    }
     case 'execute_project_script': {
       const targetKey = requiredString(input.args, 'target_key');
       const runtime = requiredString(input.args, 'runtime').toLowerCase();

package/src/runtime/plugins/store.ts

@@ -2,9 +2,10 @@ import { createHash, randomUUID } from 'crypto';
 import { join } from 'path';
 import type { RepositoryRecord } from '../../cli/repositories/types';
 import { CONTROLLER_SCOPE_REPO_ID, FORGE_INSTANCE_SCOPE_KEY, controllerSystemRoot, ensureControllerHome, repositoryControllerRoot } from '../../cli/repositories/controller-home';
-import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, rmSync } from 'fs';
+import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync } from 'fs';
 import type { ExecutionJob, ResourceClaimSpec } from '../execution/jobs/types';
 import { appendRuntimeEvent } from '../evidence/event-ledger';
+import { redactSensitiveText, redactSensitiveValue } from '../evidence/sensitive-output';
 import { readJsonFile, sanitizeFileComponent, writeJsonAtomic } from '../shared/json-files';
 import { createFirstPartyPluginAdapterMap } from './first-party-registry';
 import { reconcileFirstPartyExternalPluginRegistration, reconcileFirstPartyExternalPluginRegistrations } from './first-party-external-registration';
@@ -444,6 +445,20 @@ export function migrateRepositoryPluginConfigLegacyFiles(
     join(repository.canonicalRoot, '.repo-harness', 'plugins'),
   ];
   mkdirSync(targetRoot, { recursive: true });
+  // Upgrade an already-adopted v1/v2 Controller Home config in place. The
+  // adapter owns schema semantics; this store remains the sole file writer.
+  const browserTarget = repositoryPluginConfigPath({ controllerHome, repoId: repository.repoId }, 'browser');
+  const browserNormalizer = PLUGIN_ADAPTERS.get('browser')?.normalizeLegacyConfig;
+  if (!browserNormalizer) throw new Error('PLUGIN_CONFIG_MIGRATION_INVALID: browser schema owner missing');
+  if (existsSync(browserTarget)) {
+    const stat = lstatSync(browserTarget);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('PLUGIN_CONFIG_AUTHORITY_PATH_INVALID: browser config');
+    let current: unknown;
+    try { current = JSON.parse(readFileSync(browserTarget, 'utf8')); }
+    catch { throw new Error('PLUGIN_CONFIG_AUTHORITY_INVALID: browser config JSON'); }
+    const normalized = browserNormalizer(current);
+    if ((current as { schemaVersion?: unknown }).schemaVersion !== 3) writeJsonAtomic(browserTarget, normalized);
+  }
   for (const legacyRoot of legacyRoots) {
     if (!existsSync(legacyRoot)) continue;
     const stat = lstatSync(legacyRoot);
@@ -461,7 +476,16 @@ export function migrateRepositoryPluginConfigLegacyFiles(
       const sourceStat = lstatSync(source);
       if (sourceStat.isSymbolicLink() || !sourceStat.isFile()) continue;
       const target = repositoryPluginConfigPath({ controllerHome, repoId: repository.repoId }, pluginId);
-      if (!existsSync(target)) cpSync(source, target, { force: false, errorOnExist: false });
+      if (!existsSync(target)) {
+        if (pluginId === 'browser') {
+          let parsed: unknown;
+          try { parsed = JSON.parse(readFileSync(source, 'utf8')); }
+          catch { throw new Error('PLUGIN_CONFIG_MIGRATION_INVALID: legacy browser JSON'); }
+          writeJsonAtomic(target, browserNormalizer(parsed));
+        } else {
+          cpSync(source, target, { force: false, errorOnExist: false });
+        }
+      }
       rmSync(source, { force: true });
     }
     if (readdirSync(legacyRoot).length === 0) rmSync(legacyRoot, { recursive: true, force: true });
@@ -475,7 +499,6 @@ function computeManifest(
   pluginId: string,
   resolvedAdapter?: AssistantPluginAdapter,
 ): AssistantPluginManifest {
-  migrateRepositoryPluginConfigLegacyFiles(controllerHome, repository);
   const adapter = resolvedAdapter ?? resolvePluginAdapter(controllerHome, pluginId);
   if (!adapter || !adapterMatchesRepository(adapter, repository)) throw new Error(`PLUGIN_NOT_FOUND: ${pluginId}`);
   const previous = readStoredManifest(controllerHome, repository.repoId, pluginId);
@@ -678,7 +701,18 @@ function enforceConfirmation(action: AssistantPluginActionDescriptor, request: A
   // Ordinary authorization is delegated to the host AI/tool permission model.
   // Forge keeps only the explicit strong-confirmation boundary for
   // destructive or irreversible plugin operations.
-  if (action.confirmation === 'none' || action.confirmation === 'authorization') return;
+  if (action.confirmation === 'none') return;
+  if (action.confirmation === 'authorization') {
+    if (action.requiredConfirmationText) {
+      if (request.confirmAuthorization !== true) {
+        throw new Error(`PLUGIN_CONFIRMATION_REQUIRED: ${request.pluginId}/${request.actionId} requires confirmAuthorization=true`);
+      }
+      if (request.confirmationText !== action.requiredConfirmationText) {
+        throw new Error(`PLUGIN_CONFIRMATION_TEXT_REQUIRED: provide confirmationText=${action.requiredConfirmationText}`);
+      }
+    }
+    return;
+  }
   if (action.confirmation === 'strong_confirmation') {
     if (request.confirmAuthorization !== true) {
       throw new Error(`PLUGIN_CONFIRMATION_REQUIRED: ${request.pluginId}/${request.actionId} requires confirmAuthorization=true`);
@@ -922,6 +956,7 @@ export function syncAssistantPluginRegistry(
   repository: RepositoryRecord,
 ): { manifests: AssistantPluginManifest[]; index: AssistantPluginRegistryIndex } {
   invalidateAssistantPluginManifestCache(controllerHome, repository.repoId);
+  migrateRepositoryPluginConfigLegacyFiles(controllerHome, repository);
   const manifests = listAssistantPluginManifests(controllerHome, repository, { forceRefresh: true });
   for (const manifest of manifests) {
     writeJsonAtomic(manifestPath(controllerHome, repository.repoId, manifest.pluginId), manifest);
@@ -939,6 +974,7 @@ export function syncAssistantPluginManifest(
   pluginId: string,
 ): { manifest: AssistantPluginManifest; index: AssistantPluginRegistryIndex } {
   invalidateAssistantPluginManifestCache(controllerHome, repository.repoId, pluginId);
+  migrateRepositoryPluginConfigLegacyFiles(controllerHome, repository);
   const manifest = computeManifest(controllerHome, repository, pluginId);
   writeJsonAtomic(manifestPath(controllerHome, repository.repoId, manifest.pluginId), manifest);
   markControllerContextProjectionDirty(repository.canonicalRoot, `plugin:${pluginId}:synced`);
@@ -1180,7 +1216,7 @@ export interface PluginActionReceipt {
   origin?: { surface: string; actor?: string; correlationId?: string };
   authorization?: PluginActionAuthorizationEvidence;
   result?: Record<string, unknown>;
-  error?: { code: string; message: string };
+  error?: { code: string; message: string; retryable?: boolean; details?: Record<string, unknown> };
   /** True for a compact direct-read observation; it is evidence, never an effect-completion authority. */
   observationOnly?: boolean;
   /** SHA-256 of the direct-read result. Result content is intentionally not persisted for observation-only receipts. */
@@ -1345,6 +1381,21 @@ function attributedWorkForPluginAction(
   return work;
 }
 
+/** Reuse the canonical Work binding check before a Process request ID is reserved. */
+export function preflightPluginActionWorkBinding(
+  controllerHome: string,
+  pluginScope: { kind: 'controller' } | { kind: 'repository'; repository: RepositoryRecord },
+  action: AssistantPluginActionDescriptor,
+  request: AssistantPluginActionRequest,
+): void {
+  if (!request.workId?.trim()) return;
+  const scope = pluginScope.kind === 'controller'
+    ? controllerPluginActionScope(controllerHome)
+    : repositoryPluginActionScope(pluginScope.repository);
+  if (action.risk === 'remote_write') remoteEffectWorkForPluginAction(controllerHome, scope, action, request);
+  else attributedWorkForPluginAction(controllerHome, scope, action, request);
+}
+
 function bindLocalEffectReceiptToAttributedWork(
   controllerHome: string,
   scope: PluginActionScopeContext,
@@ -1669,6 +1720,13 @@ async function submitPluginAction(
       }
     }
 
+    if (action.requiresExplicitCapabilityGrant && !activeAuthorizationGrant) {
+      throw new AssistantPluginError(
+        'PLUGIN_CAPABILITY_GRANT_REQUIRED',
+        `${manifest.pluginId}/${action.actionId} requires an explicit reusable capability grant for its exact target. Run the dedicated authorization action first.`,
+      );
+    }
+
     const result = await withAssistantPluginResourceLeases(
       controllerHome,
       scope,
@@ -1820,8 +1878,23 @@ async function submitPluginAction(
       ? error.effectOutcome
       : 'failed';
     const outcomeUnknown = effectOutcome === 'outcome_unknown';
+    const failure: NonNullable<PluginActionReceipt['error']> = {
+      code,
+      message: redactSensitiveText(message).text,
+      ...(isAssistantPluginError(error) ? { retryable: error.retryable } : {}),
+    };
+    // Error evidence stays compact; oversized provider diagnostics must not
+    // turn failure settlement into an unbounded persistence write.
+    if (isAssistantPluginError(error) && error.details) {
+      try {
+        const details = redactSensitiveValue(error.details).value;
+        if (Buffer.byteLength(JSON.stringify(details), 'utf8') <= 8_192) failure.details = details;
+      } catch {
+        // Non-JSON provider diagnostics cannot override the settled failure.
+      }
+    }
     const outcomeResult = outcomeUnknown
-      ? { outcome: 'outcome_unknown', error: { code, message } }
+      ? { outcome: 'outcome_unknown', error: failure }
       : undefined;
     if (boundRemoteWork) {
       appendWorkEvidence({ controllerHome, repoId: workAttributionRepoId(scope, request) }, boundRemoteWork.workId, {
@@ -1851,7 +1924,7 @@ async function submitPluginAction(
       origin: request.origin,
       authorization,
       ...(outcomeResult ? { result: outcomeResult } : {}),
-      error: { code, message },
+      error: failure,
     };
     writeJsonAtomic(pluginActionReceiptPath(controllerHome, scope.scopeKey, receiptId), receipt);
     writeJsonAtomic(requestPath, {

package/src/runtime/plugins/types.ts

@@ -50,6 +50,8 @@ export interface AssistantPluginActionDescriptor {
   readOnly: boolean;
   risk: AssistantPluginActionRisk;
   confirmation: AssistantPluginActionConfirmation;
+  /** Requires an existing explicit reusable grant; this action cannot implicitly create its own grant. */
+  requiresExplicitCapabilityGrant?: boolean;
   requiredConfirmationText?: string;
   defaultTimeoutMs: number;
   cancellable: boolean;
@@ -194,6 +196,8 @@ export interface AssistantPluginAdapter {
   /** Internal adapters remain exactly addressable by trusted composition but are omitted from normal user-facing plugin listings. */
   exposure?: AssistantPluginExposure;
   buildManifest(previousRevision?: number, previousUpdatedAt?: string, repoRoot?: string, context?: AssistantPluginBuildContext): AssistantPluginManifest;
+  /** Pure plugin-owned schema conversion/validation; the config store alone commits migrated bytes. */
+  normalizeLegacyConfig?(raw: unknown): object;
   /** Resolve an exact stable resource identity for reusable authorization-class actions. */
   resolveAuthorizationContext?(input: AssistantPluginActionExecutionInput): Promise<AssistantPluginAuthorizationContext | undefined>;
   executeAction(input: AssistantPluginActionExecutionInput): Promise<Record<string, unknown>>;

package/src/runtime/projections/git-status-sampler.ts

@@ -1,7 +1,7 @@
 import { join } from 'path';
 import { repositoryControllerRoot } from '../../cli/repositories/controller-home';
 import { selectRepositoryCheckout } from '../../cli/repositories/registry';
-import type { RepositoryGitStatusSnapshot } from '../../cli/repositories/structured-git';
+import { splitRepositoryGitStatus, type RepositoryGitStatusSnapshot } from '../../cli/repositories/structured-git';
 import type { RepositoryRecord } from '../../cli/repositories/types';
 import { runBoundedGit } from '../execution/thin-harness/async-process';
 import { readJsonFile, sanitizeFileComponent, writeJsonAtomic } from '../shared/json-files';
@@ -23,23 +23,6 @@ function samplePath(controllerHome: string, repoId: string, checkoutId: string):
 const GIT_STATUS_SAMPLE_TIMEOUT_MS = 5_000;
 const GIT_STATUS_SAMPLE_MAX_BYTES = 512 * 1024;
 
-function splitStatus(porcelain: string): Pick<RepositoryGitStatusSnapshot, 'staged' | 'unstaged' | 'untracked'> {
-  const staged: string[] = [];
-  const unstaged: string[] = [];
-  const untracked: string[] = [];
-  for (const line of porcelain.split(/\r?\n/)) {
-    if (!line || line.startsWith('## ')) continue;
-    const code = line.slice(0, 2);
-    const path = line.slice(3).trim();
-    if (code === '??') untracked.push(path);
-    else {
-      if (code[0] !== ' ' && code[0] !== '?') staged.push(path);
-      if (code[1] !== ' ' && code[1] !== '?') unstaged.push(path);
-    }
-  }
-  return { staged, unstaged, untracked };
-}
-
 async function gitSample(repository: RepositoryRecord, args: readonly string[], maxOutputBytes = GIT_STATUS_SAMPLE_MAX_BYTES) {
   return runBoundedGit(repository.canonicalRoot, args, {
     timeoutMs: GIT_STATUS_SAMPLE_TIMEOUT_MS,
@@ -63,7 +46,7 @@ export async function writeRepositoryGitStatusSample(
     throw new Error(`GIT_STATUS_SAMPLE_FAILED: ${porcelainResult.stderr || `exit ${porcelainResult.exitCode}`}`);
   }
   const porcelain = porcelainResult.stdout;
-  const split = splitStatus(porcelain);
+  const split = splitRepositoryGitStatus(porcelain);
   const sample: RepositoryGitStatusSample = {
     repoId: repository.repoId,
     checkoutId: repository.activeCheckoutId,

package/src/runtime/recovery/actions.ts

@@ -44,7 +44,7 @@ export const RECOVERY_ACTIONS = {
   localJobsReconcile: {
     id: 'recovery.local_jobs_reconcile',
     title: 'Reconcile Local Jobs',
-    description: 'Terminalize stale active Local Jobs and rebuild the Local Bridge active index without using repository_command_execute.',
+    description: 'Terminalize stale active Local Jobs and rebuild the Local Bridge active index without invoking execute_command.',
     class: 'local_jobs_reconciliation_required',
     risk: 'low',
     confirmation: 'authorization',

package/src/runtime/recovery/lifecycle-inventory.ts

@@ -169,7 +169,7 @@ export const RUNTIME_LIFECYCLE_INVENTORY: readonly RuntimeLifecycleClassDefiniti
     retentionCapacity: 'Global maximum, lease expiry and absolute lifetime bound stream-only sessions.',
     cleanupAuthority: 'MCP transport registry lifecycle.',
     recoverySemantics: 'Closing transport state never cancels or completes a durably accepted Job.',
-    closureStatus: 'existing_bounded', evidencePaths: ['docs/architecture/modules/controller-runtime/transport-lifecycle.md','src/cli/mcp/transports'],
+    closureStatus: 'existing_bounded', evidencePaths: ['docs/architecture/modules/controller-runtime/transport-lifecycle.md','adapters/mcp/transports'],
   }),
   lifecycle({
     id: 'browser_session_profile', owner: 'Browser session/provider authority', scope: 'provider', dataClass: 'provider_artifact',
@@ -241,16 +241,6 @@ export const RUNTIME_LIFECYCLE_INVENTORY: readonly RuntimeLifecycleClassDefiniti
     recoverySemantics: 'Quarantine remains diagnostic evidence, never a shadow active authority; legacy symlinks are relocated without traversal, and repeated maintenance is idempotent and fail-closed on unreadable evidence.',
     closureStatus: 'existing_bounded', evidencePaths: ['src/runtime/recovery/quarantine-retention.ts','src/runtime/recovery/maintenance-executor.ts','src/runtime/recovery/local-jobs-repair.ts','tests/runtime/capability-recovery.test.ts'],
   }),
-  lifecycle({
-    id: 'codegraph_cache', owner: 'Context / CodeGraph cache lifecycle', scope: 'repository', dataClass: 'cache',
-    storage: 'Controller Home tool-cache/codegraph or explicit external cache root',
-    terminalCondition: 'Index is stale, superseded, repository-retired or evicted as rebuildable cache.',
-    activeProtection: 'Only a live process-scoped Forge locator fences Controller Home cache deletion; unreadable, truncated, or ambiguous locator evidence fails closed. Raw source remains authority when cache is missing/stale.',
-    retentionCapacity: 'Forge-owned Controller Home indexes use a 7-day default idle grace, 512 MiB per-repository cap, 2 GiB Controller aggregate cap, and bounded oldest-first scan/removal budgets. Inactive caches may be rebuilt and evicted under age or capacity pressure; explicit external cache roots remain outside Forge cleanup authority.',
-    cleanupAuthority: 'Central Runtime cleanup owns rebuildable Controller Home CodeGraph eviction; no semantic authority is deleted and non-owned/symlink entries fail closed.',
-    recoverySemantics: 'Missing/stale cache degrades explicitly to lexical/raw-source evidence and rebuilds on demand; removal is idempotent and bounded by the shared cleanup budget.',
-    closureStatus: 'existing_bounded', evidencePaths: ['src/runtime/context/codegraph-cache-boundary.ts','src/runtime/control-plane/codegraph-cache-retention.ts','src/runtime/control-plane/runtime-cleanup.ts','tests/runtime/codegraph-cache-retention.test.ts'],
-  }),
   lifecycle({
     id: 'operational_memory', owner: 'Kernel Memory shadow reducer', scope: 'controller', dataClass: 'derived',
     storage: 'Controller Home derived operational Memory records backed by retained Process evidence',

package/src/runtime/recovery/probe.ts

@@ -205,7 +205,7 @@ export function buildCapabilityRecoverySnapshot(input: CapabilityRecoveryInput):
       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 by forge runtime storage; use the maintenance executor instead of execute_command.'
           : 'Command execute is blocked, denied, or unavailable.',
       commandExecuteActions(recentClass),
     )
@@ -300,7 +300,7 @@ export function buildCapabilityRecoverySnapshot(input: CapabilityRecoveryInput):
       ? ['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.'] : []),
+        : (input.runtimeStorageReady === false ? ['Runtime storage is not ready. Use runtime_maintenance_status/runtime_maintenance_apply; do not try to repair execute_command with execute_command.'] : []),
     runtimeHealth: sharedHealth,
     runtimeOperationalView: input.runtimeOperationalView,
   };

package/src/runtime/release/release-coordinator.ts

@@ -145,7 +145,12 @@ export function decideConfiguredRuntimeReleaseReconciliation(
   const sessions = completeRuntimeReleaseSessions(controllerHome);
   const active = sessions.filter((session) => !releaseSessionIsTerminal(session));
   const session = coordinatorSession(active);
-  if (session) {
+  // A single soaking predecessor remains rollback authority, but inability to
+  // certify it must not forever prevent a newer immutable source revision from
+  // preparing its own Candidate B. Two active sessions are allowed only by the
+  // existing exact soaking-predecessor/successor placement contract.
+  const onlySoakingPredecessor = active.length === 1 && session?.phase === 'soaking';
+  if (session && !onlySoakingPredecessor) {
     return { required: true, reason: 'active_session', action: runtimeReleaseActionForSession(session), session };
   }
 
@@ -153,12 +158,16 @@ export function decideConfiguredRuntimeReleaseReconciliation(
   // ReleaseSession can progress entirely from its durable authority without
   // periodic repository/process churn in the Recovery daemon.
   const source = observeSource();
-  if (!source.configured) return { required: false, reason: 'source_not_configured' };
+  if (!source.configured) return session
+    ? { required: true, reason: 'active_session', action: runtimeReleaseActionForSession(session), session }
+    : { required: false, reason: 'source_not_configured' };
   const sourceRevision = source.sourceRevision?.trim();
   const activeSourceCommit = source.activeSourceCommit?.trim();
   if (!sourceRevision) throw new Error('RELEASE_AUTOMATION_SOURCE_REVISION_UNKNOWN');
   if (!activeSourceCommit) throw new Error('RELEASE_AUTOMATION_ACTIVE_SOURCE_COMMIT_UNKNOWN');
-  if (sourceRevision === activeSourceCommit) return { required: false, reason: 'source_current' };
+  if (sourceRevision === activeSourceCommit) return session
+    ? { required: true, reason: 'active_session', action: runtimeReleaseActionForSession(session), session }
+    : { required: false, reason: 'source_current' };
 
   // An autonomous release is one attempt per immutable source revision.
   // A terminal ReleaseSession is durable evidence that this exact commit was
@@ -187,8 +196,15 @@ export async function advanceConfiguredRuntimeReleaseStep<C extends RuntimeRelea
   config: C,
   provider: RuntimeReleaseProvider<C>,
   requestId?: string,
+  reconciliation?: RuntimeReleaseReconciliationDecision,
 ): Promise<RuntimeReleaseProgressResult> {
-  const decision = decideConfiguredRuntimeReleaseAction(config.controllerHome);
+  // The Coordinator's source comparison may select a new Candidate while the
+  // one allowable soaking predecessor stays open. Provider.prepare itself
+  // revalidates source/Stable A under the existing Recovery mutation lock.
+  const decision: RuntimeReleaseCoordinatorDecision = reconciliation?.required
+    && reconciliation.reason === 'source_mismatch' && reconciliation.action === 'prepare'
+    ? { action: 'prepare' }
+    : decideConfiguredRuntimeReleaseAction(config.controllerHome);
   const request = requestId?.trim();
   switch (decision.action) {
     case 'prepare':

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

@@ -1,6 +1,8 @@
 import {
   beginControllerRoundRelayAfterRelease,
+  bindControllerSessionToCurrentRuntime,
   controllerRoundBlockerClass,
+  controllerSessionPrincipalId,
   getControllerRoundRelay,
   getControllerWorkBinding,
   getRetainedControllerSession,
@@ -8,6 +10,7 @@ import {
   resumeControllerRoundOccurrence,
   type ControllerBinding,
   type ControllerHost,
+  type ControllerSession,
 } from '../../../packages/kernel/controller/api/index';
 import { getWorkContract, semanticWorkState } from '../../../packages/kernel/work/api/index';
 import {
@@ -16,8 +19,10 @@ import {
 } from './scheduled-controller-composition';
 import {
   ensureWorkflowSupervisorEnrollmentForWork,
+  wakeWorkflowSupervisorScheduledTaskForWork,
   type WorkflowSupervisorEnrollmentStatus,
 } from './workflow-supervisor-composition';
+import { getRuntimeWriteClaim } from './write-fence';
 
 export interface ControllerProgressionInput {
   workId: string;
@@ -26,6 +31,8 @@ export interface ControllerProgressionInput {
   continuationHint?: string;
   allowSemanticWaitRecovery?: boolean;
   scheduleName?: string;
+  scheduleId?: string;
+  scheduleOccurrenceId?: string;
   bindingArgs?: Record<string, unknown>;
 }
 
@@ -35,6 +42,7 @@ export interface ControllerProgressionDependencies {
   prepareOccurrence?: typeof prepareControllerRoundOccurrence;
   resumeOccurrence?: typeof resumeControllerRoundOccurrence;
   ensureSupervisorEnrollment?: typeof ensureWorkflowSupervisorEnrollmentForWork;
+  wakeScheduledSupervisorTask?: typeof wakeWorkflowSupervisorScheduledTaskForWork;
 }
 
 export type ControllerProgressionResult =
@@ -56,6 +64,12 @@ export type ControllerProgressionResult =
         reason?: string;
       };
     }
+  | {
+      status: 'scheduled_supervisor_woken';
+      binding: ControllerBinding;
+      taskId: string;
+      effectId: string;
+    }
   | {
       status: 'chatgpt_not_enrolled';
       binding: ControllerBinding;
@@ -85,6 +99,27 @@ export type ControllerProgressionResult =
  * 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,
@@ -100,18 +135,45 @@ export async function reconcileControllerProgression(
   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: retainedSession,
+    session,
     scheduleName: input.scheduleName,
     args: input.bindingArgs ?? {},
   });
 
-  if (retainedSession.controllerType === 'chatgpt') {
+  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 existingRound = getControllerRoundRelay(store, input.workId);
     let controllerRoundOccurrenceId = input.occurrenceId;
     if (existingRound?.status === 'pending_release') {
       // The semantic turn already chose continue_immediately. Once its exact
@@ -134,7 +196,7 @@ export async function reconcileControllerProgression(
     }
     if (existingRound?.status === 'blocked'
       && controllerRoundBlockerClass(existingRound) === 'provider_dispatch_outcome_unknown') {
-      const supervisorEnrollment = await ensureSupervisorEnrollment(store, input.workId);
+      const supervisorEnrollment = await ensureSupervisorEnrollment(store, input.workId, input.scheduleId, input.scheduleOccurrenceId);
       return {
         status: supervisorEnrollment.status === 'enrolled' ? 'chatgpt_enrolled' : 'chatgpt_not_enrolled',
         binding,
@@ -157,7 +219,7 @@ export async function reconcileControllerProgression(
     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);
+    const supervisorEnrollment = await ensureSupervisorEnrollment(store, input.workId, input.scheduleId, input.scheduleOccurrenceId);
     return {
       status: supervisorEnrollment.status === 'enrolled' ? 'chatgpt_enrolled' : 'chatgpt_not_enrolled',
       binding,