@unbrained/pm-cli 2026.8.14 → 2026.8.16

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

@@ -1,6 +1,69 @@
-/** Compare declared refusal states with real-entrypoint observations. */
+/** 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]="55318c8e-1fbd-5abd-b18f-f0cc1f81dd5c")}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 })));
     const findings = [];
@@ -68,5 +131,98 @@ export function verifyPmRefusalReachability(catalog, observations) {
         findings,
     };
 }
+/** Verify executable and declared-path proof for emitted recovery references. */
+export function verifyPmRecoveryReferences(obligations, observations) {
+    const findings = [];
+    const declaredIds = new Set();
+    const duplicateIds = new Set();
+    for (const obligation of obligations) {
+        if (declaredIds.has(obligation.id)) {
+            duplicateIds.add(obligation.id);
+            findings.push({
+                kind: "duplicate_obligation",
+                reference_id: obligation.id,
+                detail: `Recovery obligation ${obligation.id} was declared more than once.`,
+            });
+            continue;
+        }
+        declaredIds.add(obligation.id);
+    }
+    const observationsById = new Map();
+    for (const observation of observations) {
+        if (observationsById.has(observation.id)) {
+            findings.push({
+                kind: "duplicate_observation",
+                reference_id: observation.id,
+                detail: `Recovery reference ${observation.id} was observed more than once.`,
+            });
+            continue;
+        }
+        observationsById.set(observation.id, observation);
+        if (!declaredIds.has(observation.id)) {
+            findings.push({
+                kind: "undeclared_observation",
+                reference_id: observation.id,
+                detail: `Recovery observation ${observation.id} has no emitted obligation.`,
+            });
+        }
+    }
+    for (const obligation of obligations) {
+        if (duplicateIds.has(obligation.id))
+            continue;
+        const observation = observationsById.get(obligation.id);
+        if (!observation) {
+            findings.push({
+                kind: "missing_observation",
+                reference_id: obligation.id,
+                detail: `No reachability proof was recorded for ${obligation.kind} ${obligation.value}.`,
+            });
+        }
+        else if (!observation.reachable) {
+            findings.push({
+                kind: "unreachable_reference",
+                reference_id: obligation.id,
+                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);
+        const kindObservations = kindObligations
+            .filter((obligation) => !duplicateIds.has(obligation.id))
+            .map((obligation) => observationsById.get(obligation.id))
+            .filter((observation) => observation !== undefined);
+        return {
+            kind,
+            declared: kindObligations.length,
+            observed: kindObservations.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
+        ? left.reference_id.localeCompare(right.reference_id)
+        : left.kind.localeCompare(right.kind));
+    const passed = coverageByKind.reduce((total, coverage) => total + coverage.passed, 0);
+    return {
+        ok: findings.length === 0,
+        declared_reference_count: obligations.length,
+        observed_reference_count: observations.length,
+        pass_fraction: declaredIds.size === 0 ? 1 : passed / declaredIds.size,
+        coverage_by_kind: coverageByKind,
+        findings,
+    };
+}
 //# sourceMappingURL=refusal-reachability.js.map
-//# debugId=55318c8e-1fbd-5abd-b18f-f0cc1f81dd5c
+//# 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>;

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-bootstrap.d.ts

@@ -31,6 +31,8 @@ export interface BootstrapGlobalOptions {
     outputFormat?: "toon" | "json";
     /** Caller-carried cross-call budget and served-item state. */
     outputSession?: string;
+    /** Opaque budget-compaction continuation cursor. */
+    outputCursor?: string;
     /** Whether machine-readable row discovery metadata is requested. */
     outputRowContract?: boolean;
     /** Invocation-wide mutation author override. */

package/dist/sdk/cli-bootstrap.js

@@ -4,7 +4,7 @@
  * Provides public bootstrap argument normalization for embedded CLI hosts.
  */
 
-!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]="7b3209a8-8580-542c-9e80-21d04df3f61f")}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]="eccdb2d2-da6f-555b-ba1b-8339f9b64f1a")}catch(e){}}();
 import { EXECUTABLE_COMMAND_ALIASES, resolveSubcommandFlagContractsForCommand, } from "./cli-contracts.js";
 export { EXECUTABLE_COMMAND_ALIASES };
 import { levenshteinDistanceWithinLimit } from "../core/shared/levenshtein.js";
@@ -20,6 +20,7 @@ const GLOBAL_VALUE_CONSUMING_FLAGS = new Set([
     "--output-budget",
     "--output-format",
     "--output-session",
+    "--output-cursor",
 ]);
 const OUTPUT_VALUE_FLAGS = new Set([
     "--output-include",
@@ -27,6 +28,7 @@ const OUTPUT_VALUE_FLAGS = new Set([
     "--output-budget",
     "--output-format",
     "--output-session",
+    "--output-cursor",
 ]);
 /** Whether a global value-consuming flag uses its inline `--flag=value` form. */
 const isInlineGlobalValueToken = (token) => {
@@ -117,6 +119,9 @@ export function parseBootstrapGlobalOptions(argv) {
         ...(state.outputValues.get("--output-session") === undefined
             ? {}
             : { outputSession: state.outputValues.get("--output-session") }),
+        ...(state.outputValues.get("--output-cursor") === undefined
+            ? {}
+            : { outputCursor: state.outputValues.get("--output-cursor") }),
         ...(state.author === ""
             ? { authorMissingValue: true }
             : state.author !== undefined
@@ -890,4 +895,4 @@ export const _testOnly = {
     resolveCanonicalFlag,
 };
 //# sourceMappingURL=cli-bootstrap.js.map
-//# debugId=7b3209a8-8580-542c-9e80-21d04df3f61f
+//# debugId=eccdb2d2-da6f-555b-ba1b-8339f9b64f1a

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

@@ -7,7 +7,7 @@
  * a hand-picked test list.
  */
 
-!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]="cf238c71-1626-5e48-9207-7acf22c0d680")}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]="8b227cb2-a30d-5384-b9c2-558603181c67")}catch(e){}}();
 import { PM_TOOL_ACTIONS } from "./enum-contracts.js";
 import { resolveSubcommandFlagContractsForCommand, } from "./flag-contracts.js";
 import { pmToolActionParameterKeys } from "./tool-schema.js";
@@ -23,6 +23,7 @@ const CLI_TRANSPORT_FLAGS = new Set([
     "--output-budget",
     "--output-format",
     "--output-session",
+    "--output-cursor",
     "--output-row-contract",
     "--no-changed-fields",
     "--no-extensions",
@@ -383,4 +384,4 @@ export function analyzeSdkCliParameterCompleteness(source = {}) {
     });
 }
 //# sourceMappingURL=completeness.js.map
-//# debugId=cf238c71-1626-5e48-9207-7acf22c0d680
+//# debugId=8b227cb2-a30d-5384-b9c2-558603181c67

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]="a5a2c81f-8870-5111-b13c-74c362098d54")}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) {
@@ -342,6 +342,7 @@ export const HISTORY_REPAIR_FLAG_CONTRACTS = [
     { flag: "--id", value_name: "item-id" },
     { flag: "--all" },
     { flag: "--dry-run" },
+    { flag: "--normalize-provenance" },
     { flag: "--author" },
     { flag: "--message" },
     { flag: "--force" },
@@ -350,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" },
@@ -1817,4 +1821,4 @@ export function toCompletionFlagString(flagContracts, includeGlobal = true) {
     return normalizeUniqueStringList(all).join(" ");
 }
 //# sourceMappingURL=flag-contracts.js.map
-//# debugId=a5a2c81f-8870-5111-b13c-74c362098d54
+//# debugId=c82d9b50-274f-585d-be0e-9a0c5067b9e9