@unbrained/pm-cli 2026.8.17 → 2026.8.18

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Official marketplace for pm CLI — native git-based project management for Claude Code and AI coding agents.",
-    "version": "2026.8.17"
+    "version": "2026.8.18"
   },
   "plugins": [
     {
       "name": "pm-claude",
       "source": "./plugins/pm-claude",
       "description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents, hybrid TUI task tracking, session context injection, and coordination subagents for git-based project management without leaving Claude Code.",
-      "version": "2026.8.17",
+      "version": "2026.8.18",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/AGENTS.md

@@ -63,8 +63,8 @@ For real repository tracking, do not override `PM_PATH`. If a script must target
 ```bash
 pm context --limit 10
 pm search "<request keywords>" --limit 10
-pm list-open --limit 20
-pm list-in-progress --limit 20
+pm list --status open --limit 20
+pm list --status in_progress --limit 20
 pm create --create-mode progressive --title "..." --description "..." --type Task --status open
 pm claim <id>
 pm update <id> --status in_progress --message "Start implementation"
@@ -82,12 +82,13 @@ Author identity is automatic; use `--author` only for an explicit override.
 
 ## Working Rules
 
-- **Orient:** run `pm context`, `pm search`, `pm list-open`, and `pm list-in-progress` before `pm create`. If net-new work is required, create or reuse the parent lineage first and record duplicate-check evidence in a create-time comment.
+- **Orient:** run `pm context`, `pm search`, `pm list --status open`, and `pm list --status in_progress` before `pm create`. If net-new work is required, create or reuse the parent lineage first and record duplicate-check evidence in a create-time comment.
 - **Verify before you claim:** the verification recipe for the Non-Negotiable above. A `closed` item whose `resolution`/`close_reason` describes the fix represents completed, shipped work — never describe it as outstanding. Confirm release/CI/infra status against the live system, e.g. `pm get pm-9gxi`, `npm view @unbrained/pm-cli version`, `gh release list`, `gh run list --workflow=auto-release.yml`.
 - **Implement:** keep edits scoped to the claimed item. Link changed files with `pm files`, docs with `pm docs`, and runnable verification with `pm test`.
 - **Record:** use `pm comments`, `pm notes`, and `pm learnings` for progress, rationale, and durable lessons. Prefer append-style updates over rewriting item content.
 - **Verify:** use sandbox-safe commands. For documentation-only work, run at least `pnpm build` and a focused link/content check. For broader work, run linked tests, coverage, validation, and release gates as appropriate.
 - **Close:** add evidence first, then `pm close <id> "<reason>" --validate-close warn`, then `pm release <id>`.
+- **Land closeout through review:** tracker evidence, item closure, and the generated changelog are part of the reviewed delivery. Never push post-merge closeout commits directly to `main`; if evidence depends on the merge SHA, carry it in a normal `main`-based follow-up PR so the new head retains analyzer provenance. See [Releasing](docs/RELEASING.md#reviewed-delivery-closeout).
 
 ## Test Safety
 

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 2026.8.18 - 2026-08-18
+
+### Added
+
+- Alias shim layer: config-aware hidden aliases with one-line migration hints (foundation for all consolidations) ([pm-0z7n](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-0z7n.toon))
+
+### Fixed
+
+- A commit pushed directly to the default branch can never be released: both analyzer-evidence fallbacks presuppose a pull request, and nothing declares that precondition ([pm-u1baah](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-u1baah.toon))
+- GH-1052: typed fail-closed whole-list SDK primitive ([pm-y4aaol](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-y4aaol.toon))
+- Packed Bun SDK import fails on node:module stripTypeScriptTypes ([pm-ikj8ve](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ikj8ve.toon))
+- GH-1051: package catalog rejects universal output-budget controls ([pm-2firut](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-2firut.toon))
+- Bun event streaming falls back to authoritative history without node:sqlite ([pm-b8hwfr](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-b8hwfr.toon))
+- Surface replication gate scopes trigger activation to relevant diff content ([pm-mrhwow](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-mrhwow.toon))
+- CodeQL: remove generated-code artifact path interpolation from exporter integration harness ([pm-ozxkm2](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ozxkm2.toon))
+- Exporter artifact-channel contract: clean stdout, bounded receipts, and binary-safe streaming ([pm-dilou2](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-dilou2.toon))
+- GH-1048: Windows Node 24 numeric EDQUOT fixtures construct NaN on platforms that do not declare that errno ([pm-y4kovm](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-y4kovm.toon))
+- Queued daily releases recognize an already-published same-day release before analyzer provenance ([pm-dm2vfz](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-dm2vfz.toon))
+
+### Security
+
+- Adopt Dependabot PR \#1046 pinned CodeQL 4.37.7 and TruffleHog 3.97.0 refresh ([pm-pp6al9](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-pp6al9.toon))
+
+### Deprecated
+
+- ADR: noun-verb CLI grammar — accepted consolidation principles and alias-preserving deprecation policy ([pm-pbyu](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/decisions/pm-pbyu.toon))
+
+### Other
+
+- Command-grammar conformance gate: the noun-verb table and shared verb vocabulary become machine-checked contracts a non-conforming command cannot pass ([pm-wt43zj](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-wt43zj.toon))
+- Consolidate the 8 list-\* status variants into pm list --status (list-all/open/draft/in-progress/blocked/closed/canceled become hidden aliases) ([pm-pfqi](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-pfqi.toon))
+- Command-destination census: 14 of 76 canonical commands have no declared home in the target grammar, so the surface can be frozen with its shape still undecided ([pm-yy8rmx](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-yy8rmx.toon))
+- Half of the pm events payload is per-row resume cursors an agent never reads: 48 percent of stream bytes buy a capability consumed once per batch ([pm-ez1dfg](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-ez1dfg.toon))
+
 ## 2026.8.17 - 2026-08-17
 
 ### Added
@@ -37,7 +71,6 @@
 - GH-1028: history-author-acknowledge bulk mutation lacks dry-run and misreports empty selection ([pm-mcxk8v](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-mcxk8v.toon))
 - GH-1030: contracts --json --full is wholly omitted by the default output budget ([pm-2qvq7a](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-2qvq7a.toon))
 - Auto Release blocker closure ignores successful recovery dispatch and reruns the stale tag-push workflow ([pm-db8onn](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-db8onn.toon))
-- A commit pushed directly to the default branch can never be released: both analyzer-evidence fallbacks presuppose a pull request, and nothing declares that precondition ([pm-u1baah](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-u1baah.toon))
 
 ### Other
 
@@ -52,7 +85,6 @@
 - Provide an audited repair and severity-migration contract for legacy invalid provenance ([pm-76fkpp](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-76fkpp.toon))
 - Detect extension-host pm-cli version skew before a workspace reports healthy ([pm-643e0k](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-643e0k.toon))
 - Restore strict unknown-key parity for docs linked-artifact additions ([pm-22rzjp](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-22rzjp.toon))
-- Surface replication gate scopes trigger activation to relevant diff content ([pm-mrhwow](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-mrhwow.toon))
 - Make every failing health verdict self-indexing and attach gate severity to findings ([pm-larv4r](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-larv4r.toon))
 - GH-1004: history-repair remains writer-version-specific across 2026.8.7 and 2026.8.13 ([pm-igdvfq](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-igdvfq.toon))
 - Assurance gates preserve zero-valued counts and report actionable source failures ([pm-xmmafu](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-xmmafu.toon))
@@ -969,10 +1001,10 @@
 
 ### Fixed
 
+- Sentry no longer captures deliberate Ctrl+C/Ctrl+D interrupts as error-level events (AbortError, PM-CLI-27) ([pm-ksv2](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ksv2.toon))
 - pm get --full omits children for Plan parents while pm list --parent returns them ([pm-y4z5](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-y4z5.toon))
 - Intentional package CommandError outcomes create high-severity Sentry issues (PM-CLI-16) ([pm-7071](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-7071.toon))
 - Extension install self-copy guard: reject source-inside-destination layouts before fs.cp EINVAL (PM-CLI-28) ([pm-8myl](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-8myl.toon))
-- Sentry captures deliberate Ctrl+C interrupts as error-level events (AbortError, PM-CLI-27) ([pm-ksv2](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ksv2.toon))
 - Torn-install bundle transients block scheduled releases: boot-time chunk-integrity self-check + distinct error code for gate classification ([pm-wfvq](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-wfvq.toon))
 - GH-446: pm get omits schedule facet (events/start_at/end_at/location) for Meeting/Event/Reminder ([pm-x1g5](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-x1g5.toon))
 - GH-533: create/update accept empty --title — required-title contract inconsistent between omitted and empty string ([pm-7je0](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-7je0.toon))

package/README.md

@@ -84,7 +84,7 @@ pm create \
   --ac "Restore succeeds after stale lock cleanup and has regression coverage." \
   --create-mode progressive
 
-pm list-open --limit 10
+pm list --status open --limit 10
 pm claim <item-id>
 pm update <item-id> --status in_progress --message "Start implementation"
 pm files <item-id> --add path=src/core/lock/lock.ts
@@ -102,8 +102,8 @@ Use `pm next` to get the single highest-priority ready item (and why), or `pm co
 pm next                                          # the next actionable item + rationale, ready/blocked queues
 pm context --limit 10
 pm search "keywords for the requested work" --limit 10
-pm list-open --limit 20
-pm list-in-progress --limit 20
+pm list --status open --limit 20
+pm list --status in_progress --limit 20
 ```
 
 If no relevant item exists, create a parent lineage before child work, claim the child item, link changed files/docs/tests, and leave evidence comments before closing. The full workflow is in the [Agent Guide](docs/AGENT_GUIDE.md).

package/dist/cli/error-guidance.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]="5251395b-715a-5559-a7d5-ca3bc4a1bb16")}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]="763daf66-1309-50bc-8783-8c232e4d690d")}catch(e){}}();
 import { resolveRecoveryCommandName } from "../sdk/agent/command-recovery.js";
 import { renderPmCommand } from "./argv-utils.js";
 import { discoverNearbyPmRoot } from "../sdk/tracker-root-discovery.js";
@@ -483,7 +483,7 @@ function buildItemNotFoundGuidance(rawMessage, message, context) {
     const nextSteps = isPlaceholder
         ? [
             "Check that the variable holding the item ID is defined before passing it to pm.",
-            'Use "pm list-open --limit 20" to find valid IDs.',
+            'Use "pm list --status open --limit 20" to find valid IDs.',
         ]
         : ["Confirm the active --path/PM_PATH scope, then retry with a valid id."];
     return applyPmCliErrorContext(makeGuidanceMessage({
@@ -492,7 +492,10 @@ function buildItemNotFoundGuidance(rawMessage, message, context) {
         happened,
         required: "Use an existing item ID from current tracker data.",
         why: "Mutation and read commands operate only on known IDs.",
-        examples: ["pm list-open --limit 20", 'pm search "<keyword>" --limit 10'],
+        examples: [
+            "pm list --status open --limit 20",
+            'pm search "<keyword>" --limit 10',
+        ],
         nextSteps,
     }), rawMessage, context);
 }
@@ -1237,4 +1240,4 @@ export const _testOnly = {
     resolveKnownPackageCommandHint,
 };
 //# sourceMappingURL=error-guidance.js.map
-//# debugId=5251395b-715a-5559-a7d5-ca3bc4a1bb16
+//# debugId=763daf66-1309-50bc-8783-8c232e4d690d

package/dist/cli/register-list-query.js

@@ -1,10 +1,11 @@
 
-!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]="0bcbdc33-3145-54cc-b4b6-10df50aef57a")}catch(e){}}();
-import { EXIT_CODE, PmCliError, renderRowsAsCsv, renderRowsAsTable, } from "../sdk/runtime-primitives.js";
+!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]="7bcf441b-e211-535f-9502-5624add292e5")}catch(e){}}();
+import { EXIT_CODE, PmCliError, readSettings, renderRowsAsCsv, renderRowsAsTable, resolvePmRoot, } from "../sdk/runtime-primitives.js";
+import { renderPmCommandAliasMigrationHint, resolvePmCommandAlias, } from "../sdk/cli-contracts.js";
 import { EVAL_QUERY_SET_SCHEMA_ID } from "../sdk/eval.js";
 import { applyContextIntentProjection } from "../sdk/context-intent-contracts.js";
-import { serializeNdjsonRows } from "../sdk/output.js";
-import { listMutationEvents, subscribeMutationEvents, } from "../sdk/mutation-events.js";
+import { serializeNdjsonRows, serializeNdjsonStream, } from "../sdk/output.js";
+import { listMutationEvents, subscribeMutationEventBatches, subscribeMutationEvents, } from "../sdk/mutation-events.js";
 import { runActivity } from "./commands/activity.js";
 import { runAggregate } from "./commands/aggregate.js";
 import { renderContextMarkdown, runContext, resolveContextOutputFormat, } from "./commands/context.js";
@@ -103,6 +104,14 @@ function registerContentAndGovernanceFilters(command) {
         .option("--filter-sprint-missing", "Show only items missing sprint")
         .option("--filter-release-missing", "Show only items missing release");
 }
+const CANONICAL_LIST_STATUS_VARIANTS = {
+    draft: { name: "list-draft", dependencyBlocked: false },
+    open: { name: "list-open", dependencyBlocked: false },
+    in_progress: { name: "list-in-progress", dependencyBlocked: false },
+    blocked: { name: "list-blocked", dependencyBlocked: true },
+    closed: { name: "list-closed", dependencyBlocked: false },
+    canceled: { name: "list-canceled", dependencyBlocked: false },
+};
 /** Resolve and validate the mutually exclusive list rendering modes. */
 function resolveRegisteredListOutputContext(options, globalOptions) {
     const streamMode = options.stream === true;
@@ -146,39 +155,63 @@ function renderRegisteredListResult(commandName, result, output) {
     }
 }
 async function runRegisteredListCommand(params) {
-    const globalOptions = getGlobalOptions(params.actionCommand);
+    const parsedGlobalOptions = getGlobalOptions(params.actionCommand);
+    const globalOptions = params.aliasContract
+        ? { ...parsedGlobalOptions, command: params.aliasContract.canonical }
+        : parsedGlobalOptions;
     const startedAt = Date.now();
-    if (params.options.all === true) {
-        throw new PmCliError("List --all was ambiguous and is no longer an alias for --no-truncate. Use `pm list --status all --no-truncate` for every status, or `pm list-all --no-truncate` for the dedicated all-status command.", EXIT_CODE.USAGE, {
-            code: "ambiguous_list_all",
-            examples: [
-                "pm list --status all --no-truncate",
-                "pm list-all --no-truncate",
-            ],
-        });
+    if (params.aliasContract?.lifecycle === "deprecated") {
+        const deprecationHints = await readSettings(resolvePmRoot(process.cwd(), globalOptions.path)).then((settings) => settings.ux.deprecation_hints);
+        if (deprecationHints) {
+            printError(renderPmCommandAliasMigrationHint(params.aliasContract));
+        }
     }
     const intentOptions = applyContextIntentProjection("list", params.options);
     const listOptions = normalizeListOptions(intentOptions);
-    applyDefaultListProjection(listOptions, params.name);
-    if (params.excludeTerminal)
-        listOptions.excludeTerminal = true;
-    if (params.name === "list" && listOptions.status === undefined) {
-        listOptions.status = "all";
+    let effectiveName = params.name;
+    let effectiveStatus = params.status;
+    let effectiveDependencyBlocked = params.dependencyBlocked === true;
+    let effectiveExcludeTerminal = params.excludeTerminal === true;
+    const requestedStatus = listOptions.status?.trim().toLowerCase();
+    const requestedVariant = params.name === "list" && requestedStatus !== undefined
+        ? CANONICAL_LIST_STATUS_VARIANTS[requestedStatus]
+        : undefined;
+    if (params.name === "list") {
+        if (params.options.all === true || requestedStatus === "all") {
+            effectiveName = "list-all";
+            effectiveExcludeTerminal = false;
+            listOptions.status = undefined;
+        }
+        else if (requestedStatus !== undefined && requestedVariant !== undefined) {
+            effectiveName = requestedVariant.name;
+            effectiveStatus = requestedStatus;
+            effectiveDependencyBlocked = requestedVariant.dependencyBlocked;
+            effectiveExcludeTerminal = false;
+            listOptions.status = undefined;
+        }
     }
-    listOptions.dependencyBlocked = params.dependencyBlocked;
+    applyDefaultListProjection(listOptions, effectiveName);
+    if (effectiveExcludeTerminal)
+        listOptions.excludeTerminal = true;
+    listOptions.dependencyBlocked = effectiveDependencyBlocked;
     const output = resolveRegisteredListOutputContext(intentOptions, globalOptions);
-    const result = await runList(params.dependencyBlocked ? undefined : params.status, listOptions, globalOptions);
-    renderRegisteredListResult(params.name, result, output);
+    const result = await runList(effectiveDependencyBlocked ? undefined : effectiveStatus, listOptions, globalOptions);
+    renderRegisteredListResult("list", result, output);
     if (globalOptions.profile) {
-        printError(`profile:command=${params.name} took_ms=${Date.now() - startedAt}`);
+        printError(`profile:command=list took_ms=${Date.now() - startedAt}`);
     }
 }
 function registerListCommand(program, descriptor) {
-    const { name, description, status, excludeTerminal, allowStatusFilter, dependencyBlocked, } = descriptor;
-    const command = program.command(name).description(description);
+    const { name, description, status, excludeTerminal, allowStatusFilter, dependencyBlocked, aliasContract, } = descriptor;
+    const command = program
+        .command(name, { hidden: aliasContract?.hidden === true })
+        .description(description);
     if (allowStatusFilter) {
         command.option("--status <value>", "Filter by status (repeatable or comma-separated; matches any; all selects every status)", collect);
     }
+    if (name === "list") {
+        command.option("--all", "Include every lifecycle status");
+    }
     command
         .option("--for <intent>", "Apply a declared context intent projection")
         .option("--token-budget <n>", "Override the selected intent's maximum estimated output tokens")
@@ -228,6 +261,7 @@ function registerListCommand(program, descriptor) {
             dependencyBlocked,
             options,
             actionCommand,
+            aliasContract,
         });
     });
     // Hidden pure snake_case underscore-duplicate alias (kept parse-functional).
@@ -235,7 +269,6 @@ function registerListCommand(program, descriptor) {
     addHiddenOption(command, "--assignee_filter <value>", "Alias for --assignee-filter");
     addHiddenOption(command, "--tree_depth <n>", "Alias for --tree-depth");
     addHiddenOption(command, "--token_budget <n>", "Alias for --token-budget");
-    addHiddenOption(command, "--all", "Removed ambiguous alias; emits migration guidance");
     // Singular alias so `--filter-estimate-missing` works (matches update-many spelling).
     addHiddenOption(command, "--filter-estimate-missing", "Alias for --filter-estimates-missing");
 }
@@ -411,6 +444,13 @@ function buildMutationEventOptions(options, pmRoot) {
     const harness = readRepeatableStringOption(options, "harness");
     const agentInstance = readRepeatableStringOption(options, "agentInstance");
     const provenanceFilter = readRepeatableStringOption(options, "provenanceFilter");
+    const rawCursorMode = typeof options.cursorMode === "string" ? options.cursorMode : undefined;
+    if (rawCursorMode !== undefined &&
+        rawCursorMode !== "batch" &&
+        rawCursorMode !== "row") {
+        throw new PmCliError("Events --cursor-mode must be batch or row.", EXIT_CODE.USAGE, { code: "invalid_event_cursor_mode" });
+    }
+    const cursorMode = rawCursorMode;
     return {
         pmRoot,
         since: typeof options.since === "string" ? options.since : undefined,
@@ -426,42 +466,76 @@ function buildMutationEventOptions(options, pmRoot) {
         ...(harness === undefined ? {} : { harness }),
         ...(agentInstance === undefined ? {} : { agentInstance }),
         ...(provenanceFilter === undefined ? {} : { provenanceFilter }),
+        cursorMode,
     };
 }
-async function runEventsAction(options, command) {
-    const globalOptions = getGlobalOptions(command);
-    const startedAt = Date.now();
-    const eventOptions = buildMutationEventOptions(options, globalOptions.path);
-    if (options.follow === true) {
-        if (options.provenanceSummary === true) {
-            throw new PmCliError("Events --provenance-summary is bounded to one page and cannot be combined with --follow.", EXIT_CODE.USAGE);
-        }
-        const intervalMs = typeof options.intervalMs === "string"
-            ? Number(options.intervalMs)
-            : undefined;
+/** Follows mutation events using either compatibility row cursors or the default batch-boundary trailer contract. */
+async function followMutationEvents(eventOptions, options, quiet) {
+    if (options.provenanceSummary === true) {
+        throw new PmCliError("Events --provenance-summary is bounded to one page and cannot be combined with --follow.", EXIT_CODE.USAGE);
+    }
+    const intervalMs = typeof options.intervalMs === "string"
+        ? Number(options.intervalMs)
+        : undefined;
+    if (eventOptions.cursorMode === "row") {
         for await (const event of subscribeMutationEvents({
             ...eventOptions,
             intervalMs,
         })) {
-            if (!globalOptions.quiet) {
+            if (!quiet) {
                 writeStdout(`${JSON.stringify(event)}\n`);
             }
         }
         return;
     }
+    for await (const page of subscribeMutationEventBatches({
+        ...eventOptions,
+        intervalMs,
+    })) {
+        if (!quiet) {
+            writeStdout(`${serializeNdjsonStream(page.events, {
+                count: page.count,
+                has_more: page.has_more,
+                next_cursor: page.next_cursor ?? null,
+                source: page.source,
+                heartbeat: page.count === 0,
+            })}\n`);
+        }
+    }
+}
+/** Serializes one bounded mutation-event page using its declared row or batch cursor mode. */
+function renderMutationEventPage(page) {
+    if (page.cursor_mode === "row") {
+        return serializeNdjsonRows(page.events);
+    }
+    return serializeNdjsonStream(page.events, {
+        count: page.count,
+        has_more: page.has_more,
+        next_cursor: page.next_cursor ?? null,
+        source: page.source,
+        ...(page.provenance_summary === undefined
+            ? {}
+            : { provenance_summary: page.provenance_summary }),
+    });
+}
+async function runEventsAction(options, command) {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const eventOptions = buildMutationEventOptions(options, globalOptions.path);
+    if (options.follow === true) {
+        await followMutationEvents(eventOptions, options, globalOptions.quiet === true);
+        return;
+    }
     const page = await listMutationEvents(eventOptions);
     setActiveCommandResult(page);
-    const rendered = serializeNdjsonRows([
-        ...page.events,
-        ...(page.provenance_summary === undefined
-            ? []
-            : [
-                {
-                    type: "provenance_summary",
-                    provenance_summary: page.provenance_summary,
-                },
-            ]),
-    ]);
+    if (globalOptions.json) {
+        printResult(page, globalOptions);
+        if (globalOptions.profile) {
+            printError(`profile:command=events took_ms=${Date.now() - startedAt}`);
+        }
+        return;
+    }
+    const rendered = renderMutationEventPage(page);
     if (!globalOptions.quiet && rendered.length > 0) {
         writeStdout(`${rendered}\n`);
     }
@@ -530,7 +604,7 @@ export function registerListQueryCommands(program, options) {
     const listCommandDescriptors = [
         {
             name: "list",
-            description: "List items across every lifecycle status with optional filters.",
+            description: "List active items with optional lifecycle-status and project filters.",
             excludeTerminal: true,
             allowStatusFilter: true,
         },
@@ -579,7 +653,13 @@ export function registerListQueryCommands(program, options) {
     ];
     for (const descriptor of listCommandDescriptors) {
         if (shouldRegister(descriptor.name)) {
-            registerListCommand(program, descriptor);
+            const aliasContract = resolvePmCommandAlias(descriptor.name);
+            registerListCommand(program, {
+                ...descriptor,
+                ...(aliasContract?.registration === "commander"
+                    ? { aliasContract }
+                    : {}),
+            });
         }
     }
     if (shouldRegister("aggregate")) {
@@ -775,6 +855,7 @@ export function registerListQueryCommands(program, options) {
             .option("--author <value>", "Filter by mutation author (repeatable or comma-separated)", collect)
             .option("--item <value>", "Filter by item or workspace stream id (repeatable or comma-separated)", collect)
             .option("--limit <n>", "Return at most 1,000 events (default: 100)")
+            .option("--cursor-mode <mode>", "Cursor framing: batch emits one terminal trailer (default); row preserves one cursor per event")
             .option("--full", "Include each complete authoritative history entry")
             .option("--provenance", "Include patch-free author, harness, instance, and extensible provenance")
             .option("--provenance-summary", "Include bounded provenance completeness counts")
@@ -838,4 +919,4 @@ export const _testOnlyRegisterListQuery = {
     parseListFormat,
 };
 //# sourceMappingURL=register-list-query.js.map
-//# debugId=0bcbdc33-3145-54cc-b4b6-10df50aef57a
+//# debugId=7bcf441b-e211-535f-9502-5624add292e5