imprint-mcp 0.6.0 → 0.6.2

package/src/imprint/teach.ts

@@ -7,6 +7,7 @@
  * step, and multiple workflows per site (each in its own subdirectory).
  */
 
+import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import {
@@ -18,12 +19,14 @@ import {
 import * as p from '@clack/prompts';
 import type { OnDeadlineReached } from './agent.ts';
 import { compileAuthAgent } from './auth-compile-agent.ts';
+import { authWorkflowHash } from './auth-compile-tools.ts';
 import {
   type SharedModuleManifestEntry,
   buildPlanSidecarPath,
   readBuildPlanFile,
   topoLevelsForTools,
 } from './build-plan.ts';
+import type { CompileAgentResult } from './compile-agent-types.ts';
 import {
   type CompileAgentProgress,
   type TriageResult,
@@ -55,6 +58,7 @@ import {
   generateSkillMd,
 } from './integrations.ts';
 import {
+  type LLMOptions,
   type ProviderName,
   type ProviderStatus,
   detectTeachProvider,
@@ -65,6 +69,7 @@ import { loadJsonFile } from './load-json.ts';
 import { createLog, muteLog, unmuteLog } from './log.ts';
 import { MultiProgress } from './multi-progress.ts';
 import { localSiteDir, localToolDir } from './paths.ts';
+import { rebindExistingBackendsCacheToWorkflow } from './probe-backends.ts';
 import { describeAgentActivity, formatElapsed } from './progress.ts';
 import { record } from './record.ts';
 import { detectPageMintedHeaders, redactSession } from './redact.ts';
@@ -118,6 +123,37 @@ import { setSpanAttributes, shutdownTracing, traced } from './tracing.ts';
 import { CronConfigSchema, SessionSchema, WorkflowSchema } from './types.ts';
 import type { CronConfig, Playbook, Session, Workflow } from './types.ts';
 
+export function authCompileLlmConfig(provider: ProviderName, model: string): LLMOptions {
+  return { provider, model };
+}
+
+export function authCompletionMatches(
+  completion: WorkflowState['authCompletion'],
+  expected: { toolName: string; buildPlanHash: string; workflowHash: string },
+): boolean {
+  return Boolean(
+    completion &&
+      completion.toolName === expected.toolName &&
+      completion.buildPlanHash === expected.buildPlanHash &&
+      completion.workflowHash === expected.workflowHash,
+  );
+}
+
+export function hasDurableAuthState(
+  workflow: Workflow,
+  stored: { values: Record<string, string>; cookies: unknown[]; storage?: unknown[] },
+): boolean {
+  const required = workflow.authConfig?.persist ?? [];
+  if (required.length > 0) {
+    return required.every((name) => String(stored.values[name] ?? '').length > 0);
+  }
+  return stored.cookies.length > 0 || (stored.storage?.length ?? 0) > 0;
+}
+
+function fileSha256(path: string): string {
+  return createHash('sha256').update(readFileSync(path)).digest('hex');
+}
+
 export {
   buildTeachStateFromSession,
   resolveTeachStatePath,
@@ -126,9 +162,11 @@ export {
 
 /**
  * How many compile agents run in parallel when more than one tool is selected.
+ * Each compiler can now invoke a separate live semantic verifier, so keep this
+ * at 2 to avoid provider rate-limit bursts and same-site anti-bot pressure.
  * Single-tool runs still use concurrency 1.
  */
-const COMPILE_CONCURRENCY = 3;
+const COMPILE_CONCURRENCY = 2;
 
 /** Module logger — suppressed during teach's spinner phases via muteLog(). */
 const log = createLog('teach');
@@ -957,16 +995,12 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
             allLoginSeqs.length > 0
               ? {
                   sharedContext: {
-                    loginRequestSeqs: allLoginSeqs,
+                    loginRequestSeqs: credentialSeqs,
                     credentialNames: [],
                     tokenExtractionNotes: '',
                     sharedHelperNotes: '',
-                    twoFactorDetected: false,
-                    twoFactorType: 'none' as const,
-                    twoFactorRequestSeqs: [],
-                    authCompletionSeqs: [],
-                    twoFactorContext: [],
-                    twoFactorNotes: '',
+                    authRequestSeqs: allLoginSeqs,
+                    authNotes: '',
                   },
                 }
               : {},
@@ -1187,21 +1221,36 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
       });
     }
     // A `--from-step` resume into plan-prereqs/generate reconstructs the prior
-    // run's tools from persisted state (shared-module planning needs ≥2 tools, and
-    // a multi-tool generate resumes all of them) — not just the most-recent
-    // workflow. selectMultiToolResumePlans scopes this to the same recording as the
+    // 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.
+    // 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.
     const allCandidatePlans: CandidateCompilePlan[] = [];
     if (opts.fromStep) {
-      const selection = selectMultiToolResumePlans(state, workflowKey, startFrom);
+      let plannedToolNames: Set<string> | undefined;
+      const persistedBuildPlanPath = resolveTeachStatePath(site, ws?.buildPlanPath);
+      if (persistedBuildPlanPath && existsSync(persistedBuildPlanPath)) {
+        const persistedBuildPlan = readBuildPlanFile(persistedBuildPlanPath);
+        if (persistedBuildPlan) {
+          plannedToolNames = new Set(persistedBuildPlan.perTool.map((tool) => tool.toolName));
+        }
+      }
+      const selection = selectMultiToolResumePlans(state, workflowKey, startFrom, {
+        noInteractive: opts.noInteractive,
+        allTools: opts.allTools,
+        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}" for --from-step ${startFrom}: its prior run didn't reach "${startFrom}" — resume an earlier step or re-run it.`,
+            : 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.`,
         );
       }
       for (const sel of selection.plans) {
@@ -1273,7 +1322,7 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
   // full) while dropping the bulk of telemetry/asset/noise requests — e.g. 415
   // vs 4396 requests on a big multi-tool site. Handing the agent the entire
   // redacted recording instead makes it burn its turn/time budget exploring
-  // thousands of irrelevant requests (the amex auth compile never converged on a
+  // thousands of irrelevant requests (large auth recordings otherwise may never converge on a
   // playbook because of this). The detect-candidates summary already triages;
   // this aligns the compile session with it.
   const triagedCandidate = redactedPath?.replace(/\.redacted\.json$/, '.triaged.json');
@@ -1398,92 +1447,142 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
   // before any tool (auth or data) compiles.
   if (stopIdx < STEPS.indexOf('generate')) await finishEarly();
 
+  if (authDetected && willGenerate && !buildPlanPath) {
+    throw new Error(
+      'Authentication was detected, but auth planning did not produce a build plan. Data-tool compilation was not started.',
+    );
+  }
+
   // ── auth-tool: agentic compile loop + interactive 2FA ──
   if (buildPlanPath && willGenerate) {
     const buildPlan = readBuildPlanFile(buildPlanPath);
     if (buildPlan?.authTool) {
       const authPlan = buildPlan.authTool;
-      const redactedSession = SessionSchema.parse(
-        JSON.parse(readFileSync(compileSessionPath, 'utf8')),
+      const buildPlanHash = fileSha256(buildPlanPath);
+      const existingAuthWorkflowPath = pathJoin(
+        localToolDir(site, authPlan.toolName),
+        'workflow.json',
       );
-      // Passwordless / OTP-only logins (e.g. email + emailed code, magic link)
-      // carry no password for the username+password extractor to pair, so
-      // teachCredentials is empty. Derive the planner-declared credential values
-      // from the recorded login request(s), persist them, and back-fill
-      // ${credential.X} into the redacted session the agent reads.
-      if (!teachCredentials && sessionPath && existsSync(sessionPath)) {
-        try {
-          const rawForCreds = SessionSchema.parse(JSON.parse(readFileSync(sessionPath, 'utf8')));
-          const derived = deriveLoginCredentials(
-            rawForCreds,
-            authPlan.loginRequestSeqs,
+      const existingAuthIndexPath = pathJoin(localToolDir(site, authPlan.toolName), 'index.ts');
+      const existingAuthWorkflow =
+        existsSync(existingAuthWorkflowPath) && existsSync(existingAuthIndexPath)
+          ? WorkflowSchema.parse(JSON.parse(readFileSync(existingAuthWorkflowPath, 'utf8')))
+          : undefined;
+      const storedAuthState = existingAuthWorkflow
+        ? await loadSiteCredentials(site).catch(() => null)
+        : null;
+      const existingAuthWorkflowHash = existingAuthWorkflow
+        ? authWorkflowHash(existingAuthWorkflow)
+        : undefined;
+      const reusableCompletion =
+        existingAuthWorkflow &&
+        existingAuthWorkflowHash &&
+        storedAuthState &&
+        hasDurableAuthState(existingAuthWorkflow, storedAuthState)
+          ? plans
+              .map((plan) => state.workflows[plan.workflowKey]?.authCompletion)
+              .find((completion) =>
+                authCompletionMatches(completion, {
+                  toolName: authPlan.toolName,
+                  buildPlanHash,
+                  workflowHash: existingAuthWorkflowHash as string,
+                }),
+              )
+          : undefined;
+      if (reusableCompletion) {
+        p.log.info(
+          `Reusing verified auth tool "${authPlan.toolName}"; auth artifacts are unchanged.`,
+        );
+      } else {
+        const redactedSession = SessionSchema.parse(
+          JSON.parse(readFileSync(compileSessionPath, 'utf8')),
+        );
+        // A resumed generate step may still have valid credentials from an earlier
+        // successful teach. Prefer those over values reconstructed from the old
+        // recording so a stale recording cannot overwrite the credential store.
+        if (!teachCredentials) {
+          const view = await loadSiteCredentials(site).catch(() => null);
+          const storedValues = selectCompleteAuthCredentials(
+            view?.values ?? {},
             authPlan.credentialNames,
           );
-          if (Object.keys(derived.values).length > 0) {
-            const backend = await getCredentialBackend();
-            for (const [name, value] of Object.entries(derived.values)) {
-              await backend.setSecret(site, name, value);
-              upsertManifestEntry(site, {
-                name,
-                kind: 'username',
-                description: 'Login identifier',
-              });
+          if (storedValues) {
+            teachCredentials = { site, values: storedValues };
+            if (authPlan.credentialNames.length > 0) {
+              p.log.info(
+                `Using stored credentials for "${site}": ${authPlan.credentialNames.join(', ')}`,
+              );
             }
-            applyCredentialPlaceholders(redactedSession, derived.replacements);
-            teachCredentials = { site, values: derived.values };
-            p.log.success(
-              `Derived ${Object.keys(derived.values).length} credential(s) for passwordless login: ${Object.keys(derived.values).join(', ')}`,
-            );
           }
-        } catch (err) {
-          p.log.warn(
-            `Credential derivation failed: ${err instanceof Error ? err.message : String(err)}`,
-          );
         }
-      }
 
-      // The recording can't always yield credentials — hosted/redirect logins
-      // (Auth0, Okta, …) submit the password as a page navigation (no XHR body),
-      // and the capture listener masks password fields. Before skipping, reuse
-      // anything already stored, then — when interactive — prompt for exactly the
-      // credentials the detection LLM identified for this login
-      // (authPlan.credentialNames; the live 2FA code is intentionally not in that
-      // list — it's entered during verification).
-      if (!teachCredentials) {
-        const view = await loadSiteCredentials(site).catch(() => null);
-        if (view && Object.keys(view.values).length > 0) {
-          teachCredentials = { site, values: view.values };
-          p.log.info(
-            `Using stored credentials for "${site}": ${Object.keys(view.values).join(', ')}`,
-          );
-        }
-      }
-      if (!teachCredentials && !opts.noInteractive && authPlan.credentialNames.length > 0) {
-        let detectedUsername: string | undefined;
-        if (sessionPath && existsSync(sessionPath)) {
+        // Passwordless / OTP-only logins (e.g. email + emailed code, magic link)
+        // carry no password for the username+password extractor to pair, so
+        // teachCredentials can be empty. If no complete stored set exists, derive
+        // the planner-declared credential values from the recorded login request(s),
+        // persist them, and back-fill ${credential.X} into the redacted session the
+        // agent reads.
+        if (!teachCredentials && sessionPath && existsSync(sessionPath)) {
           try {
-            detectedUsername = detectRecordedUsername(
-              SessionSchema.parse(JSON.parse(readFileSync(sessionPath, 'utf8'))),
+            const rawForCreds = SessionSchema.parse(JSON.parse(readFileSync(sessionPath, 'utf8')));
+            const derived = deriveLoginCredentials(
+              rawForCreds,
+              authPlan.credentialRequestSeqs,
+              authPlan.credentialNames,
+            );
+            if (Object.keys(derived.values).length > 0) {
+              const backend = await getCredentialBackend();
+              for (const [name, value] of Object.entries(derived.values)) {
+                await backend.setSecret(site, name, value);
+                upsertManifestEntry(site, {
+                  name,
+                  kind: 'username',
+                  description: 'Login identifier',
+                });
+              }
+              applyCredentialPlaceholders(redactedSession, derived.replacements);
+              teachCredentials = { site, values: derived.values };
+              p.log.success(
+                `Derived ${Object.keys(derived.values).length} credential(s) for passwordless login: ${Object.keys(derived.values).join(', ')}`,
+              );
+            }
+          } catch (err) {
+            p.log.warn(
+              `Credential derivation failed: ${err instanceof Error ? err.message : String(err)}`,
             );
-          } catch {
-            /* best-effort pre-fill only */
           }
         }
-        teachCredentials = await promptForCredentials({
-          site,
-          names: authPlan.credentialNames,
-          detectedUsername,
-        });
-      }
 
-      if (!teachCredentials) {
-        const hint = opts.noInteractive
-          ? ` Set them with \`imprint credential set ${site} <name>\` (${authPlan.credentialNames.join(', ') || 'the login credentials'}), then resume with \`imprint teach ${site} --from-step generate\`.`
-          : '';
-        p.log.warn(
-          `Auth tool "${authPlan.toolName}" was planned but no credentials are available — skipping auth compile.${hint} Data tools will attempt inline login.`,
-        );
-      } else {
+        // The recording cannot always yield credentials because the capture layer
+        // masks sensitive fields. Reuse a complete stored set or prompt for the
+        // credential names identified during planning.
+        if (!teachCredentials && !opts.noInteractive && authPlan.credentialNames.length > 0) {
+          let detectedUsername: string | undefined;
+          if (sessionPath && existsSync(sessionPath)) {
+            try {
+              detectedUsername = detectRecordedUsername(
+                SessionSchema.parse(JSON.parse(readFileSync(sessionPath, 'utf8'))),
+              );
+            } catch {
+              /* best-effort pre-fill only */
+            }
+          }
+          teachCredentials = await promptForCredentials({
+            site,
+            names: authPlan.credentialNames,
+            detectedUsername,
+          });
+        }
+
+        if (!teachCredentials) {
+          const hint = opts.noInteractive
+            ? ` Set them with \`imprint credential set ${site} <name>\` (${authPlan.credentialNames.join(', ') || 'the login credentials'}), then resume with \`imprint teach ${site} --from-step generate\`.`
+            : '';
+          throw new Error(
+            `Auth tool "${authPlan.toolName}" was planned but no credentials are available.${hint} Data-tool compilation was not started.`,
+          );
+        }
+
         spinner.start(`Compiling auth tool: ${authPlan.toolName}`);
         try {
           muteLog();
@@ -1493,23 +1592,15 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
             sessionPath: compileSessionPath,
             authToolPlan: authPlan,
             teachCredentials,
-            llmConfig: { provider: compileProviderName },
-            // Browser-minted logins compile on the playbook rung — each live test
-            // launches a real browser (navigate + anti-bot settle + form submit),
-            // which is far slower than an API replay. Give the agent room to write
-            // and iterate a playbook, not just a workflow.json.
+            llmConfig: authCompileLlmConfig(compileProviderName, compileModel),
             maxDurationMs: 20 * 60 * 1000,
             onProgress: (prog) => spinner.message(formatAuthProgress(prog)),
-            // Interactive 2FA bridge: the agent (via the verification stage) reaches
-            // the OTP/push challenge, then asks the user — here — for the live second
-            // factor. Stop the spinner + unmute logs around the prompt so it renders
-            // cleanly, then restore. Omitted in --no-interactive (the agent falls
-            // back to an unattended placeholder attempt).
+            // Render agent-requested user input outside the spinner.
             onPrompt: opts.noInteractive
               ? undefined
               : async (message, options) => {
                   unmuteLog();
-                  spinner.stop('2FA required — your input needed.');
+                  spinner.stop('Authentication requires your input.');
                   let answer = '';
                   if (options && options.length > 0) {
                     const sel = await p.select({
@@ -1522,16 +1613,15 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
                     answer = p.isCancel(txt) ? '' : String(txt ?? '');
                   }
                   muteLog();
-                  spinner.start('Completing 2FA verification');
+                  spinner.start('Continuing authentication verification');
                   return answer;
                 },
-            // Cool-off bridge: wait out a rate-flag with NO login, informing the
-            // user. Bounded to 10 min; overridable via IMPRINT_AUTH_COOLOFF_MS.
+            // Honor an agent-requested delay without firing a live action.
             onCooldown: async (minutes, reason) => {
               const envMs = Number(process.env.IMPRINT_AUTH_COOLOFF_MS);
               const ms = Number.isFinite(envMs)
                 ? Math.max(0, envMs)
-                : Math.min(Math.max(minutes, 1), 10) * 60_000;
+                : Math.max(0, minutes) * 60_000;
               unmuteLog();
               p.log.info(
                 `Cooling off ~${Math.round(ms / 60000)} min before retrying the login${reason ? ` (${reason})` : ''} — no login fires during the wait.`,
@@ -1543,36 +1633,43 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
           });
           unmuteLog();
 
-          if (!authResult.success || !authResult.workflowPath) {
-            spinner.stop('Auth tool compilation failed.');
-            p.log.warn(`Auth agent: ${authResult.message}\nData tools will attempt inline login.`);
-          } else {
-            emit({
-              workflowPath: authResult.workflowPath,
-              outDir: pathDirname(authResult.workflowPath),
-              force: true,
-            });
-            // The point of completing auth is a stored session token the data
-            // tools reuse. Confirm one was persisted before claiming success.
-            let sessionStored = false;
-            try {
-              const { loadSiteCredentials } = await import('./credential-store.ts');
-              const view = await loadSiteCredentials(site);
-              sessionStored = view.cookies.length > 0 || Object.keys(view.values).length > 0;
-            } catch {
-              /* non-fatal */
+          assertSuccessfulAuthCompile(authResult);
+          emit({
+            workflowPath: authResult.workflowPath,
+            outDir: pathDirname(authResult.workflowPath),
+            force: true,
+          });
+          const emittedWorkflow = WorkflowSchema.parse(
+            JSON.parse(readFileSync(authResult.workflowPath, 'utf8')),
+          );
+          const storedState = await loadSiteCredentials(site).catch(() => null);
+          const sessionStored = Boolean(
+            storedState && hasDurableAuthState(emittedWorkflow, storedState),
+          );
+          const completion = {
+            toolName: authPlan.toolName,
+            buildPlanHash,
+            workflowHash: authWorkflowHash(emittedWorkflow),
+            completedAt: new Date().toISOString(),
+          };
+          if (sessionStored) {
+            for (const plan of plans) {
+              const ws = state.workflows[plan.workflowKey];
+              if (ws) ws.authCompletion = completion;
             }
-            spinner.stop(
-              sessionStored
-                ? `Auth tool compiled + session stored (${authResult.turns} turns, ${Math.round(authResult.durationMs / 1000)}s) — data tools will reuse it.`
-                : `Auth tool compiled (${authResult.turns} turns) — no live session stored; data tools will be unverified until you run \`imprint login ${site}\`.`,
-            );
+            saveTeachState(site, state);
           }
+          spinner.stop(
+            sessionStored
+              ? `Auth tool compiled + session stored (${authResult.turns} turns, ${Math.round(authResult.durationMs / 1000)}s) — data tools will reuse it.`
+              : `Auth tool compiled (${authResult.turns} turns) — no live session stored; data tools will be unverified until you run \`imprint login ${site}\`.`,
+          );
         } catch (err) {
           unmuteLog();
           spinner.stop('Auth tool compilation failed.');
-          p.log.warn(
-            `Auth tool failed: ${err instanceof Error ? err.message : String(err)}\nData tools will attempt inline login.`,
+          throw new Error(
+            `Auth stage failed; data-tool compilation was not started: ${err instanceof Error ? err.message : String(err)}`,
+            { cause: err },
           );
         }
       }
@@ -1602,6 +1699,7 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
       allTools: opts.allTools,
       buildPlanPath: buildPlanPath || undefined,
       sharedModules: sharedModulesManifest.length > 0 ? sharedModulesManifest : undefined,
+      resumeExistingArtifacts: Boolean(opts.fromStep),
     });
   } finally {
     unmuteLog();
@@ -1695,6 +1793,21 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
     }
   }
 
+  // Capability reductions are agent decisions, not silent compile losses.
+  // Keep the reasoning in workflow.json and repeat it in the final teach
+  // result so operators can distinguish an intentionally smaller honest tool
+  // from a compiler that simply forgot an input.
+  for (const result of results) {
+    for (const limitation of result.workflow.limitations ?? []) {
+      const omitted = limitation.omittedParameters?.length
+        ? `; omitted inputs: ${limitation.omittedParameters.join(', ')}`
+        : '';
+      p.log.warn(
+        `tool "${result.workflow.toolName}" capability limitation — ${limitation.feature}: ${limitation.reason}${omitted}`,
+      );
+    }
+  }
+
   // `--to-step emit/generate/compile-playbook` runs the per-tool compile but stops
   // before register (platform integration) — inWindow('register') already skipped
   // it above. Finish with the phase-window summary instead of the normal "Done!"
@@ -1839,6 +1952,9 @@ async function compileCandidatePlans(opts: {
   buildPlanPath?: string;
   /** Shared-module build manifest (verified flags) for this site. */
   sharedModules?: SharedModuleManifestEntry[];
+  /** The user explicitly resumed a prior teach phase; generated artifacts that
+   *  already exist are revision inputs, not disposable scratch output. */
+  resumeExistingArtifacts?: boolean;
 }): Promise<TeachToolResult[]> {
   const concurrency = opts.plans.length === 1 ? 1 : COMPILE_CONCURRENCY;
   const mp = opts.plans.length > 1 ? new MultiProgress() : null;
@@ -2058,6 +2174,32 @@ function renderCompileSummary(summary: CompileOutcomeSummary): string[] {
   return lines;
 }
 
+type SuccessfulAuthCompile = CompileAgentResult & { success: true; workflowPath: string };
+
+export function assertSuccessfulAuthCompile(
+  result: CompileAgentResult,
+): asserts result is SuccessfulAuthCompile {
+  if (!result.success) {
+    throw new Error(`Auth agent did not complete successfully: ${result.message}`);
+  }
+  if (!result.workflowPath) {
+    throw new Error('Auth agent reported success without producing workflow.json.');
+  }
+}
+
+export function selectCompleteAuthCredentials(
+  values: Record<string, string>,
+  requiredNames: string[],
+): Record<string, string> | null {
+  const selected: Record<string, string> = {};
+  for (const name of requiredNames) {
+    const value = values[name];
+    if (typeof value !== 'string' || value.length === 0) return null;
+    selected[name] = value;
+  }
+  return selected;
+}
+
 async function compileSelectedCandidate(opts: {
   plan: CandidateCompilePlan;
   site: string;
@@ -2074,12 +2216,15 @@ async function compileSelectedCandidate(opts: {
   teachCredentials?: { site: string; values: Record<string, string> };
   buildPlanPath?: string;
   sharedModules?: SharedModuleManifestEntry[];
+  resumeExistingArtifacts?: boolean;
 }): Promise<TeachToolResult> {
   const { plan, site, state } = opts;
   const startIdx = STEPS.indexOf(plan.startFrom);
   const toolName = plan.candidate?.toolName ?? plan.workflowKey;
   const workflowDir = localToolDir(site, toolName);
   mkdirSync(workflowDir, { recursive: true });
+  const revisionMode =
+    Boolean(opts.resumeExistingArtifacts) && existsSync(pathJoin(workflowDir, 'workflow.json'));
 
   // The per-tool compile (generate → compile-playbook → emit) is ATOMIC by design:
   // each phase gates on startIdx ONLY (not the window's stopIdx), so once started it
@@ -2098,19 +2243,20 @@ async function compileSelectedCandidate(opts: {
     // 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 toolPlan =
+      plan.candidate && !revisionMode
+        ? 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,
@@ -2127,6 +2273,7 @@ async function compileSelectedCandidate(opts: {
       buildPlanPath: opts.buildPlanPath,
       sharedModules: opts.sharedModules,
       toolPlan,
+      revisionMode,
     });
 
     assertCandidateToolName('Compiled workflow', result.workflow.toolName, plan.candidate);
@@ -2148,6 +2295,16 @@ async function compileSelectedCandidate(opts: {
   if (!genResult) {
     throw new Error(`generate step did not produce a workflow for "${toolName}".`);
   }
+  // Semantic verification may revise the workflow after generate() returns
+  // (for example, omitting an unsupported secondary parameter and recording a
+  // limitation). Reload that final artifact before compiling any fallback so
+  // later agents cannot work from the pre-verification object.
+  genResult.workflow = loadJsonFile(
+    genResult.workflowPath,
+    WorkflowSchema,
+    { notFound: `workflow.json not found at ${genResult.workflowPath}` },
+    'workflow.json',
+  );
 
   // ── Step 2: compile-playbook (after generate — runtime artifact, not needed for dual-pass) ──
   let pbResult: { playbook: Playbook; playbookPath: string };
@@ -2157,6 +2314,7 @@ async function compileSelectedCandidate(opts: {
       outPath: pathJoin(workflowDir, 'playbook.yaml'),
       llmConfig: { provider: opts.providerName },
       candidate: plan.candidate,
+      workflow: genResult.workflow,
       sharedContext: plan.sharedContext,
       preTriagedSession: opts.sharedTriageResult,
     });
@@ -2187,6 +2345,11 @@ async function compileSelectedCandidate(opts: {
 
   exportSiteManifest(site, workflowDir, genResult.workflow, pbResult.playbook);
 
+  // Emission and post-verification annotations can change workflow.json's
+  // metadata hash without changing the already-proven transport behavior.
+  // Reuse the existing no-network rebind so a bounded resume does not trigger
+  // an unnecessary comprehensive probe on its first real call.
+  rebindExistingBackendsCacheToWorkflow(workflowDir);
   await writeQuickBackendsCache(workflowDir, genResult.workflow);
 
   return {
@@ -3022,21 +3185,14 @@ function formatCompileProgress(progress: CompileAgentProgress): string {
   return `Compiling • ${activity} (${formatElapsed(progress.elapsedMs)}${retry})`;
 }
 
-/** Build the auth-compile spinner line. Pure (formatting only). The turn is
- *  monotonic across resumable segments (no per-segment reset). When the most
- *  recent live verification FAILED, surface the reason (phase + error + HTTP
- *  status) and which live-login attempt of the budget it was — so the user sees
- *  what happened and why it's taking longer, not a silently-resetting counter. */
+/** Build the auth-compile spinner line. Turns stay monotonic across resumed
+ *  segments; live failures surface the requested action and observed status. */
 export function formatAuthProgress(progress: CompileAgentProgress): string {
   const base = `Auth compile: turn ${progress.turn}`;
   const lv = progress.lastVerification;
   if (lv && !lv.ok) {
     const status = typeof lv.status === 'number' ? ` HTTP ${lv.status}` : '';
-    const attempt =
-      typeof progress.attempt === 'number' && typeof progress.maxAttempts === 'number'
-        ? `; attempt ${progress.attempt}/${progress.maxAttempts}`
-        : '';
-    return `${base} — verify ${lv.phase} FAILED (${lv.error ?? 'error'}${status})${attempt} — agent retrying`;
+    return `${base} — verify ${lv.action} FAILED (${lv.error ?? 'error'}${status}) — agent revising`;
   }
   return base;
 }