@moretea-labs/forge 1.7.0 → 1.7.1

package/src/runtime/plugins/external-adapter.ts

@@ -248,13 +248,23 @@ function desktopSession(status: Record<string, unknown>, interactionId: string):
   return recordArray(status.sessions).find((session) => firstString(session, 'interactionId', 'interaction_id') === interactionId);
 }
 
-function desktopApplicationIsActive(status: Record<string, unknown>, bundleId: string, appName: string): boolean {
-  return recordArray(status.applications).some((application) => {
-    if (application.active !== true || application.terminated === true) return false;
-    const candidateBundleId = firstString(application, 'bundle_id', 'bundleIdentifier');
-    const candidateName = firstString(application, 'name', 'appName');
-    return bundleId ? candidateBundleId === bundleId : Boolean(appName) && candidateName === appName;
-  });
+async function independentlyEnsureExactFrontmostDesktopApplication(
+  bundleId: string,
+  appName: string,
+  dependencies: ExternalPluginAdapterDependencies,
+): Promise<void> {
+  const activateAndVerify = dependencies.activateAndVerifyFrontmostApplication ?? activateAndVerifyFrontmostApplication;
+  const proof = await activateAndVerify({ bundleId: bundleId || undefined, appName: appName || undefined });
+  const proofBundleId = typeof proof.bundleId === 'string' ? proof.bundleId.trim() : '';
+  const proofAppName = typeof proof.appName === 'string' ? proof.appName.trim() : '';
+  const proofMatches = bundleId ? proofBundleId === bundleId : proofAppName === appName;
+  if (proof.activated !== true || proof.verified !== true || !proofMatches) {
+    throw new AssistantPluginError(
+      'DESKTOP_ACTIVATION_FALLBACK_IDENTITY_MISMATCH',
+      `Forge did not prove the exact requested application ${bundleId || appName} as frontmost.`,
+      { retryable: true, details: { target: { bundleId, appName }, observed: { bundleId: proofBundleId, appName: proofAppName } } },
+    );
+  }
 }
 
 async function openVerifiedDesktopSession(
@@ -272,7 +282,7 @@ async function openVerifiedDesktopSession(
   }
 
   let result: Record<string, unknown>;
-  let fallbackVerified = false;
+  let providerActivationError: AssistantPluginError | undefined;
   try {
     result = await callProvider(
       registration,
@@ -285,7 +295,7 @@ async function openVerifiedDesktopSession(
     );
   } catch (error) {
     if (!(error instanceof AssistantPluginError) || error.code !== 'APP_ACTIVATION_FAILED') throw error;
-
+    providerActivationError = error;
     result = await callProvider(
       registration,
       `${requestId}:fallback-session`,
@@ -295,59 +305,36 @@ async function openVerifiedDesktopSession(
       signal,
       dependencies,
     );
-
-    const activateFallback = dependencies.activateAndVerifyFrontmostApplication ?? activateAndVerifyFrontmostApplication;
-    try {
-      const fallbackProof = await activateFallback({ bundleId: bundleId || undefined, appName: appName || undefined });
-      const proofBundleId = typeof fallbackProof.bundleId === 'string' ? fallbackProof.bundleId.trim() : '';
-      const proofAppName = typeof fallbackProof.appName === 'string' ? fallbackProof.appName.trim() : '';
-      const proofMatches = bundleId ? proofBundleId === bundleId : proofAppName === appName;
-      if (fallbackProof.activated !== true || fallbackProof.verified !== true || !proofMatches) {
-        throw new AssistantPluginError(
-          'DESKTOP_ACTIVATION_FALLBACK_IDENTITY_MISMATCH',
-          `Forge fallback did not prove the exact requested application ${bundleId || appName} as frontmost.`,
-          { retryable: true, details: { target: { bundleId, appName }, observed: { bundleId: proofBundleId, appName: proofAppName } } },
-        );
-      }
-      fallbackVerified = true;
-    } catch (fallbackError) {
-      if (fallbackError instanceof AssistantPluginError) {
-        throw new AssistantPluginError(
-          'DESKTOP_ACTIVATION_FALLBACK_FAILED',
-          `Desktop Operator activation failed and Forge could not independently verify ${bundleId || appName} as frontmost.`,
-          {
-            retryable: fallbackError.retryable,
-            details: {
-              providerErrorCode: error.code,
-              fallbackErrorCode: fallbackError.code,
-              fallbackErrorMessage: fallbackError.message,
-              target: bundleId || appName,
-            },
-          },
-        );
-      }
-      throw new AssistantPluginError(
-        'DESKTOP_ACTIVATION_FALLBACK_FAILED',
-        `Desktop Operator activation failed and Forge fallback failed for ${bundleId || appName}.`,
-        { retryable: true, details: { providerErrorCode: error.code, fallbackErrorMessage: String(fallbackError), target: bundleId || appName } },
-      );
-    }
   }
 
-  if (!fallbackVerified) {
-    const activeStatus = await callProvider(
-      registration,
-      `${requestId}:active-status`,
-      'desktop_status',
-      { limit: 500 },
-      timeoutMs,
-      signal,
-      dependencies,
-    );
-    if (!desktopApplicationIsActive(activeStatus, bundleId, appName)) {
-      throw providerError('DESKTOP_ACTIVATION_NOT_CONFIRMED', `Desktop Operator did not confirm ${bundleId || appName} as the frontmost application after activation.`, true);
+  try {
+    await independentlyEnsureExactFrontmostDesktopApplication(bundleId, appName, dependencies);
+  } catch (verificationError) {
+    const wrappedCode = providerActivationError ? 'DESKTOP_ACTIVATION_FALLBACK_FAILED' : 'DESKTOP_ACTIVATION_NOT_CONFIRMED';
+    const wrappedMessage = providerActivationError
+      ? `Desktop Operator activation failed and Forge could not independently verify ${bundleId || appName} as frontmost.`
+      : `Desktop Operator returned an activated session, but Forge could not independently verify ${bundleId || appName} as frontmost.`;
+    if (verificationError instanceof AssistantPluginError) {
+      throw new AssistantPluginError(wrappedCode, wrappedMessage, {
+        retryable: verificationError.retryable,
+        details: {
+          ...(providerActivationError ? { providerErrorCode: providerActivationError.code } : {}),
+          verificationErrorCode: verificationError.code,
+          verificationErrorMessage: verificationError.message,
+          target: bundleId || appName,
+        },
+      });
     }
+    throw new AssistantPluginError(wrappedCode, wrappedMessage, {
+      retryable: true,
+      details: {
+        ...(providerActivationError ? { providerErrorCode: providerActivationError.code } : {}),
+        verificationErrorMessage: String(verificationError),
+        target: bundleId || appName,
+      },
+    });
   }
+
   return result;
 }
 
@@ -616,6 +603,53 @@ export function createExternalPluginAdapter(
         };
       }
 
+      if (registration.pluginId === 'desktop_operator' && input.actionId === 'desktop_key') {
+        const sourceInteractionId = typeof input.args.interaction_id === 'string' ? input.args.interaction_id.trim() : '';
+        const keys = Array.isArray(input.args.keys) ? input.args.keys : [];
+        if (!sourceInteractionId || keys.length === 0) {
+          throw providerError('DESKTOP_FOREGROUND_KEY_ARGUMENT_INVALID', 'desktop_key requires interaction_id and at least one key.');
+        }
+        const sourceStatus = await callProvider(
+          registration,
+          `${input.requestId}:source-status`,
+          'desktop_status',
+          { limit: 500 },
+          input.timeoutMs,
+          input.signal,
+          dependencies,
+        );
+        const sourceSession = desktopSession(sourceStatus, sourceInteractionId);
+        if (!sourceSession) {
+          throw providerError('DESKTOP_FOREGROUND_KEY_SESSION_NOT_FOUND', `Desktop session ${sourceInteractionId} is no longer available.`, true);
+        }
+        const bundleId = firstString(sourceSession, 'bundleIdentifier', 'bundle_id');
+        const appName = firstString(sourceSession, 'appName', 'app_name');
+        if (!bundleId && !appName) {
+          throw providerError('DESKTOP_FOREGROUND_KEY_TARGET_UNAVAILABLE', `Desktop session ${sourceInteractionId} has no stable application identity.`);
+        }
+        const activation = await openVerifiedDesktopSession(
+          registration,
+          `${input.requestId}:activate`,
+          { ...(bundleId ? { bundle_id: bundleId } : { app_name: appName }), launch: false, activate: true },
+          input.timeoutMs,
+          input.signal,
+          dependencies,
+        );
+        const activationInteractionId = firstString(activation, 'interactionId', 'interaction_id');
+        if (!activationInteractionId) {
+          throw providerError('DESKTOP_ACTIVATION_SESSION_MISSING', 'Desktop Operator activated the application without returning a bound interaction session.', true);
+        }
+        return await callProvider(
+          registration,
+          `${input.requestId}:key`,
+          'desktop_key',
+          { interaction_id: activationInteractionId, keys },
+          input.timeoutMs,
+          input.signal,
+          dependencies,
+        );
+      }
+
       if (registration.pluginId === 'desktop_operator' && input.actionId === 'desktop_session_open' && input.args.activate === true) {
         return await openVerifiedDesktopSession(
           registration,

package/src/runtime/plugins/macos-capability-broker.ts

@@ -54,14 +54,6 @@ export function validateMacOsCapabilityBrokerHandshake(
     ? handshake.browserAutomationActions.filter((entry): entry is string => typeof entry === 'string')
     : [];
   const browserProtocolVersion = handshake.browserAutomationProtocolVersion;
-  const declaresBrowserMetadata = Array.isArray(handshake.internalCapabilities)
-    || Array.isArray(handshake.browserAutomationActions)
-    || browserProtocolVersion !== undefined;
-  // Desktop Operator v0.2.1 predates optional browser capability metadata in its handshake,
-  // but it implements the separately routed macos_browser_automation method. In that legacy
-  // shape, let the real method/action call prove support. Unsupported methods/actions still
-  // fail closed at the provider boundary.
-  if (!declaresBrowserMetadata) return;
   if (!capabilities.includes(BROWSER_AUTOMATION_CAPABILITY)
     || browserProtocolVersion !== BROWSER_AUTOMATION_PROTOCOL_VERSION
     || (requestedAction && !actions.includes(requestedAction))) {

package/src/runtime/plugins/store.ts

@@ -598,6 +598,8 @@ export interface PluginActionReceipt {
   receiptId: string;
   requestId: string;
   repoId: string;
+  /** Work authority repository when it differs from controller/provider receipt scope. */
+  workRepoId?: string;
   pluginId: string;
   actionId: string;
   semanticKey: string;
@@ -613,6 +615,7 @@ export interface PluginActionReceipt {
 interface PluginActionRequestIndex {
   requestId: string;
   repoId: string;
+  workRepoId?: string;
   receiptId: string;
   semanticKey: string;
   createdAt: string;
@@ -733,6 +736,15 @@ function localEffectTarget(
   };
 }
 
+function workAttributionRepoId(repository: RepositoryRecord, request: AssistantPluginActionRequest): string {
+  const explicit = request.workRepoId?.trim();
+  if (!request.workId?.trim()) {
+    if (explicit) throw new Error(`WORK_PLUGIN_ATTRIBUTION_REPO_WITHOUT_WORK: ${explicit}`);
+    return repository.repoId;
+  }
+  return explicit || repository.repoId;
+}
+
 function remoteEffectWorkForPluginAction(
   controllerHome: string,
   repository: RepositoryRecord,
@@ -745,7 +757,8 @@ function remoteEffectWorkForPluginAction(
   if (action.risk !== 'remote_write') {
     throw new Error(`WORK_PLUGIN_RECEIPT_BINDING_REQUIRES_REMOTE_WRITE: ${action.actionId}`);
   }
-  const work = getWorkContract({ controllerHome, repoId: repository.repoId }, workId);
+  const workRepoId = workAttributionRepoId(repository, request);
+  const work = getWorkContract({ controllerHome, repoId: workRepoId }, workId);
   if (!work) throw new Error(`WORK_PLUGIN_RECEIPT_BINDING_NOT_FOUND: ${workId}`);
   if (work.workKind !== 'remote_effect') {
     throw new Error(`WORK_PLUGIN_RECEIPT_BINDING_KIND_MISMATCH: ${workId} is ${work.workKind}, expected remote_effect`);
@@ -772,14 +785,38 @@ function attributedWorkForPluginAction(
 ): WorkContract | undefined {
   const workId = request.workId?.trim();
   if (!workId || action.risk === 'remote_write') return undefined;
-  const work = getWorkContract({ controllerHome, repoId: repository.repoId }, workId);
-  if (!work) throw new Error(`WORK_PLUGIN_ATTRIBUTION_NOT_FOUND: ${workId}`);
+  const workRepoId = workAttributionRepoId(repository, request);
+  const work = getWorkContract({ controllerHome, repoId: workRepoId }, workId);
+  if (!work) throw new Error(`WORK_PLUGIN_ATTRIBUTION_NOT_FOUND: ${workRepoId}:${workId}`);
   if (isTerminalWorkContractStatus(work.status)) {
     throw new Error(`WORK_PLUGIN_ATTRIBUTION_TERMINAL: ${workId} is ${work.status}`);
   }
   return work;
 }
 
+function bindLocalEffectReceiptToAttributedWork(
+  controllerHome: string,
+  repository: RepositoryRecord,
+  action: AssistantPluginActionDescriptor,
+  request: AssistantPluginActionRequest,
+  receipt: PluginActionReceipt,
+  work?: WorkContract,
+): WorkContract | undefined {
+  if (!request.workId || receipt.status !== 'succeeded') return work;
+  const workRepoId = workAttributionRepoId(repository, request);
+  const attributed = work ?? getWorkContract({ controllerHome, repoId: workRepoId }, request.workId.trim());
+  if (!attributed) throw new Error(`WORK_PLUGIN_ATTRIBUTION_NOT_FOUND: ${workRepoId}:${request.workId.trim()}`);
+  if (attributed.workKind !== 'local_effect' || action.readOnly || action.risk === 'readonly') return attributed;
+  if (attributed.evidenceRefs.some((evidence) => evidence.evidenceId === receipt.receiptId)) return attributed;
+  if (isTerminalWorkContractStatus(attributed.status)) return attributed;
+  return appendWorkEvidence({ controllerHome, repoId: workRepoId }, attributed.workId, {
+    evidenceId: receipt.receiptId,
+    title: 'typed local plugin effect completed',
+    summary: `${receipt.pluginId}/${receipt.actionId} completed with durable receipt ${receipt.receiptId}.`,
+    detailLevel: 'summary',
+  });
+}
+
 export function finalizeRemoteEffectWorkFromActionReceipt(
   controllerHome: string,
   repoId: string,
@@ -795,7 +832,11 @@ export function finalizeRemoteEffectWorkFromActionReceipt(
     throw new Error(`WORK_REMOTE_EFFECT_FINALIZE_TERMINAL: ${workId} is ${work.status}`);
   }
   const receipt = work.evidenceRefs
-    .map((evidence) => evidence.evidenceId ? readPluginActionReceipt(controllerHome, repoId, evidence.evidenceId) : undefined)
+    .map((evidence) => {
+      if (!evidence.evidenceId) return undefined;
+      return readPluginActionReceipt(controllerHome, repoId, evidence.evidenceId)
+        ?? readPluginActionReceipt(controllerHome, CONTROLLER_SCOPE_REPO_ID, evidence.evidenceId);
+    })
     .find((candidate) => candidate?.workId === workId && candidate.status === 'succeeded');
   if (!receipt) {
     throw new Error(`WORK_REMOTE_EFFECT_FINALIZE_RECEIPT_REQUIRED: ${workId} has no successful durable plugin action receipt`);
@@ -833,9 +874,10 @@ function bindRemoteEffectReceiptToWork(
   const work = remoteEffectWorkForPluginAction(controllerHome, repository, action, request, receipt.receiptId);
   if (!work) return undefined;
   if (work.status === 'completed') return work;
+  const workRepoId = workAttributionRepoId(repository, request);
   let updated = work;
   if (!work.evidenceRefs.some((evidence) => evidence.evidenceId === receipt.receiptId)) {
-    updated = appendWorkEvidence({ controllerHome, repoId: repository.repoId }, work.workId, {
+    updated = appendWorkEvidence({ controllerHome, repoId: workRepoId }, work.workId, {
       evidenceId: receipt.receiptId,
       title: 'typed remote plugin effect completed',
       summary: `${receipt.pluginId}/${receipt.actionId} completed with durable receipt ${receipt.receiptId}.`,
@@ -856,7 +898,7 @@ function bindRemoteEffectReceiptToWork(
     recordedAt: new Date().toISOString(),
   };
   return recordWorkCompletionReceipt(
-    { controllerHome, repoId: repository.repoId },
+    { controllerHome, repoId: workRepoId },
     work.workId,
     remoteReceipt,
     'completed_remote',
@@ -940,7 +982,15 @@ export async function submitAssistantPluginAction(
     if (request.workId && existing.workId !== request.workId) {
       throw new Error(`WORK_PLUGIN_RECEIPT_BINDING_CONFLICT: ${request.requestId} already belongs to Work ${existing.workId ?? 'none'}`);
     }
-    if (request.workId && action.risk === 'remote_write') bindRemoteEffectReceiptToWork(controllerHome, repository, action, request, existing);
+    const requestedWorkRepoId = request.workId ? workAttributionRepoId(repository, request) : undefined;
+    if (requestedWorkRepoId && (index.workRepoId ?? index.repoId) !== requestedWorkRepoId) {
+      throw new Error(`WORK_PLUGIN_ATTRIBUTION_REPO_CONFLICT: ${request.requestId} already belongs to Work repository ${index.workRepoId ?? index.repoId}`);
+    }
+    if (request.workId && action.risk === 'remote_write') {
+      bindRemoteEffectReceiptToWork(controllerHome, repository, action, request, existing);
+    } else if (request.workId) {
+      bindLocalEffectReceiptToAttributedWork(controllerHome, repository, action, request, existing);
+    }
     return {
       manifest,
       action,
@@ -1181,6 +1231,7 @@ export async function submitAssistantPluginAction(
       receiptId,
       requestId: request.requestId,
       repoId: repository.repoId,
+      ...(request.workId ? { workRepoId: workAttributionRepoId(repository, request) } : {}),
       pluginId: request.pluginId,
       actionId: request.actionId,
       semanticKey: key,
@@ -1201,11 +1252,16 @@ export async function submitAssistantPluginAction(
     writeJsonAtomic(requestPath, {
       requestId: request.requestId,
       repoId: repository.repoId,
+      ...(request.workId ? { workRepoId: workAttributionRepoId(repository, request) } : {}),
       receiptId,
       semanticKey: key,
       createdAt,
     } satisfies PluginActionRequestIndex);
-    if (boundRemoteWork) bindRemoteEffectReceiptToWork(controllerHome, repository, action, request, receipt);
+    if (boundRemoteWork) {
+      bindRemoteEffectReceiptToWork(controllerHome, repository, action, request, receipt);
+    } else if (attributedWork) {
+      bindLocalEffectReceiptToAttributedWork(controllerHome, repository, action, request, receipt, attributedWork);
+    }
     const nextManifest = getAssistantPluginManifest(controllerHome, repository, request.pluginId);
     return {
       manifest: nextManifest,
@@ -1221,7 +1277,7 @@ export async function submitAssistantPluginAction(
     const message = error instanceof Error ? error.message : String(error);
     const code = /^([A-Z][A-Z0-9_]+)/.exec(message)?.[1] ?? 'PLUGIN_ACTION_FAILED';
     if (boundRemoteWork) {
-      appendWorkEvidence({ controllerHome, repoId: repository.repoId }, boundRemoteWork.workId, {
+      appendWorkEvidence({ controllerHome, repoId: workAttributionRepoId(repository, request) }, boundRemoteWork.workId, {
         title: 'typed remote plugin effect failed',
         summary: `${request.pluginId}/${request.actionId}: ${message}`.slice(0, 1_000),
         detailLevel: 'summary',
@@ -1246,6 +1302,7 @@ export async function submitAssistantPluginAction(
       receiptId,
       requestId: request.requestId,
       repoId: repository.repoId,
+      ...(request.workId ? { workRepoId: workAttributionRepoId(repository, request) } : {}),
       pluginId: request.pluginId,
       actionId: request.actionId,
       semanticKey: key,

package/src/runtime/plugins/types.ts

@@ -124,8 +124,10 @@ export interface AssistantPluginActionRequest {
   pluginId: string;
   actionId: string;
   requestId: string;
-  /** Optional existing external-effect Work that owns this typed action receipt. */
+  /** Optional existing Work that owns this typed action receipt. */
   workId?: string;
+  /** Durable repository authority for workId. May differ from provider scope for controller-scoped plugins. */
+  workRepoId?: string;
   args: Record<string, unknown>;
   timeoutMs?: number;
   signal?: AbortSignal;

package/src/runtime/recovery/maintenance-executor.ts

@@ -91,7 +91,7 @@ export interface RuntimeMaintenanceCandidate {
   sourceControllerHome?: string;
   objective?: string;
   continuationPrompt?: string;
-  disposition?: 'resume_or_supersede_review' | 'completion_reconciliation' | 'ownership_reconciliation' | 'source_preservation_required';
+  disposition?: 'resume_or_supersede_review' | 'completion_reconciliation' | 'ownership_reconciliation' | 'source_preservation_required' | 'semantic_completion_required';
   sourceState?: 'no_managed_source' | 'clean_integrated' | 'dirty_worktree' | 'unintegrated_commits' | 'source_state_unknown';
 }
 
@@ -584,10 +584,20 @@ function inspectStaleWorkRepositorySource(
   };
 }
 
-function staleWorkCandidateReason(source: StaleWorkSourceInspection): string {
-  return source.safeToCancel
-    ? `Nonterminal WorkContract exceeded the explicit maintenance age threshold and has no active Plan, Requirement, Schedule, or Controller authority. ${source.detail} Explicit full maintenance may cancel Work metadata while retaining durable evidence.`
-    : `Protected stale Work: no active lifecycle authority remains, but repository source preservation is required. ${source.detail} The Work must remain nonterminal until source is explicitly adopted, delivered, or cleanup is semantically authorized.`;
+function staleWorkSemanticTerminalizationReady(contract: WorkContract): boolean {
+  if (contract.phase !== 'cleanup') return false;
+  return (['implementation', 'verification', 'delivery'] as const).every((phase) =>
+    ['satisfied', 'skipped'].includes(contract.phaseEvidence[phase].state));
+}
+
+function staleWorkCandidateReason(source: StaleWorkSourceInspection, semanticReady: boolean): string {
+  if (!source.safeToCancel) {
+    return `Protected stale Work: no active lifecycle authority remains, but repository source preservation is required. ${source.detail} The Work must remain nonterminal until source is explicitly adopted, delivered, or cleanup is semantically authorized.`;
+  }
+  if (!semanticReady) {
+    return `Protected stale Work: repository source has no unique live changes, but the Work semantic lifecycle has not reached cleanup with implementation, verification, and delivery explicitly satisfied or skipped. ${source.detail} Maintenance may clean source debt, but it cannot infer that the objective or acceptance criteria are complete.`;
+  }
+  return `Cleanup-ready WorkContract exceeded the explicit maintenance age threshold and has no active Plan, Requirement, Schedule, or Controller authority. ${source.detail} Explicit full maintenance may finish cleanup while retaining durable evidence.`;
 }
 
 function scanRetainedWorktreeCandidates(
@@ -738,19 +748,26 @@ function scanStaleWorkContractCandidates(
     })
     .sort((left, right) => right.ageMinutes - left.ageMinutes)
     .slice(0, options.maxCandidates)
-    .map(({ contract, ageMinutes, source }) => ({
-      kind: 'stale_work_contract' as const,
-      id: contract.workId,
-      path: source.path,
-      status: contract.status,
-      safe: source.safeToCancel,
-      reason: staleWorkCandidateReason(source),
-      ageMinutes,
-      suggestedAction: 'full_maintenance_pass' as const,
-      ownershipStatus: 'explicit' as const,
-      sourceState: source.state,
-      disposition: source.safeToCancel ? undefined : ('source_preservation_required' as const),
-    }));
+    .map(({ contract, ageMinutes, source }) => {
+      const semanticReady = staleWorkSemanticTerminalizationReady(contract);
+      return {
+        kind: 'stale_work_contract' as const,
+        id: contract.workId,
+        path: source.path,
+        status: contract.status,
+        safe: source.safeToCancel && semanticReady,
+        reason: staleWorkCandidateReason(source, semanticReady),
+        ageMinutes,
+        suggestedAction: 'full_maintenance_pass' as const,
+        ownershipStatus: 'explicit' as const,
+        sourceState: source.state,
+        disposition: !source.safeToCancel
+          ? ('source_preservation_required' as const)
+          : !semanticReady
+            ? ('semantic_completion_required' as const)
+            : undefined,
+      };
+    });
 }
 
 export function applyStaleWorkContractMaintenanceCandidate(
@@ -794,25 +811,38 @@ export function applyStaleWorkContractMaintenanceCandidate(
           ...candidate,
           path: source.path ?? candidate.path,
           safe: false,
-          reason: staleWorkCandidateReason(source),
+          reason: staleWorkCandidateReason(source, staleWorkSemanticTerminalizationReady(current)),
           sourceState: source.state,
           disposition: 'source_preservation_required' as const,
           applied: false,
           result: `work_source_preserved:${source.state}`,
         };
       }
+      const semanticReady = staleWorkSemanticTerminalizationReady(current);
+      if (!semanticReady) {
+        return {
+          ...candidate,
+          path: source.path ?? candidate.path,
+          safe: false,
+          reason: staleWorkCandidateReason(source, false),
+          sourceState: source.state,
+          disposition: 'semantic_completion_required' as const,
+          applied: false,
+          result: 'work_semantic_completion_required',
+        };
+      }
       transitionWorkContractPhase({ controllerHome, repoId: repository.repoId }, current.workId, {
         phase: 'cleanup',
         status: 'cancelled',
         state: 'skipped',
-        summary: 'Cancelled by explicit full maintenance stale Work cleanup after proving no unique live repository source; durable evidence retained.',
+        summary: 'Cancelled by explicit full maintenance after the Work had already reached cleanup with prior semantic phases satisfied and no unique live repository source remained; durable evidence retained.',
         evidenceRefs: current.evidenceRefs,
       });
       return {
         ...candidate,
         path: source.path ?? candidate.path,
         safe: true,
-        reason: staleWorkCandidateReason(source),
+        reason: staleWorkCandidateReason(source, true),
         sourceState: source.state,
         disposition: undefined,
         applied: true,
@@ -856,14 +886,20 @@ function scanStaleEditSessionCandidates(
     .filter(({ ageMinutes }) => ageMinutes >= options.minAgeMinutes)
     .sort((left, right) => right.ageMinutes - left.ageMinutes)
     .slice(0, options.maxCandidates)
-    .map(({ session, ageMinutes }) => {
+    .flatMap(({ session, ageMinutes }) => {
       const work = session.workId
         ? getWorkContract({ controllerHome, repoId: repository.repoId }, session.workId)
         : undefined;
       const terminalWork = Boolean(work && isTerminalWorkContractStatus(work.status));
+      if (work && !terminalWork && activeWorkAuthorityRefs(repository, controllerHome, work).length > 0) {
+        // The Edit Session inherits the live Work lifecycle authority. Reporting it
+        // as stale maintenance debt while that authority is active would duplicate
+        // ownership and can permanently block release readiness for valid long work.
+        return [];
+      }
       const contractFreeDirect = !session.workId;
       const safeToReconcile = terminalWork || contractFreeDirect;
-      return {
+      return [{
         kind: 'stale_edit_session' as const,
         id: session.sessionId,
         status: session.status,
@@ -872,11 +908,11 @@ function scanStaleEditSessionCandidates(
           ? 'Edit Session belongs to a terminal WorkContract; cleanup may reconcile metadata only and must refuse unique uncommitted source changes.'
           : contractFreeDirect
             ? 'Contract-free Direct Edit Session has no WorkContract by design; cleanup may reconcile metadata only and must refuse unique uncommitted source changes.'
-            : 'Edit Session WorkContract is missing or still nonterminal; active-session ownership must remain fenced.',
+            : 'Edit Session WorkContract is missing or still nonterminal without live lifecycle authority; active-session ownership must remain fenced.',
         ageMinutes,
         suggestedAction: 'full_maintenance_pass' as const,
         ownershipStatus: safeToReconcile ? 'explicit' as const : 'unknown' as const,
-      };
+      }];
     });
 }
 

package/src/runtime/root/package-connector-service.ts

@@ -122,13 +122,40 @@ async function defaultConnectorEndpointProbe(endpoint: string): Promise<boolean>
   }
 }
 
+export async function waitForPackageConnectorEndpointReady(
+  endpoint: string,
+  options: {
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    probeEndpoint?: (endpoint: string) => Promise<boolean>;
+    wait?: (ms: number) => Promise<void>;
+    now?: () => number;
+  } = {},
+): Promise<boolean> {
+  const timeoutMs = Math.max(0, options.timeoutMs ?? 15_000);
+  const pollIntervalMs = Math.max(10, options.pollIntervalMs ?? 100);
+  const probeEndpoint = options.probeEndpoint ?? defaultConnectorEndpointProbe;
+  const wait = options.wait ?? ((ms: number) => new Promise<void>((resolveWait) => setTimeout(resolveWait, ms)));
+  const now = options.now ?? Date.now;
+  const deadline = now() + timeoutMs;
+  do {
+    if (await probeEndpoint(endpoint)) return true;
+    if (now() >= deadline) return false;
+    await wait(Math.min(pollIntervalMs, Math.max(1, deadline - now())));
+  } while (now() <= deadline);
+  return false;
+}
+
 export function packageConnectorLaunchSpec(input: { release: PackageConnectorReleaseBinding; controllerHome: string; endpoint: string; executable?: string }): { executable: string; args: string[]; environment: Record<string, string>; port: number } {
   const parsed = new URL(input.endpoint);
   const port = Number(parsed.port);
   if (parsed.protocol !== 'http:' || parsed.hostname !== '127.0.0.1' || parsed.pathname !== '/mcp' || !Number.isInteger(port) || port < 1 || port > 65_535) {
     throw new Error('FORGE_PACKAGE_CONNECTOR_ENDPOINT_INVALID');
   }
-  const executable = resolve(input.executable ?? process.execPath);
+  const executable = resolve(input.executable ?? process.env.FORGE_CONNECTOR_EXECUTABLE ?? process.execPath);
+  if (/^forge-recovery-(?:gateway|watchdog)$/i.test(basename(executable))) {
+    throw new Error('FORGE_PACKAGE_CONNECTOR_EXECUTABLE_INVALID');
+  }
   const packageRoot = resolve(input.release.packageRoot);
   const cliEntry = join(packageRoot, 'src', 'cli', 'index.ts');
   const nodeLoader = join(packageRoot, 'src', 'runtime', 'shared', 'node-ts-loader.mjs');
@@ -168,6 +195,7 @@ export function packageConnectorServiceMatchesRelease(input: {
   endpoint: string;
   platform: NodeJS.Platform;
   env?: NodeJS.ProcessEnv;
+  executable?: string;
 }): boolean {
   try {
     if (
@@ -176,7 +204,12 @@ export function packageConnectorServiceMatchesRelease(input: {
       || resolve(input.authority.releaseRoot) !== resolve(input.release.releaseRoot)
       || resolve(input.authority.packageRoot) !== resolve(input.release.packageRoot)
     ) return false;
-    const launch = packageConnectorLaunchSpec({ release: input.release, controllerHome: input.controllerHome, endpoint: input.endpoint });
+    const launch = packageConnectorLaunchSpec({
+      release: input.release,
+      controllerHome: input.controllerHome,
+      endpoint: input.endpoint,
+      executable: input.executable,
+    });
     if (input.platform === 'darwin') {
       const paths = packageConnectorServicePaths(input.controllerHome, input.env?.HOME);
       if (input.authority.mode !== 'launchd' || !input.authority.servicePath) return false;
@@ -226,10 +259,15 @@ function startPortable(paths: PackageConnectorServicePaths, launch: ReturnType<t
   } finally { closeSync(stdout); closeSync(stderr); }
 }
 
-export async function installPackageConnectorService(input: { release: PackageConnectorReleaseBinding; controllerHome: string; endpoint: string; platform?: NodeJS.Platform; env?: NodeJS.ProcessEnv; forcePortable?: boolean }): Promise<PackageConnectorServiceResult> {
+export async function installPackageConnectorService(input: { release: PackageConnectorReleaseBinding; controllerHome: string; endpoint: string; executable?: string; platform?: NodeJS.Platform; env?: NodeJS.ProcessEnv; forcePortable?: boolean; probeEndpoint?: (endpoint: string) => Promise<boolean> }): Promise<PackageConnectorServiceResult> {
   const paths = packageConnectorServicePaths(input.controllerHome, input.env?.HOME);
   mkdirSync(join(paths.serviceRoot, 'logs'), { recursive: true, mode: 0o700 });
-  const launch = packageConnectorLaunchSpec({ release: input.release, controllerHome: input.controllerHome, endpoint: input.endpoint });
+  const launch = packageConnectorLaunchSpec({
+    release: input.release,
+    controllerHome: input.controllerHome,
+    endpoint: input.endpoint,
+    executable: input.executable,
+  });
   const platform = input.platform ?? process.platform, env = input.env ?? process.env;
   if (!input.forcePortable && platform === 'darwin') {
     await retireConflictingForgeLaunchAgents({
@@ -243,6 +281,8 @@ export async function installPackageConnectorService(input: { release: PackageCo
     installLaunchAgent(paths.sourcePlistPath, paths.label);
     const result = await bootstrapLaunchAgentWithRetryV2({ label: paths.label, plistPath: paths.installedPlistPath });
     if (!result.ok) throw new Error(`FORGE_PACKAGE_CONNECTOR_LAUNCHD_INSTALL_FAILED: ${result.diagnostics.join('; ')}`);
+    const endpointReady = await waitForPackageConnectorEndpointReady(input.endpoint, { probeEndpoint: input.probeEndpoint });
+    if (!endpointReady) throw new Error(`FORGE_PACKAGE_CONNECTOR_ENDPOINT_NOT_READY: ${input.endpoint}`);
     const installed = { endpoint: input.endpoint, mode: 'launchd' as const, persistent: true, servicePath: paths.installedPlistPath, releaseId: input.release.releaseId, releaseRoot: input.release.releaseRoot };
     writePackageConnectorServiceAuthority({ release: input.release, controllerHome: input.controllerHome, result: installed });
     return installed;
@@ -264,6 +304,7 @@ export async function ensurePackageConnectorService(input: {
   release: PackageConnectorReleaseBinding;
   controllerHome: string;
   endpoint: string;
+  executable?: string;
   platform?: NodeJS.Platform;
   env?: NodeJS.ProcessEnv;
   forcePortable?: boolean;
@@ -296,6 +337,7 @@ export async function ensurePackageConnectorService(input: {
         endpoint: input.endpoint,
         platform,
         env: input.env,
+        executable: input.executable,
       })
       && await (input.probeEndpoint ?? defaultConnectorEndpointProbe)(input.endpoint)
     ) {