@moretea-labs/forge 1.6.0 → 1.7.0

package/src/runtime/control-plane/routing/route-policy.ts

@@ -1,6 +1,6 @@
 import { createHash } from 'crypto';
 
-export const ROUTE_POLICY_VERSION = 'route-policy-v3' as const;
+export const ROUTE_POLICY_VERSION = 'route-policy-v4' as const;
 
 export type RouteExecutionMode = 'direct_control' | 'goal_workloop' | 'handoff_only';
 export type RouteWorkMode = 'direct_edit' | 'bounded_work' | 'quick_agent' | 'issue_task';
@@ -238,8 +238,6 @@ export function decideRoute(input: RoutePolicyInput): RouteDecision {
     ? false
     : input.recovery.isolationRequired === true || explicitParallelMode;
   const requiresRecovery = input.recovery.required === true
-    || input.intent.requiresLongRunningChecks === true
-    || explicitMode === 'debug'
     || explicitMode === 'release'
     || explicitMode === 'scale';
   const coordinationRequired = explicitParallelMode || input.intent.requiresIndependentDeliverables === true
@@ -289,26 +287,21 @@ export function decideRoute(input: RoutePolicyInput): RouteDecision {
   }
 
   if (input.workspace.dirty && mutation) {
-    reasons.push({ code: 'dirty_workspace_requires_explicit_adoption', message: 'Mutation against a dirty workspace requires an exact reviewed adoption or a clean isolated checkout.' });
-    return {
-      executionMode: 'handoff_only', executorKind: 'handoff_only', selectedProviderId: null,
-      workMode: 'direct_edit', executionPath: 'durable', requiresWork: true, requiresApproval: false,
-      requiresIsolation: true, requiresRecovery: true, createHandoff: true, waitForUser: false,
-      approvalState: 'approval_not_required', alternatives: [], ...decisionBase(input, reasons),
-    };
+    reasons.push({
+      code: 'dirty_workspace_preserve_existing_changes',
+      message: 'The checkout is already dirty; preserve unrelated changes and treat inspected/actual scope as evidence instead of creating Work solely for adoption.',
+    });
   }
   if (explicitMode) reasons.push({ code: `explicit_${explicitMode}`, message: `Explicit -${explicitMode} mode overrides automatic work topology while policy gates remain authoritative.` });
   if (protectedPath) reasons.push({ code: 'protected_path', message: 'The predicted scope includes a protected or release-sensitive path.' });
   if (requiresRecovery) reasons.push({ code: 'recovery_required', message: 'The operation needs resumable Work and bounded recovery.' });
   if (requiresIsolation) reasons.push({ code: 'isolation_required', message: 'The operation requires an isolated checkout or serialized lane.' });
-  if (input.intent.requiresLongRunningChecks) reasons.push({ code: 'long_checks', message: 'Long-running checks require durable continuation.' });
+  if (input.intent.requiresLongRunningChecks) reasons.push({ code: 'long_checks', message: 'Long-running checks may use a lightweight handle; duration alone does not require durable Work.' });
   if (input.intent.requiresInvestigation) reasons.push({ code: 'investigation', message: 'Investigation is required before or during implementation.' });
   if (input.intent.needsDependencies) reasons.push({ code: 'dependencies', message: 'Dependency ordering requires durable Work.' });
   if (coordinationRequired) reasons.push({ code: 'independent_deliverables', message: 'Multiple independent deliverables require durable PlanContract/Work coordination.' });
 
   const explicitBoundedMode = explicitMode === 'plan'
-    || explicitMode === 'debug'
-    || explicitMode === 'review'
     || explicitMode === 'release';
   const complex = explicitMode === 'direct'
     ? false
@@ -320,11 +313,9 @@ export function decideRoute(input: RoutePolicyInput): RouteDecision {
     || input.capabilities.requiresWorker === true
     || input.capabilities.requiresExternalEffect === true
     || input.intent.needsDependencies === true
-    || protectedPath
     || destructive
     || remoteWrite
-    || secretAccess
-    || (mutation && (expectedFiles > 4 || expectedChangedLines > 200));
+    || secretAccess;
   const executionMode: RouteExecutionMode = complex ? 'goal_workloop' : 'direct_control';
   // Work topology is independent from executor/provider choice. Independent or
   // parallel deliverables stay in the durable Goal Workloop and are decomposed by

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

@@ -1,6 +1,5 @@
 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';
@@ -26,7 +25,6 @@ export interface ForgeRuntimeStatus {
   gatewaySeparated?: boolean;
   workerIsolation?: boolean;
   degraded?: boolean;
-  recovery?: ControllerStartupRecoveryResult;
   generation?: string;
   source?: RuntimeSourceIdentity;
   restartRequired?: boolean;

package/src/runtime/diagnostics/mcp-timing.ts

@@ -21,6 +21,19 @@ export interface McpTimingTrace {
   commandExecutionMs?: number;
   resultSerializationMs?: number;
   resultPersistenceMs?: number;
+  /** Public Gateway only: resolve current Canonical Runtime identity/token/endpoint. */
+  gatewayProxyResolveMs?: number;
+  /** Public Gateway only: establish or await a Canonical Runtime MCP client connection. */
+  gatewayProxyConnectMs?: number;
+  /** Public Gateway only: MCP call duration after a client is acquired, including Canonical Runtime work. */
+  gatewayProxyCallMs?: number;
+  /** Public Gateway only: time from forwarding the tool call until the Canonical Runtime handler starts. */
+  gatewayProxyCanonicalDispatchLagMs?: number;
+  /** Canonical Runtime server duration projected back through the proxy response. */
+  gatewayProxyCanonicalDurationMs?: number;
+  /** Public Gateway only: response/transport tail after canonical handler completion. */
+  gatewayProxyReturnMs?: number;
+  gatewayProxyConnectionState?: 'reused' | 'cold_connect' | 'coalesced_connect' | 'identity_reconnect';
   totalToolDurationMs: number;
   sessionId?: string;
   repoId?: string;

package/src/runtime/diagnostics/mcp-transport-benchmark.ts

@@ -0,0 +1,129 @@
+export type McpTransportTimingScope = 'tool_call' | 'connect_and_tool_call';
+
+export interface McpTransportLatencySample {
+  label: string;
+  tool: string;
+  timingScope?: McpTransportTimingScope;
+  clientTotalMs: number;
+  serverDurationMs: number;
+  traceId?: string;
+  requestId?: string;
+  observedAt?: string;
+}
+
+export interface McpTransportLatencyStats {
+  p50: number;
+  p95: number;
+  max: number;
+}
+
+export interface McpTransportLatencyGroup {
+  label: string;
+  tool: string;
+  timingScope: McpTransportTimingScope;
+  sampleCount: number;
+  clientTotalMs: McpTransportLatencyStats;
+  serverDurationMs: McpTransportLatencyStats;
+  externalResidualMs: McpTransportLatencyStats;
+  externalSharePct: McpTransportLatencyStats;
+  serverExceedsClientCount: number;
+}
+
+export interface McpTransportLatencyReport {
+  schemaVersion: 1;
+  sampleCount: number;
+  groups: McpTransportLatencyGroup[];
+}
+
+function round(value: number): number {
+  return Math.round(value * 100) / 100;
+}
+
+function percentile(values: number[], fraction: number): number {
+  if (values.length === 0) return 0;
+  const sorted = [...values].sort((left, right) => left - right);
+  const index = Math.max(0, Math.min(sorted.length - 1, Math.ceil(sorted.length * fraction) - 1));
+  return round(sorted[index]!);
+}
+
+function stats(values: number[]): McpTransportLatencyStats {
+  return {
+    p50: percentile(values, 0.5),
+    p95: percentile(values, 0.95),
+    max: round(Math.max(...values, 0)),
+  };
+}
+
+function validDuration(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+
+export function normalizeMcpTransportLatencySample(value: unknown): McpTransportLatencySample {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('MCP_TRANSPORT_SAMPLE_INVALID: sample must be an object');
+  }
+  const record = value as Record<string, unknown>;
+  const label = typeof record.label === 'string' ? record.label.trim() : '';
+  const tool = typeof record.tool === 'string' ? record.tool.trim() : '';
+  const timingScope = record.timingScope === undefined || record.timingScope === 'tool_call'
+    ? 'tool_call'
+    : record.timingScope === 'connect_and_tool_call'
+      ? 'connect_and_tool_call'
+      : undefined;
+  if (!label) throw new Error('MCP_TRANSPORT_SAMPLE_INVALID: label is required');
+  if (!tool) throw new Error('MCP_TRANSPORT_SAMPLE_INVALID: tool is required');
+  if (!timingScope) throw new Error('MCP_TRANSPORT_SAMPLE_INVALID: timingScope must be tool_call or connect_and_tool_call');
+  if (!validDuration(record.clientTotalMs)) throw new Error('MCP_TRANSPORT_SAMPLE_INVALID: clientTotalMs must be a non-negative finite number');
+  if (!validDuration(record.serverDurationMs)) throw new Error('MCP_TRANSPORT_SAMPLE_INVALID: serverDurationMs must be a non-negative finite number');
+  return {
+    label,
+    tool,
+    timingScope,
+    clientTotalMs: record.clientTotalMs,
+    serverDurationMs: record.serverDurationMs,
+    ...(typeof record.traceId === 'string' && record.traceId.trim() ? { traceId: record.traceId.trim() } : {}),
+    ...(typeof record.requestId === 'string' && record.requestId.trim() ? { requestId: record.requestId.trim() } : {}),
+    ...(typeof record.observedAt === 'string' && record.observedAt.trim() ? { observedAt: record.observedAt.trim() } : {}),
+  };
+}
+
+export function extractForgeServerDuration(result: unknown): number | undefined {
+  if (!result || typeof result !== 'object' || Array.isArray(result)) return undefined;
+  const structured = (result as Record<string, unknown>).structuredContent;
+  if (!structured || typeof structured !== 'object' || Array.isArray(structured)) return undefined;
+  const responseMeta = (structured as Record<string, unknown>).responseMeta;
+  if (!responseMeta || typeof responseMeta !== 'object' || Array.isArray(responseMeta)) return undefined;
+  const duration = (responseMeta as Record<string, unknown>).serverDurationMs;
+  return validDuration(duration) ? duration : undefined;
+}
+
+export function aggregateMcpTransportLatencySamples(values: unknown[]): McpTransportLatencyReport {
+  const samples = values.map(normalizeMcpTransportLatencySample);
+  const grouped = new Map<string, McpTransportLatencySample[]>();
+  for (const sample of samples) {
+    const key = `${sample.label}\u0000${sample.tool}\u0000${sample.timingScope ?? 'tool_call'}`;
+    const entries = grouped.get(key) ?? [];
+    entries.push(sample);
+    grouped.set(key, entries);
+  }
+  const groups = [...grouped.values()].map((entries): McpTransportLatencyGroup => {
+    const client = entries.map((sample) => sample.clientTotalMs);
+    const server = entries.map((sample) => sample.serverDurationMs);
+    const residual = entries.map((sample) => Math.max(0, sample.clientTotalMs - sample.serverDurationMs));
+    const share = entries.map((sample, index) => client[index]! > 0 ? residual[index]! / client[index]! * 100 : 0);
+    return {
+      label: entries[0]!.label,
+      tool: entries[0]!.tool,
+      timingScope: entries[0]!.timingScope ?? 'tool_call',
+      sampleCount: entries.length,
+      clientTotalMs: stats(client),
+      serverDurationMs: stats(server),
+      externalResidualMs: stats(residual),
+      externalSharePct: stats(share),
+      serverExceedsClientCount: entries.filter((sample) => sample.serverDurationMs > sample.clientTotalMs).length,
+    };
+  }).sort((left, right) => left.label.localeCompare(right.label)
+    || left.tool.localeCompare(right.tool)
+    || left.timingScope.localeCompare(right.timingScope));
+  return { schemaVersion: 1, sampleCount: samples.length, groups };
+}

package/src/runtime/diagnostics/performance.ts

@@ -1,5 +1,5 @@
 import { execFileSync } from 'child_process';
-import { existsSync, lstatSync, readdirSync, rmSync } from 'fs';
+import { existsSync, lstatSync, readdirSync, rmSync, statfsSync } from 'fs';
 import { tmpdir } from 'os';
 import { basename, dirname, join, resolve } from 'path';
 
@@ -46,6 +46,7 @@ export interface RuntimePerformanceDiagnostics {
   };
   processes: RuntimeProcessSample[];
   temp: { scannedRoots: string[]; totalEntries: number; cleanupCandidates: number; entries: RuntimeTempEntry[] };
+  storage: { availableBytes?: number; availableGiB?: number; pressure: 'normal' | 'warning' | 'critical' | 'unknown'; managedCacheRoots: string[] };
   cleanupPreview?: { safeToTerminate: RuntimeProcessSample[]; safeToRemoveTempEntries: RuntimeTempEntry[]; requiresConfirmation: true };
   truncated: {
     summary: boolean;
@@ -322,7 +323,27 @@ export function collectRuntimePerformanceDiagnostics(input: DiagnosticsInput): R
   const temp = input.includeTempDirs === false
     ? { roots: [] as string[], entries: [] as RuntimeTempEntry[] }
     : scanRuntimeTempEntries(processes);
+  let availableBytes: number | undefined;
+  try {
+    const fs = statfsSync(input.repoRoot);
+    availableBytes = Number(fs.bavail) * Number(fs.bsize);
+  } catch {}
+  const availableGiB = availableBytes === undefined ? undefined : Math.round((availableBytes / (1024 ** 3)) * 10) / 10;
+  const storagePressure: RuntimePerformanceDiagnostics['storage']['pressure'] = availableGiB === undefined
+    ? 'unknown'
+    : availableGiB < 30
+      ? 'critical'
+      : availableGiB < 50
+        ? 'warning'
+        : 'normal';
+  const managedCacheRoots = [
+    join(input.repoRoot, '.forge', 'ios', 'DerivedData'),
+    join(input.repoRoot, '.ai', 'harness'),
+    join(input.repoRoot, '.repo-harness'),
+  ].filter((path) => existsSync(path));
   const findings: RuntimePerformanceDiagnostics['findings'] = [];
+  if (storagePressure === 'critical') findings.push({ severity: 'critical', code: 'LOW_DISK_SPACE', message: `Only ${availableGiB} GiB of repository volume space is available.` });
+  else if (storagePressure === 'warning') findings.push({ severity: 'warning', code: 'LOW_DISK_SPACE', message: `Repository volume free space is ${availableGiB} GiB.` });
   if (orphanWorkers.length > 0) findings.push({ severity: orphanWorkers.length >= 3 ? 'critical' : 'warning', code: 'ORPHAN_WORKERS', message: 'Detected ' + orphanWorkers.length + ' orphan worker process(es).' });
   const totalCpu = Math.round(repoProcesses.reduce((sum, process) => sum + process.cpu, 0) * 10) / 10;
   if (totalCpu >= 100 || highCpu.length >= 3) findings.push({ severity: 'warning', code: 'HIGH_FORGE_CPU', message: 'Forge-related CPU is ' + totalCpu + '%.' });
@@ -341,6 +362,7 @@ export function collectRuntimePerformanceDiagnostics(input: DiagnosticsInput): R
     ...(orphanWorkers.length ? ['Terminate orphan workers only after reviewing cleanupPreview.safeToTerminate.'] : []),
     ...(tempCleanupCandidates.length ? ['Remove stale temp entries through runtime_maintenance_apply after reviewing cleanupPreview.safeToRemoveTempEntries.'] : []),
     ...(highCpu.length ? ['Inspect highCpuProcesses before restarting the controller stack.'] : []),
+    ...(storagePressure === 'critical' ? ['Allow Forge generated-cache retention to reclaim stale DerivedData before starting another heavy iOS verification.'] : []),
   ];
   return {
     schemaVersion: 1,
@@ -358,6 +380,7 @@ export function collectRuntimePerformanceDiagnostics(input: DiagnosticsInput): R
       cleanupCandidates: tempCleanupCandidates.length,
       entries: temp.entries.slice(0, MAX_DIAGNOSTIC_TEMP_ENTRIES),
     },
+    storage: { availableBytes, availableGiB, pressure: storagePressure, managedCacheRoots },
     cleanupPreview: input.cleanupPreview === true
       ? {
         safeToTerminate: rawCleanupProcesses,

package/src/runtime/evidence/event-ledger.ts

@@ -18,7 +18,7 @@ export interface RuntimeEntityEvent {
   eventId: string;
   eventType: string;
   repoId: string;
-  entityType: 'job' | 'plugin' | 'schedule' | 'occurrence' | 'portfolio' | 'candidate-finding' | 'release' | 'lease' | 'schedule-decision' | 'assistant-action-proposal' | 'assistant-standing-grant';
+  entityType: 'job' | 'plugin' | 'schedule' | 'occurrence' | 'portfolio' | 'release' | 'lease' | 'schedule-decision';
   entityId: string;
   correlationId?: string;
   causationId?: string;

package/src/runtime/execution/jobs/store.ts

@@ -2,7 +2,7 @@ import { createHash, randomUUID } from 'crypto';
 import { existsSync, readdirSync } from 'fs';
 import { join } from 'path';
 import { ensureControllerHome, ensureRepositoryControllerLayout, repositoryControllerRoot } from '../../../cli/repositories/controller-home';
-import { withControllerLock } from '../../../cli/repositories/locks';
+import { releaseControllerLock, tryAcquireControllerLock, withControllerLock } from '../../../cli/repositories/locks';
 import { appendJobEvent } from '../../evidence/event-ledger';
 import { writeExecutionArtifact } from '../../evidence/artifact-store';
 import { markRepositoryProjectionDirty } from '../../projections/invalidation';
@@ -206,7 +206,9 @@ function writeActiveIndex(controllerHome: string, index: ActiveJobIndex): void {
   writeJsonAtomic(activeIndexPath(controllerHome), {
     schemaVersion: 1,
     updatedAt: now(),
-    jobs: [...deduped.values()].sort((a, b) => a.queuedAt.localeCompare(b.queuedAt)).slice(-5000),
+    // Active work is correctness state, not a presentation window. Dropping an
+    // entry here makes Scheduler/recovery reads forget a durable non-terminal Job.
+    jobs: [...deduped.values()].sort((a, b) => a.queuedAt.localeCompare(b.queuedAt)),
   } satisfies ActiveJobIndex);
 }
 
@@ -258,7 +260,9 @@ export function rebuildExecutionJobIndexes(controllerHome: string, repoIds: stri
     for (const repoId of targetRepos) {
       const records = join(executionJobRoot(controllerHome, repoId), 'records');
       let names: string[] = [];
-      try { names = readdirSync(records).filter((name) => name.endsWith('.json')).slice(0, 5000); } catch { continue; }
+      // Startup repair must rebuild every active and request authority. Only the
+      // recent-history projection below is intentionally bounded.
+      try { names = readdirSync(records).filter((name) => name.endsWith('.json')); } catch { continue; }
       for (const name of names) {
         try {
           const job = readJsonFile<ExecutionJob>(join(records, name));
@@ -648,11 +652,61 @@ export function listActiveExecutionJobs(controllerHome: string, repoId?: string)
     try {
       const job = getExecutionJob(controllerHome, entry.repoId, entry.jobId);
       if (ACTIVE_JOB_STATUSES.has(job.status)) output.push(job);
-    } catch { /* stale index repaired below */ }
+    } catch { /* maintenance reconciliation owns stale-index repair */ }
   }
   return output;
 }
 
+/**
+ * Maintenance-only active-index convergence. The active index itself is the
+ * bounded candidate set; this never scans historical Job directories. Ordinary
+ * read APIs remain side-effect free, while the Scheduler can remove terminal or
+ * missing entries once and make subsequent idle reads genuinely cheap.
+ */
+export function reconcileActiveExecutionJobIndex(
+  controllerHome: string,
+  repoId?: string,
+): ExecutionJob[] {
+  const key = { scope: 'global' as const, resource: 'execution-index' };
+  const owner = `execution-index-active-reconcile:${repoId ?? 'all'}`;
+  const acquired = tryAcquireControllerLock(controllerHome, key, owner);
+  if (!acquired.acquired) return listActiveExecutionJobs(controllerHome, repoId);
+  try {
+    const index = readActiveIndex(controllerHome);
+    const jobs: ExecutionJob[] = [];
+    const retained: ActiveJobIndex['jobs'] = [];
+    let removed = 0;
+    for (const entry of index.jobs) {
+      if (repoId && entry.repoId !== repoId) {
+        retained.push(entry);
+        continue;
+      }
+      try {
+        const job = getExecutionJob(controllerHome, entry.repoId, entry.jobId);
+        if (!ACTIVE_JOB_STATUSES.has(job.status)) {
+          removed += 1;
+          continue;
+        }
+        jobs.push(job);
+        retained.push({
+          jobId: job.jobId,
+          repoId: job.repoId,
+          status: job.status,
+          priority: job.priority,
+          queuedAt: job.queuedAt,
+          updatedAt: job.updatedAt,
+        });
+      } catch {
+        removed += 1;
+      }
+    }
+    if (removed > 0) writeActiveIndex(controllerHome, { ...index, jobs: retained });
+    return jobs;
+  } finally {
+    releaseControllerLock(controllerHome, key, acquired.lock.lockId);
+  }
+}
+
 function executionJobApprovalRequestId(job: ExecutionJob): string | undefined {
   if (typeof job.result?.approvalRequestId === 'string') return job.result.approvalRequestId;
   const authorization = job.result?.authorization;

package/src/runtime/execution/jobs/types.ts

@@ -45,7 +45,7 @@ export interface ResourceClaimSpec {
 }
 
 export interface ExecutionJobOrigin {
-  surface: 'mcp' | 'local-ui' | 'mobile-intent' | 'chatgpt-action' | 'assistant-routine' | 'standing-grant' | 'cli' | 'schedule' | 'reconciliation' | 'system';
+  surface: 'mcp' | 'local-ui' | 'mobile-intent' | 'chatgpt-action' | 'cli' | 'schedule' | 'reconciliation' | 'system';
   actor?: string;
   correlationId?: string;
   causationId?: string;

package/src/runtime/execution/managed-workspace.ts

@@ -1,5 +1,5 @@
 import { createHash } from 'crypto';
-import { existsSync, mkdirSync, realpathSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, realpathSync, symlinkSync } from 'fs';
 import { dirname, join, resolve } from 'path';
 import { repositoryControllerRoot } from '../../cli/repositories/controller-home';
 import type { RepositoryRecord } from '../../cli/repositories/types';
@@ -14,6 +14,7 @@ import { branchSlugSegment, validateBranchName } from '../../cli/repositories/br
 import { withControllerLock } from '../../cli/repositories/locks';
 import { resolveGitExecutable } from '../../effects/git-executable';
 import { runProcess } from '../../effects/process-runner';
+import { repositoryChildProcessEnvironment, resolveBunExecutable } from '../shared/process-environment';
 import { readJsonFile, writeJsonAtomic } from '../shared/json-files';
 
 export interface EnsureManagedWorkspaceInput {
@@ -21,6 +22,24 @@ export interface EnsureManagedWorkspaceInput {
   title: string;
   baseRef?: string;
   branchName?: string;
+  /** Explicitly materialize lockfile-backed Node dependencies in this isolated worktree. */
+  prepareDependencies?: boolean;
+}
+
+export interface ManagedWorkspaceDependencyBootstrap {
+  packageManager: 'bun' | 'pnpm' | 'npm' | 'yarn';
+  lockfile: string;
+  command: string[];
+}
+
+export interface ManagedWorkspaceDependencyPreparation {
+  mode: 'already_ready' | 'canonical_reuse' | 'installed';
+  nodeModulesRoot: string;
+  canonicalRoot?: string;
+}
+
+export interface ManagedWorkspaceDependencies {
+  materializeDependencies?: (workspaceRoot: string) => void;
 }
 
 export interface ManagedWorkspace {
@@ -73,6 +92,180 @@ function assertBranch(root: string, branch: string): string {
   return normalized;
 }
 
+export function managedWorkspaceDependencyBootstrap(repoRoot: string): ManagedWorkspaceDependencyBootstrap | undefined {
+  if (!existsSync(join(repoRoot, 'package.json')) || existsSync(join(repoRoot, 'node_modules'))) return undefined;
+  const lockCandidates = [
+    ['bun', 'bun.lock', ['bun', 'install', '--frozen-lockfile']],
+    ['bun', 'bun.lockb', ['bun', 'install', '--frozen-lockfile']],
+    ['pnpm', 'pnpm-lock.yaml', ['pnpm', 'install', '--frozen-lockfile']],
+    ['npm', 'package-lock.json', ['npm', 'ci']],
+    ['yarn', 'yarn.lock', ['yarn', 'install', '--frozen-lockfile']],
+  ] as const;
+  const detected = lockCandidates.find(([, lockfile]) => existsSync(join(repoRoot, lockfile)));
+  if (!detected) return undefined;
+  return { packageManager: detected[0], lockfile: detected[1], command: [...detected[2]] };
+}
+
+const DEPENDENCY_REUSE_CONFIG_PATHS = [
+  '.npmrc',
+  'bunfig.toml',
+  'pnpm-workspace.yaml',
+  '.yarnrc.yml',
+] as const;
+
+function dependencyInputMatches(leftRoot: string, rightRoot: string, path: string): boolean {
+  const left = join(leftRoot, path);
+  const right = join(rightRoot, path);
+  const leftExists = existsSync(left);
+  const rightExists = existsSync(right);
+  if (leftExists !== rightExists) return false;
+  return !leftExists || readFileSync(left).equals(readFileSync(right));
+}
+
+function linkedWorkspaceCanonicalRoot(repoRoot: string): string | undefined {
+  const common = runProcess(resolveGitExecutable(), ['-C', repoRoot, 'rev-parse', '--path-format=absolute', '--git-common-dir'], {
+    timeoutMs: 15_000,
+    maxOutputBytes: 8 * 1024,
+  });
+  if (!common.ok || !common.stdout.trim()) return undefined;
+  const canonicalRoot = dirname(resolve(common.stdout.trim()));
+  if (!existsSync(canonicalRoot)) return undefined;
+  try {
+    if (realpathSync(canonicalRoot) === realpathSync(repoRoot)) return undefined;
+  } catch {
+    return undefined;
+  }
+  const topLevel = runProcess(resolveGitExecutable(), ['-C', canonicalRoot, 'rev-parse', '--show-toplevel'], {
+    timeoutMs: 15_000,
+    maxOutputBytes: 8 * 1024,
+  });
+  if (!topLevel.ok || !topLevel.stdout.trim()) return undefined;
+  try {
+    return realpathSync(topLevel.stdout.trim()) === realpathSync(canonicalRoot) ? canonicalRoot : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function resolveManagedWorkspaceCanonicalDependencies(repoRoot: string): {
+  canonicalRoot: string;
+  nodeModulesRoot: string;
+} | undefined {
+  const bootstrap = managedWorkspaceDependencyBootstrap(repoRoot);
+  if (!bootstrap) return undefined;
+  const canonicalRoot = linkedWorkspaceCanonicalRoot(repoRoot);
+  if (!canonicalRoot) return undefined;
+  const nodeModulesRoot = join(canonicalRoot, 'node_modules');
+  if (!existsSync(nodeModulesRoot)) return undefined;
+  const dependencyInputs = ['package.json', bootstrap.lockfile, ...DEPENDENCY_REUSE_CONFIG_PATHS];
+  if (!dependencyInputs.every((path) => dependencyInputMatches(repoRoot, canonicalRoot, path))) return undefined;
+  return { canonicalRoot, nodeModulesRoot: realpathSync(nodeModulesRoot) };
+}
+
+function packageManifestRequiresDependencyMaterialization(repoRoot: string): boolean {
+  const packagePath = join(repoRoot, 'package.json');
+  if (!existsSync(packagePath)) return false;
+  let manifest: Record<string, unknown>;
+  try {
+    const parsed = JSON.parse(readFileSync(packagePath, 'utf8')) as unknown;
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return true;
+    manifest = parsed as Record<string, unknown>;
+  } catch {
+    // Preserve fail-closed dependency preparation for malformed manifests. The
+    // package manager remains the authority for the concrete parse error once a
+    // supported frozen lockfile is present.
+    return true;
+  }
+
+  const dependencyFields = [
+    'dependencies',
+    'devDependencies',
+    'optionalDependencies',
+    'peerDependencies',
+    'bundleDependencies',
+    'bundledDependencies',
+  ] as const;
+  if (dependencyFields.some((field) => {
+    const value = manifest[field];
+    return Array.isArray(value)
+      ? value.length > 0
+      : Boolean(value && typeof value === 'object' && Object.keys(value as Record<string, unknown>).length > 0);
+  })) return true;
+
+  const workspaces = manifest.workspaces;
+  if (Array.isArray(workspaces)) return workspaces.length > 0;
+  if (workspaces && typeof workspaces === 'object') {
+    const packages = (workspaces as Record<string, unknown>).packages;
+    if (Array.isArray(packages)) return packages.length > 0;
+    return Object.keys(workspaces as Record<string, unknown>).length > 0;
+  }
+  return false;
+}
+
+function reuseManagedWorkspaceCanonicalDependencies(repoRoot: string): ManagedWorkspaceDependencyPreparation | undefined {
+  const nodeModulesRoot = join(repoRoot, 'node_modules');
+  const reusable = resolveManagedWorkspaceCanonicalDependencies(repoRoot);
+  if (!reusable) return undefined;
+  try {
+    symlinkSync(reusable.nodeModulesRoot, nodeModulesRoot, process.platform === 'win32' ? 'junction' : 'dir');
+  } catch (error) {
+    if (!existsSync(nodeModulesRoot)) {
+      const detail = error instanceof Error ? error.message : String(error);
+      throw new Error(`MANAGED_WORKSPACE_DEPENDENCY_REUSE_FAILED: ${detail}`);
+    }
+  }
+  return {
+    mode: 'canonical_reuse',
+    nodeModulesRoot: realpathSync(nodeModulesRoot),
+    canonicalRoot: reusable.canonicalRoot,
+  };
+}
+
+export function materializeManagedWorkspaceDependencies(repoRoot: string): ManagedWorkspaceDependencyPreparation | undefined {
+  if (!existsSync(join(repoRoot, 'package.json'))) return undefined;
+  const nodeModulesRoot = join(repoRoot, 'node_modules');
+  if (existsSync(nodeModulesRoot)) {
+    return { mode: 'already_ready', nodeModulesRoot: realpathSync(nodeModulesRoot) };
+  }
+  // A linked worktree may safely reuse canonical dependencies even when the
+  // package manifest itself declares no dependencies. The supported lockfile
+  // and dependency-reuse inputs remain the authority for proving equivalence.
+  const reused = reuseManagedWorkspaceCanonicalDependencies(repoRoot);
+  if (reused) return reused;
+  // A package manifest can define dependency-free scripts (for example a
+  // built-in `node -e` check). Such checks do not need node_modules and must not
+  // be rejected merely because the repository intentionally has no lockfile.
+  if (!packageManifestRequiresDependencyMaterialization(repoRoot)) return undefined;
+  const bootstrap = managedWorkspaceDependencyBootstrap(repoRoot);
+  if (!bootstrap) {
+    throw new Error('MANAGED_WORKSPACE_DEPENDENCY_LOCK_REQUIRED: package.json declares dependencies but no supported lockfile was found');
+  }
+  const childEnv = repositoryChildProcessEnvironment();
+  const executable = bootstrap.packageManager === 'bun'
+    ? resolveBunExecutable(process.execPath, childEnv)
+    : bootstrap.command[0]!;
+  const result = runProcess(executable, bootstrap.command.slice(1), {
+    cwd: repoRoot,
+    env: childEnv,
+    timeoutMs: 10 * 60_000,
+    maxOutputBytes: 4 * 1024 * 1024,
+  });
+  if (!result.ok) {
+    const detail = result.stderr || result.error || `exit ${result.status}`;
+    throw new Error(`MANAGED_WORKSPACE_DEPENDENCY_INSTALL_FAILED: ${bootstrap.command.join(' ')}: ${detail}`);
+  }
+  if (!existsSync(nodeModulesRoot)) {
+    throw new Error(`MANAGED_WORKSPACE_DEPENDENCY_INSTALL_INCOMPLETE: ${bootstrap.command.join(' ')} completed without node_modules`);
+  }
+  return { mode: 'installed', nodeModulesRoot: realpathSync(nodeModulesRoot) };
+}
+
+export function materializeManagedWorkspaceCheckDependencies(repoRoot: string): ManagedWorkspaceDependencyPreparation | undefined {
+  if (!existsSync(join(repoRoot, 'package.json')) || existsSync(join(repoRoot, 'node_modules'))) return undefined;
+  if (!linkedWorkspaceCanonicalRoot(repoRoot)) return undefined;
+  return materializeManagedWorkspaceDependencies(repoRoot);
+}
+
 function existingWorkspace(path: string, branch: string): boolean {
   if (!existsSync(path)) return false;
   const root = runProcess(resolveGitExecutable(), ['-C', path, 'rev-parse', '--show-toplevel'], {
@@ -109,6 +302,7 @@ export function ensureManagedWorkspace(
   controllerHome: string,
   repository: RepositoryRecord,
   input: EnsureManagedWorkspaceInput,
+  dependencies: ManagedWorkspaceDependencies = {},
 ): ManagedWorkspace {
   const requestId = input.requestId.trim();
   if (!requestId) throw new Error('MANAGED_WORKSPACE_REQUEST_ID_REQUIRED');
@@ -159,6 +353,14 @@ export function ensureManagedWorkspace(
       if (!repositoryCheckoutRootMatches(repository, path)) {
         throw new Error(`MANAGED_WORKSPACE_REPOSITORY_MISMATCH: ${path}`);
       }
+      if (input.prepareDependencies === true) {
+        (dependencies.materializeDependencies ?? materializeManagedWorkspaceDependencies)(path);
+      } else {
+        // Reusing a byte-equivalent canonical dependency tree is cheap and
+        // deterministic, so isolated Work checkouts should get it even when a
+        // full package-manager install was not explicitly requested.
+        reuseManagedWorkspaceCanonicalDependencies(path);
+      }
 
       const record = addRepositoryCheckout({
         repoId: repository.repoId,