@unbrained/pm-cli 2026.8.9 → 2026.8.11

package/dist/sdk/governance/health.js

@@ -4,7 +4,7 @@
  * Implements the pm health command surface and its agent-facing runtime behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="97e1ed14-cd36-5910-b829-4619af6080e1")}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]="539b0cb4-5e20-51e2-a33e-1a43ca961f05")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { resolveItemTypeRegistry } from "../../core/item/type-registry.js";
@@ -28,7 +28,7 @@ import { toNonEmptyStringOrUndefined } from "../../core/shared/primitives.js";
 import { nowIso } from "../../core/shared/time.js";
 import { parseItemDocument } from "../../core/item/item-format.js";
 import { effectiveItemFormatVersion, scanItemFormatVersions, } from "../../core/item/item-format-version.js";
-import { listAllItemMetadata, listAllItemMetadataWithBody, } from "../../core/store/item-store.js";
+import { listAllItemMetadataLight, listAllItemMetadataWithBody, } from "../../core/store/item-store.js";
 import { PM_TELEMETRY_SOURCE_CONTEXT_VALUES, TELEMETRY_MAX_QUEUE_ENTRY_ATTEMPTS, TELEMETRY_SCHEMA_VERSION, } from "../../core/telemetry/runtime.js";
 import { getItemFormatFromPath, getSettingsPath, ITEM_FILE_EXTENSIONS, resolveGlobalPmRoot, resolvePmRoot, } from "../../core/store/paths.js";
 import { readSettingsWithMetadata } from "../../core/store/settings.js";
@@ -322,7 +322,10 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDri
         : await auditMergeDriverConfiguration(gitWorkspaceRoot);
     const pendingMergeReceipts = gitWorkspaceRoot === null
         ? []
-        : await listMergeReceipts(gitWorkspaceRoot, { includeLossless: true });
+        : await listMergeReceipts(gitWorkspaceRoot, {
+            includeLossless: true,
+            pmRoot,
+        });
     const { pendingDecisions: pendingMergeDecisions, lossless: losslessMergeReceipts, } = partitionMergeReceipts(pendingMergeReceipts);
     const mergeDriverInstallationMissing = mergeDriverAudit?.status === "missing" &&
         mergeDriverAudit.missing_keys.length === 5 &&
@@ -1652,7 +1655,7 @@ function resolveHealthSkipPolicy(options) {
 }
 async function readHealthItems(params) {
     if (params.skipPolicy.skipDrift && params.skipPolicy.skipVectors) {
-        return listAllItemMetadata(params.pmRoot, params.settings.item_format, params.typeRegistry.type_to_folder, params.itemReadWarnings, params.settings.schema);
+        return listAllItemMetadataLight(params.pmRoot, params.settings.item_format, params.typeRegistry.type_to_folder, params.itemReadWarnings, params.settings.schema);
     }
     return listAllItemMetadataWithBody(params.pmRoot, params.settings.item_format, params.typeRegistry.type_to_folder, params.itemReadWarnings, params.settings.schema);
 }
@@ -1702,7 +1705,7 @@ const resolveUnknownAuthorEventCount = (authorAttribution) => authorAttribution.
 /** Preserve actionable-author semantics for current and legacy scan payloads. */
 const resolveActionableUnknownAuthorEventCount = (authorAttribution) => authorAttribution.actionable_unknown_event_count ??
     resolveUnknownAuthorEventCount(authorAttribution);
-function buildStorageHealthCheck(items, settings, historySummary, authorAttribution, staleInProgress, provenanceResolverOutcomes) {
+function buildStorageHealthCheck(items, settings, historySummary, authorAttribution, staleInProgress, provenanceResolverOutcomes, provenanceInvalidValues) {
     const unknownAuthorEventCount = resolveUnknownAuthorEventCount(authorAttribution);
     const actionableUnknownAuthorEventCount = resolveActionableUnknownAuthorEventCount(authorAttribution);
     const hasAuthorEvents = unknownAuthorEventCount > 0;
@@ -1738,6 +1741,9 @@ function buildStorageHealthCheck(items, settings, historySummary, authorAttribut
             ...(provenanceResolverOutcomes.length > 0
                 ? { provenance_resolver_outcomes: provenanceResolverOutcomes }
                 : {}),
+            ...(provenanceInvalidValues.length > 0
+                ? { provenance_invalid_values: provenanceInvalidValues }
+                : {}),
             ...(historySummary.max_entries !== null
                 ? {
                     compact_policy: {
@@ -1881,6 +1887,7 @@ export async function runHealth(global, options = {}) {
     }));
     const provenanceResolverHealth = await scanProvenanceResolverHealth(pmRoot);
     const provenanceResolverOutcomes = provenanceResolverHealth.outcomes;
+    const provenanceInvalidValues = provenanceResolverHealth.invalid_values;
     const provenanceWarnings = provenanceResolverHealth.warnings;
     const locksCheck = await buildLocksCheck(pmRoot);
     const integrityCheck = skipPolicy.skipIntegrity
@@ -1898,7 +1905,7 @@ export async function runHealth(global, options = {}) {
         buildSettingsValuesHealthCheck(settingWarnings),
         telemetryCheck.check,
         extensionCheck.check,
-        buildStorageHealthCheck(items, settings, historySummary, authorAttribution, staleInProgress.scan, provenanceResolverOutcomes),
+        buildStorageHealthCheck(items, settings, historySummary, authorAttribution, staleInProgress.scan, provenanceResolverOutcomes, provenanceInvalidValues),
         locksCheck.check,
         integrityCheck.check,
         historyDriftCheck.check,
@@ -1983,4 +1990,4 @@ export const _testOnlyHealthCommand = {
     warningCode,
 };
 //# sourceMappingURL=health.js.map
-//# debugId=97e1ed14-cd36-5910-b829-4619af6080e1
+//# debugId=539b0cb4-5e20-51e2-a33e-1a43ca961f05

package/dist/sdk/governance/provenance-health.d.ts

@@ -11,10 +11,23 @@ export interface ProvenanceResolverHealthOutcome {
     /** Attempted events that produced a bounded value. */
     successes: number;
 }
+/** Aggregate for legacy provenance values that violate the bounded domain. */
+export interface ProvenanceValueHealthFinding {
+    /** Detected harness namespace. */
+    harness: string;
+    /** Provenance dimension containing the invalid value. */
+    dimension: string;
+    /** Privacy-safe invalid-value class. */
+    kind: "boolean" | "single_digit";
+    /** Events containing this invalid value class. */
+    count: number;
+}
 /** Bounded provenance health result suitable for `pm health` adapters. */
 export interface ProvenanceResolverHealthScan {
     /** Stable resolver outcome aggregates. */
     outcomes: ProvenanceResolverHealthOutcome[];
+    /** Aggregated invalid legacy values without retaining the values themselves. */
+    invalid_values: ProvenanceValueHealthFinding[];
     /** Advisory warnings for attempted resolvers with no success. */
     warnings: string[];
     /** Number of nonblank history events inspected. */

package/dist/sdk/governance/provenance-health.js

@@ -4,10 +4,26 @@
  * Reads bounded, privacy-safe provenance resolver outcomes for health checks.
  */
 
-!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]="68d4d540-a878-57f1-b2ae-00b111f94b43")}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]="60154e1b-8348-5b6b-badf-e76bba43bef8")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 const DEFAULT_PROVENANCE_HISTORY_BYTE_LIMIT = 8_388_608;
+const ATTEMPTED_PROVENANCE_OUTCOME_STATUSES = new Set(["resolved", "failed"]);
+const INVALID_PROVENANCE_VALUE_CLASSIFIERS = [
+    {
+        kind: "boolean",
+        matches: (value) => typeof value === "boolean" ||
+            (typeof value === "string" && /^(?:true|false)$/iu.test(value.trim())),
+    },
+    {
+        kind: "single_digit",
+        matches: (value) => (typeof value === "number" &&
+            Number.isInteger(value) &&
+            value >= 0 &&
+            value <= 9) ||
+            (typeof value === "string" && /^\d$/u.test(value.trim())),
+    },
+];
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -58,22 +74,44 @@ function parseHistoryEntry(line) {
         return null;
     }
 }
-function collectResolverOutcomes(entry, aggregates) {
+function collectResolverOutcomes(entry, aggregates, invalidValues) {
+    const harness = typeof entry.agent_harness === "string" ? entry.agent_harness : undefined;
+    if (harness === undefined)
+        return;
+    const provenance = isRecord(entry.agent_provenance)
+        ? entry.agent_provenance
+        : {};
+    Object.entries(provenance).forEach(([dimension, observation]) => {
+        if (!isRecord(observation))
+            return;
+        const kind = INVALID_PROVENANCE_VALUE_CLASSIFIERS.find((classifier) => classifier.matches(observation.value))?.kind;
+        if (!kind)
+            return;
+        const key = `${harness}\0${dimension}\0${kind}`;
+        const aggregate = invalidValues.get(key) ?? {
+            harness,
+            dimension,
+            kind,
+            count: 0,
+        };
+        aggregate.count += 1;
+        invalidValues.set(key, aggregate);
+    });
     if (!isRecord(entry.context))
         return;
     const outcomes = entry.context.agent_provenance_outcomes;
-    if (!isRecord(outcomes) || typeof entry.agent_harness !== "string")
+    if (!isRecord(outcomes))
         return;
-    for (const [dimension, rawOutcome] of Object.entries(outcomes)) {
+    Object.entries(outcomes).forEach(([dimension, rawOutcome]) => {
         if (!isRecord(rawOutcome) || typeof rawOutcome.resolver !== "string") {
-            continue;
+            return;
         }
-        if (rawOutcome.status !== "resolved" && rawOutcome.status !== "failed") {
-            continue;
+        if (!ATTEMPTED_PROVENANCE_OUTCOME_STATUSES.has(String(rawOutcome.status))) {
+            return;
         }
-        const key = `${entry.agent_harness}\0${dimension}\0${rawOutcome.resolver}`;
+        const key = `${harness}\0${dimension}\0${rawOutcome.resolver}`;
         const aggregate = aggregates.get(key) ?? {
-            harness: entry.agent_harness,
+            harness,
             dimension,
             resolver: rawOutcome.resolver,
             attempts: 0,
@@ -83,9 +121,9 @@ function collectResolverOutcomes(entry, aggregates) {
         if (rawOutcome.status === "resolved")
             aggregate.successes += 1;
         aggregates.set(key, aggregate);
-    }
+    });
 }
-function collectHistoryContent(content, aggregates, eventLimit, initialEventsRead) {
+function collectHistoryContent(content, aggregates, invalidValues, eventLimit, initialEventsRead) {
     let eventsRead = initialEventsRead;
     for (const line of content.split("\n")) {
         if (line.trim().length === 0)
@@ -95,13 +133,14 @@ function collectHistoryContent(content, aggregates, eventLimit, initialEventsRea
         eventsRead += 1;
         const entry = parseHistoryEntry(line);
         if (entry)
-            collectResolverOutcomes(entry, aggregates);
+            collectResolverOutcomes(entry, aggregates, invalidValues);
     }
     return { eventsRead, truncated: false };
 }
 /** Scan immutable history without failing over malformed streams owned by integrity checks. */
 export async function scanProvenanceResolverHealth(pmRoot, eventLimit = 10_000) {
     const aggregates = new Map();
+    const invalidValues = new Map();
     let eventsRead = 0;
     let bytesRead = 0;
     let truncated = false;
@@ -110,7 +149,7 @@ export async function scanProvenanceResolverHealth(pmRoot, eventLimit = 10_000)
         if (history === null)
             continue;
         bytesRead += history.bytesRead;
-        const collected = collectHistoryContent(history.content, aggregates, eventLimit, eventsRead);
+        const collected = collectHistoryContent(history.content, aggregates, invalidValues, eventLimit, eventsRead);
         eventsRead = collected.eventsRead;
         if (collected.truncated) {
             truncated = true;
@@ -124,16 +163,23 @@ export async function scanProvenanceResolverHealth(pmRoot, eventLimit = 10_000)
     const outcomes = [...aggregates.values()].sort((left, right) => left.harness.localeCompare(right.harness) ||
         left.dimension.localeCompare(right.dimension) ||
         left.resolver.localeCompare(right.resolver));
+    const invalidValueFindings = [...invalidValues.values()].sort((left, right) => left.harness.localeCompare(right.harness) ||
+        left.dimension.localeCompare(right.dimension) ||
+        left.kind.localeCompare(right.kind));
     return {
         outcomes,
+        invalid_values: invalidValueFindings,
         warnings: truncated
             ? []
-            : outcomes
-                .filter((outcome) => outcome.attempts > 0 && outcome.successes === 0)
-                .map((outcome) => `provenance_resolver_zero_success:${outcome.harness}:${outcome.dimension}:${outcome.resolver}:${String(outcome.attempts)}`),
+            : [
+                ...outcomes
+                    .filter((outcome) => outcome.attempts > 0 && outcome.successes === 0)
+                    .map((outcome) => `provenance_resolver_zero_success:${outcome.harness}:${outcome.dimension}:${outcome.resolver}:${String(outcome.attempts)}`),
+                ...invalidValueFindings.map((finding) => `provenance_value_domain_invalid:${finding.harness}:${finding.dimension}:${finding.kind}:${String(finding.count)}`),
+            ],
         events_read: eventsRead,
         truncated,
     };
 }
 //# sourceMappingURL=provenance-health.js.map
-//# debugId=68d4d540-a878-57f1-b2ae-00b111f94b43
+//# debugId=60154e1b-8348-5b6b-badf-e76bba43bef8

package/dist/sdk/governance/validate-item-reader.d.ts

@@ -0,0 +1,13 @@
+import type { ItemMetadata, PmSettings } from "../../types/index.js";
+/** Item projection accepted by validate checks; body is read only for strict drift verification. */
+export type ValidateItem = ItemMetadata & {
+    body: string;
+};
+/** Load collections for normal checks and add bodies only when history hashes must be verified. */
+export declare function readValidateItems(params: {
+    includeBody: boolean;
+    pmRoot: string;
+    settings: PmSettings;
+    typeToFolder: Record<string, string>;
+    warnings: string[];
+}): Promise<ValidateItem[]>;

package/dist/sdk/governance/validate-item-reader.js

@@ -0,0 +1,18 @@
+/**
+ * @module sdk/governance/validate-item-reader
+ *
+ * Selects the least expensive authoritative item projection required by a
+ * validation run.
+ */
+
+!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]="896ffe11-2cf1-5de0-8d07-5585d4f30c94")}catch(e){}}();
+import { listAllItemMetadata, listAllItemMetadataWithBody, } from "../../core/store/item-store.js";
+/** Load collections for normal checks and add bodies only when history hashes must be verified. */
+export async function readValidateItems(params) {
+    if (params.includeBody) {
+        return listAllItemMetadataWithBody(params.pmRoot, params.settings.item_format, params.typeToFolder, params.warnings, params.settings.schema);
+    }
+    return listAllItemMetadata(params.pmRoot, params.settings.item_format, params.typeToFolder, params.warnings, params.settings.schema);
+}
+//# sourceMappingURL=validate-item-reader.js.map
+//# debugId=896ffe11-2cf1-5de0-8d07-5585d4f30c94

package/dist/sdk/governance/validate.d.ts

@@ -1,17 +1,17 @@
 import { type RuntimeStatusRegistry } from "../../core/schema/runtime-schema.js";
 import type { GlobalOptions } from "../../core/shared/command-types.js";
-import { listAllItemMetadataWithBody } from "../../core/store/item-store.js";
 import { type CloseReasonBackfillRow, type EstimateBackfillRow, type StaleLinkPruneRow, type TerminalParentFixRow, type ValidateFixRecord } from "../../core/validate/fix-planning.js";
 import { type DuplicateIssueCode } from "../../core/governance/issue-codes.js";
 import { type MissingFieldOccurrence } from "../../core/validate/missing-by-type.js";
 import type { ValidateMetadataProfile, ValidateMetadataRequiredField } from "../../types/index.js";
 import { type OutputProjectionDeclaration } from "../output-projection.js";
 import { type RelationshipKindRegistry } from "../relationships.js";
+import { type ValidateItem } from "./validate-item-reader.js";
 type ValidateCheckName = "metadata" | "resolution" | "lifecycle" | "dependency_references" | "files" | "command_references" | "history_drift" | "format_version" | "storage_integrity";
 type ValidateStatus = "ok" | "warn" | "error";
 type ValidateDependencyCycleSeverity = "off" | "warn" | "error";
 type ValidateFileScanMode = "default" | "tracked-all" | "tracked-all-strict";
-type ItemWithBody = Awaited<ReturnType<typeof listAllItemMetadataWithBody>>[number];
+type ItemWithBody = ValidateItem;
 type OrphanedPathClassification = "docs_unowned" | "tests_unowned" | "source_unowned" | "unlinked_existing";
 declare const LIFECYCLE_PATTERN_FIELD_KEYS: readonly ["blocked_reason", "resolution", "actual_result"];
 type LifecyclePatternFieldKey = (typeof LIFECYCLE_PATTERN_FIELD_KEYS)[number];

package/dist/sdk/governance/validate.js

@@ -4,7 +4,7 @@
  * Implements the pm validate command surface and its agent-facing runtime behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="f4fe9337-9b1c-590f-9071-d685559bb7b9")}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]="b5b7e497-f067-5504-9ffa-fd177997c518")}catch(e){}}();
 import fs from "node:fs/promises";
 import { realpathSync } from "node:fs";
 import { execFile } from "node:child_process";
@@ -23,7 +23,6 @@ import { PmCliError } from "../../core/shared/errors.js";
 import { toNonEmptyStringOrUndefined } from "../../core/shared/primitives.js";
 import { nowIso } from "../../core/shared/time.js";
 import { CURRENT_ITEM_FORMAT_VERSION, effectiveItemFormatVersion, scanItemFormatVersions, } from "../../core/item/item-format-version.js";
-import { listAllItemMetadataWithBody } from "../../core/store/item-store.js";
 import { getSettingsPath, resolvePmRoot } from "../../core/store/paths.js";
 import { readSettings } from "../../core/store/settings.js";
 import { partitionFixesByGrant, planCloseReasonBackfillFixes, planEstimateBackfillFixes, planResolutionBackfillFixes, planStaleLinkPruneFixes, planTerminalParentFixes, resolveGrantedFixScopes, toFixOutputRow, } from "../../core/validate/fix-planning.js";
@@ -43,6 +42,7 @@ import { createRelationshipKindRegistry, } from "../relationships.js";
 import { runDocs } from "../docs.js";
 import { runFiles } from "../files.js";
 import { extractReferencedPmItemIdsFromCommand } from "../test/linked-command-detection.js";
+import { readValidateItems, } from "./validate-item-reader.js";
 const FILE_SCAN_DIRECTORIES = ["src", "tests", "docs"];
 const FILE_SCAN_ROOT_FILES = [
     "README.md",
@@ -2100,7 +2100,10 @@ async function buildStorageIntegrityCheck(pmRoot, items, typeToFolder, settings)
     }
     const pendingMergeReceipts = gitWorkspaceRoot === null
         ? []
-        : await listMergeReceipts(gitWorkspaceRoot, { includeLossless: true });
+        : await listMergeReceipts(gitWorkspaceRoot, {
+            includeLossless: true,
+            pmRoot,
+        });
     const { pendingDecisions: pendingMergeDecisions, lossless: losslessMergeReceipts, } = partitionMergeReceipts(pendingMergeReceipts);
     if (pendingMergeDecisions.length > 0) {
         warnings.push(`validate_merge_decisions_unreviewed:${pendingMergeDecisions.length}`);
@@ -2262,9 +2265,15 @@ export async function runValidate(options, global, services = {}) {
     const settings = await readSettings(pmRoot);
     const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
     const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
-    const itemReadWarnings = [];
-    const items = await listAllItemMetadataWithBody(pmRoot, settings.item_format, typeRegistry.type_to_folder, itemReadWarnings, settings.schema);
     const requestedChecks = resolveRequestedChecks(options);
+    const itemReadWarnings = [];
+    const items = await readValidateItems({
+        includeBody: requestedChecks.has("history_drift"),
+        pmRoot,
+        settings,
+        typeToFolder: typeRegistry.type_to_folder,
+        warnings: itemReadWarnings,
+    });
     if (requestedChecks.has("history_drift")) {
         const authorAttribution = await scanHistoryAuthorAttribution(pmRoot);
         if (authorAttribution.actionable_unknown_event_count > 0) {
@@ -2337,4 +2346,4 @@ export async function runValidate(options, global, services = {}) {
 }
 /* c8 ignore stop */
 //# sourceMappingURL=validate.js.map
-//# debugId=f4fe9337-9b1c-590f-9071-d685559bb7b9
+//# debugId=b5b7e497-f067-5504-9ffa-fd177997c518

package/dist/sdk/graph/run.js

@@ -11,7 +11,7 @@
  * queries in long-lived hosts are answered from the memoized snapshot.
  */
 
-!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]="ba8e7432-539e-55d3-b105-689db55d26b2")}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]="6c8bfb7a-687a-5fbb-b408-ffdbab1187a9")}catch(e){}}();
 import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
 import { pathExists } from "../../core/fs/fs-utils.js";
 import { isTerminalStatus } from "../../core/item/status.js";
@@ -19,6 +19,7 @@ import { resolveItemTypeRegistry } from "../../core/item/type-registry.js";
 import { resolveRuntimeStatusRegistry } from "../../core/schema/runtime-schema.js";
 import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
+import { createUnknownSubcommandError } from "../agent/subcommand-recovery.js";
 import { listAllItemMetadataLight } from "../../core/store/item-store.js";
 import { getSettingsPath, resolvePmRoot } from "../../core/store/paths.js";
 import { readSettings } from "../../core/store/settings.js";
@@ -74,7 +75,11 @@ function normalizeIdList(raw) {
 export function parseGraphSubcommand(raw, id, target) {
     const candidate = raw.trim().toLowerCase();
     if (!GRAPH_SUBCOMMAND_VALUES.includes(candidate)) {
-        throw new PmCliError(`Invalid graph subcommand "${raw}". Use one of: ${GRAPH_SUBCOMMAND_VALUES.join(", ")}.`, EXIT_CODE.USAGE);
+        throw createUnknownSubcommandError({
+            command_path: "graph",
+            token: candidate || "<empty>",
+            allowed: GRAPH_SUBCOMMAND_VALUES,
+        });
     }
     const subcommand = candidate;
     if (ROOTED_SUBCOMMANDS.has(subcommand) && !id?.trim()) {
@@ -714,4 +719,4 @@ export async function runGraph(subcommandRaw, id, target, options, global) {
     return attachGraphProjection(value, invocation.summary, "result_rows");
 }
 //# sourceMappingURL=run.js.map
-//# debugId=ba8e7432-539e-55d3-b105-689db55d26b2
+//# debugId=6c8bfb7a-687a-5fbb-b408-ffdbab1187a9

package/dist/sdk/index.d.ts

@@ -17,6 +17,10 @@ export { SNAPSHOT_SCHEMA, createWorkspaceSnapshot, deleteWorkspaceSnapshot, insp
 export { flushTelemetryQueue } from "./telemetry-flush.js";
 export { EXECUTABLE_COMMAND_ALIASES, applyBootstrapPagerPolicy, coalesceRepeatedListFlags, listAliasPluralKeys, mergeLinkedTestTwoTokenEntries, normalizeBootstrapInvocation, normalizeLegacyExtensionActionSyntax, parseBootstrapCommandName, parseBootstrapGlobalOptions, parseBootstrapHelpRequest, parseBootstrapTypeValue, stripGlobalBootstrapTokens, type BootstrapGlobalOptions, type BootstrapHelpRequest, type BootstrapInvocationNormalizationResult, type BootstrapNormalizationEvent, } from "./cli-bootstrap.js";
 export { quoteCommandArg, quoteWindowsCommandArg, renderPmCommand, } from "./command-line.js";
+export * from "./agent/command-recovery.js";
+export * from "./agent/command-suggestions.js";
+export * from "./agent/item-addressing.js";
+export * from "./agent/create-option-policy.js";
 export { runGc, type GcCheckpointsSummary, type GcLocksSummary, } from "./governance/gc.js";
 export { _testOnlyHealthCommand, runHealth, type HealthCheck, } from "./governance/health.js";
 export { _testOnlyValidateCommand, projectValidateCounts, runValidate, type ValidateCheck, type ValidateCountsFixesSummary, type ValidateCountsResult, type ValidateFixesSummary, type ValidateMutationServices, } from "./governance/validate.js";
@@ -48,9 +52,12 @@ export { RESERVED_ITEM_FIELD_NAMES } from "../core/extensions/item-fields.js";
 export type { LocatedItem } from "../core/store/item-store.js";
 export { PM_PACKAGE_CONVENTIONAL_RESOURCE_ROOTS, PM_PACKAGE_RESOURCE_KINDS, collectPackageExtensionDirectories, readPmPackageManifest, type PmPackageCatalogLinkMap, type PmPackageCatalogMediaMap, type PmPackageCatalogMetadata, type PmPackageManifest, type PmPackageResourceKind, type PmPackageResourceMap, } from "../core/packages/manifest.js";
 export type { CommanderOptionAliasContract, CommanderOptionRegistrationContract, } from "./cli-contracts.js";
-export { ACTIVITY_FLAG_CONTRACTS, ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, AGGREGATE_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS, CALENDAR_FLAG_CONTRACTS, CLAIM_FLAG_CONTRACTS, CLOSE_ACTION_OPTION_KEYS, CLOSE_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, CLOSE_TASK_FLAG_CONTRACTS, COMMENTS_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONFIG_FLAG_CONTRACTS, CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS, CONTEXT_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, CREATE_COMMANDER_STRING_OPTION_CONTRACTS, CREATE_FLAG_CONTRACTS, DELETE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, DOCS_FLAG_CONTRACTS, EVAL_FLAG_CONTRACTS, EVENT_FLAG_CONTRACTS, EVENTS_FLAG_CONTRACTS, EXTENSION_ACTIVATE_FLAG_CONTRACTS, EXTENSION_ADOPT_ALL_FLAG_CONTRACTS, EXTENSION_ADOPT_FLAG_CONTRACTS, EXTENSION_CATALOG_FLAG_CONTRACTS, EXTENSION_DEACTIVATE_FLAG_CONTRACTS, EXTENSION_DESCRIBE_FLAG_CONTRACTS, EXTENSION_DOCTOR_FLAG_CONTRACTS, EXTENSION_EXPLORE_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, EXTENSION_INIT_FLAG_CONTRACTS, EXTENSION_INSTALL_FLAG_CONTRACTS, EXTENSION_MANAGE_FLAG_CONTRACTS, EXTENSION_MIGRATE_FLAG_CONTRACTS, EXTENSION_RELOAD_FLAG_CONTRACTS, EXTENSION_SCOPE_FLAG_CONTRACTS, EXTENSION_UNINSTALL_FLAG_CONTRACTS, FILES_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, GC_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, HISTORY_COMPACT_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, HISTORY_REDACT_FLAG_CONTRACTS, HISTORY_REPAIR_FLAG_CONTRACTS, HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, INSTALL_FLAG_CONTRACTS, ITEM_MUTATE_FLAG_CONTRACTS, ITEM_COMPLETE_FLAG_CONTRACTS, LEARNINGS_FLAG_CONTRACTS, LIST_COMMANDER_STRING_OPTION_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, MEET_FLAG_CONTRACTS, MERGE_FLAG_CONTRACTS, NEXT_COMMANDER_STRING_OPTION_CONTRACTS, NEXT_FLAG_CONTRACTS, NOTES_FLAG_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PACKAGE_INIT_FLAG_CONTRACTS, PAUSE_TASK_FLAG_CONTRACTS, PLAN_CREATE_METADATA_PARAMETER_KEYS, PLAN_FLAG_CONTRACTS, PM_COMMAND_OUTPUT_BUDGET_CONTRACTS, PM_CLI_ONLY_TOOL_ACTION_WAIVERS, PM_CORE_COMMAND_NAMES, PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS, PM_EXTENSION_CAPABILITY_CONTRACTS, PM_EXTENSION_POLICY_MODE_CONTRACTS, PM_EXTENSION_POLICY_SURFACE_CONTRACTS, PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS, PM_EXTENSION_SERVICE_NAME_CONTRACTS, PM_EXTENSION_TRUST_MODE_CONTRACTS, PM_PROVIDER_TOOL_PARAMETERS_SCHEMA, PM_PROVIDER_TOOL_PARAMETERS_SCHEMA_VERSION, PM_TOOL_ACTIONS, analyzePmToolActionParity, PM_TOOL_ACTION_PARAMETER_CONTRACTS, PM_TOOL_PARAMETERS_SCHEMA, PM_TOOL_PARAMETERS_SCHEMA_MAJOR, PM_TOOL_PARAMETERS_SCHEMA_VERSION, PM_OUTPUT_BUDGET_CLASSES, PM_OUTPUT_DEGRADATION_STEPS, PROFILE_FLAG_CONTRACTS, REINDEX_FLAG_CONTRACTS, RELEASE_FLAG_CONTRACTS, REMIND_FLAG_CONTRACTS, RESTORE_FLAG_CONTRACTS, SCHEMA_FLAG_CONTRACTS, SEARCH_COMMANDER_STRING_OPTION_CONTRACTS, SEARCH_FLAG_CONTRACTS, START_TASK_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, SUBCOMMAND_GLOBAL_FLAG_CONTRACTS, TELEMETRY_FLAG_CONTRACTS, TEST_ALL_FLAG_CONTRACTS, TEST_FLAG_CONTRACTS, TEST_RUNS_FLAG_CONTRACTS, TOOL_ACTIVITY_OPTION_CONTRACTS, TOOL_AGGREGATE_OPTION_CONTRACTS, TOOL_BULK_MUTATION_FILTER_OPTION_CONTRACT_SOURCE, TOOL_CALENDAR_OPTION_CONTRACTS, TOOL_CLOSE_MANY_FILTER_OPTION_CONTRACTS, TOOL_CONTEXT_OPTION_CONTRACTS, TOOL_CREATE_OPTION_CONTRACTS, TOOL_CREATE_OPTION_CONTRACT_SOURCE, TOOL_DEPS_OPTION_CONTRACTS, TOOL_GRAPH_OPTION_CONTRACTS, TOOL_LIST_FILTER_OPTION_CONTRACTS, TOOL_SEARCH_FILTER_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACT_SOURCE, TOOL_UPDATE_MANY_FILTER_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACT_SOURCE, UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, UPDATE_COMMANDER_STRING_OPTION_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, UPGRADE_FLAG_CONTRACTS, VALIDATE_FLAG_CONTRACTS, WORKSPACE_FLAG_CONTRACTS, buildPmActionToolInputSchema, PM_TOOL_RESERVED_CUSTOM_FIELD_PROPERTIES, compactFlagAliasContracts, createPmCommandOutputBudget, definePmCommandOutputBudget, estimatePmOutputTokens, inferPmOutputBudgetClass, analyzeSdkCliParameterCompleteness, isPmExtensionCapabilityContract, isPmExtensionPolicyModeContract, isPmExtensionPolicySurfaceContract, isPmExtensionServiceNameContract, isPmToolAction, hasSubcommandFlagContractsForCommand, readFirstStringFromCommanderOptions, readFirstValueFromCommanderOptions, readStringArrayFromCommanderOptions, resolveSubcommandFlagContractsForCommand, resolvePmCommandOutputBudget, resolvePmToolCustomFieldCollision, toCompletionFlagString, withFlagAliasMetadata, } from "./cli-contracts.js";
+export { ACTIVITY_FLAG_CONTRACTS, ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, AGGREGATE_FLAG_CONTRACTS, ASSURANCE_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS, CALENDAR_FLAG_CONTRACTS, CLAIM_FLAG_CONTRACTS, CLOSE_ACTION_OPTION_KEYS, CLOSE_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, CLOSE_TASK_FLAG_CONTRACTS, COMMENTS_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONFIG_FLAG_CONTRACTS, CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS, CONTEXT_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, CREATE_COMMANDER_STRING_OPTION_CONTRACTS, CREATE_FLAG_CONTRACTS, DELETE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, DOCS_FLAG_CONTRACTS, EVAL_FLAG_CONTRACTS, EVENT_FLAG_CONTRACTS, EVENTS_FLAG_CONTRACTS, EXTENSION_ACTIVATE_FLAG_CONTRACTS, EXTENSION_ADOPT_ALL_FLAG_CONTRACTS, EXTENSION_ADOPT_FLAG_CONTRACTS, EXTENSION_CATALOG_FLAG_CONTRACTS, EXTENSION_DEACTIVATE_FLAG_CONTRACTS, EXTENSION_DESCRIBE_FLAG_CONTRACTS, EXTENSION_DOCTOR_FLAG_CONTRACTS, EXTENSION_EXPLORE_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, EXTENSION_INIT_FLAG_CONTRACTS, EXTENSION_INSTALL_FLAG_CONTRACTS, EXTENSION_MANAGE_FLAG_CONTRACTS, EXTENSION_MIGRATE_FLAG_CONTRACTS, EXTENSION_RELOAD_FLAG_CONTRACTS, EXTENSION_SCOPE_FLAG_CONTRACTS, EXTENSION_UNINSTALL_FLAG_CONTRACTS, FILES_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, GC_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, HISTORY_COMPACT_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, HISTORY_REDACT_FLAG_CONTRACTS, HISTORY_REPAIR_FLAG_CONTRACTS, HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, INSTALL_FLAG_CONTRACTS, ITEM_MUTATE_FLAG_CONTRACTS, ITEM_COMPLETE_FLAG_CONTRACTS, LEARNINGS_FLAG_CONTRACTS, LIST_COMMANDER_STRING_OPTION_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, MEET_FLAG_CONTRACTS, MERGE_FLAG_CONTRACTS, NEXT_COMMANDER_STRING_OPTION_CONTRACTS, NEXT_FLAG_CONTRACTS, NOTES_FLAG_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PACKAGE_INIT_FLAG_CONTRACTS, PAUSE_TASK_FLAG_CONTRACTS, PLAN_CREATE_METADATA_PARAMETER_KEYS, PLAN_FLAG_CONTRACTS, PM_COMMAND_OUTPUT_BUDGET_CONTRACTS, PM_CLI_ONLY_TOOL_ACTION_WAIVERS, PM_CORE_COMMAND_NAMES, PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS, PM_EXTENSION_CAPABILITY_CONTRACTS, PM_EXTENSION_POLICY_MODE_CONTRACTS, PM_EXTENSION_POLICY_SURFACE_CONTRACTS, PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS, PM_EXTENSION_SERVICE_NAME_CONTRACTS, PM_EXTENSION_TRUST_MODE_CONTRACTS, PM_PROVIDER_TOOL_PARAMETERS_SCHEMA, PM_PROVIDER_TOOL_PARAMETERS_SCHEMA_VERSION, PM_TOOL_ACTIONS, analyzePmToolActionParity, PM_TOOL_ACTION_PARAMETER_CONTRACTS, PM_TOOL_PARAMETERS_SCHEMA, PM_TOOL_PARAMETERS_SCHEMA_MAJOR, PM_TOOL_PARAMETERS_SCHEMA_VERSION, PM_OUTPUT_BUDGET_CLASSES, PM_OUTPUT_DEGRADATION_STEPS, PROFILE_FLAG_CONTRACTS, REINDEX_FLAG_CONTRACTS, RELEASE_FLAG_CONTRACTS, REMIND_FLAG_CONTRACTS, RESTORE_FLAG_CONTRACTS, SCHEMA_FLAG_CONTRACTS, SEARCH_COMMANDER_STRING_OPTION_CONTRACTS, SEARCH_FLAG_CONTRACTS, START_TASK_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, SUBCOMMAND_GLOBAL_FLAG_CONTRACTS, TELEMETRY_FLAG_CONTRACTS, TEST_ALL_FLAG_CONTRACTS, TEST_FLAG_CONTRACTS, TEST_RUNS_FLAG_CONTRACTS, TOOL_ACTIVITY_OPTION_CONTRACTS, TOOL_AGGREGATE_OPTION_CONTRACTS, TOOL_BULK_MUTATION_FILTER_OPTION_CONTRACT_SOURCE, TOOL_CALENDAR_OPTION_CONTRACTS, TOOL_CLOSE_MANY_FILTER_OPTION_CONTRACTS, TOOL_CONTEXT_OPTION_CONTRACTS, TOOL_CREATE_OPTION_CONTRACTS, TOOL_CREATE_OPTION_CONTRACT_SOURCE, TOOL_DEPS_OPTION_CONTRACTS, TOOL_GRAPH_OPTION_CONTRACTS, TOOL_LIST_FILTER_OPTION_CONTRACTS, TOOL_SEARCH_FILTER_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACT_SOURCE, TOOL_UPDATE_MANY_FILTER_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACT_SOURCE, UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, UPDATE_COMMANDER_STRING_OPTION_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, UPGRADE_FLAG_CONTRACTS, VALIDATE_FLAG_CONTRACTS, WORKSPACE_FLAG_CONTRACTS, buildPmActionToolInputSchema, PM_TOOL_RESERVED_CUSTOM_FIELD_PROPERTIES, compactFlagAliasContracts, createPmCommandOutputBudget, definePmCommandOutputBudget, estimatePmOutputTokens, inferPmOutputBudgetClass, analyzeSdkCliParameterCompleteness, isPmExtensionCapabilityContract, isPmExtensionPolicyModeContract, isPmExtensionPolicySurfaceContract, isPmExtensionServiceNameContract, isPmToolAction, hasSubcommandFlagContractsForCommand, readFirstStringFromCommanderOptions, readFirstValueFromCommanderOptions, readStringArrayFromCommanderOptions, resolveSubcommandFlagContractsForCommand, resolvePmCommandOutputBudget, resolvePmToolCustomFieldCollision, toCompletionFlagString, withFlagAliasMetadata, } from "./cli-contracts.js";
 export type { CliFlagContract, OptionsFromContracts, PmActionSchemaContract, PmActionToolInputSchemaOptions, PmToolCustomFieldCollision, PmBulkMutationControlOptions, PmBulkMutationFilterOptions, PmCloseActionOptions, PmCloseManyActionOptions, PmCreateActionOptions, PmMutationAttributionOptions, PmOptionScalar, PmCommandOutputBudgetContract, PmOutputBudgetClass, PmOutputDegradationStep, PmUpdateActionOptions, PmUpdateManyActionOptions, PmExtensionCapabilityContract, PmExtensionPolicyModeContract, PmExtensionPolicySurfaceContract, PmExtensionSandboxProfileContract, PmExtensionServiceNameContract, PmExtensionTrustModeContract, PmToolAction, SdkCliActionParameterCoverage, SdkCliCompletenessContractSource, SdkCliParameterCoverageEntry, SdkCliParameterDisposition, ToolOptionFlagContract, } from "./cli-contracts.js";
 export * from "./compose.js";
+export * from "./governance/assurance.js";
+export * from "./governance/assurance-action.js";
+export * from "./governance/assurance-runtime.js";
 export * from "./compile-cache.js";
 export * from "./environment/project-runtime-compatibility.js";
 export * from "./environment/source-context.js";
@@ -106,6 +113,8 @@ export * from "./runtime-primitives.js";
 export * from "./error-runtime.js";
 export * from "./error-code-catalog.js";
 export * from "./generated-error-code-catalog.js";
+export * from "./agent/refusal-reachability.js";
+export * from "./agent/subcommand-recovery.js";
 export * from "./flag-invocation-contracts.js";
 export * from "./relationships.js";
 export * from "./actionability.js";

package/dist/sdk/index.js

@@ -4,7 +4,7 @@
  * Defines public SDK APIs and package-author helpers for Index.
  */
 
-!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]="ae84c7af-bfa7-577d-b9f3-2bd9450d5755")}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]="8c96c6f6-f711-559a-bb35-9eeaedc720aa")}catch(e){}}();
 export { PM_COMMAND_VISIBILITY_CONTRACTS, PM_MCP_PROMPT_CONTRACTS, PM_MCP_RESOURCE_CONTRACTS, PM_MCP_TOOL_COMMAND_CONTRACTS, listPmCommandsForTier, listPmMcpToolsForProfile, renderPmCommandVisibilityMarkdown, resolvePmCommandVisibilityTier, } from "./agent-capability-contracts.js";
 export * from "./agent-session-context.js";
 export { isErrnoError, limitAnnotationEntries, parseAnnotationTextInput, readAnnotationEntries, normalizeAnnotationTransportOptions, resolveAnnotationInput, resolveAnnotationIndex, runAnnotationCommand, wrapOwnershipConflict, } from "./annotations.js";
@@ -18,6 +18,10 @@ export { SNAPSHOT_SCHEMA, createWorkspaceSnapshot, deleteWorkspaceSnapshot, insp
 export { flushTelemetryQueue } from "./telemetry-flush.js";
 export { EXECUTABLE_COMMAND_ALIASES, applyBootstrapPagerPolicy, coalesceRepeatedListFlags, listAliasPluralKeys, mergeLinkedTestTwoTokenEntries, normalizeBootstrapInvocation, normalizeLegacyExtensionActionSyntax, parseBootstrapCommandName, parseBootstrapGlobalOptions, parseBootstrapHelpRequest, parseBootstrapTypeValue, stripGlobalBootstrapTokens, } from "./cli-bootstrap.js";
 export { quoteCommandArg, quoteWindowsCommandArg, renderPmCommand, } from "./command-line.js";
+export * from "./agent/command-recovery.js";
+export * from "./agent/command-suggestions.js";
+export * from "./agent/item-addressing.js";
+export * from "./agent/create-option-policy.js";
 export { runGc, } from "./governance/gc.js";
 export { _testOnlyHealthCommand, runHealth, } from "./governance/health.js";
 export { _testOnlyValidateCommand, projectValidateCounts, runValidate, } from "./governance/validate.js";
@@ -47,8 +51,11 @@ export { PROFILE_SUBCOMMANDS, formatProfileApplyHuman, formatProfileLintHuman, f
 export * from "./extension-contracts.js";
 export { RESERVED_ITEM_FIELD_NAMES } from "../core/extensions/item-fields.js";
 export { PM_PACKAGE_CONVENTIONAL_RESOURCE_ROOTS, PM_PACKAGE_RESOURCE_KINDS, collectPackageExtensionDirectories, readPmPackageManifest, } from "../core/packages/manifest.js";
-export { ACTIVITY_FLAG_CONTRACTS, ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, AGGREGATE_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS, CALENDAR_FLAG_CONTRACTS, CLAIM_FLAG_CONTRACTS, CLOSE_ACTION_OPTION_KEYS, CLOSE_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, CLOSE_TASK_FLAG_CONTRACTS, COMMENTS_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONFIG_FLAG_CONTRACTS, CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS, CONTEXT_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, CREATE_COMMANDER_STRING_OPTION_CONTRACTS, CREATE_FLAG_CONTRACTS, DELETE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, DOCS_FLAG_CONTRACTS, EVAL_FLAG_CONTRACTS, EVENT_FLAG_CONTRACTS, EVENTS_FLAG_CONTRACTS, EXTENSION_ACTIVATE_FLAG_CONTRACTS, EXTENSION_ADOPT_ALL_FLAG_CONTRACTS, EXTENSION_ADOPT_FLAG_CONTRACTS, EXTENSION_CATALOG_FLAG_CONTRACTS, EXTENSION_DEACTIVATE_FLAG_CONTRACTS, EXTENSION_DESCRIBE_FLAG_CONTRACTS, EXTENSION_DOCTOR_FLAG_CONTRACTS, EXTENSION_EXPLORE_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, EXTENSION_INIT_FLAG_CONTRACTS, EXTENSION_INSTALL_FLAG_CONTRACTS, EXTENSION_MANAGE_FLAG_CONTRACTS, EXTENSION_MIGRATE_FLAG_CONTRACTS, EXTENSION_RELOAD_FLAG_CONTRACTS, EXTENSION_SCOPE_FLAG_CONTRACTS, EXTENSION_UNINSTALL_FLAG_CONTRACTS, FILES_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, GC_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, HISTORY_COMPACT_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, HISTORY_REDACT_FLAG_CONTRACTS, HISTORY_REPAIR_FLAG_CONTRACTS, HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, INSTALL_FLAG_CONTRACTS, ITEM_MUTATE_FLAG_CONTRACTS, ITEM_COMPLETE_FLAG_CONTRACTS, LEARNINGS_FLAG_CONTRACTS, LIST_COMMANDER_STRING_OPTION_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, MEET_FLAG_CONTRACTS, MERGE_FLAG_CONTRACTS, NEXT_COMMANDER_STRING_OPTION_CONTRACTS, NEXT_FLAG_CONTRACTS, NOTES_FLAG_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PACKAGE_INIT_FLAG_CONTRACTS, PAUSE_TASK_FLAG_CONTRACTS, PLAN_CREATE_METADATA_PARAMETER_KEYS, PLAN_FLAG_CONTRACTS, PM_COMMAND_OUTPUT_BUDGET_CONTRACTS, PM_CLI_ONLY_TOOL_ACTION_WAIVERS, PM_CORE_COMMAND_NAMES, PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS, PM_EXTENSION_CAPABILITY_CONTRACTS, PM_EXTENSION_POLICY_MODE_CONTRACTS, PM_EXTENSION_POLICY_SURFACE_CONTRACTS, PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS, PM_EXTENSION_SERVICE_NAME_CONTRACTS, PM_EXTENSION_TRUST_MODE_CONTRACTS, PM_PROVIDER_TOOL_PARAMETERS_SCHEMA, PM_PROVIDER_TOOL_PARAMETERS_SCHEMA_VERSION, PM_TOOL_ACTIONS, analyzePmToolActionParity, PM_TOOL_ACTION_PARAMETER_CONTRACTS, PM_TOOL_PARAMETERS_SCHEMA, PM_TOOL_PARAMETERS_SCHEMA_MAJOR, PM_TOOL_PARAMETERS_SCHEMA_VERSION, PM_OUTPUT_BUDGET_CLASSES, PM_OUTPUT_DEGRADATION_STEPS, PROFILE_FLAG_CONTRACTS, REINDEX_FLAG_CONTRACTS, RELEASE_FLAG_CONTRACTS, REMIND_FLAG_CONTRACTS, RESTORE_FLAG_CONTRACTS, SCHEMA_FLAG_CONTRACTS, SEARCH_COMMANDER_STRING_OPTION_CONTRACTS, SEARCH_FLAG_CONTRACTS, START_TASK_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, SUBCOMMAND_GLOBAL_FLAG_CONTRACTS, TELEMETRY_FLAG_CONTRACTS, TEST_ALL_FLAG_CONTRACTS, TEST_FLAG_CONTRACTS, TEST_RUNS_FLAG_CONTRACTS, TOOL_ACTIVITY_OPTION_CONTRACTS, TOOL_AGGREGATE_OPTION_CONTRACTS, TOOL_BULK_MUTATION_FILTER_OPTION_CONTRACT_SOURCE, TOOL_CALENDAR_OPTION_CONTRACTS, TOOL_CLOSE_MANY_FILTER_OPTION_CONTRACTS, TOOL_CONTEXT_OPTION_CONTRACTS, TOOL_CREATE_OPTION_CONTRACTS, TOOL_CREATE_OPTION_CONTRACT_SOURCE, TOOL_DEPS_OPTION_CONTRACTS, TOOL_GRAPH_OPTION_CONTRACTS, TOOL_LIST_FILTER_OPTION_CONTRACTS, TOOL_SEARCH_FILTER_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACT_SOURCE, TOOL_UPDATE_MANY_FILTER_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACT_SOURCE, UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, UPDATE_COMMANDER_STRING_OPTION_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, UPGRADE_FLAG_CONTRACTS, VALIDATE_FLAG_CONTRACTS, WORKSPACE_FLAG_CONTRACTS, buildPmActionToolInputSchema, PM_TOOL_RESERVED_CUSTOM_FIELD_PROPERTIES, compactFlagAliasContracts, createPmCommandOutputBudget, definePmCommandOutputBudget, estimatePmOutputTokens, inferPmOutputBudgetClass, analyzeSdkCliParameterCompleteness, isPmExtensionCapabilityContract, isPmExtensionPolicyModeContract, isPmExtensionPolicySurfaceContract, isPmExtensionServiceNameContract, isPmToolAction, hasSubcommandFlagContractsForCommand, readFirstStringFromCommanderOptions, readFirstValueFromCommanderOptions, readStringArrayFromCommanderOptions, resolveSubcommandFlagContractsForCommand, resolvePmCommandOutputBudget, resolvePmToolCustomFieldCollision, toCompletionFlagString, withFlagAliasMetadata, } from "./cli-contracts.js";
+export { ACTIVITY_FLAG_CONTRACTS, ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, AGGREGATE_FLAG_CONTRACTS, ASSURANCE_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS, CALENDAR_FLAG_CONTRACTS, CLAIM_FLAG_CONTRACTS, CLOSE_ACTION_OPTION_KEYS, CLOSE_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, CLOSE_TASK_FLAG_CONTRACTS, COMMENTS_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONFIG_FLAG_CONTRACTS, CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS, CONTEXT_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, CREATE_COMMANDER_STRING_OPTION_CONTRACTS, CREATE_FLAG_CONTRACTS, DELETE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, DOCS_FLAG_CONTRACTS, EVAL_FLAG_CONTRACTS, EVENT_FLAG_CONTRACTS, EVENTS_FLAG_CONTRACTS, EXTENSION_ACTIVATE_FLAG_CONTRACTS, EXTENSION_ADOPT_ALL_FLAG_CONTRACTS, EXTENSION_ADOPT_FLAG_CONTRACTS, EXTENSION_CATALOG_FLAG_CONTRACTS, EXTENSION_DEACTIVATE_FLAG_CONTRACTS, EXTENSION_DESCRIBE_FLAG_CONTRACTS, EXTENSION_DOCTOR_FLAG_CONTRACTS, EXTENSION_EXPLORE_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, EXTENSION_INIT_FLAG_CONTRACTS, EXTENSION_INSTALL_FLAG_CONTRACTS, EXTENSION_MANAGE_FLAG_CONTRACTS, EXTENSION_MIGRATE_FLAG_CONTRACTS, EXTENSION_RELOAD_FLAG_CONTRACTS, EXTENSION_SCOPE_FLAG_CONTRACTS, EXTENSION_UNINSTALL_FLAG_CONTRACTS, FILES_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, GC_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, HISTORY_COMPACT_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, HISTORY_REDACT_FLAG_CONTRACTS, HISTORY_REPAIR_FLAG_CONTRACTS, HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, INSTALL_FLAG_CONTRACTS, ITEM_MUTATE_FLAG_CONTRACTS, ITEM_COMPLETE_FLAG_CONTRACTS, LEARNINGS_FLAG_CONTRACTS, LIST_COMMANDER_STRING_OPTION_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, MEET_FLAG_CONTRACTS, MERGE_FLAG_CONTRACTS, NEXT_COMMANDER_STRING_OPTION_CONTRACTS, NEXT_FLAG_CONTRACTS, NOTES_FLAG_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PACKAGE_INIT_FLAG_CONTRACTS, PAUSE_TASK_FLAG_CONTRACTS, PLAN_CREATE_METADATA_PARAMETER_KEYS, PLAN_FLAG_CONTRACTS, PM_COMMAND_OUTPUT_BUDGET_CONTRACTS, PM_CLI_ONLY_TOOL_ACTION_WAIVERS, PM_CORE_COMMAND_NAMES, PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS, PM_EXTENSION_CAPABILITY_CONTRACTS, PM_EXTENSION_POLICY_MODE_CONTRACTS, PM_EXTENSION_POLICY_SURFACE_CONTRACTS, PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS, PM_EXTENSION_SERVICE_NAME_CONTRACTS, PM_EXTENSION_TRUST_MODE_CONTRACTS, PM_PROVIDER_TOOL_PARAMETERS_SCHEMA, PM_PROVIDER_TOOL_PARAMETERS_SCHEMA_VERSION, PM_TOOL_ACTIONS, analyzePmToolActionParity, PM_TOOL_ACTION_PARAMETER_CONTRACTS, PM_TOOL_PARAMETERS_SCHEMA, PM_TOOL_PARAMETERS_SCHEMA_MAJOR, PM_TOOL_PARAMETERS_SCHEMA_VERSION, PM_OUTPUT_BUDGET_CLASSES, PM_OUTPUT_DEGRADATION_STEPS, PROFILE_FLAG_CONTRACTS, REINDEX_FLAG_CONTRACTS, RELEASE_FLAG_CONTRACTS, REMIND_FLAG_CONTRACTS, RESTORE_FLAG_CONTRACTS, SCHEMA_FLAG_CONTRACTS, SEARCH_COMMANDER_STRING_OPTION_CONTRACTS, SEARCH_FLAG_CONTRACTS, START_TASK_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, SUBCOMMAND_GLOBAL_FLAG_CONTRACTS, TELEMETRY_FLAG_CONTRACTS, TEST_ALL_FLAG_CONTRACTS, TEST_FLAG_CONTRACTS, TEST_RUNS_FLAG_CONTRACTS, TOOL_ACTIVITY_OPTION_CONTRACTS, TOOL_AGGREGATE_OPTION_CONTRACTS, TOOL_BULK_MUTATION_FILTER_OPTION_CONTRACT_SOURCE, TOOL_CALENDAR_OPTION_CONTRACTS, TOOL_CLOSE_MANY_FILTER_OPTION_CONTRACTS, TOOL_CONTEXT_OPTION_CONTRACTS, TOOL_CREATE_OPTION_CONTRACTS, TOOL_CREATE_OPTION_CONTRACT_SOURCE, TOOL_DEPS_OPTION_CONTRACTS, TOOL_GRAPH_OPTION_CONTRACTS, TOOL_LIST_FILTER_OPTION_CONTRACTS, TOOL_SEARCH_FILTER_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACT_SOURCE, TOOL_UPDATE_MANY_FILTER_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACT_SOURCE, UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, UPDATE_COMMANDER_STRING_OPTION_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, UPGRADE_FLAG_CONTRACTS, VALIDATE_FLAG_CONTRACTS, WORKSPACE_FLAG_CONTRACTS, buildPmActionToolInputSchema, PM_TOOL_RESERVED_CUSTOM_FIELD_PROPERTIES, compactFlagAliasContracts, createPmCommandOutputBudget, definePmCommandOutputBudget, estimatePmOutputTokens, inferPmOutputBudgetClass, analyzeSdkCliParameterCompleteness, isPmExtensionCapabilityContract, isPmExtensionPolicyModeContract, isPmExtensionPolicySurfaceContract, isPmExtensionServiceNameContract, isPmToolAction, hasSubcommandFlagContractsForCommand, readFirstStringFromCommanderOptions, readFirstValueFromCommanderOptions, readStringArrayFromCommanderOptions, resolveSubcommandFlagContractsForCommand, resolvePmCommandOutputBudget, resolvePmToolCustomFieldCollision, toCompletionFlagString, withFlagAliasMetadata, } from "./cli-contracts.js";
 export * from "./compose.js";
+export * from "./governance/assurance.js";
+export * from "./governance/assurance-action.js";
+export * from "./governance/assurance-runtime.js";
 export * from "./compile-cache.js";
 export * from "./environment/project-runtime-compatibility.js";
 export * from "./environment/source-context.js";
@@ -104,6 +111,8 @@ export * from "./runtime-primitives.js";
 export * from "./error-runtime.js";
 export * from "./error-code-catalog.js";
 export * from "./generated-error-code-catalog.js";
+export * from "./agent/refusal-reachability.js";
+export * from "./agent/subcommand-recovery.js";
 export * from "./flag-invocation-contracts.js";
 export * from "./relationships.js";
 export * from "./actionability.js";
@@ -141,4 +150,4 @@ export * from "./governance.js";
 export * from "./query.js";
 export * from "./testing.js";
 //# sourceMappingURL=index.js.map
-//# debugId=ae84c7af-bfa7-577d-b9f3-2bd9450d5755
+//# debugId=8c96c6f6-f711-559a-bb35-9eeaedc720aa

package/dist/sdk/lifecycle/claim.js

@@ -4,11 +4,12 @@
  * Implements the pm claim command surface and its agent-facing runtime behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="9c3fc3ab-ba84-5f6d-a05c-bc452ae26c15")}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]="2e9b9321-a892-5bab-b6f8-4717fb5962df")}catch(e){}}();
 import { pathExists, resolveRuntimeStatusRegistry, statusIsTerminal, EXIT_CODE, PmCliError, toItemRecord, mutateItem, getSettingsPath, resolvePmRoot, readSettings, resolveAuthor, resolveClaimPrincipal, } from "../runtime-primitives.js";
 import { wrapOwnershipConflict } from "../annotations.js";
 import { describeItemOwnershipConflict } from "../ownership-source.js";
-import { runNext } from "../query/next.js";
+import { runNext, } from "../query/next.js";
+import { recordClaimSemanticAttribution, recordReleaseSemanticAttribution, } from "../context/semantic-session-attribution.js";
 /** Stable warning/error code for an exhausted atomic next-work walk. */
 export const NO_AVAILABLE_NEXT_ITEM_CODE = "no_available_next_item";
 /** Returns whether a failed claim lost the atomic test-and-set race. */
@@ -76,6 +77,14 @@ export async function runClaim(id, force, global, options = {}) {
             };
         },
     });
+    if (!skipped) {
+        await recordClaimSemanticAttribution({
+            pmRoot,
+            settings,
+            principal: claimPrincipal,
+            itemId: result.item.id,
+        });
+    }
     return {
         item: toItemRecord(result.item),
         claimed_by: skipped && previousAssignee !== null ? previousAssignee : author,
@@ -173,6 +182,7 @@ export async function runRelease(id, force, global, options = {}) {
     }
     const settings = await readSettings(pmRoot);
     const author = resolveAuthor(options.author, settings.author_default);
+    const claimPrincipal = resolveClaimPrincipal(author);
     const ownershipReleaseBypass = options.ownershipReleaseBypass === true;
     let previousAssignee = null;
     let result;
@@ -207,6 +217,11 @@ export async function runRelease(id, force, global, options = {}) {
             ],
         });
     }
+    await recordReleaseSemanticAttribution({
+        pmRoot,
+        principal: claimPrincipal,
+        itemId: result.item.id,
+    });
     return {
         item: toItemRecord(result.item),
         released_by: author,
@@ -215,4 +230,4 @@ export async function runRelease(id, force, global, options = {}) {
     };
 }
 //# sourceMappingURL=claim.js.map
-//# debugId=9c3fc3ab-ba84-5f6d-a05c-bc452ae26c15
+//# debugId=2e9b9321-a892-5bab-b6f8-4717fb5962df