@moretea-labs/forge 1.7.1 → 1.8.0

package/src/runtime/control-plane/launcher/provider-mcp-bootstrap.ts

@@ -12,6 +12,23 @@ export interface ProviderMcpBootstrap {
   env: NodeJS.ProcessEnv;
 }
 
+export interface ProviderMcpReservationIdentity {
+  principalId: string;
+  sessionId: string;
+}
+
+export function providerMcpReservationIdentity(
+  provider: 'codex',
+  reservationId: string,
+): ProviderMcpReservationIdentity {
+  const suffix = reservationId.trim();
+  if (!suffix) throw new Error('LAUNCHER_RESERVATION_ID_REQUIRED');
+  return {
+    principalId: `external:${provider}:${suffix}`,
+    sessionId: `external-session:${provider}:${suffix}`,
+  };
+}
+
 function runtimeMcpUrl(controllerHome: string): string {
   const observed = observeRuntimeStatus(controllerHome);
   if (!observed.running || !observed.ready) {
@@ -33,13 +50,12 @@ export function resolveProviderMcpBootstrap(
   const config = readForgeRuntimeServiceConfig(forgeRuntimeServicePaths(controllerHome).configPath);
   const token = readFileSync(config.authTokenFile, 'utf8').trim();
   if (!token) throw new Error('LAUNCHER_RUNTIME_MCP_TOKEN_EMPTY');
-  const suffix = reservationId.trim();
-  if (!suffix) throw new Error('LAUNCHER_RESERVATION_ID_REQUIRED');
+  const identity = providerMcpReservationIdentity(provider, reservationId);
   return {
     url: runtimeMcpUrl(controllerHome),
     bearerTokenEnvVar: FORGE_RUNTIME_MCP_TOKEN_ENV,
-    principalId: `external:${provider}:${suffix}`,
-    sessionId: `external-session:${provider}:${suffix}`,
+    principalId: identity.principalId,
+    sessionId: identity.sessionId,
     env: {
       ...process.env,
       [FORGE_RUNTIME_MCP_TOKEN_ENV]: token,

package/src/runtime/control-plane/launcher/thin-launcher.ts

@@ -13,9 +13,14 @@ import {
   reserveExternalControllerLaunch,
 } from './launch-reservation-store';
 import type { ControllerType } from '../facade/types';
-import { getControllerSession } from '../facade/controller-session-store';
+import {
+  beginControllerRoundRelayAfterRelease,
+  getControllerSession,
+  reconcileControllerRoundAfterAbandonedRelease,
+  releaseControllerSessionWithAuthority,
+} from '../../../../packages/kernel/controller/api/index';
 import { codexMcpConfigArgs, resolveProviderMcpBootstrap, type ProviderMcpBootstrap } from './provider-mcp-bootstrap';
-import { getChatgptWorkConversationBinding } from './chatgpt-work-binding-store';
+import { getChatgptWorkConversationBinding } from '../../../../adapters/chatgpt/work-conversation-binding-store';
 import { repositoryChildProcessEnvironment } from '../../shared/process-environment';
 import { redactProcessOutput } from '../../../effects/process-runner';
 
@@ -203,6 +208,43 @@ async function awaitExternalControllerStartup(
       } catch {
         // Exit evidence is best-effort after another authority has already released the reservation.
       }
+      if (claimExpectation) {
+        try {
+          const owner = getControllerSession(stores.work, workId);
+          const ownerPrincipal = owner ? (owner.principalId?.trim() || owner.controllerId) : '';
+          const ownerInstanceId = owner?.controllerInstanceId?.trim() || '';
+          const exactLaunchedOwner = Boolean(
+            owner
+            && owner.controllerType === claimExpectation.controllerType
+            && owner.controllerId === claimExpectation.controllerId
+            && ownerPrincipal === claimExpectation.principalId
+            && owner.sessionId === claimExpectation.sessionId
+            && ownerInstanceId
+            && typeof owner.claimGeneration === 'number'
+            && owner.claimGeneration >= 1,
+          );
+          if (owner && exactLaunchedOwner) {
+            const released = releaseControllerSessionWithAuthority(stores.work, {
+              workId,
+              actor: `external-controller-exit:${reservationId}`,
+              authority: {
+                controllerId: owner.controllerId,
+                controllerType: owner.controllerType,
+                principalId: ownerPrincipal,
+                controllerInstanceId: ownerInstanceId,
+                claimGeneration: owner.claimGeneration!,
+              },
+            });
+            if (released.allowed) {
+              const relay = beginControllerRoundRelayAfterRelease(stores.work, { workId, releasedSession: owner });
+              if (!relay) reconcileControllerRoundAfterAbandonedRelease(stores.work, { workId, releasedSession: owner });
+            }
+          }
+        } catch {
+          // The launcher may only retire the exact reservation-bound ownership epoch.
+          // A concurrent/new owner or relay transition is authoritative and must win.
+        }
+      }
       if (startupSettled) return;
       startupSettled = true;
       clearTimer();
@@ -306,6 +348,10 @@ export function buildSuperControllerInvocation(
       executable,
       args: [
         '--ask-for-approval', 'never',
+        // A launched Codex controller must use the reservation-scoped Forge MCP
+        // transport below, never a globally configured Codex App that happens to
+        // expose another Forge tool surface under a shared principal.
+        '--disable', 'apps',
         ...codexMcpConfigArgs(mcpBootstrap),
         'exec', '--sandbox', 'workspace-write',
         ...(request.args ?? []),
@@ -374,7 +420,7 @@ export async function launchSuperController(
       `Continue Forge Work ${work.workId} in repo ${work.repoId}.`,
       handoff ? `Handoff: ${handoff.summary}\nNext: ${handoff.recommendedContinuationPrompt ?? handoff.recommendedPrompt}` : '',
       request.continuationPrompt?.trim() ? `Continuation: ${request.continuationPrompt.trim()}` : '',
-      `No Controller ownership was preclaimed for this continued conversation. First call rh_work operation=controller_claim with repo_id=${work.repoId}, work_id=${work.workId}, and controller_type=chatgpt through your authenticated MCP session; do not invent controller_id/session_id. Only after that exact Work claim succeeds, call rh_work operation=continue with the same repo_id/work_id. Treat Forge Work/Plan/evidence as source of truth; do not invent new scope from chat history. If the claim does not succeed, do not mutate. Continue the next safe action, finalize only when acceptance passes, and create a HandoffItem when judgement is required.`,
+      `No Controller ownership was preclaimed for this continued conversation. First call rh_work operation=controller_claim with repo_id=${work.repoId}, work_id=${work.workId}, and controller_type=chatgpt through your authenticated MCP session; do not invent controller_id/session_id. When that exact Work claim succeeds, capture data.controllerAuthorityId from the response as the opaque Work-bound controller capability. Pass that exact value unchanged as controller_authority_id on the following rh_work operation=continue and every later lifecycle call for this Work, including verify, finalize, stop, and controller_release; if the current frozen client schema does not expose controller_authority_id, pass the same opaque value as session_id compatibility carrier. Never use data.session.sessionId as the durable capability because MCP execution sessions may be replaced or invalidated. Treat Forge Work/Plan/evidence as source of truth; do not invent new scope from chat history. If the claim does not succeed, do not mutate. Continue the next safe action, finalize only when acceptance passes, and create a HandoffItem when judgement is required.`,
     ].filter(Boolean).join('\n')
     : [
       `Work: ${work.workId}`,
@@ -383,7 +429,7 @@ export async function launchSuperController(
       `Current status: ${work.status}`,
       handoff ? `Handoff: ${handoff.summary}\nNext: ${handoff.recommendedContinuationPrompt ?? handoff.recommendedPrompt}` : '',
       request.continuationPrompt?.trim() ? `Continuation: ${request.continuationPrompt.trim()}` : '',
-      `No Controller ownership was preclaimed for you. First call rh_work operation=controller_claim with repo_id=${work.repoId}, work_id=${work.workId}, and controller_type=${request.controllerType} through your authenticated MCP session; do not invent controller_id/session_id. Only after that exact Work claim succeeds, call rh_work operation=continue with the same repo_id/work_id and continue the returned next safe action. If the claim does not succeed, do not mutate the repository: create no patch, command, commit, or test run until ownership is established. Then use the repository MCP facade, record verification evidence, finalize only when acceptance passes, and create a HandoffItem when judgement is required.`, 
+      `No Controller ownership was preclaimed for you. First call rh_work operation=controller_claim with repo_id=${work.repoId}, work_id=${work.workId}, and controller_type=${request.controllerType} through your authenticated MCP session; do not invent controller_id/session_id. When that exact Work claim succeeds, capture data.controllerAuthorityId from the response as the opaque Work-bound controller capability. Pass that exact value unchanged as controller_authority_id on the following rh_work operation=continue and every later lifecycle call for this Work, including verify, finalize, stop, and controller_release; if the current frozen client schema does not expose controller_authority_id, pass the same opaque value as session_id compatibility carrier. Never use data.session.sessionId as the durable capability because MCP execution sessions may be replaced or invalidated. If the claim does not succeed, do not mutate the repository: create no patch, command, commit, or test run until ownership is established. Then use the repository MCP facade, record verification evidence, finalize only when acceptance passes, and create a HandoffItem when judgement is required.`,
     ].filter(Boolean).join('\n');
   try {
     const mcpBootstrap = request.controllerType === 'codex'

package/src/runtime/control-plane/lifecycle-retention-metrics.ts

@@ -0,0 +1,60 @@
+import { lstatSync, readdirSync } from 'fs';
+import { join } from 'path';
+
+export const RUNTIME_LIFECYCLE_RETENTION_POLICY_VERSION = 'runtime-lifecycle-retention-v1';
+export const DEFAULT_RECLAIM_SIZE_SCAN_BUDGET = 10_000;
+
+export interface ReclaimablePathMeasurement {
+  bytes: number;
+  entries: number;
+  complete: boolean;
+}
+
+/**
+ * Measure a cleanup candidate before deletion without turning accounting into
+ * an unbounded filesystem walk. A truncated measurement is never presented as
+ * exact reclaimed bytes; callers must increment unknownReclaimedByteCount.
+ */
+export function measureReclaimablePath(
+  path: string,
+  maxEntries = DEFAULT_RECLAIM_SIZE_SCAN_BUDGET,
+): ReclaimablePathMeasurement {
+  let remaining = Math.max(1, Math.floor(maxEntries));
+  let bytes = 0;
+  let entries = 0;
+  let complete = true;
+
+  const visit = (current: string): void => {
+    if (remaining <= 0) {
+      complete = false;
+      return;
+    }
+    remaining -= 1;
+    entries += 1;
+    let stats;
+    try {
+      stats = lstatSync(current);
+    } catch {
+      complete = false;
+      return;
+    }
+    if (!stats.isDirectory() || stats.isSymbolicLink()) {
+      bytes += Math.max(0, stats.size);
+      return;
+    }
+    let children: string[];
+    try {
+      children = readdirSync(current);
+    } catch {
+      complete = false;
+      return;
+    }
+    for (const child of children) {
+      visit(join(current, child));
+      if (!complete && remaining <= 0) return;
+    }
+  };
+
+  visit(path);
+  return { bytes, entries, complete };
+}

package/src/runtime/control-plane/persistence/experience-store.ts

@@ -0,0 +1,169 @@
+import { readForgeInstanceIdentity } from '../../../../packages/kernel/identity/api/index';
+import { resolveProjectForRepositoryPlacement } from '../workspace/workspace-store';
+import type { ScopeRef } from '../../../../packages/kernel/identity/api/index';
+import type { ExperienceRecord, ExperienceStorePort, OutcomeObservation, OutcomeObservationStorePort } from '../../../../packages/kernel/memory/api/index';
+import { getWorkContract, isTerminalWorkContractStatus, type WorkContract } from '../../../../packages/kernel/work/api/index';
+import { controllerSessionAuthorityMatches, getControllerRoundRelay, getControllerSession } from '../../../../packages/kernel/controller/api/index';
+import { readExecutionArtifact } from '../../evidence/artifact-store';
+import { readExecutionEvidence } from '../../evidence/evidence-store';
+import { assertControlPlaneMetadataPayload } from './metadata-payload-policy';
+import { WORKFLOW_RUN_NAMESPACE, type WorkflowRunRecord } from './workflow-run-store';
+import { deleteControlPlaneRecordWithinTransaction, listControlPlaneRecords, listControlPlaneRecordsWithinTransaction, readControlPlaneRecord, readControlPlaneRecordWithinTransaction, withControlPlaneTransaction, writeControlPlaneRecordWithinTransaction, type SqliteDatabase } from './sqlite-store';
+
+export const EXPERIENCE_NAMESPACE = 'assistant_experience';
+export const OUTCOME_OBSERVATION_NAMESPACE = 'assistant_outcome_observation';
+export interface ExperienceWriteIdentity { workId: string; controllerId: string; authorityId: string }
+
+export function experienceScopesForWork(work: WorkContract, controllerHome?: string): ScopeRef[] {
+  const scopes: ScopeRef[] = [{ schemaVersion: 1, kind: 'work', id: work.workId }];
+  const declaredProject = work.scopeRef?.kind === 'project' ? work.scopeRef.id : work.engineeringContext?.projectContractReceipt?.projectId;
+  const instance = controllerHome ? readForgeInstanceIdentity(controllerHome) : undefined;
+  const projectId = controllerHome && instance ? resolveProjectForRepositoryPlacement({ controllerHome,
+    forgeInstanceId: instance.instanceId, repositoryId: work.repoId, checkoutId: work.checkoutId, projectId: declaredProject })?.projectId ?? declaredProject : declaredProject;
+  if (projectId) scopes.push({ schemaVersion: 1, kind: 'project', id: projectId });
+  if (work.requirementId) scopes.push({ schemaVersion: 1, kind: 'requirement', id: work.requirementId });
+  if (work.planId) scopes.push({ schemaVersion: 1, kind: 'plan', id: work.planId });
+  if (work.planStepId) scopes.push({ schemaVersion: 1, kind: 'plan_step', id: work.planStepId });
+  if (work.scopeRef && !scopes.some(s => s.kind === work.scopeRef!.kind && s.id === work.scopeRef!.id)) scopes.push(work.scopeRef);
+  return scopes;
+}
+
+function matchesScope(work: WorkContract, scope: ScopeRef, controllerHome: string): boolean {
+  return experienceScopesForWork(work, controllerHome).some(candidate => candidate.kind === scope.kind && candidate.id === scope.id);
+}
+
+function canonicalWorkflowEvidenceAvailable(input: { controllerHome: string; repoId: string }, ref: string, scope: ScopeRef, sourceWorkId: string): boolean {
+  try {
+    const source = getWorkContract(input, sourceWorkId);
+    if (!source || !matchesScope(source, scope, input.controllerHome)) return false;
+    const linked = source.evidenceRefs.find(item => item.evidenceId === ref || item.artifactId === ref);
+    if (linked) {
+      if (ref.startsWith('ART-')) {
+        const artifact = readExecutionArtifact(input.controllerHome, input.repoId, ref, 16 * 1024);
+        return !artifact.truncated && artifact.artifact.kind === 'evidence';
+      }
+      if (ref.startsWith('EVD-')) return readExecutionEvidence(input.controllerHome, input.repoId, ref).evidenceId === ref;
+    }
+    if (source.checkRefs.some(check => check.receipt?.receiptId === ref && ['passed', 'failed'].includes(check.receipt.status))) return true;
+    if (ref.startsWith('workflow-run-') || ref.startsWith('workflow-publication-')) {
+      const runs = listControlPlaneRecords<WorkflowRunRecord>(input.controllerHome, { namespace: WORKFLOW_RUN_NAMESPACE, scope: sourceWorkId, limit: 1000 });
+      return runs.some(row => row.value.evidenceRef === ref || row.value.publicationReceipt?.receiptId === ref);
+    }
+    const outcome = readControlPlaneRecord<OutcomeObservation>(input.controllerHome, OUTCOME_OBSERVATION_NAMESPACE, `${scope.kind}:${scope.id}`, ref)?.value;
+    if (outcome && outcome.sourceWorkId === sourceWorkId) {
+      return canonicalWorkflowEvidenceAvailable(input, outcome.evidenceRef, scope, sourceWorkId);
+    }
+    return false;
+  } catch { return false; }
+}
+
+function assertMemoryWriteAuthority(input: { controllerHome: string; repoId: string; identity?: ExperienceWriteIdentity }, scope: ScopeRef, sourceWorkId: string, sourceRoundId: string): void {
+  const identity = input.identity;
+  if (!identity) throw new Error('EXPERIENCE_CONTROLLER_REQUIRED');
+  const current = getWorkContract(input, identity.workId), source = getWorkContract(input, sourceWorkId);
+  if (!current || isTerminalWorkContractStatus(current.status) || !source || !matchesScope(current, scope, input.controllerHome) || !matchesScope(source, scope, input.controllerHome)) throw new Error('EXPERIENCE_WORK_SCOPE_MISMATCH');
+  const owner = getControllerSession(input, identity.workId);
+  if (!owner || owner.controllerId !== identity.controllerId) throw new Error('EXPERIENCE_CONTROLLER_NOT_OWNER');
+  const relay = getControllerRoundRelay(input, identity.workId);
+  if (relay) {
+    if (relay.status !== 'claimed' || relay.authorityId !== identity.authorityId || relay.claimGeneration !== owner.claimGeneration
+      || sourceRoundId !== `${relay.relayScopeId}:${relay.roundCount}`) throw new Error('EXPERIENCE_ROUND_AUTHORITY_MISMATCH');
+  } else if (!controllerSessionAuthorityMatches(owner, identity.authorityId)
+    || sourceRoundId !== `${identity.workId}:${owner.claimGeneration}`) throw new Error('EXPERIENCE_CLAIM_AUTHORITY_MISMATCH');
+}
+
+/** One SQLite writer; nested domain operations share the same transaction. */
+export function controllerExperienceStore(input: { controllerHome: string; repoId: string; identity?: ExperienceWriteIdentity; now?: () => string }): ExperienceStorePort {
+  let transaction: SqliteDatabase | undefined;
+  const key = (scope: ScopeRef) => `${scope.kind}:${scope.id}`;
+  const work = (id: string) => getWorkContract(input, id);
+  return {
+    transaction(operation) {
+      if (transaction) return operation();
+      return withControlPlaneTransaction(input.controllerHome, database => {
+        transaction = database;
+        try { return operation(); } finally { transaction = undefined; }
+      });
+    },
+    assertWriteAuthority(scope, sourceWorkId, sourceRoundId) {
+      assertMemoryWriteAuthority(input, scope, sourceWorkId, sourceRoundId);
+    },
+    evidenceAvailable(ref, scope, sourceWorkId) {
+      return canonicalWorkflowEvidenceAvailable(input, ref, scope, sourceWorkId);
+    },
+    read(scope, id) {
+      const row = transaction ? readControlPlaneRecordWithinTransaction<ExperienceRecord>(transaction, EXPERIENCE_NAMESPACE, key(scope), id)
+        : readControlPlaneRecord<ExperienceRecord>(input.controllerHome, EXPERIENCE_NAMESPACE, key(scope), id);
+      if (row && row.value.revision !== row.revision) throw new Error('EXPERIENCE_STORED_REVISION_MISMATCH');
+      return row?.value;
+    },
+    list(scope, limit) {
+      const query = { namespace: EXPERIENCE_NAMESPACE, scope: key(scope), limit };
+      return (transaction ? listControlPlaneRecordsWithinTransaction<ExperienceRecord>(transaction, query)
+        : listControlPlaneRecords<ExperienceRecord>(input.controllerHome, query)).map(row => row.value);
+    },
+    write(record, expectedRevision) {
+      if (!transaction) throw new Error('EXPERIENCE_TRANSACTION_REQUIRED');
+      assertControlPlaneMetadataPayload(record, 'experience', 16 * 1024);
+      const row = writeControlPlaneRecordWithinTransaction(transaction, { namespace: EXPERIENCE_NAMESPACE, scope: key(record.scope), key: record.id,
+        schemaVersion: 1, value: record, expectedRevision, action: record.retractedAt ? 'experience_retracted' : record.supersedesId ? 'experience_superseded' : 'experience_recorded' });
+      if (row.revision !== record.revision) throw new Error('EXPERIENCE_REVISION_CONFLICT');
+    },
+    assertSafePayload: record => assertControlPlaneMetadataPayload(record, 'experience', 16 * 1024),
+  };
+}
+
+export function controllerOutcomeObservationStore(input: { controllerHome: string; repoId: string; identity?: ExperienceWriteIdentity; now?: () => string }): OutcomeObservationStorePort {
+  let transaction: SqliteDatabase | undefined;
+  const key = (scope: ScopeRef) => `${scope.kind}:${scope.id}`;
+  return {
+    transaction(operation) {
+      if (transaction) return operation();
+      return withControlPlaneTransaction(input.controllerHome, database => {
+        transaction = database;
+        try { return operation(); } finally { transaction = undefined; }
+      });
+    },
+    assertWriteAuthority(scope, sourceWorkId, sourceRoundId) { assertMemoryWriteAuthority(input, scope, sourceWorkId, sourceRoundId); },
+    evidenceAvailable(ref, scope, sourceWorkId) { return canonicalWorkflowEvidenceAvailable(input, ref, scope, sourceWorkId); },
+    read(scope, id) {
+      const row = transaction ? readControlPlaneRecordWithinTransaction<OutcomeObservation>(transaction, OUTCOME_OBSERVATION_NAMESPACE, key(scope), id)
+        : readControlPlaneRecord<OutcomeObservation>(input.controllerHome, OUTCOME_OBSERVATION_NAMESPACE, key(scope), id);
+      return row?.value;
+    },
+    list(scope, limit) {
+      const query = { namespace: OUTCOME_OBSERVATION_NAMESPACE, scope: key(scope), limit };
+      return (transaction ? listControlPlaneRecordsWithinTransaction<OutcomeObservation>(transaction, query)
+        : listControlPlaneRecords<OutcomeObservation>(input.controllerHome, query)).map(row => row.value);
+    },
+    write(observation) {
+      if (!transaction) throw new Error('OUTCOME_TRANSACTION_REQUIRED');
+      assertControlPlaneMetadataPayload(observation, 'outcome_observation', 32 * 1024);
+      writeControlPlaneRecordWithinTransaction(transaction, { namespace: OUTCOME_OBSERVATION_NAMESPACE, scope: key(observation.scope), key: observation.id,
+        schemaVersion: 1, value: observation, expectedRevision: null, action: 'outcome_observation_recorded' });
+    },
+    assertSafePayload: observation => assertControlPlaneMetadataPayload(observation, 'outcome_observation', 32 * 1024),
+  };
+}
+
+/** Called by central maintenance, never by recall. A 30-day terminal grace preserves diagnosis. */
+export function cleanupExpiredExperiences(controllerHome: string, now = new Date().toISOString(), limit = 100): number {
+  const at = Date.parse(now);
+  if (!Number.isFinite(at)) throw new Error('EXPERIENCE_CLEANUP_TIME_INVALID');
+  return withControlPlaneTransaction(controllerHome, database => {
+    let removed = 0;
+    if (!Number.isSafeInteger(limit) || limit < 1) throw new Error('EXPERIENCE_CLEANUP_LIMIT_INVALID');
+    // Filter terminal candidates before LIMIT so immortal lessons cannot starve retirement.
+    // SQLite parses ISO offsets; lexicographic comparison would be incorrect for mixed offsets.
+    const candidates = database.prepare(`SELECT scope, record_key FROM control_plane_records
+      WHERE namespace = ? AND julianday(COALESCE(json_extract(payload, '$.retractedAt'), json_extract(payload, '$.expiresAt'))) <= julianday(?)
+      ORDER BY updated_at, scope, record_key LIMIT ?`).all(EXPERIENCE_NAMESPACE, new Date(at - 30 * 86_400_000).toISOString(), Math.min(1000, limit)) as Array<{ scope: string; record_key: string }>;
+    for (const candidate of candidates) {
+      const row = readControlPlaneRecordWithinTransaction<ExperienceRecord>(database, EXPERIENCE_NAMESPACE, candidate.scope, candidate.record_key);
+      if (!row) continue;
+      deleteControlPlaneRecordWithinTransaction(database, { namespace: EXPERIENCE_NAMESPACE, scope: row.scope, key: row.key, expectedRevision: row.revision, action: 'experience_expired_retention' });
+      removed++;
+    }
+    return removed;
+  });
+}