@moretea-labs/forge 1.8.0 → 1.8.1

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

@@ -19,6 +19,8 @@ import { basename, dirname, join } from 'path';
 import { ensureRepositoryControllerLayout, repositoryControllerRoot } from '../../../cli/repositories/controller-home';
 import { mutateControlPlaneRecord, readOrImportControlPlaneRecord } from '../../control-plane/persistence/sqlite-store';
 import { isSensitiveOutputKey, redactSensitiveText } from '../../evidence/sensitive-output';
+import { touchSchedulerWakeSignal } from '../../control-plane/global-scheduler/wake-signal';
+import { isRepositoryProcessScopeKey, legacyWorkspaceScopeRoot, processScopeRoot } from './process-scope';
 import {
   isManagedProcessActive,
   isManagedProcessTerminal,
@@ -30,7 +32,12 @@ import {
 } from './types';
 
 function processesRoot(controllerHome: string, repoId: string): string {
-  const root = ensureRepositoryControllerLayout(controllerHome, repoId);
+  // Repository scopes keep the established per-repository layout. Instance and
+  // workspace scopes own sibling partitions so a non-repository process never
+  // needs a synthetic repository identity or repository storage.
+  const root = isRepositoryProcessScopeKey(repoId)
+    ? ensureRepositoryControllerLayout(controllerHome, repoId)
+    : processScopeRoot(controllerHome, repoId);
   const dir = join(root, 'processes');
   mkdirSync(dir, { recursive: true });
   mkdirSync(join(dir, 'logs'), { recursive: true });
@@ -522,7 +529,13 @@ export function getProcessRecord(
   repoId: string,
   processId: string,
 ): ManagedProcessRecord | undefined {
-  return readProcessRecord(processPath(controllerHome, repoId, processId));
+  const current = readProcessRecord(processPath(controllerHome, repoId, processId));
+  if (current) return current;
+  // Bounded migration read: workspace processes written before the workspace
+  // partition existed are still attachable instead of being reported missing.
+  const legacyRoot = legacyWorkspaceScopeRoot(controllerHome, repoId);
+  if (!legacyRoot) return undefined;
+  return readProcessRecord(join(legacyRoot, 'processes', `${processId}.json`));
 }
 
 /**
@@ -559,6 +572,21 @@ export function tryCompleteProcessRecord(
   const sanitized = sanitizeProcessRecord(next).record;
   atomicWrite(path, sanitized);
   updateRecoveryIndexMembership(controllerHome, repoId, processId, processRecoveryMembership(sanitized));
+  // Terminal Process persistence remains the lifecycle authority. The scheduler
+  // notification is emitted only after durable terminal state exists, and only
+  // for Check-backed Processes whose receipts can unblock Work/Edit validation.
+  // Notification failure must never reinterpret or roll back the terminal CAS;
+  // the explicit schedule deadline still provides a bounded observation path.
+  if (sanitized.checkExecution || sanitized.origin?.surface === 'check' || sanitized.origin?.checkId) {
+    try {
+      touchSchedulerWakeSignal(controllerHome, `check-process-terminal:${processId}`);
+    } catch (error) {
+      console.error(
+        `[forge scheduler] Check Process terminal wake failed for ${processId}:`,
+        error instanceof Error ? error.message : String(error),
+      );
+    }
+  }
   return { ok: true, record: sanitized };
 }
 

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

@@ -17,7 +17,6 @@ export interface ExecutionConcurrencyWaitProjection {
   wakeTrigger:
     | { kind: 'work_terminal'; workId: string }
     | { kind: 'resource_release'; resourceKeys: string[] }
-    | { kind: 'controller_release'; workId: string }
     | { kind: 'scheduler_capacity'; capacityKey: string }
     | { kind: 'work_contract_change'; workId: string };
   observedAt: string;
@@ -186,6 +185,8 @@ export interface ManagedProcessRecord {
   processId: string;
   repoId: string;
   checkoutId?: string;
+  /** Authenticated principal that owns the handle; opaque ids never authorize by themselves. */
+  principalId?: string;
   /** Optional facade WorkContract that owns this command. */
   workId?: string;
   /** Immutable pre-spawn authority required for post-terminal Work reconciliation. */
@@ -288,6 +289,8 @@ export interface SpawnManagedProcessInput {
   controllerHome: string;
   repoId: string;
   checkoutId?: string;
+  /** Authenticated principal recorded for principal-bound attachment. */
+  principalId?: string;
   /** Immutable resolved execution identity — required; validated immediately before spawn. */
   executionIdentity: ResolvedExecutionIdentity;
   workId?: string;
@@ -306,6 +309,8 @@ export interface SpawnManagedProcessInput {
   resourceClaims?: ProcessResourceClaim[];
   checkExecution?: ProcessCheckExecutionIdentity;
   origin?: ManagedProcessRecord['origin'];
+  /** Runtime-owned child allowed to rebind only the exact current Runtime write authority. */
+  trustedRuntimeChild?: 'plugin_action_sidecar';
   runtimeInstanceId?: string;
   releaseAuthorityRevision?: number;
   releaseId?: string;

package/src/runtime/execution/workers/executor.ts

@@ -29,7 +29,6 @@ import { existsSync } from 'fs';
 import { isAbsolute, relative, resolve, sep } from 'path';
 import { isAssistantPluginError } from '../../plugins/errors';
 import { executeWork, validateWork } from '../../control-plane/execution/work-operation-service';
-import { finalizeWork } from '../../control-plane/execution/work-finalization-service';
 import { describeFailure } from '../../../../packages/protocols/failure';
 
 
@@ -525,8 +524,7 @@ export async function executeExecutionJob(controllerHome: string, job: Execution
     // Durable Work mutations execute through control-plane application services.
     // The Worker must never import MCP transport to obtain Work semantics.
     const durableWorkOperation = job.payload.operation === 'work_execute'
-      || job.payload.operation === 'work_validate'
-      || job.payload.operation === 'work_finalize';
+      || job.payload.operation === 'work_validate';
     const toolArguments = { ...(job.payload.arguments ?? {}) };
     const workArguments = {
       ...toolArguments,
@@ -537,9 +535,7 @@ export async function executeExecutionJob(controllerHome: string, job: Execution
       ? await executeWork(runtimeContext, workArguments)
       : job.payload.operation === 'work_validate'
         ? await validateWork(runtimeContext, workArguments)
-        : job.payload.operation === 'work_finalize'
-          ? await finalizeWork(runtimeContext, workArguments)
-          : undefined;
+        : undefined;
     const executionResult: CallToolResult | undefined = durableWorkOperation && executionRecord
       ? { structuredContent: executionRecord, content: [] }
       : undefined;

package/src/runtime/platform/service-inventory.ts

@@ -0,0 +1,130 @@
+import { createHash } from 'crypto';
+import { resolve } from 'path';
+import type { PlatformServiceManagerHost } from './service-manager';
+
+export type ForgePersistentServiceOwner = 'forge-core' | 'provider';
+export type ForgePersistentServiceState = 'current' | 'retired';
+
+export interface ForgePersistentServiceIdentity {
+  id: string;
+  owner: ForgePersistentServiceOwner;
+  state: ForgePersistentServiceState;
+  launchdLabel: string;
+  systemdUnitName: string;
+}
+
+export const FORGE_RECOVERY_DAEMON_LABEL = 'com.moretea.forge-recovery';
+export const FORGE_RECOVERY_GATEWAY_LABEL = 'com.moretea.forge-recovery-gateway';
+export const FORGE_RECOVERY_WATCHDOG_LABEL = 'com.moretea.forge-recovery-watchdog';
+
+const RETIRED_CORE_LABELS = [
+  ['legacy-runtime', 'com.moretea.forge.runtime'],
+  ['legacy-mcp-gateway', 'com.moretea.forge.mcp-gateway'],
+  ['bootstrap-supervisor', 'com.moretea.forge-bootstrap-supervisor'],
+  ['evolution-supervisor', 'com.moretea.forge-evolution-supervisor'],
+  ['legacy-recovery-gateway', FORGE_RECOVERY_GATEWAY_LABEL],
+  ['legacy-recovery-watchdog', FORGE_RECOVERY_WATCHDOG_LABEL],
+] as const;
+
+/**
+ * These identities are intentionally outside Forge core lifecycle authority.
+ * They are listed to make the negative ownership boundary machine-visible,
+ * not to authorize any retirement action.
+ */
+export const FORGE_PROVIDER_OWNED_PERSISTENT_SERVICES = [
+  'com.moretea.forge.desktop-operator',
+  'com.moretea.desktop-operator',
+] as const;
+
+function controllerHomeSuffix(controllerHome: string): string {
+  return createHash('sha256').update(resolve(controllerHome)).digest('hex').slice(0, 12);
+}
+
+export function forgeRuntimePersistentServiceLabel(controllerHome: string): string {
+  return `com.moretea.forge.runtime.${controllerHomeSuffix(controllerHome)}`;
+}
+
+export function forgeConnectorPersistentServiceLabel(controllerHome: string): string {
+  return `com.moretea.forge.mcp-gateway.${controllerHomeSuffix(controllerHome)}`;
+}
+
+function identity(
+  id: string,
+  label: string,
+  state: ForgePersistentServiceState,
+): ForgePersistentServiceIdentity {
+  return {
+    id,
+    owner: 'forge-core',
+    state,
+    launchdLabel: label,
+    systemdUnitName: `${label}.service`,
+  };
+}
+
+export const FORGE_RETIRED_PERSISTENT_SERVICES: readonly ForgePersistentServiceIdentity[] =
+  RETIRED_CORE_LABELS.map(([id, label]) => identity(id, label, 'retired'));
+
+export function forgeOwnedPersistentServiceInventory(controllerHome: string): {
+  current: ForgePersistentServiceIdentity[];
+  retired: readonly ForgePersistentServiceIdentity[];
+  providerOwnedExcludedLabels: readonly string[];
+} {
+  return {
+    current: [
+      identity('runtime', forgeRuntimePersistentServiceLabel(controllerHome), 'current'),
+      identity('mcp-gateway', forgeConnectorPersistentServiceLabel(controllerHome), 'current'),
+      identity('recovery', FORGE_RECOVERY_DAEMON_LABEL, 'current'),
+    ],
+    retired: FORGE_RETIRED_PERSISTENT_SERVICES,
+    providerOwnedExcludedLabels: FORGE_PROVIDER_OWNED_PERSISTENT_SERVICES,
+  };
+}
+
+export interface ForgeRetiredServiceReconciliation {
+  id: string;
+  label: string;
+  platform: 'launchd' | 'systemd-user';
+  serviceWasPresent: boolean;
+  artifactWasPresent: boolean;
+  retired: boolean;
+}
+
+export async function reconcileRetiredForgePersistentServices(input: {
+  host: PlatformServiceManagerHost;
+  env?: NodeJS.ProcessEnv;
+  accountHome?: string;
+}): Promise<ForgeRetiredServiceReconciliation[]> {
+  if (!input.host.selection.persistent || input.host.selection.kind === 'portable') return [];
+  const results: ForgeRetiredServiceReconciliation[] = [];
+  for (const service of FORGE_RETIRED_PERSISTENT_SERVICES) {
+    if (input.host.selection.kind === 'launchd') {
+      const result = await input.host.retireLaunchdExact({
+        label: service.launchdLabel,
+        accountHome: input.accountHome,
+      });
+      results.push({
+        id: service.id,
+        label: service.launchdLabel,
+        platform: 'launchd',
+        serviceWasPresent: result.serviceWasPresent,
+        artifactWasPresent: result.plistWasPresent,
+        retired: result.absentAfter,
+      });
+    } else {
+      const result = input.host.retireSystemdUserExact({
+        unitName: service.systemdUnitName,
+        env: input.env,
+      });
+      results.push({
+        id: service.id,
+        label: service.systemdUnitName,
+        platform: 'systemd-user',
+        serviceWasPresent: result.serviceWasPresent,
+        artifactWasPresent: result.unitFileWasPresent,
+        retired: result.absentAfter,
+      });
+    }
+  }
+  return results;
+}

package/src/runtime/platform/service-manager.ts

@@ -8,6 +8,8 @@ import {
   installLaunchAgent,
   launchAgentPath,
   retireConflictingForgeLaunchAgents,
+  retireLaunchAgentExact,
+  type ExactLaunchAgentRetirementResult,
 } from '../../cli/controller/launch-agents';
 import {
   installSystemdUserUnit,
@@ -15,6 +17,8 @@ import {
   systemdUserAvailable,
   writeSystemdUserUnit,
   systemdUserInstallCommands,
+  retireSystemdUserUnitExact,
+  type ExactSystemdUserUnitRetirementResult,
   type SystemdUserUnitInput,
 } from '../../cli/controller/systemd-user';
 
@@ -48,6 +52,8 @@ export interface PlatformServiceManagerHost {
   bootstrapLaunchd(input: { label: string; plistPath: string }): Promise<{ ok: boolean; diagnostics: string[] }>;
   bootoutLaunchd(input: { label: string; plistPath: string }): Promise<{ ok: boolean; diagnostics: string[] }>;
   retireConflictingLaunchd(input: Parameters<typeof retireConflictingForgeLaunchAgents>[0]): ReturnType<typeof retireConflictingForgeLaunchAgents>;
+  retireLaunchdExact(input: { label: string; accountHome?: string }): Promise<ExactLaunchAgentRetirementResult>;
+  retireSystemdUserExact(input: { unitName: string; env?: NodeJS.ProcessEnv }): ExactSystemdUserUnitRetirementResult;
   launchdDomain(): string;
   detachLaunchdBootout(label: string): void;
   startDetached(input: PlatformDetachedProcessInput): number;
@@ -98,6 +104,8 @@ export function createPlatformServiceManagerHost(input: {
     bootstrapLaunchd: bootstrapLaunchAgentWithRetryV2,
     bootoutLaunchd: bootoutLaunchAgentWithRetryV2,
     retireConflictingLaunchd: retireConflictingForgeLaunchAgents,
+    retireLaunchdExact: retireLaunchAgentExact,
+    retireSystemdUserExact: retireSystemdUserUnitExact,
     launchdDomain: currentUserLaunchdDomain,
     detachLaunchdBootout(label: string): void {
       if (platform !== 'darwin') return;

package/src/runtime/plugins/action-application.ts

@@ -1,13 +1,23 @@
+import { MAX_PLUGIN_ACTION_TIMEOUT_MS } from '../../../packages/plugin-runtime/external/index';
 import type { RepositoryRecord } from '../../cli/repositories/types';
 import type { ProcessHandle } from '../execution/process-runtime/types';
-import { startLightweightPluginAction, waitLightweightPluginAction } from './lightweight-action';
+import {
+  startManagedControllerPluginAction,
+  startManagedPluginAction,
+  waitManagedControllerPluginAction,
+  waitManagedPluginAction,
+} from './lightweight-action';
 import {
   executeAssistantPluginDirectNonPersistent,
   executeAssistantPluginReadDirect,
+  executeControllerPluginDirectNonPersistent,
+  executeControllerPluginReadDirect,
   getAssistantPluginManifest,
+  getControllerPluginManifest,
   isDirectNonPersistentPluginAction,
   isDirectPluginReadAction,
   submitAssistantPluginAction,
+  submitControllerPluginAction,
 } from './store';
 import type {
   AssistantPluginActionDescriptor,
@@ -15,12 +25,19 @@ import type {
   AssistantPluginManifest,
 } from './types';
 
+export const PLUGIN_ACTION_SIDECAR_SETTLEMENT_GRACE_MS = 30_000;
+
+export function pluginActionSidecarTimeoutMs(providerTimeoutMs: number): number {
+  return providerTimeoutMs + PLUGIN_ACTION_SIDECAR_SETTLEMENT_GRACE_MS;
+}
+
 export type AssistantPluginActionApplicationResult =
   | {
       kind: 'direct_read';
       manifest: AssistantPluginManifest;
       action: AssistantPluginActionDescriptor;
       result: Record<string, unknown>;
+      receipt: Awaited<ReturnType<typeof executeAssistantPluginReadDirect>>['receipt'];
     }
   | {
       kind: 'direct_non_persistent';
@@ -29,14 +46,14 @@ export type AssistantPluginActionApplicationResult =
       result: Record<string, unknown>;
     }
   | {
-      kind: 'lightweight_running';
+      kind: 'managed_running';
       manifest: AssistantPluginManifest;
       action?: AssistantPluginActionDescriptor;
       requestId: string;
       process: ProcessHandle;
     }
   | {
-      kind: 'lightweight_failed';
+      kind: 'managed_failed';
       manifest: AssistantPluginManifest;
       action?: AssistantPluginActionDescriptor;
       requestId: string;
@@ -56,22 +73,27 @@ export type AssistantPluginActionApplicationResult =
  */
 export async function executeAssistantPluginActionApplication(input: {
   controllerHome: string;
-  repository: RepositoryRecord;
+  scope: { kind: 'controller' } | { kind: 'repository'; repository: RepositoryRecord };
   request: AssistantPluginActionRequest;
   interactiveWaitMs?: number;
   wait?: boolean;
   waitMs?: number;
 }): Promise<AssistantPluginActionApplicationResult> {
-  const manifest = getAssistantPluginManifest(input.controllerHome, input.repository, input.request.pluginId);
+  const manifest = input.scope.kind === 'controller'
+    ? getControllerPluginManifest(input.controllerHome, input.request.pluginId)
+    : getAssistantPluginManifest(input.controllerHome, input.scope.repository, input.request.pluginId);
   const action = manifest.actions.find((entry) => entry.actionId === input.request.actionId);
 
   if (action && isDirectPluginReadAction(action)) {
-    const direct = await executeAssistantPluginReadDirect(input.controllerHome, input.repository, input.request);
+    const direct = input.scope.kind === 'controller'
+      ? await executeControllerPluginReadDirect(input.controllerHome, input.request)
+      : await executeAssistantPluginReadDirect(input.controllerHome, input.scope.repository, input.request);
     return {
       kind: 'direct_read',
       manifest: direct.manifest,
       action: direct.action,
       result: direct.result,
+      receipt: direct.receipt,
     };
   }
 
@@ -79,7 +101,9 @@ export async function executeAssistantPluginActionApplication(input: {
     if (!isDirectNonPersistentPluginAction(action)) {
       throw new Error(`PLUGIN_DIRECT_NON_PERSISTENT_CONTRACT_INVALID: ${input.request.pluginId}/${input.request.actionId}`);
     }
-    const direct = await executeAssistantPluginDirectNonPersistent(input.controllerHome, input.repository, input.request);
+    const direct = input.scope.kind === 'controller'
+      ? await executeControllerPluginDirectNonPersistent(input.controllerHome, input.request)
+      : await executeAssistantPluginDirectNonPersistent(input.controllerHome, input.scope.repository, input.request);
     return {
       kind: 'direct_non_persistent',
       manifest: direct.manifest,
@@ -88,27 +112,57 @@ export async function executeAssistantPluginActionApplication(input: {
     };
   }
 
-  if (input.repository.repoId !== '__controller__' && action?.executionMode === 'lightweight_process') {
-    const timeoutMs = Math.max(1_000, input.request.timeoutMs ?? action.defaultTimeoutMs ?? 10 * 60_000);
-    let { handle } = await startLightweightPluginAction({
-      controllerHome: input.controllerHome,
-      repository: input.repository,
-      request: input.request,
-      interactiveWaitMs: input.interactiveWaitMs,
-      timeoutMs,
-    });
+  if (action?.executionMode === 'runtime') {
+    // Stateful providers may own in-memory resources whose identity is valid only
+    // inside the canonical Runtime process. Keep the normal durable request/effect
+    // receipt path, but do not relocate execution into a short-lived sidecar.
+    return {
+      kind: 'submitted',
+      submitted: input.scope.kind === 'controller'
+        ? await submitControllerPluginAction(input.controllerHome, input.request)
+        : await submitAssistantPluginAction(input.controllerHome, input.scope.repository, input.request),
+    };
+  }
+
+  if (action) {
+    const requestedTimeoutMs = Number.isFinite(input.request.timeoutMs)
+      ? input.request.timeoutMs!
+      : action.defaultTimeoutMs;
+    const timeoutMs = Math.min(Math.max(1_000, Math.trunc(requestedTimeoutMs)), MAX_PLUGIN_ACTION_TIMEOUT_MS);
+    const sidecarTimeoutMs = pluginActionSidecarTimeoutMs(timeoutMs);
+    let { handle } = input.scope.kind === 'controller'
+      ? await startManagedControllerPluginAction({
+          controllerHome: input.controllerHome,
+          request: input.request,
+          interactiveWaitMs: input.interactiveWaitMs,
+          timeoutMs: sidecarTimeoutMs,
+        })
+      : await startManagedPluginAction({
+          controllerHome: input.controllerHome,
+          repository: input.scope.repository,
+          request: input.request,
+          interactiveWaitMs: input.interactiveWaitMs,
+          timeoutMs: sidecarTimeoutMs,
+        });
     if (!handle.completed && input.wait === true) {
-      handle = await waitLightweightPluginAction(
-        input.controllerHome,
-        input.repository.repoId,
-        handle.processId,
-        Math.max(1, input.waitMs ?? 15_000),
-        input.request.signal,
-      );
+      handle = input.scope.kind === 'controller'
+        ? await waitManagedControllerPluginAction(
+            input.controllerHome,
+            handle.processId,
+            Math.max(1, input.waitMs ?? 15_000),
+            input.request.signal,
+          )
+        : await waitManagedPluginAction(
+            input.controllerHome,
+            input.scope.repository.repoId,
+            handle.processId,
+            Math.max(1, input.waitMs ?? 15_000),
+            input.request.signal,
+          );
     }
     if (!handle.completed) {
       return {
-        kind: 'lightweight_running',
+        kind: 'managed_running',
         manifest,
         action,
         requestId: input.request.requestId,
@@ -117,19 +171,22 @@ export async function executeAssistantPluginActionApplication(input: {
     }
     if (!handle.ok) {
       return {
-        kind: 'lightweight_failed',
+        kind: 'managed_failed',
         manifest,
         action,
         requestId: input.request.requestId,
         process: handle,
       };
     }
-    // The sidecar writes the authoritative receipt. Re-enter the deterministic
-    // store with the same request id to read/bind that receipt without replay.
+    // The durable sidecar writes the authoritative receipt. Re-enter the
+    // deterministic store with the same request id to bind/read it without
+    // replaying the provider effect.
   }
 
   return {
     kind: 'submitted',
-    submitted: await submitAssistantPluginAction(input.controllerHome, input.repository, input.request),
+    submitted: input.scope.kind === 'controller'
+      ? await submitControllerPluginAction(input.controllerHome, input.request)
+      : await submitAssistantPluginAction(input.controllerHome, input.scope.repository, input.request),
   };
 }

package/src/runtime/plugins/app-store-connect-adapter.ts

@@ -16,6 +16,7 @@ import { readRepositoryPluginConfig, writeRepositoryPluginConfig } from './confi
 import { buildQueryString, encodeBase64Url, stableMockId } from './google-shared';
 
 const APP_STORE_CONNECT_PLUGIN_ID = 'app_store_connect';
+const CONTROLLER_PLUGIN_CONFIG_SCOPE = 'controller:global';
 const API_BASE_URL = 'https://api.appstoreconnect.apple.com';
 const DEFAULT_TIMEOUT_MS = 60_000;
 const PRIVATE_KEY_READ_MAX_ATTEMPTS = 4;
@@ -107,7 +108,7 @@ function repositoryConfig(repoRoot: string, controllerHome?: string, repoId?: st
 
 function loadConfig(repoRoot: string, controllerHome?: string, repoId?: string): AppStoreConnectPluginConfig {
   const global = controllerHome ? readConfigFile(globalConfigPath(controllerHome)) : undefined;
-  if (repoId === CONTROLLER_SCOPE_REPO_ID) return normalizeConfig(global ?? {});
+  if (repoId === CONTROLLER_SCOPE_REPO_ID || repoId === CONTROLLER_PLUGIN_CONFIG_SCOPE) return normalizeConfig(global ?? {});
   const local = repositoryConfig(repoRoot, controllerHome, repoId);
   return normalizeConfig({ ...(global ?? {}), ...(local ?? {}) });
 }
@@ -123,7 +124,7 @@ function saveConfig(
   repoId?: string,
 ): AppStoreConnectPluginConfig {
   const cleanPatch = definedPatch(patch);
-  if (controllerHome && repoId === CONTROLLER_SCOPE_REPO_ID) {
+  if (controllerHome && repoId === CONTROLLER_PLUGIN_CONFIG_SCOPE) {
     const path = globalConfigPath(controllerHome);
     const next = normalizeConfig({ ...(readConfigFile(path) ?? {}), ...cleanPatch });
     mkdirSync(dirname(path), { recursive: true });
@@ -131,6 +132,7 @@ function saveConfig(
     return next;
   }
 
+  if (repoId === CONTROLLER_SCOPE_REPO_ID) throw new Error('APP_STORE_CONNECT_LEGACY_CONTROLLER_SCOPE_WRITE_RETIRED');
   if (!controllerHome || !repoId) throw new Error('APP_STORE_CONNECT_CONTROLLER_CONTEXT_REQUIRED');
   // Repository state is an overlay only. Do not materialize inherited global
   // credential references into every repository just because configure ran.
@@ -199,9 +201,9 @@ async function readPrivateKeyFile(path: string, source: string): Promise<{ key?:
       }
       if (code === 'EDEADLK') {
         throw new AssistantPluginError(
-          'PLUGIN_PROVIDER_UNAVAILABLE',
-          'App Store Connect private key is temporarily unavailable because the filesystem is busy.',
-          { retryable: true, details: { credentialSource: source, code } },
+          'PLUGIN_AUTH_REQUIRED',
+          'Configured App Store Connect private key is not locally available. Keep File Provider/iCloud credentials downloaded or configure a stable local private_key_path.',
+          { retryable: false, details: { credentialSource: source, code, localCredentialUnavailable: true } },
         );
       }
       throw new AssistantPluginError(
@@ -211,7 +213,11 @@ async function readPrivateKeyFile(path: string, source: string): Promise<{ key?:
       );
     }
   }
-  throw new AssistantPluginError('PLUGIN_PROVIDER_UNAVAILABLE', 'App Store Connect private key is temporarily unavailable.', { retryable: true });
+  throw new AssistantPluginError(
+    'PLUGIN_AUTH_REQUIRED',
+    'Configured App Store Connect private key is not locally available.',
+    { retryable: false, details: { credentialSource: source, localCredentialUnavailable: true } },
+  );
 }
 
 async function privateKeyMaterial(config: AppStoreConnectPluginConfig): Promise<{ key?: string; source?: string; warning?: string }> {
@@ -223,6 +229,23 @@ async function privateKeyMaterial(config: AppStoreConnectPluginConfig): Promise<
   return {};
 }
 
+async function resolveLiveAuthStatus(config: AppStoreConnectPluginConfig): Promise<AppStoreConnectAuthState> {
+  const auth = resolveAuth(config);
+  if (config.provider !== 'app-store-connect-api' || !config.enabled || !auth.ready) return auth;
+  try {
+    const material = await privateKeyMaterial(config);
+    if (material.key) return auth;
+    const detail = material.warning ?? 'Configured App Store Connect private key is not locally readable.';
+    return { ...auth, ready: false, authenticated: false, errors: [...auth.errors, detail] };
+  } catch (error) {
+    if (error instanceof AssistantPluginError && error.code === 'PLUGIN_AUTH_REQUIRED') {
+      const detail = error.message.replace(/^PLUGIN_AUTH_REQUIRED:\s*/, '');
+      return { ...auth, ready: false, authenticated: false, errors: [...auth.errors, detail] };
+    }
+    throw error;
+  }
+}
+
 function resolveAuth(config: AppStoreConnectPluginConfig): AppStoreConnectAuthState {
   if (config.provider === 'mock') {
     return {
@@ -860,15 +883,16 @@ export async function executeAppStoreConnectPluginAction(input: AssistantPluginA
   if (config.provider === 'mock') return mockResponse(input.actionId, input.args, config);
   const auth = resolveAuth(config);
   if (input.actionId === 'auth_status') {
+    const liveAuth = await resolveLiveAuthStatus(config);
     return {
-      ready: config.enabled && auth.ready,
-      provider: auth.provider,
-      issuerId: auth.issuerId ? 'configured' : undefined,
-      keyId: auth.keyId ? 'configured' : undefined,
-      credentialSource: auth.credentialSource,
-      errors: auth.errors,
-      warnings: auth.warnings,
-      userFacingStatus: userFacingAscStatus(config, auth),
+      ready: config.enabled && liveAuth.ready,
+      provider: liveAuth.provider,
+      issuerId: liveAuth.issuerId ? 'configured' : undefined,
+      keyId: liveAuth.keyId ? 'configured' : undefined,
+      credentialSource: liveAuth.credentialSource,
+      errors: liveAuth.errors,
+      warnings: liveAuth.warnings,
+      userFacingStatus: userFacingAscStatus(config, liveAuth),
     };
   }
   if (!config.enabled || !auth.ready) throw new AssistantPluginError('PLUGIN_NOT_READY', 'App Store Connect plugin is not ready.', { retryable: false, details: { enabled: config.enabled, errors: auth.errors } });