@unbrained/pm-cli 2026.9.3 → 2026.9.5

package/.agents/skills/HARNESS_COMPATIBILITY.md

@@ -6,7 +6,7 @@ This repository supports external automation harnesses through shared docs and `
 
 Use the same low-token route in every harness:
 
-1. `pm install guide-shell --project` (enable optional local guide commands)
+1. `pm package install guide-shell --project` (enable optional local guide commands)
 2. `pm guide` (topic index)
 3. `pm guide <topic>` (focused route)
 4. `pm guide <topic> --depth standard|deep` (details only when needed)

package/.agents/skills/README.md

@@ -41,7 +41,7 @@ pm guide skills
 pm guide harnesses --depth standard
 ```
 
-Guide topics: `quickstart`, `commands`, `workflows`, `sdk`, `extensions`,
-`skills`, `harnesses`, `release`, `tokens`, `graph`, `assurance`, `merge`.
+Guide topics are declared at runtime: `pm guide` prints the current index and
+`pm guide <topic> --depth brief` expands one topic. Do not copy the list.
 
 Compatibility routing: [Harness compatibility matrix](HARNESS_COMPATIBILITY.md)

package/.agents/skills/pm-developer/SKILL.md

@@ -60,6 +60,7 @@ pm files <ID> --add path=<path>,scope=project,note="<why>"
 pm docs  <ID> --add path=<doc>,scope=project,note="<why>"
 pm test  <ID> --add command="node scripts/run-tests.mjs test -- <target>",scope=project,timeout_seconds=240
 pm comments <ID> "Evidence: <what changed and what passed>"
+pm learnings <ID> --add "<lesson that outlives this item>"
 pm test <ID> --run --progress
 pm close <ID> "<reason with evidence>" --validate-close warn
 pm release <ID>
@@ -76,7 +77,9 @@ enters, and use these drift-gated references:
 
 `pm help` shows the bounded core tier. Use `pm guide capabilities`, `pm
 contracts --summary`, or `pm <command> --help --json` for progressive
-disclosure into the wider surface.
+disclosure into the wider surface. Durable lessons and history maintenance
+(`pm learnings`, `pm history --verify`, `history-repair`, `history-redact`,
+`history-compact`, `close-many`) are routed by `pm guide evidence`.
 
 ## Token Discipline
 

package/.agents/skills/pm-developer/references/COMMAND_PLAYBOOK.md

@@ -29,6 +29,16 @@ pm docs <ID> --add path=docs/<doc>.md,scope=project,note="public docs update"
 pm test <ID> --add command="node scripts/run-tests.mjs test -- tests/unit/<file>.spec.ts",scope=project,timeout_seconds=240
 ```
 
+## Durable Knowledge And Record Maintenance
+
+```bash
+pm learnings <ID> --add "<lesson that applies beyond this item>"
+pm learnings <ID> --limit 5
+pm history <ID> --verify --strict-exit
+pm history-repair --all --dry-run
+pm close-many --ids <ID>,<ID> --reason "<shared reason>" --dry-run
+```
+
 ## Close Workflow
 
 ```bash

package/.agents/skills/pm-developer/references/GRAPH_AND_RELATIONSHIPS.md

@@ -24,12 +24,14 @@ pm contracts --json --full | jq '.relationship_kind_contracts'
 | `discovered_from` | This item was found while doing that one        | no       | no        |
 | `incident_from`   | This item originates in that recorded incident  | no       | no        |
 | `supersedes`      | This item replaces that one                     | no       | no        |
+| `recurs_from`     | This defect recurs from that closed one         | no       | no        |
 | `commits_to`      | This item lands in that changeset or release    | yes      | no        |
 | `related`         | Associative, non-directional                    | no       | no        |
 
 `related` carries the least information. Prefer a typed kind whenever one
 applies — `discovered_from`, `implements`, and `verifies` are the three that
-most often replace a reflexive `related`.
+most often replace a reflexive `related`. A defect that repeats an earlier
+closed one gets `recurs_from`, which is what the recurrence policy joins on.
 
 ## Adding Edges
 

package/.agents/skills/pm-extensions/SKILL.md

@@ -57,8 +57,8 @@ pm contracts --runtime-only --availability-only
 
 ```bash
 pm package explore --project              # inspect state first
-pm package manage --detail summary
-pm package doctor --detail deep
+pm package manage --project
+pm package doctor --detail summary
 pm package install <package> --project            # then mutate
 pm contracts --command <extension-command> --flags-only
 pm package doctor --detail deep           # verify after

package/.agents/skills/pm-extensions/references/LIFECYCLE.md

@@ -4,8 +4,8 @@
 
 ```bash
 pm package explore --project
-pm package manage --detail summary
-pm package doctor --detail deep
+pm package manage --project
+pm package doctor --detail summary
 ```
 
 ## Install and Activate
@@ -21,7 +21,7 @@ pm package doctor --detail summary
 ```bash
 pm package adopt <name> --project
 pm package adopt-all --project
-pm package manage --detail summary
+pm package manage --project
 ```
 
 ## Deactivate / Uninstall

package/.agents/skills/pm-extensions/references/TROUBLESHOOTING.md

@@ -2,9 +2,9 @@
 
 ## Common Diagnostic Sequence
 
-1. `pm extension explore --project`
-2. `pm extension manage --detail summary`
-3. `pm extension doctor --detail deep --trace`
+1. `pm package explore --project`
+2. `pm package manage --project`
+3. `pm package doctor --detail deep --trace`
 4. `pm contracts --runtime-only --availability-only`
 
 ## Symptoms and Checks

package/.agents/skills/pm-user/SKILL.md

@@ -86,6 +86,8 @@ the criteria; `--dep` **appends**.
 | Group and count             | `pm aggregate --group-by <field>`        | `commands`   |
 | Lineage and ordering        | `pm deps`, `pm graph <verb>`             | `graph`      |
 | Recent movement             | `pm activity`, `pm events`, `pm history` | `assurance`  |
+| Durable lessons and records | `pm learnings`, `pm notes`, `pm history` | `evidence`   |
+| Deadlines and meetings      | `pm remind`, `pm event`, `pm meet`       | `automation` |
 | Data quality                | `pm validate`, `pm health`               | `assurance`  |
 | Plan a multi-step change    | `pm plan`                                | `workflows`  |
 | Custom types and statuses   | `pm schema`, `pm config`                 | `commands`   |

package/.agents/skills/pm-user/references/BACKLOG_SHAPING.md

@@ -89,8 +89,13 @@ Record evolution explicitly rather than letting it be inferred:
 pm update <NEW> --dep "id=<OLD>,kind=supersedes"
 pm update <FIX> --dep "id=<INCIDENT>,kind=incident_from"
 pm update <TEST> --dep "id=<FEATURE>,kind=verifies"
+pm update <NEW-DEFECT> --dep "id=<CLOSED-DEFECT>,kind=recurs_from"
 ```
 
+Record the lesson where the next agent will read it, on the item that proved
+it, with `pm learnings <ID> --add "..."`; a closed item without its learning
+forces the next reader to rediscover it.
+
 ## Periodic Hygiene
 
 ```bash

package/.agents/skills/pm-user/references/WORKFLOWS.md

@@ -24,12 +24,27 @@ pm comments <ID> "Owner update: <state>"
 pm release <ID>
 ```
 
-## Audit-Friendly Collaboration
+## Recording Durable Knowledge
 
-For non-owner append-only collaboration:
+A comment explains this item; a learning outlives it. Record a lesson the
+moment it is confirmed, on the item that produced it:
 
 ```bash
-pm comments <ID> --add "audit comment" --allow-audit-comment
-pm notes <ID> --add "audit note" --allow-audit-comment
-pm update <ID> --dep "id=<id>,kind=related,author=<author>,created_at=now" --allow-audit-dep-update
+pm learnings <ID> --add "<what turned out to be true and how it was proven>"
+pm learnings <ID> --limit 5
+pm guide evidence --depth brief
+```
+
+## Append-Only Collaboration Between Owners
+
+Comments, notes, and typed dependencies append for any author on a bare
+install; no bypass flag is needed. The review-style flags below are provided by
+the `governance-audit` package and are refused as unknown options until it is
+installed:
+
+```bash
+pm package install governance-audit --project
+pm comments <ID> --add "review comment" --allow-audit-comment
+pm notes <ID> --add "review note" --allow-audit-comment
+pm update <ID> --dep "id=<id>,kind=discovered_from" --allow-audit-dep-update
 ```

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.9.3"
+    "version": "2026.9.5"
   },
   "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.9.3",
+      "version": "2026.9.5",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## 2026.9.5 - 2026-09-05
+
+### Fixed
+
+- pm next recommends outcome-milestone gates as actionable work, and summary.containers counts a bucket the envelope never emits ([pm-08mt4k](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-08mt4k.toon))
+- Windows published-release verifier test can preempt its own readiness and cleanup contract ([pm-euqm7x](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-euqm7x.toon))
+- Commander usage refusals omit token_accounting even when --token-accounting is parsed ([pm-bfa1ob](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-bfa1ob.toon))
+- flag-invocation-parity only iterates declared flags, so 21 runtime options across 8 core commands have no flag contract ([pm-2bqgs7](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-2bqgs7.toon))
+- pm release leaves the item in_progress with no owner: offer --status open (or hint) so released work does not linger as phantom WIP ([pm-ugld](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ugld.toon))
+- GH-1169: the unknown-command hint routes to the 15-command root help that hides the target, and test is the only singular collection verb ([pm-u4t9gp](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-u4t9gp.toon))
+- pm context summary counts are denominated in the returned slice, so the canonical orient cold-start reports 4 open items in a 291-item backlog ([pm-79gv6q](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-79gv6q.toon))
+- GH-1171: restore parses the on-disk item before consulting history, so a zero-byte or corrupted item file with an intact stream cannot be rebuilt ([pm-96fsma](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-96fsma.toon))
+- history-compact renumbers version identifiers, so pm get --at N and pm restore N address a different recorded state after compaction with exit 0 and no signal ([pm-m0yjtg](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-m0yjtg.toon))
+- A deleted item's id is immediately re-mintable, so one immutable history stream can hold two unrelated items and every integrity check still reports verified ([pm-e3gn0z](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-e3gn0z.toon))
+- Point-in-time reconstruction crashes with an unstructured runtime error when a history stream opens without a baseline entry, so the restore-any-version guarantee fails with no diagnosable condition ([pm-qw1uw6](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-qw1uw6.toon))
+- Agent skills instruct flags and spellings the runtime refuses, and no guide topic routes the evidence or automation families ([pm-4957pz](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-4957pz.toon))
+- Sentry-injected release artifacts exceed the CI package budget because pre- and post-injection packlists share one ceiling ([pm-llbnua](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-llbnua.toon))
+- GH-1190: Windows nightly can publish the event index after an unlocked fallback append ([pm-a7207g](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-a7207g.toon))
+- Tag-push Release must regenerate the exact-tag changelog before immutable publication ([pm-e63v1x](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-e63v1x.toon))
+
+### Other
+
+- Upgrade Greptile review tooling to 3.5.0 with compatible dependency evidence ([pm-o3mczz](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-o3mczz.toon))
+- Point-in-time reconstruction gate: prove every item at every recorded version replays exactly from its history stream alone ([pm-wlqxg3](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-wlqxg3.toon))
+- Refresh compatible jscpd 5.1.2 and reconcile the 2026-09-04 dependency census ([pm-gredf1](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-gredf1.toon))
+
+## 2026.9.4 - 2026-09-04
+
+### Added
+
+- Verdict contract: one declared vocabulary of reproducible predicates over recorded state, composable into a score, with reward shaping explicitly refused ([pm-e1vkee](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-e1vkee.toon))
+
+### Fixed
+
+- Packed npx smoke timeout rejects valid slow dependency reification ([pm-8eebb6](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-8eebb6.toon))
+- GH-1186: unrecoverable legacy merge-receipt references block strict health with diagnostic-only remediation ([pm-cf4t42](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-cf4t42.toon))
+- GH-1185: hash-only merge receipts make discarded scalar values unreachable to the reviewing agent ([pm-mg13iz](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-mg13iz.toon))
+- GH-1184: scalar merge conflict ordering ignores recency and requested preference ([pm-7wzb6d](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-7wzb6d.toon))
+- Acceptance criteria are documented as merging like tags but are stored as one delimiter-joined scalar, so concurrent criteria additions from different branches are silently discarded ([pm-inn5y5](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-inn5y5.toon))
+- GH-1183: Windows nightly event-index lock acquisition and fallback publication are nondeterministic ([pm-fqlocp](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-fqlocp.toon))
+- GH-1177: Claude session provenance path is derived from invocation cwd instead of the session-start workspace ([pm-l7m7k5](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-l7m7k5.toon))
+- GH-1179: legacy merge-receipt shape is misclassified as a gate-failing missing history reference with no remedy ([pm-wn3ee5](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-wn3ee5.toon))
+- Re-anchoring overwrites the original hash pair, so the immutability proof for every pre-merge entry is destroyed by the operation that repairs the chain ([pm-aka8m7](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-aka8m7.toon))
+
+### Security
+
+- GH-1178: history hashes exclude record author and agent provenance, so attribution can be rewritten without detection ([pm-javbsq](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-javbsq.toon))
+
+### Other
+
+- Refresh compatible @types/node 26.4.1 patch ([pm-vwtwqj](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-vwtwqj.toon))
+
 ## 2026.9.3 - 2026-09-03
 
 ### Fixed

package/dist/cli/commander-usage.d.ts

@@ -11,6 +11,8 @@ import type { ExtensionCommandHelpDescriptor } from "./extension-command-help.js
 export declare const BUILTIN_TYPE_HELP_VALUES: string;
 /** Documents the commander usage context payload exchanged by command, SDK, and package integrations. */
 export interface CommanderUsageContext extends CommanderGuidanceContext {
+    /** Normalized invocation retained for recovery and transport accounting. */
+    normalizedInvocationArgs: string[];
     /** Human-readable explanation suitable for logs and agent-facing output. */
     message: string;
     /** Value that configures or reports command name for this contract. */

package/dist/cli/commander-usage.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]="8879d491-9158-548c-bfbd-8ab57d8eb936")}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]="18758585-648f-5422-80e4-fbc7478c3cf3")}catch(e){}}();
 import { pathExists, resolveItemTypeRegistry, EXIT_CODE, getSettingsPath, resolvePmRoot, readSettings, getActiveExtensionRegistrations, locateItem, runActiveServiceOverride, levenshteinDistanceWithinLimit, } from "../sdk/runtime-primitives.js";
 import { BUILTIN_ITEM_TYPE_VALUES } from "../types/index.js";
 import { PM_CORE_COMMAND_NAMES, resolveSubcommandFlagContractsForCommand, } from "../sdk/cli-contracts.js";
@@ -11,6 +11,7 @@ import { extractProvidedOptionFlags, normalizeLongFlag, renderPmCommand, } from
 import { normalizeExtensionNameForMatch } from "./commands/extension/shared.js";
 import { rankCommandPaths } from "../sdk/agent/command-suggestions.js";
 import { renderMissingOptionRetry } from "../sdk/agent/command-recovery.js";
+import { attachOutputTokenAccounting } from "../sdk/output-token-accounting.js";
 /** Supported values accepted by the builtin type help contract. */
 export const BUILTIN_TYPE_HELP_VALUES = BUILTIN_ITEM_TYPE_VALUES.join("|");
 const OPTIONAL_PACKAGE_INSTALL_HINTS = {
@@ -91,8 +92,9 @@ export function appendCommanderExtensionFailures(renderedUsage, json, failures)
     }
     if (json) {
         const primaryFailure = failures.find((entry) => entry.declared_command_match === true);
-        return JSON.stringify({
-            ...JSON.parse(renderedUsage),
+        const { token_accounting: priorAccounting, ...usage } = JSON.parse(renderedUsage);
+        const enriched = {
+            ...usage,
             ...(primaryFailure
                 ? {
                     extension_command_failure: {
@@ -105,7 +107,8 @@ export function appendCommanderExtensionFailures(renderedUsage, json, failures)
                 }
                 : {}),
             failed_extensions: failures,
-        }, null, 2);
+        };
+        return JSON.stringify(priorAccounting === undefined ? enriched : attachOutputTokenAccounting(enriched, (value) => `${JSON.stringify(value, null, 2)}\n`), null, 2);
     }
     const details = failures
         .map((entry) => `- ${entry.layer}:${entry.name}: ${entry.error}`)
@@ -435,9 +438,9 @@ function resolveUnknownCommandFallbacks(commandPaths) {
 function buildUnknownCommandExamples(suggestedPaths, hasConcreteCandidates) {
     const suggestedExamples = suggestedPaths.map((path) => `pm ${path} --help`);
     if (hasConcreteCandidates) {
-        return [...new Set([...suggestedExamples, "pm --help"])];
+        return [...new Set([...suggestedExamples, "pm --help --all"])];
     }
-    return [...new Set(["pm --help", ...suggestedExamples])];
+    return [...new Set(["pm --help --all", ...suggestedExamples])];
 }
 /** Implements build unknown command guidance from runtime for the public runtime surface of this module. */
 export function buildUnknownCommandGuidanceFromRuntime(rawMessage, root, extensionDescriptors) {
@@ -473,7 +476,7 @@ export function buildUnknownCommandGuidanceFromRuntime(rawMessage, root, extensi
         unknownCommandExamples: examples,
         unknownCommandNextSteps: [
             ...(didYouMean ? [didYouMean] : []),
-            'Run "pm --help" to list commands available in this runtime, including active extensions.',
+            'Run "pm --help --all" to list every command available in this runtime, including active extensions.',
             "Use one of the suggested command paths above with --help to inspect valid flags and usage.",
             ...(optionalPackageHint ? [optionalPackageHint] : []),
         ],
@@ -528,11 +531,9 @@ export function isKnownHelpCommandPath(root, commandPathTokens) {
     for (const [tokenIndex, token] of commandPathTokens.entries()) {
         const next = resolveChildCommandByToken(current, token);
         if (!next) {
-            if (current.commands.some((candidate) => candidate.name() !== "help")) {
-                return false;
-            }
             const declaredArguments = current.registeredArguments;
             return (declaredArguments.length > 0 &&
+                (current.commands.length === 0 || declaredArguments[0]?.required === true) &&
                 (declaredArguments.at(-1)?.variadic === true ||
                     commandPathTokens.length - tokenIndex <= declaredArguments.length));
         }
@@ -756,7 +757,9 @@ export async function formatCommanderUsageJson(error, rootProgram, extensionDesc
         verifiedCollectionItemId: usageContext.verifiedCollectionItemId,
         failedExtensions: usageContext.failedExtensions,
     });
-    return JSON.stringify(lean ? projectLeanErrorEnvelope(envelope) : envelope, null, 2);
+    const projected = lean ? projectLeanErrorEnvelope(envelope) : envelope;
+    const accountingRequested = parseBootstrapGlobalOptions(usageContext.normalizedInvocationArgs).tokenAccounting === true;
+    return JSON.stringify(accountingRequested ? attachOutputTokenAccounting(projected, (value) => `${JSON.stringify(value, null, 2)}\n`) : projected, null, 2);
 }
 /** Public contract for test only, shared by SDK and presentation-layer consumers. */
 export const _testOnly = {
@@ -767,4 +770,4 @@ export const _testOnly = {
     suggestNearestLongFlags,
 };
 //# sourceMappingURL=commander-usage.js.map
-//# debugId=8879d491-9158-548c-bfbd-8ab57d8eb936
+//# debugId=18758585-648f-5422-80e4-fbc7478c3cf3

package/dist/cli/help-json-payload.js

@@ -1,14 +1,15 @@
 
-!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]="43167bb0-7cc0-599f-8587-8583d398f1ad")}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]="e4324332-da8f-5ae1-b0e3-b6d0e9674f98")}catch(e){}}();
 import { hasSubcommandFlagContractsForCommand, PM_COMMAND_ALIAS_CONTRACTS, PM_CORE_COMMAND_NAMES, } from "../sdk/cli-contracts.js";
-import { commandOptionFlagLabel, resolveCommandOptionPolicyState, resolveTypeDefinition, EXIT_CODE, printError, writeStdout, } from "../sdk/runtime-primitives.js";
+import { commandOptionFlagLabel, resolveCommandOptionPolicyState, resolveTypeDefinition, EXIT_CODE, writeStderr, writeStdout, } from "../sdk/runtime-primitives.js";
 import { buildDynamicExtensionHelpOptionSummaries, mergeHelpOptionSummaries, findCommandByPath, findDirectChildCommand, commandAliases, } from "./extension-command-help.js";
 import { getPmCommandHelpVisibilityTier, isFullHelpDiscovery, normalizeHelpCommandPath, resolveHelpDetailMode, resolveHelpNarrative, } from "./help-content.js";
 import { getCommandPath } from "./registration-helpers.js";
 import { parseBootstrapGlobalOptions, parseBootstrapHelpRequest, parseBootstrapCommandName, parseBootstrapTypeValue, } from "./bootstrap-args.js";
 import { extractProvidedOptionFlags, renderPmCommand } from "./argv-utils.js";
 import { formatCommanderErrorForJson } from "./error-guidance.js";
-import { BUILTIN_TYPE_HELP_VALUES, buildUnknownCommandGuidanceFromRuntime, } from "./commander-usage.js";
+import { BUILTIN_TYPE_HELP_VALUES, buildUnknownCommandGuidanceFromRuntime, isKnownHelpCommandPath, } from "./commander-usage.js";
+import { attachOutputTokenAccounting } from "../sdk/output-token-accounting.js";
 import { resolveCreateExplicitEmptyFlag } from "../sdk/agent/create-option-policy.js";
 import { formatPmPositionalActionFlagTip, PM_POSITIONAL_ACTION_CONTRACTS, resolvePmPositionalActionContract, } from "../sdk/cli-contracts/grammar-contracts.js";
 import { resolvePmCommandCapabilityFamily, resolvePmCommandVisibilityTier, } from "../sdk/agent-capability-contracts.js";
@@ -49,7 +50,8 @@ function resolveCommandFromPathTokens(root, pathTokens) {
     const requestedPath = pathTokens.join(" ");
     if (!PM_CORE_COMMAND_NAMES.some((commandName) => commandName === requestedPath) &&
         !hasSubcommandFlagContractsForCommand(requestedPath) &&
-        !resolvePmPositionalActionContract(requestedPath)) {
+        !resolvePmPositionalActionContract(requestedPath) &&
+        !isKnownHelpCommandPath(root, pathTokens)) {
         return null;
     }
     for (let length = pathTokens.length - 1; length > 0; length -= 1) {
@@ -352,7 +354,7 @@ function buildJsonHelpPayload(rootProgram, targetCommand, argv, requestedPath, e
         ? requestedCommandPath
         : commanderPath;
     const positionalAction = resolvePmPositionalActionContract(resolvedPath);
-    const projectedPath = positionalAction?.command ?? resolvedPath;
+    const projectedPath = positionalAction?.command ?? commanderPath;
     const commandPath = projectedPath.length > 0 ? projectedPath : undefined;
     const rootCommandPath = commandPath?.split(" ")[0];
     const fallbackNarrative = resolveHelpNarrative(commandPath, detailMode);
@@ -413,7 +415,10 @@ export async function maybeRenderBootstrapJsonHelp(rootProgram, argv, extensionD
                 normalizedInvocationArgs: [...argv],
                 providedOptionFlags: extractProvidedOptionFlags(argv),
             });
-            printError(JSON.stringify(envelope, null, 2));
+            const output = bootstrapGlobal.tokenAccounting
+                ? attachOutputTokenAccounting(envelope, (value) => `${JSON.stringify(value, null, 2)}\n`)
+                : envelope;
+            writeStderr(`${JSON.stringify(output, null, 2)}\n`);
         }
         process.exitCode = EXIT_CODE.USAGE;
         return true;
@@ -563,4 +568,4 @@ export const _testOnly = {
     resolveExtensionCommandSurface,
 };
 //# sourceMappingURL=help-json-payload.js.map
-//# debugId=43167bb0-7cc0-599f-8587-8583d398f1ad
+//# debugId=e4324332-da8f-5ae1-b0e3-b6d0e9674f98

package/dist/cli/main.js

@@ -3,9 +3,9 @@
  * @module cli/main
  */
 
-!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]="f947c7f0-adf8-59da-8bc7-9cd746b05839")}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]="aefde24d-ee93-53ac-9163-86c867d1eb78")}catch(e){}}();
 import { Command, CommanderError } from "commander";
-import { activateExtensions, clearActiveExtensionHooks, createCoreCommandHookContext, resetActiveExtensionRuntimeState, createEmptyExtensionRegistrationRegistry, discoverExtensions, getActiveCommandResult, getActiveExtensionRegistrations, loadExtensions, consumeAfterCommandAffectedItems, runActiveCommandHandler, runActiveParserOverride, runActivePreflightOverride, runAfterCommandHooks, runBeforeCommandHooks, setActiveCommandResult, setActiveCommandContext, setActiveExtensionCommands, setActiveExtensionHooks, setActiveExtensionParsers, setActiveExtensionPreflight, setActiveExtensionRegistrations, setActiveExtensionRenderers, setActiveExtensionServices, pathExists, resolvePmCliVersion, resolvePmPackageRootFromModule, resolveItemTypeRegistry, resolveRuntimeFieldRegistry, EXIT_CODE, resolveTelemetryErrorCategory, PmCliError, asRecordOrNull, printError, printResult, maybeRunFirstUseTelemetryPrompt, emitTelemetryErrorEvent, startTelemetryCommand, deriveTelemetryCommandResolution, sentryCaptureCliError, sentryFinishCommandSpan, sentryFlush, sentryLogCliUsageError, sentrySetCommandContext, sentryStartCommandSpan, ensureSentryInit, getSettingsPath, resolvePmRoot, readSettings, readSettingsWithMetadata, runWithWorkspaceHarnessSignalDescriptors, createLazyModule, } from "../sdk/runtime-primitives.js";
+import { activateExtensions, clearActiveExtensionHooks, createCoreCommandHookContext, resetActiveExtensionRuntimeState, createEmptyExtensionRegistrationRegistry, discoverExtensions, getActiveCommandResult, getActiveExtensionRegistrations, loadExtensions, consumeAfterCommandAffectedItems, runActiveCommandHandler, runActiveParserOverride, runActivePreflightOverride, runAfterCommandHooks, runBeforeCommandHooks, setActiveCommandResult, setActiveCommandContext, setActiveExtensionCommands, setActiveExtensionHooks, setActiveExtensionParsers, setActiveExtensionPreflight, setActiveExtensionRegistrations, setActiveExtensionRenderers, setActiveExtensionServices, pathExists, resolvePmCliVersion, resolvePmPackageRootFromModule, resolveItemTypeRegistry, resolveRuntimeFieldRegistry, EXIT_CODE, resolveTelemetryErrorCategory, PmCliError, asRecordOrNull, printError, printResult, writeStderr, maybeRunFirstUseTelemetryPrompt, emitTelemetryErrorEvent, startTelemetryCommand, deriveTelemetryCommandResolution, sentryCaptureCliError, sentryFinishCommandSpan, sentryFlush, sentryLogCliUsageError, sentrySetCommandContext, sentryStartCommandSpan, ensureSentryInit, getSettingsPath, resolvePmRoot, readSettings, readSettingsWithMetadata, runWithWorkspaceHarnessSignalDescriptors, createLazyModule, } from "../sdk/runtime-primitives.js";
 import { runWithReproducibleProcessEnvironment } from "../sdk/reproducibility/process.js";
 import { resolveSubcommandFlagContractsForCommand } from "../sdk/cli-contracts.js";
 import { createExtensionCommandSdk } from "../sdk/extension-command-context.js";
@@ -2168,7 +2168,10 @@ async function handleRunPmCliKnownError(context, numericExitCode) {
     const renderedError = context.jsonErrors
         ? JSON.stringify(context.bootstrapGlobal.tokenAccounting ? attachOutputTokenAccounting(jsonErrorPayload, (value) => `${JSON.stringify(value, null, 2)}\n`) : jsonErrorPayload, null, 2)
         : formatPmCliErrorForDisplay(errorMessage, enrichedContext);
-    printError(renderedError);
+    if (context.jsonErrors)
+        writeStderr(`${renderedError}\n`);
+    else
+        printError(renderedError);
     const { errorCategory, commandResolution } = await context.emitTelemetryCommandError({
         command: context.attemptedCommand,
         errorCode: classification.code,
@@ -2254,7 +2257,10 @@ async function handleUnknownHelpCommandError(context, code) {
         commandResolution,
         resolutionStage: "parse",
     });
-    printError(renderedUsage);
+    if (context.jsonErrors)
+        writeStderr(`${renderedUsage}\n`);
+    else
+        printError(renderedUsage);
     if (loggedHandledErrorToSentry) {
         await sentryFlush(HANDLED_ERROR_SENTRY_FLUSH_TIMEOUT_MS);
     }
@@ -2318,7 +2324,10 @@ async function handleRunPmCliCommanderUsageError(context, code) {
         commandResolution,
         resolutionStage: "parse",
     });
-    printError(renderedUsage);
+    if (context.jsonErrors)
+        writeStderr(`${renderedUsage}\n`);
+    else
+        printError(renderedUsage);
     if (loggedHandledErrorToSentry) {
         await sentryFlush(HANDLED_ERROR_SENTRY_FLUSH_TIMEOUT_MS);
     }
@@ -2561,4 +2570,4 @@ export const _testOnly = {
     wrapThrownErrorForSentry,
 };
 //# sourceMappingURL=main.js.map
-//# debugId=f947c7f0-adf8-59da-8bc7-9cd746b05839
+//# debugId=aefde24d-ee93-53ac-9163-86c867d1eb78

package/dist/cli/register-list-query.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]="1c6a0524-a8eb-5a20-b395-b488249c4e83")}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]="7b6e80ad-a85b-5539-8f47-02bfad799cdb")}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";
@@ -762,6 +762,8 @@ export function registerListQueryCommands(program, options) {
             .option("--blocked-limit <n>", "Limit blocked rows (default: same as --limit)")
             .option("--ready-only", "Omit the blocked companion list")
             .option("--include-decisions", "Include human-gated Decision items in the claimable ready queue")
+            .option("--include-gates", "Include outcome gates in the ready queue")
+            .option("--include-containers", "Include containers with unfinished descendants in the ready queue")
             .option("--format <value>", "Next output format override: markdown|toon|json")
             .option("--explain-ranking", "Include the scorer model, per-signal contributions, and ranked ready ids")
             .option("--token-budget <n>", "Maximum estimated tokens spent on the ranked ready queue");
@@ -939,4 +941,4 @@ export const _testOnlyRegisterListQuery = {
     parseListFormat,
 };
 //# sourceMappingURL=register-list-query.js.map
-//# debugId=1c6a0524-a8eb-5a20-b395-b488249c4e83
+//# debugId=7b6e80ad-a85b-5539-8f47-02bfad799cdb

package/dist/cli/register-mutation.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]="4e3b2528-5128-5bfd-8234-1e60fe90d9e2")}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]="c9d736d1-58bf-5088-aaae-0b89ad61d41f")}catch(e){}}();
 import { resolveBodyFileContent, resolveCliBulkIdsInput, EXIT_CODE, splitCommaList, PmCliError, createUnknownSubcommandError, } from "../sdk/runtime-primitives.js";
 import { CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, MERGE_SUBCOMMAND_VALUES, PLAN_CREATE_METADATA_PARAMETER_KEYS, UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, } from "../sdk/cli-contracts.js";
 import { BUILTIN_ITEM_TYPE_VALUES, PLAN_STEP_LINK_KIND_VALUES, } from "../types/index.js";
@@ -1717,6 +1717,7 @@ export function registerMutationCommands(program, registrationOptions = {}) {
     program
         .command("history-repair")
         .argument("[id]", "Item id (omit with --all)")
+        .option("--salvage-tail", "Recover invalid tail; requires verified prefix")
         .option("--all", "Scan every stream for drift and repair each drifted stream in one audited pass")
         .option("--dry-run", "Preview the re-anchor impact without writing the history file")
         .option("--normalize-provenance", "Remove invalid provenance; return aggregate-only evidence")
@@ -1735,6 +1736,7 @@ export function registerMutationCommands(program, registrationOptions = {}) {
             message: typeof options.message === "string" ? options.message : undefined,
             force: Boolean(options.force),
             normalizeProvenance: options.normalizeProvenance === true,
+            salvageTail: options.salvageTail === true,
         };
         // history-repair only re-anchors the audit stream; item content is untouched,
         // so search caches do not need invalidation.
@@ -1889,4 +1891,4 @@ export function registerMutationCommands(program, registrationOptions = {}) {
         .action(runDepsAction);
 }
 //# sourceMappingURL=register-mutation.js.map
-//# debugId=4e3b2528-5128-5bfd-8234-1e60fe90d9e2
+//# debugId=c9d736d1-58bf-5088-aaae-0b89ad61d41f

package/dist/cli/register-operations.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]="ecf75f5d-6345-5487-b7e4-1bd8f97326fd")}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]="4528cd9c-39e7-5d88-8e76-e7dec97c366a")}catch(e){}}();
 import { resolveRuntimeStatusRegistry, setActiveCommandResult, EXIT_CODE, PmCliError, createUnknownSubcommandError, resolveAuthor, resolvePmRoot, readSettings, } from "../sdk/runtime-primitives.js";
 import { resolveStartTaskInProgressStatus } from "../sdk/start-task-status.js";
 import { parseStatsAnalyticsJson } from "./stats-analytics-json.js";
@@ -491,6 +491,8 @@ async function runClaimAction(id, options, command) {
             sprint: typeof options.sprint === "string" ? options.sprint : undefined,
             release: typeof options.release === "string" ? options.release : undefined,
             includeDecisions: options.includeDecisions === true,
+            includeGates: options.includeGates === true,
+            includeContainers: options.includeContainers === true,
             tokenBudget: (options.tokenBudget ?? options.token_budget),
             explainRanking: options.explainRanking === true ||
                 options.explain_ranking === true,
@@ -765,6 +767,8 @@ export function registerOperationCommands(program) {
         .option("--release <value>", "Filter --next candidates by release")
         .option("--max-attempts <n>", "Bound the --next candidate walk (default 10; maximum 100)")
         .option("--include-decisions", "Allow --next to claim human-gated Decision items")
+        .option("--include-gates", "Allow --next to claim outcome gates")
+        .option("--include-containers", "Allow --next to claim containers with unfinished descendants")
         .option("--token-budget <n>", "Bound the estimated tokens used to rank --next candidates")
         .option("--explain-ranking", "Include ranking provenance for --next selection")
         .description("Claim an item for active work.")
@@ -909,4 +913,4 @@ function registerSchedulingShortcutCommands(program) {
     });
 }
 //# sourceMappingURL=register-operations.js.map
-//# debugId=ecf75f5d-6345-5487-b7e4-1bd8f97326fd
+//# debugId=4528cd9c-39e7-5d88-8e76-e7dec97c366a