@dailephd/my-dev-kit-lab 0.7.1 → 0.7.2

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to my-dev-kit-lab are documented here.
 
 ## [Unreleased]
 
+## [0.7.2] - 2026-10-03
+
+### Local-repository experiments
+
+- Added explicitly selected local Git repositories as `context-window-scaling` subjects: `experiment run --experiment context-window-scaling --target <repository> --local-subject-config <path>`, with a strict `LocalRepositorySubjectConfigV1`. The experiment, its treatments, budgets, token estimator, correctness, success, plots, and report schemas are unchanged, and bundled and synthetic modes behave as before.
+- Contexts for both treatments are built only from regular files inside the declared source roots that Git does not ignore and that are at most 1 MiB; ignored, oversized, symbolic-link, and other unsafe entries are excluded, and the guided treatment fails if retrieval returns an excluded file.
+- The repository is treated as read-only: private scratch state is created outside it and removed, repository state is compared before and after the run, and an output directory equal to or inside the repository is rejected. A detected change fails the run and is not reverted.
+- Durable external-local output omits the repository path, source text, and file names: exact file identities appear as numbered `<redacted file N>` placeholders marked by `fileIdentityRedaction: "redacted"`, and the report target carries `privacyProjection: "external-local-redacted"`. A new `local-repository-subject-manifest.json` records the logical subject ID, full Git commit, branch, dirty state, safety policy, source roots, case IDs, and aggregate size counts.
+- A failed external-local run exits nonzero with a bounded error and writes no report, execution artifact, or manifest.
+- Fixed a crash in which a local-repository run pointed at a directory past the Windows path-length limit ended with an unhandled stream error instead of a classified error, and made known-file redaction in error text cover backslash-separated paths.
+- Extended help, `experiment describe` text, and the packed-package acceptance gate (`npm run verify:packed-package`) to cover the installed external-local run with the real published my-dev-kit, rejection cases, privacy scanning that includes JSON-escaped Windows paths, and target immutability.
+- Replaced a trailing-slash regular expression in glob base normalization with a linear scan after a CodeQL polynomial-regular-expression finding; glob selection behavior is unchanged.
+- No retrieval precision, recall, ranking, or winner metric was added; those remain planned for v0.8.0.
+
 ## [0.7.1] - 2026-10-02
 
 ### Synthetic large-repository generator

package/README.md

@@ -6,7 +6,7 @@ my-dev-kit provides local repository indexing and graph-guided retrieval. my-dev
 
 Whole-ecosystem workflows are centralized in [my-dev-kit/docs/ECOSYSTEM_DEVELOPMENT_WORKFLOWS.md](https://github.com/dailephd/my-dev-kit/blob/main/docs/ECOSYSTEM_DEVELOPMENT_WORKFLOWS.md). Its [command-surface compatibility map](https://github.com/dailephd/my-dev-kit/blob/main/docs/ECOSYSTEM_DEVELOPMENT_WORKFLOWS.md#915-command-surface-compatibility-map) documents which Lab outputs can safely seed my-dev-kit investigation, Observer reference work, or Orchestrator evidence, and which look-alike artifacts are not direct inputs.
 
-The latest release is v0.7.1 (synthetic large-repository generator), and the published package and installed CLI are version 0.7.1. The previous release is v0.7.0 (context-window scaling), and v0.7.2 (real/local external repository experiments) is planned after the current release. The v0.4.5 context-integrity evaluation remains intentionally frozen against the published `@dailephd/my-dev-kit@1.10.4` and `@dailephd/my-dev-kit-orchestrator@1.2.3` contracts; those versions are historical validation baselines, not a statement that they are the ecosystem's current releases. See [docs/CURRENT_STATE.md](docs/CURRENT_STATE.md) for current state.
+The latest release is v0.7.2 (local-repository experiments), and the published package and installed CLI are version 0.7.2. The previous release is v0.7.1 (synthetic large-repository generator). The v0.4.5 context-integrity evaluation remains intentionally frozen against the published `@dailephd/my-dev-kit@1.10.4` and `@dailephd/my-dev-kit-orchestrator@1.2.3` contracts; those versions are historical validation baselines, not a statement that they are the ecosystem's current releases. See [docs/CURRENT_STATE.md](docs/CURRENT_STATE.md) for current state.
 
 v0.4.6 adds a supported `my-dev-kit-lab` installed CLI router (`--help`, `--version`, `security validate`, `audit`, the `experiment` family, `report render`, `plots generate`, `gallery build`, `demo final`, and the historical direct final-demo invocation form), a writable lab workspace model kept separate from the installed package and the inspected target, and a permanent packed-tarball installation/execution acceptance gate (`npm run verify:packed-package`). See [docs/ROADMAP.md](docs/ROADMAP.md) and [docs/CURRENT_STATE.md](docs/CURRENT_STATE.md) for status detail and [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the runtime path model. The "Installed CLI" section below documents the shipped command surface; the source-checkout `npm run` workflow in Quickstart remains available for contributors.
 
@@ -16,9 +16,10 @@ v0.4.6 adds a supported `my-dev-kit-lab` installed CLI router (`--help`, `--vers
 - **Measure warm-index reuse (v0.5.0–v0.5.1, released):** the `warm-index-reuse` experiment plugin builds one my-dev-kit index per benchmark project, reuses it across that project's tasks, and compares every task with a matched `raw-full-file` baseline. Reports separate one-time index-build cost from per-task retrieval cost, show amortized index cost and cumulative measurements, and include deterministic fake-agent correctness and token evidence; `plots generate` renders four warm-index SVG charts. The v0.5.1 release adds a dedicated 12-task benchmark corpus (`benchmarks/contracts/warm-index-benchmark-cases.json`: six medium and six large/mixed tasks tagged `localized`, `cross-module`, or `broad-change`) for comparing warm-index behavior as task count grows. Estimated context tokens (a character-based context-size estimate) and fake-agent total tokens (simulated harness telemetry) are reported separately, and neither is provider billing telemetry.
 - **Run selectable real-agent warm-index campaigns (v0.5.2, released):** `--campaign codex-full`, `claude-full`, or `codex-timeout-isolation` (with `--include-real-agents`) runs exactly one provider — Codex or Claude — against the exact raw and warm contexts the experiment already measured, over the frozen production corpus each preset owns. Provider outcomes (`completed`, `failed`, `timeout`, `invalid-output`, `agent-unavailable`, `agent-limit-reached`, `skipped`) are classified and reported separately from warm-index infrastructure status, so a campaign can complete its indexing/retrieval work even when provider evidence is partial or unavailable. A campaign run automatically produces the report, the same four warm-index SVG charts, and a three-item gallery (report, plots, bounded execution evidence). Its report screenshot is best-effort presentation evidence: unavailable browser runtime or failed capture is reported explicitly, no PNG is fabricated, and neither outcome fails an otherwise successful campaign. Legacy runs without `--campaign` keep the existing deterministic fake-agent, report-only behavior unchanged. See [docs/WORKFLOWS.md](docs/WORKFLOWS.md#warm-index-reuse-experiment) and [docs/METRICS.md](docs/METRICS.md#warm-index-reuse-metrics).
 - **Record index freshness evidence (v0.6.0):** a warm-index run captures an index snapshot after its one index build — the exact indexed file set from the my-dev-kit index contract, each with SHA-256 content identity, size, and modified-time metadata, plus the my-dev-kit version and index-command evidence — and assesses freshness immediately before each task's warm retrieval as `fresh`, `stale`, `partially-stale`, or `unknown`. The evidence appears in `warm-index-execution.json` and in the existing `report.json`/`report.txt`/`report.html` warm-index reports. It is observational only: it covers only files the snapshot lists (not the whole repository), never changes retrieval, execution or provider status, and adds no CLI flag, metric, plot, gallery item, or reindex recommendation in v0.6.0. See [docs/METRICS.md](docs/METRICS.md#index-freshness-evidence-v060) and [docs/WORKFLOWS.md](docs/WORKFLOWS.md#warm-index-reuse-experiment).
-- **Compare no-refresh, partial-refresh, and full-refresh retrieval after a controlled change (v0.6.3, previous release):** the `incremental-change-staleness` experiment plugin runs six frozen controlled-change scenario families (unrelated-file, local-implementation, exported-symbol, public-API, import-graph, and test-only changes) against four disposable target copies — `stale-index` (no refresh), `changed-files-refresh` and `affected-neighborhood-refresh` (real partial refreshes performed by my-dev-kit 1.12.5 through `index --incremental --refresh-scope`, selected internally with no Lab-level flag), and `full-refresh` (a complete new post-change index, used as a comparison reference rather than a preferred treatment). Each partial treatment truthfully records whether upstream applied the requested partial scope or fell back to a full rebuild (`APPLIED_PARTIAL` or `FALLBACK_FULL`); a fallback is not counted as partial-refresh evidence. Three comparisons against `full-refresh` are persisted with retrieval, deterministic fake-agent correctness, and required-file evidence in `incremental-change-staleness-execution.json` (schema `my-dev-kit-lab-incremental-change-staleness-execution-v2`) and the existing `report.json`/`report.txt`/`report.html`; historical v0.6.2 (V1) artifacts stay readable. There is no winner, ranking, or safety claim, and the plugin is self-only (`--target` is not accepted). `--kit-command` also accepts `incremental-change-staleness` and now defaults to my-dev-kit 1.12.5. See [docs/WORKFLOWS.md](docs/WORKFLOWS.md) and [docs/METRICS.md](docs/METRICS.md).
+- **Compare no-refresh, partial-refresh, and full-refresh retrieval after a controlled change (v0.6.3, released; retained in the current package):** the `incremental-change-staleness` experiment plugin runs six frozen controlled-change scenario families (unrelated-file, local-implementation, exported-symbol, public-API, import-graph, and test-only changes) against four disposable target copies — `stale-index` (no refresh), `changed-files-refresh` and `affected-neighborhood-refresh` (real partial refreshes performed by my-dev-kit 1.12.5 through `index --incremental --refresh-scope`, selected internally with no Lab-level flag), and `full-refresh` (a complete new post-change index, used as a comparison reference rather than a preferred treatment). Each partial treatment truthfully records whether upstream applied the requested partial scope or fell back to a full rebuild (`APPLIED_PARTIAL` or `FALLBACK_FULL`); a fallback is not counted as partial-refresh evidence. Three comparisons against `full-refresh` are persisted with retrieval, deterministic fake-agent correctness, and required-file evidence in `incremental-change-staleness-execution.json` (schema `my-dev-kit-lab-incremental-change-staleness-execution-v2`) and the existing `report.json`/`report.txt`/`report.html`; historical v0.6.2 (V1) artifacts stay readable. There is no winner, ranking, or safety claim, and the plugin is self-only (`--target` is not accepted). `--kit-command` also accepts `incremental-change-staleness` and now defaults to my-dev-kit 1.12.5. See [docs/WORKFLOWS.md](docs/WORKFLOWS.md) and [docs/METRICS.md](docs/METRICS.md).
 - **Measure context-window scaling (v0.7.0, released):** the self-only `context-window-scaling` plugin compares `raw-full-file` and `my-dev-kit-guided` over 8k, 16k, 32k, 64k, or custom positive-integer estimated-token budgets. It records fit, utilization, deterministic fake-agent correctness/success, and omitted expected relevant files, with JSON/text/HTML reports and three SVG plots. `plots generate` reads `context-window-scaling-execution.json`. Token counts are a character-based estimate, not provider-tokenizer or billing data; fake-agent correctness is context-independent in the current harness. See [docs/WORKFLOWS.md](docs/WORKFLOWS.md), [docs/METRICS.md](docs/METRICS.md), and [docs/COMMANDS.md](docs/COMMANDS.md).
-- **Run context-window scaling over synthetic repositories (v0.7.1, current release):** `context-window-scaling` uses the bundled fixed corpus by default, or `--synthetic-config <path>` (a `SyntheticRepositoryConfigV1` JSON file) to generate disposable deterministic TypeScript/Python repositories beneath the run output. The option is a command input selector, not plugin scientific config; it is mutually exclusive with `--case`, and the scientific semantics, execution artifact, reports, and plots are unchanged. See [docs/COMMANDS.md](docs/COMMANDS.md) and [docs/WORKFLOWS.md](docs/WORKFLOWS.md).
+- **Run context-window scaling over synthetic repositories (v0.7.1, released):** `context-window-scaling` uses the bundled fixed corpus by default, or `--synthetic-config <path>` (a `SyntheticRepositoryConfigV1` JSON file) to generate disposable deterministic TypeScript/Python repositories beneath the run output. The option is a command input selector, not plugin scientific config; it is mutually exclusive with `--case`, and the scientific semantics, execution artifact, reports, and plots are unchanged. See [docs/COMMANDS.md](docs/COMMANDS.md) and [docs/WORKFLOWS.md](docs/WORKFLOWS.md).
+- **Run context-window scaling over a local Git repository (v0.7.2, current release):** `context-window-scaling` can also run against an explicitly selected local Git repository with `--target <repository> --local-subject-config <path>` (a `LocalRepositorySubjectConfigV1` JSON file). The Lab treats the repository as read-only and compares its state before and after the run, builds contexts only from files Git does not ignore (ignored, oversized (over 1 MiB), symbolic-link, and other unsafe entries are excluded), requires the output directory to be outside the repository, and keeps the repository path, source text, and file names out of durable artifacts (file identities appear as numbered `<redacted file N>` placeholders). A `local-repository-subject-manifest.json` records the logical subject ID, the full Git commit, the branch, and aggregate size metadata. This measures operational context fit only, not retrieval precision, recall, or ranking quality. It is part of the current package. See [docs/COMMANDS.md](docs/COMMANDS.md) and [docs/WORKFLOWS.md](docs/WORKFLOWS.md).
 - **Assess affected-neighborhood evidence (v0.6.1, released; retained in the current package):** using the baseline my-dev-kit graph of the same prepared warm index (loaded once per session), each task's confirmed modified or missing indexed files, and the baseline symbols those files contain, are mapped to graph nodes. The affected neighborhood is those seed nodes plus their direct one-hop neighbors (edges of any kind, either direction). The task's `expectedFiles` and file-scoped `expectedSymbols` are mapped to graph nodes and compared with that neighborhood, which yields six numeric warm-side metrics (`changedFileCount`, `changedSymbolCount`, `affectedNodeCount`, `affectedEdgeCount`, `taskOverlapCount`, `taskOverlapPercent`) plus categorical evidence: a `related`, `unrelated`, or `unknown` relationship and a `recommended`, `not-indicated`, or `unknown` `reindexRecommendation`. Incomplete evidence is reported as `unknown`, never as unrelated. The assessment is recorded additively in `warm-index-execution.json` and shown in the existing `report.json`/`report.txt`/`report.html` warm-index reports. It is observational only: retrieval, execution status, and provider status are unchanged, nothing is reindexed automatically, and no CLI flag, experiment plugin, plot, or gallery item was added. See [docs/METRICS.md](docs/METRICS.md#affected-neighborhood-metrics-v061) and [docs/WORKFLOWS.md](docs/WORKFLOWS.md#warm-index-reuse-experiment).
 - **Audit repository health:** run conservative code-rot detectors for TypeScript/JavaScript, Python, Java, and Kotlin, or adapt security findings into the common audit report.
 - **Validate CLI/package security:** inspect dependencies, package contents, path and subprocess boundaries, malformed inputs, optional static scanners, and bounded fuzz targets.
@@ -238,12 +239,12 @@ See [docs/METRICS.md](docs/METRICS.md) for full metric definitions.
 - Claude and Codex token totals are used only when the CLI/run exposes them; missing provider token evidence stays explicitly unavailable (never zero, and never substituted with an estimated context-token count)
 - Codex and Claude campaign runs can produce timeouts, invalid-output, agent-unavailable, or agent-limit-reached outcomes; these are structured provider states, not warm-index infrastructure failures
 - Small projects may make raw-full-file cheaper than my-dev-kit-guided; larger localized tasks are where my-dev-kit is expected to become more useful
-- The generic experiment-plugin framework has four registered plugins: `context-strategy-comparison`, `warm-index-reuse`, `incremental-change-staleness`, and `context-window-scaling`. The v0.7.0 context-window-scaling plugin is released; v0.7.1 lets it also run over caller-supplied synthetic repositories; external/local repository experiments (v0.7.2), retrieval precision/recall, and agent-success plugins remain planned.
+- The generic experiment-plugin framework has four registered plugins: `context-strategy-comparison`, `warm-index-reuse`, `incremental-change-staleness`, and `context-window-scaling`. The v0.7.0 context-window-scaling plugin is released; v0.7.1 lets it also run over caller-supplied synthetic repositories; v0.7.2 lets it run over an explicitly selected local Git repository; retrieval precision/recall and agent-success plugins remain planned.
 - `warm-index-reuse` without `--campaign` still uses the deterministic fake agent only. With `--campaign`, exactly one real provider (Codex or Claude) runs per campaign preset — there is no multi-agent matrix, retry, provider switching, or scheduler. The v0.5.1 expanded corpus is deterministic fake-agent benchmark evidence when run without `--campaign`. No warm-index mode calculates a token-savings percentage, break-even task, winner, or ranking, and component-duration sums are not wall-clock latency
 - The current release does not guarantee token savings; it produces auditable evidence for specific cases, targets, agents, and strategies
 - Context-window scaling uses estimated tokens (`ceil(characters / 4)`) and experiment budgets, not actual provider tokenizer or model-window limits. Its deterministic fake-agent correctness check does not measure semantic sensitivity to the supplied context.
 - Released v0.6.1 affected-neighborhood evidence is bounded to the baseline graph of the prepared index and to the snapshot-represented files: a changed symbol means the symbol was present in a confirmed changed indexed file, not that its own text was proven to change; `not-indicated` means only that this bounded analysis found no supporting evidence for reindexing, not that skipping a reindex is safe; unresolved or ambiguous expected symbols keep a task at `unknown` rather than unrelated
-- v0.6.3 (previous release) partial-refresh evidence is scoped to the executed deterministic scenarios and the configured my-dev-kit 1.12.5-or-later tool. A partial treatment can fall back to a full rebuild and is then reported as not comparable as partial refresh, so an applied partial refresh in one run does not guarantee the next; `no-observed-regression-relative-to-full` is not a safety claim, and full refresh is a reference rather than a winner. Correctness remains deterministic fake-agent evidence, and `incremental-change-staleness` accepts no external `--target`.
+- v0.6.3 partial-refresh evidence is scoped to the executed deterministic scenarios and the configured my-dev-kit 1.12.5-or-later tool. A partial treatment can fall back to a full rebuild and is then reported as not comparable as partial refresh, so an applied partial refresh in one run does not guarantee the next; `no-observed-regression-relative-to-full` is not a safety claim, and full refresh is a reference rather than a winner. Correctness remains deterministic fake-agent evidence, and `incremental-change-staleness` accepts no external `--target`.
 - Provider telemetry dashboards, semantic LLM judging, and cloud API billing integration are not yet implemented
 - The six new stage-context strategies have no CLI flags yet, are configured programmatically, and do not yet include plots, screenshots, or gallery integration
 - The published upstream artifacts the stage-context strategies read do not expose considered-but-unselected reads or unnecessary-read evidence; those metrics report `unavailable` rather than zero

package/dist/src/cli/help.js

@@ -166,15 +166,26 @@ export function renderExperimentRunHelp() {
         "  --context-budgets <values>                          Comma-separated estimated-context-token budgets: 8k, 16k, 32k,",
         "                                                      64k (8192/16384/32768/65536), or positive integers such as",
         "                                                      12000 (default: 8k,16k,32k,64k). Duplicates after",
-        "                                                      normalization are rejected. Only --out, --case,",
-        "                                                      --synthetic-config, --context-budgets, and --kit-command are",
-        "                                                      accepted; --case selects from the bundled four-case catalog.",
-        "                                                      Self target only.",
+        "                                                      normalization are rejected. Only --out, --target, --case,",
+        "                                                      --synthetic-config, --local-subject-config, --context-budgets,",
+        "                                                      and --kit-command are accepted; --case selects from the bundled",
+        "                                                      four-case catalog. Bundled and synthetic modes run against the",
+        "                                                      Lab itself (--target is rejected there); an external --target",
+        "                                                      requires --local-subject-config.",
         "  --synthetic-config <path>                           Path to a SyntheticRepositoryConfigV1 JSON file; relative paths",
         "                                                      resolve against the invocation directory. Generated",
         "                                                      repositories are written beneath the selected experiment",
         "                                                      output directory (synthetic-repositories/). Mutually exclusive",
         "                                                      with --case. Without it, the bundled four-case catalog is used.",
+        "  --local-subject-config <path>                       Path to a LocalRepositorySubjectConfigV1 JSON file; applies to",
+        "                                                      context-window-scaling with an explicit external --target (a",
+        "                                                      local Git worktree root). Relative paths resolve against the",
+        "                                                      invocation directory. The repository is never modified; the",
+        "                                                      output directory must be outside it. Durable output omits the",
+        "                                                      repository path, source text, and file names, and adds",
+        "                                                      local-repository-subject-manifest.json. Mutually exclusive with",
+        "                                                      --case and --synthetic-config. Measures operational context fit",
+        "                                                      only, not retrieval precision, recall, or ranking quality.",
         "                                                      Generate plots with \"plots generate --experiment <run dir>\".",
         "",
         "warm-index-reuse only:",

package/dist/src/commands/runExperimentDescribeCommand.js

@@ -130,6 +130,9 @@ function describePurpose(plugin) {
 }
 function describeTargetBehavior(plugin) {
     const supportsExternal = plugin.metadata.supportedTargets.includes("external-local");
+    if (plugin.metadata.id === "context-window-scaling") {
+        return "Three subject modes. Bundled (default): the bundled fixed scaling corpus against the Lab itself. Synthetic: caller-supplied deterministic synthetic repositories via --synthetic-config <path> (a SyntheticRepositoryConfigV1 JSON file, mutually exclusive with --case) written beneath the experiment output directory. External local repository: an explicitly selected local Git worktree via --target <path> together with --local-subject-config <path> (a LocalRepositorySubjectConfigV1 JSON file); the repository is never modified, the output directory must be outside it, and durable output omits the repository path, source text, and file names. Operational context-fit measurement only; no retrieval precision, recall, or ranking quality is measured.";
+    }
     if (supportsExternal) {
         return "Runs against the current lab repository when --target is omitted, or against an explicit local target project when --target <path> is provided. Outputs stay under lab-controlled output directories by default.";
     }
@@ -153,7 +156,7 @@ function describeExamples(plugin) {
         `my-dev-kit-lab experiment run --experiment ${plugin.metadata.id}${agentOptions}`
     ];
     // Only advertise an explicit --target example for plugins that support external targets.
-    if (plugin.metadata.supportedTargets.includes("external-local")) {
+    if (plugin.metadata.supportedTargets.includes("external-local") && plugin.metadata.id !== "context-window-scaling") {
         examples.push(`my-dev-kit-lab experiment run --experiment ${plugin.metadata.id} --target "Z:\\Users\\newuser\\Projects\\my-dev-kit-v1"${agentOptions}${screenshotOption}`);
     }
     // Only advertise campaign examples for plugins that declare the campaignPreset config field.
@@ -161,7 +164,7 @@ function describeExamples(plugin) {
         examples.push(`my-dev-kit-lab experiment run --experiment ${plugin.metadata.id} --campaign codex-full --include-real-agents --out <dir>`, `my-dev-kit-lab experiment run --experiment ${plugin.metadata.id} --campaign claude-full --include-real-agents --case warm-medium-complete-idempotent --out <dir>`);
     }
     if (plugin.metadata.id === "context-window-scaling") {
-        examples.push(`my-dev-kit-lab experiment run --experiment ${plugin.metadata.id} --synthetic-config <path-to-config.json> --out <run-dir>`);
+        examples.push(`my-dev-kit-lab experiment run --experiment ${plugin.metadata.id} --synthetic-config <path-to-config.json> --out <run-dir>`, `my-dev-kit-lab experiment run --experiment ${plugin.metadata.id} --target <local-git-repository> --local-subject-config <path-to-local-subject-config.json> --out <run-dir-outside-the-repository>`);
     }
     return examples;
 }

package/dist/src/commands/runExperimentRunCommand.js

@@ -3,8 +3,11 @@ import path from "node:path";
 import { parseAgentCommandTemplate } from "../agents/index.js";
 import { parseAgentId } from "../agents/agentRegistry.js";
 import { readBenchmarkProjectProfiles, readEvaluationCases } from "../evaluation/index.js";
+import { loadLocalRepositorySubject } from "../evaluation/localRepositorySubject/index.js";
 import { contextStrategyComparisonPlugin, contextWindowScalingPlugin, createDefaultExperimentPluginRegistry, getWarmIndexCampaignPreset, incrementalChangeStalenessPlugin, parseContextBudgetsCliValue, parseWarmIndexCampaignPresetId, resolveExperimentTarget, runExperiment, warmIndexReusePlugin } from "../experiments/index.js";
 import { prepareSyntheticContextWindowScalingInputs } from "../experiments/plugins/contextWindowScaling/index.js";
+import { projectExternalLocalTarget, projectRunForExternalLocalPersistence, } from "../experiments/plugins/contextWindowScaling/localSubjectPrivacy.js";
+import { assertWorkRootOutsideTarget } from "../experiments/plugins/contextWindowScaling/localSubjectScratch.js";
 import { buildDefaultExperimentOutputRoot } from "../experiments/outputPaths.js";
 import { parsePromptComplexityLevel, parsePromptStrategy } from "../prompts/index.js";
 import { writePluginExperimentReports } from "../report/index.js";
@@ -38,7 +41,16 @@ const DEFAULT_PROJECT_PROFILES_RESOURCE = "benchmarks/contracts/benchmark-projec
 // catalog's package-relative targetRoot, so both resolve from the package root, never the cwd.
 const CONTEXT_WINDOW_SCALING_CASES_RESOURCE = "benchmarks/contracts/context-window-scaling-cases.json";
 // Options the context-window-scaling plugin accepts; every other flag is rejected, not ignored.
-const CONTEXT_WINDOW_SCALING_ALLOWED_FLAGS = ["--experiment", "--out", "--case", "--synthetic-config", "--context-budgets", "--kit-command"];
+const CONTEXT_WINDOW_SCALING_ALLOWED_FLAGS = [
+    "--experiment",
+    "--out",
+    "--target",
+    "--case",
+    "--synthetic-config",
+    "--local-subject-config",
+    "--context-budgets",
+    "--kit-command"
+];
 export async function runExperimentRunCommandFromArgs(argv, options = {}) {
     try {
         const args = parseRunExperimentArgs(argv);
@@ -53,8 +65,8 @@ export async function runExperimentRunCommandFromArgs(argv, options = {}) {
             experimentId: args.experimentId,
             runId
         });
-        if (args.syntheticConfigPath !== undefined && outputRoot === undefined) {
-            // Synthetic generation needs the concrete root before the runner runs; use the exact default the
+        if ((args.syntheticConfigPath !== undefined || args.localSubjectConfigPath !== undefined) && outputRoot === undefined) {
+            // Synthetic generation and external-local runs need the concrete root before the runner runs; use the exact default the
             // runner itself would compute for this self-targeted invocation.
             outputRoot = buildDefaultExperimentOutputRoot({
                 toolRoot,
@@ -74,22 +86,53 @@ export async function runExperimentRunCommandFromArgs(argv, options = {}) {
             toolRoot,
             runId
         });
+        const localSubject = readLoadedLocalSubject(inputs);
+        // External-local runs persist only a projected run: no target, tool, or output machine-local paths.
+        const persistedRun = localSubject
+            ? projectRunForExternalLocalPersistence(result, projectExternalLocalTarget(localSubject.manifest))
+            : result;
+        if (localSubject && result.status === "failed") {
+            // A failed local run has no execution evidence, so no report is produced and none could be mistaken for a
+            // completed experiment. The safe failure description (codes and kinds only) is the whole outcome.
+            console.log([
+                `Experiment: ${result.pluginId}`,
+                `Run ID: ${result.runId}`,
+                "Status: failed",
+                "Mode: external-local repository subject",
+                `Subject: ${localSubject.subjectId}`,
+                ...result.failures.map((failure) => `Failure: ${failure.message}`)
+            ].join("\n"));
+            return 1;
+        }
         const reports = await writePluginExperimentReports({
-            run: result,
+            run: persistedRun,
             plugin: registry.describe(result.pluginId),
-            outputRoot: String(result.metadata?.outputRoot ?? "")
+            outputRoot: String(result.metadata?.outputRoot ?? ""),
+            redactOutputRoot: localSubject !== undefined
         });
-        const outputLines = [
-            `Experiment: ${result.pluginId}`,
-            `Run ID: ${result.runId}`,
-            `Status: ${result.status}`,
-            `Mode: ${result.target.isSelf ? "self" : "external target"}`,
-            `Tool root: ${result.target.toolRoot}`,
-            `Target root: ${result.target.targetRoot}`,
-            `Output: ${String(result.metadata?.outputRoot ?? "")}`,
-            `Report JSON: ${reports.outputPaths.jsonPath}`,
-            `Report HTML: ${reports.outputPaths.htmlPath}`
-        ];
+        const outputLines = localSubject
+            ? [
+                `Experiment: ${result.pluginId}`,
+                `Run ID: ${result.runId}`,
+                `Status: ${result.status}`,
+                "Mode: external-local repository subject",
+                `Subject: ${localSubject.subjectId}`,
+                `Output: ${String(result.metadata?.outputRoot ?? "")}`,
+                `Report JSON: ${reports.outputPaths.jsonPath}`,
+                `Report HTML: ${reports.outputPaths.htmlPath}`,
+                ...result.failures.map((failure) => `Failure: ${failure.message}`)
+            ]
+            : [
+                `Experiment: ${result.pluginId}`,
+                `Run ID: ${result.runId}`,
+                `Status: ${result.status}`,
+                `Mode: ${result.target.isSelf ? "self" : "external target"}`,
+                `Tool root: ${result.target.toolRoot}`,
+                `Target root: ${result.target.targetRoot}`,
+                `Output: ${String(result.metadata?.outputRoot ?? "")}`,
+                `Report JSON: ${reports.outputPaths.jsonPath}`,
+                `Report HTML: ${reports.outputPaths.htmlPath}`
+            ];
         // Automatic presentation (report already produced above) applies only to warm-index-reuse
         // campaign runs; legacy fake-agent warm-index runs and context-strategy-comparison stay
         // report-only, unchanged.
@@ -161,6 +204,7 @@ export function parseRunExperimentArgs(argv) {
     let campaignPreset;
     let contextBudgets;
     let syntheticConfigPath;
+    let localSubjectConfigPath;
     const seenFlags = [];
     const commandTemplates = {};
     for (let index = 0; index < argv.length; index += 1) {
@@ -188,6 +232,12 @@ export function parseRunExperimentArgs(argv) {
             }
             syntheticConfigPath = readRequiredValue(argv, ++index, "--synthetic-config");
         }
+        else if (arg === "--local-subject-config") {
+            if (localSubjectConfigPath !== undefined) {
+                throw new Error("--local-subject-config may be supplied only once.");
+            }
+            localSubjectConfigPath = readRequiredValue(argv, ++index, "--local-subject-config");
+        }
         else if (arg === "--case") {
             caseIds.push(...splitList(readRequiredValue(argv, ++index, "--case")));
         }
@@ -258,6 +308,9 @@ export function parseRunExperimentArgs(argv) {
     if (syntheticConfigPath !== undefined && experimentId !== contextWindowScalingPlugin.metadata.id) {
         throw new Error(`--synthetic-config is only supported for --experiment ${contextWindowScalingPlugin.metadata.id}.`);
     }
+    if (localSubjectConfigPath !== undefined && experimentId !== contextWindowScalingPlugin.metadata.id) {
+        throw new Error(`--local-subject-config is only supported for --experiment ${contextWindowScalingPlugin.metadata.id}.`);
+    }
     if (experimentId === contextWindowScalingPlugin.metadata.id) {
         const unsupported = [...new Set(seenFlags.filter((flag) => !CONTEXT_WINDOW_SCALING_ALLOWED_FLAGS.includes(flag)))];
         if (unsupported.length > 0) {
@@ -269,6 +322,23 @@ export function parseRunExperimentArgs(argv) {
         if (syntheticConfigPath !== undefined && seenFlags.includes("--case")) {
             throw new Error("--case and --synthetic-config are mutually exclusive; the synthetic config owns the generated case set.");
         }
+        // Subject-mode matrix: bundled (no source flags), synthetic (--synthetic-config), external-local
+        // (--target with --local-subject-config). Every other combination is rejected, never given a precedence.
+        if (localSubjectConfigPath !== undefined && syntheticConfigPath !== undefined) {
+            throw new Error("--synthetic-config and --local-subject-config are mutually exclusive; choose one subject source.");
+        }
+        if (localSubjectConfigPath !== undefined && seenFlags.includes("--case")) {
+            throw new Error("--case cannot be combined with --local-subject-config; the local subject config owns the case set.");
+        }
+        if (localSubjectConfigPath !== undefined && targetPath === undefined) {
+            throw new Error(`--local-subject-config requires an external --target for ${experimentId}.`);
+        }
+        if (syntheticConfigPath !== undefined && targetPath !== undefined) {
+            throw new Error("--synthetic-config cannot be combined with --target; synthetic subjects are generated beneath the experiment output directory.");
+        }
+        if (targetPath !== undefined && localSubjectConfigPath === undefined) {
+            throw new Error(`External ${experimentId} targets require --local-subject-config.`);
+        }
     }
     if (kitCommand !== undefined && !KIT_COMMAND_PLUGIN_IDS.includes(experimentId)) {
         throw new Error(`--kit-command is only supported for --experiment ${KIT_COMMAND_PLUGIN_IDS.join(" or ")}.`);
@@ -292,6 +362,7 @@ export function parseRunExperimentArgs(argv) {
         targetPath,
         outDir,
         syntheticConfigPath,
+        localSubjectConfigPath,
         config: withoutUndefined({
             casesPath,
             projectProfilesPath,
@@ -370,6 +441,27 @@ async function loadContextWindowScalingInputs(args, toolRoot, context, outputRoo
     if (!validation.valid || !validation.config) {
         throw new Error(`Invalid context window scaling config: ${validation.errors.join("; ")}`);
     }
+    if (args.localSubjectConfigPath !== undefined) {
+        if (outputRoot === undefined) {
+            throw new Error("Internal error: external-local runs require a resolved experiment output root.");
+        }
+        const target = resolveExperimentTarget(args.targetPath, toolRoot);
+        if (target.isSelf || target.kind !== "external-local") {
+            throw new Error("Local-repository subject mode requires an external-local target; --target must not be the Lab repository.");
+        }
+        // Fail closed before anything is created: the output root (and the private scratch beneath it) must be outside the target.
+        try {
+            await assertWorkRootOutsideTarget(outputRoot, target.targetRoot);
+        }
+        catch {
+            throw new Error("Experiment output root must not be inside the external target project.");
+        }
+        const configPath = path.resolve(context.invocationCwd, args.localSubjectConfigPath);
+        const localSubjectConfig = await readJsonConfigFile("--local-subject-config", configPath, args.localSubjectConfigPath);
+        // The selected --target is the physical root handed to the Batch 1 loader; the config carries no path.
+        const localSubject = await loadLocalRepositorySubject({ config: localSubjectConfig, repositoryPath: target.targetRoot });
+        return { cases: localSubject.evaluationCases, localSubject, env: process.env };
+    }
     if (args.syntheticConfigPath !== undefined) {
         if (outputRoot === undefined) {
             throw new Error("Internal error: synthetic generation requires a resolved experiment output root.");
@@ -396,20 +488,27 @@ async function loadContextWindowScalingInputs(args, toolRoot, context, outputRoo
 }
 // The command only reads and parses the caller-supplied file; schema validation belongs to the synthetic planner.
 async function readSyntheticConfigJson(resolvedPath, displayPath) {
+    return readJsonConfigFile("--synthetic-config", resolvedPath, displayPath);
+}
+async function readJsonConfigFile(flag, resolvedPath, displayPath) {
     let text;
     try {
         text = await readFile(resolvedPath, "utf8");
     }
     catch (error) {
-        throw new Error(`Cannot read --synthetic-config ${displayPath}: ${error instanceof Error ? error.message : String(error)}`);
+        throw new Error(`Cannot read ${flag} ${displayPath}: ${error instanceof Error ? error.message : String(error)}`);
     }
     try {
         return JSON.parse(text);
     }
     catch (error) {
-        throw new Error(`--synthetic-config ${displayPath} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+        throw new Error(`${flag} ${displayPath} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
+function readLoadedLocalSubject(inputs) {
+    const value = inputs?.localSubject;
+    return value && typeof value === "object" ? value : undefined;
+}
 // Shared by both registered plugins: explicit paths resolve against toolRoot, defaults come from
 // bundled package resources so they do not depend on the invocation cwd.
 async function loadCasesAndProjectProfiles(args, toolRoot, context) {

package/dist/src/core/fileGlobs.js

@@ -98,3 +98,47 @@ export function collectFilesForGlobs(targetRoot, globs) {
         .sort(([a], [b]) => a.localeCompare(b))
         .map(([relativePath, absolutePath]) => ({ relativePath, absolutePath }));
 }
+/**
+ * Pure counterpart of `collectFilesForGlobs` for a caller-supplied, already validated list of repository-relative
+ * file paths. It applies the same glob matching and the same walk exclusions (excluded directory names below the
+ * glob base directory, temp files) and the same ordering, but never touches the filesystem, so the caller decides
+ * which files may be opened at all. Unlike the walking variant it does not require the base directory to exist.
+ */
+export function selectRelativePathsForGlobs(relativePaths, globs) {
+    const selected = new Set();
+    for (const globPattern of globs) {
+        if (!globPattern || typeof globPattern !== "string") {
+            throw new Error("Invalid glob pattern.");
+        }
+        const baseDir = baseDirectoryFromGlob(globPattern);
+        if (baseDir.split("/").includes("..") || path.isAbsolute(baseDir)) {
+            throw new Error(`Resolved path escapes target root: ${globPattern}`);
+        }
+        // Linear scan for the trailing "/" run (a regular expression here is a polynomial-backtracking risk on
+        // glob text that comes from user configuration).
+        let baseEnd = baseDir.length;
+        while (baseEnd > 0 && baseDir.charCodeAt(baseEnd - 1) === 47)
+            baseEnd -= 1;
+        const normalizedBase = baseDir === "." ? "" : baseDir.slice(0, baseEnd);
+        for (const relativePath of relativePaths) {
+            const normalizedPath = relativePath.replace(/\\/g, "/");
+            if (normalizedPath === normalizedBase) {
+                // An exact file base is used as-is by the walking variant (no walk exclusions apply).
+                if (matchesGlob(normalizedPath, globPattern))
+                    selected.add(normalizedPath);
+                continue;
+            }
+            if (normalizedBase !== "" && !normalizedPath.startsWith(`${normalizedBase}/`))
+                continue;
+            const belowBase = normalizedBase === "" ? normalizedPath : normalizedPath.slice(normalizedBase.length + 1);
+            const directorySegments = belowBase.split("/").slice(0, -1);
+            if (directorySegments.some((segment) => excludedDirNames.has(segment)))
+                continue;
+            if (isTempFile(normalizedPath))
+                continue;
+            if (matchesGlob(normalizedPath, globPattern))
+                selected.add(normalizedPath);
+        }
+    }
+    return [...selected].sort((a, b) => a.localeCompare(b));
+}