@dailephd/my-dev-kit-lab 0.5.2 → 0.6.0

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to my-dev-kit-lab are documented here.
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-09-24
+
+Index freshness and changed-file detection.
+
+- Added `IndexSnapshotV1` (schema `my-dev-kit-lab-index-snapshot-v1`): after a warm-index run's one index build, Lab interprets the my-dev-kit manifest and symbol index and records baseline index evidence — manifest metadata, the exact indexed-file set the upstream index contract lists (never a directory walk), per-file SHA-256, size, and modified-time metadata, the index command, and an inventory of generated index artifacts. Snapshots are `complete`, `partial`, or `unavailable` with explicit reasons; source contents are never persisted.
+- Added a configured my-dev-kit `--version` probe, run once per prepared index session outside the measured index build. An unsupported or failing probe is non-fatal and recorded as explicitly unavailable.
+- Added `IndexFreshnessAssessmentV1` (schema `my-dev-kit-lab-index-freshness-v1`): a read-only comparison of the files the snapshot lists against their current state. SHA-256 is the comparison identity; modified time is diagnostic only. Modified and missing indexed files are confirmed changes; unreadable or unresolvable files stay explicit unresolved evidence; files absent from the snapshot are not inferred to be newly indexable. Exactly four statuses: `fresh`, `stale`, `partially-stale`, `unknown`.
+- Freshness is assessed for every task immediately before its warm retrieval and is observational only: it never triggers or recommends reindexing, suppresses retrieval, or changes execution, provider, agent, correctness, or token-evidence status. One index is still built per benchmark project.
+- Extended `warm-index-execution.json` additively (schema `my-dev-kit-lab-warm-index-execution-v1` unchanged) with project-level `indexSnapshot` and task-level `indexFreshness`.
+- Extended the warm-index report additively (schema `my-dev-kit-lab-warm-index-report-v1` unchanged) with an index freshness summary (assessed, unassessed, fresh, stale, partially-stale, and unknown task counts) and per-task freshness evidence in `report.json`, `report.txt`, and `report.html`. Report evidence is bounded to 20 changed files and 10 unresolved entries per task, omits content hashes, and escapes dynamic strings; a task with no assessment is shown as not assessed, distinct from `unknown`. Report limitations and the run interpretation state what freshness does and does not establish.
+- No new CLI command or flag, `ExperimentMetric`, plot, gallery item, or experiment plugin was added: the warm-index metrics, exactly four plots, and the three-item campaign gallery are unchanged, and no reindex recommendation exists.
+- Extended the packed-package acceptance gate (`npm run verify:packed-package`) to prove the exact tarball ships the snapshot and freshness runtime and that an installed warm-index run produces snapshot, tool-version, freshness, and report freshness evidence while the target, installed package, and packaged examples stay unchanged.
+- Validation of the implementation candidate: exact-SHA ordinary CI passed on Ubuntu, macOS, and Windows with Node 24 and latest, and the full local suite passed with the packed-package gate.
+
 ## [0.5.2] - 2026-09-23
 
 Warm-index real-agent campaigns.

package/README.md

@@ -6,9 +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.5.2 (warm-index real-agent campaigns). The previous release, v0.5.1, added the expanded warm-index benchmark suite. 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).
-
-The current release is v0.5.2, and the package and installed CLI are version 0.5.2. v0.5.1 (expanded warm-index benchmark suite) is the previous release; v0.6.0 (index freshness and changed-file detection) is next planned. See [docs/CURRENT_STATE.md](docs/CURRENT_STATE.md) for current state.
+The latest release is v0.6.0 (index freshness and changed-file detection), and the package and installed CLI are version 0.6.0. The previous release is v0.5.2 (warm-index real-agent campaigns), and v0.6.1 (affected-neighborhood experiments) is next planned. 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.
 
@@ -17,6 +15,7 @@ v0.4.6 adds a supported `my-dev-kit-lab` installed CLI router (`--help`, `--vers
 - **Run context-strategy experiments:** compare `raw-full-file` with `my-dev-kit-guided` using deterministic fixtures or locally configured Codex and Claude CLIs.
 - **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, a best-effort report screenshot (skipped without a browser runtime, never fatal), and a three-item gallery (report, plots, bounded execution evidence). 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, current):** 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. See [docs/METRICS.md](docs/METRICS.md#index-freshness-evidence-v060) 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.
 - **Validate Android projects:** run nineteen static checks by default, with Gradle operations, external tools, and network access available only through explicit opt-in flags.
@@ -200,7 +199,7 @@ When `--target` is omitted, the experiment runs in self mode against my-dev-kit-
 | Plugin experiment report JSON | `lab-output/experiments/<plugin>/<target>/<run>/report.json` |
 | Plugin experiment report HTML | `lab-output/experiments/<plugin>/<target>/<run>/report.html` |
 | Plugin experiment report text | `lab-output/experiments/<plugin>/<target>/<run>/report.txt` |
-| Warm-index execution evidence | `<experiment out>/warm-index-execution.json` (plus `indexes/`, `commands/`, and `agents/` beneath the same output root) |
+| Warm-index execution evidence | `<experiment out>/warm-index-execution.json` (plus `indexes/`, `commands/`, and `agents/` beneath the same output root); the v0.6.0 artifact carries project-level `indexSnapshot` and per-task `indexFreshness` evidence |
 | Warm-index campaign presentation (v0.5.2) | `<experiment out>/plots/` (four charts), `<experiment out>/report.png` (best-effort), `<experiment out>/gallery/gallery-manifest.json` and `gallery-index.html` — automatic for `--campaign` runs only |
 | Plot data | `lab-output/<plots>/plot-data.json` |
 | SVG charts | `lab-output/<plots>/charts/*.svg` |

package/dist/src/evaluation/indexFreshness.js

@@ -0,0 +1,199 @@
+import { realpath } from "node:fs/promises";
+import { compareCodeUnits, mapInBatches, resolveIndexedFilePath, snapshotIndexedFile, } from "./indexSnapshot.js";
+export const INDEX_FRESHNESS_SCHEMA_VERSION = "my-dev-kit-lab-index-freshness-v1";
+const MAX_CHANGES = 100;
+const MAX_UNRESOLVED = 50;
+const MAX_REPORTED_PATH_LENGTH = 260;
+const SHA256_PATTERN = /^[0-9a-f]{64}$/;
+/**
+ * Policy: the four-state freshness decision table. `fresh` requires a complete baseline and a
+ * complete comparison with no confirmed change; a confirmed change is `stale` only when the
+ * comparison was complete, otherwise `partially-stale`; without a confirmed change an incomplete
+ * comparison is `unknown`. Never converts uncertainty to `fresh`. Pure.
+ */
+export function classifyIndexFreshness(input) {
+    if (input.baselineSnapshotStatus === "unavailable") {
+        return "unknown";
+    }
+    const comparisonComplete = input.baselineSnapshotStatus === "complete" && input.unresolvedCount === 0;
+    if (input.confirmedChangeCount > 0) {
+        return comparisonComplete ? "stale" : "partially-stale";
+    }
+    return comparisonComplete ? "fresh" : "unknown";
+}
+function boundedText(value) {
+    return value.length > MAX_REPORTED_PATH_LENGTH ? `${value.slice(0, MAX_REPORTED_PATH_LENGTH)}...` : value;
+}
+function isValidBaselineEntry(entry) {
+    if (typeof entry !== "object" || entry === null)
+        return false;
+    const candidate = entry;
+    return (typeof candidate.path === "string" &&
+        candidate.path.length > 0 &&
+        typeof candidate.sha256 === "string" &&
+        SHA256_PATTERN.test(candidate.sha256) &&
+        typeof candidate.sizeBytes === "number" &&
+        typeof candidate.modifiedAt === "string");
+}
+async function compareIndexedFile(targetRoot, realTargetRoot, sourceRoots, entry) {
+    if (!isValidBaselineEntry(entry)) {
+        const listedPath = typeof entry?.path === "string" ? boundedText(entry.path) : null;
+        return {
+            kind: "unresolved",
+            unresolved: {
+                path: listedPath,
+                reasonCode: "unsupported-snapshot-entry",
+                message: "Snapshot entry lacks a path, SHA-256, size, or modified time.",
+            },
+        };
+    }
+    const resolution = resolveIndexedFilePath(targetRoot, sourceRoots, entry.path);
+    if (!resolution.ok) {
+        return {
+            kind: "unresolved",
+            unresolved: { path: boundedText(entry.path), reasonCode: "unsafe-path", message: `Path cannot be safely resolved (${resolution.reason}).` },
+        };
+    }
+    const current = await snapshotIndexedFile(targetRoot, realTargetRoot, resolution.relativePath);
+    if (!current.ok) {
+        if (current.reason === "missing") {
+            return {
+                kind: "change",
+                change: {
+                    path: entry.path,
+                    changeType: "missing",
+                    baselineSha256: entry.sha256,
+                    baselineSizeBytes: entry.sizeBytes,
+                    baselineModifiedAt: entry.modifiedAt,
+                    currentSha256: null,
+                    currentSizeBytes: null,
+                    currentModifiedAt: null,
+                },
+            };
+        }
+        const unsafe = current.reason === "outside-target-or-source-roots" || current.reason === "invalid-path";
+        return {
+            kind: "unresolved",
+            unresolved: {
+                path: boundedText(entry.path),
+                reasonCode: unsafe ? "unsafe-path" : "file-read-failed",
+                message: unsafe ? "Current file resolves outside the target." : `Current file could not be read as a regular file (${current.reason}).`,
+            },
+        };
+    }
+    if (current.file.sha256 === entry.sha256) {
+        return { kind: "unchanged" };
+    }
+    return {
+        kind: "change",
+        change: {
+            path: entry.path,
+            changeType: "modified",
+            baselineSha256: entry.sha256,
+            baselineSizeBytes: entry.sizeBytes,
+            baselineModifiedAt: entry.modifiedAt,
+            currentSha256: current.file.sha256,
+            currentSizeBytes: current.file.sizeBytes,
+            currentModifiedAt: current.file.modifiedAt,
+        },
+    };
+}
+/**
+ * Compares the files an index snapshot lists against their current state. Read-only: never
+ * modifies the target, invokes my-dev-kit, re-indexes, or retrieves. Files that exist now but are
+ * absent from the snapshot are deliberately ignored — the snapshot records the exact indexed set,
+ * not everything under the source roots, so "added" files cannot be inferred truthfully. Never
+ * throws; an unassessable input yields an explicit `unknown` assessment.
+ */
+export async function assessIndexFreshness(options) {
+    const { snapshot, targetRoot, sourceRoots } = options;
+    const assessedAt = (options.now ?? (() => new Date()))().toISOString();
+    const baselineSnapshotStatus = snapshot?.status ?? "unavailable";
+    const changes = [];
+    const unresolved = [];
+    let unchangedFileCount = 0;
+    let unresolvedTotal = 0;
+    const addUnresolved = (entry, count = 1) => {
+        unresolvedTotal += count;
+        unresolved.push(entry);
+    };
+    try {
+        if (!snapshot || snapshot.status === "unavailable") {
+            addUnresolved({
+                path: null,
+                reasonCode: "snapshot-unavailable",
+                message: snapshot?.unavailable ? boundedText(snapshot.unavailable.message) : "No index snapshot is available for this session.",
+            });
+        }
+        else {
+            let realTargetRoot;
+            try {
+                realTargetRoot = await realpath(targetRoot);
+            }
+            catch {
+                addUnresolved({ path: null, reasonCode: "file-read-failed", message: "Target root could not be resolved." });
+            }
+            if (snapshot.status === "complete" && snapshot.files.length !== snapshot.indexedFileCount) {
+                addUnresolved({
+                    path: null,
+                    reasonCode: "unsupported-snapshot-entry",
+                    message: `Complete snapshot lists ${snapshot.indexedFileCount} indexed files but carries ${snapshot.files.length} entries.`,
+                });
+            }
+            for (const entry of snapshot.unresolvedFiles) {
+                addUnresolved({
+                    path: entry.path,
+                    reasonCode: "snapshot-file-unresolved",
+                    message: `The index snapshot could not hash this indexed file (${entry.reason}).`,
+                });
+            }
+            // Unresolved entries the snapshot itself truncated still count toward the total.
+            unresolvedTotal += Math.max(0, snapshot.unresolvedFileCount - snapshot.unresolvedFiles.length);
+            if (realTargetRoot !== undefined) {
+                const rootForComparison = realTargetRoot;
+                const comparisons = await mapInBatches(snapshot.files, (entry) => compareIndexedFile(targetRoot, rootForComparison, sourceRoots, entry));
+                for (const comparison of comparisons) {
+                    if (comparison.kind === "unchanged")
+                        unchangedFileCount += 1;
+                    else if (comparison.kind === "change")
+                        changes.push(comparison.change);
+                    else
+                        addUnresolved(comparison.unresolved);
+                }
+            }
+        }
+    }
+    catch (error) {
+        addUnresolved({
+            path: null,
+            reasonCode: "file-read-failed",
+            message: boundedText(`Freshness comparison failed: ${error instanceof Error ? error.message : String(error)}`),
+        });
+    }
+    changes.sort((left, right) => compareCodeUnits(left.path, right.path) || compareCodeUnits(left.changeType, right.changeType));
+    unresolved.sort((left, right) => compareCodeUnits(left.path ?? "", right.path ?? "") || compareCodeUnits(left.reasonCode, right.reasonCode) || compareCodeUnits(left.message, right.message));
+    const modifiedCount = changes.filter((change) => change.changeType === "modified").length;
+    const missingCount = changes.length - modifiedCount;
+    const warnings = [];
+    if (changes.length > MAX_CHANGES)
+        warnings.push(`Change list truncated to ${MAX_CHANGES} of ${changes.length} entries.`);
+    if (unresolved.length > MAX_UNRESOLVED)
+        warnings.push(`Unresolved list truncated to ${MAX_UNRESOLVED} of ${unresolved.length} entries.`);
+    return {
+        schemaVersion: INDEX_FRESHNESS_SCHEMA_VERSION,
+        status: classifyIndexFreshness({ baselineSnapshotStatus, confirmedChangeCount: changes.length, unresolvedCount: unresolvedTotal }),
+        assessedAt,
+        baselineSnapshotStatus,
+        indexedFileCount: snapshot?.indexedFileCount ?? 0,
+        comparableFileCount: unchangedFileCount + modifiedCount,
+        unchangedFileCount,
+        changedFileCount: modifiedCount,
+        missingFileCount: missingCount,
+        unresolvedFileCount: unresolvedTotal,
+        changes: changes.slice(0, MAX_CHANGES),
+        changesTruncated: changes.length > MAX_CHANGES,
+        unresolved: unresolved.slice(0, MAX_UNRESOLVED),
+        unresolvedTruncated: unresolvedTotal > Math.min(unresolved.length, MAX_UNRESOLVED),
+        warnings,
+    };
+}

package/dist/src/evaluation/indexSnapshot.js

@@ -0,0 +1,393 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { readdir, readFile, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import { relativeWithinRoot, resolveWithinRoot } from "../core/pathSafety.js";
+export const INDEX_SNAPSHOT_SCHEMA_VERSION = "my-dev-kit-lab-index-snapshot-v1";
+const SUPPORTED_MANIFEST_ARTIFACT_KIND = "my-dev-kit-v1-manifest";
+const SUPPORTED_MANIFEST_VERSION_PATTERN = /^1\./;
+const MANIFEST_FILE = "manifest.json";
+const MAX_ARTIFACT_ENTRIES = 512;
+const MAX_UNRESOLVED_ENTRIES = 50;
+const MAX_REPORTED_PATH_LENGTH = 260;
+const HASH_CONCURRENCY = 32;
+const MAX_TOOL_VERSION_LENGTH = 128;
+const TOOL_VERSION_NOT_PROBED = {
+    name: "my-dev-kit",
+    version: null,
+    availability: "unavailable",
+    reason: "The my-dev-kit index manifest and index command output do not expose the tool version, and no --version probe result was supplied.",
+};
+/**
+ * Policy: turns the outcome of a `<kit-command> --version` probe into bounded tool evidence. Uses
+ * the first non-empty output line verbatim (no semver requirement); anything unsupported, empty,
+ * unprintable, or oversized is explicitly unavailable rather than guessed. Pure.
+ */
+export function interpretToolVersionOutput(probe) {
+    const unavailable = (reason) => ({
+        name: "my-dev-kit",
+        version: null,
+        availability: "unavailable",
+        reason: boundedText(reason),
+    });
+    if (!probe.ok) {
+        const detail = probe.error ? `: ${probe.error}` : "";
+        return unavailable(`The --version probe did not succeed (exit code ${probe.exitCode ?? "none"})${detail}`);
+    }
+    const line = probe.stdout.split(/\r?\n/).map((entry) => entry.trim()).find((entry) => entry.length > 0);
+    if (line === undefined) {
+        return unavailable("The --version probe produced no output.");
+    }
+    if (/[\u0000-\u001f\u007f]/.test(line)) {
+        return unavailable("The --version probe reported a non-printable value.");
+    }
+    if (line.length > MAX_TOOL_VERSION_LENGTH) {
+        return unavailable(`The --version probe reported a value longer than ${MAX_TOOL_VERSION_LENGTH} characters.`);
+    }
+    return { name: "my-dev-kit", version: line, availability: "available", reason: null };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Locale- and platform-independent ordering so snapshots never depend on enumeration order. */
+export function compareCodeUnits(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function boundedText(value) {
+    return value.length > MAX_REPORTED_PATH_LENGTH ? `${value.slice(0, MAX_REPORTED_PATH_LENGTH)}...` : value;
+}
+/**
+ * Policy: validates the manifest against the supported my-dev-kit contract and the expected
+ * target. Pure; performs no filesystem access.
+ */
+export function interpretIndexManifest(manifest, expected) {
+    const unsupported = (message) => ({ ok: false, code: "manifest-unsupported", message });
+    if (!isRecord(manifest)) {
+        return unsupported("Index manifest is not a JSON object.");
+    }
+    if (manifest.artifactKind !== SUPPORTED_MANIFEST_ARTIFACT_KIND) {
+        return unsupported(`Index manifest artifactKind is not ${SUPPORTED_MANIFEST_ARTIFACT_KIND}.`);
+    }
+    if (typeof manifest.version !== "string" || !SUPPORTED_MANIFEST_VERSION_PATTERN.test(manifest.version)) {
+        return unsupported("Index manifest version is missing or not a supported 1.x version.");
+    }
+    const artifacts = manifest.artifacts;
+    const symbolIndexPath = isRecord(artifacts) ? artifacts.symbolIndex : undefined;
+    if (typeof symbolIndexPath !== "string" || symbolIndexPath.length === 0) {
+        return unsupported("Index manifest does not name a symbolIndex artifact.");
+    }
+    if (typeof manifest.projectRoot !== "string" || manifest.projectRoot.length === 0) {
+        return unsupported("Index manifest does not record a projectRoot.");
+    }
+    const sourceRoots = manifest.sourceRoots;
+    if (!Array.isArray(sourceRoots) || !sourceRoots.every((root) => typeof root === "string")) {
+        return unsupported("Index manifest does not record sourceRoots.");
+    }
+    const sameSourceRoots = sourceRoots.length === expected.sourceRoots.length && sourceRoots.every((root, index) => root === expected.sourceRoots[index]);
+    if (!sameSourceRoots) {
+        return {
+            ok: false,
+            code: "manifest-target-mismatch",
+            message: `Index manifest source roots [${sourceRoots.join(", ")}] do not match [${expected.sourceRoots.join(", ")}].`,
+        };
+    }
+    const summary = manifest.summary;
+    const manifestFileCount = isRecord(summary) && typeof summary.fileCount === "number" ? summary.fileCount : null;
+    return {
+        ok: true,
+        contract: {
+            manifestArtifactKind: manifest.artifactKind,
+            manifestVersion: manifest.version,
+            createdAt: typeof manifest.createdAt === "string" ? manifest.createdAt : null,
+            symbolIndexRelativePath: symbolIndexPath,
+            manifestFileCount,
+            sourceRoots: [...sourceRoots],
+            projectRoot: manifest.projectRoot,
+        },
+    };
+}
+/**
+ * Policy: extracts the exact indexed-file path list from a symbol-index artifact. The count the
+ * index declares must agree with the list; duplicates are rejected rather than merged.
+ */
+export function interpretSymbolIndexFiles(symbolIndex, manifestFileCount) {
+    const unsupported = (message) => ({ ok: false, code: "symbol-index-unsupported", message });
+    if (!isRecord(symbolIndex)) {
+        return unsupported("Symbol index is not a JSON object.");
+    }
+    if (typeof symbolIndex.schemaVersion !== "string") {
+        return unsupported("Symbol index does not record a schemaVersion.");
+    }
+    const files = symbolIndex.files;
+    if (!Array.isArray(files)) {
+        return unsupported("Symbol index does not list indexed files.");
+    }
+    const paths = [];
+    for (const entry of files) {
+        if (!isRecord(entry) || typeof entry.path !== "string" || entry.path.length === 0) {
+            return unsupported("Symbol index contains a file entry without a path.");
+        }
+        paths.push(entry.path);
+    }
+    if (new Set(paths).size !== paths.length) {
+        return unsupported("Symbol index lists the same file path more than once.");
+    }
+    const declaredCounts = [symbolIndex.fileCount, manifestFileCount].filter((count) => typeof count === "number");
+    if (declaredCounts.some((count) => count !== paths.length)) {
+        return {
+            ok: false,
+            code: "indexed-file-count-mismatch",
+            message: `Symbol index lists ${paths.length} files but the index declares ${declaredCounts.join("/")}.`,
+        };
+    }
+    return { ok: true, schemaVersion: symbolIndex.schemaVersion, paths };
+}
+/**
+ * Policy: normalizes an index-listed path to a target-relative forward-slash path and confirms it
+ * stays inside the target and one of the configured source roots. Pure.
+ */
+export function resolveIndexedFilePath(targetRoot, sourceRoots, listedPath) {
+    const forward = listedPath.replace(/\\/g, "/");
+    if (forward.length === 0 || forward.includes("\0") || forward.startsWith("/") || /^[A-Za-z]:/.test(forward)) {
+        return { ok: false, reason: "invalid-path" };
+    }
+    try {
+        const absolute = resolveWithinRoot(targetRoot, forward);
+        const relativePath = relativeWithinRoot(targetRoot, absolute);
+        if (relativePath.length === 0) {
+            return { ok: false, reason: "invalid-path" };
+        }
+        const insideSourceRoot = sourceRoots.some((sourceRoot) => {
+            try {
+                relativeWithinRoot(resolveWithinRoot(targetRoot, sourceRoot), absolute);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        });
+        return insideSourceRoot ? { ok: true, relativePath } : { ok: false, reason: "outside-target-or-source-roots" };
+    }
+    catch {
+        return { ok: false, reason: "outside-target-or-source-roots" };
+    }
+}
+async function hashFile(absolutePath) {
+    const hash = createHash("sha256");
+    let sizeBytes = 0;
+    for await (const chunk of createReadStream(absolutePath)) {
+        const buffer = chunk;
+        sizeBytes += buffer.length;
+        hash.update(buffer);
+    }
+    return { sha256: hash.digest("hex"), sizeBytes };
+}
+/** Reads and hashes one target-relative file without leaving the target (symlinks are resolved first). */
+export async function snapshotIndexedFile(targetRoot, realTargetRoot, relativePath) {
+    const absolutePath = path.resolve(targetRoot, relativePath);
+    try {
+        // A symlink must not carry the read outside the target.
+        const realPath = await realpath(absolutePath);
+        try {
+            relativeWithinRoot(realTargetRoot, realPath);
+        }
+        catch {
+            return { ok: false, reason: "outside-target-or-source-roots" };
+        }
+        const stats = await stat(realPath);
+        if (!stats.isFile()) {
+            return { ok: false, reason: "not-a-file" };
+        }
+        const { sha256, sizeBytes } = await hashFile(realPath);
+        return { ok: true, file: { path: relativePath, sha256, sizeBytes, modifiedAt: stats.mtime.toISOString() } };
+    }
+    catch (error) {
+        return { ok: false, reason: error.code === "ENOENT" ? "missing" : "unreadable" };
+    }
+}
+async function enumerateIndexArtifacts(indexDir) {
+    const artifacts = [];
+    let truncated = false;
+    const pending = [indexDir];
+    while (pending.length > 0) {
+        const directory = pending.pop();
+        for (const entry of await readdir(directory, { withFileTypes: true })) {
+            const absolutePath = path.join(directory, entry.name);
+            if (entry.isDirectory()) {
+                pending.push(absolutePath);
+            }
+            else if (entry.isFile()) {
+                if (artifacts.length >= MAX_ARTIFACT_ENTRIES) {
+                    truncated = true;
+                    continue;
+                }
+                artifacts.push({ path: relativeWithinRoot(indexDir, absolutePath), sizeBytes: (await stat(absolutePath)).size });
+            }
+        }
+    }
+    artifacts.sort((left, right) => compareCodeUnits(left.path, right.path));
+    return { artifacts, truncated };
+}
+async function readJson(filePath) {
+    let text;
+    try {
+        text = await readFile(filePath, "utf8");
+    }
+    catch (error) {
+        const missing = error.code === "ENOENT";
+        return { ok: false, missing, message: missing ? "file does not exist" : `file could not be read: ${error.message}` };
+    }
+    try {
+        return { ok: true, value: JSON.parse(text) };
+    }
+    catch (error) {
+        return { ok: false, missing: false, message: `file is not valid JSON: ${error.message}` };
+    }
+}
+/** Runs `fn` over `items` with bounded concurrency, returning results in input order. */
+export async function mapInBatches(items, fn) {
+    const results = [];
+    for (let start = 0; start < items.length; start += HASH_CONCURRENCY) {
+        results.push(...(await Promise.all(items.slice(start, start + HASH_CONCURRENCY).map(fn))));
+    }
+    return results;
+}
+function unavailableSnapshot(command, failure, tool, manifest = null) {
+    return {
+        schemaVersion: INDEX_SNAPSHOT_SCHEMA_VERSION,
+        status: "unavailable",
+        unavailable: { code: failure.code, message: boundedText(failure.message) },
+        manifest,
+        tool: { ...tool },
+        indexCommand: summarizeIndexCommand(command),
+        indexedFileCount: 0,
+        files: [],
+        unresolvedFileCount: 0,
+        unresolvedFiles: [],
+        artifacts: [],
+        artifactsTruncated: false,
+    };
+}
+function summarizeIndexCommand(command) {
+    return { commandString: command.commandString, executable: command.executable, args: [...command.args] };
+}
+/**
+ * Captures bounded index-build evidence from an already built index: which files the index lists,
+ * their SHA-256 content identity, and the generated artifact inventory. Reads only the index
+ * directory and the listed files inside the target; runs no my-dev-kit command and never throws —
+ * an uninterpretable index yields an explicit `unavailable` snapshot instead of a guessed one.
+ * Performs no comparison and assigns no freshness.
+ */
+export async function captureIndexSnapshot(options) {
+    const { indexDir, targetRoot, sourceRoots, command } = options;
+    const tool = options.tool ?? TOOL_VERSION_NOT_PROBED;
+    try {
+        const manifestRead = await readJson(path.join(indexDir, MANIFEST_FILE));
+        if (!manifestRead.ok) {
+            return unavailableSnapshot(command, {
+                ok: false,
+                code: manifestRead.missing ? "manifest-missing" : "manifest-unreadable",
+                message: `Index manifest ${manifestRead.message}.`,
+            }, tool);
+        }
+        const manifest = interpretIndexManifest(manifestRead.value, { sourceRoots });
+        if (!manifest.ok) {
+            return unavailableSnapshot(command, manifest, tool);
+        }
+        const { contract } = manifest;
+        const realTargetRoot = await realpath(targetRoot);
+        let manifestRoot;
+        try {
+            manifestRoot = await realpath(contract.projectRoot);
+        }
+        catch {
+            manifestRoot = path.resolve(contract.projectRoot);
+        }
+        if (path.relative(realTargetRoot, manifestRoot) !== "") {
+            return unavailableSnapshot(command, {
+                ok: false,
+                code: "manifest-target-mismatch",
+                message: "Index manifest projectRoot does not match the target root.",
+            }, tool);
+        }
+        let symbolIndexFile;
+        try {
+            symbolIndexFile = resolveWithinRoot(indexDir, contract.symbolIndexRelativePath);
+        }
+        catch {
+            return unavailableSnapshot(command, {
+                ok: false,
+                code: "manifest-unsupported",
+                message: "Index manifest symbolIndex path escapes the index directory.",
+            }, tool);
+        }
+        const symbolIndexRead = await readJson(symbolIndexFile);
+        if (!symbolIndexRead.ok) {
+            return unavailableSnapshot(command, {
+                ok: false,
+                code: symbolIndexRead.missing ? "symbol-index-missing" : "symbol-index-unreadable",
+                message: `Symbol index ${symbolIndexRead.message}.`,
+            }, tool);
+        }
+        const symbolIndex = interpretSymbolIndexFiles(symbolIndexRead.value, contract.manifestFileCount);
+        const manifestSummary = {
+            path: MANIFEST_FILE,
+            artifactKind: contract.manifestArtifactKind,
+            schemaVersion: contract.manifestVersion,
+            createdAt: contract.createdAt,
+            symbolIndexPath: relativeWithinRoot(indexDir, symbolIndexFile),
+            symbolIndexSchemaVersion: symbolIndex.ok ? symbolIndex.schemaVersion : "unknown",
+        };
+        if (!symbolIndex.ok) {
+            return unavailableSnapshot(command, symbolIndex, tool, manifestSummary);
+        }
+        const resolved = symbolIndex.paths.map((listed) => ({ listed, resolution: resolveIndexedFilePath(targetRoot, sourceRoots, listed) }));
+        const unresolved = [];
+        const toHash = [];
+        for (const { listed, resolution } of resolved) {
+            if (resolution.ok) {
+                toHash.push(resolution.relativePath);
+            }
+            else {
+                unresolved.push({ path: boundedText(listed), reason: resolution.reason });
+            }
+        }
+        const files = [];
+        for (let start = 0; start < toHash.length; start += HASH_CONCURRENCY) {
+            const batch = toHash.slice(start, start + HASH_CONCURRENCY);
+            const results = await Promise.all(batch.map((relativePath) => snapshotIndexedFile(targetRoot, realTargetRoot, relativePath)));
+            results.forEach((result, position) => {
+                if (result.ok) {
+                    files.push(result.file);
+                }
+                else {
+                    unresolved.push({ path: boundedText(batch[position]), reason: result.reason });
+                }
+            });
+        }
+        files.sort((left, right) => compareCodeUnits(left.path, right.path));
+        unresolved.sort((left, right) => compareCodeUnits(left.path, right.path) || compareCodeUnits(left.reason, right.reason));
+        const inventory = await enumerateIndexArtifacts(indexDir);
+        return {
+            schemaVersion: INDEX_SNAPSHOT_SCHEMA_VERSION,
+            status: unresolved.length === 0 ? "complete" : "partial",
+            unavailable: null,
+            manifest: manifestSummary,
+            tool: { ...tool },
+            indexCommand: summarizeIndexCommand(command),
+            indexedFileCount: symbolIndex.paths.length,
+            files,
+            unresolvedFileCount: unresolved.length,
+            unresolvedFiles: unresolved.slice(0, MAX_UNRESOLVED_ENTRIES),
+            artifacts: inventory.artifacts,
+            artifactsTruncated: inventory.truncated,
+        };
+    }
+    catch (error) {
+        return unavailableSnapshot(command, {
+            ok: false,
+            code: "snapshot-capture-failed",
+            message: `Index snapshot capture failed: ${error.message}`,
+        }, tool);
+    }
+}

package/dist/src/evaluation/runMyDevKitRetrieval.js

@@ -1,6 +1,8 @@
 import path from "node:path";
 import { countEstimatedTokens, countTextChars, tokenCountMethod } from "../core/countTokens.js";
 import { runMeasuredCommand } from "../core/runMeasuredCommand.js";
+import { interpretToolVersionOutput } from "./indexSnapshot.js";
+const VERSION_PROBE_TIMEOUT_MS = 30_000;
 function parseJsonIfPossible(text) {
     try {
         return JSON.parse(text);
@@ -89,6 +91,38 @@ export async function buildMyDevKitIndex(options) {
         command
     };
 }
+/**
+ * Runs `<kit-command> --version` once through the shared measured-command runner and returns
+ * bounded tool evidence. Kept separate from `buildMyDevKitIndex` so it never counts toward index
+ * duration. An unsupported, failing, slow, or empty probe is explicit `unavailable` evidence; it
+ * never throws and never fails the caller.
+ */
+export async function probeMyDevKitVersion(options) {
+    try {
+        const command = await runMeasuredCommand({
+            commandId: "version",
+            commandString: options.kitCommand,
+            cwd: process.cwd(),
+            outDir: options.commandsDir,
+            extraArgs: ["--version"],
+            timeoutMs: VERSION_PROBE_TIMEOUT_MS
+        });
+        return interpretToolVersionOutput({
+            ok: command.ok,
+            exitCode: command.exitCode,
+            stdout: command.stdout,
+            error: command.error
+        });
+    }
+    catch (error) {
+        return interpretToolVersionOutput({
+            ok: false,
+            exitCode: null,
+            stdout: "",
+            error: error instanceof Error ? error.message : String(error)
+        });
+    }
+}
 /**
  * Runs search -> lookup -> slice -> source against an already prepared index. Never invokes
  * `index`; `durationMs` covers retrieval only.

package/dist/src/experiments/plugins/warmIndexReuse/execution.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { resolveWithinRoot } from "../../../core/pathSafety.js";
+import { assessIndexFreshness } from "../../../evaluation/indexFreshness.js";
 import { runMyDevKitRetrievalFromIndex } from "../../../evaluation/runMyDevKitRetrieval.js";
 import { runRawFullFileBaseline } from "../../../evaluation/runRawFullFileBaseline.js";
 import { groupWarmIndexCases, taskOutputSegment } from "./selection.js";
@@ -90,8 +91,15 @@ async function executeTask(args) {
     }
     let warmRetrieval;
     let warmStatus = "failed";
+    let indexFreshness;
     if (!args.session) {
         errors.push(args.setupFailure ?? { side: "warm", code: "warm-index-setup-failed", message: "No warm index session." });
+        // No snapshot exists, so freshness is conservatively unknown rather than assumed.
+        indexFreshness = await assessIndexFreshness({
+            snapshot: null,
+            targetRoot: evaluationCase.absoluteTargetRoot,
+            sourceRoots: evaluationCase.sourceRoots,
+        });
     }
     else {
         try {
@@ -101,6 +109,12 @@ async function executeTask(args) {
             errors.push({ side: "warm", code: "warm-session-target-mismatch", message: errorMessage(error) });
         }
         if (!errors.some((error) => error.side === "warm")) {
+            // Observational only: measured immediately before reuse, and retrieval below runs regardless.
+            indexFreshness = await assessIndexFreshness({
+                snapshot: args.session.indexSnapshot,
+                targetRoot: args.session.targetRoot,
+                sourceRoots: args.session.sourceRoots,
+            });
             try {
                 // requireKit: false retains subordinate command evidence; a skipped result caused by a
                 // failed command is classified as failed below rather than as an honest skip.
@@ -134,6 +148,7 @@ async function executeTask(args) {
         warmStatus,
         rawBaseline,
         warmRetrieval,
+        indexFreshness,
         warnings,
         errors,
     };

package/dist/src/experiments/plugins/warmIndexReuse/executionArtifact.js

@@ -46,6 +46,7 @@ function summarizeTask(task) {
                 commands: warm.commands.map(summarizeCommand),
             }
             : null,
+        indexFreshness: task.indexFreshness ? structuredClone(task.indexFreshness) : null,
         warnings: [...task.warnings],
         errors: task.errors.map((error) => ({ ...error })),
     };
@@ -62,6 +63,7 @@ export function summarizeProjectExecution(project) {
         sessionPrepared: project.session !== undefined,
         buildDurationMs: project.build ? project.build.durationMs : null,
         indexCommand: project.build ? summarizeCommand(project.build.command) : null,
+        indexSnapshot: project.session ? structuredClone(project.session.indexSnapshot) : null,
         tasks: project.tasks.map(summarizeTask),
         warnings: [...project.warnings],
         errors: [...project.errors],

package/dist/src/experiments/plugins/warmIndexReuse/warmIndexSession.js

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import path from "node:path";
-import { buildMyDevKitIndex } from "../../../evaluation/runMyDevKitRetrieval.js";
+import { buildMyDevKitIndex, probeMyDevKitVersion } from "../../../evaluation/runMyDevKitRetrieval.js";
+import { captureIndexSnapshot } from "../../../evaluation/indexSnapshot.js";
 /**
  * Builds the index once through the shared `buildMyDevKitIndex` owner. A build that reports
  * success but leaves no index directory is not treated as a prepared session.
@@ -17,12 +18,26 @@ export async function prepareWarmIndexSession(options) {
         }
         return { ok: false, warnings: [...build.warnings, message], build };
     }
+    const sourceRoots = Object.freeze([...options.target.sourceRoots]);
+    // One `--version` probe per prepared session, outside the measured index build; it never fails
+    // the session (an unsupported probe becomes explicit `unavailable` tool evidence).
+    const tool = await probeMyDevKitVersion({ kitCommand: options.kitCommand, commandsDir: options.commandsDir });
+    // Reads the just-built index and the files it lists; never invokes my-dev-kit again and never
+    // fails the session (an uninterpretable index becomes an explicit `unavailable` snapshot).
+    const indexSnapshot = await captureIndexSnapshot({
+        indexDir: build.indexDir,
+        targetRoot: options.target.absoluteTargetRoot,
+        sourceRoots,
+        command: build.command,
+        tool
+    });
     const session = Object.freeze({
         indexDir: build.indexDir,
         buildDurationMs: build.durationMs,
         targetRoot: options.target.absoluteTargetRoot,
-        sourceRoots: Object.freeze([...options.target.sourceRoots]),
-        buildCommand: build.command
+        sourceRoots,
+        buildCommand: build.command,
+        indexSnapshot
     });
     return { ok: true, session, build };
 }

package/dist/src/report/experiments/buildPluginExperimentReport.js

@@ -97,6 +97,16 @@ function buildFindings(run) {
         ...skipped,
     ];
 }
+/** Neutral, count-only sentence derived from the report's persisted freshness summary. */
+function freshnessSentence(report) {
+    const summary = report.indexFreshnessSummary;
+    if (!summary || summary.assessedTaskCount === 0) {
+        return "No per-task index freshness assessment was available in this report.";
+    }
+    return (`Index freshness was assessed for ${summary.assessedTaskCount} task boundar${summary.assessedTaskCount === 1 ? "y" : "ies"}: ` +
+        `fresh=${summary.freshTaskCount}, stale=${summary.staleTaskCount}, partially-stale=${summary.partiallyStaleTaskCount}, unknown=${summary.unknownTaskCount}. ` +
+        "Freshness is observational evidence over files represented by the index snapshot and does not change retrieval or provider status.");
+}
 function buildInterpretation(run, contextStrategyComparisonV043, warmIndexReuse) {
     if (run.pluginId === "warm-index-reuse" && warmIndexReuse) {
         const summary = warmIndexReuse.summary;
@@ -107,7 +117,8 @@ function buildInterpretation(run, contextStrategyComparisonV043, warmIndexReuse)
                     "The report separates one-time index-build duration from per-task retrieval duration and shows how the fixed build cost is amortized across repeated tasks. " +
                     `Deterministic fake-agent correctness/token evidence is available for ${summary.agentCorrectnessAvailableCount} of ${summary.agentSideCount} task sides (correctness) and ${summary.agentTotalTokensAvailableCount} (total tokens); ` +
                     "fake-agent totals are simulated harness evidence, not real-model or provider measurements. " +
-                    "Estimated context-token values are context-size estimates, not provider token usage.",
+                    "Estimated context-token values are context-size estimates, not provider token usage. " +
+                    freshnessSentence(warmIndexReuse),
                 recommendedNextStep: run.status === "completed"
                     ? "Review per-task measurements and cumulative component costs for each project; the variants are reported side by side and are not ranked."
                     : "Inspect unavailable metrics, warnings, and failures before drawing conclusions from this run.",
@@ -132,7 +143,8 @@ function buildInterpretation(run, contextStrategyComparisonV043, warmIndexReuse)
                 `Agent evidence status: ${campaign.agentEvidenceStatus} (${campaign.executedSideCount} of ${campaign.scheduledSideCount} scheduled sides executed` +
                 `${nonCompletedCounts ? `; outcome counts: ${nonCompletedCounts}` : ""}). ` +
                 `Token evidence status: ${campaign.tokenEvidenceStatus} (${summary.agentTotalTokensAvailableCount} of ${summary.agentSideCount} task sides have a total-token value). ` +
-                "Context estimated tokens remain a separate character-based context-size estimate and are never substituted for provider telemetry.",
+                "Context estimated tokens remain a separate character-based context-size estimate and are never substituted for provider telemetry. " +
+                freshnessSentence(warmIndexReuse),
             recommendedNextStep: isInfrastructureComplete && isAgentEvidenceComplete
                 ? "Review per-task correctness, token provenance, and cumulative component measurements."
                 : "Review infrastructure gaps (index build, raw/warm retrieval) separately from provider/agent limitations before drawing conclusions from this run.",

package/dist/src/report/experiments/buildWarmIndexReuseReport.js

@@ -1,4 +1,4 @@
-import { WARM_INDEX_REUSE_REPORT_SCHEMA_VERSION, } from "./warmIndexReuseReportModel.js";
+import { MAX_REPORT_FRESHNESS_CHANGES, MAX_REPORT_FRESHNESS_UNRESOLVED, WARM_INDEX_REUSE_REPORT_SCHEMA_VERSION, } from "./warmIndexReuseReportModel.js";
 const WARM_INDEX_REUSE_PLUGIN_ID = "warm-index-reuse";
 const COMMON_LIMITATIONS = [
     "Context estimated-token counts use the character-based estimate and are not provider billing telemetry.",
@@ -23,6 +23,13 @@ const CLAUDE_CAMPAIGN_LIMITATIONS = [
     "Token totals may be unavailable for some CLI/version/run outcomes.",
     "Unavailable token totals remain unavailable and are never replaced by zero or a context estimate.",
 ];
+const FRESHNESS_LIMITATIONS = [
+    "Freshness compares only files proven by the index snapshot to have been indexed. It does not establish that the entire repository is unchanged.",
+    "A new file that was not represented in the snapshot is outside the current freshness comparison and is not automatically evidence that the index is stale.",
+    "File content SHA-256 is the comparison identity. Modified timestamps are diagnostic metadata only.",
+    "Freshness is observational evidence. It does not trigger reindexing, suppress warm retrieval, alter execution status, or alter provider/agent outcome status.",
+    "Freshness statuses: fresh means all represented indexed files were completely compared and their content identities still match; stale means a complete comparison confirmed at least one represented indexed file is modified or missing; partially-stale means at least one represented indexed file is confirmed changed but comparison evidence is incomplete; unknown means no confirmed change established staleness but evidence is insufficient to prove freshness. A task without an assessment is reported as not assessed, which is not the same as unknown.",
+];
 const COST_MODEL = [
     "Index construction is a one-time cost per benchmark project; task retrieval is the repeated warm cost.",
     "Cold start: for the first task in a project, the cumulative warm component duration is the one-time index build plus the first retrieval.",
@@ -90,6 +97,7 @@ export function buildWarmIndexReuseReport(run) {
                     warm: task.warm,
                     rawAgent: toReportAgent(rawEvidence),
                     warmAgent: toReportAgent(warmEvidence),
+                    indexFreshness: toReportFreshness(execution.tasks[taskIndex].indexFreshness),
                 };
             }),
         };
@@ -121,6 +129,49 @@ export function buildWarmIndexReuseReport(run) {
         projects,
         agent: agentIdentity,
         agentCampaign,
+        indexFreshnessSummary: summarizeFreshness(projects.flatMap((project) => project.tasks)),
+    };
+}
+function boundedList(source, limit, map) {
+    const items = source.slice(0, limit).map(map);
+    return { totalCount: source.length, displayedCount: items.length, omittedCount: source.length - items.length, items };
+}
+/**
+ * Presents persisted freshness evidence only: it never recomputes a status, count, or hash and
+ * never touches the filesystem. Absent evidence stays null rather than becoming `unknown`.
+ */
+function toReportFreshness(freshness) {
+    if (!freshness)
+        return null;
+    return {
+        status: freshness.status,
+        assessedAt: freshness.assessedAt,
+        baselineSnapshotStatus: freshness.baselineSnapshotStatus,
+        indexedFileCount: freshness.indexedFileCount,
+        comparableFileCount: freshness.comparableFileCount,
+        unchangedFileCount: freshness.unchangedFileCount,
+        changedFileCount: freshness.changedFileCount,
+        missingFileCount: freshness.missingFileCount,
+        unresolvedFileCount: freshness.unresolvedFileCount,
+        changes: boundedList(freshness.changes, MAX_REPORT_FRESHNESS_CHANGES, (change) => ({ path: change.path, changeType: change.changeType })),
+        unresolved: boundedList(freshness.unresolved, MAX_REPORT_FRESHNESS_UNRESOLVED, (entry) => ({
+            path: entry.path,
+            reasonCode: entry.reasonCode,
+            message: entry.message,
+        })),
+        warnings: [...freshness.warnings],
+    };
+}
+function summarizeFreshness(tasks) {
+    const assessed = tasks.flatMap((task) => (task.indexFreshness ? [task.indexFreshness] : []));
+    const count = (status) => assessed.filter((freshness) => freshness.status === status).length;
+    return {
+        assessedTaskCount: assessed.length,
+        unassessedTaskCount: tasks.length - assessed.length,
+        freshTaskCount: count("fresh"),
+        staleTaskCount: count("stale"),
+        partiallyStaleTaskCount: count("partially-stale"),
+        unknownTaskCount: count("unknown"),
     };
 }
 function deriveAgentIdentity(args) {
@@ -191,10 +242,10 @@ function buildCampaignSummary(args) {
 }
 function buildLimitations(agent) {
     if (agent.mode === "deterministic-fake") {
-        return [...COMMON_LIMITATIONS, ...FAKE_AGENT_LIMITATIONS];
+        return [...COMMON_LIMITATIONS, ...FAKE_AGENT_LIMITATIONS, ...FRESHNESS_LIMITATIONS];
     }
     const providerLimitations = agent.id === "codex" ? CODEX_CAMPAIGN_LIMITATIONS : CLAUDE_CAMPAIGN_LIMITATIONS;
-    return [...COMMON_LIMITATIONS, ...providerLimitations];
+    return [...COMMON_LIMITATIONS, ...providerLimitations, ...FRESHNESS_LIMITATIONS];
 }
 function toReportAgent(agent) {
     if (!agent)

package/dist/src/report/experiments/renderPluginExperimentReportText.js

@@ -301,6 +301,7 @@ function renderWarmIndexReuseSection(lines, section) {
     lines.push(fieldLine("Agent Mode", section.agent.mode));
     lines.push(fieldLine("Agent Correctness Available (task sides)", `${section.summary.agentCorrectnessAvailableCount} of ${section.summary.agentSideCount}`));
     lines.push(fieldLine("Agent Token Totals Available (task sides)", `${section.summary.agentTotalTokensAvailableCount} of ${section.summary.agentSideCount}`));
+    renderFreshnessSummary(lines, section);
     if (section.agentCampaign) {
         renderCampaignSection(lines, section.agentCampaign);
     }
@@ -324,6 +325,7 @@ function renderWarmIndexReuseSection(lines, section) {
             const rows = [
                 ["Raw Status", task.rawStatus],
                 ["Warm Status", task.warmStatus],
+                ["Index Freshness Status", task.indexFreshness ? task.indexFreshness.status : "not assessed"],
                 ["Raw Context Characters", formatWarmMetric(task.raw.contextCharacters)],
                 ["Warm Context Characters", formatWarmMetric(task.warm.contextCharacters)],
                 ["Raw Estimated Context Tokens (estimate)", formatWarmMetric(task.raw.contextEstimatedTokens)],
@@ -347,9 +349,62 @@ function renderWarmIndexReuseSection(lines, section) {
             for (const [label, value] of rows) {
                 lines.push(fieldLine(label, value));
             }
+            renderTaskFreshnessDetail(lines, task.indexFreshness);
         }
     });
 }
+function renderFreshnessSummary(lines, section) {
+    // Reports serialized before v0.6.0 Batch 3 lack the summary; render them as having no assessment.
+    const summary = section.indexFreshnessSummary ?? {
+        assessedTaskCount: 0,
+        unassessedTaskCount: section.summary.taskCount,
+        freshTaskCount: 0,
+        staleTaskCount: 0,
+        partiallyStaleTaskCount: 0,
+        unknownTaskCount: 0,
+    };
+    pushSection(lines, "Index Freshness Summary");
+    lines.push(fieldLine("Assessed Tasks", summary.assessedTaskCount));
+    lines.push(fieldLine("Unassessed Tasks", summary.unassessedTaskCount));
+    lines.push(fieldLine("Fresh Tasks", summary.freshTaskCount));
+    lines.push(fieldLine("Stale Tasks", summary.staleTaskCount));
+    lines.push(fieldLine("Partially-Stale Tasks", summary.partiallyStaleTaskCount));
+    lines.push(fieldLine("Unknown Tasks", summary.unknownTaskCount));
+}
+function pushFreshnessBoundedNote(lines, list) {
+    if (list.omittedCount > 0) {
+        lines.push(`Displayed: ${list.displayedCount} of ${list.totalCount}`);
+        lines.push(`Omitted: ${list.omittedCount}`);
+    }
+}
+/** Renders the persisted freshness counts and bounded evidence; hashes are never printed. */
+function renderTaskFreshnessDetail(lines, freshness) {
+    if (!freshness)
+        return;
+    lines.push(fieldLine("Baseline Snapshot Status", freshness.baselineSnapshotStatus));
+    lines.push(fieldLine("Indexed Files", freshness.indexedFileCount));
+    lines.push(fieldLine("Comparable Files", freshness.comparableFileCount));
+    lines.push(fieldLine("Unchanged Files", freshness.unchangedFileCount));
+    lines.push(fieldLine("Modified Files", freshness.changedFileCount));
+    lines.push(fieldLine("Missing Files", freshness.missingFileCount));
+    lines.push(fieldLine("Unresolved Comparisons", freshness.unresolvedFileCount));
+    lines.push("Freshness Changes:");
+    pushFreshnessBoundedNote(lines, freshness.changes);
+    if (freshness.changes.items.length === 0) {
+        lines.push("- none");
+    }
+    for (const change of freshness.changes.items) {
+        lines.push(`- ${sanitizeScalar(change.changeType)} ${sanitizeScalar(change.path)}`);
+    }
+    lines.push("Freshness Unresolved Evidence:");
+    pushFreshnessBoundedNote(lines, freshness.unresolved);
+    if (freshness.unresolved.items.length === 0) {
+        lines.push("- none");
+    }
+    for (const entry of freshness.unresolved.items) {
+        lines.push(`- ${entry.path === null ? "run-level" : sanitizeScalar(entry.path)} [${sanitizeScalar(entry.reasonCode)}] ${sanitizeScalar(entry.message)}`);
+    }
+}
 export function renderPluginExperimentReportText(report) {
     const lines = [];
     pushSection(lines, "Plugin Experiment Report");

package/dist/src/report/experiments/renderWarmIndexReuseHtml.js

@@ -25,6 +25,7 @@ export function renderWarmIndexReuseHtml(section) {
         ["Agent correctness available", `${section.summary.agentCorrectnessAvailableCount} of ${section.summary.agentSideCount}`],
         ["Agent token totals available", `${section.summary.agentTotalTokensAvailableCount} of ${section.summary.agentSideCount}`],
     ])}
+    ${renderFreshnessSummary(section.indexFreshnessSummary ?? legacyFreshnessSummary(section.summary.taskCount))}
     ${section.agentCampaign ? renderCampaignSection(section.agentCampaign) : ""}
     <h3>Cold Start And Warm Reuse</h3>
     ${list(section.costModel)}
@@ -33,6 +34,73 @@ export function renderWarmIndexReuseHtml(section) {
     ${section.projects.length === 0 ? "<p>No warm-index project evidence was recorded.</p>" : section.projects.map((project, index) => renderProject(project, index, section.agent.id)).join("\n")}
   </section>`;
 }
+// Reports serialized before v0.6.0 Batch 3 lack the summary; they are rendered as having no assessment.
+function legacyFreshnessSummary(taskCount) {
+    return {
+        assessedTaskCount: 0,
+        unassessedTaskCount: taskCount,
+        freshTaskCount: 0,
+        staleTaskCount: 0,
+        partiallyStaleTaskCount: 0,
+        unknownTaskCount: 0,
+    };
+}
+function renderFreshnessSummary(summary) {
+    return `<h3>Index Freshness</h3>
+    ${table(["Field", "Value"], [
+        ["Assessed tasks", String(summary.assessedTaskCount)],
+        ["Unassessed tasks", String(summary.unassessedTaskCount)],
+        ["Fresh tasks", String(summary.freshTaskCount)],
+        ["Stale tasks", String(summary.staleTaskCount)],
+        ["Partially-stale tasks", String(summary.partiallyStaleTaskCount)],
+        ["Unknown tasks", String(summary.unknownTaskCount)],
+    ])}`;
+}
+/** Persisted freshness evidence per task; hashes are deliberately absent from this presentation. */
+function renderProjectFreshness(tasks) {
+    const overview = table(["Task", "Freshness", "Baseline", "Indexed", "Comparable", "Unchanged", "Modified", "Missing", "Unresolved"], tasks.map((task) => {
+        const freshness = task.indexFreshness;
+        const label = `${task.taskOrdinal}. ${task.caseId}`;
+        return freshness
+            ? [
+                label,
+                freshness.status,
+                freshness.baselineSnapshotStatus,
+                String(freshness.indexedFileCount),
+                String(freshness.comparableFileCount),
+                String(freshness.unchangedFileCount),
+                String(freshness.changedFileCount),
+                String(freshness.missingFileCount),
+                String(freshness.unresolvedFileCount),
+            ]
+            : [label, "not assessed", "unavailable", "", "", "", "", "", ""];
+    }));
+    const detailRows = tasks.flatMap((task) => {
+        const freshness = task.indexFreshness;
+        if (!freshness)
+            return [];
+        const label = `${task.taskOrdinal}. ${task.caseId}`;
+        return [
+            ...freshness.changes.items.map((change) => [label, change.changeType, change.path, ""]),
+            ...freshness.unresolved.items.map((entry) => [label, "unresolved", entry.path ?? "run-level", `${entry.reasonCode}: ${entry.message}`]),
+        ];
+    });
+    const omitted = tasks.flatMap((task) => {
+        const freshness = task.indexFreshness;
+        if (!freshness)
+            return [];
+        return [
+            ...(freshness.changes.omittedCount > 0 ? [`Task ${task.taskOrdinal}: ${freshness.changes.omittedCount} of ${freshness.changes.totalCount} changes omitted.`] : []),
+            ...(freshness.unresolved.omittedCount > 0
+                ? [`Task ${task.taskOrdinal}: ${freshness.unresolved.omittedCount} of ${freshness.unresolved.totalCount} unresolved entries omitted.`]
+                : []),
+        ];
+    });
+    return `<h4>Index Freshness</h4>
+    ${overview}
+    ${detailRows.length === 0 ? "" : table(["Task", "Evidence type", "Path", "Detail"], detailRows)}
+    ${omitted.length === 0 ? "" : list(omitted)}`;
+}
 function renderCampaignSection(campaign) {
     return `<h3>Real-Agent Campaign</h3>
     ${table(["Field", "Value"], [
@@ -115,6 +183,7 @@ function renderProject(project, index, agentId) {
         formatMetric(task.raw.cumulativeEstimatedContextTokens),
         formatMetric(task.warm.cumulativeEstimatedContextTokens),
     ]))}
+    ${renderProjectFreshness(project.tasks)}
     <p class="muted">Estimated tokens are character-based context-size estimates, not provider token usage.</p>
     <p class="muted">${agentColumnsNote(agentId)}</p>
     ${table([

package/dist/src/report/experiments/warmIndexReuseReportModel.js

@@ -1 +1,4 @@
 export const WARM_INDEX_REUSE_REPORT_SCHEMA_VERSION = "my-dev-kit-lab-warm-index-report-v1";
+/** Report presentation limits; the full persisted lists stay in warm-index-execution.json. */
+export const MAX_REPORT_FRESHNESS_CHANGES = 20;
+export const MAX_REPORT_FRESHNESS_UNRESOLVED = 10;

package/docs/METRICS.md

@@ -535,3 +535,21 @@ Available in the installed v0.5.2 CLI. A `--campaign` run replaces the determini
   Caveat: Claude and Codex token exposure depends on that provider's actual CLI output for the run; token evidence is reported as `unavailable`/`partial` explicitly rather than assumed. No fixed claim that either provider always or never exposes a token total is made — `tokenEvidenceStatus` is the authoritative, per-run signal.
 
 No token-savings percentage, break-even task, winner, ranking, or provider billing metric is calculated for a campaign run, matching the fake-agent path above.
+
+### Index freshness evidence (v0.6.0)
+
+Status: released in v0.6.0 and present in the current package. The freshness values below are report evidence, not metric formulas: no `ExperimentMetric` ID, plot, or gallery item is added for them.
+
+Before each task's warm retrieval, the warm-index run compares the files the index snapshot proves were indexed against their current state and persists one assessment per task (`indexFreshness` in `warm-index-execution.json`). The report only presents that persisted assessment; it never re-reads the filesystem, re-hashes files, or invokes my-dev-kit.
+
+- **Snapshot-scoped comparison.** Only files listed by the index snapshot are compared. Freshness does not establish that the whole repository is unchanged.
+- **SHA-256 is the authority.** A file is modified when its current SHA-256 differs from the snapshot's, or missing when it no longer exists. A changed modified time with identical content is not a change; timestamps are diagnostic metadata only.
+- **New and non-indexed files.** A file that was not represented in the snapshot is outside the comparison and is not, by itself, evidence that the index is stale. Lab does not guess which files my-dev-kit would index.
+- **Four statuses.**
+  - `fresh`: the snapshot was complete, every represented file was compared, and every content identity still matches.
+  - `stale`: a complete comparison confirmed at least one represented file is modified or missing.
+  - `partially-stale`: at least one represented file is confirmed changed, but comparison evidence is incomplete (a partial snapshot or unresolved comparisons).
+  - `unknown`: no confirmed change established staleness, but evidence is insufficient to prove freshness (an unavailable or partial snapshot, or an unresolved comparison). It is never treated as `fresh`.
+- **`unknown` versus not assessed.** `unknown` means an assessment ran and could not prove freshness. A task with no assessment (for example a report from before v0.6.0) is shown as `not assessed` and counted as unassessed, never as `unknown`.
+- **Report-level counts.** `report.warmIndexReuse.indexFreshnessSummary` holds direct presentation counts of assessed, unassessed, `fresh`, `stale`, `partially-stale`, and `unknown` tasks (assessed equals the sum of the four statuses). They are counts, not `ExperimentMetric` formulas: no percentage, score, or ranking is calculated. Each task's `indexFreshness` lists at most 20 changed files and 10 unresolved comparisons, with the persisted totals and the omitted count; hashes stay in `warm-index-execution.json`.
+- **Observational only.** Freshness does not trigger reindexing, suppress or alter warm retrieval, or change execution status, correctness, provider or agent outcome status, or token evidence. v0.6.0 makes no reindex recommendation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dailephd/my-dev-kit-lab",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "type": "module",
   "description": "Evidence, benchmark, and evaluation companion for my-dev-kit.",
   "bin": {