@moretea-labs/forge 1.7.2 → 1.8.1

package/src/runtime/standalone-recovery/mcp-server.ts

@@ -0,0 +1,79 @@
+import type { IncomingMessage, ServerResponse } from 'http';
+import { createMcpHandler, Server, type Tool } from '@modelcontextprotocol/server';
+import { toNodeHandler } from '@modelcontextprotocol/node';
+import { FORGE_VERSION } from '../../version';
+
+export interface RecoveryMcpRequestContext {
+  remoteAddress: string;
+}
+
+export interface RecoveryMcpServerOptions {
+  tools: readonly Tool[];
+  dispatchTool(name: string, args: Record<string, unknown>, context: RecoveryMcpRequestContext): Promise<unknown>;
+}
+
+/**
+ * Standalone Recovery owns durable recovery/release authority, never MCP
+ * transport-session authority. Both MCP 2026-07-28 and the bounded 2025-era
+ * compatibility protocol are served statelessly so a Gateway process
+ * replacement cannot invalidate the Recovery control path.
+ */
+export class RecoveryMcpServer {
+  constructor(private readonly options: RecoveryMcpServerOptions) {}
+
+  async close(): Promise<void> {
+    // Stateless handlers retain no cross-request transport resources.
+  }
+
+  async handle(request: IncomingMessage, response: ServerResponse, body?: unknown): Promise<void> {
+    if (request.method !== 'POST') {
+      response.statusCode = 405;
+      response.setHeader('allow', 'POST');
+      response.end();
+      return;
+    }
+
+    const context: RecoveryMcpRequestContext = {
+      remoteAddress: request.socket.remoteAddress ?? 'unknown',
+    };
+    const handler = createMcpHandler(async () => this.createServer(context), {
+      legacy: 'stateless',
+      responseMode: 'auto',
+    });
+    try {
+      await toNodeHandler(handler)(request, response, body);
+    } finally {
+      await handler.close();
+    }
+  }
+
+  private createServer(context: RecoveryMcpRequestContext): Server {
+    const server = new Server(
+      { name: 'forge-standalone-recovery', version: FORGE_VERSION },
+      { capabilities: { tools: {} } },
+    );
+    server.setRequestHandler('tools/list', async () => ({ tools: [...this.options.tools] }));
+    server.setRequestHandler('tools/call', async (request) => {
+      const name = request.params.name;
+      const args = request.params.arguments && typeof request.params.arguments === 'object' && !Array.isArray(request.params.arguments)
+        ? request.params.arguments as Record<string, unknown>
+        : {};
+      try {
+        const payload = await this.options.dispatchTool(name, args, context);
+        const structuredContent = payload && typeof payload === 'object' && !Array.isArray(payload)
+          ? payload as Record<string, unknown>
+          : { value: payload };
+        return {
+          content: [{ type: 'text' as const, text: JSON.stringify(payload) }],
+          structuredContent,
+        };
+      } catch (error) {
+        return {
+          isError: true,
+          content: [{ type: 'text' as const, text: error instanceof Error ? error.message : 'Recovery request rejected' }],
+        };
+      }
+    });
+    return server;
+  }
+}

package/src/runtime/standalone-recovery/mutation-identity-contract.ts

@@ -0,0 +1,21 @@
+/** Canonical external mutation identity contract for Standalone Recovery.
+ *
+ * Both the runtime fencing implementation and the MCP tool schema derive from
+ * this single authority. Keep target-identity field names and validation shape
+ * here so an upgraded Recovery cannot require fields that its own connector
+ * schema forgot to expose.
+ */
+export const RECOVERY_MUTATION_IDENTITY_CONTRACT = {
+  expected_host: { type: 'string', minLength: 1, maxLength: 255 },
+  expected_platform: { type: 'string', minLength: 1, maxLength: 64 },
+  expected_controller_home: { type: 'string', minLength: 1, maxLength: 2048 },
+  expected_recovery_release: { type: 'string', minLength: 1, maxLength: 256 },
+  expected_target_runtime: { type: 'string', minLength: 1, maxLength: 1024 },
+} as const;
+
+export const RECOVERY_MUTATION_IDENTITY_FIELDS = Object.freeze(
+  Object.keys(RECOVERY_MUTATION_IDENTITY_CONTRACT),
+) as readonly (keyof typeof RECOVERY_MUTATION_IDENTITY_CONTRACT)[];
+
+export type RecoveryMutationIdentityField = (typeof RECOVERY_MUTATION_IDENTITY_FIELDS)[number];
+export type RecoveryMutationIdentityArguments = Record<RecoveryMutationIdentityField, string>;

package/src/runtime/standalone-recovery/operation-lock.ts

@@ -0,0 +1,160 @@
+import { randomUUID } from 'crypto';
+import { spawnSync } from 'child_process';
+import { closeSync, mkdirSync, openSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import { isProcessAlive } from '../shared/process-tree';
+
+export interface RecoveryOperationLockRecord {
+  schemaVersion?: 1;
+  pid: number;
+  instanceId: string;
+  processStartTime?: string;
+  acquiredAt: string;
+  action?: string;
+  requestId?: string;
+}
+
+export interface RecoveryOperationLockHandle {
+  path: string;
+  record: RecoveryOperationLockRecord;
+  close: () => void;
+}
+
+export type RecoveryOperationLockAttempt =
+  | { acquired: true; handle: RecoveryOperationLockHandle }
+  | { acquired: false; owner: RecoveryOperationLockRecord };
+
+function processStartTime(pid: number): string | undefined {
+  const result = spawnSync('/bin/ps', ['-o', 'lstart=', '-p', String(pid)], {
+    encoding: 'utf8',
+    timeout: 2_000,
+    maxBuffer: 4_096,
+  });
+  if (result.status !== 0 || typeof result.stdout !== 'string') return undefined;
+  return result.stdout.trim() || undefined;
+}
+
+function readRecoveryOperationLockPath(path: string): RecoveryOperationLockRecord | undefined {
+  let raw: string;
+  try {
+    raw = readFileSync(path, 'utf8');
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+    throw error;
+  }
+  try {
+    const parsed = JSON.parse(raw) as RecoveryOperationLockRecord;
+    if (!Number.isInteger(parsed.pid) || parsed.pid <= 0) return undefined;
+    if (typeof parsed.instanceId !== 'string' || !parsed.instanceId.trim()) return undefined;
+    if (typeof parsed.acquiredAt !== 'string' || !parsed.acquiredAt.trim()) return undefined;
+    return parsed;
+  } catch {
+    return undefined;
+  }
+}
+
+export function recoveryOperationLockPath(controllerHome: string): string {
+  const resolved = resolve(controllerHome);
+  let canonical = resolved;
+  try {
+    canonical = realpathSync(resolved);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+  }
+  return join(canonical, 'recovery', 'locks', 'operation.lock');
+}
+
+export function readRecoveryOperationLock(controllerHome: string): RecoveryOperationLockRecord | undefined {
+  return readRecoveryOperationLockPath(recoveryOperationLockPath(controllerHome));
+}
+
+export function recoveryOperationLockOwnerAlive(lock: RecoveryOperationLockRecord): boolean {
+  if (!isProcessAlive(lock.pid)) return false;
+  if (!lock.processStartTime) return true;
+  const observed = processStartTime(lock.pid);
+  return observed === lock.processStartTime;
+}
+
+export function acquireRecoveryOperationLock(input: {
+  controllerHome: string;
+  action: string;
+  requestId?: string;
+  instanceIdPrefix?: string;
+}, dependencies: {
+  writeRecord?: (fd: number, content: string) => void;
+} = {}): RecoveryOperationLockAttempt {
+  const path = recoveryOperationLockPath(input.controllerHome);
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const instanceId = `${input.instanceIdPrefix ?? 'recovery-operation-'}${randomUUID()}`;
+  const requestId = input.requestId?.trim() || `internal:${input.action}:${instanceId}`;
+  const record: RecoveryOperationLockRecord = {
+    schemaVersion: 1,
+    pid: process.pid,
+    instanceId,
+    processStartTime: processStartTime(process.pid),
+    acquiredAt: new Date().toISOString(),
+    action: input.action,
+    requestId,
+  };
+
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    let fd: number | undefined;
+    try {
+      try {
+        fd = openSync(path, 'wx', 0o600);
+        try {
+          (dependencies.writeRecord ?? ((targetFd: number, content: string) => writeFileSync(targetFd, content)))(fd, JSON.stringify(record));
+        } catch (error) {
+          // O_EXCL proved this process created this exact path. A partial or failed
+          // owner-record write must never leave an unreadable lock that poisons
+          // every later Recovery/certification attempt.
+          try { rmSync(path, { force: true }); } finally {
+            try { closeSync(fd); } catch { /* best effort */ }
+            fd = undefined;
+          }
+          throw error;
+        }
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+        const existing = readRecoveryOperationLockPath(path);
+        if (!existing) throw new Error('RECOVERY_OPERATION_LOCK_UNCERTAIN');
+        if (recoveryOperationLockOwnerAlive(existing)) return { acquired: false, owner: existing };
+        const latest = readRecoveryOperationLockPath(path);
+        if (!latest || latest.instanceId !== existing.instanceId) {
+          if (attempt === 1) {
+            if (latest && recoveryOperationLockOwnerAlive(latest)) return { acquired: false, owner: latest };
+            throw new Error('RECOVERY_OPERATION_LOCK_RACE');
+          }
+          continue;
+        }
+        if (recoveryOperationLockOwnerAlive(latest)) return { acquired: false, owner: latest };
+        try { writeFileSync(`${path}.stale-${Date.now()}-${existing.instanceId}`, readFileSync(path)); } catch { /* evidence best effort */ }
+        rmSync(path, { force: true });
+        continue;
+      }
+
+      if (fd === undefined) throw new Error('RECOVERY_OPERATION_LOCK_BUSY');
+      let closed = false;
+      return {
+        acquired: true,
+        handle: {
+          path,
+          record,
+          close: () => {
+            if (closed) return;
+            closed = true;
+            closeSync(fd!);
+            const current = readRecoveryOperationLockPath(path);
+            if (current?.instanceId === instanceId) rmSync(path, { force: true });
+          },
+        },
+      };
+    } catch (error) {
+      if (fd !== undefined) {
+        try { closeSync(fd); } catch { /* best effort */ }
+      }
+      throw error;
+    }
+  }
+  throw new Error('RECOVERY_OPERATION_LOCK_BUSY');
+}

package/src/runtime/standalone-recovery/performance.ts

@@ -0,0 +1,173 @@
+import { spawnSync } from 'node:child_process';
+
+/** Release acceptance evidence, never a readiness/liveness or watchdog input. */
+export interface RuntimePerformanceIdentity {
+  releaseId: string;
+  authorityRevision: number;
+  runtimeInstanceId: string;
+  pid: number;
+  startedAt: string;
+}
+
+export interface RuntimePerformanceEvidence extends RuntimePerformanceIdentity {
+  policy: 'runaway-cpu-v4';
+  measuredFrom: string;
+  measuredUntil: string;
+  warmupMs: number;
+  durationMs: number;
+  sampleCount: number;
+  meanCpuPercent: number;
+  p95CpuPercent: number;
+  /** Windows whose CPU consumption reached the per-window runaway ceiling. */
+  sustainedHighWindowCount: number;
+}
+
+export interface RuntimeCpuReading { cpuMs: number; processStartTime: string }
+
+const PERFORMANCE_WINDOW_MS = 2_500;
+const PERFORMANCE_MAX_WINDOW_MS = 3_750;
+const PERFORMANCE_WARMUP_WINDOWS = 4;
+const PERFORMANCE_SAMPLE_WINDOWS = 20;
+const PERFORMANCE_WARMUP_MS = PERFORMANCE_WINDOW_MS * PERFORMANCE_WARMUP_WINDOWS;
+const PERFORMANCE_DURATION_MS = PERFORMANCE_WINDOW_MS * PERFORMANCE_SAMPLE_WINDOWS;
+
+// Recovery known-good is a runaway safety gate, not the comparative release benchmark.
+// The v4 sampler keeps the same 60-second budget, the same twenty 2.5-second windows
+// and the same 25%/50% ceilings as v2/v3, but decides runaway from *sustained*
+// consumption instead of from nearest-rank p95.
+//
+// Why p95 cannot be the decision rule: the Canonical Runtime performs bounded,
+// scheduled maintenance (the release-fenced periodic cleanup child and the in-process
+// scheduler/recovery passes). Such a pass lasts several seconds and recurs about once
+// per minute, so in any 50-second observation at least two windows necessarily land
+// inside it. nearest-rank p95 is exactly the second-highest window, so a healthy
+// Runtime with an ~11% mean was deterministically rejected (live evidence:
+// mean=12.60% p95=65.05% and mean=11.41% p95=65.13%, both rolled back within minutes
+// of cutover) and every automatic release progression converged on rollback.
+//
+// A watchdog duty must distinguish "unbounded spin" from "bounded periodic work", so
+// v4 rejects a sample only when the process is high for at least half of the observed
+// windows (sustainedHighWindowCount * 2 >= sampleCount) or when the mean exceeds the
+// ceiling. The historical runaway population (mean >= 90.64%, p95 >= 104.72%) fails
+// both tests by a wide margin, while a once-per-minute bounded pass (<= 4 of 20
+// windows) can no longer be mistaken for runaway. p95 stays in the evidence for audit.
+// Relative <=10% regression remains Benchmark/Release Evaluation authority.
+export const RECOVERY_RUNAWAY_MEAN_CPU_PERCENT = 25;
+export const RECOVERY_RUNAWAY_P95_CPU_PERCENT = 50;
+
+/** Dependencies are in-process test seams; no transport accepts evidence or threshold overrides. */
+export interface RuntimePerformanceDependencies {
+  readCpu?: (pid: number) => RuntimeCpuReading;
+  monotonicNow?: () => number;
+  wallNow?: () => number;
+  sleep?: (ms: number) => Promise<void>;
+}
+
+export function readRuntimeCpu(pid: number): RuntimeCpuReading {
+  const result = spawnSync('/bin/ps', ['-p', String(pid), '-o', 'time=', '-o', 'lstart='], {
+    encoding: 'utf8', timeout: 2_000, maxBuffer: 4_096, env: { ...process.env, LC_ALL: 'C' },
+  });
+  const match = result.status === 0
+    ? result.stdout.trim().match(/^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+(?:\.\d+)?)\s+(.+)$/)
+    : undefined;
+  if (!match) throw new Error('RECOVERY_PERFORMANCE_UNKNOWN: process CPU measurement unavailable');
+  const cpuMs = (Number(match[1] ?? 0) * 86400 + Number(match[2] ?? 0) * 3600
+    + Number(match[3]) * 60 + Number(match[4])) * 1000;
+  return { cpuMs, processStartTime: match[5]! };
+}
+
+export function samePerformanceIdentity(a: RuntimePerformanceIdentity, b: RuntimePerformanceIdentity): boolean {
+  return a.releaseId === b.releaseId && a.authorityRevision === b.authorityRevision
+    && a.runtimeInstanceId === b.runtimeInstanceId && a.pid === b.pid && a.startedAt === b.startedAt;
+}
+
+export function assertRuntimePerformanceEvidence(
+  evidence: RuntimePerformanceEvidence,
+  identity: RuntimePerformanceIdentity,
+  now = Date.now(),
+): void {
+  const age = now - Date.parse(evidence.measuredUntil);
+  if (evidence.policy !== 'runaway-cpu-v4' || !samePerformanceIdentity(evidence, identity)
+    || !Number.isFinite(age) || age < 0 || age > 60_000
+    || evidence.warmupMs < PERFORMANCE_WARMUP_MS || evidence.warmupMs > PERFORMANCE_MAX_WINDOW_MS * PERFORMANCE_WARMUP_WINDOWS
+    || evidence.durationMs < PERFORMANCE_DURATION_MS || evidence.durationMs > PERFORMANCE_MAX_WINDOW_MS * PERFORMANCE_SAMPLE_WINDOWS || evidence.sampleCount !== PERFORMANCE_SAMPLE_WINDOWS
+    || !Number.isFinite(evidence.meanCpuPercent) || evidence.meanCpuPercent < 0
+    || !Number.isFinite(evidence.p95CpuPercent) || evidence.p95CpuPercent < 0
+    || !Number.isInteger(evidence.sustainedHighWindowCount)
+    || evidence.sustainedHighWindowCount < 0
+    || evidence.sustainedHighWindowCount > evidence.sampleCount) {
+    throw new Error('RECOVERY_PERFORMANCE_UNKNOWN: incomplete, stale or mismatched performance evidence');
+  }
+  const sustained = evidence.sustainedHighWindowCount * 2 >= evidence.sampleCount;
+  if (evidence.meanCpuPercent > RECOVERY_RUNAWAY_MEAN_CPU_PERCENT || sustained) {
+    throw new Error(`RECOVERY_PERFORMANCE_REJECTED: mean=${evidence.meanCpuPercent.toFixed(2)}% p95=${evidence.p95CpuPercent.toFixed(2)}% sustained=${evidence.sustainedHighWindowCount}/${evidence.sampleCount}`);
+  }
+}
+
+/** Observe 10 seconds of warmup followed by twenty 2.5-second CPU-time delta windows. */
+export async function measureRuntimePerformance(
+  observeIdentity: () => RuntimePerformanceIdentity,
+  dependencies: RuntimePerformanceDependencies = {},
+): Promise<RuntimePerformanceEvidence> {
+  const readCpu = dependencies.readCpu ?? readRuntimeCpu;
+  const monotonicNow = dependencies.monotonicNow ?? (() => performance.now());
+  const wallNow = dependencies.wallNow ?? Date.now;
+  const sleep = dependencies.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const identity = observeIdentity();
+  const initial = readCpu(identity.pid);
+  const observe = () => {
+    if (!samePerformanceIdentity(identity, observeIdentity())) {
+      throw new Error('RECOVERY_PERFORMANCE_UNKNOWN: Runtime or release authority changed');
+    }
+    const cpu = readCpu(identity.pid);
+    if (cpu.processStartTime !== initial.processStartTime || !Number.isFinite(cpu.cpuMs)) {
+      throw new Error('RECOVERY_PERFORMANCE_UNKNOWN: process identity changed');
+    }
+    return cpu;
+  };
+  const warmingAt = monotonicNow();
+  let previousWarmupAt = warmingAt;
+  for (let i = 0; i < PERFORMANCE_WARMUP_WINDOWS; i++) {
+    await sleep(PERFORMANCE_WINDOW_MS);
+    observe();
+    const nextWarmupAt = monotonicNow();
+    const elapsed = nextWarmupAt - previousWarmupAt;
+    if (elapsed < PERFORMANCE_WINDOW_MS || elapsed > PERFORMANCE_MAX_WINDOW_MS) {
+      throw new Error('RECOVERY_PERFORMANCE_UNKNOWN: interrupted CPU warmup window');
+    }
+    previousWarmupAt = nextWarmupAt;
+  }
+  const warmupMs = monotonicNow() - warmingAt;
+  const measuredFrom = new Date(wallNow()).toISOString();
+  let previousCpu = observe().cpuMs;
+  let previousAt = monotonicNow();
+  const startedAt = previousAt;
+  let totalCpuMs = 0;
+  const windows: number[] = [];
+  for (let i = 0; i < PERFORMANCE_SAMPLE_WINDOWS; i++) {
+    await sleep(PERFORMANCE_WINDOW_MS);
+    const nextCpu = observe().cpuMs;
+    const nextAt = monotonicNow();
+    const elapsed = nextAt - previousAt;
+    const cpuDelta = nextCpu - previousCpu;
+    // Suspended/overloaded collectors cannot pass as ordinary sample windows.
+    if (elapsed < PERFORMANCE_WINDOW_MS || elapsed > PERFORMANCE_MAX_WINDOW_MS || cpuDelta < 0) {
+      throw new Error('RECOVERY_PERFORMANCE_UNKNOWN: interrupted CPU observation window');
+    }
+    windows.push(cpuDelta / elapsed * 100);
+    totalCpuMs += cpuDelta;
+    previousCpu = nextCpu;
+    previousAt = nextAt;
+  }
+  const durationMs = previousAt - startedAt;
+  windows.sort((a, b) => a - b);
+  const evidence: RuntimePerformanceEvidence = {
+    ...identity, policy: 'runaway-cpu-v4', measuredFrom, measuredUntil: new Date(wallNow()).toISOString(),
+    warmupMs, durationMs, sampleCount: windows.length,
+    meanCpuPercent: totalCpuMs / durationMs * 100,
+    p95CpuPercent: windows[Math.ceil(windows.length * 0.95) - 1]!,
+    sustainedHighWindowCount: windows.filter((cpuPercent) => cpuPercent >= RECOVERY_RUNAWAY_P95_CPU_PERCENT).length,
+  };
+  assertRuntimePerformanceEvidence(evidence, observeIdentity(), wallNow());
+  return evidence;
+}

package/src/runtime/standalone-recovery/release.ts

@@ -15,8 +15,8 @@ import {
 import { dirname, join, relative, resolve, sep } from 'path';
 import { writeJsonAtomic } from '../shared/json-files';
 
-export const RECOVERY_RELEASE_BINARIES = [
-  'forge-recovery',
+export const RECOVERY_RELEASE_BINARIES = ['forge-recovery'] as const;
+export const RECOVERY_RELEASE_COMPATIBILITY_BINARIES = [
   'forge-recovery-gateway',
   'forge-recovery-watchdog',
 ] as const;
@@ -24,7 +24,8 @@ export const RECOVERY_RELEASE_BINARIES = [
 export const RECOVERY_RELEASE_ROLE_CANARY_ARG = '--forge-release-role-canary';
 
 export type RecoveryReleaseBinary = (typeof RECOVERY_RELEASE_BINARIES)[number];
-export type RecoveryRuntimeRole = 'gateway' | 'watchdog';
+/** daemon is the only current persistent owner; gateway/watchdog remain legacy CLI compatibility roles. */
+export type RecoveryRuntimeRole = 'daemon' | 'gateway' | 'watchdog';
 export interface RecoveryReleaseManifest {
   schemaVersion: 1;
   releaseRevision: string;
@@ -32,6 +33,8 @@ export interface RecoveryReleaseManifest {
   sourceRoot: string;
   cleanWorkspace: boolean;
   builtAt: string;
+  /** Product version derived from the source package and bound by the manifest hash. */
+  productVersion?: string;
   legacy?: boolean;
   artifacts: Record<RecoveryReleaseBinary, { sha256: string }>;
 }
@@ -42,6 +45,7 @@ export interface RecoveryReleaseDescriptor {
   sourceCommit: string;
   sourceRoot: string;
   cleanWorkspace: boolean;
+  productVersion?: string;
   manifestSha256: string;
   artifacts: RecoveryReleaseManifest['artifacts'];
   legacy: boolean;
@@ -81,6 +85,49 @@ export function recoveryRuntimeStatePath(controllerHome: string, role: RecoveryR
   return join(recoveryRoot(controllerHome), 'state', `${role}-runtime.json`);
 }
 
+export function recoveryGatewayDrainMarkerPath(controllerHome: string): string {
+  return join(recoveryRoot(controllerHome), 'state', 'gateway-draining.json');
+}
+
+const RECOVERY_GATEWAY_DRAIN_MARKER_TTL_MS = 5 * 60_000;
+
+export function recoveryGatewayIsDraining(controllerHome: string, now = Date.now()): boolean {
+  const path = recoveryGatewayDrainMarkerPath(controllerHome);
+  if (!existsSync(path)) return false;
+  try {
+    const marker = JSON.parse(readFileSync(path, 'utf8')) as { pid?: unknown; at?: unknown };
+    const pid = Number(marker.pid);
+    const at = typeof marker.at === 'string' ? Date.parse(marker.at) : Number.NaN;
+    if (!Number.isInteger(pid) || pid <= 0 || !Number.isFinite(at) || now - at > RECOVERY_GATEWAY_DRAIN_MARKER_TTL_MS) {
+      rmSync(path, { force: true });
+      return false;
+    }
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code === 'EPERM') return true;
+      rmSync(path, { force: true });
+      return false;
+    }
+  } catch {
+    rmSync(path, { force: true });
+    return false;
+  }
+}
+
+export function setRecoveryGatewayDraining(controllerHome: string, draining: boolean): void {
+  const path = recoveryGatewayDrainMarkerPath(controllerHome);
+  if (!draining) {
+    rmSync(path, { force: true });
+    return;
+  }
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  writeJsonAtomic(path, { schemaVersion: 1, draining: true, pid: process.pid, at: new Date().toISOString() });
+  chmodSync(path, 0o600);
+}
+
 function fileSha256(path: string): string {
   return createHash('sha256').update(readFileSync(path)).digest('hex');
 }
@@ -109,6 +156,7 @@ export function readRecoveryRelease(path: string | undefined): RecoveryReleaseDe
     if (typeof parsed.sourceCommit !== 'string' || !parsed.sourceCommit.trim()) return undefined;
     if (typeof parsed.sourceRoot !== 'string' || !parsed.sourceRoot.trim()) return undefined;
     if (typeof parsed.cleanWorkspace !== 'boolean') return undefined;
+    if (parsed.productVersion !== undefined && (typeof parsed.productVersion !== 'string' || !parsed.productVersion.trim())) return undefined;
     if (!parsed.artifacts || typeof parsed.artifacts !== 'object') return undefined;
     const artifacts = {} as RecoveryReleaseManifest['artifacts'];
     for (const binary of RECOVERY_RELEASE_BINARIES) {
@@ -123,6 +171,7 @@ export function readRecoveryRelease(path: string | undefined): RecoveryReleaseDe
       sourceCommit: parsed.sourceCommit,
       sourceRoot: resolve(parsed.sourceRoot),
       cleanWorkspace: parsed.cleanWorkspace,
+      productVersion: typeof parsed.productVersion === 'string' ? parsed.productVersion.trim() : undefined,
       manifestSha256: createHash('sha256').update(bytes).digest('hex'),
       artifacts,
       legacy: parsed.legacy === true,
@@ -179,11 +228,15 @@ export function publishRecoveryCompatibilityLinks(controllerHome: string): void
   assertRecoveryReleaseContained(controllerHome, current);
   const binRoot = join(recoveryRoot(controllerHome), 'bin');
   mkdirSync(binRoot, { recursive: true, mode: 0o700 });
-  for (const binary of RECOVERY_RELEASE_BINARIES) {
+  const compatibilityTargets = [
+    ...RECOVERY_RELEASE_BINARIES.map((binary) => ({ binary, target: binary })),
+    ...RECOVERY_RELEASE_COMPATIBILITY_BINARIES.map((binary) => ({ binary, target: 'forge-recovery' as const })),
+  ];
+  for (const { binary, target } of compatibilityTargets) {
     const destination = join(binRoot, binary);
     const temporary = `${destination}.${process.pid}.tmp`;
     rmSync(temporary, { force: true });
-    symlinkSync(join('..', 'current', binary), temporary);
+    symlinkSync(join('..', 'current', target), temporary);
     renameSync(temporary, destination);
   }
 }

package/src/runtime/standalone-recovery/service-labels.ts

@@ -1,2 +1,5 @@
-export const RECOVERY_GATEWAY_LABEL = 'com.moretea.forge-recovery-gateway';
-export const RECOVERY_WATCHDOG_LABEL = 'com.moretea.forge-recovery-watchdog';
+export {
+  FORGE_RECOVERY_DAEMON_LABEL as RECOVERY_DAEMON_LABEL,
+  FORGE_RECOVERY_GATEWAY_LABEL as RECOVERY_GATEWAY_LABEL,
+  FORGE_RECOVERY_WATCHDOG_LABEL as RECOVERY_WATCHDOG_LABEL,
+} from '../platform/service-inventory';

package/src/runtime/standalone-recovery/watchdog-heartbeat.ts

@@ -151,10 +151,13 @@ export function evaluateRecoveryWatchdogHealth(input: {
   return { ok: true, detail: 'Recovery Watchdog heartbeat, PID, and immutable release identity are current', pulseAgeMs, heartbeat, runtimeIdentity, currentReleaseRevision: current.releaseRevision };
 }
 
-export function observeRecoveryWatchdogHealth(controllerHome: string): RecoveryWatchdogHealth {
+export function observeRecoveryWatchdogHealth(controllerHome: string, enabled = true): RecoveryWatchdogHealth {
+  if (!enabled) {
+    return { ok: true, detail: 'Recovery Watchdog is disabled by the configured install profile' };
+  }
   return evaluateRecoveryWatchdogHealth({
     heartbeat: readRecoveryWatchdogHeartbeat(controllerHome),
-    runtimeIdentity: readRecoveryRuntimeIdentity(controllerHome, 'watchdog'),
+    runtimeIdentity: readRecoveryRuntimeIdentity(controllerHome, 'daemon'),
     currentRelease: readCurrentRecoveryRelease(controllerHome),
   });
 }

package/src/runtime/watchdog/workflow-watchdog.ts

@@ -3,7 +3,7 @@ import { getLocalBridgeJobEventsSnapshot, listLocalBridgeJobSnapshots } from '..
 import type { RepositoryRecord } from '../../cli/repositories/types';
 import { listExecutionJobs } from '../execution/jobs/store';
 import { collectRuntimePerformanceDiagnostics, type RuntimePerformanceDiagnostics } from '../diagnostics/performance';
-import { listSchedules } from '../workflow/schedules/store';
+import { listSchedules } from '../../../packages/kernel/scheduler/api/index';
 
 const ACTIVE_AGENT_STATUSES = new Set(['queued', 'starting', 'running']);
 

package/src/runtime/workflow/schedules/browser-probe.ts

@@ -82,6 +82,7 @@ async function browserAction(
   occurrenceId: string,
   actionId: string,
   args: Record<string, unknown>,
+  authorizationGrantRefs: readonly string[],
 ): Promise<Record<string, unknown>> {
   return executeBrowserPluginAction({
     controllerHome,
@@ -92,9 +93,16 @@ async function browserAction(
     requestId: `schedule-browser-probe:${occurrenceId}:${actionId}`,
     args,
     origin: { surface: 'schedule', actor: 'browser-probe', correlationId: occurrenceId },
+    authorizationGrantRefs,
   });
 }
 
+/** Exact interactive grants attached to this Schedule; contents remain Controller-owned. */
+export function scheduledBrowserProbeAuthorizationGrantRefs(args: Record<string, unknown>): string[] {
+  if (!Array.isArray(args.authorization_grant_refs)) return [];
+  return [...new Set(args.authorization_grant_refs.map(String).map((value) => value.trim()).filter(Boolean))];
+}
+
 interface ScheduledBrowserSessionMetadata {
   url?: string;
   ownership?: string;
@@ -137,8 +145,9 @@ async function scheduledBrowserSessionMetadata(
   repository: RepositoryRecord,
   occurrenceId: string,
   sessionId: string,
+  authorizationGrantRefs: readonly string[],
 ): Promise<ScheduledBrowserSessionMetadata | undefined> {
-  const inventory = await browserAction(controllerHome, repository, occurrenceId, 'list_sessions', {});
+  const inventory = await browserAction(controllerHome, repository, occurrenceId, 'list_sessions', {}, authorizationGrantRefs);
   const sessions = Array.isArray(inventory.sessions) ? inventory.sessions : [];
   const saved = sessions
     .map((entry) => recordValue(entry))
@@ -170,10 +179,12 @@ export async function executeScheduledBrowserProbe(input: {
   const url = stringValue(input.args.probe_url) ?? stringValue(input.args.url);
   if (!requestedSessionId && !url) throw new Error('SCHEDULE_BROWSER_PROBE_TARGET_REQUIRED');
 
+  const authorizationGrantRefs = scheduledBrowserProbeAuthorizationGrantRefs(input.args);
+
   const waitUntil = stringValue(input.args.wait_until) ?? 'domcontentloaded';
   const timeoutMs = boundedNumber(input.args.timeout_ms, 60_000, 1_000, 120_000);
   const savedSession = requestedSessionId
-    ? await scheduledBrowserSessionMetadata(input.controllerHome, input.repository, input.occurrenceId, requestedSessionId)
+    ? await scheduledBrowserSessionMetadata(input.controllerHome, input.repository, input.occurrenceId, requestedSessionId, authorizationGrantRefs)
     : undefined;
   const navigationAction = scheduledBrowserProbeNavigationAction(savedSession?.ownership, Boolean(url));
   const managedRehydrateIntent = scheduledBrowserProbeManagedRehydrateIntent(savedSession);
@@ -188,7 +199,7 @@ export async function executeScheduledBrowserProbe(input: {
       state: waitUntil,
       timeout_ms: timeoutMs,
       ...managedRehydrateIntent,
-    });
+    }, authorizationGrantRefs);
   } else if (navigationAction === 'navigate') {
     navigation = await browserAction(input.controllerHome, input.repository, input.occurrenceId, 'navigate', {
       ...(requestedSessionId ? { session_id: requestedSessionId } : {}),
@@ -197,14 +208,14 @@ export async function executeScheduledBrowserProbe(input: {
       timeout_ms: timeoutMs,
       retries: 1,
       ...managedRehydrateIntent,
-    });
+    }, authorizationGrantRefs);
   } else {
     navigation = await browserAction(input.controllerHome, input.repository, input.occurrenceId, 'reload', {
       session_id: requestedSessionId!,
       wait_until: waitUntil,
       timeout_ms: timeoutMs,
       ...managedRehydrateIntent,
-    });
+    }, authorizationGrantRefs);
   }
 
   const session = recordValue(navigation.session);
@@ -224,7 +235,7 @@ export async function executeScheduledBrowserProbe(input: {
       session_id: sessionId,
       ...(stringValue(input.args.selector) ? { selector: stringValue(input.args.selector) } : {}),
       max_chars: boundedNumber(input.args.max_chars, 20_000, 256, 100_000),
-    });
+    }, authorizationGrantRefs);
     rawText = stringValue(textResult.text) ?? '';
     truncated = textResult.truncated === true;
   }