@unbrained/pm-cli 2026.9.3 → 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]="d45775e5-6826-521b-80b3-429ed22947d9")}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";
@@ -19,10 +19,10 @@ export { isFileMissingError, pathExists, readFileIfExists, removeFileIfExists, w
 export { normalizeBulkIdsValue, parseBulkIdsText, resolveCliBulkIdsInput, } from "../core/io/bulk-ids-input.js";
 export { computeHistoryDiff, patchPathToChangedField, } from "../core/history/history-diff.js";
 export { enforceHistoryStreamPolicyForItem, enforceHistoryStreamPolicyForItems, } from "../core/history/history-stream-policy.js";
-export { appendHistoryEntry, CURRENT_HISTORY_ITEM_HASH_VERSION, createHistoryEntry, hashDocument, hashDocumentForVersion, hashEmptyDocument, SUPPORTED_HISTORY_ITEM_HASH_VERSIONS, } from "../core/history/history.js";
+export { appendHistoryEntry, CURRENT_HISTORY_ITEM_HASH_VERSION, CURRENT_HISTORY_RECORD_HASH_VERSION, createHistoryEntry, hashDocument, hashDocumentForVersion, hashEmptyDocument, hashHistoryPatch, hashHistoryRecord, hashHistoryStream, resealHistoryRewrite, sealHistoryRecord, SUPPORTED_HISTORY_ITEM_HASH_VERSIONS, SUPPORTED_HISTORY_RECORD_HASH_VERSIONS, verifyHistoryRecordHash, verifyHistoryRewriteEvidence, } from "../core/history/history.js";
 export { readHistoryEntries } from "../core/history/read.js";
 export { appendWorkspaceAuditEvent, appendWorkspaceHistoryChange, getWorkspaceHistoryPath, inspectWorkspaceHistoryState, mutateWorkspaceJsonWithHistory, reconcileWorkspaceJsonHistory, restoreWorkspaceJsonFromHistory, WORKSPACE_HISTORY_ID, writeWorkspaceJsonWithHistory, } from "../core/history/workspace-history.js";
-export { normalizeReplayPatchOps, replayToCanonicalItemDocument, replayToItemDocument, toReplayDocument, verifyHistoryChain, verifyHistoryChainWithVersion, } from "../core/history/replay.js";
+export { normalizeReplayPatchOps, reanchorHistoryEntries, replayToCanonicalItemDocument, replayToItemDocument, toReplayDocument, verifyHistoryChain, verifyHistoryChainWithVersion, } from "../core/history/replay.js";
 export { resolveBodyFileContent } from "../core/io/body-file.js";
 export { generateItemId, normalizeItemId, normalizeRawItemId, } from "../core/item/id.js";
 export { canonicalDocument, normalizeItemMetadata, parseItemDocument, serializeItemDocument, } from "../core/item/item-format.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=d45775e5-6826-521b-80b3-429ed22947d9
+//# 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. */
@@ -789,6 +791,25 @@ export interface HistoryPatchOp {
     /** Value that configures or reports value for this contract. */
     value?: unknown;
 }
+/** Immutable evidence retained whenever history maintenance replaces anchors or patch operations. */
+export interface HistoryReanchorEvidence {
+    /** Before-state anchor present on the record before re-anchoring. */
+    before_hash: string;
+    /** After-state anchor present on the record before re-anchoring. */
+    after_hash: string;
+    /** Item hash epoch present before re-anchoring. */
+    item_hash_version?: number;
+    /** Hash of the original patch, retained even when redaction forbids retaining its values. */
+    patch_hash: string;
+    /** Original patch operations when repair replaced or skipped recorded intent. */
+    patch?: HistoryPatchOp[];
+    /** Record-integrity epoch protecting the pre-re-anchor record. */
+    record_hash_version?: number;
+    /** Record hash protecting the pre-re-anchor attribution and operation metadata. */
+    record_hash?: string;
+    /** Exact prior sealed record when maintenance can retain its non-sensitive payload. */
+    record?: HistoryEntry;
+}
 /** Documents the history entry payload exchanged by command, SDK, and package integrations. */
 export interface HistoryEntry {
     /** Value that configures or reports ts for this contract. */
@@ -839,6 +860,12 @@ export interface HistoryEntry {
     after_hash: string;
     /** Version of the item canonicalization used by before_hash and after_hash. Absent on legacy streams. */
     item_hash_version?: number;
+    /** Version of the canonical immutable-record envelope. Absent on legacy entries whose coverage is item-state-only. */
+    record_hash_version?: number;
+    /** SHA-256 hash covering this event's immutable metadata, patch, and item anchors. */
+    record_hash?: string;
+    /** Append-only evidence for every prior anchor or patch representation replaced by maintenance. */
+    reanchor_evidence?: HistoryReanchorEvidence[];
     /** Human-readable explanation suitable for logs and agent-facing output. */
     message?: string;
     /** Structured audit metadata that does not alter replayed item state. */

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]="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=668a8823-62c4-5c69-9b9b-0c72d6d94b2b
+//# debugId=8173bdb0-39c8-56c0-85c2-5c39f5c213cc

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_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/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/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.