@unbrained/pm-cli 2026.8.6 → 2026.8.8

package/dist/cli.js

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

package/dist/core/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]="b52d2756-f640-5f53-981f-05fa23fa1718")}catch(e){}}();
 import { getActiveCommandContext, runActiveCommandOverride, runActiveRendererOverride, runActiveServiceOverrideSync, setActiveCommandResult, } from "../extensions/index.js";
 import { EXIT_CODE } from "../shared/constants.js";
 import { isHostOutputSuppressed } from "./output-control.js";
@@ -12,6 +12,7 @@ import { projectMutationResult } from "./mutation-projection.js";
 import { attachReadOutputContracts } from "../../sdk/context-intent-contracts.js";
 import { attachOutputTokenAccounting } from "../../sdk/output-token-accounting.js";
 import { resolveReadOutputEncoding } from "../../sdk/read-output-contracts.js";
+const DECLARED_PROCESS_EXIT_CODES = new Set(Object.values(EXIT_CODE));
 const NATIVE_OUTPUT_MARKER = "__pm_native_output";
 let streamErrorHandlersInstalled = false;
 function isPlainObject(value) {
@@ -333,6 +334,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) ??
@@ -387,6 +389,12 @@ export function formatOutput(result, options) {
 }
 /** Implements print result for the public runtime surface of this module. */
 export function printResult(result, options) {
+    if (isPlainObject(result) &&
+        Number.isInteger(result.exit_code) &&
+        DECLARED_PROCESS_EXIT_CODES.has(Number(result.exit_code)) &&
+        (process.exitCode === undefined || process.exitCode === EXIT_CODE.SUCCESS)) {
+        process.exitCode = Number(result.exit_code);
+    }
     const projected = options.idOnly
         ? projectMutationResult(result, { idOnly: true })
         : options.fullChangedFields
@@ -416,4 +424,4 @@ export const outputTestOnly = {
     renderToonValue,
 };
 //# sourceMappingURL=output.js.map
-//# debugId=816ae182-02ba-56a9-8204-7474e30322bc
+//# debugId=b52d2756-f640-5f53-981f-05fa23fa1718

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

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

package/dist/core/sentry/helpers.js

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

package/dist/core/shared/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/core/shared/constants.d.ts

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

package/dist/core/shared/constants.js

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

package/dist/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/annotations.d.ts

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

package/dist/sdk/annotations.js

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