@unbrained/pm-cli 2026.8.15 → 2026.8.16

package/dist/core/history/workspace-history.js

@@ -5,7 +5,7 @@
  * HistoryEntry format used by item mutations.
  */
 
-!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]="0f666995-78f8-5741-ae0c-0d792feea599")}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]="9027d972-ce29-5511-ba81-27e17d97446e")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { readFileIfExists, writeFileAtomic } from "../fs/fs-utils.js";
@@ -54,6 +54,28 @@ function workspaceDocuments(document) {
         ? document.metadata.documents
         : {};
 }
+/** Refuse a workspace mutation or replay whose append-only chain is invalid. */
+function throwWorkspaceHistoryVerificationFailure(errors) {
+    throw new PmCliError(`Workspace history verification failed: ${errors.join(", ")}`, EXIT_CODE.CONFLICT, {
+        code: "workspace_history_chain_invalid",
+        reason: "workspace_history_chain_verification_failed",
+        verification_errors: [...errors],
+        required: "Repair the _workspace history chain before reading, reconciling, restoring, or appending audited singleton state.",
+        why: "Continuing against an unverifiable append-only stream could hide or compound workspace state corruption.",
+        examples: [
+            "pm history _workspace --verify --json",
+            "pm validate --check-history-drift --fix-hints --json",
+        ],
+        nextSteps: [
+            "Inspect the exact verification_errors and preserve the corrupt stream as evidence.",
+            "Use the history-drift remediation returned by validate before retrying the refused operation.",
+        ],
+        recovery: {
+            recovery_mode: "compact",
+            next_best_command: "pm history _workspace --verify --json",
+        },
+    });
+}
 /** Resolve a governed singleton path and reject paths outside the tracker root. */
 function resolveGovernedDocumentPath(pmRoot, filePath) {
     const absolutePath = path.resolve(filePath);
@@ -76,7 +98,7 @@ export async function inspectWorkspaceHistoryState(pmRoot) {
     const entries = await readHistoryEntries(getWorkspaceHistoryPath(pmRoot), WORKSPACE_HISTORY_ID);
     const verification = verifyHistoryChain(entries);
     if (!verification.ok) {
-        throw new TypeError(`Workspace history verification failed: ${verification.errors.join(", ")}`);
+        throwWorkspaceHistoryVerificationFailure(verification.errors);
     }
     const documents = workspaceDocuments(entries.length === 0
         ? EMPTY_CANONICAL_DOCUMENT
@@ -123,7 +145,7 @@ async function appendWorkspaceHistoryChangeLocked(change) {
     const entries = await readHistoryEntries(historyPath, WORKSPACE_HISTORY_ID);
     const verification = verifyHistoryChain(entries);
     if (!verification.ok) {
-        throw new TypeError(`Workspace history verification failed: ${verification.errors.join(", ")}`);
+        throwWorkspaceHistoryVerificationFailure(verification.errors);
     }
     const idempotentEntry = change.idempotencyKey === undefined
         ? undefined
@@ -194,7 +216,7 @@ export async function appendWorkspaceAuditEvent(options) {
         const entries = await readHistoryEntries(historyPath, WORKSPACE_HISTORY_ID);
         const verification = verifyHistoryChain(entries);
         if (!verification.ok) {
-            throw new TypeError(`Workspace history verification failed: ${verification.errors.join(", ")}`);
+            throwWorkspaceHistoryVerificationFailure(verification.errors);
         }
         const beforeDocument = entries.length === 0
             ? EMPTY_CANONICAL_DOCUMENT
@@ -303,7 +325,7 @@ export async function reconcileWorkspaceJsonHistory(options) {
         const entries = await readHistoryEntries(historyPath, WORKSPACE_HISTORY_ID);
         const verification = verifyHistoryChain(entries);
         if (!verification.ok) {
-            throw new TypeError(`Workspace history verification failed: ${verification.errors.join(", ")}`);
+            throwWorkspaceHistoryVerificationFailure(verification.errors);
         }
         const beforeDocument = replayWorkspaceEntries(entries);
         const priorDocuments = workspaceDocuments(beforeDocument);
@@ -349,15 +371,15 @@ export async function restoreWorkspaceJsonFromHistory(options) {
     try {
         const { documentPath, absolutePath } = resolveGovernedDocumentPath(options.pmRoot, options.filePath);
         const entries = await readHistoryEntries(getWorkspaceHistoryPath(options.pmRoot), WORKSPACE_HISTORY_ID);
+        const verification = verifyHistoryChain(entries);
+        if (!verification.ok) {
+            throwWorkspaceHistoryVerificationFailure(verification.errors);
+        }
         if (!Number.isInteger(options.targetVersion) ||
             options.targetVersion < 1 ||
             options.targetVersion > entries.length) {
             throw new TypeError(`Invalid workspace history target version: ${String(options.targetVersion)}`);
         }
-        const verification = verifyHistoryChain(entries);
-        if (!verification.ok) {
-            throw new TypeError(`Workspace history verification failed: ${verification.errors.join(", ")}`);
-        }
         const target = workspaceDocuments(replayWorkspaceEntries(entries, options.targetVersion))[documentPath];
         if (target === undefined) {
             throw new TypeError(`Workspace history version ${options.targetVersion} does not contain ${documentPath}`);
@@ -408,4 +430,4 @@ export async function restoreWorkspaceJsonFromHistory(options) {
     }
 }
 //# sourceMappingURL=workspace-history.js.map
-//# debugId=0f666995-78f8-5741-ae0c-0d792feea599
+//# debugId=9027d972-ce29-5511-ba81-27e17d97446e

package/dist/core/output/output.js

@@ -4,14 +4,14 @@
  * 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]="bccd5918-1a51-5258-8d66-1960c51523cf")}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]="202cbb3e-71fe-5701-a1f5-eb515bf56561")}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";
 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";
+import { isReadOutputBudgetExceeded, resolveReadOutputEncoding, } from "../../sdk/read-output-contracts.js";
 import { encode as encodeToon } from "@toon-format/toon";
 const DECLARED_PROCESS_EXIT_CODES = new Set(Object.values(EXIT_CODE));
 const NATIVE_OUTPUT_MARKER = "__pm_native_output";
@@ -389,6 +389,9 @@ function formatEffectiveOutput(effectiveResult, nativeOutput, options) {
         ? projectLinkedTestEvidence(outputResult, options.lean === true)
         : outputResult;
     const intentOutputResult = attachReadOutputContracts(command, resolvedCommandOptions, projectedOutputResult);
+    if (isReadOutputBudgetExceeded(intentOutputResult)) {
+        process.exitCode ||= EXIT_CODE.USAGE;
+    }
     const renderResolvedOutput = (value) => {
         if (format === "toon") {
             const markdownDefault = renderDefaultMarkdownResult(value);
@@ -465,4 +468,4 @@ export const outputTestOnly = {
     renderToonValue,
 };
 //# sourceMappingURL=output.js.map
-//# debugId=bccd5918-1a51-5258-8d66-1960c51523cf
+//# debugId=202cbb3e-71fe-5701-a1f5-eb515bf56561

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

@@ -87,6 +87,8 @@ export interface PmCliErrorContext {
     nextSteps?: string[];
     /** Exact selectors that could not be matched by a lossless removal. */
     unmatched?: string[];
+    /** Exact verifier findings that caused an integrity-sensitive operation to refuse. */
+    verification_errors?: string[];
     /** Local dependency targets that could not be resolved before mutation. */
     unresolved_targets?: string[];
     /** Available history bounds for a failed point-in-time read or restore target. */

package/dist/core/shared/errors.js

@@ -1,6 +1,6 @@
 /** Implements the exported pm cli error runtime abstraction for core/shared/errors.ts. */
 
-!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]="d1a7b5e2-0915-5f00-8b5a-38af814e1ea1")}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]="bf08255e-7ef4-5929-8431-2df83d98d0ba")}catch(e){}}();
 export class PmCliError extends Error {
     /** Value that configures or reports exit code for this contract. */
     exitCode;
@@ -18,4 +18,4 @@ export class PmCliError extends Error {
     }
 }
 //# sourceMappingURL=errors.js.map
-//# debugId=d1a7b5e2-0915-5f00-8b5a-38af814e1ea1
+//# debugId=bf08255e-7ef4-5929-8431-2df83d98d0ba

package/dist/core/store/item-store.js

@@ -4,7 +4,7 @@
  * Reads and writes tracker storage with format-aware helpers for Item Store.
  */
 
-!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]="f43e1170-e797-5a0c-b02e-d31e002ab275")}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]="d24d61bf-7db8-5f35-8dbc-5ef93ec8220b")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { getActiveExtensionRegistrations, projectAfterCommandItemSnapshot, recordAfterCommandAffectedItem, runActiveOnReadHooks, runActiveBeforeMutationHooks, runActiveOnWriteHooks, runActiveServiceOverride, } from "../extensions/index.js";
@@ -69,6 +69,15 @@ function trackerRootNotDirectoryError(pmRoot) {
         ],
     });
 }
+function trackerRootUnreadableError(pmRoot) {
+    return new PmCliError(`Tracker root is not readable at ${pmRoot}.`, EXIT_CODE.GENERIC_FAILURE, {
+        code: "tracker_root_unreadable",
+        reason: "unreadable",
+        nextSteps: [
+            "Grant read and directory-search permission to the tracker root, then retry the SDK read.",
+        ],
+    });
+}
 async function assertMissingMetadataRootAncestors(pmRoot) {
     const filesystemRoot = path.parse(path.resolve(pmRoot)).root;
     let ancestor = path.dirname(path.resolve(pmRoot));
@@ -114,11 +123,28 @@ async function assertItemMetadataRoot(pmRoot) {
         if (isErrno(error, "ENOTDIR")) {
             throw trackerRootNotDirectoryError(pmRoot);
         }
+        if (isErrno(error, "EACCES") || isErrno(error, "EPERM")) {
+            throw trackerRootUnreadableError(pmRoot);
+        }
         throw error;
     }
     if (!stats.isDirectory()) {
         throw trackerRootNotDirectoryError(pmRoot);
     }
+    if (process.platform !== "win32" &&
+        ((stats.mode & 0o444) === 0 || (stats.mode & 0o111) === 0)) {
+        throw trackerRootUnreadableError(pmRoot);
+    }
+    try {
+        const directory = await fs.opendir(pmRoot);
+        await directory.close();
+    }
+    catch (error) {
+        if (isErrno(error, "EACCES") || isErrno(error, "EPERM")) {
+            throw trackerRootUnreadableError(pmRoot);
+        }
+        throw error;
+    }
 }
 /** Implements locate item for the public runtime surface of this module. */
 export async function locateItem(pmRoot, rawId, idPrefix = "pm-", preferredFormat, typeToFolder = TYPE_TO_FOLDER) {
@@ -684,4 +710,4 @@ export async function deleteItem(params) {
     }
 }
 //# sourceMappingURL=item-store.js.map
-//# debugId=f43e1170-e797-5a0c-b02e-d31e002ab275
+//# debugId=d24d61bf-7db8-5f35-8dbc-5ef93ec8220b

package/dist/sdk/agent/refusal-reachability.d.ts

@@ -37,9 +37,11 @@ export interface PmRefusalReachabilityReport {
     findings: PmRefusalReachabilityFinding[];
 }
 /** Recovery-reference kinds emitted by structured refusal envelopes. */
-export declare const PM_RECOVERY_REFERENCE_KINDS: readonly ["suggested_retry", "candidate_command", "example", "next_step"];
+export declare const PM_RECOVERY_REFERENCE_KINDS: readonly ["suggested_retry", "candidate_command", "example", "next_step", "migration_hint", "restore_with"];
 /** Recovery-reference kind emitted by a refusal. */
 export type PmRecoveryReferenceKind = (typeof PM_RECOVERY_REFERENCE_KINDS)[number];
+/** Behavioral promise attached to a recovery reference. */
+export type PmRecoveryReferenceSemantics = "recovery" | "replacement" | "behavior_preserving";
 /** One derived promise that another invocation or command path is reachable. */
 export interface PmRecoveryReferenceObligation {
     /** Stable reference identifier derived from its emitting envelope. */
@@ -48,6 +50,8 @@ export interface PmRecoveryReferenceObligation {
     probe_id: string;
     /** Typed recovery vocabulary rather than prose inference. */
     kind: PmRecoveryReferenceKind;
+    /** Whether the reference recovers, replaces, or preserves the original behavior. */
+    semantics: PmRecoveryReferenceSemantics;
     /** Exact emitted command or recovery text. */
     value: string;
 }
@@ -59,6 +63,8 @@ export interface PmRecoveryReferenceObservation {
     reachable: boolean;
     /** How the promise was discharged. */
     proof: "executed" | "declared_command_path" | "linked_execution";
+    /** Semantics actually demonstrated by the proof. */
+    semantics: PmRecoveryReferenceSemantics;
 }
 /** Coverage totals for one emitted recovery-reference kind. */
 export interface PmRecoveryReferenceKindCoverage {
@@ -74,7 +80,7 @@ export interface PmRecoveryReferenceKindCoverage {
 /** One recovery-reference coverage failure. */
 export interface PmRecoveryReferenceFinding {
     /** Stable finding kind for assurance and CI. */
-    kind: "duplicate_obligation" | "duplicate_observation" | "missing_observation" | "unreachable_reference" | "undeclared_observation";
+    kind: "duplicate_obligation" | "duplicate_observation" | "missing_observation" | "unreachable_reference" | "wrong_semantics" | "undeclared_observation";
     /** Obligation or observation identifier. */
     reference_id: string;
     /** Human-readable mismatch summary. */
@@ -95,6 +101,8 @@ export interface PmRecoveryReferenceReport {
     /** Stable, sorted conformance findings. */
     findings: PmRecoveryReferenceFinding[];
 }
+/** Derive typed obligations from every recognized recovery field in an emitted envelope. */
+export declare function derivePmRecoveryReferenceObligations(probeId: string, envelope: unknown): PmRecoveryReferenceObligation[];
 /** Compare declared refusal states with real-entrypoint observations. */
 export declare function verifyPmRefusalReachability(catalog: readonly PmErrorCodeContract[], observations: readonly PmRefusalProbeObservation[]): PmRefusalReachabilityReport;
 /** Verify executable and declared-path proof for emitted recovery references. */

package/dist/sdk/agent/refusal-reachability.js

@@ -1,12 +1,68 @@
 /** Recovery-reference kinds emitted by structured refusal envelopes. */
 
-!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]="631031be-883f-5a1d-bcb6-498208cf7922")}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]="e96813c2-e30f-5000-9935-281c564c19aa")}catch(e){}}();
 export const PM_RECOVERY_REFERENCE_KINDS = [
     "suggested_retry",
     "candidate_command",
     "example",
     "next_step",
+    "migration_hint",
+    "restore_with",
 ];
+const RECOVERY_REFERENCE_FIELD_CONTRACTS = {
+    suggested_retry: { kind: "suggested_retry", semantics: "recovery" },
+    candidate_command: { kind: "candidate_command", semantics: "recovery" },
+    candidate_commands: { kind: "candidate_command", semantics: "recovery" },
+    example: { kind: "example", semantics: "recovery" },
+    examples: { kind: "example", semantics: "recovery" },
+    next_step: { kind: "next_step", semantics: "recovery" },
+    next_steps: { kind: "next_step", semantics: "recovery" },
+    migration_hint: { kind: "migration_hint", semantics: "replacement" },
+    migration_hints: { kind: "migration_hint", semantics: "replacement" },
+    restore_with: {
+        kind: "restore_with",
+        semantics: "behavior_preserving",
+    },
+};
+/** Derive typed obligations from every recognized recovery field in an emitted envelope. */
+export function derivePmRecoveryReferenceObligations(probeId, envelope) {
+    const obligations = [];
+    const visit = (value, path) => {
+        if (Array.isArray(value)) {
+            value.forEach((entry, index) => visit(entry, [...path, String(index)]));
+            return;
+        }
+        if (typeof value !== "object" || value === null)
+            return;
+        for (const [key, entry] of Object.entries(value).sort(([left], [right]) => left.localeCompare(right))) {
+            const baseContract = RECOVERY_REFERENCE_FIELD_CONTRACTS[key];
+            const contract = baseContract?.kind === "migration_hint" &&
+                value.semantics === "behavior_preserving"
+                ? { ...baseContract, semantics: "behavior_preserving" }
+                : baseContract;
+            const entries = Array.isArray(entry) ? entry : [entry];
+            if (contract !== undefined) {
+                entries.forEach((candidate, index) => {
+                    if (typeof candidate !== "string" || candidate.trim().length === 0)
+                        return;
+                    const coordinate = [...path, key, String(index)]
+                        .map((segment) => encodeURIComponent(segment))
+                        .join("/");
+                    obligations.push({
+                        id: `${probeId}:${contract.kind}:${coordinate}`,
+                        probe_id: probeId,
+                        kind: contract.kind,
+                        semantics: contract.semantics,
+                        value: candidate,
+                    });
+                });
+            }
+            visit(entry, [...path, key]);
+        }
+    };
+    visit(envelope, []);
+    return obligations;
+}
 /** Compare declared refusal states with real-entrypoint observations. */
 export function verifyPmRefusalReachability(catalog, observations) {
     const declarations = catalog.flatMap((contract) => (contract.owned_states ?? []).map((state) => ({ contract, state })));
@@ -129,6 +185,13 @@ export function verifyPmRecoveryReferences(obligations, observations) {
                 detail: `Recovery reference ${obligation.value} did not reach its promised target.`,
             });
         }
+        else if (observation.semantics !== obligation.semantics) {
+            findings.push({
+                kind: "wrong_semantics",
+                reference_id: obligation.id,
+                detail: `Recovery reference ${obligation.value} promised ${obligation.semantics}; proof demonstrated ${observation.semantics}.`,
+            });
+        }
     }
     const coverageByKind = PM_RECOVERY_REFERENCE_KINDS.map((kind) => {
         const kindObligations = obligations.filter((obligation) => obligation.kind === kind);
@@ -140,7 +203,12 @@ export function verifyPmRecoveryReferences(obligations, observations) {
             kind,
             declared: kindObligations.length,
             observed: kindObservations.length,
-            passed: kindObservations.filter(({ reachable }) => reachable).length,
+            passed: kindObligations.filter((obligation) => {
+                const observation = observationsById.get(obligation.id);
+                return (!duplicateIds.has(obligation.id) &&
+                    observation?.reachable === true &&
+                    observation.semantics === obligation.semantics);
+            }).length,
         };
     });
     findings.sort((left, right) => left.reference_id !== right.reference_id
@@ -157,4 +225,4 @@ export function verifyPmRecoveryReferences(obligations, observations) {
     };
 }
 //# sourceMappingURL=refusal-reachability.js.map
-//# debugId=631031be-883f-5a1d-bcb6-498208cf7922
+//# debugId=e96813c2-e30f-5000-9935-281c564c19aa

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

@@ -46,12 +46,63 @@ export interface AcknowledgeUnknownAuthorEventsOptions {
     /** Select every currently actionable, undispositioned event in the tracker. */
     all_actionable?: boolean;
     /** Principal attributed by maintainer review. */
-    attributed_author: string;
+    attributed_author?: string;
     /** Reviewer appending the disposition event. */
-    reviewer: string;
+    reviewer?: string;
     /** Evidence-backed rationale for the attribution. */
-    reason: string;
+    reason?: string;
+    /** Resolve and return the selected plan without appending history. */
+    dry_run?: boolean;
+    /** Fingerprint from the exact preview plan being applied. */
+    plan_fingerprint?: string;
+    /** Maximum coordinate rows included in the returned plan. */
+    coordinate_limit?: number;
 }
+/** One source-bound coordinate in an author-acknowledgement plan. */
+export interface UnknownAuthorAcknowledgmentPlanCoordinate extends UnknownAuthorHistoryEvent {
+    /** SHA-256 of the exact immutable JSONL source line. */
+    source_event_hash: string;
+    /** Whether the row is undispositioned or an explicit apply would supersede it. */
+    disposition: "actionable" | "already_acknowledged";
+}
+/** Deterministic preview shared by CLI, SDK, and MCP apply paths. */
+export interface UnknownAuthorAcknowledgmentPlan {
+    /** Selector family resolved by the plan. */
+    selection: {
+        kind: "events" | "all_actionable";
+    };
+    /** Complete number of unique selected coordinates. */
+    selected_count: number;
+    /** Selected coordinates not covered by an earlier disposition. */
+    actionable_count: number;
+    /** Coordinates an explicit-events apply would supersede. */
+    already_acknowledged_count: number;
+    /** Coordinate rows omitted only from this bounded preview. */
+    omitted_count: number;
+    /** Stable ordered prefix of the complete selected set. */
+    coordinates: UnknownAuthorAcknowledgmentPlanCoordinate[];
+    /** SHA-256 over selection kind and every complete source-bound coordinate. */
+    plan_fingerprint: string;
+}
+/** Structured preview or apply result for immutable author acknowledgement. */
+export interface UnknownAuthorAcknowledgmentResult {
+    /** Whether this invocation was a read-only preview. */
+    dry_run: boolean;
+    /** Whether an append-only workspace event was written. */
+    mutated: boolean;
+    /** Number of coordinates written to the appended disposition. */
+    acknowledged: number;
+    /** Effect-aware command outcome. */
+    outcome: "preview" | "effect" | "no_effect" | "partial_effect";
+    /** Stable shell and transport exit paired with the outcome. */
+    exit_code: 0 | 6 | 7;
+    /** Exact plan used for preview or apply. */
+    plan: UnknownAuthorAcknowledgmentPlan;
+    /** Appended workspace history path when mutation occurred. */
+    history_path?: string;
+}
+/** Resolve a deterministic, source-bound author-acknowledgement preview. */
+export declare function planUnknownAuthorHistoryAcknowledgment(pmRoot: string, selector: Pick<AcknowledgeUnknownAuthorEventsOptions, "events" | "all_actionable">, coordinateLimit?: number): Promise<UnknownAuthorAcknowledgmentPlan>;
 /** Resolve the mutually exclusive CLI and SDK acknowledgment selectors. */
 export declare function resolveUnknownAuthorAcknowledgmentSelector(rawEvents: readonly string[], allActionable: boolean): {
     events: UnknownAuthorHistoryEvent[];
@@ -60,15 +111,9 @@ export declare function resolveUnknownAuthorAcknowledgmentSelector(rawEvents: re
 /** 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;
-}>;
+export declare function acknowledgeUnknownAuthorHistoryEventsFromTransport(pmRoot: string, input: Record<string, unknown>): Promise<UnknownAuthorAcknowledgmentResult>;
 /**
  * Append an audited disposition for immutable unknown-author events without
  * rewriting their original streams.
  */
-export declare function acknowledgeUnknownAuthorHistoryEvents(pmRoot: string, options: AcknowledgeUnknownAuthorEventsOptions): Promise<{
-    acknowledged: number;
-    history_path: string;
-}>;
+export declare function acknowledgeUnknownAuthorHistoryEvents(pmRoot: string, options: AcknowledgeUnknownAuthorEventsOptions): Promise<UnknownAuthorAcknowledgmentResult>;