@stablekernel/pi-background-run 0.1.0 → 0.2.1

package/extension/index.ts

@@ -20,9 +20,16 @@
  *    the Map from bgrun-job entries.
  * 3. Filesystem scan (cross-session, cross-restart, cross-worktree) — the jobs
  *    dir is the permanent truth: filename→pid, log→exit code, kill -0→liveness.
+ *    Surfaced via bgstatus by id (always) or includeDone (explicit); other
+ *    sessions' RUNNING jobs are adopted into the live widget only when
+ *    adoptForeignJobs is enabled.
  */
 
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  CONFIG_DIR_NAME,
+  type ExtensionAPI,
+  type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { Box, Text } from "@earendil-works/pi-tui";
 import { spawn } from "node:child_process";
@@ -35,6 +42,7 @@ import {
   renameSync,
   unlinkSync,
   statSync,
+  writeFileSync,
 } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
@@ -44,8 +52,110 @@ import { homedir } from "node:os";
 // the command fails. Never use `set -e` in the wrapper.
 const EXIT_MARKER = "__BGRUN_EXIT__=";
 
-const AUTO_CLEANUP_DAYS = 14;
 const DEFAULT_CLEANUP_DAYS = 7;
+const ADOPTED_POLL_MS = 30_000; // re-check interval for adopted (foreign) jobs
+
+// ── Configuration ───────────────────────────────────────────────────────────
+//
+// Layered: defaults ← user config file ← project config file (trusted projects
+// only) ← environment variables. Pi passes no first-class per-extension config
+// through the ExtensionAPI, so this follows the documented pattern: the
+// extension reads its own JSON config from ~/.pi/agent/pi-bgrun.json (user) and
+// <cwd>/<CONFIG_DIR_NAME>/pi-bgrun.json (project, honored only when the project
+// is trusted), with PI_BGRUN_* env vars as overrides.
+
+interface BgrunConfig {
+  jobsDir: string;
+  // 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.
+  adoptForeignJobs: boolean;
+  // Include finished jobs in bgstatus listings by default. Default false —
+  // completed jobs are noise; ask for them explicitly (bgstatus includeDone).
+  showCompletedJobs: boolean;
+  // Log retention for auto-clean sweeps and the bgclean default. Also the
+  // throttle interval for auto-clean (at most one sweep per cleanupDays).
+  cleanupDays: number;
+}
+
+interface BgrunConfigFile {
+  jobsDir?: unknown;
+  adoptForeignJobs?: unknown;
+  showCompletedJobs?: unknown;
+  cleanupDays?: unknown;
+}
+
+function parseBoolEnv(v: string | undefined): boolean | undefined {
+  if (v === undefined) return undefined;
+  const t = v.trim().toLowerCase();
+  if (["1", "true", "yes", "on"].includes(t)) return true;
+  if (["0", "false", "no", "off"].includes(t)) return false;
+  return undefined;
+}
+
+function readConfigFile(path: string): BgrunConfigFile {
+  try {
+    const raw = JSON.parse(readFileSync(path, "utf8"));
+    if (raw && typeof raw === "object" && !Array.isArray(raw))
+      return raw as BgrunConfigFile;
+  } catch {
+    // missing or malformed — treat as empty
+  }
+  return {};
+}
+
+// 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?: {
+  cwd?: string;
+  isProjectTrusted?: () => boolean;
+}): BgrunConfig {
+  const user = readConfigFile(join(homedir(), ".pi", "agent", "pi-bgrun.json"));
+  let project: BgrunConfigFile = {};
+  try {
+    if (ctx?.isProjectTrusted?.()) {
+      project = readConfigFile(
+        join(ctx.cwd ?? process.cwd(), CONFIG_DIR_NAME, "pi-bgrun.json"),
+      );
+    }
+  } catch {
+    // unreadable project config — ignore
+  }
+  const merged: BgrunConfigFile = { ...user, ...project };
+  const foreignFile =
+    typeof merged.adoptForeignJobs === "boolean"
+      ? merged.adoptForeignJobs
+      : undefined;
+  const completedFile =
+    typeof merged.showCompletedJobs === "boolean"
+      ? merged.showCompletedJobs
+      : undefined;
+  const dirFile =
+    typeof merged.jobsDir === "string" && merged.jobsDir
+      ? merged.jobsDir
+      : undefined;
+  const daysFile =
+    typeof merged.cleanupDays === "number" &&
+    Number.isFinite(merged.cleanupDays) &&
+    merged.cleanupDays > 0
+      ? merged.cleanupDays
+      : undefined;
+  const envDays = Number(process.env.PI_BGRUN_CLEANUP_DAYS);
+  const daysEnv = Number.isFinite(envDays) && envDays > 0 ? envDays : undefined;
+  return {
+    jobsDir:
+      process.env.PI_BGRUN_DIR ||
+      dirFile ||
+      join(homedir(), ".pi-bgrun", "jobs"),
+    adoptForeignJobs:
+      parseBoolEnv(process.env.PI_BGRUN_FOREIGN_JOBS) ?? foreignFile ?? false,
+    showCompletedJobs:
+      parseBoolEnv(process.env.PI_BGRUN_SHOW_COMPLETED) ??
+      completedFile ??
+      false,
+    cleanupDays: daysEnv ?? daysFile ?? DEFAULT_CLEANUP_DAYS,
+  };
+}
 
 interface JobRecord {
   id: string;
@@ -96,13 +206,21 @@ function isRunningPid(pid: number): boolean {
 
 export default function (pi: ExtensionAPI) {
   const jobs = new Map<string, JobRecord>();
-  const jobsDir = process.env.PI_BGRUN_DIR || join(homedir(), ".pi-bgrun", "jobs");
+  // Poller for adopted (foreign) jobs — they have no ChildProcess handle, so
+  // no exit event; their logs/pids are re-checked on an interval instead.
+  let adoptedPoller: ReturnType<typeof setInterval> | undefined;
 
   // ── Helpers ───────────────────────────────────────────────────────────────
 
   function makeSlug(command: string): string {
-    const raw = command.toLowerCase().replace(/[/\\.-]+/g, " ").trim();
-    const slug = raw.replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60);
+    const raw = command
+      .toLowerCase()
+      .replace(/[/\\.-]+/g, " ")
+      .trim();
+    const slug = raw
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .slice(0, 60);
     return slug || "job";
   }
 
@@ -129,7 +247,9 @@ export default function (pi: ExtensionAPI) {
   function parseExitFromLog(logPath: string): number | null {
     try {
       const content = readFileSync(logPath, "utf8");
-      const lines = content.split("\n").filter((l) => l.startsWith(EXIT_MARKER));
+      const lines = content
+        .split("\n")
+        .filter((l) => l.startsWith(EXIT_MARKER));
       if (lines.length === 0) return null;
       const match = lines[lines.length - 1].match(/^__BGRUN_EXIT__=(\d+)/);
       return match ? parseInt(match[1], 10) : null;
@@ -149,6 +269,7 @@ export default function (pi: ExtensionAPI) {
 
   function updateWidget(ctx: ExtensionContext): void {
     if (!ctx.hasUI) return;
+    revalidateAdoptedJobs();
     const running: JobRecord[] = [];
     for (const rec of jobs.values()) {
       if (rec.exitCode === undefined) running.push(rec);
@@ -159,23 +280,26 @@ export default function (pi: ExtensionAPI) {
     }
     const lines = [`📊 bgrun: ${running.length} running`];
     for (const rec of running) {
-      const startedAt = new Date(rec.started).toLocaleTimeString([], { hour12: false });
+      const startedAt = new Date(rec.started).toLocaleTimeString([], {
+        hour12: false,
+      });
       const cmd = rec.cmd.length > 40 ? rec.cmd.slice(0, 37) + "…" : rec.cmd;
       const label = rec.name ? `${rec.name} · ${cmd}` : cmd.padEnd(40);
       const tag = rec.adopted ? " (adopted)" : "";
-      lines.push(`  ${rec.id.slice(0, 20)}  ${label}  (since ${startedAt})${tag}`);
+      lines.push(
+        `  ${rec.id.slice(0, 20)}  ${label}  (since ${startedAt})${tag}`,
+      );
     }
     ctx.ui.setWidget("bgrun", lines);
   }
 
-  function clearWidget(ctx: ExtensionContext): void {
-    if (!ctx.hasUI) return;
-    ctx.ui.setWidget("bgrun", undefined);
-  }
-
   // ── Cleanup ───────────────────────────────────────────────────────────────
 
-  function cleanOldJobs(days: number, ctx?: ExtensionContext): { removed: number; kept: number; skippedRunning: number } {
+  function cleanOldJobs(
+    days: number,
+    jobsDir: string,
+    ctx?: ExtensionContext,
+  ): { removed: number; kept: number; skippedRunning: number } {
     const result = { removed: 0, kept: 0, skippedRunning: 0 };
     let entries: string[];
     try {
@@ -229,26 +353,132 @@ export default function (pi: ExtensionAPI) {
     return result;
   }
 
-  // ── Entry renderer: job cards in the transcript ───────────────────────────
+  // Throttled auto-clean: runs at session_start/session_shutdown at most once
+  // per cleanupDays (tracked via a .last-clean marker in the jobs dir). Manual
+  // bgclean always runs and refreshes the marker. This is the "7-day timer" —
+  // any session boundary after the interval fires the sweep, so long-lived
+  // sessions and restart-heavy workflows both stay covered without cleaning on
+  // every bgrun call.
+  function autoCleanJobs(ctx: ExtensionContext): void {
+    const cfg = resolveConfig(ctx);
+    const markerPath = join(cfg.jobsDir, ".last-clean");
+    try {
+      const last = Number(readFileSync(markerPath, "utf8").trim());
+      if (
+        Number.isFinite(last) &&
+        Date.now() - last < cfg.cleanupDays * 24 * 60 * 60 * 1000
+      )
+        return;
+    } catch {
+      // no marker yet — run the sweep
+    }
+    cleanOldJobs(cfg.cleanupDays, cfg.jobsDir, ctx);
+    try {
+      mkdirSync(cfg.jobsDir, { recursive: true });
+      writeFileSync(markerPath, String(Date.now()));
+    } catch {
+      // best-effort
+    }
+  }
 
-  pi.registerEntryRenderer<BgrunJobEntryData>("bgrun-job", (entry, { expanded }, theme) => {
-    const d = entry.data ?? ({ id: "?", cmd: "", started: 0, logPath: "", state: "running" } as BgrunJobEntryData);
-    const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
-    const icon = d.state === "done" ? (d.exitCode === 0 ? "✅" : "❌") : "🔄";
-    const exitStr = d.state === "done" ? ` exit=${d.exitCode ?? "?"}` : "";
-    const namePrefix = d.name ? `"${d.name}" ` : "";
-    box.addChild(new Text(`${icon} ${theme.fg("accent", "bgrun")} ${namePrefix}${d.id}${exitStr}`, 0, 0));
-    const cmdPreview = d.cmd.length > 60 ? d.cmd.slice(0, 57) + "…" : d.cmd;
-    box.addChild(new Text(theme.fg("dim", `  $ ${cmdPreview}`), 0, 0));
-    if (expanded) {
-      box.addChild(new Text(theme.fg("dim", `  log: ${d.logPath}`), 0, 0));
-      box.addChild(new Text(theme.fg("dim", `  started: ${new Date(d.started).toLocaleString()}`), 0, 0));
-      if (d.exitedAt) {
-        box.addChild(new Text(theme.fg("dim", `  finished: ${new Date(d.exitedAt).toLocaleString()}`), 0, 0));
+  // Re-check adopted (foreign) jobs: they have no exit event, so the exit
+  // marker in the log (or a dead pid) is the only completion signal. Without
+  // this, adopted jobs render as "running" forever even after they finish.
+  // Finished adopted jobs are dropped from the in-memory registry entirely —
+  // they aren't this session's history; the log stays on disk (id lookup,
+  // disk note, and cleanup all still cover it). Called from the adopted poller
+  // and before rendering the widget / listing jobs.
+  function revalidateAdoptedJobs(): void {
+    for (const [id, rec] of jobs) {
+      if (!rec.adopted || rec.exitCode !== undefined) continue;
+      let exit = parseExitFromLog(rec.logPath);
+      if (exit === null && rec.pid > 0 && !isRunningPid(rec.pid)) {
+        // pid gone with no marker — killed/crashed before the wrapper could write it
+        exit = -1;
       }
+      if (exit !== null) jobs.delete(id);
     }
-    return box;
-  });
+  }
+
+  function hasAdoptedRunning(): boolean {
+    for (const rec of jobs.values()) {
+      if (rec.adopted && rec.exitCode === undefined) return true;
+    }
+    return false;
+  }
+
+  function ensureAdoptedPoller(ctx: ExtensionContext): void {
+    if (adoptedPoller !== undefined || !hasAdoptedRunning()) return;
+    adoptedPoller = setInterval(() => {
+      revalidateAdoptedJobs();
+      updateWidget(ctx);
+      if (!hasAdoptedRunning()) stopAdoptedPoller();
+    }, ADOPTED_POLL_MS);
+    adoptedPoller.unref();
+  }
+
+  function stopAdoptedPoller(): void {
+    if (adoptedPoller !== undefined) {
+      clearInterval(adoptedPoller);
+      adoptedPoller = undefined;
+    }
+  }
+
+  // ── Entry renderer: job cards in the transcript ───────────────────────────
+
+  pi.registerEntryRenderer<BgrunJobEntryData>(
+    "bgrun-job",
+    (entry, { expanded }, theme) => {
+      const d =
+        entry.data ??
+        ({
+          id: "?",
+          cmd: "",
+          started: 0,
+          logPath: "",
+          state: "running",
+        } as BgrunJobEntryData);
+      const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
+      const icon = d.state === "done" ? (d.exitCode === 0 ? "✅" : "❌") : "🔄";
+      const exitStr = d.state === "done" ? ` exit=${d.exitCode ?? "?"}` : "";
+      const namePrefix = d.name ? `"${d.name}" ` : "";
+      box.addChild(
+        new Text(
+          `${icon} ${theme.fg("accent", "bgrun")} ${namePrefix}${d.id}${exitStr}`,
+          0,
+          0,
+        ),
+      );
+      const cmdPreview = d.cmd.length > 60 ? d.cmd.slice(0, 57) + "…" : d.cmd;
+      box.addChild(new Text(theme.fg("dim", `  $ ${cmdPreview}`), 0, 0));
+      if (expanded) {
+        box.addChild(new Text(theme.fg("dim", `  log: ${d.logPath}`), 0, 0));
+        box.addChild(
+          new Text(
+            theme.fg(
+              "dim",
+              `  started: ${new Date(d.started).toLocaleString()}`,
+            ),
+            0,
+            0,
+          ),
+        );
+        if (d.exitedAt) {
+          box.addChild(
+            new Text(
+              theme.fg(
+                "dim",
+                `  finished: ${new Date(d.exitedAt).toLocaleString()}`,
+              ),
+              0,
+              0,
+            ),
+          );
+        }
+      }
+      return box;
+    },
+  );
 
   // ── session_start: reconstruct Map from entries + auto-cleanup ────────────
 
@@ -283,52 +513,69 @@ export default function (pi: ExtensionAPI) {
         });
       }
     } catch (err) {
-      console.error("[pi-bgrun] session_start reconstruction failed:", (err as Error).message);
+      console.error(
+        "[pi-bgrun] session_start reconstruction failed:",
+        (err as Error).message,
+      );
     }
 
     // Adopt running jobs discovered from the jobs dir (started by other sessions).
-    // These render in the widget and bgstatus, but have no ChildProcess handle —
-    // no exit event, so no wake-on-exit for adopted jobs.
-    try {
-      for (const name of readdirSync(jobsDir)) {
-        if (!name.endsWith(".log")) continue;
-        const id = name.slice(0, -".log".length);
-        if (jobs.has(id)) continue;
-        const logPath = join(jobsDir, name);
-        const exit = parseExitFromLog(logPath);
-        if (exit !== null) continue; // finished — nothing to show in the widget
-        const pid = pidFromId(id);
-        if (pid === null || pid <= 0 || !isRunningPid(pid)) continue; // dead pid, marker just not written yet
-        let started = Date.now();
-        try {
-          started = statSync(logPath).birthtimeMs;
-        } catch {
-          // keep fallback
+    // Opt-in (adoptForeignJobs / PI_BGRUN_FOREIGN_JOBS=1): the jobs dir is shared
+    // across every pi session on the machine, and most sessions don't want
+    // unrelated jobs from other projects cluttering the widget. Adopted jobs
+    // have no ChildProcess handle — no exit event, so a poller re-checks their
+    // logs and pids instead, and they leave the widget once finished.
+    const cfg = resolveConfig(ctx);
+    const jobsDir = cfg.jobsDir;
+    if (cfg.adoptForeignJobs) {
+      try {
+        for (const name of readdirSync(jobsDir)) {
+          if (!name.endsWith(".log")) continue;
+          const id = name.slice(0, -".log".length);
+          if (jobs.has(id)) continue;
+          const logPath = join(jobsDir, name);
+          const exit = parseExitFromLog(logPath);
+          if (exit !== null) continue; // finished — nothing to show in the widget
+          const pid = pidFromId(id);
+          if (pid === null || pid <= 0 || !isRunningPid(pid)) continue; // dead pid, marker just not written yet
+          let started = Date.now();
+          try {
+            started = statSync(logPath).birthtimeMs;
+          } catch {
+            // keep fallback
+          }
+          jobs.set(id, {
+            id,
+            pid,
+            cmd: "(started by another session)",
+            started,
+            logPath,
+            ctx,
+            adopted: true,
+          });
         }
-        jobs.set(id, {
-          id,
-          pid,
-          cmd: "(started by another session)",
-          started,
-          logPath,
-          ctx,
-          adopted: true,
-        });
+      } catch {
+        // jobs dir doesn't exist — nothing to adopt.
       }
-    } catch {
-      // jobs dir doesn't exist — nothing to adopt.
+      ensureAdoptedPoller(ctx);
     }
 
     // Show the widget if anything is now running (covers adopted + reconstructed jobs).
     updateWidget(ctx);
-    // Auto-cleanup of old logs (14-day default, fire-and-forget).
-    cleanOldJobs(AUTO_CLEANUP_DAYS, ctx);
+    // Auto-cleanup of old logs, throttled to one sweep per cleanupDays via a
+    // marker in the jobs dir (see autoCleanJobs). Also runs on session_shutdown.
+    autoCleanJobs(ctx);
   });
 
-  pi.on("session_shutdown", async () => {
-    // Nothing to clean up — no timer; exit handlers are per-child and die with
-    // the ChildProcess handles. The widget is owned by the TUI which is tearing
-    // down anyway.
+  pi.on("session_shutdown", async (_event, ctx) => {
+    stopAdoptedPoller();
+    // Sweep old logs on the way out. Throttled via the .last-clean marker so
+    // restart-heavy workflows don't sweep more than once per cleanupDays.
+    try {
+      autoCleanJobs(ctx);
+    } catch {
+      // best-effort — shutdown must never throw
+    }
   });
 
   // ── bgrun tool ────────────────────────────────────────────────────────────
@@ -341,7 +588,8 @@ export default function (pi: ExtensionAPI) {
       "You will be woken automatically when the job finishes. Use this instead of bash for any command " +
       "expected to run >30s or emit >100 lines (tests, builds, linters). Optionally pass `name` for a " +
       "short human-readable label used in the job id, status output, and wake messages.",
-    promptSnippet: "Run a long command detached in the background; get woken on completion",
+    promptSnippet:
+      "Run a long command detached in the background; get woken on completion",
     promptGuidelines: [
       "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.",
@@ -350,7 +598,8 @@ export default function (pi: ExtensionAPI) {
     ],
     parameters: Type.Object({
       command: Type.String({
-        description: "Shell command to run in the background. Run as `sh -c`, so pipes and && work.",
+        description:
+          "Shell command to run in the background. Run as `sh -c`, so pipes and && work.",
       }),
       name: Type.Optional(
         Type.String({
@@ -367,18 +616,24 @@ export default function (pi: ExtensionAPI) {
       }
       const name = sanitizeName(rawName);
 
+      const jobsDir = resolveConfig(ctx).jobsDir;
       mkdirSync(jobsDir, { recursive: true });
 
       const slug = makeSlug(name ?? command);
       const ts = Math.floor(Date.now() / 1000);
       // The id must carry the CHILD's pid (liveness checks depend on it), but the
       // log fd must exist before spawn. Create at a temp path, rename after spawn.
-      const tmpPath = join(jobsDir, `.tmp-${slug}-${ts}-${Math.random().toString(36).slice(2, 8)}.log`);
+      const tmpPath = join(
+        jobsDir,
+        `.tmp-${slug}-${ts}-${Math.random().toString(36).slice(2, 8)}.log`,
+      );
       let logFd: number;
       try {
         logFd = openSync(tmpPath, "w");
       } catch (err) {
-        throw new Error(`bgrun: cannot create log file: ${(err as Error).message}`);
+        throw new Error(
+          `bgrun: cannot create log file: ${(err as Error).message}`,
+        );
       }
       const wrapped = `${command}; ec=$?; printf '\\n${EXIT_MARKER}%d\\n' "$ec"; exit $ec`;
 
@@ -394,7 +649,10 @@ export default function (pi: ExtensionAPI) {
       try {
         renameSync(tmpPath, logPath);
       } catch (err) {
-        console.error(`[pi-bgrun] rename to final log path failed:`, (err as Error).message);
+        console.error(
+          `[pi-bgrun] rename to final log path failed:`,
+          (err as Error).message,
+        );
       }
 
       const record: JobRecord = {
@@ -433,7 +691,8 @@ export default function (pi: ExtensionAPI) {
         delete rec.child; // release the handle reference
 
         const exitCode = code ?? parseExitFromLog(logPath) ?? -1;
-        const exitStr = exitCode >= 0 ? String(exitCode) : `signal ${signal ?? "?"}`;
+        const exitStr =
+          exitCode >= 0 ? String(exitCode) : `signal ${signal ?? "?"}`;
         const exitEmoji = exitCode === 0 ? "✅" : "❌";
         const lastLine = readLastLogLine(logPath);
 
@@ -466,14 +725,20 @@ export default function (pi: ExtensionAPI) {
           try {
             pi.sendUserMessage(wake, { deliverAs: "followUp" });
           } catch (e2) {
-            console.error(`[pi-bgrun] wake failed for job ${id}:`, (e2 as Error).message);
+            console.error(
+              `[pi-bgrun] wake failed for job ${id}:`,
+              (e2 as Error).message,
+            );
           }
         }
 
         // Toast for the human.
         if (rec.ctx.hasUI) {
           const toastLabel = (rec.name ?? command).slice(0, 50);
-          rec.ctx.ui.notify(`${exitEmoji} ${toastLabel} → exit ${exitStr}`, exitCode === 0 ? "info" : "error");
+          rec.ctx.ui.notify(
+            `${exitEmoji} ${toastLabel} → exit ${exitStr}`,
+            exitCode === 0 ? "info" : "error",
+          );
         }
 
         // Update/clear the widget.
@@ -488,7 +753,10 @@ export default function (pi: ExtensionAPI) {
 
       const startedLines = [`started: ${id}`];
       if (name) startedLines.push(`  name: ${name}`);
-      startedLines.push(`  log: ${logPath}`, `  You'll be woken automatically when it finishes.`);
+      startedLines.push(
+        `  log: ${logPath}`,
+        `  You'll be woken automatically when it finishes.`,
+      );
       return {
         content: [{ type: "text", text: startedLines.join("\n") }],
         details: { id, name, logPath, pid: childPid },
@@ -506,16 +774,22 @@ export default function (pi: ExtensionAPI) {
       "Use this for a quick peek at results; use ctx_execute_file on the log path for whole-log failure analysis.",
     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)" })),
+      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)" }),
+      ),
     }),
-    async execute(_toolCallId, params) {
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const { id, lines = 40 } = params;
       if (!id) throw new Error("bgtail: id is required");
-      const logPath = join(jobsDir, `${id}.log`);
+      const logPath = join(resolveConfig(ctx).jobsDir, `${id}.log`);
       try {
         const content = readFileSync(logPath, "utf8");
-        const all = content.split("\n").filter((l) => !l.startsWith(EXIT_MARKER) && l.trim().length > 0);
+        const all = content
+          .split("\n")
+          .filter((l) => !l.startsWith(EXIT_MARKER) && l.trim().length > 0);
         const tail = all.slice(-lines);
         return {
           content: [{ type: "text", text: tail.join("\n") || "(empty log)" }],
@@ -523,7 +797,9 @@ export default function (pi: ExtensionAPI) {
         };
       } catch {
         return {
-          content: [{ type: "text", text: `No log found for job ${id} at ${logPath}` }],
+          content: [
+            { type: "text", text: `No log found for job ${id} at ${logPath}` },
+          ],
           details: { id, linesShown: 0, logPath, notFound: true },
           isError: true,
         };
@@ -537,38 +813,73 @@ export default function (pi: ExtensionAPI) {
     name: "bgstatus",
     label: "Background Job Status",
     description:
-      "Show status of background jobs. With an id: one job's state + exit code. Without: list all known jobs.",
+      "Show status of background jobs. With an id: one job's state + exit code. Without: list this session's " +
+      "running jobs (finished jobs are hidden by default — pass includeDone or set showCompletedJobs to list " +
+      "them; other sessions' jobs are only listed when adoptForeignJobs is enabled).",
     promptSnippet: "Check status of bgrun jobs",
     parameters: Type.Object({
-      id: Type.Optional(Type.String({ description: "Optional job id to inspect" })),
+      id: Type.Optional(
+        Type.String({ description: "Optional job id to inspect" }),
+      ),
+      includeDone: Type.Optional(
+        Type.Boolean({
+          description:
+            "Include finished jobs (and other logs on disk) in the listing",
+        }),
+      ),
     }),
     async execute(
       _toolCallId,
       params,
-    ): Promise<{ content: { type: "text"; text: string }[]; details: BgStatusDetails; isError?: boolean }> {
+      _signal,
+      _onUpdate,
+      ctx,
+    ): Promise<{
+      content: { type: "text"; text: string }[];
+      details: BgStatusDetails;
+      isError?: boolean;
+    }> {
       const { id } = params;
+      const cfg = resolveConfig(ctx);
+      const jobsDir = cfg.jobsDir;
       if (id) {
         const rec = jobs.get(id);
         if (rec) {
-          const state = rec.exitCode !== undefined ? "done" : "running";
-          const exit = rec.exitCode !== undefined ? ` exit=${rec.exitCode}` : "";
+          const state = rec.exitCode === undefined ? "running" : "done";
+          const exit =
+            rec.exitCode === undefined ? "" : ` exit=${rec.exitCode}`;
           const lines = [`${id}: ${state}${exit}`];
           if (rec.name) lines.push(`  name: ${rec.name}`);
           lines.push(`  cmd: ${rec.cmd}`, `  log: ${rec.logPath}`);
           return {
             content: [{ type: "text", text: lines.join("\n") }],
-            details: { id, state, exitCode: rec.exitCode ?? undefined, cmd: rec.cmd, name: rec.name, recovered: false },
+            details: {
+              id,
+              state,
+              exitCode: rec.exitCode ?? undefined,
+              cmd: rec.cmd,
+              name: rec.name,
+              recovered: false,
+            },
           };
         }
         const logPath = join(jobsDir, `${id}.log`);
         try {
           const exit = parseExitFromLog(logPath);
-          const state = exit !== null ? "done" : "running";
+          const state = exit === null ? "running" : "done";
           return {
             content: [
-              { type: "text", text: `${id}: ${state}${exit !== null ? ` exit=${exit}` : ""} (recovered from log)\n  log: ${logPath}` },
+              {
+                type: "text",
+                text: `${id}: ${state}${exit === null ? "" : ` exit=${exit}`} (recovered from log)\n  log: ${logPath}`,
+              },
             ],
-            details: { id, state, exitCode: exit ?? undefined, recovered: true },
+            details: {
+              id,
+              state,
+              exitCode: exit ?? undefined,
+              recovered: true,
+            },
           };
         } catch {
           return {
@@ -578,16 +889,27 @@ export default function (pi: ExtensionAPI) {
           };
         }
       }
-      // List all: merge in-memory records with a directory scan of log files.
+      // List: this session's jobs (running by default; finished only when
+      // includeDone / showCompletedJobs is set), plus — when opted in — other
+      // sessions' jobs from the shared jobs dir. Hidden disk logs get a
+      // one-line count instead of spamming the listing.
+      const showDone = params.includeDone ?? cfg.showCompletedJobs;
+      revalidateAdoptedJobs();
+      updateWidget(ctx);
       const lines: string[] = [];
       const seen = new Set<string>();
       for (const [jid, rec] of jobs) {
         seen.add(jid);
-        const state = rec.exitCode !== undefined ? "done" : "running";
-        const exit = rec.exitCode !== undefined ? ` exit=${rec.exitCode}` : "";
-        const label = rec.name ? `${jid} — ${rec.name}` : jid;
-        lines.push(`  ${label}: ${state}${exit}`);
+        if (rec.exitCode === undefined || showDone) {
+          const state = rec.exitCode === undefined ? "running" : "done";
+          const exit =
+            rec.exitCode === undefined ? "" : ` exit=${rec.exitCode}`;
+          const label = rec.name ? `${jid} — ${rec.name}` : jid;
+          const from = rec.adopted ? " (adopted)" : "";
+          lines.push(`  ${label}: ${state}${exit}${from}`);
+        }
       }
+      let hiddenOnDisk = 0;
       try {
         for (const name of readdirSync(jobsDir)) {
           if (!name.endsWith(".log")) continue;
@@ -595,12 +917,28 @@ export default function (pi: ExtensionAPI) {
           if (seen.has(jid)) continue;
           const logPath = join(jobsDir, name);
           const exit = parseExitFromLog(logPath);
-          const state = exit !== null ? "done" : "running";
-          lines.push(`  ${jid}: ${state}${exit !== null ? ` exit=${exit}` : ""} (from log)`);
+          if (exit !== null) {
+            // finished log on disk (other or older session)
+            if (showDone) {
+              lines.push(`  ${jid}: done exit=${exit} (from log)`);
+            } else {
+              hiddenOnDisk++;
+            }
+          } else if (cfg.adoptForeignJobs) {
+            // running foreign job — only surfaced when adoption is enabled
+            lines.push(`  ${jid}: running (from log)`);
+          } else {
+            hiddenOnDisk++;
+          }
         }
       } catch {
         // jobs dir doesn't exist — nothing to scan.
       }
+      if (hiddenOnDisk > 0) {
+        lines.push(
+          `  (${hiddenOnDisk} more job log(s) on disk — pass includeDone to list, bgclean to prune)`,
+        );
+      }
       if (lines.length === 0) {
         return {
           content: [{ type: "text", text: "(no bgrun jobs)" }],
@@ -625,15 +963,28 @@ export default function (pi: ExtensionAPI) {
     promptSnippet: "Remove old bgrun job logs",
     parameters: Type.Object({
       days: Type.Optional(
-        Type.Number({ description: "Remove logs older than this many days (default 7)" }),
+        Type.Number({
+          description: "Remove logs older than this many days (default 7)",
+        }),
       ),
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-      const { days = DEFAULT_CLEANUP_DAYS } = params;
+      const cfg = resolveConfig(ctx);
+      const { days = cfg.cleanupDays } = params;
       if (typeof days !== "number" || days < 0 || !Number.isFinite(days)) {
-        throw new Error(`bgclean: days must be a non-negative number, got ${days}`);
+        throw new Error(
+          `bgclean: days must be a non-negative number, got ${days}`,
+        );
+      }
+      const result = cleanOldJobs(days, cfg.jobsDir, ctx);
+      // Manual clean refreshes the throttle marker so the next auto-sweep
+      // doesn't immediately redo this work.
+      try {
+        mkdirSync(cfg.jobsDir, { recursive: true });
+        writeFileSync(join(cfg.jobsDir, ".last-clean"), String(Date.now()));
+      } catch {
+        // best-effort
       }
-      const result = cleanOldJobs(days, ctx);
       const summary = `removed ${result.removed} job log(s), kept ${result.kept}${result.skippedRunning > 0 ? `, skipped ${result.skippedRunning} running` : ""}`;
       return {
         content: [{ type: "text", text: summary }],