@moretea-labs/forge 1.6.0 → 1.7.1

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; }
 
@@ -17,6 +18,12 @@ export interface ControllerSessionClaimInput {
   controllerInstanceId?: string;
   /** Optional compare-and-swap fence supplied by a recovering caller. */
   expectedClaimGeneration?: number;
+  /**
+   * Permit a different authenticated controller epoch to recover this Work only
+   * after the canonical execution/activity grace has elapsed. Callers must pair
+   * this with expectedClaimGeneration from the owner they observed.
+   */
+  allowStaleRecovery?: boolean;
   leaseMs?: number;
 }
 
@@ -48,9 +55,50 @@ function write(options: ControllerSessionStoreOptions, store: ControllerSessionS
   });
 }
 
-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);
+const DEFAULT_CONTROLLER_RECOVERY_GRACE_MS = 5 * 60_000;
+const MAX_CONTROLLER_RECOVERY_GRACE_MS = 60 * 60_000;
+const DEFAULT_CONTROLLER_LEASE_MS = 60 * 60_000;
+const MAX_CONTROLLER_LEASE_MS = 60 * 60_000;
+
+function optionsNowMs(options: ControllerSessionStoreOptions): number {
+  const parsed = Date.parse(now(options));
+  return Number.isFinite(parsed) ? parsed : Date.now();
+}
+
+function activeSession(store: ControllerSessionStore, workId: string, atMs: number = Date.now()): ControllerSession | undefined {
+  return store.sessions.find((session) => session.workId === workId && Date.parse(session.leaseExpiresAt) > atMs);
+}
+
+function sessionBlocksRecovery(
+  options: ControllerSessionStoreOptions,
+  owner: ControllerSession,
+  input: { nowMs: number; graceMs?: number },
+): boolean {
+  const execution = peekExecutionSession(options.controllerHome, owner.sessionId);
+  const graceMs = Math.max(60_000, Math.min(input.graceMs ?? DEFAULT_CONTROLLER_RECOVERY_GRACE_MS, MAX_CONTROLLER_RECOVERY_GRACE_MS));
+  if (execution?.invalidatedAt) {
+    const invalidatedAtMs = Date.parse(execution.invalidatedAt);
+    if (!Number.isFinite(invalidatedAtMs)) return true;
+    return input.nowMs - invalidatedAtMs < graceMs;
+  }
+  if (execution?.activeWorkId && execution.activeWorkId !== owner.workId) return false;
+  const activityMs = [execution?.lastValidatedAt, execution?.updatedAt, owner.claimedAt]
+    .map((value) => value ? Date.parse(value) : Number.NaN)
+    .filter(Number.isFinite)
+    .reduce((latest, value) => Math.max(latest, value), Number.NEGATIVE_INFINITY);
+  if (!Number.isFinite(activityMs)) return false;
+  return input.nowMs - activityMs < graceMs;
+}
+
+export function controllerSessionBlocksRecovery(
+  options: ControllerSessionStoreOptions,
+  workId: string,
+  input: { nowMs?: number; graceMs?: number } = {},
+): boolean {
+  const nowMs = input.nowMs ?? Date.now();
+  const owner = activeSession(read(options), workId, nowMs);
+  if (!owner) return false;
+  return sessionBlocksRecovery(options, owner, { nowMs, graceMs: input.graceMs });
 }
 
 function assertIdentity(input: ControllerSessionClaimInput): void {
@@ -59,6 +107,13 @@ function assertIdentity(input: ControllerSessionClaimInput): void {
   }
 }
 
+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,
@@ -66,7 +121,7 @@ function claimedSession(
   previous?: ControllerSession,
 ): ControllerSession {
   const leaseExpiresAt = new Date(
-    Date.parse(claimedAt) + Math.max(1_000, Math.min(input.leaseMs ?? 300_000, 3_600_000)),
+    Date.parse(claimedAt) + Math.max(1_000, Math.min(input.leaseMs ?? DEFAULT_CONTROLLER_LEASE_MS, MAX_CONTROLLER_LEASE_MS)),
   ).toISOString();
   const previousPrincipal = previous?.principalId?.trim() || previous?.controllerId;
   const inputPrincipal = input.principalId?.trim() || input.controllerId;
@@ -105,9 +160,10 @@ function persistClaim(
   previous?: ControllerSession,
 ): ControllerSession {
   const claimedAt = now(options);
+  const claimedAtMs = Date.parse(claimedAt);
   const session = claimedSession(options, input, claimedAt, previous);
   const sessions = [
-    ...store.sessions.filter((entry) => entry.workId !== input.workId && Date.parse(entry.leaseExpiresAt) > Date.now()),
+    ...store.sessions.filter((entry) => entry.workId !== input.workId && Date.parse(entry.leaseExpiresAt) > claimedAtMs),
     session,
   ];
   write(options, { schemaVersion: 1, updatedAt: claimedAt, sessions });
@@ -115,14 +171,194 @@ function persistClaim(
 }
 
 export function getControllerSession(options: ControllerSessionStoreOptions, workId: string): ControllerSession | undefined {
-  return activeSession(read(options), workId);
+  return activeSession(read(options), workId, optionsNowMs(options));
 }
 
 export function listControllerSessions(options: ControllerSessionStoreOptions): ControllerSession[] {
-  const at = Date.now();
+  const at = optionsNowMs(options);
   return read(options).sessions.filter((session) => Date.parse(session.leaseExpiresAt) > at);
 }
 
+export interface ControllerOwnershipAuthority {
+  controllerId: string;
+  controllerType: ControllerType;
+  principalId: string;
+  controllerInstanceId: string;
+  claimGeneration: number;
+}
+
+export type ControllerTerminalizationAuthority = ControllerOwnershipAuthority;
+
+export function controllerSessionPrincipalId(
+  owner: Pick<ControllerSession, 'principalId' | 'controllerId'>,
+): string {
+  return owner.principalId?.trim() || owner.controllerId;
+}
+
+export function requireControllerOwnershipAuthority(
+  owner: ControllerSession,
+  workId: string = owner.workId,
+): ControllerOwnershipAuthority {
+  const principalId = controllerSessionPrincipalId(owner);
+  const controllerInstanceId = owner.controllerInstanceId?.trim() || '';
+  if (!controllerInstanceId) throw new Error(`WORK_CONTROLLER_INSTANCE_MISMATCH: ${workId}`);
+  if (typeof owner.claimGeneration !== 'number' || owner.claimGeneration < 1) {
+    throw new Error(`WORK_CONTROLLER_CLAIM_GENERATION_REQUIRED: ${workId}`);
+  }
+  return {
+    controllerId: owner.controllerId,
+    controllerType: owner.controllerType,
+    principalId,
+    controllerInstanceId,
+    claimGeneration: owner.claimGeneration,
+  };
+}
+
+export function assertControllerOwnershipAuthority(
+  owner: ControllerSession,
+  expected: {
+    workId?: string;
+    controllerId: string;
+    principalId: string;
+    controllerInstanceId?: string;
+    controllerType?: ControllerType;
+  },
+): ControllerOwnershipAuthority {
+  const workId = expected.workId ?? owner.workId;
+  const authority = requireControllerOwnershipAuthority(owner, workId);
+  if (authority.controllerId !== expected.controllerId.trim()) {
+    throw new Error(`WORK_CONTROLLER_OWNER_MISMATCH: ${workId} is owned by ${owner.controllerId}`);
+  }
+  if (expected.controllerType && authority.controllerType !== expected.controllerType) {
+    throw new Error(`WORK_CONTROLLER_TYPE_MISMATCH: ${workId} is owned by ${owner.controllerType}`);
+  }
+  if (authority.principalId !== expected.principalId.trim()) {
+    throw new Error(`WORK_CONTROLLER_PRINCIPAL_MISMATCH: ${workId}`);
+  }
+  if (expected.controllerInstanceId !== undefined
+    && authority.controllerInstanceId !== expected.controllerInstanceId.trim()) {
+    throw new Error(`WORK_CONTROLLER_INSTANCE_MISMATCH: ${workId}`);
+  }
+  return authority;
+}
+
+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 };
+
+export function controllerTerminalizationAuthorityFromSession(
+  owner: ControllerSession,
+): ControllerTerminalizationAuthority | undefined {
+  try {
+    return requireControllerOwnershipAuthority(owner);
+  } catch {
+    return undefined;
+  }
+}
+
+function controllerTerminalizationAuthorityMatches(
+  owner: ControllerSession,
+  authority: ControllerTerminalizationAuthority,
+): boolean {
+  const ownerPrincipal = controllerSessionPrincipalId(owner);
+  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, optionsNowMs(options));
+      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, optionsNowMs(options));
+      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 };
+    },
+  );
+}
+
+export function releaseObservedControllerSession(
+  options: ControllerSessionStoreOptions,
+  input: { workId: string; actor: string; owner: ControllerSession },
+): ControllerTerminalizationFenceResult<void> {
+  const authority = controllerTerminalizationAuthorityFromSession(input.owner);
+  if (!authority) return { allowed: false, reason: 'stale_controller_authority', owner: input.owner };
+  return releaseControllerSessionWithAuthority(options, {
+    workId: input.workId,
+    actor: input.actor,
+    authority,
+  });
+}
+
 /**
  * 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,8 +373,9 @@ 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);
+      const current = activeSession(store, input.workId, optionsNowMs(options));
       assertExpectedGeneration(input, current);
       if (current && (current.controllerId !== input.controllerId || current.sessionId !== input.sessionId)) {
         throw new Error(`WORK_ALREADY_CLAIMED: ${input.workId} is owned by ${current.controllerId}`);
@@ -167,16 +404,21 @@ 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);
+      const currentNowMs = optionsNowMs(options);
+      const current = activeSession(store, input.workId, currentNowMs);
       assertExpectedGeneration(input, current);
       if (!current) return persistClaim(options, store, input);
       const priorExecution = peekExecutionSession(options.controllerHome, current.sessionId);
       const currentPrincipal = current.principalId?.trim() || priorExecution?.principalId?.trim() || current.controllerId;
-      if (currentPrincipal !== input.principalId.trim()) {
+      const staleRecoveryAllowed = input.allowStaleRecovery === true
+        && input.expectedClaimGeneration !== undefined
+        && !sessionBlocksRecovery(options, current, { nowMs: currentNowMs });
+      if (currentPrincipal !== input.principalId.trim() && !staleRecoveryAllowed) {
         throw new Error(`WORK_CONTROLLER_PRINCIPAL_MISMATCH: ${input.workId} is owned by another authenticated principal`);
       }
-      if (current.controllerId !== input.controllerId) {
+      if (current.controllerId !== input.controllerId && !staleRecoveryAllowed) {
         throw new Error(`WORK_ALREADY_CLAIMED: ${input.workId} is owned by ${current.controllerId}`);
       }
       return persistClaim(options, store, input, current);
@@ -184,6 +426,54 @@ export function resumeControllerSession(
   );
 }
 
+/**
+ * Rebind one active Work to the authenticated Controller transport/Runtime that
+ * is serving the current request. Same-instance transport rollover needs only
+ * principal/controller proof. A Runtime-instance change additionally requires
+ * positive proof that the requested instance is the live canonical Runtime;
+ * this prevents a stale old Runtime request from migrating ownership backwards.
+ * The observed claim generation is always supplied as a CAS fence.
+ */
+export function bindControllerSessionToCurrentRuntime(
+  options: ControllerSessionStoreOptions,
+  input: ControllerSessionClaimInput & {
+    principalId: string;
+    controllerInstanceId: string;
+    currentRuntimeInstanceId?: string;
+    allowClaimIfMissing?: boolean;
+  },
+): ControllerSession {
+  assertIdentity(input);
+  const current = getControllerSession(options, input.workId);
+  if (!current) {
+    if (input.allowClaimIfMissing !== true) throw new Error(`WORK_CONTROLLER_OWNER_REQUIRED: ${input.workId}`);
+    return claimControllerSession(options, { ...input, expectedClaimGeneration: 0 });
+  }
+  const currentPrincipal = controllerSessionPrincipalId(current);
+  if (current.controllerId !== input.controllerId) {
+    throw new Error(`WORK_CONTROLLER_OWNER_MISMATCH: ${input.workId} is owned by ${current.controllerId}`);
+  }
+  if (current.controllerType !== input.controllerType) {
+    throw new Error(`WORK_CONTROLLER_TYPE_MISMATCH: ${input.workId} is owned by ${current.controllerType}`);
+  }
+  if (currentPrincipal !== input.principalId.trim()) {
+    throw new Error(`WORK_CONTROLLER_PRINCIPAL_MISMATCH: ${input.workId}`);
+  }
+  const ownerInstanceId = current.controllerInstanceId?.trim() || '';
+  const requestedInstanceId = input.controllerInstanceId.trim();
+  if (ownerInstanceId !== requestedInstanceId) {
+    const currentRuntimeInstanceId = input.currentRuntimeInstanceId?.trim() || '';
+    if (!currentRuntimeInstanceId || currentRuntimeInstanceId !== requestedInstanceId) {
+      throw new Error(`WORK_CONTROLLER_INSTANCE_MISMATCH: ${input.workId}`);
+    }
+  }
+  if (ownerInstanceId === requestedInstanceId && current.sessionId === input.sessionId) return current;
+  return resumeControllerSession(options, {
+    ...input,
+    expectedClaimGeneration: current.claimGeneration,
+  });
+}
+
 export function releaseControllerSession(options: ControllerSessionStoreOptions, workId: string, controllerId: string): void {
   withControllerLock(
     options.controllerHome,

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

@@ -13,7 +13,7 @@ import {
   type GoalWorkloopStartInput,
 } from './goal-workloop';
 import { getWorkContract } from './work-contract-store';
-import type { CapabilityRisk, FacadeResult, WorkContractConstraints } from './types';
+import type { CapabilityRisk, FacadeResult, WorkContractConstraints, WorkKind } from './types';
 
 export {
   continueGoalWorkloop,
@@ -47,6 +47,18 @@ function accessModeValue(value: unknown): AccessMode | undefined {
   return isAccessMode(candidate) ? candidate : undefined;
 }
 
+function workKindValue(value: unknown): Extract<WorkKind, 'repository_change' | 'completed_no_change' | 'read_only_review' | 'investigation' | 'local_effect' | 'remote_effect' | 'reconciliation'> | undefined {
+  return value === 'repository_change'
+    || value === 'completed_no_change'
+    || value === 'read_only_review'
+    || value === 'investigation'
+    || value === 'local_effect'
+    || value === 'remote_effect'
+    || value === 'reconciliation'
+    ? value
+    : undefined;
+}
+
 function constraintsValue(value: unknown): WorkContractConstraints | undefined {
   if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
   const record = value as Record<string, unknown>;
@@ -65,6 +77,7 @@ function constraintsValue(value: unknown): WorkContractConstraints | undefined {
         ? 'isolated'
         : record.workspaceMode === 'auto' || record.workspace_mode === 'auto' ? 'auto' : undefined,
     requireWorktree: booleanValue(record, 'requireWorktree', 'require_worktree'),
+    directMainProhibited: booleanValue(record, 'directMainProhibited', 'direct_main_prohibited'),
   };
   return Object.fromEntries(
     Object.entries(constraints).filter(([, entry]) => entry !== undefined),
@@ -139,9 +152,11 @@ 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,
+    workKind: workKindValue(args.work_kind),
     modeInput: {
       objective: typeof args.objective === 'string' ? args.objective : undefined,
       expectedFiles: typeof args.expected_files === 'number' ? args.expected_files : undefined,
@@ -150,6 +165,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,