@unbrained/pm-cli 2026.8.7 → 2026.8.8

package/dist/cli.js

@@ -5,13 +5,14 @@
  * Bootstraps the executable pm CLI entrypoint and startup optimizations.
  */
 
-!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]="46833198-bc44-5ed4-b685-51434f93d8df")}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]="81ec2fa2-c616-5978-999d-b76d5f45bafe")}catch(e){}}();
 import fs from "node:fs";
 import * as nodeModule from "node:module";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { runCliWithBundleIntegrity, } from "./cli/bundle-integrity.js";
+import { runCliWithBundleIntegrity } from "./cli/bundle-integrity.js";
+import { runRuntimeCompatibleCli } from "./cli/runtime-compatibility-boundary.js";
 import { pruneCompileCacheGenerations, resolveCompileCacheGeneration, } from "./sdk/compile-cache.js";
 function enableNodeCompileCache() {
     const { enableCompileCache } = nodeModule;
@@ -90,7 +91,16 @@ export const _testOnly = {
 if (!printFastVersionIfRequested()) {
     enableNodeCompileCache();
     const cliEntrypointPath = fileURLToPath(import.meta.url);
-    await runCliWithBundleIntegrity(process.argv.slice(2), cliEntrypointPath, () => import("./cli-bundle/main.js"), process.stderr.write.bind(process.stderr));
+    const executingVersion = readPackageVersionForPath(cliEntrypointPath);
+    const invocationArgv = process.argv.slice(2);
+    await runRuntimeCompatibleCli({
+        executingVersion,
+        projectRoot: process.cwd(),
+        argv: invocationArgv,
+        allowStale: process.env.PM_ALLOW_STALE_CLI === "1",
+        run: () => runCliWithBundleIntegrity(invocationArgv, cliEntrypointPath, () => import("./cli-bundle/main.js"), process.stderr.write.bind(process.stderr)),
+        writeError: process.stderr.write.bind(process.stderr),
+    });
 }
 //# sourceMappingURL=cli.js.map
-//# debugId=46833198-bc44-5ed4-b685-51434f93d8df
+//# debugId=81ec2fa2-c616-5978-999d-b76d5f45bafe

package/dist/core/output/output.js

@@ -4,7 +4,7 @@
  * Formats compact human and machine output for Output.
  */
 
-!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]="4a84286a-e1e3-5465-94c9-b44f8e4472d5")}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]="b52d2756-f640-5f53-981f-05fa23fa1718")}catch(e){}}();
 import { getActiveCommandContext, runActiveCommandOverride, runActiveRendererOverride, runActiveServiceOverrideSync, setActiveCommandResult, } from "../extensions/index.js";
 import { EXIT_CODE } from "../shared/constants.js";
 import { isHostOutputSuppressed } from "./output-control.js";
@@ -12,6 +12,7 @@ import { projectMutationResult } from "./mutation-projection.js";
 import { attachReadOutputContracts } from "../../sdk/context-intent-contracts.js";
 import { attachOutputTokenAccounting } from "../../sdk/output-token-accounting.js";
 import { resolveReadOutputEncoding } from "../../sdk/read-output-contracts.js";
+const DECLARED_PROCESS_EXIT_CODES = new Set(Object.values(EXIT_CODE));
 const NATIVE_OUTPUT_MARKER = "__pm_native_output";
 let streamErrorHandlersInstalled = false;
 function isPlainObject(value) {
@@ -388,6 +389,12 @@ export function formatOutput(result, options) {
 }
 /** Implements print result for the public runtime surface of this module. */
 export function printResult(result, options) {
+    if (isPlainObject(result) &&
+        Number.isInteger(result.exit_code) &&
+        DECLARED_PROCESS_EXIT_CODES.has(Number(result.exit_code)) &&
+        (process.exitCode === undefined || process.exitCode === EXIT_CODE.SUCCESS)) {
+        process.exitCode = Number(result.exit_code);
+    }
     const projected = options.idOnly
         ? projectMutationResult(result, { idOnly: true })
         : options.fullChangedFields
@@ -417,4 +424,4 @@ export const outputTestOnly = {
     renderToonValue,
 };
 //# sourceMappingURL=output.js.map
-//# debugId=4a84286a-e1e3-5465-94c9-b44f8e4472d5
+//# debugId=b52d2756-f640-5f53-981f-05fa23fa1718

package/dist/core/sentry/helpers.d.ts

@@ -15,6 +15,16 @@ export declare function sentryFinishCommandSpan(ok: boolean, error?: string, met
     command_resolution?: TelemetryCommandResolution;
     resolution_stage?: TelemetryResolutionStage;
 }): void;
+/**
+ * Tag value recorded when a captured error declares no canonical pm error code.
+ *
+ * The release reliability gate classifies Sentry issues from the `pm.error_code`
+ * and `pm.exit_code` tags and fails closed when either is absent. Emitting this
+ * sentinel keeps the producer side of that contract total: an undeclared runtime
+ * fault is still classifiable (and still blocks, because it resolves to no
+ * catalog contract) instead of being unjudgeable for lack of a tag.
+ */
+export declare const UNCLASSIFIED_CAPTURED_ERROR_CODE = "unclassified_runtime_error";
 /** Implements sentry capture cli error for the public runtime surface of this module. */
 export declare function sentryCaptureCliError(error: unknown): void;
 /** Implements sentry log cli usage error for the public runtime surface of this module. */

package/dist/core/sentry/helpers.js

@@ -4,7 +4,7 @@
  * Integrates Sentry instrumentation and release diagnostics for Helpers.
  */
 
-!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]="48cce5c1-5cca-53cc-8991-f97669251a72")}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]="ffe56aed-b794-5bf4-99fd-e3c5fe065163")}catch(e){}}();
 import { getSentry } from "./instrument.js";
 import { PmCliError } from "../shared/errors.js";
 import { EXIT_CODE } from "../shared/constants.js";
@@ -110,6 +110,60 @@ export function sentryFinishCommandSpan(ok, error, metadata) {
     activeCommandSpan.end();
     activeCommandSpan = undefined;
 }
+/**
+ * Tag value recorded when a captured error declares no canonical pm error code.
+ *
+ * The release reliability gate classifies Sentry issues from the `pm.error_code`
+ * and `pm.exit_code` tags and fails closed when either is absent. Emitting this
+ * sentinel keeps the producer side of that contract total: an undeclared runtime
+ * fault is still classifiable (and still blocks, because it resolves to no
+ * catalog contract) instead of being unjudgeable for lack of a tag.
+ */
+export const UNCLASSIFIED_CAPTURED_ERROR_CODE = "unclassified_runtime_error";
+/**
+ * Reads the declared error contract carried by a thrown value, if any.
+ *
+ * There is deliberately no `PmCliError` special case: `shouldCaptureCliError`
+ * rejects every `PmCliError` before capture, so such a branch would be
+ * unreachable — and a `PmCliError` carries a public `code` and a numeric
+ * `exitCode`, so the general path below would classify it identically anyway.
+ */
+function readCapturedErrorContract(error) {
+    const candidate = typeof error === "object" && error !== null
+        ? error
+        : undefined;
+    const hasDeclaredExitCode = typeof candidate?.exitCode === "number";
+    const exitCode = hasDeclaredExitCode
+        ? Math.trunc(candidate?.exitCode)
+        : EXIT_CODE.GENERIC_FAILURE;
+    // A declared pm code always travels with a numeric exit code. Requiring both
+    // halves keeps a Node errno error (string `code`, no `exitCode`) from being
+    // reported as though it were a catalog contract.
+    const hasDeclaredErrorCode = typeof candidate?.code === "string" &&
+        candidate.code.length > 0 &&
+        hasDeclaredExitCode;
+    return {
+        error_code: hasDeclaredErrorCode
+            ? candidate?.code
+            : UNCLASSIFIED_CAPTURED_ERROR_CODE,
+        exit_code: exitCode,
+    };
+}
+/**
+ * Builds the contract tags every captured event carries.
+ *
+ * These are attached to the event itself rather than to the ambient scope
+ * because the scope writer (`sentryFinishCommandSpan`) returns early when no
+ * command span is active, and the unknown-error path captures before that
+ * writer runs.
+ */
+function buildCapturedErrorTags(error) {
+    const contract = readCapturedErrorContract(error);
+    return {
+        "pm.error_code": contract.error_code,
+        "pm.exit_code": String(contract.exit_code),
+    };
+}
 /** Implements sentry capture cli error for the public runtime surface of this module. */
 export function sentryCaptureCliError(error) {
     if (!shouldCaptureCliError(error))
@@ -117,6 +171,7 @@ export function sentryCaptureCliError(error) {
     const Sentry = getSentry();
     if (!Sentry)
         return;
+    const tags = buildCapturedErrorTags(error);
     if (error instanceof Error) {
         const extras = {};
         if ("exitCode" in error &&
@@ -127,10 +182,10 @@ export function sentryCaptureCliError(error) {
             typeof error.context === "object") {
             extras.error_context = error.context;
         }
-        Sentry.captureException(error, { extra: extras });
+        Sentry.captureException(error, { extra: extras, tags });
     }
     else {
-        Sentry.captureException(new Error(String(error)));
+        Sentry.captureException(new Error(String(error)), { tags });
     }
 }
 /** Implements sentry log cli usage error for the public runtime surface of this module. */
@@ -215,4 +270,4 @@ export async function sentryFlush(timeoutMs = 3000) {
     }
 }
 //# sourceMappingURL=helpers.js.map
-//# debugId=48cce5c1-5cca-53cc-8991-f97669251a72
+//# debugId=ffe56aed-b794-5bf4-99fd-e3c5fe065163

package/dist/core/shared/constants.d.ts

@@ -58,6 +58,8 @@ export declare const EXIT_CODE: {
     readonly NOT_FOUND: 3;
     readonly CONFLICT: 4;
     readonly DEPENDENCY_FAILED: 5;
+    readonly NO_EFFECT: 6;
+    readonly PARTIAL_EFFECT: 7;
 };
 /** Restricts telemetry error category values accepted by command, SDK, and storage contracts. */
 export type TelemetryErrorCategory = "usage" | "validation" | "conflict" | "runtime" | "unknown";

package/dist/core/shared/constants.js

@@ -1,5 +1,5 @@
 
-!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]="46d7e58b-d1b6-5f9d-86cb-76ca671ed127")}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]="36b908f0-ea19-5adc-8ccd-320ad3c3b1fe")}catch(e){}}();
 import { createDefaultExtensionGovernancePolicy } from "../extensions/extension-types.js";
 /**
  * Canonical default lifecycle status model and workflow role mapping.
@@ -421,6 +421,8 @@ export const EXIT_CODE = {
     NOT_FOUND: 3,
     CONFLICT: 4,
     DEPENDENCY_FAILED: 5,
+    NO_EFFECT: 6,
+    PARTIAL_EFFECT: 7,
 };
 /** Public contract for telemetry error category by code, shared by SDK and presentation-layer consumers. */
 export const TELEMETRY_ERROR_CATEGORY_BY_CODE = Object.freeze({
@@ -475,4 +477,4 @@ export function resolveTelemetryErrorCategory(errorCode) {
     return "unknown";
 }
 //# sourceMappingURL=constants.js.map
-//# debugId=46d7e58b-d1b6-5f9d-86cb-76ca671ed127
+//# debugId=36b908f0-ea19-5adc-8ccd-320ad3c3b1fe

package/dist/sdk/annotations.d.ts

@@ -23,7 +23,45 @@ export interface AnnotationCommandOptions {
     force?: boolean;
     /** Whether list results include paging metadata. */
     includeMeta?: boolean;
+    /** Return the complete collection after a mutation instead of the bounded mutation receipt. */
+    fullHistory?: boolean;
 }
+/** Identifies the single annotation mutation represented by a bounded response. */
+export interface AnnotationMutationReceipt {
+    /** Mutation applied to the annotation collection. */
+    action: "add" | "edit" | "delete";
+    /** Stable one-based collection position targeted by the mutation. */
+    entry_index: number;
+    /** Number of stored entries changed by the mutation. */
+    changed_count: 1;
+    /** Whether the response includes the complete post-mutation collection. */
+    full_history_included: boolean;
+}
+/** Transport-neutral selectors that restore a complete annotation collection. */
+export interface AnnotationHistoryRestoration {
+    /** Stable semantic selector shared by every transport. */
+    selector: "full_history";
+    /** Equivalent CLI flag. */
+    cli_flag: "--full-history";
+    /** Equivalent direct SDK option. */
+    sdk_option: "fullHistory";
+    /** Equivalent MCP tool option. */
+    mcp_option: "full";
+}
+/** Describes annotation history withheld from a bounded mutation response. */
+export interface AnnotationOmissionReceipt {
+    /** Whether any historical collection entries were withheld. */
+    has_omissions: boolean;
+    /** Number of independently restorable field groups withheld. */
+    omitted_field_group_count: number;
+    /** Omitted groups and the transport-neutral selectors that restore them. */
+    omitted_field_groups: Array<{
+        name: string;
+        restore_with: AnnotationHistoryRestoration;
+    }>;
+}
+/** Map transport-level `full` onto the SDK annotation history option. */
+export declare function normalizeAnnotationTransportOptions(options: Record<string, unknown>): Record<string, unknown>;
 /** Presentation-layer inputs accepted by the shared annotation source resolver. */
 export interface AnnotationSourceOptions {
     /** Inline annotation text or the stdin token (`-`). */
@@ -93,6 +131,8 @@ export type AnnotationCommandResult<TKey extends string, TEntry extends Annotati
     returned_count?: number;
     has_more?: boolean;
     limit?: number;
+    mutation_receipt?: AnnotationMutationReceipt;
+    omission_receipt?: AnnotationOmissionReceipt;
 };
 /** Implements limit annotation entries for the public runtime surface of this module. */
 export declare function limitAnnotationEntries<TEntry>(values: TEntry[], limit: number | undefined): TEntry[];

package/dist/sdk/annotations.js

@@ -4,7 +4,7 @@
  * Implements the pm annotation command 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]="eeb7b433-094b-5c4f-bc81-d4988ac297b4")}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]="13cf8bd9-0aee-5838-a6eb-de9f87ddfac7")}catch(e){}}();
 import { readFile } from "node:fs/promises";
 import { pathExists } from "../core/fs/fs-utils.js";
 import { getActiveExtensionRegistrations } from "../core/extensions/index.js";
@@ -18,6 +18,15 @@ import { resolveAuthor } from "../core/shared/author.js";
 import { locateItem, mutateItem, readLocatedItem, } from "../core/store/item-store.js";
 import { getSettingsPath, resolvePmRoot } from "../core/store/paths.js";
 import { readSettings } from "../core/store/settings.js";
+/** Map transport-level `full` onto the SDK annotation history option. */
+export function normalizeAnnotationTransportOptions(options) {
+    const normalized = {
+        ...options,
+        ...(options.full === true ? { fullHistory: true } : {}),
+    };
+    delete normalized.full;
+    return normalized;
+}
 /** Reject mutation of canonical structured events while allowing ordinary annotations. */
 function assertAnnotationEntryMutable(entry, operation) {
     if (typeof entry === "object" &&
@@ -249,7 +258,10 @@ export async function runAnnotationCommand(id, options, global, config) {
             wrapOwnershipConflict(error, config.conflictGuidance);
         }
         const allEntries = readAnnotationEntries(result.item, config.collectionKey);
-        return renderAnnotationResult(result.item.id, config.collectionKey, allEntries, limit, options.includeMeta === true);
+        return renderAnnotationResult(result.item.id, config.collectionKey, allEntries, limit, options.includeMeta === true, {
+            action: "delete",
+            entryIndex: config.input.index,
+        }, options.fullHistory === true);
     }
     const rawText = config.input.rawValue ?? config.input.value ?? "";
     assertAnnotationAddValueIsNotFlagLike(rawText, config);
@@ -289,7 +301,11 @@ export async function runAnnotationCommand(id, options, global, config) {
             wrapOwnershipConflict(error, config.conflictGuidance);
         }
         const allEntries = readAnnotationEntries(result.item, config.collectionKey);
-        return renderAnnotationResult(result.item.id, config.collectionKey, allEntries, limit, options.includeMeta === true);
+        return renderAnnotationResult(result.item.id, config.collectionKey, allEntries, limit, options.includeMeta === true, {
+            action: "edit",
+            entryIndex: config.input.index,
+            entry: allEntries[config.input.index - 1],
+        }, options.fullHistory === true);
     }
     let result;
     try {
@@ -315,7 +331,11 @@ export async function runAnnotationCommand(id, options, global, config) {
         wrapOwnershipConflict(error, config.conflictGuidance);
     }
     const allEntries = readAnnotationEntries(result.item, config.collectionKey);
-    return renderAnnotationResult(result.item.id, config.collectionKey, allEntries, limit, options.includeMeta === true);
+    return renderAnnotationResult(result.item.id, config.collectionKey, allEntries, limit, options.includeMeta === true, {
+        action: "add",
+        entryIndex: allEntries.length,
+        entry: allEntries.at(-1),
+    }, options.fullHistory === true);
 }
 /** Implements resolve annotation index for the public runtime surface of this module. */
 export function resolveAnnotationIndex(oneBasedIndex, count, collectionKey) {
@@ -330,21 +350,53 @@ export function resolveAnnotationIndex(oneBasedIndex, count, collectionKey) {
     }
     return oneBasedIndex - 1;
 }
-function renderAnnotationResult(id, collectionKey, allEntries, limit, includeMeta) {
-    const entries = limitAnnotationEntries(allEntries, limit);
+function renderAnnotationResult(id, collectionKey, allEntries, limit, includeMeta, mutation, fullHistory = false) {
+    const entries = mutation === undefined || fullHistory
+        ? limitAnnotationEntries(allEntries, mutation !== undefined && fullHistory ? undefined : limit)
+        : mutation.entry === undefined
+            ? []
+            : [mutation.entry];
+    const historyOmitted = mutation !== undefined && entries.length < allEntries.length;
     return {
         id,
         [collectionKey]: entries,
         count: entries.length,
-        ...(includeMeta
+        ...([includeMeta, mutation !== undefined].includes(true)
             ? {
                 total_count: allEntries.length,
                 returned_count: entries.length,
-                has_more: entries.length < allEntries.length,
+                has_more: historyOmitted || entries.length < allEntries.length,
                 ...(limit !== undefined ? { limit } : {}),
             }
             : {}),
+        ...(mutation === undefined
+            ? {}
+            : {
+                mutation_receipt: {
+                    action: mutation.action,
+                    entry_index: mutation.entryIndex,
+                    changed_count: 1,
+                    full_history_included: !historyOmitted,
+                },
+                omission_receipt: {
+                    has_omissions: historyOmitted,
+                    omitted_field_group_count: historyOmitted ? 1 : 0,
+                    omitted_field_groups: historyOmitted
+                        ? [
+                            {
+                                name: `${collectionKey}_history`,
+                                restore_with: {
+                                    selector: "full_history",
+                                    cli_flag: "--full-history",
+                                    sdk_option: "fullHistory",
+                                    mcp_option: "full",
+                                },
+                            },
+                        ]
+                        : [],
+                },
+            }),
     };
 }
 //# sourceMappingURL=annotations.js.map
-//# debugId=eeb7b433-094b-5c4f-bc81-d4988ac297b4
+//# debugId=13cf8bd9-0aee-5838-a6eb-de9f87ddfac7

package/dist/sdk/author-attribution.d.ts

@@ -52,6 +52,18 @@ export interface AcknowledgeUnknownAuthorEventsOptions {
     /** Evidence-backed rationale for the attribution. */
     reason: string;
 }
+/** Resolve the mutually exclusive CLI and SDK acknowledgment selectors. */
+export declare function resolveUnknownAuthorAcknowledgmentSelector(rawEvents: readonly string[], allActionable: boolean): {
+    events: UnknownAuthorHistoryEvent[];
+    all_actionable: boolean;
+};
+/** Parse user-facing item or workspace history coordinates into SDK events. */
+export declare function parseUnknownAuthorHistoryEventCoordinates(values: readonly string[]): UnknownAuthorHistoryEvent[];
+/** Normalize an untyped transport payload and execute author acknowledgment. */
+export declare function acknowledgeUnknownAuthorHistoryEventsFromTransport(pmRoot: string, input: Record<string, unknown>): Promise<{
+    acknowledged: number;
+    history_path: string;
+}>;
 /**
  * Append an audited disposition for immutable unknown-author events without
  * rewriting their original streams.

package/dist/sdk/author-attribution.js

@@ -4,13 +4,14 @@
  * 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]="09427917-8347-59cc-9358-452671aed3c3")}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]="4fd16197-979e-5269-bed7-f2fb0e2038c2")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
-import { appendWorkspaceAuditEvent } from "../core/history/workspace-history.js";
+import { appendWorkspaceAuditEvent, WORKSPACE_HISTORY_ID, } from "../core/history/workspace-history.js";
 import { readSettings } from "../core/store/settings.js";
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
+import { readRuntimeString, readRuntimeStringArray } from "./runtime-input.js";
 /**
  * Refuse an acknowledgment argument as a classified usage error.
  *
@@ -22,8 +23,8 @@ import { PmCliError } from "../core/shared/errors.js";
  * keeps expected validation out of the error channel without masking genuine
  * failures, which retain their own exit codes.
  */
-function refuseAuthorAcknowledgmentArgument(message, code) {
-    throw new PmCliError(message, EXIT_CODE.USAGE, { code });
+function refuseAuthorAcknowledgmentArgument(message, context) {
+    throw new PmCliError(message, EXIT_CODE.USAGE, context);
 }
 /** First release-governance anchor after which unknown authors require remediation. */
 export const HISTORY_AUTHOR_ATTRIBUTION_BASELINE = "2026-07-15T06:22:12.276Z";
@@ -203,6 +204,63 @@ export const scanHistoryAuthorAttribution = async (pmRoot, sampleLimit = 20, inc
         ...(includeActionableEvents ? { actionable_events: actionableEvents } : {}),
     };
 };
+/** Resolve the mutually exclusive CLI and SDK acknowledgment selectors. */
+export function resolveUnknownAuthorAcknowledgmentSelector(rawEvents, allActionable) {
+    const hasExplicitEvents = rawEvents.length > 0;
+    if (hasExplicitEvents && allActionable) {
+        refuseAuthorAcknowledgmentArgument("Specify exactly one selector: repeat --event or pass --all-actionable.", {
+            code: "history_author_acknowledge_selector_conflict",
+            required: "Exactly one of --event or --all-actionable",
+            examples: [
+                'pm history-author-acknowledge --event pm-a1b2:4 --attributed-author agent --reviewer maintainer --reason "Verified provenance"',
+                'pm history-author-acknowledge --all-actionable --attributed-author import-agent --reviewer maintainer --reason "Reviewed the complete actionable set"',
+            ],
+        });
+    }
+    if (!hasExplicitEvents && !allActionable) {
+        refuseAuthorAcknowledgmentArgument("Specify exactly one selector: repeat --event or pass --all-actionable.", {
+            code: "history_author_acknowledge_selector_required",
+            required: "Exactly one of --event or --all-actionable",
+            examples: [
+                'pm history-author-acknowledge --event pm-a1b2:4 --attributed-author agent --reviewer maintainer --reason "Verified provenance"',
+                'pm history-author-acknowledge --all-actionable --attributed-author import-agent --reviewer maintainer --reason "Reviewed the complete actionable set"',
+            ],
+        });
+    }
+    return {
+        events: parseUnknownAuthorHistoryEventCoordinates(rawEvents),
+        all_actionable: allActionable,
+    };
+}
+/** Parse user-facing item or workspace history coordinates into SDK events. */
+export function parseUnknownAuthorHistoryEventCoordinates(values) {
+    return values.map((value) => {
+        const separator = value.lastIndexOf(":");
+        const itemId = value.slice(0, separator).trim();
+        const line = Number(value.slice(separator + 1));
+        const validItemId = itemId === WORKSPACE_HISTORY_ID || /^[a-z0-9][a-z0-9-]*$/iu.test(itemId);
+        if (separator < 1 ||
+            !validItemId ||
+            !Number.isSafeInteger(line) ||
+            line < 1) {
+            refuseAuthorAcknowledgmentArgument(`history-author-acknowledge --event expects <item-id>:<one-based-line>, received "${value}".`, { code: "history_author_acknowledge_target_unreadable" });
+        }
+        return { item_id: itemId, line };
+    });
+}
+/** Normalize an untyped transport payload and execute author acknowledgment. */
+export function acknowledgeUnknownAuthorHistoryEventsFromTransport(pmRoot, input) {
+    const selector = resolveUnknownAuthorAcknowledgmentSelector(readRuntimeStringArray(input.historyEvent), input.allActionable === true || input.all_actionable === true);
+    return acknowledgeUnknownAuthorHistoryEvents(pmRoot, {
+        events: selector.events,
+        all_actionable: selector.all_actionable,
+        attributed_author: readRuntimeString(input, "attributedAuthor") ??
+            readRuntimeString(input, "attributed_author") ??
+            "",
+        reviewer: readRuntimeString(input, "reviewer") ?? "",
+        reason: readRuntimeString(input, "reason") ?? "",
+    });
+}
 /**
  * Append an audited disposition for immutable unknown-author events without
  * rewriting their original streams.
@@ -213,8 +271,11 @@ export async function acknowledgeUnknownAuthorHistoryEvents(pmRoot, options) {
     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" });
+    }
     if (selectorCount > 1) {
-        refuseAuthorAcknowledgmentArgument("Author acknowledgment accepts either explicit events or all_actionable, not both.", "history_author_acknowledge_selector_conflict");
+        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))
@@ -229,7 +290,7 @@ export async function acknowledgeUnknownAuthorHistoryEvents(pmRoot, options) {
         reason.length > 0,
     ].includes(false);
     if (requiredValuesMissing) {
-        refuseAuthorAcknowledgmentArgument("Author acknowledgment requires events, reviewer, attributed_author, and reason.", "history_author_acknowledge_required_values_missing");
+        refuseAuthorAcknowledgmentArgument("Author acknowledgment requires events, reviewer, attributed_author, and reason.", { code: "history_author_acknowledge_required_values_missing" });
     }
     const uniqueEvents = [
         ...new Map(selectedEvents.map((event) => [
@@ -239,12 +300,13 @@ export async function acknowledgeUnknownAuthorHistoryEvents(pmRoot, options) {
     ].sort((left, right) => left.item_id.localeCompare(right.item_id) || left.line - right.line);
     for (const event of uniqueEvents) {
         const invalidCoordinate = [
-            /^[a-z0-9][a-z0-9-]*$/i.test(event.item_id),
+            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.`, "history_author_acknowledge_target_unreadable");
+            refuseAuthorAcknowledgmentArgument(`Unknown-author acknowledgment target ${event.item_id}:${event.line} is not readable.`, { code: "history_author_acknowledge_target_unreadable" });
         }
         let parsed;
         try {
@@ -253,10 +315,10 @@ export async function acknowledgeUnknownAuthorHistoryEvents(pmRoot, options) {
             parsed = JSON.parse(line ?? "");
         }
         catch {
-            refuseAuthorAcknowledgmentArgument(`Unknown-author acknowledgment target ${event.item_id}:${event.line} is not readable.`, "history_author_acknowledge_target_unreadable");
+            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.`, "history_author_acknowledge_target_not_actionable");
+            refuseAuthorAcknowledgmentArgument(`Author acknowledgment target ${event.item_id}:${event.line} is not an actionable unknown-author event.`, { code: "history_author_acknowledge_target_not_actionable" });
         }
     }
     const settings = await readSettings(pmRoot);
@@ -280,4 +342,4 @@ export async function acknowledgeUnknownAuthorHistoryEvents(pmRoot, options) {
     };
 }
 //# sourceMappingURL=author-attribution.js.map
-//# debugId=09427917-8347-59cc-9358-452671aed3c3
+//# debugId=4fd16197-979e-5269-bed7-f2fb0e2038c2