imprint-mcp 0.6.4 → 0.6.5

package/README.md

@@ -93,6 +93,11 @@ regenerate/record it with `bun scripts/demo-teach.ts`.)*
 > [!TIP]
 > All three steps happen in a single `imprint teach` command. Credentials and PII are redacted automatically before anything reaches the LLM.
 
+When one recording yields multiple tools, all candidates are selected by default.
+Imprint automatically includes upstream lookup/producer tools required by any
+selected downstream tool. Use `--primary-tool` to compile only the primary tool
+and its prerequisites; `--all-tools` makes the default full-set selection explicit.
+
 The recorder also has a bounded fallback for Next.js React Server Component
 responses that Chromium evicts before `Network.getResponseBody` can read them.
 It streams only narrowly identified GET navigation/prefetch and POST Server

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "imprint-mcp",
-  "version": "0.6.4",
+  "version": "0.6.5",
   "description": "Teach an AI agent how to use any website. Once. Records a real browser session + narration; generates a deterministic MCP tool plus a DOM-replay playbook fallback.",
   "type": "module",
   "exports": {

package/src/cli.ts

@@ -40,6 +40,45 @@ export function parseDuration(dur: string): number | null {
   return num;
 }
 
+export type TeachSelectionMode =
+  | 'tool'
+  | 'primary'
+  | 'all-explicit'
+  | 'all-default'
+  | 'interactive-default-all';
+
+/** Pure CLI selection-mode resolver shared by validation and telemetry. */
+export function resolveTeachSelectionMode(opts: {
+  tool?: string;
+  primaryTool?: boolean;
+  allTools?: boolean;
+  noInteractive?: boolean;
+}): { mode: TeachSelectionMode; error?: string } {
+  if (opts.tool && opts.allTools) {
+    return { mode: 'tool', error: 'error: --tool cannot be combined with --all-tools' };
+  }
+  if (opts.tool && opts.primaryTool) {
+    return { mode: 'tool', error: 'error: --tool cannot be combined with --primary-tool' };
+  }
+  if (opts.allTools && opts.primaryTool) {
+    return {
+      mode: 'primary',
+      error: 'error: --all-tools cannot be combined with --primary-tool',
+    };
+  }
+  return {
+    mode: opts.tool
+      ? 'tool'
+      : opts.primaryTool
+        ? 'primary'
+        : opts.allTools
+          ? 'all-explicit'
+          : opts.noInteractive
+            ? 'all-default'
+            : 'interactive-default-all',
+  };
+}
+
 const HELP = `imprint v${VERSION} — teach an AI agent to use any website. Once.
 
 USAGE
@@ -112,7 +151,7 @@ export const VERB_HELP: Record<string, VerbHelp> = {
     summary:
       'Record a workflow, compile both artifacts, emit the tool, and connect to your AI platform — all in one interactive flow. Supports resuming incomplete runs and multiple workflows per site.',
     usage: [
-      'imprint teach <site> [--url <url>] [--from-session <path>] [--persist-profile] [--no-interactive] [--all-tools] [--tool <toolName>] [--provider <name>] [--model <name>] [--timeout <duration>] [--keep-test] [--skip-replay] [--from-step <step>] [--to-step <step>] [--only <step>]',
+      'imprint teach <site> [--url <url>] [--from-session <path>] [--persist-profile] [--no-interactive] [--primary-tool | --all-tools] [--tool <toolName>] [--provider <name>] [--model <name>] [--timeout <duration>] [--keep-test] [--skip-replay] [--from-step <step>] [--to-step <step>] [--only <step>]',
     ],
     flags: [
       { name: '--url <url>', description: 'Starting URL (else about:blank).' },
@@ -123,13 +162,15 @@ export const VERB_HELP: Record<string, VerbHelp> = {
       { name: '--persist-profile', description: 'Reuse a stable Chrome profile for this site.' },
       {
         name: '--no-interactive',
-        description:
-          'Run without prompts; compile the primary detected tool and print integration snippets.',
+        description: 'Run without prompts; compile all detected tools by default.',
       },
       {
         name: '--all-tools',
-        description:
-          'With --no-interactive, compile every detected candidate tool instead of only the primary.',
+        description: 'Explicitly compile all detected tools (the default).',
+      },
+      {
+        name: '--primary-tool',
+        description: 'Compile only the primary detected tool and its upstream dependencies.',
       },
       {
         name: '--tool <toolName>',
@@ -1423,6 +1464,7 @@ async function main(argv: string[]): Promise<number> {
           'persist-profile': { type: 'boolean' },
           'no-interactive': { type: 'boolean' },
           'all-tools': { type: 'boolean' },
+          'primary-tool': { type: 'boolean' },
           tool: { type: 'string' },
           provider: { type: 'string' },
           model: { type: 'string' },
@@ -1464,8 +1506,14 @@ async function main(argv: string[]): Promise<number> {
           return 2;
         }
       }
-      if (values.tool && values['all-tools']) {
-        console.error('error: --tool cannot be combined with --all-tools');
+      const selection = resolveTeachSelectionMode({
+        tool: values.tool,
+        primaryTool: values['primary-tool'],
+        allTools: values['all-tools'],
+        noInteractive: values['no-interactive'],
+      });
+      if (selection.error) {
+        console.error(selection.error);
         return 2;
       }
 
@@ -1500,6 +1548,7 @@ async function main(argv: string[]): Promise<number> {
       const ctrl = new AbortController();
       const onSigint = (): void => ctrl.abort();
       process.once('SIGINT', onSigint);
+      const teachSelectionMode = selection.mode;
 
       try {
         const { teach } = await import('./imprint/teach.ts');
@@ -1513,7 +1562,10 @@ async function main(argv: string[]): Promise<number> {
             'imprint.provider': values.provider ?? 'auto',
             'imprint.model': values.model ?? 'auto',
             'imprint.timeout_ms': teachTimeoutMs ?? 'default',
-            'imprint.all_tools': values['all-tools'] ?? false,
+            'imprint.all_tools':
+              teachSelectionMode === 'all-explicit' || teachSelectionMode === 'all-default',
+            'imprint.selection_mode': teachSelectionMode,
+            'imprint.primary_tool': values['primary-tool'] ?? false,
             'imprint.tool': values.tool,
             'imprint.no_interactive': values['no-interactive'] ?? false,
             'imprint.skip_replay': values['skip-replay'] ?? false,
@@ -1530,7 +1582,7 @@ async function main(argv: string[]): Promise<number> {
               model: values.model,
               maxDurationMs: teachTimeoutMs,
               keepTest: values['keep-test'] || process.env.IMPRINT_KEEP_TEST === '1',
-              allTools: values['all-tools'],
+              primaryTool: values['primary-tool'],
               tool: values.tool,
               skipReplay: values['skip-replay'],
               fromStep: fromStepArg,

package/src/imprint/teach-state.ts

@@ -33,6 +33,7 @@ import {
   type SharedCompileContext,
   SharedCompileContextSchema,
   type ToolCandidate,
+  closeCandidateSelection,
 } from './tool-candidates.ts';
 
 export const TEACH_STEPS = [
@@ -55,6 +56,8 @@ export interface WorkflowState {
   redactedPath?: string;
   triagedPath?: string;
   classificationsPath?: string;
+  /** Hash of the replay classification payload used for candidate/build planning. */
+  classificationsHash?: string;
   completedSteps: TeachStep[];
   error?: string;
   startedAt: string;
@@ -90,6 +93,94 @@ export interface TeachState {
   workflows: Record<string, WorkflowState>;
 }
 
+/** Candidate-backed resumes must reconstruct the persisted tool set so a
+ * downstream tool is never resumed without its upstream dependencies. */
+export function isCandidateBackedResume(
+  ws: WorkflowState | undefined,
+): ws is WorkflowState & { candidate: ToolCandidate } {
+  return ws?.candidate !== undefined;
+}
+
+/** Only a fresh detection run supersedes existing tools. A resume may
+ * intentionally exclude tools from another recording or an earlier phase. */
+export function staleCompletedToolsForRun(
+  completedToolNames: readonly string[],
+  incomingToolNames: ReadonlySet<string>,
+  cleanupStaleTools: boolean,
+): string[] {
+  return cleanupStaleTools ? completedToolNames.filter((name) => !incomingToolNames.has(name)) : [];
+}
+
+/** Resolve behavior from the actual run chosen by the CLI/TUI, rather than from
+ * the presence of a CLI flag. Interactive Continue/Redo must follow the same
+ * resume semantics as an explicit `--from-step`. */
+export function resolvedTeachRunPolicy(startFrom: TeachStep, resumesExistingRun: boolean) {
+  return {
+    cleanupStaleTools: !resumesExistingRun,
+    reuseExistingBuildPlan: startFrom !== 'plan-prereqs',
+    reviseExistingArtifacts: resumesExistingRun,
+  };
+}
+
+function candidatePlanningSignature(candidate: ToolCandidate): string {
+  return JSON.stringify(candidate);
+}
+
+/** Whether re-detection changed the candidate set or any planning-relevant
+ * candidate evidence for this recording. A changed graph invalidates prior
+ * plan-prereqs/compile progress even when candidate names stayed the same. */
+export function candidateSelectionChanged(
+  state: TeachState,
+  sessionPath: string,
+  selected: ToolCandidate[],
+  sharedContext?: SharedCompileContext,
+  classificationsHash?: string,
+): boolean {
+  const priorWorkflows = Object.values(state.workflows).filter(
+    (workflow) => workflow.sessionPath === sessionPath && workflow.candidate,
+  );
+  if (priorWorkflows.length === 0) return false;
+  const prior = priorWorkflows.map((workflow) => workflow.candidate as ToolCandidate);
+  const signatures = (candidates: ToolCandidate[]): string[] =>
+    candidates.map(candidatePlanningSignature).sort();
+  if (JSON.stringify(signatures(prior)) !== JSON.stringify(signatures(selected))) return true;
+  const priorContexts = new Set(
+    priorWorkflows.map((workflow) => JSON.stringify(workflow.sharedContext ?? null)),
+  );
+  if (priorContexts.size !== 1 || !priorContexts.has(JSON.stringify(sharedContext ?? null))) {
+    return true;
+  }
+  const priorClassificationHashes = new Set(
+    priorWorkflows.map((workflow) => workflow.classificationsHash ?? null),
+  );
+  return (
+    priorClassificationHashes.size !== 1 ||
+    !priorClassificationHashes.has(classificationsHash ?? null)
+  );
+}
+
+/** Remove obsolete candidate state for one recording after a new selection is
+ * finalized. Other recordings and pending placeholders remain untouched. */
+export function pruneUnselectedCandidateWorkflows(
+  state: TeachState,
+  sessionPath: string,
+  selectedToolNames: ReadonlySet<string>,
+): string[] {
+  const removed: string[] = [];
+  for (const [key, workflow] of Object.entries(state.workflows)) {
+    if (
+      workflow.sessionPath !== sessionPath ||
+      !workflow.candidate ||
+      selectedToolNames.has(workflow.candidate.toolName)
+    ) {
+      continue;
+    }
+    delete state.workflows[key];
+    removed.push(key);
+  }
+  return removed;
+}
+
 export function teachStatePath(site: string): string {
   return pathJoin(localSiteDir(site), '.teach-state.json');
 }
@@ -106,9 +197,10 @@ export function loadTeachState(site: string): TeachState {
   try {
     const state = JSON.parse(readFileSync(loadPath, 'utf8')) as TeachState;
     for (const workflow of Object.values(state.workflows)) {
-      if (!workflow.sharedContext) continue;
-      const parsed = SharedCompileContextSchema.safeParse(workflow.sharedContext);
-      workflow.sharedContext = parsed.success ? parsed.data : undefined;
+      if (workflow.sharedContext) {
+        const parsed = SharedCompileContextSchema.safeParse(workflow.sharedContext);
+        workflow.sharedContext = parsed.success ? parsed.data : undefined;
+      }
     }
     return isLegacy ? normalizeLegacyTeachState(site, state) : state;
   } catch {
@@ -434,8 +526,8 @@ export function resolveStepStartTarget(
   return { workflowKey, ws };
 }
 
-/** A multi-tool `--from-step` resume reconstructs the prior run's tools from
- *  persisted state. Scope it to (a) tools from the SAME recording as the resume
+/** A candidate-backed resume reconstructs the prior run's tools from persisted
+ *  state. Scope it to (a) tools from the SAME recording as the resume
  *  target — cross-recording tools have a different session and would otherwise be
  *  compiled against the wrong one — and (b) tools whose prior run actually reached
  *  `fromStep`'s prerequisites — a tool that failed earlier has no
@@ -445,13 +537,14 @@ export function resolveStepStartTarget(
 interface MultiToolResumeSelection {
   plans: {
     workflowKey: string;
-    candidate: WorkflowState['candidate'];
+    candidate: ToolCandidate;
     sharedContext: WorkflowState['sharedContext'];
   }[];
   skipped: {
     workflowKey: string;
     reason: 'different-recording' | 'not-resumable' | 'not-in-build-plan';
   }[];
+  cycles: string[][];
 }
 
 export function selectMultiToolResumePlans(
@@ -459,13 +552,18 @@ export function selectMultiToolResumePlans(
   targetWorkflowKey: string,
   fromStep: TeachStep,
   opts?: {
-    noInteractive?: boolean;
-    allTools?: boolean;
+    primaryTool?: boolean;
     toolName?: string;
     plannedToolNames?: ReadonlySet<string>;
   },
 ): MultiToolResumeSelection {
   const target = state.workflows[targetWorkflowKey];
+  const persistedPrimary = Object.entries(state.workflows).find(
+    ([key, workflow]) =>
+      !key.startsWith('_pending_') &&
+      workflow.candidate?.primary &&
+      (!target || workflow.sessionPath === target.sessionPath),
+  );
   const plans: MultiToolResumeSelection['plans'] = [];
   const skipped: MultiToolResumeSelection['skipped'] = [];
   for (const [key, ws] of Object.entries(state.workflows)) {
@@ -484,6 +582,34 @@ export function selectMultiToolResumePlans(
     }
     plans.push({ workflowKey: key, candidate: ws.candidate, sharedContext: ws.sharedContext });
   }
+  if (target?.candidate && !plans.some((plan) => plan.workflowKey === targetWorkflowKey)) {
+    const reason = skipped.find((entry) => entry.workflowKey === targetWorkflowKey)?.reason;
+    throw new Error(
+      `Cannot resume tool "${target.candidate.toolName}" from "${fromStep}": the target is ${reason ?? 'unavailable'}. Resume an earlier step or re-run from "detect-candidates".`,
+    );
+  }
+  const closePlans = (rootNames: string[]): Pick<MultiToolResumeSelection, 'plans' | 'cycles'> => {
+    const candidatePlans = plans;
+    const closure = closeCandidateSelection(
+      candidatePlans.map((plan) => plan.candidate),
+      rootNames,
+    );
+    const selectedNames = new Set(closure.selected.map((candidate) => candidate.toolName));
+    const eligibleNames = new Set(candidatePlans.map((plan) => plan.candidate.toolName));
+    for (const candidate of closure.selected) {
+      for (const dependency of candidate.dependsOnTools) {
+        if (eligibleNames.has(dependency)) continue;
+        throw new Error(
+          `Cannot resume tool "${candidate.toolName}" from "${fromStep}": required upstream tool "${dependency}" is unavailable. Re-run from "detect-candidates" to rebuild a complete tool set.`,
+        );
+      }
+    }
+    return {
+      plans: plans.filter((plan) => selectedNames.has(plan.candidate.toolName)),
+      cycles: closure.cycles,
+    };
+  };
+
   if (opts?.toolName) {
     const selected = plans.find(
       (plan) => plan.workflowKey === opts.toolName || plan.candidate?.toolName === opts.toolName,
@@ -493,14 +619,30 @@ export function selectMultiToolResumePlans(
         `Cannot resume tool "${opts.toolName}": it is not resumable from "${fromStep}" in the selected recording.`,
       );
     }
-    return { plans: [selected], skipped };
+    return { ...closePlans([selected.candidate.toolName]), skipped };
   }
-  if (opts?.noInteractive && !opts.allTools && plans.length > 1) {
-    const primary = plans.find((plan) => plan.candidate?.primary);
-    const selected = primary ?? plans.find((plan) => plan.workflowKey === targetWorkflowKey);
-    return { plans: selected ? [selected] : [], skipped };
+  if (opts?.primaryTool) {
+    if (!persistedPrimary) {
+      throw new Error(
+        `Cannot resume from "${fromStep}" with --primary-tool: the selected recording has no primary candidate. Re-run from "detect-candidates".`,
+      );
+    }
+    const primary = plans.find((plan) => plan.workflowKey === persistedPrimary[0]);
+    if (!primary) {
+      const reason = skipped.find((entry) => entry.workflowKey === persistedPrimary[0])?.reason;
+      throw new Error(
+        `Cannot resume primary tool "${persistedPrimary[1].candidate?.toolName ?? persistedPrimary[0]}" from "${fromStep}": it is ${reason ?? 'unavailable'}. Resume an earlier step or re-run from "detect-candidates".`,
+      );
+    }
+    return {
+      ...closePlans([primary.candidate.toolName]),
+      skipped,
+    };
   }
-  return { plans, skipped };
+  return {
+    ...closePlans(plans.map((plan) => plan.candidate.toolName)),
+    skipped,
+  };
 }
 
 /** True when the `[startIdx, stopIdx]` phase window overlaps the atomic analysis

package/src/imprint/teach.ts

@@ -23,6 +23,7 @@ import { authWorkflowHash } from './auth-compile-tools.ts';
 import {
   type SharedModuleManifestEntry,
   buildPlanSidecarPath,
+  deriveTokenContractHints,
   readBuildPlanFile,
   topoLevelsForTools,
 } from './build-plan.ts';
@@ -95,26 +96,34 @@ import {
   type WorkflowState,
   analysisBlockRunsForWindow,
   buildTeachStateFromSession,
+  candidateSelectionChanged,
   detectCandidatesCompletedSteps,
   discoverCompletedWorkflows,
   discoverOrphanSession,
   friendlySessionTimestamp,
+  isCandidateBackedResume,
   isExistingTeachFile as isExistingFile,
   loadTeachState,
   nextTeachStep as nextStep,
   pruneStalePendingTeachWorkflows,
+  pruneUnselectedCandidateWorkflows,
   resolveStepStartTarget,
   resolveTeachStatePath,
   resolveWorkflowTriagedPath,
+  resolvedTeachRunPolicy,
   saveTeachState,
   selectMultiToolResumePlans,
+  staleCompletedToolsForRun,
   toRelativeTeachStatePath as toRelative,
 } from './teach-state.ts';
 import {
   type SharedCompileContext,
   type ToolCandidate,
   buildSharedCompileContext as buildCandidateSharedCompileContext,
+  closeCandidateSelection,
+  deriveStructuralCandidateDependencies,
   detectToolCandidates,
+  mergeCandidateDependencies,
   primaryToolCandidate,
   sharedContextHasAuth,
 } from './tool-candidates.ts';
@@ -178,6 +187,40 @@ function fileSha256(path: string): string {
   return createHash('sha256').update(readFileSync(path)).digest('hex');
 }
 
+/** Read replay classifications only when the sidecar belongs to the exact
+ * recording being compiled. Request seq numbers are recording-local, so using
+ * a site-global cache from another recording could fabricate dependency edges. */
+export function loadCachedClassificationsForSession(
+  classPath: string,
+  sessionPath: string,
+): ClassifiedValue[] | undefined {
+  if (!existsSync(classPath) || !existsSync(sessionPath)) return undefined;
+  try {
+    const cached = JSON.parse(readFileSync(classPath, 'utf8')) as {
+      sourceSessionHash?: string;
+      classifications?: ClassifiedValue[];
+    };
+    if (
+      !cached.sourceSessionHash ||
+      cached.sourceSessionHash !== fileSha256(sessionPath) ||
+      !Array.isArray(cached.classifications)
+    ) {
+      return undefined;
+    }
+    return cached.classifications;
+  } catch {
+    return undefined;
+  }
+}
+
+function classificationsPlanningHash(
+  classifications: ClassifiedValue[] | undefined,
+): string | undefined {
+  return classifications
+    ? createHash('sha256').update(JSON.stringify(classifications)).digest('hex')
+    : undefined;
+}
+
 export {
   buildTeachStateFromSession,
   resolveTeachStatePath,
@@ -227,8 +270,8 @@ interface TeachOptions {
   fromSession?: string;
   /** Retain parser.test.ts after successful compile-agent verification. */
   keepTest?: boolean;
-  /** Non-interactive: compile every detected candidate instead of primary only. */
-  allTools?: boolean;
+  /** Compile only the primary detected candidate and its upstream dependencies. */
+  primaryTool?: boolean;
   /** Bounded resume: compile exactly one persisted candidate from the retained recording. */
   tool?: string;
   /** Skip the replay-and-diff stage entirely. */
@@ -518,6 +561,7 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
   let redactedPath: string | null = null;
   let resumedTriagedPath: string | null = null;
   let usingFromSession = false;
+  let resumesExistingRun = false;
 
   const hasExisting = completedWorkflows.length > 0 || incompleteWorkflows.length > 0;
 
@@ -534,6 +578,7 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
     // run's persisted outputs. resolveStepStartTarget picks the most-recent
     // workflow and THROWS if it didn't reach far enough (the dependency guard).
     const target = resolveStepStartTarget(site, state, opts.fromStep, opts.tool);
+    resumesExistingRun = true;
     workflowKey = target.workflowKey;
     startFrom = opts.fromStep;
     sessionPath = resolveTeachStatePath(site, target.ws.sessionPath);
@@ -571,6 +616,7 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
     if (choice.action === 'new') {
       startFrom = 'record';
     } else if (choice.action === 'continue') {
+      resumesExistingRun = true;
       workflowKey = choice.workflowKey;
       const ws = state.workflows[workflowKey];
       if (!ws) {
@@ -584,6 +630,7 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
     } else if (choice.action === 'redo') {
       workflowKey = choice.workflowKey;
       startFrom = choice.fromStep;
+      resumesExistingRun = startFrom !== 'record';
       const ws = state.workflows[workflowKey];
       if (ws) {
         sessionPath = resolveTeachStatePath(site, ws.sessionPath);
@@ -614,6 +661,7 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
   }
 
   const startIdx = STEPS.indexOf(startFrom);
+  const runPolicy = resolvedTeachRunPolicy(startFrom, resumesExistingRun);
   // Upper bound of the phase window: `--to-step`/`--only` stop the chain after a
   // given step (default = the last step, i.e. run to the end). A phase runs only
   // when it falls within [startFrom, toStep].
@@ -912,6 +960,7 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
   if (stopIdx < STEPS.indexOf('replay-and-diff')) await finishEarly();
 
   let plans: CandidateCompilePlan[];
+  let candidateBackedResume = false;
 
   // The replay→triage→detect-candidates analysis is one atomic block (the sub-
   // steps share a parallel run + the triaged session), so the window can START
@@ -959,24 +1008,30 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
       const replayPromise = (async () => {
         if (!needsReplay) {
           const classPath = pathJoin(localSiteDir(site), '.classifications.json');
-          if (existsSync(classPath)) {
-            try {
-              return JSON.parse(readFileSync(classPath, 'utf8'))
-                .classifications as ClassifiedValue[];
-            } catch {
-              /* proceed without */
-            }
+          const cached = loadCachedClassificationsForSession(classPath, replaySessionPath);
+          if (!cached && existsSync(classPath)) {
+            p.log.warn(
+              'Ignoring cached replay classifications because they are untagged or belong to a different recording.',
+            );
           }
-          return undefined;
+          return cached;
         }
         return siteReplayAndDiff(site, replaySessionPath, mp);
       })();
 
       // Branch B: triage → detect-candidates → user selection (fast, ~30s)
-      type CandidateChainResult = {
-        triageResult?: TriageResult;
-        plans: CandidateCompilePlan[];
-      };
+      type CandidateChainResult =
+        | {
+            triageResult?: TriageResult;
+            plans: CandidateCompilePlan[];
+          }
+        | {
+            triageResult?: TriageResult;
+            detection: Awaited<ReturnType<typeof detectTeachCandidates>>;
+            preliminarySelected: ToolCandidate[];
+            baseState: WorkflowState;
+            pendingKey: string | null;
+          };
       const candidatePromise = (async (): Promise<CandidateChainResult> => {
         if (!needsCandidates) {
           const ws = state.workflows[workflowKey];
@@ -1065,12 +1120,16 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
         mp.pause();
         mp.clear();
         spinner.start('Detecting candidate tools');
-        const detection = await detectTeachCandidates({
+        const detected = await detectTeachCandidates({
           sessionPath: compileSessionPath,
           providerName,
           model,
           trustSessionScope: !!localTriagedPath,
         });
+        const detection = {
+          ...detected,
+          candidates: deriveStructuralCandidateDependencies(detected.candidates),
+        };
         spinner.stop(
           `Detected ${detection.candidates.length} candidate tool${detection.candidates.length === 1 ? '' : 's'}.`,
         );
@@ -1079,8 +1138,6 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
         const selected = await selectTeachCandidates(detection, opts);
         mp.resume();
 
-        const sharedContext = buildCandidateSharedCompileContext(detection, selected);
-
         // ── Credential prompt (deferred until here so the LLM decides which login succeeded) ──
         const llmLoginSeqs = new Set(detection.sharedContext?.loginRequestSeqs ?? []);
         if (credentialFindings.length > 0 && llmLoginSeqs.size > 0) {
@@ -1147,48 +1204,17 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
         if (localTriagedPath) {
           baseState.triagedPath = toRelative(site, localTriagedPath);
         }
-        const candidatePlans = selected.map((candidate) => {
-          checkpoint(site, state, candidate.toolName, {
-            ...baseState,
-            // Preserve prior progress only when re-detecting the SAME recording, so
-            // a re-run of the analysis block (`--from-step`/`--only detect-candidates`,
-            // or interactive redo) doesn't regress a tool that already reached
-            // generate…register (which would break a later `--from-step register`).
-            // A fresh / different recording producing the same toolName must NOT
-            // inherit the old `plan-prereqs` marker, or the alreadyPlanned shortcut
-            // below would skip re-planning and compile against the previous
-            // recording's `_shared/` modules — detectCandidatesCompletedSteps gates
-            // on the recording's sessionPath.
-            completedSteps: detectCandidatesCompletedSteps(
-              state.workflows[candidate.toolName],
-              baseState.sessionPath,
-            ),
-            candidate,
-            sharedContext,
-          });
-          return {
-            workflowKey: candidate.toolName,
-            startFrom: 'generate' as Step,
-            candidate,
-            sharedContext,
-          };
-        });
-
-        if (pendingKey && state.workflows[pendingKey]) {
-          delete state.workflows[pendingKey];
-          saveTeachState(site, state);
-        }
-
         return {
           triageResult: localTriageResult,
-          plans: candidatePlans,
+          detection,
+          preliminarySelected: selected,
+          baseState,
+          pendingKey,
         };
       })();
 
       // Wait for candidate chain (includes user interaction)
       const candidateResult = await candidatePromise;
-      plans = candidateResult.plans;
-
       triageResult = candidateResult.triageResult;
 
       // Wait for replay — may already be done, or show progress while waiting
@@ -1213,6 +1239,70 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
 
       mp.clear();
 
+      if ('plans' in candidateResult) {
+        plans = candidateResult.plans;
+      } else {
+        const finalizedSelection = finalizeTeachCandidateSelection(
+          candidateResult.detection.candidates,
+          candidateResult.preliminarySelected.map((candidate) => candidate.toolName),
+          siteClassifications,
+        );
+        const candidates = finalizedSelection.candidates;
+        const finalDetection = { ...candidateResult.detection, candidates };
+        const notice = formatTeachCandidateAutoAddNotice(finalizedSelection.autoAdded, 'replay');
+        if (notice) p.note(notice.body, notice.title);
+        for (const cycle of finalizedSelection.cycles) {
+          p.log.warn(`Tool dependency cycle detected: ${cycle.join(' → ')}`);
+        }
+
+        const sharedContext = buildCandidateSharedCompileContext(
+          finalDetection,
+          finalizedSelection.selected,
+        );
+        const classificationsHash = classificationsPlanningHash(siteClassifications);
+        const selectedNames = new Set(
+          finalizedSelection.selected.map((candidate) => candidate.toolName),
+        );
+        const selectionChanged = candidateSelectionChanged(
+          state,
+          candidateResult.baseState.sessionPath,
+          finalizedSelection.selected,
+          sharedContext,
+          classificationsHash,
+        );
+        pruneUnselectedCandidateWorkflows(
+          state,
+          candidateResult.baseState.sessionPath,
+          selectedNames,
+        );
+        plans = finalizedSelection.selected.map((candidate) => {
+          checkpoint(site, state, candidate.toolName, {
+            ...candidateResult.baseState,
+            // Preserve prior progress only when re-detecting the SAME recording, so
+            // a re-run of the analysis block doesn't regress a tool that already
+            // reached generate…register. A different recording must not inherit the
+            // old plan-prereqs marker or shared-module build.
+            completedSteps: detectCandidatesCompletedSteps(
+              selectionChanged ? undefined : state.workflows[candidate.toolName],
+              candidateResult.baseState.sessionPath,
+            ),
+            candidate,
+            sharedContext,
+            classificationsHash,
+          });
+          return {
+            workflowKey: candidate.toolName,
+            startFrom: 'generate' as Step,
+            candidate,
+            sharedContext,
+          };
+        });
+        if (candidateResult.pendingKey && state.workflows[candidateResult.pendingKey]) {
+          delete state.workflows[candidateResult.pendingKey];
+          saveTeachState(site, state);
+        }
+      }
+
       // Checkpoints — write sequentially after both complete
       updateCandidateStageCheckpoints({
         site,
@@ -1233,12 +1323,8 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
   } else {
     // Resuming from generate or later — load cached data
     const classPath = pathJoin(localSiteDir(site), '.classifications.json');
-    if (existsSync(classPath)) {
-      try {
-        siteClassifications = JSON.parse(readFileSync(classPath, 'utf8')).classifications;
-      } catch {
-        /* proceed without */
-      }
+    if (redactedPath) {
+      siteClassifications = loadCachedClassificationsForSession(classPath, redactedPath);
     }
     const ws = state.workflows[workflowKey];
     const resolvedTriagedPath = resolveWorkflowTriagedPath(site, ws);
@@ -1252,17 +1338,18 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
         triagedPath: resolvedArtifactCheckpointPath(site, ws.triagedPath, resolvedTriagedPath),
       });
     }
-    // A `--from-step` resume into plan-prereqs/generate reconstructs the prior
-    // run's tools from persisted state (shared-module planning may need ≥2 tools).
-    // An explicit --all-tools or interactive resume keeps the full set; documented
-    // non-interactive behavior selects only the persisted primary candidate.
+    // A candidate-backed resume reconstructs the prior run's tools from persisted
+    // state (shared-module planning may need ≥2 tools). This applies both to an
+    // explicit `--from-step` and to the interactive Continue/Redo paths.
+    // Resume defaults to the full persisted set. --primary-tool narrows to the
+    // primary candidate plus its upstream dependency closure.
     // selectMultiToolResumePlans scopes reconstruction to the same recording as the
     // resume target and to tools that actually reached `startFrom`'s prerequisites,
     // so a sibling from a different run can't be compiled against the wrong session
-    // and one that failed earlier can't crash loading a missing artifact. Confined
-    // to --from-step so interactive resume keeps its single-tool behavior.
+    // and one that failed earlier can't crash loading a missing artifact.
+    candidateBackedResume = isCandidateBackedResume(ws);
     const allCandidatePlans: CandidateCompilePlan[] = [];
-    if (opts.fromStep) {
+    if (candidateBackedResume) {
       let plannedToolNames: Set<string> | undefined;
       const persistedBuildPlanPath = resolveTeachStatePath(site, ws?.buildPlanPath);
       if (persistedBuildPlanPath && existsSync(persistedBuildPlanPath)) {
@@ -1272,20 +1359,22 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
         }
       }
       const selection = selectMultiToolResumePlans(state, workflowKey, startFrom, {
-        noInteractive: opts.noInteractive,
-        allTools: opts.allTools,
+        primaryTool: opts.primaryTool,
         toolName: opts.tool,
         plannedToolNames,
       });
       for (const { workflowKey: skippedKey, reason } of selection.skipped) {
         p.log.warn(
           reason === 'different-recording'
-            ? `Skipping tool "${skippedKey}" for --from-step ${startFrom}: it belongs to a different recording than the resume target.`
+            ? `Skipping tool "${skippedKey}" while resuming from ${startFrom}: it belongs to a different recording than the resume target.`
             : reason === 'not-in-build-plan'
-              ? `Skipping tool "${skippedKey}" for --from-step ${startFrom}: it is not in the current build plan.`
-              : `Skipping tool "${skippedKey}" for --from-step ${startFrom}: its prior run didn't reach "${startFrom}" — resume an earlier step or re-run it.`,
+              ? `Skipping tool "${skippedKey}" while resuming from ${startFrom}: it is not in the current build plan.`
+              : `Skipping tool "${skippedKey}" while resuming from ${startFrom}: its prior run didn't reach "${startFrom}" — resume an earlier step or re-run it.`,
         );
       }
+      for (const cycle of selection.cycles) {
+        p.log.warn(`Tool dependency cycle detected: ${cycle.join(' → ')}`);
+      }
       for (const sel of selection.plans) {
         allCandidatePlans.push({
           workflowKey: sel.workflowKey,
@@ -1295,10 +1384,14 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
         });
       }
     }
-    plans =
-      allCandidatePlans.length > 0
-        ? allCandidatePlans
-        : [{ workflowKey, startFrom, candidate: ws?.candidate, sharedContext: ws?.sharedContext }];
+    if (candidateBackedResume && allCandidatePlans.length === 0) {
+      throw new Error(
+        `Cannot resume from "${startFrom}": the selected recording has no resumable candidates. Re-run from "detect-candidates".`,
+      );
+    }
+    plans = candidateBackedResume
+      ? allCandidatePlans
+      : [{ workflowKey, startFrom, candidate: ws?.candidate, sharedContext: ws?.sharedContext }];
   }
 
   // Early stop: `--to-step replay-and-diff|triage|detect-candidates` finishes
@@ -1367,16 +1460,18 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
   });
 
   // ── Clean up stale tools from previous teach runs ──
-  // Skipped entirely on a `--from-step` resume: a resume is scoped to a subset of
+  // Skipped on every resume, including interactive Continue/Redo: a resume is scoped to a subset of
   // the site's tools (selectMultiToolResumePlans intentionally leaves other
   // recordings' tools — and same-recording tools that didn't reach the step —
   // alone), so "not in the resume set" does NOT mean "stale". Treating it as stale
   // here would silently rmSync a tool the resume just promised to preserve. Cleanup
   // only applies to a fresh run that produces a superseding tool set.
   const incomingToolNames = new Set(plans.map((pl) => pl.candidate?.toolName ?? pl.workflowKey));
-  const staleTools = opts.fromStep
-    ? []
-    : discoverCompletedWorkflows(site).filter((name) => !incomingToolNames.has(name));
+  const staleTools = staleCompletedToolsForRun(
+    discoverCompletedWorkflows(site),
+    incomingToolNames,
+    runPolicy.cleanupStaleTools,
+  );
   if (staleTools.length > 0) {
     let shouldReplace = true;
     if (!opts.noInteractive) {
@@ -1417,7 +1512,7 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
   // one tool; otherwise its assigned shared modules and producer-token contract
   // silently disappear from the revision agent's context.
   const alreadyPlanned =
-    opts.fromStep !== 'plan-prereqs' &&
+    runPolicy.reuseExistingBuildPlan &&
     plans.every((pl) => state.workflows[pl.workflowKey]?.completedSteps.includes('plan-prereqs')) &&
     existsSync(sidecar);
   if (willGenerate && compileModel && alreadyPlanned && firstWs) {
@@ -1721,10 +1816,9 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
       sharedTriageResult: triageResult,
       siteClassifications,
       teachCredentials,
-      allTools: opts.allTools,
       buildPlanPath: buildPlanPath || undefined,
       sharedModules: sharedModulesManifest.length > 0 ? sharedModulesManifest : undefined,
-      resumeExistingArtifacts: Boolean(opts.fromStep),
+      resumeExistingArtifacts: runPolicy.reviseExistingArtifacts,
     });
   } finally {
     unmuteLog();
@@ -1754,7 +1848,7 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
     }
   }
 
-  const primaryResult = results[0] as TeachToolResult;
+  const primaryResult = selectPrimaryNamedResult(results, plans) as TeachToolResult;
 
   // ── 6. Platform integration ────────────────────────────────────────
   if (inWindow('register')) {
@@ -1913,47 +2007,133 @@ async function detectTeachCandidates(opts: {
   );
 }
 
-async function selectTeachCandidates(
+export async function selectTeachCandidates(
   detection: Awaited<ReturnType<typeof detectToolCandidates>>,
   opts: TeachOptions,
 ): Promise<ToolCandidate[]> {
   if (detection.candidates.length === 1) return [detection.candidates[0] as ToolCandidate];
 
-  if (opts.noInteractive) {
-    if (opts.allTools) return detection.candidates;
+  if (opts.primaryTool) {
     const primary = primaryToolCandidate(detection);
-    p.log.warn(
-      `Detected ${detection.candidates.length} candidate tools; --no-interactive compiles only primary "${primary.toolName}". Pass --all-tools to compile all.`,
-    );
-    return [primary];
+    const closure = finalizeTeachCandidateSelection(detection.candidates, [primary.toolName]);
+    for (const cycle of closure.cycles) {
+      p.log.warn(`Tool dependency cycle detected: ${cycle.join(' → ')}`);
+    }
+    return closure.selected;
+  }
+
+  if (opts.noInteractive) {
+    return detection.candidates;
   }
 
+  const picker = buildTeachCandidatePicker(detection.candidates);
   const answer = await p.multiselect({
     message:
       'Which tools should Imprint compile from this recording?\n  (press [space] to toggle, [enter] to submit)',
     required: true,
-    initialValues: detection.candidates
-      .filter((candidate) => candidate.primary)
-      .map((c) => c.toolName),
-    options: detection.candidates.map((candidate) => ({
-      value: candidate.toolName,
-      label: `${candidate.toolName}${candidate.primary ? ' (primary)' : ''}`,
-      hint: `${Math.round(candidate.confidence * 100)}% — ${candidate.description}`,
-    })),
+    initialValues: picker.initialValues,
+    options: picker.options,
   });
   if (p.isCancel(answer)) {
     p.outro('Cancelled.');
     process.exit(0);
   }
 
-  const selectedNames = new Set(answer as string[]);
-  const selected = detection.candidates.filter((candidate) =>
-    selectedNames.has(candidate.toolName),
-  );
-  if (selected.length === 0) {
+  const closure = finalizeTeachCandidateSelection(detection.candidates, answer as string[]);
+  if (closure.selected.length === 0) {
     throw new Error('At least one tool candidate must be selected.');
   }
-  return selected;
+  const notice = formatTeachCandidateAutoAddNotice(closure.autoAdded, 'structural');
+  if (notice) p.note(notice.body, notice.title);
+  for (const cycle of closure.cycles) {
+    p.log.warn(`Tool dependency cycle detected: ${cycle.join(' → ')}`);
+  }
+  return closure.selected;
+}
+
+export function buildTeachCandidatePicker(candidates: ToolCandidate[]): {
+  initialValues: string[];
+  options: Array<{ value: string; label: string; hint: string }>;
+} {
+  return {
+    initialValues: candidates.map((candidate) => candidate.toolName),
+    options: candidates.map((candidate) => ({
+      value: candidate.toolName,
+      label: `${candidate.toolName}${candidate.primary ? ' (primary)' : ''}`,
+      hint: [
+        `${Math.round(candidate.confidence * 100)}% — ${candidate.description}`,
+        candidate.dependsOnTools.length > 0
+          ? `requires ${candidate.dependsOnTools.join(', ')}`
+          : undefined,
+      ]
+        .filter(Boolean)
+        .join(' — '),
+    })),
+  };
+}
+
+/** Merge replay-grounded producer edges using the persisted ClassifiedValue
+ * shape. The token deriver deliberately accepts a value-only projection so raw
+ * recorded values stay out of planner payloads; adapt value1 at this boundary. */
+export function mergeReplayCandidateDependencies(
+  candidates: ToolCandidate[],
+  siteClassifications?: ClassifiedValue[],
+): ToolCandidate[] {
+  const tokenHints = siteClassifications
+    ? deriveTokenContractHints({
+        selectedTools: candidates,
+        ephemeralValues: siteClassifications.map((classification) => ({
+          classification: classification.classification,
+          originalSeq: classification.originalSeq,
+          location: classification.location,
+          producerSeq: classification.producerSeq,
+          producerPath: classification.producerPath,
+          value: classification.value1,
+        })),
+      })
+    : [];
+  return mergeCandidateDependencies(
+    candidates,
+    tokenHints.map((hint) => ({
+      consumerTool: hint.consumerTool,
+      producerTool: hint.producerTool,
+    })),
+  );
+}
+
+/** Pure boundary between detected candidates, optional replay evidence, and
+ * the exact dependency-closed set handed to checkpointing/build planning. */
+export function finalizeTeachCandidateSelection(
+  candidates: ToolCandidate[],
+  selectedToolNames: Iterable<string>,
+  siteClassifications?: ClassifiedValue[],
+): ReturnType<typeof closeCandidateSelection> & { candidates: ToolCandidate[] } {
+  const mergedCandidates = mergeReplayCandidateDependencies(candidates, siteClassifications);
+  return {
+    candidates: mergedCandidates,
+    ...closeCandidateSelection(mergedCandidates, selectedToolNames),
+  };
+}
+
+export function formatTeachCandidateAutoAddNotice(
+  autoAdded: ToolCandidate[],
+  source: 'structural' | 'replay',
+): { body: string; title: string } | undefined {
+  if (autoAdded.length === 0) return undefined;
+  return {
+    body: autoAdded.map((candidate) => `  + ${candidate.toolName}`).join('\n'),
+    title: source === 'replay' ? 'Added recorded prerequisites' : 'Added required upstream tools',
+  };
+}
+
+/** Select the compiled result corresponding to the detected primary candidate.
+ * Dependency closure preserves detection order, which need not put primary first. */
+export function selectPrimaryNamedResult<T extends { workflow: { toolName: string } }>(
+  results: readonly T[],
+  plans: ReadonlyArray<{ candidate?: { toolName: string; primary: boolean } }>,
+): T | undefined {
+  const primaryToolName = plans.find((plan) => plan.candidate?.primary)?.candidate?.toolName;
+  return results.find((result) => result.workflow.toolName === primaryToolName) ?? results[0];
 }
 
 async function compileCandidatePlans(opts: {
@@ -1969,10 +2149,6 @@ async function compileCandidatePlans(opts: {
   sharedTriageResult?: TriageResult;
   siteClassifications?: ClassifiedValue[];
   teachCredentials?: { site: string; values: Record<string, string> };
-  /** Mirror of TeachOptions.allTools — when true, partial failures abort
-   *  the run with a non-zero exit so the user notices missing tools instead
-   *  of getting a silent warning. */
-  allTools?: boolean;
   /** Absolute path to the multi-tool build plan sidecar (.build-plan.json). */
   buildPlanPath?: string;
   /** Shared-module build manifest (verified flags) for this site. */
@@ -2142,18 +2318,20 @@ async function compileCandidatePlans(opts: {
     if (first) p.log.warn(`${first.name}: ${first.firstLineError}`);
   }
 
-  // Hard-fail when --all-tools was requested AND any tool failed. Silent
-  // partial compiles ship MCP servers with missing tools; the user only
-  // notices later when an LLM tries to call one that doesn't exist.
-  if (opts.allTools && summary.failures.length > 0) {
-    throw new Error(
-      `--all-tools requested but ${summary.failures.length} of ${opts.plans.length} tools failed to compile. See the summary above; re-run \`imprint teach\` after addressing the failures (or omit --all-tools to ship only what compiled).`,
-    );
-  }
+  assertCompleteSelectedToolSet(summary.failures.length, opts.plans.length);
 
   return summary.successes;
 }
 
+/** Enforce that compilation never ships a partial selected set. A missing
+ * producer can make every otherwise-successful consumer unusable. */
+export function assertCompleteSelectedToolSet(failureCount: number, selectedCount: number): void {
+  if (failureCount === 0) return;
+  throw new Error(
+    `Selected tool set is incomplete: ${failureCount} of ${selectedCount} tools failed to compile. See the summary above and re-run \`imprint teach\` after addressing the failures.`,
+  );
+}
+
 /** Pure summarizer — extracted so unit tests can drive arbitrary outcome
  *  shapes without spinning up real compile pipelines. */
 interface CompileOutcomeSummary {
@@ -2488,7 +2666,10 @@ async function siteReplayAndDiff(
     };
 
     const classPath = pathJoin(localSiteDir(site), '.classifications.json');
-    writeFileSync(classPath, JSON.stringify(diffResult, null, 2));
+    writeFileSync(
+      classPath,
+      JSON.stringify({ ...diffResult, sourceSessionHash: fileSha256(sessionPath) }, null, 2),
+    );
 
     mp.clear();
     mp.remove('replay');

package/src/imprint/tool-candidates.ts

@@ -133,6 +133,9 @@ export const ToolCandidateSchema = z.object({
   expectedOutput: z.string().default(''),
   likelyParams: z.array(CandidateParamSchema).default([]),
   dependencySeqs: z.array(z.number().int().nonnegative()).default([]),
+  /** Direct user-visible tool prerequisites. A consumer may only be selected
+   *  together with the transitive closure of these producer tools. */
+  dependsOnTools: z.array(z.string().regex(/^[a-z][a-z0-9_]*$/)).default([]),
 });
 export type ToolCandidate = z.infer<typeof ToolCandidateSchema>;
 
@@ -328,6 +331,124 @@ export function primaryToolCandidate(detection: ToolCandidateDetection): ToolCan
   return primary;
 }
 
+/** Add deterministic candidate-level dependencies from request evidence.
+ * A dependency request creates an edge only when exactly one candidate owns
+ * that request seq. Shared/ambiguous ownership, unowned auth/bootstrap seqs,
+ * and self-owned seqs deliberately create no edge. */
+export function deriveStructuralCandidateDependencies(
+  candidates: ToolCandidate[],
+): ToolCandidate[] {
+  const ownersBySeq = new Map<number, Set<string>>();
+  for (const candidate of candidates) {
+    for (const seq of candidate.requestSeqs) {
+      const owners = ownersBySeq.get(seq) ?? new Set<string>();
+      owners.add(candidate.toolName);
+      ownersBySeq.set(seq, owners);
+    }
+  }
+
+  const edges: Array<{ consumerTool: string; producerTool: string }> = [];
+  for (const candidate of candidates) {
+    for (const seq of candidate.dependencySeqs) {
+      const owners = ownersBySeq.get(seq);
+      if (!owners || owners.size !== 1) continue;
+      const producerTool = owners.values().next().value as string | undefined;
+      if (!producerTool || producerTool === candidate.toolName) continue;
+      edges.push({ consumerTool: candidate.toolName, producerTool });
+    }
+  }
+  return mergeCandidateDependencies(candidates, edges);
+}
+
+/** Merge grounded producer edges into candidate metadata. Unknown tools and
+ * self-edges are ignored; dependency names are de-duplicated and normalized to
+ * candidate detection order for stable persistence and display. */
+export function mergeCandidateDependencies(
+  candidates: ToolCandidate[],
+  edges: ReadonlyArray<{ consumerTool: string; producerTool: string }>,
+): ToolCandidate[] {
+  const names = new Set(candidates.map((candidate) => candidate.toolName));
+  const dependencySets = new Map<string, Set<string>>();
+  for (const candidate of candidates) {
+    dependencySets.set(
+      candidate.toolName,
+      new Set(
+        candidate.dependsOnTools.filter((name) => names.has(name) && name !== candidate.toolName),
+      ),
+    );
+  }
+  for (const edge of edges) {
+    if (
+      edge.consumerTool === edge.producerTool ||
+      !names.has(edge.consumerTool) ||
+      !names.has(edge.producerTool)
+    ) {
+      continue;
+    }
+    dependencySets.get(edge.consumerTool)?.add(edge.producerTool);
+  }
+
+  const order = new Map(candidates.map((candidate, index) => [candidate.toolName, index]));
+  return candidates.map((candidate) => ({
+    ...candidate,
+    dependsOnTools: [...(dependencySets.get(candidate.toolName) ?? [])].sort(
+      (a, b) =>
+        (order.get(a) ?? Number.MAX_SAFE_INTEGER) - (order.get(b) ?? Number.MAX_SAFE_INTEGER),
+    ),
+  }));
+}
+
+interface CandidateSelectionClosure {
+  selected: ToolCandidate[];
+  autoAdded: ToolCandidate[];
+  /** Cycles encountered while walking selected dependencies. Each path repeats
+   *  its first name at the end, e.g. ["a", "b", "a"]. */
+  cycles: string[][];
+}
+
+/** Return the transitive dependency closure in original detection order.
+ * Cycles are included exactly once and reported, never treated as recursion
+ * errors. Unknown selected/dependency names are ignored. */
+export function closeCandidateSelection(
+  candidates: ToolCandidate[],
+  selectedToolNames: Iterable<string>,
+): CandidateSelectionClosure {
+  const byName = new Map(candidates.map((candidate) => [candidate.toolName, candidate]));
+  const initiallySelected = new Set([...selectedToolNames].filter((name) => byName.has(name)));
+  const included = new Set<string>();
+  const visiting: string[] = [];
+  const cycles: string[][] = [];
+  const cycleKeys = new Set<string>();
+
+  const include = (name: string): void => {
+    if (included.has(name)) return;
+    const candidate = byName.get(name);
+    if (!candidate) return;
+    const cycleStart = visiting.indexOf(name);
+    if (cycleStart >= 0) {
+      const cycle = [...visiting.slice(cycleStart), name];
+      const key = [...new Set(cycle.slice(0, -1))].sort().join('\u0000');
+      if (!cycleKeys.has(key)) {
+        cycleKeys.add(key);
+        cycles.push(cycle);
+      }
+      return;
+    }
+    visiting.push(name);
+    for (const dependency of candidate.dependsOnTools) include(dependency);
+    visiting.pop();
+    included.add(name);
+  };
+
+  for (const name of initiallySelected) include(name);
+  const selected = candidates.filter((candidate) => included.has(candidate.toolName));
+  return {
+    selected,
+    autoAdded: selected.filter((candidate) => !initiallySelected.has(candidate.toolName)),
+    cycles,
+  };
+}
+
 export function buildSharedCompileContext(
   detection: ToolCandidateDetection,
   _selected: ToolCandidate[],