@unbrained/pm-cli 2026.8.6 → 2026.8.7

package/dist/sdk/read-output-session.js

@@ -0,0 +1,200 @@
+/**
+ * @module sdk/read-output-session
+ *
+ * Implements a stateless, caller-carried session ledger for cross-call output
+ * budgets and resolvable references to item facts served by earlier reads.
+ */
+
+!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]="04ad0d11-1fb7-5eb4-8ff0-d81a7090c4ff")}catch(e){}}();
+import { EXIT_CODE } from "../core/shared/constants.js";
+import { PmCliError } from "../core/shared/errors.js";
+import { mapReadOutputRows, readOutputRowCollections, } from "./read-output-rows.js";
+/** Smallest session ceiling that can carry a useful result and both receipts. */
+export const PM_READ_OUTPUT_SESSION_MIN_TOKENS = 256;
+/** Maximum caller-carried served-item identities accepted in one session state. */
+export const PM_READ_OUTPUT_SESSION_MAX_SEEN_ITEM_IDS = 10_000;
+const SESSION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/u;
+const ITEM_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u;
+const SESSION_KEYS = new Set([
+    "version",
+    "id",
+    "token_budget",
+    "spent_tokens",
+    "seen_item_ids",
+]);
+const SESSION_FIELD_VALIDATIONS = [
+    {
+        valid: (state) => state.version === 1,
+        reason: "version must equal 1.",
+    },
+    {
+        valid: (state) => typeof state.id === "string" && SESSION_ID_PATTERN.test(state.id),
+        reason: "id must be 1-64 portable identifier characters.",
+    },
+    {
+        valid: (state) => Number.isSafeInteger(state.token_budget) &&
+            state.token_budget >= PM_READ_OUTPUT_SESSION_MIN_TOKENS,
+        reason: `token_budget must be a safe integer of at least ${PM_READ_OUTPUT_SESSION_MIN_TOKENS}.`,
+    },
+    {
+        valid: (state) => Number.isSafeInteger(state.spent_tokens) &&
+            state.spent_tokens >= 0 &&
+            state.spent_tokens <= state.token_budget,
+        reason: "spent_tokens must be a non-negative safe integer no larger than token_budget.",
+    },
+    {
+        valid: (state) => Array.isArray(state.seen_item_ids) &&
+            state.seen_item_ids.length <=
+                PM_READ_OUTPUT_SESSION_MAX_SEEN_ITEM_IDS &&
+            state.seen_item_ids.every((id) => typeof id === "string" && ITEM_ID_PATTERN.test(id)),
+        reason: `seen_item_ids must contain at most ${PM_READ_OUTPUT_SESSION_MAX_SEEN_ITEM_IDS} portable item identifiers.`,
+    },
+];
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** Throw one stable usage refusal for a malformed caller-carried session. */
+function invalidSession(reason) {
+    throw new PmCliError(`--output-session ${reason}`, EXIT_CODE.USAGE, {
+        code: "invalid_read_output_session",
+        field: "outputSession",
+    });
+}
+/** Parse and strictly validate a JSON string or typed session-state object. */
+export function parseReadOutputSession(value) {
+    if (value === undefined)
+        return undefined;
+    let parsed = value;
+    if (typeof value === "string") {
+        try {
+            parsed = JSON.parse(value);
+        }
+        catch {
+            invalidSession("must be a valid JSON object.");
+        }
+    }
+    if (!isRecord(parsed))
+        invalidSession("must be a JSON object.");
+    const unknownKeys = Object.keys(parsed).filter((key) => !SESSION_KEYS.has(key));
+    if (unknownKeys.length > 0) {
+        invalidSession(`contains unknown field "${unknownKeys.sort()[0]}".`);
+    }
+    const invalidField = SESSION_FIELD_VALIDATIONS.find((validation) => !validation.valid(parsed));
+    if (invalidField !== undefined)
+        invalidSession(invalidField.reason);
+    const seenItemIds = [...new Set(parsed.seen_item_ids)].sort();
+    return {
+        version: 1,
+        id: parsed.id,
+        token_budget: parsed.token_budget,
+        spent_tokens: parsed.spent_tokens,
+        seen_item_ids: seenItemIds,
+    };
+}
+/** Resolve an item identity from built-in list rows and nested search hits. */
+function itemIdFromRow(row) {
+    if (!isRecord(row))
+        return undefined;
+    if (typeof row.id === "string")
+        return row.id;
+    if (typeof row.item_id === "string")
+        return row.item_id;
+    return isRecord(row.item) && typeof row.item.id === "string"
+        ? row.item.id
+        : undefined;
+}
+/** Summarize delivered item facts and compact references across row paths. */
+function summarizeReadOutputSessionRows(result) {
+    const deliveredIds = new Set();
+    let suppressedRepeatCount = 0;
+    for (const collection of readOutputRowCollections(result)) {
+        const rows = Array.isArray(collection.value)
+            ? collection.value
+            : Object.values(collection.value);
+        for (const row of rows) {
+            if (!isRecord(row))
+                continue;
+            if (typeof row.context_ref === "string") {
+                suppressedRepeatCount += 1;
+                continue;
+            }
+            const itemId = itemIdFromRow(row);
+            if (itemId !== undefined)
+                deliveredIds.add(itemId);
+        }
+    }
+    return { deliveredIds, suppressedRepeatCount };
+}
+/** Replace previously served item rows with compact, resolvable references. */
+export function applyReadOutputSessionReferences(result, state) {
+    const seen = new Set(state.seen_item_ids);
+    return mapReadOutputRows(result, (row) => {
+        const itemId = itemIdFromRow(row);
+        return itemId !== undefined && seen.has(itemId)
+            ? {
+                id: itemId,
+                context_ref: `session:${state.id}:${itemId}`,
+            }
+            : row;
+    });
+}
+/** Attach a fixed-point session receipt and return the exact charged tokens. */
+export function attachReadOutputSessionReceipt(result, state) {
+    const { deliveredIds, suppressedRepeatCount } = summarizeReadOutputSessionRows(result);
+    const nextSeen = [
+        ...new Set([...state.seen_item_ids, ...deliveredIds]),
+    ].sort();
+    const receipt = {
+        contract_version: 1,
+        id: state.id,
+        measurement_scope: "complete_read_envelope",
+        estimator: "ceil(utf8_bytes / 4)",
+        token_budget: state.token_budget,
+        spent_before_tokens: state.spent_tokens,
+        spent_this_call_tokens: 0,
+        charged_this_call_tokens: 0,
+        spent_total_tokens: state.spent_tokens,
+        remaining_tokens: state.token_budget - state.spent_tokens,
+        exhausted: false,
+        seen_before_count: state.seen_item_ids.length,
+        new_item_count: deliveredIds.size,
+        suppressed_repeat_count: suppressedRepeatCount,
+        reference_format: "session:<session-id>:<item-id>",
+        restore_reference_with: "pm get <item-id> --brief",
+        next_state: {
+            version: 1,
+            id: state.id,
+            token_budget: state.token_budget,
+            spent_tokens: state.spent_tokens,
+            seen_item_ids: nextSeen,
+        },
+    };
+    const withReceipt = { ...result, read_session: receipt };
+    const applyEstimate = (estimate) => {
+        receipt.spent_this_call_tokens = estimate;
+        receipt.charged_this_call_tokens = Math.min(state.token_budget - state.spent_tokens, estimate);
+        receipt.spent_total_tokens = Math.min(state.token_budget, state.spent_tokens + receipt.charged_this_call_tokens);
+        receipt.remaining_tokens = Math.max(0, state.token_budget - receipt.spent_total_tokens);
+        receipt.exhausted =
+            receipt.remaining_tokens < PM_READ_OUTPUT_SESSION_MIN_TOKENS;
+        receipt.next_state.spent_tokens = receipt.spent_total_tokens;
+    };
+    let estimate = 0;
+    let highestMeasuredEstimate = 0;
+    for (let iteration = 0; iteration < 8; iteration += 1) {
+        applyEstimate(estimate);
+        const measured = Math.ceil(Buffer.byteLength(JSON.stringify(withReceipt), "utf8") / 4);
+        if (measured === estimate)
+            return withReceipt;
+        highestMeasuredEstimate = Math.max(highestMeasuredEstimate, measured);
+        estimate = measured;
+    }
+    applyEstimate(highestMeasuredEstimate);
+    return withReceipt;
+}
+/** Return the unspent group budget available to the current invocation. */
+export function readOutputSessionRemainingTokens(state) {
+    return Math.max(0, state.token_budget - state.spent_tokens);
+}
+//# sourceMappingURL=read-output-session.js.map
+//# debugId=04ad0d11-1fb7-5eb4-8ff0-d81a7090c4ff

package/dist/sdk/runtime-input.d.ts

@@ -13,6 +13,8 @@ export declare function readRuntimeScalarStringAllowBlank(args: Record<string, u
 export declare function isRuntimeRecord(value: unknown): value is Record<string, unknown>;
 /** Parse an integer-valued MCP option while retaining a caller-specific label. */
 export declare function parseRuntimeInteger(value: unknown, label: string): number | undefined;
+/** Resolve a numeric-or-string limit from top-level and nested action inputs. */
+export declare function resolveRuntimeLimit(args: Record<string, unknown>, options: Record<string, unknown>): number | string | undefined;
 /** Fixed SDK-runtime global options derived from one untyped action payload. */
 export declare function actionGlobalOptions(args: Record<string, unknown>): GlobalOptions;
 /** Reconcile MCP array/scalar option spellings with CLI flag expectations. */

package/dist/sdk/runtime-input.js

@@ -5,7 +5,7 @@
  * primitives are shared by native action dispatchers and MCP-specific adapters.
  */
 
-!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]="be34ba04-504d-5c5a-90a7-22abb1142211")}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]="bcda2578-3b01-5e64-9d53-cd32c0f927b8")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { asRecordClone } from "../core/shared/primitives.js";
@@ -59,6 +59,16 @@ export function parseRuntimeInteger(value, label) {
     }
     return undefined;
 }
+/** Resolve a numeric-or-string limit from top-level and nested action inputs. */
+export function resolveRuntimeLimit(args, options) {
+    if (typeof args.limit === "number" && Number.isFinite(args.limit)) {
+        return args.limit;
+    }
+    if (typeof options.limit === "number" && Number.isFinite(options.limit)) {
+        return options.limit;
+    }
+    return (readRuntimeString(args, "limit") ?? readRuntimeString(options, "limit"));
+}
 /** Fixed SDK-runtime global options derived from one untyped action payload. */
 export function actionGlobalOptions(args) {
     const outputFormat = readRuntimeString(args, "outputFormat");
@@ -72,6 +82,7 @@ export function actionGlobalOptions(args) {
         outputInclude: readRuntimeString(args, "outputInclude"),
         outputLimit: readRuntimeScalarString(args, "outputLimit"),
         outputBudget: readRuntimeScalarString(args, "outputBudget"),
+        outputSession: readRuntimeString(args, "outputSession"),
         outputFormat: outputFormat === "json" || outputFormat === "toon"
             ? outputFormat
             : undefined,
@@ -155,6 +166,7 @@ const UNIVERSAL_READ_OUTPUT_OPTION_KEYS = [
     "outputLimit",
     "outputBudget",
     "outputFormat",
+    "outputSession",
 ];
 /** Reconcile MCP array/scalar option spellings with CLI flag expectations. */
 export function normalizeMcpOptionsArrays(options, action) {
@@ -489,4 +501,4 @@ export function updateManyOptionsFromFlat(options) {
     };
 }
 //# sourceMappingURL=runtime-input.js.map
-//# debugId=be34ba04-504d-5c5a-90a7-22abb1142211
+//# debugId=bcda2578-3b01-5e64-9d53-cd32c0f927b8

package/dist/sdk/runtime-primitives.d.ts

@@ -16,7 +16,7 @@ export { pathExists, readFileIfExists, removeFileIfExists, writeFileAtomic, } fr
 export { type HistoryDiffValueEntry, computeHistoryDiff, patchPathToChangedField, } from "../core/history/history-diff.js";
 export { enforceHistoryStreamPolicyForItem, enforceHistoryStreamPolicyForItems, } from "../core/history/history-stream-policy.js";
 export { appendHistoryEntry, createHistoryEntry, hashDocument, hashEmptyDocument, } from "../core/history/history.js";
-export { appendWorkspaceAuditEvent, appendWorkspaceHistoryChange, getWorkspaceHistoryPath, WORKSPACE_HISTORY_ID, writeWorkspaceJsonWithHistory, type WorkspaceAuditEventOptions, type WorkspaceHistoryChange, type WorkspaceJsonWriteOptions, } from "../core/history/workspace-history.js";
+export { appendWorkspaceAuditEvent, appendWorkspaceHistoryChange, getWorkspaceHistoryPath, mutateWorkspaceJsonWithHistory, WORKSPACE_HISTORY_ID, writeWorkspaceJsonWithHistory, type WorkspaceAuditEventOptions, type WorkspaceHistoryChange, type WorkspaceJsonMutation, type WorkspaceJsonMutationOptions, type WorkspaceJsonWriteOptions, } from "../core/history/workspace-history.js";
 export { normalizeReplayPatchOps, replayToCanonicalItemDocument, replayToItemDocument, toReplayDocument, verifyHistoryChain, } from "../core/history/replay.js";
 export { resolveBodyFileContent } from "../core/io/body-file.js";
 export { generateItemId, normalizeItemId, normalizeRawItemId, } from "../core/item/id.js";

package/dist/sdk/runtime-primitives.js

@@ -7,7 +7,7 @@
  * prefer the typed operations exported by the main SDK barrel.
  */
 
-!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]="89efaf82-c9cb-560d-b1ca-5a676b4b979c")}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]="febc7f96-1757-5c07-8d99-ed5fce742afa")}catch(e){}}();
 export { createCheckpointId, loadMutationCheckpoint, restoreCheckpointItems, writeMutationCheckpoint, } from "../core/checkpoint/mutation-checkpoint.js";
 export { flattenFlagListValue, resolveFlagValueKind, } from "../core/extensions/flag-value-types.js";
 export { activateExtensions, clearActiveExtensionHooks, consumeAfterCommandAffectedItems, createCoreCommandHookContext, createEmptyExtensionRegistrationRegistry, discoverExtensions, getActiveCommandResult, getActiveExtensionRegistrations, loadExtensions, projectAfterCommandItemSnapshot, recordAfterCommandAffectedItem, resetActiveExtensionRuntimeState, runActiveCommandHandler, runActiveBeforeMutationHooks, runActiveOnIndexHooks, runActiveOnReadHooks, runActiveOnWriteHooks, runActiveParserOverride, runActivePreflightOverride, runActiveServiceOverride, runAfterCommandHooks, runBeforeCommandHooks, setActiveCommandContext, setActiveCommandResult, setActiveExtensionCommands, setActiveExtensionHooks, setActiveExtensionParsers, setActiveExtensionPreflight, setActiveExtensionRegistrations, setActiveExtensionRenderers, setActiveExtensionServices, } from "../core/extensions/index.js";
@@ -18,7 +18,7 @@ export { pathExists, readFileIfExists, removeFileIfExists, writeFileAtomic, } fr
 export { computeHistoryDiff, patchPathToChangedField, } from "../core/history/history-diff.js";
 export { enforceHistoryStreamPolicyForItem, enforceHistoryStreamPolicyForItems, } from "../core/history/history-stream-policy.js";
 export { appendHistoryEntry, createHistoryEntry, hashDocument, hashEmptyDocument, } from "../core/history/history.js";
-export { appendWorkspaceAuditEvent, appendWorkspaceHistoryChange, getWorkspaceHistoryPath, WORKSPACE_HISTORY_ID, writeWorkspaceJsonWithHistory, } from "../core/history/workspace-history.js";
+export { appendWorkspaceAuditEvent, appendWorkspaceHistoryChange, getWorkspaceHistoryPath, mutateWorkspaceJsonWithHistory, WORKSPACE_HISTORY_ID, writeWorkspaceJsonWithHistory, } from "../core/history/workspace-history.js";
 export { normalizeReplayPatchOps, replayToCanonicalItemDocument, replayToItemDocument, toReplayDocument, verifyHistoryChain, } from "../core/history/replay.js";
 export { resolveBodyFileContent } from "../core/io/body-file.js";
 export { generateItemId, normalizeItemId, normalizeRawItemId, } from "../core/item/id.js";
@@ -79,4 +79,4 @@ export { maybeRunFirstUseTelemetryPrompt } from "../core/telemetry/consent.js";
 export { deriveTelemetryCommandResolution, } from "../core/telemetry/observability.js";
 export { emitTelemetryErrorEvent, finishTelemetryCommand, startTelemetryCommand, } from "../core/telemetry/runtime.js";
 //# sourceMappingURL=runtime-primitives.js.map
-//# debugId=89efaf82-c9cb-560d-b1ca-5a676b4b979c
+//# debugId=febc7f96-1757-5c07-8d99-ed5fce742afa

package/dist/sdk/runtime-stats-options.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @module sdk/runtime-stats-options
+ *
+ * Maps the flat SDK/MCP action transport into the typed stats command options
+ * shared by the CLI and direct SDK surfaces.
+ */
+import type { StatsCommandOptions } from "./stats.js";
+/** Convert a flat runtime option bag into the canonical typed stats payload. */
+export declare function statsCommandOptionsFromRuntime(options: Record<string, unknown>): StatsCommandOptions;

package/dist/sdk/runtime-stats-options.js

@@ -0,0 +1,38 @@
+
+!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]="dbabff08-1bb7-539b-b1c1-c10584aa0a67")}catch(e){}}();
+import { readRuntimeString, readRuntimeStringArray } from "./runtime-input.js";
+/** Convert a flat runtime option bag into the canonical typed stats payload. */
+export function statsCommandOptionsFromRuntime(options) {
+    return {
+        storage: options.storage === true,
+        metadataCoverage: options.metadataCoverage === true,
+        fieldUtilization: options.fieldUtilization === true,
+        byAssignee: options.byAssignee === true,
+        byTag: options.byTag === true,
+        byPriority: options.byPriority === true,
+        tagPrefix: typeof options.tagPrefix === "string" ? options.tagPrefix : undefined,
+        measurements: options.measurements === true,
+        metric: readRuntimeString(options, "metric"),
+        measurementLimit: typeof options.measurementLimit === "number"
+            ? options.measurementLimit
+            : undefined,
+        observe: readRuntimeStringArray(options.observe),
+        direction: typeof options.improvementDirection === "string"
+            ? options.improvementDirection
+            : undefined,
+        measurementSource: readRuntimeString(options, "measurementSource"),
+        measurementItem: readRuntimeString(options, "measurementItem"),
+        measurementRevision: readRuntimeString(options, "measurementRevision"),
+        author: readRuntimeString(options, "author"),
+        message: readRuntimeString(options, "message"),
+        provenanceCoverage: options.provenanceCoverage === true,
+        fleetAttribution: options.fleetAttribution === true,
+        since: readRuntimeString(options, "since"),
+        eventLimit: typeof options.eventLimit === "number" ? options.eventLimit : undefined,
+        minimumSample: typeof options.minimumSample === "number"
+            ? options.minimumSample
+            : undefined,
+    };
+}
+//# sourceMappingURL=runtime-stats-options.js.map
+//# debugId=dbabff08-1bb7-539b-b1c1-c10584aa0a67

package/dist/sdk/runtime.d.ts

@@ -10,6 +10,7 @@ import { EXIT_CODE } from "../core/shared/constants.js";
 export type { WorkspaceExtensionCommandContract, WorkspaceFieldContract, } from "./workspace-contracts.js";
 import { type PmReadOutputOptions, type PmReadOutputResultFor } from "./read-output-contracts.js";
 export type { PmReadOutputBudgetExceeded, PmReadOutputOptions, PmReadOutputResult, PmReadOutputResultFor, PmReadOutputSurfaceContract, } from "./read-output-contracts.js";
+export type { PmReadOutputSessionReceipt, PmReadOutputSessionState } from "./read-output-session.js";
 export type { PmContextIntentContract } from "./context-intent-contracts.js";
 export type { PmErrorCodeContract } from "./error-code-catalog.js";
 export { clearWorkspaceContractsCache } from "./workspace-contracts-cache.js";

package/dist/sdk/runtime.js

@@ -4,7 +4,7 @@
  * Defines public SDK APIs and package-author helpers for Runtime.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="57628397-0652-5a7b-8521-2f0fb2abb787")}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]="42339e0d-ca3c-505f-8b98-acec81158b6e")}catch(e){}}();
 export { PM_GITIGNORE_END, PM_GITIGNORE_START, ensurePmGitignore, getPmGitignoreBlock, } from "./workspace.js";
 export { SEARCH_EXTENSION_FLAG_DEFINITIONS } from "./extension-contracts.js";
 import { AsyncLocalStorage } from "node:async_hooks";
@@ -64,7 +64,7 @@ import { acknowledgeUnknownAuthorHistoryEvents, } from "./author-attribution.js"
 import { runProfileApply, runProfileLint, runProfileList, runProfileShow, } from "./profile.js";
 import { runHistoryRedact, } from "./history-redact.js";
 import { runMcpHistoryCompactAction, runMcpHistoryRepairAction, } from "./history-mcp.js";
-import { actionGlobalOptions as globalOptions, closeManyOptionsFromFlat, extensionOptionsFromArgs, graphOptionsFromFlat, mutationListOptions, normalizeActionName, normalizeCommandPath, normalizeMcpOptionsArrays, normalizeMcpUpdateOptions, optionsWithAuthor, parseRuntimeInteger as parseMcpInteger, readRuntimeScalarString as readScalarString, readRuntimeScalarStringAllowBlank as readScalarStringAllowBlank, readRuntimeString as readString, readRuntimeStringArray as readStringArray, updateManyOptionsFromFlat, withAddNoteOption, withFilesDiscoveryOptions, withMutationCompaction, } from "./runtime-input.js";
+import { actionGlobalOptions as globalOptions, closeManyOptionsFromFlat, extensionOptionsFromArgs, graphOptionsFromFlat, mutationListOptions, normalizeActionName, normalizeCommandPath, normalizeMcpOptionsArrays, normalizeMcpUpdateOptions, optionsWithAuthor, parseRuntimeInteger as parseMcpInteger, readRuntimeScalarString as readScalarString, readRuntimeScalarStringAllowBlank as readScalarStringAllowBlank, readRuntimeString as readString, readRuntimeStringArray as readStringArray, resolveRuntimeLimit, updateManyOptionsFromFlat, withAddNoteOption, withFilesDiscoveryOptions, withMutationCompaction, } from "./runtime-input.js";
 import { runDeps } from "./dependencies.js";
 import { runDocs } from "./docs.js";
 import { runGraph, } from "./graph/run.js";
@@ -73,6 +73,7 @@ import { runContracts, } from "./cli-contracts/runtime-contracts.js";
 import { runList } from "./query/list.js";
 import { runSearch, } from "./query/search.js";
 import { runStats, } from "./stats.js";
+import { statsCommandOptionsFromRuntime } from "./runtime-stats-options.js";
 import { runDuplicates, } from "./duplicates.js";
 import { runTelemetry } from "./telemetry.js";
 import { runTest } from "./test/execution.js";
@@ -1424,18 +1425,9 @@ function runMcpTelemetryAction(ctx) {
     return runTelemetry({
         subcommand: readString(ctx.args, "subcommand") ??
             readString(ctx.options, "subcommand"),
-        limit: resolveMcpTelemetryLimit(ctx.args, ctx.options),
+        limit: resolveRuntimeLimit(ctx.args, ctx.options),
     }, ctx.global);
 }
-function resolveMcpTelemetryLimit(args, options) {
-    if (typeof args.limit === "number" && Number.isFinite(args.limit)) {
-        return args.limit;
-    }
-    if (typeof options.limit === "number" && Number.isFinite(options.limit)) {
-        return options.limit;
-    }
-    return readString(args, "limit") ?? readString(options, "limit");
-}
 function runMcpHealthAction(ctx) {
     const healthOptions = { ...ctx.options };
     if (healthOptions.brief === undefined &&
@@ -1670,19 +1662,6 @@ function runMcpProfileAction(ctx) {
     }
     return handler();
 }
-function runMcpStatsAction(ctx) {
-    return runStats(ctx.global, {
-        storage: ctx.options.storage === true,
-        metadataCoverage: ctx.options.metadataCoverage === true,
-        fieldUtilization: ctx.options.fieldUtilization === true,
-        byAssignee: ctx.options.byAssignee === true,
-        byTag: ctx.options.byTag === true,
-        byPriority: ctx.options.byPriority === true,
-        tagPrefix: typeof ctx.options.tagPrefix === "string"
-            ? ctx.options.tagPrefix
-            : undefined,
-    });
-}
 async function runMcpAppendAction(ctx) {
     const { changedFields, idOnly, runnerOptions } = withMutationCompaction(ctx.args, ctx.options);
     return projectMutationResult(await runAppend(requireMcpItemId(ctx, runnerOptions), runnerOptions, ctx.global), {
@@ -1875,7 +1854,7 @@ const SDK_ACTION_HANDLERS = {
     plan: runMcpPlanAction,
     schema: runMcpSchemaAction,
     profile: runMcpProfileAction,
-    stats: runMcpStatsAction,
+    stats: (ctx) => runStats(ctx.global, statsCommandOptionsFromRuntime(ctx.options)),
     append: runMcpAppendAction,
     "update-many": runMcpUpdateManyAction,
     "close-many": runMcpCloseManyAction,
@@ -1962,4 +1941,4 @@ async function loadWorkspaceExtensionRegistrations(pmRoot, settings, cwd) {
     }
 }
 //# sourceMappingURL=runtime.js.map
-//# debugId=57628397-0652-5a7b-8521-2f0fb2abb787
+//# debugId=42339e0d-ca3c-505f-8b98-acec81158b6e

package/dist/sdk/stats.d.ts

@@ -3,6 +3,8 @@ import { type GroupedBreakdown, type MetadataCoverageReport } from "../core/gove
 import { type HistoryStorageStats } from "../core/history/history-storage-stats.js";
 import type { GlobalOptions } from "../core/shared/command-types.js";
 import type { ItemStatus, ItemType } from "../types/index.js";
+import { type ImprovementDirection, type ImprovementLedgerResult, type RecordImprovementObservationResult } from "./improvement-ledger.js";
+import { type FleetAttributionAnalytics, type ProvenanceCoverageAnalytics } from "./history-analytics.js";
 /** Documents the stats command options payload exchanged by command, SDK, and package integrations. */
 export interface StatsCommandOptions {
     /** Include aggregate per-stream history storage metrics (sizes, depth, oldest/newest). */
@@ -19,6 +21,36 @@ export interface StatsCommandOptions {
     tagPrefix?: string;
     /** Include a content-field utilization breakdown (notes/learnings/files/docs/tests/comments/deps/body usage rates). */
     fieldUtilization?: boolean;
+    /** Include the audited improvement observation ledger and derived trends. */
+    measurements?: boolean;
+    /** Exact improvement metric filter used with --measurements. */
+    metric?: string;
+    /** Maximum newest improvement observations returned. */
+    measurementLimit?: number;
+    /** Repeatable name=value[,unit=...][,threshold=...] observations to append. */
+    observe?: string[];
+    /** Improvement direction applied to newly recorded observations. */
+    direction?: ImprovementDirection;
+    /** Producing gate or instrument associated with new observations. */
+    measurementSource?: string;
+    /** Tracked owner associated with new observations. */
+    measurementItem?: string;
+    /** Explicit source revision for new observations. */
+    measurementRevision?: string;
+    /** Intentional mutation author override. */
+    author?: string;
+    /** Human-readable observation audit rationale. */
+    message?: string;
+    /** Include live declared-versus-observed provenance coverage. */
+    provenanceCoverage?: boolean;
+    /** Include immutable-history fleet outcome attribution. */
+    fleetAttribution?: boolean;
+    /** Inclusive history analytics lower bound or negative duration. */
+    since?: string;
+    /** Maximum immutable events consumed by each analytics projection. */
+    eventLimit?: number;
+    /** Minimum close or explicit-value denominator required for rates. */
+    minimumSample?: number;
 }
 /** Documents the stats result payload exchanged by command, SDK, and package integrations. */
 export interface StatsResult {
@@ -44,6 +76,14 @@ export interface StatsResult {
     storage?: HistoryStorageStats;
     /** Present only with --field-utilization: content-field utilization rates across all items. */
     field_utilization?: ContentFieldUtilizationReport;
+    /** Audited improvement observations and baseline-to-latest trends. */
+    improvement_ledger?: ImprovementLedgerResult;
+    /** Receipts for observations appended by this invocation. */
+    recorded_observations?: RecordImprovementObservationResult[];
+    /** Live provenance coverage over a bounded immutable-history window. */
+    provenance_coverage?: ProvenanceCoverageAnalytics;
+    /** Bounded fleet attribution derived from immutable history. */
+    fleet_attribution?: FleetAttributionAnalytics;
     /** ISO 8601 timestamp recording when generated occurred. */
     generated_at: string;
 }