@unbrained/pm-cli 2026.8.7 → 2026.8.9

package/dist/core/shared/author.js

@@ -4,7 +4,7 @@
  * Provides shared primitives and utilities for Author.
  */
 
-!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]="0139d8ef-d286-571f-89f8-7de2f8422f22")}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]="a89b5501-1909-5ea8-b34b-8ca9b4bc5dd5")}catch(e){}}();
 import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash } from "node:crypto";
 import fs from "node:fs";
@@ -31,13 +31,12 @@ export const BUILTIN_HARNESS_SIGNAL_DESCRIPTORS = [
         session_environment_keys: ["CLAUDE_CODE_SESSION_ID"],
         provenance_environment_keys: {
             effort: ["CLAUDE_EFFORT"],
-            role: ["CLAUDE_CODE_CHILD_SESSION"],
         },
         provenance_resolvers: {
             model: "claude_session_file",
             version: "claude_session_file",
         },
-        provenance_unavailable_dimensions: ["topic"],
+        provenance_unavailable_dimensions: ["role", "topic"],
         argv_markers: ["claude", "claude-code"],
         client_names: ["claude", "claude-code", "claude code"],
     },
@@ -192,6 +191,28 @@ function firstEnvironmentValue(env, keys) {
     return undefined;
 }
 function provenanceFromArgv(argv, dimension) {
+    const flaggedValue = provenanceFlagValue(argv, dimension);
+    if (flaggedValue !== undefined)
+        return flaggedValue;
+    if (dimension === "topic") {
+        return argv
+            .slice(0, 16)
+            .map((token) => token.trim())
+            .find((token) => /^pm-[a-z0-9][a-z0-9-]{2,63}$/u.test(token));
+    }
+    if (dimension === "role") {
+        const command = argv
+            .slice(0, 8)
+            .map((token) => token.trim().toLowerCase())
+            .find((token) => ["claim", "create", "update", "close", "release", "review"].includes(token));
+        if (command === "review")
+            return "reviewer";
+        if (command)
+            return "implementer";
+    }
+    return undefined;
+}
+function provenanceFlagValue(argv, dimension) {
     const acceptedFlags = dimension === "model"
         ? ["--model", "--agent-model"]
         : [`--agent-${dimension}`];
@@ -208,6 +229,21 @@ function provenanceFromArgv(argv, dimension) {
     }
     return undefined;
 }
+const AGENT_ROLE_VALUES = new Set([
+    "implementation",
+    "implementer",
+    "investigator",
+    "orchestrator",
+    "planner",
+    "release-operator",
+    "reviewer",
+]);
+function normalizeProvenanceValue(dimension, value) {
+    if (dimension !== "role" || value === undefined)
+        return value;
+    const normalized = value.trim().toLowerCase().replaceAll(/[_\s]+/gu, "-");
+    return AGENT_ROLE_VALUES.has(normalized) ? normalized : undefined;
+}
 function boundedProvenanceValue(provenance, dimension) {
     return nonBlank(provenance?.[dimension])?.slice(0, 256);
 }
@@ -307,7 +343,7 @@ function resolveAgentProvenanceObservation(dimension, signals, env, descriptor,
     let overrideValue;
     let argvValue;
     if (hostResolvedDimensions.has(dimension)) {
-        overrideValue = nonBlank(env[overrideKey])?.slice(0, 256);
+        overrideValue = normalizeProvenanceValue(dimension, nonBlank(env[overrideKey])?.slice(0, 256));
         argvValue = provenanceFromArgv(signals.argv ?? [], dimension);
     }
     const environmentKeysByDimension = {
@@ -321,10 +357,10 @@ function resolveAgentProvenanceObservation(dimension, signals, env, descriptor,
     const values = [
         overrideValue,
         boundedProvenanceValue(sessionContext?.provenance, dimension),
-        firstEnvironmentValue(env, environmentKeysByDimension[dimension]),
-        boundedProvenanceValue(clientProvenance, dimension),
-        boundedProvenanceValue(signals.provenance, dimension),
-        argvValue,
+        normalizeProvenanceValue(dimension, firstEnvironmentValue(env, environmentKeysByDimension[dimension])),
+        normalizeProvenanceValue(dimension, boundedProvenanceValue(clientProvenance, dimension)),
+        normalizeProvenanceValue(dimension, boundedProvenanceValue(signals.provenance, dimension)),
+        normalizeProvenanceValue(dimension, argvValue),
         resolveProvenanceProbe(dimension, signals, env, descriptor),
     ];
     const sources = [
@@ -469,6 +505,75 @@ export function detectAgentIdentity(signals) {
     ];
     return Object.fromEntries(entries.filter((entry) => entry[1] !== undefined));
 }
+function resolveProvenanceOutcome(dimension, identity, descriptor, env, probesEnabled, invalidValue) {
+    const resolver = descriptor?.provenance_resolvers[dimension];
+    if (identity.provenance?.[dimension]) {
+        return {
+            status: "resolved",
+            ...(resolver ? { resolver } : {}),
+            rule_version: "v1",
+        };
+    }
+    if (invalidValue) {
+        return {
+            status: "unavailable",
+            reason: "invalid_value",
+            rule_version: "v1",
+        };
+    }
+    if (resolver) {
+        const resolverHasInput = resolver === "ai_agent_version"
+            ? nonBlank(env.AI_AGENT) !== undefined
+            : nonBlank(env.CLAUDE_CODE_SESSION_ID) !== undefined;
+        const status = resolverHasInput && probesEnabled ? "failed" : "unavailable";
+        const reason = !resolverHasInput
+            ? "harness_unavailable"
+            : probesEnabled
+                ? "resolver_failed"
+                : "probes_disabled";
+        return { status, reason, resolver, rule_version: "v1" };
+    }
+    return {
+        status: "unavailable",
+        reason: descriptor?.provenance_unavailable_dimensions.includes(dimension)
+            ? "harness_unavailable"
+            : "resolver_not_configured",
+        rule_version: "v1",
+    };
+}
+/**
+ * Diagnose provenance without exposing environment values, paths, or probe data.
+ *
+ * This additive SDK contract keeps legacy `detectAgentIdentity` projections
+ * stable while giving health checks and history writers explicit absence states.
+ */
+export function diagnoseAgentIdentity(signals) {
+    const effectiveSignals = effectiveHarnessDetectionSignals(signals);
+    const identity = detectAgentIdentity(effectiveSignals);
+    const descriptor = currentHarnessSignalDescriptors(effectiveSignals.descriptors).find((candidate) => candidate.harness === identity.harness);
+    const env = effectiveSignals.env ?? {};
+    const probesEnabled = effectiveSignals.probes_enabled !== false &&
+        workspaceHarnessSignalsStorage.getStore()?.probesEnabled !== false &&
+        !["0", "false", "off"].includes(nonBlank(env.PM_AGENT_PROBES)?.toLowerCase() ?? "");
+    const sessionContext = resolveAgentSessionContextFromSignals(effectiveSignals, env);
+    const invalidRoleValue = [
+        env.PM_AGENT_ROLE,
+        sessionContext.provenance?.role,
+        firstEnvironmentValue(env, descriptor?.provenance_environment_keys.role),
+        effectiveSignals.client_info?.provenance?.role,
+        effectiveSignals.provenance?.role,
+        provenanceFlagValue(effectiveSignals.argv ?? [], "role"),
+    ].some((candidate) => {
+        const value = nonBlank(candidate)?.slice(0, 256);
+        return (value !== undefined &&
+            normalizeProvenanceValue("role", value) === undefined);
+    });
+    const outcomes = Object.fromEntries(AGENT_PROVENANCE_DIMENSIONS.map((dimension) => [
+        dimension,
+        resolveProvenanceOutcome(dimension, identity, descriptor, env, probesEnabled, dimension === "role" && invalidRoleValue),
+    ]));
+    return { ...identity, provenance_outcomes: outcomes };
+}
 /** Reads the invocation-wide author override through the canonical environment seam. */
 export function readAuthorEnvironment() {
     return process.env.PM_AUTHOR;
@@ -575,4 +680,4 @@ export function resolveAuthor(candidate, fallback) {
     return identity.author;
 }
 //# sourceMappingURL=author.js.map
-//# debugId=0139d8ef-d286-571f-89f8-7de2f8422f22
+//# debugId=a89b5501-1909-5ea8-b34b-8ca9b4bc5dd5

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/actionability.d.ts

@@ -7,4 +7,4 @@
  * blocker or ready-work classifications without storage or rendering side
  * effects.
  */
-export { collectBlockedByIds, collectDependencyBlockedIds, computeActionabilityReport, resolveItemBlockers, type ActionabilityReport, type ActionableEntry, type ResolvedBlocker, } from "../core/item/actionability.js";
+export { ACTIONABILITY_ORDERING_KINDS, collectBlockedByIds, collectBlockedByIdsFromCorpus, collectDependencyBlockedIds, computeActionabilityReport, indexBlockedByIds, resolveItemBlockers, type ActionabilityReport, type ActionableEntry, type ResolvedBlocker, } from "../core/item/actionability.js";

package/dist/sdk/actionability.js

@@ -8,7 +8,7 @@
  * effects.
  */
 
-!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]="9184e723-8269-5e45-8c6a-52fd02da60e6")}catch(e){}}();
-export { collectBlockedByIds, collectDependencyBlockedIds, computeActionabilityReport, resolveItemBlockers, } from "../core/item/actionability.js";
+!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]="cc271a73-9767-54bb-a142-d4d4569e3c6a")}catch(e){}}();
+export { ACTIONABILITY_ORDERING_KINDS, collectBlockedByIds, collectBlockedByIdsFromCorpus, collectDependencyBlockedIds, computeActionabilityReport, indexBlockedByIds, resolveItemBlockers, } from "../core/item/actionability.js";
 //# sourceMappingURL=actionability.js.map
-//# debugId=9184e723-8269-5e45-8c6a-52fd02da60e6
+//# debugId=cc271a73-9767-54bb-a142-d4d4569e3c6a

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