@moretea-labs/forge 1.5.0-rc.1

package/src/runtime/shared/local-bridge-surface.ts

@@ -0,0 +1,231 @@
+/**
+ * Authoritative Local Bridge / Local Controller surface resolution.
+ *
+ * The caller-provided Controller Home is authoritative. Surface resolution
+ * never selects a runtime slot or follows a separate traffic authority.
+ */
+
+import {
+  loadMcpLocalConfig,
+  loadMcpRuntimeState,
+  loadMcpServiceLocalConfig,
+  loadMcpServiceRuntimeState,
+  type McpLocalConfig,
+  type McpRuntimeState,
+} from '../../cli/mcp/auth';
+import { inferLocalControllerProcess } from '../diagnostics/performance';
+import type { LocalBridgeMode } from '../health/evaluator';
+
+export type LocalBridgeSurfaceMode = LocalBridgeMode;
+
+export interface LocalBridgeSurface {
+  mode: LocalBridgeSurfaceMode;
+  /** True when the product intends a Local Controller surface for this repo/runtime. */
+  enabled: boolean;
+  /** True when readiness must fail closed without a healthy surface. */
+  requiredForReadiness: boolean;
+  /** Configured or observed endpoint URL (may be undefined when disabled / not applicable). */
+  endpoint?: string;
+  endpointConfigured: boolean;
+  /** Expected surface kind for operators and probes. */
+  expectedSurface: 'local-controller' | 'none';
+  processRunning?: boolean;
+  pid?: number;
+  generation?: string;
+  error?: string;
+  /** Where endpoint/mode were resolved from. */
+  source: 'service-runtime' | 'repo-runtime' | 'service-config' | 'repo-config' | 'process-scan' | 'none';
+  ownerKind: 'mcp-keepalive' | 'controller-service' | 'external' | 'unknown' | 'none';
+}
+
+function normalizeEndpoint(host: string, port: number): string {
+  const safeHost = host.trim() || '127.0.0.1';
+  const displayHost = safeHost === '0.0.0.0' || safeHost === '::' ? '127.0.0.1' : safeHost;
+  return `http://${displayHost}:${port}/`;
+}
+
+function modeFromRuntime(runtime: McpRuntimeState | null | undefined): LocalBridgeSurfaceMode | undefined {
+  const mode = runtime?.localController?.mode;
+  if (mode === 'standalone' || mode === 'embedded' || mode === 'remote' || mode === 'disabled' || mode === 'unknown') {
+    return mode;
+  }
+  return undefined;
+}
+
+function resolveAuthoritativeMcpHomes(controllerHome: string | undefined): string[] {
+  return controllerHome ? [controllerHome] : [];
+}
+
+function firstServiceRuntime(homes: string[]): {
+  runtime: McpRuntimeState | null;
+  home?: string;
+} {
+  // Do not pass legacyRepoRoot while scanning homes: an empty slot home would
+  // otherwise inherit repo-local runtime and shadow a later authoritative home.
+  for (const home of homes) {
+    const runtime = loadMcpServiceRuntimeState(home);
+    if (runtime?.localController) return { runtime, home };
+  }
+  for (const home of homes) {
+    const runtime = loadMcpServiceRuntimeState(home);
+    if (runtime) return { runtime, home };
+  }
+  return { runtime: null };
+}
+
+function firstServiceConfig(homes: string[]): {
+  config: McpLocalConfig | null;
+  home?: string;
+} {
+  // Same rule as runtime: slot homes without mcp/* must not fall back to
+  // repo-local disabled/legacy config before later homes are considered.
+  for (const home of homes) {
+    const config = loadMcpServiceLocalConfig(home);
+    if (config?.localController) return { config, home };
+  }
+  for (const home of homes) {
+    const config = loadMcpServiceLocalConfig(home);
+    if (config) return { config, home };
+  }
+  return { config: null };
+}
+
+/**
+ * Resolve Local Bridge capability from Controller Home, then repo-local fallbacks.
+ * Controller Home selection belongs to the canonical Runtime owner, not this resolver.
+ */
+export function resolveLocalBridgeSurface(input: {
+  controllerHome?: string;
+  repoRoot: string;
+  /** Optional process scan; when omitted, scan only if runtime state is missing. */
+  allowProcessScan?: boolean;
+}): LocalBridgeSurface {
+  const allowProcessScan = input.allowProcessScan !== false;
+  const homes = resolveAuthoritativeMcpHomes(input.controllerHome);
+
+  const { runtime: serviceRuntime } = firstServiceRuntime(homes);
+  const repoRuntime = loadMcpRuntimeState(input.repoRoot);
+  const runtime = serviceRuntime?.localController ? serviceRuntime : (repoRuntime ?? serviceRuntime);
+  const runtimeSource: LocalBridgeSurface['source'] = serviceRuntime?.localController
+    ? 'service-runtime'
+    : repoRuntime?.localController
+      ? 'repo-runtime'
+      : 'none';
+
+  const { config: serviceConfig } = firstServiceConfig(homes);
+  const repoConfig = loadMcpLocalConfig(input.repoRoot);
+  const config = serviceConfig?.localController ? serviceConfig : (repoConfig ?? serviceConfig);
+  const configSource: LocalBridgeSurface['source'] = serviceConfig?.localController
+    ? 'service-config'
+    : repoConfig?.localController
+      ? 'repo-config'
+      : 'none';
+
+  const configuredEnabled = config?.localController?.enabled;
+  const configuredMode = config?.localController?.mode;
+  const configuredHost = config?.localController?.host ?? '127.0.0.1';
+  const configuredPort = config?.localController?.port;
+  const configuredEndpoint = typeof configuredPort === 'number' && Number.isFinite(configuredPort)
+    ? normalizeEndpoint(configuredHost, configuredPort)
+    : undefined;
+
+  const runtimeLc = runtime?.localController;
+  if (runtimeLc) {
+    const mode = modeFromRuntime(runtime) ?? configuredMode ?? 'unknown';
+    const enabled = mode !== 'disabled' && configuredEnabled !== false;
+    // Prefer live runtime endpoint; fall back to matching config from the same authority chain.
+    const endpoint = runtimeLc.endpoint?.trim() || configuredEndpoint;
+    const ownerKind = mode === 'embedded'
+      ? 'mcp-keepalive'
+      : mode === 'remote'
+        ? 'external'
+        : mode === 'standalone'
+          ? 'controller-service'
+          : 'unknown';
+    return {
+      mode: enabled ? mode : 'disabled',
+      enabled,
+      // Embedded UI is operationally useful but not a hard readiness gate unless
+      // standalone mode is configured and required by deployment.
+      requiredForReadiness: enabled && mode === 'standalone',
+      endpoint,
+      endpointConfigured: Boolean(endpoint),
+      expectedSurface: enabled ? 'local-controller' : 'none',
+      processRunning: runtimeLc.running,
+      pid: runtimeLc.pid,
+      generation: runtimeLc.generation ?? runtime?.generation,
+      error: runtimeLc.error,
+      source: runtimeSource === 'none' ? 'service-runtime' : runtimeSource,
+      ownerKind,
+    };
+  }
+
+  if (configuredEnabled === false || configuredMode === 'disabled') {
+    return {
+      mode: 'disabled',
+      enabled: false,
+      requiredForReadiness: false,
+      endpoint: configuredEndpoint,
+      endpointConfigured: Boolean(configuredEndpoint),
+      expectedSurface: 'none',
+      source: configSource === 'none' ? 'service-config' : configSource,
+      ownerKind: 'none',
+    };
+  }
+
+  if (configuredEndpoint) {
+    const mode = configuredMode ?? 'standalone';
+    return {
+      mode,
+      enabled: true,
+      requiredForReadiness: mode === 'standalone',
+      endpoint: configuredEndpoint,
+      endpointConfigured: true,
+      expectedSurface: 'local-controller',
+      source: configSource === 'none' ? 'service-config' : configSource,
+      ownerKind: mode === 'embedded' ? 'mcp-keepalive' : mode === 'standalone' ? 'controller-service' : 'unknown',
+    };
+  }
+
+  if (allowProcessScan) {
+    const inferred = inferLocalControllerProcess(input.repoRoot);
+    if (inferred?.running) {
+      return {
+        mode: 'standalone',
+        enabled: true,
+        requiredForReadiness: false,
+        endpoint: inferred.endpoint,
+        endpointConfigured: Boolean(inferred.endpoint),
+        expectedSurface: 'local-controller',
+        processRunning: true,
+        pid: inferred.pid,
+        source: 'process-scan',
+        ownerKind: 'controller-service',
+      };
+    }
+  }
+
+  // No configured surface: do not invent legacy 8766 as an expected endpoint.
+  return {
+    mode: 'unknown',
+    enabled: false,
+    requiredForReadiness: false,
+    endpointConfigured: false,
+    expectedSurface: 'none',
+    source: 'none',
+    ownerKind: 'none',
+  };
+}
+
+export function summarizeRecentJobs(jobs: Array<{ status: string }>): {
+  activeJobCount: number;
+  recentJobSummary: Record<string, number>;
+} {
+  const recentJobSummary: Record<string, number> = {};
+  let activeJobCount = 0;
+  for (const job of jobs) {
+    recentJobSummary[job.status] = (recentJobSummary[job.status] ?? 0) + 1;
+    if (['approved', 'running', 'dispatched'].includes(job.status)) activeJobCount += 1;
+  }
+  return { activeJobCount, recentJobSummary };
+}

package/src/runtime/shared/managed-env.ts

@@ -0,0 +1,154 @@
+import { existsSync, readFileSync } from 'fs';
+import { delimiter, resolve } from 'path';
+
+const ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const SUPPORTED_PREFIXES = ['FORGE_', 'GOOGLE_'] as const;
+const SUPPORTED_NAMES = new Set([
+  'OPENAI_WORKSPACE_AGENT_ACCESS_TOKEN',
+  'CHATGPT_WORKSPACE_AGENT_ACCESS_TOKEN',
+]);
+
+export interface ManagedEnvBootstrapOptions {
+  cwd?: string;
+  controllerHome?: string;
+  env?: NodeJS.ProcessEnv;
+  repoRoot?: string;
+}
+
+function hasForgeMarkers(path: string): boolean {
+  return existsSync(resolve(path, '.git'))
+    || existsSync(resolve(path, '.forge'))
+    || existsSync(resolve(path, '_ops'));
+}
+
+function inferRepoRoot(start: string): string | undefined {
+  let current = resolve(start);
+  while (true) {
+    if (hasForgeMarkers(current)) return current;
+    const parent = resolve(current, '..');
+    if (parent === current) return undefined;
+    current = parent;
+  }
+}
+
+function isSupportedName(name: string): boolean {
+  return SUPPORTED_NAMES.has(name) || SUPPORTED_PREFIXES.some((prefix) => name.startsWith(prefix));
+}
+
+function decodeDoubleQuoted(value: string): string {
+  let decoded = '';
+  for (let index = 0; index < value.length; index += 1) {
+    const current = value[index];
+    if (current !== '\\' || index === value.length - 1) {
+      decoded += current;
+      continue;
+    }
+    index += 1;
+    const escaped = value[index];
+    switch (escaped) {
+      case 'n':
+        decoded += '\n';
+        break;
+      case 'r':
+        decoded += '\r';
+        break;
+      case 't':
+        decoded += '\t';
+        break;
+      case '\\':
+        decoded += '\\';
+        break;
+      case '"':
+        decoded += '"';
+        break;
+      default:
+        decoded += escaped;
+        break;
+    }
+  }
+  return decoded;
+}
+
+function parseEnvLine(line: string): [string, string] | null {
+  const trimmed = line.trim();
+  if (!trimmed || trimmed.startsWith('#')) return null;
+  const normalized = trimmed.startsWith('export ') ? trimmed.slice('export '.length).trimStart() : trimmed;
+  const separator = normalized.indexOf('=');
+  if (separator <= 0) return null;
+  const key = normalized.slice(0, separator).trim();
+  if (!ENV_KEY_PATTERN.test(key) || !isSupportedName(key)) return null;
+  let value = normalized.slice(separator + 1).trim();
+  if (value.startsWith('"') && value.endsWith('"') && value.length >= 2) {
+    return [key, decodeDoubleQuoted(value.slice(1, -1))];
+  }
+  if (value.startsWith("'") && value.endsWith("'") && value.length >= 2) {
+    return [key, value.slice(1, -1)];
+  }
+  const inlineComment = value.search(/\s#/);
+  if (inlineComment >= 0) value = value.slice(0, inlineComment).trimEnd();
+  return [key, value];
+}
+
+function parseEnvFile(path: string): Map<string, string> {
+  const entries = new Map<string, string>();
+  if (!existsSync(path)) return entries;
+  const source = readFileSync(path, 'utf8').replace(/^\uFEFF/, '');
+  for (const line of source.split(/\r?\n/)) {
+    const parsed = parseEnvLine(line);
+    if (!parsed) continue;
+    entries.set(parsed[0], parsed[1]);
+  }
+  return entries;
+}
+
+function pushCandidate(files: string[], seen: Set<string>, path: string | undefined): void {
+  const normalized = path?.trim();
+  if (!normalized) return;
+  const resolved = resolve(normalized);
+  if (seen.has(resolved)) return;
+  seen.add(resolved);
+  files.push(resolved);
+}
+
+function candidateFiles(options: ManagedEnvBootstrapOptions): string[] {
+  const env = options.env ?? process.env;
+  const files: string[] = [];
+  const seen = new Set<string>();
+  const single = env.FORGE_ENV_FILE?.trim();
+  if (single) pushCandidate(files, seen, single);
+  const multiple = env.FORGE_ENV_FILES?.split(delimiter).map((value) => value.trim()).filter(Boolean) ?? [];
+  for (const entry of multiple) pushCandidate(files, seen, entry);
+
+  const repoRoot = options.repoRoot?.trim() || inferRepoRoot(options.cwd ?? process.cwd());
+  if (repoRoot) {
+    pushCandidate(files, seen, resolve(repoRoot, '_ops', 'secrets', 'forge.env'));
+    pushCandidate(files, seen, resolve(repoRoot, '_ops', 'secrets', 'controller.env'));
+    pushCandidate(files, seen, resolve(repoRoot, '_ops', 'env', '.env.local'));
+  }
+  const controllerHome = options.controllerHome?.trim();
+  if (controllerHome) {
+    pushCandidate(files, seen, resolve(controllerHome, '..', 'secrets', 'forge.env'));
+    pushCandidate(files, seen, resolve(controllerHome, '..', 'secrets', 'controller.env'));
+    pushCandidate(files, seen, resolve(controllerHome, '..', 'env', '.env.local'));
+  }
+  return files;
+}
+
+export function bootstrapManagedRuntimeEnv(options: ManagedEnvBootstrapOptions = {}): {
+  loadedFiles: string[];
+  appliedKeys: string[];
+} {
+  const env = options.env ?? process.env;
+  const loadedFiles: string[] = [];
+  const appliedKeys: string[] = [];
+  for (const file of candidateFiles(options)) {
+    if (!existsSync(file)) continue;
+    loadedFiles.push(file);
+    for (const [key, value] of parseEnvFile(file)) {
+      if (env[key]?.trim()) continue;
+      env[key] = value;
+      appliedKeys.push(key);
+    }
+  }
+  return { loadedFiles, appliedKeys };
+}

package/src/runtime/shared/node-ts-loader.mjs

@@ -0,0 +1,50 @@
+import { access, readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import ts from 'typescript';
+
+export async function resolve(specifier, context, nextResolve) {
+  try {
+    return await nextResolve(specifier, context);
+  } catch (error) {
+    if ((specifier.startsWith('./') || specifier.startsWith('../')) && !/\.[a-z0-9]+$/i.test(specifier)) {
+      for (const suffix of ['.ts', '/index.ts']) {
+        const url = new URL(specifier + suffix, context.parentURL);
+        try {
+          await access(fileURLToPath(url));
+          return { url: url.href, shortCircuit: true };
+        } catch {}
+      }
+    }
+    throw error;
+  }
+}
+
+export async function load(url, context, nextLoad) {
+  if (url.startsWith('file:') && url.endsWith('.ts')) {
+    const source = await readFile(fileURLToPath(url), 'utf8');
+    const result = ts.transpileModule(source, {
+      fileName: fileURLToPath(url),
+      reportDiagnostics: true,
+      compilerOptions: {
+        target: ts.ScriptTarget.ES2022,
+        module: ts.ModuleKind.ESNext,
+        moduleResolution: ts.ModuleResolutionKind.Bundler,
+        isolatedModules: true,
+        sourceMap: true,
+        inlineSources: true,
+        verbatimModuleSyntax: false,
+      },
+    });
+    const errors = (result.diagnostics ?? []).filter((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error);
+    if (errors.length > 0) {
+      const formatted = ts.formatDiagnostics(errors, {
+        getCanonicalFileName: (fileName) => fileName,
+        getCurrentDirectory: () => process.cwd(),
+        getNewLine: () => '\n',
+      });
+      throw new Error(`TypeScript transpilation failed for ${url}:\n${formatted}`);
+    }
+    return { format: 'module', source: result.outputText, shortCircuit: true };
+  }
+  return nextLoad(url, context);
+}

package/src/runtime/shared/process-environment.ts

@@ -0,0 +1,97 @@
+import { existsSync } from 'fs';
+import { homedir } from 'os';
+import { basename, delimiter, isAbsolute, join } from 'path';
+
+/**
+ * Environment boundary for repository-owned child processes.
+ *
+ * Controller/Supervisor authority, topology, and process identity belong to
+ * the hosting runtime and must never be inherited by repository commands,
+ * checks, or their children.
+ */
+
+const RUNTIME_PRIVATE_ENV_PREFIXES = [
+  'FORGE_CONTROLLER_',
+  'FORGE_DAEMON_',
+  'FORGE_PROCESS_RUNNER',
+  'FORGE_RUNTIME_',
+  'FORGE_SUPERVISOR_',
+  'FORGE_WRITER_',
+] as const;
+
+const RUNTIME_PRIVATE_ENV_KEYS = new Set([
+  'FORGE_MCP_INSTANCE_ID',
+  'FORGE_MCP_PUBLIC_ORIGIN',
+  'FORGE_STABLE_SUPERVISOR',
+]);
+
+function appendExecutableDirectory(pathEntries: string[], candidate: string | undefined): void {
+  if (!candidate || !isAbsolute(candidate) || pathEntries.includes(candidate)) return;
+  pathEntries.push(candidate);
+}
+
+function validBunExecutable(candidate: string | undefined): string | undefined {
+  const value = candidate?.trim();
+  if (!value) return undefined;
+  const executable = basename(value).toLowerCase();
+  if (executable !== 'bun' && executable !== 'bun.exe') return undefined;
+  if (isAbsolute(value) && !existsSync(value)) return undefined;
+  return value;
+}
+
+export function resolveBunExecutable(
+  execPath: string = process.execPath,
+  env: NodeJS.ProcessEnv = process.env,
+  accountHome: string = homedir(),
+): string {
+  const configured = validBunExecutable(env.FORGE_BUN_EXECUTABLE);
+  if (configured) return configured;
+  const executable = basename(execPath).toLowerCase();
+  if (executable === 'bun' || executable === 'bun.exe') return execPath;
+
+  const binary = process.platform === 'win32' ? 'bun.exe' : 'bun';
+  const bunInstall = env.BUN_INSTALL?.trim();
+  const home = env.HOME?.trim() || env.USERPROFILE?.trim() || accountHome.trim();
+  const candidates = [
+    bunInstall ? join(bunInstall, 'bin', binary) : undefined,
+    home ? join(home, '.bun', 'bin', binary) : undefined,
+    process.platform === 'darwin' ? join('/opt/homebrew/bin', binary) : undefined,
+    process.platform !== 'win32' ? join('/usr/local/bin', binary) : undefined,
+  ];
+  for (const candidate of candidates) {
+    if (candidate && existsSync(candidate)) return candidate;
+  }
+  return binary;
+}
+
+export function repositoryChildProcessEnvironment(
+  env: NodeJS.ProcessEnv = process.env,
+): NodeJS.ProcessEnv {
+  const sanitized = { ...env };
+  for (const key of Object.keys(sanitized)) {
+    if (
+      RUNTIME_PRIVATE_ENV_KEYS.has(key)
+      || RUNTIME_PRIVATE_ENV_PREFIXES.some((prefix) => key.startsWith(prefix))
+    ) {
+      delete sanitized[key];
+    }
+  }
+
+  const pathEntries = (sanitized.PATH ?? '').split(delimiter).filter(Boolean);
+  const bunInstall = sanitized.BUN_INSTALL?.trim();
+  const home = sanitized.HOME?.trim() || sanitized.USERPROFILE?.trim();
+  const voltaHome = sanitized.VOLTA_HOME?.trim();
+  const nvmBin = sanitized.NVM_BIN?.trim();
+  const pnpmHome = sanitized.PNPM_HOME?.trim();
+  appendExecutableDirectory(pathEntries, bunInstall ? join(bunInstall, 'bin') : undefined);
+  appendExecutableDirectory(pathEntries, home ? join(home, '.bun', 'bin') : undefined);
+  appendExecutableDirectory(pathEntries, nvmBin);
+  appendExecutableDirectory(pathEntries, voltaHome ? join(voltaHome, 'bin') : undefined);
+  appendExecutableDirectory(pathEntries, pnpmHome);
+  appendExecutableDirectory(pathEntries, home ? join(home, '.local', 'bin') : undefined);
+  if (process.platform === 'darwin') appendExecutableDirectory(pathEntries, '/opt/homebrew/bin');
+  if (process.platform !== 'win32') appendExecutableDirectory(pathEntries, '/usr/local/bin');
+  sanitized.PATH = pathEntries.join(delimiter);
+
+  return sanitized;
+}

package/src/runtime/shared/process-identity.ts

@@ -0,0 +1,72 @@
+import { createHash } from 'crypto';
+import { runProcess } from '../../effects/process-runner';
+import { isProcessAlive } from './process-tree';
+
+export interface ProcessIdentityProbe {
+  isAlive(pid: number): boolean;
+  command(pid: number): string | undefined;
+  startTime(pid: number): string | undefined;
+  inspect?(pid: number): { command?: string; startTime?: string };
+  listProcesses?(): Array<{ pid: number; command: string }>;
+}
+
+export interface ExpectedProcessIdentity {
+  pid: number;
+  processStartTime: string;
+  executableFingerprint: string;
+}
+
+function inspectProcess(pid: number): { command?: string; startTime?: string } {
+  const result = runProcess('ps', ['-o', 'lstart=', '-o', 'command=', '-p', String(pid)], { timeoutMs: 1_000, maxOutputBytes: 32 * 1024 });
+  if (!result.ok) return {};
+  const match = /^\s*(\S+\s+\S+\s+\S+\s+\S+\s+\S+)\s+([\s\S]+?)\s*$/.exec(result.stdout);
+  return match ? { startTime: match[1], command: match[2] } : {};
+}
+
+const defaultProbe: ProcessIdentityProbe = {
+  isAlive: (pid) => isProcessAlive(pid),
+  inspect: inspectProcess,
+  command: (pid) => {
+    const result = runProcess('ps', ['-o', 'command=', '-p', String(pid)], { timeoutMs: 1_000, maxOutputBytes: 32 * 1024 });
+    return result.ok ? result.stdout.trim() || undefined : undefined;
+  },
+  startTime: (pid) => {
+    const result = runProcess('ps', ['-o', 'lstart=', '-p', String(pid)], { timeoutMs: 1_000, maxOutputBytes: 4 * 1024 });
+    return result.ok ? result.stdout.trim() || undefined : undefined;
+  },
+  listProcesses: () => {
+    const result = runProcess('ps', ['-axo', 'pid=,command='], { timeoutMs: 2_000, maxOutputBytes: 1024 * 1024 });
+    if (!result.ok) return [];
+    return result.stdout
+      .split('\n')
+      .map((line) => /^\s*(\d+)\s+(.+?)\s*$/.exec(line))
+      .filter((match): match is RegExpExecArray => Boolean(match))
+      .map((match) => ({ pid: Number.parseInt(match[1], 10), command: match[2] }))
+      .filter((entry) => Number.isInteger(entry.pid) && entry.pid > 0 && entry.command.length > 0);
+  },
+};
+
+export function executableFingerprint(command: string): string {
+  return createHash('sha256').update(command).digest('hex').slice(0, 24);
+}
+
+export function processIdentityMatches(
+  expected: ExpectedProcessIdentity | undefined,
+  actualPid: number | undefined,
+  probe: ProcessIdentityProbe = defaultProbe,
+): { matches: boolean; reason?: string } {
+  if (!expected || !actualPid) return { matches: false, reason: 'identity_missing' };
+  if (expected.pid !== actualPid) return { matches: false, reason: 'pid_changed' };
+  if (!probe.isAlive(actualPid)) return { matches: false, reason: 'process_dead' };
+  const inspected = probe.inspect?.(actualPid);
+  const command = inspected?.command ?? probe.command(actualPid);
+  const startTime = inspected?.startTime ?? probe.startTime(actualPid);
+  if (!command || !startTime) return { matches: false, reason: 'identity_probe_unavailable' };
+  if (startTime !== expected.processStartTime) return { matches: false, reason: 'process_start_time_changed' };
+  if (executableFingerprint(command) !== expected.executableFingerprint) {
+    return { matches: false, reason: 'executable_fingerprint_changed' };
+  }
+  return { matches: true };
+}
+
+export { defaultProbe as defaultProcessIdentityProbe };