pm-starter 2026.10.25 → 2026.10.27

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 2026.10.27 - 2026-10-27
+
+### Other
+
+- Use SDK-certified complete reads in starter commands and exports ([pm-starter-sdk-adoption-1025](https://github.com/unbraind/pm-starter/blob/main/.agents/pm/tasks/pm-starter-sdk-adoption-1025.toon))
+
 ## 2026.10.25 - 2026-10-25
 
 ### Added
@@ -19,7 +25,6 @@
 
 ### Fixed
 
-- Fix release publish ordering before protected main push ([pm-starter-nf9d](https://github.com/unbraind/pm-starter/blob/main/.agents/pm/issues/pm-starter-nf9d.toon))
 - The changelog gate stamps an untagged version with the current date, so its verdict flips every midnight with no commit ([pm-starter-4n5o](https://github.com/unbraind/pm-starter/blob/main/.agents/pm/issues/pm-starter-4n5o.toon))
 - The release job authenticated with a stored npm token that expired, so publishing stopped while every other gate stayed green ([pm-starter-fllw](https://github.com/unbraind/pm-starter/blob/main/.agents/pm/issues/pm-starter-fllw.toon))
 - A release run bumped and committed a new version every night while publishing was impossible, because the only externally-failable step runs last ([pm-starter-kjvk](https://github.com/unbraind/pm-starter/blob/main/.agents/pm/issues/pm-starter-kjvk.toon))
@@ -28,6 +33,10 @@
 
 - Certify pm-starter on PM CLI/SDK 2026.10.4 and consolidate pending dependency updates ([pm-starter-cz6b](https://github.com/unbraind/pm-starter/blob/main/.agents/pm/chores/pm-starter-cz6b.toon))
 
+### Closed
+
+- Closed: Fix release publish ordering before protected main push ([pm-starter-nf9d](https://github.com/unbraind/pm-starter/blob/main/.agents/pm/issues/pm-starter-nf9d.toon))
+
 ## 2026.10.5 - 2026-10-05
 
 ### Other
@@ -89,32 +98,38 @@
 
 ### Fixed
 
-- Pin pm-changelog 2026.8.30 before the next release ([pm-starter-pjdl](https://github.com/unbraind/pm-starter/blob/main/.agents/pm/issues/pm-starter-pjdl.toon))
 - Regenerate the changelog after the release tag exists ([pm-starter-b41g](https://github.com/unbraind/pm-starter/blob/main/.agents/pm/issues/pm-starter-b41g.toon))
 
+### Closed
+
+- Closed: Pin pm-changelog 2026.8.30 before the next release ([pm-starter-pjdl](https://github.com/unbraind/pm-starter/blob/main/.agents/pm/issues/pm-starter-pjdl.toon))
+
 ## 2026.8.29 - 2026-08-29
 
 ### Fixed
 
 - A failed provenance publish silently falls back to an unattested one ([pm-starter-uxmy](https://github.com/unbraind/pm-starter/blob/main/.agents/pm/issues/pm-starter-uxmy.toon))
-- Close PR 82 attestation audit bypasses ([pm-starter-83vb](https://github.com/unbraind/pm-starter/blob/main/.agents/pm/issues/pm-starter-83vb.toon))
 - The publish-attestation gate misses a publish routed through an unquoted shell variable ([pm-starter-74p9](https://github.com/unbraind/pm-starter/blob/main/.agents/pm/issues/pm-starter-74p9.toon))
 - Fix same-line scalar assignment bypass in publish attestation scanner ([pm-starter-2899](https://github.com/unbraind/pm-starter/blob/main/.agents/pm/issues/pm-starter-2899.toon))
 
+### Closed
+
+- Closed: Close PR 82 attestation audit bypasses ([pm-starter-83vb](https://github.com/unbraind/pm-starter/blob/main/.agents/pm/issues/pm-starter-83vb.toon))
+
 ## 2026.8.28 - 2026-08-28
 
 ### Fixed
 
 - changelog scripts read the workspace with default budgets, so pm-changelog refuses complete-read checks once the tracker exceeds one page ([pm-starter-ibm7](https://github.com/unbraind/pm-starter/blob/main/.agents/pm/issues/pm-starter-ibm7.toon))
 
-### Security
-
-- The identity gate deadlocks the one remediation its own failure message prescribes ([pm-starter-tf19](https://github.com/unbraind/pm-starter/blob/main/.agents/pm/issues/pm-starter-tf19.toon))
-
 ### Other
 
 - Retire stale PR 65 evidence note after revert 67 ([pm-starter-pmnm](https://github.com/unbraind/pm-starter/blob/main/.agents/pm/tasks/pm-starter-pmnm.toon))
 
+### Closed
+
+- Closed: The identity gate deadlocks the one remediation its own failure message prescribes ([pm-starter-tf19](https://github.com/unbraind/pm-starter/blob/main/.agents/pm/issues/pm-starter-tf19.toon))
+
 ## 2026.8.17 - 2026-08-17
 
 ### Fixed
@@ -186,14 +201,14 @@
 
 ## 2026.7.28 - 2026-07-28
 
-### Fixed
-
-- Extension reports a stale runtime version after the 2026.7.27 bump ([pm-starter-1atg](https://github.com/unbraind/pm-starter/blob/main/.agents/pm/issues/pm-starter-1atg.toon))
-
 ### Other
 
 - Adopt pm-cli 2026.7.28 ([pm-starter-evym](https://github.com/unbraind/pm-starter/blob/main/.agents/pm/chores/pm-starter-evym.toon))
 
+### Closed
+
+- Closed: Extension reports a stale runtime version after the 2026.7.27 bump ([pm-starter-1atg](https://github.com/unbraind/pm-starter/blob/main/.agents/pm/issues/pm-starter-1atg.toon))
+
 ## 2026.7.27 - 2026-07-27
 
 ### Removed
@@ -202,34 +217,34 @@
 
 ## 2026.7.26 - 2026-07-26
 
-### Fixed
-
-- Starter template used any throughout, hiding three wrong SDK contracts and three unguarded pm reads ([pm-starter-kre3](https://github.com/unbraind/pm-starter/blob/main/.agents/pm/issues/pm-starter-kre3.toon))
-
 ### Other
 
 - Enable governance duplicate-detection advisory mode and adopt pm-cli 2026.7.25 ([pm-starter-tfh8](https://github.com/unbraind/pm-starter/blob/main/.agents/pm/chores/pm-starter-tfh8.toon))
 
-## 2026.7.25 - 2026-07-25
+### Closed
 
-### Fixed
+- Closed: Starter template used any throughout, hiding three wrong SDK contracts and three unguarded pm reads ([pm-starter-kre3](https://github.com/unbraind/pm-starter/blob/main/.agents/pm/issues/pm-starter-kre3.toon))
 
-- pm item reads are capped at Node's 1 MiB spawnSync default, so a mature tracker fails with no diagnosis ([pm-starter-y8hb](https://github.com/unbraind/pm-starter/blob/main/.agents/pm/issues/pm-starter-y8hb.toon))
+## 2026.7.25 - 2026-07-25
 
 ### Other
 
 - Adopt --respect-item-release in changelog scripts and bump pm-changelog to 2026.7.24 ([pm-starter-toz4](https://github.com/unbraind/pm-starter/blob/main/.agents/pm/chores/pm-starter-toz4.toon))
 
-## 2026.7.23 - 2026-07-23
+### Closed
 
-### Fixed
+- Closed: pm item reads are capped at Node's 1 MiB spawnSync default, so a mature tracker fails with no diagnosis ([pm-starter-y8hb](https://github.com/unbraind/pm-starter/blob/main/.agents/pm/issues/pm-starter-y8hb.toon))
 
-- Recommend pm merge reconcile (2026.7.22) over raw history-repair in Multi-agent merge safety docs ([pm-starter-ll3f](https://github.com/unbraind/pm-starter/blob/main/.agents/pm/issues/pm-starter-ll3f.toon))
+## 2026.7.23 - 2026-07-23
 
 ### Other
 
 - Adopt pm field-aware merge driver for multi-agent branch-merge safety ([pm-starter-ey52](https://github.com/unbraind/pm-starter/blob/main/.agents/pm/chores/pm-starter-ey52.toon))
 
+### Closed
+
+- Closed: Recommend pm merge reconcile (2026.7.22) over raw history-repair in Multi-agent merge safety docs ([pm-starter-ll3f](https://github.com/unbraind/pm-starter/blob/main/.agents/pm/issues/pm-starter-ll3f.toon))
+
 ## 2026.7.19 - 2026-07-19
 
 ### Added

package/README.md

@@ -117,8 +117,8 @@ acceptance is a separate concern. A changing source fails parity explicitly.
 
 ## Without git
 
-All starter commands, the read-only exporters, and both laboratories work in a plain
-initialized tracker with no Git executable. Creating or running a laboratory needs
+All starter commands, the read-only exporters, both laboratories and the failure-first
+recovery recipes work in a plain initialized tracker with no Git executable. Creating or running a laboratory needs
 no repository. Cloning the starter and repository release/changelog automation need
 Git. Laboratory commands require a host that injects the SDK (tested with 2026.10.20)
 and return an actionable refusal when it is absent.
@@ -148,6 +148,32 @@ implementation; the real CLI supplies the live `api` object at activation time.
 For the same reason the `EXIT_CODE` / `CommandError` error contract is
 re-implemented locally rather than imported from the SDK.
 
+## Complete SDK reads
+
+`starter demo` and `starter-demo export` use `ctx.sdk.client.listAllComplete`
+with full bodies, including closed and canceled items. The SDK calls
+`certifyCompleteListResult` itself: there is no external JSON envelope parser
+or local completeness policy left in this package. Both commands then call the
+SDK history action with `verify: true` for each item. That action reads fresh
+history and uses `verifyHistoryEntries`, including comparison with the current
+item, before returning a verification receipt. A cached event index is never
+accepted as integrity evidence. These reads work without `pm` or `git` on PATH.
+
+Install and activation require pm-cli >=2026.8.18, the first published stable
+release with `PmClient.listAllComplete`. The development SDK remains pinned to
+2026.10.20. See the [published API inventory](docs/sdk-floor.md) for every used
+capability and its first-release artifact evidence. Hosts without SDK injection
+receive an explicit failed-read outcome. Failed or incomplete reads
+continue to fail with exit code 1, including exports; they never become an empty
+workspace. SDK certification is intentionally stricter about counts, unique IDs,
+full projections, unbounded delivery and omission receipts. Invalid history now
+fails explicitly, even if a previous cached read succeeded. `PM_JSON_MAX_BUFFER`
+continues to apply to the other subprocess examples; SDK reads do not use it.
+The exported `readPmItems` helper now accepts the host SDK context and returns a
+Promise. The former `describeListAllIncompleteness` helper was removed with its
+local policy. SDK rows can retain optional properties with value `undefined`
+that CLI JSON omitted; their serialized values are identical. Renderer ownership and callback guards retain their existing scope.
+
 ## SDK 2026.7.6 patterns
 
 The starter demonstrates several patterns introduced or stabilized in the
@@ -224,3 +250,19 @@ npx pm github sync --repo unbraind/pm-starter --dry-run
 ```
 
 This does not enable scheduled sync. See `docs/certification-2026.10.4.md` for validation and copied-real-tracker evidence. Whole-executable and statement coverage remains tracked in `pm-starter-puy5`.
+
+## Failure-first task recipes
+
+`pm starter recover --json` deliberately encounters three native refusals and
+finishes each read through a structured recovery contract. Use
+`--recipe missing-item|unsupported-capability|insufficient-budget` for one loop,
+or `--output-format toon` for compact TOON receipts. The typed
+`runFailureFirstRecipes(ctx.sdk, { recipe: 'all' })` API uses the same code path.
+
+The workflows discover a valid item ID, select an advertised graph read, and
+recover an infeasible output budget using the SDK's certified complete-list
+helper. They read existing trackers without Git and never execute suggested
+shell text or write item data. Each receipt asserts its native discriminator,
+remedy and successful retry; the missing-item SDK classifier is labeled
+explicitly. See the [runnable CLI and SDK examples](docs/failure-first-recipes.md)
+for contracts, refusal codes and concurrency limits.

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./laboratories.ts";
-import type { ExtensionApi } from "@unbrained/pm-cli/sdk";
+export * from "./recipes.ts";
+import type { CommandHandlerContext, ExtensionApi } from "@unbrained/pm-cli/sdk";
 /**
  * Semantic exit codes this package throws via {@link CommandError}.
  *
@@ -57,38 +58,15 @@ export type PmReadOutcome = {
     readonly reason: string;
 };
 /**
- * Safely read all items from the workspace by shelling out to `pm`.
+ * Read the whole tracker through the host SDK, preserving explicit failure.
  *
- * Never throws, so demos cannot blow up at activation/read time — but it also
- * never reports a failed read as an empty workspace. Every failure path returns
- * `{ ok: false, reason }` naming what went wrong, and callers turn that into a
- * {@link CommandError} rather than rendering it as "no items". This is the SAFE
- * read pattern every demo reuses.
- *
- * @param pmRoot - Workspace root passed through to `pm --path`.
- * @returns The rows on a proven-complete read, or the reason the read failed.
- */
-export declare function readPmItems(pmRoot: string): PmReadOutcome;
-/**
- * Name the reason a `pm list --status all` envelope is not the whole workspace, or
- * return `null` when it is complete.
- *
- * The envelope has carried a completeness receipt since 2026.8.15, and reading
- * `.items` without consulting it is how a partial answer becomes a
- * successful-looking result. That is not hypothetical: pm-cli 2026.8.14 returned
- * 10 items of a 682-item workspace with `truncated: true`, and every consumer
- * that ignored the receipt reported success on 1.5% of the data.
- *
- * Four independent signals each mean "the rows you got are not all the rows".
- * A missing `completeness` object counts as incomplete rather than complete: an
- * answer that cannot be verified is not a verified answer, and treating absence
- * as success is the same mistake one level up.
- *
- * @param envelope - Parsed `pm list --status all --json` output.
- * @returns A human-readable reason naming the tripped signal and the
- *          count-versus-total figures, or `null` if the answer is complete.
+ * listAllComplete uses certifyCompleteListResult for strict, full, unbounded
+ * delivery. A fresh verified history read checks each item against its durable
+ * stream before any row reaches a command or exporter. History's verification
+ * delegates to verifyHistoryEntries, rather than trusting the cached event index.
+ * No runtime SDK import or pm/git subprocess is required.
  */
-export declare function describeListAllIncompleteness(envelope: unknown): string | null;
+export declare function readPmItems(ctx: Pick<CommandHandlerContext, "sdk">): Promise<PmReadOutcome>;
 declare const _default: {
     name: string;
     version: string;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAiDA,cAAc,mBAAmB,CAAC;AAElC,OAAO,KAAK,EAIV,YAAY,EAab,MAAM,uBAAuB,CAAC;AAoB/B;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS;aACpB,eAAe,EAAE,CAAC;aAClB,KAAK,EAAE,CAAC;aACR,SAAS,EAAE,CAAC;CACJ,CAAC;AAKX;;;;;;;;GAQG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,yFAAyF;IACzF,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,OAAO,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAkC,EAIxE;CACF;AAMD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAK1F;AAED,wFAAwF;AACxF,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAMpG;AAED,mFAAmF;AACnF,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,QAAQ,EAAE,MAAM,EAChB,GAAG,IAAI,EAAE,MAAM,EAAE,GAChB,MAAM,CAWR;AA4DD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CAAE,GACrE;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpD;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CA0EzD;AA2BD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CA2B9E;;;;kBA+3Be,YAAY"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAiDA,cAAc,mBAAmB,CAAC;AAElC,cAAc,cAAc,CAAC;AAE7B,OAAO,KAAK,EAGV,qBAAqB,EACrB,YAAY,EAab,MAAM,uBAAuB,CAAC;AAoB/B;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS;aACpB,eAAe,EAAE,CAAC;aAClB,KAAK,EAAE,CAAC;aACR,SAAS,EAAE,CAAC;CACJ,CAAC;AAKX;;;;;;;;GAQG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,yFAAyF;IACzF,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,OAAO,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAkC,EAIxE;CACF;AAMD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAK1F;AAED,wFAAwF;AACxF,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAMpG;AAED,mFAAmF;AACnF,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,QAAQ,EAAE,MAAM,EAChB,GAAG,IAAI,EAAE,MAAM,EAAE,GAChB,MAAM,CAWR;AA8CD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CAAE,GACrE;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpD;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC,qBAAqB,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAcjG;;;;kBAg5Be,YAAY"}

package/dist/index.js

@@ -6,8 +6,8 @@
 //
 // Each demonstration is labelled in comments as "DEMO: <capability>" and is
 // deliberately INERT — no destructive behavior and no network access. The demos
-// only read (via `pm ... --json`), print, or return data; they never delete or
-// mutate your workspace on their own.
+// only read (via the host SDK or `pm ... --json`), print, or return data; they
+// never delete or mutate your workspace on their own.
 //
 // ---------------------------------------------------------------------------
 // CAPABILITY → setup function → manifest capability  (see README for the full
@@ -46,6 +46,8 @@
 import { spawnSync } from "node:child_process";
 import { runExportLaboratory, runLaboratoryCommand } from "./laboratories.js";
 export * from "./laboratories.js";
+import { runFailureFirstCommand } from "./recipes.js";
+export * from "./recipes.js";
 // Standalone-installed extensions load ONLY their own `dist/` at runtime, so
 // `@unbrained/pm-cli` is not resolvable as a runtime value. We therefore use the
 // zero-runtime-coupling pattern: import `defineExtension` as a TYPE only and
@@ -175,177 +177,40 @@ function pmJsonMaxBuffer() {
     const raw = Number(process.env.PM_JSON_MAX_BUFFER);
     return Number.isSafeInteger(raw) && raw > 0 ? raw : 64 * 1024 * 1024;
 }
-/** Name the real cause of a failed `pm` read. A stdout overrun kills the child
- * with `status: null` and EMPTY stderr, so without this the failure surfaces as
- * an unexplained error (or, worse, as an empty result set). */
-function describePmReadFailure(error, limitBytes) {
-    const code = error.code;
-    if (code === "ENOBUFS") {
-        // This read is always the full workspace, so "narrow the operation" would be a
-        // dead instruction here — name only the lever the reader actually has.
-        return `pm output exceeded the ${limitBytes} byte read buffer. `
-            + "Raise PM_JSON_MAX_BUFFER (in bytes) to increase the read limit for this workspace.";
-    }
-    return `pm read failed: ${error.message}`;
-}
 /**
- * Safely read all items from the workspace by shelling out to `pm`.
- *
- * Never throws, so demos cannot blow up at activation/read time — but it also
- * never reports a failed read as an empty workspace. Every failure path returns
- * `{ ok: false, reason }` naming what went wrong, and callers turn that into a
- * {@link CommandError} rather than rendering it as "no items". This is the SAFE
- * read pattern every demo reuses.
+ * Read the whole tracker through the host SDK, preserving explicit failure.
  *
- * @param pmRoot - Workspace root passed through to `pm --path`.
- * @returns The rows on a proven-complete read, or the reason the read failed.
+ * listAllComplete uses certifyCompleteListResult for strict, full, unbounded
+ * delivery. A fresh verified history read checks each item against its durable
+ * stream before any row reaches a command or exporter. History's verification
+ * delegates to verifyHistoryEntries, rather than trusting the cached event index.
+ * No runtime SDK import or pm/git subprocess is required.
  */
-export function readPmItems(pmRoot) {
-    const maxBuffer = pmJsonMaxBuffer();
-    const result = spawnSync("pm", ["--path", pmRoot, "list", "--status", "all", "--full", "--include-body", "--no-truncate", "--strict-read", "--json"], { encoding: "utf-8", maxBuffer });
-    if (result.error) {
-        return { ok: false, reason: describePmReadFailure(result.error, maxBuffer) };
-    }
-    if (result.status !== 0) {
-        return {
-            ok: false,
-            reason: `pm exited ${result.status} — ${result.stderr?.trim() || "no stderr output"}`,
-        };
-    }
-    let parsed;
+export async function readPmItems(ctx) {
+    if (!ctx.sdk)
+        return { ok: false, reason: "This read requires a pm host with ctx.sdk (pm-cli >=2026.10.20)." };
     try {
-        parsed = JSON.parse(result.stdout);
-    }
-    catch (err) {
-        // Kept separate from the incompleteness check below so the diagnostic names
-        // the actual failure: unparseable output is a different problem from a
-        // parsed envelope that admits it is partial.
-        return {
-            ok: false,
-            reason: `could not parse \`pm list --status all --json\` output: ${err instanceof Error ? err.message : String(err)}`,
-        };
-    }
-    // A bare array carries no completeness receipt, so it cannot prove it is the
-    // whole workspace — and an unprovable answer is exactly what this reader
-    // exists to refuse. Accepting it would leave a legacy-shaped partial response
-    // as an open bypass around every check below.
-    if (Array.isArray(parsed)) {
-        return {
-            ok: false,
-            reason: "`pm list --status all --json` returned a bare array, which carries no completeness receipt to verify",
-        };
-    }
-    // Anything that is not an object carries no receipt either, and
-    // `describeListAllIncompleteness` answers `null` for every non-object — so
-    // without this check a payload of `null`, `false`, `42` or `"text"` would
-    // fall through to an absent rows field and be reported as a successful empty
-    // workspace. That is the bare-array fail-open one shape over.
-    if (!isObject(parsed)) {
-        return {
-            ok: false,
-            reason: `\`pm list --status all --json\` returned ${parsed === null ? "null" : typeof parsed}, which carries no completeness receipt to verify`,
-        };
-    }
-    const incomplete = describeListAllIncompleteness(parsed);
-    if (incomplete) {
-        // A truncated or degraded envelope is a FAILED read that looks like a
-        // successful one: `items` is present and parses, so without this check the
-        // demo renders a partial workspace and reports success.
-        return { ok: false, reason: `refusing an incomplete pm read — ${incomplete}` };
-    }
-    const rows = readPath(parsed, "items") ?? readPath(parsed, "results");
-    if (rows === undefined)
-        return { ok: true, items: [] };
-    if (!Array.isArray(rows)) {
-        return { ok: false, reason: "`pm list --status all --json` returned a non-array rows field" };
+        const result = await ctx.sdk.client.listAllComplete({ includeBody: true });
+        for (const item of result.items) {
+            const history = await ctx.sdk.client.run("history", { id: item.id, options: { verify: true, compact: true } });
+            if (readPath(history, "verification", "ok") !== true) {
+                return { ok: false, reason: `history integrity verification failed for ${item.id}` };
+            }
+        }
+        return { ok: true, items: result.items };
     }
-    // Dropping unusable rows would contradict everything above: the receipt said
-    // this answer is the whole workspace, so silently returning fewer rows than it
-    // contains is a partial read reported as a complete one — the exact failure
-    // this reader exists to refuse, arriving through the row payload instead of
-    // through the receipt.
-    const unusable = rows.findIndex((row) => !isObject(row));
-    if (unusable !== -1) {
-        return {
-            ok: false,
-            reason: `\`pm list --status all --json\` returned an unusable row at index ${unusable} (${rows[unusable] === null ? "null" : typeof rows[unusable]}); the receipt claimed a complete answer, so dropping it would report a shortened workspace as complete`,
-        };
+    catch (error) {
+        return { ok: false, reason: String(error) };
     }
-    return { ok: true, items: rows };
 }
-/**
- * Read the workspace or fail the command, so a failed read never renders as an
- * empty one.
- *
- * @param pmRoot - Workspace root passed through to `pm --path`.
- * @returns The rows of a proven-complete read.
- * @throws {CommandError} With {@link EXIT_CODE.GENERIC_FAILURE} when the read failed.
- */
-function readPmItemsOrFail(pmRoot) {
-    const outcome = readPmItems(pmRoot);
+/** Read verified complete rows or fail with the command runtime's semantic exit code. */
+async function readPmItemsOrFail(ctx) {
+    const outcome = await readPmItems(ctx);
     if (!outcome.ok) {
         throw new CommandError(`pm-starter: could not read pm items — ${outcome.reason}`, EXIT_CODE.GENERIC_FAILURE);
     }
     return outcome.items;
 }
-/**
- * Render one count field for the scale suffix, tolerating a field the installed
- * CLI does not emit or emits as something other than a number.
- */
-function readCount(envelope, key) {
-    const value = readPath(envelope, key);
-    return typeof value === "number" ? String(value) : "?";
-}
-/**
- * Name the reason a `pm list --status all` envelope is not the whole workspace, or
- * return `null` when it is complete.
- *
- * The envelope has carried a completeness receipt since 2026.8.15, and reading
- * `.items` without consulting it is how a partial answer becomes a
- * successful-looking result. That is not hypothetical: pm-cli 2026.8.14 returned
- * 10 items of a 682-item workspace with `truncated: true`, and every consumer
- * that ignored the receipt reported success on 1.5% of the data.
- *
- * Four independent signals each mean "the rows you got are not all the rows".
- * A missing `completeness` object counts as incomplete rather than complete: an
- * answer that cannot be verified is not a verified answer, and treating absence
- * as success is the same mistake one level up.
- *
- * @param envelope - Parsed `pm list --status all --json` output.
- * @returns A human-readable reason naming the tripped signal and the
- *          count-versus-total figures, or `null` if the answer is complete.
- */
-export function describeListAllIncompleteness(envelope) {
-    // A non-object, or a bare ARRAY, carries no receipt to contradict — and an
-    // array is `typeof "object"`, so it must be excluded explicitly or the check
-    // reports every array as "completeness absent". `readPmItems` already handles
-    // the array shape on its own line above; only an ENVELOPE can claim to be
-    // incomplete.
-    if (!isObject(envelope))
-        return null;
-    // Every field below is read through `readPath` rather than asserted with a
-    // cast. These values come from whichever pm build the user has installed, so
-    // their types are an assumption, not a guarantee — and a cast that turns out
-    // to be wrong fails the comparison silently, which for a completeness receipt
-    // means reporting "complete" for an answer that never claimed to be.
-    const scale = `${readCount(envelope, "count")} of ${readCount(envelope, "total")} item(s) returned`;
-    if (readPath(envelope, "truncated") === true)
-        return `the row list was truncated (${scale})`;
-    if (readPath(envelope, "has_more") === true)
-        return `more rows exist past the returned page (${scale})`;
-    const status = readPath(envelope, "completeness", "status");
-    if (status !== "complete") {
-        // Anything that is not the literal string "complete" is treated as
-        // incomplete, including a non-string the cast would previously have let
-        // through untyped.
-        const described = status === undefined ? "absent" : JSON.stringify(status);
-        return `completeness.status is ${described}, not "complete" (${scale})`;
-    }
-    if (readPath(envelope, "omission_receipt", "has_omissions") === true) {
-        return `field groups were omitted from the projection (${scale})`;
-    }
-    return null;
-}
 // ---------------------------------------------------------------------------
 // DEMO: commands (registerCommand)
 //
@@ -365,6 +230,14 @@ export function describeListAllIncompleteness(envelope) {
  * @param api - The extension API surface passed to `activate`.
  */
 function setupCommands(api) {
+    api.registerCommand({
+        name: "starter recover",
+        description: "Encounter native refusals and finish read-only tasks through their structured remedies.",
+        examples: ["pm starter recover --json", "pm starter recover --recipe insufficient-budget"],
+        flags: [{ long: "--recipe", value_name: "recipe", type: "string", description: "all (default), missing-item, unsupported-capability or insufficient-budget." }],
+        failure_hints: ["Select an initialized tracker with at least one item and a host with ctx.sdk."],
+        run: runFailureFirstCommand,
+    });
     api.registerCommand({
         name: "starter lab",
         description: "Run one read-only capability laboratory on directory and synthetic remote adapters.",
@@ -471,10 +344,10 @@ function setupCommands(api) {
         intent: "demonstrate a command result flowing through a custom renderer",
         examples: ["pm starter demo", "pm starter demo --json"],
         failure_hints: [
-            "The demo reads items via `pm list --status all --json`; ensure the workspace is initialized.",
+            "The demo uses host SDK complete reads and verified history; initialize the workspace and use pm-cli >=2026.10.20.",
         ],
         async run(ctx) {
-            const items = readPmItemsOrFail(ctx.pm_root);
+            const items = await readPmItemsOrFail(ctx);
             // Return a small, predictable shape the renderer override can recognize.
             return {
                 starter_demo: true,
@@ -937,7 +810,7 @@ function setupImportExport(api) {
     // Read-only: serializes the current items to a compact JSON payload and
     // prints it (or returns it for --json hosts). Never writes to disk.
     api.registerExporter("starter-demo", async (ctx) => {
-        const items = readPmItemsOrFail(ctx.pm_root);
+        const items = await readPmItemsOrFail(ctx);
         const payload = items.map((i) => ({
             id: i.id,
             title: i.title,
@@ -1067,7 +940,7 @@ function setupPreflight(api) {
         return {
             enforce_item_format_gate: d.enforce_item_format_gate ?? true,
             run_preflight_item_format_sync: d.run_preflight_item_format_sync ?? false,
-            run_extension_migrations: ctx.command === "starter lab" || ctx.command === "starter-lab export"
+            run_extension_migrations: ctx.command === "starter lab" || ctx.command === "starter-lab export" || ctx.command === "starter recover"
                 ? false : d.run_extension_migrations ?? true,
             enforce_mandatory_migration_gate: d.enforce_mandatory_migration_gate ?? false,
         };
@@ -1150,7 +1023,7 @@ function setupFlags(api) {
 const defineExtension = (module) => module;
 export default defineExtension({
     name: "pm-starter",
-    version: "2026.10.25",
+    version: "2026.10.27",
     activate(api) {
         // Register every capability group. Each helper is defensive enough to be
         // safely deleted when you fork this scaffold for a real extension.