@unbrained/pm-cli 2026.8.10 → 2026.8.12

package/dist/sdk/cli-contracts.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]="8071fd9d-649a-5fce-b342-84b11066d559")}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]="969b5bd2-e7de-5db8-bef2-6748675a100c")}catch(e){}}();
 export { EXECUTABLE_COMMAND_ALIASES } from "./cli-contracts/command-aliases.js";
 export { ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS, CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS, LIST_COMMANDER_STRING_OPTION_CONTRACTS, NEXT_COMMANDER_STRING_OPTION_CONTRACTS, SEARCH_COMMANDER_STRING_OPTION_CONTRACTS, readFirstValueFromCommanderOptions, readFirstStringFromCommanderOptions, readStringArrayFromCommanderOptions, } from "./cli-contracts/commander-types.js";
 export { CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, CREATE_COMMANDER_STRING_OPTION_CONTRACTS, UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, UPDATE_COMMANDER_STRING_OPTION_CONTRACTS, } from "./cli-contracts/commander-mutation-options.js";
@@ -9,9 +9,9 @@ export { CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, CREATE_COMMANDER_REPEAT
 // keep importing everything from "./cli-contracts.js" unchanged.
 export { PM_EXTENSION_CAPABILITY_CONTRACTS, PM_EXTENSION_SERVICE_NAME_CONTRACTS, PM_EXTENSION_POLICY_MODE_CONTRACTS, PM_EXTENSION_TRUST_MODE_CONTRACTS, PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS, PM_EXTENSION_POLICY_SURFACE_CONTRACTS, PM_CORE_COMMAND_NAMES, PM_CLI_ONLY_TOOL_ACTION_WAIVERS, PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS, PM_TOOL_ACTIONS, analyzePmToolActionParity, isPmToolAction, isPmExtensionCapabilityContract, isPmExtensionServiceNameContract, isPmExtensionPolicyModeContract, isPmExtensionPolicySurfaceContract, } from "./cli-contracts/enum-contracts.js";
 export { TOOL_LIST_FILTER_OPTION_CONTRACTS, TOOL_AGGREGATE_OPTION_CONTRACTS, TOOL_SEARCH_FILTER_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACTS, TOOL_CREATE_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_MANY_FILTER_OPTION_CONTRACTS, TOOL_CLOSE_MANY_FILTER_OPTION_CONTRACTS, TOOL_CALENDAR_OPTION_CONTRACTS, TOOL_ACTIVITY_OPTION_CONTRACTS, TOOL_CONTEXT_OPTION_CONTRACTS, TOOL_DEPS_OPTION_CONTRACTS, TOOL_GRAPH_OPTION_CONTRACTS, TOOL_BULK_MUTATION_FILTER_OPTION_CONTRACT_SOURCE, TOOL_CREATE_OPTION_CONTRACT_SOURCE, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACT_SOURCE, TOOL_UPDATE_OPTION_CONTRACT_SOURCE, } from "./cli-contracts/tool-option-contracts.js";
-export { withFlagAliasMetadata, compactFlagAliasContracts, SUBCOMMAND_GLOBAL_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, AGGREGATE_FLAG_CONTRACTS, COMMENTS_FLAG_CONTRACTS, NOTES_FLAG_CONTRACTS, LEARNINGS_FLAG_CONTRACTS, FILES_FLAG_CONTRACTS, DOCS_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, HISTORY_REDACT_FLAG_CONTRACTS, HISTORY_REPAIR_FLAG_CONTRACTS, HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, HISTORY_COMPACT_FLAG_CONTRACTS, MERGE_FLAG_CONTRACTS, SCHEMA_FLAG_CONTRACTS, PROFILE_FLAG_CONTRACTS, PLAN_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, CONFIG_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, EXTENSION_SCOPE_FLAG_CONTRACTS, EXTENSION_INIT_FLAG_CONTRACTS, EXTENSION_MIGRATE_FLAG_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PACKAGE_INIT_FLAG_CONTRACTS, EXTENSION_INSTALL_FLAG_CONTRACTS, EXTENSION_UNINSTALL_FLAG_CONTRACTS, EXTENSION_EXPLORE_FLAG_CONTRACTS, EXTENSION_DESCRIBE_FLAG_CONTRACTS, EXTENSION_ADOPT_ALL_FLAG_CONTRACTS, EXTENSION_ACTIVATE_FLAG_CONTRACTS, EXTENSION_DEACTIVATE_FLAG_CONTRACTS, EXTENSION_MANAGE_FLAG_CONTRACTS, EXTENSION_RELOAD_FLAG_CONTRACTS, EXTENSION_DOCTOR_FLAG_CONTRACTS, EXTENSION_CATALOG_FLAG_CONTRACTS, EXTENSION_ADOPT_FLAG_CONTRACTS, INSTALL_FLAG_CONTRACTS, UPGRADE_FLAG_CONTRACTS, REINDEX_FLAG_CONTRACTS, CLOSE_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CLAIM_FLAG_CONTRACTS, RESTORE_FLAG_CONTRACTS, DELETE_FLAG_CONTRACTS, RELEASE_FLAG_CONTRACTS, START_TASK_FLAG_CONTRACTS, PAUSE_TASK_FLAG_CONTRACTS, CLOSE_TASK_FLAG_CONTRACTS, MEET_FLAG_CONTRACTS, EVENT_FLAG_CONTRACTS, EVENTS_FLAG_CONTRACTS, REMIND_FLAG_CONTRACTS, TEST_FLAG_CONTRACTS, TEST_ALL_FLAG_CONTRACTS, TELEMETRY_FLAG_CONTRACTS, TEST_RUNS_FLAG_CONTRACTS, GC_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, VALIDATE_FLAG_CONTRACTS, CREATE_FLAG_CONTRACTS, ITEM_COMPLETE_FLAG_CONTRACTS, ITEM_MUTATE_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, CALENDAR_FLAG_CONTRACTS, ACTIVITY_FLAG_CONTRACTS, CONTEXT_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, EVAL_FLAG_CONTRACTS, WORKSPACE_FLAG_CONTRACTS, NEXT_FLAG_CONTRACTS, SEARCH_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, hasSubcommandFlagContractsForCommand, resolveSubcommandFlagContractsForCommand, toCompletionFlagString, } from "./cli-contracts/flag-contracts.js";
+export { withFlagAliasMetadata, compactFlagAliasContracts, SUBCOMMAND_GLOBAL_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, AGGREGATE_FLAG_CONTRACTS, COMMENTS_FLAG_CONTRACTS, NOTES_FLAG_CONTRACTS, LEARNINGS_FLAG_CONTRACTS, FILES_FLAG_CONTRACTS, DOCS_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, HISTORY_REDACT_FLAG_CONTRACTS, HISTORY_REPAIR_FLAG_CONTRACTS, HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, HISTORY_COMPACT_FLAG_CONTRACTS, MERGE_FLAG_CONTRACTS, SCHEMA_FLAG_CONTRACTS, PROFILE_FLAG_CONTRACTS, PLAN_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, CONFIG_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, EXTENSION_SCOPE_FLAG_CONTRACTS, EXTENSION_INIT_FLAG_CONTRACTS, EXTENSION_MIGRATE_FLAG_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PACKAGE_INIT_FLAG_CONTRACTS, EXTENSION_INSTALL_FLAG_CONTRACTS, EXTENSION_UNINSTALL_FLAG_CONTRACTS, EXTENSION_EXPLORE_FLAG_CONTRACTS, EXTENSION_DESCRIBE_FLAG_CONTRACTS, EXTENSION_ADOPT_ALL_FLAG_CONTRACTS, EXTENSION_ACTIVATE_FLAG_CONTRACTS, EXTENSION_DEACTIVATE_FLAG_CONTRACTS, EXTENSION_MANAGE_FLAG_CONTRACTS, EXTENSION_RELOAD_FLAG_CONTRACTS, EXTENSION_DOCTOR_FLAG_CONTRACTS, EXTENSION_CATALOG_FLAG_CONTRACTS, EXTENSION_ADOPT_FLAG_CONTRACTS, INSTALL_FLAG_CONTRACTS, UPGRADE_FLAG_CONTRACTS, REINDEX_FLAG_CONTRACTS, CLOSE_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CLAIM_FLAG_CONTRACTS, RESTORE_FLAG_CONTRACTS, DELETE_FLAG_CONTRACTS, RELEASE_FLAG_CONTRACTS, START_TASK_FLAG_CONTRACTS, PAUSE_TASK_FLAG_CONTRACTS, CLOSE_TASK_FLAG_CONTRACTS, MEET_FLAG_CONTRACTS, EVENT_FLAG_CONTRACTS, EVENTS_FLAG_CONTRACTS, REMIND_FLAG_CONTRACTS, TEST_FLAG_CONTRACTS, TEST_ALL_FLAG_CONTRACTS, TELEMETRY_FLAG_CONTRACTS, TEST_RUNS_FLAG_CONTRACTS, GC_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, VALIDATE_FLAG_CONTRACTS, ASSURANCE_FLAG_CONTRACTS, CREATE_FLAG_CONTRACTS, ITEM_COMPLETE_FLAG_CONTRACTS, ITEM_MUTATE_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, CALENDAR_FLAG_CONTRACTS, ACTIVITY_FLAG_CONTRACTS, CONTEXT_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, EVAL_FLAG_CONTRACTS, WORKSPACE_FLAG_CONTRACTS, NEXT_FLAG_CONTRACTS, SEARCH_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, hasSubcommandFlagContractsForCommand, resolveSubcommandFlagContractsForCommand, toCompletionFlagString, } from "./cli-contracts/flag-contracts.js";
 export { buildPmActionToolInputSchema, PM_TOOL_RESERVED_CUSTOM_FIELD_PROPERTIES, resolvePmToolCustomFieldCollision, CLOSE_ACTION_OPTION_KEYS, PLAN_CREATE_METADATA_PARAMETER_KEYS, PM_TOOL_ACTION_PARAMETER_CONTRACTS, PM_TOOL_PARAMETERS_SCHEMA_VERSION, PM_TOOL_PARAMETERS_SCHEMA_MAJOR, PM_PROVIDER_TOOL_PARAMETERS_SCHEMA_VERSION, PM_TOOL_PARAMETERS_SCHEMA, PM_PROVIDER_TOOL_PARAMETERS_SCHEMA, _testOnlyCliContracts, } from "./cli-contracts/tool-schema.js";
 export { analyzeSdkCliParameterCompleteness, } from "./cli-contracts/completeness.js";
 export { PM_COMMAND_OUTPUT_BUDGET_CONTRACTS, PM_OUTPUT_BUDGET_CLASSES, PM_OUTPUT_DEGRADATION_STEPS, createPmCommandOutputBudget, definePmCommandOutputBudget, estimatePmOutputTokens, inferPmOutputBudgetClass, resolvePmCommandOutputBudget, } from "./cli-contracts/agent-output-contracts.js";
 //# sourceMappingURL=cli-contracts.js.map
-//# debugId=8071fd9d-649a-5fce-b342-84b11066d559
+//# debugId=969b5bd2-e7de-5db8-bef2-6748675a100c

package/dist/sdk/cli-program.js

@@ -4,7 +4,7 @@
  * Builds the reusable Commander root that embeds pm's universal global contracts.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="a410d336-c332-56fc-9a5d-7841a2b3dfa5")}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]="b799c7c2-21b8-5c19-8565-7166e6f06a90")}catch(e){}}();
 import { Command } from "commander";
 import { writeStdout } from "../core/output/output.js";
 /** Create a fresh pm root program suitable for one-shot CLI or embedded hosts. */
@@ -30,6 +30,7 @@ export function createPmCliProgram(version) {
         .option("--output-budget <tokens>", "Bound estimated tokens in read output")
         .option("--output-format <toon|json>", "Select the read-output encoding")
         .option("--output-session <state>", "Carry a JSON session budget and served-item ledger across read calls")
+        .option("--output-row-contract", "Include the machine-readable row selector and TOON encoding contract")
         .option("--quiet", "Suppress stdout output")
         .option("--no-changed-fields", "Omit the changed_fields array from mutation output (keeps changed_field_count)")
         .option("--full-changed-fields", "Restore the legacy full mutation envelope and changed_fields array")
@@ -44,4 +45,4 @@ export function createPmCliProgram(version) {
         .exitOverride();
 }
 //# sourceMappingURL=cli-program.js.map
-//# debugId=a410d336-c332-56fc-9a5d-7841a2b3dfa5
+//# debugId=b799c7c2-21b8-5c19-8565-7166e6f06a90

package/dist/sdk/completion.js

@@ -4,11 +4,11 @@
  * Implements the pm completion 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]="6c9648d7-ab14-5e0d-8793-86ae13643fa6")}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]="fca471b1-155a-5fc4-9aa9-d45e5f1315dd")}catch(e){}}();
 import { EXIT_CODE, PmCliError } from "./runtime-primitives.js";
 import { listPmCommandsForTier } from "./agent-capability-contracts.js";
 import { SCAFFOLD_CAPABILITIES } from "./extension/scaffold.js";
-import { AGGREGATE_FLAG_CONTRACTS, ACTIVITY_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, CONTEXT_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, MEET_FLAG_CONTRACTS, REMIND_FLAG_CONTRACTS, CREATE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, NEXT_FLAG_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PLAN_FLAG_CONTRACTS, SEARCH_FLAG_CONTRACTS, EVENTS_FLAG_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, toCompletionFlagString, } from "./cli-contracts.js";
+import { AGGREGATE_FLAG_CONTRACTS, ACTIVITY_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, CONTEXT_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, MEET_FLAG_CONTRACTS, REMIND_FLAG_CONTRACTS, CREATE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, NEXT_FLAG_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PLAN_FLAG_CONTRACTS, SEARCH_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, EVENTS_FLAG_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, toCompletionFlagString, } from "./cli-contracts.js";
 import { BUILTIN_ITEM_TYPE_VALUES, STATUS_VALUES } from "../types/index.js";
 import { listGuideTopicIds } from "./guide-topics.js";
 const VALID_SHELLS = ["bash", "zsh", "fish"];
@@ -38,6 +38,7 @@ const DUPLICATES_FLAGS = toCompletionFlagString(DUPLICATES_FLAG_CONTRACTS);
 const GRAPH_FLAGS = toCompletionFlagString(GRAPH_FLAG_CONTRACTS);
 const GUIDE_FLAGS = toCompletionFlagString(GUIDE_FLAG_CONTRACTS);
 const SEARCH_FLAGS = toCompletionFlagString(SEARCH_FLAG_CONTRACTS);
+const STATS_FLAGS = toCompletionFlagString(STATS_FLAG_CONTRACTS);
 const HEALTH_FLAGS = toCompletionFlagString(HEALTH_FLAG_CONTRACTS);
 const INIT_FLAGS = toCompletionFlagString(INIT_FLAG_CONTRACTS);
 const CONTRACTS_FLAGS = toCompletionFlagString(CONTRACTS_FLAG_CONTRACTS);
@@ -608,7 +609,7 @@ export function generateBashScript(itemTypes = [], tags = [], eagerTagExpansion
         `      COMPREPLY=(${compgen("--add --stdin --file --edit --delete --limit --full-history --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
         "      ;;",
         "    files)",
-        `      COMPREPLY=(${compgen("discover lookup --add --add-glob --remove --migrate --list --apply --note --append-stable --validate-paths --scope --limit --offset --no-truncate --strict-read --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
+        `      COMPREPLY=(${compgen("discover lookup --add --add-glob --remove --migrate --list --apply --note --append-stable --validate-paths --scope --limit --offset --no-truncate --strict-read --explain --lines --decision-depth --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
         "      ;;",
         "    docs)",
         `      COMPREPLY=(${compgen("--add --add-glob --remove --migrate --note --validate-paths --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
@@ -623,7 +624,7 @@ export function generateBashScript(itemTypes = [], tags = [], eagerTagExpansion
         `      COMPREPLY=(${compgen(`ancestors descendants predecessors successors paths impact analyze audit communities redundancy dominators slack centrality articulation plan index ${GRAPH_FLAGS}`)})`,
         "      ;;",
         "    test)",
-        `      COMPREPLY=(${compgen("--add --add-json --remove --list --run --match --only-index --only-last --background --timeout --progress --env-set --env-clear --shared-host-safe --pm-context --override-linked-pm-context --fail-on-context-mismatch --fail-on-skipped --fail-on-empty-test-run --require-assertions-for-pm --check-context --auto-pm-context --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
+        `      COMPREPLY=(${compgen("--add --add-json --remove --remove-index --list --run --match --only-index --only-last --background --timeout --progress --env-set --env-clear --shared-host-safe --pm-context --override-linked-pm-context --fail-on-context-mismatch --fail-on-skipped --fail-on-empty-test-run --require-assertions-for-pm --check-context --auto-pm-context --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
         "      ;;",
         "    test-all)",
         `      COMPREPLY=(${compgen("--status --limit --offset --background --timeout --progress --env-set --env-clear --shared-host-safe --pm-context --override-linked-pm-context --fail-on-context-mismatch --fail-on-skipped --fail-on-empty-test-run --require-assertions-for-pm --check-context --auto-pm-context --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
@@ -677,7 +678,7 @@ export function generateBashScript(itemTypes = [], tags = [], eagerTagExpansion
         `      COMPREPLY=(${compgen("--dry-run --scope --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
         "      ;;",
         "    stats)",
-        `      COMPREPLY=(${compgen("--storage --metadata-coverage --field-utilization --by-assignee --by-tag --by-priority --tag-prefix --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
+        `      COMPREPLY=(${compgen(STATS_FLAGS)})`,
         "      ;;",
         "    close|close-task)",
         `      COMPREPLY=(${compgen(CLOSE_MUTATION_FLAGS)})`,
@@ -788,6 +789,7 @@ _pm() {
     '--output-budget[Set the universal estimated-token ceiling]:tokens' \\
     '--output-format[Select the universal read encoding]:(toon json)' \\
     '--output-session[Carry cross-call read budget and served-item state]:state' \\
+    '--output-row-contract[Include row schema metadata in read output]' \\
     '--no-changed-fields[Omit changed_fields array from mutation output]' \\
     '--pm-path[Explicit tracker storage path for this command]:path:_files -/' \\
     '--path[Compatibility alias for --pm-path]:path:_files -/' \\
@@ -1304,13 +1306,14 @@ ${zshSearchRuntimeFieldFlags}            '--json[Output JSON]' \\
             '--to[Upper timestamp bound (ISO/date string or relative)]:date' \\
             '--limit[Max entries]:number' \\
             '--compact[Condensed activity projection]' \\
+            '--raw[Emit raw compact per-event activity output]' \\
             '--full[Show full activity entries]' \\
             '--provenance[Patch-free identity and agent provenance projection]' \\
             '--provenance-summary[Include bounded provenance completeness counts]' \\
             '*--harness[Filter by recorded or vocabulary-resolved harness]:harness' \\
             '*--agent-instance[Filter by privacy-safe agent instance]:instance' \\
             '*--provenance-filter[Filter by exact declared provenance value]:dimension=value' \\
-            '--stream[Emit line-delimited JSON rows]:mode' \\
+            '--stream[Emit line-delimited JSON rows (requires --json)]:mode' \\
             '--json[Output JSON]' \\
             '--quiet[Suppress stdout]'
           ;;
@@ -1336,6 +1339,7 @@ ${zshSearchRuntimeFieldFlags}            '--json[Output JSON]' \\
           ;;
         stats)
           _arguments \\
+            '--include-empty[Include registered zero-count type and status buckets]' \\
             '--storage[Include aggregate history-stream storage metrics]' \\
             '--metadata-coverage[Include metadata coverage percentages overall and by type]' \\
             '--field-utilization[Include content-field utilization rates across all items]' \\
@@ -1412,6 +1416,9 @@ ${zshSearchRuntimeFieldFlags}            '--json[Output JSON]' \\
             '--offset[Skip the first lookup matches]:number' \\
             '--no-truncate[Return every lookup match]' \\
             '--strict-read[Require authoritative source reads]' \\
+            '--explain[Include ranked source-to-work rationale]' \\
+            '--lines[Attribute an inclusive source line range]:start_end' \\
+            '--decision-depth[Maximum governing-decision relationship depth]:number' \\
             '--author[Mutation author]:author' \\
             '--message[History message]:message' \\
             '--force[Force override]' \\
@@ -1457,6 +1464,7 @@ ${zshSearchRuntimeFieldFlags}            '--json[Output JSON]' \\
             '--add[Add linked test entry]:entry' \\
             '--add-json[Add linked test entry from JSON object/array]:json' \\
             '--remove[Remove linked test entry by command/path]:entry' \\
+            '--remove-index[Remove linked test entry by 1-based index]:index' \\
             '--list[List linked tests without mutating]' \\
             '--run[Run linked tests]' \\
             '--match[Run linked tests whose command/path contains substring]:substring' \\
@@ -1816,6 +1824,7 @@ complete -c pm -l output-limit -d 'Set the universal read row ceiling' -r
 complete -c pm -l output-budget -d 'Set the universal estimated-token ceiling' -r
 complete -c pm -l output-format -d 'Select the universal read encoding' -r -a 'toon json'
 complete -c pm -l output-session -d 'Carry cross-call read budget and served-item state' -r
+complete -c pm -l output-row-contract -d 'Include row schema metadata in read output'
 complete -c pm -l no-changed-fields -d 'Omit changed_fields array from mutation output'
 complete -c pm -l id-only -d 'Print only id and status for single-item mutation output'
 complete -c pm -l pm-path -d 'Explicit tracker storage path for this command' -r
@@ -2137,6 +2146,9 @@ complete -c pm -n '__fish_seen_subcommand_from files' -l limit -d 'Maximum looku
 complete -c pm -n '__fish_seen_subcommand_from files' -l offset -d 'Skip the first lookup matches' -r
 complete -c pm -n '__fish_seen_subcommand_from files' -l no-truncate -d 'Return every lookup match'
 complete -c pm -n '__fish_seen_subcommand_from files' -l strict-read -d 'Require authoritative source reads'
+complete -c pm -n '__fish_seen_subcommand_from files' -l explain -d 'Include ranked source-to-work rationale'
+complete -c pm -n '__fish_seen_subcommand_from files' -l lines -d 'Attribute an inclusive source line range' -r
+complete -c pm -n '__fish_seen_subcommand_from files' -l decision-depth -d 'Maximum governing-decision relationship depth' -r
 
 
 # search flags
@@ -2363,13 +2375,14 @@ complete -c pm -n '__fish_seen_subcommand_from activity' -l from -d 'Lower times
 complete -c pm -n '__fish_seen_subcommand_from activity' -l to -d 'Upper timestamp bound (ISO/date string or relative)' -r
 complete -c pm -n '__fish_seen_subcommand_from activity' -l limit -d 'Max activity entries' -r
 complete -c pm -n '__fish_seen_subcommand_from activity' -l compact -d 'Condensed activity projection'
+complete -c pm -n '__fish_seen_subcommand_from activity' -l raw -d 'Emit raw compact per-event activity output'
 complete -c pm -n '__fish_seen_subcommand_from activity' -l full -d 'Show full activity entries'
 complete -c pm -n '__fish_seen_subcommand_from activity' -l provenance -d 'Patch-free identity and agent provenance projection'
 complete -c pm -n '__fish_seen_subcommand_from activity' -l provenance-summary -d 'Include bounded provenance completeness counts'
 complete -c pm -n '__fish_seen_subcommand_from activity' -l harness -d 'Filter by recorded or vocabulary-resolved harness' -r
 complete -c pm -n '__fish_seen_subcommand_from activity' -l agent-instance -d 'Filter by privacy-safe agent instance' -r
 complete -c pm -n '__fish_seen_subcommand_from activity' -l provenance-filter -d 'Filter by exact declared provenance value' -r
-complete -c pm -n '__fish_seen_subcommand_from activity' -l stream -d 'Emit line-delimited JSON rows'
+complete -c pm -n '__fish_seen_subcommand_from activity' -l stream -d 'Emit line-delimited JSON rows (requires --json)'
 complete -c pm -n '__fish_seen_subcommand_from contracts' -l action -d 'Filter schema by tool action' -r
 complete -c pm -n '__fish_seen_subcommand_from contracts' -l command -d 'Scope output to one command (narrow-by-default)' -r
 complete -c pm -n '__fish_seen_subcommand_from contracts' -l summary -d 'Return compact command intent summary'
@@ -2427,6 +2440,7 @@ complete -c pm -n '__fish_seen_subcommand_from comments notes learnings' -l forc
 complete -c pm -n '__fish_seen_subcommand_from test' -l add -d 'Add linked test entry' -r
 complete -c pm -n '__fish_seen_subcommand_from test' -l add-json -d 'Add linked test entry from JSON object/array' -r
 complete -c pm -n '__fish_seen_subcommand_from test' -l remove -d 'Remove linked test entry' -r
+complete -c pm -n '__fish_seen_subcommand_from test' -l remove-index -d 'Remove linked test entry by 1-based index' -r
 complete -c pm -n '__fish_seen_subcommand_from test' -l list -d 'List linked tests without mutating'
 complete -c pm -n '__fish_seen_subcommand_from test' -l run -d 'Run linked tests'
 complete -c pm -n '__fish_seen_subcommand_from test' -l match -d 'Run linked tests whose command/path contains substring' -r
@@ -2483,6 +2497,7 @@ complete -c pm -n '__fish_seen_subcommand_from gc' -l dry-run -d 'Preview cleanu
 complete -c pm -n '__fish_seen_subcommand_from gc' -l scope -d 'Limit cleanup to index/embeddings/runtime/locks scopes' -r
 
 # stats flags
+complete -c pm -n '__fish_seen_subcommand_from stats' -l include-empty -d 'Include registered zero-count type and status buckets'
 complete -c pm -n '__fish_seen_subcommand_from stats' -l storage -d 'Include aggregate history-stream storage metrics'
 complete -c pm -n '__fish_seen_subcommand_from stats' -l metadata-coverage -d 'Include metadata coverage percentages overall and by type'
 complete -c pm -n '__fish_seen_subcommand_from stats' -l field-utilization -d 'Include content-field utilization rates across all items'
@@ -2747,4 +2762,4 @@ export function runCompletion(shell, itemTypes = [], tags = [], eagerTagExpansio
     };
 }
 //# sourceMappingURL=completion.js.map
-//# debugId=6c9648d7-ab14-5e0d-8793-86ae13643fa6
+//# debugId=fca471b1-155a-5fc4-9aa9-d45e5f1315dd

package/dist/sdk/config.js

@@ -4,7 +4,7 @@
  * Implements the pm config 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]="2a186a29-9d21-5ebe-9c66-3e889253b15b")}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]="a9a8d99c-df4e-55b3-81f5-27124d598c5f")}catch(e){}}();
 import { pathExists } from "../core/fs/fs-utils.js";
 import { resolveConfigPositionalValue, } from "../core/config/positional-value.js";
 import { NESTED_SETTING_DESCRIPTORS, parseNestedSettingValue, readNestedSettingValue, resolveNestedSettingDescriptor, writeNestedSettingValue, } from "../core/config/nested-settings.js";
@@ -16,6 +16,7 @@ import { buildInvalidTypeError } from "../core/schema/item-types-file.js";
 import { resolveItemTypesFilePath } 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 { migrateItemFilesToFormat } from "../core/store/item-format-migration.js";
 import { getSettingsPath, resolveGlobalPmRoot, resolvePmRoot, } from "../core/store/paths.js";
 import { readSettingsWithMetadata, writeSettings, } from "../core/store/settings.js";
@@ -181,7 +182,12 @@ function normalizeAction(value) {
         value === "export") {
         return value;
     }
-    throw new PmCliError(`Invalid config action "${value}". Allowed: get, set, list, export`, EXIT_CODE.USAGE);
+    throw createUnknownSubcommandError({
+        command_path: "config",
+        token: value.trim() || "<empty>",
+        allowed: ["export", "get", "list", "set"],
+        token_kind: "action",
+    });
 }
 function normalizeKey(value) {
     const key = CONFIG_KEY_BY_ALIAS[value];
@@ -1091,4 +1097,4 @@ export const _testOnlyConfigCommand = {
     normalizeWarnings,
 };
 //# sourceMappingURL=config.js.map
-//# debugId=2a186a29-9d21-5ebe-9c66-3e889253b15b
+//# debugId=a9a8d99c-df4e-55b3-81f5-27124d598c5f

package/dist/sdk/context/semantic-session-attribution.d.ts

@@ -0,0 +1,32 @@
+import { type AgentSemanticAttribution } from "../../core/session/session-state.js";
+import { readSettings } from "../../core/store/settings.js";
+/** Resolve an item's canonical parent lineage under a strict depth bound. */
+export declare function resolveSemanticLineageIds(pmRoot: string, settings: Awaited<ReturnType<typeof readSettings>>, itemId: string): Promise<string[]>;
+/** Record one successful claim and its bounded canonical lineage. */
+export declare function recordClaimSemanticAttribution(params: {
+    pmRoot: string;
+    settings: Awaited<ReturnType<typeof readSettings>>;
+    principal: string;
+    itemId: string;
+}): Promise<void>;
+/** Remove one released claim from the active semantic workset. */
+export declare function recordReleaseSemanticAttribution(params: {
+    pmRoot: string;
+    principal: string;
+    itemId: string;
+}): Promise<void>;
+/** Set or clear focused semantic work with canonical lineage evidence. */
+export declare function recordFocusSemanticAttribution(params: {
+    pmRoot: string;
+    settings: Awaited<ReturnType<typeof readSettings>>;
+    principal: string;
+    itemId?: string;
+}): Promise<void>;
+/** Public constants used by scale and negative-control tests. */
+export declare const SEMANTIC_ATTRIBUTION_LIMITS: {
+    readonly lineage_depth: 16;
+    readonly active_items: 64;
+    readonly evidence_rows: 32;
+};
+/** Convert bounded claim/focus evidence into normalized context affinity. */
+export declare function semanticAttributionAffinity(attribution: AgentSemanticAttribution | undefined): Readonly<Record<string, number>> | undefined;

package/dist/sdk/context/semantic-session-attribution.js

@@ -0,0 +1,83 @@
+/**
+ * @module sdk/semantic-session-attribution
+ *
+ * Maintains bounded claimed/focused lineage evidence used by automatic
+ * mutation provenance without scanning history or retaining prompt content.
+ */
+
+!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]="97c1e310-3cd9-5846-a54c-d019b0351541")}catch(e){}}();
+import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
+import { resolveItemTypeRegistry } from "../../core/item/type-registry.js";
+import { recordClaimedWorkAttribution, recordFocusedWorkAttribution, releaseClaimedWorkAttribution, } from "../../core/session/session-state.js";
+import { locateItem, readLocatedItem } from "../../core/store/item-store.js";
+const MAX_SEMANTIC_LINEAGE_DEPTH = 16;
+/** Resolve an item's canonical parent lineage under a strict depth bound. */
+export async function resolveSemanticLineageIds(pmRoot, settings, itemId) {
+    const typeToFolder = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations()).type_to_folder;
+    const lineage = [];
+    const seen = new Set();
+    let cursor = itemId;
+    while (cursor && lineage.length < MAX_SEMANTIC_LINEAGE_DEPTH) {
+        const normalized = cursor.trim().toLowerCase();
+        if (!normalized || seen.has(normalized))
+            break;
+        seen.add(normalized);
+        const located = await locateItem(pmRoot, cursor, settings.id_prefix, settings.item_format, typeToFolder);
+        if (!located)
+            break;
+        const loaded = await readLocatedItem(located, { schema: settings.schema });
+        lineage.push(loaded.document.metadata.id);
+        cursor = loaded.document.metadata.parent;
+    }
+    return lineage;
+}
+/** Record one successful claim and its bounded canonical lineage. */
+export async function recordClaimSemanticAttribution(params) {
+    await recordClaimedWorkAttribution({
+        pmRoot: params.pmRoot,
+        principal: params.principal,
+        itemId: params.itemId,
+        lineageIds: await resolveSemanticLineageIds(params.pmRoot, params.settings, params.itemId),
+    });
+}
+/** Remove one released claim from the active semantic workset. */
+export async function recordReleaseSemanticAttribution(params) {
+    await releaseClaimedWorkAttribution(params);
+}
+/** Set or clear focused semantic work with canonical lineage evidence. */
+export async function recordFocusSemanticAttribution(params) {
+    await recordFocusedWorkAttribution({
+        pmRoot: params.pmRoot,
+        principal: params.principal,
+        ...(params.itemId
+            ? {
+                itemId: params.itemId,
+                lineageIds: await resolveSemanticLineageIds(params.pmRoot, params.settings, params.itemId),
+            }
+            : {}),
+    });
+}
+/** Public constants used by scale and negative-control tests. */
+export const SEMANTIC_ATTRIBUTION_LIMITS = {
+    lineage_depth: MAX_SEMANTIC_LINEAGE_DEPTH,
+    active_items: 64,
+    evidence_rows: 32,
+};
+/** Convert bounded claim/focus evidence into normalized context affinity. */
+export function semanticAttributionAffinity(attribution) {
+    if (!attribution)
+        return undefined;
+    const affinity = {};
+    for (const itemId of attribution.active_item_ids)
+        affinity[itemId] = 1;
+    if (attribution.focused_item_id)
+        affinity[attribution.focused_item_id] = 1;
+    for (const evidence of attribution.evidence) {
+        const lineage = /^lineage:(.+)$/u.exec(evidence)?.[1];
+        if (lineage && affinity[lineage] === undefined)
+            affinity[lineage] = 0.75;
+    }
+    return Object.keys(affinity).length > 0 ? affinity : undefined;
+}
+//# sourceMappingURL=semantic-session-attribution.js.map
+//# debugId=97c1e310-3cd9-5846-a54c-d019b0351541

package/dist/sdk/context-intent-contracts.js

@@ -5,11 +5,11 @@
  * workspace configuration, and packages.
  */
 
-!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]="e48a306e-debb-5e66-ae9b-68bf17fa405f")}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]="fa03d543-ff0d-5556-8558-9bed82838a58")}catch(e){}}();
 import { AsyncLocalStorage } from "node:async_hooks";
 import { attachOutputOmissionReceipt } from "./output-projection.js";
 import { encodeQueryCursor } from "./pagination.js";
-import { applyReadOutputDimensions } from "./read-output-contracts.js";
+import { applyReadOutputDimensions, stabilizeReadOutputReceiptEstimates, } from "./read-output-contracts.js";
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 /** Built-in intent projections shared by CLI, SDK, MCP, and package authors. */
@@ -590,14 +590,55 @@ function collapseContinuationMetadata(options, result) {
     };
     return projected;
 }
+/** Return whether one projected value is a mutable output record. */
+function isOutputRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** Read one numeric fixed-point estimate from an optional receipt. */
+function receiptEstimate(value, field) {
+    if (!isOutputRecord(value))
+        return undefined;
+    return typeof value[field] === "number" ? value[field] : undefined;
+}
+/** Stabilize every token receipt after suppressing discovery-only metadata. */
+function stabilizeSuppressedRowContractReceipts(result, options) {
+    let finalized = result;
+    for (let iteration = 0; iteration < 8; iteration += 1) {
+        const previousContextEstimate = receiptEstimate(finalized.context_intent, "estimated_tokens");
+        const previousReadEstimate = receiptEstimate(finalized.read_output, "estimated_tokens");
+        const previousSessionEstimate = receiptEstimate(finalized.read_session, "spent_this_call_tokens");
+        if (isOutputRecord(finalized.context_intent)) {
+            updateContextIntentEstimate(finalized, finalized.context_intent);
+        }
+        finalized = stabilizeReadOutputReceiptEstimates(finalized, options);
+        if (receiptEstimate(finalized.context_intent, "estimated_tokens") ===
+            previousContextEstimate &&
+            receiptEstimate(finalized.read_output, "estimated_tokens") ===
+                previousReadEstimate &&
+            receiptEstimate(finalized.read_session, "spent_this_call_tokens") ===
+                previousSessionEstimate) {
+            break;
+        }
+    }
+    return finalized;
+}
 /** Attach universal row, omission, and optional intent-budget contracts in rendering order. */
 export function attachReadOutputContracts(command, options, result) {
     const disclosedResult = attachOutputOmissionReceipt(command, result);
-    return typeof disclosedResult === "object" &&
+    const projected = typeof disclosedResult === "object" &&
         disclosedResult !== null &&
         !Array.isArray(disclosedResult)
         ? applyReadOutputDimensions(command ?? "", options, collapseContinuationMetadata(options, attachContextIntentReceipt(command ?? "", options, disclosedResult)))
         : disclosedResult;
+    if (options.outputRowContract === true ||
+        options.output_row_contract === true ||
+        typeof projected !== "object" ||
+        projected === null ||
+        Array.isArray(projected) ||
+        !Object.hasOwn(projected, "row_contract")) {
+        return projected;
+    }
+    return stabilizeSuppressedRowContractReceipts(Object.fromEntries(Object.entries(projected).filter(([key]) => key !== "row_contract")), options);
 }
 //# sourceMappingURL=context-intent-contracts.js.map
-//# debugId=e48a306e-debb-5e66-ae9b-68bf17fa405f
+//# debugId=fa03d543-ff0d-5556-8558-9bed82838a58

package/dist/sdk/core-governance.d.ts

@@ -5,5 +5,7 @@
  * exposed by both the focused core entrypoint and the complete SDK barrel.
  */
 export { AGENT_PROVENANCE_DIMENSIONS, BUILTIN_HARNESS_SIGNAL_DESCRIPTORS, diagnoseAgentIdentity, detectAgentIdentity, detectHarnessIdentity, readAuthorEnvironment, registerHarnessSignalDescriptors, resolveAuthorIdentity, runWithHarnessDetectionSignals, runWithWorkspaceHarnessSignalDescriptors, writeAuthorEnvironment, type AgentClientInfo, type AgentModelSource, type AgentProvenance, type AgentProvenanceAbsenceReason, type AgentProvenanceObservation, type AgentProvenanceOutcome, type AuthorSource, type DetectedAgentIdentity, type DiagnosedAgentIdentity, type HarnessDetectionSignals, type HarnessSignalDescriptor, type ResolvedAuthorIdentity, } from "../core/shared/author.js";
-export { analyzeAgentProvenanceDescriptorCoverage, groupHistoryByEpisode, resolveHistoryEpisodeGroupIdentity, summarizeAgentProvenance, summarizeAgentModelProvenance, type AgentEpisodeGroup, type AgentModelProvenanceCoverage, type AgentProvenanceDimensionCoverage, type AgentProvenanceDescriptorCoverage, } from "./provenance.js";
+export { SEMANTIC_ATTRIBUTION_LIMITS, recordClaimSemanticAttribution, recordFocusSemanticAttribution, recordReleaseSemanticAttribution, resolveSemanticLineageIds, semanticAttributionAffinity, } from "./context/semantic-session-attribution.js";
+export { explainSourceTraceability, parseSourceLineRange, type SourceDecisionPath, type SourceLineRange, type SourceTraceabilityEvidence, type SourceTraceabilityExplanation, type SourceTraceabilityRationale, type SourceTraceabilityReceipt, } from "./traceability/source-traceability.js";
+export { analyzeAgentProvenanceDescriptorCoverage, evaluateSemanticAttributionCoverage, groupHistoryByEpisode, resolveHistoryEpisodeGroupIdentity, summarizeAgentProvenance, summarizeAgentModelProvenance, type AgentEpisodeGroup, type AgentModelProvenanceCoverage, type AgentProvenanceDimensionCoverage, type AgentProvenanceDescriptorCoverage, type AgentSemanticAttributionCoverage, type AgentSemanticAttributionCoverageGate, } from "./provenance.js";
 export { analyzeSdkCliParameterCompleteness, type SdkCliActionParameterCoverage, type SdkCliCompletenessContractSource, type SdkCliParameterCoverageEntry, type SdkCliParameterDisposition, } from "./cli-contracts.js";

package/dist/sdk/core-governance.js

@@ -5,9 +5,11 @@
  * exposed by both the focused core entrypoint and the complete 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]="7442357d-52b9-5461-9ac4-3acd898334da")}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]="d19cfa31-a02f-53a7-8685-5d169d6e051d")}catch(e){}}();
 export { AGENT_PROVENANCE_DIMENSIONS, BUILTIN_HARNESS_SIGNAL_DESCRIPTORS, diagnoseAgentIdentity, detectAgentIdentity, detectHarnessIdentity, readAuthorEnvironment, registerHarnessSignalDescriptors, resolveAuthorIdentity, runWithHarnessDetectionSignals, runWithWorkspaceHarnessSignalDescriptors, writeAuthorEnvironment, } from "../core/shared/author.js";
-export { analyzeAgentProvenanceDescriptorCoverage, groupHistoryByEpisode, resolveHistoryEpisodeGroupIdentity, summarizeAgentProvenance, summarizeAgentModelProvenance, } from "./provenance.js";
+export { SEMANTIC_ATTRIBUTION_LIMITS, recordClaimSemanticAttribution, recordFocusSemanticAttribution, recordReleaseSemanticAttribution, resolveSemanticLineageIds, semanticAttributionAffinity, } from "./context/semantic-session-attribution.js";
+export { explainSourceTraceability, parseSourceLineRange, } from "./traceability/source-traceability.js";
+export { analyzeAgentProvenanceDescriptorCoverage, evaluateSemanticAttributionCoverage, groupHistoryByEpisode, resolveHistoryEpisodeGroupIdentity, summarizeAgentProvenance, summarizeAgentModelProvenance, } from "./provenance.js";
 export { analyzeSdkCliParameterCompleteness, } from "./cli-contracts.js";
 //# sourceMappingURL=core-governance.js.map
-//# debugId=7442357d-52b9-5461-9ac4-3acd898334da
+//# debugId=d19cfa31-a02f-53a7-8685-5d169d6e051d

package/dist/sdk/core.d.ts

@@ -3,9 +3,10 @@
  *
  * Provides the stable item lifecycle client and universal project data types.
  */
-export { BASELINE_ITEM_FORMAT_VERSION, BUILTIN_ITEM_TYPE_VALUES, CONFIDENCE_TEXT_VALUES, CURRENT_ITEM_FORMAT_VERSION, DEPENDENCY_KIND_VALUES, EXIT_CODE, ISSUE_SEVERITY_VALUES, ITEM_TYPE_VALUES, PM_CLI_EXPECTED_ERROR_NAME, PmCliError, PmClient, RISK_VALUES, STATUS_VALUES, canonicalDocument, classifyItemFormatVersion, createPmCliExpectedError, effectiveItemFormatVersion, emptyImportedDocument, isPmCliExpectedError, normalizeItemFormatVersion, normalizeItemId, normalizeStatusInput, nowIso, runAction, serializeItemDocument, aggregate, append, claim, claimNext, close, comments, context, copy, create, deleteItem, deps, docs, files, filesDiscover, focus, get, graph, learnings, list, next, notes, release, restore, search, update, type AggregateOptions, type AggregateResult, type AggregateRow, type AppendCommandOptions, type AppendResult, type ClaimNextOptions, type ClaimResult, type CloseResult, type CommentsCommandOptions, type CommentsResult, type ContextOptions, type ContextResult, type CopyResult, type CreateResult, type Dependency, type DeleteResult, type DepsCommandOptions, type DepsResult, type DocsCommandOptions, type DocsResult, type FilesCommandOptions, type FilesDiscoverOptions, type FilesDiscoverResult, type FilesResult, type FocusResult, type GetOptions, type GetResult, type ItemFormatVersionScanEntry, type ItemFormatVersionScanResult, type ItemFormatVersionStatus, type LearningsCommandOptions, type LearningsResult, type ListOptions, type ListResult, type NextOptions, type NextResult, type NotesCommandOptions, type NotesResult, type PmActionInput, type PmActionName, type PmActionOptions, type PmClientOptions, type ReleaseResult, type RestoreResult, type SearchOptions, type SearchResult, type UpdateResult, } from "./runtime.js";
+export { BASELINE_ITEM_FORMAT_VERSION, BUILTIN_ITEM_TYPE_VALUES, CONFIDENCE_TEXT_VALUES, CURRENT_ITEM_FORMAT_VERSION, DEPENDENCY_KIND_VALUES, EXIT_CODE, ISSUE_SEVERITY_VALUES, ITEM_TYPE_VALUES, PM_CLI_EXPECTED_ERROR_NAME, PmCliError, PmClient, RISK_VALUES, STATUS_VALUES, canonicalDocument, classifyItemFormatVersion, createPmCliExpectedError, effectiveItemFormatVersion, emptyImportedDocument, isPmCliExpectedError, normalizeItemFormatVersion, normalizeItemId, normalizeStatusInput, nowIso, runAction, serializeItemDocument, aggregate, append, claim, claimNext, close, comments, context, copy, create, deleteItem, deps, docs, files, filesDiscover, focus, get, graph, learnings, list, next, notes, release, restore, search, update, type AggregateOptions, type AggregateResult, type AggregateRow, type AssuranceActionInput, type AssuranceActionResult, type AppendCommandOptions, type AppendResult, type ClaimNextOptions, type ClaimResult, type CloseResult, type CommentsCommandOptions, type CommentsResult, type ContextOptions, type ContextResult, type CopyResult, type CreateResult, type Dependency, type DeleteResult, type DepsCommandOptions, type DepsResult, type DocsCommandOptions, type DocsResult, type FilesCommandOptions, type FilesDiscoverOptions, type FilesDiscoverResult, type FilesResult, type FocusResult, type GetOptions, type GetResult, type ItemFormatVersionScanEntry, type ItemFormatVersionScanResult, type ItemFormatVersionStatus, type LearningsCommandOptions, type LearningsResult, type ListOptions, type ListResult, type NextOptions, type NextResult, type NotesCommandOptions, type NotesResult, type PmActionInput, type PmActionName, type PmActionOptions, type PmClientOptions, type ReleaseResult, type RestoreResult, type SearchOptions, type SearchResult, type UpdateResult, } from "./runtime.js";
 export * from "./core-governance.js";
 export * from "./agent-session-context.js";
+export { isAlreadyClaimedError } from "./lifecycle/claim.js";
 export { PM_READ_OUTPUT_DIMENSIONS, PM_READ_OUTPUT_OPTION_FLAGS, PM_READ_OUTPUT_COMPOSITION_OPTION_FLAGS, PM_READ_OUTPUT_SURFACE_CONTRACTS, applyReadOutputDimensions, isReadOutputBudgetExceeded, resolveReadOutputDimensions, resolveReadOutputEncoding, resolveReadOutputSurface, validateReadOutputOptions, } from "./read-output-contracts.js";
 export { applyReadOutputSessionReferences, attachReadOutputSessionReceipt, parseReadOutputSession, readOutputSessionRemainingTokens, } from "./read-output-session.js";
 export type { PmReadOutputBudgetExceeded, PmReadOutputDimension, PmReadOutputLegacyAlias, PmReadOutputOptions, PmReadOutputReceipt, PmReadOutputResult, PmReadOutputResultFor, PmReadOutputSurface, PmReadOutputSurfaceContract, } from "./read-output-contracts.js";

package/dist/sdk/core.js

@@ -4,11 +4,12 @@
  * Provides the stable item lifecycle client and universal project data types.
  */
 
-!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]="54d31df7-e708-585d-9fb2-3c5ddfcc6138")}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]="2e0a2422-64c7-5ad3-867c-04479171fa27")}catch(e){}}();
 export { BASELINE_ITEM_FORMAT_VERSION, BUILTIN_ITEM_TYPE_VALUES, CONFIDENCE_TEXT_VALUES, CURRENT_ITEM_FORMAT_VERSION, DEPENDENCY_KIND_VALUES, EXIT_CODE, ISSUE_SEVERITY_VALUES, ITEM_TYPE_VALUES, PM_CLI_EXPECTED_ERROR_NAME, PmCliError, PmClient, RISK_VALUES, STATUS_VALUES, canonicalDocument, classifyItemFormatVersion, createPmCliExpectedError, effectiveItemFormatVersion, emptyImportedDocument, isPmCliExpectedError, normalizeItemFormatVersion, normalizeItemId, normalizeStatusInput, nowIso, runAction, serializeItemDocument, aggregate, append, claim, claimNext, close, comments, context, copy, create, deleteItem, deps, docs, files, filesDiscover, focus, get, graph, learnings, list, next, notes, release, restore, search, update, } from "./runtime.js";
 export * from "./core-governance.js";
 export * from "./agent-session-context.js";
+export { isAlreadyClaimedError } from "./lifecycle/claim.js";
 export { PM_READ_OUTPUT_DIMENSIONS, PM_READ_OUTPUT_OPTION_FLAGS, PM_READ_OUTPUT_COMPOSITION_OPTION_FLAGS, PM_READ_OUTPUT_SURFACE_CONTRACTS, applyReadOutputDimensions, isReadOutputBudgetExceeded, resolveReadOutputDimensions, resolveReadOutputEncoding, resolveReadOutputSurface, validateReadOutputOptions, } from "./read-output-contracts.js";
 export { applyReadOutputSessionReferences, attachReadOutputSessionReceipt, parseReadOutputSession, readOutputSessionRemainingTokens, } from "./read-output-session.js";
 //# sourceMappingURL=core.js.map
-//# debugId=54d31df7-e708-585d-9fb2-3c5ddfcc6138
+//# debugId=2e0a2422-64c7-5ad3-867c-04479171fa27

package/dist/sdk/error-code-catalog.d.ts

@@ -8,6 +8,17 @@
 export type PmErrorCodeStability = "provisional" | "stable";
 /** Semantic process-exit class shared by shell and SDK consumers. */
 export type PmErrorCodeClass = "generic_failure" | "usage" | "not_found" | "conflict" | "dependency_failed";
+/** One externally observable refusal state and its executable entrypoint probe. */
+export interface PmRefusalStateContract {
+    /** Stable semantic state owned by the error code. */
+    state: string;
+    /** Stable probe identifier implemented by the entrypoint conformance suite. */
+    probe_id: string;
+    /** Public command roots through which the state must remain reachable. */
+    entrypoints: string[];
+    /** Exit class expected when the probe reaches the state. */
+    expected_exit_class: PmErrorCodeClass;
+}
 /** Stable shell exit-code taxonomy shared by every structured error. */
 export declare const PM_ERROR_CODE_EXIT_CLASS_CONTRACTS: readonly [{
     readonly exit_code: 1;
@@ -47,6 +58,8 @@ export interface PmErrorCodeContract {
     canonical_code?: string;
     /** Stable compatibility spellings that resolve to this canonical code. */
     aliases?: string[];
+    /** Observable states this code claims, each backed by a real-entrypoint probe. */
+    owned_states?: PmRefusalStateContract[];
 }
 /** Validate, normalize, sort, and freeze an error-code catalog. */
 export declare function definePmErrorCodeCatalog(declarations: readonly PmErrorCodeContract[]): readonly PmErrorCodeContract[];

package/dist/sdk/error-code-catalog.js

@@ -6,7 +6,7 @@
  */
 /** Stable shell exit-code taxonomy shared by every structured error. */
 
-!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]="393243a5-dd90-52c1-a9c1-588fd33f8b6a")}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]="c76fa303-6672-5c1e-9cf5-3a08bd3a7814")}catch(e){}}();
 export const PM_ERROR_CODE_EXIT_CLASS_CONTRACTS = [
     { exit_code: 1, class: "generic_failure" },
     { exit_code: 2, class: "usage" },
@@ -21,6 +21,34 @@ function normalizeContractList(values) {
         ...new Set(values.map((value) => value.trim()).filter(Boolean)),
     ].sort();
 }
+function normalizeOwnedStates(states) {
+    if (!states)
+        return [];
+    const seenStates = new Set();
+    const seenProbes = new Set();
+    return states
+        .map((state) => {
+        const normalizedState = state.state.trim();
+        const probeId = state.probe_id.trim();
+        const entrypoints = normalizeContractList(state.entrypoints);
+        if (!/^[a-z][a-z0-9_]*$/.test(normalizedState) ||
+            !/^[a-z][a-z0-9-]*$/.test(probeId) ||
+            entrypoints.length === 0 ||
+            seenStates.has(normalizedState) ||
+            seenProbes.has(probeId)) {
+            throw new TypeError("Invalid pm refusal state contract");
+        }
+        seenStates.add(normalizedState);
+        seenProbes.add(probeId);
+        return {
+            state: normalizedState,
+            probe_id: probeId,
+            entrypoints,
+            expected_exit_class: state.expected_exit_class,
+        };
+    })
+        .sort((left, right) => left.state.localeCompare(right.state));
+}
 function isValidNormalizedErrorCodeContract(declaration, sources, emittingCommands, canonicalCode, aliases) {
     return ![
         [1, 2, 3, 4, 5].includes(declaration.exit_code),
@@ -86,9 +114,13 @@ export function definePmErrorCodeCatalog(declarations) {
         const emittingCommands = normalizeContractList(declaration.emitting_commands);
         const canonicalCode = (declaration.canonical_code ?? code).trim();
         const aliases = normalizeContractList(declaration.aliases ?? []);
+        const ownedStates = normalizeOwnedStates(declaration.owned_states);
         if (!isValidNormalizedErrorCodeContract(declaration, sources, emittingCommands, canonicalCode, aliases)) {
             throw new TypeError(`Invalid pm error code contract: ${code}`);
         }
+        if (ownedStates.some((state) => state.expected_exit_class !== declaration.class)) {
+            throw new TypeError(`Invalid pm refusal state exit class: ${code}`);
+        }
         return Object.freeze({
             ...declaration,
             code,
@@ -98,6 +130,7 @@ export function definePmErrorCodeCatalog(declarations) {
             emitting_commands: emittingCommands,
             canonical_code: canonicalCode,
             aliases,
+            owned_states: ownedStates,
         });
     });
     validateErrorCodeAliases(normalized);
@@ -118,4 +151,4 @@ export function resolvePmErrorCodeContract(code, catalog) {
     return contract;
 }
 //# sourceMappingURL=error-code-catalog.js.map
-//# debugId=393243a5-dd90-52c1-a9c1-588fd33f8b6a
+//# debugId=c76fa303-6672-5c1e-9cf5-3a08bd3a7814