@unbrained/pm-cli 2026.6.30 → 2026.7.2

package/dist/cli/commands/test.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]="588f0e3a-3f1c-56d9-8908-c8003ae549cd")}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]="caa941ed-c848-506c-9a3c-3d4959be0246")}catch(e){}}();
 import { spawn } from "node:child_process";
 import { cp, mkdir, mkdtemp, readdir, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
@@ -276,25 +276,24 @@ function extractPmInvocationArgsFromSegment(segment) {
     if (executable === "node" && args.length > 0 && isPmCliScriptToken(args[0])) {
         return args.slice(1);
     }
+    return extractPackageManagerPmInvocationArgs(executable, args);
+}
+function extractPackageManagerPmInvocationArgs(executable, args) {
+    const parsed = parsePackageManagerPmInvocation(executable, args);
+    if (!parsed || (!isPmExecutableToken(parsed.command) && !isPmCliPackageToken(parsed.command))) {
+        return null;
+    }
+    return parsed.args;
+}
+function parsePackageManagerPmInvocation(executable, args) {
     if (executable === "npx" || executable === "bunx") {
-        const parsed = parseNpxCommand(args);
-        /* c8 ignore start -- npx launcher edge permutations are covered by command-parser integration suites */
-        if (parsed && (isPmExecutableToken(parsed.command) || isPmCliPackageToken(parsed.command))) {
-            return parsed.args;
-        }
-        /* c8 ignore stop */
+        return parseNpxCommand(args);
     }
     if (executable === "pnpm") {
-        const parsed = parsePnpmDlxCommand(args);
-        if (parsed && (isPmExecutableToken(parsed.command) || isPmCliPackageToken(parsed.command))) {
-            return parsed.args;
-        }
+        return parsePnpmDlxCommand(args);
     }
     if (executable === "npm") {
-        const parsed = parseNpmExecCommand(args);
-        if (parsed && (isPmExecutableToken(parsed.command) || isPmCliPackageToken(parsed.command))) {
-            return parsed.args;
-        }
+        return parseNpmExecCommand(args);
     }
     return null;
 }
@@ -452,30 +451,23 @@ function segmentInvokesUnsafeDirectTestRunner(normalizedSegment) {
         return true;
     }
     if (executable === "node") {
-        return (args.includes("--test") ||
-            args.some((arg) => arg === "vitest" || arg === "vitest.mjs" || arg.endsWith("/vitest") || arg.endsWith("/vitest.mjs")));
+        return nodeArgsInvokeUnsafeDirectTestRunner(args);
     }
+    return packageManagerInvokesUnsafeDirectTestRunner(executable, args);
+}
+function nodeArgsInvokeUnsafeDirectTestRunner(args) {
+    return (args.includes("--test") ||
+        args.some((arg) => arg === "vitest" || arg === "vitest.mjs" || arg.endsWith("/vitest") || arg.endsWith("/vitest.mjs")));
+}
+function packageManagerInvokesUnsafeDirectTestRunner(executable, args) {
     if (executable === "npx" || executable === "bunx") {
         return isDirectTestRunnerSubcommand(parseNpxCommand(args)?.command);
     }
-    if (executable === "pnpm") {
-        const dlx = parsePnpmDlxCommand(args);
-        if (isDirectTestRunnerSubcommand(dlx?.command)) {
-            return true;
-        }
-        return firstDirectTestRunnerSubcommand(executable, args) === "vitest";
-    }
-    if (executable === "npm") {
-        const exec = parseNpmExecCommand(args);
-        if (isDirectTestRunnerSubcommand(exec?.command)) {
-            return true;
-        }
-        return firstDirectTestRunnerSubcommand(executable, args) === "vitest";
-    }
-    if (executable === "yarn" || executable === "bun") {
-        return firstDirectTestRunnerSubcommand(executable, args) === "vitest";
+    if (executable === "pnpm" || executable === "npm") {
+        return (isDirectTestRunnerSubcommand(parsePackageManagerPmInvocation(executable, args)?.command) ||
+            firstDirectTestRunnerSubcommand(executable, args) === "vitest");
     }
-    return false;
+    return (executable === "yarn" || executable === "bun") && firstDirectTestRunnerSubcommand(executable, args) === "vitest";
 }
 function assertSandboxSafeTestRunnerCommand(command) {
     const normalized = normalizeCommandForValidation(command);
@@ -496,52 +488,48 @@ function getRuntimeSafetySkipReason(command) {
 function parseAddEntries(raw) {
     if (!raw)
         return [];
-    return raw.map((entry) => {
-        const trimmed = entry.trim();
-        const kv = looksLikeStructuredLinkedTestEntry(trimmed)
-            ? normalizeStructuredLinkedTestEntry(parseCsvKv(entry, "--add"), "--add")
-            : { command: trimmed };
-        const command = kv.command?.trim() || undefined;
-        const filePath = kv.path?.trim() || undefined;
-        if (!command) {
-            throw new PmCliError("--add requires command=<value> or a bare command (path=<value> is optional metadata)", EXIT_CODE.USAGE);
-        }
-        const sharedHostSafe = parseLinkedTestBooleanValue(kv.shared_host_safe?.trim(), "--add", "shared_host_safe");
-        /* c8 ignore start -- command is guaranteed present after the non-empty guard above */
-        if (command) {
-            assertNoRecursiveTestAllCommand(command);
-            assertSandboxSafeTestRunnerCommand(command);
-        }
-        /* c8 ignore stop */
-        const timeoutSecondsRaw = kv.timeout_seconds?.trim();
-        const timeoutAliasRaw = kv.timeout?.trim();
-        if (timeoutSecondsRaw && timeoutAliasRaw && timeoutSecondsRaw !== timeoutAliasRaw) {
-            throw new PmCliError("--add timeout and timeout_seconds must match when both are provided", EXIT_CODE.USAGE);
-        }
-        const timeoutRaw = timeoutSecondsRaw ?? timeoutAliasRaw;
-        const timeoutSeconds = timeoutRaw === undefined ? undefined : Math.floor(parseOptionalNumber(timeoutRaw, "timeout_seconds"));
-        const envSet = parseLinkedTestEnvSetValue(kv.env_set?.trim(), "--add");
-        const envClear = parseLinkedTestEnvClearValue(kv.env_clear?.trim(), "--add");
-        const pmContextMode = parseLinkedTestContextModeValue(kv.pm_context_mode?.trim(), "--add");
-        return {
-            command,
-            path: filePath,
-            scope: ensureScope(kv.scope),
-            timeout_seconds: timeoutSeconds,
-            pm_context_mode: pmContextMode,
-            env_set: envSet,
-            env_clear: envClear,
-            shared_host_safe: sharedHostSafe,
-            assert_stdout_contains: parseLinkedTestStringList(kv.assert_stdout_contains?.trim()),
-            assert_stdout_regex: parseLinkedTestRegexList(kv.assert_stdout_regex?.trim(), "--add", "assert_stdout_regex"),
-            assert_stderr_contains: parseLinkedTestStringList(kv.assert_stderr_contains?.trim()),
-            assert_stderr_regex: parseLinkedTestRegexList(kv.assert_stderr_regex?.trim(), "--add", "assert_stderr_regex"),
-            assert_stdout_min_lines: parseLinkedTestMinLines(kv.assert_stdout_min_lines?.trim(), "--add"),
-            assert_json_field_equals: parseLinkedTestAssertionEqualsMap(kv.assert_json_field_equals?.trim(), "--add"),
-            assert_json_field_gte: parseLinkedTestAssertionGteMap(kv.assert_json_field_gte?.trim(), "--add"),
-            note: kv.note?.trim() || undefined,
-        };
-    });
+    return raw.map(parseAddEntry);
+}
+function parseAddEntry(entry) {
+    const trimmed = entry.trim();
+    const kv = looksLikeStructuredLinkedTestEntry(trimmed)
+        ? normalizeStructuredLinkedTestEntry(parseCsvKv(entry, "--add"), "--add")
+        : { command: trimmed };
+    const command = trimLinkedTestEntryField(kv.command);
+    if (!command) {
+        throw new PmCliError("--add requires command=<value> or a bare command (path=<value> is optional metadata)", EXIT_CODE.USAGE);
+    }
+    assertNoRecursiveTestAllCommand(command);
+    assertSandboxSafeTestRunnerCommand(command);
+    return {
+        command,
+        path: trimLinkedTestEntryField(kv.path),
+        scope: ensureScope(kv.scope),
+        timeout_seconds: parseLinkedTestTimeoutSeconds(trimLinkedTestEntryField(kv.timeout_seconds), trimLinkedTestEntryField(kv.timeout)),
+        pm_context_mode: parseLinkedTestContextModeValue(trimLinkedTestEntryField(kv.pm_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"),
+        assert_stdout_contains: parseLinkedTestStringList(trimLinkedTestEntryField(kv.assert_stdout_contains)),
+        assert_stdout_regex: parseLinkedTestRegexList(trimLinkedTestEntryField(kv.assert_stdout_regex), "--add", "assert_stdout_regex"),
+        assert_stderr_contains: parseLinkedTestStringList(trimLinkedTestEntryField(kv.assert_stderr_contains)),
+        assert_stderr_regex: parseLinkedTestRegexList(trimLinkedTestEntryField(kv.assert_stderr_regex), "--add", "assert_stderr_regex"),
+        assert_stdout_min_lines: parseLinkedTestMinLines(trimLinkedTestEntryField(kv.assert_stdout_min_lines), "--add"),
+        assert_json_field_equals: parseLinkedTestAssertionEqualsMap(trimLinkedTestEntryField(kv.assert_json_field_equals), "--add"),
+        assert_json_field_gte: parseLinkedTestAssertionGteMap(trimLinkedTestEntryField(kv.assert_json_field_gte), "--add"),
+        note: trimLinkedTestEntryField(kv.note),
+    };
+}
+function trimLinkedTestEntryField(value) {
+    const trimmed = value?.trim();
+    return trimmed && trimmed.length > 0 ? trimmed : undefined;
+}
+function parseLinkedTestTimeoutSeconds(timeoutSecondsRaw, timeoutAliasRaw) {
+    if (timeoutSecondsRaw && timeoutAliasRaw && timeoutSecondsRaw !== timeoutAliasRaw) {
+        throw new PmCliError("--add timeout and timeout_seconds must match when both are provided", EXIT_CODE.USAGE);
+    }
+    const timeoutRaw = timeoutSecondsRaw ?? timeoutAliasRaw;
+    return timeoutRaw === undefined ? undefined : Math.floor(parseOptionalNumber(timeoutRaw, "timeout_seconds"));
 }
 /* c8 ignore start -- add-json validation matrix is covered by linked-test parser integration suites */
 function parseAddJsonEntries(raw) {
@@ -1121,47 +1109,11 @@ function compareAssertionValues(actual, expected) {
 /* c8 ignore start -- assertion failure-path permutations are covered by linked-test integration fixtures */
 function evaluateLinkedTestAssertions(linkedTest, stdout, stderr) {
     const failures = [];
-    for (const expected of linkedTest.assert_stdout_contains ?? []) {
-        if (!stdout.includes(expected)) {
-            failures.push(`stdout missing required text: "${expected}"`);
-        }
-    }
-    for (const pattern of linkedTest.assert_stdout_regex ?? []) {
-        try {
-            const regex = new RegExp(pattern, "m");
-            if (!regex.test(stdout)) {
-                failures.push(`stdout failed regex assertion: /${pattern}/m`);
-            }
-        }
-        catch (error) {
-            failures.push(`stdout regex assertion is invalid: /${pattern}/ (${error instanceof Error ? error.message : String(error)})`);
-        }
-    }
-    for (const expected of linkedTest.assert_stderr_contains ?? []) {
-        if (!stderr.includes(expected)) {
-            failures.push(`stderr missing required text: "${expected}"`);
-        }
-    }
-    for (const pattern of linkedTest.assert_stderr_regex ?? []) {
-        try {
-            const regex = new RegExp(pattern, "m");
-            if (!regex.test(stderr)) {
-                failures.push(`stderr failed regex assertion: /${pattern}/m`);
-            }
-        }
-        catch (error) {
-            failures.push(`stderr regex assertion is invalid: /${pattern}/ (${error instanceof Error ? error.message : String(error)})`);
-        }
-    }
-    if (typeof linkedTest.assert_stdout_min_lines === "number") {
-        const lineCount = stdout
-            .split(/\r?\n/)
-            .map((line) => line.trim())
-            .filter((line) => line.length > 0).length;
-        if (lineCount < linkedTest.assert_stdout_min_lines) {
-            failures.push(`stdout line count ${lineCount} is below required minimum ${linkedTest.assert_stdout_min_lines}`);
-        }
-    }
+    failures.push(...evaluateContainsAssertions("stdout", stdout, linkedTest.assert_stdout_contains));
+    failures.push(...evaluateRegexAssertions("stdout", stdout, linkedTest.assert_stdout_regex));
+    failures.push(...evaluateContainsAssertions("stderr", stderr, linkedTest.assert_stderr_contains));
+    failures.push(...evaluateRegexAssertions("stderr", stderr, linkedTest.assert_stderr_regex));
+    failures.push(...evaluateStdoutLineCountAssertion(stdout, linkedTest.assert_stdout_min_lines));
     const jsonEqualsAssertions = linkedTest.assert_json_field_equals ?? {};
     const jsonGteAssertions = linkedTest.assert_json_field_gte ?? {};
     const needsJsonAssertions = Object.keys(jsonEqualsAssertions).length > 0 || Object.keys(jsonGteAssertions).length > 0;
@@ -1204,6 +1156,40 @@ function evaluateLinkedTestAssertions(linkedTest, stdout, stderr) {
     return failures;
 }
 /* c8 ignore stop */
+function evaluateContainsAssertions(streamName, output, expectedValues) {
+    const failures = [];
+    for (const expected of expectedValues ?? []) {
+        if (!output.includes(expected)) {
+            failures.push(`${streamName} missing required text: "${expected}"`);
+        }
+    }
+    return failures;
+}
+function evaluateRegexAssertions(streamName, output, patterns) {
+    const failures = [];
+    for (const pattern of patterns ?? []) {
+        try {
+            const regex = new RegExp(pattern, "m");
+            if (!regex.test(output)) {
+                failures.push(`${streamName} failed regex assertion: /${pattern}/m`);
+            }
+        }
+        catch (error) {
+            failures.push(`${streamName} regex assertion is invalid: /${pattern}/ (${error instanceof Error ? error.message : String(error)})`);
+        }
+    }
+    return failures;
+}
+function evaluateStdoutLineCountAssertion(stdout, minimum) {
+    if (typeof minimum !== "number") {
+        return [];
+    }
+    const lineCount = stdout
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0).length;
+    return lineCount < minimum ? [`stdout line count ${lineCount} is below required minimum ${minimum}`] : [];
+}
 const EMPTY_LINKED_TEST_RUN_PATTERNS = [
     { code: "no_projects_matched_filters", regex: /\bNo projects matched the filters\b/i },
     { code: "no_test_files_found", regex: /\bNo test files found\b/i },
@@ -1220,303 +1206,283 @@ function detectEmptyLinkedTestRun(stdout, stderr) {
     }
     return null;
 }
-/* c8 ignore start -- linked-test orchestration branch matrix is covered by end-to-end command integration runs */
+function createLinkedTestSandboxLayout(sandboxRoot) {
+    return {
+        root: sandboxRoot,
+        schemaProjectPmPath: path.join(sandboxRoot, "schema", "project", ".agents", "pm"),
+        schemaGlobalPmPath: path.join(sandboxRoot, "schema", "global"),
+        trackerProjectPmPath: path.join(sandboxRoot, "tracker", "project", ".agents", "pm"),
+        trackerGlobalPmPath: path.join(sandboxRoot, "tracker", "global"),
+    };
+}
+async function initializeLinkedTestSandboxes(layout) {
+    await runInit(undefined, { path: layout.schemaProjectPmPath });
+    await runInit(undefined, { path: layout.schemaGlobalPmPath });
+    await runInit(undefined, { path: layout.trackerProjectPmPath });
+    await runInit(undefined, { path: layout.trackerGlobalPmPath });
+}
+async function seedLinkedTestSandboxesFromSource(layout, sourceRoots) {
+    if (!sourceRoots) {
+        return;
+    }
+    await seedLinkedTestSandbox(layout.schemaProjectPmPath, layout.schemaGlobalPmPath, sourceRoots);
+    await seedLinkedTestSandbox(layout.trackerProjectPmPath, layout.trackerGlobalPmPath, sourceRoots);
+    await seedLinkedTestTrackerData(sourceRoots.projectPmRoot, layout.trackerProjectPmPath);
+    await seedLinkedTestTrackerData(sourceRoots.globalPmRoot, layout.trackerGlobalPmPath);
+}
+async function countLinkedTestSandboxItems(layout, sourceRoots) {
+    return {
+        sourceProjectItemCount: sourceRoots ? await countLinkedTestItemFiles(sourceRoots.projectPmRoot) : 0,
+        sourceGlobalItemCount: sourceRoots ? await countLinkedTestItemFiles(sourceRoots.globalPmRoot) : 0,
+        schemaProjectItemCount: await countLinkedTestItemFiles(layout.schemaProjectPmPath),
+        schemaGlobalItemCount: await countLinkedTestItemFiles(layout.schemaGlobalPmPath),
+        trackerProjectItemCount: await countLinkedTestItemFiles(layout.trackerProjectPmPath),
+        trackerGlobalItemCount: await countLinkedTestItemFiles(layout.trackerGlobalPmPath),
+    };
+}
+function buildLinkedTestExecutionContext(params) {
+    const trackerMode = params.effectivePmContextMode === "tracker";
+    const selectedSandboxProjectPmPath = trackerMode ? params.layout.trackerProjectPmPath : params.layout.schemaProjectPmPath;
+    const selectedSandboxGlobalPmPath = trackerMode ? params.layout.trackerGlobalPmPath : params.layout.schemaGlobalPmPath;
+    const selectedSandboxProjectItemCount = trackerMode ? params.counts.trackerProjectItemCount : params.counts.schemaProjectItemCount;
+    const selectedSandboxGlobalItemCount = trackerMode ? params.counts.trackerGlobalItemCount : params.counts.schemaGlobalItemCount;
+    return {
+        requested_pm_context_mode: params.requestedPmContextMode,
+        pm_context_mode: params.effectivePmContextMode,
+        auto_pm_context_applied: params.autoPmContextApplied,
+        is_pm_command: params.isPmCommand,
+        is_pm_tracker_read_command: params.isPmTrackerReadCommand,
+        source_project_pm_path: params.sourceRoots?.projectPmRoot ?? "",
+        sandbox_project_pm_path: selectedSandboxProjectPmPath,
+        source_global_pm_path: params.sourceRoots?.globalPmRoot ?? "",
+        sandbox_global_pm_path: selectedSandboxGlobalPmPath,
+        source_project_item_count: params.counts.sourceProjectItemCount,
+        sandbox_project_item_count: selectedSandboxProjectItemCount,
+        source_global_item_count: params.counts.sourceGlobalItemCount,
+        sandbox_global_item_count: selectedSandboxGlobalItemCount,
+        mismatch_detected: params.isPmCommand && params.counts.sourceProjectItemCount !== selectedSandboxProjectItemCount,
+        project_extensions_seeded: Boolean(params.sourceRoots),
+        global_extensions_seeded: Boolean(params.sourceRoots),
+    };
+}
+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)
+        : undefined;
+    const command = typeof params.linkedTest.command === "string" && params.linkedTest.command.length > 0
+        ? params.linkedTest.command
+        : undefined;
+    const isPmCommand = command ? commandInvokesPmCli(command) : false;
+    const isPmTrackerReadCommand = isPmCommand && command ? commandInvokesPmTrackerReadCommand(command) : false;
+    const autoPmContextApplied = params.options?.autoPmContext === true && isPmTrackerReadCommand;
+    const requestedPmContextMode = autoPmContextApplied
+        ? "auto"
+        : resolveLinkedTestRequestedContextMode(params.linkedTest, params.runLevelPmContextMode, params.options?.overrideLinkedPmContext === true);
+    const effectivePmContextMode = resolveLinkedTestEffectiveContextMode(requestedPmContextMode, isPmTrackerReadCommand);
+    return {
+        linkedOverridePmContextMode,
+        executionContext: buildLinkedTestExecutionContext({
+            layout: params.layout,
+            counts: params.counts,
+            sourceRoots: params.sourceRoots,
+            isPmCommand,
+            isPmTrackerReadCommand,
+            requestedPmContextMode,
+            effectivePmContextMode,
+            autoPmContextApplied,
+        }),
+    };
+}
+function buildLinkedTestSkippedResult(linkedTest, executionContext, error) {
+    return {
+        command: linkedTest.command,
+        path: linkedTest.path,
+        status: "skipped",
+        execution_context: executionContext,
+        error,
+    };
+}
+function buildLinkedTestAssertionFailureResult(linkedTest, executionContext, error, output) {
+    return {
+        command: linkedTest.command,
+        path: linkedTest.path,
+        status: "failed",
+        exit_code: 1,
+        failure_category: "assertion_failure",
+        execution_context: executionContext,
+        ...(output ? { stdout: output.stdout, stderr: output.stderr } : {}),
+        error,
+    };
+}
+function resolveLinkedTestPreflightResult(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);
+    }
+    const failOnMismatchByDefault = params.executionContext.pm_context_mode === "schema" &&
+        params.executionContext.is_pm_tracker_read_command &&
+        params.executionContext.mismatch_detected;
+    const failOnMismatchByFlag = params.options?.failOnContextMismatch === true &&
+        params.executionContext.is_pm_command &&
+        params.executionContext.mismatch_detected;
+    if (failOnMismatchByDefault || failOnMismatchByFlag) {
+        const mismatchHint = buildPmContextMismatchHint({
+            executionContext: params.executionContext,
+            runLevelPmContextMode: params.runLevelPmContextMode,
+            linkedOverridePmContextMode: params.linkedOverridePmContextMode,
+        });
+        const mismatchPrefix = params.options?.checkContext === true
+            ? "Linked test preflight PM context mismatch detected"
+            : "Linked test PM context mismatch detected";
+        return buildLinkedTestAssertionFailureResult(params.linkedTest, params.executionContext, `${mismatchPrefix} (source_project_items=${params.executionContext.source_project_item_count}, ` +
+            `sandbox_project_items=${params.executionContext.sandbox_project_item_count}).${mismatchHint}`);
+    }
+    if (params.options?.requireAssertionsForPm === true &&
+        params.executionContext.is_pm_command &&
+        !hasLinkedTestAssertions(params.linkedTest)) {
+        return buildLinkedTestAssertionFailureResult(params.linkedTest, params.executionContext, "Linked PM command requires assertions when --require-assertions-for-pm is enabled.");
+    }
+    return null;
+}
+function buildLinkedTestExecutionEnv(params) {
+    const effectiveDirectives = resolveEffectiveLinkedTestDirectives(params.runtimeDirectives, params.linkedTest);
+    const executionEnv = { ...process.env };
+    applyEnvDirectiveStage(executionEnv, params.runtimeDirectives);
+    applyEnvDirectiveStage(executionEnv, {
+        env_set: params.linkedTest.env_set ?? {},
+        env_clear: params.linkedTest.env_clear ?? [],
+    });
+    if (effectiveDirectives.shared_host_safe) {
+        applySharedHostSafeDefaults(executionEnv);
+    }
+    executionEnv.FORCE_COLOR = "0";
+    executionEnv.PM_PATH = params.executionContext.sandbox_project_pm_path;
+    executionEnv.PM_GLOBAL_PATH = params.executionContext.sandbox_global_pm_path;
+    return executionEnv;
+}
+function buildLinkedTestPassedResult(linkedTest, executionContext, execution) {
+    return {
+        command: linkedTest.command,
+        path: linkedTest.path,
+        status: "passed",
+        exit_code: 0,
+        execution_context: executionContext,
+        stdout: execution.stdout,
+        stderr: execution.stderr,
+    };
+}
+function buildLinkedTestEmptyRunResult(params) {
+    return {
+        command: params.linkedTest.command,
+        path: params.linkedTest.path,
+        status: "failed",
+        exit_code: 1,
+        failure_category: "empty_run",
+        execution_context: params.executionContext,
+        stdout: params.execution.stdout,
+        stderr: params.execution.stderr,
+        error: `Linked test reported an empty test run (${params.emptyRunSignal}) while --fail-on-empty-test-run is enabled. ` +
+            "Update test selection or disable --fail-on-empty-test-run for this run.",
+    };
+}
+function buildLinkedTestCommandFailureResult(params) {
+    return {
+        command: params.linkedTest.command,
+        path: params.linkedTest.path,
+        status: "failed",
+        exit_code: resolveLinkedTestFailureExitCode(params.execution),
+        failure_category: classifyLinkedTestFailure(params.execution),
+        execution_context: params.executionContext,
+        stdout: params.execution.stdout,
+        stderr: params.execution.stderr,
+        error: formatLinkedTestExecutionError(params.execution, params.timeoutMs),
+    };
+}
+function buildLinkedTestPassedExecutionResult(params) {
+    if (params.options?.failOnEmptyTestRun === true) {
+        const emptyRunSignal = detectEmptyLinkedTestRun(params.execution.stdout, params.execution.stderr);
+        if (emptyRunSignal) {
+            return buildLinkedTestEmptyRunResult({ ...params, emptyRunSignal });
+        }
+    }
+    const assertionFailures = evaluateLinkedTestAssertions(params.linkedTest, params.execution.stdout, params.execution.stderr);
+    if (assertionFailures.length > 0) {
+        return buildLinkedTestAssertionFailureResult(params.linkedTest, params.executionContext, `Linked test assertion(s) failed: ${assertionFailures.join("; ")}`, params.execution);
+    }
+    return buildLinkedTestPassedResult(params.linkedTest, params.executionContext, params.execution);
+}
+async function runSingleLinkedTest(params) {
+    const command = params.linkedTest.command ?? "";
+    const timeoutMs = (params.linkedTest.timeout_seconds ?? params.defaultTimeoutSeconds ?? 120) * 1000;
+    const execution = await runLinkedTestCommand(command, timeoutMs, buildLinkedTestExecutionEnv(params), {
+        index: params.index + 1,
+        total: params.total,
+        timeoutMs,
+        command,
+    }, params.progressMode);
+    const passed = execution.exitCode === 0 && !execution.timedOut && !execution.maxBufferExceeded;
+    return passed
+        ? buildLinkedTestPassedExecutionResult({ ...params, execution })
+        : buildLinkedTestCommandFailureResult({ ...params, execution, timeoutMs });
+}
 /**
  * Implements run linked tests for the public runtime surface of this module.
  */
 export async function runLinkedTests(tests, defaultTimeoutSeconds, options) {
     const results = [];
     const sandboxRoot = await mkdtemp(path.join(tmpdir(), "pm-linked-test-"));
-    const schemaSandboxPmPath = path.join(sandboxRoot, "schema", "project", ".agents", "pm");
-    const schemaSandboxGlobalPath = path.join(sandboxRoot, "schema", "global");
-    const trackerSandboxPmPath = path.join(sandboxRoot, "tracker", "project", ".agents", "pm");
-    const trackerSandboxGlobalPath = path.join(sandboxRoot, "tracker", "global");
+    const layout = createLinkedTestSandboxLayout(sandboxRoot);
     const runLevelPmContextMode = parsePmContextMode(options?.pmContext);
     const progressMode = options?.progress === true ? "always" : "auto";
     const runtimeDirectives = resolveRuntimeDirectives(options?.envSet, options?.envClear, options?.sharedHostSafe);
-    let sourceProjectItemCount = 0;
-    let sourceGlobalItemCount = 0;
-    let schemaSandboxProjectItemCount = 0;
-    let schemaSandboxGlobalItemCount = 0;
-    let trackerSandboxProjectItemCount = 0;
-    let trackerSandboxGlobalItemCount = 0;
     const sourceRoots = options?.sourceRoots;
-    const projectExtensionsSeeded = Boolean(sourceRoots);
-    const globalExtensionsSeeded = Boolean(sourceRoots);
     try {
-        await runInit(undefined, { path: schemaSandboxPmPath });
-        await runInit(undefined, { path: schemaSandboxGlobalPath });
-        await runInit(undefined, { path: trackerSandboxPmPath });
-        await runInit(undefined, { path: trackerSandboxGlobalPath });
-        if (sourceRoots) {
-            await seedLinkedTestSandbox(schemaSandboxPmPath, schemaSandboxGlobalPath, sourceRoots);
-            await seedLinkedTestSandbox(trackerSandboxPmPath, trackerSandboxGlobalPath, sourceRoots);
-            await seedLinkedTestTrackerData(sourceRoots.projectPmRoot, trackerSandboxPmPath);
-            await seedLinkedTestTrackerData(sourceRoots.globalPmRoot, trackerSandboxGlobalPath);
-            sourceProjectItemCount = await countLinkedTestItemFiles(sourceRoots.projectPmRoot);
-            sourceGlobalItemCount = await countLinkedTestItemFiles(sourceRoots.globalPmRoot);
-        }
-        schemaSandboxProjectItemCount = await countLinkedTestItemFiles(schemaSandboxPmPath);
-        schemaSandboxGlobalItemCount = await countLinkedTestItemFiles(schemaSandboxGlobalPath);
-        trackerSandboxProjectItemCount = await countLinkedTestItemFiles(trackerSandboxPmPath);
-        trackerSandboxGlobalItemCount = await countLinkedTestItemFiles(trackerSandboxGlobalPath);
-        const buildExecutionContext = (isPmCommand, isPmTrackerReadCommand, requestedPmContextMode, effectivePmContextMode, autoPmContextApplied) => {
-            const selectedSandboxProjectPmPath = effectivePmContextMode === "tracker" ? trackerSandboxPmPath : schemaSandboxPmPath;
-            const selectedSandboxGlobalPmPath = effectivePmContextMode === "tracker" ? trackerSandboxGlobalPath : schemaSandboxGlobalPath;
-            const selectedSandboxProjectItemCount = effectivePmContextMode === "tracker" ? trackerSandboxProjectItemCount : schemaSandboxProjectItemCount;
-            const selectedSandboxGlobalItemCount = effectivePmContextMode === "tracker" ? trackerSandboxGlobalItemCount : schemaSandboxGlobalItemCount;
-            const mismatchDetected = isPmCommand && sourceProjectItemCount !== selectedSandboxProjectItemCount;
-            return {
-                requested_pm_context_mode: requestedPmContextMode,
-                pm_context_mode: effectivePmContextMode,
-                auto_pm_context_applied: autoPmContextApplied,
-                is_pm_command: isPmCommand,
-                is_pm_tracker_read_command: isPmTrackerReadCommand,
-                source_project_pm_path: sourceRoots?.projectPmRoot ?? "",
-                sandbox_project_pm_path: selectedSandboxProjectPmPath,
-                source_global_pm_path: sourceRoots?.globalPmRoot ?? "",
-                sandbox_global_pm_path: selectedSandboxGlobalPmPath,
-                source_project_item_count: sourceProjectItemCount,
-                sandbox_project_item_count: selectedSandboxProjectItemCount,
-                source_global_item_count: sourceGlobalItemCount,
-                sandbox_global_item_count: selectedSandboxGlobalItemCount,
-                mismatch_detected: mismatchDetected,
-                project_extensions_seeded: projectExtensionsSeeded,
-                global_extensions_seeded: globalExtensionsSeeded,
-            };
-        };
+        await initializeLinkedTestSandboxes(layout);
+        await seedLinkedTestSandboxesFromSource(layout, sourceRoots);
+        const counts = await countLinkedTestSandboxItems(layout, sourceRoots);
         for (let index = 0; index < tests.length; index += 1) {
             const linkedTest = tests[index];
-            const linkedOverridePmContextMode = typeof linkedTest.pm_context_mode === "string" && linkedTest.pm_context_mode.trim().length > 0
-                ? parsePmContextMode(linkedTest.pm_context_mode)
-                : undefined;
-            const isPmCommand = typeof linkedTest.command === "string" && linkedTest.command.length > 0
-                ? commandInvokesPmCli(linkedTest.command)
-                : false;
-            const isPmTrackerReadCommand = isPmCommand && typeof linkedTest.command === "string" && linkedTest.command.length > 0
-                ? commandInvokesPmTrackerReadCommand(linkedTest.command)
-                : false;
-            const autoPmContextApplied = options?.autoPmContext === true && isPmTrackerReadCommand;
-            const requestedPmContextMode = autoPmContextApplied
-                ? "auto"
-                : resolveLinkedTestRequestedContextMode(linkedTest, runLevelPmContextMode, options?.overrideLinkedPmContext === true);
-            const effectivePmContextMode = resolveLinkedTestEffectiveContextMode(requestedPmContextMode, isPmTrackerReadCommand);
-            const executionContext = buildExecutionContext(isPmCommand, isPmTrackerReadCommand, requestedPmContextMode, effectivePmContextMode, autoPmContextApplied);
-            if (!linkedTest.command) {
-                results.push({
-                    command: linkedTest.command,
-                    path: linkedTest.path,
-                    status: "skipped",
-                    execution_context: executionContext,
-                    error: "No command configured for this linked test.",
-                });
-                continue;
-            }
-            const runtimeSafetySkipReason = getRuntimeSafetySkipReason(linkedTest.command);
-            if (runtimeSafetySkipReason) {
-                results.push({
-                    command: linkedTest.command,
-                    path: linkedTest.path,
-                    status: "skipped",
-                    execution_context: executionContext,
-                    error: runtimeSafetySkipReason,
-                });
-                continue;
-            }
-            const failOnMismatchByDefault = executionContext.pm_context_mode === "schema" &&
-                executionContext.is_pm_tracker_read_command &&
-                executionContext.mismatch_detected;
-            const failOnMismatchByFlag = options?.failOnContextMismatch === true && executionContext.is_pm_command && executionContext.mismatch_detected;
-            if (failOnMismatchByDefault || failOnMismatchByFlag) {
-                const mismatchHint = buildPmContextMismatchHint({
-                    executionContext,
-                    runLevelPmContextMode,
-                    linkedOverridePmContextMode,
-                });
-                const mismatchPrefix = options?.checkContext === true ? "Linked test preflight PM context mismatch detected" : "Linked test PM context mismatch detected";
-                results.push({
-                    command: linkedTest.command,
-                    path: linkedTest.path,
-                    status: "failed",
-                    exit_code: 1,
-                    failure_category: "assertion_failure",
-                    execution_context: executionContext,
-                    error: `${mismatchPrefix} (source_project_items=${executionContext.source_project_item_count}, ` +
-                        `sandbox_project_items=${executionContext.sandbox_project_item_count}).${mismatchHint}`,
-                });
-                continue;
-            }
-            if (options?.requireAssertionsForPm === true && executionContext.is_pm_command && !hasLinkedTestAssertions(linkedTest)) {
-                results.push({
-                    command: linkedTest.command,
-                    path: linkedTest.path,
-                    status: "failed",
-                    exit_code: 1,
-                    failure_category: "assertion_failure",
-                    execution_context: executionContext,
-                    error: "Linked PM command requires assertions when --require-assertions-for-pm is enabled.",
-                });
-                continue;
-            }
-            const timeoutMs = ((linkedTest.timeout_seconds ?? defaultTimeoutSeconds ?? 120) * 1000);
-            const effectiveDirectives = resolveEffectiveLinkedTestDirectives(runtimeDirectives, linkedTest);
-            const executionEnv = { ...process.env };
-            applyEnvDirectiveStage(executionEnv, runtimeDirectives);
-            applyEnvDirectiveStage(executionEnv, {
-                env_set: linkedTest.env_set ?? {},
-                env_clear: linkedTest.env_clear ?? [],
+            const commandContext = resolveLinkedTestCommandContext({
+                linkedTest,
+                layout,
+                counts,
+                sourceRoots,
+                runLevelPmContextMode,
+                options,
             });
-            if (effectiveDirectives.shared_host_safe) {
-                applySharedHostSafeDefaults(executionEnv);
-            }
-            executionEnv.FORCE_COLOR = "0";
-            executionEnv.PM_PATH = executionContext.sandbox_project_pm_path;
-            executionEnv.PM_GLOBAL_PATH = executionContext.sandbox_global_pm_path;
-            const execution = await runLinkedTestCommand(linkedTest.command, timeoutMs, executionEnv, {
-                index: index + 1,
-                total: tests.length,
-                timeoutMs,
-                command: linkedTest.command,
-            }, progressMode);
-            const passed = execution.exitCode === 0 && !execution.timedOut && !execution.maxBufferExceeded;
-            if (passed) {
-                if (options?.failOnEmptyTestRun === true) {
-                    const emptyRunSignal = detectEmptyLinkedTestRun(execution.stdout, execution.stderr);
-                    if (emptyRunSignal) {
-                        results.push({
-                            command: linkedTest.command,
-                            path: linkedTest.path,
-                            status: "failed",
-                            exit_code: 1,
-                            failure_category: "empty_run",
-                            execution_context: executionContext,
-                            stdout: execution.stdout,
-                            stderr: execution.stderr,
-                            error: `Linked test reported an empty test run (${emptyRunSignal}) while --fail-on-empty-test-run is enabled. ` +
-                                "Update test selection or disable --fail-on-empty-test-run for this run.",
-                        });
-                        continue;
-                    }
-                }
-                const assertionFailures = evaluateLinkedTestAssertions(linkedTest, execution.stdout, execution.stderr);
-                if (assertionFailures.length > 0) {
-                    results.push({
-                        command: linkedTest.command,
-                        path: linkedTest.path,
-                        status: "failed",
-                        exit_code: 1,
-                        failure_category: "assertion_failure",
-                        execution_context: executionContext,
-                        stdout: execution.stdout,
-                        stderr: execution.stderr,
-                        error: `Linked test assertion(s) failed: ${assertionFailures.join("; ")}`,
-                    });
-                    continue;
-                }
-                results.push({
-                    command: linkedTest.command,
-                    path: linkedTest.path,
-                    status: "passed",
-                    exit_code: 0,
-                    execution_context: executionContext,
-                    stdout: execution.stdout,
-                    stderr: execution.stderr,
-                });
+            const preflightResult = resolveLinkedTestPreflightResult({
+                linkedTest,
+                executionContext: commandContext.executionContext,
+                runLevelPmContextMode,
+                linkedOverridePmContextMode: commandContext.linkedOverridePmContextMode,
+                options,
+            });
+            if (preflightResult) {
+                results.push(preflightResult);
                 continue;
             }
-            const failureCategory = classifyLinkedTestFailure(execution);
-            results.push({
-                command: linkedTest.command,
-                path: linkedTest.path,
-                status: "failed",
-                exit_code: resolveLinkedTestFailureExitCode(execution),
-                failure_category: failureCategory,
-                execution_context: executionContext,
-                stdout: execution.stdout,
-                stderr: execution.stderr,
-                error: formatLinkedTestExecutionError(execution, timeoutMs),
-            });
+            results.push(await runSingleLinkedTest({
+                linkedTest,
+                index,
+                total: tests.length,
+                defaultTimeoutSeconds,
+                runtimeDirectives,
+                progressMode,
+                executionContext: commandContext.executionContext,
+                options,
+            }));
         }
     }
     finally {
-        await rm(sandboxRoot, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+        await rm(layout.root, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
     }
     return results;
 }
-/**
- * Implements run test for the public runtime surface of this module.
- */
-export async function runTest(id, options, global) {
-    const stdinResolver = createStdinTokenResolver();
-    const pmRoot = resolvePmRoot(process.cwd(), global.path);
-    if (!(await pathExists(getSettingsPath(pmRoot)))) {
-        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
-    }
-    const settings = await readSettings(pmRoot);
-    const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
-    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 = [...parseAddEntries(resolvedAdds), ...parseAddJsonEntries(resolvedAddJsons)];
-    const removes = parseRemoveEntries(resolvedRemoves);
-    const shouldMutate = adds.length > 0 || removes.length > 0;
-    let tests = [];
-    let itemId;
-    let changed = false;
-    if (shouldMutate) {
-        const author = resolveAuthor(options.author, settings.author_default);
-        const result = await mutateItem({
-            pmRoot,
-            settings,
-            id,
-            op: "tests_add",
-            author,
-            message: options.message,
-            force: options.force,
-            skipNoop: true,
-            mutate(document) {
-                const previous = document.metadata.tests ?? [];
-                const next = [...(document.metadata.tests ?? [])];
-                for (const add of adds) {
-                    const exists = next.some((entry) => entry.command === add.command &&
-                        entry.path === add.path &&
-                        entry.scope === add.scope &&
-                        entry.pm_context_mode === add.pm_context_mode);
-                    if (!exists) {
-                        next.push(add);
-                    }
-                }
-                if (removes.length > 0) {
-                    for (let i = next.length - 1; i >= 0; i -= 1) {
-                        const entry = next[i];
-                        if (removes.includes(entry.path ?? "") || removes.includes(entry.command ?? "")) {
-                            next.splice(i, 1);
-                        }
-                    }
-                }
-                document.metadata.tests = next;
-                return { changedFields: stableValueEquals(previous, next) ? [] : ["tests"] };
-            },
-        });
-        tests = result.item.tests ?? [];
-        itemId = result.item.id;
-        changed = result.changedFields.length > 0;
-    }
-    else {
-        const located = await locateItem(pmRoot, id, settings.id_prefix, settings.item_format, typeRegistry.type_to_folder);
-        if (!located) {
-            throw new PmCliError(`Item ${id} not found`, EXIT_CODE.NOT_FOUND);
-        }
-        itemId = located.id;
-        const loaded = await readLocatedItem(located, { schema: settings.schema });
-        tests = loaded.document.metadata.tests ?? [];
-    }
-    let defaultTimeoutSeconds;
-    if (options.timeout !== undefined) {
-        defaultTimeoutSeconds = parseOptionalNumber(options.timeout, "timeout");
-    }
-    const pmContextMode = parsePmContextMode(options.pmContext);
-    const hasRuntimeDirectiveFlags = (options.envSet?.length ?? 0) > 0 ||
+function hasTestRuntimeDirectiveFlags(options) {
+    return ((options.envSet?.length ?? 0) > 0 ||
         (options.envClear?.length ?? 0) > 0 ||
         options.sharedHostSafe === true ||
         options.pmContext !== undefined ||
@@ -1526,43 +1492,105 @@ export async function runTest(id, options, global) {
         options.failOnEmptyTestRun === true ||
         options.requireAssertionsForPm === true ||
         options.checkContext === true ||
-        options.autoPmContext === true;
-    if (hasRuntimeDirectiveFlags && options.run !== true) {
+        options.autoPmContext === true);
+}
+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);
     }
     const hasSelectorFlags = options.match !== undefined || options.onlyIndex !== undefined || options.onlyLast === true;
     if (hasSelectorFlags && options.run !== true) {
         throw new PmCliError("--match, --only-index, and --only-last require --run", EXIT_CODE.USAGE);
     }
+}
+async function resolveLinkedTestItem(params) {
+    const { id, options, pmRoot, settings, typeToFolder, adds, removes } = params;
+    if (adds.length === 0 && removes.length === 0) {
+        const located = await locateItem(pmRoot, id, settings.id_prefix, settings.item_format, typeToFolder);
+        if (!located) {
+            throw new PmCliError(`Item ${id} not found`, EXIT_CODE.NOT_FOUND);
+        }
+        const loaded = await readLocatedItem(located, { schema: settings.schema });
+        return { itemId: located.id, tests: loaded.document.metadata.tests ?? [], changed: false };
+    }
+    const result = await mutateItem({
+        pmRoot,
+        settings,
+        id,
+        op: "tests_add",
+        author: resolveAuthor(options.author, settings.author_default),
+        message: options.message,
+        force: options.force,
+        skipNoop: true,
+        mutate(document) {
+            const previous = document.metadata.tests ?? [];
+            const next = [...previous];
+            for (const add of adds) {
+                const exists = next.some((entry) => entry.command === add.command &&
+                    entry.path === add.path &&
+                    entry.scope === add.scope &&
+                    entry.pm_context_mode === add.pm_context_mode);
+                if (!exists) {
+                    next.push(add);
+                }
+            }
+            if (removes.length > 0) {
+                for (let i = next.length - 1; i >= 0; i -= 1) {
+                    const entry = next[i];
+                    if (removes.includes(entry.path ?? "") || removes.includes(entry.command ?? "")) {
+                        next.splice(i, 1);
+                    }
+                }
+            }
+            document.metadata.tests = next;
+            return { changedFields: stableValueEquals(previous, next) ? [] : ["tests"] };
+        },
+    });
+    return {
+        itemId: result.item.id,
+        tests: result.item.tests ?? [],
+        changed: result.changedFields.length > 0,
+    };
+}
+function resolveTestRunOptions(options, tests) {
+    assertTestRunFlagUsage(options);
     const selectorInput = {
         match: options.match,
         onlyIndex: options.onlyIndex === undefined ? undefined : parseOnlyIndexValue(options.onlyIndex),
         onlyLast: options.onlyLast,
     };
     const runSelection = options.run === true ? resolveLinkedTestRunSelection(tests, selectorInput) : undefined;
-    const testsToRun = runSelection?.selected ?? tests;
-    const runStartedAt = options.run === true ? nowIso() : undefined;
-    const runResults = options.run === true
-        ? await runLinkedTests(testsToRun, defaultTimeoutSeconds, {
-            progress: options.progress,
-            envSet: options.envSet,
-            envClear: options.envClear,
-            sharedHostSafe: options.sharedHostSafe,
-            pmContext: pmContextMode,
-            overrideLinkedPmContext: options.overrideLinkedPmContext,
-            failOnContextMismatch: options.failOnContextMismatch,
-            failOnEmptyTestRun: options.failOnEmptyTestRun,
-            requireAssertionsForPm: options.requireAssertionsForPm,
-            checkContext: options.checkContext,
-            autoPmContext: options.autoPmContext,
-            sourceRoots: {
-                projectPmRoot: pmRoot,
-                globalPmRoot: resolveGlobalPmRoot(process.cwd()),
-            },
-        })
-        : [];
-    const failureCategories = countFailureCategories(runResults);
-    const failOnSkippedTriggered = options.run === true && options.failOnSkipped === true && runResults.some((entry) => entry.status === "skipped");
+    return {
+        defaultTimeoutSeconds: options.timeout === undefined ? undefined : parseOptionalNumber(options.timeout, "timeout"),
+        pmContextMode: parsePmContextMode(options.pmContext),
+        runSelection,
+        testsToRun: runSelection?.selected ?? tests,
+    };
+}
+async function executeSelectedLinkedTests(params) {
+    const { options, runOptions, pmRoot } = params;
+    if (options.run !== true) {
+        return [];
+    }
+    return await runLinkedTests(runOptions.testsToRun, runOptions.defaultTimeoutSeconds, {
+        progress: options.progress,
+        envSet: options.envSet,
+        envClear: options.envClear,
+        sharedHostSafe: options.sharedHostSafe,
+        pmContext: runOptions.pmContextMode,
+        overrideLinkedPmContext: options.overrideLinkedPmContext,
+        failOnContextMismatch: options.failOnContextMismatch,
+        failOnEmptyTestRun: options.failOnEmptyTestRun,
+        requireAssertionsForPm: options.requireAssertionsForPm,
+        checkContext: options.checkContext,
+        autoPmContext: options.autoPmContext,
+        sourceRoots: {
+            projectPmRoot: pmRoot,
+            globalPmRoot: resolveGlobalPmRoot(process.cwd()),
+        },
+    });
+}
+function buildTestWarnings(options, runSelection, runResults) {
     const warnings = [];
     if (runSelection && runSelection.selector !== null) {
         warnings.push(`linked_test_selection:${runSelection.selector}=${runSelection.requested};selected=${runSelection.selected_count};skipped=${runSelection.skipped_count};indexes=${runSelection.selected_indexes.join(",")}`);
@@ -1574,58 +1602,96 @@ export async function runTest(id, options, global) {
             `mismatches=${preflight.mismatches};` +
             `auto_remediated=${preflight.auto_remediated}`);
     }
-    if (options.run === true && runStartedAt && settings.testing.record_results_to_items === true) {
-        const summary = summarizeRunResultStatuses(runResults);
-        const trackedRunId = resolveTrackedRunId("test");
-        const attemptRaw = process.env.PM_BACKGROUND_TEST_RUN_ATTEMPT?.trim();
-        const parsedAttempt = attemptRaw ? Number.parseInt(attemptRaw, 10) : Number.NaN;
-        const resumedFrom = process.env.PM_BACKGROUND_TEST_RUN_RESUMED_FROM?.trim();
-        try {
-            await appendTrackedTestRunSummary({
-                pmRoot,
-                settings,
-                itemId,
-                author: resolveAuthor(options.author, settings.author_default),
-                message: `Track test run summary (${trackedRunId})`,
-                entry: {
-                    run_id: trackedRunId,
-                    kind: "test",
-                    status: summary.failed > 0 || failOnSkippedTriggered === true ? "failed" : "passed",
-                    started_at: runStartedAt,
-                    finished_at: nowIso(),
-                    recorded_at: nowIso(),
-                    attempt: Number.isFinite(parsedAttempt) && parsedAttempt >= 1 ? parsedAttempt : undefined,
-                    resumed_from: resumedFrom && resumedFrom.length > 0 ? resumedFrom : undefined,
-                    passed: summary.passed,
-                    failed: summary.failed,
-                    skipped: summary.skipped,
-                    fail_on_skipped_triggered: failOnSkippedTriggered ? true : undefined,
-                },
-            });
-        }
-        catch (error) {
-            warnings.push(`test_result_tracking_failed:${itemId}:${error instanceof Error ? error.message : String(error)}`);
-        }
+    return warnings;
+}
+async function recordTestRunSummary(params) {
+    const { options, pmRoot, settings, itemId, runStartedAt, runResults, failOnSkippedTriggered, warnings } = params;
+    if (options.run !== true || !runStartedAt || settings.testing.record_results_to_items !== true) {
+        return;
+    }
+    const summary = summarizeRunResultStatuses(runResults);
+    const trackedRunId = resolveTrackedRunId("test");
+    const attemptRaw = process.env.PM_BACKGROUND_TEST_RUN_ATTEMPT?.trim();
+    const parsedAttempt = attemptRaw ? Number.parseInt(attemptRaw, 10) : Number.NaN;
+    const resumedFrom = process.env.PM_BACKGROUND_TEST_RUN_RESUMED_FROM?.trim();
+    try {
+        await appendTrackedTestRunSummary({
+            pmRoot,
+            settings,
+            itemId,
+            author: resolveAuthor(options.author, settings.author_default),
+            message: `Track test run summary (${trackedRunId})`,
+            entry: {
+                run_id: trackedRunId,
+                kind: "test",
+                status: summary.failed > 0 || failOnSkippedTriggered === true ? "failed" : "passed",
+                started_at: runStartedAt,
+                finished_at: nowIso(),
+                recorded_at: nowIso(),
+                attempt: Number.isFinite(parsedAttempt) && parsedAttempt >= 1 ? parsedAttempt : undefined,
+                resumed_from: resumedFrom && resumedFrom.length > 0 ? resumedFrom : undefined,
+                passed: summary.passed,
+                failed: summary.failed,
+                skipped: summary.skipped,
+                fail_on_skipped_triggered: failOnSkippedTriggered ? true : undefined,
+            },
+        });
     }
+    catch (error) {
+        warnings.push(`test_result_tracking_failed:${itemId}:${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Implements run test for the public runtime surface of this module.
+ */
+export async function runTest(id, options, global) {
+    const stdinResolver = createStdinTokenResolver();
+    const pmRoot = resolvePmRoot(process.cwd(), global.path);
+    if (!(await pathExists(getSettingsPath(pmRoot)))) {
+        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
+    }
+    const settings = await readSettings(pmRoot);
+    const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
+    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 = [...parseAddEntries(resolvedAdds), ...parseAddJsonEntries(resolvedAddJsons)];
+    const removes = parseRemoveEntries(resolvedRemoves);
+    const item = await resolveLinkedTestItem({
+        id,
+        options,
+        pmRoot,
+        settings,
+        typeToFolder: typeRegistry.type_to_folder,
+        adds,
+        removes,
+    });
+    const runOptions = resolveTestRunOptions(options, item.tests);
+    const runStartedAt = options.run === true ? nowIso() : undefined;
+    const runResults = await executeSelectedLinkedTests({ options, runOptions, pmRoot });
+    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);
+    await recordTestRunSummary({ options, pmRoot, settings, itemId: item.itemId, runStartedAt, runResults, failOnSkippedTriggered, warnings });
     return {
         ok: runResults.every((entry) => entry.status !== "failed") && failOnSkippedTriggered !== true,
-        id: itemId,
-        tests,
+        id: item.itemId,
+        tests: item.tests,
         run_results: runResults,
         failure_categories: failureCategories,
-        selection: runSelection
+        selection: runOptions.runSelection
             ? {
-                selector: runSelection.selector,
-                requested: runSelection.requested,
-                selected_indexes: runSelection.selected_indexes,
-                selected_count: runSelection.selected_count,
-                skipped_count: runSelection.skipped_count,
+                selector: runOptions.runSelection.selector,
+                requested: runOptions.runSelection.requested,
+                selected_indexes: runOptions.runSelection.selected_indexes,
+                selected_count: runOptions.runSelection.selected_count,
+                skipped_count: runOptions.runSelection.skipped_count,
             }
             : undefined,
         fail_on_skipped_triggered: failOnSkippedTriggered ? true : undefined,
         warnings: warnings.length > 0 ? warnings : undefined,
-        changed,
-        count: tests.length,
+        changed: item.changed,
+        count: item.tests.length,
     };
 }
 /* c8 ignore stop */
@@ -1656,4 +1722,4 @@ export const _testOnlyTestCommand = {
     summarizeRunResultStatuses,
 };
 //# sourceMappingURL=test.js.map
-//# debugId=588f0e3a-3f1c-56d9-8908-c8003ae549cd
+//# debugId=caa941ed-c848-506c-9a3c-3d4959be0246