@unbrained/pm-cli 2026.8.20 → 2026.8.21

package/dist/core/shared/errors.js

@@ -1,6 +1,6 @@
 /** Implements the exported pm cli error runtime abstraction for core/shared/errors.ts. */
 
-!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]="a19ff5c0-2c4d-5576-a551-cab35276fdc3")}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]="e8873345-5824-5832-9fa3-79719ddc6b58")}catch(e){}}();
 export class PmCliError extends Error {
     /** Value that configures or reports exit code for this contract. */
     exitCode;
@@ -18,4 +18,4 @@ export class PmCliError extends Error {
     }
 }
 //# sourceMappingURL=errors.js.map
-//# debugId=a19ff5c0-2c4d-5576-a551-cab35276fdc3
+//# debugId=e8873345-5824-5832-9fa3-79719ddc6b58

package/dist/core/store/item-store.js

@@ -4,7 +4,7 @@
  * Reads and writes tracker storage with format-aware helpers for Item Store.
  */
 
-!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]="b6db139b-7646-58f9-96af-d3c65bf7ddf6")}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]="f49b5141-f348-5954-a87e-8fd957593113")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { getActiveExtensionRegistrations, projectAfterCommandItemSnapshot, recordAfterCommandAffectedItem, runActiveOnReadHooks, runActiveBeforeMutationHooks, runActiveOnWriteHooks, runActiveServiceOverride, } from "../extensions/index.js";
@@ -22,6 +22,7 @@ import { normalizeItemId, normalizeRawItemId } from "../item/id.js";
 import { acquireItemMetadataDerivedIndexLock, listAllDocumentCandidatesCached, listAllDocumentsCached, listAllDocumentsCachedLight, refreshItemMetadataDerivedIndex, } from "./item-metadata-cache.js";
 import { getHistoryPath, getItemPath, ITEM_FILE_EXTENSIONS } from "./paths.js";
 import { resolveGovernanceKnobs } from "./settings.js";
+import { assertReadableTrackerRoot } from "./tracker-preflight.js";
 import { resolveClaimPrincipal } from "../shared/author.js";
 import { nowIso } from "../shared/time.js";
 async function fileExists(targetPath) {
@@ -60,92 +61,6 @@ function resolveItemFormatSearchOrder(preferredFormat) {
     }
     return ["toon", "json_markdown"];
 }
-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",
-        nextSteps: [
-            "Pass the tracker directory itself, usually <workspace>/.agents/pm.",
-        ],
-    });
-}
-function trackerRootUnreadableError(pmRoot) {
-    return new PmCliError(`Tracker root is not readable at ${pmRoot}.`, EXIT_CODE.GENERIC_FAILURE, {
-        code: "tracker_root_unreadable",
-        reason: "unreadable",
-        nextSteps: [
-            "Grant read and directory-search permission to the tracker root, then retry the SDK read.",
-        ],
-    });
-}
-async function assertMissingMetadataRootAncestors(pmRoot) {
-    const filesystemRoot = path.parse(path.resolve(pmRoot)).root;
-    let ancestor = path.dirname(path.resolve(pmRoot));
-    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);
-        }
-        break;
-    }
-}
-/** Require metadata enumeration to start from a real directory so an invalid source cannot masquerade as an empty tracker. */
-async function assertItemMetadataRoot(pmRoot) {
-    let stats;
-    try {
-        stats = await fs.stat(pmRoot);
-    }
-    catch (error) {
-        if (isErrno(error, "ENOENT")) {
-            await assertMissingMetadataRootAncestors(pmRoot);
-            throw new PmCliError(`Tracker root does not exist at ${pmRoot}.`, EXIT_CODE.NOT_FOUND, {
-                code: "tracker_root_missing",
-                reason: "missing",
-                nextSteps: [
-                    "Confirm the tracker root path and retry the SDK read.",
-                    "Initialize a tracker before enumerating its item metadata.",
-                ],
-            });
-        }
-        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;
-    }
-}
 /** Implements locate item for the public runtime surface of this module. */
 export async function locateItem(pmRoot, rawId, idPrefix = "pm-", preferredFormat, typeToFolder = TYPE_TO_FOLDER) {
     const normalizedId = normalizeItemId(rawId, idPrefix);
@@ -189,7 +104,7 @@ export async function readLocatedItem(item, options = {}) {
 }
 /** Implements list all item metadata for the public runtime surface of this module. */
 export async function listAllItemMetadata(pmRoot, preferredFormat, typeToFolder = TYPE_TO_FOLDER, warnings, schema) {
-    await assertItemMetadataRoot(pmRoot);
+    await assertReadableTrackerRoot(pmRoot);
     const documents = await listAllDocumentsCached(pmRoot, preferredFormat, typeToFolder, warnings, schema);
     return documents.map((document) => document.metadata);
 }
@@ -200,13 +115,13 @@ export async function listAllItemMetadata(pmRoot, preferredFormat, typeToFolder
  * read just the light scalar/small fields — see {@link listAllDocumentsCachedLight}.
  */
 export async function listAllItemMetadataLight(pmRoot, preferredFormat, typeToFolder = TYPE_TO_FOLDER, warnings, schema) {
-    await assertItemMetadataRoot(pmRoot);
+    await assertReadableTrackerRoot(pmRoot);
     const documents = await listAllDocumentsCachedLight(pmRoot, preferredFormat, typeToFolder, warnings, schema);
     return documents.map((document) => document.metadata);
 }
 /** List item metadata with bodies, optionally bypassing the derived-index fast path when an integrity workflow must re-read authoritative files. */
 export async function listAllItemMetadataWithBody(pmRoot, preferredFormat, typeToFolder = TYPE_TO_FOLDER, warnings, schema, options = {}) {
-    await assertItemMetadataRoot(pmRoot);
+    await assertReadableTrackerRoot(pmRoot);
     const candidates = await listAllDocumentCandidatesCached(pmRoot, preferredFormat, typeToFolder, warnings, schema, {
         includeBody: true,
         forceSourceScan: options.forceSourceScan,
@@ -727,4 +642,4 @@ export async function deleteItem(params) {
     }
 }
 //# sourceMappingURL=item-store.js.map
-//# debugId=b6db139b-7646-58f9-96af-d3c65bf7ddf6
+//# debugId=f49b5141-f348-5954-a87e-8fd957593113

package/dist/core/store/tracker-preflight.d.ts

@@ -0,0 +1,7 @@
+import { type PmCliErrorRecoveryPayload } from "../shared/errors.js";
+/** Build the non-interactive, tokenized retry that initializes a selected tracker root. */
+export declare function buildTrackerInitializationRecovery(pmRoot: string): PmCliErrorRecoveryPayload;
+/** Require a tracker root to be a readable directory without requiring initialized settings. */
+export declare function assertReadableTrackerRoot(pmRoot: string): Promise<void>;
+/** Require the selected tracker root and its settings marker before an SDK command reads or mutates project state. */
+export declare function assertInitializedTracker(pmRoot: string): Promise<void>;

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/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;

package/dist/sdk/agent/tracker-preflight-contracts.js

@@ -0,0 +1,127 @@
+/**
+ * @module sdk/agent/tracker-preflight-contracts
+ *
+ * Declares and scores executable recovery for tracker filesystem preflight failures.
+ */
+
+!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]="941a11a9-f756-56b3-9dc1-8afd78bc9328")}catch(e){}}();
+const TRACKER_PREFLIGHT_RECOVERY_CONTRACTS = [
+    {
+        probe_id: "tracker-root-missing",
+        failure_kind: "missing_root",
+        expected_error_code: "tracker_root_missing",
+        expected_exit_code: 3,
+        recovery_kind: "initialize",
+    },
+    {
+        probe_id: "tracker-root-settings-missing",
+        failure_kind: "settings_missing",
+        expected_error_code: "tracker_not_initialized",
+        expected_exit_code: 3,
+        recovery_kind: "initialize",
+    },
+    {
+        probe_id: "tracker-root-not-directory",
+        failure_kind: "not_directory",
+        expected_error_code: "tracker_root_not_directory",
+        expected_exit_code: 2,
+        recovery_kind: "select_directory",
+    },
+    {
+        probe_id: "tracker-root-unreadable",
+        failure_kind: "unreadable_root",
+        expected_error_code: "tracker_root_unreadable",
+        expected_exit_code: 1,
+        recovery_kind: "repair_permissions",
+    },
+];
+/** Return defensive copies of every core tracker preflight recovery contract. */
+export function listTrackerPreflightRecoveryContracts() {
+    return TRACKER_PREFLIGHT_RECOVERY_CONTRACTS.map((contract) => ({
+        ...contract,
+    }));
+}
+function findTrackerPreflightObservationFindings(contract, observation) {
+    const findings = [];
+    if (observation.error_code !== contract.expected_error_code) {
+        findings.push({
+            code: "error_code_mismatch",
+            probe_id: contract.probe_id,
+            detail: `Expected ${contract.expected_error_code}, received ${observation.error_code}.`,
+        });
+    }
+    if (observation.exit_code !== contract.expected_exit_code) {
+        findings.push({
+            code: "exit_code_mismatch",
+            probe_id: contract.probe_id,
+            detail: `Expected exit ${contract.expected_exit_code}, received ${observation.exit_code}.`,
+        });
+    }
+    if (observation.recovery_kind !== contract.recovery_kind) {
+        findings.push({
+            code: "recovery_kind_mismatch",
+            probe_id: contract.probe_id,
+            detail: `Expected ${contract.recovery_kind}, received ${observation.recovery_kind}.`,
+        });
+    }
+    const initIndex = observation.suggested_retry_args.indexOf("init");
+    const validInitCommand = initIndex === 0 ||
+        (initIndex === 2 &&
+            observation.suggested_retry_args[0] === "--pm-path" &&
+            observation.suggested_retry_args[1]?.length > 0);
+    if (contract.recovery_kind === "initialize" && !validInitCommand) {
+        findings.push({
+            code: "missing_init_recovery",
+            probe_id: contract.probe_id,
+            detail: "Missing and uninitialized roots must emit a tokenized init retry.",
+        });
+    }
+    if (observation.unsafe_init_recommended ||
+        (contract.recovery_kind !== "initialize" &&
+            observation.suggested_retry_args.includes("init"))) {
+        findings.push({
+            code: "unsafe_init_recovery",
+            probe_id: contract.probe_id,
+            detail: "A tracker root that cannot be initialized safely must not recommend initialization.",
+        });
+    }
+    if (!observation.retry_succeeded) {
+        findings.push({
+            code: "retry_failed",
+            probe_id: contract.probe_id,
+            detail: "The emitted retry or safe alternate-root recovery did not execute successfully.",
+        });
+    }
+    return findings;
+}
+/** Score runtime observations against the complete tracker preflight recovery corpus. */
+export function scoreTrackerPreflightRecoveryClosure(observations) {
+    const observationsByProbe = new Map(observations.map((observation) => [observation.probe_id, observation]));
+    const findings = [];
+    let closedProbeCount = 0;
+    for (const contract of TRACKER_PREFLIGHT_RECOVERY_CONTRACTS) {
+        const observation = observationsByProbe.get(contract.probe_id);
+        if (observation === undefined) {
+            findings.push({
+                code: "missing_probe",
+                probe_id: contract.probe_id,
+                detail: "No runtime observation was supplied for this contract.",
+            });
+            continue;
+        }
+        const observationFindings = findTrackerPreflightObservationFindings(contract, observation);
+        findings.push(...observationFindings);
+        if (observationFindings.length === 0)
+            closedProbeCount += 1;
+    }
+    findings.sort((left, right) => left.probe_id.localeCompare(right.probe_id) ||
+        left.code.localeCompare(right.code));
+    return {
+        ok: findings.length === 0,
+        probe_count: TRACKER_PREFLIGHT_RECOVERY_CONTRACTS.length,
+        closed_probe_count: closedProbeCount,
+        findings,
+    };
+}
+//# sourceMappingURL=tracker-preflight-contracts.js.map
+//# debugId=941a11a9-f756-56b3-9dc1-8afd78bc9328

package/dist/sdk/annotations.js

@@ -4,9 +4,10 @@
  * Implements the pm annotation command 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]="0af9967c-ca72-563a-9518-2e68da0c0fe0")}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]="eac75dc5-80b4-50d2-b615-4f96edca7346")}catch(e){}}();
+import { assertInitializedTracker } from "./environment/tracker-preflight.js";
 import { readFile } from "node:fs/promises";
-import { isFileAbsentError, pathExists } from "../core/fs/fs-utils.js";
+import { isFileAbsentError } from "../core/fs/fs-utils.js";
 import { getActiveExtensionRegistrations } from "../core/extensions/index.js";
 import { resolveItemTypeRegistry } from "../core/item/type-registry.js";
 import { createStdinTokenResolver, parseCsvKv } from "../core/item/parse.js";
@@ -16,7 +17,7 @@ import { parseLimit } from "../core/shared/numeric-parsers.js";
 import { nowIso } from "../core/shared/time.js";
 import { resolveAuthor } from "../core/shared/author.js";
 import { locateItem, mutateItem, readLocatedItem, } from "../core/store/item-store.js";
-import { getSettingsPath, resolvePmRoot } from "../core/store/paths.js";
+import { resolvePmRoot } from "../core/store/paths.js";
 import { readSettings } from "../core/store/settings.js";
 /** Map transport-level `full` onto the SDK annotation history option. */
 export function normalizeAnnotationTransportOptions(options) {
@@ -215,9 +216,7 @@ function assertAnnotationMessageHasTextSource(config, options) {
 export async function runAnnotationCommand(id, options, global, config) {
     assertAnnotationMessageHasTextSource(config, options);
     const pmRoot = resolvePmRoot(process.cwd(), global.path);
-    if (!(await pathExists(getSettingsPath(pmRoot)))) {
-        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
-    }
+    await assertInitializedTracker(pmRoot);
     const settings = await readSettings(pmRoot);
     const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
     const limit = parseLimit(options.limit);
@@ -399,4 +398,4 @@ function renderAnnotationResult(id, collectionKey, allEntries, limit, includeMet
     };
 }
 //# sourceMappingURL=annotations.js.map
-//# debugId=0af9967c-ca72-563a-9518-2e68da0c0fe0
+//# debugId=eac75dc5-80b4-50d2-b615-4f96edca7346

package/dist/sdk/config.d.ts

@@ -1,3 +1,8 @@
+/**
+ * @module sdk/config
+ *
+ * Implements the pm config command surface and its agent-facing runtime behavior.
+ */
 import { type ConfigKey } from "../core/config/positional-value.js";
 import { type NestedSettingDescriptor } from "../core/config/nested-settings.js";
 import type { GlobalOptions } from "../core/shared/command-types.js";

package/dist/sdk/config.js

@@ -4,8 +4,7 @@
  * Implements the pm config 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]="a9a8d99c-df4e-55b3-81f5-27124d598c5f")}catch(e){}}();
-import { pathExists } from "../core/fs/fs-utils.js";
+!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]="5918331a-46e9-5699-b85d-89f49a27d341")}catch(e){}}();
 import { resolveConfigPositionalValue, } from "../core/config/positional-value.js";
 import { NESTED_SETTING_DESCRIPTORS, parseNestedSettingValue, readNestedSettingValue, resolveNestedSettingDescriptor, writeNestedSettingValue, } from "../core/config/nested-settings.js";
 import { getActiveExtensionRegistrations } from "../core/extensions/index.js";
@@ -17,6 +16,7 @@ import { resolveItemTypesFilePath } from "../core/schema/runtime-schema.js";
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { createUnknownSubcommandError } from "./agent/subcommand-recovery.js";
+import { assertInitializedTracker } from "./environment/tracker-preflight.js";
 import { migrateItemFilesToFormat } from "../core/store/item-format-migration.js";
 import { getSettingsPath, resolveGlobalPmRoot, resolvePmRoot, } from "../core/store/paths.js";
 import { readSettingsWithMetadata, writeSettings, } from "../core/store/settings.js";
@@ -503,8 +503,8 @@ async function resolveSettingsTarget(scope, global) {
         ? resolvePmRoot(cwd, global.path)
         : resolveGlobalPmRoot(cwd);
     const settingsPath = getSettingsPath(pmRoot);
-    if (scope === "project" && !(await pathExists(settingsPath))) {
-        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
+    if (scope === "project") {
+        await assertInitializedTracker(pmRoot);
     }
     return { pmRoot, settingsPath };
 }
@@ -1097,4 +1097,4 @@ export const _testOnlyConfigCommand = {
     normalizeWarnings,
 };
 //# sourceMappingURL=config.js.map
-//# debugId=a9a8d99c-df4e-55b3-81f5-27124d598c5f
+//# debugId=5918331a-46e9-5699-b85d-89f49a27d341

package/dist/sdk/context-intent-runtime.js

@@ -6,10 +6,11 @@
  * SDK entrypoint.
  */
 
-!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]="7ba0243e-98d1-5aef-bd47-54f0b630be58")}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]="1a7548f2-93a0-5dfc-9d9a-c5aef4656c7c")}catch(e){}}();
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { isFileAbsentError } from "../core/fs/fs-utils.js";
+import { assertReadableTrackerRoot } from "./environment/tracker-preflight.js";
 import { runWithContextIntentContracts, } from "./context-intent-contracts.js";
 /** Conventional workspace declaration file relative to the tracker root. */
 export const PM_CONTEXT_INTENTS_FILE = "context-intents.json";
@@ -59,11 +60,13 @@ export async function readWorkspaceContextIntentContracts(pmRoot) {
     catch (error) {
         // Absent declarations are the norm. `ENOTDIR` counts as absent too: when
         // the tracker root is a regular file the declaration cannot exist, and the
-        // authoritative root guard downstream owns that refusal — this optional
-        // read must not pre-empt it with a raw runtime fault.
+        // authoritative root guard downstream owns that refusal. Other read
+        // failures first pass through the same root guard so permissions failures
+        // cannot pre-empt it with an unclassified runtime fault.
         if (isFileAbsentError(error)) {
             return [];
         }
+        await assertReadableTrackerRoot(pmRoot);
         throw error;
     }
     let parsed;
@@ -110,4 +113,4 @@ export async function runWithDiscoveredContextIntentContracts(options, run) {
     return await runWithContextIntentContracts(layers, run);
 }
 //# sourceMappingURL=context-intent-runtime.js.map
-//# debugId=7ba0243e-98d1-5aef-bd47-54f0b630be58
+//# debugId=1a7548f2-93a0-5dfc-9d9a-c5aef4656c7c

package/dist/sdk/contracts.d.ts

@@ -16,4 +16,5 @@ export * from "./output-contracts.js";
 export * from "./read-output-contracts.js";
 export * from "./agent/refusal-closure.js";
 export * from "./agent/closed-domain-contracts.js";
+export * from "./agent/tracker-preflight-contracts.js";
 export type { PmReadOutputSessionReceipt, PmReadOutputSessionState, } from "./read-output-session.js";

package/dist/sdk/contracts.js

@@ -4,7 +4,7 @@
  * Exposes command and action contract data without loading SDK runtime code.
  */
 
-!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]="8e9dc315-4c5a-5cb0-befc-e0dbbf7e8571")}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]="8bdc03e5-c5cd-5842-b438-cf7bc79863f0")}catch(e){}}();
 export * from "./cli-contracts.js";
 export * from "./cli-contracts/grammar-contracts.js";
 export * from "./cli-contracts/command-exit-contracts.js";
@@ -18,5 +18,6 @@ export * from "./output-contracts.js";
 export * from "./read-output-contracts.js";
 export * from "./agent/refusal-closure.js";
 export * from "./agent/closed-domain-contracts.js";
+export * from "./agent/tracker-preflight-contracts.js";
 //# sourceMappingURL=contracts.js.map
-//# debugId=8e9dc315-4c5a-5cb0-befc-e0dbbf7e8571
+//# debugId=8bdc03e5-c5cd-5842-b438-cf7bc79863f0