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

package/docs/extensions/job.md

@@ -7,25 +7,23 @@ for it, or kill it.
 
 ## 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 |
+| Capability | How | What you get |
+|---|---|---|
+| Background execution | `job` (`start`) | A long build, test suite, server, or watcher keeps running while the turn moves on. |
+| Job listing | `job` (`list`), `/jobs` | This session's jobs with status and elapsed time, and a live peer session's tagged `peer`. |
+| Polling and waiting | `job` (`status`, `logs`, `wait`) | One call returns a job's status, a bounded output tail, or blocks until it finishes. |
+| Stopping jobs | `job` (`kill` with `signal`) | A running job receives `SIGTERM`, `SIGKILL`, or `SIGINT`, and a finished one can be cleared. |
+| 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. |
+| Start deadline | `timeoutMs` on `start` | A job is killed after the requested wall-clock limit instead of running until the session ends. |
+| Kill escalation | `killGraceMs` | A kill sends `SIGTERM` first, then `SIGKILL` after the grace period, on a user kill and on shutdown. |
+| 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. |
+| 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. |
+| Status chips | `job.showStatus` | `▸ N` running and `✗ N` unreported-failure counts in the footer. |
+| 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. |
+| Job screen | `/jobs` | Select a job, open its log, kill it, or clear finished ones, with a confirmation on the destructive verbs. |
+| Detached lifetime | `job` (`start`, `detached`) | A POSIX job outlives the session and is reattached next time; Windows refuses the detach instead of faking one. |
+| Finished-job pruning | `maxJobs` | The registry drops the oldest finished records once the configured count is exceeded. |
+| Structured result | tool-result `details` | Every call returns a `JobDetails` record of the job and the action's outcome. |
 
 ## Quickstart
 
@@ -210,7 +208,7 @@ are in
 | `maxLogBytes` | `8388608` | Bytes a log segment may reach before it rotates to `<id>.log.1`; `0` keeps logs unbounded. |
 | `killGraceMs` | `5000` | Grace before SIGTERM escalates to SIGKILL. |
 | `repaintMs` | `1000` | Status-chip refresh interval while jobs run. |
-| `sessionTtlMs` | `60000` | How long a session heartbeat is trusted before its jobs may be reaped. |
+| `sessionTtlMs` | `60000` | How old a session heartbeat may be before its pid is re-checked for reuse. |
 | `registryDir` | — | Override the registry/log directory. |
 
 ## Security
@@ -236,7 +234,9 @@ rewritten.
   kill or clear it, and the tool's `clear` refuses that record too; the tool can
   still take one over by explicit id (`status`/`logs`/`kill`, where `kill`
   adopts it). Chips, completion notices, and pruning stay this session's own, so
-  a peer's finished job waits for that session to clear it.
+  a peer's finished job waits for that session to clear it — including when that
+  session has been idle long enough for its heartbeat to age, because the
+  heartbeat only ticks while a job is running.
 - **A carriage return is not a line break.** Output is split on `\n` only; a
   progress rewrite (`10%\r50%\r100%`) is one line whose sanitized form keeps the
   text after the last `\r`. A program that only ever emits `\r` therefore
@@ -279,7 +279,7 @@ rewritten.
 | `outputSchema` / `structuredContent` | None. Results return `JobDetails` in tool-result `details` only. |
 | State storage | One durable registry file per session, `~/.pi/agent/jobs/<projectKey>/registry-<sessionHash>.json` (keyed by the session cwd, so entering a worktree does not move it), merged from every session file on load; a dead session's records are adopted and a legacy shared `registry.json` is migrated once. Ids are reserved with an atomic `O_EXCL` `<id>.lock` before `start`, and a POSIX job's exit code is written to a per-job `.status` file. Tool results carry `JobDetails`; unreported completions arrive as a shared transcript notice (`my-pi-agent/notice`) at `before_agent_start`. |
 | Lifecycle | `session_start` loads and reconciles the registry and arms `onFinish` and `onComplete`; `session_shutdown` kills session-owned jobs and clears both status chips. `session_tree` repaints; `agent_start`/`agent_settled` track busy; `context` prunes stale notices of its own source. |
-| Event bus | Each job that reaches a terminal state is published on `my-pi-agent/job-finished` (`lib/events.ts`) with its id, label, status, exit code, and signal, from the one `settle` path every transition goes through. bytefly's notify capability subscribes there instead of importing this extension. |
+| Event bus | Each job that reaches a terminal state is published on `my-pi-agent/job-finished` (`lib/events.ts`) with its id, label, status, exit code, and signal, from the one path every transition goes through — a close event, a pid observed gone on the clock, a gone peer's leftover reaped, and an orphan killed while the registry loads — which announces the completion and fires the one wake turn together. A peer's record settled here is adopted, so its completion is this session's to report. bytefly's notify capability subscribes there instead of importing this extension. |
 
 ## Design notes
 
@@ -322,10 +322,13 @@ rewritten.
   per session, `start` claims the next `j<n>` with an `O_EXCL` `<id>.lock`
   before spawning, so two sessions cannot pick the same id from a stale read;
   the reservation is pruned once the id is committed to a registry file.
-- **Sessions heartbeat; reconciliation is owner-aware.** Each session writes a
-  liveness marker, so a peer's live non-detached job is not reaped until its
-  owner's marker expires. `persist` merges onto a fresh read and drops ids this
-  session deleted.
+- **Sessions heartbeat; ownership is the process.** Each session writes a liveness
+  marker (its pid, that process's start time, and its last beat), and the beat only
+  ticks while a job runs — so a session that has finished its work goes quiet rather
+  than dying. Only a session that is *gone* — its pid is dead, or a reused one —
+  gives up its records: a quiet peer keeps its file, its marker, and its jobs, and a
+  peer's live non-detached job is never reaped. `persist` merges onto a fresh read and
+  drops ids this session deleted.
 - **Exit codes survive a session boundary.** A POSIX job is spawned behind an
   `EXIT` trap that writes `$?` to a per-job `.status` file (path passed in the
   environment); a later session reads it when it finds a dead pid and reports
@@ -336,14 +339,17 @@ rewritten.
   `detached` dev server survives.
 - **Pid reuse is guarded by a start-time token.** Before signalling an unowned
   pid, its best-effort start token (`ps -o lstart=`) is re-checked; a mismatch
-  is treated as gone instead of as a signal. Where no token is available the
-  check degrades to liveness.
+  is treated as gone instead of as a signal. The same token is written into a
+  session's marker, so a pid that has been reused is a gone session rather than a
+  quiet one. Where no token is available the check degrades to liveness.
 - **Reattached jobs are polled.** A reattached detached job has no child
   handle, so its `close` event never fires; the repaint clock polls it and
   settles it (recovering an exit code from the status file, else `unknown`)
   when the pid disappears.
 - **Shared seams, job policy.** The spawn/tree-kill/liveness seam
-  (`lib/spawn.ts`), the byte-safe line splitter (`lib/lines.ts`), the
+  (`lib/spawn.ts`), the command supervisor (`lib/child.ts`, which `watch` drives
+  too: one SIGTERM → SIGKILL body, each extension's own grace), the byte-safe
+  line splitter (`lib/lines.ts`), the
   untrusted-line boundary (`lib/format.ts`), the pending-report coordinator
   (`lib/report.ts`), the status chips (`lib/tui/status-controller.ts`), and the
   `/jobs` screen frame (`lib/tui/dock-screen.ts`) are shared with `watch`; this
@@ -387,19 +393,22 @@ rewritten.
 | `index.ts` | Factory: registers the tool/command and wires events, including the shared `lib/report.ts` completion reporter. |
 | `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`. |
+| `format.ts` | Pure formatting, duration, and transcript outcome-line helpers, plus the job row both surfaces draw; sanitization is `lib/format.ts`'s `sanitizeUntrustedLine`. |
 | `paths.ts` | Session/marker/registry/status file-name helpers. |
-| `registry.ts` | Per-session registry load/merge, legacy migration, and pure reconciliation. |
+| `registry.ts` | Per-session registry load/merge under `<agent-dir>/jobs/<project>/`, legacy migration, and the pure reconciliation a load runs — `loadRecords` merges every file, recovers dead pids, and classifies the survivors and orphans. |
 | `reservations.ts` | Atomic `O_EXCL` job-id reservation and release. |
 | `status.ts` | `EXIT`-trap exit-status file (write path via env, read on reattach). |
-| `session.ts` | Per-session heartbeat markers and owner-liveness rules. |
-| `store.ts` | Durable store: registry dir, this session's atomic merge-write, deletions. |
+| `session.ts` | Per-session heartbeat markers and the ownership rule: `live`, `quiet`, or `gone`. |
+| `store.ts` | Durable store: the registry directory (`<agent-dir>/jobs/<project>/`), this session's atomic merge-write, deletions. |
 | `logs.ts` | Bounded, sanitized log-tail reading. |
 | `ui.ts` | Footer status chips and the failure alert, over the shared `lib/tui/status-controller.ts` (chips, attached context, `notify`). |
 | `waiters.ts` | `wait` resolver bookkeeping. |
 | `log-writer.ts` | Per-job log sink: write stream, line split, rotation queue, and the output-driven repaint window. |
-| `runtime.ts` | Composition: job table, child handles, process events, repaint clock. |
-| `tui.ts` | The `/jobs` screen (a `DockListScreen` subclass: job rows, focus block, counts, verbs) and the `JobResult` transcript block over the shared `TailResult`. |
+| `runtime.ts` | The job table and the durable record: load and reconcile, the one settle path that announces a completion and its wake turn (holding either until the session arms its listener), waiters, clear, shutdown. |
+| `child.ts` | A job's process and its output: the spawn policy, the handle, the log stream and stdin, close/error settle, the signal and its SIGKILL grace, and the files a job leaves, over the shared `lib/child.ts` supervisor. |
+| `clock.ts` | The periodic work: the repaint clock that re-asserts the chip, and the sweep that polls the jobs this session reattached. |
+| `render.ts` | The `JobResult` transcript block over the shared `TailResult`. |
+| `view/jobs-screen.ts` | The `/jobs` screen (a `DockListScreen` subclass: job rows, focus block, counts, verbs), loaded on first use. |
 | `tools.ts` | The `job` tool and its transcript rendering. |
 | `commands.ts` | The `/jobs` command. |
 | `types.ts` | Shared types. |
@@ -409,10 +418,13 @@ rewritten.
 `extensions/job/` covers schema validation (`schema`), pure formatting and
 sanitization (`format`), the durable store (`store`), per-session reconciliation
 (`registry`), id reservation (`reservations`), exit-status recovery (`status`),
-session markers (`session`), bounded log reads and tail flags (`logs`), wait
-bookkeeping (`waiters`), the `job` tool (`tools`), the `/jobs` screen (`tui`),
-the runtime's session-scoped list and failure notification (`runtime`), `send`
-to a job's stdin and the pipe's lifecycle (`runtime`), log rotation, its two
-segments, and the cross-segment read (`runtime`), and the
-install/resume/shutdown lifecycle (`extension`). Tests drive a scripted
-`FakeChild` and a temp registry, so the suite runs without launching a process.
+session markers and the ownership rule (`session`), bounded log reads and tail
+flags (`logs`), log rotation and its two segments (`log-writer`), wait
+bookkeeping and the wait promise (`waiters`), the `job` tool (`tools`), the
+`/jobs` screen (`view/jobs-screen`), the table's session-scoped list,
+reattachment, clear and failure notification (`runtime`), a job's spawn, finish,
+kill, Windows policy, detached output, bounded tail and pid questions (`child`),
+`send` to a job's stdin and the pipe's lifecycle (`stdin`), the repaint clock and
+the external sweep (`clock`), and the install/resume/shutdown lifecycle
+(`extension`). Tests drive a scripted `FakeChild` and a temp registry, so the
+suite runs without launching a process.

package/docs/extensions/memory.md

@@ -11,22 +11,20 @@ reminded of twice.
 
 ## 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 |
+| Capability | How | What you get |
+|---|---|---|
+| Automatic recall | the `[MEMORY]` context message | Stored notes arrive before each run, bounded by a byte cap, without the user asking. |
+| Durable notes | `memory` | The model adds, updates, forgets, or lists short facts that outlive the session branch. |
+| Two scopes | the `scope` parameter, `/memory path` | Notes are global or per-project, each a plain markdown file you can edit by hand. |
+| 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. |
+| Note picker | `/memory` | Add, edit, forget, merge, or move a note in the TUI, with a scope filter and a reload. |
+| Whole-file editing | `/memory edit`, `/memory clear` | The file in the multi-line editor, or a scope cleared behind a confirm. |
+| Duplicate guard | `memory` `add` | Re-stating a stored fact in new words is a no-op that names the existing note. |
+| Store health | `/memory doctor` | Counts, file bytes, the injection budget with its omissions, and near-duplicate pairs. |
+| Store freshness | `memory`, `/memory reload` | A hand edit is picked up on the next read, and `reload` forces it. |
+| Recall off switch | `memory.inject` | Injection can be turned off without deleting the notes, for a session that must not receive them. |
+| Trust-gated project store | the `project` scope | The project file is read and written only when the project is trusted. |
+| Headless coverage | `list`, `path`, `reload`, `doctor` outside `tui` | Read-only verbs notify everywhere; picker, edit, and clear require an interactive session. |
 
 ## Quickstart
 
@@ -261,12 +259,12 @@ skill. Mitigations:
 | `types.ts` | `MemoryScope`, `MemoryAction`, `MemoryDetails`, the context type. |
 | `config.ts` | Defaults and the `memory` section of `bytefly.json` loading/clamping. |
 | `schema.ts` | TypeBox params/result and pure validation of action, scope, and text. |
-| `store.ts` | Paths, parse/read, file stamps, add/update/forget/merge/clear transforms, atomic queued write. |
+| `store.ts` | Paths (`<agent-dir>/memory.md` and the project's), parse/read, file stamps, add/update/forget/merge/clear transforms, atomic queued write. |
 | `doctor.ts` | The health report (pure): counts, file bytes, the injection plan's omissions, and near-duplicate pairs. |
 | `runtime.ts` | Session view of both stores, stamp-based refresh, trust gating, mutations. |
 | `format.ts` | Pure call/result/notice text and the bounded injection body. |
 | `errors.ts` | Re-exports `messageOf`, the shared error-text extraction (defined in `lib/errors.ts`) for the tool and command. |
-| `tui.ts` | The `/memory` picker component (note list, inline editor, merge mark, scope move, scope filter), drawn from the `lib/tui/` kit (`titleRule`, `dockListFrame`, `listRow`, `emptyState`). |
+| `view/memory-picker.ts` | The `/memory` picker component (note list, inline editor, merge mark, scope move, scope filter), loaded on first use, drawn from the `lib/tui/` kit (`titleRule`, `dockListFrame`, `listRow`, `emptyState`). |
 | `tools.ts` | `registerTool("memory", …)`. |
 | `commands.ts` | `registerCommand("memory", …)`. |
 
@@ -275,7 +273,7 @@ skill. Mitigations:
 `bun test extensions/memory` covers the pure store transforms (including the
 near-duplicate comparison key and the `add` guard), file stamps, schema and
 config validation, formatting/injection truncation, the `/memory` picker
-(`tui.test.ts`: rendering, navigation, scope filter, inline add/edit, forget
+(`view/memory-picker.test.ts`: rendering, navigation, scope filter, inline add/edit, forget
 confirm, trust), and the extension surface (registration, `session_start`
 loading, injection and dedup, external-edit refresh, `/memory reload`, update
 and trust gating, and the `/memory` command) through the