@cad0p/pi-steering 0.1.0

package/src/testing/index.test.ts

@@ -0,0 +1,1696 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+
+/**
+ * Tests for the Phase 5a testing primitives (`./index.ts`).
+ *
+ * Coverage axis:
+ *   - `loadHarness`         — evaluator + dispatcher built from a
+ *                              minimal config; includeDefaults on/off;
+ *                              plugin merging; config.disabledRules; custom
+ *                              host override.
+ *   - `mockContext`         — default shape; per-option overrides; exec
+ *                              stubbing + unstubbed reject; findEntries
+ *                              filter + timestamp parsing; appendEntry
+ *                              capture visible via getAppendedEntries.
+ *   - `mockObserverContext` — default shape; exec stub pass-through;
+ *                              entries/appendEntry capture.
+ *   - `getAppendedEntries`  — empty on fresh ctx, populated after
+ *                              appendEntry, empty on non-mock ctx.
+ *
+ * These are UNIT tests against the primitives — they don't exercise
+ * the underlying evaluator / observer dispatcher semantics in depth
+ * (those are covered in the *.test.ts suites). Here we verify the
+ * wrappers assemble the right plumbing.
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { EvaluatorHost } from "../evaluator.ts";
+import type {
+  Observer,
+  ObserverContext,
+  Plugin,
+  PredicateContext,
+  PredicateHandler,
+  Rule,
+} from "../schema.ts";
+import {
+  createRecordingHost,
+  expectAllows,
+  expectBlocks,
+  expectRuleFires,
+  formatMatrix,
+  getAppendedEntries,
+  loadHarness,
+  mockContext,
+  mockExtensionContext,
+  mockObserverContext,
+  priorEntry,
+  runMatrix,
+  testObserver,
+  testPredicate,
+} from "./index.ts";
+
+// ---------------------------------------------------------------------------
+// Shared stubs
+// ---------------------------------------------------------------------------
+
+/**
+ * Minimal `ExtensionContext` stub for harness evaluate/dispatch
+ * invocations. Only `cwd` + `sessionManager.getEntries` are read by
+ * the evaluator pipeline; everything else we leave unset.
+ */
+function makeExtCtx(cwd = "/repo"): ExtensionContext {
+  return {
+    cwd,
+    sessionManager: {
+      getEntries: () => [],
+    } as unknown as ExtensionContext["sessionManager"],
+  } as ExtensionContext;
+}
+
+// ---------------------------------------------------------------------------
+// loadHarness
+// ---------------------------------------------------------------------------
+
+describe("loadHarness", () => {
+  it("builds evaluator + dispatcher from a minimal (empty) config", async () => {
+    const h = loadHarness({ config: {} });
+    // evaluator fires: allow (no rules → undefined).
+    const res = await h.evaluate(
+      {
+        type: "tool_call",
+        toolCallId: "t",
+        toolName: "bash",
+        input: { command: "echo hi" },
+      },
+      makeExtCtx(),
+      0,
+    );
+    assert.equal(res, undefined);
+    // dispatcher fires: no observers, no throw.
+    await h.dispatch(
+      {
+        type: "tool_result",
+        toolCallId: "t",
+        toolName: "bash",
+        input: { command: "echo hi" },
+        content: [{ type: "text", text: "" }],
+        isError: false,
+        details: { exitCode: 0 },
+      } as unknown as Parameters<typeof h.dispatch>[0],
+      makeExtCtx(),
+      0,
+    );
+    // Resolved shape is sane.
+    assert.deepEqual(h.resolved.rules, []);
+    assert.deepEqual(h.resolved.observers, []);
+  });
+
+  it("includeDefaults: true injects DEFAULT_RULES (no-force-push fires)", async () => {
+    const h = loadHarness({ config: {}, includeDefaults: true });
+    const res = await h.evaluate(
+      {
+        type: "tool_call",
+        toolCallId: "t",
+        toolName: "bash",
+        input: { command: "git push --force" },
+      },
+      makeExtCtx(),
+      0,
+    );
+    assert.ok(res && res.block === true);
+    assert.match(res.reason ?? "", /\[steering:no-force-push@[^\]]+\]/);
+  });
+
+  it("includeDefaults: false (default) does NOT inject defaults", async () => {
+    const h = loadHarness({ config: {} });
+    const res = await h.evaluate(
+      {
+        type: "tool_call",
+        toolCallId: "t",
+        toolName: "bash",
+        input: { command: "git push --force" },
+      },
+      makeExtCtx(),
+      0,
+    );
+    assert.equal(res, undefined);
+  });
+
+  it("merges a custom plugin's rules + predicates", async () => {
+    // Custom rule + plugin predicate; evaluate a matching bash call.
+    const rule: Rule = {
+      name: "no-cowsay",
+      tool: "bash",
+      field: "command",
+      pattern: "^cowsay\\b",
+      reason: "no cows",
+    };
+    const plugin: Plugin = {
+      name: "petting-zoo",
+      predicates: {
+        // Loose predicate: always-true; here to verify the merger
+        // registered it so `when` can reference it by name.
+        always: async () => true,
+      },
+      rules: [rule],
+    };
+    const h = loadHarness({ config: { plugins: [plugin] } });
+    assert.ok(h.resolved.predicates["always"] !== undefined);
+    assert.equal(h.resolved.rules.length, 1);
+    assert.equal(h.resolved.rules[0]!.name, "no-cowsay");
+
+    const res = await h.evaluate(
+      {
+        type: "tool_call",
+        toolCallId: "t",
+        toolName: "bash",
+        input: { command: "cowsay hello" },
+      },
+      makeExtCtx(),
+      0,
+    );
+    assert.ok(res && res.block === true);
+  });
+
+  it("applies config.disabledRules to named rules", async () => {
+    const h = loadHarness({
+      config: { disabledRules: ["no-force-push"] },
+      includeDefaults: true,
+    });
+    // Rule was filtered out → force-push no longer blocks.
+    const res = await h.evaluate(
+      {
+        type: "tool_call",
+        toolCallId: "t",
+        toolName: "bash",
+        input: { command: "git push --force" },
+      },
+      makeExtCtx(),
+      0,
+    );
+    assert.equal(res, undefined);
+  });
+
+  it("respects a custom host option", async () => {
+    let execCalls = 0;
+    const host: EvaluatorHost = {
+      exec: async () => {
+        execCalls++;
+        return { stdout: "main", stderr: "", code: 0, killed: false };
+      },
+      appendEntry: () => {},
+    };
+    // A rule with a condition that calls ctx.exec.
+    const rule: Rule = {
+      name: "uses-exec",
+      tool: "bash",
+      field: "command",
+      pattern: "^git\\b",
+      reason: "calls exec",
+      when: {
+        condition: async (ctx) => {
+          await ctx.exec("git", ["rev-parse", "HEAD"]);
+          return true;
+        },
+      },
+    };
+    const h = loadHarness({ config: { rules: [rule] }, host });
+    const res = await h.evaluate(
+      {
+        type: "tool_call",
+        toolCallId: "t",
+        toolName: "bash",
+        input: { command: "git status" },
+      },
+      makeExtCtx(),
+      0,
+    );
+    assert.ok(res && res.block === true);
+    assert.equal(execCalls, 1);
+  });
+
+  it("default host's unstubbed exec surfaces as a logged warning + fires fail-CLOSED (S1)", async () => {
+    // S1: a throwing predicate (here: the default host's `exec`
+    // throwing 'exec not stubbed') is caught by the evaluator and
+    // treated as `"unknown"`. Outer-level `condition:` is
+    // bare-`PredicateFn`-typed (no leaf-level `onUnknown:` opt-in
+    // available), so the projection always uses the default `"block"`
+    // policy and the rule fires fail-CLOSED. The test's original
+    // intent — 'authors who forget to stub exec see a clear error' —
+    // still holds: the warning names the rule + its source and carries
+    // the original error message.
+    //
+    // Symmetry note: outer-level `condition:` throws now mirror the
+    // inner not-block treatment + the plugin-handler exception
+    // contract — throw → `"unknown"` → default `"block"` projection.
+    // Authors who want fail-OPEN treatment for a throwing condition
+    // need to express the policy at the containing block level (e.g.
+    // inside `not: { condition: fn, onUnknown: "allow" }`).
+    const rule: Rule = {
+      name: "uses-exec",
+      tool: "bash",
+      field: "command",
+      pattern: "^git\\b",
+      reason: "calls exec",
+      when: {
+        condition: async (ctx) => {
+          await ctx.exec("git", ["rev-parse", "HEAD"]);
+          return true;
+        },
+      },
+    };
+    const h = loadHarness({ config: { rules: [rule] } });
+    const warnings: string[] = [];
+    const originalWarn = console.warn;
+    console.warn = (...args: unknown[]) => {
+      warnings.push(args.map((a) => String(a)).join(" "));
+    };
+    try {
+      const result = await h.evaluate(
+        {
+          type: "tool_call",
+          toolCallId: "t",
+          toolName: "bash",
+          input: { command: "git status" },
+        },
+        makeExtCtx(),
+        0,
+      );
+      // Rule fires fail-CLOSED (condition: threw → unknown → default
+      // leaf-level `"block"` policy fires the rule).
+      assert.ok(result && result.block === true);
+      // Warning names the rule + its `@<source>` tag + the
+      // unstubbed-exec message via the `when.condition threw` channel.
+      assert.ok(
+        warnings.some((w) =>
+          /Rule "uses-exec"@user.*when\.condition threw.*exec not stubbed/.test(
+            w,
+          ),
+        ),
+        `no matching warning in:\n${warnings.join("\n")}`,
+      );
+    } finally {
+      console.warn = originalWarn;
+    }
+  });
+
+  it("exposes harness.config reflecting the effective (disable-filtered) state (T3)", () => {
+    const harness = loadHarness({
+      config: {
+        rules: [
+          {
+            name: "keep-me",
+            tool: "bash",
+            field: "command",
+            pattern: /^keep/,
+            reason: "keep",
+          },
+          {
+            name: "drop-me",
+            tool: "bash",
+            field: "command",
+            pattern: /^drop/,
+            reason: "drop",
+          },
+        ],
+        disabledRules: ["drop-me"],
+      },
+    });
+    // Config mirror is post-filter: only `keep-me` survives in
+    // `config.rules`; the `disabledRules` list is preserved for
+    // introspection.
+    assert.ok(harness.config);
+    assert.equal(harness.config.rules?.length, 1);
+    assert.equal(harness.config.rules?.[0]?.name, "keep-me");
+    assert.deepEqual(harness.config.disabledRules, ["drop-me"]);
+  });
+
+  it("exposes harness.resolved with plugin-side rules after merger (T3)", () => {
+    const pluginRule = {
+      name: "plugin-rule",
+      tool: "bash" as const,
+      field: "command" as const,
+      pattern: /^keep/,
+      reason: "plugin",
+    };
+    const droppedPluginRule = {
+      name: "dropped-plugin-rule",
+      tool: "bash" as const,
+      field: "command" as const,
+      pattern: /^drop/,
+      reason: "drop",
+    };
+    const harness = loadHarness({
+      config: {
+        plugins: [{ name: "demo", rules: [pluginRule, droppedPluginRule] }],
+        disabledRules: ["dropped-plugin-rule"],
+      },
+    });
+    // `resolved` reflects plugin-merger output: plugin-shipped rules
+    // after disable filtering. User rules live on `harness.config`,
+    // not here.
+    const resolvedNames = harness.resolved.rules.map((r) => r.name);
+    assert.deepEqual(resolvedNames, ["plugin-rule"]);
+    assert.ok(
+      !resolvedNames.includes("dropped-plugin-rule"),
+      "disabled plugin rule must not appear in resolved state",
+    );
+  });
+
+  it("surfaces an empty diagnostics array for a clean config", () => {
+    const rule = {
+      name: "clean",
+      tool: "bash" as const,
+      field: "command" as const,
+      pattern: /^never$/,
+      reason: "clean",
+    };
+    const harness = loadHarness({ config: { rules: [rule] } });
+    assert.deepEqual(harness.diagnostics, []);
+  });
+
+  it("does NOT throw on a malformed plugin name; surfaces it as an invalid-name error-class diagnostic", () => {
+    // `validateName` flows through the diagnostic stream rather than
+    // throwing so plugin-author tests can read the failure surface
+    // from `harness.diagnostics` instead of catching a thrown Error.
+    const plugin: Plugin = {
+      // Spaces in a plugin name forge the `[steering:<name>@<source>]`
+      // block-reason tag (S3 boundary).
+      name: "bad name",
+    };
+    const harness = loadHarness({ config: { plugins: [plugin] } });
+    const hit = harness.diagnostics.find((d) => d.kind === "invalid-name");
+    assert.ok(
+      hit,
+      `expected an invalid-name diagnostic; got: ${JSON.stringify(harness.diagnostics)}`,
+    );
+    assert.equal(hit.type, "error");
+    assert.match(hit.message, /^plugin name "bad name".*disallowed/);
+  });
+
+  it("returns a no-op harness on a plugin-merger-side error-class diagnostic (reserved-tracker-name)", () => {
+    // Symmetric short-circuit: any error-class diagnostic — from the
+    // loader, the cross-config merge, OR the plugin merger — produces
+    // a no-op harness so plugin-author tests see uniform behavior
+    // regardless of which surface flagged the problem. Before the
+    // short-circuit moved to AFTER `resolvePlugins`, plugin-merger
+    // errors flowed through to a partially-built harness.
+    const t = {
+      initial: "?" as const,
+      unknown: "unknown" as const,
+      modifiers: {},
+      subshellSemantics: "isolated" as const,
+    };
+    const plugin: Plugin = {
+      name: "reserved-name-plugin",
+      trackers: { events: t as never },
+      rules: [
+        {
+          name: "would-block",
+          tool: "bash" as const,
+          field: "command" as const,
+          pattern: /^.*$/,
+          reason: "never",
+        },
+      ],
+    };
+    const harness = loadHarness({ config: { plugins: [plugin] } });
+    // Diagnostic surfaced.
+    const hit = harness.diagnostics.find(
+      (d) => d.kind === "reserved-tracker-name",
+    );
+    assert.ok(
+      hit,
+      `expected a reserved-tracker-name diagnostic; got: ${JSON.stringify(harness.diagnostics)}`,
+    );
+    // Harness is no-op: resolved is empty (no rules / no observers /
+    // no trackers), so the would-block rule that the plugin shipped
+    // alongside the bad tracker doesn't fire either.
+    assert.equal(harness.resolved.rules.length, 0);
+    assert.equal(harness.resolved.observers.length, 0);
+    assert.deepEqual(harness.resolved.trackers, {});
+    // Consistency: resolved.diagnostics mirrors the outer
+    // harness.diagnostics in the no-op short-circuit branch so
+    // consumers reading either surface get the same list.
+    assert.equal(
+      harness.resolved.diagnostics.length,
+      harness.diagnostics.length,
+    );
+    assert.ok(
+      harness.resolved.diagnostics.some(
+        (d) => d.kind === "reserved-tracker-name",
+      ),
+    );
+  });
+
+  it("surfaces an error-class diagnostic when a plugin claims a reserved tracker name", () => {
+    // Plugin authors writing tests against `loadHarness` should see
+    // reserved-name violations in their diagnostics array, NOT a thrown
+    // error that hides which other diagnostics fired alongside.
+    const t = {
+      initial: "?" as const,
+      unknown: "unknown" as const,
+      modifiers: {},
+      subshellSemantics: "isolated" as const,
+    };
+    const plugin: Plugin = {
+      name: "reserved-name-plugin",
+      // `events` is reserved for the evaluator's speculative-entry
+      // synthesis; plugins must not register a tracker under that name.
+      trackers: { events: t as never },
+    };
+    const harness = loadHarness({ config: { plugins: [plugin] } });
+    const hit = harness.diagnostics.find(
+      (d) => d.kind === "reserved-tracker-name",
+    );
+    assert.ok(
+      hit,
+      `expected a reserved-tracker-name diagnostic; got: ${JSON.stringify(harness.diagnostics)}`,
+    );
+    assert.equal(hit.type, "error");
+  });
+
+  it("surfaces a warning-class diagnostic when two plugins register the same predicate key", () => {
+    const plugin1: Plugin = {
+      name: "p1",
+      predicates: { branch: () => true },
+    };
+    const plugin2: Plugin = {
+      name: "p2",
+      predicates: { branch: () => false },
+    };
+    const harness = loadHarness({
+      config: { plugins: [plugin1, plugin2] },
+    });
+    const hit = harness.diagnostics.find(
+      (d) => d.kind === "predicate-collision",
+    );
+    assert.ok(
+      hit,
+      `expected a predicate-collision diagnostic; got: ${JSON.stringify(harness.diagnostics)}`,
+    );
+    assert.equal(hit.type, "warning");
+  });
+
+  it("does NOT throw on a tracker-name collision; surfaces it as a single error-class diagnostic", () => {
+    // loadHarness aggregates loader + buildConfig + resolvePlugins
+    // diagnostics and short-circuits to a no-op evaluator/dispatcher
+    // when any error-class diagnostic fires, so plugin-author tests
+    // can read the diagnostic from `harness.diagnostics` instead of
+    // catching a thrown Error. The shared merge-pipeline helper
+    // short-circuits before resolvePlugins, so the same collision
+    // should appear exactly once even though both buildConfig's
+    // detectTrackerNameCollisions and resolvePlugins independently
+    // flag the same shape.
+    const t = {
+      initial: "?" as const,
+      unknown: "unknown" as const,
+      modifiers: {},
+      subshellSemantics: "isolated" as const,
+    };
+    const harness = loadHarness({
+      config: {
+        plugins: [
+          { name: "pa", trackers: { branch: t as never } },
+          { name: "pb", trackers: { branch: t as never } },
+        ],
+      },
+    });
+    const hits = harness.diagnostics.filter(
+      (d) => d.kind === "tracker-name-collision",
+    );
+    assert.equal(
+      hits.length,
+      1,
+      `expected a single tracker-name-collision diagnostic; got: ${JSON.stringify(harness.diagnostics)}`,
+    );
+    const [hit] = hits;
+    assert.equal(hit?.type, "error");
+  });
+
+  it("does NOT throw on a malformed user-config rule name; surfaces it as an invalid-name error-class diagnostic", () => {
+    // User-config rule name validation runs inside the shared
+    // merge-pipeline helper before `resolvePlugins`, so a malformed
+    // rule name in the harness's input config produces the same
+    // `kind: "invalid-name"` diagnostic shape as a malformed
+    // plugin-shipped rule name. Without unification the harness
+    // would throw a plain `pi-steering: rule name "..."` Error from
+    // `buildEvaluator`, contradicting the documented "does NOT throw
+    // on error-class diagnostics" contract.
+    const harness = loadHarness({
+      config: {
+        rules: [
+          {
+            name: "phony] BAD",
+            tool: "bash" as const,
+            field: "command" as const,
+            pattern: /^never$/,
+            reason: "r",
+          },
+        ],
+      },
+    });
+    const hit = harness.diagnostics.find((d) => d.kind === "invalid-name");
+    assert.ok(
+      hit,
+      `expected an invalid-name diagnostic; got: ${JSON.stringify(harness.diagnostics)}`,
+    );
+    assert.equal(hit.type, "error");
+    assert.match(hit.message, /^rule name "phony\] BAD".*disallowed/);
+    assert.match(hit.message, /\(user config\)/);
+    // Harness short-circuits to a no-op evaluator/dispatcher pair
+    // the same way it does for plugin-shipped errors.
+    assert.equal(harness.resolved.rules.length, 0);
+  });
+
+  it("does NOT throw on a malformed user-config observer name; surfaces it as an invalid-name error-class diagnostic", () => {
+    // Same shape as the rule-name case but for observers — confirms
+    // the validation covers both surfaces of `validateUserConfigNames`.
+    const harness = loadHarness({
+      config: {
+        observers: [
+          {
+            name: "bad observer name",
+            watch: { toolName: "bash" as const },
+            onResult: () => {},
+          },
+        ],
+      },
+    });
+    const hit = harness.diagnostics.find((d) => d.kind === "invalid-name");
+    assert.ok(
+      hit,
+      `expected an invalid-name diagnostic; got: ${JSON.stringify(harness.diagnostics)}`,
+    );
+    assert.equal(hit.type, "error");
+    assert.match(hit.message, /^observer name "bad observer name".*disallowed/);
+    assert.match(hit.message, /\(user config\)/);
+  });
+
+  it("surfaces BOTH a tracker-name-collision AND a malformed user-config rule name in one harness load", () => {
+    // Combined error: tracker-name-collision (merge-side) plus a
+    // malformed user-config rule name. Pins that user-config name
+    // validation runs unconditionally so both surface in one
+    // harness load, not on consecutive runs.
+    const t = {
+      initial: "?" as const,
+      unknown: "unknown" as const,
+      modifiers: {},
+      subshellSemantics: "isolated" as const,
+    };
+    const harness = loadHarness({
+      config: {
+        plugins: [
+          { name: "pa", trackers: { branch: t as never } },
+          { name: "pb", trackers: { branch: t as never } },
+        ],
+        rules: [
+          {
+            name: "phony] BAD",
+            tool: "bash" as const,
+            field: "command" as const,
+            pattern: /^never$/,
+            reason: "r",
+          },
+        ],
+      },
+    });
+    assert.ok(
+      harness.diagnostics.some((d) => d.kind === "tracker-name-collision"),
+      `expected a tracker-name-collision diagnostic; got: ${JSON.stringify(harness.diagnostics)}`,
+    );
+    assert.ok(
+      harness.diagnostics.some(
+        (d) =>
+          d.kind === "invalid-name" &&
+          /phony\] BAD/.test(d.message) &&
+          /\(user config\)/.test(d.message),
+      ),
+      `expected an invalid-name diagnostic for the malformed user-config rule; got: ${JSON.stringify(harness.diagnostics)}`,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// mockContext
+// ---------------------------------------------------------------------------
+
+describe("mockContext", () => {
+  it("returns a ctx with all required PredicateContext fields populated", () => {
+    const ctx = mockContext();
+    assert.equal(typeof ctx.cwd, "string");
+    assert.equal(ctx.tool, "bash");
+    assert.deepEqual(ctx.input, { tool: "bash", command: "" });
+    assert.equal(ctx.agentLoopIndex, 0);
+    assert.equal(typeof ctx.exec, "function");
+    assert.equal(typeof ctx.appendEntry, "function");
+    assert.equal(typeof ctx.findEntries, "function");
+    // Default walkerState populates cwd + an empty env map (Tier B /
+    // D1: plugin authors reading `walkerState.env.get(...)` get a
+    // well-typed Map even when the test doesn't wire up the env
+    // tracker explicitly).
+    assert.deepEqual(ctx.walkerState, {
+      cwd: "/tmp/test",
+      env: new Map<string, string>(),
+    });
+  });
+
+  it("applies cwd / agentLoopIndex / tool / input / walkerState overrides", () => {
+    const ctx = mockContext({
+      cwd: "/work",
+      agentLoopIndex: 7,
+      tool: "write",
+      input: { tool: "write", path: "/a.ts", content: "x" },
+      walkerState: { cwd: "/work", branch: "main" },
+    });
+    assert.equal(ctx.cwd, "/work");
+    assert.equal(ctx.agentLoopIndex, 7);
+    assert.equal(ctx.tool, "write");
+    assert.deepEqual(ctx.input, {
+      tool: "write",
+      path: "/a.ts",
+      content: "x",
+    });
+    // walkerState overrides merge OVER the defaults (shallow merge),
+    // so branch lands, cwd overrides the default, and env stays as the
+    // default empty Map — matching production evaluator shape.
+    assert.deepEqual(ctx.walkerState, {
+      cwd: "/work",
+      env: new Map(),
+      branch: "main",
+    });
+  });
+
+  it("derives default input shape per tool", () => {
+    const w = mockContext({ tool: "write" });
+    assert.deepEqual(w.input, { tool: "write", path: "", content: "" });
+    const e = mockContext({ tool: "edit" });
+    assert.deepEqual(e.input, { tool: "edit", path: "", edits: [] });
+  });
+
+  it("stubs exec: passes through cmd/args/opts", async () => {
+    const seen: Array<{
+      cmd: string;
+      args: readonly string[];
+      cwd?: string | undefined;
+    }> = [];
+    const ctx = mockContext({
+      exec: (cmd, args, opts) => {
+        seen.push({ cmd, args, cwd: opts?.cwd });
+        return { stdout: "ok", stderr: "", exitCode: 0 };
+      },
+    });
+    const r = await ctx.exec("git", ["status"], { cwd: "/x" });
+    assert.equal(r.stdout, "ok");
+    assert.deepEqual(seen, [{ cmd: "git", args: ["status"], cwd: "/x" }]);
+  });
+
+  it("unstubbed exec rejects with a clear error", async () => {
+    const ctx = mockContext();
+    await assert.rejects(
+      () => ctx.exec("git", ["status"]),
+      /mockContext: exec not stubbed/,
+    );
+  });
+
+  it("findEntries filters by customType and parses timestamps to epoch-ms", () => {
+    const iso = "2026-01-02T03:04:05.000Z";
+    const ctx = mockContext({
+      entries: [
+        {
+          type: "custom",
+          customType: "a",
+          data: { v: 1 },
+          timestamp: iso,
+        },
+        {
+          type: "custom",
+          customType: "b",
+          data: { v: 2 },
+          timestamp: iso,
+        },
+        {
+          type: "custom",
+          customType: "a",
+          data: { v: 3 },
+          timestamp: "not-a-date",
+        },
+      ],
+    });
+    const hits = ctx.findEntries<{ v: number }>("a");
+    assert.equal(hits.length, 2);
+    assert.deepEqual(hits[0]!.data, { v: 1 });
+    assert.equal(hits[0]!.timestamp, Date.parse(iso));
+    // Unparseable timestamp → 0 (documented fallback).
+    assert.equal(hits[1]!.timestamp, 0);
+    // No match → empty.
+    assert.deepEqual(ctx.findEntries("missing"), []);
+  });
+
+  it("appendEntry writes are captured (visible via getAppendedEntries)", () => {
+    // Auto-tag: object payloads get `_agentLoopIndex` merged in,
+    // bare calls wrap as `{ value: undefined, _agentLoopIndex }`.
+    // Same shape the real engine writes (production parity is the
+    // whole point of routing through createAppendEntry).
+    const ctx = mockContext();
+    ctx.appendEntry("x", { a: 1 });
+    ctx.appendEntry("y"); // no data — pi allows bare customType.
+    const captured = getAppendedEntries(ctx);
+    assert.equal(captured.length, 2);
+    assert.equal(captured[0]!.customType, "x");
+    assert.deepEqual(captured[0]!.data, { a: 1, _agentLoopIndex: 0 });
+    assert.equal(captured[1]!.customType, "y");
+    assert.deepEqual(captured[1]!.data, {
+      value: undefined,
+      _agentLoopIndex: 0,
+    });
+  });
+
+  it("appendEntry auto-tags object payloads with agentLoopIndex (G2)", () => {
+    const ctx = mockContext({ agentLoopIndex: 5 });
+    ctx.appendEntry("marker", { foo: 1 });
+    const entries = getAppendedEntries(ctx);
+    assert.deepEqual(entries, [
+      { customType: "marker", data: { foo: 1, _agentLoopIndex: 5 } },
+    ]);
+  });
+
+  it("appendEntry wraps primitive payloads as { value, _agentLoopIndex } (G2)", () => {
+    const ctx = mockContext({ agentLoopIndex: 2 });
+    ctx.appendEntry("num", 42);
+    const entries = getAppendedEntries(ctx);
+    assert.deepEqual(entries, [
+      { customType: "num", data: { value: 42, _agentLoopIndex: 2 } },
+    ]);
+  });
+
+  it("appendEntry wraps array payloads (F2 / G2 / G3)", () => {
+    const ctx = mockContext({ agentLoopIndex: 5 });
+    ctx.appendEntry("items", [1, 2, 3]);
+    const entries = getAppendedEntries(ctx);
+    assert.deepEqual(entries, [
+      { customType: "items", data: { value: [1, 2, 3], _agentLoopIndex: 5 } },
+    ]);
+  });
+
+  // ---- toolCallEvents: walkerState.events surface for tool_call-
+  // ---- scope `when.happened` and plugin predicates over synthesized entries
+
+  it("toolCallEvents default: walkerState has no `events` key when the option is omitted", () => {
+    // Matches the production shape for non-bash candidates or configs
+    // with no eligible observer — the evaluator's synthesis pass runs
+    // only for bash, and mockContext doesn't manufacture one on the
+    // caller's behalf.
+    const ctx = mockContext();
+    assert.equal(
+      (ctx.walkerState as Record<string, unknown> | undefined)?.["events"],
+      undefined,
+    );
+  });
+
+  it("toolCallEvents threads through to ctx.walkerState.events", () => {
+    // Surface-level: plugin authors drive `when.happened` with `in: "tool_call"`
+    // in isolation by passing `toolCallEvents`. The option merges
+    // into walkerState under the reserved `events` key, same shape
+    // the walker-level synthesis pass produces in production.
+    const events = {
+      SYNC: [{ data: {}, timestamp: 2 ** 52 + 1, speculative: true as const }],
+    };
+    const ctx = mockContext({ toolCallEvents: events });
+    const got = (ctx.walkerState as Record<string, unknown>)["events"];
+    assert.equal(got, events);
+  });
+
+  it("toolCallEvents overrides an `events` entry placed on walkerState directly", () => {
+    // Explicit option wins: the caller who opts into `toolCallEvents`
+    // gets the canonical shape without having to strip their own
+    // `walkerState.events` entry. Mirrors the evaluator's merge order
+    // (`{ ...trackerState, events }`).
+    const override = {
+      X: [{ data: 1, timestamp: 7, speculative: true as const }],
+    };
+    const ctx = mockContext({
+      walkerState: { cwd: "/w", events: { X: [] } },
+      toolCallEvents: override,
+    });
+    const got = (ctx.walkerState as Record<string, unknown>)["events"];
+    assert.equal(got, override);
+  });
+
+  it("testPredicate forwards toolCallEvents so plugin predicates over walkerState.events can be driven", async () => {
+    // End-to-end: a plugin predicate introspects walkerState.events,
+    // and testPredicate (which forwards the full options object to
+    // mockContext) lets the caller exercise both branches.
+    const fires: PredicateHandler<string> = async (event, ctx) => {
+      const events = (ctx.walkerState as Record<string, unknown> | undefined)?.[
+        "events"
+      ] as Record<string, readonly unknown[]> | undefined;
+      return (events?.[event]?.length ?? 0) > 0;
+    };
+
+    const cold = await testPredicate(fires, "SYNC", {});
+    assert.equal(cold, false, "no toolCallEvents → predicate sees nothing");
+
+    const warm = await testPredicate(fires, "SYNC", {
+      toolCallEvents: {
+        SYNC: [
+          { data: {}, timestamp: 2 ** 52 + 1, speculative: true as const },
+        ],
+      },
+    });
+    assert.equal(warm, true, "toolCallEvents populated → predicate fires");
+  });
+
+  // -------------------------------------------------------------------
+  // Env surface (Tier B / PR #5 — D1)
+  // -------------------------------------------------------------------
+
+  it("default walkerState carries an empty env Map", () => {
+    const ctx = mockContext();
+    const env = ctx.walkerState?.["env"];
+    assert.ok(env instanceof Map, "walkerState.env is a Map");
+    assert.equal((env as Map<string, string>).size, 0);
+  });
+
+  it("walkerState override SHALLOW-MERGES with defaults so env stays a Map (M8)", () => {
+    // Correctness fix M8: `mockContext({ walkerState: { cwd: "/x" } })`
+    // previously replaced the entire default, dropping `env: new Map()`
+    // and crashing any predicate that did `ctx.walkerState.env.get(...)`.
+    // The merge now preserves defaults for fields the override omits.
+    const ctx = mockContext({ walkerState: { cwd: "/x" } });
+    assert.equal(ctx.walkerState?.["cwd"], "/x", "override cwd lands");
+    const env = ctx.walkerState?.["env"];
+    assert.ok(
+      env instanceof Map,
+      "walkerState.env is still a Map — default not dropped by partial override",
+    );
+    assert.equal((env as Map<string, string>).size, 0);
+  });
+
+  it("walkerState.env override threads through to ctx", () => {
+    const ctx = mockContext({
+      walkerState: {
+        cwd: "/ws/pkg",
+        env: new Map([["WS", "/ws"]]),
+      },
+    });
+    const env = ctx.walkerState?.["env"] as ReadonlyMap<string, string>;
+    assert.equal(env.get("WS"), "/ws");
+    assert.equal(ctx.walkerState?.["cwd"], "/ws/pkg");
+  });
+
+  it("walkerState.cwd === 'unknown' is a legal input (exercises onUnknown branch)", async () => {
+    // Spec requirement: mockContext should accept walkerState.cwd
+    // at the "unknown" sentinel so tests can exercise the
+    // fail-closed `onUnknown: 'block'` path without wiring up a
+    // full walker.
+    const ctx = mockContext({
+      walkerState: { cwd: "unknown", env: new Map() },
+    });
+    assert.equal(ctx.walkerState?.["cwd"], "unknown");
+
+    // Sanity: a plugin predicate reading the sentinel can discriminate.
+    const onUnknownBlock = async (_args: unknown, c: typeof ctx) =>
+      c.walkerState?.["cwd"] === "unknown";
+    assert.equal(await onUnknownBlock(null, ctx), true);
+  });
+
+  it("env is consumable by a ReasonFn-style predicate via testPredicate", async () => {
+    // End-to-end: a plugin reads walkerState.env.get('NAME') and
+    // fires the rule when the var resolves to a specific value.
+    const envGuard: PredicateHandler<string> = async (name, ctx) => {
+      const env = ctx.walkerState?.["env"] as
+        | ReadonlyMap<string, string>
+        | undefined;
+      return env?.get(name) === "/workspace";
+    };
+    const hit = await testPredicate(envGuard, "WS", {
+      walkerState: {
+        cwd: "/start",
+        env: new Map([["WS", "/workspace"]]),
+      },
+    });
+    assert.equal(hit, true);
+
+    const miss = await testPredicate(envGuard, "WS", {
+      walkerState: { cwd: "/start", env: new Map() },
+    });
+    assert.equal(miss, false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// mockObserverContext
+// ---------------------------------------------------------------------------
+
+describe("mockObserverContext", () => {
+  it("returns a ctx with all required ObserverContext fields populated", () => {
+    const ctx = mockObserverContext();
+    assert.equal(ctx.cwd, "/tmp/test");
+    assert.equal(ctx.agentLoopIndex, 0);
+    assert.equal(typeof ctx.appendEntry, "function");
+    assert.equal(typeof ctx.findEntries, "function");
+  });
+
+  it("applies cwd / agentLoopIndex / entries overrides", () => {
+    const iso = "2026-03-04T05:06:07.000Z";
+    const ctx = mockObserverContext({
+      cwd: "/work",
+      agentLoopIndex: 3,
+      entries: [
+        {
+          type: "custom",
+          customType: "seen",
+          data: { n: 42 },
+          timestamp: iso,
+        },
+      ],
+    });
+    assert.equal(ctx.cwd, "/work");
+    assert.equal(ctx.agentLoopIndex, 3);
+    const hits = ctx.findEntries<{ n: number }>("seen");
+    assert.equal(hits.length, 1);
+    assert.deepEqual(hits[0]!.data, { n: 42 });
+    assert.equal(hits[0]!.timestamp, Date.parse(iso));
+  });
+
+  it("appendEntry captures are independent per context", () => {
+    const a = mockObserverContext({ agentLoopIndex: 0 });
+    const b = mockObserverContext({ agentLoopIndex: 0 });
+    a.appendEntry("one", { x: 1 });
+    b.appendEntry("two", { y: 2 });
+    assert.deepEqual(getAppendedEntries(a), [
+      { customType: "one", data: { x: 1, _agentLoopIndex: 0 } },
+    ]);
+    assert.deepEqual(getAppendedEntries(b), [
+      { customType: "two", data: { y: 2, _agentLoopIndex: 0 } },
+    ]);
+  });
+
+  it("observer appendEntry auto-tags with agentLoopIndex (G2)", () => {
+    const ctx = mockObserverContext({ agentLoopIndex: 9 });
+    ctx.appendEntry("seen", { foo: 1 });
+    assert.deepEqual(getAppendedEntries(ctx), [
+      { customType: "seen", data: { foo: 1, _agentLoopIndex: 9 } },
+    ]);
+  });
+
+  it("observer appendEntry wraps primitive payloads (G2)", () => {
+    const ctx = mockObserverContext({ agentLoopIndex: 3 });
+    ctx.appendEntry("n", 7);
+    assert.deepEqual(getAppendedEntries(ctx), [
+      { customType: "n", data: { value: 7, _agentLoopIndex: 3 } },
+    ]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getAppendedEntries
+// ---------------------------------------------------------------------------
+
+describe("getAppendedEntries", () => {
+  it("returns empty for a freshly-built mockContext (nothing appended yet)", () => {
+    const ctx = mockContext();
+    assert.deepEqual(getAppendedEntries(ctx), []);
+  });
+
+  it("returns writes after ctx.appendEntry calls", () => {
+    const ctx = mockContext();
+    ctx.appendEntry("x", { a: 1 });
+    const captured = getAppendedEntries(ctx);
+    assert.deepEqual(captured, [
+      { customType: "x", data: { a: 1, _agentLoopIndex: 0 } },
+    ]);
+  });
+
+  it("returns empty for a non-mock context (safe lookup, no throw)", () => {
+    // Craft a minimal non-mock PredicateContext. Shape-only — we never
+    // call its methods.
+    const adhoc: PredicateContext = {
+      cwd: "/",
+      tool: "bash",
+      input: { tool: "bash", command: "" },
+      agentLoopIndex: 0,
+      exec: () => Promise.resolve({ stdout: "", stderr: "", exitCode: 0 }),
+      appendEntry: () => {},
+      findEntries: () => [],
+    };
+    assert.deepEqual(getAppendedEntries(adhoc), []);
+    // Same for an ad-hoc ObserverContext.
+    const adhocObs: ObserverContext = {
+      cwd: "/",
+      agentLoopIndex: 0,
+      appendEntry: () => {},
+      findEntries: () => [],
+    };
+    assert.deepEqual(getAppendedEntries(adhocObs), []);
+  });
+
+  it("returned snapshot is decoupled from later writes", () => {
+    const ctx = mockContext();
+    ctx.appendEntry("first");
+    const snap = getAppendedEntries(ctx);
+    ctx.appendEntry("second");
+    // Snapshot captured only the first entry.
+    assert.equal(snap.length, 1);
+    // Re-reading picks up both.
+    assert.equal(getAppendedEntries(ctx).length, 2);
+  });
+});
+
+// ===========================================================================
+// Phase 5b — Convenience wrappers
+// ===========================================================================
+
+describe("testPredicate", () => {
+  it("returns the predicate's boolean verdict", async () => {
+    const alwaysTrue: PredicateHandler<unknown> = async () => true;
+    const alwaysFalse: PredicateHandler<unknown> = async () => false;
+    assert.equal(await testPredicate(alwaysTrue, null), true);
+    assert.equal(await testPredicate(alwaysFalse, null), false);
+  });
+
+  it("threads args + ctx (walkerState + exec stub) to the predicate", async () => {
+    const branchEq: PredicateHandler<string> = async (arg, ctx) => {
+      return ctx.walkerState?.["branch"] === arg;
+    };
+    const fires = await testPredicate(branchEq, "main", {
+      walkerState: { branch: "main" },
+    });
+    assert.equal(fires, true);
+  });
+
+  it("predicates can call stubbed exec via ctx", async () => {
+    const readsExec: PredicateHandler<unknown> = async (_, ctx) => {
+      const r = await ctx.exec("echo", ["hi"]);
+      return r.exitCode === 0;
+    };
+    const fires = await testPredicate(readsExec, null, {
+      exec: () => ({ stdout: "hi", stderr: "", exitCode: 0 }),
+    });
+    assert.equal(fires, true);
+  });
+});
+
+describe("testObserver", () => {
+  it("fires onResult when watch matches (or watch is absent)", async () => {
+    const obs: Observer = {
+      name: "all-events",
+      onResult: (_evt, ctx) => {
+        ctx.appendEntry("seen");
+      },
+    };
+    const { entries, watchMatched } = await testObserver(obs, {
+      toolName: "bash",
+      input: { command: "ls" },
+      output: {},
+      exitCode: 0,
+    });
+    assert.equal(watchMatched, true);
+    assert.equal(entries.length, 1);
+    assert.equal(entries[0]?.customType, "seen");
+  });
+
+  it("does NOT fire onResult when watch filter rejects", async () => {
+    const obs: Observer = {
+      name: "bash-only",
+      watch: { toolName: "bash" },
+      onResult: (_evt, ctx) => {
+        ctx.appendEntry("seen");
+      },
+    };
+    const { entries, watchMatched } = await testObserver(obs, {
+      toolName: "read",
+      input: {},
+      output: {},
+    });
+    assert.equal(watchMatched, false);
+    assert.equal(entries.length, 0);
+  });
+
+  it("watch.inputMatches with absent key is fail-closed", async () => {
+    const obs: Observer = {
+      name: "cmd-match",
+      watch: { inputMatches: { command: /^git/ } },
+      onResult: () => {},
+    };
+    const { watchMatched } = await testObserver(obs, {
+      toolName: "read",
+      input: {}, // no `command` field
+      output: {},
+    });
+    assert.equal(watchMatched, false);
+  });
+
+  it("watch.exitCode: success / failure / numeric / any", async () => {
+    const mk = (code: number | "success" | "failure" | "any") => ({
+      name: "e" + String(code),
+      watch: { exitCode: code },
+      onResult: () => {},
+    });
+    const ok = { toolName: "bash", input: {}, output: {}, exitCode: 0 };
+    const fail = {
+      toolName: "bash",
+      input: {},
+      output: {},
+      exitCode: 2,
+    };
+    assert.equal((await testObserver(mk("success"), ok)).watchMatched, true);
+    assert.equal((await testObserver(mk("success"), fail)).watchMatched, false);
+    assert.equal((await testObserver(mk("failure"), fail)).watchMatched, true);
+    assert.equal((await testObserver(mk(2), fail)).watchMatched, true);
+    assert.equal((await testObserver(mk("any"), fail)).watchMatched, true);
+  });
+
+  it("warns when options.exec is set (observers don't see exec)", async () => {
+    const obs: Observer = { name: "n", onResult: () => {} };
+    const warnings: unknown[][] = [];
+    const orig = console.warn;
+    console.warn = (...args: unknown[]) => warnings.push(args);
+    try {
+      await testObserver(
+        obs,
+        { toolName: "bash", input: {}, output: {} },
+        { exec: () => ({ stdout: "", stderr: "", exitCode: 0 }) },
+      );
+    } finally {
+      console.warn = orig;
+    }
+    assert.equal(warnings.length, 1);
+    assert.match(String(warnings[0]?.[0] ?? ""), /exec option ignored/);
+  });
+
+  it("watch.inputMatches.command is wrapper-aware on bash events (ADR §12)", async () => {
+    // Regression test for the former testing-side reimplementation
+    // of matchesWatch: it did a raw-string match only, so a watch of
+    // `command: /^git commit/` silently missed `sh -c 'git commit ...'`
+    // while production correctly fired on it. Now `testObserver`
+    // shares `matchesWatch` with the dispatcher so both paths agree.
+    const fired: string[] = [];
+    const obs: Observer = {
+      name: "commit-watcher",
+      watch: {
+        toolName: "bash",
+        inputMatches: { command: /^git commit/ },
+      },
+      onResult: (evt) => {
+        fired.push(String((evt.input as { command?: unknown }).command));
+      },
+    };
+
+    // Raw match still works (outer command IS `git commit ...`).
+    const raw = await testObserver(obs, {
+      toolName: "bash",
+      input: { command: 'git commit -m "x"' },
+      output: {},
+      exitCode: 0,
+    });
+    assert.equal(raw.watchMatched, true);
+
+    // Wrapper-aware: outer is `sh -c '...'`, the inner extracted ref
+    // is `git commit -m "x"` — the pattern matches the inner ref, so
+    // the observer fires. This previously failed silently under the
+    // reimplemented filter.
+    const wrapped = await testObserver(obs, {
+      toolName: "bash",
+      input: { command: `sh -c 'git commit -m "x"'` },
+      output: {},
+      exitCode: 0,
+    });
+    assert.equal(wrapped.watchMatched, true);
+    assert.equal(fired.length, 2);
+
+    // Negative control: an unrelated outer command doesn't match,
+    // even though it's a bash event.
+    const miss = await testObserver(obs, {
+      toolName: "bash",
+      input: { command: "ls -la" },
+      output: {},
+      exitCode: 0,
+    });
+    assert.equal(miss.watchMatched, false);
+  });
+});
+
+describe("expectBlocks / expectAllows / expectRuleFires", () => {
+  const blockAllRule: Rule = {
+    name: "block-all",
+    tool: "bash",
+    field: "command",
+    pattern: /.*/,
+    reason: "test block",
+    noOverride: true,
+  };
+
+  it("expectBlocks returns result on block", async () => {
+    const harness = loadHarness({ config: { rules: [blockAllRule] } });
+    const result = await expectBlocks(harness, { command: "anything" });
+    assert.ok(result);
+    assert.equal(result.block, true);
+  });
+
+  it("expectBlocks throws AssertionError on allow", async () => {
+    const harness = loadHarness({ config: { rules: [] } });
+    await assert.rejects(
+      () => expectBlocks(harness, { command: "anything" }),
+      /expected block, got allow/,
+    );
+  });
+
+  it("expectBlocks { rule } asserts rule name match", async () => {
+    const harness = loadHarness({ config: { rules: [blockAllRule] } });
+    await expectBlocks(harness, { command: "x" }, { rule: "block-all" });
+    await assert.rejects(
+      () => expectBlocks(harness, { command: "x" }, { rule: "other-rule" }),
+      /expected rule "other-rule" to fire/,
+    );
+  });
+
+  it("expectBlocks { reason: RegExp } asserts reason match", async () => {
+    const harness = loadHarness({ config: { rules: [blockAllRule] } });
+    await expectBlocks(harness, { command: "x" }, { reason: /test block/ });
+    await assert.rejects(
+      () => expectBlocks(harness, { command: "x" }, { reason: /wrong reason/ }),
+      /reason did not match/,
+    );
+  });
+
+  it("expectAllows succeeds on no block", async () => {
+    const harness = loadHarness({ config: { rules: [] } });
+    await expectAllows(harness, { command: "anything" });
+  });
+
+  it("expectAllows throws on block", async () => {
+    const harness = loadHarness({ config: { rules: [blockAllRule] } });
+    await assert.rejects(
+      () => expectAllows(harness, { command: "x" }),
+      /expected allow, got block/,
+    );
+  });
+
+  it("expectRuleFires delegates to expectBlocks { rule }", async () => {
+    const harness = loadHarness({ config: { rules: [blockAllRule] } });
+    await expectRuleFires(harness, { command: "x" }, "block-all");
+    await assert.rejects(
+      () => expectRuleFires(harness, { command: "x" }, "nope"),
+      /expected rule "nope" to fire/,
+    );
+  });
+
+  it("accepts a WriteShorthand", async () => {
+    const writeBlock: Rule = {
+      name: "write-block",
+      tool: "write",
+      field: "content",
+      pattern: /forbidden/,
+      reason: "no",
+      noOverride: true,
+    };
+    const harness = loadHarness({ config: { rules: [writeBlock] } });
+    await expectBlocks(harness, {
+      write: { path: "f.txt", content: "forbidden content" },
+    });
+    await expectAllows(harness, {
+      write: { path: "f.txt", content: "ok content" },
+    });
+  });
+});
+
+describe("runMatrix / formatMatrix", () => {
+  const blockAllRule: Rule = {
+    name: "block-all",
+    tool: "bash",
+    field: "command",
+    pattern: /.*/,
+    reason: "test block",
+    noOverride: true,
+  };
+
+  it("tallies pass / fail counts", async () => {
+    const harness = loadHarness({ config: { rules: [blockAllRule] } });
+    const result = await runMatrix(harness, [
+      { name: "a", event: { command: "x" }, expect: "block" },
+      {
+        name: "b",
+        event: { command: "y" },
+        expect: { block: true, rule: "block-all" },
+      },
+      { name: "c", event: { command: "z" }, expect: "allow" }, // will fail
+    ]);
+    assert.equal(result.total, 3);
+    assert.equal(result.passed, 2);
+    assert.equal(result.failed, 1);
+    assert.equal(result.cases[0]?.passed, true);
+    assert.equal(result.cases[1]?.passed, true);
+    assert.equal(result.cases[2]?.passed, false);
+    assert.match(
+      result.cases[2]?.errorMessage ?? "",
+      /expected allow.*got block/,
+    );
+  });
+
+  it("block:{rule} expectation catches wrong-rule fires", async () => {
+    const r1: Rule = {
+      name: "rule-one",
+      tool: "bash",
+      field: "command",
+      pattern: /^x/,
+      reason: "r1",
+      noOverride: true,
+    };
+    const r2: Rule = {
+      name: "rule-two",
+      tool: "bash",
+      field: "command",
+      pattern: /^y/,
+      reason: "r2",
+      noOverride: true,
+    };
+    const harness = loadHarness({ config: { rules: [r1, r2] } });
+    const result = await runMatrix(harness, [
+      {
+        name: "wrong-rule",
+        event: { command: "x" },
+        expect: { block: true, rule: "rule-two" }, // r1 fires, not r2
+      },
+    ]);
+    assert.equal(result.passed, 0);
+    assert.equal(result.failed, 1);
+    assert.match(
+      result.cases[0]?.errorMessage ?? "",
+      /expected rule "rule-two"; got "rule-one"/,
+    );
+  });
+
+  it("never throws — failures appear in the result", async () => {
+    const harness = loadHarness({ config: { rules: [] } });
+    // All cases will fail.
+    const result = await runMatrix(harness, [
+      { name: "f1", event: { command: "x" }, expect: "block" },
+      { name: "f2", event: { command: "y" }, expect: "block" },
+    ]);
+    assert.equal(result.passed, 0);
+    assert.equal(result.failed, 2);
+  });
+
+  it("formatMatrix renders a readable report", async () => {
+    const harness = loadHarness({ config: { rules: [blockAllRule] } });
+    const result = await runMatrix(harness, [
+      { name: "case-a", event: { command: "x" }, expect: "block" },
+      { name: "case-b", event: { command: "y" }, expect: "allow" },
+    ]);
+    const report = formatMatrix(result);
+    assert.match(report, /MATRIX — 2 cases\. 1 pass, 1 fail/);
+    assert.match(report, /\[case-a\].*expect:block.*actual:BLOCK/);
+    assert.match(report, /\[case-b\].*expect:allow.*actual:BLOCK.*FAIL/);
+    assert.match(report, /PASS: 1\/2/);
+  });
+});
+
+// ===========================================================================
+// createRecordingHost + mockExtensionContext
+// ===========================================================================
+
+describe("createRecordingHost", () => {
+  it("returns a host with empty entries / execCalls / appendedEntries", () => {
+    const host = createRecordingHost();
+    assert.deepEqual(host.entries, []);
+    assert.deepEqual(host.execCalls, []);
+    assert.deepEqual(host.appendedEntries, []);
+    assert.equal(typeof host.exec, "function");
+    assert.equal(typeof host.appendEntry, "function");
+  });
+
+  it("appendEntry records both raw (appendedEntries) and session-shape (entries) logs", () => {
+    const host = createRecordingHost();
+    host.appendEntry("marker", { foo: 1 });
+    host.appendEntry("marker-bare"); // bare call — pi allows no data.
+    assert.equal(host.appendedEntries.length, 2);
+    assert.deepEqual(host.appendedEntries[0], {
+      type: "marker",
+      data: { foo: 1 },
+    });
+    assert.deepEqual(host.appendedEntries[1], {
+      type: "marker-bare",
+      data: undefined,
+    });
+
+    assert.equal(host.entries.length, 2);
+    // Session-shape entries mirror what pi's sessionManager emits:
+    // type, customType, data, timestamp, id, parentId.
+    assert.equal(host.entries[0]?.type, "custom");
+    assert.equal(host.entries[0]?.customType, "marker");
+    assert.deepEqual(host.entries[0]?.data, { foo: 1 });
+    assert.equal(typeof host.entries[0]?.timestamp, "string");
+    assert.match(
+      host.entries[0]?.timestamp ?? "",
+      /^2026-01-01T00:00:/, // monotonic ISO starting at the 2026-01-01 epoch.
+    );
+    assert.equal(host.entries[0]?.parentId, null);
+    // Timestamps strictly increase so chronological asserts are stable.
+    assert.ok(
+      (host.entries[0]?.timestamp ?? "") < (host.entries[1]?.timestamp ?? ""),
+      "entry timestamps should be monotonically increasing",
+    );
+  });
+
+  it("exec defaults to empty-success, records cmd/args/cwd per call", async () => {
+    const host = createRecordingHost();
+    const r = await host.exec("git", ["status"], { cwd: "/work" });
+    assert.deepEqual(r, {
+      stdout: "",
+      stderr: "",
+      code: 0,
+      killed: false,
+    });
+    assert.equal(host.execCalls.length, 1);
+    assert.deepEqual(host.execCalls[0], {
+      cmd: "git",
+      args: ["status"],
+      cwd: "/work",
+    });
+
+    // A call without explicit cwd falls back to "/".
+    await host.exec("pwd", []);
+    assert.equal(host.execCalls[1]?.cwd, "/");
+  });
+
+  it("exec override is threaded through, default still records the call", async () => {
+    const host = createRecordingHost({
+      exec: async (cmd, _args, cwd) => ({
+        stdout: `ran:${cmd}@${cwd}`,
+        stderr: "",
+        code: 0,
+        killed: false,
+      }),
+    });
+    const r = await host.exec("echo", ["hi"], { cwd: "/x" });
+    assert.equal(r.stdout, "ran:echo@/x");
+    assert.equal(host.execCalls.length, 1);
+  });
+
+  it("defensively copies args so later mutation doesn't corrupt the record", async () => {
+    const host = createRecordingHost();
+    const args = ["status"];
+    await host.exec("git", args, { cwd: "/x" });
+    args.push("--mutated");
+    assert.deepEqual(host.execCalls[0]?.args, ["status"]);
+  });
+});
+
+describe("mockExtensionContext", () => {
+  it("exposes cwd + sessionManager.getEntries", () => {
+    const entries = [
+      {
+        type: "custom" as const,
+        customType: "seen",
+        data: { n: 1 },
+        timestamp: "2026-01-01T00:00:00.000Z",
+        id: "e1",
+        parentId: null,
+      },
+    ];
+    const ctx = mockExtensionContext("/repo", entries);
+    assert.equal(ctx.cwd, "/repo");
+    assert.deepEqual(ctx.sessionManager.getEntries(), entries);
+  });
+
+  it("defaults entries to an empty array when omitted", () => {
+    const ctx = mockExtensionContext("/repo");
+    assert.deepEqual(ctx.sessionManager.getEntries(), []);
+  });
+
+  it("round-trips: host.appendEntry writes visible via ctx.sessionManager.getEntries", () => {
+    // The core contract: feeding `host.entries` into the ctx lets
+    // the engine's writes flow back into its subsequent reads.
+    const host = createRecordingHost();
+    const ctx = mockExtensionContext("/repo", host.entries);
+
+    assert.deepEqual(ctx.sessionManager.getEntries(), []);
+    host.appendEntry("mark", { a: 1 });
+    const read = ctx.sessionManager.getEntries();
+    assert.equal(read.length, 1);
+    const first = read[0];
+    assert.ok(first && first.type === "custom");
+    assert.equal(first.customType, "mark");
+    assert.deepEqual(first.data, { a: 1 });
+
+    host.appendEntry("mark", { a: 2 });
+    assert.equal(ctx.sessionManager.getEntries().length, 2);
+  });
+
+  it("drives harness.evaluate + harness.dispatch end-to-end with a shared entries store", async () => {
+    // Demonstrates the intended plugin-author usage pattern:
+    // harness + recording host + shared ctx lets a test assert on
+    // the cross-hook observer → evaluator handoff without any
+    // `as any` escape hatches.
+    const rule: Rule = {
+      name: "needs-mark",
+      tool: "bash",
+      field: "command",
+      pattern: /^git pu/,
+      reason: "needs mark",
+      noOverride: true,
+      when: {
+        // Default `when.happened` semantic: fires when the type has
+        // NOT been written in the scope (ADR §5).
+        happened: { event: "test-passed", in: "agent_loop" },
+      },
+    };
+    const observer: Observer = {
+      name: "test-tracker",
+      watch: { toolName: "bash", inputMatches: { command: /^npm test/ } },
+      onResult: (_evt, obsCtx) => {
+        obsCtx.appendEntry("test-passed", {});
+      },
+    };
+
+    const host = createRecordingHost();
+    const ctx = mockExtensionContext("/repo", host.entries);
+    const harness = loadHarness({
+      config: { rules: [rule], observers: [observer] },
+      host,
+    });
+
+    // Without a prior test-passed entry, the guarded command blocks.
+    const blocked = await harness.evaluate(
+      {
+        type: "tool_call",
+        toolCallId: "tc1",
+        toolName: "bash",
+        input: { command: "git pu origin feat/x" },
+      } as unknown as Parameters<typeof harness.evaluate>[0],
+      ctx,
+      0,
+    );
+    assert.ok(blocked && blocked.block === true);
+
+    // Dispatch an `npm test` success → observer records test-passed.
+    await harness.dispatch(
+      {
+        type: "tool_result",
+        toolCallId: "tc1",
+        toolName: "bash",
+        input: { command: "npm test" },
+        content: [],
+        details: { exitCode: 0 },
+      } as unknown as Parameters<typeof harness.dispatch>[0],
+      ctx,
+      0,
+    );
+    assert.ok(
+      host.entries.some((e) => e.customType === "test-passed"),
+      "observer should have recorded a test-passed entry",
+    );
+
+    // Subsequent guarded command in the same agent loop passes.
+    const allowed = await harness.evaluate(
+      {
+        type: "tool_call",
+        toolCallId: "tc2",
+        toolName: "bash",
+        input: { command: "git pu origin feat/x" },
+      } as unknown as Parameters<typeof harness.evaluate>[0],
+      ctx,
+      0,
+    );
+    assert.equal(allowed, undefined);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// priorEntry
+// ---------------------------------------------------------------------------
+
+describe("priorEntry", () => {
+  it("merges _agentLoopIndex into plain-object data", () => {
+    const entry = priorEntry(
+      "ws-sync-done",
+      { note: "merged" },
+      { agentLoopIndex: 5 },
+    );
+    assert.deepEqual(entry, {
+      type: "custom",
+      customType: "ws-sync-done",
+      timestamp: "2026-01-01T00:00:00.000Z",
+      data: { note: "merged", _agentLoopIndex: 5 },
+    });
+  });
+
+  it("wraps primitive data as { value, _agentLoopIndex }", () => {
+    const entry = priorEntry("counter", 42, { agentLoopIndex: 2 });
+    assert.deepEqual(entry.data, { value: 42, _agentLoopIndex: 2 });
+  });
+
+  it("wraps array data as { value, _agentLoopIndex } (not merged)", () => {
+    const entry = priorEntry("list", [1, 2, 3], { agentLoopIndex: 1 });
+    assert.deepEqual(entry.data, { value: [1, 2, 3], _agentLoopIndex: 1 });
+  });
+
+  it("wraps undefined data as { value: undefined, _agentLoopIndex }", () => {
+    const entry = priorEntry("flag", undefined, { agentLoopIndex: 3 });
+    assert.deepEqual(entry.data, { value: undefined, _agentLoopIndex: 3 });
+  });
+
+  it("wraps null data as { value: null, _agentLoopIndex } (null is not a plain object)", () => {
+    const entry = priorEntry("sentinel", null, { agentLoopIndex: 0 });
+    assert.deepEqual(entry.data, { value: null, _agentLoopIndex: 0 });
+  });
+
+  it("defaults agentLoopIndex to 0 when opts omitted", () => {
+    const entry = priorEntry("marker", {});
+    assert.deepEqual(entry.data, { _agentLoopIndex: 0 });
+    assert.equal(entry.timestamp, "2026-01-01T00:00:00.000Z");
+    assert.equal(entry.type, "custom");
+    assert.equal(entry.customType, "marker");
+  });
+
+  it("respects custom timestamp when provided", () => {
+    const entry = priorEntry(
+      "t",
+      {},
+      {
+        agentLoopIndex: 0,
+        timestamp: "2026-06-15T12:34:56.789Z",
+      },
+    );
+    assert.equal(entry.timestamp, "2026-06-15T12:34:56.789Z");
+  });
+
+  it("round-trip with mockContext: entry is visible to findEntries with scope tag intact", () => {
+    // The entry should flow from `entries` through `findEntries` with
+    // its data shape preserved, INCLUDING the _agentLoopIndex tag —
+    // that's what lets the engine's agent_loop scope filter match it.
+    const ctx = mockContext({
+      agentLoopIndex: 5,
+      entries: [priorEntry("ws-sync-done", {}, { agentLoopIndex: 5 })],
+    });
+    const hits = ctx.findEntries<{ _agentLoopIndex: number }>("ws-sync-done");
+    assert.equal(hits.length, 1);
+    assert.equal(hits[0]?.data._agentLoopIndex, 5);
+  });
+});