@bugabinga/pi-ext-llmiterate 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0 - 2026-05-21
+
+- a40a427 prepare extensions for npm release
+- 133cb7d chore(pi): migrate extensions to earendil packages
+- 5ca1296 Rework Pi agent extensions
+

package/README.md

@@ -0,0 +1,160 @@
+# llmiterate
+
+File-save prompt markers for pi.
+
+## Marker syntax
+
+A prompt line starts with a configured marker as the first word after whitespace.
+Default markers: `LLM`, `PROMPT`.
+
+```java
+void main(final String[] a) {
+  LLM some prompt text
+  if (a.length == 0)
+    LLM deal with this
+  LLM open ui
+  LLM and then fix perf
+}
+```
+
+Parsing result:
+
+- `LLM some prompt text` → one agent request
+- `LLM deal with this` → one agent request
+- consecutive `LLM open ui` + `LLM and then fix perf` → one multi-line agent request
+
+Comment markers are not special. Configure them explicitly if wanted:
+
+```json
+{
+  "llmiterate": {
+    "markers": ["LLM", "//LLM", "/// LLM", "* LLM"]
+  }
+}
+```
+
+```rust
+fn fancy_algorithm() {
+  //LLM implement knapsack algorithm
+}
+```
+
+Rules:
+
+- marker must be first word/token on line, modulo leading whitespace
+- no automatic comment-prefix stripping for matching
+- use configured markers like `//LLM`, `* LLM`, `/// LLM` for comments
+- consecutive lines with the same marker are grouped
+- no `:` and no `{{ }}` syntax
+- empty marker lines are ignored
+- fenced code blocks in Markdown are ignored
+
+## Replacement behavior
+
+llmiterate instructs the agent to treat marker lines as inline prompts/TODOs and replace the whole marker span with the requested implementation/change.
+
+## Rerun policy
+
+Once queued, a marker key is recorded in the platform state dir:
+
+| Platform | State path |
+|----------|------------|
+| Linux/BSD | `${XDG_STATE_HOME:-~/.local/state}/pi/llmiterate/<projectHash>/state.json` |
+| macOS | `~/Library/Application Support/pi/llmiterate/<projectHash>/state.json` |
+| Windows | `%LOCALAPPDATA%\\pi\\llmiterate\\<projectHash>\\state.json` |
+
+```text
+file:startLine:hash(promptText)
+```
+
+Same marker will not rerun on later saves. To rerun, edit the prompt text or run:
+
+```text
+/llmiterate reset
+```
+
+## Execution model
+
+llmiterate always runs marker work in an isolated background Pi RPC worker.
+It never injects marker prompts into the current chat session.
+
+The worker is launched as:
+
+```bash
+pi --mode rpc --no-extensions --session-dir <platform-state-dir>/llmiterate/<projectHash>/sessions
+```
+
+Each marker job gets a fresh RPC session. Jobs are serialized per project: one background job runs at a time, queued jobs wait.
+Each job revalidates the marker span before launch; stale markers are skipped.
+
+## Editor safety
+
+llmiterate never edits files itself. File mutation comes only from the isolated Pi job via normal tools.
+
+## Watch behavior
+
+- handles normal writes, atomic-save rename patterns, moves into watched dirs, and new directories
+- refreshes directory watchers after `rename` events
+- removes watchers for deleted/moved-away directories
+- tracks watcher errors in status
+- skips queued requests when their marker span changed before background agent start
+- watches only directories that can contain paths configured in `llmiterate.include`
+- treats `llmiterate.exclude` as an optional veto after the include whitelist
+
+## Singleton behavior
+
+llmiterate is a singleton per detected project root, not raw shell cwd. The first Pi process creates `<platform-state-dir>/llmiterate/<projectHash>/lock` and owns the watcher. Other Pi processes launched anywhere under the same project root go into standby and only show status.
+
+Project root detection:
+
+1. nearest ancestor containing `.pi/` or `AGENTS.md`
+2. else nearest ancestor containing `.git`
+3. else current cwd
+
+- duplicate watchers do not queue duplicate agent runs
+- singleton roots are canonicalized with `realpath` so symlinked launches share a lock
+- stale global per-project locks are recovered when the owning PID is gone
+- subprojects are separate when they have their own `.pi/`, `AGENTS.md`, or `.git`
+
+## Config
+
+All config lives under the `llmiterate` key in Pi `settings.json`.
+Global: `~/.pi/agent/settings.json`. Project override: `.pi/settings.json`.
+
+Default `include` is empty, so llmiterate watches nothing until explicitly enabled for paths.
+
+```json
+{
+  "llmiterate": {
+    "enabled": true,
+    "include": ["src/**/*.{ts,tsx,rs,java,md}", "docs/**/*.md"],
+    "exclude": [
+      ".git/**",
+      ".pi/**",
+      "node_modules/**",
+      "target/**"
+    ],
+    "debounceMs": 3000,
+    "maxFileBytes": 1000000,
+    "markers": ["LLM", "PROMPT"]
+  }
+}
+```
+
+## Commands
+
+```text
+/llmiterate          toggle panel
+/llmiterate show     show panel
+/llmiterate hide     hide panel
+/llmiterate status   show panel
+/llmiterate scan     scan all matching files now
+/llmiterate reset    forget processed marker ledger
+/llmiterate reload   reload config + watcher
+```
+
+## Demo
+
+<!-- demo:workflow_suite:start -->
+![Workflow suite](assets/workflow_suite.gif)
+<!-- demo:workflow_suite:end -->

package/__bench__/PERF.md

@@ -0,0 +1,47 @@
+# llmiterate performance notes
+
+## Workflow
+
+Profile command:
+
+```bash
+bun --cpu-prof --cpu-prof-md --cpu-prof-dir=__bench__/profiles --cpu-prof-name=baseline.cpuprofile.md __bench__/bench.ts
+```
+
+Benchmark command:
+
+```bash
+bun __bench__/bench.ts
+/tmp/go-bin/benchstat __bench__/baseline.txt __bench__/optimized.txt
+```
+
+## Profile findings
+
+Baseline CPU profile hotspots:
+
+- path filtering dominated scans: `shouldIncludePath`, regex excludes, and `toSlash` split/join
+- parser spent avoidable time rebuilding marker regexes and checking Markdown extension per line
+
+## Optimizations
+
+- compile path filters once per runtime
+- split simple `dir/**` excludes into `Set` root-dir checks / prefix checks before regex fallback
+- add `shouldIncludeCompiledPath()` for hot scan paths
+- make `toSlash()` allocation-free when path is already slash-normalized
+- cache marker regex by normalized marker list
+- compute Markdown-file status once per parse
+
+## Benchstat
+
+```text
+                    │ __bench__/baseline.txt │        __bench__/optimized.txt        │
+                    │         sec/op         │    sec/op     vs base                 │
+ParseNoMarkers                  73.71µ ± ∞ ¹   57.10µ ± ∞ ¹        ~ (p=0.333 n=1+5)
+ParseSomeMarkers                82.60µ ± ∞ ¹   70.85µ ± ∞ ¹        ~ (p=0.333 n=1+5)
+ParseMarkdownFences            110.88µ ± ∞ ¹   80.38µ ± ∞ ¹        ~ (p=0.333 n=1+5)
+PathFilterCompiled             3227.5µ ± ∞ ¹   763.7µ ± ∞ ¹        ~ (p=0.333 n=1+5)
+geomean                         216.1µ         125.5µ        -41.90%
+¹ need >= 6 samples for confidence interval at level 0.95
+```
+
+Note: baseline was captured before optimization; optimized has 5 samples. Confidence is limited but direction/magnitude is clear.

package/__bench__/baseline.txt

@@ -0,0 +1,4 @@
+BenchmarkParseNoMarkers 4000 73707 ns/op
+BenchmarkParseSomeMarkers 4000 82603 ns/op
+BenchmarkParseMarkdownFences 2000 110883 ns/op
+BenchmarkPathFilterCompiled 2000 3227542 ns/op

package/__bench__/bench.ts

@@ -0,0 +1,66 @@
+import { performance } from "node:perf_hooks";
+import { compilePathFilter, defaultConfig, parseMarkerPrompts, shouldIncludeCompiledPath } from "../core";
+
+const ITERATIONS = Number(process.env.ITERATIONS ?? 2000);
+const MIN_TIME_MS = Number(process.env.MIN_TIME_MS ?? 200);
+
+const sourceNoMarkers = makeSource(600, 0);
+const sourceSomeMarkers = makeSource(600, 20);
+const markdown = makeMarkdown(900, 30);
+const paths = makePaths(5000);
+const filter = compilePathFilter(defaultConfig());
+
+bench("ParseNoMarkers", () => parseMarkerPrompts("src/main.ts", sourceNoMarkers));
+bench("ParseSomeMarkers", () => parseMarkerPrompts("src/main.ts", sourceSomeMarkers));
+bench("ParseMarkdownFences", () => parseMarkerPrompts("docs/notes.md", markdown));
+bench("PathFilterCompiled", () => {
+  let matched = 0;
+  for (const p of paths) if (shouldIncludeCompiledPath(p, filter)) matched++;
+  if (matched === 0) throw new Error("impossible");
+  return matched;
+});
+
+function bench(name: string, fn: () => unknown): void {
+  for (let i = 0; i < 50; i++) fn();
+
+  let iterations = ITERATIONS;
+  let elapsed = 0;
+  let result: unknown;
+
+  do {
+    const start = performance.now();
+    for (let i = 0; i < iterations; i++) result = fn();
+    elapsed = performance.now() - start;
+    if (elapsed < MIN_TIME_MS) iterations *= 2;
+  } while (elapsed < MIN_TIME_MS);
+
+  if (result === undefined) throw new Error("bench result vanished");
+  const nsPerOp = (elapsed * 1_000_000) / iterations;
+  console.log(`Benchmark${name} ${iterations} ${nsPerOp.toFixed(0)} ns/op`);
+}
+
+function makeSource(lines: number, markerEvery: number): string {
+  const out: string[] = [];
+  for (let i = 0; i < lines; i++) {
+    if (markerEvery > 0 && i % markerEvery === 0) out.push(`  LLM implement generated case ${i}`);
+    else out.push(`  const value${i} = callThing(${i}, "${i}");`);
+  }
+  return out.join("\n");
+}
+
+function makeMarkdown(lines: number, markerEvery: number): string {
+  const out: string[] = ["# Notes"];
+  for (let i = 0; i < lines; i++) {
+    if (i % 80 === 0) out.push("```ts");
+    if (i % 80 === 40) out.push("```");
+    if (markerEvery > 0 && i % markerEvery === 0) out.push(`LLM summarize section ${i}`);
+    else out.push(`Regular prose line ${i} with enough text to be realistic.`);
+  }
+  return out.join("\n");
+}
+
+function makePaths(count: number): string[] {
+  const exts = ["ts", "tsx", "rs", "java", "md", "png", "lock"];
+  const dirs = ["src", "test", "node_modules/pkg", "target/debug", "research/pages", "docs"];
+  return Array.from({ length: count }, (_, i) => `${dirs[i % dirs.length]}/file-${i}.${exts[i % exts.length]}`);
+}

package/__bench__/benchstat.txt

@@ -0,0 +1,8 @@
+                    │ __bench__/baseline.txt │        __bench__/optimized.txt        │
+                    │         sec/op         │    sec/op     vs base                 │
+ParseNoMarkers                  73.71µ ± ∞ ¹   57.10µ ± ∞ ¹        ~ (p=0.333 n=1+5)
+ParseSomeMarkers                82.60µ ± ∞ ¹   70.85µ ± ∞ ¹        ~ (p=0.333 n=1+5)
+ParseMarkdownFences            110.88µ ± ∞ ¹   80.38µ ± ∞ ¹        ~ (p=0.333 n=1+5)
+PathFilterCompiled             3227.5µ ± ∞ ¹   763.7µ ± ∞ ¹        ~ (p=0.333 n=1+5)
+geomean                         216.1µ         125.5µ        -41.90%
+¹ need >= 6 samples for confidence interval at level 0.95

package/__bench__/optimized.txt

@@ -0,0 +1,20 @@
+BenchmarkParseNoMarkers 4000 57699 ns/op
+BenchmarkParseSomeMarkers 4000 69163 ns/op
+BenchmarkParseMarkdownFences 4000 80377 ns/op
+BenchmarkPathFilterCompiled 2000 797186 ns/op
+BenchmarkParseNoMarkers 4000 59416 ns/op
+BenchmarkParseSomeMarkers 4000 70846 ns/op
+BenchmarkParseMarkdownFences 4000 83867 ns/op
+BenchmarkPathFilterCompiled 2000 763720 ns/op
+BenchmarkParseNoMarkers 4000 56519 ns/op
+BenchmarkParseSomeMarkers 4000 67986 ns/op
+BenchmarkParseMarkdownFences 4000 78726 ns/op
+BenchmarkPathFilterCompiled 2000 750411 ns/op
+BenchmarkParseNoMarkers 4000 55438 ns/op
+BenchmarkParseSomeMarkers 4000 76997 ns/op
+BenchmarkParseMarkdownFences 4000 90038 ns/op
+BenchmarkPathFilterCompiled 2000 761932 ns/op
+BenchmarkParseNoMarkers 4000 57098 ns/op
+BenchmarkParseSomeMarkers 4000 71594 ns/op
+BenchmarkParseMarkdownFences 4000 79348 ns/op
+BenchmarkPathFilterCompiled 2000 763887 ns/op

package/__tests__/__snapshots__/core.test.ts.snap

@@ -0,0 +1,17 @@
+// Bun Snapshot v1, https://bun.sh/docs/test/snapshots
+
+exports[`llmiterate output snapshots agent prompt snapshot 1`] = `
+"llmiterate request from @a.rs:1
+
+Prompt marker contents:
+\`\`\`text
+implement foo
+\`\`\`
+
+Instructions:
+- Work in/around @a.rs.
+- Marker span to replace: a.rs:1-1.
+- Treat the marker line(s) as an inline prompt/TODO, not program code.
+- Replace the whole marker span with the requested implementation or code change.
+- Do not leave the marker line(s) behind unless impossible; explain if impossible."
+`;

package/__tests__/__snapshots__/ui.test.ts.snap

@@ -0,0 +1,15 @@
+// Bun Snapshot v1, https://bun.sh/docs/test/snapshots
+
+exports[`llmiterate UI widget empty snapshot 1`] = `
+"╭ llmiterate ──────────────────────────────────────────────╮
+│no prompts queued yet                                     │
+╰──────────────────────────────────────────────────────────╯"
+`;
+
+exports[`llmiterate UI widget run snapshot 1`] = `
+"╭ llmiterate ──────────────────────────────────────────────────────────────────╮
+│● src/main.ts:1 LLM implement foo and bar                                     │
+│  running edit                                                                │
+│  I am editing the file now and will run tests afterwards.                    │
+╰──────────────────────────────────────────────────────────────────────────────╯"
+`;

package/__tests__/core.test.ts

@@ -0,0 +1,268 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, test } from "bun:test";
+import {
+  buildAgentPrompt,
+  compilePathFilter,
+  defaultConfig,
+  emptyState,
+  globToRegExp,
+  isExcludedPath,
+  hashProjectRoot,
+  loadState,
+  normalizeConfig,
+  parseMarkerPrompts,
+  platformStateDir,
+  projectStoreDir,
+  previewText,
+  saveState,
+  STATE_FILE,
+  shouldIncludeCompiledPath,
+  shouldIncludePath,
+  shouldWatchDirectory,
+  toSlash,
+} from "../core";
+
+const tempDirs: string[] = [];
+
+afterEach(() => {
+  while (tempDirs.length) rmSync(tempDirs.pop()!, { recursive: true, force: true });
+});
+
+function tempDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), "llmiterate-core-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+describe("llmiterate parser", () => {
+  test("parses marker as first word on line", () => {
+    const blocks = parseMarkerPrompts("Main.java", [
+      "void main(final String[] a) {",
+      "  LLM some prompt text",
+      "  if (a.length == 0)",
+      "    LLM deal with this",
+      "}",
+    ].join("\n"));
+
+    expect(blocks).toHaveLength(2);
+    expect(blocks[0]).toMatchObject({ marker: "LLM", startLine: 2, endLine: 2, prompt: "some prompt text" });
+    expect(blocks[1]).toMatchObject({ marker: "LLM", startLine: 4, endLine: 4, prompt: "deal with this" });
+  });
+
+  test("groups consecutive marker lines with same marker", () => {
+    const blocks = parseMarkerPrompts("Main.java", [
+      "  LLM open ui",
+      "  LLM and then fix perf",
+      "  run();",
+    ].join("\n"));
+
+    expect(blocks).toHaveLength(1);
+    expect(blocks[0]).toMatchObject({ startLine: 1, endLine: 2, prompt: "open ui\nand then fix perf" });
+  });
+
+  test("does not group different markers", () => {
+    const blocks = parseMarkerPrompts("a.ts", "LLM first\nPROMPT second\nLLM third");
+    expect(blocks.map((b) => b.prompt)).toEqual(["first", "second", "third"]);
+    expect(blocks.map((b) => b.startLine)).toEqual([1, 2, 3]);
+  });
+
+  test("does not strip comments unless configured marker includes comment", () => {
+    expect(parseMarkerPrompts("src/lib.rs", "  // LLM implement knapsack algo")).toHaveLength(0);
+
+    const blocks = parseMarkerPrompts("src/lib.rs", "  //LLM implement knapsack algo", ["//LLM"]);
+    expect(blocks).toHaveLength(1);
+    expect(blocks[0]).toMatchObject({ marker: "//LLM", prompt: "implement knapsack algo" });
+  });
+
+  test("supports markers containing spaces", () => {
+    const blocks = parseMarkerPrompts("a.rs", "  /// LLM add tests", ["/// LLM"]);
+    expect(blocks).toHaveLength(1);
+    expect(blocks[0]).toMatchObject({ marker: "/// LLM", prompt: "add tests" });
+  });
+
+  test("sorts overlapping markers longest-first", () => {
+    const [block] = parseMarkerPrompts("a.rs", "/// LLM add tests", ["LLM", "/// LLM"]);
+    expect(block).toMatchObject({ marker: "/// LLM", prompt: "add tests" });
+  });
+
+  test("supports PROMPT marker too", () => {
+    const blocks = parseMarkerPrompts("a.ts", "PROMPT add tests");
+    expect(blocks).toHaveLength(1);
+    expect(blocks[0]).toMatchObject({ marker: "PROMPT", prompt: "add tests" });
+  });
+
+  test("marker must be first word", () => {
+    expect(parseMarkerPrompts("a.md", "some LLM receives message history")).toHaveLength(0);
+    expect(parseMarkerPrompts("a.ts", "xLLM implement foo")).toHaveLength(0);
+    expect(parseMarkerPrompts("a.ts", "LLMish implement foo")).toHaveLength(0);
+  });
+
+  test("ignores empty marker lines", () => {
+    expect(parseMarkerPrompts("a.ts", "LLM\nPROMPT   ")).toHaveLength(0);
+  });
+
+  test("ignores enum/string assignment false positives", () => {
+    expect(parseMarkerPrompts("node.d.ts", 'PROMPT = "PROMPT",')).toHaveLength(0);
+  });
+
+  test("does not parse old colon or brace syntax", () => {
+    expect(parseMarkerPrompts("a.ts", "// PROMPT: do thing")).toHaveLength(0);
+    expect(parseMarkerPrompts("a.ts", "// PROMPT{{\n// do thing\n// }}")).toHaveLength(0);
+  });
+
+  test("ignores Markdown fenced code blocks", () => {
+    const blocks = parseMarkerPrompts("notes.md", [
+      "# docs",
+      "```ts",
+      "LLM fake inside fence",
+      "```",
+      "LLM real outside fence",
+      "~~~",
+      "PROMPT fake tilde fence",
+      "~~~",
+    ].join("\n"));
+
+    expect(blocks).toHaveLength(1);
+    expect(blocks[0]).toMatchObject({ startLine: 5, prompt: "real outside fence" });
+  });
+
+  test("normalizes CRLF and CR line endings", () => {
+    expect(parseMarkerPrompts("a.ts", "LLM one\r\nLLM two")[0]!.prompt).toBe("one\ntwo");
+    expect(parseMarkerPrompts("a.ts", "LLM one\rLLM two")[0]!.prompt).toBe("one\ntwo");
+  });
+});
+
+describe("llmiterate config/state/path helpers", () => {
+  test("defaults to watching nothing", () => {
+    const config = defaultConfig();
+    const filter = compilePathFilter(config);
+    expect(config.include).toEqual([]);
+    expect(shouldWatchDirectory("", filter)).toBe(false);
+    expect(shouldIncludeCompiledPath("src/a.ts", filter)).toBe(false);
+  });
+
+  test("normalizes valid partial config and rejects invalid values", () => {
+    const config = normalizeConfig({
+      enabled: false,
+      include: ["src/**/*.ts"],
+      exclude: ["tmp/**"],
+      debounceMs: 12.8,
+      maxFileBytes: 42,
+      markers: ["//LLM", "bad\nmarker", "  PROMPT  "],
+    });
+
+    expect(config).toMatchObject({
+      enabled: false,
+      include: ["src/**/*.ts"],
+      exclude: ["tmp/**"],
+      debounceMs: 12,
+      maxFileBytes: 42,
+      markers: ["//LLM", "PROMPT"],
+    });
+
+    const fallback = defaultConfig();
+    expect(normalizeConfig({ include: [""] })).toMatchObject({
+      include: fallback.include,
+    });
+  });
+
+  test("uses platform state dir for project stores", () => {
+    const oldXdg = process.env.XDG_STATE_HOME;
+    const stateRoot = tempDir();
+    process.env.XDG_STATE_HOME = stateRoot;
+    try {
+      const root = "/tmp/project";
+      expect(platformStateDir()).toBe(join(stateRoot, "pi"));
+      expect(projectStoreDir(root)).toBe(join(stateRoot, "pi", "llmiterate", hashProjectRoot(root)));
+    } finally {
+      if (oldXdg === undefined) delete process.env.XDG_STATE_HOME;
+      else process.env.XDG_STATE_HOME = oldXdg;
+    }
+  });
+
+  test("platformStateDir uses native conventions", () => {
+    expect(platformStateDir("linux", {}, "/home/me")).toBe("/home/me/.local/state/pi");
+    expect(platformStateDir("linux", { XDG_STATE_HOME: "/state" }, "/home/me")).toBe("/state/pi");
+    expect(platformStateDir("darwin", {}, "/Users/me")).toBe("/Users/me/Library/Application Support/pi");
+    expect(platformStateDir("win32", { LOCALAPPDATA: "C:\\Users\\me\\AppData\\Local" }, "C:\\Users\\me"))
+      .toBe("C:\\Users\\me\\AppData\\Local\\pi");
+    expect(platformStateDir("win32", {}, "C:\\Users\\me"))
+      .toBe("C:\\Users\\me\\AppData\\Local\\pi");
+  });
+
+  test("saves and loads state, invalid state falls back empty", () => {
+    const storeDir = tempDir();
+    const state = emptyState();
+    state.processed["a.ts:1:hash"] = {
+      file: "a.ts",
+      startLine: 1,
+      endLine: 1,
+      promptHash: "hash",
+      promptPreview: "preview",
+      queuedAt: 123,
+    };
+
+    saveState(storeDir, state);
+    expect(loadState(storeDir)).toEqual(state);
+    expect(readFileSync(join(storeDir, STATE_FILE), "utf-8")).toEndWith("\n");
+
+    writeFileSync(join(storeDir, STATE_FILE), JSON.stringify({
+      version: 1,
+      processed: {
+        good: state.processed["a.ts:1:hash"],
+        bad: { file: "missing required fields" },
+      },
+    }));
+    expect(loadState(storeDir).processed).toEqual({ good: state.processed["a.ts:1:hash"] });
+    rmSync(join(storeDir, STATE_FILE));
+    expect(loadState(storeDir)).toEqual(emptyState());
+  });
+
+  test("glob supports globstar, brace alternatives, and excludes", () => {
+    const re = globToRegExp("**/*.{ts,rs}");
+    expect(re.test("index.ts")).toBe(true);
+    expect(re.test("src/lib.rs")).toBe(true);
+    expect(re.test("src/lib.java")).toBe(false);
+
+    const filter = compilePathFilter({ include: ["**/*.{ts,rs}"], exclude: ["node_modules/**", "packages/pkg/dist/**"] });
+    expect(shouldIncludeCompiledPath("src/lib.rs", filter)).toBe(true);
+    expect(shouldIncludePath("node_modules/x.ts", filter)).toBe(false);
+    expect(isExcludedPath("node_modules/x.ts", filter)).toBe(true);
+    expect(isExcludedPath("packages/pkg/dist/x.ts", filter)).toBe(true);
+
+    const defaults = compilePathFilter(defaultConfig());
+    expect(shouldIncludeCompiledPath("extensions/devil/node_modules/pkg/index.ts", defaults)).toBe(false);
+  });
+
+  test("directory watch traversal is include-whitelisted with exclude veto", () => {
+    const filter = compilePathFilter({ include: ["src/**/*.ts", "docs/*.md"], exclude: ["src/generated/**"] });
+    expect(shouldWatchDirectory("", filter)).toBe(true);
+    expect(shouldWatchDirectory("src", filter)).toBe(true);
+    expect(shouldWatchDirectory("src/feature", filter)).toBe(true);
+    expect(shouldWatchDirectory("docs", filter)).toBe(true);
+    expect(shouldWatchDirectory("research", filter)).toBe(false);
+    expect(shouldWatchDirectory("docs/deep", filter)).toBe(false);
+    expect(shouldWatchDirectory("src/generated", filter)).toBe(false);
+  });
+
+  test("globstar include watches all directories unless excluded", () => {
+    const filter = compilePathFilter({ include: ["**/*.ts"], exclude: ["node_modules/**"] });
+    expect(shouldWatchDirectory("any/depth", filter)).toBe(true);
+    expect(shouldWatchDirectory("node_modules", filter)).toBe(false);
+  });
+
+  test("toSlash and previewText are allocation-aware utility behavior", () => {
+    expect(toSlash("a/b/c")).toBe("a/b/c");
+    expect(toSlash("a\\b\\c")).toBe("a/b/c");
+    expect(previewText(" one\n two\tthree ", 9)).toBe("one two …");
+  });
+});
+
+describe("llmiterate output snapshots", () => {
+  test("agent prompt snapshot", () => {
+    const [block] = parseMarkerPrompts("a.rs", "LLM implement foo");
+    expect(buildAgentPrompt(block!)).toMatchSnapshot();
+  });
+});