@unbrained/pm-cli 2026.8.6 → 2026.8.8

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

@@ -13,6 +13,7 @@ import { type CliFlagInvocationContract } from "../flag-invocation-contracts.js"
 import { type PmCommandVisibilityTier } from "../agent-capability-contracts.js";
 import type { PmErrorCodeContract } from "../error-code-catalog.js";
 import { type PmCommandOutputEnvelopeContract } from "../output-contracts.js";
+import { type PmCommandExitContract, type PmCommandExitOutcomeContract } from "./command-exit-contracts.js";
 /** Documents the contracts command options payload exchanged by command, SDK, and package integrations. */
 export interface ContractsCommandOptions {
     /** Value that configures or reports action for this contract. */
@@ -152,6 +153,14 @@ export interface ContractsResult {
         budget: PmCommandOutputBudgetContract;
         envelope: PmCommandOutputEnvelopeContract;
     }>;
+    /** Stable outcome vocabulary and exhaustive per-command process exit sets. */
+    command_exit_contracts?: {
+        vocabulary: readonly PmCommandExitOutcomeContract[];
+        command_sets: Array<{
+            commands: string[];
+            exit_codes: PmCommandExitContract["exit_codes"];
+        }>;
+    };
 }
 type PmToolAction = (typeof PM_TOOL_ACTIONS)[number];
 /** Documents the contracts action availability payload exchanged by command, SDK, and package integrations. */
@@ -260,6 +269,7 @@ declare function attachCreateRequiredOptionContracts(schema: Record<string, unkn
 declare function readContractsSettings(pmRoot: string, readSettingsFn?: typeof readSettings): Promise<Awaited<ReturnType<typeof readSettings>>>;
 declare function buildCommandSummarySurface(commands: readonly string[]): CommandSummarySurface[];
 declare function buildCommandOutputContracts(commands: readonly string[]): NonNullable<ContractsResult["command_output_contracts"]>;
+declare function buildCommandExitContractGroups(commands: readonly string[]): NonNullable<ContractsResult["command_exit_contracts"]>["command_sets"];
 /** Implements run contracts for the public runtime surface of this module. */
 export declare function runContracts(options: ContractsCommandOptions, global: GlobalOptions): Promise<ContractsResult>;
 /** Public contract for test only contracts command, shared by SDK and presentation-layer consumers. */
@@ -269,6 +279,7 @@ export declare const _testOnlyContractsCommand: {
     buildExtensionActionSchemaBranch: typeof buildExtensionActionSchemaBranch;
     buildCommandSummarySurface: typeof buildCommandSummarySurface;
     buildCommandOutputContracts: typeof buildCommandOutputContracts;
+    buildCommandExitContractGroups: typeof buildCommandExitContractGroups;
     buildRuntimeFieldFlagContracts: typeof buildRuntimeFieldFlagContracts;
     collectActionContractDescriptors: typeof collectActionContractDescriptors;
     collectExtensionCommandContracts: typeof collectExtensionCommandContracts;

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]="adf76b7b-fc29-5b35-b33a-5ae008cbc8e7")}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";
@@ -16,6 +16,7 @@ import { enrichCliFlagInvocationContracts, } from "../flag-invocation-contracts.
 import { resolvePmCommandVisibilityTier, } from "../agent-capability-contracts.js";
 import { PM_ERROR_CODE_CATALOG } from "../generated-error-code-catalog.js";
 import { resolvePmCommandOutputEnvelope, } from "../output-contracts.js";
+import { PM_COMMAND_EXIT_OUTCOME_CONTRACTS, resolvePmCommandExitContract, } from "./command-exit-contracts.js";
 const AGENT_BOOTSTRAP_FLAGS = new Map([
     [
         "claim",
@@ -1619,6 +1620,27 @@ function buildCommandOutputContracts(commands) {
         envelope: resolvePmCommandOutputEnvelope(command),
     }));
 }
+function buildCommandExitContractGroups(commands) {
+    const groups = new Map();
+    for (const command of commands) {
+        const contract = resolvePmCommandExitContract(command);
+        const exitCodes = contract === undefined
+            ? [
+                EXIT_CODE.SUCCESS,
+                EXIT_CODE.GENERIC_FAILURE,
+                EXIT_CODE.USAGE,
+                EXIT_CODE.NOT_FOUND,
+                EXIT_CODE.CONFLICT,
+                EXIT_CODE.DEPENDENCY_FAILED,
+            ]
+            : contract.exit_codes;
+        const key = exitCodes.join(",");
+        const group = groups.get(key) ?? { commands: [], exit_codes: exitCodes };
+        group.commands.push(command);
+        groups.set(key, group);
+    }
+    return [...groups.values()];
+}
 function resolveExtensionCommandContracts(selection, runtime, outputCommands) {
     if (selection.selectedCommand) {
         return runtime.extensionContracts.filter((entry) => splitCommandPathAliases(entry.command).includes(selection.selectedCommand));
@@ -1744,6 +1766,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 +1786,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);
@@ -1785,6 +1813,10 @@ export async function runContracts(options, global) {
         result.error_codes = PM_ERROR_CODE_CATALOG;
         result.command_output_contracts =
             buildCommandOutputContracts(outputCommands);
+        result.command_exit_contracts = {
+            vocabulary: PM_COMMAND_EXIT_OUTCOME_CONTRACTS,
+            command_sets: buildCommandExitContractGroups(outputCommands),
+        };
     }
     return result;
 }
@@ -1795,6 +1827,7 @@ export const _testOnlyContractsCommand = {
     buildExtensionActionSchemaBranch,
     buildCommandSummarySurface,
     buildCommandOutputContracts,
+    buildCommandExitContractGroups,
     buildRuntimeFieldFlagContracts,
     collectActionContractDescriptors,
     collectExtensionCommandContracts,
@@ -1821,4 +1854,4 @@ export const _testOnlyContractsCommand = {
     toRuntimeShortFlagToken,
 };
 //# sourceMappingURL=runtime-contracts.js.map
-//# debugId=e6dd81d6-95d6-51e6-a0c9-ba7bb5372457
+//# debugId=adf76b7b-fc29-5b35-b33a-5ae008cbc8e7

package/dist/sdk/cli-contracts/tool-parameter-tables.js

@@ -4,8 +4,9 @@
  * Defines SDK command-contract metadata for Tool Parameter Tables.
  */
 
-!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]="4dd6e565-011f-5411-9fcb-37e94ee4cdb2")}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]="35c4b819-02d6-582a-a7eb-fe3f4a4903d9")}catch(e){}}();
 import { PLAN_HARNESS_VALUES, PLAN_MODE_VALUES, PLAN_STEP_LINK_KIND_VALUES, PLAN_STEP_STATUS_VALUES, } from "../../types/index.js";
+import { PM_READ_OUTPUT_SESSION_MAX_SEEN_ITEM_IDS } from "../read-output-session.js";
 /** Public contract for pm tool parameter properties, shared by SDK and presentation-layer consumers. */
 export const PM_TOOL_PARAMETER_PROPERTIES = {
     json: { type: "boolean", default: true },
@@ -20,6 +21,39 @@ export const PM_TOOL_PARAMETER_PROPERTIES = {
     },
     outputBudget: { type: "integer", minimum: 1 },
     outputFormat: { type: "string", enum: ["json", "toon"] },
+    outputSession: {
+        anyOf: [
+            { type: "string", minLength: 1 },
+            {
+                type: "object",
+                additionalProperties: false,
+                required: [
+                    "version",
+                    "id",
+                    "token_budget",
+                    "spent_tokens",
+                    "seen_item_ids",
+                ],
+                properties: {
+                    version: { const: 1 },
+                    id: {
+                        type: "string",
+                        pattern: "^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$",
+                    },
+                    token_budget: { type: "integer", minimum: 256 },
+                    spent_tokens: { type: "integer", minimum: 0 },
+                    seen_item_ids: {
+                        type: "array",
+                        maxItems: PM_READ_OUTPUT_SESSION_MAX_SEEN_ITEM_IDS,
+                        items: {
+                            type: "string",
+                            pattern: "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
+                        },
+                    },
+                },
+            },
+        ],
+    },
     path: { type: "string" },
     pmExecutable: { type: "string" },
     timeoutMs: { type: "number" },
@@ -365,6 +399,21 @@ export const PM_TOOL_PARAMETER_PROPERTIES = {
     byTag: { type: "boolean" },
     byPriority: { type: "boolean" },
     tagPrefix: { type: "string" },
+    measurements: { type: "boolean" },
+    metric: { type: "string" },
+    measurementLimit: { type: "integer", minimum: 0, maximum: 1000 },
+    observe: { type: "array", items: { type: "string" } },
+    improvementDirection: {
+        type: "string",
+        enum: ["higher", "lower", "target"],
+    },
+    measurementSource: { type: "string" },
+    measurementItem: { type: "string" },
+    measurementRevision: { type: "string" },
+    provenanceCoverage: { type: "boolean" },
+    fleetAttribution: { type: "boolean" },
+    eventLimit: { type: "integer", minimum: 1, maximum: 100000 },
+    minimumSample: { type: "integer", minimum: 1, maximum: 10000 },
     verify: { type: "boolean" },
     literal: { type: "array", items: { type: "string" } },
     regex: { type: "array", items: { type: "string" } },
@@ -562,10 +611,7 @@ export const PM_TOOL_PARAMETER_PROPERTIES = {
 export const PM_TOOL_ACTION_SCOPED_PARAMETER_PROPERTIES = {
     activity: {
         harness: {
-            anyOf: [
-                { type: "string" },
-                { type: "array", items: { type: "string" } },
-            ],
+            anyOf: [{ type: "string" }, { type: "array", items: { type: "string" } }],
         },
     },
     events: {
@@ -586,10 +632,7 @@ export const PM_TOOL_ACTION_SCOPED_PARAMETER_PROPERTIES = {
     },
     history: {
         harness: {
-            anyOf: [
-                { type: "string" },
-                { type: "array", items: { type: "string" } },
-            ],
+            anyOf: [{ type: "string" }, { type: "array", items: { type: "string" } }],
         },
     },
     remind: {
@@ -845,6 +888,18 @@ export const PM_TOOL_PARAMETER_METADATA = {
         description: "Universal read-result encoding selector.",
         examples: ["toon", "json"],
     },
+    outputSession: {
+        description: "Caller-carried JSON session state that enforces a token ceiling across read calls and replaces repeated item facts with resolvable context references.",
+        examples: [
+            {
+                version: 1,
+                id: "orientation",
+                token_budget: 4000,
+                spent_tokens: 0,
+                seen_item_ids: [],
+            },
+        ],
+    },
     profile: {
         description: "Emit deterministic timing diagnostics to stderr.",
     },
@@ -1255,6 +1310,51 @@ export const PM_TOOL_PARAMETER_METADATA = {
     fieldUtilization: {
         description: "For stats action: include a field_utilization block reporting present/total/percent for content fields (notes, learnings, files, docs, tests, comments, deps, body, linked_command) across all items so under-documented dimensions are visible at a glance.",
     },
+    measurements: {
+        description: "For stats action: include the audited append-only improvement ledger and baseline-to-latest trends.",
+    },
+    metric: {
+        description: "Exact improvement metric name used to filter ledger reads.",
+        examples: ["quality.coverage.lines"],
+    },
+    measurementLimit: {
+        description: "Maximum newest improvement observations returned by stats.",
+        examples: [50],
+    },
+    observe: {
+        description: "Repeatable audited observation in name=value[,unit=...][,threshold=...] form.",
+        examples: [["quality.coverage.lines=100,unit=percent,threshold=100"]],
+    },
+    improvementDirection: {
+        description: "Improvement direction for newly recorded observations.",
+        examples: ["higher", "lower", "target"],
+    },
+    measurementSource: {
+        description: "Producing gate or instrument for a new observation.",
+        examples: ["pnpm coverage"],
+    },
+    measurementItem: {
+        description: "Tracked item that owns an improvement observation.",
+        examples: ["pm-123abc"],
+    },
+    measurementRevision: {
+        description: "Explicit source revision for a new observation.",
+        examples: ["0123456789abcdef"],
+    },
+    provenanceCoverage: {
+        description: "For stats action: compare configured provenance descriptors with bounded immutable-history observations.",
+    },
+    fleetAttribution: {
+        description: "For stats action: derive observational throughput, rework, and defect-escape rates by harness, model, and author source.",
+    },
+    eventLimit: {
+        description: "Maximum immutable history events consumed by an analytics projection.",
+        examples: [10000],
+    },
+    minimumSample: {
+        description: "Minimum denominator before analytics rates are reported.",
+        examples: [5],
+    },
     offset: {
         description: "Number of matching rows to skip before limit is applied.",
         examples: [0, 50, "100"],
@@ -1664,6 +1764,12 @@ export const PM_TOOL_PARAMETER_METADATA = {
  * because its single `name` property must cover every action at once.
  */
 export const PM_TOOL_ACTION_SCOPED_PARAMETER_METADATA = {
+    stats: {
+        since: {
+            description: "Inclusive ISO 8601 timestamp or negative duration lower bound for provenance and fleet analytics.",
+            examples: ["2026-08-01T00:00:00.000Z", "-30d"],
+        },
+    },
     events: {
         since: {
             description: "Durable event cursor returned as next_cursor, or an inclusive event timestamp.",
@@ -1698,12 +1804,25 @@ export const PM_TOOL_ACTION_SCOPED_PARAMETER_METADATA = {
             examples: [600, "1200"],
         },
     },
+    comments: {
+        full: {
+            description: "Return the complete post-mutation comment history instead of the bounded mutation receipt projection.",
+        },
+    },
     notes: {
+        full: {
+            description: "Return the complete post-mutation note history instead of the bounded mutation receipt projection.",
+        },
         since: {
             description: "Inclusive ISO 8601 creation timestamp lower bound for structured note event filtering.",
             examples: ["2026-01-01T00:00:00.000Z"],
         },
     },
+    learnings: {
+        full: {
+            description: "Return the complete post-mutation learning history instead of the bounded mutation receipt projection.",
+        },
+    },
     next: {
         tag: {
             description: "Only recommend items carrying this exact tag.",
@@ -1788,4 +1907,4 @@ export const PM_TOOL_ACTION_SCOPED_PARAMETER_METADATA = {
     },
 };
 //# sourceMappingURL=tool-parameter-tables.js.map
-//# debugId=4dd6e565-011f-5411-9fcb-37e94ee4cdb2
+//# debugId=35c4b819-02d6-582a-a7eb-fe3f4a4903d9

package/dist/sdk/cli-contracts/tool-schema.d.ts

@@ -91,7 +91,7 @@ export interface PmActionToolInputSchemaOptions {
  */
 export declare function buildPmActionToolInputSchema(action: PmToolAction, options?: PmActionToolInputSchemaOptions): Record<string, unknown>;
 /** Canonical version of the action-scoped strict MCP tool-parameters schema (`PM_TOOL_PARAMETERS_SCHEMA`). Exported as the single source of truth so the MCP server, the `pm contracts` command, SDK consumers, and the contract tests all bind to one constant instead of re-typing the `"4.0.2"` literal (pm-r9sz). Bump the patch/minor for additive, backward-compatible schema changes; bump the MAJOR for breaking changes — the major also drives the `$id` `tool-parameters-v{major}` slug, so the two never drift. */
-export declare const PM_TOOL_PARAMETERS_SCHEMA_VERSION: "4.4.0";
+export declare const PM_TOOL_PARAMETERS_SCHEMA_VERSION: "4.4.1";
 /**
  * Major component of {@link PM_TOOL_PARAMETERS_SCHEMA_VERSION}, used to build the
  * schema `$id` slug so a breaking version bump renames the document in lockstep.

package/dist/sdk/cli-contracts/tool-schema.js

@@ -7,7 +7,7 @@
  * consumers from a single source of truth.
  */
 
-!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]="b26c9bc3-e1bf-5174-a0af-296c947678da")}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]="d9f01e68-6b54-5861-a4b5-ae40613c2047")}catch(e){}}();
 import { normalizeUniqueStringList } from "./string-lists.js";
 import { PM_TOOL_ACTIONS } from "./enum-contracts.js";
 import { TOOL_CREATE_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_MANY_FILTER_OPTION_CONTRACTS, TOOL_CONTEXT_OPTION_CONTRACTS, TOOL_ACTIVITY_OPTION_CONTRACTS, TOOL_LIST_FILTER_OPTION_CONTRACTS, TOOL_AGGREGATE_OPTION_CONTRACTS, TOOL_SEARCH_FILTER_OPTION_CONTRACTS, TOOL_CLOSE_MANY_FILTER_OPTION_CONTRACTS, } from "./tool-option-contracts.js";
@@ -30,6 +30,7 @@ const PM_TOOL_READ_OUTPUT_PARAMETER_KEYS = [
     "outputLimit",
     "outputBudget",
     "outputFormat",
+    "outputSession",
 ];
 /** Canonical top-level MCP properties that take precedence over runtime custom fields. */
 export const PM_TOOL_RESERVED_CUSTOM_FIELD_PROPERTIES = new Set([
@@ -810,6 +811,7 @@ const PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
             "edit",
             "delete",
             "limit",
+            "full",
             ...AUTHOR_MESSAGE_FORCE_PARAMETER_KEYS,
         ],
     },
@@ -826,6 +828,7 @@ const PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
             "since",
             "eventType",
             "includeMeta",
+            "full",
             ...AUTHOR_MESSAGE_FORCE_PARAMETER_KEYS,
         ],
         mutuallyExclusive: [
@@ -845,6 +848,7 @@ const PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
             "edit",
             "delete",
             "limit",
+            "full",
             ...AUTHOR_MESSAGE_FORCE_PARAMETER_KEYS,
         ],
     },
@@ -1013,6 +1017,21 @@ const PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
             "byTag",
             "byPriority",
             "tagPrefix",
+            "measurements",
+            "metric",
+            "measurementLimit",
+            "observe",
+            "improvementDirection",
+            "measurementSource",
+            "measurementItem",
+            "measurementRevision",
+            "author",
+            "message",
+            "provenanceCoverage",
+            "fleetAttribution",
+            "since",
+            "eventLimit",
+            "minimumSample",
         ],
     },
     duplicates: {
@@ -1411,7 +1430,7 @@ function createLazyContractSchema(build) {
     });
 }
 /** Canonical version of the action-scoped strict MCP tool-parameters schema (`PM_TOOL_PARAMETERS_SCHEMA`). Exported as the single source of truth so the MCP server, the `pm contracts` command, SDK consumers, and the contract tests all bind to one constant instead of re-typing the `"4.0.2"` literal (pm-r9sz). Bump the patch/minor for additive, backward-compatible schema changes; bump the MAJOR for breaking changes — the major also drives the `$id` `tool-parameters-v{major}` slug, so the two never drift. */
-export const PM_TOOL_PARAMETERS_SCHEMA_VERSION = "4.4.0";
+export const PM_TOOL_PARAMETERS_SCHEMA_VERSION = "4.4.1";
 /**
  * Major component of {@link PM_TOOL_PARAMETERS_SCHEMA_VERSION}, used to build the
  * schema `$id` slug so a breaking version bump renames the document in lockstep.
@@ -1493,4 +1512,4 @@ export const _testOnlyCliContracts = {
     withFlagAliasMetadata,
 };
 //# sourceMappingURL=tool-schema.js.map
-//# debugId=b26c9bc3-e1bf-5174-a0af-296c947678da
+//# debugId=d9f01e68-6b54-5861-a4b5-ae40613c2047

package/dist/sdk/cli-program.js

@@ -4,7 +4,7 @@
  * Builds the reusable Commander root that embeds pm's universal global contracts.
  */
 
-!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]="26c939a0-e02d-5998-95e3-a4c26c3b47bd")}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]="a410d336-c332-56fc-9a5d-7841a2b3dfa5")}catch(e){}}();
 import { Command } from "commander";
 import { writeStdout } from "../core/output/output.js";
 /** Create a fresh pm root program suitable for one-shot CLI or embedded hosts. */
@@ -29,6 +29,7 @@ export function createPmCliProgram(version) {
         .option("--output-limit <count>", "Bound rows in read output")
         .option("--output-budget <tokens>", "Bound estimated tokens in read output")
         .option("--output-format <toon|json>", "Select the read-output encoding")
+        .option("--output-session <state>", "Carry a JSON session budget and served-item ledger across read calls")
         .option("--quiet", "Suppress stdout output")
         .option("--no-changed-fields", "Omit the changed_fields array from mutation output (keeps changed_field_count)")
         .option("--full-changed-fields", "Restore the legacy full mutation envelope and changed_fields array")
@@ -43,4 +44,4 @@ export function createPmCliProgram(version) {
         .exitOverride();
 }
 //# sourceMappingURL=cli-program.js.map
-//# debugId=26c939a0-e02d-5998-95e3-a4c26c3b47bd
+//# debugId=a410d336-c332-56fc-9a5d-7841a2b3dfa5

package/dist/sdk/comments.d.ts

@@ -1,5 +1,6 @@
 import { type GlobalOptions } from "./runtime-primitives.js";
 import type { Comment } from "../types/index.js";
+import { type AnnotationMutationReceipt, type AnnotationOmissionReceipt } from "./annotations.js";
 /** Documents the comments command options payload exchanged by command, SDK, and package integrations. */
 export interface CommentsCommandOptions {
     /** Value that configures or reports add for this contract. */
@@ -16,6 +17,8 @@ export interface CommentsCommandOptions {
     limit?: string;
     /** Value that configures or reports include meta for this contract. */
     includeMeta?: boolean;
+    /** Return complete comment history after a mutation instead of a bounded receipt. */
+    fullHistory?: boolean;
     /** Value that configures or reports author for this contract. */
     author?: string;
     /** Human-readable explanation suitable for logs and agent-facing output. */
@@ -39,6 +42,10 @@ export interface CommentsResult {
     has_more?: boolean;
     /** Value that configures or reports limit for this contract. */
     limit?: number;
+    /** Mutation identity when this result changed the collection. */
+    mutation_receipt?: AnnotationMutationReceipt;
+    /** Declares whether older comments were withheld from a mutation response. */
+    omission_receipt?: AnnotationOmissionReceipt;
 }
 /** Implements run comments for the public runtime surface of this module. */
 export declare function runComments(id: string, options: CommentsCommandOptions, global: GlobalOptions): Promise<CommentsResult>;

package/dist/sdk/comments.js

@@ -4,7 +4,7 @@
  * Implements the pm comments 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]="500e83b0-28a8-58b1-a625-2d81eb245eb4")}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]="667218ac-866c-59b1-8309-18ad92434fca")}catch(e){}}();
 import { readFile } from "node:fs/promises";
 import { EXIT_CODE, PmCliError, createStdinTokenResolver, } from "./runtime-primitives.js";
 import { isErrnoError, parseAnnotationTextInput, runAnnotationCommand, } from "./annotations.js";
@@ -122,4 +122,4 @@ export async function runComments(id, options, global) {
     });
 }
 //# sourceMappingURL=comments.js.map
-//# debugId=500e83b0-28a8-58b1-a625-2d81eb245eb4
+//# debugId=667218ac-866c-59b1-8309-18ad92434fca

package/dist/sdk/completion.js

@@ -4,7 +4,7 @@
  * Implements the pm completion 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]="bba460dd-91d7-5444-b754-58c684a425fd")}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]="6c9648d7-ab14-5e0d-8793-86ae13643fa6")}catch(e){}}();
 import { EXIT_CODE, PmCliError } from "./runtime-primitives.js";
 import { listPmCommandsForTier } from "./agent-capability-contracts.js";
 import { SCAFFOLD_CAPABILITIES } from "./extension/scaffold.js";
@@ -599,13 +599,13 @@ export function generateBashScript(itemTypes = [], tags = [], eagerTagExpansion
         `      COMPREPLY=(${compgen(`${LIFECYCLE_ACTIONS} ${PACKAGE_LIFECYCLE_FLAGS}`)})`,
         "      ;;",
         "    comments)",
-        `      COMPREPLY=(${compgen("--add --body --stdin --file --edit --delete --limit --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
+        `      COMPREPLY=(${compgen("--add --body --stdin --file --edit --delete --limit --full-history --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
         "      ;;",
         "    notes)",
-        `      COMPREPLY=(${compgen("--add --add-json --stdin --file --edit --delete --limit --since --event-type --include-meta --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
+        `      COMPREPLY=(${compgen("--add --add-json --stdin --file --edit --delete --limit --since --event-type --include-meta --full-history --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
         "      ;;",
         "    learnings)",
-        `      COMPREPLY=(${compgen("--add --stdin --file --edit --delete --limit --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
+        `      COMPREPLY=(${compgen("--add --stdin --file --edit --delete --limit --full-history --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
         "      ;;",
         "    files)",
         `      COMPREPLY=(${compgen("discover lookup --add --add-glob --remove --migrate --list --apply --note --append-stable --validate-paths --scope --limit --offset --no-truncate --strict-read --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
@@ -787,6 +787,7 @@ _pm() {
     '--output-limit[Set the universal read row ceiling]:limit' \\
     '--output-budget[Set the universal estimated-token ceiling]:tokens' \\
     '--output-format[Select the universal read encoding]:(toon json)' \\
+    '--output-session[Carry cross-call read budget and served-item state]:state' \\
     '--no-changed-fields[Omit changed_fields array from mutation output]' \\
     '--pm-path[Explicit tracker storage path for this command]:path:_files -/' \\
     '--path[Compatibility alias for --pm-path]:path:_files -/' \\
@@ -1353,6 +1354,7 @@ ${zshSearchRuntimeFieldFlags}            '--json[Output JSON]' \\
             '--edit[Replace the comment at 1-based index (text from positional/--add/--stdin/--file)]:index' \\
             '--delete[Delete the comment at 1-based index]:index' \\
             '--limit[Return only latest n entries]:number' \\
+            '--full-history[Return complete post-mutation history]' \\
             '--author[Entry author (falls back to PM_AUTHOR/settings)]:author' \\
             '--message[History message]:message' \\
             '--force[Force override]' \\
@@ -1371,6 +1373,7 @@ ${zshSearchRuntimeFieldFlags}            '--json[Output JSON]' \\
             '--since[Return structured events at or after an ISO timestamp]:timestamp' \\
             '--event-type[Return structured events with this top-level type]:event_type' \\
             '--include-meta[Include result counts and truncation metadata]' \\
+            '--full-history[Return complete post-mutation history]' \\
             '--author[Entry author (falls back to PM_AUTHOR/settings)]:author' \\
             '--message[History message]:message' \\
             '--force[Force override]' \\
@@ -1385,6 +1388,7 @@ ${zshSearchRuntimeFieldFlags}            '--json[Output JSON]' \\
             '--edit[Replace the entry at a 1-based index]:index' \\
             '--delete[Delete the entry at a 1-based index]:index' \\
             '--limit[Return only latest n entries]:number' \\
+            '--full-history[Return complete post-mutation history]' \\
             '--author[Entry author (falls back to PM_AUTHOR/settings)]:author' \\
             '--message[History message]:message' \\
             '--force[Force override]' \\
@@ -1811,6 +1815,7 @@ complete -c pm -l output-include -d 'Retain comma-separated read fields or secti
 complete -c pm -l output-limit -d 'Set the universal read row ceiling' -r
 complete -c pm -l output-budget -d 'Set the universal estimated-token ceiling' -r
 complete -c pm -l output-format -d 'Select the universal read encoding' -r -a 'toon json'
+complete -c pm -l output-session -d 'Carry cross-call read budget and served-item state' -r
 complete -c pm -l no-changed-fields -d 'Omit changed_fields array from mutation output'
 complete -c pm -l id-only -d 'Print only id and status for single-item mutation output'
 complete -c pm -l pm-path -d 'Explicit tracker storage path for this command' -r
@@ -2413,6 +2418,7 @@ complete -c pm -n '__fish_seen_subcommand_from notes' -l file -d 'Read entry tex
 complete -c pm -n '__fish_seen_subcommand_from notes' -l edit -d 'Replace the entry at a 1-based index' -r
 complete -c pm -n '__fish_seen_subcommand_from notes' -l delete -d 'Delete the entry at a 1-based index' -r
 complete -c pm -n '__fish_seen_subcommand_from comments notes learnings' -l limit -d 'Return only latest n entries' -r
+complete -c pm -n '__fish_seen_subcommand_from comments notes learnings' -l full-history -d 'Return complete post-mutation history'
 complete -c pm -n '__fish_seen_subcommand_from comments notes learnings' -l author -d 'Entry author' -r
 complete -c pm -n '__fish_seen_subcommand_from comments notes learnings' -l message -d 'History message' -r
 complete -c pm -n '__fish_seen_subcommand_from comments notes learnings' -l force -d 'Force override'
@@ -2484,6 +2490,7 @@ complete -c pm -n '__fish_seen_subcommand_from stats' -l by-assignee -d 'Lifecyc
 complete -c pm -n '__fish_seen_subcommand_from stats' -l by-tag -d 'Lifecycle-bucketed breakdown grouped by tag'
 complete -c pm -n '__fish_seen_subcommand_from stats' -l by-priority -d 'Lifecycle-bucketed breakdown grouped by priority'
 complete -c pm -n '__fish_seen_subcommand_from stats' -l tag-prefix -d 'With --by-tag: only count tags with this prefix' -r
+complete -c pm -n '__fish_seen_subcommand_from stats' -l analytics -d 'Improvement ledger/history analytics JSON' -r
 
 # append flags
 complete -c pm -n '__fish_seen_subcommand_from append' -s b -l body -d 'Item body' -r
@@ -2740,4 +2747,4 @@ export function runCompletion(shell, itemTypes = [], tags = [], eagerTagExpansio
     };
 }
 //# sourceMappingURL=completion.js.map
-//# debugId=bba460dd-91d7-5444-b754-58c684a425fd
+//# debugId=6c9648d7-ab14-5e0d-8793-86ae13643fa6

package/dist/sdk/contracts.d.ts

@@ -4,6 +4,7 @@
  * Exposes command and action contract data without loading SDK runtime code.
  */
 export * from "./cli-contracts.js";
+export * from "./cli-contracts/command-exit-contracts.js";
 export * from "./context-intent-contracts.js";
 export * from "./error-code-catalog.js";
 export * from "./generated-error-code-catalog.js";
@@ -11,3 +12,4 @@ export * from "./flag-invocation-contracts.js";
 export * from "./output-token-accounting.js";
 export * from "./output-contracts.js";
 export * from "./read-output-contracts.js";
+export type { PmReadOutputSessionReceipt, PmReadOutputSessionState, } from "./read-output-session.js";