@iamu-dev/iamu 0.2.0-beta.5 → 0.2.0-beta.6

package/dist/bin.js

@@ -200,17 +200,24 @@ function defaultConfig(params) {
     cloud_api_url: null
   };
 }
-var baseProjectFields, localOnlyConfig, cloudLinkedConfig, projectConfigSchema;
+var modelTierSchema, projectModelsConfigSchema, baseProjectFields, localOnlyConfig, cloudLinkedConfig, projectConfigSchema;
 var init_config = __esm({
   "../../packages/protocol/dist/schemas/frontmatter/config.js"() {
     "use strict";
     init_common();
     init_version();
+    modelTierSchema = z4.string().min(1).max(128).describe("Model role tier ('fast', 'thorough', 'inherit') or a specific model identifier.");
+    projectModelsConfigSchema = z4.object({
+      walker: modelTierSchema.optional(),
+      matcher: modelTierSchema.optional(),
+      judge: modelTierSchema.optional()
+    }).strict();
     baseProjectFields = {
       schema_version: z4.literal(SCHEMA_VERSION),
       id: uuidSchema,
       project_slug: slugSchema,
-      project_name: z4.string().min(1)
+      project_name: z4.string().min(1),
+      models: projectModelsConfigSchema.optional()
     };
     localOnlyConfig = z4.object({
       ...baseProjectFields,
@@ -1154,7 +1161,21 @@ var init_walkthrough_bundle = __esm({
           judge_prompt: z19.string().optional(),
           judge_model: z19.string().optional()
         }).optional()
-      }).optional()
+      }).optional(),
+      models: z19.object({
+        walker: z19.string().optional(),
+        matcher: z19.string().optional(),
+        judge: z19.string().optional(),
+        walker_reported: z19.string().optional(),
+        matcher_reported: z19.string().optional(),
+        judge_reported: z19.string().optional(),
+        walker_tier: z19.string().optional(),
+        matcher_tier: z19.string().optional(),
+        judge_tier: z19.string().optional(),
+        execution_mode: z19.enum(["multi_agent", "single_agent"]).optional(),
+        velocity_sec_per_step: z19.number().optional(),
+        total_duration_sec: z19.number().optional()
+      }).optional().describe("AI model configuration and reported runtime provenance for this walkthrough.")
     });
     walkthroughBundleSchema = z19.object({
       manifest: bundleManifestSchema,
@@ -1377,6 +1398,7 @@ var init_walkthrough_canonical = __esm({
       build: buildMetadataSchema.optional(),
       viewport: runViewportSchema.optional(),
       environment: z20.string().optional(),
+      models: z20.record(z20.unknown()).optional(),
       findings: z20.array(canonicalFindingSchema),
       steps: z20.array(canonicalStepSchema),
       human_tests: z20.array(canonicalHumanTestSchema),
@@ -7248,6 +7270,7 @@ async function buildCanonical(projectRoot, manifest, completedAt, inputs) {
     ...manifest.build ? { build: manifest.build } : {},
     ...manifest.viewport ? { viewport: manifest.viewport } : {},
     ...manifest.environment ? { environment: manifest.environment } : {},
+    ...manifest.models ? { models: manifest.models } : {},
     findings: canonicalFindings,
     steps: canonicalSteps,
     human_tests: humanTests,
@@ -7408,6 +7431,20 @@ function renderCanonicalMarkdown(canonical) {
     lines.push(`- Viewport: ${canonical.viewport.device} (${canonical.viewport.width}\xD7${canonical.viewport.height})`);
   }
   lines.push(`- Started: ${canonical.provenance.started_at}`, `- Completed: ${canonical.provenance.completed_at}`, `- Walker prompt: ${canonical.provenance.walker_prompt.id}@${canonical.provenance.walker_prompt.version}`, `- Findings: ${canonical.findings.length}`, `- Steps: ${canonical.steps.length}`);
+  const models = canonical.models;
+  if (models) {
+    const parts = [
+      models.walker ? `Walker: ${models.walker}${models.walker_reported ? ` (${models.walker_reported})` : ""}` : "",
+      models.judge ? `Judge: ${models.judge}${models.judge_reported ? ` (${models.judge_reported})` : ""}` : "",
+      models.matcher ? `Matcher: ${models.matcher}` : ""
+    ].filter(Boolean);
+    if (parts.length > 0) {
+      lines.push(`- Models: ${parts.join(" \xB7 ")}`);
+    }
+    if (typeof models.velocity_sec_per_step === "number") {
+      lines.push(`- Velocity: ~${models.velocity_sec_per_step}s/step (${models.total_duration_sec}s total)`);
+    }
+  }
   const what = canonical.what_worked;
   if (what && what.length > 0) {
     lines.push("", "## What worked");
@@ -7777,6 +7814,7 @@ async function assembleWalkthroughBundle(projectRoot, runId) {
       report_markdown: report3,
       verdict: verdictArray,
       judge_meta: judgeMeta,
+      ...manifest.models ? { models: manifest.models } : {},
       ...buildFields(manifest),
       ...await readCanonicalExtras(projectRoot, runId)
     },
@@ -14434,6 +14472,18 @@ async function startRun(scenarioSlug, opts) {
   }
   const build = detectBuild({ cwd: projectRoot, label: opts.build });
   const environment = resolveEnvironment(opts.env, start2.url);
+  const cfg = await readConfig(projectRoot).catch(() => null);
+  const walker = opts.walker ?? process.env.IAMU_WALKER_MODEL ?? cfg?.models?.walker ?? "fast";
+  const judge = opts.judge ?? process.env.IAMU_JUDGE_MODEL ?? cfg?.models?.judge ?? "thorough";
+  const matcher = opts.matcher ?? process.env.IAMU_MATCHER_MODEL ?? cfg?.models?.matcher ?? "thorough";
+  const models = {
+    walker,
+    judge,
+    matcher,
+    walker_tier: ["fast", "thorough", "inherit"].includes(walker) ? walker : "custom",
+    judge_tier: ["fast", "thorough", "inherit"].includes(judge) ? judge : "custom",
+    matcher_tier: ["fast", "thorough", "inherit"].includes(matcher) ? matcher : "custom"
+  };
   let revisit = [];
   try {
     revisit = await computeRevisitPlaces(projectRoot, scenarioSlug, start2.url);
@@ -14451,6 +14501,7 @@ async function startRun(scenarioSlug, opts) {
     status: "running",
     created_at: (/* @__PURE__ */ new Date()).toISOString(),
     completed_at: null,
+    models,
     ...build ? { build } : {},
     ...environment ? { environment } : {},
     ...revisit.length > 0 ? { revisit } : {},
@@ -14472,6 +14523,7 @@ async function startRun(scenarioSlug, opts) {
           ...targetWarning ? { target_warning: targetWarning } : {},
           persona_slug: fm.persona,
           outline_slug: fm.outline,
+          models,
           build: build ?? null,
           environment: environment ?? null,
           revisit,
@@ -14490,6 +14542,9 @@ async function startRun(scenarioSlug, opts) {
   console.log(`  ${chalk11.dim("persona:")}  ${fm.persona}`);
   console.log(`  ${chalk11.dim("outline:")}  ${fm.outline}`);
   console.log(`  ${chalk11.dim("target:")}   ${start2.url}`);
+  console.log(
+    `  ${chalk11.dim("models:")}   walker: ${chalk11.cyan(walker)} \xB7 judge: ${chalk11.cyan(judge)} \xB7 matcher: ${chalk11.cyan(matcher)}`
+  );
   if (targetWarning) {
     console.log(`  ${symbols.warning} ${chalk11.yellow(targetWarning)}`);
   }
@@ -16673,6 +16728,7 @@ __export(browse_exports, {
   readBrowseState: () => readBrowseState,
   shouldDisableSandbox: () => shouldDisableSandbox,
   start: () => start,
+  waitForVisualStability: () => waitForVisualStability,
   withPage: () => withPage
 });
 import { randomUUID as randomUUID7 } from "crypto";
@@ -16879,6 +16935,45 @@ async function stop(opts, driver) {
   }
   report2(opts, { stopped: true }, [`  ${chalk20.green("\u2713")} Browser stopped`]);
 }
+async function waitForVisualStability(page, maxWaitMs = 300) {
+  let timer;
+  try {
+    const nodeTimeout = new Promise((resolve4) => {
+      timer = setTimeout(resolve4, maxWaitMs + 100);
+    });
+    const browserWait = page.evaluate((maxWait) => {
+      return new Promise((resolve4) => {
+        const timeout = setTimeout(resolve4, maxWait);
+        const done = () => {
+          clearTimeout(timeout);
+          resolve4();
+        };
+        const g = globalThis;
+        if (typeof g.requestAnimationFrame !== "function") {
+          done();
+          return;
+        }
+        g.requestAnimationFrame(() => {
+          g.requestAnimationFrame?.(() => {
+            const animations = g.document?.getAnimations ? g.document.getAnimations().filter((a) => a.playState === "running" && a.finished) : [];
+            if (animations.length === 0) {
+              done();
+              return;
+            }
+            Promise.allSettled(
+              animations.map((a) => a.finished)
+            ).finally(done);
+          });
+        });
+      });
+    }, maxWaitMs).catch(() => {
+    });
+    await Promise.race([browserWait, nodeTimeout]);
+  } catch {
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
 async function withPage(opts, driver, fn, target) {
   const state = readBrowseState();
   if (!state) {
@@ -16898,9 +16993,9 @@ async function withPage(opts, driver, fn, target) {
     await fn(page);
     await page.waitForLoadState("domcontentloaded").catch(() => {
     });
-    await page.waitForTimeout(400);
     let screenshot = null;
     if (opts.shot) {
+      await waitForVisualStability(page);
       screenshot = path22.resolve(opts.shot);
       mkdirSync(path22.dirname(screenshot), { recursive: true });
       await page.screenshot({ path: screenshot, fullPage: Boolean(opts.full) });
@@ -18887,7 +18982,7 @@ function composeWalkerPrompt(p) {
     `Screenshots to: ${rd}/screenshots/step-N.png \u2014 absolute paths.`,
     `Record findings with: ${iamu} new-finding --scenario ${p.scenarioSlug} --run ${p.runId} --step <N> --title "..." --type <helps|hinders|missing|irrelevant|incorrect> --severity <critical|major|minor|observation> --ui-fact "..." --consequence "..." --task-impact <blocks|impairs|slows|neutral|accelerates|enables> --confidence <high|medium|low> --json \u2014 then add the body (description + "## Recommendation") below the frontmatter of the file it returns.`,
     "`--step <N>` is the step whose screenshot shows the problem (or strength): it is the evidence people see next to the finding, so record that step and its screenshot first, and pick the screenshot where the thing is actually visible.",
-    `Before you finish, write ${rd}/summary.json: {"what_worked": [...], "open_questions": [...]} \u2014 one sentence each, in the persona's language.`,
+    `Before you finish, write ${rd}/summary.json: {"what_worked": [...], "open_questions": [...], "model": "<your model identifier if known, e.g. claude-3-5-haiku, gemini-3.8-flash, or unspecified>"} \u2014 one sentence each, in the persona's language.`,
     "",
     "Do not read the product's source code, other iamu/ entity files, or earlier runs: you know only what the persona knows.",
     "",
@@ -19709,6 +19804,36 @@ async function complete(runId, opts) {
     return;
   }
   const completedAt = pickCompletedAt(run.manifest);
+  const walkerSummary = await readWalkerSummary(run.runDirPath);
+  let judgeReported;
+  try {
+    const verdictsRaw = await fs26.readFile(
+      path26.join(run.runDirPath, "verdicts.json"),
+      "utf8"
+    );
+    const parsed = JSON.parse(verdictsRaw);
+    if (parsed.provenance?.model) {
+      judgeReported = parsed.provenance.model;
+    }
+  } catch {
+  }
+  const stepCount = provenanceAudit.step_count;
+  const durationSec = provenanceAudit.duration_seconds ?? (run.manifest.created_at && Date.parse(completedAt) > Date.parse(run.manifest.created_at) ? Math.round(
+    (Date.parse(completedAt) - Date.parse(run.manifest.created_at)) / 1e3 * 10
+  ) / 10 : null);
+  const velocitySec = provenanceAudit.avg_step_interval_seconds ?? (durationSec != null && stepCount > 1 ? Math.round(durationSec / (stepCount - 1) * 10) / 10 : null);
+  const existingModels = run.manifest.models ?? {};
+  const updatedModels = {
+    ...existingModels,
+    ...walkerSummary.model ? { walker_reported: walkerSummary.model } : {},
+    ...judgeReported ? { judge_reported: judgeReported } : {},
+    ...durationSec != null ? { total_duration_sec: durationSec } : {},
+    ...velocitySec != null ? { velocity_sec_per_step: velocitySec } : {}
+  };
+  run.manifest = {
+    ...run.manifest,
+    models: updatedModels
+  };
   const assembled = await assembleRun(
     run.projectRoot,
     runId,
@@ -19869,6 +19994,17 @@ function printCompletionSummary(run, completedAt, assembled, extras, provenanceA
   console.log(`  steps      ${count(canonical.steps.length)}`);
   console.log(`  started    ${chalk30.dim(manifest.created_at)}`);
   console.log(`  completed  ${chalk30.dim(completedAt)}`);
+  const models = manifest.models;
+  if (models?.velocity_sec_per_step != null) {
+    console.log(
+      `  velocity   ${chalk30.cyan(`~${models.velocity_sec_per_step}s/step`)} ${chalk30.dim(`(${models.total_duration_sec}s total)`)}`
+    );
+  }
+  if (models && (models.walker || models.judge || models.matcher)) {
+    const w = models.walker_reported ? `${models.walker} (${models.walker_reported})` : models.walker ?? "fast";
+    const j = models.judge_reported ? `${models.judge} (${models.judge_reported})` : models.judge ?? "thorough";
+    console.log(`  models     ${chalk30.dim(`walker: ${w} \xB7 judge: ${j}`)}`);
+  }
   console.log();
   console.log(
     `  ${chalk30.dim("canonical:")} ${chalk30.dim(path26.relative(projectRoot, assembled.canonicalPath))}`
@@ -19962,9 +20098,11 @@ async function readWalkerSummary(runDirPath) {
       await fs26.readFile(path26.join(runDirPath, "summary.json"), "utf8")
     );
     const strings = (v) => Array.isArray(v) ? v.filter((x) => typeof x === "string" && x.trim() !== "") : void 0;
+    const model = typeof data.model === "string" && data.model.trim() !== "" ? data.model.trim() : void 0;
     return {
       what_worked: strings(data.what_worked),
-      open_questions: strings(data.open_questions)
+      open_questions: strings(data.open_questions),
+      model
     };
   } catch {
     return {};
@@ -20754,6 +20892,15 @@ function registerWalkthroughCommands(program2) {
   ).option(
     "--env <name>",
     "Environment the product runs in (default: the target URL's origin)"
+  ).option(
+    "--walker <tierOrModel>",
+    "Model tier ('fast', 'thorough', 'inherit') or model ID for driving browser navigation (default: fast)"
+  ).option(
+    "--judge <tierOrModel>",
+    "Model tier ('fast', 'thorough', 'inherit') or model ID for human test evaluation (default: thorough)"
+  ).option(
+    "--matcher <tierOrModel>",
+    "Model tier ('fast', 'thorough', 'inherit') or model ID for finding matching (default: thorough)"
   ).option(
     "--check",
     "Enforce target URL reachability (fail fast if server is offline)"

package/dist/commands/start-run.d.ts

@@ -0,0 +1,52 @@
+import { type BuildMetadata, type RunViewport, type ScenarioFrontmatter } from "@iamu-dev/protocol";
+/**
+ * The URL a run starts at: `--target` (or the scenario's `target_url`)
+ * as the base, with the scenario's `entry_path` resolved against it.
+ * Returns an error message instead when there is nothing usable.
+ */
+export declare function resolveStartUrl(target: string | undefined, scenario: Pick<ScenarioFrontmatter, "target_url" | "entry_path">): {
+    url: string;
+} | {
+    error: string;
+};
+/**
+ * Fast preflight probe to check if the target URL answers HTTP requests.
+ * Times out quickly (default: 1000ms) to avoid stalling walkthrough initialization.
+ */
+export declare function checkTargetReachable(url: string, timeoutMs?: number): Promise<{
+    reachable: boolean;
+    error?: string;
+}>;
+/**
+ * The build as one line: label, branch, commit and CI provider. A dirty
+ * tree shows next to the commit, so a re-run after an uncommitted fix
+ * visibly walks a different build.
+ *
+ * @example
+ * ```ts
+ * formatBuild({ git_sha: "90e2444…", git_dirty: true, worktree_hash: "3fa9c1d2e4b5" });
+ * // "90e2444 + uncommitted changes (3fa9c1…)"
+ * ```
+ */
+export declare function formatBuild(build: BuildMetadata): string;
+/**
+ * A run viewport as one line.
+ *
+ * @example
+ * ```ts
+ * formatViewport({ device: "desktop", width: 1280, height: 800, source: "persona-tags" });
+ * // "desktop 1280×800 (from persona tags)"
+ * ```
+ */
+export declare function formatViewport(v: RunViewport): string;
+export interface StartRunOptions {
+    target?: string;
+    build?: string;
+    env?: string;
+    json?: boolean;
+    check?: boolean;
+    walker?: string;
+    judge?: string;
+    matcher?: string;
+}
+export declare function startRun(scenarioSlug: string, opts: StartRunOptions): Promise<void>;

package/dist/index.js

@@ -199,17 +199,24 @@ function defaultConfig(params) {
     cloud_api_url: null
   };
 }
-var baseProjectFields, localOnlyConfig, cloudLinkedConfig, projectConfigSchema;
+var modelTierSchema, projectModelsConfigSchema, baseProjectFields, localOnlyConfig, cloudLinkedConfig, projectConfigSchema;
 var init_config = __esm({
   "../../packages/protocol/dist/schemas/frontmatter/config.js"() {
     "use strict";
     init_common();
     init_version();
+    modelTierSchema = z4.string().min(1).max(128).describe("Model role tier ('fast', 'thorough', 'inherit') or a specific model identifier.");
+    projectModelsConfigSchema = z4.object({
+      walker: modelTierSchema.optional(),
+      matcher: modelTierSchema.optional(),
+      judge: modelTierSchema.optional()
+    }).strict();
     baseProjectFields = {
       schema_version: z4.literal(SCHEMA_VERSION),
       id: uuidSchema,
       project_slug: slugSchema,
-      project_name: z4.string().min(1)
+      project_name: z4.string().min(1),
+      models: projectModelsConfigSchema.optional()
     };
     localOnlyConfig = z4.object({
       ...baseProjectFields,
@@ -1153,7 +1160,21 @@ var init_walkthrough_bundle = __esm({
           judge_prompt: z19.string().optional(),
           judge_model: z19.string().optional()
         }).optional()
-      }).optional()
+      }).optional(),
+      models: z19.object({
+        walker: z19.string().optional(),
+        matcher: z19.string().optional(),
+        judge: z19.string().optional(),
+        walker_reported: z19.string().optional(),
+        matcher_reported: z19.string().optional(),
+        judge_reported: z19.string().optional(),
+        walker_tier: z19.string().optional(),
+        matcher_tier: z19.string().optional(),
+        judge_tier: z19.string().optional(),
+        execution_mode: z19.enum(["multi_agent", "single_agent"]).optional(),
+        velocity_sec_per_step: z19.number().optional(),
+        total_duration_sec: z19.number().optional()
+      }).optional().describe("AI model configuration and reported runtime provenance for this walkthrough.")
     });
     walkthroughBundleSchema = z19.object({
       manifest: bundleManifestSchema,
@@ -1376,6 +1397,7 @@ var init_walkthrough_canonical = __esm({
       build: buildMetadataSchema.optional(),
       viewport: runViewportSchema.optional(),
       environment: z20.string().optional(),
+      models: z20.record(z20.unknown()).optional(),
       findings: z20.array(canonicalFindingSchema),
       steps: z20.array(canonicalStepSchema),
       human_tests: z20.array(canonicalHumanTestSchema),
@@ -7247,6 +7269,7 @@ async function buildCanonical(projectRoot, manifest, completedAt, inputs) {
     ...manifest.build ? { build: manifest.build } : {},
     ...manifest.viewport ? { viewport: manifest.viewport } : {},
     ...manifest.environment ? { environment: manifest.environment } : {},
+    ...manifest.models ? { models: manifest.models } : {},
     findings: canonicalFindings,
     steps: canonicalSteps,
     human_tests: humanTests,
@@ -7407,6 +7430,20 @@ function renderCanonicalMarkdown(canonical) {
     lines.push(`- Viewport: ${canonical.viewport.device} (${canonical.viewport.width}\xD7${canonical.viewport.height})`);
   }
   lines.push(`- Started: ${canonical.provenance.started_at}`, `- Completed: ${canonical.provenance.completed_at}`, `- Walker prompt: ${canonical.provenance.walker_prompt.id}@${canonical.provenance.walker_prompt.version}`, `- Findings: ${canonical.findings.length}`, `- Steps: ${canonical.steps.length}`);
+  const models = canonical.models;
+  if (models) {
+    const parts = [
+      models.walker ? `Walker: ${models.walker}${models.walker_reported ? ` (${models.walker_reported})` : ""}` : "",
+      models.judge ? `Judge: ${models.judge}${models.judge_reported ? ` (${models.judge_reported})` : ""}` : "",
+      models.matcher ? `Matcher: ${models.matcher}` : ""
+    ].filter(Boolean);
+    if (parts.length > 0) {
+      lines.push(`- Models: ${parts.join(" \xB7 ")}`);
+    }
+    if (typeof models.velocity_sec_per_step === "number") {
+      lines.push(`- Velocity: ~${models.velocity_sec_per_step}s/step (${models.total_duration_sec}s total)`);
+    }
+  }
   const what = canonical.what_worked;
   if (what && what.length > 0) {
     lines.push("", "## What worked");
@@ -7776,6 +7813,7 @@ async function assembleWalkthroughBundle(projectRoot, runId) {
       report_markdown: report3,
       verdict: verdictArray,
       judge_meta: judgeMeta,
+      ...manifest.models ? { models: manifest.models } : {},
       ...buildFields(manifest),
       ...await readCanonicalExtras(projectRoot, runId)
     },
@@ -14413,6 +14451,18 @@ async function startRun(scenarioSlug, opts) {
   }
   const build = detectBuild({ cwd: projectRoot, label: opts.build });
   const environment = resolveEnvironment(opts.env, start2.url);
+  const cfg = await readConfig(projectRoot).catch(() => null);
+  const walker = opts.walker ?? process.env.IAMU_WALKER_MODEL ?? cfg?.models?.walker ?? "fast";
+  const judge = opts.judge ?? process.env.IAMU_JUDGE_MODEL ?? cfg?.models?.judge ?? "thorough";
+  const matcher = opts.matcher ?? process.env.IAMU_MATCHER_MODEL ?? cfg?.models?.matcher ?? "thorough";
+  const models = {
+    walker,
+    judge,
+    matcher,
+    walker_tier: ["fast", "thorough", "inherit"].includes(walker) ? walker : "custom",
+    judge_tier: ["fast", "thorough", "inherit"].includes(judge) ? judge : "custom",
+    matcher_tier: ["fast", "thorough", "inherit"].includes(matcher) ? matcher : "custom"
+  };
   let revisit = [];
   try {
     revisit = await computeRevisitPlaces(projectRoot, scenarioSlug, start2.url);
@@ -14430,6 +14480,7 @@ async function startRun(scenarioSlug, opts) {
     status: "running",
     created_at: (/* @__PURE__ */ new Date()).toISOString(),
     completed_at: null,
+    models,
     ...build ? { build } : {},
     ...environment ? { environment } : {},
     ...revisit.length > 0 ? { revisit } : {},
@@ -14451,6 +14502,7 @@ async function startRun(scenarioSlug, opts) {
           ...targetWarning ? { target_warning: targetWarning } : {},
           persona_slug: fm.persona,
           outline_slug: fm.outline,
+          models,
           build: build ?? null,
           environment: environment ?? null,
           revisit,
@@ -14469,6 +14521,9 @@ async function startRun(scenarioSlug, opts) {
   console.log(`  ${chalk11.dim("persona:")}  ${fm.persona}`);
   console.log(`  ${chalk11.dim("outline:")}  ${fm.outline}`);
   console.log(`  ${chalk11.dim("target:")}   ${start2.url}`);
+  console.log(
+    `  ${chalk11.dim("models:")}   walker: ${chalk11.cyan(walker)} \xB7 judge: ${chalk11.cyan(judge)} \xB7 matcher: ${chalk11.cyan(matcher)}`
+  );
   if (targetWarning) {
     console.log(`  ${symbols.warning} ${chalk11.yellow(targetWarning)}`);
   }
@@ -16652,6 +16707,7 @@ __export(browse_exports, {
   readBrowseState: () => readBrowseState,
   shouldDisableSandbox: () => shouldDisableSandbox,
   start: () => start,
+  waitForVisualStability: () => waitForVisualStability,
   withPage: () => withPage
 });
 import { randomUUID as randomUUID7 } from "crypto";
@@ -16858,6 +16914,45 @@ async function stop(opts, driver) {
   }
   report2(opts, { stopped: true }, [`  ${chalk20.green("\u2713")} Browser stopped`]);
 }
+async function waitForVisualStability(page, maxWaitMs = 300) {
+  let timer;
+  try {
+    const nodeTimeout = new Promise((resolve3) => {
+      timer = setTimeout(resolve3, maxWaitMs + 100);
+    });
+    const browserWait = page.evaluate((maxWait) => {
+      return new Promise((resolve3) => {
+        const timeout = setTimeout(resolve3, maxWait);
+        const done = () => {
+          clearTimeout(timeout);
+          resolve3();
+        };
+        const g = globalThis;
+        if (typeof g.requestAnimationFrame !== "function") {
+          done();
+          return;
+        }
+        g.requestAnimationFrame(() => {
+          g.requestAnimationFrame?.(() => {
+            const animations = g.document?.getAnimations ? g.document.getAnimations().filter((a) => a.playState === "running" && a.finished) : [];
+            if (animations.length === 0) {
+              done();
+              return;
+            }
+            Promise.allSettled(
+              animations.map((a) => a.finished)
+            ).finally(done);
+          });
+        });
+      });
+    }, maxWaitMs).catch(() => {
+    });
+    await Promise.race([browserWait, nodeTimeout]);
+  } catch {
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
 async function withPage(opts, driver, fn, target) {
   const state = readBrowseState();
   if (!state) {
@@ -16877,9 +16972,9 @@ async function withPage(opts, driver, fn, target) {
     await fn(page);
     await page.waitForLoadState("domcontentloaded").catch(() => {
     });
-    await page.waitForTimeout(400);
     let screenshot = null;
     if (opts.shot) {
+      await waitForVisualStability(page);
       screenshot = path22.resolve(opts.shot);
       mkdirSync(path22.dirname(screenshot), { recursive: true });
       await page.screenshot({ path: screenshot, fullPage: Boolean(opts.full) });
@@ -18866,7 +18961,7 @@ function composeWalkerPrompt(p) {
     `Screenshots to: ${rd}/screenshots/step-N.png \u2014 absolute paths.`,
     `Record findings with: ${iamu} new-finding --scenario ${p.scenarioSlug} --run ${p.runId} --step <N> --title "..." --type <helps|hinders|missing|irrelevant|incorrect> --severity <critical|major|minor|observation> --ui-fact "..." --consequence "..." --task-impact <blocks|impairs|slows|neutral|accelerates|enables> --confidence <high|medium|low> --json \u2014 then add the body (description + "## Recommendation") below the frontmatter of the file it returns.`,
     "`--step <N>` is the step whose screenshot shows the problem (or strength): it is the evidence people see next to the finding, so record that step and its screenshot first, and pick the screenshot where the thing is actually visible.",
-    `Before you finish, write ${rd}/summary.json: {"what_worked": [...], "open_questions": [...]} \u2014 one sentence each, in the persona's language.`,
+    `Before you finish, write ${rd}/summary.json: {"what_worked": [...], "open_questions": [...], "model": "<your model identifier if known, e.g. claude-3-5-haiku, gemini-3.8-flash, or unspecified>"} \u2014 one sentence each, in the persona's language.`,
     "",
     "Do not read the product's source code, other iamu/ entity files, or earlier runs: you know only what the persona knows.",
     "",
@@ -19688,6 +19783,36 @@ async function complete(runId, opts) {
     return;
   }
   const completedAt = pickCompletedAt(run.manifest);
+  const walkerSummary = await readWalkerSummary(run.runDirPath);
+  let judgeReported;
+  try {
+    const verdictsRaw = await fs26.readFile(
+      path26.join(run.runDirPath, "verdicts.json"),
+      "utf8"
+    );
+    const parsed = JSON.parse(verdictsRaw);
+    if (parsed.provenance?.model) {
+      judgeReported = parsed.provenance.model;
+    }
+  } catch {
+  }
+  const stepCount = provenanceAudit.step_count;
+  const durationSec = provenanceAudit.duration_seconds ?? (run.manifest.created_at && Date.parse(completedAt) > Date.parse(run.manifest.created_at) ? Math.round(
+    (Date.parse(completedAt) - Date.parse(run.manifest.created_at)) / 1e3 * 10
+  ) / 10 : null);
+  const velocitySec = provenanceAudit.avg_step_interval_seconds ?? (durationSec != null && stepCount > 1 ? Math.round(durationSec / (stepCount - 1) * 10) / 10 : null);
+  const existingModels = run.manifest.models ?? {};
+  const updatedModels = {
+    ...existingModels,
+    ...walkerSummary.model ? { walker_reported: walkerSummary.model } : {},
+    ...judgeReported ? { judge_reported: judgeReported } : {},
+    ...durationSec != null ? { total_duration_sec: durationSec } : {},
+    ...velocitySec != null ? { velocity_sec_per_step: velocitySec } : {}
+  };
+  run.manifest = {
+    ...run.manifest,
+    models: updatedModels
+  };
   const assembled = await assembleRun(
     run.projectRoot,
     runId,
@@ -19848,6 +19973,17 @@ function printCompletionSummary(run, completedAt, assembled, extras, provenanceA
   console.log(`  steps      ${count(canonical.steps.length)}`);
   console.log(`  started    ${chalk30.dim(manifest.created_at)}`);
   console.log(`  completed  ${chalk30.dim(completedAt)}`);
+  const models = manifest.models;
+  if (models?.velocity_sec_per_step != null) {
+    console.log(
+      `  velocity   ${chalk30.cyan(`~${models.velocity_sec_per_step}s/step`)} ${chalk30.dim(`(${models.total_duration_sec}s total)`)}`
+    );
+  }
+  if (models && (models.walker || models.judge || models.matcher)) {
+    const w = models.walker_reported ? `${models.walker} (${models.walker_reported})` : models.walker ?? "fast";
+    const j = models.judge_reported ? `${models.judge} (${models.judge_reported})` : models.judge ?? "thorough";
+    console.log(`  models     ${chalk30.dim(`walker: ${w} \xB7 judge: ${j}`)}`);
+  }
   console.log();
   console.log(
     `  ${chalk30.dim("canonical:")} ${chalk30.dim(path26.relative(projectRoot, assembled.canonicalPath))}`
@@ -19941,9 +20077,11 @@ async function readWalkerSummary(runDirPath) {
       await fs26.readFile(path26.join(runDirPath, "summary.json"), "utf8")
     );
     const strings = (v) => Array.isArray(v) ? v.filter((x) => typeof x === "string" && x.trim() !== "") : void 0;
+    const model = typeof data.model === "string" && data.model.trim() !== "" ? data.model.trim() : void 0;
     return {
       what_worked: strings(data.what_worked),
-      open_questions: strings(data.open_questions)
+      open_questions: strings(data.open_questions),
+      model
     };
   } catch {
     return {};
@@ -20725,6 +20863,15 @@ function registerWalkthroughCommands(program) {
   ).option(
     "--env <name>",
     "Environment the product runs in (default: the target URL's origin)"
+  ).option(
+    "--walker <tierOrModel>",
+    "Model tier ('fast', 'thorough', 'inherit') or model ID for driving browser navigation (default: fast)"
+  ).option(
+    "--judge <tierOrModel>",
+    "Model tier ('fast', 'thorough', 'inherit') or model ID for human test evaluation (default: thorough)"
+  ).option(
+    "--matcher <tierOrModel>",
+    "Model tier ('fast', 'thorough', 'inherit') or model ID for finding matching (default: thorough)"
   ).option(
     "--check",
     "Enforce target URL reachability (fail fast if server is offline)"

package/dist/templates/skills/iamu-run.md

@@ -185,12 +185,16 @@ The result's `walker_prompt` is the walker's entire prompt. Pass it verbatim —
 
 A fresh subagent is NOT blind by default. On most hosts it still loads the project's agent instructions and can read files in the repo, so it may know the domain model, the route table, and why a screen was built the way it was — none of which the persona knows. The methodology's "Stay outside the product" rule is what keeps it honest; it is part of `walker_prompt` — never remove or soften it. If the host lets you restrict a subagent's tools, give the walker only the driving surface, file write/edit, and a shell for `iamu` commands.
 
+**Model tiering & subagent dispatch:**
+- **Walker (Browser Navigation):** High turn count, mechanical tool-use. Use the **fast** model tier (`flash` or `haiku`) by default to cut walk time by ~60% and conserve session quota.
+- **Matcher & Judge:** Broad synthesis and semantic comparison. Use the **thorough** frontier tier (`pro`, `sonnet`, or active model) to prevent severity inflation.
+
 ```
 # In Claude Code:
-Agent({ description: "Walk <scenario-slug> as <persona.name>", prompt: "<walker_prompt, verbatim>" })
+Agent({ description: "Walk <scenario-slug> as <persona.name>", model: "haiku", prompt: "<walker_prompt, verbatim>" })
 
 # In Antigravity / generic subagent hosts:
-invoke_subagent(Role="Persona Walker", Prompt="<walker_prompt, verbatim>")
+invoke_subagent(Role="Persona Walker", Model="flash", Prompt="<walker_prompt, verbatim>")
 ```
 
 The subagent inherits the driving-surface tools and drives the product independently. It does not see this conversation.
@@ -202,7 +206,7 @@ The subagent inherits the driving-surface tools and drives the product independe
 - **Screenshot every 3-4 taps at most.** Batching more desyncs the moment an answer opens a screen she did not expect.
 - **Coordinates are device points, origin top-left.** A scaled screenshot must be mapped back to that space before tapping.
 
-**If subagent dispatch is not supported by your host editor** (e.g. standard Cursor without subagent tools), fall back to walking in the same context — but strictly adhere to the persona behavioral constraints in `walker_prompt`.
+**If subagent dispatch or model-switching is not supported by your host editor** (e.g. standard Cursor / Windsurf single-session mode), fall back to walking directly in the current session (inheriting the active model) — but strictly adhere to the persona behavioral constraints in `walker_prompt`.
 
 After the walker returns, continue to the post-walk pipeline below.
 
@@ -269,7 +273,7 @@ This reads all steps, findings, and entity files, assembles `canonical.json`, ge
 iamu match <run-id> --json
 ```
 
-If `needed` is `false` (no earlier findings for this scenario, or none this run), skip to C. Otherwise, read the prompt from `iamu/.runs/<run-id>/match_prompt.md` directly and dispatch a matcher subagent with it as its only context. Write its JSON answer to `<matches.json>` and record it:
+If `needed` is `false` (no earlier findings for this scenario, or none this run), skip to C. Otherwise, read the prompt from `iamu/.runs/<run-id>/match_prompt.md` directly and dispatch a matcher subagent with it as its only context (use the **thorough** model tier, e.g. `Model="pro"` in Antigravity, to accurately evaluate semantic equivalence). Write its JSON answer to `<matches.json>` and record it:
 
 ```bash
 iamu match-record <run-id> --file <matches.json>
@@ -283,7 +287,7 @@ This links recurrences to their earlier canonical finding, marks earlier finding
 iamu evaluate <run-id> --json
 ```
 
-Read the evaluation prompt from `iamu/.runs/<run-id>/judge_prompt.md` directly. Dispatch the evaluator as a subagent with that prompt. After the evaluator returns verdicts, record them locally with `--no-push`:
+Read the evaluation prompt from `iamu/.runs/<run-id>/judge_prompt.md` directly. Dispatch the evaluator as a subagent with that prompt (use the **thorough** model tier, e.g. `Model="pro"` in Antigravity, to prevent severity inflation). After the evaluator returns verdicts, record them locally with `--no-push`:
 
 ```bash
 iamu evaluate-record <run-id> --file <verdicts.json> --no-prompt --no-push

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iamu-dev/iamu",
-  "version": "0.2.0-beta.5",
+  "version": "0.2.0-beta.6",
   "type": "module",
   "description": "Test your product as realistic personas — scenario-driven development CLI",
   "license": "UNLICENSED",
@@ -57,9 +57,9 @@
     "tsup": "^8.5.1",
     "typescript": "^5.8.0",
     "vitest": "^4.1.11",
+    "@iamu-dev/protocol": "0.1.0",
     "@iamu-dev/local-store": "0.1.0",
-    "@iamu/tsconfig": "0.1.0",
-    "@iamu-dev/protocol": "0.1.0"
+    "@iamu/tsconfig": "0.1.0"
   },
   "scripts": {
     "build": "tsup && tsc -b tsconfig.build.json --emitDeclarationOnly && node scripts/copy-assets.mjs",