@moretea-labs/forge 1.5.0-rc.1 → 1.5.0

package/src/runtime/gateway/mcp/work-validation-reconciler.ts

@@ -1,219 +1 @@
-import {
-  getWorkContract,
-  transitionWorkContractPhase,
-  updateWorkContract,
-} from '../../control-plane/facade/work-contract-store';
-import {
-  transitionWorkHandle,
-  type WorkHandleState,
-} from '../../control-plane/execution/work-handle-store';
-import { processCheckCompletionReceipt } from '../../execution/process-runtime/check-receipt';
-import { processCheckSemanticScopeKey } from '../../execution/process-runtime/check-facade';
-import { getProcessRecord } from '../../execution/process-runtime/store';
-import { controllerCheckExecutionIdentity } from '../../../cli/controller/check-runner';
-
-export type WorkValidationOutcome =
-  | 'not_validating'
-  | 'running'
-  | 'passed'
-  | 'failed'
-  | 'infrastructure_failure';
-
-export interface WorkValidationReconciliation {
-  handle: WorkHandleState;
-  changed: boolean;
-  outcome: WorkValidationOutcome;
-  summary?: string;
-}
-
-export function hasCurrentWorkValidationAuthority(input: {
-  finalizationValidation: WorkHandleState['finalization']['validation'];
-  validatedInputFingerprint?: string;
-  evidenceState: string;
-  expectedFingerprint: string;
-}): boolean {
-  return input.finalizationValidation === 'done'
-    && input.evidenceState === 'valid'
-    && input.validatedInputFingerprint === input.expectedFingerprint;
-}
-
-/**
- * A new validation run invalidates delivery authority without deleting or
- * rewriting the prior receipts. `stale` is the only valid transition from an
- * already-valid evidence set; all other retryable states converge through
- * `partial`.
- */
-export function markWorkValidationPending(controllerHome: string, handle: WorkHandleState): void {
-  const contractId = handle.workContractId;
-  if (!contractId) return;
-  const options = { controllerHome, repoId: handle.repositoryId };
-  const contract = getWorkContract(options, contractId);
-  if (!contract || contract.completionReceipt) return;
-  const evidenceState = contract.evidenceState === 'valid' || contract.evidenceState === 'stale'
-    ? 'stale'
-    : 'partial';
-  if (contract.evidenceState !== evidenceState) updateWorkContract(options, contractId, { evidenceState });
-}
-
-/**
- * Project durable validation evidence into the Work-owned contract lifecycle.
- * Process and Check records contribute evidence only; they never become a
- * second completion or lifecycle authority.
- */
-export function projectWorkValidationOutcome(
-  controllerHome: string,
-  handle: WorkHandleState,
-  outcome: Exclude<WorkValidationOutcome, 'not_validating' | 'running'>,
-  summary?: string,
-): void {
-  const contractId = handle.workContractId;
-  if (!contractId) return;
-  const options = { controllerHome, repoId: handle.repositoryId };
-  const contract = getWorkContract(options, contractId);
-  if (!contract || contract.completionReceipt) return;
-
-  if (outcome === 'passed') {
-    transitionWorkContractPhase(options, contractId, {
-      phase: 'delivery',
-      status: 'running',
-      state: 'active',
-      summary: summary ?? 'All requested validation receipts passed; delivery is next.',
-      evidenceRefs: contract.evidenceRefs,
-    });
-    updateWorkContract(options, contractId, { evidenceState: 'valid' });
-    return;
-  }
-
-  if (outcome === 'failed') {
-    transitionWorkContractPhase(options, contractId, {
-      phase: 'cleanup',
-      status: 'failed',
-      state: 'failed',
-      summary: summary ?? 'A requested validation check failed; terminal cleanup is next.',
-      evidenceRefs: contract.evidenceRefs,
-    });
-    updateWorkContract(options, contractId, { evidenceState: 'failed' });
-    return;
-  }
-
-  transitionWorkContractPhase(options, contractId, {
-    phase: 'cleanup',
-    status: 'failed',
-    state: 'failed',
-    summary: summary ?? 'Validation infrastructure failed; terminal cleanup is required without treating this as an acceptance failure.',
-    evidenceRefs: contract.evidenceRefs,
-  });
-  updateWorkContract(options, contractId, {
-    evidenceState: contract.evidenceState === 'valid' || contract.evidenceState === 'stale' ? 'stale' : 'partial',
-  });
-}
-
-function settleInfrastructureFailure(
-  controllerHome: string,
-  handle: WorkHandleState,
-  summary: string,
-): WorkValidationReconciliation {
-  const next = transitionWorkHandle(controllerHome, handle, 'failed', {
-    finalization: { ...handle.finalization, validation: 'failed', lastError: summary },
-    validationRun: undefined,
-    failureReason: summary,
-  });
-  projectWorkValidationOutcome(controllerHome, next, 'infrastructure_failure', summary);
-  return { handle: next, changed: true, outcome: 'infrastructure_failure', summary };
-}
-
-/**
- * Converge a persisted Work validation run from durable Process receipts.
- *
- * No command is launched here. Missing/running bindings stay pending; timeout,
- * cancellation, missing process state, or malformed receipt makes the Work
- * terminally failed for cleanup without classifying it as an acceptance failure.
- */
-export function reconcileWorkValidation(
-  controllerHome: string,
-  handle: WorkHandleState,
-): WorkValidationReconciliation {
-  const run = handle.validationRun;
-  if (handle.state !== 'validating' || !run) {
-    return { handle, changed: false, outcome: 'not_validating' };
-  }
-
-  if (run.requestedChecks.length === 0) {
-    const next = transitionWorkHandle(controllerHome, handle, run.resumeState, {
-      finalization: { ...handle.finalization, validation: 'done', lastError: undefined },
-      validationRun: undefined,
-      validatedInputFingerprint: run.fingerprint,
-      failureReason: undefined,
-    });
-    projectWorkValidationOutcome(controllerHome, next, 'passed', 'No validation checks were required.');
-    return { handle: next, changed: true, outcome: 'passed' };
-  }
-
-  for (const checkId of run.requestedChecks) {
-    const binding = run.processes[checkId];
-    if (!binding) return { handle, changed: false, outcome: 'running' };
-    const record = getProcessRecord(controllerHome, handle.repositoryId, binding.processId);
-    if (!record) {
-      return settleInfrastructureFailure(
-        controllerHome,
-        handle,
-        `Validation process record is unavailable: ${binding.processId}`,
-      );
-    }
-    if (record.status === 'running' || record.status === 'starting' || record.status === 'running_recovered') {
-      return { handle, changed: false, outcome: 'running' };
-    }
-
-    try {
-      const currentIdentity = record.checkExecution
-        ? controllerCheckExecutionIdentity(handle.worktreePath, checkId, record.checkExecution.timeoutMs)
-        : undefined;
-      const receipt = processCheckCompletionReceipt(record, {
-        repoId: handle.repositoryId,
-        checkoutId: handle.checkoutId,
-        workId: handle.workId,
-        executionSessionId: handle.sessionId,
-        checkId,
-        processId: binding.processId,
-        ...(currentIdentity ? {
-          checkExecution: {
-            cacheKey: currentIdentity.cacheKey,
-            revision: currentIdentity.revision,
-            definitionDigest: currentIdentity.definitionDigest,
-            environmentFingerprint: currentIdentity.environmentFingerprint,
-            timeoutMs: currentIdentity.timeoutMs,
-            scopeKey: processCheckSemanticScopeKey({
-              checkoutId: handle.checkoutId,
-              workId: handle.workId,
-              verificationBinding: { executionSessionId: handle.sessionId },
-            }, currentIdentity.reuseScope),
-          },
-        } : {}),
-      });
-      if (!receipt.ok) {
-        if (receipt.status === 'timed_out' || receipt.status === 'cancelled') {
-          return settleInfrastructureFailure(controllerHome, handle, receipt.summary);
-        }
-        const next = transitionWorkHandle(controllerHome, handle, 'failed', {
-          finalization: { ...handle.finalization, validation: 'failed', lastError: receipt.summary },
-          validationRun: undefined,
-          failureReason: receipt.summary,
-        });
-        projectWorkValidationOutcome(controllerHome, next, 'failed', receipt.summary);
-        return { handle: next, changed: true, outcome: 'failed', summary: receipt.summary };
-      }
-    } catch (error) {
-      const summary = error instanceof Error ? error.message : String(error);
-      return settleInfrastructureFailure(controllerHome, handle, summary);
-    }
-  }
-
-  const next = transitionWorkHandle(controllerHome, handle, run.resumeState, {
-    finalization: { ...handle.finalization, validation: 'done', lastError: undefined },
-    validationRun: undefined,
-    validatedInputFingerprint: run.fingerprint,
-    failureReason: undefined,
-  });
-  projectWorkValidationOutcome(controllerHome, next, 'passed', 'All requested validation receipts passed.');
-  return { handle: next, changed: true, outcome: 'passed' };
-}
+export * from '../../control-plane/execution/work-validation-reconciler';

package/src/runtime/plugins/browser-adapter.ts

@@ -383,6 +383,11 @@ function loadConfig(repoRoot: string): BrowserPluginConfig {
   return normalizeConfig(readJson<Partial<BrowserPluginConfig>>(configPath(repoRoot)) ?? {});
 }
 
+export function readBrowserPluginConfiguration(repoRoot: string): { enabled: boolean; allowedDomains: string[] } {
+  const config = loadConfig(repoRoot);
+  return { enabled: config.enabled, allowedDomains: [...(config.allowedDomains ?? [])] };
+}
+
 function saveConfig(repoRoot: string, patch: Partial<BrowserPluginConfig>): BrowserPluginConfig {
   const next = normalizeConfig({ ...loadConfig(repoRoot), ...patch });
   writeJson(configPath(repoRoot), next);

package/src/runtime/plugins/desktop-operator-registration.ts

@@ -384,7 +384,7 @@ export function createDesktopOperatorRegistrationInput(
     providerPluginId: 'desktop_operator',
     displayName: 'Forge Desktop Operator',
     provider: 'local-macos',
-    pluginVersion: options.pluginVersion ?? '0.1.0',
+    pluginVersion: options.pluginVersion ?? '0.2.1',
     protocolVersion: options.protocolVersion ?? '1.0',
     scope: 'controller',
     enabled: options.enabled !== false,

package/src/runtime/plugins/store.ts

@@ -265,13 +265,21 @@ function writeRegistry(controllerHome: string, repoId: string, manifests: Assist
   return index;
 }
 
-function mapResourceClaims(action: AssistantPluginActionDescriptor, repository: RepositoryRecord): ResourceClaimSpec[] {
+export function claimsForAssistantPluginAction(
+  action: AssistantPluginActionDescriptor,
+  repository: RepositoryRecord,
+  trustedPluginId: string,
+): ResourceClaimSpec[] {
   const controllerScoped = repository.repoId === CONTROLLER_SCOPE_REPO_ID;
+  const pluginId = trustedPluginId.trim().replace(/[^a-zA-Z0-9._-]+/g, '-');
+  if (!pluginId) throw new Error('PLUGIN_ID_REQUIRED_FOR_RESOURCE_CLAIMS');
   return action.resourceClaims.map((claim) => ({
-    resourceKey: controllerScoped
-      ? `controller-system:${claim.resource}`
-      : claim.resource === 'remote'
-        ? `remote:${repository.repoId}`
+    resourceKey: claim.resource === 'remote' || claim.resource === 'provider-state'
+      // The manifest/plugin id was resolved from the trusted registration; a
+      // provider never supplies arbitrary resource-key text.
+      ? `provider-state:${pluginId}`
+      : controllerScoped
+        ? `controller-system:${claim.resource}`
         : claim.resource === 'workspace'
           ? `workspace:${repository.activeCheckoutId}`
           : claim.resource === 'git-refs'
@@ -764,7 +772,7 @@ export async function submitAssistantPluginAction(
           mode: 'mutating',
           idempotent: action.idempotent,
           replayable: action.idempotent,
-          resourceClaims: mapResourceClaims(action, repository),
+          resourceClaims: claimsForAssistantPluginAction(action, repository, manifest.pluginId),
         },
         objective: `Execute bounded controller-local effect ${request.pluginId}/${request.actionId}`,
         mode: 'direct_control',

package/src/runtime/plugins/types.ts

@@ -4,7 +4,7 @@ export type AssistantPluginLifecycleState = 'enabled' | 'disabled' | 'degraded'
 export type AssistantPluginHealthState = 'ready' | 'disabled' | 'degraded' | 'error';
 export type AssistantPluginActionRisk = 'readonly' | 'workspace_write' | 'remote_write' | 'destructive';
 export type AssistantPluginActionConfirmation = 'none' | 'authorization' | 'strong_confirmation';
-export type AssistantPluginResource = 'repo-state' | 'workspace' | 'remote' | 'git-refs';
+export type AssistantPluginResource = 'repo-state' | 'workspace' | 'remote' | 'git-refs' | 'provider-state';
 
 export interface AssistantPluginPermissionScope {
   scope: string;

package/src/runtime/projections/materialized-view.ts

@@ -22,7 +22,6 @@ import {
   type ProjectionRefreshOwner,
 } from './invalidation';
 import { readRepositoryGitStatusSample } from './git-status-sampler';
-import { listCampaigns } from '../workflow/campaigns/store';
 import { listAssistantPluginManifests } from '../plugins/store';
 import type { ProjectionObservation, ProjectionSourceReconciliation } from '../health';
 import { RUNTIME_HEALTH_THRESHOLDS } from '../health/evaluator';
@@ -60,12 +59,6 @@ export interface RepositoryRuntimeProjection {
     degraded: number;
     error: number;
   };
-  campaigns?: {
-    active: number;
-    waitingForSupervisor: number;
-    pendingReviews: number;
-    readyForHumanAcceptance: number;
-  };
 }
 
 interface DirtyProjectionReadCacheEntry {
@@ -112,12 +105,6 @@ function emptyProjection(repoId: string, reason?: string): RepositoryRuntimeProj
       degraded: 0,
       error: 0,
     },
-    campaigns: {
-      active: 0,
-      waitingForSupervisor: 0,
-      pendingReviews: 0,
-      readyForHumanAcceptance: 0,
-    },
   };
 }
 
@@ -191,7 +178,7 @@ function projectionWithExecutionIndexOverlay(
 }
 
 function dirtyReasonImpliesActiveRisk(reason: string | undefined): boolean {
-  return Boolean(reason && /^(job:|leases-|campaign:|schedule:|worker:|process:|cleanup:)/.test(reason));
+  return Boolean(reason && /^(job:|leases-|schedule:|worker:|process:|cleanup:)/.test(reason));
 }
 
 function buildRepositoryProjection(
@@ -210,8 +197,6 @@ function buildRepositoryProjection(
   // Terminal attention records remain in history for diagnosis and audit, but only
   // active/unresolved records should influence "current readiness" decisions.
   const currentAttentionJobs = attentionJobs.filter((job) => !job.finishedAt || activeJobIds.has(job.jobId));
-  const campaigns = listCampaigns(controllerHome, repoId, 1_000);
-  const reviewableCampaigns = campaigns.filter((campaign) => ['active', 'waiting_for_supervisor'].includes(campaign.status));
   const repository = listRepositories(controllerHome).find((entry) => entry.repoId === repoId);
   const plugins = repository ? listAssistantPluginManifests(controllerHome, repository, {
     preferStored: true,
@@ -251,12 +236,6 @@ function buildRepositoryProjection(
       degraded: plugins.filter((plugin) => plugin.health.state === 'degraded').length,
       error: plugins.filter((plugin) => plugin.health.state === 'error').length,
     },
-    campaigns: {
-      active: campaigns.filter((campaign) => campaign.status === 'active').length,
-      waitingForSupervisor: campaigns.filter((campaign) => campaign.status === 'waiting_for_supervisor').length,
-      pendingReviews: reviewableCampaigns.reduce((count, campaign) => count + campaign.checkpoints.filter((checkpoint) => checkpoint.status === 'open').length, 0),
-      readyForHumanAcceptance: campaigns.filter((campaign) => campaign.status === 'ready_for_human_acceptance').length,
-    },
   };
   projection.metadata = {
     ...projection.metadata!,
@@ -270,7 +249,6 @@ function buildRepositoryProjection(
       currentAttention: projection.currentAttention,
       attention: projection.attention,
       plugins: projection.plugins,
-      campaigns: projection.campaigns,
     })).digest('hex'),
   };
   return projection;

package/src/runtime/recovery/maintenance-executor.ts

@@ -19,6 +19,7 @@ import {
   type RuntimeStorageRepairApplyResult,
   type RuntimeStorageRepairPreview,
 } from './local-jobs-repair';
+import { gcTerminalProcesses, type ProcessGcResult } from '../execution/process-runtime/gc';
 
 export type RuntimeMaintenanceActionId =
   | 'local_jobs_reconcile'
@@ -118,6 +119,8 @@ export interface RuntimeMaintenanceApplyResult extends Omit<RuntimeMaintenanceSt
   actionId: RuntimeMaintenanceActionId;
   applied: Array<RuntimeMaintenanceCandidate & { applied: boolean; result?: string; error?: string }>;
   runtimeStorageRepairApply?: RuntimeStorageRepairApplyResult;
+  /** Existing bounded terminal-process retention, run only during explicit full maintenance. */
+  processGc?: ProcessGcResult;
   projection?: unknown;
 }
 
@@ -801,6 +804,11 @@ export function applyRuntimeMaintenance(
       return { ...candidate, applied: false, error: error instanceof Error ? error.message : String(error) };
     }
   });
+  // Reuse the existing Process GC within the explicit full-maintenance cadence.
+  // No scheduler, per-tool-call cleanup, or database compaction is introduced.
+  const processGc = options.actionId === 'full_maintenance_pass'
+    ? gcTerminalProcesses({ controllerHome, repoId: repository.repoId })
+    : undefined;
 
   if (options.actionId === 'runtime_storage_finalize_relocation' || options.actionId === 'full_maintenance_pass' || applied.some((candidate) => candidate.applied) || runtimeStorageRepairApply) {
     rebuildActiveIndex(repository.canonicalRoot);
@@ -817,6 +825,7 @@ export function applyRuntimeMaintenance(
     runtimeStorageError: after.runtimeStorageError ?? storage.error,
     applied,
     runtimeStorageRepairApply,
+    processGc,
     projection,
   };
 }

package/src/runtime/resources/ownership.ts

@@ -1,7 +1,6 @@
 export type ResourceOwnerKind =
   | 'execution_job'
   | 'agent_run'
-  | 'campaign'
   | 'work_contract'
   | 'edit_session'
   | 'controller_generation'

package/src/runtime/root/gateway-adapter.ts

@@ -8,6 +8,7 @@ export interface RuntimeGatewayServerOptions {
   runtimeInstanceId: string;
   runtimeSourceRoot: string;
   sessionId?: string;
+  controllerType?: 'chatgpt' | 'codex' | 'claude' | 'grok';
 }
 
 /**
@@ -28,6 +29,7 @@ export function createRuntimeGatewayServer(
     profile: 'controller',
     principalId,
     sessionId: options.sessionId,
+    controllerType: options.controllerType,
     controllerInstanceId: options.runtimeInstanceId,
     runtimeSourceRoot: options.runtimeSourceRoot,
   });

package/src/runtime/root/mcp-transport.ts

@@ -17,12 +17,14 @@ export interface RuntimeMcpTransportHandle {
   close(): Promise<void>;
 }
 
+export type ForwardedControllerType = 'chatgpt' | 'codex' | 'claude' | 'grok';
+
 export interface StartRuntimeMcpTransportOptions {
   host: string;
   port: number;
   authToken: string;
   readiness: () => RuntimeReadiness;
-  createServer: (principalId: string, sessionId?: string) => Server;
+  createServer: (principalId: string, sessionId?: string, controllerType?: ForwardedControllerType) => Server;
   onFatal?: (error: Error) => void;
 }
 
@@ -99,8 +101,14 @@ export async function startRuntimeMcpTransport(
         const forwardedSessionId = typeof req.headers['x-forge-forwarded-session-id'] === 'string'
           ? req.headers['x-forge-forwarded-session-id'].trim().slice(0, 512)
           : '';
+        const forwardedControllerTypeRaw = typeof req.headers['x-forge-forwarded-controller-type'] === 'string'
+          ? req.headers['x-forge-forwarded-controller-type'].trim().toLowerCase()
+          : '';
+        const forwardedControllerType = ['chatgpt', 'codex', 'claude', 'grok'].includes(forwardedControllerTypeRaw)
+          ? forwardedControllerTypeRaw as ForwardedControllerType
+          : undefined;
         const principal = forwardedPrincipalId || principalId(options.authToken);
-        const server = options.createServer(principal, forwardedSessionId || undefined);
+        const server = options.createServer(principal, forwardedSessionId || undefined, forwardedControllerType);
         transport = new StreamableHTTPServerTransport({
           sessionIdGenerator: () => randomUUID(),
           onsessioninitialized: (createdSessionId) => {

package/src/runtime/root/package-runtime-release.ts

@@ -0,0 +1,161 @@
+import { createHash, randomUUID } from 'crypto';
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from 'fs';
+import { dirname, join, relative, resolve } from 'path';
+import { ensureControllerHome } from '../../cli/repositories/controller-home';
+import { CONTROL_PLANE_SCHEMA_VERSION } from '../control-plane/persistence/sqlite-store';
+import { packageRuntimeSourceRoot } from '../control-plane/runtime-generation';
+import { FORGE_VERSION } from '../../version';
+import { publishRuntimeRelease, type RuntimeReleaseAuthority } from './release-store';
+import type { RuntimeReleaseManifest } from './types';
+
+export interface PackageRuntimeFileRecord {
+  path: string;
+  sha256: string;
+  bytes: number;
+}
+
+export interface PackageRuntimeRelease {
+  releaseId: string;
+  releaseRoot: string;
+  packageRoot: string;
+  packageVersion: string;
+  packageFingerprint: string;
+  artifactIdentity: string;
+  entrypointPath: string;
+  manifestPath: string;
+  indexPath: string;
+  fileCount: number;
+  authority: RuntimeReleaseAuthority;
+}
+
+const PACKAGE_RUNTIME_ROOTS = ['src', 'bin', 'assets', 'scripts'] as const;
+const PACKAGE_RUNTIME_FILES = ['package.json'] as const;
+
+function sha256(value: Buffer | string): string {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function atomicWrite(path: string, content: string, mode = 0o600): void {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
+  writeFileSync(temporary, content, { encoding: 'utf8', mode });
+  renameSync(temporary, path);
+}
+
+function walkRegularFiles(root: string, current: string, output: string[]): void {
+  if (!existsSync(current)) return;
+  const stat = lstatSync(current);
+  if (stat.isSymbolicLink()) return;
+  if (stat.isFile()) {
+    output.push(relative(root, current).split('\\').join('/'));
+    return;
+  }
+  if (!stat.isDirectory()) return;
+  for (const entry of readdirSync(current).sort()) walkRegularFiles(root, join(current, entry), output);
+}
+
+export function packageRuntimeFileIndex(packageRoot = packageRuntimeSourceRoot()): PackageRuntimeFileRecord[] {
+  const root = resolve(packageRoot);
+  const paths: string[] = [];
+  for (const directory of PACKAGE_RUNTIME_ROOTS) walkRegularFiles(root, join(root, directory), paths);
+  for (const file of PACKAGE_RUNTIME_FILES) walkRegularFiles(root, join(root, file), paths);
+  const unique = [...new Set(paths)].sort();
+  if (!unique.includes('package.json') || !unique.some((path) => path === 'bin/forge-runtime.mjs')) {
+    throw new Error(`PACKAGE_RUNTIME_SURFACE_INCOMPLETE: ${root}`);
+  }
+  return unique.map((path) => {
+    const bytes = readFileSync(join(root, path));
+    return { path, sha256: sha256(bytes), bytes: bytes.length };
+  });
+}
+
+export function packageRuntimeFingerprint(records: PackageRuntimeFileRecord[]): string {
+  const hash = createHash('sha256');
+  for (const record of records) hash.update(record.path).update('\0').update(record.sha256).update('\0').update(String(record.bytes)).update('\n');
+  return hash.digest('hex');
+}
+
+function packageVersion(root: string): string {
+  try {
+    const value = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as { name?: unknown; version?: unknown };
+    if (value.name !== '@moretea-labs/forge') throw new Error('package name mismatch');
+    if (typeof value.version !== 'string' || !value.version.trim()) throw new Error('package version missing');
+    return value.version.trim();
+  } catch (error) {
+    throw new Error(`PACKAGE_RUNTIME_IDENTITY_INVALID: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+function launcherSource(input: { packageRoot: string; indexPath: string; indexSha256: string }): string {
+  return `#!/usr/bin/env node\n`
+    + `import { createHash } from 'node:crypto';\n`
+    + `import { existsSync, readFileSync } from 'node:fs';\n`
+    + `import { join } from 'node:path';\n`
+    + `import { spawn } from 'node:child_process';\n`
+    + `const packageRoot=${JSON.stringify(input.packageRoot)};\n`
+    + `const indexPath=${JSON.stringify(input.indexPath)};\n`
+    + `const expectedIndex=${JSON.stringify(input.indexSha256)};\n`
+    + `const digest=(v)=>createHash('sha256').update(v).digest('hex');\n`
+    + `let raw; try { raw=readFileSync(indexPath); } catch (error) { console.error('FORGE_PACKAGE_RUNTIME_INDEX_MISSING: '+error.message); process.exit(78); }\n`
+    + `if(digest(raw)!==expectedIndex){console.error('FORGE_PACKAGE_RUNTIME_INDEX_CHANGED');process.exit(78);}\n`
+    + `let records; try { records=JSON.parse(raw.toString('utf8')).files; } catch { console.error('FORGE_PACKAGE_RUNTIME_INDEX_INVALID'); process.exit(78); }\n`
+    + `for(const record of records){const path=join(packageRoot,record.path);if(!existsSync(path)||digest(readFileSync(path))!==record.sha256){console.error('FORGE_PACKAGE_RUNTIME_SOURCE_CHANGED: '+record.path);process.exit(78);}}\n`
+    + `const runtime=join(packageRoot,'bin','forge-runtime.mjs');\n`
+    + `const child=spawn(process.execPath,[runtime,...process.argv.slice(2)],{stdio:'inherit',env:{...process.env,FORGE_FORCE_NODE:'1'}});\n`
+    + `for(const signal of ['SIGINT','SIGTERM','SIGHUP']){try{process.on(signal,()=>child.kill(signal));}catch{}}\n`
+    + `child.on('error',(error)=>{console.error('FORGE_PACKAGE_RUNTIME_LAUNCH_FAILED: '+error.message);process.exit(1);});\n`
+    + `child.on('exit',(code)=>process.exit(code??1));\n`;
+}
+
+export function materializePackageRuntimeRelease(input: {
+  controllerHome?: string;
+  packageRoot?: string;
+  operationId?: string;
+} = {}): PackageRuntimeRelease {
+  const controllerHome = ensureControllerHome(input.controllerHome);
+  const packageRoot = resolve(input.packageRoot ?? packageRuntimeSourceRoot());
+  const version = packageVersion(packageRoot);
+  const records = packageRuntimeFileIndex(packageRoot);
+  const fingerprint = packageRuntimeFingerprint(records);
+  const safeVersion = version.replace(/[^A-Za-z0-9._-]+/g, '-');
+  const releaseId = `package-${safeVersion}-${fingerprint.slice(0, 16)}`;
+  const releaseRoot = join(controllerHome, 'runtime', 'releases', releaseId);
+  const indexPath = join(releaseRoot, 'package-files.json');
+  const indexJson = `${JSON.stringify({ schemaVersion: 1, package: '@moretea-labs/forge', version, fingerprint, files: records }, null, 2)}\n`;
+  atomicWrite(indexPath, indexJson);
+  const entrypointPath = join(releaseRoot, 'forge-runtime');
+  const launcher = launcherSource({ packageRoot, indexPath, indexSha256: sha256(Buffer.from(indexJson)) });
+  atomicWrite(entrypointPath, launcher, 0o700);
+  chmodSync(entrypointPath, 0o700);
+  const artifactIdentity = `sha256:${sha256(Buffer.from(launcher))}`;
+  const manifest: RuntimeReleaseManifest = {
+    schemaVersion: 1,
+    releaseId,
+    artifactIdentity,
+    entrypoint: 'forge-runtime',
+    arguments: [],
+    configurationSchemaVersion: 1,
+    controllerHome,
+    databaseSchemaCompatibility: { minimum: CONTROL_PLANE_SCHEMA_VERSION, maximum: CONTROL_PLANE_SCHEMA_VERSION },
+    workerProtocolVersion: 1,
+    releaseRevision: `package:${version}:${fingerprint}`,
+    cleanWorkspace: true,
+    createdAt: new Date().toISOString(),
+  };
+  const manifestPath = join(releaseRoot, 'manifest.json');
+  atomicWrite(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+  const authority = publishRuntimeRelease(controllerHome, manifestPath, input.operationId ?? `package-runtime-${FORGE_VERSION}-${Date.now()}`);
+  return {
+    releaseId,
+    releaseRoot,
+    packageRoot,
+    packageVersion: version,
+    packageFingerprint: fingerprint,
+    artifactIdentity,
+    entrypointPath,
+    manifestPath,
+    indexPath,
+    fileCount: records.length,
+    authority,
+  };
+}