@unbrained/pm-cli 2026.8.4 → 2026.8.6

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]="6d814d40-522c-5bcc-b404-7e6511cf999a")}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]="34fc99f6-45e5-53f2-96eb-767d50ed449c")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { resolveItemTypeRegistry } from "../../core/item/type-registry.js";
@@ -35,6 +35,7 @@ import { readSettingsWithMetadata } from "../../core/store/settings.js";
 import { buildRemediationMap } from "../../core/diagnostics/remediation.js";
 import { scanHistoryAuthorAttribution, } from "../author-attribution.js";
 import { readManagedExtensionState } from "../extension.js";
+import { applyStoredExtensionMigrationState } from "../extension/migrations.js";
 import { buildCapabilityContractMetadata, buildRegistrationCollisionRemediation, collectUnknownCapabilityGuidance, } from "../extension/doctor.js";
 import { scanStaleInProgressItems, } from "./stale-work.js";
 import { scanTrackedRuntimeCache } from "./tracked-runtime-cache.js";
@@ -605,6 +606,7 @@ async function buildExtensionCheck(pmRoot, settings, noExtensionsFlag) {
         readManagedExtensionState(loadResult.roots.project),
         readManagedExtensionState(loadResult.roots.global),
     ]);
+    await applyStoredExtensionMigrationState(pmRoot, activationResult.registrations.migrations);
     const migrationStatus = summarizeMigrationStatuses(activationResult.registrations.migrations);
     const activationDetails = {
         failed: activationResult.failed,
@@ -695,6 +697,13 @@ async function buildExtensionCheck(pmRoot, settings, noExtensionsFlag) {
                 warnings: extensionWarnings,
                 activation: activationDetails,
                 triage: extensionTriage,
+                ...(migrationStatus.summary.pending_count > 0
+                    ? {
+                        remediation_map: {
+                            extension_migration_pending: "pm extension migrate --project",
+                        },
+                    }
+                    : {}),
                 capability_contract: capabilityContract,
                 capability_guidance: capabilityGuidance,
             },
@@ -1955,4 +1964,4 @@ export const _testOnlyHealthCommand = {
     warningCode,
 };
 //# sourceMappingURL=health.js.map
-//# debugId=6d814d40-522c-5bcc-b404-7e6511cf999a
+//# debugId=34fc99f6-45e5-53f2-96eb-767d50ed449c

package/dist/sdk/graph/governance.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]="251ae2b0-10f4-528d-86b0-d224b126f8eb")}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]="76fa19c7-a421-5026-8de8-450285987c4e")}catch(e){}}();
 import { isTransitiveKind, orientTransitiveEdge, transitiveFamilyKey, } from "./analytics.js";
 /** Default bounded sample size applied to every finding family. */
 const DEFAULT_MAX_SAMPLE_SIZE = 25;
@@ -195,7 +195,7 @@ function collectOrderingFindings(assembly, nodeStates, isBlocked, maxSampleSize)
             return predecessorState === undefined || !predecessorState.terminal;
         }))
         .map((state) => state.id);
-    appendFinding(findings, staleLifecycleBlocks, maxSampleSize, "stale_lifecycle_block", "warning", "A blocked lifecycle status must be backed by at least one open ordering predecessor.", (count) => `${count} status-blocked item(s) with no open blocker edge`, "Re-open the missing prerequisite as an edge, or move the item back to an active status.");
+    appendFinding(findings, staleLifecycleBlocks, maxSampleSize, "stale_lifecycle_block", "warning", "A blocked lifecycle status must be backed by at least one open ordering predecessor.", (count) => `${count} status-blocked item(s) with no open blocker edge`, 'Add a local blocker edge, declare an external blocker with --dep "id=<external-ref>,kind=blocked_by,source_kind=external", or move the item back to an active status.');
     return findings;
 }
 /** Format one duplicate-edge group as a compact deterministic evidence string. */
@@ -466,4 +466,4 @@ export function diffRelationshipAuditSnapshots(baseline, current) {
     };
 }
 //# sourceMappingURL=governance.js.map
-//# debugId=251ae2b0-10f4-528d-86b0-d224b126f8eb
+//# debugId=76fa19c7-a421-5026-8de8-450285987c4e

package/dist/sdk/graph/remediation.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]="1f26594a-5843-556e-90b4-d733733f8828")}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]="9b8e22ad-6268-515d-994e-6b98a062ba93")}catch(e){}}();
 import { findRedundantRelationshipEdges } from "./analytics.js";
 import { auditWorkspaceRelationshipGraph, collectDuplicateRelationshipEdgeGroups, formatDuplicateEdgeGroup, } from "./governance.js";
 /** Per-finding-code operation template applied to every sampled subject. */
@@ -55,7 +55,7 @@ const FINDING_STEP_TEMPLATES = {
     stale_lifecycle_block: {
         op: "investigate",
         confidence: "medium",
-        rationale: "Re-open the missing prerequisite as an ordering edge, or move the item back to an active status; only the holder's owner knows which is true.",
+        rationale: 'Add a local ordering edge, declare an external blocker with --dep "id=<external-ref>,kind=blocked_by,source_kind=external", or move the item back to an active status; only the holder\'s owner knows which is true.',
     },
     isolated_active_node: {
         op: "investigate",
@@ -155,4 +155,4 @@ export function planRelationshipRemediation(assembly, options = {}) {
     };
 }
 //# sourceMappingURL=remediation.js.map
-//# debugId=1f26594a-5843-556e-90b4-d733733f8828
+//# debugId=9b8e22ad-6268-515d-994e-6b98a062ba93

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]="ab1a6d49-f6e6-5a02-a948-8fd6e9be265a")}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]="0fbc54bf-3321-5c73-a351-5db01aab5544")}catch(e){}}();
 import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
 import { pathExists } from "../../core/fs/fs-utils.js";
 import { isTerminalStatus } from "../../core/item/status.js";
@@ -423,9 +423,7 @@ function runGraphSlack(invocation) {
 /** Execute the structural-centrality ranking subcommand. */
 function runGraphCentrality(invocation) {
     const limit = invocation.limit ?? DEFAULT_SAMPLE_LIMIT;
-    const result = computeRelationshipCentrality(invocation.assembly.graph, {
-        ...(invocation.kinds === undefined ? {} : { kinds: invocation.kinds }),
-    });
+    const result = computeRelationshipCentrality(invocation.assembly.graph, invocation.kinds === undefined ? {} : { kinds: invocation.kinds });
     const analysis = result.value;
     return {
         subcommand: "centrality",
@@ -454,9 +452,7 @@ function runGraphCentrality(invocation) {
 /** Execute the articulation-point and bridge (cut-structure) subcommand. */
 function runGraphArticulation(invocation) {
     const limit = invocation.limit ?? DEFAULT_SAMPLE_LIMIT;
-    const result = findRelationshipCutStructure(invocation.assembly.graph, {
-        ...(invocation.kinds === undefined ? {} : { kinds: invocation.kinds }),
-    });
+    const result = findRelationshipCutStructure(invocation.assembly.graph, invocation.kinds === undefined ? {} : { kinds: invocation.kinds });
     const { articulationPoints, bridges } = result.value;
     return {
         subcommand: "articulation",
@@ -717,4 +713,4 @@ export async function runGraph(subcommandRaw, id, target, options, global) {
     return attachGraphProjection(value, invocation.summary, "result_rows");
 }
 //# sourceMappingURL=run.js.map
-//# debugId=ab1a6d49-f6e6-5a02-a948-8fd6e9be265a
+//# debugId=0fbc54bf-3321-5c73-a351-5db01aab5544

package/dist/sdk/index.d.ts

@@ -20,7 +20,10 @@ export { quoteCommandArg, quoteWindowsCommandArg, renderPmCommand, } from "./com
 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";
-export { runExtension } from "./extension.js";
+export { runExtension, type ExtensionCommandAction, } from "./extension.js";
+export { resolveExtensionInstallSourceIdentity, type ExtensionInstallSourceCandidate, type ExtensionInstallSourceResolution, type ExtensionInstallSourceSelection, type ResolvedExtensionInstallSource, } from "./extension/source-resolution.js";
+export { applyStoredExtensionMigrationState, readExtensionMigrationState, resolveExtensionMigrationStatePath, runExtensionMigrateAction, runExtensionMigrations, type ExtensionMigrationActionContext, type ExtensionMigrationOutcomeStatus, type ExtensionMigrationReceipt, type ExtensionMigrationRunResult, type ExtensionMigrationState, type ExtensionMigrationStateEntry, type RunExtensionMigrationsOptions, } from "./extension/migrations.js";
+export { findInstalledNpmPackageCandidate, type GithubInstallSource, type InstalledNpmPackageCandidate, type InstallSource, type LocalInstallSource, type NpmInstallSource, type ResolvedInstallSource, } from "./extension/install-sources.js";
 export { buildExtensionDescribeResult, renderExtensionDescribeMarkdown, type ExtensionCommandClaimant, type ExtensionCommandOwnership, type ExtensionDescribeActivationStatus, type ExtensionDescribeResult, type ExtensionSurfaceDescription, } from "./extension/describe.js";
 export { runEvent, runMeet, runRemind, type MeetingEventShortcutOptions, type ReminderShortcutOptions, type SchedulingShortcutCommonOptions, } from "./scheduling-shortcuts.js";
 export { createExtensionCommandSdk } from "./extension-command-context.js";
@@ -45,7 +48,7 @@ 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_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, 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, definePmCommandOutputBudget, estimatePmOutputTokens, 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, 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 "./compile-cache.js";
@@ -83,6 +86,7 @@ export * from "./pagination.js";
 export * from "./query/item-filter-options.js";
 export * from "./query/parsers.js";
 export * from "./output.js";
+export * from "./output-contracts.js";
 export * from "./relationship-analytics.js";
 export * from "./relationship-context.js";
 export * from "./relationship-history.js";
@@ -118,6 +122,7 @@ export { runUpgrade } from "./governance/upgrade.js";
 export { PLAN_SHOW_DEPTH_VALUES, PLAN_SUBCOMMANDS, PLAN_TEMPLATE_NAMES, } from "./lifecycle/plan.js";
 export * from "./define.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, acquireLock, appendHistoryEntry, canonicalDocument, classifyItemFormatVersion, clearWorkspaceContractsCache, commitImportedItem, createHistoryEntry, createPmCliExpectedError, effectiveItemFormatVersion, emptyImportedDocument, ensureTrackerInitialized, generateItemId, getActiveExtensionRegistrations, getContracts, getHistoryPath, getItemPath, getSettingsPath, getWorkspaceContracts, isPmCliExpectedError, isTimestampLiteral, listAllItemMetadata, loadCreateTemplateOptions, locateItem, normalizeItemMetadata, normalizeItemFormatVersion, normalizeItemId, normalizeRawItemId, normalizeStatusInput, nowIso, parseTags, pathExists, readBooleanOption, readCsvListOption, readFileIfExists, readLocatedItem, readRequiredString, readSettings, readStringOption, removeFileIfExists, renderCalendarMarkdown, renderCalendarToon, renderGuideMarkdown, resolveCalendarOutputFormat, resolveGuideOutputFormat, resolveItemTypeRegistry, resolveImplicitPmRoot, resolvePmRoot, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, runAction, runActiveOnReadHooks, runActiveOnWriteHooks, runCalendar, runCompletion, runGuide, runList, runReindex, runSearch, runTemplatesList, runTemplatesSave, runTemplatesShow, runTestRunsList, runTestRunsLogs, runTestRunsResume, runTestRunsStatus, runTestRunsStop, scanItemFormatVersions, selectImportAuthor, serializeItemDocument, splitFrontMatter, toEstimatedMinutesValue, toImportBoolean, toImportConfidence, toImportInteger, toImportLinkedDocs, toImportLinkedFiles, toImportLinkedTests, toImportLogEntries, toImportNormalizedEnum, toImportNumberMap, toImportPriority, toImportStatus, toImportStringList, toImportStringMap, toImportTags, toNonEmptyImportString, writeFileAtomic, aggregate, append, claim, claimNext, close, closeTask, comments, config, context, copy, create, deleteItem, deps, docs, duplicates, extension, extensionActivate, extensionDeactivate, extensionList, files, filesDiscover, filesLookup, focus, gc, get, graph, health, historyCompact, historyCompactBulk, historyRedact, historyRepair, historyRepairAll, init, learnings, list, next, notes, packageActivate, packageCatalog, packageDeactivate, packageDescribe, packageDoctor, packageInstall, packageLifecycle, packageList, packageManage, packageReload, packageUninstall, pauseTask, profile, profileApply, profileLint, profileList, profileShow, release, restore, schema, schemaAddField, schemaAddStatus, schemaAddType, schemaApplyPreset, schemaInferTypes, schemaList, schemaListFields, schemaRemapStatus, schemaRemoveField, schemaRemoveStatus, schemaRemoveType, schemaShow, schemaShowField, schemaShowStatus, schemaRenameField, schemaRenameType, search, startTask, stats, update, upgrade, validate, type AggregateOptions, type AggregateResult, type AggregateRow, type AppendCommandOptions, type AppendResult, type BlockerEntry, type CalendarOptions, type CalendarResult, type ClaimResult, type CloseResult, type CloseTaskResult, type CommitImportedItemParams, type CommitImportedItemResult, type CommentsCommandOptions, type CommentsResult, type ConfigCommandOptions, type ConfigResult, type CompletionResult, type CompletionShell, type ContractsCommandOptions, type ContractsResult, type ContextFocusItem, type ContextOptions, type ContextOutputFormat, type ContextResult, type CopyResult, type CreatePmCliExpectedErrorOptions, type CreateResult, type CreateTemplateOptions, type Dependency, type DeleteResult, type DepsCommandOptions, type DepsResult, type DocsCommandOptions, type DocsResult, type ExtensionCommandOptions, type ExtensionCommandResult, type FilesCommandOptions, type FilesDiscoverOptions, type FilesDiscoverResult, type FilesLookupOptions, type FilesLookupResult, type FilesResult, type FocusResult, type GcCommandOptions, type GcResult, type GetContractsOptions, type GetOptions, type GetResult, type GuideDepth, type GuideOptions, type GuideOutputFormat, type GuideResult, type HealthResult, type ImportLinkedScope, type InitCommandOptions, type InitResult, type ItemFormatVersionScanEntry, type ItemFormatVersionScanResult, type ItemFormatVersionStatus, type LearningsCommandOptions, type LearningsResult, type LinkedDoc, type LinkedFile, type LinkedTest, type ListedItem, type ListCompactResult, type ListFullResult, type ListOptions, type ListProjectedItem, type ListProjectedItemCore, type ListResult, type ListResultItem, type ListSortField, type ListSortOrder, type ListTreeItem, type ListTreeMetadata, type ListVerboseResult, type LogNote, type NextActionableItem, type NextBlockerRef, type NextOptions, type NextOutputFormat, type NextRecommendation, type NextResult, type NotesCommandOptions, type NotesResult, type PackageCommandOptions, type PackageCommandResult, type PauseTaskResult, type PmActionInput, type PmActionName, type PmActionOptions, type PmClientCloseActionOptions, type PmClientFullMutationOptions, type PmClientMutationOptions, type PmClientOptions, type PmClientRunArgs, type PmCliExpectedError, type ProfileApplyCommandOptions, type ProfileApplyResult, type ProfileLintResult, type ProfileListResult, type ProfileResult, type ProfileShowResult, type ProfileSubcommand, type ReindexOptions, type ReindexResult, type ReleaseResult, type RestoreResult, type RunHealthOptions, type SchemaAddFieldCommandOptions, type SchemaAddFieldResult, type SchemaAddStatusCommandOptions, type SchemaAddStatusResult, type SchemaAddTypeCommandOptions, type SchemaAddTypeInferCommandOptions, type SchemaAddTypeInferResult, type SchemaAddTypeResult, type SchemaApplyPresetCommandOptions, type SchemaApplyPresetResult, type SchemaInspectResult, type SchemaListFieldsResult, type SchemaListResult, type SchemaRemoveFieldCommandOptions, type SchemaRemoveFieldResult, type SchemaRemoveStatusCommandOptions, type SchemaRemoveStatusResult, type SchemaRemoveTypeCommandOptions, type SchemaRemoveTypeResult, type SchemaShowFieldResult, type SchemaShowResult, type SchemaShowStatusResult, type SchemaResult, type RunSchemaEvolutionMigrationOptions, type SchemaEvolutionMigrationRequest, type SchemaEvolutionMigrationResult, type SchemaSubcommand, type SearchCompactResult, type SearchHit, type SearchHitHighlight, type SearchMatchMode, type SearchOptions, type ClaimNextOptions, type SearchResult, type SearchResultItem, type SearchVerboseResult, type StartTaskResult, type StatsCommandOptions, type StatsResult, type TemplatesListResult, type TemplatesSaveResult, type TemplatesShowResult, type TestRunsListCommandOptions, type TestRunsLogsCommandOptions, type TestRunsResumeCommandOptions, type TestRunsStopCommandOptions, type ToImportLinkedArtifactsOptions, type ToImportLinkedTestsOptions, type ToImportLogEntriesOptions, type UpdateResult, type UpgradeCommandOptions, type UpgradeResult, type ValidateCommandOptions, type ValidateResult, type WorkspaceContracts, type WorkspaceContractsOptions, type WorkspaceExtensionCommandContract, type WorkspaceFieldContract, } from "./runtime.js";
+export { extensionMigrate, packageMigrate } from "./package-migrations.js";
 export { CONTEXT_OUTPUT_VALUES, NEXT_OUTPUT_VALUES, PM_GITIGNORE_END, PM_GITIGNORE_START, analyzeSdkActionCoverage, ensurePmGitignore, getPmGitignoreBlock, closeItem, runAggregate, runClose, runCopy, runContext, runDelete, runFocus, runGet, runNext, runRestore, runUpdate, type CloseCommandOptions, type CopyOptions, type DeleteCommandOptions, type EnsurePmGitignoreResult, type HierarchyChild, type HierarchyNode, type HotFile, type FocusOptions, type ImportPriorityValue, type ProgressEntry, type RecentContextItem, type RestoreCommandOptions, type SdkActionCoverageRow, type StaleEntry, type TestHealthSummary, type UpdateCommandOptions, type WorkloadEntry, } from "./runtime.js";
 export { runStats } from "./stats.js";
 export { DEFAULT_EVAL_QUERIES_RELATIVE_PATH, EVAL_QUERY_SET_CONTRACT, EVAL_QUERY_SET_EXAMPLE, EVAL_QUERY_SET_SCHEMA_ID, parseEvalQuerySet, runEval, type EvalOptions, type EvalQueryReport, type EvalResult, } from "./eval.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]="d5bccdd6-a532-570a-b545-f316abaaf70b")}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]="4e336574-f00e-5296-a55f-7f27a264188c")}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, resolveAnnotationInput, resolveAnnotationIndex, runAnnotationCommand, wrapOwnershipConflict, } from "./annotations.js";
@@ -21,7 +21,10 @@ export { quoteCommandArg, quoteWindowsCommandArg, renderPmCommand, } from "./com
 export { runGc, } from "./governance/gc.js";
 export { _testOnlyHealthCommand, runHealth, } from "./governance/health.js";
 export { _testOnlyValidateCommand, projectValidateCounts, runValidate, } from "./governance/validate.js";
-export { runExtension } from "./extension.js";
+export { runExtension, } from "./extension.js";
+export { resolveExtensionInstallSourceIdentity, } from "./extension/source-resolution.js";
+export { applyStoredExtensionMigrationState, readExtensionMigrationState, resolveExtensionMigrationStatePath, runExtensionMigrateAction, runExtensionMigrations, } from "./extension/migrations.js";
+export { findInstalledNpmPackageCandidate, } from "./extension/install-sources.js";
 export { buildExtensionDescribeResult, renderExtensionDescribeMarkdown, } from "./extension/describe.js";
 export { runEvent, runMeet, runRemind, } from "./scheduling-shortcuts.js";
 export { createExtensionCommandSdk } from "./extension-command-context.js";
@@ -44,7 +47,7 @@ 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_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, 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, definePmCommandOutputBudget, estimatePmOutputTokens, 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, 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 "./compile-cache.js";
 export * from "./context-relevance.js";
@@ -81,6 +84,7 @@ export * from "./pagination.js";
 export * from "./query/item-filter-options.js";
 export * from "./query/parsers.js";
 export * from "./output.js";
+export * from "./output-contracts.js";
 export * from "./relationship-analytics.js";
 export * from "./relationship-context.js";
 export * from "./relationship-history.js";
@@ -110,6 +114,7 @@ export { runUpgrade } from "./governance/upgrade.js";
 export { PLAN_SHOW_DEPTH_VALUES, PLAN_SUBCOMMANDS, PLAN_TEMPLATE_NAMES, } from "./lifecycle/plan.js";
 export * from "./define.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, acquireLock, appendHistoryEntry, canonicalDocument, classifyItemFormatVersion, clearWorkspaceContractsCache, commitImportedItem, createHistoryEntry, createPmCliExpectedError, effectiveItemFormatVersion, emptyImportedDocument, ensureTrackerInitialized, generateItemId, getActiveExtensionRegistrations, getContracts, getHistoryPath, getItemPath, getSettingsPath, getWorkspaceContracts, isPmCliExpectedError, isTimestampLiteral, listAllItemMetadata, loadCreateTemplateOptions, locateItem, normalizeItemMetadata, normalizeItemFormatVersion, normalizeItemId, normalizeRawItemId, normalizeStatusInput, nowIso, parseTags, pathExists, readBooleanOption, readCsvListOption, readFileIfExists, readLocatedItem, readRequiredString, readSettings, readStringOption, removeFileIfExists, renderCalendarMarkdown, renderCalendarToon, renderGuideMarkdown, resolveCalendarOutputFormat, resolveGuideOutputFormat, resolveItemTypeRegistry, resolveImplicitPmRoot, resolvePmRoot, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, runAction, runActiveOnReadHooks, runActiveOnWriteHooks, runCalendar, runCompletion, runGuide, runList, runReindex, runSearch, runTemplatesList, runTemplatesSave, runTemplatesShow, runTestRunsList, runTestRunsLogs, runTestRunsResume, runTestRunsStatus, runTestRunsStop, scanItemFormatVersions, selectImportAuthor, serializeItemDocument, splitFrontMatter, toEstimatedMinutesValue, toImportBoolean, toImportConfidence, toImportInteger, toImportLinkedDocs, toImportLinkedFiles, toImportLinkedTests, toImportLogEntries, toImportNormalizedEnum, toImportNumberMap, toImportPriority, toImportStatus, toImportStringList, toImportStringMap, toImportTags, toNonEmptyImportString, writeFileAtomic, aggregate, append, claim, claimNext, close, closeTask, comments, config, context, copy, create, deleteItem, deps, docs, duplicates, extension, extensionActivate, extensionDeactivate, extensionList, files, filesDiscover, filesLookup, focus, gc, get, graph, health, historyCompact, historyCompactBulk, historyRedact, historyRepair, historyRepairAll, init, learnings, list, next, notes, packageActivate, packageCatalog, packageDeactivate, packageDescribe, packageDoctor, packageInstall, packageLifecycle, packageList, packageManage, packageReload, packageUninstall, pauseTask, profile, profileApply, profileLint, profileList, profileShow, release, restore, schema, schemaAddField, schemaAddStatus, schemaAddType, schemaApplyPreset, schemaInferTypes, schemaList, schemaListFields, schemaRemapStatus, schemaRemoveField, schemaRemoveStatus, schemaRemoveType, schemaShow, schemaShowField, schemaShowStatus, schemaRenameField, schemaRenameType, search, startTask, stats, update, upgrade, validate, } from "./runtime.js";
+export { extensionMigrate, packageMigrate } from "./package-migrations.js";
 export { CONTEXT_OUTPUT_VALUES, NEXT_OUTPUT_VALUES, PM_GITIGNORE_END, PM_GITIGNORE_START, analyzeSdkActionCoverage, ensurePmGitignore, getPmGitignoreBlock, closeItem, runAggregate, runClose, runCopy, runContext, runDelete, runFocus, runGet, runNext, runRestore, runUpdate, } from "./runtime.js";
 export { runStats } from "./stats.js";
 export { DEFAULT_EVAL_QUERIES_RELATIVE_PATH, EVAL_QUERY_SET_CONTRACT, EVAL_QUERY_SET_EXAMPLE, EVAL_QUERY_SET_SCHEMA_ID, parseEvalQuerySet, runEval, } from "./eval.js";
@@ -128,4 +133,4 @@ export * from "./governance.js";
 export * from "./query.js";
 export * from "./testing.js";
 //# sourceMappingURL=index.js.map
-//# debugId=d5bccdd6-a532-570a-b545-f316abaaf70b
+//# debugId=4e336574-f00e-5296-a55f-7f27a264188c

package/dist/sdk/item-transaction.d.ts

@@ -33,8 +33,17 @@ export interface BulkItemCloseMutation {
     /** Close options forwarded to the public `close` runtime primitive. */
     options?: PmClientFullMutationOptions;
 }
+/** One atomic claim release inside a bulk mutation batch. */
+export interface BulkItemReleaseMutation {
+    /** Discriminates the claim-release operation. */
+    op: "release";
+    /** Target item id. */
+    id: string;
+    /** Release options forwarded to the public `release` runtime primitive. */
+    options?: PmClientFullMutationOptions;
+}
 /** Union of the item mutations a bulk transaction batch can carry. */
-export type BulkItemMutation = BulkItemCreateMutation | BulkItemUpdateMutation | BulkItemCloseMutation;
+export type BulkItemMutation = BulkItemCreateMutation | BulkItemUpdateMutation | BulkItemCloseMutation | BulkItemReleaseMutation;
 /** Options accepted by the bulk item-mutation transaction helper. */
 export interface CommitItemMutationsOptions {
     /** Tracker root that owns the journal and workspace-wide writer lock. */
@@ -80,18 +89,20 @@ interface LocatedItemSnapshot {
     id: string;
     closedAt: string | undefined;
     updatedAt: string;
+    assignee: string | undefined;
+    claimPrincipal: string | undefined;
 }
 /** Read one item's transaction-relevant fields, mapping not-found to undefined. */
 declare function readItemSnapshot(pmRoot: string, id: string): Promise<LocatedItemSnapshot | undefined>;
-/** Derive a journal-safe step id from one mutation's position and target. */
+/** Derive a journal-safe step id bound to position, target, and payload. */
 declare function deriveStepId(mutation: BulkItemMutation, index: number): string;
 /** Build the durable history-message marker for one bulk mutation phase. */
 declare function bulkHistoryMarker(transactionId: string, stepId: string, phase: "apply" | "compensate"): string;
 /**
- * Report whether an update step's forward mutation is durably applied. Updates
- * cannot be inferred from field values (a moving target), so the applied apply
- * marker in the item's immutable history is the source of truth; a later
- * compensate marker means the mutation was rolled back and must re-apply.
+ * Report whether a step's forward mutation is durably applied. Mutable item
+ * fields cannot prove transaction ownership, so the apply marker in immutable
+ * history is the source of truth; a later compensation marker means the
+ * mutation was rolled back and must re-apply.
  */
 declare function isUpdateMarkerApplied(pmRoot: string, canonicalId: string, transactionId: string, stepId: string): Promise<boolean>;
 /** Idempotently restore an item to its captured pre-mutation version. */
@@ -119,6 +130,40 @@ declare function buildCreateStep(config: {
  * interrupted batches resumable across processes and agents.
  */
 export declare function commitItemMutations(options: CommitItemMutationsOptions): Promise<CommitItemMutationsResult>;
+/** Options for completing one item as a single atomic SDK transaction. */
+export interface CommitItemCompletionOptions {
+    /** Tracker root that owns the item and transaction journal. */
+    pmRoot: string;
+    /** Stable idempotency key for the composed completion. */
+    transactionId: string;
+    /** Attributable actor for evidence, closure, and claim release. */
+    author: string;
+    /** Item being completed. */
+    id: string;
+    /** Durable close reason. */
+    reason: string;
+    /** Evidence and linked-resource updates recorded before closure. */
+    evidence?: PmClientFullMutationOptions;
+    /** Structured closure fields and validation policy. */
+    closeOptions?: PmClientFullMutationOptions;
+    /** Claim-release controls. */
+    releaseOptions?: PmClientFullMutationOptions;
+    /** Workspace transaction lock lifetime in seconds. */
+    lockTtlSeconds?: number;
+    /** Maximum time to wait for the workspace transaction lock. */
+    lockWaitMs?: number;
+    /** Optional transition observer used by telemetry and crash tests. */
+    onTransition?: CommitWorkspaceTransactionOptions["onTransition"];
+}
+/** Build the ordered mutation sequence used by atomic item completion. */
+export declare function buildItemCompletionMutations(options: Pick<CommitItemCompletionOptions, "id" | "reason" | "evidence" | "closeOptions" | "releaseOptions">): BulkItemMutation[];
+/**
+ * Record evidence, close an item, and release its claim as one compensating
+ * transaction. A failure restores the exact pre-completion item version, so
+ * callers never observe the protocol's otherwise possible half-finished
+ * states through a committed result.
+ */
+export declare function commitItemCompletion(options: CommitItemCompletionOptions): Promise<CommitItemMutationsResult>;
 /** Public contract for test only item transaction internals, shared with white-box specs. */
 export declare const _testOnlyItemTransaction: {
     buildCreateStep: typeof buildCreateStep;

package/dist/sdk/item-transaction.js

@@ -6,12 +6,14 @@
  * with correct-by-construction inspection and compensation wiring.
  */
 
-!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]="0b22a2a8-d626-54e1-8f14-670e651a6eb2")}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]="ed638747-7a72-5332-87fc-c82088457b91")}catch(e){}}();
+import crypto from "node:crypto";
 import path from "node:path";
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
+import { stableStringify } from "../core/shared/serialization.js";
 import { readHistoryEntries } from "./history-read.js";
-import { close, create, deleteItem, get, restore, update, } from "./runtime.js";
+import { close, create, deleteItem, get, release, restore, update, } from "./runtime.js";
 import { commitWorkspaceTransaction, } from "./workspace-transaction.js";
 /** Read one item's transaction-relevant fields, mapping not-found to undefined. */
 async function readItemSnapshot(pmRoot, id) {
@@ -22,18 +24,29 @@ async function readItemSnapshot(pmRoot, id) {
             id: item.id,
             closedAt: item.closed_at,
             updatedAt: item.updated_at,
+            assignee: item.assignee,
+            claimPrincipal: item.claim_principal,
         };
     }
     catch (error) {
-        if (error instanceof PmCliError &&
-            error.exitCode === EXIT_CODE.NOT_FOUND) {
+        if (error instanceof PmCliError && error.exitCode === EXIT_CODE.NOT_FOUND) {
             return undefined;
         }
         throw error;
     }
 }
-/** Derive a journal-safe step id from one mutation's position and target. */
+/** Derive a journal-safe step id bound to position, target, and payload. */
 function deriveStepId(mutation, index) {
+    const sanitizedTarget = mutation.id.replaceAll(/[^a-zA-Z0-9._-]/gu, "_");
+    const fingerprint = crypto
+        .createHash("sha256")
+        .update(stableStringify(mutation))
+        .digest("hex")
+        .slice(0, 12);
+    return `${index + 1}-${mutation.op}-${sanitizedTarget}-${fingerprint}`;
+}
+/** Derive the stable public outcome key without exposing journal internals. */
+function deriveOutcomeKey(mutation, index) {
     const sanitizedTarget = mutation.id.replaceAll(/[^a-zA-Z0-9._-]/gu, "_");
     return `${index + 1}-${mutation.op}-${sanitizedTarget}`;
 }
@@ -42,10 +55,10 @@ function bulkHistoryMarker(transactionId, stepId, phase) {
     return `bulk-item-transaction ${transactionId} ${stepId} ${phase}`;
 }
 /**
- * Report whether an update step's forward mutation is durably applied. Updates
- * cannot be inferred from field values (a moving target), so the applied apply
- * marker in the item's immutable history is the source of truth; a later
- * compensate marker means the mutation was rolled back and must re-apply.
+ * Report whether a step's forward mutation is durably applied. Mutable item
+ * fields cannot prove transaction ownership, so the apply marker in immutable
+ * history is the source of truth; a later compensation marker means the
+ * mutation was rolled back and must re-apply.
  */
 async function isUpdateMarkerApplied(pmRoot, canonicalId, transactionId, stepId) {
     const entries = await readHistoryEntries(path.join(pmRoot, "history", `${canonicalId}.jsonl`), canonicalId);
@@ -163,7 +176,13 @@ function buildCloseStep(config, mutation, stepId) {
         // fight legitimate prior closure, and recovery must adopt completed work.
         async inspect() {
             const snapshot = await readItemSnapshot(config.pmRoot, mutation.id);
-            if (snapshot?.closedAt === undefined) {
+            if (snapshot === undefined) {
+                return { state: "pending" };
+            }
+            if (await isUpdateMarkerApplied(config.pmRoot, snapshot.id, config.transactionId, stepId)) {
+                return { state: "applied", result: { id: snapshot.id, op: "close" } };
+            }
+            if (snapshot.closedAt === undefined) {
                 return { state: "pending" };
             }
             return { state: "applied", result: { id: snapshot.id, op: "close" } };
@@ -172,7 +191,11 @@ function buildCloseStep(config, mutation, stepId) {
             return prepareRestoreCompensation(config.pmRoot, mutation);
         },
         async apply() {
-            const closed = await close(mutation.id, mutation.reason, { ...mutation.options, author: config.author }, { pmRoot: config.pmRoot });
+            const closed = await close(mutation.id, mutation.reason, {
+                ...mutation.options,
+                author: config.author,
+                message: bulkHistoryMarker(config.transactionId, stepId, "apply"),
+            }, { pmRoot: config.pmRoot });
             const closedItem = closed.item;
             return { id: String(closedItem.id), op: "close" };
         },
@@ -181,16 +204,54 @@ function buildCloseStep(config, mutation, stepId) {
         },
     };
 }
+/** Build the workspace-transaction step for one claim release. */
+function buildReleaseStep(config, mutation, stepId) {
+    return {
+        id: stepId,
+        async inspect() {
+            const snapshot = await readItemSnapshot(config.pmRoot, mutation.id);
+            if (snapshot === undefined) {
+                return { state: "pending" };
+            }
+            if (await isUpdateMarkerApplied(config.pmRoot, snapshot.id, config.transactionId, stepId)) {
+                return { state: "applied", result: { id: snapshot.id, op: "release" } };
+            }
+            if (snapshot.assignee !== undefined ||
+                snapshot.claimPrincipal !== undefined) {
+                return { state: "pending" };
+            }
+            return { state: "applied", result: { id: snapshot.id, op: "release" } };
+        },
+        async prepareCompensation() {
+            return prepareRestoreCompensation(config.pmRoot, mutation);
+        },
+        async apply() {
+            const released = await release(mutation.id, {
+                ...mutation.options,
+                author: config.author,
+                message: bulkHistoryMarker(config.transactionId, stepId, "apply"),
+            }, { pmRoot: config.pmRoot });
+            const releasedItem = released.item;
+            return { id: String(releasedItem.id), op: "release" };
+        },
+        async compensate(data) {
+            await compensateByRestore(config, mutation.id, stepId, data);
+        },
+    };
+}
 /** Convert one validated bulk mutation into its workspace-transaction step. */
 function buildStepForMutation(config, mutation, index) {
     const stepId = deriveStepId(mutation, index);
-    if (mutation.op === "create") {
-        return buildCreateStep(config, mutation, stepId);
+    switch (mutation.op) {
+        case "create":
+            return buildCreateStep(config, mutation, stepId);
+        case "update":
+            return buildUpdateStep(config, mutation, stepId);
+        case "close":
+            return buildCloseStep(config, mutation, stepId);
+        case "release":
+            return buildReleaseStep(config, mutation, stepId);
     }
-    if (mutation.op === "update") {
-        return buildUpdateStep(config, mutation, stepId);
-    }
-    return buildCloseStep(config, mutation, stepId);
 }
 /** Reject malformed bulk mutation rows before any journal or lock work. */
 function assertValidBulkMutation(mutation, index) {
@@ -199,8 +260,8 @@ function assertValidBulkMutation(mutation, index) {
         Array.isArray(mutation)) {
         throw new TypeError(`Bulk mutation ${index + 1} must be an object`);
     }
-    if (!["create", "update", "close"].includes(mutation.op)) {
-        throw new TypeError(`Bulk mutation ${index + 1} op must be create, update, or close`);
+    if (!["create", "update", "close", "release"].includes(mutation.op)) {
+        throw new TypeError(`Bulk mutation ${index + 1} op must be create, update, close, or release`);
     }
     if (typeof mutation.id !== "string" || mutation.id.trim().length === 0) {
         throw new TypeError(`Bulk mutation ${index + 1} requires a non-empty id`);
@@ -255,10 +316,13 @@ export async function commitItemMutations(options) {
             : { onTransition: options.onTransition }),
     });
     const results = {};
-    for (const [stepId, value] of Object.entries(committed.results)) {
+    for (const [index, mutation] of mutations.entries()) {
+        const stepId = deriveStepId(mutation, index);
+        const value = committed.results[stepId];
         // Journal values round-trip this module's own step outputs, which are
         // always {id, op} objects — the cast restores the concrete outcome shape.
-        results[stepId] = value;
+        results[deriveOutcomeKey(mutation, index)] =
+            value;
     }
     return {
         transactionId: committed.transactionId,
@@ -267,6 +331,52 @@ export async function commitItemMutations(options) {
         results,
     };
 }
+/** Build the ordered mutation sequence used by atomic item completion. */
+export function buildItemCompletionMutations(options) {
+    const mutations = [];
+    if (options.evidence !== undefined &&
+        Object.keys(options.evidence).length > 0) {
+        mutations.push({ op: "update", id: options.id, options: options.evidence });
+    }
+    mutations.push({
+        op: "close",
+        id: options.id,
+        reason: options.reason,
+        ...(options.closeOptions === undefined
+            ? {}
+            : { options: options.closeOptions }),
+    }, {
+        op: "release",
+        id: options.id,
+        ...(options.releaseOptions === undefined
+            ? {}
+            : { options: options.releaseOptions }),
+    });
+    return mutations;
+}
+/**
+ * Record evidence, close an item, and release its claim as one compensating
+ * transaction. A failure restores the exact pre-completion item version, so
+ * callers never observe the protocol's otherwise possible half-finished
+ * states through a committed result.
+ */
+export function commitItemCompletion(options) {
+    return commitItemMutations({
+        pmRoot: options.pmRoot,
+        transactionId: options.transactionId,
+        author: options.author,
+        mutations: buildItemCompletionMutations(options),
+        ...(options.lockTtlSeconds === undefined
+            ? {}
+            : { lockTtlSeconds: options.lockTtlSeconds }),
+        ...(options.lockWaitMs === undefined
+            ? {}
+            : { lockWaitMs: options.lockWaitMs }),
+        ...(options.onTransition === undefined
+            ? {}
+            : { onTransition: options.onTransition }),
+    });
+}
 /** Public contract for test only item transaction internals, shared with white-box specs. */
 export const _testOnlyItemTransaction = {
     buildCreateStep,
@@ -277,4 +387,4 @@ export const _testOnlyItemTransaction = {
     readItemSnapshot,
 };
 //# sourceMappingURL=item-transaction.js.map
-//# debugId=0b22a2a8-d626-54e1-8f14-670e651a6eb2
+//# debugId=ed638747-7a72-5332-87fc-c82088457b91

package/dist/sdk/lifecycle/create.d.ts

@@ -20,6 +20,10 @@ export interface CreateCommandOptions extends MutationMetadataCommandOptions, Sh
     type?: string;
     /** Lifecycle state reported for status. */
     status?: string;
+    /** Author-controlled reason when creating directly in a terminal status. */
+    closeReason?: string;
+    /** Actual completion time when importing an already-completed item. */
+    completedAt?: string;
     /** Value that configures or reports priority for this contract. */
     priority?: string | number;
     /** Value that configures or reports tags for this contract. */