@unbrained/pm-cli 2026.9.3 → 2026.9.4

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]="668a8823-62c4-5c69-9b9b-0c72d6d94b2b")}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]="4ee067ac-f28d-5411-9ac7-c92112384a64")}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=668a8823-62c4-5c69-9b9b-0c72d6d94b2b
+//# debugId=4ee067ac-f28d-5411-9ac7-c92112384a64

package/docs/AGENT_ENVIRONMENTS.md

@@ -0,0 +1,47 @@
+# SDK Agent Environments
+
+Tracker: [pm-e1vkee](../.agents/pm/features/pm-e1vkee.toon), [pm-gd6vnn](../.agents/pm/features/pm-gd6vnn.toon), [pm-li2fj5](../.agents/pm/features/pm-li2fj5.toon), [pm-t8a0x1](../.agents/pm/features/pm-t8a0x1.toon)
+
+## Agent Quick Context
+
+`@unbrained/pm-cli/sdk` provides three composable contracts for building reproducible project-management environments without a machine-learning runtime dependency:
+
+- an observation contract declares every read ceiling, emitted-byte calibration, corpus-size dependence, and an ordered degradation ladder;
+- a verdict contract evaluates named, versioned predicates over recorded state and returns `satisfied`, `violated`, or `not_applicable` without producing a reward signal;
+- an episode specification combines a deterministic workspace recipe, canonical task items, observable and withheld fields, hard limits, and an adapter for ordinary `PmClient` actions.
+
+The executable [public-SDK example](examples/sdk-agent-environment/README.md) runs the complete reset → observe → act → verdict → close loop in a temporary pm workspace.
+
+## Contract Boundaries
+
+Observation cost is knowable before a read. `describeObservationCost()` returns the sum of the declared read ceilings plus the calibrated expected emitted bytes. `serveDeclaredObservation()` measures stable serialized bytes, attempts tiers in declaration order, names the served tier, and returns a payload-free refusal if no tier fits.
+
+Verdicts only inspect the adapter's `WorkspaceRecordedState`. Evidence identifies the exact snapshot and JSON pointer while a digest avoids copying field values into the result. The interpreter is deterministic and read-only; `policy: "verdict_only_no_reward"` makes the non-reward boundary machine-readable.
+
+Episodes never grant a second mutation vocabulary. The adapter's `execute()` method should call ordinary public `PmClient` methods, so lifecycle validation, history, extensions, and policy remain authoritative. Each session owns its counters and trajectory, allowing concurrent runs without shared episode state.
+
+Withheld grading fields cannot also be observable. Every tier field must be declared observable, and projection copies only the selected tier fields. Hard action and observation limits fail closed.
+
+## Minimal Shape
+
+```ts
+import {
+  defineEpisodeSpecification,
+  openPmEpisode,
+  type EpisodeRuntimeAdapter,
+} from "@unbrained/pm-cli/sdk";
+
+const specification = defineEpisodeSpecification({
+  // Versioned recipe, task set, observation, verdict, and limits.
+});
+const session = await openPmEpisode(
+  specification,
+  adapter satisfies EpisodeRuntimeAdapter<MyAction>,
+);
+
+await session.observe();
+await session.step({ kind: "close" });
+const evidence = await session.close();
+```
+
+Use the same specification and adapter boundary for benchmarks, evaluations, training data collection, or scale-transfer experiments. Consumer intent changes through `mode`; the pm action and evidence contracts do not.

package/docs/AGENT_PROVENANCE_ADR.md

@@ -10,7 +10,9 @@ Implementation lineage:
 resolution and patch-free historical reads implemented by
 [pm-ffz0a9](../.agents/pm/issues/pm-ffz0a9.toon),
 [pm-v8gfi7](../.agents/pm/issues/pm-v8gfi7.toon), and
-[pm-3yxwv5](../.agents/pm/issues/pm-3yxwv5.toon). Cross-harness adapters and
+[pm-3yxwv5](../.agents/pm/issues/pm-3yxwv5.toon). Stable Claude session
+discovery across child working directories is tracked by
+[pm-l7m7k5](../.agents/pm/issues/pm-l7m7k5.toon). Cross-harness adapters and
 operator-managed probe/vocabulary controls are tracked by
 [pm-c0lrdm](../.agents/pm/features/pm-c0lrdm.toon) and
 [pm-yds9dt](../.agents/pm/chores/pm-yds9dt.toon).
@@ -56,7 +58,13 @@ from literal descriptor keys, trusted caller data, or a named bounded resolver.
 Detection does not spawn processes, traverse process trees, evaluate user
 regexes, or access the network. The built-in Claude and Codex resolvers read
 only bounded windows of the current session's harness-owned JSONL file. Claude
-uses the recent tail to recover its recorded model/version. Codex uses the
+resolves an explicitly supplied transcript first, then the direct workspace
+coordinate, then performs a deterministic scan of at most 512 immediate
+project directories for the unique stable session id. This keeps provenance
+attached when the invocation cwd moves into a child package. No match is
+reported as `resolver_input_missing`; multiple matches are ambiguous and remain
+`resolver_failed` instead of selecting an arbitrary transcript. Claude uses the
+bounded session window to recover its recorded model/version. Codex uses the
 recent tail plus a bounded initial-head fallback for oversized sessions to
 recover allow-listed `turn_context.model` and `turn_context.effort` values.
 Both cap traversal, file bytes, lines, and line length, ignore all other fields,
@@ -70,6 +78,13 @@ the existing domain-separated, truncated `agent_instance` digest. Public
 telemetry continues to use installation-scoped hashes or presence booleans; it
 does not export raw provenance values.
 
+Health counts resolvers with an available input, plus failed or ambiguous
+resolution attempts, as attempts. A sustained attempted-but-zero-success series
+remains advisory: it truthfully identifies parser, filesystem, ambiguity, or
+provider-shape drift without treating missing descriptive metadata as
+authorization or item-state corruption. Missing-input and probes-disabled
+events are classified separately and do not inflate that warning.
+
 ## Compatibility
 
 All new history fields are optional. Readers must accept:

package/docs/CONTEXT_INTEGRITY_CONTRACTS.md

@@ -1,6 +1,6 @@
 # Context Integrity Contracts
 
-Tracker references: [pm-4fwgaz](../.agents/pm/issues/pm-4fwgaz.toon), [pm-qqoumq](../.agents/pm/issues/pm-qqoumq.toon), [pm-fpdk37](../.agents/pm/issues/pm-fpdk37.toon), [pm-jn1x30](../.agents/pm/issues/pm-jn1x30.toon), and [pm-0wfdim](../.agents/pm/issues/pm-0wfdim.toon).
+Tracker references: [pm-4fwgaz](../.agents/pm/issues/pm-4fwgaz.toon), [pm-qqoumq](../.agents/pm/issues/pm-qqoumq.toon), [pm-fpdk37](../.agents/pm/issues/pm-fpdk37.toon), [pm-jn1x30](../.agents/pm/issues/pm-jn1x30.toon), [pm-0wfdim](../.agents/pm/issues/pm-0wfdim.toon), [pm-javbsq](../.agents/pm/issues/pm-javbsq.toon), and [pm-aka8m7](../.agents/pm/issues/pm-aka8m7.toon).
 
 ## Agent Quick Context
 
@@ -53,6 +53,43 @@ History writers using item-hash epoch 2 always emit `item_hash_version: 2`. An e
 
 Repair keeps implicit legacy streams implicit and byte-stable when no drift exists. Unsupported explicit epochs still fail with a typed `unsupported_item_hash_version` diagnostic instead of being rewritten.
 
+| Writer/runtime range                     | Item-hash output | Read contract                                                                                                                  |
+| ---------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| Legacy writers before an explicit marker | implicit epoch 1 | Modern readers retain legacy canonicalization candidates.                                                                      |
+| Observed 2026.8.24 through 2026.8.28     | explicit epoch 2 | Modern readers accept both field-frozen and expanded epoch-2 forms without mixing forms inside one entry.                      |
+| 2026.8.31 and newer                      | explicit epoch 3 | Exact pins and bounded ranges that cannot select an epoch-3 reader cause current runtimes to reject the write before mutation. |
+
+The table records confirmed release boundaries rather than inventing an exact
+first release for legacy epoch 1 or epoch 2. The SDK exports
+`HISTORY_ITEM_HASH_VERSION_3_INTRODUCED_IN`, and runtime compatibility checks
+use that boundary for package-manager-neutral write refusal.
+
+## Whole-Record History Integrity
+
+Item anchors prove the replayed project state; they do not prove who recorded an
+event, when it happened, which operation produced it, or which provenance and
+context were attached. New events therefore use a separate record-integrity
+epoch. `record_hash_version: 1` seals every immutable field while preserving the
+item-hash epoch as an independent compatibility contract.
+
+`verifyHistoryRecordHash()` reports `record_and_item_state` for a valid sealed
+event and `item_state_only` for a legacy event with neither record-envelope
+field. Half-present, unsupported, and mismatched envelopes fail closed. The
+public SDK also exports the record and patch hashing, sealing,
+`verifyHistoryRewriteEvidence()`, rewrite-resealing, stream-digest, and
+reanchoring primitives so packages and embedded hosts do not need private core
+imports or their own canonicalization.
+
+Maintenance retains prior anchors and patch digests in `reanchor_evidence`.
+When policy permits, it also retains the exact prior sealed record so
+metadata-only rewrites remain independently verifiable. Privacy-sensitive
+redaction and provenance normalization deliberately retain digest-only evidence
+instead of embedding the removed value. This separates two claims: the current
+chain is replay-consistent, and a rewrite preserved evidence of what it
+replaced. Compaction records a digest of its pruned prefix and explicitly states
+that individual pruned entries require the pre-compaction stream; it never
+upgrades intentional information loss into a stronger assurance claim.
+
 ## Verification Boundary
 
 The regression suite covers each contract at its public SDK or command boundary. Release verification additionally installs the packed package into a temporary project and exercises sparse reads, remote docs, graph impact, extension diagnostics, and history repair without touching the repository tracker.

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/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/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"
+  }
+}