@moretea-labs/forge 1.5.0-rc.1

package/src/runtime/control-plane/runtime-generation.ts

@@ -0,0 +1,509 @@
+import { randomUUID } from 'crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { spawnSync } from 'child_process';
+import { ensureControllerHome, resolveControllerHome } from '../../cli/repositories/controller-home';
+import { repositoryIdentity } from '../../cli/controller/runtime-config';
+import { stableCheckoutId } from '../../cli/repositories/identity';
+import { readJsonFile, writeJsonAtomic } from '../shared/json-files';
+import { resolveManagedRuntimeSourceIdentity } from '../release/identity';
+
+/** Explicit override for the Controller Runtime Source root (not an execution repository). */
+export const CONTROLLER_RUNTIME_SOURCE_ROOT_ENV = 'FORGE_CONTROLLER_RUNTIME_SOURCE_ROOT';
+/** Optional concise Forge source-root override. */
+export const CONTROLLER_RUNTIME_SOURCE_ROOT_ENV_ALIAS = 'FORGE_SOURCE_ROOT';
+
+export interface RuntimeSourceIdentity {
+  repoId: string;
+  checkoutId: string;
+  repoRoot: string;
+  canonicalRoot: string;
+  branch: string | null;
+  commit?: string;
+  /** Exact immutable release identity when the runtime executes from a staged release. */
+  releaseRevision?: string;
+  defaultBranch: string;
+  defaultBranchCommit?: string;
+  dirty: boolean;
+  observedAt: string;
+}
+
+export interface RuntimeGenerationRecord {
+  schemaVersion: 1;
+  generation: string;
+  revision: number;
+  controllerHome: string;
+  source: RuntimeSourceIdentity;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export type RuntimeSourceDriftCode =
+  | 'RUNTIME_SOURCE_OK'
+  | 'RUNTIME_SOURCE_SNAPSHOT_MISSING'
+  | 'RUNTIME_SOURCE_CURRENT_UNAVAILABLE'
+  | 'RUNTIME_SOURCE_SNAPSHOT_STALE';
+
+export interface RuntimeSourceDrift {
+  restartRequired: boolean;
+  reasons: string[];
+  code: RuntimeSourceDriftCode;
+}
+
+export type RuntimeSourceResolveReason =
+  | 'explicit'
+  | 'env'
+  | 'package-root'
+  | 'process-cwd'
+  | 'unavailable';
+
+export interface ResolvedControllerRuntimeSourceRoot {
+  root?: string;
+  reason: RuntimeSourceResolveReason;
+  detail?: string;
+}
+
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+function gitText(root: string, args: string[]): string | undefined {
+  const result = spawnSync('git', ['-C', root, ...args], {
+    encoding: 'utf-8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: 10_000,
+  });
+  return result.status === 0 && result.stdout.trim()
+    ? result.stdout.trim()
+    : undefined;
+}
+
+function gitOk(root: string, args: string[]): boolean {
+  const result = spawnSync('git', ['-C', root, ...args], {
+    stdio: 'ignore',
+    timeout: 10_000,
+  });
+  return result.status === 0;
+}
+
+interface ImmutableRuntimeReleaseIdentity {
+  sourceCommit: string;
+  releaseRevision: string;
+  cleanWorkspace: boolean;
+}
+
+function ownGitCheckoutRoot(root: string): string | undefined {
+  const topLevel = gitText(root, ['rev-parse', '--show-toplevel']);
+  if (!topLevel) return undefined;
+  try {
+    return realpathSync(topLevel);
+  } catch {
+    return resolve(topLevel);
+  }
+}
+
+function readImmutableRuntimeReleaseIdentity(root: string): ImmutableRuntimeReleaseIdentity | undefined {
+  const manifestPath = join(root, 'manifest.json');
+  if (!existsSync(manifestPath)) return undefined;
+  let manifest: Record<string, unknown>;
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as Record<string, unknown>;
+  } catch {
+    throw new Error(`RUNTIME_RELEASE_MANIFEST_INVALID: ${manifestPath}`);
+  }
+  const sourceCommit = typeof manifest.sourceCommit === 'string' ? manifest.sourceCommit.trim() : '';
+  const releaseRevision = typeof manifest.releaseRevision === 'string' ? manifest.releaseRevision.trim() : '';
+  if (!sourceCommit || !releaseRevision || typeof manifest.cleanWorkspace !== 'boolean') {
+    throw new Error(`RUNTIME_RELEASE_MANIFEST_INCOMPLETE: ${manifestPath}`);
+  }
+  return {
+    sourceCommit,
+    releaseRevision,
+    cleanWorkspace: manifest.cleanWorkspace,
+  };
+}
+
+function detectDefaultBranch(root: string): string {
+  const originHead = gitText(root, ['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD']);
+  if (originHead?.startsWith('origin/')) return originHead.slice('origin/'.length);
+  if (gitOk(root, ['show-ref', '--verify', '--quiet', 'refs/heads/main'])) return 'main';
+  if (gitOk(root, ['show-ref', '--verify', '--quiet', 'refs/heads/master'])) return 'master';
+  return gitText(root, ['branch', '--show-current']) ?? 'main';
+}
+
+function runtimeSourceStatusPaths(root: string): string[] {
+  const paths = [
+    'src',
+    'package.json',
+    'bun.lock',
+    'bun.lockb',
+    'bunfig.toml',
+  ].filter((entry) => existsSync(join(root, entry)));
+  try {
+    for (const entry of readdirSync(root)) {
+      if (/^tsconfig(?:\..+)?\.json$/.test(entry) && existsSync(join(root, entry))) paths.push(entry);
+    }
+  } catch (_error) {
+    return paths.length > 0 ? [...new Set(paths)] : ['.'];
+  }
+  return paths.length > 0 ? [...new Set(paths)] : ['.'];
+}
+
+function runtimeSourceDirty(root: string): boolean {
+  return Boolean(gitText(root, ['status', '--porcelain=v1', '--untracked-files=all', '--', ...runtimeSourceStatusPaths(root)]));
+}
+
+/**
+ * Package/install root that owns Controller runtime code.
+ * Derived from this module's location so ambient process.cwd() cannot redefine it.
+ */
+export function packageRuntimeSourceRoot(): string {
+  return resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+}
+
+function readPackageName(root: string): string | undefined {
+  try {
+    const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as { name?: string };
+    return typeof pkg.name === 'string' ? pkg.name : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * True when `root` is a Controller runtime package checkout or install tree.
+ * Does not hardcode absolute paths or require a specific clone name.
+ */
+export function looksLikeControllerRuntimePackage(root: string): boolean {
+  if (!root || !existsSync(root)) return false;
+  const name = readPackageName(root);
+  if (name === '@moretea-labs/forge') return true;
+  // Source checkout / worktree without install: canonical Runtime entry + package markers.
+  return existsSync(join(root, 'src', 'runtime', 'root', 'entry.ts'))
+    && existsSync(join(root, 'package.json'));
+}
+
+/**
+ * Unique Controller Runtime Source root resolver.
+ *
+ * Authority order:
+ * 1. explicit canonical Runtime root
+ * 2. FORGE_CONTROLLER_RUNTIME_SOURCE_ROOT / FORGE_SOURCE_ROOT
+ * 3. package root derived from this module (source checkout, global install, worktree)
+ * 4. process.cwd() only when it itself looks like the controller package
+ *
+ * Execution repository roots must never be passed here for drift evaluation.
+ */
+export function resolveControllerRuntimeSourceRoot(options: {
+  explicitRoot?: string;
+  env?: NodeJS.ProcessEnv;
+  cwd?: string;
+} = {}): ResolvedControllerRuntimeSourceRoot {
+  const env = options.env ?? process.env;
+  const explicit = options.explicitRoot?.trim();
+  if (explicit) {
+    return { root: resolve(explicit), reason: 'explicit' };
+  }
+
+  const fromEnv = env[CONTROLLER_RUNTIME_SOURCE_ROOT_ENV]?.trim()
+    || env[CONTROLLER_RUNTIME_SOURCE_ROOT_ENV_ALIAS]?.trim();
+  if (fromEnv) {
+    return { root: resolve(fromEnv), reason: 'env' };
+  }
+
+  const packageRoot = packageRuntimeSourceRoot();
+  if (looksLikeControllerRuntimePackage(packageRoot)) {
+    return { root: packageRoot, reason: 'package-root' };
+  }
+
+  const cwd = resolve(options.cwd ?? process.cwd());
+  if (looksLikeControllerRuntimePackage(cwd)) {
+    return {
+      root: cwd,
+      reason: 'process-cwd',
+      detail: 'ambient cwd matches controller runtime package markers',
+    };
+  }
+
+  return {
+    reason: 'unavailable',
+    detail: `Unable to resolve controller runtime source root (packageRoot=${packageRoot}, cwd=${cwd})`,
+  };
+}
+
+export function runtimeGenerationPath(controllerHome: string): string {
+  return join(resolveControllerHome(controllerHome), 'system', 'runtime-generation.json');
+}
+
+/**
+ * Status/readiness storms re-resolve the Controller Runtime Source repeatedly.
+ * Cache only the authority path (not every explicit collectRuntimeSourceIdentity
+ * call) so tests and rotate/start can still observe immediate dirty/commit changes.
+ */
+const RUNTIME_SOURCE_IDENTITY_CACHE_TTL_MS = 2_500;
+const runtimeSourceIdentityCache = new Map<string, { at: number; value: RuntimeSourceIdentity }>();
+
+export function clearRuntimeSourceIdentityCacheForTest(): void {
+  runtimeSourceIdentityCache.clear();
+}
+
+export function collectRuntimeSourceIdentity(repoRoot: string): RuntimeSourceIdentity {
+  // Prefer Runtime-injected immutable release binding before any Git walk-up.
+  // Managed children must not follow ambient parent HEAD when the active release is frozen.
+  const bound = resolveManagedRuntimeSourceIdentity({ runtimeRoot: repoRoot });
+  if (bound) return bound;
+
+  const canonicalRoot = realpathSync(repoRoot);
+  const repoId = `repo_${repositoryIdentity(canonicalRoot)}`;
+  const checkoutId = stableCheckoutId(repoId, canonicalRoot);
+  const gitRoot = ownGitCheckoutRoot(canonicalRoot);
+  const ownsGitCheckout = gitRoot === canonicalRoot;
+
+  if (!ownsGitCheckout) {
+    const release = readImmutableRuntimeReleaseIdentity(canonicalRoot);
+    if (release) {
+      return {
+        repoId,
+        checkoutId,
+        repoRoot,
+        canonicalRoot,
+        branch: null,
+        commit: release.sourceCommit,
+        releaseRevision: release.releaseRevision,
+        defaultBranch: 'main',
+        defaultBranchCommit: release.sourceCommit,
+        dirty: !release.cleanWorkspace,
+        observedAt: nowIso(),
+      };
+    }
+    // An install tree without its own Git checkout must remain unversioned. Never
+    // inherit branch/HEAD/dirty state from an ambient parent repository.
+    return {
+      repoId,
+      checkoutId,
+      repoRoot,
+      canonicalRoot,
+      branch: null,
+      defaultBranch: 'main',
+      dirty: false,
+      observedAt: nowIso(),
+    };
+  }
+
+  const defaultBranch = detectDefaultBranch(canonicalRoot);
+  return {
+    repoId,
+    checkoutId,
+    repoRoot,
+    canonicalRoot,
+    branch: gitText(canonicalRoot, ['branch', '--show-current']) ?? null,
+    commit: gitText(canonicalRoot, ['rev-parse', '--verify', 'HEAD']),
+    defaultBranch,
+    defaultBranchCommit: gitText(canonicalRoot, ['rev-parse', '--verify', defaultBranch]),
+    dirty: runtimeSourceDirty(canonicalRoot),
+    observedAt: nowIso(),
+  };
+}
+
+function collectRuntimeSourceIdentityCached(repoRoot: string): RuntimeSourceIdentity {
+  const now = Date.now();
+  const cacheKey = resolve(repoRoot);
+  const cached = runtimeSourceIdentityCache.get(cacheKey);
+  if (cached && now - cached.at <= RUNTIME_SOURCE_IDENTITY_CACHE_TTL_MS) {
+    return cached.value;
+  }
+  const value = collectRuntimeSourceIdentity(repoRoot);
+  runtimeSourceIdentityCache.set(cacheKey, { at: now, value });
+  if (runtimeSourceIdentityCache.size > 32) {
+    const oldest = runtimeSourceIdentityCache.keys().next().value;
+    if (oldest !== undefined) runtimeSourceIdentityCache.delete(oldest);
+  }
+  return value;
+}
+
+/**
+ * Safe identity collection: missing/unreadable roots return undefined instead of throwing.
+ */
+export function tryCollectRuntimeSourceIdentity(repoRoot: string | undefined): RuntimeSourceIdentity | undefined {
+  if (!repoRoot?.trim()) return undefined;
+  try {
+    if (!existsSync(repoRoot)) return undefined;
+    return collectRuntimeSourceIdentity(repoRoot);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Current Controller Runtime Source identity from the unique authority resolver.
+ * Never accepts an execution repository root.
+ */
+export function collectCurrentControllerRuntimeSourceIdentity(options: {
+  explicitRoot?: string;
+  env?: NodeJS.ProcessEnv;
+  cwd?: string;
+} = {}): RuntimeSourceIdentity | undefined {
+  const resolved = resolveControllerRuntimeSourceRoot(options);
+  if (!resolved.root?.trim()) return undefined;
+  try {
+    if (!existsSync(resolved.root)) return undefined;
+    return collectRuntimeSourceIdentityCached(resolved.root);
+  } catch {
+    return undefined;
+  }
+}
+
+export function readRuntimeGeneration(controllerHome: string): RuntimeGenerationRecord | undefined {
+  const path = runtimeGenerationPath(controllerHome);
+  if (!existsSync(path)) return undefined;
+  return readJsonFile<RuntimeGenerationRecord>(path, undefined);
+}
+
+export function rotateRuntimeGeneration(
+  controllerHome: string,
+  source: RuntimeSourceIdentity,
+): RuntimeGenerationRecord {
+  const path = runtimeGenerationPath(controllerHome);
+  mkdirSync(join(ensureControllerHome(controllerHome), 'system'), { recursive: true });
+  const current = readRuntimeGeneration(controllerHome);
+  const timestamp = nowIso();
+  const next: RuntimeGenerationRecord = {
+    schemaVersion: 1,
+    generation: `runtime-${Date.now()}-${randomUUID().slice(0, 8)}`,
+    revision: Math.max(0, current?.revision ?? 0) + 1,
+    controllerHome: ensureControllerHome(controllerHome),
+    source,
+    createdAt: timestamp,
+    updatedAt: timestamp,
+  };
+  writeJsonAtomic(path, next);
+  return next;
+}
+
+export function ensureRuntimeGeneration(
+  controllerHome: string,
+  source: RuntimeSourceIdentity,
+): RuntimeGenerationRecord {
+  return readRuntimeGeneration(controllerHome) ?? rotateRuntimeGeneration(controllerHome, source);
+}
+
+/**
+ * Compare startup Runtime Source snapshot against the current Controller Runtime Source.
+ * Missing active snapshot is fail-closed (restart required), never silent pass.
+ */
+export function evaluateRuntimeSourceDrift(
+  active: RuntimeSourceIdentity | undefined,
+  current: RuntimeSourceIdentity | undefined,
+): RuntimeSourceDrift {
+  if (!active) {
+    return {
+      restartRequired: true,
+      reasons: ['Controller runtime source snapshot is missing'],
+      code: 'RUNTIME_SOURCE_SNAPSHOT_MISSING',
+    };
+  }
+  if (!current) {
+    return {
+      restartRequired: true,
+      reasons: ['Controller runtime source is unavailable for drift evaluation'],
+      code: 'RUNTIME_SOURCE_CURRENT_UNAVAILABLE',
+    };
+  }
+
+  const reasons: string[] = [];
+  if (active.canonicalRoot !== current.canonicalRoot) {
+    reasons.push(`runtime source root moved from ${active.canonicalRoot} to ${current.canonicalRoot}`);
+  }
+  if (active.checkoutId !== current.checkoutId) {
+    reasons.push(`runtime checkout changed from ${active.checkoutId} to ${current.checkoutId}`);
+  }
+  if ((active.branch ?? '') !== (current.branch ?? '')) {
+    reasons.push(`runtime branch changed from ${active.branch ?? 'detached'} to ${current.branch ?? 'detached'}`);
+  }
+  // The resolved runtime source checkout is the authority for the running
+  // controller. A clean, explicitly selected stable branch is valid even
+  // when the local default branch points at a different (possibly unrelated)
+  // development line. Comparing against defaultBranchCommit here made every
+  // clean feature/stable branch look stale until it was merged into main.
+  if (active.commit && current.commit && active.commit !== current.commit) {
+    reasons.push(`runtime commit changed from ${active.commit} to ${current.commit}`);
+  }
+  if ((active.releaseRevision ?? '') !== (current.releaseRevision ?? '')) {
+    reasons.push(`runtime release changed from ${active.releaseRevision ?? 'source-checkout'} to ${current.releaseRevision ?? 'source-checkout'}`);
+  }
+  if (active.dirty) {
+    reasons.push('runtime was started from a dirty source checkout');
+  } else if (current.dirty) {
+    reasons.push('runtime source files changed after startup');
+  }
+
+  return {
+    restartRequired: reasons.length > 0,
+    reasons,
+    code: reasons.length > 0 ? 'RUNTIME_SOURCE_SNAPSHOT_STALE' : 'RUNTIME_SOURCE_OK',
+  };
+}
+
+/**
+ * Shared drift evaluation used by MCP, CLI, Local Bridge, and restart verification.
+ * Always resolves "current" from the Controller Runtime Source authority — never from
+ * the selected execution repository.
+ */
+export function evaluateActiveRuntimeSourceDrift(
+  active: RuntimeSourceIdentity | undefined,
+  options: {
+    explicitRoot?: string;
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    /** Test-only override of the current runtime source root (not an execution repo). */
+    currentRuntimeRoot?: string;
+  } = {},
+): RuntimeSourceDrift & { current?: RuntimeSourceIdentity } {
+  const current = options.currentRuntimeRoot
+    ? (() => {
+      try {
+        if (!options.currentRuntimeRoot || !existsSync(options.currentRuntimeRoot)) return undefined;
+        // Explicit roots are test/diagnostic fixtures and must observe edits
+        // immediately; the authority-root cache is only for status storms.
+        return collectRuntimeSourceIdentity(options.currentRuntimeRoot);
+      } catch {
+        return undefined;
+      }
+    })()
+    : active?.releaseRevision && active.canonicalRoot && existsSync(active.canonicalRoot)
+      ? (() => {
+        try {
+          // An immutable release cannot drift to the long-lived MCP Gateway's
+          // source checkout. Re-read the frozen release itself so missing or
+          // corrupted release identity still fails closed, while source-mode
+          // runtimes continue to compare against their live source authority.
+          return collectRuntimeSourceIdentityCached(active.canonicalRoot);
+        } catch {
+          return undefined;
+        }
+      })()
+      : collectCurrentControllerRuntimeSourceIdentity(options);
+  return {
+    current,
+    ...evaluateRuntimeSourceDrift(active, current),
+  };
+}
+
+export function formatRuntimeSourceDriftMessage(drift: RuntimeSourceDrift): string {
+  if (drift.code === 'RUNTIME_SOURCE_SNAPSHOT_MISSING' || (
+    drift.restartRequired
+    && drift.reasons.length === 1
+    && drift.reasons[0] === 'Controller runtime source snapshot is missing'
+  )) {
+    return 'Controller runtime source snapshot is missing. Restart the controller from an authoritative runtime source before mutating work.';
+  }
+  if (drift.code === 'RUNTIME_SOURCE_CURRENT_UNAVAILABLE') {
+    return 'Controller runtime source is unavailable for drift evaluation. Restore the authoritative runtime source and restart the controller before mutating work.';
+  }
+  if (drift.restartRequired) {
+    const reasons = drift.reasons.length > 0 ? drift.reasons.join('; ') : 'unknown runtime source drift';
+    return `Controller runtime source changed after startup: ${reasons}. Restore the authoritative runtime source and restart the controller before mutating work.`;
+  }
+  return '';
+}

package/src/runtime/control-plane/runtime-pid-ownership.ts

@@ -0,0 +1,11 @@
+import { existsSync, readFileSync } from 'fs';
+
+export function forgeRuntimeOwnsPidFile(pidPath: string, pid = process.pid): boolean {
+  if (!existsSync(pidPath)) return false;
+  try {
+    const recordedPid = Number.parseInt(readFileSync(pidPath, 'utf8').trim(), 10);
+    return Number.isInteger(recordedPid) && recordedPid === pid;
+  } catch {
+    return false;
+  }
+}

package/src/runtime/control-plane/runtime-status-client.ts

@@ -0,0 +1,90 @@
+import { resolveControllerHome } from '../../cli/repositories/controller-home';
+import { readSchedulerHealthSnapshot } from './global-scheduler/scheduler';
+import type { ControllerStartupRecoveryResult } from './startup-recovery';
+import type { RuntimeSourceIdentity } from './runtime-generation';
+import { readRuntimeOwner } from '../root/ownership';
+import { observeRuntimeStatus } from '../root/status';
+import { readRuntimeGeneration } from './runtime-generation';
+
+export type ForgeRuntimeShutdownReason =
+  | 'SIGINT'
+  | 'SIGTERM'
+  | 'max_lifetime'
+  | 'scheduler_error'
+  | 'lifecycle_complete'
+  | 'process_missing';
+
+/** Read-only observation over the Canonical Forge Runtime. */
+export interface ForgeRuntimeStatus {
+  schemaVersion: 1;
+  status: 'starting' | 'ready' | 'failed' | 'stopped' | 'unavailable';
+  pid?: number;
+  startedAt?: string;
+  stoppedAt?: string;
+  shutdownReason?: ForgeRuntimeShutdownReason;
+  error?: string;
+  gatewaySeparated?: boolean;
+  workerIsolation?: boolean;
+  degraded?: boolean;
+  recovery?: ControllerStartupRecoveryResult;
+  generation?: string;
+  source?: RuntimeSourceIdentity;
+  restartRequired?: boolean;
+  restartReasons?: string[];
+  instanceId?: string;
+}
+
+export const DEFAULT_SCHEDULER_HEARTBEAT_TIMEOUT_MS = 60_000;
+const MIN_SCHEDULER_HEARTBEAT_TIMEOUT_MS = 5_000;
+
+export function schedulerHeartbeatSnapshotHealthy(
+  scheduler: ReturnType<typeof readSchedulerHealthSnapshot>,
+  nowMs = Date.now(),
+): boolean {
+  if (!scheduler.loopStartedAt) return false;
+  const heartbeat = scheduler.lastHeartbeatAt ?? scheduler.lastTickAt;
+  if (!heartbeat) return false;
+  const heartbeatAt = Date.parse(heartbeat);
+  const configuredTimeout = Number(scheduler.heartbeatTimeoutMs);
+  const timeoutMs = Number.isFinite(configuredTimeout) && configuredTimeout > 0
+    ? Math.max(MIN_SCHEDULER_HEARTBEAT_TIMEOUT_MS, configuredTimeout)
+    : DEFAULT_SCHEDULER_HEARTBEAT_TIMEOUT_MS;
+  return Number.isFinite(heartbeatAt) && nowMs - heartbeatAt <= timeoutMs;
+}
+
+export function resolveForgeRuntimeStatusHome(controllerHome: string): string {
+  return resolveControllerHome(controllerHome);
+}
+
+export function readForgeRuntimeStatus(controllerHome: string): ForgeRuntimeStatus {
+  const home = resolveForgeRuntimeStatusHome(controllerHome);
+  const observation = observeRuntimeStatus(home);
+  const owner = readRuntimeOwner(home);
+  const snapshot = observation.snapshot;
+  const generation = readRuntimeGeneration(home);
+  const status: ForgeRuntimeStatus['status'] = observation.ready
+    ? 'ready'
+    : observation.running
+      ? 'starting'
+      : snapshot
+        ? 'stopped'
+        : 'unavailable';
+  const pid = snapshot?.pid ?? owner?.pid;
+  const startedAt = snapshot?.startedAt ?? owner?.acquiredAt;
+  const instanceId = snapshot?.runtimeInstanceId ?? owner?.runtimeInstanceId;
+  return {
+    schemaVersion: 1,
+    status,
+    ...(pid ? { pid } : {}),
+    ...(startedAt ? { startedAt } : {}),
+    ...(!observation.running && snapshot ? { stoppedAt: snapshot.updatedAt, shutdownReason: 'process_missing' as const } : {}),
+    ...(!observation.ready && observation.reasonCodes.length > 0 ? { error: observation.reasonCodes.join(',') } : {}),
+    gatewaySeparated: false,
+    workerIsolation: true,
+    ...(generation ? { generation: generation.generation, source: generation.source } : {}),
+    degraded: observation.running && !observation.ready,
+    restartRequired: false,
+    restartReasons: [],
+    ...(instanceId ? { instanceId } : {}),
+  };
+}