@unbrained/pm-cli 2026.9.4 → 2026.9.5

package/dist/sdk/runtime-primitives.js

@@ -7,7 +7,7 @@
  * prefer the typed operations exported by the main SDK barrel.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="aba5403c-0694-5c51-95a8-ae7e7575347b")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="619b20e3-78d9-55bd-9d2d-857a3bc1bee8")}catch(e){}}();
 export { createCheckpointId, loadMutationCheckpoint, restoreCheckpointItems, writeMutationCheckpoint, } from "../core/checkpoint/mutation-checkpoint.js";
 export { flattenFlagListValue, resolveFlagValueKind, } from "../core/extensions/flag-value-types.js";
 export { createUnknownSubcommandError, } from "./agent/subcommand-recovery.js";
@@ -36,7 +36,7 @@ export { isTerminalStatus, normalizeStatusForRegistry, normalizeStatusInput, } f
 export { COMMON_MUTATION_COMMAND_OPTION_KEYS, canonicalizeCommandOptionKey, commandOptionFlagLabel, resolveCommandOptionPolicyState, resolveItemTypeRegistry, resolveTypeDefinition, resolveTypeName, validateTypeOptions, } from "../core/item/type-registry.js";
 export { resolveTypeSynonym } from "../core/item/type-synonyms.js";
 export { acquireLock } from "../core/lock/lock.js";
-export { printError, printResult, writeStdout } from "../core/output/output.js";
+export { printError, printResult, writeStderr, writeStdout } from "../core/output/output.js";
 export { renderRowsAsCsv, renderRowsAsTable } from "../core/output/tabular.js";
 export { parseLimit } from "../core/shared/numeric-parsers.js";
 export { resolveConfiguredPmPackageRoot, resolvePmCliVersion, resolvePmPackageRootFromModule, } from "../core/packages/root.js";
@@ -82,4 +82,4 @@ export { maybeRunFirstUseTelemetryPrompt } from "../core/telemetry/consent.js";
 export { deriveTelemetryCommandResolution, } from "../core/telemetry/observability.js";
 export { emitTelemetryErrorEvent, finishTelemetryCommand, startTelemetryCommand, } from "../core/telemetry/runtime.js";
 //# sourceMappingURL=runtime-primitives.js.map
-//# debugId=aba5403c-0694-5c51-95a8-ae7e7575347b
+//# debugId=619b20e3-78d9-55bd-9d2d-857a3bc1bee8

package/dist/types.d.ts

@@ -428,6 +428,8 @@ export interface ItemTypeDefinition {
     description?: string;
     /** Status assigned to newly created items of this type when `--status` is not provided. Falls back to the workflow's open status when unset or invalid. */
     default_status?: string;
+    /** Agent work can be dispatched automatically; human work needs a decision, and gates track outcomes. Omission inherits the built-in role or defaults custom types to agent work. */
+    execution_role?: "agent" | "human" | "gate";
     /** Value that configures or reports folder for this contract. */
     folder?: string;
     /** Value that configures or reports aliases for this contract. */

package/dist/types.js

@@ -5,7 +5,7 @@
  */
 /** Supported values accepted by the builtin item type contract. */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="4ee067ac-f28d-5411-9ac7-c92112384a64")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="8173bdb0-39c8-56c0-85c2-5c39f5c213cc")}catch(e){}}();
 export const BUILTIN_ITEM_TYPE_VALUES = [
     "Epic",
     "Feature",
@@ -243,4 +243,4 @@ export const CONTEXT_SECTION_VALUES = [
     "tests",
 ];
 //# sourceMappingURL=types.js.map
-//# debugId=4ee067ac-f28d-5411-9ac7-c92112384a64
+//# debugId=8173bdb0-39c8-56c0-85c2-5c39f5c213cc

package/docs/AGENT_GUIDE.md

@@ -195,6 +195,32 @@ post-merge observations on GitHub without changing repository state when no
 tracked closeout update is required. See [Releasing](RELEASING.md#reviewed-delivery-closeout)
 for the release contract.
 
+## Review and Analyzer Proof
+
+Use the [review helper](../scripts/reviews/pr-review-loop.mjs) to wait for
+terminal checks, then inspect its paginated inventory of comments, reviews,
+inline threads, edits, reactions, and resolution state. Inspect failed-check
+details in the receipt even when the helper itself exits successfully.
+
+```bash
+node scripts/reviews/pr-review-loop.mjs watch --pr <number> --repo unbraind/pm-cli --interval 60
+node scripts/release/hosted-analysis-gate.mjs --repo unbraind/pm-cli --sha <full-40-character-head-sha> --json
+```
+
+Both receipts must pass for the exact current head before merge. A successful
+CodeFactor check can still contain a notice: the stricter analyzer gate requires
+zero outstanding annotations and verifies DeepScan plus branch protection.
+Do not substitute a green check conclusion for that proof. This escape and its
+correction are recorded in [pm-08mt4k](../.agents/pm/issues/pm-08mt4k.toon).
+
+Use the helper's `acknowledge-inline` operation for actionable inline findings
+and `acknowledge` for top-level comments or review summaries. Rate valid feedback
+positively and explain false or stale findings on their actual review surface.
+After each push, request the reviewers again and wait for terminal results;
+provider quota or skipped reviews are limitations, not approvals. Before merge,
+run `inventory` once more to catch new or edited feedback, and require all
+findings to have an explicit disposition.
+
 ## Documentation Rules for Agents
 
 - Keep [README](../README.md) short.
@@ -205,6 +231,16 @@ for the release contract.
 - Link docs back to the active item with `pm docs`.
 - Do not link public docs to ignored local operations artifacts or private evidence logs.
 
+## Scheduling and Handoff
+
+Read [SDK execution contracts](SDK_EXECUTION_CONTRACTS.md) before building an
+agent work allocator. Use `next` and `claim --next` for executable work; inspect
+`decision_needed`, `gate_needed`, and `containers` when no recommendation is
+available. Only opt into those buckets when the current task calls for them.
+Use `pause-task` to stop work; `release` alone preserves in-progress status.
+Context summary totals describe the matching population, while `returned_focus`
+describes the bounded selection.
+
 ## Safe Defaults
 
 Use these defaults unless the task requires otherwise:

package/docs/HISTORY_RECOVERY.md

@@ -0,0 +1,146 @@
+# History durability and recovery
+
+Tracked by [pm-96fsma](../.agents/pm/issues/pm-96fsma.toon),
+[pm-m0yjtg](../.agents/pm/issues/pm-m0yjtg.toon),
+[pm-qw1uw6](../.agents/pm/issues/pm-qw1uw6.toon),
+[pm-e3gn0z](../.agents/pm/issues/pm-e3gn0z.toon), and
+[pm-wlqxg3](../.agents/pm/tasks/pm-wlqxg3.toon).
+
+Project management depends on trustworthy context. History is not just an
+activity feed: it is the reconstructable source for prior item states, including
+their evidence, relationships, and lifecycle transitions. Recovery must not
+manufacture missing context or silently change an item's identity.
+
+## Stable addresses after compaction
+
+`pm get <id> --at <version>` and `pm restore <id> <version>` use durable,
+one-based version addresses. Compaction checkpoints the last compacted state
+at its original version. Retained entries keep their addresses, including after
+repeated compactions. Versions before the checkpoint fail with
+`history_version_pruned`; they never select a different retained entry.
+
+The checkpoint records `history_compaction.version_offset`. Add that offset to
+a physical one-based stream position to obtain its durable version. `pm history`
+reports `version_addressing`, and compact rows include their `version` alongside
+the physical `index`. Verification error ordinals and diff indices remain
+physical positions in the current stream. The checkpoint timestamp is the last
+compacted entry's timestamp; the maintenance audit event records compaction time.
+
+Legacy checkpoints without a recorded offset cannot prove their original
+numeric addresses. Numeric reads fail with `history_version_mapping_unavailable`.
+Use a retained timestamp instead; the SDK then returns `as_of_version: null`.
+SDK consumers must handle this nullable value. `target.historyIndex` is always
+the resolved physical zero-based position, not an original version number.
+Default and timestamp-based compaction remain available for these legacy
+streams. They preserve an unknown offset as `null`, including no-op results;
+compaction never manufactures a numeric mapping from physical positions.
+
+## Recover an unreadable item file
+
+```bash
+pm history <id> --full
+pm restore <id> <version>
+pm history <id> --verify --strict-exit
+```
+
+Restore accepts an absent file or an unparsable item document when intact
+history can reconstruct it. It verifies the history before using the recovered
+state, preserves the original unreadable bytes for rollback, and uses the normal
+ownership and lock checks. Successful recovery reports
+`restore_unreadable_item_recovered`. Permission errors and unresolved merge
+conflicts are not treated as missing files. A missing initial baseline returns
+`history_baseline_unavailable` with recovery guidance rather than inventing
+metadata from a partial patch.
+
+CLI shape errors name the item ID, file path, and zero-length files. The SDK
+error context also includes byte length and an explicit empty-file flag.
+`pm health --check-only` names malformed item paths and invalid
+history lines without mutating either file; use those diagnostics to select the
+specific recovery operation above.
+
+Invalid UTF-8 is a separate refusal (`item_document_encoding_invalid`), not a
+recoverable text parse failure. Preserve a binary backup before recovering such
+a file; text decoding must never silently replace original bytes.
+Its SDK error context identifies the item ID, path, byte length, and nonempty
+state just as text-shape diagnostics do.
+
+## Recover an invalid history tail
+
+Keep a local backup before applying destructive history maintenance. Preview
+exactly one stream, inspect the receipt, then explicitly apply:
+
+```bash
+pm history-repair <id> --salvage-tail --dry-run --json
+pm history-repair <id> --salvage-tail --json
+pm history <id> --verify --strict-exit
+```
+
+Salvage requires a nonempty, hash-verified prefix and retains its bytes unchanged.
+The receipt records the first invalid physical line, discarded UTF-8 byte count,
+discarded-suffix SHA-256, and retained record count. An appended `history_salvage`
+event records that receipt without copying potentially private damaged contents.
+Salvage does not rehash prior entries, reconcile item state, or normalize
+provenance. It refuses bulk selection, conflicting repair modes, merge conflict
+markers, parseable records after corruption, and potentially complete records
+with attached corruption. Recover those cases from version control or a backup.
+Non-UTF-8 streams are also refused, so receipt hashes and rollback snapshots
+always describe the original bytes rather than a lossy decoded approximation.
+
+The public SDK uses the same operation:
+
+```ts
+import { PmClient } from "@unbrained/pm-cli";
+
+const client = new PmClient({ pmRoot: "/project/.agents/pm" });
+const preview = await client.historyRepair("pm-example", {
+  salvageTail: true,
+  dryRun: true,
+});
+console.log(preview.salvage);
+```
+
+The CLI and MCP expose this SDK-owned contract; package authors do not need a
+separate recovery implementation.
+
+## Permanent item identities
+
+Deleting an item retains its identity reservation through its history file.
+Generated IDs skip those reservations, even under reproducible execution.
+Explicit recreation fails with `item_identity_reserved`; use restore to recover
+the original subject, or create a new ID for unrelated work.
+The first `create` append exclusively creates its effective history file, so
+concurrent SDK callers and extension redirects cannot both reserve it. A failed
+partial first write keeps the reservation for diagnosis; it is never deleted
+to make the identity reusable. Subsequent large-record appenders still need the
+normal item lock or an equivalent caller-owned serialization boundary.
+
+Verification refuses a second `create` event, including one imported through
+branch union, and names both physical ordinals. Point-in-time reads cannot cross
+that discontinuity silently. Recover the original streams rather than rehashing
+two unrelated subjects into a single supposedly valid item.
+
+`pm validate --check-history-drift` reports this as an error, with item ID,
+original and repeated genesis ordinals, and the observed sequence. The public
+`findHistoryIdentityDiscontinuities` SDK primitive provides the same evidence
+for importers. A delete followed by create is distinguished from multiple creates
+or a checkpoint followed by create; these observations do not prove which
+writer or branch introduced the records. Old drift caches are invalidated, and
+known-invalid streams are reread even in metadata-cache mode.
+
+## Regression verification
+
+```bash
+node scripts/run-tests.mjs test -- tests/integration/history-durability.integration.spec.ts
+node scripts/run-tests.mjs test -- tests/integration/history-maintenance-replay.integration.spec.ts
+```
+
+The fixture drives real CLI lifecycle mutations, independently captures each
+serialized state, removes the live item file, and compares every addressable
+version against those captures. Companion cases exercise repeated compaction,
+legacy mapping refusal, seeded identity reuse, invalid-tail preservation,
+unreadable-file recovery, and missing baselines. Maintenance fixtures additionally
+perform redaction and a real divergent Git merge, compare every version with an
+independent strict patch fold, and compare the final state with a separately
+read item. Concurrent writes and binary corruption are negative controls, not
+mocked successful outcomes. All fixtures use temporary trackers, never repository
+tracker data.

package/docs/README.md

@@ -81,6 +81,7 @@ pm guide release --json
 - [Extension Lifecycle Contracts](EXTENSION_LIFECYCLE.md) - source identity, durable migrations, and scoped preflight ownership.
 - [Extension Author Contracts](EXTENSION_AUTHOR_CONTRACTS.md) - the stability guarantees and contract surface package authors build against.
 - [SDK](SDK.md) - public import surfaces and typed authoring examples.
+- [SDK execution and recovery contracts](SDK_EXECUTION_CONTRACTS.md): schema-driven scheduling, handoff, and command recovery.
 - [Multi-Branch Merge Safety](MERGE_SAFETY.md) - semantic tracker merge drivers, post-merge integrity gates, delete/modify policy, and recovery-receipt retention.
 - [Codex Plugin](CODEX_PLUGIN.md) - native MCP plugin install, tools, skills, and safety notes.
 - [Native ChatGPT and Codex Plugin Implementation Plan](CHATGPT_CODEX_PLUGIN_IMPLEMENTATION.md) - official-source

package/docs/RELEASING.md

@@ -30,7 +30,10 @@ authoritative blocker-recovery run selection by
 [pm-db8onn](../.agents/pm/issues/pm-db8onn.toon), and queued automatic
 same-day recovery by [pm-dm2vfz](../.agents/pm/issues/pm-dm2vfz.toon).
 Bounded Sentry request latency is tracked by
-[pm-b9g2cs](../.agents/pm/issues/pm-b9g2cs.toon).
+[pm-b9g2cs](../.agents/pm/issues/pm-b9g2cs.toon), and exact-tag changelog
+stabilization by [pm-e63v1x](../.agents/pm/issues/pm-e63v1x.toon). Dual-phase
+package sizing around Sentry injection is tracked by
+[pm-llbnua](../.agents/pm/issues/pm-llbnua.toon).
 
 ## Version Policy
 
@@ -333,7 +336,12 @@ The static phase includes `pnpm sdk:surface:check`,
 `pnpm benchmark:transport:check`. The packaging phase runs
 `pnpm quality:package-artifact`, which evaluates npm's actual packlist against
 the committed unpacked-size, file-count, required-runtime-file, and forbidden
-source-map budgets. Additive SDK exports require a reviewed
+source-map budgets. Release additionally reruns the packlist gate immediately
+after Sentry debug-ID injection and before any Sentry upload or finalization,
+using the separately committed `sentry-injected` ceiling. CI constrains the base
+build, publication constrains the exact mutated artifact users install, and a
+rejected package cannot leave finalized observability artifacts. Additive SDK
+exports require a reviewed
 snapshot refresh. A removal or semantic signature change fails until the
 maintainer supplies
 `pnpm sdk:surface:update -- --acknowledge-breaking "<release rationale>"`;
@@ -353,23 +361,27 @@ git push origin v<version>
 `.github/workflows/release.yml` runs on `v*.*.*` tags and handles:
 
 - full-history checkout
-- manual `workflow_dispatch` by tag for recovery. An isolated anonymous exact-version probe keeps already-published recovery on the reviewed dispatch-time `main` source; when the immutable tag exists but npm publication never completed, recovery checks out that exact tagged source and retains the original version guard
+- manual `workflow_dispatch` by tag for recovery. An isolated anonymous exact-version probe keeps already-published recovery on the reviewed dispatch-time `main` source; when the immutable tag exists but npm publication never completed, recovery preserves the reviewed package gate and budget in runner-temporary storage before checking out that exact tagged source. The controls inspect the untouched tagged package without becoming part of it, so recovery applies the current fail-closed distribution policy while retaining the original version guard and immutable package bytes.
 - pnpm install with frozen lockfile
 - version policy and tag guard
 - secret scan
 - build, clone-local merge-driver installation, typecheck, test, and coverage
 - generated changelog verification and `pm-changelog` installation before the
   tracker-bearing static gate, so a clean checkout does not misclassify the
-  managed extension's linked files as missing. Recovery of an unpublished
-  immutable tag regenerates only `CHANGELOG.md` with the tagged checkout's
-  canonical package script and fails if that operation changes any other
-  tracked source path (apart from managed-extension install metadata).
+  managed extension's linked files as missing. Every exact-tag source,
+  including an ordinary tag push and recovery of an unpublished immutable tag,
+  regenerates only `CHANGELOG.md` with the tagged checkout's canonical package
+  script and fails if that operation changes any other tracked source path
+  (apart from managed-extension install metadata). Reviewed `main` recovery
+  sources retain the non-mutating drift check.
 - static quality gate (shared complexity, duplication, dead/orphan module, file/folder hygiene, source/exported docstring coverage profile)
 - temporary-project compatibility gate against latest published tracker data
 - reliability threshold gate (Sentry severity threshold, bounded to a recent-activity window via `--sentry-window-days` (default `14`, `0` = unbounded) so a stale benign unresolved issue cannot block every scheduled release; Sentry requests use the fail-closed bounded `--sentry-request-timeout-ms` contract (default `120000`, maximum `300000`); `--telemetry-mode` gate policy: `off` | `best-effort` | `required`). Scheduled `auto-release.yml` failures open/update an `Auto Release blocked` GitHub issue so blocked daily releases are never silently skipped.
 - sandboxed `pm` coverage
-- optional Sentry release metadata and sourcemap upload when `SENTRY_AUTH_TOKEN` is configured
-- npm pack dry run and npx tarball smoke test
+- a base npm pack dry run, optional Sentry debug-ID injection, a second
+  `sentry-injected` packlist budget over the exact publishable bytes, and only
+  then optional Sentry release metadata/upload/finalization and the npx tarball
+  smoke test
 - generated release notes from changelog plus sanitized tracker metadata
 - artifact uploads
 - `npm publish --access public --provenance --tag latest`, skipped on retry
@@ -458,8 +470,10 @@ Use the npm registry package for maintainer global updates. Do not use `npm inst
   the existing immutable tag, reapplies the version guard, installs the managed
   changelog extension, regenerates the package changelog with the tagged
   checkout's canonical policy under a tracked-path mutation guard, and permits
-  first publication only from that tagged source. Other registry failures stop
-  before source selection or publication.
+  first publication only from that tagged source. Ordinary tag-push releases
+  use the same guarded regeneration because their tag did not exist when the
+  release commit's changelog was prepared. Other registry failures stop before
+  source selection or publication.
 - If an immutable published package contains a defect that cannot be repaired
   by rerunning the same tag workflow, document the incident and ship the code
   fix in the next UTC day's release.

package/docs/SDK_CONTEXT_TRUTH_CONTRACTS.md

@@ -1,7 +1,9 @@
 # SDK Context Truth Contracts
 
 Tracker references: [pm-23xkss](../.agents/pm/issues/pm-23xkss.toon) and
-[pm-r8u2g6](../.agents/pm/issues/pm-r8u2g6.toon).
+[pm-r8u2g6](../.agents/pm/issues/pm-r8u2g6.toon),
+[pm-79gv6q](../.agents/pm/issues/pm-79gv6q.toon), and
+[pm-08mt4k](../.agents/pm/issues/pm-08mt4k.toon).
 
 ## Agent Quick Context
 
@@ -68,3 +70,24 @@ silently route tracker files through the wrong merge behavior. Run
 This policy does not weaken storage, history, merge-fence, or pending-receipt
 checks. It only distinguishes an optional never-installed clone capability
 from a broken capability that the repository appears to rely on.
+
+## Population and Focus Are Separate
+
+`context.summary.scope` is `matching_items`: lifecycle totals describe all items
+matching the request filters and parent subtree before the focus limit, intent
+projection, and token packing. Without filters this is the workspace population.
+`active_items`, `in_progress`, `open`, and `blocked` use that same population as
+`total_items`, `closed`, and `canceled`. `open` includes active statuses other than
+in-progress; `blocked` is an overlapping classification that includes unresolved
+dependency edges as well as blocked lifecycle states.
+
+`summary.returned_focus` reports the bounded focus selection. The existing
+`high_level` and `low_level` counts describe their emitted rows. An orient or
+handoff response limited to one row can therefore still report hundreds of open
+items. `omission_receipt.summary_scope` repeats `matching_items` so a consumer
+reading projection metadata cannot confuse omitted detail with absent work.
+
+Never infer a population count from an array length. To visit individual items,
+follow the response's continuation and omission receipts. To schedule work, use
+the shared [execution contracts](SDK_EXECUTION_CONTRACTS.md), which keep human
+input, gates, and containers visible without dispatching them by default.

package/docs/SDK_EXECUTION_CONTRACTS.md

@@ -0,0 +1,105 @@
+# SDK Execution and Recovery Contracts
+
+Tracker references: [pm-08mt4k](../.agents/pm/issues/pm-08mt4k.toon),
+[pm-ugld](../.agents/pm/issues/pm-ugld.toon),
+[pm-2bqgs7](../.agents/pm/issues/pm-2bqgs7.toon),
+[pm-u4t9gp](../.agents/pm/issues/pm-u4t9gp.toon), and
+[pm-bfa1ob](../.agents/pm/issues/pm-bfa1ob.toon).
+
+## Declare Who Can Execute a Type
+
+Custom settings definitions and package `defineItemType` definitions accept
+`execution_role: "agent" | "human" | "gate"`. An omitted role defaults to agent
+execution; built-in Decision and Milestone types default to human and gate,
+respectively. A definition can override a built-in role. Aliases resolve through
+the type registry, and invalid roles are rejected rather than silently enabling
+execution.
+
+Package authors can declare a review checkpoint alongside the rest of their item
+type definition:
+
+```ts
+import { defineItemType } from "@unbrained/pm-cli/sdk/authoring";
+
+export const checkpoint = defineItemType({
+  name: "Checkpoint",
+  folder: "checkpoints",
+  aliases: ["checkpoint"],
+  execution_role: "gate",
+});
+```
+
+`computeActionabilityReport` is the pure SDK primitive: it accepts candidates,
+the surrounding item corpus, a status registry, and an optional item type
+registry. It resolves both forward `blocked_by` and reverse `blocks` edges,
+terminal prerequisites, active descendants, and execution roles. Its result
+contains ready leaves, blocked leaves, human decisions, gates, and containers.
+`selectActionableEntries` applies explicit dispatch opt-ins to that report;
+ownership and ranking remain the responsibility of the caller. The selector
+returns `ready`, `decisions`, and `gates`: eligible opted-in containers enter
+`ready`, subject to their execution role. Read `report.containers` for the full
+classified container worklist; the selector does not return a separate
+`containers` property.
+
+Integrations that construct an `ActionabilityReport` themselves must now provide
+the `containers`, `decisions`, and `gates` arrays. Prefer computing the report
+through the SDK so these classifications stay consistent with dependency and
+schema rules. Existing callers may omit the new selection options and type
+registry argument.
+
+## Read Every Scheduling Bucket
+
+`pm next` exposes `ready`, `decision_needed`, `gate_needed`, `containers`,
+`blocked`, and `held_by_others`. Summary counts describe the full matching
+buckets; each bounded worklist has truncation totals when needed. The row
+contract advertises the new gate and container collections to generic consumers.
+Intent budgets compact these worklists along with the other scheduling rows.
+Final-delivery feedback records their visible identifiers so recursive context
+improvement observes what the caller actually received.
+A workspace containing only outcome gates returns no recommendation and explains
+how to inspect or explicitly include gates.
+
+`--include-decisions`, `--include-gates`, and `--include-containers` opt into
+held-out work for both `next` and `claim --next`. The SDK and MCP use
+`includeDecisions`, `includeGates`, and `includeContainers`. These options do not
+bypass unresolved blockers, blocked lifecycle states, or ownership checks.
+Context places gates, human work, and containers in high-level context rather
+than agent execution detail. Population summaries retain all matching work.
+
+## Stop Work Explicitly
+
+`release` relinquishes ownership and preserves status. When an in-progress item
+is released (using the configured workflow status), its result includes `released_unclaimed_in_progress` and a concrete
+`pm pause-task <id>` suggestion. Use `pause-task` when the intended operation is
+to stop work and return it to the configured open state. Consumers should not
+interpret an ownership release as evidence that work has stopped.
+
+## Recover from Command Mistakes
+
+Unknown commands direct the caller to `pm --help --all`, the complete core
+command surface. `pm tests <id>` is an executable alias of `pm test <id>`.
+Positional item operands are accepted in help requests, including hybrid
+commands such as `pm files <id> --help --json`; invalid child command names still
+produce usage errors.
+
+With `--token-accounting`, JSON refusals carry the same serialized-output
+accounting used by successful commands. Accounting is attached after diagnostic
+projection and recalculated if extension failures enrich the refusal. The
+receipt measures the emitted diagnostic, including its own receipt overhead.
+Recovery metadata retains the actual invocation, including the accounting flag.
+The executable transcript gate predicts that transport change independently and
+rejects any other payload drift. It also verifies that the accounting-off
+attempted command agrees with its normalized arguments before projection.
+Detailed recovery evidence must contain argument and provided-field arrays.
+Compact recovery is accepted only when the transcript explicitly declares and
+verifies that mode; its advertised retry still executes as a separate step.
+Serialized JSON refusals use the SDK `writeStderr` transport primitive so an
+`error_format` text override cannot replace a measured machine payload.
+Human-readable error formatting remains customizable through `error_format`.
+
+The flag-invocation gate compares registered executable options against SDK
+contracts without filtering out undeclared observations. An option missing from
+the contract and a root command missing a resolver both fail the gate. A seeded
+undeclared option is a mandatory negative control. Contract snapshots, MCP
+parameter declarations, help, and completion are regenerated from the shared
+contract tables.

package/docs/TESTING.md

@@ -146,6 +146,11 @@ boilerplate summaries are rejected.
 
 ## TOON Storage Round-Trip Gate
 
+History-only lifecycle reconstruction and recovery contracts are described in
+[History durability and recovery](HISTORY_RECOVERY.md). Their integration suite
+is part of the required all-source test run and compares historical projections
+against independently captured item files, including after removing those files.
+
 TOON item serialization is a fail-closed storage boundary. Before returning
 bytes to any create, update, merge, migration, or package caller, pm decodes the
 new `@toon-format/toon` output and compares it with the JSON-like canonical

package/docs/agent-task-token-baseline.json

@@ -1,7 +1,7 @@
 {
   "version": 4,
   "transcript_version": 2,
-  "transcript_digest": "sha256:4f9e96bb6ce12bbbeb2514e4bd5958d201c4e62e95083bcbebd749d1e48cc82d",
+  "transcript_digest": "sha256:b8a6aea318c41e6a40dbcaf8094da8397ca747515a7df249d35c1f21ad94a307",
   "estimator": "ceil(utf8_bytes / 4)",
   "measurement_scope": "output_before_token_accounting",
   "published_with_release": true,
@@ -12,12 +12,12 @@
       "active_ownership",
       "workspace_state"
     ],
-    "measured_winner_tokens": 1055,
+    "measured_winner_tokens": 1102,
     "protocols": [
       {
         "task_id": "orientation-context-intent",
         "command_count": 1,
-        "estimated_tokens": 1055,
+        "estimated_tokens": 1102,
         "capabilities": [
           "actionable_work",
           "active_ownership",
@@ -47,7 +47,7 @@
       {
         "task_id": "orientation-operating-rules",
         "command_count": 4,
-        "estimated_tokens": 2293,
+        "estimated_tokens": 2340,
         "capabilities": [
           "actionable_work",
           "active_ownership",
@@ -77,7 +77,7 @@
       {
         "task_id": "orientation-contracts-next",
         "command_count": 2,
-        "estimated_tokens": 4798,
+        "estimated_tokens": 4829,
         "capabilities": [
           "actionable_work",
           "active_ownership",
@@ -109,18 +109,18 @@
   "tasks": [
     {
       "id": "orientation-context-intent",
-      "max_estimated_tokens": 1055,
+      "max_estimated_tokens": 1102,
       "steps": [
         {
           "id": "context",
-          "max_estimated_tokens": 1055,
+          "max_estimated_tokens": 1102,
           "accounting_mode": "self_reported"
         }
       ]
     },
     {
       "id": "orientation-contracts-next",
-      "max_estimated_tokens": 4798,
+      "max_estimated_tokens": 4829,
       "steps": [
         {
           "id": "contracts",
@@ -129,18 +129,18 @@
         },
         {
           "id": "next",
-          "max_estimated_tokens": 687,
+          "max_estimated_tokens": 718,
           "accounting_mode": "self_reported"
         }
       ]
     },
     {
       "id": "orientation-operating-rules",
-      "max_estimated_tokens": 2293,
+      "max_estimated_tokens": 2340,
       "steps": [
         {
           "id": "context",
-          "max_estimated_tokens": 1055,
+          "max_estimated_tokens": 1102,
           "accounting_mode": "self_reported"
         },
         {
@@ -162,7 +162,7 @@
     },
     {
       "id": "context-bootstrap",
-      "max_estimated_tokens": 1978,
+      "max_estimated_tokens": 2025,
       "steps": [
         {
           "id": "triage",
@@ -171,7 +171,7 @@
         },
         {
           "id": "orient",
-          "max_estimated_tokens": 1055,
+          "max_estimated_tokens": 1102,
           "accounting_mode": "self_reported"
         },
         {
@@ -199,12 +199,12 @@
     },
     {
       "id": "unknown-option-recovery",
-      "max_estimated_tokens": 585,
+      "max_estimated_tokens": 603,
       "steps": [
         {
           "id": "refuse-option",
-          "max_estimated_tokens": 422,
-          "accounting_mode": "independent_transport"
+          "max_estimated_tokens": 440,
+          "accounting_mode": "self_reported"
         },
         {
           "id": "retry-option",
@@ -261,5 +261,5 @@
       ]
     }
   ],
-  "composite_max_estimated_tokens": 12477
+  "composite_max_estimated_tokens": 12667
 }

package/docs/agent-task-transcripts.json

@@ -186,6 +186,7 @@
           "expected_accounting_mode": "self_reported",
           "required_fields": ["code", "refusal", "recovery"],
           "expected_error_code": "unknown_context_intent",
+          "expected_field_values": { "recovery.recovery_mode": "compact" },
           "expected_refusal_surface": "--for"
         },
         {
@@ -216,7 +217,7 @@
           ],
           "expected_exit_code": 2,
           "expected_output_kind": "refusal",
-          "expected_accounting_mode": "independent_transport",
+          "expected_accounting_mode": "self_reported",
           "required_fields": ["code", "refusal", "recovery"],
           "expected_error_code": "unknown_option",
           "expected_refusal_surface": "--include-body"