imprint-mcp 0.4.1 → 0.4.2

package/README.md

@@ -180,6 +180,8 @@ When an API call gets blocked, Imprint doesn't jump to DOM replay. It escalates
 
 The full order is `fetch → fetch-bootstrap → cdp-replay → stealth-fetch → playbook`; `auto` mode walks it and stops at the first backend that works.
 
+For bot-protected sites, `imprint probe-backends <site> --tool <toolName>` writes a `backends.json` preference cache so cron and MCP start from the known-good backend instead of rediscovering blocked rungs. Use `imprint probe-backends <site> --all` to refresh every tool in a multi-tool site; `imprint mcp status` reports stale or invalid backend caches before they quietly fall back to the default ladder. CDP replay records both cold and warm timings when it succeeds: a timeout-safe cold start may rank by its fast warm runtime, but a cold start above the preferred threshold stays behind cold-safe backends in durable cache order.
+
 Every recording compiles to *both* `workflow.json` and `playbook.yaml`, so the ladder always has a DOM fallback.
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "imprint-mcp",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "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": {
@@ -63,6 +63,7 @@
     "playwright-extra": "^4.3.6",
     "puppeteer-extra-plugin-stealth": "^2.11.2",
     "redactum": "^1.1.0",
+    "semver": "^7.8.4",
     "yaml": "^2.8.4",
     "zod": "^3.24.0"
   },
@@ -72,6 +73,7 @@
     "@types/chrome-remote-interface": "^0.31.14",
     "@types/node": "^22.10.0",
     "@types/node-cron": "^3.0.11",
+    "@types/semver": "^7.7.1",
     "knip": "^5.0.0",
     "madge": "^8.0.0",
     "typescript": "^5.7.0"

package/src/cli.ts

@@ -346,9 +346,13 @@ export const VERB_HELP: Record<string, VerbHelp> = {
   },
   'probe-backends': {
     summary: 'Try each backend once and cache the working order to backends.json.',
-    usage: ['imprint probe-backends <site> [--tool <toolName>] [--out <path>] [--param k=v]…'],
+    usage: [
+      'imprint probe-backends <site> [--tool <toolName>] [--out <path>] [--param k=v]…',
+      'imprint probe-backends <site> --all [--param k=v]…',
+    ],
     flags: [
       { name: '--tool <toolName>', description: 'Select a generated tool for multi-tool sites.' },
+      { name: '--all', description: 'Probe every generated tool for the site.' },
       { name: '--out <path>', description: 'Override backends.json output path.' },
       { name: '--param k=v', description: 'Override a workflow parameter (repeatable).' },
     ],
@@ -451,6 +455,17 @@ export const VERB_HELP: Record<string, VerbHelp> = {
     ],
     example: 'imprint mcp status',
   },
+  update: {
+    summary: 'Check for updates and install the latest version of imprint.',
+    usage: ['imprint update [--check]'],
+    flags: [
+      {
+        name: '--check',
+        description: 'Only check whether an update is available; do not install.',
+      },
+    ],
+    example: 'imprint update',
+  },
 };
 
 function printVerbHelp(verb: string): void {
@@ -621,7 +636,7 @@ async function main(argv: string[]): Promise<number> {
 
     case 'doctor': {
       const { doctor, reportDoctor } = await import('./imprint/doctor.ts');
-      const report = reportDoctor(doctor());
+      const report = reportDoctor(await doctor());
       for (const line of report.lines) console.log(line);
       return report.ok ? 0 : 1;
     }
@@ -1201,6 +1216,7 @@ async function main(argv: string[]): Promise<number> {
       const { values } = parseArgs({
         args: argv.slice(2),
         options: {
+          all: { type: 'boolean' },
           out: { type: 'string' },
           tool: { type: 'string' },
           param: { type: 'string', multiple: true },
@@ -1209,7 +1225,30 @@ async function main(argv: string[]): Promise<number> {
       });
       const overrides = tryParseParamKV(values.param);
       if (overrides === null) return 2;
-      const { probeBackends } = await import('./imprint/probe-backends.ts');
+      if (values.all && values.tool) {
+        console.error('error: --all cannot be combined with --tool');
+        return 2;
+      }
+      if (values.all && values.out) {
+        console.error('error: --all cannot be combined with --out');
+        return 2;
+      }
+      const { probeAllBackends, probeBackends } = await import('./imprint/probe-backends.ts');
+      if (values.all) {
+        const results = await probeAllBackends({
+          site,
+          paramOverrides: Object.keys(overrides).length > 0 ? overrides : undefined,
+        });
+        for (const result of results) {
+          console.log(`[imprint] probed → ${result.outPath}`);
+          console.log(`[imprint] preferred order: ${result.cache.preferredOrder.join(' → ')}`);
+        }
+        console.log('');
+        console.log(
+          '[imprint] cron + mcp-server now skip futile rungs at startup using these caches.',
+        );
+        return 0;
+      }
       const result = await probeBackends({
         site,
         outPath: values.out,
@@ -1482,6 +1521,38 @@ async function main(argv: string[]): Promise<number> {
       return 0;
     }
 
+    case 'update': {
+      const { checkForUpdate, performUpdate } = await import('./imprint/update.ts');
+      const checkOnly = argv.slice(1).includes('--check');
+      if (checkOnly) {
+        const result = await checkForUpdate();
+        if (!result) {
+          console.error('Could not reach npm registry.');
+          return 1;
+        }
+        console.log(`Current: v${result.current}`);
+        console.log(`Latest:  v${result.latest}`);
+        if (result.updateAvailable) {
+          console.log('\nUpdate available — run `imprint update` to install.');
+        } else {
+          console.log('\nAlready up to date.');
+        }
+        return 0;
+      }
+      console.log('Checking for updates...');
+      const result = await performUpdate();
+      if (result.from === result.to && result.ok) {
+        console.log(`imprint v${result.from} is already the latest version.`);
+        return 0;
+      }
+      if (result.ok) {
+        console.log(`Updated imprint: v${result.from} → v${result.to}`);
+        return 0;
+      }
+      console.error(`Update failed: ${result.error}`);
+      return 1;
+    }
+
     default: {
       const suggestion = closestVerb(verb);
       const tail = suggestion ? `did you mean \`imprint ${suggestion}\`?` : 'run `imprint --help`';

package/src/imprint/backend-ladder.ts

@@ -317,7 +317,8 @@ export async function runWithLadder(
           result = await runCdpReplay(tool, params, options?.cdpPool);
           break;
         case 'stealth-fetch': {
-          const sf = ensureStealthFetch(tool, stealthCache);
+          const paramsWithDefaults = withWorkflowDefaults(tool.workflow, params);
+          const sf = await ensureStealthFetch(tool, stealthCache, paramsWithDefaults);
           // When the workflow declares a bootstrap block, mint its declared
           // session-token state (CSRF cookies etc.) from the SAME stealth
           // session that provides the transport cookies. Without this, a
@@ -327,7 +328,7 @@ export async function runWithLadder(
           const initialState = tool.workflow.bootstrap
             ? await stealthBootstrapState(sf, tool.workflow.bootstrap)
             : undefined;
-          result = await tool.toolFn(params, { fetchImpl: sf.fetchImpl, initialState });
+          result = await tool.toolFn(paramsWithDefaults, { fetchImpl: sf.fetchImpl, initialState });
           break;
         }
         case 'playbook': {
@@ -1213,8 +1214,21 @@ async function stealthBootstrapState(
   return state;
 }
 
-function ensureStealthFetch(tool: ResolvedTool, cache: Map<string, StealthFetch>): StealthFetch {
-  const cached = cache.get(tool.site);
+async function ensureStealthFetch(
+  tool: ResolvedTool,
+  cache: Map<string, StealthFetch>,
+  params: Record<string, string | number | boolean>,
+): Promise<StealthFetch> {
+  const credentials = (await loadCredentialStore(tool.site)) ?? {
+    site: tool.site,
+    cookies: [],
+    values: {},
+  };
+  const bootstrapUrl = tool.workflow.bootstrap?.url
+    ? substituteString(tool.workflow.bootstrap.url, params, credentials, [], 'url')
+    : undefined;
+  const cacheKey = bootstrapUrl ? `${tool.site}:${bootstrapUrl}` : tool.site;
+  const cached = cache.get(cacheKey);
   if (cached) return cached;
   const sf = createStealthFetch({
     baseUrl: pickBaseUrl(tool),
@@ -1223,9 +1237,9 @@ function ensureStealthFetch(tool: ResolvedTool, cache: Map<string, StealthFetch>
     // minted in the same session as the anti-bot cookies. Otherwise the
     // stealth rung can't satisfy a `${state.X}` the workflow bootstrap was
     // supposed to provide, and escalation from fetch-bootstrap dead-ends.
-    bootstrapUrl: tool.workflow.bootstrap?.url,
+    bootstrapUrl,
   });
-  cache.set(tool.site, sf);
+  cache.set(cacheKey, sf);
   return sf;
 }
 

package/src/imprint/cron.ts

@@ -16,7 +16,7 @@ import { loadJsonFile } from './load-json.ts';
 import { createLog, isDebug } from './log.ts';
 import { evaluateNotifyWhen, notify } from './notify.ts';
 import { imprintHomeDir } from './paths.ts';
-import { loadBackendsCache } from './probe-backends.ts';
+import { loadBackendsCache, persistRuntimeBackendsCache } from './probe-backends.ts';
 import { checkSiteCredentialsReady } from './runtime.ts';
 import { availableSitesHint } from './sites.ts';
 import type { StealthFetch } from './stealth-fetch.ts';
@@ -100,6 +100,19 @@ async function runOnce(
   }
 
   if (result.ok) {
+    try {
+      const cache = persistRuntimeBackendsCache({
+        tool,
+        assetRoot,
+        usedBackend,
+        attempts,
+      });
+      if (cache) log(`  learned backend order: ${cache.preferredOrder.join(' → ')}`);
+    } catch (err) {
+      log(
+        `  warning: could not persist backend order: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
     const data = typeof result.data === 'string' ? result.data : JSON.stringify(result.data);
     // Cap the inline preview at ~500 chars; full payload available via
     // IMPRINT_DEBUG=1. Long-running daemons flood stderr otherwise.

package/src/imprint/doctor.ts

@@ -8,6 +8,7 @@ import { join as pathJoin } from 'node:path';
 import { findChromium } from './chromium.ts';
 import { defaultHermesConfigPath } from './install.ts';
 import { getProviderStatuses } from './llm.ts';
+import { checkForUpdate } from './update.ts';
 import { VERSION } from './version.ts';
 
 export interface CheckResult {
@@ -17,9 +18,10 @@ export interface CheckResult {
   fix?: string;
 }
 
-export function doctor(): CheckResult[] {
+export async function doctor(): Promise<CheckResult[]> {
   return [
     checkBun(),
+    await checkLatestVersion(),
     checkChromium(),
     checkPlaywrightChromium(),
     checkVirtualDisplay(),
@@ -31,6 +33,22 @@ export function doctor(): CheckResult[] {
   ];
 }
 
+async function checkLatestVersion(): Promise<CheckResult> {
+  const result = await checkForUpdate();
+  if (!result) {
+    return { name: 'Latest version', ok: true, detail: `v${VERSION} (could not reach registry)` };
+  }
+  if (!result.updateAvailable) {
+    return { name: 'Latest version', ok: true, detail: `v${VERSION} (up to date)` };
+  }
+  return {
+    name: 'Latest version',
+    ok: true,
+    detail: `v${result.current} → v${result.latest} available`,
+    fix: 'run: imprint update',
+  };
+}
+
 function checkBun(): CheckResult {
   const v = process.versions.bun;
   if (!v) {

package/src/imprint/mcp-maintenance.ts

@@ -27,6 +27,7 @@ import {
 import * as p from '@clack/prompts';
 import YAML from 'yaml';
 import { imprintHomeDir, localSiteDir } from './paths.ts';
+import { type BackendsCacheStatus, loadBackendsCacheStatus } from './probe-backends.ts';
 import {
   type WorkflowState,
   loadTeachState,
@@ -38,7 +39,7 @@ import {
 
 type McpClient = 'claude-code' | 'codex' | 'claude-desktop' | 'openclaw' | 'hermes';
 type LocalDeleteMode = 'none' | 'tool' | 'site';
-type IssueKind = 'missing-session' | 'stale-registration';
+type IssueKind = 'missing-session' | 'stale-registration' | 'stale-backends' | 'invalid-backends';
 
 const CLIENTS: McpClient[] = ['claude-code', 'codex', 'claude-desktop', 'openclaw', 'hermes'];
 const DISABLED_STORE_VERSION = 1;
@@ -81,6 +82,15 @@ interface LocalToolStatus {
   hasPlaybook: boolean;
   hasBackends: boolean;
   hasCron: boolean;
+  backendCache: PublicBackendsCacheStatus;
+}
+
+interface PublicBackendsCacheStatus {
+  status: BackendsCacheStatus['status'];
+  path: string | null;
+  preferredOrder?: string[];
+  reason?: string;
+  remediation?: string;
 }
 
 interface LocalWorkflowStatus {
@@ -475,7 +485,13 @@ function cmdStatus(argv: string[]): number {
   const status = scanMcpStatus({ site });
   if (flags.json === true) console.log(JSON.stringify(status, null, 2));
   else console.log(formatMcpStatus(status));
-  return status.issues.some((i) => i.kind === 'stale-registration' || i.kind === 'missing-session')
+  return status.issues.some(
+    (i) =>
+      i.kind === 'stale-registration' ||
+      i.kind === 'missing-session' ||
+      i.kind === 'stale-backends' ||
+      i.kind === 'invalid-backends',
+  )
     ? 1
     : 0;
 }
@@ -691,6 +707,11 @@ function issueFixHint(issue: McpIssue): string | null {
       return `choose "Fix an issue" or run: imprint mcp delete ${issue.name ?? `imprint-${issue.site}`} --client ${issue.client ?? 'all'} --yes`;
     case 'missing-session':
       return `choose "Fix an issue" or run: imprint mcp prune-state --site ${issue.site} --missing-session --yes`;
+    case 'stale-backends':
+    case 'invalid-backends':
+      return issue.path
+        ? `run: imprint probe-backends ${issue.site}${issue.workflow ? ` --tool ${issue.workflow}` : ''}`
+        : `run: imprint probe-backends ${issue.site}${issue.workflow ? ` --tool ${issue.workflow}` : ''}`;
   }
   return null;
 }
@@ -712,26 +733,32 @@ function scanLocalSites(ctx: MaintenanceContext): LocalSiteStatus[] {
     if (entry === 'node_modules' || entry.startsWith('.')) continue;
     const dir = pathJoin(ctx.imprintHome, entry);
     if (!safeIsDir(dir)) continue;
-    sites.push(scanLocalSite(entry, dir));
+    sites.push(scanLocalSite(entry, dir, ctx.imprintHome));
   }
   return sites;
 }
 
-function scanLocalSite(site: string, dir: string): LocalSiteStatus {
+function scanLocalSite(site: string, dir: string, imprintHome: string): LocalSiteStatus {
   const tools: LocalToolStatus[] = [];
   for (const entry of readdirSync(dir).sort()) {
     if (entry === 'sessions' || entry === '_shared' || entry.startsWith('.')) continue;
     const toolDir = pathJoin(dir, entry);
     if (!safeIsDir(toolDir)) continue;
+    const toolName = workflowJsonToolName(toolDir) ?? entry;
+    const cacheStatus = loadBackendsCacheStatus(site, imprintHome, toolDir, {
+      warn: false,
+      toolName,
+    });
     tools.push({
       site,
-      toolName: entry,
+      toolName,
       dir: toolDir,
       complete: existsSync(pathJoin(toolDir, 'index.ts')),
       hasWorkflow: existsSync(pathJoin(toolDir, 'workflow.json')),
       hasPlaybook: existsSync(pathJoin(toolDir, 'playbook.yaml')),
       hasBackends: existsSync(pathJoin(toolDir, 'backends.json')),
       hasCron: existsSync(pathJoin(toolDir, 'cron.json')),
+      backendCache: publicBackendsCacheStatus(cacheStatus),
     });
   }
 
@@ -746,6 +773,29 @@ function scanLocalSite(site: string, dir: string): LocalSiteStatus {
   return { site, dir, tools, workflows };
 }
 
+function publicBackendsCacheStatus(status: BackendsCacheStatus): PublicBackendsCacheStatus {
+  if (status.status === 'ok') {
+    return {
+      status: status.status,
+      path: status.path,
+      preferredOrder: status.cache.preferredOrder,
+    };
+  }
+  if (status.status === 'missing') {
+    return {
+      status: status.status,
+      path: status.path,
+      remediation: status.remediation,
+    };
+  }
+  return {
+    status: status.status,
+    path: status.path,
+    reason: status.reason,
+    remediation: status.remediation,
+  };
+}
+
 function workflowStatus(
   site: string,
   name: string,
@@ -795,6 +845,21 @@ function collectIssues(opts: {
   const sitesByName = new Map(opts.sites.map((s) => [s.site, s]));
 
   for (const site of opts.sites) {
+    for (const tool of site.tools) {
+      if (tool.backendCache.status === 'stale' || tool.backendCache.status === 'invalid') {
+        issues.push({
+          kind: tool.backendCache.status === 'stale' ? 'stale-backends' : 'invalid-backends',
+          site: site.site,
+          workflow: tool.toolName,
+          path: tool.backendCache.path ?? undefined,
+          message:
+            tool.backendCache.status === 'stale'
+              ? `${site.site}/${tool.toolName} has a stale backends.json; runtime will fall back to the default ladder until reprobed`
+              : `${site.site}/${tool.toolName} has an invalid backends.json; runtime will fall back to the default ladder until reprobed`,
+        });
+      }
+    }
+
     for (const wf of site.workflows) {
       if (wf.missingSession) {
         issues.push({
@@ -1091,7 +1156,7 @@ function pruneTeachState(
   for (const site of sites) {
     const statePath = teachStatePath(site);
     if (!existsSync(statePath)) continue;
-    const status = scanLocalSite(site, localSiteDir(site));
+    const status = scanLocalSite(site, localSiteDir(site), ctx.imprintHome);
     const remove = new Set(
       status.workflows
         .filter(

package/src/imprint/mcp-server.ts

@@ -20,7 +20,7 @@ import { resolveLadder, runWithLadder } from './backend-ladder.ts';
 import type { CdpBrowserFetch } from './cdp-browser-fetch.ts';
 import { createLog } from './log.ts';
 import { imprintHomeDir } from './paths.ts';
-import { loadBackendsCache } from './probe-backends.ts';
+import { loadBackendsCacheStatus, persistRuntimeBackendsCache } from './probe-backends.ts';
 import { checkSiteCredentialsReady } from './runtime.ts';
 import { availableSitesHint } from './sites.ts';
 import type { StealthFetch } from './stealth-fetch.ts';
@@ -173,7 +173,7 @@ function buildServer(
 
     try {
       const ladder = resolveLadder('auto', tool.preferredOrder);
-      const { result, usedBackend } = await runWithLadder(
+      const { result, usedBackend, attempts } = await runWithLadder(
         ladder,
         tool,
         args,
@@ -209,6 +209,24 @@ function buildServer(
           content: [{ type: 'text', text: `${text}\n(backend: ${usedBackend})` }],
         };
       }
+      try {
+        const cache = persistRuntimeBackendsCache({
+          tool,
+          assetRoot,
+          usedBackend,
+          attempts,
+        });
+        if (cache) {
+          tool.preferredOrder = cache.preferredOrder;
+          log(
+            `  learned backend order for ${tool.workflow.toolName}: ${cache.preferredOrder.join(' → ')}`,
+          );
+        }
+      } catch (err) {
+        log(
+          `  warning: could not persist backend order for ${tool.workflow.toolName}: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
       const text =
         typeof result.data === 'string' ? result.data : JSON.stringify(result.data, null, 2);
       return { content: [{ type: 'text', text: `${text}\n\n(backend: ${usedBackend})` }] };
@@ -250,12 +268,19 @@ export async function runMcpServer(opts: RunMcpServerOptions): Promise<void> {
   const discovered = await discoverTools(assetRoot, opts.site, '[imprint mcp]');
   const tools: ResolvedTool[] = discovered.map((t) => {
     const playbookPath = pathResolve(t.dir, 'playbook.yaml');
-    const cache = loadBackendsCache(t.site, assetRoot, t.dir);
+    const cacheStatus = loadBackendsCacheStatus(t.site, assetRoot, t.dir, {
+      toolName: t.workflow.toolName,
+    });
+    if (cacheStatus.status === 'stale' || cacheStatus.status === 'invalid') {
+      log(
+        `  ${t.workflow.toolName}: ${cacheStatus.status} backends.json (${cacheStatus.reason}); run \`${cacheStatus.remediation}\``,
+      );
+    }
     return {
       ...t,
       inputSchema: buildJsonSchema(t.workflow.parameters),
       playbookPath: existsSync(playbookPath) ? playbookPath : undefined,
-      preferredOrder: cache?.preferredOrder,
+      preferredOrder: cacheStatus.status === 'ok' ? cacheStatus.cache.preferredOrder : undefined,
     };
   });
   if (tools.length === 0) {

package/src/imprint/probe-backends.ts

@@ -7,8 +7,9 @@
 
 import { createHash } from 'node:crypto';
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { resolve as pathResolve } from 'node:path';
+import { basename, resolve as pathResolve } from 'node:path';
 import { runWithLadder } from './backend-ladder.ts';
+import type { CdpBrowserFetch } from './cdp-browser-fetch.ts';
 import { createLog } from './log.ts';
 import { imprintHomeDir } from './paths.ts';
 import { availableSitesHint } from './sites.ts';
@@ -42,6 +43,41 @@ interface ProbeBackendsResult {
 }
 
 const log = createLog('probe');
+const DEFAULT_PREFERRED_MAX_MS = 90_000;
+
+type BackendProbeCandidate = {
+  backend: ConcreteBackend;
+  durationMs: number;
+  rankingDurationMs?: number;
+  coldDurationMs?: number;
+  warmDurationMs?: number;
+  tooSlow: boolean;
+};
+
+type BackendRuntimeAttempt = {
+  backend: ConcreteBackend;
+  outcome: 'ok' | 'escalate' | 'failed' | 'unavailable';
+  detail: string;
+  durationMs: number;
+};
+
+export type BackendsCacheStatus =
+  | {
+      status: 'missing';
+      path: string | null;
+      remediation: string;
+    }
+  | {
+      status: 'ok';
+      path: string;
+      cache: BackendsCache;
+    }
+  | {
+      status: 'stale' | 'invalid';
+      path: string;
+      reason: string;
+      remediation: string;
+    };
 
 export async function probeBackends(opts: ProbeBackendsOptions): Promise<ProbeBackendsResult> {
   const assetRoot = opts.assetRoot ?? imprintHomeDir();
@@ -59,7 +95,36 @@ export async function probeBackends(opts: ProbeBackendsOptions): Promise<ProbeBa
       `No generated tool found for site "${opts.site}".\n${availableSitesHint(assetRoot, opts.site)}\n→ run \`imprint teach ${opts.site}\` or \`imprint emit ~/.imprint/${opts.site}/<toolName>/workflow.json\` first.`,
     );
   }
-  const outPath = opts.outPath ?? pathResolve(tool.dir, 'backends.json');
+  return await probeResolvedTool(opts, assetRoot, tool, opts.outPath);
+}
+
+export async function probeAllBackends(
+  opts: Omit<ProbeBackendsOptions, 'outPath' | 'toolName'>,
+): Promise<ProbeBackendsResult[]> {
+  const assetRoot = opts.assetRoot ?? imprintHomeDir();
+  const discovered = await discoverTools(assetRoot, opts.site, '[imprint probe]');
+  if (discovered.length === 0) {
+    throw new Error(
+      `No generated tools found for site "${opts.site}".\n${availableSitesHint(assetRoot, opts.site)}\n→ run \`imprint teach ${opts.site}\` or \`imprint emit ~/.imprint/${opts.site}/<toolName>/workflow.json\` first.`,
+    );
+  }
+
+  const results: ProbeBackendsResult[] = [];
+  for (const tool of [...discovered].sort((a, b) =>
+    a.workflow.toolName.localeCompare(b.workflow.toolName),
+  )) {
+    results.push(await probeResolvedTool(opts, assetRoot, tool));
+  }
+  return results;
+}
+
+async function probeResolvedTool(
+  opts: Pick<ProbeBackendsOptions, 'site' | 'paramOverrides'>,
+  assetRoot: string,
+  tool: ResolvedTool,
+  explicitOutPath?: string,
+): Promise<ProbeBackendsResult> {
+  const outPath = explicitOutPath ?? pathResolve(tool.dir, 'backends.json');
 
   const params = resolveParams(tool, opts.paramOverrides);
 
@@ -72,59 +137,96 @@ export async function probeBackends(opts: ProbeBackendsOptions): Promise<ProbeBa
   // falls through fetch-bootstrap (~30-60s) before reaching the spliced-in
   // cdp-replay rung, wasting time on every call.
   const stealthCache = new Map<string, StealthFetch>();
+  const cdpPool = new Map<string, CdpBrowserFetch>();
   const allBackends: ConcreteBackend[] = workflowNeedsBootstrap(tool.workflow)
     ? ['fetch', 'fetch-bootstrap', 'cdp-replay', 'stealth-fetch', 'playbook']
     : ['fetch', 'stealth-fetch', 'playbook'];
   const results: BackendsCache['results'] = {};
-  const working: ConcreteBackend[] = [];
-
-  for (const backend of allBackends) {
-    log(`probing ${backend}…`);
-    const t0 = Date.now();
-    const { result, attempts } = await runWithLadder(
-      [backend],
-      tool,
-      params,
-      assetRoot,
-      stealthCache,
-    );
-    const durationMs = Date.now() - t0;
-    const attempt = attempts[0];
+  const working: BackendProbeCandidate[] = [];
+  const preferredMaxMs = preferredBackendMaxMs();
 
-    if (!attempt) {
-      results[backend] = { outcome: 'skipped', detail: 'no attempt recorded' };
-      continue;
-    }
+  try {
+    for (const backend of allBackends) {
+      log(`probing ${backend}…`);
+      const t0 = Date.now();
+      const { result, attempts } = await runWithLadder(
+        [backend],
+        tool,
+        params,
+        assetRoot,
+        stealthCache,
+        backend === 'cdp-replay' ? { cdpPool, skipBootstrapSplice: true } : undefined,
+      );
+      const durationMs = Date.now() - t0;
+      const attempt = attempts[0];
 
-    if (attempt.outcome === 'unavailable') {
-      results[backend] = { outcome: 'unavailable', detail: attempt.detail };
-      log(`  ${backend}: unavailable (${attempt.detail})`);
-      continue;
-    }
+      if (!attempt) {
+        results[backend] = { outcome: 'skipped', detail: 'no attempt recorded' };
+        continue;
+      }
 
-    if (result.ok) {
-      results[backend] = { outcome: 'ok', durationMs };
-      working.push(backend);
-      log(`  ${backend}: OK in ${durationMs}ms`);
-      continue;
-    }
+      if (attempt.outcome === 'unavailable') {
+        results[backend] = { outcome: 'unavailable', detail: attempt.detail };
+        log(`  ${backend}: unavailable (${attempt.detail})`);
+        continue;
+      }
 
-    if (result.error === 'FORBIDDEN') {
-      results[backend] = {
-        outcome: 'forbidden',
-        durationMs,
-        detail: result.message.slice(0, 200),
-      };
-      log(`  ${backend}: FORBIDDEN`);
-    } else {
-      results[backend] = {
-        outcome: 'failed',
-        durationMs,
-        error: result.error,
-        detail: result.message.slice(0, 200),
-      };
-      log(`  ${backend}: ${result.error} — ${result.message.slice(0, 100)}`);
+      if (result.ok) {
+        const warm =
+          backend === 'cdp-replay'
+            ? await probeWarmCdpReplay(tool, params, assetRoot, stealthCache, cdpPool)
+            : null;
+        const tooSlow = durationMs > preferredMaxMs;
+        const rankingDurationMs = warm?.ok ? warm.durationMs : durationMs;
+        const detailParts: string[] = [];
+        if (tooSlow)
+          detailParts.push(`cold start exceeded preferred backend threshold ${preferredMaxMs}ms`);
+        if (warm?.ok) detailParts.push(`warm cdp-replay succeeded in ${warm.durationMs}ms`);
+        else if (warm) detailParts.push(`warm cdp-replay failed: ${warm.detail}`);
+        results[backend] = {
+          outcome: 'ok',
+          durationMs,
+          ...(backend === 'cdp-replay'
+            ? {
+                coldDurationMs: durationMs,
+                ...(warm?.ok ? { warmDurationMs: warm.durationMs, rankingDurationMs } : {}),
+              }
+            : {}),
+          ...(tooSlow ? { tooSlow: true } : {}),
+          ...(detailParts.length ? { detail: detailParts.join('; ') } : {}),
+        };
+        working.push({
+          backend,
+          durationMs,
+          ...(backend === 'cdp-replay' ? { coldDurationMs: durationMs } : {}),
+          ...(warm?.ok ? { warmDurationMs: warm.durationMs, rankingDurationMs } : {}),
+          tooSlow,
+        });
+        log(
+          `  ${backend}: OK in ${durationMs}ms${warm?.ok ? ` (warm ${warm.durationMs}ms)` : ''}${tooSlow ? ' (cold slow)' : ''}`,
+        );
+        continue;
+      }
+
+      if (result.error === 'FORBIDDEN') {
+        results[backend] = {
+          outcome: 'forbidden',
+          durationMs,
+          detail: result.message.slice(0, 200),
+        };
+        log(`  ${backend}: FORBIDDEN`);
+      } else {
+        results[backend] = {
+          outcome: 'failed',
+          durationMs,
+          error: result.error,
+          detail: result.message.slice(0, 200),
+        };
+        log(`  ${backend}: ${result.error} — ${result.message.slice(0, 100)}`);
+      }
     }
+  } finally {
+    await closeProbeCdpPool(cdpPool);
   }
 
   if (working.length === 0) {
@@ -135,23 +237,71 @@ export async function probeBackends(opts: ProbeBackendsOptions): Promise<ProbeBa
     );
   }
 
+  const preferredOrder = rankSuccessfulBackends(working);
   const cache: BackendsCache = {
     probedAt: new Date().toISOString(),
     imprintVersion: VERSION,
     schemaVersion: 2,
     workflowHash: workflowHash(tool.workflow),
     capabilityHash: capabilityHash(tool.workflow),
-    preferredOrder: working,
+    preferredOrder,
     results,
   };
   BackendsCacheSchema.parse(cache); // catch schema drift early
 
   writeFileSync(outPath, `${JSON.stringify(cache, null, 2)}\n`);
-  log(`wrote ${outPath} — preferred: ${working.join(' → ')}`);
+  log(`wrote ${outPath} — preferred: ${preferredOrder.join(' → ')}`);
 
   return { cache, outPath };
 }
 
+export function rankSuccessfulBackends(candidates: BackendProbeCandidate[]): ConcreteBackend[] {
+  return [...candidates]
+    .sort((a, b) => {
+      if (a.tooSlow !== b.tooSlow) return a.tooSlow ? 1 : -1;
+      return effectiveRankingDuration(a) - effectiveRankingDuration(b);
+    })
+    .map((c) => c.backend);
+}
+
+function effectiveRankingDuration(candidate: BackendProbeCandidate): number {
+  return candidate.rankingDurationMs ?? candidate.warmDurationMs ?? candidate.durationMs;
+}
+
+function backendResultTooSlow(result: BackendsCache['results'][string] | undefined): boolean {
+  return result?.outcome === 'ok' && result.tooSlow === true;
+}
+
+async function probeWarmCdpReplay(
+  tool: ResolvedTool,
+  params: Record<string, string | number | boolean>,
+  assetRoot: string,
+  stealthCache: Map<string, StealthFetch>,
+  cdpPool: Map<string, CdpBrowserFetch>,
+): Promise<{ ok: true; durationMs: number } | { ok: false; detail: string } | null> {
+  if (!cdpPool.has(tool.site)) return null;
+  log('probing cdp-replay warm reuse…');
+  const t0 = Date.now();
+  const { result } = await runWithLadder(['cdp-replay'], tool, params, assetRoot, stealthCache, {
+    cdpPool,
+    skipBootstrapSplice: true,
+  });
+  const durationMs = Date.now() - t0;
+  if (result.ok) return { ok: true, durationMs };
+  return { ok: false, detail: `${result.error}: ${result.message.slice(0, 160)}` };
+}
+
+async function closeProbeCdpPool(cdpPool: Map<string, CdpBrowserFetch>): Promise<void> {
+  const sessions = [...cdpPool.values()];
+  cdpPool.clear();
+  await Promise.allSettled(sessions.map((session) => session.close()));
+}
+
+function preferredBackendMaxMs(): number {
+  const raw = Number(process.env.IMPRINT_BACKEND_PREFERRED_MAX_MS ?? DEFAULT_PREFERRED_MAX_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_PREFERRED_MAX_MS;
+}
+
 function workflowNeedsBootstrap(workflow: ResolvedTool['workflow']): boolean {
   if (workflow.bootstrap) return true;
   return workflow.requests.some((r) =>
@@ -177,16 +327,19 @@ function capabilityHash(workflow: ResolvedTool['workflow']): string {
   return createHash('sha256').update(JSON.stringify(caps)).digest('hex');
 }
 
-/** Read backends.json. Returns null on missing/malformed — runtime
- *  falls back to the default ladder; a stale cache must never break cron. */
-export function loadBackendsCache(
+/** Read backends.json with status information. Runtime can still fall back to
+ *  the default ladder, while status commands can explain why a cache was not
+ *  usable. */
+export function loadBackendsCacheStatus(
   site: string,
   _assetRoot: string,
   toolDir?: string,
-): BackendsCache | null {
-  if (!toolDir) return null;
+  opts: { warn?: boolean; toolName?: string } = {},
+): BackendsCacheStatus {
+  const remediation = backendsCacheRemediation(site, opts.toolName ?? toolDirName(toolDir));
+  if (!toolDir) return { status: 'missing', path: null, remediation };
   const path = pathResolve(toolDir, 'backends.json');
-  if (!existsSync(path)) return null;
+  if (!existsSync(path)) return { status: 'missing', path, remediation };
   try {
     const raw = JSON.parse(readFileSync(path, 'utf8'));
     const parsed = BackendsCacheSchema.parse(raw);
@@ -195,20 +348,129 @@ export function loadBackendsCache(
       if (existsSync(workflowPath)) {
         const currentHash = workflowHashSync(readFileSync(workflowPath, 'utf8'));
         if (currentHash !== parsed.workflowHash) {
-          process.stderr.write(
-            `[imprint] backends.json at ${path} is stale for current workflow — ignoring (run \`imprint probe-backends ${site}\` to regenerate)\n`,
-          );
-          return null;
+          const reason = 'workflow hash changed';
+          if (opts.warn !== false) {
+            process.stderr.write(
+              `[imprint] backends.json at ${path} is stale for current workflow — ignoring (run \`${remediation}\` to regenerate)\n`,
+            );
+          }
+          return { status: 'stale', path, reason, remediation };
         }
       }
     }
-    return parsed;
+    return { status: 'ok', path, cache: parsed };
   } catch (err) {
-    process.stderr.write(
-      `[imprint] backends.json at ${path} failed to parse — ignoring (run \`imprint probe-backends ${site}\` to regenerate): ${err instanceof Error ? err.message : String(err)}\n`,
-    );
-    return null;
+    const reason = err instanceof Error ? err.message : String(err);
+    if (opts.warn !== false) {
+      process.stderr.write(
+        `[imprint] backends.json at ${path} failed to parse — ignoring (run \`${remediation}\` to regenerate): ${reason}\n`,
+      );
+    }
+    return { status: 'invalid', path, reason, remediation };
+  }
+}
+
+/** Read backends.json. Returns null on missing/malformed — runtime
+ *  falls back to the default ladder; a stale cache must never break cron. */
+export function loadBackendsCache(
+  site: string,
+  _assetRoot: string,
+  toolDir?: string,
+): BackendsCache | null {
+  const status = loadBackendsCacheStatus(site, _assetRoot, toolDir);
+  return status.status === 'ok' ? status.cache : null;
+}
+
+export function persistRuntimeBackendsCache(opts: {
+  tool: ResolvedTool;
+  assetRoot: string;
+  usedBackend: ConcreteBackend;
+  attempts: BackendRuntimeAttempt[];
+}): BackendsCache | null {
+  const status = loadBackendsCacheStatus(opts.tool.site, opts.assetRoot, opts.tool.dir, {
+    warn: false,
+    toolName: opts.tool.workflow.toolName,
+  });
+  const results: BackendsCache['results'] =
+    status.status === 'ok' ? { ...status.cache.results } : {};
+
+  for (const attempt of opts.attempts) {
+    if (attempt.outcome === 'ok') {
+      const tooSlow = attempt.durationMs > preferredBackendMaxMs();
+      results[attempt.backend] = {
+        outcome: 'ok',
+        durationMs: attempt.durationMs,
+        ...(tooSlow
+          ? {
+              tooSlow: true,
+              detail: `exceeded preferred backend threshold ${preferredBackendMaxMs()}ms`,
+            }
+          : {}),
+      };
+    } else if (attempt.outcome === 'unavailable') {
+      results[attempt.backend] = { outcome: 'unavailable', detail: attempt.detail };
+    } else if (attempt.detail.startsWith('FORBIDDEN:')) {
+      results[attempt.backend] = {
+        outcome: 'forbidden',
+        durationMs: attempt.durationMs,
+        detail: attempt.detail.slice(0, 200),
+      };
+    } else {
+      const error = attempt.detail.split(':')[0] || 'UNKNOWN';
+      results[attempt.backend] = {
+        outcome: 'failed',
+        durationMs: attempt.durationMs,
+        error,
+        detail: attempt.detail.slice(0, 200),
+      };
+    }
   }
+
+  const existingPreferred = status.status === 'ok' ? status.cache.preferredOrder : [];
+  const observedOkAttempts = opts.attempts
+    .filter((a) => a.outcome === 'ok')
+    .sort((a, b) => a.durationMs - b.durationMs);
+  const observedOk = observedOkAttempts.map((a) => a.backend);
+  const slowObservedOk = observedOkAttempts
+    .filter((a) => a.durationMs > preferredBackendMaxMs())
+    .map((a) => a.backend);
+  const fastObservedOk = observedOk.filter((backend) => !slowObservedOk.includes(backend));
+  const usedOkAttempt = observedOkAttempts.find((a) => a.backend === opts.usedBackend);
+  const usedBackendTooSlow =
+    usedOkAttempt !== undefined && usedOkAttempt.durationMs > preferredBackendMaxMs();
+  const existingFast = existingPreferred.filter(
+    (backend) => !backendResultTooSlow(results[backend]),
+  );
+  const existingSlow = existingPreferred.filter((backend) =>
+    backendResultTooSlow(results[backend]),
+  );
+  const structuralFallbacks: ConcreteBackend[] = existsSync(
+    pathResolve(opts.tool.dir, 'playbook.yaml'),
+  )
+    ? ['playbook']
+    : [];
+  const preferredOrder = uniqueBackends([
+    ...(usedOkAttempt && !usedBackendTooSlow ? [opts.usedBackend] : []),
+    ...existingFast,
+    ...fastObservedOk,
+    ...existingSlow,
+    ...slowObservedOk,
+    ...(usedOkAttempt && usedBackendTooSlow ? [opts.usedBackend] : []),
+    ...structuralFallbacks,
+  ]);
+  const cache: BackendsCache = {
+    probedAt: new Date().toISOString(),
+    imprintVersion: VERSION,
+    schemaVersion: 2,
+    workflowHash: workflowHash(opts.tool.workflow),
+    capabilityHash: capabilityHash(opts.tool.workflow),
+    preferredOrder,
+    results,
+  };
+
+  BackendsCacheSchema.parse(cache);
+  writeFileSync(pathResolve(opts.tool.dir, 'backends.json'), `${JSON.stringify(cache, null, 2)}\n`);
+  return cache;
 }
 
 function workflowHashSync(workflowJson: string): string {
@@ -217,6 +479,27 @@ function workflowHashSync(workflowJson: string): string {
     .digest('hex');
 }
 
+function backendsCacheRemediation(site: string, toolName?: string): string {
+  return toolName
+    ? `imprint probe-backends ${site} --tool ${toolName}`
+    : `imprint probe-backends ${site}`;
+}
+
+function toolDirName(toolDir?: string): string | undefined {
+  return toolDir ? basename(toolDir) : undefined;
+}
+
+function uniqueBackends(backends: ConcreteBackend[]): ConcreteBackend[] {
+  const seen = new Set<ConcreteBackend>();
+  const out: ConcreteBackend[] = [];
+  for (const backend of backends) {
+    if (seen.has(backend)) continue;
+    seen.add(backend);
+    out.push(backend);
+  }
+  return out;
+}
+
 /** Param priority: caller overrides → cron.json → workflow defaults. */
 function resolveParams(
   tool: ResolvedTool,

package/src/imprint/types.ts

@@ -380,6 +380,18 @@ const BackendProbeResultSchema = z.discriminatedUnion('outcome', [
   z.object({
     outcome: z.literal('ok'),
     durationMs: z.number(),
+    /** Optional cdp-replay cold-start measurement. `durationMs` remains the
+     *  first-call duration for backward compatibility. */
+    coldDurationMs: z.number().optional(),
+    /** Optional cdp-replay warm-pool measurement from a second call against the
+     *  same pooled Chrome. Used to explain why CDP may outrank stealth when its
+     *  cold start is still under the operator timeout. */
+    warmDurationMs: z.number().optional(),
+    /** Effective duration used for preference ranking when it differs from the
+     *  first-call duration, e.g. warm cdp-replay. */
+    rankingDurationMs: z.number().optional(),
+    tooSlow: z.boolean().optional(),
+    detail: z.string().optional(),
   }),
   z.object({
     outcome: z.literal('forbidden'),

package/src/imprint/update.ts

@@ -0,0 +1,73 @@
+import { spawnSync } from 'node:child_process';
+import semver from 'semver';
+import { VERSION } from './version.ts';
+
+const PACKAGE_NAME = 'imprint-mcp';
+const REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
+
+interface UpdateCheckResult {
+  current: string;
+  latest: string;
+  updateAvailable: boolean;
+}
+
+interface UpdateResult {
+  ok: boolean;
+  from: string;
+  to: string;
+  error?: string;
+}
+
+export async function checkForUpdate(): Promise<UpdateCheckResult | null> {
+  try {
+    const res = await fetch(REGISTRY_URL, {
+      headers: { accept: 'application/json' },
+      signal: AbortSignal.timeout(5_000),
+    });
+    if (!res.ok) return null;
+    const data = (await res.json()) as { version?: string };
+    const latest = data.version;
+    if (!latest) return null;
+    return { current: VERSION, latest, updateAvailable: semver.gt(latest, VERSION) };
+  } catch {
+    return null;
+  }
+}
+
+const IS_COMPILED = typeof (globalThis as Record<string, unknown>).__IMPRINT_VERSION__ === 'string';
+
+export async function performUpdate(): Promise<UpdateResult> {
+  const check = await checkForUpdate();
+  if (!check) {
+    return { ok: false, from: VERSION, to: VERSION, error: 'could not reach npm registry' };
+  }
+  if (!check.updateAvailable) {
+    return { ok: true, from: VERSION, to: VERSION };
+  }
+
+  const result = IS_COMPILED
+    ? spawnSync(
+        'bash',
+        [
+          '-c',
+          'curl -fsSL https://raw.githubusercontent.com/ashaychangwani/imprint/main/scripts/install.sh | bash',
+        ],
+        { stdio: 'pipe', timeout: 60_000 },
+      )
+    : spawnSync('bun', ['install', '-g', `${PACKAGE_NAME}@latest`], {
+        stdio: 'pipe',
+        timeout: 60_000,
+      });
+
+  if (result.status !== 0) {
+    const stderr = result.stderr?.toString().trim();
+    return {
+      ok: false,
+      from: check.current,
+      to: check.latest,
+      error: stderr || result.error?.message || `install exited with code ${result.status}`,
+    };
+  }
+
+  return { ok: true, from: check.current, to: check.latest };
+}