@unbrained/pm-cli 2026.8.6 → 2026.8.8

package/dist/sdk/stats.js

@@ -4,7 +4,7 @@
  * Implements the pm stats 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]="e8916552-697e-565c-91e1-4829ecb584af")}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]="a4de53c1-bb22-591f-a064-142c642a2443")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { getActiveExtensionRegistrations, runActiveOnReadHooks, } from "../core/extensions/index.js";
@@ -21,6 +21,9 @@ import { nowIso } from "../core/shared/time.js";
 import { listAllItemMetadataLight, listAllItemMetadataWithBody, } from "../core/store/item-store.js";
 import { getSettingsPath, resolvePmRoot } from "../core/store/paths.js";
 import { readSettings } from "../core/store/settings.js";
+import { recordImprovementObservation, readImprovementLedger, } from "./improvement-ledger.js";
+import { projectFleetAttributionAnalytics, projectProvenanceCoverageAnalytics, readHistoryAnalyticsWindow, } from "./history-analytics.js";
+import { parseTestRunMeasurements } from "./test/measurements.js";
 function zeroByType(itemTypes) {
     return itemTypes.reduce((acc, value) => {
         acc[value] = 0;
@@ -73,6 +76,88 @@ export const _testOnly = {
     countNonEmptyLines,
     readHistoryStreamContents,
 };
+async function recordStatsObservations(global, options) {
+    const recorded = [];
+    const observedAt = nowIso();
+    for (const measurement of parseTestRunMeasurements(options.observe, observedAt)) {
+        recorded.push(await recordImprovementObservation({
+            metric: measurement.name,
+            value: measurement.value,
+            direction: options.direction,
+            unit: measurement.unit,
+            threshold: measurement.threshold,
+            source: options.measurementSource,
+            itemId: options.measurementItem,
+            revision: options.measurementRevision,
+            observedAt,
+            author: options.author,
+            message: options.message,
+        }, global));
+    }
+    return recorded;
+}
+function requestedBreakdowns(items, options, classifier) {
+    const breakdowns = {};
+    if (options.byAssignee) {
+        breakdowns.assignee = groupItemsByDimension(items, "assignee", classifier);
+    }
+    if (options.byTag) {
+        breakdowns.tag = groupItemsByDimension(items, "tag", classifier, {
+            tagPrefix: options.tagPrefix,
+        });
+    }
+    if (options.byPriority) {
+        breakdowns.priority = groupItemsByDimension(items, "priority", classifier);
+    }
+    return breakdowns;
+}
+async function requestedHistoryAnalytics(pmRoot, items, settings, terminalStatuses, options) {
+    const historyOptions = {
+        since: options.since,
+        eventLimit: options.eventLimit,
+        minimumSample: options.minimumSample,
+    };
+    const sharedWindow = options.provenanceCoverage || options.fleetAttribution
+        ? await readHistoryAnalyticsWindow(pmRoot, historyOptions)
+        : undefined;
+    return {
+        provenanceCoverage: options.provenanceCoverage && sharedWindow
+            ? projectProvenanceCoverageAnalytics(sharedWindow, settings.agent_identity?.harness_signals, historyOptions)
+            : undefined,
+        fleetAttribution: options.fleetAttribution && sharedWindow
+            ? projectFleetAttributionAnalytics(sharedWindow, items, terminalStatuses, historyOptions)
+            : undefined,
+    };
+}
+function assembleStatsResult(totals, byType, byStatus, optional) {
+    const hasBreakdowns = Object.keys(optional.breakdowns).length > 0;
+    return {
+        totals,
+        by_type: byType,
+        by_status: byStatus,
+        ...(optional.metadataCoverage
+            ? { metadata_coverage: optional.metadataCoverage }
+            : {}),
+        ...(hasBreakdowns ? { breakdowns: optional.breakdowns } : {}),
+        ...(optional.storage ? { storage: optional.storage } : {}),
+        ...(optional.fieldUtilization
+            ? { field_utilization: optional.fieldUtilization }
+            : {}),
+        ...(optional.improvementLedger
+            ? { improvement_ledger: optional.improvementLedger }
+            : {}),
+        ...(optional.recordedObservations.length > 0
+            ? { recorded_observations: optional.recordedObservations }
+            : {}),
+        ...(optional.provenanceCoverage
+            ? { provenance_coverage: optional.provenanceCoverage }
+            : {}),
+        ...(optional.fleetAttribution
+            ? { fleet_attribution: optional.fleetAttribution }
+            : {}),
+        generated_at: nowIso(),
+    };
+}
 /** Implements run stats for the public runtime surface of this module. */
 export async function runStats(global, options = {}) {
     const pmRoot = resolvePmRoot(process.cwd(), global.path);
@@ -80,6 +165,7 @@ export async function runStats(global, options = {}) {
         throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
     }
     const settings = await readSettings(pmRoot);
+    const recordedObservations = await recordStatsObservations(global, options);
     const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
     const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
     // Field utilization needs the heavy collections (notes/learnings/files/docs/
@@ -116,36 +202,33 @@ export async function runStats(global, options = {}) {
     const metadataCoverage = options.metadataCoverage
         ? computeMetadataCoverage(items, classifier)
         : undefined;
-    const breakdowns = {};
-    if (options.byAssignee) {
-        breakdowns.assignee = groupItemsByDimension(items, "assignee", classifier);
-    }
-    if (options.byTag) {
-        breakdowns.tag = groupItemsByDimension(items, "tag", classifier, {
-            tagPrefix: options.tagPrefix,
-        });
-    }
-    if (options.byPriority) {
-        breakdowns.priority = groupItemsByDimension(items, "priority", classifier);
-    }
-    const hasBreakdowns = Object.keys(breakdowns).length > 0;
+    const breakdowns = requestedBreakdowns(items, options, classifier);
     const fieldUtilization = options.fieldUtilization
         ? computeContentFieldUtilization(items)
         : undefined;
-    return {
-        totals: {
-            items: items.length,
-            history_streams: streams.length,
-            history_entries: historyEntries,
-        },
-        by_type: byType,
-        by_status: byStatus,
-        ...(metadataCoverage ? { metadata_coverage: metadataCoverage } : {}),
-        ...(hasBreakdowns ? { breakdowns } : {}),
-        ...(storage ? { storage } : {}),
-        ...(fieldUtilization ? { field_utilization: fieldUtilization } : {}),
-        generated_at: nowIso(),
-    };
+    const improvementLedger = options.measurements === true || recordedObservations.length > 0
+        ? await readImprovementLedger({
+            pmRoot,
+            metric: options.metric,
+            itemId: options.measurementItem,
+            limit: options.measurementLimit,
+        })
+        : undefined;
+    const { provenanceCoverage, fleetAttribution } = await requestedHistoryAnalytics(pmRoot, items, settings, statusRegistry.terminal_statuses, options);
+    return assembleStatsResult({
+        items: items.length,
+        history_streams: streams.length,
+        history_entries: historyEntries,
+    }, byType, byStatus, {
+        metadataCoverage,
+        breakdowns,
+        storage,
+        fieldUtilization,
+        improvementLedger,
+        recordedObservations,
+        provenanceCoverage,
+        fleetAttribution,
+    });
 }
 //# sourceMappingURL=stats.js.map
-//# debugId=e8916552-697e-565c-91e1-4829ecb584af
+//# debugId=a4de53c1-bb22-591f-a064-142c642a2443

package/dist/sdk/test/execution.js

@@ -4,7 +4,7 @@
  * Implements the pm test 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]="7d05534b-3cf7-506c-8626-4bd4a42cbc80")}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]="2c0646bf-44d7-521f-aea1-b0683d88a8fa")}catch(e){}}();
 import { spawn } from "node:child_process";
 import { cp, mkdir, mkdtemp, open, readdir, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
@@ -28,6 +28,7 @@ import { LINKED_TEST_PM_CONTEXT_MODE_VALUES as PM_CONTEXT_MODE_VALUES, LINKED_TE
 import { parseOnlyIndexValue, resolveLinkedTestRunSelection, } from "../../core/test/run-selectors.js";
 import { SCOPE_VALUES } from "../../types/index.js";
 import { diffTestRunMeasurements, parseTestRunMeasurements, queryTestRunMeasurementsBelow, } from "./measurements.js";
+import { SOURCE_CONTEXT_ACCESS_ENV } from "../environment/source-context.js";
 const TEST_OUTPUT_MAX_BUFFER_BYTES = 20 * 1024 * 1024;
 const DEFAULT_LINKED_TEST_TIMEOUT_FORCE_KILL_DELAY_MS = 3000;
 const DEFAULT_LINKED_TEST_HEARTBEAT_INTERVAL_MS = 10000;
@@ -1398,6 +1399,7 @@ function buildLinkedTestExecutionEnv(params) {
         process.env.PM_SOURCE_WORKSPACE_ROOT ?? process.cwd();
     executionEnv.PM_SOURCE_PM_PATH =
         params.executionContext.source_project_pm_path;
+    executionEnv[SOURCE_CONTEXT_ACCESS_ENV] = "read_only";
     return executionEnv;
 }
 function buildLinkedTestPassedResult(linkedTest, executionContext, execution) {
@@ -1872,4 +1874,4 @@ export const _testOnlyTestCommand = {
     summarizeRunResultStatuses,
 };
 //# sourceMappingURL=execution.js.map
-//# debugId=7d05534b-3cf7-506c-8626-4bd4a42cbc80
+//# debugId=2c0646bf-44d7-521f-aea1-b0683d88a8fa

package/dist/sdk/test/parsers.js

@@ -4,13 +4,14 @@
  * Implements the pm linked test parsers 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]="f592ba2b-fc8d-5930-a2a5-d02835c457a3")}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]="74163bed-a473-543e-ae6a-0d5091b3b3a9")}catch(e){}}();
 import { parseOptionalNumber } from "../../core/item/parse.js";
 import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
 import { splitCommaList } from "../../core/shared/split-comma-list.js";
 import { STRUCTURED_LINKED_TEST_KEYS } from "./entry.js";
 import { SCOPE_VALUES } from "../../types/index.js";
+import { SOURCE_CONTEXT_ACCESS_ENV, SOURCE_CONTEXT_WRITE_OVERRIDE_ENV, } from "../environment/source-context.js";
 /**
  * Shared linked-test field parsers used by the `create` and `test` commands.
  *
@@ -30,6 +31,8 @@ export const LINKED_TEST_PROTECTED_ENV_KEYS = new Set([
     "PM_GLOBAL_PATH",
     "PM_SOURCE_PM_PATH",
     "PM_SOURCE_WORKSPACE_ROOT",
+    SOURCE_CONTEXT_ACCESS_ENV,
+    SOURCE_CONTEXT_WRITE_OVERRIDE_ENV,
     "FORCE_COLOR",
 ]);
 /** Public contract for linked test env name pattern, shared by SDK and presentation-layer consumers. */
@@ -521,4 +524,4 @@ export const _testOnlyLinkedTestParsers = {
     parseLinkedTestJsonEntry,
 };
 //# sourceMappingURL=parsers.js.map
-//# debugId=f592ba2b-fc8d-5930-a2a5-d02835c457a3
+//# debugId=74163bed-a473-543e-ae6a-0d5091b3b3a9

package/dist/sdk/workspace-snapshot.d.ts

@@ -29,6 +29,7 @@ declare class WorkspaceLockHeartbeat {
 /** Internal heartbeat constructor exposed only for deterministic lock tests. */
 export declare const _testOnlyWorkspaceSnapshot: {
     WorkspaceLockHeartbeat: typeof WorkspaceLockHeartbeat;
+    withSnapshotFilesystemGuard: typeof withSnapshotFilesystemGuard;
 };
 /** Immutable manifest stored with every content-addressed snapshot object. */
 export interface WorkspaceSnapshotManifest {
@@ -117,6 +118,14 @@ export interface RestoreWorkspaceSnapshotResult {
     /** Stable audit operation appended after staging and before activation. */
     audit_operation: "workspace_snapshot_restore";
 }
+/**
+ * Runs a bounded snapshot filesystem stage, converting host environment faults
+ * into declared refusals.
+ *
+ * The operation label is a fixed identifier, never a path: snapshot failures
+ * are reported without disclosing workspace topology.
+ */
+declare function withSnapshotFilesystemGuard<T>(operation: string, run: () => Promise<T>): Promise<T>;
 /**
  * Publish a prepared immutable object, treating a concurrent winning publish
  * as successful deduplication.

package/dist/sdk/workspace-snapshot.js

@@ -5,7 +5,7 @@
  * state while excluding clone-local caches, locks, and recovery journals.
  */
 
-!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]="3e32be7c-f8a4-547d-8c19-456b4567982e")}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]="cdde844a-a14a-501d-a45b-18cbd1dd9008")}catch(e){}}();
 import crypto from "node:crypto";
 import { cp, lstat, mkdir, readFile, readdir, rename, rm, writeFile, } from "node:fs/promises";
 import path from "node:path";
@@ -15,6 +15,7 @@ import { acquireLock } from "../core/lock/lock.js";
 import { getLockPath } from "../core/store/paths.js";
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
+import { withHostEnvironmentBoundary } from "./environment/host-environment-errors.js";
 /** Current content-addressed workspace snapshot manifest schema identifier. */
 export const SNAPSHOT_SCHEMA = "https://schema.unbrained.dev/pm/workspace-snapshot/v1";
 const SNAPSHOT_RUNTIME_PATH = path.join("runtime", "workspace-snapshots");
@@ -27,6 +28,11 @@ const EXCLUDED_ROOT_NAMES = new Set([
 ]);
 const SNAPSHOT_TARGET_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
 const WORKSPACE_WRITER_LOCK_ID = "sdk-workspace-transaction";
+const SNAPSHOT_HOST_FAULT_CODES = {
+    capacity: { code: "workspace_snapshot_storage_exhausted" },
+    permission: { code: "workspace_snapshot_permission_denied" },
+    resource: { code: "workspace_snapshot_resource_exhausted" },
+};
 const DEFAULT_ATOMIC_OPERATIONS = {
     renameEntry: rename,
     removeEntry: async (target) => {
@@ -97,6 +103,7 @@ class WorkspaceLockHeartbeat {
 /** Internal heartbeat constructor exposed only for deterministic lock tests. */
 export const _testOnlyWorkspaceSnapshot = {
     WorkspaceLockHeartbeat,
+    withSnapshotFilesystemGuard,
 };
 async function collectAuthoritativeFiles(root, relative = "") {
     const entries = await readdir(path.join(root, relative), {
@@ -193,6 +200,27 @@ function isErrno(error, code) {
         "code" in error &&
         error.code === code);
 }
+/**
+ * Runs a bounded snapshot filesystem stage, converting host environment faults
+ * into declared refusals.
+ *
+ * The operation label is a fixed identifier, never a path: snapshot failures
+ * are reported without disclosing workspace topology.
+ */
+async function withSnapshotFilesystemGuard(operation, run) {
+    return withHostEnvironmentBoundary(`workspace_snapshot_${operation}`, run, {
+        codes: {
+            capacity: SNAPSHOT_HOST_FAULT_CODES.capacity.code,
+            permission: SNAPSHOT_HOST_FAULT_CODES.permission.code,
+            resource: SNAPSHOT_HOST_FAULT_CODES.resource.code,
+        },
+        why: "Snapshot create and restore copy authoritative tracker state before activation, so the stage needs capacity and write access up front.",
+        nextSteps: [
+            "Reclaim rebuildable tracker cache space with pm gc, then retry.",
+        ],
+        suggestedRetry: "pm gc --json",
+    });
+}
 function snapshotStore(pmRoot) {
     return path.join(pmRoot, SNAPSHOT_RUNTIME_PATH);
 }
@@ -302,14 +330,16 @@ export async function createWorkspaceSnapshot(pmRoot, options = {}) {
     }
     if (!deduplicated) {
         const temporaryRoot = path.join(store, "objects", `.create-${process.pid}-${crypto.randomUUID()}`);
-        await mkdir(path.join(temporaryRoot, "files"), { recursive: true });
-        for (const [index, file] of manifest.files.entries()) {
-            const target = path.join(temporaryRoot, "files", file);
-            await mkdir(path.dirname(target), { recursive: true });
-            await writeFile(target, contents[index]);
-        }
-        await writeFile(path.join(temporaryRoot, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
-        await mkdir(path.dirname(objectRoot), { recursive: true });
+        await withSnapshotFilesystemGuard("create_object", async () => {
+            await mkdir(path.join(temporaryRoot, "files"), { recursive: true });
+            for (const [index, file] of manifest.files.entries()) {
+                const target = path.join(temporaryRoot, "files", file);
+                await mkdir(path.dirname(target), { recursive: true });
+                await writeFile(target, contents[index]);
+            }
+            await writeFile(path.join(temporaryRoot, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+            await mkdir(path.dirname(objectRoot), { recursive: true });
+        });
         deduplicated = await publishWorkspaceSnapshotObject(temporaryRoot, objectRoot);
     }
     if (options.name !== undefined) {
@@ -467,12 +497,14 @@ export async function restoreWorkspaceSnapshotWithRecovery(pmRoot, target, optio
         const base = path.basename(pmRoot);
         staging = path.join(parent, `.${base}.restore-${crypto.randomUUID()}`);
         const backup = path.join(parent, `.${base}.backup-${crypto.randomUUID()}`);
-        await mkdir(staging, { recursive: true });
-        await cp(source, staging, { recursive: true, force: false });
-        await mkdir(path.join(staging, "runtime"), { recursive: true });
-        await cp(store, path.join(staging, SNAPSHOT_RUNTIME_PATH), {
-            recursive: true,
-            force: false,
+        await withSnapshotFilesystemGuard("restore_stage", async () => {
+            await mkdir(staging, { recursive: true });
+            await cp(source, staging, { recursive: true, force: false });
+            await mkdir(path.join(staging, "runtime"), { recursive: true });
+            await cp(store, path.join(staging, SNAPSHOT_RUNTIME_PATH), {
+                recursive: true,
+                force: false,
+            });
         });
         const audit = await appendWorkspaceAuditEvent({
             pmRoot: staging,
@@ -564,4 +596,4 @@ export async function deleteWorkspaceSnapshot(pmRoot, target) {
     return { deleted: "object", target };
 }
 //# sourceMappingURL=workspace-snapshot.js.map
-//# debugId=3e32be7c-f8a4-547d-8c19-456b4567982e
+//# debugId=cdde844a-a14a-501d-a45b-18cbd1dd9008

package/docs/AGENT_RUNTIME_PRIMITIVES.md

@@ -25,6 +25,8 @@ historical projections, and versioned legacy identity are tracked by
 [pm-ffz0a9](../.agents/pm/issues/pm-ffz0a9.toon),
 [pm-v8gfi7](../.agents/pm/issues/pm-v8gfi7.toon), and
 [pm-3yxwv5](../.agents/pm/issues/pm-3yxwv5.toon).
+[pm-alhqbz](../.agents/pm/issues/pm-alhqbz.toon) governs the nested source-write
+boundary retained by linked-test package lifecycles.
 
 `pm` treats project management as context management. These primitives keep
 mutation provenance, source-workspace identity, extension flags, and bounded
@@ -198,10 +200,15 @@ Every extension command, parser, preflight hook, renderer, and service receives:
 Linked tests set `PM_SOURCE_WORKSPACE_ROOT` before replacing `PM_PATH` and
 `PM_GLOBAL_PATH`, and protect `PM_SOURCE_PM_PATH` as the read-only source
 tracker coordinate for source-repository lifecycle commands such as
-`pm merge install`. Extensions can therefore inspect source VCS metadata
-without writing real tracker state. Package code should prefer `pm_root_rel`
-in output and persisted evidence to avoid leaking host-specific absolute
-paths.
+`pm merge install`. They also set `PM_SOURCE_CONTEXT_ACCESS=read_only`.
+Validation may continue to inspect the source coordinates, but a nested
+non-dry-run `pm merge install` selects the current package repository instead
+of the source workspace. A maintainer can deliberately opt into the legacy
+source mutation for one invocation with `PM_ALLOW_SOURCE_CONTEXT_WRITES=1`;
+`resolveMergeInstallContext()` reports whether that override selects the source.
+Both variables are protected from linked-test `env_set` and `env_clear`
+metadata. Package code should prefer `pm_root_rel` in output and persisted
+evidence to avoid leaking host-specific absolute paths.
 
 ## Strict extension flag descriptors
 

package/docs/IMPROVEMENT_ANALYTICS.md

@@ -0,0 +1,103 @@
+# Improvement Ledger and History Analytics
+
+Tracker references: [pm-chahyq](../.agents/pm/features/pm-chahyq.toon), [pm-1wiugq](../.agents/pm/issues/pm-1wiugq.toon), [pm-gw6uyq](../.agents/pm/features/pm-gw6uyq.toon)
+
+`pm` treats project management as context management. Improvement observations and fleet analytics therefore remain attached to authoritative project context: observations are audited workspace state, while provenance and outcome analytics are bounded projections of immutable history.
+
+## Agent Quick Context
+
+- Record quantitative evidence with `pm stats --analytics '{...}'`; do not hand-edit `.agents/pm/improvement-ledger.json`.
+- Request ledger and history projections through the single typed `--analytics` JSON object. This keeps the agent-facing command contract bounded while the SDK and MCP retain their fully typed fields.
+- Ledger reads are newest-first and bounded; trends still use every matching retained observation.
+- Use an explicit metric direction. `lower` is the default; `target` requires a threshold and measures convergence toward it.
+- Use `provenanceCoverage` to find declared-but-inert or undeclared provenance dimensions.
+- Use `fleetAttribution` for observational comparisons only. It must never authorize, assign, route, rank, or evaluate an individual agent.
+- Bound history work with `since`, `eventLimit`, and `minimumSample`.
+
+## Audited improvement observations
+
+```bash
+pm stats \
+  --analytics "$(jq -cn --arg revision "$(git rev-parse HEAD)" '{
+    observe: ["quality.coverage.lines=100,unit=percent,threshold=100"],
+    direction: "higher",
+    measurementSource: "pnpm coverage",
+    measurementItem: "pm-example",
+    measurementRevision: $revision,
+    measurements: true
+  }')" \
+  --json
+```
+
+Each observation records a content identity, metric, finite value, direction, timestamp, revision provenance, author, and optional unit, threshold, source, and owning item. When no revision is supplied, `pm` uses Git HEAD when available and otherwise records an explicit `unversioned` marker.
+
+Retries are idempotent by revision, metric, source, and owner. Reusing that key with different numeric or metric-contract data fails with a conflict instead of silently rewriting history. A metric keeps one direction, unit, and—when target-directed—target threshold throughout its series.
+
+```bash
+pm stats --analytics '{"measurements":true,"metric":"quality.coverage.lines","measurementLimit":20}'
+```
+
+The `improvement_ledger` result contains:
+
+- `observations`: a bounded newest-first page;
+- `total` and `truncated`: the complete match count and omission state;
+- `trends`: baseline, latest, delta, improvement state, and sample count per metric;
+- `source: audited_workspace_singleton`: the state provenance receipt.
+
+The singleton is written through the workspace lock and `_workspace` hash-chained audit stream. Compaction may reduce historical patches, but it does not remove current ledger state.
+
+## Provenance coverage
+
+```bash
+pm stats --analytics '{"provenanceCoverage":true,"since":"-30d","eventLimit":10000,"minimumSample":5}' --json
+```
+
+This projection compares configured harness signal descriptors with observed immutable history. It reports descriptor coverage, observed/unavailable/legacy-missing values, inert dimensions with sufficient explicit samples, undeclared dimensions, and stable warning codes. The live corpus is the positive control; deliberately missing descriptors and unavailable values provide negative controls in tests.
+
+## Fleet attribution
+
+```bash
+pm stats --analytics '{"fleetAttribution":true,"since":"-30d","eventLimit":10000,"minimumSample":5}' --json
+```
+
+Fleet attribution groups bounded events by harness, model, and author source. Each group reports state and annotation events, terminal transitions, reopens, and issues linked with `discovered_from` to closed work. Rates remain `null` until the close denominator reaches `minimum_sample`.
+
+The result always includes `policy: observational_only_not_for_authorization_or_routing`. Missing dimensions are `unavailable`, small denominators are `insufficient`, and a `window` receipt states the lower bound, consumed event count, truncation, and continuation cursor.
+
+## SDK
+
+```ts
+import {
+  readImprovementLedger,
+  recordImprovementObservation,
+  runFleetAttributionAnalytics,
+  runProvenanceCoverageAnalytics,
+} from "@unbrained/pm-cli/sdk";
+
+await recordImprovementObservation(
+  {
+    metric: "quality.coverage.lines",
+    value: 100,
+    direction: "higher",
+    unit: "percent",
+    revision: process.env.GIT_COMMIT,
+  },
+  { path: ".agents/pm" },
+);
+
+const ledger = await readImprovementLedger({
+  pmRoot: ".agents/pm",
+  metric: "quality.coverage.lines",
+  limit: 20,
+});
+```
+
+`PmClient.stats()` exposes the combined typed contract. The lower-level functions support packages that need one primitive without constructing a command transport. MCP uses the same action schema; its direction field is named `improvementDirection` to avoid collision with dependency-graph traversal direction. The CLI deliberately folds the new analytics fields into one validated `--analytics` object so its help and contract surface stay within the enforced agent-token budget.
+
+## Safety and interpretation
+
+- Treat observations as evidence, not a universal objective function. Record the producing gate and owning item so context survives.
+- Compare like-for-like metric contracts; a changed unit, direction, or target should use a new metric name.
+- Do not infer causality from attribution. The projection describes recorded history and relationship links only.
+- A truncated window is incomplete evidence. Resume or increase the bound before publishing conclusions.
+- Keep credentials, private payloads, host identifiers, and customer data out of metric names, sources, messages, and item links.

package/docs/OUTPUT_PROJECTION_CONTRACTS.md

@@ -213,19 +213,19 @@ metadata as a continuation negative control. The checked-in report is
 
 | Intent | 2-item tokens / budget | 2,243-item tokens / budget | Current-scale rows | Degradation |
 | ------ | ---------------------- | -------------------------- | ------------------ | ----------- |
-| `context:orient` | 707 / 2,400 | 1,000 / 2,400 | 3 | bounded sections |
+| `context:orient` | 735 / 2,400 | 1,028 / 2,400 | 3 | bounded sections |
 | `get:inspect` | 401 / 3,200 | 415 / 3,200 | item envelope | standard item |
-| `list:triage` | 393 / 3,200 | 3,181 / 3,200 | 70 | budget-derived rows |
+| `list:triage` | 443 / 3,200 | 3,189 / 3,200 | 69 | budget-derived rows |
 | `next:execute` | 395 / 1,200 | 1,171 / 1,200 | 14 | budget-derived rows |
-| `search:discover` | 301 / 1,800 | 1,763 / 1,800 | 28 | budget-derived rows |
+| `search:discover` | 350 / 1,800 | 1,761 / 1,800 | 27 | budget-derived rows |
 
 Whole-answer cursor cost is measured against the unprojected single call for
 the identical ordered row set:
 
 | Family | Rows | Pages | Optimized bytes/row | Optimized walk | Repeated-metadata control | Unbounded call | Walk / unbounded |
 | ------ | ---- | ----- | ------------------- | -------------- | ------------------------- | -------------- | ---------------- |
-| `list:triage` | 1,998 | 30 | 172.29 | 344,234 B | 379,875 B | 1,558,741 B | 0.2208 |
-| `search:discover` | 1,998 | 64 | 201.24 | 402,075 B | 454,869 B | 1,681,847 B | 0.2391 |
+| `list:triage` | 1,998 | 31 | 172.93 | 345,519 B | 387,489 B | 1,558,741 B | 0.2217 |
+| `search:discover` | 1,998 | 66 | 202.50 | 404,591 B | 470,046 B | 1,681,847 B | 0.2406 |
 
 These are corpus-generated figures, not live tracker payloads. The generated
 corpus contains 2,243 items; the `status:all` query intentionally excludes 245

package/docs/README.md

@@ -53,8 +53,10 @@ pm guide release --json
 - [Agent Provenance ADR Amendment](AGENT_PROVENANCE_ADR.md) - extensible model, effort, role, and host provenance with privacy and compatibility boundaries.
 - [SDK Agent Session and Episode Context](SDK_AGENT_SESSION_CONTEXT.md) - inherited role/topic context, cross-process episode identity, and deterministic history grouping.
 - [SDK Context Coordination](SDK_CONTEXT_COORDINATION.md) - durable mutation events, bounded duplicate governance, and scale-safe package primitives.
+- [Improvement Ledger and History Analytics](IMPROVEMENT_ANALYTICS.md) - audited quantitative observations, live provenance coverage, and bounded observational fleet outcomes.
 - [SDK Evidence Traceability and Integrity](SDK_EVIDENCE_TRACEABILITY.md) - reverse source-to-item lookup, atomic evidence replacement, no-op history, linked-test collision classification, and telemetry drain receipts.
 - [SDK Context Integrity Primitives](SDK_CONTEXT_INTEGRITY_PRIMITIVES.md) - batch duplicate discovery, structured errors, Plan evidence/lifecycle, sparse settings, tombstones, linked-test output, relocation diagnostics, and scoped output services.
+- [SDK Context Integrity](SDK_CONTEXT_INTEGRITY.md) - truthful `get` projections, bounded annotation mutations, shared author coordinates, health provider boundaries, and changeset-aware replication gates.
 - [Reproducible Workspaces and Snapshots](REPRODUCIBLE_WORKSPACES.md) - deterministic SDK recipes and content-addressed authoritative tracker restore points.
 - [Portable Corpus Shapes](CORPUS_SHAPES.md) - versioned SDK populations for realistic benchmarks, evaluations, and package tests.
 - [Agent UX Contracts](AGENT_UX_CONTRACTS.md) - ordering-cycle advisories, graph count units, collision safety, compact context, ownership wording, and recovery behavior.

package/docs/READ_OUTPUT_CONTRACTS.md

@@ -1,6 +1,6 @@
 # Universal Read Output Contracts
 
-Tracker references: [pm-hb7ug8](../.agents/pm/features/pm-hb7ug8.toon) and [pm-cxr0jb](../.agents/pm/features/pm-cxr0jb.toon).
+Tracker references: [pm-hb7ug8](../.agents/pm/features/pm-hb7ug8.toon), [pm-cxr0jb](../.agents/pm/features/pm-cxr0jb.toon), [pm-hid9g1](../.agents/pm/features/pm-hid9g1.toon), and [pm-sb0tns](../.agents/pm/issues/pm-sb0tns.toon).
 
 ## Agent Quick Context
 
@@ -15,6 +15,58 @@ Every built-in read surface uses four output dimensions: what to include, how mu
 
 The contract covers `list`, `context`, `search`, `get`, `next`, `health`, `deps`, `graph`, `history`, `activity`, `validate`, `events`, `contracts`, `comments`, `notes`, `files`, `docs`, `stats`, and `aggregate`, including list aliases and `ctx`.
 
+Row shaping follows each envelope's `row_contract.row_keys`, including
+dot-delimited nested arrays and object maps such as `graph.nodes`. Include,
+amount, repeat suppression, and cost compaction therefore operate on the same
+machine-declared rows; they do not rely on command-specific top-level keys.
+
+## Cross-Call Context Sessions
+
+`--output-session <json>` / `outputSession` composes the four per-call
+dimensions across a request group. The caller supplies versioned state and
+passes the returned `read_session.next_state` to the next read:
+
+```json
+{
+  "version": 1,
+  "id": "orientation",
+  "token_budget": 4000,
+  "spent_tokens": 0,
+  "seen_item_ids": []
+}
+```
+
+The session ceiling and an explicit `--output-budget` both bind; the smaller
+remaining allowance wins. Rows for item facts already present in the caller's
+context become `{ "id": "pm-a1b2", "context_ref":
+"session:orientation:pm-a1b2" }` instead of repeating prose. References retain
+stable item identity and can be restored with `pm get <item-id> --brief` when
+the prior context is unavailable. The receipt reports estimated and charged
+tokens separately when the remaining group allowance is smaller than the
+minimum control envelope, plus the accumulated spend, remaining capacity,
+newly served items, and suppressed repeats.
+
+Session state is deliberately caller-carried: CLI processes, SDK clients, MCP
+hosts, and packages share the same deterministic primitive without a hidden
+daemon or mutable cache. Validation rejects unknown fields, invalid identifiers,
+unsupported schema versions, unsafe integers, and spend beyond the declared
+ceiling before a read executes.
+
+The mandatory orientation calibration runs `context`, `list`, `search`, `get`,
+and `next` against both a two-item tracker and a 2,243-item tracker. Its
+cross-call ceilings are strict: complete serialized bytes and cumulative spend
+may only shrink, while repeat suppression may only hold or improve. The gate
+also fixes the expected unique-fact shape:
+
+| Tracker tier | Group spend / budget | Seen items | Suppressed repeats | Delivered bytes |
+| ------------ | -------------------- | ---------- | ------------------ | --------------- |
+| 2 items      | 3,663 / 20,000       | 2          | 3                  | 14,646          |
+| 2,243 items  | 9,999 / 20,000       | 106        | 7                  | 39,985          |
+
+These are deterministic synthetic-corpus measurements from
+`scripts/release/context-intent-calibration.json`; they contain no hosted
+tracker content.
+
 ## Precedence and Compatibility
 
 Resolution is deterministic: canonical controls win over command-local compatibility options, which win over intent defaults, which win over command defaults. Existing options such as `--fields`, `--limit`, `--token-budget`, `--format`, `--brief`, and `--full` remain accepted. Contract output marks them as hidden compatibility aliases and supplies a migration hint; traversal, cursor, side-effect, and streaming controls instead receive an explicit behavior-preservation hint because a static output control cannot replace their semantics. Callers that omit the canonical controls receive the byte-identical established result.
@@ -41,6 +93,13 @@ const result = await pm.list({
   outputInclude: "id,title,status",
   outputLimit: 10,
   outputBudget: 800,
+  outputSession: {
+    version: 1,
+    id: "orientation",
+    token_budget: 4000,
+    spent_tokens: 0,
+    seen_item_ids: [],
+  },
 });
 ```