@stablekernel/pi-background-run 0.3.0 → 0.5.0

package/package.json

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

package/skill/run-bg/SKILL.md

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