@unbrained/pm-cli 2026.8.21 → 2026.8.23

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

@@ -5,10 +5,11 @@
  * 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]="b3c001df-9891-5cf7-990b-8d9da7b51801")}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]="76c9c2d0-951d-579e-916e-e8d54d4a8be9")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
-import { compactReadOutputToBudget, estimateReadOutputTokens, updateReadOutputReceiptEstimate, } from "./read-output-budget.js";
+import { compactReadOutputToBudget, estimateReadOutputTokens, resolveReadOutputRecoveryBudget, updateReadOutputReceiptEstimate, } from "./read-output-budget.js";
+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";
@@ -43,6 +44,7 @@ export const PM_READ_OUTPUT_SURFACES = [
     "docs",
     "stats",
     "aggregate",
+    "duplicates",
     "package-catalog",
     "package-manage",
     "comments-audit",
@@ -60,6 +62,7 @@ const CANONICAL_OPTIONS = {
     cost: "--output-budget",
     encoding: "--output-format",
 };
+const READ_OUTPUT_INVOCATION_PROVENANCE = Symbol.for("pm.readOutputInvocationProvenance");
 /** Canonical CLI flags that opt a read invocation into universal output shaping. */
 export const PM_READ_OUTPUT_OPTION_FLAGS = Object.freeze(PM_READ_OUTPUT_DIMENSIONS.map((dimension) => CANONICAL_OPTIONS[dimension]));
 /** Canonical control that composes the four per-call dimensions across reads. */
@@ -136,6 +139,7 @@ const LEGACY_FLAGS_BY_COMMAND = {
     docs: {},
     stats: {},
     aggregate: {},
+    duplicates: { amount: ["--limit"] },
     "package-catalog": {},
     "package-manage": {},
     "comments-audit": {},
@@ -363,14 +367,32 @@ export function applyReadOutputIncludeModes(command, includeValue, commandOption
     const modeOptions = readOutputIncludeModeOptions(command);
     const selectors = [];
     const modes = [];
+    const optionsWithProvenance = commandOptions;
+    const existingProvenance = optionsWithProvenance[READ_OUTPUT_INVOCATION_PROVENANCE];
+    const canonicalModes = new Set(existingProvenance?.canonical_include_modes ?? []);
+    const explicitLegacyAliases = new Set(existingProvenance?.explicit_legacy_aliases ?? []);
     for (const token of requested) {
         const option = modeOptions.get(token);
         if (option === undefined) {
             selectors.push(token);
             continue;
         }
+        const legacyFlag = `--${token.replaceAll("_", "-")}`;
+        if (isRequestedOption(readOption(commandOptions, legacyFlag))) {
+            explicitLegacyAliases.add(legacyFlag);
+        }
         commandOptions[option] = true;
         modes.push(token);
+        canonicalModes.add(token);
+    }
+    if (modes.length > 0) {
+        optionsWithProvenance[READ_OUTPUT_INVOCATION_PROVENANCE] = {
+            canonical_include_modes: [...canonicalModes],
+            explicit_legacy_aliases: [...explicitLegacyAliases],
+            ...(existingProvenance?.cli_invocation_observed === true
+                ? { cli_invocation_observed: true }
+                : {}),
+        };
     }
     return { selectors, modes };
 }
@@ -430,8 +452,10 @@ function positiveInteger(value) {
             : Number.NaN;
     return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined;
 }
-function resolveLegacyDimension(contract, options, usable) {
+function resolveLegacyDimension(contract, options, usable, ignore) {
     for (const alias of contract.legacy_aliases) {
+        if (ignore(alias.flag))
+            continue;
         const value = readOption(options, alias.flag);
         const candidate = { value, flag: alias.flag };
         if (isRequestedOption(value) && usable(candidate))
@@ -496,12 +520,43 @@ function resolveEncodingValue(canonical, legacy) {
         ? { source: "legacy", value: legacy.value }
         : undefined;
 }
+function shouldIgnoreReadOutputLegacyAlias(provenance, dimension, flag) {
+    if (!provenance)
+        return false;
+    const explicitLegacyAliases = new Set(provenance.explicit_legacy_aliases);
+    if (provenance.cli_invocation_observed === true) {
+        return !explicitLegacyAliases.has(flag);
+    }
+    const forwardedIncludeAliases = new Set(provenance.canonical_include_modes.map((mode) => `--${mode.replaceAll("_", "-")}`));
+    return (dimension === "include" &&
+        forwardedIncludeAliases.has(flag) &&
+        !explicitLegacyAliases.has(flag));
+}
+function hasCompleteReadOutputIntent(command, legacyByDimension, provenance) {
+    const root = command
+        .trim()
+        .toLowerCase()
+        .replaceAll(/\s+/gu, " ")
+        .split(" ")[0];
+    return (root === "list-all" ||
+        legacyByDimension.amount?.flag === "--no-truncate" ||
+        legacyByDimension.include?.flag === "--full" ||
+        provenance?.canonical_include_modes.includes("full") === true);
+}
+function canonicalReadOutputOptionsUsed(resolvedByDimension, provenance) {
+    return PM_READ_OUTPUT_DIMENSIONS.flatMap((dimension) => resolvedByDimension[dimension]?.source === "canonical" ||
+        (dimension === "include" &&
+            (provenance?.canonical_include_modes.length ?? 0) > 0)
+        ? [CANONICAL_OPTIONS[dimension]]
+        : []);
+}
 /** Resolve canonical and compatibility controls into the universal dimension set. */
 export function resolveReadOutputDimensions(command, options) {
     const normalizedCommand = resolveReadOutputSurface(command, options);
     if (!normalizedCommand)
         return undefined;
     const contract = SURFACE_CONTRACT_BY_COMMAND.get(normalizedCommand);
+    const invocationProvenance = options[READ_OUTPUT_INVOCATION_PROVENANCE];
     const legacyResolvers = {
         include: (candidate) => resolveIncludeValue(undefined, candidate),
         amount: (candidate) => resolveAmountValue(undefined, candidate),
@@ -510,7 +565,7 @@ export function resolveReadOutputDimensions(command, options) {
     };
     const legacyByDimension = Object.fromEntries(PM_READ_OUTPUT_DIMENSIONS.map((dimension) => [
         dimension,
-        resolveLegacyDimension(contract.dimensions[dimension], options, (candidate) => legacyResolvers[dimension](candidate) !== undefined),
+        resolveLegacyDimension(contract.dimensions[dimension], options, (candidate) => legacyResolvers[dimension](candidate) !== undefined, (flag) => shouldIgnoreReadOutputLegacyAlias(invocationProvenance, dimension, flag)),
     ]));
     const legacyAliasesUsed = PM_READ_OUTPUT_DIMENSIONS.flatMap((dimension) => {
         const resolved = legacyByDimension[dimension];
@@ -524,29 +579,31 @@ export function resolveReadOutputDimensions(command, options) {
         return [alias.migration_hint];
     });
     const encoding = resolveEncodingValue(options.outputFormat ?? options.output_format, legacyByDimension.encoding);
+    const include = resolveIncludeValue(options.outputInclude ?? options.output_include, legacyByDimension.include);
+    const amount = resolveAmountValue(options.outputLimit ?? options.output_limit, legacyByDimension.amount);
     const explicitCost = resolveCostValue(options.outputBudget ?? options.output_budget, legacyByDimension.cost);
-    const completeResultIntent = command.trim().toLowerCase().replaceAll(/\s+/gu, " ").split(" ")[0] ===
-        "list-all" ||
-        legacyByDimension.amount?.flag === "--no-truncate" ||
-        legacyByDimension.include?.flag === "--full";
+    const completeResultIntent = hasCompleteReadOutputIntent(command, legacyByDimension, invocationProvenance);
     const budget = resolvePmCommandOutputBudget(command, {
         generateFallback: true,
     });
     const resolvedOutputFormat = encoding?.value === "json" || options.resolvedOutputFormat === "json"
         ? "json"
         : "toon";
+    const cost = explicitCost ??
+        (completeResultIntent
+            ? { source: "intent", value: "unbounded" }
+            : {
+                source: "default",
+                value: budget.default_max_estimated_tokens_by_format[resolvedOutputFormat],
+            });
+    const resolvedByDimension = { include, amount, cost, encoding };
     return {
         command: normalizedCommand,
-        include: resolveIncludeValue(options.outputInclude ?? options.output_include, legacyByDimension.include),
-        amount: resolveAmountValue(options.outputLimit ?? options.output_limit, legacyByDimension.amount),
-        cost: explicitCost ??
-            (completeResultIntent
-                ? { source: "intent", value: "unbounded" }
-                : {
-                    source: "default",
-                    value: budget.default_max_estimated_tokens_by_format[resolvedOutputFormat],
-                }),
+        include,
+        amount,
+        cost,
         encoding,
+        canonical_options_used: canonicalReadOutputOptionsUsed(resolvedByDimension, invocationProvenance),
         legacy_aliases_used: legacyAliasesUsed,
         migration_hints: migrationHints,
         precedence: READ_OUTPUT_PRECEDENCE,
@@ -732,8 +789,9 @@ function applyAmountBound(result, amount) {
     return bounded;
 }
 function requestedDimensions(resolved) {
-    return PM_READ_OUTPUT_DIMENSIONS.filter((dimension) => resolved[dimension] !== undefined &&
-        resolved[dimension]?.source !== "default");
+    return PM_READ_OUTPUT_DIMENSIONS.filter((dimension) => (resolved[dimension] !== undefined &&
+        resolved[dimension]?.source !== "default") ||
+        resolved.canonical_options_used.includes(CANONICAL_OPTIONS[dimension]));
 }
 /** Stabilize the per-call and cross-call receipts in one complete envelope. */
 function attachReadOutputSessionContracts(result, state, receipt) {
@@ -847,6 +905,12 @@ function resolveBindingReadOutputBudget(resolved, session) {
     ];
     return budgets.sort((left, right) => left.tokens - right.tokens)[0];
 }
+function canonicalReadOutputReceiptFields(resolved) {
+    const canonicalOptions = resolved.canonical_options_used;
+    return canonicalOptions && canonicalOptions.length > 0
+        ? { canonical_options_used: canonicalOptions }
+        : {};
+}
 /** Build the smallest truthful omission envelope or reject an exhausted session. */
 function omitReadOutputForBudget(resolved, requested, session, bindingBudget, omittedResultEstimatedTokens) {
     const minimalReceipt = {
@@ -860,6 +924,7 @@ function omitReadOutputForBudget(resolved, requested, session, bindingBudget, om
             }
             : {}),
         precedence: resolved.precedence,
+        ...canonicalReadOutputReceiptFields(resolved),
         legacy_aliases_used: [],
         migration_hints: [],
         estimated_tokens: 0,
@@ -893,10 +958,10 @@ function omitReadOutputForBudget(resolved, requested, session, bindingBudget, om
     return boundedOmission;
 }
 /** Decide whether shaping would add no value to an already-bounded result. */
-function canReturnReadOutputUnchanged(resolved, requested, session, result) {
+function canReturnReadOutputUnchanged(resolved, session, result) {
     if (session !== undefined)
         return false;
-    const canonicalRequestedCount = requested.filter((dimension) => resolved[dimension]?.source === "canonical").length;
+    const canonicalRequestedCount = resolved.canonical_options_used.length;
     if (resolved.cost?.value === "unbounded") {
         return (canonicalRequestedCount === (resolved.cost.source === "canonical" ? 1 : 0));
     }
@@ -915,7 +980,7 @@ function canReturnReadOutputUnchanged(resolved, requested, session, result) {
  * without this an explicitly requested unbounded read is silently downgraded and
  * the only working recovery is never named.
  */
-function attachReadOutputTruncationDisclosure(projected, resolved, receipt, bindingBudget, continuationCursorRebased, collectionsBeforeBudget) {
+function attachReadOutputTruncationDisclosure(projected, resolved, receipt, bindingBudget, continuationCursorRebased, measuredResultTokens, collectionsBeforeBudget) {
     if (!receipt.rows_compacted)
         return;
     const overridden = resolved.amount?.value === "unbounded" ? ["amount"] : [];
@@ -949,6 +1014,10 @@ function attachReadOutputTruncationDisclosure(projected, resolved, receipt, bind
         ];
     });
     const primary = continuations[0];
+    const recoveryBudget = resolveReadOutputRecoveryBudget({
+        effective_budget_tokens: bindingBudget.tokens,
+        measured_result_tokens: measuredResultTokens,
+    });
     if (primary && typeof projected.next_cursor !== "string") {
         projected.next_cursor = primary.cursor;
     }
@@ -965,11 +1034,13 @@ function attachReadOutputTruncationDisclosure(projected, resolved, receipt, bind
         compacted_row_paths: receipt.compacted_row_paths,
         continuation_cursor_rebased: continuationCursorRebased,
         continuation_available: continuations.length > 0,
-        recovery_budget_multiplier: 1,
+        recovery_budget_multiplier: primary
+            ? 1
+            : recoveryBudget.recovery_budget_multiplier,
         continuations,
         restore_with: primary
             ? "Use recovery binding."
-            : "Increase --output-budget because no declared row collection can be continued.",
+            : `Retry with --output-budget ${recoveryBudget.output_budget} because no declared row collection can be continued.`,
         recovery: primary
             ? {
                 cursor: primary.cursor,
@@ -978,9 +1049,9 @@ function attachReadOutputTruncationDisclosure(projected, resolved, receipt, bind
                 mcp: "outputCursor",
             }
             : {
-                cli: "--output-budget 1200",
-                sdk: { outputBudget: 1200 },
-                mcp: { outputBudget: 1200 },
+                cli: `--output-budget ${recoveryBudget.output_budget}`,
+                sdk: { outputBudget: recoveryBudget.output_budget },
+                mcp: { outputBudget: recoveryBudget.output_budget },
             },
     };
 }
@@ -1051,7 +1122,7 @@ function captureReadOutputContinuationState(projected, cursor, options) {
             : options.after,
     };
 }
-function compactReadOutputProjection(projected, resolved, receipt, bindingBudget, session, continuationState) {
+function compactReadOutputProjection(projected, resolved, receipt, bindingBudget, session, continuationState, measuredResultTokens) {
     const assuranceMinimumRows = resolved.command === "assurance" && Array.isArray(projected.assertions)
         ? projected.assertions.filter((row) => isRecord(row) && row.verdict !== "pass").length
         : 0;
@@ -1059,7 +1130,7 @@ function compactReadOutputProjection(projected, resolved, receipt, bindingBudget
         ? new Map([["assertions", assuranceMinimumRows]])
         : new Map());
     const continuationCursorRebased = rebaseBudgetCompactedCursor(compacted, continuationState.originalItemCount, continuationState.cursorSource, continuationState.cursorContinuesExistingPage);
-    attachReadOutputTruncationDisclosure(compacted, resolved, receipt, bindingBudget, continuationCursorRebased, continuationState.collectionsBeforeBudget);
+    attachReadOutputTruncationDisclosure(compacted, resolved, receipt, bindingBudget, continuationCursorRebased, measuredResultTokens, continuationState.collectionsBeforeBudget);
     if (session !== undefined) {
         compacted = attachReadOutputSessionContracts(compacted, session, receipt);
     }
@@ -1077,7 +1148,7 @@ export function applyReadOutputDimensions(command, options, result) {
         : undefined;
     const requested = requestedDimensions(resolved);
     if (cursor === undefined &&
-        canReturnReadOutputUnchanged(resolved, requested, session, result)) {
+        canReturnReadOutputUnchanged(resolved, session, result)) {
         return result;
     }
     const continuationReadyResult = attachValidateDiagnosticRowContract(resolved.command, result);
@@ -1095,6 +1166,7 @@ export function applyReadOutputDimensions(command, options, result) {
             }
             : {}),
         precedence: resolved.precedence,
+        ...canonicalReadOutputReceiptFields(resolved),
         legacy_aliases_used: resolved.legacy_aliases_used,
         migration_hints: resolved.migration_hints,
         estimated_tokens: 0,
@@ -1111,7 +1183,8 @@ export function applyReadOutputDimensions(command, options, result) {
     updateReadOutputReceiptEstimate(projected, receipt);
     if (bindingBudget !== undefined &&
         receipt.estimated_tokens > bindingBudget.tokens) {
-        projected = compactReadOutputProjection(projected, resolved, receipt, bindingBudget, session, continuationState);
+        const measuredResultTokens = receipt.estimated_tokens;
+        projected = compactReadOutputProjection(projected, resolved, receipt, bindingBudget, session, continuationState, measuredResultTokens);
     }
     if (bindingBudget !== undefined &&
         receipt.estimated_tokens > bindingBudget.tokens) {
@@ -1134,4 +1207,4 @@ export function resolveReadOutputEncoding(command, options) {
         : undefined;
 }
 //# sourceMappingURL=read-output-contracts.js.map
-//# debugId=b3c001df-9891-5cf7-990b-8d9da7b51801
+//# debugId=76c9c2d0-951d-579e-916e-e8d54d4a8be9

package/dist/sdk/relationship-context.js

@@ -5,7 +5,7 @@
  * packet for agents, custom tools, and presentation-layer 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]="31a800f7-1374-5e7c-ad23-ae3d8ebcebe0")}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]="afdba960-ae43-52be-b21d-282dac1f22ff")}catch(e){}}();
 import { createQueryFingerprint, encodeQueryCursor, resolveQueryCursorStart, } from "./pagination.js";
 import { createRelationshipKindRegistry, } from "./relationships.js";
 /** Deterministic priority used when one node matches several semantic families. */
@@ -37,8 +37,7 @@ function explainDirectEdge(edge, node, registry) {
         return node === before ? "prerequisite" : "dependent";
     }
     if (definition?.hierarchy) {
-        // Legacy and JSON-parsed definitions may predate explicit hierarchy direction.
-        const sourceIsParent = (definition.hierarchyDirection ?? "source_parent") === "source_parent";
+        const sourceIsParent = definition.hierarchyDirection === "source_parent";
         const parent = sourceIsParent ? edge.source : edge.target;
         return node === parent ? "ancestor" : "descendant";
     }
@@ -283,4 +282,4 @@ export function buildRelationshipContext(graph, rootId, details, options = {}) {
     };
 }
 //# sourceMappingURL=relationship-context.js.map
-//# debugId=31a800f7-1374-5e7c-ad23-ae3d8ebcebe0
+//# debugId=afdba960-ae43-52be-b21d-282dac1f22ff

package/dist/sdk/relationships.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="b1c32b57-0231-5bea-ade4-99247504f938")}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]="d7d44fba-603b-5ef2-8490-51112b929433")}catch(e){}}();
 import { BUILTIN_RELATIONSHIP_KINDS, } from "./relationship-kinds/contract.js";
 export { BUILTIN_RELATIONSHIP_KINDS, } from "./relationship-kinds/contract.js";
 function normalizeKind(kind) {
@@ -105,6 +105,17 @@ function assertRelationshipKindPayload(definition, kind) {
             definition.aliases.some((alias) => typeof alias !== "string")))
         throw new TypeError(`Invalid relationship aliases for ${kind}`);
 }
+function resolveRelationshipTraversal(definition) {
+    if (definition.traversal)
+        return definition.traversal;
+    // Dual-family extension kinds use ordering precedence, matching relationship
+    // context role classification. Explicit traversal always remains authoritative.
+    if (definition.ordering)
+        return "ordering";
+    if (definition.hierarchy)
+        return "hierarchy";
+    return definition.direction === "undirected" ? "association" : "semantic";
+}
 /** Mutable registry with immutable snapshots and collision-safe extension registration. */
 export class RelationshipKindRegistry {
     #definitions = new Map();
@@ -139,15 +150,11 @@ export class RelationshipKindRegistry {
         const normalized = Object.freeze({
             ...definition,
             kind,
-            traversal: definition.traversal ??
-                (definition.hierarchy
-                    ? "hierarchy"
-                    : definition.ordering
-                        ? "ordering"
-                        : definition.direction === "undirected"
-                            ? "association"
-                            : "semantic"),
+            traversal: resolveRelationshipTraversal(definition),
             hierarchy: definition.hierarchy ?? false,
+            hierarchyDirection: definition.hierarchy
+                ? (definition.hierarchyDirection ?? "source_parent")
+                : undefined,
             inverse,
             aliases: Object.freeze(aliases),
             payloadSchema: definition.payloadSchema
@@ -570,4 +577,4 @@ export function dependencyToRelationship(source, dependency, registry = defaultR
     };
 }
 //# sourceMappingURL=relationships.js.map
-//# debugId=b1c32b57-0231-5bea-ade4-99247504f938
+//# debugId=d7d44fba-603b-5ef2-8490-51112b929433

package/dist/sdk/reproducibility/process.d.ts

@@ -0,0 +1,19 @@
+import { type ReproducibleExecutionSettings, type ReproducibleExecutionRunner } from "../../core/reproducibility/context.js";
+/** Stable environment-variable names understood by every pm process transport. */
+export declare const PM_REPRODUCIBLE_PROCESS_ENV: Readonly<{
+    readonly clock: "PM_CLOCK";
+    readonly tickMs: "PM_CLOCK_TICK_MS";
+    readonly seed: "PM_SEED";
+}>;
+/** Environment-shaped input accepted by the reproducible process adapter. */
+export type ReproducibleProcessEnvironment = Readonly<Record<string, string | undefined>>;
+/** Public deterministic settings installed by recipes and process transports. */
+export type { ReproducibleExecutionSettings };
+/** Runner used by long-lived transports whose serial operations share one sequence. */
+export type ReproducibleProcessRunner = ReproducibleExecutionRunner;
+/** Resolve validated deterministic settings, or undefined when no opt-in is present. */
+export declare function resolveReproducibleProcessEnvironment(environment: ReproducibleProcessEnvironment): ReproducibleExecutionSettings | undefined;
+/** Create one process-lifetime runner for long-lived serial transports such as MCP. */
+export declare function createReproducibleProcessRunner(environment: ReproducibleProcessEnvironment): ReproducibleProcessRunner;
+/** Run one process transport operation under its declared deterministic context. */
+export declare function runWithReproducibleProcessEnvironment<T>(environment: ReproducibleProcessEnvironment, operation: () => Promise<T>): Promise<T>;

package/dist/sdk/reproducibility/process.js

@@ -0,0 +1,88 @@
+/**
+ * @module sdk/reproducible-process
+ *
+ * Owns the process-environment contract that lets CLI and MCP transports enter
+ * the same deterministic execution context as SDK workspace recipes.
+ */
+
+!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]="ae031bac-f5a1-5762-9c58-0410b8f1f86d")}catch(e){}}();
+import { EXIT_CODE } from "../../core/shared/constants.js";
+import { PmCliError } from "../../core/shared/errors.js";
+import { isRfc3339DateTime } from "../../core/shared/time.js";
+import { createReproducibleExecutionRunner, validateReproducibleExecutionSettings, } from "../../core/reproducibility/context.js";
+/** Stable environment-variable names understood by every pm process transport. */
+export const PM_REPRODUCIBLE_PROCESS_ENV = Object.freeze({
+    clock: "PM_CLOCK",
+    tickMs: "PM_CLOCK_TICK_MS",
+    seed: "PM_SEED",
+});
+function invalidProcessEnvironment(message, reason, field, providedFields) {
+    return new PmCliError(message, EXIT_CODE.USAGE, {
+        code: "invalid_reproducible_process_environment",
+        reason,
+        field,
+        required: `${PM_REPRODUCIBLE_PROCESS_ENV.clock} and ${PM_REPRODUCIBLE_PROCESS_ENV.seed}; ${PM_REPRODUCIBLE_PROCESS_ENV.tickMs} is optional`,
+        nextSteps: [
+            `Set ${PM_REPRODUCIBLE_PROCESS_ENV.clock} to an ISO-8601 instant with Z or a numeric UTC offset and ${PM_REPRODUCIBLE_PROCESS_ENV.seed} to a non-empty reproducibility seed.`,
+            `Optionally set ${PM_REPRODUCIBLE_PROCESS_ENV.tickMs} to a non-negative integer; it defaults to 1.`,
+            `Unset all three variables to retain normal wall-clock and cryptographic-random behavior.`,
+        ],
+        recovery: {
+            recovery_mode: "compact",
+            provided_fields: providedFields,
+            missing_required_fields: reason === "incomplete"
+                ? [
+                    PM_REPRODUCIBLE_PROCESS_ENV.clock,
+                    PM_REPRODUCIBLE_PROCESS_ENV.seed,
+                ].filter((name) => !providedFields.includes(name))
+                : undefined,
+        },
+    });
+}
+/** Resolve validated deterministic settings, or undefined when no opt-in is present. */
+export function resolveReproducibleProcessEnvironment(environment) {
+    const clock = environment[PM_REPRODUCIBLE_PROCESS_ENV.clock];
+    const tick = environment[PM_REPRODUCIBLE_PROCESS_ENV.tickMs];
+    const seed = environment[PM_REPRODUCIBLE_PROCESS_ENV.seed];
+    const providedFields = [
+        [PM_REPRODUCIBLE_PROCESS_ENV.clock, clock],
+        [PM_REPRODUCIBLE_PROCESS_ENV.tickMs, tick],
+        [PM_REPRODUCIBLE_PROCESS_ENV.seed, seed],
+    ]
+        .filter((entry) => entry[1] !== undefined)
+        .map(([name]) => name);
+    if (providedFields.length === 0) {
+        return undefined;
+    }
+    if (clock === undefined || seed === undefined) {
+        throw invalidProcessEnvironment("Reproducible process execution requires PM_CLOCK and PM_SEED together.", "incomplete", clock === undefined
+            ? PM_REPRODUCIBLE_PROCESS_ENV.clock
+            : PM_REPRODUCIBLE_PROCESS_ENV.seed, providedFields);
+    }
+    if (seed.trim().length === 0) {
+        throw invalidProcessEnvironment(`${PM_REPRODUCIBLE_PROCESS_ENV.seed} must not be empty.`, "invalid_value", PM_REPRODUCIBLE_PROCESS_ENV.seed, providedFields);
+    }
+    if (!isRfc3339DateTime(clock)) {
+        throw invalidProcessEnvironment(`${PM_REPRODUCIBLE_PROCESS_ENV.clock} must be a valid ISO-8601 instant with Z or a numeric UTC offset.`, "invalid_value", PM_REPRODUCIBLE_PROCESS_ENV.clock, providedFields);
+    }
+    const tickMs = tick === undefined ? 1 : Number(tick);
+    if (tick?.trim().length === 0 ||
+        !Number.isSafeInteger(tickMs) ||
+        tickMs < 0) {
+        throw invalidProcessEnvironment(`${PM_REPRODUCIBLE_PROCESS_ENV.tickMs} must be a non-negative integer.`, "invalid_value", PM_REPRODUCIBLE_PROCESS_ENV.tickMs, providedFields);
+    }
+    return validateReproducibleExecutionSettings({ clock, seed, tickMs });
+}
+/** Create one process-lifetime runner for long-lived serial transports such as MCP. */
+export function createReproducibleProcessRunner(environment) {
+    const settings = resolveReproducibleProcessEnvironment(environment);
+    return settings === undefined
+        ? (operation) => operation()
+        : createReproducibleExecutionRunner(settings);
+}
+/** Run one process transport operation under its declared deterministic context. */
+export async function runWithReproducibleProcessEnvironment(environment, operation) {
+    return createReproducibleProcessRunner(environment)(operation);
+}
+//# sourceMappingURL=process.js.map
+//# debugId=ae031bac-f5a1-5762-9c58-0410b8f1f86d

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

@@ -53,7 +53,7 @@ export { type VectorizationEmbeddingIdentity, type VectorizationEmbeddingMetadat
 export { sentryCaptureCliError, sentryFinishCommandSpan, sentryFlush, sentryLogCliUsageError, sentrySetCommandContext, sentryStartCommandSpan, } from "../core/sentry/helpers.js";
 export { ensureSentryInit } from "../core/sentry/instrument.js";
 export { clearFocusedItem, getFocusedItem, setFocusedItem, } from "../core/session/session-state.js";
-export { readAuthorEnvironment, diagnoseAgentIdentity, resolveAuthor, resolveClaimPrincipal, runWithHarnessDetectionSignals, runWithWorkspaceHarnessSignalDescriptors, type AgentClientInfo, writeAuthorEnvironment, } from "../core/shared/author.js";
+export { readAuthorEnvironment, diagnoseAgentIdentity, resolveAuthor, resolveClaimPrincipal, runWithHarnessDetectionSignals, runWithWorkspaceHarnessSignalDescriptors, BUILTIN_AGENT_PROVENANCE_ADAPTERS, listAgentProvenanceAdapters, normalizeAgentProvenanceAdapterValue, registerAgentProvenanceAdapters, type AgentProvenanceAdapter, type AgentClientInfo, writeAuthorEnvironment, } from "../core/shared/author.js";
 export { agentSessionEnvironment, boundAgentEpisodeIdentity, runWithAgentSessionContext, resolveAgentSessionContextFromSignals, type AgentEpisodeIdentity, type AgentSessionContext, } from "../core/shared/agent-session-context.js";
 export { evaluateMutationGuard, isMutationAction, listMutationActions, scanMutationSecrets, type EvaluateMutationGuardOptions, type MutationGuardResult, type MutationGuardSettings, type SecretGuardFinding, type SecretGuardMode, } from "./mutation-guard.js";
 export { jaccardSimilarity, normalizeSimilarityText, scoreItemSimilarity, tokenizeSimilarityText, type ItemSimilarityScore, } from "./similarity-scoring.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]="1bcfba24-e761-571c-96e6-36bbc12d2814")}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]="472ea74c-138f-584f-b363-e76e100e124c")}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";
@@ -55,7 +55,7 @@ export { buildVectorizationEmbeddingIdentity, buildVectorizationEmbeddingMetadat
 export { sentryCaptureCliError, sentryFinishCommandSpan, sentryFlush, sentryLogCliUsageError, sentrySetCommandContext, sentryStartCommandSpan, } from "../core/sentry/helpers.js";
 export { ensureSentryInit } from "../core/sentry/instrument.js";
 export { clearFocusedItem, getFocusedItem, setFocusedItem, } from "../core/session/session-state.js";
-export { readAuthorEnvironment, diagnoseAgentIdentity, resolveAuthor, resolveClaimPrincipal, runWithHarnessDetectionSignals, runWithWorkspaceHarnessSignalDescriptors, writeAuthorEnvironment, } from "../core/shared/author.js";
+export { readAuthorEnvironment, diagnoseAgentIdentity, resolveAuthor, resolveClaimPrincipal, runWithHarnessDetectionSignals, runWithWorkspaceHarnessSignalDescriptors, BUILTIN_AGENT_PROVENANCE_ADAPTERS, listAgentProvenanceAdapters, normalizeAgentProvenanceAdapterValue, registerAgentProvenanceAdapters, writeAuthorEnvironment, } from "../core/shared/author.js";
 export { agentSessionEnvironment, boundAgentEpisodeIdentity, runWithAgentSessionContext, resolveAgentSessionContextFromSignals, } from "../core/shared/agent-session-context.js";
 export { evaluateMutationGuard, isMutationAction, listMutationActions, scanMutationSecrets, } from "./mutation-guard.js";
 export { jaccardSimilarity, normalizeSimilarityText, scoreItemSimilarity, tokenizeSimilarityText, } from "./similarity-scoring.js";
@@ -81,4 +81,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=1bcfba24-e761-571c-96e6-36bbc12d2814
+//# debugId=472ea74c-138f-584f-b363-e76e100e124c

package/dist/sdk/runtime.d.ts

@@ -6,6 +6,7 @@
 export { PM_GITIGNORE_END, PM_GITIGNORE_START, ensurePmGitignore, getPmGitignoreBlock, type EnsurePmGitignoreResult, } from "./workspace.js";
 export { SEARCH_EXTENSION_FLAG_DEFINITIONS } from "./extension-contracts.js";
 export type { FlagDefinition } from "../core/extensions/loader.js";
+export * from "./cli-contracts/agent-output-contracts.js";
 import { EXIT_CODE } from "../core/shared/constants.js";
 import type { ItemMetadata } from "../types/index.js";
 import { type PmCompleteListOptions, type PmCompleteListResult } from "./query/complete-list.js";
@@ -155,7 +156,7 @@ export declare class PmClient {
     /** Return project tracker statistics with the same sections as `pm stats`. */
     stats<Options extends ReadOptions<StatsCommandOptions> = StatsCommandOptions>(options?: Options): ReadPromise<StatsResult, Options>;
     /** Discover existing duplicate clusters without mutating tracker state. */
-    duplicates(options?: DuplicatesCommandOptions): Promise<DuplicatesResult>;
+    duplicates<Options extends ReadOptions<DuplicatesCommandOptions> = DuplicatesCommandOptions>(options?: Options): ReadPromise<DuplicatesResult, Options>;
     /** List, add, edit, or delete item comments. */
     comments<Options extends ReadOptions<CommentsCommandOptions> = CommentsCommandOptions>(id: string, options?: Options): ReadPromise<CommentsResult, Options>;
     /** List or append private item notes. */
@@ -371,7 +372,7 @@ export declare function aggregate<Options extends ReadOptions<AggregateOptions>
 /** Return project tracker statistics with the same sections as `pm stats` without constructing a reusable client. */
 export declare function stats<Options extends ReadOptions<StatsCommandOptions> = StatsCommandOptions>(options?: Options, clientOptions?: PmClientOptions): ReadPromise<StatsResult, Options>;
 /** Discover duplicate clusters without constructing a reusable client. */
-export declare function duplicates(options?: DuplicatesCommandOptions, clientOptions?: PmClientOptions): Promise<DuplicatesResult>;
+export declare function duplicates<Options extends ReadOptions<DuplicatesCommandOptions> = DuplicatesCommandOptions>(options?: Options, clientOptions?: PmClientOptions): ReadPromise<DuplicatesResult, Options>;
 /** List, add, edit, or delete item comments without constructing a reusable client. */
 export declare function comments<Options extends ReadOptions<CommentsCommandOptions> = CommentsCommandOptions>(id: string, options?: Options, clientOptions?: PmClientOptions): ReadPromise<CommentsResult, Options>;
 /** List or append private item notes without constructing a reusable client. */

package/dist/sdk/runtime.js

@@ -4,9 +4,10 @@
  * 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]="c770afea-3eb6-5476-ba07-8ec1c5d9c699")}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]="600f391a-c960-5dda-a85a-04d3fa8b1a51")}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";
 import { AsyncLocalStorage } from "node:async_hooks";
 import path from "node:path";
 import { createEmptyExtensionCommandRegistry, createEmptyExtensionHookRegistry, createEmptyExtensionParserRegistry, createEmptyExtensionPreflightRegistry, createEmptyExtensionRegistrationRegistry, createEmptyExtensionRendererRegistry, createEmptyExtensionServiceRegistry, } from "../core/extensions/extension-registries.js";
@@ -1456,12 +1457,13 @@ function runMcpConfigAction(ctx) {
     const configAction = readString(ctx.args, "configAction") ??
         readString(ctx.options, "configAction") ??
         readString(ctx.options, "action");
-    if (configAction === undefined) {
+    if (configAction === undefined)
         throw new PmCliError("Missing required argument: configAction", 64);
-    }
+    const value = readString(ctx.args, "value") ?? readString(ctx.options, "value");
+    const options = readString(ctx.options, "policy") !== undefined && value !== undefined ? { ...ctx.options, value } : ctx.options;
     return runConfig(readString(ctx.args, "scope") ??
         readString(ctx.options, "scope") ??
-        "project", configAction, readString(ctx.args, "key") ?? readString(ctx.options, "key"), ctx.options, ctx.global, readString(ctx.args, "value") ?? readString(ctx.options, "value"));
+        "project", configAction, readString(ctx.args, "key") ?? readString(ctx.options, "key"), options, ctx.global, readString(ctx.options, "policy") === undefined ? value : undefined);
 }
 function runMcpActivityAction(ctx) {
     const options = ctx.options;
@@ -1944,4 +1946,4 @@ async function loadWorkspaceExtensionRegistrations(pmRoot, settings, cwd) {
     }
 }
 //# sourceMappingURL=runtime.js.map
-//# debugId=c770afea-3eb6-5476-ba07-8ec1c5d9c699
+//# debugId=600f391a-c960-5dda-a85a-04d3fa8b1a51

package/dist/sdk/test/batch.d.ts

@@ -25,6 +25,12 @@ export interface TestAllCommandOptions {
     pmContext?: string;
     /** Value that configures or reports override linked pm context for this contract. */
     overrideLinkedPmContext?: boolean;
+    /** Source-workspace visibility and working-directory mode. */
+    workspaceContext?: string;
+    /** Force run-level source-workspace mode over linked metadata. */
+    overrideLinkedWorkspaceContext?: boolean;
+    /** Explicitly permit untrusted commands when project policy also permits them. */
+    allowUntrustedLinkedTests?: boolean;
     /** Value that configures or reports fail on context mismatch for this contract. */
     failOnContextMismatch?: boolean;
     /** Value that configures or reports fail on skipped for this contract. */