imprint-mcp 0.2.0 → 0.2.1

package/README.md

@@ -156,7 +156,7 @@ Shows which providers are detected. Interactive `imprint teach` prompts you to c
 
 To force a specific provider and skip the picker, pass `--provider <name>` to `teach`, `generate`, or `compile-playbook`. `teach` and `generate` require a compile-agent provider (`claude-cli`, `codex-cli`, or `anthropic-api`); `compile-playbook` can also use `cursor-cli`.
 
-After selecting a provider, `teach` prompts for a **model** (e.g. `claude-opus-4-7` vs `claude-sonnet-4-6` for Anthropic, `gpt-5.4` vs `o3` for Codex). Override with `--model <name>`. Each tool compiles with a **5-minute timeout** by default; override with `--timeout <duration>` (e.g. `--timeout 10m`, `--timeout 1h`). To skip the replay-and-diff stage (the automated second pass that classifies ephemeral vs constant values), pass `--skip-replay` — faster, but may reduce workflow accuracy for sites with dynamic request parameters.
+After selecting a provider, `teach` prompts for a **model** (e.g. `claude-opus-4-7` vs `claude-sonnet-4-6` for Anthropic, `gpt-5.4` vs `o3` for Codex). Override with `--model <name>`. Each tool compiles with a **20-minute timeout** by default — the compile agent writes the MCP server and runs thorough verification tests, so most complex tools take 10-15 minutes. Override with `--timeout <duration>` (e.g. `--timeout 30m`, `--timeout 1h`). To persist the generated tests after compilation, set `IMPRINT_KEEP_TEST=1` or pass `--keep-test`. To skip the replay-and-diff stage (the automated second pass that classifies ephemeral vs constant values), pass `--skip-replay` — faster, but may reduce workflow accuracy for sites with dynamic request parameters.
 
 <br>
 

package/package.json

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

package/prompts/compile-agent.md

@@ -373,7 +373,7 @@ In all cases, the `give_up` call must include a `what_was_tried` field listing c
 
 ## Time Budget
 
-You have a 10-minute wall-clock deadline. Most successful runs take 8-20 turns. If you're past 20 turns and still not converging, step back and reconsider your approach:
+You have a 20-minute wall-clock deadline. Most successful runs take 8-20 turns. If you're past 20 turns and still not converging, step back and reconsider your approach:
 - Re-read the response body from scratch
 - Look for a different anchor value
 - Try a different extraction shape

package/src/cli.ts

@@ -139,7 +139,7 @@ export const VERB_HELP: Record<string, VerbHelp> = {
       },
       {
         name: '--timeout <duration>',
-        description: 'Per-tool compile timeout. Accepts 10m, 1h, 300s, or plain ms. Default 10m.',
+        description: 'Per-tool compile timeout. Accepts 20m, 1h, 300s, or plain ms. Default 20m.',
       },
       {
         name: '--keep-test',
@@ -190,7 +190,7 @@ export const VERB_HELP: Record<string, VerbHelp> = {
       { name: '--out <path>', description: 'Override the workflow.json output path.' },
       {
         name: '--max-duration <time>',
-        description: 'Agent timeout (e.g., "10m", "1h", "300s"). Default 10m.',
+        description: 'Agent timeout (e.g., "20m", "1h", "300s"). Default 20m.',
       },
       {
         name: '--provider <name>',

package/src/imprint/compile-agent.ts

@@ -53,7 +53,7 @@ export function resolveCompileAgentModel(provider: ProviderName): string {
 interface CompileAgentOptions {
   /** Path to the recorded session JSON (absolute or relative). */
   sessionPath: string;
-  /** Hard wall-clock budget. Default 10 minutes. */
+  /** Hard wall-clock budget. Default 20 minutes. */
   maxDurationMs?: number;
   /** Override LLM config (region, model, project). */
   llmConfig?: LLMOptions;
@@ -197,7 +197,7 @@ ${formatCandidateContext(opts.candidate, opts.sharedContext)}
 Begin by calling read_session_summary to orient yourself, then proceed per the system prompt.`;
 
   // 7. Compute deadline
-  const deadlineMs = Date.now() + (opts.maxDurationMs ?? 10 * 60 * 1000);
+  const deadlineMs = Date.now() + (opts.maxDurationMs ?? 20 * 60 * 1000);
 
   // 8. Instantiate provider (or use injected one for testing).
   //    CLI providers take a different path: they don't implement Anthropic

package/src/imprint/compile.ts

@@ -145,7 +145,7 @@ export async function generate(opts: GenerateOptions): Promise<GenerateResult> {
         ];
         if (result.outcome === 'timeout') {
           lines.push(
-            'hint: increase the timeout with --timeout (teach) or --max-duration (generate)',
+            'hint: most complex tools take 10-15 minutes. increase the timeout with --timeout (teach) or --max-duration (generate)',
           );
         }
         throw new Error(lines.join('\n'));

package/src/imprint/credential-extract.ts

@@ -12,14 +12,13 @@
  * value is visible and lets us confirm which form was the login form.
  */
 
-import { isSensitiveCredentialKey, normalizeKey } from './sensitive-keys.ts';
+import { isSensitiveCredentialKey, isUsernameLikeKey } from './sensitive-keys.ts';
 import type { CapturedEvent, CapturedRequest, Session } from './types.ts';
 
-/** Field-name patterns we'll treat as the username/email partner of a
- *  password field. Ordered by preference: emails first, then user-ish
- *  identifiers. */
-const USERNAME_KEY_RE =
-  /^(user(?:name|id)?|email(?:address)?|login(?:id)?|account|patron(?:number|id)?)$/i;
+/** Predicate: this key looks like the username/email/login partner of a
+ *  password field. Backed by `USERNAME_LIKE_KEYS` in sensitive-keys.ts so
+ *  the dictionary stays in one place. */
+const isUsernameKey = (key: string): boolean => isUsernameLikeKey(key);
 
 /** Where, within a request, a redactable value lives. */
 export type ReplacementLocation =
@@ -58,6 +57,29 @@ interface ExtractionResult {
   replacements: Replacement[];
 }
 
+/** Parsers are tried in this order on every request that has a body. Each
+ *  one is side-effect-free and returns `null` when its input doesn't fit
+ *  its expected framing — so trying JSON first on a form body, or form on
+ *  a JSON body, is safe: only the parser that actually fits will produce a
+ *  finding.
+ *
+ *  Dispatch is parser-driven, not Content-Type-driven, because real sites
+ *  routinely mislabel their bodies — the canonical example is the Nextep
+ *  cafe API (`Content-Type: text/plain` for JSON bodies). Letting the data
+ *  speak for itself prevents whole classes of silent extraction failures.
+ *
+ *  URL-query parsing runs even on requests without a body (e.g. GET-based
+ *  logins that pass credentials in the query string). Multipart is checked
+ *  before generic form-urlencoded because a multipart body still contains
+ *  `=` characters and would be parsed as a single malformed form pair
+ *  otherwise. */
+const BODY_PARSERS: Array<(r: CapturedRequest) => BodyFinding | null> = [
+  findInJsonBody,
+  findInJsonWrappedInForm,
+  findInMultipartBody,
+  findInFormBody,
+];
+
 /** Top-level entry point. */
 export function extractCredentials(session: Session): ExtractionResult {
   const findings: CredentialFinding[] = [];
@@ -65,13 +87,17 @@ export function extractCredentials(session: Session): ExtractionResult {
   const usernamesInDom = collectFormSubmitUsernames(session.events);
 
   for (const req of session.requests) {
-    if (!req.body) continue;
-    const ct = (req.headers['content-type'] ?? req.headers['Content-Type'] ?? '').toLowerCase();
-    const found = ct.includes('json')
-      ? findInJsonBody(req)
-      : ct.includes('urlencoded') || req.body.includes('=')
-        ? findInFormBody(req)
-        : null;
+    let found: BodyFinding | null = null;
+    if (req.body) {
+      for (const parse of BODY_PARSERS) {
+        found = parse(req);
+        if (found) break;
+      }
+    }
+    // Last-resort: credentials in the URL query string (rare but real for
+    // some legacy GET-based login endpoints). Tried after body parsers so
+    // body-based logins always win when both are present.
+    if (!found) found = findInUrlQuery(req);
     if (!found) continue;
 
     const confirmedByDom = usernamesInDom.has(found.usernameValue);
@@ -132,7 +158,7 @@ function findInFormBody(req: CapturedRequest): BodyFinding | null {
 
   // Second pass: find a username-like key.
   for (const { key, value } of pairs) {
-    if (USERNAME_KEY_RE.test(normalizeKey(key)) && value.length > 0) {
+    if (isUsernameKey(key) && value.length > 0) {
       usernameKey = key;
       usernameValue = value;
       break;
@@ -163,11 +189,7 @@ function findInJsonBody(req: CapturedRequest): BodyFinding | null {
   if (typeof pwdHit.value !== 'string' || pwdHit.value.length === 0) return null;
 
   // Look for a username-like key; prefer one in the same parent object.
-  const userHit = findFirstByPredicate(
-    parsed,
-    (k) => USERNAME_KEY_RE.test(normalizeKey(k)),
-    pwdHit.parent,
-  );
+  const userHit = findFirstByPredicate(parsed, isUsernameKey, pwdHit.parent);
   if (!userHit || typeof userHit.value !== 'string' || userHit.value.length === 0) return null;
 
   return {
@@ -178,6 +200,138 @@ function findInJsonBody(req: CapturedRequest): BodyFinding | null {
   };
 }
 
+/** Handles legacy framings where a JSON document is the value of a single
+ *  form-encoded field — `payload={"username":"…","password":"…"}` or
+ *  `data=…` or `request=…`. Real PHP / ColdFusion apps do this. We delegate
+ *  the inner pairing to findInJsonBody by synthesizing a child request, and
+ *  re-encode the path as `body-form` so the redactor knows to swap the
+ *  whole inner JSON string back in. */
+function findInJsonWrappedInForm(req: CapturedRequest): BodyFinding | null {
+  if (!req.body) return null;
+  const pairs = parseFormBody(req.body);
+  if (pairs.length === 0) return null;
+
+  const WRAPPER_KEYS = new Set(['payload', 'data', 'request', 'json', 'body']);
+  for (const { key, value } of pairs) {
+    if (!WRAPPER_KEYS.has(key.toLowerCase())) continue;
+    if (!value.startsWith('{') && !value.startsWith('[')) continue;
+    // Build a synthetic request with the unwrapped JSON as body.
+    const inner: CapturedRequest = { ...req, body: value };
+    const found = findInJsonBody(inner);
+    if (!found) continue;
+    // Project the JSON paths back into form-key terms — the redactor
+    // matches on `originalValue` regardless of `location`, but we keep the
+    // location semantically correct so future readers aren't confused.
+    return {
+      ...found,
+      usernameLocation: { kind: 'body-form', key },
+      passwordLocation: { kind: 'body-form', key },
+    };
+  }
+  return null;
+}
+
+/** Parse a multipart/form-data body into {key, value} pairs and pair like
+ *  the form-urlencoded path. Defensive: any malformed part is skipped.
+ *
+ *  We sniff the boundary from the first line (`--<boundary>`) rather than
+ *  trusting the Content-Type header, because the whole point of this
+ *  module is to not trust Content-Type. */
+function findInMultipartBody(req: CapturedRequest): BodyFinding | null {
+  if (!req.body) return null;
+  const body = req.body;
+  // First line should be `--<boundary>`. If it doesn't start with `--` or
+  // there's no following newline, this isn't multipart.
+  const firstNewline = body.indexOf('\n');
+  if (firstNewline < 0) return null;
+  const firstLine = body.slice(0, firstNewline).trimEnd();
+  if (!firstLine.startsWith('--')) return null;
+  const boundary = firstLine.slice(2);
+  if (boundary.length === 0 || boundary.length > 200) return null;
+  // Split on the boundary; skip the prologue (empty before first boundary)
+  // and the epilogue (after closing `--<boundary>--`).
+  const sep = `--${boundary}`;
+  const parts = body.split(sep).slice(1);
+  const pairs: Array<{ key: string; value: string }> = [];
+  for (const partRaw of parts) {
+    const part = partRaw.startsWith('\r\n')
+      ? partRaw.slice(2)
+      : partRaw.startsWith('\n')
+        ? partRaw.slice(1)
+        : partRaw;
+    if (part.startsWith('--')) break; // closing boundary
+    // Headers and body are separated by a blank line.
+    const headerEnd = part.indexOf('\r\n\r\n');
+    const headerEnd2 = headerEnd >= 0 ? headerEnd : part.indexOf('\n\n');
+    if (headerEnd2 < 0) continue;
+    const sepLen = headerEnd >= 0 ? 4 : 2;
+    const headers = part.slice(0, headerEnd2);
+    let value = part.slice(headerEnd2 + sepLen);
+    // Strip the trailing CRLF that precedes the next boundary.
+    value = value.replace(/\r?\n$/, '');
+    const nameMatch = headers.match(/name="([^"]*)"/i);
+    if (!nameMatch) continue;
+    const key = nameMatch[1] ?? '';
+    if (!key) continue;
+    pairs.push({ key, value });
+  }
+  if (pairs.length === 0) return null;
+  return pairFromKeyValuePairs(pairs, 'body-form');
+}
+
+/** Credentials in the URL query string — `GET /login?username=…&password=…`
+ *  or a POST whose body is empty but credentials ride in the URL. Rare but
+ *  real for some legacy CGI endpoints. */
+function findInUrlQuery(req: CapturedRequest): BodyFinding | null {
+  let qs: string;
+  try {
+    const u = new URL(req.url);
+    qs = u.search.startsWith('?') ? u.search.slice(1) : u.search;
+  } catch {
+    return null;
+  }
+  if (!qs) return null;
+  const pairs = parseFormBody(qs);
+  if (pairs.length === 0) return null;
+  return pairFromKeyValuePairs(pairs, 'body-form');
+}
+
+/** Shared pairing: given key/value pairs, find a password partner and a
+ *  username partner. Returns a BodyFinding or null. Used by every parser
+ *  that flattens its input into key/value pairs (form, multipart, URL
+ *  query). The `location.kind` argument is passed through unchanged. */
+function pairFromKeyValuePairs(
+  pairs: Array<{ key: string; value: string }>,
+  kind: 'body-form',
+): BodyFinding | null {
+  let passwordKey: string | null = null;
+  let passwordValue: string | null = null;
+  for (const { key, value } of pairs) {
+    if (isSensitiveCredentialKey(key) && value.length > 0) {
+      passwordKey = key;
+      passwordValue = value;
+      break;
+    }
+  }
+  if (passwordKey === null || passwordValue === null) return null;
+  let usernameKey: string | null = null;
+  let usernameValue: string | null = null;
+  for (const { key, value } of pairs) {
+    if (isUsernameKey(key) && value.length > 0) {
+      usernameKey = key;
+      usernameValue = value;
+      break;
+    }
+  }
+  if (usernameKey === null || usernameValue === null) return null;
+  return {
+    usernameValue,
+    passwordValue,
+    usernameLocation: { kind, key: usernameKey },
+    passwordLocation: { kind, key: passwordKey },
+  };
+}
+
 interface JsonHit {
   key: string;
   value: unknown;
@@ -238,12 +392,7 @@ function collectFormSubmitUsernames(events: CapturedEvent[]): Set<string> {
         fields?: Array<{ name?: string; type?: string; value?: string }>;
       };
       for (const f of detail.fields ?? []) {
-        if (
-          f.name &&
-          f.value &&
-          f.type !== 'password' &&
-          USERNAME_KEY_RE.test(normalizeKey(f.name))
-        ) {
+        if (f.name && f.value && f.type !== 'password' && isUsernameKey(f.name)) {
           out.add(f.value);
         }
       }

package/src/imprint/emit.ts

@@ -5,6 +5,7 @@ import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join as pathJoin, resolve as pathResolve } from 'node:path';
 import { loadJsonFile } from './load-json.ts';
 import { ensureImprintRuntimeLink } from './runtime-link.ts';
+import { isLoginFieldKey } from './sensitive-keys.ts';
 import { type Workflow, WorkflowSchema } from './types.ts';
 
 interface EmitOptions {
@@ -36,6 +37,8 @@ export function emit(opts: EmitOptions): EmitResult {
     'workflow.json',
   );
 
+  assertNoCredentialShapedParams(workflow);
+
   const outDir = opts.outDir ?? defaultOutDir(opts.workflowPath, workflow);
 
   mkdirSync(outDir, { recursive: true });
@@ -137,6 +140,88 @@ export { WORKFLOW };
 `;
 }
 
+/** Pre-emit guardrail: refuse to write a workflow whose parameters look
+ *  like login credentials (`password`, `userid`, `email`, etc., per the
+ *  shared dictionary in sensitive-keys.ts) but are templated as plain
+ *  `${param.X}` instead of credential-store references like
+ *  `${credential.X}`.
+ *
+ *  This catches the failure mode where upstream credential extraction
+ *  silently failed (e.g. unusual Content-Type, body framing the parser
+ *  didn't recognise, declined credential-save prompt), so the compile
+ *  agent had no credential anchor and chose to model the login fields as
+ *  ordinary callable parameters. The resulting MCP tool would advertise
+ *  `userid`/`password` as required inputs, forward whatever the caller
+ *  passed verbatim, and (most often) silently produce empty results when
+ *  the caller passed empty strings.
+ *
+ *  We require either:
+ *    - The parameter isn't credential-shaped, OR
+ *    - The body template references `${credential.<name>}` (or another
+ *      `credential.*` reference), in which case the workflow is pulling
+ *      from the credential store and the `${param.X}` parameter is
+ *      effectively a no-op the user can safely ignore.
+ *
+ *  Throws with the remediation steps the user needs to take. */
+function assertNoCredentialShapedParams(workflow: Workflow): void {
+  const offenders: Array<{ name: string; matches: string[] }> = [];
+  for (const param of workflow.parameters) {
+    if (!isLoginFieldKey(param.name)) continue;
+    const paramRef = `\${param.${param.name}}`;
+    const credentialRef = `\${credential.${param.name}}`;
+    const requestsUsingParam: string[] = [];
+    let coveredByCredentialRef = false;
+    for (let i = 0; i < workflow.requests.length; i++) {
+      const req = workflow.requests[i];
+      if (!req) continue;
+      const haystack = `${req.url} ${req.body ?? ''} ${Object.values(req.headers).join(' ')}`;
+      if (haystack.includes(credentialRef)) {
+        coveredByCredentialRef = true;
+      }
+      if (haystack.includes(paramRef)) {
+        requestsUsingParam.push(`requests[${i}] (${req.method} ${req.url})`);
+      }
+    }
+    // Only flag if the body templates the param and there's no parallel
+    // credential reference. A workflow that uses both `${param.X}` and
+    // `${credential.X}` is suspicious but not necessarily broken — leave
+    // it to the user. The dangerous case is `${param.X}` alone.
+    if (requestsUsingParam.length > 0 && !coveredByCredentialRef) {
+      offenders.push({ name: param.name, matches: requestsUsingParam });
+    }
+  }
+  if (offenders.length === 0) return;
+
+  const lines = [
+    `Workflow ${JSON.stringify(workflow.toolName)} declares ${offenders.length} credential-shaped parameter(s) that are templated as plain \`\${param.X}\` instead of \`\${credential.X}\`:`,
+    '',
+  ];
+  for (const o of offenders) {
+    lines.push(`  • parameter \`${o.name}\` — used in:`);
+    for (const m of o.matches) lines.push(`      - ${m}`);
+  }
+  lines.push(
+    '',
+    'Credentials MUST be pulled from the credential store via `${credential.<name>}`, never modelled as plain workflow parameters.',
+    "This usually means the redact stage failed to extract a username+password pair from the recorded login request — common causes include unusual Content-Type headers, multipart bodies, or login fields the extractor dictionary doesn't yet cover.",
+    '',
+    'To fix:',
+    `  1. Delete the redacted session: rm ${workflowToolHint(workflow)}/sessions/*.redacted.json (or the relevant one)`,
+    `  2. Re-run from the redact stage: imprint teach ${workflow.site} --from redact`,
+    '  3. Accept the "Save credentials for site to the credential manager?" prompt this time.',
+    '  4. Let teach continue through generate → compile-playbook → emit.',
+    '',
+    "If the prompt does NOT appear during step 3, the extractor still cannot pair this site's login fields — please file a bug attaching the (redacted!) session.",
+  );
+  throw new Error(lines.join('\n'));
+}
+
+/** Pretty path hint for the error message above. We don't have IMPRINT_HOME
+ *  in scope and don't need it — `~/.imprint/<site>` is the convention. */
+function workflowToolHint(workflow: Workflow): string {
+  return `~/.imprint/${workflow.site}`;
+}
+
 function pascalCase(s: string): string {
   return s
     .split(/[_-]+/)

package/src/imprint/sensitive-keys.ts

@@ -112,15 +112,126 @@ const SENSITIVE_KEYS = [
   'dob',
 ];
 
-const SENSITIVE_KEY_SET = new Set(SENSITIVE_KEYS.map((k) => k.toLowerCase()));
+// `normalizeKey` (defined below) lowercases and strips `_`/`-` — set
+// membership goes through it, so we MUST pre-normalize the stored entries
+// or lookups for e.g. `j_password` (→ `jpassword`) will miss a stored
+// `j_password`. Hoisting a local copy of the rule rather than ordering
+// gymnastics keeps the file linear.
+const _normalize = (s: string): string => s.toLowerCase().replace(/[-_]/g, '');
+
+const SENSITIVE_KEY_SET = new Set(SENSITIVE_KEYS.map(_normalize));
 
 /** Subset of SENSITIVE_KEYS that specifically denote a credential (not PII).
  *  Used by credential-extract.ts when looking for the password half of a
- *  login form pair — we don't want to treat e.g. `dob` as a password. */
-const PASSWORD_LIKE_KEYS = new Set(
-  ['password', 'passwd', 'pwd', 'pin', 'patronpassword', 'patron_password'].map((k) =>
-    k.toLowerCase(),
-  ),
+ *  login form pair — we don't want to treat e.g. `dob` as a password.
+ *
+ *  Inclusion criterion: a key name that, when present in a request body
+ *  alongside a username-like partner, almost always means "this is the
+ *  password the user typed at login time." Be liberal here — false positives
+ *  cost the user one extra prompt confirmation; false negatives ship broken
+ *  tools. New additions should reference a real recorded site that broke
+ *  without them.
+ *
+ *  Sites observed needing each entry:
+ *    - password / passwd / pwd:                most modern APIs
+ *    - pin:                                    bank / utility login forms
+ *    - pass:                                   legacy PHP forms (e.g. SMF)
+ *    - secret:                                 OAuth ROPC payloads
+ *    - j_password:                             Java EE / Spring Security default form-login
+ *    - userpassword / loginpassword / accountpassword:
+ *                                              vendor SSO portals that namespace fields
+ *    - patronpassword / patron_password:       Discover & Go libraries (kept for back-compat)
+ */
+const PASSWORD_LIKE_ENTRIES = [
+  'password',
+  'passwd',
+  'pwd',
+  'pin',
+  'pass',
+  'secret',
+  'j_password',
+  'userpassword',
+  'loginpassword',
+  'accountpassword',
+  'patronpassword',
+  'patron_password',
+];
+const PASSWORD_LIKE_KEYS = new Set(PASSWORD_LIKE_ENTRIES.map(_normalize));
+
+/** Subset of SENSITIVE_KEYS that specifically denote a username/email/login
+ *  identifier — the partner half of a username+password login pair.
+ *
+ *  Same inclusion criterion as PASSWORD_LIKE_KEYS: liberal coverage of real
+ *  recorded forms, narrow enough not to match arbitrary identifiers. Note
+ *  this set is intentionally distinct from `email`, `phone` etc. in
+ *  SENSITIVE_KEYS — those get redacted as PII regardless, but only the
+ *  subset here qualifies as the "username partner" the credential extractor
+ *  pairs with a password.
+ *
+ *  Sites observed needing each entry:
+ *    - user / username / user_name / userid / user_id:
+ *                                              most APIs
+ *    - login / loginid / login_id / login_email:
+ *                                              REST endpoints that name the form field after the action
+ *    - email / emailaddress / email_address:   email-as-username flows
+ *    - account / accountid / account_id:       enterprise SSO portals
+ *    - patron / patronnumber / patron_number / patronid / patron_id:
+ *                                              library systems (Discover & Go)
+ *    - j_username:                             Java EE / Spring Security default form-login
+ *    - signin / signinid / sign_in_id:         vendor SSO portals (Okta-style)
+ *    - usr / uid:                              legacy CGI / older PHP
+ *    - memberid / member_id / membername / member_name:
+ *                                              membership-driven sites (gyms, clubs)
+ *    - customerid / customer_id / customernumber / customer_number:
+ *                                              ecommerce account portals
+ *    - clientid / client_id / clientnumber / client_number:
+ *                                              B2B portals (CAUTION: also matches OAuth client_id;
+ *                                              credential-extract.ts gates on having a password
+ *                                              partner in the same parent, so OAuth token endpoints
+ *                                              that pass client_id without a password won't match)
+ */
+const USERNAME_LIKE_KEYS = new Set(
+  [
+    'user',
+    'username',
+    'user_name',
+    'userid',
+    'user_id',
+    'login',
+    'loginid',
+    'login_id',
+    'loginemail',
+    'login_email',
+    'email',
+    'emailaddress',
+    'email_address',
+    'account',
+    'accountid',
+    'account_id',
+    'patron',
+    'patronnumber',
+    'patron_number',
+    'patronid',
+    'patron_id',
+    'j_username',
+    'signin',
+    'signinid',
+    'sign_in_id',
+    'usr',
+    'uid',
+    'memberid',
+    'member_id',
+    'membername',
+    'member_name',
+    'customerid',
+    'customer_id',
+    'customernumber',
+    'customer_number',
+    'clientid',
+    'client_id',
+    'clientnumber',
+    'client_number',
+  ].map(_normalize),
 );
 
 const SENSITIVE_HEADERS = [
@@ -138,7 +249,7 @@ const SENSITIVE_HEADERS = [
 
 const SENSITIVE_HEADER_SET = new Set(SENSITIVE_HEADERS.map((h) => h.toLowerCase()));
 
-export const normalizeKey = (s: string): string => s.toLowerCase().replace(/[-_]/g, '');
+export const normalizeKey = _normalize;
 
 /** True if the key name suggests a sensitive value (auth, payment, PII). */
 export function isSensitiveKey(key: string): boolean {
@@ -151,6 +262,29 @@ export function isSensitiveCredentialKey(key: string): boolean {
   return PASSWORD_LIKE_KEYS.has(normalizeKey(key));
 }
 
+/** True if the key name suggests a username/email/login identifier — the
+ *  partner half of a login pair. Used in credential extraction and in the
+ *  pre-emit guardrail that flags workflows templating credentials as plain
+ *  parameters. */
+export function isUsernameLikeKey(key: string): boolean {
+  return USERNAME_LIKE_KEYS.has(normalizeKey(key));
+}
+
+/** True for either half of a login pair (username or password). Used by the
+ *  pre-emit guardrail and the post-redact pairing audit, which both need to
+ *  decide "is this parameter name credential-shaped?" without caring which
+ *  half. */
+export function isLoginFieldKey(key: string): boolean {
+  const n = normalizeKey(key);
+  return PASSWORD_LIKE_KEYS.has(n) || USERNAME_LIKE_KEYS.has(n);
+}
+
+/** Raw password-like key strings (pre-normalization) for callers that need
+ *  substring matching against raw body text rather than parsed key lookup. */
+export function passwordLikeTokens(): readonly string[] {
+  return PASSWORD_LIKE_ENTRIES;
+}
+
 export function isSensitiveHeader(header: string): boolean {
   return SENSITIVE_HEADER_SET.has(header.toLowerCase());
 }

package/src/imprint/teach-state.ts

@@ -55,6 +55,13 @@ export interface WorkflowState {
   updatedAt: string;
   candidate?: ToolCandidate;
   sharedContext?: SharedCompileContext;
+  /** Non-fatal flags raised by upstream stages that downstream stages (and
+   *  the user) should know about. Currently used by the redact stage to
+   *  record `'credentials_not_paired'` when a password-shaped body field
+   *  was scrubbed but no username+password pair could be extracted —
+   *  meaning the generated workflow will template credentials as plain
+   *  parameters instead of `${credential.X}` references. */
+  warnings?: string[];
 }
 
 export interface TeachState {

package/src/imprint/teach.ts

@@ -48,6 +48,7 @@ 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 {
@@ -89,7 +90,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. */
@@ -599,8 +600,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,
     });
   }
 
@@ -885,7 +916,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 +929,14 @@ 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 3,`,
+        '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.`,
+        '',
+        'To persist the generated tests after compilation, set IMPRINT_KEEP_TEST=1',
+        'or pass --keep-test.',
       ].join('\n'),
       'Compile step',
     );
@@ -1568,6 +1603,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(