@unbrained/pm-cli 2026.9.2 → 2026.9.4

package/dist/core/output/output.js

@@ -4,13 +4,14 @@
  * Formats compact human and machine output for Output.
  */
 
-!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]="202cbb3e-71fe-5701-a1f5-eb515bf56561")}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]="fa89762b-915f-5ef0-a091-f05338c11683")}catch(e){}}();
 import { getActiveCommandContext, runActiveCommandOverride, runActiveRendererOverride, runActiveServiceOverrideSync, setActiveCommandResult, } from "../extensions/index.js";
 import { EXIT_CODE } from "../shared/constants.js";
 import { isHostOutputSuppressed } from "./output-control.js";
 import { projectMutationResult } from "./mutation-projection.js";
 import { attachReadOutputContracts } from "../../sdk/context-intent-contracts.js";
 import { attachOutputTokenAccounting } from "../../sdk/output-token-accounting.js";
+import { propagateContextUsageServingReceipt } from "../../sdk/context-usage.js";
 import { isReadOutputBudgetExceeded, resolveReadOutputEncoding, } from "../../sdk/read-output-contracts.js";
 import { encode as encodeToon } from "@toon-format/toon";
 const DECLARED_PROCESS_EXIT_CODES = new Set(Object.values(EXIT_CODE));
@@ -19,6 +20,18 @@ let streamErrorHandlersInstalled = false;
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function setActiveCommandResultOmitted(source) {
+    const omitted = { read_output: { result_omitted: true } };
+    propagateContextUsageServingReceipt(source, omitted);
+    setActiveCommandResult(omitted);
+}
+function setActiveCommandDeliveryResult(result, receiptSource, structuredDeliveryPreserved) {
+    if (structuredDeliveryPreserved) {
+        setActiveCommandResult(result);
+        return;
+    }
+    setActiveCommandResultOmitted(receiptSource);
+}
 function shouldUseNativeOutput(result) {
     return isPlainObject(result) && result[NATIVE_OUTPUT_MARKER] === true;
 }
@@ -346,11 +359,13 @@ function resolveOutputService(effectiveResult, nativeOutput, options, format) {
             rendered: serviceOverride.result.endsWith("\n")
                 ? serviceOverride.result
                 : `${serviceOverride.result}\n`,
+            structuredDeliveryPreserved: false,
         };
     }
     return {
         result: serviceOverride.handled ? serviceOverride.result : effectiveResult,
         rendered: null,
+        structuredDeliveryPreserved: !serviceOverride.handled || isPlainObject(serviceOverride.result),
     };
 }
 /** Formats a command result after command-level output ownership is resolved. */
@@ -382,9 +397,12 @@ function formatEffectiveOutput(effectiveResult, nativeOutput, options) {
         commandOptions: resolvedCommandOptions,
     };
     const service = resolveOutputService(effectiveResult, nativeOutput, effectiveOptions, format);
-    if (service.rendered !== null)
+    if (service.rendered !== null) {
+        setActiveCommandResultOmitted(effectiveResult);
         return service.rendered;
+    }
     const outputResult = service.result;
+    propagateContextUsageServingReceipt(effectiveResult, outputResult);
     const projectedOutputResult = command === "test"
         ? projectLinkedTestEvidence(outputResult, options.lean === true)
         : outputResult;
@@ -392,6 +410,7 @@ function formatEffectiveOutput(effectiveResult, nativeOutput, options) {
     if (isReadOutputBudgetExceeded(intentOutputResult)) {
         process.exitCode ||= EXIT_CODE.USAGE;
     }
+    let { structuredDeliveryPreserved } = service;
     const renderResolvedOutput = (value) => {
         if (format === "toon") {
             const markdownDefault = renderDefaultMarkdownResult(value);
@@ -402,6 +421,7 @@ function formatEffectiveOutput(effectiveResult, nativeOutput, options) {
             ? { rendered: null }
             : runActiveRendererOverride(format, value);
         if (rendererOverride.rendered !== null) {
+            structuredDeliveryPreserved = false;
             return rendererOverride.rendered.endsWith("\n")
                 ? rendererOverride.rendered
                 : `${rendererOverride.rendered}\n`;
@@ -414,7 +434,9 @@ function formatEffectiveOutput(effectiveResult, nativeOutput, options) {
     const accountedOutputResult = options.tokenAccounting === true
         ? attachOutputTokenAccounting(intentOutputResult, renderResolvedOutput)
         : intentOutputResult;
-    return renderResolvedOutput(accountedOutputResult);
+    const rendered = renderResolvedOutput(accountedOutputResult);
+    setActiveCommandDeliveryResult(accountedOutputResult, effectiveResult, options.quiet !== true && structuredDeliveryPreserved);
+    return rendered;
 }
 /** Implements format output for the public runtime surface of this module. */
 export function formatOutput(result, options) {
@@ -427,9 +449,11 @@ export function formatOutput(result, options) {
         ? suppressedOutput.result
         : stripNativeOutputMarker(commandOverride.result);
     setActiveCommandResult(effectiveResult);
-    return suppressedOutput
-        ? ""
-        : formatEffectiveOutput(effectiveResult, nativeOutput, options);
+    if (suppressedOutput) {
+        setActiveCommandResultOmitted(effectiveResult);
+        return "";
+    }
+    return formatEffectiveOutput(effectiveResult, nativeOutput, options);
 }
 /** Implements print result for the public runtime surface of this module. */
 export function printResult(result, options) {
@@ -468,4 +492,4 @@ export const outputTestOnly = {
     renderToonValue,
 };
 //# sourceMappingURL=output.js.map
-//# debugId=202cbb3e-71fe-5701-a1f5-eb515bf56561
+//# debugId=fa89762b-915f-5ef0-a091-f05338c11683

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

@@ -26,7 +26,7 @@ export interface AgentProvenanceObservation {
  */
 export type AgentProvenance = Readonly<Record<string, AgentProvenanceObservation | null>>;
 /** Bounded reason explaining why one declared provenance dimension was absent. */
-export type AgentProvenanceAbsenceReason = "harness_unavailable" | "resolver_failed" | "resolver_not_configured" | "probes_disabled" | "invalid_value";
+export type AgentProvenanceAbsenceReason = "harness_unavailable" | "resolver_input_missing" | "resolver_failed" | "resolver_not_configured" | "probes_disabled" | "invalid_value";
 /** Machine-readable resolution outcome for one provenance dimension. */
 export interface AgentProvenanceOutcome {
     /** Whether the dimension resolved without retaining private source material. */
@@ -168,6 +168,8 @@ export interface HarnessDetectionSignals {
     cwd?: string;
     /** Home directory override used by embedders and isolated tests. */
     home_dir?: string;
+    /** Explicit harness-owned session file supplied by an embedding host. */
+    session_file?: string;
 }
 /** Built-in agent descriptors evaluated before package and workspace additions. */
 export declare const BUILTIN_HARNESS_SIGNAL_DESCRIPTORS: readonly HarnessSignalDescriptor[];

package/dist/core/shared/author.js

@@ -4,7 +4,7 @@
  * Provides shared primitives and utilities for Author.
  */
 
-!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]="cf550961-0040-5e04-9d8d-16e316027e43")}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]="dfbf4eb8-1f02-5880-a70a-0e7ed9b9784a")}catch(e){}}();
 import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash } from "node:crypto";
 import fs from "node:fs";
@@ -12,6 +12,7 @@ import os from "node:os";
 import path from "node:path";
 import { resolveAgentSessionContextFromSignals, } from "./agent-session-context.js";
 import { readAgentSemanticAttributionSync, } from "../session/session-state.js";
+import { isFileAbsentError } from "../fs/fs-utils.js";
 /** Stable built-in provenance dimensions understood by the default runtime. */
 export const AGENT_PROVENANCE_DIMENSIONS = [
     "model",
@@ -357,18 +358,83 @@ function parseClaudeProvenanceLine(line) {
     }
     return Object.freeze({ model, version });
 }
-function readClaudeSessionProvenance(dimension, signals, env) {
+/** Classify one candidate without following symlinks or leaking filesystem detail. */
+function claudeTranscriptCandidateStatus(candidate) {
+    try {
+        return fs.lstatSync(candidate).isFile() ? "available" : "missing";
+    }
+    catch (error) {
+        return isFileAbsentError(error) ? "missing" : "failed";
+    }
+}
+/** Resolve a bounded cross-workspace Claude transcript discovery result. */
+function discoverClaudeSessionFile(projectsRoot, session) {
+    let discovered;
+    try {
+        discovered = fs
+            .readdirSync(projectsRoot, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .sort((left, right) => left.name.localeCompare(right.name))
+            .slice(0, 512)
+            .map((entry) => {
+            const candidate = path.join(projectsRoot, entry.name, `${session}.jsonl`);
+            return {
+                candidate,
+                status: claudeTranscriptCandidateStatus(candidate),
+            };
+        });
+    }
+    catch (error) {
+        return { status: isFileAbsentError(error) ? "missing" : "failed" };
+    }
+    const matches = discovered
+        .filter(({ status }) => status === "available")
+        .map(({ candidate }) => candidate);
+    if (matches.length === 0) {
+        return {
+            status: discovered.some(({ status }) => status === "failed")
+                ? "failed"
+                : "missing",
+        };
+    }
+    if (matches.length > 1)
+        return { status: "ambiguous" };
+    return { status: "available", path: matches[0] };
+}
+/** Resolve one Claude transcript by stable session identity without exposing its path. */
+function resolveClaudeSessionFile(signals, env) {
     const session = nonBlank(env.CLAUDE_CODE_SESSION_ID);
-    if (!session || !/^[A-Za-z0-9_-]{1,128}$/u.test(session))
-        return undefined;
+    if (!session || !/^[A-Za-z0-9_-]{1,128}$/u.test(session)) {
+        return { status: "unavailable" };
+    }
     const workspace = path.resolve(signals.cwd ?? process.cwd());
     const encodedWorkspace = workspace.replaceAll(/[^A-Za-z0-9-]/gu, "-");
-    const sessionPath = path.join(signals.home_dir ?? os.homedir(), ".claude", "projects", encodedWorkspace, `${session}.jsonl`);
+    const projectsRoot = path.join(signals.home_dir ?? os.homedir(), ".claude", "projects");
+    const directPath = path.join(projectsRoot, encodedWorkspace, `${session}.jsonl`);
+    const explicitPath = nonBlank(signals.session_file);
+    const suppliedPath = explicitPath && path.basename(explicitPath) === `${session}.jsonl`
+        ? explicitPath
+        : undefined;
+    for (const candidate of [suppliedPath, directPath]) {
+        if (!candidate)
+            continue;
+        const status = claudeTranscriptCandidateStatus(candidate);
+        if (status === "available")
+            return { status, path: candidate };
+        if (status === "failed")
+            return { status };
+    }
+    return discoverClaudeSessionFile(projectsRoot, session);
+}
+function readClaudeSessionProvenance(dimension, signals, env) {
+    const resolution = resolveClaudeSessionFile(signals, env);
+    if (resolution.status !== "available")
+        return undefined;
     try {
-        const file = fs.openSync(sessionPath, "r");
+        const file = fs.openSync(resolution.path, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
         try {
             const stats = fs.fstatSync(file);
-            const cacheKey = `${sessionPath}\u0000${stats.size}\u0000${stats.mtimeMs}`;
+            const cacheKey = `${resolution.path}\u0000${stats.size}\u0000${stats.mtimeMs}`;
             const cached = claudeProvenanceSnapshotCache.get(cacheKey);
             if (cached)
                 return cached[dimension];
@@ -553,14 +619,20 @@ function resolveProvenanceProbe(dimension, signals, env, descriptor) {
     }
     return undefined;
 }
-function provenanceResolverHasInput(resolver, descriptor, env) {
+function provenanceResolverHasInput(resolver, descriptor, signals, env) {
     if (resolver === "ai_agent_version") {
         const value = nonBlank(env.AI_AGENT);
-        return (value !== undefined && literalSignalMatches(value, descriptor.harness));
+        return value !== undefined &&
+            literalSignalMatches(value, descriptor.harness)
+            ? "available"
+            : "unavailable";
+    }
+    if (resolver === "codex_session_file") {
+        return nonBlank(env.CODEX_THREAD_ID) !== undefined
+            ? "available"
+            : "unavailable";
     }
-    return resolver === "codex_session_file"
-        ? nonBlank(env.CODEX_THREAD_ID) !== undefined
-        : nonBlank(env.CLAUDE_CODE_SESSION_ID) !== undefined;
+    return resolveClaudeSessionFile(signals, env).status;
 }
 function effectiveHarnessDetectionSignals(signals) {
     if (signals)
@@ -907,7 +979,17 @@ export function detectAgentIdentity(signals) {
     ];
     return Object.fromEntries(entries.filter((entry) => entry[1] !== undefined));
 }
-function resolveProvenanceOutcome(dimension, identity, descriptor, env, probesEnabled, invalidValue) {
+/** Classify one configured resolver's privacy-safe absence outcome. */
+function provenanceResolverAbsence(resolverInput) {
+    if (resolverInput === "unavailable") {
+        return { status: "unavailable", reason: "harness_unavailable" };
+    }
+    if (resolverInput === "missing") {
+        return { status: "unavailable", reason: "resolver_input_missing" };
+    }
+    return { status: "failed", reason: "resolver_failed" };
+}
+function resolveProvenanceOutcome(dimension, identity, descriptor, signals, env, probesEnabled, invalidValue) {
     const resolver = descriptor?.provenance_resolvers[dimension];
     if (identity.provenance?.[dimension]) {
         return {
@@ -924,14 +1006,20 @@ function resolveProvenanceOutcome(dimension, identity, descriptor, env, probesEn
         };
     }
     if (resolver) {
-        const resolverHasInput = provenanceResolverHasInput(resolver, descriptor, env);
-        const status = resolverHasInput && probesEnabled ? "failed" : "unavailable";
-        const reason = !resolverHasInput
-            ? "harness_unavailable"
-            : probesEnabled
-                ? "resolver_failed"
-                : "probes_disabled";
-        return { status, reason, resolver, rule_version: "v1" };
+        if (!probesEnabled) {
+            return {
+                status: "unavailable",
+                reason: "probes_disabled",
+                resolver,
+                rule_version: "v1",
+            };
+        }
+        const resolverInput = provenanceResolverHasInput(resolver, descriptor, signals, env);
+        return {
+            ...provenanceResolverAbsence(resolverInput),
+            resolver,
+            rule_version: "v1",
+        };
     }
     return {
         status: descriptor?.provenance_unavailable_dimensions.includes(dimension)
@@ -972,7 +1060,7 @@ export function diagnoseAgentIdentity(signals) {
     });
     const outcomes = Object.fromEntries(AGENT_PROVENANCE_DIMENSIONS.map((dimension) => [
         dimension,
-        resolveProvenanceOutcome(dimension, identity, descriptor, env, probesEnabled, dimension === "role" && invalidRoleValue),
+        resolveProvenanceOutcome(dimension, identity, descriptor, effectiveSignals, env, probesEnabled, dimension === "role" && invalidRoleValue),
     ]));
     return { ...identity, provenance_outcomes: outcomes };
 }
@@ -1082,4 +1170,4 @@ export function resolveAuthor(candidate, fallback) {
     return identity.author;
 }
 //# sourceMappingURL=author.js.map
-//# debugId=cf550961-0040-5e04-9d8d-16e316027e43
+//# debugId=dfbf4eb8-1f02-5880-a70a-0e7ed9b9784a

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

@@ -4,6 +4,8 @@ export declare function nowIso(): string;
 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;
+/** Return whether a value is a calendar-valid RFC 3339 date-time whose fractional seconds carry no sub-millisecond information. */
+export declare function isMillisecondPrecisionRfc3339DateTime(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]="7887e752-b1b8-5c5e-9dd8-93b41cb757af")}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]="fb1102d4-1beb-5de8-87e6-af2efebafe39")}catch(e){}}();
 import { PmCliError } from "./errors.js";
 import { evictOldestMemoEntries } from "./memo.js";
 import { EXIT_CODE } from "./constants.js";
@@ -48,6 +48,12 @@ export function isRfc3339DateTime(input) {
         (offsetHourRaw === undefined || Number(offsetHourRaw) <= 23) &&
         (offsetMinuteRaw === undefined || Number(offsetMinuteRaw) <= 59));
 }
+/** Return whether a value is a calendar-valid RFC 3339 date-time whose fractional seconds carry no sub-millisecond information. */
+export function isMillisecondPrecisionRfc3339DateTime(input) {
+    const fraction = /\.(\d+)(?:Z|[+-]\d{2}:\d{2})$/iu.exec(input)?.[1];
+    return (isRfc3339DateTime(input) &&
+        (fraction === undefined || /^\d{0,3}0*$/u.test(fraction)));
+}
 /**
  * Memoized `Date.parse` for {@link compareTimestampStrings}. Sort comparators call it
  * O(n log n) times over a corpus whose timestamp strings repeat heavily, and
@@ -298,4 +304,4 @@ export const _testOnly = {
     isWhitespaceCharacter,
 };
 //# sourceMappingURL=time.js.map
-//# debugId=7887e752-b1b8-5c5e-9dd8-93b41cb757af
+//# debugId=fb1102d4-1beb-5de8-87e6-af2efebafe39

package/dist/core/store/item-metadata-query-index.js

@@ -4,7 +4,7 @@
  * Maintains a rebuildable SQLite projection for bounded metadata queries.
  */
 
-!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]="e94075b0-810d-506c-b6a2-ae322526c078")}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]="97cfeab2-8e3f-5b70-9f64-10494158d141")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
@@ -185,13 +185,13 @@ function readIndexMetadata(database) {
  * callers can remove and lazily rebuild this optional projection.
  */
 export async function updateItemMetadataQueryIndex(options) {
+    const Database = resolveDatabaseSync();
+    if (!Database)
+        return false;
     const indexPath = queryIndexPath(options.pmRoot);
     let database;
     try {
         await fs.access(indexPath);
-        const Database = resolveDatabaseSync();
-        if (!Database)
-            return false;
         database = new Database(indexPath);
         database.exec("PRAGMA foreign_keys = ON");
         const metadata = readIndexMetadata(database);
@@ -470,4 +470,4 @@ export const _testOnly = {
     },
 };
 //# sourceMappingURL=item-metadata-query-index.js.map
-//# debugId=e94075b0-810d-506c-b6a2-ae322526c078
+//# debugId=97cfeab2-8e3f-5b70-9f64-10494158d141

package/dist/sdk/context/recency.d.ts

@@ -0,0 +1,9 @@
+/** Deterministic oldest coordinate used when legacy creation metadata is invalid. */
+export declare const CONTEXT_RECENCY_EPOCH = "1970-01-01T00:00:00.000Z";
+/**
+ * Canonicalize a calendar-valid RFC 3339 instant or dashed legacy date-only
+ * value. Compact dates, sub-millisecond instants, and host-local date-times are
+ * rejected because they cannot round-trip through the strict timestamp contract
+ * losslessly and deterministically.
+ */
+export declare function canonicalizeContextRecencyCoordinate(value: unknown): string | null;

package/dist/sdk/context/recency.js

@@ -0,0 +1,34 @@
+/**
+ * @module sdk/context/recency
+ *
+ * Canonicalizes the absolute timestamps used as durable context-recency
+ * coordinates without accepting relative or host-local date-time values.
+ */
+
+!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]="377499d7-13b3-55f0-9d44-425bfcaf7964")}catch(e){}}();
+import { isMillisecondPrecisionRfc3339DateTime, resolveIsoOrRelative, } from "../../core/shared/time.js";
+/** Deterministic oldest coordinate used when legacy creation metadata is invalid. */
+export const CONTEXT_RECENCY_EPOCH = "1970-01-01T00:00:00.000Z";
+/**
+ * Canonicalize a calendar-valid RFC 3339 instant or dashed legacy date-only
+ * value. Compact dates, sub-millisecond instants, and host-local date-times are
+ * rejected because they cannot round-trip through the strict timestamp contract
+ * losslessly and deterministically.
+ */
+export function canonicalizeContextRecencyCoordinate(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    if (!isMillisecondPrecisionRfc3339DateTime(trimmed) &&
+        !/^\d{4}-\d{2}-\d{2}$/u.test(trimmed)) {
+        return null;
+    }
+    try {
+        return resolveIsoOrRelative(trimmed, new Date(Number.NaN), "context signal recency coordinate");
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=recency.js.map
+//# debugId=377499d7-13b3-55f0-9d44-425bfcaf7964

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

@@ -0,0 +1,9 @@
+/**
+ * @module sdk/context/usage-egress
+ *
+ * Keeps post-projection context feedback best-effort without weakening the
+ * response contract returned by embedded SDK and MCP hosts.
+ */
+import { finalizeContextUsageDelivery } from "../context-usage.js";
+/** Finalize derived usage feedback and attach a stable warning on failure. */
+export declare function finalizeContextUsageEgress(pmRoot: string, projected: unknown, finalize?: typeof finalizeContextUsageDelivery): Promise<void>;

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

@@ -0,0 +1,30 @@
+/**
+ * @module sdk/context/usage-egress
+ *
+ * Keeps post-projection context feedback best-effort without weakening the
+ * response contract returned by embedded SDK and MCP hosts.
+ */
+
+!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]="c5a14f99-ce5b-5da7-8b17-6b6a56f0644a")}catch(e){}}();
+import { finalizeContextUsageDelivery } from "../context-usage.js";
+/** Finalize derived usage feedback and attach a stable warning on failure. */
+export async function finalizeContextUsageEgress(pmRoot, projected, finalize = finalizeContextUsageDelivery) {
+    try {
+        await finalize({ pmRoot, result: projected });
+    }
+    catch {
+        if (typeof projected === "object" &&
+            projected !== null &&
+            !Array.isArray(projected)) {
+            const record = projected;
+            const warnings = Array.isArray(record.warnings)
+                ? record.warnings.filter((warning) => typeof warning === "string")
+                : [];
+            record.warnings = [
+                ...new Set([...warnings, "context_usage_feedback_write_failed"]),
+            ].sort();
+        }
+    }
+}
+//# sourceMappingURL=usage-egress.js.map
+//# debugId=c5a14f99-ce5b-5da7-8b17-6b6a56f0644a

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

@@ -5,12 +5,13 @@
  * 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]="da15ca02-02cc-5886-8c82-610939b8581c")}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]="5dc9c6e4-6db8-560f-a87f-368132e2ffb3")}catch(e){}}();
 import { AsyncLocalStorage } from "node:async_hooks";
 import { renderPmCommand } from "./command-line.js";
 import { attachOutputOmissionReceipt } from "./output-projection.js";
 import { encodeQueryCursor } from "./pagination.js";
 import { applyReadOutputDimensions, stabilizeReadOutputReceiptEstimates, } from "./read-output-contracts.js";
+import { propagateContextUsageServingReceipt } from "./context-usage.js";
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 /** Built-in intent projections shared by CLI, SDK, MCP, and package authors. */
@@ -692,6 +693,7 @@ export function attachReadOutputContracts(command, options, result) {
         !Array.isArray(disclosedResult)
         ? applyReadOutputDimensions(command ?? "", options, collapseContinuationMetadata(options, attachContextIntentReceipt(command ?? "", options, disclosedResult)))
         : disclosedResult;
+    propagateContextUsageServingReceipt(result, projected);
     if (options.outputRowContract === true ||
         options.output_row_contract === true ||
         typeof projected !== "object" ||
@@ -700,7 +702,9 @@ export function attachReadOutputContracts(command, options, result) {
         !Object.hasOwn(projected, "row_contract")) {
         return projected;
     }
-    return stabilizeSuppressedRowContractReceipts(Object.fromEntries(Object.entries(projected).filter(([key]) => key !== "row_contract")), options);
+    const suppressed = stabilizeSuppressedRowContractReceipts(Object.fromEntries(Object.entries(projected).filter(([key]) => key !== "row_contract")), options);
+    propagateContextUsageServingReceipt(projected, suppressed);
+    return suppressed;
 }
 //# sourceMappingURL=context-intent-contracts.js.map
-//# debugId=da15ca02-02cc-5886-8c82-610939b8581c
+//# debugId=5dc9c6e4-6db8-560f-a87f-368132e2ffb3

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

@@ -1,11 +1,28 @@
 import type { RuntimeStatusRegistry } from "../core/schema/runtime-schema.js";
 import type { ItemMetadata } from "../types/index.js";
+import type { HistoryEventClass } from "../core/history/event-classification.js";
 /** Canonical signal keys understood by the built-in relevance model. */
 export declare const CONTEXT_RELEVANCE_SIGNAL_NAMES: readonly ["structural", "recency", "activity_density", "graph_proximity", "claim_focus", "priority_pressure", "risk_pressure", "deadline_pressure", "knowledge_density", "author_affinity", "usage_affinity", "semantic_similarity"];
 /** A normalized signal consumed by the built-in context relevance scorer. */
 export type ContextRelevanceSignalName = (typeof CONTEXT_RELEVANCE_SIGNAL_NAMES)[number];
 /** Normalized candidate features; omitted signals are excluded from weighting. */
 export type ContextRelevanceSignals = Partial<Record<Exclude<ContextRelevanceSignalName, "structural">, number>>;
+/** Authoritative coordinate and fallback that produced an item's recency. */
+export interface ContextRecencyEvidence {
+    /** Source selected by the canonical fallback ladder. */
+    source: "substantive_history" | "release_cohort" | "created_at";
+    /** ISO coordinate used for deterministic recency ordering. */
+    coordinate: string;
+    /** Immutable operation selected from history when source is substantive_history. */
+    history_op?: string;
+    /** Declared class selected from history when source is substantive_history. */
+    event_class?: HistoryEventClass;
+}
+/** Per-signal provenance exposed by explained relevance results. */
+export interface ContextSignalProvenance {
+    /** Evidence for the canonical temporal component. */
+    recency: ContextRecencyEvidence;
+}
 /** A project-management object and its derived relevance signals. */
 export interface ContextRelevanceCandidate<TItem> {
     /** Stable identifier used to reference this record across commands and storage. */
@@ -14,11 +31,15 @@ export interface ContextRelevanceCandidate<TItem> {
     item: TItem;
     /** Value that configures or reports signals for this contract. */
     signals?: ContextRelevanceSignals;
+    /** Authoritative source details for explainable derived signals. */
+    signal_provenance?: ContextSignalProvenance;
 }
 /** Item candidate whose built-in metadata derivation always supplies signals. */
 export interface ItemContextRelevanceCandidate extends ContextRelevanceCandidate<ItemMetadata> {
     /** Complete built-in derivation result, with unavailable signals omitted by value. */
     signals: ContextRelevanceSignals;
+    /** Built-in recency derivation always discloses its source. */
+    signal_provenance: ContextSignalProvenance;
 }
 /** Inputs that make item-signal derivation deterministic and host-configurable. */
 export interface BuildItemContextRelevanceCandidatesOptions {
@@ -42,6 +63,8 @@ export interface BuildItemContextRelevanceCandidatesOptions {
     knowledgeDensity?: Readonly<Record<string, number>>;
     /** Optional history-derived author affinity by item id. */
     authorAffinity?: Readonly<Record<string, number>>;
+    /** Latest substantive history evidence keyed by item id. */
+    recencyEvidence?: Readonly<Record<string, ContextRecencyEvidence>>;
 }
 /**
  * Derive the canonical metadata signals consumed by `pm context` and `pm next`.