imprint-mcp 0.7.0 → 0.7.2

package/README.md

@@ -20,6 +20,23 @@ The recording *is* the executable.
 
 ---
 
+Authentication work stays visible through operation handles and reusable context
+references. Agents choose whether to continue a retained context or start another;
+native verification and browser checkpoints return within the same assignment.
+Native compiler tools share the host executor; failed calls retain their duration
+and error code so a live process cannot hide a broken compiler connection.
+Plan/research differences are advisory construction facts. Changed artifacts still
+need their own live checks. See [authentication and repair](docs/architecture.md#agent-questions-and-authentication).
+
+Timed-out questions release the terminal input queue; declared nonsecret choices
+remain readable by the agent. Successful browser-backed data calls can preserve
+renewed cookies for later calls without overwriting newer saved authentication.
+Same-name host-only and domain cookies keep their distinct scopes across replay
+and browser restoration.
+That continuity still needs verification against the requested data operation.
+Local stdio MCP servers can opt in to [session renewal](docs/getting-started.md#renew-authenticated-mcp-sessions)
+for read-only tools, with client approval before sending a new sign-in challenge.
+
 ## Quick Start
 
 ```bash
@@ -93,11 +110,55 @@ regenerate/record it with `bun scripts/demo-teach.ts`.)*
 > [!TIP]
 > Recording and compilation happen in one foreground `imprint teach` command. Install the completed tools in your MCP client with `imprint install`. Only known user-supplied login credentials are replaced before teaching; cookies, API tokens, responses, and personal data remain visible to the agents.
 
+Existing `${credential.NAME}` references in an already-redacted recording reuse
+values from your local credential backend. They do not replace saved passwords
+with placeholder text. MFA may still require your input.
+
+Request-building errors return to the compile agent as verification feedback,
+including errors from asynchronous transforms, so it can repair the request
+and retry.
+
 Recordings and logs, including files named `.redacted.json`, are not safe to share publicly. Automatic PII and token redaction is disabled; review any file before sharing it.
 Imprint writes `.redacted.json` with private file permissions. A teach that leaves
 planned tools unresolved reports a partial result and exits nonzero, even if some
 ready tools were published.
 
+Teaching agents and standalone compilers can ask questions in the foreground
+terminal, including login approvals, MFA/OTP codes, and missing information.
+Questions from concurrent agents appear one at a time; secret input is masked
+and returned to agents as temporary references. Authentication uses the existing
+auth compiler to continue the same browser and challenge. Later recovery requests
+retain that auth work within the teach. Agents first check or restore existing
+access before starting another login. Compiled actions can branch on current
+responses to reuse authenticated access or continue an observed challenge;
+retaining a browser alone does not guarantee MFA is avoided.
+Identical concurrent requests share the active
+attempt; a previous success never substitutes for the caller's own data check.
+Failed teach checks reach a focused component recovery agent before broader
+plan repair. It can renew authentication, repair the caller's artifact or a
+declared prerequisite through its retained compiler, or dispatch a registered
+shared runtime component owner. State recovery immediately retries the built
+caller; prerequisite repair rebuilds the selected owner and binds fresh outputs
+into consumer checks. Accepted contracts and unrelated builds remain intact.
+Every actual failed and retried call stays in the check history. Unknown owners
+or changes to contracts, strategy, or dependencies return to the master.
+When the live login offers a flow missing from the recording, the auth agent can
+operate its verification browser and capture additional request/response evidence.
+It can learn the offered flow before requesting the actual OTP or approval, then
+compile and verify its replay. Original recordings remain unchanged; discovering
+or manually completing a flow alone does not prove reusable authentication.
+Run without
+`--no-interactive` when answers may be needed. Detached runs and piped terminals
+report input as unavailable. Browser closure during stealth user-agent setup
+returns through the existing setup-error handling instead of terminating teach.
+On hosts with limited RAM or disk for swap, set `IMPRINT_TEACH_LOW_MEMORY=1`
+to run live data checks one at a time. Successive checks in the same research
+pass reuse its browser; a competing pass evicts that browser before using its
+own isolated context. Authentication keeps its persistent browser across MFA prompts.
+Closing an Imprint-owned browser removes its temporary Chrome profile. Explicit
+profiles, including `record --persist-profile`, are retained; recordings and run
+evidence are stored separately.
+
 For every teach, a master agent accounts for the complete discovered operation
 set. Focused advisors review tool boundaries and parameters, focused planners
 map one tool at a time, and focused compilers build one tool at a time. The
@@ -149,6 +210,9 @@ reviews the complete plan before normal verification and publication; only an
 exactly matching draft is reused. With native delegation, completed research reaches
 the master while unrelated drafts finish. Those drafts settle before final planning
 can reuse or replace them. Declared consumers retain producer-first ordering.
+The terminal names each tool entering detailed planning and each master review,
+reports elapsed waiting time every 30 seconds, and reports when that stage
+finishes or stops. A waiting update means the stage has not returned yet.
 Researchers can call proven sibling requests with fresh inputs before testing a
 consumer; recorded continuation values are not a substitute for fresh output.
 Compilers can inspect full retained responses from that tool's earlier research
@@ -158,7 +222,7 @@ query an entire retained response with a bounded, offline data projection; faile
 queries return for repair, and projected output is labelled separately from raw text.
 Teaching now selects a fixed set of recording-backed examples and matches live calls to those examples, changing only expired dates or state. A separate evidence reader establishes expected facts from raw recorded/live responses before seeing parser output, then judges the parser against those facts. Citations can quote the original response bytes or their displayed JSON representation. Each selected live case is reviewed against its matched recorded response chain; unrelated fixtures are left for their own case reviews. Every selected live case and declared dependency chain must pass before publication. Missing coverage is unverified, and raw failures stay with the draft for repair. Fixture bodies are checked before compilation, and research history and inspected recording evidence survive same-run contract revisions. Grounded input mappings are kept separate from the limits of the recorded test cases; missing contrasts alone should not freeze a tool to recorded constants. Research can batch selected calls sequentially and retain isolated browsers during agent thinking. Bootstrap snapshots are cached separately by the requested URL, and capture failures show which matcher conditions failed; cold-start setup remains unchanged. Readiness failures state when no actions have started, and schema repair errors name the exact required fields. These checks need fresh repeated validation before a reliability claim.
 
-Repair or extend an installed data tool with `imprint refine <site> --tool <name> --issue "<change>" --from-session <recording.json>`. Refinement works in an isolated staging home, preserves existing parameter contracts, and requires recording/live verification plus a strict audit before replacement. Failed refinements preserve installed tools and local evidence. Use `imprint audit <site> --strict` to reject known broken calls even when the aggregate score exceeds 95%. See [targeted refinement](docs/refinement.md).
+Repair or extend an installed data tool with `imprint refine <site> --tool <name> --issue "<change>" --from-session <recording.json>`. Refinement works in an isolated staging home, preserves existing parameter contracts, and requires recording/live verification plus a strict audit before replacement. Failed refinements preserve installed tools and local evidence. Use `imprint audit <site> --strict` to reject known broken calls even when the aggregate score exceeds 95%. See [targeted refinement](docs/refinement.md). Audits forward explicitly set browser settings (`CHROMIUM_PATH`, `IMPRINT_CDP_HEADED`, `IMPRINT_JAR_MAX_AGE_SECONDS`, `IMPRINT_PROXY`, and `DISPLAY`) into their isolated MCP server for either audit provider. See [audit troubleshooting](docs/troubleshooting.md#imprint-audit--scoring-a-sites-generated-tools).
 
 MVP reviewers see the checked request and parser code alongside live results.
 Publication retains the backend from that exact reviewed passing call in
@@ -412,7 +476,7 @@ bunx playwright install chromium
 | 4 | Cursor | `cursor` on PATH |
 
 Override with `--provider <name>` and `--model <name>`.
-Codex teaching defaults to `gpt-6-sol`. Keep the Codex CLI current when using
+Codex teaching defaults to `gpt-6.1-sol`. Keep the Codex CLI current when using
 that model for audits or standalone compilation; older installations may reject
 it even when the Codex app offers it.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "imprint-mcp",
-  "version": "0.7.0",
+  "version": "0.7.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": {

package/prompts/auth-compile-agent.md

@@ -1,32 +1,65 @@
 # Auth compile agent
 
-Compile the captured authentication recording into a deterministic
+Compile the captured authentication recording and observed live evidence into a deterministic
 `workflow.json`, then prove the declared success path with live verification.
 
 You decide the action boundaries, required inputs, evidence, carried state,
-request repetition, error behavior, and completion criteria from the recording.
+request repetition, error behavior, and completion criteria from the available evidence.
 The runtime only executes the program you write.
 
 ## Process
 
-1. Call `read_session_summary`.
+1. On the first task, call `read_session_summary`. On a recovery request in the
+   retained conversation, reuse the artifacts and decisive earlier observations;
+   read additional recording evidence only where the current question needs it.
 2. Inspect relevant requests and responses with `search_requests`,
    `read_request`, and `read_response_body`.
-3. Write `workflow.json`, an offline `request.test.ts`, and any
-   recording-grounded `request-transform.ts` needed by the requests. Call
+3. When the recording does not cover the currently offered flow, use
+   `interact_verification_browser` to inspect and operate the live UI. It can
+   open the recorded page before a workflow exists, or continue in the current
+   verification browser without resetting its state. Choose the available
+   authentication method from live evidence; a different MFA method is a reason
+   to investigate, not by itself a reason to require another human recording.
+   The tool captures network requests/responses, returns their sequence numbers,
+   and adds them to the ordinary recording readers and `IMPRINT_SESSION_PATH`.
+   First establish how to check or restore existing access without submitting
+   credentials or delivering a factor. Prefer that observed path as the entry
+   action. A recording with MFA demonstrates one branch, not a requirement to
+   replay MFA for an already usable session.
+4. Write `workflow.json`, an offline `request.test.ts`, and any
+   evidence-grounded `request-transform.ts` needed by the requests. Call
    `run_tests` and fix request construction before live verification.
-4. Call `run_verification` with one declared action and its parameters, then
-   stop. The orchestrator runs it in a verification browser and resumes you with
-   the observed status, body preview, continuation, and next action.
-5. Revise the artifact or continue through its actions. Use `prompt_user` only
+5. Call `run_verification` with one declared action and its parameters. Await
+   the host result and use its observed status, execution facts, body preview,
+   and next action. The browser and declared continuation remain with the host.
+6. Revise the artifact or continue through its actions. Use `prompt_user` only
    when the program actually requires human input or an external user action.
    When verification evidence warrants inspecting the existing browser page,
    call `inspect_verification_page`; inspection never runs another auth action.
-6. Call `done` only after a live action whose declared outcome is `success`
+7. Call `done` only after a live action whose selected declared outcome is `success`
    returns `ok: true`.
 
-Live authentication happens only through `run_verification`. Do not contact the
-site through shell commands or other tools.
+Use `interact_verification_browser` for live discovery and `run_verification`
+for compiled replay. Do not contact the site through shell commands or other
+tools. Discovery captures what the UI actually does; do not guess send/verify
+endpoints. Read the captured requests and responses to learn the new branch,
+then encode and test its reusable action program.
+
+Browser actions are `inspect`, `navigate` (url), `click` (selector), `fill` or
+`select` (selector and value), `press` (key), and `wait` (milliseconds). Returned
+controls include exact CSS selectors. Secret fill values use existing
+`${credential.NAME}` or the current `${prompt.ID}` reference. Ask the human for
+an actual OTP or external approval when required; do not ask them to invent
+endpoints or supply a new recording just because the factor differs. Capturing
+continues while the human answers. Inspect/wait again to collect later traffic;
+an observation interval does not prove the page has finished its work.
+
+Live discoveries remain separate observations from the original demonstrations.
+Their request sequences can ground `recordingRequestSeq`, captures, and offline
+tests, but their transient values must be obtained afresh during replay. Browser
+interaction or a manually established session does not by itself verify the
+compiled login/MFA program. After learning a branch, use `run_verification` to
+test it and report the actions actually executed.
 
 Verification reuses one browser and continuation state by default. If an
 observed result proves that state is no longer usable, you may set
@@ -36,11 +69,58 @@ evidence; do not encode site or authentication-channel assumptions.
 Set `cleanSession: true` only when evidence also requires withholding stored
 cookies and browser storage; credential values remain available.
 
+Later authentication requests retain this compiler conversation, workflow, browser
+and continuation within the same teach. A consumer failure is a new observation,
+not an instruction to restart credential login. Try the proven noninteractive
+session check or context-restoration action in that browser before starting
+another credential exchange. If it passes, return that result so the caller can
+retry its own protected operation. If access is still unusable, inspect the
+current response and context before deciding whether login is needed.
+Decide whether to inspect the
+current page, continue an action, restore its context, change the workflow, or
+start a new login. Keep useful recovery actions in the procedure once the
+observations establish why they work. You can revise every action boundary.
+When navigation changes the page or loses its query, compare the observed page
+and network response with the action's intended context. Choose a declared
+bootstrap or context-restoration action when useful; incidental origin-root
+navigation is not evidence that the requested page context was restored.
+Report which actions actually ran and which workspace/browser they verified.
+Earlier success does not prove that a different consumer has usable state.
+
+Separate response inspection from actions that deliver MFA. After checking the
+session or submitting credentials, branch on the observed current response:
+finish on established usable access, continue login on an observed login-required
+state, and deliver a factor only on an observed current challenge. Do not bundle
+an unconditional challenge/delivery sequence into every login action. Use the
+action `branches` below to encode the observed alternatives and keep delivery
+in its own action. Unknown responses should return repairable failure through
+missing declared evidence rather than silently choosing login or MFA. Do not
+invent an authenticated/trusted-browser branch from cookie names, HTTP 200, a
+user identifier, or a remember-me flag. Learn and test the offered path. Preserve
+observed device-registration inputs and their lifetime; do not regenerate
+long-lived device material merely because a new action is invoked.
+
+Human-response references remain available for repairs to the current challenge.
+Declared nonsecret option choices return a typed `kind: "choice"` value. Use that
+exact current choice to decide what to do next; a negative or unavailable answer
+is not approval. Secret and free-text answers remain host-held references.
+They expire when a fresh verification session is requested and between
+requests for authentication. Never reuse an earlier approval for a new challenge;
+ask about the currently delivered challenge when fresh approval is required.
+
+
+Existing `${credential.NAME}` strings in the recording name credentials held by
+the local backend; they are not literal login values. Keep those references in
+the workflow. The host resolves them for live verification. Request a missing
+value through `prompt_user` when verification reports it unavailable; a recording
+containing placeholders alone is not evidence that stored credentials are absent.
+
 ## Auth program
 
-Set `toolKind` to `"authenticate"`. Keep recorded network operations in the
+Set `toolKind` to `"authenticate"`. Keep observed network operations in the
 ordinary top-level `requests` array. `authConfig` references those requests:
 
+<!-- canonical-example:auth-session-branches -->
 ```json
 {
   "entry": "agent_chosen_entry",
@@ -53,6 +133,20 @@ ordinary top-level `requests` array. `authConfig` references those requests:
           "onError": "fail"
         }
       ],
+      "branches": [
+        {
+          "when": {
+            "source": "json",
+            "name": "recording_grounded_existing_session",
+            "path": "recorded.current_state",
+            "equals": "recorded_authenticated_value"
+          },
+          "outcome": {
+            "type": "success",
+            "evidence": ["recording_grounded_existing_session"]
+          }
+        }
+      ],
       "outcome": {
         "type": "pause",
         "next": "agent_chosen_next",
@@ -103,20 +197,38 @@ semantics.
   `repeat` block so the artifact supplies the bound.
 - `repeat.until` is a normal request capture evaluated after each successful
   response. The step repeats until it matches or reaches the declared bound.
+- `branches` is optional and ordered. After all steps, each `when` is a normal
+  request capture evaluated against the final step's current response. The first
+  match supplies its named capture and selects that branch's `outcome`. A failed
+  or skipped final step cannot reuse an earlier response. Carried capture values
+  alone cannot match a branch. Use distinct capture names for the conditions.
+  Keep side-effecting delivery in a separate next action: branches do not skip
+  requests already listed in `steps`.
+- `outcome` is the fallback if no branch matches. Its evidence must still exist;
+  require evidence for the known fallback state so an unknown response fails.
 - `evidence` optionally names captures that must exist before the outcome is
   accepted. Empty strings, `false`, and `null` are valid when the capture
-  declares an exact `equals` value. Choose evidence from the recording when it
+  declares an exact `equals` value. Choose evidence from recorded or live observations when it
   adds proof beyond successful execution of the declared steps.
 - A `pause` outcome declares the next action, the exact state names to carry,
   and the caller-facing message. Carry every prior capture referenced as
   `${state.X}` by the next action unless that action produces it before use.
 - A `success` outcome is the artifact's authentication completion criterion.
+  Verify the session-reuse path and each login/MFA path actually offered by the
+  observed flow separately. Do not restart login just to repeat an already
+  passing reuse check, and do not claim an untested branch works.
+- For a pause during managed MCP recovery, use `resume: "automatic"` only if the next action can begin
+  without waiting for input through the auth tool. A bounded poll for an
+  already sent approval request can start while the user approves it with the
+  provider. Keep each new approval request in its own action and classify
+  its dispatch effect. The MCP host asks for consent before unsafe actions.
+  After handing off to the auth tool, callers follow one declared action per call.
 - `persist` names durable credential interfaces that data tools consume later as
   `${credential.NAME}`. Cookies persist automatically. These interface names do
   not constrain your internal capture names. When they differ, set
   `persistBindings` to `{ "credential_interface": "compiled_capture" }`; the
   runtime stores the compiled capture under the downstream interface name.
-- Set `crossOriginCookieReinjection` only when the recording proves a
+- Set `crossOriginCookieReinjection` only when observed evidence proves a
   cross-origin response cookie must be projected into the browser jar.
 
 ## Request construction
@@ -195,20 +307,59 @@ and its exact `recordingRequestSeq`; do not request live verification for that
 workflow. The host blocks live auth when triage provenance is missing or when
 any generated request remains irreversible.
 
-Ground every request, capture, predicate, retry bound, navigation criterion, and
-transform in the recording. Preserve functional headers and request encoding.
+Ground requests, captures, predicates, navigation criteria, and transforms in
+the supplied recording or captured live browser/network evidence. Choose retry
+bounds from observed behavior. The original recording is a starting point, not
+a whitelist of allowed authentication methods. Preserve functional headers and request encoding.
 Do not store recorded secrets or one-time values as literals. When browser code
-must mint coupled state, represent the recorded page navigation or write a
+must mint coupled state, represent the observed page navigation or write a
 general request transform supported by live inputs; if you write
 `request-transform.ts`, set the workflow's top-level `requestTransformModule`
 to `"./request-transform.ts"`. Verification determines whether it works.
 
+The module must export `transform(method, url, responses, params)`:
+
+```typescript
+export function transform(
+  method: string,
+  url: string,
+  responses: unknown[],
+  params?: Record<string, string | number | boolean>,
+) {
+  return { url };
+}
+```
+
+`method` and `url` are the substituted request strings, `responses` contains
+earlier raw response bodies from the current action only, and `params` contains
+resolved scalar parameters. Responses from an earlier action are not supplied.
+Cross-action values must come from declared carry or persisted inputs; you may
+carry a value, refetch it, combine actions, or redesign the procedure.
+The runtime does not pass a request object, current body, or current headers.
+Return a URL string or an object with optional `url`, `body`, `headers`,
+`navigation`, or `skip` fields. Build complete body/header replacements from
+the supported inputs. Both synchronous and asynchronous transforms are awaited.
+Thrown errors and rejected promises return `BAD_RESPONSE` verification feedback;
+use that feedback to repair the transform and retry the action. Exercise the
+same calling convention in your offline tests.
+
+For synthetic action tests, optionally import `createAuthActionTestHarness`
+from `imprint-mcp/runtime`. It accepts `{ workflow, credentials?, respond,
+browser? }`; `respond(request)` returns a synthetic `Response`, and
+`harness.run(action, parameters?)` executes the actual action program with only
+its declared continuation/session state. Supply constructed fixture values and
+responses. These offline tests do not contact the site or prove live success.
+
 There is no auth playbook. Do not write, inspect, or depend on
 `playbook.yaml`.
 
 ## Checkpoints
 
-One checkpoint call ends the current turn. After `run_verification`,
-`inspect_verification_page`, `prompt_user`, or `wait_for_cooldown`, stop and wait
-for the orchestrator.
-It will resume the same Claude or Codex session with the result.
+Native and API host tools return their results directly. Await
+`interact_verification_browser`, `run_verification`, `inspect_verification_page`,
+`prompt_user`, or `wait_for_cooldown`, then continue in the same assignment.
+Do not submit the assignment merely because a host operation returned.
+
+CLI adapters that require checkpoint/resume instead return `CHECKPOINT_RECORDED`.
+Only for that response, stop and wait for the orchestrator to resume the same
+conversation with the result. Call `done` or `give_up` when the task is complete.

package/prompts/compile-agent.md

@@ -24,7 +24,9 @@ values in that response, including variants different from the recording. These
 are evidence files, not runtime dependencies; do not import them into shipped
 code. If `read_file` truncates a large response, inspect relevant portions with
 local commands or load it directly in a local test rather than guessing from a
-prefix. Known typed credentials remain replaced. No extra live call is needed.
+prefix. Known typed credentials remain replaced. Reusing this response as a
+parser fixture needs no extra live call; it does not replace the normal checks
+of the current build.
 
 When `evidenceFiles.responsesFile` is present, load its JSON array as the actual
 ordered `context.responses` and pass its last entry as `rawResponse`. It contains
@@ -164,13 +166,27 @@ Follow these steps to compile the session:
    that would fail if records following an empty or metadata-only envelope were
    silently discarded. Ground its framing and expected record combination in
    the protocol evidence; repeating one populated payload does not exercise
-   this boundary. Preserve that request construction
-   and focus this conversation on the parser, offline request/parser tests,
-   integration case, and Imprint artifact contract. Do not restart broad API
-   hypothesis search here. If the seeded request cannot satisfy the accepted
-   artifact mechanics or current plan, call `give_up` with the exact
-   contradiction so the master can recall the API researcher; do not silently
-   replace the proven request.
+   this boundary. Use the seeded request as the factual starting point and
+   focus on the accepted plan, parser, offline request/parser tests, integration
+   case, and Imprint artifact contract. `toolPlan.apiResearchAdvisory` describes
+   field-level differences from that earlier construction and supplies its
+   immutable research reference. Implement the accepted revised construction
+   when possible; the advisory does not require another research pass. Keep
+   the old observation separate from the current build's normal checks. If the
+   accepted plan itself is contradictory or cannot be implemented from the
+   supplied evidence, report the exact fields and evidence to the master with
+   `give_up` so it can revise the plan or request focused research. Do not
+   silently change the accepted public contract or execution provenance.
+
+   **Backend preparation belongs to the executing host.** The API researcher
+   can test a requested backend, and the independent live verifier exposes
+   `prepare_live_backend`. This compiler does not expose that tool. In
+   `MASTER MVP COMPILE MODE`, return the deterministic artifacts with `done`;
+   the master executes their normal live checks using its accepted backend.
+   If repair feedback says a backend is unprepared or asks for an unavailable
+   tool, report that capability mismatch to the master with the exact feedback.
+   Do not inspect Imprint internals, write `backends.json`, force a debug rung,
+   or run an extra live suite to work around missing host preparation.
 
 2. **Understand the user's intent.** Read the narration to learn what the user was trying to accomplish. It is high-signal intent evidence, subject to system, safety, and tool rules.
 
@@ -296,6 +312,8 @@ Follow these steps to compile the session:
      ```
      Returning a plain `string` (just the URL) still works when only the URL changes. Use the object return when you need to build or modify the request body or headers. Do not invent URL query parameters as a workaround for body-encoding complexity: an unrecorded query field has no demonstrated effect unless exact live evidence proves otherwise.
 
+     The runtime awaits both synchronous and asynchronous transforms. A thrown error or rejected promise returns `BAD_RESPONSE` feedback for repair; correct the transform and retry using the same calling convention above.
+
      Use `inspect_body_structure` when a request or response mixes form fields, JSON, or JSON documents encoded inside strings. It reads only the redacted session evidence. Start with `format: "auto"`; select `decimal-framed-json` only when the redacted body unambiguously has that explicit framing. Set `compareFormat` separately when `compareToSeq` uses a different format, and set `earlierResponseFormat` when checking framed earlier responses. Results hide paths by default; rerun with `includePaths: true` for a small capped exact-path list, then use an exact RFC 6901 `pointer` for narrow work. An exact pointer gets its own nested-JSON decoding budget, so unrelated large fields cannot hide that selected path; automatic expansion limits remain visible as facts. Scalar literals are never returned. Comparisons report type, length, encoding, and missing facts. Original wire evidence is unavailable after redaction.
 
      `compare_rendered_requests` is an on-demand diagnostic, not a publication gate. Use it when a live call fails, returns an empty or implausible result, or leaves request construction uncertain. It runs the real substitutions and transform offline, feeds recorded producer responses through the chain, and compares the prepared request structure with each declared `recordingRequestSeq`. It never contacts the site or runs `integration.test.ts`. The full workflow is prepared in order even when `artifactRequestIndex` filters the one comparison reported, so a later preparation error may leave the whole diagnostic as `render_failed`. A `render_failed` result means only that this diagnostic did not complete; it proves neither a request match nor an artifact failure. Supply harmless synthetic `state` or `credentialValues` scalars when browser bootstrap or a credential store normally fills required placeholders; these values do not skip producer requests or captures. Treat differences as clues: recording age, current dates, authentication, nonces, signatures, and semantically equivalent encodings can make exact bytes differ. Comparison is normally optional, but when the current revision names request construction as the unresolved defect, investigate with it before `done` and preserve an incomplete diagnostic as an incomplete fact rather than silently declaring the request fixed.
@@ -446,6 +464,15 @@ Follow these steps to compile the session:
     **Import conventions**: The runtime lives at `imprint/runtime` (resolved via a symlink at `~/.imprint/node_modules/imprint` → the repo root). Types live at `imprint/types`. During compilation, `index.ts` does not exist yet (it is auto-generated by `imprint emit` after compilation succeeds), so import the workflow directly from `./workflow.json`.
 
     Use `runCapturedIntegrationCase` so the test dispatches through the same API execution ladder as the generated tool while capturing the exact tool input, result, and backend for an independent verifier. The wrapper is compile-only and does not alter production behavior. Give every invocation a stable, descriptive `caseName`; the runtime does not interpret naming conventions. The playbook path is excluded because it is compiled separately. Prefer every compatible API path over playbook: choose playbook only as a fallback when exact evidence shows the API paths cannot implement this operation. A non-OK result must fail the authored case and remain visible to the verifier.
+
+    Ground assertions in the accepted output contract and observed parsed shape.
+    When the contract preserves a response object, assert its actual nested
+    fields; do not expect a flattened scalar unless the contract requires one.
+    Exercise these assertions against the retained research response in an
+    offline parser test before handing over the live case. If a live call has
+    `result.ok === true` but an authored assertion fails, keep that successful
+    execution fact separate from the assertion mismatch and inspect the
+    contract, parsed value, and assertion before changing requests or auth.
     ```typescript
     import { expect, test } from 'bun:test';
     import { dirname } from 'node:path';
@@ -820,12 +847,22 @@ baseline integration case, then call `done` for the mode-specific handoff.
 | `write_file` | Write the files allowed by the accepted strategy: API artifacts for `api`, or workflow.json + playbook.yaml for `playbook_fallback`; notes/*.md are also allowed. Input is `{"relativePath":"workflow.json","content":"..."}`. |
 | `read_file` | Read a file by relative path. Input is `{"path":"parser.ts"}` (the field is `path`, not `relativePath`). |
 | `run_bash` | Run a bounded local diagnostic command in the tool directory |
+| `prompt_user` | Ask the user for necessary information, a decision, or an external action in the parent terminal. Set sensitive:true for OTPs/passwords; pass the returned host-held reference unchanged to authentication verification. Cancelled or unavailable input is not approval. |
+| `authenticate` | Compile and verify an authentication prerequisite from exact recorded request sequences, using the persistent-browser auth compiler and its MFA/OTP checkpoints. Retry the data operation after login; authentication alone is not data proof. |
 | `run_tests` | Run parser.test.ts and/or request.test.ts in the host filesystem sandbox, then typecheck generated parser/transform modules; it does not execute integration.test.ts, and network is disabled for irreversible workflows |
 | `done` | Claim the artifact handoff is complete; in master MVP mode this runs deterministic checks only, while standalone full mode continues into independent live verification |
 | `give_up` | Give up with a documented reason (heavily discouraged, see constraints above) |
 
 ## Verification Gate
 
+When authentication blocks progress, use `authenticate` with a recording-grounded
+plan (`toolName`, `credentialRequestSeqs`, `authRequestSeqs`, `credentialNames`,
+`captures`, `notes`). Its auth compiler can send a recorded challenge, ask the
+user for an OTP or approval, and continue the same browser session. Ask ordinary
+questions with `prompt_user`. Do not write answers or host-held secret references
+into generated artifacts. Input is unavailable in a detached/noninteractive run;
+report that limitation honestly rather than treating it as approval.
+
 When you call `done`, the harness independently verifies the artifact contract
 for the accepted strategy.
 

package/prompts/component-recovery.md

@@ -0,0 +1,40 @@
+# Recover an owned component before changing a consumer contract
+
+You own one focused recovery decision for a failed check. The failure may come
+from authentication, a prerequisite, a shared module, or the caller's own
+artifact. Inspect the supplied facts and declared owners; the error code or a
+filename alone does not establish cause. Site names never select recovery.
+
+Return exactly one decision:
+
+- `{"action":"authenticate","plan":{...},"reason":"..."}` uses the attached
+  recording-grounded auth owner. Choose the appropriate listed context and
+  supplied credential/request declarations. The auth owner decides actions and
+  first checks or restores usable access in the retained browser before
+  restarting login. A recovered session returns to the unchanged consumer check.
+  Only observed current login/challenge evidence warrants another credential or
+  factor action. Obtain fresh human input when required; never invent or reuse
+  approval.
+- `{"action":"recover_component","componentId":"supplied id","reason":"..."}`
+  sends the exact failure to that declared component owner. Choose it only when
+  the evidence supports a component-local repair without changing the accepted
+  consumer contract. A prerequisite owner can rebuild its existing procedure;
+  dependent calls then bind fresh producer results. An explicitly registered
+  shared-module owner repairs and verifies that module through its normal host.
+- `{"action":"return_failure","reason":"..."}` requests broader master
+  investigation when ownership or cause is unclear, or the contract, strategy,
+  dependency graph, or scope needs changing.
+
+Return the decision directly, without an interaction envelope. Do not edit data
+artifacts yourself, invent owner identifiers, or assign all failures to auth.
+The host preserves each failed attempt and dispatches only to the chosen owner.
+Successful state recovery immediately retries the existing caller. Artifact
+repair preserves the accepted plan and rebuilds only the selected owner, then
+rechecks affected dependencies and consumer calls. Repair completion never
+substitutes for a passing consumer result.
+
+Use `previousRecoveries` and prior observations to reconsider repeated rejection;
+do not blindly repeat an unchanged repair. There is no fixed retry cap. Shared
+recovery is scoped to the explicit owner id, not a guessed similarity between
+sites, tool names, messages, cookies, or paths. If a component has no declared
+owner, return the failure rather than guessing who may modify it.

package/prompts/master-teach-decision.md

@@ -66,6 +66,18 @@ Missing transport provenance, an unnecessary dependency, or newly available
 sibling bootstrap evidence changes the request plan: omit the old
 `implementationPlan` and re-plan the tool instead of using `recallToolNames`.
 
+Failed checks have a focused component recovery path before they return here.
+The agent can select the attached auth owner, the caller's retained compiler,
+a declared prerequisite compiler, or an explicitly registered shared runtime
+owner. State recovery retries the exact built caller; artifact repair retains
+the accepted contract and implementation plan, rebuilds the selected owner,
+and rechecks affected consumers using fresh producer outputs. This does not
+require a master or focused planner decision merely to renew state or repair
+an artifact. Unknown ownership or changes to contract, strategy, dependency
+graph, or scope still require your judgment. Invocation receipts preserve failed
+attempts as well as retries. A repaired component or auth navigation checkpoint
+never substitutes for a passing consumer call.
+
 The input may include `userGuidance`. It is an explicit human scope or priority,
 not recording evidence. Follow it when deciding which discovered operations
 belong in the plan. In particular, if the user names the operations they care
@@ -196,6 +208,18 @@ working tools remain intact. No fake candidate edit is needed. Keep the useful
 request as a starting point and distinguish an unproven research claim from an
 exhausted API route. Do not request research for an ordinary parser-only defect.
 
+Planning feedback may include a `plan_note` with
+`kind:"api_research_plan_difference"`. It names bounded field-level differences
+between a proposal and an earlier researched construction, with the exact plan,
+research and observation references. Missing values appear as `null`; omitted
+differences remain available in those references. This is advisory evidence,
+not an API failure or a reason to restart the entire wave. You may revise the
+affected plan, request focused research, or accept the revised construction for
+normal compilation and checks. No extra justification document is required.
+Keep each observation attached to the construction it executed; accepting a
+different construction never transfers the old call's proof to the new build.
+Preserve unrelated successful drafts and the explicit dependency edges.
+
 When `decisionPurpose` is `research_review`, this is the two-way checkpoint
 before final plan approval. Independent proven tools may already have focused
 plan proposals and compiled drafts while other research continues. Review every
@@ -304,10 +328,11 @@ no-op digest; it does not decide which semantic repair is best.
 During focused planning or a later repair, changing a required
 producer-consumer promise invalidates only the affected producer and consumer.
 A new or changed result path, consumer parameter, dependency, or supporting
-recorded request then needs focused proof. During `research_review`, do not make
+recorded request needs checks of the resulting construction. During `research_review`, do not make
 a speculative link edit merely to authorize a sibling follow-up. A genuine
-change to the core operation boundary or standalone request still needs new
-research. Removing an optional idea, editing prose, changing confidence, or
+change to the core operation boundary or standalone request may need focused
+research; choose that explicitly when its observations would resolve a gap.
+Removing an optional idea, editing prose, changing confidence, or
 changing an internal edge label does not justify disturbing unrelated proven
 tools.
 

package/prompts/master-teach-focused-planner.md

@@ -71,7 +71,16 @@ for the master and request a narrower supported contract.
 Optional breadth can wait.
 
 Request research for every selected operation has already finished. Read the
-complete `apiResearch` handoff list before proposing this tool. A proven handoff
+supplied `apiResearch` handoffs for this tool and its declared dependencies.
+`apiResearchIndex` summarizes the other completed operations without repeating
+their full response previews and histories. Use those summaries together with
+`availableProducers` and `siblingToolEvidence` to notice a possible dependency or
+boundary change. When a sibling's exact construction or response is needed,
+read its `handoffRef` through run-local shared research; do not read unrelated
+handoffs simply because they exist. If no readable reference is supplied, tell
+the master which operation and detail you need. The index is a reading guide,
+not independent evidence or a replacement for a consumer's own test.
+A proven handoff
 contains the exact smallest tested workflow, parameter values, winning rung,
 backend facts, and redacted response preview. Use those factual request and
 response shapes to decide which calls stay inside one tool, every justified
@@ -86,10 +95,14 @@ The master has already returned partial handoffs to their retained researchers;
 do not silently complete or reinterpret a partial request in this planning
 stage. If an injected or older handoff is still partial, preserve its stated
 gap and tell the master that research must continue.
-Carry the proven workflow, request transform and producer value representations
-through unchanged. Plan parsing around that tested construction; do not rewrite
-its nested request envelope or redefine an upstream value's shape in prose.
-An executable construction change needs fresh research proof.
+Use the tested workflow, request transform and producer value representations
+as the factual starting point. Plan parsing around that construction unless the
+accepted contract or evidence supports revising it. Keep execution provenance
+truthful: a plain-fetch request does not acquire response-navigation provenance
+because a comparable parser fixture came from a browser response. You may propose
+a revised construction for master review or ask for focused research when that
+would resolve an uncertainty. Prior observations describe only the construction
+they executed; the revised build receives its own normal checks.
 Do not replace a proven minimal call with a larger recorded request graph. A
 blocked handoff is an exact research gap for the master to resolve; it is not
 automatic evidence for playbook.