wicked-garden 12.42.0 → 12.44.0

package/.claude-plugin/marketplace.json

@@ -1 +1 @@
-{"name": "wicked-garden", "owner": {"name": "Mike Parcewski"}, "plugins": [{"name": "wicked-garden", "source": "./", "description": "Your coding agent already plans and swarms \u2014 Wicked Garden is the curated toolkit for what it can't: proof-not-claims gates, code links grep can't see, deterministic refactor, cross-session memory, real multi-model second opinions. Don't fight the harness; fill its gaps. The gate needs wicked-vault (a self-contained infra peer, installed directly) and re-derives through garden's built-in engine; estate/bus are opt-in layers (wicked-testing and wicked-brain are retired \u2014 QE ships in-catalog as the qe domain, memory lives in wicked-estate).", "version": "12.42.0"}], "version": "12.42.0"}
+{"name": "wicked-garden", "owner": {"name": "Mike Parcewski"}, "plugins": [{"name": "wicked-garden", "source": "./", "description": "Your coding agent already plans and swarms \u2014 Wicked Garden is the curated toolkit for what it can't: proof-not-claims gates, code links grep can't see, deterministic refactor, cross-session memory, real multi-model second opinions. Don't fight the harness; fill its gaps. The gate needs wicked-vault (a self-contained infra peer, installed directly) and re-derives through garden's built-in engine; estate/bus are opt-in layers (wicked-testing and wicked-brain are retired \u2014 QE ships in-catalog as the qe domain, memory lives in wicked-estate).", "version": "12.44.0"}], "version": "12.44.0"}

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-garden",
-  "version": "12.42.0",
+  "version": "12.44.0",
   "description": "Your coding agent's harness already plans and swarms; Wicked Garden is the curated toolkit for what it can't do alone. Proof, not claims \u2014 gates re-derive 'done' through the internal loom engine (fail-closed, independently attested via wicked-vault), so a self-asserted pass can't lie its way green. Relationships grep can't see \u2014 the wicked-estate code graph + injected bus/dispatch/capability/archetype edges power blast-radius & lineage. Plus deterministic multi-file refactor (wicked-patch), cross-session memory + knowledge (the mem domain over wicked-estate), real multi-model second opinions (jam:council), portable expertise as on-demand skill-refs, and evidence-gated testing (the in-catalog qe domain). It reads the shape of your work to apply the right rigor \u2014 steering, not a pipeline \u2014 then gets out of the way. The compiler stamps a self-contained evidence gate into any repo that runs with no wicked-garden installed. Don't fight the harness; fill its gaps. The evidence gate requires wicked-vault, a self-contained infra peer wicked-garden installs directly; wicked-bus is an opt-in layer \u2014 install what you'll use, the toolkit works without the rest.",
   "wicked_vault_version": "^0.5.0",
   "wicked_ledger_version": "^0.4.0",

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## [Unreleased]
 
+## [12.44.0] — 2026-10-08
+
+### Added
+- **`mcp-scaffold`: the `openapi` and `install` actions (DES-mcp-server-workflow rev 2, slice 2 of 2).** `scripts/mcp/openapi.py` turns an OpenAPI 3 document into the server's `tools.json` through wicked-crew's conversion service — `POST /api/v1/mcp/servers/preview` with `{name, kind: "rest", url, openapiUrl | openapi, operations?}` at `--crew-url`, else `$WICKED_CREW_URL`, else `http://127.0.0.1:7701` — writing `{"source": {specUrl|specFile, baseUrl, convertedAt}, "tools": [{name, description, inputSchema, annotations, class, rest}], "skipped": [...]}` and setting `baseUrl` in `mcp-server.config.json`; it refuses to overwrite generated tools, never sends a `secret`/`auth` key, exits 1 carrying the daemon's refusal and exits 2 when no daemon answers ("write the tools by hand (branch B)") — it never invents tools. `scripts/mcp/install.py` installs or updates the built server for running, idempotent by the config's `key`: it locates the one `mcp-server.config.json` (`--from-run` under `$WICKED_TREE`, or `--dir`), builds and stages `dist/` + manifests into `<root>/<key>/next/` (`~/.wicked/mcp-servers` unless `--install-root`/`$WICKED_MCP_INSTALL_ROOT`; `--from-npm <pkg>@<ver>` installs a published package instead), smokes it with `probe.py --env <SERVER>_TOKEN` (a failure naming that variable is `pending_credential`, disclosed; any other failure exits 1 with `current/` untouched), swaps `current/` → `previous/` and `next/` → `current/` so the command `node <root>/<key>/current/dist/server.js` never changes, registers it in crew's MCP registry with `auth: {ref: "env:<SERVER>_TOKEN"}` — the one-secret contract: a reference the daemon resolves, never a value (`secret_missing` → `registered: false` with both remedies; no daemon → the reason; an existing key → `registered: "updated"`), writes the operator's CLI MCP configs only through `wicked-installer mcp upsert` (an installer without the verb is reported as skipped), and records `<root>/<key>/installed.json` `{key, version, source, command, args, envNames, installedAt, registered, smoke}`. `--uninstall <key>` deletes the registration, the CLI entries and the root. Exit 0 staged, 1 staging/smoke/registry failure, 2 bad arguments. The skill gains both actions, the `mcp-server` workflow's per-phase guide (scope, source-discovery, design, build, install) and the "Use when" phrases; the core router row is now `scaffold · openapi · probe · install`. Tests: `tests/mcp/test_mcp_openapi.py`, `tests/mcp/test_mcp_install.py` (stub `npm` and `wicked-installer` on PATH, a local http.server as the daemon, a real smoke probe).
+- **`mcp-scaffold`: a TypeScript server template, now the default (`scaffold.py --lang typescript`; DES-mcp-server-workflow rev 2, slice 1 of 2).** `skills/mcp-scaffold/assets/typescript/` is a whole project: fastmcp 4 on Node >= 22, loglayer (OpenTelemetry plugin, redaction by name, a console transport bound to stderr — stdout carries protocol frames only — and a request-scoped child logger through `AsyncLocalStorage`), OpenTelemetry through `@opentelemetry/sdk-node` (spans `mcp.tool.call` and `http.client.request`, instruments `mcp.tool.calls`/`mcp.tool.duration`/`mcp.tool.errors`; the OTLP trace, metric and log exporters are armed only when `OTEL_EXPORTER_OTLP_ENDPOINT` is set, otherwise nothing leaves the process), and authentication on every tool (`canAccess`; httpStream refuses a request without `MCP_SERVER_BEARER` with 401). The server reads ONE secret, `<SERVER>_TOKEN` (bearer token, API key, basic password or OAuth2 client secret, as the scheme says) — the one variable crew's broker and registry inject — and fails at startup naming it; every non-secret parameter lives in the committed `mcp-server.config.json` (`key`, `version`, `transport`, `baseUrl`, `auth`, `rateLimitPerMin`). `defineTool` wraps each tool in the span, the child logger, the instruments and a per-tool token bucket; `src/tools/generated.ts` registers every `tools.json` entry (the conversion service's output) with annotations derived from its class, calling `src/rest.ts`, which pins scheme/host/port/base path, sends allowlisted arguments only, never follows a redirect, refuses auth and hop-by-hop headers from arguments and retries 429/5xx for read tools only. `npm test` builds and runs a stdio conformance smoke (initialize, tools/list, tools/call; a missing secret exits non-zero naming the variable; httpStream 401) and a per-tool contract-test shape. Every `.ts` file starts with an SPDX line. `scaffold.py` copies the directory stamping the name, its env prefix and the year; `--out` may be an existing directory, but every file it would write must be absent — it refuses naming the first collision and writes nothing. `node` and `python` stay as the dependency-free one-file templates. `probe.py --env NAME` passes exactly that variable through to the server (never printed) and, on a failure, reports only which of those names the server's stderr mentioned (`stderrNames`). The skill gains the skeleton's contract and a "Steering this server follows" checklist (MCPS-1001…1007, sourced from wicked-core's `governance/packs/mcp-server`). Tests: `tests/mcp/test_mcp_scaffold.py` (default lang, stamping, SPDX, no secret values, scaffold into a populated dir, collision refusal, `--env` passthrough; the npm install/build/lint/test/probe end-to-end behind `WICKED_GARDEN_E2E_NPM=1`).
+
+### Changed
+- **Governed-worker floor: foreground evidence, tool debris under the notes root, verdict scope (wicked-garden#1229, #1223).** New **C6**: no turn ends with tasks pending — the done-when recipe runs in order in the foreground with each command and exit code pasted; "running in the background" is never a closing line (three creator attempts in run ad5a4ca7 ended that way, F35). New **C7**: reporter output, coverage, screenshots, logs and scratch files go under the unit's notes root (`$WICKED_NOTES_ROOT` or the path the brief names), never in the repository — pass the tool's output flag or delete the file before the turn ends (S17b left a 2.3 MB `.vitest/json/output.json` in the worktree; crew's deliver skip-list, wicked-crew#861, is the backstop). **C2** now reads: a failure called pre-existing cites its run on the base tree (command + exit code) or it is a failure. New **E3**: every verdict item is in scope unless a human ruling strikes it by name (companion to wicked-core#760). Provenance rows added; `tests/test_governed_worker_rules.py` pins the text.
+
+### Fixed
+- **Walkthrough: the `lint` action the `walkthrough_plan` pin calls now exists, and `record` reads the storyline the author wrote (wicked-garden#1231, the garden half of wicked-core#753).** The engine pins `walkthrough_plan` to `"${WICKED_GARDEN_ROOT}/scripts/wicked-garden" run scripts/demo/walkthrough.mjs lint --root "${WICKED_EVIDENCE_ROOT}"`, but `walkthrough.mjs` accepted only `record|seal` and exited 2 with usage — so every walkthrough was denied, storyline or not. `lint --root <author dir>` (new `scripts/demo/walkthrough-lint.mjs`, DES-walkthrough-proof §4.5) imports `<author dir>/storyline.mjs`, prints `{ok, storyline, chapters, checks, findings: [{rule, where, detail}]}` and exits 0 only with no finding (1 with any, 2 on a usage error; `--root` defaults to `$WICKED_EVIDENCE_ROOT`). It refuses: a missing or unloadable storyline; an empty plan; `baseUrl` other than `"fixture"`; a `fixture.start` that is not a plain argv, runs inline code (`-e`, `-c`, `--eval`, ...), names an absolute path or `..`, or (with `--tree <dir>`) a script the tree does not hold; a secret-shaped `fixture.env` name; a chapter without `proves` step ids (with `--steps a,b`, ids outside the plan), without a `locator` (on_screen) check, without a `probe`/`artifact` (state) check, or without a `join` (cross_check) of the two; a walkthrough without a `guard` (must_not_happen) check; unknown check kinds, a locator without a selector, a probe not in `fixture.probes`, an artifact path escaping `DATA_DIR`, a join not naming two earlier checks; a `verify` that is not `jq_pred` or that `jq` rejects; and a check with no `negative` sample or whose verifier PASSES one of its samples (a tautology; run through `jq -e` exactly as the vault does, failing closed without `jq`). `record` took its storyline from `<dirname(WICKED_EVIDENCE_ROOT)>/author/<WICKED_RUN_UNIT>/` — the unit **ordinal** — so a storyline written where the engine said was reported "storyline not found"; it now reads `--storyline`, else `$WICKED_WALKTHROUGH_AUTHOR/storyline.mjs` (the author dir wicked-core's `record_launch` hands it), and with neither refuses `storyline_refused` naming both. The demo skill gains a walkthrough-author section and `refs/walkthrough-author.md` (where the file goes, every rule id, a passing example the tests lint). Tests: `tests/demo/test_walkthrough_lint.py` (27: a clean pass, the exact pinned launcher command, one per rule, the documented example, a storyline that throws while read still gets a report), `tests/demo/test_walkthrough.py` (4: the author dir is read with an ordinal `WICKED_RUN_UNIT`, a missing author storyline names its path, no source refuses by name, the unjailed result lists the author storyline's chapters). The record tool does not yet re-run the lint before recording (§4.4 step 1); that follows separately.
+- **`mcp-scaffold` TypeScript template: the conformance smoke no longer times out on a loaded host.** Loading fastmcp and the OpenTelemetry SDK can take well over 10 s when the machine is busy; the stdio exchange now waits up to 60 s, the httpStream readiness poll up to 60 s, `testTimeout` is 90 s, and the npm end-to-end test (`WICKED_GARDEN_E2E_NPM=1`) probes with `--timeout 30`.
+- **CI no longer installs the retired `wicked-loom` package; the trust-spine tests need only node + wicked-vault (closes the wicked-garden#1132 residual).** Loom runs in-process (`scripts/loom/`, absorbed from wicked-loom), but `.github/workflows/test.yml` still ran `npm i -g wicked-vault wicked-loom` and `tests/qe/test_prove.py` / `tests/e2e/test_e2e_gate_cli.py` skipped (or, under `WICKED_REQUIRE_E2E=1`, failed) unless a `wicked-loom` binary was on PATH — and then pinned `WICKED_LOOM_BIN` to it, so CI exercised the deprecated external binary instead of the in-process gate garden ships. The tests now require node + a resolvable vault only, pass `WICKED_LOOM_BIN` through only when the caller set it, and CI installs `wicked-vault` alone. `docs/cross-cli-skill-format.md` no longer describes the deleted cross-CLI baseline or its `--write-baseline` flag, and the repo's agent guide (`.claude/CLAUDE.md`) no longer calls wicked-loom a required peer. Proof: `WICKED_REQUIRE_E2E=1 python3 -m pytest tests/qe/test_prove.py tests/e2e/test_e2e_gate_cli.py` → 17 passed with only `wicked-vault` on PATH.
+
+## [12.43.0] — 2026-10-05
+
+### Fixed
+- **Walkthrough tool: the proof root is what crew's walkthrough view and acceptance read (wicked-garden#1208).** `scripts/demo/walkthrough.mjs record` wrote only `{key, verdict, failed_at_sec}` per chapter, `progress.json` only at the end, its segments under `<root>/segments/`, no planned chapter list and no stitched take — so crew's view (`GET /runs/:id/walkthrough`, WT-W1) showed "Starting the app" for the whole recording, then a failed chapter by its key with no title, no check, no frame and nothing to watch. The tool now writes crew's contract: `chapters.json` (`{key, title, blurb, tags, resets}`) before the app starts; `progress.json` `{state: "starting_app"}` → `{state: "recording", chapter, index, total}` per chapter → `{state: "judging"}`; `result.json` with a top-level `tree` and per chapter `title`, `takes`, `failed_at_sec` (the earliest failing check's `at_sec`, else the take's `failure.json` — DES §4.5), `failed_frame` (the earliest failing on-screen check's frame, else one cut from the take at `failed_at_sec`), `proves`, `legs` and `checks[] {id, kind, sentence, passed, at_sec, evidence[] (root-relative paths), vault_entry, detail}`; the segments under `demo-video/segments/<key>/`, and the take stitched from each chapter's kept video (the good take, else the failed take the recorder kept) into `demo-video/demo.mp4` with `demo-video/chapters.md` markers and `demo-video/poster.jpg`. **The seal is now the form crew recomputes** (`walkthrough-acceptance.ts`, WT-W2): sha256 over `"<sha256 hex>  <posix relative path>\n"` lines in UTF-8 byte order — the tool hashed `"<path>:<sha>\n"` in locale order, so every live take would have been denied as "walkthrough evidence changed after it was sealed". Like crew, the seal refuses a root holding a link or a non-regular entry outside `app/`/`data/`, or a file it cannot read: `record` then writes `INCONCLUSIVE` with `cause: unsealable_root` and prints the seal line with `bundle_sha: null` (crew reads it as not sealed and denies); `seal --root` exits 1 and says why. A chapter whose take failed has its kept video published at `demo-video/segments/<key>/segment.mp4` too (a copy; `guard.json` and `failed-<take>/failure.json` still say it failed), since that is the one path crew reads a chapter as recorded from. A segment key outside `^[a-z0-9][a-z0-9-]*$` (what `record.mjs` and crew accept) is refused as `storyline_refused`, naming the key, instead of being dropped by the view silently. `record.mjs` exports `stitchParts` (the one stitch, also used by its own `--stitch`) and `extractFrame`. Tests: `tests/demo/test_walkthrough.py` (the seal against a Python recompute of crew's form, `chapters.json`, the running progress read mid-take, the key rule, and a PASS+FAIL recording checked field by field).
+- **`_estate_client.py` keeps estate's diagnostics block (wicked-garden#1211).** The shim read `content[0]` of an MCP result only; estate's RetrievalTools put `STALENESS:` (and since estate#242 `CLAMPED:`, plus `LEXICAL-FALLBACK:`) in the second text block, so every skill going through the shim could not tell a stale or clamped answer from a fresh, complete one. `_unwrap_blocks(envelope)` returns `(payload, diagnostics_lines)`, `call_blocks(tool, arguments)` returns `{"result", "diagnostics"}`, and the CLI's `call` action — the command every skill names — prints `{"result": …, "diagnostics": [...]}` so the seat reading stdout sees the marker (additive: `result` is where it always was; a consumer that never reads `diagnostics` sees no change). `call`/`_unwrap` keep their one-value contract. The search skill and its hotspots ref say where the marker now appears. The governed read-verb allowlist the skill lint mirrors (`tests/test_skill_governed_grounding.py`) is unchanged: wicked-core's `ESTATE_READ_VERBS` still lacks `lineage`/`traverse`/`hotspots` (wicked-core#729 open), and garden must not coach a verb the fence denies.
+
+### Changed
+- **Domain vendor: the schema bundle `VERSION` follows the owner to 1.2.1.** wicked-core#699 bumped its governance schema bundle to 1.2.1 (conformance-rules 1.2.0 declares the DC-S1 project-rule fields it already documented). `skills/domain/vendor/VERSION` now matches, so `tests/domain/test_schema_vendor_pin.py` passes again against a current wicked-core checkout. `domain-model.schema.json` is byte-unchanged, and documents still carry `schema_version: "1.0.0"`.
+
 ## [12.42.0] — 2026-10-03
 
 ### Changed
@@ -971,7 +994,9 @@ through `v9.2.18`. Major themes across that span:
 
 For each of those releases, see the corresponding tag in git history.
 
-[Unreleased]: https://github.com/mikeparcewski/wicked-garden/compare/v12.42.0...HEAD
+[Unreleased]: https://github.com/mikeparcewski/wicked-garden/compare/v12.44.0...HEAD
+[12.44.0]: https://github.com/mikeparcewski/wicked-garden/compare/v12.43.0...v12.44.0
+[12.43.0]: https://github.com/mikeparcewski/wicked-garden/compare/v12.42.0...v12.43.0
 [12.42.0]: https://github.com/mikeparcewski/wicked-garden/compare/v12.41.0...v12.42.0
 [12.41.0]: https://github.com/mikeparcewski/wicked-garden/compare/v12.40.0...v12.41.0
 [12.40.0]: https://github.com/mikeparcewski/wicked-garden/compare/v12.39.0...v12.40.0

package/docs/cross-cli-skill-format.md

@@ -4,8 +4,8 @@ wicked-garden is installed into Claude Code, Codex, OpenCode, Pi and Antigravity
 parties and snapshotted by wicked-crew for every seat. Only Claude Code reads Claude Code's
 plugin frontmatter — so a skill's identity, dispatch shape and prose must not depend on it.
 This page is the format; `scripts/_skill_meta.py` is its one reader; the lint
-(`tests/test_skill_portability.py`) enforces it; `tests/cross_cli_baseline.json` lists what
-still has to be translated (12.37.x batches; the strict release deletes the baseline).
+(`tests/test_skill_portability.py`) enforces it, strictly: the 12.37.x translation batches are
+done and the baseline they burned down was deleted (B18), so every hit fails.
 
 ## Frontmatter: the closed key set
 
@@ -75,8 +75,8 @@ generically instead.
 
 ## Products and size
 
-`wicked-testing`, `wicked-brain`, `wicked-signals` are retired and `wicked-loom` is being replaced — the skill TEXT retires the `wicked-loom` reference ahead of the peer itself (`wicked-loom` stays the prove gate's CI peer in `test.yml` / `tests/qe/test_prove.py` until the prove/loom-cutover seam removes it; DES-L6 B6 / review F3) —
-by the in-process gate — name their successors (the `qe` domain, wicked-estate through the `mem` /
+`wicked-testing`, `wicked-brain`, `wicked-signals` are retired and `wicked-loom` was replaced (CI no longer installs it; DES-L6 B6 / review F3)
+by the in-process gate (`scripts/loom/`) — name their successors (the `qe` domain, wicked-estate through the `mem` /
 `search` skills, the built-in gate) or mark the line `<!-- historical -->` (`retired-product-ref`).
 A SKILL.md stays under 500 lines and 24 KiB (`skill-too-large`; `scripts/ci/validate.py` applies
 the same bound to routers and modules); detail goes in `refs/`. Skill-relative paths, the
@@ -84,9 +84,7 @@ the same bound to routers and modules); detail goes in `refs/`. Skill-relative p
 
 ## Tooling
 
-- `python3 tests/test_skill_portability.py` — the report (0 violations, 0 stale baseline entries).
-- `python3 tests/test_skill_portability.py --write-baseline` — regenerate the baseline **at B0
-  only**; afterwards the file only shrinks (a batch deletes the entries it translated; a stale entry
-  fails CI; B18 deletes the file).
+- `python3 tests/test_skill_portability.py` — the report (0 violations). There is no baseline: it
+  was deleted at B18 and `test_cross_cli_baseline_is_gone` fails if one comes back.
 - `python3 scripts/ci/validate.py && python3 scripts/_validate_registry.py` — the release gate,
   role-aware.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-garden",
-  "version": "12.42.0",
+  "version": "12.44.0",
   "type": "module",
   "description": "Curated toolkit for what AI coding agents can't do alone: evidence-gated work, codegraph relationships, deterministic multi-file refactor, multi-model second opinions, and cross-session memory. Installs as a Claude Code plugin.",
   "keywords": [

package/scripts/_estate_client.py

@@ -727,31 +727,51 @@ def _rpc(method: str, params: dict, *, timeout: float) -> Optional[dict]:
     return responses.get(2)
 
 
-def _unwrap(envelope: Optional[dict]) -> Optional[Any]:
-    """Extract a tool's payload from an MCP tools/call envelope.
-
-    Estate wraps results as {"result": {"content": [{"type":"text","text": …}],
-    "isError": bool}}. The text is usually the tool's own JSON string, which is
-    parsed and returned; a tool that emits plain (non-JSON) text gets its text
-    handed back verbatim as a str. Returns None on error / isError=true /
-    a malformed envelope shape.
+def _unwrap_blocks(envelope: Optional[dict]) -> "tuple[Optional[Any], list[str]]":
+    """Extract a tool's payload AND its diagnostics from an MCP tools/call envelope.
+
+    Estate wraps results as {"result": {"content": [{"type":"text","text": …}, …],
+    "isError": bool}}. `content[0]` is the tool's own JSON string, which is parsed
+    and returned (a tool that emits plain, non-JSON text gets its text handed back
+    verbatim as a str). `content[1]`, when present, is the diagnostics block the
+    estate MCP server appends (`wicked-estate-mcp/src/lib.rs`, "Append diagnostics
+    as a second text block"): one line each — `STALENESS: …` (W7.4 freshness),
+    `CLAMPED: …` (estate#242, a bound the server lowered), `LEXICAL-FALLBACK: …`.
+    They are returned as a list of lines so a caller can tell a stale or clamped
+    answer from a fresh, complete one (wicked-garden#1211).
+
+    Returns (None, []) on error / isError=true / a malformed envelope shape.
     """
     if not isinstance(envelope, dict):
-        return None
+        return None, []
     result = envelope.get("result")
     if not isinstance(result, dict) or result.get("isError"):
-        return None
+        return None, []
     content = result.get("content")
     if not isinstance(content, list) or not content:
-        return None
+        return None, []
     text = content[0].get("text") if isinstance(content[0], dict) else None
     if text is None:
-        return None
+        return None, []
     try:
-        return json.loads(text)
+        payload: Any = json.loads(text)
     except (json.JSONDecodeError, TypeError):
         # Some tools may return plain text; hand it back verbatim.
-        return text
+        payload = text
+    diagnostics: list[str] = []
+    for block in content[1:]:
+        more = block.get("text") if isinstance(block, dict) else None
+        if isinstance(more, str):
+            diagnostics.extend(line for line in more.split("\n") if line.strip())
+    return payload, diagnostics
+
+
+def _unwrap(envelope: Optional[dict]) -> Optional[Any]:
+    """The payload alone (`content[0]` parsed) — see `_unwrap_blocks` for both blocks.
+
+    Returns None on error / isError=true / a malformed envelope shape.
+    """
+    return _unwrap_blocks(envelope)[0]
 
 
 # ─────────────────────────────────────────────────────────────────────────────
@@ -791,6 +811,24 @@ def call(tool: str, arguments: Optional[dict] = None, timeout: float = 8.0) -> O
         return None
 
 
+def call_blocks(tool: str, arguments: Optional[dict] = None, timeout: float = 8.0) -> Optional[dict]:
+    """Like `call`, but keep the diagnostics block (wicked-garden#1211).
+
+    Returns {"result": <parsed payload>, "diagnostics": [<line>, …]} — the
+    `STALENESS:` / `CLAMPED:` / `LEXICAL-FALLBACK:` lines estate rides in the
+    second content block — or None when estate is unreachable or the tool
+    errored (the same fail-open shape as `call`).
+    """
+    try:
+        env = _rpc("tools/call", {"name": tool, "arguments": arguments or {}}, timeout=timeout)
+    except Exception:
+        return None
+    payload, diagnostics = _unwrap_blocks(env)
+    if payload is None and not diagnostics:
+        return None
+    return {"result": payload, "diagnostics": diagnostics}
+
+
 def call_raw(tool: str, arguments: Optional[dict] = None, timeout: float = 8.0) -> Optional[dict]:
     """Like `call`, but return the full MCP envelope (for callers that need
     `isError` / staleness diagnostics). Fail-open (None)."""
@@ -1053,7 +1091,11 @@ def main(argv: list) -> int:
         if not tool:
             _emit({"error": "call requires {\"tool\": \"<ToolName>\", \"arguments\": {...}}"})
             return 1
-        _emit({"result": call(tool, args.get("arguments", {}))})
+        # Both blocks, in-band (wicked-garden#1211): the seat reading stdout sees the
+        # `STALENESS:` / `CLAMPED:` lines beside the payload, as the MCP caller does.
+        blocks = call_blocks(tool, args.get("arguments", {}))
+        _emit({"result": blocks["result"] if blocks else None,
+               "diagnostics": blocks["diagnostics"] if blocks else []})
     elif action == "propose":
         kind_type = args.get("kind_type")
         payload = args.get("payload")

package/scripts/demo/record.mjs

@@ -79,6 +79,49 @@ export function failedAtInVideo(dir, failedAt, trimStart = SEGMENT_TRIM_START) {
   }
 }
 
+// ---- exported stitch ---------------------------------------------------------------------------
+/**
+ * Join segment videos (same codec, size and frame rate — every take is cut by buildVideo) into one MP4 with
+ * chapter metadata, without re-encoding. `parts` = [{ title, file }] in take order; `workDir` holds the two
+ * ffmpeg list files. Returns the `| m:ss | Title |` marker rows (chapters.md) and the total seconds.
+ */
+export function stitchParts(parts, outFile, { ffmpeg = "ffmpeg", title = "Demo", workDir }) {
+  const ffprobe = ffprobeOf(ffmpeg);
+  const probeSeconds = (file) => {
+    const r = spawnSync(ffprobe, ["-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", file], { encoding: "utf8" });
+    if (r.status !== 0) throw new Error(`ffprobe failed on ${file}: ${r.stderr}`);
+    return Number(r.stdout.trim());
+  };
+  if (!parts.length) throw new Error("no segments recorded yet");
+  fs.mkdirSync(workDir, { recursive: true });
+  const list = path.join(workDir, "concat.txt");
+  fs.writeFileSync(list, parts.map((p) => `file '${p.file.replace(/\\/g, "/").replace(/'/g, "'\\''")}'`).join("\n") + "\n");
+  let at = 0;
+  const meta = [";FFMETADATA1", `title=${String(title).replace(/[=;#\\\n]/g, " ")}`];
+  const rows = ["| Time | Chapter |", "|---|---|"];
+  for (const p of parts) {
+    const d = probeSeconds(p.file);
+    meta.push("[CHAPTER]", "TIMEBASE=1/1000", `START=${Math.round(at * 1000)}`, `END=${Math.round((at + d) * 1000)}`, `title=${String(p.title).replace(/[=;#\\\n]/g, " ")}`);
+    rows.push(`| ${Math.floor(at / 60)}:${String(Math.floor(at % 60)).padStart(2, "0")} | ${p.title} |`);
+    at += d;
+  }
+  const metaFile = path.join(workDir, "chapters.ffmeta");
+  fs.writeFileSync(metaFile, meta.join("\n") + "\n");
+  const r = spawnSync(ffmpeg, ["-y", "-f", "concat", "-safe", "0", "-i", list, "-i", metaFile, "-map", "0", "-map_metadata", "1",
+    "-map_chapters", "1", "-map", "-0:d", "-c", "copy", "-movflags", "+faststart", outFile], { stdio: ["ignore", "ignore", "pipe"] });
+  if (r.status !== 0) throw new Error(`stitch failed: ${r.stderr?.toString().slice(-1500)}`);
+  return { seconds: at, rows };
+}
+
+/** One frame of a video as a JPEG (`atSec` into it); false when ffmpeg could not decode one there. */
+export function extractFrame(video, atSec, outFile, { ffmpeg = "ffmpeg" } = {}) {
+  const r = spawnSync(ffmpeg, ["-y", "-ss", String(Math.max(0, atSec)), "-i", video, "-frames:v", "1", "-q:v", "3", outFile],
+    { stdio: ["ignore", "ignore", "pipe"] });
+  const ok = r.status === 0 && fs.existsSync(outFile) && fs.statSync(outFile).size > 0;
+  if (!ok) fs.rmSync(outFile, { force: true });
+  return ok;
+}
+
 // ---- exported recorder factory -----------------------------------------------------------------
 /**
  * Build a reusable per-segment recorder bound to a story context.
@@ -241,7 +284,6 @@ export function makeSegmentRecorder({
 // ---- CLI entry point (only runs when invoked directly) -----------------------------------------
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   const FFMPEG = process.env.FFMPEG || "ffmpeg";
-  const FFPROBE = ffprobeOf(FFMPEG);
 
   function usage(msg) {
     if (msg) console.error(`error: ${msg}\n`);
@@ -302,12 +344,6 @@ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
   const readTimings = (key) => { try { return JSON.parse(fs.readFileSync(path.join(segDir(key), "timings.json"), "utf8")); } catch { return {}; } };
 
   // ---- stitch ----
-  function probeSeconds(file) {
-    const r = spawnSync(FFPROBE, ["-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", file], { encoding: "utf8" });
-    if (r.status !== 0) throw new Error(`ffprobe failed on ${file}: ${r.stderr}`);
-    return Number(r.stdout.trim());
-  }
-
   /** A segment's guard.json (how its last take was recorded), or null when it has none. */
   function readGuard(key) {
     try { return JSON.parse(fs.readFileSync(path.join(segDir(key), "guard.json"), "utf8")); } catch { return null; }
@@ -333,24 +369,10 @@ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
     refuseFailedTakes();
     const segs = SEGMENTS.filter((s) => fs.existsSync(segVideo(s.key)));
     const missing = SEGMENTS.filter((s) => !fs.existsSync(segVideo(s.key))).map((s) => s.key);
-    if (!segs.length) throw new Error("no segments recorded yet");
-    const list = path.join(SEG_DIR, "concat.txt");
-    fs.writeFileSync(list, segs.map((s) => `file '${segVideo(s.key).replace(/\\/g, "/").replace(/'/g, "'\\''")}'`).join("\n") + "\n");
-    let at = 0;
-    const meta = [";FFMETADATA1", `title=${(story.title || "Demo").replace(/[=;#\\\n]/g, " ")}`];
-    const rows = ["| Time | Chapter |", "|---|---|"];
-    for (const s of segs) {
-      const d = probeSeconds(segVideo(s.key));
-      const title = s.intro ? "Introduction" : s.title;
-      meta.push("[CHAPTER]", "TIMEBASE=1/1000", `START=${Math.round(at * 1000)}`, `END=${Math.round((at + d) * 1000)}`, `title=${title.replace(/[=;#\\\n]/g, " ")}`);
-      rows.push(`| ${Math.floor(at / 60)}:${String(Math.floor(at % 60)).padStart(2, "0")} | ${title} |`);
-      at += d;
-    }
-    fs.writeFileSync(path.join(SEG_DIR, "chapters.ffmeta"), meta.join("\n") + "\n");
-    // Segments share codec, size and frame rate, so they join without re-encoding.
-    const r = spawnSync(FFMPEG, ["-y", "-f", "concat", "-safe", "0", "-i", list, "-i", path.join(SEG_DIR, "chapters.ffmeta"), "-map", "0", "-map_metadata", "1",
-      "-map_chapters", "1", "-map", "-0:d", "-c", "copy", "-movflags", "+faststart", FINAL], { stdio: ["ignore", "ignore", "pipe"] });
-    if (r.status !== 0) throw new Error(`stitch failed: ${r.stderr?.toString().slice(-1500)}`);
+    const { seconds: at, rows } = stitchParts(
+      segs.map((s) => ({ title: s.intro ? "Introduction" : s.title, file: segVideo(s.key) })),
+      FINAL, { ffmpeg: FFMPEG, title: story.title || "Demo", workDir: SEG_DIR },
+    );
     fs.writeFileSync(path.join(OUT, "chapters.md"), rows.join("\n") + "\n");
     fs.writeFileSync(path.join(OUT, "timings.json"), JSON.stringify(Object.fromEntries(SEGMENTS.map((s) => [s.key, readTimings(s.key)])), null, 2));
     // How the stitched segments were recorded: read-only only when every one of them was (a segment recorded

package/scripts/demo/walkthrough-lint.mjs

@@ -0,0 +1,248 @@
+// Walkthrough storyline lint (DES-walkthrough-proof §4.5; wicked-garden#1231).
+//
+//   wicked-garden run scripts/demo/walkthrough.mjs lint --root <author dir> [--storyline <path>]
+//                                                       [--tree <dir>] [--steps <id,id,...>]
+//
+// The `walkthrough_plan` step's pinned validator runs this against the author dir the engine hands it
+// (wicked-core `WALKTHROUGH_LINT_SCRIPT`: `--root "${WICKED_EVIDENCE_ROOT}"`, where that root is
+// `<evidence root>/author/<plan step>`). It reads `<root>/storyline.mjs`, prints one JSON object
+// `{ok, storyline, chapters, checks, findings: [{rule, where, detail}]}` on stdout and exits 0 only when
+// there is no finding; 1 when there is at least one; 2 on a usage error.
+//
+// A check's `kind` is the record tool's collector (`runCollector` in walkthrough.mjs). The DES's check
+// classes map onto them: locator = on_screen, probe/artifact = saved_state/events/side_effects/output,
+// guard = must_not_happen, join = cross_check.
+
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
+
+export const CHECK_CLASS = Object.freeze({
+  __proto__: null,
+  locator: "on_screen",
+  probe: "state",
+  artifact: "state",
+  guard: "must_not_happen",
+  join: "cross_check",
+});
+
+/** The verifier the record tool hands the vault for a check (kept in step with walkthrough.mjs verifierForCheck). */
+export function defaultVerifier(kind) {
+  switch (kind) {
+    case "locator": return { kind: "jq_pred", params: { expr: ".inner_text != null" } };
+    case "probe": return { kind: "jq_pred", params: { expr: ".raw.exit_code == 0" } };
+    case "artifact": return { kind: "jq_pred", params: { expr: ".sha256 != null" } };
+    case "guard": return { kind: "jq_pred", params: { expr: "(.foreign_writes | length) == 0 and ((.console_errors // []) | length) == 0" } };
+    case "join": return { kind: "jq_pred", params: { expr: ".joined | to_entries | all(.value != null)" } };
+    default: return null;
+  }
+}
+
+const SEGMENT_KEY = /^[a-z0-9][a-z0-9-]*$/;
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const PLAIN_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+// Env names a storyline may not hand the fixture: credentials never reach the jailed app (§7).
+const SECRET_ENV = /(SECRET|TOKEN|PASSWORD|PASSWD|PASSPHRASE|API_?KEY|ACCESS_?KEY|PRIVATE_?KEY|CREDENTIAL|AUTH)/i;
+// Inline-code flags: `node -e`, `python -c`, `sh -c`, ... — the fixture must be a script the tree declares.
+const INLINE_FLAGS = new Set(["-e", "-c", "--eval", "-p", "--print", "--command"]);
+const SCRIPT_LIKE = /\.(?:m?js|cjs|ts|mts|py|sh|rb|pl)$/i;
+
+/** The first line of a thrown value's message; never throws itself (a storyline can throw anything). */
+function why(e) {
+  try { return String(e?.message ?? e).split("\n")[0]; } catch { return "the storyline threw a value that cannot be read"; }
+}
+
+function hasDotDot(p) { return /(?:^|[\\/])\.\.(?:[\\/]|$)/.test(p); }
+
+/**
+ * Lint a loaded storyline object. Pure apart from running `jq` for the negative samples.
+ * @param {object} story the storyline's default export
+ * @param {{tree?: string|null, steps?: string[]|null, jq?: string}} opts
+ * @returns {{findings: {rule: string, where: string, detail: string}[], chapters: number, checks: number}}
+ */
+export function lintStoryline(story, { tree = null, steps = null, jq = "jq" } = {}) {
+  const findings = [];
+  const add = (rule, where, detail) => findings.push({ rule, where, detail });
+
+  if (!story || typeof story !== "object") {
+    add("storyline_shape", "default export", "the storyline's default export must be an object");
+    return { findings, chapters: 0, checks: 0 };
+  }
+
+  // ---- baseUrl + fixture ------------------------------------------------------------------------------
+  if (story.baseUrl !== "fixture") {
+    add("base_url", "baseUrl", `baseUrl must be "fixture" (the record tool films the fixture it starts), got ${JSON.stringify(story.baseUrl)}`);
+  }
+  const fixture = story.fixture;
+  if (!fixture || typeof fixture !== "object") {
+    add("fixture_start", "fixture", "fixture is required: { start: [argv], ready, probes?, env? }");
+  } else {
+    const start = fixture.start;
+    if (!Array.isArray(start) || start.length === 0 || !start.every((a) => typeof a === "string" && a.length > 0)) {
+      add("fixture_start", "fixture.start", "fixture.start must be a non-empty argv array of strings (no shell)");
+    } else {
+      for (const arg of start.slice(1)) {
+        if (INLINE_FLAGS.has(arg)) add("fixture_start", "fixture.start", `inline code (${arg}) is refused: start a script the tree declares`);
+      }
+      for (const arg of start) {
+        if (path.isAbsolute(arg) || /^[A-Za-z]:[\\/]/.test(arg)) add("fixture_start", "fixture.start", `${JSON.stringify(arg)} is an absolute path; the fixture runs from app/ (the tree)`);
+        else if (hasDotDot(arg)) add("fixture_start", "fixture.start", `${JSON.stringify(arg)} leaves app/ (the tree)`);
+      }
+      if (tree) {
+        for (const arg of start.slice(1)) {
+          if (arg.startsWith("-") || path.isAbsolute(arg) || hasDotDot(arg)) continue;
+          if (!(arg.includes("/") || SCRIPT_LIKE.test(arg))) continue;
+          if (!fs.existsSync(path.join(tree, arg))) add("fixture_start", "fixture.start", `${JSON.stringify(arg)} is not in the tree (${tree})`);
+        }
+      }
+    }
+    if (fixture.env !== undefined) {
+      if (!fixture.env || typeof fixture.env !== "object" || Array.isArray(fixture.env)) {
+        add("fixture_env", "fixture.env", "fixture.env must be an object of name: value");
+      } else {
+        for (const name of Object.keys(fixture.env)) {
+          if (SECRET_ENV.test(name)) add("secret_env", `fixture.env.${name}`, "a secret-shaped env name is refused: no credential reaches the jailed app");
+        }
+      }
+    }
+    if (fixture.probes !== undefined && (!fixture.probes || typeof fixture.probes !== "object" || Array.isArray(fixture.probes))) {
+      add("fixture_probes", "fixture.probes", "fixture.probes must be an object of name: argv");
+    }
+  }
+  const probes = fixture && typeof fixture.probes === "object" && fixture.probes ? fixture.probes : {};
+
+  // ---- segments ---------------------------------------------------------------------------------------
+  const segments = Array.isArray(story.segments) ? story.segments : null;
+  if (!segments) {
+    add("segments", "segments", "segments must be an array");
+    return { findings, chapters: 0, checks: 0 };
+  }
+  const chapters = segments.filter((s) => s && !s.intro);
+  if (chapters.length === 0) add("segments", "segments", "the storyline has no chapter (an empty plan proves nothing)");
+
+  const seenKeys = new Set();
+  let checkCount = 0;
+  let mustNotHappen = 0;
+
+  segments.forEach((seg, i) => {
+    const where = `segments[${i}]${seg && typeof seg.key === "string" ? ` (${seg.key})` : ""}`;
+    if (!seg || typeof seg !== "object") { add("segment_shape", where, "a segment must be an object"); return; }
+    if (!SEGMENT_KEY.test(String(seg.key ?? ""))) add("segment_key", where, `key ${JSON.stringify(seg.key)}: lowercase letters, digits and hyphens only`);
+    else if (seenKeys.has(seg.key)) add("segment_key", where, `key ${JSON.stringify(seg.key)} is used twice`);
+    seenKeys.add(seg.key);
+    if (typeof seg.run !== "function") add("segment_run", where, "run(ctx) must be a function");
+    if (seg.intro) return;
+
+    // proves: plan step ids
+    if (!Array.isArray(seg.proves) || seg.proves.length === 0) {
+      add("proves", where, "proves[] must name at least one plan step id");
+    } else {
+      for (const id of seg.proves) {
+        if (typeof id !== "string" || !PLAIN_ID.test(id)) add("proves", where, `proves id ${JSON.stringify(id)} is not a plain step id`);
+        else if (steps && !steps.includes(id)) add("proves", where, `proves id ${JSON.stringify(id)} is not a step of the plan (${steps.join(", ")})`);
+      }
+    }
+
+    const checks = Array.isArray(seg.checks) ? seg.checks : null;
+    if (!checks || checks.length === 0) { add("chapter_checks", where, "a chapter needs checks[]"); return; }
+    const byId = new Map();
+    const classes = { on_screen: [], state: [], must_not_happen: [], cross_check: [] };
+
+    checks.forEach((c, j) => {
+      const cw = `${where}.checks[${j}]${c && typeof c.id === "string" ? ` (${c.id})` : ""}`;
+      if (!c || typeof c !== "object") { add("check_shape", cw, "a check must be an object"); return; }
+      checkCount += 1;
+      if (!SAFE_ID.test(String(c.id ?? ""))) add("check_id", cw, `id ${JSON.stringify(c.id)}: letters, digits, '.', '_' and '-' only`);
+      else if (byId.has(c.id)) add("check_id", cw, `id ${JSON.stringify(c.id)} is used twice in this chapter`);
+      const cls = typeof c.kind === "string" && Object.hasOwn(CHECK_CLASS, c.kind) ? CHECK_CLASS[c.kind] : null;
+      if (!cls) { add("check_kind", cw, `kind ${JSON.stringify(c.kind)} is not one of ${Object.keys(CHECK_CLASS).join(", ")}`); return; }
+      classes[cls].push(c.id);
+      if (cls === "must_not_happen") mustNotHappen += 1;
+
+      // Collector inputs
+      if (c.kind === "locator" && (typeof c.selector !== "string" || !c.selector.trim())) add("check_selector", cw, "a locator check needs a selector");
+      if (c.kind === "probe") {
+        if (typeof c.name !== "string" || !c.name) add("check_probe", cw, "a probe check needs name (a key of fixture.probes)");
+        else if (!Object.prototype.hasOwnProperty.call(probes, c.name)) add("check_probe", cw, `probe ${JSON.stringify(c.name)} is not in fixture.probes`);
+        if (c.parse !== undefined && !["json", "jsonl", "sqlite-json", "text"].includes(c.parse)) add("check_probe", cw, `parse ${JSON.stringify(c.parse)} is not json | jsonl | sqlite-json | text`);
+      }
+      if (c.kind === "artifact") {
+        const p = c.path;
+        if (typeof p !== "string" || !p) add("check_artifact", cw, "an artifact check needs path (relative to DATA_DIR)");
+        else if (path.isAbsolute(p) || hasDotDot(p)) add("check_artifact", cw, `artifact path ${JSON.stringify(p)} escapes DATA_DIR`);
+      }
+      if (c.kind === "join") {
+        const src = Array.isArray(c.sources) ? c.sources : [];
+        if (src.length < 2) add("check_join", cw, "a join needs sources[] naming at least two earlier checks");
+        for (const s of src) if (!byId.has(s)) add("check_join", cw, `source ${JSON.stringify(s)} is not an earlier check of this chapter`);
+      }
+
+      // Verifier + negative samples (S3): the verifier must FAIL on every sample.
+      const verifier = c.verify === undefined ? defaultVerifier(c.kind) : c.verify;
+      const expr = verifier?.params?.expr;
+      if (!verifier || verifier.kind !== "jq_pred" || typeof expr !== "string" || !expr.trim()) {
+        add("check_verify", cw, "verify must be { kind: \"jq_pred\", params: { expr } } — the one verifier the record tool hands the vault");
+      } else {
+        const negs = c.negative;
+        if (!Array.isArray(negs) || negs.length === 0) {
+          add("negative_missing", cw, "every check needs at least one negative sample (a capture its verifier must FAIL)");
+        } else {
+          negs.forEach((sample, k) => {
+            const r = spawnSync(jq, ["-e", expr], { input: JSON.stringify(sample), encoding: "utf8", timeout: 10_000 });
+            if (r.error) add("negative_unverified", `${cw}.negative[${k}]`, `jq could not run (${r.error.code ?? r.error.message}); the lint fails closed`);
+            else if (r.status === 0) add("negative_passes", `${cw}.negative[${k}]`, `the verifier \`${expr}\` PASSES this sample, so the check cannot fail (a tautology)`);
+            else if (r.status !== 1 && r.status !== 4) add("check_verify", cw, `jq rejected \`${expr}\` (exit ${r.status}): ${(r.stderr || "").trim().slice(0, 200)}`);
+          });
+        }
+      }
+      byId.set(c.id, c);
+    });
+
+    if (classes.on_screen.length === 0) add("chapter_on_screen", where, "a chapter needs at least one on_screen check (kind: locator)");
+    if (classes.state.length === 0) add("chapter_state", where, "a chapter needs at least one saved_state/events/side_effects/output check (kind: probe or artifact)");
+    if (classes.on_screen.length && classes.state.length) {
+      const joined = checks.some((c) => c?.kind === "join" && Array.isArray(c.sources)
+        && c.sources.some((s) => classes.on_screen.includes(s)) && c.sources.some((s) => classes.state.includes(s)));
+      if (!joined) add("chapter_cross_check", where, "a chapter with on_screen and state checks needs a join (cross_check) whose sources include one of each");
+    }
+  });
+
+  if (chapters.length && mustNotHappen === 0) add("must_not_happen", "segments", "the walkthrough needs at least one must_not_happen check (kind: guard)");
+
+  return { findings, chapters: chapters.length, checks: checkCount };
+}
+
+/** The `lint` action: resolve, import and lint the storyline; print the report; return the exit code. */
+export async function lintAction({ root, storyline, tree, steps }) {
+  const storyPath = storyline ? path.resolve(storyline) : root ? path.join(path.resolve(root), "storyline.mjs") : null;
+  const report = (findings, extra = {}) => {
+    const out = { ok: findings.length === 0, storyline: storyPath, chapters: 0, checks: 0, ...extra, findings };
+    process.stdout.write(JSON.stringify(out) + "\n");
+    for (const f of findings) process.stderr.write(`lint: ${f.rule} at ${f.where}: ${f.detail}\n`);
+    return findings.length === 0 ? 0 : 1;
+  };
+  if (!storyPath) {
+    process.stderr.write("usage: walkthrough.mjs lint --root <author dir> [--storyline <path>] [--tree <dir>] [--steps <id,...>]\n");
+    return 2;
+  }
+  let st;
+  try { st = fs.statSync(storyPath); } catch {
+    return report([{ rule: "storyline_missing", where: storyPath, detail: "no storyline here: the walkthrough_plan author writes <author dir>/storyline.mjs" }]);
+  }
+  if (!st.isFile()) return report([{ rule: "storyline_missing", where: storyPath, detail: "not a regular file" }]);
+  let story;
+  try {
+    story = (await import(pathToFileURL(storyPath).href)).default;
+  } catch (e) {
+    return report([{ rule: "storyline_unloadable", where: storyPath, detail: why(e) }]);
+  }
+  let result;
+  try {
+    result = lintStoryline(story, { tree: tree ? path.resolve(tree) : null, steps });
+  } catch (e) {
+    // A storyline that throws while being read (a getter, a proxy) is a finding, never a crash without a report.
+    return report([{ rule: "storyline_unreadable", where: storyPath, detail: why(e) }]);
+  }
+  return report(result.findings, { chapters: result.chapters, checks: result.checks });
+}