@unbrained/pm-cli 2026.8.21 → 2026.8.23

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

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## 2026.8.23 - 2026-08-23
+
+### Added
+
+- Every instruction the product emits about its own next command is an unexecuted claim: the recovery vocabulary is generated, asserted as text, and run by nothing ([pm-h8tpeh](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-h8tpeh.toon))
+
+### Changed
+
+- Update ESLint to compatible 10.9.0 release ([pm-940mcx](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-940mcx.toon))
+
+### Fixed
+
+- Allow linked tests to opt out of source-workspace injection for self-sandboxing repo-wide gates ([pm-efkvdy](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-efkvdy.toon))
+- Linked-test schema context changes non-PM repository checks, so commands that pass directly fail when recorded and run through pm test ([pm-e97jyf](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-e97jyf.toon))
+- GH-1089: expose reproducible execution through supported CLI and MCP process configuration ([pm-gh1089](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1089.toon))
+- Budget recovery can recommend a smaller ceiling than the request that already truncated ([pm-xam9bt](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-xam9bt.toon))
+
+### Security
+
+- Linked-test commands are merge-unioned workspace data executed with shell:true — no provenance, allowlist, or confirmation boundary ([pm-ed28wi](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ed28wi.toon))
+- Cross-harness provenance adapters: automatically resolve native model, version, and effort signals beyond Claude without identity flags ([pm-c0lrdm](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-c0lrdm.toon))
+
+### Other
+
+- Cross-process reproducibility gate: prove CLI and MCP deterministic runs are byte-identical and fail on ambient time leaks ([pm-vklr99](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-vklr99.toon))
+- Expose agent probe controls and versioned legacy-author vocabulary through pm config and SDK mutation APIs ([pm-yds9dt](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-yds9dt.toon))
+- Diagnostic output budget: errors, warnings, and recovery bundles are the output an agent reads most and the only output with no declared ceiling ([pm-cha95z](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-cha95z.toon))
+
+## 2026.8.22 - 2026-08-22
+
+### Fixed
+
+- GH-1078: Complete-list certification accepts absent or contradictory truth receipts and emits stale recovery ([pm-gh1078](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1078.toon))
+- GH-1076: read-only duplicates rejects universal JSON output controls ([pm-gh1076](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1076.toon))
+- GH-1074: package doctor cannot distinguish a safe declining service override from a global interceptor ([pm-gh1074](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1074.toon))
+- GH-1073: pm init accepts a whitespace id prefix that makes later creates fail ([pm-gh1073](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1073.toon))
+- GH-1075: Windows Node 24 nightly validation failed at main 3e7ac007 ([pm-gh1075](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1075.toon))
+- The child hierarchy kind has an unenforced direction and cardinality: 7 of 15 rows are inverted against the registry's own declaration and no channel, validator, or audit finding notices ([pm-vk7zek](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-vk7zek.toon))
+- Hierarchy-canonicalizing dependency kinds bypass every cycle detector: mutual child_of edges leave the graph provably inconsistent while validate, health, and graph analyze all report acyclic ([pm-rggtvd](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-rggtvd.toon))
+
+### Security
+
+- GH-1072: pm install leaks user allow-scripts config into isolated package installs ([pm-gh1072](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1072.toon))
+
 ## 2026.8.21 - 2026-08-21
 
 ### Added

package/dist/cli/error-guidance.d.ts

@@ -4,6 +4,7 @@
  * Provides CLI runtime support for Error Guidance.
  */
 import { type PmCliErrorContext, type PmCliErrorRecoveryPayload } from "../sdk/runtime-primitives.js";
+import { type PmDiagnosticOutputReceipt, type PmProjectedDiagnostic } from "../sdk/cli-contracts/agent-output-contracts.js";
 interface GuidanceMessage {
     code: string;
     type: string;
@@ -20,6 +21,17 @@ interface GuidanceMessage {
     availableDependencies?: NonNullable<PmCliErrorContext["available_dependencies"]>;
     recovery?: PmCliErrorRecoveryPayload;
 }
+/** Compact refusal identity embedded in every structured error envelope. */
+export interface PmRefusalEnvelope {
+    /** Command, flag, or missing operand that rejected the invocation. */
+    surface: string;
+    /** Supplied scalar rejected by a closed domain, when available. */
+    rejected_value?: string;
+    /** Complete legal domain advertised by the refusal, when applicable. */
+    legal_domain?: string[];
+    /** Process exit code paired with the refusal. */
+    exit_code: number;
+}
 /** Documents the json error envelope payload exchanged by command, SDK, and package integrations. */
 export interface JsonErrorEnvelope {
     /** Schema type that determines the shape and validation rules for this value. */
@@ -52,9 +64,15 @@ export interface JsonErrorEnvelope {
     available_dependencies?: NonNullable<PmCliErrorContext["available_dependencies"]>;
     /** Value that configures or reports recovery for this contract. */
     recovery?: PmCliErrorRecoveryPayload;
+    /** Stable compact identity of the failing surface and legal recovery domain. */
+    refusal: PmRefusalEnvelope;
+    /** Binding output-budget receipt for this diagnostic. */
+    diagnostic_output?: PmDiagnosticOutputReceipt;
 }
+/** Error envelope after deterministic budget projection. */
+export type ProjectedJsonErrorEnvelope = PmProjectedDiagnostic<JsonErrorEnvelope>;
 /** Compact an error envelope to fields that change the caller's next action. */
-export declare function projectLeanErrorEnvelope(envelope: JsonErrorEnvelope): Omit<JsonErrorEnvelope, "required" | "why" | "title">;
+export declare function projectLeanErrorEnvelope(envelope: ProjectedJsonErrorEnvelope): ProjectedJsonErrorEnvelope;
 /** Documents the error classification payload exchanged by command, SDK, and package integrations. */
 export interface ErrorClassification {
     /** Schema type that determines the shape and validation rules for this value. */
@@ -149,15 +167,15 @@ export declare function formatPmCliErrorForDisplay(rawMessage: string, context?:
 /** Implements classify pm cli error for the public runtime surface of this module. */
 export declare function classifyPmCliError(rawMessage: string, context?: PmCliErrorContext): ErrorClassification;
 /** Implements format pm cli error for json for the public runtime surface of this module. */
-export declare function formatPmCliErrorForJson(rawMessage: string, exitCode: number, context?: PmCliErrorContext): JsonErrorEnvelope;
+export declare function formatPmCliErrorForJson(rawMessage: string, exitCode: number, context?: PmCliErrorContext): ProjectedJsonErrorEnvelope;
 /** Implements format commander error for display for the public runtime surface of this module. */
 export declare function formatCommanderErrorForDisplay(rawMessage: string, commandName: string | undefined, allowedTypes: string, context?: CommanderGuidanceContext): string;
 /** Implements classify commander error for the public runtime surface of this module. */
 export declare function classifyCommanderError(rawMessage: string, commandName: string | undefined, allowedTypes: string, context?: CommanderGuidanceContext): ErrorClassification;
 /** Implements format commander error for json for the public runtime surface of this module. */
-export declare function formatCommanderErrorForJson(rawMessage: string, commandName: string | undefined, allowedTypes: string, exitCode: number, context?: CommanderGuidanceContext): JsonErrorEnvelope;
+export declare function formatCommanderErrorForJson(rawMessage: string, commandName: string | undefined, allowedTypes: string, exitCode: number, context?: CommanderGuidanceContext): ProjectedJsonErrorEnvelope;
 /** Implements format unknown error for json for the public runtime surface of this module. */
-export declare function formatUnknownErrorForJson(rawMessage: string, exitCode: number): JsonErrorEnvelope;
+export declare function formatUnknownErrorForJson(rawMessage: string, exitCode: number): ProjectedJsonErrorEnvelope;
 /** Implements classify unknown error for the public runtime surface of this module. */
 export declare function classifyUnknownError(rawMessage: string): ErrorClassification;
 /** Public contract for test only, shared by SDK and presentation-layer consumers. */

package/dist/cli/error-guidance.js

@@ -1,11 +1,12 @@
 
-!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]="d90c153b-bb1d-57b1-81fd-e0ea7347c520")}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]="4bdb7fcf-dd74-57bc-8a0e-07539095462e")}catch(e){}}();
 import { resolveRecoveryCommandName } from "../sdk/agent/command-recovery.js";
+import { projectPmDiagnosticOutput, projectPmDiagnosticText, } from "../sdk/cli-contracts/agent-output-contracts.js";
 import { renderPmCommand } from "./argv-utils.js";
 import { discoverNearbyPmRoot } from "../sdk/tracker-root-discovery.js";
 /** Compact an error envelope to fields that change the caller's next action. */
 export function projectLeanErrorEnvelope(envelope) {
-    const { required: _required, why: _why, title: _title, ...actionable } = envelope;
+    const { why: _why, title: _title, ...actionable } = envelope;
     return actionable;
 }
 // JSON/classification payloads are consumed heavily by agents; suppress common
@@ -249,12 +250,14 @@ export function renderGuidanceMessage(message) {
     const lines = [
         `Error: ${message.title}`,
         "",
-        "What happened:",
-        `  ${message.happened}`,
-        "",
         "What is required:",
         `  ${message.required}`,
     ];
+    if (message.nextSteps && message.nextSteps.length > 0) {
+        lines.push("");
+        lines.push(...renderList("Next steps:", message.nextSteps));
+    }
+    lines.push("", "What happened:", `  ${message.happened}`);
     if (message.why) {
         lines.push("", "Why:");
         lines.push(`  ${message.why}`);
@@ -263,10 +266,6 @@ export function renderGuidanceMessage(message) {
         lines.push("");
         lines.push(...renderList("Examples:", message.examples));
     }
-    if (message.nextSteps && message.nextSteps.length > 0) {
-        lines.push("");
-        lines.push(...renderList("Next steps:", message.nextSteps));
-    }
     if (message.verificationErrors && message.verificationErrors.length > 0) {
         lines.push("");
         lines.push(...renderList("Verification errors:", message.verificationErrors));
@@ -305,6 +304,42 @@ function attachStructuredGuidanceDetails(payload, message) {
     }
     return payload;
 }
+function resolveRefusalCandidateFlag(message, normalizedArgs) {
+    if (message.flag)
+        return message.flag;
+    return message.recovery?.provided_fields?.find((field) => field !== "--json" &&
+        field !== "--quiet" &&
+        normalizedArgs.includes(field));
+}
+function resolveRefusalRejectedValue(message, normalizedArgs, candidateFlag) {
+    if (message.value !== undefined)
+        return message.value;
+    if (candidateFlag) {
+        return normalizedArgs[normalizedArgs.indexOf(candidateFlag) + 1];
+    }
+    const allowedValues = message.recovery?.allowed_values;
+    if (!allowedValues?.length)
+        return undefined;
+    return normalizedArgs.find((argument, index) => index > 0 &&
+        !argument.startsWith("-") &&
+        !allowedValues.includes(argument));
+}
+function buildRefusalEnvelope(message, exitCode) {
+    const normalizedArgs = message.recovery?.normalized_args ?? [];
+    const candidateFlag = resolveRefusalCandidateFlag(message, normalizedArgs);
+    const rejectedValue = resolveRefusalRejectedValue(message, normalizedArgs, candidateFlag);
+    return {
+        surface: candidateFlag ??
+            message.recovery?.missing?.[0] ??
+            inferCommandNameFromRecovery(message.recovery) ??
+            "command",
+        ...(rejectedValue !== undefined ? { rejected_value: rejectedValue } : {}),
+        ...(message.recovery?.allowed_values?.length
+            ? { legal_domain: message.recovery.allowed_values }
+            : {}),
+        exit_code: exitCode,
+    };
+}
 function guidanceToJsonEnvelope(message, exitCode) {
     return attachStructuredGuidanceDetails({
         type: message.type,
@@ -313,8 +348,20 @@ function guidanceToJsonEnvelope(message, exitCode) {
         detail: message.happened,
         required: message.required,
         exit_code: exitCode,
+        refusal: buildRefusalEnvelope(message, exitCode),
     }, message);
 }
+function projectJsonErrorGuidance(guidance, exitCode) {
+    const recovery = guidance.recovery;
+    const hasActionableRecovery = Boolean(recovery?.suggested_retry) ||
+        Boolean(recovery?.suggested_retry_args?.length) ||
+        Boolean(recovery?.allowed_values?.length) ||
+        Boolean(recovery?.candidate_commands?.length) ||
+        Boolean(guidance.nextSteps?.length);
+    return projectPmDiagnosticOutput(guidanceToJsonEnvelope(guidance, exitCode), {
+        diagnosticClass: hasActionableRecovery ? "recovery_bundle" : "error",
+    });
+}
 function guidanceToClassification(message) {
     return attachStructuredGuidanceDetails({
         type: message.type,
@@ -416,7 +463,10 @@ function applyPmCliErrorContext(guidance, rawMessage, context) {
     const fallbackTitle = guidance.code === "command_failed" && context.code
         ? buildFallbackTitleFromMessage(normalizedRawMessage)
         : undefined;
-    const recovery = normalizeRecoveryPayload(context.recovery) ?? guidance.recovery;
+    const contextRecovery = normalizeRecoveryPayload(context.recovery);
+    const recovery = contextRecovery && guidance.recovery
+        ? normalizeRecoveryPayload({ ...guidance.recovery, ...contextRecovery })
+        : (contextRecovery ?? guidance.recovery);
     return {
         ...guidance,
         code,
@@ -601,6 +651,10 @@ function buildInvalidArgumentGuidance(rawMessage, message, context) {
         ? `pm ${commandName} --help`
         : "pm <command> --help";
     const allowedValues = inferAllowedValuesFromMessage(message);
+    const enrichedRecovery = normalizeRecoveryPayload({
+        ...recovery,
+        allowed_values: recovery?.allowed_values ?? allowedValues,
+    });
     const retryExample = buildAllowedValueRetryCommand(recovery, allowedValues);
     const examples = retryExample
         ? [retryExample, helpExample]
@@ -621,6 +675,7 @@ function buildInvalidArgumentGuidance(rawMessage, message, context) {
         why: "Validation protects data consistency and deterministic behavior across commands.",
         examples,
         nextSteps,
+        recovery: enrichedRecovery,
     }), rawMessage, context);
 }
 function buildPmCliErrorGuidance(rawMessage, context) {
@@ -1164,7 +1219,8 @@ function buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, cont
 }
 /** Implements format pm cli error for display for the public runtime surface of this module. */
 export function formatPmCliErrorForDisplay(rawMessage, context) {
-    return renderGuidanceMessage(buildPmCliErrorGuidance(rawMessage, context));
+    const guidance = buildPmCliErrorGuidance(rawMessage, context);
+    return projectPmDiagnosticText(renderGuidanceMessage(guidance), guidance.required).output;
 }
 /** Implements classify pm cli error for the public runtime surface of this module. */
 export function classifyPmCliError(rawMessage, context) {
@@ -1172,11 +1228,12 @@ export function classifyPmCliError(rawMessage, context) {
 }
 /** Implements format pm cli error for json for the public runtime surface of this module. */
 export function formatPmCliErrorForJson(rawMessage, exitCode, context) {
-    return guidanceToJsonEnvelope(buildPmCliErrorGuidance(rawMessage, context), exitCode);
+    return projectJsonErrorGuidance(buildPmCliErrorGuidance(rawMessage, context), exitCode);
 }
 /** Implements format commander error for display for the public runtime surface of this module. */
 export function formatCommanderErrorForDisplay(rawMessage, commandName, allowedTypes, context) {
-    return renderGuidanceMessage(buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, context));
+    const guidance = buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, context);
+    return projectPmDiagnosticText(renderGuidanceMessage(guidance), guidance.required).output;
 }
 /** Implements classify commander error for the public runtime surface of this module. */
 export function classifyCommanderError(rawMessage, commandName, allowedTypes, context) {
@@ -1184,12 +1241,12 @@ export function classifyCommanderError(rawMessage, commandName, allowedTypes, co
 }
 /** Implements format commander error for json for the public runtime surface of this module. */
 export function formatCommanderErrorForJson(rawMessage, commandName, allowedTypes, exitCode, context) {
-    return guidanceToJsonEnvelope(buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, context), exitCode);
+    return projectJsonErrorGuidance(buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, context), exitCode);
 }
 /** Implements format unknown error for json for the public runtime surface of this module. */
 export function formatUnknownErrorForJson(rawMessage, exitCode) {
     const guidance = buildUnknownErrorGuidance(rawMessage);
-    return guidanceToJsonEnvelope(guidance, exitCode);
+    return projectJsonErrorGuidance(guidance, exitCode);
 }
 function buildUnknownErrorGuidance(rawMessage) {
     const message = normalizeMessage(rawMessage);
@@ -1240,4 +1297,4 @@ export const _testOnly = {
     resolveKnownPackageCommandHint,
 };
 //# sourceMappingURL=error-guidance.js.map
-//# debugId=d90c153b-bb1d-57b1-81fd-e0ea7347c520
+//# debugId=4bdb7fcf-dd74-57bc-8a0e-07539095462e

package/dist/cli/main.d.ts

@@ -11,6 +11,8 @@ import { type ExtensionCommandHelpDescriptor } from "./extension-command-help.js
 import { normalizeBootstrapInvocation } from "./bootstrap-args.js";
 import { type MandatoryMigrationBlocker } from "./migration-gates.js";
 import { resolveUnknownCommanderToken } from "./commander-usage.js";
+/** Record the exact compatibility flags present in the raw CLI invocation. */
+declare function recordCliReadOutputInvocationProvenance(actionCommand: Command, commandPath: string, commandOptions: Record<string, unknown>): void;
 declare function setActiveExtensionHookContextForTest(context: ActiveExtensionHookContext<MandatoryMigrationBlocker> | null): void;
 declare function setActiveRuntimeExtensionCommandDescriptorsForTest(descriptors: Map<string, ExtensionCommandHelpDescriptor>): void;
 interface RuntimeExtensionSnapshot {
@@ -292,6 +294,7 @@ export declare const _testOnly: {
     readRecordBoolean: typeof readRecordBoolean;
     readRecordNumber: typeof readRecordNumber;
     readRecordString: typeof readRecordString;
+    recordCliReadOutputInvocationProvenance: typeof recordCliReadOutputInvocationProvenance;
     registerDynamicExtensionCommandPaths: typeof registerDynamicExtensionCommandPaths;
     registerRuntimeSchemaFieldFlags: typeof registerRuntimeSchemaFieldFlags;
     resolveCoreCommandRegistrationSelection: typeof resolveCoreCommandRegistrationSelection;

package/dist/cli/main.js

@@ -3,9 +3,10 @@
  * @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]="27eeca2d-756c-539b-a0d4-d64516ee4aa6")}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]="7289d222-cf1f-5fa5-ac8a-d690b6012e39")}catch(e){}}();
 import { Command } 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 { runWithReproducibleProcessEnvironment } from "../sdk/reproducibility/process.js";
 import { resolveSubcommandFlagContractsForCommand } from "../sdk/cli-contracts.js";
 import { createExtensionCommandSdk } from "../sdk/extension-command-context.js";
 import { PmClient } from "../sdk/runtime.js";
@@ -27,10 +28,38 @@ import { loadExtensionRecoveryFailures, loadUnknownCommandRecoveryFailures } fro
 import { maybeRenderBootstrapJsonHelp, attachCreateUpdatePolicyHelpText } from "./help-json-payload.js";
 import { attachOutputTokenAccounting } from "../sdk/output-token-accounting.js";
 import { runWithDiscoveredContextIntentContracts } from "../sdk/context-intent-runtime.js";
-import { applyReadOutputIncludeModes, validateReadOutputOptions } from "../sdk/read-output-contracts.js";
+import { PM_READ_OUTPUT_SURFACE_CONTRACTS, applyReadOutputIncludeModes, readOutputIncludeModeOptions, resolveReadOutputSurface, validateReadOutputOptions, } from "../sdk/read-output-contracts.js";
 import { loadContextIntentSnapshotForInvocation } from "./context-intent-invocation.js";
 import { isPmSuccessfulExitCode } from "../sdk/cli-contracts/command-exit-contracts.js";
 const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
+const READ_OUTPUT_INVOCATION_PROVENANCE = Symbol.for("pm.readOutputInvocationProvenance");
+/** Carry private read-output provenance across Commander's option rebuilds. */
+function copyReadOutputInvocationProvenance(source, target) {
+    const provenance = Reflect.get(source, READ_OUTPUT_INVOCATION_PROVENANCE);
+    if (provenance !== undefined) {
+        Reflect.set(target, READ_OUTPUT_INVOCATION_PROVENANCE, provenance);
+    }
+}
+/** Record the exact compatibility flags present in the raw CLI invocation. */
+function recordCliReadOutputInvocationProvenance(actionCommand, commandPath, commandOptions) {
+    const surface = resolveReadOutputSurface(commandPath, commandOptions);
+    if (!surface)
+        return;
+    let rootCommand = actionCommand;
+    while (rootCommand.parent)
+        rootCommand = rootCommand.parent;
+    const rawArgs = rootCommand.rawArgs;
+    const providedFlags = new Set(extractProvidedOptionFlags(rawArgs.slice(2)));
+    const contract = PM_READ_OUTPUT_SURFACE_CONTRACTS.find((candidate) => candidate.command === surface);
+    const explicitLegacyAliases = Object.values(contract.dimensions).flatMap((dimension) => dimension.legacy_aliases.flatMap((alias) => providedFlags.has(alias.flag) ? [alias.flag] : []));
+    const previous = Reflect.get(commandOptions, READ_OUTPUT_INVOCATION_PROVENANCE);
+    Reflect.set(commandOptions, READ_OUTPUT_INVOCATION_PROVENANCE, {
+        canonical_include_modes: previous?.canonical_include_modes ?? [],
+        explicit_legacy_aliases: explicitLegacyAliases,
+        cli_invocation_observed: true,
+    });
+    copyReadOutputInvocationProvenance(commandOptions, actionCommand);
+}
 function resolvePmPackageRoot() {
     return resolvePmPackageRootFromModule(import.meta.url, ["../.."]);
 }
@@ -512,15 +541,18 @@ async function handleGenericRunPmCliError(params) {
  * command computes its rows, so it cannot be resolved by the output layer.
  */
 function forwardReadOutputIncludeModes(actionCommand, commandPath, globalOptions, commandOptions) {
+    recordCliReadOutputInvocationProvenance(actionCommand, commandPath, commandOptions);
     const requested = globalOptions.outputInclude;
     if (requested === undefined)
         return;
-    const modeOptions = {};
-    const { selectors, modes } = applyReadOutputIncludeModes(commandPath, requested, modeOptions);
+    const { selectors, modes } = applyReadOutputIncludeModes(commandPath, requested, commandOptions);
     if (modes.length === 0)
         return;
-    for (const [key, value] of Object.entries(modeOptions)) {
-        commandOptions[key] = value;
+    copyReadOutputInvocationProvenance(commandOptions, actionCommand);
+    const modeOptions = readOutputIncludeModeOptions(commandPath);
+    for (const mode of modes) {
+        const key = modeOptions.get(mode);
+        const value = commandOptions[key];
         actionCommand.setOptionValueWithSource(key, value, "cli");
     }
     const residual = selectors.length > 0 ? selectors.join(",") : undefined;
@@ -540,6 +572,7 @@ function forwardReadOutputIncludeModes(actionCommand, commandPath, globalOptions
 function extractCommandScopedOptions(command, commandArgs, extensionFlagDefinitions = []) {
     const allOptions = command.optsWithGlobals();
     const scoped = { ...allOptions };
+    copyReadOutputInvocationProvenance(command, scoped);
     delete scoped.json;
     delete scoped.quiet;
     delete scoped.path;
@@ -2355,8 +2388,7 @@ async function handleRunPmCliError(params) {
         emitTelemetryCommandError: context.emitTelemetryCommandError,
     });
 }
-/** Implements run pm cli for the public runtime surface of this module. */
-export async function runPmCli(rawArgv = process.argv.slice(2)) {
+async function runPmCliInReproducibleContext(rawArgv) {
     program = createPmCliProgram(CLI_VERSION);
     attachProgramLifecycleHooks(program);
     // The runtime-extension snapshot caches dedupe discovery work within a
@@ -2426,6 +2458,15 @@ export async function runPmCli(rawArgv = process.argv.slice(2)) {
         restorePmAuthor?.();
     }
 }
+/** Implements run pm cli for the public runtime surface of this module. */
+export async function runPmCli(rawArgv = process.argv.slice(2)) {
+    try {
+        await runWithReproducibleProcessEnvironment(process.env, () => runPmCliInReproducibleContext(rawArgv));
+    }
+    catch (error) {
+        await handleRunPmCliError({ error, invocationArgv: [...rawArgv] });
+    }
+}
 /** Public contract for test only, shared by SDK and presentation-layer consumers. */
 export const _testOnly = {
     activationCommandMatchesProbe,
@@ -2493,6 +2534,7 @@ export const _testOnly = {
     readRecordBoolean,
     readRecordNumber,
     readRecordString,
+    recordCliReadOutputInvocationProvenance,
     registerDynamicExtensionCommandPaths,
     registerRuntimeSchemaFieldFlags,
     resolveCoreCommandRegistrationSelection,
@@ -2516,4 +2558,4 @@ export const _testOnly = {
     wrapThrownErrorForSentry,
 };
 //# sourceMappingURL=main.js.map
-//# debugId=27eeca2d-756c-539b-a0d4-d64516ee4aa6
+//# debugId=7289d222-cf1f-5fa5-ac8a-d690b6012e39

package/dist/cli/register-mutation.js

@@ -1,7 +1,7 @@
 
-!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]="07f3212f-c6d3-534e-8273-fae43a8fca18")}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]="49cddeba-127e-5d6c-a62d-4a63088ce8c6")}catch(e){}}();
 import { resolveBodyFileContent, EXIT_CODE, splitCommaList, PmCliError, createUnknownSubcommandError, } from "../sdk/runtime-primitives.js";
-import { CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, PLAN_CREATE_METADATA_PARAMETER_KEYS, UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, } from "../sdk/cli-contracts.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";
 import { MERGE_DRIVER_ARTIFACT_VALUES, runMergeDriver, runMergeInstall, runMergeReconcile, runMergeReceiptReport, } from "./commands/merge.js";
 import { runAppend } from "./commands/append.js";
@@ -823,7 +823,7 @@ async function runMergeAction(subcommand, artifact, base, ours, theirs, options,
             throw createUnknownSubcommandError({
                 command_path: "merge",
                 token: subcommand,
-                allowed: ["install", "reconcile", "report", "driver"],
+                allowed: MERGE_SUBCOMMAND_VALUES,
                 display_name: "merge",
             });
     }
@@ -898,7 +898,7 @@ async function runSchemaAction(subcommand, name, options, command) {
     assertSchemaSubcommandPresent(normalizedSubcommand, SCHEMA_SUBCOMMANDS);
     if (!SCHEMA_SUBCOMMANDS.includes(normalizedSubcommand) &&
         typeName === undefined &&
-        !looksLikeSchemaSubcommandTypo(normalizedSubcommand)) {
+        !looksLikeSchemaSubcommandTypo(subcommand)) {
         typeName = subcommand;
         normalizedSubcommand = "add-type";
     }
@@ -1724,7 +1724,7 @@ export function registerMutationCommands(program, registrationOptions = {}) {
         .action(runHistoryCompactAction);
     program
         .command("merge")
-        .argument("<subcommand>", "Merge subcommand: install, reconcile, report, driver")
+        .argument("<subcommand>", `Merge subcommand: ${MERGE_SUBCOMMAND_VALUES.join(", ")}`)
         .argument("[artifact]", `driver only: artifact class to merge (${MERGE_DRIVER_ARTIFACT_VALUES.join(", ")})`)
         .argument("[base]", "driver only: common-ancestor file path (git %O)")
         .argument("[ours]", "driver only: current-branch file path (git %A)")
@@ -1840,4 +1840,4 @@ export function registerMutationCommands(program, registrationOptions = {}) {
         .action(runDepsAction);
 }
 //# sourceMappingURL=register-mutation.js.map
-//# debugId=07f3212f-c6d3-534e-8273-fae43a8fca18
+//# debugId=49cddeba-127e-5d6c-a62d-4a63088ce8c6

package/dist/cli/register-operations.d.ts

@@ -4,7 +4,80 @@
  * Provides CLI runtime support for Register Operations.
  */
 import type { Command } from "commander";
+declare function validateBackgroundTestOptions(options: Record<string, unknown>, values: {
+    addValues: string[];
+    addJsonValues: string[];
+    removeValues: string[];
+    removeIndexValues: string[];
+}): void;
+declare function buildRunTestOptions(options: Record<string, unknown>, values: {
+    addValues: string[];
+    addJsonValues: string[];
+    removeValues: string[];
+    removeIndexValues: string[];
+}): {
+    add: string[];
+    addJson: string[];
+    remove: string[];
+    removeIndex: string[];
+    list: boolean;
+    run: boolean;
+    match: string | undefined;
+    onlyIndex: string | number | undefined;
+    onlyLast: boolean;
+    timeout: string | undefined;
+    progress: boolean;
+    envSet: string[];
+    envClear: string[];
+    sharedHostSafe: boolean;
+    pmContext: string | undefined;
+    overrideLinkedPmContext: boolean;
+    workspaceContext: string | undefined;
+    overrideLinkedWorkspaceContext: boolean;
+    allowUntrustedLinkedTests: boolean;
+    acknowledgeLinkedTests: boolean;
+    failOnContextMismatch: boolean;
+    failOnSkipped: boolean;
+    failOnEmptyTestRun: boolean;
+    requireAssertionsForPm: boolean;
+    checkContext: boolean;
+    autoPmContext: boolean;
+    author: string | undefined;
+    message: string | undefined;
+    force: boolean;
+    measure: string[];
+    metricBelow: string | undefined;
+    metricDiff: string | undefined;
+};
+/** Public contract for test-only operation adapter coverage. */
+export declare const _testOnlyRegisterOperations: {
+    buildRunTestOptions: typeof buildRunTestOptions;
+    buildRunTestAllOptions: typeof buildRunTestAllOptions;
+    validateBackgroundTestOptions: typeof validateBackgroundTestOptions;
+};
+declare function buildRunTestAllOptions(options: Record<string, unknown>): {
+    status: string | undefined;
+    limit: string | undefined;
+    offset: string | undefined;
+    timeout: string | undefined;
+    progress: boolean;
+    envSet: string[];
+    envClear: string[];
+    sharedHostSafe: boolean;
+    pmContext: string | undefined;
+    overrideLinkedPmContext: boolean;
+    workspaceContext: string | undefined;
+    overrideLinkedWorkspaceContext: boolean;
+    allowUntrustedLinkedTests: boolean;
+    failOnContextMismatch: boolean;
+    failOnSkipped: boolean;
+    failOnEmptyTestRun: boolean;
+    requireAssertionsForPm: boolean;
+    checkContext: boolean;
+    autoPmContext: boolean;
+};
 /** Enforces the claim target XOR selection contract before dispatch. */
 export declare function requireClaimTarget(id: string | undefined, next: boolean): void;
 /** Implements register operation commands for the public runtime surface of this module. */
 export declare function registerOperationCommands(program: Command): void;
+export {};