@unbrained/pm-cli 2026.8.22 → 2026.8.24

package/dist/sdk/test/execution.d.ts

@@ -1,10 +1,11 @@
 import type { GlobalOptions } from "../../core/shared/command-types.js";
 import { resolveAuthor } from "../../core/shared/author.js";
 import { runInit } from "../init.js";
-import { type LinkedTestPmContextMode } from "./parsers.js";
+import { type LinkedTestPmContextMode, type LinkedTestWorkspaceContextMode } from "./parsers.js";
 import { type LinkedTestRunSelection } from "../../core/test/run-selectors.js";
 import type { LinkedTest, LinkScope, TestRunMeasurement } from "../../types/index.js";
 import { type TestRunMeasurementDiff } from "./measurements.js";
+import { type LinkedTestTrustDecision } from "./trust.js";
 type ResolvedLinkedTestPmContextMode = Exclude<LinkedTestPmContextMode, "auto">;
 interface LinkedTestExecutionResult {
     stdout: string;
@@ -61,6 +62,14 @@ export interface TestCommandOptions {
     pmContext?: string;
     /** Value that configures or reports override linked pm context for this contract. */
     overrideLinkedPmContext?: boolean;
+    /** Source-workspace visibility and working-directory mode. */
+    workspaceContext?: string;
+    /** Force the run-level workspace mode over per-test metadata. */
+    overrideLinkedWorkspaceContext?: boolean;
+    /** Explicitly permit an untrusted linked command when project policy also permits it. */
+    allowUntrustedLinkedTests?: boolean;
+    /** Record clone-local acknowledgement for the item's current linked tests. */
+    acknowledgeLinkedTests?: boolean;
     /** Value that configures or reports fail on context mismatch for this contract. */
     failOnContextMismatch?: boolean;
     /** Value that configures or reports fail on skipped for this contract. */
@@ -87,7 +96,7 @@ export interface TestCommandOptions {
     metricDiff?: string;
 }
 /** Restricts linked test failure category values accepted by command, SDK, and storage contracts. */
-export type LinkedTestFailureCategory = "infra_collision" | "assertion_failure" | "empty_run" | "timeout" | "max_buffer" | "spawn_error" | "signal";
+export type LinkedTestFailureCategory = "infra_collision" | "trust_refusal" | "assertion_failure" | "empty_run" | "timeout" | "max_buffer" | "spawn_error" | "signal";
 /** Documents the test run result payload exchanged by command, SDK, and package integrations. */
 export interface TestRunResult {
     /** Value that configures or reports command for this contract. */
@@ -118,6 +127,11 @@ export interface TestRunResult {
         mismatch_detected: boolean;
         project_extensions_seeded: boolean;
         global_extensions_seeded: boolean;
+        requested_workspace_context_mode: LinkedTestWorkspaceContextMode;
+        workspace_context_mode: LinkedTestWorkspaceContextMode;
+        working_directory: string;
+        source_workspace_root: string;
+        trust: LinkedTestTrustDecision;
     };
     /** Value that configures or reports stdout for this contract. */
     stdout?: string;
@@ -195,7 +209,7 @@ declare function segmentInvokesRecursiveTestAll(segment: string): boolean;
 declare function parseLinkedTestTimeoutSeconds(timeoutSecondsRaw: string | undefined, timeoutAliasRaw: string | undefined): number | undefined;
 declare function parseAddJsonEntries(raw: string[] | undefined): LinkedTest[];
 declare function endLinkedTestProgress(context: LinkedTestProgressContext, executionResult: Pick<LinkedTestExecutionResult, "timedOut" | "maxBufferExceeded" | "outputTruncated" | "exitCode" | "signal">, startedAt: number, mode: LinkedTestProgressMode): void;
-declare function runLinkedTestCommand(command: string, timeoutMs: number, env: NodeJS.ProcessEnv, progressContext: LinkedTestProgressContext, progressMode: LinkedTestProgressMode): Promise<LinkedTestExecutionResult>;
+declare function runLinkedTestCommand(command: string, timeoutMs: number, env: NodeJS.ProcessEnv, progressContext: LinkedTestProgressContext, progressMode: LinkedTestProgressMode, cwd?: string): Promise<LinkedTestExecutionResult>;
 declare function formatLinkedTestExecutionError(result: LinkedTestExecutionResult, timeoutMs: number): string;
 /** Implements classify linked test failure for the public runtime surface of this module. */
 export declare function classifyLinkedTestFailure(result: Pick<LinkedTestExecutionResult, "stdout" | "stderr" | "spawnError" | "signal" | "timedOut" | "maxBufferExceeded">): LinkedTestFailureCategory;
@@ -228,6 +242,11 @@ interface RunLinkedTestsOptions {
     requireAssertionsForPm?: boolean;
     checkContext?: boolean;
     autoPmContext?: boolean;
+    workspaceContext?: string;
+    overrideLinkedWorkspaceContext?: boolean;
+    pmRoot?: string;
+    allowUntrustedLinkedTests?: boolean;
+    untrustedLinkedTestsPolicyEnabled?: boolean;
 }
 interface LinkedTestSandboxLayout {
     root: string;
@@ -235,6 +254,8 @@ interface LinkedTestSandboxLayout {
     schemaGlobalPmPath: string;
     trackerProjectPmPath: string;
     trackerGlobalPmPath: string;
+    workspaceSnapshotRoot: string;
+    workspaceIsolatedRoot: string;
 }
 interface LinkedTestSandboxCounts {
     sourceProjectItemCount: number;
@@ -255,6 +276,10 @@ declare function buildLinkedTestExecutionContext(params: {
     requestedPmContextMode: LinkedTestPmContextMode;
     effectivePmContextMode: ResolvedLinkedTestPmContextMode;
     autoPmContextApplied: boolean;
+    requestedWorkspaceContextMode: LinkedTestWorkspaceContextMode;
+    workspaceContextMode: LinkedTestWorkspaceContextMode;
+    sourceWorkspaceRoot: string;
+    trust: LinkedTestTrustDecision;
 }): NonNullable<TestRunResult["execution_context"]>;
 /** Implements run linked tests for the public runtime surface of this module. */
 export declare function runLinkedTests(tests: LinkedTest[], defaultTimeoutSeconds: number | undefined, options?: RunLinkedTestsOptions): Promise<TestRunResult[]>;

package/dist/sdk/test/execution.js

@@ -4,10 +4,10 @@
  * 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]="5fe0ee3e-9590-56fc-b238-e56ff1970e52")}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]="7659721c-21f5-55da-8cce-31b290de5bfb")}catch(e){}}();
 import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import { spawn } from "node:child_process";
-import { cp, mkdir, mkdtemp, open, readdir, rm } from "node:fs/promises";
+import { cp, mkdir, mkdtemp, open, readdir, rm, symlink, } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
@@ -25,12 +25,13 @@ import { readSettings } from "../../core/store/settings.js";
 import { appendTrackedTestRunSummary, buildTrackedTestRunHistory, } from "../../core/test/item-test-run-tracking.js";
 import { runInit } from "../init.js";
 import { looksLikeStructuredLinkedTestEntry, normalizeStructuredLinkedTestEntry, } from "./entry.js";
-import { LINKED_TEST_PM_CONTEXT_MODE_VALUES as PM_CONTEXT_MODE_VALUES, LINKED_TEST_PROTECTED_ENV_KEYS, parseLinkedTestAssertionEqualsMap, parseLinkedTestAssertionGteMap, parseLinkedTestBoolean as parseLinkedTestBooleanValue, parseLinkedTestContextMode as parseLinkedTestContextModeValue, parseLinkedTestEnvClear as parseLinkedTestEnvClearValue, parseLinkedTestEnvSet as parseLinkedTestEnvSetValue, parseLinkedTestJsonEntries, parseLinkedTestMinLines, parseLinkedTestRegexList, parseLinkedTestStringList, } from "./parsers.js";
+import { LINKED_TEST_PM_CONTEXT_MODE_VALUES as PM_CONTEXT_MODE_VALUES, LINKED_TEST_PROTECTED_ENV_KEYS, parseLinkedTestAssertionEqualsMap, parseLinkedTestAssertionGteMap, parseLinkedTestBoolean as parseLinkedTestBooleanValue, parseLinkedTestContextMode as parseLinkedTestContextModeValue, parseLinkedTestEnvClear as parseLinkedTestEnvClearValue, parseLinkedTestEnvSet as parseLinkedTestEnvSetValue, parseLinkedTestJsonEntries, parseLinkedTestMinLines, parseLinkedTestRegexList, parseLinkedTestStringList, parseLinkedTestWorkspaceContextMode, } from "./parsers.js";
 import { parseOnlyIndexValue, resolveLinkedTestRunSelection, } from "../../core/test/run-selectors.js";
 import { SCOPE_VALUES } from "../../types/index.js";
 import { diffTestRunMeasurements, parseTestRunMeasurements, queryTestRunMeasurementsBelow, } from "./measurements.js";
 import { withHostEnvironmentBoundary } from "../environment/host-environment-errors.js";
 import { SOURCE_CONTEXT_ACCESS_ENV } from "../environment/source-context.js";
+import { acknowledgeLinkedTests, attachLinkedTestMutationProvenance, resolveLinkedTestSourceRef, resolveLinkedTestSourceWorkspaceRoot, resolveLinkedTestTrust, } from "./trust.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;
@@ -170,6 +171,15 @@ function parsePmContextMode(raw) {
     }
     throw new PmCliError(`Invalid --pm-context value "${raw}". Expected one of: ${PM_CONTEXT_MODE_VALUES.join(", ")}`, EXIT_CODE.USAGE);
 }
+function parseWorkspaceContextMode(raw) {
+    return parseLinkedTestWorkspaceContextMode(raw ?? "source", "--workspace-context");
+}
+function resolveLinkedTestWorkspaceContextMode(linkedTest, runLevelMode, overrideLinkedMode) {
+    if (overrideLinkedMode) {
+        return runLevelMode;
+    }
+    return (parseLinkedTestWorkspaceContextMode(linkedTest.workspace_context_mode, "linked test") ?? runLevelMode);
+}
 function resolveLinkedTestRequestedContextMode(linkedTest, runLevelMode, overrideLinkedPmContext) {
     if (overrideLinkedPmContext) {
         return runLevelMode;
@@ -460,6 +470,7 @@ function parseAddEntry(entry) {
         scope: ensureScope(kv.scope),
         timeout_seconds: parseLinkedTestTimeoutSeconds(trimLinkedTestEntryField(kv.timeout_seconds), trimLinkedTestEntryField(kv.timeout)),
         pm_context_mode: parseLinkedTestContextModeValue(trimLinkedTestEntryField(kv.pm_context_mode), "--add"),
+        workspace_context_mode: parseLinkedTestWorkspaceContextMode(trimLinkedTestEntryField(kv.workspace_context_mode), "--add"),
         env_set: parseLinkedTestEnvSetValue(trimLinkedTestEntryField(kv.env_set), "--add"),
         env_clear: parseLinkedTestEnvClearValue(trimLinkedTestEntryField(kv.env_clear), "--add"),
         shared_host_safe: parseLinkedTestBooleanValue(trimLinkedTestEntryField(kv.shared_host_safe), "--add", "shared_host_safe"),
@@ -760,9 +771,9 @@ function waitForLinkedTestChildClose(child) {
         });
     });
 }
-function createLinkedTestChild(command, env, stdoutFd, stderrFd) {
+function createLinkedTestChild(command, env, stdoutFd, stderrFd, cwd) {
     return spawn(command, {
-        cwd: process.cwd(),
+        cwd,
         env,
         shell: true,
         windowsHide: true,
@@ -791,7 +802,7 @@ async function readLinkedTestCapture(capturePath) {
         await handle.close();
     }
 }
-async function runLinkedTestCommand(command, timeoutMs, env, progressContext, progressMode) {
+async function runLinkedTestCommand(command, timeoutMs, env, progressContext, progressMode, cwd = process.cwd()) {
     const startedAt = Date.now();
     const captureRoot = await mkdtemp(path.join(tmpdir(), "pm-linked-test-output-"));
     try {
@@ -803,7 +814,7 @@ async function runLinkedTestCommand(command, timeoutMs, env, progressContext, pr
         ]);
         let child;
         try {
-            child = createLinkedTestChild(command, env, stdoutHandle.fd, stderrHandle.fd);
+            child = createLinkedTestChild(command, env, stdoutHandle.fd, stderrHandle.fd, cwd);
         }
         finally {
             await Promise.all([stdoutHandle.close(), stderrHandle.close()]);
@@ -902,6 +913,7 @@ export function classifyLinkedTestFailure(result) {
 function createEmptyFailureCategoryCounts() {
     return {
         infra_collision: 0,
+        trust_refusal: 0,
         assertion_failure: 0,
         empty_run: 0,
         timeout: 0,
@@ -1264,8 +1276,48 @@ function createLinkedTestSandboxLayout(sandboxRoot) {
         schemaGlobalPmPath: path.join(sandboxRoot, "schema", "global"),
         trackerProjectPmPath: path.join(sandboxRoot, "tracker", "project", ".agents", "pm"),
         trackerGlobalPmPath: path.join(sandboxRoot, "tracker", "global"),
+        workspaceSnapshotRoot: path.join(sandboxRoot, "workspace", "project"),
+        workspaceIsolatedRoot: path.join(sandboxRoot, "workspace", "isolated"),
     };
 }
+function linkedTestsRequireWorkspaceSnapshot(tests, runLevelMode, overrideLinkedMode) {
+    return tests.some((linkedTest) => resolveLinkedTestWorkspaceContextMode(linkedTest, runLevelMode, overrideLinkedMode) === "snapshot");
+}
+async function seedLinkedTestWorkspaceSnapshot(layout, sourceWorkspaceRoot) {
+    const excludedSegments = new Set([
+        ".agents",
+        ".git",
+        ".nyc_output",
+        ".turbo",
+        "coverage",
+        "node_modules",
+    ]);
+    await mkdir(path.dirname(layout.workspaceSnapshotRoot), { recursive: true });
+    await cp(sourceWorkspaceRoot, layout.workspaceSnapshotRoot, {
+        recursive: true,
+        force: true,
+        filter(source) {
+            const relative = path.relative(sourceWorkspaceRoot, source);
+            if (!relative) {
+                return true;
+            }
+            return !relative
+                .split(path.sep)
+                .some((segment) => excludedSegments.has(segment));
+        },
+    });
+    const sourceNodeModules = path.join(sourceWorkspaceRoot, "node_modules");
+    if (await pathExists(sourceNodeModules)) {
+        await symlink(sourceNodeModules, path.join(layout.workspaceSnapshotRoot, "node_modules"), process.platform === "win32" ? "junction" : "dir");
+    }
+}
+async function bindSnapshotTracker(snapshotRoot, sandboxPmPath) {
+    const agentsRoot = path.join(snapshotRoot, ".agents");
+    const target = path.join(agentsRoot, "pm");
+    await mkdir(agentsRoot, { recursive: true });
+    await rm(target, { recursive: true, force: true });
+    await symlink(sandboxPmPath, target, process.platform === "win32" ? "junction" : "dir");
+}
 async function initializeLinkedTestSandboxes(layout, initialize = runInit, includeTrackerData = true) {
     const initOptions = { defaults: true, agentGuidance: "skip" };
     await initialize(undefined, { path: layout.schemaProjectPmPath }, initOptions);
@@ -1326,6 +1378,12 @@ function buildLinkedTestExecutionContext(params) {
     const selectedSandboxGlobalItemCount = trackerMode
         ? params.counts.trackerGlobalItemCount
         : params.counts.schemaGlobalItemCount;
+    const workingDirectory = params.workspaceContextMode === "snapshot"
+        ? params.layout.workspaceSnapshotRoot
+        : params.workspaceContextMode === "isolated"
+            ? params.layout.workspaceIsolatedRoot
+            : params.sourceWorkspaceRoot;
+    const exposedSourceWorkspaceRoot = params.workspaceContextMode === "isolated" ? "" : workingDirectory;
     return {
         requested_pm_context_mode: params.requestedPmContextMode,
         pm_context_mode: params.effectivePmContextMode,
@@ -1346,9 +1404,14 @@ function buildLinkedTestExecutionContext(params) {
                 params.counts.sourceGlobalItemCount !== selectedSandboxGlobalItemCount),
         project_extensions_seeded: Boolean(params.sourceRoots),
         global_extensions_seeded: Boolean(params.sourceRoots),
+        requested_workspace_context_mode: params.requestedWorkspaceContextMode,
+        workspace_context_mode: params.workspaceContextMode,
+        working_directory: workingDirectory,
+        source_workspace_root: exposedSourceWorkspaceRoot,
+        trust: params.trust,
     };
 }
-function resolveLinkedTestCommandContext(params) {
+async function resolveLinkedTestCommandContext(params) {
     const linkedOverridePmContextMode = typeof params.linkedTest.pm_context_mode === "string" &&
         params.linkedTest.pm_context_mode.trim().length > 0
         ? parsePmContextMode(params.linkedTest.pm_context_mode)
@@ -1366,6 +1429,15 @@ function resolveLinkedTestCommandContext(params) {
         ? "auto"
         : resolveLinkedTestRequestedContextMode(params.linkedTest, params.runLevelPmContextMode, params.options?.overrideLinkedPmContext === true);
     const effectivePmContextMode = resolveLinkedTestEffectiveContextMode(requestedPmContextMode, isPmTrackerReadCommand);
+    const selectedSandboxProjectPmPath = effectivePmContextMode === "tracker"
+        ? params.layout.trackerProjectPmPath
+        : params.layout.schemaProjectPmPath;
+    if (params.workspaceContextMode === "snapshot") {
+        await bindSnapshotTracker(params.layout.workspaceSnapshotRoot, selectedSandboxProjectPmPath);
+    }
+    const trust = params.options?.pmRoot
+        ? await resolveLinkedTestTrust(params.options.pmRoot, params.linkedTest, params.currentSourceRef)
+        : await resolveLinkedTestTrust(params.layout.root, params.linkedTest, params.currentSourceRef);
     return {
         linkedOverridePmContextMode,
         executionContext: buildLinkedTestExecutionContext({
@@ -1377,6 +1449,10 @@ function resolveLinkedTestCommandContext(params) {
             requestedPmContextMode,
             effectivePmContextMode,
             autoPmContextApplied,
+            requestedWorkspaceContextMode: params.requestedWorkspaceContextMode,
+            workspaceContextMode: params.workspaceContextMode,
+            sourceWorkspaceRoot: params.sourceWorkspaceRoot,
+            trust,
         }),
     };
 }
@@ -1401,14 +1477,47 @@ function buildLinkedTestAssertionFailureResult(linkedTest, executionContext, err
         error,
     };
 }
-function resolveLinkedTestPreflightResult(params) {
+function buildLinkedTestTrustRefusalResult(linkedTest, executionContext, error) {
+    return {
+        command: linkedTest.command,
+        path: linkedTest.path,
+        status: "failed",
+        exit_code: 1,
+        failure_category: "trust_refusal",
+        execution_context: executionContext,
+        error,
+    };
+}
+/** Build the fail-closed result for a command this clone has not trusted. */
+function resolveLinkedTestTrustPreflightResult(params) {
+    if (params.executionContext.trust.trusted)
+        return null;
+    const overrideRequested = params.options?.allowUntrustedLinkedTests === true;
+    const policyEnabled = params.options?.untrustedLinkedTestsPolicyEnabled === true;
+    if (overrideRequested && policyEnabled)
+        return null;
+    const recovery = policyEnabled
+        ? "Retry with --allow-untrusted-linked-tests for this invocation, or acknowledge the current commands with --acknowledge-linked-tests."
+        : "Set testing.allow_untrusted_linked_tests=true, then retry with --allow-untrusted-linked-tests; alternatively acknowledge the current commands with --acknowledge-linked-tests.";
+    return buildLinkedTestTrustRefusalResult(params.linkedTest, params.executionContext, `Linked test command is not trusted by this clone (source_ref=${params.executionContext.trust.source_ref ?? "unknown"}, current_ref=${params.executionContext.trust.current_source_ref ?? "unknown"}). ${recovery}`);
+}
+/** Resolve missing-command and runtime-safety skips before policy checks. */
+function resolveLinkedTestSafetyPreflightResult(params) {
     if (!params.linkedTest.command) {
         return buildLinkedTestSkippedResult(params.linkedTest, params.executionContext, "No command configured for this linked test.");
     }
     const runtimeSafetySkipReason = getRuntimeSafetySkipReason(params.linkedTest.command);
-    if (runtimeSafetySkipReason) {
-        return buildLinkedTestSkippedResult(params.linkedTest, params.executionContext, runtimeSafetySkipReason);
-    }
+    return runtimeSafetySkipReason
+        ? buildLinkedTestSkippedResult(params.linkedTest, params.executionContext, runtimeSafetySkipReason)
+        : null;
+}
+function resolveLinkedTestPreflightResult(params) {
+    const safetyFailure = resolveLinkedTestSafetyPreflightResult(params);
+    if (safetyFailure)
+        return safetyFailure;
+    const trustFailure = resolveLinkedTestTrustPreflightResult(params);
+    if (trustFailure)
+        return trustFailure;
     const failOnMismatchByDefault = params.executionContext.pm_context_mode === "schema" &&
         params.executionContext.is_pm_tracker_read_command &&
         params.executionContext.mismatch_detected;
@@ -1451,11 +1560,20 @@ function buildLinkedTestExecutionEnv(params) {
     executionEnv.FORCE_COLOR = "0";
     executionEnv.PM_PATH = params.executionContext.sandbox_project_pm_path;
     executionEnv.PM_GLOBAL_PATH = params.executionContext.sandbox_global_pm_path;
-    executionEnv.PM_SOURCE_WORKSPACE_ROOT =
-        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";
+    if (params.executionContext.workspace_context_mode === "isolated") {
+        delete executionEnv.PM_SOURCE_WORKSPACE_ROOT;
+        delete executionEnv.PM_SOURCE_PM_PATH;
+        delete executionEnv[SOURCE_CONTEXT_ACCESS_ENV];
+    }
+    else {
+        executionEnv.PM_SOURCE_WORKSPACE_ROOT =
+            params.executionContext.source_workspace_root;
+        executionEnv.PM_SOURCE_PM_PATH =
+            params.executionContext.workspace_context_mode === "snapshot"
+                ? params.executionContext.sandbox_project_pm_path
+                : params.executionContext.source_project_pm_path;
+        executionEnv[SOURCE_CONTEXT_ACCESS_ENV] = "read_only";
+    }
     return executionEnv;
 }
 function buildLinkedTestPassedResult(linkedTest, executionContext, execution) {
@@ -1518,7 +1636,7 @@ async function runSingleLinkedTest(params) {
         total: params.total,
         timeoutMs,
         command,
-    }, params.progressMode);
+    }, params.progressMode, params.executionContext.working_directory);
     const passed = execution.exitCode === 0 &&
         !execution.timedOut &&
         !execution.maxBufferExceeded;
@@ -1532,23 +1650,36 @@ export async function runLinkedTests(tests, defaultTimeoutSeconds, options) {
     const sandboxRoot = await mkdtemp(path.join(tmpdir(), "pm-linked-test-"));
     const layout = createLinkedTestSandboxLayout(sandboxRoot);
     const runLevelPmContextMode = parsePmContextMode(options?.pmContext);
+    const runLevelWorkspaceContextMode = parseWorkspaceContextMode(options?.workspaceContext);
     const progressMode = options?.progress === true ? "always" : "auto";
     const runtimeDirectives = resolveRuntimeDirectives(options?.envSet, options?.envClear, options?.sharedHostSafe);
     const sourceRoots = options?.sourceRoots;
+    const sourceWorkspaceRoot = resolveLinkedTestSourceWorkspaceRoot();
     const includeTrackerData = linkedTestsRequireTrackerData(tests, runLevelPmContextMode, options);
+    const includeWorkspaceSnapshot = linkedTestsRequireWorkspaceSnapshot(tests, runLevelWorkspaceContextMode, options?.overrideLinkedWorkspaceContext === true);
+    const currentSourceRef = await resolveLinkedTestSourceRef(sourceWorkspaceRoot);
     try {
         await initializeLinkedTestSandboxes(layout, runInit, includeTrackerData);
+        await mkdir(layout.workspaceIsolatedRoot, { recursive: true });
         await seedLinkedTestSandboxesFromSource(layout, sourceRoots, includeTrackerData);
+        if (includeWorkspaceSnapshot) {
+            await seedLinkedTestWorkspaceSnapshot(layout, sourceWorkspaceRoot);
+        }
         const counts = await countLinkedTestSandboxItems(layout, sourceRoots);
         for (let index = 0; index < tests.length; index += 1) {
             const linkedTest = tests[index];
-            const commandContext = resolveLinkedTestCommandContext({
+            const workspaceContextMode = resolveLinkedTestWorkspaceContextMode(linkedTest, runLevelWorkspaceContextMode, options?.overrideLinkedWorkspaceContext === true);
+            const commandContext = await resolveLinkedTestCommandContext({
                 linkedTest,
                 layout,
                 counts,
                 sourceRoots,
                 runLevelPmContextMode,
                 options,
+                requestedWorkspaceContextMode: runLevelWorkspaceContextMode,
+                workspaceContextMode,
+                currentSourceRef,
+                sourceWorkspaceRoot,
             });
             const preflightResult = resolveLinkedTestPreflightResult({
                 linkedTest,
@@ -1602,7 +1733,8 @@ function linkedTestsHaveSameIdentity(left, right) {
     return (left.command === right.command &&
         left.path === right.path &&
         left.scope === right.scope &&
-        left.pm_context_mode === right.pm_context_mode);
+        left.pm_context_mode === right.pm_context_mode &&
+        left.workspace_context_mode === right.workspace_context_mode);
 }
 function appendMissingLinkedTests(current, additions) {
     const next = [...current];
@@ -1635,21 +1767,29 @@ function applyLinkedTestMutations(previous, adds, removes, removeIndexes) {
     return removeLinkedTestsBySelector(appendMissingLinkedTests(previous, adds), removes, removeIndexes);
 }
 function hasTestRuntimeDirectiveFlags(options) {
-    return ((options.envSet?.length ?? 0) > 0 ||
-        (options.envClear?.length ?? 0) > 0 ||
-        options.sharedHostSafe === true ||
-        options.pmContext !== undefined ||
-        options.overrideLinkedPmContext === true ||
-        options.failOnContextMismatch === true ||
-        options.failOnSkipped === true ||
-        options.failOnEmptyTestRun === true ||
-        options.requireAssertionsForPm === true ||
-        options.checkContext === true ||
-        options.autoPmContext === true);
+    return [
+        (options.envSet?.length ?? 0) > 0,
+        (options.envClear?.length ?? 0) > 0,
+        options.sharedHostSafe === true,
+        options.pmContext !== undefined,
+        options.overrideLinkedPmContext === true,
+        options.failOnContextMismatch === true,
+        options.failOnSkipped === true,
+        options.failOnEmptyTestRun === true,
+        options.requireAssertionsForPm === true,
+        options.checkContext === true,
+        options.autoPmContext === true,
+        options.workspaceContext !== undefined,
+        options.overrideLinkedWorkspaceContext === true,
+        options.allowUntrustedLinkedTests === true,
+    ].some(Boolean);
 }
 function assertTestRunFlagUsage(options) {
     if (hasTestRuntimeDirectiveFlags(options) && options.run !== true) {
-        throw new PmCliError("--env-set, --env-clear, --shared-host-safe, --pm-context, --override-linked-pm-context, --fail-on-context-mismatch, --fail-on-skipped, --fail-on-empty-test-run, --require-assertions-for-pm, --check-context, and --auto-pm-context require --run", EXIT_CODE.USAGE);
+        throw new PmCliError("--env-set, --env-clear, --shared-host-safe, --pm-context, --override-linked-pm-context, --workspace-context, --override-linked-workspace-context, --allow-untrusted-linked-tests, --fail-on-context-mismatch, --fail-on-skipped, --fail-on-empty-test-run, --require-assertions-for-pm, --check-context, and --auto-pm-context require --run", EXIT_CODE.USAGE);
+    }
+    if (options.acknowledgeLinkedTests === true && options.run === true) {
+        throw new PmCliError("--acknowledge-linked-tests records trust without executing commands; run it separately before --run", EXIT_CODE.USAGE);
     }
     const hasSelectorFlags = options.match !== undefined ||
         options.onlyIndex !== undefined ||
@@ -1749,6 +1889,11 @@ async function executeSelectedLinkedTests(params) {
         requireAssertionsForPm: options.requireAssertionsForPm,
         checkContext: options.checkContext,
         autoPmContext: options.autoPmContext,
+        workspaceContext: options.workspaceContext,
+        overrideLinkedWorkspaceContext: options.overrideLinkedWorkspaceContext,
+        pmRoot,
+        allowUntrustedLinkedTests: options.allowUntrustedLinkedTests,
+        untrustedLinkedTestsPolicyEnabled: params.untrustedLinkedTestsPolicyEnabled,
         sourceRoots: {
             projectPmRoot: pmRoot,
             globalPmRoot: resolveGlobalPmRoot(process.cwd()),
@@ -1798,6 +1943,8 @@ function buildTrackedTestRunSummary(params) {
             command: result.command.trim(),
             requested_pm_context_mode: result.execution_context?.requested_pm_context_mode,
             pm_context_mode: result.execution_context?.pm_context_mode,
+            workspace_context_mode: result.execution_context?.workspace_context_mode,
+            trust_reason: result.execution_context?.trust.reason,
         })),
     };
 }
@@ -1854,6 +2001,12 @@ function buildTestMeasurementProjection(options, runs, recordedRun) {
             : diffTestRunMeasurements(runs, options.metricDiff),
     };
 }
+/** Acknowledge current linked commands only when the dedicated mode is active. */
+async function maybeAcknowledgeLinkedTests(options, pmRoot, tests) {
+    if (options.acknowledgeLinkedTests !== true)
+        return undefined;
+    return acknowledgeLinkedTests(pmRoot, tests, nowIso());
+}
 /** Implements run test for the public runtime surface of this module. */
 export async function runTest(id, options, global) {
     const stdinResolver = createStdinTokenResolver();
@@ -1869,10 +2022,11 @@ export async function runTest(id, options, global) {
     const resolvedAdds = await stdinResolver.resolveList(options.add, "--add");
     const resolvedAddJsons = await stdinResolver.resolveList(options.addJson, "--add-json");
     const resolvedRemoves = await stdinResolver.resolveList(options.remove, "--remove");
-    const adds = [
+    const parsedAdds = [
         ...parseAddEntries(resolvedAdds),
         ...parseAddJsonEntries(resolvedAddJsons),
     ];
+    const adds = (await attachLinkedTestMutationProvenance(parsedAdds, resolveAuthor(options.author, settings.author_default), nowIso())) ?? [];
     const removes = parseRemoveEntries(resolvedRemoves);
     const removeIndexes = parseRemoveIndexes(options.removeIndex);
     const item = await resolveLinkedTestItem({
@@ -1886,17 +2040,22 @@ export async function runTest(id, options, global) {
         removeIndexes,
     });
     const runOptions = resolveTestRunOptions(options, item.tests);
+    const trustAcknowledgement = await maybeAcknowledgeLinkedTests(options, pmRoot, item.tests);
     const runStartedAt = options.run === true ? nowIso() : undefined;
     const runResults = await executeSelectedLinkedTests({
         options,
         runOptions,
         pmRoot,
+        untrustedLinkedTestsPolicyEnabled: settings.testing.allow_untrusted_linked_tests,
     });
     const failureCategories = countFailureCategories(runResults);
     const failOnSkippedTriggered = options.run === true &&
         options.failOnSkipped === true &&
         runResults.some((entry) => entry.status === "skipped");
     const warnings = buildTestWarnings(options, runOptions.runSelection, runResults);
+    if (trustAcknowledgement) {
+        warnings.push(`linked_test_trust_acknowledged:${trustAcknowledgement.acknowledged}`);
+    }
     const recordedRun = await recordTestRunSummary({
         options,
         pmRoot,
@@ -1972,4 +2131,4 @@ export const _testOnlyTestCommand = {
     summarizeRunResultStatuses,
 };
 //# sourceMappingURL=execution.js.map
-//# debugId=5fe0ee3e-9590-56fc-b238-e56ff1970e52
+//# debugId=7659721c-21f5-55da-8cce-31b290de5bfb

package/dist/sdk/test/parsers.d.ts

@@ -20,6 +20,10 @@ export declare const LINKED_TEST_ENV_NAME_PATTERN: RegExp;
 export declare const LINKED_TEST_PM_CONTEXT_MODE_VALUES: readonly ["schema", "tracker", "auto"];
 /** Restricts linked test pm context mode values accepted by command, SDK, and storage contracts. */
 export type LinkedTestPmContextMode = (typeof LINKED_TEST_PM_CONTEXT_MODE_VALUES)[number];
+/** Supported values accepted by the linked test workspace context contract. */
+export declare const LINKED_TEST_WORKSPACE_CONTEXT_MODE_VALUES: readonly ["source", "isolated", "snapshot"];
+/** Restricts source-workspace modes accepted by command and storage contracts. */
+export type LinkedTestWorkspaceContextMode = (typeof LINKED_TEST_WORKSPACE_CONTEXT_MODE_VALUES)[number];
 /** Implements parse linked test env set for the public runtime surface of this module. */
 export declare function parseLinkedTestEnvSet(raw: string | undefined, optionName: string): Record<string, string> | undefined;
 /** Implements parse linked test env clear for the public runtime surface of this module. */
@@ -28,6 +32,8 @@ export declare function parseLinkedTestEnvClear(raw: string | undefined, optionN
 export declare function parseLinkedTestBoolean(raw: string | undefined, optionName: string, fieldLabel: string): boolean | undefined;
 /** Implements parse linked test context mode for the public runtime surface of this module. */
 export declare function parseLinkedTestContextMode(raw: string | undefined, optionName: string): LinkedTest["pm_context_mode"] | undefined;
+/** Parse one linked-test source-workspace context mode. */
+export declare function parseLinkedTestWorkspaceContextMode(raw: string | undefined, optionName: string): LinkedTest["workspace_context_mode"] | undefined;
 /** Implements parse linked test string list for the public runtime surface of this module. */
 export declare function parseLinkedTestStringList(raw: string | undefined): string[] | undefined;
 /** Implements parse linked test regex list for the public runtime surface of this module. */

package/dist/sdk/test/parsers.js

@@ -4,7 +4,7 @@
  * 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]="74163bed-a473-543e-ae6a-0d5091b3b3a9")}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]="64adcc3c-3646-5990-9442-4c4374a2dc7d")}catch(e){}}();
 import { parseOptionalNumber } from "../../core/item/parse.js";
 import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
@@ -43,6 +43,12 @@ export const LINKED_TEST_PM_CONTEXT_MODE_VALUES = [
     "tracker",
     "auto",
 ];
+/** Supported values accepted by the linked test workspace context contract. */
+export const LINKED_TEST_WORKSPACE_CONTEXT_MODE_VALUES = [
+    "source",
+    "isolated",
+    "snapshot",
+];
 /** Implements parse linked test env set for the public runtime surface of this module. */
 export function parseLinkedTestEnvSet(raw, optionName) {
     if (!raw) {
@@ -119,6 +125,17 @@ export function parseLinkedTestContextMode(raw, optionName) {
     }
     throw new PmCliError(`${optionName} pm_context_mode must be one of: ${LINKED_TEST_PM_CONTEXT_MODE_VALUES.join(", ")}`, EXIT_CODE.USAGE);
 }
+/** Parse one linked-test source-workspace context mode. */
+export function parseLinkedTestWorkspaceContextMode(raw, optionName) {
+    if (!raw) {
+        return undefined;
+    }
+    const value = raw.trim().toLowerCase();
+    if (LINKED_TEST_WORKSPACE_CONTEXT_MODE_VALUES.includes(value)) {
+        return value;
+    }
+    throw new PmCliError(`${optionName} workspace_context_mode must be one of: ${LINKED_TEST_WORKSPACE_CONTEXT_MODE_VALUES.join(", ")}`, EXIT_CODE.USAGE);
+}
 /** Implements parse linked test string list for the public runtime surface of this module. */
 export function parseLinkedTestStringList(raw) {
     if (!raw) {
@@ -476,6 +493,7 @@ function parseLinkedTestJsonEntry(rawEntry, label, optionName) {
         !LINKED_TEST_PM_CONTEXT_MODE_VALUES.includes(pmContextModeValue)) {
         throw fail(`field "pm_context_mode" must be one of: ${LINKED_TEST_PM_CONTEXT_MODE_VALUES.join(", ")}`);
     }
+    const workspaceContextModeValue = parseLinkedTestWorkspaceContextMode(readJsonEntryString(entry, "workspace_context_mode", fail), `${optionName} ${label}`);
     const noteValue = readJsonEntryString(entry, "note", fail);
     return {
         command,
@@ -483,6 +501,7 @@ function parseLinkedTestJsonEntry(rawEntry, label, optionName) {
         scope: readJsonEntryScope(entry, fail),
         timeout_seconds: readJsonEntryTimeoutSeconds(entry, fail),
         pm_context_mode: pmContextModeValue,
+        workspace_context_mode: workspaceContextModeValue,
         env_set: readJsonEntryEnvSet(entry, fail),
         env_clear: readJsonEntryEnvClear(entry, fail),
         shared_host_safe: readJsonEntryBoolean(entry, "shared_host_safe", fail),
@@ -524,4 +543,4 @@ export const _testOnlyLinkedTestParsers = {
     parseLinkedTestJsonEntry,
 };
 //# sourceMappingURL=parsers.js.map
-//# debugId=74163bed-a473-543e-ae6a-0d5091b3b3a9
+//# debugId=64adcc3c-3646-5990-9442-4c4374a2dc7d

package/dist/sdk/test/trust.d.ts

@@ -0,0 +1,33 @@
+import type { LinkedTest } from "../../types/index.js";
+/** Classification of one linked-test command against the current clone. */
+export interface LinkedTestTrustDecision {
+    /** Stable hash binding the decision to command, context, and provenance. */
+    fingerprint: string;
+    /** Whether execution may proceed without an untrusted-command override. */
+    trusted: boolean;
+    /** Machine-readable reason for the decision. */
+    reason: "legacy" | "local_mutation" | "local_source_ref" | "acknowledged" | "invalid_provenance" | "foreign_source_ref";
+    /** Source ref recorded when the command entered tracker data. */
+    source_ref?: string;
+    /** Current source ref used for the local decision. */
+    current_source_ref?: string;
+}
+/** Resolve the current Git branch without invoking a shell. */
+export declare function resolveLinkedTestSourceRef(cwd?: string): Promise<string | undefined>;
+/** Resolve the source checkout shared by linked-test provenance and execution. */
+export declare function resolveLinkedTestSourceWorkspaceRoot(cwd?: string): string;
+/** Attach immutable author/time/ref provenance to newly stored commands. */
+export declare function attachLinkedTestProvenance(tests: LinkedTest[] | undefined, author: string, createdAt: string, sourceRef: string | undefined): LinkedTest[] | undefined;
+/** Attach provenance while avoiding Git inspection for an empty mutation. */
+export declare function attachLinkedTestMutationProvenance(tests: LinkedTest[] | undefined, author: string, createdAt: string): Promise<LinkedTest[] | undefined>;
+/** Produce the clone-local trust identity for one linked-test entry. */
+export declare function linkedTestTrustFingerprint(test: LinkedTest): string;
+/** Resolve whether one stored command is trusted by this clone. */
+export declare function resolveLinkedTestTrust(pmRoot: string, test: LinkedTest, currentSourceRef?: string): Promise<LinkedTestTrustDecision>;
+/** Resolve a collection with one ledger read for validation and batch runs. */
+export declare function resolveLinkedTestTrustBatch(pmRoot: string, tests: LinkedTest[], currentSourceRef?: string): Promise<LinkedTestTrustDecision[]>;
+/** Persist explicit clone-local acknowledgement for selected linked tests. */
+export declare function acknowledgeLinkedTests(pmRoot: string, tests: LinkedTest[], acknowledgedAt: string): Promise<{
+    acknowledged: number;
+    fingerprints: string[];
+}>;