@unbrained/pm-cli 2026.8.6 → 2026.8.7

package/dist/sdk/improvement-ledger.js

@@ -0,0 +1,261 @@
+/**
+ * @module sdk/improvement-ledger
+ *
+ * Persists append-only quantitative observations in an audited workspace
+ * singleton and exposes bounded trend reads for self-improvement loops.
+ */
+
+!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]="aaa927b3-4bc4-561f-aff1-85dc95c12ea1")}catch(e){}}();
+import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import path from "node:path";
+import { promisify } from "node:util";
+import { pathExists, readFileIfExists } from "../core/fs/fs-utils.js";
+import { mutateWorkspaceJsonWithHistory } from "../core/history/workspace-history.js";
+import { EXIT_CODE } from "../core/shared/constants.js";
+import { resolveAuthor } from "../core/shared/author.js";
+import { PmCliError } from "../core/shared/errors.js";
+import { stableStringify } from "../core/shared/serialization.js";
+import { nowIso } from "../core/shared/time.js";
+import { getSettingsPath, resolvePmRoot, resolveWorkspaceRoot, } from "../core/store/paths.js";
+import { readSettings } from "../core/store/settings.js";
+import { parseImprovementLedgerDocument as parseLedger } from "./improvement-ledger-validation.js";
+const execFileAsync = promisify(execFile);
+const DEFAULT_OBSERVATION_LIMIT = 50;
+const MAX_OBSERVATION_LIMIT = 1_000;
+const METRIC_NAME_PATTERN = /^[a-z0-9](?:[a-z0-9._/-]{0,126}[a-z0-9])?$/u;
+function normalizeMetricName(value) {
+    const metric = value.trim().toLowerCase();
+    if (!METRIC_NAME_PATTERN.test(metric)) {
+        throw new PmCliError(`Invalid metric name "${value}"; use 1-128 lowercase letters, digits, dots, slashes, underscores, or hyphens.`, EXIT_CODE.USAGE, { code: "invalid_improvement_metric" });
+    }
+    return metric;
+}
+function normalizeDirection(value) {
+    const direction = value ?? "lower";
+    if (!["higher", "lower", "target"].includes(direction)) {
+        throw new PmCliError("Improvement direction must be higher, lower, or target.", EXIT_CODE.USAGE, { code: "invalid_improvement_observation" });
+    }
+    return direction;
+}
+function normalizeOptionalText(value, field) {
+    const normalized = value?.trim();
+    if (!normalized)
+        return undefined;
+    if (normalized.length > 256) {
+        throw new PmCliError(`${field} must not exceed 256 characters.`, EXIT_CODE.USAGE, { code: "invalid_improvement_observation" });
+    }
+    return normalized;
+}
+function parseObservationLimit(value) {
+    const limit = value ?? DEFAULT_OBSERVATION_LIMIT;
+    if (!Number.isSafeInteger(limit) ||
+        limit < 0 ||
+        limit > MAX_OBSERVATION_LIMIT) {
+        throw new PmCliError(`Improvement observation limit must be an integer from 0 to ${MAX_OBSERVATION_LIMIT}.`, EXIT_CODE.USAGE, { code: "invalid_improvement_observation_limit" });
+    }
+    return limit;
+}
+function parseIsoTimestamp(value, field) {
+    const milliseconds = Date.parse(value);
+    if (!Number.isFinite(milliseconds)) {
+        throw new PmCliError(`${field} must be an ISO timestamp.`, EXIT_CODE.USAGE, {
+            code: "invalid_improvement_observation_timestamp",
+        });
+    }
+    return new Date(milliseconds).toISOString();
+}
+async function buildImprovementObservation(pmRoot, settings, options) {
+    if (!Number.isFinite(options.value)) {
+        throw new PmCliError("Improvement observation value must be finite.", EXIT_CODE.USAGE, { code: "invalid_improvement_observation" });
+    }
+    const metric = normalizeMetricName(options.metric);
+    const direction = normalizeDirection(options.direction);
+    if ((options.threshold !== undefined && !Number.isFinite(options.threshold)) ||
+        (direction === "target" && options.threshold === undefined)) {
+        throw new PmCliError("Target-directed observations require a finite threshold.", EXIT_CODE.USAGE, { code: "invalid_improvement_observation" });
+    }
+    const revision = await resolveObservationRevision(pmRoot, options.revision);
+    const source = normalizeOptionalText(options.source, "source");
+    const itemId = normalizeOptionalText(options.itemId, "itemId");
+    const unit = normalizeOptionalText(options.unit, "unit");
+    const idempotencyKey = normalizeOptionalText(options.idempotencyKey, "idempotencyKey") ??
+        (revision.revision_source === "unversioned"
+            ? undefined
+            : [
+                revision.revision,
+                metric,
+                source ?? "manual",
+                itemId ?? "workspace",
+            ].join(":"));
+    const observationWithoutId = {
+        metric,
+        value: options.value,
+        direction,
+        ...(unit === undefined ? {} : { unit }),
+        ...(options.threshold === undefined
+            ? {}
+            : { threshold: options.threshold }),
+        observed_at: parseIsoTimestamp(options.observedAt ?? nowIso(), "observedAt"),
+        ...revision,
+        author: resolveAuthor(options.author, settings.author_default),
+        ...(itemId === undefined ? {} : { item_id: itemId }),
+        ...(source === undefined ? {} : { source }),
+        ...(idempotencyKey === undefined
+            ? {}
+            : { idempotency_key: idempotencyKey }),
+    };
+    return {
+        id: createHash("sha256")
+            .update(stableStringify(observationWithoutId))
+            .digest("hex")
+            .slice(0, 24),
+        ...observationWithoutId,
+    };
+}
+function ensureObservationCanAppend(ledger, observation) {
+    const existing = observation.idempotency_key
+        ? ledger.observations.find((row) => row.idempotency_key === observation.idempotency_key)
+        : ledger.observations.find((row) => row.id === observation.id);
+    if (existing) {
+        if (existing.metric !== observation.metric ||
+            existing.value !== observation.value ||
+            existing.direction !== observation.direction ||
+            existing.threshold !== observation.threshold ||
+            existing.unit !== observation.unit) {
+            throw new PmCliError(`Improvement observation retry key already records a different value for ${observation.metric}.`, EXIT_CODE.CONFLICT, { code: "improvement_observation_conflict" });
+        }
+        return existing;
+    }
+    const priorMetric = ledger.observations.find((row) => row.metric === observation.metric);
+    if (priorMetric &&
+        (priorMetric.direction !== observation.direction ||
+            priorMetric.unit !== observation.unit ||
+            (observation.direction === "target" &&
+                priorMetric.threshold !== observation.threshold))) {
+        throw new PmCliError(`Metric ${observation.metric} is already declared with direction ${priorMetric.direction} and unit ${priorMetric.unit ?? "<none>"}.`, EXIT_CODE.CONFLICT, { code: "improvement_metric_contract_conflict" });
+    }
+    return undefined;
+}
+async function resolveObservationRevision(pmRoot, explicit) {
+    const callerRevision = normalizeOptionalText(explicit, "revision");
+    if (callerRevision) {
+        return { revision: callerRevision, revision_source: "caller" };
+    }
+    try {
+        const result = await execFileAsync("git", ["rev-parse", "--verify", "HEAD^{commit}"], {
+            cwd: resolveWorkspaceRoot(pmRoot),
+            encoding: "utf8",
+            timeout: 5_000,
+        });
+        const revision = result.stdout.trim();
+        return { revision, revision_source: "git" };
+    }
+    catch {
+        // Git is optional for root-layout and embedded SDK workspaces.
+    }
+    return { revision: "unversioned", revision_source: "unversioned" };
+}
+function trendForMetric(observations) {
+    const baseline = observations[0];
+    const latest = observations[observations.length - 1];
+    const delta = latest.value - baseline.value;
+    const improved = latest.direction === "higher"
+        ? delta > 0
+        : latest.direction === "lower"
+            ? delta < 0
+            : Math.abs(latest.value - latest.threshold) <
+                Math.abs(baseline.value - baseline.threshold);
+    return {
+        metric: latest.metric,
+        direction: latest.direction,
+        baseline,
+        latest,
+        delta,
+        improved,
+        sample_count: observations.length,
+    };
+}
+/** Record one audited observation, returning an idempotent receipt on retry. */
+export async function recordImprovementObservation(options, global = {}) {
+    const pmRoot = resolvePmRoot(process.cwd(), global.path);
+    if (!(await pathExists(getSettingsPath(pmRoot)))) {
+        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
+    }
+    const settings = await readSettings(pmRoot);
+    const observation = await buildImprovementObservation(pmRoot, settings, options);
+    const filePath = path.join(pmRoot, "improvement-ledger.json");
+    const mutation = await mutateWorkspaceJsonWithHistory({
+        pmRoot,
+        filePath,
+        op: "improvement_observe",
+        author: observation.author,
+        lockTtlSeconds: settings.locks.ttl_seconds,
+        lockWaitMs: settings.locks.wait_ms,
+        message: options.message ??
+            `Record ${observation.metric}=${String(options.value)} improvement observation`,
+        mutate: (beforeRaw) => {
+            const ledger = parseLedger(beforeRaw);
+            const existing = ensureObservationCanAppend(ledger, observation);
+            if (existing) {
+                return { raw: beforeRaw, result: existing };
+            }
+            ledger.observations.push(observation);
+            ledger.observations.sort((left, right) => left.observed_at.localeCompare(right.observed_at) ||
+                left.metric.localeCompare(right.metric) ||
+                left.id.localeCompare(right.id));
+            return {
+                raw: `${stableStringify(ledger)}\n`,
+                result: observation,
+            };
+        },
+    });
+    return {
+        changed: mutation.changed,
+        observation: mutation.result,
+        ledger_path: "improvement-ledger.json",
+    };
+}
+/** Read a bounded newest-first observation page and derive complete trends. */
+export async function readImprovementLedger(options = {}) {
+    const pmRoot = resolvePmRoot(options.cwd ?? process.cwd(), options.pmRoot);
+    if (!(await pathExists(getSettingsPath(pmRoot)))) {
+        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
+    }
+    const metric = options.metric === undefined
+        ? undefined
+        : normalizeMetricName(options.metric);
+    const since = options.since === undefined
+        ? undefined
+        : parseIsoTimestamp(options.since, "since");
+    const limit = parseObservationLimit(options.limit);
+    const ledger = parseLedger(await readFileIfExists(path.join(pmRoot, "improvement-ledger.json")));
+    const matching = ledger.observations.filter((row) => (metric === undefined || row.metric === metric) &&
+        (options.itemId === undefined || row.item_id === options.itemId) &&
+        (since === undefined || row.observed_at >= since));
+    const byMetric = new Map();
+    for (const observation of matching) {
+        const rows = byMetric.get(observation.metric) ?? [];
+        rows.push(observation);
+        byMetric.set(observation.metric, rows);
+    }
+    return {
+        observations: [...matching].reverse().slice(0, limit),
+        total: matching.length,
+        truncated: matching.length > limit,
+        trends: [...byMetric]
+            .map(([, observations]) => trendForMetric(observations))
+            .sort((left, right) => left.metric.localeCompare(right.metric)),
+        source: "audited_workspace_singleton",
+    };
+}
+/** Pure helpers exposed for storage and trend contract tests. */
+export const _testOnlyImprovementLedger = {
+    normalizeMetricName,
+    normalizeDirection,
+    parseLedger,
+    parseObservationLimit,
+    trendForMetric,
+};
+//# sourceMappingURL=improvement-ledger.js.map
+//# debugId=aaa927b3-4bc4-561f-aff1-85dc95c12ea1

package/dist/sdk/index.d.ts

@@ -20,7 +20,7 @@ export { quoteCommandArg, quoteWindowsCommandArg, renderPmCommand, } from "./com
 export { runGc, type GcCheckpointsSummary, type GcLocksSummary, } from "./governance/gc.js";
 export { _testOnlyHealthCommand, runHealth, type HealthCheck, } from "./governance/health.js";
 export { _testOnlyValidateCommand, projectValidateCounts, runValidate, type ValidateCheck, type ValidateCountsFixesSummary, type ValidateCountsResult, type ValidateFixesSummary, type ValidateMutationServices, } from "./governance/validate.js";
-export { runExtension, type ExtensionCommandAction, } from "./extension.js";
+export { runExtension, type ExtensionCommandAction } from "./extension.js";
 export { resolveExtensionInstallSourceIdentity, type ExtensionInstallSourceCandidate, type ExtensionInstallSourceResolution, type ExtensionInstallSourceSelection, type ResolvedExtensionInstallSource, } from "./extension/source-resolution.js";
 export { applyStoredExtensionMigrationState, readExtensionMigrationState, resolveExtensionMigrationStatePath, runExtensionMigrateAction, runExtensionMigrations, type ExtensionMigrationActionContext, type ExtensionMigrationOutcomeStatus, type ExtensionMigrationReceipt, type ExtensionMigrationRunResult, type ExtensionMigrationState, type ExtensionMigrationStateEntry, type RunExtensionMigrationsOptions, } from "./extension/migrations.js";
 export { findInstalledNpmPackageCandidate, type GithubInstallSource, type InstalledNpmPackageCandidate, type InstallSource, type LocalInstallSource, type NpmInstallSource, type ResolvedInstallSource, } from "./extension/install-sources.js";
@@ -61,6 +61,8 @@ export * from "./lifecycle-completion.js";
 export * from "./lifecycle-policy.js";
 export * from "./output-projection.js";
 export * from "./read-output-contracts.js";
+export * from "./read-output-rows.js";
+export * from "./read-output-session.js";
 export * from "./output-token-accounting.js";
 export * from "./context-packing.js";
 export * from "./context-usage.js";
@@ -70,7 +72,7 @@ export * from "./history-compact.js";
 export * from "./history-read.js";
 export * from "./history-provenance.js";
 export * from "./mutation-events.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 * from "./history-redact.js";
 export { _testOnly } from "./history-redact.js";
 export * from "./history-repair.js";
@@ -125,6 +127,8 @@ export { BASELINE_ITEM_FORMAT_VERSION, BUILTIN_ITEM_TYPE_VALUES, CONFIDENCE_TEXT
 export { extensionMigrate, packageMigrate } from "./package-migrations.js";
 export { CONTEXT_OUTPUT_VALUES, NEXT_OUTPUT_VALUES, PM_GITIGNORE_END, PM_GITIGNORE_START, analyzeSdkActionCoverage, ensurePmGitignore, getPmGitignoreBlock, closeItem, runAggregate, runClose, runCopy, runContext, runDelete, runFocus, runGet, runNext, runRestore, runUpdate, type CloseCommandOptions, type CopyOptions, type DeleteCommandOptions, type EnsurePmGitignoreResult, type HierarchyChild, type HierarchyNode, type HotFile, type FocusOptions, type ImportPriorityValue, type ProgressEntry, type RecentContextItem, type RestoreCommandOptions, type SdkActionCoverageRow, type StaleEntry, type TestHealthSummary, type UpdateCommandOptions, type WorkloadEntry, } from "./runtime.js";
 export { runStats } from "./stats.js";
+export { readImprovementLedger, recordImprovementObservation, type ImprovementDirection, type ImprovementLedgerDocument, type ImprovementLedgerResult, type ImprovementObservation, type ImprovementTrend, type ReadImprovementLedgerOptions, type RecordImprovementObservationOptions, type RecordImprovementObservationResult, } from "./improvement-ledger.js";
+export { evaluateProvenanceCoverage, projectFleetAttributionAnalytics, projectProvenanceCoverageAnalytics, readHistoryAnalyticsWindow, runFleetAttributionAnalytics, runProvenanceCoverageAnalytics, type FleetAttributionAnalytics, type FleetAttributionDimension, type FleetAttributionRow, type HistoryAnalyticsWindowOptions, type HistoryAnalyticsWindowReceipt, type HistoryAnalyticsEvent, type HistoryAnalyticsWindow, type ProvenanceCoverageAnalytics, } from "./history-analytics.js";
 export { DEFAULT_EVAL_QUERIES_RELATIVE_PATH, EVAL_QUERY_SET_CONTRACT, EVAL_QUERY_SET_EXAMPLE, EVAL_QUERY_SET_SCHEMA_ID, parseEvalQuerySet, runEval, type EvalOptions, type EvalQueryReport, type EvalResult, } from "./eval.js";
 export { runTelemetry, TELEMETRY_SUBCOMMANDS, type TelemetryCommandOptions, type TelemetryFlushResult, type TelemetryStatusSummary, type TelemetrySubcommand, } from "./telemetry.js";
 export { classifyLinkedTestFailure, countFailureCategories, extractReferencedPmItemIdsFromCommand, resolveLinkedTestFailureExitCode, runLinkedTests, runTest, summarizeContextPreflight, type LinkedTestFailureCategory, type TestCommandOptions, type TestResult, type TestRunResult, } from "./test/execution.js";

package/dist/sdk/index.js

@@ -4,7 +4,7 @@
  * Defines public SDK APIs and package-author helpers for Index.
  */
 
-!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]="4e336574-f00e-5296-a55f-7f27a264188c")}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]="346cbfc0-a42a-5ae6-b95a-af3bd63fc6d1")}catch(e){}}();
 export { PM_COMMAND_VISIBILITY_CONTRACTS, PM_MCP_PROMPT_CONTRACTS, PM_MCP_RESOURCE_CONTRACTS, PM_MCP_TOOL_COMMAND_CONTRACTS, listPmCommandsForTier, listPmMcpToolsForProfile, renderPmCommandVisibilityMarkdown, resolvePmCommandVisibilityTier, } from "./agent-capability-contracts.js";
 export * from "./agent-session-context.js";
 export { isErrnoError, limitAnnotationEntries, parseAnnotationTextInput, readAnnotationEntries, resolveAnnotationInput, resolveAnnotationIndex, runAnnotationCommand, wrapOwnershipConflict, } from "./annotations.js";
@@ -21,7 +21,7 @@ export { quoteCommandArg, quoteWindowsCommandArg, renderPmCommand, } from "./com
 export { runGc, } from "./governance/gc.js";
 export { _testOnlyHealthCommand, runHealth, } from "./governance/health.js";
 export { _testOnlyValidateCommand, projectValidateCounts, runValidate, } from "./governance/validate.js";
-export { runExtension, } from "./extension.js";
+export { runExtension } from "./extension.js";
 export { resolveExtensionInstallSourceIdentity, } from "./extension/source-resolution.js";
 export { applyStoredExtensionMigrationState, readExtensionMigrationState, resolveExtensionMigrationStatePath, runExtensionMigrateAction, runExtensionMigrations, } from "./extension/migrations.js";
 export { findInstalledNpmPackageCandidate, } from "./extension/install-sources.js";
@@ -59,6 +59,8 @@ export * from "./lifecycle-completion.js";
 export * from "./lifecycle-policy.js";
 export * from "./output-projection.js";
 export * from "./read-output-contracts.js";
+export * from "./read-output-rows.js";
+export * from "./read-output-session.js";
 export * from "./output-token-accounting.js";
 export * from "./context-packing.js";
 export * from "./context-usage.js";
@@ -68,7 +70,7 @@ export * from "./history-compact.js";
 export * from "./history-read.js";
 export * from "./history-provenance.js";
 export * from "./mutation-events.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 * from "./history-redact.js";
 export { _testOnly } from "./history-redact.js";
 export * from "./history-repair.js";
@@ -117,6 +119,8 @@ export { BASELINE_ITEM_FORMAT_VERSION, BUILTIN_ITEM_TYPE_VALUES, CONFIDENCE_TEXT
 export { extensionMigrate, packageMigrate } from "./package-migrations.js";
 export { CONTEXT_OUTPUT_VALUES, NEXT_OUTPUT_VALUES, PM_GITIGNORE_END, PM_GITIGNORE_START, analyzeSdkActionCoverage, ensurePmGitignore, getPmGitignoreBlock, closeItem, runAggregate, runClose, runCopy, runContext, runDelete, runFocus, runGet, runNext, runRestore, runUpdate, } from "./runtime.js";
 export { runStats } from "./stats.js";
+export { readImprovementLedger, recordImprovementObservation, } from "./improvement-ledger.js";
+export { evaluateProvenanceCoverage, projectFleetAttributionAnalytics, projectProvenanceCoverageAnalytics, readHistoryAnalyticsWindow, runFleetAttributionAnalytics, runProvenanceCoverageAnalytics, } from "./history-analytics.js";
 export { DEFAULT_EVAL_QUERIES_RELATIVE_PATH, EVAL_QUERY_SET_CONTRACT, EVAL_QUERY_SET_EXAMPLE, EVAL_QUERY_SET_SCHEMA_ID, parseEvalQuerySet, runEval, } from "./eval.js";
 export { runTelemetry, TELEMETRY_SUBCOMMANDS, } from "./telemetry.js";
 export { classifyLinkedTestFailure, countFailureCategories, extractReferencedPmItemIdsFromCommand, resolveLinkedTestFailureExitCode, runLinkedTests, runTest, summarizeContextPreflight, } from "./test/execution.js";
@@ -133,4 +137,4 @@ export * from "./governance.js";
 export * from "./query.js";
 export * from "./testing.js";
 //# sourceMappingURL=index.js.map
-//# debugId=4e336574-f00e-5296-a55f-7f27a264188c
+//# debugId=346cbfc0-a42a-5ae6-b95a-af3bd63fc6d1

package/dist/sdk/lifecycle/plan.js

@@ -4,7 +4,7 @@
  * Implements the pm plan 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]="d4b9caa3-59eb-5747-ba76-49f786c5010e")}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]="5d3c68a6-0b40-56b5-ae9e-776e1830ed3e")}catch(e){}}();
 import { pathExists, getActiveExtensionRegistrations, isTerminalStatus, resolveItemTypeRegistry, resolveRuntimeStatusRegistry, resolveTypeName, EXIT_CODE, PmCliError, splitCommaList, nowIso, locateItem, mutateItem, readLocatedItem, getSettingsPath, resolvePmRoot, readSettings, resolveAuthor, isTerminalPlanMode, } from "../runtime-primitives.js";
 import { PLAN_HARNESS_VALUES, PLAN_MODE_VALUES, PLAN_STEP_LINK_KIND_VALUES, PLAN_STEP_STATUS_VALUES, } from "../../types/index.js";
 import { runCreate, } from "./create.js";
@@ -726,7 +726,10 @@ async function planCreate(options, global, ctx) {
         test: toSpecArray(options.test),
         doc: toSpecArray(options.doc),
         field: toSpecArray(options.field),
-        assignee: requestedAssignee,
+        // Ownership is assigned by the atomic Plan metadata mutation below. The
+        // base create must remain author-owned so strict ownership governance does
+        // not reject the metadata seed as a cross-owner follow-up mutation.
+        assignee: resolveAuthor(options.author, ctx.settings.author_default),
         blockedBy: undefined,
         dep: buildPlanCreateDependencies(options),
         message: options.message ??
@@ -1576,4 +1579,4 @@ export const _testOnlyPlanCommand = {
     changedPlanMetadataFields,
 };
 //# sourceMappingURL=plan.js.map
-//# debugId=d4b9caa3-59eb-5747-ba76-49f786c5010e
+//# debugId=5d3c68a6-0b40-56b5-ae9e-776e1830ed3e

package/dist/sdk/merge/install.js

@@ -8,7 +8,7 @@
  * mutations refresh the fenced block automatically once it is installed.
  */
 
-!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]="1729579e-ef08-55c3-914f-c025ba3033e4")}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]="a250384a-0279-5d01-ade4-f64be3119ed9")}catch(e){}}();
 import { readFile, realpath, writeFile } from "node:fs/promises";
 import { execFile } from "node:child_process";
 import path from "node:path";
@@ -185,6 +185,14 @@ export function buildMergeAttributePatterns(trackerRelativeRoot, typeFolders) {
     patterns.push(`${quoteGitAttributePattern(`${prefix}history/*.jsonl`)} merge=pm-history`);
     patterns.push(`${quoteGitAttributePattern(`${prefix}settings.json`)} merge=pm-json`);
     patterns.push(`${quoteGitAttributePattern(`${prefix}**/*.json`)} merge=pm-json`);
+    // Extensions are package assets, not tracker item streams. The broad
+    // fallback patterns above intentionally protect unknown contributed item
+    // folders, so this last-match escape hatch must explicitly unset merge for
+    // every file beneath the reserved extension package root.
+    patterns.push(`${quoteGitAttributePattern(`${prefix}extensions/**`)} -merge`);
+    // The managed extension inventory is tracker state rather than package
+    // content, so restore its structured JSON driver after the asset exclusion.
+    patterns.push(`${quoteGitAttributePattern(`${prefix}extensions/.managed-extensions.json`)} merge=pm-json`);
     return patterns;
 }
 async function reconcileGitattributesBlock(workspaceRoot, patterns, dryRun) {
@@ -510,4 +518,4 @@ export async function installMergeFence(options) {
     };
 }
 //# sourceMappingURL=install.js.map
-//# debugId=1729579e-ef08-55c3-914f-c025ba3033e4
+//# debugId=a250384a-0279-5d01-ade4-f64be3119ed9

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

@@ -1,21 +1,12 @@
 
-!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]="64c4e6e1-d7c4-50e0-a444-fb2fa3c65443")}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]="1726fdce-dc71-5707-ae75-b588691e813d")}catch(e){}}();
+import { countReadOutputRows, readOutputRowCollections, } from "./read-output-rows.js";
 const MAX_ESTIMATE_ITERATIONS = 8;
 const MAX_COMPACTION_ITERATIONS = 64;
 /** Return whether a value is a non-array object record. */
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
-/** Resolve declared row keys, falling back to top-level array properties. */
-function rowKeys(result) {
-    const contract = result.row_contract;
-    if (isRecord(contract) && Array.isArray(contract.row_keys)) {
-        return contract.row_keys.filter((entry) => typeof entry === "string");
-    }
-    return Object.entries(result)
-        .filter(([, value]) => Array.isArray(value))
-        .map(([key]) => key);
-}
 /** Recursively shorten explanatory strings and record whether content changed. */
 function compactStrings(value, state) {
     if (typeof value === "string") {
@@ -48,27 +39,38 @@ export function updateReadOutputReceiptEstimate(result, receipt) {
 }
 /** Reduce the largest row collection until the budget fits or no rows can move. */
 function compactRowsToBudget(result, receipt, budget) {
-    const keys = rowKeys(result);
     for (let iteration = 0; iteration < MAX_COMPACTION_ITERATIONS; iteration += 1) {
         updateReadOutputReceiptEstimate(result, receipt);
         if (receipt.estimated_tokens <= budget)
             return;
-        const candidate = keys
-            .map((key) => ({
-            key,
-            rows: Array.isArray(result[key]) ? result[key] : [],
+        const candidate = readOutputRowCollections(result)
+            .filter((collection) => (Array.isArray(collection.value)
+            ? collection.value.length
+            : Object.keys(collection.value).length) > 1)
+            .map((collection) => ({
+            collection,
+            length: Array.isArray(collection.value)
+                ? collection.value.length
+                : Object.keys(collection.value).length,
         }))
-            .filter(({ rows }) => rows.length > 1)
-            .sort((left, right) => right.rows.length - left.rows.length ||
-            left.key.localeCompare(right.key))[0];
+            .sort((left, right) => right.length - left.length ||
+            left.collection.path.localeCompare(right.collection.path))[0]?.collection;
         if (!candidate)
             return;
-        candidate.rows.splice(-Math.max(1, Math.ceil(candidate.rows.length / 2)));
+        if (Array.isArray(candidate.value)) {
+            candidate.value.splice(-Math.max(1, Math.ceil(candidate.value.length / 2)));
+        }
+        else {
+            const keys = Object.keys(candidate.value);
+            for (const key of keys.slice(-Math.max(1, Math.ceil(keys.length / 2)))) {
+                delete candidate.value[key];
+            }
+        }
         receipt.rows_compacted = true;
         result.has_more = true;
         result.truncated = true;
         if (typeof result.count === "number") {
-            result.count = keys.reduce((total, key) => total + (Array.isArray(result[key]) ? result[key].length : 0), 0);
+            result.count = countReadOutputRows(result);
         }
     }
 }
@@ -83,4 +85,4 @@ export function compactReadOutputToBudget(result, receipt, budget) {
     return compacted;
 }
 //# sourceMappingURL=read-output-budget.js.map
-//# debugId=64c4e6e1-d7c4-50e0-a444-fb2fa3c65443
+//# debugId=1726fdce-dc71-5707-ae75-b588691e813d

package/dist/sdk/read-output-contracts.d.ts

@@ -1,3 +1,4 @@
+import { type PmReadOutputSessionReceipt, type PmReadOutputSessionState } from "./read-output-session.js";
 /** Stable output dimensions shared by every read surface. */
 export declare const PM_READ_OUTPUT_DIMENSIONS: readonly ["include", "amount", "cost", "encoding"];
 /** One member of the universal read-output dimension set. */
@@ -16,6 +17,8 @@ export interface PmReadOutputOptions {
     outputBudget?: string | number;
     /** Requested static renderer encoding; streaming remains a command behavior. */
     outputFormat?: "json" | "toon";
+    /** Caller-carried cross-call budget and served-fact state. */
+    outputSession?: string | PmReadOutputSessionState;
 }
 /** Compatibility spelling retained for a command-specific output control. */
 export interface PmReadOutputLegacyAlias {
@@ -118,11 +121,16 @@ export interface PmReadOutputBudgetExceeded {
 /** Read result with an optional shaping receipt or a discriminated omission. */
 export type PmReadOutputResult<Result> = (Result & {
     read_output?: PmReadOutputReceipt;
-}) | PmReadOutputBudgetExceeded;
+    read_session?: PmReadOutputSessionReceipt;
+}) | (PmReadOutputBudgetExceeded & {
+    read_session?: PmReadOutputSessionReceipt;
+});
 /** Select the omission-aware result type when an option shape can request a budget. */
-export type PmReadOutputResultFor<Result, Options> = "outputBudget" extends keyof Options ? PmReadOutputResult<Result> : Result;
+export type PmReadOutputResultFor<Result, Options> = "outputBudget" extends keyof Options ? PmReadOutputResult<Result> : "outputSession" extends keyof Options ? PmReadOutputResult<Result> : Result;
 /** Canonical CLI flags that opt a read invocation into universal output shaping. */
 export declare const PM_READ_OUTPUT_OPTION_FLAGS: readonly string[];
+/** Canonical control that composes the four per-call dimensions across reads. */
+export declare const PM_READ_OUTPUT_COMPOSITION_OPTION_FLAGS: readonly ["--output-session"];
 /** Universal output contract for every built-in read surface. */
 export declare const PM_READ_OUTPUT_SURFACE_CONTRACTS: readonly PmReadOutputSurfaceContract[];
 /** Resolve a command or list/context alias to its canonical read-output surface. */