@unbrained/pm-cli 2026.8.15 → 2026.8.17

package/dist/sdk/author-attribution.js

@@ -4,7 +4,8 @@
  * Provides reusable diagnostics for mutation-author provenance in tracker history.
  */
 
-!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]="4fd16197-979e-5269-bed7-f2fb0e2038c2")}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]="b389e521-f689-5895-a5f4-08c3866b3ea3")}catch(e){}}();
+import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { appendWorkspaceAuditEvent, WORKSPACE_HISTORY_ID, } from "../core/history/workspace-history.js";
@@ -204,6 +205,111 @@ export const scanHistoryAuthorAttribution = async (pmRoot, sampleLimit = 20, inc
         ...(includeActionableEvents ? { actionable_events: actionableEvents } : {}),
     };
 };
+/** Deduplicate and deterministically order history coordinates. */
+function normalizeUnknownAuthorHistoryEvents(events) {
+    return [
+        ...new Map(events.map((event) => [
+            `${event.item_id}:${event.line}`,
+            { item_id: event.item_id, line: event.line },
+        ])).values(),
+    ].sort((left, right) => left.item_id.localeCompare(right.item_id) || left.line - right.line);
+}
+/** Read the append-only set of previously dispositioned coordinates. */
+async function readAcknowledgedUnknownEvents(pmRoot) {
+    try {
+        return collectAcknowledgedUnknownEvents(await fs.readFile(path.join(pmRoot, "history", "_workspace.jsonl"), "utf8"));
+    }
+    catch {
+        return new Set();
+    }
+}
+/** Check whether a coordinate can safely name one immutable history line. */
+function isValidUnknownAuthorHistoryEvent(event) {
+    return ((event.item_id === WORKSPACE_HISTORY_ID ||
+        /^[a-z0-9][a-z0-9-]*$/iu.test(event.item_id)) &&
+        Number.isSafeInteger(event.line) &&
+        event.line >= 1);
+}
+/** Resolve one coordinate against its preloaded immutable source stream. */
+function resolveAcknowledgmentPlanCoordinate(event, acknowledgedEvents, sourceLines) {
+    const sourceLine = sourceLines[event.line - 1] ?? "";
+    let parsed;
+    try {
+        parsed = JSON.parse(sourceLine);
+    }
+    catch {
+        refuseAuthorAcknowledgmentArgument(`Unknown-author acknowledgment target ${event.item_id}:${event.line} is not readable.`, { code: "history_author_acknowledge_target_unreadable" });
+    }
+    if (classifyHistoryAuthorEvent(parsed) !== "actionable_unknown") {
+        refuseAuthorAcknowledgmentArgument(`Author acknowledgment target ${event.item_id}:${event.line} is not an actionable unknown-author event.`, { code: "history_author_acknowledge_target_not_actionable" });
+    }
+    return {
+        ...event,
+        source_event_hash: createHash("sha256").update(sourceLine).digest("hex"),
+        disposition: acknowledgedEvents.has(`${event.item_id}:${event.line}`)
+            ? "already_acknowledged"
+            : "actionable",
+    };
+}
+async function resolveUnknownAuthorAcknowledgmentPlan(pmRoot, selector, coordinateLimit) {
+    const explicitEvents = selector.events ?? [];
+    const selectorCount = Number(selector.all_actionable === true) +
+        Number(explicitEvents.length > 0);
+    if (selectorCount === 0) {
+        refuseAuthorAcknowledgmentArgument("Specify exactly one selector: events or all_actionable.", { code: "history_author_acknowledge_selector_required" });
+    }
+    if (selectorCount > 1) {
+        refuseAuthorAcknowledgmentArgument("Author acknowledgment accepts either explicit events or all_actionable, not both.", { code: "history_author_acknowledge_selector_conflict" });
+    }
+    if (!Number.isSafeInteger(coordinateLimit) || coordinateLimit < 0) {
+        refuseAuthorAcknowledgmentArgument("Author acknowledgment coordinate_limit must be a non-negative integer.", { code: "history_author_acknowledge_preview_limit_invalid" });
+    }
+    const selectedEvents = normalizeUnknownAuthorHistoryEvents(selector.all_actionable === true
+        ? (await scanHistoryAuthorAttribution(pmRoot, 0, true))
+            .actionable_events
+        : explicitEvents);
+    const acknowledgedEvents = await readAcknowledgedUnknownEvents(pmRoot);
+    const sourceLinesByItem = new Map();
+    for (const event of selectedEvents) {
+        if (!isValidUnknownAuthorHistoryEvent(event)) {
+            refuseAuthorAcknowledgmentArgument(`Unknown-author acknowledgment target ${event.item_id}:${event.line} is not readable.`, { code: "history_author_acknowledge_target_unreadable" });
+        }
+        if (sourceLinesByItem.has(event.item_id))
+            continue;
+        try {
+            sourceLinesByItem.set(event.item_id, (await fs.readFile(path.join(pmRoot, "history", `${event.item_id}.jsonl`), "utf8")).split(/\r?\n/u));
+        }
+        catch {
+            refuseAuthorAcknowledgmentArgument(`Unknown-author acknowledgment target ${event.item_id}:${event.line} is not readable.`, { code: "history_author_acknowledge_target_unreadable" });
+        }
+    }
+    const completeCoordinates = selectedEvents.map((event) => resolveAcknowledgmentPlanCoordinate(event, acknowledgedEvents, sourceLinesByItem.get(event.item_id)));
+    const kind = selector.all_actionable === true ? "all_actionable" : "events";
+    const planFingerprint = createHash("sha256")
+        .update(JSON.stringify({
+        version: 1,
+        selection: kind,
+        coordinates: completeCoordinates,
+    }))
+        .digest("hex");
+    const actionableCount = completeCoordinates.filter(({ disposition }) => disposition === "actionable").length;
+    return {
+        plan: {
+            selection: { kind },
+            selected_count: completeCoordinates.length,
+            actionable_count: actionableCount,
+            already_acknowledged_count: completeCoordinates.length - actionableCount,
+            omitted_count: Math.max(0, completeCoordinates.length - coordinateLimit),
+            coordinates: completeCoordinates.slice(0, coordinateLimit),
+            plan_fingerprint: planFingerprint,
+        },
+        completeCoordinates,
+    };
+}
+/** Resolve a deterministic, source-bound author-acknowledgement preview. */
+export async function planUnknownAuthorHistoryAcknowledgment(pmRoot, selector, coordinateLimit = 50) {
+    return (await resolveUnknownAuthorAcknowledgmentPlan(pmRoot, selector, coordinateLimit)).plan;
+}
 /** Resolve the mutually exclusive CLI and SDK acknowledgment selectors. */
 export function resolveUnknownAuthorAcknowledgmentSelector(rawEvents, allActionable) {
     const hasExplicitEvents = rawEvents.length > 0;
@@ -254,11 +360,19 @@ export function acknowledgeUnknownAuthorHistoryEventsFromTransport(pmRoot, input
     return acknowledgeUnknownAuthorHistoryEvents(pmRoot, {
         events: selector.events,
         all_actionable: selector.all_actionable,
+        dry_run: input.dryRun === true || input.dry_run === true,
+        plan_fingerprint: readRuntimeString(input, "planFingerprint") ??
+            readRuntimeString(input, "plan_fingerprint"),
+        coordinate_limit: typeof input.limit === "number"
+            ? input.limit
+            : typeof input.limit === "string"
+                ? Number(input.limit)
+                : undefined,
         attributed_author: readRuntimeString(input, "attributedAuthor") ??
             readRuntimeString(input, "attributed_author") ??
-            "",
-        reviewer: readRuntimeString(input, "reviewer") ?? "",
-        reason: readRuntimeString(input, "reason") ?? "",
+            undefined,
+        reviewer: readRuntimeString(input, "reviewer"),
+        reason: readRuntimeString(input, "reason"),
     });
 }
 /**
@@ -266,23 +380,21 @@ export function acknowledgeUnknownAuthorHistoryEventsFromTransport(pmRoot, input
  * rewriting their original streams.
  */
 export async function acknowledgeUnknownAuthorHistoryEvents(pmRoot, options) {
-    const reviewer = options.reviewer.trim();
-    const attributedAuthor = options.attributed_author.trim();
-    const reason = options.reason.trim();
-    const explicitEvents = options.events ?? [];
-    const selectorCount = Number(options.all_actionable === true) + Number(explicitEvents.length > 0);
-    if (selectorCount === 0) {
-        refuseAuthorAcknowledgmentArgument("Specify exactly one selector: events or all_actionable.", { code: "history_author_acknowledge_selector_required" });
+    const reviewer = options.reviewer?.trim() ?? "";
+    const attributedAuthor = options.attributed_author?.trim() ?? "";
+    const reason = options.reason?.trim() ?? "";
+    const resolved = await resolveUnknownAuthorAcknowledgmentPlan(pmRoot, options, options.coordinate_limit ?? 50);
+    if (options.dry_run === true) {
+        return {
+            dry_run: true,
+            mutated: false,
+            acknowledged: 0,
+            outcome: "preview",
+            exit_code: EXIT_CODE.SUCCESS,
+            plan: resolved.plan,
+        };
     }
-    if (selectorCount > 1) {
-        refuseAuthorAcknowledgmentArgument("Author acknowledgment accepts either explicit events or all_actionable, not both.", { code: "history_author_acknowledge_selector_conflict" });
-    }
-    const selectedEvents = options.all_actionable === true
-        ? (await scanHistoryAuthorAttribution(pmRoot, 0, true))
-            .actionable_events
-        : explicitEvents;
     const requiredValuesMissing = [
-        selectedEvents.length > 0,
         reviewer.length > 0,
         reviewer.toLowerCase() !== "unknown",
         attributedAuthor.length > 0,
@@ -292,34 +404,35 @@ export async function acknowledgeUnknownAuthorHistoryEvents(pmRoot, options) {
     if (requiredValuesMissing) {
         refuseAuthorAcknowledgmentArgument("Author acknowledgment requires events, reviewer, attributed_author, and reason.", { code: "history_author_acknowledge_required_values_missing" });
     }
-    const uniqueEvents = [
-        ...new Map(selectedEvents.map((event) => [
-            `${event.item_id}:${event.line}`,
-            { item_id: event.item_id, line: event.line },
-        ])).values(),
-    ].sort((left, right) => left.item_id.localeCompare(right.item_id) || left.line - right.line);
-    for (const event of uniqueEvents) {
-        const invalidCoordinate = [
-            event.item_id === WORKSPACE_HISTORY_ID ||
-                /^[a-z0-9][a-z0-9-]*$/i.test(event.item_id),
-            Number.isSafeInteger(event.line),
-            event.line >= 1,
-        ].includes(false);
-        if (invalidCoordinate) {
-            refuseAuthorAcknowledgmentArgument(`Unknown-author acknowledgment target ${event.item_id}:${event.line} is not readable.`, { code: "history_author_acknowledge_target_unreadable" });
-        }
-        let parsed;
-        try {
-            const raw = await fs.readFile(path.join(pmRoot, "history", `${event.item_id}.jsonl`), "utf8");
-            const line = raw.split(/\r?\n/)[event.line - 1];
-            parsed = JSON.parse(line ?? "");
-        }
-        catch {
-            refuseAuthorAcknowledgmentArgument(`Unknown-author acknowledgment target ${event.item_id}:${event.line} is not readable.`, { code: "history_author_acknowledge_target_unreadable" });
-        }
-        if (classifyHistoryAuthorEvent(parsed) !== "actionable_unknown") {
-            refuseAuthorAcknowledgmentArgument(`Author acknowledgment target ${event.item_id}:${event.line} is not an actionable unknown-author event.`, { code: "history_author_acknowledge_target_not_actionable" });
-        }
+    if (!options.plan_fingerprint?.trim()) {
+        refuseAuthorAcknowledgmentArgument("Author acknowledgment apply requires plan_fingerprint from a fresh dry-run preview.", {
+            code: "history_author_acknowledge_plan_fingerprint_required",
+            recovery: {
+                suggested_retry: "Rerun history-author-acknowledge with --dry-run, then pass --plan-fingerprint <value>.",
+            },
+        });
+    }
+    if (options.plan_fingerprint.trim() !== resolved.plan.plan_fingerprint) {
+        throw new PmCliError("Author acknowledgment selection changed after preview; no history was mutated.", EXIT_CODE.CONFLICT, {
+            code: "history_author_acknowledge_plan_conflict",
+            recovery: {
+                suggested_retry: "Rerun history-author-acknowledge with --dry-run and apply the fresh plan_fingerprint.",
+            },
+        });
+    }
+    const eventsToAcknowledge = resolved.completeCoordinates
+        .filter(({ disposition }) => resolved.plan.selection.kind === "events" ||
+        disposition === "actionable")
+        .map(({ item_id, line }) => ({ item_id, line }));
+    if (eventsToAcknowledge.length === 0) {
+        return {
+            dry_run: false,
+            mutated: false,
+            acknowledged: 0,
+            outcome: "no_effect",
+            exit_code: EXIT_CODE.NO_EFFECT,
+            plan: resolved.plan,
+        };
     }
     const settings = await readSettings(pmRoot);
     const appended = await appendWorkspaceAuditEvent({
@@ -328,7 +441,7 @@ export async function acknowledgeUnknownAuthorHistoryEvents(pmRoot, options) {
         author: reviewer,
         context: {
             author_acknowledgment: {
-                events: uniqueEvents,
+                events: eventsToAcknowledge,
                 attributed_author: attributedAuthor,
             },
         },
@@ -336,10 +449,21 @@ export async function acknowledgeUnknownAuthorHistoryEvents(pmRoot, options) {
         lockTtlSeconds: settings.locks.ttl_seconds,
         lockWaitMs: settings.locks.wait_ms,
     });
+    const effectResult = resolved.plan.actionable_count > 0 &&
+        resolved.plan.already_acknowledged_count > 0
+        ? {
+            outcome: "partial_effect",
+            exit_code: EXIT_CODE.PARTIAL_EFFECT,
+        }
+        : { outcome: "effect", exit_code: EXIT_CODE.SUCCESS };
     return {
-        acknowledged: uniqueEvents.length,
+        dry_run: false,
+        mutated: true,
+        acknowledged: eventsToAcknowledge.length,
+        ...effectResult,
+        plan: resolved.plan,
         history_path: appended.historyPath,
     };
 }
 //# sourceMappingURL=author-attribution.js.map
-//# debugId=4fd16197-979e-5269-bed7-f2fb0e2038c2
+//# debugId=b389e521-f689-5895-a5f4-08c3866b3ea3

package/dist/sdk/cli-contracts/flag-contracts.js

@@ -7,7 +7,7 @@
  * flag surface stays single-sourced across the CLI, SDK, and MCP boundaries.
  */
 
-!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]="512c41c1-624f-517c-abc3-4448b49cd9e6")}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]="c82d9b50-274f-585d-be0e-9a0c5067b9e9")}catch(e){}}();
 import { normalizeUniqueStringList } from "./string-lists.js";
 import { RESERVED_EXTENSION_HOST_FLAGS } from "../../core/extensions/reserved-host-flags.js";
 function normalizeFlagAliasKey(flag) {
@@ -351,6 +351,9 @@ export const HISTORY_REPAIR_FLAG_CONTRACTS = [
 export const HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS = [
     { flag: "--event", repeatable: true },
     { flag: "--all-actionable" },
+    { flag: "--dry-run" },
+    { flag: "--plan-fingerprint" },
+    { flag: "--limit", value_type: "number" },
     { flag: "--attributed-author", aliases: ["--attributed_author"] },
     { flag: "--reviewer" },
     { flag: "--reason" },
@@ -1818,4 +1821,4 @@ export function toCompletionFlagString(flagContracts, includeGlobal = true) {
     return normalizeUniqueStringList(all).join(" ");
 }
 //# sourceMappingURL=flag-contracts.js.map
-//# debugId=512c41c1-624f-517c-abc3-4448b49cd9e6
+//# debugId=c82d9b50-274f-585d-be0e-9a0c5067b9e9

package/dist/sdk/cli-contracts/tool-parameter-tables.js

@@ -4,7 +4,7 @@
  * Defines SDK command-contract metadata for Tool Parameter Tables.
  */
 
-!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]="ddb90f7e-f3ca-56d8-be75-13e238da306c")}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]="4749819e-f2af-5a17-9d32-2e2770c497c3")}catch(e){}}();
 import { PLAN_HARNESS_VALUES, PLAN_MODE_VALUES, PLAN_STEP_LINK_KIND_VALUES, PLAN_STEP_STATUS_VALUES, } from "../../types/index.js";
 import { PM_READ_OUTPUT_SESSION_MAX_SEEN_ITEM_IDS } from "../read-output-session.js";
 import { ASSURANCE_DEFINITION_SCHEMA } from "./schemas/assurance-definition.js";
@@ -229,6 +229,7 @@ export const PM_TOOL_PARAMETER_PROPERTIES = {
     parent: { type: "string" },
     reviewer: { type: "string" },
     attributedAuthor: { type: "string" },
+    planFingerprint: { type: "string", pattern: "^[a-f0-9]{64}$" },
     historyEvent: { type: "array", items: { type: "string" } },
     risk: { type: "string" },
     confidence: { anyOf: [{ type: "string" }, { type: "number" }] },
@@ -663,6 +664,7 @@ export const PM_TOOL_ACTION_SCOPED_PARAMETER_PROPERTIES = {
                 "apply",
                 "derive",
                 "promote",
+                "risk",
             ],
         },
         preset: {
@@ -1197,6 +1199,12 @@ export const PM_TOOL_PARAMETER_METADATA = {
         description: "Unknown-author history target in <item-id>:<one-based-line> form.",
         examples: [["pm-example:4", "pm-example:5"]],
     },
+    planFingerprint: {
+        description: "Exact SHA-256 returned by a history-author-acknowledge dry-run preview; apply refuses stale or changed source coordinates.",
+        examples: [
+            "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+        ],
+    },
     estimate: {
         description: "Estimated effort in minutes.",
         examples: [60, "120"],
@@ -1886,8 +1894,8 @@ export const PM_TOOL_PARAMETER_METADATA = {
 export const PM_TOOL_ACTION_SCOPED_PARAMETER_METADATA = {
     assurance: {
         subcommand: {
-            description: "Assurance operation: list, show, put, remove, run, verdicts, presets, apply, derive, or promote.",
-            examples: ["list", "run", "derive", "promote"],
+            description: "Assurance operation: list, show, put, remove, run, verdicts, presets, apply, derive, promote, or risk.",
+            examples: ["list", "run", "derive", "promote", "risk"],
         },
         kind: {
             description: "Assurance declaration kind for registry operations: measurement, assertion, or gate.",
@@ -2059,4 +2067,4 @@ export const PM_TOOL_ACTION_SCOPED_PARAMETER_METADATA = {
     },
 };
 //# sourceMappingURL=tool-parameter-tables.js.map
-//# debugId=ddb90f7e-f3ca-56d8-be75-13e238da306c
+//# debugId=4749819e-f2af-5a17-9d32-2e2770c497c3

package/dist/sdk/cli-contracts/tool-schema.js

@@ -7,7 +7,7 @@
  * consumers from a single source of truth.
  */
 
-!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]="aa58e280-0a39-5285-a451-811e60481661")}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]="1d6089b2-ab59-59ad-a475-9a6ef1356b40")}catch(e){}}();
 import { normalizeUniqueStringList } from "./string-lists.js";
 import { PM_TOOL_ACTIONS } from "./enum-contracts.js";
 import { TOOL_CREATE_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_MANY_FILTER_OPTION_CONTRACTS, TOOL_CONTEXT_OPTION_CONTRACTS, TOOL_ACTIVITY_OPTION_CONTRACTS, TOOL_LIST_FILTER_OPTION_CONTRACTS, TOOL_AGGREGATE_OPTION_CONTRACTS, TOOL_SEARCH_FILTER_OPTION_CONTRACTS, TOOL_CLOSE_MANY_FILTER_OPTION_CONTRACTS, } from "./tool-option-contracts.js";
@@ -632,8 +632,16 @@ const PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
         oneOfRequired: [["id"], ["all"]],
     },
     "history-author-acknowledge": {
-        required: ["attributedAuthor", "reviewer", "reason"],
-        optional: ["historyEvent", "allActionable"],
+        optional: [
+            "historyEvent",
+            "allActionable",
+            "dryRun",
+            "planFingerprint",
+            "limit",
+            "attributedAuthor",
+            "reviewer",
+            "reason",
+        ],
         oneOfRequired: [["historyEvent"], ["allActionable"]],
     },
     "history-compact": {
@@ -1580,4 +1588,4 @@ export const _testOnlyCliContracts = {
     withFlagAliasMetadata,
 };
 //# sourceMappingURL=tool-schema.js.map
-//# debugId=aa58e280-0a39-5285-a451-811e60481661
+//# debugId=1d6089b2-ab59-59ad-a475-9a6ef1356b40

package/dist/sdk/completion.js

@@ -4,11 +4,11 @@
  * Implements the pm completion command surface and its agent-facing runtime behavior.
  */
 
-!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]="fca471b1-155a-5fc4-9aa9-d45e5f1315dd")}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]="c337a436-ac3e-5447-9c76-de9aeebb2a1c")}catch(e){}}();
 import { EXIT_CODE, PmCliError } from "./runtime-primitives.js";
 import { listPmCommandsForTier } from "./agent-capability-contracts.js";
 import { SCAFFOLD_CAPABILITIES } from "./extension/scaffold.js";
-import { AGGREGATE_FLAG_CONTRACTS, ACTIVITY_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, CONTEXT_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, MEET_FLAG_CONTRACTS, REMIND_FLAG_CONTRACTS, CREATE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, NEXT_FLAG_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PLAN_FLAG_CONTRACTS, SEARCH_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, EVENTS_FLAG_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, toCompletionFlagString, } from "./cli-contracts.js";
+import { AGGREGATE_FLAG_CONTRACTS, ACTIVITY_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, CONTEXT_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, MEET_FLAG_CONTRACTS, REMIND_FLAG_CONTRACTS, CREATE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, NEXT_FLAG_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PLAN_FLAG_CONTRACTS, SEARCH_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, EVENTS_FLAG_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, toCompletionFlagString, } from "./cli-contracts.js";
 import { BUILTIN_ITEM_TYPE_VALUES, STATUS_VALUES } from "../types/index.js";
 import { listGuideTopicIds } from "./guide-topics.js";
 const VALID_SHELLS = ["bash", "zsh", "fish"];
@@ -29,6 +29,7 @@ const UPDATE_MANY_FLAGS = toCompletionFlagString(UPDATE_MANY_FLAG_CONTRACTS);
 const CLOSE_MANY_FLAGS = toCompletionFlagString(CLOSE_MANY_FLAG_CONTRACTS);
 const ACTIVITY_FLAGS = toCompletionFlagString(ACTIVITY_FLAG_CONTRACTS);
 const HISTORY_FLAGS = toCompletionFlagString(HISTORY_FLAG_CONTRACTS);
+const HISTORY_AUTHOR_ACKNOWLEDGE_FLAGS = toCompletionFlagString(HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, false);
 const EVENTS_FLAGS = toCompletionFlagString(EVENTS_FLAG_CONTRACTS);
 const CALENDAR_FLAGS = toCompletionFlagString(CALENDAR_FLAG_CONTRACTS);
 const CONTEXT_FLAGS = toCompletionFlagString(CONTEXT_FLAG_CONTRACTS);
@@ -648,7 +649,7 @@ export function generateBashScript(itemTypes = [], tags = [], eagerTagExpansion
         `      COMPREPLY=(${compgen("--before --ids --all-over --closed --all-streams --min-entries --dry-run --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
         "      ;;",
         "    history-author-acknowledge)",
-        `      COMPREPLY=(${compgen("--event --all-actionable --attributed-author --reviewer --reason --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
+        `      COMPREPLY=(${compgen(`${HISTORY_AUTHOR_ACKNOWLEDGE_FLAGS} --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help`)})`,
         "      ;;",
         "    get)",
         `      COMPREPLY=(${compgen(GET_FLAGS)})`,
@@ -1199,6 +1200,9 @@ ${zshSearchRuntimeFieldFlags}            '--json[Output JSON]' \\
           _arguments \\
             '*--event[Actionable unknown-author event]:item_and_line' \\
             '--all-actionable[Select every currently actionable event]' \\
+            '--dry-run[Preview a deterministic source-bound plan]' \\
+            '--plan-fingerprint[Apply the exact dry-run plan]:sha256' \\
+            '--limit[Maximum coordinate rows returned in the plan]:number' \\
             '--attributed-author[Principal attributed by maintainer review]:author' \\
             '--reviewer[Reviewer recording the disposition]:reviewer' \\
             '--reason[Evidence-backed review rationale]:reason' \\
@@ -2308,6 +2312,9 @@ complete -c pm -n '__fish_seen_subcommand_from history-compact' -l message -d 'A
 complete -c pm -n '__fish_seen_subcommand_from history-compact' -l force -d 'Force ownership/lock override'
 complete -c pm -n '__fish_seen_subcommand_from history-author-acknowledge' -l event -d 'Actionable unknown-author event' -r
 complete -c pm -n '__fish_seen_subcommand_from history-author-acknowledge' -l all-actionable -d 'Select every currently actionable event'
+complete -c pm -n '__fish_seen_subcommand_from history-author-acknowledge' -l dry-run -d 'Preview a deterministic source-bound plan'
+complete -c pm -n '__fish_seen_subcommand_from history-author-acknowledge' -l plan-fingerprint -d 'Apply the exact dry-run plan' -r
+complete -c pm -n '__fish_seen_subcommand_from history-author-acknowledge' -l limit -d 'Maximum coordinate rows returned in the plan' -r
 complete -c pm -n '__fish_seen_subcommand_from history-author-acknowledge' -l attributed-author -d 'Principal attributed by maintainer review' -r
 complete -c pm -n '__fish_seen_subcommand_from history-author-acknowledge' -l reviewer -d 'Reviewer recording the disposition' -r
 complete -c pm -n '__fish_seen_subcommand_from history-author-acknowledge' -l reason -d 'Evidence-backed review rationale' -r
@@ -2762,4 +2769,4 @@ export function runCompletion(shell, itemTypes = [], tags = [], eagerTagExpansio
     };
 }
 //# sourceMappingURL=completion.js.map
-//# debugId=fca471b1-155a-5fc4-9aa9-d45e5f1315dd
+//# debugId=c337a436-ac3e-5447-9c76-de9aeebb2a1c

package/dist/sdk/compose.d.ts

@@ -460,7 +460,7 @@ export interface ExtensionManifestCompatibilityManifest {
  * load, while `*_unchecked`/`*_exceeded_warn` are advisory (the extension still
  * loads).
  */
-export type ExtensionManifestCompatibilityCode = "pm_min_version_invalid" | "pm_min_version_unchecked" | "pm_min_version_unmet" | "pm_max_version_invalid" | "pm_max_version_unchecked" | "pm_max_version_exceeded" | "pm_max_version_exceeded_warn";
+export type ExtensionManifestCompatibilityCode = "pm_min_version_invalid" | "pm_min_version_unchecked" | "pm_min_version_unmet" | "pm_max_version_invalid" | "pm_max_version_unchecked" | "pm_max_version_exceeded" | "pm_max_version_exceeded_warn" | "manifest_unknown_key" | "no_version_bounds_declared";
 /**
  * A single version-bound issue {@link checkExtensionManifestCompatibility} found
  * when evaluating a manifest against a target pm version.
@@ -471,13 +471,17 @@ export interface ExtensionManifestCompatibilityFinding {
     /** `error` when the bound blocks the load against the target version, `warning` when it is advisory. */
     severity: "error" | "warning";
     /** Which manifest bound produced the finding. */
-    constraint: PmVersionBoundKind;
+    constraint: PmVersionBoundKind | "manifest";
     /** The declared bound value, verbatim. */
     required: string;
     /** The target pm version the bound was evaluated against. */
     current: string;
     /** Human-readable explanation of the outcome and its effect on loading. */
     message: string;
+    /** JSON-style manifest location responsible for a schema-level finding. */
+    path?: string;
+    /** Canonical manifest key that replaces a recognized legacy or mistaken spelling. */
+    suggested_key?: "pm_min_version" | "pm_max_version";
 }
 /**
  * The structured result of {@link checkExtensionManifestCompatibility}.

package/dist/sdk/compose.js

@@ -1,10 +1,11 @@
 
-!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]="fb438c6a-1927-54c3-98dd-dd7423df6722")}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]="705476d3-74b8-540d-b646-956e24f703d4")}catch(e){}}();
 import { normalizeKnownExtensionCapability, resolveLegacyExtensionCapabilityAlias, } from "../core/extensions/extension-capability-aliases.js";
 import { normalizeCommandName } from "../core/extensions/extension-runtime-helpers.js";
 import { RESERVED_ITEM_FIELD_NAMES } from "../core/extensions/item-fields.js";
 import { describeExtensionLongFlagFailure, findExtensionFlagTokenFailure, } from "../core/extensions/flag-definition-validation.js";
 import { evaluatePmMaxVersionBound, evaluatePmMinVersionBound, } from "../core/extensions/version-compat.js";
+import { inspectExtensionManifestSchema } from "../core/extensions/manifest-schema.js";
 /**
  * Typed identity helper for extension module exports.
  *
@@ -903,7 +904,7 @@ function toCompatibilityFinding(evaluation, pmVersion) {
         return null;
     }
     const code = `${evaluation.kind}_${evaluation.status}`;
-    let message;
+    let message = "";
     switch (code) {
         case "pm_min_version_invalid":
             message = `pm_min_version "${evaluation.required}" is not a valid version; the extension is treated as incompatible and the loader skips it.`;
@@ -962,6 +963,35 @@ export function checkExtensionManifestCompatibility(manifest, target) {
     const minEvaluation = evaluatePmMinVersionBound(manifest.pm_min_version, target.pmVersion);
     const maxEvaluation = evaluatePmMaxVersionBound(manifest.pm_max_version, target.pmVersion, target.pmMaxVersionExceededMode ?? "block");
     const findings = [];
+    const schema = inspectExtensionManifestSchema(manifest);
+    for (const key of schema.unknownKeys) {
+        findings.push({
+            code: "manifest_unknown_key",
+            severity: "warning",
+            constraint: "manifest",
+            required: key,
+            current: target.pmVersion,
+            path: key,
+            ...(key === "compatibility"
+                ? { suggested_key: "pm_min_version" }
+                : {}),
+            message: key === "compatibility"
+                ? 'Manifest key "compatibility" is ignored; declare the canonical pm_min_version and optional pm_max_version fields instead.'
+                : `Manifest key "${key}" is not part of the extension manifest contract and will be ignored.`,
+        });
+    }
+    if (schema.missingVersionBounds) {
+        findings.push({
+            code: "no_version_bounds_declared",
+            severity: "warning",
+            constraint: "manifest",
+            required: "pm_min_version",
+            current: target.pmVersion,
+            path: "$",
+            suggested_key: "pm_min_version",
+            message: "No canonical pm version bounds are declared; add pm_min_version so compatibility intent is explicit.",
+        });
+    }
     const minFinding = toCompatibilityFinding(minEvaluation, target.pmVersion);
     if (minFinding !== null) {
         findings.push(minFinding);
@@ -1071,4 +1101,4 @@ export function preflightExtension(blueprint, options = {}) {
     };
 }
 //# sourceMappingURL=compose.js.map
-//# debugId=fb438c6a-1927-54c3-98dd-dd7423df6722
+//# debugId=705476d3-74b8-540d-b646-956e24f703d4

package/dist/sdk/context-intent-contracts.d.ts

@@ -29,15 +29,19 @@ export interface PmContextIntentReceipt {
     included_field_groups: string[];
     /** Effective token ceiling after an explicit caller override is applied. */
     token_budget: number;
-    /** Deterministic JSON-size estimate for the result including this receipt. */
+    /** Ceiling declared by the selected intent before caller overrides. */
+    declared_token_budget: number;
+    /** Signed difference between the effective and declared ceilings. */
+    token_budget_override: number;
+    /** Deterministic JSON-size estimate for the useful result before any receipt-only omission. */
     estimated_tokens: number;
-    /** Whether the measured result fits the declared ceiling. */
+    /** Whether the measured result fits the effective ceiling after caller overrides. */
     within_budget: boolean;
     /** Projection strategy applied before the result was measured. */
     degradation: "bounded_fields_and_rows" | "bounded_ranked_rows" | "bounded_sections" | "budget_row_compaction" | "recursive_budget_compaction" | "budget_receipt_only" | "standard_item" | "none";
-    /** Whether the declared ceiling can carry at least one useful result row. */
+    /** Whether the declared ceiling can carry the measured useful projection, independent of an override. */
     declaration_feasible: boolean;
-    /** True only when no useful result survived the declared ceiling. */
+    /** True only when no useful result survived the effective ceiling. */
     result_omitted: boolean;
     /** Row ceiling calculated from the selected intent's effective token budget. */
     budget_derived_limit?: number;