@iamu-dev/iamu 0.8.0-beta.3 → 0.8.0-beta.5

package/dist/build-hash.txt

@@ -0,0 +1 @@
+dad4b931f0b71316a0e09fabc9b14adcebbd375f6021ca5be52187963a81bb5a

package/dist/commands/advise.d.ts

@@ -1,7 +1,19 @@
 /** Stamped into `advised_by` and `advice.json`. Bump when advise.md changes meaningfully. */
-export declare const ADVISOR_VERSION = "1.5.0";
+export declare const ADVISOR_VERSION = "1.6.0";
 /** The installed `iamu/.prompts/advise.md`, or the bundled template. */
 export declare function readAdvisePrompt(projectRoot: string): string;
+/** Over this many characters, `iamu advise` warns that a host may cut the prompt. */
+export declare const ADVISE_PROMPT_WARN_CHARS = 40000;
+/**
+ * The closing "Output JSON schema (strict)" section for a bundle's mode.
+ * It ends the prompt so a host that cuts a long prompt in the middle
+ * never hides the answer's shape. A project synthesis asks only for
+ * directions, observations and design proposals.
+ *
+ * @example
+ * answerSchemaFooter("project"); // "## Output JSON schema (strict)\n\n…"
+ */
+export declare function answerSchemaFooter(mode: "run" | "project"): string;
 export interface AdviseOptions {
     run?: string;
     project?: boolean;

package/dist/commands/browse-driver.d.ts

@@ -46,7 +46,21 @@ export interface BrowserDriver {
     kill(pid: number, signal?: NodeJS.Signals | number): void;
     /** Is `pid` still alive in the OS process table? */
     alive?(pid: number): boolean;
+    /** A free port for a new browser's CDP; defaults to asking the OS. */
+    freePort?(): Promise<number>;
 }
+/**
+ * `promise`, or a rejection naming `what` once `ms` pass — for page calls
+ * Playwright gives no timeout of their own (`evaluate`, `title`).
+ *
+ * @example
+ * ```ts
+ * const title = await bounded(page.title(), 15_000, "The page title");
+ * ```
+ *
+ * @public
+ */
+export declare function bounded<T>(promise: Promise<T>, ms: number, what: string): Promise<T>;
 /** How long a CDP liveness probe may take before the port counts as dead. */
 export declare const CDP_PROBE_TIMEOUT_MS = 1000;
 /**

package/dist/commands/browse.d.ts

@@ -37,20 +37,51 @@ interface BrowseState {
     pid?: number;
     headless?: boolean;
     activeTabIndex?: number;
+    /** The run this browser belongs to; absent when started without one. */
+    run?: string;
+    /** That run's project root, to tell whether it is still being walked. */
+    project?: string;
 }
 /**
- * The state `iamu browse start` left in `~/.iamu/browse/state.json`, or
- * null when no browser was started (or the file is unreadable).
+ * The state `iamu browse start` left for this run
+ * (`~/.iamu/browse/<run-id>.json`), else the one a browser started
+ * without a run left (`state.json`), or null when there is none.
+ *
+ * @param run - Run id; omitted, only the shared state is read.
  *
  * @example
  * ```ts
- * const state = readBrowseState();
+ * const state = readBrowseState(runId);
  * if (state) console.log(`CDP on :${state.port}`);
  * ```
  *
  * @public
  */
-export declare function readBrowseState(): BrowseState | null;
+export declare function readBrowseState(run?: string | null): BrowseState | null;
+/**
+ * Every browse state on this machine, one per browser `start` recorded
+ * (per run, plus the shared one).
+ *
+ * @example
+ * ```ts
+ * for (const s of listBrowseStates()) console.log(s.run ?? "-", s.port);
+ * ```
+ *
+ * @public
+ */
+export declare function listBrowseStates(): BrowseState[];
+/**
+ * A port nothing listens on right now: the one the OS hands out for
+ * port 0.
+ *
+ * @example
+ * ```ts
+ * const port = await pickFreePort();
+ * ```
+ *
+ * @public
+ */
+export declare function pickFreePort(): Promise<number>;
 /**
  * Parse `"390x844"` into a size.
  *
@@ -169,8 +200,21 @@ export declare function computePageFingerprint(url: string, bodySnippet: string)
 /**
  * Track page state across consecutive steps in a run.
  * Emits a warning when 3 consecutive steps produce zero observable URL/DOM transition.
+ * The count lives in the run directory (`.stagnation.json`), so it goes
+ * with the run.
+ *
+ * @param runDirPath - The run's directory (`iamu/.runs/<id>`).
+ * @param fingerprint - {@link computePageFingerprint} of the page now.
+ * @param action - The step's action, for the warning.
+ *
+ * @example
+ * ```ts
+ * const { warning } = checkAndRecordStagnation(runDirPath, fp, "Click Pay");
+ * ```
+ *
+ * @public
  */
-export declare function checkAndRecordStagnation(projectRoot: string, runId: string, fingerprint: string, action: string): {
+export declare function checkAndRecordStagnation(runDirPath: string, fingerprint: string, action: string): {
     count: number;
     warning?: string;
 };
@@ -199,6 +243,11 @@ export declare function detectAntiBotChallenge(page: Page, allowEvaluate?: boole
  * nothing on success — the caller decides the output shape. Detaching
  * never closes the page.
  *
+ * The whole command races a deadline (`IAMU_BROWSE_DEADLINE_MS`, default
+ * 45 s): a page that never answers fails the command with a clear
+ * message instead of hanging the walker, and the browser is still
+ * detached.
+ *
  * @public
  */
 export declare function withPage(opts: BrowseOptions, driver: BrowserDriver, fn: (page: Page) => Promise<void>, 
@@ -213,6 +262,19 @@ onPostShot?: (page: Page) => Promise<void>): Promise<PageResult | null>;
  * @public
  */
 export declare function resilientAriaSnapshot(page: Page): Promise<string>;
+/**
+ * A warning for a step that ended on another origin than the run's
+ * target, or undefined. It is recorded as the step's `origin_warning`,
+ * never in its note: a sign-in or payment page on purpose is fine, but a
+ * tab another app took over is not the product under test. Both URLs
+ * must be http(s); `about:blank` and relative URLs never warn.
+ *
+ * @example
+ * stepOriginWarning("http://localhost:3001/settings", "http://localhost:3000/");
+ * // "The step ended on http://localhost:3001, not the run's target http://localhost:3000. …"
+ * stepOriginWarning("http://localhost:3000/a", "http://localhost:3000/"); // undefined
+ */
+export declare function stepOriginWarning(pageUrl: string | null | undefined, targetUrl: string | null | undefined): string | undefined;
 /** What {@link clearOriginStorage} removed. */
 export interface ClearedStorage {
     origin: string;
@@ -226,7 +288,9 @@ export interface ClearedStorage {
  */
 export declare function clearOriginStorage(origin: string, driver?: BrowserDriver, 
 /** Page to open after clearing (the run's start URL); else about:blank. */
-returnTo?: string): Promise<ClearedStorage | {
+returnTo?: string, 
+/** The run whose browser to clear; else the shared one. */
+run?: string | null): Promise<ClearedStorage | {
     error: string;
 }>;
 /**

package/dist/commands/complete.d.ts

@@ -111,7 +111,42 @@ type AssembledRunFiles = {
  * `match-record`) does not drop them. It holds the run's record lock so
  * stages that re-derive them in parallel never interleave.
  */
-export declare function assembleRun(projectRoot: string, runId: string, manifest: WalkthroughManifest, completedAt: string): Promise<AssembledRunFiles>;
+export declare function assembleRun(projectRoot: string, runId: string, manifest: WalkthroughManifest, completedAt: string, opts?: AssembleRunOptions): Promise<AssembledRunFiles>;
+/** How an assembly may touch files outside the run directory. */
+export interface AssembleRunOptions {
+    /**
+     * Write `fix_status` on earlier findings from this run's verification
+     * delta. Only `complete` (first completion) and `match-record` pass
+     * true; every other re-derivation reports without writing. Default false.
+     */
+    writeFixStatus?: boolean;
+}
+/**
+ * Re-derive a completed run's canonical.json and report.md from the
+ * manifest as it is on disk now. For a caller that already holds the
+ * run's record lock; otherwise use {@link rederiveRunLocked}.
+ *
+ * @throws Error when the run has no readable `walkthrough.json`.
+ */
+export declare function rederiveRunUnlocked(projectRoot: string, runId: string, opts?: AssembleRunOptions): Promise<AssembledRunFiles>;
+/**
+ * Re-derive a completed run's canonical.json and report.md under the
+ * run's record lock, reading the manifest inside the lock. For stages
+ * that changed something the report shows (triage, designer-dismiss).
+ * Never writes `fix_status` unless `opts.writeFixStatus` is set.
+ *
+ * @param projectRoot - Absolute path to the project root.
+ * @param runId - The completed run to re-derive.
+ * @param opts - `writeFixStatus` (default false).
+ * @returns The written files and the verification delta.
+ * @throws Error when the run has no readable `walkthrough.json`.
+ *
+ * @example
+ * ```ts
+ * await rederiveRunLocked(projectRoot, runId);
+ * ```
+ */
+export declare function rederiveRunLocked(projectRoot: string, runId: string, opts?: AssembleRunOptions): Promise<AssembledRunFiles>;
 /**
  * {@link assembleRun} for a caller that already holds the run's record
  * lock (`withRunLock` is not re-entrant). The record stages take the lock
@@ -119,7 +154,7 @@ export declare function assembleRun(projectRoot: string, runId: string, manifest
  * stage never reads half-written findings or overwrites the report with
  * an older canonical.
  */
-export declare function assembleRunUnlocked(projectRoot: string, runId: string, manifest: WalkthroughManifest, completedAt: string): Promise<AssembledRunFiles>;
+export declare function assembleRunUnlocked(projectRoot: string, runId: string, manifest: WalkthroughManifest, completedAt: string, opts?: AssembleRunOptions): Promise<AssembledRunFiles>;
 /** One requested place, whether the run reached it, and what awaits there. */
 export type RevisitReportPlace = RevisitPlaceCoverage & {
     findings: Array<{

package/dist/commands/context.d.ts

@@ -23,6 +23,22 @@ export declare function commandError(message: string, opts?: CommandDiagnosticOp
 export declare function resolveRunDir(projectRoot: string, runId: string, opts?: {
     json?: boolean;
 }): string | null;
+/**
+ * Resolve the directory of a run that exists — one `iamu start-run`
+ * created, so it holds `walkthrough.json`. Writers into a run (summary,
+ * step) use this so a mistyped or never-started run id fails with
+ * `run_not_found` instead of creating a phantom run directory. Returns
+ * `null` once the error has been reported.
+ *
+ * @example
+ * ```ts
+ * const dir = requireRun(projectRoot, runId, opts);
+ * if (!dir) return;
+ * ```
+ */
+export declare function requireRun(projectRoot: string, runId: string, opts?: {
+    json?: boolean;
+}): string | null;
 /**
  * Resolves the active scenario slug following the OpenSpec single-entity resolution pattern:
  * 1. Explicit slug argument if provided

package/dist/commands/doctor.d.ts

@@ -32,6 +32,8 @@ export declare function checkProjectTestabilityContract(projectRoot: string): Pr
 }>;
 export declare function runDoctorChecks(projectRoot?: string, opts?: {
     target?: string;
+    /** The cloud reachability probe's fetch (tests pass a fake). */
+    fetch?: typeof fetch;
 }): Promise<DoctorResult>;
 export declare function doctor(opts?: {
     json?: boolean;

package/dist/commands/explore-crawl.d.ts

@@ -14,11 +14,14 @@
  *   save, log out …), form submits, downloads and other origins are
  *   never clicked. Nothing is typed into a field.
  * - Every request that is not GET/HEAD/OPTIONS is aborted before it
- *   leaves the browser, and recorded on the action that caused it.
+ *   leaves the browser, and recorded on the action that caused it. So is
+ *   a page load or fetch whose path or query reads like a write
+ *   (`/logout`, `?action=delete`), however a script started it.
  *
  * Dialogs are dismissed (`confirm()` answers no) and popups closed.
  * WebSocket messages are not guarded; a page controlled by a service
- * worker (whose requests the guard cannot see) is refused.
+ * worker (whose requests the guard cannot see) is refused, and a crawl
+ * stops (`stats.stopped: "service_worker"`) once one takes control.
  */
 import { type ExploreBudget, type ExploreStats, type ExploreSurface } from "@iamu-dev/local-store";
 import type { Page } from "playwright-core";

package/dist/commands/init.d.ts

@@ -20,8 +20,14 @@ export declare function devServerHint(projectRoot: string, devCommandRecorded?:
  */
 export declare function detectTargetPort(projectRoot: string): number | undefined;
 export declare function detectTargetUrl(projectRoot: string): string;
-/** The target line of the init summary, by testability status. */
-export declare function describeTargetStatus(status: TestabilityStatus): string;
+/**
+ * The target line of the init summary, by testability status. A draft
+ * target is "detected" only when the project named it; otherwise it is
+ * the default.
+ */
+export declare function describeTargetStatus(status: TestabilityStatus, opts?: {
+    fallback?: boolean;
+}): string;
 export declare function createDraftTestabilityContent(targetUrl?: string, status?: TestabilityStatus): string;
 export interface InitOptions {
     name?: string;

package/dist/commands/instructions.d.ts

@@ -1,21 +1,6 @@
-export interface InstructionsOptions {
-    phase?: string;
-    scenario?: string;
-    run?: string;
-    surface?: string;
-    json?: boolean;
-}
 /**
  * Generates dynamic staging instructions for an active or specified scenario.
  */
 export declare function instructionsStage(slug?: string, opts?: {
     json?: boolean;
 }): Promise<void>;
-/**
- * Phases `iamu instructions [phase]` serves (`run` is an alias of `walk`).
- */
-export declare const INSTRUCTION_PHASES: string[];
-/**
- * Top-level dispatcher for `iamu instructions [phase] [slug]`.
- */
-export declare function instructions(phase?: string, slug?: string, opts?: InstructionsOptions): Promise<void>;

package/dist/commands/match.d.ts

@@ -1,4 +1,10 @@
 import { type WalkthroughManifest } from "@iamu-dev/local-store";
+/**
+ * Where the matcher's raw answer goes in the run directory, parallel to
+ * `judge_answer.json`. `matches.json` is the validated record that only
+ * `match-record` writes.
+ */
+export declare const MATCH_ANSWER_FILE = "match_answer.json";
 /** A completed run's manifest, or null after reporting why not. */
 export declare function completedManifest(runDirPath: string, runId: string, opts?: {
     json?: boolean;

package/dist/commands/mcp-config.d.ts

@@ -1,10 +1,88 @@
+import type { HostAdapter } from "../adapters/types.js";
+/** What {@link writeSyncMcpEntry} changed besides the `iamu-sync` entry. */
+export interface SyncMcpWriteResult {
+    /**
+     * True when the file held the old `iamu` entry (`iamu mcp-server`, a
+     * command that no longer exists) and it was removed.
+     */
+    removedLegacy: boolean;
+}
 /**
- * Write or update the `iamu-sync` entry in an MCP config file.
- * Merges with existing content — does not clobber other servers.
- * Throws if existing file contains invalid JSON (avoids silent data loss).
+ * Remove the legacy `iamu` (`mcp-server`) entry from an existing MCP
+ * file, for every project, cloud-linked or not: before 0.8, `iamu init`
+ * wrote it everywhere. Writes only when the entry was there; a missing
+ * or malformed file is left alone (`false`).
+ *
+ * @returns Whether the entry was there and is now gone.
+ *
+ * @example
+ * ```ts
+ * if (await removeLegacyIamuEntry(".mcp.json")) console.log("removed");
+ * ```
  */
-export declare function writeSyncMcpEntry(mcpPath: string): Promise<void>;
+export declare function removeLegacyIamuEntry(mcpPath: string): Promise<boolean>;
 /**
- * Check if an MCP config file has an `iamu-sync` entry.
+ * Write or update the `iamu-sync` entry in an MCP config file, and drop
+ * the legacy `iamu` (`mcp-server`) entry if it is there. Merges with
+ * existing content — does not clobber other servers.
+ *
+ * @param mcpPath - The host's project MCP file; `null` for a host that
+ *   has none (see `HostAdapter.manualMcpSetup`), which throws.
+ * @throws When the file holds invalid JSON (avoids silent data loss), or
+ *   when `mcpPath` is null.
+ *
+ * @example
+ * ```ts
+ * const { removedLegacy } = await writeSyncMcpEntry(".mcp.json");
+ * ```
  */
-export declare function hasSyncMcpEntry(parsed: Record<string, unknown>, mcpPath: string): boolean;
+export declare function writeSyncMcpEntry(mcpPath: string | null): Promise<SyncMcpWriteResult>;
+/** The outcome of registering `iamu-sync` for one host. */
+export type SyncMcpRegistration = {
+    status: "written";
+    path: string;
+    removedLegacy: boolean;
+} | {
+    status: "legacy_removed";
+    path: string;
+    removedLegacy: true;
+} | {
+    status: "manual";
+    instruction: string;
+} | {
+    status: "failed";
+    path: string;
+    message: string;
+};
+/**
+ * Register `iamu-sync` for `host` without ever throwing: a host with no
+ * project MCP file yields its by-hand instruction, a malformed file a
+ * failure to report. Used by `iamu init` and `iamu update`.
+ *
+ * @example
+ * ```ts
+ * const r = await registerSyncMcpForHost(host, projectRoot);
+ * printSyncMcpRegistration(host, r, "registered");
+ * ```
+ */
+export declare function registerSyncMcpForHost(host: HostAdapter, projectRoot: string): Promise<SyncMcpRegistration>;
+/**
+ * For a project that registers no `iamu-sync` (not cloud-linked): drop
+ * the legacy `iamu` entry from `host`'s MCP file if it has one. Never
+ * throws; `null` when there was nothing to remove.
+ *
+ * @example
+ * ```ts
+ * const r = await removeLegacyMcpForHost(host, projectRoot);
+ * if (r) printSyncMcpRegistration(host, r, "refreshed");
+ * ```
+ */
+export declare function removeLegacyMcpForHost(host: HostAdapter, projectRoot: string): Promise<SyncMcpRegistration | null>;
+/**
+ * Print one host's registration outcome: a success line (plus a note
+ * when the legacy entry went), the by-hand instruction, or a warning on
+ * stderr. Never sets an exit code — the rest of the setup stands.
+ *
+ * @param verb - "registered" (init) or "refreshed" (update).
+ */
+export declare function printSyncMcpRegistration(host: HostAdapter, result: SyncMcpRegistration, verb: "registered" | "refreshed"): void;

package/dist/commands/new-entity.d.ts

@@ -3,6 +3,8 @@ export interface NewEntityOptions {
     slug?: string;
     description?: string;
     body?: string;
+    /** Read the body from this file (`-` for stdin). */
+    bodyFile?: string;
     narrative?: string;
     access?: string;
     role?: string;
@@ -31,6 +33,32 @@ export interface NewEntityOptions {
     stateApproximation?: string;
     json?: boolean;
 }
+/** The body flags `iamu new` and `iamu set` share. */
+export interface BodyInputOptions {
+    body?: string;
+    bodyFile?: string;
+    json?: boolean;
+}
+/**
+ * The body a command should write, from `--body <text>` or
+ * `--body-file <path>` (`-` reads stdin; a relative path is resolved
+ * against the working directory). A `--body` holding a literal `\n` is
+ * refused: the shell passed a backslash and an `n`, which would be stored
+ * as-is instead of a line break. Errors are reported as command errors.
+ *
+ * @param flag - The flag name the text came from (`--narrative` for the alias).
+ * @returns `{ body }` (undefined when neither flag was given), or `null`
+ *   once an error has been reported.
+ *
+ * @example
+ * ```ts
+ * const input = await resolveBodyInput(opts, "iamu new persona");
+ * if (!input) return;
+ * ```
+ */
+export declare function resolveBodyInput(opts: BodyInputOptions, command: string, flag?: string): Promise<{
+    body: string | undefined;
+} | null>;
 /** Entity types `iamu new <type>` creates (findings: `iamu new-finding`). */
 export declare const SUPPORTED_TYPES: readonly ["persona", "outline", "capability", "source", "scenario"];
 export declare function newEntity(type: string, opts: NewEntityOptions): Promise<void>;

package/dist/commands/post-walk.d.ts

@@ -10,9 +10,12 @@ export interface PostWalkOptions {
  *
  * 1. Completes the run locally (`iamu complete --no-prompt --no-push`) if still `in-progress`.
  * 2. Records any subagent answer files already present in `<run-dir>/`
- *    (`matches.json`, `judge_answer.json` / `verdicts.json`, `advise_answer.json`,
- *    `designer_answer.json`) in canonical lock-safe order.
- * 3. Generates all remaining post-walk subagent prompts (`match_prompt.md`,
- *    `judge_prompt.md`, `advise_prompt.md`, `designer_prompt.md`) in one hop.
+ *    (`match_answer.json`, `judge_answer.json`, `advise_answer.json`,
+ *    `designer_answer.json`) in canonical lock-safe order. `matches.json`
+ *    is match-record's validated record, never an answer file.
+ * 3. Generates the remaining post-walk subagent prompts (`match_prompt.md`,
+ *    `judge_prompt.md`, `designer_prompt.md`). `advise_prompt.md` waits
+ *    for `verdicts.json`: the advisor reads the judge's verdicts, so a
+ *    second `post-walk` after `evaluate-record` builds it.
  */
 export declare function postWalk(runIdArg?: string, opts?: PostWalkOptions): Promise<void>;

package/dist/commands/pull.d.ts

@@ -2,4 +2,5 @@ export declare function pull(refs?: string[], opts?: {
     force?: boolean;
     preview?: boolean;
     json?: boolean;
+    all?: boolean;
 }): Promise<void>;

package/dist/commands/set-entity.d.ts

@@ -71,6 +71,8 @@ export interface SetEntityOptions {
     glossary?: ContextFrontmatter["glossary"] | false;
     /** Markdown body narrative. */
     body?: string;
+    /** Read the body from this file (`-` for stdin) instead of `--body`. */
+    bodyFile?: string;
     /** JSON patch file (or - for stdin) containing staging fields. */
     file?: string;
     json?: boolean;

package/dist/commands/skills.d.ts

@@ -17,11 +17,18 @@ export declare function resolveTargetHosts(projectRoot: string, hostFilter?: str
     error?: string;
 };
 /**
- * Installed skill/command files that differ from what `iamu update` would
- * write for this CLI version. Local reads only — no network.
+ * Installed skill files that differ from what `iamu update` would write
+ * for this CLI version, for every host `iamu update` would touch: a
+ * detected host with no iamu skills yet counts (its skills are missing),
+ * unless the Iamu plugin supplies them. Local reads only — no network.
  *
- * @returns Absolute paths of the stale files; empty when up to date or
- *   when no host has iamu skills installed.
+ * @returns Absolute paths of the stale (or missing) files; empty when up
+ *   to date or when no agent host is detected.
+ *
+ * @example
+ * ```ts
+ * if ((await findStaleSkills(root)).length > 0) console.log(STALE_SKILLS_MESSAGE);
+ * ```
  */
 export declare function findStaleSkills(projectRoot: string): Promise<string[]>;
 /** The one-line nudge `iamu status` and `iamu sync` print. */
@@ -31,4 +38,6 @@ export declare function installSkillsForHosts(hosts: HostAdapter[], projectRoot:
 }): Promise<{
     totalSkills: number;
     totalCommands: number;
+    /** Project-relative paths of skills kept because they differ (see above). */
+    keptSkills: string[];
 }>;

package/dist/commands/step-numbering.d.ts

@@ -1,5 +1,6 @@
 /**
- * A step number claimed on disk. The file at `stepPath` exists (empty)
+ * A step number claimed on disk. The file at `stepPath` exists (holding
+ * a `{ reservation: { pid, ts } }` marker that step readers skip)
  * until the caller overwrites it with the step, or calls `release()`.
  *
  * @public

package/dist/commands/step.d.ts

@@ -27,9 +27,16 @@ export interface RecordStepInput {
     shot?: string | null;
     /** When true, move `shot` into `screenshots/step-N.png` via rename instead of copying. */
     moveShot?: boolean;
+    /**
+     * A full-page frame of the same moment (`browse step`), moved into
+     * `screenshots/step-N.full.png`; skipped when the file is not there.
+     */
+    fullShot?: string | null;
     url?: string | null;
     surface?: string | null;
     grounding?: string | null;
+    /** The step ended on another origin than the run's target (`browse step`). */
+    originWarning?: string | null;
     timestamp?: string;
     maxSteps?: string | number;
     extra?: Record<string, unknown>;