@unbrained/pm-cli 2026.9.5 → 2026.9.6

package/dist/core/extensions/module-graph-snapshot.js

@@ -5,7 +5,8 @@
  * verification.
  */
 
-!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]="e81790e9-3de2-5639-a84d-2c4714afbbf4")}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]="361b49b6-942e-55d9-9979-d72bc94721c6")}catch(e){}}();
+import { withHostEnvironmentBoundary } from "../fs/host-environment-errors.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 /**
@@ -23,11 +24,11 @@ export async function snapshotExtensionModuleGraph(snapshotRoot, extension) {
         throw new Error(`Cannot snapshot extension entry outside its package directory: ${extension.entry_path}`);
     }
     const snapshotDirectory = path.join(snapshotRoot, `${extension.layer}-${extension.directory.replace(/[^a-zA-Z0-9._-]/gu, "_")}`);
-    await fs.cp(sourceDirectory, snapshotDirectory, {
+    await withHostEnvironmentBoundary("extension_module_graph_snapshot", () => fs.cp(sourceDirectory, snapshotDirectory, {
         recursive: true,
         force: true,
-    });
+    }));
     return path.join(snapshotDirectory, relativeEntryPath);
 }
 //# sourceMappingURL=module-graph-snapshot.js.map
-//# debugId=e81790e9-3de2-5639-a84d-2c4714afbbf4
+//# debugId=361b49b6-942e-55d9-9979-d72bc94721c6

package/dist/core/fs/host-environment-errors.d.ts

@@ -0,0 +1,27 @@
+import { PmCliError } from "../shared/errors.js";
+/** Optional stable codes used by an existing SDK surface for each fault class. */
+export interface HostEnvironmentFaultCodeOverrides {
+    /** Code used for quota and storage exhaustion. */
+    capacity?: string;
+    /** Code used for access policy and read-only filesystems. */
+    permission?: string;
+    /** Code used for file-descriptor and memory exhaustion. */
+    resource?: string;
+}
+/** Context and compatibility controls for a host-environment boundary. */
+export interface HostEnvironmentBoundaryOptions {
+    /** Existing surface-specific codes that must remain compatible. */
+    codes?: HostEnvironmentFaultCodeOverrides;
+    /** Human explanation of why the operation needs host resources. */
+    why?: string;
+    /** Additional ordered recovery guidance. */
+    nextSteps?: readonly string[];
+    /** Copyable retry command when one is safe. */
+    suggestedRetry?: string;
+}
+/** Return a declared host errno only when it represents recoverable environment state. */
+export declare function classifyHostEnvironmentFault(error: unknown): string | null;
+/** Translate one known host fault into a stable path-redacted SDK refusal. */
+export declare function translateHostEnvironmentFault(error: unknown, operation: string, options?: HostEnvironmentBoundaryOptions): PmCliError | null;
+/** Run one SDK filesystem stage and translate only declared host faults. */
+export declare function withHostEnvironmentBoundary<T>(operation: string, run: () => Promise<T>, options?: HostEnvironmentBoundaryOptions): Promise<T>;

package/dist/core/fs/host-environment-errors.js

@@ -0,0 +1,142 @@
+/**
+ * @module core/fs/host-environment-errors
+ *
+ * Classifies host filesystem/resource failures at SDK boundaries without
+ * leaking local paths or swallowing genuine implementation defects.
+ */
+
+!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]="1262c682-2b8a-506f-a3e1-155ad682d763")}catch(e){}}();
+import { constants as osConstants } from "node:os";
+import { EXIT_CODE } from "../shared/constants.js";
+import { PmCliError } from "../shared/errors.js";
+const HOST_ENVIRONMENT_FAULTS = new Map([
+    [
+        "EACCES",
+        {
+            summary: "was denied filesystem permission",
+            recovery: "Grant the required filesystem access, then retry.",
+            category: "permission",
+        },
+    ],
+    [
+        "EDQUOT",
+        {
+            summary: "exceeded the filesystem quota",
+            recovery: "Raise or reclaim the filesystem quota, then retry.",
+            category: "capacity",
+        },
+    ],
+    [
+        "EMFILE",
+        {
+            summary: "exhausted the process file-descriptor limit",
+            recovery: "Close unused file handles or raise the process limit, then retry.",
+            category: "resource",
+        },
+    ],
+    [
+        "ENFILE",
+        {
+            summary: "exhausted the host file-descriptor limit",
+            recovery: "Free host file descriptors or raise the host limit, then retry.",
+            category: "resource",
+        },
+    ],
+    [
+        "ENOMEM",
+        {
+            summary: "ran out of available memory",
+            recovery: "Free memory or reduce concurrent work, then retry.",
+            category: "resource",
+        },
+    ],
+    [
+        "ENOSPC",
+        {
+            summary: "ran out of storage space",
+            recovery: "Free storage on the filesystem holding the project, then retry.",
+            category: "capacity",
+        },
+    ],
+    [
+        "EPERM",
+        {
+            summary: "was denied by the host permission policy",
+            recovery: "Grant the required filesystem permission, then retry.",
+            category: "permission",
+        },
+    ],
+    [
+        "EROFS",
+        {
+            summary: "targeted a read-only filesystem",
+            recovery: "Use a writable project filesystem or remount it read-write, then retry.",
+            category: "permission",
+        },
+    ],
+]);
+const OPERATION_PATTERN = /^[a-z][a-z0-9_]{0,63}$/u;
+const HOST_ENVIRONMENT_ERRNO_NAMES = new Map([
+    [osConstants.errno.EACCES, "EACCES"],
+    [osConstants.errno.EDQUOT, "EDQUOT"],
+    [osConstants.errno.EMFILE, "EMFILE"],
+    [osConstants.errno.ENFILE, "ENFILE"],
+    [osConstants.errno.ENOMEM, "ENOMEM"],
+    [osConstants.errno.ENOSPC, "ENOSPC"],
+    [osConstants.errno.EPERM, "EPERM"],
+    [osConstants.errno.EROFS, "EROFS"],
+].filter(([errno]) => Number.isInteger(errno)));
+const HOST_ENVIRONMENT_FAULT_CODES = {
+    capacity: { code: "host_environment_capacity_fault" },
+    permission: { code: "host_environment_permission_fault" },
+    resource: { code: "host_environment_resource_fault" },
+};
+/** Return a declared host errno only when it represents recoverable environment state. */
+export function classifyHostEnvironmentFault(error) {
+    if (typeof error !== "object" || error === null) {
+        return null;
+    }
+    const errorRecord = error;
+    if (typeof errorRecord.code === "string" &&
+        HOST_ENVIRONMENT_FAULTS.has(errorRecord.code)) {
+        return errorRecord.code;
+    }
+    if (typeof errorRecord.errno !== "number" ||
+        !Number.isInteger(errorRecord.errno)) {
+        return null;
+    }
+    return HOST_ENVIRONMENT_ERRNO_NAMES.get(Math.abs(errorRecord.errno)) ?? null;
+}
+/** Translate one known host fault into a stable path-redacted SDK refusal. */
+export function translateHostEnvironmentFault(error, operation, options = {}) {
+    const errno = classifyHostEnvironmentFault(error);
+    if (errno === null)
+        return null;
+    if (!OPERATION_PATTERN.test(operation)) {
+        throw new PmCliError("Host environment operation labels must be bounded identifiers.", EXIT_CODE.USAGE, { code: "host_environment_operation_invalid", field: "operation" });
+    }
+    const fault = HOST_ENVIRONMENT_FAULTS.get(errno);
+    return new PmCliError(`Host filesystem operation ${operation} ${fault.summary}.`, EXIT_CODE.GENERIC_FAILURE, {
+        code: options.codes?.[fault.category] ??
+            HOST_ENVIRONMENT_FAULT_CODES[fault.category].code,
+        reason: errno,
+        required: fault.recovery,
+        why: options.why ??
+            "The operating system refused a required project filesystem operation.",
+        nextSteps: [fault.recovery, ...(options.nextSteps ?? [])],
+        ...(options.suggestedRetry
+            ? { recovery: { suggested_retry: options.suggestedRetry } }
+            : {}),
+    });
+}
+/** Run one SDK filesystem stage and translate only declared host faults. */
+export async function withHostEnvironmentBoundary(operation, run, options = {}) {
+    try {
+        return await run();
+    }
+    catch (error) {
+        throw translateHostEnvironmentFault(error, operation, options) ?? error;
+    }
+}
+//# sourceMappingURL=host-environment-errors.js.map
+//# debugId=1262c682-2b8a-506f-a3e1-155ad682d763

package/dist/core/output/mutation-projection.js

@@ -19,7 +19,7 @@
  * MCP server, and returns the original reference unchanged when nothing is compacted.
  */
 
-!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]="a3e0573a-01fd-54fb-a568-51c5287b696c")}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]="d6a389b0-7a14-56e7-ac2c-17fcdecc7b29")}catch(e){}}();
 const CHANGED_FIELDS_KEY = "changed_fields";
 const CHANGED_FIELD_COUNT_KEY = "changed_field_count";
 const ROWS_KEY = "rows";
@@ -115,6 +115,7 @@ function projectIdOnlyResult(result) {
         }
         : { id };
 }
+/** Project a recognized item mutation to identity and change counts while preserving warnings and executable recovery. */
 function projectCompactMutationEnvelope(result) {
     if (!isPlainObject(result) || !isPlainObject(result.item))
         return null;
@@ -137,10 +138,15 @@ function projectCompactMutationEnvelope(result) {
             : {}),
         changed_field_count: changedFields.length,
     };
+    appendCompactMutationEvidence(result, result.item, compact);
+    return compact;
+}
+/** Keep lifecycle context, warnings, and executable recovery alongside the compact identity. */
+function appendCompactMutationEvidence(result, item, compact) {
     const closeReason = typeof result.close_reason === "string"
         ? result.close_reason
-        : typeof result.item.close_reason === "string"
-            ? result.item.close_reason
+        : typeof item.close_reason === "string"
+            ? item.close_reason
             : undefined;
     if (closeReason !== undefined)
         compact.close_reason = closeReason;
@@ -149,7 +155,8 @@ function projectCompactMutationEnvelope(result) {
         compact.recurrence = recurrence;
     if (Array.isArray(result.warnings) && result.warnings.length > 0)
         compact.warnings = result.warnings;
-    return compact;
+    if (isPlainObject(result.recovery))
+        compact.recovery = result.recovery;
 }
 function compactUpdateManyRows(envelope) {
     const rows = isUpdateManyMutationEnvelope(envelope)
@@ -208,4 +215,4 @@ export function projectMutationResult(result, options = {}) {
     return changed ? projected : result;
 }
 //# sourceMappingURL=mutation-projection.js.map
-//# debugId=a3e0573a-01fd-54fb-a568-51c5287b696c
+//# debugId=d6a389b0-7a14-56e7-ac2c-17fcdecc7b29

package/dist/core/store/item-metadata-query-index.js

@@ -4,13 +4,13 @@
  * Maintains a rebuildable SQLite projection for bounded metadata queries.
  */
 
-!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]="97cfeab2-8e3f-5b70-9f64-10494158d141")}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]="530ad63f-f7c5-52c9-9f81-a74b1cd4c36e")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
 import { createRequire } from "node:module";
 const QUERY_INDEX_FILENAME = "metadata-query-index.sqlite";
-const QUERY_INDEX_VERSION = "4";
+const QUERY_INDEX_VERSION = "5";
 function loadDatabaseSync(loadModule) {
     try {
         const loaded = loadModule(["node", "sqlite"].join(":"));
@@ -102,6 +102,7 @@ function writeMetadata(database, key, value) {
         .prepare("INSERT INTO metadata(key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value")
         .run(key, value);
 }
+/** Upsert authoritative metadata and replace dependent search, key and linked-file rows in the caller transaction. */
 function insertRow(database, row) {
     const metadata = row.metadata;
     database
@@ -128,10 +129,12 @@ function insertRow(database, row) {
     database
         .prepare("DELETE FROM item_linked_files WHERE item_id = ?")
         .run(metadata.id);
-    database.prepare("DELETE FROM item_search WHERE id = ?").run(metadata.id);
+    // FTS UNINDEXED columns cannot provide identity lookup. Share the items rowid
+    // so both rebuilding and incremental maintenance use a single indexed row.
+    database.prepare("DELETE FROM item_search WHERE rowid = (SELECT rowid FROM items WHERE id = ?)").run(metadata.id);
     database
-        .prepare("INSERT INTO item_search(id, title, description, tags) VALUES (?, ?, ?, ?)")
-        .run(metadata.id, metadata.title, metadata.description, metadata.tags.join(" "));
+        .prepare("INSERT INTO item_search(rowid, id, title, description, tags) SELECT rowid, ?, ?, ?, ? FROM items WHERE id = ?")
+        .run(metadata.id, metadata.title, metadata.description, metadata.tags.join(" "), metadata.id);
     const insertMetadataKey = database.prepare("INSERT INTO item_metadata_keys(item_id, key) VALUES (?, ?)");
     for (const key of Object.keys(metadata)) {
         insertMetadataKey.run(metadata.id, key);
@@ -203,13 +206,13 @@ export async function updateItemMetadataQueryIndex(options) {
         }
         database.exec("BEGIN IMMEDIATE");
         const deleteByPath = database.prepare("DELETE FROM items WHERE relative_path = ?");
-        const findIdByPath = database.prepare("SELECT id FROM items WHERE relative_path = ?");
-        const deleteSearchById = database.prepare("DELETE FROM item_search WHERE id = ?");
+        const findRowidByPath = database.prepare("SELECT rowid FROM items WHERE relative_path = ?");
+        const deleteSearchByRowid = database.prepare("DELETE FROM item_search WHERE rowid = ?");
         for (const relativePath of options.deletedRelativePaths ?? []) {
-            const deleted = findIdByPath.get(relativePath);
+            const deleted = findRowidByPath.get(relativePath);
             deleteByPath.run(relativePath);
             if (deleted)
-                deleteSearchById.run(deleted.id);
+                deleteSearchByRowid.run(deleted.rowid);
         }
         if (options.row)
             insertRow(database, options.row);
@@ -470,4 +473,4 @@ export const _testOnly = {
     },
 };
 //# sourceMappingURL=item-metadata-query-index.js.map
-//# debugId=97cfeab2-8e3f-5b70-9f64-10494158d141
+//# debugId=530ad63f-f7c5-52c9-9f81-a74b1cd4c36e

package/dist/core/store/item-metadata-read-work.d.ts

@@ -0,0 +1,19 @@
+/** Logical metadata work, independent of output projection and cache hit rate. */
+export interface ItemMetadataReadWork {
+    /** Completed full, light, or body-bearing item-store enumeration calls. */
+    enumeration_calls: number;
+    /** Metadata rows returned by those calls, counting repeated enumeration. */
+    metadata_rows: number;
+}
+/** Record completed enumeration in each enclosing measurement, without retaining item data. */
+export declare function recordItemMetadataEnumeration(rowCount: number): void;
+/**
+ * Measure an awaited operation without changing its result or failure semantics.
+ * Concurrent roots remain isolated; nested measurements also contribute to their
+ * parents. The returned snapshot excludes work completed after the operation.
+ * Counters cover filesystem item-store enumeration APIs, not arbitrary host I/O.
+ */
+export declare function measureItemMetadataReadWork<T>(operation: () => T | Promise<T>): Promise<{
+    result: T;
+    work: Readonly<ItemMetadataReadWork>;
+}>;

package/dist/core/store/item-metadata-read-work.js

@@ -0,0 +1,44 @@
+/**
+ * @module core/store/item-metadata-read-work
+ *
+ * Measures successful filesystem metadata enumerations within one async SDK
+ * operation. Cache hits count too: materializing a cached corpus is still work.
+ */
+
+!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]="1cd39e2f-41c7-5005-925d-d4539cda15d3")}catch(e){}}();
+import { AsyncLocalStorage } from "node:async_hooks";
+import { channel } from "node:diagnostics_channel";
+const observers = new AsyncLocalStorage();
+const enumerations = channel("@unbrained/pm-cli/item-metadata-enumeration/v1");
+/** Record completed enumeration in each enclosing measurement, without retaining item data. */
+export function recordItemMetadataEnumeration(rowCount) {
+    enumerations.publish(rowCount);
+}
+/**
+ * Measure an awaited operation without changing its result or failure semantics.
+ * Concurrent roots remain isolated; nested measurements also contribute to their
+ * parents. The returned snapshot excludes work completed after the operation.
+ * Counters cover filesystem item-store enumeration APIs, not arbitrary host I/O.
+ */
+export async function measureItemMetadataReadWork(operation) {
+    const work = { enumeration_calls: 0, metadata_rows: 0 };
+    // A named channel crosses the published query/bundled runtime boundary;
+    // async membership prevents concurrent roots from counting each other's work.
+    /** Count notifications only while this measurement belongs to the active async scope. */
+    const observe = (message) => {
+        if (observers.getStore()?.includes(work)) {
+            work.enumeration_calls += 1;
+            work.metadata_rows += message;
+        }
+    };
+    enumerations.subscribe(observe);
+    try {
+        const result = await observers.run([...(observers.getStore() ?? []), work], operation);
+        return { result, work: { ...work } };
+    }
+    finally {
+        enumerations.unsubscribe(observe);
+    }
+}
+//# sourceMappingURL=item-metadata-read-work.js.map
+//# debugId=1cd39e2f-41c7-5005-925d-d4539cda15d3

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

@@ -4,8 +4,9 @@
  * 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]="c3390c01-c153-5baa-b9bd-07ea8d34828f")}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]="7cbc256e-cdd8-51de-9c22-08cf2f3cd010")}catch(e){}}();
 import fs from "node:fs/promises";
+import { recordItemMetadataEnumeration } from "./item-metadata-read-work.js";
 import path from "node:path";
 import { getActiveExtensionRegistrations, projectAfterCommandItemSnapshot, recordAfterCommandAffectedItem, runActiveOnReadHooks, runActiveBeforeMutationHooks, runActiveOnWriteHooks, runActiveServiceOverride, } from "../extensions/index.js";
 import { collectRegisteredItemFieldNames } from "../extensions/item-fields.js";
@@ -151,6 +152,7 @@ export async function readLocatedItemSnapshot(item, options = {}) {
 export async function listAllItemMetadata(pmRoot, preferredFormat, typeToFolder = TYPE_TO_FOLDER, warnings, schema) {
     await assertReadableTrackerRoot(pmRoot);
     const documents = await listAllDocumentsCached(pmRoot, preferredFormat, typeToFolder, warnings, schema);
+    recordItemMetadataEnumeration(documents.length);
     return documents.map((document) => document.metadata);
 }
 /**
@@ -162,6 +164,7 @@ export async function listAllItemMetadata(pmRoot, preferredFormat, typeToFolder
 export async function listAllItemMetadataLight(pmRoot, preferredFormat, typeToFolder = TYPE_TO_FOLDER, warnings, schema) {
     await assertReadableTrackerRoot(pmRoot);
     const documents = await listAllDocumentsCachedLight(pmRoot, preferredFormat, typeToFolder, warnings, schema);
+    recordItemMetadataEnumeration(documents.length);
     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. */
@@ -171,6 +174,7 @@ export async function listAllItemMetadataWithBody(pmRoot, preferredFormat, typeT
         includeBody: true,
         forceSourceScan: options.forceSourceScan,
     });
+    recordItemMetadataEnumeration(candidates.length);
     return candidates.map((candidate) => ({
         ...candidate.metadata,
         // includeBody:true guarantees candidate bodies are materialized.
@@ -687,4 +691,4 @@ export async function deleteItem(params) {
     }
 }
 //# sourceMappingURL=item-store.js.map
-//# debugId=c3390c01-c153-5baa-b9bd-07ea8d34828f
+//# debugId=7cbc256e-cdd8-51de-9c22-08cf2f3cd010

package/dist/core/validate/fix-planning.d.ts

@@ -97,7 +97,7 @@ export interface StaleLinkPruneRow {
     /** Value that configures or reports link kind for this contract. */
     link_kind: "files" | "docs";
     /** Value that configures or reports classification for this contract. */
-    classification: "moved" | "deleted";
+    classification: "moved" | "deleted" | "malformed";
 }
 /** Plan link prunes for `--prune-missing` (pm-0v2m / GH-184). Only links whose stale path classified as `deleted` are pruned; `moved` links keep their relink candidates in the files-check details instead of being dropped, so recoverable link information is never destroyed. Link removal only — real files are never touched. */
 export declare function planStaleLinkPruneFixes(rows: readonly StaleLinkPruneRow[]): ValidateFixRecord[];

package/dist/core/validate/fix-planning.js

@@ -16,7 +16,7 @@
  *   explicitly granted.
  */
 
-!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]="ab236f47-a866-5236-b8da-f7f23140b978")}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]="98a73818-c4ef-5bce-8b23-6c40f7312cc3")}catch(e){}}();
 import { EXIT_CODE } from "../shared/constants.js";
 import { PmCliError } from "../shared/errors.js";
 import { resolveEstimateDefaultMinutes } from "./estimate-defaults.js";
@@ -187,4 +187,4 @@ export function toFixOutputRow(fix) {
     };
 }
 //# sourceMappingURL=fix-planning.js.map
-//# debugId=ab236f47-a866-5236-b8da-f7f23140b978
+//# debugId=98a73818-c4ef-5bce-8b23-6c40f7312cc3

package/dist/core/validate/missing-link-owners.d.ts

@@ -13,7 +13,7 @@
  * the already-collected stale-link rows plus a metadata `lookup` closure.
  */
 /** Classification assigned to a stale linked path during files validation. */
-export type StaleLinkClassification = "moved" | "deleted";
+export type StaleLinkClassification = "moved" | "deleted" | "malformed";
 /** Documents the stale link owner input payload exchanged by command, SDK, and package integrations. */
 export interface StaleLinkOwnerInput {
     /** Value that configures or reports item id for this contract. */

package/dist/core/validate/missing-link-owners.js

@@ -12,10 +12,12 @@
  * Pure module (GH-210): no filesystem access and no heavy imports — callers pass
  * the already-collected stale-link rows plus a metadata `lookup` closure.
  */
-/** `moved` wins over `deleted` when a single path's rows disagree on classification: `moved` means a relink candidate exists, which is the safer, more-actionable signal (relink instead of risk pruning a still-reachable link). In practice all rows for one path share a classification; this is a deterministic tie-break for the degenerate case. */
+/** `malformed` wins over other classifications to prevent unsafe automatic repair. Otherwise `moved` wins over `deleted` when a single path's rows disagree on classification: `moved` means a relink candidate exists, which is the safer, more-actionable signal (relink instead of risk pruning a still-reachable link). In practice all rows for one path share a classification; this is a deterministic tie-break for the degenerate case. */
 
-!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]="e063d634-4306-5725-927a-5f2af1722458")}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]="1a4f19cf-56ba-571a-908c-97278a8284f7")}catch(e){}}();
 function preferClassification(current, next) {
+    if (current === "malformed" || next === "malformed")
+        return "malformed";
     return current === "moved" || next === "moved" ? "moved" : "deleted";
 }
 function ownerKey(input) {
@@ -91,4 +93,4 @@ export function summarizeMissingLinkedPathRows(rows) {
     return lines;
 }
 //# sourceMappingURL=missing-link-owners.js.map
-//# debugId=e063d634-4306-5725-927a-5f2af1722458
+//# debugId=1a4f19cf-56ba-571a-908c-97278a8284f7

package/dist/core/validate/stale-file-classification.d.ts

@@ -6,27 +6,29 @@
  *   scanned candidate set — the candidates are reported so an agent can relink
  *   the item to the new location instead of dropping the link, or
  * - `deleted`: no candidate with that basename exists anywhere in the scan,
- *   so the link points at content that is gone and pruning it is safe.
+ *   making it eligible for an explicitly requested prune, or
+ * - `malformed`: an ambiguous missing CSV or path:note literal which must be
+ *   reviewed before any relocation or removal is inferred.
  *
  * Pure module (pm-0v2m / GH-184): no filesystem access — callers pass the
  * already-collected candidate file list from the files check scan.
  */
 /** Classification labels for linked paths that no longer exist on disk. */
-export type StaleLinkedPathClassification = "moved" | "deleted";
+export type StaleLinkedPathClassification = "moved" | "deleted" | "malformed";
 /** Documents the classified stale linked path payload exchanged by command, SDK, and package integrations. */
 export interface ClassifiedStaleLinkedPath {
     /** Normalized workspace-relative stale linked path. */
     path: string;
     /** Value that configures or reports classification for this contract. */
     classification: StaleLinkedPathClassification;
-    /** Candidate new locations (same basename, different path), sorted and capped at `candidateLimit`. Empty for `deleted`. */
+    /** Candidate new locations (same basename, different path), sorted and capped at `candidateLimit`. Empty for `deleted` and `malformed`. */
     candidates: string[];
     /** True when more candidates existed than `candidateLimit` allowed. */
     candidates_truncated: boolean;
 }
 /** Fallback stale path candidate limit used when callers do not provide an override. */
 export declare const DEFAULT_STALE_PATH_CANDIDATE_LIMIT = 3;
-/** Classify each stale (missing) linked path as `moved` or `deleted` by matching its basename against the candidate file list. Output preserves the input order of `stalePaths` (callers pass an already-sorted unique list). A candidate equal to the stale path itself never matches (the path is known missing; an identical candidate would be self-referential noise). */
+/** Classify each stale (missing) linked path as `moved`, `deleted`, or `malformed` by matching its basename against the candidate file list. Output preserves the input order of `stalePaths` (callers pass an already-sorted unique list). A candidate equal to the stale path itself never matches (the path is known missing; an identical candidate would be self-referential noise). */
 export declare function classifyStaleLinkedPaths(stalePaths: readonly string[], candidateFiles: readonly string[], candidateLimit?: number): ClassifiedStaleLinkedPath[];
 /** Render compact `<path>:moved:<top-candidate>` / `<path>:deleted` rows for the files check details (token-efficient counterpart to the full classification objects). */
 export declare function summarizeStaleLinkedPathClassifications(classified: readonly ClassifiedStaleLinkedPath[]): string[];

package/dist/core/validate/stale-file-classification.js

@@ -6,20 +6,23 @@
  *   scanned candidate set — the candidates are reported so an agent can relink
  *   the item to the new location instead of dropping the link, or
  * - `deleted`: no candidate with that basename exists anywhere in the scan,
- *   so the link points at content that is gone and pruning it is safe.
+ *   making it eligible for an explicitly requested prune, or
+ * - `malformed`: an ambiguous missing CSV or path:note literal which must be
+ *   reviewed before any relocation or removal is inferred.
  *
  * Pure module (pm-0v2m / GH-184): no filesystem access — callers pass the
  * already-collected candidate file list from the files check scan.
  */
 /** Fallback stale path candidate limit used when callers do not provide an override. */
 
-!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]="5a5b0bd8-d99b-52fb-82ae-52ba48c54c30")}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]="eb4fe9bd-31b5-5ed3-b401-3e3776ec12e9")}catch(e){}}();
 export const DEFAULT_STALE_PATH_CANDIDATE_LIMIT = 3;
+/** Extract a basename from either portable separator convention. */
 function basenameOf(relativePath) {
     const lastSlash = Math.max(relativePath.lastIndexOf("/"), relativePath.lastIndexOf("\\"));
     return lastSlash === -1 ? relativePath : relativePath.slice(lastSlash + 1);
 }
-/** Classify each stale (missing) linked path as `moved` or `deleted` by matching its basename against the candidate file list. Output preserves the input order of `stalePaths` (callers pass an already-sorted unique list). A candidate equal to the stale path itself never matches (the path is known missing; an identical candidate would be self-referential noise). */
+/** Classify each stale (missing) linked path as `moved`, `deleted`, or `malformed` by matching its basename against the candidate file list. Output preserves the input order of `stalePaths` (callers pass an already-sorted unique list). A candidate equal to the stale path itself never matches (the path is known missing; an identical candidate would be self-referential noise). */
 export function classifyStaleLinkedPaths(stalePaths, candidateFiles, candidateLimit = DEFAULT_STALE_PATH_CANDIDATE_LIMIT) {
     const limit = Number.isFinite(candidateLimit) && candidateLimit >= 1
         ? Math.floor(candidateLimit)
@@ -39,6 +42,18 @@ export function classifyStaleLinkedPaths(stalePaths, candidateFiles, candidateLi
         }
     }
     return stalePaths.map((stalePath) => {
+        // Historical CSV and path:note input must not become a confident basename
+        // relocation. Existing files are checked before classification; this only
+        // rejects ambiguous missing references, never an existing literal filename.
+        if (stalePath.includes(",") ||
+            stalePath.replace(/^[a-z]:[\\/]/i, "").includes(":")) {
+            return {
+                path: stalePath,
+                classification: "malformed",
+                candidates: [],
+                candidates_truncated: false,
+            };
+        }
         const matches = (candidatesByBasename.get(basenameOf(stalePath)) ?? [])
             .filter((candidate) => candidate !== stalePath)
             .sort((left, right) => left.localeCompare(right));
@@ -62,7 +77,7 @@ export function classifyStaleLinkedPaths(stalePaths, candidateFiles, candidateLi
 export function summarizeStaleLinkedPathClassifications(classified) {
     return classified.map((entry) => entry.classification === "moved"
         ? `${entry.path}:moved:${entry.candidates[0]}`
-        : `${entry.path}:deleted`);
+        : `${entry.path}:${entry.classification}`);
 }
 //# sourceMappingURL=stale-file-classification.js.map
-//# debugId=5a5b0bd8-d99b-52fb-82ae-52ba48c54c30
+//# debugId=eb4fe9bd-31b5-5ed3-b401-3e3776ec12e9

package/dist/mcp/server.js

@@ -5,7 +5,7 @@
  * Runs the MCP server adapter that exposes pm actions and contracts to external agents.
  */
 
-!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]="71cfdc6b-c990-51b6-a9ae-ed9bf98136f7")}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]="1950da06-8c27-5506-bc64-4bf51c1a3f1c")}catch(e){}}();
 import { realpathSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
@@ -410,11 +410,13 @@ async function emitMcpChangeNotifications(action) {
     }
     pruneClosedMcpSubscriptionRegistries();
 }
+/** Resolve one tool's workspace and scope SDK attribution to that request without changing process environment. */
 async function handleToolCall(paramsInput, clientInfo, progressiveDiscoveryNegotiated = false) {
+    const clientSignals = clientInfo ? { client_info: clientInfo } : {};
     return runWithHarnessDetectionSignals({
         env: process.env,
         argv: process.argv,
-        ...(clientInfo ? { client_info: clientInfo } : {}),
+        ...clientSignals,
     }, async () => {
         const params = asRecordClone(paramsInput);
         const name = readRequiredString(params, "name");
@@ -454,7 +456,12 @@ async function handleToolCall(paramsInput, clientInfo, progressiveDiscoveryNegot
         const workspaceIdentity = (await pathExists(getSettingsPath(pmRoot)))
             ? (await readSettings(pmRoot)).agent_identity
             : undefined;
-        return runWithWorkspaceHarnessSignalDescriptors(workspaceIdentity?.harness_signals ?? [], async () => {
+        return runWithHarnessDetectionSignals({
+            env: { ...process.env, PM_PATH: pmRoot },
+            argv: process.argv,
+            cwd,
+            ...clientSignals,
+        }, () => runWithWorkspaceHarnessSignalDescriptors(workspaceIdentity?.harness_signals ?? [], async () => {
             // pm-qxwu: non-breaking detection of typo'd / unexpected top-level keys.
             // additionalProperties stays true so passthrough still works; we only warn.
             // pm-upi0 extends the same mechanism into the nested options object.
@@ -472,7 +479,7 @@ async function handleToolCall(paramsInput, clientInfo, progressiveDiscoveryNegot
             const result = await handler(args);
             void emitMcpChangeNotifications(action);
             return resultContent(result, warnings, args.tokenAccounting === true, progressiveDiscoveryNegotiated);
-        }, { probesEnabled: workspaceIdentity?.probes_enabled });
+        }, { probesEnabled: workspaceIdentity?.probes_enabled }));
     });
 }
 /** Open one modern subscription through a concrete transport-owned sink. */
@@ -1225,4 +1232,4 @@ if (isInvokedAsMcpMainModule(process.argv[1], import.meta.url)) {
 }
 /* c8 ignore stop */
 //# sourceMappingURL=server.js.map
-//# debugId=71cfdc6b-c990-51b6-a9ae-ed9bf98136f7
+//# debugId=1950da06-8c27-5506-bc64-4bf51c1a3f1c

package/dist/sdk/cli-contracts/flag-contracts.d.ts

@@ -21,6 +21,8 @@ export interface CliFlagContract {
     value_type?: "string" | "number" | "boolean";
     /** Marks a presentation-only flag that may change paging or rendering without invalidating continuation. Omission means the flag is query-semantic. */
     cursor_semantics?: "presentation";
+    /** Host reservation boundary: inherited flags are forbidden on extensions; root-only flags may have command-local meanings. */
+    reservation_scope?: "inherited" | "root_only";
 }
 /** Maps an MCP tool option `param` to the CLI `flag` it forwards to, plus the value semantics (`allowEmpty`, `repeatable`, `booleanish`) the bridge needs to translate a structured tool call into argv. */
 export interface ToolOptionFlagContract {