@unbrained/pm-cli 2026.8.16 → 2026.8.18

package/dist/core/sentry/helpers.js

@@ -4,7 +4,7 @@
  * Integrates Sentry instrumentation and release diagnostics for Helpers.
  */
 
-!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]="ffe56aed-b794-5bf4-99fd-e3c5fe065163")}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]="5e6ba316-b067-51df-abeb-c3e3488a504d")}catch(e){}}();
 import { getSentry } from "./instrument.js";
 import { PmCliError } from "../shared/errors.js";
 import { EXIT_CODE } from "../shared/constants.js";
@@ -236,7 +236,7 @@ export function shouldCaptureCliError(error) {
     }
     if (error instanceof Error &&
         error.name === "AbortError" &&
-        /(?:ctrl\+c|sigint|user[- ]initiated)/i.test(error.message)) {
+        /(?:ctrl\+[cd]|sigint|user[- ]initiated)/i.test(error.message)) {
         return false;
     }
     if (typeof error === "object" &&
@@ -270,4 +270,4 @@ export async function sentryFlush(timeoutMs = 3000) {
     }
 }
 //# sourceMappingURL=helpers.js.map
-//# debugId=ffe56aed-b794-5bf4-99fd-e3c5fe065163
+//# debugId=5e6ba316-b067-51df-abeb-c3e3488a504d

package/dist/core/shared/constants.js

@@ -1,5 +1,5 @@
 
-!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]="36b908f0-ea19-5adc-8ccd-320ad3c3b1fe")}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]="45e1dcb9-d2d6-52d7-b0b0-a57556a3fb03")}catch(e){}}();
 import { createDefaultExtensionGovernancePolicy } from "../extensions/extension-types.js";
 /**
  * Canonical default lifecycle status model and workflow role mapping.
@@ -271,6 +271,9 @@ export const SETTINGS_DEFAULTS = {
     output: {
         default_format: "toon",
     },
+    ux: {
+        deprecation_hints: true,
+    },
     history: {
         missing_stream: "auto_create",
         compact_policy: {
@@ -477,4 +480,4 @@ export function resolveTelemetryErrorCategory(errorCode) {
     return "unknown";
 }
 //# sourceMappingURL=constants.js.map
-//# debugId=36b908f0-ea19-5adc-8ccd-320ad3c3b1fe
+//# debugId=45e1dcb9-d2d6-52d7-b0b0-a57556a3fb03

package/dist/core/shared/errors.d.ts

@@ -63,6 +63,16 @@ export interface PmCliErrorContext {
     measurement_id?: string;
     /** Assurance measurement source kind involved in a refusal, when known. */
     source_kind?: string;
+    /** Source item whose endpoint metadata violated a relationship contract. */
+    source_id?: string;
+    /** Source item creation time used to evaluate a temporal relationship contract. */
+    source_created_at?: string;
+    /** Target item whose endpoint metadata violated a relationship contract. */
+    target_id?: string;
+    /** Target item creation time used to evaluate a temporal relationship contract. */
+    target_created_at?: string;
+    /** Temporal relationship rule evaluated for the source and target. */
+    temporal_order?: string;
     /** Validate or health check selected by an assurance source, when known. */
     check?: string;
     /** Serialization format involved in a parse failure. */

package/dist/core/shared/errors.js

@@ -1,6 +1,6 @@
 /** Implements the exported pm cli error runtime abstraction for core/shared/errors.ts. */
 
-!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]="bf08255e-7ef4-5929-8431-2df83d98d0ba")}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]="c863f07f-428b-5b7f-a5f7-23e7f5fa749a")}catch(e){}}();
 export class PmCliError extends Error {
     /** Value that configures or reports exit code for this contract. */
     exitCode;
@@ -18,4 +18,4 @@ export class PmCliError extends Error {
     }
 }
 //# sourceMappingURL=errors.js.map
-//# debugId=bf08255e-7ef4-5929-8431-2df83d98d0ba
+//# debugId=c863f07f-428b-5b7f-a5f7-23e7f5fa749a

package/dist/core/shared/time.d.ts

@@ -2,6 +2,8 @@
 export declare function nowIso(): string;
 /** Implements check whether timestamp literal for the public runtime surface of this module. */
 export declare function isTimestampLiteral(input: string): boolean;
+/** Return whether a string is a calendar-valid RFC 3339 date-time. */
+export declare function isRfc3339DateTime(input: string): boolean;
 /** Implements compare timestamp strings for the public runtime surface of this module. */
 export declare function compareTimestampStrings(left: string, right: string): number;
 /** Timestamp-bearing record accepted by shared inclusive bound filtering. */

package/dist/core/shared/time.js

@@ -4,7 +4,7 @@
  * Provides shared primitives and utilities for Time.
  */
 
-!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]="6be1497f-a0d5-518b-bf6a-e549b18fad8a")}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]="7887e752-b1b8-5c5e-9dd8-93b41cb757af")}catch(e){}}();
 import { PmCliError } from "./errors.js";
 import { evictOldestMemoEntries } from "./memo.js";
 import { EXIT_CODE } from "./constants.js";
@@ -15,6 +15,7 @@ const COMPACT_DATE = /^(\d{4})(\d{2})(\d{2})$/;
 const COMPACT_DATETIME = /^(\d{4})(\d{2})(\d{2})(?:[T\s]?)(\d{2})(\d{2})(\d{2})?([.,]\d{1,3})?(Z|[+-]\d{2}:?\d{2})?$/i;
 const HYPHEN_TIME = /^(\d{4}-\d{2}-\d{2})[T\s](\d{2})-(\d{2})(?:-(\d{2}))?([.,]\d{1,3})?(Z|[+-]\d{2}:?\d{2})?$/i;
 const COMPACT_TIME = /^(\d{4}-\d{2}-\d{2})[T\s](\d{2})(\d{2})(\d{2})?([.,]\d{1,3})?(Z|[+-]\d{2}:?\d{2})?$/i;
+const RFC_3339_DATE_TIME = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:Z|[+-](\d{2}):(\d{2}))$/i;
 /** Implements now iso for the public runtime surface of this module. */
 export function nowIso() {
     return nextReproducibleTimestamp() ?? new Date().toISOString();
@@ -23,6 +24,30 @@ export function nowIso() {
 export function isTimestampLiteral(input) {
     return Number.isFinite(Date.parse(input));
 }
+/** Return whether a string is a calendar-valid RFC 3339 date-time. */
+export function isRfc3339DateTime(input) {
+    const match = RFC_3339_DATE_TIME.exec(input);
+    if (!match || !Number.isFinite(Date.parse(input)))
+        return false;
+    const [, yearRaw, monthRaw, dayRaw, hourRaw, minuteRaw, secondRaw, offsetHourRaw, offsetMinuteRaw,] = match;
+    const [year, month, day, hour, minute, second] = [
+        yearRaw,
+        monthRaw,
+        dayRaw,
+        hourRaw,
+        minuteRaw,
+        secondRaw,
+    ].map(Number);
+    return (month >= 1 &&
+        month <= 12 &&
+        day >= 1 &&
+        day <= daysInUtcMonth(year, month - 1) &&
+        hour <= 23 &&
+        minute <= 59 &&
+        second <= 59 &&
+        (offsetHourRaw === undefined || Number(offsetHourRaw) <= 23) &&
+        (offsetMinuteRaw === undefined || Number(offsetMinuteRaw) <= 59));
+}
 /**
  * Memoized `Date.parse` for {@link compareTimestampStrings}. Sort comparators call it
  * O(n log n) times over a corpus whose timestamp strings repeat heavily, and
@@ -273,4 +298,4 @@ export const _testOnly = {
     isWhitespaceCharacter,
 };
 //# sourceMappingURL=time.js.map
-//# debugId=6be1497f-a0d5-518b-bf6a-e549b18fad8a
+//# debugId=7887e752-b1b8-5c5e-9dd8-93b41cb757af

package/dist/core/store/settings-validator.d.ts

@@ -35,6 +35,10 @@ export interface ParsedSettings {
     output: {
         default_format: "toon" | "json";
     };
+    /** Agent and human interaction preferences. */
+    ux?: {
+        deprecation_hints?: boolean;
+    };
     /** Value that configures or reports history for this contract. */
     history?: {
         missing_stream: "auto_create" | "strict_error";

package/dist/core/store/settings-validator.js

@@ -12,7 +12,7 @@
  * byte-identical to the previous implementation.
  */
 
-!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]="027f6acb-15cc-5707-85ed-b5298b6b6abe")}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]="8883f930-193e-5133-835a-f15b1b62f6be")}catch(e){}}();
 import { GOVERNANCE_PRESET_VALUES, RUNTIME_FIELD_COMMAND_VALUES, RUNTIME_FIELD_TYPE_VALUES, RUNTIME_STATUS_ROLE_VALUES, RUNTIME_UNKNOWN_FIELD_POLICY_VALUES, } from "../../types.js";
 // Generic over `never` so it is assignable to every `Outcome<T>`.
 const FAIL = { ok: false };
@@ -304,6 +304,7 @@ const settingsCheck = vObject({
         retention_days: vOptional(vNumber({ int: true, positive: true })),
     })),
     output: vObject({ default_format: vLiteral("toon", "json") }),
+    ux: vOptional(vObject({ deprecation_hints: vOptional(vBoolean) })),
     history: vOptional(vObject({
         missing_stream: vLiteral("auto_create", "strict_error"),
         compact_policy: vOptional(vObject({
@@ -414,4 +415,4 @@ export function validateSettings(raw) {
     return { success: true, data: result.value };
 }
 //# sourceMappingURL=settings-validator.js.map
-//# debugId=027f6acb-15cc-5707-85ed-b5298b6b6abe
+//# debugId=8883f930-193e-5133-835a-f15b1b62f6be

package/dist/core/store/settings.js

@@ -4,7 +4,7 @@
  * Reads and writes tracker storage with format-aware helpers for Settings.
  */
 
-!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]="a434b9ea-4692-51c5-8761-0f1759fff394")}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]="67bf189e-e816-536d-9051-589a2e468423")}catch(e){}}();
 import { validateSettings } from "./settings-validator.js";
 import { runActiveOnReadHooks, runActiveOnWriteHooks, } from "../extensions/index.js";
 import { GOVERNANCE_PRESET_DEFAULTS, SETTINGS_DEFAULTS, } from "../shared/constants.js";
@@ -710,6 +710,7 @@ function mergeSettings(settings) {
         },
         checkpoints: { ...defaults.checkpoints, ...settings.checkpoints },
         output: { ...defaults.output, ...settings.output },
+        ux: { ...defaults.ux, ...settings.ux },
         history: {
             ...defaults.history,
             ...settings.history,
@@ -777,6 +778,9 @@ function orderSerializedSettingsSections(ordered) {
     ordered.output = orderObject(ordered.output, [
         "default_format",
     ]);
+    ordered.ux = orderObject(ordered.ux, [
+        "deprecation_hints",
+    ]);
     ordered.history = orderObject(ordered.history, [
         "missing_stream",
         "compact_policy",
@@ -934,6 +938,7 @@ function buildSerializeBaseSettings(settings) {
         mutation_guard: valueOrDefault(settings.mutation_guard, SETTINGS_DEFAULTS.mutation_guard),
         checkpoints: valueOrDefault(settings.checkpoints, SETTINGS_DEFAULTS.checkpoints),
         output: valueOrDefault(settings.output, SETTINGS_DEFAULTS.output),
+        ux: valueOrDefault(settings.ux, SETTINGS_DEFAULTS.ux),
         history: valueOrDefault(settings.history, SETTINGS_DEFAULTS.history),
         validation: valueOrDefault(settings.validation, SETTINGS_DEFAULTS.validation),
         workflow: valueOrDefault(settings.workflow, SETTINGS_DEFAULTS.workflow),
@@ -1084,6 +1089,7 @@ const SETTINGS_TOP_LEVEL_KEY_ORDER = [
     "locks",
     "checkpoints",
     "output",
+    "ux",
     "history",
     "validation",
     "governance",
@@ -1298,4 +1304,4 @@ export const settingsStoreTestOnly = {
     selectedSettingsReadCacheSignaturesEqual,
 };
 //# sourceMappingURL=settings.js.map
-//# debugId=a434b9ea-4692-51c5-8761-0f1759fff394
+//# debugId=67bf189e-e816-536d-9051-589a2e468423

package/dist/mcp/tool-definitions.js

@@ -4,8 +4,8 @@
  * Defines the Tool Definitions module for pm CLI source.
  */
 
-!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]="d440a41a-ae54-55fd-b939-5404a1edcdd7")}catch(e){}}();
-import { GRAPH_SUBCOMMAND_VALUES, PM_TOOL_ACTIONS, } from "../sdk/cli-contracts/enum-contracts.js";
+!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]="90896fb6-ee3e-575d-b103-bbc1a83c6672")}catch(e){}}();
+import { GRAPH_SUBCOMMAND_VALUES, PM_DISCOVERABLE_TOOL_ACTIONS, } from "../sdk/cli-contracts/enum-contracts.js";
 import { buildPmActionToolInputSchema } from "../sdk/cli-contracts/tool-schema.js";
 import { RUNTIME_STATUS_ROLE_VALUES } from "../types.js";
 const CANONICAL_OUTPUT_SESSION_TOOL_PROPERTY = buildPmActionToolInputSchema("list").properties.outputSession;
@@ -65,9 +65,9 @@ const idSchema = {
     description: "pm item id, for example pm-abc1.",
 };
 // pm-fd8n: derive the pm_run action enumeration from the canonical
-// PM_TOOL_ACTIONS contract instead of a hand-maintained prose list, so the
+// PM_DISCOVERABLE_TOOL_ACTIONS contract instead of a hand-maintained prose list, so the
 // MCP-facing description can never drift from the actual supported actions.
-const PM_RUN_ACTION_DESCRIPTION = `Operation name (one of): ${PM_TOOL_ACTIONS.join(", ")}. ` +
+const PM_RUN_ACTION_DESCRIPTION = `Operation name (one of): ${PM_DISCOVERABLE_TOOL_ACTIONS.join(", ")}. ` +
     "Package-owned actions are available dynamically when their provider package is installed.";
 const LIST_TOP_LEVEL_OPTION_PROPERTIES = {
     status: { type: "string", description: "Alias for options.status." },
@@ -111,7 +111,7 @@ const RAW_TOOLS = [
         inputSchema: objectSchema({
             action: {
                 type: "string",
-                enum: [...PM_TOOL_ACTIONS],
+                enum: [...PM_DISCOVERABLE_TOOL_ACTIONS],
                 description: PM_RUN_ACTION_DESCRIPTION,
             },
             id: idSchema,
@@ -209,7 +209,7 @@ const RAW_TOOLS = [
     },
     {
         name: "pm_events",
-        description: "Read a bounded, cursor-resumable page of committed mutation events across item history streams.",
+        description: "Read a bounded, cursor-resumable page of committed mutation events across item history streams. Batch cursors are the token-efficient default; pass cursorMode=row for per-event checkpoints.",
         inputSchema: objectSchema({
             since: {
                 type: "string",
@@ -235,6 +235,11 @@ const RAW_TOOLS = [
             },
             limit: { type: "integer", minimum: 0, maximum: 1000 },
             full: { type: "boolean" },
+            cursorMode: {
+                type: "string",
+                enum: ["batch", "row"],
+                description: "Cursor framing: batch returns one terminal next_cursor (default); row also adds a cursor to every event.",
+            },
         }),
     },
     {
@@ -743,4 +748,4 @@ export function buildMcpToolContracts() {
     }).sort((left, right) => left.name.localeCompare(right.name));
 }
 //# sourceMappingURL=tool-definitions.js.map
-//# debugId=d440a41a-ae54-55fd-b939-5404a1edcdd7
+//# debugId=90896fb6-ee3e-575d-b103-bbc1a83c6672

package/dist/sdk/agent/refusal-reachability.d.ts

@@ -1,9 +1,3 @@
-/**
- * @module sdk/agent/refusal-reachability
- *
- * Verifies real-entrypoint observations against refusal states declared by the
- * generated public error-code catalog.
- */
 import type { PmErrorCodeContract, PmErrorCodeClass } from "../error-code-catalog.js";
 /** One recorded result from driving a real public entrypoint into a refusal. */
 export interface PmRefusalProbeObservation {
@@ -42,6 +36,50 @@ export declare const PM_RECOVERY_REFERENCE_KINDS: readonly ["suggested_retry", "
 export type PmRecoveryReferenceKind = (typeof PM_RECOVERY_REFERENCE_KINDS)[number];
 /** Behavioral promise attached to a recovery reference. */
 export type PmRecoveryReferenceSemantics = "recovery" | "replacement" | "behavior_preserving";
+/** Literal envelope fields recognized as recovery-reference producers. */
+export declare const PM_RECOVERY_REFERENCE_FIELDS: readonly ("restore_with" | "migration_hint" | "migration_hints" | "suggested_retry" | "next_best_command" | "fallback_candidates" | "examples" | "next_steps" | "suggested_next_steps" | "candidate_commands" | "candidate_command" | "example" | "next_step" | "retry_command")[];
+/** One source file supplied to the producer-census analyzer. */
+export interface PmRecoveryProducerSource {
+    /** Repository-relative source path. */
+    path: string;
+    /** Complete source text. */
+    content: string;
+}
+/** One literal recovery field emitted from a source location. */
+export interface PmRecoveryProducerLocation {
+    /** Repository-relative producer source path. */
+    path: string;
+    /** One-based source line. */
+    line: number;
+    /** Literal structured-envelope field. */
+    field: (typeof PM_RECOVERY_REFERENCE_FIELDS)[number];
+    /** Normalized recovery kind. */
+    kind: PmRecoveryReferenceKind;
+}
+/** Producer-census failure that requires a new field contract or producer. */
+export interface PmRecoveryProducerCensusFinding {
+    /** Stable finding kind. */
+    kind: "invalid_source" | "missing_kind_producer" | "unknown_recovery_field";
+    /** Source path or normalized kind. */
+    subject: string;
+    /** Actionable explanation. */
+    detail: string;
+}
+/** Complete literal producer-table census for recovery references. */
+export interface PmRecoveryProducerCensusReport {
+    /** Whether every recovery kind has a producer and no unknown fields exist. */
+    ok: boolean;
+    /** Source files inspected. */
+    scanned_file_count: number;
+    /** Literal producer locations. */
+    producer_count: number;
+    /** Stable counts by normalized recovery kind. */
+    producer_count_by_kind: Record<PmRecoveryReferenceKind, number>;
+    /** Stable producer locations. */
+    producers: PmRecoveryProducerLocation[];
+    /** Missing-kind or unknown-field findings. */
+    findings: PmRecoveryProducerCensusFinding[];
+}
 /** One derived promise that another invocation or command path is reachable. */
 export interface PmRecoveryReferenceObligation {
     /** Stable reference identifier derived from its emitting envelope. */
@@ -101,6 +139,8 @@ export interface PmRecoveryReferenceReport {
     /** Stable, sorted conformance findings. */
     findings: PmRecoveryReferenceFinding[];
 }
+/** Census syntax-parsed structured-envelope producers without executing source code. */
+export declare function censusPmRecoveryReferenceProducers(sources: readonly PmRecoveryProducerSource[]): PmRecoveryProducerCensusReport;
 /** Derive typed obligations from every recognized recovery field in an emitted envelope. */
 export declare function derivePmRecoveryReferenceObligations(probeId: string, envelope: unknown): PmRecoveryReferenceObligation[];
 /** Compare declared refusal states with real-entrypoint observations. */