@unbrained/pm-cli 2026.8.23 → 2026.8.24

package/dist/core/extensions/command-metadata-contract.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @module core/extensions/command-metadata-contract
+ *
+ * Owns the closed metadata domains shared by extension registration, runtime
+ * validation, SDK contracts, and workspace projections.
+ */
+/** Canonical capability-family values accepted for every command surface. */
+export declare const EXTENSION_COMMAND_CAPABILITY_FAMILIES: readonly ["workspace", "intake", "context", "lifecycle", "evidence", "graph", "quality", "automation", "extensions", "internal"];
+/** Capability family an extension command contributes to agent routing. */
+export type ExtensionCommandCapabilityFamily = (typeof EXTENSION_COMMAND_CAPABILITY_FAMILIES)[number];

package/dist/core/extensions/command-metadata-contract.js

@@ -0,0 +1,23 @@
+/**
+ * @module core/extensions/command-metadata-contract
+ *
+ * Owns the closed metadata domains shared by extension registration, runtime
+ * validation, SDK contracts, and workspace projections.
+ */
+/** Canonical capability-family values accepted for every command surface. */
+
+!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]="b799a368-2a8a-5031-8d14-f6b9dc4a3978")}catch(e){}}();
+export const EXTENSION_COMMAND_CAPABILITY_FAMILIES = Object.freeze([
+    "workspace",
+    "intake",
+    "context",
+    "lifecycle",
+    "evidence",
+    "graph",
+    "quality",
+    "automation",
+    "extensions",
+    "internal",
+]);
+//# sourceMappingURL=command-metadata-contract.js.map
+//# debugId=b799a368-2a8a-5031-8d14-f6b9dc4a3978

package/dist/core/extensions/command-visibility-tier.js

@@ -1,9 +1,18 @@
 
-!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]="45d00ef3-870c-5f3f-89c1-6abd54c518fe")}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]="764d9a7d-90a2-578f-ab5d-bd0c039596df")}catch(e){}}();
 import { assertOptionalStringField } from "./registration-validation.js";
+import { EXTENSION_COMMAND_CAPABILITY_FAMILIES } from "./command-metadata-contract.js";
+const COMMAND_CAPABILITY_FAMILIES = new Set(EXTENSION_COMMAND_CAPABILITY_FAMILIES);
+function assertCommandCapabilityFamily(family) {
+    if (family !== undefined &&
+        !COMMAND_CAPABILITY_FAMILIES.has(String(family))) {
+        throw new Error(`registerCommand definition.family must be one of: ${EXTENSION_COMMAND_CAPABILITY_FAMILIES.join(", ")}`);
+    }
+}
 /** Validate optional command metadata strings and the closed visibility tier. */
 export function assertCommandDefinitionMetadataStrings(definition) {
     assertOptionalStringField("registerCommand definition.action", definition.action);
+    assertOptionalStringField("registerCommand definition.family", definition.family);
     assertOptionalStringField("registerCommand definition.description", definition.description);
     assertOptionalStringField("registerCommand definition.intent", definition.intent);
     assertOptionalStringField("registerCommand definition.tier", definition.tier);
@@ -15,6 +24,7 @@ export function assertCommandDefinitionMetadataStrings(definition) {
         tier !== "internal") {
         throw new Error("registerCommand definition.tier must be core, standard, full, or internal");
     }
+    assertCommandCapabilityFamily(definition.family);
 }
 //# sourceMappingURL=command-visibility-tier.js.map
-//# debugId=45d00ef3-870c-5f3f-89c1-6abd54c518fe
+//# debugId=764d9a7d-90a2-578f-ab5d-bd0c039596df

package/dist/core/extensions/extension-types.d.ts

@@ -13,6 +13,8 @@ import type { GetItemAtResult } from "../../sdk/history-read.js";
 import type { RelationshipEvent, RelationshipEventInput, RelationshipEventStore } from "../../sdk/relationship-history.js";
 import type { CommitWorkspaceTransactionOptions, WorkspaceTransactionCommitResult } from "../../sdk/workspace-transaction.js";
 import type { KnownItemFieldType } from "./item-field-types.js";
+import type { ExtensionCommandCapabilityFamily } from "./command-metadata-contract.js";
+export type { ExtensionCommandCapabilityFamily } from "./command-metadata-contract.js";
 /** Public contract for known extension capabilities, shared by SDK and presentation-layer consumers. */
 export declare const KNOWN_EXTENSION_CAPABILITIES: readonly ["commands", "renderers", "hooks", "schema", "importers", "search", "parser", "preflight", "services"];
 /** Restricts extension capability values accepted by command, SDK, and storage contracts. */
@@ -691,6 +693,8 @@ export interface CommandDefinition {
     flags?: FlagDefinition[];
     /** Minimum agent surface tier that should advertise this command. */
     tier?: "core" | "standard" | "full" | "internal";
+    /** Capability family used by generated agent routing surfaces. */
+    family?: ExtensionCommandCapabilityFamily;
 }
 /**
  * Optional command-definition metadata for first-class importer/exporter
@@ -1272,6 +1276,8 @@ export interface RegisteredExtensionCommandDefinition {
     arguments: ExtensionCommandArgumentDefinition[];
     /** Minimum agent surface tier that should advertise this command. */
     tier?: "core" | "standard" | "full" | "internal";
+    /** Capability family used by generated agent routing surfaces. */
+    family?: ExtensionCommandCapabilityFamily;
 }
 /** Documents the registered extension schema field definitions payload exchanged by command, SDK, and package integrations. */
 export interface RegisteredExtensionSchemaFieldDefinitions {

package/dist/core/extensions/extension-types.js

@@ -1,6 +1,6 @@
 /** Public contract for known extension capabilities, shared by SDK and presentation-layer consumers. */
 
-!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]="87454a57-b62e-560a-b66f-3c15d4a95cc2")}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]="ef5c8553-c206-5bb5-913a-85afb936f6d7")}catch(e){}}();
 export const KNOWN_EXTENSION_CAPABILITIES = [
     "commands",
     "renderers",
@@ -100,4 +100,4 @@ export function createDefaultExtensionGovernancePolicy() {
     };
 }
 //# sourceMappingURL=extension-types.js.map
-//# debugId=87454a57-b62e-560a-b66f-3c15d4a95cc2
+//# debugId=ef5c8553-c206-5bb5-913a-85afb936f6d7

package/dist/core/extensions/loader.js

@@ -4,7 +4,7 @@
  * Implements extension runtime contracts and governance for Loader.
  */
 
-!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]="10311c96-5cba-5021-a8c5-82abd6eeb6f5")}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]="e4e1b7c2-6551-5e56-b26a-30062aed5b97")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
@@ -1505,7 +1505,8 @@ class ExtensionApiRegistrar {
                 examples,
                 failure_hints: failureHints,
                 arguments: argumentsDefinition,
-                tier: definition.tier,
+                tier: definition.tier ?? "standard",
+                family: definition.family ?? "extensions",
             };
             if (description) {
                 registration.description = description;
@@ -2220,4 +2221,4 @@ export const _testOnlyLoader = {
     },
 };
 //# sourceMappingURL=loader.js.map
-//# debugId=10311c96-5cba-5021-a8c5-82abd6eeb6f5
+//# debugId=e4e1b7c2-6551-5e56-b26a-30062aed5b97

package/dist/core/io/body-file.js

@@ -4,10 +4,11 @@
  * Reads command body content from files, stdin, and inline arguments.
  */
 
-!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]="7426082f-94a6-5b4e-9748-d3faab2fe1d4")}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]="a97ee152-4d20-54f1-add9-fdb991ab6b33")}catch(e){}}();
 import { readFile } from "node:fs/promises";
 import { EXIT_CODE } from "../shared/constants.js";
 import { PmCliError } from "../shared/errors.js";
+import { createStdinTokenResolver } from "../item/parse.js";
 const defaultBodyFileReader = (path) => readFile(path, "utf8");
 /** Implements resolve body file content for the public runtime surface of this module. */
 export async function resolveBodyFileContent(bodyFile, inlineBody, readFileImpl = defaultBodyFileReader) {
@@ -31,6 +32,9 @@ export async function resolveBodyFileContent(bodyFile, inlineBody, readFileImpl
             why: "An empty --body-file value has no file to read the body from.",
         });
     }
+    if (path === "-") {
+        return (await createStdinTokenResolver().resolveValue("-", "--body-file"));
+    }
     try {
         return await readFileImpl(path);
     }
@@ -49,10 +53,11 @@ export async function resolveBodyFileContent(bodyFile, inlineBody, readFileImpl
             why: `The body content is loaded from the file at the supplied path, so an unreadable path cannot produce a body${errno ? ` (underlying error: ${errno})` : ""}.`,
             nextSteps: [
                 `Verify the path: ls -l "${path}"`,
+                "Or pipe the body with --body-file -.",
                 "Or pass the body inline with --body <text>.",
             ],
         });
     }
 }
 //# sourceMappingURL=body-file.js.map
-//# debugId=7426082f-94a6-5b4e-9748-d3faab2fe1d4
+//# debugId=a97ee152-4d20-54f1-add9-fdb991ab6b33

package/dist/core/io/bulk-ids-input.d.ts

@@ -0,0 +1,24 @@
+/** File reader injected by tests or host runtimes that virtualize argv files. */
+export type BulkIdsFileReader = (path: string) => Promise<string>;
+/** Stdin reader injected by tests or hosts that do not use process stdin. */
+export type BulkIdsStdinReader = (optionName: string) => Promise<string>;
+/** Dependencies used to resolve CLI-only external ID sources. */
+export interface BulkIdsInputReaders {
+    /** Read a UTF-8 `@path` payload. */
+    readFile?: BulkIdsFileReader;
+    /** Read the complete stdin payload for `-`. */
+    readStdin?: BulkIdsStdinReader;
+}
+/** Transport-native bulk ID shapes accepted by SDK and MCP adapters. */
+export type BulkIdsValue = string | number | readonly (string | number)[] | undefined;
+/** Parse comma- or line-delimited item IDs with stable first-seen deduplication. */
+export declare function parseBulkIdsText(raw: string): string[];
+/** Normalize SDK/MCP scalar-or-array ID input into the list query's CSV form. */
+export declare function normalizeBulkIdsValue(value: BulkIdsValue): string | undefined;
+/**
+ * Resolve one CLI `--ids` value. `-` reads newline/comma-delimited stdin and
+ * `@path` reads the same grammar from a UTF-8 file; ordinary argv text accepts
+ * the grammar inline. The return value is canonical CSV for existing list
+ * filtering and unmatched-id accounting.
+ */
+export declare function resolveCliBulkIdsInput(value: string | undefined, optionName?: string, readers?: BulkIdsInputReaders): Promise<string | undefined>;

package/dist/core/io/bulk-ids-input.js

@@ -0,0 +1,113 @@
+/**
+ * @module core/io/bulk-ids-input
+ *
+ * Normalizes bulk item-id selectors supplied inline, through stdin, or from an
+ * argv-referenced file. Presentation layers can share the parser while MCP and
+ * embedded SDK callers keep passing transport-native arrays.
+ */
+
+!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]="411f4336-eb02-5167-9dce-ea99822a8a14")}catch(e){}}();
+import { readFile } from "node:fs/promises";
+import { createStdinTokenResolver } from "../item/parse.js";
+import { EXIT_CODE } from "../shared/constants.js";
+import { PmCliError } from "../shared/errors.js";
+const defaultFileReader = (path) => readFile(path, "utf8");
+const defaultStdinReader = async (optionName) => (await createStdinTokenResolver().resolveValue("-", optionName));
+/** Parse comma- or line-delimited item IDs with stable first-seen deduplication. */
+export function parseBulkIdsText(raw) {
+    return [
+        ...new Set(raw
+            .split(/[,\r\n]+/)
+            .map((entry) => entry.trim())
+            .filter((entry) => entry.length > 0)),
+    ];
+}
+function normalizeBulkIdsArray(value) {
+    const entries = [];
+    for (const entry of value) {
+        if (typeof entry === "string") {
+            entries.push(entry);
+        }
+        else if (typeof entry === "number" && Number.isFinite(entry)) {
+            entries.push(String(entry));
+        }
+        else {
+            return "";
+        }
+    }
+    const ids = parseBulkIdsText(entries.join("\n"));
+    return ids.length > 0 ? ids.join(",") : "";
+}
+/** Normalize SDK/MCP scalar-or-array ID input into the list query's CSV form. */
+export function normalizeBulkIdsValue(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value === "number") {
+        // Preserve an explicitly supplied but invalid numeric selector as blank so
+        // the bulk lifecycle's fail-closed empty-ID guard rejects it. Returning
+        // undefined here would erase the allowlist and could broaden a mutation to
+        // every item matched by the remaining filters.
+        return Number.isFinite(value) ? String(value) : "";
+    }
+    if (Array.isArray(value)) {
+        return normalizeBulkIdsArray(value);
+    }
+    if (typeof value !== "string") {
+        return "";
+    }
+    const ids = parseBulkIdsText(value);
+    return ids.length > 0 ? ids.join(",") : "";
+}
+/**
+ * Resolve one CLI `--ids` value. `-` reads newline/comma-delimited stdin and
+ * `@path` reads the same grammar from a UTF-8 file; ordinary argv text accepts
+ * the grammar inline. The return value is canonical CSV for existing list
+ * filtering and unmatched-id accounting.
+ */
+export async function resolveCliBulkIdsInput(value, optionName = "--ids", readers = {}) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    let raw = value;
+    try {
+        if (trimmed === "-") {
+            raw = await (readers.readStdin ?? defaultStdinReader)(optionName);
+        }
+        else if (trimmed.startsWith("@")) {
+            const path = trimmed.slice(1).trim();
+            if (path.length === 0) {
+                throw new PmCliError(`${optionName} @path requires a non-empty file path.`, EXIT_CODE.USAGE, {
+                    code: "bulk_ids_input_missing_path",
+                    required: `Pass ${optionName} @<path>, ${optionName} -, or inline IDs.`,
+                });
+            }
+            raw = await (readers.readFile ?? defaultFileReader)(path);
+        }
+    }
+    catch (error) {
+        if (error instanceof PmCliError) {
+            throw error;
+        }
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new PmCliError(`${optionName} could not read ${trimmed === "-" ? "stdin" : `"${trimmed.slice(1).trim()}"`}: ${detail}`, EXIT_CODE.NOT_FOUND, {
+            code: "bulk_ids_input_unreadable",
+            required: `Provide readable newline/comma-delimited IDs via ${optionName} -, ${optionName} @<path>, or inline argv text.`,
+            nextSteps: [
+                `Retry with inline IDs: ${optionName} pm-a1b2,pm-c3d4`,
+                `Or pipe IDs: pm list --id-only | pm update-many ${optionName} - --dry-run`,
+            ],
+        });
+    }
+    const normalized = normalizeBulkIdsValue(raw);
+    if (normalized !== "") {
+        return normalized;
+    }
+    throw new PmCliError(`${optionName} requires at least one non-empty item ID.`, EXIT_CODE.USAGE, {
+        code: "bulk_ids_input_empty",
+        required: `Provide one or more comma- or newline-delimited IDs through argv, stdin, or @path.`,
+    });
+}
+//# sourceMappingURL=bulk-ids-input.js.map
+//# debugId=411f4336-eb02-5167-9dce-ea99822a8a14

package/dist/core/item/parse.d.ts

@@ -53,10 +53,30 @@ export declare function assertNoUnknownCsvKeys(kv: Record<string, string>, optio
 /** Documents the stdin token resolver payload exchanged by command, SDK, and package integrations. */
 export interface StdinTokenResolver {
     /** Value that configures or reports resolve value for this contract. */
-    resolveValue(value: string | undefined, optionName: string): Promise<string | undefined>;
+    resolveValue(value: string | undefined, optionName: string, resolveToken?: boolean): Promise<string | undefined>;
     /** Value that configures or reports resolve list for this contract. */
-    resolveList(values: string[] | undefined, optionName: string): Promise<string[] | undefined>;
+    resolveList(values: string[] | undefined, optionName: string, resolveToken?: boolean): Promise<string[] | undefined>;
 }
+/** Mark transport-decoded options whose dash values are data, not stdin tokens. */
+export declare function preserveMutationStdinTokenLiterals<T extends object>(options: T): T;
+/** Mark selected mutation fields whose dash values are literal transport data. */
+export declare function preserveMutationStdinTokenFields<T extends object>(options: T, fields: readonly PropertyKey[]): T;
+/** Copy the complete mutation stdin-token policy across an option clone. */
+export declare function transferMutationStdinTokenPolicy<T extends object>(source: object, target: T): T;
+/** Add a source mutation stdin-token policy without weakening the target. */
+export declare function overlayMutationStdinTokenPolicy<T extends object>(source: object, target: T): T;
+/** Report whether lifecycle input should interpret dash values as stdin tokens. */
+export declare function shouldResolveMutationStdinTokens(options: object): boolean;
+/** Report whether one mutation field should interpret dash as a stdin token. */
+export declare function shouldResolveMutationStdinTokenField(options: object, field: PropertyKey): boolean;
+/** Refuse competing stdin-token fields before any resolver starts reading. */
+export declare function assertSingleStdinTokenConsumer(candidates: readonly {
+    value: string | readonly string[] | undefined;
+    optionName: string;
+    resolveToken?: boolean;
+}[]): void;
+/** Resolve a typed mutation option bag only after its complete stdin plan is conflict-free. */
+export declare function resolveMutationStdinTokenFields<T extends object>(options: T, scalarFields: readonly (readonly [keyof T & string, string])[], listFields: readonly (readonly [keyof T & string, string])[]): Promise<T>;
 /** Implements create stdin token resolver for the public runtime surface of this module. */
 export declare function createStdinTokenResolver(): StdinTokenResolver;
 /** Implements parse optional number for the public runtime surface of this module. */

package/dist/core/item/parse.js

@@ -4,7 +4,7 @@
  * Defines item parsing, formatting, and lifecycle helpers for Parse.
  */
 
-!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]="d5003dd5-f208-5734-9711-dff935d8c851")}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]="2252cfb9-37ea-57f1-b7ea-2b0c0f87ecb2")}catch(e){}}();
 import { PmCliError } from "../shared/errors.js";
 import { EXIT_CODE } from "../shared/constants.js";
 const STDIN_TOKEN = "-";
@@ -416,6 +416,95 @@ async function readStdinText(optionName) {
         });
     });
 }
+const ALL_MUTATION_STDIN_FIELDS = Symbol("all-mutation-stdin-fields");
+const literalStdinTokenFields = new WeakMap();
+/** Mark transport-decoded options whose dash values are data, not stdin tokens. */
+export function preserveMutationStdinTokenLiterals(options) {
+    literalStdinTokenFields.set(options, ALL_MUTATION_STDIN_FIELDS);
+    return options;
+}
+/** Mark selected mutation fields whose dash values are literal transport data. */
+export function preserveMutationStdinTokenFields(options, fields) {
+    const current = literalStdinTokenFields.get(options);
+    if (current === ALL_MUTATION_STDIN_FIELDS)
+        return options;
+    literalStdinTokenFields.set(options, new Set([...(current ?? []), ...fields]));
+    return options;
+}
+/** Copy the complete mutation stdin-token policy across an option clone. */
+export function transferMutationStdinTokenPolicy(source, target) {
+    const policy = literalStdinTokenFields.get(source);
+    if (policy === undefined)
+        return target;
+    literalStdinTokenFields.set(target, policy === ALL_MUTATION_STDIN_FIELDS ? policy : new Set(policy));
+    return target;
+}
+/** Add a source mutation stdin-token policy without weakening the target. */
+export function overlayMutationStdinTokenPolicy(source, target) {
+    const sourcePolicy = literalStdinTokenFields.get(source);
+    const targetPolicy = literalStdinTokenFields.get(target);
+    if (sourcePolicy === undefined ||
+        targetPolicy === ALL_MUTATION_STDIN_FIELDS) {
+        return target;
+    }
+    if (sourcePolicy === ALL_MUTATION_STDIN_FIELDS) {
+        literalStdinTokenFields.set(target, sourcePolicy);
+        return target;
+    }
+    literalStdinTokenFields.set(target, new Set([...(targetPolicy ?? []), ...sourcePolicy]));
+    return target;
+}
+/** Report whether lifecycle input should interpret dash values as stdin tokens. */
+export function shouldResolveMutationStdinTokens(options) {
+    return literalStdinTokenFields.get(options) !== ALL_MUTATION_STDIN_FIELDS;
+}
+/** Report whether one mutation field should interpret dash as a stdin token. */
+export function shouldResolveMutationStdinTokenField(options, field) {
+    const literalFields = literalStdinTokenFields.get(options);
+    return (literalFields !== ALL_MUTATION_STDIN_FIELDS && !literalFields?.has(field));
+}
+/** Refuse competing stdin-token fields before any resolver starts reading. */
+export function assertSingleStdinTokenConsumer(candidates) {
+    let stdinConsumerOption;
+    for (const candidate of candidates) {
+        if (candidate.resolveToken === false || candidate.value === undefined) {
+            continue;
+        }
+        const values = Array.isArray(candidate.value)
+            ? candidate.value
+            : [candidate.value];
+        const tokenCount = values.filter((value) => value.trim() === STDIN_TOKEN).length;
+        if (tokenCount > 1) {
+            throw new PmCliError(`${candidate.optionName} accepts "${STDIN_TOKEN}" stdin token at most once per command invocation`, EXIT_CODE.USAGE);
+        }
+        if (tokenCount === 0)
+            continue;
+        if (stdinConsumerOption !== undefined &&
+            stdinConsumerOption !== candidate.optionName) {
+            throw new PmCliError(`Only one option may use "${STDIN_TOKEN}" stdin token per command invocation. Already used by ${stdinConsumerOption}.`, EXIT_CODE.USAGE);
+        }
+        stdinConsumerOption = candidate.optionName;
+    }
+}
+/** Resolve a typed mutation option bag only after its complete stdin plan is conflict-free. */
+export async function resolveMutationStdinTokenFields(options, scalarFields, listFields) {
+    const source = options;
+    const definitions = [...scalarFields, ...listFields];
+    assertSingleStdinTokenConsumer(definitions.map(([field, optionName]) => ({
+        value: source[field],
+        optionName,
+        resolveToken: shouldResolveMutationStdinTokenField(options, field),
+    })));
+    const stdinResolver = createStdinTokenResolver();
+    const resolved = { ...source };
+    for (const [field, optionName] of scalarFields) {
+        resolved[field] = await stdinResolver.resolveValue(source[field], optionName, shouldResolveMutationStdinTokenField(options, field));
+    }
+    for (const [field, optionName] of listFields) {
+        resolved[field] = await stdinResolver.resolveList(source[field], optionName, shouldResolveMutationStdinTokenField(options, field));
+    }
+    return preserveMutationStdinTokenLiterals(resolved);
+}
 /** Implements create stdin token resolver for the public runtime surface of this module. */
 export function createStdinTokenResolver() {
     let stdinValuePromise;
@@ -430,7 +519,9 @@ export function createStdinTokenResolver() {
         }
         return await stdinValuePromise;
     };
-    const resolveValue = async (value, optionName) => {
+    const resolveValue = async (value, optionName, resolveToken = true) => {
+        if (!resolveToken)
+            return value;
         if (value === undefined) {
             return undefined;
         }
@@ -439,7 +530,9 @@ export function createStdinTokenResolver() {
         }
         return await consumeStdin(optionName);
     };
-    const resolveList = async (values, optionName) => {
+    const resolveList = async (values, optionName, resolveToken = true) => {
+        if (!resolveToken)
+            return values;
         if (!values) {
             return undefined;
         }
@@ -486,4 +579,4 @@ export const _testOnly = {
     parseMarkdownKeyValueLines,
 };
 //# sourceMappingURL=parse.js.map
-//# debugId=d5003dd5-f208-5734-9711-dff935d8c851
+//# debugId=2252cfb9-37ea-57f1-b7ea-2b0c0f87ecb2

package/dist/mcp/server.d.ts

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
-import { readRequiredString, runAction } from "../sdk/runtime.js";
+import { readRequiredString, type PmActionInput } from "../sdk/runtime.js";
 interface JsonRpcRequest {
     jsonrpc?: string;
     id?: string | number | null;
     method?: string;
     params?: Record<string, unknown>;
 }
+declare function runMcpAction(args: PmActionInput): Promise<unknown>;
 declare function nearestDeclaredKey(unexpected: string, declared: string[]): string | undefined;
 declare function detectUnexpectedTopLevelKeys(toolName: string, args: Record<string, unknown>, toolDeclaredKeys?: Map<string, string[]>): string[];
 declare function collectMutationGuardWarnings(toolName: string, action: string | undefined, args: Record<string, unknown>): Promise<string[]>;
@@ -53,7 +54,7 @@ export declare const _testOnly: {
     readonly readScalarString: typeof import("../sdk/runtime-input.js").readRuntimeScalarString;
     readonly readScalarStringAllowBlank: typeof import("../sdk/runtime-input.js").readRuntimeScalarStringAllowBlank;
     readonly readStringArray: typeof import("../sdk/runtime-input.js").readRuntimeStringArray;
-    runAction: typeof runAction;
+    runAction: typeof runMcpAction;
     readonly updateManyOptionsFromFlat: typeof import("../sdk/runtime-input.js").updateManyOptionsFromFlat;
     readonly withAddNoteOption: typeof import("../sdk/runtime-input.js").withAddNoteOption;
     readonly withFilesDiscoveryOptions: typeof import("../sdk/runtime-input.js").withFilesDiscoveryOptions;

package/dist/mcp/server.js

@@ -5,7 +5,7 @@
  * Runs the MCP server adapter that exposes pm actions and contracts to external agents.
  */
 
-!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]="740314ae-4228-5187-a939-f438fea48415")}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]="8ce8addc-e47e-5bb9-8a94-0959a1a535e9")}catch(e){}}();
 import { realpathSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
@@ -18,11 +18,14 @@ import { NARROW_TOOL_ACTIONS, TOOLS } from "./tool-definitions.js";
 import { normalizeWorkspaceToolArguments, resolveMcpToolAccess, resolveMcpToolSurface, } from "./runtime-capabilities.js";
 import { PM_MCP_PROMPT_CONTRACTS, PM_MCP_RESOURCE_CONTRACTS, } from "../sdk/agent-capability-contracts.js";
 import { commitItemMutations } from "../sdk/item-transaction.js";
-import { isRuntimeRecord } from "../sdk/runtime-input.js";
+import { isRuntimeRecord, markMcpMutationTransportInput, } from "../sdk/runtime-input.js";
 import { attachOutputTokenAccounting } from "../sdk/output-token-accounting.js";
 import { createReproducibleProcessRunner, runWithReproducibleProcessEnvironment, } from "../sdk/reproducibility/process.js";
 import { parseAtomicMutationControls, resolveItemMutationDocument, } from "../sdk/structured-mutations.js";
 import { resolveAuthor, resolvePmRoot } from "../sdk/runtime-primitives.js";
+function runMcpAction(args) {
+    return runAction(markMcpMutationTransportInput(args));
+}
 const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
 function resolvePmPackageRoot() {
     return fileURLToPath(new URL("../..", import.meta.url));
@@ -97,7 +100,7 @@ function detectUnexpectedTopLevelKeys(toolName, args, toolDeclaredKeys = declare
     return warnings;
 }
 const HANDLERS = {
-    pm_run: (args) => runAction(args),
+    pm_run: (args) => runMcpAction(args),
     pm_mutate: async (args) => {
         const transactionId = readRequiredString(args, "transactionId");
         const controls = parseAtomicMutationControls(args);
@@ -138,7 +141,7 @@ const HANDLERS = {
     },
     ...Object.fromEntries(Object.entries(NARROW_TOOL_ACTIONS).map(([tool, action]) => [
         tool,
-        (args) => runAction({ ...args, action }),
+        (args) => runMcpAction({ ...args, action }),
     ])),
 };
 /** Resolve the pm action a tools/call invocation will dispatch, when knowable. */
@@ -353,10 +356,10 @@ async function readWorkspaceResource(uri, params) {
     }
     let value;
     if (uri === "pm://workspace/context") {
-        value = await runAction({ ...args, action: "context", limit: 10 });
+        value = await runMcpAction({ ...args, action: "context", limit: 10 });
     }
     else if (uri === "pm://workspace/claims") {
-        value = await runAction({
+        value = await runMcpAction({
             ...args,
             action: "list",
             status: "in_progress",
@@ -364,7 +367,11 @@ async function readWorkspaceResource(uri, params) {
         });
     }
     else if (uri === "pm://workspace/focus") {
-        value = await runAction({ ...args, action: "focus", subcommand: "show" });
+        value = await runMcpAction({
+            ...args,
+            action: "focus",
+            subcommand: "show",
+        });
     }
     else {
         const guidePath = path.join(cwd, "AGENTS.md");
@@ -621,7 +628,7 @@ export const _testOnly = {
     get readStringArray() {
         return readRuntimeTestHook("readStringArray");
     },
-    runAction,
+    runAction: runMcpAction,
     get updateManyOptionsFromFlat() {
         return readRuntimeTestHook("updateManyOptionsFromFlat");
     },
@@ -642,4 +649,4 @@ if (isInvokedAsMcpMainModule(process.argv[1], import.meta.url)) {
 }
 /* c8 ignore stop */
 //# sourceMappingURL=server.js.map
-//# debugId=740314ae-4228-5187-a939-f438fea48415
+//# debugId=8ce8addc-e47e-5bb9-8a94-0959a1a535e9