imprint-mcp 0.2.0 → 0.3.0

package/src/imprint/teach.ts

@@ -9,9 +9,20 @@
 
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join as pathJoin, resolve as pathResolve } from 'node:path';
+import {
+  basename as pathBasename,
+  dirname as pathDirname,
+  join as pathJoin,
+  resolve as pathResolve,
+} from 'node:path';
 import * as p from '@clack/prompts';
 import type { OnDeadlineReached } from './agent.ts';
+import {
+  type SharedModuleManifestEntry,
+  buildPlanSidecarPath,
+  readBuildPlanFile,
+  topoLevelsForTools,
+} from './build-plan.ts';
 import {
   type CompileAgentProgress,
   type TriageResult,
@@ -19,6 +30,7 @@ import {
   generate,
   triageRequests,
 } from './compile.ts';
+import { mapLimit, mapLimitSettled } from './concurrency.ts';
 import {
   type CredentialFinding,
   type Replacement,
@@ -41,15 +53,23 @@ import {
   isTeachCompatibleProvider,
 } from './llm.ts';
 import { loadJsonFile } from './load-json.ts';
-import { muteLog, unmuteLog } from './log.ts';
+import { createLog, muteLog, unmuteLog } from './log.ts';
 import { MultiProgress } from './multi-progress.ts';
 import { localSiteDir, localToolDir } from './paths.ts';
 import { describeAgentActivity, formatElapsed } from './progress.ts';
 import { record } from './record.ts';
 import { detectPageMintedHeaders, redactSession } from './redact.ts';
 import { loadCredentialStore } from './runtime.ts';
+import { isSensitiveCredentialKey, passwordLikeTokens } from './sensitive-keys.ts';
 import type { ClassifiedValue } from './session-diff.ts';
-import { listSiteSessions, mergeSessions, writeCombinedSession } from './session-merge.ts';
+import {
+  listSessionsInDir,
+  listSiteSessions,
+  mergeSessions,
+  writeCombinedSession,
+} from './session-merge.ts';
+import { clearCachedToken } from './stealth-token-cache.ts';
+import { planAndBuildPrereqs } from './teach-plan.ts';
 import {
   TEACH_STEPS as STEPS,
   type TeachStep as Step,
@@ -73,11 +93,25 @@ import {
   detectToolCandidates,
   primaryToolCandidate,
 } from './tool-candidates.ts';
+import { planToolCompile } from './tool-plan.ts';
+import { setSpanAttributes, traced } from './tracing.ts';
 import { CronConfigSchema, SessionSchema, WorkflowSchema } from './types.ts';
 import type { CronConfig, Playbook, Session, Workflow } from './types.ts';
 
 export { buildTeachStateFromSession, resolveTeachStatePath } from './teach-state.ts';
 
+/**
+ * How many compile agents run in parallel when more than one tool is selected.
+ * Kept at 2 (not 3): bursts of near-identical reverse-engineering requests in a
+ * short window raise the model's usage-policy safety-filter false-positive rate,
+ * so we trade a little wall-clock for fewer spurious refusals. Single-tool runs
+ * still use concurrency 1.
+ */
+const COMPILE_CONCURRENCY = 2;
+
+/** Module logger — suppressed during teach's spinner phases via muteLog(). */
+const log = createLog('teach');
+
 // ─── Types ──────────────────────────────────────────────────────────────────
 
 interface TeachOptions {
@@ -89,7 +123,7 @@ interface TeachOptions {
   provider?: ProviderName;
   /** Override the compile model (otherwise prompted or auto-detected). */
   model?: string;
-  /** Per-tool compile timeout in ms. Default 10 minutes. */
+  /** Per-tool compile timeout in ms. Default 20 minutes. */
   maxDurationMs?: number;
   fromSession?: string;
   /** Retain parser.test.ts after successful compile-agent verification. */
@@ -317,7 +351,7 @@ export async function promptForTeachProvider(
 async function promptForModel(provider: ProviderName): Promise<string> {
   const { availableModelsForProvider } = await import('./llm.ts');
   const models = availableModelsForProvider(provider);
-  if (models.length <= 1) return models[0]?.model ?? 'claude-opus-4-7';
+  if (models.length <= 1) return models[0]?.model ?? 'claude-opus-4-8';
 
   const choice = await p.select({
     message: 'Which model should compile this workflow?',
@@ -500,16 +534,25 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
   if (startIdx <= STEPS.indexOf('record')) {
     const startUrl = await resolveStartUrl(opts);
 
-    spinner.start('Recording...');
+    spinner.start('Recording');
     spinner.stop('Ready to record.');
     console.log('');
 
-    const recordResult = await record({
-      site: site,
-      url: startUrl,
-      persistProfile: opts.persistProfile,
-      signal: opts.signal,
-    });
+    const recordResult = await traced(
+      'teach.record',
+      'CHAIN',
+      { 'imprint.site': site, 'imprint.url': startUrl },
+      async (span) => {
+        const res = await record({
+          site: site,
+          url: startUrl,
+          persistProfile: opts.persistProfile,
+          signal: opts.signal,
+        });
+        setSpanAttributes(span, { 'imprint.record.event_count': res.count });
+        return res;
+      },
+    );
     sessionPath = recordResult.sessionPath;
 
     checkpoint(site, state, workflowKey, {
@@ -518,21 +561,30 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
       startedAt: new Date().toISOString(),
       updatedAt: new Date().toISOString(),
     });
+  }
 
-    // ── 1b. Combine with past sessions (optional) ────────────────────
-    const originalSessionPath = sessionPath;
-    sessionPath = await promptSessionCombine({
-      site,
-      currentSessionPath: sessionPath,
-      noInteractive: opts.noInteractive ?? false,
-    });
-    if (sessionPath !== originalSessionPath) {
-      checkpoint(site, state, workflowKey, {
-        sessionPath: toRelative(site, sessionPath),
-        completedSteps: ['record'],
-        startedAt: new Date().toISOString(),
-        updatedAt: new Date().toISOString(),
+  // ── 1b. Combine with past sessions (optional) ──────────────────────
+  // Runs after recording OR when --from-session is provided. Skipped when
+  // resuming from a checkpoint (the checkpoint already stores the final
+  // session path, possibly combined from a previous run).
+  if (sessionPath && (startIdx <= STEPS.indexOf('record') || usingFromSession)) {
+    const isCombinedSession = pathBasename(sessionPath).startsWith('combined-');
+    if (!isCombinedSession) {
+      const originalSessionPath = sessionPath;
+      sessionPath = await combineAvailableSessions({
+        site,
+        currentSessionPath: sessionPath,
+        noInteractive: opts.noInteractive ?? false,
+        fromSession: usingFromSession,
       });
+      if (sessionPath !== originalSessionPath) {
+        checkpoint(site, state, workflowKey, {
+          sessionPath: toRelative(site, sessionPath),
+          completedSteps: ['record'],
+          startedAt: new Date().toISOString(),
+          updatedAt: new Date().toISOString(),
+        });
+      }
     }
   }
 
@@ -581,14 +633,33 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
       }
     }
 
-    spinner.start('Redacting credentials...');
-    const pageMintedHeaders = detectPageMintedHeaders(session);
-    const { session: scrubbed, stats } = redactSession(session, {
-      replacements: confirmedReplacements,
-      keepHeaders: pageMintedHeaders,
-    });
+    spinner.start('Redacting credentials');
     redactedPath = sessionPath.replace(/\.json$/, '.redacted.json');
-    writeFileSync(redactedPath, `${JSON.stringify(scrubbed, null, 2)}\n`, 'utf8');
+    const { stats } = await traced(
+      'teach.redact',
+      'CHAIN',
+      { 'imprint.site': site },
+      async (span) => {
+        const pageMintedHeaders = detectPageMintedHeaders(session);
+        const redaction = redactSession(session, {
+          replacements: confirmedReplacements,
+          keepHeaders: pageMintedHeaders,
+        });
+        writeFileSync(
+          redactedPath as string,
+          `${JSON.stringify(redaction.session, null, 2)}\n`,
+          'utf8',
+        );
+        setSpanAttributes(span, {
+          'imprint.redact.totalRedactions': redaction.stats.totalRedactions,
+          'imprint.redact.requestsRedacted': redaction.stats.requestsRedacted,
+          'imprint.redact.cookiesRedacted': redaction.stats.cookiesRedacted,
+          'imprint.redact.placeholdersInjected': redaction.stats.placeholdersInjected,
+          'imprint.redact.freeformRedactions': redaction.stats.freeformRedactions,
+        });
+        return redaction;
+      },
+    );
     const placeholderNote =
       stats.placeholdersInjected > 0
         ? `, ${stats.placeholdersInjected} replaced with credential placeholders`
@@ -599,8 +670,38 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
       `Redacted ${stats.totalRedactions} value(s) across ${stats.requestsRedacted} request(s) and ${stats.cookiesRedacted} cookie(s)${placeholderNote}${freeformNote}.`,
     );
 
+    // Post-redact pairing audit: if any request body contained a
+    // password-shaped field but credential extraction failed to produce a
+    // confirmed username+password pair, the downstream compile stage will
+    // template credentials as `${param.X}` instead of `${credential.X}` —
+    // shipping a broken MCP tool that asks callers to provide credentials
+    // by hand instead of pulling from the credential store.
+    //
+    // The most common reason is an unusual request framing (custom
+    // Content-Type, unusual key naming) that the extractor's dictionaries
+    // or parsers don't yet cover. Surface this loudly so the user can
+    // either re-record, file a bug, or proceed knowing the tool needs
+    // hand-editing.
+    const warnings: string[] = [];
+    const unpairedPasswordSeqs = findUnpairedPasswordRequests(session);
+    if (unpairedPasswordSeqs.length > 0 && confirmedReplacements.length === 0) {
+      warnings.push('credentials_not_paired');
+      const seqList = unpairedPasswordSeqs.slice(0, 5).join(', ');
+      const more = unpairedPasswordSeqs.length > 5 ? ', …' : '';
+      p.log.warn(
+        [
+          `Detected ${unpairedPasswordSeqs.length} request(s) with a password-shaped field (seqs: ${seqList}${more}) but no username+password pair was extracted.`,
+          'The generated workflow will treat credentials as plain parameters and will NOT pull from the credential store.',
+          'This usually means the request body uses an unusual framing (Content-Type, key naming, multipart variant) the extractor did not recognise.',
+          `→ Recommended: file a bug with the redacted session at ${toRelative(site, redactedPath)}, then re-record once the extractor is fixed.`,
+          '→ To proceed anyway, just continue — the tool will need manual credential wiring before it works.',
+        ].join('\n'),
+      );
+    }
+
     updateCheckpoint(site, state, workflowKey, 'redact', {
       redactedPath: toRelative(site, redactedPath),
+      warnings: warnings.length > 0 ? warnings : undefined,
     });
   }
 
@@ -717,7 +818,7 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
           const model = await getModel();
           mp.pause();
           mp.clear();
-          spinner.start('Triaging requests...');
+          spinner.start('Triaging requests');
           localTriageResult = await triageRequests(triageSession, {
             provider: providerName,
             model,
@@ -751,7 +852,7 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
         const model = await getModel();
         mp.pause();
         mp.clear();
-        spinner.start('Detecting candidate tools...');
+        spinner.start('Detecting candidate tools');
         const detection = await detectTeachCandidates({
           sessionPath: compileSessionPath,
           providerName,
@@ -827,7 +928,7 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
       await new Promise((r) => setTimeout(r, 0));
       const showedSpinner = !replaySettled;
       if (showedSpinner) {
-        spinner.start('Waiting for replay to finish...');
+        spinner.start('Waiting for replay to finish');
       }
       siteClassifications = await replayPromise;
       if (showedSpinner) {
@@ -885,7 +986,7 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
   let compileModel = '';
   if (needsCompileProvider) {
     compileModel = await getModel();
-    const timeoutMs = opts.maxDurationMs ?? 10 * 60 * 1000;
+    const timeoutMs = opts.maxDurationMs ?? 20 * 60 * 1000;
     const timeoutDisplay =
       timeoutMs >= 3_600_000
         ? `${Math.round(timeoutMs / 3_600_000)}h`
@@ -898,10 +999,22 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
         `Timeout: ${timeoutDisplay} per tool`,
         '',
         plans.length === 1
-          ? 'An LLM agent will reverse-engineer the API response format.'
-          : `${plans.length} LLM compile agents will reverse-engineer selected tools with concurrency 3.`,
-        `Expect up to ${timeoutDisplay} per tool and moderate to high token use, depending on`,
-        'the complexity of the recording. You can interrupt with Ctrl-C.',
+          ? 'An LLM agent will reverse-engineer the API response format,'
+          : `${plans.length} LLM compile agents will reverse-engineer selected tools with concurrency ${COMPILE_CONCURRENCY},`,
+        'write the MCP server, and run thorough verification tests.',
+        'Most complex tools take 10-15 minutes — please be patient.',
+        `Timeout: ${timeoutDisplay} per tool. You can interrupt with Ctrl-C.`,
+        ...(plans.length > 1
+          ? [
+              '',
+              'Shared helper modules are planned + built once under _shared/ before',
+              'the tools compile, so each tool reuses them. Set IMPRINT_NO_BUILD_PLAN=1',
+              'to disable and compile every tool independently.',
+            ]
+          : []),
+        '',
+        'To persist the generated tests after compilation, set IMPRINT_KEEP_TEST=1',
+        'or pass --keep-test.',
       ].join('\n'),
       'Compile step',
     );
@@ -937,7 +1050,75 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
     }
   }
 
-  if (plans.length > 1) muteLog();
+  // ── plan-prereqs: plan + build shared modules once before the fan-out ──
+  // Only engages for ≥2 selected tools that are about to be (re)generated.
+  // Single-tool runs and resumes-past-generate are unchanged.
+  const selectedCandidates = plans.map((pl) => pl.candidate).filter((c): c is ToolCandidate => !!c);
+  const willGenerate = plans.some((pl) => STEPS.indexOf(pl.startFrom) <= STEPS.indexOf('generate'));
+  let buildPlanPath = '';
+  let sharedModulesManifest: SharedModuleManifestEntry[] = [];
+  if (selectedCandidates.length >= 2 && willGenerate && compileModel) {
+    const sidecar = buildPlanSidecarPath(site);
+    const firstWs = state.workflows[plans[0]?.workflowKey ?? ''];
+    const alreadyPlanned =
+      plans.every((pl) =>
+        state.workflows[pl.workflowKey]?.completedSteps.includes('plan-prereqs'),
+      ) && existsSync(sidecar);
+    if (alreadyPlanned && firstWs) {
+      // Resume past plan-prereqs — reuse the persisted plan + manifest.
+      buildPlanPath = sidecar;
+      sharedModulesManifest = firstWs.sharedModules ?? [];
+    } else {
+      // Mute raw `[imprint …]` logs from the planning subtree (build-plan,
+      // teach-plan, prereq-builder) while the spinner is live — progress flows
+      // through onProgress → spinner.message instead, matching the replay and
+      // compile phases. The skip/timeout reason is surfaced cleanly below.
+      muteLog();
+      spinner.start('Planning shared modules');
+      try {
+        const prereq = await planAndBuildPrereqs({
+          site,
+          redactedSessionPath: compileSessionPath,
+          candidates: selectedCandidates,
+          sharedContext: plans[0]?.sharedContext,
+          siteClassifications,
+          providerName: compileProviderName,
+          model: compileModel,
+          onProgress: (msg) => spinner.message(msg),
+        });
+        buildPlanPath = prereq.buildPlanPath;
+        sharedModulesManifest = prereq.sharedModules;
+        const verified = sharedModulesManifest.filter((m) => m.verified).length;
+        spinner.stop(
+          buildPlanPath
+            ? `Build plan ready (${verified}/${sharedModulesManifest.length} shared module${sharedModulesManifest.length === 1 ? '' : 's'} verified).`
+            : 'Build plan skipped.',
+        );
+        if (prereq.skippedReason) p.log.warn(prereq.skippedReason);
+      } catch (err) {
+        spinner.stop('Build planning failed — compiling tools independently.');
+        p.log.warn(
+          `Build planning failed: ${err instanceof Error ? err.message : String(err)}\nTools will compile without shared modules.`,
+        );
+        buildPlanPath = '';
+        sharedModulesManifest = [];
+      } finally {
+        unmuteLog();
+      }
+      for (const pl of plans) {
+        updateCheckpoint(site, state, pl.workflowKey, 'plan-prereqs', {
+          buildPlanPath: buildPlanPath ? toRelative(site, buildPlanPath) : undefined,
+          sharedModules: sharedModulesManifest,
+        });
+      }
+    }
+  }
+
+  // Mute raw `[imprint …]` logs from the compile subtree while the spinner /
+  // MultiProgress is live. This covers single-tool runs too: they drive the
+  // shared spinner and would otherwise leak compile.ts diagnostics into it,
+  // just as concurrent multi-tool runs would interleave their logs.
+  muteLog();
   let results: TeachToolResult[];
   try {
     results = await compileCandidatePlans({
@@ -953,9 +1134,12 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
       sharedTriageResult: triageResult,
       siteClassifications,
       teachCredentials,
+      allTools: opts.allTools,
+      buildPlanPath: buildPlanPath || undefined,
+      sharedModules: sharedModulesManifest.length > 0 ? sharedModulesManifest : undefined,
     });
   } finally {
-    if (plans.length > 1) unmuteLog();
+    unmuteLog();
   }
 
   if (results.length === 0) {
@@ -1019,8 +1203,32 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
     updateCheckpoint(site, state, result.workflow.toolName, 'register');
   }
 
+  // Drop the transient compile-time stealth token (shared across this site's
+  // per-tool `bun test` processes). It holds a live session token and is no
+  // longer needed once every tool has compiled.
+  clearCachedToken(localSiteDir(site));
+
+  // Surface any tools that shipped without a passing live integration test
+  // (waived during compile due to anti-bot / infra). These rely on the runtime
+  // playbook last-ditch path, which is a degraded fallback — operators should
+  // know rather than discover at audit/runtime.
+  const unverified = results.filter((r) => r.workflow.liveVerified === false);
+  if (unverified.length > 0) {
+    for (const r of unverified) {
+      const waiver = r.workflow.liveVerifiedWaiver;
+      const reason = waiver
+        ? `${waiver.kind} (exhausted: ${waiver.exhaustedBackends.join(', ') || 'n/a'}; first error: ${waiver.firstError})`
+        : 'reason not recorded';
+      p.log.warn(
+        `tool "${r.workflow.toolName}" shipped without live verification: ${reason}\n  → runtime callers fall through to the playbook last-ditch rung; treat this tool as unverified until audit confirms it.`,
+      );
+    }
+  }
+
   p.outro(
-    `Done! ${results.length} tool${results.length === 1 ? '' : 's'} ready: ${results.map((r) => r.workflow.toolName).join(', ')}`,
+    `Done! ${results.length} tool${results.length === 1 ? '' : 's'} ready: ${results.map((r) => r.workflow.toolName).join(', ')}${
+      unverified.length > 0 ? ` (${unverified.length} unverified — see warnings above)` : ''
+    }`,
   );
 
   return {
@@ -1036,7 +1244,7 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
 
 // ─── Candidate detection + per-tool compile ────────────────────────────────
 
-interface CandidateCompilePlan {
+export interface CandidateCompilePlan {
   workflowKey: string;
   startFrom: Step;
   candidate?: ToolCandidate;
@@ -1116,8 +1324,16 @@ 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. */
+  sharedModules?: SharedModuleManifestEntry[];
 }): Promise<TeachToolResult[]> {
-  const concurrency = opts.plans.length === 1 ? 1 : 3;
+  const concurrency = opts.plans.length === 1 ? 1 : COMPILE_CONCURRENCY;
   const mp = opts.plans.length > 1 ? new MultiProgress() : null;
 
   // Mutex for deadline prompts: concurrent compile agents can hit their
@@ -1126,7 +1342,7 @@ async function compileCandidatePlans(opts: {
   // input from the first, causing it to auto-resolve as cancelled.
   let promptLock: Promise<void> = Promise.resolve();
 
-  const outcomes = await mapLimitSettled(opts.plans, concurrency, async (plan) => {
+  const compileOne = async (plan: CandidateCompilePlan) => {
     const displayName = plan.candidate?.toolName ?? plan.workflowKey;
     let lastActivity = '';
     const onProgress = (progress: CompileAgentProgress): void => {
@@ -1164,7 +1380,7 @@ async function compileCandidatePlans(opts: {
             if (mp) {
               mp.resume();
             } else {
-              opts.spinner.start(`Compiling ${displayName}...`);
+              opts.spinner.start(`Compiling ${displayName}`);
             }
             if (p.isCancel(extend) || !extend) return null;
             return 10 * 60 * 1000;
@@ -1174,7 +1390,7 @@ async function compileCandidatePlans(opts: {
         }
       : undefined;
 
-    if (!mp) opts.spinner.start(`Compiling ${displayName}...`);
+    if (!mp) opts.spinner.start(`Compiling ${displayName}`);
     try {
       const result = await compileSelectedCandidate({
         ...opts,
@@ -1209,29 +1425,109 @@ async function compileCandidatePlans(opts: {
       }
       throw err;
     }
-  });
+  };
+
+  // Compile producer tools before their consumers so a consumer's chained
+  // verification test can mint a fresh token from the producer's live workflow.
+  // With no token contracts declared, every tool lands in a single level — the
+  // behavior is identical to the prior single concurrent fan-out.
+  type CompileOutcome = { ok: true; value: TeachToolResult } | { ok: false; error: unknown };
+  const buildPlan = opts.buildPlanPath ? readBuildPlanFile(opts.buildPlanPath) : null;
+  const levels = topoLevelsForTools(
+    opts.plans.map((plan) => ({ toolName: plan.candidate?.toolName ?? plan.workflowKey, plan })),
+    buildPlan,
+  );
+  const outcomeByKey = new Map<string, CompileOutcome>();
+  for (const level of levels) {
+    const levelPlans = level.map((k) => k.plan);
+    const levelOutcomes = await mapLimitSettled(levelPlans, concurrency, compileOne);
+    levelPlans.forEach((plan, i) => {
+      const outcome = levelOutcomes[i];
+      if (outcome) outcomeByKey.set(plan.workflowKey, outcome);
+    });
+  }
+  const outcomes: CompileOutcome[] = opts.plans.map(
+    (plan) =>
+      outcomeByKey.get(plan.workflowKey) ?? {
+        ok: false,
+        error: new Error(`no compile outcome recorded for ${plan.workflowKey}`),
+      },
+  );
+
+  const summary = summarizeCompileOutcomes(outcomes, opts.plans);
 
+  // Print the structured summary on every multi-tool run so users see
+  // exactly what compiled vs what failed — a single warn line buried in
+  // log output is easy to miss when 4 of 6 tools compiled cleanly.
+  if (opts.plans.length > 1) {
+    const lines = renderCompileSummary(summary);
+    if (summary.failures.length === 0) {
+      p.log.success(lines.join('\n'));
+    } else {
+      p.log.warn(lines.join('\n'));
+    }
+  } else if (summary.failures.length > 0) {
+    // Single-tool run: keep the old single-line warn for backwards-compat
+    // since there's nothing to summarize.
+    const first = summary.failures[0];
+    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).`,
+    );
+  }
+
+  return summary.successes;
+}
+
+/** Pure summarizer — extracted so unit tests can drive arbitrary outcome
+ *  shapes without spinning up real compile pipelines. */
+interface CompileOutcomeSummary {
+  detected: number;
+  successes: TeachToolResult[];
+  successNames: string[];
+  failures: Array<{ name: string; firstLineError: string }>;
+}
+
+export function summarizeCompileOutcomes(
+  outcomes: Array<{ ok: true; value: TeachToolResult } | { ok: false; error: unknown } | null>,
+  plans: CandidateCompilePlan[],
+): CompileOutcomeSummary {
   const successes: TeachToolResult[] = [];
-  const failures: string[] = [];
+  const successNames: string[] = [];
+  const failures: Array<{ name: string; firstLineError: string }> = [];
   for (let i = 0; i < outcomes.length; i++) {
     const outcome = outcomes[i];
-    const displayName = opts.plans[i]?.candidate?.toolName ?? opts.plans[i]?.workflowKey ?? '?';
+    const displayName = plans[i]?.candidate?.toolName ?? plans[i]?.workflowKey ?? '?';
     if (outcome?.ok) {
       successes.push(outcome.value);
+      successNames.push(displayName);
     } else {
       const msg = outcome?.error instanceof Error ? outcome.error.message : String(outcome?.error);
-      failures.push(`${displayName}: ${msg.split('\n')[0]}`);
+      failures.push({ name: displayName, firstLineError: msg.split('\n')[0] ?? '' });
     }
   }
+  return { detected: plans.length, successes, successNames, failures };
+}
 
-  if (failures.length > 0) {
-    p.log.warn(
-      `${successes.length} of ${outcomes.length} tools compiled. ` +
-        `${failures.length} failed:\n${failures.map((f) => `  • ${f}`).join('\n')}`,
-    );
+function renderCompileSummary(summary: CompileOutcomeSummary): string[] {
+  const lines: string[] = [];
+  lines.push(`Compile summary: ${summary.successes.length}/${summary.detected} tools compiled.`);
+  if (summary.successNames.length > 0) {
+    lines.push(`Compiled: ${summary.successNames.join(', ')}`);
   }
-
-  return successes;
+  if (summary.failures.length > 0) {
+    lines.push(`Failed (${summary.failures.length}):`);
+    for (const f of summary.failures) {
+      lines.push(`  • ${f.name}: ${f.firstLineError}`);
+    }
+  }
+  return lines;
 }
 
 async function compileSelectedCandidate(opts: {
@@ -1248,6 +1544,8 @@ async function compileSelectedCandidate(opts: {
   sharedTriageResult?: TriageResult;
   siteClassifications?: ClassifiedValue[];
   teachCredentials?: { site: string; values: Record<string, string> };
+  buildPlanPath?: string;
+  sharedModules?: SharedModuleManifestEntry[];
 }): Promise<TeachToolResult> {
   const { plan, site, state } = opts;
   const startIdx = STEPS.indexOf(plan.startFrom);
@@ -1255,14 +1553,34 @@ async function compileSelectedCandidate(opts: {
   const workflowDir = localToolDir(site, toolName);
   mkdirSync(workflowDir, { recursive: true });
 
-  // ── Step 1: generate (workflow.json, enriched with site-level classifications) ──
-  let genResult: { workflow: Workflow; workflowPath: string };
+  // ── Step 1: plan THEN execute (workflow.json) ──
+  let genResult: { workflow: Workflow; workflowPath: string } | undefined;
   if (startIdx <= STEPS.indexOf('generate')) {
+    const llmConfig = { provider: opts.providerName, model: opts.compileModel };
+
+    // Plan THEN execute: derive a per-tool implementation plan (param→field
+    // mapping, request construction, response parsing, shared-module imports),
+    // then run a single compile that follows it. Best-effort — a timeout or
+    // error yields no plan and the compile proceeds exactly as before.
+    const toolPlan = plan.candidate
+      ? await planToolCompile({
+          site,
+          toolName,
+          candidate: plan.candidate,
+          sharedContext: plan.sharedContext,
+          sessionPath: opts.sessionPath,
+          buildPlanPath: opts.buildPlanPath,
+          sharedModules: opts.sharedModules,
+          providerName: opts.providerName,
+          model: opts.compileModel,
+        })
+      : undefined;
+
     const result = await generate({
       sessionPath: opts.sessionPath,
       outDir: workflowDir,
       maxDurationMs: opts.maxDurationMs,
-      llmConfig: { provider: opts.providerName, model: opts.compileModel },
+      llmConfig,
       keepTest: opts.keepTest,
       candidate: plan.candidate,
       sharedContext: plan.sharedContext,
@@ -1270,7 +1588,11 @@ async function compileSelectedCandidate(opts: {
       onDeadlineReached: opts.onDeadlineReached,
       classifications: opts.siteClassifications,
       teachCredentials: opts.teachCredentials,
+      buildPlanPath: opts.buildPlanPath,
+      sharedModules: opts.sharedModules,
+      toolPlan,
     });
+
     assertCandidateToolName('Compiled workflow', result.workflow.toolName, plan.candidate);
     genResult = { workflow: result.workflow, workflowPath: result.workflowPath };
     updateCheckpoint(site, state, plan.workflowKey, 'generate', {
@@ -1287,6 +1609,9 @@ async function compileSelectedCandidate(opts: {
     );
     genResult = { workflow, workflowPath };
   }
+  if (!genResult) {
+    throw new Error(`generate step did not produce a workflow for "${toolName}".`);
+  }
 
   // ── Step 2: compile-playbook (after generate — runtime artifact, not needed for dual-pass) ──
   let pbResult: { playbook: Playbook; playbookPath: string };
@@ -1349,7 +1674,9 @@ async function siteReplayAndDiff(
 ): Promise<ClassifiedValue[] | undefined> {
   try {
     const { replayRawSession } = await import('./replay-capture.ts');
-    const { diffTriagedSessions, triageByAlignment } = await import('./session-diff.ts');
+    const { diffTriagedSessions, triageByAlignment, mergeClassifications } = await import(
+      './session-diff.ts'
+    );
 
     const session = loadJsonFile(
       sessionPath,
@@ -1392,9 +1719,49 @@ async function siteReplayAndDiff(
 
     mp.update('replay', 'Diffing replay against original...');
 
+    // Pass 1: original recording vs the automated browser replay.
     const triaged2Seqs = triageByAlignment(session.requests, replayRequests);
     const triaged2Requests = replayRequests.filter((r) => triaged2Seqs.includes(r.seq));
-    const diffResult = diffTriagedSessions(session, { requests: triaged2Requests });
+    const replayDiff = diffTriagedSessions(session, { requests: triaged2Requests });
+    const diffPasses: ClassifiedValue[][] = [replayDiff.classifications];
+
+    // Additional passes: original recording vs every OTHER real recording of
+    // this site. Real recordings come from a trusted browser, so they reproduce
+    // anti-bot-protected requests the automated replay may be blocked from
+    // making (e.g. Akamai denies Playwright at the page level). A value
+    // identical across time-separated recordings is static infrastructure
+    // (GraphQL safelisting signatures, persisted-query hashes, app keys) and
+    // must be kept even when the replay never observed it — see
+    // mergeClassifications. All passes share `session` as the original, so
+    // originalSeq aligns them.
+    let crossRecordingCount = 0;
+    try {
+      const sessionAbs = pathResolve(sessionPath);
+      const others = listSiteSessions(site).filter((s) => pathResolve(s.absPath) !== sessionAbs);
+      for (const info of others) {
+        try {
+          const other = loadJsonFile(
+            info.absPath,
+            SessionSchema,
+            { notFound: 'Other recording not found.' },
+            'session',
+          );
+          const seqs = triageByAlignment(session.requests, other.requests);
+          const reqs = other.requests.filter((r) => seqs.includes(r.seq));
+          diffPasses.push(diffTriagedSessions(session, { requests: reqs }).classifications);
+          crossRecordingCount++;
+        } catch {
+          // Skip a malformed sibling recording; the other passes still stand.
+        }
+      }
+    } catch {
+      // No sibling recordings available — replay-only classification stands.
+    }
+
+    const diffResult = {
+      ...replayDiff,
+      classifications: mergeClassifications(diffPasses),
+    };
 
     const classPath = pathJoin(localSiteDir(site), '.classifications.json');
     writeFileSync(classPath, JSON.stringify(diffResult, null, 2));
@@ -1402,6 +1769,10 @@ async function siteReplayAndDiff(
     mp.clear();
     mp.remove('replay');
 
+    const sourcesLabel =
+      crossRecordingCount > 0
+        ? `replay + ${crossRecordingCount} recording${crossRecordingCount === 1 ? '' : 's'}`
+        : 'replay';
     const nonConstant = diffResult.classifications.filter((c) => c.classification !== 'constant');
     if (nonConstant.length > 0) {
       const counts: Record<string, number> = {};
@@ -1410,10 +1781,12 @@ async function siteReplayAndDiff(
         .map(([k, v]) => `${v} ${k}`)
         .join(', ');
       p.log.info(
-        `Dual-pass: ${nonConstant.length} ephemeral values (${breakdown}). ${replayRequests.length} requests captured.`,
+        `Dual-pass (${sourcesLabel}): ${nonConstant.length} ephemeral values (${breakdown}). ${replayRequests.length} requests captured.`,
       );
     } else {
-      p.log.info(`Dual-pass: all values constant. ${replayRequests.length} requests captured.`);
+      p.log.info(
+        `Dual-pass (${sourcesLabel}): all values constant. ${replayRequests.length} requests captured.`,
+      );
     }
 
     mp.render();
@@ -1427,55 +1800,9 @@ async function siteReplayAndDiff(
   }
 }
 
-export async function mapLimit<T, R>(
-  items: T[],
-  concurrency: number,
-  fn: (item: T) => Promise<R>,
-): Promise<R[]> {
-  const results = new Array<R>(items.length);
-  let next = 0;
-  let firstError: unknown;
-  const workers = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
-    while (next < items.length && firstError === undefined) {
-      const index = next++;
-      const item = items[index];
-      if (item === undefined) continue;
-      try {
-        results[index] = await fn(item);
-      } catch (err) {
-        firstError ??= err;
-      }
-    }
-  });
-  await Promise.allSettled(workers);
-  if (firstError !== undefined) throw firstError;
-  return results;
-}
-
-type SettledResult<R> = { ok: true; value: R } | { ok: false; error: unknown };
-
-export async function mapLimitSettled<T, R>(
-  items: T[],
-  concurrency: number,
-  fn: (item: T) => Promise<R>,
-): Promise<SettledResult<R>[]> {
-  const results = new Array<SettledResult<R>>(items.length);
-  let next = 0;
-  const workers = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
-    while (next < items.length) {
-      const index = next++;
-      const item = items[index];
-      if (item === undefined) continue;
-      try {
-        results[index] = { ok: true, value: await fn(item) };
-      } catch (err) {
-        results[index] = { ok: false, error: err };
-      }
-    }
-  });
-  await Promise.allSettled(workers);
-  return results;
-}
+// Bounded-concurrency fan-out helpers now live in concurrency.ts (so teach-plan.ts
+// can reuse them without an import cycle). Re-exported here for existing callers.
+export { mapLimit, mapLimitSettled };
 
 // ─── Credential capture (interactive) ───────────────────────────────────────
 
@@ -1568,6 +1895,92 @@ async function promptAndPersistCredentials(opts: {
   };
 }
 
+/** Find request seqs whose body contains a password-shaped key (per the
+ *  shared sensitive-keys dictionary) — regardless of whether credential
+ *  extraction succeeded in pairing it with a username.
+ *
+ *  Used by the post-redact pairing audit to detect the failure mode where
+ *  a recorded login *did* happen but the extractor couldn't pair its
+ *  fields, so the redacted session has no `${credential.X}` placeholders
+ *  and the compile stage will template credentials as plain parameters.
+ *
+ *  Body shapes covered:
+ *    - JSON (any nesting depth)
+ *    - form-urlencoded (`a=b&c=d`)
+ *    - multipart/form-data (sniffed by leading `--<boundary>`)
+ *    - URL query string (covers GET-based logins)
+ *
+ *  The scan is intentionally lossy and fast: we substring-check for
+ *  password-like key names in the raw body text plus exact-key checks in
+ *  parsed JSON. False positives are tolerable here (one extra warning);
+ *  false negatives are not (silent failure recurrence). */
+export function findUnpairedPasswordRequests(session: Session): number[] {
+  const PASSWORD_LIKE_TOKENS = passwordLikeTokens();
+  const out: number[] = [];
+  for (const req of session.requests) {
+    let hit = false;
+    // 1. Check URL query string for password-shaped param names.
+    try {
+      const u = new URL(req.url);
+      for (const k of u.searchParams.keys()) {
+        if (isSensitiveCredentialKey(k)) {
+          hit = true;
+          break;
+        }
+      }
+    } catch {
+      // Bad URL — skip URL-side check.
+    }
+
+    // 2. Check body — try JSON first, then fall back to substring scan
+    //    that covers form-urlencoded and multipart in one pass.
+    if (!hit && req.body) {
+      const body = req.body;
+      // JSON path.
+      try {
+        const parsed = JSON.parse(body);
+        if (hasPasswordLikeKey(parsed)) hit = true;
+      } catch {
+        // Not JSON — substring scan handles form / multipart / anything
+        // else that contains the key name verbatim.
+      }
+      if (!hit) {
+        const lower = body.toLowerCase();
+        for (const tok of PASSWORD_LIKE_TOKENS) {
+          // Match a key-shaped occurrence: `"password"` (JSON), `password=`
+          // (form/query), or `name="password"` (multipart). Avoid bare
+          // substring matches that could fire on prose payloads.
+          if (
+            lower.includes(`"${tok}"`) ||
+            lower.includes(`${tok}=`) ||
+            lower.includes(`name="${tok}"`)
+          ) {
+            hit = true;
+            break;
+          }
+        }
+      }
+    }
+    if (hit) out.push(req.seq);
+  }
+  return out;
+}
+
+/** Recursive helper for findUnpairedPasswordRequests' JSON path. */
+function hasPasswordLikeKey(node: unknown): boolean {
+  if (Array.isArray(node)) {
+    for (const v of node) if (hasPasswordLikeKey(v)) return true;
+    return false;
+  }
+  if (node && typeof node === 'object') {
+    for (const [k, v] of Object.entries(node)) {
+      if (isSensitiveCredentialKey(k)) return true;
+      if (hasPasswordLikeKey(v)) return true;
+    }
+  }
+  return false;
+}
+
 /** Write `<workflowDir>/credentials.manifest.json` so consumers of the
  *  generated tool know what credentials to provision. No values, just names. */
 function exportSiteManifest(
@@ -1958,47 +2371,58 @@ async function offerSkillExport(opts: {
   }
 }
 
-// ─── Session combination (post-record, pre-redact) ────────────────────────
+// ─── Session combination (post-record or post-from-session, pre-redact) ──
 
-async function promptSessionCombine(opts: {
+async function combineAvailableSessions(opts: {
   site: string;
   currentSessionPath: string;
   noInteractive: boolean;
+  fromSession: boolean;
 }): Promise<string> {
-  if (opts.noInteractive) return opts.currentSessionPath;
-
-  const pastSessions = listSiteSessions(opts.site).filter(
-    (s) => s.absPath !== opts.currentSessionPath,
-  );
+  // Discover sibling sessions. For --from-session, look in the source
+  // directory (which may differ from the target site's sessions dir).
+  // For normal recordings, look in the site's sessions directory.
+  const pastSessions = opts.fromSession
+    ? listSessionsInDir(pathDirname(opts.currentSessionPath)).filter(
+        (s) => s.absPath !== opts.currentSessionPath,
+      )
+    : listSiteSessions(opts.site).filter((s) => s.absPath !== opts.currentSessionPath);
 
   if (pastSessions.length === 0) return opts.currentSessionPath;
 
-  const combine = await p.confirm({
-    message: `Found ${pastSessions.length} past recording session${pastSessions.length === 1 ? '' : 's'} for "${opts.site}". Combine with the new recording?`,
-    initialValue: false,
-  });
+  let selectedPaths: string[];
 
-  if (p.isCancel(combine) || !combine) return opts.currentSessionPath;
+  if (opts.noInteractive) {
+    // Auto-combine all available sessions
+    selectedPaths = pastSessions.map((s) => s.absPath);
+    p.log.info(`Auto-combining ${pastSessions.length + 1} session(s) for "${opts.site}".`);
+  } else {
+    const combine = await p.confirm({
+      message: `Found ${pastSessions.length} past recording session${pastSessions.length === 1 ? '' : 's'}${opts.fromSession ? ' in the source directory' : ` for "${opts.site}"`}. Combine with the ${opts.fromSession ? 'provided' : 'new'} recording?`,
+      initialValue: true,
+    });
 
-  const selected = await p.multiselect({
-    message:
-      'Select sessions to combine with the new recording:\n  (press [space] to toggle, [enter] to submit)',
-    required: true,
-    initialValues: pastSessions.map((s) => s.absPath),
-    options: pastSessions.map((s) => ({
-      value: s.absPath,
-      label: `${s.friendlyTimestamp} — ${s.url}`,
-      hint: `${s.requestCount} requests, ${s.narrationCount} narrations`,
-    })),
-  });
+    if (p.isCancel(combine) || !combine) return opts.currentSessionPath;
 
-  if (p.isCancel(selected)) return opts.currentSessionPath;
+    const selected = await p.multiselect({
+      message: 'Select sessions to combine:\n  (press [space] to toggle, [enter] to submit)',
+      required: true,
+      initialValues: pastSessions.map((s) => s.absPath),
+      options: pastSessions.map((s) => ({
+        value: s.absPath,
+        label: `${s.friendlyTimestamp} — ${s.url}`,
+        hint: `${s.requestCount} requests, ${s.narrationCount} narrations`,
+      })),
+    });
 
-  const selectedPaths = selected as string[];
-  if (selectedPaths.length === 0) return opts.currentSessionPath;
+    if (p.isCancel(selected)) return opts.currentSessionPath;
+
+    selectedPaths = selected as string[];
+    if (selectedPaths.length === 0) return opts.currentSessionPath;
+  }
 
   const spinner = p.spinner();
-  spinner.start('Combining sessions...');
+  spinner.start('Combining sessions');
 
   const sessions: Session[] = [];
   for (const path of selectedPaths) {
@@ -2020,8 +2444,21 @@ async function promptSessionCombine(opts: {
     ),
   );
 
-  const combined = mergeSessions(sessions);
-  const combinedPath = writeCombinedSession(opts.site, combined);
+  const { combined, combinedPath } = await traced(
+    'teach.combine_sessions',
+    'CHAIN',
+    { 'imprint.site': opts.site },
+    async (span) => {
+      const merged = mergeSessions(sessions);
+      const path = writeCombinedSession(opts.site, merged);
+      setSpanAttributes(span, {
+        'imprint.combine.session_count': sessions.length,
+        'imprint.combine.request_count': merged.requests.length,
+        'imprint.combine.narration_count': merged.narration.length,
+      });
+      return { combined: merged, combinedPath: path };
+    },
+  );
 
   spinner.stop(
     `Combined ${sessions.length} sessions (${combined.requests.length} requests, ${combined.narration.length} narrations).`,
@@ -2110,9 +2547,7 @@ async function writeQuickBackendsCache(workflowDir: string, workflow: Workflow):
         },
       };
       writeFileSync(backendsPath, `${JSON.stringify(cache, null, 2)}\n`);
-      process.stderr.write(
-        `[imprint teach] backend probe: fetch blocked → wrote ${backendsPath}\n`,
-      );
+      log(`backend probe: fetch blocked → wrote ${backendsPath}`);
     }
   } catch {
     // Fetch failed (timeout, network error) — don't write cache, let runtime discover