@unbrained/pm-cli 2026.8.17 → 2026.8.19

package/dist/core/extensions/exporter-output-contract.js

@@ -0,0 +1,67 @@
+
+!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]="057f439e-ac5c-5715-9fd0-4410e003d481")}catch(e){}}();
+import { cloneContextSnapshot } from "./extension-runtime-helpers.js";
+import { asRegistrationRecord, assertOptionalStringField, } from "./registration-validation.js";
+/** Validates and normalizes the public artifact-channel metadata for one exporter registration. */
+export function normalizeExporterArtifactOutput(value) {
+    const candidate = asRegistrationRecord("registerExporter options.output", value);
+    const allowedKeys = new Set(["channel", "receipt", "media_type"]);
+    for (const key of Object.keys(candidate)) {
+        if (!allowedKeys.has(key)) {
+            throw new TypeError(`registerExporter options.output contains unsupported field ${key}`);
+        }
+    }
+    if (candidate.channel !== "stdout" && candidate.channel !== "file") {
+        throw new TypeError("registerExporter options.output.channel must be stdout|file");
+    }
+    if (candidate.receipt !== undefined &&
+        candidate.receipt !== "suppress" &&
+        candidate.receipt !== "render") {
+        throw new TypeError("registerExporter options.output.receipt must be suppress|render");
+    }
+    if (candidate.channel === "stdout" && candidate.receipt === "render") {
+        throw new TypeError("registerExporter stdout artifacts cannot render a host receipt");
+    }
+    assertOptionalStringField("registerExporter options.output.media_type", candidate.media_type);
+    return {
+        channel: candidate.channel,
+        receipt: candidate.receipt ??
+            (candidate.channel === "stdout" ? "suppress" : "render"),
+        ...(typeof candidate.media_type === "string"
+            ? { media_type: candidate.media_type }
+            : {}),
+    };
+}
+/** Enforces importer/exporter channel ownership and applies the stdout-specific derived description. */
+export function resolveImportExportArtifactOutput(method, resolvedOptions, descriptionWasDeclared) {
+    if (method === "registerImporter" && resolvedOptions.output !== undefined) {
+        throw new TypeError("registerImporter options.output is exporter-only");
+    }
+    if (method !== "registerExporter" || resolvedOptions.output === undefined) {
+        return undefined;
+    }
+    const output = normalizeExporterArtifactOutput(resolvedOptions.output);
+    if (!descriptionWasDeclared && output.channel === "stdout") {
+        resolvedOptions.description =
+            "Export items with the registered extension adapter. Artifact bytes are written exclusively to stdout and the host receipt is suppressed by default.";
+    }
+    return output;
+}
+/** Snapshots a host command invocation into the stable importer/exporter context contract. */
+export function buildImportExportContext(context, registration, action) {
+    return {
+        registration,
+        action,
+        command: context.command,
+        args: cloneContextSnapshot(context.args),
+        options: cloneContextSnapshot(context.options),
+        global: cloneContextSnapshot(context.global),
+        pm_root: context.pm_root,
+        source_workspace_root: context.source_workspace_root,
+        repo_root: context.repo_root,
+        pm_root_rel: context.pm_root_rel,
+        ...(context.sdk === undefined ? {} : { sdk: context.sdk }),
+    };
+}
+//# sourceMappingURL=exporter-output-contract.js.map
+//# debugId=057f439e-ac5c-5715-9fd0-4410e003d481

package/dist/core/extensions/extension-types.d.ts

@@ -715,6 +715,39 @@ export interface ImportExportRegistrationOptions {
     /** Value that configures or reports flags for this contract. */
     flags?: FlagDefinition[];
 }
+/**
+ * Declares where an exporter writes its artifact and whether the host may
+ * render the returned structured receipt after the exporter completes.
+ */
+export type ExporterArtifactOutputContract = {
+    /** Stdout exclusively carries artifact bytes. */
+    channel: "stdout";
+    /** Stdout artifacts cannot opt back into host rendering. */
+    receipt?: "suppress";
+    /** Optional IANA media type describing the emitted artifact. */
+    media_type?: string;
+} | {
+    /** The exporter writes its artifact to a file. */
+    channel: "file";
+    /** File exporters may render or suppress their bounded receipt. */
+    receipt?: "suppress" | "render";
+    /** Optional IANA media type describing the emitted artifact. */
+    media_type?: string;
+};
+/** Exporter command metadata plus its optional artifact-delivery contract. */
+export interface ExporterRegistrationOptions extends ImportExportRegistrationOptions {
+    /** Declaration for artifact bytes and the host receipt. */
+    output?: ExporterArtifactOutputContract;
+}
+/** Fully normalized exporter artifact contract stored in inventories. */
+export interface RegisteredExporterArtifactOutputContract {
+    /** Destination carrying the artifact bytes. */
+    channel: "stdout" | "file";
+    /** Explicit host receipt policy after normalization. */
+    receipt: "suppress" | "render";
+    /** Optional IANA media type describing the emitted artifact. */
+    media_type?: string;
+}
 /** Restricts flag value type values accepted by command, SDK, and storage contracts. */
 export type FlagValueType = "string" | "number" | "boolean";
 /** Documents the flag definition payload exchanged by command, SDK, and package integrations. */
@@ -1288,6 +1321,8 @@ export interface RegisteredExtensionExporter {
     name: string;
     /** Value that configures or reports exporter for this contract. */
     exporter: string;
+    /** Declared artifact channel and normalized receipt policy. */
+    output?: RegisteredExporterArtifactOutputContract;
 }
 /** Documents the registered extension search provider payload exchanged by command, SDK, and package integrations. */
 export interface RegisteredExtensionSearchProvider {
@@ -1447,7 +1482,7 @@ export interface ExtensionApi {
     /** Value that configures or reports register importer for this contract. */
     registerImporter(name: string, importer: Importer, options?: ImportExportRegistrationOptions): void;
     /** Value that configures or reports register exporter for this contract. */
-    registerExporter(name: string, exporter: Exporter, options?: ImportExportRegistrationOptions): void;
+    registerExporter(name: string, exporter: Exporter, options?: ExporterRegistrationOptions): void;
     /** Value that configures or reports register search provider for this contract. */
     registerSearchProvider(provider: SearchProviderDefinition): void;
     /** Value that configures or reports register vector store adapter for this contract. */

package/dist/core/extensions/extension-types.js

@@ -1,6 +1,6 @@
 /** Public contract for known extension capabilities, shared by SDK and presentation-layer consumers. */
 
-!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]="294f3a0c-e74d-5963-b966-8a4443855ce3")}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]="a54549aa-2f6c-5092-a3eb-5b36ee698ea4")}catch(e){}}();
 export const KNOWN_EXTENSION_CAPABILITIES = [
     "commands",
     "renderers",
@@ -100,4 +100,4 @@ export function createDefaultExtensionGovernancePolicy() {
     };
 }
 //# sourceMappingURL=extension-types.js.map
-//# debugId=294f3a0c-e74d-5963-b966-8a4443855ce3
+//# debugId=a54549aa-2f6c-5092-a3eb-5b36ee698ea4

package/dist/core/extensions/loader.js

@@ -4,12 +4,13 @@
  * Implements extension runtime contracts and governance for Loader.
  */
 
-!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]="c88047fc-2bbd-5781-96a8-01685c06fb33")}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]="cccce7c1-dd08-5c9f-a74e-e639536b9a6a")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { pathExists } from "../fs/fs-utils.js";
 import { isPathWithinDirectory } from "../fs/path-utils.js";
+import { isHostOutputSuppressed, suppressHostOutput, } from "../output/output-control.js";
 import { resolvePmPackageRootFromModule } from "../packages/root.js";
 import { resolveGlobalPmRoot } from "../store/paths.js";
 import { asRecordLoose, resolveActivatablePropertyRecord, } from "../shared/primitives.js";
@@ -19,6 +20,7 @@ import { snapshotExtensionModuleGraph } from "./module-graph-snapshot.js";
 import { captureExtensionActivationRollback } from "./activation-transaction.js";
 import { collectPreflightCollisionWarnings, normalizePreflightOverride, } from "./preflight-ownership.js";
 import { assertCommandDefinitionMetadataStrings } from "./command-visibility-tier.js";
+import { buildImportExportContext, resolveImportExportArtifactOutput, } from "./exporter-output-contract.js";
 import { asRegistrationRecord, assertOptionalBooleanField, assertOptionalFlagDefaultField, assertOptionalStringArrayField, assertOptionalStringField, normalizeOptionalStringArrayField, } from "./registration-validation.js";
 import { describeExtensionLongFlagFailure, findExtensionFlagTokenFailure, } from "./flag-definition-validation.js";
 import { compareComparableVersions, evaluatePmMaxVersionBound, evaluatePmMinVersionBound, parseComparableVersion, } from "./version-compat.js";
@@ -26,7 +28,7 @@ import { createRelationshipKindRegistry, } from "../../sdk/relationships.js";
 import { normalizeNames, isKnownExtensionCapability, collectUnknownExtensionCapabilities, normalizeManifestCapabilities, formatUnknownExtensionCapabilityWarning, formatLegacyExtensionCapabilityAliasWarning, } from "./extension-capability-aliases.js";
 import { normalizeExtensionPolicy, serializeExtensionPolicy, hydrateExtensionPolicy, normalizePolicySandboxProfile, evaluateExtensionPolicyForExtension, evaluateExtensionPolicyForCapability, evaluateExtensionPolicyForRegistration, } from "./extension-policy.js";
 import { createEmptyExtensionHookRegistry, createEmptyExtensionCommandRegistry, createEmptyExtensionParserRegistry, createEmptyExtensionPreflightRegistry, createEmptyExtensionServiceRegistry, createEmptyExtensionRendererRegistry, createEmptyExtensionRegistrationRegistry, } from "./extension-registries.js";
-import { normalizeCommandName, cloneContextSnapshot, } from "./extension-runtime-helpers.js";
+import { normalizeCommandName } from "./extension-runtime-helpers.js";
 import { normalizeExtensionContributionInventory } from "./contribution-inventory.js";
 import { formatExtensionManifestSchemaWarnings } from "./manifest-schema.js";
 import { attachRuntimeDefinition, assertHookHandler, assertNonEmptyRegistrationString, assertRegistrationFunction, cloneRuntimeRegistrationValue, createRegistrationValidationError, extractRegistrationValidationTrace, isExtensionServiceName, isOutputRendererFormat, normalizeRegistrationRecord, normalizeRegistrationRecordList, normalizeRuntimeRegistrationRecord, normalizeRegistrationName, sanitizeRegistrationValue, toRegistrationCommandPath, validateAssuranceMeasurementProviderDefinition, } from "./registration-values.js";
@@ -1727,6 +1729,23 @@ class ExtensionApiRegistrar {
             profile: applyProjectProfileDefaults(snapshot),
         });
     }
+    /** Validates and records optional importer/exporter flag metadata through the schema policy gate. */
+    registerImportExportCommandFlags(method, commandPath, resolvedOptions) {
+        if (resolvedOptions.flags === undefined) {
+            return;
+        }
+        assertExtensionCapability(this.#loadedExtension, "schema", `${method} options.flags`);
+        if (!this.allowRegistration("schema.flags", `${method} options.flags`, "schema")) {
+            return;
+        }
+        validateFlagDefinitions(resolvedOptions.flags);
+        this.#registrationRegistry.flags.push({
+            layer: this.#loadedExtension.layer,
+            name: this.#loadedExtension.name,
+            target_command: commandPath,
+            flags: normalizeFlagDefinitions(`${method} options.flags`, resolvedOptions.flags),
+        });
+    }
     applyImportExportCommandMetadata(method, commandPath, options) {
         if (options !== undefined &&
             (typeof options !== "object" ||
@@ -1747,6 +1766,7 @@ class ExtensionApiRegistrar {
             description: options?.description ?? defaultDescription,
             arguments: options?.arguments ?? defaultArguments,
         };
+        const output = resolveImportExportArtifactOutput(method, resolvedOptions, options?.description !== undefined);
         assertOptionalStringField(`${method} options.action`, resolvedOptions.action);
         assertOptionalStringField(`${method} options.description`, resolvedOptions.description);
         assertOptionalStringField(`${method} options.intent`, resolvedOptions.intent);
@@ -1754,20 +1774,7 @@ class ExtensionApiRegistrar {
         const examples = normalizeOptionalStringArrayField(`${method} options.examples`, resolvedOptions.examples);
         const failureHints = normalizeOptionalStringArrayField(`${method} options.failure_hints`, resolvedOptions.failure_hints);
         const argumentsDefinition = normalizeCommandDefinitionArguments(resolvedOptions.arguments);
-        if (resolvedOptions.flags !== undefined) {
-            assertExtensionCapability(this.#loadedExtension, "schema", `${method} options.flags`);
-            // Route metadata flags through the same surface-policy gate as registerFlags so
-            // enforce-mode policies blocking schema.flags are honored even when importers are allowed.
-            if (this.allowRegistration("schema.flags", `${method} options.flags`, "schema")) {
-                validateFlagDefinitions(resolvedOptions.flags);
-                this.#registrationRegistry.flags.push({
-                    layer: this.#loadedExtension.layer,
-                    name: this.#loadedExtension.name,
-                    target_command: commandPath,
-                    flags: normalizeFlagDefinitions(`${method} options.flags`, resolvedOptions.flags),
-                });
-            }
-        }
+        this.registerImportExportCommandFlags(method, commandPath, resolvedOptions);
         const registration = {
             layer: this.#loadedExtension.layer,
             name: this.#loadedExtension.name,
@@ -1787,6 +1794,7 @@ class ExtensionApiRegistrar {
             registration.intent = intent;
         }
         this.#registrationRegistry.commands.push(registration);
+        return output;
     }
     registerImporter(name, importer, options) {
         assertExtensionCapability(this.#loadedExtension, "importers", "registerImporter");
@@ -1808,19 +1816,7 @@ class ExtensionApiRegistrar {
             layer: this.#loadedExtension.layer,
             name: this.#loadedExtension.name,
             command: commandPath,
-            run: async (context) => importer({
-                registration: normalizedName,
-                action: "import",
-                command: context.command,
-                args: cloneContextSnapshot(context.args),
-                options: cloneContextSnapshot(context.options),
-                global: cloneContextSnapshot(context.global),
-                pm_root: context.pm_root,
-                source_workspace_root: context.source_workspace_root,
-                repo_root: context.repo_root,
-                pm_root_rel: context.pm_root_rel,
-                ...(context.sdk === undefined ? {} : { sdk: context.sdk }),
-            }),
+            run: async (context) => importer(buildImportExportContext(context, normalizedName, "import")),
         });
     }
     registerExporter(name, exporter, options) {
@@ -1833,29 +1829,24 @@ class ExtensionApiRegistrar {
         const commandPath = toRegistrationCommandPath(normalizedName, "export");
         // Validate and register optional command metadata before mutating the registry
         // so an invalid options object leaves no partial exporter registration.
-        this.applyImportExportCommandMetadata("registerExporter", commandPath, options);
+        const output = this.applyImportExportCommandMetadata("registerExporter", commandPath, options);
         this.#registrationRegistry.exporters.push({
             layer: this.#loadedExtension.layer,
             name: this.#loadedExtension.name,
             exporter: normalizedName,
+            ...(output === undefined ? {} : { output }),
         });
         this.#commandRegistry.handlers.push({
             layer: this.#loadedExtension.layer,
             name: this.#loadedExtension.name,
             command: commandPath,
-            run: async (context) => exporter({
-                registration: normalizedName,
-                action: "export",
-                command: context.command,
-                args: cloneContextSnapshot(context.args),
-                options: cloneContextSnapshot(context.options),
-                global: cloneContextSnapshot(context.global),
-                pm_root: context.pm_root,
-                source_workspace_root: context.source_workspace_root,
-                repo_root: context.repo_root,
-                pm_root_rel: context.pm_root_rel,
-                ...(context.sdk === undefined ? {} : { sdk: context.sdk }),
-            }),
+            run: async (context) => {
+                const result = await exporter(buildImportExportContext(context, normalizedName, "export"));
+                return output?.receipt === "suppress" &&
+                    !isHostOutputSuppressed(result)
+                    ? suppressHostOutput(result)
+                    : result;
+            },
         });
     }
     registerSearchProvider(provider) {
@@ -2225,4 +2216,4 @@ export const _testOnlyLoader = {
     },
 };
 //# sourceMappingURL=loader.js.map
-//# debugId=c88047fc-2bbd-5781-96a8-01685c06fb33
+//# debugId=cccce7c1-dd08-5c9f-a74e-e639536b9a6a

package/dist/core/history/event-index.d.ts

@@ -51,6 +51,11 @@ declare function loadDatabaseSync(loadModule: (specifier: string) => unknown): D
 declare function loadStableDatabaseSync(nodeVersion: string, loadModule: (specifier: string) => unknown): DatabaseSyncConstructor | null;
 /** Rebuild the complete optional event projection from authoritative streams. */
 export declare function rebuildHistoryEventIndex(pmRoot: string): Promise<boolean>;
+/**
+ * Query authoritative history streams when the optional SQLite accelerator is
+ * unavailable. The result preserves the index contract at higher read cost.
+ */
+export declare function queryHistoryEventStreams(pmRoot: string, query: HistoryEventIndexQuery): Promise<HistoryEventIndexQueryResult>;
 /**
  * Update an already-built event projection after one authoritative append.
  * Absence is a cheap no-op; corrupt projections are removed for lazy rebuild.

package/dist/core/history/event-index.js

@@ -5,7 +5,7 @@
  * for cursor-resumable cross-item mutation event reads.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="f1205949-16d8-51ce-98e8-04abc4c78ee8")}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]="a84b308f-7eef-535c-9531-b33b0775c651")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
@@ -13,9 +13,76 @@ import { createRequire } from "node:module";
 import { readHistoryEntries } from "./read.js";
 const EVENT_INDEX_FILENAME = "history-event-index.sqlite";
 const EVENT_INDEX_VERSION = "2";
+const AUTHORITATIVE_HISTORY_CACHE_LIMIT = 8;
+const authoritativeHistoryCaches = new Map();
 function eventIndexPath(pmRoot) {
     return path.join(pmRoot, "runtime", EVENT_INDEX_FILENAME);
 }
+async function readAuthoritativeHistoryEvents(pmRoot) {
+    const historyRoot = path.join(pmRoot, "history");
+    const entries = await fs
+        .readdir(historyRoot, { withFileTypes: true })
+        .catch((error) => {
+        if (typeof error === "object" &&
+            error !== null &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return [];
+        }
+        throw error;
+    });
+    const cached = authoritativeHistoryCaches.get(pmRoot) ?? {
+        streams: new Map(),
+        ordered_events: [],
+    };
+    const presentStreams = new Set();
+    let changed = !authoritativeHistoryCaches.has(pmRoot);
+    for (const historyFile of entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".jsonl"))
+        .sort((left, right) => left.name.localeCompare(right.name))) {
+        const streamId = historyFile.name.slice(0, -".jsonl".length);
+        presentStreams.add(streamId);
+        const historyPath = path.join(historyRoot, historyFile.name);
+        const stats = await fs.stat(historyPath, { bigint: true });
+        const signature = [
+            stats.dev,
+            stats.ino,
+            stats.size,
+            stats.mtimeNs,
+            stats.ctimeNs,
+        ].join(":");
+        if (cached.streams.get(streamId)?.signature === signature)
+            continue;
+        const history = await readHistoryEntries(historyPath, streamId);
+        cached.streams.set(streamId, {
+            signature,
+            events: history.map((entry, streamOffset) => ({
+                stream_id: streamId,
+                stream_offset: streamOffset,
+                entry,
+            })),
+        });
+        changed = true;
+    }
+    for (const streamId of cached.streams.keys()) {
+        if (!presentStreams.has(streamId)) {
+            cached.streams.delete(streamId);
+            changed = true;
+        }
+    }
+    if (changed) {
+        cached.ordered_events = [...cached.streams.values()]
+            .flatMap((stream) => stream.events)
+            .sort(compareHistoryEventPosition);
+    }
+    authoritativeHistoryCaches.delete(pmRoot);
+    authoritativeHistoryCaches.set(pmRoot, cached);
+    if (authoritativeHistoryCaches.size > AUTHORITATIVE_HISTORY_CACHE_LIMIT) {
+        const oldestRoot = authoritativeHistoryCaches.keys().next().value;
+        authoritativeHistoryCaches.delete(oldestRoot);
+    }
+    return cached.ordered_events;
+}
 function loadDatabaseSync(loadModule) {
     try {
         const loaded = loadModule(["node", "sqlite"].join(":"));
@@ -85,21 +152,6 @@ export async function rebuildHistoryEventIndex(pmRoot) {
     const Database = resolveDatabaseSync();
     if (!Database)
         return false;
-    const historyRoot = path.join(pmRoot, "history");
-    const entries = await fs
-        .readdir(historyRoot, { withFileTypes: true })
-        .catch((error) => {
-        if (typeof error === "object" &&
-            error !== null &&
-            "code" in error &&
-            error.code === "ENOENT") {
-            return [];
-        }
-        throw error;
-    });
-    const historyFiles = entries
-        .filter((entry) => entry.isFile() && entry.name.endsWith(".jsonl"))
-        .sort((left, right) => left.name.localeCompare(right.name));
     const targetPath = eventIndexPath(pmRoot);
     await fs.mkdir(path.dirname(targetPath), { recursive: true });
     const temporaryPath = `${targetPath}.${randomUUID()}.tmp`;
@@ -108,16 +160,8 @@ export async function rebuildHistoryEventIndex(pmRoot) {
         database = new Database(temporaryPath);
         createSchema(database);
         database.exec("BEGIN IMMEDIATE");
-        for (const historyFile of historyFiles) {
-            const streamId = historyFile.name.slice(0, -".jsonl".length);
-            const history = await readHistoryEntries(path.join(historyRoot, historyFile.name), streamId);
-            for (const [streamOffset, entry] of history.entries()) {
-                insertEvent(database, {
-                    stream_id: streamId,
-                    stream_offset: streamOffset,
-                    entry,
-                });
-            }
+        for (const event of await readAuthoritativeHistoryEvents(pmRoot)) {
+            insertEvent(database, event);
         }
         database.exec("COMMIT");
         database.close();
@@ -132,6 +176,68 @@ export async function rebuildHistoryEventIndex(pmRoot) {
         throw error;
     }
 }
+function matchesSet(value, accepted) {
+    return !accepted || accepted.length === 0 || accepted.includes(value);
+}
+function compareHistoryEventPosition(left, right) {
+    return (left.entry.ts.localeCompare(right.entry.ts) ||
+        left.stream_id.localeCompare(right.stream_id) ||
+        left.stream_offset - right.stream_offset);
+}
+function isInsideHistoryEventWindow(event, query) {
+    if (query.after_ts !== undefined &&
+        query.after_stream_id !== undefined &&
+        query.after_stream_offset !== undefined) {
+        if (compareHistoryEventPosition(event, {
+            stream_id: query.after_stream_id,
+            stream_offset: query.after_stream_offset,
+            entry: { ...event.entry, ts: query.after_ts },
+        }) <= 0) {
+            return false;
+        }
+    }
+    else if (query.since_ts !== undefined &&
+        event.entry.ts < query.since_ts) {
+        return false;
+    }
+    return true;
+}
+function matchesHistoryEventHarness(event, query) {
+    if (!query.harnesses || query.harnesses.length === 0)
+        return true;
+    if (query.harnesses.includes(event.entry.agent_harness ?? ""))
+        return true;
+    return (event.entry.agent_harness === undefined &&
+        (query.harness_alias_authors ?? []).includes(event.entry.author));
+}
+function matchesHistoryEventQuery(event, query) {
+    if (!isInsideHistoryEventWindow(event, query) ||
+        !matchesSet(event.entry.op, query.ops) ||
+        !matchesSet(event.entry.author, query.authors) ||
+        !matchesSet(event.entry.agent_instance ?? "", query.agent_instances) ||
+        !matchesSet(event.stream_id, query.stream_ids) ||
+        !matchesHistoryEventHarness(event, query)) {
+        return false;
+    }
+    return (query.provenance ?? []).every((predicate) => {
+        const value = event.entry.agent_provenance?.[predicate.dimension]?.value;
+        return value !== undefined && predicate.values.includes(value);
+    });
+}
+/**
+ * Query authoritative history streams when the optional SQLite accelerator is
+ * unavailable. The result preserves the index contract at higher read cost.
+ */
+export async function queryHistoryEventStreams(pmRoot, query) {
+    const limit = Math.max(0, Math.floor(query.limit));
+    const rows = (await readAuthoritativeHistoryEvents(pmRoot))
+        .filter((event) => matchesHistoryEventQuery(event, query))
+        .slice(0, limit + 1);
+    return {
+        events: rows.slice(0, query.limit),
+        has_more: rows.length > query.limit,
+    };
+}
 /**
  * Update an already-built event projection after one authoritative append.
  * Absence is a cheap no-op; corrupt projections are removed for lazy rebuild.
@@ -268,4 +374,4 @@ export const _testOnly = {
     },
 };
 //# sourceMappingURL=event-index.js.map
-//# debugId=f1205949-16d8-51ce-98e8-04abc4c78ee8
+//# debugId=a84b308f-7eef-535c-9531-b33b0775c651

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

@@ -36,6 +36,8 @@ export interface PmCliErrorRecoveryPayload {
     option_scope?: "declared_on_path" | "declared_elsewhere" | "declared_nowhere";
     /** Value that configures or reports suggested retry for this contract. */
     suggested_retry?: string;
+    /** Tokenized retry arguments for direct execution without reparsing display text. */
+    suggested_retry_args?: string[];
     /** Elapsed time in milliseconds for retry after. */
     retry_after_ms?: number;
     /** Value that configures or reports fallback candidates for this contract. */

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]="c863f07f-428b-5b7f-a5f7-23e7f5fa749a")}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]="a19ff5c0-2c4d-5576-a551-cab35276fdc3")}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=c863f07f-428b-5b7f-a5f7-23e7f5fa749a
+//# debugId=a19ff5c0-2c4d-5576-a551-cab35276fdc3

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