@unbrained/pm-cli 2026.8.6 → 2026.8.7

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]="57065b65-6582-5405-bf16-698023e204bf")}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.",
@@ -1788,4 +1894,4 @@ export const PM_TOOL_ACTION_SCOPED_PARAMETER_METADATA = {
     },
 };
 //# sourceMappingURL=tool-parameter-tables.js.map
-//# debugId=4dd6e565-011f-5411-9fcb-37e94ee4cdb2
+//# debugId=57065b65-6582-5405-bf16-698023e204bf

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]="7fd02be1-d45b-5c2c-892a-4fbf8c1d5b9a")}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([
@@ -1013,6 +1014,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: {
@@ -1493,4 +1509,4 @@ export const _testOnlyCliContracts = {
     withFlagAliasMetadata,
 };
 //# sourceMappingURL=tool-schema.js.map
-//# debugId=b26c9bc3-e1bf-5174-a0af-296c947678da
+//# debugId=7fd02be1-d45b-5c2c-892a-4fbf8c1d5b9a

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/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]="8acb405a-140e-532c-81c0-e8153ea30dc0")}catch(e){}}();
 import { EXIT_CODE, PmCliError } from "./runtime-primitives.js";
 import { listPmCommandsForTier } from "./agent-capability-contracts.js";
 import { SCAFFOLD_CAPABILITIES } from "./extension/scaffold.js";
@@ -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 -/' \\
@@ -1811,6 +1812,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
@@ -2484,6 +2486,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 +2743,4 @@ export function runCompletion(shell, itemTypes = [], tags = [], eagerTagExpansio
     };
 }
 //# sourceMappingURL=completion.js.map
-//# debugId=bba460dd-91d7-5444-b754-58c684a425fd
+//# debugId=8acb405a-140e-532c-81c0-e8153ea30dc0

package/dist/sdk/contracts.d.ts

@@ -11,3 +11,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";

package/dist/sdk/contracts.js

@@ -4,7 +4,7 @@
  * Exposes command and action contract data without loading SDK runtime code.
  */
 
-!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]="2962656f-386f-59a0-8dc1-411ae382dddb")}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]="8c442738-13e6-5bf5-b60d-1439c3255f1a")}catch(e){}}();
 export * from "./cli-contracts.js";
 export * from "./context-intent-contracts.js";
 export * from "./error-code-catalog.js";
@@ -14,4 +14,4 @@ export * from "./output-token-accounting.js";
 export * from "./output-contracts.js";
 export * from "./read-output-contracts.js";
 //# sourceMappingURL=contracts.js.map
-//# debugId=2962656f-386f-59a0-8dc1-411ae382dddb
+//# debugId=8c442738-13e6-5bf5-b60d-1439c3255f1a

package/dist/sdk/core.d.ts

@@ -6,6 +6,8 @@
 export { BASELINE_ITEM_FORMAT_VERSION, BUILTIN_ITEM_TYPE_VALUES, CONFIDENCE_TEXT_VALUES, CURRENT_ITEM_FORMAT_VERSION, DEPENDENCY_KIND_VALUES, EXIT_CODE, ISSUE_SEVERITY_VALUES, ITEM_TYPE_VALUES, PM_CLI_EXPECTED_ERROR_NAME, PmCliError, PmClient, RISK_VALUES, STATUS_VALUES, canonicalDocument, classifyItemFormatVersion, createPmCliExpectedError, effectiveItemFormatVersion, emptyImportedDocument, isPmCliExpectedError, normalizeItemFormatVersion, normalizeItemId, normalizeStatusInput, nowIso, runAction, serializeItemDocument, aggregate, append, claim, claimNext, close, comments, context, copy, create, deleteItem, deps, docs, files, filesDiscover, focus, get, graph, learnings, list, next, notes, release, restore, search, update, type AggregateOptions, type AggregateResult, type AggregateRow, type AppendCommandOptions, type AppendResult, type ClaimNextOptions, type ClaimResult, type CloseResult, type CommentsCommandOptions, type CommentsResult, type ContextOptions, type ContextResult, type CopyResult, type CreateResult, type Dependency, type DeleteResult, type DepsCommandOptions, type DepsResult, type DocsCommandOptions, type DocsResult, type FilesCommandOptions, type FilesDiscoverOptions, type FilesDiscoverResult, type FilesResult, type FocusResult, type GetOptions, type GetResult, type ItemFormatVersionScanEntry, type ItemFormatVersionScanResult, type ItemFormatVersionStatus, type LearningsCommandOptions, type LearningsResult, type ListOptions, type ListResult, type NextOptions, type NextResult, type NotesCommandOptions, type NotesResult, type PmActionInput, type PmActionName, type PmActionOptions, type PmClientOptions, type ReleaseResult, type RestoreResult, type SearchOptions, type SearchResult, type UpdateResult, } from "./runtime.js";
 export * from "./core-governance.js";
 export * from "./agent-session-context.js";
-export { PM_READ_OUTPUT_DIMENSIONS, PM_READ_OUTPUT_OPTION_FLAGS, PM_READ_OUTPUT_SURFACE_CONTRACTS, applyReadOutputDimensions, isReadOutputBudgetExceeded, resolveReadOutputDimensions, resolveReadOutputEncoding, resolveReadOutputSurface, validateReadOutputOptions, } from "./read-output-contracts.js";
+export { PM_READ_OUTPUT_DIMENSIONS, PM_READ_OUTPUT_OPTION_FLAGS, PM_READ_OUTPUT_COMPOSITION_OPTION_FLAGS, PM_READ_OUTPUT_SURFACE_CONTRACTS, applyReadOutputDimensions, isReadOutputBudgetExceeded, resolveReadOutputDimensions, resolveReadOutputEncoding, resolveReadOutputSurface, validateReadOutputOptions, } from "./read-output-contracts.js";
+export { applyReadOutputSessionReferences, attachReadOutputSessionReceipt, parseReadOutputSession, readOutputSessionRemainingTokens, } from "./read-output-session.js";
 export type { PmReadOutputBudgetExceeded, PmReadOutputDimension, PmReadOutputLegacyAlias, PmReadOutputOptions, PmReadOutputReceipt, PmReadOutputResult, PmReadOutputResultFor, PmReadOutputSurface, PmReadOutputSurfaceContract, } from "./read-output-contracts.js";
+export type { PmReadOutputSessionReceipt, PmReadOutputSessionReference, PmReadOutputSessionState, } from "./read-output-session.js";
 export type { ItemDocument, ItemMetadata, ItemStatus, ItemType, PmSettings, } from "../types/index.js";

package/dist/sdk/core.js

@@ -4,10 +4,11 @@
  * Provides the stable item lifecycle client and universal project data types.
  */
 
-!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]="d70db3d9-b094-52fd-8f0f-47eed9f6e7f0")}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]="54d31df7-e708-585d-9fb2-3c5ddfcc6138")}catch(e){}}();
 export { BASELINE_ITEM_FORMAT_VERSION, BUILTIN_ITEM_TYPE_VALUES, CONFIDENCE_TEXT_VALUES, CURRENT_ITEM_FORMAT_VERSION, DEPENDENCY_KIND_VALUES, EXIT_CODE, ISSUE_SEVERITY_VALUES, ITEM_TYPE_VALUES, PM_CLI_EXPECTED_ERROR_NAME, PmCliError, PmClient, RISK_VALUES, STATUS_VALUES, canonicalDocument, classifyItemFormatVersion, createPmCliExpectedError, effectiveItemFormatVersion, emptyImportedDocument, isPmCliExpectedError, normalizeItemFormatVersion, normalizeItemId, normalizeStatusInput, nowIso, runAction, serializeItemDocument, aggregate, append, claim, claimNext, close, comments, context, copy, create, deleteItem, deps, docs, files, filesDiscover, focus, get, graph, learnings, list, next, notes, release, restore, search, update, } from "./runtime.js";
 export * from "./core-governance.js";
 export * from "./agent-session-context.js";
-export { PM_READ_OUTPUT_DIMENSIONS, PM_READ_OUTPUT_OPTION_FLAGS, PM_READ_OUTPUT_SURFACE_CONTRACTS, applyReadOutputDimensions, isReadOutputBudgetExceeded, resolveReadOutputDimensions, resolveReadOutputEncoding, resolveReadOutputSurface, validateReadOutputOptions, } from "./read-output-contracts.js";
+export { PM_READ_OUTPUT_DIMENSIONS, PM_READ_OUTPUT_OPTION_FLAGS, PM_READ_OUTPUT_COMPOSITION_OPTION_FLAGS, PM_READ_OUTPUT_SURFACE_CONTRACTS, applyReadOutputDimensions, isReadOutputBudgetExceeded, resolveReadOutputDimensions, resolveReadOutputEncoding, resolveReadOutputSurface, validateReadOutputOptions, } from "./read-output-contracts.js";
+export { applyReadOutputSessionReferences, attachReadOutputSessionReceipt, parseReadOutputSession, readOutputSessionRemainingTokens, } from "./read-output-session.js";
 //# sourceMappingURL=core.js.map
-//# debugId=d70db3d9-b094-52fd-8f0f-47eed9f6e7f0
+//# debugId=54d31df7-e708-585d-9fb2-3c5ddfcc6138

package/dist/sdk/extension.js

@@ -4,9 +4,8 @@
  * Implements the pm extension 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]="f4f1a871-b632-5263-aec0-cb00bcdbe1b3")}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]="f4b47053-cc05-51f2-b5cb-cc6dba3365c2")}catch(e){}}();
 import fs from "node:fs/promises";
-import os from "node:os";
 import path from "node:path";
 import { activateExtensions, createSerialQueue, loadExtensions, nextExtensionReloadToken, } from "../core/extensions/index.js";
 import { describeExtensionActivation } from "../core/extensions/activation-summary.js";
@@ -643,10 +642,10 @@ const resolveInstallRuntimeActivationStatus = (extensionName, scope, runtimeInst
         (installActivationFailure ? "failed" : "unknown"));
 };
 /** Probe a temporary installed extension for runtime command registrations. */
-const probeRuntimeCommandPathsForInstall = (pmRoot, settings, refreshedInstalled, global) => {
+const probeRuntimeCommandPathsForInstall = (pmRoot, parent, settings, refreshedInstalled, global) => {
     return extensionRuntimeProbeQueue.enqueue(async () => {
         const originalPackageRoot = process.env.PM_CLI_PACKAGE_ROOT;
-        const moduleGraphSnapshotRoot = await fs.mkdtemp(path.join(os.tmpdir(), "pm-extension-module-graph-"));
+        const snapshotRoot = await fs.mkdtemp(path.join(parent, ".pm-module-graph-"));
         process.env.PM_CLI_PACKAGE_ROOT = resolvePmPackageRootFromModule(import.meta.url, ["../.."]);
         try {
             const loadResult = await loadExtensions({
@@ -656,11 +655,10 @@ const probeRuntimeCommandPathsForInstall = (pmRoot, settings, refreshedInstalled
                 noExtensions: global.noExtensions === true,
                 reload_token: nextExtensionReloadToken(),
                 cache_bust: true,
-                module_graph_snapshot_root: moduleGraphSnapshotRoot,
+                module_graph_snapshot_root: snapshotRoot,
             });
             const activationResult = await activateExtensions({
                 ...loadResult,
-                loaded: loadResult.loaded,
             });
             const runtimeFailures = [
                 ...loadResult.failed.map((failure) => ({
@@ -687,7 +685,7 @@ const probeRuntimeCommandPathsForInstall = (pmRoot, settings, refreshedInstalled
             };
         }
         finally {
-            await fs.rm(moduleGraphSnapshotRoot, { recursive: true, force: true });
+            await fs.rm(snapshotRoot, { recursive: true, force: true });
             if (originalPackageRoot === undefined) {
                 delete process.env.PM_CLI_PACKAGE_ROOT;
             }
@@ -1275,7 +1273,7 @@ const buildInstalledExtensionActivation = (ctx, extensionName, runtimeProbe, com
             registered_commands: commandSummary.command_paths,
             registered_actions: commandSummary.action_paths,
             registered_item_types: installedItemTypes,
-            module_graph_verification: "fresh_snapshot",
+            module_graph_verification: "fresh_in_topology_snapshot",
             health: healthByActivation[String(activated)],
         },
     };
@@ -1287,7 +1285,7 @@ const performExtensionInstallUnderLock = async (ctx, input) => {
     const persisted = await persistExtensionInstall(ctx, input);
     const refreshedInstalled = await listInstalledExtensions(resolvedRoots.selected_root, scope, persisted.settings, persisted.managedState);
     warnings.push(...refreshedInstalled.warnings);
-    const runtimeProbe = await probeRuntimeCommandPathsForInstall(resolvedRoots.pm_root, persisted.settings, refreshedInstalled.extensions, global);
+    const runtimeProbe = await probeRuntimeCommandPathsForInstall(resolvedRoots.pm_root, path.dirname(resolvedRoots.selected_root), persisted.settings, refreshedInstalled.extensions, global);
     warnings.push(...runtimeProbe.warnings);
     // Scaffold the folders for any item types the installed package contributes
     // so the tracker is immediately healthy — matching `pm schema add-type` and
@@ -1636,7 +1634,7 @@ const runExtensionActivateDeactivateAction = async (ctx) => {
         await writeSettings(resolvedRoots.settings_root, settings, "settings:write");
     }
     const activationFailure = action === "activate"
-        ? await probeRuntimeCommandPathsForInstall(resolvedRoots.pm_root, settings, [candidate], global).then((probe) => {
+        ? await probeRuntimeCommandPathsForInstall(resolvedRoots.pm_root, path.dirname(resolvedRoots.selected_root), settings, [candidate], global).then((probe) => {
             warnings.push(...probe.warnings);
             return findActivationFailureByName(candidate.name, probe.activation_failures, ctx.scope);
         })
@@ -2192,4 +2190,4 @@ export const _testOnly = {
     withExtensionInstallLock,
 };
 //# sourceMappingURL=extension.js.map
-//# debugId=f4f1a871-b632-5263-aec0-cb00bcdbe1b3
+//# debugId=f4b47053-cc05-51f2-b5cb-cc6dba3365c2

package/dist/sdk/generated-error-code-catalog.js

@@ -4,7 +4,7 @@
  * Generated by scripts/generate-error-code-catalog.mjs. Do not edit manually.
  */
 
-!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]="7a568064-a103-5b19-969d-6e58fc0cc5b7")}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]="93c784d2-8f0f-5bf4-875e-3d83a675c9eb")}catch(e){}}();
 import { definePmErrorCodeCatalog } from "./error-code-catalog.js";
 /** Exhaustive catalog generated from literal error guidance declarations. */
 export const PM_ERROR_CODE_CATALOG = definePmErrorCodeCatalog([
@@ -668,6 +668,26 @@ export const PM_ERROR_CODE_CATALOG = definePmErrorCodeCatalog([
         sources: ["core/diagnostics/remediation.ts"],
         emitting_commands: ["*"],
     },
+    {
+        code: "improvement_metric_contract_conflict",
+        meaning: "Improvement metric contract conflict condition.",
+        stability: "provisional",
+        exit_code: 4,
+        class: "conflict",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/improvement-ledger.ts"],
+        emitting_commands: ["*"],
+    },
+    {
+        code: "improvement_observation_conflict",
+        meaning: "Improvement observation conflict condition.",
+        stability: "provisional",
+        exit_code: 4,
+        class: "conflict",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/improvement-ledger.ts"],
+        emitting_commands: ["*"],
+    },
     {
         code: "init_existing_settings_requires_force",
         meaning: "Init existing settings requires force condition.",
@@ -853,6 +873,86 @@ export const PM_ERROR_CODE_CATALOG = definePmErrorCodeCatalog([
         sources: ["sdk/mutation-events.ts"],
         emitting_commands: ["*"],
     },
+    {
+        code: "invalid_history_analytics_limit",
+        meaning: "Invalid history analytics limit condition.",
+        stability: "provisional",
+        exit_code: 2,
+        class: "usage",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/history-analytics.ts"],
+        emitting_commands: ["*"],
+    },
+    {
+        code: "invalid_history_analytics_minimum_sample",
+        meaning: "Invalid history analytics minimum sample condition.",
+        stability: "provisional",
+        exit_code: 2,
+        class: "usage",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/history-analytics.ts"],
+        emitting_commands: ["*"],
+    },
+    {
+        code: "invalid_history_analytics_since",
+        meaning: "Invalid history analytics since condition.",
+        stability: "provisional",
+        exit_code: 2,
+        class: "usage",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/history-analytics.ts"],
+        emitting_commands: ["*"],
+    },
+    {
+        code: "invalid_improvement_ledger",
+        meaning: "Invalid improvement ledger condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/improvement-ledger-validation.ts"],
+        emitting_commands: ["*"],
+    },
+    {
+        code: "invalid_improvement_metric",
+        meaning: "Invalid improvement metric condition.",
+        stability: "provisional",
+        exit_code: 2,
+        class: "usage",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/improvement-ledger.ts"],
+        emitting_commands: ["*"],
+    },
+    {
+        code: "invalid_improvement_observation",
+        meaning: "Invalid improvement observation condition.",
+        stability: "provisional",
+        exit_code: 2,
+        class: "usage",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/improvement-ledger.ts"],
+        emitting_commands: ["*"],
+    },
+    {
+        code: "invalid_improvement_observation_limit",
+        meaning: "Invalid improvement observation limit condition.",
+        stability: "provisional",
+        exit_code: 2,
+        class: "usage",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/improvement-ledger.ts"],
+        emitting_commands: ["*"],
+    },
+    {
+        code: "invalid_improvement_observation_timestamp",
+        meaning: "Invalid improvement observation timestamp condition.",
+        stability: "provisional",
+        exit_code: 2,
+        class: "usage",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/improvement-ledger.ts"],
+        emitting_commands: ["*"],
+    },
     {
         code: "invalid_provenance_predicate",
         meaning: "Invalid provenance predicate condition.",
@@ -873,6 +973,16 @@ export const PM_ERROR_CODE_CATALOG = definePmErrorCodeCatalog([
         sources: ["sdk/pagination.ts"],
         emitting_commands: ["*"],
     },
+    {
+        code: "invalid_read_output_session",
+        meaning: "Invalid read output session condition.",
+        stability: "provisional",
+        exit_code: 2,
+        class: "usage",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/read-output-session.ts"],
+        emitting_commands: ["*"],
+    },
     {
         code: "invalid_workspace_snapshot_target",
         meaning: "Invalid workspace snapshot target condition.",
@@ -2285,4 +2395,4 @@ export const PM_ERROR_CODE_CATALOG = definePmErrorCodeCatalog([
     },
 ]);
 //# sourceMappingURL=generated-error-code-catalog.js.map
-//# debugId=7a568064-a103-5b19-969d-6e58fc0cc5b7
+//# debugId=93c784d2-8f0f-5bf4-875e-3d83a675c9eb