@unbrained/pm-cli 2026.9.4 → 2026.9.6

package/dist/sdk/context-usage.js

@@ -4,18 +4,16 @@
  * Privacy-minimal, derived context-usage feedback primitives. The JSONL ledger
  * contains only item ids, timestamps, authors, ranks, profiles, and command
  * intents; it never enters item history and is safe to delete or rebuild.
+ * Persistence requires trusted, stable workspace directory entries and
+ * ancestors. For a workspace writable by an untrusted concurrent actor, set
+ * PM_CONTEXT_USAGE_DISABLED=1 or use an isolated copy owned by the caller.
  */
 
-!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]="997a09a2-cf0c-5384-b457-d9627d465b71")}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]="b1b1aa19-b1de-5140-8aea-ee1994ee9ecd")}catch(e){}}();
 import { randomUUID } from "node:crypto";
-import { appendFile, mkdir, readFile, rename, stat, writeFile, } from "node:fs/promises";
-import path from "node:path";
-import { acquireLock } from "../core/lock/lock.js";
-const DEFAULT_MAX_EVENTS = 2_048;
-const DEFAULT_RETENTION_DAYS = 30;
+import { appendEvents, readEvents, resolveNow, ContextUsageValidationError, CONTEXT_USAGE_LIMITS, } from "./context/usage-ledger.js";
+export { ContextUsageValidationError, CONTEXT_USAGE_LIMITS } from "./context/usage-ledger.js";
 const DAY_MS = 86_400_000;
-const DEFAULT_COMPACTION_BYTES = 262_144;
-const CONTEXT_USAGE_LOCK_ID = "context-usage-ledger";
 const CONTEXT_USAGE_SERVING_RECEIPT = Symbol.for("@unbrained/pm-cli/context-usage-serving-receipt");
 function asObjectRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value)
@@ -69,15 +67,13 @@ function addContextUsageIdList(ids, value) {
         addContextUsageId(ids, itemId);
 }
 function collectNextResultItemIds(record, ids) {
-    const rows = [
-        ...(asObjectRecord(record.recommended) === null
-            ? []
-            : [record.recommended]),
-        ...(Array.isArray(record.ready) ? record.ready : []),
-        ...(Array.isArray(record.decision_needed) ? record.decision_needed : []),
-        ...(Array.isArray(record.blocked) ? record.blocked : []),
-        ...(Array.isArray(record.held_by_others) ? record.held_by_others : []),
-    ];
+    const rows = asObjectRecord(record.recommended) === null
+        ? []
+        : [record.recommended];
+    for (const key of ["ready", "decision_needed", "gate_needed", "containers", "blocked", "held_by_others"]) {
+        if (Array.isArray(record[key]))
+            rows.push(...record[key]);
+    }
     for (const value of rows) {
         const row = asObjectRecord(value);
         addContextUsageId(ids, row?.id);
@@ -164,86 +160,7 @@ export async function finalizeContextUsageDelivery(options) {
     });
     return true;
 }
-/** Named validation failure emitted by context-usage SDK inputs. */
-export class ContextUsageValidationError extends TypeError {
-    /** Stable machine-readable error code for package and CLI hosts. */
-    code = "context_usage_validation_failed";
-    /** Creates a typed validation error without exposing derived ledger contents. */
-    constructor(message) {
-        super(message);
-        this.name = "ContextUsageValidationError";
-    }
-}
-function ledgerPath(pmRoot) {
-    return path.join(pmRoot, "runtime", "context-usage.jsonl");
-}
-function resolveNow(options) {
-    const iso = options.now ?? new Date().toISOString();
-    const ms = Date.parse(iso);
-    if (!Number.isFinite(ms))
-        throw new ContextUsageValidationError("Context usage now must be a valid timestamp");
-    return { iso: new Date(ms).toISOString(), ms };
-}
-async function readEvents(options) {
-    try {
-        const text = await readFile(ledgerPath(options.pmRoot), "utf8");
-        const events = text
-            .split("\n")
-            .filter(Boolean)
-            .flatMap((line) => {
-            try {
-                return [JSON.parse(line)];
-            }
-            catch {
-                return [];
-            }
-        });
-        const maxEvents = options.maxEvents ?? DEFAULT_MAX_EVENTS;
-        const retentionDays = options.retentionDays ?? DEFAULT_RETENTION_DAYS;
-        const cutoff = resolveNow(options).ms - retentionDays * DAY_MS;
-        return events
-            .filter((entry) => Date.parse(entry.at) >= cutoff)
-            .slice(-maxEvents);
-    }
-    catch {
-        return [];
-    }
-}
-async function appendEvents(options, events, deliveryServeId) {
-    const maxEvents = options.maxEvents ?? DEFAULT_MAX_EVENTS;
-    const retentionDays = options.retentionDays ?? DEFAULT_RETENTION_DAYS;
-    if (!Number.isInteger(maxEvents) ||
-        maxEvents < 1 ||
-        !Number.isFinite(retentionDays) ||
-        retentionDays <= 0) {
-        throw new ContextUsageValidationError("Context usage retention requires positive maxEvents and retentionDays");
-    }
-    const target = ledgerPath(options.pmRoot);
-    const runtimeDirectory = path.dirname(target);
-    const releaseLock = await acquireLock(options.pmRoot, CONTEXT_USAGE_LOCK_ID, 30, `context-usage:${process.pid}`, false, false, 3_000);
-    try {
-        await mkdir(runtimeDirectory, { recursive: true });
-        if (deliveryServeId !== undefined &&
-            (await readEvents(options)).some((event) => event.kind === "delivery" && event.serve_id === deliveryServeId)) {
-            return;
-        }
-        await appendFile(target, events.map((event) => `${JSON.stringify(event)}\n`).join(""), "utf8");
-        const customBounds = options.maxEvents !== undefined || options.retentionDays !== undefined;
-        if (!customBounds && (await stat(target)).size <= DEFAULT_COMPACTION_BYTES)
-            return;
-        const retained = await readEvents(options);
-        const temporary = `${target}.${process.pid}.${randomUUID()}.tmp`;
-        await writeFile(temporary, `${retained.map((entry) => JSON.stringify(entry)).join("\n")}\n`, "utf8");
-        await rename(temporary, target);
-    }
-    finally {
-        await releaseLock();
-    }
-}
-async function appendEvent(options, event) {
-    await appendEvents(options, [event]);
-}
-/** Records a propensity-complete context/next serving event. */
+/** Records a bounded prefix of ranked context candidates with explicit sampling counts. */
 export async function recordContextUsageServing(options) {
     if ([
         process.env.PM_CONTEXT_USAGE_DISABLED === "1",
@@ -255,32 +172,37 @@ export async function recordContextUsageServing(options) {
         throw new ContextUsageValidationError("Context usage serving requires an author and valid ranked rows");
     }
     const normalizedRows = options.rows.map((row) => ({
-        ...row,
         id: row.id.trim(),
+        rank: row.rank,
+        included: row.included,
     }));
     if (new Set(normalizedRows.map((row) => row.id)).size !== normalizedRows.length) {
         throw new ContextUsageValidationError("Context usage serving requires unique normalized row ids");
     }
+    const recordedRows = normalizedRows.slice(0, CONTEXT_USAGE_LIMITS.max_serving_rows);
     const receipt = {
         serve_id: randomUUID(),
         author: options.author.trim(),
         surface: options.surface,
         rows: normalizedRows,
+        recorded_item_ids: recordedRows.map((row) => row.id),
     };
-    await appendEvent(options, {
-        kind: "serve",
-        schema_version: 2,
-        serve_id: receipt.serve_id,
-        at: resolveNow(options).iso,
-        author: options.author.trim(),
-        surface: options.surface,
-        profile: options.profile.trim() || "balanced",
-        rows: receipt.rows.map((row) => ({ ...row })),
-        result_omitted: false,
-        packed_item_ids: receipt.rows
-            .filter((row) => row.included)
-            .map((row) => row.id),
-    });
+    receipt.storage = await appendEvents(options, [{
+            kind: "serve",
+            schema_version: 2,
+            serve_id: receipt.serve_id,
+            at: resolveNow(options).iso,
+            author: options.author.trim(),
+            surface: options.surface,
+            profile: options.profile.trim() || "balanced",
+            rows: recordedRows,
+            candidate_count: normalizedRows.length,
+            omitted_row_count: normalizedRows.length - recordedRows.length,
+            result_omitted: false,
+            packed_item_ids: recordedRows
+                .filter((row) => row.included)
+                .map((row) => row.id),
+        }]);
     return receipt;
 }
 /** Append the exact post-egress delivery decision for one serving receipt. */
@@ -298,6 +220,7 @@ export async function recordContextUsageDelivery(options) {
         (options.resultOmitted && deliveredItemIds.length > 0)) {
         throw new ContextUsageValidationError("Context usage delivery requires emitted ranked ids and zero ids for an omitted result");
     }
+    const recordedIds = new Set(options.receipt.recorded_item_ids ?? options.receipt.rows.map((row) => row.id));
     const delivery = {
         kind: "delivery",
         schema_version: 2,
@@ -306,7 +229,7 @@ export async function recordContextUsageDelivery(options) {
         author: options.receipt.author,
         surface: options.receipt.surface,
         result_omitted: options.resultOmitted,
-        delivered_item_ids: deliveredItemIds,
+        delivered_item_ids: deliveredItemIds.filter((id) => recordedIds.has(id)),
     };
     await appendEvents(options, [delivery], delivery.serve_id);
 }
@@ -320,13 +243,13 @@ export async function recordContextUsageTouch(options) {
         !options.intent.trim()) {
         throw new ContextUsageValidationError("Context usage touch requires author, itemId, and intent");
     }
-    await appendEvent(options, {
-        kind: "touch",
-        at: resolveNow(options).iso,
-        author: options.author.trim(),
-        item_id: options.itemId.trim(),
-        intent: options.intent.trim(),
-    });
+    await appendEvents(options, [{
+            kind: "touch",
+            at: resolveNow(options).iso,
+            author: options.author.trim(),
+            item_id: options.itemId.trim(),
+            intent: options.intent.trim(),
+        }]);
 }
 /**
  * Records mutation outcomes as one append and one optional compaction pass.
@@ -442,4 +365,4 @@ export async function readContextUsageAffinity(options) {
     };
 }
 //# sourceMappingURL=context-usage.js.map
-//# debugId=997a09a2-cf0c-5384-b457-d9627d465b71
+//# debugId=b1b1aa19-b1de-5140-8aea-ee1994ee9ecd

package/dist/sdk/define.d.ts

@@ -37,7 +37,7 @@ import type { ProjectProfileDefinition } from "../core/profile/profile-presets.j
 type ExactDefinition<TDefinition, TContract> = TDefinition & Record<Exclude<keyof TDefinition, keyof TContract>, never>;
 type FlagAuthoringDefinition = Pick<FlagDefinition, "long" | "short" | "value_name" | "description" | "required" | "enabled" | "visible" | "value_type" | "type" | "list" | "default">;
 type ItemFieldAuthoringDefinition = Pick<SchemaFieldDefinition, "name" | "type" | "optional" | "default" | "values">;
-type ItemTypeAuthoringDefinition = Pick<SchemaItemTypeDefinition, "name" | "folder" | "aliases" | "required_create_fields" | "required_create_repeatables" | "command_option_policies" | "options" | "description" | "default_status">;
+type ItemTypeAuthoringDefinition = Pick<SchemaItemTypeDefinition, "name" | "folder" | "aliases" | "required_create_fields" | "required_create_repeatables" | "command_option_policies" | "options" | "description" | "default_status" | "execution_role">;
 type MigrationAuthoringDefinition = Pick<SchemaMigrationDefinition, "id" | "description" | "status" | "mandatory" | "run">;
 type SearchProviderAuthoringDefinition = Pick<SearchProviderDefinition, "name" | "query" | "queryExpansion" | "query_expansion" | "rerank" | "embedBatch" | "embed_batch" | "embed">;
 type VectorStoreAdapterAuthoringDefinition = Pick<VectorStoreAdapterDefinition, "name" | "query" | "upsert" | "delete">;

package/dist/sdk/define.js

@@ -9,7 +9,7 @@
  * to keep `capabilities` matched to the surfaces the extension actually registers.
  */
 
-!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]="7fc669d4-1db2-5636-8304-2c111a684726")}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]="e37a2da9-966f-5044-bc5e-d27ddb07e65b")}catch(e){}}();
 export function defineExtensionManifest(manifest) {
     return manifest;
 }
@@ -218,4 +218,4 @@ export function defineOnIndexHook(hook) {
     return hook;
 }
 //# sourceMappingURL=define.js.map
-//# debugId=7fc669d4-1db2-5636-8304-2c111a684726
+//# debugId=e37a2da9-966f-5044-bc5e-d27ddb07e65b

package/dist/sdk/dependency-provenance.d.ts

@@ -61,3 +61,10 @@ export declare function normalizeDependencySourceKind(sourceKind: string | undef
  * global seeds preserve the caller-provided id verbatim (apart from trimming).
  */
 export declare function normalizeDependencySeedId(id: string, prefix: string, sourceKind: string | undefined): string;
+/**
+ * Canonicalize a local relationship target using the workspace prefix. Explicit
+ * provider locators and externally sourced identities retain case and spelling;
+ * only surrounding whitespace is removed. Resolution and parent policy remain
+ * the caller's responsibility, so dangling local ids are never guessed remote.
+ */
+export declare function normalizeItemReference(reference: string, prefix: string, sourceKind?: string): string;

package/dist/sdk/dependency-provenance.js

@@ -5,7 +5,7 @@
  * items outside the current workspace.
  */
 
-!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]="f3f3beb2-1d60-52fe-88ce-1ab3cb9dba0d")}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]="ee17fdea-aeac-55b0-8302-a8740ba8428e")}catch(e){}}();
 import { normalizeItemId } from "../core/item/id.js";
 import { isExternalDependencyReference, isExternalDependencySourceKind, } from "../core/item/dependency-reference.js";
 export { isExternalDependencyReference, isExternalDependencySourceKind, } from "../core/item/dependency-reference.js";
@@ -117,10 +117,20 @@ export function normalizeDependencySourceKind(sourceKind) {
  * global seeds preserve the caller-provided id verbatim (apart from trimming).
  */
 export function normalizeDependencySeedId(id, prefix, sourceKind) {
-    const trimmed = id.trim();
-    return isExternalDependencySourceKind(sourceKind)
+    return normalizeItemReference(id, prefix, sourceKind);
+}
+/**
+ * Canonicalize a local relationship target using the workspace prefix. Explicit
+ * provider locators and externally sourced identities retain case and spelling;
+ * only surrounding whitespace is removed. Resolution and parent policy remain
+ * the caller's responsibility, so dangling local ids are never guessed remote.
+ */
+export function normalizeItemReference(reference, prefix, sourceKind) {
+    const trimmed = reference.trim();
+    return isExternalDependencySourceKind(sourceKind) ||
+        isExternalDependencyReference(trimmed)
         ? trimmed
         : normalizeItemId(trimmed, prefix);
 }
 //# sourceMappingURL=dependency-provenance.js.map
-//# debugId=f3f3beb2-1d60-52fe-88ce-1ab3cb9dba0d
+//# debugId=ee17fdea-aeac-55b0-8302-a8740ba8428e

package/dist/sdk/duplicates.d.ts

@@ -8,6 +8,8 @@ import type { GlobalOptions } from "../core/shared/command-types.js";
 import { type DuplicateCluster, type DuplicateClustersResult } from "./similarity.js";
 /** Options shared by the `pm duplicates` command and SDK action. */
 export interface DuplicatesCommandOptions {
+    /** Compare all pairs instead of using lossless prefix filtering. */
+    exhaustive?: boolean;
     /** Lifecycle statuses to include; omitted means every status. */
     status?: readonly string[];
     /** Inclusive creation timestamp lower bound. */

package/dist/sdk/duplicates.js

@@ -1,11 +1,12 @@
 
-!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]="6152efa9-8338-57f0-b3de-5707befed019")}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]="51a84d98-6b3c-55ad-81f8-81928aa6e537")}catch(e){}}();
 import { resolvePmRoot } from "../core/store/paths.js";
 import { findDuplicateClusters, } from "./similarity.js";
 /** Discover existing duplicate clusters without creating or mutating an item. */
 export async function runDuplicates(global, options = {}) {
     const result = await findDuplicateClusters({
         pmRoot: resolvePmRoot(process.cwd(), global.path),
+        exhaustive: options.exhaustive,
         ...(options.status === undefined
             ? {}
             : {
@@ -37,4 +38,4 @@ export async function runDuplicates(global, options = {}) {
     };
 }
 //# sourceMappingURL=duplicates.js.map
-//# debugId=6152efa9-8338-57f0-b3de-5707befed019
+//# debugId=51a84d98-6b3c-55ad-81f8-81928aa6e537

package/dist/sdk/environment/host-environment-errors.d.ts

@@ -1,27 +1,5 @@
-import { PmCliError } from "../../core/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>;
+/**
+ * @module sdk/host-environment-errors
+ * Public SDK compatibility surface for path-redacted host filesystem refusals.
+ */
+export { classifyHostEnvironmentFault, translateHostEnvironmentFault, withHostEnvironmentBoundary, type HostEnvironmentBoundaryOptions, type HostEnvironmentFaultCodeOverrides, } from "../../core/fs/host-environment-errors.js";

package/dist/sdk/environment/host-environment-errors.js

@@ -1,142 +1,9 @@
 /**
  * @module sdk/host-environment-errors
- *
- * Classifies host filesystem/resource failures at SDK boundaries without
- * leaking local paths or swallowing genuine implementation defects.
+ * Public SDK compatibility surface for path-redacted host filesystem refusals.
  */
 
-!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]="1c74b5a9-67b8-597c-98de-a4487691081f")}catch(e){}}();
-import { constants as osConstants } from "node:os";
-import { EXIT_CODE } from "../../core/shared/constants.js";
-import { PmCliError } from "../../core/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;
-    }
-}
+!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]="8a0d8f6e-f4ff-5a0c-9205-d28e03df72b9")}catch(e){}}();
+export { classifyHostEnvironmentFault, translateHostEnvironmentFault, withHostEnvironmentBoundary, } from "../../core/fs/host-environment-errors.js";
 //# sourceMappingURL=host-environment-errors.js.map
-//# debugId=1c74b5a9-67b8-597c-98de-a4487691081f
+//# debugId=8a0d8f6e-f4ff-5a0c-9205-d28e03df72b9

package/dist/sdk/extension/install-runtime.js

@@ -4,7 +4,8 @@
  * Provides cross-platform extension copy safety and owner-bound install locks.
  */
 
-!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]="263602a2-c000-5df7-80d2-6f095985496f")}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]="b100fde9-412b-587b-85ac-532117e2253f")}catch(e){}}();
+import { withHostEnvironmentBoundary } from "../../core/fs/host-environment-errors.js";
 import { randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
 import os from "node:os";
@@ -88,7 +89,7 @@ export const resolveCanonicalExtensionInstallDestination = async (destinationDir
     return path.join(canonicalDestinationParent, path.basename(resolvedDestination));
 };
 /** Copy an extension without recursively copying a destination nested below its source. */
-export const copyExtensionDirectoryWithoutSelfNesting = async (sourceDirectory, destinationDirectory, copyDirectory, temporaryDirectory = os.tmpdir()) => {
+export const copyExtensionDirectoryWithoutSelfNesting = async (sourceDirectory, destinationDirectory, copyDirectory, temporaryDirectory = os.tmpdir()) => withHostEnvironmentBoundary("extension_install_copy", async () => {
     const resolvedSource = path.resolve(sourceDirectory);
     const canonicalSource = await fs
         .realpath(resolvedSource)
@@ -148,13 +149,15 @@ export const copyExtensionDirectoryWithoutSelfNesting = async (sourceDirectory,
     finally {
         await fs.rm(stagingRoot, { recursive: true, force: true });
     }
-};
+});
 /** Copy one extension directory with bounded transient-race retries. */
 export const copyExtensionDirectoryForInstall = async (sourceDirectory, destinationDirectory, copyDirectory = fs.cp) => {
     for (let attempt = 1; attempt <= EXTENSION_INSTALL_COPY_ATTEMPTS; attempt += 1) {
         try {
-            await fs.rm(destinationDirectory, { recursive: true, force: true });
-            await copyExtensionDirectoryWithoutSelfNesting(sourceDirectory, destinationDirectory, copyDirectory);
+            await withHostEnvironmentBoundary("extension_install_copy", async () => {
+                await fs.rm(destinationDirectory, { recursive: true, force: true });
+                await copyExtensionDirectoryWithoutSelfNesting(sourceDirectory, destinationDirectory, copyDirectory);
+            });
             return;
         }
         catch (error) {
@@ -308,4 +311,4 @@ export const withExtensionInstallLock = async (settingsRoot, destinationDirector
     }
 };
 //# sourceMappingURL=install-runtime.js.map
-//# debugId=263602a2-c000-5df7-80d2-6f095985496f
+//# debugId=b100fde9-412b-587b-85ac-532117e2253f

package/dist/sdk/extension/install-snapshot.js

@@ -4,7 +4,8 @@
  * Captures and restores extension files and metadata around install persistence.
  */
 
-!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]="98b47a2f-d48a-5c90-8b88-3f33bdd1c826")}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]="58ec3f16-267a-5a31-abd2-df46bb82b716")}catch(e){}}();
+import { withHostEnvironmentBoundary } from "../../core/fs/host-environment-errors.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { getSettingsPath } from "../../core/store/paths.js";
@@ -17,7 +18,7 @@ export const readOptionalMetadataFile = async (filePath) => fs.readFile(filePath
     throw error;
 });
 /** Capture extension files and metadata before applying an install mutation. */
-export const captureExtensionInstallSnapshot = async (selectedRoot, settingsRoot, destinationDirectory, destinationExists, backupDirectory) => {
+export const captureExtensionInstallSnapshot = async (selectedRoot, settingsRoot, destinationDirectory, destinationExists, backupDirectory) => withHostEnvironmentBoundary("extension_install_backup", async () => {
     const managedStatePath = resolveManagedExtensionStatePath(selectedRoot);
     const settingsPath = getSettingsPath(settingsRoot);
     const [managedStateContents, settingsContents] = await Promise.all([
@@ -39,9 +40,9 @@ export const captureExtensionInstallSnapshot = async (selectedRoot, settingsRoot
         settingsPath,
         settingsContents,
     };
-};
+});
 /** Restore directory and metadata snapshots after a partially persisted install. */
-export const restoreExtensionInstallSnapshot = async (snapshot) => {
+export const restoreExtensionInstallSnapshot = async (snapshot) => withHostEnvironmentBoundary("extension_install_rollback", async () => {
     await fs.rm(snapshot.destinationDirectory, { recursive: true, force: true });
     if (snapshot.destinationExists) {
         await fs.cp(snapshot.backupDirectory, snapshot.destinationDirectory, {
@@ -61,6 +62,6 @@ export const restoreExtensionInstallSnapshot = async (snapshot) => {
             await fs.writeFile(filePath, contents);
         }
     }
-};
+});
 //# sourceMappingURL=install-snapshot.js.map
-//# debugId=98b47a2f-d48a-5c90-8b88-3f33bdd1c826
+//# debugId=58ec3f16-267a-5a31-abd2-df46bb82b716