@unbrained/pm-cli 2026.8.7 → 2026.8.8

package/dist/sdk/merge/install.js

@@ -8,7 +8,7 @@
  * mutations refresh the fenced block automatically once it is installed.
  */
 
-!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]="a250384a-0279-5d01-ade4-f64be3119ed9")}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]="fce8fc1d-b9ca-55bc-9c5a-f4f9728a7158")}catch(e){}}();
 import { readFile, realpath, writeFile } from "node:fs/promises";
 import { execFile } from "node:child_process";
 import path from "node:path";
@@ -24,6 +24,7 @@ import { nowIso } from "../../core/shared/time.js";
 import { getSettingsPath, resolvePmRoot } from "../../core/store/paths.js";
 import { readSettings, resolveGovernanceKnobs, } from "../../core/store/settings.js";
 import { isPathOutsideRoot } from "../workspace.js";
+import { resolveSourceContextWritePolicy } from "../environment/source-context.js";
 const execFileAsync = promisify(execFile);
 /** Opening marker for the pm-owned merge-driver `.gitattributes` block. */
 export const PM_GITATTRIBUTES_START = "# pm-cli:merge-drivers:start";
@@ -80,6 +81,45 @@ const MERGE_DRIVER_DEFINITIONS = [
         itemPath: undefined,
     },
 ];
+/** Resolve explicit, inherited-source, and current-workspace precedence without I/O. */
+export function resolveMergeInstallContext(options) {
+    const explicitPath = options.explicitPath?.trim();
+    const sourceWorkspaceRoot = options.environment.PM_SOURCE_WORKSPACE_ROOT?.trim();
+    const sourcePmRoot = options.environment.PM_SOURCE_PM_PATH?.trim();
+    const sourcePolicy = resolveSourceContextWritePolicy(options.environment);
+    const sourceCoordinatesAvailable = Boolean(sourceWorkspaceRoot && sourcePmRoot);
+    const sourceContextSelected = explicitPath === undefined &&
+        sourceCoordinatesAvailable &&
+        (options.dryRun || sourcePolicy.source_writes_allowed);
+    if (explicitPath !== undefined) {
+        const pmRoot = resolvePmRoot(options.cwd, explicitPath);
+        return {
+            pm_root: pmRoot,
+            workspace_start: pmRoot,
+            source_coordinates_available: sourceCoordinatesAvailable,
+            source_context_selected: false,
+            source_policy: sourcePolicy,
+        };
+    }
+    if (sourceContextSelected) {
+        return {
+            pm_root: path.resolve(sourcePmRoot),
+            workspace_start: path.resolve(sourceWorkspaceRoot),
+            source_coordinates_available: true,
+            source_context_selected: true,
+            source_policy: sourcePolicy,
+        };
+    }
+    return {
+        pm_root: sourceCoordinatesAvailable
+            ? resolvePmRoot(options.cwd, ".agents/pm")
+            : resolvePmRoot(options.cwd),
+        workspace_start: options.cwd,
+        source_coordinates_available: sourceCoordinatesAvailable,
+        source_context_selected: false,
+        source_policy: sourcePolicy,
+    };
+}
 /** Resolve the enclosing Git worktree root or return null outside Git. */
 export async function findGitWorkspaceRoot(cwd) {
     try {
@@ -393,27 +433,17 @@ export async function refreshMergeAttributeFenceIfInstalled(pmRoot) {
  * per checkout). Requires an initialized tracker and a git repository.
  */
 export async function runMergeInstall(options, global) {
-    const explicitPath = global.path?.trim();
-    const sourceWorkspaceRoot = process.env.PM_SOURCE_WORKSPACE_ROOT?.trim();
-    const sourcePmRoot = process.env.PM_SOURCE_PM_PATH?.trim();
-    const usesLinkedTestSourceContext = explicitPath === undefined &&
-        sourceWorkspaceRoot !== undefined &&
-        sourceWorkspaceRoot.length > 0 &&
-        sourcePmRoot !== undefined &&
-        sourcePmRoot.length > 0;
-    const pmRoot = explicitPath !== undefined
-        ? resolvePmRoot(process.cwd(), explicitPath)
-        : usesLinkedTestSourceContext
-            ? path.resolve(sourcePmRoot)
-            : resolvePmRoot(process.cwd());
+    const context = resolveMergeInstallContext({
+        cwd: process.cwd(),
+        explicitPath: global.path,
+        dryRun: options.dryRun === true,
+        environment: process.env,
+    });
+    const pmRoot = context.pm_root;
     if (!(await pathExists(getSettingsPath(pmRoot)))) {
         throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
     }
-    const workspaceRoot = await resolveGitWorkspaceRoot(explicitPath !== undefined
-        ? pmRoot
-        : usesLinkedTestSourceContext
-            ? path.resolve(sourceWorkspaceRoot)
-            : process.cwd());
+    const workspaceRoot = await resolveGitWorkspaceRoot(context.workspace_start);
     return installMergeFence({
         pmRoot,
         workspaceRoot,
@@ -518,4 +548,4 @@ export async function installMergeFence(options) {
     };
 }
 //# sourceMappingURL=install.js.map
-//# debugId=a250384a-0279-5d01-ade4-f64be3119ed9
+//# debugId=fce8fc1d-b9ca-55bc-9c5a-f4f9728a7158

package/dist/sdk/notes.d.ts

@@ -5,6 +5,7 @@
  */
 import { type GlobalOptions } from "./runtime-primitives.js";
 import type { LogNote } from "../types/index.js";
+import { type AnnotationMutationReceipt, type AnnotationOmissionReceipt } from "./annotations.js";
 /** Documents the notes command options payload exchanged by command, SDK, and package integrations. */
 export interface NotesCommandOptions {
     /** Value that configures or reports add for this contract. */
@@ -27,6 +28,8 @@ export interface NotesCommandOptions {
     eventType?: string;
     /** Include total, returned, and truncation metadata. */
     includeMeta?: boolean;
+    /** Return complete note history after a mutation instead of a bounded receipt. */
+    fullHistory?: boolean;
     /** Value that configures or reports author for this contract. */
     author?: string;
     /** Human-readable explanation suitable for logs and agent-facing output. */
@@ -52,6 +55,10 @@ export interface NotesResult {
     limit?: number;
     /** Number of structured context events in the returned projection. */
     structured_event_count?: number;
+    /** Mutation identity when this result changed the collection. */
+    mutation_receipt?: AnnotationMutationReceipt;
+    /** Declares whether older notes were withheld from a mutation response. */
+    omission_receipt?: AnnotationOmissionReceipt;
 }
 /** Implements run notes for the public runtime surface of this module. */
 export declare function runNotes(id: string, options: NotesCommandOptions, global: GlobalOptions): Promise<NotesResult>;

package/dist/sdk/notes.js

@@ -4,7 +4,7 @@
  * Implements the pm notes 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]="973fe868-d08e-5a45-83c5-b7ecb959f680")}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]="ebd9f151-593f-5081-97da-d78f83de4914")}catch(e){}}();
 import { EXIT_CODE, PmCliError, parseLimit, stableStringify, } from "./runtime-primitives.js";
 import { limitAnnotationEntries, parseAnnotationTextInput, resolveAnnotationInput, runAnnotationCommand, } from "./annotations.js";
 function parseStructuredEventPayload(raw) {
@@ -137,4 +137,4 @@ export async function runNotes(id, options, global) {
     };
 }
 //# sourceMappingURL=notes.js.map
-//# debugId=973fe868-d08e-5a45-83c5-b7ecb959f680
+//# debugId=ebd9f151-593f-5081-97da-d78f83de4914

package/dist/sdk/read-output-contracts.js

@@ -5,7 +5,7 @@
  * surface without coupling package authors to command-specific option names.
  */
 
-!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]="0bccb953-bd78-5eee-a78d-8af3e250fa55")}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]="27f3a09b-9b90-5c85-9e41-21cfed5dc0ce")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { compactReadOutputToBudget, updateReadOutputReceiptEstimate, } from "./read-output-budget.js";
@@ -427,7 +427,86 @@ function projectRecordFields(value, selectors) {
     const selected = new Set(selectors.map((selector) => selector.split(".")[0]));
     return Object.fromEntries(Object.entries(value).filter(([key]) => selected.has(key)));
 }
-function applyIncludeProjection(result, selectors) {
+function getProjectionVocabulary(result) {
+    const item = isRecord(result.item) ? result.item : {};
+    const itemFields = Object.keys(item).sort((left, right) => left.localeCompare(right));
+    const sections = Object.keys(result)
+        .filter((key) => key !== "item" && key !== "read_output" && !ENVELOPE_KEYS.has(key))
+        .sort((left, right) => left.localeCompare(right));
+    return {
+        item,
+        itemFields,
+        sections,
+        valid: [
+            ...itemFields,
+            "item",
+            ...itemFields.map((field) => `item.${field}`),
+            ...sections,
+        ],
+    };
+}
+function applyGetIncludeProjection(result, selectors) {
+    const vocabulary = getProjectionVocabulary(result);
+    const unknown = selectors.filter((selector) => !vocabulary.valid.includes(selector));
+    if (unknown.length > 0) {
+        throw new PmCliError(`Unknown --output-include selector(s) for get: ${unknown.join(", ")}. Valid selectors: ${vocabulary.valid.join(", ")}.`, EXIT_CODE.USAGE);
+    }
+    const fullItem = selectors.includes("item");
+    const itemSelectors = selectors
+        .flatMap((selector) => selector.startsWith("item.")
+        ? [selector.slice("item.".length)]
+        : vocabulary.itemFields.includes(selector)
+            ? [selector]
+            : [])
+        .filter((selector, index, values) => values.indexOf(selector) === index);
+    if (fullItem && itemSelectors.length > 0) {
+        throw new PmCliError("--output-include cannot mix a full item with projected item fields; use item or item.<field>, not both.", EXIT_CODE.USAGE);
+    }
+    const selectedSections = new Set(selectors.filter((selector) => vocabulary.sections.includes(selector)));
+    const projected = Object.fromEntries(Object.entries(result).filter(([key]) => ENVELOPE_KEYS.has(key) || selectedSections.has(key)));
+    if (fullItem) {
+        projected.item = vocabulary.item;
+    }
+    else if (itemSelectors.length > 0) {
+        projected.item = projectRecordFields(vocabulary.item, itemSelectors);
+    }
+    const omittedFieldGroups = [
+        ...(fullItem
+            ? []
+            : itemSelectors.length > 0
+                ? vocabulary.itemFields
+                    .filter((field) => !itemSelectors.includes(field))
+                    .map((field) => ({
+                    name: `item.${field}`,
+                    restore_with: `--output-include item.${field}`,
+                }))
+                : [{ name: "item", restore_with: "--output-include item" }]),
+        ...vocabulary.sections
+            .filter((section) => !selectedSections.has(section))
+            .map((section) => ({
+            name: section,
+            restore_with: `--output-include ${section}`,
+        })),
+    ];
+    const inheritedOmittedFieldGroups = isRecord(projected.omission_receipt) &&
+        Array.isArray(projected.omission_receipt.omitted_field_groups)
+        ? projected.omission_receipt.omitted_field_groups
+        : [];
+    const combinedOmittedFieldGroups = [
+        ...inheritedOmittedFieldGroups,
+        ...omittedFieldGroups,
+    ];
+    projected.omission_receipt = {
+        has_omissions: combinedOmittedFieldGroups.length > 0,
+        omitted_field_group_count: combinedOmittedFieldGroups.length,
+        omitted_field_groups: combinedOmittedFieldGroups,
+    };
+    return projected;
+}
+function applyIncludeProjection(command, result, selectors) {
+    if (command === "get") {
+        return applyGetIncludeProjection(result, selectors);
+    }
     const rows = readOutputRowPaths(result);
     const qualifiedRowSelectors = selectors.flatMap((selector) => rows.flatMap((rowPath) => selector.startsWith(`${rowPath}.`)
         ? [selector.slice(rowPath.length + 1)]
@@ -486,7 +565,7 @@ function attachReadOutputSessionContracts(result, state, receipt) {
 function projectReadOutputRows(result, resolved, session) {
     let projected = { ...result };
     if (resolved.include?.source === "canonical") {
-        projected = applyIncludeProjection(projected, resolved.include.value);
+        projected = applyIncludeProjection(resolved.command, projected, resolved.include.value);
     }
     if (resolved.amount?.source === "canonical") {
         projected = applyAmountBound(projected, resolved.amount.value);
@@ -597,4 +676,4 @@ export function resolveReadOutputEncoding(command, options) {
         : undefined;
 }
 //# sourceMappingURL=read-output-contracts.js.map
-//# debugId=0bccb953-bd78-5eee-a78d-8af3e250fa55
+//# debugId=27f3a09b-9b90-5c85-9e41-21cfed5dc0ce

package/dist/sdk/runtime.d.ts

@@ -10,7 +10,7 @@ import { EXIT_CODE } from "../core/shared/constants.js";
 export type { WorkspaceExtensionCommandContract, WorkspaceFieldContract, } from "./workspace-contracts.js";
 import { type PmReadOutputOptions, type PmReadOutputResultFor } from "./read-output-contracts.js";
 export type { PmReadOutputBudgetExceeded, PmReadOutputOptions, PmReadOutputResult, PmReadOutputResultFor, PmReadOutputSurfaceContract, } from "./read-output-contracts.js";
-export type { PmReadOutputSessionReceipt, PmReadOutputSessionState } from "./read-output-session.js";
+export type { PmReadOutputSessionReceipt, PmReadOutputSessionState, } from "./read-output-session.js";
 export type { PmContextIntentContract } from "./context-intent-contracts.js";
 export type { PmErrorCodeContract } from "./error-code-catalog.js";
 export { clearWorkspaceContractsCache } from "./workspace-contracts-cache.js";

package/dist/sdk/runtime.js

@@ -4,7 +4,7 @@
  * Defines public SDK APIs and package-author helpers for Runtime.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="42339e0d-ca3c-505f-8b98-acec81158b6e")}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]="c8f2b88e-1883-5744-868b-3a16f3814813")}catch(e){}}();
 export { PM_GITIGNORE_END, PM_GITIGNORE_START, ensurePmGitignore, getPmGitignoreBlock, } from "./workspace.js";
 export { SEARCH_EXTENSION_FLAG_DEFINITIONS } from "./extension-contracts.js";
 import { AsyncLocalStorage } from "node:async_hooks";
@@ -36,6 +36,7 @@ import { runAggregate, } from "./query/aggregate.js";
 import { runAppend } from "./lifecycle/append.js";
 import { runClaim, runClaimNext, runRelease } from "./lifecycle/claim.js";
 import { runCloseMany } from "./lifecycle/close-many.js";
+import { normalizeAnnotationTransportOptions } from "./annotations.js";
 import { runComments } from "./comments.js";
 import { runHistory } from "./query/history.js";
 import { runLearnings } from "./learnings.js";
@@ -60,7 +61,7 @@ import { runExtension, } from "./extension.js";
 import { runConfig } from "./config.js";
 import { runInit } from "./init.js";
 import { runRuntimeEvalAction, runRuntimeEventsAction, runRuntimeMergeAction, runRuntimeSchedulingAction, runRuntimeWorkspaceAction, } from "./runtime-extended-actions.js";
-import { acknowledgeUnknownAuthorHistoryEvents, } from "./author-attribution.js";
+import { acknowledgeUnknownAuthorHistoryEventsFromTransport, } from "./author-attribution.js";
 import { runProfileApply, runProfileLint, runProfileList, runProfileShow, } from "./profile.js";
 import { runHistoryRedact, } from "./history-redact.js";
 import { runMcpHistoryCompactAction, runMcpHistoryRepairAction, } from "./history-mcp.js";
@@ -1387,7 +1388,7 @@ async function runMcpCloseAction(ctx) {
     });
 }
 function runMcpCommentsAction(ctx) {
-    const commentOptions = { ...ctx.options };
+    const commentOptions = normalizeAnnotationTransportOptions(ctx.options);
     const isListing = commentOptions.add === undefined &&
         commentOptions.stdin === undefined &&
         commentOptions.file === undefined &&
@@ -1395,11 +1396,10 @@ function runMcpCommentsAction(ctx) {
         commentOptions.delete === undefined;
     if (isListing) {
         commentOptions.includeMeta = true;
-        if (commentOptions.limit === undefined && commentOptions.full !== true) {
+        if (commentOptions.limit === undefined && commentOptions.fullHistory !== true) {
             commentOptions.limit = "20";
         }
     }
-    delete commentOptions.full;
     return runComments(requireMcpItemId(ctx), commentOptions, ctx.global);
 }
 function runMcpFilesAction(ctx) {
@@ -1752,23 +1752,7 @@ function runMcpGraphAction(ctx) {
     return runGraph(readRequiredString(merged, "subcommand"), readString(merged, "id") ?? ctx.id, readString(merged, "target"), graphOptionsFromFlat(merged), ctx.global);
 }
 function runMcpHistoryAuthorAcknowledgeAction(ctx) {
-    const merged = { ...ctx.args, ...ctx.options };
-    const events = readStringArray(merged.historyEvent).map((value) => {
-        const separator = value.lastIndexOf(":");
-        return {
-            item_id: value.slice(0, separator).trim(),
-            line: Number(value.slice(separator + 1)),
-        };
-    });
-    return acknowledgeUnknownAuthorHistoryEvents(resolvePmRoot(process.cwd(), ctx.global.path), {
-        events,
-        all_actionable: merged.allActionable === true || merged.all_actionable === true,
-        attributed_author: readString(merged, "attributedAuthor") ??
-            readString(merged, "attributed_author") ??
-            "",
-        reviewer: readString(merged, "reviewer") ?? "",
-        reason: readString(merged, "reason") ?? "",
-    });
+    return acknowledgeUnknownAuthorHistoryEventsFromTransport(resolvePmRoot(process.cwd(), ctx.global.path), { ...ctx.args, ...ctx.options });
 }
 const SDK_ACTION_HANDLERS = {
     init: (ctx) => runInit(readString(ctx.args, "prefix"), ctx.global, ctx.options),
@@ -1813,8 +1797,8 @@ const SDK_ACTION_HANDLERS = {
     "close-task": runMcpCloseTaskAction,
     close: runMcpCloseAction,
     comments: runMcpCommentsAction,
-    notes: (ctx) => runNotes(requireMcpItemId(ctx), ctx.options, ctx.global),
-    learnings: (ctx) => runLearnings(requireMcpItemId(ctx), ctx.options, ctx.global),
+    notes: (ctx) => runNotes(requireMcpItemId(ctx), normalizeAnnotationTransportOptions(ctx.options), ctx.global),
+    learnings: (ctx) => runLearnings(requireMcpItemId(ctx), normalizeAnnotationTransportOptions(ctx.options), ctx.global),
     files: runMcpFilesAction,
     docs: (ctx) => runDocs(requireMcpItemId(ctx), withAddNoteOption(ctx.options), ctx.global),
     test: (ctx) => runTest(requireMcpItemId(ctx), ctx.options, ctx.global),
@@ -1941,4 +1925,4 @@ async function loadWorkspaceExtensionRegistrations(pmRoot, settings, cwd) {
     }
 }
 //# sourceMappingURL=runtime.js.map
-//# debugId=42339e0d-ca3c-505f-8b98-acec81158b6e
+//# debugId=c8f2b88e-1883-5744-868b-3a16f3814813

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/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_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/README.md

@@ -56,6 +56,7 @@ pm guide release --json
 - [Improvement Ledger and History Analytics](IMPROVEMENT_ANALYTICS.md) - audited quantitative observations, live provenance coverage, and bounded observational fleet outcomes.
 - [SDK Evidence Traceability and Integrity](SDK_EVIDENCE_TRACEABILITY.md) - reverse source-to-item lookup, atomic evidence replacement, no-op history, linked-test collision classification, and telemetry drain receipts.
 - [SDK Context Integrity Primitives](SDK_CONTEXT_INTEGRITY_PRIMITIVES.md) - batch duplicate discovery, structured errors, Plan evidence/lifecycle, sparse settings, tombstones, linked-test output, relocation diagnostics, and scoped output services.
+- [SDK Context Integrity](SDK_CONTEXT_INTEGRITY.md) - truthful `get` projections, bounded annotation mutations, shared author coordinates, health provider boundaries, and changeset-aware replication gates.
 - [Reproducible Workspaces and Snapshots](REPRODUCIBLE_WORKSPACES.md) - deterministic SDK recipes and content-addressed authoritative tracker restore points.
 - [Portable Corpus Shapes](CORPUS_SHAPES.md) - versioned SDK populations for realistic benchmarks, evaluations, and package tests.
 - [Agent UX Contracts](AGENT_UX_CONTRACTS.md) - ordering-cycle advisories, graph count units, collision safety, compact context, ownership wording, and recovery behavior.