@unbrained/pm-cli 2026.9.4 → 2026.9.6

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

@@ -7,7 +7,7 @@
  * consumers from a single source of truth.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="b81a68c1-565d-56f6-a0eb-35d2c737bdb7")}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]="e72f4ab4-5bf7-53fb-a3a3-174c4064f6a4")}catch(e){}}();
 import { normalizeUniqueStringList } from "./string-lists.js";
 import { PM_TOOL_ACTIONS } from "./enum-contracts.js";
 import { TOOL_CREATE_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_MANY_FILTER_OPTION_CONTRACTS, TOOL_CONTEXT_OPTION_CONTRACTS, TOOL_ACTIVITY_OPTION_CONTRACTS, TOOL_LIST_FILTER_OPTION_CONTRACTS, TOOL_AGGREGATE_OPTION_CONTRACTS, TOOL_SEARCH_FILTER_OPTION_CONTRACTS, TOOL_CLOSE_MANY_FILTER_OPTION_CONTRACTS, } from "./tool-option-contracts.js";
@@ -216,7 +216,6 @@ const LIST_CONTRACT_PARAMETER_KEYS = toSchemaKeyList([
     "full",
 ]);
 const FIXED_STATUS_LIST_CONTRACT_PARAMETER_KEYS = LIST_CONTRACT_PARAMETER_KEYS.filter((parameter) => parameter !== "all" && parameter !== "status");
-const ALL_STATUS_LIST_CONTRACT_PARAMETER_KEYS = LIST_CONTRACT_PARAMETER_KEYS.filter((parameter) => parameter !== "status");
 const LIST_WINDOW_MUTUALLY_EXCLUSIVE_GROUPS = [
     [
         { property: "today", schema: { const: true } },
@@ -291,6 +290,8 @@ const NEXT_CONTRACT_PARAMETER_KEYS = toSchemaKeyList([
     "readyOnly",
     "format",
     "includeDecisions",
+    "includeGates",
+    "includeContainers",
     "tokenBudget",
     "explainRanking",
 ]);
@@ -482,7 +483,7 @@ const PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
         mutuallyExclusiveWhen: LIST_WINDOW_MUTUALLY_EXCLUSIVE_GROUPS,
     },
     "list-all": {
-        optional: ALL_STATUS_LIST_CONTRACT_PARAMETER_KEYS,
+        optional: LIST_CONTRACT_PARAMETER_KEYS,
         mutuallyExclusiveWhen: LIST_WINDOW_MUTUALLY_EXCLUSIVE_GROUPS,
     },
     "list-draft": {
@@ -643,9 +644,20 @@ const PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
             "all",
             "dryRun",
             "normalizeProvenance",
+            "salvageTail",
             ...AUTHOR_MESSAGE_FORCE_PARAMETER_KEYS,
         ],
         oneOfRequired: [["id"], ["all"]],
+        mutuallyExclusiveWhen: [
+            [
+                { property: "salvageTail", schema: { const: true } },
+                { property: "all", schema: { const: true } },
+            ],
+            [
+                { property: "salvageTail", schema: { const: true } },
+                { property: "normalizeProvenance", schema: { const: true } },
+            ],
+        ],
     },
     "history-author-acknowledge": {
         optional: [
@@ -1001,6 +1013,7 @@ const PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
     test: {
         required: ["id"],
         optional: [
+            "list",
             "add",
             "addJson",
             "remove",
@@ -1110,7 +1123,7 @@ const PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
         ],
     },
     duplicates: {
-        optional: ["status", "since", "threshold", "limit"],
+        optional: ["status", "since", "threshold", "limit", "exhaustive"],
     },
     health: {
         optional: [
@@ -1195,12 +1208,24 @@ const PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
                 required: ["preset", "owner"],
             },
             { property: "subcommand", value: "derive", required: ["owner"] },
+            { property: "subcommand", value: "risk", required: ["definition"] },
+            { property: "subcommand", value: "lineages", required: ["definition"] },
             {
                 property: "subcommand",
                 value: "promote",
                 required: ["id", "enforcement"],
             },
         ],
+        mutuallyExclusiveWhen: [
+            [
+                { property: "subcommand", schema: { const: "risk" } },
+                { property: "definition", schema: { not: { required: ["policy", "change"] } } },
+            ],
+            [
+                { property: "subcommand", schema: { const: "lineages" } },
+                { property: "definition", schema: { anyOf: [{ required: ["change"] }, { not: { required: ["policy"] } }] } },
+            ],
+        ],
     },
     gc: { optional: ["dryRun", "gcScope"] },
     contracts: {
@@ -1555,14 +1580,14 @@ function createLazyContractSchema(build) {
     });
 }
 /** Canonical version of the action-scoped strict MCP tool-parameters schema (`PM_TOOL_PARAMETERS_SCHEMA`). Exported as the single source of truth so the MCP server, the `pm contracts` command, SDK consumers, and contract tests bind to one version constant. Bump the patch/minor for additive, backward-compatible schema changes; bump the MAJOR for breaking changes — the major also drives the `$id` `tool-parameters-v{major}` slug, so the two never drift. */
-export const PM_TOOL_PARAMETERS_SCHEMA_VERSION = "4.10.1";
+export const PM_TOOL_PARAMETERS_SCHEMA_VERSION = "4.14.0";
 /**
  * Major component of {@link PM_TOOL_PARAMETERS_SCHEMA_VERSION}, used to build the
  * schema `$id` slug so a breaking version bump renames the document in lockstep.
  */
 export const PM_TOOL_PARAMETERS_SCHEMA_MAJOR = PM_TOOL_PARAMETERS_SCHEMA_VERSION.split(".")[0];
 /** Version of the provider-compatible flat tool-parameters schema (`PM_PROVIDER_TOOL_PARAMETERS_SCHEMA`). Tracked separately from the strict schema because the flat projection evolves independently. */
-export const PM_PROVIDER_TOOL_PARAMETERS_SCHEMA_VERSION = "1.4.0";
+export const PM_PROVIDER_TOOL_PARAMETERS_SCHEMA_VERSION = "1.7.0";
 /** Public contract for pm tool parameters schema, shared by SDK and presentation-layer consumers. */
 export const PM_TOOL_PARAMETERS_SCHEMA = createLazyContractSchema(() => ({
     $schema: "https://json-schema.org/draft/2020-12/schema",
@@ -1637,4 +1662,4 @@ export const _testOnlyCliContracts = {
     withFlagAliasMetadata,
 };
 //# sourceMappingURL=tool-schema.js.map
-//# debugId=b81a68c1-565d-56f6-a0eb-35d2c737bdb7
+//# debugId=e72f4ab4-5bf7-53fb-a3a3-174c4064f6a4

package/dist/sdk/context/usage-ledger.d.ts

@@ -0,0 +1,41 @@
+import type { ContextUsageEvent, ContextUsageLedgerOptions } from "../context-usage.js";
+/** Public storage and sampling ceilings shared by every feedback producer. */
+export declare const CONTEXT_USAGE_LIMITS: {
+    readonly max_serving_rows: 256;
+    readonly max_bytes: 262144;
+    readonly max_event_bytes: 32768;
+    readonly retained_byte_fraction: 0.5;
+    readonly max_events: 2048;
+    readonly retention_days: 30;
+};
+/** Measured persistence work for one lock-protected feedback write. */
+export interface ContextUsageWriteReceipt {
+    /** Bytes written to the append or replacement file; excludes lock metadata. */
+    written_bytes: number;
+    /** Physical ledger size at the end of the protected write. */
+    ledger_bytes: number;
+    /** Whether this write replaced the ledger with a retained suffix. */
+    compacted: boolean;
+    /** Wall-clock time waiting to acquire the cross-process ledger lock. */
+    lock_wait_ms: number;
+}
+/** Named validation failure emitted by context-usage SDK inputs. */
+export declare class ContextUsageValidationError extends TypeError {
+    /** Stable code for package and CLI hosts. */
+    readonly code = "context_usage_validation_failed";
+    /** Reject invalid feedback controls without exposing ledger contents. */
+    constructor(message: string);
+}
+/** Normalize one timestamp so filtering and serialization share the same clock. */
+export declare function resolveNow(options: ContextUsageLedgerOptions): {
+    iso: string;
+    ms: number;
+};
+/** Read only a bounded file suffix, dropping a partial first JSONL row. */
+export declare function readEvents(options: ContextUsageLedgerOptions): Promise<ContextUsageEvent[]>;
+/**
+ * Append once, or compact atomically to a half-full suffix at the high-water mark.
+ * Requires trusted, stable workspace directory entries and ancestors; the lock
+ * coordinates cooperating writers and cannot constrain hostile path replacement.
+ */
+export declare function appendEvents(options: ContextUsageLedgerOptions, events: readonly ContextUsageEvent[], deliveryServeId?: string): Promise<ContextUsageWriteReceipt>;

package/dist/sdk/context/usage-ledger.js

@@ -0,0 +1,186 @@
+/**
+ * @module sdk/context/usage-ledger
+ *
+ * Bounds derived feedback reads and writes in bytes. High-water compaction
+ * retains a half-full suffix under the same lock as append, leaving headroom
+ * for subsequent serves without rewriting on every context request.
+ */
+
+!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]="f3af7f8f-a462-5eb4-af08-c64c3c327e62")}catch(e){}}();
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, rename, rm } from "node:fs/promises";
+import path from "node:path";
+import { isFileMissingError } from "../../core/fs/fs-utils.js";
+import { acquireLock } from "../../core/lock/lock.js";
+/** Public storage and sampling ceilings shared by every feedback producer. */
+export const CONTEXT_USAGE_LIMITS = {
+    max_serving_rows: 256,
+    max_bytes: 262_144,
+    max_event_bytes: 32_768,
+    retained_byte_fraction: 0.5,
+    max_events: 2_048,
+    retention_days: 30,
+};
+/** Named validation failure emitted by context-usage SDK inputs. */
+export class ContextUsageValidationError extends TypeError {
+    /** Stable code for package and CLI hosts. */
+    code = "context_usage_validation_failed";
+    /** Reject invalid feedback controls without exposing ledger contents. */
+    constructor(message) {
+        super(message);
+        this.name = "ContextUsageValidationError";
+    }
+}
+/** Normalize one timestamp so filtering and serialization share the same clock. */
+export function resolveNow(options) {
+    const ms = Date.parse(options.now ?? new Date().toISOString());
+    if (!Number.isFinite(ms))
+        throw new ContextUsageValidationError("Context usage now must be a valid timestamp");
+    return { iso: new Date(ms).toISOString(), ms };
+}
+/** Resolve checked byte, count and time bounds before touching storage. */
+function bounds(options) {
+    const maxBytes = options.maxBytes ?? CONTEXT_USAGE_LIMITS.max_bytes;
+    const maxEvents = options.maxEvents ?? CONTEXT_USAGE_LIMITS.max_events;
+    const retentionDays = options.retentionDays ?? CONTEXT_USAGE_LIMITS.retention_days;
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1024 || maxBytes > CONTEXT_USAGE_LIMITS.max_bytes ||
+        !Number.isSafeInteger(maxEvents) || maxEvents < 1 || !Number.isFinite(retentionDays) || retentionDays <= 0) {
+        throw new ContextUsageValidationError("Context usage retention requires positive maxEvents and retentionDays, and maxBytes from 1024 through 262144");
+    }
+    return { maxBytes, maxEvents, cutoff: resolveNow(options).ms - retentionDays * 86_400_000 };
+}
+/** Open only a private regular ledger, refusing redirected runtime directories and file links. */
+async function openLedger(target, flags) {
+    if (!(await lstat(path.dirname(target))).isDirectory()) {
+        throw new ContextUsageValidationError("Context usage runtime must be a real directory");
+    }
+    try {
+        if ((await lstat(target)).isSymbolicLink()) {
+            throw new ContextUsageValidationError("Context usage ledger must not be a symbolic link");
+        }
+    }
+    catch (error) {
+        if (!isFileMissingError(error))
+            throw error;
+    }
+    // Unsupported platform flags contribute zero to the numeric bit mask. The
+    // lstat check also rejects existing links where no-follow is unavailable.
+    const handle = await open(target, flags | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o600);
+    try {
+        const metadata = await handle.stat();
+        if (!metadata.isFile() || metadata.nlink !== 1) {
+            throw new ContextUsageValidationError("Context usage ledger must be an unshared regular file");
+        }
+        return handle;
+    }
+    catch (error) {
+        await handle.close();
+        throw error;
+    }
+}
+/** Read only a bounded file suffix, dropping a partial first JSONL row. */
+export async function readEvents(options) {
+    const policy = bounds(options);
+    try {
+        const handle = await openLedger(path.join(options.pmRoot, "runtime", "context-usage.jsonl"), constants.O_RDONLY);
+        try {
+            const size = (await handle.stat()).size;
+            const start = Math.max(0, size - policy.maxBytes);
+            const buffer = Buffer.alloc(Math.min(size, policy.maxBytes));
+            const { bytesRead } = await handle.read(buffer, 0, buffer.length, start);
+            const text = buffer.subarray(0, bytesRead).toString("utf8");
+            const lines = (start > 0 ? (text.includes("\n") ? text.slice(text.indexOf("\n") + 1) : "") : text).split("\n");
+            return lines.flatMap((line) => {
+                try {
+                    const event = JSON.parse(line);
+                    return event && Date.parse(event.at) >= policy.cutoff ? [event] : [];
+                }
+                catch {
+                    return [];
+                }
+            }).slice(-policy.maxEvents);
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch {
+        return [];
+    }
+}
+/** Retain a contiguous newest suffix within both byte and event-count bounds. */
+function retainedText(events, byteLimit, maxEvents) {
+    const lines = [];
+    let bytes = 0;
+    for (let index = events.length - 1; index >= 0 && lines.length < maxEvents; index -= 1) {
+        const line = `${JSON.stringify(events[index])}\n`;
+        bytes += Buffer.byteLength(line);
+        if (bytes > byteLimit)
+            break;
+        lines.push(line);
+    }
+    return lines.reverse().join("");
+}
+/**
+ * Append once, or compact atomically to a half-full suffix at the high-water mark.
+ * Requires trusted, stable workspace directory entries and ancestors; the lock
+ * coordinates cooperating writers and cannot constrain hostile path replacement.
+ */
+export async function appendEvents(options, events, deliveryServeId) {
+    const policy = bounds(options);
+    const target = path.join(options.pmRoot, "runtime", "context-usage.jsonl");
+    const retainedBytes = Math.floor(policy.maxBytes * CONTEXT_USAGE_LIMITS.retained_byte_fraction);
+    const eventLimit = Math.min(CONTEXT_USAGE_LIMITS.max_event_bytes, retainedBytes);
+    if (events.some((event) => Buffer.byteLength(`${JSON.stringify(event)}\n`) > eventLimit)) {
+        throw new ContextUsageValidationError("Context usage event exceeds the declared byte ceiling");
+    }
+    const current = events.filter((event) => Date.parse(event.at) >= policy.cutoff);
+    const appended = retainedText(current, retainedBytes, policy.maxEvents);
+    const lockStarted = performance.now();
+    const releaseLock = await acquireLock(options.pmRoot, "context-usage-ledger", 30, `context-usage:${process.pid}`, false, false, 3_000);
+    const lockWaitMs = performance.now() - lockStarted;
+    try {
+        await mkdir(path.dirname(target), { recursive: true });
+        let handle = await openLedger(target, constants.O_WRONLY | constants.O_CREAT | constants.O_APPEND);
+        try {
+            const size = (await handle.stat()).size;
+            const previous = deliveryServeId === undefined ? undefined : await readEvents(options);
+            if (previous?.some((event) => event.kind === "delivery" && event.serve_id === deliveryServeId)) {
+                return { written_bytes: 0, ledger_bytes: size, compacted: false, lock_wait_ms: lockWaitMs };
+            }
+            const customRetention = options.maxEvents !== undefined || options.retentionDays !== undefined;
+            if (!customRetention && size + Buffer.byteLength(appended) <= policy.maxBytes) {
+                await handle.writeFile(appended, "utf8");
+                return { written_bytes: Buffer.byteLength(appended), ledger_bytes: size + Buffer.byteLength(appended), compacted: false, lock_wait_ms: lockWaitMs };
+            }
+            const retained = retainedText([...(previous ?? await readEvents(options)), ...current], retainedBytes, policy.maxEvents);
+            const temporary = `${target}.${process.pid}.${randomUUID()}.tmp`;
+            const replacement = await open(temporary, "wx", 0o600);
+            try {
+                try {
+                    await replacement.writeFile(retained, "utf8");
+                }
+                finally {
+                    await replacement.close();
+                }
+                // Windows cannot replace the destination while our append handle is open.
+                await handle.close();
+                handle = undefined;
+                await rename(temporary, target);
+                return { written_bytes: Buffer.byteLength(retained), ledger_bytes: Buffer.byteLength(retained), compacted: true, lock_wait_ms: lockWaitMs };
+            }
+            finally {
+                await rm(temporary, { force: true });
+            }
+        }
+        finally {
+            await handle?.close();
+        }
+    }
+    finally {
+        await releaseLock();
+    }
+}
+//# sourceMappingURL=usage-ledger.js.map
+//# debugId=f3af7f8f-a462-5eb4-af08-c64c3c327e62

package/dist/sdk/context-intent-contracts.js

@@ -5,7 +5,7 @@
  * workspace configuration, and packages.
  */
 
-!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]="5dc9c6e4-6db8-560f-a87f-368132e2ffb3")}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]="d6fc4c70-c955-5fb5-ab4b-5dfa1200d58d")}catch(e){}}();
 import { AsyncLocalStorage } from "node:async_hooks";
 import { renderPmCommand } from "./command-line.js";
 import { attachOutputOmissionReceipt } from "./output-projection.js";
@@ -410,7 +410,7 @@ const CONTEXT_INTENT_ROW_KEYS = {
     ],
     get: ["children"],
     list: ["items"],
-    next: ["ready", "decision_needed", "blocked", "held_by_others"],
+    next: ["ready", "decision_needed", "gate_needed", "containers", "blocked", "held_by_others"],
     search: ["items"],
 };
 /** Decode the cursor fields required to preserve a row-compacted continuation. */
@@ -707,4 +707,4 @@ export function attachReadOutputContracts(command, options, result) {
     return suppressed;
 }
 //# sourceMappingURL=context-intent-contracts.js.map
-//# debugId=5dc9c6e4-6db8-560f-a87f-368132e2ffb3
+//# debugId=d6fc4c70-c955-5fb5-ab4b-5dfa1200d58d

package/dist/sdk/context-usage.d.ts

@@ -1,3 +1,5 @@
+import { type ContextUsageWriteReceipt } from "./context/usage-ledger.js";
+export { ContextUsageValidationError, CONTEXT_USAGE_LIMITS, type ContextUsageWriteReceipt } from "./context/usage-ledger.js";
 import type { ContextRelevanceSurface } from "./context-relevance.js";
 /** One propensity row disclosed when context or next serves a candidate. */
 export interface ContextUsageServingRow {
@@ -18,6 +20,10 @@ export interface ContextUsageServingReceipt {
     surface: ContextRelevanceSurface;
     /** Propensity-complete ranked rows assembled before egress. */
     rows: readonly ContextUsageServingRow[];
+    /** Persisted sample identities; absent on legacy unsampled receipts. */
+    recorded_item_ids?: readonly string[];
+    /** Measured bounded persistence; absent on legacy receipts. */
+    storage?: ContextUsageWriteReceipt;
 }
 /** Append-only serving or subsequent-touch event. */
 export type ContextUsageEvent = {
@@ -29,6 +35,10 @@ export type ContextUsageEvent = {
     surface: ContextRelevanceSurface;
     profile: string;
     rows: ContextUsageServingRow[];
+    /** Full candidate population before deterministic prefix sampling. */
+    candidate_count?: number;
+    /** Candidate rows excluded from this bounded feedback sample. */
+    omitted_row_count?: number;
     result_omitted?: boolean;
     packed_item_ids?: string[];
     /** Legacy pre-egress field ignored by the v2 affinity fold. */
@@ -51,12 +61,18 @@ export type ContextUsageEvent = {
 };
 /** Runtime controls for the bounded derived ledger. */
 export interface ContextUsageLedgerOptions {
-    /** Tracker root containing the runtime directory. */
+    /**
+     * Tracker root containing the runtime directory. Its directory entries and
+     * ancestors must remain controlled by trusted cooperating processes during
+     * ledger operations; hostile concurrent path replacement is unsupported.
+     */
     pmRoot: string;
     /** Disable all reads and writes with zero filesystem work. */
     enabled?: boolean;
     /** Maximum retained event rows. */
     maxEvents?: number;
+    /** Physical byte ceiling; compaction retains at most half to provide headroom. */
+    maxBytes?: number;
     /** Retention horizon in days. */
     retentionDays?: number;
     /** Deterministic timestamp override. */
@@ -90,14 +106,7 @@ export declare function finalizeContextUsageDelivery(options: {
     /** Final projected response returned or rendered to the caller. */
     result: unknown;
 }): Promise<boolean>;
-/** Named validation failure emitted by context-usage SDK inputs. */
-export declare class ContextUsageValidationError extends TypeError {
-    /** Stable machine-readable error code for package and CLI hosts. */
-    readonly code = "context_usage_validation_failed";
-    /** Creates a typed validation error without exposing derived ledger contents. */
-    constructor(message: string);
-}
-/** Records a propensity-complete context/next serving event. */
+/** Records a bounded prefix of ranked context candidates with explicit sampling counts. */
 export declare function recordContextUsageServing(options: ContextUsageLedgerOptions & {
     author: string;
     surface: ContextRelevanceSurface;