@moretea-labs/forge 1.7.0 → 1.7.2

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

@@ -18,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;
 }
 
@@ -49,12 +55,39 @@ function write(options: ControllerSessionStoreOptions, store: ControllerSessionS
   });
 }
 
-const DEFAULT_CONTROLLER_RECOVERY_GRACE_MS = 10 * 60_000;
+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 activeSession(store: ControllerSessionStore, workId: string): ControllerSession | undefined {
-  const at = Date.now();
-  return store.sessions.find((session) => session.workId === workId && Date.parse(session.leaseExpiresAt) > at);
+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(
@@ -62,15 +95,10 @@ export function controllerSessionBlocksRecovery(
   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;
+  const owner = activeSession(read(options), workId, nowMs);
+  if (!owner) return false;
+  return sessionBlocksRecovery(options, owner, { nowMs, graceMs: input.graceMs });
 }
 
 function assertIdentity(input: ControllerSessionClaimInput): void {
@@ -93,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;
@@ -132,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 });
@@ -142,15 +171,15 @@ 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 ControllerTerminalizationAuthority {
+export interface ControllerOwnershipAuthority {
   controllerId: string;
   controllerType: ControllerType;
   principalId: string;
@@ -158,6 +187,61 @@ export interface ControllerTerminalizationAuthority {
   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'
@@ -167,11 +251,21 @@ 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 = owner.principalId?.trim() || owner.controllerId;
+  const ownerPrincipal = controllerSessionPrincipalId(owner);
   const ownerInstanceId = owner.controllerInstanceId?.trim() || '';
   return owner.controllerId === authority.controllerId
     && owner.controllerType === authority.controllerType
@@ -206,7 +300,7 @@ export function withControllerSessionTerminalizationFence<T>(
     { scope: 'task', repoId: options.repoId, taskId: `controller-session-${input.workId}` },
     input.actor,
     () => {
-      const owner = activeSession(read(options), input.workId);
+      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() };
@@ -240,7 +334,7 @@ export function releaseControllerSessionWithAuthority(
     input.actor,
     () => {
       const store = read(options);
-      const owner = activeSession(store, input.workId);
+      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 };
@@ -252,6 +346,19 @@ export function releaseControllerSessionWithAuthority(
   );
 }
 
+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.
@@ -268,7 +375,7 @@ export function claimControllerSession(
     () => {
       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}`);
@@ -299,15 +406,19 @@ export function resumeControllerSession(
     () => {
       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);
@@ -315,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),
@@ -143,6 +156,7 @@ export function runGoalWorkloop(
     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,