@moretea-labs/forge 1.6.0 → 1.7.0

package/src/runtime/control-plane/facade/controller-session-store.ts

@@ -4,7 +4,8 @@ import { withControllerLock } from '../../../cli/repositories/locks';
 import { peekExecutionSession } from '../execution/session-store';
 import { readJsonFile } from '../../shared/json-files';
 import { readOrImportControlPlaneRecord, writeControlPlaneRecord } from '../persistence/sqlite-store';
-import type { ControllerSession, ControllerSessionStore, ControllerType } from './types';
+import { getWorkContract } from './work-contract-store';
+import { isTerminalWorkContractStatus, type ControllerSession, type ControllerSessionStore, type ControllerType } from './types';
 
 export interface ControllerSessionStoreOptions { controllerHome: string; repoId: string; now?: () => string; }
 
@@ -48,17 +49,43 @@ function write(options: ControllerSessionStoreOptions, store: ControllerSessionS
   });
 }
 
+const DEFAULT_CONTROLLER_RECOVERY_GRACE_MS = 10 * 60_000;
+const MAX_CONTROLLER_RECOVERY_GRACE_MS = 60 * 60_000;
+
 function activeSession(store: ControllerSessionStore, workId: string): ControllerSession | undefined {
   const at = Date.now();
   return store.sessions.find((session) => session.workId === workId && Date.parse(session.leaseExpiresAt) > at);
 }
 
+export function controllerSessionBlocksRecovery(
+  options: ControllerSessionStoreOptions,
+  workId: string,
+  input: { nowMs?: number; graceMs?: number } = {},
+): boolean {
+  const owner = activeSession(read(options), workId);
+  if (!owner) return false;
+  const execution = peekExecutionSession(options.controllerHome, owner.sessionId);
+  if (!execution?.invalidatedAt) return true;
+  const invalidatedAtMs = Date.parse(execution.invalidatedAt);
+  if (!Number.isFinite(invalidatedAtMs)) return true;
+  const nowMs = input.nowMs ?? Date.now();
+  const graceMs = Math.max(60_000, Math.min(input.graceMs ?? DEFAULT_CONTROLLER_RECOVERY_GRACE_MS, MAX_CONTROLLER_RECOVERY_GRACE_MS));
+  return nowMs - invalidatedAtMs < graceMs;
+}
+
 function assertIdentity(input: ControllerSessionClaimInput): void {
   if (!input.workId.trim() || !input.controllerId.trim() || !input.sessionId.trim()) {
     throw new Error('CONTROLLER_SESSION_IDENTITY_REQUIRED');
   }
 }
 
+function assertWorkClaimable(options: ControllerSessionStoreOptions, workId: string): void {
+  const work = getWorkContract({ controllerHome: options.controllerHome, repoId: options.repoId }, workId);
+  if (work && isTerminalWorkContractStatus(work.status)) {
+    throw new Error(`WORK_CONTROLLER_CLAIM_TERMINAL: ${work.workId}:${work.status}`);
+  }
+}
+
 function claimedSession(
   options: ControllerSessionStoreOptions,
   input: ControllerSessionClaimInput,
@@ -123,6 +150,108 @@ export function listControllerSessions(options: ControllerSessionStoreOptions):
   return read(options).sessions.filter((session) => Date.parse(session.leaseExpiresAt) > at);
 }
 
+export interface ControllerTerminalizationAuthority {
+  controllerId: string;
+  controllerType: ControllerType;
+  principalId: string;
+  controllerInstanceId: string;
+  claimGeneration: number;
+}
+
+export type ControllerTerminalizationFenceReason =
+  | 'active_controller_claim'
+  | 'stale_controller_authority'
+  | 'controller_claim_missing';
+
+export type ControllerTerminalizationFenceResult<T> =
+  | { allowed: true; value: T; owner?: ControllerSession }
+  | { allowed: false; reason: ControllerTerminalizationFenceReason; owner?: ControllerSession };
+
+function controllerTerminalizationAuthorityMatches(
+  owner: ControllerSession,
+  authority: ControllerTerminalizationAuthority,
+): boolean {
+  const ownerPrincipal = owner.principalId?.trim() || owner.controllerId;
+  const ownerInstanceId = owner.controllerInstanceId?.trim() || '';
+  return owner.controllerId === authority.controllerId
+    && owner.controllerType === authority.controllerType
+    && ownerPrincipal === authority.principalId.trim()
+    && ownerInstanceId === authority.controllerInstanceId.trim()
+    && owner.claimGeneration === authority.claimGeneration;
+}
+
+/**
+ * Serialize control-path Work terminalization against the same canonical
+ * ControllerSession task lock used by claim/resume/release. This is a fence,
+ * not a second lifecycle authority: WorkContract remains the terminal state
+ * authority and ControllerSession remains the ownership authority.
+ *
+ * A caller without Controller authority may terminalize only while the Work is
+ * unclaimed. A caller that observed a live owner must present that exact durable
+ * owner epoch. Transport session ids are intentionally not compared because MCP
+ * transports may rotate without moving Work ownership; controller instance plus
+ * claim generation fence stale controller epochs while preserving that rotation.
+ */
+export function withControllerSessionTerminalizationFence<T>(
+  options: ControllerSessionStoreOptions,
+  input: {
+    workId: string;
+    actor: string;
+    authority?: ControllerTerminalizationAuthority;
+  },
+  operation: () => T,
+): ControllerTerminalizationFenceResult<T> {
+  return withControllerLock(
+    options.controllerHome,
+    { scope: 'task', repoId: options.repoId, taskId: `controller-session-${input.workId}` },
+    input.actor,
+    () => {
+      const owner = activeSession(read(options), input.workId);
+      if (!owner) {
+        if (input.authority) return { allowed: false, reason: 'controller_claim_missing' };
+        return { allowed: true, value: operation() };
+      }
+      if (!input.authority) return { allowed: false, reason: 'active_controller_claim', owner };
+
+      if (!controllerTerminalizationAuthorityMatches(owner, input.authority)) {
+        return { allowed: false, reason: 'stale_controller_authority', owner };
+      }
+      return { allowed: true, value: operation(), owner };
+    },
+  );
+}
+
+/**
+ * Release a live ControllerSession only when the caller still owns the exact
+ * durable controller epoch it observed. This closes the release-then-terminalize
+ * race without changing WorkContract lifecycle authority.
+ */
+export function releaseControllerSessionWithAuthority(
+  options: ControllerSessionStoreOptions,
+  input: {
+    workId: string;
+    actor: string;
+    authority: ControllerTerminalizationAuthority;
+  },
+): ControllerTerminalizationFenceResult<void> {
+  return withControllerLock(
+    options.controllerHome,
+    { scope: 'task', repoId: options.repoId, taskId: `controller-session-${input.workId}` },
+    input.actor,
+    () => {
+      const store = read(options);
+      const owner = activeSession(store, input.workId);
+      if (!owner) return { allowed: false, reason: 'controller_claim_missing' };
+      if (!controllerTerminalizationAuthorityMatches(owner, input.authority)) {
+        return { allowed: false, reason: 'stale_controller_authority', owner };
+      }
+      const sessions = store.sessions.filter((entry) => entry.workId !== input.workId);
+      write(options, { schemaVersion: 1, updatedAt: now(options), sessions });
+      return { allowed: true, value: undefined, owner };
+    },
+  );
+}
+
 /**
  * Strict claim used for first ownership acquisition and explicit release/reclaim flows.
  * A live claim with any different controller or transport session remains fenced.
@@ -137,6 +266,7 @@ export function claimControllerSession(
     { scope: 'task', repoId: options.repoId, taskId: `controller-session-${input.workId}` },
     `controller-claim:${input.controllerId}:${input.sessionId}`,
     () => {
+      assertWorkClaimable(options, input.workId);
       const store = read(options);
       const current = activeSession(store, input.workId);
       assertExpectedGeneration(input, current);
@@ -167,6 +297,7 @@ export function resumeControllerSession(
     { scope: 'task', repoId: options.repoId, taskId: `controller-session-${input.workId}` },
     `controller-resume:${input.controllerId}:${input.sessionId}`,
     () => {
+      assertWorkClaimable(options, input.workId);
       const store = read(options);
       const current = activeSession(store, input.workId);
       assertExpectedGeneration(input, current);

package/src/runtime/control-plane/facade/goal-workloop-access.ts

@@ -139,6 +139,7 @@ export function runGoalWorkloop(
     objective: String(args.objective ?? ''),
     acceptanceCriteria: Array.isArray(args.acceptance_criteria) ? args.acceptance_criteria.map(String) : undefined,
     allowedPaths: Array.isArray(args.allowed_paths) ? args.allowed_paths.map(String) : undefined,
+    initialLikelyPaths: Array.isArray(args.initial_likely_paths) ? args.initial_likely_paths.map(String) : undefined,
     forbiddenPaths: Array.isArray(args.forbidden_paths) ? args.forbidden_paths.map(String) : undefined,
     checks: Array.isArray(args.check_ids) ? args.check_ids.map(String) : undefined,
     constraints,
@@ -150,6 +151,7 @@ export function runGoalWorkloop(
       requiresInvestigation: args.requires_investigation === true,
       requiresLongRunningChecks: args.requires_long_running_checks === true,
       requiresParallelism: args.requires_parallelism === true,
+      explicitMode: args.mode === 'scale' ? 'scale' : undefined,
       needsDependencies: args.needs_dependencies === true,
       requiresRecovery: args.requires_recovery === true,
       requiresWorker: args.requires_worker === true,