@unbrained/pm-cli 2026.8.7 → 2026.8.8

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

@@ -45,13 +45,13 @@ export interface RunHealthOptions {
     strictDirectories?: boolean;
     /** Treat absent clone-local merge drivers as a required health failure instead of an advisory. */
     requireMergeDrivers?: boolean;
-    /** Value that configures or reports check only for this contract. */
+    /** Preserve the legacy compact check projection while keeping diagnostics read-only. */
     checkOnly?: boolean;
     /** Value that configures or reports check telemetry for this contract. */
     checkTelemetry?: boolean;
-    /** Value that configures or reports no refresh for this contract. */
+    /** Explicitly document that vector refresh is disabled. */
     noRefresh?: boolean;
-    /** Value that configures or reports refresh vectors for this contract. */
+    /** Opt in to the only mutating health operation: refreshing stale vectors. */
     refreshVectors?: boolean;
     /** Value that configures or reports verbose stale items for this contract. */
     verboseStaleItems?: boolean;
@@ -70,6 +70,12 @@ export interface RunHealthOptions {
     /** Value that configures or reports summary for this contract. */
     summary?: boolean;
 }
+interface VectorRefreshPolicy {
+    enabled: boolean;
+    checkOnly: boolean;
+    noRefresh: boolean;
+    refreshVectors: boolean;
+}
 interface MigrationStatusEntry {
     layer: "global" | "project";
     name: string;
@@ -163,6 +169,7 @@ declare function probeTelemetryEndpointHealth(endpoint: string): Promise<{
     error?: string;
 }>;
 declare function buildVectorizationProviderDetails(settings: PmSettings, snapshot: VectorizationRuntimeSnapshot): Record<string, unknown>;
+declare function resolveVectorRefreshPolicy(options: RunHealthOptions): VectorRefreshPolicy;
 interface HealthSkipPolicy {
     summaryMode: boolean;
     skipIntegrity: boolean;
@@ -196,6 +203,7 @@ export declare const _testOnlyHealthCommand: {
     resolveActionableUnknownAuthorEventCount: (authorAttribution: HistoryAuthorAttributionScan) => number;
     resolveHealthSkipPolicy: typeof resolveHealthSkipPolicy;
     resolveUnknownAuthorEventCount: (authorAttribution: HistoryAuthorAttributionScan) => number;
+    resolveVectorRefreshPolicy: typeof resolveVectorRefreshPolicy;
     selectStaleItemDetail: typeof selectStaleItemDetail;
     summarizeHealthCheckDetails: typeof summarizeHealthCheckDetails;
     summarizeExtensionList: typeof summarizeExtensionList;

package/dist/sdk/governance/health.js

@@ -4,7 +4,7 @@
  * Implements the pm health command surface and its agent-facing runtime behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="34fc99f6-45e5-53f2-96eb-767d50ed449c")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="4efa3db2-6be7-5650-b1c7-d80e125694aa")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { resolveItemTypeRegistry } from "../../core/item/type-registry.js";
@@ -1549,7 +1549,6 @@ function validateSettingsValues(settings) {
 }
 function resolveVectorRefreshPolicy(options) {
     const checkOnly = options.checkOnly === true;
-    const noRefresh = options.noRefresh === true || checkOnly;
     const refreshVectors = options.refreshVectors === true;
     if (refreshVectors && checkOnly) {
         throw new PmCliError("--check-only cannot be combined with --refresh-vectors", EXIT_CODE.USAGE);
@@ -1558,9 +1557,9 @@ function resolveVectorRefreshPolicy(options) {
         throw new PmCliError("--no-refresh cannot be combined with --refresh-vectors", EXIT_CODE.USAGE);
     }
     return {
-        enabled: refreshVectors || !noRefresh,
+        enabled: refreshVectors,
         checkOnly,
-        noRefresh,
+        noRefresh: !refreshVectors,
         refreshVectors,
     };
 }
@@ -1955,6 +1954,7 @@ export const _testOnlyHealthCommand = {
     resolveActionableUnknownAuthorEventCount,
     resolveHealthSkipPolicy,
     resolveUnknownAuthorEventCount,
+    resolveVectorRefreshPolicy,
     selectStaleItemDetail,
     summarizeHealthCheckDetails,
     summarizeExtensionList,
@@ -1964,4 +1964,4 @@ export const _testOnlyHealthCommand = {
     warningCode,
 };
 //# sourceMappingURL=health.js.map
-//# debugId=34fc99f6-45e5-53f2-96eb-767d50ed449c
+//# debugId=4efa3db2-6be7-5650-b1c7-d80e125694aa

package/dist/sdk/index.d.ts

@@ -6,8 +6,8 @@
 export { PM_COMMAND_VISIBILITY_CONTRACTS, PM_MCP_PROMPT_CONTRACTS, PM_MCP_RESOURCE_CONTRACTS, PM_MCP_TOOL_COMMAND_CONTRACTS, listPmCommandsForTier, listPmMcpToolsForProfile, renderPmCommandVisibilityMarkdown, resolvePmCommandVisibilityTier, } from "./agent-capability-contracts.js";
 export * from "./agent-session-context.js";
 export type { PmCommandVisibilityContract, PmCommandVisibilityTier, PmMcpPromptArgumentContract, PmMcpPromptContract, PmMcpResourceContract, PmMcpToolProfile, } from "./agent-capability-contracts.js";
-export { isErrnoError, limitAnnotationEntries, parseAnnotationTextInput, readAnnotationEntries, resolveAnnotationInput, resolveAnnotationIndex, runAnnotationCommand, wrapOwnershipConflict, type AnnotationCommandConfig, type AnnotationCommandOptions, type AnnotationCommandResult, type AnnotationEntry, type AnnotationInput, type AnnotationSourceOptions, type OwnershipConflictGuidance, } from "./annotations.js";
-export { acknowledgeUnknownAuthorHistoryEvents, inspectHistoryAuthorStream, scanHistoryAuthorAttribution, type AcknowledgeUnknownAuthorEventsOptions, type HistoryAuthorAttributionScan, type UnknownAuthorHistoryEvent, } from "./author-attribution.js";
+export { isErrnoError, limitAnnotationEntries, parseAnnotationTextInput, readAnnotationEntries, normalizeAnnotationTransportOptions, resolveAnnotationInput, resolveAnnotationIndex, runAnnotationCommand, wrapOwnershipConflict, type AnnotationCommandConfig, type AnnotationCommandOptions, type AnnotationCommandResult, type AnnotationEntry, type AnnotationInput, type AnnotationHistoryRestoration, type AnnotationMutationReceipt, type AnnotationOmissionReceipt, type AnnotationSourceOptions, type OwnershipConflictGuidance, } from "./annotations.js";
+export { acknowledgeUnknownAuthorHistoryEvents, acknowledgeUnknownAuthorHistoryEventsFromTransport, inspectHistoryAuthorStream, parseUnknownAuthorHistoryEventCoordinates, resolveUnknownAuthorAcknowledgmentSelector, scanHistoryAuthorAttribution, type AcknowledgeUnknownAuthorEventsOptions, type HistoryAuthorAttributionScan, type UnknownAuthorHistoryEvent, } from "./author-attribution.js";
 export { BUILTIN_CORPUS_SHAPES, PM_CORPUS_SHAPE_SCHEMA, buildCorpusShapeItemPlan, createCorpusShapeMeasurement, defineCorpusShape, listBuiltinCorpusShapes, measureCorpusShapePlan, resolveBuiltinCorpusShape, type BuiltinCorpusShapeName, type CorpusShape, type CorpusShapeEdgeWeight, type CorpusShapeItemPlan, type CorpusShapeMeasurement, type CorpusShapeProfile, } from "./corpus-shape.js";
 export * from "./core-governance.js";
 export { createPmCliProgram } from "./cli-program.js";
@@ -29,7 +29,7 @@ export { runEvent, runMeet, runRemind, type MeetingEventShortcutOptions, type Re
 export { createExtensionCommandSdk } from "./extension-command-context.js";
 export { isRuntimeRecord } from "./runtime-input.js";
 export { resolveStartTaskInProgressStatus } from "./start-task-status.js";
-export { auditMergeAttributeFence, buildMergeAttributePatterns, findGitWorkspaceRoot, installMergeFence, refreshMergeAttributeFenceIfInstalled, resolveProjectMergeTypeFolders, runMergeInstall, type MergeFenceAuditResult, type MergeFenceRefreshOutcome, type MergeInstallOptions, type MergeInstallResult, } from "./merge/install.js";
+export { auditMergeAttributeFence, buildMergeAttributePatterns, findGitWorkspaceRoot, installMergeFence, refreshMergeAttributeFenceIfInstalled, resolveMergeInstallContext, resolveProjectMergeTypeFolders, runMergeInstall, type MergeFenceAuditResult, type MergeFenceRefreshOutcome, type MergeInstallOptions, type MergeInstallContextResolution, type MergeInstallResult, } from "./merge/install.js";
 export { deriveSchemaEvolutionMigrationId, formatSchemaEvolutionMigrationHuman, planSchemaEvolutionMigration, runSchemaEvolutionMigration, type PlanSchemaEvolutionMigrationOptions, type SchemaEvolutionFieldChange, type SchemaEvolutionItemPlan, type SchemaEvolutionMigrationPlan, } from "./schema-migration.js";
 export { runWithActiveExtensions, type ActiveExtensionScopeOptions, } from "./runtime.js";
 export { applyInvocationAuthorOverride } from "./invocation-author.js";
@@ -52,6 +52,10 @@ export { ACTIVITY_FLAG_CONTRACTS, ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, AG
 export type { CliFlagContract, OptionsFromContracts, PmActionSchemaContract, PmActionToolInputSchemaOptions, PmToolCustomFieldCollision, PmBulkMutationControlOptions, PmBulkMutationFilterOptions, PmCloseActionOptions, PmCloseManyActionOptions, PmCreateActionOptions, PmMutationAttributionOptions, PmOptionScalar, PmCommandOutputBudgetContract, PmOutputBudgetClass, PmOutputDegradationStep, PmUpdateActionOptions, PmUpdateManyActionOptions, PmExtensionCapabilityContract, PmExtensionPolicyModeContract, PmExtensionPolicySurfaceContract, PmExtensionSandboxProfileContract, PmExtensionServiceNameContract, PmExtensionTrustModeContract, PmToolAction, SdkCliActionParameterCoverage, SdkCliCompletenessContractSource, SdkCliParameterCoverageEntry, SdkCliParameterDisposition, ToolOptionFlagContract, } from "./cli-contracts.js";
 export * from "./compose.js";
 export * from "./compile-cache.js";
+export * from "./environment/project-runtime-compatibility.js";
+export * from "./environment/source-context.js";
+export * from "./environment/host-environment-errors.js";
+export * from "./cli-contracts/command-exit-contracts.js";
 export * from "./context-relevance.js";
 export * from "./context-intent-contracts.js";
 export * from "./context-intent-runtime.js";

package/dist/sdk/index.js

@@ -4,11 +4,11 @@
  * Defines public SDK APIs and package-author helpers for Index.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="346cbfc0-a42a-5ae6-b95a-af3bd63fc6d1")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="ae84c7af-bfa7-577d-b9f3-2bd9450d5755")}catch(e){}}();
 export { PM_COMMAND_VISIBILITY_CONTRACTS, PM_MCP_PROMPT_CONTRACTS, PM_MCP_RESOURCE_CONTRACTS, PM_MCP_TOOL_COMMAND_CONTRACTS, listPmCommandsForTier, listPmMcpToolsForProfile, renderPmCommandVisibilityMarkdown, resolvePmCommandVisibilityTier, } from "./agent-capability-contracts.js";
 export * from "./agent-session-context.js";
-export { isErrnoError, limitAnnotationEntries, parseAnnotationTextInput, readAnnotationEntries, resolveAnnotationInput, resolveAnnotationIndex, runAnnotationCommand, wrapOwnershipConflict, } from "./annotations.js";
-export { acknowledgeUnknownAuthorHistoryEvents, inspectHistoryAuthorStream, scanHistoryAuthorAttribution, } from "./author-attribution.js";
+export { isErrnoError, limitAnnotationEntries, parseAnnotationTextInput, readAnnotationEntries, normalizeAnnotationTransportOptions, resolveAnnotationInput, resolveAnnotationIndex, runAnnotationCommand, wrapOwnershipConflict, } from "./annotations.js";
+export { acknowledgeUnknownAuthorHistoryEvents, acknowledgeUnknownAuthorHistoryEventsFromTransport, inspectHistoryAuthorStream, parseUnknownAuthorHistoryEventCoordinates, resolveUnknownAuthorAcknowledgmentSelector, scanHistoryAuthorAttribution, } from "./author-attribution.js";
 export { BUILTIN_CORPUS_SHAPES, PM_CORPUS_SHAPE_SCHEMA, buildCorpusShapeItemPlan, createCorpusShapeMeasurement, defineCorpusShape, listBuiltinCorpusShapes, measureCorpusShapePlan, resolveBuiltinCorpusShape, } from "./corpus-shape.js";
 export * from "./core-governance.js";
 export { createPmCliProgram } from "./cli-program.js";
@@ -30,7 +30,7 @@ export { runEvent, runMeet, runRemind, } from "./scheduling-shortcuts.js";
 export { createExtensionCommandSdk } from "./extension-command-context.js";
 export { isRuntimeRecord } from "./runtime-input.js";
 export { resolveStartTaskInProgressStatus } from "./start-task-status.js";
-export { auditMergeAttributeFence, buildMergeAttributePatterns, findGitWorkspaceRoot, installMergeFence, refreshMergeAttributeFenceIfInstalled, resolveProjectMergeTypeFolders, runMergeInstall, } from "./merge/install.js";
+export { auditMergeAttributeFence, buildMergeAttributePatterns, findGitWorkspaceRoot, installMergeFence, refreshMergeAttributeFenceIfInstalled, resolveMergeInstallContext, resolveProjectMergeTypeFolders, runMergeInstall, } from "./merge/install.js";
 export { deriveSchemaEvolutionMigrationId, formatSchemaEvolutionMigrationHuman, planSchemaEvolutionMigration, runSchemaEvolutionMigration, } from "./schema-migration.js";
 export { runWithActiveExtensions, } from "./runtime.js";
 export { applyInvocationAuthorOverride } from "./invocation-author.js";
@@ -50,6 +50,10 @@ export { PM_PACKAGE_CONVENTIONAL_RESOURCE_ROOTS, PM_PACKAGE_RESOURCE_KINDS, coll
 export { ACTIVITY_FLAG_CONTRACTS, ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, AGGREGATE_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS, CALENDAR_FLAG_CONTRACTS, CLAIM_FLAG_CONTRACTS, CLOSE_ACTION_OPTION_KEYS, CLOSE_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, CLOSE_TASK_FLAG_CONTRACTS, COMMENTS_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONFIG_FLAG_CONTRACTS, CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS, CONTEXT_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, CREATE_COMMANDER_STRING_OPTION_CONTRACTS, CREATE_FLAG_CONTRACTS, DELETE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, DOCS_FLAG_CONTRACTS, EVAL_FLAG_CONTRACTS, EVENT_FLAG_CONTRACTS, EVENTS_FLAG_CONTRACTS, EXTENSION_ACTIVATE_FLAG_CONTRACTS, EXTENSION_ADOPT_ALL_FLAG_CONTRACTS, EXTENSION_ADOPT_FLAG_CONTRACTS, EXTENSION_CATALOG_FLAG_CONTRACTS, EXTENSION_DEACTIVATE_FLAG_CONTRACTS, EXTENSION_DESCRIBE_FLAG_CONTRACTS, EXTENSION_DOCTOR_FLAG_CONTRACTS, EXTENSION_EXPLORE_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, EXTENSION_INIT_FLAG_CONTRACTS, EXTENSION_INSTALL_FLAG_CONTRACTS, EXTENSION_MANAGE_FLAG_CONTRACTS, EXTENSION_MIGRATE_FLAG_CONTRACTS, EXTENSION_RELOAD_FLAG_CONTRACTS, EXTENSION_SCOPE_FLAG_CONTRACTS, EXTENSION_UNINSTALL_FLAG_CONTRACTS, FILES_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, GC_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, HISTORY_COMPACT_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, HISTORY_REDACT_FLAG_CONTRACTS, HISTORY_REPAIR_FLAG_CONTRACTS, HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, INSTALL_FLAG_CONTRACTS, ITEM_MUTATE_FLAG_CONTRACTS, ITEM_COMPLETE_FLAG_CONTRACTS, LEARNINGS_FLAG_CONTRACTS, LIST_COMMANDER_STRING_OPTION_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, MEET_FLAG_CONTRACTS, MERGE_FLAG_CONTRACTS, NEXT_COMMANDER_STRING_OPTION_CONTRACTS, NEXT_FLAG_CONTRACTS, NOTES_FLAG_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PACKAGE_INIT_FLAG_CONTRACTS, PAUSE_TASK_FLAG_CONTRACTS, PLAN_CREATE_METADATA_PARAMETER_KEYS, PLAN_FLAG_CONTRACTS, PM_COMMAND_OUTPUT_BUDGET_CONTRACTS, PM_CLI_ONLY_TOOL_ACTION_WAIVERS, PM_CORE_COMMAND_NAMES, PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS, PM_EXTENSION_CAPABILITY_CONTRACTS, PM_EXTENSION_POLICY_MODE_CONTRACTS, PM_EXTENSION_POLICY_SURFACE_CONTRACTS, PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS, PM_EXTENSION_SERVICE_NAME_CONTRACTS, PM_EXTENSION_TRUST_MODE_CONTRACTS, PM_PROVIDER_TOOL_PARAMETERS_SCHEMA, PM_PROVIDER_TOOL_PARAMETERS_SCHEMA_VERSION, PM_TOOL_ACTIONS, analyzePmToolActionParity, PM_TOOL_ACTION_PARAMETER_CONTRACTS, PM_TOOL_PARAMETERS_SCHEMA, PM_TOOL_PARAMETERS_SCHEMA_MAJOR, PM_TOOL_PARAMETERS_SCHEMA_VERSION, PM_OUTPUT_BUDGET_CLASSES, PM_OUTPUT_DEGRADATION_STEPS, PROFILE_FLAG_CONTRACTS, REINDEX_FLAG_CONTRACTS, RELEASE_FLAG_CONTRACTS, REMIND_FLAG_CONTRACTS, RESTORE_FLAG_CONTRACTS, SCHEMA_FLAG_CONTRACTS, SEARCH_COMMANDER_STRING_OPTION_CONTRACTS, SEARCH_FLAG_CONTRACTS, START_TASK_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, SUBCOMMAND_GLOBAL_FLAG_CONTRACTS, TELEMETRY_FLAG_CONTRACTS, TEST_ALL_FLAG_CONTRACTS, TEST_FLAG_CONTRACTS, TEST_RUNS_FLAG_CONTRACTS, TOOL_ACTIVITY_OPTION_CONTRACTS, TOOL_AGGREGATE_OPTION_CONTRACTS, TOOL_BULK_MUTATION_FILTER_OPTION_CONTRACT_SOURCE, TOOL_CALENDAR_OPTION_CONTRACTS, TOOL_CLOSE_MANY_FILTER_OPTION_CONTRACTS, TOOL_CONTEXT_OPTION_CONTRACTS, TOOL_CREATE_OPTION_CONTRACTS, TOOL_CREATE_OPTION_CONTRACT_SOURCE, TOOL_DEPS_OPTION_CONTRACTS, TOOL_GRAPH_OPTION_CONTRACTS, TOOL_LIST_FILTER_OPTION_CONTRACTS, TOOL_SEARCH_FILTER_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACT_SOURCE, TOOL_UPDATE_MANY_FILTER_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACT_SOURCE, UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, UPDATE_COMMANDER_STRING_OPTION_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, UPGRADE_FLAG_CONTRACTS, VALIDATE_FLAG_CONTRACTS, WORKSPACE_FLAG_CONTRACTS, buildPmActionToolInputSchema, PM_TOOL_RESERVED_CUSTOM_FIELD_PROPERTIES, compactFlagAliasContracts, createPmCommandOutputBudget, definePmCommandOutputBudget, estimatePmOutputTokens, inferPmOutputBudgetClass, analyzeSdkCliParameterCompleteness, isPmExtensionCapabilityContract, isPmExtensionPolicyModeContract, isPmExtensionPolicySurfaceContract, isPmExtensionServiceNameContract, isPmToolAction, hasSubcommandFlagContractsForCommand, readFirstStringFromCommanderOptions, readFirstValueFromCommanderOptions, readStringArrayFromCommanderOptions, resolveSubcommandFlagContractsForCommand, resolvePmCommandOutputBudget, resolvePmToolCustomFieldCollision, toCompletionFlagString, withFlagAliasMetadata, } from "./cli-contracts.js";
 export * from "./compose.js";
 export * from "./compile-cache.js";
+export * from "./environment/project-runtime-compatibility.js";
+export * from "./environment/source-context.js";
+export * from "./environment/host-environment-errors.js";
+export * from "./cli-contracts/command-exit-contracts.js";
 export * from "./context-relevance.js";
 export * from "./context-intent-contracts.js";
 export * from "./context-intent-runtime.js";
@@ -137,4 +141,4 @@ export * from "./governance.js";
 export * from "./query.js";
 export * from "./testing.js";
 //# sourceMappingURL=index.js.map
-//# debugId=346cbfc0-a42a-5ae6-b95a-af3bd63fc6d1
+//# debugId=ae84c7af-bfa7-577d-b9f3-2bd9450d5755

package/dist/sdk/learnings.d.ts

@@ -5,6 +5,7 @@
  */
 import { type GlobalOptions } from "./runtime-primitives.js";
 import type { LogNote } from "../types/index.js";
+import { type AnnotationMutationReceipt, type AnnotationOmissionReceipt } from "./annotations.js";
 /** Documents the learnings command options payload exchanged by command, SDK, and package integrations. */
 export interface LearningsCommandOptions {
     /** Value that configures or reports add for this contract. */
@@ -19,6 +20,8 @@ export interface LearningsCommandOptions {
     delete?: number;
     /** Value that configures or reports limit for this contract. */
     limit?: string;
+    /** Return complete learning history after a mutation instead of a bounded receipt. */
+    fullHistory?: boolean;
     /** Value that configures or reports author for this contract. */
     author?: string;
     /** Human-readable explanation suitable for logs and agent-facing output. */
@@ -34,6 +37,18 @@ export interface LearningsResult {
     learnings: LogNote[];
     /** Value that configures or reports count for this contract. */
     count: number;
+    /** Total learning count after the mutation. */
+    total_count?: number;
+    /** Number of learning entries returned in this projection. */
+    returned_count?: number;
+    /** Whether additional stored learning entries were withheld. */
+    has_more?: boolean;
+    /** Applied read limit when one was requested. */
+    limit?: number;
+    /** Mutation identity when this result changed the collection. */
+    mutation_receipt?: AnnotationMutationReceipt;
+    /** Declares whether older learnings were withheld from a mutation response. */
+    omission_receipt?: AnnotationOmissionReceipt;
 }
 /** Implements run learnings for the public runtime surface of this module. */
 export declare function runLearnings(id: string, options: LearningsCommandOptions, global: GlobalOptions): Promise<LearningsResult>;

package/dist/sdk/learnings.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="26e30c82-7d6d-51b9-909f-b779213846b1")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="93184f29-f215-5413-9628-fb5b34523995")}catch(e){}}();
 import { parseAnnotationTextInput, resolveAnnotationInput, runAnnotationCommand, } from "./annotations.js";
 /** Implements run learnings for the public runtime surface of this module. */
 export async function runLearnings(id, options, global) {
@@ -24,4 +24,4 @@ export async function runLearnings(id, options, global) {
     });
 }
 //# sourceMappingURL=learnings.js.map
-//# debugId=26e30c82-7d6d-51b9-909f-b779213846b1
+//# debugId=93184f29-f215-5413-9628-fb5b34523995

package/dist/sdk/lifecycle/close-many.d.ts

@@ -5,6 +5,7 @@
  */
 import { type GlobalOptions, readSettings } from "../runtime-primitives.js";
 import { type ListOptions } from "../query/list.js";
+import { type PmCommandEffectReceipt } from "../cli-contracts/command-exit-contracts.js";
 /** Documents the close many command options payload exchanged by command, SDK, and package integrations. */
 export interface CloseManyCommandOptions {
     /** Lifecycle state reported for status. */
@@ -55,7 +56,7 @@ interface CloseManyApplyRow {
     error?: string;
 }
 /** Documents the close many result payload exchanged by command, SDK, and package integrations. */
-export interface CloseManyResult {
+export interface CloseManyResult extends PmCommandEffectReceipt {
     /** Value that configures or reports mode for this contract. */
     mode: "dry_run" | "apply" | "rollback";
     /** Number of matched entries represented by this result. */
@@ -97,6 +98,10 @@ export interface CloseManyResult {
     }>;
     /** Value that configures or reports ids for this contract. */
     ids: string[];
+    /** Explicitly requested --ids values that matched no selected item. */
+    unmatched_ids?: string[];
+    /** Number of explicitly requested --ids values that matched no selected item. */
+    unmatched_count?: number;
 }
 declare function hasCloseManyFilters(list: ListOptions | undefined, status: string | undefined): boolean;
 declare function hasCloseManyRollbackConflicts(list: ListOptions | undefined, status: string | undefined): boolean;

package/dist/sdk/lifecycle/close-many.js

@@ -4,12 +4,13 @@
  * Implements the pm close many command surface and its agent-facing runtime behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="1be4d7c4-3ede-59cc-8d70-df966a66e67e")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="4da07a98-855e-59cf-a6a4-2f59a8b3c0bd")}catch(e){}}();
 import { pathExists, createCheckpointId, loadMutationCheckpoint, restoreCheckpointItems, writeMutationCheckpoint, getActiveExtensionRegistrations, isTerminalStatus, resolveItemTypeRegistry, resolveRuntimeStatusRegistry, EXIT_CODE, PmCliError, toErrorMessage, resolveAuthor, nowIso, listAllItemMetadataLight, getSettingsPath, resolvePmRoot, readSettings, } from "../runtime-primitives.js";
 import { runClose } from "./close.js";
 import { hasListFilters } from "../query/list-filter-shared.js";
 import { runList } from "../query/list.js";
 import { runRestore } from "./restore.js";
+import { derivePmBulkMutationEffect, } from "../cli-contracts/command-exit-contracts.js";
 const CLOSE_MANY_CHECKPOINT_SCHEMA_VERSION = 1;
 const CLOSE_MANY_CHECKPOINT_SUBDIR = "close-many";
 const CLOSE_MANY_FILTER_GUIDANCE = [
@@ -139,6 +140,12 @@ async function runCloseManyRollback(params) {
     const restoreMessage = params.options.message ?? `Rollback close-many checkpoint ${checkpoint.id}`;
     const rollback = await restoreCheckpointItems(checkpoint.items, (id, targetUpdatedAt) => runRestore(id, targetUpdatedAt, { author: params.options.author, message: restoreMessage, force: true }, params.global));
     return {
+        ...derivePmBulkMutationEffect({
+            applied: rollback.restored_ids.length,
+            skipped: 0,
+            failed: rollback.failed_count,
+            unmatched: 0,
+        }),
         mode: "rollback",
         matched_count: checkpoint.items.length,
         dry_run: false,
@@ -266,6 +273,13 @@ async function buildCloseManyPlanContext(params) {
     const listed = await runList(params.options.status, activeListOptions(params.options.list), params.global);
     const { childrenByParent, parentByChild } = await buildActiveChildrenByParent(params.pmRoot, params.settings);
     const matched = sortCloseManyMatchedItems(listed.items, parentByChild);
+    const requestedIds = [
+        ...new Set(String(params.options.list?.ids ?? "")
+            .split(",")
+            .map((entry) => entry.trim())
+            .filter((entry) => entry.length > 0)),
+    ];
+    const matchedIds = new Set(matched.map((item) => item.id));
     const closePlannedIds = resolveCloseManyPlannedIds(matched, statusRegistry, force);
     return {
         pmRoot: params.pmRoot,
@@ -276,11 +290,14 @@ async function buildCloseManyPlanContext(params) {
         force,
         listed,
         matched,
+        unmatchedIds: requestedIds.filter((id) => !matchedIds.has(id)),
         planRows: planCloseManyRows(matched, childrenByParent, closePlannedIds, statusRegistry, force),
     };
 }
 function buildCloseManyDryRunResult(context) {
     return {
+        outcome: "effect",
+        exit_code: EXIT_CODE.SUCCESS,
         mode: "dry_run",
         matched_count: context.matched.length,
         dry_run: true,
@@ -291,6 +308,12 @@ function buildCloseManyDryRunResult(context) {
             : {}),
         item_plans: context.planRows,
         ids: [],
+        ...(context.unmatchedIds.length > 0
+            ? {
+                unmatched_ids: context.unmatchedIds,
+                unmatched_count: context.unmatchedIds.length,
+            }
+            : {}),
     };
 }
 async function resolveCloseManyCheckpointInfo(params) {
@@ -362,7 +385,16 @@ export async function runCloseMany(options, global) {
         closeOptions,
         global,
     });
+    const closedCount = rows.filter((row) => row.status === "closed").length;
+    const skippedCount = rows.filter((row) => row.status === "skipped").length;
+    const failedCount = rows.filter((row) => row.status === "failed").length;
     return {
+        ...derivePmBulkMutationEffect({
+            applied: closedCount,
+            skipped: skippedCount,
+            failed: failedCount,
+            unmatched: context.unmatchedIds.length,
+        }),
         mode: "apply",
         matched_count: context.matched.length,
         dry_run: false,
@@ -372,11 +404,17 @@ export async function runCloseMany(options, global) {
             ? { validate_close: context.validateCloseMode }
             : {}),
         ...(checkpointInfo ? { checkpoint: checkpointInfo } : {}),
-        closed_count: rows.filter((row) => row.status === "closed").length,
-        skipped_count: rows.filter((row) => row.status === "skipped").length,
-        failed_count: rows.filter((row) => row.status === "failed").length,
+        closed_count: closedCount,
+        skipped_count: skippedCount,
+        failed_count: failedCount,
         rows,
         ids: closedIds,
+        ...(context.unmatchedIds.length > 0
+            ? {
+                unmatched_ids: context.unmatchedIds,
+                unmatched_count: context.unmatchedIds.length,
+            }
+            : {}),
     };
 }
 /** Public contract for test only, shared by SDK and presentation-layer consumers. */
@@ -390,4 +428,4 @@ export const _testOnly = {
     resolveReason,
 };
 //# sourceMappingURL=close-many.js.map
-//# debugId=1be4d7c4-3ede-59cc-8d70-df966a66e67e
+//# debugId=4da07a98-855e-59cf-a6a4-2f59a8b3c0bd

package/dist/sdk/lifecycle/update-many.d.ts

@@ -8,6 +8,7 @@ import type { ItemStatus, PmSettings } from "../../types/index.js";
 import { hasListFilters } from "../query/list-filter-shared.js";
 import { type ListOptions, type ListedItem } from "../query/list.js";
 import { type UpdateCommandOptions } from "./update.js";
+import { type PmCommandEffectReceipt } from "../cli-contracts/command-exit-contracts.js";
 /** Documents the update many command options payload exchanged by command, SDK, and package integrations. */
 export interface UpdateManyCommandOptions {
     /** Lifecycle state reported for status. */
@@ -50,7 +51,7 @@ interface UpdateManyRollbackResultRow {
     error?: string;
 }
 /** Documents the update many result payload exchanged by command, SDK, and package integrations. */
-export interface UpdateManyResult {
+export interface UpdateManyResult extends PmCommandEffectReceipt {
     /** Value that configures or reports mode for this contract. */
     mode: "dry_run" | "apply" | "rollback";
     /** Number of matched entries represented by this result. */

package/dist/sdk/lifecycle/update-many.js

@@ -4,13 +4,14 @@
  * Implements the pm update many command surface and its agent-facing runtime behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="61fe3a97-39e6-53de-8663-8e70d931a2d4")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="67f8958d-60d5-5657-93ce-9803859acd9e")}catch(e){}}();
 import { pathExists, createCheckpointId, loadMutationCheckpoint, restoreCheckpointItems, writeMutationCheckpoint, toItemRecord, applyAcceptanceCriteriaMutations, applyTagRemovals, mergeAdditiveTags, parseOptionalNonNegativeInteger, parseTags, splitAcceptanceCriteria, resolvePriority, normalizeStatusInput, resolveItemTypeRegistry, resolveTypeName, collectRuntimeUpdateFieldValues, buildInvalidTypeError, resolveItemTypesFilePath, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, EXIT_CODE, PmCliError, toErrorMessage, stableValueEquals, nowIso, resolveIsoOrRelative, getActiveExtensionRegistrations, getSettingsPath, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
 import { parseStatusFilterCsv } from "../../core/item/status-filter.js";
 import { hasListFilters } from "../query/list-filter-shared.js";
 import { runList, } from "../query/list.js";
 import { runRestore } from "./restore.js";
 import { runUpdate } from "./update.js";
+import { derivePmBulkMutationEffect, } from "../cli-contracts/command-exit-contracts.js";
 const UPDATE_MANY_CHECKPOINT_SCHEMA_VERSION = 1;
 const UPDATE_MANY_CHECKPOINT_SUBDIR = "update-many";
 const NON_MUTATION_UPDATE_OPTION_KEYS = new Set([
@@ -519,6 +520,12 @@ const runUpdateManyRollback = async (params) => {
         force: params.options.update?.force ?? true,
     }, params.global));
     return {
+        ...derivePmBulkMutationEffect({
+            applied: rollback.restored_ids.length,
+            skipped: 0,
+            failed: rollback.failed_count,
+            unmatched: 0,
+        }),
         mode: "rollback",
         matched_count: checkpoint.items.length,
         dry_run: false,
@@ -642,6 +649,8 @@ const buildUpdateManyPlan = async (params) => {
 };
 /** Builds the non-mutating preview response for a prepared update-many plan. */
 const buildUpdateManyDryRunResult = (plan) => ({
+    outcome: "effect",
+    exit_code: EXIT_CODE.SUCCESS,
     mode: "dry_run",
     matched_count: plan.listed.items.length,
     dry_run: true,
@@ -653,6 +662,12 @@ const buildUpdateManyDryRunResult = (plan) => ({
 });
 /** Builds the apply response for a plan whose rows are all already current. */
 const buildUpdateManyNoopResult = (plan) => ({
+    ...derivePmBulkMutationEffect({
+        applied: 0,
+        skipped: plan.listed.items.length,
+        failed: 0,
+        unmatched: plan.unmatchedIds?.length ?? 0,
+    }),
     mode: "apply",
     matched_count: plan.listed.items.length,
     dry_run: false,
@@ -742,16 +757,25 @@ const applyUpdateManyPlan = async (params) => {
     });
     /** Counts apply rows with one terminal status. */
     const countStatus = (status) => applied.rows.filter((row) => row.status === status).length;
+    const updatedCount = countStatus("updated");
+    const skippedCount = countStatus("skipped");
+    const failedCount = countStatus("failed");
     return {
+        ...derivePmBulkMutationEffect({
+            applied: updatedCount,
+            skipped: skippedCount,
+            failed: failedCount,
+            unmatched: params.plan.unmatchedIds?.length ?? 0,
+        }),
         mode: "apply",
         matched_count: params.plan.listed.items.length,
         dry_run: false,
         filters: params.plan.listed.filters,
         planned_update_options: params.plan.updateSummary,
         ...(checkpointInfo ? { checkpoint: checkpointInfo } : {}),
-        updated_count: countStatus("updated"),
-        skipped_count: countStatus("skipped"),
-        failed_count: countStatus("failed"),
+        updated_count: updatedCount,
+        skipped_count: skippedCount,
+        failed_count: failedCount,
         rows: applied.rows,
         ids: applied.updatedIds,
         ...buildUnmatchedIdFields(params.plan),
@@ -804,4 +828,4 @@ export const _testOnlyUpdateManyCommand = {
     toComparablePreviewValue,
 };
 //# sourceMappingURL=update-many.js.map
-//# debugId=61fe3a97-39e6-53de-8663-8e70d931a2d4
+//# debugId=67f8958d-60d5-5657-93ce-9803859acd9e

package/dist/sdk/merge/index.d.ts

@@ -9,5 +9,5 @@
 export { ITEM_LATEST_TIMESTAMP_FIELDS, ITEM_UNION_COLLECTION_FIELDS, mergeHistoryStreams, mergeItemDocuments, mergeJsonDocuments, mergeRelationshipEventStreams, type HistoryMergeResult, type HistoryMergeStrategy, type ItemDocumentMergeResult, type JsonDocumentMergeResult, type ItemMergeConflictDecision, type MergePreferredSide, type RelationshipStreamMergeResult, } from "./three-way.js";
 export { listMergeReceipts, markMergeReceiptReconciled, runMergeReceiptReport, summarizeMergeReceipt, type MergeDecisionReceipt, type MergeDecisionReceiptSummary, type MergeReceiptReport, } from "./receipts.js";
 export { MERGE_DRIVER_ARTIFACT_VALUES, runMergeDriver, type MergeDriverArtifact, type MergeDriverOptions, type MergeDriverResult, } from "./driver.js";
-export { auditMergeAttributeFence, auditMergeDriverConfiguration, buildMergeAttributePatterns, findGitWorkspaceRoot, PM_GITATTRIBUTES_END, PM_GITATTRIBUTES_START, refreshMergeAttributeFenceIfInstalled, runMergeInstall, type MergeFenceAuditResult, type MergeDriverConfigurationAuditResult, type MergeFenceRefreshOutcome, type MergeInstallOptions, type MergeInstallResult, } from "./install.js";
+export { auditMergeAttributeFence, auditMergeDriverConfiguration, buildMergeAttributePatterns, findGitWorkspaceRoot, PM_GITATTRIBUTES_END, PM_GITATTRIBUTES_START, refreshMergeAttributeFenceIfInstalled, resolveMergeInstallContext, runMergeInstall, type MergeFenceAuditResult, type MergeDriverConfigurationAuditResult, type MergeFenceRefreshOutcome, type MergeInstallOptions, type MergeInstallContextResolution, type MergeInstallResult, } from "./install.js";
 export { runMergeReconcile, type MergeReconcileOptions, type MergeReconcileResult, } from "./reconcile.js";

package/dist/sdk/merge/index.js

@@ -7,11 +7,11 @@
  * this module so packages and hosts can reuse the same merge behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="27725b9d-2a1d-54ae-8191-12ebace6ef6a")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="a8072065-092c-564b-a84f-cf687f795a92")}catch(e){}}();
 export { ITEM_LATEST_TIMESTAMP_FIELDS, ITEM_UNION_COLLECTION_FIELDS, mergeHistoryStreams, mergeItemDocuments, mergeJsonDocuments, mergeRelationshipEventStreams, } from "./three-way.js";
 export { listMergeReceipts, markMergeReceiptReconciled, runMergeReceiptReport, summarizeMergeReceipt, } from "./receipts.js";
 export { MERGE_DRIVER_ARTIFACT_VALUES, runMergeDriver, } from "./driver.js";
-export { auditMergeAttributeFence, auditMergeDriverConfiguration, buildMergeAttributePatterns, findGitWorkspaceRoot, PM_GITATTRIBUTES_END, PM_GITATTRIBUTES_START, refreshMergeAttributeFenceIfInstalled, runMergeInstall, } from "./install.js";
+export { auditMergeAttributeFence, auditMergeDriverConfiguration, buildMergeAttributePatterns, findGitWorkspaceRoot, PM_GITATTRIBUTES_END, PM_GITATTRIBUTES_START, refreshMergeAttributeFenceIfInstalled, resolveMergeInstallContext, runMergeInstall, } from "./install.js";
 export { runMergeReconcile, } from "./reconcile.js";
 //# sourceMappingURL=index.js.map
-//# debugId=27725b9d-2a1d-54ae-8191-12ebace6ef6a
+//# debugId=a8072065-092c-564b-a84f-cf687f795a92

package/dist/sdk/merge/install.d.ts

@@ -1,5 +1,6 @@
 import type { GlobalOptions } from "../../core/shared/command-types.js";
 import { readSettings } from "../../core/store/settings.js";
+import { resolveSourceContextWritePolicy } from "../environment/source-context.js";
 /** Opening marker for the pm-owned merge-driver `.gitattributes` block. */
 export declare const PM_GITATTRIBUTES_START = "# pm-cli:merge-drivers:start";
 /** Closing marker for the pm-owned merge-driver `.gitattributes` block. */
@@ -37,6 +38,26 @@ export interface MergeInstallResult {
     /** ISO 8601 timestamp recording when generated occurred. */
     generated_at: string;
 }
+/** Resolved tracker and workspace selection for one merge-install invocation. */
+export interface MergeInstallContextResolution {
+    /** Tracker root selected without performing filesystem writes. */
+    pm_root: string;
+    /** Starting path used to discover the enclosing Git workspace. */
+    workspace_start: string;
+    /** Whether complete inherited source coordinates were present. */
+    source_coordinates_available: boolean;
+    /** Whether inherited source coordinates were selected. */
+    source_context_selected: boolean;
+    /** Source-coordinate write policy active for the invocation. */
+    source_policy: ReturnType<typeof resolveSourceContextWritePolicy>;
+}
+/** Resolve explicit, inherited-source, and current-workspace precedence without I/O. */
+export declare function resolveMergeInstallContext(options: {
+    cwd: string;
+    explicitPath?: string;
+    dryRun: boolean;
+    environment: Readonly<Record<string, string | undefined>>;
+}): MergeInstallContextResolution;
 /** Result of auditing clone-local driver definitions behind a committed fence. */
 export interface MergeDriverConfigurationAuditResult {
     /** Whether every required driver definition exactly matches this installation. */