pi-background-run 0.4.0 → 0.5.0

package/extension/index.ts

@@ -34,17 +34,19 @@ import { Type } from "typebox";
 import { Box, Text } from "@earendil-works/pi-tui";
 import { spawn } from "node:child_process";
 import {
-  openSync,
+  appendFileSync,
   closeSync,
-  readFileSync,
+  existsSync,
   mkdirSync,
+  openSync,
+  readFileSync,
   readdirSync,
   renameSync,
-  unlinkSync,
   statSync,
+  unlinkSync,
   writeFileSync,
 } from "node:fs";
-import { join } from "node:path";
+import { dirname, isAbsolute, join, relative, sep } from "node:path";
 import { homedir } from "node:os";
 
 // Exit marker appended to every log so the file is self-describing: the exit
@@ -54,6 +56,14 @@ const EXIT_MARKER = "__BGRUN_EXIT__=";
 
 const DEFAULT_CLEANUP_DAYS = 7;
 const STALE_POLL_MS = 30_000; // re-check interval for jobs with no live child handle
+const GLOBAL_JOBS_DIR = join(homedir(), ".pi-bgrun", "jobs");
+
+// Default regex for bggrep when the caller passes no pattern: common failure
+// signatures across test runners and build tools. ONLY a convenience default —
+// bggrep's contract is that the caller's own pattern always wins, because a
+// generic default on arbitrary tools/languages misses more than it catches.
+export const DEFAULT_GREP_PATTERN =
+  "--- FAIL:|^FAIL\\b|^panic:|fatal error:|AssertionError|Error:|error:|make: \\*\\*\\*.*Error|✗|✖";
 
 // ── Configuration ───────────────────────────────────────────────────────────
 //
@@ -66,6 +76,10 @@ const STALE_POLL_MS = 30_000; // re-check interval for jobs with no live child h
 
 interface BgrunConfig {
   jobsDir: string;
+  // True when jobsDir came from a RELATIVE path resolved against the project
+  // root (project-local logs). Only then does bgrun auto-ignore the dir in
+  // .git/info/exclude — an absolute dir is the user's explicit choice.
+  jobsDirProjectLocal: boolean;
   // Adopt other sessions' running jobs (found in the shared jobs dir) into
   // this session's widget and job list. Default false — most sessions don't
   // want unrelated jobs from other projects cluttering the widget.
@@ -112,6 +126,111 @@ function readConfigFile(path: string): BgrunConfigFile {
   return {};
 }
 
+// ── Project-local jobs dir ──────────────────────────────────────────────────
+//
+// A RELATIVE `jobsDir` (from any config layer, or PI_BGRUN_DIR) opts into
+// project-local logs: it resolves against the session's project root, so logs
+// land inside the workspace. That keeps them within the project sandbox —
+// analysis tools confined to the project root (e.g. context-mode's
+// ctx_execute_file/ctx_index) can then process whole logs without flooding
+// context. Absolute paths behave exactly as in older versions
+// (migration-safe), and with no recognizable project root a relative path
+// falls back to the global dir instead of scattering logs across whatever
+// directory pi happened to start in.
+
+function isProjectRootLike(dir: string): boolean {
+  // Cheap heuristic: a directory holding .git or pi's config dir is a project.
+  return (
+    existsSync(join(dir, ".git")) || existsSync(join(dir, CONFIG_DIR_NAME))
+  );
+}
+
+export function resolveJobsDirPath(
+  raw: string | undefined,
+  ctx?: { cwd?: string },
+): { dir: string; projectLocal: boolean } {
+  if (!raw) return { dir: GLOBAL_JOBS_DIR, projectLocal: false };
+  if (isAbsolute(raw)) return { dir: raw, projectLocal: false };
+  const root = ctx?.cwd ?? process.cwd();
+  if (!root || !isProjectRootLike(root)) {
+    return { dir: GLOBAL_JOBS_DIR, projectLocal: false };
+  }
+  return { dir: join(root, raw), projectLocal: true };
+}
+
+// Auto-ignore a project-local jobs dir in git so logs never pollute
+// `git status`: appends the dir pattern to the enclosing repo's
+// .git/info/exclude (local-only — the tracked .gitignore is never touched).
+// Memoized only on SUCCESS — a transient failure (unwritable exclude file,
+// .git appearing later) is retried on the next bgrun. Every step is
+// best-effort and must never fail a bgrun.
+const gitExcludedDirs = new Set<string>();
+
+// Returns true when the dir is settled (pattern written, already present, or
+// legitimately nothing to do — no repo above, dir is the repo root itself).
+// False only on failure, so the caller retries next time.
+export function ensureGitExcluded(jobsDir: string): boolean {
+  if (gitExcludedDirs.has(jobsDir)) return true;
+  if (tryEnsureGitExcluded(jobsDir)) {
+    gitExcludedDirs.add(jobsDir);
+    return true;
+  }
+  return false;
+}
+
+function tryEnsureGitExcluded(jobsDir: string): boolean {
+  try {
+    // Walk up from jobsDir to the enclosing work tree.
+    let cur = jobsDir;
+    for (;;) {
+      const dot = join(cur, ".git");
+      if (existsSync(dot)) return appendExcludePattern(cur, dot, jobsDir);
+      const parent = dirname(cur);
+      if (parent === cur) return true; // filesystem root — no repo above; nothing to do
+      cur = parent;
+    }
+  } catch {
+    // best-effort — ignore hygiene must never break job creation
+    return false;
+  }
+}
+
+function appendExcludePattern(
+  repoRoot: string,
+  dotGit: string,
+  jobsDir: string,
+): boolean {
+  if (jobsDir === repoRoot) return true; // can't exclude the whole repo; nothing to do
+  // `.git` is a directory in a normal checkout, or a file pointing at the
+  // real git dir in linked worktrees (git worktree add) and submodules.
+  let gitDir = dotGit;
+  if (statSync(dotGit).isFile()) {
+    const m = readFileSync(dotGit, "utf8").match(/^gitdir:\s*(.+)$/m);
+    if (!m) return false; // unparseable .git file — retry later
+    gitDir = m[1].trim();
+  }
+  const rel = relative(repoRoot, jobsDir);
+  // Defense-in-depth: the walk-up guarantees jobsDir sits under repoRoot, but
+  // a future caller or symlinked path could break that — ../-prefixed
+  // patterns are silently useless in gitignore semantics, so skip them.
+  if (rel.startsWith("..") || isAbsolute(rel)) return true;
+  const pattern = rel.split(sep).join("/") + "/";
+  const excludePath = join(gitDir, "info", "exclude");
+  let existing = "";
+  try {
+    existing = readFileSync(excludePath, "utf8");
+  } catch {
+    // no exclude file yet — we'll create it
+  }
+  if (existing.split("\n").some((l) => l.trim() === pattern)) return true;
+  mkdirSync(join(gitDir, "info"), { recursive: true });
+  appendFileSync(
+    excludePath,
+    `\n# pi-bgrun job logs (auto-added)\n${pattern}\n`,
+  );
+  return true;
+}
+
 // Resolved per call (cheap: at most two small file reads) so env/config
 // changes are picked up without module reloads — and tests can isolate.
 function resolveConfig(ctx?: {
@@ -154,11 +273,11 @@ function resolveConfig(ctx?: {
       : undefined;
   const envDays = Number(process.env.PI_BGRUN_CLEANUP_DAYS);
   const daysEnv = Number.isFinite(envDays) && envDays > 0 ? envDays : undefined;
+  const { dir: jobsDir, projectLocal: jobsDirProjectLocal } =
+    resolveJobsDirPath(process.env.PI_BGRUN_DIR || dirFile, ctx);
   return {
-    jobsDir:
-      process.env.PI_BGRUN_DIR ||
-      dirFile ||
-      join(homedir(), ".pi-bgrun", "jobs"),
+    jobsDir,
+    jobsDirProjectLocal,
     adoptForeignJobs:
       parseBoolEnv(process.env.PI_BGRUN_FOREIGN_JOBS) ?? foreignFile ?? false,
     showCompletedJobs:
@@ -711,7 +830,7 @@ export default function (pi: ExtensionAPI) {
       "Use bgrun (not bash) for any command expected to run >30s or emit >100 lines — tests, builds, linters.",
       "Give every bgrun job a short name (e.g. name: 'unit-tests') so it's recognizable in status output, the status widget, and wake messages.",
       "After bgrun returns a job id, continue other work; you will be woken automatically when it finishes.",
-      "Never cat or Read a full bgrun log — bgtail returns a condensed peek (ANSI stripped, repeats collapsed, ~8KB cap); use ctx_execute_file on the log path only when the condensed tail is insufficient.",
+      "Never cat or Read a full bgrun log — bgtail returns a condensed peek (ANSI stripped, repeats collapsed, ~8KB cap); use bggrep for pattern search or ctx_execute_file on the log path for whole-log analysis.",
     ],
     parameters: Type.Object({
       command: Type.String({
@@ -733,7 +852,11 @@ export default function (pi: ExtensionAPI) {
       }
       const name = sanitizeName(rawName);
 
-      const jobsDir = resolveConfig(ctx).jobsDir;
+      const cfg = resolveConfig(ctx);
+      // Project-local logs are auto-ignored in .git/info/exclude (best-effort)
+      // so they never pollute `git status`. Absolute dirs are left untouched.
+      if (cfg.jobsDirProjectLocal) ensureGitExcluded(cfg.jobsDir);
+      const jobsDir = cfg.jobsDir;
       mkdirSync(jobsDir, { recursive: true });
 
       const slug = makeSlug(name ?? command);
@@ -948,7 +1071,22 @@ export default function (pi: ExtensionAPI) {
     return { text: out.join("\n"), truncated: notes };
   }
 
-  // ── bgtail: read last N lines of a job's log, condensed for context ────────
+  // ── bgtail: read the newest lines of a job's log, condensed for context ────
+  //
+  // Delta tailing: each read bookmarks the total raw line count at read time
+  // (the high-water mark of what the caller has had the opportunity to see).
+  // The FIRST read for a job returns the full last-N tail; repeat reads return
+  // only lines appended since, so polling a running job never re-pays context
+  // for lines already seen. Deliberately-skipped prefix lines are never
+  // replayed as "new". raw: true keeps the verbatim last-N window (no delta
+  // header) but still advances the bookmark. A shrunken log (rotated/replaced)
+  // resets to a full tail. Bookmarks are in-memory only — a session restart
+  // starts fresh with a full tail.
+
+  const tailBookmarks = new Map<
+    string,
+    { lines: number; bytes: number; first: string }
+  >();
 
   // Shared by the bgtail tool (agent-facing) and the /bgtail slash command
   // (human-facing).
@@ -960,25 +1098,101 @@ export default function (pi: ExtensionAPI) {
     details: Record<string, unknown>;
     isError?: boolean;
   }> {
-    const { id, lines = 40, raw = false } = params;
+    const { id, lines: linesParam = 40, raw = false } = params;
+    // Clamp defensively — direct callers (e.g. the slash command) bypass the
+    // tool schema, and lines < 1 would corrupt slicing (slice(-0) = whole log).
+    const lines = Math.max(1, Math.floor(linesParam));
     if (!id) throw new Error("bgtail: id is required");
-    const logPath = join(resolveConfig(ctx).jobsDir, `${id}.log`);
+    // Prefer this session's record: its logPath stays correct even if the
+    // config (and thus the resolved jobs dir) changes mid-session — e.g. a
+    // user switching to project-local logs right after upgrading.
+    const logPath =
+      jobs.get(id)?.logPath ?? join(resolveConfig(ctx).jobsDir, `${id}.log`);
     try {
       const content = readFileSync(logPath, "utf8");
-      const all = content
-        .split("\n")
+      // Content lines only: the exit marker and blanks are filtered BEFORE the
+      // window is sliced, so "last N lines" means the last N content lines
+      // (matching pre-delta behavior) and bookmarks count content lines.
+      // /\r?\n/ keeps CRLF logs from leaving a stray \r on every line.
+      const rawLines = content
+        .split(/\r?\n/)
         .filter((l) => !l.startsWith(EXIT_MARKER) && l.trim().length > 0);
-      const tail = all.slice(-lines);
-      const { text, truncated } = condenseLogLines(tail, { raw });
+      const total = rawLines.length;
+      const first = rawLines[0]?.slice(0, 200) ?? "";
+      const prev = tailBookmarks.get(id);
+      // Append-only logs never mutate earlier lines, so a changed first
+      // content line means the log was replaced or rotated — reset to a full
+      // tail. Catches same-size replacements the shrink checks cannot see.
+      // (A previously-empty log growing content is growth, not replacement.)
+      const replaced =
+        prev !== undefined && prev.lines > 0 && prev.first !== first;
+      const shrank =
+        prev !== undefined &&
+        (prev.lines > total || prev.bytes > content.length);
+      let window: string[];
+      let header: string | undefined;
+      let newLines: number | undefined;
+      if (raw || prev === undefined || shrank || replaced) {
+        // Full tail: first read, raw mode, or a shrunken/replaced log (reset).
+        window = rawLines.slice(-lines);
+        if (!raw && (shrank || replaced)) {
+          header = shrank
+            ? "log shrank since last read — showing full tail"
+            : "log was replaced since last read — showing full tail";
+        }
+      } else {
+        const fresh = rawLines.slice(prev.lines);
+        newLines = fresh.length;
+        if (fresh.length === 0) {
+          tailBookmarks.set(id, {
+            lines: total,
+            bytes: content.length,
+            first,
+          });
+          return {
+            content: [
+              {
+                type: "text",
+                text: `(no new lines since last read — log at ${total} line${total === 1 ? "" : "s"})`,
+              },
+            ],
+            details: {
+              id,
+              linesShown: 0,
+              logPath,
+              notFound: false,
+              condensed: true,
+              newLines: 0,
+              totalLines: total,
+            },
+          };
+        }
+        window = fresh.length > lines ? fresh.slice(-lines) : fresh;
+        header =
+          `+${fresh.length} new line${fresh.length === 1 ? "" : "s"} since last read — ` +
+          `log at ${total} lines${fresh.length > lines ? ` (showing last ${lines})` : ""}`;
+      }
+      tailBookmarks.set(id, {
+        lines: total,
+        bytes: content.length,
+        first,
+      });
+      const shown = window;
+      const { text, truncated } = condenseLogLines(shown, { raw });
+      // Delta reads early-return above, so an empty window here can only be
+      // a first read of an empty log (full-tail path).
+      const body = shown.length === 0 ? "(empty log)" : text;
       const notes = truncated.length > 0 ? `\n\n(${truncated.join("; ")})` : "";
+      const head = header ? `${header}\n` : "";
       return {
-        content: [{ type: "text", text: text + notes || "(empty log)" }],
+        content: [{ type: "text", text: head + body + notes }],
         details: {
           id,
-          linesShown: tail.length,
+          linesShown: shown.length,
           logPath,
           notFound: false,
           condensed: !raw,
+          ...(newLines === undefined ? {} : { newLines, totalLines: total }),
           ...(truncated.length > 0 ? { condenserNotes: truncated } : {}),
         },
       };
@@ -997,14 +1211,17 @@ export default function (pi: ExtensionAPI) {
     name: "bgtail",
     label: "Tail Background Log",
     description:
-      "Print the last N lines of a background job's log (default 40), condensed for context: ANSI escapes stripped, repeated lines collapsed, long lines truncated, output capped (~8KB). Strips the exit-marker line. Pass raw: true for unprocessed output; use ctx_execute_file on the log path for whole-log failure analysis.",
+      "Read the newest lines of a background job's log, condensed for context: ANSI escapes stripped, repeated lines collapsed, long lines truncated, output capped (~8KB). Strips the exit-marker line. The first read returns the last N lines (default 40); REPEAT reads return only lines appended since your last read (delta tailing) — polling a running job never re-pays for the same lines. raw: true returns the unprocessed last-N window. A shrunken or replaced log resets to a full tail. For pattern search use bggrep; for whole-log analysis, ctx_execute_file on the log path.",
     promptSnippet: "Read the last N lines of a bgrun job's log",
     parameters: Type.Object({
       id: Type.String({
         description: "Job id (from bgrun's 'started: <id>' response)",
       }),
       lines: Type.Optional(
-        Type.Number({ description: "Number of lines to show (default 40)" }),
+        Type.Number({
+          description: "Number of lines to show (default 40)",
+          minimum: 1,
+        }),
       ),
       raw: Type.Optional(
         Type.Boolean({
@@ -1018,6 +1235,152 @@ export default function (pi: ExtensionAPI) {
     },
   });
 
+  // ── bggrep: pattern search over a job's log, capped for context ───────────
+  //
+  // The sandboxed whole-log path (ctx_execute_file) is confined to the
+  // project root, which a global jobs dir sits outside of — bggrep runs
+  // inside the extension with native fs access, so it works on any
+  // configured jobs dir. Matches are line-numbered (grep -n style),
+  // optionally with context lines, capped at MAX_GREP_MATCHES, and run
+  // through the same condenser as bgtail so a search can never flood context.
+
+  const MAX_GREP_MATCHES = 50;
+
+  async function bggrepCore(
+    params: { id: string; pattern?: string; context?: number },
+    ctx?: ExtensionContext,
+  ): Promise<{
+    content: { type: "text"; text: string }[];
+    details: Record<string, unknown>;
+    isError?: boolean;
+  }> {
+    const { id, pattern, context: contextParam = 0 } = params;
+    // Clamp defensively — negative context would exclude the match lines
+    // themselves from the context windows (lo > hi no-ops the inner loop).
+    const context = Math.max(0, Math.floor(contextParam));
+    if (!id) throw new Error("bggrep: id is required");
+    // Record-first, same as bgtail — correct across config changes.
+    const logPath =
+      jobs.get(id)?.logPath ?? join(resolveConfig(ctx).jobsDir, `${id}.log`);
+    const source = pattern ?? DEFAULT_GREP_PATTERN;
+    let re: RegExp;
+    try {
+      re = new RegExp(source);
+    } catch (err) {
+      throw new Error(
+        `bggrep: invalid pattern ${JSON.stringify(source)}: ${(err as Error).message}`,
+      );
+    }
+    let rawLines: string[];
+    try {
+      const content = readFileSync(logPath, "utf8");
+      // /\r?\n/ normalizes CRLF (a trailing \r would break $-anchored patterns
+      // and leak into output); blank lines are KEPT so L<n> numbers match the
+      // file. A trailing empty split element is dropped; "" yields zero lines.
+      const split = content === "" ? [] : content.split(/\r?\n/);
+      if (split.length > 0 && split[split.length - 1] === "") split.pop();
+      rawLines = split.filter((l) => !l.startsWith(EXIT_MARKER));
+    } catch {
+      return {
+        content: [
+          { type: "text", text: `No log found for job ${id} at ${logPath}` },
+        ],
+        details: { id, matches: 0, logPath, notFound: true },
+        isError: true,
+      };
+    }
+    const matchIdx: number[] = [];
+    for (let i = 0; i < rawLines.length; i++) {
+      if (re.test(rawLines[i])) matchIdx.push(i);
+    }
+    const header =
+      `${matchIdx.length} match${matchIdx.length === 1 ? "" : "es"} for /${source}/ ` +
+      `in ${rawLines.length} line${rawLines.length === 1 ? "" : "s"}`;
+    if (matchIdx.length === 0) {
+      return {
+        content: [{ type: "text", text: `${header} — none` }],
+        details: {
+          id,
+          matches: 0,
+          linesSearched: rawLines.length,
+          logPath,
+          notFound: false,
+        },
+      };
+    }
+    const capped = matchIdx.length > MAX_GREP_MATCHES;
+    const shownIdx = capped ? matchIdx.slice(0, MAX_GREP_MATCHES) : matchIdx;
+    // Context windows, merged where they overlap or touch (grep -C style).
+    const include = new Set<number>();
+    for (const i of shownIdx) {
+      const lo = Math.max(0, i - context);
+      const hi = Math.min(rawLines.length - 1, i + context);
+      for (let j = lo; j <= hi; j++) include.add(j);
+    }
+    const sorted = [...include].sort((a, b) => a - b);
+    const out: string[] = [];
+    let prev = -2;
+    for (const i of sorted) {
+      if (prev >= 0 && i > prev + 1) {
+        const gap = i - prev - 1;
+        out.push(`…[${gap} line${gap === 1 ? "" : "s"} skipped]…`);
+      }
+      out.push(`L${i + 1}: ${rawLines[i]}`);
+      prev = i;
+    }
+    const { text, truncated } = condenseLogLines(out);
+    const notes = truncated.length > 0 ? `\n\n(${truncated.join("; ")})` : "";
+    const capNote = capped
+      ? ` — showing first ${MAX_GREP_MATCHES}; ${matchIdx.length - MAX_GREP_MATCHES} more not shown`
+      : "";
+    return {
+      content: [{ type: "text", text: `${header}${capNote}\n${text}${notes}` }],
+      details: {
+        id,
+        matches: matchIdx.length,
+        linesSearched: rawLines.length,
+        logPath,
+        notFound: false,
+        pattern: source,
+        capped,
+      },
+    };
+  }
+
+  pi.registerTool({
+    name: "bggrep",
+    label: "Grep Background Log",
+    description:
+      "Search a background job's log with a regex; returns only matching lines with line numbers (optional context lines), capped (~50 matches, ~8KB) and condensed. Runs inside the extension, so it works on any jobs dir — including global logs that project-sandboxed tools (ctx_execute_file) cannot reach. Pass your own pattern whenever you know the log's format; with no pattern a generic failure-signature default is used (a convenience only — not a guarantee).",
+    promptSnippet: "Search a bgrun job's log for a pattern",
+    promptGuidelines: [
+      "Never search a bgrun log with the bash tool — uncapped output can flood context, and it needs manual log-path reconstruction and regex shell-quoting; bggrep is bounded by design.",
+      "Prefer bggrep over bash grep or reading a bgrun log — matches are line-numbered, capped, and condensed.",
+      "Pass an explicit pattern when you know the tool's output format; the default only catches common failure signatures.",
+    ],
+    parameters: Type.Object({
+      id: Type.String({
+        description: "Job id (from bgrun's 'started: <id>' response)",
+      }),
+      pattern: Type.Optional(
+        Type.String({
+          description:
+            "Regex to search for. Default: generic failure signatures — override when you know the format.",
+        }),
+      ),
+      context: Type.Optional(
+        Type.Number({
+          description:
+            "Context lines around each match (default 0, grep -C style)",
+          minimum: 0,
+        }),
+      ),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      return bggrepCore(params, ctx);
+    },
+  });
+
   // ── bgstatus: list jobs (in-memory while alive; dir scan after restart) ─────
 
   // Shared by the bgstatus tool (agent-facing) and the /bgstatus slash command

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-background-run",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Run long shell commands detached in the background for pi; get woken on completion. Output lands in a file; context stays clean.",
   "type": "module",
   "license": "MIT",

package/skill/run-bg/SKILL.md

@@ -30,7 +30,8 @@ no polling.
 |---|---|
 | Start  | `bgrun(command: "make test-short", name: "unit-tests")` → `started: <job-id>` (name is an optional short label; use it so jobs are recognizable in `bgstatus`, the status widget, and wake messages) |
 | Status | `bgstatus(<job-id>)` for one job, or `bgstatus()` for this session's running jobs — finished jobs are hidden by default; pass `includeDone: true` to list them |
-| Tail   | `bgtail(<job-id>, 40)` |
+| Tail   | `bgtail(<job-id>, 40)` — first read: last-40 tail; later reads: only lines appended since (delta tailing) |
+| Grep   | `bggrep(<job-id>, "pattern", context?)` — line-numbered matches, capped and condensed; default pattern = generic failure signatures (override when you know the format) |
 | Clean  | `bgclean()` for this session's old logs; `bgclean all` to sweep every session's (default 7-day retention) |
 
 ## Workflow
@@ -51,10 +52,11 @@ no polling.
 
 ### Reading results without flooding context
 
-- **Quick peek (≤40 lines):** call `bgtail` with the job id and `lines: 40` — strips the `__BGRUN_EXIT__` marker.
+- **Quick peek (≤40 lines):** call `bgtail` with the job id and `lines: 40` — strips the `__BGRUN_EXIT__` marker. The first read returns the last-40 tail; repeat reads return only lines appended since your last read (delta tailing) — polling a running job is nearly free.
+- **Failure extraction:** `bggrep(<job-id>, "pattern")` — line-numbered matches with optional context lines, capped and condensed. Works on global jobs dirs that `ctx_execute_file` cannot reach (it runs inside the extension). Pass your own pattern whenever you know the tool's output format; the default only catches common failure signatures.
 - **Whole-log failure analysis:** `ctx_execute_file` on the log path:
 
-  ```
+  ```javascript
   ctx_execute_file(
     path: "~/.pi-bgrun/jobs/<JOB>.log",
     language: "javascript",
@@ -67,8 +69,22 @@ no polling.
 
   A 10 000-line `make test` log collapses to a ~30-line summary in context.
 
-**Never `cat`, `Read`, or `bash cat` a full bgrun log.** Always `bgtail` or
-`ctx_execute_file`.
+**Why `bggrep` instead of `bash grep` on the log?**
+
+- `bash grep` output is uncapped — a retry-storm log can dump thousands of
+  matching lines (megabytes) straight into context, and staying safe depends
+  on remembering `| head` on every single call. `bggrep` is bounded by design
+  (~50 matches, ~2KB/line, ~8KB).
+- It takes the job id — no log-path reconstruction, no shell-quoting of the
+  regex — and works on any jobs dir, including global logs that
+  project-sandboxed `ctx_execute_file` cannot reach.
+- Output is self-describing: match count, line numbers, `…[N skipped]…` gap
+  markers, `— none` for no-match.
+
+Plain `grep` via bash is fine only for a one-off search you know is tiny.
+
+**Never `cat`, `Read`, `bash cat`, or `bash grep` a full bgrun log.** Always
+`bgtail`, `bggrep`, or `ctx_execute_file`.
 
 ## After a pi restart or session switch
 
@@ -85,7 +101,10 @@ no polling.
 
 - Call the tools; never hand-roll `nohup … &` inline.
 - One job = one id. Multiple concurrent jobs are fine — each has its own log.
-- Logs live in `~/.pi-bgrun/jobs` (override with `PI_BGRUN_DIR`).
+- Logs live in `~/.pi-bgrun/jobs` (override with `PI_BGRUN_DIR`). A **relative**
+  `jobsDir` in the project config (e.g. `.pi-bgrun/jobs`) puts logs inside the
+  project — auto-ignored via `.git/info/exclude` — which keeps them reachable
+  for project-sandboxed analysis tools like `ctx_execute_file`.
 - Cleanup: `bgclean` removes only THIS session's old logs; `bgclean all`
   sweeps every session's. Auto-sweeps at session start/shutdown are
   session-scoped plus a global orphan pass (default on — removes finished