@cad0p/pi-steering 0.1.0

package/examples/work-item-plugin/src/rules/push-requires-tests.ts

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: MIT
+// Part of the pi-steering work-item-plugin example.
+
+/**
+ * `push-requires-tests` — example rule.
+ *
+ * Demonstrates three v0.1.0 engine features in one rule:
+ *
+ *   1. Observer → rule coupling via shared constants (ADR §5, §14).
+ *      `npm-test-tracker` writes `TEST_PASSED_EVENT` on every
+ *      successful `npm test`; this rule gates `git push` on
+ *      `when.happened`, which fires when the event has NOT happened.
+ *
+ *   2. Temporal invalidation via `since` (PR §4). A separate observer
+ *      `retest-required-tracker` writes `RETEST_REQUIRED_EVENT` on
+ *      every `git pull`. Even if tests passed earlier in the loop, a
+ *      subsequent pull stale-s the test state — the rule fires again,
+ *      forcing a re-run against the updated tree.
+ *
+ *   3. `&&`-chain speculative allow (PR §4). Because the engine
+ *      sees `npm-test-tracker`'s `writes: [TEST_PASSED_EVENT]`, it
+ *      treats `npm test && git push` as safe: the push is gated on
+ *      the prior `&&` ref, and `&&` short-circuits on test failure.
+ *      This breaks the "block → agent retries same chain → block"
+ *      loop without weakening the guardrail for non-chained pushes.
+ *
+ * `in: "agent_loop"` scopes everything to the current user prompt +
+ * its tool calls. Running tests in a prior agent loop doesn't let
+ * you push in this one.
+ *
+ * Override: disallowed. Pushing without proof of green tests is an
+ * inherent-risk action here.
+ */
+
+import type { Rule } from "@cad0p/pi-steering";
+import { TEST_PASSED_EVENT } from "../observers/npm-test-tracker.ts";
+import { RETEST_REQUIRED_EVENT } from "../observers/retest-required-tracker.ts";
+
+export const pushRequiresTests = {
+  name: "push-requires-tests",
+  tool: "bash",
+  field: "command",
+  pattern: /^git\s+push\b/,
+  when: {
+    // Fires when TEST_PASSED_EVENT has NOT been written in the
+    // current agent loop, OR its most-recent entry is older than
+    // the most-recent RETEST_REQUIRED_EVENT (e.g. a later `git pull`
+    // stale-d the test state).
+    happened: {
+      event: TEST_PASSED_EVENT,
+      in: "agent_loop",
+      since: RETEST_REQUIRED_EVENT,
+    },
+  },
+  reason:
+    "Run `npm test` successfully in this agent loop before pushing. " +
+    "If you ran `git pull` after the last test, re-run tests.",
+  noOverride: true,
+  // Declaring the observer's write-type in our `writes` is NOT
+  // required — the observer already declares it. This rule doesn't
+  // write anything, so no `writes` here.
+} as const satisfies Rule;

package/examples/work-item-plugin/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "rootDir": "src"
+  },
+  "include": ["src/**/*"]
+}

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@cad0p/pi-steering",
+  "version": "0.1.0",
+  "private": false,
+  "description": "AST-backed steering hooks for pi \u2014 deterministic tool-call guardrails with command-level effective-cwd scoping.",
+  "keywords": [
+    "pi-package",
+    "extension",
+    "steering",
+    "guardrails",
+    "safety",
+    "hooks",
+    "ast",
+    "bash"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "pi-steering": "./dist/bin/pi-steering.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./plugins/git": {
+      "types": "./dist/plugins/git/index.d.ts",
+      "import": "./dist/plugins/git/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "examples",
+    "skills",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cad0p/pi-steering.git"
+  },
+  "license": "MIT",
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "clean": "rm -rf dist tsconfig.build.tsbuildinfo",
+    "build": "tsc -p tsconfig.build.json",
+    "prepare": "pnpm build",
+    "test": "node --test --experimental-strip-types 'src/**/*.test.ts'",
+    "test:examples": "pnpm -r test",
+    "typecheck": "tsc --noEmit",
+    "typecheck:examples": "pnpm -r typecheck",
+    "lint": "biome check src/ examples/ skills/ scripts/",
+    "lint:fix": "biome check --write src/ examples/ skills/ scripts/",
+    "smoke": "node scripts/smoke.mjs"
+  },
+  "dependencies": {
+    "unbash": "^3.0.0",
+    "@cad0p/unbash-walker": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.14",
+    "@types/node": "^20.19.39",
+    "typescript": "^5.4.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/steering-authoring/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: steering-authoring
+description: Author declarative steering rules for pi-steering. Use when the user asks to block or allow agent tool calls, write guardrails for bash/write/edit, author pi steering rules, add rule plugins, or convert a JSON steering config to the TypeScript config.
+---
+
+# pi-steering
+
+You have `@cad0p/pi-steering` installed. It blocks and allows agent tool calls (bash, write, edit) via declarative rules authored in TypeScript.
+
+## Where things live
+
+- Rules: `.pi/steering/index.ts` (directory form) or `.pi/steering.ts` (single-file form).
+- Local plugins: `.pi/steering/plugins/*.ts`, imported into `index.ts`.
+- Tests: `.pi/steering/*.test.ts` using `@cad0p/pi-steering/testing`.
+
+The loader walks up from `cwd` to the nearest `.pi/` dir, falling back to `~/.pi/`. See the README for the full precedence order.
+
+## Common operations
+
+| User says | You do |
+|---|---|
+| "block X" | Add a `Rule` with `tool`, `field`, and `pattern` to the `rules` array. |
+| "block X only in dir Y" | Add `when: { cwd: /Y/ }` to the rule. The walker resolves `cd "$WS/pkg"`-style dynamic targets through `envTracker`; intractable targets (unknown `$VAR`, command substitution) surface as `"unknown"` and fire `onUnknown: "block"` by default. |
+| "block X unless on branch Z" | `when: { not: { branch: /Z/ } }` — requires the git plugin. |
+| "block X unless `--flag`" | `unless: /--flag\b/`. |
+| "require Y before X" | Observer that `appendEntry`s a marker, plus a rule whose `when.happened` gates on it (`{ event, in: "agent_loop" }`). Prefer this to hand-rolled `findEntries` + `agentLoopIndex` comparisons — same semantics, less code. |
+| "require Y in a **prior** tool_call, not same-chain" | `when: { happened: { event, in: "agent_loop", notIn: "tool_call" } }`. `notIn` is scope subtraction — it removes the narrower scope from the broader one, so `&&`-chain bypass is blocked. Distinct from clause-level `not` (boolean negation). |
+| "invalidate Y when Z happens" | `when: { happened: { event: Y_EVENT, in: "agent_loop", since: Z_EVENT } }`. Y only counts if its latest entry is newer than Z's latest entry in scope. If Z never happened, the clause degrades to a simple presence check. |
+| "put runtime state in the block message" | `reason: (ctx) => \`blocked at \${ctx.walkerState?.cwd}\`` — `Rule.reason` accepts a sync or async function. The engine awaits it and prefixes with `[steering:name@source]` like a string reason. If it throws, a fail-safe fallback text fires and the error is logged to `console.warn`; the block still fires. |
+| "add a custom check" | Write a plugin in `.pi/steering/plugins/`, import it into `index.ts`, register it in `plugins: [...]`. |
+| "change the reason on a built-in rule" | Import the original rule from its plugin, spread it with `{ ...original, name: "new-name", reason: "..." }`, and use `disabledRules: ["original-name"]` + add the replacement. Preserves pattern / when / observer. |
+| "test this rule" | Create `steering.test.ts` using `expectBlocks` / `expectAllows` / `loadHarness`. |
+| "convert my JSON config to TypeScript" | Run `pi-steering import-json .pi/steering.json -o .pi/steering.ts`. Plugins, observers, and function predicates don't round-trip — author those directly in TS. |
+| "publish a pi-steering plugin" | Package as `pi-steering-<domain>` (unscoped) with `keywords: ["pi-package", "pi-steering-package"]` in package.json. peerDep on `@cad0p/pi-steering`. |
+
+## Minimal config
+
+```ts
+import { defineConfig } from "@cad0p/pi-steering";
+
+export default defineConfig({
+  rules: [
+    {
+      name: "no-dangerous-command",
+      tool: "bash",
+      field: "command",
+      pattern: /^dangerous-command\b/,
+      reason: "don't run this",
+    },
+  ],
+});
+```
+
+`DEFAULT_RULES` (e.g. `no-force-push`, `no-rm-rf-slash`) are included automatically. `DEFAULT_PLUGINS` is empty by design — plugins are opt-in (declare `plugins: [gitPlugin]`), which keeps `defineConfig`'s type unions (typo-checking on `disabledRules` / `disabledPlugins`) in sync with what's actually loaded. Disable defaults via `disabledRules: ["name"]` or opt out entirely with `disableDefaults: true`.
+
+## Git plugin (branch / upstream / commits-ahead predicates)
+
+```ts
+import { defineConfig } from "@cad0p/pi-steering";
+import gitPlugin from "@cad0p/pi-steering/plugins/git";
+
+export default defineConfig({
+  plugins: [gitPlugin],
+  rules: [
+    {
+      name: "no-main-push",
+      tool: "bash",
+      field: "command",
+      pattern: /^git\s+push\b/,
+      when: { branch: /^(main|master|mainline|trunk)$/ },
+      reason: "don't push from main",
+    },
+  ],
+});
+```
+
+## Testing
+
+```ts
+// .pi/steering/steering.test.ts
+import { describe, it } from "node:test";
+import { expectAllows, expectBlocks, loadHarness } from "@cad0p/pi-steering/testing";
+import config from "./index.ts";
+
+describe("my steering config", () => {
+  const harness = loadHarness({ config, includeDefaults: true });
+
+  it("blocks dangerous-command", async () => {
+    await expectBlocks(harness, { command: "dangerous-command run" });
+  });
+
+  it("allows safe commands", async () => {
+    await expectAllows(harness, { command: "ls" });
+  });
+});
+```
+
+Run with `node --test --experimental-strip-types '.pi/steering/**/*.test.ts'`.
+
+## Details
+
+Read [the package README](../../README.md) for the full schema, plugin authoring, observer / turn-state patterns, override semantics, and the JSON-to-TS conversion surface.

package/src/INVARIANTS.md

@@ -0,0 +1,116 @@
+# Internal invariants — `S`, `E`, and `O` tags
+
+Short reference for the load-bearing invariants flagged across the
+engine source. These are NOT a public API contract — they are
+maintainer shorthand to keep related call sites traceable across
+files. Source comments cite the tag and rely on this file for the
+definition.
+
+This file ships with the package as a maintainer-facing glossary;
+it is not part of the public API surface (no exports), but is
+included in the npm tarball for source-readers consulting tagged
+call sites on disk.
+
+## Safety invariants (`S`)
+
+The engine evaluates user-authored steering rules against
+LLM-proposed tool calls. The `S` invariants are the layered defenses
+that keep a buggy or malformed plugin / rule from silently
+failing OPEN the gate.
+
+### `S1` — fail-closed isolation
+
+**Where:** `evaluator.ts` (`evaluateEvent` top-level wrap; per-rule
+try/catch), `evaluator-internals/predicates.ts` (per-predicate
+try/catch in `runPredicateChain`).
+
+A predicate that throws — built-in or plugin-supplied, sync or async
+— is treated as "rule does not fire", logged via `console.warn` with
+the rule name + `@<source>` tag + key, and evaluation continues with
+the next rule. The top-level wrap in `evaluator.ts` is the outermost
+catch: if the engine's own scaffolding throws (parse errors, walker
+bugs, corrupted session JSONL), the tool is BLOCKED with an
+engine-tagged reason so the agent sees the throw came from the
+engine, not from a rule.
+
+The same pattern applies to observers in `observer-dispatcher.ts` —
+a throwing observer is isolated to its own dispatch and never
+escalates.
+
+### `S2` — write-through-read consistency
+
+**Where:** `evaluator-internals/context.ts` (`createAppendEntry` /
+`createFindEntries` paired-cache invariant).
+
+When `createAppendEntry` and `createFindEntries` share the same
+cache map (the evaluator wires them this way per tool_call; the
+observer-dispatcher wires them per tool_result),
+`createAppendEntry` invalidates the cache entry for the written
+`customType` so the next paired `createFindEntries` call re-reads.
+Callers omitting the shared cache get per-closure snapshot behavior.
+
+### `S3` — name validation
+
+**Where:** `plugin-merger.ts` (`validateName`; production pipeline
+via `validateUserConfigNames` + `resolvePlugins`), `evaluator.ts`
+(defensive throw in `buildEvaluator`), `observer-dispatcher.ts`
+(defensive throw in `buildObserverDispatcher`).
+
+Rule / plugin / observer names flow into user-visible strings — the
+`[steering:<name>@<source>]` block-reason tag shown to the LLM, the
+`@<source>` tag in warning logs, override-comment target matching,
+`disabledRules` / `disabledPlugins` config references. Names
+containing whitespace, control characters, `]`, or newlines let a
+malicious or careless config author forge block reasons that
+deceive the agent.
+
+Validated at production call sites (`validateUserConfigNames`,
+`resolvePlugins`) and as defense-in-depth at `buildEvaluator` /
+`buildObserverDispatcher` — see per-site JSDocs.
+
+## Evaluation invariants (`E`)
+
+### `E1` — cross-rule write visibility within a phase
+
+**Where:** paired-cache wiring in `evaluator.ts` and
+`observer-dispatcher.ts`; cache mechanism in
+`evaluator-internals/context.ts`.
+
+Within a single tool_call (or tool_result) phase, rule B's
+`when.happened` predicate MUST see entries rule A's `onFire` wrote
+earlier in the same phase. Implementation: shared cache invalidation
+per `S2`.
+
+## Orchestration invariants (`O`)
+
+### `O1` — observer-drop parity between runtime and CLI
+
+**Where:** `internal/session-runtime.ts` (`buildSessionRuntime` →
+`finalizePluginState`); `bin/pi-steering.ts`
+(`runCliMergeWithInfoCapture`).
+
+**What:** Both surfaces apply `disabledRules` filtering BEFORE
+running `dropUnusedObservers`, so an observer whose only consumers
+are disabled rules surfaces the same `console.info` breadcrumb in
+both paths. A future surface that bypasses this ordering would see
+different observer-drop behavior than the runtime.
+
+**Pinned by:** `internal/session-runtime.test.ts` (runtime branch);
+`bin/pi-steering.test.ts` (CLI branch).
+
+### `O2` — single-emission lock for cross-detector tracker-name collisions
+
+**Where:** `internal/session-runtime.ts` (`runMergerPipeline`);
+`loader.ts` (`detectTrackerNameCollisions`); `plugin-merger.ts`
+(`resolvePlugins`).
+
+**What:** Both `buildConfig` (loader-side) and `resolvePlugins`
+(merger-side) independently detect tracker-name collisions.
+`runMergerPipeline` short-circuits before invoking `resolvePlugins`
+when any merge-side diagnostic is error-class, so the aggregated
+error message lists each tracker-name collision exactly once.
+
+**Pinned by:** `internal/session-runtime.test.ts` "throws on an
+error-class diagnostic regardless of failOnWarnings" (single-emission
+lock); `factory-time-load.test.ts` "throws on tracker-name-collision"
+(integration mirror).

package/src/__test-helpers__.ts

@@ -0,0 +1,243 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+
+/**
+ * Shared test-double helpers.
+ *
+ * `evaluator.test.ts` and `observer-dispatcher.test.ts` both need:
+ *
+ *   - a minimal {@link ExtensionContext} stub whose `sessionManager`
+ *     only exposes `getEntries()` (everything else throws on access),
+ *   - a "tracked host" {@link EvaluatorHost} that records every
+ *     `exec` / `appendEntry` call plus pushes `appendEntry` payloads
+ *     into an entries array shaped like the pi session JSONL, so the
+ *     same array can back a `makeCtx` stub and let tests assert
+ *     cross-handler `findEntries` visibility.
+ *
+ * The two former copies diverged only in whether `makeHost` accepted an
+ * `exec` override (evaluator tests need it to count child-process
+ * invocations for the memoization assertions; observer tests don't).
+ * That's now a single option on the unified helper.
+ *
+ * Kept OUT of the public surface: `__test-helpers__` is a leading-double-
+ * underscore convention indicating "test only"; nothing under `src/`
+ * imports it at runtime.
+ */
+
+import {
+  mkdirSync,
+  mkdtempSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach } from "node:test";
+import type {
+  ExtensionContext,
+  ExecResult as PiExecResult,
+} from "@earendil-works/pi-coding-agent";
+import type { EvaluatorHost } from "./evaluator-internals/context.ts";
+
+// ---------------------------------------------------------------------------
+// Isolated $HOME fixture
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-test scratch `$HOME` fixture. Registers `beforeEach` /
+ * `afterEach` that:
+ *
+ *   - `mkdtempSync` a fresh temp dir using `prefix`,
+ *   - save `process.env["HOME"]`, point it at the temp dir,
+ *   - restore `process.env["HOME"]` and recursively remove the temp
+ *     dir on teardown.
+ *
+ * Used by every test surface that exercises the loader walk-up
+ * (`index.test.ts`, `loader.test.ts`, `internal/session-runtime.test.ts`)
+ * so the per-file scratch-HOME boilerplate stays in one place.
+ *
+ * The temp dir path is exposed via the optional `onReady` callback,
+ * fired inside `beforeEach`; tests typically stash it in a
+ * describe-scoped `let` for terser reads.
+ */
+export function useIsolatedHome(
+  prefix: string,
+  onReady?: (tmp: string) => void,
+): void {
+  let tmp: string;
+  let priorHome: string | undefined;
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), prefix));
+    priorHome = process.env["HOME"];
+    process.env["HOME"] = tmp;
+    onReady?.(tmp);
+  });
+  afterEach(() => {
+    if (priorHome === undefined) delete process.env["HOME"];
+    else process.env["HOME"] = priorHome;
+    rmSync(tmp, { recursive: true, force: true });
+  });
+}
+
+/**
+ * Like {@link useIsolatedHome} but also chdirs into the scratch dir, so factory-time tests find the per-test config via the loader walk-up. macOS tmpdir is a symlink; canonicalized via `realpathSync` so cwd-mismatch tests don't see false-divergence.
+ */
+export function useScratchHome(
+  prefix: string,
+  onReady?: (tmp: string) => void,
+): void {
+  let tmp: string;
+  let priorHome: string | undefined;
+  let priorCwd: string;
+  beforeEach(() => {
+    priorCwd = process.cwd();
+    tmp = realpathSync(mkdtempSync(join(tmpdir(), prefix)));
+    priorHome = process.env["HOME"];
+    process.env["HOME"] = tmp;
+    process.chdir(tmp);
+    onReady?.(tmp);
+  });
+  afterEach(() => {
+    process.chdir(priorCwd);
+    if (priorHome === undefined) delete process.env["HOME"];
+    else process.env["HOME"] = priorHome;
+    rmSync(tmp, { recursive: true, force: true });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Steering-config fixture writers
+// ---------------------------------------------------------------------------
+
+/**
+ * Write a single-file steering config to `<dir>/.pi/steering.ts`.
+ * `body` is the full module source (must include `export default`).
+ * Used by suites whose fixtures embed regex literals or other
+ * non-JSON-friendly module shapes inline.
+ */
+export function writeSteeringSingleFileConfig(dir: string, body: string): void {
+  mkdirSync(join(dir, ".pi"), { recursive: true });
+  writeFileSync(join(dir, ".pi", "steering.ts"), body, "utf8");
+}
+
+/**
+ * Write a directory-form steering config to
+ * `<dir>/.pi/steering/index.ts`. `body` is the full module source
+ * (must include `export default`). Mirrors the layout the bin tests
+ * use for their isolated `@cad0p/pi-steering` invocations.
+ */
+export function writeSteeringDirConfig(dir: string, body: string): void {
+  const pi = join(dir, ".pi", "steering");
+  mkdirSync(pi, { recursive: true });
+  writeFileSync(join(pi, "index.ts"), body, "utf8");
+}
+
+// ---------------------------------------------------------------------------
+// Session-entry shape
+// ---------------------------------------------------------------------------
+
+/**
+ * Exact shape pi's `sessionManager.getEntries()` returns for entries
+ * produced by `appendEntry`. The evaluator filters to `type: "custom"`,
+ * matches by `customType`, and reads `{ data, timestamp }` — other
+ * fields (`id`, `parentId`) exist on real entries so we mirror them
+ * here to avoid silent type drift.
+ */
+export interface CustomEntry {
+  readonly type: "custom";
+  readonly customType: string;
+  readonly data: unknown;
+  readonly timestamp: string;
+  readonly id: string;
+  readonly parentId: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// ExtensionContext stub
+// ---------------------------------------------------------------------------
+
+/**
+ * Minimal stub for pi's `ExtensionContext`. Only the fields the
+ * evaluator + observer-dispatcher read are populated; everything else
+ * throws if touched so accidental reliance on unsupported surface
+ * breaks loudly.
+ *
+ * The `entries` array mimics `sessionManager.getEntries()` output —
+ * tests that want cross-handler `findEntries` visibility pass
+ * `host.entries` (from {@link makeTrackedHost}) here so the host's
+ * `appendEntry` writes show up on subsequent reads.
+ */
+export function makeCtx(
+  cwd: string,
+  entries: ReadonlyArray<CustomEntry> = [],
+): ExtensionContext {
+  return {
+    cwd,
+    sessionManager: {
+      getEntries: () => entries,
+      // Other SessionManager methods are stubbed to throw via the
+      // unknown-cast below; any accidental dependency surfaces as a
+      // clear TypeError rather than silently passing.
+    } as unknown as ExtensionContext["sessionManager"],
+  } as ExtensionContext;
+}
+
+// ---------------------------------------------------------------------------
+// Tracked EvaluatorHost
+// ---------------------------------------------------------------------------
+
+/**
+ * Tracked {@link EvaluatorHost} recording every exec / appendEntry
+ * call so tests can assert memoization + audit logging.
+ *
+ * `entries` is the backing array `makeCtx` wraps when tests want the
+ * host's `appendEntry` writes visible to a later `findEntries` read.
+ * Timestamps are monotonically-incrementing second-level ISO strings
+ * so ordering asserts stay stable inside the same millisecond.
+ */
+export interface TrackedHost extends EvaluatorHost {
+  readonly execCalls: Array<{ cmd: string; args: string[]; cwd: string }>;
+  readonly appended: Array<{ type: string; data: unknown }>;
+  readonly entries: CustomEntry[];
+}
+
+/**
+ * Build a {@link TrackedHost}. Optional `exec` override lets evaluator
+ * tests count real invocations against the cache (the default exec
+ * returns `{ stdout: "", stderr: "", code: 0, killed: false }`).
+ */
+export function makeTrackedHost(options?: {
+  exec?: (cmd: string, args: string[], cwd: string) => Promise<PiExecResult>;
+}): TrackedHost {
+  const execCalls: TrackedHost["execCalls"] = [];
+  const appended: TrackedHost["appended"] = [];
+  const entries: CustomEntry[] = [];
+  let idCounter = 0;
+  return {
+    execCalls,
+    appended,
+    entries,
+    exec: async (cmd, args, opts) => {
+      const cwd = opts?.cwd ?? "/";
+      execCalls.push({ cmd, args: [...args], cwd });
+      if (options?.exec) {
+        return options.exec(cmd, args, cwd);
+      }
+      return { stdout: "", stderr: "", code: 0, killed: false };
+    },
+    appendEntry: (type, data) => {
+      appended.push({ type, data });
+      entries.push({
+        type: "custom",
+        customType: type,
+        data,
+        timestamp: new Date(
+          Date.UTC(2026, 0, 1, 0, 0, idCounter++),
+        ).toISOString(),
+        id: `entry-${idCounter}`,
+        parentId: null,
+      });
+    },
+  };
+}