@unbrained/pm-cli 2026.8.15 → 2026.8.16

package/dist/sdk/governance/coverage-assurance.js

@@ -0,0 +1,61 @@
+/**
+ * @module sdk/governance/coverage-assurance
+ *
+ * Provides exact integer coverage assurance for repository and package gates.
+ */
+/** Coverage metrics required by the exact repository quality 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]="340305b6-e3c8-5daa-bfbe-4a9c62a6d039")}catch(e){}}();
+export const PM_EXACT_COVERAGE_METRICS = [
+    "lines",
+    "branches",
+    "functions",
+    "statements",
+];
+/** Require a coverage report entry to expose an object-shaped metric map. */
+function assertCoverageEntry(file, entry) {
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+        throw new TypeError(`Coverage entry for ${file} must be an object.`);
+    }
+}
+/** Return exact validated counts for one required metric. */
+function coverageCounts(file, metric, value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new TypeError(`Coverage entry ${file} has invalid ${metric} counts.`);
+    }
+    const counts = value;
+    if (typeof counts.covered !== "number" ||
+        typeof counts.total !== "number" ||
+        !Number.isInteger(counts.covered) ||
+        !Number.isInteger(counts.total) ||
+        counts.covered < 0 ||
+        counts.total < counts.covered) {
+        throw new TypeError(`Coverage entry ${file} has invalid ${metric} counts.`);
+    }
+    return { covered: counts.covered, total: counts.total };
+}
+/** Return exact uncovered counts for every summary entry and required metric. */
+export function findCoverageDeficits(summary) {
+    if (typeof summary !== "object" ||
+        summary === null ||
+        Array.isArray(summary)) {
+        throw new TypeError("Coverage summary must be a JSON object.");
+    }
+    if (!("total" in summary)) {
+        throw new TypeError("Coverage summary is missing the total entry.");
+    }
+    const deficits = [];
+    for (const [file, entry] of Object.entries(summary)) {
+        assertCoverageEntry(file, entry);
+        for (const metric of PM_EXACT_COVERAGE_METRICS) {
+            const counts = coverageCounts(file, metric, entry[metric]);
+            const uncovered = counts.total - counts.covered;
+            if (uncovered > 0) {
+                deficits.push({ file, metric, uncovered, ...counts });
+            }
+        }
+    }
+    return deficits;
+}
+//# sourceMappingURL=coverage-assurance.js.map
+//# debugId=340305b6-e3c8-5daa-bfbe-4a9c62a6d039

package/dist/sdk/governance/extension-host-version.js

@@ -5,7 +5,7 @@
  * package-manager layout skew is visible before SDK singleton state diverges.
  */
 
-!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]="b55cafdc-9a3b-5386-bd85-cbd2311a5933")}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]="c21b1a94-1d80-57c0-b090-c4831fc505a2")}catch(e){}}();
 import fs from "node:fs/promises";
 import { createRequire } from "node:module";
 import path from "node:path";
@@ -48,17 +48,27 @@ async function readPackageVersion(packageJsonPath) {
         return undefined;
     }
 }
+/** Resolve symlink and platform alias segments without failing soft scans for absent hosts. */
+async function canonicalPath(candidate) {
+    try {
+        return await fs.realpath(candidate);
+    }
+    catch {
+        return path.resolve(candidate);
+    }
+}
 /** Scan the host plus the nearest pm-cli package resolvable by every loaded extension. */
 export async function scanExtensionHostVersions(loadedExtensions, workspaceRoot, hostPackageRoot = resolvePmPackageRootFromModule(import.meta.url, [
     "../../..",
 ])) {
-    const hostPackageJson = path.join(hostPackageRoot, "package.json");
+    const canonicalWorkspaceRoot = await canonicalPath(workspaceRoot);
+    const hostPackageJson = await canonicalPath(path.join(hostPackageRoot, "package.json"));
     const hostVersion = await readPackageVersion(hostPackageJson);
     const copies = new Map();
     if (hostVersion !== undefined) {
-        copies.set(path.resolve(hostPackageJson), {
+        copies.set(hostPackageJson, {
             version: hostVersion,
-            path: displayPackagePath(hostPackageJson, workspaceRoot),
+            path: displayPackagePath(hostPackageJson, canonicalWorkspaceRoot),
             layout: "host",
             consumers: ["pm-cli-host"],
         });
@@ -66,10 +76,11 @@ export async function scanExtensionHostVersions(loadedExtensions, workspaceRoot,
     for (const extension of loadedExtensions) {
         try {
             const resolved = createRequire(extension.entry_path).resolve("@unbrained/pm-cli/package.json");
-            const version = await readPackageVersion(resolved);
+            const canonicalPackageJson = await canonicalPath(resolved);
+            const version = await readPackageVersion(canonicalPackageJson);
             if (version === undefined)
                 continue;
-            const key = path.resolve(resolved);
+            const key = canonicalPackageJson;
             const existing = copies.get(key);
             if (existing) {
                 if (!existing.consumers.includes(extension.name)) {
@@ -80,8 +91,8 @@ export async function scanExtensionHostVersions(loadedExtensions, workspaceRoot,
             }
             copies.set(key, {
                 version,
-                path: displayPackagePath(resolved, workspaceRoot),
-                layout: dependencyLayout(resolved),
+                path: displayPackagePath(canonicalPackageJson, canonicalWorkspaceRoot),
+                layout: dependencyLayout(canonicalPackageJson),
                 consumers: [extension.name],
             });
         }
@@ -102,4 +113,4 @@ export async function scanExtensionHostVersions(loadedExtensions, workspaceRoot,
     };
 }
 //# sourceMappingURL=extension-host-version.js.map
-//# debugId=b55cafdc-9a3b-5386-bd85-cbd2311a5933
+//# debugId=c21b1a94-1d80-57c0-b090-c4831fc505a2

package/dist/sdk/index.d.ts

@@ -7,7 +7,7 @@ export { PM_COMMAND_VISIBILITY_CONTRACTS, PM_MCP_PROMPT_CONTRACTS, PM_MCP_RESOUR
 export * from "./agent-session-context.js";
 export type { PmCommandVisibilityContract, PmCommandVisibilityTier, PmMcpPromptArgumentContract, PmMcpPromptContract, PmMcpResourceContract, PmMcpToolProfile, } from "./agent-capability-contracts.js";
 export { isErrnoError, limitAnnotationEntries, parseAnnotationTextInput, readAnnotationEntries, normalizeAnnotationTransportOptions, resolveAnnotationInput, resolveAnnotationIndex, runAnnotationCommand, wrapOwnershipConflict, type AnnotationCommandConfig, type AnnotationCommandOptions, type AnnotationCommandResult, type AnnotationEntry, type AnnotationInput, type AnnotationHistoryRestoration, type AnnotationMutationReceipt, type AnnotationOmissionReceipt, type AnnotationSourceOptions, type OwnershipConflictGuidance, } from "./annotations.js";
-export { acknowledgeUnknownAuthorHistoryEvents, acknowledgeUnknownAuthorHistoryEventsFromTransport, inspectHistoryAuthorStream, parseUnknownAuthorHistoryEventCoordinates, resolveUnknownAuthorAcknowledgmentSelector, scanHistoryAuthorAttribution, type AcknowledgeUnknownAuthorEventsOptions, type HistoryAuthorAttributionScan, type UnknownAuthorHistoryEvent, } from "./author-attribution.js";
+export { acknowledgeUnknownAuthorHistoryEvents, acknowledgeUnknownAuthorHistoryEventsFromTransport, inspectHistoryAuthorStream, parseUnknownAuthorHistoryEventCoordinates, planUnknownAuthorHistoryAcknowledgment, resolveUnknownAuthorAcknowledgmentSelector, scanHistoryAuthorAttribution, type AcknowledgeUnknownAuthorEventsOptions, type HistoryAuthorAttributionScan, type UnknownAuthorAcknowledgmentPlan, type UnknownAuthorAcknowledgmentPlanCoordinate, type UnknownAuthorAcknowledgmentResult, type UnknownAuthorHistoryEvent, } from "./author-attribution.js";
 export { BUILTIN_CORPUS_SHAPES, PM_CORPUS_SHAPE_SCHEMA, buildCorpusShapeItemPlan, createCorpusShapeMeasurement, defineCorpusShape, listBuiltinCorpusShapes, measureCorpusShapePlan, resolveBuiltinCorpusShape, type BuiltinCorpusShapeName, type CorpusShape, type CorpusShapeEdgeWeight, type CorpusShapeItemPlan, type CorpusShapeMeasurement, type CorpusShapeProfile, } from "./corpus-shape.js";
 export * from "./core-governance.js";
 export { createPmCliProgram } from "./cli-program.js";
@@ -22,6 +22,7 @@ export * from "./agent/command-suggestions.js";
 export * from "./agent/item-addressing.js";
 export * from "./agent/create-option-policy.js";
 export { runGc, type GcCheckpointsSummary, type GcLocksSummary, } from "./governance/gc.js";
+export { PM_EXACT_COVERAGE_METRICS, findCoverageDeficits, type PmCoverageDeficit, type PmExactCoverageMetric, } from "./governance/coverage-assurance.js";
 export { _testOnlyHealthCommand, runHealth, type HealthCheck, } from "./governance/health.js";
 export { _testOnlyValidateCommand, projectValidateCounts, runValidate, type ValidateCheck, type ValidateCountsFixesSummary, type ValidateCountsResult, type ValidateFixesSummary, type ValidateMutationServices, } from "./governance/validate.js";
 export { runExtension, type ExtensionCommandAction } from "./extension.js";

package/dist/sdk/index.js

@@ -4,11 +4,11 @@
  * Defines public SDK APIs and package-author helpers for Index.
  */
 
-!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]="a05170b2-a48d-5275-ac04-aafc9f8315b2")}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]="9ec91496-fc1e-5be5-a8e8-145d884b0ef7")}catch(e){}}();
 export { PM_COMMAND_VISIBILITY_CONTRACTS, PM_MCP_PROMPT_CONTRACTS, PM_MCP_RESOURCE_CONTRACTS, PM_MCP_TOOL_COMMAND_CONTRACTS, listPmCommandsForTier, listPmMcpToolsForProfile, renderPmCommandVisibilityMarkdown, resolvePmCommandVisibilityTier, } from "./agent-capability-contracts.js";
 export * from "./agent-session-context.js";
 export { isErrnoError, limitAnnotationEntries, parseAnnotationTextInput, readAnnotationEntries, normalizeAnnotationTransportOptions, resolveAnnotationInput, resolveAnnotationIndex, runAnnotationCommand, wrapOwnershipConflict, } from "./annotations.js";
-export { acknowledgeUnknownAuthorHistoryEvents, acknowledgeUnknownAuthorHistoryEventsFromTransport, inspectHistoryAuthorStream, parseUnknownAuthorHistoryEventCoordinates, resolveUnknownAuthorAcknowledgmentSelector, scanHistoryAuthorAttribution, } from "./author-attribution.js";
+export { acknowledgeUnknownAuthorHistoryEvents, acknowledgeUnknownAuthorHistoryEventsFromTransport, inspectHistoryAuthorStream, parseUnknownAuthorHistoryEventCoordinates, planUnknownAuthorHistoryAcknowledgment, resolveUnknownAuthorAcknowledgmentSelector, scanHistoryAuthorAttribution, } from "./author-attribution.js";
 export { BUILTIN_CORPUS_SHAPES, PM_CORPUS_SHAPE_SCHEMA, buildCorpusShapeItemPlan, createCorpusShapeMeasurement, defineCorpusShape, listBuiltinCorpusShapes, measureCorpusShapePlan, resolveBuiltinCorpusShape, } from "./corpus-shape.js";
 export * from "./core-governance.js";
 export { createPmCliProgram } from "./cli-program.js";
@@ -23,6 +23,7 @@ export * from "./agent/command-suggestions.js";
 export * from "./agent/item-addressing.js";
 export * from "./agent/create-option-policy.js";
 export { runGc, } from "./governance/gc.js";
+export { PM_EXACT_COVERAGE_METRICS, findCoverageDeficits, } from "./governance/coverage-assurance.js";
 export { _testOnlyHealthCommand, runHealth, } from "./governance/health.js";
 export { _testOnlyValidateCommand, projectValidateCounts, runValidate, } from "./governance/validate.js";
 export { runExtension } from "./extension.js";
@@ -151,4 +152,4 @@ export * from "./governance.js";
 export * from "./query.js";
 export * from "./testing.js";
 //# sourceMappingURL=index.js.map
-//# debugId=a05170b2-a48d-5275-ac04-aafc9f8315b2
+//# debugId=9ec91496-fc1e-5be5-a8e8-145d884b0ef7

package/dist/sdk/read-output-contracts.js

@@ -5,7 +5,7 @@
  * surface without coupling package authors to command-specific option names.
  */
 
-!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]="f9774018-a5b7-505e-a8ea-cba08392afeb")}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]="e9621264-0180-53cf-862f-b59640b971da")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { compactReadOutputToBudget, estimateReadOutputTokens, updateReadOutputReceiptEstimate, } from "./read-output-budget.js";
@@ -499,7 +499,9 @@ export function resolveReadOutputDimensions(command, options) {
     const encoding = resolveEncodingValue(options.outputFormat ?? options.output_format, legacyByDimension.encoding);
     const explicitCost = resolveCostValue(options.outputBudget ?? options.output_budget, legacyByDimension.cost);
     const completeResultIntent = command.trim().toLowerCase().replaceAll(/\s+/gu, " ").split(" ")[0] ===
-        "list-all" || legacyByDimension.amount?.flag === "--no-truncate";
+        "list-all" ||
+        legacyByDimension.amount?.flag === "--no-truncate" ||
+        legacyByDimension.include?.flag === "--full";
     const budget = resolvePmCommandOutputBudget(command, {
         generateFallback: true,
     });
@@ -1056,4 +1058,4 @@ export function resolveReadOutputEncoding(command, options) {
         : undefined;
 }
 //# sourceMappingURL=read-output-contracts.js.map
-//# debugId=f9774018-a5b7-505e-a8ea-cba08392afeb
+//# debugId=e9621264-0180-53cf-862f-b59640b971da

package/dist/sdk/runtime.d.ts

@@ -33,7 +33,7 @@ import { type GcCommandOptions, type GcResult } from "./governance/gc.js";
 import { type HealthResult, type RunHealthOptions } from "./governance/health.js";
 import { type ValidateCommandOptions, type ValidateCountsResult, type ValidateResult } from "./governance/validate.js";
 import { type ExtensionCommandOptions, type ExtensionCommandResult } from "./extension.js";
-import { type AcknowledgeUnknownAuthorEventsOptions } from "./author-attribution.js";
+import { type AcknowledgeUnknownAuthorEventsOptions, type UnknownAuthorAcknowledgmentResult } from "./author-attribution.js";
 import { type HistoryCompactBulkCommandOptions, type HistoryCompactBulkResult, type HistoryCompactCommandOptions, type HistoryCompactResult } from "./history-compact.js";
 import { type HistoryRedactCommandOptions, type HistoryRedactResult } from "./history-redact.js";
 import { type HistoryRepairAllResult, type HistoryRepairCommandOptions, type HistoryRepairResult } from "./history-repair.js";
@@ -250,10 +250,7 @@ export declare class PmClient {
     /** Compact an explicit or policy-selected set of history streams. */
     historyCompactBulk(options: HistoryCompactBulkCommandOptions): Promise<HistoryCompactBulkResult>;
     /** Disposition immutable unknown-author events through append-only audit history. */
-    historyAuthorAcknowledge(options: AcknowledgeUnknownAuthorEventsOptions): Promise<{
-        acknowledged: number;
-        history_path: string;
-    }>;
+    historyAuthorAcknowledge(options: AcknowledgeUnknownAuthorEventsOptions): Promise<UnknownAuthorAcknowledgmentResult>;
     /** Run any typed plan workflow primitive through the shared CLI/MCP engine. */
     plan(subcommand: PlanSubcommand, id?: string, options?: PlanCommandOptions, stepRef?: string, reorderTo?: number): Promise<PlanCommandResult>;
     /** Create a durable plan with optional ordered seed steps. */

package/dist/sdk/runtime.js

@@ -4,7 +4,7 @@
  * Defines public SDK APIs and package-author helpers for Runtime.
  */
 
-!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]="a387cd7a-cb16-5082-80e1-9632ebd02480")}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]="bedbe090-60c3-5935-a656-da4997cd80f7")}catch(e){}}();
 export { PM_GITIGNORE_END, PM_GITIGNORE_START, ensurePmGitignore, getPmGitignoreBlock, } from "./workspace.js";
 export { SEARCH_EXTENSION_FLAG_DEFINITIONS } from "./extension-contracts.js";
 import { AsyncLocalStorage } from "node:async_hooks";
@@ -442,6 +442,7 @@ export class PmClient {
         return this.runTyped("history-author-acknowledge", {
             historyEvent: (options.events ?? []).map((event) => `${event.item_id}:${String(event.line)}`),
             allActionable: options.all_actionable === true,
+            dryRun: options.dry_run === true, planFingerprint: options.plan_fingerprint, limit: options.coordinate_limit,
             attributedAuthor: options.attributed_author,
             reviewer: options.reviewer,
             reason: options.reason,
@@ -1932,4 +1933,4 @@ async function loadWorkspaceExtensionRegistrations(pmRoot, settings, cwd) {
     }
 }
 //# sourceMappingURL=runtime.js.map
-//# debugId=a387cd7a-cb16-5082-80e1-9632ebd02480
+//# debugId=bedbe090-60c3-5935-a656-da4997cd80f7

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-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-e5gl05](../.agents/pm/issues/pm-e5gl05.toon), and [pm-cha95z](../.agents/pm/tasks/pm-cha95z.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-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-e5gl05](../.agents/pm/issues/pm-e5gl05.toon), [pm-cha95z](../.agents/pm/tasks/pm-cha95z.toon), and [pm-2qvq7a](../.agents/pm/issues/pm-2qvq7a.toon).
 
 ## Agent Quick Context
 
@@ -122,6 +122,12 @@ list-family `--no-truncate` imply an unbounded cost dimension when the caller
 does not supply `--output-budget`; they cannot silently return a budget-trimmed
 subset while claiming to return every matched row. An explicit canonical
 budget still has precedence and may request a bounded result deliberately.
+The same SDK-native rule applies to every declared complete-result spelling,
+including `contracts --full`: explicit completeness defeats only the implicit
+default ceiling. If an explicit caller budget cannot retain any useful domain
+result, the CLI still prints the parseable omission receipt but exits 2; a
+consumer therefore cannot interpret the missing command or action arrays as a
+successful empty contract.
 
 ```bash
 pm list-open --output-include id,title,status --output-limit 10

package/docs/RELEASING.md

@@ -25,7 +25,9 @@ Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon),
 classification [pm-dqtzva](../.agents/pm/issues/pm-dqtzva.toon).
 The local/hosted gate selection contract is tracked by
 [pm-ei6x66](../.agents/pm/tasks/pm-ei6x66.toon). Release-candidate analyzer
-provenance is tracked by [pm-u1baah](../.agents/pm/issues/pm-u1baah.toon).
+provenance is tracked by [pm-u1baah](../.agents/pm/issues/pm-u1baah.toon), and
+authoritative blocker-recovery run selection by
+[pm-db8onn](../.agents/pm/issues/pm-db8onn.toon).
 
 ## Version Policy
 
@@ -76,9 +78,10 @@ Policy:
   created, a non-`github-actions[bot]` closure of the exact bot-created
   `Auto Release blocked` issue on the same UTC day triggers one preparation
   retry
-- if today's tag already exists, blocker closure reruns and watches the exact
-  tag-driven Release workflow instead of invoking release preparation or
-  creating an ordinal replacement; an already-successful run is recorded as
+- if today's tag already exists, blocker closure bypasses release-preparation
+  provenance, dependency installation, and build work, then selects immutable
+  Release evidence across both tag-push and guarded workflow-dispatch runs; a
+  completed success is authoritative over stale failures and is recorded as
   recovered without republishing
 - release preparation must pass all quality and compatibility gates before commit+tag push
 - before dependency installation or build, auto-release verifies that the
@@ -92,9 +95,12 @@ Policy:
 - when scheduled failures continue across multiple UTC days, auto-release supersedes a stale open blocker with a fresh current-day blocker so same-day retry detection follows the latest scheduled failure
 - closing the exact bot-created `Auto Release blocked: scheduled run failed`
   issue as a maintainer or agent records a same-day retry marker, then either
-  retries preparation when no tag exists or reruns the exact existing tag's
-  Release workflow; it comments with the recovered tag on success and reopens
-  the same issue on failure. A second close on the same UTC day is refused
+  retries preparation when no tag exists or watches an active exact-tag Release
+  workflow. If only failed or missing evidence exists, it dispatches the
+  reviewed current `release.yml` from `main` with the immutable tag input; it
+  never reruns historical workflow code. It comments with the recovered tag on
+  success and reopens the same issue on failure. A second close on the same UTC
+  day is refused
   before release mutation and reported as `retry_already_attempted`, and
   workflow cleanup closures by `github-actions[bot]` are ignored.
 - after a scheduled run publishes a tag and the downstream release workflow succeeds, auto-release closes any open `Auto Release blocked` issue so the GitHub tracker reflects current release health

package/docs/SDK_CONTEXT_INTEGRITY.md

@@ -1,6 +1,6 @@
 # SDK Context Integrity
 
-Tracker: [pm-0k19l7](../.agents/pm/issues/pm-0k19l7.toon), [pm-9stazf](../.agents/pm/issues/pm-9stazf.toon), [pm-tu71](../.agents/pm/issues/pm-tu71.toon), [pm-0xmajx](../.agents/pm/issues/pm-0xmajx.toon), [pm-7rrqsk](../.agents/pm/issues/pm-7rrqsk.toon), [pm-ety1qc](../.agents/pm/issues/pm-ety1qc.toon), [pm-lu6sca](../.agents/pm/features/pm-lu6sca.toon), [pm-5y05kq](../.agents/pm/issues/pm-5y05kq.toon), [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon), [pm-h97qxd](../.agents/pm/issues/pm-h97qxd.toon), [pm-h06944](../.agents/pm/issues/pm-h06944.toon), [pm-5t33or](../.agents/pm/features/pm-5t33or.toon), [pm-in23qu](../.agents/pm/issues/pm-in23qu.toon), [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon), [pm-okgxwa](../.agents/pm/issues/pm-okgxwa.toon), [pm-22rzjp](../.agents/pm/issues/pm-22rzjp.toon), [pm-76fkpp](../.agents/pm/issues/pm-76fkpp.toon), [pm-igdvfq](../.agents/pm/issues/pm-igdvfq.toon), [pm-643e0k](../.agents/pm/issues/pm-643e0k.toon), and [pm-larv4r](../.agents/pm/issues/pm-larv4r.toon).
+Tracker: [pm-0k19l7](../.agents/pm/issues/pm-0k19l7.toon), [pm-9stazf](../.agents/pm/issues/pm-9stazf.toon), [pm-tu71](../.agents/pm/issues/pm-tu71.toon), [pm-0xmajx](../.agents/pm/issues/pm-0xmajx.toon), [pm-7rrqsk](../.agents/pm/issues/pm-7rrqsk.toon), [pm-ety1qc](../.agents/pm/issues/pm-ety1qc.toon), [pm-lu6sca](../.agents/pm/features/pm-lu6sca.toon), [pm-5y05kq](../.agents/pm/issues/pm-5y05kq.toon), [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon), [pm-h97qxd](../.agents/pm/issues/pm-h97qxd.toon), [pm-h06944](../.agents/pm/issues/pm-h06944.toon), [pm-5t33or](../.agents/pm/features/pm-5t33or.toon), [pm-in23qu](../.agents/pm/issues/pm-in23qu.toon), [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon), [pm-okgxwa](../.agents/pm/issues/pm-okgxwa.toon), [pm-22rzjp](../.agents/pm/issues/pm-22rzjp.toon), [pm-76fkpp](../.agents/pm/issues/pm-76fkpp.toon), [pm-igdvfq](../.agents/pm/issues/pm-igdvfq.toon), [pm-643e0k](../.agents/pm/issues/pm-643e0k.toon), [pm-larv4r](../.agents/pm/issues/pm-larv4r.toon), [pm-mcxk8v](../.agents/pm/issues/pm-mcxk8v.toon), and [pm-2zkvxm](../.agents/pm/issues/pm-2zkvxm.toon).
 
 ## Agent Quick Context
 
@@ -81,8 +81,13 @@ text. `verifyPmRecoveryReferences` accepts obligations derived from real error
 envelopes and observations produced by executing a retry, resolving a declared
 command path, or linking prose to an already executed recovery. Its report
 includes the total obligation set, pass fraction, sorted findings, and stable
-coverage buckets for `suggested_retry`, `candidate_command`, `example`, and
-`next_step`, including zero-population buckets.
+coverage buckets for `suggested_retry`, `candidate_command`, `example`,
+`next_step`, `migration_hint`, and `restore_with`, including zero-population
+buckets. `derivePmRecoveryReferenceObligations` walks emitted envelopes and
+generated read-output contracts, so tests cannot silently omit a producer
+family. Each obligation declares `recovery`, `replacement`, or
+`behavior_preserving` semantics and its proof must demonstrate the same
+promise.
 
 The repository integration corpus drives real CLI refusals, executes the
 emitted retry in a temporary tracker, compares candidate commands with the
@@ -128,17 +133,32 @@ SDK callers use `fullHistory: true`; MCP callers use `full: true`. The default s
 
 ## Author acknowledgment coordinates
 
-CLI, SDK, and MCP use the same selector and coordinate parser for `history-author-acknowledge`. A coordinate is `<item-id>:<line>` or `_workspace:<line>`, with a positive one-based line number. Exactly one of explicit events or `all_actionable` is required.
+CLI, SDK, and MCP use the same selector and coordinate parser for `history-author-acknowledge`. A coordinate is `<item-id>:<line>` or `_workspace:<line>`, with a positive one-based line number. Exactly one of explicit events or `all_actionable` is required. Applying is a two-step operation: dry-run returns a deterministic SHA-256 over the complete, ordered coordinate set and every exact source-line hash; apply requires that fingerprint and refuses stale source or selection drift with `CONFLICT` exit 4 before writing history.
 
 ```bash
 pm history-author-acknowledge \
   --event _workspace:4 \
+  --dry-run
+
+pm history-author-acknowledge \
+  --event _workspace:4 \
+  --plan-fingerprint <sha256-from-preview> \
   --attributed-author import-agent \
   --reviewer maintainer \
   --reason "Verified workspace provenance"
 ```
 
-The SDK exposes `resolveUnknownAuthorAcknowledgmentSelector` and `parseUnknownAuthorHistoryEventCoordinates` so packages never need a private copy of this grammar. Health and validate map actionable unknown-author warnings directly to this append-only acknowledgment command instead of sending callers through another diagnostic loop.
+Preview coordinates are bounded with `--limit`, but the fingerprint and counts always cover the complete selection. Plans distinguish already acknowledged coordinates, and apply reports `effect`, `no_effect` (exit 6), or `partial_effect` (exit 7). Bulk selection appends only newly actionable rows, while explicit coordinates may append a superseding disposition as described below. The SDK exposes `planUnknownAuthorHistoryAcknowledgment`, `resolveUnknownAuthorAcknowledgmentSelector`, and `parseUnknownAuthorHistoryEventCoordinates` so packages never need a private copy of this grammar. Health and validate map actionable unknown-author warnings directly to this append-only acknowledgment command instead of sending callers through another diagnostic loop.
+
+An explicit `--event` selection is also the append-only correction path: if a
+coordinate already has a disposition, preview marks it
+`already_acknowledged`, and fingerprint-bound apply appends a later disposition
+that supersedes the earlier attribution. Recover the original coordinates from
+`context.author_acknowledgment.events` in the applicable
+`history/_workspace.jsonl` record, preview those same coordinates, and apply the
+fresh fingerprint with the corrected author and review evidence. By contrast,
+`--all-actionable` intentionally selects only undispositioned rows; an empty
+bulk selection remains `no_effect` and never repeats existing dispositions.
 
 ## Health provider boundary
 
@@ -152,6 +172,14 @@ That agreement check reads only local history and JSON files: mismatched,
 missing, or unreadable singleton paths become bounded `history_drift` evidence
 without enabling embeddings, vector-store access, or any other provider I/O.
 
+Every SDK operation that requires a valid `_workspace` chain refuses the same
+way when verification fails. The typed `workspace_history_chain_invalid`
+conflict includes `verification_errors` in CLI JSON and SDK error context plus
+an executable `pm history _workspace --verify --json` recovery command. This
+keeps deliberate corruption tests and recoverable tracker drift out of the
+unexpected-runtime-error channel without weakening the fail-closed mutation
+boundary.
+
 Brief and summary check-only health projections use the scalar-only metadata
 reader. Validation uses collection-bearing metadata for evidence and
 relationship checks and materializes bodies only when strict history-drift

package/docs/SDK_CONTEXT_TRUTH_CONTRACTS.md

@@ -5,11 +5,11 @@ Tracker references: [pm-23xkss](../.agents/pm/issues/pm-23xkss.toon) and
 
 ## Agent Quick Context
 
-An empty tracker, a missing tracker, and an invalid tracker path are different
-states. Likewise, an optional local Git optimization and a drifted installed
-configuration are different health findings. The SDK preserves these
-distinctions so automation does not infer project truth from an ambiguous empty
-array or a generic failed verdict.
+An empty tracker, a missing tracker, an invalid tracker path, and an unreadable
+tracker are different states. Likewise, an optional local Git optimization and
+a drifted installed configuration are different health findings. The SDK
+preserves these distinctions so automation does not infer project truth from an
+ambiguous empty array or a generic failed verdict.
 
 ## Metadata Root Diagnostics
 
@@ -24,6 +24,11 @@ A missing root throws `PmCliError` with exit code `NOT_FOUND`, diagnostic code
 `tracker_root_missing`, and context reason `missing`. A regular file or other
 non-directory root throws `PmCliError` with exit code `USAGE`, diagnostic code
 `tracker_root_not_directory`, and context reason `not_a_directory`.
+An existing root that cannot be enumerated throws `PmCliError` with exit code
+`GENERIC_FAILURE`, diagnostic code `tracker_root_unreadable`, and context reason
+`unreadable`. On POSIX hosts, enumeration requires both read and directory-search
+permission: a root whose mode lacks either permission is unreadable, even when a
+privileged process could bypass those mode bits.
 
 Consumers should branch on the stable diagnostic code:
 
@@ -35,6 +40,9 @@ try {
   if (error instanceof PmCliError && error.code === "tracker_root_missing") {
     // Ask the caller to select or initialize a tracker.
   }
+  if (error instanceof PmCliError && error.code === "tracker_root_unreadable") {
+    // Repair tracker permissions before trusting any project context.
+  }
 }
 ```
 

package/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Official marketplace for pm CLI — native git-based project management for Claude Code and AI coding agents.",
-    "version": "2026.8.15"
+    "version": "2026.8.16"
   },
   "plugins": [
     {
       "name": "pm-claude",
       "source": "./plugins/pm-claude",
       "description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents, hybrid TUI task tracking, session context injection, and coordination subagents for git-based project management without leaving Claude Code.",
-      "version": "2026.8.15",
+      "version": "2026.8.16",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.8.15",
+  "version": "2026.8.16",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",

package/packages/pm-beads/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-beads",
-  "version": "2026.8.15",
+  "version": "2026.8.16",
   "private": true,
   "type": "module",
   "description": "First-party pm package for importing Beads JSONL records.",

package/packages/pm-calendar/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-calendar",
-  "version": "2026.8.15",
+  "version": "2026.8.16",
   "private": true,
   "type": "module",
   "description": "First-party pm package for calendar and agenda views.",

package/packages/pm-command-kit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-command-kit",
-  "version": "2026.8.15",
+  "version": "2026.8.16",
   "private": true,
   "type": "module",
   "description": "First-party pm exemplar package for the commands capability: registerCommand, registerFlags, and registerParser.",

package/packages/pm-digital-twin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-digital-twin",
-  "version": "2026.8.15",
+  "version": "2026.8.16",
   "private": true,
   "type": "module",
   "description": "Beyond-PM exemplar: a temporal production-facility digital twin built entirely on public pm SDK and extension primitives.",

package/packages/pm-governance-audit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-governance-audit",
-  "version": "2026.8.15",
+  "version": "2026.8.16",
   "private": true,
   "type": "module",
   "description": "First-party pm package for governance audit and normalization workflows.",

package/packages/pm-guide-shell/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-guide-shell",
-  "version": "2026.8.15",
+  "version": "2026.8.16",
   "private": true,
   "type": "module",
   "description": "First-party pm package for guide and shell completion workflows.",

package/packages/pm-kanban/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-kanban",
-  "version": "2026.8.15",
+  "version": "2026.8.16",
   "private": true,
   "type": "module",
   "description": "First-party pm archetype package: a complete Kanban continuous-flow profile built on public SDK primitives.",

package/packages/pm-lifecycle-hooks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-lifecycle-hooks",
-  "version": "2026.8.15",
+  "version": "2026.8.16",
   "private": true,
   "type": "module",
   "description": "First-party pm package demonstrating safe lifecycle hook registration.",

package/packages/pm-linked-test-adapters/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-linked-test-adapters",
-  "version": "2026.8.15",
+  "version": "2026.8.16",
   "private": true,
   "type": "module",
   "description": "First-party pm package for optional linked-test run management adapters and reporters.",

package/packages/pm-search-advanced/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-search-advanced",
-  "version": "2026.8.15",
+  "version": "2026.8.16",
   "private": true,
   "type": "module",
   "description": "First-party pm package for semantic, hybrid, and reindex search workflows.",

package/packages/pm-templates/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-templates",
-  "version": "2026.8.15",
+  "version": "2026.8.16",
   "private": true,
   "type": "module",
   "description": "First-party pm package for reusable create templates.",

package/packages/pm-todos/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-todos",
-  "version": "2026.8.15",
+  "version": "2026.8.16",
   "private": true,
   "type": "module",
   "description": "First-party pm package for Todo markdown import and export.",

package/packages/pm-vcs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-vcs-sdk-exemplar",
-  "version": "2026.8.15",
+  "version": "2026.8.16",
   "private": true,
   "type": "module",
   "description": "Beyond-PM exemplar: a VCS-style changeset workflow built entirely on public pm SDK and extension primitives.",

package/plugins/pm-claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pm-claude",
   "description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents (coordinator, delivery-chain, triage, verification), hybrid TUI task tracking (pm as persistent store + Claude Code task panel as live view), session context injection, and full git-based project management without leaving Claude Code.",
-  "version": "2026.8.15",
+  "version": "2026.8.16",
   "author": {
     "name": "unbrained",
     "url": "https://github.com/unbraind/pm-cli"

package/plugins/pm-codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pm-codex",
-  "version": "2026.8.15",
+  "version": "2026.8.16",
   "description": "Native Codex integration for pm-cli with bundled MCP tools, skills, commands, and agent workflows.",
   "author": {
     "name": "unbrained",