@unbrained/pm-cli 2026.7.6 → 2026.7.7

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/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,8 @@ 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`
 - `PM_CORE_COMMAND_NAMES`
 - `PM_TOOL_ACTIONS`
 - `PM_TOOL_PARAMETERS_SCHEMA`
@@ -436,7 +442,12 @@ 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 });
 
 await runAction({
   action: "context",
@@ -449,6 +460,23 @@ 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`.
+
 `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 +489,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

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.7",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",

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"]
-}