@unbrained/pm-cli 2026.7.6 → 2026.7.8

package/dist/sdk/start-task-status.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @module sdk/start-task-status
+ *
+ * Resolves lifecycle alias status transitions shared by CLI registration and the SDK runtime.
+ */
+import { type RuntimeStatusRegistry } from "../core/schema/runtime-schema.js";
+/**
+ * Resolve the status the `start-task` lifecycle alias should move an item to.
+ * Resolves `in_progress` strictly through the workspace registry so a custom
+ * workflow that omits in_progress falls back to its open status instead of
+ * setting a status the workflow does not define.
+ */
+export declare function resolveStartTaskInProgressStatus(statusRegistry: RuntimeStatusRegistry): string;

package/dist/sdk/start-task-status.js

@@ -0,0 +1,19 @@
+/**
+ * @module sdk/start-task-status
+ *
+ * Resolves lifecycle alias status transitions shared by CLI registration and the SDK runtime.
+ */
+
+!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]="71e8629b-d857-5bd5-862b-c65662265a2f")}catch(e){}}();
+import { normalizeStatusInputWithRegistry, } from "../core/schema/runtime-schema.js";
+/**
+ * Resolve the status the `start-task` lifecycle alias should move an item to.
+ * Resolves `in_progress` strictly through the workspace registry so a custom
+ * workflow that omits in_progress falls back to its open status instead of
+ * setting a status the workflow does not define.
+ */
+export function resolveStartTaskInProgressStatus(statusRegistry) {
+    return normalizeStatusInputWithRegistry("in_progress", statusRegistry) ?? statusRegistry.open_status;
+}
+//# sourceMappingURL=start-task-status.js.map
+//# debugId=71e8629b-d857-5bd5-862b-c65662265a2f

package/dist/sdk/start-task-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"start-task-status.js","sources":["sdk/start-task-status.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module sdk/start-task-status\n *\n * Resolves lifecycle alias status transitions shared by CLI registration and the SDK runtime.\n */\nimport {\n  normalizeStatusInputWithRegistry,\n  type RuntimeStatusRegistry,\n} from \"../core/schema/runtime-schema.js\";\n\n/**\n * Resolve the status the `start-task` lifecycle alias should move an item to.\n * Resolves `in_progress` strictly through the workspace registry so a custom\n * workflow that omits in_progress falls back to its open status instead of\n * setting a status the workflow does not define.\n */\nexport function resolveStartTaskInProgressStatus(statusRegistry: RuntimeStatusRegistry): string {\n  return normalizeStatusInputWithRegistry(\"in_progress\", statusRegistry) ?? statusRegistry.open_status;\n}\n"],"names":[],"mappings":"AAAA;;;;GAIG;;;AACH,OAAO,EACL,gCAAgC,GAEjC,MAAM,kCAAkC,CAAC;AAE1C;;;;;GAKG;AACH,MAAM,UAAU,gCAAgC,CAAC,cAAqC;IACpF,OAAO,gCAAgC,CAAC,aAAa,EAAE,cAAc,CAAC,IAAI,cAAc,CAAC,WAAW,CAAC;AACvG,CAAC","debugId":"71e8629b-d857-5bd5-862b-c65662265a2f"}

package/docs/COMMANDS.md

@@ -462,6 +462,13 @@ pm pause-task <id>             # move to open + release claim
 pm close-task <id> "<reason>"  # close + release assignment
 ```
 
+For lifecycle ownership commands, `--assignee <agent>` is accepted as an alias
+for `--author <agent>` on `claim`, `release`, `start-task`, `pause-task`, and
+`close-task`. Use `pm update --assignee <person>` when changing item metadata
+rather than active work ownership.
+
+Tracker references: [pm-qfte](../.agents/pm/tasks/pm-qfte.toon), [pm-98cz](../.agents/pm/features/pm-98cz.toon).
+
 After `pm create` of a workable item type, the result includes a non-binding `next_transition` hint (`pm start-task <id>` → `in_progress`) when the workflow defines a distinct in-progress status. This nudges agents to move work through `in_progress` instead of jumping straight from `open` to `closed`. Scheduling/reference types (Event, Meeting, Reminder, Milestone, Decision) never receive the hint. (GH-216)
 
 ## Scheduling Shortcuts
@@ -488,7 +495,9 @@ pm release <id>
 pm release <id> --allow-audit-release --author <you>
 ```
 
-`claim` is the normal start signal. Use `--force` only when explicitly overriding terminal-state or lock conflicts.
+`claim` is the normal start signal. `--assignee` is an ownership alias for
+`--author` on claim/release flows, not a metadata update. Use `--force` only when
+explicitly overriding terminal-state or lock conflicts.
 
 ## Logs
 

package/docs/EXTENSIONS.md

@@ -179,16 +179,9 @@ useful for agents without inflating context or leaking private item content.
 
 ## Extension Manifest
 
-Runnable manifest examples are the source of truth:
+Runnable manifest examples are the source of truth: [starter extension manifest](examples/starter-extension/manifest.json) and [policy-restricted manifest](examples/policy-restricted-extension/manifest.json).
 
-- [starter extension manifest](examples/starter-extension/manifest.json)
-- [policy-restricted manifest](examples/policy-restricted-extension/manifest.json)
-
-Schema:
-
-- Use [extension-manifest.schema.json](schemas/extension-manifest.schema.json) as the
-  `$schema` value for inline editor validation. The loader ignores `$schema` and
-  tolerates future manifest fields, but the schema documents the fields pm reads.
+Use [extension-manifest.schema.json](schemas/extension-manifest.schema.json) as the `$schema` value for inline editor validation. The loader ignores `$schema` and tolerates future manifest fields, but the schema documents the fields pm reads.
 
 Rules:
 
@@ -347,9 +340,12 @@ Run diagnostics:
 ```bash
 pm package doctor --project --detail summary
 pm package doctor --project --detail deep --trace
+pm package doctor --project --isolated --detail deep --trace
 pm package doctor --project --strict-exit
 ```
 
+Use `--isolated` (alias `--ignore-global`) when a package smoke test must inspect only the project install. Non-isolated project diagnostics include global registrations and emit an isolation remediation hint when global package state can affect the result; subprocess-based test suites can also set `PM_GLOBAL_PATH` to a temporary directory for the whole run.
+
 Manage state and update checks:
 
 ```bash
@@ -359,22 +355,12 @@ pm package adopt my-extension --project
 pm package adopt-all --project
 ```
 
-Activate or deactivate:
+Activate, deactivate, uninstall, and reload:
 
 ```bash
 pm package activate my-extension --project
 pm package deactivate my-extension --project
-```
-
-Uninstall:
-
-```bash
 pm package uninstall my-extension --project
-```
-
-Reload local edits:
-
-```bash
 pm package reload --project
 pm package reload --project --watch
 ```
@@ -432,6 +418,7 @@ Prefer `createExtensionTestHarness(module, { capabilities })` in package unit te
 
 - Manifest or entry failure: run `pm package explore --project`.
 - Activation failure: run `pm package doctor --detail deep --trace`.
+- Machine-dependent package diagnostics: run `pm package doctor --project --isolated --detail deep --trace` or set `PM_GLOBAL_PATH` to a temp directory.
 - Policy block: inspect `settings.extensions.policy` and `details.summary.policy`.
 - Runtime drift: compare with `pm --no-extensions <command>`.
 - Managed-state update-check gap: run `pm package manage --fix-managed-state`.

package/docs/RELEASING.md

@@ -139,6 +139,12 @@ Minimum coverage:
 
 Use maintainer-only local workflows for reliability checks and incident triage. Keep operational details, infrastructure topology, and raw diagnostics out of tracked release documentation and release notes.
 
+Run the public Sentry/telemetry threshold gate through the package script alias:
+
+```bash
+pnpm sentry:telemetry:gate -- --telemetry-mode best-effort
+```
+
 If private reliability checks identify repeated user friction, either confirm the current release already contains the remediation with regression coverage or fix it before continuing.
 
 4. Run the same release pipeline locally.

package/docs/SDK.md

@@ -10,6 +10,10 @@ Use it for extension authoring, package authoring, command/action contract disco
 npm install @unbrained/pm-cli
 ```
 
+The SDK ships inside the CLI package. There is no separate
+`@unbrained/pm-sdk` package; package authors should depend on
+`@unbrained/pm-cli` and import the public subpaths below.
+
 ## Import Surfaces
 
 ```ts
@@ -100,6 +104,10 @@ Storage format-version exports (under `@unbrained/pm-cli/sdk/runtime`):
 Command/action contract exports:
 
 - `PmClient` / `runAction` (high-level in-process action execution for custom tools, bots, CI, and embedded runtimes)
+- Typed read primitives on `PmClient`: `get`, `list`, `search`, `context`, `next`, `aggregate`, and `stats`
+- Read primitive option/result contracts: `GetOptions` / `GetResult`, `ListOptions` / `ListResult`, `SearchOptions` / `SearchResult`, `ContextOptions` / `ContextResult`, `NextOptions` / `NextResult`, `AggregateOptions` / `AggregateResult`, `StatsCommandOptions` / `StatsResult`
+- Typed package and extension lifecycle primitives on `PmClient`: `extension`, `extensionList`, `extensionActivate`, `extensionDeactivate`, `package`, `packageList`, `packageInstall`, `packageUninstall`, `packageDoctor`, `packageManage`, `packageDescribe`, `packageReload`, `packageCatalog`, `packageActivate`, `packageDeactivate`, and `upgrade`
+- Lifecycle primitive option/result contracts: `ExtensionCommandOptions` / `ExtensionCommandResult`, `PackageCommandOptions` / `PackageCommandResult`, `UpgradeCommandOptions` / `UpgradeResult`
 - `PM_CORE_COMMAND_NAMES`
 - `PM_TOOL_ACTIONS`
 - `PM_TOOL_PARAMETERS_SCHEMA`
@@ -436,7 +444,15 @@ const created = await pm.create({
   status: "open",
   createMode: "progressive",
 });
+await pm.claim(created.item.id, { author: "ci-agent" });
+await pm.update(created.item.id, { status: "in_progress" });
 const open = await pm.list({ status: "open", limit: "20" });
+const recommendation = await pm.next({ readyOnly: true });
+const grouped = await pm.aggregate({ groupBy: "status", count: true });
+const stats = await pm.stats({ metadataCoverage: true });
+const packages = await pm.packageList({ project: true });
+const doctor = await pm.packageDoctor({ project: true, isolated: true });
+const plannedUpgrade = await pm.upgrade(undefined, { dryRun: true, cliOnly: true });
 
 await runAction({
   action: "context",
@@ -449,6 +465,42 @@ Mutation convenience methods default to compact changed-field output for agent
 efficiency. Pass `fullChangedFields: true` alongside the command options when an
 embedded SDK consumer needs the full `changed_fields` array.
 
+Read convenience methods and the matching top-level read functions (`get`,
+`list`, `search`, `context`, `next`, `aggregate`, `stats`) are foundational
+SDK PM primitives: they return the same structured data the CLI/MCP surfaces
+use, but with stable TypeScript contracts exported from
+`@unbrained/pm-cli/sdk` and `@unbrained/pm-cli/sdk/runtime`. Use them instead of
+spawning `pm get`, `pm list`, `pm search`, `pm context`, `pm next`,
+`pm aggregate`, or `pm stats` when building a custom project-management tool, CI
+integration, or agent runtime. Presentation stays outside the SDK primitive:
+callers choose their own rendering while the data shape remains shared with the
+CLI.
+
+Lifecycle convenience methods and the matching top-level functions (`create`,
+`update`, `close`, `claim`, `release`, `copy`, `deleteItem`, `restore`,
+`focus`, `startTask`, `pauseTask`, and `closeTask`) use the same mutation paths
+as the CLI and MCP dispatcher. They are the baseline primitives for custom PM
+tools that need to own item state without spawning `pm`.
+
+Package and extension lifecycle convenience methods are the SDK primitive layer
+for custom PM tools that need to manage their own package surface without
+shelling out. Use `pm.packageList`, `pm.packageInstall`,
+`pm.packageUninstall`, `pm.packageDoctor`, `pm.packageManage`,
+`pm.packageDescribe`, `pm.packageReload`, `pm.packageCatalog`,
+`pm.packageActivate`, `pm.packageDeactivate`, and `pm.upgrade` for package-mode
+automation; use `pm.extensionList`, `pm.extensionActivate`, and
+`pm.extensionDeactivate` when the UI vocabulary is explicitly extension-focused.
+The matching top-level helpers (`packageLifecycle`, `packageList`,
+`packageInstall`, `packageUninstall`, `packageDoctor`, `packageManage`,
+`packageDescribe`, `packageReload`, `packageCatalog`, `packageActivate`,
+`packageDeactivate`, `extension`, `extensionList`, `extensionActivate`,
+`extensionDeactivate`, and `upgrade`) construct a short-lived `PmClient` for
+one-off calls. Package helpers return `PackageCommandResult` and extension
+helpers return `ExtensionCommandResult`; both names describe the same lifecycle
+payload shape with vocabulary-appropriate SDK signatures. `UpgradeResult` is the
+same structured payload rendered by the CLI, so embedded tools can own their
+presentation layer while sharing pm's package/install/doctor semantics.
+
 `PmClient` and `runAction` share the same process-wide extension activation
 queue as MCP. Calls from one process are serialized across extension load,
 activation, dispatch, cleanup, and deactivate so active extension registries stay
@@ -461,8 +513,15 @@ command options only. For per-call runtime overrides such as `cwd`, `path`, or
 
 ```ts
 await pm.run("list", { cwd: "/path/to/project", options: { status: "open" } });
+await pm.run("create", { title: "Capture SDK input", type: "Task" });
 ```
 
+For `create`, `PmClient.run` also accepts the common structured top-level item
+keys (`title`, `type`, `status`, `description`, `body`, `priority`, `tags`,
+`parent`, `createMode`, and `allowMissingParent`) and maps them to command
+options. This keeps dynamic SDK callers ergonomic while the typed `pm.create`
+method remains the preferred fully documented path.
+
 For item-type context, use the CLI inspection primitives before issuing custom-domain mutations:
 
 ```bash
@@ -544,9 +603,15 @@ Some override surfaces are single-winner: command overrides, parser overrides, p
 
 ```bash
 pm package doctor --project --detail deep --trace
+pm package doctor --project --isolated --detail deep --trace
 pm health --check-only --brief
 ```
 
+Use `--isolated` (alias `--ignore-global`) for hermetic package smoke tests:
+project diagnostics skip global registrations and avoid machine-local
+renderer/service overrides. The same isolation can be applied to a whole
+subprocess suite by setting `PM_GLOBAL_PATH` to a temporary directory.
+
 Collision warnings are deterministic and include package names plus deactivation guidance.
 If extension code calls a `register*` API without declaring the matching
 manifest capability, activation fails with

package/docs/TESTING.md

@@ -151,6 +151,9 @@ a failing package root.
 ## PM Context Modes
 
 Linked PM commands default to schema context: settings and extensions are seeded, but tracker item data stays isolated.
+When a linked command is a PM tracker-read such as `pm validate`, the default mismatch error suggests
+`--auto-pm-context`, which keeps schema isolation for ordinary commands and routes only tracker-read PM commands
+through seeded tracker data.
 
 Use explicit modes when needed:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.7.6",
+  "version": "2026.7.8",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",
@@ -103,6 +103,7 @@
     "review:greptile:gate": "node scripts/release/greptile-review-gate.mjs",
     "security:scan": "node scripts/check-secrets.mjs",
     "smoke:npx": "node scripts/smoke-npx-from-pack.mjs",
+    "sentry:telemetry:gate": "node scripts/release/sentry-telemetry-gate.mjs",
     "sentry:inject": "sentry-cli sourcemaps inject dist/",
     "sentry:upload": "sentry-cli sourcemaps upload --org unbrained --project pm-cli --release \"pm-cli@$npm_package_version\" --validate dist/",
     "build:sentry": "pnpm build && pnpm sentry:inject && pnpm sentry:upload",

package/dist/cli-bundle/chunks/activity-WJCGCYPU.js

@@ -1,18 +0,0 @@
-import {
-  _testOnly,
-  runActivity
-} from "./chunk-2XG4IZON.js";
-import "./chunk-L5PSPMZ4.js";
-import "./chunk-XUC7PI2H.js";
-import "./chunk-7DT4WSH2.js";
-import "./chunk-5VAA4YHR.js";
-import "./chunk-NMP5I3I5.js";
-import "./chunk-FLZSGSQR.js";
-import "./chunk-SHQY2IDC.js";
-import "./chunk-7C2O74AE.js";
-import "./chunk-LK6XLOGP.js";
-export {
-  _testOnly,
-  runActivity
-};
-//# sourceMappingURL=activity-WJCGCYPU.js.map

package/dist/cli-bundle/chunks/activity-Z6QUAUSG.js

@@ -1,22 +0,0 @@
-
-!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]="45eac7fa-f181-5cca-93b7-cfb58909dbb3")}catch(e){}}();
-import {
-  _testOnly,
-  runActivity
-} from "./chunk-WRTENIX3.js";
-import "./chunk-IX5BXEMX.js";
-import "./chunk-OGWQ2IEP.js";
-import "./chunk-22KBU3MW.js";
-import "./chunk-ENGQOEUY.js";
-import "./chunk-G24G7ZAV.js";
-import "./chunk-3GCS5SKL.js";
-import "./chunk-E3SZTQ4K.js";
-import "./chunk-NNHHXJB2.js";
-import "./chunk-57NWPFF2.js";
-export {
-  _testOnly,
-  runActivity
-};
-//# sourceMappingURL=activity-Z6QUAUSG.js.map
-
-//# debugId=45eac7fa-f181-5cca-93b7-cfb58909dbb3

package/dist/cli-bundle/chunks/aggregate-BDM6EIAR.js

@@ -1,25 +0,0 @@
-
-!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]="45eac7fa-f181-5cca-93b7-cfb58909dbb3")}catch(e){}}();
-import {
-  _testOnlyAggregateCommand,
-  runAggregate
-} from "./chunk-VQRSPVME.js";
-import "./chunk-VY3VQ22F.js";
-import "./chunk-3VHSI5FL.js";
-import "./chunk-QB7XMHJW.js";
-import "./chunk-MVYWGY2A.js";
-import "./chunk-22KBU3MW.js";
-import "./chunk-P4SESZGT.js";
-import "./chunk-ENGQOEUY.js";
-import "./chunk-G24G7ZAV.js";
-import "./chunk-3GCS5SKL.js";
-import "./chunk-E3SZTQ4K.js";
-import "./chunk-NNHHXJB2.js";
-import "./chunk-57NWPFF2.js";
-export {
-  _testOnlyAggregateCommand,
-  runAggregate
-};
-//# sourceMappingURL=aggregate-BDM6EIAR.js.map
-
-//# debugId=45eac7fa-f181-5cca-93b7-cfb58909dbb3

package/dist/cli-bundle/chunks/aggregate-VQ2DHU3S.js

@@ -1,21 +0,0 @@
-import {
-  _testOnlyAggregateCommand,
-  runAggregate
-} from "./chunk-KERMZVY5.js";
-import "./chunk-4BU75MF4.js";
-import "./chunk-46CUF5L6.js";
-import "./chunk-R23CSHGI.js";
-import "./chunk-JDDLOQAE.js";
-import "./chunk-7DT4WSH2.js";
-import "./chunk-5HIZDR5A.js";
-import "./chunk-5VAA4YHR.js";
-import "./chunk-NMP5I3I5.js";
-import "./chunk-FLZSGSQR.js";
-import "./chunk-SHQY2IDC.js";
-import "./chunk-7C2O74AE.js";
-import "./chunk-LK6XLOGP.js";
-export {
-  _testOnlyAggregateCommand,
-  runAggregate
-};
-//# sourceMappingURL=aggregate-VQ2DHU3S.js.map

package/dist/cli-bundle/chunks/append-RKJYPU74.js

@@ -1,15 +0,0 @@
-import {
-  runAppend
-} from "./chunk-XHET7YUZ.js";
-import "./chunk-AZYGZGGI.js";
-import "./chunk-WW4E2DC3.js";
-import "./chunk-5VAA4YHR.js";
-import "./chunk-NMP5I3I5.js";
-import "./chunk-FLZSGSQR.js";
-import "./chunk-SHQY2IDC.js";
-import "./chunk-7C2O74AE.js";
-import "./chunk-LK6XLOGP.js";
-export {
-  runAppend
-};
-//# sourceMappingURL=append-RKJYPU74.js.map

package/dist/cli-bundle/chunks/chunk-2XG4IZON.js

@@ -1,218 +0,0 @@
-import {
-  readHistoryEntries
-} from "./chunk-L5PSPMZ4.js";
-import {
-  parseLimit
-} from "./chunk-7DT4WSH2.js";
-import {
-  enforceHistoryStreamPolicyForItems,
-  listAllFrontMatterLight
-} from "./chunk-5VAA4YHR.js";
-import {
-  compareTimestampStrings,
-  nowIso,
-  resolveIsoOrRelative
-} from "./chunk-FLZSGSQR.js";
-import {
-  PmCliError,
-  getActiveExtensionRegistrations,
-  readSettings,
-  runActiveOnReadHooks
-} from "./chunk-SHQY2IDC.js";
-import {
-  EXIT_CODE,
-  getSettingsPath,
-  pathExists,
-  resolveItemTypeRegistry,
-  resolvePmRoot
-} from "./chunk-LK6XLOGP.js";
-
-// dist/cli/commands/activity.js
-import fs from "node:fs/promises";
-import path from "node:path";
-!(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] = "91b14d48-c94f-5b8a-b8d6-4276059f6061");
-  } catch (e2) {
-  }
-})();
-function parseNonEmptyFilter(raw, flagLabel) {
-  if (raw === void 0)
-    return void 0;
-  const normalized = raw.trim();
-  if (normalized.length === 0) {
-    throw new PmCliError(`${flagLabel} must not be empty`, EXIT_CODE.USAGE);
-  }
-  return normalized;
-}
-function parseRangeBound(raw, nowValue, fieldLabel) {
-  if (raw === void 0)
-    return void 0;
-  const normalized = raw.trim();
-  if (normalized.length === 0) {
-    throw new PmCliError("Activity time bounds must not be empty", EXIT_CODE.USAGE);
-  }
-  return resolveIsoOrRelative(normalized, new Date(nowValue), fieldLabel);
-}
-function includeByTimeWindow(entry, from, to) {
-  if (entry.ts.length === 0 && (from || to)) {
-    return false;
-  }
-  if (from && compareTimestampStrings(entry.ts, from) < 0) {
-    return false;
-  }
-  if (to && compareTimestampStrings(entry.ts, to) >= 0) {
-    return false;
-  }
-  return true;
-}
-function limitEntries(values, limit) {
-  if (limit === void 0)
-    return values;
-  return values.slice(0, limit);
-}
-function readActivityString(value, fallback = "") {
-  return typeof value === "string" ? value : fallback;
-}
-function normalizeActivityEntry(id, entry) {
-  return {
-    ...entry,
-    id,
-    ts: readActivityString(entry.ts),
-    author: readActivityString(entry.author, "unknown"),
-    op: readActivityString(entry.op, "unknown"),
-    patch: Array.isArray(entry.patch) ? entry.patch : [],
-    before_hash: readActivityString(entry.before_hash),
-    after_hash: readActivityString(entry.after_hash)
-  };
-}
-function sortActivity(entries) {
-  return [...entries].sort((a, b) => {
-    const byTimestamp = b.ts.localeCompare(a.ts);
-    if (byTimestamp !== 0)
-      return byTimestamp;
-    const byId = a.id.localeCompare(b.id);
-    if (byId !== 0)
-      return byId;
-    return a.op.localeCompare(b.op);
-  });
-}
-async function listHistoryFiles(historyDir) {
-  try {
-    return (await fs.readdir(historyDir)).filter((entry) => entry.endsWith(".jsonl")).sort((a, b) => a.localeCompare(b));
-  } catch (error) {
-    if (error.code === "ENOENT") {
-      return [];
-    }
-    throw error;
-  }
-}
-function resolveActivityFilters(options) {
-  const nowValue = nowIso();
-  const from = parseRangeBound(options.from, nowValue, "--from");
-  const to = parseRangeBound(options.to, nowValue, "--to");
-  if (from && to && compareTimestampStrings(from, to) >= 0) {
-    throw new PmCliError("Activity --from must be before --to", EXIT_CODE.USAGE);
-  }
-  return {
-    id: parseNonEmptyFilter(options.id, "Activity --id"),
-    op: parseNonEmptyFilter(options.op, "Activity --op"),
-    author: parseNonEmptyFilter(options.author, "Activity --author"),
-    from,
-    to,
-    limit: parseLimit(options.limit)
-  };
-}
-async function resolveActivityRuntimeContext(global2) {
-  const pmRoot = resolvePmRoot(process.cwd(), global2.path);
-  if (!await pathExists(getSettingsPath(pmRoot))) {
-    throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
-  }
-  return {
-    pmRoot,
-    settings: await readSettings(pmRoot)
-  };
-}
-async function prepareActivityHistoryRead(context) {
-  const typeRegistry = resolveItemTypeRegistry(context.settings, getActiveExtensionRegistrations());
-  const items = await listAllFrontMatterLight(context.pmRoot, context.settings.item_format, typeRegistry.type_to_folder, void 0, context.settings.schema);
-  await enforceHistoryStreamPolicyForItems({
-    pmRoot: context.pmRoot,
-    settings: context.settings,
-    itemIds: items.map((item) => item.id),
-    commandLabel: "activity"
-  });
-  const historyDir = path.join(context.pmRoot, "history");
-  await runActiveOnReadHooks({
-    path: historyDir,
-    scope: "project"
-  });
-  return historyDir;
-}
-function includeActivityEntry(entry, candidate, filters) {
-  if (filters.op && entry.op !== filters.op) {
-    return false;
-  }
-  if (filters.author && entry.author !== filters.author) {
-    return false;
-  }
-  return includeByTimeWindow(candidate, filters.from, filters.to);
-}
-async function collectActivityEntries(historyDir, filters) {
-  const combined = [];
-  for (const file of await listHistoryFiles(historyDir)) {
-    const id = file.slice(0, -".jsonl".length);
-    if (filters.id && id !== filters.id) {
-      continue;
-    }
-    const entries = await readHistoryEntries(path.join(historyDir, file), id);
-    for (const entry of entries) {
-      const candidate = normalizeActivityEntry(id, entry);
-      if (includeActivityEntry(entry, candidate, filters)) {
-        combined.push(candidate);
-      }
-    }
-  }
-  return combined;
-}
-function formatCompactActivity(activity) {
-  return activity.map((entry) => ({
-    id: entry.id,
-    op: entry.op,
-    ts: entry.ts,
-    author: entry.author,
-    ...entry.message ? { msg: entry.message } : {}
-  }));
-}
-var _testOnly = {
-  parseNonEmptyFilter,
-  parseRangeBound,
-  includeByTimeWindow,
-  limitEntries,
-  readActivityString,
-  normalizeActivityEntry,
-  sortActivity,
-  listHistoryFiles
-};
-async function runActivity(options, global2) {
-  const context = await resolveActivityRuntimeContext(global2);
-  const filters = resolveActivityFilters(options);
-  const historyDir = await prepareActivityHistoryRead(context);
-  const activity = limitEntries(sortActivity(await collectActivityEntries(historyDir, filters)), filters.limit);
-  const compact = options.compact === true;
-  const compactActivity = compact ? formatCompactActivity(activity) : void 0;
-  return {
-    activity: compact ? [] : activity,
-    compact_activity: compactActivity,
-    compact,
-    count: activity.length,
-    limit: filters.limit ?? null
-  };
-}
-
-export {
-  _testOnly,
-  runActivity
-};
-//# sourceMappingURL=chunk-2XG4IZON.js.map

package/dist/cli-bundle/chunks/chunk-2XG4IZON.js.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../../../../../../../cli/commands/activity.ts"],
-  "sourcesContent": ["/**\n * @module cli/commands/activity\n *\n * Implements the pm activity command surface and its agent-facing runtime behavior.\n */\nimport fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { getActiveExtensionRegistrations, runActiveOnReadHooks } from \"../../core/extensions/index.js\";\nimport { pathExists } from \"../../core/fs/fs-utils.js\";\nimport { enforceHistoryStreamPolicyForItems } from \"../../core/history/history-stream-policy.js\";\nimport { resolveItemTypeRegistry } from \"../../core/item/type-registry.js\";\nimport { EXIT_CODE } from \"../../core/shared/constants.js\";\nimport type { GlobalOptions } from \"../../core/shared/command-types.js\";\nimport { PmCliError } from \"../../core/shared/errors.js\";\nimport { compareTimestampStrings, nowIso, resolveIsoOrRelative } from \"../../core/shared/time.js\";\nimport { listAllFrontMatterLight } from \"../../core/store/item-store.js\";\nimport { getSettingsPath, resolvePmRoot } from \"../../core/store/paths.js\";\nimport { readSettings } from \"../../core/store/settings.js\";\nimport { readHistoryEntries } from \"./history.js\";\nimport { parseLimit } from \"../shared-parsers.js\";\nimport type { HistoryEntry } from \"../../types/index.js\";\n\n/**\n * Documents the activity command options payload exchanged by command, SDK, and package integrations.\n */\nexport interface ActivityCommandOptions {\n  id?: string;\n  op?: string;\n  author?: string;\n  from?: string;\n  to?: string;\n  limit?: string;\n  compact?: boolean;\n}\n\n/**\n * Documents the activity entry payload exchanged by command, SDK, and package integrations.\n */\nexport interface ActivityEntry extends HistoryEntry {\n  id: string;\n}\n\n/**\n * Documents the compact activity entry payload exchanged by command, SDK, and package integrations.\n */\nexport interface CompactActivityEntry {\n  id: string;\n  op: string;\n  ts: string;\n  author: string;\n  msg?: string;\n}\n\n/**\n * Documents the activity result payload exchanged by command, SDK, and package integrations.\n */\nexport interface ActivityResult {\n  activity: ActivityEntry[];\n  compact_activity?: CompactActivityEntry[];\n  compact: boolean;\n  count: number;\n  limit: number | null;\n}\n\ninterface ActivityFilters {\n  id: string | undefined;\n  op: string | undefined;\n  author: string | undefined;\n  from: string | undefined;\n  to: string | undefined;\n  limit: number | undefined;\n}\n\ninterface ActivityRuntimeContext {\n  pmRoot: string;\n  settings: Awaited<ReturnType<typeof readSettings>>;\n}\n\nfunction parseNonEmptyFilter(raw: string | undefined, flagLabel: string): string | undefined {\n  if (raw === undefined) return undefined;\n  const normalized = raw.trim();\n  if (normalized.length === 0) {\n    throw new PmCliError(`${flagLabel} must not be empty`, EXIT_CODE.USAGE);\n  }\n  return normalized;\n}\n\nfunction parseRangeBound(raw: string | undefined, nowValue: string, fieldLabel: string): string | undefined {\n  if (raw === undefined) return undefined;\n  const normalized = raw.trim();\n  if (normalized.length === 0) {\n    throw new PmCliError(\"Activity time bounds must not be empty\", EXIT_CODE.USAGE);\n  }\n  return resolveIsoOrRelative(normalized, new Date(nowValue), fieldLabel);\n}\n\nfunction includeByTimeWindow(entry: ActivityEntry, from: string | undefined, to: string | undefined): boolean {\n  if (entry.ts.length === 0 && (from || to)) {\n    return false;\n  }\n  if (from && compareTimestampStrings(entry.ts, from) < 0) {\n    return false;\n  }\n  if (to && compareTimestampStrings(entry.ts, to) >= 0) {\n    return false;\n  }\n  return true;\n}\n\nfunction limitEntries<T>(values: T[], limit: number | undefined): T[] {\n  if (limit === undefined) return values;\n  return values.slice(0, limit);\n}\n\nfunction readActivityString(value: unknown, fallback = \"\"): string {\n  return typeof value === \"string\" ? value : fallback;\n}\n\nfunction normalizeActivityEntry(id: string, entry: HistoryEntry): ActivityEntry {\n  return {\n    ...entry,\n    id,\n    ts: readActivityString(entry.ts),\n    author: readActivityString(entry.author, \"unknown\"),\n    op: readActivityString(entry.op, \"unknown\"),\n    patch: Array.isArray(entry.patch) ? entry.patch : [],\n    before_hash: readActivityString(entry.before_hash),\n    after_hash: readActivityString(entry.after_hash),\n  };\n}\n\nfunction sortActivity(entries: ActivityEntry[]): ActivityEntry[] {\n  return [...entries].sort((a, b) => {\n    const byTimestamp = b.ts.localeCompare(a.ts);\n    if (byTimestamp !== 0) return byTimestamp;\n    const byId = a.id.localeCompare(b.id);\n    if (byId !== 0) return byId;\n    return a.op.localeCompare(b.op);\n  });\n}\n\nasync function listHistoryFiles(historyDir: string): Promise<string[]> {\n  try {\n    return (await fs.readdir(historyDir))\n      .filter((entry) => entry.endsWith(\".jsonl\"))\n      .sort((a, b) => a.localeCompare(b));\n  } catch (error: unknown) {\n    // Activity should degrade gracefully when optional history storage is absent.\n    if ((error as NodeJS.ErrnoException).code === \"ENOENT\") {\n      return [];\n    }\n    throw error;\n  }\n}\n\nfunction resolveActivityFilters(options: ActivityCommandOptions): ActivityFilters {\n  const nowValue = nowIso();\n  const from = parseRangeBound(options.from, nowValue, \"--from\");\n  const to = parseRangeBound(options.to, nowValue, \"--to\");\n  if (from && to && compareTimestampStrings(from, to) >= 0) {\n    throw new PmCliError(\"Activity --from must be before --to\", EXIT_CODE.USAGE);\n  }\n  return {\n    id: parseNonEmptyFilter(options.id, \"Activity --id\"),\n    op: parseNonEmptyFilter(options.op, \"Activity --op\"),\n    author: parseNonEmptyFilter(options.author, \"Activity --author\"),\n    from,\n    to,\n    limit: parseLimit(options.limit),\n  };\n}\n\nasync function resolveActivityRuntimeContext(global: GlobalOptions): Promise<ActivityRuntimeContext> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  if (!(await pathExists(getSettingsPath(pmRoot)))) {\n    throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);\n  }\n  return {\n    pmRoot,\n    settings: await readSettings(pmRoot),\n  };\n}\n\nasync function prepareActivityHistoryRead(context: ActivityRuntimeContext): Promise<string> {\n  const typeRegistry = resolveItemTypeRegistry(context.settings, getActiveExtensionRegistrations());\n  const items = await listAllFrontMatterLight(\n    context.pmRoot,\n    context.settings.item_format,\n    typeRegistry.type_to_folder,\n    undefined,\n    context.settings.schema,\n  );\n  await enforceHistoryStreamPolicyForItems({\n    pmRoot: context.pmRoot,\n    settings: context.settings,\n    itemIds: items.map((item) => item.id),\n    commandLabel: \"activity\",\n  });\n  const historyDir = path.join(context.pmRoot, \"history\");\n  await runActiveOnReadHooks({\n    path: historyDir,\n    scope: \"project\",\n  });\n  return historyDir;\n}\n\nfunction includeActivityEntry(entry: HistoryEntry, candidate: ActivityEntry, filters: ActivityFilters): boolean {\n  // Preserve legacy filter semantics: op/author filters compare the raw\n  // history row before missing metadata is normalized to \"unknown\" for display.\n  if (filters.op && entry.op !== filters.op) {\n    return false;\n  }\n  if (filters.author && entry.author !== filters.author) {\n    return false;\n  }\n  return includeByTimeWindow(candidate, filters.from, filters.to);\n}\n\nasync function collectActivityEntries(historyDir: string, filters: ActivityFilters): Promise<ActivityEntry[]> {\n  const combined: ActivityEntry[] = [];\n  for (const file of await listHistoryFiles(historyDir)) {\n    const id = file.slice(0, -\".jsonl\".length);\n    if (filters.id && id !== filters.id) {\n      continue;\n    }\n    const entries = await readHistoryEntries(path.join(historyDir, file), id);\n    for (const entry of entries) {\n      const candidate = normalizeActivityEntry(id, entry);\n      if (includeActivityEntry(entry, candidate, filters)) {\n        combined.push(candidate);\n      }\n    }\n  }\n  return combined;\n}\n\nfunction formatCompactActivity(activity: ActivityEntry[]): CompactActivityEntry[] {\n  return activity.map((entry): CompactActivityEntry => ({\n    id: entry.id,\n    op: entry.op,\n    ts: entry.ts,\n    author: entry.author,\n    ...(entry.message ? { msg: entry.message } : {}),\n  }));\n}\n\nexport const _testOnly = {\n  parseNonEmptyFilter,\n  parseRangeBound,\n  includeByTimeWindow,\n  limitEntries,\n  readActivityString,\n  normalizeActivityEntry,\n  sortActivity,\n  listHistoryFiles,\n};\n\n/**\n * Implements run activity for the public runtime surface of this module.\n */\nexport async function runActivity(options: ActivityCommandOptions, global: GlobalOptions): Promise<ActivityResult> {\n  const context = await resolveActivityRuntimeContext(global);\n  const filters = resolveActivityFilters(options);\n  const historyDir = await prepareActivityHistoryRead(context);\n  const activity = limitEntries(sortActivity(await collectActivityEntries(historyDir, filters)), filters.limit);\n  const compact = options.compact === true;\n  const compactActivity = compact ? formatCompactActivity(activity) : undefined;\n  return {\n    activity: compact ? [] : activity,\n    compact_activity: compactActivity,\n    compact,\n    count: activity.length,\n    limit: filters.limit ?? null,\n  };\n}\n"],
-  "mappings": "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",
-  "names": ["global"]
-}