@unbrained/pm-cli 2026.8.22 → 2026.8.24

package/dist/sdk/agent/refusal-corpus-contracts.js

@@ -0,0 +1,194 @@
+/**
+ * @module sdk/agent/refusal-corpus-contracts
+ *
+ * Derives executable refusal probes from the public CLI grammar. The corpus is
+ * fail-closed: adding a required positional slot or action-dispatching command
+ * automatically adds a probe, while an action family without an authoritative
+ * value domain throws during contract construction.
+ */
+
+!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]="2e90ea29-2708-5af8-b390-599be97718e7")}catch(e){}}();
+import { PLAN_SUBCOMMANDS } from "../lifecycle/plan.js";
+import { PROFILE_SUBCOMMANDS } from "../profile.js";
+import { SCHEMA_SUBCOMMANDS } from "../schema.js";
+import { GRAPH_SUBCOMMAND_VALUES, MERGE_SUBCOMMAND_VALUES, } from "../cli-contracts/enum-contracts.js";
+import { PM_COMMAND_DESTINATION_CONTRACTS, PM_COMMAND_POSITIONAL_CONTRACTS, PM_POSITIONAL_ACTION_CONTRACTS, } from "../cli-contracts/grammar-contracts.js";
+import { resolveSubcommandFlagContractsForCommand } from "../cli-contracts/flag-contracts.js";
+const REJECTED_ACTION = "not-a-declared-action";
+function positionalPlaceholder(command, slot) {
+    if (command.startsWith("assurance ") && slot.name === "kind") {
+        return "measurement";
+    }
+    switch (slot.value_kind) {
+        case "integer":
+            return "1";
+        case "item_id":
+            return "pm-domain";
+        case "action":
+            throw new Error(`Cannot synthesize a preceding action value for positional slot ${slot.name}.`);
+        default:
+            return "example";
+    }
+}
+function probeSlug(value) {
+    return value.replaceAll(/[^a-z0-9]+/gu, "-").replaceAll(/^-|-$/gu, "");
+}
+/**
+ * Return one omission probe for every required slot in the declared grammar.
+ * Earlier positionals receive deterministic, non-mutating placeholder values.
+ */
+export function listPmRequiredArgumentRefusalContracts(contracts = PM_COMMAND_POSITIONAL_CONTRACTS.filter((contract) => PM_COMMAND_DESTINATION_CONTRACTS.some((destination) => destination.command === contract.command &&
+    destination.disposition !== "package_owned"))) {
+    return contracts
+        .flatMap((contract) => contract.slots.flatMap((slot, index) => {
+        if (!slot.required)
+            return [];
+        const commandArguments = contract.command.split(" ");
+        const requiredFlagArguments = resolveSubcommandFlagContractsForCommand(contract.command).flatMap((flagContract) => flagContract.required
+            ? [
+                flagContract.flag,
+                ...(flagContract.value_name ? ["example"] : []),
+            ]
+            : []);
+        const isVirtualAction = PM_POSITIONAL_ACTION_CONTRACTS.some((actionContract) => actionContract.command === contract.command);
+        return [
+            {
+                probe_id: `required-argument-${probeSlug(contract.command)}-${probeSlug(slot.name)}`,
+                command: contract.command,
+                refusal_args: [
+                    ...commandArguments,
+                    ...contract.slots
+                        .slice(0, index)
+                        .map((priorSlot) => positionalPlaceholder(contract.command, priorSlot)),
+                    ...requiredFlagArguments,
+                ],
+                recovery_args: [...commandArguments, "--help"],
+                error_code: isVirtualAction && !contract.command.startsWith("assurance ")
+                    ? "invalid_argument_value"
+                    : /^extension (?:activate|adopt|deactivate|uninstall)$/u.test(contract.command)
+                        ? "missing_lifecycle_target"
+                        : "missing_required_argument",
+                missing_argument: slot.name,
+                missing_argument_index: index,
+            },
+        ];
+    }))
+        .sort((left, right) => left.probe_id.localeCompare(right.probe_id));
+}
+function positionalActionValues(command) {
+    switch (command) {
+        case "assurance":
+        case "workspace snapshot":
+            return PM_POSITIONAL_ACTION_CONTRACTS.filter(({ parent }) => parent === command).map(({ action }) => action);
+        case "graph":
+            return GRAPH_SUBCOMMAND_VALUES;
+        case "merge":
+            return MERGE_SUBCOMMAND_VALUES;
+        case "plan":
+            return PLAN_SUBCOMMANDS;
+        case "profile":
+            return PROFILE_SUBCOMMANDS;
+        case "schema":
+            return SCHEMA_SUBCOMMANDS;
+        default:
+            throw new Error(`Required positional action family ${command} has no authoritative value domain.`);
+    }
+}
+/** Return one invalid-action probe for every required positional action family. */
+export function listPmSubcommandRefusalContracts(contracts = PM_COMMAND_POSITIONAL_CONTRACTS) {
+    return contracts
+        .filter(({ slots }) => slots[0]?.required === true && slots[0].value_kind === "action")
+        .map(({ command }) => {
+        const commandArguments = command.split(" ");
+        return {
+            probe_id: `unknown-subcommand-${probeSlug(command)}`,
+            command,
+            refusal_args: [...commandArguments, REJECTED_ACTION],
+            recovery_args: [...commandArguments, "--help"],
+            error_code: "unknown_subcommand",
+            rejected_value: REJECTED_ACTION,
+            allowed_values: [...positionalActionValues(command)].sort(),
+        };
+    })
+        .sort((left, right) => left.probe_id.localeCompare(right.probe_id));
+}
+function sameValues(left, right) {
+    const sortedRight = [...right].sort();
+    return (left.length === right.length &&
+        [...left].sort().every((value, index) => value === sortedRight[index]));
+}
+function scoreGrammarRefusalObservation(contract, observation) {
+    if (!observation) {
+        return [
+            {
+                code: "refusal_probe_missing",
+                probe_id: contract.probe_id,
+                detail: `${contract.probe_id} has no runtime observation.`,
+            },
+        ];
+    }
+    const findings = [];
+    if (observation.error_code !== contract.error_code) {
+        findings.push({
+            code: "refusal_error_code_mismatch",
+            probe_id: contract.probe_id,
+            detail: `${contract.probe_id} emitted ${observation.error_code || "<none>"}; expected ${contract.error_code}.`,
+        });
+    }
+    if (observation.exit_code !== 2) {
+        findings.push({
+            code: "refusal_exit_code_mismatch",
+            probe_id: contract.probe_id,
+            detail: `${contract.probe_id} exited ${observation.exit_code}; expected usage exit 2.`,
+        });
+    }
+    if ("allowed_values" in contract &&
+        !sameValues(observation.allowed_values, contract.allowed_values)) {
+        findings.push({
+            code: "refusal_allowed_values_mismatch",
+            probe_id: contract.probe_id,
+            detail: `${contract.probe_id} did not expose its complete action domain.`,
+        });
+    }
+    if (!observation.recovery_succeeded) {
+        findings.push({
+            code: "refusal_recovery_failed",
+            probe_id: contract.probe_id,
+            detail: `${contract.probe_id} help recovery did not succeed.`,
+        });
+    }
+    if (observation.refusal_mutated_state) {
+        findings.push({
+            code: "refusal_mutated_state",
+            probe_id: contract.probe_id,
+            detail: `${contract.probe_id} changed tracker state while refusing input${observation.mutated_paths?.length ? `: ${observation.mutated_paths.join(", ")}` : "."}`,
+        });
+    }
+    return findings;
+}
+/** Score exact code, exit, domain, state-safety, and recovery closure. */
+export function scorePmGrammarRefusalClosure(contracts, observations) {
+    const contractsById = new Map(contracts.map((contract) => [contract.probe_id, contract]));
+    const observationsById = new Map(observations.map((observation) => [observation.probe_id, observation]));
+    const findings = [
+        ...contracts.flatMap((contract) => scoreGrammarRefusalObservation(contract, observationsById.get(contract.probe_id))),
+        ...observations
+            .filter((observation) => !contractsById.has(observation.probe_id))
+            .map((observation) => ({
+            code: "unexpected_refusal_probe",
+            probe_id: observation.probe_id,
+            detail: `${observation.probe_id} has no declared grammar refusal contract.`,
+        })),
+    ];
+    findings.sort((left, right) => left.probe_id.localeCompare(right.probe_id) ||
+        left.code.localeCompare(right.code));
+    const failedProbeIds = new Set(findings.map(({ probe_id: probeId }) => probeId));
+    return {
+        ok: findings.length === 0,
+        probe_count: contracts.length,
+        closed_probe_count: contracts.filter(({ probe_id: probeId }) => !failedProbeIds.has(probeId)).length,
+        findings,
+    };
+}
+//# sourceMappingURL=refusal-corpus-contracts.js.map
+//# debugId=2e90ea29-2708-5af8-b390-599be97718e7

package/dist/sdk/agent-capability-contracts.d.ts

@@ -1,7 +1,8 @@
+import type { ExtensionCommandCapabilityFamily } from "../core/extensions/command-metadata-contract.js";
 /** Visibility tiers shared by CLI help, completions, docs, extensions, and MCP. */
 export type PmCommandVisibilityTier = "core" | "standard" | "full" | "internal";
 /** Stable capability families shared by every agent-facing command surface. */
-export type PmCommandCapabilityFamily = "workspace" | "intake" | "context" | "lifecycle" | "evidence" | "graph" | "quality" | "automation" | "extensions" | "internal";
+export type PmCommandCapabilityFamily = ExtensionCommandCapabilityFamily;
 /** One command's canonical agent-surface visibility declaration. */
 export interface PmCommandVisibilityContract {
     /** Canonical command path. */
@@ -14,6 +15,13 @@ export interface PmCommandCapabilityContract extends PmCommandVisibilityContract
     /** Exactly one stable capability family used to group the command. */
     family: PmCommandCapabilityFamily;
 }
+/** One generated family route shared by guides, skills, and documentation. */
+export interface PmCommandCapabilityGroup {
+    /** Stable capability family. */
+    family: PmCommandCapabilityFamily;
+    /** Non-internal commands owned by the family. */
+    commands: readonly string[];
+}
 /** Resolve one command's stable capability family. */
 export declare function resolvePmCommandCapabilityFamily(command: string): PmCommandCapabilityFamily;
 /**
@@ -26,18 +34,39 @@ export declare function resolvePmCommandCapabilityFamily(command: string): PmCom
 export declare const PM_COMMAND_CAPABILITY_CONTRACTS: readonly PmCommandCapabilityContract[];
 /** Backward-compatible tier-only projection of the capability contract. */
 export declare const PM_COMMAND_VISIBILITY_CONTRACTS: readonly PmCommandVisibilityContract[];
+/** Bounded compact-help contract: one conventional terminal screen. */
+export declare const PM_CORE_HELP_BUDGET: Readonly<{
+    max_lines: 50;
+    max_utf8_bytes: 6000;
+}>;
+/** Root options retained in the compact progressive-disclosure help screen. */
+export declare const PM_CORE_HELP_OPTION_FLAGS: readonly string[];
+/** Measure rendered core help against its line and byte ceilings. */
+export declare function measurePmCoreHelp(text: string): {
+    lines: number;
+    utf8_bytes: number;
+    within_budget: boolean;
+};
 /** Resolve one command's declared tier; extension commands default to standard. */
 export declare function resolvePmCommandVisibilityTier(command: string, extensionTier?: PmCommandVisibilityTier): PmCommandVisibilityTier;
 /** Return commands visible at a requested tier, preserving contract order. */
 export declare function listPmCommandsForTier(tier: Exclude<PmCommandVisibilityTier, "internal">): string[];
+/** Project an explicit command registry into one visibility tier. */
+export declare function listPmCommandsForTierFromContracts(tier: Exclude<PmCommandVisibilityTier, "internal">, contracts: readonly PmCommandCapabilityContract[]): string[];
 /** Return commands in one capability family, preserving contract order. */
 export declare function listPmCommandsForFamily(family: PmCommandCapabilityFamily): string[];
+/** Project an explicit command registry into one capability family. */
+export declare function listPmCommandsForFamilyFromContracts(family: PmCommandCapabilityFamily, contracts: readonly PmCommandCapabilityContract[]): string[];
+/** Group the command registry for progressive-disclosure routing surfaces. */
+export declare function listPmCommandCapabilityGroups(contracts?: readonly PmCommandCapabilityContract[]): PmCommandCapabilityGroup[];
 /** MCP profile names accepted by the server and embedding hosts. */
 export type PmMcpToolProfile = "core" | "standard" | "full" | "custom";
 /** Mapping from one narrow MCP tool to the command contract that tiers it. */
 export declare const PM_MCP_TOOL_COMMAND_CONTRACTS: Readonly<Record<string, string>>;
 /** Resolve the tools visible in a named MCP profile from command tiers. */
 export declare function listPmMcpToolsForProfile(availableTools: readonly string[], profile: Exclude<PmMcpToolProfile, "custom">): string[];
+/** Project an explicit command registry into one MCP tool profile. */
+export declare function listPmMcpToolsForProfileFromContracts(availableTools: readonly string[], profile: Exclude<PmMcpToolProfile, "custom">, contracts: readonly PmCommandCapabilityContract[]): string[];
 /** Stable MCP resource contract generated from the same agent surface table. */
 export interface PmMcpResourceContract {
     /** Stable resource URI. */
@@ -75,3 +104,7 @@ export interface PmMcpPromptContract {
 export declare const PM_MCP_PROMPT_CONTRACTS: readonly PmMcpPromptContract[];
 /** Render the generated command visibility reference used by docs drift gates. */
 export declare function renderPmCommandVisibilityMarkdown(): string;
+/** Render an explicit registry for mutation-sensitivity and host tooling. */
+export declare function renderPmCommandVisibilityMarkdownFromContracts(contracts: readonly PmCommandCapabilityContract[]): string;
+/** Render family routing for generated docs and skill progressive disclosure. */
+export declare function renderPmCapabilityRoutingMarkdown(contracts?: readonly PmCommandCapabilityContract[]): string;

package/dist/sdk/agent-capability-contracts.js

@@ -5,7 +5,7 @@
  * surfaces from one public SDK contract.
  */
 
-!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]="5e77c121-35a2-57d1-9a3e-f33447535c03")}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]="51e187c6-d48f-59e8-ad23-c72670ade3cc")}catch(e){}}();
 import { PM_CORE_COMMAND_NAMES } from "./cli-contracts/enum-contracts.js";
 const CORE_COMMANDS = new Set([
     "claim",
@@ -14,6 +14,7 @@ const CORE_COMMANDS = new Set([
     "create",
     "get",
     "help",
+    "init",
     "list",
     "next",
     "plan",
@@ -167,6 +168,36 @@ export const PM_COMMAND_CAPABILITY_CONTRACTS = Object.freeze([
 ]);
 /** Backward-compatible tier-only projection of the capability contract. */
 export const PM_COMMAND_VISIBILITY_CONTRACTS = PM_COMMAND_CAPABILITY_CONTRACTS;
+/** Bounded compact-help contract: one conventional terminal screen. */
+export const PM_CORE_HELP_BUDGET = Object.freeze({
+    max_lines: 50,
+    max_utf8_bytes: 6000,
+});
+/** Root options retained in the compact progressive-disclosure help screen. */
+export const PM_CORE_HELP_OPTION_FLAGS = Object.freeze([
+    "-V, --version",
+    "--json",
+    "--output-include <fields>",
+    "--output-limit <count>",
+    "--output-budget <tokens|unbounded>",
+    "--output-cursor <cursor>",
+    "--pm-path <dir>",
+    "--no-extensions",
+    "--no-pager",
+    "--explain",
+    "-h, --help",
+]);
+/** Measure rendered core help against its line and byte ceilings. */
+export function measurePmCoreHelp(text) {
+    const lines = text === "" ? 0 : text.split(/\r?\n/).length;
+    const utf8Bytes = Buffer.byteLength(text, "utf8");
+    return {
+        lines,
+        utf8_bytes: utf8Bytes,
+        within_budget: lines <= PM_CORE_HELP_BUDGET.max_lines &&
+            utf8Bytes <= PM_CORE_HELP_BUDGET.max_utf8_bytes,
+    };
+}
 const TIER_ORDER = {
     core: 0,
     standard: 1,
@@ -180,12 +211,55 @@ export function resolvePmCommandVisibilityTier(command, extensionTier = "standar
 }
 /** Return commands visible at a requested tier, preserving contract order. */
 export function listPmCommandsForTier(tier) {
+    return listPmCommandsForTierFromContracts(tier, PM_COMMAND_CAPABILITY_CONTRACTS);
+}
+/** Project an explicit command registry into one visibility tier. */
+export function listPmCommandsForTierFromContracts(tier, contracts) {
     const maximum = TIER_ORDER[tier];
-    return PM_COMMAND_VISIBILITY_CONTRACTS.filter((entry) => entry.tier !== "internal" && TIER_ORDER[entry.tier] <= maximum).map((entry) => entry.command);
+    return contracts
+        .filter((entry) => entry.tier !== "internal" && TIER_ORDER[entry.tier] <= maximum)
+        .map((entry) => entry.command);
 }
 /** Return commands in one capability family, preserving contract order. */
 export function listPmCommandsForFamily(family) {
-    return PM_COMMAND_CAPABILITY_CONTRACTS.filter((entry) => entry.family === family).map((entry) => entry.command);
+    return listPmCommandsForFamilyFromContracts(family, PM_COMMAND_CAPABILITY_CONTRACTS);
+}
+/** Project an explicit command registry into one capability family. */
+export function listPmCommandsForFamilyFromContracts(family, contracts) {
+    return contracts
+        .filter((entry) => entry.family === family)
+        .map((entry) => entry.command);
+}
+const CAPABILITY_FAMILY_ORDER = [
+    "workspace",
+    "intake",
+    "context",
+    "lifecycle",
+    "evidence",
+    "graph",
+    "quality",
+    "automation",
+    "extensions",
+    "internal",
+];
+const CAPABILITY_ROUTING_EXCLUDED_ALIASES = new Set([
+    "ctx",
+    "item-reopen",
+    "list-all",
+    "list-blocked",
+    "list-canceled",
+    "list-closed",
+    "list-draft",
+    "list-in-progress",
+    "list-open",
+]);
+/** Group the command registry for progressive-disclosure routing surfaces. */
+export function listPmCommandCapabilityGroups(contracts = PM_COMMAND_CAPABILITY_CONTRACTS) {
+    return CAPABILITY_FAMILY_ORDER.map((family) => ({
+        family,
+        commands: listPmCommandsForFamilyFromContracts(family, contracts).filter((command) => contracts.find((entry) => entry.command === command)?.tier !==
+            "internal" && !CAPABILITY_ROUTING_EXCLUDED_ALIASES.has(command)),
+    })).filter(({ commands }) => commands.length > 0);
 }
 /** Mapping from one narrow MCP tool to the command contract that tiers it. */
 export const PM_MCP_TOOL_COMMAND_CONTRACTS = Object.freeze({
@@ -223,9 +297,13 @@ export const PM_MCP_TOOL_COMMAND_CONTRACTS = Object.freeze({
 });
 /** Resolve the tools visible in a named MCP profile from command tiers. */
 export function listPmMcpToolsForProfile(availableTools, profile) {
+    return listPmMcpToolsForProfileFromContracts(availableTools, profile, PM_COMMAND_CAPABILITY_CONTRACTS);
+}
+/** Project an explicit command registry into one MCP tool profile. */
+export function listPmMcpToolsForProfileFromContracts(availableTools, profile, contracts) {
     if (profile === "full")
         return [...availableTools];
-    const visibleCommands = new Set(listPmCommandsForTier(profile));
+    const visibleCommands = new Set(listPmCommandsForTierFromContracts(profile, contracts));
     return availableTools.filter((tool) => {
         const command = PM_MCP_TOOL_COMMAND_CONTRACTS[tool];
         return command !== undefined && visibleCommands.has(command);
@@ -309,7 +387,11 @@ export const PM_MCP_PROMPT_CONTRACTS = Object.freeze([
 ]);
 /** Render the generated command visibility reference used by docs drift gates. */
 export function renderPmCommandVisibilityMarkdown() {
-    const rows = PM_COMMAND_CAPABILITY_CONTRACTS.map(({ command, tier, family }) => `| \`${command}\` | ${tier} | ${family} |`);
+    return renderPmCommandVisibilityMarkdownFromContracts(PM_COMMAND_CAPABILITY_CONTRACTS);
+}
+/** Render an explicit registry for mutation-sensitivity and host tooling. */
+export function renderPmCommandVisibilityMarkdownFromContracts(contracts) {
+    const rows = contracts.map(({ command, tier, family }) => `| \`${command}\` | ${tier} | ${family} |`);
     return [
         "# Generated agent command surface",
         "",
@@ -321,5 +403,21 @@ export function renderPmCommandVisibilityMarkdown() {
         "",
     ].join("\n");
 }
+/** Render family routing for generated docs and skill progressive disclosure. */
+export function renderPmCapabilityRoutingMarkdown(contracts = PM_COMMAND_CAPABILITY_CONTRACTS) {
+    const rows = listPmCommandCapabilityGroups(contracts).map(({ family, commands }) => `| ${family} | ${commands.map((command) => `\`${command}\``).join(", ")} |`);
+    return [
+        "# Generated agent capability routing",
+        "",
+        "Tracker: `pm-kxci8x`.",
+        "",
+        "This file is generated from `PM_COMMAND_CAPABILITY_CONTRACTS`. Do not edit it manually.",
+        "",
+        "| Capability family | Commands |",
+        "| --- | --- |",
+        ...rows,
+        "",
+    ].join("\n");
+}
 //# sourceMappingURL=agent-capability-contracts.js.map
-//# debugId=5e77c121-35a2-57d1-9a3e-f33447535c03
+//# debugId=51e187c6-d48f-59e8-ad23-c72670ade3cc

package/dist/sdk/annotations.d.ts

@@ -146,6 +146,8 @@ export declare function parseAnnotationTextInput(raw: string, options?: {
 export declare function isErrnoError(error: unknown): error is {
     code?: unknown;
 };
+/** Refuse presentation-level stdin directives when JSON-RPC owns the process stream. */
+export declare function assertAnnotationStdinTransportAvailable(options: AnnotationSourceOptions, optionName: string): void;
 /** Resolves mutually exclusive annotation input flags into one normalized SDK operation. */
 export declare function resolveAnnotationInput(options: AnnotationSourceOptions, noun: string): Promise<AnnotationInput>;
 /** Implements wrap ownership conflict for the public runtime surface of this module. */

package/dist/sdk/annotations.js

@@ -4,13 +4,13 @@
  * Implements the pm annotation command command surface and its agent-facing runtime behavior.
  */
 
-!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]="eac75dc5-80b4-50d2-b615-4f96edca7346")}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]="39acab93-f9ad-5b95-871e-625d912f1322")}catch(e){}}();
 import { assertInitializedTracker } from "./environment/tracker-preflight.js";
 import { readFile } from "node:fs/promises";
 import { isFileAbsentError } from "../core/fs/fs-utils.js";
 import { getActiveExtensionRegistrations } from "../core/extensions/index.js";
 import { resolveItemTypeRegistry } from "../core/item/type-registry.js";
-import { createStdinTokenResolver, parseCsvKv } from "../core/item/parse.js";
+import { createStdinTokenResolver, parseCsvKv, shouldResolveMutationStdinTokens, transferMutationStdinTokenPolicy, } from "../core/item/parse.js";
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { parseLimit } from "../core/shared/numeric-parsers.js";
@@ -26,7 +26,7 @@ export function normalizeAnnotationTransportOptions(options) {
         ...(options.full === true ? { fullHistory: true } : {}),
     };
     delete normalized.full;
-    return normalized;
+    return transferMutationStdinTokenPolicy(options, normalized);
 }
 /** Reject mutation of canonical structured events while allowing ordinary annotations. */
 function assertAnnotationEntryMutable(entry, operation) {
@@ -84,6 +84,15 @@ export function parseAnnotationTextInput(raw, options = {}) {
 export function isErrnoError(error) {
     return typeof error === "object" && error !== null && "code" in error;
 }
+/** Refuse presentation-level stdin directives when JSON-RPC owns the process stream. */
+export function assertAnnotationStdinTransportAvailable(options, optionName) {
+    if (shouldResolveMutationStdinTokens(options))
+        return;
+    throw new PmCliError(`${optionName} cannot read process stdin through the MCP JSON-RPC transport. Pass annotation text in options.add instead.`, EXIT_CODE.USAGE, {
+        code: "mcp_stdin_unavailable",
+        required: "Pass annotation text as JSON data; the MCP protocol already owns process stdin.",
+    });
+}
 async function resolveAnnotationTextSource(options, noun) {
     const sourceCount = Number(options.add !== undefined) +
         Number(options.stdin === true) +
@@ -92,14 +101,16 @@ async function resolveAnnotationTextSource(options, noun) {
         throw new PmCliError(`Specify ${noun} text using only one input source: --add, --stdin, or --file`, EXIT_CODE.USAGE);
     }
     const stdinResolver = createStdinTokenResolver();
+    const resolveStdinTokens = shouldResolveMutationStdinTokens(options);
     if (options.add !== undefined) {
         return {
-            value: (await stdinResolver.resolveValue(options.add, "--add")) ?? "",
+            value: (await stdinResolver.resolveValue(options.add, "--add", resolveStdinTokens)) ?? "",
             rawValue: options.add,
             emptyFlag: "--add",
         };
     }
     if (options.stdin === true) {
+        assertAnnotationStdinTransportAvailable(options, "--stdin");
         return {
             value: (await stdinResolver.resolveValue("-", "--stdin")) ?? "",
             emptyFlag: "--stdin",
@@ -111,15 +122,22 @@ async function resolveAnnotationTextSource(options, noun) {
     if (!filePath) {
         throw new PmCliError("--file path cannot be empty", EXIT_CODE.USAGE);
     }
+    if (filePath === "-") {
+        assertAnnotationStdinTransportAvailable(options, "--file -");
+        return {
+            value: (await stdinResolver.resolveValue("-", "--file")) ?? "",
+            emptyFlag: "--file",
+        };
+    }
     try {
         return { value: await readFile(filePath, "utf8"), emptyFlag: "--file" };
     }
     catch (error) {
         if (isErrnoError(error) && isFileAbsentError(error)) {
-            throw new PmCliError(`--file path not found: ${filePath}`, EXIT_CODE.USAGE);
+            throw new PmCliError(`--file path not found: ${filePath}. Use --file - to read stdin.`, EXIT_CODE.USAGE);
         }
         const detail = error instanceof Error ? error.message : String(error);
-        throw new PmCliError(`Failed to read --file path "${filePath}": ${detail}`, EXIT_CODE.USAGE);
+        throw new PmCliError(`Failed to read --file path "${filePath}": ${detail}. Use --file - to read stdin.`, EXIT_CODE.USAGE);
     }
 }
 /** Resolves mutually exclusive annotation input flags into one normalized SDK operation. */
@@ -398,4 +416,4 @@ function renderAnnotationResult(id, collectionKey, allEntries, limit, includeMet
     };
 }
 //# sourceMappingURL=annotations.js.map
-//# debugId=eac75dc5-80b4-50d2-b615-4f96edca7346
+//# debugId=39acab93-f9ad-5b95-871e-625d912f1322

package/dist/sdk/cli-contracts/agent-output-contracts.js

@@ -6,7 +6,7 @@
  * output policy without coupling package authors to pm's renderer.
  */
 
-!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]="b3f5a4bc-d853-530e-8f5e-d682d8b93c9d")}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]="1d338971-5a60-5b4e-b4c8-0705c8e8c98c")}catch(e){}}();
 import { PM_CORE_COMMAND_NAMES } from "./enum-contracts.js";
 /** Stable degradation stages applied when an output exceeds its token budget. */
 export const PM_OUTPUT_DEGRADATION_STEPS = [
@@ -218,8 +218,10 @@ function compactDiagnosticRecovery(value) {
         "retry_after_ms",
     ]) {
         const candidate = value[key];
-        if (Array.isArray(candidate))
-            compact[key] = candidate.slice(0, 3);
+        if (Array.isArray(candidate)) {
+            compact[key] =
+                key === "suggested_retry_args" ? candidate : candidate.slice(0, 3);
+        }
         else if (candidate !== undefined)
             compact[key] = candidate;
     }
@@ -473,4 +475,4 @@ export function projectPmDiagnosticText(output, correctiveAction, options = {})
     };
 }
 //# sourceMappingURL=agent-output-contracts.js.map
-//# debugId=b3f5a4bc-d853-530e-8f5e-d682d8b93c9d
+//# debugId=1d338971-5a60-5b4e-b4c8-0705c8e8c98c

package/dist/sdk/cli-contracts/enum-contracts.d.ts

@@ -28,6 +28,10 @@ export declare const PM_CORE_COMMAND_NAMES: readonly ["init", "config", "extensi
 export declare const GRAPH_SUBCOMMAND_VALUES: readonly ["ancestors", "descendants", "predecessors", "successors", "paths", "impact", "analyze", "audit", "communities", "redundancy", "dominators", "slack", "centrality", "articulation", "plan", "index"];
 /** Restricts graph subcommand values accepted by command, SDK, and MCP contracts. */
 export type GraphSubcommand = (typeof GRAPH_SUBCOMMAND_VALUES)[number];
+/** Supported values accepted by the merge subcommand contract across CLI and SDK surfaces. */
+export declare const MERGE_SUBCOMMAND_VALUES: readonly ["install", "reconcile", "report", "driver"];
+/** Restricts merge subcommand values accepted by command and SDK contracts. */
+export type MergeSubcommand = (typeof MERGE_SUBCOMMAND_VALUES)[number];
 /** Nested lifecycle verbs flattened by SDK and MCP package actions. */
 export declare const PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS: readonly ["init", "install", "uninstall", "explore", "manage", "describe", "reload", "doctor", "catalog", "adopt", "adopt-all", "activate", "deactivate"];
 /** Noun-first item lifecycle verbs flattened for SDK and MCP dispatch. */

package/dist/sdk/cli-contracts/enum-contracts.js

@@ -4,7 +4,7 @@
  * Defines SDK command-contract metadata for Enum Contracts.
  */
 
-!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]="8b8b6b8e-5061-5da4-a369-eca379c0090b")}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]="3935bae8-0a40-59ea-aca6-64e238d1f318")}catch(e){}}();
 import { KNOWN_EXTENSION_CAPABILITIES, KNOWN_EXTENSION_POLICY_MODES, KNOWN_EXTENSION_POLICY_SURFACES, KNOWN_EXTENSION_SANDBOX_PROFILES, KNOWN_EXTENSION_SERVICE_NAMES, KNOWN_EXTENSION_TRUST_MODES, } from "../../core/extensions/extension-types.js";
 import { PM_COMMAND_ALIAS_CONTRACTS } from "./command-aliases.js";
 /** Public contract for pm extension capability contracts, shared by SDK and presentation-layer consumers. */
@@ -124,6 +124,13 @@ export const GRAPH_SUBCOMMAND_VALUES = [
     "plan",
     "index",
 ];
+/** Supported values accepted by the merge subcommand contract across CLI and SDK surfaces. */
+export const MERGE_SUBCOMMAND_VALUES = [
+    "install",
+    "reconcile",
+    "report",
+    "driver",
+];
 /** Nested lifecycle verbs flattened by SDK and MCP package actions. */
 export const PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS = [
     "init",
@@ -208,4 +215,4 @@ export function isPmExtensionPolicySurfaceContract(value) {
     return PM_EXTENSION_POLICY_SURFACE_CONTRACTS.includes(value);
 }
 //# sourceMappingURL=enum-contracts.js.map
-//# debugId=8b8b6b8e-5061-5da4-a369-eca379c0090b
+//# debugId=3935bae8-0a40-59ea-aca6-64e238d1f318

package/dist/sdk/cli-contracts/flag-contracts.js

@@ -7,7 +7,7 @@
  * flag surface stays single-sourced across the CLI, SDK, and MCP boundaries.
  */
 
-!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]="e302f519-aa51-503b-bd1a-f3155338f133")}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]="6664bc8f-e5da-5593-a2df-ac45f1cef09e")}catch(e){}}();
 import { normalizeUniqueStringList } from "./string-lists.js";
 import { RESERVED_EXTENSION_HOST_FLAGS } from "../../core/extensions/reserved-host-flags.js";
 import { PM_POSITIONAL_ACTION_CONTRACTS, } from "./grammar-contracts.js";
@@ -894,6 +894,10 @@ export const TEST_FLAG_CONTRACTS = [
     { flag: "--shared-host-safe" },
     { flag: "--pm-context" },
     { flag: "--override-linked-pm-context" },
+    { flag: "--workspace-context" },
+    { flag: "--override-linked-workspace-context" },
+    { flag: "--allow-untrusted-linked-tests" },
+    { flag: "--acknowledge-linked-tests" },
     { flag: "--fail-on-context-mismatch" },
     { flag: "--fail-on-skipped" },
     { flag: "--fail-on-empty-test-run" },
@@ -920,6 +924,9 @@ export const TEST_ALL_FLAG_CONTRACTS = [
     { flag: "--shared-host-safe" },
     { flag: "--pm-context" },
     { flag: "--override-linked-pm-context" },
+    { flag: "--workspace-context" },
+    { flag: "--override-linked-workspace-context" },
+    { flag: "--allow-untrusted-linked-tests" },
     { flag: "--fail-on-context-mismatch" },
     { flag: "--fail-on-skipped" },
     { flag: "--fail-on-empty-test-run" },
@@ -1901,4 +1908,4 @@ export function toCompletionFlagString(flagContracts, includeGlobal = true) {
     return normalizeUniqueStringList(all).join(" ");
 }
 //# sourceMappingURL=flag-contracts.js.map
-//# debugId=e302f519-aa51-503b-bd1a-f3155338f133
+//# debugId=6664bc8f-e5da-5593-a2df-ac45f1cef09e