@stablekernel/pi-background-run 0.3.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,11 +32,21 @@ 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[];
   tools: Map<string, { execute: (...args: any[]) => Promise<any> }>;
+  commands: Map<
+    string,
+    { description?: string; handler: (...args: any[]) => Promise<void> }
+  >;
   ctx: any;
   handlers: Map<string, ((...args: any[]) => Promise<any>)[]>;
   fireSessionStart: () => Promise<void>;
@@ -45,6 +57,10 @@ function makeFakePi(opts: { idle?: boolean; priorEntries?: any[] } = {}): {
     string,
     { execute: (...args: any[]) => Promise<any> }
   >();
+  const commands = new Map<
+    string,
+    { description?: string; handler: (...args: any[]) => Promise<void> }
+  >();
   const handlers = new Map<string, ((...args: any[]) => Promise<any>)[]>();
   const idle = opts.idle ?? true;
   const ctx = {
@@ -52,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>) {
@@ -64,6 +81,9 @@ function makeFakePi(opts: { idle?: boolean; priorEntries?: any[] } = {}): {
     registerTool(def: any) {
       tools.set(def.name, def);
     },
+    registerCommand(name: string, def: any) {
+      commands.set(name, def);
+    },
     on(event: string, handler: (...args: any[]) => Promise<any>) {
       const list = handlers.get(event) ?? [];
       list.push(handler);
@@ -75,7 +95,16 @@ function makeFakePi(opts: { idle?: boolean; priorEntries?: any[] } = {}): {
       await h({ reason: "startup" }, ctx);
     }
   };
-  return { pi, wakes, entries, tools, ctx, handlers, fireSessionStart };
+  return {
+    pi,
+    wakes,
+    entries,
+    tools,
+    commands,
+    ctx,
+    handlers,
+    fireSessionStart,
+  };
 }
 
 async function loadExtension(
@@ -268,11 +297,19 @@ test("bgtail: condenses output — strips ANSI, collapses repeats, caps long lin
     const text = tail.content[0].text as string;
     assert.ok(!text.includes("\u001b"), "ANSI escapes stripped");
     assert.ok(text.includes("OK green"), "text after stripping survives");
-    assert.match(text, /wait  \[x5\]/, "5 identical lines collapsed to one with count");
+    assert.match(
+      text,
+      /wait {2}\[x5\]/,
+      "5 identical lines collapsed to one with count",
+    );
     assert.ok(!text.includes("x".repeat(4000)), "5000-char line capped");
     assert.match(text, /\u2026\[\+3\d{3} chars\]/, "truncation marker present");
     assert.match(text, /\(\d+ ANSI escape/, "notes mention ANSI stripping");
-    assert.match(text, /1 repeated-line run collapsed/, "notes mention run collapse");
+    assert.match(
+      text,
+      /1 repeated-line run collapsed/,
+      "notes mention run collapse",
+    );
     assert.ok((tail.details as any).condensed === true);
   } finally {
     delete process.env.PI_BGRUN_DIR;
@@ -309,7 +346,10 @@ test("bgtail: raw=true skips condensing", async () => {
     );
     const text = tail.content[0].text as string;
     assert.ok(text.includes("\u001b[31m"), "raw keeps ANSI escapes");
-    assert.ok(text.includes("wait\nwait\nwait"), "raw keeps repeated lines uncollapsed");
+    assert.ok(
+      text.includes("wait\nwait\nwait"),
+      "raw keeps repeated lines uncollapsed",
+    );
     assert.ok((tail.details as any).condensed === false);
   } finally {
     delete process.env.PI_BGRUN_DIR;
@@ -667,7 +707,7 @@ test("bgrun: name is optional — behavior unchanged without it", async () => {
     );
     const text = res.content[0].text as string;
     // No 'name:' line in the response.
-    assert.ok(!/^  name:/m.test(text), "no name line when name omitted");
+    assert.ok(!/^ {2}name:/m.test(text), "no name line when name omitted");
     const id = (text.match(/^started: ([^\n]+)/) || [])[1];
     assert.ok(
       id.startsWith("echo-unnamed-job-"),
@@ -702,7 +742,7 @@ test("bgrun: blank name is ignored, over-long name is truncated", async () => {
       ctx,
     );
     assert.ok(
-      !/^  name:/m.test(res1.content[0].text as string),
+      !/^ {2}name:/m.test(res1.content[0].text as string),
       "blank name ignored",
     );
 
@@ -716,7 +756,7 @@ test("bgrun: blank name is ignored, over-long name is truncated", async () => {
       ctx,
     );
     const text2 = res2.content[0].text as string;
-    const nameLine = (text2.match(/^  name: (.+)$/m) || [])[1];
+    const nameLine = (text2.match(/^ {2}name: (.+)$/m) || [])[1];
     assert.equal(nameLine.length, 80, "name truncated to 80 chars");
 
     await waitForWakes(wakes, 2);
@@ -1068,14 +1108,15 @@ test("bgrun: job id encodes the CHILD's pid, not pi's own pid", async () => {
   }
 });
 
-test("bgclean: removes a FINISHED job's old log even when its id-pid is alive", async () => {
+test("bgclean all: removes a FINISHED job's old log even when its id-pid is alive", async () => {
   // Regression: exit marker must win over pid liveness. Old code checked
   // pid first, so any log whose id-pid happened to be a live process (e.g.
   // pi's own pid from the old id bug, or pid reuse) was kept forever.
   const dir = mkdtempSync(join(tmpdir(), "pi-bgrun-test-"));
   process.env.PI_BGRUN_DIR = dir;
   try {
-    // Old finished log whose id-pid is THIS process (alive!) — must still be removed.
+    // Old finished foreign log whose id-pid is THIS process (alive!) — must
+    // still be removed by an explicit global sweep.
     const oldPath = join(dir, `stale-job-1000000000-${process.pid}.log`);
     writeFileSync(oldPath, "stale\n__BGRUN_EXIT__=2\n");
     const oldTime = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
@@ -1086,14 +1127,31 @@ test("bgclean: removes a FINISHED job's old log even when its id-pid is alive",
     await loadExtension(pi);
     const bgclean = tools.get("bgclean")!;
 
+    // Default scope: this session only — the foreign log is untouched.
+    const scoped = await bgclean.execute(
+      "call-stale-scoped",
+      { days: 7 },
+      undefined,
+      undefined,
+      ctx,
+    );
+    assert.match(scoped.content[0].text as string, /removed 0/);
+    assert.ok(
+      existsSync(oldPath),
+      "foreign log untouched by session-scoped bgclean",
+    );
+
     const result = await bgclean.execute(
       "call-stale",
-      { days: 7 },
+      { days: 7, all: true },
       undefined,
       undefined,
       ctx,
     );
-    assert.match(result.content[0].text as string, /removed 1/);
+    assert.match(
+      result.content[0].text as string,
+      /removed 1 job log\(s\) \(all sessions\)/,
+    );
     assert.ok(
       !existsSync(oldPath),
       "finished job's log removed despite live id-pid",
@@ -1134,10 +1192,267 @@ test("session_start adoption: skips finished jobs even with a live id-pid", asyn
   }
 });
 
-test("auto-clean: throttled via .last-clean marker; manual bgclean always runs", async () => {
+test("session_start: reconstructed 'running' job that finished while pi was down is cleared, not zombified", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "pi-bgrun-test-"));
+  process.env.PI_BGRUN_DIR = dir;
+  delete process.env.PI_BGRUN_FOREIGN_JOBS;
+  try {
+    // A job from 5 days ago whose transcript entry never got a done entry
+    // (pi wasn't running when it exited), whose log is long gone and whose
+    // pid is definitely dead.
+    const zombieId = `cd-old-project-make-test-${Date.now()}-99999999`;
+    const logPath = join(dir, `${zombieId}.log`); // never created
+    const priorEntries = [
+      {
+        type: "custom",
+        customType: "bgrun-job",
+        data: {
+          id: zombieId,
+          pid: 99999999,
+          cmd: "cd /old/project && make test",
+          name: undefined,
+          started: Date.now() - 5 * 24 * 60 * 60 * 1000,
+          logPath,
+          state: "running",
+        },
+      },
+    ];
+    const { pi, entries, tools, ctx, fireSessionStart } = makeFakePi({
+      priorEntries,
+    });
+    ctx.hasUI = true;
+    const widgetCalls: (string[] | undefined)[] = [];
+    ctx.ui.setWidget = (_ns: string, lines: string[] | undefined) =>
+      widgetCalls.push(lines);
+
+    await loadExtension(pi);
+    await fireSessionStart();
+
+    // Revalidation runs before the widget ever renders — the zombie is
+    // cleared immediately instead of showing as "running" forever.
+    assert.ok(
+      !widgetCalls.some((l) => Array.isArray(l)),
+      "reconstructed zombie never shown in the widget",
+    );
+
+    // A done entry is appended so future resumes reconstruct it as done.
+    const doneEntry = entries.find(
+      (e) =>
+        e.customType === "bgrun-job" &&
+        e.data?.id === zombieId &&
+        e.data?.state === "done",
+    );
+    assert.ok(doneEntry, "done entry appended for the recovered job");
+
+    // Single-id lookup reports done, not running.
+    const bgstatus = tools.get("bgstatus")!;
+    const res = await bgstatus.execute(
+      "call-z1",
+      { id: zombieId },
+      undefined,
+      undefined,
+      ctx,
+    );
+    assert.match(res.content[0].text as string, /: done/);
+  } finally {
+    delete process.env.PI_BGRUN_DIR;
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("session_start: done entries with missing exitCode (signal kills) reconstruct as done", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "pi-bgrun-test-"));
+  process.env.PI_BGRUN_DIR = dir;
+  delete process.env.PI_BGRUN_FOREIGN_JOBS;
+  try {
+    // Jobs killed by a signal persist state:"done" with exitCode: undefined —
+    // reconstruction must honor the state field, not just the exit code.
+    const killedId = `nightly-watch-${Date.now()}-${process.pid}`;
+    const logPath = join(dir, `${killedId}.log`);
+    writeFileSync(logPath, "partial output\n"); // no marker — killed before it
+    const priorEntries = [
+      {
+        type: "custom",
+        customType: "bgrun-job",
+        data: {
+          id: killedId,
+          pid: process.pid, // alive — liveness alone must not resurrect it as running
+          cmd: "npm run watch",
+          name: "nightly-watch",
+          started: Date.now() - 60_000,
+          logPath,
+          state: "done",
+          exitCode: undefined,
+          exitedAt: Date.now() - 30_000,
+        },
+      },
+    ];
+    const { pi, tools, ctx, fireSessionStart } = makeFakePi({ priorEntries });
+    ctx.hasUI = true;
+    const widgetCalls: (string[] | undefined)[] = [];
+    ctx.ui.setWidget = (_ns: string, lines: string[] | undefined) =>
+      widgetCalls.push(lines);
+
+    await loadExtension(pi);
+    await fireSessionStart();
+
+    assert.ok(
+      !widgetCalls.some((l) => Array.isArray(l)),
+      "signal-killed job with a done entry is not resurrected as running",
+    );
+    const bgstatus = tools.get("bgstatus")!;
+    const res = await bgstatus.execute(
+      "call-z2",
+      { id: killedId },
+      undefined,
+      undefined,
+      ctx,
+    );
+    assert.match(res.content[0].text as string, /: done/);
+  } finally {
+    delete process.env.PI_BGRUN_DIR;
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("auto-clean: session boundaries sweep this session's old logs AND week-old foreign orphans by default", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "pi-bgrun-test-"));
+  process.env.PI_BGRUN_DIR = dir;
+  delete process.env.PI_BGRUN_FOREIGN_JOBS;
+  delete process.env.PI_BGRUN_GLOBAL_AUTO_CLEAN;
+  try {
+    const fs = await import("node:fs");
+    const backdate = (path: string) => {
+      const oldTime = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
+      fs.utimesSync(path, oldTime, oldTime);
+    };
+
+    // This session's old done job (from the transcript) with a backdated log.
+    const mineId = `my-old-job-${Date.now()}-99999999`;
+    const myLog = join(dir, `${mineId}.log`);
+    fs.writeFileSync(myLog, "mine\n__BGRUN_EXIT__=0\n");
+    backdate(myLog);
+
+    // A foreign session's week-old FINISHED log — an orphan; swept by default.
+    const orphanLog = join(dir, "foreign-old-job-1000000000-99998.log");
+    fs.writeFileSync(orphanLog, "foreign\n__BGRUN_EXIT__=0\n");
+    backdate(orphanLog);
+
+    // A foreign session's RECENT finished log — within retention, kept.
+    const recentForeignLog = join(
+      dir,
+      `foreign-recent-${Math.floor(Date.now() / 1000)}-99997.log`,
+    );
+    fs.writeFileSync(recentForeignLog, "recent foreign\n__BGRUN_EXIT__=0\n");
+
+    // A foreign session's week-old RUNNING log (no marker, live pid) — running
+    // jobs are pid-protected even when old.
+    const runningForeignLog = join(
+      dir,
+      `foreign-running-${Math.floor(Date.now() / 1000)}-${process.pid}.log`,
+    );
+    fs.writeFileSync(runningForeignLog, "still going\n");
+    backdate(runningForeignLog);
+
+    const priorEntries = [
+      {
+        type: "custom",
+        customType: "bgrun-job",
+        data: {
+          id: mineId,
+          pid: 99999999,
+          cmd: "echo mine",
+          name: undefined,
+          started: Date.now() - 30 * 24 * 60 * 60 * 1000,
+          logPath: myLog,
+          state: "done",
+          exitCode: 0,
+          exitedAt: Date.now() - 30 * 24 * 60 * 60 * 1000,
+        },
+      },
+    ];
+    const { pi, fireSessionStart } = makeFakePi({ priorEntries });
+    await loadExtension(pi);
+    await fireSessionStart();
+
+    assert.ok(!fs.existsSync(myLog), "this session's old log swept");
+    assert.ok(
+      !fs.existsSync(orphanLog),
+      "week-old finished foreign orphan swept by default",
+    );
+    assert.ok(
+      fs.existsSync(recentForeignLog),
+      "recent foreign log kept (within retention)",
+    );
+    assert.ok(
+      fs.existsSync(runningForeignLog),
+      "old but RUNNING foreign log kept (pid-protected)",
+    );
+  } finally {
+    delete process.env.PI_BGRUN_DIR;
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("auto-clean: globalAutoClean=false opts out — foreign orphans untouched, own old logs still swept", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "pi-bgrun-test-"));
+  process.env.PI_BGRUN_DIR = dir;
+  delete process.env.PI_BGRUN_FOREIGN_JOBS;
+  process.env.PI_BGRUN_GLOBAL_AUTO_CLEAN = "0";
+  try {
+    const fs = await import("node:fs");
+    const backdate = (path: string) => {
+      const oldTime = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
+      fs.utimesSync(path, oldTime, oldTime);
+    };
+
+    const mineId = `my-old-job-${Date.now()}-99999999`;
+    const myLog = join(dir, `${mineId}.log`);
+    fs.writeFileSync(myLog, "mine\n__BGRUN_EXIT__=0\n");
+    backdate(myLog);
+
+    const orphanLog = join(dir, "foreign-old-job-1000000000-99998.log");
+    fs.writeFileSync(orphanLog, "foreign\n__BGRUN_EXIT__=0\n");
+    backdate(orphanLog);
+
+    const priorEntries = [
+      {
+        type: "custom",
+        customType: "bgrun-job",
+        data: {
+          id: mineId,
+          pid: 99999999,
+          cmd: "echo mine",
+          name: undefined,
+          started: Date.now() - 30 * 24 * 60 * 60 * 1000,
+          logPath: myLog,
+          state: "done",
+          exitCode: 0,
+          exitedAt: Date.now() - 30 * 24 * 60 * 60 * 1000,
+        },
+      },
+    ];
+    const { pi, fireSessionStart } = makeFakePi({ priorEntries });
+    await loadExtension(pi);
+    await fireSessionStart();
+
+    assert.ok(!fs.existsSync(myLog), "this session's old log still swept");
+    assert.ok(
+      fs.existsSync(orphanLog),
+      "foreign orphan untouched when globalAutoClean is off",
+    );
+  } finally {
+    delete process.env.PI_BGRUN_DIR;
+    delete process.env.PI_BGRUN_GLOBAL_AUTO_CLEAN;
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("auto-clean: global orphan sweep is throttled via .last-clean; manual bgclean all always runs", async () => {
   const dir = mkdtempSync(join(tmpdir(), "pi-bgrun-test-"));
   process.env.PI_BGRUN_DIR = dir;
   delete process.env.PI_BGRUN_FOREIGN_JOBS;
+  delete process.env.PI_BGRUN_GLOBAL_AUTO_CLEAN; // default: on
   try {
     const fs = await import("node:fs");
     const backdate = (path: string) => {
@@ -1145,92 +1460,150 @@ test("auto-clean: throttled via .last-clean marker; manual bgclean always runs",
       fs.utimesSync(path, oldTime, oldTime);
     };
 
-    // Old log A + first session_start (no marker yet) → sweep runs, A removed.
+    // Old foreign log A + first session_start (no marker yet) → global sweep
+    // runs, A removed.
     const logA = join(dir, "old-a-1000000000-99999.log");
     fs.writeFileSync(logA, "old a\n__BGRUN_EXIT__=0\n");
     backdate(logA);
     {
-      const { pi, ctx, fireSessionStart } = makeFakePi();
+      const { pi, fireSessionStart } = makeFakePi();
       await loadExtension(pi);
       await fireSessionStart();
     }
-    assert.ok(!fs.existsSync(logA), "first sweep removed old log A");
+    assert.ok(!fs.existsSync(logA), "first global sweep removed old log A");
     assert.ok(
       fs.existsSync(join(dir, ".last-clean")),
       "throttle marker written",
     );
 
-    // Old log B + second session_start while marker is fresh → throttled, B kept.
+    // Old foreign log B + second session_start while marker is fresh →
+    // throttled, B kept.
     const logB = join(dir, "old-b-1000000000-99998.log");
     fs.writeFileSync(logB, "old b\n__BGRUN_EXIT__=0\n");
     backdate(logB);
     {
-      const { pi, ctx, fireSessionStart } = makeFakePi();
+      const { pi, fireSessionStart } = makeFakePi();
       await loadExtension(pi);
       await fireSessionStart();
     }
-    assert.ok(fs.existsSync(logB), "second sweep throttled — old log B kept");
+    assert.ok(
+      fs.existsSync(logB),
+      "second global sweep throttled — old log B kept",
+    );
 
-    // Manual bgclean ignores the throttle and removes B.
+    // Manual `bgclean all` ignores the throttle and removes B.
     const { pi: pi3, tools: tools3, ctx: ctx3 } = makeFakePi();
     await loadExtension(pi3);
     const bgclean = tools3.get("bgclean")!;
     const result = await bgclean.execute(
       "call-t1",
-      {},
+      { all: true },
       undefined,
       undefined,
       ctx3,
     );
-    assert.match(result.content[0].text as string, /removed 1/);
-    assert.ok(!fs.existsSync(logB), "manual bgclean removed log B");
+    assert.match(
+      result.content[0].text as string,
+      /removed 1 job log\(s\) \(all sessions\)/,
+    );
+    assert.ok(!fs.existsSync(logB), "manual bgclean all removed log B");
   } finally {
     delete process.env.PI_BGRUN_DIR;
+    delete process.env.PI_BGRUN_GLOBAL_AUTO_CLEAN;
     rmSync(dir, { recursive: true, force: true });
   }
 });
 
-test("bgclean: removes old logs, keeps recent ones", async () => {
+test("bgclean: default scope is this session's logs; all: true sweeps everything", async () => {
   const dir = mkdtempSync(join(tmpdir(), "pi-bgrun-test-"));
   process.env.PI_BGRUN_DIR = dir;
+  // Isolate bgclean's scoping from the global orphan auto-sweep (default on)
+  // so the foreign log survives session_start for bgclean to (not) act on.
+  process.env.PI_BGRUN_GLOBAL_AUTO_CLEAN = "0";
   try {
-    const { pi, tools, ctx } = makeFakePi();
+    const fs = await import("node:fs");
+    const backdate = (path: string) => {
+      const oldTime = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
+      fs.utimesSync(path, oldTime, oldTime);
+    };
+
+    const mkEntry = (
+      id: string,
+      logPath: string,
+      extra: Record<string, unknown> = {},
+    ) => ({
+      type: "custom",
+      customType: "bgrun-job",
+      data: {
+        id,
+        pid: 99999999,
+        cmd: `echo ${id}`,
+        name: undefined,
+        started: Date.now() - 60_000,
+        logPath,
+        state: "done",
+        exitCode: 0,
+        exitedAt: Date.now() - 30_000,
+        ...extra,
+      },
+    });
+
+    // This session's recent done job (fresh log — kept).
+    const recentId = `recent-job-${Date.now()}-99999998`;
+    const recentLog = join(dir, `${recentId}.log`);
+    fs.writeFileSync(recentLog, "recent\n__BGRUN_EXIT__=0\n");
+
+    // This session's old done job (backdated log — removed by default scope).
+    const oldId = `old-session-job-${Date.now()}-99999997`;
+    const oldLog = join(dir, `${oldId}.log`);
+    fs.writeFileSync(oldLog, "old session job\n__BGRUN_EXIT__=0\n");
+    backdate(oldLog);
+
+    // A foreign session's old log — untouched by default, removed with all.
+    const foreignLog = join(dir, "foreign-old-job-1000000000-99996.log");
+    fs.writeFileSync(foreignLog, "foreign\n__BGRUN_EXIT__=0\n");
+    backdate(foreignLog);
+
+    const priorEntries = [
+      mkEntry(recentId, recentLog),
+      mkEntry(oldId, oldLog, {
+        started: Date.now() - 30 * 24 * 60 * 60 * 1000,
+        exitedAt: Date.now() - 30 * 24 * 60 * 60 * 1000,
+      }),
+    ];
+    const { pi, tools, ctx, fireSessionStart } = makeFakePi({ priorEntries });
     await loadExtension(pi);
-    const bgrun = tools.get("bgrun")!;
+    await fireSessionStart(); // reconstruct + session-scoped auto-sweep runs here too
+
     const bgclean = tools.get("bgclean")!;
 
-    // Run a real job (recent log — should be kept).
-    await bgrun.execute(
-      "call-c1",
-      { command: "echo recent" },
+    // Default: this session only.
+    const scoped = await bgclean.execute(
+      "call-c2",
+      { days: 7 },
       undefined,
       undefined,
       ctx,
     );
-    await new Promise((r) => setTimeout(r, 200)); // let it finish
-
-    // Write an old log file (backdated mtime).
-    const oldPath = join(dir, "old-job-1000000000-99999.log");
-    const fs = await import("node:fs");
-    fs.writeFileSync(oldPath, "old output\n__BGRUN_EXIT__=0\n");
-    const oldTime = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000); // 30 days ago
-    fs.utimesSync(oldPath, oldTime, oldTime);
+    assert.match(scoped.content[0].text as string, /\(this session\)/);
+    assert.ok(!fs.existsSync(oldLog), "this session's old log removed");
+    assert.ok(fs.existsSync(recentLog), "this session's recent log kept");
+    assert.ok(
+      fs.existsSync(foreignLog),
+      "foreign log untouched by session-scoped bgclean",
+    );
 
-    const result = await bgclean.execute(
-      "call-c2",
-      { days: 7 },
+    // all: true sweeps the shared dir.
+    const global = await bgclean.execute(
+      "call-c3",
+      { days: 7, all: true },
       undefined,
       undefined,
       ctx,
     );
-    const text = result.content[0].text as string;
-    assert.match(text, /removed 1/);
-    assert.ok(!fs.existsSync(oldPath), "old log removed");
-    // The recent log should still exist.
-    const remaining = fs
-      .readdirSync(dir)
-      .filter((f: string) => f.endsWith(".log"));
-    assert.equal(remaining.length, 1, "recent log kept");
+    assert.match(global.content[0].text as string, /\(all sessions\)/);
+    assert.ok(!fs.existsSync(foreignLog), "foreign log removed by bgclean all");
+    assert.ok(fs.existsSync(recentLog), "recent log still kept");
   } finally {
     delete process.env.PI_BGRUN_DIR;
     rmSync(dir, { recursive: true, force: true });
@@ -1292,6 +1665,903 @@ test("bgclean: does not remove a running job's log", async () => {
     } catch {
       // already gone — fine
     }
+  } finally {
+    delete process.env.PI_BGRUN_DIR;
+    delete process.env.PI_BGRUN_GLOBAL_AUTO_CLEAN;
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("slash commands: /bgstatus, /bgtail, /bgclean registered and share the tool logic", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "pi-bgrun-test-"));
+  process.env.PI_BGRUN_DIR = dir;
+  delete process.env.PI_BGRUN_FOREIGN_JOBS;
+  delete process.env.PI_BGRUN_GLOBAL_AUTO_CLEAN;
+  try {
+    const { pi, wakes, tools, commands, ctx } = makeFakePi();
+    ctx.hasUI = true;
+    const notes: { text: string; kind: string }[] = [];
+    ctx.ui.notify = (text: string, kind: string) => notes.push({ text, kind });
+
+    await loadExtension(pi);
+
+    // All three human-facing commands are registered (/bgrun is agent-only).
+    assert.ok(commands.has("bgstatus"), "/bgstatus registered");
+    assert.ok(commands.has("bgtail"), "/bgtail registered");
+    assert.ok(commands.has("bgclean"), "/bgclean registered");
+    assert.ok(!commands.has("bgrun"), "/bgrun deliberately not a command");
+
+    // Run a real job to completion so there's something to inspect.
+    const bgrun = tools.get("bgrun")!;
+    const res = await bgrun.execute(
+      "call-cmd1",
+      { command: "echo cmd-mirror", name: "mirror-job" },
+      undefined,
+      undefined,
+      ctx,
+    );
+    const id = (res.content[0].text as string).match(/^started: ([^\n]+)/)![1];
+    await waitForWakes(wakes, 1);
+
+    // /bgstatus <id> → single-job status via notify.
+    await commands.get("bgstatus")!.handler(id, ctx);
+    assert.ok(
+      notes.some((n) => n.text.includes(id) && /: done/.test(n.text)),
+      "/bgstatus <id> notifies job status",
+    );
+
+    // /bgstatus done → listing includes the finished job.
+    await commands.get("bgstatus")!.handler("done", ctx);
+    assert.ok(
+      notes.some((n) => /mirror-job: done exit=0/.test(n.text)),
+      "/bgstatus done lists finished jobs",
+    );
+
+    // /bgtail <id> <lines> → condensed tail via notify.
+    await commands.get("bgtail")!.handler(`${id} 5`, ctx);
+    assert.ok(
+      notes.some((n) => n.text.includes("cmd-mirror")),
+      "/bgtail notifies the log tail",
+    );
+
+    // /bgtail with no args → usage error.
+    await commands.get("bgtail")!.handler("", ctx);
+    assert.ok(
+      notes.some((n) => n.kind === "error" && /Usage: \/bgtail/.test(n.text)),
+      "/bgtail without id shows usage",
+    );
+
+    // /bgclean (no args) → session-scoped summary via notify.
+    await commands.get("bgclean")!.handler("", ctx);
+    assert.ok(
+      notes.some((n) => /removed 0 job log\(s\) \(this session\)/.test(n.text)),
+      "/bgclean notifies the session-scoped summary",
+    );
+
+    // /bgclean 7 all → global scope.
+    await commands.get("bgclean")!.handler("7 all", ctx);
+    assert.ok(
+      notes.some((n) => /\(all sessions\)/.test(n.text)),
+      "/bgclean all notifies the global summary",
+    );
+  } finally {
+    delete process.env.PI_BGRUN_DIR;
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("formatSince: same-day shows time only; older days include the date", async () => {
+  const url = pathToFileURL(join(process.cwd(), "extension/index.ts")).href;
+  const mod: any = await import(url);
+  assert.equal(typeof mod.formatSince, "function");
+
+  const now = new Date("2026-09-09T10:00:00").getTime();
+  const sameDay = new Date("2026-09-09T06:30:12").getTime();
+  const prevDay = new Date("2026-09-04T15:05:40").getTime();
+  const prevMonth = new Date("2026-08-12T23:59:59").getTime();
+  const prevYear = new Date("2025-12-30T08:00:00").getTime();
+
+  // Same calendar day → time only (unchanged display).
+  assert.equal(mod.formatSince(sameDay, now), "06:30:12");
+
+  // Different day, same year → date + time.
+  const prevDayStr = mod.formatSince(prevDay, now);
+  assert.match(prevDayStr, /Sep 4/);
+  assert.match(prevDayStr, /15:05:40/);
+
+  const prevMonthStr = mod.formatSince(prevMonth, now);
+  assert.match(prevMonthStr, /Aug 12/);
+  assert.match(prevMonthStr, /23:59:59/);
+
+  // Different year → date includes the year.
+  const prevYearStr = mod.formatSince(prevYear, now);
+  assert.match(prevYearStr, /2025/);
+  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 });