@moretea-labs/forge 1.7.2 → 1.8.0

package/packages/kernel/controller/infrastructure/controller-session-store.ts

@@ -0,0 +1,578 @@
+import { createHash, randomUUID, timingSafeEqual } from 'crypto';
+import { join } from 'path';
+import { repositoryControllerRoot } from '../../../../src/cli/repositories/controller-home';
+import { withControllerLock } from '../../../../src/cli/repositories/locks';
+import { peekExecutionSession } from '../../../../src/runtime/control-plane/execution/session-store';
+import { readJsonFile } from '../../../../src/runtime/shared/json-files';
+import { readControlPlaneRecord, readOrImportControlPlaneRecord, writeControlPlaneRecord } from '../../../../src/runtime/control-plane/persistence/sqlite-store';
+import { getWorkContract, isTerminalWorkContractStatus } from '../../work/api/index';
+import { type ControllerSession, type ControllerSessionStore, type ControllerType } from '../domain/types';
+
+export interface ControllerSessionStoreOptions { controllerHome: string; repoId: string; now?: () => string; }
+
+export interface ControllerSessionClaimInput {
+  workId: string;
+  controllerId: string;
+  controllerType: ControllerType;
+  sessionId: string;
+  /** Optional digest of the Work-bound controller capability. Plaintext is never persisted in ControllerSession. */
+  authorityDigest?: string;
+  principalId?: string;
+  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;
+}
+
+function path(options: ControllerSessionStoreOptions): string {
+  return join(repositoryControllerRoot(options.controllerHome, options.repoId), 'controller-sessions.json');
+}
+
+function now(options: ControllerSessionStoreOptions): string { return options.now?.() ?? new Date().toISOString(); }
+
+function read(options: ControllerSessionStoreOptions): ControllerSessionStore {
+  const legacyPath = path(options);
+  return readOrImportControlPlaneRecord<ControllerSessionStore>(options.controllerHome, {
+    namespace: 'controller_session_claim_store',
+    scope: options.repoId,
+    key: 'index',
+    schemaVersion: 1,
+    readLegacy: () => readJsonFile<ControllerSessionStore>(legacyPath, { schemaVersion: 1, updatedAt: now(options), sessions: [] }),
+  })?.value ?? { schemaVersion: 1, updatedAt: now(options), sessions: [] };
+}
+
+function write(options: ControllerSessionStoreOptions, store: ControllerSessionStore): void {
+  writeControlPlaneRecord(options.controllerHome, {
+    namespace: 'controller_session_claim_store',
+    scope: options.repoId,
+    key: 'index',
+    schemaVersion: 1,
+    value: store,
+    action: 'controller_session_claim_write',
+  });
+}
+
+const RETAINED_SESSION_NAMESPACE = 'controller_session_identity';
+
+interface RetainedControllerSessionRecord {
+  schemaVersion: 1;
+  session: ControllerSession;
+  retainedAt: string;
+  releasedAt?: string;
+}
+
+function persistRetainedControllerSession(
+  options: ControllerSessionStoreOptions,
+  session: ControllerSession,
+  releasedAt?: string,
+): void {
+  const retainedAt = now(options);
+  writeControlPlaneRecord(options.controllerHome, {
+    namespace: RETAINED_SESSION_NAMESPACE,
+    scope: options.repoId,
+    key: session.workId,
+    schemaVersion: 1,
+    value: { schemaVersion: 1, session, retainedAt, ...(releasedAt ? { releasedAt } : {}) } satisfies RetainedControllerSessionRecord,
+    action: releasedAt ? 'controller_session_identity_released' : 'controller_session_identity_retained',
+  });
+}
+
+/** Durable session identity survives transport/lease release; it is not an ownership lease. */
+export function getRetainedControllerSession(
+  options: ControllerSessionStoreOptions,
+  workId: string,
+): ControllerSession | undefined {
+  const retained = readControlPlaneRecord<RetainedControllerSessionRecord>(
+    options.controllerHome,
+    RETAINED_SESSION_NAMESPACE,
+    options.repoId,
+    workId,
+  )?.value.session;
+  if (retained) return retained;
+  return read(options).sessions.find((entry) => entry.workId === workId);
+}
+
+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 {
+  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,
+  claimedAt: string,
+  previous?: ControllerSession,
+): ControllerSession {
+  const leaseExpiresAt = new Date(
+    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;
+  const sameOwner = previous?.controllerId === input.controllerId
+    && previous?.controllerType === input.controllerType
+    && previousPrincipal === inputPrincipal
+    && (previous.controllerInstanceId ?? '') === (input.controllerInstanceId?.trim() ?? '');
+  const claimGeneration = sameOwner
+    ? Math.max(1, previous?.claimGeneration ?? 1)
+    : Math.max(0, previous?.claimGeneration ?? 0) + 1;
+  const authorityDigest = input.authorityDigest?.trim() || (sameOwner ? previous?.authorityDigest?.trim() : '') || '';
+  return {
+    schemaVersion: 1,
+    workId: input.workId,
+    controllerId: input.controllerId,
+    controllerType: input.controllerType,
+    sessionId: input.sessionId,
+    ...(authorityDigest ? { authorityDigest } : {}),
+    ...(input.principalId?.trim() ? { principalId: input.principalId.trim() } : {}),
+    ...(input.controllerInstanceId?.trim() ? { controllerInstanceId: input.controllerInstanceId.trim() } : {}),
+    claimGeneration,
+    claimedAt,
+    leaseExpiresAt,
+  };
+}
+
+function assertExpectedGeneration(input: ControllerSessionClaimInput, current: ControllerSession | undefined): void {
+  if (input.expectedClaimGeneration === undefined) return;
+  const actual = current?.claimGeneration ?? 0;
+  if (actual !== input.expectedClaimGeneration) {
+    throw new Error(`WORK_CLAIM_GENERATION_MISMATCH: ${input.workId} expected=${input.expectedClaimGeneration} actual=${actual}`);
+  }
+}
+
+function persistClaim(
+  options: ControllerSessionStoreOptions,
+  store: ControllerSessionStore,
+  input: ControllerSessionClaimInput,
+  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) > claimedAtMs),
+    session,
+  ];
+  write(options, { schemaVersion: 1, updatedAt: claimedAt, sessions });
+  persistRetainedControllerSession(options, session);
+  return session;
+}
+
+export function getControllerSession(options: ControllerSessionStoreOptions, workId: string): ControllerSession | undefined {
+  return activeSession(read(options), workId, optionsNowMs(options));
+}
+
+export function listControllerSessions(options: ControllerSessionStoreOptions): ControllerSession[] {
+  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;
+}
+
+function digestControllerAuthority(authorityId: string): string {
+  return createHash('sha256').update(authorityId).digest('hex');
+}
+
+/** Mint a non-relay Work-bound capability. Only the digest belongs in durable ControllerSession state. */
+export function mintControllerSessionAuthority(): { authorityId: string; authorityDigest: string } {
+  const authorityId = `ctrl_${randomUUID().replace(/-/g, '')}`;
+  return { authorityId, authorityDigest: digestControllerAuthority(authorityId) };
+}
+
+/** Bind an already-authorized opaque capability without persisting its plaintext value. */
+export function controllerSessionAuthorityDigest(authorityId: string): string {
+  const normalized = authorityId.trim();
+  if (!normalized) throw new Error('WORK_CONTROLLER_AUTHORITY_REQUIRED');
+  return digestControllerAuthority(normalized);
+}
+
+/** Verify an opaque capability without exposing or persisting its plaintext value. */
+export function controllerSessionAuthorityMatches(owner: ControllerSession, authorityId: string | undefined): boolean {
+  const expected = owner.authorityDigest?.trim() || '';
+  const candidate = authorityId?.trim() || '';
+  if (!expected || !candidate) return false;
+  const actual = digestControllerAuthority(candidate);
+  if (expected.length !== actual.length) return false;
+  return timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(actual, 'hex'));
+}
+
+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 releasedAt = now(options);
+      persistRetainedControllerSession(options, owner, releasedAt);
+      const sessions = store.sessions.filter((entry) => entry.workId !== input.workId);
+      write(options, { schemaVersion: 1, updatedAt: releasedAt, 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.
+ */
+export function claimControllerSession(
+  options: ControllerSessionStoreOptions,
+  input: ControllerSessionClaimInput,
+): ControllerSession {
+  assertIdentity(input);
+  return withControllerLock(
+    options.controllerHome,
+    { 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, optionsNowMs(options));
+      const previous = current ?? store.sessions
+        .filter((entry) => entry.workId === input.workId)
+        .sort((left, right) => (right.claimGeneration ?? 0) - (left.claimGeneration ?? 0))[0];
+      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}`);
+      }
+      return persistClaim(options, store, input, previous);
+    },
+  );
+}
+
+/**
+ * Resume a claim after transport replacement. Durable Work ownership belongs to
+ * the authenticated principal/controller epoch, not to one MCP transport session.
+ * A same-principal session rotation therefore preserves ownership generation;
+ * a controller-epoch change is recovery and advances the generation fence.
+ */
+export function resumeControllerSession(
+  options: ControllerSessionStoreOptions,
+  input: ControllerSessionClaimInput & { principalId: string; controllerInstanceId: string },
+): ControllerSession {
+  assertIdentity(input);
+  if (!input.principalId.trim() || !input.controllerInstanceId.trim()) {
+    throw new Error('CONTROLLER_RESUME_AUTHORITY_REQUIRED');
+  }
+  return withControllerLock(
+    options.controllerHome,
+    { 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 currentNowMs = optionsNowMs(options);
+      const current = activeSession(store, input.workId, currentNowMs);
+      assertExpectedGeneration(input, current);
+      if (!current) {
+        const previous = store.sessions
+          .filter((entry) => entry.workId === input.workId)
+          .sort((left, right) => (right.claimGeneration ?? 0) - (left.claimGeneration ?? 0))[0];
+        return persistClaim(options, store, input, previous);
+      }
+      const priorExecution = peekExecutionSession(options.controllerHome, current.sessionId);
+      const currentPrincipal = current.principalId?.trim() || priorExecution?.principalId?.trim() || current.controllerId;
+      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 && !staleRecoveryAllowed) {
+        throw new Error(`WORK_ALREADY_CLAIMED: ${input.workId} is owned by ${current.controllerId}`);
+      }
+      if (current.controllerType !== input.controllerType && !staleRecoveryAllowed) {
+        throw new Error(`WORK_CONTROLLER_TYPE_MISMATCH: ${input.workId} is owned by ${current.controllerType}`);
+      }
+      return persistClaim(options, store, input, current);
+    },
+  );
+}
+
+/**
+ * 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,
+    { scope: 'task', repoId: options.repoId, taskId: `controller-session-${workId}` },
+    `controller-release:${controllerId}`,
+    () => {
+      const store = read(options);
+      const owner = store.sessions.find((entry) => entry.workId === workId && entry.controllerId === controllerId);
+      const releasedAt = now(options);
+      if (owner) persistRetainedControllerSession(options, owner, releasedAt);
+      const sessions = store.sessions.filter((entry) => entry.workId !== workId || entry.controllerId !== controllerId);
+      write(options, { schemaVersion: 1, updatedAt: releasedAt, sessions });
+    },
+  );
+}

package/packages/kernel/controller/ports/controller-host.ts

@@ -0,0 +1,16 @@
+import type { ControllerBinding, ControllerRoundContext } from '../domain/types';
+
+export interface ControllerHostResumeResult {
+  accepted: boolean;
+  dispatchId?: string;
+  reason?: string;
+  /** Explicit provider/user blocker. Valid only when accepted=false; callers persist a resumable wait instead of terminal rejection. */
+  waitForUser?: boolean;
+  /** Durable user-action Handoff created by the provider adapter when waitForUser=true. */
+  handoffId?: string;
+}
+
+/** Provider-neutral continuation port. Implementations live in adapters/*. */
+export interface ControllerHost {
+  resume(binding: ControllerBinding, roundContext: ControllerRoundContext): Promise<ControllerHostResumeResult> | ControllerHostResumeResult;
+}

package/packages/kernel/goal/api/index.ts

@@ -0,0 +1 @@
+export * from '../domain/types';

package/packages/kernel/goal/domain/types.ts

@@ -0,0 +1,40 @@
+export const REQUIREMENT_STATES = ['planned', 'active', 'waiting_for_user', 'done', 'cancelled'] as const;
+export type RequirementState = (typeof REQUIREMENT_STATES)[number];
+
+export const REQUIREMENT_STATE_TRANSITIONS: Readonly<Record<RequirementState, readonly RequirementState[]>> = {
+  planned: ['planned', 'active', 'waiting_for_user', 'cancelled'],
+  active: ['active', 'waiting_for_user', 'done', 'cancelled'],
+  waiting_for_user: ['waiting_for_user', 'planned', 'active', 'done', 'cancelled'],
+  done: ['done', 'cancelled'],
+  cancelled: ['cancelled'],
+};
+
+export const PLAN_CONTRACT_STATUSES = [
+  'draft',
+  'inspecting',
+  'reviewing',
+  'approved',
+  'executing',
+  'replanning',
+  'verifying',
+  'ready_to_finalize',
+  'finalized',
+  'superseded',
+  'cancelled',
+  'invalidated_by_drift',
+] as const;
+export type PlanContractStatus = (typeof PLAN_CONTRACT_STATUSES)[number];
+
+export const TERMINAL_PLAN_CONTRACT_STATUSES: readonly PlanContractStatus[] = [
+  'finalized',
+  'superseded',
+  'cancelled',
+  'invalidated_by_drift',
+];
+
+export function isTerminalPlanContractStatus(status: PlanContractStatus): boolean {
+  return TERMINAL_PLAN_CONTRACT_STATUSES.includes(status);
+}
+
+export const PLAN_STEP_STATUSES = ['pending', 'ready', 'executing', 'validating', 'completed'] as const;
+export type PlanStepStatus = (typeof PLAN_STEP_STATUSES)[number];

package/packages/kernel/goal/index.ts

@@ -0,0 +1 @@
+export * from './api/index';

package/packages/kernel/identity/api/index.ts

@@ -0,0 +1,5 @@
+export * from '../domain/types';
+export * from '../domain/scope';
+export * from '../application/identity-service';
+export * from '../domain/workspace';
+export * from '../domain/semantic-sync';