@unbrained/pm-cli 2026.10.22 → 2026.10.23

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

@@ -36,7 +36,7 @@ export { parseStatusFilterCsv } from "../core/item/status-filter.js";
 export { isTerminalStatus,normalizeStatusForRegistry,normalizeStatusInput,} from "../core/item/status.js";
 export { COMMON_MUTATION_COMMAND_OPTION_KEYS,type ItemTypeRegistry,type ResolvedItemTypeDefinition,canonicalizeCommandOptionKey,commandOptionFlagLabel,resolveCommandOptionPolicyState,resolveItemTypeRegistry,resolveTypeDefinition,resolveTypeName,validateTypeOptions,} from "../core/item/type-registry.js";
 export { resolveTypeSynonym } from "../core/item/type-synonyms.js";
-export { acquireLock } from "../core/lock/lock.js";
+export { acquireLock,acquireLockLease } from "../core/lock/lock.js";
 export { printError,printResult,writeStderr,writeStdout } from "../core/output/output.js";
 export { renderRowsAsCsv,renderRowsAsTable } from "../core/output/tabular.js";
 export { parseLimit } from "../core/shared/numeric-parsers.js";

package/dist/sdk/runtime-primitives.js

@@ -1,2 +1,2 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="490f9450-fd66-5ba0-a345-6a0394682a6b")}catch{}})();import{assertSchemaPreviewSupported}from"./runtime/schema-preview.js";import{parseExtensionLongFlagToken,resolveExtensionLongFlagName}from"../core/extensions/flag-definition-validation.js";import{createCheckpointId,loadMutationCheckpoint,restoreCheckpointItems,writeMutationCheckpoint}from"../core/checkpoint/mutation-checkpoint.js";import{describeFlagScalarValueFailure,flattenFlagListValue,resolveExtensionFlagValueContract,resolveFlagValueKind}from"../core/extensions/flag-value-types.js";import{createUnknownSubcommandError}from"./agent/subcommand-recovery.js";import{activateExtensions,clearActiveExtensionHooks,consumeAfterCommandAffectedItems,createCoreCommandHookContext,createEmptyExtensionRegistrationRegistry,discoverExtensions,getActiveCommandResult,getActiveExtensionRegistrations,loadExtensions,projectAfterCommandItemSnapshot,recordAfterCommandAffectedItem,resetActiveExtensionRuntimeState,runActiveCommandHandler,runActiveBeforeMutationHooks,runActiveOnIndexHooks,runActiveOnReadHooks,runActiveOnWriteHooks,runActiveParserOverride,runActivePreflightOverride,runActiveServiceOverride,runAfterCommandHooks,runBeforeCommandHooks,setActiveCommandContext,setActiveCommandResult,setActiveExtensionCommands,setActiveExtensionHooks,setActiveExtensionParsers,setActiveExtensionPreflight,setActiveExtensionRegistrations,setActiveExtensionRenderers,setActiveExtensionServices}from"../core/extensions/index.js";import{applyRegisteredItemFieldDefaultsAndValidation,collectRegisteredItemFieldNames,parseRegisteredItemFieldAssignments}from"../core/extensions/item-fields.js";import{resolveExtensionRoots}from"../core/extensions/loader.js";import{resolveRegisteredSearchProvider,resolveRegisteredVectorStoreAdapter}from"../core/extensions/runtime-registrations.js";import{isFileMissingError,pathExists,readFileIfExists,removeFileIfExists,writeFileAtomic}from"../core/fs/fs-utils.js";import{normalizeBulkIdsValue,parseBulkIdsText,resolveCliBulkIdsInput}from"../core/io/bulk-ids-input.js";import{computeHistoryDiff,patchPathToChangedField}from"../core/history/history-diff.js";import{enforceHistoryStreamPolicyForItem,enforceHistoryStreamPolicyForItems}from"../core/history/history-stream-policy.js";import{appendHistoryEntry,CURRENT_HISTORY_ITEM_HASH_VERSION,CURRENT_HISTORY_RECORD_HASH_VERSION,createHistoryEntry,hashDocument,hashDocumentForVersion,hashEmptyDocument,hashHistoryPatch,hashHistoryRecord,hashHistoryStream,resealHistoryRewrite,sealHistoryRecord,SUPPORTED_HISTORY_ITEM_HASH_VERSIONS,SUPPORTED_HISTORY_RECORD_HASH_VERSIONS,verifyHistoryRecordHash,verifyHistoryRewriteEvidence}from"../core/history/history.js";import{readHistoryEntries}from"../core/history/read.js";import{appendWorkspaceAuditEvent,appendWorkspaceHistoryChange,getWorkspaceHistoryPath,inspectWorkspaceHistoryState,mutateWorkspaceJsonWithHistory,reconcileWorkspaceJsonHistory,restoreWorkspaceJsonFromHistory,WORKSPACE_HISTORY_ID,writeWorkspaceJsonWithHistory}from"../core/history/workspace-history.js";import{normalizeReplayPatchOps,reanchorHistoryEntries,replayToCanonicalItemDocument,replayToItemDocument,toReplayDocument,verifyHistoryChain,verifyHistoryChainWithVersion}from"../core/history/replay.js";import{resolveBodyFileContent}from"../core/io/body-file.js";import{generateItemId,normalizeItemId,normalizeRawItemId}from"../core/item/id.js";import{canonicalDocument,normalizeItemMetadata,parseItemDocument,serializeItemDocument}from"../core/item/item-format.js";import{toItemRecord}from"../core/item/item-record.js";import{assertParentReferenceIsNotSelf,isPlaceholderReferenceToken,normalizeParentReferenceValue,validateMissingParentReference}from"../core/item/parent-reference-policy.js";import{applyAcceptanceCriteriaMutations,applyTagRemovals,assertNoUnknownCsvKeys,createStdinTokenResolver,looksLikeGenericKeyValueEntry,mergeAdditiveTags,parseCsvKv,parseOptionalNonNegativeInteger,parseOptionalNumber,parseTags,preserveMutationStdinTokenFields,preserveMutationStdinTokenLiterals,transferMutationStdinTokenPolicy,shouldResolveMutationStdinTokenField,shouldResolveMutationStdinTokens,splitAcceptanceCriteria}from"../core/item/parse.js";import{resolvePriority}from"../core/item/priority.js";import{validateSprintOrReleaseValue}from"../core/item/sprint-release-format.js";import{parseStatusFilterCsv}from"../core/item/status-filter.js";import{isTerminalStatus,normalizeStatusForRegistry,normalizeStatusInput}from"../core/item/status.js";import{COMMON_MUTATION_COMMAND_OPTION_KEYS,canonicalizeCommandOptionKey,commandOptionFlagLabel,resolveCommandOptionPolicyState,resolveItemTypeRegistry,resolveTypeDefinition,resolveTypeName,validateTypeOptions}from"../core/item/type-registry.js";import{resolveTypeSynonym}from"../core/item/type-synonyms.js";import{acquireLock}from"../core/lock/lock.js";import{printError,printResult,writeStderr,writeStdout}from"../core/output/output.js";import{renderRowsAsCsv,renderRowsAsTable}from"../core/output/tabular.js";import{parseLimit}from"../core/shared/numeric-parsers.js";import{resolveConfiguredPmPackageRoot,resolvePmCliVersion,resolvePmPackageRootFromModule}from"../core/packages/root.js";import{buildInvalidTypeError}from"../core/schema/item-types-file.js";import{collectRuntimeFilterValues,matchesRuntimeFilters}from"../core/schema/runtime-field-filters.js";import{collectRuntimeCreateFieldValues,collectRuntimeUpdateFieldValues}from"../core/schema/runtime-field-values.js";import{readRuntimeFieldOptionValue}from"../core/schema/runtime-field-values.js";import{normalizeStatusInputWithRegistry,resolveItemTypesFilePath,resolveRuntimeFieldRegistry,resolveRuntimeStatusRegistry,statusIsTerminal}from"../core/schema/runtime-schema.js";import{describeAllowedTransitions,evaluateTransition,resolveTypeWorkflows}from"../core/schema/type-workflows.js";import{REINDEX_LOCK_ID,shouldRunSearchRefreshInForeground}from"../core/search/background-refresh.js";import{readVectorizationStatusLedger,refreshSearchArtifactsForMutation,writeVectorizationStatusLedger}from"../core/search/cache.js";import{buildSearchCorpus,buildSemanticCorpusInput,resolveSearchCorpusFields,resolveSemanticCorpusCharacterLimit}from"../core/search/corpus.js";import{executeEmbeddingBatchesWithRetry}from"../core/search/embedding-batches.js";import{resolveEmbeddingProviders}from"../core/search/providers.js";import{resolveSettingsWithSemanticRuntimeDefaults}from"../core/search/semantic-defaults.js";import{executeVectorDelete,executeVectorReset,executeVectorUpsert,resolveVectorStores}from"../core/search/vector-stores.js";import{buildVectorizationEmbeddingIdentity,buildVectorizationEmbeddingMetadata,hasVectorizationEmbeddingIdentityChanged,hasVectorizationVectorDimensionChanged,inferConsistentVectorDimension}from"../core/search/vectorization-metadata.js";import{sentryCaptureCliError,sentryDiscardCommandSpan,sentryFinishCommandSpan,sentryFlush,sentryLogCliUsageError,sentrySetCommandContext,sentryStartCommandSpan}from"../core/sentry/helpers.js";import{ensureSentryInit,ensureSentryCommandTracing}from"../core/sentry/instrument.js";import{clearFocusedItem,getFocusedItem,setFocusedItem}from"../core/session/session-state.js";import{readAuthorEnvironment,diagnoseAgentIdentity,resolveAuthor,resolveClaimPrincipal,runWithHarnessDetectionSignals,runWithWorkspaceHarnessSignalDescriptors,BUILTIN_AGENT_PROVENANCE_ADAPTERS,listAgentProvenanceAdapters,normalizeAgentProvenanceAdapterValue,registerAgentProvenanceAdapters,writeAuthorEnvironment}from"../core/shared/author.js";import{agentSessionEnvironment,boundAgentEpisodeIdentity,runWithAgentSessionContext,resolveAgentSessionContextFromSignals}from"../core/shared/agent-session-context.js";import{evaluateMutationGuard,isMutationAction,listMutationActions,scanMutationSecrets}from"./mutation-guard.js";import{jaccardSimilarity,normalizeSimilarityText,scoreItemSimilarity,tokenizeSimilarityText}from"./similarity-scoring.js";import{inspectStaleInProgressItems,scanStaleInProgressItems}from"./governance/stale-work.js";import{CREATE_DIRECT_CLOSE_REASON_DEFAULT,EXIT_CODE,ITEM_METADATA_KEY_ORDER,SETTINGS_DEFAULTS,TYPE_TO_FOLDER,resolveTelemetryErrorCategory}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";import{decodeHtmlEntitiesInOptions}from"../core/shared/html-entity-decode.js";import{createLazyModule}from"../core/shared/lazy-module.js";import{levenshteinDistanceWithinLimit}from"../core/shared/levenshtein.js";import{isPureSnakeCaseAlias}from"../core/shared/option-alias-visibility.js";import{asRecordClone,asRecordOrNull,toErrorMessage,toNonEmptyStringOrUndefined}from"../core/shared/primitives.js";import{createSerialQueue}from"../core/shared/serial-queue.js";import{stableStringify,stableValueEquals}from"../core/shared/serialization.js";import{splitCommaList}from"../core/shared/split-comma-list.js";import{compareTimestampStrings,nowIso,resolveIsoOrRelative}from"../core/shared/time.js";import{migrateItemFilesToFormat}from"../core/store/item-format-migration.js";import{listAllDocumentCandidatesCached}from"../core/store/item-metadata-cache.js";import{buildItemNotFoundError,createMutationGuardSdk,deleteItem,listAllItemMetadata,listAllItemMetadataLight,locateItem,mutateItem,mutateItemWithHistoryContext,readLocatedItem}from"../core/store/item-store.js";import{isTerminalPlanMode,shouldCompletePlanOnClose}from"../core/item/plan-lifecycle.js";import{getHistoryPath,getItemPath,getSettingsPath,resolveGlobalPmRoot,resolveImplicitPmRoot,resolvePmRoot,resolveWorkspaceRoot}from"../core/store/paths.js";import{persistSelectedItemFormat,readSettings,readSettingsWithMetadata,runWithConfigurationOnlySettings,writeSettings}from"../core/store/settings.js";import{maybeRunFirstUseTelemetryPrompt}from"../core/telemetry/consent.js";import{deriveTelemetryCommandResolution}from"../core/telemetry/observability.js";import{emitTelemetryErrorEvent,finishTelemetryCommand,startTelemetryCommand}from"../core/telemetry/runtime.js";export{BUILTIN_AGENT_PROVENANCE_ADAPTERS,COMMON_MUTATION_COMMAND_OPTION_KEYS,CREATE_DIRECT_CLOSE_REASON_DEFAULT,CURRENT_HISTORY_ITEM_HASH_VERSION,CURRENT_HISTORY_RECORD_HASH_VERSION,EXIT_CODE,ITEM_METADATA_KEY_ORDER,PmCliError,REINDEX_LOCK_ID,SETTINGS_DEFAULTS,SUPPORTED_HISTORY_ITEM_HASH_VERSIONS,SUPPORTED_HISTORY_RECORD_HASH_VERSIONS,TYPE_TO_FOLDER,WORKSPACE_HISTORY_ID,acquireLock,activateExtensions,agentSessionEnvironment,appendHistoryEntry,appendWorkspaceAuditEvent,appendWorkspaceHistoryChange,applyAcceptanceCriteriaMutations,applyRegisteredItemFieldDefaultsAndValidation,applyTagRemovals,asRecordClone,asRecordOrNull,assertNoUnknownCsvKeys,assertParentReferenceIsNotSelf,assertSchemaPreviewSupported,boundAgentEpisodeIdentity,buildInvalidTypeError,buildItemNotFoundError,buildSearchCorpus,buildSemanticCorpusInput,buildVectorizationEmbeddingIdentity,buildVectorizationEmbeddingMetadata,canonicalDocument,canonicalizeCommandOptionKey,clearActiveExtensionHooks,clearFocusedItem,collectRegisteredItemFieldNames,collectRuntimeCreateFieldValues,collectRuntimeFilterValues,collectRuntimeUpdateFieldValues,commandOptionFlagLabel,compareTimestampStrings,computeHistoryDiff,consumeAfterCommandAffectedItems,createCheckpointId,createCoreCommandHookContext,createEmptyExtensionRegistrationRegistry,createHistoryEntry,createLazyModule,createMutationGuardSdk,createSerialQueue,createStdinTokenResolver,createUnknownSubcommandError,decodeHtmlEntitiesInOptions,deleteItem,deriveTelemetryCommandResolution,describeAllowedTransitions,describeFlagScalarValueFailure,diagnoseAgentIdentity,discoverExtensions,emitTelemetryErrorEvent,enforceHistoryStreamPolicyForItem,enforceHistoryStreamPolicyForItems,ensureSentryCommandTracing,ensureSentryInit,evaluateMutationGuard,evaluateTransition,executeEmbeddingBatchesWithRetry,executeVectorDelete,executeVectorReset,executeVectorUpsert,finishTelemetryCommand,flattenFlagListValue,generateItemId,getActiveCommandResult,getActiveExtensionRegistrations,getFocusedItem,getHistoryPath,getItemPath,getSettingsPath,getWorkspaceHistoryPath,hasVectorizationEmbeddingIdentityChanged,hasVectorizationVectorDimensionChanged,hashDocument,hashDocumentForVersion,hashEmptyDocument,hashHistoryPatch,hashHistoryRecord,hashHistoryStream,inferConsistentVectorDimension,inspectStaleInProgressItems,inspectWorkspaceHistoryState,isFileMissingError,isMutationAction,isPlaceholderReferenceToken,isPureSnakeCaseAlias,isTerminalPlanMode,isTerminalStatus,jaccardSimilarity,levenshteinDistanceWithinLimit,listAgentProvenanceAdapters,listAllDocumentCandidatesCached,listAllItemMetadata,listAllItemMetadataLight,listMutationActions,loadExtensions,loadMutationCheckpoint,locateItem,looksLikeGenericKeyValueEntry,matchesRuntimeFilters,maybeRunFirstUseTelemetryPrompt,mergeAdditiveTags,migrateItemFilesToFormat,mutateItem,mutateItemWithHistoryContext,mutateWorkspaceJsonWithHistory,normalizeAgentProvenanceAdapterValue,normalizeBulkIdsValue,normalizeItemId,normalizeItemMetadata,normalizeParentReferenceValue,normalizeRawItemId,normalizeReplayPatchOps,normalizeSimilarityText,normalizeStatusForRegistry,normalizeStatusInput,normalizeStatusInputWithRegistry,nowIso,parseBulkIdsText,parseCsvKv,parseExtensionLongFlagToken,parseItemDocument,parseLimit,parseOptionalNonNegativeInteger,parseOptionalNumber,parseRegisteredItemFieldAssignments,parseStatusFilterCsv,parseTags,patchPathToChangedField,pathExists,persistSelectedItemFormat,preserveMutationStdinTokenFields,preserveMutationStdinTokenLiterals,printError,printResult,projectAfterCommandItemSnapshot,readAuthorEnvironment,readFileIfExists,readHistoryEntries,readLocatedItem,readRuntimeFieldOptionValue,readSettings,readSettingsWithMetadata,readVectorizationStatusLedger,reanchorHistoryEntries,reconcileWorkspaceJsonHistory,recordAfterCommandAffectedItem,refreshSearchArtifactsForMutation,registerAgentProvenanceAdapters,removeFileIfExists,renderRowsAsCsv,renderRowsAsTable,replayToCanonicalItemDocument,replayToItemDocument,resealHistoryRewrite,resetActiveExtensionRuntimeState,resolveAgentSessionContextFromSignals,resolveAuthor,resolveBodyFileContent,resolveClaimPrincipal,resolveCliBulkIdsInput,resolveCommandOptionPolicyState,resolveConfiguredPmPackageRoot,resolveEmbeddingProviders,resolveExtensionFlagValueContract,resolveExtensionLongFlagName,resolveExtensionRoots,resolveFlagValueKind,resolveGlobalPmRoot,resolveImplicitPmRoot,resolveIsoOrRelative,resolveItemTypeRegistry,resolveItemTypesFilePath,resolvePmCliVersion,resolvePmPackageRootFromModule,resolvePmRoot,resolvePriority,resolveRegisteredSearchProvider,resolveRegisteredVectorStoreAdapter,resolveRuntimeFieldRegistry,resolveRuntimeStatusRegistry,resolveSearchCorpusFields,resolveSemanticCorpusCharacterLimit,resolveSettingsWithSemanticRuntimeDefaults,resolveTelemetryErrorCategory,resolveTypeDefinition,resolveTypeName,resolveTypeSynonym,resolveTypeWorkflows,resolveVectorStores,resolveWorkspaceRoot,restoreCheckpointItems,restoreWorkspaceJsonFromHistory,runActiveBeforeMutationHooks,runActiveCommandHandler,runActiveOnIndexHooks,runActiveOnReadHooks,runActiveOnWriteHooks,runActiveParserOverride,runActivePreflightOverride,runActiveServiceOverride,runAfterCommandHooks,runBeforeCommandHooks,runWithAgentSessionContext,runWithConfigurationOnlySettings,runWithHarnessDetectionSignals,runWithWorkspaceHarnessSignalDescriptors,scanMutationSecrets,scanStaleInProgressItems,scoreItemSimilarity,sealHistoryRecord,sentryCaptureCliError,sentryDiscardCommandSpan,sentryFinishCommandSpan,sentryFlush,sentryLogCliUsageError,sentrySetCommandContext,sentryStartCommandSpan,serializeItemDocument,setActiveCommandContext,setActiveCommandResult,setActiveExtensionCommands,setActiveExtensionHooks,setActiveExtensionParsers,setActiveExtensionPreflight,setActiveExtensionRegistrations,setActiveExtensionRenderers,setActiveExtensionServices,setFocusedItem,shouldCompletePlanOnClose,shouldResolveMutationStdinTokenField,shouldResolveMutationStdinTokens,shouldRunSearchRefreshInForeground,splitAcceptanceCriteria,splitCommaList,stableStringify,stableValueEquals,startTelemetryCommand,statusIsTerminal,toErrorMessage,toItemRecord,toNonEmptyStringOrUndefined,toReplayDocument,tokenizeSimilarityText,transferMutationStdinTokenPolicy,validateMissingParentReference,validateSprintOrReleaseValue,validateTypeOptions,verifyHistoryChain,verifyHistoryChainWithVersion,verifyHistoryRecordHash,verifyHistoryRewriteEvidence,writeAuthorEnvironment,writeFileAtomic,writeMutationCheckpoint,writeSettings,writeStderr,writeStdout,writeVectorizationStatusLedger,writeWorkspaceJsonWithHistory};
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="1c243970-5eca-5344-91f9-7c5ab719f22d")}catch{}})();import{assertSchemaPreviewSupported}from"./runtime/schema-preview.js";import{parseExtensionLongFlagToken,resolveExtensionLongFlagName}from"../core/extensions/flag-definition-validation.js";import{createCheckpointId,loadMutationCheckpoint,restoreCheckpointItems,writeMutationCheckpoint}from"../core/checkpoint/mutation-checkpoint.js";import{describeFlagScalarValueFailure,flattenFlagListValue,resolveExtensionFlagValueContract,resolveFlagValueKind}from"../core/extensions/flag-value-types.js";import{createUnknownSubcommandError}from"./agent/subcommand-recovery.js";import{activateExtensions,clearActiveExtensionHooks,consumeAfterCommandAffectedItems,createCoreCommandHookContext,createEmptyExtensionRegistrationRegistry,discoverExtensions,getActiveCommandResult,getActiveExtensionRegistrations,loadExtensions,projectAfterCommandItemSnapshot,recordAfterCommandAffectedItem,resetActiveExtensionRuntimeState,runActiveCommandHandler,runActiveBeforeMutationHooks,runActiveOnIndexHooks,runActiveOnReadHooks,runActiveOnWriteHooks,runActiveParserOverride,runActivePreflightOverride,runActiveServiceOverride,runAfterCommandHooks,runBeforeCommandHooks,setActiveCommandContext,setActiveCommandResult,setActiveExtensionCommands,setActiveExtensionHooks,setActiveExtensionParsers,setActiveExtensionPreflight,setActiveExtensionRegistrations,setActiveExtensionRenderers,setActiveExtensionServices}from"../core/extensions/index.js";import{applyRegisteredItemFieldDefaultsAndValidation,collectRegisteredItemFieldNames,parseRegisteredItemFieldAssignments}from"../core/extensions/item-fields.js";import{resolveExtensionRoots}from"../core/extensions/loader.js";import{resolveRegisteredSearchProvider,resolveRegisteredVectorStoreAdapter}from"../core/extensions/runtime-registrations.js";import{isFileMissingError,pathExists,readFileIfExists,removeFileIfExists,writeFileAtomic}from"../core/fs/fs-utils.js";import{normalizeBulkIdsValue,parseBulkIdsText,resolveCliBulkIdsInput}from"../core/io/bulk-ids-input.js";import{computeHistoryDiff,patchPathToChangedField}from"../core/history/history-diff.js";import{enforceHistoryStreamPolicyForItem,enforceHistoryStreamPolicyForItems}from"../core/history/history-stream-policy.js";import{appendHistoryEntry,CURRENT_HISTORY_ITEM_HASH_VERSION,CURRENT_HISTORY_RECORD_HASH_VERSION,createHistoryEntry,hashDocument,hashDocumentForVersion,hashEmptyDocument,hashHistoryPatch,hashHistoryRecord,hashHistoryStream,resealHistoryRewrite,sealHistoryRecord,SUPPORTED_HISTORY_ITEM_HASH_VERSIONS,SUPPORTED_HISTORY_RECORD_HASH_VERSIONS,verifyHistoryRecordHash,verifyHistoryRewriteEvidence}from"../core/history/history.js";import{readHistoryEntries}from"../core/history/read.js";import{appendWorkspaceAuditEvent,appendWorkspaceHistoryChange,getWorkspaceHistoryPath,inspectWorkspaceHistoryState,mutateWorkspaceJsonWithHistory,reconcileWorkspaceJsonHistory,restoreWorkspaceJsonFromHistory,WORKSPACE_HISTORY_ID,writeWorkspaceJsonWithHistory}from"../core/history/workspace-history.js";import{normalizeReplayPatchOps,reanchorHistoryEntries,replayToCanonicalItemDocument,replayToItemDocument,toReplayDocument,verifyHistoryChain,verifyHistoryChainWithVersion}from"../core/history/replay.js";import{resolveBodyFileContent}from"../core/io/body-file.js";import{generateItemId,normalizeItemId,normalizeRawItemId}from"../core/item/id.js";import{canonicalDocument,normalizeItemMetadata,parseItemDocument,serializeItemDocument}from"../core/item/item-format.js";import{toItemRecord}from"../core/item/item-record.js";import{assertParentReferenceIsNotSelf,isPlaceholderReferenceToken,normalizeParentReferenceValue,validateMissingParentReference}from"../core/item/parent-reference-policy.js";import{applyAcceptanceCriteriaMutations,applyTagRemovals,assertNoUnknownCsvKeys,createStdinTokenResolver,looksLikeGenericKeyValueEntry,mergeAdditiveTags,parseCsvKv,parseOptionalNonNegativeInteger,parseOptionalNumber,parseTags,preserveMutationStdinTokenFields,preserveMutationStdinTokenLiterals,transferMutationStdinTokenPolicy,shouldResolveMutationStdinTokenField,shouldResolveMutationStdinTokens,splitAcceptanceCriteria}from"../core/item/parse.js";import{resolvePriority}from"../core/item/priority.js";import{validateSprintOrReleaseValue}from"../core/item/sprint-release-format.js";import{parseStatusFilterCsv}from"../core/item/status-filter.js";import{isTerminalStatus,normalizeStatusForRegistry,normalizeStatusInput}from"../core/item/status.js";import{COMMON_MUTATION_COMMAND_OPTION_KEYS,canonicalizeCommandOptionKey,commandOptionFlagLabel,resolveCommandOptionPolicyState,resolveItemTypeRegistry,resolveTypeDefinition,resolveTypeName,validateTypeOptions}from"../core/item/type-registry.js";import{resolveTypeSynonym}from"../core/item/type-synonyms.js";import{acquireLock,acquireLockLease}from"../core/lock/lock.js";import{printError,printResult,writeStderr,writeStdout}from"../core/output/output.js";import{renderRowsAsCsv,renderRowsAsTable}from"../core/output/tabular.js";import{parseLimit}from"../core/shared/numeric-parsers.js";import{resolveConfiguredPmPackageRoot,resolvePmCliVersion,resolvePmPackageRootFromModule}from"../core/packages/root.js";import{buildInvalidTypeError}from"../core/schema/item-types-file.js";import{collectRuntimeFilterValues,matchesRuntimeFilters}from"../core/schema/runtime-field-filters.js";import{collectRuntimeCreateFieldValues,collectRuntimeUpdateFieldValues}from"../core/schema/runtime-field-values.js";import{readRuntimeFieldOptionValue}from"../core/schema/runtime-field-values.js";import{normalizeStatusInputWithRegistry,resolveItemTypesFilePath,resolveRuntimeFieldRegistry,resolveRuntimeStatusRegistry,statusIsTerminal}from"../core/schema/runtime-schema.js";import{describeAllowedTransitions,evaluateTransition,resolveTypeWorkflows}from"../core/schema/type-workflows.js";import{REINDEX_LOCK_ID,shouldRunSearchRefreshInForeground}from"../core/search/background-refresh.js";import{readVectorizationStatusLedger,refreshSearchArtifactsForMutation,writeVectorizationStatusLedger}from"../core/search/cache.js";import{buildSearchCorpus,buildSemanticCorpusInput,resolveSearchCorpusFields,resolveSemanticCorpusCharacterLimit}from"../core/search/corpus.js";import{executeEmbeddingBatchesWithRetry}from"../core/search/embedding-batches.js";import{resolveEmbeddingProviders}from"../core/search/providers.js";import{resolveSettingsWithSemanticRuntimeDefaults}from"../core/search/semantic-defaults.js";import{executeVectorDelete,executeVectorReset,executeVectorUpsert,resolveVectorStores}from"../core/search/vector-stores.js";import{buildVectorizationEmbeddingIdentity,buildVectorizationEmbeddingMetadata,hasVectorizationEmbeddingIdentityChanged,hasVectorizationVectorDimensionChanged,inferConsistentVectorDimension}from"../core/search/vectorization-metadata.js";import{sentryCaptureCliError,sentryDiscardCommandSpan,sentryFinishCommandSpan,sentryFlush,sentryLogCliUsageError,sentrySetCommandContext,sentryStartCommandSpan}from"../core/sentry/helpers.js";import{ensureSentryInit,ensureSentryCommandTracing}from"../core/sentry/instrument.js";import{clearFocusedItem,getFocusedItem,setFocusedItem}from"../core/session/session-state.js";import{readAuthorEnvironment,diagnoseAgentIdentity,resolveAuthor,resolveClaimPrincipal,runWithHarnessDetectionSignals,runWithWorkspaceHarnessSignalDescriptors,BUILTIN_AGENT_PROVENANCE_ADAPTERS,listAgentProvenanceAdapters,normalizeAgentProvenanceAdapterValue,registerAgentProvenanceAdapters,writeAuthorEnvironment}from"../core/shared/author.js";import{agentSessionEnvironment,boundAgentEpisodeIdentity,runWithAgentSessionContext,resolveAgentSessionContextFromSignals}from"../core/shared/agent-session-context.js";import{evaluateMutationGuard,isMutationAction,listMutationActions,scanMutationSecrets}from"./mutation-guard.js";import{jaccardSimilarity,normalizeSimilarityText,scoreItemSimilarity,tokenizeSimilarityText}from"./similarity-scoring.js";import{inspectStaleInProgressItems,scanStaleInProgressItems}from"./governance/stale-work.js";import{CREATE_DIRECT_CLOSE_REASON_DEFAULT,EXIT_CODE,ITEM_METADATA_KEY_ORDER,SETTINGS_DEFAULTS,TYPE_TO_FOLDER,resolveTelemetryErrorCategory}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";import{decodeHtmlEntitiesInOptions}from"../core/shared/html-entity-decode.js";import{createLazyModule}from"../core/shared/lazy-module.js";import{levenshteinDistanceWithinLimit}from"../core/shared/levenshtein.js";import{isPureSnakeCaseAlias}from"../core/shared/option-alias-visibility.js";import{asRecordClone,asRecordOrNull,toErrorMessage,toNonEmptyStringOrUndefined}from"../core/shared/primitives.js";import{createSerialQueue}from"../core/shared/serial-queue.js";import{stableStringify,stableValueEquals}from"../core/shared/serialization.js";import{splitCommaList}from"../core/shared/split-comma-list.js";import{compareTimestampStrings,nowIso,resolveIsoOrRelative}from"../core/shared/time.js";import{migrateItemFilesToFormat}from"../core/store/item-format-migration.js";import{listAllDocumentCandidatesCached}from"../core/store/item-metadata-cache.js";import{buildItemNotFoundError,createMutationGuardSdk,deleteItem,listAllItemMetadata,listAllItemMetadataLight,locateItem,mutateItem,mutateItemWithHistoryContext,readLocatedItem}from"../core/store/item-store.js";import{isTerminalPlanMode,shouldCompletePlanOnClose}from"../core/item/plan-lifecycle.js";import{getHistoryPath,getItemPath,getSettingsPath,resolveGlobalPmRoot,resolveImplicitPmRoot,resolvePmRoot,resolveWorkspaceRoot}from"../core/store/paths.js";import{persistSelectedItemFormat,readSettings,readSettingsWithMetadata,runWithConfigurationOnlySettings,writeSettings}from"../core/store/settings.js";import{maybeRunFirstUseTelemetryPrompt}from"../core/telemetry/consent.js";import{deriveTelemetryCommandResolution}from"../core/telemetry/observability.js";import{emitTelemetryErrorEvent,finishTelemetryCommand,startTelemetryCommand}from"../core/telemetry/runtime.js";export{BUILTIN_AGENT_PROVENANCE_ADAPTERS,COMMON_MUTATION_COMMAND_OPTION_KEYS,CREATE_DIRECT_CLOSE_REASON_DEFAULT,CURRENT_HISTORY_ITEM_HASH_VERSION,CURRENT_HISTORY_RECORD_HASH_VERSION,EXIT_CODE,ITEM_METADATA_KEY_ORDER,PmCliError,REINDEX_LOCK_ID,SETTINGS_DEFAULTS,SUPPORTED_HISTORY_ITEM_HASH_VERSIONS,SUPPORTED_HISTORY_RECORD_HASH_VERSIONS,TYPE_TO_FOLDER,WORKSPACE_HISTORY_ID,acquireLock,acquireLockLease,activateExtensions,agentSessionEnvironment,appendHistoryEntry,appendWorkspaceAuditEvent,appendWorkspaceHistoryChange,applyAcceptanceCriteriaMutations,applyRegisteredItemFieldDefaultsAndValidation,applyTagRemovals,asRecordClone,asRecordOrNull,assertNoUnknownCsvKeys,assertParentReferenceIsNotSelf,assertSchemaPreviewSupported,boundAgentEpisodeIdentity,buildInvalidTypeError,buildItemNotFoundError,buildSearchCorpus,buildSemanticCorpusInput,buildVectorizationEmbeddingIdentity,buildVectorizationEmbeddingMetadata,canonicalDocument,canonicalizeCommandOptionKey,clearActiveExtensionHooks,clearFocusedItem,collectRegisteredItemFieldNames,collectRuntimeCreateFieldValues,collectRuntimeFilterValues,collectRuntimeUpdateFieldValues,commandOptionFlagLabel,compareTimestampStrings,computeHistoryDiff,consumeAfterCommandAffectedItems,createCheckpointId,createCoreCommandHookContext,createEmptyExtensionRegistrationRegistry,createHistoryEntry,createLazyModule,createMutationGuardSdk,createSerialQueue,createStdinTokenResolver,createUnknownSubcommandError,decodeHtmlEntitiesInOptions,deleteItem,deriveTelemetryCommandResolution,describeAllowedTransitions,describeFlagScalarValueFailure,diagnoseAgentIdentity,discoverExtensions,emitTelemetryErrorEvent,enforceHistoryStreamPolicyForItem,enforceHistoryStreamPolicyForItems,ensureSentryCommandTracing,ensureSentryInit,evaluateMutationGuard,evaluateTransition,executeEmbeddingBatchesWithRetry,executeVectorDelete,executeVectorReset,executeVectorUpsert,finishTelemetryCommand,flattenFlagListValue,generateItemId,getActiveCommandResult,getActiveExtensionRegistrations,getFocusedItem,getHistoryPath,getItemPath,getSettingsPath,getWorkspaceHistoryPath,hasVectorizationEmbeddingIdentityChanged,hasVectorizationVectorDimensionChanged,hashDocument,hashDocumentForVersion,hashEmptyDocument,hashHistoryPatch,hashHistoryRecord,hashHistoryStream,inferConsistentVectorDimension,inspectStaleInProgressItems,inspectWorkspaceHistoryState,isFileMissingError,isMutationAction,isPlaceholderReferenceToken,isPureSnakeCaseAlias,isTerminalPlanMode,isTerminalStatus,jaccardSimilarity,levenshteinDistanceWithinLimit,listAgentProvenanceAdapters,listAllDocumentCandidatesCached,listAllItemMetadata,listAllItemMetadataLight,listMutationActions,loadExtensions,loadMutationCheckpoint,locateItem,looksLikeGenericKeyValueEntry,matchesRuntimeFilters,maybeRunFirstUseTelemetryPrompt,mergeAdditiveTags,migrateItemFilesToFormat,mutateItem,mutateItemWithHistoryContext,mutateWorkspaceJsonWithHistory,normalizeAgentProvenanceAdapterValue,normalizeBulkIdsValue,normalizeItemId,normalizeItemMetadata,normalizeParentReferenceValue,normalizeRawItemId,normalizeReplayPatchOps,normalizeSimilarityText,normalizeStatusForRegistry,normalizeStatusInput,normalizeStatusInputWithRegistry,nowIso,parseBulkIdsText,parseCsvKv,parseExtensionLongFlagToken,parseItemDocument,parseLimit,parseOptionalNonNegativeInteger,parseOptionalNumber,parseRegisteredItemFieldAssignments,parseStatusFilterCsv,parseTags,patchPathToChangedField,pathExists,persistSelectedItemFormat,preserveMutationStdinTokenFields,preserveMutationStdinTokenLiterals,printError,printResult,projectAfterCommandItemSnapshot,readAuthorEnvironment,readFileIfExists,readHistoryEntries,readLocatedItem,readRuntimeFieldOptionValue,readSettings,readSettingsWithMetadata,readVectorizationStatusLedger,reanchorHistoryEntries,reconcileWorkspaceJsonHistory,recordAfterCommandAffectedItem,refreshSearchArtifactsForMutation,registerAgentProvenanceAdapters,removeFileIfExists,renderRowsAsCsv,renderRowsAsTable,replayToCanonicalItemDocument,replayToItemDocument,resealHistoryRewrite,resetActiveExtensionRuntimeState,resolveAgentSessionContextFromSignals,resolveAuthor,resolveBodyFileContent,resolveClaimPrincipal,resolveCliBulkIdsInput,resolveCommandOptionPolicyState,resolveConfiguredPmPackageRoot,resolveEmbeddingProviders,resolveExtensionFlagValueContract,resolveExtensionLongFlagName,resolveExtensionRoots,resolveFlagValueKind,resolveGlobalPmRoot,resolveImplicitPmRoot,resolveIsoOrRelative,resolveItemTypeRegistry,resolveItemTypesFilePath,resolvePmCliVersion,resolvePmPackageRootFromModule,resolvePmRoot,resolvePriority,resolveRegisteredSearchProvider,resolveRegisteredVectorStoreAdapter,resolveRuntimeFieldRegistry,resolveRuntimeStatusRegistry,resolveSearchCorpusFields,resolveSemanticCorpusCharacterLimit,resolveSettingsWithSemanticRuntimeDefaults,resolveTelemetryErrorCategory,resolveTypeDefinition,resolveTypeName,resolveTypeSynonym,resolveTypeWorkflows,resolveVectorStores,resolveWorkspaceRoot,restoreCheckpointItems,restoreWorkspaceJsonFromHistory,runActiveBeforeMutationHooks,runActiveCommandHandler,runActiveOnIndexHooks,runActiveOnReadHooks,runActiveOnWriteHooks,runActiveParserOverride,runActivePreflightOverride,runActiveServiceOverride,runAfterCommandHooks,runBeforeCommandHooks,runWithAgentSessionContext,runWithConfigurationOnlySettings,runWithHarnessDetectionSignals,runWithWorkspaceHarnessSignalDescriptors,scanMutationSecrets,scanStaleInProgressItems,scoreItemSimilarity,sealHistoryRecord,sentryCaptureCliError,sentryDiscardCommandSpan,sentryFinishCommandSpan,sentryFlush,sentryLogCliUsageError,sentrySetCommandContext,sentryStartCommandSpan,serializeItemDocument,setActiveCommandContext,setActiveCommandResult,setActiveExtensionCommands,setActiveExtensionHooks,setActiveExtensionParsers,setActiveExtensionPreflight,setActiveExtensionRegistrations,setActiveExtensionRenderers,setActiveExtensionServices,setFocusedItem,shouldCompletePlanOnClose,shouldResolveMutationStdinTokenField,shouldResolveMutationStdinTokens,shouldRunSearchRefreshInForeground,splitAcceptanceCriteria,splitCommaList,stableStringify,stableValueEquals,startTelemetryCommand,statusIsTerminal,toErrorMessage,toItemRecord,toNonEmptyStringOrUndefined,toReplayDocument,tokenizeSimilarityText,transferMutationStdinTokenPolicy,validateMissingParentReference,validateSprintOrReleaseValue,validateTypeOptions,verifyHistoryChain,verifyHistoryChainWithVersion,verifyHistoryRecordHash,verifyHistoryRewriteEvidence,writeAuthorEnvironment,writeFileAtomic,writeMutationCheckpoint,writeSettings,writeStderr,writeStdout,writeVectorizationStatusLedger,writeWorkspaceJsonWithHistory};
 //# sourceMappingURL=runtime-primitives.js.map

package/dist/sdk/runtime.d.ts

@@ -78,7 +78,7 @@ export { BASELINE_ITEM_FORMAT_VERSION,CURRENT_ITEM_FORMAT_VERSION,classifyItemFo
 export { parseTags } from "../core/item/parse.js";
 export { isTerminalStatus,normalizeStatusInput } from "../core/item/status.js";
 export { resolveItemTypeRegistry } from "../core/item/type-registry.js";
-export { acquireLock } from "../core/lock/lock.js";
+export { acquireLock,acquireLockLease,type LockLease } from "../core/lock/lock.js";
 export { resolveRuntimeFieldRegistry,resolveRuntimeStatusRegistry } from "../core/schema/runtime-schema.js";
 export { EXIT_CODE };
 export { PmCliError } from "../core/shared/errors.js";

package/dist/sdk/runtime.js

@@ -1,2 +1,2 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="b22c5f2e-2914-5c58-acb2-7aad91aa8663")}catch{}})();import{AsyncLocalStorage}from"node:async_hooks";import{createEmptyExtensionCommandRegistry,createEmptyExtensionHookRegistry,createEmptyExtensionParserRegistry,createEmptyExtensionPreflightRegistry,createEmptyExtensionRegistrationRegistry,createEmptyExtensionRendererRegistry,createEmptyExtensionServiceRegistry}from"../core/extensions/extension-registries.js";import{activateExtensions,deactivateExtensions,loadExtensions,runActiveCommandHandler,runWithIsolatedExtensionRuntime,setActiveExtensionCommands,setActiveExtensionHooks,setActiveExtensionParsers,setActiveExtensionPreflight,setActiveExtensionRegistrations,setActiveExtensionRenderers,setActiveExtensionServices}from"../core/extensions/index.js";import{pathExists}from"../core/fs/fs-utils.js";import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";import{asRecordClone}from"../core/shared/primitives.js";import{HOISTED_ACTION_OPTION_KEYS}from"./runtime-input.js";import{createAsyncReadWriteGate}from"../core/shared/serial-queue.js";import{getSettingsPath,resolvePmRoot}from"../core/store/paths.js";import{readSettings}from"../core/store/settings.js";import{PM_TOOL_ACTIONS}from"./cli-contracts/enum-contracts.js";import{runContracts}from"./cli-contracts/runtime-contracts.js";import{attachReadOutputContracts}from"./context-intent-contracts.js";import{runWithDiscoveredContextIntentContracts}from"./context-intent-runtime.js";import{finalizeContextUsageEgress}from"./context/usage-egress.js";import{createExtensionCommandSdk}from"./extension-command-context.js";import{INIT_INVOCATION_CWD}from"./init.js";import{certifyCompleteListResult,createCompleteListOptions}from"./query/complete-list.js";import{listClientItemMetadataLight}from"./query/light-metadata.js";import{normalizeReadOutputIncludeModeOptions,validateReadOutputOptions}from"./read-output-contracts.js";import{SDK_ACTION_ALIASES}from"./runtime-action-aliases.js";import{closeManyOptionsFromFlat,extensionOptionsFromArgs,actionGlobalOptions as globalOptions,mutationListOptions,mutationOptionsWithOverrides,normalizeActionName,normalizeCommandPath,normalizeMcpOptionsArrays,normalizeMcpUpdateOptions,optionsWithAuthor,readRuntimeScalarString as readScalarString,readRuntimeScalarStringAllowBlank as readScalarStringAllowBlank,readRuntimeString as readString,readRuntimeStringArray as readStringArray,shouldInvalidateWorkspaceContractsCacheAfterAction,updateManyOptionsFromFlat,withAddNoteOption,withFilesDiscoveryOptions,withMutationCompaction}from"./runtime-input.js";import{SDK_ACTION_HANDLERS}from"./runtime/actions.js";import{getOwnHandler,readRequiredString}from"./runtime/context.js";import{clearWorkspaceContractsCache}from"./workspace-contracts-cache.js";import{PM_GITIGNORE_END,PM_GITIGNORE_START,ensurePmGitignore,getPmGitignoreBlock}from"./workspace.js";import{SEARCH_EXTENSION_FLAG_DEFINITIONS}from"./extension-contracts.js";export*from"./cli-contracts/agent-output-contracts.js";import{PmCompleteListValidationError,assertCompleteListResult,certifyCompleteListResult as certifyCompleteListResult2,createCompleteListOptions as createCompleteListOptions2,inspectCompleteListResult}from"./query/complete-list.js";import{getWorkspaceContracts}from"./query/workspace-contracts.js";import{clearWorkspaceContractsCache as clearWorkspaceContractsCache2}from"./workspace-contracts-cache.js";export*from"./governance/workflow-policy.js";import{runCloseTask,runPauseTask,runStartTask}from"./lifecycle/task-composition.js";import{getActiveExtensionRegistrations,runActiveOnReadHooks,runActiveOnWriteHooks}from"../core/extensions/index.js";import{pathExists as pathExists2,readFileIfExists,removeFileIfExists,writeFileAtomic}from"../core/fs/fs-utils.js";import{appendHistoryEntry,createHistoryEntry}from"../core/history/history.js";import{HISTORY_EVENT_CLASSIFICATION_VERSION,MAINTENANCE_HISTORY_OPERATIONS,SUBSTANTIVE_HISTORY_OPERATIONS,classifyHistoryEvent}from"../core/history/event-classification.js";import{generateItemId,normalizeItemId,normalizeRawItemId}from"../core/item/id.js";import{readBooleanOption,readCsvListOption,readStringOption}from"./package-runtime-options.js";import{PM_CLI_EXPECTED_ERROR_NAME,createPmCliExpectedError,isPmCliExpectedError}from"./errors.js";import{commitImportedItem,emptyImportedDocument,ensureTrackerInitialized,selectImportAuthor,toEstimatedMinutesValue,toImportBoolean,toImportConfidence,toImportInteger,toImportLinkedDocs,toImportLinkedFiles,toImportLinkedTests,toImportLogEntries,toImportNormalizedEnum,toImportNumberMap,toImportPriority,toImportStatus,toImportStringList,toImportStringMap,toImportTags,toNonEmptyImportString}from"./package-import-adapters.js";import{canonicalDocument,normalizeItemMetadata,serializeItemDocument,splitFrontMatter}from"../core/item/item-format.js";import{BASELINE_ITEM_FORMAT_VERSION,CURRENT_ITEM_FORMAT_VERSION,classifyItemFormatVersion,effectiveItemFormatVersion,normalizeItemFormatVersion,scanItemFormatVersions}from"../core/item/item-format-version.js";import{parseTags}from"../core/item/parse.js";import{isTerminalStatus,normalizeStatusInput}from"../core/item/status.js";import{resolveItemTypeRegistry}from"../core/item/type-registry.js";import{acquireLock}from"../core/lock/lock.js";import{resolveRuntimeFieldRegistry,resolveRuntimeStatusRegistry}from"../core/schema/runtime-schema.js";import{PmCliError as PmCliError2}from"../core/shared/errors.js";import{isTimestampLiteral,nowIso}from"../core/shared/time.js";import{jaccardSimilarity,normalizeSimilarityText,scoreItemSimilarity,tokenizeSimilarityText}from"./similarity-scoring.js";import{listAllItemMetadata,listAllItemMetadataLight,locateItem,readLocatedItem}from"../core/store/item-store.js";import{getHistoryPath,getItemPath,getSettingsPath as getSettingsPath2,resolveImplicitPmRoot,resolvePmRoot as resolvePmRoot2}from"../core/store/paths.js";import{readSettings as readSettings2}from"../core/store/settings.js";import{runAggregate}from"./query/aggregate.js";import{CONTEXT_OUTPUT_VALUES,runContext}from"./query/context.js";import{runGet}from"./query/get.js";import{runList}from"./query/list.js";import{closeItem,runClose}from"./lifecycle/close.js";import{runCopy}from"./lifecycle/copy.js";import{runDelete}from"./lifecycle/delete.js";import{runFocus}from"./lifecycle/focus.js";import{runRestore}from"./lifecycle/restore.js";import{DEFAULT_TERMINAL_TRANSITION_POLICY,applyTerminalOrderingPolicy,requireTerminalReason,resolveTerminalReason}from"./lifecycle-policy.js";import{runUpdate}from"./lifecycle/update.js";import{runReopen}from"./lifecycle/reopen.js";import{NEXT_OUTPUT_VALUES,runNext}from"./query/next.js";import{runSearch}from"./query/search.js";import{runStats}from"./stats.js";import{runDuplicates}from"./duplicates.js";import{renderCalendarMarkdown,renderCalendarToon,resolveCalendarOutputFormat,runCalendar}from"./query/calendar.js";import{renderGuideMarkdown,resolveGuideOutputFormat,runGuide}from"./guide.js";import{runCompletion}from"./completion.js";import{runReindex}from"./governance/reindex.js";import{loadCreateTemplateOptions,runTemplatesList,runTemplatesSave,runTemplatesShow}from"./templates.js";import{runTestRunsList,runTestRunsLogs,runTestRunsResume,runTestRunsStatus,runTestRunsStop}from"./test/runs.js";import{BUILTIN_ITEM_TYPE_VALUES,CONFIDENCE_TEXT_VALUES,DEPENDENCY_KIND_VALUES,ISSUE_SEVERITY_VALUES,ITEM_TYPE_VALUES,RISK_VALUES,STATUS_VALUES}from"../types/index.js";const ACTIVE_EXTENSION_HOST_CONTEXT=Symbol("pm.active-extension-host-context");function splitFullClientMutationOptions(options){return{fullChangedFields:!0,options}}class PmClient{defaults;constructor(options={}){this.defaults={...options.pmRoot===void 0?{}:{path:options.pmRoot},...options.cwd===void 0?{}:{cwd:options.cwd},...options.author===void 0?{}:{author:options.author},...options.noExtensions===void 0?{}:{noExtensions:options.noExtensions}}}static forActiveExtensionHost(options){const client=new PmClient({...options,noExtensions:!0});return client.defaults[ACTIVE_EXTENSION_HOST_CONTEXT]=!0,client}run(action,args={}){return runAction({...this.defaults,...args,action})}runTyped(action,args={}){return this.run(action,args)}context(options={}){return this.runTyped("context",{options})}listAllItemMetadataLight(){return listClientItemMetadataLight(this.defaults.path,this.defaults.cwd)}list(options={}){return this.runTyped("list",{options})}async listAllComplete(options={}){return certifyCompleteListResult(await this.list(createCompleteListOptions(options)))}search(query,options={}){return this.runTyped("search",{query,options})}get(id,options={}){return this.runTyped("get",{id,options})}next(options={}){return this.runTyped("next",{options})}aggregate(options={}){return this.runTyped("aggregate",{options})}stats(options={}){return this.runTyped("stats",{options})}duplicates(options={}){return this.runTyped("duplicates",{options})}comments(id,options={}){return this.runTyped("comments",{id,options})}notes(id,options={}){return this.runTyped("notes",{id,options})}learnings(id,options={}){return this.runTyped("learnings",{id,options})}files(id,options={}){return this.runTyped("files",{id,options})}filesDiscover(id,options={}){return this.runTyped("files-discover",{id,options})}filesLookup(options){return this.runTyped("files-lookup",{options})}docs(id,options={}){return this.runTyped("docs",{id,options})}deps(id,options={}){return this.runTyped("deps",{id,options})}graph(subcommand,ids={},options={}){return this.runTyped("graph",{subcommand,...ids,options})}append(id,body,options={}){return this.runTyped("append",{id,...splitFullClientMutationOptions(mutationOptionsWithOverrides(options,{body}))})}init(prefix,options={}){return this.runTyped("init",{...prefix===void 0?{}:{prefix},options})}config(scope,configAction,key,value,options={}){return this.runTyped("config",{scope,configAction,...key===void 0?{}:{key},...value===void 0?{}:{value},options})}schema(subcommand,options={}){return this.runTyped("schema",{options:{...options,subcommand}})}workflowPolicy(action,name,options={}){return this.runTyped("schema",{name,options:{...options,subcommand:action}})}schemaList(){return this.runTyped("schema",{options:{subcommand:"list"}})}schemaShow(name){return this.runTyped("schema",{name,options:{subcommand:"show"}})}schemaAddType(name,options={}){return this.runTyped("schema",{name,options:{...options,subcommand:"add-type"}})}schemaRemoveType(name,options={}){return this.runTyped("schema",{name,options:{...options,subcommand:"remove-type"}})}schemaAddStatus(name,options={}){return this.runTyped("schema",{name,options:{...options,subcommand:"add-status"}})}schemaRemoveStatus(name,options={}){return this.runTyped("schema",{name,options:{...options,subcommand:"remove-status"}})}schemaAddField(name,options={}){const{type,...mutationOptions}=options;return this.runTyped("schema",{name,options:{...mutationOptions,fieldType:type,subcommand:"add-field"}})}schemaRemoveField(name,options={}){return this.runTyped("schema",{name,options:{...options,subcommand:"remove-field"}})}schemaListFields(){return this.runTyped("schema",{options:{subcommand:"list-fields"}})}schemaShowField(name){return this.runTyped("schema",{name,options:{subcommand:"show-field"}})}schemaApplyPreset(typePreset,options={}){return this.runTyped("schema",{typePreset,options:{...options,subcommand:"apply-preset"}})}schemaInferTypes(options={}){return this.runTyped("schema",{options:{...options,subcommand:"add-type",infer:!0}})}schemaRenameType(from,to,options){return this.runTyped("schema",{name:from,options:{...options,subcommand:"rename-type",to}})}schemaRenameField(from,to,options,type){return this.runTyped("schema",{name:from,options:{...options,subcommand:"rename-field",to,...type?{fieldTypeScope:type}:{}}})}schemaRemapStatus(from,to,options){return this.runTyped("schema",{name:from,options:{...options,subcommand:"remap-status",to}})}schemaShowStatus(name){return this.runTyped("schema",{name,options:{subcommand:"show-status"}})}profile(subcommand,options={}){return this.runTyped("profile",{options:{...options,subcommand}})}profileList(){return this.runTyped("profile",{options:{subcommand:"list"}})}profileShow(name){return this.runTyped("profile",{name,options:{subcommand:"show"}})}profileApply(name,options={}){return this.runTyped("profile",{name,options:{...options,subcommand:"apply"}})}profileLint(name){return this.runTyped("profile",{name,options:{subcommand:"lint"}})}validate(options={}){return this.runTyped("validate",{options})}health(options={}){return this.runTyped("health",{options})}gc(options={}){return this.runTyped("gc",{options})}assurance(input){return this.runTyped("assurance",{options:{...input,subcommand:input.action}})}historyRedact(id,options){return this.runTyped("history-redact",{id,options})}historyRepair(id,options={}){return this.runTyped("history-repair",{id,options})}historyRepairAll(options={}){return this.runTyped("history-repair",{options:{...options,all:!0}})}historyAttest(options={}){return this.runTyped("history-attest",{options})}historyCompact(id,options={}){return this.runTyped("history-compact",{id,options})}historyCompactBulk(options){return this.runTyped("history-compact",{options})}historyAuthorAcknowledge(options){return this.runTyped("history-author-acknowledge",{historyEvent:(options.events??[]).map(event=>`${event.item_id}:${String(event.line)}`),allActionable:options.all_actionable===!0,dryRun:options.dry_run===!0,planFingerprint:options.plan_fingerprint,limit:options.coordinate_limit,attributedAuthor:options.attributed_author,reviewer:options.reviewer,reason:options.reason})}plan(subcommand,id,options={},stepRef,reorderTo){return this.runTyped("plan",{fullChangedFields:!0,...id===void 0?{}:{id},...stepRef===void 0?{}:{stepRef},...reorderTo===void 0?{}:{reorderTo},options:mutationOptionsWithOverrides(options,{subcommand})})}planCreate(options){return this.plan("create",void 0,options)}planShow(id,options={}){return this.plan("show",id,options)}planAddStep(id,options){return this.plan("add-step",id,options)}planUpdateStep(id,stepRef,options){return this.plan("update-step",id,options,stepRef)}planCompleteStep(id,stepRef,options={}){return this.plan("complete-step",id,options,stepRef)}planBlockStep(id,stepRef,options){return this.plan("block-step",id,options,stepRef)}planReorderStep(id,stepRef,reorderTo,options={}){return this.plan("reorder-step",id,options,stepRef,reorderTo)}planRemoveStep(id,stepRef,options={}){return this.plan("remove-step",id,options,stepRef)}planLink(id,stepRef,options){return this.plan("link",id,options,stepRef)}planUnlink(id,stepRef,options){return this.plan("unlink",id,options,stepRef)}planDecision(id,options){return this.plan("decision",id,options)}planDiscovery(id,options){return this.plan("discovery",id,options)}planValidation(id,options){return this.plan("validation",id,options)}planResume(id,options){return this.plan("resume",id,options)}planApprove(id,options={}){return this.plan("approve",id,options)}planMaterialize(id,options){return this.plan("materialize",id,options)}create(options={}){return this.runTyped("create",splitFullClientMutationOptions(options))}update(id,options={}){return this.runTyped("update",{id,...splitFullClientMutationOptions(options)})}reopen(id,reason,options={}){return this.runTyped("item-reopen",{id,reason,fullChangedFields:!0,options})}close(id,reason,options={}){return this.runTyped("close",{id,reason,...splitFullClientMutationOptions(options)})}claim(id,options={}){return this.runTyped("claim",{id,...splitFullClientMutationOptions(options)})}claimNext(options={}){return this.runTyped("claim",{next:!0,...splitFullClientMutationOptions(options)})}release(id,options={}){return this.runTyped("release",{id,...splitFullClientMutationOptions(options)})}copy(id,options={}){return this.runTyped("copy",{id,...splitFullClientMutationOptions(options)})}delete(id,options={}){return this.runTyped("delete",{id,...splitFullClientMutationOptions(options)})}restore(id,target,options={}){return this.runTyped("restore",{fullChangedFields:!0,id,options:{...options,target}})}focus(id,options={}){return this.runTyped("focus",{...id===void 0?{}:{id},...splitFullClientMutationOptions(options)})}startTask(id,options={}){return this.runTyped("start-task",{id,...splitFullClientMutationOptions(options)})}pauseTask(id,options={}){return this.runTyped("pause-task",{id,...splitFullClientMutationOptions(options)})}closeTask(id,reason,options={}){return this.runTyped("close-task",{id,reason,...splitFullClientMutationOptions(options)})}extension(target,options={}){return this.runTyped("extension",{...target===void 0?{}:{target},options})}extensionList(options={}){return this.extension("list",options)}extensionActivate(target,options={}){return this.runTyped("extension-activate",{target,options})}extensionDeactivate(target,options={}){return this.runTyped("extension-deactivate",{target,options})}package(target,options={}){return this.runTyped("package",{...target===void 0?{}:{target},options:{...options,vocabulary:"package"}})}packageList(options={}){return this.package("list",options)}packageInstall(target,options={}){return this.runTyped("package-install",{target,options})}packageUninstall(target,options={}){return this.runTyped("package-uninstall",{target,options})}packageDoctor(options={}){return this.runTyped("package-doctor",{options})}packageManage(target,options={}){return this.runTyped("package-manage",{...target===void 0?{}:{target},options})}packageDescribe(target,options={}){return this.runTyped("package-describe",{...target===void 0?{}:{target},options})}packageReload(options={}){return this.runTyped("package-reload",{options})}packageCatalog(options={}){return this.runTyped("package-catalog",{options})}packageActivate(target,options={}){return this.runTyped("package-activate",{target,options})}packageDeactivate(target,options={}){return this.runTyped("package-deactivate",{target,options})}packageMigrate(options={}){return this.package(void 0,{...options,migrate:!0})}upgrade(target,options={}){return this.runTyped("upgrade",{...target===void 0?{}:{target},options})}}function context(options={},clientOptions={}){return new PmClient(clientOptions).context(options)}function list(options={},clientOptions={}){return new PmClient(clientOptions).list(options)}function listAllComplete(options={},clientOptions={}){return new PmClient(clientOptions).listAllComplete(options)}function search(query,options={},clientOptions={}){return new PmClient(clientOptions).search(query,options)}function get(id,options={},clientOptions={}){return new PmClient(clientOptions).get(id,options)}function next(options={},clientOptions={}){return new PmClient(clientOptions).next(options)}function aggregate(options={},clientOptions={}){return new PmClient(clientOptions).aggregate(options)}function stats(options={},clientOptions={}){return new PmClient(clientOptions).stats(options)}function duplicates(options={},clientOptions={}){return new PmClient(clientOptions).duplicates(options)}function comments(id,options={},clientOptions={}){return new PmClient(clientOptions).comments(id,options)}function notes(id,options={},clientOptions={}){return new PmClient(clientOptions).notes(id,options)}function learnings(id,options={},clientOptions={}){return new PmClient(clientOptions).learnings(id,options)}function files(id,options={},clientOptions={}){return new PmClient(clientOptions).files(id,options)}function filesDiscover(id,options={},clientOptions={}){return new PmClient(clientOptions).filesDiscover(id,options)}function filesLookup(options,clientOptions={}){return new PmClient(clientOptions).filesLookup(options)}function docs(id,options={},clientOptions={}){return new PmClient(clientOptions).docs(id,options)}function deps(id,options={},clientOptions={}){return new PmClient(clientOptions).deps(id,options)}function graph(subcommand,ids={},options={},clientOptions={}){return new PmClient(clientOptions).graph(subcommand,ids,options)}function append(id,body,options={},clientOptions={}){return new PmClient(clientOptions).append(id,body,options)}function init(prefix,options={},clientOptions={}){return new PmClient(clientOptions).init(prefix,options)}function config(scope,configAction,key,value,options={},clientOptions={}){return new PmClient(clientOptions).config(scope,configAction,key,value,options)}function schema(subcommand,options={},clientOptions={}){return new PmClient(clientOptions).schema(subcommand,options)}function schemaList(clientOptions={}){return new PmClient(clientOptions).schemaList()}function schemaShow(name,clientOptions={}){return new PmClient(clientOptions).schemaShow(name)}function schemaAddType(name,options={},clientOptions={}){return new PmClient(clientOptions).schemaAddType(name,options)}function schemaRemoveType(name,options={},clientOptions={}){return new PmClient(clientOptions).schemaRemoveType(name,options)}function schemaAddStatus(name,options={},clientOptions={}){return new PmClient(clientOptions).schemaAddStatus(name,options)}function schemaRemoveStatus(name,options={},clientOptions={}){return new PmClient(clientOptions).schemaRemoveStatus(name,options)}function schemaAddField(name,options={},clientOptions={}){return new PmClient(clientOptions).schemaAddField(name,options)}function schemaRemoveField(name,options={},clientOptions={}){return new PmClient(clientOptions).schemaRemoveField(name,options)}function schemaListFields(clientOptions={}){return new PmClient(clientOptions).schemaListFields()}function schemaShowField(name,clientOptions={}){return new PmClient(clientOptions).schemaShowField(name)}function schemaApplyPreset(typePreset,options={},clientOptions={}){return new PmClient(clientOptions).schemaApplyPreset(typePreset,options)}function schemaInferTypes(options={},clientOptions={}){return new PmClient(clientOptions).schemaInferTypes(options)}function schemaRenameType(from,to,options,clientOptions={}){return new PmClient(clientOptions).schemaRenameType(from,to,options)}function schemaRenameField(from,to,options,type,clientOptions={}){return new PmClient(clientOptions).schemaRenameField(from,to,options,type)}function schemaRemapStatus(from,to,options,clientOptions={}){return new PmClient(clientOptions).schemaRemapStatus(from,to,options)}function schemaShowStatus(name,clientOptions={}){return new PmClient(clientOptions).schemaShowStatus(name)}function profile(subcommand,options={},clientOptions={}){return new PmClient(clientOptions).profile(subcommand,options)}function profileList(clientOptions={}){return new PmClient(clientOptions).profileList()}function profileShow(name,clientOptions={}){return new PmClient(clientOptions).profileShow(name)}function profileApply(name,options={},clientOptions={}){return new PmClient(clientOptions).profileApply(name,options)}function profileLint(name,clientOptions={}){return new PmClient(clientOptions).profileLint(name)}function validate(options={},clientOptions={}){return new PmClient(clientOptions).validate(options)}function health(options={},clientOptions={}){return new PmClient(clientOptions).health(options)}function gc(options={},clientOptions={}){return new PmClient(clientOptions).gc(options)}function historyRedact(id,options,clientOptions={}){return new PmClient(clientOptions).historyRedact(id,options)}function historyRepair(id,options={},clientOptions={}){return new PmClient(clientOptions).historyRepair(id,options)}function historyRepairAll(options={},clientOptions={}){return new PmClient(clientOptions).historyRepairAll(options)}function historyCompact(id,options={},clientOptions={}){return new PmClient(clientOptions).historyCompact(id,options)}function historyCompactBulk(options,clientOptions={}){return new PmClient(clientOptions).historyCompactBulk(options)}function create(options={},clientOptions={}){return new PmClient(clientOptions).create(options)}function update(id,options={},clientOptions={}){return new PmClient(clientOptions).update(id,options)}function reopen(id,reason,options={},clientOptions={}){return new PmClient(clientOptions).reopen(id,reason,options)}function close(id,reason,options={},clientOptions={}){return new PmClient(clientOptions).close(id,reason,options)}function claim(id,options={},clientOptions={}){return new PmClient(clientOptions).claim(id,options)}function claimNext(options={},clientOptions={}){return new PmClient(clientOptions).claimNext(options)}function release(id,options={},clientOptions={}){return new PmClient(clientOptions).release(id,options)}function copy(id,options={},clientOptions={}){return new PmClient(clientOptions).copy(id,options)}function deleteItem(id,options={},clientOptions={}){return new PmClient(clientOptions).delete(id,options)}function restore(id,target,options={},clientOptions={}){return new PmClient(clientOptions).restore(id,target,options)}function focus(id,options={},clientOptions={}){return new PmClient(clientOptions).focus(id,options)}function startTask(id,options={},clientOptions={}){return new PmClient(clientOptions).startTask(id,options)}function pauseTask(id,options={},clientOptions={}){return new PmClient(clientOptions).pauseTask(id,options)}function closeTask(id,reason,options={},clientOptions={}){return new PmClient(clientOptions).closeTask(id,reason,options)}function extension(target,options={},clientOptions={}){return new PmClient(clientOptions).extension(target,options)}function extensionList(options={},clientOptions={}){return new PmClient(clientOptions).extensionList(options)}function extensionActivate(target,options={},clientOptions={}){return new PmClient(clientOptions).extensionActivate(target,options)}function extensionDeactivate(target,options={},clientOptions={}){return new PmClient(clientOptions).extensionDeactivate(target,options)}function packageLifecycle(target,options={},clientOptions={}){return new PmClient(clientOptions).package(target,options)}function packageList(options={},clientOptions={}){return new PmClient(clientOptions).packageList(options)}function packageInstall(target,options={},clientOptions={}){return new PmClient(clientOptions).packageInstall(target,options)}function packageUninstall(target,options={},clientOptions={}){return new PmClient(clientOptions).packageUninstall(target,options)}function packageDoctor(options={},clientOptions={}){return new PmClient(clientOptions).packageDoctor(options)}function packageManage(target,options={},clientOptions={}){return new PmClient(clientOptions).packageManage(target,options)}function packageDescribe(target,options={},clientOptions={}){return new PmClient(clientOptions).packageDescribe(target,options)}function packageReload(options={},clientOptions={}){return new PmClient(clientOptions).packageReload(options)}function packageCatalog(options={},clientOptions={}){return new PmClient(clientOptions).packageCatalog(options)}function packageActivate(target,options={},clientOptions={}){return new PmClient(clientOptions).packageActivate(target,options)}function packageDeactivate(target,options={},clientOptions={}){return new PmClient(clientOptions).packageDeactivate(target,options)}function upgrade(target,options={},clientOptions={}){return new PmClient(clientOptions).upgrade(target,options)}async function getContracts(pmRootOrOptions,options={}){const resolvedOptions=typeof pmRootOrOptions=="string"?{...options,pmRoot:pmRootOrOptions}:pmRootOrOptions??options,global2={json:!0,quiet:resolvedOptions.quiet??!0,noExtensions:resolvedOptions.noExtensions??!1,noPager:!0,profile:resolvedOptions.profile??!1,path:resolvedOptions.pmRoot};return runContracts(resolvedOptions,global2)}const extensionActivationGate=createAsyncReadWriteGate(),activeExtensionScope=new AsyncLocalStorage;function resetActiveExtensionRegistries(){setActiveExtensionHooks(createEmptyExtensionHookRegistry()),setActiveExtensionCommands(createEmptyExtensionCommandRegistry()),setActiveExtensionParsers(createEmptyExtensionParserRegistry()),setActiveExtensionPreflight(createEmptyExtensionPreflightRegistry()),setActiveExtensionServices(createEmptyExtensionServiceRegistry()),setActiveExtensionRenderers(createEmptyExtensionRendererRegistry()),setActiveExtensionRegistrations(createEmptyExtensionRegistrationRegistry())}async function withActiveExtensions(global2,explicitCwd,resolutionCwd,run){return runWithIsolatedExtensionRuntime(()=>explicitCwd===void 0?extensionActivationGate.read(()=>withActiveExtensionsExclusively(global2,resolutionCwd,run)):extensionActivationGate.write(()=>withCwd(explicitCwd,()=>withActiveExtensionsExclusively(global2,resolutionCwd,run))))}async function runWithActiveExtensions(options,run){const explicitCwd=options.cwd;if(activeExtensionScope.getStore()===!0&&explicitCwd===void 0&&options.noExtensions===!0){const pmRoot=resolvePmRoot(process.cwd(),options.path);return runWithIsolatedExtensionRuntime(()=>runWithDiscoveredContextIntentContracts({pmRoot},run))}const resolutionCwd=explicitCwd??process.cwd();return withActiveExtensions(globalOptions({path:options.path,noExtensions:options.noExtensions}),explicitCwd,resolutionCwd,()=>activeExtensionScope.run(!0,run))}async function withActiveExtensionsExclusively(global2,cwd,run){const pmRoot=resolvePmRoot(cwd,global2.path);if(global2.noExtensions)return resetActiveExtensionRegistries(),runWithDiscoveredContextIntentContracts({pmRoot},()=>run(null));if(!await pathExists(getSettingsPath(pmRoot)))return resetActiveExtensionRegistries(),run(null);let active=null,activated;try{const settings=await readSettings(pmRoot),loadResult=await loadExtensions({pmRoot,settings,cwd,noExtensions:!1}),activationResult=await activateExtensions({...loadResult,loaded:loadResult.loaded});activated={loadResult,activationResult},setActiveExtensionHooks(activationResult.hooks),setActiveExtensionCommands(activationResult.commands),setActiveExtensionParsers(activationResult.parsers),setActiveExtensionPreflight(activationResult.preflight),setActiveExtensionServices(activationResult.services),setActiveExtensionRenderers(activationResult.renderers),setActiveExtensionRegistrations(activationResult.registrations),active={registrations:activationResult.registrations,commands:activationResult.commands,pmRoot,packages:loadResult.loaded}}catch(error){resetActiveExtensionRegistries(),console.error("[pm-sdk] extension activation failed; continuing without active extensions:",error)}try{return await runWithDiscoveredContextIntentContracts({pmRoot,packages:active?.packages},()=>run(active))}finally{resetActiveExtensionRegistries(),activated&&await deactivateExtensions(activated.loadResult,activated.activationResult).catch(()=>{})}}function resolveActiveExtensionActionCommand(action,active){const normalizedAction=normalizeActionName(action);return active?.registrations.commands.find(entry=>normalizeActionName(entry.action)===normalizedAction)?.command??active?.commands.handlers.find(entry=>normalizeActionName(entry.command)===normalizedAction)?.command}async function dispatchActiveExtensionAction(action,args,options,global2,active){if(!active)throw new PmCliError(`Unsupported native pm action: ${action}`,EXIT_CODE.USAGE);const command=resolveActiveExtensionActionCommand(action,active);if(!command)throw new PmCliError(`Unsupported native pm action: ${action}`,EXIT_CODE.USAGE);const extensionAuthor=typeof options.author=="string"?options.author:global2.author,handlerResult=await runActiveCommandHandler({command:normalizeCommandPath(command),args:readStringArray(options.args??args.args),options:extensionOptionsFromArgs(args,options),global:{...global2,author:extensionAuthor},pm_root:active.pmRoot,sdk:createExtensionCommandSdk(active.pmRoot,PmClient.forActiveExtensionHost({pmRoot:active.pmRoot,author:extensionAuthor}),extensionAuthor,normalizeCommandPath(command))});if(!handlerResult.handled){const suffix=handlerResult.warnings.length>0?` (${handlerResult.warnings.join(", ")})`:"";throw new PmCliError(`Unsupported native pm action: ${action}${suffix}`,EXIT_CODE.USAGE)}return handlerResult.result}async function withCwd(cwd,run){const previous=process.cwd();process.chdir(cwd);try{return await run()}finally{process.chdir(previous)}}function resolveSdkActionInput(args){const rawAction=readRequiredString(args,"action"),normalizedAction=normalizeActionName(rawAction),alias=getOwnHandler(SDK_ACTION_ALIASES,normalizedAction),action=alias?.action??normalizedAction,resolvedArgs={...args,action};return alias?.options!==void 0&&(resolvedArgs.options={...alias.options,...asRecordClone(args.options)}),action==="package"&&(resolvedArgs.options={...asRecordClone(resolvedArgs.options),vocabulary:"package"}),{action,args:resolvedArgs}}async function runAction(args){const resolved=resolveSdkActionInput(args),global2=globalOptions(resolved.args),invalidateWorkspaceContractsCache=shouldInvalidateWorkspaceContractsCacheAfterAction(resolved.action),explicitCwd=readString(resolved.args,"cwd"),resolutionCwd=explicitCwd??process.cwd();resolved.action==="init"&&(global2[INIT_INVOCATION_CWD]=resolutionCwd),(resolved.action!=="init"||global2.path!==void 0||(process.env.PM_PATH?.trim().length??0)>0)&&(global2.path=resolvePmRoot(resolutionCwd,global2.path));try{return resolved.action==="history-attest"?await dispatchAction(resolved.action,resolved.args,global2,null):args[ACTIVE_EXTENSION_HOST_CONTEXT]===!0||activeExtensionScope.getStore()===!0?await dispatchAction(resolved.action,resolved.args,global2,null):await withActiveExtensions(global2,explicitCwd,resolutionCwd,activeExtensions=>dispatchAction(resolved.action,resolved.args,global2,activeExtensions))}finally{invalidateWorkspaceContractsCache&&clearWorkspaceContractsCache()}}function analyzeSdkActionCoverage(actions=PM_TOOL_ACTIONS){return actions.map(action=>{const normalized=normalizeActionName(action),alias=getOwnHandler(SDK_ACTION_ALIASES,normalized),resolvedAction=alias?.action??normalized,covered=getOwnHandler(SDK_ACTION_HANDLERS,resolvedAction)!==void 0;return{action,resolved_action:resolvedAction,covered,route:covered?alias?"alias":"native":"missing"}})}async function dispatchAction(action,args,global2,activeExtensions){const options=optionsWithAuthor(args,action);if(action==="create"||action==="update"){const{assertNativeMutationOptions}=await import("./runtime/mutation-admission.js");await assertNativeMutationOptions(action,args,options,global2.path,HOISTED_ACTION_OPTION_KEYS[action])}const handler=getOwnHandler(SDK_ACTION_HANDLERS,action),extensionCommand=handler?void 0:resolveActiveExtensionActionCommand(action,activeExtensions),readCommand=extensionCommand===void 0?action:`extension:${extensionCommand}`;validateReadOutputOptions(readCommand,options),normalizeReadOutputIncludeModeOptions(readCommand,options);const ctx={action,args,options,id:readString(args,"id"),force:args.force===!0||options.force===!0,global:global2,activeExtensions},result=handler?await handler(ctx):await dispatchActiveExtensionAction(action,args,options,global2,activeExtensions);if(action==="history-attest")return result;{options.resolvedOutputFormat="json";const projected=attachReadOutputContracts(readCommand,options,result);return await finalizeContextUsageEgress(resolvePmRoot(process.cwd(),global2.path),projected),projected}}const actionRunnerTestHooks={closeManyOptionsFromFlat,extensionOptionsFromArgs,globalOptions,mutationListOptions,normalizeActionName,normalizeCommandPath,normalizeMcpUpdateOptions,normalizeMcpOptionsArrays,optionsWithAuthor,readRequiredString,readScalarString,readScalarStringAllowBlank,readStringArray,updateManyOptionsFromFlat,withAddNoteOption,withFilesDiscoveryOptions,withMutationCompaction};(process.env.NODE_ENV==="test"||process.env.VITEST!==void 0||process.env.VITEST_WORKER_ID!==void 0)&&(globalThis.__pmCliActionRunnerTestHooks=actionRunnerTestHooks);import{readRequiredString as readRequiredString2}from"./runtime/context.js";export{BASELINE_ITEM_FORMAT_VERSION,BUILTIN_ITEM_TYPE_VALUES,CONFIDENCE_TEXT_VALUES,CONTEXT_OUTPUT_VALUES,CURRENT_ITEM_FORMAT_VERSION,DEFAULT_TERMINAL_TRANSITION_POLICY,DEPENDENCY_KIND_VALUES,EXIT_CODE,HISTORY_EVENT_CLASSIFICATION_VERSION,ISSUE_SEVERITY_VALUES,ITEM_TYPE_VALUES,MAINTENANCE_HISTORY_OPERATIONS,NEXT_OUTPUT_VALUES,PM_CLI_EXPECTED_ERROR_NAME,PM_GITIGNORE_END,PM_GITIGNORE_START,PmCliError2 as PmCliError,PmClient,PmCompleteListValidationError,RISK_VALUES,SEARCH_EXTENSION_FLAG_DEFINITIONS,STATUS_VALUES,SUBSTANTIVE_HISTORY_OPERATIONS,acquireLock,aggregate,analyzeSdkActionCoverage,append,appendHistoryEntry,applyTerminalOrderingPolicy,assertCompleteListResult,canonicalDocument,certifyCompleteListResult2 as certifyCompleteListResult,claim,claimNext,classifyHistoryEvent,classifyItemFormatVersion,clearWorkspaceContractsCache2 as clearWorkspaceContractsCache,close,closeItem,closeTask,comments,commitImportedItem,config,context,copy,create,createCompleteListOptions2 as createCompleteListOptions,createHistoryEntry,createPmCliExpectedError,deleteItem,deps,docs,duplicates,effectiveItemFormatVersion,emptyImportedDocument,ensurePmGitignore,ensureTrackerInitialized,extension,extensionActivate,extensionDeactivate,extensionList,files,filesDiscover,filesLookup,focus,gc,generateItemId,get,getActiveExtensionRegistrations,getContracts,getHistoryPath,getItemPath,getPmGitignoreBlock,getSettingsPath2 as getSettingsPath,getWorkspaceContracts,graph,health,historyCompact,historyCompactBulk,historyRedact,historyRepair,historyRepairAll,init,inspectCompleteListResult,isPmCliExpectedError,isTerminalStatus,isTimestampLiteral,jaccardSimilarity,learnings,list,listAllComplete,listAllItemMetadata,listAllItemMetadataLight,loadCreateTemplateOptions,locateItem,next,normalizeItemFormatVersion,normalizeItemId,normalizeItemMetadata,normalizeRawItemId,normalizeSimilarityText,normalizeStatusInput,notes,nowIso,packageActivate,packageCatalog,packageDeactivate,packageDescribe,packageDoctor,packageInstall,packageLifecycle,packageList,packageManage,packageReload,packageUninstall,parseTags,pathExists2 as pathExists,pauseTask,profile,profileApply,profileLint,profileList,profileShow,readBooleanOption,readCsvListOption,readFileIfExists,readLocatedItem,readRequiredString2 as readRequiredString,readSettings2 as readSettings,readStringOption,release,removeFileIfExists,renderCalendarMarkdown,renderCalendarToon,renderGuideMarkdown,reopen,requireTerminalReason,resolveCalendarOutputFormat,resolveGuideOutputFormat,resolveImplicitPmRoot,resolveItemTypeRegistry,resolvePmRoot2 as resolvePmRoot,resolveRuntimeFieldRegistry,resolveRuntimeStatusRegistry,resolveTerminalReason,restore,runAction,runActiveOnReadHooks,runActiveOnWriteHooks,runAggregate,runCalendar,runClose,runCloseTask,runCompletion,runContext,runCopy,runDelete,runDuplicates,runFocus,runGet,runGuide,runList,runNext,runPauseTask,runReindex,runReopen,runRestore,runSearch,runStartTask,runStats,runTemplatesList,runTemplatesSave,runTemplatesShow,runTestRunsList,runTestRunsLogs,runTestRunsResume,runTestRunsStatus,runTestRunsStop,runUpdate,runWithActiveExtensions,scanItemFormatVersions,schema,schemaAddField,schemaAddStatus,schemaAddType,schemaApplyPreset,schemaInferTypes,schemaList,schemaListFields,schemaRemapStatus,schemaRemoveField,schemaRemoveStatus,schemaRemoveType,schemaRenameField,schemaRenameType,schemaShow,schemaShowField,schemaShowStatus,scoreItemSimilarity,search,selectImportAuthor,serializeItemDocument,splitFrontMatter,startTask,stats,toEstimatedMinutesValue,toImportBoolean,toImportConfidence,toImportInteger,toImportLinkedDocs,toImportLinkedFiles,toImportLinkedTests,toImportLogEntries,toImportNormalizedEnum,toImportNumberMap,toImportPriority,toImportStatus,toImportStringList,toImportStringMap,toImportTags,toNonEmptyImportString,tokenizeSimilarityText,update,upgrade,validate,writeFileAtomic};
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="25588333-8aa9-5861-8966-3253b8a4c432")}catch{}})();import{AsyncLocalStorage}from"node:async_hooks";import{createEmptyExtensionCommandRegistry,createEmptyExtensionHookRegistry,createEmptyExtensionParserRegistry,createEmptyExtensionPreflightRegistry,createEmptyExtensionRegistrationRegistry,createEmptyExtensionRendererRegistry,createEmptyExtensionServiceRegistry}from"../core/extensions/extension-registries.js";import{activateExtensions,deactivateExtensions,loadExtensions,runActiveCommandHandler,runWithIsolatedExtensionRuntime,setActiveExtensionCommands,setActiveExtensionHooks,setActiveExtensionParsers,setActiveExtensionPreflight,setActiveExtensionRegistrations,setActiveExtensionRenderers,setActiveExtensionServices}from"../core/extensions/index.js";import{pathExists}from"../core/fs/fs-utils.js";import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";import{asRecordClone}from"../core/shared/primitives.js";import{HOISTED_ACTION_OPTION_KEYS}from"./runtime-input.js";import{createAsyncReadWriteGate}from"../core/shared/serial-queue.js";import{getSettingsPath,resolvePmRoot}from"../core/store/paths.js";import{readSettings}from"../core/store/settings.js";import{PM_TOOL_ACTIONS}from"./cli-contracts/enum-contracts.js";import{runContracts}from"./cli-contracts/runtime-contracts.js";import{attachReadOutputContracts}from"./context-intent-contracts.js";import{runWithDiscoveredContextIntentContracts}from"./context-intent-runtime.js";import{finalizeContextUsageEgress}from"./context/usage-egress.js";import{createExtensionCommandSdk}from"./extension-command-context.js";import{INIT_INVOCATION_CWD}from"./init.js";import{certifyCompleteListResult,createCompleteListOptions}from"./query/complete-list.js";import{listClientItemMetadataLight}from"./query/light-metadata.js";import{normalizeReadOutputIncludeModeOptions,validateReadOutputOptions}from"./read-output-contracts.js";import{SDK_ACTION_ALIASES}from"./runtime-action-aliases.js";import{closeManyOptionsFromFlat,extensionOptionsFromArgs,actionGlobalOptions as globalOptions,mutationListOptions,mutationOptionsWithOverrides,normalizeActionName,normalizeCommandPath,normalizeMcpOptionsArrays,normalizeMcpUpdateOptions,optionsWithAuthor,readRuntimeScalarString as readScalarString,readRuntimeScalarStringAllowBlank as readScalarStringAllowBlank,readRuntimeString as readString,readRuntimeStringArray as readStringArray,shouldInvalidateWorkspaceContractsCacheAfterAction,updateManyOptionsFromFlat,withAddNoteOption,withFilesDiscoveryOptions,withMutationCompaction}from"./runtime-input.js";import{SDK_ACTION_HANDLERS}from"./runtime/actions.js";import{getOwnHandler,readRequiredString}from"./runtime/context.js";import{clearWorkspaceContractsCache}from"./workspace-contracts-cache.js";import{PM_GITIGNORE_END,PM_GITIGNORE_START,ensurePmGitignore,getPmGitignoreBlock}from"./workspace.js";import{SEARCH_EXTENSION_FLAG_DEFINITIONS}from"./extension-contracts.js";export*from"./cli-contracts/agent-output-contracts.js";import{PmCompleteListValidationError,assertCompleteListResult,certifyCompleteListResult as certifyCompleteListResult2,createCompleteListOptions as createCompleteListOptions2,inspectCompleteListResult}from"./query/complete-list.js";import{getWorkspaceContracts}from"./query/workspace-contracts.js";import{clearWorkspaceContractsCache as clearWorkspaceContractsCache2}from"./workspace-contracts-cache.js";export*from"./governance/workflow-policy.js";import{runCloseTask,runPauseTask,runStartTask}from"./lifecycle/task-composition.js";import{getActiveExtensionRegistrations,runActiveOnReadHooks,runActiveOnWriteHooks}from"../core/extensions/index.js";import{pathExists as pathExists2,readFileIfExists,removeFileIfExists,writeFileAtomic}from"../core/fs/fs-utils.js";import{appendHistoryEntry,createHistoryEntry}from"../core/history/history.js";import{HISTORY_EVENT_CLASSIFICATION_VERSION,MAINTENANCE_HISTORY_OPERATIONS,SUBSTANTIVE_HISTORY_OPERATIONS,classifyHistoryEvent}from"../core/history/event-classification.js";import{generateItemId,normalizeItemId,normalizeRawItemId}from"../core/item/id.js";import{readBooleanOption,readCsvListOption,readStringOption}from"./package-runtime-options.js";import{PM_CLI_EXPECTED_ERROR_NAME,createPmCliExpectedError,isPmCliExpectedError}from"./errors.js";import{commitImportedItem,emptyImportedDocument,ensureTrackerInitialized,selectImportAuthor,toEstimatedMinutesValue,toImportBoolean,toImportConfidence,toImportInteger,toImportLinkedDocs,toImportLinkedFiles,toImportLinkedTests,toImportLogEntries,toImportNormalizedEnum,toImportNumberMap,toImportPriority,toImportStatus,toImportStringList,toImportStringMap,toImportTags,toNonEmptyImportString}from"./package-import-adapters.js";import{canonicalDocument,normalizeItemMetadata,serializeItemDocument,splitFrontMatter}from"../core/item/item-format.js";import{BASELINE_ITEM_FORMAT_VERSION,CURRENT_ITEM_FORMAT_VERSION,classifyItemFormatVersion,effectiveItemFormatVersion,normalizeItemFormatVersion,scanItemFormatVersions}from"../core/item/item-format-version.js";import{parseTags}from"../core/item/parse.js";import{isTerminalStatus,normalizeStatusInput}from"../core/item/status.js";import{resolveItemTypeRegistry}from"../core/item/type-registry.js";import{acquireLock,acquireLockLease}from"../core/lock/lock.js";import{resolveRuntimeFieldRegistry,resolveRuntimeStatusRegistry}from"../core/schema/runtime-schema.js";import{PmCliError as PmCliError2}from"../core/shared/errors.js";import{isTimestampLiteral,nowIso}from"../core/shared/time.js";import{jaccardSimilarity,normalizeSimilarityText,scoreItemSimilarity,tokenizeSimilarityText}from"./similarity-scoring.js";import{listAllItemMetadata,listAllItemMetadataLight,locateItem,readLocatedItem}from"../core/store/item-store.js";import{getHistoryPath,getItemPath,getSettingsPath as getSettingsPath2,resolveImplicitPmRoot,resolvePmRoot as resolvePmRoot2}from"../core/store/paths.js";import{readSettings as readSettings2}from"../core/store/settings.js";import{runAggregate}from"./query/aggregate.js";import{CONTEXT_OUTPUT_VALUES,runContext}from"./query/context.js";import{runGet}from"./query/get.js";import{runList}from"./query/list.js";import{closeItem,runClose}from"./lifecycle/close.js";import{runCopy}from"./lifecycle/copy.js";import{runDelete}from"./lifecycle/delete.js";import{runFocus}from"./lifecycle/focus.js";import{runRestore}from"./lifecycle/restore.js";import{DEFAULT_TERMINAL_TRANSITION_POLICY,applyTerminalOrderingPolicy,requireTerminalReason,resolveTerminalReason}from"./lifecycle-policy.js";import{runUpdate}from"./lifecycle/update.js";import{runReopen}from"./lifecycle/reopen.js";import{NEXT_OUTPUT_VALUES,runNext}from"./query/next.js";import{runSearch}from"./query/search.js";import{runStats}from"./stats.js";import{runDuplicates}from"./duplicates.js";import{renderCalendarMarkdown,renderCalendarToon,resolveCalendarOutputFormat,runCalendar}from"./query/calendar.js";import{renderGuideMarkdown,resolveGuideOutputFormat,runGuide}from"./guide.js";import{runCompletion}from"./completion.js";import{runReindex}from"./governance/reindex.js";import{loadCreateTemplateOptions,runTemplatesList,runTemplatesSave,runTemplatesShow}from"./templates.js";import{runTestRunsList,runTestRunsLogs,runTestRunsResume,runTestRunsStatus,runTestRunsStop}from"./test/runs.js";import{BUILTIN_ITEM_TYPE_VALUES,CONFIDENCE_TEXT_VALUES,DEPENDENCY_KIND_VALUES,ISSUE_SEVERITY_VALUES,ITEM_TYPE_VALUES,RISK_VALUES,STATUS_VALUES}from"../types/index.js";const ACTIVE_EXTENSION_HOST_CONTEXT=Symbol("pm.active-extension-host-context");function splitFullClientMutationOptions(options){return{fullChangedFields:!0,options}}class PmClient{defaults;constructor(options={}){this.defaults={...options.pmRoot===void 0?{}:{path:options.pmRoot},...options.cwd===void 0?{}:{cwd:options.cwd},...options.author===void 0?{}:{author:options.author},...options.noExtensions===void 0?{}:{noExtensions:options.noExtensions}}}static forActiveExtensionHost(options){const client=new PmClient({...options,noExtensions:!0});return client.defaults[ACTIVE_EXTENSION_HOST_CONTEXT]=!0,client}run(action,args={}){return runAction({...this.defaults,...args,action})}runTyped(action,args={}){return this.run(action,args)}context(options={}){return this.runTyped("context",{options})}listAllItemMetadataLight(){return listClientItemMetadataLight(this.defaults.path,this.defaults.cwd)}list(options={}){return this.runTyped("list",{options})}async listAllComplete(options={}){return certifyCompleteListResult(await this.list(createCompleteListOptions(options)))}search(query,options={}){return this.runTyped("search",{query,options})}get(id,options={}){return this.runTyped("get",{id,options})}next(options={}){return this.runTyped("next",{options})}aggregate(options={}){return this.runTyped("aggregate",{options})}stats(options={}){return this.runTyped("stats",{options})}duplicates(options={}){return this.runTyped("duplicates",{options})}comments(id,options={}){return this.runTyped("comments",{id,options})}notes(id,options={}){return this.runTyped("notes",{id,options})}learnings(id,options={}){return this.runTyped("learnings",{id,options})}files(id,options={}){return this.runTyped("files",{id,options})}filesDiscover(id,options={}){return this.runTyped("files-discover",{id,options})}filesLookup(options){return this.runTyped("files-lookup",{options})}docs(id,options={}){return this.runTyped("docs",{id,options})}deps(id,options={}){return this.runTyped("deps",{id,options})}graph(subcommand,ids={},options={}){return this.runTyped("graph",{subcommand,...ids,options})}append(id,body,options={}){return this.runTyped("append",{id,...splitFullClientMutationOptions(mutationOptionsWithOverrides(options,{body}))})}init(prefix,options={}){return this.runTyped("init",{...prefix===void 0?{}:{prefix},options})}config(scope,configAction,key,value,options={}){return this.runTyped("config",{scope,configAction,...key===void 0?{}:{key},...value===void 0?{}:{value},options})}schema(subcommand,options={}){return this.runTyped("schema",{options:{...options,subcommand}})}workflowPolicy(action,name,options={}){return this.runTyped("schema",{name,options:{...options,subcommand:action}})}schemaList(){return this.runTyped("schema",{options:{subcommand:"list"}})}schemaShow(name){return this.runTyped("schema",{name,options:{subcommand:"show"}})}schemaAddType(name,options={}){return this.runTyped("schema",{name,options:{...options,subcommand:"add-type"}})}schemaRemoveType(name,options={}){return this.runTyped("schema",{name,options:{...options,subcommand:"remove-type"}})}schemaAddStatus(name,options={}){return this.runTyped("schema",{name,options:{...options,subcommand:"add-status"}})}schemaRemoveStatus(name,options={}){return this.runTyped("schema",{name,options:{...options,subcommand:"remove-status"}})}schemaAddField(name,options={}){const{type,...mutationOptions}=options;return this.runTyped("schema",{name,options:{...mutationOptions,fieldType:type,subcommand:"add-field"}})}schemaRemoveField(name,options={}){return this.runTyped("schema",{name,options:{...options,subcommand:"remove-field"}})}schemaListFields(){return this.runTyped("schema",{options:{subcommand:"list-fields"}})}schemaShowField(name){return this.runTyped("schema",{name,options:{subcommand:"show-field"}})}schemaApplyPreset(typePreset,options={}){return this.runTyped("schema",{typePreset,options:{...options,subcommand:"apply-preset"}})}schemaInferTypes(options={}){return this.runTyped("schema",{options:{...options,subcommand:"add-type",infer:!0}})}schemaRenameType(from,to,options){return this.runTyped("schema",{name:from,options:{...options,subcommand:"rename-type",to}})}schemaRenameField(from,to,options,type){return this.runTyped("schema",{name:from,options:{...options,subcommand:"rename-field",to,...type?{fieldTypeScope:type}:{}}})}schemaRemapStatus(from,to,options){return this.runTyped("schema",{name:from,options:{...options,subcommand:"remap-status",to}})}schemaShowStatus(name){return this.runTyped("schema",{name,options:{subcommand:"show-status"}})}profile(subcommand,options={}){return this.runTyped("profile",{options:{...options,subcommand}})}profileList(){return this.runTyped("profile",{options:{subcommand:"list"}})}profileShow(name){return this.runTyped("profile",{name,options:{subcommand:"show"}})}profileApply(name,options={}){return this.runTyped("profile",{name,options:{...options,subcommand:"apply"}})}profileLint(name){return this.runTyped("profile",{name,options:{subcommand:"lint"}})}validate(options={}){return this.runTyped("validate",{options})}health(options={}){return this.runTyped("health",{options})}gc(options={}){return this.runTyped("gc",{options})}assurance(input){return this.runTyped("assurance",{options:{...input,subcommand:input.action}})}historyRedact(id,options){return this.runTyped("history-redact",{id,options})}historyRepair(id,options={}){return this.runTyped("history-repair",{id,options})}historyRepairAll(options={}){return this.runTyped("history-repair",{options:{...options,all:!0}})}historyAttest(options={}){return this.runTyped("history-attest",{options})}historyCompact(id,options={}){return this.runTyped("history-compact",{id,options})}historyCompactBulk(options){return this.runTyped("history-compact",{options})}historyAuthorAcknowledge(options){return this.runTyped("history-author-acknowledge",{historyEvent:(options.events??[]).map(event=>`${event.item_id}:${String(event.line)}`),allActionable:options.all_actionable===!0,dryRun:options.dry_run===!0,planFingerprint:options.plan_fingerprint,limit:options.coordinate_limit,attributedAuthor:options.attributed_author,reviewer:options.reviewer,reason:options.reason})}plan(subcommand,id,options={},stepRef,reorderTo){return this.runTyped("plan",{fullChangedFields:!0,...id===void 0?{}:{id},...stepRef===void 0?{}:{stepRef},...reorderTo===void 0?{}:{reorderTo},options:mutationOptionsWithOverrides(options,{subcommand})})}planCreate(options){return this.plan("create",void 0,options)}planShow(id,options={}){return this.plan("show",id,options)}planAddStep(id,options){return this.plan("add-step",id,options)}planUpdateStep(id,stepRef,options){return this.plan("update-step",id,options,stepRef)}planCompleteStep(id,stepRef,options={}){return this.plan("complete-step",id,options,stepRef)}planBlockStep(id,stepRef,options){return this.plan("block-step",id,options,stepRef)}planReorderStep(id,stepRef,reorderTo,options={}){return this.plan("reorder-step",id,options,stepRef,reorderTo)}planRemoveStep(id,stepRef,options={}){return this.plan("remove-step",id,options,stepRef)}planLink(id,stepRef,options){return this.plan("link",id,options,stepRef)}planUnlink(id,stepRef,options){return this.plan("unlink",id,options,stepRef)}planDecision(id,options){return this.plan("decision",id,options)}planDiscovery(id,options){return this.plan("discovery",id,options)}planValidation(id,options){return this.plan("validation",id,options)}planResume(id,options){return this.plan("resume",id,options)}planApprove(id,options={}){return this.plan("approve",id,options)}planMaterialize(id,options){return this.plan("materialize",id,options)}create(options={}){return this.runTyped("create",splitFullClientMutationOptions(options))}update(id,options={}){return this.runTyped("update",{id,...splitFullClientMutationOptions(options)})}reopen(id,reason,options={}){return this.runTyped("item-reopen",{id,reason,fullChangedFields:!0,options})}close(id,reason,options={}){return this.runTyped("close",{id,reason,...splitFullClientMutationOptions(options)})}claim(id,options={}){return this.runTyped("claim",{id,...splitFullClientMutationOptions(options)})}claimNext(options={}){return this.runTyped("claim",{next:!0,...splitFullClientMutationOptions(options)})}release(id,options={}){return this.runTyped("release",{id,...splitFullClientMutationOptions(options)})}copy(id,options={}){return this.runTyped("copy",{id,...splitFullClientMutationOptions(options)})}delete(id,options={}){return this.runTyped("delete",{id,...splitFullClientMutationOptions(options)})}restore(id,target,options={}){return this.runTyped("restore",{fullChangedFields:!0,id,options:{...options,target}})}focus(id,options={}){return this.runTyped("focus",{...id===void 0?{}:{id},...splitFullClientMutationOptions(options)})}startTask(id,options={}){return this.runTyped("start-task",{id,...splitFullClientMutationOptions(options)})}pauseTask(id,options={}){return this.runTyped("pause-task",{id,...splitFullClientMutationOptions(options)})}closeTask(id,reason,options={}){return this.runTyped("close-task",{id,reason,...splitFullClientMutationOptions(options)})}extension(target,options={}){return this.runTyped("extension",{...target===void 0?{}:{target},options})}extensionList(options={}){return this.extension("list",options)}extensionActivate(target,options={}){return this.runTyped("extension-activate",{target,options})}extensionDeactivate(target,options={}){return this.runTyped("extension-deactivate",{target,options})}package(target,options={}){return this.runTyped("package",{...target===void 0?{}:{target},options:{...options,vocabulary:"package"}})}packageList(options={}){return this.package("list",options)}packageInstall(target,options={}){return this.runTyped("package-install",{target,options})}packageUninstall(target,options={}){return this.runTyped("package-uninstall",{target,options})}packageDoctor(options={}){return this.runTyped("package-doctor",{options})}packageManage(target,options={}){return this.runTyped("package-manage",{...target===void 0?{}:{target},options})}packageDescribe(target,options={}){return this.runTyped("package-describe",{...target===void 0?{}:{target},options})}packageReload(options={}){return this.runTyped("package-reload",{options})}packageCatalog(options={}){return this.runTyped("package-catalog",{options})}packageActivate(target,options={}){return this.runTyped("package-activate",{target,options})}packageDeactivate(target,options={}){return this.runTyped("package-deactivate",{target,options})}packageMigrate(options={}){return this.package(void 0,{...options,migrate:!0})}upgrade(target,options={}){return this.runTyped("upgrade",{...target===void 0?{}:{target},options})}}function context(options={},clientOptions={}){return new PmClient(clientOptions).context(options)}function list(options={},clientOptions={}){return new PmClient(clientOptions).list(options)}function listAllComplete(options={},clientOptions={}){return new PmClient(clientOptions).listAllComplete(options)}function search(query,options={},clientOptions={}){return new PmClient(clientOptions).search(query,options)}function get(id,options={},clientOptions={}){return new PmClient(clientOptions).get(id,options)}function next(options={},clientOptions={}){return new PmClient(clientOptions).next(options)}function aggregate(options={},clientOptions={}){return new PmClient(clientOptions).aggregate(options)}function stats(options={},clientOptions={}){return new PmClient(clientOptions).stats(options)}function duplicates(options={},clientOptions={}){return new PmClient(clientOptions).duplicates(options)}function comments(id,options={},clientOptions={}){return new PmClient(clientOptions).comments(id,options)}function notes(id,options={},clientOptions={}){return new PmClient(clientOptions).notes(id,options)}function learnings(id,options={},clientOptions={}){return new PmClient(clientOptions).learnings(id,options)}function files(id,options={},clientOptions={}){return new PmClient(clientOptions).files(id,options)}function filesDiscover(id,options={},clientOptions={}){return new PmClient(clientOptions).filesDiscover(id,options)}function filesLookup(options,clientOptions={}){return new PmClient(clientOptions).filesLookup(options)}function docs(id,options={},clientOptions={}){return new PmClient(clientOptions).docs(id,options)}function deps(id,options={},clientOptions={}){return new PmClient(clientOptions).deps(id,options)}function graph(subcommand,ids={},options={},clientOptions={}){return new PmClient(clientOptions).graph(subcommand,ids,options)}function append(id,body,options={},clientOptions={}){return new PmClient(clientOptions).append(id,body,options)}function init(prefix,options={},clientOptions={}){return new PmClient(clientOptions).init(prefix,options)}function config(scope,configAction,key,value,options={},clientOptions={}){return new PmClient(clientOptions).config(scope,configAction,key,value,options)}function schema(subcommand,options={},clientOptions={}){return new PmClient(clientOptions).schema(subcommand,options)}function schemaList(clientOptions={}){return new PmClient(clientOptions).schemaList()}function schemaShow(name,clientOptions={}){return new PmClient(clientOptions).schemaShow(name)}function schemaAddType(name,options={},clientOptions={}){return new PmClient(clientOptions).schemaAddType(name,options)}function schemaRemoveType(name,options={},clientOptions={}){return new PmClient(clientOptions).schemaRemoveType(name,options)}function schemaAddStatus(name,options={},clientOptions={}){return new PmClient(clientOptions).schemaAddStatus(name,options)}function schemaRemoveStatus(name,options={},clientOptions={}){return new PmClient(clientOptions).schemaRemoveStatus(name,options)}function schemaAddField(name,options={},clientOptions={}){return new PmClient(clientOptions).schemaAddField(name,options)}function schemaRemoveField(name,options={},clientOptions={}){return new PmClient(clientOptions).schemaRemoveField(name,options)}function schemaListFields(clientOptions={}){return new PmClient(clientOptions).schemaListFields()}function schemaShowField(name,clientOptions={}){return new PmClient(clientOptions).schemaShowField(name)}function schemaApplyPreset(typePreset,options={},clientOptions={}){return new PmClient(clientOptions).schemaApplyPreset(typePreset,options)}function schemaInferTypes(options={},clientOptions={}){return new PmClient(clientOptions).schemaInferTypes(options)}function schemaRenameType(from,to,options,clientOptions={}){return new PmClient(clientOptions).schemaRenameType(from,to,options)}function schemaRenameField(from,to,options,type,clientOptions={}){return new PmClient(clientOptions).schemaRenameField(from,to,options,type)}function schemaRemapStatus(from,to,options,clientOptions={}){return new PmClient(clientOptions).schemaRemapStatus(from,to,options)}function schemaShowStatus(name,clientOptions={}){return new PmClient(clientOptions).schemaShowStatus(name)}function profile(subcommand,options={},clientOptions={}){return new PmClient(clientOptions).profile(subcommand,options)}function profileList(clientOptions={}){return new PmClient(clientOptions).profileList()}function profileShow(name,clientOptions={}){return new PmClient(clientOptions).profileShow(name)}function profileApply(name,options={},clientOptions={}){return new PmClient(clientOptions).profileApply(name,options)}function profileLint(name,clientOptions={}){return new PmClient(clientOptions).profileLint(name)}function validate(options={},clientOptions={}){return new PmClient(clientOptions).validate(options)}function health(options={},clientOptions={}){return new PmClient(clientOptions).health(options)}function gc(options={},clientOptions={}){return new PmClient(clientOptions).gc(options)}function historyRedact(id,options,clientOptions={}){return new PmClient(clientOptions).historyRedact(id,options)}function historyRepair(id,options={},clientOptions={}){return new PmClient(clientOptions).historyRepair(id,options)}function historyRepairAll(options={},clientOptions={}){return new PmClient(clientOptions).historyRepairAll(options)}function historyCompact(id,options={},clientOptions={}){return new PmClient(clientOptions).historyCompact(id,options)}function historyCompactBulk(options,clientOptions={}){return new PmClient(clientOptions).historyCompactBulk(options)}function create(options={},clientOptions={}){return new PmClient(clientOptions).create(options)}function update(id,options={},clientOptions={}){return new PmClient(clientOptions).update(id,options)}function reopen(id,reason,options={},clientOptions={}){return new PmClient(clientOptions).reopen(id,reason,options)}function close(id,reason,options={},clientOptions={}){return new PmClient(clientOptions).close(id,reason,options)}function claim(id,options={},clientOptions={}){return new PmClient(clientOptions).claim(id,options)}function claimNext(options={},clientOptions={}){return new PmClient(clientOptions).claimNext(options)}function release(id,options={},clientOptions={}){return new PmClient(clientOptions).release(id,options)}function copy(id,options={},clientOptions={}){return new PmClient(clientOptions).copy(id,options)}function deleteItem(id,options={},clientOptions={}){return new PmClient(clientOptions).delete(id,options)}function restore(id,target,options={},clientOptions={}){return new PmClient(clientOptions).restore(id,target,options)}function focus(id,options={},clientOptions={}){return new PmClient(clientOptions).focus(id,options)}function startTask(id,options={},clientOptions={}){return new PmClient(clientOptions).startTask(id,options)}function pauseTask(id,options={},clientOptions={}){return new PmClient(clientOptions).pauseTask(id,options)}function closeTask(id,reason,options={},clientOptions={}){return new PmClient(clientOptions).closeTask(id,reason,options)}function extension(target,options={},clientOptions={}){return new PmClient(clientOptions).extension(target,options)}function extensionList(options={},clientOptions={}){return new PmClient(clientOptions).extensionList(options)}function extensionActivate(target,options={},clientOptions={}){return new PmClient(clientOptions).extensionActivate(target,options)}function extensionDeactivate(target,options={},clientOptions={}){return new PmClient(clientOptions).extensionDeactivate(target,options)}function packageLifecycle(target,options={},clientOptions={}){return new PmClient(clientOptions).package(target,options)}function packageList(options={},clientOptions={}){return new PmClient(clientOptions).packageList(options)}function packageInstall(target,options={},clientOptions={}){return new PmClient(clientOptions).packageInstall(target,options)}function packageUninstall(target,options={},clientOptions={}){return new PmClient(clientOptions).packageUninstall(target,options)}function packageDoctor(options={},clientOptions={}){return new PmClient(clientOptions).packageDoctor(options)}function packageManage(target,options={},clientOptions={}){return new PmClient(clientOptions).packageManage(target,options)}function packageDescribe(target,options={},clientOptions={}){return new PmClient(clientOptions).packageDescribe(target,options)}function packageReload(options={},clientOptions={}){return new PmClient(clientOptions).packageReload(options)}function packageCatalog(options={},clientOptions={}){return new PmClient(clientOptions).packageCatalog(options)}function packageActivate(target,options={},clientOptions={}){return new PmClient(clientOptions).packageActivate(target,options)}function packageDeactivate(target,options={},clientOptions={}){return new PmClient(clientOptions).packageDeactivate(target,options)}function upgrade(target,options={},clientOptions={}){return new PmClient(clientOptions).upgrade(target,options)}async function getContracts(pmRootOrOptions,options={}){const resolvedOptions=typeof pmRootOrOptions=="string"?{...options,pmRoot:pmRootOrOptions}:pmRootOrOptions??options,global2={json:!0,quiet:resolvedOptions.quiet??!0,noExtensions:resolvedOptions.noExtensions??!1,noPager:!0,profile:resolvedOptions.profile??!1,path:resolvedOptions.pmRoot};return runContracts(resolvedOptions,global2)}const extensionActivationGate=createAsyncReadWriteGate(),activeExtensionScope=new AsyncLocalStorage;function resetActiveExtensionRegistries(){setActiveExtensionHooks(createEmptyExtensionHookRegistry()),setActiveExtensionCommands(createEmptyExtensionCommandRegistry()),setActiveExtensionParsers(createEmptyExtensionParserRegistry()),setActiveExtensionPreflight(createEmptyExtensionPreflightRegistry()),setActiveExtensionServices(createEmptyExtensionServiceRegistry()),setActiveExtensionRenderers(createEmptyExtensionRendererRegistry()),setActiveExtensionRegistrations(createEmptyExtensionRegistrationRegistry())}async function withActiveExtensions(global2,explicitCwd,resolutionCwd,run){return runWithIsolatedExtensionRuntime(()=>explicitCwd===void 0?extensionActivationGate.read(()=>withActiveExtensionsExclusively(global2,resolutionCwd,run)):extensionActivationGate.write(()=>withCwd(explicitCwd,()=>withActiveExtensionsExclusively(global2,resolutionCwd,run))))}async function runWithActiveExtensions(options,run){const explicitCwd=options.cwd;if(activeExtensionScope.getStore()===!0&&explicitCwd===void 0&&options.noExtensions===!0){const pmRoot=resolvePmRoot(process.cwd(),options.path);return runWithIsolatedExtensionRuntime(()=>runWithDiscoveredContextIntentContracts({pmRoot},run))}const resolutionCwd=explicitCwd??process.cwd();return withActiveExtensions(globalOptions({path:options.path,noExtensions:options.noExtensions}),explicitCwd,resolutionCwd,()=>activeExtensionScope.run(!0,run))}async function withActiveExtensionsExclusively(global2,cwd,run){const pmRoot=resolvePmRoot(cwd,global2.path);if(global2.noExtensions)return resetActiveExtensionRegistries(),runWithDiscoveredContextIntentContracts({pmRoot},()=>run(null));if(!await pathExists(getSettingsPath(pmRoot)))return resetActiveExtensionRegistries(),run(null);let active=null,activated;try{const settings=await readSettings(pmRoot),loadResult=await loadExtensions({pmRoot,settings,cwd,noExtensions:!1}),activationResult=await activateExtensions({...loadResult,loaded:loadResult.loaded});activated={loadResult,activationResult},setActiveExtensionHooks(activationResult.hooks),setActiveExtensionCommands(activationResult.commands),setActiveExtensionParsers(activationResult.parsers),setActiveExtensionPreflight(activationResult.preflight),setActiveExtensionServices(activationResult.services),setActiveExtensionRenderers(activationResult.renderers),setActiveExtensionRegistrations(activationResult.registrations),active={registrations:activationResult.registrations,commands:activationResult.commands,pmRoot,packages:loadResult.loaded}}catch(error){resetActiveExtensionRegistries(),console.error("[pm-sdk] extension activation failed; continuing without active extensions:",error)}try{return await runWithDiscoveredContextIntentContracts({pmRoot,packages:active?.packages},()=>run(active))}finally{resetActiveExtensionRegistries(),activated&&await deactivateExtensions(activated.loadResult,activated.activationResult).catch(()=>{})}}function resolveActiveExtensionActionCommand(action,active){const normalizedAction=normalizeActionName(action);return active?.registrations.commands.find(entry=>normalizeActionName(entry.action)===normalizedAction)?.command??active?.commands.handlers.find(entry=>normalizeActionName(entry.command)===normalizedAction)?.command}async function dispatchActiveExtensionAction(action,args,options,global2,active){if(!active)throw new PmCliError(`Unsupported native pm action: ${action}`,EXIT_CODE.USAGE);const command=resolveActiveExtensionActionCommand(action,active);if(!command)throw new PmCliError(`Unsupported native pm action: ${action}`,EXIT_CODE.USAGE);const extensionAuthor=typeof options.author=="string"?options.author:global2.author,handlerResult=await runActiveCommandHandler({command:normalizeCommandPath(command),args:readStringArray(options.args??args.args),options:extensionOptionsFromArgs(args,options),global:{...global2,author:extensionAuthor},pm_root:active.pmRoot,sdk:createExtensionCommandSdk(active.pmRoot,PmClient.forActiveExtensionHost({pmRoot:active.pmRoot,author:extensionAuthor}),extensionAuthor,normalizeCommandPath(command))});if(!handlerResult.handled){const suffix=handlerResult.warnings.length>0?` (${handlerResult.warnings.join(", ")})`:"";throw new PmCliError(`Unsupported native pm action: ${action}${suffix}`,EXIT_CODE.USAGE)}return handlerResult.result}async function withCwd(cwd,run){const previous=process.cwd();process.chdir(cwd);try{return await run()}finally{process.chdir(previous)}}function resolveSdkActionInput(args){const rawAction=readRequiredString(args,"action"),normalizedAction=normalizeActionName(rawAction),alias=getOwnHandler(SDK_ACTION_ALIASES,normalizedAction),action=alias?.action??normalizedAction,resolvedArgs={...args,action};return alias?.options!==void 0&&(resolvedArgs.options={...alias.options,...asRecordClone(args.options)}),action==="package"&&(resolvedArgs.options={...asRecordClone(resolvedArgs.options),vocabulary:"package"}),{action,args:resolvedArgs}}async function runAction(args){const resolved=resolveSdkActionInput(args),global2=globalOptions(resolved.args),invalidateWorkspaceContractsCache=shouldInvalidateWorkspaceContractsCacheAfterAction(resolved.action),explicitCwd=readString(resolved.args,"cwd"),resolutionCwd=explicitCwd??process.cwd();resolved.action==="init"&&(global2[INIT_INVOCATION_CWD]=resolutionCwd),(resolved.action!=="init"||global2.path!==void 0||(process.env.PM_PATH?.trim().length??0)>0)&&(global2.path=resolvePmRoot(resolutionCwd,global2.path));try{return resolved.action==="history-attest"?await dispatchAction(resolved.action,resolved.args,global2,null):args[ACTIVE_EXTENSION_HOST_CONTEXT]===!0||activeExtensionScope.getStore()===!0?await dispatchAction(resolved.action,resolved.args,global2,null):await withActiveExtensions(global2,explicitCwd,resolutionCwd,activeExtensions=>dispatchAction(resolved.action,resolved.args,global2,activeExtensions))}finally{invalidateWorkspaceContractsCache&&clearWorkspaceContractsCache()}}function analyzeSdkActionCoverage(actions=PM_TOOL_ACTIONS){return actions.map(action=>{const normalized=normalizeActionName(action),alias=getOwnHandler(SDK_ACTION_ALIASES,normalized),resolvedAction=alias?.action??normalized,covered=getOwnHandler(SDK_ACTION_HANDLERS,resolvedAction)!==void 0;return{action,resolved_action:resolvedAction,covered,route:covered?alias?"alias":"native":"missing"}})}async function dispatchAction(action,args,global2,activeExtensions){const options=optionsWithAuthor(args,action);if(action==="create"||action==="update"){const{assertNativeMutationOptions}=await import("./runtime/mutation-admission.js");await assertNativeMutationOptions(action,args,options,global2.path,HOISTED_ACTION_OPTION_KEYS[action])}const handler=getOwnHandler(SDK_ACTION_HANDLERS,action),extensionCommand=handler?void 0:resolveActiveExtensionActionCommand(action,activeExtensions),readCommand=extensionCommand===void 0?action:`extension:${extensionCommand}`;validateReadOutputOptions(readCommand,options),normalizeReadOutputIncludeModeOptions(readCommand,options);const ctx={action,args,options,id:readString(args,"id"),force:args.force===!0||options.force===!0,global:global2,activeExtensions},result=handler?await handler(ctx):await dispatchActiveExtensionAction(action,args,options,global2,activeExtensions);if(action==="history-attest")return result;{options.resolvedOutputFormat="json";const projected=attachReadOutputContracts(readCommand,options,result);return await finalizeContextUsageEgress(resolvePmRoot(process.cwd(),global2.path),projected),projected}}const actionRunnerTestHooks={closeManyOptionsFromFlat,extensionOptionsFromArgs,globalOptions,mutationListOptions,normalizeActionName,normalizeCommandPath,normalizeMcpUpdateOptions,normalizeMcpOptionsArrays,optionsWithAuthor,readRequiredString,readScalarString,readScalarStringAllowBlank,readStringArray,updateManyOptionsFromFlat,withAddNoteOption,withFilesDiscoveryOptions,withMutationCompaction};(process.env.NODE_ENV==="test"||process.env.VITEST!==void 0||process.env.VITEST_WORKER_ID!==void 0)&&(globalThis.__pmCliActionRunnerTestHooks=actionRunnerTestHooks);import{readRequiredString as readRequiredString2}from"./runtime/context.js";export{BASELINE_ITEM_FORMAT_VERSION,BUILTIN_ITEM_TYPE_VALUES,CONFIDENCE_TEXT_VALUES,CONTEXT_OUTPUT_VALUES,CURRENT_ITEM_FORMAT_VERSION,DEFAULT_TERMINAL_TRANSITION_POLICY,DEPENDENCY_KIND_VALUES,EXIT_CODE,HISTORY_EVENT_CLASSIFICATION_VERSION,ISSUE_SEVERITY_VALUES,ITEM_TYPE_VALUES,MAINTENANCE_HISTORY_OPERATIONS,NEXT_OUTPUT_VALUES,PM_CLI_EXPECTED_ERROR_NAME,PM_GITIGNORE_END,PM_GITIGNORE_START,PmCliError2 as PmCliError,PmClient,PmCompleteListValidationError,RISK_VALUES,SEARCH_EXTENSION_FLAG_DEFINITIONS,STATUS_VALUES,SUBSTANTIVE_HISTORY_OPERATIONS,acquireLock,acquireLockLease,aggregate,analyzeSdkActionCoverage,append,appendHistoryEntry,applyTerminalOrderingPolicy,assertCompleteListResult,canonicalDocument,certifyCompleteListResult2 as certifyCompleteListResult,claim,claimNext,classifyHistoryEvent,classifyItemFormatVersion,clearWorkspaceContractsCache2 as clearWorkspaceContractsCache,close,closeItem,closeTask,comments,commitImportedItem,config,context,copy,create,createCompleteListOptions2 as createCompleteListOptions,createHistoryEntry,createPmCliExpectedError,deleteItem,deps,docs,duplicates,effectiveItemFormatVersion,emptyImportedDocument,ensurePmGitignore,ensureTrackerInitialized,extension,extensionActivate,extensionDeactivate,extensionList,files,filesDiscover,filesLookup,focus,gc,generateItemId,get,getActiveExtensionRegistrations,getContracts,getHistoryPath,getItemPath,getPmGitignoreBlock,getSettingsPath2 as getSettingsPath,getWorkspaceContracts,graph,health,historyCompact,historyCompactBulk,historyRedact,historyRepair,historyRepairAll,init,inspectCompleteListResult,isPmCliExpectedError,isTerminalStatus,isTimestampLiteral,jaccardSimilarity,learnings,list,listAllComplete,listAllItemMetadata,listAllItemMetadataLight,loadCreateTemplateOptions,locateItem,next,normalizeItemFormatVersion,normalizeItemId,normalizeItemMetadata,normalizeRawItemId,normalizeSimilarityText,normalizeStatusInput,notes,nowIso,packageActivate,packageCatalog,packageDeactivate,packageDescribe,packageDoctor,packageInstall,packageLifecycle,packageList,packageManage,packageReload,packageUninstall,parseTags,pathExists2 as pathExists,pauseTask,profile,profileApply,profileLint,profileList,profileShow,readBooleanOption,readCsvListOption,readFileIfExists,readLocatedItem,readRequiredString2 as readRequiredString,readSettings2 as readSettings,readStringOption,release,removeFileIfExists,renderCalendarMarkdown,renderCalendarToon,renderGuideMarkdown,reopen,requireTerminalReason,resolveCalendarOutputFormat,resolveGuideOutputFormat,resolveImplicitPmRoot,resolveItemTypeRegistry,resolvePmRoot2 as resolvePmRoot,resolveRuntimeFieldRegistry,resolveRuntimeStatusRegistry,resolveTerminalReason,restore,runAction,runActiveOnReadHooks,runActiveOnWriteHooks,runAggregate,runCalendar,runClose,runCloseTask,runCompletion,runContext,runCopy,runDelete,runDuplicates,runFocus,runGet,runGuide,runList,runNext,runPauseTask,runReindex,runReopen,runRestore,runSearch,runStartTask,runStats,runTemplatesList,runTemplatesSave,runTemplatesShow,runTestRunsList,runTestRunsLogs,runTestRunsResume,runTestRunsStatus,runTestRunsStop,runUpdate,runWithActiveExtensions,scanItemFormatVersions,schema,schemaAddField,schemaAddStatus,schemaAddType,schemaApplyPreset,schemaInferTypes,schemaList,schemaListFields,schemaRemapStatus,schemaRemoveField,schemaRemoveStatus,schemaRemoveType,schemaRenameField,schemaRenameType,schemaShow,schemaShowField,schemaShowStatus,scoreItemSimilarity,search,selectImportAuthor,serializeItemDocument,splitFrontMatter,startTask,stats,toEstimatedMinutesValue,toImportBoolean,toImportConfidence,toImportInteger,toImportLinkedDocs,toImportLinkedFiles,toImportLinkedTests,toImportLogEntries,toImportNormalizedEnum,toImportNumberMap,toImportPriority,toImportStatus,toImportStringList,toImportStringMap,toImportTags,toNonEmptyImportString,tokenizeSimilarityText,update,upgrade,validate,writeFileAtomic};
 //# sourceMappingURL=runtime.js.map

package/dist/sdk/workspace-snapshot.d.ts

@@ -29,7 +29,11 @@ assertHealthy():void;
 stop():Promise<void>;
 /** Serialize renewal attempts and retain the first ownership failure. */
 private scheduleRenewal;
-/** Atomically refresh only the lock still owned by this process and actor. */
+/**
+     * Atomically refresh only the lock still owned by this process and actor.
+     * The check and the write run under the lock's cleanup gate, which takeover
+     * also holds, so a renewal can never republish a lock another writer took.
+     */
 private renew;
 }
 /** Internal heartbeat constructor exposed only for deterministic lock tests. */

package/dist/sdk/workspace-snapshot.js

@@ -1,6 +1,6 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="3b4a5521-a665-5f60-8d01-16033b078916")}catch{}})();import crypto from"node:crypto";import{cp,lstat,mkdir,readFile,readdir,rename,rm,writeFile}from"node:fs/promises";import path from"node:path";import{isFileMissingError,writeFileAtomic}from"../core/fs/fs-utils.js";import{appendWorkspaceAuditEvent}from"../core/history/workspace-history.js";import{acquireLock}from"../core/lock/lock.js";import{getLockPath}from"../core/store/paths.js";import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";import{withHostEnvironmentBoundary}from"./environment/host-environment-errors.js";const SNAPSHOT_SCHEMA="https://schema.unbrained.dev/pm/workspace-snapshot/v1",WORKSPACE_SNAPSHOT_ACTIONS=["create","list","inspect","restore","delete"],SNAPSHOT_RUNTIME_PATH=path.join("runtime","workspace-snapshots"),EXCLUDED_ROOT_NAMES=new Set(["checkpoints","locks","runtime","search","transactions"]),SNAPSHOT_TARGET_PATTERN=/^[a-z0-9][a-z0-9._-]*$/,WORKSPACE_WRITER_LOCK_ID="sdk-workspace-transaction",SNAPSHOT_HOST_FAULT_CODES={capacity:{code:"workspace_snapshot_storage_exhausted"},permission:{code:"workspace_snapshot_permission_denied"},resource:{code:"workspace_snapshot_resource_exhausted"}},DEFAULT_ATOMIC_OPERATIONS={renameEntry:rename,removeEntry:async target=>{await rm(target,{recursive:!0,force:!0})}};class WorkspaceLockHeartbeat{lockPath;owner;intervalMs;timer;refresh;failure;constructor(lockPath,owner,ttlSeconds){this.lockPath=lockPath,this.owner=owner,this.intervalMs=Math.max(10,Math.floor(ttlSeconds*1e3/3))}start(){this.scheduleRenewal(),this.timer=setInterval(()=>{this.scheduleRenewal()},this.intervalMs),this.timer.unref()}async refreshNow(){this.scheduleRenewal(),await this.refresh,this.assertHealthy()}assertHealthy(){if(this.failure!==void 0)throw new Error("Workspace snapshot restore lost its writer lock",{cause:this.failure})}async stop(){this.timer!==void 0&&clearInterval(this.timer),await this.refresh,this.assertHealthy()}scheduleRenewal(){this.refresh!==void 0||this.failure!==void 0||(this.refresh=this.renew().catch(error=>{this.failure=error}).finally(()=>{this.refresh=void 0}))}async renew(){const parsed=JSON.parse(await readFile(this.lockPath,"utf8"));if(typeof parsed!="object"||parsed===null||Array.isArray(parsed))throw new Error("Workspace writer lock has invalid structure");const lock=parsed;if(lock.id!==WORKSPACE_WRITER_LOCK_ID||lock.owner!==this.owner||lock.pid!==process.pid)throw new Error("Workspace writer lock ownership changed");await writeFileAtomic(this.lockPath,`${JSON.stringify({...lock,created_at:new Date().toISOString()},null,2)}
-`)}}const _testOnlyWorkspaceSnapshot={WorkspaceLockHeartbeat,withSnapshotFilesystemGuard};async function collectAuthoritativeFiles(root,relative=""){const entries=await readdir(path.join(root,relative),{withFileTypes:!0}),files=[];for(const entry of entries.sort((left,right)=>left.name.localeCompare(right.name))){if(relative.length===0&&EXCLUDED_ROOT_NAMES.has(entry.name))continue;const entryRelative=path.posix.join(relative.replaceAll(path.sep,"/"),entry.name);if(entry.isSymbolicLink())throw new Error(`Workspace snapshots reject symbolic links: ${entryRelative}`);if(entry.isDirectory())files.push(...await collectAuthoritativeFiles(root,entryRelative));else if(entry.isFile())files.push(entryRelative);else throw new Error(`Workspace snapshots reject unsupported filesystem entries: ${entryRelative}`)}return files}async function buildManifest(pmRoot){const files=await collectAuthoritativeFiles(pmRoot),hash=crypto.createHash("sha256"),contents=[];let bytes=0;for(const file of files){const content=await readFile(path.join(pmRoot,file));contents.push(content),bytes+=content.byteLength,hash.update(file),hash.update("\0"),hash.update(String(content.byteLength)),hash.update("\0"),hash.update(content)}const fingerprint=hash.digest("hex");return{manifest:{schema:SNAPSHOT_SCHEMA,fingerprint,files,bytes},contents}}function lineCount(content){return content===void 0||content.byteLength===0?0:content.toString("utf8").split(`
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="66cb8c82-3760-5628-a1de-69e417cf0292")}catch{}})();import crypto from"node:crypto";import{cp,lstat,mkdir,readFile,readdir,rename,rm,writeFile}from"node:fs/promises";import path from"node:path";import{isFileMissingError,writeFileAtomic}from"../core/fs/fs-utils.js";import{appendWorkspaceAuditEvent}from"../core/history/workspace-history.js";import{acquireLockLease,waitForStaleCleanupGate}from"../core/lock/lock.js";import{getLockPath}from"../core/store/paths.js";import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";import{withHostEnvironmentBoundary}from"./environment/host-environment-errors.js";const SNAPSHOT_SCHEMA="https://schema.unbrained.dev/pm/workspace-snapshot/v1",WORKSPACE_SNAPSHOT_ACTIONS=["create","list","inspect","restore","delete"],SNAPSHOT_RUNTIME_PATH=path.join("runtime","workspace-snapshots"),EXCLUDED_ROOT_NAMES=new Set(["checkpoints","locks","runtime","search","transactions"]),SNAPSHOT_TARGET_PATTERN=/^[a-z0-9][a-z0-9._-]*$/,WORKSPACE_WRITER_LOCK_ID="sdk-workspace-transaction",SNAPSHOT_HOST_FAULT_CODES={capacity:{code:"workspace_snapshot_storage_exhausted"},permission:{code:"workspace_snapshot_permission_denied"},resource:{code:"workspace_snapshot_resource_exhausted"}},DEFAULT_ATOMIC_OPERATIONS={renameEntry:rename,removeEntry:async target=>{await rm(target,{recursive:!0,force:!0})}};class WorkspaceLockHeartbeat{lockPath;owner;intervalMs;timer;refresh;failure;constructor(lockPath,owner,ttlSeconds){this.lockPath=lockPath,this.owner=owner,this.intervalMs=Math.max(10,Math.floor(ttlSeconds*1e3/3))}start(){this.scheduleRenewal(),this.timer=setInterval(()=>{this.scheduleRenewal()},this.intervalMs),this.timer.unref()}async refreshNow(){this.scheduleRenewal(),await this.refresh,this.assertHealthy()}assertHealthy(){if(this.failure!==void 0)throw new Error("Workspace snapshot restore lost its writer lock",{cause:this.failure})}async stop(){this.timer!==void 0&&clearInterval(this.timer),await this.refresh,this.assertHealthy()}scheduleRenewal(){this.refresh!==void 0||this.failure!==void 0||(this.refresh=this.renew().catch(error=>{this.failure=error}).finally(()=>{this.refresh=void 0}))}async renew(){const releaseGate=await waitForStaleCleanupGate(this.lockPath,WORKSPACE_WRITER_LOCK_ID);if(releaseGate===null)throw new Error("Workspace writer lock cleanup gate stayed held");try{const parsed=JSON.parse(await readFile(this.lockPath,"utf8"));if(typeof parsed!="object"||parsed===null||Array.isArray(parsed))throw new Error("Workspace writer lock has invalid structure");const lock=parsed;if(lock.id!==WORKSPACE_WRITER_LOCK_ID||lock.owner!==this.owner||lock.pid!==process.pid)throw new Error("Workspace writer lock ownership changed");await writeFileAtomic(this.lockPath,`${JSON.stringify({...lock,created_at:new Date().toISOString()},null,2)}
+`)}finally{await releaseGate()}}}const _testOnlyWorkspaceSnapshot={WorkspaceLockHeartbeat,withSnapshotFilesystemGuard};async function collectAuthoritativeFiles(root,relative=""){const entries=await readdir(path.join(root,relative),{withFileTypes:!0}),files=[];for(const entry of entries.sort((left,right)=>left.name.localeCompare(right.name))){if(relative.length===0&&EXCLUDED_ROOT_NAMES.has(entry.name))continue;const entryRelative=path.posix.join(relative.replaceAll(path.sep,"/"),entry.name);if(entry.isSymbolicLink())throw new Error(`Workspace snapshots reject symbolic links: ${entryRelative}`);if(entry.isDirectory())files.push(...await collectAuthoritativeFiles(root,entryRelative));else if(entry.isFile())files.push(entryRelative);else throw new Error(`Workspace snapshots reject unsupported filesystem entries: ${entryRelative}`)}return files}async function buildManifest(pmRoot){const files=await collectAuthoritativeFiles(pmRoot),hash=crypto.createHash("sha256"),contents=[];let bytes=0;for(const file of files){const content=await readFile(path.join(pmRoot,file));contents.push(content),bytes+=content.byteLength,hash.update(file),hash.update("\0"),hash.update(String(content.byteLength)),hash.update("\0"),hash.update(content)}const fingerprint=hash.digest("hex");return{manifest:{schema:SNAPSHOT_SCHEMA,fingerprint,files,bytes},contents}}function lineCount(content){return content===void 0||content.byteLength===0?0:content.toString("utf8").split(`
 `).filter(line=>line.trim().length>0).length}async function snapshotContents(root,files){const contents=new Map;for(let offset=0;offset<files.length;offset+=32){const batch=files.slice(offset,offset+32),entries=await Promise.all(batch.map(async file=>[file,await readFile(path.join(root,file))]));for(const[file,content]of entries)contents.set(file,content)}return contents}function validateSnapshotTarget(target){if(!SNAPSHOT_TARGET_PATTERN.test(target))throw new PmCliError("Snapshot names and fingerprints must use lowercase letters, digits, dots, underscores, or hyphens",EXIT_CODE.USAGE,{code:"invalid_workspace_snapshot_target",required:"Provide a non-empty lowercase snapshot name or 64-character hexadecimal fingerprint.",why:"Snapshot targets are used as portable reference filenames and content identities.",examples:["pm workspace snapshot list --json","pm workspace snapshot inspect baseline --json"],nextSteps:["List available snapshots, then retry with a returned name or fingerprint."],recovery:{suggested_retry:"pm workspace snapshot list --json"}})}async function withSnapshotFilesystemGuard(operation,run){return withHostEnvironmentBoundary(`workspace_snapshot_${operation}`,run,{codes:{capacity:SNAPSHOT_HOST_FAULT_CODES.capacity.code,permission:SNAPSHOT_HOST_FAULT_CODES.permission.code,resource:SNAPSHOT_HOST_FAULT_CODES.resource.code},why:"Snapshot create and restore copy authoritative tracker state before activation, so the stage needs capacity and write access up front.",nextSteps:["Reclaim rebuildable tracker cache space with pm gc, then retry."],suggestedRetry:"pm gc --json"})}function snapshotStore(pmRoot){return path.join(pmRoot,SNAPSHOT_RUNTIME_PATH)}function workspaceSnapshotNotFound(target){return new PmCliError(`Unknown workspace snapshot: ${target}`,EXIT_CODE.NOT_FOUND,{code:"workspace_snapshot_not_found",required:"Use a snapshot name or fingerprint returned by snapshot list.",why:"The requested reference or immutable snapshot object does not exist.",examples:["pm workspace snapshot list --json"],nextSteps:["List available snapshots and retry with an exact target."],recovery:{suggested_retry:"pm workspace snapshot list --json"}})}async function readSnapshotJson(file,target){try{return JSON.parse(await readFile(file,"utf8"))}catch(error){throw isFileMissingError(error)?workspaceSnapshotNotFound(target):error}}async function removeSnapshotEntry(entry,target,recursive){try{await rm(entry,{recursive})}catch(error){throw isFileMissingError(error)?workspaceSnapshotNotFound(target):error}}async function publishWorkspaceSnapshotObject(temporaryRoot,objectRoot,operations=DEFAULT_ATOMIC_OPERATIONS){try{return await operations.renameEntry(temporaryRoot,objectRoot),!1}catch(error){if(!(error instanceof Error&&"code"in error&&(error.code==="EEXIST"||error.code==="ENOTEMPTY")))throw error;return await operations.removeEntry(temporaryRoot),!0}}async function swapWorkspaceSnapshotRootWithActivation(staging,pmRoot,backup,operations,afterActivation){await operations.renameEntry(pmRoot,backup);try{await operations.renameEntry(staging,pmRoot),await afterActivation?.()}catch(error){throw await operations.renameEntry(backup,pmRoot),await operations.removeEntry(staging),error}await operations.removeEntry(backup)}async function swapWorkspaceSnapshotRoot(staging,pmRoot,backup,operations=DEFAULT_ATOMIC_OPERATIONS){await swapWorkspaceSnapshotRootWithActivation(staging,pmRoot,backup,operations)}async function resolveSnapshotFingerprint(pmRoot,target){return validateSnapshotTarget(target),/^[a-f0-9]{64}$/.test(target)?target:(await readSnapshotJson(path.join(snapshotStore(pmRoot),"refs",`${target}.json`),target)).fingerprint}async function createWorkspaceSnapshot(pmRoot,options={}){if(options.name!==void 0&&(validateSnapshotTarget(options.name),/^[a-f0-9]{64}$/.test(options.name)))throw new PmCliError("Snapshot names must not be 64-character lowercase hexadecimal fingerprints",EXIT_CODE.USAGE,{code:"workspace_snapshot_name_reserved_fingerprint",required:"Choose a human-readable reference name that cannot be mistaken for a content fingerprint.",why:"Exact 64-character hexadecimal values address immutable objects.",examples:["pm workspace snapshot create baseline --json"],nextSteps:["Retry with a shorter descriptive snapshot name."]});const{manifest,contents}=await buildManifest(pmRoot),store=snapshotStore(pmRoot),objectRoot=path.join(store,"objects",manifest.fingerprint);let deduplicated=!1;try{deduplicated=(await lstat(objectRoot)).isDirectory()}catch(error){if(!(error instanceof Error&&"code"in error&&isFileMissingError(error)))throw error}if(!deduplicated){const temporaryRoot=path.join(store,"objects",`.create-${process.pid}-${crypto.randomUUID()}`);await withSnapshotFilesystemGuard("create_object",async()=>{await mkdir(path.join(temporaryRoot,"files"),{recursive:!0});for(const[index,file]of manifest.files.entries()){const target=path.join(temporaryRoot,"files",file);await mkdir(path.dirname(target),{recursive:!0}),await writeFile(target,contents[index])}await writeFile(path.join(temporaryRoot,"manifest.json"),`${JSON.stringify(manifest,null,2)}
 `,"utf8"),await mkdir(path.dirname(objectRoot),{recursive:!0})}),deduplicated=await publishWorkspaceSnapshotObject(temporaryRoot,objectRoot)}if(options.name!==void 0){const reference={name:options.name,fingerprint:manifest.fingerprint},refsRoot=path.join(store,"refs");await mkdir(refsRoot,{recursive:!0});const temporaryRef=path.join(refsRoot,`.ref-${process.pid}-${crypto.randomUUID()}`);await writeFile(temporaryRef,`${JSON.stringify(reference,null,2)}
-`,"utf8"),await rename(temporaryRef,path.join(refsRoot,`${options.name}.json`))}return{manifest,...options.name===void 0?{}:{name:options.name},deduplicated}}async function inspectWorkspaceSnapshot(pmRoot,target){const fingerprint=await resolveSnapshotFingerprint(pmRoot,target),manifest=await readSnapshotJson(path.join(snapshotStore(pmRoot),"objects",fingerprint,"manifest.json"),target);if(manifest.schema!==SNAPSHOT_SCHEMA||manifest.fingerprint!==fingerprint)throw new PmCliError(`Snapshot manifest identity mismatch: ${target}`,EXIT_CODE.CONFLICT,{code:"workspace_snapshot_manifest_mismatch",required:"Use an intact snapshot whose manifest fingerprint matches its object path.",why:"Content identity must be verified before snapshot data is trusted.",examples:["pm workspace snapshot list --json"],nextSteps:["Inspect or recreate the snapshot before restoring it."]});return manifest}async function listWorkspaceSnapshots(pmRoot){const store=snapshotStore(pmRoot),objectNames=await readdir(path.join(store,"objects")).catch(error=>{if(error instanceof Error&&"code"in error&&isFileMissingError(error))return[];throw error}),referenceNames=await readdir(path.join(store,"refs")).catch(error=>{if(error instanceof Error&&"code"in error&&isFileMissingError(error))return[];throw error});return{objects:await Promise.all(objectNames.filter(name=>/^[a-f0-9]{64}$/.test(name)).sort().map(name=>inspectWorkspaceSnapshot(pmRoot,name))),references:await Promise.all(referenceNames.filter(name=>name.endsWith(".json")).sort().map(async name=>JSON.parse(await readFile(path.join(store,"refs",name),"utf8"))))}}async function planWorkspaceSnapshotRestore(pmRoot,target){const targetManifest=await inspectWorkspaceSnapshot(pmRoot,target),{manifest:currentManifest,contents:currentContentList}=await buildManifest(pmRoot),currentContents=new Map(currentManifest.files.map((file,index)=>[file,currentContentList[index]])),targetContents=await snapshotContents(path.join(snapshotStore(pmRoot),"objects",targetManifest.fingerprint,"files"),targetManifest.files),currentFiles=new Set(currentManifest.files),targetFiles=new Set(targetManifest.files),changedFiles=new Set([...currentFiles,...targetFiles]);for(const file of changedFiles){const currentContent=currentContents.get(file),targetContent=targetContents.get(file);currentContent!==void 0&&targetContent!==void 0&&currentContent.equals(targetContent)&&changedFiles.delete(file)}const affectedHistoryStreams=currentManifest.files.filter(file=>file.startsWith("history/")&&file.endsWith(".jsonl")).map(file=>{const currentEntries=lineCount(currentContents.get(file)),targetEntries=lineCount(targetContents.get(file));return{path:file,current_entries:currentEntries,target_entries:targetEntries,removed_entries:Math.max(0,currentEntries-targetEntries)}}).filter(entry=>entry.removed_entries>0).sort((left,right)=>left.path.localeCompare(right.path));return{target_fingerprint:targetManifest.fingerprint,current_fingerprint:currentManifest.fingerprint,changed_file_count:changedFiles.size,removed_file_count:[...currentFiles].filter(file=>!targetFiles.has(file)).length,added_file_count:[...targetFiles].filter(file=>!currentFiles.has(file)).length,removed_item_count:[...currentFiles].filter(file=>file.endsWith(".toon")&&!targetFiles.has(file)).length,affected_history_stream_count:affectedHistoryStreams.length,removed_history_entry_count:affectedHistoryStreams.reduce((total,entry)=>total+entry.removed_entries,0),affected_history_streams:affectedHistoryStreams,changes_authoritative_state:currentManifest.fingerprint!==targetManifest.fingerprint}}async function restoreWorkspaceSnapshotWithRecovery(pmRoot,target,options={}){if(options.force!==!0)throw new PmCliError("Workspace snapshot restore requires explicit force confirmation; inspect the impact with planWorkspaceSnapshotRestore or pm workspace snapshot restore <target> --dry-run, then retry with force",EXIT_CODE.USAGE,{code:"workspace_snapshot_force_required",required:"Preview the destructive impact, then explicitly confirm the restore.",why:"A restore replaces the complete authoritative tracker state.",examples:[`pm workspace snapshot restore ${target} --dry-run --json`,`pm workspace snapshot restore ${target} --force --json`],nextSteps:["Review the dry-run counts before retrying with --force."],recovery:{suggested_retry:`pm workspace snapshot restore ${target} --dry-run --json`}});const author=options.author?.trim()||"pm-sdk",lockTtlSeconds=options.lockTtlSeconds??60,lockWaitMs=options.lockWaitMs??5e3,releaseWorkspaceLock=await acquireLock(pmRoot,WORKSPACE_WRITER_LOCK_ID,lockTtlSeconds,author,!1,!1,lockWaitMs),heartbeat=new WorkspaceLockHeartbeat(getLockPath(pmRoot,WORKSPACE_WRITER_LOCK_ID),author,lockTtlSeconds);heartbeat.start(),await heartbeat.refreshNow();let staging,swapStarted=!1,heartbeatStopped=!1;try{const plan=await planWorkspaceSnapshotRestore(pmRoot,target),manifest=await inspectWorkspaceSnapshot(pmRoot,target),recovery=await createWorkspaceSnapshot(pmRoot),fingerprint=manifest.fingerprint,store=snapshotStore(pmRoot),source=path.join(store,"objects",fingerprint,"files"),parent=path.dirname(pmRoot),base=path.basename(pmRoot);staging=path.join(parent,`.${base}.restore-${crypto.randomUUID()}`);const backup=path.join(parent,`.${base}.backup-${crypto.randomUUID()}`);await withSnapshotFilesystemGuard("restore_stage",async()=>{await mkdir(staging,{recursive:!0}),await cp(source,staging,{recursive:!0,force:!1}),await mkdir(path.join(staging,"runtime"),{recursive:!0}),await cp(store,path.join(staging,SNAPSHOT_RUNTIME_PATH),{recursive:!0,force:!1})});const audit=await appendWorkspaceAuditEvent({pmRoot:staging,op:"workspace_snapshot_restore",author,message:options.message??`Restore workspace snapshot ${fingerprint}; recovery snapshot ${recovery.manifest.fingerprint}`,context:{target_fingerprint:fingerprint,pre_restore_fingerprint:recovery.manifest.fingerprint,changed_file_count:plan.changed_file_count,removed_file_count:plan.removed_file_count,removed_item_count:plan.removed_item_count,affected_history_stream_count:plan.affected_history_stream_count,removed_history_entry_count:plan.removed_history_entry_count},lockTtlSeconds,lockWaitMs}),auditHistoryPath=path.relative(staging,audit.historyPath).replaceAll("\\","/");await heartbeat.stop(),heartbeatStopped=!0;const stagedWorkspaceLock=getLockPath(staging,WORKSPACE_WRITER_LOCK_ID);return await mkdir(path.dirname(stagedWorkspaceLock),{recursive:!0}),await writeFile(stagedWorkspaceLock,await readFile(getLockPath(pmRoot,WORKSPACE_WRITER_LOCK_ID)),{flag:"wx"}),swapStarted=!0,await swapWorkspaceSnapshotRootWithActivation(staging,pmRoot,backup,DEFAULT_ATOMIC_OPERATIONS,async()=>{heartbeat.start(),heartbeatStopped=!1,await heartbeat.refreshNow()}),await heartbeat.stop(),heartbeatStopped=!0,{manifest,plan,recovery_fingerprint:recovery.manifest.fingerprint,audit_history_path:auditHistoryPath,audit_operation:"workspace_snapshot_restore"}}catch(error){throw staging!==void 0&&!swapStarted&&await Promise.allSettled([rm(staging,{recursive:!0,force:!0})]),error}finally{try{heartbeatStopped||await heartbeat.stop()}catch{}finally{await releaseWorkspaceLock()}}}async function restoreWorkspaceSnapshot(pmRoot,target){return(await restoreWorkspaceSnapshotWithRecovery(pmRoot,target,{force:!0,message:"Restore requested through the compatibility SDK signature"})).manifest}async function deleteWorkspaceSnapshot(pmRoot,target){validateSnapshotTarget(target);const store=snapshotStore(pmRoot);if(!/^[a-f0-9]{64}$/.test(target))return await removeSnapshotEntry(path.join(store,"refs",`${target}.json`),target,!1),{deleted:"reference",target};const{references}=await listWorkspaceSnapshots(pmRoot);if(references.some(reference=>reference.fingerprint===target))throw new Error(`Snapshot object ${target} is still referenced`);return await removeSnapshotEntry(path.join(store,"objects",target),target,!0),{deleted:"object",target}}export{SNAPSHOT_SCHEMA,WORKSPACE_SNAPSHOT_ACTIONS,_testOnlyWorkspaceSnapshot,createWorkspaceSnapshot,deleteWorkspaceSnapshot,inspectWorkspaceSnapshot,listWorkspaceSnapshots,planWorkspaceSnapshotRestore,publishWorkspaceSnapshotObject,restoreWorkspaceSnapshot,restoreWorkspaceSnapshotWithRecovery,swapWorkspaceSnapshotRoot};
+`,"utf8"),await rename(temporaryRef,path.join(refsRoot,`${options.name}.json`))}return{manifest,...options.name===void 0?{}:{name:options.name},deduplicated}}async function inspectWorkspaceSnapshot(pmRoot,target){const fingerprint=await resolveSnapshotFingerprint(pmRoot,target),manifest=await readSnapshotJson(path.join(snapshotStore(pmRoot),"objects",fingerprint,"manifest.json"),target);if(manifest.schema!==SNAPSHOT_SCHEMA||manifest.fingerprint!==fingerprint)throw new PmCliError(`Snapshot manifest identity mismatch: ${target}`,EXIT_CODE.CONFLICT,{code:"workspace_snapshot_manifest_mismatch",required:"Use an intact snapshot whose manifest fingerprint matches its object path.",why:"Content identity must be verified before snapshot data is trusted.",examples:["pm workspace snapshot list --json"],nextSteps:["Inspect or recreate the snapshot before restoring it."]});return manifest}async function listWorkspaceSnapshots(pmRoot){const store=snapshotStore(pmRoot),objectNames=await readdir(path.join(store,"objects")).catch(error=>{if(error instanceof Error&&"code"in error&&isFileMissingError(error))return[];throw error}),referenceNames=await readdir(path.join(store,"refs")).catch(error=>{if(error instanceof Error&&"code"in error&&isFileMissingError(error))return[];throw error});return{objects:await Promise.all(objectNames.filter(name=>/^[a-f0-9]{64}$/.test(name)).sort().map(name=>inspectWorkspaceSnapshot(pmRoot,name))),references:await Promise.all(referenceNames.filter(name=>name.endsWith(".json")).sort().map(async name=>JSON.parse(await readFile(path.join(store,"refs",name),"utf8"))))}}async function planWorkspaceSnapshotRestore(pmRoot,target){const targetManifest=await inspectWorkspaceSnapshot(pmRoot,target),{manifest:currentManifest,contents:currentContentList}=await buildManifest(pmRoot),currentContents=new Map(currentManifest.files.map((file,index)=>[file,currentContentList[index]])),targetContents=await snapshotContents(path.join(snapshotStore(pmRoot),"objects",targetManifest.fingerprint,"files"),targetManifest.files),currentFiles=new Set(currentManifest.files),targetFiles=new Set(targetManifest.files),changedFiles=new Set([...currentFiles,...targetFiles]);for(const file of changedFiles){const currentContent=currentContents.get(file),targetContent=targetContents.get(file);currentContent!==void 0&&targetContent!==void 0&&currentContent.equals(targetContent)&&changedFiles.delete(file)}const affectedHistoryStreams=currentManifest.files.filter(file=>file.startsWith("history/")&&file.endsWith(".jsonl")).map(file=>{const currentEntries=lineCount(currentContents.get(file)),targetEntries=lineCount(targetContents.get(file));return{path:file,current_entries:currentEntries,target_entries:targetEntries,removed_entries:Math.max(0,currentEntries-targetEntries)}}).filter(entry=>entry.removed_entries>0).sort((left,right)=>left.path.localeCompare(right.path));return{target_fingerprint:targetManifest.fingerprint,current_fingerprint:currentManifest.fingerprint,changed_file_count:changedFiles.size,removed_file_count:[...currentFiles].filter(file=>!targetFiles.has(file)).length,added_file_count:[...targetFiles].filter(file=>!currentFiles.has(file)).length,removed_item_count:[...currentFiles].filter(file=>file.endsWith(".toon")&&!targetFiles.has(file)).length,affected_history_stream_count:affectedHistoryStreams.length,removed_history_entry_count:affectedHistoryStreams.reduce((total,entry)=>total+entry.removed_entries,0),affected_history_streams:affectedHistoryStreams,changes_authoritative_state:currentManifest.fingerprint!==targetManifest.fingerprint}}async function restoreWorkspaceSnapshotWithRecovery(pmRoot,target,options={}){if(options.force!==!0)throw new PmCliError("Workspace snapshot restore requires explicit force confirmation; inspect the impact with planWorkspaceSnapshotRestore or pm workspace snapshot restore <target> --dry-run, then retry with force",EXIT_CODE.USAGE,{code:"workspace_snapshot_force_required",required:"Preview the destructive impact, then explicitly confirm the restore.",why:"A restore replaces the complete authoritative tracker state.",examples:[`pm workspace snapshot restore ${target} --dry-run --json`,`pm workspace snapshot restore ${target} --force --json`],nextSteps:["Review the dry-run counts before retrying with --force."],recovery:{suggested_retry:`pm workspace snapshot restore ${target} --dry-run --json`}});const author=options.author?.trim()||"pm-sdk",lockTtlSeconds=options.lockTtlSeconds??60,lockWaitMs=options.lockWaitMs??5e3,workspaceLease=await acquireLockLease(pmRoot,WORKSPACE_WRITER_LOCK_ID,lockTtlSeconds,author,!1,!1,lockWaitMs),releaseWorkspaceLock=workspaceLease.release,heartbeat=new WorkspaceLockHeartbeat(getLockPath(pmRoot,WORKSPACE_WRITER_LOCK_ID),author,lockTtlSeconds);heartbeat.start(),await heartbeat.refreshNow();let staging,swapStarted=!1,heartbeatStopped=!1;try{const plan=await planWorkspaceSnapshotRestore(pmRoot,target),manifest=await inspectWorkspaceSnapshot(pmRoot,target),recovery=await createWorkspaceSnapshot(pmRoot),fingerprint=manifest.fingerprint,store=snapshotStore(pmRoot),source=path.join(store,"objects",fingerprint,"files"),parent=path.dirname(pmRoot),base=path.basename(pmRoot);staging=path.join(parent,`.${base}.restore-${crypto.randomUUID()}`);const backup=path.join(parent,`.${base}.backup-${crypto.randomUUID()}`);await withSnapshotFilesystemGuard("restore_stage",async()=>{await mkdir(staging,{recursive:!0}),await cp(source,staging,{recursive:!0,force:!1}),await mkdir(path.join(staging,"runtime"),{recursive:!0}),await cp(store,path.join(staging,SNAPSHOT_RUNTIME_PATH),{recursive:!0,force:!1})});const audit=await appendWorkspaceAuditEvent({pmRoot:staging,op:"workspace_snapshot_restore",author,message:options.message??`Restore workspace snapshot ${fingerprint}; recovery snapshot ${recovery.manifest.fingerprint}`,context:{target_fingerprint:fingerprint,pre_restore_fingerprint:recovery.manifest.fingerprint,changed_file_count:plan.changed_file_count,removed_file_count:plan.removed_file_count,removed_item_count:plan.removed_item_count,affected_history_stream_count:plan.affected_history_stream_count,removed_history_entry_count:plan.removed_history_entry_count},lockTtlSeconds,lockWaitMs}),auditHistoryPath=path.relative(staging,audit.historyPath).replaceAll("\\","/");await heartbeat.stop(),heartbeatStopped=!0;const stagedWorkspaceLock=getLockPath(staging,WORKSPACE_WRITER_LOCK_ID),stagedRoot=staging;return await workspaceLease.fence(async()=>{await mkdir(path.dirname(stagedWorkspaceLock),{recursive:!0}),await writeFile(stagedWorkspaceLock,await readFile(getLockPath(pmRoot,WORKSPACE_WRITER_LOCK_ID)),{flag:"wx"}),swapStarted=!0,await swapWorkspaceSnapshotRootWithActivation(stagedRoot,pmRoot,backup,DEFAULT_ATOMIC_OPERATIONS,async()=>{heartbeat.start(),heartbeatStopped=!1,await heartbeat.refreshNow()})}),await heartbeat.stop(),heartbeatStopped=!0,{manifest,plan,recovery_fingerprint:recovery.manifest.fingerprint,audit_history_path:auditHistoryPath,audit_operation:"workspace_snapshot_restore"}}catch(error){throw staging!==void 0&&!swapStarted&&await Promise.allSettled([rm(staging,{recursive:!0,force:!0})]),error}finally{try{heartbeatStopped||await heartbeat.stop()}catch{}finally{await releaseWorkspaceLock()}}}async function restoreWorkspaceSnapshot(pmRoot,target){return(await restoreWorkspaceSnapshotWithRecovery(pmRoot,target,{force:!0,message:"Restore requested through the compatibility SDK signature"})).manifest}async function deleteWorkspaceSnapshot(pmRoot,target){validateSnapshotTarget(target);const store=snapshotStore(pmRoot);if(!/^[a-f0-9]{64}$/.test(target))return await removeSnapshotEntry(path.join(store,"refs",`${target}.json`),target,!1),{deleted:"reference",target};const{references}=await listWorkspaceSnapshots(pmRoot);if(references.some(reference=>reference.fingerprint===target))throw new Error(`Snapshot object ${target} is still referenced`);return await removeSnapshotEntry(path.join(store,"objects",target),target,!0),{deleted:"object",target}}export{SNAPSHOT_SCHEMA,WORKSPACE_SNAPSHOT_ACTIONS,_testOnlyWorkspaceSnapshot,createWorkspaceSnapshot,deleteWorkspaceSnapshot,inspectWorkspaceSnapshot,listWorkspaceSnapshots,planWorkspaceSnapshotRestore,publishWorkspaceSnapshotObject,restoreWorkspaceSnapshot,restoreWorkspaceSnapshotWithRecovery,swapWorkspaceSnapshotRoot};
 //# sourceMappingURL=workspace-snapshot.js.map

package/dist/sdk/workspace.js

@@ -1,9 +1,9 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="df771be0-6c32-5483-8aa7-3f8c5253a506")}catch{}})();import{isFileMissingError}from"../core/fs/fs-utils.js";import{readFile,writeFile}from"node:fs/promises";import path from"node:path";import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";const PM_GITIGNORE_START="# pm-cli:runtime-cache:start",PM_GITIGNORE_END="# pm-cli:runtime-cache:end",PM_GITIGNORE_DEFAULT_TRACKER_ROOT=".agents/pm",PM_GITIGNORE_RUNTIME_DIRECTORIES=["runtime/","search/","locks/","transactions/","checkpoints/"],PM_GITIGNORE_TRACKED_FILES=["search/eval-queries.json"];async function withGitignorePermissionRecovery(operation){try{return await operation()}catch(error){throw error instanceof Error&&"code"in error&&typeof error.code=="string"&&["EACCES","EPERM","EROFS"].includes(error.code)?new PmCliError("The workspace .gitignore is not writable.",EXIT_CODE.GENERIC_FAILURE,{code:"init_gitignore_unwritable",reason:error.code.toLowerCase(),required:"Grant the current user read and write access to the workspace .gitignore before initialization.",why:"pm init must publish its managed runtime-cache ignore fence without replacing unrelated entries.",nextSteps:["Grant read and write access to the workspace .gitignore and rerun pm init.","If the workspace is intentionally read-only, initialize pm in a writable workspace or clone."]}):error}}function normalizeTrackerRelativeRoot(trackerRelativeRoot){const root=trackerRelativeRoot.split(path.sep).join("/").replace(/^\.\/+/,"");let end=root.length;for(;end>0&&root[end-1]==="/";)end-=1;return root.slice(0,end)}function isPathOutsideRoot(relativePath){const normalized=relativePath.replaceAll("\\","/");return path.isAbsolute(relativePath)||normalized===".."||normalized.startsWith("../")}function getPmGitignoreBlock(trackerRelativeRoot=PM_GITIGNORE_DEFAULT_TRACKER_ROOT){const root=normalizeTrackerRelativeRoot(trackerRelativeRoot);if(/[\r\n]/u.test(root))throw new PmCliError("A tracker path containing a line break cannot be represented safely in .gitignore.",EXIT_CODE.USAGE,{code:"invalid_argument_value",required:"a tracker path without line breaks",nextSteps:["Choose a tracker path without carriage returns or newlines and rerun pm init."]});const literalRoot=root.replace(/[\\*?[\]#! \t]/gu,"\\$&");return[PM_GITIGNORE_START,...PM_GITIGNORE_RUNTIME_DIRECTORIES.map(directory=>directory==="search/"?`${literalRoot}/${directory}*`:`${literalRoot}/${directory}`),...PM_GITIGNORE_TRACKED_FILES.map(file=>`!${literalRoot}/${file}`),PM_GITIGNORE_END].join(`
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="38df9536-d87a-52ac-958d-091a17c9da9c")}catch{}})();import{isFileMissingError}from"../core/fs/fs-utils.js";import{readFile,realpath,stat,writeFile}from"node:fs/promises";import path from"node:path";import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";const PM_GITIGNORE_START="# pm-cli:runtime-cache:start",PM_GITIGNORE_END="# pm-cli:runtime-cache:end",PM_GITIGNORE_DEFAULT_TRACKER_ROOT=".agents/pm";async function physicalInitPath(input){let ancestor=path.resolve(input);const missing=[];for(;;)try{const physical=await realpath(ancestor);if(!(await stat(physical)).isDirectory())throw Object.assign(new Error("Initialization path ancestry must be a directory."),{code:"ENOTDIR"});return path.join(physical,...missing)}catch(error){if(!isFileMissingError(error)||path.dirname(ancestor)===ancestor)throw error;missing.unshift(path.basename(ancestor)),ancestor=path.dirname(ancestor)}}const PM_GITIGNORE_RUNTIME_DIRECTORIES=["runtime/","search/","locks/","transactions/","checkpoints/"],PM_GITIGNORE_TRACKED_FILES=["search/eval-queries.json"];async function withGitignorePermissionRecovery(operation){try{return await operation()}catch(error){throw error instanceof Error&&"code"in error&&typeof error.code=="string"&&["EACCES","EPERM","EROFS"].includes(error.code)?new PmCliError("The workspace .gitignore is not writable.",EXIT_CODE.GENERIC_FAILURE,{code:"init_gitignore_unwritable",reason:error.code.toLowerCase(),required:"Grant the current user read and write access to the workspace .gitignore before initialization.",why:"pm init must publish its managed runtime-cache ignore fence without replacing unrelated entries.",nextSteps:["Grant read and write access to the workspace .gitignore and rerun pm init.","If the workspace is intentionally read-only, initialize pm in a writable workspace or clone."]}):error}}function normalizeTrackerRelativeRoot(trackerRelativeRoot){const root=trackerRelativeRoot.split(path.sep).join("/").replace(/^\.\/+/,"");let end=root.length;for(;end>0&&root[end-1]==="/";)end-=1;return root.slice(0,end)}function isPathOutsideRoot(relativePath){const normalized=relativePath.replaceAll("\\","/");return path.isAbsolute(relativePath)||normalized===".."||normalized.startsWith("../")}function getPmGitignoreBlock(trackerRelativeRoot=PM_GITIGNORE_DEFAULT_TRACKER_ROOT){const root=normalizeTrackerRelativeRoot(trackerRelativeRoot);if(/[\r\n]/u.test(root))throw new PmCliError("A tracker path containing a line break cannot be represented safely in .gitignore.",EXIT_CODE.USAGE,{code:"invalid_argument_value",required:"a tracker path without line breaks",nextSteps:["Choose a tracker path without carriage returns or newlines and rerun pm init."]});const literalRoot=root.replace(/[\\*?[\]#! \t]/gu,"\\$&");return[PM_GITIGNORE_START,...PM_GITIGNORE_RUNTIME_DIRECTORIES.map(directory=>directory==="search/"?`${literalRoot}/${directory}*`:`${literalRoot}/${directory}`),...PM_GITIGNORE_TRACKED_FILES.map(file=>`!${literalRoot}/${file}`),PM_GITIGNORE_END].join(`
 `)}function mergeTrackerIgnoreRules(lines,trackerRoot,rules){const literalRoot=trackerRoot.replace(/[\\*?[\]#! \t]/gu,"\\$&"),prefixes=[...new Set([trackerRoot,literalRoot])].flatMap(root=>PM_GITIGNORE_RUNTIME_DIRECTORIES.flatMap(directory=>[`${root}/${directory}`,`!${root}/${directory}`])),merged=[];let replaced=!1;for(const line of lines)prefixes.some(prefix=>line.startsWith(prefix))?(replaced||merged.push(...rules),replaced=!0):merged.push(line);return replaced||merged.push(...rules),merged}function managedGitignoreBlocks(current){const blocks=[];let start=-1,bodyStart=0,offset=0;for(const line of current.split(`
 `)){const marker=line.endsWith("\r")?line.slice(0,-1):line;marker===PM_GITIGNORE_START?(start=offset,bodyStart=offset+line.length+1):marker===PM_GITIGNORE_END&&start>=0&&(blocks.push({index:start,end:offset+marker.length,lines:current.slice(bodyStart,offset).split(/\r?\n/u).filter(entry=>entry.length>0)}),start=-1),offset+=line.length+1}return blocks}function reconcileGitignoreContent(current,trackerRoot){const newline=current.includes(`\r
 `)?`\r
 `:`
 `,rules=getPmGitignoreBlock(trackerRoot).split(`
 `).slice(1,-1),blocks=managedGitignoreBlocks(current),existingRules=blocks.flatMap(entry=>entry.lines),block=[PM_GITIGNORE_START,...mergeTrackerIgnoreRules(existingRules,trackerRoot,rules),PM_GITIGNORE_END].join(newline);if(blocks.length===0){const separator=current.length===0?"":current.endsWith(`
-`)?newline:`${newline}${newline}`;return`${current}${separator}${block}${newline}`}let next=current;for(const[index,match]of[...blocks.entries()].reverse())next=`${next.slice(0,match.index)}${index===0?block:""}${next.slice(match.end)}`;return next}async function ensurePmGitignore(workspaceRoot,options={}){const gitignorePath=path.join(workspaceRoot,".gitignore");let trackerRelativeRoot=PM_GITIGNORE_DEFAULT_TRACKER_ROOT;if(options.pmRoot!==void 0){const relative=normalizeTrackerRelativeRoot(path.relative(path.resolve(workspaceRoot),path.resolve(options.pmRoot)));if(isPathOutsideRoot(relative))return{path:gitignorePath,changed:!1};trackerRelativeRoot=relative}let current="";try{current=await withGitignorePermissionRecovery(()=>readFile(gitignorePath,"utf8"))}catch(error){if(!(error instanceof Error&&"code"in error&&isFileMissingError(error)))throw error}const next=reconcileGitignoreContent(current,trackerRelativeRoot);return next===current?{path:gitignorePath,changed:!1}:(await withGitignorePermissionRecovery(()=>writeFile(gitignorePath,next,"utf8")),{path:gitignorePath,changed:!0})}export{PM_GITIGNORE_DEFAULT_TRACKER_ROOT,PM_GITIGNORE_END,PM_GITIGNORE_RUNTIME_DIRECTORIES,PM_GITIGNORE_START,PM_GITIGNORE_TRACKED_FILES,ensurePmGitignore,getPmGitignoreBlock,isPathOutsideRoot};
+`)?newline:`${newline}${newline}`;return`${current}${separator}${block}${newline}`}let next=current;for(const[index,match]of[...blocks.entries()].reverse())next=`${next.slice(0,match.index)}${index===0?block:""}${next.slice(match.end)}`;return next}async function ensurePmGitignore(workspaceRoot,options={}){const gitignorePath=path.join(workspaceRoot,".gitignore");let trackerRelativeRoot=PM_GITIGNORE_DEFAULT_TRACKER_ROOT;if(options.pmRoot!==void 0){const relative=normalizeTrackerRelativeRoot(path.relative(await physicalInitPath(workspaceRoot),await physicalInitPath(options.pmRoot)));if(isPathOutsideRoot(relative))return{path:gitignorePath,changed:!1};trackerRelativeRoot=relative}let current="";try{current=await withGitignorePermissionRecovery(()=>readFile(gitignorePath,"utf8"))}catch(error){if(!(error instanceof Error&&"code"in error&&isFileMissingError(error)))throw error}const next=reconcileGitignoreContent(current,trackerRelativeRoot);return next===current?{path:gitignorePath,changed:!1}:(await withGitignorePermissionRecovery(()=>writeFile(gitignorePath,next,"utf8")),{path:gitignorePath,changed:!0})}export{PM_GITIGNORE_DEFAULT_TRACKER_ROOT,PM_GITIGNORE_END,PM_GITIGNORE_RUNTIME_DIRECTORIES,PM_GITIGNORE_START,PM_GITIGNORE_TRACKED_FILES,ensurePmGitignore,getPmGitignoreBlock,isPathOutsideRoot};
 //# sourceMappingURL=workspace.js.map

package/docs/CONFIGURATION.md

@@ -82,7 +82,7 @@ If the existing project `settings.json` has invalid JSON, a configuration write
 | `item_format`                              | item storage format (`toon` writes; legacy markdown is read/migrate only)                                                                                                                             |
 | `output.default_format`                    | default renderer, usually `toon`                                                                                                                                                                      |
 | `locks.ttl_seconds`                        | stale lock threshold                                                                                                                                                                                  |
-| `locks.wait_ms`                            | bounded jittered wait budget before a contended item mutation returns `lock_conflict` (default `3000`; set `0` to fail fast)                                                                          |
+| `locks.wait_ms`                            | wait budget before a contended lock returns `lock_conflict`; item-store mutations, restore and the hierarchy lock restart it on each owner handoff (120 s cap), other locks use it as a fixed total (default `3000`; `0` fails fast) |
 | `history.missing_stream`                   | `auto_create` or `strict_error`                                                                                                                                                                       |
 | `history.compact_policy.enabled`           | enable the compaction advisory: `pm health` warns on over-threshold streams (default `false`); when disabled, `max_entries`/`trigger` are inert                                                       |
 | `history.compact_policy.max_entries`       | when the policy is enabled, the entry count above which a stream is flagged by `pm health` and the default `pm history-compact --all-over` threshold (default `500`)                                  |
@@ -115,7 +115,18 @@ receipt before removal; it records the original owner and is an attempted
 recovery audit, not proof that a later mutation committed. Keep these local
 runtime receipts out of version control.
 
-For expected live contention, set `PM_LOCK_WAIT_MS` to a larger bounded
+For item-store mutations (update, close, claim, comments, notes and the other
+item-store writes), restore and the hierarchy-integrity lock (parented creates,
+parent changes and integrity-sensitive dependency additions) the wait budget
+measures stalls, not queue length: while other writers keep acquiring and releasing the
+lock, a waiter keeps waiting (up to 120 s total), so many concurrent agents on
+one tracker queue instead of failing. Other lock users, including package import
+commits and internal short-lived locks, keep a fixed total budget. A lock held by
+the same owner for the whole budget still refuses with `lock_conflict`, whose
+recovery reports `waited_ms` and `owner_handoffs`. A writer whose lease expired
+and was taken over refuses its commit with `lock_lost` instead of overwriting
+the newer write; re-read and apply the change again. For an owner that is
+expected to hold the lock longer, set `PM_LOCK_WAIT_MS` to a larger bounded
 millisecond budget, or configure `locks.wait_ms`, and retry the same operation.
 CLI recovery preserves its normalized arguments and quoted values, including
 whitespace and empty argument strings. Malformed argument vectors are omitted
@@ -167,7 +178,7 @@ underscore aliases remain accepted for compatibility.
 | `PM_AUTHOR`                       | optional explicit session-wide mutation author override                                                                  |
 | `PM_PATH`                         | override project tracker root for tests or sandboxes                                                                     |
 | `PM_GLOBAL_PATH`                  | override global profile root for tests or sandboxes                                                                      |
-| `PM_LOCK_WAIT_MS`                 | per-process override for `locks.wait_ms`; non-negative integer milliseconds, with `0` restoring fail-fast lock conflicts |
+| `PM_LOCK_WAIT_MS`                 | per-process override for the `locks.wait_ms` budget (a no-progress window only where that lock uses the progress policy); non-negative integer milliseconds, with `0` restoring fail-fast lock conflicts |
 | `PM_OLLAMA_MODEL`                 | choose default Ollama embedding model                                                                                    |
 | `PM_DISABLE_OLLAMA_AUTO_DEFAULTS` | disable implicit Ollama search defaults                                                                                  |
 | `PM_CONTEXT_USAGE_DISABLED`       | set to `1` to disable the derived context/next usage-feedback ledger with zero filesystem reads or writes                |
@@ -180,6 +191,11 @@ that look like workspace roots are rejected unless `--force` is provided.
 Initialization maintains the repository's runtime-cache `.gitignore` fence for
 every tracker sharing that repository. Initializing or reinitializing a nested
 tracker preserves the enclosing tracker's exclusions and unrelated user rules.
+Equivalent physical and symlink-addressed paths share the same containment
+check, including tracker directories that initialization has not created yet.
+A symlink leading outside the repository remains an external tracker and does
+not add rules here. This boundary is tracked by
+[pm-p8s5k7e6lhda](../.agents/pm/issues/pm-p8s5k7e6lhda.toon).
 Custom tracker paths are literal Git paths, including spaces and wildcard
 characters. An intentional root-layout tracker uses repository-root exclusions.
 Paths containing line breaks are refused because `.gitignore` cannot safely

package/docs/EXTENSION_AUTHOR_CONTRACTS.md

@@ -76,8 +76,9 @@ Create path:
 `mutateItem` path:
 
 - Used by `pm update`, `pm close`, `pm claim`, `pm release`, `pm restore`, `pm delete`, and other mutations of existing items.
-- Locates the item, acquires the lock, reads the item through the `onRead` hook, enforces ownership and history policy, applies the mutation, consults `item_store_write`, writes the item atomically, appends history, fires `onWrite` for the item and history stream, records the after-command affected-item snapshot, then releases the lock.
+- Locates the item, acquires the lock, reads the item through the `onRead` hook, enforces ownership and history policy, applies the mutation, enters the commit fence, consults `item_store_write`, writes the item atomically, appends history, fires `onWrite` for the item and history stream, records the after-command affected-item snapshot, then releases the lock.
 - `item_store_write` handlers can redirect the target path, replace serialized contents, or skip the physical item write.
+- The commit fence verifies the lock lease and the stored item revision first. When the lease was taken over (`lock_lost`) or the item changed after the read (`stale_revision`), the mutation refuses before `item_store_write` or `item_store_delete` (non-dry-run) runs, so a handler that persists the payload itself never commits a refused write.
 
 Both paths guarantee:
 

package/docs/EXTENSION_LIFECYCLE.md

@@ -4,6 +4,9 @@ Tracked by [pm-ig5cfe](../.agents/pm/issues/pm-ig5cfe.toon),
 [pm-495lkc](../.agents/pm/issues/pm-495lkc.toon), and
 [pm-miy5k6](../.agents/pm/issues/pm-miy5k6.toon).
 Static inventory is tracked by [pm-lhhnx9](../.agents/pm/issues/pm-lhhnx9.toon).
+Verified replacements and disabled compatibility findings are tracked by
+[pm-c9wz5ef4ulnv](../.agents/pm/issues/pm-c9wz5ef4ulnv.toon) and
+[pm-5xn8we1wue0m](../.agents/pm/issues/pm-5xn8we1wue0m.toon).
 
 ## Read-only configured inventory
 
@@ -32,6 +35,45 @@ each. Use `pm install npm:<package>` to force npm identity or the reported bare
 alias command to force the bundled package. Install-all results carry the same
 receipt on every package row.
 
+## Verified replacements
+
+`pm package install` and the SDK's `runExtension(source, { install: true }, global)`
+retain the previous installation through fresh-module runtime verification and
+contribution persistence. When a copied replacement fails to load or activate,
+pm restores the previous package tree and exact managed/settings content. A
+settings restoration appends a compensating workspace-history event.
+
+The failed attempt still returns `ok: false` and its candidate diagnostics, with
+`previous_state_preserved: true`, `overwritten: false`, and
+`rollback.status: "restored"`. The previous command remains available in a new
+process. Multi-target and install-all receipts retain these fields per package.
+SDK `ExtensionCommandResult` / `PackageCommandResult` consumers can narrow
+`details.rollback.status` to access typed recovery arguments on failed restoration.
+These two diagnostic keys are now reserved typed fields. Code constructing
+lifecycle result objects or test doubles must use the boolean and rollback
+shapes, or rename custom metadata stored under those keys. Ordinary result
+readers remain compatible; the runtime implementation is unchanged by this
+declaration refinement.
+
+If restoration fails, `previous_state_preserved` is false. The retained backup
+and executable `rollback.recovery_args` / `rollback.recovery_command` identify a
+source for reinstalling the previous package. Resolve the reported filesystem
+failure first. Fresh installations and installations whose source is already
+the destination retain failed code for diagnosis and report
+`previous_state_preserved: false`; they have no earlier package version to
+recover. Package code can have external side effects during activation; this
+snapshot protects the installation and its managed/settings content.
+
+## Disabled package compatibility
+
+An explicitly disabled package remains visible in inventory and discovery.
+Its host-version warnings use `extension_disabled_pm_*` codes and are advisory
+in health, including `--strict-exit`. Each finding identifies the package,
+required bound and scoped activation command to use after satisfying that
+bound. Enabled packages retain the ordinary `extension_pm_*` compatibility
+checks and blocking policy. Deactivation does not permit incompatible code to
+load or suppress malformed-manifest, missing-entry or other unrelated findings.
+
 ## Durable Extension Migrations
 
 Active packages register schema migrations through `api.registerMigration`.
@@ -62,3 +104,8 @@ compose without warnings, and runtime invokes only the matching owner. Empty or
 omitted command ownership retains the legacy global behavior and collides with
 every other override. Activation summaries and persisted contribution
 inventories expose `preflight_ownership` for static doctor and tooling output.
+
+Rollback failures retain the initial error as their cause and expose an original
+typed refusal as `context.original_code`, while keeping the rollback code and
+exit policy. This diagnostic boundary is tracked by
+[pm-4vymxc](../.agents/pm/issues/pm-4vymxc.toon).