@unbrained/pm-cli 2026.8.20 → 2026.8.22

package/dist/core/extensions/extension-hook-runtime.js

@@ -4,7 +4,7 @@
  * Implements extension runtime contracts and governance for Extension Hook Runtime.
  */
 
-!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]="ac377139-8ce2-58ad-8005-0ac907a9baed")}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]="d1dd5d4f-5f08-5e52-b109-d066f92ae3b3")}catch(e){}}();
 import { cloneCommandOptionsSnapshot, cloneContextSnapshot, cloneGlobalOptionsSnapshot, normalizeCommandName, } from "./extension-runtime-helpers.js";
 import { stableValueEquals } from "../shared/serialization.js";
 import { EXIT_CODE } from "../shared/constants.js";
@@ -480,6 +480,20 @@ function isLegacyOutputPayloadEcho(result, context, serviceContext) {
         result !== null &&
         stableValueEquals(result, serviceContext.payload));
 }
+function resolveMatchedServiceDecision(matched, decision, warnings) {
+    if (!decision.handled) {
+        return undefined;
+    }
+    if (matched.passThrough === true) {
+        warnings.push(`extension_service_pass_through_contract_violated:${matched.layer}:${matched.name}:${matched.service}`);
+        return undefined;
+    }
+    return {
+        handled: true,
+        result: decision.result,
+        warnings,
+    };
+}
 /** Implements run service override sync for the public runtime surface of this module. */
 export function runServiceOverrideSync(services, context) {
     const matches = matchingServiceOverrides(services, context.service);
@@ -499,15 +513,9 @@ export function runServiceOverrideSync(services, context) {
                 warnings.push(`extension_output_format_payload_echo_deprecated:${matched.layer}:${matched.name}`);
                 continue;
             }
-            const decision = resolveServiceOverrideValue(result, context);
-            if (!decision.handled) {
-                continue;
-            }
-            return {
-                handled: true,
-                result: decision.result,
-                warnings,
-            };
+            const resolved = resolveMatchedServiceDecision(matched, resolveServiceOverrideValue(result, context), warnings);
+            if (resolved)
+                return resolved;
         }
         catch {
             warnings.push(`extension_service_override_failed:${matched.layer}:${matched.name}:${matched.service}`);
@@ -534,15 +542,9 @@ export async function runServiceOverride(services, context) {
                 warnings.push(`extension_output_format_payload_echo_deprecated:${matched.layer}:${matched.name}`);
                 continue;
             }
-            const decision = resolveServiceOverrideValue(result, context);
-            if (!decision.handled) {
-                continue;
-            }
-            return {
-                handled: true,
-                result: decision.result,
-                warnings,
-            };
+            const resolved = resolveMatchedServiceDecision(matched, resolveServiceOverrideValue(result, context), warnings);
+            if (resolved)
+                return resolved;
         }
         catch {
             warnings.push(`extension_service_override_failed:${matched.layer}:${matched.name}:${matched.service}`);
@@ -695,4 +697,4 @@ export function runRendererOverride(renderers, context) {
     }
 }
 //# sourceMappingURL=extension-hook-runtime.js.map
-//# debugId=ac377139-8ce2-58ad-8005-0ac907a9baed
+//# debugId=d1dd5d4f-5f08-5e52-b109-d066f92ae3b3

package/dist/core/extensions/extension-types.d.ts

@@ -483,6 +483,11 @@ export type ServiceOverrideDecision = {
 };
 /** Restricts service override values accepted by command, SDK, and storage contracts. */
 export type ServiceOverride = (context: ServiceOverrideContext) => unknown | ServiceOverrideDecision;
+/** Host-enforced ownership metadata for a service override. */
+export interface ServiceOverrideOwnership {
+    /** Declare that the callback may only decline. Any handled result is ignored and diagnosed by the host. */
+    passThrough?: boolean;
+}
 /** Documents the registered extension hook payload exchanged by command, SDK, and package integrations. */
 export interface RegisteredExtensionHook<THook> {
     /** Value that configures or reports layer for this contract. */
@@ -1187,6 +1192,8 @@ export interface RegisteredExtensionServiceOverride {
     service: ExtensionServiceName;
     /** Value that configures or reports run for this contract. */
     run: ServiceOverride;
+    /** Whether the host forbids this callback from handling the service payload. */
+    passThrough?: boolean;
 }
 /** Documents the registered extension renderer override payload exchanged by command, SDK, and package integrations. */
 export interface RegisteredExtensionRendererOverride {
@@ -1464,7 +1471,7 @@ export interface ExtensionApi {
     /** Value that configures or reports register preflight for this contract. */
     registerPreflight(override: PreflightOverride | ScopedPreflightOverrideDefinition): void;
     /** Value that configures or reports register service for this contract. */
-    registerService(service: ExtensionServiceName, override: ServiceOverride): void;
+    registerService(service: ExtensionServiceName, override: ServiceOverride, ownership?: ServiceOverrideOwnership): void;
     /** Value that configures or reports register flags for this contract. */
     registerFlags(targetCommand: string, flags: FlagDefinition[]): void;
     /** Value that configures or reports register item fields for this contract. */

package/dist/core/extensions/extension-types.js

@@ -1,6 +1,6 @@
 /** Public contract for known extension capabilities, shared by SDK and presentation-layer consumers. */
 
-!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]="a54549aa-2f6c-5092-a3eb-5b36ee698ea4")}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]="87454a57-b62e-560a-b66f-3c15d4a95cc2")}catch(e){}}();
 export const KNOWN_EXTENSION_CAPABILITIES = [
     "commands",
     "renderers",
@@ -100,4 +100,4 @@ export function createDefaultExtensionGovernancePolicy() {
     };
 }
 //# sourceMappingURL=extension-types.js.map
-//# debugId=a54549aa-2f6c-5092-a3eb-5b36ee698ea4
+//# debugId=87454a57-b62e-560a-b66f-3c15d4a95cc2

package/dist/core/extensions/loader.js

@@ -4,7 +4,7 @@
  * Implements extension runtime contracts and governance for Loader.
  */
 
-!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]="cccce7c1-dd08-5c9f-a74e-e639536b9a6a")}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]="10311c96-5cba-5021-a8c5-82abd6eeb6f5")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
@@ -19,6 +19,7 @@ import { KNOWN_ITEM_FIELD_TYPES, normalizeItemFieldType, suggestKnownItemFieldTy
 import { snapshotExtensionModuleGraph } from "./module-graph-snapshot.js";
 import { captureExtensionActivationRollback } from "./activation-transaction.js";
 import { collectPreflightCollisionWarnings, normalizePreflightOverride, } from "./preflight-ownership.js";
+import { normalizeServiceOverrideOwnership } from "./service-ownership.js";
 import { assertCommandDefinitionMetadataStrings } from "./command-visibility-tier.js";
 import { buildImportExportContext, resolveImportExportArtifactOutput, } from "./exporter-output-contract.js";
 import { asRegistrationRecord, assertOptionalBooleanField, assertOptionalFlagDefaultField, assertOptionalStringArrayField, assertOptionalStringField, normalizeOptionalStringArrayField, } from "./registration-validation.js";
@@ -1569,7 +1570,7 @@ class ExtensionApiRegistrar {
             ...normalized,
         });
     }
-    registerService(service, override) {
+    registerService(service, override, ownership = {}) {
         assertExtensionCapability(this.#loadedExtension, "services", "registerService");
         const normalizedService = String(service).trim().toLowerCase();
         if (!isExtensionServiceName(normalizedService)) {
@@ -1584,6 +1585,9 @@ class ExtensionApiRegistrar {
             name: this.#loadedExtension.name,
             service: normalizedService,
             run: override,
+            ...(normalizeServiceOverrideOwnership(ownership)
+                ? { passThrough: true }
+                : {}),
         });
     }
     registerRenderer(format, renderer, ownership = {}) {
@@ -2216,4 +2220,4 @@ export const _testOnlyLoader = {
     },
 };
 //# sourceMappingURL=loader.js.map
-//# debugId=cccce7c1-dd08-5c9f-a74e-e639536b9a6a
+//# debugId=10311c96-5cba-5021-a8c5-82abd6eeb6f5

package/dist/core/extensions/service-ownership.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @module core/extensions/service-ownership
+ *
+ * Validates host-enforced ownership metadata for extension service overrides.
+ */
+import type { ServiceOverrideOwnership } from "./extension-types.js";
+/** Validate one service ownership declaration and return its normalized pass-through flag. */
+export declare function normalizeServiceOverrideOwnership(ownership: ServiceOverrideOwnership): boolean;

package/dist/core/extensions/service-ownership.js

@@ -0,0 +1,20 @@
+/** Validate one service ownership declaration and return its normalized pass-through flag. */
+
+!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]="a30142c8-b04d-5878-8497-c902ff299e94")}catch(e){}}();
+export function normalizeServiceOverrideOwnership(ownership) {
+    if (ownership === null ||
+        typeof ownership !== "object" ||
+        Array.isArray(ownership)) {
+        throw new TypeError("registerService ownership must be an object");
+    }
+    if (Reflect.ownKeys(ownership).some((key) => key !== "passThrough")) {
+        throw new TypeError("registerService ownership supports only passThrough");
+    }
+    if (ownership.passThrough !== undefined &&
+        typeof ownership.passThrough !== "boolean") {
+        throw new TypeError("registerService ownership.passThrough must be a boolean when provided");
+    }
+    return ownership.passThrough === true;
+}
+//# sourceMappingURL=service-ownership.js.map
+//# debugId=a30142c8-b04d-5878-8497-c902ff299e94

package/dist/core/item/id.js

@@ -4,7 +4,7 @@
  * Defines item parsing, formatting, and lifecycle helpers for Id.
  */
 
-!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]="50a277b9-d530-5aa0-8bd0-8eb0d36911e5")}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]="6b3f1585-ab12-57ca-80eb-d3cebc384c52")}catch(e){}}();
 import crypto from "node:crypto";
 import path from "node:path";
 import { TYPE_TO_FOLDER } from "../shared/constants.js";
@@ -12,10 +12,25 @@ import { pathExists } from "../fs/fs-utils.js";
 import { nextReproducibleToken } from "../reproducibility/context.js";
 /** Implements normalize prefix for the public runtime surface of this module. */
 export function normalizePrefix(input) {
-    const normalized = (input ?? "").trim().toLowerCase();
-    if (!normalized)
+    const normalized = [];
+    let separatorPending = false;
+    for (const character of (input ?? "").toLowerCase()) {
+        const codePoint = character.charCodeAt(0);
+        const isAsciiDigit = codePoint >= 48 && codePoint <= 57;
+        const isAsciiLetter = codePoint >= 97 && codePoint <= 122;
+        if (!isAsciiDigit && !isAsciiLetter) {
+            separatorPending = normalized.length > 0;
+            continue;
+        }
+        if (separatorPending) {
+            normalized.push("-");
+            separatorPending = false;
+        }
+        normalized.push(character);
+    }
+    if (normalized.length === 0)
         return "pm-";
-    return normalized.endsWith("-") ? normalized : `${normalized}-`;
+    return `${normalized.join("")}-`;
 }
 /** Implements normalize raw item id for the public runtime surface of this module. */
 export function normalizeRawItemId(input) {
@@ -91,4 +106,4 @@ export async function generateItemId(pmRoot, prefix, options = {}) {
     throw new Error(`Unable to generate unique id after ${attempts} attempts`);
 }
 //# sourceMappingURL=id.js.map
-//# debugId=50a277b9-d530-5aa0-8bd0-8eb0d36911e5
+//# debugId=6b3f1585-ab12-57ca-80eb-d3cebc384c52

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

@@ -4,7 +4,7 @@
  * Defines item parsing, formatting, and lifecycle helpers for Item Format.
  */
 
-!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]="eaf0e260-a864-57cf-b23b-aac4f9151d8e")}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]="5eac19ec-235e-5e6f-8ae7-4725f99c9d7f")}catch(e){}}();
 import { encode as encodeToon } from "@toon-format/toon";
 import { isDeepStrictEqual } from "node:util";
 import { CONFIDENCE_TEXT_VALUES, ISSUE_SEVERITY_VALUES, PLAN_STEP_STATUS_VALUES, RECURRENCE_FREQUENCY_VALUES, RECURRENCE_WEEKDAY_VALUES, STATUS_VALUES, weekdayOrderIndex, } from "../../types/index.js";
@@ -601,6 +601,30 @@ function normalizeTestRunMeasurements(value) {
         .slice(0, 32);
     return deduplicated.length > 0 ? deduplicated : undefined;
 }
+/** Normalize and bound command/context provenance retained for a test run. */
+function normalizeTestRunExecutions(values) {
+    if (!Array.isArray(values))
+        return undefined;
+    const executions = values
+        .filter((execution) => execution &&
+        typeof execution.command === "string" &&
+        execution.command.trim().length > 0)
+        .slice(0, 32)
+        .map((execution) => ({
+        command: execution.command.trim(),
+        requested_pm_context_mode: execution.requested_pm_context_mode === "schema" ||
+            execution.requested_pm_context_mode === "tracker" ||
+            execution.requested_pm_context_mode === "auto"
+            ? execution.requested_pm_context_mode
+            : undefined,
+        pm_context_mode: execution.pm_context_mode === "schema" ||
+            execution.pm_context_mode === "tracker" ||
+            execution.pm_context_mode === "auto"
+            ? execution.pm_context_mode
+            : undefined,
+    }));
+    return executions.length > 0 ? executions : undefined;
+}
 function normalizeTestRunSummary(value) {
     const runId = typeof value.run_id === "string" ? value.run_id.trim() : "";
     const kind = value.kind === "test" || value.kind === "test-all" ? value.kind : "test";
@@ -623,6 +647,7 @@ function normalizeTestRunSummary(value) {
         linked_tests: normalizeNonNegativeInteger(value.linked_tests),
         fail_on_skipped_triggered: value.fail_on_skipped_triggered === true ? true : undefined,
         measurements: normalizeTestRunMeasurements(value.measurements),
+        executions: normalizeTestRunExecutions(value.executions),
     };
     deleteUndefinedFields(summary);
     return summary;
@@ -1393,4 +1418,4 @@ export const _testOnlyItemFormat = {
     sortTests,
 };
 //# sourceMappingURL=item-format.js.map
-//# debugId=eaf0e260-a864-57cf-b23b-aac4f9151d8e
+//# debugId=5eac19ec-235e-5e6f-8ae7-4725f99c9d7f

package/dist/core/shared/errors.d.ts

@@ -79,6 +79,10 @@ export interface PmCliErrorContext {
     check?: string;
     /** Serialization format involved in a parse failure. */
     format?: string;
+    /** CLI flag whose supplied value violated a shared mutation grammar. */
+    flag?: string;
+    /** Supplied scalar value that violated a shared mutation grammar. */
+    value?: string;
     /** Item format version involved in a compatibility failure. */
     format_version?: number;
     /** Schema type that determines the shape and validation rules for this value. */
@@ -99,6 +103,22 @@ export interface PmCliErrorContext {
     nextSteps?: string[];
     /** Exact selectors that could not be matched by a lossless removal. */
     unmatched?: string[];
+    /** Dependency selectors that matched no stored edge. */
+    unmatched_selectors?: Array<{
+        id: string;
+        kind?: string;
+        source_kind?: string;
+        author?: string;
+        created_at?: string;
+    }>;
+    /** Compact stored dependency identities available when a removal failed. */
+    available_dependencies?: Array<{
+        id: string;
+        kind: string;
+        source_kind?: string;
+        author?: string;
+        created_at?: string;
+    }>;
     /** Exact verifier findings that caused an integrity-sensitive operation to refuse. */
     verification_errors?: string[];
     /** Local dependency targets that could not be resolved before mutation. */

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]="922e2e27-1499-5466-98e4-322d0d742e40")}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=922e2e27-1499-5466-98e4-322d0d742e40

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/refusal-reachability.d.ts

@@ -37,7 +37,7 @@ export type PmRecoveryReferenceKind = (typeof PM_RECOVERY_REFERENCE_KINDS)[numbe
 /** Behavioral promise attached to a recovery reference. */
 export type PmRecoveryReferenceSemantics = "recovery" | "replacement" | "behavior_preserving";
 /** Literal envelope fields recognized as recovery-reference producers. */
-export declare const PM_RECOVERY_REFERENCE_FIELDS: readonly ("restore_with" | "migration_hint" | "migration_hints" | "suggested_retry" | "next_best_command" | "fallback_candidates" | "examples" | "next_steps" | "suggested_next_steps" | "candidate_commands" | "example" | "candidate_command" | "next_step" | "retry_command")[];
+export declare const PM_RECOVERY_REFERENCE_FIELDS: readonly ("suggested_retry" | "next_best_command" | "candidate_commands" | "next_steps" | "examples" | "restore_with" | "migration_hint" | "migration_hints" | "fallback_candidates" | "suggested_next_steps" | "example" | "candidate_command" | "next_step" | "retry_command")[];
 /** One source file supplied to the producer-census analyzer. */
 export interface PmRecoveryProducerSource {
     /** Repository-relative source path. */