@unbrained/pm-cli 2026.8.6 → 2026.8.7

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

package/dist/sdk/cli-bootstrap.d.ts

@@ -29,6 +29,8 @@ export interface BootstrapGlobalOptions {
     outputBudget?: string;
     /** Canonical renderer encoding for read output. */
     outputFormat?: "toon" | "json";
+    /** Caller-carried cross-call budget and served-item state. */
+    outputSession?: string;
     /** Invocation-wide mutation author override. */
     author?: string;
     /** Whether `--author` was present without its required value. */

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]="212ba734-6a06-576f-8ad8-de759727cd75")}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]="1c2ee12c-9a3e-57bc-8336-f6c558458802")}catch(e){}}();
 import { EXECUTABLE_COMMAND_ALIASES, resolveSubcommandFlagContractsForCommand, } from "./cli-contracts.js";
 export { EXECUTABLE_COMMAND_ALIASES };
 import { levenshteinDistanceWithinLimit } from "../core/shared/levenshtein.js";
@@ -16,12 +16,14 @@ const GLOBAL_VALUE_CONSUMING_FLAGS = new Set([
     "--output-limit",
     "--output-budget",
     "--output-format",
+    "--output-session",
 ]);
 const OUTPUT_VALUE_FLAGS = new Set([
     "--output-include",
     "--output-limit",
     "--output-budget",
     "--output-format",
+    "--output-session",
 ]);
 /** Whether a global value-consuming flag uses its inline `--flag=value` form. */
 const isInlineGlobalValueToken = (token) => {
@@ -105,6 +107,9 @@ export function parseBootstrapGlobalOptions(argv) {
                 outputFormat: state.outputValues.get("--output-format"),
             }
             : {}),
+        ...(state.outputValues.get("--output-session") === undefined
+            ? {}
+            : { outputSession: state.outputValues.get("--output-session") }),
         ...(state.author === ""
             ? { authorMissingValue: true }
             : state.author !== undefined
@@ -866,4 +871,4 @@ export const _testOnly = {
     resolveCanonicalFlag,
 };
 //# sourceMappingURL=cli-bootstrap.js.map
-//# debugId=212ba734-6a06-576f-8ad8-de759727cd75
+//# debugId=1c2ee12c-9a3e-57bc-8336-f6c558458802

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

@@ -7,11 +7,11 @@
  * 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]="5f5b9bd3-1b92-5fb2-b649-6eb942a7a3c4")}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]="0c81aa87-3ffb-5837-a3fa-eae5fb70eaf1")}catch(e){}}();
 import { PM_TOOL_ACTIONS } from "./enum-contracts.js";
 import { resolveSubcommandFlagContractsForCommand, } from "./flag-contracts.js";
 import { pmToolActionParameterKeys } from "./tool-schema.js";
-import { PM_READ_OUTPUT_OPTION_FLAGS, resolveReadOutputSurface, } from "../read-output-contracts.js";
+import { PM_READ_OUTPUT_COMPOSITION_OPTION_FLAGS, PM_READ_OUTPUT_OPTION_FLAGS, resolveReadOutputSurface, } from "../read-output-contracts.js";
 const CLI_TRANSPORT_FLAGS = new Set([
     "--author",
     "--follow",
@@ -22,6 +22,7 @@ const CLI_TRANSPORT_FLAGS = new Set([
     "--output-limit",
     "--output-budget",
     "--output-format",
+    "--output-session",
     "--no-changed-fields",
     "--no-extensions",
     "--no-pager",
@@ -30,7 +31,10 @@ const CLI_TRANSPORT_FLAGS = new Set([
     "--quiet",
     "--interval-ms",
 ]);
-const READ_OUTPUT_OPTION_FLAGS = new Set(PM_READ_OUTPUT_OPTION_FLAGS);
+const READ_OUTPUT_OPTION_FLAGS = new Set([
+    ...PM_READ_OUTPUT_OPTION_FLAGS,
+    ...PM_READ_OUTPUT_COMPOSITION_OPTION_FLAGS,
+]);
 const CLI_PRESENTATION_FLAGS = new Set([
     "--brief",
     "--format",
@@ -137,6 +141,27 @@ const ACTION_FLAG_PARAMETER_OVERRIDES = {
     package: { "--gh": "github", "--scaffold": "init" },
     install: { "--gh": "github" },
 };
+const ACTION_STRUCTURED_FLAG_PARAMETERS = {
+    stats: {
+        "--analytics": [
+            "measurements",
+            "metric",
+            "measurementLimit",
+            "observe",
+            "improvementDirection",
+            "measurementSource",
+            "measurementItem",
+            "measurementRevision",
+            "author",
+            "message",
+            "provenanceCoverage",
+            "fleetAttribution",
+            "since",
+            "eventLimit",
+            "minimumSample",
+        ],
+    },
+};
 function actionCommand(action) {
     if (action.startsWith("extension-")) {
         return `extension ${action.slice("extension-".length)}`;
@@ -168,6 +193,17 @@ function aliasTarget(flag, contracts) {
     return contracts.find(({ aliases }) => aliases?.includes(flag))?.flag;
 }
 function classifyCliInput(action, contract, contracts, sdkParameters) {
+    const structuredParameters = ACTION_STRUCTURED_FLAG_PARAMETERS[action]?.[contract.flag];
+    if (structuredParameters !== undefined &&
+        structuredParameters.every((parameter) => sdkParameters.has(parameter))) {
+        return {
+            surface: "cli",
+            input: contract.flag,
+            counterpart: structuredParameters[0],
+            disposition: "shared",
+            reason: "The validated CLI JSON object fans out across strict SDK parameters.",
+        };
+    }
     const parameter = parameterForFlag(action, contract.flag);
     if (sdkParameters.has(parameter)) {
         return {
@@ -242,6 +278,17 @@ function classifyCliInput(action, contract, contracts, sdkParameters) {
     };
 }
 function classifySdkInput(action, parameter, cliEntries) {
+    const structuredCounterpart = Object.entries(ACTION_STRUCTURED_FLAG_PARAMETERS[action] ?? {}).find(([flag, parameters]) => parameters.includes(parameter) &&
+        cliEntries.some(({ input, disposition }) => input === flag && disposition === "shared"));
+    if (structuredCounterpart !== undefined) {
+        return {
+            surface: "sdk",
+            input: parameter,
+            counterpart: structuredCounterpart[0],
+            disposition: "shared",
+            reason: "The strict SDK parameter is reachable through the validated CLI JSON object.",
+        };
+    }
     const cliCounterpart = cliEntries.find(({ counterpart, disposition }) => counterpart === parameter &&
         (disposition === "shared" ||
             disposition === "compatibility_alias" ||
@@ -317,4 +364,4 @@ export function analyzeSdkCliParameterCompleteness(source = {}) {
     });
 }
 //# sourceMappingURL=completeness.js.map
-//# debugId=5f5b9bd3-1b92-5fb2-b649-6eb942a7a3c4
+//# debugId=0c81aa87-3ffb-5837-a3fa-eae5fb70eaf1

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]="01e8d488-ce63-54cc-848e-e7842a9d873d")}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]="8de867f9-e4d7-5c05-bae5-c3845a2280b7")}catch(e){}}();
 import { normalizeUniqueStringList } from "./string-lists.js";
 import { RESERVED_EXTENSION_HOST_FLAGS } from "../../core/extensions/reserved-host-flags.js";
 function normalizeFlagAliasKey(flag) {
@@ -911,6 +911,7 @@ export const STATS_FLAG_CONTRACTS = [
     { flag: "--by-tag" },
     { flag: "--by-priority" },
     { flag: "--tag-prefix" },
+    { flag: "--analytics" },
 ];
 /** Public contract for duplicate-cluster discovery flags. */
 export const DUPLICATES_FLAG_CONTRACTS = [
@@ -1751,4 +1752,4 @@ export function toCompletionFlagString(flagContracts, includeGlobal = true) {
     return normalizeUniqueStringList(all).join(" ");
 }
 //# sourceMappingURL=flag-contracts.js.map
-//# debugId=01e8d488-ce63-54cc-848e-e7842a9d873d
+//# debugId=8de867f9-e4d7-5c05-bae5-c3845a2280b7

package/dist/sdk/cli-contracts/registration-helpers.js

@@ -4,7 +4,7 @@
  * Provides CLI runtime support for Registration 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]="e520de00-0810-5356-9290-324cf1d3c133")}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]="d44229ca-8c70-5d55-a168-32bfe66711e6")}catch(e){}}();
 import { Option } from "commander";
 import { pathExists, refreshSearchArtifactsForMutation, shouldRunSearchRefreshInForeground, EXIT_CODE, PmCliError, printError, printResult, writeStdout, getSettingsPath, resolvePmRoot, readSettings, runActiveServiceOverride, setActiveCommandResult, } from "../runtime-primitives.js";
 import { ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS, CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, CREATE_COMMANDER_STRING_OPTION_CONTRACTS, LIST_COMMANDER_STRING_OPTION_CONTRACTS, NEXT_COMMANDER_STRING_OPTION_CONTRACTS, SEARCH_COMMANDER_STRING_OPTION_CONTRACTS, UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, UPDATE_COMMANDER_STRING_OPTION_CONTRACTS, readFirstValueFromCommanderOptions, readFirstStringFromCommanderOptions, readStringArrayFromCommanderOptions, } from "../cli-contracts.js";
@@ -111,6 +111,7 @@ export function getGlobalOptions(command) {
         outputInclude: readStringCommandOption(opts, "outputInclude"),
         outputLimit: readStringCommandOption(opts, "outputLimit"),
         outputBudget: readStringCommandOption(opts, "outputBudget"),
+        outputSession: readStringCommandOption(opts, "outputSession"),
         ...(opts.outputFormat === "toon" || opts.outputFormat === "json"
             ? { outputFormat: opts.outputFormat }
             : {}),
@@ -969,4 +970,4 @@ export const _testOnly = {
     collectMutationItemIds,
 };
 //# sourceMappingURL=registration-helpers.js.map
-//# debugId=e520de00-0810-5356-9290-324cf1d3c133
+//# debugId=d44229ca-8c70-5d55-a168-32bfe66711e6

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

@@ -4,7 +4,7 @@
  * Implements the pm contracts 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]="e6dd81d6-95d6-51e6-a0c9-ba7bb5372457")}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]="36bb127d-7a88-5e0d-8296-3d74b9ceb813")}catch(e){}}();
 import { EXIT_CODE, SETTINGS_DEFAULTS, PmCliError, activateExtensions, getActiveExtensionRegistrations, loadExtensions, pathExists, commandOptionFlagLabel, resolveCommandOptionPolicyState, resolveItemTypeRegistry, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, getSettingsPath, resolvePmRoot, readSettings, } from "../runtime-primitives.js";
 import { buildMcpToolContracts, } from "../../mcp/tool-definitions.js";
 import { ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, ACTIVITY_FLAG_CONTRACTS, AGGREGATE_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS, CALENDAR_FLAG_CONTRACTS, CLAIM_FLAG_CONTRACTS, CLOSE_TASK_FLAG_CONTRACTS, COMMENTS_FLAG_CONTRACTS, CLOSE_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONFIG_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS, CONTEXT_FLAG_CONTRACTS, CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, CREATE_COMMANDER_STRING_OPTION_CONTRACTS, CREATE_FLAG_CONTRACTS, DELETE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, DOCS_FLAG_CONTRACTS, EXTENSION_ACTIVATE_FLAG_CONTRACTS, EXTENSION_ADOPT_ALL_FLAG_CONTRACTS, EXTENSION_ADOPT_FLAG_CONTRACTS, EXTENSION_CATALOG_FLAG_CONTRACTS, EXTENSION_DEACTIVATE_FLAG_CONTRACTS, EXTENSION_DESCRIBE_FLAG_CONTRACTS, EXTENSION_DOCTOR_FLAG_CONTRACTS, EXTENSION_EXPLORE_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, EXTENSION_INIT_FLAG_CONTRACTS, EXTENSION_INSTALL_FLAG_CONTRACTS, EXTENSION_MANAGE_FLAG_CONTRACTS, EXTENSION_MIGRATE_FLAG_CONTRACTS, EXTENSION_RELOAD_FLAG_CONTRACTS, EXTENSION_UNINSTALL_FLAG_CONTRACTS, FILES_FLAG_CONTRACTS, GC_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, HISTORY_COMPACT_FLAG_CONTRACTS, HISTORY_REDACT_FLAG_CONTRACTS, HISTORY_REPAIR_FLAG_CONTRACTS, HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, INSTALL_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, ITEM_COMPLETE_FLAG_CONTRACTS, ITEM_MUTATE_FLAG_CONTRACTS, LEARNINGS_FLAG_CONTRACTS, LIST_COMMANDER_STRING_OPTION_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, MERGE_FLAG_CONTRACTS, NOTES_FLAG_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PACKAGE_INIT_FLAG_CONTRACTS, PM_EXTENSION_CAPABILITY_CONTRACTS, PM_EXTENSION_POLICY_MODE_CONTRACTS, PM_EXTENSION_POLICY_SURFACE_CONTRACTS, PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS, PM_EXTENSION_SERVICE_NAME_CONTRACTS, PM_EXTENSION_TRUST_MODE_CONTRACTS, PM_OUTPUT_DEGRADATION_STEPS, PLAN_FLAG_CONTRACTS, PM_CORE_COMMAND_NAMES, PM_TOOL_ACTIONS, PM_TOOL_PARAMETERS_SCHEMA, REINDEX_FLAG_CONTRACTS, RELEASE_FLAG_CONTRACTS, RESTORE_FLAG_CONTRACTS, SCHEMA_FLAG_CONTRACTS, PROFILE_FLAG_CONTRACTS, SEARCH_COMMANDER_STRING_OPTION_CONTRACTS, EVAL_FLAG_CONTRACTS, WORKSPACE_FLAG_CONTRACTS, NEXT_FLAG_CONTRACTS, SEARCH_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, START_TASK_FLAG_CONTRACTS, PAUSE_TASK_FLAG_CONTRACTS, TELEMETRY_FLAG_CONTRACTS, TEST_ALL_FLAG_CONTRACTS, TEST_FLAG_CONTRACTS, TEST_RUNS_FLAG_CONTRACTS, UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, UPDATE_COMMANDER_STRING_OPTION_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, UPGRADE_FLAG_CONTRACTS, VALIDATE_FLAG_CONTRACTS, compactFlagAliasContracts, resolvePmCommandOutputBudget, } from "../cli-contracts.js";
@@ -1744,6 +1744,15 @@ function attachCommanderAliasContractsResult(result, selection) {
     }
     result.commander_aliases_omitted_reason = "unfiltered_default_brief";
 }
+/** Attach the compact agent-facing command semantics shared by summary and full projections. */
+function attachAgentCommandContractsResult(result, outputCommands) {
+    result.command_summaries = buildCommandSummarySurface(outputCommands);
+    result.output_policy = {
+        token_estimate: "ceil(utf8_bytes / 4)",
+        degradation_ladder: [...PM_OUTPUT_DEGRADATION_STEPS],
+        allows_unbounded_opt_out: true,
+    };
+}
 /** Implements run contracts for the public runtime surface of this module. */
 export async function runContracts(options, global) {
     const selection = resolveContractsSelection(options);
@@ -1755,13 +1764,10 @@ export async function runContracts(options, global) {
     const commands = resolveContractsCommands(selection, actionContext);
     const outputCommands = resolveOutputCommands(selection, commands);
     const result = createContractsResult(selection, schemaContext, actionContext, outputCommands);
+    if (selection.summary || selection.fullOutput) {
+        attachAgentCommandContractsResult(result, outputCommands);
+    }
     if (selection.summary) {
-        result.command_summaries = buildCommandSummarySurface(outputCommands);
-        result.output_policy = {
-            token_estimate: "ceil(utf8_bytes / 4)",
-            degradation_ladder: [...PM_OUTPUT_DEGRADATION_STEPS],
-            allows_unbounded_opt_out: true,
-        };
         return result;
     }
     const commandAliases = buildCommandAliasSurface(commands);
@@ -1821,4 +1827,4 @@ export const _testOnlyContractsCommand = {
     toRuntimeShortFlagToken,
 };
 //# sourceMappingURL=runtime-contracts.js.map
-//# debugId=e6dd81d6-95d6-51e6-a0c9-ba7bb5372457
+//# debugId=36bb127d-7a88-5e0d-8296-3d74b9ceb813