@unbrained/pm-cli 2026.8.7 → 2026.8.9

package/dist/sdk/similarity.js

@@ -5,10 +5,12 @@
  * governance and package-owned duplicate analysis.
  */
 
-!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]="078456b8-ed61-5c47-afc7-7553833934e1")}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]="a2fad90a-3575-5f3e-8cbe-ac380ac45591")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { resolveItemTypeRegistry } from "../core/item/type-registry.js";
+import { normalizeStatusInput } from "../core/item/status.js";
+import { resolveRuntimeStatusRegistry } from "../core/schema/runtime-schema.js";
 import { listAllItemMetadataLight } from "../core/store/item-store.js";
 import { resolvePmRoot } from "../core/store/paths.js";
 import { readSettings } from "../core/store/settings.js";
@@ -62,14 +64,38 @@ async function loadPreparedDuplicateItems(options, since) {
     const pmRoot = resolvePmRoot(options.cwd ?? process.cwd(), options.pmRoot);
     const settings = await readSettings(pmRoot);
     const typeRegistry = resolveItemTypeRegistry(settings);
-    const allowedStatuses = options.statuses
-        ? new Set(options.statuses.map((status) => status.trim()).filter(Boolean))
+    const requestedStatuses = options.statuses
+        ?.map((status) => status.trim().toLowerCase())
+        .filter(Boolean);
+    if (options.statuses !== undefined && requestedStatuses?.length === 0) {
+        throw new PmCliError("Duplicate cluster statuses must include at least one lifecycle status or all.", EXIT_CODE.USAGE);
+    }
+    const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
+    const normalizedStatuses = requestedStatuses?.map((status) => {
+        if (status === "all")
+            return status;
+        const normalized = normalizeStatusInput(status, statusRegistry);
+        if (!normalized) {
+            throw new PmCliError(`Unknown duplicate-cluster status "${status}". Allowed: all, ${statusRegistry.definitions.map((entry) => entry.id).join(", ")}.`, EXIT_CODE.USAGE);
+        }
+        return normalized;
+    });
+    const hasAll = normalizedStatuses?.includes("all") === true;
+    if (hasAll && normalizedStatuses?.some((status) => status !== "all")) {
+        throw new PmCliError('The "all" status cannot be combined with other statuses.', EXIT_CODE.USAGE);
+    }
+    const effectiveStatuses = hasAll ? undefined : normalizedStatuses;
+    const allowedStatuses = effectiveStatuses
+        ? new Set(effectiveStatuses)
         : undefined;
-    return (await listAllItemMetadataLight(pmRoot, settings.item_format, typeRegistry.type_to_folder, undefined, settings.schema))
-        .filter((item) => (!allowedStatuses || allowedStatuses.has(item.status)) &&
-        (!since || new Date(item.created_at).getTime() >= since.getTime()))
-        .sort((left, right) => left.id.localeCompare(right.id))
-        .map((item) => ({ item, prepared: prepareSimilarityText(item.title) }));
+    return {
+        items: (await listAllItemMetadataLight(pmRoot, settings.item_format, typeRegistry.type_to_folder, undefined, settings.schema))
+            .filter((item) => (!allowedStatuses || allowedStatuses.has(item.status)) &&
+            (!since || new Date(item.created_at).getTime() >= since.getTime()))
+            .sort((left, right) => left.id.localeCompare(right.id))
+            .map((item) => ({ item, prepared: prepareSimilarityText(item.title) })),
+        statuses: effectiveStatuses,
+    };
 }
 function collectDuplicateCandidatePairs(items, maxPairEvaluations = MAX_BATCH_PAIR_EVALUATIONS) {
     const candidates = new Set();
@@ -233,7 +259,7 @@ export async function findDuplicateClusters(options = {}) {
         limit: undefined,
     });
     const { limit, since } = validateDuplicateClusterOptions(options);
-    const items = await loadPreparedDuplicateItems(options, since);
+    const { items, statuses } = await loadPreparedDuplicateItems(options, since);
     const candidates = collectDuplicateCandidatePairs(items);
     const union = createDuplicateUnionFind(items.length);
     const matches = scoreDuplicateCandidates(items, candidates, threshold, union);
@@ -243,6 +269,10 @@ export async function findDuplicateClusters(options = {}) {
         count: clusters.length,
         threshold,
         source: "metadata_scan",
+        filters: {
+            statuses: statuses ?? null,
+            since: options.since ?? null,
+        },
         cost: {
             item_count: items.length,
             candidate_pairs: candidates.size,
@@ -273,4 +303,4 @@ export async function evaluateSimilarityGovernance(candidate, options) {
     return { mode: options.mode, bypassed, result };
 }
 //# sourceMappingURL=similarity.js.map
-//# debugId=078456b8-ed61-5c47-afc7-7553833934e1
+//# debugId=a2fad90a-3575-5f3e-8cbe-ac380ac45591

package/dist/sdk/structured-mutations.js

@@ -5,7 +5,7 @@
  * transaction contract and normalizes full item documents for CLI round trips.
  */
 
-!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]="91be2c5d-c495-54bc-ac79-b4c645ad2c6e")}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]="07876c03-63a8-5c69-9c6c-c3446076a382")}catch(e){}}();
 import crypto from "node:crypto";
 import { normalizeItemId, normalizePrefix } from "../core/item/id.js";
 import { EXIT_CODE, ITEM_PROJECT_CONTEXT_KEYS, } from "../core/shared/constants.js";
@@ -43,6 +43,9 @@ const READ_ONLY_ITEM_KEYS = new Set([
     "format_version",
     "path",
     "author",
+    "collection_counts",
+    "notes_count",
+    "tests_count",
 ]);
 const UPDATE_READ_ONLY_ITEM_KEYS = new Set([
     ...READ_ONLY_ITEM_KEYS,
@@ -568,4 +571,4 @@ export function validateItemMutationRows(value) {
     return parseItemMutationBatch(JSON.stringify(value));
 }
 //# sourceMappingURL=structured-mutations.js.map
-//# debugId=91be2c5d-c495-54bc-ac79-b4c645ad2c6e
+//# debugId=07876c03-63a8-5c69-9c6c-c3446076a382

package/dist/sdk/test/execution.js

@@ -4,7 +4,7 @@
  * Implements the pm test command surface and its agent-facing runtime behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="7d05534b-3cf7-506c-8626-4bd4a42cbc80")}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]="2c0646bf-44d7-521f-aea1-b0683d88a8fa")}catch(e){}}();
 import { spawn } from "node:child_process";
 import { cp, mkdir, mkdtemp, open, readdir, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
@@ -28,6 +28,7 @@ import { LINKED_TEST_PM_CONTEXT_MODE_VALUES as PM_CONTEXT_MODE_VALUES, LINKED_TE
 import { parseOnlyIndexValue, resolveLinkedTestRunSelection, } from "../../core/test/run-selectors.js";
 import { SCOPE_VALUES } from "../../types/index.js";
 import { diffTestRunMeasurements, parseTestRunMeasurements, queryTestRunMeasurementsBelow, } from "./measurements.js";
+import { SOURCE_CONTEXT_ACCESS_ENV } from "../environment/source-context.js";
 const TEST_OUTPUT_MAX_BUFFER_BYTES = 20 * 1024 * 1024;
 const DEFAULT_LINKED_TEST_TIMEOUT_FORCE_KILL_DELAY_MS = 3000;
 const DEFAULT_LINKED_TEST_HEARTBEAT_INTERVAL_MS = 10000;
@@ -1398,6 +1399,7 @@ function buildLinkedTestExecutionEnv(params) {
         process.env.PM_SOURCE_WORKSPACE_ROOT ?? process.cwd();
     executionEnv.PM_SOURCE_PM_PATH =
         params.executionContext.source_project_pm_path;
+    executionEnv[SOURCE_CONTEXT_ACCESS_ENV] = "read_only";
     return executionEnv;
 }
 function buildLinkedTestPassedResult(linkedTest, executionContext, execution) {
@@ -1872,4 +1874,4 @@ export const _testOnlyTestCommand = {
     summarizeRunResultStatuses,
 };
 //# sourceMappingURL=execution.js.map
-//# debugId=7d05534b-3cf7-506c-8626-4bd4a42cbc80
+//# debugId=2c0646bf-44d7-521f-aea1-b0683d88a8fa

package/dist/sdk/test/linked-command-detection.d.ts

@@ -1,8 +1,3 @@
-/**
- * @module sdk/test/linked-command-detection
- *
- * Parses linked-test command invocations for sandbox and context-safety checks.
- */
 /** Public contract for pm global flags with value, shared by SDK and presentation-layer consumers. */
 export declare const PM_GLOBAL_FLAGS_WITH_VALUE: Set<string>;
 /** Value-bearing flags accepted before item positionals by item-referencing commands. */
@@ -28,7 +23,7 @@ export declare const SCRIPT_RUN_FLAGS_WITH_VALUE: Set<string>;
 /** Implements split normalized command segments for the public runtime surface of this module. */
 export declare function splitNormalizedCommandSegments(normalizedCommand: string): string[];
 /** Extract pm CLI arguments from one normalized shell-command segment. */
-export declare function extractPmInvocationArgsFromSegment(segment: string): string[] | null;
+export declare function extractPmInvocationArgsFromSegment(segment: string, cwd?: string): string[] | null;
 /** Extract referenced item IDs from pm CLI invocations embedded in one command. */
 export declare const extractReferencedPmItemIdsFromCommand: (command: string, idPrefix?: string) => string[];
 /** Implements strip leading env assignments for the public runtime surface of this module. */
@@ -42,7 +37,7 @@ export declare function normalizePackageSpecifier(token: string): string;
 /** Implements check whether pm cli package token for the public runtime surface of this module. */
 export declare function isPmCliPackageToken(token: string): boolean;
 /** Implements check whether pm cli script token for the public runtime surface of this module. */
-export declare function isPmCliScriptToken(token: string): boolean;
+export declare function isPmCliScriptToken(token: string, cwd?: string): boolean;
 /** Implements parse npx command for the public runtime surface of this module. */
 export declare function parseNpxCommand(tokens: string[]): {
     command: string;

package/dist/sdk/test/linked-command-detection.js

@@ -9,7 +9,9 @@
 // normalized command string. Kept in core so SDK governance and CLI test
 // execution share one dependency-direction-safe parser.
 
-!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]="8c4d45cf-6b97-5151-a325-db09d31962a7")}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]="673a5a26-6214-58d6-af19-baee5a8359f0")}catch(e){}}();
+import { readFileSync } from "node:fs";
+import path from "node:path";
 const PM_SUBCOMMANDS_WITH_ITEM_REFERENCE = new Set([
     "get",
     "history",
@@ -277,15 +279,15 @@ export function splitNormalizedCommandSegments(normalizedCommand) {
         .filter((segment) => segment.length > 0);
 }
 /** Extract pm CLI arguments from one normalized shell-command segment. */
-export function extractPmInvocationArgsFromSegment(segment) {
+export function extractPmInvocationArgsFromSegment(segment, cwd = process.cwd()) {
     const tokens = stripLeadingEnvAssignments(segment.split(" ").filter((token) => token.length > 0));
     if (tokens.length === 0)
         return null;
     const [executable, ...args] = tokens;
-    if (isPmExecutableToken(executable) || isPmCliScriptToken(executable)) {
+    if (isPmExecutableToken(executable) || isPmCliScriptToken(executable, cwd)) {
         return args;
     }
-    if (executable === "node" && args[0] && isPmCliScriptToken(args[0])) {
+    if (executable === "node" && args[0] && isPmCliScriptToken(args[0], cwd)) {
         return args.slice(1);
     }
     const invocation = executable === "npx" || executable === "bunx"
@@ -408,10 +410,21 @@ export function isPmCliPackageToken(token) {
         token.endsWith("/pm-cli"));
 }
 /** Implements check whether pm cli script token for the public runtime surface of this module. */
-export function isPmCliScriptToken(token) {
-    return (token === "dist/cli.js" ||
-        token === "./dist/cli.js" ||
-        token.endsWith("/dist/cli.js"));
+export function isPmCliScriptToken(token, cwd = process.cwd()) {
+    const normalized = token.replaceAll("\\", "/");
+    if (normalized !== "dist/cli.js" &&
+        normalized !== "./dist/cli.js" &&
+        !normalized.endsWith("/dist/cli.js")) {
+        return false;
+    }
+    const scriptPath = path.resolve(cwd, token);
+    try {
+        const packageJson = JSON.parse(readFileSync(path.join(path.dirname(path.dirname(scriptPath)), "package.json"), "utf8"));
+        return packageJson.name === "@unbrained/pm-cli";
+    }
+    catch {
+        return false;
+    }
 }
 /** Implements parse npx command for the public runtime surface of this module. */
 export function parseNpxCommand(tokens) {
@@ -531,4 +544,4 @@ export function firstPositionalToken(tokens, flagsWithValue = new Set()) {
     return undefined;
 }
 //# sourceMappingURL=linked-command-detection.js.map
-//# debugId=8c4d45cf-6b97-5151-a325-db09d31962a7
+//# debugId=673a5a26-6214-58d6-af19-baee5a8359f0

package/dist/sdk/test/parsers.js

@@ -4,13 +4,14 @@
  * Implements the pm linked test parsers command surface and its agent-facing runtime behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="f592ba2b-fc8d-5930-a2a5-d02835c457a3")}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]="74163bed-a473-543e-ae6a-0d5091b3b3a9")}catch(e){}}();
 import { parseOptionalNumber } from "../../core/item/parse.js";
 import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
 import { splitCommaList } from "../../core/shared/split-comma-list.js";
 import { STRUCTURED_LINKED_TEST_KEYS } from "./entry.js";
 import { SCOPE_VALUES } from "../../types/index.js";
+import { SOURCE_CONTEXT_ACCESS_ENV, SOURCE_CONTEXT_WRITE_OVERRIDE_ENV, } from "../environment/source-context.js";
 /**
  * Shared linked-test field parsers used by the `create` and `test` commands.
  *
@@ -30,6 +31,8 @@ export const LINKED_TEST_PROTECTED_ENV_KEYS = new Set([
     "PM_GLOBAL_PATH",
     "PM_SOURCE_PM_PATH",
     "PM_SOURCE_WORKSPACE_ROOT",
+    SOURCE_CONTEXT_ACCESS_ENV,
+    SOURCE_CONTEXT_WRITE_OVERRIDE_ENV,
     "FORCE_COLOR",
 ]);
 /** Public contract for linked test env name pattern, shared by SDK and presentation-layer consumers. */
@@ -521,4 +524,4 @@ export const _testOnlyLinkedTestParsers = {
     parseLinkedTestJsonEntry,
 };
 //# sourceMappingURL=parsers.js.map
-//# debugId=f592ba2b-fc8d-5930-a2a5-d02835c457a3
+//# debugId=74163bed-a473-543e-ae6a-0d5091b3b3a9

package/dist/sdk/workspace-snapshot.d.ts

@@ -29,6 +29,7 @@ declare class WorkspaceLockHeartbeat {
 /** Internal heartbeat constructor exposed only for deterministic lock tests. */
 export declare const _testOnlyWorkspaceSnapshot: {
     WorkspaceLockHeartbeat: typeof WorkspaceLockHeartbeat;
+    withSnapshotFilesystemGuard: typeof withSnapshotFilesystemGuard;
 };
 /** Immutable manifest stored with every content-addressed snapshot object. */
 export interface WorkspaceSnapshotManifest {
@@ -117,6 +118,14 @@ export interface RestoreWorkspaceSnapshotResult {
     /** Stable audit operation appended after staging and before activation. */
     audit_operation: "workspace_snapshot_restore";
 }
+/**
+ * Runs a bounded snapshot filesystem stage, converting host environment faults
+ * into declared refusals.
+ *
+ * The operation label is a fixed identifier, never a path: snapshot failures
+ * are reported without disclosing workspace topology.
+ */
+declare function withSnapshotFilesystemGuard<T>(operation: string, run: () => Promise<T>): Promise<T>;
 /**
  * Publish a prepared immutable object, treating a concurrent winning publish
  * as successful deduplication.

package/dist/sdk/workspace-snapshot.js

@@ -5,7 +5,7 @@
  * state while excluding clone-local caches, locks, and recovery journals.
  */
 
-!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]="3e32be7c-f8a4-547d-8c19-456b4567982e")}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]="cdde844a-a14a-501d-a45b-18cbd1dd9008")}catch(e){}}();
 import crypto from "node:crypto";
 import { cp, lstat, mkdir, readFile, readdir, rename, rm, writeFile, } from "node:fs/promises";
 import path from "node:path";
@@ -15,6 +15,7 @@ import { acquireLock } from "../core/lock/lock.js";
 import { getLockPath } from "../core/store/paths.js";
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
+import { withHostEnvironmentBoundary } from "./environment/host-environment-errors.js";
 /** Current content-addressed workspace snapshot manifest schema identifier. */
 export const SNAPSHOT_SCHEMA = "https://schema.unbrained.dev/pm/workspace-snapshot/v1";
 const SNAPSHOT_RUNTIME_PATH = path.join("runtime", "workspace-snapshots");
@@ -27,6 +28,11 @@ const EXCLUDED_ROOT_NAMES = new Set([
 ]);
 const SNAPSHOT_TARGET_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
 const WORKSPACE_WRITER_LOCK_ID = "sdk-workspace-transaction";
+const SNAPSHOT_HOST_FAULT_CODES = {
+    capacity: { code: "workspace_snapshot_storage_exhausted" },
+    permission: { code: "workspace_snapshot_permission_denied" },
+    resource: { code: "workspace_snapshot_resource_exhausted" },
+};
 const DEFAULT_ATOMIC_OPERATIONS = {
     renameEntry: rename,
     removeEntry: async (target) => {
@@ -97,6 +103,7 @@ class WorkspaceLockHeartbeat {
 /** Internal heartbeat constructor exposed only for deterministic lock tests. */
 export const _testOnlyWorkspaceSnapshot = {
     WorkspaceLockHeartbeat,
+    withSnapshotFilesystemGuard,
 };
 async function collectAuthoritativeFiles(root, relative = "") {
     const entries = await readdir(path.join(root, relative), {
@@ -193,6 +200,27 @@ function isErrno(error, code) {
         "code" in error &&
         error.code === code);
 }
+/**
+ * Runs a bounded snapshot filesystem stage, converting host environment faults
+ * into declared refusals.
+ *
+ * The operation label is a fixed identifier, never a path: snapshot failures
+ * are reported without disclosing workspace topology.
+ */
+async function withSnapshotFilesystemGuard(operation, run) {
+    return withHostEnvironmentBoundary(`workspace_snapshot_${operation}`, run, {
+        codes: {
+            capacity: SNAPSHOT_HOST_FAULT_CODES.capacity.code,
+            permission: SNAPSHOT_HOST_FAULT_CODES.permission.code,
+            resource: SNAPSHOT_HOST_FAULT_CODES.resource.code,
+        },
+        why: "Snapshot create and restore copy authoritative tracker state before activation, so the stage needs capacity and write access up front.",
+        nextSteps: [
+            "Reclaim rebuildable tracker cache space with pm gc, then retry.",
+        ],
+        suggestedRetry: "pm gc --json",
+    });
+}
 function snapshotStore(pmRoot) {
     return path.join(pmRoot, SNAPSHOT_RUNTIME_PATH);
 }
@@ -302,14 +330,16 @@ export async function createWorkspaceSnapshot(pmRoot, options = {}) {
     }
     if (!deduplicated) {
         const temporaryRoot = path.join(store, "objects", `.create-${process.pid}-${crypto.randomUUID()}`);
-        await mkdir(path.join(temporaryRoot, "files"), { recursive: true });
-        for (const [index, file] of manifest.files.entries()) {
-            const target = path.join(temporaryRoot, "files", file);
-            await mkdir(path.dirname(target), { recursive: true });
-            await writeFile(target, contents[index]);
-        }
-        await writeFile(path.join(temporaryRoot, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
-        await mkdir(path.dirname(objectRoot), { recursive: true });
+        await withSnapshotFilesystemGuard("create_object", async () => {
+            await mkdir(path.join(temporaryRoot, "files"), { recursive: true });
+            for (const [index, file] of manifest.files.entries()) {
+                const target = path.join(temporaryRoot, "files", file);
+                await mkdir(path.dirname(target), { recursive: true });
+                await writeFile(target, contents[index]);
+            }
+            await writeFile(path.join(temporaryRoot, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+            await mkdir(path.dirname(objectRoot), { recursive: true });
+        });
         deduplicated = await publishWorkspaceSnapshotObject(temporaryRoot, objectRoot);
     }
     if (options.name !== undefined) {
@@ -467,12 +497,14 @@ export async function restoreWorkspaceSnapshotWithRecovery(pmRoot, target, optio
         const base = path.basename(pmRoot);
         staging = path.join(parent, `.${base}.restore-${crypto.randomUUID()}`);
         const backup = path.join(parent, `.${base}.backup-${crypto.randomUUID()}`);
-        await mkdir(staging, { recursive: true });
-        await cp(source, staging, { recursive: true, force: false });
-        await mkdir(path.join(staging, "runtime"), { recursive: true });
-        await cp(store, path.join(staging, SNAPSHOT_RUNTIME_PATH), {
-            recursive: true,
-            force: false,
+        await withSnapshotFilesystemGuard("restore_stage", async () => {
+            await mkdir(staging, { recursive: true });
+            await cp(source, staging, { recursive: true, force: false });
+            await mkdir(path.join(staging, "runtime"), { recursive: true });
+            await cp(store, path.join(staging, SNAPSHOT_RUNTIME_PATH), {
+                recursive: true,
+                force: false,
+            });
         });
         const audit = await appendWorkspaceAuditEvent({
             pmRoot: staging,
@@ -564,4 +596,4 @@ export async function deleteWorkspaceSnapshot(pmRoot, target) {
     return { deleted: "object", target };
 }
 //# sourceMappingURL=workspace-snapshot.js.map
-//# debugId=3e32be7c-f8a4-547d-8c19-456b4567982e
+//# debugId=cdde844a-a14a-501d-a45b-18cbd1dd9008

package/docs/AGENT_GUIDE.md

@@ -189,6 +189,7 @@ Use these defaults unless the task requires otherwise:
 - `pm validate --check-resolution --check-history-drift` before closing broad work.
 - `pm history-redact <id> --dry-run` before rewriting sensitive history payloads, then rerun without `--dry-run` once scope is confirmed.
 - `pm history-repair <id> --dry-run` when `pm health` or `pm validate --check-history-drift` report drifted streams; it re-anchors the hash chain and reconciles with the on-disk item without touching item content. Rerun without `--dry-run` to apply.
+- `pm merge reconcile --dry-run --json` after a branch merge that touched tracker data. Review every discarded-value receipt before applying; a lossy reconciliation requires the explicit `--force` acceptance flag. `history-repair` alone does not settle merge receipts.
 - `pm schema list` and `pm schema show <Type>` before creating custom-domain work; they show built-in, persisted custom, and extension-provided item types without reading schema files by hand.
 - `pm schema add-type <Name>` when `pm create`/`pm update` reject a project-specific type as invalid; it registers the type in `.agents/pm/schema/types.json` so `pm create <Name> "..."` works. Built-in types are reserved; the upsert is idempotent. `pm schema remove-type <Name>` removes a custom type (warns, non-blocking, if items still use it).
 - `pm schema add-status <id> --role <role>` / `pm schema remove-status <id>` manage custom lifecycle statuses in `.agents/pm/schema/statuses.json`; roles come from the runtime status-role vocabulary, the upsert is idempotent, and built-in default statuses cannot be removed. `pm schema list` now reports statuses (builtin vs custom) alongside types.
@@ -204,7 +205,7 @@ Use these defaults unless the task requires otherwise:
 Concurrent agents work on ordinary Git branches/worktrees; tracker artifacts need the semantic merge contract from [Merge Safety](MERGE_SAFETY.md). The short loop:
 
 - After a fresh clone or new worktree, run `pm merge install` once so the field-aware merge drivers back the committed `.gitattributes` fence.
-- After every merge that touches `.agents/pm`, run `pm validate --check-storage-integrity` and `pm history --verify --strict-exit`; follow the remediation output (`pm history-repair` wiring included).
+- After every merge that touches `.agents/pm`, run `pm merge reconcile --dry-run --json`, review the receipt classification, then apply `pm merge reconcile`. Add `--force` only after explicitly accepting or re-applying every discarded scalar value. Finish with `pm validate --check-storage-integrity` and `pm history --verify --strict-exit`.
 - Repositories fanning out many branches between merges should raise id entropy: `pm config project set ids_token_length 6`.
 - Use `--add-ac`/`--remove-ac` (not `--ac`) so concurrent acceptance-criteria edits merge instead of clobbering.
 

package/docs/AGENT_RUNTIME_PRIMITIVES.md

@@ -25,6 +25,8 @@ historical projections, and versioned legacy identity are tracked by
 [pm-ffz0a9](../.agents/pm/issues/pm-ffz0a9.toon),
 [pm-v8gfi7](../.agents/pm/issues/pm-v8gfi7.toon), and
 [pm-3yxwv5](../.agents/pm/issues/pm-3yxwv5.toon).
+[pm-alhqbz](../.agents/pm/issues/pm-alhqbz.toon) governs the nested source-write
+boundary retained by linked-test package lifecycles.
 
 `pm` treats project management as context management. These primitives keep
 mutation provenance, source-workspace identity, extension flags, and bounded
@@ -198,10 +200,15 @@ Every extension command, parser, preflight hook, renderer, and service receives:
 Linked tests set `PM_SOURCE_WORKSPACE_ROOT` before replacing `PM_PATH` and
 `PM_GLOBAL_PATH`, and protect `PM_SOURCE_PM_PATH` as the read-only source
 tracker coordinate for source-repository lifecycle commands such as
-`pm merge install`. Extensions can therefore inspect source VCS metadata
-without writing real tracker state. Package code should prefer `pm_root_rel`
-in output and persisted evidence to avoid leaking host-specific absolute
-paths.
+`pm merge install`. They also set `PM_SOURCE_CONTEXT_ACCESS=read_only`.
+Validation may continue to inspect the source coordinates, but a nested
+non-dry-run `pm merge install` selects the current package repository instead
+of the source workspace. A maintainer can deliberately opt into the legacy
+source mutation for one invocation with `PM_ALLOW_SOURCE_CONTEXT_WRITES=1`;
+`resolveMergeInstallContext()` reports whether that override selects the source.
+Both variables are protected from linked-test `env_set` and `env_clear`
+metadata. Package code should prefer `pm_root_rel` in output and persisted
+evidence to avoid leaking host-specific absolute paths.
 
 ## Strict extension flag descriptors
 

package/docs/COMMANDS.md

@@ -78,6 +78,7 @@ Use `--with-packages` for one-step agent setup when bundled package commands sho
 pm package                     # bare command defaults to --explore (list installed)
 pm install '*' --project
 pm package catalog --project
+pm package manage --project --output-format json
 pm install npm:@scope/pm-package --project
 pm package describe --project   # by-name surface map of every loaded package
 pm package describe my-package --markdown --output docs/my-package-reference.md
@@ -90,6 +91,11 @@ pm upgrade --cli-only --repair
 ```
 
 `pm install` and `pm package` are the preferred package-first workflow. `pm package` and `pm extension` bare invocations default to `--explore` so agents can list installed packages without remembering an action flag. `pm install '*'`, shell-expanded `pm install *`, and `pm install all` install bundled first-party packages. `pm extension` remains as a compatibility command for direct extension lifecycle operations.
+`pm package catalog` emits one row per package, with every resolvable bundled
+alias preserved in `aliases`; totals therefore measure packages rather than
+alias-index entries. `pm package manage` participates in the universal read
+output contract, so `--output-include`, `--output-limit`, `--output-budget`, and
+`--output-format` behave like the same controls on other SDK-backed reads.
 Install output includes a light `verification` summary with target tracker root, activation state, registered commands/actions/item types, and an `ok|degraded` health verdict. Runtime activation failure sets the command result and process exit status to failure; inspect `activation_diagnostics` and `command_discovery.next_steps` for the exact recovery path.
 Bare install names use bundled aliases before installed npm packages. Every
 install result reports `source_resolution`; when both candidates exist it marks
@@ -113,6 +119,7 @@ pm list-open --type Task --priority 1 --limit 20
 pm list-in-progress --limit 20
 pm aggregate --group-by parent,type --status open
 pm aggregate --group-by parent,type --completion --include-unparented
+pm duplicates --status all --threshold 0.8
 ```
 
 Use `pm next` when the only question is "what should I work on now?" It computes dependency-aware readiness, keeps dangling dependency ids blocked until repaired, and combines lifecycle-blocked plus graph-blocked work in the companion queue. The `recommended` projection is excluded from the `ready` tail; every actionable row carries its one-based `rank`, and the tail preserves the exact recommendation order. Foreign-owned in-progress work is summarized under `held_by_others`. Human-gated `Decision` records remain visible under `decision_needed` but are excluded from agent recommendations by default.
@@ -126,6 +133,10 @@ pm next --ready-only --limit 3 --json   # tightest agent-loop projection
 ```
 
 Use `context` first for a compact active-work snapshot. Use `search` when the request names a concept, component, or prior issue.
+Use `duplicates --status all` for a true whole-history duplicate check. The
+result echoes `filters.statuses: null` for the unrestricted corpus; named or
+custom statuses are normalized through the runtime status registry and an
+unknown status fails instead of returning a false-clean result.
 Use `pm get <id>` to read a single item by ID — the single-item read primitive used throughout the agent loop. It accepts `--fields <list>` and `--depth brief|standard|deep|full` for token-minimal projections, and `--tree`/`--tree-depth <n>` to include descendants. Standard/deep reads expose a normalized `schedule` facet (`deadline`, `start_at`, `end_at`, `location`, reminders, and events) when scheduling metadata exists. Container-oriented built-ins (Epic, Feature, Milestone, and Plan) plus custom types automatically expose type-agnostic child counts and continuation metadata. Standard depth keeps that rollup counts-only; `--depth deep|full` or an explicit `--fields id,children` request adds the deterministic bounded child sample. Built-in leaf reads avoid a workspace scan unless children are explicitly requested. `pm get <id> --json` returns the `body` inside the `item` object (`.item.body`); see [Full results, totals, and bodies](#full-results-totals-and-bodies). To duplicate an existing item as a starting point, `pm copy <id> --title "New title"` clones it into a fresh id with lifecycle fields reset.
 
 Add `--at <version|ISO-timestamp>` for a verified point-in-time read. It replays the same hash-checked history kernel used by restore but never acquires a lock, writes the item, or appends history. The result always includes `reconstructed: true`, `as_of_version`, and `as_of_timestamp`. Future/out-of-range targets fail with structured `valid_range` metadata. `--at` cannot be combined with `--tree`; workspace-wide historical graph projections require a future indexed primitive.
@@ -891,12 +902,19 @@ one-command reconciliation gate:
 ```bash
 pm merge reconcile --dry-run --json
 pm merge reconcile --message "Reconcile branch histories" --json
+# Only after reviewing every discarded-value receipt:
+pm merge reconcile --force --message "Accept reviewed merge decisions" --json
 ```
 
 The command scans every history stream, delegates repairs to the audited
 `history-repair --all` engine, then runs the history-drift and storage-integrity
 validation checks. Dry-run leaves drift intact and reports it in `validation`;
-apply exits nonzero if any stream fails or either invariant stays red. No Git
+apply exits nonzero if any stream fails or either invariant stays red. Lossless
+receipts remain visible in `pm merge report` but do not count as discarded-value
+decisions. When a receipt contains a discarded scalar value, apply refuses with
+`merge_reconcile_discards_require_acceptance` until the coordinator reviews or
+re-applies the value and passes `--force`. `pm history-repair` is the narrower
+drift-only tool and never substitutes for receipt reconciliation. No Git
 hook is installed automatically—teams may call this command from an explicit
 post-merge hook after opting into that policy.
 

package/docs/DEPENDENCY_KIND_CONTRACT.md

@@ -0,0 +1,29 @@
+# Dependency-kind contract
+
+Tracker: [pm-4020c5](../.agents/pm/issues/pm-4020c5.toon), [pm-jkbqt8](../.agents/pm/issues/pm-jkbqt8.toon)
+
+Dependency rows have one canonical stored spelling per relationship meaning. Command inputs remain compatibility-friendly: hyphens normalize to underscores and the aliases below are accepted, but `pm create` and `pm update` persist the canonical kind. Existing historical rows are never rewritten implicitly.
+
+| Canonical kind | Accepted legacy aliases |
+| --- | --- |
+| `blocked_by` | `depends_on`, `depends-on` |
+| `related` | `related_to`, `related-to` |
+| `parent` | `child_of`, `child-of`, `epic` |
+| `child` | `parent_child`, `parent-child`, `task` |
+
+`epic` and `task` are compatibility aliases, not item types embedded in the relationship ontology. New integrations should use `parent` or `child` and express the work classification through the item `type` field.
+
+The SDK relationship registry is authoritative. `canonicalizeRelationshipKind()` rejects unknown spellings, while `resolveCanonicalRelationshipKind()` supports validation flows that need an undefined result. `pm contracts` publishes `relationship_kind_contracts` with canonical names, aliases, inverses, and ordering/hierarchy semantics.
+
+## Direction and actionability
+
+`blocked_by` and `blocks` are inverse storage directions with identical scheduling meaning:
+
+- `A --blocked_by--> B` means A waits for B.
+- `B --blocks--> A` means A waits for B.
+
+Readiness, `pm next`, context blocker summaries, `pm list-blocked`, downstream `unblocks` projections, and close-time auto-unblock use that shared interpretation. This applies to mixed-direction corpora without migrating existing rows.
+
+## Legacy observability
+
+`pm deps` returns `legacy_alias_counts` for the workspace. `pm graph audit` returns the same field beside the canonical `profile.edges_by_kind` counts. Empty objects mean no stored alias debt. These diagnostics are read-only; terminal history remains untouched until an explicitly governed migration is requested.

package/docs/ITEM_READ_PROJECTIONS.md

@@ -0,0 +1,26 @@
+# Stable Item Read Projections
+
+Tracker reference: [pm-b1w8vr](../.agents/pm/issues/pm-b1w8vr.toon).
+
+Item mutation and read-back surfaces share one collection vocabulary:
+`comments`, `notes`, `learnings`, `files`, `tests`, `docs`, `reminders`, and
+`events`. Every normal `pm get` and SDK `runGet` result carries
+`item.collection_counts` with all eight keys, including zero values. This gives
+agents a stable, low-token way to verify a write without requesting complete
+collection payloads.
+
+`brief` and `standard` omit the collection arrays but retain the stable counts.
+`deep`, `full`, and `--full` include every collection array, normalizing absent
+collections to `[]`, and retain `notes_count`, `tests_count`, and
+`collection_counts`. A full projection is therefore a structural superset of
+the standard item projection rather than a different shape.
+
+Field projections can request `collection_counts` directly:
+
+```bash
+pm get pm-example --fields id,updated_at,collection_counts
+```
+
+Package authors receive the same contract from `runGet`. Do not infer whether
+a collection exists by checking for an omitted key; use the count projection,
+or request a full projection when the entries themselves are needed.