@stablekernel/pi-background-run 0.4.0 → 0.5.0

package/extension/index.test.ts

@@ -19,10 +19,12 @@ import {
   readFileSync,
   writeFileSync,
   existsSync,
+  mkdirSync,
+  appendFileSync,
   readdirSync,
 } from "node:fs";
 import { join } from "node:path";
-import { tmpdir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { pathToFileURL } from "node:url";
 
 interface CapturedWake {
@@ -30,7 +32,13 @@ interface CapturedWake {
   options?: Record<string, unknown>;
 }
 
-function makeFakePi(opts: { idle?: boolean; priorEntries?: any[] } = {}): {
+function makeFakePi(
+  opts: {
+    idle?: boolean;
+    priorEntries?: any[];
+    ctxFields?: Record<string, unknown>;
+  } = {},
+): {
   pi: any;
   wakes: CapturedWake[];
   entries: any[];
@@ -60,6 +68,7 @@ function makeFakePi(opts: { idle?: boolean; priorEntries?: any[] } = {}): {
     hasUI: false,
     ui: { notify() {}, setWidget() {}, setStatus() {} },
     sessionManager: { getEntries: () => entries },
+    ...(opts.ctxFields as Record<string, unknown> | undefined),
   };
   const pi = {
     sendUserMessage(text: string, options?: Record<string, unknown>) {
@@ -1770,3 +1779,791 @@ test("formatSince: same-day shows time only; older days include the date", async
   assert.match(prevYearStr, /Dec 30/);
   assert.match(prevYearStr, /08:00:00/);
 });
+
+// ── Project-local jobs dir ──────────────────────────────────────────────────
+
+test("resolveJobsDirPath: relative resolves against a project root; absolute and no-root fall back", async () => {
+  const mod = await import(
+    pathToFileURL(join(process.cwd(), "extension/index.ts")).href
+  );
+  const proj = mkdtempSync(join(tmpdir(), "pi-bgrun-proj-"));
+  const scratch = mkdtempSync(join(tmpdir(), "pi-bgrun-scratch-"));
+  try {
+    mkdirSync(join(proj, ".git"), { recursive: true });
+
+    // absolute → used as-is, never flagged project-local (older configs keep
+    // working unchanged — the migration guarantee)
+    const absPath = join(proj, "abs-jobs");
+    const abs = mod.resolveJobsDirPath(absPath, { cwd: proj });
+    assert.equal(abs.dir, absPath);
+    assert.equal(abs.projectLocal, false);
+
+    // relative + project root → resolved against the root, flagged project-local
+    const rel = mod.resolveJobsDirPath(".pi-bgrun/jobs", { cwd: proj });
+    assert.equal(rel.dir, join(proj, ".pi-bgrun", "jobs"));
+    assert.equal(rel.projectLocal, true);
+
+    // unset → global default
+    const none = mod.resolveJobsDirPath(undefined, { cwd: proj });
+    assert.equal(none.dir, join(homedir(), ".pi-bgrun", "jobs"));
+    assert.equal(none.projectLocal, false);
+
+    // relative + cwd that is not a project → global fallback, never cwd-relative
+    const fb = mod.resolveJobsDirPath(".pi-bgrun/jobs", { cwd: scratch });
+    assert.equal(fb.dir, join(homedir(), ".pi-bgrun", "jobs"));
+    assert.equal(fb.projectLocal, false);
+  } finally {
+    rmSync(proj, { recursive: true, force: true });
+    rmSync(scratch, { recursive: true, force: true });
+  }
+});
+
+test("ensureGitExcluded: appends the jobs dir pattern to .git/info/exclude once per dir", async () => {
+  const mod = await import(
+    pathToFileURL(join(process.cwd(), "extension/index.ts")).href
+  );
+  const repo = mkdtempSync(join(tmpdir(), "pi-bgrun-repo-"));
+  try {
+    mkdirSync(join(repo, ".git", "info"), { recursive: true });
+    mod.ensureGitExcluded(join(repo, ".pi-bgrun", "jobs"));
+    mod.ensureGitExcluded(join(repo, ".pi-bgrun", "jobs"));
+    // a second, different jobs dir under the same repo adds its own pattern
+    mod.ensureGitExcluded(join(repo, ".pi-bgrun", "other"));
+    const exclude = readFileSync(join(repo, ".git", "info", "exclude"), "utf8");
+    assert.match(exclude, /# pi-bgrun job logs/);
+    assert.equal(
+      exclude.split("\n").filter((l) => l.trim() === ".pi-bgrun/jobs/").length,
+      1,
+      "pattern appears exactly once",
+    );
+    assert.ok(exclude.split("\n").includes(".pi-bgrun/other/"));
+  } finally {
+    rmSync(repo, { recursive: true, force: true });
+  }
+});
+
+test("ensureGitExcluded: linked worktree (.git file) writes to the pointed git dir", async () => {
+  const mod = await import(
+    pathToFileURL(join(process.cwd(), "extension/index.ts")).href
+  );
+  const wt = mkdtempSync(join(tmpdir(), "pi-bgrun-wt-"));
+  const gd = mkdtempSync(join(tmpdir(), "pi-bgrun-gitdir-"));
+  try {
+    writeFileSync(join(wt, ".git"), `gitdir: ${gd}\n`);
+    mod.ensureGitExcluded(join(wt, ".pi-bgrun", "jobs"));
+    const exclude = readFileSync(join(gd, "info", "exclude"), "utf8");
+    assert.match(exclude, /^\.pi-bgrun\/jobs\/$/m);
+    // nothing was created inside the worktree's own .git (it's a file)
+    assert.ok(!existsSync(join(wt, ".git", "info")));
+  } finally {
+    rmSync(wt, { recursive: true, force: true });
+    rmSync(gd, { recursive: true, force: true });
+  }
+});
+
+test("ensureGitExcluded: gitdir pointer with spaces in the path", async () => {
+  const mod = await import(
+    pathToFileURL(join(process.cwd(), "extension/index.ts")).href
+  );
+  const wt = mkdtempSync(join(tmpdir(), "pi-bgrun-wt-"));
+  const gd = join(tmpdir(), "pi-bgrun git dir with spaces");
+  mkdirSync(gd, { recursive: true });
+  try {
+    writeFileSync(join(wt, ".git"), `gitdir: ${gd}\n`);
+    assert.equal(mod.ensureGitExcluded(join(wt, ".pi-bgrun", "jobs")), true);
+    const exclude = readFileSync(join(gd, "info", "exclude"), "utf8");
+    assert.match(exclude, /^\.pi-bgrun\/jobs\/$/m);
+  } finally {
+    rmSync(wt, { recursive: true, force: true });
+    rmSync(gd, { recursive: true, force: true });
+  }
+});
+
+test("ensureGitExcluded: retries after a transient failure — memoizes only on success", async () => {
+  const mod = await import(
+    pathToFileURL(join(process.cwd(), "extension/index.ts")).href
+  );
+  const repo = mkdtempSync(join(tmpdir(), "pi-bgrun-repo-"));
+  try {
+    mkdirSync(join(repo, ".git", "info"), { recursive: true });
+    // Block the exclude path with a directory → the append fails (EISDIR)
+    mkdirSync(join(repo, ".git", "info", "exclude"));
+    const jobsDir = join(repo, ".pi-bgrun", "jobs");
+    assert.equal(mod.ensureGitExcluded(jobsDir), false);
+
+    // Unblock: the next call must retry (failure was not memoized) and succeed
+    rmSync(join(repo, ".git", "info", "exclude"), { recursive: true });
+    assert.equal(mod.ensureGitExcluded(jobsDir), true);
+    const exclude = readFileSync(join(repo, ".git", "info", "exclude"), "utf8");
+    assert.match(exclude, /^\.pi-bgrun\/jobs\/$/m);
+  } finally {
+    rmSync(repo, { recursive: true, force: true });
+  }
+});
+
+test("bgrun: relative jobsDir in project config → project-local log + auto git-exclude", async () => {
+  const proj = mkdtempSync(join(tmpdir(), "pi-bgrun-proj-"));
+  delete process.env.PI_BGRUN_DIR;
+  try {
+    mkdirSync(join(proj, ".git"), { recursive: true });
+    mkdirSync(join(proj, ".pi"), { recursive: true });
+    writeFileSync(
+      join(proj, ".pi", "pi-bgrun.json"),
+      JSON.stringify({ jobsDir: ".pi-bgrun/jobs" }),
+    );
+    const { pi, wakes, tools, ctx } = makeFakePi({
+      ctxFields: { cwd: proj, isProjectTrusted: () => true },
+    });
+    await loadExtension(pi);
+    const bgrun = tools.get("bgrun")!;
+
+    const res = await bgrun.execute(
+      "call-1",
+      { command: "echo project-local" },
+      undefined,
+      undefined,
+      ctx,
+    );
+    const id = ((res.content[0].text as string).match(/^started: ([^\n]+)/) ||
+      [])[1];
+    assert.ok(id, "got a job id");
+
+    await waitForWakes(wakes, 1);
+
+    const logPath = join(proj, ".pi-bgrun", "jobs", `${id}.log`);
+    assert.ok(existsSync(logPath), "log written inside the project");
+    assert.match(readFileSync(logPath, "utf8"), /project-local/);
+
+    const exclude = join(proj, ".git", "info", "exclude");
+    assert.ok(existsSync(exclude), "exclude file created");
+    assert.match(readFileSync(exclude, "utf8"), /^\.pi-bgrun\/jobs\/$/m);
+  } finally {
+    delete process.env.PI_BGRUN_DIR;
+    rmSync(proj, { recursive: true, force: true });
+  }
+});
+
+test("bgtail: prefers the session record's logPath when the jobsDir config changes", async () => {
+  const proj = mkdtempSync(join(tmpdir(), "pi-bgrun-proj-"));
+  delete process.env.PI_BGRUN_DIR;
+  try {
+    mkdirSync(join(proj, ".git"), { recursive: true });
+    mkdirSync(join(proj, ".pi"), { recursive: true });
+    writeFileSync(
+      join(proj, ".pi", "pi-bgrun.json"),
+      JSON.stringify({ jobsDir: ".pi-bgrun/jobs" }),
+    );
+    const { pi, wakes, tools, ctx } = makeFakePi({
+      ctxFields: { cwd: proj, isProjectTrusted: () => true },
+    });
+    await loadExtension(pi);
+    const bgrun = tools.get("bgrun")!;
+    const bgtail = tools.get("bgtail")!;
+
+    const res = await bgrun.execute(
+      "call-1",
+      { command: "echo migrated-log" },
+      undefined,
+      undefined,
+      ctx,
+    );
+    const id = ((res.content[0].text as string).match(/^started: ([^\n]+)/) ||
+      [])[1];
+    assert.ok(id, "got a job id");
+    await waitForWakes(wakes, 1);
+
+    // A ctx with no project config/trust now resolves the jobs dir to the
+    // GLOBAL default — only the session record's logPath can still find the
+    // log (the mid-upgrade config-change scenario).
+    const plainCtx = { ...ctx, cwd: undefined, isProjectTrusted: undefined };
+    const tail = await bgtail.execute(
+      "call-2",
+      { id, lines: 10 },
+      undefined,
+      undefined,
+      plainCtx,
+    );
+    assert.equal(tail.details.notFound, false);
+    assert.match(tail.content[0].text as string, /migrated-log/);
+  } finally {
+    delete process.env.PI_BGRUN_DIR;
+    rmSync(proj, { recursive: true, force: true });
+  }
+});
+
+// ── bggrep ──────────────────────────────────────────────────────────────────
+
+test("bggrep: line-numbered matches; explicit pattern wins; default pattern; no-match case", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "pi-bgrun-test-"));
+  process.env.PI_BGRUN_DIR = dir;
+  try {
+    const { pi, wakes, tools, ctx } = makeFakePi();
+    await loadExtension(pi);
+    const bgrun = tools.get("bgrun")!;
+    const bggrep = tools.get("bggrep")!;
+
+    const res = await bgrun.execute(
+      "c1",
+      { command: "printf 'alpha\\nerror: boom BANANA\\nomega\\n'" },
+      undefined,
+      undefined,
+      ctx,
+    );
+    const id = ((res.content[0].text as string).match(/^started: ([^\n]+)/) ||
+      [])[1];
+    assert.ok(id, "got a job id");
+    await waitForWakes(wakes, 1);
+
+    // explicit pattern → only matching lines, with line numbers
+    const g = await bggrep.execute(
+      "c2",
+      { id, pattern: "BANANA" },
+      undefined,
+      undefined,
+      ctx,
+    );
+    assert.equal(g.details.matches, 1);
+    assert.equal(g.details.notFound, false);
+    assert.match(g.content[0].text as string, /L2: error: boom BANANA/);
+    assert.doesNotMatch(g.content[0].text as string, /alpha|omega/);
+
+    // default pattern (no pattern passed) catches the failure signature
+    const g2 = await bggrep.execute("c3", { id }, undefined, undefined, ctx);
+    assert.equal(g2.details.matches, 1);
+    assert.match(g2.content[0].text as string, /1 match for \//);
+    assert.equal(
+      g2.details.pattern,
+      "--- FAIL:|^FAIL\\b|^panic:|fatal error:|AssertionError|Error:|error:|make: \\*\\*\\*.*Error|✗|✖",
+    );
+
+    // a log with no failure signatures → clean no-match (not an error)
+    const res2 = await bgrun.execute(
+      "c4",
+      { command: "echo all clear, nothing to see" },
+      undefined,
+      undefined,
+      ctx,
+    );
+    const id2 = ((res2.content[0].text as string).match(/^started: ([^\n]+)/) ||
+      [])[1];
+    await waitForWakes(wakes, 2);
+    const g3 = await bggrep.execute(
+      "c5",
+      { id: id2 },
+      undefined,
+      undefined,
+      ctx,
+    );
+    assert.equal(g3.details.matches, 0);
+    assert.equal(g3.isError, undefined);
+    assert.match(g3.content[0].text as string, /— none/);
+  } finally {
+    delete process.env.PI_BGRUN_DIR;
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("bggrep: context lines with gap markers between distant matches", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "pi-bgrun-test-"));
+  process.env.PI_BGRUN_DIR = dir;
+  try {
+    const { pi, wakes, tools, ctx } = makeFakePi();
+    await loadExtension(pi);
+    const bgrun = tools.get("bgrun")!;
+    const bggrep = tools.get("bggrep")!;
+
+    const res = await bgrun.execute(
+      "c1",
+      {
+        command:
+          "printf 'l1\\nMATCH one\\nl3\\nl4\\nl5\\nl6\\nl7\\nMATCH two\\nl9\\n'",
+      },
+      undefined,
+      undefined,
+      ctx,
+    );
+    const id = ((res.content[0].text as string).match(/^started: ([^\n]+)/) ||
+      [])[1];
+    assert.ok(id, "got a job id");
+    await waitForWakes(wakes, 1);
+
+    const g = await bggrep.execute(
+      "c2",
+      { id, pattern: "MATCH", context: 1 },
+      undefined,
+      undefined,
+      ctx,
+    );
+    assert.equal(g.details.matches, 2);
+    const text = g.content[0].text as string;
+    assert.match(text, /L2: MATCH one/);
+    assert.match(text, /L1: l1/); // context before
+    assert.match(text, /L8: MATCH two/);
+    assert.match(text, /L9: l9/); // context after
+    assert.match(text, /…\[3 lines skipped\]…/); // l4-l6 between the windows
+  } finally {
+    delete process.env.PI_BGRUN_DIR;
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("bggrep: invalid pattern errors clearly", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "pi-bgrun-test-"));
+  process.env.PI_BGRUN_DIR = dir;
+  try {
+    const { pi, wakes, tools, ctx } = makeFakePi();
+    await loadExtension(pi);
+    const bgrun = tools.get("bgrun")!;
+    const bggrep = tools.get("bggrep")!;
+    const res = await bgrun.execute(
+      "c1",
+      { command: "echo hi" },
+      undefined,
+      undefined,
+      ctx,
+    );
+    const id = ((res.content[0].text as string).match(/^started: ([^\n]+)/) ||
+      [])[1];
+    await waitForWakes(wakes, 1);
+    await assert.rejects(
+      bggrep.execute(
+        "c2",
+        { id, pattern: "([unclosed" },
+        undefined,
+        undefined,
+        ctx,
+      ),
+      /bggrep: invalid pattern/,
+    );
+  } finally {
+    delete process.env.PI_BGRUN_DIR;
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("bggrep: caps at 50 matches with a not-shown note", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "pi-bgrun-test-"));
+  process.env.PI_BGRUN_DIR = dir;
+  try {
+    const { pi, wakes, tools, ctx } = makeFakePi();
+    await loadExtension(pi);
+    const bgrun = tools.get("bgrun")!;
+    const bggrep = tools.get("bggrep")!;
+    const res = await bgrun.execute(
+      "c1",
+      { command: 'for i in $(seq 1 60); do echo "boom $i"; done' },
+      undefined,
+      undefined,
+      ctx,
+    );
+    const id = ((res.content[0].text as string).match(/^started: ([^\n]+)/) ||
+      [])[1];
+    await waitForWakes(wakes, 1);
+    const g = await bggrep.execute(
+      "c2",
+      { id, pattern: "boom" },
+      undefined,
+      undefined,
+      ctx,
+    );
+    assert.equal(g.details.matches, 60);
+    assert.equal(g.details.capped, true);
+    assert.match(
+      g.content[0].text as string,
+      /showing first 50; 10 more not shown/,
+    );
+    assert.match(g.content[0].text as string, /L50: boom 50/);
+    assert.doesNotMatch(g.content[0].text as string, /L51: boom 51/);
+  } finally {
+    delete process.env.PI_BGRUN_DIR;
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("bggrep: prefers the session record's logPath when the jobsDir config changes", async () => {
+  const proj = mkdtempSync(join(tmpdir(), "pi-bgrun-proj-"));
+  delete process.env.PI_BGRUN_DIR;
+  try {
+    mkdirSync(join(proj, ".git"), { recursive: true });
+    mkdirSync(join(proj, ".pi"), { recursive: true });
+    writeFileSync(
+      join(proj, ".pi", "pi-bgrun.json"),
+      JSON.stringify({ jobsDir: ".pi-bgrun/jobs" }),
+    );
+    const { pi, wakes, tools, ctx } = makeFakePi({
+      ctxFields: { cwd: proj, isProjectTrusted: () => true },
+    });
+    await loadExtension(pi);
+    const bgrun = tools.get("bgrun")!;
+    const bggrep = tools.get("bggrep")!;
+    const res = await bgrun.execute(
+      "c1",
+      { command: "echo pattern-target-line" },
+      undefined,
+      undefined,
+      ctx,
+    );
+    const id = ((res.content[0].text as string).match(/^started: ([^\n]+)/) ||
+      [])[1];
+    await waitForWakes(wakes, 1);
+
+    const plainCtx = { ...ctx, cwd: undefined, isProjectTrusted: undefined };
+    const g = await bggrep.execute(
+      "c2",
+      { id, pattern: "pattern-target" },
+      undefined,
+      undefined,
+      plainCtx,
+    );
+    assert.equal(g.details.notFound, false);
+    assert.equal(g.details.matches, 1);
+  } finally {
+    delete process.env.PI_BGRUN_DIR;
+    rmSync(proj, { recursive: true, force: true });
+  }
+});
+
+// ── bgtail delta tailing ────────────────────────────────────────────────────
+
+test("bgtail: delta tailing — first read full tail, then only new lines, then none", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "pi-bgrun-test-"));
+  process.env.PI_BGRUN_DIR = dir;
+  try {
+    const { pi, wakes, tools, ctx } = makeFakePi();
+    await loadExtension(pi);
+    const bgrun = tools.get("bgrun")!;
+    const bgtail = tools.get("bgtail")!;
+    const res = await bgrun.execute(
+      "c1",
+      { command: "echo first line" },
+      undefined,
+      undefined,
+      ctx,
+    );
+    const id = ((res.content[0].text as string).match(/^started: ([^\n]+)/) ||
+      [])[1];
+    assert.ok(id, "got a job id");
+    await waitForWakes(wakes, 1);
+    const logPath = join(dir, `${id}.log`);
+
+    // First read: full tail, no delta header
+    const t1 = await bgtail.execute("c2", { id }, undefined, undefined, ctx);
+    assert.match(t1.content[0].text as string, /first line/);
+    assert.equal(t1.details.newLines, undefined);
+    assert.doesNotMatch(
+      t1.content[0].text as string,
+      /new lines since last read/,
+    );
+
+    // Log grows: only the new lines come back, with a +N header
+    appendFileSync(logPath, "appended-A\nappended-B\n");
+    const t2 = await bgtail.execute("c3", { id }, undefined, undefined, ctx);
+    const text2 = t2.content[0].text as string;
+    assert.match(text2, /\+2 new lines since last read/);
+    assert.match(text2, /appended-A/);
+    assert.match(text2, /appended-B/);
+    assert.doesNotMatch(text2, /first line/);
+    assert.equal(t2.details.newLines, 2);
+
+    // Nothing new: a tiny no-new-lines response (cheap polling)
+    const t3 = await bgtail.execute("c4", { id }, undefined, undefined, ctx);
+    assert.match(t3.content[0].text as string, /no new lines since last read/);
+    assert.equal(t3.details.linesShown, 0);
+  } finally {
+    delete process.env.PI_BGRUN_DIR;
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("bgtail: raw:true keeps the verbatim window but still advances the bookmark", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "pi-bgrun-test-"));
+  process.env.PI_BGRUN_DIR = dir;
+  try {
+    const { pi, wakes, tools, ctx } = makeFakePi();
+    await loadExtension(pi);
+    const bgrun = tools.get("bgrun")!;
+    const bgtail = tools.get("bgtail")!;
+    const res = await bgrun.execute(
+      "c1",
+      { command: "echo baseline" },
+      undefined,
+      undefined,
+      ctx,
+    );
+    const id = ((res.content[0].text as string).match(/^started: ([^\n]+)/) ||
+      [])[1];
+    await waitForWakes(wakes, 1);
+    const logPath = join(dir, `${id}.log`);
+
+    appendFileSync(logPath, "post-raw line\n");
+    const r = await bgtail.execute(
+      "c2",
+      { id, lines: 3, raw: true },
+      undefined,
+      undefined,
+      ctx,
+    );
+    assert.match(r.content[0].text as string, /post-raw line/);
+    assert.equal(r.details.condensed, false);
+
+    // The raw read advanced the bookmark → the next condensed read is empty
+    const t = await bgtail.execute("c3", { id }, undefined, undefined, ctx);
+    assert.match(t.content[0].text as string, /no new lines since last read/);
+  } finally {
+    delete process.env.PI_BGRUN_DIR;
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("bgtail: a shrunken log resets to a full tail with a note", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "pi-bgrun-test-"));
+  process.env.PI_BGRUN_DIR = dir;
+  try {
+    const { pi, wakes, tools, ctx } = makeFakePi();
+    await loadExtension(pi);
+    const bgrun = tools.get("bgrun")!;
+    const bgtail = tools.get("bgtail")!;
+    const res = await bgrun.execute(
+      "c1",
+      { command: "echo long original content line" },
+      undefined,
+      undefined,
+      ctx,
+    );
+    const id = ((res.content[0].text as string).match(/^started: ([^\n]+)/) ||
+      [])[1];
+    await waitForWakes(wakes, 1);
+    const logPath = join(dir, `${id}.log`);
+
+    // First read sets the bookmark; then the log is replaced by a shorter one
+    await bgtail.execute("c2", { id }, undefined, undefined, ctx);
+    writeFileSync(logPath, "tiny replacement\n");
+    const t = await bgtail.execute("c3", { id }, undefined, undefined, ctx);
+    const text = t.content[0].text as string;
+    assert.match(text, /log shrank since last read — showing full tail/);
+    assert.match(text, /tiny replacement/);
+  } finally {
+    delete process.env.PI_BGRUN_DIR;
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("bgtail: a replaced log with the same line count resets to a full tail", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "pi-bgrun-test-"));
+  process.env.PI_BGRUN_DIR = dir;
+  try {
+    const { pi, wakes, tools, ctx } = makeFakePi();
+    await loadExtension(pi);
+    const bgrun = tools.get("bgrun")!;
+    const bgtail = tools.get("bgtail")!;
+    const res = await bgrun.execute(
+      "c1",
+      { command: "printf 'aaaa\\nbbbb\\ncccc\\n'" },
+      undefined,
+      undefined,
+      ctx,
+    );
+    const id = ((res.content[0].text as string).match(/^started: ([^\n]+)/) ||
+      [])[1];
+    await waitForWakes(wakes, 1);
+    const logPath = join(dir, `${id}.log`);
+
+    // First read sets the bookmark (3 content lines, first line "aaaa")
+    await bgtail.execute("c2", { id }, undefined, undefined, ctx);
+    // Replacement: SAME line count, LARGER byte size (so the shrink checks
+    // cannot fire), different first line — only the first-line detector
+    // (append-only logs never mutate line 0) can catch this.
+    writeFileSync(
+      logPath,
+      "xxxxxxxxxxxxxxxxxx\nyyyyyyyyyyyyyyyyyy\nzzzzzzzzzzzzzzzzzz\n",
+    );
+    const t = await bgtail.execute("c3", { id }, undefined, undefined, ctx);
+    const text = t.content[0].text as string;
+    assert.match(text, /log was replaced since last read — showing full tail/);
+    assert.match(text, /xxxxxxxxxxxxxxxxxx/);
+  } finally {
+    delete process.env.PI_BGRUN_DIR;
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("bggrep and bgtail normalize CRLF logs", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "pi-bgrun-test-"));
+  process.env.PI_BGRUN_DIR = dir;
+  try {
+    const { pi, wakes, tools, ctx } = makeFakePi();
+    await loadExtension(pi);
+    const bgrun = tools.get("bgrun")!;
+    const bgtail = tools.get("bgtail")!;
+    const bggrep = tools.get("bggrep")!;
+    const res = await bgrun.execute(
+      "c1",
+      { command: "echo something" },
+      undefined,
+      undefined,
+      ctx,
+    );
+    const id = ((res.content[0].text as string).match(/^started: ([^\n]+)/) ||
+      [])[1];
+    await waitForWakes(wakes, 1);
+    const logPath = join(dir, `${id}.log`);
+
+    writeFileSync(logPath, "alpha\r\nerror: boom\r\nomega\r\n");
+    // A $-anchored pattern must match despite the CRLF source
+    const g = await bggrep.execute(
+      "c2",
+      { id, pattern: "boom$" },
+      undefined,
+      undefined,
+      ctx,
+    );
+    assert.match(g.content[0].text as string, /L2: error: boom/);
+    // And no stray \r leaks into either tool's output
+    assert.ok(!(g.content[0].text as string).includes("\r"));
+    const t = await bgtail.execute("c3", { id }, undefined, undefined, ctx);
+    assert.ok(!(t.content[0].text as string).includes("\r"));
+    assert.match(t.content[0].text as string, /error: boom/);
+  } finally {
+    delete process.env.PI_BGRUN_DIR;
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("bggrep: empty log reports zero lines, and a missing log is notFound", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "pi-bgrun-test-"));
+  process.env.PI_BGRUN_DIR = dir;
+  try {
+    const { pi, wakes, tools, ctx } = makeFakePi();
+    await loadExtension(pi);
+    const bgrun = tools.get("bgrun")!;
+    const bggrep = tools.get("bggrep")!;
+    const res = await bgrun.execute(
+      "c1",
+      { command: "echo x" },
+      undefined,
+      undefined,
+      ctx,
+    );
+    const id = ((res.content[0].text as string).match(/^started: ([^\n]+)/) ||
+      [])[1];
+    await waitForWakes(wakes, 1);
+
+    writeFileSync(join(dir, `${id}.log`), "");
+    const g = await bggrep.execute(
+      "c2",
+      { id, pattern: "Error:" },
+      undefined,
+      undefined,
+      ctx,
+    );
+    assert.match(
+      g.content[0].text as string,
+      /0 matches for \/Error:\/ in 0 lines — none/,
+    );
+
+    const missing = await bggrep.execute(
+      "c3",
+      { id: "no-such-job-123", pattern: "x" },
+      undefined,
+      undefined,
+      ctx,
+    );
+    assert.equal(missing.isError, true);
+    assert.equal(missing.details.notFound, true);
+  } finally {
+    delete process.env.PI_BGRUN_DIR;
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("bggrep: context windows combine with the 50-match cap", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "pi-bgrun-test-"));
+  process.env.PI_BGRUN_DIR = dir;
+  try {
+    const { pi, wakes, tools, ctx } = makeFakePi();
+    await loadExtension(pi);
+    const bgrun = tools.get("bgrun")!;
+    const bggrep = tools.get("bggrep")!;
+    const res = await bgrun.execute(
+      "c1",
+      { command: "echo x" },
+      undefined,
+      undefined,
+      ctx,
+    );
+    const id = ((res.content[0].text as string).match(/^started: ([^\n]+)/) ||
+      [])[1];
+    await waitForWakes(wakes, 1);
+
+    // 240 lines, a hit every 4th line → 60 matches (cap 50); with context: 1
+    // each window is [i-1, i+1] and consecutive windows leave a 1-line gap.
+    const lines: string[] = [];
+    for (let i = 1; i <= 240; i++) {
+      lines.push(i % 4 === 0 ? `hit ${i}` : `filler ${i}`);
+    }
+    writeFileSync(join(dir, `${id}.log`), lines.join("\n") + "\n");
+    const r = await bggrep.execute(
+      "c2",
+      { id, pattern: "^hit", context: 1 },
+      undefined,
+      undefined,
+      ctx,
+    );
+    const text = r.content[0].text as string;
+    assert.equal(r.details.matches, 60);
+    assert.equal(r.details.capped, true);
+    assert.match(text, /showing first 50; 10 more not shown/);
+    assert.match(text, /L4: hit 4/);
+    assert.match(text, /…\[1 line skipped\]…/);
+  } finally {
+    delete process.env.PI_BGRUN_DIR;
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("bgtail and bggrep clamp nonsensical numeric params", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "pi-bgrun-test-"));
+  process.env.PI_BGRUN_DIR = dir;
+  try {
+    const { pi, wakes, tools, ctx } = makeFakePi();
+    await loadExtension(pi);
+    const bgrun = tools.get("bgrun")!;
+    const bgtail = tools.get("bgtail")!;
+    const bggrep = tools.get("bggrep")!;
+    const res = await bgrun.execute(
+      "c1",
+      { command: "printf 'one\\ntwo\\nthree\\nfour\\nfive\\n'" },
+      undefined,
+      undefined,
+      ctx,
+    );
+    const id = ((res.content[0].text as string).match(/^started: ([^\n]+)/) ||
+      [])[1];
+    await waitForWakes(wakes, 1);
+
+    // lines: 0 must not mean "everything" (slice(-0) pitfall) — clamps to 1
+    const t = await bgtail.execute(
+      "c2",
+      { id, lines: 0 },
+      undefined,
+      undefined,
+      ctx,
+    );
+    assert.equal(t.details.linesShown, 1);
+    assert.match(t.content[0].text as string, /five/);
+    assert.ok(!(t.content[0].text as string).includes("four"));
+
+    // negative context must not drop the match lines themselves — clamps to 0
+    const g = await bggrep.execute(
+      "c3",
+      { id, pattern: "^three", context: -1 },
+      undefined,
+      undefined,
+      ctx,
+    );
+    assert.match(g.content[0].text as string, /L3: three/);
+  } finally {
+    delete process.env.PI_BGRUN_DIR;
+    rmSync(dir, { recursive: true, force: true });
+  }
+});