@gavin-hu/my-pi-agent 0.18.0 → 0.20.0

package/{extensions/job/README.md → docs/extensions/job.md}

@@ -5,47 +5,51 @@ the background and manage them without blocking the turn. A job starts
 immediately and keeps running across tool calls; poll it, tail its output, wait
 for it, or kill it.
 
-<img src="../../assets/job.png" alt="The /jobs screen: a summary line, the job rows with status glyphs and elapsed times, and the focused job's command, cwd, and last output line" width="100%">
-
+## Capabilities
+
+Status records what a reader can rely on: **Shipped** is in a tagged release, **Unreleased** is complete in the current tree but not yet tagged, and **Partial** has one released part and one unreleased part. Rows are ordered by user value, highest first.
+
+| Capability | How | What you get | Status |
+|---|---|---|---|
+| Background execution | `job` (`start`) | A long build, test suite, server, or watcher keeps running while the turn moves on. | Shipped |
+| Job listing | `job` (`list`), `/jobs` | This session's jobs with status and elapsed time, and a live peer session's tagged `peer`. | Shipped |
+| Polling and waiting | `job` (`status`, `logs`, `wait`) | One call returns a job's status, a bounded output tail, or blocks until it finishes. | Shipped |
+| Stopping jobs | `job` (`kill` with `signal`) | A running job receives `SIGTERM`, `SIGKILL`, or `SIGINT`, and a finished one can be cleared. | Shipped |
+| Selective clear | `job` (`clear` with `id`, `all`) | Clear one finished record by id, or remove running jobs with `all` after a confirmation in the screen. | Shipped |
+| Start deadline | `timeoutMs` on `start` | A job is killed after the requested wall-clock limit instead of running until the session ends. | Shipped |
+| Kill escalation | `killGraceMs` | A kill sends `SIGTERM` first, then `SIGKILL` after the grace period, on a user kill and on shutdown. | Shipped |
+| Stdin driving | `job` (`send` with `input`, `newline`, `eof`) | A line or a bare keystroke reaches a running job started with `stdin: true`, and `eof` closes its input. | Shipped |
+| Rotating logs | `job` (`logs`), `job.maxLogBytes` | stdout and stderr stream to an append-only log that rotates at 8 MiB, so a chatty job cannot fill the disk. | Shipped |
+| Status chips | `job.showStatus` | `▸ N` running and `✗ N` unreported-failure counts in the footer. | Shipped |
+| Completion reporting | `job` (`wake`), `job.wakeOnFinish` | A finished job is reported at the next turn, or triggers one as soon as the agent is idle. | Shipped |
+| Job screen | `/jobs` | Select a job, open its log, kill it, or clear finished ones, with a confirmation on the destructive verbs. | Shipped |
+| Detached lifetime | `job` (`start`, `detached`) | A POSIX job outlives the session and is reattached next time; Windows refuses the detach instead of faking one. | Shipped |
+| Finished-job pruning | `maxJobs` | The registry drops the oldest finished records once the configured count is exceeded. | Shipped |
+| Structured result | tool-result `details` | Every call returns a `JobDetails` record of the job and the action's outcome. | Shipped |
+
+## Quickstart
+
+```bash
+pi --extension ./extensions/job   # load just this extension
+pi -e .                           # load the whole @gavin-hu/my-pi-agent package
+pi install ./                     # install the package
 ```
-pi --extension ./extensions/job    # load just this extension
-pi -e .                            # load the whole @gavin-hu/my-pi-agent package
-pi install ./                      # install the package
+
+```text
+/jobs                             # this session's jobs, and their logs
 ```
 
-## Tool rendering
+The model starts a job with `job start` and collects it with `job status`,
+`job logs`, or `job wait`.
 
-How the `job` call and its result look in the transcript — the call line as a headline and the body indented under it:
+## Tool
 
 <img src="../../assets/tools/job.png" alt="The job tool's result: the call line and an indented body with a finished and a failed job row, each with its status glyph and elapsed time" width="100%">
 
-## What it does
-
-- Registers one model-callable tool, `job`, with actions `start`, `list`,
-  `status`, `logs`, `send`, `kill`, `wait`, and `clear`.
-- Shows this session's jobs, and — tagged `peer` — a live peer session's, so two
-  Pi sessions on one repo can see each other's builds; the peer's rows are
-  read-only on the screen.
-- Runs each command in its own process group, streaming stdout and stderr to an
-  append-only log file under `~/.pi/agent/jobs/<project>/`. A segment rotates
-  to `<id>.log.1` at `maxLogBytes` (8 MiB by default), so a chatty job cannot
-  fill the disk, and `logs` reads across the boundary.
-- Feeds a running job input when it was started with `stdin: true`: `send`
-  writes a line (or a bare keystroke) to its stdin, and `eof: true` closes it, so
-  a REPL, a debugger prompt, or a `read` can be driven without a TTY.
-- Shows a `▸ N` running status chip and a separate `✗ N` unreported-failure
-  chip for this session's jobs, plus a `/jobs` screen for selecting, tailing,
-  killing, and clearing.
-- Reports finished jobs to the model at the start of the next turn, or — for
-  jobs started with `wake: true` — by triggering one turn as soon as the agent is
-  idle, including right after a running turn settles.
-- Kills session-owned jobs on shutdown so no process is left behind; on POSIX,
-  start a job with `detached: true` to keep it running and reattach next session.
-  A detached job points its own output straight at its log file, so it keeps
-  logging after this process ends. Windows has neither a process group to leave
-  nor a shell `EXIT` trap, so it refuses the detach instead of faking one.
-
-## Tool
+`job` — `executionMode: "sequential"`, `readOnlyHint: false`,
+`destructiveHint: true`, `idempotentHint: false`, `openWorldHint: true`. One
+tool with eight actions: `start` returns immediately with an id, and the rest
+act on it.
 
 | Field | Value |
 |---|---|
@@ -147,20 +151,27 @@ job status j1
 ✓ j1 tests · exit 0 · 12.0s
 ```
 
-### Command: `/jobs`
+## Commands
 
 `/jobs` opens an interactive list in the TUI, and prints a text summary
-elsewhere. The list shows the jobs this session started, a dead session's
-records adopted into it, and a live peer session's jobs tagged `peer`. On
-the screen: `↑`/`↓` or `j`/`k` select, `PgUp`/`PgDn` page, `Home`/`End` jump,
-`Enter`/`l` opens the log pane, `d` (or `K`) kills the selected running job,
-`x` clears finished jobs, `Esc`/`q` closes. `d` and `x` ask for a `y`/`N`
-confirmation before acting, so a stray key cannot kill a build; when `x` would
-drop an unreported result, the prompt says how many. A `d` on a finished job (or
-an `x` with nothing finished) says so instead of doing nothing. Another
-session's row opens its log but is otherwise left alone: `d` answers
-`j9 is another session's job; not killed.`, and `x` counts and clears only this
-session's finished jobs. In the log pane,
+elsewhere.
+
+<img src="../../assets/screens/job.png" alt="The /jobs screen: a summary line, the job rows with status glyphs and elapsed times, and the focused job's command, cwd, and last output line" width="100%">
+
+| Command | What it does |
+|---|---|
+| `/jobs` | Show and manage background jobs: an interactive list in the TUI, a text summary elsewhere. |
+
+The list shows the jobs this session started, a dead session's records adopted
+into it, and a live peer session's jobs tagged `peer`. On the screen: `↑`/`↓` or
+`j`/`k` select, `PgUp`/`PgDn` page, `Home`/`End` jump, `Enter`/`l` opens the log
+pane, `d` (or `K`) kills the selected running job, `x` clears finished jobs,
+`Esc`/`q` closes. `d` and `x` ask for a `y`/`N` confirmation before acting, so a
+stray key cannot kill a build; when `x` would drop an unreported result, the
+prompt says how many. A `d` on a finished job (or an `x` with nothing finished)
+says so instead of doing nothing. Another session's row opens its log but is
+otherwise left alone: `d` answers `j9 is another session's job; not killed.`,
+and `x` counts and clears only this session's finished jobs. In the log pane,
 `↑`/`↓`, `PgUp`/`PgDn`, `Home`/`End`, and `g`/`G` scroll; the view follows the
 tail until you scroll up, and `Esc`/`Backspace`/`q` returns to the list. The
 pane's subheader names the job's log file, notes when only a bounded tail is
@@ -172,8 +183,7 @@ chips count only this session's. Running jobs come first, then recent finished
 ones, and a focused detail pane follows (command, cwd, outcome, the owner when
 it is another session, and the last output line). Selection is tracked by job
 id, so the live re-sort cannot move the cursor or switch the open log out from
-under the user.
-Any dock screen (`/todos`, `/jobs`, `/rewind`, or the
+under the user. Any dock screen (`/todos`, `/jobs`, `/rewind`, or the
 `question` questionnaire) hides the above-editor goal/todo rails for its
 lifetime and restores them on close.
 
@@ -185,8 +195,9 @@ notifications instead.
 
 ## Configuration
 
-The `job` section of the shared `bytefly.json` (global document, then project
-document, project wins):
+The keys live in the `job` section of the shared `bytefly.json`; resolution rules
+are in
+[`../configuration.md`](../configuration.md#job--background-jobs).
 
 | Key | Default | Meaning |
 |---|---|---|
@@ -354,7 +365,7 @@ rewritten.
   cached from the stdout stream for `status`/`wait`/completion notes; only the
   `/jobs` log pane reads the file.
 - **Pure logic split from IO.** `format.ts` and the reconciliation in
-  `registry.ts` are pure; `process.ts` and the runtime take injectable
+  `registry.ts` are pure; the runtime takes injectable
   spawn/liveness/kill/clock functions, so the whole suite runs without
   launching a process.
 - **The transcript reuses the `/jobs` grammar.** `job list` renders the same
@@ -377,7 +388,6 @@ rewritten.
 | `schema.ts` | Parameter schema and pure validation (a `JobCall` union). |
 | `config.ts` | The `job` section of `bytefly.json`: loading and clamping. |
 | `format.ts` | Pure formatting, duration, and transcript outcome-line helpers; sanitization is `lib/format.ts`'s `sanitizeUntrustedLine`. |
-| `process.ts` | The job-only process remainder: the `LivenessFn` seam and the `ps` start-time token. Spawn, tree-kill, and liveness itself come from `lib/spawn.ts`. |
 | `paths.ts` | Session/marker/registry/status file-name helpers. |
 | `registry.ts` | Per-session registry load/merge, legacy migration, and pure reconciliation. |
 | `reservations.ts` | Atomic `O_EXCL` job-id reservation and release. |

package/{extensions/memory/README.md → docs/extensions/memory.md}

@@ -7,7 +7,28 @@ live as human-editable markdown, not in the session branch, so they survive
 `AGENTS.md`; `memory` is for the one-liners the model should not have to be
 reminded of twice.
 
-<img src="../../assets/memory.png" alt="The /memory picker: a Memory title rule, an `All · 3 project, 2 global` summary, five notes tagged by scope with the focused one marked, and the key hints" width="100%">
+<img src="../../assets/screens/memory.png" alt="The /memory picker: a Memory title rule, an `All · 3 project, 2 global` summary, five notes tagged by scope with the focused one marked, and the key hints" width="100%">
+
+## Capabilities
+
+Status records what a reader can rely on: **Shipped** is in a tagged release, **Unreleased** is complete in the current tree but not yet tagged, and **Partial** has one released part and one unreleased part. Rows are ordered by user value, highest first.
+
+| Capability | How | What you get | Status |
+|---|---|---|---|
+| Automatic recall | the `[MEMORY]` context message | Stored notes arrive before each run, bounded by a byte cap, without the user asking. | Shipped |
+| Durable notes | `memory` | The model adds, updates, forgets, or lists short facts that outlive the session branch. | Shipped |
+| Two scopes | the `scope` parameter, `/memory path` | Notes are global or per-project, each a plain markdown file you can edit by hand. | Shipped |
+| Repo-root anchor | the `project` store | The project store is anchored at the repository root, so a subdirectory and every worktree read the same file. | Shipped |
+| Note picker | `/memory` | Add, edit, forget, merge, or move a note in the TUI, with a scope filter and a reload. | Shipped |
+| Whole-file editing | `/memory edit`, `/memory clear` | The file in the multi-line editor, or a scope cleared behind a confirm. | Shipped |
+| Duplicate guard | `memory` `add` | Re-stating a stored fact in new words is a no-op that names the existing note. | Shipped |
+| Store health | `/memory doctor` | Counts, file bytes, the injection budget with its omissions, and near-duplicate pairs. | Shipped |
+| Store freshness | `memory`, `/memory reload` | A hand edit is picked up on the next read, and `reload` forces it. | Shipped |
+| Recall off switch | `memory.inject` | Injection can be turned off without deleting the notes, for a session that must not receive them. | Shipped |
+| Trust-gated project store | the `project` scope | The project file is read and written only when the project is trusted. | Shipped |
+| Headless coverage | `list`, `path`, `reload`, `doctor` outside `tui` | Read-only verbs notify everywhere; picker, edit, and clear require an interactive session. | Shipped |
+
+## Quickstart
 
 ```bash
 pi --extension ./extensions/memory    # load just this extension
@@ -15,61 +36,42 @@ pi -e .                               # load the whole @gavin-hu/my-pi-agent pac
 pi install ./                         # install the package
 ```
 
-## Tool rendering
+```text
+/memory                               # open the picker (a listing elsewhere)
+/memory doctor                        # check the stores and the injection budget
+```
+
+## Tool
 
 How the `memory` call and its result look in the transcript — the call line as a headline and the body indented under it:
 
 <img src="../../assets/tools/memory.png" alt="The memory tool's result: the call line and an indented body confirming the write and the new project and global counts" width="100%">
 
-## What it does
-
-- Registers one model-callable tool, `memory`, with four actions: `add` a note,
-  `update` an exact note, `forget` an exact note, or `list` what is stored.
-  `add` is a no-op when the note already exists, ignoring case and trailing
-  punctuation, so re-stating a fact in new words does not grow the store.
-- Keeps two stores, both plain markdown with one bullet per note:
-
-  | Scope | File |
-  |---|---|
-  | `global` | `<agent-dir>/memory.md` |
-  | `project` | `<repo-root>/.pi/memory.md` |
-
-  The project store is anchored at the **repository root**, so it is stable when
-  Pi runs from a subdirectory and shared across git worktrees.
-- Injects the stored notes as a hidden `[MEMORY]` context message before each
-  run, bounded by a byte cap, so the model recalls them without being asked.
-- Re-reads each store when its file changes on disk (compared by mtime and size),
-  so an external edit lands in the same session without a restart.
-- Exposes `/memory`: in the TUI it opens a picker to add, edit, or forget a
-  single note, merge two notes into one, move a note to the other scope, filter
-  by scope, and reload; elsewhere it lists the store. `/memory path`, `edit`, and `clear` print the file paths,
-  open the multi-line editor, and clear a scope; `/memory doctor` reports store
-  health.
-- Reports store health with `/memory doctor`: note counts and file bytes per
-  scope, how much of the `maxInjectBytes` budget the injection uses and which
-  scope overflowed it, and the near-duplicate pairs the conservative key already
-  considers one fact. It is read-only — the report names the pair and the picker
-  merges it.
-- Loads and writes the project store only when the project is trusted, sanitizes
-  every note to one terminal-safe line, and writes atomically.
+`memory` — direct exposure (the default), `executionMode: "sequential"`,
+annotations `readOnlyHint: false`, `destructiveHint: true` (forget deletes),
+`idempotentHint: true`, `openWorldHint: false`. It is a singleton tool with an
+action switch (like `job`); `list` reads both stores, and the other three
+mutate one.
 
-## Tool
+| Parameter | Type | Meaning |
+|---|---|---|
+| `action` | `add` \| `update` \| `forget` \| `list` | What to do with the store. |
+| `text` | string | The note to add, or the exact note to update or forget. Required for `add`/`update`/`forget`. |
+| `to` | string | The replacement note for `update`. Required for `update`. |
+| `scope` | `project` (default) \| `global` | Which store `add`/`update`/`forget` changes. |
 
-`memory` is a singleton tool with an action switch (like `job`). It declares an
-`outputSchema` and returns matching `structuredContent`
-(`{ action, scope, project, global, changed, entry?, to?, existing?, error? }`).
+Result (`details` / `structuredContent`, `MemoryResult`): `{ action, scope,
+project, global, changed, entry?, to?, existing?, error? }`.
 
-| Field | Value |
+The two stores are plain markdown with one bullet per note:
+
+| Scope | File |
 |---|---|
-| `name` | `memory` |
-| `action` | `add` \| `update` \| `forget` \| `list` |
-| `text` | The note to add, or the exact note to update or forget. Required for `add`/`update`/`forget`. |
-| `to` | The replacement note for `update`. Required for `update`. |
-| `scope` | `project` (default) or `global`. Used by `add`/`update`/`forget`. |
-| `exposure` | `direct` (default). |
-| `executionMode` | `sequential` — calls share the cached stores. |
-| `annotations` | `readOnlyHint: false`, `destructiveHint: true` (forget deletes), `idempotentHint: true`, `openWorldHint: false`. |
-| `outputSchema` | `MemoryResult` — also returned as `structuredContent`. |
+| `global` | `<agent-dir>/memory.md` |
+| `project` | `<repo-root>/.pi/memory.md` |
+
+The project store is anchored at the **repository root**, so it is stable when
+Pi runs from a subdirectory and shared across git worktrees.
 
 Validation happens before anything is written (a violation returns an error
 result carrying the unchanged notes, never a half-apply): a known action; a
@@ -97,6 +99,10 @@ or stem both survive.
 
 ## Commands
 
+`/memory` opens the picker in the TUI and notifies the stored notes elsewhere.
+`list`, `path`, `reload`, and `doctor` report through `notify` in every mode;
+`edit` and `clear` need an interactive session.
+
 | Command | What it does |
 |---|---|
 | `/memory` | In the TUI, open the picker (add, edit, forget, merge, or move notes; `s`/Tab filters by scope; `r` reloads). Other modes notify the stored notes. |
@@ -145,9 +151,8 @@ not change it.
 
 ## Configuration
 
-The `memory` section of the shared `bytefly.json`, read from the global
-document then the project document (project values override global; missing or
-malformed documents are ignored):
+The `memory` section of the shared `bytefly.json`; resolution rules are in
+[`../configuration.md`](../configuration.md#memory--durable-notes):
 
 | Key | Default | Meaning |
 |---|---|---|
@@ -177,10 +182,13 @@ skill. Mitigations:
 
 - Notes are injected whole (bounded), so a very large store is truncated with a
   `(+N more; use the memory tool)` tail rather than summarized.
-- External edits to a store are picked up automatically by an mtime/size check
-  before the next injection or tool call. A same-size edit within one filesystem
-  mtime tick is only caught by `/memory reload`; a store that becomes unreadable
-  (symlinked or over the size cap) keeps its last good view until fixed.
+- External edits to a store are picked up automatically by an `(mtimeNs, size)`
+  check before the next injection or tool call, so a same-size edit inside one
+  millisecond is seen. The residual case is the filesystem's own resolution: where
+  the stamp is no finer than the last one read — a one-second mtime, or a write
+  the kernel coalesced — only `/memory reload` catches the edit. A store that
+  becomes unreadable (symlinked or over the size cap) keeps its last good view
+  until fixed.
 - Matching for `forget` is exact and case-sensitive.
 - The near-duplicate guard on `add` is deliberately conservative: it folds
   case, whitespace runs, and trailing sentence punctuation only, never word
@@ -188,8 +196,8 @@ skill. Mitigations:
   both be stored; `/memory doctor` reports the pairs the key does consider equal,
   and `m` in the picker merges them under wording you write.
 - `update` replaces every exact match of `text`; a replacement that already
-exists under a different note can leave a duplicate. Forget the old note first
-when consolidating, or merge the pair in the picker afterward.
+  exists under a different note can leave a duplicate. Forget the old note first
+  when consolidating, or merge the pair in the picker afterward.
 - Only one note per line; multi-line notes are collapsed to a single line.
 
 ## Non-goals
@@ -237,10 +245,13 @@ when consolidating, or merge the pair in the picker afterward.
   writers for the same file, and each write lands atomically via a temp file and
   rename; `executionMode: "sequential"` keeps in-process calls ordered as well.
 - **Stamped cache, not a watcher.** The session cache is validated against each
-  file's `(mtimeMs, size)` stamp before every read, matching the worktree cache's
-  freshness check rather than holding an `fs.watch` handle. A mutation adopts the
-  fresh on-disk stamp, so a self-write is not mistaken for an external change, and
-  a failed re-read keeps the last good view instead of breaking the run.
+  file's `(mtimeNs, size)` stamp before every read rather than holding an
+  `fs.watch` handle. The stamp is the nanosecond field a bigint `stat` returns, so
+  a same-size edit in the same millisecond is a distinct state; a millisecond
+  stamp would have to read the file on every run to tell them apart. A mutation
+  adopts the fresh on-disk stamp, so a self-write is not mistaken for an external
+  change, and a failed re-read keeps the last good view instead of breaking the
+  run.
 
 ## Files