@moretea-labs/forge 1.5.1 → 1.6.0

package/src/runtime/execution/process-runtime/gc.ts

@@ -6,10 +6,10 @@
  * - GC failures must not throw into the controller main loop.
  */
 
-import { existsSync, readdirSync, unlinkSync, statSync } from 'fs';
+import { existsSync, readFileSync, readdirSync, unlinkSync, statSync } from 'fs';
 import { join } from 'path';
 import { ensureRepositoryControllerLayout, repositoryControllerRoot } from '../../../cli/repositories/controller-home';
-import { getProcessRecord, listActiveProcessIds } from './store';
+import { listActiveProcessIds } from './store';
 import type { ProcessRuntimeStatus } from './types';
 import { assertRuntimeMayWrite } from '../../root/write-fence';
 import { isProcessAlive } from '../../shared/process-tree';
@@ -39,6 +39,8 @@ export interface ProcessGcResult {
   removedRecords: number;
   removedLogs: number;
   skippedActive: number;
+  /** Legacy/corrupt records without enough terminal proof are preserved. */
+  skippedInvalid?: number;
   error?: string;
 }
 
@@ -50,6 +52,54 @@ function logDir(controllerHome: string, repoId: string): string {
   return join(processesDir(controllerHome, repoId), 'logs');
 }
 
+interface ProcessGcMetadata {
+  status?: ProcessRuntimeStatus;
+  finishedAt?: string;
+  updatedAt?: string;
+  identity?: { pid: number; processStartTime: string };
+  identityUntrusted?: boolean;
+  reusableCheckEvidence: boolean;
+}
+
+/**
+ * GC deliberately reads only the metadata needed to prove terminality. Historical
+ * Process records can predate today's required command descriptor; feeding those
+ * records through the normal recovery reader would either throw during redaction
+ * or, worse, require manufacturing a fake executable. A malformed/unknown record
+ * is skipped rather than deleted, preserving fail-closed recovery semantics.
+ */
+function readProcessGcMetadata(path: string): ProcessGcMetadata | undefined {
+  try {
+    const raw = JSON.parse(readFileSync(path, 'utf8')) as Record<string, unknown>;
+    if (raw.schemaVersion !== 1) return undefined;
+    const status = typeof raw.status === 'string' && TERMINAL.has(raw.status as ProcessRuntimeStatus)
+      ? raw.status as ProcessRuntimeStatus
+      : typeof raw.status === 'string'
+        ? raw.status as ProcessRuntimeStatus
+        : undefined;
+    const identityRaw = raw.identity && typeof raw.identity === 'object' && !Array.isArray(raw.identity)
+      ? raw.identity as Record<string, unknown>
+      : undefined;
+    const pid = typeof identityRaw?.pid === 'number' && Number.isInteger(identityRaw.pid) && identityRaw.pid > 0
+      ? identityRaw.pid
+      : undefined;
+    const processStartTime = typeof identityRaw?.processStartTime === 'string' ? identityRaw.processStartTime : undefined;
+    const checkExecution = raw.checkExecution && typeof raw.checkExecution === 'object' && !Array.isArray(raw.checkExecution)
+      ? raw.checkExecution as Record<string, unknown>
+      : undefined;
+    return {
+      status,
+      finishedAt: typeof raw.finishedAt === 'string' ? raw.finishedAt : undefined,
+      updatedAt: typeof raw.updatedAt === 'string' ? raw.updatedAt : undefined,
+      ...(pid && processStartTime ? { identity: { pid, processStartTime } } : {}),
+      identityUntrusted: raw.identityUntrusted === true,
+      reusableCheckEvidence: status === 'succeeded' && typeof checkExecution?.cacheKey === 'string' && checkExecution.cacheKey.length > 0,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
 function safeUnlink(path: string): boolean {
   try {
     if (existsSync(path)) {
@@ -89,6 +139,7 @@ export function gcTerminalProcesses(options: ProcessGcOptions): ProcessGcResult
     const active = new Set(listActiveProcessIds(options.controllerHome, options.repoId));
     const terminal: Array<{ processId: string; finishedAt: number; path: string; reusableCheckEvidence: boolean }> = [];
     let skippedActive = 0;
+    let skippedInvalid = 0;
 
     for (const name of readdirSync(root)) {
       if (!name.endsWith('.json') || name === 'active-index.json') continue;
@@ -97,12 +148,15 @@ export function gcTerminalProcesses(options: ProcessGcOptions): ProcessGcResult
         skippedActive += 1;
         continue;
       }
-      const record = getProcessRecord(options.controllerHome, options.repoId, processId);
-      if (!record) continue;
+      const metadata = readProcessGcMetadata(join(root, name));
+      if (!metadata?.status) {
+        skippedInvalid += 1;
+        continue;
+      }
       // Skip still-alive identity matches even if status drifted.
-      if (record.identity && !record.identityUntrusted && !record.identity.processStartTime.startsWith('untrusted:')) {
+      if (metadata.identity && !metadata.identityUntrusted && !metadata.identity.processStartTime.startsWith('untrusted:')) {
         try {
-          if (isProcessAlive(record.identity.pid)) {
+          if (isProcessAlive(metadata.identity.pid)) {
             skippedActive += 1;
             continue;
           }
@@ -110,15 +164,15 @@ export function gcTerminalProcesses(options: ProcessGcOptions): ProcessGcResult
           /* ignore probe failures */
         }
       }
-      if (!TERMINAL.has(record.status)) continue;
+      if (!TERMINAL.has(metadata.status)) continue;
       // Do not delete terminal evidence that has never been read when maxAge is not exceeded
       // unless we are strictly over maxTerminalRecords budget (handled by sort below).
-      const finished = Date.parse(record.finishedAt ?? record.updatedAt);
+      const finished = Date.parse(metadata.finishedAt ?? metadata.updatedAt ?? '');
       terminal.push({
         processId,
         finishedAt: Number.isFinite(finished) ? finished : 0,
         path: join(root, name),
-        reusableCheckEvidence: record.status === 'succeeded' && Boolean(record.checkExecution?.cacheKey),
+        reusableCheckEvidence: metadata.reusableCheckEvidence,
       });
     }
 
@@ -140,7 +194,7 @@ export function gcTerminalProcesses(options: ProcessGcOptions): ProcessGcResult
       }
     }
 
-    return { ok: true, removedRecords, removedLogs, skippedActive };
+    return { ok: true, removedRecords, removedLogs, skippedActive, skippedInvalid };
   } catch (error) {
     return {
       ok: false,

package/src/runtime/execution/process-runtime/persisted-check.ts

@@ -1,6 +1,7 @@
 import { createHash } from 'crypto';
 import { existsSync } from 'fs';
 import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
 import {
   controllerCheckExecutionIdentity,
   listControllerChecks,
@@ -37,7 +38,10 @@ export function resolvePersistedCheckCliInvocation(
 }
 
 export function resolveRuntimeCliTarget(controllerHome?: string): CliRuntimeTarget {
-  const moduleSourceRoot = resolve(import.meta.dir, '..', '..', '..', '..');
+  const moduleDir = typeof import.meta.dir === 'string' && import.meta.dir
+    ? import.meta.dir
+    : dirname(fileURLToPath(import.meta.url));
+  const moduleSourceRoot = resolve(moduleDir, '..', '..', '..', '..');
   const sourceEntry = resolve(moduleSourceRoot, 'src', 'cli', 'index.ts');
   const source = resolveControllerRuntimeSourceRoot({
     explicitRoot: existsSync(sourceEntry) ? moduleSourceRoot : undefined,
@@ -214,7 +218,11 @@ export async function runPersistedCheckViaProcessRuntime(
     scopeKey: persistedCheckSemanticScopeKey(input, semanticCheck.reuseScope),
   };
   const cliTarget = resolveRuntimeCliTarget(input.controllerHome);
-  const checkResultReceiptPath = allocatePersistedCheckResultReceiptPath(input.controllerHome, input.repoId);
+  const checkResultReceiptPath = allocatePersistedCheckResultReceiptPath(
+    input.controllerHome,
+    input.repoId,
+    input.requestId,
+  );
   const checkArgs = [
     '--repo',
     executionRoot,

package/src/runtime/execution/process-runtime/resource-claims.ts

@@ -4,6 +4,8 @@
  */
 
 import type { ResourceClaimSpec } from '../jobs/types';
+import { readFileSync } from 'fs';
+import { join } from 'path';
 import type { ControllerCheckEffects } from '../../../cli/controller/check-runner';
 import { classifyRepositoryCommand, fixedShellWrapperCommand } from '../../../cli/repositories/command-classifier';
 import { normalizeRepositoryCommand } from '../../../cli/repositories/command-normalization';
@@ -157,7 +159,89 @@ function iosSimulatorTestCommandClaims(
   ]);
 }
 
-function hostOnlyCommandClaims(command: string | readonly string[]): ResourceClaimSpec[] | undefined {
+function localHttpServerClaims(command: string | readonly string[]): ResourceClaimSpec[] | undefined {
+  const canonical = normalizeRepositoryCommand(command);
+  if (canonical.kind !== 'argv') return undefined;
+  const program = (canonical.executable ?? '').split(/[\\/]/).at(-1)?.toLowerCase();
+  if (program !== 'python' && program !== 'python3') return undefined;
+  const args = canonical.args ?? [];
+  if (args[0] !== '-m' || args[1] !== 'http.server' || args.includes('--cgi')) return undefined;
+  let bind = '0.0.0.0';
+  let port = '8000';
+  for (let index = 2; index < args.length; index += 1) {
+    const arg = args[index]!;
+    if (arg === '--bind') { bind = args[index + 1] ?? bind; index += 1; continue; }
+    if (arg === '--directory' || arg === '-d' || arg === '--protocol') { index += 1; continue; }
+    if (!arg.startsWith('-') && /^\d{1,5}$/.test(arg)) port = arg;
+  }
+  return [claimHostService(`tcp-listen:${bind}:${port}`, 'write')];
+}
+
+function loopbackCurlClaims(command: string | readonly string[], repoId: string): ResourceClaimSpec[] | undefined {
+  const canonical = normalizeRepositoryCommand(command);
+  if (canonical.kind !== 'argv') return undefined;
+  const program = (canonical.executable ?? '').split(/[\\/]/).at(-1)?.toLowerCase();
+  if (program !== 'curl') return undefined;
+  const args = canonical.args ?? [];
+  if (args.some((arg) => /^(?:-X|--request|-d|--data|--data-raw|--data-binary|-F|--form|-T|--upload-file|-o|--output|-O|--remote-name)$/i.test(arg))) return undefined;
+  const explicitMethodIndex = args.findIndex((arg) => arg === '-X' || arg === '--request');
+  if (explicitMethodIndex >= 0 && !/^(?:GET|HEAD)$/i.test(args[explicitMethodIndex + 1] ?? '')) return undefined;
+  const urls = args.filter((arg) => /^https?:\/\//i.test(arg));
+  if (urls.length === 0 || urls.some((url) => {
+    try {
+      const host = new URL(url).hostname.toLowerCase();
+      return !['127.0.0.1', 'localhost', '::1'].includes(host);
+    } catch { return true; }
+  })) return undefined;
+  return [claimNetwork(repoId, 'read')];
+}
+
+function simpleViteScript(script: string): boolean {
+  const normalized = script.trim();
+  if (!normalized || /[;&|`$<>\n\r]/.test(normalized)) return false;
+  return /^(?:(?:\.\/)?node_modules\/.bin\/)?vite(?:\s|$)/.test(normalized);
+}
+
+function viteServiceClaims(
+  command: string | readonly string[],
+  repoId: string,
+  checkoutId?: string,
+  repoRoot?: string,
+): ResourceClaimSpec[] | undefined {
+  const canonical = normalizeRepositoryCommand(command);
+  if (canonical.kind !== 'argv') return undefined;
+  const program = (canonical.executable ?? '').split(/[\\/]/).at(-1)?.toLowerCase();
+  const args = canonical.args ?? [];
+  let vite = program === 'vite';
+  if (!vite && (program === 'npx' || program === 'bunx') && args[0]?.toLowerCase() === 'vite') vite = true;
+  if (!vite && program === 'bun' && args[0]?.toLowerCase() === 'x' && args[1]?.toLowerCase() === 'vite') vite = true;
+  if (!vite && repoRoot && ['npm', 'pnpm', 'yarn', 'bun'].includes(program ?? '')) {
+    const runIndex = args[0]?.toLowerCase() === 'run' ? 1 : program === 'yarn' ? 0 : -1;
+    const scriptName = runIndex >= 0 ? args[runIndex]?.toLowerCase() : undefined;
+    if (scriptName === 'dev') {
+      try {
+        const pkg = JSON.parse(readFileSync(join(repoRoot, 'package.json'), 'utf8')) as { scripts?: Record<string, unknown> };
+        const script = typeof pkg.scripts?.dev === 'string' ? pkg.scripts.dev : '';
+        vite = simpleViteScript(script);
+      } catch {
+        vite = false;
+      }
+    }
+  }
+  if (!vite) return undefined;
+  return normalizeClaims([
+    claimBuildCacheWrite(repoId),
+    claimHostService(`vite:${checkoutScope(checkoutId)}`, 'write'),
+  ]);
+}
+
+function hostOnlyCommandClaims(command: string | readonly string[], repoId: string, checkoutId?: string, repoRoot?: string): ResourceClaimSpec[] | undefined {
+  const localServer = localHttpServerClaims(command);
+  if (localServer) return localServer;
+  const loopbackCurl = loopbackCurlClaims(command, repoId);
+  if (loopbackCurl) return loopbackCurl;
+  const vite = viteServiceClaims(command, repoId, checkoutId, repoRoot);
+  if (vite) return vite;
   const canonical = normalizeRepositoryCommand(command);
   if (canonical.kind === 'shell') {
     return browserAppleScriptHeredocClaims(canonical.shellCommand ?? '');
@@ -347,13 +431,14 @@ export function claimsForRepositoryCommand(
   repoId: string,
   checkoutId?: string,
   defaultBranch?: string,
+  repoRoot?: string,
 ): ResourceClaimSpec[] {
   const classification = classifyRepositoryCommand(command, defaultBranch);
   const canonical = normalizeRepositoryCommand(command);
   const focused = isFocusedCheckCommand(command);
   const iosSimulatorClaims = iosSimulatorTestCommandClaims(command, repoId, checkoutId);
   if (iosSimulatorClaims) return iosSimulatorClaims;
-  const hostClaims = hostOnlyCommandClaims(command);
+  const hostClaims = hostOnlyCommandClaims(command, repoId, checkoutId, repoRoot);
   if (hostClaims) return hostClaims;
 
   if (classification.risk === 'readonly') {

package/src/runtime/execution/process-runtime/runtime.ts

@@ -258,8 +258,23 @@ function captureIdentity(pid: number | undefined): {
 } {
   if (!pid || pid <= 0) return {};
   const probe = defaultProcessIdentityProbe;
-  if (!probe.isAlive(pid)) return {};
+  // The combined inspect probe already proves the PID exists on the normal
+  // POSIX path. Avoid an immediately preceding ps(stat) child process; only
+  // fall back to the separate alive/command/start-time probes when the combined
+  // observation is unavailable or incomplete.
   const inspected = probe.inspect?.(pid);
+  if (inspected?.command && inspected.startTime) {
+    return {
+      identity: {
+        pid,
+        processStartTime: inspected.startTime,
+        executableFingerprint: executableFingerprint(inspected.command),
+        processGroupId: process.platform !== 'win32' ? pid : undefined,
+      },
+      identityUntrusted: false,
+    };
+  }
+  if (!probe.isAlive(pid)) return {};
   const command = inspected?.command ?? probe.command(pid);
   const startTime = inspected?.startTime ?? probe.startTime(pid);
   if (!command || !startTime) {

package/src/runtime/execution/process-runtime/store.ts

@@ -308,6 +308,12 @@ function sanitizeProcessRecord(record: ManagedProcessRecord): { record: ManagedP
 function readProcessRecord(path: string): ManagedProcessRecord | undefined {
   const record = readJson<ManagedProcessRecord>(path);
   if (!record || record.schemaVersion !== 1) return undefined;
+  // Legacy/partial Process files can predate the required command descriptor.
+  // They are not executable recovery authority and must never be repaired by
+  // inventing a command. Treat them as unavailable to normal Runtime readers;
+  // bounded GC has its own metadata-only parser so one such file cannot block
+  // cleanup of unrelated proven terminal records.
+  if (!record.command || typeof record.command !== 'object' || Array.isArray(record.command)) return undefined;
   const sanitized = sanitizeProcessRecord(record);
   if (sanitized.changed) atomicWrite(path, sanitized.record);
   return sanitized.record;

package/src/runtime/gateway/mcp/execution-tools.ts

@@ -659,7 +659,11 @@ function terminalCleanupOutcome(
   if (contract?.status === 'cancelled') return 'cancelled';
   const reason = `${handle.failureReason ?? ''} ${handle.finalization.lastError ?? ''}`.toLowerCase();
   if (contract?.status === 'blocked' && reason.includes('terminal')) return 'blocked_terminal';
-  if (contract?.status === 'failed' || handle.state === 'failed' || handle.state === 'failed_terminal_cleanup') {
+  // `failed` is a retryable execution-handle state (its transition table allows
+  // failed -> validating/editing). Do not reinterpret it as terminal cleanup
+  // unless the durable Work itself is terminal. `failed_terminal_cleanup` is
+  // the explicit point of no return for resource cleanup reconciliation.
+  if (contract?.status === 'failed' || handle.state === 'failed_terminal_cleanup') {
     if (reason.includes('infrastructure') || reason.includes('timed out') || reason.includes('unavailable')) {
       return 'infrastructure_failed';
     }
@@ -1202,12 +1206,20 @@ async function validateWork(ctx: MultiRepositoryMcpToolContext, args: Record<str
         repoId: handle.repositoryId,
         checkoutId: handle.checkoutId,
         repoRoot: validated.worktreeRepository.canonicalRoot,
-        executionIdentity: executionIdentityForWork(validated.worktreeRepository, handle),
+        executionIdentity: Object.freeze({
+          ...executionIdentityForWork(validated.worktreeRepository, handle),
+          expectedHead: validationHead === 'unknown' ? handle.expectedHead : validationHead,
+        }),
         checkId,
         requestId: processRequestId,
         workId: handle.workId,
         commandId: processRequestId,
         verificationBinding: { executionSessionId: session.sessionId },
+        verificationSnapshot: contract && contract.allowedPaths.length > 0 ? {
+          workId: contract.workId,
+          allowedPaths: contract.allowedPaths,
+          forbiddenPaths: contract.forbiddenPaths,
+        } : undefined,
       });
       if (executed.mode === 'durable') {
         checks.push({ checkId, ok: undefined, status: 'deferred', summary: executed.durable?.reason, durable: executed.durable });
@@ -1236,7 +1248,6 @@ async function validateWork(ctx: MultiRepositoryMcpToolContext, args: Record<str
       repoId: handle.repositoryId,
       checkoutId: handle.checkoutId,
       workId: handle.workId,
-      executionSessionId: session.sessionId,
       checkId,
       processId: process.processId,
     });
@@ -1311,21 +1322,25 @@ async function validateWork(ctx: MultiRepositoryMcpToolContext, args: Record<str
       failureSummary,
     );
   }
-  if (completed && !passed) {
-    const cleanup = await reconcileTerminalCleanup(
-      ctx,
-      session,
-      next,
-      args,
-      infrastructureFailure ? 'infrastructure_failed' : 'validation_failed',
-    );
+  if (completed && acceptedFailure) {
+    const cleanup = await reconcileTerminalCleanup(ctx, session, next, args, 'validation_failed');
     const value = {
       ...cleanup,
       validation: { passed, completed, checks, targeted: true, changedPaths, cleanupTriggered: true },
     };
     return makeBoundedResult(ctx, session, handle.repositoryId, handle.workId, 'validation', value);
   }
-  const value = { work: compactHandle(next), validation: { passed, completed, checks, targeted: true, changedPaths } };
+  const value = {
+    work: compactHandle(next),
+    validation: {
+      passed,
+      completed,
+      checks,
+      targeted: true,
+      changedPaths,
+      ...(infrastructureFailure ? { retryable: true, cleanupTriggered: false } : {}),
+    },
+  };
   return makeBoundedResult(ctx, session, handle.repositoryId, handle.workId, 'validation', value);
 }
 

package/src/runtime/gateway/mcp/router.ts

@@ -898,7 +898,7 @@ export async function routeDurableMcpCall(
       }, validation.isError === true);
     }
 
-    const applied = await callRepositoryTool(ctx.controllerHome, name, args);
+    const applied = await callRepositoryTool(ctx.controllerHome, name, args, ctx);
     if (!applied || applied.isError === true) return applied;
     const patchPayload = (applied.structuredContent ?? {}) as Record<string, unknown>;
     if (patchPayload.status !== 'applied') return applied;