@moretea-labs/forge 1.8.0 → 1.8.2

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;
@@ -90,6 +92,24 @@ export interface AssistantPluginManifest {
     duplicateStateAllowed: false;
     sourceOfTruth: string[];
   };
+  /**
+   * A temporary transport projection. It is descriptive only: the replacement
+   * owner remains the sole execution and persistence authority.
+   */
+  compatibility?: {
+    replacementOwner: string;
+    boundedConsumers: Array<{
+      surface: 'plugin_action_execute';
+      pluginId: string;
+      actionIds: string[];
+    }>;
+    removalCondition: {
+      kind: 'no_supported_frozen_contract_actions';
+      surface: 'plugin_action_execute';
+      pluginId: string;
+      actionIds: string[];
+    };
+  };
   enabled: boolean;
   lifecycle: {
     state: AssistantPluginLifecycleState;
@@ -140,6 +160,8 @@ export interface AssistantPluginActionRequest {
 
 export interface AssistantPluginActionExecutionInput {
   controllerHome: string;
+  /** Explicit per-invocation authorization for protected plugin actions. */
+  confirmAuthorization?: boolean;
   repoId: string;
   repoRoot: string;
   pluginId: string;
@@ -174,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/plugins/xiaohongshu-publish.ts

@@ -158,6 +158,22 @@ export function buildXiaohongshuPluginManifest(previousRevision = 0, previousUpd
         'browser-profile:authentication-and-session',
       ],
     },
+    compatibility: {
+      replacementOwner: 'Workflow Runtime (rh_work workflow_execute) and the versioned xiaohongshu Workflow assets',
+      boundedConsumers: [
+        {
+          surface: 'plugin_action_execute',
+          pluginId: PLUGIN_ID,
+          actionIds: ['get_publish_recipe', 'publish_note'],
+        },
+      ],
+      removalCondition: {
+        kind: 'no_supported_frozen_contract_actions',
+        surface: 'plugin_action_execute',
+        pluginId: PLUGIN_ID,
+        actionIds: ['get_publish_recipe', 'publish_note'],
+      },
+    },
     enabled: true,
     lifecycle: { state: 'enabled', reason: 'Compatibility translation is available; all publishing effects are Workflow-owned.' },
     health: health(), permissions: permissions(), capabilities: capabilities(), actions: actions(), updatedAt: previousUpdatedAt ?? now(),

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/projections/invalidation.ts

@@ -146,7 +146,7 @@ export function updateRepositoryProjectionRefreshRequest(
     sourceRevision?: string;
     nowMs?: number;
   },
-  options: { lock?: boolean } = {},
+  options: { lock?: boolean; supersedeAttempt?: boolean } = {},
 ): ProjectionDirtyMarker | undefined {
   try {
     const fence = assertRuntimeMayWrite('update_active_projection', controllerHome);
@@ -170,7 +170,11 @@ export function updateRepositoryProjectionRefreshRequest(
       ),
     );
 
-    if (current && sameSource) {
+    const supersedeAttempt = options.supersedeAttempt === true
+      && current?.refreshStatus !== undefined
+      && current.refreshStatus !== 'pending';
+
+    if (current && sameSource && !supersedeAttempt) {
       const normalized = normalizeMarker(current);
       const enriched: ProjectionDirtyMarker = {
         ...normalized,
@@ -214,7 +218,7 @@ export function markRepositoryProjectionDirty(
     reason,
     sourceRevision: options.sourceRevision,
     nowMs: options.nowMs,
-  });
+  }, { supersedeAttempt: true });
 }
 
 export function readRepositoryProjectionDirty(controllerHome: string, repoId: string): ProjectionDirtyMarker | undefined {

package/src/runtime/projections/materialized-view.ts

@@ -27,7 +27,7 @@ import type { ProjectionObservation, ProjectionSourceReconciliation } from '../h
 import { RUNTIME_HEALTH_THRESHOLDS } from '../health/evaluator';
 import { isProcessAlive } from '../shared/process-tree';
 import type { TaskLedgerProjection } from '../../cli/controller/task-ledger';
-import { collectWorkLifecycleAttention } from '../control-plane/execution/work-lifecycle-audit';
+import { collectWorkLifecycleAttention, workLifecycleAttentionBlocksReadiness } from '../control-plane/execution/work-lifecycle-audit';
 
 export interface ProjectionMetadata {
   contentRevision: number;
@@ -164,7 +164,9 @@ function projectionWithExecutionIndexOverlay(
   const activeJobIds = new Set(activeJobSummaries.map((job) => job.jobId));
   const attentionJobs = recentJobs?.filter((job) => ATTENTION_JOB_STATUSES.has(job.status));
   const materializedLifecycleAttention = base.attention.filter((entry) => entry.jobId.startsWith('lifecycle:'));
-  const materializedCurrentLifecycleAttention = base.currentAttention.filter((entry) => entry.jobId.startsWith('lifecycle:'));
+  const materializedCurrentLifecycleAttention = base.currentAttention
+    .filter((entry) => entry.jobId.startsWith('lifecycle:'))
+    .filter(workLifecycleAttentionBlocksReadiness);
   const attention = attentionJobs
     ? attentionJobs.map(attentionSummary)
     : base.attention.filter((entry) => !entry.jobId.startsWith('lifecycle:'));
@@ -190,6 +192,8 @@ function projectionWithExecutionIndexOverlay(
     // Lifecycle attention is producer-owned materialized state. Hot reads overlay
     // only lightweight ExecutionJob/Lease indexes and must never synchronously
     // re-run Git/Work lifecycle reconciliation on the MCP request event loop.
+    // Re-apply the current readiness classifier to persisted lifecycle entries so
+    // a policy cutover cannot leave obsolete blockers stuck in currentAttention.
     currentAttention: [...currentAttention, ...materializedCurrentLifecycleAttention].slice(0, 100),
     attention: [...attention, ...materializedLifecycleAttention].slice(0, 100),
   };
@@ -247,7 +251,7 @@ function buildRepositoryProjection(
     activeLeases: leases.length,
     currentAttention: [
       ...currentAttentionJobs.map((job) => ({ jobId: job.jobId, status: job.status, message: job.error?.message })),
-      ...lifecycleAttention,
+      ...lifecycleAttention.filter(workLifecycleAttentionBlocksReadiness),
     ].slice(0, 100),
     attention: [
       ...attentionJobs.map((job) => ({ jobId: job.jobId, status: job.status, message: job.error?.message })),
@@ -474,10 +478,15 @@ function refreshRepositoryProjection(
   const nowMs = options.nowMs ?? Date.now();
   const acquiredAt = nowIso(nowMs);
   const owner = refreshOwner(options, acquiredAt);
-  return withRepositoryProjectionRefreshLock(
+  const lockOwner = `projection-refresh:${owner.pid}`;
+
+  // Claim one refresh generation under the repository projection lock, then release
+  // it before the expensive materialization. Real jobs/leases/finalizers must be
+  // able to invalidate the projection while a refresh is building.
+  const claim = withRepositoryProjectionRefreshLock(
     controllerHome,
     repoId,
-    `projection-refresh:${owner.pid}`,
+    lockOwner,
     () => {
       dirtyProjectionReadCache.delete(dirtyProjectionReadCacheKey(controllerHome, repoId));
       const previous = readJsonFile<RepositoryRuntimeProjection | undefined>(projectionPath(controllerHome, repoId), undefined);
@@ -497,13 +506,26 @@ function refreshRepositoryProjection(
           sourceRevision,
           nowMs,
         }, { lock: false });
-        if (!marker) return { refreshed: false, skippedReason: 'passive_runtime' };
+        if (!marker) {
+          return {
+            kind: 'skip' as const,
+            result: { refreshed: false, skippedReason: 'passive_runtime' as const },
+          };
+        }
+      }
+      if (!marker) {
+        return {
+          kind: 'skip' as const,
+          result: { refreshed: false, skippedReason: 'clean' as const, projection: previous },
+        };
       }
-      if (!marker) return { refreshed: false, skippedReason: 'clean', projection: previous };
 
       const currentOwner = refreshOwner(options, acquiredAt);
       if (ownerStillOwnsRefresh(marker, nowMs, currentOwner)) {
-        return { refreshed: false, skippedReason: 'running', marker, projection: previous };
+        return {
+          kind: 'skip' as const,
+          result: { refreshed: false, skippedReason: 'running' as const, marker, projection: previous },
+        };
       }
       if (marker.refreshStatus === 'running' && !ownerStillOwnsRefresh(marker, nowMs, currentOwner)) {
         marker = recoverStaleOwner(controllerHome, repoId, marker, acquiredAt, 'stale_owner_or_restart');
@@ -514,42 +536,64 @@ function refreshRepositoryProjection(
         && marker.nextAttemptAt
         && Date.parse(marker.nextAttemptAt) > nowMs
       ) {
-        return { refreshed: false, skippedReason: 'retry_deferred', marker, projection: previous };
+        return {
+          kind: 'skip' as const,
+          result: { refreshed: false, skippedReason: 'retry_deferred' as const, marker, projection: previous },
+        };
       }
 
       const running = markRunning(controllerHome, repoId, {
         ...marker,
         sourceRevision: marker.sourceRevision ?? sourceRevision,
       }, owner, acquiredAt);
-      try {
-        const latestPrevious = readJsonFile<RepositoryRuntimeProjection | undefined>(projectionPath(controllerHome, repoId), undefined);
-        const buildRevision = normalizeGitRevision(running.sourceRevision) ?? sourceRevision;
-        const projection = buildRepositoryProjection(controllerHome, repoId, latestPrevious, buildRevision);
-        const current = readRepositoryProjectionDirty(controllerHome, repoId);
-        if (
-          !current
-          || current.nonce !== running.nonce
-          || (
-            running.sourceRevision
-            && current.sourceRevision
-            && !gitRevisionsEquivalent(running.sourceRevision, current.sourceRevision)
-          )
-        ) {
-          return { refreshed: false, skippedReason: 'superseded', marker: current, projection: latestPrevious };
-        }
-        writeJsonAtomic(projectionPath(controllerHome, repoId), projection);
-        clearRepositoryProjectionDirty(controllerHome, repoId, current, projection.metadata?.generatedFromRevision);
-        dirtyProjectionReadCache.delete(dirtyProjectionReadCacheKey(controllerHome, repoId));
-        return { refreshed: true, projection };
-      } catch (error) {
-        const current = readRepositoryProjectionDirty(controllerHome, repoId);
-        if (current?.nonce === running.nonce) {
-          markFailed(controllerHome, repoId, running, owner, error, options.nowMs ?? Date.now());
-        }
-        throw error;
-      }
+      return {
+        kind: 'build' as const,
+        running,
+        previous: readJsonFile<RepositoryRuntimeProjection | undefined>(projectionPath(controllerHome, repoId), undefined),
+        buildRevision: normalizeGitRevision(running.sourceRevision) ?? sourceRevision,
+      };
     },
   );
+
+  if (claim.kind === 'skip') return claim.result;
+
+  let projection: RepositoryRuntimeProjection;
+  try {
+    projection = buildRepositoryProjection(controllerHome, repoId, claim.previous, claim.buildRevision);
+  } catch (error) {
+    // Failure bookkeeping is another short CAS section. If a real mutation already
+    // superseded this nonce, it owns the dirty marker and must not be overwritten.
+    withRepositoryProjectionRefreshLock(controllerHome, repoId, lockOwner, () => {
+      const current = readRepositoryProjectionDirty(controllerHome, repoId);
+      if (current?.nonce === claim.running.nonce) {
+        markFailed(controllerHome, repoId, claim.running, owner, error, options.nowMs ?? Date.now());
+      }
+    });
+    throw error;
+  }
+
+  // Publish only if the exact claimed nonce still owns the refresh. A concurrent
+  // mutation either superseded it while build ran or will mark dirty after this
+  // short publish section, so no invalidation can be lost.
+  return withRepositoryProjectionRefreshLock(controllerHome, repoId, lockOwner, () => {
+    const current = readRepositoryProjectionDirty(controllerHome, repoId);
+    const currentProjection = readJsonFile<RepositoryRuntimeProjection | undefined>(projectionPath(controllerHome, repoId), undefined);
+    if (
+      !current
+      || current.nonce !== claim.running.nonce
+      || (
+        claim.running.sourceRevision
+        && current.sourceRevision
+        && !gitRevisionsEquivalent(claim.running.sourceRevision, current.sourceRevision)
+      )
+    ) {
+      return { refreshed: false, skippedReason: 'superseded', marker: current, projection: currentProjection };
+    }
+    writeJsonAtomic(projectionPath(controllerHome, repoId), projection);
+    clearRepositoryProjectionDirty(controllerHome, repoId, current, projection.metadata?.generatedFromRevision);
+    dirtyProjectionReadCache.delete(dirtyProjectionReadCacheKey(controllerHome, repoId));
+    return { refreshed: true, projection };
+  });
 }
 
 export function refreshRepositoryProjectionForRepository(

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',
@@ -93,13 +93,13 @@ export const RECOVERY_ACTIONS = {
   },
   stageAndActivateRuntimeRelease: {
     id: 'recovery.stage_and_activate_runtime_release',
-    title: 'Stage and activate canonical Runtime release',
-    description: 'Build one immutable Runtime release from the selected registered repository, then hand lifecycle activation to the standalone Recovery transaction.',
+    title: 'Prepare isolated Runtime ReleaseSession',
+    description: 'Compatibility action id: ask standalone Recovery to freeze its configured source and Stable A authority, create isolated Candidate B, and build a portable release. It no longer activates Stable A.',
     class: 'stale_runtime_state',
     risk: 'medium',
     confirmation: 'authorization',
     localOnly: true,
-    boundedTo: ['registered_repository', 'runtime_release_storage', 'external_runtime_lifecycle'],
+    boundedTo: ['registered_repository', 'runtime_release_storage'],
   },
   restartPrimaryConnector: {
     id: 'recovery.restart_primary_connector',

package/src/runtime/recovery/capability-action-application.ts

@@ -3,15 +3,14 @@ import { ensureRepositoryRuntimeStorage } from '../../cli/repositories/runtime-s
 import { prepareTransferArtifacts } from '../../cli/repositories/selected-path-actions';
 import { applyRuntimeCleanup, previewRuntimeCleanup } from '../maintenance/cleanup';
 import { rebuildRepositoryProjection } from '../projections/materialized-view';
-import { assertRuntimeReleaseFiles, stageRuntimeReleaseFromCandidateSource } from '../root/release-materialize';
 import { recoveryActionById } from './actions';
 import { assertRecoveryAuthorized, buildRecoveryAuditRecord } from './audit';
 import { applyRuntimeMaintenance } from './maintenance-executor';
-import { writeRecoveryAuditRecord } from './store';
+import { writeInstanceRecoveryAuditRecord, writeRecoveryAuditRecord } from './store';
 
 export interface CapabilityRecoveryApplicationInput {
   controllerHome: string;
-  repository: RepositoryRecord;
+  repository?: RepositoryRecord;
   actionId: string;
   reason: string;
   confirmAuthorization: boolean;
@@ -23,17 +22,30 @@ export interface CapabilityRecoveryApplicationInput {
 }
 
 export interface CapabilityRecoveryApplicationResult {
-  repoId: string;
+  repoId?: string;
+  scope: 'forge_instance' | 'repository';
   action: NonNullable<ReturnType<typeof recoveryActionById>>;
   audit: ReturnType<typeof writeRecoveryAuditRecord>;
   result: Record<string, unknown>;
 }
 
+const INSTANCE_RECOVERY_ACTION_IDS = new Set([
+  'recovery.stage_and_activate_runtime_release',
+  'recovery.restart_primary_connector',
+  'recovery.probe_again',
+  'recovery.workspace_auth_login_prepare',
+  'recovery.external_filesystem_grant_preview',
+]);
+
+export function recoveryActionScope(actionId: string): 'forge_instance' | 'repository' {
+  return INSTANCE_RECOVERY_ACTION_IDS.has(actionId) ? 'forge_instance' : 'repository';
+}
+
 export class RecoveryApplicationError extends Error {
-  readonly code: 'RECOVERY_ACTION_UNKNOWN';
+  readonly code: 'RECOVERY_ACTION_UNKNOWN' | 'RECOVERY_REPOSITORY_CONTEXT_REQUIRED';
   readonly actionId: string;
 
-  constructor(code: 'RECOVERY_ACTION_UNKNOWN', actionId: string) {
+  constructor(code: RecoveryApplicationError['code'], actionId: string) {
     super(`${code}: ${actionId}`);
     this.name = 'RecoveryApplicationError';
     this.code = code;
@@ -85,29 +97,19 @@ export async function executeCapabilityRecoveryAction(
         : undefined,
   );
 
+  const scope = recoveryActionScope(action.id);
+  const repository = scope === 'repository'
+    ? input.repository ?? (() => { throw new RecoveryApplicationError('RECOVERY_REPOSITORY_CONTEXT_REQUIRED', action.id); })()
+    : undefined;
+
   let payload: Record<string, unknown>;
   let affectedPaths: string[] = [];
   switch (action.id) {
     case 'recovery.stage_and_activate_runtime_release': {
-      const staged = stageRuntimeReleaseFromCandidateSource({
-        controllerHome: input.controllerHome,
-        sourceRoot: input.repository.canonicalRoot,
-        sourceRepositoryId: input.repository.repoId,
+      payload = await input.callStandaloneRecoveryTool('prepare_runtime_release_session', {
+        request_id: `runtime-release-session-${Date.now()}`,
       });
-      assertRuntimeReleaseFiles(staged);
-      payload = {
-        staged: {
-          releaseId: staged.releaseId,
-          sourceCommit: staged.sourceCommit,
-          artifactIdentity: staged.artifactIdentity,
-          manifestSha256: staged.manifestSha256,
-        },
-        activation: await input.callStandaloneRecoveryTool('activate_runtime_release', {
-          request_id: `runtime-cutover-${Date.now()}`,
-          release_path: staged.manifestPath,
-        }),
-      };
-      affectedPaths = ['controllerHome/runtime/releases', 'controllerHome/runtime/releases/authority.json'];
+      affectedPaths = ['controllerHome/recovery/state/release-sessions', 'candidate-runtime-lanes'];
       break;
     }
     case 'recovery.restart_primary_connector': {
@@ -121,20 +123,20 @@ export async function executeCapabilityRecoveryAction(
       payload = { recovery: await input.recoverySnapshot() };
       break;
     case 'recovery.rebuild_projection': {
-      const projection = rebuildRepositoryProjection(input.controllerHome, input.repository.repoId);
+      const projection = rebuildRepositoryProjection(input.controllerHome, repository!.repoId);
       payload = { projection };
       affectedPaths = ['.ai/harness/controller/projections'];
       break;
     }
     case 'recovery.refresh_repository': {
-      const runtimeStorage = ensureRepositoryRuntimeStorage(input.repository, input.controllerHome);
-      const projection = rebuildRepositoryProjection(input.controllerHome, input.repository.repoId);
+      const runtimeStorage = ensureRepositoryRuntimeStorage(repository!, input.controllerHome);
+      const projection = rebuildRepositoryProjection(input.controllerHome, repository!.repoId);
       payload = { runtimeStorage, projection };
       affectedPaths = ['.ai/harness/controller', '.ai/harness/local-bridge'];
       break;
     }
     case 'recovery.cleanup_preview': {
-      payload = previewRuntimeCleanup(input.repository.canonicalRoot, {
+      payload = previewRuntimeCleanup(repository!.canonicalRoot, {
         minAgeMinutes: input.minAgeMinutes,
         includeTempDirs: true,
         includeTerminalLocalJobs: true,
@@ -145,7 +147,7 @@ export async function executeCapabilityRecoveryAction(
       break;
     }
     case 'recovery.cleanup_apply': {
-      payload = applyRuntimeCleanup(input.repository.canonicalRoot, {
+      payload = applyRuntimeCleanup(repository!.canonicalRoot, {
         minAgeMinutes: input.minAgeMinutes,
         includeTempDirs: true,
         includeTerminalLocalJobs: true,
@@ -159,7 +161,7 @@ export async function executeCapabilityRecoveryAction(
     }
     case 'recovery.reconcile_jobs':
     case 'recovery.local_jobs_reconcile': {
-      const maintenance = applyRuntimeMaintenance(input.repository, input.controllerHome, {
+      const maintenance = applyRuntimeMaintenance(repository!, input.controllerHome, {
         actionId: 'local_jobs_reconcile',
         confirmMaintenance: true,
         minAgeMinutes: input.minAgeMinutes ?? 10,
@@ -170,7 +172,7 @@ export async function executeCapabilityRecoveryAction(
       break;
     }
     case 'recovery.local_jobs_quarantine_unreadable': {
-      const maintenance = applyRuntimeMaintenance(input.repository, input.controllerHome, {
+      const maintenance = applyRuntimeMaintenance(repository!, input.controllerHome, {
         actionId: 'quarantine_unreadable_local_jobs',
         confirmMaintenance: true,
         minAgeMinutes: input.minAgeMinutes ?? 0,
@@ -181,7 +183,7 @@ export async function executeCapabilityRecoveryAction(
       break;
     }
     case 'recovery.runtime_storage_finalize_relocation': {
-      const maintenance = applyRuntimeMaintenance(input.repository, input.controllerHome, {
+      const maintenance = applyRuntimeMaintenance(repository!, input.controllerHome, {
         actionId: 'runtime_storage_finalize_relocation',
         confirmMaintenance: true,
         minAgeMinutes: input.minAgeMinutes ?? 0,
@@ -192,7 +194,7 @@ export async function executeCapabilityRecoveryAction(
       break;
     }
     case 'recovery.create_patch_handoff':
-      payload = prepareTransferArtifacts(input.repository, { reason: input.reason }) as unknown as Record<string, unknown>;
+      payload = prepareTransferArtifacts(repository!, { reason: input.reason }) as unknown as Record<string, unknown>;
       affectedPaths = ['.ai/harness/transfers', '.ai/harness/session'];
       break;
     case 'recovery.workspace_auth_login_prepare':
@@ -213,16 +215,15 @@ export async function executeCapabilityRecoveryAction(
       payload = { skipped: true, reason: `No executor is registered for ${action.id}.` };
   }
 
-  const audit = writeRecoveryAuditRecord(
-    input.controllerHome,
-    input.repository.repoId,
-    buildRecoveryAuditRecord({
-      actor: 'capability_recovery_apply',
-      action,
-      result: payload.skipped === true ? 'skipped' : 'succeeded',
-      reason: input.reason,
-      affectedPaths,
-    }),
-  );
-  return { repoId: input.repository.repoId, action, audit, result: payload };
+  const auditRecord = buildRecoveryAuditRecord({
+    actor: 'capability_recovery_apply',
+    action,
+    result: payload.skipped === true ? 'skipped' : 'succeeded',
+    reason: input.reason,
+    affectedPaths,
+  });
+  const audit = repository
+    ? writeRecoveryAuditRecord(input.controllerHome, repository.repoId, auditRecord)
+    : writeInstanceRecoveryAuditRecord(input.controllerHome, auditRecord);
+  return { ...(repository ? { repoId: repository.repoId } : {}), scope, action, audit, result: payload };
 }