@unbrained/pm-cli 2026.8.30 → 2026.9.1

package/dist/sdk/history-repair.js

@@ -4,7 +4,7 @@
  * Implements the pm history repair 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]="04dbdc08-ad98-543f-96dc-fde635bae92e")}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]="151e5d26-d6f5-5fcf-84ab-ce89e2b7664e")}catch(e){}}();
 import { assertInitializedTracker } from "./environment/tracker-preflight.js";
 import { realpath } from "node:fs/promises";
 import path from "node:path";
@@ -12,7 +12,7 @@ import jsonPatch from "fast-json-patch";
 import { patchPathToChangedField } from "../core/history/history-diff.js";
 import { pathExists, readFileIfExists } from "../core/fs/fs-utils.js";
 import { executeHistoryRewrite, writeHistoryRawWithRollback, } from "../core/history/history-rewrite.js";
-import { historyEntriesToRaw, normalizeReplayPatchOps, reanchorHistoryEntries, replayHash, resolveHistoryRepairItemHashVersion, toReplayDocument, verifyHistoryChain, verifyHistoryChainWithVersion, } from "../core/history/replay.js";
+import { historyEntriesToRaw, normalizeReplayPatchOps, reanchorHistoryEntries, replayHashVerificationCandidates, resolveHistoryRepairItemHashVersion, toReplayDocument, verifyHistoryChain, verifyHistoryChainWithVersion, } from "../core/history/replay.js";
 import { scanHistoryDrift } from "../core/history/drift-scan.js";
 import { invalidateHistoryDriftCache } from "../core/history/drift-cache.js";
 import { readHistoryEntries } from "../core/history/read.js";
@@ -287,11 +287,11 @@ async function loadHistoryRepairItemReplay(subject, settings, historyEntries, it
         };
     }
     const currentItemReplay = toReplayDocument(loadedItem.document);
-    const lastOriginalAfterHash = historyEntries[historyEntries.length - 1]?.after_hash;
+    const lastOriginalAfterHash = historyEntries[historyEntries.length - 1].after_hash;
     return {
         currentItemReplay,
         currentItemPath,
-        matchedChainBefore: replayHash(currentItemReplay, itemHashVersion) === lastOriginalAfterHash,
+        matchedChainBefore: replayHashVerificationCandidates(currentItemReplay, itemHashVersion).includes(lastOriginalAfterHash),
         currentItemRawBeforeLock: loadedItem.raw,
         loadedItem,
     };
@@ -312,6 +312,10 @@ function buildHistoryRepairEntries(params) {
     const afterReplay = params.reconcileNeeded && params.currentItemReplay
         ? params.currentItemReplay
         : params.finalReplay;
+    const beforeHashes = replayHashVerificationCandidates(params.finalReplay, params.itemHashVersion);
+    const previousAfterHash = params.reanchorEntries[params.reanchorEntries.length - 1].after_hash;
+    const semanticIndex = beforeHashes.indexOf(previousAfterHash);
+    const afterHashes = replayHashVerificationCandidates(afterReplay, params.itemHashVersion);
     rewrittenEntries.push({
         ts: nowIso(),
         author: params.author,
@@ -319,8 +323,8 @@ function buildHistoryRepairEntries(params) {
         patch: params.reconcileNeeded && params.currentItemReplay
             ? jsonPatch.compare(params.finalReplay, params.currentItemReplay)
             : [],
-        before_hash: replayHash(params.finalReplay, params.itemHashVersion),
-        after_hash: replayHash(afterReplay, params.itemHashVersion),
+        before_hash: beforeHashes[semanticIndex],
+        after_hash: afterHashes[semanticIndex],
         message: params.message,
         ...(params.explicitItemHashVersion
             ? { item_hash_version: params.itemHashVersion }
@@ -403,9 +407,12 @@ export async function runHistoryRepair(id, options, global) {
     const reanchor = reanchorHistoryEntries(provenanceNormalization.entries, itemHashVersion);
     const itemReplayContext = await loadHistoryRepairItemReplay(subject, settings, historyEntries, itemHashVersion);
     const finalReplay = reanchor.finalDocument;
-    const reconcileNeeded = itemReplayContext.currentItemReplay !== null &&
-        replayHash(finalReplay, itemHashVersion) !==
-            replayHash(itemReplayContext.currentItemReplay, itemHashVersion);
+    const finalReplayHashes = replayHashVerificationCandidates(finalReplay, itemHashVersion);
+    let reconcileNeeded = false;
+    if (itemReplayContext.currentItemReplay !== null) {
+        const currentItemReplayHashes = replayHashVerificationCandidates(itemReplayContext.currentItemReplay, itemHashVersion);
+        reconcileNeeded = !finalReplayHashes.some((hash, hashIndex) => hash === currentItemReplayHashes[hashIndex]);
+    }
     // GH-603: reconciling toward the on-disk item can silently overwrite the
     // replayed effect of other authors' events (classic after a lossy merge).
     // Surface exactly what is being discarded before any write happens.
@@ -591,4 +598,4 @@ export async function runHistoryRepairAll(options, global) {
     };
 }
 //# sourceMappingURL=history-repair.js.map
-//# debugId=04dbdc08-ad98-543f-96dc-fde635bae92e
+//# debugId=151e5d26-d6f5-5fcf-84ab-ce89e2b7664e

package/dist/sdk/index.d.ts

@@ -170,7 +170,7 @@ export { readImprovementLedger, recordImprovementObservation, type ImprovementDi
 export { evaluateProvenanceCoverage, projectFleetAttributionAnalytics, projectProvenanceCoverageAnalytics, readHistoryAnalyticsWindow, runFleetAttributionAnalytics, runProvenanceCoverageAnalytics, type FleetAttributionAnalytics, type FleetAttributionDimension, type FleetAttributionRow, type HistoryAnalyticsWindowOptions, type HistoryAnalyticsWindowReceipt, type HistoryAnalyticsEvent, type HistoryAnalyticsWindow, type ProvenanceCoverageAnalytics, } from "./history-analytics.js";
 export { DEFAULT_EVAL_QUERIES_RELATIVE_PATH, EVAL_QUERY_SET_CONTRACT, EVAL_QUERY_SET_EXAMPLE, EVAL_QUERY_SET_SCHEMA_ID, parseEvalQuerySet, runEval, type EvalOptions, type EvalQueryReport, type EvalResult, } from "./eval.js";
 export { runTelemetry, TELEMETRY_SUBCOMMANDS, type TelemetryCommandOptions, type TelemetryFlushResult, type TelemetryStatusSummary, type TelemetrySubcommand, } from "./telemetry.js";
-export { classifyLinkedTestFailure, countFailureCategories, extractReferencedPmItemIdsFromCommand, resolveLinkedTestFailureExitCode, runLinkedTests, runTest, summarizeContextPreflight, type LinkedTestFailureCategory, type TestCommandOptions, type TestResult, type TestRunResult, } from "./test/execution.js";
+export { classifyLinkedTestCommandSafety, classifyLinkedTestFailure, countFailureCategories, extractReferencedPmItemIdsFromCommand, resolveLinkedTestFailureExitCode, runLinkedTests, runTest, summarizeContextPreflight, type LinkedTestFailureCategory, type LinkedTestCommandSafetyClassification, type TestCommandOptions, type TestResult, type TestRunResult, } from "./test/execution.js";
 export { TEST_RUN_MEASUREMENT_LIMIT, diffTestRunMeasurements, parseTestRunMeasurements, queryTestRunMeasurementsBelow, type TestRunMeasurementDiff, } from "./test/measurements.js";
 export { runTestAll, type TestAllCommandOptions, type TestAllItemResult, type TestAllResult, } from "./test/batch.js";
 export { LINKED_TEST_ENV_NAME_PATTERN, LINKED_TEST_PM_CONTEXT_MODE_VALUES, LINKED_TEST_WORKSPACE_CONTEXT_MODE_VALUES, LINKED_TEST_PROTECTED_ENV_KEYS, parseLinkedTestAssertionEqualsMap, parseLinkedTestAssertionGteMap, parseLinkedTestBoolean, parseLinkedTestContextMode, parseLinkedTestEnvClear, parseLinkedTestEnvSet, parseLinkedTestJsonEntries, parseLinkedTestMinLines, parseLinkedTestRegexList, parseLinkedTestStringList, parseLinkedTestWorkspaceContextMode, type LinkedTestPmContextMode, type LinkedTestWorkspaceContextMode, } from "./test/parsers.js";
@@ -182,6 +182,7 @@ export { describeProfileComposition, describeProjectProfile, type ProjectProfile
 export { lintProjectProfile, PROFILE_LINT_CODES, PROFILE_LINT_DIMENSIONS, type ProfileLintCode, type ProfileLintDimension, type ProfileLintSeverity, type ProjectProfileLintFinding, type ProjectProfileLintReport, } from "../core/profile/profile-lint.js";
 export * from "./authoring.js";
 export * from "./governance.js";
+export * from "./mcp/discovery.js";
 export * from "./query.js";
 export * from "./testing.js";
 export type { GlobalOptions } from "../core/shared/command-types.js";

package/dist/sdk/index.js

@@ -4,7 +4,7 @@
  * Defines public SDK APIs and package-author helpers for Index.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="ea1845ab-34f5-5a1c-ad49-ac81495c1840")}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]="8a1a02de-32cb-5714-b950-6041ae8ce229")}catch(e){}}();
 export { PM_COMMAND_CAPABILITY_CONTRACTS, PM_COMMAND_VISIBILITY_CONTRACTS, PM_MCP_PROMPT_CONTRACTS, PM_MCP_RESOURCE_CONTRACTS, PM_MCP_TOOL_COMMAND_CONTRACTS, listPmCommandsForFamily, listPmCommandsForTier, listPmMcpToolsForProfile, renderPmCommandVisibilityMarkdown, resolvePmCommandCapabilityFamily, resolvePmCommandVisibilityTier, } from "./agent-capability-contracts.js";
 export * from "./mcp/protocol.js";
 export * from "./mcp/interactions.js";
@@ -161,7 +161,7 @@ export { readImprovementLedger, recordImprovementObservation, } from "./improvem
 export { evaluateProvenanceCoverage, projectFleetAttributionAnalytics, projectProvenanceCoverageAnalytics, readHistoryAnalyticsWindow, runFleetAttributionAnalytics, runProvenanceCoverageAnalytics, } from "./history-analytics.js";
 export { DEFAULT_EVAL_QUERIES_RELATIVE_PATH, EVAL_QUERY_SET_CONTRACT, EVAL_QUERY_SET_EXAMPLE, EVAL_QUERY_SET_SCHEMA_ID, parseEvalQuerySet, runEval, } from "./eval.js";
 export { runTelemetry, TELEMETRY_SUBCOMMANDS, } from "./telemetry.js";
-export { classifyLinkedTestFailure, countFailureCategories, extractReferencedPmItemIdsFromCommand, resolveLinkedTestFailureExitCode, runLinkedTests, runTest, summarizeContextPreflight, } from "./test/execution.js";
+export { classifyLinkedTestCommandSafety, classifyLinkedTestFailure, countFailureCategories, extractReferencedPmItemIdsFromCommand, resolveLinkedTestFailureExitCode, runLinkedTests, runTest, summarizeContextPreflight, } from "./test/execution.js";
 export { TEST_RUN_MEASUREMENT_LIMIT, diffTestRunMeasurements, parseTestRunMeasurements, queryTestRunMeasurementsBelow, } from "./test/measurements.js";
 export { runTestAll, } from "./test/batch.js";
 export { LINKED_TEST_ENV_NAME_PATTERN, LINKED_TEST_PM_CONTEXT_MODE_VALUES, LINKED_TEST_WORKSPACE_CONTEXT_MODE_VALUES, LINKED_TEST_PROTECTED_ENV_KEYS, parseLinkedTestAssertionEqualsMap, parseLinkedTestAssertionGteMap, parseLinkedTestBoolean, parseLinkedTestContextMode, parseLinkedTestEnvClear, parseLinkedTestEnvSet, parseLinkedTestJsonEntries, parseLinkedTestMinLines, parseLinkedTestRegexList, parseLinkedTestStringList, parseLinkedTestWorkspaceContextMode, } from "./test/parsers.js";
@@ -173,7 +173,8 @@ export { describeProfileComposition, describeProjectProfile, } from "../core/pro
 export { lintProjectProfile, PROFILE_LINT_CODES, PROFILE_LINT_DIMENSIONS, } from "../core/profile/profile-lint.js";
 export * from "./authoring.js";
 export * from "./governance.js";
+export * from "./mcp/discovery.js";
 export * from "./query.js";
 export * from "./testing.js";
 //# sourceMappingURL=index.js.map
-//# debugId=ea1845ab-34f5-5a1c-ad49-ac81495c1840
+//# debugId=8a1a02de-32cb-5714-b950-6041ae8ce229

package/dist/sdk/init-agent-guidance.js

@@ -4,7 +4,7 @@
  * Implements the pm init agent guidance 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]="e404796d-439b-5f4c-9330-5b12ff41d7b2")}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]="542cd5ac-e4a7-51fe-8521-d0bacd9e6a07")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import readline from "node:readline/promises";
@@ -96,10 +96,10 @@ function buildAgentGuidanceBlock(lineEnding, projectTestCommand = "<your project
         AGENT_GUIDANCE_START_MARKER,
         "## pm Workflow (Agent Quickstart)",
         "",
-        '- Orient before mutate: `pm context --limit 10`, `pm search "<keywords>" --limit 10`, `pm list --status open --limit 20`.',
+        '- Cold start with the measured canonical orientation: `pm context --limit 10 --for orient`; before item mutation, also run `pm search "<keywords>" --limit 10`, `pm list --status open --limit 20`, and `pm list --status in_progress --limit 20`.',
         "- Claim and execute: `pm claim <id>` then `pm update <id> --status in_progress`.",
         `- Link evidence while coding: \`pm files <id> --add ...\`, \`pm docs <id> --add ...\`, \`pm test <id> --add command="${projectTestCommand}"\`.`,
-        '- Verify and close: `pm test <id> --run --progress`, `pm close <id> "<evidence>" --validate-close warn`, `pm release <id>`.',
+        '- Verify and close: `pm test <id> --run --progress`, then atomically record closure evidence with `pm close <id> "<reason>" --resolution "<what changed>" --expected "<expected outcome>" --actual "<observed outcome>" --validate-close warn`, then `pm release <id>`.',
         "- Author identity is automatic for supported agent harnesses; use `--author` only for an explicit override.",
         "",
         AGENT_GUIDANCE_END_MARKER,
@@ -494,4 +494,4 @@ export async function runInitAgentGuidance(options) {
     };
 }
 //# sourceMappingURL=init-agent-guidance.js.map
-//# debugId=e404796d-439b-5f4c-9330-5b12ff41d7b2
+//# debugId=542cd5ac-e4a7-51fe-8521-d0bacd9e6a07

package/dist/sdk/lifecycle/update.js

@@ -4,7 +4,7 @@
  * Implements the pm update 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]="6865ca88-7ca1-52fd-86fb-2a3439abeafa")}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]="78f8b369-1802-555d-a8cc-0147c0d8fb08")}catch(e){}}();
 import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import { resolveMutationStdinTokenFields } from "../../core/item/parse.js";
 import { COMMON_MUTATION_COMMAND_OPTION_KEYS, canonicalizeCommandOptionKey, commandOptionFlagLabel, resolveItemTypeRegistry, resolveCommandOptionPolicyState, resolveTypeDefinition, resolveTypeName, validateTypeOptions, normalizeItemId, toItemRecord, buildInvalidTypeError, assertParentReferenceIsNotSelf, normalizeParentReferenceValue, validateMissingParentReference, validateSprintOrReleaseValue, applyAcceptanceCriteriaMutations, applyTagRemovals, assertNoUnknownCsvKeys, looksLikeGenericKeyValueEntry, mergeAdditiveTags, parseCsvKv, parseOptionalNonNegativeInteger, parseOptionalNumber, parseTags, shouldResolveMutationStdinTokens, transferMutationStdinTokenPolicy, splitAcceptanceCriteria, resolvePriority, normalizeStatusInput, isTerminalStatus, collectRuntimeUpdateFieldValues, resolveItemTypesFilePath, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, describeAllowedTransitions, evaluateTransition, resolveTypeWorkflows, EXIT_CODE, PmCliError, stableValueEquals, resolveIsoOrRelative, getActiveExtensionRegistrations, collectRegisteredItemFieldNames, applyRegisteredItemFieldDefaultsAndValidation, parseRegisteredItemFieldAssignments, buildItemNotFoundError, listAllItemMetadataLight, locateItem, readLocatedItem, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
@@ -1273,6 +1273,25 @@ function applySimpleItemMutations(document, options, statusRegistry, changedFiel
     return (normalizeStatusInput(document.metadata.status, statusRegistry) ??
         document.metadata.status);
 }
+const TERMINAL_EVIDENCE_METADATA_KEYS = [
+    "closed_at",
+    "completed_at",
+    "close_reason",
+    "resolution",
+    "expected_result",
+    "actual_result",
+    "fixed_version",
+];
+/** Remove stale terminal evidence when work returns to an active lifecycle. */
+function clearTerminalEvidence(metadata, changedFields) {
+    for (const key of TERMINAL_EVIDENCE_METADATA_KEYS) {
+        if (metadata[key] === undefined) {
+            continue;
+        }
+        delete metadata[key];
+        changedFields.push(key);
+    }
+}
 function applyStatusMutation(document, context, statusInput, previousStatusNormalized, changedFields) {
     const status = parseStatus(statusInput, context.statusRegistry);
     document.metadata.status = status;
@@ -1286,14 +1305,8 @@ function applyStatusMutation(document, context, statusInput, previousStatusNorma
         return;
     }
     if (!isTerminalStatus(status, context.statusRegistry) &&
-        isTerminalStatus(previousStatusNormalized, context.statusRegistry) &&
-        document.metadata.closed_at !== undefined) {
-        delete document.metadata.closed_at;
-        changedFields.push("closed_at");
-        if (document.metadata.completed_at !== undefined) {
-            delete document.metadata.completed_at;
-            changedFields.push("completed_at");
-        }
+        isTerminalStatus(previousStatusNormalized, context.statusRegistry)) {
+        clearTerminalEvidence(document.metadata, changedFields);
     }
 }
 function applyStatusAndCompletionMutations(document, context, previousStatusNormalized, changedFields) {
@@ -2121,4 +2134,4 @@ export const _testOnlyUpdateCommand = {
     resolveRuntimeUnsetDefinition: (token, registry) => resolveRuntimeUnsetFieldDefinition(token, "update", registry),
 };
 //# sourceMappingURL=update.js.map
-//# debugId=6865ca88-7ca1-52fd-86fb-2a3439abeafa
+//# debugId=78f8b369-1802-555d-a8cc-0147c0d8fb08

package/dist/sdk/mcp/discovery.d.ts

@@ -0,0 +1,152 @@
+import { type PmCommandCapabilityFamily, type PmCommandVisibilityTier, type PmMcpToolProfile } from "../agent-capability-contracts.js";
+/** Namespaced MCP extension that opts a client into progressive tool discovery. */
+export declare const PM_MCP_PROGRESSIVE_DISCOVERY_EXTENSION = "dev.unbrained.pm/progressive-tool-discovery";
+/** Versioned server capability advertised for progressive tool discovery. */
+export declare const PM_MCP_PROGRESSIVE_DISCOVERY_SERVER_CAPABILITY: Readonly<{
+    version: 1;
+    discoveryTool: "pm_discover";
+    canonicalResult: "structuredContent.result";
+    compatibilityText: "pointer";
+}>;
+/** Small stable tool catalog returned to clients that negotiate the extension. */
+export declare const PM_MCP_ENTRY_TOOL_NAMES: readonly string[];
+/** Ranking signals composed by the public discovery contract. */
+export type PmToolDiscoverySignalName = "lexical" | "semantic" | "graph" | "permission" | "freshness" | "usage";
+/** Optional host-owned signals supplied for one tool. */
+export interface PmToolDiscoverySignalInput {
+    /** Semantic relevance normalized to the inclusive range zero through one. */
+    semantic?: number;
+    /** Graph proximity normalized to the inclusive range zero through one. */
+    graph?: number;
+    /** Definition freshness normalized to the inclusive range zero through one. */
+    freshness?: number;
+    /** Historical selection usefulness normalized to the inclusive range zero through one. */
+    usage?: number;
+}
+/** One tool definition accepted by the SDK discovery engine. */
+export interface PmToolDiscoveryCandidate {
+    /** Stable callable tool name. */
+    name: string;
+    /** Agent-facing tool description. */
+    description: string;
+    /** JSON Schema supplied when callers request schema expansion. */
+    inputSchema: Record<string, unknown>;
+    /** Whether the current caller is authorized to invoke the tool. */
+    authorized?: boolean;
+    /** Optional host-owned ranking signals. */
+    signals?: PmToolDiscoverySignalInput;
+}
+/** Options controlling one progressive discovery page. */
+export interface PmToolDiscoveryOptions {
+    /** Free-text capability intent. Empty text lists by deterministic policy order. */
+    query?: string;
+    /** Restrict results to one stable capability family. */
+    family?: PmCommandCapabilityFamily;
+    /** Restrict results to tools visible at or below this tier. */
+    tier?: Exclude<PmCommandVisibilityTier, "internal">;
+    /** Maximum result rows, from one through one hundred. */
+    limit?: number;
+    /** Opaque continuation cursor from an equivalent discovery request. */
+    cursor?: string;
+    /** Include complete input schemas instead of the default compact projection. */
+    includeSchema?: boolean;
+    /** Estimated-token ceiling, or unbounded for the complete selected page. */
+    outputBudget?: number | "unbounded";
+    /** MCP profile that produced the authorized candidate catalog. */
+    profile?: PmMcpToolProfile;
+    /** Host-owned HMAC key of at least 32 bytes for restart-stable cursors. */
+    cursorIntegrityKey?: Uint8Array;
+}
+/** Applied score for one signal with explicit provenance. */
+export interface PmToolDiscoveryAppliedSignal {
+    /** Normalized signal value. */
+    value: number;
+    /** Public policy weight. */
+    weight: number;
+    /** Whether the signal was computed or supplied rather than defaulted. */
+    available: boolean;
+    /** Transparent source of the normalized value. */
+    source: "computed" | "host" | "authorization" | "unavailable";
+}
+/** One ranked discovery result. */
+export interface PmToolDiscoveryResultRow {
+    /** Stable callable tool name. */
+    name: string;
+    /** Agent-facing description. */
+    description: string;
+    /** Canonical CLI command backing the tool. */
+    command: string;
+    /** Minimum visibility tier inherited from the command contract. */
+    tier: PmCommandVisibilityTier;
+    /** Stable capability family inherited from the command contract. */
+    family: PmCommandCapabilityFamily;
+    /** Weighted aggregate score used for ordering. */
+    score: number;
+    /** Complete per-signal score explanation. */
+    signals: Readonly<Record<PmToolDiscoverySignalName, PmToolDiscoveryAppliedSignal>>;
+    /** Complete JSON Schema when explicitly requested. */
+    input_schema?: Record<string, unknown>;
+}
+/** Explicit receipt for information omitted from a discovery page. */
+export interface PmToolDiscoveryOmissionReceipt {
+    /** Whether any result rows or schemas were omitted. */
+    has_omissions: boolean;
+    /** Stable omitted field groups. */
+    omitted: Array<{
+        name: "input_schema" | "tools";
+        reason: "compact_projection" | "limit" | "token_budget";
+        restore_with: string;
+    }>;
+}
+/** Deterministic progressive tool discovery response. */
+export interface PmToolDiscoveryResult {
+    /** Stable result discriminator for model and host routing. */
+    result_type: "pm_tool_discovery";
+    /** Public contract revision. */
+    contract_version: 1;
+    /** Normalized query used by ranking and cursor binding. */
+    query: string;
+    /** MCP profile that produced the candidate catalog. */
+    profile: PmMcpToolProfile;
+    /** Ranked page of authorized tools. */
+    tools: PmToolDiscoveryResultRow[];
+    /** Total authorized rows after filters and before pagination. */
+    total: number;
+    /** Rows returned on this page. */
+    returned: number;
+    /** Whether a later ranked row remains. */
+    has_more: boolean;
+    /** Opaque continuation cursor bound to query, filters, and catalog. */
+    next_cursor?: string;
+    /** Exact estimated serialized result cost. */
+    token_cost: {
+        estimated_tokens: number;
+        budget: number | "unbounded";
+        within_budget: boolean;
+    };
+    /** Public ranking formula and weights. */
+    ranking_policy: {
+        version: 1;
+        formula: "weighted_sum_then_name";
+        weights: Readonly<Record<PmToolDiscoverySignalName, number>>;
+    };
+    /** Cache identity and invalidation contract for deterministic pages. */
+    cache: {
+        key: string;
+        ttl_ms: number;
+        scope: "private";
+        invalidates_on: readonly string[];
+    };
+    /** Explicit recovery for compacted fields and rows. */
+    omission_receipt: PmToolDiscoveryOmissionReceipt;
+}
+/** Parse untrusted adapter input without discarding malformed discovery values. */
+export declare function parsePmToolDiscoveryOptions(input: Record<string, unknown>): PmToolDiscoveryOptions;
+/**
+ * Rank and page an authorized MCP tool catalog under an explicit token budget.
+ *
+ * Cursors fail closed when the query, filters, schemas, authorization-filtered
+ * catalog, or ranking inputs change. Host signals override documented local
+ * fallbacks without changing the public formula or hiding signal provenance.
+ */
+export declare function discoverPmTools(candidates: readonly PmToolDiscoveryCandidate[], options?: PmToolDiscoveryOptions): PmToolDiscoveryResult;