@unbrained/pm-cli 2026.8.19 → 2026.8.21

package/dist/core/store/tracker-preflight.js

@@ -0,0 +1,142 @@
+/**
+ * @module core/store/tracker-preflight
+ *
+ * Owns the filesystem preflight shared by tracker-reading SDK primitives.
+ */
+
+!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]="8b0efe32-43f5-51ed-b1d5-5c26a3ae5bf0")}catch(e){}}();
+import fs from "node:fs/promises";
+import path from "node:path";
+import { EXIT_CODE } from "../shared/constants.js";
+import { PmCliError, } from "../shared/errors.js";
+import { pathExists } from "../fs/fs-utils.js";
+import { getSettingsPath } from "./paths.js";
+function isErrno(error, code) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === code);
+}
+/** Build the non-interactive, tokenized retry that initializes a selected tracker root. */
+export function buildTrackerInitializationRecovery(pmRoot) {
+    const suggestedRetryArguments = [
+        "--pm-path",
+        pmRoot,
+        "init",
+        "--defaults",
+        "--agent-guidance",
+        "skip",
+    ];
+    return {
+        suggested_retry: `pm ${suggestedRetryArguments
+            .map((argument) => `'${argument.replaceAll("'", `'"'"'`)}'`)
+            .join(" ")}`,
+        suggested_retry_args: suggestedRetryArguments,
+    };
+}
+function trackerRootNotDirectoryError(pmRoot) {
+    return new PmCliError(`Tracker root is not a directory at ${pmRoot}.`, EXIT_CODE.USAGE, {
+        code: "tracker_root_not_directory",
+        reason: "not_a_directory",
+        resolved_path: pmRoot,
+        nextSteps: [
+            "Pass a tracker directory, usually <workspace>/.agents/pm, rather than a file path.",
+        ],
+    });
+}
+function trackerRootUnreadableError(pmRoot) {
+    return new PmCliError(`Tracker root is not readable at ${pmRoot}.`, EXIT_CODE.GENERIC_FAILURE, {
+        code: "tracker_root_unreadable",
+        reason: "unreadable",
+        resolved_path: pmRoot,
+        nextSteps: [
+            "Grant read and directory-search permission to the tracker root, then retry.",
+        ],
+    });
+}
+async function assertMissingRootAncestors(pmRoot) {
+    const resolvedRoot = path.resolve(pmRoot);
+    const filesystemRoot = path.parse(resolvedRoot).root;
+    let ancestor = path.dirname(resolvedRoot);
+    while (ancestor !== filesystemRoot) {
+        let ancestorStats;
+        try {
+            ancestorStats = await fs.stat(ancestor);
+        }
+        catch (error) {
+            if (isErrno(error, "ENOTDIR")) {
+                throw trackerRootNotDirectoryError(pmRoot);
+            }
+            if (!isErrno(error, "ENOENT")) {
+                throw error;
+            }
+            ancestor = path.dirname(ancestor);
+            continue;
+        }
+        if (!ancestorStats.isDirectory()) {
+            throw trackerRootNotDirectoryError(pmRoot);
+        }
+        return;
+    }
+}
+/** Require a tracker root to be a readable directory without requiring initialized settings. */
+export async function assertReadableTrackerRoot(pmRoot) {
+    let stats;
+    try {
+        stats = await fs.stat(pmRoot);
+    }
+    catch (error) {
+        if (isErrno(error, "ENOENT")) {
+            await assertMissingRootAncestors(pmRoot);
+            throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Tracker root does not exist. Run pm init first.`, EXIT_CODE.NOT_FOUND, {
+                code: "tracker_root_missing",
+                reason: "missing",
+                resolved_path: pmRoot,
+                nextSteps: [
+                    "Confirm the tracker root path or initialize it with the emitted retry.",
+                ],
+                recovery: buildTrackerInitializationRecovery(pmRoot),
+            });
+        }
+        if (isErrno(error, "ENOTDIR")) {
+            throw trackerRootNotDirectoryError(pmRoot);
+        }
+        if (isErrno(error, "EACCES") || isErrno(error, "EPERM")) {
+            throw trackerRootUnreadableError(pmRoot);
+        }
+        throw error;
+    }
+    if (!stats.isDirectory()) {
+        throw trackerRootNotDirectoryError(pmRoot);
+    }
+    if (process.platform !== "win32" &&
+        ((stats.mode & 0o444) === 0 || (stats.mode & 0o111) === 0)) {
+        throw trackerRootUnreadableError(pmRoot);
+    }
+    try {
+        const directory = await fs.opendir(pmRoot);
+        await directory.close();
+    }
+    catch (error) {
+        if (isErrno(error, "EACCES") || isErrno(error, "EPERM")) {
+            throw trackerRootUnreadableError(pmRoot);
+        }
+        throw error;
+    }
+}
+/** Require the selected tracker root and its settings marker before an SDK command reads or mutates project state. */
+export async function assertInitializedTracker(pmRoot) {
+    await assertReadableTrackerRoot(pmRoot);
+    if (await pathExists(getSettingsPath(pmRoot))) {
+        return;
+    }
+    throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND, {
+        code: "tracker_not_initialized",
+        reason: "settings_missing",
+        resolved_path: pmRoot,
+        nextSteps: ["Initialize the selected tracker root with the emitted retry."],
+        recovery: buildTrackerInitializationRecovery(pmRoot),
+    });
+}
+//# sourceMappingURL=tracker-preflight.js.map
+//# debugId=8b0efe32-43f5-51ed-b1d5-5c26a3ae5bf0

package/dist/sdk/agent/closed-domain-contracts.d.ts

@@ -0,0 +1,25 @@
+/** A closed-domain refusal that can be executed and recovered automatically. */
+export interface PmClosedDomainContract {
+    /** Stable assurance identity. */
+    probe_id: string;
+    /** Public command accepting the constrained flag. */
+    command: string;
+    /** Constrained option spelling. */
+    flag: string;
+    /** Invalid token used to prove the refusal path. */
+    rejected_value: string;
+    /** Exact argv that must refuse the invalid token. */
+    refusal_args: readonly string[];
+    /** Complete stable core domain accepted by the command. */
+    allowed_values: readonly string[];
+    /** Exact argv expected in the refusal's executable recovery. */
+    suggested_retry_args: readonly string[];
+    /** Stable machine-readable error code that owns the refusal. */
+    error_code: "projection_options_mutually_exclusive" | "unknown_context_intent" | "unknown_field_projection";
+    /** Whether a complete accepted-value domain is required in the refusal. */
+    allowed_values_required?: boolean;
+}
+/** Return the complete stable core refusal corpus shared by every public surface. */
+export declare function listCoreClosedDomainContracts(): PmClosedDomainContract[];
+/** Render a compact but complete core-domain description for command help. */
+export declare function renderPmClosedDomainHelp(command: string, flag: "--fields" | "--for"): string;

package/dist/sdk/agent/closed-domain-contracts.js

@@ -0,0 +1,140 @@
+/**
+ * @module sdk/agent/closed-domain-contracts
+ *
+ * Declares executable closed-domain refusals once for SDK consumers, CLI help,
+ * and repository assurance. Runtime schema fields can extend field domains
+ * without changing the stable core corpus.
+ */
+
+!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]="35d4f3d7-7ec2-5a8b-bd96-f7e73c658737")}catch(e){}}();
+import { PM_CONTEXT_INTENT_CONTRACTS } from "../context-intent-contracts.js";
+import { LIST_COMMAND_DEFAULT_PROJECTIONS, listGetProjectionFields, listListProjectionFields, listSearchProjectionFields, } from "../query/projection-contracts.js";
+const REJECTED_INTENT = "not-a-declared-intent";
+const REJECTED_FIELD = "not-a-declared-field";
+/** Return the complete stable core refusal corpus shared by every public surface. */
+export function listCoreClosedDomainContracts() {
+    const positionalArguments = {
+        get: ["pm-domain"],
+        search: ["Domain query"],
+    };
+    const intentContracts = [
+        ...new Set(PM_CONTEXT_INTENT_CONTRACTS.map(({ command }) => command)),
+    ].map((command) => {
+        const commandContracts = PM_CONTEXT_INTENT_CONTRACTS.filter((candidate) => candidate.command === command);
+        const contract = commandContracts[0];
+        const positionals = positionalArguments[contract.command] ?? [];
+        return {
+            probe_id: `${contract.command}-invalid-intent`,
+            command: contract.command,
+            flag: "--for",
+            rejected_value: REJECTED_INTENT,
+            refusal_args: [
+                contract.command,
+                ...positionals,
+                "--for",
+                REJECTED_INTENT,
+            ],
+            allowed_values: commandContracts.map(({ intent }) => intent).sort(),
+            suggested_retry_args: [
+                contract.command,
+                ...positionals,
+                "--for",
+                contract.intent,
+            ],
+            error_code: "unknown_context_intent",
+        };
+    });
+    const listFields = listListProjectionFields();
+    const listFieldContracts = Object.keys(LIST_COMMAND_DEFAULT_PROJECTIONS).map((command) => ({
+        probe_id: `${command}-invalid-field`,
+        command,
+        flag: "--fields",
+        rejected_value: REJECTED_FIELD,
+        refusal_args: [command, "--fields", REJECTED_FIELD],
+        allowed_values: listFields,
+        suggested_retry_args: [
+            command,
+            "--fields",
+            "id,title,status",
+            "--limit",
+            "10",
+        ],
+        error_code: "unknown_field_projection",
+    }));
+    const contracts = [
+        ...intentContracts,
+        ...listFieldContracts,
+        {
+            probe_id: "get-invalid-field",
+            command: "get",
+            flag: "--fields",
+            rejected_value: REJECTED_FIELD,
+            refusal_args: ["get", "pm-domain", "--fields", REJECTED_FIELD],
+            allowed_values: listGetProjectionFields(),
+            suggested_retry_args: ["get", "pm-domain", "--fields", "id,title,status"],
+            error_code: "unknown_field_projection",
+        },
+        {
+            probe_id: "list-mutually-exclusive-projection",
+            command: "list",
+            flag: "--projection",
+            rejected_value: "--brief+--full",
+            refusal_args: ["list", "--brief", "--full"],
+            allowed_values: [],
+            suggested_retry_args: ["list", "--brief"],
+            error_code: "projection_options_mutually_exclusive",
+            allowed_values_required: false,
+        },
+        {
+            probe_id: "get-mutually-exclusive-projection",
+            command: "get",
+            flag: "--projection",
+            rejected_value: "--full+--fields",
+            refusal_args: ["get", "pm-domain", "--full", "--fields", "id"],
+            allowed_values: [],
+            suggested_retry_args: ["get", "pm-domain", "--full"],
+            error_code: "projection_options_mutually_exclusive",
+            allowed_values_required: false,
+        },
+        {
+            probe_id: "search-mutually-exclusive-projection",
+            command: "search",
+            flag: "--projection",
+            rejected_value: "--full+--fields",
+            refusal_args: ["search", "Domain query", "--full", "--fields", "id"],
+            allowed_values: [],
+            suggested_retry_args: ["search", "Domain query", "--full"],
+            error_code: "projection_options_mutually_exclusive",
+            allowed_values_required: false,
+        },
+        {
+            probe_id: "search-invalid-field",
+            command: "search",
+            flag: "--fields",
+            rejected_value: REJECTED_FIELD,
+            refusal_args: ["search", "Domain query", "--fields", REJECTED_FIELD],
+            allowed_values: listSearchProjectionFields(),
+            suggested_retry_args: [
+                "search",
+                "Domain query",
+                "--fields",
+                "id,title,status,score",
+            ],
+            error_code: "unknown_field_projection",
+        },
+    ];
+    return contracts.sort((left, right) => left.probe_id.localeCompare(right.probe_id));
+}
+/** Render a compact but complete core-domain description for command help. */
+export function renderPmClosedDomainHelp(command, flag) {
+    const contract = listCoreClosedDomainContracts().find((candidate) => candidate.command === command && candidate.flag === flag);
+    if (!contract)
+        return "No stable core values are declared.";
+    const canonicalValues = contract.allowed_values.filter((value) => !value.startsWith("item."));
+    const runtimeSuffix = flag === "--fields"
+        ? " item.<field> aliases and configured runtime metadata fields are also accepted."
+        : " Configured package and workspace intents may extend this domain.";
+    return `Allowed core values: ${canonicalValues.join("|")}.${runtimeSuffix}`;
+}
+//# sourceMappingURL=closed-domain-contracts.js.map
+//# debugId=35d4f3d7-7ec2-5a8b-bd96-f7e73c658737

package/dist/sdk/agent/refusal-closure.d.ts

@@ -10,15 +10,27 @@ export interface PmRefusalClosureObservation {
     rejected_value: string;
     /** Complete accepted domain emitted by the refusal. */
     allowed_values: readonly string[];
+    /** Stable error code emitted by the refusal. */
+    error_code?: string;
+    /** Contract-owned error code required for this refusal. */
+    expected_error_code?: string;
+    /** Contract-owned complete accepted domain. */
+    expected_allowed_values?: readonly string[];
+    /** Whether an accepted-value domain is required for this refusal class. */
+    allowed_values_required?: boolean;
     /** Exact command emitted for recovery. */
     suggested_retry: string;
+    /** Shell-free argv emitted for safe programmatic recovery. */
+    suggested_retry_args?: readonly string[];
+    /** Contract-owned argv required for deterministic recovery. */
+    expected_suggested_retry_args?: readonly string[];
     /** Whether executing the advertised retry succeeded. */
     retry_succeeded: boolean;
 }
 /** One missing or contradictory recovery primitive. */
 export interface PmRefusalClosureFinding {
     /** Stable finding code. */
-    code: "accepted_rejected_value" | "duplicate_probe" | "empty_corpus" | "missing_allowed_values" | "missing_suggested_retry" | "non_refusal_exit" | "retry_failed";
+    code: "accepted_rejected_value" | "duplicate_probe" | "error_code_mismatch" | "empty_corpus" | "incomplete_allowed_values" | "missing_allowed_values" | "missing_suggested_retry_args" | "missing_suggested_retry" | "non_refusal_exit" | "suggested_retry_args_mismatch" | "retry_failed";
     /** Stable corpus identifier. */
     probe_id: string;
     /** Actionable mismatch detail. */

package/dist/sdk/agent/refusal-closure.js

@@ -5,8 +5,48 @@
  * an agent to recover without another discovery round trip.
  */
 
-!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]="65cfaa41-6f53-5339-8b55-c1a4d3660c5d")}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]="0ec8c375-e58e-5ce4-b0aa-8a8a4dfa0778")}catch(e){}}();
 import { EXIT_CODE } from "../../core/shared/constants.js";
+/** Compare a refusal with its optional SDK-owned exact contract. */
+function listContractObservationFindings(observation) {
+    return [
+        observation.expected_error_code !== undefined &&
+            observation.error_code !== observation.expected_error_code
+            ? {
+                code: "error_code_mismatch",
+                probe_id: observation.probe_id,
+                detail: `Expected error code ${observation.expected_error_code}, received ${observation.error_code ?? "<missing>"}.`,
+            }
+            : undefined,
+        observation.expected_allowed_values !== undefined &&
+            JSON.stringify([...observation.allowed_values].sort()) !==
+                JSON.stringify([...observation.expected_allowed_values].sort())
+            ? {
+                code: "incomplete_allowed_values",
+                probe_id: observation.probe_id,
+                detail: "The refusal's accepted domain differs from the SDK-owned domain contract.",
+            }
+            : undefined,
+        observation.expected_suggested_retry_args !== undefined &&
+            (observation.suggested_retry_args?.length ?? 0) === 0
+            ? {
+                code: "missing_suggested_retry_args",
+                probe_id: observation.probe_id,
+                detail: "The refusal omitted shell-free suggested retry arguments.",
+            }
+            : undefined,
+        observation.expected_suggested_retry_args !== undefined &&
+            (observation.suggested_retry_args?.length ?? 0) > 0 &&
+            JSON.stringify(observation.suggested_retry_args) !==
+                JSON.stringify(observation.expected_suggested_retry_args)
+            ? {
+                code: "suggested_retry_args_mismatch",
+                probe_id: observation.probe_id,
+                detail: "The refusal's suggested retry arguments differ from the SDK-owned contract.",
+            }
+            : undefined,
+    ];
+}
 /** Return every closure defect contributed by one unique observation. */
 function listObservationFindings(observation) {
     return [
@@ -17,7 +57,8 @@ function listObservationFindings(observation) {
                 detail: `${observation.entrypoint} returned exit code ${observation.exit_code}; a structured usage refusal must return ${EXIT_CODE.USAGE}.`,
             }
             : undefined,
-        observation.allowed_values.length === 0
+        observation.allowed_values_required !== false &&
+            observation.allowed_values.length === 0
             ? {
                 code: "missing_allowed_values",
                 probe_id: observation.probe_id,
@@ -45,6 +86,7 @@ function listObservationFindings(observation) {
                 detail: "The advertised suggested retry did not succeed.",
             }
             : undefined,
+        ...listContractObservationFindings(observation),
     ];
 }
 /** Score structured closed-domain refusals and executable retries. */
@@ -89,4 +131,4 @@ export function scorePmRefusalClosure(observations) {
     };
 }
 //# sourceMappingURL=refusal-closure.js.map
-//# debugId=65cfaa41-6f53-5339-8b55-c1a4d3660c5d
+//# debugId=0ec8c375-e58e-5ce4-b0aa-8a8a4dfa0778

package/dist/sdk/agent/refusal-reachability.d.ts

@@ -139,6 +139,28 @@ export interface PmRecoveryReferenceReport {
     /** Stable, sorted conformance findings. */
     findings: PmRecoveryReferenceFinding[];
 }
+/** Per-kind runtime evidence; counts do not claim one observation per source location. */
+export interface PmRecoveryProducerRuntimeCoverage {
+    /** Typed recovery-reference kind. */
+    kind: PmRecoveryReferenceKind;
+    /** Literal source producers discovered for the kind. */
+    source_producers: number;
+    /** Distinct runtime values observed for the kind. */
+    runtime_values: number;
+}
+/** Unified per-kind source-census and runtime-value coverage receipt. */
+export interface PmRecoveryProducerRuntimeReport {
+    /** Whether every source-declared kind emitted at least one runtime value. */
+    ok: boolean;
+    /** Source producer denominator. */
+    source_producer_count: number;
+    /** Distinct runtime-value denominator. */
+    runtime_value_count: number;
+    /** Stable per-kind source and runtime coverage. */
+    coverage_by_kind: PmRecoveryProducerRuntimeCoverage[];
+    /** Kinds with source producers but no runtime evidence. */
+    missing_runtime_kinds: PmRecoveryReferenceKind[];
+}
 /** Census syntax-parsed structured-envelope producers without executing source code. */
 export declare function censusPmRecoveryReferenceProducers(sources: readonly PmRecoveryProducerSource[]): PmRecoveryProducerCensusReport;
 /** Derive typed obligations from every recognized recovery field in an emitted envelope. */
@@ -147,3 +169,7 @@ export declare function derivePmRecoveryReferenceObligations(probeId: string, en
 export declare function verifyPmRefusalReachability(catalog: readonly PmErrorCodeContract[], observations: readonly PmRefusalProbeObservation[]): PmRefusalReachabilityReport;
 /** Verify executable and declared-path proof for emitted recovery references. */
 export declare function verifyPmRecoveryReferences(obligations: readonly PmRecoveryReferenceObligation[], observations: readonly PmRecoveryReferenceObservation[]): PmRecoveryReferenceReport;
+/** Join source-census counts to distinct emitted runtime values by typed kind. */
+export declare function verifyPmRecoveryProducerRuntimeCoverage(census: PmRecoveryProducerCensusReport, obligations: readonly PmRecoveryReferenceObligation[]): PmRecoveryProducerRuntimeReport;
+/** Honest kind-level name for the compatibility implementation above. */
+export declare const verifyPmRecoveryKindRuntimeCoverage: typeof verifyPmRecoveryProducerRuntimeCoverage;

package/dist/sdk/agent/refusal-reachability.js

@@ -5,7 +5,7 @@
  * generated public error-code catalog.
  */
 
-!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]="7b488d32-9f92-5a80-965e-e2555cd49315")}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]="4f4e7daa-14aa-5dad-8a30-79a4d76159d4")}catch(e){}}();
 import * as nodeModule from "node:module";
 /** Recovery-reference kinds emitted by structured refusal envelopes. */
 export const PM_RECOVERY_REFERENCE_KINDS = [
@@ -566,5 +566,29 @@ export function verifyPmRecoveryReferences(obligations, observations) {
         findings,
     };
 }
+/** Join source-census counts to distinct emitted runtime values by typed kind. */
+export function verifyPmRecoveryProducerRuntimeCoverage(census, obligations) {
+    const runtimeValuesByKind = new Map(PM_RECOVERY_REFERENCE_KINDS.map((kind) => [kind, new Set()]));
+    for (const obligation of obligations) {
+        runtimeValuesByKind.get(obligation.kind).add(obligation.value);
+    }
+    const coverageByKind = PM_RECOVERY_REFERENCE_KINDS.map((kind) => ({
+        kind,
+        source_producers: census.producer_count_by_kind[kind],
+        runtime_values: runtimeValuesByKind.get(kind).size,
+    }));
+    const missingRuntimeKinds = coverageByKind
+        .filter(({ source_producers: sourceProducers, runtime_values: runtimeValues }) => sourceProducers > 0 && runtimeValues === 0)
+        .map(({ kind }) => kind);
+    return {
+        ok: census.ok && missingRuntimeKinds.length === 0,
+        source_producer_count: census.producer_count,
+        runtime_value_count: coverageByKind.reduce((total, { runtime_values: runtimeValues }) => total + runtimeValues, 0),
+        coverage_by_kind: coverageByKind,
+        missing_runtime_kinds: missingRuntimeKinds,
+    };
+}
+/** Honest kind-level name for the compatibility implementation above. */
+export const verifyPmRecoveryKindRuntimeCoverage = verifyPmRecoveryProducerRuntimeCoverage;
 //# sourceMappingURL=refusal-reachability.js.map
-//# debugId=7b488d32-9f92-5a80-965e-e2555cd49315
+//# debugId=4f4e7daa-14aa-5dad-8a30-79a4d76159d4

package/dist/sdk/agent/tracker-preflight-contracts.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @module sdk/agent/tracker-preflight-contracts
+ *
+ * Declares and scores executable recovery for tracker filesystem preflight failures.
+ */
+/** Filesystem states distinguished by the shared tracker preflight. */
+export type PmTrackerPreflightFailureKind = "missing_root" | "settings_missing" | "not_directory" | "unreadable_root";
+/** Recovery behavior that is safe for a tracker preflight failure. */
+export type PmTrackerPreflightRecoveryKind = "initialize" | "select_directory" | "repair_permissions";
+/** Static refusal and recovery obligation for one tracker filesystem state. */
+export interface PmTrackerPreflightRecoveryContract {
+    /** Stable probe identifier used by repository gates and evidence. */
+    probe_id: string;
+    /** Filesystem state created by the executable probe. */
+    failure_kind: PmTrackerPreflightFailureKind;
+    /** Stable structured error code required from CLI and SDK transports. */
+    expected_error_code: string;
+    /** Process exit code required from the CLI transport. */
+    expected_exit_code: 1 | 2 | 3;
+    /** Safe recovery behavior for this filesystem state. */
+    recovery_kind: PmTrackerPreflightRecoveryKind;
+}
+/** Runtime evidence captured from one executable tracker preflight probe. */
+export interface PmTrackerPreflightRecoveryObservation {
+    /** Stable probe identifier from the corresponding contract. */
+    probe_id: string;
+    /** Structured error code emitted by the refusal. */
+    error_code: string;
+    /** Process exit code emitted by the refusal. */
+    exit_code: number;
+    /** Recovery behavior exercised by the probe driver. */
+    recovery_kind: PmTrackerPreflightRecoveryKind;
+    /** Tokenized retry emitted by the refusal, or an empty list when no deterministic retry is safe. */
+    suggested_retry_args: string[];
+    /** Whether the emitted retry or safe alternate-root retry executed successfully. */
+    retry_succeeded: boolean;
+    /** Whether a file-path refusal incorrectly recommended tracker initialization. */
+    unsafe_init_recommended: boolean;
+}
+/** Actionable failure emitted by the tracker preflight closure scorer. */
+export interface PmTrackerPreflightRecoveryFinding {
+    /** Stable finding code for automation and ratchets. */
+    code: "missing_probe" | "error_code_mismatch" | "exit_code_mismatch" | "recovery_kind_mismatch" | "missing_init_recovery" | "unsafe_init_recovery" | "retry_failed";
+    /** Probe that failed its recovery obligation. */
+    probe_id: string;
+    /** Human-readable explanation of the failed obligation. */
+    detail: string;
+}
+/** Aggregate executable-closure report for the tracker preflight corpus. */
+export interface PmTrackerPreflightRecoveryReport {
+    /** Whether every declared probe met its refusal and recovery contract. */
+    ok: boolean;
+    /** Number of declared tracker preflight probes. */
+    probe_count: number;
+    /** Number of probes with no findings. */
+    closed_probe_count: number;
+    /** Deterministically ordered failed obligations. */
+    findings: PmTrackerPreflightRecoveryFinding[];
+}
+/** Return defensive copies of every core tracker preflight recovery contract. */
+export declare function listTrackerPreflightRecoveryContracts(): PmTrackerPreflightRecoveryContract[];
+/** Score runtime observations against the complete tracker preflight recovery corpus. */
+export declare function scoreTrackerPreflightRecoveryClosure(observations: readonly PmTrackerPreflightRecoveryObservation[]): PmTrackerPreflightRecoveryReport;