@unbrained/pm-cli 2026.7.18 → 2026.7.19

package/dist/cli-bundle/chunks/{chunk-2FUOXSRN.js → chunk-BFJP4VYC.js}

@@ -1,13 +1,13 @@
 import {
   verifyHistoryChain
-} from "./chunk-X5YCTFKT.js";
+} from "./chunk-RWAIRGBC.js";
 import {
   hashDocument
-} from "./chunk-646MQXFW.js";
+} from "./chunk-RLLOZAM2.js";
 import {
   getHistoryPath,
   writeFileAtomic
-} from "./chunk-WACRQ26A.js";
+} from "./chunk-WCBB6VI3.js";
 
 // dist/core/history/drift-scan.js
 import fs from "node:fs/promises";
@@ -207,4 +207,4 @@ async function scanHistoryDrift(pmRoot, items, options = {}) {
 export {
   scanHistoryDrift
 };
-//# sourceMappingURL=chunk-2FUOXSRN.js.map
+//# sourceMappingURL=chunk-BFJP4VYC.js.map

package/dist/cli-bundle/chunks/{chunk-633PKXLT.js → chunk-BZKE2O5V.js}

@@ -16,7 +16,7 @@ import {
   recordAfterCommandAffectedItem,
   runActiveOnWriteHooks,
   serializeItemDocument
-} from "./chunk-P22HGFFI.js";
+} from "./chunk-QFG4MB7P.js";
 import {
   EXIT_CODE,
   ITEM_METADATA_KEY_ORDER,
@@ -31,7 +31,7 @@ import {
   resolvePmRoot,
   resolveRuntimeStatusRegistry,
   writeFileAtomic
-} from "./chunk-KX62NMZC.js";
+} from "./chunk-D35WYXWC.js";
 
 // dist/cli/commands/copy.js
 function selectAuthor(explicitAuthor, settingsAuthor) {
@@ -172,6 +172,6 @@ async function runCopy(sourceId, options, global) {
 export {
   runCopy
 };
-//# sourceMappingURL=chunk-633PKXLT.js.map
+//# sourceMappingURL=chunk-BZKE2O5V.js.map
 
 //# debugId=10297567-d434-5182-abfd-6c340c9fde5c

package/dist/cli-bundle/chunks/{chunk-XPUTSGJU.js → chunk-CZA2DXCV.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]="dbfc61b1-b48d-5bdb-9bad-29d99b72c6b1")}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]="034a0471-7e4c-5b35-acaa-97c52368d9f4")}catch(e){}}();
 import {
   collectRuntimeFilterValues,
   matchesRuntimeFilters,
@@ -7,33 +7,30 @@ import {
   parsePriority,
   parseType,
   runList
-} from "./chunk-NCVT6XEL.js";
+} from "./chunk-YG56M3NE.js";
+import {
+  parseLimit
+} from "./chunk-FIUTBFC6.js";
 import {
   createQueryFingerprint,
   encodeQueryCursor,
   resolveQueryCursorStart
-} from "./chunk-2IPNL3DR.js";
+} from "./chunk-UOIFZ66L.js";
+import {
+  collectBlockedByIds,
+  collectDependencyBlockedIds,
+  computeActionabilityReport,
+  resolveItemBlockers
+} from "./chunk-6BNV3G6C.js";
 import {
   cloneEmptyReplayDocument,
   normalizeReplayPatchOps,
   readHistoryEntries,
   tryApplyReplayPatch,
   verifyHistoryChain
-} from "./chunk-KH6QAHME.js";
-import {
-  parseLimit
-} from "./chunk-PT7MCCGD.js";
-import {
-  readContextUsageAffinity,
-  recordContextUsageServing
-} from "./chunk-YJSURTBB.js";
-import {
-  collectBlockedByIds,
-  collectDependencyBlockedIds,
-  computeActionabilityReport,
-  resolveItemBlockers
-} from "./chunk-YFE7JHX3.js";
+} from "./chunk-M4B4RK4J.js";
 import {
+  acquireLock,
   compareTimestampStrings,
   enforceHistoryStreamPolicyForItem,
   enforceHistoryStreamPolicyForItems,
@@ -52,7 +49,7 @@ import {
   resolveIsoOrRelative,
   runActiveOnReadHooks,
   runActiveServiceOverride
-} from "./chunk-P22HGFFI.js";
+} from "./chunk-QFG4MB7P.js";
 import {
   CONTEXT_DEPTH_VALUES,
   CONTEXT_SECTION_VALUES,
@@ -68,22 +65,182 @@ import {
   resolveRuntimeFieldRegistry,
   resolveRuntimeStatusRegistry,
   weekdayOrderIndex
-} from "./chunk-KX62NMZC.js";
+} from "./chunk-D35WYXWC.js";
+
+// dist/sdk/context-usage.js
+import { randomUUID } from "node:crypto";
+import { appendFile, mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+var DEFAULT_MAX_EVENTS = 2048;
+var DEFAULT_RETENTION_DAYS = 30;
+var DAY_MS = 864e5;
+var DEFAULT_COMPACTION_BYTES = 262144;
+var CONTEXT_USAGE_LOCK_ID = "context-usage-ledger";
+function ledgerPath(pmRoot) {
+  return path.join(pmRoot, "runtime", "context-usage.jsonl");
+}
+function resolveNow(options) {
+  const iso = options.now ?? (/* @__PURE__ */ new Date()).toISOString();
+  const ms = Date.parse(iso);
+  if (!Number.isFinite(ms))
+    throw new TypeError("Context usage now must be a valid timestamp");
+  return { iso: new Date(ms).toISOString(), ms };
+}
+async function readEvents(options) {
+  try {
+    const text = await readFile(ledgerPath(options.pmRoot), "utf8");
+    const events = text.split("\n").filter(Boolean).flatMap((line) => {
+      try {
+        return [JSON.parse(line)];
+      } catch {
+        return [];
+      }
+    });
+    const maxEvents = options.maxEvents ?? DEFAULT_MAX_EVENTS;
+    const retentionDays = options.retentionDays ?? DEFAULT_RETENTION_DAYS;
+    const cutoff = resolveNow(options).ms - retentionDays * DAY_MS;
+    return events.filter((entry) => Date.parse(entry.at) >= cutoff).slice(-maxEvents);
+  } catch {
+    return [];
+  }
+}
+async function appendEvents(options, events) {
+  const maxEvents = options.maxEvents ?? DEFAULT_MAX_EVENTS;
+  const retentionDays = options.retentionDays ?? DEFAULT_RETENTION_DAYS;
+  if (!Number.isInteger(maxEvents) || maxEvents < 1 || !Number.isFinite(retentionDays) || retentionDays <= 0) {
+    throw new TypeError("Context usage retention requires positive maxEvents and retentionDays");
+  }
+  const target = ledgerPath(options.pmRoot);
+  const runtimeDirectory = path.dirname(target);
+  const releaseLock = await acquireLock(options.pmRoot, CONTEXT_USAGE_LOCK_ID, 30, `context-usage:${process.pid}`, false, false, 3e3);
+  try {
+    await mkdir(runtimeDirectory, { recursive: true });
+    await appendFile(target, events.map((event) => `${JSON.stringify(event)}
+`).join(""), "utf8");
+    const customBounds = options.maxEvents !== void 0 || options.retentionDays !== void 0;
+    if (!customBounds && (await stat(target)).size <= DEFAULT_COMPACTION_BYTES)
+      return;
+    const retained = await readEvents(options);
+    const temporary = `${target}.${process.pid}.${randomUUID()}.tmp`;
+    await writeFile(temporary, `${retained.map((entry) => JSON.stringify(entry)).join("\n")}
+`, "utf8");
+    await rename(temporary, target);
+  } finally {
+    await releaseLock();
+  }
+}
+async function appendEvent(options, event) {
+  await appendEvents(options, [event]);
+}
+async function recordContextUsageServing(options) {
+  if (process.env.PM_CONTEXT_USAGE_DISABLED === "1" || options.enabled === false)
+    return;
+  if (!options.author.trim() || options.rows.some((row) => !row.id.trim() || !Number.isInteger(row.rank) || row.rank < 1)) {
+    throw new TypeError("Context usage serving requires an author and valid ranked rows");
+  }
+  await appendEvent(options, {
+    kind: "serve",
+    at: resolveNow(options).iso,
+    author: options.author.trim(),
+    surface: options.surface,
+    profile: options.profile.trim() || "balanced",
+    rows: options.rows
+  });
+}
+async function recordContextUsageTouch(options) {
+  if (process.env.PM_CONTEXT_USAGE_DISABLED === "1" || options.enabled === false)
+    return;
+  if (!options.author.trim() || !options.itemId.trim() || !options.intent.trim()) {
+    throw new TypeError("Context usage touch requires author, itemId, and intent");
+  }
+  await appendEvent(options, {
+    kind: "touch",
+    at: resolveNow(options).iso,
+    author: options.author.trim(),
+    item_id: options.itemId.trim(),
+    intent: options.intent.trim()
+  });
+}
+async function recordContextUsageTouches(options) {
+  if (process.env.PM_CONTEXT_USAGE_DISABLED === "1" || options.enabled === false || options.itemIds.length === 0)
+    return;
+  const author = options.author.trim();
+  const intent = options.intent.trim();
+  if (!author || !intent) {
+    throw new TypeError("Context usage touch requires author and intent");
+  }
+  const itemIds = /* @__PURE__ */ new Set();
+  for (const itemId of options.itemIds) {
+    if (typeof itemId !== "string") {
+      throw new TypeError("Context usage touch requires string itemIds");
+    }
+    const trimmedId = itemId.trim();
+    if (!trimmedId)
+      throw new TypeError("Context usage touch requires non-empty itemId");
+    itemIds.add(trimmedId);
+  }
+  const at = resolveNow(options).iso;
+  const events = [...itemIds].map((itemId) => ({ kind: "touch", at, author, item_id: itemId, intent }));
+  await appendEvents(options, events);
+}
+function findTouchTimeInHorizon(touches, itemId, servedAt, horizonMs) {
+  return touches.find(({ entry, time }) => entry.item_id === itemId && time >= servedAt && time - servedAt <= horizonMs)?.time;
+}
+async function readContextUsageAffinity(options) {
+  if (process.env.PM_CONTEXT_USAGE_DISABLED === "1" || options.enabled === false)
+    return { affinity: {}, positive_judgments: 0, serving_events: 0 };
+  const events = await readEvents(options);
+  const now = resolveNow(options).ms;
+  const horizonMs = (options.horizonHours ?? 24) * 36e5;
+  if (!Number.isFinite(horizonMs) || horizonMs <= 0)
+    throw new TypeError("Context usage horizonHours must be positive");
+  const author = options.author.trim();
+  const touches = events.filter((event) => event.kind === "touch" && event.author === author).map((entry) => ({ entry, time: Date.parse(entry.at) }));
+  const scores = /* @__PURE__ */ new Map();
+  let servingEvents = 0;
+  let positiveJudgments = 0;
+  for (const event of events) {
+    if (event.kind !== "serve" || event.author !== author)
+      continue;
+    servingEvents += 1;
+    const servedAt = Date.parse(event.at);
+    for (const row of event.rows) {
+      if (!row.included)
+        continue;
+      const touchTime = findTouchTimeInHorizon(touches, row.id, servedAt, horizonMs);
+      if (touchTime === void 0)
+        continue;
+      positiveJudgments += 1;
+      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)
+  ]));
+  return {
+    affinity,
+    positive_judgments: positiveJudgments,
+    serving_events: servingEvents
+  };
+}
 
 // dist/core/history/history-diff.js
 function decodeJsonPointerSegment(segment) {
   return segment.replaceAll("~1", "/").replaceAll("~0", "~");
 }
-function patchPathToChangedField(path2) {
-  if (path2 === "/body" || path2.startsWith("/body/"))
+function patchPathToChangedField(path3) {
+  if (path3 === "/body" || path3.startsWith("/body/"))
     return "body";
-  if (path2 === "/metadata" || path2.startsWith("/metadata/") || path2 === "/front_matter" || path2.startsWith("/front_matter/")) {
-    const segment2 = path2.replace(/^\/(?:metadata|front_matter)\/?/, "").split("/")[0];
+  if (path3 === "/metadata" || path3.startsWith("/metadata/") || path3 === "/front_matter" || path3.startsWith("/front_matter/")) {
+    const segment2 = path3.replace(/^\/(?:metadata|front_matter)\/?/, "").split("/")[0];
     if (!segment2)
       return "metadata";
     return decodeJsonPointerSegment(segment2);
   }
-  const segment = path2.replace(/^\//, "").split("/")[0];
+  const segment = path3.replace(/^\//, "").split("/")[0];
   return segment ? decodeJsonPointerSegment(segment) : "root";
 }
 function readFieldValue(doc, field) {
@@ -260,7 +417,7 @@ async function runHistory(id, options, global) {
 
 // dist/cli/commands/activity.js
 import fs from "node:fs/promises";
-import path from "node:path";
+import path2 from "node:path";
 function parseNonEmptyFilter(raw, flagLabel) {
   if (raw === void 0)
     return void 0;
@@ -367,7 +524,7 @@ async function prepareActivityHistoryRead(context) {
     itemIds: items.map((item) => item.id),
     commandLabel: "activity"
   });
-  const historyDir = path.join(context.pmRoot, "history");
+  const historyDir = path2.join(context.pmRoot, "history");
   await runActiveOnReadHooks({
     path: historyDir,
     scope: "project"
@@ -390,7 +547,7 @@ async function collectActivityEntries(historyDir, filters) {
     if (filters.id && id !== filters.id) {
       continue;
     }
-    const entries = await readHistoryEntries(path.join(historyDir, file), id);
+    const entries = await readHistoryEntries(path2.join(historyDir, file), id);
     for (const entry of entries) {
       const candidate = normalizeActivityEntry(id, entry);
       if (includeActivityEntry(entry, candidate, filters)) {
@@ -2502,6 +2659,10 @@ function formatProjectedFocusLine(item, fields) {
   }).join(" ");
 }
 function formatAgendaLine(event) {
+  if ("reference_only" in event) {
+    const suffix = event.kind === "reminder" ? ` \u2014 ${event.reminder_text ?? "reminder"}` : event.kind === "event" ? ` \u2014 ${event.event_title ?? "event"}${event.event_recurring ? " (recurring)" : ""}` : "";
+    return `${formatClock2(event.at)} [${event.kind}] ${event.item_id} (see focus item)${suffix}`;
+  }
   const base = `${formatClock2(event.at)} [${event.kind}] ${event.item_id} p${event.item_priority} ${event.item_status} ${event.item_title}`;
   if (event.kind === "reminder") {
     return `${base} \u2014 ${event.reminder_text}`;
@@ -2841,7 +3002,7 @@ function buildContextCursorFingerprint(options) {
 function shouldPageContextFocus(options, corpusItemCount) {
   return options.limit !== void 0 || options.maxItems !== void 0 || options.after !== void 0 || corpusItemCount >= CONTEXT_SCALE_THRESHOLD;
 }
-async function buildContextAgenda(options, global, runtime, subtreeIds) {
+async function buildContextAgenda(options, global, runtime, subtreeIds, listedFocusIds) {
   const calendarOptions = {
     ...runtime.baseListOptions,
     view: "agenda",
@@ -2850,8 +3011,29 @@ async function buildContextAgenda(options, global, runtime, subtreeIds) {
   };
   const agenda = await runCalendar(calendarOptions, global);
   const scopedAgenda = subtreeIds === void 0 ? agenda.events : agenda.events.filter((event) => subtreeIds.has(event.item_id.trim().toLowerCase()));
-  const agendaEvents = filterTerminalCalendarEvents(scopedAgenda, runtime.statusRegistry).slice(0, runtime.limit);
-  return { agenda, agendaEvents, agendaSummary: summarizeAgenda(agendaEvents) };
+  const fullAgendaEvents = filterTerminalCalendarEvents(scopedAgenda, runtime.statusRegistry).slice(0, runtime.limit);
+  const agendaEvents = fullAgendaEvents.map((event) => {
+    if (!listedFocusIds.has(event.item_id)) {
+      return event;
+    }
+    return {
+      at: event.at,
+      date: event.date,
+      kind: event.kind,
+      item_id: event.item_id,
+      reference_only: true,
+      ...event.kind === "reminder" ? { reminder_text: event.reminder_text } : {},
+      ...event.kind === "event" ? {
+        event_title: event.event_title,
+        event_recurring: event.event_recurring
+      } : {}
+    };
+  });
+  return {
+    agenda,
+    agendaEvents,
+    agendaSummary: summarizeAgenda(fullAgendaEvents)
+  };
 }
 function countContextStatus(items, status, statusRegistry) {
   const targetStatus = String(status);
@@ -2966,7 +3148,11 @@ async function runContext(options, global) {
   const author = process.env.PM_AUTHOR ?? runtime.settings.author_default;
   const blockedIds = collectDependencyBlockedIds(corpus.fullCorpus, runtime.statusRegistry);
   const focusGroups = await resolveContextFocusGroups(corpus.listedItemMetadata, corpus.allItems, blockedIds, runtime.statusRegistry, runtime.sectionsIncluded, runtime.limit, nowIso(), author, options.after, buildContextCursorFingerprint(options), shouldPageContextFocus(options, corpus.fullCorpus.length), pmRoot);
-  const agendaContext = await buildContextAgenda(options, global, runtime, corpus.subtreeIds);
+  const agendaContext = await buildContextAgenda(options, global, runtime, corpus.subtreeIds, new Set([
+    ...focusGroups.highLevel,
+    ...focusGroups.lowLevel,
+    ...focusGroups.blockedFallback
+  ].map((item) => item.id)));
   const warnings = mergeSortedWarnings(corpus.listed.warnings, agendaContext.agenda.warnings, focusGroups.ranking.warnings);
   const inProgressCount = countContextStatus(focusGroups.activeItems, normalizeStatusInput("in_progress", runtime.statusRegistry), runtime.statusRegistry);
   const openCount = countContextStatus(focusGroups.activeItems, normalizeStatusInput("open", runtime.statusRegistry), runtime.statusRegistry);
@@ -3281,10 +3467,14 @@ async function rankReadyEntriesWithRelevance(rankedReady, childrenByParent, stat
     packing
   };
 }
+function resolveNextCallerAuthor(options, settingsAuthor) {
+  const requestedAssignee = options.assignee?.trim();
+  return options.callerAuthor ?? (requestedAssignee && requestedAssignee.length > 0 ? requestedAssignee : void 0) ?? process.env.PM_AUTHOR ?? settingsAuthor;
+}
 async function runNext(options, global) {
   const pmRoot = resolvePmRoot(process.cwd(), global.path);
   const settings = await readSettings(pmRoot);
-  const callerAuthor = options.callerAuthor ?? process.env.PM_AUTHOR ?? settings.author_default;
+  const callerAuthor = resolveNextCallerAuthor(options, settings.author_default);
   const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
   const now = nowIso();
   const limit = parseNextLimit(options.limit, "--limit", DEFAULT_NEXT_LIMIT);
@@ -3424,6 +3614,10 @@ function collectStaleVectorizationIds(items, ledgerEntries) {
 }
 
 export {
+  recordContextUsageServing,
+  recordContextUsageTouch,
+  recordContextUsageTouches,
+  readContextUsageAffinity,
   runHistory,
   runActivity,
   resolveCalendarOutputFormat,
@@ -3447,12 +3641,12 @@ export {
   resolveContextOutputFormat,
   renderContextMarkdown,
   runContext,
-  collectStaleVectorizationIds,
   NEXT_OUTPUT_VALUES,
   resolveNextOutputFormat,
   runNext,
-  renderNextMarkdown
+  renderNextMarkdown,
+  collectStaleVectorizationIds
 };
-//# sourceMappingURL=chunk-XPUTSGJU.js.map
+//# sourceMappingURL=chunk-CZA2DXCV.js.map
 
-//# debugId=dbfc61b1-b48d-5bdb-9bad-29d99b72c6b1
+//# debugId=034a0471-7e4c-5b35-acaa-97c52368d9f4