@unbrained/pm-cli 2026.8.5 → 2026.8.7

package/dist/core/extensions/activation-summary.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]="8d5e0d6f-5ffa-5302-87da-3e741b80b716")}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]="1d184acd-e639-5b28-a294-98d22de2ebc7")}catch(e){}}();
 import { collectUsedExtensionCapabilities, normalizeExtensionName, } from "./capability-usage.js";
 /**
  * Canonical lifecycle hook kinds paired with their {@link ExtensionHookRegistry}
@@ -77,10 +77,13 @@ export function describeExtensionActivation(activation, options = {}) {
             ? { renderer_ownership: rendererOwnership }
             : {}),
         preflight_overrides: preflight.overrides.filter((entry) => matches(entry.name)).length,
+        preflight_ownership: preflight.overrides
+            .filter((entry) => matches(entry.name))
+            .map((entry) => ({ commands: [...(entry.commands ?? [])] })),
     };
 }
 function sortUnique(values) {
     return [...new Set(values)].sort((left, right) => left.localeCompare(right));
 }
 //# sourceMappingURL=activation-summary.js.map
-//# debugId=8d5e0d6f-5ffa-5302-87da-3e741b80b716
+//# debugId=1d184acd-e639-5b28-a294-98d22de2ebc7

package/dist/core/extensions/contribution-inventory.d.ts

@@ -22,4 +22,5 @@ export declare function createExtensionContributionInventory(summary: {
     renderer_overrides: string[];
     renderer_ownership?: ExtensionContributionInventory["renderer_ownership"];
     preflight_overrides: number;
+    preflight_ownership?: ExtensionContributionInventory["preflight_ownership"];
 }): ExtensionContributionInventory;

package/dist/core/extensions/contribution-inventory.js

@@ -4,7 +4,7 @@
  * Validates and canonicalizes the serializable extension surface inventory.
  */
 
-!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]="8ba4e82a-ab38-5527-84cf-ec553f434a22")}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]="2c4e3831-6644-5db3-a28b-1c6a131da2e1")}catch(e){}}();
 import { normalizeCommandName } from "./extension-runtime-helpers.js";
 const COMMAND_PATH_FIELDS = new Set([
     "commands",
@@ -75,6 +75,29 @@ function normalizeRendererOwnership(value) {
     }
     return ownership.sort((left, right) => left.format.localeCompare(right.format));
 }
+/** Validate preflight command ownership without importing extension code. */
+function normalizePreflightOwnership(value) {
+    if (!Array.isArray(value))
+        return null;
+    const ownership = [];
+    for (const rawEntry of value) {
+        if (typeof rawEntry !== "object" || rawEntry === null)
+            return null;
+        const commands = rawEntry.commands;
+        if (!Array.isArray(commands) ||
+            commands.some((command) => typeof command !== "string")) {
+            return null;
+        }
+        ownership.push({
+            commands: [
+                ...new Set(commands.map((command) => normalizeCommandName(command))),
+            ]
+                .filter((command) => command.length > 0)
+                .sort((left, right) => left.localeCompare(right)),
+        });
+    }
+    return ownership;
+}
 /** Normalize an optional contribution inventory, returning null for malformed data. */
 export function normalizeExtensionContributionInventory(value) {
     if (value === undefined || value === null)
@@ -102,6 +125,13 @@ export function normalizeExtensionContributionInventory(value) {
             return null;
         inventory.renderer_ownership = ownership;
     }
+    const rawPreflightOwnership = record.preflight_ownership;
+    if (rawPreflightOwnership !== undefined) {
+        const ownership = normalizePreflightOwnership(rawPreflightOwnership);
+        if (ownership === null)
+            return null;
+        inventory.preflight_ownership = ownership;
+    }
     return inventory;
 }
 /** Project an activation summary into the versioned static inventory contract. */
@@ -131,7 +161,10 @@ export function createExtensionContributionInventory(summary) {
             ? { renderer_ownership: summary.renderer_ownership }
             : {}),
         preflight_overrides: summary.preflight_overrides,
+        ...(summary.preflight_ownership
+            ? { preflight_ownership: summary.preflight_ownership }
+            : {}),
     };
 }
 //# sourceMappingURL=contribution-inventory.js.map
-//# debugId=8ba4e82a-ab38-5527-84cf-ec553f434a22
+//# debugId=2c4e3831-6644-5db3-a28b-1c6a131da2e1

package/dist/core/extensions/extension-hook-runtime.js

@@ -4,7 +4,7 @@
  * Implements extension runtime contracts and governance for Extension Hook Runtime.
  */
 
-!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]="4c40667c-1e20-5813-b2f3-eb4cb966b246")}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]="ac377139-8ce2-58ad-8005-0ac907a9baed")}catch(e){}}();
 import { cloneCommandOptionsSnapshot, cloneContextSnapshot, cloneGlobalOptionsSnapshot, normalizeCommandName, } from "./extension-runtime-helpers.js";
 import { stableValueEquals } from "../shared/serialization.js";
 import { EXIT_CODE } from "../shared/constants.js";
@@ -337,7 +337,6 @@ export async function runParserOverride(parsers, context) {
 }
 /** Implements run preflight override for the public runtime surface of this module. */
 export async function runPreflightOverride(preflight, context) {
-    const matched = [...preflight.overrides].reverse()[0];
     const baseContext = {
         command: normalizeCommandName(context.command),
         args: cloneContextSnapshot(context.args),
@@ -349,6 +348,9 @@ export async function runPreflightOverride(preflight, context) {
         pm_root_rel: context.pm_root_rel,
     };
     const baseDecision = cloneContextSnapshot(context.decision);
+    const matched = [...preflight.overrides]
+        .reverse()
+        .find((entry) => !entry.commands?.length || entry.commands.includes(baseContext.command));
     if (!matched) {
         return {
             overridden: false,
@@ -693,4 +695,4 @@ export function runRendererOverride(renderers, context) {
     }
 }
 //# sourceMappingURL=extension-hook-runtime.js.map
-//# debugId=4c40667c-1e20-5813-b2f3-eb4cb966b246
+//# debugId=ac377139-8ce2-58ad-8005-0ac907a9baed

package/dist/core/extensions/extension-types.d.ts

@@ -162,6 +162,11 @@ export interface ExtensionContributionInventory {
     }>;
     /** Number of preflight overrides in the package. */
     preflight_overrides?: number;
+    /** Optional command ownership for each preflight override. Empty commands mean global ownership. */
+    preflight_ownership?: Array<{
+        /** Command paths on which the override may run. */
+        commands: string[];
+    }>;
 }
 /** Documents the extension manifest payload exchanged by command, SDK, and package integrations. */
 export interface ExtensionManifest {
@@ -457,6 +462,16 @@ export type CommandHandler = (context: CommandHandlerContext) => unknown;
 export type ParserOverride = (context: ParserOverrideContext) => ParserOverrideDelta | Promise<ParserOverrideDelta>;
 /** Restricts preflight override values accepted by command, SDK, and storage contracts. */
 export type PreflightOverride = (context: PreflightOverrideContext) => PreflightOverrideDelta | Promise<PreflightOverrideDelta>;
+/** Static ownership declaration used to select and diagnose preflight overrides. */
+export interface PreflightOverrideOwnership {
+    /** Normalized command paths on which this preflight override may run. */
+    commands?: string[];
+}
+/** Declarative preflight override paired with statically inspectable ownership. */
+export interface ScopedPreflightOverrideDefinition extends PreflightOverrideOwnership {
+    /** Preflight handler invoked only for a declared command, or globally when unscoped. */
+    run: PreflightOverride;
+}
 /** Explicitly claims or declines one service payload without relying on object identity. */
 export type ServiceOverrideDecision = {
     handled: true;
@@ -1065,6 +1080,8 @@ export interface RegisteredExtensionPreflightOverride {
     name: string;
     /** Value that configures or reports run for this contract. */
     run: PreflightOverride;
+    /** Normalized command paths owned by this preflight override. */
+    commands?: string[];
 }
 /** Documents the registered extension service override payload exchanged by command, SDK, and package integrations. */
 export interface RegisteredExtensionServiceOverride {
@@ -1330,7 +1347,7 @@ export interface ExtensionApi {
     /** Value that configures or reports register parser for this contract. */
     registerParser(command: string, override: ParserOverride): void;
     /** Value that configures or reports register preflight for this contract. */
-    registerPreflight(override: PreflightOverride): void;
+    registerPreflight(override: PreflightOverride | ScopedPreflightOverrideDefinition): void;
     /** Value that configures or reports register service for this contract. */
     registerService(service: ExtensionServiceName, override: ServiceOverride): void;
     /** Value that configures or reports register flags for this contract. */

package/dist/core/extensions/extension-types.js

@@ -1,6 +1,6 @@
 /** Public contract for known extension capabilities, shared by SDK and presentation-layer consumers. */
 
-!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]="938c39a8-6545-5d8b-b717-69138932d528")}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]="50ad61f1-6719-541c-b4e0-4a88468725cf")}catch(e){}}();
 export const KNOWN_EXTENSION_CAPABILITIES = [
     "commands",
     "renderers",
@@ -99,4 +99,4 @@ export function createDefaultExtensionGovernancePolicy() {
     };
 }
 //# sourceMappingURL=extension-types.js.map
-//# debugId=938c39a8-6545-5d8b-b717-69138932d528
+//# debugId=50ad61f1-6719-541c-b4e0-4a88468725cf

package/dist/core/extensions/loader.js

@@ -4,7 +4,7 @@
  * Implements extension runtime contracts and governance for Loader.
  */
 
-!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]="ed58c949-c3d3-5a74-9146-05b0a04b58c4")}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]="3d5208e5-0ea5-54a5-82a8-50294b4a0655")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
@@ -17,6 +17,7 @@ import { flattenFlagListValue, isFlagDefaultValueCoercible, resolveFlagValueKind
 import { KNOWN_ITEM_FIELD_TYPES, normalizeItemFieldType, suggestKnownItemFieldType, } from "./item-field-types.js";
 import { snapshotExtensionModuleGraph } from "./module-graph-snapshot.js";
 import { captureExtensionActivationRollback } from "./activation-transaction.js";
+import { collectPreflightCollisionWarnings, normalizePreflightOverride, } from "./preflight-ownership.js";
 import { assertCommandDefinitionMetadataStrings } from "./command-visibility-tier.js";
 import { asRegistrationRecord, assertOptionalBooleanField, assertOptionalFlagDefaultField, assertOptionalStringArrayField, assertOptionalStringField, normalizeOptionalStringArrayField, } from "./registration-validation.js";
 import { describeExtensionLongFlagFailure, findExtensionFlagTokenFailure, } from "./flag-definition-validation.js";
@@ -1675,11 +1676,11 @@ class ExtensionApiRegistrar {
         if (!this.allowRegistration("preflight.override", "registerPreflight", "preflight")) {
             return;
         }
-        assertFunctionHandler("registerPreflight override", override);
+        const normalized = normalizePreflightOverride(override);
         this.#preflightRegistry.overrides.push({
             layer: this.#loadedExtension.layer,
             name: this.#loadedExtension.name,
-            run: override,
+            ...normalized,
         });
     }
     registerService(service, override) {
@@ -2171,15 +2172,6 @@ function collectParserCollisionWarnings(parsers) {
     }
     return warnings;
 }
-function collectPreflightCollisionWarnings(preflight) {
-    if (preflight.overrides.length <= 1) {
-        return [];
-    }
-    const winner = preflight.overrides[preflight.overrides.length - 1];
-    return preflight.overrides
-        .slice(0, -1)
-        .map((displaced) => `extension_preflight_override_collision:${winner.layer}:${winner.name}:${displaced.layer}:${displaced.name}`);
-}
 // Services whose runtime semantics are chain/fall-through (each override gets a chance);
 // for those, registering multiple overrides is by design, not a collision.
 const CHAINED_SERVICE_NAMES = new Set(["output_format"]);
@@ -2320,4 +2312,4 @@ export const _testOnlyLoader = {
     },
 };
 //# sourceMappingURL=loader.js.map
-//# debugId=ed58c949-c3d3-5a74-9146-05b0a04b58c4
+//# debugId=3d5208e5-0ea5-54a5-82a8-50294b4a0655

package/dist/core/extensions/preflight-ownership.d.ts

@@ -0,0 +1,5 @@
+import type { ExtensionPreflightRegistry, PreflightOverride, RegisteredExtensionPreflightOverride, ScopedPreflightOverrideDefinition } from "./extension-types.js";
+/** Normalize one callback or scoped definition into a registered handler payload. */
+export declare function normalizePreflightOverride(override: PreflightOverride | ScopedPreflightOverrideDefinition): Pick<RegisteredExtensionPreflightOverride, "run" | "commands">;
+/** Report pairwise overlap while permitting disjoint scoped ownership. */
+export declare function collectPreflightCollisionWarnings(preflight: ExtensionPreflightRegistry): string[];

package/dist/core/extensions/preflight-ownership.js

@@ -0,0 +1,42 @@
+/**
+ * @module core/extensions/preflight-ownership
+ *
+ * Normalizes preflight ownership and diagnoses competing registrations.
+ */
+
+!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]="065f61c6-2123-5a6d-984a-569bb14d6911")}catch(e){}}();
+import { normalizeCommandName } from "./extension-runtime-helpers.js";
+/** Normalize one callback or scoped definition into a registered handler payload. */
+export function normalizePreflightOverride(override) {
+    const run = typeof override === "function" ? override : override.run;
+    if (typeof run !== "function") {
+        throw new TypeError("registerPreflight override requires a function handler");
+    }
+    const commands = [
+        ...new Set((typeof override === "function" ? [] : (override.commands ?? [])).map((command) => {
+            if (typeof command !== "string" || command.trim().length === 0) {
+                throw new TypeError("registerPreflight ownership.commands must contain non-empty command paths");
+            }
+            return normalizeCommandName(command);
+        })),
+    ];
+    return { run, ...(commands.length > 0 ? { commands } : {}) };
+}
+/** Report pairwise overlap while permitting disjoint scoped ownership. */
+export function collectPreflightCollisionWarnings(preflight) {
+    const warnings = [];
+    for (let winnerIndex = 1; winnerIndex < preflight.overrides.length; winnerIndex += 1) {
+        const winner = preflight.overrides[winnerIndex];
+        for (const displaced of preflight.overrides.slice(0, winnerIndex)) {
+            if (winner.commands?.length &&
+                displaced.commands?.length &&
+                !displaced.commands.some((command) => winner.commands.includes(command))) {
+                continue;
+            }
+            warnings.push(`extension_preflight_override_collision:${winner.layer}:${winner.name}:${displaced.layer}:${displaced.name}`);
+        }
+    }
+    return warnings;
+}
+//# sourceMappingURL=preflight-ownership.js.map
+//# debugId=065f61c6-2123-5a6d-984a-569bb14d6911

package/dist/core/extensions/reserved-host-flags.js

@@ -5,7 +5,7 @@
  */
 /** Host-owned flags inherited by every subcommand, including extension commands. */
 
-!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]="875ac35b-c6ce-5690-a05a-8e4d279a49bf")}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]="47bfb287-bdd9-5984-9db4-cb996845d98c")}catch(e){}}();
 export const RESERVED_EXTENSION_HOST_FLAGS = Object.freeze([
     { flag: "--json" },
     { flag: "--lean" },
@@ -14,6 +14,7 @@ export const RESERVED_EXTENSION_HOST_FLAGS = Object.freeze([
     { flag: "--output-limit", value_name: "count" },
     { flag: "--output-budget", value_name: "tokens" },
     { flag: "--output-format", value_name: "toon|json" },
+    { flag: "--output-session", value_name: "state" },
     { flag: "--quiet" },
     { flag: "--no-changed-fields" },
     { flag: "--full-changed-fields" },
@@ -31,4 +32,4 @@ export const RESERVED_EXTENSION_HOST_FLAG_NAMES = new Set(RESERVED_EXTENSION_HOS
     ...(definition.aliases ?? []),
 ]));
 //# sourceMappingURL=reserved-host-flags.js.map
-//# debugId=875ac35b-c6ce-5690-a05a-8e4d279a49bf
+//# debugId=47bfb287-bdd9-5984-9db4-cb996845d98c

package/dist/core/history/workspace-history.d.ts

@@ -47,6 +47,18 @@ export interface WorkspaceJsonWriteOptions {
     /** Whether creating a previously absent singleton produces a history entry. */
     recordCreation?: boolean;
 }
+/** Result of deriving one audited singleton snapshot while its lock is held. */
+export interface WorkspaceJsonMutation<Result> {
+    /** Fully serialized JSON value to persist. */
+    raw: string;
+    /** Caller-defined result derived from the same locked before-state. */
+    result: Result;
+}
+/** Options for deriving and writing one audited singleton under one lock. */
+export interface WorkspaceJsonMutationOptions<Result> extends Omit<WorkspaceJsonWriteOptions, "raw"> {
+    /** Derive the next snapshot and receipt from the locked serialized state. */
+    mutate: (beforeRaw: string | null) => WorkspaceJsonMutation<Result> | Promise<WorkspaceJsonMutation<Result>>;
+}
 /** Options for one append-only workspace audit event that leaves state unchanged. */
 export interface WorkspaceAuditEventOptions {
     /** Tracker root containing the workspace history stream. */
@@ -79,7 +91,15 @@ export declare function appendWorkspaceAuditEvent(options: WorkspaceAuditEventOp
     historyPath: string;
 }>;
 /**
- * Atomically serialize a JSON singleton snapshot, write, history append, and
- * compensation under the workspace-history lock.
+ * Derive and persist an audited singleton mutation from one lock-protected
+ * before-state, preventing read-modify-write callers from losing updates.
+ */
+export declare function mutateWorkspaceJsonWithHistory<Result>(params: WorkspaceJsonMutationOptions<Result>): Promise<{
+    changed: boolean;
+    result: Result;
+}>;
+/**
+ * Atomically persist one caller-serialized JSON singleton and its audit entry
+ * under the workspace-history lock, with compensation if history append fails.
  */
 export declare function writeWorkspaceJsonWithHistory(params: WorkspaceJsonWriteOptions): Promise<boolean>;

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

@@ -5,12 +5,12 @@
  * 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]="8a15177d-4090-5e58-aac7-20b2ed7684a2")}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]="86b45d6b-2192-5d31-8f73-94d6e6b17dfc")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { readFileIfExists, writeFileAtomic } from "../fs/fs-utils.js";
 import { acquireLock } from "../lock/lock.js";
-import { EMPTY_CANONICAL_DOCUMENT, EXIT_CODE, } from "../shared/constants.js";
+import { EMPTY_CANONICAL_DOCUMENT, EXIT_CODE } from "../shared/constants.js";
 import { PmCliError } from "../shared/errors.js";
 import { stableStringify } from "../shared/serialization.js";
 import { appendHistoryEntry, createHistoryEntry } from "./history.js";
@@ -155,46 +155,70 @@ export async function appendWorkspaceAuditEvent(options) {
  * Atomically serialize a JSON singleton snapshot, write, history append, and
  * compensation under the workspace-history lock.
  */
-export async function writeWorkspaceJsonWithHistory(params) {
-    const release = await acquireLock(params.pmRoot, "workspace-history", params.lockTtlSeconds, params.author, false, false, params.lockWaitMs);
+async function writeWorkspaceJsonWithHistoryLocked(params, beforeRaw) {
+    if (beforeRaw === params.raw)
+        return false;
+    const before = beforeRaw === null ? null : JSON.parse(beforeRaw);
+    const after = JSON.parse(params.raw);
+    await writeFileAtomic(params.filePath, params.raw);
     try {
-        const beforeRaw = await readFileIfExists(params.filePath);
-        if (beforeRaw === params.raw)
-            return false;
-        const before = beforeRaw === null ? null : JSON.parse(beforeRaw);
-        const after = JSON.parse(params.raw);
-        await writeFileAtomic(params.filePath, params.raw);
-        try {
-            if (beforeRaw !== null || params.recordCreation !== false) {
-                await appendWorkspaceHistoryChangeLocked({
-                    pmRoot: params.pmRoot,
-                    documentPath: path
-                        .relative(params.pmRoot, params.filePath)
-                        .replaceAll("\\", "/"),
-                    before,
-                    after,
-                    op: params.op,
-                    author: params.author,
-                    lockTtlSeconds: params.lockTtlSeconds,
-                    lockWaitMs: params.lockWaitMs,
-                    message: params.message,
-                });
-            }
+        if (beforeRaw !== null || params.recordCreation !== false) {
+            await appendWorkspaceHistoryChangeLocked({
+                pmRoot: params.pmRoot,
+                documentPath: path
+                    .relative(params.pmRoot, params.filePath)
+                    .replaceAll("\\", "/"),
+                before,
+                after,
+                op: params.op,
+                author: params.author,
+                lockTtlSeconds: params.lockTtlSeconds,
+                lockWaitMs: params.lockWaitMs,
+                message: params.message,
+            });
         }
-        catch (error) {
-            if (beforeRaw === null) {
-                await fs.rm(params.filePath, { force: true });
-            }
-            else {
-                await writeFileAtomic(params.filePath, beforeRaw);
-            }
-            throw error;
+    }
+    catch (error) {
+        if (beforeRaw === null) {
+            await fs.rm(params.filePath, { force: true });
+        }
+        else {
+            await writeFileAtomic(params.filePath, beforeRaw);
         }
-        return true;
+        throw error;
+    }
+    return true;
+}
+/**
+ * Derive and persist an audited singleton mutation from one lock-protected
+ * before-state, preventing read-modify-write callers from losing updates.
+ */
+export async function mutateWorkspaceJsonWithHistory(params) {
+    const release = await acquireLock(params.pmRoot, "workspace-history", params.lockTtlSeconds, params.author, false, false, params.lockWaitMs);
+    try {
+        const beforeRaw = await readFileIfExists(params.filePath);
+        const mutation = await params.mutate(beforeRaw);
+        return {
+            changed: await writeWorkspaceJsonWithHistoryLocked({ ...params, raw: mutation.raw }, beforeRaw),
+            result: mutation.result,
+        };
+    }
+    finally {
+        await release();
+    }
+}
+/**
+ * Atomically persist one caller-serialized JSON singleton and its audit entry
+ * under the workspace-history lock, with compensation if history append fails.
+ */
+export async function writeWorkspaceJsonWithHistory(params) {
+    const release = await acquireLock(params.pmRoot, "workspace-history", params.lockTtlSeconds, params.author, false, false, params.lockWaitMs);
+    try {
+        return await writeWorkspaceJsonWithHistoryLocked(params, await readFileIfExists(params.filePath));
     }
     finally {
         await release();
     }
 }
 //# sourceMappingURL=workspace-history.js.map
-//# debugId=8a15177d-4090-5e58-aac7-20b2ed7684a2
+//# debugId=86b45d6b-2192-5d31-8f73-94d6e6b17dfc

package/dist/core/output/output.d.ts

@@ -22,6 +22,8 @@ export interface OutputOptions {
     outputBudget?: string;
     /** Canonical renderer encoding for read output. */
     outputFormat?: "toon" | "json";
+    /** Caller-carried cross-call budget and served-item state. */
+    outputSession?: string;
     /** Fallback output format used when callers do not provide an override. */
     defaultOutputFormat?: "toon" | "json";
     /** Value that configures or reports command for this contract. */

package/dist/core/output/output.js

@@ -4,7 +4,7 @@
  * Formats compact human and machine output for Output.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="816ae182-02ba-56a9-8204-7474e30322bc")}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]="4a84286a-e1e3-5465-94c9-b44f8e4472d5")}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";
@@ -333,6 +333,7 @@ function formatEffectiveOutput(effectiveResult, nativeOutput, options) {
             ["outputLimit", options.outputLimit],
             ["outputBudget", options.outputBudget],
             ["outputFormat", options.outputFormat],
+            ["outputSession", options.outputSession],
         ].filter((entry) => entry[1] !== undefined)),
     };
     const format = resolveReadOutputEncoding(command ?? "", commandOptions) ??
@@ -416,4 +417,4 @@ export const outputTestOnly = {
     renderToonValue,
 };
 //# sourceMappingURL=output.js.map
-//# debugId=816ae182-02ba-56a9-8204-7474e30322bc
+//# debugId=4a84286a-e1e3-5465-94c9-b44f8e4472d5

package/dist/core/shared/command-types.d.ts

@@ -27,6 +27,8 @@ export interface GlobalOptions {
     outputBudget?: string;
     /** Canonical renderer encoding for read output. */
     outputFormat?: "toon" | "json";
+    /** Caller-carried cross-call budget and served-item state. */
+    outputSession?: string;
     /** Filesystem path used for path resolution. */
     path?: string;
     /** Value that configures or reports no extensions for this contract. */

package/dist/core/shared/command-types.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]="83f9379e-d39e-55d3-9ac4-d98f854ad566")}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]="ff47df0c-93db-5e20-be4e-48a2aedfeebf")}catch(e){}}();
 export {};
 //# sourceMappingURL=command-types.js.map
-//# debugId=83f9379e-d39e-55d3-9ac4-d98f854ad566
+//# debugId=ff47df0c-93db-5e20-be4e-48a2aedfeebf

package/dist/mcp/tool-definitions.js

@@ -4,10 +4,11 @@
  * Defines the Tool Definitions module for pm CLI source.
  */
 
-!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]="89c1ac6d-c217-54ea-8728-5a58762f86d9")}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]="cde81c26-97fa-5236-b807-e944ba4af321")}catch(e){}}();
 import { GRAPH_SUBCOMMAND_VALUES, PM_TOOL_ACTIONS, } from "../sdk/cli-contracts/enum-contracts.js";
 import { buildPmActionToolInputSchema } from "../sdk/cli-contracts/tool-schema.js";
 import { RUNTIME_STATUS_ROLE_VALUES } from "../types.js";
+const CANONICAL_OUTPUT_SESSION_TOOL_PROPERTY = buildPmActionToolInputSchema("list").properties.outputSession;
 const READ_OUTPUT_TOOL_PROPERTIES = {
     outputInclude: {
         type: "string",
@@ -28,6 +29,9 @@ const READ_OUTPUT_TOOL_PROPERTIES = {
         enum: ["json", "toon"],
         description: "Universal read-result encoding selector.",
     },
+    outputSession: {
+        ...CANONICAL_OUTPUT_SESSION_TOOL_PROPERTY,
+    },
 };
 /** MCP transport parameters layered over every canonical action schema. */
 export const TOOL_SCHEMA_BASE = {
@@ -735,4 +739,4 @@ export function buildMcpToolContracts() {
     }).sort((left, right) => left.name.localeCompare(right.name));
 }
 //# sourceMappingURL=tool-definitions.js.map
-//# debugId=89c1ac6d-c217-54ea-8728-5a58762f86d9
+//# debugId=cde81c26-97fa-5236-b807-e944ba4af321

package/dist/sdk/author-attribution.js

@@ -4,11 +4,27 @@
  * 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]="364a8999-58e2-58c9-bfa6-acd8c42ec471")}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]="09427917-8347-59cc-9358-452671aed3c3")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { appendWorkspaceAuditEvent } 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";
+/**
+ * Refuse an acknowledgment argument as a classified usage error.
+ *
+ * Argument validation is an expected outcome of a public mutation surface, not a
+ * product failure. Raising a bare `TypeError` left the refusal at exit code 1,
+ * which the CLI observability boundary reports as an unclassified handled error
+ * and the release gate then reads as a blocking production issue. Carrying
+ * {@link EXIT_CODE.USAGE} plus a stable code keeps the refusal teachable and
+ * 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 });
+}
 /** First release-governance anchor after which unknown authors require remediation. */
 export const HISTORY_AUTHOR_ATTRIBUTION_BASELINE = "2026-07-15T06:22:12.276Z";
 /** Parsed epoch for the immutable attribution baseline used by every stream scan. */
@@ -198,7 +214,7 @@ export async function acknowledgeUnknownAuthorHistoryEvents(pmRoot, options) {
     const explicitEvents = options.events ?? [];
     const selectorCount = Number(options.all_actionable === true) + Number(explicitEvents.length > 0);
     if (selectorCount > 1) {
-        throw new TypeError("Author acknowledgment accepts either explicit events or all_actionable, not both.");
+        refuseAuthorAcknowledgmentArgument("Author acknowledgment accepts either explicit events or all_actionable, not both.", "history_author_acknowledge_selector_conflict");
     }
     const selectedEvents = options.all_actionable === true
         ? (await scanHistoryAuthorAttribution(pmRoot, 0, true))
@@ -213,7 +229,7 @@ export async function acknowledgeUnknownAuthorHistoryEvents(pmRoot, options) {
         reason.length > 0,
     ].includes(false);
     if (requiredValuesMissing) {
-        throw new TypeError("Author acknowledgment requires events, reviewer, attributed_author, and reason.");
+        refuseAuthorAcknowledgmentArgument("Author acknowledgment requires events, reviewer, attributed_author, and reason.", "history_author_acknowledge_required_values_missing");
     }
     const uniqueEvents = [
         ...new Map(selectedEvents.map((event) => [
@@ -228,7 +244,7 @@ export async function acknowledgeUnknownAuthorHistoryEvents(pmRoot, options) {
             event.line >= 1,
         ].includes(false);
         if (invalidCoordinate) {
-            throw new TypeError(`Unknown-author acknowledgment target ${event.item_id}:${event.line} is not readable.`);
+            refuseAuthorAcknowledgmentArgument(`Unknown-author acknowledgment target ${event.item_id}:${event.line} is not readable.`, "history_author_acknowledge_target_unreadable");
         }
         let parsed;
         try {
@@ -237,10 +253,10 @@ export async function acknowledgeUnknownAuthorHistoryEvents(pmRoot, options) {
             parsed = JSON.parse(line ?? "");
         }
         catch {
-            throw new TypeError(`Unknown-author acknowledgment target ${event.item_id}:${event.line} is not readable.`);
+            refuseAuthorAcknowledgmentArgument(`Unknown-author acknowledgment target ${event.item_id}:${event.line} is not readable.`, "history_author_acknowledge_target_unreadable");
         }
         if (classifyHistoryAuthorEvent(parsed) !== "actionable_unknown") {
-            throw new TypeError(`Author acknowledgment target ${event.item_id}:${event.line} is not an actionable unknown-author event.`);
+            refuseAuthorAcknowledgmentArgument(`Author acknowledgment target ${event.item_id}:${event.line} is not an actionable unknown-author event.`, "history_author_acknowledge_target_not_actionable");
         }
     }
     const settings = await readSettings(pmRoot);
@@ -264,4 +280,4 @@ export async function acknowledgeUnknownAuthorHistoryEvents(pmRoot, options) {
     };
 }
 //# sourceMappingURL=author-attribution.js.map
-//# debugId=364a8999-58e2-58c9-bfa6-acd8c42ec471
+//# debugId=09427917-8347-59cc-9358-452671aed3c3