@unbrained/pm-cli 2026.9.2 → 2026.9.4

package/docs/MERGE_SAFETY.md

@@ -5,7 +5,19 @@ Tracked by [pm-wc1r](../.agents/pm/features/pm-wc1r.toon), with the integrity an
 Lossless receipt health gating is tracked by
 [pm-baksix](../.agents/pm/issues/pm-baksix.toon), and executable remediation
 that performs settlement is tracked by
-[pm-r0p3at](../.agents/pm/issues/pm-r0p3at.toon).
+[pm-r0p3at](../.agents/pm/issues/pm-r0p3at.toon). Immutable record sealing and
+retained re-anchor evidence are tracked by
+[pm-javbsq](../.agents/pm/issues/pm-javbsq.toon) and
+[pm-aka8m7](../.agents/pm/issues/pm-aka8m7.toon); preferred-era receipt-summary
+compatibility is tracked by
+[pm-wn3ee5](../.agents/pm/issues/pm-wn3ee5.toon).
+Lossless concurrent acceptance-criteria composition is tracked by
+[pm-inn5y5](../.agents/pm/issues/pm-inn5y5.toon).
+Recency-aware scalar convergence, bounded fresh-clone decision evidence, and
+audited pre-durable receipt dispositions are tracked by
+[pm-7wzb6d](../.agents/pm/issues/pm-7wzb6d.toon),
+[pm-mg13iz](../.agents/pm/issues/pm-mg13iz.toon), and
+[pm-cf4t42](../.agents/pm/issues/pm-cf4t42.toon).
 
 pm stores project context as reviewable repository files. Concurrent agents can therefore use ordinary branches and worktrees, but tracker artifacts need semantic merge behavior: raw line merging cannot preserve TOON collection counts, JSON object structure, or append-only history hash chains.
 
@@ -59,12 +71,12 @@ pm merge install --dry-run --json
 
 ## Artifact semantics
 
-| Artifact                                                         | Driver                              | Merge behavior                                                                                                                                                                                                                                          |
-| ---------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Item `.toon` / `.md`                                             | `pm-item-toon` / `pm-item-markdown` | Three-way field merge; append-like collections use set union, `updated_at` uses latest timestamp, scalar conflicts select a stable direction-independent value, and canonical serialization recomputes TOON counts.                                     |
-| `history/*.jsonl`                                                | `pm-history`                        | Preserves the common prefix and both divergent suffixes, orders deterministically, then re-anchors the resulting hash chain.                                                                                                                            |
-| tracker `**/*.jsonl` except the later `history/*.jsonl` override | `pm-relationship`                   | Covers default and package-owned custom relationship event paths, unions divergent suffixes by `eventId` (timestamp-ordered, ours-first on ties), and renumbers `sequence` consecutively so the strict-sequence store loader accepts the merged stream. |
-| root `settings.json` and nested `**/*.json`                      | `pm-json`                           | Recursively merges objects per key. Arrays compose when both branches preserve the base and add distinct entries, so independent extension installs and evaluation additions merge without weakening edit/removal conflict detection.                   |
+| Artifact                                                         | Driver                              | Merge behavior                                                                                                                                                                                                                                                                      |
+| ---------------------------------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Item `.toon` / `.md`                                             | `pm-item-toon` / `pm-item-markdown` | Three-way field merge; append-like collections use set union, `updated_at` uses the latest timestamp, scalar conflicts select the value from the later document update with stable value order as an equal-timestamp tie-break, and canonical serialization recomputes TOON counts. |
+| `history/*.jsonl`                                                | `pm-history`                        | Preserves the common prefix and both divergent suffixes, orders deterministically, then re-anchors the resulting hash chain.                                                                                                                                                        |
+| tracker `**/*.jsonl` except the later `history/*.jsonl` override | `pm-relationship`                   | Covers default and package-owned custom relationship event paths, unions divergent suffixes by `eventId` (timestamp-ordered, ours-first on ties), and renumbers `sequence` consecutively so the strict-sequence store loader accepts the merged stream.                             |
+| root `settings.json` and nested `**/*.json`                      | `pm-json`                           | Recursively merges objects per key. Arrays compose when both branches preserve the base and add distinct entries, so independent extension installs and evaluation additions merge without weakening edit/removal conflict detection.                                               |
 
 The `tests` collection has an additional execution-safety rule. Its semantic
 identity excludes provenance so the same command/context does not duplicate
@@ -80,17 +92,50 @@ boundary for append-like data that becomes executable after a merge; ordinary
 notes, files, and other non-executable collections retain normal set-union
 behavior.
 
-When both sides change the same item scalar differently, the driver writes the same stable value regardless of which branch Git labels ours or theirs, but exits nonzero. Item results and receipts expose the caller's `requested_preference`; the per-decision `retained` and `discarded` values or hashes are authoritative because stable value order can retain either side. Readers normalize the legacy receipt key `preferred`, while new receipts no longer emit it. JSON leaf conflicts retain the explicit preferred-side policy. Git keeps either path conflicted so a human or coordinating agent must review the discarded value and explicitly `git add` the resolution. This correction is tracked by [pm-qckpnq](../.agents/pm/issues/pm-qckpnq.toon).
+Although `acceptance_criteria` is serialized as a semicolon-delimited scalar
+for backward compatibility, the item driver treats its parsed criteria as a
+collection. Independent additions compose in branch order, removals made by
+either side remain removed, the field is reported in `union_fields`, and a
+lossless merge does not create a scalar conflict decision. This gives repeated
+`pm update --add-ac` mutations the same multi-branch preservation guarantee as
+native append-like metadata without a storage migration.
+
+When both sides change the same item scalar differently, the driver retains the
+value from the document with the later `metadata.updated_at` timestamp. Equal
+timestamps fall back to stable value ordering, so reversing Git's ours/theirs
+labels still converges to the same result. Item results, driver results, and
+receipts expose `conflict_resolution: latest_document_update` and
+`requested_preference_applied: false`; each conflict decision adds
+`retained_side` and `resolution_basis` so review automation can distinguish a
+recency decision from the stable tie-break. The caller's
+`requested_preference` remains observable but does not override item scalar
+convergence. Readers continue to accept legacy `preferred_side` and
+`stable_value_order` receipts and normalize the legacy `preferred` key. JSON
+leaf conflicts retain their explicit preferred-side policy. Git keeps the item
+path conflicted so a human or coordinating agent must review the discarded
+value and explicitly `git add` the resolution.
+
+The exact object `{ "pm_item_scalar_missing": true }` is reserved for
+JSON-stable missing-value evidence. Item merge inputs reject that object as a
+present metadata value, while the hashing primitive independently separates
+present and missing domains. This prevents extension data from impersonating a
+deletion without wrapping every ordinary scalar in receipt output.
 
 The driver result's `guidance` always points unresolved conflicts to `pm merge report`. When a clone-local receipt exists, guidance includes its privacy-safe receipt and item ids for exact correlation; discarded values remain confined to the local receipt and never appear in generic logs or tracker history. Tracked by [pm-fbrz7p](../.agents/pm/issues/pm-fbrz7p.toon).
 
 For item conflicts, the driver writes a clone-local receipt below the Git
 directory and a durable privacy-safe sidecar below `merge-receipts/` in the
 tracker. The local receipt contains retained and discarded values so recovery
-does not depend on a reflog. The tracked sidecar contains only field names and
-value hashes, so fresh clones and CI can still fail closed on an unreviewed
-decision without publishing either value. When both copies exist the SDK
-deduplicates them and prefers the locally recoverable copy:
+does not depend on a reflog. The tracked sidecar applies the versioned
+`bounded_non_sensitive_scalars_v1` policy. Built-in lifecycle statuses,
+priority integers from 0 through 4, bounded risk/confidence/severity ordinals,
+and `null` are stored with both their value and matching hash. All other values
+remain hash-only. `value_availability` distinguishes `bounded_inline`, `mixed`,
+and `hash_only`, while the clone-local receipt remains `clone_local`. This lets
+a fresh-clone reviewer recover ordinary control-plane decisions without
+publishing titles, descriptions, custom statuses, or other potentially private
+content. When both copies exist the SDK deduplicates them and prefers the
+locally recoverable copy:
 
 ```bash
 pm merge report
@@ -108,7 +153,9 @@ that distinction without returning malformed contents.
 loss-aware contract through `complete`, `invalid_evidence_count`, bounded
 `invalid_evidence[]`, `invalid_evidence_truncated`, and
 `clone_local_evidence_resolved`. Each rejected candidate reports a stable
-reason plus its `clone_local`, `durable`, or copy-consistency source. A safe
+reason plus its `clone_local`, `durable`, or copy-consistency source. Schema and
+identity failures additionally expose a bounded `validation_error` such as
+`required_fields`, `item_path`, `filename`, or `durable_decisions`. A safe
 receipt filename is returned as `receipt_id`; unsafe candidate names are
 represented only by `candidate_name_hash`, and malformed contents are never
 returned. The detail list is capped at 100 rows while the count remains exact,
@@ -118,13 +165,26 @@ POSIX instead of treating platform-specific `ENOENT`/`ENOTDIR` spellings as
 equivalent. Full health also cross-checks the privacy-safe receipt summaries in
 append-only history against valid pending and reconciled evidence. Missing
 evidence emits `merge_receipt_history_reference_missing:<n>` with bounded item,
-history-line, and receipt-id-or-hash coordinates. Its remediation enumerates
-the exact references and directs recovery from an authoritative clone or
-backup; it never recommends deleting receipts or rewriting history. The CLI
+history-line, and receipt-id-or-hash coordinates. Recover an available receipt
+from an authoritative clone or backup first. For an exact reference whose
+history-event timestamp predates tracked durable receipts, `pm merge reconcile
+--force` can append a `merge_reconcile` audit event containing the original
+item, line, receipt id, timestamp, and the closed
+`legacy_clone_local_only` reason. Health accepts only that exact coordinate and
+reports it through `accepted_missing_merge_receipt_dispositions`; it never
+rewrites or deletes the original history. The audit event must also occur after
+the referenced history line; an earlier event cannot pre-authorize a later
+missing receipt. Missing post-durable evidence remains blocking and cannot be
+dispositioned through this compatibility path. The CLI
 exits nonzero when evidence is incomplete, even when the valid-receipt count is
 zero. Current SDK implementations always emit the new field, while its optional
 type preserves structural compatibility for existing typed adapters and test
-fixtures. `runMergeReceiptReport` remains the compatible valid-only report.
+fixtures. A structurally valid preferred-era history summary that contains its
+complete privacy-safe receipt evidence is accepted in place: health counts it
+as `accepted_legacy_merge_receipt_references` and does not demand an external
+receipt file that the older writer never created. Incomplete, contradictory, or
+modern summaries still fail closed. `runMergeReceiptReport` remains the
+compatible valid-only report.
 
 ## Cross-branch id collision safety
 
@@ -165,7 +225,8 @@ Serialized source claims are ignored. Receipt readers validate the complete
 bounded schema, safe identifiers, filename and item-path identity, timestamps,
 and bounded decision structure before a sidecar enters health or
 reconciliation. Reads use size-preflighted, no-follow regular-file descriptors;
-durable decisions must retain hash-only values. Qualifying durable-only receipts
+durable decision values must conform to the declared bounded-inline policy or
+remain hash-only. Qualifying durable-only receipts
 are reloaded from the authoritative store and accepted only after exact canonical
 item path, declared-field, and merged-value hash verification. Legacy receipts,
 receipts whose declared fields disagree with their hashes, same-item tampering,
@@ -173,16 +234,19 @@ and drift on unrelated items fail closed to the normal `pm history-repair`
 guidance. Health indexes authoritative evidence once by item and reconciliation
 uses the same per-item groups with a fixed receipt-only worker pool, so committed
 sidecars cannot amplify drift scans into unbounded parallel repair work.
-The machine-executable remediation names the apply command because `--dry-run`
-returns a successful preview without changing the red health state. Operators
-may still run the documented dry-run first; agents that execute the remediation
-field verbatim perform the settlement instead of entering a successful no-op
-loop.
+The machine-executable remediation for a missing receipt reference names
+`pm merge reconcile --dry-run`. It never publishes `--force` as an executable
+hint: the human-readable summary explains that exact eligible pre-durable
+coordinates may be dispositioned by a separately reviewed force pass. Ordinary
+pending lossless receipts retain their unforced apply remediation.
 Apply-mode reconciliation repeats the same proof against the exact
 item snapshot used by the audited history rewrite. The audit event and
 settlement include only the individually proven receipt id, so one valid receipt
 cannot authorize an untrusted same-item sibling. Failed or unproven receipts
 remain pending unless the coordinator explicitly reviews and supplies `--force`.
+Snapshot verification accepts both the current presence-domain digest and the
+legacy version-1 scalar digest, so already-written receipts remain repairable;
+new receipts always use the collision-free presence-domain scheme.
 Receipts with discarded scalar values retain the distinct
 `merge_decisions_unreviewed:<n>` finding. Matching authoritative hash proof
 allows those receipts to settle without `--force`; without qualifying proof,
@@ -192,6 +256,15 @@ an unforced apply command that clears `merge_decisions_unreviewed` when the
 receipt proves the exact current merged values. This prevents routine repair
 from hiding unfinished reconciliation while avoiding redundant force for an
 already-proven canonical snapshot.
+The same `--force` boundary also handles an unrecoverable pre-durable
+clone-local-only history reference. Preview and apply results expose
+`missing_history_references_before`, `legacy_disposition_eligible`,
+`legacy_disposition_recorded`, and `missing_history_references_after`. When
+coordinates exceed the bounded health response, explicit result guidance
+requires repeated dry-run and reviewed force passes until health no longer
+reports truncated coordinate details and the remaining count is zero. An apply
+result cannot return `ok: true` while any missing reference or truncated
+evidence remains.
 It exits nonzero while either merge-critical validation check is non-green, so
 CI and explicit post-merge hooks cannot approve unresolved receipts or drift.
 The apply pass uses the audited history rewrite boundary to append a
@@ -233,6 +306,29 @@ keeps version incompatibility distinct from item corruption and is tracked by
 [pm-2htk4p](../.agents/pm/issues/pm-2htk4p.toon) and
 [pm-2qahia](../.agents/pm/issues/pm-2qahia.toon).
 
+New history events also carry `record_hash_version` and `record_hash`. Unlike
+the item anchors, the record hash covers the complete immutable event: author
+and agent provenance, timestamp, operation, message, context, patch, item-hash
+epoch, and before/after anchors. A record that carries only one envelope field,
+uses an unsupported record epoch, or changes after sealing fails verification.
+Entries created before this envelope remain readable as explicit
+`item_state_only` coverage; they are not presented as record-authenticated.
+
+Every maintenance rewrite verifies a present record hash before changing the
+stream and reseals the output. When anchors or patch representation change, the
+entry's append-only `reanchor_evidence` retains the prior anchors, item epoch,
+patch digest, and prior record envelope. Lenient repair additionally retains
+the complete replaced patch operations. `verifyHistoryRewriteEvidence()`
+reconstructs every available prior envelope and rejects a record that was
+modified and merely resealed after maintenance. Redaction never copies sensitive patch
+values into new evidence: it keeps the digest and drops a retained patch if the
+patch itself matched a redaction rule. Compaction baselines retain the pruned
+entry count and ordered stream digest plus an explicit
+`individual_pruned_entries_require_pre_compaction_stream` limitation. A holder
+of the pre-compaction stream can therefore validate the checkpoint, while the
+post-compaction stream does not falsely claim that it can reconstruct content
+that was intentionally pruned.
+
 ## Delete versus modify policy
 
 A delete on one branch and an edit on another is not safely resolvable by a generic file driver. The merged workspace must not silently resurrect the item. `storage_integrity` reports the live document plus delete-terminated history as a hard finding. The coordinator chooses one policy explicitly:

package/docs/PERFORMANCE.md

@@ -12,7 +12,7 @@ Every measured CLI and SDK operation targets:
 - default output at or below 5,000 estimated tokens;
 - no feature, flag, output, history, or validation loss.
 
-The committed regression budgets in [`scripts/bench/scale-budgets.json`](../scripts/bench/scale-budgets.json) protect the current baseline while the product targets stay fixed. Short local checks use the best observed latency as a regression floor; statistically meaningful runs of 20 or more use p95. Both receive 25% baseline headroom plus a 25 ms scheduler/filesystem noise margin. Reports always retain min/p50/p95, and product-target status always uses p95. This lets a busy workstation detect deterministic code slowdowns without pretending that three samples produce a meaningful p95 or hiding the real tail-latency target.
+The committed regression budgets in [`scripts/bench/scale-budgets.json`](../scripts/bench/scale-budgets.json) protect the current baseline while the product targets stay fixed. Baseline refreshes use the Node major pinned by release and primary CI workflows (currently Node 24); newer supported runtimes remain compatibility targets, but their startup and memory characteristics must not silently rewrite the release baseline. Short local checks use the best observed latency as a regression floor; statistically meaningful runs of 20 or more use p95. Both receive 25% baseline headroom plus a 25 ms scheduler/filesystem noise margin. Reports always retain min/p50/p95, and product-target status always uses p95. This lets a busy workstation detect deterministic code slowdowns without pretending that three samples produce a meaningful p95 or hiding the real tail-latency target.
 
 ## Reproducible fixtures
 
@@ -92,7 +92,10 @@ probe off and performs no query on the create path; advisory/strict modes reuse
 one dependency-light SDK scorer with the package-owned dedupe audit. Mutation
 history events use a separate rebuildable ordered SQLite projection so
 `pm events --since <cursor>` catch-up cost follows new history rows instead of
-workspace size. See [SDK Context Coordination](SDK_CONTEXT_COORDINATION.md).
+workspace size. Its v5 schema also indexes the declared substantive-versus-
+maintenance event class, allowing context recency to fetch only the latest
+substantive row per requested stream instead of folding complete histories on
+each read. See [SDK Context Coordination](SDK_CONTEXT_COORDINATION.md).
 
 SDK hosts that commit authoritative item documents outside the stock mutation
 commands use `acquireItemMetadataDerivedIndexLock` and
@@ -127,7 +130,7 @@ To refresh a baseline after an intentional, measured improvement:
 pnpm benchmark:scale --items ci --iterations 5 --transport both --update --headroom 1.25
 ```
 
-Review the report and budget diff together. Never update a budget merely to silence a regression.
+Review the report and budget diff together. Before a refresh, compare the delivery head with its exact base commit using the same runtime, fixture shape, and transport set; retain that evidence on the owning PM item. Never update a budget merely to silence a regression.
 
 ## Startup and observability
 

package/docs/README.md

@@ -63,6 +63,7 @@ pm guide release --json
 - [Mutation Integrity](MUTATION_INTEGRITY.md) - shared CLI/SDK/MCP author, secret, append-only disposition, and stale-work guardrails.
 - [Agent Provenance ADR Amendment](AGENT_PROVENANCE_ADR.md) - extensible model, effort, role, and host provenance with privacy and compatibility boundaries.
 - [SDK Agent Session and Episode Context](SDK_AGENT_SESSION_CONTEXT.md) - inherited role/topic context, cross-process episode identity, and deterministic history grouping.
+- [SDK Agent Environments](AGENT_ENVIRONMENTS.md) - calibrated observations, total verdicts, isolated episodes, and an executable public-SDK environment.
 - [Improvement Ledger and History Analytics](IMPROVEMENT_ANALYTICS.md) - audited quantitative observations, live provenance coverage, and bounded observational fleet outcomes.
 - [Project Assurance Primitives](ASSURANCE.md) - SDK-owned measurements, assertions, lifecycle gates, cost receipts, and durable verdict history shared by CLI and MCP.
 - [Defect Recurrence and Boundary Evidence](DEFECT_RECURRENCE.md) - captured external samples, structured defect-escape evidence, incremental change-risk indexing, and executable recovery-producer census.

package/docs/READ_OUTPUT_CONTRACTS.md

@@ -1,6 +1,6 @@
 # Universal Read Output Contracts
 
-Tracker references: [pm-hb7ug8](../.agents/pm/features/pm-hb7ug8.toon), [pm-cxr0jb](../.agents/pm/features/pm-cxr0jb.toon), [pm-hid9g1](../.agents/pm/features/pm-hid9g1.toon), [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon), [pm-5t33or](../.agents/pm/features/pm-5t33or.toon), [pm-srns](../.agents/pm/issues/pm-srns.toon), [pm-sb0tns](../.agents/pm/issues/pm-sb0tns.toon), [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon), [pm-eugaqy](../.agents/pm/issues/pm-eugaqy.toon), [pm-jt8aa2](../.agents/pm/issues/pm-jt8aa2.toon), [pm-kyjdne](../.agents/pm/issues/pm-kyjdne.toon), [pm-8nev0o](../.agents/pm/issues/pm-8nev0o.toon), [pm-oahhyc](../.agents/pm/issues/pm-oahhyc.toon), [pm-q4isdq](../.agents/pm/issues/pm-q4isdq.toon), [pm-e5gl05](../.agents/pm/issues/pm-e5gl05.toon), [pm-cha95z](../.agents/pm/tasks/pm-cha95z.toon), [pm-2qvq7a](../.agents/pm/issues/pm-2qvq7a.toon), and [pm-xam9bt](../.agents/pm/issues/pm-xam9bt.toon).
+Tracker references: [pm-hb7ug8](../.agents/pm/features/pm-hb7ug8.toon), [pm-cxr0jb](../.agents/pm/features/pm-cxr0jb.toon), [pm-hid9g1](../.agents/pm/features/pm-hid9g1.toon), [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon), [pm-5t33or](../.agents/pm/features/pm-5t33or.toon), [pm-wv47pf](../.agents/pm/issues/pm-wv47pf.toon), [pm-srns](../.agents/pm/issues/pm-srns.toon), [pm-sb0tns](../.agents/pm/issues/pm-sb0tns.toon), [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon), [pm-eugaqy](../.agents/pm/issues/pm-eugaqy.toon), [pm-jt8aa2](../.agents/pm/issues/pm-jt8aa2.toon), [pm-kyjdne](../.agents/pm/issues/pm-kyjdne.toon), [pm-8nev0o](../.agents/pm/issues/pm-8nev0o.toon), [pm-oahhyc](../.agents/pm/issues/pm-oahhyc.toon), [pm-q4isdq](../.agents/pm/issues/pm-q4isdq.toon), [pm-e5gl05](../.agents/pm/issues/pm-e5gl05.toon), [pm-cha95z](../.agents/pm/tasks/pm-cha95z.toon), [pm-2qvq7a](../.agents/pm/issues/pm-2qvq7a.toon), and [pm-xam9bt](../.agents/pm/issues/pm-xam9bt.toon).
 
 ## Agent Quick Context
 
@@ -153,6 +153,14 @@ pm contracts --full --json
 
 Every projected result carries a `read_output` receipt with the requested dimensions, precedence, observed option provenance, deterministic estimated token count, string/row compaction signals, and budget outcome. When canonical controls are present, `canonical_options_used` records spellings such as `--output-include`; the optional field is omitted when no canonical control was supplied so minimum-budget session receipts remain compact. `legacy_aliases_used` and `migration_hints` record only compatibility flags the caller actually supplied. A command-local flag synthesized internally to execute a canonical projection mode is therefore never misreported as deprecated syntax. When both spellings are supplied, both provenance arrays report that mixed invocation. Budget degradation discovers nested arrays as well as declared result rows, so validation diagnostics and other governance payloads compact their inner findings before the useful result is omitted. `compacted_row_paths` names every reduced collection without redefining those nested arrays as ordinary pagination rows.
 
+For `context` and `next`, that final projection is also the usage-feedback
+delivery boundary. The SDK carries a JSON-invisible serve receipt through
+intent and universal output projection, then appends the final omitted decision
+and exact emitted item ids. An infeasible output budget records zero delivered
+rows; it can never leave the packer's earlier inclusions marked as served.
+`PmClient` finalizes the receipt before resolving, while the CLI finalizes it
+from the exact active result passed to telemetry and after-command hooks.
+
 When rows are dropped to satisfy a ceiling, the result also carries `output_budget_truncation`, naming the binding budget and its source, any explicitly requested dimension the budget overrode, every compacted collection path, and executable CLI/SDK/MCP recovery options — a default ceiling can override an explicit `--output-limit unbounded`, and that override is reported rather than silent. If a producer supplied an opaque item-page cursor, compaction rebases it to the last row actually returned and reports `continuation_cursor_rebased: true`; following the cursor therefore cannot skip rows removed from the middle of a producer page. If no useful content can fit, `PmReadOutputBudgetExceeded` provides a discriminated omission result, a compact `{ outputBudget: "unbounded" }` recovery object, and `omitted_result_estimated_tokens`, the last useful-result estimate before omission; use `isReadOutputBudgetExceeded` before accessing result-specific fields. Universal controls are rejected on mutation commands and on the mutation mode of hybrid commands such as `comments`, `notes`, `files`, and `docs`.
 
 Cursor recovery carries the opaque value once in `recovery.cursor` and declares

package/docs/SDK.md

@@ -1773,14 +1773,17 @@ For persistent derived signals, use `ContextSignalStore` with a caller-owned
 `ContextSignalStoreAdapter`, or use `JsonFileContextSignalStoreAdapter` for a
 same-directory atomic JSON snapshot. Each snapshot carries both a
 `format_version` and `signal_set_version`, the authoritative history or index
-`source_cursor`, the stable caller clock, and whether its items came from the
-`derived_index` or `scan_fallback` path. Item rows are deterministic and sorted;
-the snapshot never replaces item or history data.
-
-`readOrRebuild(items, options)` reuses a snapshot only when the cursor and
-complete item-id set match. Missing, stale, version-incompatible, or corrupt
-state is rebuilt from the authoritative items and atomically replaced. The
-result reports `cache_status` and non-fatal `context_signal_store_stale`,
+`source_cursor`, a deterministic `recency_evidence_fingerprint`, the stable
+caller clock, and whether its items came from the `derived_index` or
+`scan_fallback` path. Item rows are deterministic and sorted; the snapshot never
+replaces item or history data.
+
+`readOrRebuild(items, options)` reuses a snapshot only when its format and
+signal-set metadata are supported, its item source matches, and its cursor,
+complete item-id set, and substantive recency-evidence fingerprint match.
+Missing, stale, version-incompatible, or corrupt state is rebuilt from the
+authoritative items and atomically replaced. The result reports `cache_status`
+and non-fatal `context_signal_store_stale`,
 `context_signal_store_invalid`, or `context_signal_store_write_failed`
 warnings. A write failure still serves the in-memory rebuilt candidates because
 the snapshot is derived, never authoritative. Optional maps for activity density,

package/docs/SDK_CONTEXT.md

@@ -31,6 +31,13 @@ stale, or unwritable snapshots return a stable warning, its meaning, an
 executable recovery command, and the expected effect. Re-running `pm context`
 confirms a successful rebuild as fresh.
 
+Recency uses the public `classifyHistoryEvent()` contract and the most recent
+substantive immutable event, with release-cohort and `created_at` fallbacks.
+Explained ranking carries the selected coordinate, operation, and class.
+`recordContextUsageServing()` plus `recordContextUsageDelivery()` expose the
+same two-phase feedback boundary used by CLI and `PmClient`, so custom hosts can
+correlate propensity rows with the exact result delivered after output budgets.
+
 See [Context relevance and packing](CONTEXT_RELEVANCE.md) for signal and token
 budgets, and [context coordination](SDK_CONTEXT_COORDINATION.md) for cursored
 events and duplicate governance.

package/docs/SDK_CONTEXT_EVIDENCE_CONTRACTS.md

@@ -1,6 +1,6 @@
 # SDK Context and Evidence Contracts
 
-Tracked by [pm-gok2km](../.agents/pm/issues/pm-gok2km.toon), [pm-zryb9d](../.agents/pm/issues/pm-zryb9d.toon), [pm-qckpnq](../.agents/pm/issues/pm-qckpnq.toon), [pm-hfqju5](../.agents/pm/issues/pm-hfqju5.toon), [pm-2htk4p](../.agents/pm/issues/pm-2htk4p.toon), and [pm-v0a0un](../.agents/pm/issues/pm-v0a0un.toon).
+Tracked by [pm-gok2km](../.agents/pm/issues/pm-gok2km.toon), [pm-zryb9d](../.agents/pm/issues/pm-zryb9d.toon), [pm-qckpnq](../.agents/pm/issues/pm-qckpnq.toon), [pm-hfqju5](../.agents/pm/issues/pm-hfqju5.toon), [pm-2htk4p](../.agents/pm/issues/pm-2htk4p.toon), [pm-v0a0un](../.agents/pm/issues/pm-v0a0un.toon), [pm-7wzb6d](../.agents/pm/issues/pm-7wzb6d.toon), [pm-mg13iz](../.agents/pm/issues/pm-mg13iz.toon), and [pm-cf4t42](../.agents/pm/issues/pm-cf4t42.toon).
 
 These contracts keep SDK context truthful, bounded, and reusable across the CLI, MCP, packages, and automation. They are designed around the project principle that project management is context management: a compact response must reveal material omissions, merge evidence must describe what actually survived, and compatibility failures must not masquerade as corruption.
 
@@ -22,7 +22,29 @@ This keeps health diagnostics and lazy runtime behavior on one ownership contrac
 
 ## Merge provenance
 
-Stable-value item merges distinguish a caller request from the outcome. Low-level item results, driver results, clone-local receipts, and privacy-safe summaries expose `requested_preference`. The actual outcome remains in each decision's `retained` and `discarded` values or hashes. New receipts do not emit the ambiguous `preferred` key; readers still ingest legacy schema-v1 receipts and normalize that key to `requested_preference`.
+Item scalar merges distinguish a caller request from the convergent outcome.
+The `latest_document_update` policy selects the branch document with the later
+`metadata.updated_at`; equal timestamps use stable value order. Low-level item
+results, driver results, receipts, and privacy-safe summaries expose
+`requested_preference` plus `requested_preference_applied: false`. Each new
+decision records `retained_side` and `resolution_basis`. New receipts do not
+emit the ambiguous `preferred` key; readers still ingest legacy schema-v1
+receipts and normalize `preferred_side` and `stable_value_order` evidence.
+
+Tracked receipt evidence uses `bounded_non_sensitive_scalars_v1`: built-in
+status, priority 0 through 4, risk/confidence/severity ordinals, and `null` may
+be included beside their verifiable hashes. Every other value remains
+hash-only. Fresh-clone consumers must branch on `value_availability` rather than
+assuming raw values exist. Invalid evidence separates `schema_invalid` from
+`identity_invalid` and adds a bounded `validation_error`, while retaining the
+legacy combined reason in the public union for source compatibility.
+
+`runMergeReconcile` also reports missing history receipt counts before and
+after the operation. With explicit `force`, it can append a narrowly matched
+audit disposition for a missing reference whose original event predates the
+durable-receipt epoch. The item id, original line, receipt id, and timestamp
+must all match, and the audit event must occur later in that history stream;
+current-era missing evidence remains blocking.
 
 ## Claim race classification
 

package/docs/SDK_RUNTIME_BOUNDARIES.md

@@ -2,7 +2,9 @@
 
 Tracker: [pm-1eted6](../.agents/pm/issues/pm-1eted6.toon),
 [pm-3lhth4](../.agents/pm/issues/pm-3lhth4.toon), and
-[pm-0xmajx](../.agents/pm/issues/pm-0xmajx.toon). Refusal reachability and
+[pm-0xmajx](../.agents/pm/issues/pm-0xmajx.toon), with forward history-epoch
+protection tracked by
+[pm-aka8m7](../.agents/pm/issues/pm-aka8m7.toon). Refusal reachability and
 recovery completeness are tracked by
 [pm-elmpav](../.agents/pm/features/pm-elmpav.toon),
 [pm-185870](../.agents/pm/issues/pm-185870.toon), and
@@ -29,6 +31,20 @@ package-manager-neutral recovery action. SDK callers receive the same warning
 inside `ProjectRuntimeCompatibilityResult`. `PM_ALLOW_STALE_CLI=1` is the
 explicit, auditable emergency override.
 
+The boundary is bidirectional for history storage. A current runtime also
+refuses a mutation when any package declaration or lockfile pin cannot select a
+runtime that reads the writer epoch. Every manifest section is evaluated, so a
+newer permissive declaration cannot hide an older exact pin. Upper-bounded
+ranges that exclude the first compatible reader also fail closed, including
+inclusive hyphen ranges. Disjunctive ranges evaluate each alternative, so one
+branch that can select a compatible reader keeps the declaration writable. The
+original incompatible declaration is preserved in the diagnostic rather than
+being reduced to its representative lower bound. The typed
+`project_runtime_history_epoch_incompatible` error reports the writer epoch,
+the incompatible declaration, its redaction-safe source, and the minimum
+upgrade. Reads remain available, and the same emergency override is reserved
+for an intentionally coordinated fleet migration.
+
 The public `isProjectMutatingInvocation` classifier applies the same decision
 to package hosts and the bundled CLI. It resolves mixed command families by
 their effective action: configuration, merge, schema, profile, package,

package/docs/examples/sdk-agent-environment/README.md

@@ -0,0 +1,14 @@
+# Public SDK Agent Environment
+
+Tracker: [pm-t8a0x1](../../../.agents/pm/features/pm-t8a0x1.toon)
+
+This executable example imports only Node.js built-ins and `@unbrained/pm-cli/sdk`. It creates an isolated temporary tracker, uses ordinary `PmClient` actions, serves a budgeted observation, evaluates recorded state, and closes the episode. It has no machine-learning dependencies.
+
+From an installed package checkout:
+
+```bash
+npm install @unbrained/pm-cli
+npm start
+```
+
+The JSON result is intentionally small and stable enough for a CI assertion. The temporary workspace is removed after the run.

package/docs/examples/sdk-agent-environment/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "pm-sdk-agent-environment-example",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "node run-agent-environment.mjs"
+  }
+}

package/docs/examples/sdk-agent-environment/run-agent-environment.mjs

@@ -0,0 +1,154 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  PM_EPISODE_SCHEMA,
+  PM_OBSERVATION_SCHEMA,
+  PM_VERDICT_SCHEMA,
+  PM_WORKSPACE_RECIPE_SCHEMA,
+  PmClient,
+  defineEpisodeSpecification,
+  openPmEpisode,
+  runWithWorkspaceRecipe,
+} from "@unbrained/pm-cli/sdk";
+
+class PublicSdkAdapter {
+  constructor(workspace) {
+    this.client = new PmClient({ cwd: workspace, noExtensions: true });
+    this.itemId = "";
+    this.revision = 0;
+  }
+
+  async reset(recipe) {
+    const created = await runWithWorkspaceRecipe(recipe, async () => {
+      await this.client.init("environment");
+      return this.client.create({
+        id: "pm-created-by-adapter",
+        title: "Complete the SDK environment task",
+        type: "Task",
+        status: "open",
+        description: "Created inside a deterministic public-SDK episode.",
+      });
+    });
+    this.itemId = created.item.id;
+    this.revision = 0;
+    return { workspace_id: "temporary-pm-workspace", state_id: "revision:0" };
+  }
+
+  async execute(_action) {
+    const result = await this.client.close(
+      this.itemId,
+      "Public SDK episode completed",
+      {
+        resolution: "The ordinary PmClient close action recorded completion.",
+        expected: "The task is closed through the public SDK.",
+        actual: "The task is closed through the public SDK.",
+        validateClose: "warn",
+      },
+    );
+    this.revision += 1;
+    return { state_id: `revision:${this.revision}`, output: result };
+  }
+
+  async readRecordedState() {
+    const result = await this.client.get(this.itemId);
+    return {
+      snapshot_id: `revision:${this.revision}`,
+      state: {
+        item: {
+          id: result.item.id,
+          title: result.item.title,
+          status: result.item.status,
+          resolution: result.item.resolution,
+        },
+      },
+    };
+  }
+}
+
+const observation = {
+  schema: PM_OBSERVATION_SCHEMA,
+  id: "sdk-task-state",
+  version: 1,
+  reads: [{ command: "get", budget_tokens: 256 }],
+  calibration: {
+    basis: "emitted_bytes",
+    samples: [96, 128, 160],
+    expected_emitted_bytes: 128,
+    tolerance_bytes: 32,
+  },
+  corpus_dependence: { kind: "independent" },
+  tiers: [
+    {
+      id: "standard",
+      max_tokens: 256,
+      fields: ["item.id", "item.title", "item.status", "item.resolution"],
+    },
+    { id: "identity", max_tokens: 48, fields: ["item.id", "item.status"] },
+  ],
+};
+
+const verdict = {
+  schema: PM_VERDICT_SCHEMA,
+  id: "sdk-task-closed",
+  version: 1,
+  predicates: [
+    {
+      id: "closed",
+      kind: "field_equals",
+      path: "item.status",
+      expected: "closed",
+    },
+    { id: "explained", kind: "field_present", path: "item.resolution" },
+  ],
+  composition: { operator: "all", predicate_ids: ["closed", "explained"] },
+};
+
+const workspace = await mkdtemp(join(tmpdir(), "pm-sdk-environment-"));
+try {
+  const session = await openPmEpisode(
+    defineEpisodeSpecification({
+      schema: PM_EPISODE_SCHEMA,
+      id: "public-sdk-environment",
+      version: 1,
+      mode: "evaluation",
+      recipe: {
+        schema: PM_WORKSPACE_RECIPE_SCHEMA,
+        seed: "public-sdk-environment",
+        clock: "2026-09-03T00:00:00.000Z",
+        tickMs: 1,
+        operations: [],
+      },
+      task_item_ids: ["pm-created-by-adapter"],
+      observable_fields: [
+        "item.id",
+        "item.title",
+        "item.status",
+        "item.resolution",
+      ],
+      withheld_fields: ["grading.expected_status"],
+      observation,
+      verdict,
+      limits: {
+        max_actions: 1,
+        max_observations: 2,
+        max_tokens_per_observation: 256,
+      },
+    }),
+    new PublicSdkAdapter(workspace),
+  );
+  const initial = await session.observe();
+  await session.step({ kind: "close" });
+  const completed = await session.close();
+  process.stdout.write(
+    `${JSON.stringify({
+      initial_status: initial.status,
+      initial_tier: initial.receipt.served_tier,
+      verdict: completed.verdict.outcome,
+      policy: completed.verdict.policy,
+      trajectory: completed.trajectory.map((entry) => entry.kind),
+    })}\n`,
+  );
+} finally {
+  await rm(workspace, { recursive: true, force: true });
+}

package/docs/generated/REFUSAL_CLOSURE_CENSUS.md

@@ -4,12 +4,12 @@ Tracker: `pm-f05lsg`.
 
 Every catalog code is listed. An `uncovered` row is an explicit closure obligation, never an omission or implied approval.
 
-- Catalog error codes: 355
+- Catalog error codes: 357
 - Executable error codes: 19
 - Executable-code ratchet floor: 18
 - Required executable canonical codes: `bulk_ids_input_empty`, `bulk_ids_input_missing_path`, `bulk_ids_input_unreadable`, `invalid_argument_value`, `manifest_unknown_key`, `missing_lifecycle_target`, `missing_required_argument`, `no_version_bounds_declared`, `projection_options_mutually_exclusive`, `tracker_not_initialized`, `tracker_root_missing`, `tracker_root_not_directory`, `tracker_root_unreadable`, `unknown_context_intent`, `unknown_field_projection`, `unknown_option`, `unknown_subcommand`
-- Uncovered error codes: 336
-- Coverage fraction: 0.053521
+- Uncovered error codes: 338
+- Coverage fraction: 0.053221
 - Closed-domain probes: 19
 - Grammar probes: 94
 
@@ -120,6 +120,7 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 | `history_merge_conflict_markers_detected` | `merge_conflict_markers_detected` | uncovered | none | 0 |
 | `history_stream_over_compact_threshold` | `history_stream_over_compact_threshold` | uncovered | none | 0 |
 | `history_target_out_of_range` | `history_target_out_of_range` | uncovered | none | 0 |
+| `history_timestamp_invalid` | `history_timestamp_invalid` | uncovered | none | 0 |
 | `history_unknown_author_events` | `history_unknown_author_events` | uncovered | none | 0 |
 | `host_environment_capacity_fault` | `host_environment_capacity_fault` | uncovered | none | 0 |
 | `host_environment_operation_invalid` | `host_environment_operation_invalid` | uncovered | none | 0 |
@@ -232,6 +233,7 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 | `profile_name_not_normalized` | `profile_name_not_normalized` | uncovered | none | 0 |
 | `profile_summary_empty` | `profile_summary_empty` | uncovered | none | 0 |
 | `profile_title_empty` | `profile_title_empty` | uncovered | none | 0 |
+| `project_runtime_history_epoch_incompatible` | `project_runtime_history_epoch_incompatible` | uncovered | none | 0 |
 | `project_runtime_stale_mutation` | `project_runtime_stale_mutation` | uncovered | none | 0 |
 | `project_runtime_stale_read` | `project_runtime_stale_read` | uncovered | none | 0 |
 | `projection_options_mutually_exclusive` | `projection_options_mutually_exclusive` | executable | closed_domain | 3 |