@moretea-labs/forge 1.8.0 → 1.8.2

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

@@ -1,14 +1,41 @@
 import { createHash, randomUUID, timingSafeEqual } from 'crypto';
 import { join } from 'path';
-import { repositoryControllerRoot } from '../../../../src/cli/repositories/controller-home';
+import { FORGE_INSTANCE_SCOPE_KEY, 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 {
+  peekExecutionSession,
+  peekExecutionSessionWithinTransaction,
+} 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 {
+  readControlPlaneRecord,
+  readControlPlaneRecordWithinTransaction,
+  writeControlPlaneRecord,
+  writeControlPlaneRecordWithinTransaction,
+  type SqliteDatabase,
+} from '../../../../src/runtime/control-plane/persistence/sqlite-store';
 import { type ControllerSession, type ControllerSessionStore, type ControllerType } from '../domain/types';
+import { getWorkContract, semanticWorkState } from '../../work/api/index';
 
-export interface ControllerSessionStoreOptions { controllerHome: string; repoId: string; now?: () => string; }
+export interface ControllerSessionStoreOptions {
+  controllerHome: string;
+  /** Legacy repository provenance/migration hint only; canonical ControllerSession state is ForgeInstance-scoped. */
+  repoId: string;
+  now?: () => string;
+}
+
+const SESSION_STORE_NAMESPACE = 'controller_session_claim_store';
+const SESSION_STORE_KEY = 'index';
+const SESSION_STORE_SCHEMA_VERSION = 1;
+
+function assertControllerWorkClaimable(options: ControllerSessionStoreOptions, workId: string): void {
+  const work = getWorkContract({ controllerHome: options.controllerHome, repoId: options.repoId }, workId);
+  if (!work) return;
+  const state = semanticWorkState(work);
+  if (state !== 'open') throw new Error(`WORK_CONTROLLER_CLAIM_TERMINAL: ${workId}:${state}`);
+}
+
+export type ClaimedControllerSession = ControllerSession & { claimGeneration: number };
 
 export interface ControllerSessionClaimInput {
   workId: string;
@@ -36,23 +63,70 @@ function path(options: ControllerSessionStoreOptions): string {
 
 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',
+function legacyStore(options: ControllerSessionStoreOptions): ControllerSessionStore {
+  const sqlite = readControlPlaneRecord<ControllerSessionStore>(
+    options.controllerHome,
+    SESSION_STORE_NAMESPACE,
+    options.repoId,
+    SESSION_STORE_KEY,
+  )?.value;
+  if (sqlite) return sqlite;
+  return readJsonFile<ControllerSessionStore>(path(options), {
     schemaVersion: 1,
-    readLegacy: () => readJsonFile<ControllerSessionStore>(legacyPath, { schemaVersion: 1, updatedAt: now(options), sessions: [] }),
-  })?.value ?? { schemaVersion: 1, updatedAt: now(options), sessions: [] };
+    updatedAt: now(options),
+    sessions: [],
+  });
+}
+
+function mergeSessionStores(
+  canonical: ControllerSessionStore,
+  legacy: ControllerSessionStore,
+): ControllerSessionStore {
+  const sessions = new Map(canonical.sessions.map((session) => [session.workId, session]));
+  for (const candidate of legacy.sessions) {
+    const existing = sessions.get(candidate.workId);
+    if (!existing) {
+      sessions.set(candidate.workId, candidate);
+      continue;
+    }
+    if (JSON.stringify(existing) === JSON.stringify(candidate)) continue;
+    const existingGeneration = existing.claimGeneration ?? 0;
+    const candidateGeneration = candidate.claimGeneration ?? 0;
+    const existingClaimedAt = Date.parse(existing.claimedAt);
+    const candidateClaimedAt = Date.parse(candidate.claimedAt);
+    if (existingGeneration > candidateGeneration
+      || (existingGeneration === candidateGeneration
+        && Number.isFinite(existingClaimedAt)
+        && Number.isFinite(candidateClaimedAt)
+        && existingClaimedAt > candidateClaimedAt)) {
+      // Canonical state has advanced since the read-only legacy snapshot.
+      continue;
+    }
+    throw new Error(`CONTROLLER_SESSION_ID_COLLISION: ${candidate.workId}`);
+  }
+  return {
+    schemaVersion: 1,
+    updatedAt: canonical.updatedAt >= legacy.updatedAt ? canonical.updatedAt : legacy.updatedAt,
+    sessions: [...sessions.values()],
+  };
+}
+
+function read(options: ControllerSessionStoreOptions): ControllerSessionStore {
+  const canonical = readControlPlaneRecord<ControllerSessionStore>(
+    options.controllerHome,
+    SESSION_STORE_NAMESPACE,
+    FORGE_INSTANCE_SCOPE_KEY,
+    SESSION_STORE_KEY,
+  )?.value ?? { schemaVersion: 1 as const, updatedAt: now(options), sessions: [] };
+  return mergeSessionStores(canonical, legacyStore(options));
 }
 
 function write(options: ControllerSessionStoreOptions, store: ControllerSessionStore): void {
   writeControlPlaneRecord(options.controllerHome, {
-    namespace: 'controller_session_claim_store',
-    scope: options.repoId,
-    key: 'index',
-    schemaVersion: 1,
+    namespace: SESSION_STORE_NAMESPACE,
+    scope: FORGE_INSTANCE_SCOPE_KEY,
+    key: SESSION_STORE_KEY,
+    schemaVersion: SESSION_STORE_SCHEMA_VERSION,
     value: store,
     action: 'controller_session_claim_write',
   });
@@ -67,18 +141,42 @@ interface RetainedControllerSessionRecord {
   releasedAt?: string;
 }
 
+function retainedControllerSessionRecord(
+  options: ControllerSessionStoreOptions,
+  session: ControllerSession,
+  releasedAt?: string,
+): RetainedControllerSessionRecord {
+  const retainedAt = now(options);
+  return { schemaVersion: 1, session, retainedAt, ...(releasedAt ? { releasedAt } : {}) };
+}
+
 function persistRetainedControllerSession(
   options: ControllerSessionStoreOptions,
   session: ControllerSession,
   releasedAt?: string,
 ): void {
-  const retainedAt = now(options);
   writeControlPlaneRecord(options.controllerHome, {
     namespace: RETAINED_SESSION_NAMESPACE,
-    scope: options.repoId,
+    scope: FORGE_INSTANCE_SCOPE_KEY,
+    key: session.workId,
+    schemaVersion: 1,
+    value: retainedControllerSessionRecord(options, session, releasedAt),
+    action: releasedAt ? 'controller_session_identity_released' : 'controller_session_identity_retained',
+  });
+}
+
+function persistRetainedControllerSessionWithinTransaction(
+  database: SqliteDatabase,
+  options: ControllerSessionStoreOptions,
+  session: ControllerSession,
+  releasedAt?: string,
+): void {
+  writeControlPlaneRecordWithinTransaction(database, {
+    namespace: RETAINED_SESSION_NAMESPACE,
+    scope: FORGE_INSTANCE_SCOPE_KEY,
     key: session.workId,
     schemaVersion: 1,
-    value: { schemaVersion: 1, session, retainedAt, ...(releasedAt ? { releasedAt } : {}) } satisfies RetainedControllerSessionRecord,
+    value: retainedControllerSessionRecord(options, session, releasedAt),
     action: releasedAt ? 'controller_session_identity_released' : 'controller_session_identity_retained',
   });
 }
@@ -88,14 +186,32 @@ export function getRetainedControllerSession(
   options: ControllerSessionStoreOptions,
   workId: string,
 ): ControllerSession | undefined {
-  const retained = readControlPlaneRecord<RetainedControllerSessionRecord>(
+  const canonical = readControlPlaneRecord<RetainedControllerSessionRecord>(
+    options.controllerHome,
+    RETAINED_SESSION_NAMESPACE,
+    FORGE_INSTANCE_SCOPE_KEY,
+    workId,
+  )?.value.session;
+  const legacy = 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);
+  if (canonical && legacy && JSON.stringify(canonical) !== JSON.stringify(legacy)) {
+    const canonicalGeneration = canonical.claimGeneration ?? 0;
+    const legacyGeneration = legacy.claimGeneration ?? 0;
+    const canonicalClaimedAt = Date.parse(canonical.claimedAt);
+    const legacyClaimedAt = Date.parse(legacy.claimedAt);
+    if (!(canonicalGeneration > legacyGeneration
+      || (canonicalGeneration === legacyGeneration
+        && Number.isFinite(canonicalClaimedAt)
+        && Number.isFinite(legacyClaimedAt)
+        && canonicalClaimedAt > legacyClaimedAt))) {
+      throw new Error(`CONTROLLER_SESSION_ID_COLLISION: ${workId}`);
+    }
+  }
+  return canonical ?? legacy ?? read(options).sessions.find((entry) => entry.workId === workId);
 }
 
 const DEFAULT_CONTROLLER_RECOVERY_GRACE_MS = 5 * 60_000;
@@ -150,19 +266,18 @@ 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}`);
-  }
-}
+/**
+ * Compatibility no-op. ControllerSession is mechanical dispatch/reattachment
+ * state and does not decide whether semantic Work is open or terminal.
+ */
+export function assertControllerSessionWorkClaimable(_options: ControllerSessionStoreOptions, _workId: string): void {}
 
 function claimedSession(
   options: ControllerSessionStoreOptions,
   input: ControllerSessionClaimInput,
   claimedAt: string,
   previous?: ControllerSession,
-): ControllerSession {
+): ClaimedControllerSession {
   const leaseExpiresAt = new Date(
     Date.parse(claimedAt) + Math.max(1_000, Math.min(input.leaseMs ?? DEFAULT_CONTROLLER_LEASE_MS, MAX_CONTROLLER_LEASE_MS)),
   ).toISOString();
@@ -199,12 +314,12 @@ function assertExpectedGeneration(input: ControllerSessionClaimInput, current: C
   }
 }
 
-function persistClaim(
+function preparedClaim(
   options: ControllerSessionStoreOptions,
   store: ControllerSessionStore,
   input: ControllerSessionClaimInput,
   previous?: ControllerSession,
-): ControllerSession {
+): { claimedAt: string; session: ClaimedControllerSession; nextStore: ControllerSessionStore } {
   const claimedAt = now(options);
   const claimedAtMs = Date.parse(claimedAt);
   const session = claimedSession(options, input, claimedAt, previous);
@@ -212,9 +327,68 @@ function persistClaim(
     ...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;
+  return { claimedAt, session, nextStore: { schemaVersion: 1, updatedAt: claimedAt, sessions } };
+}
+
+function persistClaim(
+  options: ControllerSessionStoreOptions,
+  store: ControllerSessionStore,
+  input: ControllerSessionClaimInput,
+  previous?: ControllerSession,
+): ClaimedControllerSession {
+  const prepared = preparedClaim(options, store, input, previous);
+  write(options, prepared.nextStore);
+  persistRetainedControllerSession(options, prepared.session);
+  return prepared.session;
+}
+
+function readSessionStoreWithinTransaction(
+  database: SqliteDatabase,
+  options: ControllerSessionStoreOptions,
+) {
+  let current = readControlPlaneRecordWithinTransaction<ControllerSessionStore>(
+    database, SESSION_STORE_NAMESPACE, FORGE_INSTANCE_SCOPE_KEY, SESSION_STORE_KEY,
+  );
+  const legacySqlite = readControlPlaneRecordWithinTransaction<ControllerSessionStore>(
+    database, SESSION_STORE_NAMESPACE, options.repoId, SESSION_STORE_KEY,
+  )?.value;
+  const legacy = legacySqlite ?? readJsonFile<ControllerSessionStore>(path(options), {
+    schemaVersion: 1,
+    updatedAt: now(options),
+    sessions: [],
+  });
+  if (current) return { ...current, value: mergeSessionStores(current.value, legacy) };
+  current = writeControlPlaneRecordWithinTransaction(database, {
+    namespace: SESSION_STORE_NAMESPACE,
+    scope: FORGE_INSTANCE_SCOPE_KEY,
+    key: SESSION_STORE_KEY,
+    schemaVersion: SESSION_STORE_SCHEMA_VERSION,
+    value: legacy,
+    action: 'legacy_controller_session_import',
+    expectedRevision: null,
+  });
+  return current;
+}
+
+function persistClaimWithinTransaction(
+  database: SqliteDatabase,
+  options: ControllerSessionStoreOptions,
+  storeRecord: ReturnType<typeof readSessionStoreWithinTransaction>,
+  input: ControllerSessionClaimInput,
+  previous?: ControllerSession,
+): ClaimedControllerSession {
+  const prepared = preparedClaim(options, storeRecord.value, input, previous);
+  writeControlPlaneRecordWithinTransaction(database, {
+    namespace: SESSION_STORE_NAMESPACE,
+    scope: FORGE_INSTANCE_SCOPE_KEY,
+    key: SESSION_STORE_KEY,
+    schemaVersion: SESSION_STORE_SCHEMA_VERSION,
+    value: prepared.nextStore,
+    action: 'controller_session_claim_write',
+    expectedRevision: storeRecord.revision,
+  });
+  persistRetainedControllerSessionWithinTransaction(database, options, prepared.session);
+  return prepared.session;
 }
 
 export function getControllerSession(options: ControllerSessionStoreOptions, workId: string): ControllerSession | undefined {
@@ -371,7 +545,7 @@ export function withControllerSessionTerminalizationFence<T>(
 ): ControllerTerminalizationFenceResult<T> {
   return withControllerLock(
     options.controllerHome,
-    { scope: 'task', repoId: options.repoId, taskId: `controller-session-${input.workId}` },
+    { scope: 'global', resource: 'controller-session-store' },
     input.actor,
     () => {
       const owner = activeSession(read(options), input.workId, optionsNowMs(options));
@@ -404,7 +578,7 @@ export function releaseControllerSessionWithAuthority(
 ): ControllerTerminalizationFenceResult<void> {
   return withControllerLock(
     options.controllerHome,
-    { scope: 'task', repoId: options.repoId, taskId: `controller-session-${input.workId}` },
+    { scope: 'global', resource: 'controller-session-store' },
     input.actor,
     () => {
       const store = read(options);
@@ -442,14 +616,14 @@ export function releaseObservedControllerSession(
 export function claimControllerSession(
   options: ControllerSessionStoreOptions,
   input: ControllerSessionClaimInput,
-): ControllerSession {
+): ClaimedControllerSession {
   assertIdentity(input);
   return withControllerLock(
     options.controllerHome,
-    { scope: 'task', repoId: options.repoId, taskId: `controller-session-${input.workId}` },
+    { scope: 'global', resource: 'controller-session-store' },
     `controller-claim:${input.controllerId}:${input.sessionId}`,
     () => {
-      assertWorkClaimable(options, input.workId);
+      assertControllerWorkClaimable(options, input.workId);
       const store = read(options);
       const current = activeSession(store, input.workId, optionsNowMs(options));
       const previous = current ?? store.sessions
@@ -470,45 +644,86 @@ export function claimControllerSession(
  * A same-principal session rotation therefore preserves ownership generation;
  * a controller-epoch change is recovery and advances the generation fence.
  */
+function resumableControllerSessionPrevious(
+  options: ControllerSessionStoreOptions,
+  store: ControllerSessionStore,
+  input: ControllerSessionClaimInput & { principalId: string; controllerInstanceId: string },
+  database?: SqliteDatabase,
+): ControllerSession | undefined {
+  assertControllerWorkClaimable(options, input.workId);
+  const currentNowMs = optionsNowMs(options);
+  const current = activeSession(store, input.workId, currentNowMs);
+  assertExpectedGeneration(input, current);
+  if (!current) {
+    return store.sessions
+      .filter((entry) => entry.workId === input.workId)
+      .sort((left, right) => (right.claimGeneration ?? 0) - (left.claimGeneration ?? 0))[0];
+  }
+  const explicitPrincipal = current.principalId?.trim();
+  const priorExecution = explicitPrincipal
+    ? undefined
+    : database
+      ? peekExecutionSessionWithinTransaction(database, options.controllerHome, current.sessionId)
+      : peekExecutionSession(options.controllerHome, current.sessionId);
+  const currentPrincipal = explicitPrincipal || 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 current;
+}
+
+export function withControllerSessionMutationLock<T>(
+  options: ControllerSessionStoreOptions,
+  workId: string,
+  actor: string,
+  operation: () => T,
+): T {
+  return withControllerLock(
+    options.controllerHome,
+    { scope: 'global', resource: 'controller-session-store' },
+    actor,
+    operation,
+  );
+}
+
+/** Transaction-aware resume used only by higher-level Controller claim orchestration while the canonical session lock is held. */
+export function resumeControllerSessionWithinTransaction(
+  database: SqliteDatabase,
+  options: ControllerSessionStoreOptions,
+  input: ControllerSessionClaimInput & { principalId: string; controllerInstanceId: string },
+): ClaimedControllerSession {
+  assertIdentity(input);
+  if (!input.principalId.trim() || !input.controllerInstanceId.trim()) throw new Error('CONTROLLER_RESUME_AUTHORITY_REQUIRED');
+  const storeRecord = readSessionStoreWithinTransaction(database, options);
+  const previous = resumableControllerSessionPrevious(options, storeRecord.value, input, database);
+  return persistClaimWithinTransaction(database, options, storeRecord, input, previous);
+}
+
 export function resumeControllerSession(
   options: ControllerSessionStoreOptions,
   input: ControllerSessionClaimInput & { principalId: string; controllerInstanceId: string },
-): ControllerSession {
+): ClaimedControllerSession {
   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}` },
+  return withControllerSessionMutationLock(
+    options,
+    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);
+      const previous = resumableControllerSessionPrevious(options, store, input);
+      return persistClaim(options, store, input, previous);
     },
   );
 }
@@ -531,40 +746,76 @@ export function bindControllerSessionToCurrentRuntime(
   },
 ): 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,
-  });
+  const currentRuntimeInstanceId = input.currentRuntimeInstanceId?.trim() || '';
+  return withControllerSessionMutationLock(
+    options,
+    input.workId,
+    `controller-bind-current-runtime:${input.controllerId}:${input.sessionId}`,
+    () => {
+      assertControllerWorkClaimable(options, input.workId);
+      const store = read(options);
+      const current = activeSession(store, input.workId, optionsNowMs(options));
+      const retained = current ? undefined : getRetainedControllerSession(options, input.workId);
+      const retainedMatchesIdentity = Boolean(
+        retained
+        && retained.controllerId === input.controllerId
+        && retained.controllerType === input.controllerType
+        && controllerSessionPrincipalId(retained) === input.principalId.trim(),
+      );
+      const previous = current ?? (input.allowClaimIfMissing === true && retainedMatchesIdentity ? retained : undefined);
+
+      if (!current && !previous && input.allowClaimIfMissing !== true) {
+        throw new Error(`WORK_CONTROLLER_OWNER_REQUIRED: ${input.workId}`);
+      }
+      if (!current && retainedMatchesIdentity) {
+        if (!currentRuntimeInstanceId || currentRuntimeInstanceId !== requestedInstanceId) {
+          throw new Error(`WORK_CONTROLLER_INSTANCE_MISMATCH: ${input.workId}`);
+        }
+      }
+
+      if (current) {
+        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() || '';
+        if (ownerInstanceId !== requestedInstanceId) {
+          if (!currentRuntimeInstanceId || currentRuntimeInstanceId !== requestedInstanceId) {
+            throw new Error(`WORK_CONTROLLER_INSTANCE_MISMATCH: ${input.workId}`);
+          }
+        }
+        const requestedAuthorityDigest = input.authorityDigest?.trim() || '';
+        const currentAuthorityDigest = current.authorityDigest?.trim() || '';
+        if (
+          ownerInstanceId === requestedInstanceId
+          && current.sessionId === input.sessionId
+          && (!requestedAuthorityDigest || requestedAuthorityDigest === currentAuthorityDigest)
+        ) return current;
+      }
+
+      // The opaque Work capability belongs to durable ownership, not to one
+      // transport or Runtime process. A positively-current Runtime migration keeps
+      // the same digest while claim generation fences the new controller epoch.
+      const preservedAuthorityDigest = input.authorityDigest?.trim() || previous?.authorityDigest?.trim() || undefined;
+      return persistClaim(options, store, {
+        ...input,
+        ...(preservedAuthorityDigest ? { authorityDigest: preservedAuthorityDigest } : {}),
+      }, previous);
+    },
+  );
 }
 
 export function releaseControllerSession(options: ControllerSessionStoreOptions, workId: string, controllerId: string): void {
   withControllerLock(
     options.controllerHome,
-    { scope: 'task', repoId: options.repoId, taskId: `controller-session-${workId}` },
+    { scope: 'global', resource: 'controller-session-store' },
     `controller-release:${controllerId}`,
     () => {
       const store = read(options);

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

@@ -8,6 +8,8 @@ export interface ControllerHostResumeResult {
   waitForUser?: boolean;
   /** Durable user-action Handoff created by the provider adapter when waitForUser=true. */
   handoffId?: string;
+  /** Known non-ambiguous provider failure that may retry the same semantic round under its existing failure budget. */
+  recoverable?: boolean;
 }
 
 /** Provider-neutral continuation port. Implementations live in adapters/*. */

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

@@ -1,5 +1,15 @@
 export * from '../domain/types';
 export * from '../domain/scope';
+export * from '../domain/grant';
 export * from '../application/identity-service';
 export * from '../domain/workspace';
 export * from '../domain/semantic-sync';
+export * from '../infrastructure/grant-store';
+export * from '../domain/user-request';
+export * from '../infrastructure/user-request-store';
+export * from '../domain/owned-resource';
+export * from '../infrastructure/owned-resource-store';
+export * from '../domain/capability-broker';
+export * from '../infrastructure/capability-broker';
+export * from '../domain/activity-projection';
+export * from '../infrastructure/activity-projection-store';

package/packages/kernel/identity/domain/activity-projection.ts

@@ -0,0 +1,43 @@
+/**
+ * Canonical Activity Projection Model.
+ * 
+ * GUI work tree is an explicit-link projection of Requirement / Plan / Work,
+ * while direct capability activity that has no Work appears in Activity/history
+ * rather than being forced into a synthetic Work.
+ * 
+ * Realtime progress comes from Process / Operation / Agent / provider snapshots
+ * with observedAt/freshness. History combines semantic revisions with selected
+ * immutable receipts and terminal operation events.
+ */
+
+export interface CapabilityActivityItem {
+  activityId: string;
+  capabilityId: string;
+  kind: 'direct_execution' | 'agent_delegation' | 'scheduled_trigger' | 'work_bound';
+  targetScope: string;
+  principalId: string;
+  associatedWorkId?: string;
+  status: 'running' | 'completed' | 'failed' | 'cancelled';
+  startedAt: string;
+  completedAt?: string;
+  summary?: string;
+  receiptRef?: string;
+}
+
+export interface WorkTreeProjectionNode {
+  type: 'requirement' | 'plan' | 'work';
+  id: string;
+  title?: string;
+  status: string;
+  revision: number;
+  updatedAt: string;
+  parentId?: string;
+  children?: WorkTreeProjectionNode[];
+}
+
+export interface UnifiedActivityView {
+  workTree: WorkTreeProjectionNode[];
+  directActivities: CapabilityActivityItem[];
+  observedAt: string;
+  freshnessMs: number;
+}