loopforge 3.7.1 → 3.8.2

package/dist/evidence-provider.js

@@ -1,19 +1,20 @@
-/** EvidenceProvider — Pluggable evidence capture interface (v1.18).
+/** EvidenceProvider — Pluggable machine-observation capture (v1.18 / v3.8).
  *
- * This module defines an abstract EvidenceProvider interface so
- * additional evidence sources (test runners, linters, bundle analysis)
- * can be added without touching the verification pipeline.
+ * v3.8: providers produce `MachineObservation`s, not ad-hoc snapshots. A
+ * configured provider ALWAYS yields an observation: unavailability, timeouts,
+ * errors and aborts are recorded as observations with the matching status and
+ * are never silently filtered out of the round's factual record. Only
+ * observations can create a `verified` fact — agent self-reports never can.
  *
- * Built-in provider: GitEvidenceProvider — git file state capture with
- * parallel async execution (v2.0.1) and a synchronous fallback.
+ * Built-in: GitEvidenceProvider — git file state capture with parallel async
+ * execution (v2.0.1), plus explicitly configured shell-free command providers.
  */
 import { createHash } from "node:crypto";
 import { readFileSync, realpathSync, statSync } from "node:fs";
 import { spawn, execFile, } from "node:child_process";
 import { isAbsolute, relative, resolve, sep } from "node:path";
-import { isRecord } from "./token-utils.js";
 import { containInWorkspace } from "./workspace.js";
-import { getPolicy } from "./policy.js";
+import { commandConfigHash, deriveConfiguredCapability, getPolicy, resolveStateDirectory } from "./policy.js";
 import { logEvent } from "./observability.js";
 import { policyMetrics } from "./policy-metrics.js";
 const providerFactories = new Map();
@@ -28,37 +29,172 @@ export function unregisterEvidenceProvider(name) {
         return false;
     return providerFactories.delete(name);
 }
-// ── EvidenceCollector ──────────────────────────────────────────────────────
-/** L8: true when a command snapshot reports that the command hit its own
- *  deadline (the CommandEvidenceProvider kills the child and records
- *  status "timeout") rather than completing. */
-function isTimedOutSnapshot(snapshot) {
-    if (!isRecord(snapshot.data))
+/** v3.8: Whether a provider factory is registered for this name. Readiness
+ *  of the RUNTIME (PATH resolution, executables) is a `doctor` concern and is
+ *  deliberately not part of the hashed capability. */
+export function isProviderRegistered(name) {
+    return providerFactories.has(name);
+}
+// ── The single machine-backed predicate ────────────────────────────────────
+/** v3.8: The ONE machine-backed predicate. A command observation proves a
+ *  claim only when it is an after-phase command that PASSED and whose
+ *  entrypoint was not modified in the same round. Before-phase observations
+ *  are the baseline and never evidence. When no git delta is available the
+ *  entrypoint arm fails open (matching the historical behaviour).
+ *
+ *  v3.8 replaced two divergent implementations (the gate excluded tampered
+ *  commands, evidence-claims did not) with this single function. */
+export function isPassedAfterObservation(observation, gitChangedFiles) {
+    if (observation.kind !== "command")
+        return false;
+    if (observation.phase !== "after")
+        return false;
+    if (observation.status !== "passed")
         return false;
-    return snapshot.data.kind === "command" && snapshot.data.status === "timeout";
+    const entrypoints = observation.data.entrypointFiles ?? [];
+    if (!gitChangedFiles || gitChangedFiles.size === 0)
+        return true;
+    return !entrypoints.some((file) => gitChangedFiles.has(file));
+}
+/** v3.8: The changed-file set of a round's git observation, or null when no
+ *  git observation exists (entrypoint checks then fail open). */
+export function gitChangedFiles(observations) {
+    const git = observations.find((observation) => observation.providerId === "git");
+    return git ? new Set(git.files) : null;
+}
+/** v3.8: Live capability derived from observations. Rendered only — never
+ *  hashed, never persisted independently (it is a pure function of the
+ *  observations it is given). */
+export function deriveObservedCapability(observations, configured) {
+    const latest = new Map();
+    const latestCommand = new Map();
+    for (const observation of observations) {
+        latest.set(observation.providerId, observation.status);
+        if (observation.kind === "command") {
+            latestCommand.set(observation.data.commandId, {
+                status: observation.status,
+                configHash: observation.data.configHash,
+            });
+        }
+    }
+    return {
+        providers: configured.providers.map((provider) => ({
+            providerId: provider.providerId,
+            status: latest.get(provider.providerId) ?? "unavailable",
+        })),
+        commands: configured.commands.map((command) => {
+            const seen = latestCommand.get(command.commandId);
+            return {
+                commandId: command.commandId,
+                status: seen?.status ?? "unavailable",
+                configHash: seen?.configHash ?? command.configHash,
+            };
+        }),
+    };
+}
+/** v3.8: Human-readable capability warnings for start/resume/status. A loop
+ *  with no machine verification can still run — its success claims are simply
+ *  recorded as `insufficient` instead of `verified`. */
+export function capabilityWarnings(configured, observed) {
+    const warnings = [];
+    if (!configured.observationConfigured) {
+        warnings.push("No evidence provider is configured — the runtime can observe nothing " +
+            "this loop; success claims will be recorded as insufficient.");
+    }
+    if (!configured.contractVerificationAvailable) {
+        warnings.push("No enabled verification command is configured — Round Contract items " +
+            "cannot be machine-verified; contract closure will require an explicit " +
+            "blocked outcome.");
+    }
+    if (observed) {
+        const dead = observed.providers.filter((provider) => provider.status === "unavailable" || provider.status === "error");
+        if (dead.length > 0) {
+            warnings.push(`Evidence provider(s) unavailable: ${dead.map((p) => p.providerId).join(", ")}.`);
+        }
+    }
+    return warnings;
 }
-/** Collects evidence from all configured providers (always async — the
- *  synchronous collect() was removed in v3.7).
+/** v3.8: The ONE capability derivation. Everything that speaks about
+ *  capability — `RoundDriver.prepare()`, MCP start/resume/next/status, the
+ *  capability warnings — reads this, so the surfaces cannot drift into
+ *  different stories about what the runtime can observe.
  *
- * Usage:
- *   const collector = new EvidenceCollector([new GitEvidenceProvider()]);
- *   const snapshots = await collector.collectAsync({ phase: "before" });
- *   // snapshots = [{ provider: "git", files: [...], data: {...} }]
- */
+ *  `available` is provider-REGISTRY state (code, not policy): it is rendered
+ *  and reported by `doctor`, never hashed. The hashed half stays
+ *  `deriveConfiguredCapability(policy)` inside the canonical state. */
+export function deriveEvidenceCapability(policy, observations = []) {
+    const configured = deriveConfiguredCapability(policy);
+    const observed = deriveObservedCapability(observations, configured);
+    const statusByProvider = new Map(observed.providers.map((provider) => [provider.providerId, provider.status]));
+    return {
+        schemaVersion: 1,
+        providers: configured.providers.map((provider) => ({
+            providerId: provider.providerId,
+            available: isProviderRegistered(provider.providerId),
+            status: statusByProvider.get(provider.providerId) ?? "unavailable",
+        })),
+        commands: configured.commands.map((command) => ({
+            commandId: command.commandId,
+            enabled: command.enabled,
+            phase: command.phase,
+            configHash: command.configHash,
+            ready: command.enabled && (command.phase === "after" || command.phase === "both"),
+        })),
+        contractVerificationAvailable: configured.contractVerificationAvailable,
+        warnings: capabilityWarnings(configured, observed),
+    };
+}
+// ── EvidenceCollector ──────────────────────────────────────────────────────
+/** v3.8: The stand-in for a name in `policy.evidence.providers` that no
+ *  registered factory answers. Configuring a provider is a factual claim that
+ *  it observes something; when the runtime has no such provider the claim must
+ *  still leave a record, so this one captures `unavailable` instead of the
+ *  name vanishing from the round. Registration is code state (a `doctor`
+ *  concern), so the observation is the only place the gap can legitimately
+ *  appear in the Vault. */
+function unregisteredProvider(name) {
+    return {
+        name,
+        kind: "custom",
+        capture(context) {
+            return syntheticObservation(name, "custom", context?.phase ?? "after", Date.now(), "unavailable", "provider is not registered in this runtime (see `loopforge doctor`)");
+        },
+    };
+}
+/** v3.8: Build the observation a failed capture resolves to. The status names
+ *  the machine fact; `detail` explains it for the audit trail. */
+function syntheticObservation(providerId, kind, phase, startedAt, status, detail) {
+    return {
+        schemaVersion: 1,
+        providerId,
+        kind,
+        phase,
+        startedAt,
+        finishedAt: Date.now(),
+        status,
+        files: [],
+        data: { detail },
+    };
+}
+/** Collects observations from all configured providers (always async).
+ *
+ * v3.8: every configured provider produces exactly one observation per
+ * collection. A provider that returns null, throws, times out, or is aborted
+ * yields an observation with `unavailable` / `error` / `timeout` / `aborted`
+ * — the round's factual record keeps the gap instead of hiding it. */
 export class EvidenceCollector {
     providers;
     constructor(providers) {
         this.providers = providers;
     }
-    /** Build the collector described by loop_policy.json. Unknown provider
-     *  names are ignored so newer configs remain backward compatible. */
+    /** Build the collector described by loop_policy.json. Every configured name
+     *  yields exactly one provider, in configuration order: a name with no
+     *  registered factory gets `unregisteredProvider`, which records
+     *  `unavailable` rather than letting a configured provider vanish without a
+     *  trace. */
     static fromProviderNames(providerNames) {
-        const providers = [];
-        for (const name of providerNames) {
-            const factory = providerFactories.get(name);
-            if (factory)
-                providers.push(factory());
-        }
+        const providers = providerNames
+            .map((name) => providerFactories.get(name)?.() ?? unregisteredProvider(name));
         return new EvidenceCollector(providers);
     }
     /** Build built-ins and explicitly configured command providers. */
@@ -75,13 +211,10 @@ export class EvidenceCollector {
         }
         return new EvidenceCollector(providers);
     }
-    // v3.7: the synchronous collect() was removed with the sync lifecycle
-    // (prepareSync / captureGitFileState) — evidence collection is always
-    // async (collectAsync). It never worked for async providers anyway: they
-    // were silently skipped and recorded as failures.
     /** Capture all providers concurrently with per-provider timeout isolation. */
     async collectAsync(options = {}) {
         const timeoutMs = options.timeoutMs ?? getPolicy().evidence.timeout_ms;
+        const phase = options.phase ?? "after";
         const captures = this.providers.map(async (provider) => {
             const startedAt = Date.now();
             const controller = new AbortController();
@@ -92,46 +225,43 @@ export class EvidenceCollector {
                     signal: controller.signal,
                     timeoutMs,
                     loopId: options.loopId,
-                    phase: options.phase ?? "after",
+                    phase,
                 }));
-                const snapshot = timeoutMs > 0
+                const observation = timeoutMs > 0
                     ? await Promise.race([
                         capture,
-                        new Promise((resolve) => {
+                        new Promise((resolveRace) => {
                             timer = setTimeout(() => {
                                 timedOut = true;
                                 controller.abort(new Error(`Evidence provider timed out after ${timeoutMs}ms`));
-                                resolve(null);
+                                resolveRace(null);
                             }, timeoutMs);
                         }),
                     ])
                     : await capture;
-                const outcome = timedOut
-                    ? "timeout"
-                    : snapshot
-                        // L8: a command that hit its OWN deadline reports status
-                        // "timeout" — count it as a timeout, not as available. Only the
-                        // outer collector race previously produced "timeout", so the
-                        // metric systematically undercounted command deadline hits.
-                        ? isTimedOutSnapshot(snapshot) ? "timeout" : "available"
-                        : "unavailable";
-                policyMetrics.recordEvidence(provider.name, outcome, Date.now() - startedAt, options.loopId);
                 if (timedOut) {
+                    policyMetrics.recordEvidence(provider.name, "timeout", Date.now() - startedAt, options.loopId);
                     logEvent("evidence_provider_timeout", { provider: provider.name, timeoutMs });
+                    return syntheticObservation(provider.name, provider.kind, phase, startedAt, "timeout", `provider exceeded ${timeoutMs}ms`);
+                }
+                if (!observation) {
+                    policyMetrics.recordEvidence(provider.name, "unavailable", Date.now() - startedAt, options.loopId);
+                    return syntheticObservation(provider.name, provider.kind, phase, startedAt, "unavailable", "provider reported no observation");
                 }
-                return timedOut ? null : snapshot;
+                policyMetrics.recordEvidence(provider.name, observation.status === "timeout" ? "timeout" : "available", Date.now() - startedAt, options.loopId);
+                return observation;
             }
             catch (error) {
                 policyMetrics.recordEvidence(provider.name, "failure", Date.now() - startedAt, options.loopId);
                 logEvent("evidence_provider_error", { provider: provider.name, error: String(error) });
-                return null;
+                return syntheticObservation(provider.name, provider.kind, phase, startedAt, "error", String(error));
             }
             finally {
                 if (timer)
                     clearTimeout(timer);
             }
         });
-        return (await Promise.all(captures)).filter((snapshot) => snapshot !== null);
+        return await Promise.all(captures);
     }
 }
 function commandCwd(configured) {
@@ -152,14 +282,40 @@ function commandCwd(configured) {
  *  paths are skipped. Returns forward-slash paths (git convention) so the
  *  gate can intersect them with the round's git diff. Empty result = the
  *  command's entrypoint cannot be observed (external command) — fail open. */
-function resolveEntrypointFiles(executable, args, cwd) {
+/** Package-manager executables, whose own configuration IS the command's
+ *  harness: `npm test` runs whatever `scripts.test` names, so an edit there
+ *  changes what the machine will execute. Any other command's harness is what
+ *  its own command line names. */
+const PACKAGE_MANAGER_EXECUTABLES = new Set([
+    "npm", "npm.cmd", "npm.exe",
+    "npx", "npx.cmd", "npx.exe",
+    "pnpm", "pnpm.cmd", "yarn", "yarn.cmd", "yarnpkg",
+    "bun", "bunx",
+]);
+function isPackageManagerCommand(executable) {
+    const base = executable.split(/[\\/]/).pop() ?? executable;
+    return PACKAGE_MANAGER_EXECUTABLES.has(base.trim().toLowerCase());
+}
+/** The workspace files a command's execution depends on, resolved
+ *  statically: the script it names on its own command line, plus package.json
+ *  when a package manager is what runs it. Exported for the pure-function
+ *  test — spawning a real package manager is not portable (a bare `npm`
+ *  cannot be spawned without a shell, and the runtime uses `shell: false`). */
+export function resolveEntrypointFiles(executable, args, cwd) {
     // v3.3.1: entrypoint containment uses the shared workspace check.
     const workspace = process.cwd();
     const candidates = [...args];
     if (executable.includes("/") || executable.includes("\\")) {
         candidates.unshift(executable);
     }
-    candidates.push("package.json");
+    // v3.8.1: `package.json` is a candidate only for a package-manager
+    // invocation, which is the only case where it defines what runs. Adding it
+    // unconditionally made EVERY command's entrypoint set include it, so a round
+    // that touched package.json — for any reason at all, with any command — was
+    // reported as "the verification entrypoint changed" and rejected, however
+    // unrelated the file was to what actually executed.
+    if (isPackageManagerCommand(executable))
+        candidates.push("package.json");
     const found = [];
     for (const candidate of candidates) {
         try {
@@ -180,7 +336,9 @@ function resolveEntrypointFiles(executable, args, cwd) {
 /** Explicit, shell-free verification command. Disabled unless configured. */
 export class CommandEvidenceProvider {
     name;
+    kind = "command";
     config;
+    configHash;
     constructor(config) {
         const name = typeof config.name === "string" && config.name.trim()
             ? config.name.trim()
@@ -207,6 +365,7 @@ export class CommandEvidenceProvider {
                 : 20_000,
             success_exit_codes: successExitCodes,
         };
+        this.configHash = commandConfigHash(this.config);
         this.name = `command:${name}`;
     }
     capture(context) {
@@ -215,25 +374,24 @@ export class CommandEvidenceProvider {
             return Promise.resolve(null);
         }
         const startedAt = Date.now();
-        // L8: honor the CONFIGURED output cap. The old Math.min(20_000, ...)
-        // silently clamped every larger configured value — a policy that says
-        // max_output_chars: 50000 quietly retained only 20k. (The constructor
-        // already defaults the cap to 20_000 when unset.)
         const cap = Math.max(0, this.config.max_output_chars);
         const timeoutMs = Math.max(1, Math.min(this.config.timeout_ms, context?.timeoutMs || this.config.timeout_ms));
         let cwd;
         if (!this.config.executable) {
-            return Promise.resolve(this.snapshot(phase, "missing", null, null, "", "Command executable is empty", false, 0, []));
+            return Promise.resolve(this.observation(phase, "error", null, null, "", "", false, 0, [], "command executable is empty"));
         }
         try {
             cwd = commandCwd(this.config.cwd);
         }
         catch (error) {
-            return Promise.resolve(this.snapshot(phase, "invalid_cwd", null, null, "", String(error), false, Date.now() - startedAt, []));
+            return Promise.resolve(this.observation(phase, "error", null, null, "", "", false, Date.now() - startedAt, [], String(error)));
         }
         // v3.3: Workspace entrypoint files for tamper detection at the gate.
         const entrypointFiles = resolveEntrypointFiles(this.config.executable, this.config.args, cwd);
         return new Promise((resolveCapture) => {
+            // v3.8: the FULL streams are hashed; the retained excerpt is capped.
+            const stdoutHash = createHash("sha256");
+            const stderrHash = createHash("sha256");
             let stdout = "";
             let stderr = "";
             let truncated = false;
@@ -241,9 +399,10 @@ export class CommandEvidenceProvider {
             let settled = false;
             const append = (current, chunk) => {
                 const text = String(chunk);
+                if (text.length === 0)
+                    return current;
                 if (retained >= cap) {
-                    if (text.length > 0)
-                        truncated = true;
+                    truncated = true;
                     return current;
                 }
                 const remaining = cap - retained;
@@ -260,24 +419,31 @@ export class CommandEvidenceProvider {
                 stdio: ["ignore", "pipe", "pipe"],
             });
             let timer;
-            const finish = (status, exitCode, signal) => {
+            const finish = (status, exitCode, signal, failureDetail) => {
                 if (settled)
                     return;
                 settled = true;
                 if (timer)
                     clearTimeout(timer);
                 context?.signal.removeEventListener("abort", abort);
-                resolveCapture(this.snapshot(phase, status, exitCode, signal, stdout, stderr, truncated, Date.now() - startedAt, entrypointFiles));
+                resolveCapture(this.observation(phase, status, exitCode, signal, stdout, stderr, truncated, Date.now() - startedAt, entrypointFiles, failureDetail, stdoutHash.digest("hex"), stderrHash.digest("hex")));
             };
             const abort = () => {
                 child.kill();
-                finish("aborted", null, null);
+                finish("aborted", null, null, "aborted by the collector deadline");
             };
-            child.stdout.on("data", (chunk) => { stdout = append(stdout, chunk); });
-            child.stderr.on("data", (chunk) => { stderr = append(stderr, chunk); });
+            child.stdout.on("data", (chunk) => {
+                stdoutHash.update(String(chunk));
+                stdout = append(stdout, chunk);
+            });
+            child.stderr.on("data", (chunk) => {
+                stderrHash.update(String(chunk));
+                stderr = append(stderr, chunk);
+            });
             child.once("error", (error) => {
+                stderrHash.update(error.message);
                 stderr = append(stderr, error.message);
-                finish(error.code === "ENOENT" ? "missing" : "failed", null, null);
+                finish(error.code === "ENOENT" ? "unavailable" : "error", null, null, error.code ?? error.message);
             });
             child.once("close", (code, signal) => {
                 const passed = code !== null && this.config.success_exit_codes.includes(code);
@@ -285,7 +451,7 @@ export class CommandEvidenceProvider {
             });
             timer = setTimeout(() => {
                 child.kill();
-                finish("timeout", null, null);
+                finish("timeout", null, null, `command exceeded ${timeoutMs}ms`);
             }, timeoutMs);
             timer.unref?.();
             if (context?.signal.aborted)
@@ -294,22 +460,31 @@ export class CommandEvidenceProvider {
                 context?.signal.addEventListener("abort", abort, { once: true });
         });
     }
-    snapshot(phase, status, exitCode, signal, stdout, stderr, truncated, durationMs, entrypointFiles) {
+    observation(phase, status, exitCode, signal, stdout, stderr, truncated, durationMs, entrypointFiles, failureDetail, stdoutSha256, stderrSha256) {
+        const finishedAt = Date.now();
         return {
-            provider: this.name,
-            timestamp: Date.now(),
+            schemaVersion: 1,
+            providerId: this.name,
+            kind: "command",
+            phase,
+            startedAt: finishedAt - durationMs,
+            finishedAt,
+            status,
             files: [],
             data: {
-                kind: "command",
-                commandName: this.config.name,
+                commandId: this.config.name,
+                argv: [this.config.executable, ...this.config.args],
+                cwd: this.config.cwd ?? ".",
+                configHash: this.configHash,
                 required: this.config.required,
-                phase,
-                status,
                 exitCode,
                 signal,
                 durationMs,
-                stdout,
-                stderr,
+                ...(failureDetail ? { failureDetail } : {}),
+                stdoutSha256: stdoutSha256 ?? createHash("sha256").update(stdout).digest("hex"),
+                stderrSha256: stderrSha256 ?? createHash("sha256").update(stderr).digest("hex"),
+                stdoutExcerpt: stdout,
+                stderrExcerpt: stderr,
                 truncated,
                 entrypointFiles,
             },
@@ -334,7 +509,7 @@ export async function captureGitFileStateAsync(signal, timeoutMs,
 cwd = process.cwd()) {
     const timeout = timeoutMs ?? 15000;
     const runGit = (args) => {
-        return new Promise((resolve, reject) => {
+        return new Promise((resolveGit, reject) => {
             // M1: core.quotePath=false — git otherwise octal-escapes every path
             // with bytes >= 0x80 (Chinese and other non-ASCII filenames become
             // "\346\226\207..."). Escaped names can't be stat/hash'd, so content
@@ -352,7 +527,7 @@ cwd = process.cwd()) {
             });
             child.on("close", (code) => {
                 code === 0
-                    ? resolve(stdout)
+                    ? resolveGit(stdout)
                     : reject(new Error(`git ${args[0]} exited ${code}`));
             });
             child.on("error", reject);
@@ -385,12 +560,37 @@ cwd = process.cwd()) {
     }
 }
 // ── Built-in: GitEvidenceProvider ──────────────────────────────────────────
-/** v3.7: async capture only — the synchronous captureGitFileState() fallback
- *  was removed together with the sync lifecycle (prepareSync). */
+/** The runtime's resolved state directory, or null when it cannot be observed
+ *  (configured outside the workspace, or an unresolvable path). */
+function stateDirectory(workspace) {
+    try {
+        return resolveStateDirectory(workspace, getPolicy().backend.root_dir);
+    }
+    catch {
+        return null;
+    }
+}
+/** True when a workspace-relative or absolute file path is the state directory
+ *  or lives inside it. */
+function isInsideDirectory(file, workspace, dir) {
+    const absolute = isAbsolute(file) ? file : resolve(workspace, file);
+    const prefix = dir.endsWith(sep) ? dir : `${dir}${sep}`;
+    return absolute === dir || absolute.startsWith(prefix);
+}
 export class GitEvidenceProvider {
     name = "git";
+    kind = "git";
     capture(context) {
         const workspace = context?.cwd ?? process.cwd();
+        const startedAt = Date.now();
+        // v3.8.1: the runtime's OWN state directory is not the agent's work. The
+        // vault lives inside the workspace by default, so every round's
+        // bookkeeping writes would otherwise read as machine-observed motion —
+        // the very signal the stall evaluator and the restore checks consume. The
+        // exclusion lives here, at the fact, and not in the workspace's
+        // .gitignore (which the runtime does not own and a user may not have).
+        const stateDir = stateDirectory(workspace);
+        const isRuntimeState = (file) => stateDir !== null && isInsideDirectory(file, workspace, stateDir);
         return captureGitFileStateAsync(context?.signal, context?.timeoutMs, workspace).then((state) => {
             if (!state)
                 return null;
@@ -398,7 +598,7 @@ export class GitEvidenceProvider {
                     ...state.tracked,
                     ...state.staged,
                     ...state.untracked,
-                ])].sort();
+                ])].filter((file) => !isRuntimeState(file)).sort();
             // v3.7.1: paths from git are workspace-relative; the capture runs with
             // the workspace as cwd, so relative stat/read resolve there naturally.
             // An injectable cwd (tests) must resolve explicitly.
@@ -411,21 +611,25 @@ export class GitEvidenceProvider {
                     fingerprints[file] = `${stat.mode}:${hash}`;
                 }
                 catch {
-                    // Deleted files are evidence too.  A stable sentinel lets the diff
+                    // Deleted files are evidence too. A stable sentinel lets the diff
                     // distinguish deleted/restored transitions across a round.
                     fingerprints[file] = "missing";
                 }
             }
             return {
-                provider: "git",
-                timestamp: Date.now(),
+                schemaVersion: 1,
+                providerId: "git",
+                kind: "git",
+                phase: context?.phase ?? "after",
+                startedAt,
+                finishedAt: Date.now(),
+                status: "observed",
                 files,
                 data: {
-                    tracked: state.tracked,
-                    staged: state.staged,
-                    untracked: state.untracked,
+                    tracked: state.tracked.filter((file) => !isRuntimeState(file)),
+                    staged: state.staged.filter((file) => !isRuntimeState(file)),
+                    untracked: state.untracked.filter((file) => !isRuntimeState(file)),
                     fingerprints,
-                    // v2.13: HEAD commit hash for backtrack workspace restore
                     head: state.head,
                 },
             };
@@ -434,31 +638,47 @@ export class GitEvidenceProvider {
 }
 registerEvidenceProvider("git", () => new GitEvidenceProvider());
 // ── Utility ────────────────────────────────────────────────────────────────
-/** Extract merged file list from evidence snapshots for backward compat
- *  with runtimeFilesChanged (string[] | null).
+/** Extract merged file list from observations for backward compat with
+ *  runtimeFilesChanged (string[] | null).
  *
- *  Looks for the "git" provider first; falls back to merging all
- *  providers' files arrays (deduplicated). */
-export function extractFilesFromSnapshots(snapshots) {
-    if (snapshots.length === 0)
+ *  Looks for the "git" provider first; falls back to merging all providers'
+ *  files arrays (deduplicated). */
+export function extractFilesFromSnapshots(observations) {
+    if (observations.length === 0)
         return null;
-    // Prefer the git provider for backward compat
-    const gitSnapshot = snapshots.find((s) => s.provider === "git");
-    if (gitSnapshot)
-        return [...gitSnapshot.files].sort();
-    // Fallback: merge all providers
+    const gitObservation = observations.find((item) => item.providerId === "git");
+    if (gitObservation)
+        return [...gitObservation.files].sort();
     const allFiles = new Set();
-    for (const s of snapshots) {
-        for (const f of s.files)
-            allFiles.add(f);
+    for (const item of observations) {
+        for (const file of item.files)
+            allFiles.add(file);
     }
     return [...allFiles].sort();
 }
-/** Compute a diff between two evidence collections (before → after).
- *  Returns files that appeared in the after-snapshot but not the before.
- *  Used by runtime.ts to compute runtimeFilesChanged. */
-function snapshotFingerprints(snapshot) {
-    const value = snapshot.data.fingerprints;
+/** v3.8: The round delta of two observation collections (before → after):
+ *  files that appeared, disappeared, or changed content. The full payload of
+ *  each after-observation is preserved; only `files` is narrowed. This is the
+ *  single derivation the transaction persists and every reader consumes. */
+export function diffSnapshotCollections(before, after) {
+    return after.map((observation) => {
+        const baseline = before.find((item) => item.providerId === observation.providerId);
+        if (!baseline)
+            return observation;
+        return {
+            ...observation,
+            files: diffProviderSnapshot(baseline, observation),
+        };
+    });
+}
+/** Compute a diff between two observation collections (before → after). */
+export function diffSnapshots(before, after) {
+    return extractFilesFromSnapshots(diffSnapshotCollections(before, after));
+}
+function snapshotFingerprints(observation) {
+    if (observation.kind !== "git")
+        return null;
+    const value = observation.data.fingerprints;
     if (!value || typeof value !== "object" || Array.isArray(value))
         return null;
     const fingerprints = {};
@@ -482,80 +702,4 @@ function diffProviderSnapshot(before, after) {
         return beforeFingerprints[file] !== afterFingerprints[file];
     }).sort();
 }
-/** Return provider snapshots narrowed to evidence produced during this round.
- *  The full provider payload remains available in data, while files contains
- *  only added/removed/content-changed paths. */
-export function diffSnapshotCollections(before, after) {
-    return after.map((snapshot) => {
-        const baseline = before.find((item) => item.provider === snapshot.provider);
-        if (!baseline)
-            return snapshot;
-        return {
-            ...snapshot,
-            files: diffProviderSnapshot(baseline, snapshot),
-        };
-    });
-}
-export function diffSnapshots(before, after) {
-    return extractFilesFromSnapshots(diffSnapshotCollections(before, after));
-}
-// ═══════════════════════════════════════════════════════════════════════════
-// v3.3.1: Backtrack auto-restore (engine.backtrack_auto_restore)
-// ═══════════════════════════════════════════════════════════════════════════
-/** v3.3.1: Implement the v2.13 policy switch `engine.backtrack_auto_restore` —
- *  automatically restore the workspace after a backtrack:
- *  1. `git stash push -u` — every uncommitted change (tracked + untracked)
- *     is preserved in a stash, never destroyed (an untracked file the agent
- *     created in the failed rounds is not silently deleted).
- *  2. `git reset --hard <restoreHead>` — when the failed rounds created
- *     commits, discard them back to the clean round's commit (the v2.12
- *     restore-point HEAD).
- *
- *  Runs only inside the workspace (cwd, shell: false, 30s timeout), and the
- *  caller gates it behind the policy flag — DANGEROUS by design, off by
- *  default. Failures are reported, never thrown: the verification gate still
- *  checks workspace cleanliness afterwards, and the backtrack prompt already
- *  instructs manual restore as the fallback. An empty workspace ("No local
- *  changes") is not a failure. */
-export async function runBacktrackAutoRestore(gitHead, round,
-/** v3.3.1: workspace root; injectable so tests can run against a temp
- *  repo. Defaults to the process cwd, matching the evidence providers. */
-cwd = process.cwd()) {
-    const run = (args) => new Promise((resolvePromise) => {
-        execFile("git", args, {
-            cwd,
-            shell: false,
-            timeout: 30_000,
-        }, (error, stdout, stderr) => {
-            if (error) {
-                resolvePromise({ ok: false, out: String(stderr || error.message) });
-                return;
-            }
-            resolvePromise({ ok: true, out: String(stdout) });
-        });
-    });
-    const steps = [];
-    const stash = await run(["stash", "push", "-u", "-m", `loopforge-backtrack-round-${round}`]);
-    const workspaceWasClean = stash.out.includes("No local changes");
-    steps.push(`stash: ${workspaceWasClean ? "clean (nothing to stash)" : stash.ok ? "ok" : `failed — ${stash.out.trim()}`}`);
-    // L6 (v3.7.x): a failed stash must abort the restore. The contract above
-    // says every uncommitted change is preserved in a stash, NEVER destroyed —
-    // `reset --hard` after a stash failure would destroy exactly the changes
-    // the stash was meant to save (failed-round work AND any unrelated user
-    // edits). The verification gate then reports the workspace as unrestored
-    // and the backtrack prompt's manual-restore instructions take over.
-    if (!workspaceWasClean && !stash.ok) {
-        return {
-            ok: false,
-            detail: steps.join("; ") +
-                "; reset --hard SKIPPED — uncommitted changes would be destroyed",
-        };
-    }
-    if (gitHead) {
-        const reset = await run(["reset", "--hard", gitHead]);
-        steps.push(`reset --hard ${gitHead.slice(0, 12)}: ${reset.ok ? "ok" : `failed — ${reset.out.trim()}`}`);
-        return { ok: reset.ok, detail: steps.join("; ") };
-    }
-    return { ok: workspaceWasClean || stash.ok, detail: steps.join("; ") };
-}
 //# sourceMappingURL=evidence-provider.js.map