@unbrained/pm-cli 2026.9.2 → 2026.9.3

package/dist/sdk/context-usage.js

@@ -6,7 +6,7 @@
  * intents; it never enters item history and is safe to delete or rebuild.
  */
 
-!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]="5f4ccd28-a001-54aa-8378-893025c69b96")}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]="997a09a2-cf0c-5384-b457-d9627d465b71")}catch(e){}}();
 import { randomUUID } from "node:crypto";
 import { appendFile, mkdir, readFile, rename, stat, writeFile, } from "node:fs/promises";
 import path from "node:path";
@@ -16,6 +16,154 @@ const DEFAULT_RETENTION_DAYS = 30;
 const DAY_MS = 86_400_000;
 const DEFAULT_COMPACTION_BYTES = 262_144;
 const CONTEXT_USAGE_LOCK_ID = "context-usage-ledger";
+const CONTEXT_USAGE_SERVING_RECEIPT = Symbol.for("@unbrained/pm-cli/context-usage-serving-receipt");
+function asObjectRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+/** Attach a JSON-invisible serving receipt to a result for later egress. */
+export function attachContextUsageServingReceipt(result, receipt) {
+    const record = asObjectRecord(result);
+    if (record !== null && receipt !== null) {
+        record[CONTEXT_USAGE_SERVING_RECEIPT] = receipt;
+    }
+}
+/** Copy an attached serving receipt across a result projection boundary. */
+export function propagateContextUsageServingReceipt(source, target) {
+    const sourceRecord = asObjectRecord(source);
+    const targetRecord = asObjectRecord(target);
+    const receipt = sourceRecord?.[CONTEXT_USAGE_SERVING_RECEIPT];
+    if (targetRecord !== null && receipt !== undefined) {
+        targetRecord[CONTEXT_USAGE_SERVING_RECEIPT] = receipt;
+    }
+}
+function receiptFromResult(result) {
+    return (asObjectRecord(result)?.[CONTEXT_USAGE_SERVING_RECEIPT] ?? null);
+}
+function resultReceiptSaysOmitted(result) {
+    const record = asObjectRecord(result);
+    for (const key of ["read_output", "context_intent"]) {
+        const receipt = asObjectRecord(record?.[key]);
+        if (receipt?.result_omitted === true)
+            return true;
+    }
+    return false;
+}
+function addContextUsageId(ids, value) {
+    if (typeof value === "string" && value.trim().length > 0) {
+        ids.add(value.trim());
+    }
+}
+function addContextUsageDirectRows(ids, value) {
+    if (!Array.isArray(value))
+        return;
+    for (const row of value) {
+        addContextUsageId(ids, asObjectRecord(row)?.id);
+    }
+}
+function addContextUsageIdList(ids, value) {
+    if (!Array.isArray(value))
+        return;
+    for (const itemId of value)
+        addContextUsageId(ids, itemId);
+}
+function collectNextResultItemIds(record, ids) {
+    const rows = [
+        ...(asObjectRecord(record.recommended) === null
+            ? []
+            : [record.recommended]),
+        ...(Array.isArray(record.ready) ? record.ready : []),
+        ...(Array.isArray(record.decision_needed) ? record.decision_needed : []),
+        ...(Array.isArray(record.blocked) ? record.blocked : []),
+        ...(Array.isArray(record.held_by_others) ? record.held_by_others : []),
+    ];
+    for (const value of rows) {
+        const row = asObjectRecord(value);
+        addContextUsageId(ids, row?.id);
+        for (const blocker of Array.isArray(row?.blockers) ? row.blockers : []) {
+            addContextUsageId(ids, asObjectRecord(blocker)?.id);
+        }
+        for (const unblockedId of Array.isArray(row?.unblocks)
+            ? row.unblocks
+            : []) {
+            addContextUsageId(ids, unblockedId);
+        }
+    }
+}
+function collectContextResultItemIds(record, ids) {
+    for (const key of [
+        "high_level",
+        "low_level",
+        "blocked_fallback",
+        "recently_created",
+        "unparented",
+        "activity",
+        "progress",
+        "blockers",
+        "staleness",
+    ]) {
+        addContextUsageDirectRows(ids, record[key]);
+    }
+    for (const value of Array.isArray(record.blockers)
+        ? record.blockers
+        : []) {
+        addContextUsageId(ids, asObjectRecord(value)?.blocked_by);
+    }
+    collectContextNestedItemIds(record, ids);
+}
+function collectContextNestedItemIds(record, ids) {
+    for (const value of Array.isArray(record.hierarchy)
+        ? record.hierarchy
+        : []) {
+        const node = asObjectRecord(value);
+        addContextUsageId(ids, node?.id);
+        addContextUsageDirectRows(ids, node?.children);
+    }
+    for (const key of ["files", "workload"]) {
+        for (const value of Array.isArray(record[key]) ? record[key] : []) {
+            addContextUsageIdList(ids, asObjectRecord(value)?.items);
+        }
+    }
+    const agenda = asObjectRecord(record.agenda);
+    for (const value of Array.isArray(agenda?.events) ? agenda.events : []) {
+        addContextUsageId(ids, asObjectRecord(value)?.item_id);
+    }
+    const tests = asObjectRecord(record.tests);
+    addContextUsageIdList(ids, tests?.items_failing);
+}
+/**
+ * Collect every item identifier visible in a final context or next result.
+ * The traversal is shape-aware so summary counters and unrelated identifier
+ * fields cannot enter the privacy-minimal usage ledger.
+ */
+export function collectContextUsageDeliveredItemIds(result, surface) {
+    const record = asObjectRecord(result);
+    if (record === null || resultReceiptSaysOmitted(result))
+        return [];
+    const ids = new Set();
+    if (surface === "next") {
+        collectNextResultItemIds(record, ids);
+    }
+    else {
+        collectContextResultItemIds(record, ids);
+    }
+    return [...ids];
+}
+/** Resolve and append one post-egress decision carried by a context result. */
+export async function finalizeContextUsageDelivery(options) {
+    const receipt = receiptFromResult(options.result);
+    if (receipt === null)
+        return false;
+    const resultOmitted = resultReceiptSaysOmitted(options.result);
+    await recordContextUsageDelivery({
+        pmRoot: options.pmRoot,
+        receipt,
+        deliveredItemIds: collectContextUsageDeliveredItemIds(options.result, receipt.surface),
+        resultOmitted,
+    });
+    return true;
+}
 /** Named validation failure emitted by context-usage SDK inputs. */
 export class ContextUsageValidationError extends TypeError {
     /** Stable machine-readable error code for package and CLI hosts. */
@@ -61,7 +209,7 @@ async function readEvents(options) {
         return [];
     }
 }
-async function appendEvents(options, events) {
+async function appendEvents(options, events, deliveryServeId) {
     const maxEvents = options.maxEvents ?? DEFAULT_MAX_EVENTS;
     const retentionDays = options.retentionDays ?? DEFAULT_RETENTION_DAYS;
     if (!Number.isInteger(maxEvents) ||
@@ -75,6 +223,10 @@ async function appendEvents(options, events) {
     const releaseLock = await acquireLock(options.pmRoot, CONTEXT_USAGE_LOCK_ID, 30, `context-usage:${process.pid}`, false, false, 3_000);
     try {
         await mkdir(runtimeDirectory, { recursive: true });
+        if (deliveryServeId !== undefined &&
+            (await readEvents(options)).some((event) => event.kind === "delivery" && event.serve_id === deliveryServeId)) {
+            return;
+        }
         await appendFile(target, events.map((event) => `${JSON.stringify(event)}\n`).join(""), "utf8");
         const customBounds = options.maxEvents !== undefined || options.retentionDays !== undefined;
         if (!customBounds && (await stat(target)).size <= DEFAULT_COMPACTION_BYTES)
@@ -93,21 +245,70 @@ async function appendEvent(options, event) {
 }
 /** Records a propensity-complete context/next serving event. */
 export async function recordContextUsageServing(options) {
-    if (process.env.PM_CONTEXT_USAGE_DISABLED === "1" ||
-        options.enabled === false)
-        return;
+    if ([
+        process.env.PM_CONTEXT_USAGE_DISABLED === "1",
+        options.enabled === false,
+    ].includes(true))
+        return null;
     if (!options.author.trim() ||
         options.rows.some((row) => !row.id.trim() || !Number.isInteger(row.rank) || row.rank < 1)) {
         throw new ContextUsageValidationError("Context usage serving requires an author and valid ranked rows");
     }
+    const normalizedRows = options.rows.map((row) => ({
+        ...row,
+        id: row.id.trim(),
+    }));
+    if (new Set(normalizedRows.map((row) => row.id)).size !== normalizedRows.length) {
+        throw new ContextUsageValidationError("Context usage serving requires unique normalized row ids");
+    }
+    const receipt = {
+        serve_id: randomUUID(),
+        author: options.author.trim(),
+        surface: options.surface,
+        rows: normalizedRows,
+    };
     await appendEvent(options, {
         kind: "serve",
+        schema_version: 2,
+        serve_id: receipt.serve_id,
         at: resolveNow(options).iso,
         author: options.author.trim(),
         surface: options.surface,
         profile: options.profile.trim() || "balanced",
-        rows: options.rows,
+        rows: receipt.rows.map((row) => ({ ...row })),
+        result_omitted: false,
+        packed_item_ids: receipt.rows
+            .filter((row) => row.included)
+            .map((row) => row.id),
     });
+    return receipt;
+}
+/** Append the exact post-egress delivery decision for one serving receipt. */
+export async function recordContextUsageDelivery(options) {
+    if (options.receipt === null ||
+        process.env.PM_CONTEXT_USAGE_DISABLED === "1" ||
+        options.enabled === false) {
+        return;
+    }
+    const rankedIds = new Set(options.receipt.rows.map((row) => row.id));
+    const deliveredItemIds = [
+        ...new Set(options.deliveredItemIds.map((id) => id.trim())),
+    ];
+    if (deliveredItemIds.some((id) => id.length === 0 || !rankedIds.has(id)) ||
+        (options.resultOmitted && deliveredItemIds.length > 0)) {
+        throw new ContextUsageValidationError("Context usage delivery requires emitted ranked ids and zero ids for an omitted result");
+    }
+    const delivery = {
+        kind: "delivery",
+        schema_version: 2,
+        serve_id: options.receipt.serve_id,
+        at: resolveNow(options).iso,
+        author: options.receipt.author,
+        surface: options.receipt.surface,
+        result_omitted: options.resultOmitted,
+        delivered_item_ids: deliveredItemIds,
+    };
+    await appendEvents(options, [delivery], delivery.serve_id);
 }
 /** Records one subsequent item read or mutation outcome. */
 export async function recordContextUsageTouch(options) {
@@ -165,6 +366,18 @@ function findTouchTimeInHorizon(touches, itemId, servedAt, horizonMs) {
         time >= servedAt &&
         time - servedAt <= horizonMs)?.time;
 }
+function firstDeliveriesByServeId(events, author) {
+    const deliveries = new Map();
+    for (const event of events) {
+        if (event.kind === "delivery" &&
+            event.schema_version === 2 &&
+            event.author === author &&
+            !deliveries.has(event.serve_id)) {
+            deliveries.set(event.serve_id, event);
+        }
+    }
+    return deliveries;
+}
 /**
  * Derives decayed served-then-touched affinity. A small exploration floor keeps
  * ignored and unseen items eligible, preventing a popularity feedback lock-in.
@@ -172,26 +385,41 @@ function findTouchTimeInHorizon(touches, itemId, servedAt, horizonMs) {
 export async function readContextUsageAffinity(options) {
     if (process.env.PM_CONTEXT_USAGE_DISABLED === "1" ||
         options.enabled === false)
-        return { affinity: {}, positive_judgments: 0, serving_events: 0 };
+        return {
+            affinity: {},
+            positive_judgments: 0,
+            serving_events: 0,
+            untrusted_serving_events: 0,
+        };
     const events = await readEvents(options);
     const now = resolveNow(options).ms;
     const horizonMs = (options.horizonHours ?? 24) * 3_600_000;
-    if (!Number.isFinite(horizonMs) || horizonMs <= 0)
+    if (![Number.isFinite(horizonMs), horizonMs > 0].every(Boolean))
         throw new ContextUsageValidationError("Context usage horizonHours must be positive");
     const author = options.author.trim();
     const touches = events
-        .filter((event) => event.kind === "touch" && event.author === author)
+        .filter((event) => event.kind === "touch")
+        .filter((event) => event.author === author)
         .map((entry) => ({ entry, time: Date.parse(entry.at) }));
     const scores = new Map();
     let servingEvents = 0;
+    let untrustedServingEvents = 0;
     let positiveJudgments = 0;
-    for (const event of events) {
-        if (event.kind !== "serve" || event.author !== author)
-            continue;
+    const deliveries = firstDeliveriesByServeId(events, author);
+    events
+        .filter((event) => event.kind === "serve")
+        .filter((event) => event.author === author)
+        .forEach((event) => {
+        if (![event.schema_version === 2, Boolean(event.serve_id)].every(Boolean)) {
+            untrustedServingEvents += 1;
+            return;
+        }
         servingEvents += 1;
         const servedAt = Date.parse(event.at);
+        const delivery = deliveries.get(event.serve_id);
+        const deliveredIds = new Set(delivery?.delivered_item_ids ?? []);
         for (const row of event.rows) {
-            if (!row.included)
+            if (!deliveredIds.has(row.id))
                 continue;
             const touchTime = findTouchTimeInHorizon(touches, row.id, servedAt, horizonMs);
             if (touchTime === undefined)
@@ -200,17 +428,18 @@ export async function readContextUsageAffinity(options) {
             const ageDays = Math.max(0, (now - touchTime) / DAY_MS);
             scores.set(row.id, (scores.get(row.id) ?? 0) + Math.exp(-ageDays / 14));
         }
-    }
+    });
     const maximum = Math.max(0, ...scores.values());
     const affinity = Object.fromEntries([...scores.entries()].map(([id, score]) => [
         id,
-        0.05 + 0.95 * (maximum > 0 ? score / maximum : 0),
+        maximum === 0 ? 0.05 : 0.05 + (0.95 * score) / maximum,
     ]));
     return {
         affinity,
         positive_judgments: positiveJudgments,
         serving_events: servingEvents,
+        untrusted_serving_events: untrustedServingEvents,
     };
 }
 //# sourceMappingURL=context-usage.js.map
-//# debugId=5f4ccd28-a001-54aa-8378-893025c69b96
+//# debugId=997a09a2-cf0c-5384-b457-d9627d465b71

package/dist/sdk/generated/generated-error-code-catalog-part-1.js

@@ -1,6 +1,6 @@
 /** Generated partition 1 of the exhaustive error-code catalog. */
 
-!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]="4734edf6-c174-50d0-b4e9-1003bc8a20bf")}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]="0a4690e9-4cde-5218-81fb-5d59807fa344")}catch(e){}}();
 export const PM_ERROR_CODE_CATALOG_PART_1 = [
     {
         code: "acceptance_criteria_mutation_conflict",
@@ -1271,6 +1271,18 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         canonical_code: "history_target_out_of_range",
         aliases: [],
     },
+    {
+        code: "history_timestamp_invalid",
+        meaning: "History timestamp invalid condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["core/history/event-index.ts", "core/history/history.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "history_timestamp_invalid",
+        aliases: [],
+    },
     {
         code: "history_unknown_author_events",
         meaning: "History unknown author events condition.",
@@ -2148,18 +2160,6 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         canonical_code: "missing_budget",
         aliases: [],
     },
-    {
-        code: "missing_cli_flag",
-        meaning: "Missing cli flag condition.",
-        stability: "provisional",
-        exit_code: 1,
-        class: "generic_failure",
-        recovery: "Inspect the structured error guidance and retry the suggested command.",
-        sources: ["sdk/cli-contracts/tool-option-contracts.ts"],
-        emitting_commands: ["*"],
-        canonical_code: "missing_cli_flag",
-        aliases: [],
-    },
 ];
 //# sourceMappingURL=generated-error-code-catalog-part-1.js.map
-//# debugId=4734edf6-c174-50d0-b4e9-1003bc8a20bf
+//# debugId=0a4690e9-4cde-5218-81fb-5d59807fa344

package/dist/sdk/generated/generated-error-code-catalog-part-2.js

@@ -1,7 +1,19 @@
 /** Generated partition 2 of the exhaustive error-code catalog. */
 
-!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]="41e6f81d-ccb5-546c-9b26-3b78027528b5")}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]="5d5a1c08-21ed-5823-8c1b-15f7907ab3b5")}catch(e){}}();
 export const PM_ERROR_CODE_CATALOG_PART_2 = [
+    {
+        code: "missing_cli_flag",
+        meaning: "Missing cli flag condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/cli-contracts/tool-option-contracts.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "missing_cli_flag",
+        aliases: [],
+    },
     {
         code: "missing_destination",
         meaning: "Missing destination condition.",
@@ -2174,4 +2186,4 @@ export const PM_ERROR_CODE_CATALOG_PART_2 = [
     },
 ];
 //# sourceMappingURL=generated-error-code-catalog-part-2.js.map
-//# debugId=41e6f81d-ccb5-546c-9b26-3b78027528b5
+//# debugId=5d5a1c08-21ed-5823-8c1b-15f7907ab3b5

package/dist/sdk/index.d.ts

@@ -81,6 +81,7 @@ export * from "./environment/source-context.js";
 export * from "./environment/host-environment-errors.js";
 export * from "./cli-contracts/command-exit-contracts.js";
 export * from "./context-relevance.js";
+export * from "./context/recency.js";
 export * from "./context-intent-contracts.js";
 export * from "./context-intent-runtime.js";
 export * from "./context-signal-store.js";
@@ -94,6 +95,7 @@ export * from "./read-output-session.js";
 export * from "./output-token-accounting.js";
 export * from "./context-packing.js";
 export * from "./context-usage.js";
+export { classifyHistoryEvent, HISTORY_EVENT_CLASSIFICATION_VERSION, MAINTENANCE_HISTORY_OPERATIONS, SUBSTANTIVE_HISTORY_OPERATIONS, type HistoryEventClass, } from "../core/history/event-classification.js";
 export * from "./dependency-provenance.js";
 export * from "./duplicates.js";
 export * from "./lifecycle/reopen.js";

package/dist/sdk/index.js

@@ -4,7 +4,7 @@
  * Defines public SDK APIs and package-author helpers for Index.
  */
 
-!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]="8a1a02de-32cb-5714-b950-6041ae8ce229")}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]="62e450f7-9ed9-5855-923a-7b2ffb8b49f4")}catch(e){}}();
 export { PM_COMMAND_CAPABILITY_CONTRACTS, PM_COMMAND_VISIBILITY_CONTRACTS, PM_MCP_PROMPT_CONTRACTS, PM_MCP_RESOURCE_CONTRACTS, PM_MCP_TOOL_COMMAND_CONTRACTS, listPmCommandsForFamily, listPmCommandsForTier, listPmMcpToolsForProfile, renderPmCommandVisibilityMarkdown, resolvePmCommandCapabilityFamily, resolvePmCommandVisibilityTier, } from "./agent-capability-contracts.js";
 export * from "./mcp/protocol.js";
 export * from "./mcp/interactions.js";
@@ -78,6 +78,7 @@ export * from "./environment/source-context.js";
 export * from "./environment/host-environment-errors.js";
 export * from "./cli-contracts/command-exit-contracts.js";
 export * from "./context-relevance.js";
+export * from "./context/recency.js";
 export * from "./context-intent-contracts.js";
 export * from "./context-intent-runtime.js";
 export * from "./context-signal-store.js";
@@ -91,6 +92,7 @@ export * from "./read-output-session.js";
 export * from "./output-token-accounting.js";
 export * from "./context-packing.js";
 export * from "./context-usage.js";
+export { classifyHistoryEvent, HISTORY_EVENT_CLASSIFICATION_VERSION, MAINTENANCE_HISTORY_OPERATIONS, SUBSTANTIVE_HISTORY_OPERATIONS, } from "../core/history/event-classification.js";
 export * from "./dependency-provenance.js";
 export * from "./duplicates.js";
 export * from "./lifecycle/reopen.js";
@@ -177,4 +179,4 @@ export * from "./mcp/discovery.js";
 export * from "./query.js";
 export * from "./testing.js";
 //# sourceMappingURL=index.js.map
-//# debugId=8a1a02de-32cb-5714-b950-6041ae8ce229
+//# debugId=62e450f7-9ed9-5855-923a-7b2ffb8b49f4

package/dist/sdk/init.d.ts

@@ -5,6 +5,8 @@ import type { GovernancePreset, PmSettings } from "../types/index.js";
 import { type ExtensionCommandResult } from "./extension.js";
 import { type InitAgentGuidanceMode, type InitAgentGuidanceSummary } from "./init-agent-guidance.js";
 import { installMergeFence } from "./merge/install.js";
+/** Symbol key for the captured working directory of an in-process init call. */
+export declare const INIT_INVOCATION_CWD: unique symbol;
 /** Documents the init installed packages summary payload exchanged by command, SDK, and package integrations. */
 export interface InitInstalledPackagesSummary {
     /** Value that configures or reports installed all for this contract. */

package/dist/sdk/init.js

@@ -4,7 +4,7 @@
  * Implements the pm init command surface and its agent-facing runtime behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="75c0d2d2-6a89-508f-b7dd-b43d55978b44")}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]="d06d4db7-8ab7-5a9f-84df-508bd305ea23")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import readline from "node:readline/promises";
@@ -27,6 +27,8 @@ import { renderPmCommand } from "./command-line.js";
 import { runExtension } from "./extension.js";
 import { INIT_AGENT_GUIDANCE_MODE_VALUES, runInitAgentGuidance, } from "./init-agent-guidance.js";
 import { findGitWorkspaceRoot, installMergeFence } from "./merge/install.js";
+/** Symbol key for the captured working directory of an in-process init call. */
+export const INIT_INVOCATION_CWD = Symbol.for("pm.sdk.init-invocation-cwd");
 /** Implements summarize init result for the public runtime surface of this module. */
 export function summarizeInitResult(result) {
     return {
@@ -709,9 +711,21 @@ async function installInitMergeFence(pmRoot, gitWorkspaceRoot, warnings, install
         warnings.push(`merge_fence_skipped:install_failed:${error.context.code ?? "pm_error"}:${error.message}:run pm merge install after resolving the Git repository error`);
     }
 }
+async function ensureInitWorkspaceGitignore(workspaceRoot, pmRoot, agentGuidanceMode, warnings) {
+    if (workspaceRoot === undefined ||
+        workspaceRoot === null ||
+        agentGuidanceMode === "status") {
+        return;
+    }
+    const gitignore = await ensurePmGitignore(workspaceRoot, { pmRoot });
+    if (gitignore.changed) {
+        warnings.push(`updated:gitignore:${gitignore.path}`);
+    }
+}
 /** Implements run init for the public runtime surface of this module. */
 export async function runInit(prefixArg, global, options = {}) {
-    const cwd = process.cwd();
+    const invocationCwd = global[INIT_INVOCATION_CWD];
+    const cwd = typeof invocationCwd === "string" ? invocationCwd : process.cwd();
     const invocation = resolveInitInvocation(cwd, global, prefixArg, options.workspace);
     const pmRoot = invocation.pmRoot;
     prefixArg = resolveInitPrefixInput(invocation.prefixArg, options.idPrefix);
@@ -773,12 +787,7 @@ export async function runInit(prefixArg, global, options = {}) {
         settings = await readSettings(pmRoot);
     }
     await ensureInitTypeDirectories({ pmRoot, settings, createdDirs, warnings });
-    if (workspaceRoot && normalizedOptions.agentGuidanceMode !== "status") {
-        const gitignore = await ensurePmGitignore(workspaceRoot, { pmRoot });
-        if (gitignore.changed) {
-            warnings.push(`updated:gitignore:${gitignore.path}`);
-        }
-    }
+    await ensureInitWorkspaceGitignore(workspaceRoot, pmRoot, normalizedOptions.agentGuidanceMode, warnings);
     if (!settingsExists &&
         options.mergeFence !== false &&
         normalizedOptions.agentGuidanceMode !== "status") {
@@ -809,4 +818,4 @@ export async function runInit(prefixArg, global, options = {}) {
     };
 }
 //# sourceMappingURL=init.js.map
-//# debugId=75c0d2d2-6a89-508f-b7dd-b43d55978b44
+//# debugId=d06d4db7-8ab7-5a9f-84df-508bd305ea23

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

@@ -7,7 +7,7 @@ import { type GlobalOptions, type RuntimeStatusRegistry } from "../runtime-primi
 import type { ContextDepth, ContextSectionName, ContextSettings, ItemMetadata, ItemStatus, PmSettings } from "../../types/index.js";
 import { type CalendarRow } from "./calendar.js";
 import { type CompactActivityEntry } from "./activity.js";
-import { type ContextRelevanceContributions, type ContextRelevanceReport, type ContextRelevanceSignalName } from "../context-relevance.js";
+import { type ContextRelevanceContributions, type ContextRecencyEvidence, type ContextRelevanceReport, type ContextRelevanceSignalName } from "../context-relevance.js";
 export { buildItemContextRelevanceCandidates } from "../context-relevance.js";
 import { type ContextPackingReport } from "../context-packing.js";
 import { type ContextSignalStoreReadResult } from "../context-signal-store.js";
@@ -398,6 +398,8 @@ export interface ContextRankingSummary {
         baseline_rank: number;
         score: number;
         contributions: ContextRelevanceContributions;
+        /** Authoritative temporal source used for the recency contribution. */
+        recency?: ContextRecencyEvidence;
     }>;
     /** Number of candidates considered before answer-sized projection. */
     candidate_count: number;

package/dist/sdk/query/context.js

@@ -4,7 +4,7 @@
  * Implements the pm context command surface and its agent-facing runtime behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="a870e3ac-f731-5cbf-a66e-38d1d5b1d0aa")}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]="56205e5f-fc26-59ab-abdf-45bdcaf1c263")}catch(e){}}();
 import { SETTINGS_DEFAULTS, EXIT_CODE, PmCliError, compareTimestampStrings, nowIso, isTerminalStatus, normalizeStatusForRegistry, normalizeStatusInput, resolveRuntimeStatusRegistry, resolvePmRoot, readSettings, resolveAuthor, discoverExtensions, } from "../runtime-primitives.js";
 import { collectDependencyBlockedIds, resolveItemBlockers, } from "../actionability.js";
 import { CONTEXT_DEPTH_VALUES, CONTEXT_SECTION_VALUES, } from "../../types/index.js";
@@ -17,7 +17,7 @@ export { buildItemContextRelevanceCandidates } from "../context-relevance.js";
 import { createQueryFingerprint, encodeQueryCursor, resolveQueryCursorStart, selectCursorSemanticOptions, } from "../pagination.js";
 import { CONTEXT_FLAG_CONTRACTS } from "../cli-contracts/flag-contracts.js";
 import { packContextCandidates, } from "../context-packing.js";
-import { readContextUsageAffinity, recordContextUsageServing, } from "../context-usage.js";
+import { attachContextUsageServingReceipt, collectContextUsageDeliveredItemIds, readContextUsageAffinity, recordContextUsageServing, } from "../context-usage.js";
 import { readWorkspaceContextSignals, } from "../context-signal-store.js";
 import { readWorkspaceMemory, selectWorkspaceMemory, } from "../workspace-memory.js";
 import { detectAgentIdentity } from "../../core/shared/author.js";
@@ -465,6 +465,9 @@ export function toContextRankingSummary(report, featureStore, servedItemIds) {
             baseline_rank: entry.baseline_rank,
             score: entry.score,
             contributions: entry.contributions,
+            ...(entry.signal_provenance === undefined
+                ? {}
+                : { recency: entry.signal_provenance.recency }),
         })),
         candidate_count: report.ranked.length,
         omitted_count: report.ranked.length - ranked.length,
@@ -1512,18 +1515,27 @@ function maybeAttachEmptyContextSuggestions(result, activeItems, blockedItems) {
 async function attachContextUsageFeedback(result, focusGroups, pmRoot, author) {
     try {
         const included = new Set(focusGroups.packing.included.map((entry) => entry.id));
-        await recordContextUsageServing({
+        const rows = focusGroups.ranking.ranked.map((entry) => ({
+            id: entry.id,
+            rank: entry.rank,
+            included: included.has(entry.id),
+        }));
+        const rankedIds = new Set(rows.map((row) => row.id));
+        for (const id of collectContextUsageDeliveredItemIds(result, "context")) {
+            if (!rankedIds.has(id)) {
+                rows.push({ id, rank: rows.length + 1, included: false });
+                rankedIds.add(id);
+            }
+        }
+        const receipt = await recordContextUsageServing({
             pmRoot,
             author,
             surface: "context",
             profile: focusGroups.packing.profile,
-            rows: focusGroups.ranking.ranked.map((entry) => ({
-                id: entry.id,
-                rank: entry.rank,
-                included: included.has(entry.id),
-            })),
+            rows,
             enabled: process.env.PM_CONTEXT_USAGE_DISABLED !== "1",
         });
+        attachContextUsageServingReceipt(result, receipt);
     }
     catch {
         result.warnings = mergeSortedWarnings(result.warnings, [
@@ -1676,4 +1688,4 @@ export async function runContext(options, global) {
     return result;
 }
 //# sourceMappingURL=context.js.map
-//# debugId=a870e3ac-f731-5cbf-a66e-38d1d5b1d0aa
+//# debugId=56205e5f-fc26-59ab-abdf-45bdcaf1c263