@unbrained/pm-cli 2026.8.23 → 2026.8.25

package/dist/sdk/read-output/continuation.d.ts

@@ -1,6 +1,19 @@
 import type { PmReadOutputCursorEnvelope, PmReadOutputSurface } from "../read-output-contracts.js";
-/** Fingerprint the complete canonical row snapshot so changed evidence fails closed. */
-export declare function readOutputCollectionFingerprint(path: string, value: unknown[] | Record<string, unknown>): string;
+/** Stable snapshot policy for a read surface whose probes refresh observation metadata. */
+export interface PmReadOutputContinuationFingerprintPolicy {
+    /** Version included in fingerprints so policy changes invalidate older cursors. */
+    version: 3;
+    /** Declared continuation row paths governed by this policy. */
+    paths: readonly string[];
+    /** Exact direct detail fields excluded for each named dynamic row. */
+    ignored_detail_field_names_by_row: Readonly<Record<string, readonly string[]>>;
+    /** Promise that verdicts, stable configuration, and nonvolatile evidence remain bound. */
+    guarantee: "nonvolatile_snapshot_and_stable_configuration";
+}
+/** Command-specific exceptions to complete-row continuation fingerprinting. */
+export declare const PM_READ_OUTPUT_CONTINUATION_FINGERPRINT_POLICIES: Readonly<Partial<Record<PmReadOutputSurface, PmReadOutputContinuationFingerprintPolicy>>>;
+/** Fingerprint the policy-normalized row snapshot so stable evidence changes fail closed. */
+export declare function readOutputCollectionFingerprint(path: string, value: unknown[] | Record<string, unknown>, command?: PmReadOutputSurface): string;
 /** Encode one stable declared-row continuation for CLI, SDK, and MCP callers. */
 export declare function encodeReadOutputContinuationCursor(cursor: Omit<PmReadOutputCursorEnvelope, "version">): string;
 /** Decode and validate one universal declared-row continuation cursor. */

package/dist/sdk/read-output/continuation.js

@@ -6,7 +6,7 @@
  * resolution and budget policy.
  */
 
-!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]="1c73c31e-6246-5730-8c8a-d3ba7c9ec112")}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]="9e63b4b0-09a5-50bf-9f56-5f239c75ffe5")}catch(e){}}();
 import { createHash } from "node:crypto";
 import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
@@ -14,13 +14,93 @@ import { stableStringify } from "../../core/shared/serialization.js";
 import { resolveReadOutputSurface } from "../read-output-contracts.js";
 import { readOutputContinuationRowCollections, sliceReadOutputRowCollection, } from "../read-output-rows.js";
 const MAX_READ_OUTPUT_CURSOR_LENGTH = 4096;
+const HEALTH_TELEMETRY_VOLATILE_DETAIL_FIELDS = Object.freeze([
+    "queue_draining",
+    "queue_entries",
+    "queue_exists",
+    "queue_high_retry_entries",
+    "queue_invalid_rows",
+    "queue_max_attempts",
+    "queue_rows_total",
+    "queue_size_bytes",
+    "pending_otel_spans",
+    "last_attempted_flush_at",
+    "last_failed_flush_at",
+    "last_otel_attempt_at",
+    "last_otel_failure_at",
+    "last_otel_success_at",
+    "last_successful_flush_at",
+]);
+/** Command-specific exceptions to complete-row continuation fingerprinting. */
+export const PM_READ_OUTPUT_CONTINUATION_FINGERPRINT_POLICIES = Object.freeze({
+    health: Object.freeze({
+        version: 3,
+        paths: Object.freeze(["checks"]),
+        ignored_detail_field_names_by_row: Object.freeze({
+            telemetry: HEALTH_TELEMETRY_VOLATILE_DETAIL_FIELDS,
+        }),
+        guarantee: "nonvolatile_snapshot_and_stable_configuration",
+    }),
+});
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
-/** Fingerprint the complete canonical row snapshot so changed evidence fails closed. */
-export function readOutputCollectionFingerprint(path, value) {
+function normalizeReadOutputFingerprintValue(value) {
+    if (Array.isArray(value)) {
+        return value.map(normalizeReadOutputFingerprintValue);
+    }
+    if (!isRecord(value))
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [
+        key,
+        normalizeReadOutputFingerprintValue(entry),
+    ]));
+}
+function normalizeReadOutputFingerprintRow(value, policy) {
+    if (!isRecord(value))
+        return normalizeReadOutputFingerprintValue(value);
+    const rowName = typeof value.name === "string" ? value.name : undefined;
+    const ignoredDetailFields = rowName !== undefined &&
+        Object.hasOwn(policy.ignored_detail_field_names_by_row, rowName)
+        ? policy.ignored_detail_field_names_by_row[rowName]
+        : undefined;
+    return Object.fromEntries(Object.entries(value)
+        .map(([key, entry]) => {
+        if (key !== "details" || !ignoredDetailFields || !isRecord(entry)) {
+            return [key, normalizeReadOutputFingerprintValue(entry)];
+        }
+        return [
+            key,
+            Object.fromEntries(Object.entries(entry)
+                .filter(([detailKey]) => !ignoredDetailFields.includes(detailKey))
+                .map(([detailKey, detailValue]) => [
+                detailKey,
+                normalizeReadOutputFingerprintValue(detailValue),
+            ])),
+        ];
+    }));
+}
+function normalizeReadOutputFingerprintSnapshot(value, policy) {
+    return Array.isArray(value)
+        ? value.map((row) => normalizeReadOutputFingerprintRow(row, policy))
+        : normalizeReadOutputFingerprintRow(value, policy);
+}
+/** Fingerprint the policy-normalized row snapshot so stable evidence changes fail closed. */
+export function readOutputCollectionFingerprint(path, value, command) {
+    const policy = command
+        ? PM_READ_OUTPUT_CONTINUATION_FINGERPRINT_POLICIES[command]
+        : undefined;
+    const policyApplies = policy?.paths.includes(path) === true;
     return createHash("sha256")
-        .update(stableStringify({ path, value }))
+        .update(stableStringify({
+        path,
+        value: policyApplies
+            ? normalizeReadOutputFingerprintSnapshot(value, policy)
+            : value,
+        ...(policyApplies
+            ? { fingerprint_policy_version: policy.version }
+            : {}),
+    }))
         .digest("base64url")
         .slice(0, 16);
 }
@@ -105,11 +185,11 @@ export function applyReadOutputContinuation(result, command, cursor) {
     if (!collection ||
         totalRows !== cursor.total_rows ||
         cursor.offset > totalRows ||
-        readOutputCollectionFingerprint(cursor.path, collection.value) !==
+        readOutputCollectionFingerprint(cursor.path, collection.value, command) !==
             cursor.fingerprint) {
         throw new PmCliError("The read-output continuation no longer matches the declared row collection; restart the bounded read.", EXIT_CODE.USAGE, { code: "read_output_cursor_stale" });
     }
     return sliceReadOutputRowCollection(result, cursor.path, cursor.offset);
 }
 //# sourceMappingURL=continuation.js.map
-//# debugId=1c73c31e-6246-5730-8c8a-d3ba7c9ec112
+//# debugId=9e63b4b0-09a5-50bf-9f56-5f239c75ffe5

package/dist/sdk/read-output-contracts.d.ts

@@ -1,6 +1,7 @@
 export { resolveReadOutputRecoveryBudget } from "./read-output-budget.js";
 export type { PmReadOutputRecoveryBudget, PmReadOutputRecoveryBudgetInput, } from "./read-output-budget.js";
-export { decodeReadOutputContinuationCursor, encodeReadOutputContinuationCursor, } from "./read-output/continuation.js";
+export { decodeReadOutputContinuationCursor, encodeReadOutputContinuationCursor, PM_READ_OUTPUT_CONTINUATION_FINGERPRINT_POLICIES, readOutputCollectionFingerprint, } from "./read-output/continuation.js";
+export type { PmReadOutputContinuationFingerprintPolicy } from "./read-output/continuation.js";
 import { type PmReadOutputSessionReceipt, type PmReadOutputSessionState } from "./read-output-session.js";
 /** Stable output dimensions shared by every read surface. */
 export declare const PM_READ_OUTPUT_DIMENSIONS: readonly ["include", "amount", "cost", "encoding"];
@@ -61,6 +62,8 @@ export interface PmReadOutputSurfaceContract {
     precedence: readonly ["canonical", "legacy", "intent", "default"];
     /** Stable policy used before budget compaction selects retained rows. */
     budget_retention_policy: "ordered_prefix" | "verdict_priority";
+    /** Exact command-local whole-result modes accepted by `outputInclude`. */
+    projection_modes?: readonly string[];
 }
 /** Source that selected an effective output dimension. */
 export type PmReadOutputDimensionSource = "canonical" | "legacy" | "intent" | "default";

package/dist/sdk/read-output-contracts.js

@@ -5,7 +5,7 @@
  * surface without coupling package authors to command-specific option names.
  */
 
-!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]="76c9c2d0-951d-579e-916e-e8d54d4a8be9")}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]="d084da05-c967-58f1-afe4-069f09838e6f")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { compactReadOutputToBudget, estimateReadOutputTokens, resolveReadOutputRecoveryBudget, updateReadOutputReceiptEstimate, } from "./read-output-budget.js";
@@ -13,7 +13,7 @@ export { resolveReadOutputRecoveryBudget } from "./read-output-budget.js";
 import { resolvePmCommandOutputBudget } from "./cli-contracts/agent-output-contracts.js";
 import { boundReadOutputRows, countReadOutputRows, mapReadOutputRows, readOutputBudgetCollections, readOutputContinuationRowCollections, readOutputRowPaths, } from "./read-output-rows.js";
 import { applyReadOutputContinuation, decodeReadOutputContinuationCursor, encodeReadOutputContinuationCursor, prioritizeAssuranceAssertions, readOutputCollectionFingerprint, } from "./read-output/continuation.js";
-export { decodeReadOutputContinuationCursor, encodeReadOutputContinuationCursor, } from "./read-output/continuation.js";
+export { decodeReadOutputContinuationCursor, encodeReadOutputContinuationCursor, PM_READ_OUTPUT_CONTINUATION_FINGERPRINT_POLICIES, readOutputCollectionFingerprint, } from "./read-output/continuation.js";
 import { applyReadOutputSessionReferences, attachReadOutputSessionReceipt, parseReadOutputSession, readOutputSessionRemainingTokens, } from "./read-output-session.js";
 import { decodeQueryCursorEnvelope, encodeQueryCursor } from "./pagination.js";
 /** Stable output dimensions shared by every read surface. */
@@ -205,6 +205,9 @@ function buildSurfaceContract(command) {
         dimensions,
         precedence: READ_OUTPUT_PRECEDENCE,
         budget_retention_policy: command === "assurance" ? "verdict_priority" : "ordered_prefix",
+        projection_modes: Object.freeze([
+            ...readOutputIncludeModeOptions(command).keys(),
+        ]),
     });
 }
 /** Universal output contract for every built-in read surface. */
@@ -1092,7 +1095,7 @@ function rebaseBudgetCompactedCursor(projected, originalItemCount, cursorSource,
     }
     return true;
 }
-function captureReadOutputContinuationState(projected, cursor, options) {
+function captureReadOutputContinuationState(projected, command, cursor, options) {
     const collectionsBeforeBudget = new Map(readOutputContinuationRowCollections(projected).map((collection) => {
         const rows = Array.isArray(collection.value)
             ? collection.value.length
@@ -1106,7 +1109,7 @@ function captureReadOutputContinuationState(projected, cursor, options) {
                 baseOffset: continued ? cursor.offset : 0,
                 fingerprint: continued
                     ? cursor.fingerprint
-                    : readOutputCollectionFingerprint(collection.path, collection.value),
+                    : readOutputCollectionFingerprint(collection.path, collection.value, command),
             },
         ];
     }));
@@ -1154,7 +1157,7 @@ export function applyReadOutputDimensions(command, options, result) {
     const continuationReadyResult = attachValidateDiagnosticRowContract(resolved.command, result);
     const bindingBudget = resolveBindingReadOutputBudget(resolved, session);
     let projected = projectReadOutputRows(continuationReadyResult, resolved, session, cursor);
-    const continuationState = captureReadOutputContinuationState(projected, cursor, options);
+    const continuationState = captureReadOutputContinuationState(projected, resolved.command, cursor, options);
     const receipt = {
         contract_version: 1,
         command: resolved.command,
@@ -1207,4 +1210,4 @@ export function resolveReadOutputEncoding(command, options) {
         : undefined;
 }
 //# sourceMappingURL=read-output-contracts.js.map
-//# debugId=76c9c2d0-951d-579e-916e-e8d54d4a8be9
+//# debugId=d084da05-c967-58f1-afe4-069f09838e6f

package/dist/sdk/runtime-extended-actions.js

@@ -1,7 +1,8 @@
 
-!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]="0492d773-2af2-5072-8164-9f8aab536191")}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]="8a3a82a1-9e3d-555f-9111-3c3e19887f75")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
+import { transferMutationStdinTokenPolicy, } from "./runtime-primitives.js";
 import { createUnknownSubcommandError } from "./agent/subcommand-recovery.js";
 import { resolvePmRoot } from "../core/store/paths.js";
 import { runEval } from "./eval.js";
@@ -14,7 +15,8 @@ import { parseRuntimeInteger, readRuntimeString, readRuntimeStringArray, } from
 import { runEvent, runMeet, runRemind, } from "./scheduling-shortcuts.js";
 import { createWorkspaceSnapshot, deleteWorkspaceSnapshot, inspectWorkspaceSnapshot, listWorkspaceSnapshots, planWorkspaceSnapshotRestore, restoreWorkspaceSnapshotWithRecovery, } from "./workspace-snapshot.js";
 function mergedInput(context) {
-    return { ...context.args, ...context.options };
+    const input = { ...context.args, ...context.options };
+    return transferMutationStdinTokenPolicy(context.options, input);
 }
 function requiredString(input, key) {
     const value = readRuntimeString(input, key);
@@ -169,4 +171,4 @@ export function runRuntimeSchedulingAction(context) {
     return runRemind(title, input, context.global);
 }
 //# sourceMappingURL=runtime-extended-actions.js.map
-//# debugId=0492d773-2af2-5072-8164-9f8aab536191
+//# debugId=8a3a82a1-9e3d-555f-9111-3c3e19887f75

package/dist/sdk/runtime-input.d.ts

@@ -3,6 +3,10 @@ import type { CloseManyCommandOptions } from "./lifecycle/close-many.js";
 import type { UpdateManyCommandOptions } from "./lifecycle/update-many.js";
 import type { GraphCommandOptions } from "./graph/run.js";
 import type { ListOptions } from "./query/list.js";
+/** Mark an action object decoded from the MCP JSON-RPC transport. */
+export declare function markMcpMutationTransportInput<T extends object>(input: T): T;
+/** Clone mutation options with overrides while retaining stdin provenance. */
+export declare function mutationOptionsWithOverrides<Source extends object, Overrides extends object>(source: Source, overrides: Overrides, omittedKeys?: readonly PropertyKey[]): Source & Overrides;
 /** Read a non-empty string without altering its caller-provided whitespace. */
 export declare function readRuntimeString(args: Record<string, unknown>, key: string): string | undefined;
 /** Normalize a non-empty string or finite number into a scalar string. */

package/dist/sdk/runtime-input.js

@@ -5,12 +5,41 @@
  * primitives are shared by native action dispatchers and MCP-specific adapters.
  */
 
-!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]="0e153ece-4fc0-5134-97f0-c2315aff0031")}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]="2a1e986f-304d-50f6-a405-6afc221bdad5")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { asRecordClone } from "../core/shared/primitives.js";
 import { normalizeListOptions, normalizeUpdateOptions, } from "./cli-contracts/registration-helpers.js";
 import { UPDATE_COMMANDER_STRING_OPTION_CONTRACTS } from "./cli-contracts/commander-mutation-options.js";
+import { normalizeBulkIdsValue, } from "../core/io/bulk-ids-input.js";
+import { overlayMutationStdinTokenPolicy, preserveMutationStdinTokenLiterals, transferMutationStdinTokenPolicy, } from "../core/item/parse.js";
+const MCP_MUTATION_TRANSPORT = Symbol("pm.mcp-mutation-transport");
+/** Mark an action object decoded from the MCP JSON-RPC transport. */
+export function markMcpMutationTransportInput(input) {
+    Object.defineProperty(input, MCP_MUTATION_TRANSPORT, {
+        value: true,
+        enumerable: true,
+    });
+    return input;
+}
+function isMcpMutationTransportInput(input) {
+    return MCP_MUTATION_TRANSPORT in input;
+}
+function preserveTransportLiteralOptions(source, options) {
+    return isMcpMutationTransportInput(source)
+        ? preserveMutationStdinTokenLiterals(options)
+        : transferMutationStdinTokenPolicy(source, options);
+}
+/** Clone mutation options with overrides while retaining stdin provenance. */
+export function mutationOptionsWithOverrides(source, overrides, omittedKeys = []) {
+    const options = transferMutationStdinTokenPolicy(source, {
+        ...source,
+        ...overrides,
+    });
+    for (const key of omittedKeys)
+        Reflect.deleteProperty(options, key);
+    return options;
+}
 /** Read a non-empty string without altering its caller-provided whitespace. */
 export function readRuntimeString(args, key) {
     const value = args[key];
@@ -119,6 +148,7 @@ const SCALAR_TO_ARRAY_FIELDS = new Set([
     "envClear",
     "env_clear",
 ]);
+const ANNOTATION_SCALAR_TO_ARRAY_FIELDS = new Set([...SCALAR_TO_ARRAY_FIELDS].filter((field) => field !== "file"));
 // Actions where the linked-resource fields `add` and `remove` are string[] arrays.
 // For other actions (comments/notes/learnings) `add` and `remove` are scalar strings
 // and must NOT be auto-promoted.
@@ -129,6 +159,21 @@ const ARRAY_ADD_REMOVE_ACTIONS = new Set([
     "test",
     "test-all",
 ]);
+const SCALAR_ANNOTATION_SOURCE_ACTIONS = new Set([
+    "comments",
+    "notes",
+    "learnings",
+]);
+function assertMcpAnnotationFileUnavailable(action, options) {
+    if (!SCALAR_ANNOTATION_SOURCE_ACTIONS.has(action) ||
+        !Object.prototype.hasOwnProperty.call(options, "file")) {
+        return;
+    }
+    throw new PmCliError(`MCP ${action} does not accept options.file. Pass annotation text in options.add instead.`, EXIT_CODE.USAGE, {
+        code: "mcp_annotation_file_unavailable",
+        required: "Pass annotation text as JSON data; MCP annotation actions cannot read server-local files.",
+    });
+}
 /** Lifecycle actions where a top-level assignee argument aliases the author. */
 const LIFECYCLE_AUTHOR_ALIAS_ACTIONS = new Set([
     "claim",
@@ -171,10 +216,13 @@ const UNIVERSAL_READ_OUTPUT_OPTION_KEYS = [
     "outputCursor",
 ];
 /** Reconcile MCP array/scalar option spellings with CLI flag expectations. */
-export function normalizeMcpOptionsArrays(options, action) {
+export function normalizeMcpOptionsArrays(options, action = "") {
     const result = {};
-    const promoteAddRemove = action !== undefined && ARRAY_ADD_REMOVE_ACTIONS.has(action);
+    const promoteAddRemove = ARRAY_ADD_REMOVE_ACTIONS.has(action);
     const preserveStandaloneNote = action === "files" || action === "files-discover" || action === "docs";
+    const scalarToArrayFields = SCALAR_ANNOTATION_SOURCE_ACTIONS.has(action)
+        ? ANNOTATION_SCALAR_TO_ARRAY_FIELDS
+        : SCALAR_TO_ARRAY_FIELDS;
     for (const [key, value] of Object.entries(options)) {
         if (Array.isArray(value) && ARRAY_TO_CSV_FIELDS.has(key)) {
             result[key] = value.join(",");
@@ -184,7 +232,8 @@ export function normalizeMcpOptionsArrays(options, action) {
             result[key] = value;
             continue;
         }
-        if (typeof value === "string" && SCALAR_TO_ARRAY_FIELDS.has(key)) {
+        if (typeof value === "string" &&
+            scalarToArrayFields.has(key)) {
             result[key] = [value];
             continue;
         }
@@ -198,8 +247,28 @@ export function normalizeMcpOptionsArrays(options, action) {
     }
     return result;
 }
+/** Resolve the explicit or lifecycle-assignee author accepted by MCP actions. */
+function resolveMcpActionAuthor(args, options, action) {
+    const author = readRuntimeString(args, "author");
+    if (author !== undefined) {
+        return author;
+    }
+    return action !== undefined && LIFECYCLE_AUTHOR_ALIAS_ACTIONS.has(action)
+        ? (readRuntimeString(args, "assignee") ??
+            readRuntimeString(options, "assignee"))
+        : undefined;
+}
+/** Add a resolved author only when the normalized options do not provide one. */
+function withResolvedAuthor(options, author) {
+    return author !== undefined && options.author === undefined
+        ? { ...options, author }
+        : options;
+}
 /** Merge hoisted top-level action arguments and author aliases into options. */
 export function optionsWithAuthor(args, action) {
+    const sourceOptions = isRuntimeRecord(args.options)
+        ? args.options
+        : undefined;
     const baseOptions = asRecordClone(args.options);
     const hoistedTopLevel = {};
     const hoistKey = (key) => {
@@ -214,19 +283,14 @@ export function optionsWithAuthor(args, action) {
     for (const key of UNIVERSAL_READ_OUTPUT_OPTION_KEYS) {
         hoistKey(key);
     }
-    const options = normalizeMcpOptionsArrays({ ...hoistedTopLevel, ...baseOptions }, action);
-    const author = readRuntimeString(args, "author");
-    const authorFromAssignee = action !== undefined && LIFECYCLE_AUTHOR_ALIAS_ACTIONS.has(action)
-        ? (readRuntimeString(args, "assignee") ??
-            readRuntimeString(options, "assignee"))
-        : undefined;
-    if (author && options.author === undefined) {
-        return { ...options, author };
-    }
-    if (authorFromAssignee && options.author === undefined) {
-        return { ...options, author: authorFromAssignee };
+    if (action !== undefined && isMcpMutationTransportInput(args)) {
+        assertMcpAnnotationFileUnavailable(action, baseOptions);
     }
-    return options;
+    const options = normalizeMcpOptionsArrays({ ...hoistedTopLevel, ...baseOptions }, action);
+    const stdinPolicySource = isMcpMutationTransportInput(args)
+        ? args
+        : (sourceOptions ?? args);
+    return preserveTransportLiteralOptions(stdinPolicySource, withResolvedAuthor(options, resolveMcpActionAuthor(args, options, action)));
 }
 // GH-170 (pm-pfnx): the narrow pm_files/pm_docs tools spell the CLI --note flag
 // as `addNote` (the shared `note` parameter is the array-typed create/update
@@ -318,10 +382,13 @@ export function extensionOptionsFromArgs(args, options) {
 }
 /** Mutation tools (create/update/close/append/update-many) return a verbose `changed_fields` array. On the agent path we drop it to a `changed_field_count` by default for token efficiency, restoring the full array only when the caller explicitly passes the MCP-level fullChangedFields=true control. Mutation options are forwarded unchanged so runtime fields named `full` remain valid user data. */
 export function withMutationCompaction(args, options) {
+    const runnerOptions = preserveTransportLiteralOptions(options ?? {}, {
+        ...options,
+    });
     return {
         changedFields: args.fullChangedFields === true ? "full" : "compact",
         idOnly: args.idOnly === true,
-        runnerOptions: { ...options },
+        runnerOptions,
     };
 }
 /** Translate flat MCP filter parameters into the shared list-option shape. */
@@ -336,7 +403,7 @@ export function mutationListOptions(options) {
         updatedBefore: readRuntimeScalarString(options, "filterUpdatedBefore"),
         createdAfter: readRuntimeScalarString(options, "filterCreatedAfter"),
         createdBefore: readRuntimeScalarString(options, "filterCreatedBefore"),
-        ids: readRuntimeScalarStringAllowBlank(options, "ids"),
+        ids: normalizeBulkIdsValue(options.ids),
         assignee: readRuntimeScalarString(options, "filterAssignee"),
         assigneeFilter: readRuntimeScalarString(options, "filterAssigneeFilter") ??
             readRuntimeScalarString(options, "filterAssignee_filter"),
@@ -385,12 +452,19 @@ export function graphOptionsFromFlat(options) {
         ...(options.full === true ? { full: true } : {}),
     };
 }
+function normalizeBulkMutationListOptions(options) {
+    const normalized = normalizeListOptions(options);
+    if (options.ids !== undefined) {
+        normalized.ids = normalizeBulkIdsValue(options.ids);
+    }
+    return normalized;
+}
 /** Build close-many command options from one flat MCP parameter payload. */
 export function closeManyOptionsFromFlat(options) {
     return {
         status: readRuntimeString(options, "filterStatus"),
         list: isRuntimeRecord(options.list)
-            ? normalizeListOptions(options.list)
+            ? normalizeBulkMutationListOptions(options.list)
             : mutationListOptions(options),
         reason: readRuntimeString(options, "reason"),
         resolution: readRuntimeString(options, "resolution"),
@@ -474,12 +548,13 @@ export function updateManyOptionsFromFlat(options) {
         const updateSource = isRuntimeRecord(options.update)
             ? options.update
             : updateManyUpdateOptionsFromFlat(options);
+        const normalizedUpdate = preserveTransportLiteralOptions(options, normalizeMcpUpdateOptions(updateSource));
         return {
             status: readRuntimeScalarString(options, "filterStatus"),
             list: isRuntimeRecord(options.list)
-                ? normalizeListOptions(options.list)
+                ? normalizeBulkMutationListOptions(options.list)
                 : mutationListOptions(options),
-            update: normalizeMcpUpdateOptions(updateSource),
+            update: overlayMutationStdinTokenPolicy(updateSource, normalizedUpdate),
             dryRun: options.dryRun === true || options.dry_run === true ? true : undefined,
             rollback: readRuntimeString(options, "rollback"),
             checkpoint: options.checkpoint === false ||
@@ -492,7 +567,7 @@ export function updateManyOptionsFromFlat(options) {
     return {
         status: readRuntimeScalarString(options, "filterStatus"),
         list: mutationListOptions(options),
-        update: updateManyUpdateOptionsFromFlat(options),
+        update: preserveTransportLiteralOptions(options, updateManyUpdateOptionsFromFlat(options)),
         dryRun: options.dryRun === true || options.dry_run === true ? true : undefined,
         rollback: readRuntimeString(options, "rollback"),
         checkpoint: options.checkpoint === false ||
@@ -503,4 +578,4 @@ export function updateManyOptionsFromFlat(options) {
     };
 }
 //# sourceMappingURL=runtime-input.js.map
-//# debugId=0e153ece-4fc0-5134-97f0-c2315aff0031
+//# debugId=2a1e986f-304d-50f6-a405-6afc221bdad5

package/dist/sdk/runtime-primitives.d.ts

@@ -14,6 +14,7 @@ export { applyRegisteredItemFieldDefaultsAndValidation, collectRegisteredItemFie
 export { resolveExtensionRoots } from "../core/extensions/loader.js";
 export { resolveRegisteredSearchProvider, resolveRegisteredVectorStoreAdapter, } from "../core/extensions/runtime-registrations.js";
 export { pathExists, readFileIfExists, removeFileIfExists, writeFileAtomic, } from "../core/fs/fs-utils.js";
+export { normalizeBulkIdsValue, parseBulkIdsText, resolveCliBulkIdsInput, type BulkIdsFileReader, type BulkIdsInputReaders, type BulkIdsStdinReader, type BulkIdsValue, } from "../core/io/bulk-ids-input.js";
 export { type HistoryDiffValueEntry, computeHistoryDiff, patchPathToChangedField, } from "../core/history/history-diff.js";
 export { enforceHistoryStreamPolicyForItem, enforceHistoryStreamPolicyForItems, } from "../core/history/history-stream-policy.js";
 export { appendHistoryEntry, CURRENT_HISTORY_ITEM_HASH_VERSION, createHistoryEntry, hashDocument, hashDocumentForVersion, hashEmptyDocument, SUPPORTED_HISTORY_ITEM_HASH_VERSIONS, type HistoryItemHashVersion, } from "../core/history/history.js";
@@ -25,7 +26,7 @@ export { generateItemId, normalizeItemId, normalizeRawItemId, } from "../core/it
 export { canonicalDocument, normalizeItemMetadata, parseItemDocument, serializeItemDocument, } from "../core/item/item-format.js";
 export { toItemRecord } from "../core/item/item-record.js";
 export { assertParentReferenceIsNotSelf, isPlaceholderReferenceToken, normalizeParentReferenceValue, validateMissingParentReference, } from "../core/item/parent-reference-policy.js";
-export { applyAcceptanceCriteriaMutations, applyTagRemovals, assertNoUnknownCsvKeys, createStdinTokenResolver, looksLikeGenericKeyValueEntry, mergeAdditiveTags, parseCsvKv, parseOptionalNonNegativeInteger, parseOptionalNumber, parseTags, splitAcceptanceCriteria, } from "../core/item/parse.js";
+export { applyAcceptanceCriteriaMutations, applyTagRemovals, assertNoUnknownCsvKeys, createStdinTokenResolver, looksLikeGenericKeyValueEntry, mergeAdditiveTags, parseCsvKv, parseOptionalNonNegativeInteger, parseOptionalNumber, parseTags, preserveMutationStdinTokenFields, preserveMutationStdinTokenLiterals, transferMutationStdinTokenPolicy, shouldResolveMutationStdinTokenField, shouldResolveMutationStdinTokens, splitAcceptanceCriteria, } from "../core/item/parse.js";
 export { resolvePriority } from "../core/item/priority.js";
 export { validateSprintOrReleaseValue } from "../core/item/sprint-release-format.js";
 export { parseStatusFilterCsv } from "../core/item/status-filter.js";

package/dist/sdk/runtime-primitives.js

@@ -7,7 +7,7 @@
  * prefer the typed operations exported by the main SDK barrel.
  */
 
-!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]="472ea74c-138f-584f-b363-e76e100e124c")}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]="be6f7869-f197-5d38-b8d9-faf8f390cd56")}catch(e){}}();
 export { createCheckpointId, loadMutationCheckpoint, restoreCheckpointItems, writeMutationCheckpoint, } from "../core/checkpoint/mutation-checkpoint.js";
 export { flattenFlagListValue, resolveFlagValueKind, } from "../core/extensions/flag-value-types.js";
 export { createUnknownSubcommandError, } from "./agent/subcommand-recovery.js";
@@ -16,6 +16,7 @@ export { applyRegisteredItemFieldDefaultsAndValidation, collectRegisteredItemFie
 export { resolveExtensionRoots } from "../core/extensions/loader.js";
 export { resolveRegisteredSearchProvider, resolveRegisteredVectorStoreAdapter, } from "../core/extensions/runtime-registrations.js";
 export { pathExists, readFileIfExists, removeFileIfExists, writeFileAtomic, } from "../core/fs/fs-utils.js";
+export { normalizeBulkIdsValue, parseBulkIdsText, resolveCliBulkIdsInput, } from "../core/io/bulk-ids-input.js";
 export { computeHistoryDiff, patchPathToChangedField, } from "../core/history/history-diff.js";
 export { enforceHistoryStreamPolicyForItem, enforceHistoryStreamPolicyForItems, } from "../core/history/history-stream-policy.js";
 export { appendHistoryEntry, CURRENT_HISTORY_ITEM_HASH_VERSION, createHistoryEntry, hashDocument, hashDocumentForVersion, hashEmptyDocument, SUPPORTED_HISTORY_ITEM_HASH_VERSIONS, } from "../core/history/history.js";
@@ -27,7 +28,7 @@ export { generateItemId, normalizeItemId, normalizeRawItemId, } from "../core/it
 export { canonicalDocument, normalizeItemMetadata, parseItemDocument, serializeItemDocument, } from "../core/item/item-format.js";
 export { toItemRecord } from "../core/item/item-record.js";
 export { assertParentReferenceIsNotSelf, isPlaceholderReferenceToken, normalizeParentReferenceValue, validateMissingParentReference, } from "../core/item/parent-reference-policy.js";
-export { applyAcceptanceCriteriaMutations, applyTagRemovals, assertNoUnknownCsvKeys, createStdinTokenResolver, looksLikeGenericKeyValueEntry, mergeAdditiveTags, parseCsvKv, parseOptionalNonNegativeInteger, parseOptionalNumber, parseTags, splitAcceptanceCriteria, } from "../core/item/parse.js";
+export { applyAcceptanceCriteriaMutations, applyTagRemovals, assertNoUnknownCsvKeys, createStdinTokenResolver, looksLikeGenericKeyValueEntry, mergeAdditiveTags, parseCsvKv, parseOptionalNonNegativeInteger, parseOptionalNumber, parseTags, preserveMutationStdinTokenFields, preserveMutationStdinTokenLiterals, transferMutationStdinTokenPolicy, shouldResolveMutationStdinTokenField, shouldResolveMutationStdinTokens, splitAcceptanceCriteria, } from "../core/item/parse.js";
 export { resolvePriority } from "../core/item/priority.js";
 export { validateSprintOrReleaseValue } from "../core/item/sprint-release-format.js";
 export { parseStatusFilterCsv } from "../core/item/status-filter.js";
@@ -81,4 +82,4 @@ export { maybeRunFirstUseTelemetryPrompt } from "../core/telemetry/consent.js";
 export { deriveTelemetryCommandResolution, } from "../core/telemetry/observability.js";
 export { emitTelemetryErrorEvent, finishTelemetryCommand, startTelemetryCommand, } from "../core/telemetry/runtime.js";
 //# sourceMappingURL=runtime-primitives.js.map
-//# debugId=472ea74c-138f-584f-b363-e76e100e124c
+//# debugId=be6f7869-f197-5d38-b8d9-faf8f390cd56

package/dist/sdk/runtime.js

@@ -4,7 +4,7 @@
  * Defines public SDK APIs and package-author helpers for Runtime.
  */
 
-!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]="600f391a-c960-5dda-a85a-04d3fa8b1a51")}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]="72111aa2-52b2-53da-a1c8-07ba53a74944")}catch(e){}}();
 export { PM_GITIGNORE_END, PM_GITIGNORE_START, ensurePmGitignore, getPmGitignoreBlock, } from "./workspace.js";
 export { SEARCH_EXTENSION_FLAG_DEFINITIONS } from "./extension-contracts.js";
 export * from "./cli-contracts/agent-output-contracts.js";
@@ -72,7 +72,7 @@ import { PROFILE_SUBCOMMANDS, runProfileApply, runProfileLint, runProfileList, r
 import { runHistoryRedact, } from "./history-redact.js";
 import { runMcpHistoryCompactAction, runMcpHistoryRepairAction, } from "./history-mcp.js";
 import { runMcpCloseAction, runMcpReopenAction } from "./lifecycle/mcp-actions.js";
-import { actionGlobalOptions as globalOptions, closeManyOptionsFromFlat, extensionOptionsFromArgs, graphOptionsFromFlat, mutationListOptions, normalizeActionName, normalizeCommandPath, normalizeMcpOptionsArrays, normalizeMcpUpdateOptions, optionsWithAuthor, parseRuntimeInteger as parseMcpInteger, readRuntimeScalarString as readScalarString, readRuntimeScalarStringAllowBlank as readScalarStringAllowBlank, readRuntimeString as readString, readRuntimeStringArray as readStringArray, resolveRuntimeLimit, updateManyOptionsFromFlat, withAddNoteOption, withFilesDiscoveryOptions, withMutationCompaction, } from "./runtime-input.js";
+import { actionGlobalOptions as globalOptions, closeManyOptionsFromFlat, extensionOptionsFromArgs, graphOptionsFromFlat, mutationListOptions, mutationOptionsWithOverrides, normalizeActionName, normalizeCommandPath, normalizeMcpOptionsArrays, normalizeMcpUpdateOptions, optionsWithAuthor, parseRuntimeInteger as parseMcpInteger, readRuntimeScalarString as readScalarString, readRuntimeScalarStringAllowBlank as readScalarStringAllowBlank, readRuntimeString as readString, readRuntimeStringArray as readStringArray, resolveRuntimeLimit, updateManyOptionsFromFlat, withAddNoteOption, withFilesDiscoveryOptions, withMutationCompaction, } from "./runtime-input.js";
 import { runDeps } from "./dependencies.js";
 import { runDocs } from "./docs.js";
 import { runGraph, } from "./graph/run.js";
@@ -252,7 +252,7 @@ export class PmClient {
     append(id, body, options = {}) {
         return this.runTyped("append", {
             id,
-            ...splitFullClientMutationOptions({ ...options, body }),
+            ...splitFullClientMutationOptions(mutationOptionsWithOverrides(options, { body })),
         });
     }
     /** Initialize a workspace with the same semantics as `pm init`. */
@@ -461,7 +461,7 @@ export class PmClient {
             ...(id === undefined ? {} : { id }),
             ...(stepRef === undefined ? {} : { stepRef }),
             ...(reorderTo === undefined ? {} : { reorderTo }),
-            options: { ...options, subcommand },
+            options: mutationOptionsWithOverrides(options, { subcommand }),
         });
     }
     /** Create a durable plan with optional ordered seed steps. */
@@ -1718,22 +1718,13 @@ async function runMcpRestoreAction(ctx) {
         idOnly,
     });
 }
-function withoutLifecycleAssigneeAlias(options) {
-    const updateOptions = { ...options };
-    delete updateOptions.assignee;
-    return updateOptions;
-}
 async function runMcpStartTaskAction(ctx) {
     const pmRoot = resolvePmRoot(process.cwd(), ctx.global.path);
     const settings = await readSettings(pmRoot);
     const inProgressStatus = resolveStartTaskInProgressStatus(resolveRuntimeStatusRegistry(settings.schema));
     const id = requireMcpItemId(ctx);
     const claimResult = await runClaim(id, ctx.force, ctx.global, ctx.options);
-    const updateResult = await runUpdate(id, {
-        ...withoutLifecycleAssigneeAlias(ctx.options),
-        status: inProgressStatus,
-        force: ctx.force,
-    }, ctx.global);
+    const updateResult = await runUpdate(id, mutationOptionsWithOverrides(ctx.options, { status: inProgressStatus, force: ctx.force }, ["assignee"]), ctx.global);
     return { id, action: "start_task", claim: claimResult, update: updateResult };
 }
 async function runMcpPauseTaskAction(ctx) {
@@ -1741,11 +1732,7 @@ async function runMcpPauseTaskAction(ctx) {
     const settings = await readSettings(pmRoot);
     const id = requireMcpItemId(ctx);
     const openStatus = resolveRuntimeStatusRegistry(settings.schema).open_status;
-    const updateResult = await runUpdate(id, {
-        ...withoutLifecycleAssigneeAlias(ctx.options),
-        status: openStatus,
-        force: ctx.force,
-    }, ctx.global);
+    const updateResult = await runUpdate(id, mutationOptionsWithOverrides(ctx.options, { status: openStatus, force: ctx.force }, ["assignee"]), ctx.global);
     const releaseResult = await runRelease(id, ctx.force, ctx.global, ctx.options);
     return {
         id,
@@ -1946,4 +1933,4 @@ async function loadWorkspaceExtensionRegistrations(pmRoot, settings, cwd) {
     }
 }
 //# sourceMappingURL=runtime.js.map
-//# debugId=600f391a-c960-5dda-a85a-04d3fa8b1a51
+//# debugId=72111aa2-52b2-53da-a1c8-07ba53a74944