@iamu-dev/iamu 0.2.0-beta.4 → 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) });
@@ -17001,6 +17096,35 @@ function printStep(opts, record, projectRoot) {
   }
 }
 async function browseStep(args, opts, driver) {
+  if (opts.stepFile) {
+    try {
+      let raw;
+      if (opts.stepFile === "-") {
+        raw = readFileSync6(0, "utf8");
+      } else {
+        raw = readFileSync6(opts.stepFile, "utf8");
+      }
+      const data = JSON.parse(raw);
+      if (data.run && typeof data.run === "string") opts.run = data.run;
+      if (data.action && typeof data.action === "string")
+        opts.action = data.action;
+      if (data.note && typeof data.note === "string") opts.note = data.note;
+      if (data.surface && typeof data.surface === "string")
+        opts.surface = data.surface;
+      if (args.length === 0 && data.cmd) {
+        if (Array.isArray(data.cmd)) {
+          args = data.cmd.map(String);
+        } else if (typeof data.cmd === "string") {
+          args = data.cmd.trim().split(/\s+/);
+        }
+      }
+    } catch (err) {
+      return fail(
+        `Failed to read step payload from ${opts.stepFile}: ${err.message}`,
+        opts
+      );
+    }
+  }
   if (!opts.run)
     return fail("--run <run-id> is required for browse step.", opts);
   if (!opts.action) {
@@ -18858,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.",
     "",
@@ -19457,8 +19581,21 @@ async function evaluate(runId, opts) {
     )
   };
   const prompt = composeJudgePrompt(input);
+  const promptFilePath = opts?.promptFile ?? path25.join(runDirPath, "judge_prompt.md");
+  await fs25.writeFile(promptFilePath, prompt, "utf8");
   if (opts?.json) {
-    console.log(JSON.stringify({ ...input, judge_prompt: prompt }, null, 2));
+    console.log(
+      JSON.stringify(
+        {
+          ...input,
+          prompt_file: path25.relative(projectRoot, promptFilePath),
+          prompt_file_abs: path25.resolve(promptFilePath),
+          judge_prompt: prompt
+        },
+        null,
+        2
+      )
+    );
     return;
   }
   console.log(prompt);
@@ -19550,7 +19687,7 @@ ${formatIssues(fileResult.error)}`,
     runId,
     validatedVerdicts
   );
-  const cloudInfo = await pushRunToCloud(projectRoot, runId);
+  const cloudInfo = opts?.push === false ? void 0 : await pushRunToCloud(projectRoot, runId);
   if (opts?.json) {
     console.log(
       JSON.stringify(
@@ -19667,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,
@@ -19794,7 +19961,7 @@ async function collectCompletionExtras(run, opts) {
     parseRunViewport(manifest.viewport)
   );
   const codeWarning = opts?.force ? null : codeChangedWarning(manifest.build, detectWorktreeState(projectRoot));
-  const cloudInfo = await pushRunToCloud(projectRoot, runId);
+  const cloudInfo = opts?.push === false ? void 0 : await pushRunToCloud(projectRoot, runId);
   return { revisit, viewportWarning, codeWarning, cloudInfo };
 }
 function completeJsonPayload(canonical, extras) {
@@ -19827,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))}`
@@ -19920,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 {};
@@ -20247,9 +20427,28 @@ async function match(runId, opts) {
   );
   const needed = input.current.length > 0 && (input.prior.length > 0 || (input.guidance ?? []).length > 0);
   const prompt = needed ? composeMatchPrompt(input) : null;
+  const promptFilePath = opts?.promptFile ?? path27.join(runDirPath, "match_prompt.md");
+  if (prompt) {
+    await fs27.writeFile(promptFilePath, prompt, "utf8");
+  } else {
+    try {
+      await fs27.unlink(promptFilePath);
+    } catch {
+    }
+  }
   if (opts?.json) {
     console.log(
-      JSON.stringify({ ...input, needed, match_prompt: prompt }, null, 2)
+      JSON.stringify(
+        {
+          ...input,
+          needed,
+          prompt_file: prompt ? path27.relative(ctx.projectRoot, promptFilePath) : null,
+          prompt_file_abs: prompt ? path27.resolve(promptFilePath) : null,
+          match_prompt: prompt
+        },
+        null,
+        2
+      )
     );
     return;
   }
@@ -20693,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)"
@@ -20723,7 +20931,10 @@ function registerWalkthroughCommands(program2) {
   ).option(
     "--run <run-id>",
     "Run ID to size browser (start) or record step into (step)"
-  ).option("--action <text>", "Action description (step only)").option("--note <text>", "Persona inner monologue / reasoning (step only)").option("--surface <name>", "Screen or surface name (step only)").option("--width <px>", "Window width (start)").option("--height <px>", "Window height (start)").option("--headless", "Run without a window (start)").option(
+  ).option("--action <text>", "Action description (step only)").option("--note <text>", "Persona inner monologue / reasoning (step only)").option("--surface <name>", "Screen or surface name (step only)").option(
+    "--step-file <path>",
+    "Read step payload (action, note, cmd) from a JSON file or '-' for stdin (step only)"
+  ).option("--width <px>", "Window width (start)").option("--height <px>", "Window height (start)").option("--headless", "Run without a window (start)").option(
     "--port <port>",
     "CDP port (start), default 9333",
     (value) => parsePortOption(value)
@@ -20799,9 +21010,9 @@ function registerWalkthroughCommands(program2) {
   ).option("-y, --yes", "Skip interactive prompts").option("--no-prompt", "Skip interactive prompt to view results").option("--view", "Open results in browser immediately without prompt").option(
     "--strict-provenance",
     "Fail if steps show synthetic or programmatic timing anomalies"
-  ).addHelpText(
+  ).option("--no-push", "Skip pushing the run to Iamu Cloud").addHelpText(
     "after",
-    "\nExamples:\n  $ iamu complete <run-id>\n  $ iamu complete <run-id> --view\n  $ iamu complete <run-id> --no-prompt\n  $ iamu complete <run-id> --json\n  $ iamu complete <run-id> --strict-provenance"
+    "\nExamples:\n  $ iamu complete <run-id>\n  $ iamu complete <run-id> --view\n  $ iamu complete <run-id> --no-prompt\n  $ iamu complete <run-id> --no-push\n  $ iamu complete <run-id> --json\n  $ iamu complete <run-id> --strict-provenance"
   ).action(
     async (runId, opts) => {
       const { complete: complete2 } = await Promise.resolve().then(() => (init_complete(), complete_exports));
@@ -20810,23 +21021,27 @@ function registerWalkthroughCommands(program2) {
   );
   program2.command("match <run-id>").helpGroup("Walkthrough:").description(
     "Compose the prompt that links this run's findings to earlier ones"
-  ).option("--json", "Output the match input bundle as JSON").action(async (runId, opts) => {
-    const { match: match2 } = await Promise.resolve().then(() => (init_match(), match_exports));
-    await match2(runId, opts);
-  });
+  ).option("--json", "Output the match input bundle as JSON").option("--prompt-file <path>", "Write the generated prompt to a file").action(
+    async (runId, opts) => {
+      const { match: match2 } = await Promise.resolve().then(() => (init_match(), match_exports));
+      await match2(runId, opts);
+    }
+  );
   program2.command("match-record <run-id>").helpGroup("Walkthrough:").description(
     "Record finding matches and re-derive the run's since-last-run delta"
   ).requiredOption("--file <path>", "Path to matches JSON file").option("--json", "Output match results as JSON").action(async (runId, opts) => {
     const { matchRecord: matchRecord2 } = await Promise.resolve().then(() => (init_match(), match_exports));
     await matchRecord2(runId, opts);
   });
-  program2.command("evaluate <run-id>").helpGroup("Walkthrough:").description("Compose evaluation prompt for human-test questions").option("--json", "Output evaluation input bundle as JSON").action(async (runId, opts) => {
-    const { evaluate: evaluate2 } = await Promise.resolve().then(() => (init_evaluate(), evaluate_exports));
-    await evaluate2(runId, opts);
-  });
-  program2.command("evaluate-record <run-id>").helpGroup("Walkthrough:").description("Record evaluation verdicts into the run's verdicts.json").requiredOption("--file <path>", "Path to verdicts JSON file").option("--json", "Output summary as JSON").option("-y, --yes", "Skip interactive prompts").option("--no-prompt", "Skip interactive prompt to view results").option("--view", "Open results in browser immediately without prompt").addHelpText(
+  program2.command("evaluate <run-id>").helpGroup("Walkthrough:").description("Compose evaluation prompt for human-test questions").option("--json", "Output evaluation input bundle as JSON").option("--prompt-file <path>", "Write the generated prompt to a file").action(
+    async (runId, opts) => {
+      const { evaluate: evaluate2 } = await Promise.resolve().then(() => (init_evaluate(), evaluate_exports));
+      await evaluate2(runId, opts);
+    }
+  );
+  program2.command("evaluate-record <run-id>").helpGroup("Walkthrough:").description("Record evaluation verdicts into the run's verdicts.json").requiredOption("--file <path>", "Path to verdicts JSON file").option("--json", "Output summary as JSON").option("-y, --yes", "Skip interactive prompts").option("--no-prompt", "Skip interactive prompt to view results").option("--no-push", "Skip pushing the updated run to Iamu Cloud").option("--view", "Open results in browser immediately without prompt").addHelpText(
     "after",
-    "\nExamples:\n  $ iamu evaluate-record <run-id> --file verdicts.json\n  $ iamu evaluate-record <run-id> --file verdicts.json --no-prompt\n  $ iamu evaluate-record <run-id> --file verdicts.json --json"
+    "\nExamples:\n  $ iamu evaluate-record <run-id> --file verdicts.json\n  $ iamu evaluate-record <run-id> --file verdicts.json --no-prompt\n  $ iamu evaluate-record <run-id> --file verdicts.json --no-push\n  $ iamu evaluate-record <run-id> --file verdicts.json --json"
   ).action(
     async (runId, opts) => {
       const { evaluateRecord: evaluateRecord2 } = await Promise.resolve().then(() => (init_evaluate(), evaluate_exports));

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>;