diff --git a/.ai/contexts/README.md b/.ai/contexts/README.md
index 44f49992..c2c93fca 100644
--- a/.ai/contexts/README.md
+++ b/.ai/contexts/README.md
@@ -22,6 +22,7 @@ without re-reading `main.js`, now ~2600 LOC.
 | Paths in terminal output becoming links: the matcher, the openability check, `path:line` | [terminal-path-links](terminal-path-links.md) |
 | What the right mouse button does in a terminal: the four modes, and keeping the press from the application | [terminal-right-click](terminal-right-click.md) |
 | The frameless window: the strip that replaces the title bar, its drag regions, the window controls, the menu's accelerators | [window-frame](window-frame.md) |
+| The Agents view, the daemon's job files, attach/detach, dispatch | [bg-agents](bg-agents.md) |
 
 ## Reading order for a new contributor (~30 min)
 
diff --git a/.ai/contexts/bg-agents.md b/.ai/contexts/bg-agents.md
new file mode 100644
index 00000000..ce5c5b9a
--- /dev/null
+++ b/.ai/contexts/bg-agents.md
@@ -0,0 +1,419 @@
+# Context: bg-agents
+
+**Purpose**: The Agents view — a graphical replacement for the `claude agents`
+TUI. Lists the daemon's `--bg` sessions and the external interactive ones,
+attaches/stops/respawns/deletes/dispatches through the CLI. User doc:
+`docs/background-agents.md`.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `bg-agents-roster.js` | Pure: `parseJobState`, `parseCliList`, `mergeRoster`, `dispatchArgs`, `parseDispatchOutput`, `JOB_STATES`, `JOB_ID_RE` |
+| `bg-agents.js` | Watchers over `~/.claude/jobs/*/state.json`, descriptor subscription, `reconcile()` through `claude agents --json --all`, `runVerb`, `dispatch`, `onChange`; `projectRoot`/`worktreeRoot` on every entry, cached |
+| `project-root.js` | `resolveProjectRoots(cwd)`: the `.claude/worktrees` pattern, else one `git rev-parse`; never throws |
+| `bg-agents-ipc.js` | `get-bg-agents`, `bg-agent-verb`, `dispatch-bg-agent`, the `bg-agents-changed` push |
+| `cli-session-state.js` | `onDescriptorsChanged`, `readAllDescriptors`, `kind`/`jobId` on live-elsewhere |
+| `pty-ops.js` | `detachPty` |
+| `main.js` | `runClaudeCommand`; the `type: 'attach'` branch of `open-terminal`; detach in `stop-session`; `bgAgents.init` and `bg-agents-ipc` wiring; `bgAgents.stop()` in the window's `closed` handler |
+| `public/agents-view.js` | The view; `agentJobIsLive`; `groupAgentEntries` (Group by); `bgAgentSessionIds` for the sidebar badge |
+| `public/resume-guard.js` | A live `kind: 'bg'` descriptor answers `{ attach, cwd }` |
+| `public/dialogs.js` | `showDispatchAgentDialog` |
+| `public/shortcuts.js` | The rebindable `agentsToggle` (default Primary+Shift+`A`) |
+
+## Invariants
+
+1. Never `--resume` or `--fork-session` a live job. A job is live when its
+   state is `working` or `blocked` (see "Job states"). `claude attach` is the
+   only path to a live job (`guardResume` turns a `bg` verdict into attach
+   options; `open-terminal` builds `claude attach`). Nothing ever resumes one.
+2. Every call to the CLI goes through the login shell with an argv quoted by
+   `quoteArgvForShell` (`runClaudeCommand`, the scheduler's path). Never a
+   command string built by hand. The daemon's control socket and
+   `control.key` are never touched.
+3. Closing an attach tab detaches (`\x1a`, 2 s grace, then kill —
+   `detachPty`). `claude stop` is the only stop.
+4. No steady-state cost before the view is first opened: the watchers are
+   armed by the first `get-bg-agents`. Closing the view keeps them so the
+   sidebar badge stays current; the window's `closed` handler releases them.
+5. `jobs/` and the `kind: "bg"` descriptor are undocumented. Failure is
+   silence: an unreadable `state.json` keeps the previous value; a CLI that
+   fails leaves a file-only roster with `daemonReachable: false`. Canaries:
+   `test/canary-bg-agents-files.test.js`, `test/canary-cli-session-state.test.js`.
+6. A verb's id is validated against `JOB_ID_RE` before any spawn; a prompt
+   starting with `-` is refused by `dispatchArgs`.
+7. The attach options are exactly `{ type: 'attach', jobId, cwd }`. Never
+   `sandbox`, `preLaunchCmd` or MCP emulation: the attach branch of
+   `open-terminal` skips them, and the client only talks to the daemon.
+
+## Job states
+
+`JOB_STATES` in `bg-agents-roster.js` is `working`, `blocked`, `done`,
+`stopped`, `failed`. `blocked` is a live job waiting on input (observed on CLI
+2.1.285, 2026-09-30; the first design listed three states). `failed` is a job
+that ended in error (observed on CLI 2.1.285, 2026-10-01, two jobs); before it
+was in the set such a job parsed as `null` and its row read `?`. `failed` is
+finished, like `done` and `stopped`: not live, hidden by the Finished filter,
+counted as finished, Respawn and Delete enabled. `agentJobIsLive`
+(`public/agents-view.js`) — `working` or `blocked` on a background entry — is
+the single live predicate in the renderer, so every state outside those two
+is finished without a list to keep in sync.
+
+| Verb | Live job | Not live |
+|---|---|---|
+| Attach | allowed | disabled (a finished session resumes like any other) |
+| Stop | allowed | disabled |
+| Respawn | refused | allowed |
+| Delete (`rm`) | refused | allowed |
+
+The UI disables the buttons (`agentVerbAvailability`); `runVerb` refuses
+`respawn`/`rm` on a live roster entry with the same rule, so a stale renderer
+cannot bypass it. A blocked row draws as waiting (orange), not as a spinner.
+
+## Data flow
+
+`jobs/<id>/state.json` (fs.watch, per directory) and `sessions/<pid>.json`
+(through `cli-session-state`'s flush) both call `scheduleRebuild()`,
+coalesced at `FLUSH_MS` (250 ms). `rebuild()` = `mergeRoster(cli, jobs,
+readAllDescriptors())`. The CLI list is the authority for which jobs exist
+and their `state`; the file supplies `detail`, `tokens`, `fan`, `children`,
+`result`, `--agent`/`--model`/`--name`; the descriptor supplies `status`,
+`pid`, `agent`. `reconcile()` runs on every `get-bg-agents` (the renderer
+calls it on open and every 30 s while visible) and after every verb and
+dispatch. The push `bg-agents-changed` carries `{roster, daemonReachable}`.
+
+### Lifecycle
+
+- `reconcile()` is a no-op until `start()`: it returns the current (empty)
+  snapshot without spawning the CLI.
+- The first `get-bg-agents` calls `start()`, which arms the jobs-directory
+  watcher, one watcher per job directory, and the descriptor subscription.
+  Later calls find `started` already true and only reconcile.
+- Every `get-bg-agents` also re-subscribes the `bg-agents-changed` push
+  (`subscribe()` in `bg-agents-ipc.js`). `stop()` clears the listener set; on
+  macOS the app outlives its window, the `closed` handler calls `stop()`, and
+  the window created next would otherwise never receive an update.
+- A `reconcile()` in flight when `stop()` runs is dropped: `stop()` bumps
+  `generation`, and the reconcile compares the value it captured before
+  awaiting the CLI and returns without touching the (now reset) state.
+- `bgAgents.init()` calls `stop()` first, so a re-init starts clean.
+
+## Non-obvious behaviors
+
+- The view is a sibling of `#jsonl-viewer`, shown by hiding
+  `#terminal-area` (as the Stats tab does), so the grid's state survives.
+  `hideAllViewers()` calls `hideAgentsView({ restore: false })`, as do the
+  Agent Files / Work Files tabs, Settings and the grid; only the toggle
+  restores the terminal area.
+- The view persists `localStorage.agentsViewActive` (`'1'`/`'0'`).
+  `initAgentsView()` reads it into `agentsOpenAtStartup`; `app.js` calls
+  `restoreAgentsViewAtStartup()` after the working set is restored, so the
+  view is shown once the restored sessions are open.
+  `agentsShowFinished` persists under `localStorage.agentsShowFinished`
+  (`'0'` hides finished sessions); the grouping under
+  `localStorage.agentsGroupBy` (see "Group by").
+- `claude --bg` prints its id wrapped in ANSI colour codes (see "Measured
+  facts"); `parseDispatchOutput` takes the first standalone eight-hex token,
+  which the colour codes do not hide, and `dispatch` reports
+  `ok: true, id: null` when there is none — the row then arrives through the
+  files.
+- `claude agents --json --all` runs through an interactive login shell
+  (`runClaudeCommand`), so rc files may print to stdout around the JSON.
+  `parseCliList` first tries a strict parse, then the candidate arrays that
+  start with `[` at the start of a line and end with `]` at the end of a line
+  (at most 32 of each), and returns `null` when none parses. A verb's error
+  text goes through `stripShellNoise`, which drops only the leading
+  `bash: no job control in this shell` / `cannot set terminal process group`
+  lines; the CLI's own stderr is kept verbatim.
+- `claude rm` runs from the home directory, never from the job's cwd: that
+  directory may be the worktree `rm` deletes, and Windows refuses to remove a
+  live process's cwd. `stop` and `respawn` run in the job cwd (respawn's brief
+  needs it), falling back to home when it no longer exists.
+- An attach tab's `cli-session-state` status comes from the daemon worker's
+  descriptor (same `sessionId`), so busy/idle needs no special path.
+- When a row is attached here and the user runs Stop or Delete on it, the
+  renderer stops the local attach pty first (`stopSession`), so the client
+  does not outlive the job.
+- Narrow widths: a row's grid columns add up to ~670 px of minimum width.
+  Without `min-width: 0` on `#main` that minimum became `#main`'s own, so
+  with a narrow window or a wide sidebar `#main` ran past the window edge
+  and the header's right end (New agent) was clipped by `body`'s
+  `overflow: hidden`. `#main` now shrinks to the space left, the list
+  scrolls sideways, and the header wraps its controls (`flex-wrap`, New
+  agent `flex-shrink: 0`) onto extra rows.
+- Dispatch dialog height: it reuses `.new-session-dialog`, which has no
+  height limit, so on a short screen the bottom (Start / Cancel) left the
+  window. The dispatch dialog adds `dispatch-agent-dialog`
+  (`max-height: calc(100vh - 32px)`, `overflow-y: auto`) and scrolls inside
+  the window. The class is scoped on purpose: the other dialogs share
+  `.new-session-dialog` and may hold popovers that an `overflow` would clip.
+- Window controls: the frameless window draws the system buttons over the
+  top-right corner, and `#agents-viewer-header` is the top row of `#main`.
+  It is in the `window-frameless` header lists of `style.css` (right inset
+  `--strip-inset-right`, left inset for a collapsed sidebar), and its labels
+  are `no-drag`, so New agent stays clear of the controls and a click on
+  "Finished" or "Group" does not start a window drag. A new view that
+  reaches the top of `#main` must join those lists; see
+  [window-frame.md](window-frame.md).
+
+## Group by
+
+The header's `#agents-group-by` select sets `agentsGroupBy` (`none`, `state`,
+`project`), persisted under `localStorage.agentsGroupBy`. `readAgentsGroupBy`
+wraps the read in try/catch and `normalizeAgentsGroupBy` maps anything else
+(unset included) to `state`, the default; an explicitly stored `none` or
+`project` is kept. The default is not written back, so it only lands in
+storage once the user picks something. The write is wrapped too, so a storage
+that throws still lets the choice apply for the session. The `<select>` in
+`index.html` marks `state` as `selected` to match before `initAgentsView` runs.
+
+- `groupAgentEntries(entries, mode)` is pure and returns
+  `[{ key, label, title, entries }]`, empty groups dropped. It keeps the input
+  order inside each group: the renderer passes it the already filtered
+  (Finished) and sorted (`sortAgentEntries`) list, so grouping never re-sorts
+  rows. `none` returns one unlabelled group; the renderer then skips headers
+  entirely, so the flat list is byte-identical to before.
+- `AGENT_STATE_META` (key → `{ emoji, label }`) is the single source for the
+  state groups' order, their header label and emoji, and the emoji at the
+  start of each row's `.agents-row-state` (in every mode). `agentStateMeta`
+  (entry → `{ key, emoji, label }`) is the only lookup: interactive entries
+  are `external` whatever their state; a background entry whose state is
+  `null` or not a key is `unknown`. Order: Working, Blocked, Done, Stopped,
+  Failed, External, Unknown. "Blocked" matches the row's own state word.
+  Emojis are literals from the map, never data, and sit in their own
+  `aria-hidden` span (`.agents-group-emoji`, `.agents-state-emoji`) so the
+  label and the state text stay plain text. Project headers carry no emoji.
+  A new job state needs an entry here, or its rows fall into Unknown.
+- Project groups are keyed by `entry.projectRoot || entry.cwd` (see
+  "Project and worktree roots"); the string is used as is (a trailing slash
+  or a different case makes a different group); neither is the "No project"
+  group. The label is the last path segment (`/` and `\` both split, so
+  Windows paths work). Labels shared by several roots become
+  `last (parent)`; if still shared, the full path. Order: a group holding any
+  `agentIsLive` entry first — interactive sessions count as live, the same
+  rank `sortAgentEntries` uses — then by label, case-insensitive
+  (`localeCompare`, `sensitivity: 'base'`), with "No project" last in its
+  rank.
+- Header rows are `.agents-group-header` / `.agents-subgroup-header`, not
+  `.agents-row`. The viewer's click handler checks `[data-collapse]` before
+  `.agents-row`, so a header click toggles the group and never selects a row;
+  the selection (`agentsSelectedKey`) is untouched by a regroup or a
+  collapse. The header's `title` (full path) and `data-collapse` go through
+  `agentsEscapeAttr` and are read back with `dataset`; the label through
+  `escapeHtml`.
+- Headers are `position: sticky` in the scrolling `#agents-list`, sized
+  `1.2em` of the list's 12px (rows are 12px), weight 600, with more padding
+  above than below; the count is weight 400, smaller and `--text-muted`.
+- Collapsing: every header (State, Project, worktree sub-group) is
+  `role="button"`, `tabindex="0"`, `aria-expanded`, with a `▾`/`▸` chevron in
+  an `aria-hidden` span; click, Enter or Space (a `keydown` on the viewer)
+  calls `toggleAgentsGroup`. A collapsed header keeps its label and total
+  count and renders none of its rows; a collapsed project also hides its
+  sub-groups; a collapsed sub-group hides only its rows. Keys
+  (`agentsCollapseKey`) are scoped by mode and level — `state:<state>`,
+  `project:<projectRoot or cwd>` (`project:` for No project),
+  `worktree:<projectRoot>|<worktreeRoot>` — so folding Done in State mode
+  folds nothing in Project mode. The set (`agentsCollapsedGroups`, a `Set`
+  whose insertion order is the age) is kept in memory across roster pushes,
+  regroups, mode switches and the Finished filter, and persisted as a JSON
+  array under `localStorage.agentsCollapsedGroups` (read and write in
+  try/catch). `parseCollapsedGroups` drops invalid JSON, non-arrays and
+  non-strings, de-duplicates, and keeps the newest `AGENTS_COLLAPSE_MAX`
+  (200); a toggle that adds past the cap evicts the oldest key. Keys of
+  groups that no longer exist stay until evicted. The selected row may sit in
+  a collapsed group: the selection and the detail pane stay (and its verbs
+  keep working); the row is just not drawn. Nothing collapses in None mode.
+- Worktree sub-groups: `#agents-group-worktrees` sets `agentsGroupWorktrees`,
+  persisted under `localStorage.agentsGroupWorktrees` (`'0'` off; unset or
+  anything else on; read and write in try/catch). It is disabled (kept
+  visible, greyed through `:has(input:disabled)`) outside Project mode;
+  `renderAgentsView` refreshes `disabled` on every render.
+  `groupAgentEntries(entries, 'project', { worktrees: true })` adds
+  `children` (`[{ key, label, title, entries }]`) to a project group only
+  when its entries span more than one worktree (`worktreeRoot || cwd`): a
+  project living in one worktree, even a linked one, stays flat — sub-headers
+  there would only repeat the project header. "No project" never gets
+  children. Sub-group label: `main` when `key === projectRoot`, else the
+  worktree directory's last segment, disambiguated like the project labels
+  (`main` excluded). Order: live first, then main, then label. The project
+  header's count is the project total; each `.agents-subgroup-header` (1em,
+  weight 600, muted, indented, not sticky) shows its own count, title via
+  `agentsEscapeAttr`; the rows under it get `.agents-row--nested` (indent
+  only). The option is ignored in the other modes.
+
+## Project and worktree roots
+
+`project-root.js` (main process) resolves, for one cwd,
+`{ projectRoot, worktreeRoot }`: the git project's main working tree and the
+top of the worktree the cwd lives in (the cwd may be a subdirectory).
+`derive-project-path.js`'s `resolveWorktreePath` was not reused: it is
+synchronous, needs the parent to exist, only takes a cwd that is exactly
+`<root>/.claude/worktrees/<name>`, and knows nothing about `git worktree add`
+directories elsewhere.
+
+1. Pattern (pure, no fs): `<root>/.claude/worktrees/<name>[/…]`, either
+   separator → `projectRoot = <root>`, `worktreeRoot =
+   <root>/.claude/worktrees/<name>`; the lazy match takes the outermost
+   `.claude/worktrees`. Works for a directory that no longer exists (a
+   finished job whose worktree was removed). Only `.claude/worktrees` is a
+   pattern; `.worktrees` / `.claude-worktrees` go through git when they exist.
+2. Otherwise, if the cwd is an existing directory: one
+   `git -C <cwd> rev-parse --git-common-dir --show-toplevel` through
+   `execFile` (argv array, no shell, `cwd` option, `GIT_TIMEOUT_MS` = 2 s,
+   `GIT_*` variables stripped from the env so an inherited `GIT_DIR` — e.g.
+   from a git hook — cannot point it at another repo). `worktreeRoot` = the
+   top-level; `projectRoot` = the parent of the common dir when it is named
+   `.git`, else (bare repo, submodule whose common dir is
+   `.git/modules/<sub>`) the top-level.
+3. Anything else — missing directory, not a repository, git missing, timeout,
+   a throw — gives `{ cwd, cwd }`. It never throws.
+
+`bg-agents.js` attaches both fields to every roster entry (background and
+interactive) in `rebuild()`: a cached value, else the pattern result or the
+cwd itself, so the roster renders at once. Then `resolveMissingRoots` queues
+every cwd not cached nor pending (at most `ROOT_CONCURRENCY` = 4 resolutions
+at a time, never awaited by `reconcile`/`get-bg-agents`). A finished
+resolution is cached (`rootCache`, a Map per cwd, `ROOT_CACHE_MAX` = 500,
+oldest evicted first) and calls `scheduleRebuild()` only when it differs from
+the provisional value, so a cwd that resolves to itself costs no change
+event. A failure is cached as the cwd, so git is never re-run for a known
+cwd until `stop()` (which clears the cache, the queue, and — through
+`generation` — drops resolutions still in flight). The resolver is
+injectable (`init({ resolveProjectRoots })`) for tests.
+
+Known limits: the cache is never invalidated while the watchers run — a repo
+moved or deleted, a directory that becomes a git repo later, or a git call
+that timed out once keeps its first answer until the window's `closed`
+handler (or a re-init) calls `stop()`. A submodule is grouped as its own
+project, not under its superproject. Two different spellings of one path
+(symlink, case on Windows) can still make two groups, since the pattern
+branch and the fallback keep the cwd's spelling.
+
+## The sidebar
+
+`bgAgentSessionIds` (a `Set` of the `sessionId` of every live background job,
+`agentJobIsLive`: `working` or `blocked`) is rebuilt by `applyAgentsSnapshot`,
+which refreshes the sidebar only when the set changed. `sidebar.js` prefixes a
+`bg` badge ("click to attach") to a session row whose id is in it. Two
+consequences:
+
+- The set is empty until the first `get-bg-agents` — the badge needs the view
+  to have been opened once in this window (`refreshAgentsRoster()` runs at
+  open; the push keeps it current afterwards).
+- A finished job loses its badge at the next snapshot. Clicking its row
+  resumes normally: the attach decision is made by `guardResume` from a live
+  descriptor, not from the badge.
+
+## Attach
+
+`guardResume(session, { automatic, api, confirm, live })`:
+
+- `automatic` (restore, reload): a session live elsewhere returns `false`;
+  nothing attaches or resumes on its own.
+- `live.kind === 'bg'` with a `jobId`: `{ attach: jobId, cwd }`. `app.js`
+  turns that into `{ type: 'attach', jobId, cwd }` and marks the entry
+  `attach`. Without a `jobId` it refuses (`false`) rather than offering to
+  resume.
+- Any other live-elsewhere session keeps the confirm dialog.
+
+The Agents view's Attach button builds the same options itself
+(`attachBgAgent`, skipping the guard; it is only enabled for a live job).
+In `open-terminal`, `type: 'attach'` validates `jobId` against `JOB_ID_RE`,
+takes `cwd` from the options, runs `claude attach <jobId>` and skips sandbox,
+pre-launch command and MCP emulation. The session is flagged `isAttach` with
+`attachJobId`, which `isAttachedHere` (passed to `bgAgents.init`) reads to set
+`attachedHere` on the roster entry. Attach tabs are excluded from the working
+set (`entry.attach`). After a renderer reload the tab is reopened through the
+reattach branch of `open-terminal`, which returns `attach: !!session.isAttach`;
+`openSession` sets `entry.attach` from it, so the flag survives the reload.
+
+The view's HTML puts CLI- and file-sourced values (name, cwd, href, session
+id) in attributes through `agentsEscapeAttr`, which also escapes `"` and `'`:
+`escapeHtml` does not, and a quote would otherwise let a value add a
+`data-verb` that a click runs.
+
+## Detach
+
+`stop-session` on an `isAttach` session calls `detachPty` and returns
+`{ ok: true, detached: true }`: write `\x1a` (Ctrl+Z, which makes `claude attach` leave and
+leaves the session running), wait `graceMs` (2000), then
+`killPty` if the client is still there. If the write fails it kills at once.
+A detach already pending (`session.detaching`, `session.stopRequested`) makes
+every further Stop a no-op: a second kill of a ConPTY on Windows is a heap
+double free (#405). The write goes through `writePty`.
+The header's stop button is labelled **Detach** for such a tab
+(`terminalStopBtn.title`). The job is stopped only by `claude stop`, from the
+Agents view.
+
+## Running the CLI
+
+`runClaudeCommand` (`main.js`) runs `claude <argv>` through the login shell
+profile so `PATH` matches a terminal; the login shell makes a call slow (a
+`claude agents --json --all` took 12 s under bash on Windows), hence
+`LIST_TIMEOUT_MS` 20 s and `VERB_TIMEOUT_MS` 60 s. Under cmd.exe or PowerShell
+the shell would mangle quotes, `&` and newlines of a prompt, so
+`claude-binary.js` finds `claude` on `PATH` and spawns it without a shell: the
+`.exe` itself, or, for an npm `claude.cmd` shim (libuv does not resolve
+`.cmd`), the `node` + `cli.js` the shim points to, or `cmd.exe /d /s /c` with
+escaped arguments as a last resort (a multi-line argument is refused there).
+A timeout kills the whole process tree (`taskkill /T` on Windows, the process
+group elsewhere), except for `--bg`: it may have started the daemon, so only
+the client is killed. The call resolves on `close` so stdout is drained, or
+1 s after `exit` when a daemon holding the pipes keeps `close` from firing. `dispatchArgs` puts `--` before the prompt:
+`--add-dir` is variadic and would otherwise swallow it. A job's own
+`state.json` state wins over the cached CLI list's.
+
+## Known limits
+
+- `runVerb`'s live-guard looks the job up in the roster. When the roster does
+  not have it — before the first reconcile, or a job beyond `MAX_JOBS` — the
+  guard passes `rm` and `respawn` through and the CLI is left to refuse.
+- `MAX_JOBS` (200) truncates the watched job directories by sorted id, not by
+  recency; with the daemon answering, the roster still comes from the CLI list.
+- The jobs-directory watcher's `error` handler only logs; it does not re-arm
+  the watcher, so new job directories are noticed by the next reconcile
+  instead.
+- Window close and app quit kill attach ptys without `\x1a` first (the
+  `closed` handler calls `killPty`). The session survives; the client just
+  does not leave politely.
+- `parseDispatchOutput` was checked against one measured output (see
+  "Measured facts"); a CLI that changes that line may make `dispatch` return
+  `id: null`, which only costs the row selection.
+- Liveness of interactive descriptors is pid-only (`isProcessAlive`): a
+  reused pid shows an external session that is gone.
+- A login shell whose rc files print to stdout is tolerated by the tolerant
+  list parse, as long as the JSON array stays on its own lines; other noise
+  (text on the same line as the JSON, a stray line that happens to parse as
+  a JSON array before it) is not, and the view then reports the daemon
+  unreachable.
+- Whether the CLI itself refuses `claude rm` or `claude respawn` on a live job
+  is NOT verified. The UI disables both on a live row and `runVerb` refuses
+  them when the roster knows the job is live; outside that (see the first
+  item) nothing guards it.
+
+## Measured facts (CLI 2.1.285, Linux, 2026-09-30)
+
+- `claude agents --json --all`: ~0.15 s CPU; array of `{id, sessionId, name,
+  cwd, kind, startedAt, pid?, state?, status?}`.
+- The daemon reports a fourth job state, `blocked`, for a live job waiting on
+  input, and (2026-10-01) a fifth, `failed`, for a job that ended in error.
+- `claude attach <id>` in a pty: Ctrl+Z detaches, client exits 0, session
+  stays `working`.
+- `claude logs <id>` prints screen ANSI, unusable without xterm — not used.
+- `claude --bg --name plan-check "say hello and stop"` prints
+  `backgrounded · <id> · <name>`, then dim hint lines
+  `claude agents`, `claude attach <id>`, `claude logs <id>`,
+  `claude stop <id>`. The id is 8 hex chars wrapped in ANSI colour codes
+  (`ESC[36m` … `ESC[39m`) even when stdout is piped. `parseDispatchOutput`
+  returns the id for that text and `null` for a line without an id
+  (`test/bg-agents-roster.test.js`).
+- In a cwd that is not a trusted workspace the CLI refuses: `Workspace not
+  trusted. Run \`claude\` in <dir> once and accept the trust prompt, then
+  retry.` A dispatch from a never-trusted project therefore shows that
+  message as its error.
+
+## If you change this, also check
+
+- `.ai/contexts/ipc-bridge.md` (the three handlers, the event)
+- `.ai/contexts/cli-session-state.md` (the descriptor hooks)
+- `docs/background-agents.md`, `docs/keyboard-shortcuts.md`
diff --git a/.ai/contexts/cli-session-state.md b/.ai/contexts/cli-session-state.md
index b75408e1..1ea629c6 100644
--- a/.ai/contexts/cli-session-state.md
+++ b/.ai/contexts/cli-session-state.md
@@ -308,6 +308,21 @@ The sidebar has no dedicated marker for such a session. Once the watcher has
 seen its state file, `getStatus()` gives it the same state+age line as any live
 session (see the section above).
 
+## Descriptor hooks for the agents view
+
+The Agents view (`.ai/contexts/bg-agents.md`) reads the same
+`~/.claude/sessions/<pid>.json` files through three additions:
+
+- `onDescriptorsChanged(listener)` fires once per flushed batch of descriptor
+  changes and returns an unsubscribe function. A throwing listener is logged
+  and does not stop the others.
+- `readAllDescriptors()` returns the parsed descriptors whose pid is alive,
+  capped at `MAX_DESCRIPTOR_SCAN` files; `kind` (`'bg'` or `'interactive'`) and
+  `jobId` are part of the parsed shape.
+- The results of `liveElsewhere` / `liveElsewhereMany` carry `kind` and
+  `jobId`, so `guardResume` can answer a `kind: 'bg'` session with an attach
+  instead of a resume confirmation.
+
 ## Canary tests
 
 `test/canary-*.test.js` is a convention this module introduces. A canary
diff --git a/.ai/contexts/ipc-bridge.md b/.ai/contexts/ipc-bridge.md
index 372de541..0a8ee5c8 100644
--- a/.ai/contexts/ipc-bridge.md
+++ b/.ai/contexts/ipc-bridge.md
@@ -11,6 +11,7 @@ This file is the **canonical inventory** of the IPC surface. When you add a new
 | `preload.js` | ~150 | The `contextBridge.exposeInMainWorld('api', {...})` block. Every renderer-facing function. |
 | `main.js` | ~2600 | The `ipcMain.handle('<name>', ...)` and `ipcMain.on('<name>', ...)` handlers, scattered throughout. |
 | `schedule-ipc.js` | ~220 | **Also registers IPC handlers** (`get-schedule-creator-command`, `create-schedule-session`, `run-schedule-now`) — `init()` is called from `main.js`, but a `main.js`-only search for `ipcMain.handle` misses these three. Audit both files. |
+| `bg-agents-ipc.js` | ~25 | **Also registers IPC handlers** (`get-bg-agents`, `bg-agent-verb`, `dispatch-bg-agent`) and sends `bg-agents-changed` — `init()` is called from `main.js`, so a `main.js`-only search for `ipcMain.handle` misses these three. Audit both files. |
 
 ## Public surface (IPC inventory)
 
@@ -115,6 +116,16 @@ design (parser, runner, quoting, cwd resolution, refresh triggers, editing):
 boundary in either direction: the session's cwd is re-resolved main-side on
 every call, and the absolute path built from it is used and discarded there.
 
+### Background agents (see `.ai/contexts/bg-agents.md`)
+
+| IPC | Args | Returns | Notes |
+|---|---|---|---|
+| `get-bg-agents` | — | `{roster, daemonReachable}` | Arms the watchers on first call, re-subscribes the `bg-agents-changed` push on every call, then reconciles through `claude agents --json --all`. Handler in `bg-agents-ipc.js`. |
+| `bg-agent-verb` | `(verb, id)` | `{ok, error?}` | `stop` \| `respawn` \| `rm`; id validated against `JOB_ID_RE`; `respawn`/`rm` refused on a live (`working`/`blocked`) job. |
+| `dispatch-bg-agent` | `(fields)` | `{ok, id?, error?}` | `claude --bg …` in `fields.cwd`. |
+
+`open-terminal` accepts `sessionOptions = {type: 'attach', jobId, cwd}` and runs `claude attach <jobId>`; `stop-session` on such a session detaches (`{ok, detached: true}`).
+
 ### Misc
 
 | IPC | Notes |
@@ -137,7 +148,7 @@ every call, and the absolute path built from it is used and discarded there.
 
 ### Events (main → renderer)
 
-`terminal-data`, `session-detected`, `process-exited`, `terminal-notification`, `cli-busy-state`, `session-forked`, `subagent-spawned`, `subagent-completed`, `subagent-watch-event`, `projects-changed`, `status-update`, `indexing-progress`, `file-changed`, `mcp-open-diff`, `mcp-open-file`, `mcp-close-all-diffs`, `mcp-close-tab`, `updater-event`, `show-whats-new`, `session-transcript-activity`
+`terminal-data`, `session-detected`, `process-exited`, `terminal-notification`, `cli-busy-state`, `session-forked`, `subagent-spawned`, `subagent-completed`, `subagent-watch-event`, `projects-changed`, `status-update`, `indexing-progress`, `file-changed`, `mcp-open-diff`, `mcp-open-file`, `mcp-close-all-diffs`, `mcp-close-tab`, `updater-event`, `show-whats-new`, `session-transcript-activity`, `bg-agents-changed`
 
 `session-transcript-activity` and (not listed above; see
 `.ai/contexts/session-cache.md`, "Remote hosts — busy spinner") `remote-activity`
diff --git a/.ai/shared-guidelines.md b/.ai/shared-guidelines.md
index 29b91aa3..3d4c2927 100644
--- a/.ai/shared-guidelines.md
+++ b/.ai/shared-guidelines.md
@@ -23,6 +23,7 @@ Switchboard is an **Electron desktop app**: renderer + main-process, no Domain/A
 | Change what is reported to ActivityWatch (the two buckets, focus, the Settings section) | [contexts/activitywatch.md](contexts/activitywatch.md) |
 | Change what a right-click does in the terminal (context menu, paste, mouse reports to the application) | [contexts/terminal-right-click.md](contexts/terminal-right-click.md) |
 | Change the window frame, the strip that replaces the title bar, its drag regions or the menu's accelerators | [contexts/window-frame.md](contexts/window-frame.md) |
+| Change the Agents view, the daemon's job files, attach/detach, dispatch | [contexts/bg-agents.md](contexts/bg-agents.md) |
 | Change the renderer (sidebar, terminal, app.js) | `public/*.js` — entry is `app.js` |
 | Write a test | `test/*.test.js` — node:test + jsdom for renderer files |
 | Working practices for AI agents (HANDOFF format, shell pitfalls, review loop) | [agent-practices.md](agent-practices.md) |
@@ -124,6 +125,7 @@ These exist on `devsuitup/switchboard` main but not on `doctly/switchboard` main
 - **Frameless window** — the app-drawn strip, the ☰ menu, the zoom keys; see [contexts/window-frame.md](contexts/window-frame.md)
 - **Terminal right-click modes** — the press is kept from the application outside Native mode; see [contexts/terminal-right-click.md](contexts/terminal-right-click.md)
 - **No automatic resume of a session live elsewhere** — restore and reload skip it, a click asks; see [contexts/cli-session-state.md](contexts/cli-session-state.md), "Live elsewhere"
+- **Background agents view** — the daemon's `--bg` sessions listed, attached, stopped, dispatched; see [contexts/bg-agents.md](contexts/bg-agents.md)
 
 (Not exhaustive — `git log --oneline upstream/main..main` is the ground truth.)
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 00da1499..cdfb4e36 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -18,6 +18,7 @@ What changes for you in each release of Switchboard. How to write an entry: [doc
 - The IDE Emulation label in a session's terminal header now says whether the CLI is connected: it reads "IDE Emulation" only while it is, "IDE Emulation: waiting for CLI" when Switchboard is listening but the CLI has not connected, and "IDE Emulation: failed" when it could not start for that session, with the reason in its tooltip. A session whose IDE Emulation port was already taken no longer shows the label as if it worked. (#320)
 - On Windows, the file panel no longer opens or saves a credential file (such as one under `.ssh`) through its 8.3 short name or a `\\?\` path. (#390)
 ### New
+- An Agents view lists the sessions the Claude daemon runs in the background (`claude --bg`) and the interactive sessions running outside Switchboard, grouped by state or by project and worktree. Open it from the people icon in the sidebar or with Ctrl+Shift+A (Cmd+Shift+A on macOS); attach to a live one by double click, stop, respawn or delete one, and start a new one with New agent. A background session that is running shows a `bg` badge in the sidebar and is attached instead of resumed. (#374)
 - A session's Changes panel also lists the changes in the worktrees its subagents are working in, under a header naming the agent and its branch. Those rows open as read-only diffs; a subagent that works in the session's own directory adds nothing. (#303)
 - A live session on a remote host that is not open in a terminal has a Send a prompt… button on its row: type a text and it is written to the running session as a new prompt, without attaching. It needs `ncat` or an OpenBSD `nc` on the host, and is refused for a Windows host. The dialog says "Sent": the session's own status shows whether it picked the prompt up. (#219)
 - A remote session that is not open in a tab and waits on a dialog on its host, such as a permission prompt or a question, shows the orange attention state, and its status line says what it waits for. It appears and clears with the next refresh of the host. (#394)
diff --git a/README.md b/README.md
index 85760326..0a919d29 100644
--- a/README.md
+++ b/README.md
@@ -43,6 +43,7 @@ its sessions from `~/.claude/projects`. Installed builds update themselves; see
 | Every open session as a live card | [Grid overview](docs/grid-overview.md) |
 | Busy, waiting and attention indicators; the status bar | [Status indicators](docs/notifications.md) |
 | Subagent hierarchy, live status, transcripts | [Subagents](docs/subagents.md) |
+| The sessions the claude daemon runs in the background: list, attach, stop, dispatch | [Background agents](docs/background-agents.md) |
 | Claude's file opens and proposed edits in a side panel | [IDE emulation](docs/ide-emulation.md) |
 | A session's git changes, with an editor | [Changes view](docs/changes-view.md) |
 | `CLAUDE.md`, memory files and `.work-files/` | [Agent Files and Work Files](docs/memory-workfiles.md) |
diff --git a/bg-agents-ipc.js b/bg-agents-ipc.js
new file mode 100644
index 00000000..9bdcba9e
--- /dev/null
+++ b/bg-agents-ipc.js
@@ -0,0 +1,25 @@
+// bg-agents-ipc.js — see .ai/contexts/bg-agents.md and .ai/contexts/ipc-bridge.md
+'use strict';
+
+function init({ ipcMain, bgAgents, getMainWindow, log }) {
+  const push = (snapshot) => {
+    const win = getMainWindow();
+    if (!win || win.isDestroyed()) return;
+    try { win.webContents.send('bg-agents-changed', snapshot); } catch (err) { log.warn(`[bg-agents] push failed: ${err.message}`); }
+  };
+  let unsubscribe = null;
+  const subscribe = () => {
+    if (unsubscribe) unsubscribe();
+    unsubscribe = bgAgents.onChange(push);
+  };
+  ipcMain.handle('get-bg-agents', async () => {
+    subscribe();
+    bgAgents.start();
+    return bgAgents.reconcile();
+  });
+  ipcMain.handle('bg-agent-verb', (_event, verb, id) => bgAgents.runVerb(verb, id));
+  ipcMain.handle('dispatch-bg-agent', (_event, fields) => bgAgents.dispatch(fields));
+  subscribe();
+}
+
+module.exports = { init };
diff --git a/bg-agents-roster.js b/bg-agents-roster.js
new file mode 100644
index 00000000..b87686dd
--- /dev/null
+++ b/bg-agents-roster.js
@@ -0,0 +1,220 @@
+// bg-agents-roster.js — see .ai/contexts/bg-agents.md
+'use strict';
+
+const JOB_STATES = new Set(['working', 'blocked', 'done', 'stopped', 'failed']);
+const SESSION_STATUSES = new Set(['busy', 'idle', 'waiting', 'shell']);
+const JOB_ID_RE = /^[0-9a-f]{8}$/;
+const JOB_ID_IN_TEXT_RE = /(?:^|[^0-9a-f])([0-9a-f]{8})(?![0-9a-f])/i;
+const TRANSCRIPT_ID_RE = /([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/i;
+
+const str = (v) => (typeof v === 'string' && v ? v : null);
+const num = (v) => (Number.isFinite(v) ? v : null);
+
+function sessionIdFromLinkScanPath(p) {
+  if (typeof p !== 'string') return null;
+  const m = TRANSCRIPT_ID_RE.exec(p);
+  return m ? m[1].toLowerCase() : null;
+}
+
+function flagValue(flags, name) {
+  if (!Array.isArray(flags)) return null;
+  const i = flags.indexOf(name);
+  return i >= 0 && i + 1 < flags.length ? str(flags[i + 1]) : null;
+}
+
+function parseJobState(text) {
+  let raw;
+  try { raw = JSON.parse(text); } catch { return null; }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  const fan = Array.isArray(raw.fan)
+    ? raw.fan.filter(f => f && typeof f === 'object').map(f => ({
+      id: str(f.id), kind: str(f.kind), label: str(f.label), startedAt: num(f.startedAt), doneAt: num(f.doneAt),
+    }))
+    : [];
+  const children = Array.isArray(raw.children)
+    ? raw.children.filter(c => c && typeof c === 'object').map(c => ({
+      id: c.id == null ? null : String(c.id), href: str(c.href), kind: str(c.kind),
+    }))
+    : [];
+  return {
+    state: JOB_STATES.has(raw.state) ? raw.state : null,
+    detail: str(raw.detail),
+    tempo: str(raw.tempo),
+    tokens: num(raw.tokens),
+    fan,
+    children,
+    result: raw.output && typeof raw.output === 'object' ? str(raw.output.result) : null,
+    template: str(raw.template),
+    agent: flagValue(raw.respawnFlags, '--agent'),
+    model: flagValue(raw.respawnFlags, '--model'),
+    name: flagValue(raw.respawnFlags, '--name'),
+    sessionId: sessionIdFromLinkScanPath(raw.linkScanPath),
+  };
+}
+
+const MAX_NOISY_CANDIDATES = 32;
+
+function arrayStarts(text) {
+  const out = [];
+  for (let i = text.indexOf('['); i !== -1 && out.length < MAX_NOISY_CANDIDATES; i = text.indexOf('[', i + 1)) {
+    if (!text.slice(text.lastIndexOf('\n', i - 1) + 1, i).trim()) out.push(i);
+  }
+  return out;
+}
+
+function arrayEnds(text) {
+  const out = [];
+  for (let i = text.lastIndexOf(']'); i !== -1 && out.length < MAX_NOISY_CANDIDATES; i = i > 0 ? text.lastIndexOf(']', i - 1) : -1) {
+    const eol = text.indexOf('\n', i);
+    if (!text.slice(i + 1, eol === -1 ? text.length : eol).trim()) out.push(i);
+  }
+  return out;
+}
+
+function parseJsonArray(text) {
+  const s = String(text == null ? '' : text);
+  try { return JSON.parse(s); } catch { /* fall through to the noisy parse */ }
+  const starts = arrayStarts(s);
+  const ends = arrayEnds(s);
+  for (const a of starts) {
+    for (const b of ends) {
+      if (b <= a) continue;
+      try {
+        const v = JSON.parse(s.slice(a, b + 1));
+        if (Array.isArray(v)) return v;
+      } catch { /* next candidate */ }
+    }
+  }
+  return null;
+}
+
+const SHELL_NOISE_RE = /^(?:[\w./-]*sh): (?:no job control in this shell|cannot set terminal process group\b.*|initialize_job_control: .*)$/;
+
+function stripShellNoise(stderr) {
+  const lines = String(stderr == null ? '' : stderr).split('\n');
+  let i = 0;
+  while (i < lines.length && SHELL_NOISE_RE.test(lines[i].trim())) i++;
+  return lines.slice(i).join('\n').trim();
+}
+
+function parseCliList(text) {
+  const raw = parseJsonArray(text);
+  if (!Array.isArray(raw)) return null;
+  const out = [];
+  for (const s of raw) {
+    if (!s || typeof s !== 'object') continue;
+    const kind = s.kind === 'background' || s.kind === 'interactive' ? s.kind : null;
+    if (!kind || typeof s.sessionId !== 'string' || !s.sessionId) continue;
+    out.push({
+      id: str(s.id),
+      sessionId: s.sessionId,
+      name: str(s.name),
+      cwd: str(s.cwd),
+      kind,
+      state: JOB_STATES.has(s.state) ? s.state : null,
+      status: SESSION_STATUSES.has(s.status) ? s.status : null,
+      pid: Number.isInteger(s.pid) && s.pid > 0 ? s.pid : null,
+      startedAt: num(s.startedAt),
+    });
+  }
+  return out;
+}
+
+function emptyEntry() {
+  return {
+    id: null, sessionId: null, name: null, cwd: null, kind: 'background',
+    state: null, status: null, pid: null, startedAt: null,
+    agent: null, model: null, detail: null, tempo: null, tokens: null,
+    fan: [], children: [], result: null, attachedHere: false,
+  };
+}
+
+function backgroundEntry(id, cliEntry, job, descriptor) {
+  const e = emptyEntry();
+  e.id = id;
+  if (job) {
+    Object.assign(e, {
+      sessionId: job.sessionId, name: job.name, state: job.state, agent: job.agent, model: job.model,
+      detail: job.detail, tempo: job.tempo, tokens: job.tokens, fan: job.fan, children: job.children, result: job.result,
+    });
+  }
+  if (cliEntry) {
+    e.sessionId = cliEntry.sessionId || e.sessionId;
+    e.name = cliEntry.name || e.name;
+    e.cwd = cliEntry.cwd || e.cwd;
+    e.state = (job && job.state) || cliEntry.state || e.state;
+    e.status = cliEntry.status || e.status;
+    e.pid = cliEntry.pid || e.pid;
+    e.startedAt = cliEntry.startedAt ?? e.startedAt;
+  }
+  if (descriptor) {
+    e.sessionId = e.sessionId || descriptor.sessionId;
+    e.name = e.name || descriptor.name;
+    e.cwd = e.cwd || descriptor.cwd;
+    e.agent = e.agent || descriptor.agent;
+    e.status = descriptor.status || e.status;
+    e.pid = descriptor.pid || e.pid;
+    e.startedAt = e.startedAt ?? descriptor.startedAt;
+  }
+  return e;
+}
+
+function mergeRoster({ cli, jobs, descriptors, isOwnPid, isAttachedHere }) {
+  const own = typeof isOwnPid === 'function' ? isOwnPid : () => false;
+  const attached = typeof isAttachedHere === 'function' ? isAttachedHere : () => false;
+  const byJobId = new Map();
+  for (const d of descriptors || []) {
+    if (d && d.kind === 'bg' && typeof d.jobId === 'string') byJobId.set(d.jobId, d);
+  }
+  const roster = [];
+  if (Array.isArray(cli)) {
+    for (const s of cli) {
+      if (s.kind !== 'background' || !s.id) continue;
+      roster.push(backgroundEntry(s.id, s, jobs ? jobs.get(s.id) : null, byJobId.get(s.id)));
+    }
+  } else if (jobs) {
+    for (const [id, job] of jobs) roster.push(backgroundEntry(id, null, job, byJobId.get(id)));
+  }
+  for (const d of descriptors || []) {
+    if (!d || d.kind !== 'interactive' || !d.sessionId || own(d.pid)) continue;
+    roster.push({
+      ...emptyEntry(), kind: 'interactive', sessionId: d.sessionId, name: d.name, cwd: d.cwd,
+      status: d.status, pid: d.pid, startedAt: d.startedAt,
+    });
+  }
+  for (const e of roster) e.attachedHere = e.kind === 'background' && !!attached(e.id);
+  return roster;
+}
+
+function splitAddDirs(value) {
+  if (typeof value !== 'string') return [];
+  return value.split(',').map(s => s.trim()).filter(Boolean);
+}
+
+function dispatchArgs(fields) {
+  const f = fields && typeof fields === 'object' ? fields : {};
+  const prompt = typeof f.prompt === 'string' ? f.prompt.trim() : '';
+  if (!prompt) return { ok: false, error: 'a prompt is required' };
+  if (prompt.startsWith('-')) return { ok: false, error: 'the prompt cannot start with "-": the CLI would read it as a flag' };
+  if (typeof f.cwd !== 'string' || !f.cwd) return { ok: false, error: 'a project directory is required' };
+  const args = ['--bg'];
+  const name = typeof f.name === 'string' ? f.name.trim() : '';
+  if (name) args.push('--name', name);
+  const agent = typeof f.agent === 'string' ? f.agent.trim() : '';
+  if (agent) args.push('--agent', agent);
+  if (f.dangerouslySkipPermissions) args.push('--dangerously-skip-permissions');
+  else if (typeof f.permissionMode === 'string' && f.permissionMode) args.push('--permission-mode', f.permissionMode);
+  for (const dir of splitAddDirs(f.addDirs)) args.push('--add-dir', dir);
+  args.push('--', prompt);
+  return { ok: true, args, cwd: f.cwd };
+}
+
+function parseDispatchOutput(stdout) {
+  const m = JOB_ID_IN_TEXT_RE.exec(String(stdout || ''));
+  return m ? m[1].toLowerCase() : null;
+}
+
+module.exports = {
+  parseJobState, parseCliList, mergeRoster, dispatchArgs, parseDispatchOutput,
+  sessionIdFromLinkScanPath, stripShellNoise, JOB_ID_RE, JOB_STATES,
+};
diff --git a/bg-agents.js b/bg-agents.js
new file mode 100644
index 00000000..50346432
--- /dev/null
+++ b/bg-agents.js
@@ -0,0 +1,278 @@
+// see .ai/contexts/bg-agents.md
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const {
+  parseJobState, parseCliList, mergeRoster, dispatchArgs, parseDispatchOutput, stripShellNoise, JOB_ID_RE,
+} = require('./bg-agents-roster');
+const { resolveProjectRoots, projectRootFromPattern, worktreeRootFromPattern } = require('./project-root');
+
+const DEFAULT_JOBS_DIR = path.join(os.homedir(), '.claude', 'jobs');
+const FLUSH_MS = 250;
+const MAX_JOBS = 200;
+const LIST_TIMEOUT_MS = 20000;
+const VERB_TIMEOUT_MS = 60000;
+const VERBS = new Set(['stop', 'respawn', 'rm']);
+const ROOT_CACHE_MAX = 500;
+const ROOT_CONCURRENCY = 4;
+
+let jobsDir = DEFAULT_JOBS_DIR;
+let homeDir = os.homedir();
+let log = { info() {}, warn() {}, error() {}, debug() {} };
+let runClaude = null;
+let cliSessionState = null;
+let makeIsOwnPid = () => () => false;
+let isAttachedHere = () => false;
+let resolveRoots = resolveProjectRoots;
+const rootCache = new Map();
+const rootPending = new Set();
+const rootQueue = [];
+let rootActive = 0;
+
+let started = false;
+let generation = 0;
+let dirWatcher = null;
+const jobWatchers = new Map();
+const jobs = new Map();
+let cliList = null;
+let daemonReachable = false;
+let roster = [];
+let flushTimer = null;
+let unsubscribeDescriptors = null;
+const listeners = new Set();
+
+function init(ctx) {
+  stop();
+  jobsDir = ctx.jobsDir || DEFAULT_JOBS_DIR;
+  homeDir = ctx.homeDir || os.homedir();
+  log = ctx.log || log;
+  runClaude = ctx.runClaude;
+  cliSessionState = ctx.cliSessionState;
+  makeIsOwnPid = ctx.makeIsOwnPid || (() => () => false);
+  isAttachedHere = ctx.isAttachedHere || (() => false);
+  resolveRoots = ctx.resolveProjectRoots || resolveProjectRoots;
+}
+
+function onChange(listener) {
+  listeners.add(listener);
+  return () => { listeners.delete(listener); };
+}
+
+function getSnapshot() {
+  return { roster, daemonReachable };
+}
+
+function emit() {
+  const snapshot = getSnapshot();
+  for (const listener of listeners) {
+    try { listener(snapshot); } catch (err) { log.warn(`[bg-agents] listener failed: ${err.message}`); }
+  }
+}
+
+function provisionalRoots(cwd) {
+  return { projectRoot: projectRootFromPattern(cwd) || cwd, worktreeRoot: worktreeRootFromPattern(cwd) || cwd };
+}
+
+function rootsFor(cwd) {
+  if (!cwd) return { projectRoot: null, worktreeRoot: null };
+  return rootCache.get(cwd) || provisionalRoots(cwd);
+}
+
+function pumpRoots() {
+  while (rootActive < ROOT_CONCURRENCY && rootQueue.length) {
+    const cwd = rootQueue.shift();
+    const gen = generation;
+    rootActive++;
+    Promise.resolve()
+      .then(() => resolveRoots(cwd))
+      .catch(() => null)
+      .then((roots) => {
+        if (gen !== generation) return;
+        rootActive--;
+        rootPending.delete(cwd);
+        const value = roots && roots.projectRoot
+          ? { projectRoot: roots.projectRoot, worktreeRoot: roots.worktreeRoot || roots.projectRoot }
+          : { projectRoot: cwd, worktreeRoot: cwd };
+        rootCache.set(cwd, value);
+        while (rootCache.size > ROOT_CACHE_MAX) rootCache.delete(rootCache.keys().next().value);
+        const shown = provisionalRoots(cwd);
+        if (value.projectRoot !== shown.projectRoot || value.worktreeRoot !== shown.worktreeRoot) scheduleRebuild();
+        pumpRoots();
+      });
+  }
+}
+
+function resolveMissingRoots(entries) {
+  for (const e of entries) {
+    if (!e.cwd || rootCache.has(e.cwd) || rootPending.has(e.cwd)) continue;
+    rootPending.add(e.cwd);
+    rootQueue.push(e.cwd);
+  }
+  pumpRoots();
+}
+
+function rebuild({ onlyIfChanged = false } = {}) {
+  const previous = roster;
+  let descriptors = [];
+  try { descriptors = cliSessionState ? cliSessionState.readAllDescriptors() : []; } catch {}
+  roster = mergeRoster({
+    cli: daemonReachable ? cliList : null,
+    jobs,
+    descriptors,
+    isOwnPid: makeIsOwnPid(),
+    isAttachedHere,
+  }).map(e => ({ ...e, ...rootsFor(e.cwd) }));
+  if (onlyIfChanged && JSON.stringify(previous) === JSON.stringify(roster)) return;
+  emit();
+  resolveMissingRoots(roster);
+}
+
+function scheduleRebuild() {
+  if (!started || flushTimer) return;
+  flushTimer = setTimeout(() => { flushTimer = null; rebuild({ onlyIfChanged: true }); }, FLUSH_MS);
+  if (typeof flushTimer.unref === 'function') flushTimer.unref();
+}
+
+function readJob(id) {
+  let text;
+  try { text = fs.readFileSync(path.join(jobsDir, id, 'state.json'), 'utf8'); } catch { return; }
+  const job = parseJobState(text);
+  if (job) jobs.set(id, job);
+  else log.debug(`[bg-agents] ${id}/state.json unreadable, keeping the previous value`);
+}
+
+function watchJob(id) {
+  if (!started || jobWatchers.has(id)) return;
+  readJob(id);
+  try {
+    const watcher = fs.watch(path.join(jobsDir, id), (_eventType, filename) => {
+      if (filename && filename !== 'state.json') return;
+      readJob(id);
+      scheduleRebuild();
+    });
+    watcher.on('error', () => { try { watcher.close(); } catch {} jobWatchers.delete(id); });
+    jobWatchers.set(id, watcher);
+  } catch (err) {
+    log.debug(`[bg-agents] cannot watch ${id}: ${err.message}`);
+  }
+}
+
+function syncJobWatchers() {
+  if (!started) return;
+  let names;
+  try { names = fs.readdirSync(jobsDir); } catch { names = []; }
+  const ids = names.filter(n => JOB_ID_RE.test(n)).sort().slice(0, MAX_JOBS);
+  const wanted = new Set(ids);
+  for (const [id, watcher] of jobWatchers) {
+    if (wanted.has(id)) continue;
+    try { watcher.close(); } catch {}
+    jobWatchers.delete(id);
+    jobs.delete(id);
+  }
+  for (const id of ids) watchJob(id);
+  scheduleRebuild();
+}
+
+function start() {
+  if (started) return true;
+  started = true;
+  try {
+    dirWatcher = fs.watch(jobsDir, (eventType) => { if (eventType !== 'change') syncJobWatchers(); });
+    dirWatcher.on('error', (err) => { log.warn(`[bg-agents] jobs watcher error: ${err.message}`); });
+  } catch (err) {
+    dirWatcher = null;
+    log.debug(`[bg-agents] cannot watch ${jobsDir}: ${err.message}`);
+  }
+  syncJobWatchers();
+  if (cliSessionState) {
+    unsubscribeDescriptors = cliSessionState.onDescriptorsChanged(scheduleRebuild);
+    try { cliSessionState.ensureWatching(); } catch {}
+  }
+  return true;
+}
+
+function stop() {
+  started = false;
+  generation++;
+  if (dirWatcher) { try { dirWatcher.close(); } catch {} dirWatcher = null; }
+  for (const watcher of jobWatchers.values()) { try { watcher.close(); } catch {} }
+  jobWatchers.clear();
+  jobs.clear();
+  if (flushTimer) { clearTimeout(flushTimer); flushTimer = null; }
+  if (unsubscribeDescriptors) { unsubscribeDescriptors(); unsubscribeDescriptors = null; }
+  listeners.clear();
+  cliList = null;
+  daemonReachable = false;
+  roster = [];
+  rootCache.clear();
+  rootPending.clear();
+  rootQueue.length = 0;
+  rootActive = 0;
+}
+
+async function run(argv, opts) {
+  if (typeof runClaude !== 'function') return { code: null, stdout: '', stderr: 'claude runner not configured' };
+  try {
+    return await runClaude(argv, opts);
+  } catch (err) {
+    return { code: null, stdout: '', stderr: err && err.message ? err.message : String(err) };
+  }
+}
+
+async function reconcile() {
+  const gen = generation;
+  const result = await run(['agents', '--json', '--all'], { cwd: homeDir, timeout: LIST_TIMEOUT_MS });
+  if (gen !== generation || !started) return getSnapshot();
+  const list = result.code === 0 ? parseCliList(result.stdout) : null;
+  if (list) {
+    cliList = list;
+    daemonReachable = true;
+    syncJobWatchers();
+  } else {
+    cliList = null;
+    daemonReachable = false;
+    log.debug(`[bg-agents] claude agents --json failed: code=${result.code} ${String(result.stderr).trim().slice(0, 200)}`);
+  }
+  rebuild();
+  return getSnapshot();
+}
+
+function cwdFor(id) {
+  const entry = roster.find(e => e.kind === 'background' && e.id === id);
+  if (entry && entry.cwd && fs.existsSync(entry.cwd)) return entry.cwd;
+  return homeDir;
+}
+
+async function runVerb(verb, id) {
+  if (!VERBS.has(verb)) return { ok: false, error: `unknown verb: ${String(verb)}` };
+  if (typeof id !== 'string' || !JOB_ID_RE.test(id)) return { ok: false, error: 'invalid background session id' };
+  const live = roster.find(e => e.kind === 'background' && e.id === id);
+  if (verb !== 'stop' && live && (live.state === 'working' || live.state === 'blocked')) {
+    return { ok: false, error: `cannot ${verb} a ${live.state} session; stop it first` };
+  }
+  const result = await run([verb, id], { cwd: verb === 'rm' ? homeDir : cwdFor(id), timeout: VERB_TIMEOUT_MS });
+  const ok = result.code === 0;
+  const error = ok ? null : (stripShellNoise(result.stderr) || `claude ${verb} exited with ${result.code}`);
+  await reconcile();
+  return ok ? { ok: true } : { ok: false, error };
+}
+
+async function dispatch(fields) {
+  const built = dispatchArgs(fields);
+  if (!built.ok) return { ok: false, error: built.error };
+  if (!fs.existsSync(built.cwd)) return { ok: false, error: `project directory no longer exists: ${built.cwd}` };
+  const result = await run(built.args, { cwd: built.cwd, timeout: VERB_TIMEOUT_MS });
+  if (result.code !== 0) {
+    return { ok: false, error: String(result.stderr).trim() || `claude --bg exited with ${result.code}` };
+  }
+  const id = parseDispatchOutput(result.stdout);
+  await reconcile();
+  return { ok: true, id };
+}
+
+module.exports = {
+  init, start, stop, onChange, getSnapshot, reconcile, runVerb, dispatch,
+  DEFAULT_JOBS_DIR, FLUSH_MS, MAX_JOBS, ROOT_CACHE_MAX, LIST_TIMEOUT_MS, VERB_TIMEOUT_MS,
+};
diff --git a/build/screenshot-agents.png b/build/screenshot-agents.png
new file mode 100644
index 00000000..cfacea41
Binary files /dev/null and b/build/screenshot-agents.png differ
diff --git a/claude-binary.js b/claude-binary.js
new file mode 100644
index 00000000..bcd0f346
--- /dev/null
+++ b/claude-binary.js
@@ -0,0 +1,59 @@
+// see .ai/contexts/bg-agents.md ("Running the CLI")
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const CMD_META = /([()\][%!^"`<>&|;, *?])/g;
+
+function findOnPath(name, { pathEnv, pathExt, exists, sep }) {
+  const exts = String(pathExt || '').split(';').filter(Boolean);
+  for (const dir of String(pathEnv || '').split(sep).filter(Boolean)) {
+    for (const ext of exts) {
+      const candidate = path.win32.join(dir, name + ext.toLowerCase());
+      if (exists(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+function escapeForCmd(arg) {
+  let s = String(arg).replace(/(\\*)"/g, '$1$1\\"').replace(/(\\*)$/, '$1$1');
+  s = `"${s}"`;
+  return s.replace(CMD_META, '^$1').replace(CMD_META, '^$1');
+}
+
+// How to run `claude <argv>` on Windows without a shell profile: the .exe itself, the .exe or node + cli.js an npm
+// .cmd shim points to, or cmd.exe over the shim. Only PATHEXT names count: npm also leaves an extensionless sh shim. Returns { program, args, verbatim } or { error }.
+function resolveWindowsClaude(argv, env = {}, deps = {}) {
+  const exists = deps.exists || ((p) => fs.existsSync(p));
+  const readFile = deps.readFile || ((p) => fs.readFileSync(p, 'utf8'));
+  const found = findOnPath('claude', {
+    pathEnv: env.PATH || env.Path, pathExt: env.PATHEXT || '.COM;.EXE;.BAT;.CMD', exists, sep: ';',
+  });
+  if (!found) return { error: 'claude was not found on PATH' };
+  const ext = path.win32.extname(found).toLowerCase();
+  if (ext === '.exe' || ext === '.com') return { program: found, args: argv, verbatim: false };
+  if (ext !== '.cmd' && ext !== '.bat') return { error: `cannot run ${found}` };
+
+  let shim = '';
+  try { shim = readFile(found); } catch {}
+  const m = /"%dp0%\\([^"]+\.(?:js|exe))"/i.exec(shim);
+  if (m) {
+    const dir = path.win32.dirname(found);
+    const script = path.win32.join(dir, m[1]);
+    if (/\.exe$/i.test(script) && exists(script)) return { program: script, args: argv, verbatim: false };
+    const bundled = path.win32.join(dir, 'node.exe');
+    const node = exists(bundled) ? bundled : findOnPath('node', {
+      pathEnv: env.PATH || env.Path, pathExt: '.EXE', exists, sep: ';',
+    });
+    if (node && exists(script)) return { program: node, args: [script, ...argv], verbatim: false };
+  }
+  if (argv.some((a) => /[\r\n]/.test(a))) {
+    return { error: 'a multi-line argument cannot go through a claude.cmd shim; install claude with its native installer or pick a bash profile' };
+  }
+  const line = [found, ...argv].map(escapeForCmd).join(' ');
+  return { program: env.ComSpec || 'cmd.exe', args: ['/d', '/s', '/c', `"${line}"`], verbatim: true };
+}
+
+module.exports = { resolveWindowsClaude, escapeForCmd };
diff --git a/cli-session-state.js b/cli-session-state.js
index db1f3ed4..641a1703 100644
--- a/cli-session-state.js
+++ b/cli-session-state.js
@@ -38,6 +38,9 @@ const lastRescanAt = new Map();
 // sessionId -> { status, statusUpdatedAt, pid } for live pids only -- see .ai/contexts/cli-session-state.md
 const statusBySession = new Map();
 const lastProbeAt = new Map();
+const MAX_DESCRIPTOR_SCAN = 1000;
+// Listeners told "the directory changed" after each flushed batch -- see .ai/contexts/bg-agents.md
+const descriptorListeners = new Set();
 
 function defaultIsProcessAlive(pid) {
   try {
@@ -145,6 +148,54 @@ function parseState(text) {
   };
 }
 
+// The descriptor subset the agents view reads -- see .ai/contexts/bg-agents.md
+function parseDescriptor(text) {
+  let raw;
+  try { raw = JSON.parse(text); } catch { return null; }
+  if (!raw || typeof raw !== 'object') return null;
+  if (!Number.isInteger(raw.pid) || raw.pid <= 0) return null;
+  if (typeof raw.sessionId !== 'string' || !raw.sessionId) return null;
+  const s = (v) => (typeof v === 'string' && v ? v : null);
+  return {
+    pid: raw.pid,
+    sessionId: raw.sessionId,
+    kind: s(raw.kind),
+    jobId: s(raw.jobId),
+    agent: s(raw.agent),
+    name: s(raw.name),
+    cwd: s(raw.cwd),
+    status: KNOWN_STATUSES.has(raw.status) ? raw.status : null,
+    startedAt: Number.isFinite(raw.startedAt) ? raw.startedAt : null,
+  };
+}
+
+function readAllDescriptors() {
+  let names;
+  try { names = fs.readdirSync(dir); } catch { return []; }
+  const out = [];
+  let seen = 0;
+  for (const name of names) {
+    if (!STATE_FILE_RE.test(name)) continue;
+    if (++seen > MAX_DESCRIPTOR_SCAN) break;
+    let text;
+    try { text = fs.readFileSync(path.join(dir, name), 'utf8'); } catch { continue; }
+    const d = parseDescriptor(text);
+    if (d && isProcessAlive(d.pid)) out.push(d);
+  }
+  return out;
+}
+
+function onDescriptorsChanged(listener) {
+  descriptorListeners.add(listener);
+  return () => { descriptorListeners.delete(listener); };
+}
+
+function notifyDescriptorsChanged() {
+  for (const listener of descriptorListeners) {
+    try { listener(); } catch (err) { log.warn(`[cli-state] descriptor listener failed: ${err.message}`); }
+  }
+}
+
 function findSession(sessionId) {
   if (!activeSessions) return null;
   for (const [key, session] of activeSessions) {
@@ -207,6 +258,7 @@ function flush() {
   const batch = [...pending];
   pending.clear();
   for (const name of batch) handleFile(name);
+  if (batch.length > 0) notifyDescriptorsChanged();
 }
 
 function seed() {
@@ -344,6 +396,8 @@ async function scanLiveProcesses(sessionIds, exclude) {
       pid: raw.pid,
       cwd: typeof raw.cwd === 'string' ? raw.cwd : null,
       startedAt: Number.isFinite(raw.startedAt) ? raw.startedAt : null,
+      kind: typeof raw.kind === 'string' && raw.kind ? raw.kind : null,
+      jobId: typeof raw.jobId === 'string' && raw.jobId ? raw.jobId : null,
     });
   }
   return found;
@@ -388,6 +442,10 @@ module.exports = {
   ensureWatching,
   stop,
   parseState,
+  onDescriptorsChanged,
+  readAllDescriptors,
+  parseDescriptor,
+  ownProcessFilter,
   getStatus,
   KNOWN_STATUSES,
   DEFAULT_DIR,
diff --git a/docs/README.md b/docs/README.md
index b2312723..3fa7341e 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -17,6 +17,7 @@ links are in the [README](../README.md#download).
 | [Grid overview](grid-overview.md) | All open sessions as live cards, grouped by project or flat |
 | [Status indicators](notifications.md) | What each dot and colour in the sidebar means, and the status bar |
 | [Subagents](subagents.md) | Subagent rows, their live status, the read-only transcript viewer |
+| [Background agents](background-agents.md) | The Agents view: the daemon's `--bg` sessions, attach in a tab, stop, respawn, delete, dispatch |
 | [IDE emulation](ide-emulation.md) | Switchboard as Claude's IDE: file opens and diffs in a side panel |
 | [Changes view](changes-view.md) | A session's git status and diffs, with an editor for local sessions |
 | [Agent Files and Work Files](memory-workfiles.md) | The two file tabs: `CLAUDE.md` and memory files, schedules, `.work-files/` |
@@ -27,7 +28,7 @@ links are in the [README](../README.md#download).
 | [ActivityWatch](activitywatch.md) | Opt-in reporting of session time to a local ActivityWatch server |
 | [Activity trace](activity-trace.md) | Debug mode: the trace behind the activity indicators |
 | [Settings reference](settings.md) | Every setting, its default, its scope, and where it is explained |
-| [Keyboard shortcuts](keyboard-shortcuts.md) | Every shortcut, and how to rebind the three that can be |
+| [Keyboard shortcuts](keyboard-shortcuts.md) | Every shortcut, and how to rebind the four that can be |
 | [Customizing colors](customizing-colors.md) | Community guide, in French, to editing the CSS inside `app.asar` (written against v0.0.30) |
 
 ## Working on the app
diff --git a/docs/background-agents.md b/docs/background-agents.md
new file mode 100644
index 00000000..13cd12f1
--- /dev/null
+++ b/docs/background-agents.md
@@ -0,0 +1,135 @@
+# Background agents
+
+![The Agents view grouped by state](../build/screenshot-agents.png)
+
+The Agents view is Switchboard's replacement for the `claude agents` TUI: it
+lists the sessions the Claude CLI daemon runs in the background
+(`claude --bg`) and the interactive `claude` sessions running outside this
+Switchboard, and acts on them without a terminal.
+
+## Opening it
+
+The people icon in the sidebar's filter row, or `Ctrl+Shift+A` (`Cmd+Shift+A`
+on macOS; [rebindable](keyboard-shortcuts.md)). The same toggle closes it and
+brings back whatever was there: the grid, the active session, or the
+placeholder. Opening any other view (Agent Files, Work Files, Settings, the
+grid, Stats) closes it. Whether the view is open is remembered across
+restarts.
+
+## The list
+
+One row per session: a state glyph (the same rungs as the sidebar: spinner
+while busy, orange while waiting, green when idle, grey when finished), its
+name, its `--agent`, its state emoji then `state · status` (see the table
+below), its directory, and its age. Working
+and blocked sessions and external interactive sessions come first, newest
+first. **Finished** shows or hides `done`, `stopped` and `failed` sessions;
+the choice is remembered. The list refreshes when the daemon's files change,
+and is re-read from the CLI every 30 seconds while the view is open.
+
+**Group**, next to Finished, splits the list into sections with a header
+each (its name and how many rows it holds):
+
+- **State** (the default): Working, Blocked, Done, Stopped, Failed, then
+  External for the interactive sessions running outside Switchboard, then
+  Unknown. Each header starts with the state's emoji.
+- **None**: one flat list.
+- **Project**: one section per project, named after its folder (hover the
+  header for the full path; two projects with the same folder name show
+  their parent folder too). All the worktrees of one git project — the
+  `.claude/worktrees/<name>` ones as well as any `git worktree add`
+  directory, and any subdirectory of them — fall under the project's main
+  checkout. A directory that is not in a git repository is its own project.
+  Projects with something running come first, then the rest alphabetically;
+  sessions without a directory go under No project.
+
+**Worktrees**, next to Group (checked by default, remembered), adds a second
+level in Project mode: inside a project, one smaller sub-header per worktree
+with its own count — **main** for the main checkout, the worktree's folder
+name for the others (hover for the full path). Sub-headers only appear for a
+project whose sessions run in more than one worktree; a project that lives in
+a single worktree stays a flat list under its header. Worktrees with
+something running come first, then main, then the others alphabetically. The
+box is greyed out in the other modes.
+
+Click a header (or focus it and press Enter or Space) to fold its section:
+the header keeps its name and count, its rows are hidden; folding a project
+hides its worktree sub-sections too. The arrow at the start of the header
+shows which sections are folded. It works in every grouping, each grouping
+remembers its own folded sections, and they stay folded across refreshes and
+restarts. A selected session in a folded section stays selected.
+
+Rows keep their usual order inside a section, the Finished filter applies
+first (a section left empty is not shown), and the choice is remembered.
+
+A job is in one of five states: `working`, `blocked` (live, waiting for
+input), `done`, `stopped` or `failed` (ended in error). `working` and
+`blocked` both count as live; the other three are finished.
+
+The same emoji marks a state in the State headers and at the start of every
+row's state column, whatever the grouping:
+
+| Emoji | State |
+|---|---|
+| ⚙️ | Working |
+| ✋ | Blocked (waiting for input) |
+| ✅ | Done |
+| ⏹️ | Stopped |
+| ❌ | Failed |
+| 🖥️ | External (an interactive session outside Switchboard) |
+| ❓ | Unknown |
+
+Selecting a row opens its detail: the daemon's one-line status, tokens,
+model, start time, pid, the subagents it ran, the links it produced (merge
+requests open in the browser), its last result, and the verbs:
+
+| Verb | Runs | Available |
+|---|---|---|
+| Attach | `claude attach <id>` in a terminal tab | while the session is live (`working` or `blocked`) |
+| Transcript | the read-only transcript viewer | whenever the transcript exists |
+| Stop | `claude stop <id>`; the conversation is kept | while live |
+| Respawn | `claude respawn <id>` | a background session that is not live |
+| Delete | `claude rm <id>`, after confirmation; the worktree goes too when that is safe | a background session that is not live |
+
+An external interactive session offers Transcript only. A live session is
+never resumed: attach is the only way into it. To respawn or delete one, stop
+it first.
+
+## Attaching
+
+Double-click a row you can attach to (a live `working` or `blocked` session,
+with the daemon answering) to attach, the same as the **Attach** button in the
+detail pane. A double click on a finished or external session, on a group
+header or on a button does nothing extra.
+
+An attach tab is an ordinary terminal tab running `claude attach`. Its stop
+button reads **Detach**: closing the tab sends Ctrl+Z, the attach client
+leaves, and the session keeps running under the daemon. Stopping the session
+is only offered in the Agents view. Attach tabs are not reopened by
+[session restore](session-restore.md). Quitting Switchboard or closing its
+window ends the attach client without the Ctrl+Z; the session still keeps
+running.
+
+A click in the sidebar on a session the daemon is running attaches to it
+instead of asking to resume it. Once the Agents view has been opened, such a
+row carries a `bg` badge while the job is live; the badge goes when the job
+finishes, and a finished background session resumes like any other.
+
+## New agent
+
+**New agent** opens a dialog: prompt, project, name (`--name`), agent
+(`--agent`), permission mode or Dangerous Skip, additional directories. It
+runs `claude --bg …` in the project directory and selects the new row. A
+prompt starting with `-` is refused, since the CLI would read it as a flag.
+
+## When the daemon does not answer
+
+The view reads two files the CLI writes for itself, `~/.claude/jobs/<id>/state.json`
+and `~/.claude/sessions/<pid>.json`, and asks `claude agents --json --all`
+which sessions exist. When that command fails, a banner says so, the list
+comes from the files alone, and every verb but Transcript is disabled.
+Neither file is a documented interface; a CLI upgrade may change them, and
+`test/canary-bg-agents-files.test.js` says so when it happens.
+
+At most 200 job directories are watched; in that file-only mode the list
+shows only the jobs among them.
diff --git a/docs/keyboard-shortcuts.md b/docs/keyboard-shortcuts.md
index aacab9c2..4d6c717e 100644
--- a/docs/keyboard-shortcuts.md
+++ b/docs/keyboard-shortcuts.md
@@ -2,13 +2,14 @@
 
 "Primary" below is `Cmd` on macOS and `Ctrl` on Windows and Linux.
 
-## Rebindable: sessions and grid
+## Rebindable: sessions, grid and agents
 
 | Action | Default | Effect |
 |---|---|---|
 | Navigate sessions / grid | Primary+Shift+↑/↓/←/→ | In the grid, move between cards in two dimensions; in single view, ← and ↑ go to the previous session, → and ↓ to the next |
 | Previous / next session | Primary+Shift+`[` / `]` | Cycle through the sessions |
 | Toggle grid view | Primary+Shift+`G` | Show or hide the [grid](grid-overview.md) |
+| Toggle agents view | Primary+Shift+`A` | Show or hide the [background agents](background-agents.md) view |
 
 These work with the focus in a terminal, where they are caught before the
 program sees them, and anywhere else in the window. Shift, not Alt, avoids the
diff --git a/docs/settings.md b/docs/settings.md
index 8bfbdb45..a13cb87f 100644
--- a/docs/settings.md
+++ b/docs/settings.md
@@ -46,7 +46,7 @@ for one launch — see [Launching sessions](launching-sessions.md).
 
 ### Keyboard Shortcuts
 
-Three rebindable shortcuts, stored as `shortcuts` — see
+Four rebindable shortcuts, stored as `shortcuts` — see
 [Keyboard shortcuts](keyboard-shortcuts.md#rebinding).
 
 ### Updates
diff --git a/eslint.config.js b/eslint.config.js
index c28248b4..5d381cb3 100644
--- a/eslint.config.js
+++ b/eslint.config.js
@@ -330,6 +330,20 @@ const rendererCrossFileGlobals = {
   // Resume guard for sessions live in another process (public/resume-guard.js)
   guardResume: 'readonly',
   liveElsewhereMany: 'readonly',
+  // Agents view (public/agents-view.js) — see .ai/contexts/bg-agents.md
+  agentsViewActive: 'writable',
+  bgAgentSessionIds: 'readonly',
+  initAgentsView: 'readonly',
+  showAgentsView: 'readonly',
+  hideAgentsView: 'readonly',
+  toggleAgentsView: 'readonly',
+  restoreAgentsViewAtStartup: 'readonly',
+  applyAgentsSnapshot: 'readonly',
+  refreshAgentsRoster: 'readonly',
+  attachBgAgent: 'readonly',
+  runAgentVerb: 'readonly',
+  selectAgentsRow: 'readonly',
+  showDispatchAgentDialog: 'readonly',
   // claude.ai bridge URL (public/bridge-url.js)
   bridgeSessionUrl: 'readonly',
 };
@@ -372,7 +386,7 @@ module.exports = [
   // Dual-mode helper: classic <script> in the renderer AND require()-d in tests.
   // Same browser globals as the rest of public/, plus `module` for the CJS footer.
   {
-    files: ['public/shortcuts.js', 'public/terminal-context-menu.js', 'public/terminal-manager.js', 'public/restore-plan.js', 'public/resume-guard.js', 'public/bridge-url.js', 'public/stop-session-ui.js', 'public/window-strip.js', 'public/header-controls.js', 'public/process-exit.js', 'public/whats-new.js'],
+    files: ['public/shortcuts.js', 'public/terminal-context-menu.js', 'public/terminal-manager.js', 'public/restore-plan.js', 'public/resume-guard.js', 'public/bridge-url.js', 'public/stop-session-ui.js', 'public/window-strip.js', 'public/header-controls.js', 'public/process-exit.js', 'public/whats-new.js', 'public/agents-view.js'],
     languageOptions: {
       ecmaVersion: 2024,
       sourceType: 'script',
diff --git a/main.js b/main.js
index 2a7ea9f4..4f48e7a8 100644
--- a/main.js
+++ b/main.js
@@ -1,6 +1,6 @@
 const { app, BrowserWindow, clipboard, dialog, ipcMain, Menu, powerMonitor, screen, session, shell } = require('electron');
 const { Worker } = require('worker_threads');
-const { execFile } = require('child_process');
+const { execFile, spawn: spawnChild } = require('child_process');
 const path = require('path');
 const fs = require('fs');
 const os = require('os');
@@ -76,7 +76,9 @@ const { scanMdFiles, acceptMdFile } = require('./scan-md-files');
 const { isSensitivePath, isSensitivePathAsync, isAllowedMemoryPath: _isAllowedMemoryPath, resolveAllowedMemoryPath: _resolveAllowedMemoryPath, isKnownProjectRoot: _isKnownProjectRoot } = require('./ipc-path-validator');
 const { validatePreLaunchCmd } = require('./pre-launch-cmd-guard');
 const { normalizePtySize } = require('./pty-size');
-const { setPtyOpLogger, resizePty, killPty, ptyExitSignalName } = require('./pty-ops');
+const { resolveWindowsClaude } = require('./claude-binary');
+const { setPtyOpLogger, resizePty, killPty, detachPty, ptyExitSignalName } = require('./pty-ops');
+const { JOB_ID_RE } = require('./bg-agents-roster');
 const { createComposerState } = require('./composer-state');
 const { handleTerminalInput } = require('./terminal-input');
 const { createTriggerContext } = require('./trigger-context');
@@ -425,6 +427,7 @@ function createWindow() {
     }
     changesWatchers.closeAll();
     closeAllFileWatchers();
+    bgAgents.stop();
     // Release all subagent file watchers (closes fs.watch handles + clears any
     // debounce timers / polling fallbacks via the stored teardown closure)
     for (const [, entry] of subagentWatchers) {
@@ -1690,6 +1693,13 @@ ipcMain.handle('get-active-terminals', () => {
 ipcMain.handle('stop-session', (_event, sessionId) => {
   const session = activeSessions.get(sessionId);
   if (!session || session.exited) return { ok: false, error: 'not running' };
+  // see .ai/contexts/bg-agents.md ("Detach")
+  if (session.isAttach) {
+    if (session.stopRequested) return { ok: true, detached: true };
+    session.stopRequested = true;
+    detachPty(session, sessionId);
+    return { ok: true, detached: true };
+  }
   session.stopRequested = true;
   killPty(session, sessionId);
   return { ok: true };
@@ -2328,6 +2338,69 @@ function wireSessionPty(session, sessionId, ptyProcess) {
   });
 }
 
+function killProcessTree(child) {
+  try {
+    if (isWindows) spawnChild('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
+    else process.kill(-child.pid, 'SIGKILL');
+  } catch { try { child.kill('SIGKILL'); } catch {} }
+}
+
+// Run `claude <argv>` to completion through the login shell -- see .ai/contexts/bg-agents.md
+function runClaudeCommand(claudeArgv, { cwd, timeout }) {
+  return new Promise((resolve) => {
+    const globalSettings = getSetting('global') || {};
+    const profile = resolveShell(globalSettings.shellProfile || SETTING_DEFAULTS.shellProfile);
+    const shell = profile.path;
+    // cmd.exe and PowerShell mangle quotes, `&` and newlines in a prompt: run claude itself
+    const direct = isWindows && !isWslShell(shell) && !/bash|zsh|fish|^sh$|^nu$/.test(path.basename(shell, path.extname(shell)).toLowerCase());
+    const childEnv = { ...cleanPtyEnv, FORCE_COLOR: '0' };
+    let program = shell;
+    let args;
+    let verbatim = false;
+    if (direct) {
+      const plan = resolveWindowsClaude(claudeArgv, childEnv);
+      if (plan.error) { resolve({ code: null, stdout: '', stderr: plan.error }); return; }
+      ({ program, args, verbatim } = plan);
+    } else {
+      args = shellArgs(shell, 'claude ' + quoteArgvForShell(shell, claudeArgv), profile.args || []);
+    }
+    // a timed-out --bg may have started the daemon: kill the client only, never its group
+    const killTree = claudeArgv[0] !== '--bg';
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    const finish = (code, err) => {
+      if (settled) return;
+      settled = true;
+      resolve({ code, stdout, stderr: err ? `${stderr}${err.message}` : stderr });
+    };
+    let child;
+    try {
+      child = spawnChild(program, args, {
+        cwd, stdio: ['ignore', 'pipe', 'pipe'], env: childEnv, windowsHide: true,
+        windowsVerbatimArguments: verbatim, detached: killTree && !isWindows,
+      });
+    } catch (err) {
+      finish(null, err);
+      return;
+    }
+    const timer = setTimeout(() => {
+      if (killTree) killProcessTree(child);
+      else { try { child.kill('SIGKILL'); } catch {} }
+      finish(null, new Error(`claude ${claudeArgv[0]} timed out after ${timeout} ms`));
+    }, timeout);
+    child.stdout.on('data', (d) => { stdout += d.toString(); });
+    child.stderr.on('data', (d) => { stderr += d.toString(); });
+    child.on('error', (err) => { clearTimeout(timer); finish(null, err); });
+    child.on('close', (code) => { clearTimeout(timer); finish(code); });
+    // a daemon that inherited the pipes keeps `close` from firing: settle shortly after the client exits
+    child.on('exit', (code) => {
+      const grace = setTimeout(() => { clearTimeout(timer); finish(code); }, 1000);
+      if (typeof grace.unref === 'function') grace.unref();
+    });
+  });
+}
+
 // --- IPC: open-terminal ---
 ipcMain.handle('open-terminal', async (_event, sessionId, projectPath, isNew, sessionOptions, initialSize) => {
   if (!mainWindow) return { ok: false, error: 'no window' };
@@ -2355,7 +2428,7 @@ ipcMain.handle('open-terminal', async (_event, sessionId, projectPath, isNew, se
     }
 
     return {
-      ok: true, reattached: true, sandbox: !!session.sandbox,
+      ok: true, reattached: true, attach: !!session.isAttach, sandbox: !!session.sandbox,
       mcpState: session.mcpError ? 'failed' : getMcpState(session.realSessionId || sessionId),
       mcpError: session.mcpError || null,
       generation: session.generation,
@@ -2409,13 +2482,22 @@ ipcMain.handle('open-terminal', async (_event, sessionId, projectPath, isNew, se
   const resumeSourceId = sessionOptions?.forkFrom
     ? String(sessionOptions.forkFrom)
     : (!isNew ? sessionId : null);
-  if (resumeSourceId && sessionOptions?.type !== 'terminal') {
+  if (resumeSourceId && sessionOptions?.type !== 'terminal' && sessionOptions?.type !== 'attach') {
     const realCwd = resolveSessionRealCwd(
       PROJECTS_DIR, resumeSourceId, projectPath ? encodeProjectPath(projectPath) : null
     );
     if (realCwd && fs.existsSync(realCwd)) spawnCwd = realCwd;
   }
 
+  // see .ai/contexts/bg-agents.md ("Attach")
+  const isAttach = sessionOptions?.type === 'attach';
+  let attachJobId = null;
+  if (isAttach) {
+    if (!JOB_ID_RE.test(String(sessionOptions.jobId))) return { ok: false, error: 'invalid background session id' };
+    attachJobId = String(sessionOptions.jobId);
+    if (typeof sessionOptions.cwd === 'string' && sessionOptions.cwd) spawnCwd = sessionOptions.cwd;
+  }
+
   // see .ai/contexts/panel-terminal.md ("Main process")
   const panelOwnerId = sessionOptions?.type === 'terminal' && sessionOptions.panelFor
     ? String(sessionOptions.panelFor)
@@ -2518,61 +2600,65 @@ ipcMain.handle('open-terminal', async (_event, sessionId, projectPath, isNew, se
     } else {
       // Build claude command, using array to prevent accidental shell injection
       const claudeArgs = [];
-      // A sidebar card is not proof the session exists on disk: launchNewSession
-      // shows one before claude starts, so a launch that fails immediately (bad
-      // flag, missing directory) leaves a card whose transcript was never
-      // written. Resuming that id makes claude exit with "No conversation found
-      // with session ID", and the banner's advice — re-click to relaunch — could
-      // never work because every retry resumed the same missing id. Start it
-      // instead, reusing the id the sidebar already shows.
-      const startsFresh = isNew
-        || (!sessionOptions?.forkFrom && !sessionTranscriptExists(PROJECTS_DIR, sessionId));
-      if (!isNew && startsFresh && !sessionOptions?.forkFrom) {
-        log.info(`[open-terminal] ${sessionId} has no transcript — starting it instead of resuming`);
-      }
-      if (sessionOptions?.forkFrom) {
-        claudeArgs.push('--resume', String(sessionOptions.forkFrom), '--fork-session');
-      } else if (startsFresh) {
-        claudeArgs.push('--session-id', String(sessionId));
+      if (isAttach) {
+        claudeArgs.push('attach', attachJobId);
       } else {
-        claudeArgs.push('--resume', String(sessionId));
-      }
-
-      if (sessionOptions) {
-        if (sessionOptions.dangerouslySkipPermissions) {
-          claudeArgs.push('--dangerously-skip-permissions');
-        } else if (sessionOptions.permissionMode) {
-          claudeArgs.push('--permission-mode', String(sessionOptions.permissionMode));
+        // A sidebar card is not proof the session exists on disk: launchNewSession
+        // shows one before claude starts, so a launch that fails immediately (bad
+        // flag, missing directory) leaves a card whose transcript was never
+        // written. Resuming that id makes claude exit with "No conversation found
+        // with session ID", and the banner's advice — re-click to relaunch — could
+        // never work because every retry resumed the same missing id. Start it
+        // instead, reusing the id the sidebar already shows.
+        const startsFresh = isNew
+          || (!sessionOptions?.forkFrom && !sessionTranscriptExists(PROJECTS_DIR, sessionId));
+        if (!isNew && startsFresh && !sessionOptions?.forkFrom) {
+          log.info(`[open-terminal] ${sessionId} has no transcript — starting it instead of resuming`);
         }
-        // --worktree only applies when STARTING a session — it creates a fresh
-        // isolated git worktree. Resuming (isNew === false) must reuse the
-        // session's existing directory, so ignore the worktree option on resume
-        // regardless of which call site supplied it (sidebar click, schedule
-        // creator, fork, …). Otherwise a resume tries to spin up a new worktree
-        // and fails to attach.
-        if (startsFresh && sessionOptions.worktree && !isGitRepo(spawnCwd)) {
-          // Worktree is commonly enabled globally, but plenty of projects are
-          // not git repos. Passing --worktree there makes claude refuse to start
-          // at all ("Can only use --worktree in a git repository"), which turns
-          // one global convenience toggle into a broken project. Drop the flag
-          // and run unisolated rather than fail the launch.
-          log.warn(`[open-terminal] ${spawnCwd} is not a git repository — launching without --worktree`);
-        } else if (startsFresh && sessionOptions.worktree) {
-          claudeArgs.push('--worktree');
-          if (sessionOptions.worktreeName) {
-            claudeArgs.push(String(sessionOptions.worktreeName));
-          }
-        }
-        if (sessionOptions.chrome) {
-          claudeArgs.push('--chrome');
+        if (sessionOptions?.forkFrom) {
+          claudeArgs.push('--resume', String(sessionOptions.forkFrom), '--fork-session');
+        } else if (startsFresh) {
+          claudeArgs.push('--session-id', String(sessionId));
+        } else {
+          claudeArgs.push('--resume', String(sessionId));
         }
-        for (const dir of parseAddDirs(sessionOptions.addDirs)) {
-          claudeArgs.push('--add-dir', dir);
+
+        if (sessionOptions) {
+          if (sessionOptions.dangerouslySkipPermissions) {
+            claudeArgs.push('--dangerously-skip-permissions');
+          } else if (sessionOptions.permissionMode) {
+            claudeArgs.push('--permission-mode', String(sessionOptions.permissionMode));
+          }
+          // --worktree only applies when STARTING a session — it creates a fresh
+          // isolated git worktree. Resuming (isNew === false) must reuse the
+          // session's existing directory, so ignore the worktree option on resume
+          // regardless of which call site supplied it (sidebar click, schedule
+          // creator, fork, …). Otherwise a resume tries to spin up a new worktree
+          // and fails to attach.
+          if (startsFresh && sessionOptions.worktree && !isGitRepo(spawnCwd)) {
+            // Worktree is commonly enabled globally, but plenty of projects are
+            // not git repos. Passing --worktree there makes claude refuse to start
+            // at all ("Can only use --worktree in a git repository"), which turns
+            // one global convenience toggle into a broken project. Drop the flag
+            // and run unisolated rather than fail the launch.
+            log.warn(`[open-terminal] ${spawnCwd} is not a git repository — launching without --worktree`);
+          } else if (startsFresh && sessionOptions.worktree) {
+            claudeArgs.push('--worktree');
+            if (sessionOptions.worktreeName) {
+              claudeArgs.push(String(sessionOptions.worktreeName));
+            }
+          }
+          if (sessionOptions.chrome) {
+            claudeArgs.push('--chrome');
+          }
+          for (const dir of parseAddDirs(sessionOptions.addDirs)) {
+            claudeArgs.push('--add-dir', dir);
+          }
         }
-      }
 
-      if (sessionOptions?.appendSystemPrompt) {
-        claudeArgs.push('--append-system-prompt', String(sessionOptions.appendSystemPrompt));
+        if (sessionOptions?.appendSystemPrompt) {
+          claudeArgs.push('--append-system-prompt', String(sessionOptions.appendSystemPrompt));
+        }
       }
 
       let claudeCmd = 'claude ' + quoteArgvForShell(shell, claudeArgs);
@@ -2580,7 +2666,7 @@ ipcMain.handle('open-terminal', async (_event, sessionId, projectPath, isNew, se
       // Sandbox: run claude inside a bubblewrap sandbox that only exposes the
       // project directory and Claude's own config/state dirs. Linux only —
       // bwrap has no macOS/Windows equivalent wired up here.
-      if (sessionOptions?.sandbox) {
+      if (!isAttach && sessionOptions?.sandbox) {
         if (process.platform !== 'linux') {
           return { ok: false, error: 'Sandbox mode requires Linux (bubblewrap)' };
         }
@@ -2589,7 +2675,7 @@ ipcMain.handle('open-terminal', async (_event, sessionId, projectPath, isNew, se
 
       // preLaunchCmd is raw shell by design (e.g. "aws-vault exec profile --")
       // — see pre-launch-cmd-guard.js for what is and isn't blocked and why.
-      if (sessionOptions?.preLaunchCmd) {
+      if (!isAttach && sessionOptions?.preLaunchCmd) {
         const pre = String(sessionOptions.preLaunchCmd);
         const preCheck = validatePreLaunchCmd(pre);
         if (!preCheck.ok) {
@@ -2600,7 +2686,7 @@ ipcMain.handle('open-terminal', async (_event, sessionId, projectPath, isNew, se
 
       // Start MCP server for this session so Claude CLI sends diffs/file opens to Switchboard
       // (skip if user disabled IDE emulation in global settings)
-      if (sessionOptions?.mcpEmulation !== false) {
+      if (!isAttach && sessionOptions?.mcpEmulation !== false) {
         try {
           mcpServer = await startMcpServer(sessionId, [spawnCwd], mainWindow, log);
           claudeCmd += ' --ide';
@@ -2637,7 +2723,7 @@ ipcMain.handle('open-terminal', async (_event, sessionId, projectPath, isNew, se
       }
       // see docs/sandbox.md ("Schedules")
       if (projectPath) scheduleProjects().add(projectPath);
-      if (sessionOptions?.sandbox) {
+      if (!isAttach && sessionOptions?.sandbox) {
         // Directories the sandboxed claude must still reach beyond the cwd:
         // the project root when resuming inside a worktree (git metadata lives
         // there), and any user-configured Additional Directories.
@@ -2674,6 +2760,7 @@ ipcMain.handle('open-terminal', async (_event, sessionId, projectPath, isNew, se
     cwd: spawnCwd,
     projectFolder, knownJsonlFiles,
     isPlainTerminal, panelFor: panelOwnerId, forkFrom: sessionOptions?.forkFrom || null,
+    isAttach, attachJobId,
     // Recorded so a reattach can report it too — the renderer badges sandboxed
     // sessions, and a reattached session is still inside the same sandbox.
     sandbox: !!sessionOptions?.sandbox,
@@ -2936,6 +3023,22 @@ const localTranscriptTracker = createLocalTranscriptTracker({ hasPty: sessionHas
 ipcMain.handle('session-live-elsewhere', (_event, sessionId) => cliSessionState.liveElsewhere(sessionId, sessionHasPty, ptyPids));
 ipcMain.handle('sessions-live-elsewhere', (_event, sessionIds) => cliSessionState.liveElsewhereMany(sessionIds, sessionHasPty, ptyPids));
 
+// see .ai/contexts/bg-agents.md
+const bgAgents = require('./bg-agents');
+bgAgents.init({
+  log,
+  runClaude: runClaudeCommand,
+  cliSessionState,
+  makeIsOwnPid: () => cliSessionState.ownProcessFilter(ptyPids),
+  isAttachedHere: (jobId) => {
+    for (const session of activeSessions.values()) {
+      if (session && !session.exited && session.isAttach && session.attachJobId === jobId) return true;
+    }
+    return false;
+  },
+});
+require('./bg-agents-ipc').init({ ipcMain, bgAgents, getMainWindow: () => mainWindow, log });
+
 // --- fs.watch on projects directory ---
 let projectsWatcher = null;
 
diff --git a/preload.js b/preload.js
index 50dbf2d1..540b1200 100644
--- a/preload.js
+++ b/preload.js
@@ -20,6 +20,10 @@ contextBridge.exposeInMainWorld('api', {
   getSessionsLiveElsewhere: (ids) => ipcRenderer.invoke('sessions-live-elsewhere', ids),
   getActiveTerminals: () => ipcRenderer.invoke('get-active-terminals'),
   stopSession: (id) => ipcRenderer.invoke('stop-session', id),
+  // see .ai/contexts/bg-agents.md
+  getBgAgents: () => ipcRenderer.invoke('get-bg-agents'),
+  bgAgentVerb: (verb, id) => ipcRenderer.invoke('bg-agent-verb', verb, id),
+  dispatchBgAgent: (fields) => ipcRenderer.invoke('dispatch-bg-agent', fields),
   // see .ai/contexts/session-state.md ("The two lifecycle verbs: detach and stop")
   remoteStopSession: (alias, sessionId) => ipcRenderer.invoke('remote-stop-session', { alias, sessionId }),
   remoteSendPrompt: (alias, sessionId, text) => ipcRenderer.invoke('remote-send-prompt', { alias, sessionId, text }),
@@ -125,6 +129,7 @@ contextBridge.exposeInMainWorld('api', {
   onSubagentSpawned: (cb) => ipcRenderer.on('subagent-spawned', (_e, payload) => cb(payload)),
   onSubagentCompleted: (cb) => ipcRenderer.on('subagent-completed', (_e, payload) => cb(payload)),
   onSubagentWatchEvent: (cb) => ipcRenderer.on('subagent-watch-event', (_e, payload) => cb(payload)),
+  onBgAgentsChanged: (cb) => ipcRenderer.on('bg-agents-changed', (_e, payload) => cb(payload)),
   onProjectsChanged: (callback) => {
     ipcRenderer.on('projects-changed', () => callback());
   },
diff --git a/project-root.js b/project-root.js
new file mode 100644
index 00000000..c2d0b21a
--- /dev/null
+++ b/project-root.js
@@ -0,0 +1,65 @@
+// see .ai/contexts/bg-agents.md
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const childProcess = require('child_process');
+
+const GIT_TIMEOUT_MS = 2000;
+const CLAUDE_WORKTREE_RE = /^(.+?)([/\\]\.claude[/\\]worktrees[/\\][^/\\]+)(?:[/\\].*)?$/;
+
+function projectRootFromPattern(cwd) {
+  if (typeof cwd !== 'string' || !cwd) return null;
+  const m = cwd.match(CLAUDE_WORKTREE_RE);
+  return m ? m[1] : null;
+}
+
+function worktreeRootFromPattern(cwd) {
+  if (typeof cwd !== 'string' || !cwd) return null;
+  const m = cwd.match(CLAUDE_WORKTREE_RE);
+  return m ? m[1] + m[2] : null;
+}
+
+function rootFromCommonDir(commonDir) {
+  if (typeof commonDir !== 'string' || !commonDir) return null;
+  const trimmed = commonDir.replace(/[/\\]+$/, '');
+  return path.basename(trimmed) === '.git' ? path.dirname(trimmed) : null;
+}
+
+function gitEnv(env) {
+  const out = {};
+  for (const [k, v] of Object.entries(env || {})) if (!k.startsWith('GIT_')) out[k] = v;
+  return out;
+}
+
+function runGit(execFile, cwd, env) {
+  return new Promise((resolve) => {
+    try {
+      execFile('git', ['-C', cwd, 'rev-parse', '--git-common-dir', '--show-toplevel'],
+        { cwd, timeout: GIT_TIMEOUT_MS, windowsHide: true, env: gitEnv(env) },
+        (err, stdout) => resolve(err ? null : String(stdout || '')));
+    } catch {
+      resolve(null);
+    }
+  });
+}
+
+async function resolveProjectRoots(cwd, { execFile = childProcess.execFile, env = process.env } = {}) {
+  if (typeof cwd !== 'string' || !cwd) return { projectRoot: null, worktreeRoot: null };
+  const patternRoot = projectRootFromPattern(cwd);
+  if (patternRoot) return { projectRoot: patternRoot, worktreeRoot: worktreeRootFromPattern(cwd) };
+  const fallback = { projectRoot: cwd, worktreeRoot: cwd };
+  let exists = false;
+  try { exists = fs.statSync(cwd).isDirectory(); } catch {}
+  if (!exists) return fallback;
+  const out = await runGit(execFile, cwd, env);
+  if (!out) return fallback;
+  const [commonLine, topLine] = out.split(/\r?\n/).map(s => s.trim());
+  const worktreeRoot = topLine ? path.resolve(cwd, topLine) : cwd;
+  const projectRoot = (commonLine && rootFromCommonDir(path.resolve(cwd, commonLine))) || worktreeRoot;
+  return { projectRoot, worktreeRoot };
+}
+
+module.exports = {
+  projectRootFromPattern, worktreeRootFromPattern, rootFromCommonDir, resolveProjectRoots, gitEnv, GIT_TIMEOUT_MS,
+};
diff --git a/pty-ops.js b/pty-ops.js
index 530bee30..30a99941 100644
--- a/pty-ops.js
+++ b/pty-ops.js
@@ -57,10 +57,23 @@ function writePty(session, data, sessionId) {
   return withPty(session, 'write', (pty) => pty.write(data), sessionId);
 }
 
+// see .ai/contexts/bg-agents.md
+function detachPty(session, sessionId, { graceMs = 2000, schedule = setTimeout } = {}) {
+  if (session.detaching) return true;
+  session.detaching = true;
+  const wrote = writePty(session, '\x1a', sessionId);
+  if (!wrote) return killPty(session, sessionId);
+  const timer = schedule(() => {
+    if (!session.exited) killPty(session, sessionId);
+  }, graceMs);
+  if (timer && typeof timer.unref === 'function') timer.unref();
+  return true;
+}
+
 /** The name of the signal node-pty reports on exit (`SIGKILL`), or null when none killed it. */
 function ptyExitSignalName(signal, signals = os.constants.signals) {
   if (!signal) return null;
   return Object.keys(signals).find((name) => signals[name] === signal) || `signal ${signal}`;
 }
 
-module.exports = { setPtyOpLogger, withPty, resizePty, killPty, writePty, ptyExitSignalName };
+module.exports = { setPtyOpLogger, withPty, resizePty, killPty, writePty, detachPty, ptyExitSignalName };
diff --git a/public/agents-view.js b/public/agents-view.js
new file mode 100644
index 00000000..39d2bd87
--- /dev/null
+++ b/public/agents-view.js
@@ -0,0 +1,562 @@
+// see .ai/contexts/bg-agents.md
+
+const AGENTS_RECONCILE_MS = 30000;
+const bgAgentSessionIds = new Set();
+let agentsViewActive = false;
+let agentsRoster = [];
+let agentsDaemonReachable = true;
+let agentsSelectedKey = null;
+let agentsShowFinished = true;
+let agentsGroupBy = 'state';
+let agentsGroupWorktrees = true;
+const AGENTS_COLLAPSE_MAX = 200;
+let agentsCollapsedGroups = new Set();
+let agentsReconcileTimer = null;
+let agentsOpenAtStartup = false;
+const agentsPendingVerbs = new Set();
+const agentsVerbErrors = new Map();
+
+function agentsEscapeAttr(value) {
+  return escapeHtml(value).replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+}
+
+function agentsEntryKey(entry) {
+  return entry.kind === 'background' ? 'bg:' + entry.id : 'int:' + entry.sessionId;
+}
+
+function agentJobIsLive(entry) {
+  return entry.kind === 'background' && (entry.state === 'working' || entry.state === 'blocked');
+}
+
+function agentIsLive(entry) {
+  return entry.kind === 'interactive' || agentJobIsLive(entry);
+}
+
+function sortAgentEntries(entries) {
+  return entries.slice().sort((a, b) => {
+    const rank = (e) => (agentIsLive(e) ? 0 : 1);
+    if (rank(a) !== rank(b)) return rank(a) - rank(b);
+    const sa = Number.isFinite(a.startedAt) ? a.startedAt : -Infinity;
+    const sb = Number.isFinite(b.startedAt) ? b.startedAt : -Infinity;
+    return sb - sa;
+  });
+}
+
+const AGENTS_GROUP_MODES = ['none', 'state', 'project'];
+const AGENT_STATE_META = {
+  working: { emoji: '⚙️', label: 'Working' },
+  blocked: { emoji: '✋', label: 'Blocked' },
+  done: { emoji: '✅', label: 'Done' },
+  stopped: { emoji: '⏹️', label: 'Stopped' },
+  failed: { emoji: '❌', label: 'Failed' },
+  external: { emoji: '🖥️', label: 'External' },
+  unknown: { emoji: '❓', label: 'Unknown' },
+};
+
+function normalizeAgentsGroupBy(value) {
+  return AGENTS_GROUP_MODES.includes(value) ? value : 'state';
+}
+
+function agentStateGroupKey(entry) {
+  if (entry.kind === 'interactive') return 'external';
+  const known = entry.state && entry.state !== 'external' && entry.state !== 'unknown' && Object.hasOwn(AGENT_STATE_META, entry.state);
+  return known ? entry.state : 'unknown';
+}
+
+function agentStateMeta(entry) {
+  const key = agentStateGroupKey(entry);
+  return { key, ...AGENT_STATE_META[key] };
+}
+
+function agentPathSegments(cwd) {
+  return String(cwd).split(/[\\/]+/).filter(Boolean);
+}
+
+function bucketAgentsByPath(entries, keyOf) {
+  const buckets = new Map();
+  for (const entry of entries) {
+    const key = keyOf(entry) || '';
+    if (!buckets.has(key)) buckets.set(key, []);
+    buckets.get(key).push(entry);
+  }
+  return [...buckets].map(([key, list]) => {
+    const segs = agentPathSegments(key);
+    return { key, segs, label: segs[segs.length - 1] || key, title: key, entries: list };
+  });
+}
+
+function disambiguatePathLabels(groups, eligible) {
+  const relabel = (pick) => {
+    const counts = new Map();
+    for (const g of groups) if (eligible(g)) counts.set(g.label, (counts.get(g.label) || 0) + 1);
+    for (const g of groups) if (eligible(g) && counts.get(g.label) > 1) g.label = pick(g);
+  };
+  relabel((g) => (g.segs.length > 1 ? `${g.segs[g.segs.length - 1]} (${g.segs[g.segs.length - 2]})` : g.key));
+  relabel((g) => g.key);
+}
+
+function agentLiveRank(group) {
+  return group.entries.some(agentIsLive) ? 0 : 1;
+}
+
+function agentsByLabel(a, b) {
+  return a.label.localeCompare(b.label, undefined, { sensitivity: 'base' });
+}
+
+function groupAgentsByWorktree(projectKey, entries) {
+  const groups = bucketAgentsByPath(entries, e => e.worktreeRoot || e.cwd);
+  for (const g of groups) g.main = !!projectKey && g.key === projectKey;
+  for (const g of groups) if (g.main) g.label = 'main';
+  disambiguatePathLabels(groups, g => !g.main);
+  groups.sort((a, b) => agentLiveRank(a) - agentLiveRank(b) || Number(b.main) - Number(a.main) || agentsByLabel(a, b));
+  return groups.map(({ key, label, title, entries: list }) => ({ key, label, title, entries: list }));
+}
+
+function groupAgentsByProject(entries, worktrees) {
+  const groups = bucketAgentsByPath(entries, e => e.projectRoot || e.cwd);
+  for (const g of groups) if (!g.key) g.label = 'No project';
+  disambiguatePathLabels(groups, g => !!g.key);
+  groups.sort((a, b) => agentLiveRank(a) - agentLiveRank(b) || Number(!a.key) - Number(!b.key) || agentsByLabel(a, b));
+  return groups.map(({ key, label, title, entries: list }) => {
+    const group = { key, label, title, entries: list };
+    if (worktrees && key) {
+      const children = groupAgentsByWorktree(key, list);
+      if (children.length > 1) group.children = children;
+    }
+    return group;
+  });
+}
+
+function groupAgentEntries(entries, mode, opts = {}) {
+  if (!entries.length) return [];
+  const m = normalizeAgentsGroupBy(mode);
+  if (m === 'none') return [{ key: '', label: '', title: '', entries: entries.slice() }];
+  if (m === 'project') return groupAgentsByProject(entries, !!opts.worktrees);
+  return Object.entries(AGENT_STATE_META)
+    .map(([key, meta]) => ({ key, label: meta.label, emoji: meta.emoji, title: '', entries: entries.filter(e => agentStateGroupKey(e) === key) }))
+    .filter(g => g.entries.length);
+}
+
+function agentRowIcon(entry) {
+  const live = agentIsLive(entry);
+  const blocked = entry.kind === 'background' && entry.state === 'blocked';
+  const icon = renderSessionIcon({
+    busy: live && !blocked && entry.status === 'busy',
+    waitingForInput: live && (blocked || entry.status === 'waiting'),
+    stale: !live,
+  });
+  return { slotClass: icon.slotClasses[0], title: icon.title };
+}
+
+function agentVerbAvailability(entry, daemonReachable) {
+  const bg = entry.kind === 'background';
+  const live = agentJobIsLive(entry);
+  const reachable = !!daemonReachable;
+  return {
+    transcript: !!entry.sessionId,
+    attach: live && reachable,
+    stop: live && reachable,
+    respawn: bg && !live && reachable,
+    rm: bg && !live && reachable,
+  };
+}
+
+function formatTokens(n) {
+  if (!Number.isFinite(n)) return '';
+  if (n < 1000) return String(n);
+  if (n < 1_000_000) return Math.round(n / 1000) + 'k';
+  return (n / 1_000_000).toFixed(1) + 'M';
+}
+
+function formatAgentAge(startedAt, now = Date.now()) {
+  if (!Number.isFinite(startedAt)) return '';
+  const s = Math.max(0, Math.floor((now - startedAt) / 1000));
+  if (s < 60) return s + 's';
+  const m = Math.floor(s / 60);
+  if (m < 60) return m + ' min';
+  const h = Math.floor(m / 60);
+  if (h < 24) return h + ' h';
+  return Math.floor(h / 24) + 'd ' + (h % 24) + 'h';
+}
+
+function agentsSelectedEntry() {
+  return agentsRoster.find(e => agentsEntryKey(e) === agentsSelectedKey) || null;
+}
+
+function applyAgentsSnapshot(snapshot) {
+  agentsRoster = Array.isArray(snapshot && snapshot.roster) ? snapshot.roster : [];
+  agentsDaemonReachable = !snapshot || snapshot.daemonReachable !== false;
+  const next = new Set(agentsRoster.filter(e => agentJobIsLive(e) && e.sessionId).map(e => e.sessionId));
+  let changed = next.size !== bgAgentSessionIds.size;
+  if (!changed) for (const id of next) if (!bgAgentSessionIds.has(id)) { changed = true; break; }
+  if (changed) {
+    bgAgentSessionIds.clear();
+    for (const id of next) bgAgentSessionIds.add(id);
+    if (typeof refreshSidebar === 'function') refreshSidebar();
+  }
+  if (agentsViewActive) renderAgentsView();
+}
+
+async function refreshAgentsRoster() {
+  try {
+    applyAgentsSnapshot(await window.api.getBgAgents());
+  } catch (err) {
+    console.warn('[agents-view] roster refresh failed', err);
+  }
+}
+
+function selectAgentsRow(id) {
+  agentsSelectedKey = 'bg:' + id;
+  if (agentsViewActive) renderAgentsView();
+}
+
+function renderAgentRow(entry, nested = false) {
+  const key = agentsEntryKey(entry);
+  const icon = agentRowIcon(entry);
+  const state = entry.kind === 'interactive' ? 'external' : (entry.state || '?');
+  const stateEmoji = agentStateMeta(entry).emoji;
+  const status = entry.status ? ' · ' + entry.status : '';
+  const classes = ['agents-row'];
+  if (nested) classes.push('agents-row--nested');
+  if (key === agentsSelectedKey) classes.push('selected');
+  if (agentsPendingVerbs.has(key)) classes.push('pending');
+  return `<div class="${classes.join(' ')}" data-key="${agentsEscapeAttr(key)}">
+    <span class="session-icon ${icon.slotClass}" title="${agentsEscapeAttr(icon.title)}"></span>
+    <span class="agents-row-name">${escapeHtml(entry.name || entry.sessionId || entry.id || '')}</span>
+    <span class="agents-row-agent">${escapeHtml(entry.agent || '—')}</span>
+    <span class="agents-row-state"><span class="agents-state-emoji" aria-hidden="true">${stateEmoji}</span> ${escapeHtml(state + status)}</span>
+    <span class="agents-row-cwd" title="${agentsEscapeAttr(entry.cwd || '')}">${escapeHtml(entry.cwd ? shortProjectPath(entry.cwd) : '')}</span>
+    <span class="agents-row-age">${escapeHtml(formatAgentAge(entry.startedAt))}</span>
+  </div>`;
+}
+
+function agentsCollapseKey(mode, group, parentKey) {
+  if (mode === 'worktree') return `worktree:${parentKey}|${group.key}`;
+  return `${mode}:${group.key}`;
+}
+
+function parseCollapsedGroups(text) {
+  let list;
+  try { list = JSON.parse(text); } catch { return []; }
+  if (!Array.isArray(list)) return [];
+  const keys = [...new Set(list.filter(k => typeof k === 'string'))];
+  return keys.slice(-AGENTS_COLLAPSE_MAX);
+}
+
+function serializeCollapsedGroups(keys) {
+  return JSON.stringify([...keys].slice(-AGENTS_COLLAPSE_MAX));
+}
+
+function readAgentsCollapsedGroups() {
+  try {
+    return new Set(parseCollapsedGroups(localStorage.getItem('agentsCollapsedGroups')));
+  } catch {
+    return new Set();
+  }
+}
+
+function toggleAgentsGroup(collapseKey) {
+  if (agentsCollapsedGroups.has(collapseKey)) agentsCollapsedGroups.delete(collapseKey);
+  else agentsCollapsedGroups.add(collapseKey);
+  while (agentsCollapsedGroups.size > AGENTS_COLLAPSE_MAX) agentsCollapsedGroups.delete(agentsCollapsedGroups.values().next().value);
+  try { localStorage.setItem('agentsCollapsedGroups', serializeCollapsedGroups(agentsCollapsedGroups)); } catch {}
+  renderAgentsView();
+}
+
+function renderAgentHeader(cls, group, collapseKey, collapsed) {
+  const title = group.title ? ` title="${agentsEscapeAttr(group.title)}"` : '';
+  const emoji = group.emoji ? `<span class="agents-group-emoji" aria-hidden="true">${group.emoji}</span> ` : '';
+  const chevron = `<span class="agents-group-chevron" aria-hidden="true">${collapsed ? '▸' : '▾'}</span> `;
+  return `<div class="${cls}" data-collapse="${agentsEscapeAttr(collapseKey)}" role="button" tabindex="0" aria-expanded="${collapsed ? 'false' : 'true'}"${title}>${chevron}${emoji}<span class="agents-group-label">${escapeHtml(group.label)}</span> · <span class="agents-group-count">${group.entries.length}</span></div>`;
+}
+
+function renderAgentGroup(group) {
+  const key = agentsCollapseKey(agentsGroupBy, group);
+  const collapsed = agentsCollapsedGroups.has(key);
+  const head = renderAgentHeader('agents-group-header', group, key, collapsed);
+  if (collapsed) return head;
+  if (!group.children) return head + group.entries.map(e => renderAgentRow(e)).join('');
+  return head + group.children.map((c) => {
+    const subKey = agentsCollapseKey('worktree', c, group.key);
+    const subCollapsed = agentsCollapsedGroups.has(subKey);
+    const subHead = renderAgentHeader('agents-subgroup-header', c, subKey, subCollapsed);
+    return subCollapsed ? subHead : subHead + c.entries.map(e => renderAgentRow(e, true)).join('');
+  }).join('');
+}
+
+function renderAgentList(visible) {
+  if (agentsGroupBy === 'none') return visible.map(e => renderAgentRow(e)).join('');
+  return groupAgentEntries(visible, agentsGroupBy, { worktrees: agentsGroupWorktrees }).map(renderAgentGroup).join('');
+}
+
+function readAgentsGroupWorktrees() {
+  try {
+    return localStorage.getItem('agentsGroupWorktrees') !== '0';
+  } catch {
+    return true;
+  }
+}
+
+function readAgentsGroupBy() {
+  try {
+    return normalizeAgentsGroupBy(localStorage.getItem('agentsGroupBy'));
+  } catch {
+    return 'state';
+  }
+}
+
+function renderAgentDetail(entry) {
+  const key = agentsEntryKey(entry);
+  const v = agentVerbAvailability(entry, agentsDaemonReachable);
+  const pending = agentsPendingVerbs.has(key);
+  const btn = (verb, label, enabled) =>
+    `<button type="button" class="agents-verb-btn" data-verb="${verb}"${enabled && !pending ? '' : ' disabled'}>${label}</button>`;
+  const meta = [];
+  if (Number.isFinite(entry.tokens)) meta.push(formatTokens(entry.tokens) + ' tokens');
+  if (entry.model) meta.push(entry.model);
+  if (Number.isFinite(entry.startedAt)) meta.push('started ' + new Date(entry.startedAt).toLocaleString());
+  if (entry.pid) meta.push('pid ' + entry.pid);
+  const fan = (entry.fan || []).map((f) => {
+    const dur = Number.isFinite(f.startedAt) && Number.isFinite(f.doneAt) ? formatAgentAge(f.startedAt, f.doneAt) : '';
+    const tail = f.doneAt ? (dur ? ` (${dur}, done)` : ' (done)') : ' (running)';
+    return `<li>${escapeHtml(f.label || f.id || '')}${escapeHtml(tail)}</li>`;
+  }).join('');
+  const children = (entry.children || []).filter(c => c.href)
+    .map(c => `<a href="#" class="agents-link" data-href="${agentsEscapeAttr(c.href)}">${escapeHtml(c.id || c.href)}</a>`)
+    .join(' · ');
+  const error = agentsVerbErrors.get(key);
+  return `
+    <div class="agents-detail-head">
+      <span class="agents-detail-name">${escapeHtml(entry.name || entry.sessionId || '')}</span>
+      <span class="agents-detail-actions">
+        ${btn('attach', 'Attach', v.attach)}${btn('transcript', 'Transcript', v.transcript)}${btn('stop', 'Stop', v.stop)}${btn('respawn', 'Respawn', v.respawn)}${btn('rm', 'Delete', v.rm)}
+      </span>
+    </div>
+    ${entry.detail ? `<div class="agents-detail-line">${escapeHtml(entry.detail)}</div>` : ''}
+    ${meta.length ? `<div class="agents-detail-meta">${escapeHtml(meta.join(' · '))}</div>` : ''}
+    ${entry.kind === 'interactive' ? `<div class="agents-detail-meta">${escapeHtml(entry.cwd || '')}${entry.status ? ' · ' + escapeHtml(entry.status) : ''}</div>` : ''}
+    ${fan ? `<div class="agents-detail-section">Subagents<ul>${fan}</ul></div>` : ''}
+    ${children ? `<div class="agents-detail-section">Produced: ${children}</div>` : ''}
+    ${entry.result ? `<div class="agents-detail-section">Last result: ${escapeHtml(entry.result)}</div>` : ''}
+    ${error ? `<div class="agents-detail-error">${escapeHtml(error)}</div>` : ''}
+  `;
+}
+
+function renderAgentsView() {
+  const listEl = document.getElementById('agents-list');
+  const detailEl = document.getElementById('agents-detail');
+  const countEl = document.getElementById('agents-viewer-count');
+  const bannerEl = document.getElementById('agents-viewer-banner');
+  if (!listEl || !detailEl) return;
+  const visible = sortAgentEntries(agentsRoster.filter(e => agentsShowFinished || agentIsLive(e)));
+  const running = agentsRoster.filter(agentJobIsLive).length;
+  const finished = agentsRoster.filter(e => e.kind === 'background' && !agentJobIsLive(e)).length;
+  const worktreesBox = document.getElementById('agents-group-worktrees');
+  if (worktreesBox) worktreesBox.disabled = agentsGroupBy !== 'project';
+  if (countEl) countEl.textContent = `${running} running · ${finished} finished`;
+  if (bannerEl) {
+    bannerEl.textContent = 'The daemon is not answering; state comes from files only.';
+    bannerEl.style.display = agentsDaemonReachable ? 'none' : '';
+  }
+  if (agentsSelectedKey && !visible.some(e => agentsEntryKey(e) === agentsSelectedKey)) agentsSelectedKey = null;
+
+  const nextList = document.createElement('div');
+  nextList.id = 'agents-list';
+  nextList.innerHTML = visible.length
+    ? renderAgentList(visible)
+    : '<div class="plans-empty">No background agents. <code>claude --bg</code> starts one, or New agent.</div>';
+  morphdom(listEl, nextList);
+
+  const selected = agentsSelectedEntry();
+  const nextDetail = document.createElement('div');
+  nextDetail.id = 'agents-detail';
+  nextDetail.innerHTML = selected ? renderAgentDetail(selected) : '<div class="agents-detail-empty">Select an agent</div>';
+  morphdom(detailEl, nextDetail);
+}
+
+function attachBgAgent(entry) {
+  if (!entry || !agentJobIsLive(entry) || !entry.sessionId) return;
+  let session = sessionMap.get(entry.sessionId);
+  if (!session) {
+    session = { sessionId: entry.sessionId, projectPath: entry.cwd, name: entry.name, summary: entry.name || entry.id, firstPrompt: '' };
+    sessionMap.set(entry.sessionId, session);
+  }
+  if (agentsViewActive && gridViewActive) hideAgentsView();
+  openSession(session, { type: 'attach', jobId: entry.id, cwd: entry.cwd });
+}
+
+async function runAgentVerb(verb, entry) {
+  if (!entry) return;
+  const key = agentsEntryKey(entry);
+  if (verb === 'transcript') {
+    showJsonlViewer(sessionMap.get(entry.sessionId) || { sessionId: entry.sessionId, name: entry.name, projectPath: entry.cwd });
+    return;
+  }
+  if (verb === 'attach') {
+    attachBgAgent(entry);
+    return;
+  }
+  if (verb === 'rm' && !window.confirm('Delete this background session? Its conversation goes, and its worktree when that is safe.')) return;
+  if (entry.attachedHere && (verb === 'stop' || verb === 'rm')) {
+    try { await window.api.stopSession(entry.sessionId); } catch {}
+  }
+  agentsPendingVerbs.add(key);
+  agentsVerbErrors.delete(key);
+  if (agentsViewActive) renderAgentsView();
+  let result;
+  try {
+    result = await window.api.bgAgentVerb(verb, entry.id);
+  } catch (err) {
+    result = { ok: false, error: err && err.message ? err.message : String(err) };
+  }
+  agentsPendingVerbs.delete(key);
+  if (!result || result.ok === false) agentsVerbErrors.set(key, (result && result.error) || 'unknown error');
+  await refreshAgentsRoster();
+}
+
+function setAgentsToggleActive(on) {
+  const btn = document.getElementById('agents-toggle-btn');
+  if (btn) btn.classList.toggle('active', on);
+}
+
+async function showAgentsView() {
+  hideAllViewers();
+  placeholder.style.display = 'none';
+  terminalArea.style.display = 'none';
+  terminalHeader.style.display = 'none';
+  const el = document.getElementById('agents-viewer');
+  if (el) el.style.display = 'flex';
+  agentsViewActive = true;
+  localStorage.setItem('agentsViewActive', '1');
+  setAgentsToggleActive(true);
+  renderAgentsView();
+  await refreshAgentsRoster();
+  if (!agentsReconcileTimer) {
+    agentsReconcileTimer = setInterval(() => { if (agentsViewActive) refreshAgentsRoster(); }, AGENTS_RECONCILE_MS);
+  }
+}
+
+function hideAgentsView({ restore = true } = {}) {
+  const el = document.getElementById('agents-viewer');
+  if (el) el.style.display = 'none';
+  const wasActive = agentsViewActive;
+  agentsViewActive = false;
+  if (wasActive) localStorage.setItem('agentsViewActive', '0');
+  if (agentsReconcileTimer) { clearInterval(agentsReconcileTimer); agentsReconcileTimer = null; }
+  setAgentsToggleActive(false);
+  if (!wasActive || !restore) return;
+  terminalArea.style.display = '';
+  if (gridViewActive) {
+    placeholder.style.display = 'none';
+    terminalHeader.style.display = 'none';
+    gridViewer.style.display = 'block';
+    for (const entry of openSessions.values()) if (!entry.closed) fitAndScroll(entry);
+  } else if (activeSessionId && openSessions.has(activeSessionId)) {
+    showSession(activeSessionId);
+  } else {
+    placeholder.style.display = '';
+  }
+}
+
+function toggleAgentsView() {
+  if (agentsViewActive) hideAgentsView();
+  else showAgentsView();
+}
+
+async function restoreAgentsViewAtStartup() {
+  if (!agentsOpenAtStartup) return;
+  agentsOpenAtStartup = false;
+  await showAgentsView();
+}
+
+function initAgentsView() {
+  agentsOpenAtStartup = localStorage.getItem('agentsViewActive') === '1';
+  agentsShowFinished = localStorage.getItem('agentsShowFinished') !== '0';
+  const box = document.getElementById('agents-show-finished');
+  if (box) {
+    box.checked = agentsShowFinished;
+    box.addEventListener('change', () => {
+      agentsShowFinished = box.checked;
+      localStorage.setItem('agentsShowFinished', agentsShowFinished ? '1' : '0');
+      renderAgentsView();
+    });
+  }
+  agentsGroupBy = readAgentsGroupBy();
+  const groupSel = document.getElementById('agents-group-by');
+  if (groupSel) {
+    groupSel.value = agentsGroupBy;
+    groupSel.addEventListener('change', () => {
+      agentsGroupBy = normalizeAgentsGroupBy(groupSel.value);
+      try { localStorage.setItem('agentsGroupBy', agentsGroupBy); } catch {}
+      renderAgentsView();
+    });
+  }
+  agentsCollapsedGroups = readAgentsCollapsedGroups();
+  agentsGroupWorktrees = readAgentsGroupWorktrees();
+  const worktreesBox = document.getElementById('agents-group-worktrees');
+  if (worktreesBox) {
+    worktreesBox.checked = agentsGroupWorktrees;
+    worktreesBox.disabled = agentsGroupBy !== 'project';
+    worktreesBox.addEventListener('change', () => {
+      agentsGroupWorktrees = worktreesBox.checked;
+      try { localStorage.setItem('agentsGroupWorktrees', agentsGroupWorktrees ? '1' : '0'); } catch {}
+      renderAgentsView();
+    });
+  }
+  const newBtn = document.getElementById('agents-new-btn');
+  if (newBtn) {
+    newBtn.addEventListener('click', () => {
+      if (typeof showDispatchAgentDialog !== 'function') return;
+      const active = activeSessionId ? sessionMap.get(activeSessionId) : null;
+      showDispatchAgentDialog(active && active.projectPath ? { projectPath: active.projectPath } : null);
+    });
+  }
+  const viewer = document.getElementById('agents-viewer');
+  if (viewer) {
+    viewer.addEventListener('click', (e) => {
+      const link = e.target.closest('.agents-link');
+      if (link) {
+        e.preventDefault();
+        window.api.openExternal(link.dataset.href);
+        return;
+      }
+      const verbBtn = e.target.closest('.agents-verb-btn');
+      if (verbBtn) {
+        if (!verbBtn.disabled) runAgentVerb(verbBtn.dataset.verb, agentsSelectedEntry());
+        return;
+      }
+      const head = e.target.closest('[data-collapse]');
+      if (head) {
+        toggleAgentsGroup(head.dataset.collapse);
+        return;
+      }
+      const row = e.target.closest('.agents-row');
+      if (row) {
+        agentsSelectedKey = row.dataset.key;
+        renderAgentsView();
+      }
+    });
+  }
+  if (viewer) {
+    viewer.addEventListener('dblclick', (e) => {
+      if (e.target.closest('.agents-verb-btn, .agents-link, [data-collapse]')) return;
+      const row = e.target.closest('.agents-row');
+      if (!row) return;
+      const entry = agentsRoster.find(x => agentsEntryKey(x) === row.dataset.key);
+      if (entry && agentVerbAvailability(entry, agentsDaemonReachable).attach) attachBgAgent(entry);
+    });
+    viewer.addEventListener('keydown', (e) => {
+      if (e.key !== 'Enter' && e.key !== ' ') return;
+      const head = e.target.closest && e.target.closest('[data-collapse]');
+      if (!head) return;
+      e.preventDefault();
+      toggleAgentsGroup(head.dataset.collapse);
+    });
+  }
+  window.api.onBgAgentsChanged((snapshot) => applyAgentsSnapshot(snapshot));
+}
+
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = { sortAgentEntries, agentRowIcon, agentVerbAvailability, formatTokens, formatAgentAge, agentsEntryKey, groupAgentEntries, normalizeAgentsGroupBy, AGENT_STATE_META, agentStateMeta,
+    agentsCollapseKey, parseCollapsedGroups, serializeCollapsedGroups, AGENTS_COLLAPSE_MAX };
+}
diff --git a/public/app.js b/public/app.js
index 54c151db..c7d086db 100644
--- a/public/app.js
+++ b/public/app.js
@@ -177,6 +177,7 @@ function persistWorkingSet() {
     const set = [];
     for (const [sessionId, entry] of openSessions) {
       if (entry.session.type === 'terminal') continue; // exclude plain shells
+      if (entry.attach) continue; // attach tabs are not restored
       if (entry.closed) continue;
       set.push({
         sessionId,
@@ -891,7 +892,8 @@ async function triggerRebuildAndSearch() {
 // see .ai/contexts/session-state.md ("The two lifecycle verbs: detach and stop")
 // btn (optional): the clicked control, flashed on failure instead of alert() — see sidebar.js's session-delete-btn
 async function confirmAndStopSession(sessionId, btn) {
-  const plan = resolveSessionStop(sessionMap.get(sessionId));
+  const openEntry = openSessions.get(sessionId);
+  const plan = resolveSessionStop(sessionMap.get(sessionId), { attach: !!(openEntry && openEntry.attach) });
   if (!confirm(plan.confirmText)) return;
   const result = plan.remote
     ? await window.api.remoteStopSession(plan.alias, sessionId)
@@ -1215,6 +1217,9 @@ async function showTerminalHeader(session) {
   terminalHeaderName.textContent = displayName;
   terminalHeaderId.textContent = session.sessionId;
   terminalHeaderSandbox.style.display = sandboxedSessions.get(session.sessionId) ? '' : 'none';
+  const headerEntry = openSessions.get(session.sessionId);
+  terminalStopBtn.title = headerEntry && headerEntry.attach ? 'Detach (the session keeps running)' : 'Stop process';
+  terminalStopBtn.setAttribute('aria-label', terminalStopBtn.title);
   terminalHeader.style.display = '';
   updateTerminalHeader();
 
@@ -1252,8 +1257,12 @@ async function openSession(session, customOptions, { automatic = false, live } =
     }
   }
 
-  // see .ai/contexts/cli-session-state.md ("Live elsewhere")
-  if (!(await guardResume(session, { automatic, live, api: window.api, confirm: (msg) => window.confirm(msg) }))) return false;
+  // see .ai/contexts/cli-session-state.md ("Live elsewhere") and .ai/contexts/bg-agents.md ("Attach")
+  const verdict = customOptions?.type === 'attach' ? true : await guardResume(session, { automatic, live, api: window.api, confirm: (msg) => window.confirm(msg) });
+  if (verdict === false) return false;
+  if (verdict && typeof verdict === 'object' && verdict.attach) {
+    customOptions = { type: 'attach', jobId: verdict.attach, cwd: verdict.cwd || projectPath };
+  }
 
   // Create new terminal entry (hidden until showSession)
   const entry = createTerminalEntry(session);
@@ -1261,6 +1270,7 @@ async function openSession(session, customOptions, { automatic = false, live } =
   // Open terminal in main process — see .ai/contexts/session-state.md ("Reopening a plain terminal")
   const resumeOptions = customOptions
     || (session.type === 'terminal' ? { type: 'terminal' } : await resolveDefaultSessionOptions({ projectPath }));
+  entry.attach = resumeOptions.type === 'attach';
   forgetSessionExit(sessionId);
   beginPtyOpen(sessionId);
   let result;
@@ -1277,6 +1287,7 @@ async function openSession(session, customOptions, { automatic = false, live } =
     showSession(sessionId);
     return;
   }
+  if (result.reattached) entry.attach = !!result.attach;
   skippedWorkingSetEntries.delete(sessionId);
   syncPtySizeAfterOpen(entry);
   if (typeof setSessionMcpState === 'function') setSessionMcpState(sessionId, result.mcpState, result.mcpError);
@@ -1359,6 +1370,7 @@ document.querySelectorAll('.sidebar-tab').forEach(tab => {
       terminalArea.style.display = 'none';
       memoryViewer.style.display = 'none';
       settingsViewer.style.display = 'none';
+      if (typeof hideAgentsView === 'function') hideAgentsView({ restore: false });
       statsViewer.style.display = 'flex';
       loadStats();
     } else if (tabName === 'memory') {
@@ -1379,6 +1391,7 @@ document.querySelectorAll('.sidebar-tab').forEach(tab => {
 // Initialize grid observers now that DOM refs are ready
 initGridObservers();
 initGridGroupToggle();
+initAgentsView();
 
 // JSONL viewer (renderJsonlText, formatDuration, makeCollapsible, renderJsonlEntry, showJsonlViewer) → jsonl-viewer.js
 
@@ -1454,11 +1467,23 @@ initGridGroupToggle();
   // Insert next to the resort button
   resortBtn.parentElement.insertBefore(gridToggleBtn, resortBtn);
 
+  const agentsToggleBtn = document.createElement('button');
+  agentsToggleBtn.id = 'agents-toggle-btn';
+  agentsToggleBtn.title = 'Background agents';
+  agentsToggleBtn.innerHTML = '<svg width="14" height="14" stroke="currentColor" fill="none" stroke-width="2" viewBox="0 0 24 24" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="8" r="4"></circle><path d="M4 21v-1a6 6 0 0 1 6-6h4a6 6 0 0 1 6 6v1"></path></svg>';
+  agentsToggleBtn.addEventListener('click', toggleAgentsView);
+  resortBtn.parentElement.insertBefore(agentsToggleBtn, resortBtn);
+
   // Global keyboard shortcuts (covers non-terminal focus)
   // When a terminal is focused, xterm's customKeyEventHandler fires first and sets
   // e._handled to prevent the document listener from double-firing the same action.
   document.addEventListener('keydown', (e) => {
     if (e._handled) return;
+    if (matchShortcut('agentsToggle', e, isMac, appShortcuts)) {
+      e.preventDefault();
+      toggleAgentsView();
+      return;
+    }
     // Toggle grid view (default Cmd/Ctrl+Shift+G)
     if (matchShortcut('gridToggle', e, isMac, appShortcuts)) {
       e.preventDefault();
@@ -1527,6 +1552,7 @@ loadProjects().then(async () => {
   }
   // Restore working set (persisted across full restarts via global settings)
   await restoreWorkingSet();
+  restoreAgentsViewAtStartup();
 });
 
 // Live-reload sidebar when filesystem changes are detected
diff --git a/public/dialogs.js b/public/dialogs.js
index 04e61086..49b7f3db 100644
--- a/public/dialogs.js
+++ b/public/dialogs.js
@@ -585,3 +585,167 @@ function showAddProjectDialog() {
   }
   document.addEventListener('keydown', onKey);
 }
+
+// see .ai/contexts/bg-agents.md
+async function showDispatchAgentDialog(project) {
+  const projects = (typeof cachedAllProjects !== 'undefined' ? cachedAllProjects : [])
+    .map(p => p && p.projectPath).filter(Boolean);
+  const requested = project && project.projectPath;
+  if (requested && !projects.includes(requested)) projects.unshift(requested);
+  const defaultPath = requested || projects[0] || '';
+  let effective = {};
+  if (defaultPath) {
+    try { effective = (await window.api.getEffectiveSettings(defaultPath)) || {}; } catch { effective = {}; }
+  }
+
+  const overlay = document.createElement('div');
+  overlay.className = 'new-session-overlay';
+  const dialog = document.createElement('div');
+  dialog.className = 'new-session-dialog dispatch-agent-dialog';
+
+  let selectedMode = effective.permissionMode || null;
+  let dangerousSkip = !!effective.dangerouslySkipPermissions;
+
+  function renderModeGrid() {
+    return PERMISSION_MODES.map(m => {
+      const isSelected = !dangerousSkip && selectedMode === m.value;
+      return `<button class="permission-option${isSelected ? ' selected' : ''}" data-mode="${m.value}"><span class="perm-name">${m.label}</span><span class="perm-desc">${m.desc}</span></button>`;
+    }).join('') +
+    `<button class="permission-option dangerous${dangerousSkip ? ' selected' : ''}" data-mode="dangerous-skip"><span class="perm-name">Dangerous Skip</span><span class="perm-desc">Skip all safety prompts (use with caution)</span></button>`;
+  }
+
+  dialog.innerHTML = `
+    <h3>New background agent</h3>
+    <div class="settings-field settings-field-wide">
+      <div class="settings-field-info">
+        <span class="settings-label">Prompt</span>
+        <div class="settings-description">The task the agent runs, in the background, under the claude daemon</div>
+      </div>
+      <div class="settings-field-control">
+        <textarea class="settings-input" id="dad-prompt" rows="4"></textarea>
+      </div>
+    </div>
+    <div class="settings-field">
+      <div class="settings-field-info">
+        <span class="settings-label">Project</span>
+        <div class="settings-description">Working directory of the agent</div>
+      </div>
+      <div class="settings-field-control">
+        <select class="settings-input" id="dad-project"></select>
+      </div>
+    </div>
+    <div class="settings-field">
+      <div class="settings-field-info">
+        <span class="settings-label">Name</span>
+        <div class="settings-description">--name; empty lets the CLI pick one</div>
+      </div>
+      <div class="settings-field-control">
+        <input type="text" class="settings-input" id="dad-name" placeholder="optional">
+      </div>
+    </div>
+    <div class="settings-field">
+      <div class="settings-field-info">
+        <span class="settings-label">Agent</span>
+        <div class="settings-description">--agent, e.g. fleet:em; empty for none</div>
+      </div>
+      <div class="settings-field-control">
+        <input type="text" class="settings-input" id="dad-agent" placeholder="optional">
+      </div>
+    </div>
+    <div class="settings-field">
+      <div class="settings-label">Permission Mode</div>
+      <div class="permission-grid" id="dad-mode-grid">${renderModeGrid()}</div>
+    </div>
+    <div class="settings-field settings-field-wide">
+      <div class="settings-field-info">
+        <span class="settings-label">Additional Directories</span>
+        <div class="settings-description">Extra directories to include (comma-separated)</div>
+      </div>
+      <div class="settings-field-control">
+        <input type="text" class="settings-input" id="dad-add-dirs" placeholder="/path/to/dir1, /path/to/dir2">
+      </div>
+    </div>
+    <div id="dad-error" class="agents-detail-error"></div>
+    <div class="new-session-actions">
+      <button class="new-session-cancel-btn">Cancel</button>
+      <button class="new-session-start-btn">Start</button>
+    </div>
+  `;
+
+  const projectSelect = dialog.querySelector('#dad-project');
+  for (const p of projects) {
+    const opt = document.createElement('option');
+    opt.value = p;
+    opt.textContent = shortProjectPath(p);
+    if (p === defaultPath) opt.selected = true;
+    projectSelect.appendChild(opt);
+  }
+  dialog.querySelector('#dad-add-dirs').value = effective.addDirs || SETTING_DEFAULTS.addDirs || '';
+
+  overlay.appendChild(dialog);
+  document.body.appendChild(overlay);
+
+  const modeGrid = dialog.querySelector('#dad-mode-grid');
+  modeGrid.addEventListener('click', (e) => {
+    const btn = e.target.closest('.permission-option');
+    if (!btn) return;
+    const mode = btn.dataset.mode;
+    if (mode === 'dangerous-skip') {
+      dangerousSkip = !dangerousSkip;
+      if (dangerousSkip) selectedMode = null;
+    } else {
+      dangerousSkip = false;
+      selectedMode = mode === 'null' ? null : mode;
+    }
+    modeGrid.innerHTML = renderModeGrid();
+  });
+
+  const errorEl = dialog.querySelector('#dad-error');
+  const startBtn = dialog.querySelector('.new-session-start-btn');
+  let starting = false;
+
+  function close() {
+    overlay.remove();
+    document.removeEventListener('keydown', onKey);
+  }
+
+  async function start() {
+    if (starting) return;
+    const prompt = dialog.querySelector('#dad-prompt').value.trim();
+    if (!prompt) { errorEl.textContent = 'A prompt is required.'; return; }
+    const fields = {
+      prompt,
+      name: dialog.querySelector('#dad-name').value.trim(),
+      agent: dialog.querySelector('#dad-agent').value.trim(),
+      cwd: projectSelect.value,
+      permissionMode: dangerousSkip ? null : selectedMode,
+      dangerouslySkipPermissions: dangerousSkip,
+      addDirs: dialog.querySelector('#dad-add-dirs').value.trim(),
+    };
+    errorEl.textContent = '';
+    starting = true;
+    startBtn.disabled = true;
+    let result;
+    try { result = await window.api.dispatchBgAgent(fields); } catch (err) { result = { ok: false, error: err && err.message }; }
+    starting = false;
+    startBtn.disabled = false;
+    if (!result || result.ok === false) {
+      errorEl.textContent = (result && result.error) || 'unknown error';
+      return;
+    }
+    close();
+    if (result.id && typeof selectAgentsRow === 'function') selectAgentsRow(result.id);
+    if (typeof refreshAgentsRoster === 'function') refreshAgentsRoster();
+  }
+
+  dialog.querySelector('.new-session-cancel-btn').onclick = close;
+  startBtn.onclick = start;
+  overlay.addEventListener('click', (e) => { if (e.target === overlay) close(); });
+
+  function onKey(e) {
+    if (e.key === 'Escape') close();
+    if (e.key === 'Enter' && !e.target.matches('input, textarea, select, button')) start();
+  }
+  document.addEventListener('keydown', onKey);
+  dialog.querySelector('#dad-prompt').focus();
+}
diff --git a/public/grid-view.js b/public/grid-view.js
index f74cad9e..02438fbd 100644
--- a/public/grid-view.js
+++ b/public/grid-view.js
@@ -401,6 +401,7 @@ function showGridView() {
   memoryViewer.style.display = 'none';
   settingsViewer.style.display = 'none';
   jsonlViewer.style.display = 'none';
+  if (typeof hideAgentsView === 'function') hideAgentsView({ restore: false });
   terminalArea.style.display = '';
 
   // Switch #terminals to grid layout
diff --git a/public/index.html b/public/index.html
index b9a71b9c..c4abb86e 100644
--- a/public/index.html
+++ b/public/index.html
@@ -75,6 +75,27 @@
       </div>
       <div id="jsonl-viewer-body"></div>
     </div>
+    <div id="agents-viewer" style="display:none;">
+      <div id="agents-viewer-header">
+        <span id="agents-viewer-title">Agents</span>
+        <span id="agents-viewer-count"></span>
+        <label id="agents-finished-toggle"><input type="checkbox" id="agents-show-finished" checked> Finished</label>
+        <label id="agents-group-toggle">Group
+          <select id="agents-group-by" title="Group the list">
+            <option value="none">None</option>
+            <option value="state" selected>State</option>
+            <option value="project">Project</option>
+          </select>
+        </label>
+        <label id="agents-worktrees-toggle" title="Sub-group each project by worktree"><input type="checkbox" id="agents-group-worktrees" checked> Worktrees</label>
+        <button id="agents-new-btn" type="button">New agent</button>
+      </div>
+      <div id="agents-viewer-banner" style="display:none;"></div>
+      <div id="agents-viewer-body">
+        <div id="agents-list"></div>
+        <div id="agents-detail"></div>
+      </div>
+    </div>
     <div id="terminal-area">
       <div id="terminal-header" style="display:none;">
         <div id="terminal-header-info">
@@ -155,6 +176,8 @@
   <script src="remote-activity-ui.js"></script>
   <script src="local-transcript-adapter.js"></script>
   <script src="memory-workfiles-view.js"></script>
+  <!-- see .ai/contexts/bg-agents.md -->
+  <script src="agents-view.js"></script>
   <!-- restore-plan.js decides working-set restore vs. defer-and-retry; consumed by app.js only. -->
   <script src="restore-plan.js"></script>
   <script src="resume-guard.js"></script>
diff --git a/public/memory-workfiles-view.js b/public/memory-workfiles-view.js
index 6b2b0871..1aa5381c 100644
--- a/public/memory-workfiles-view.js
+++ b/public/memory-workfiles-view.js
@@ -16,6 +16,7 @@ function hideAllViewers() {
   if (traceViewer) traceViewer.style.display = 'none';
   settingsViewer.style.display = 'none';
   jsonlViewer.style.display = 'none';
+  if (typeof hideAgentsView === 'function') hideAgentsView({ restore: false });
   terminalArea.style.display = '';
   // Stop any subagent file-watches kept alive by Agent blocks that the user
   // was viewing — without this, fs.watchFile keeps polling indefinitely.
@@ -192,6 +193,7 @@ async function openMemory(file) {
   terminalArea.style.display = 'none';
   statsViewer.style.display = 'none';
   settingsViewer.style.display = 'none';
+  if (typeof hideAgentsView === 'function') hideAgentsView({ restore: false });
   memoryViewer.style.display = 'flex';
 
   memoryPanel.open(file.filename, file.filePath, content);
@@ -344,6 +346,7 @@ async function openWorkFile(file) {
   statsViewer.style.display = 'none';
   settingsViewer.style.display = 'none';
   memoryViewer.style.display = 'none';
+  if (typeof hideAgentsView === 'function') hideAgentsView({ restore: false });
   workFilesViewer.style.display = 'flex';
 
   workFilesPanel.open(file.filename, file.filePath, content);
diff --git a/public/resume-guard.js b/public/resume-guard.js
index 7c088d38..90b36830 100644
--- a/public/resume-guard.js
+++ b/public/resume-guard.js
@@ -28,6 +28,11 @@ async function guardResume(session, { automatic = false, api, confirm, live } =
   }
   if (!live) return true;
   if (automatic) return false;
+  // see .ai/contexts/bg-agents.md
+  if (live.kind === 'bg') {
+    if (typeof live.jobId === 'string' && live.jobId) return { attach: live.jobId, cwd: live.cwd || null };
+    return false;
+  }
   return !!confirm(liveElsewhereMessage(live));
 }
 
diff --git a/public/settings-panel.js b/public/settings-panel.js
index 88e39d0b..c53af288 100644
--- a/public/settings-panel.js
+++ b/public/settings-panel.js
@@ -42,6 +42,7 @@
     document.getElementById('stats-viewer').style.display = 'none';
     document.getElementById('memory-viewer').style.display = 'none';
     document.getElementById('jsonl-viewer').style.display = 'none';
+    if (typeof hideAgentsView === 'function') hideAgentsView({ restore: false });
     settingsViewer.style.display = 'flex';
 
     function useGlobalCheckbox(fieldName) {
diff --git a/public/shortcuts.js b/public/shortcuts.js
index f192850e..358a1708 100644
--- a/public/shortcuts.js
+++ b/public/shortcuts.js
@@ -20,6 +20,8 @@ const DEFAULT_SHORTCUTS = {
   sessionNavBrackets: { primary: true, alt: false, shift: true },
   // Ctrl/Cmd+Shift+G — toggle the grid overview.
   gridToggle: { primary: true, alt: false, shift: true, key: 'g' },
+  // Ctrl/Cmd+Shift+A — toggle the background agents view.
+  agentsToggle: { primary: true, alt: false, shift: true, key: 'a' },
 };
 
 // Metadata for rendering the settings UI and resolving each action's key family.
@@ -42,6 +44,12 @@ const SHORTCUT_DEFS = [
     description: 'Show or hide the session grid overview',
     family: 'key',
   },
+  {
+    id: 'agentsToggle',
+    label: 'Toggle agents view',
+    description: 'Show or hide the background agents view',
+    family: 'key',
+  },
 ];
 
 function getDef(id) {
diff --git a/public/sidebar.js b/public/sidebar.js
index d5adc0f6..45d5ca4a 100644
--- a/public/sidebar.js
+++ b/public/sidebar.js
@@ -1493,6 +1493,15 @@ function buildSessionItem(session) {
     summaryEl.prepend(badge);
   }
 
+  // see .ai/contexts/bg-agents.md ("The sidebar")
+  if (typeof bgAgentSessionIds !== 'undefined' && bgAgentSessionIds.has(session.sessionId)) {
+    const badge = document.createElement('span');
+    badge.className = 'bg-badge';
+    badge.title = 'Background session run by the claude daemon — click to attach';
+    badge.textContent = 'bg';
+    summaryEl.prepend(badge);
+  }
+
   if (session.type === 'terminal') {
     const badge = document.createElement('span');
     badge.className = 'terminal-badge';
diff --git a/public/stop-session-ui.js b/public/stop-session-ui.js
index 32ec02ff..e42fff23 100644
--- a/public/stop-session-ui.js
+++ b/public/stop-session-ui.js
@@ -1,12 +1,15 @@
 // Dual-mode helper — see .ai/contexts/session-state.md ("The two lifecycle verbs: detach and stop")
 
 // session: the sessionMap entry for the row being stopped, or undefined.
-function resolveSessionStop(session) {
+function resolveSessionStop(session, { attach = false } = {}) {
   const alias = session && session.remoteAlias;
   if (alias) {
-    return { remote: true, alias, confirmText: `Stop this session on ${alias}?` };
+    return { remote: true, alias, attach: false, confirmText: `Stop this session on ${alias}?` };
   }
-  return { remote: false, alias: null, confirmText: 'Stop this session?' };
+  if (attach) {
+    return { remote: false, alias: null, attach: true, confirmText: 'Detach from this background session? It keeps running; the Agents view can stop it.' };
+  }
+  return { remote: false, alias: null, attach: false, confirmText: 'Stop this session?' };
 }
 
 // Is this remote session's process still running? See .ai/contexts/session-state.md ("stopBeforeArchive").
diff --git a/public/style.css b/public/style.css
index f84eea81..a8967e48 100644
--- a/public/style.css
+++ b/public/style.css
@@ -1322,6 +1322,7 @@ body { display: flex; flex-direction: column; }
   flex-direction: column;
   position: relative;
   min-height: 0;
+  min-width: 0;
   background: var(--surface-sunken);
 }
 
@@ -1680,6 +1681,65 @@ body { display: flex; flex-direction: column; }
   margin-right: auto;
 }
 
+/* Agents view — see .ai/contexts/bg-agents.md */
+#agents-viewer { display: none; flex-direction: column; flex: 1; min-height: 0; }
+#agents-viewer-header {
+  display: flex; flex-wrap: wrap; align-items: center; gap: 6px 10px; padding: 8px 16px;
+  background: var(--surface-chrome); border-bottom: 1px solid var(--hairline); flex-shrink: 0;
+}
+#agents-new-btn { flex-shrink: 0; }
+#agents-viewer-title { font-size: 13px; color: #b0b0c4; font-weight: 500; }
+#agents-viewer-count { font-size: 11px; color: #7a7a90; margin-right: auto; }
+#agents-worktrees-toggle:has(input:disabled) { opacity: 0.5; }
+#agents-finished-toggle, #agents-group-toggle, #agents-worktrees-toggle { font-size: 11px; color: #7a7a90; display: inline-flex; align-items: center; gap: 4px; }
+#agents-group-by, #agents-new-btn, .agents-verb-btn {
+  background: transparent; border: 1px solid var(--control-border); color: #b0b0c4;
+  font-size: 11px; padding: 3px 8px; border-radius: 6px; cursor: pointer; font-family: inherit;
+}
+#agents-group-by:hover, #agents-new-btn:hover, .agents-verb-btn:hover:not([disabled]) { background: var(--control-surface); }
+#agents-group-by option { background: var(--surface-chrome); color: #c8c8d8; }
+.agents-group-header {
+  padding: 14px 16px 6px; font-size: 1.2em; font-weight: 600; color: #d0d0e0; line-height: 1.3;
+  border-bottom: 1px solid var(--hairline); background: var(--surface-chrome);
+  overflow: hidden; text-overflow: ellipsis; white-space: nowrap; position: sticky; top: 0; z-index: 1;
+}
+.agents-group-emoji { margin-right: 2px; }
+.agents-group-count { font-weight: 400; font-size: 0.85em; color: var(--text-muted); }
+.agents-state-emoji { margin-right: 2px; }
+.agents-subgroup-header {
+  padding: 8px 16px 4px 28px; font-size: 1em; font-weight: 600; color: var(--text-muted);
+  border-bottom: 1px solid var(--hairline); overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+}
+.agents-row--nested { padding-left: 28px; }
+.agents-group-header, .agents-subgroup-header { cursor: pointer; user-select: none; -webkit-user-select: none; }
+.agents-group-header:hover, .agents-subgroup-header:hover { color: #e8e8f4; }
+.agents-group-header:focus-visible, .agents-subgroup-header:focus-visible { outline: 2px solid var(--accent-border-strong); outline-offset: -2px; }
+.agents-group-chevron { display: inline-block; width: 1em; color: var(--text-muted); font-weight: 400; }
+.agents-verb-btn[disabled] { opacity: 0.4; cursor: default; }
+#agents-viewer-banner { padding: 6px 16px; font-size: 11px; color: #f0a050; background: rgba(240,160,80,0.08); }
+#agents-viewer-body { display: flex; flex-direction: column; flex: 1; min-height: 0; }
+#agents-list { flex: 1; overflow: auto; min-height: 0; font-size: 12px; }
+.agents-row {
+  display: grid; grid-template-columns: 18px minmax(160px, 2fr) minmax(90px, 1fr) minmax(110px, 1fr) minmax(160px, 2fr) 60px;
+  gap: 8px; align-items: center; padding: 6px 16px; font-size: 12px; color: #c8c8d8; cursor: pointer;
+  border-bottom: 1px solid var(--hairline);
+}
+.agents-row:hover { background: var(--control-surface); }
+.agents-row.selected { background: rgba(128,136,255,0.1); }
+.agents-row.pending { opacity: 0.5; }
+.agents-row-name, .agents-row-cwd { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.agents-row-agent, .agents-row-state, .agents-row-age { color: #7a7a90; }
+#agents-detail { border-top: 1px solid var(--hairline); padding: 10px 16px; max-height: 40%; overflow: auto; font-size: 12px; color: #c8c8d8; flex-shrink: 0; }
+.agents-detail-head { display: flex; align-items: center; gap: 10px; margin-bottom: 6px; }
+.agents-detail-name { font-weight: 500; margin-right: auto; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.agents-detail-actions { display: flex; gap: 6px; flex-shrink: 0; }
+.agents-detail-line { margin: 4px 0; }
+.agents-detail-meta, .agents-detail-empty { color: #7a7a90; margin: 4px 0; }
+.agents-detail-section { margin-top: 8px; }
+.agents-detail-section ul { margin: 4px 0 0 16px; padding: 0; }
+.agents-detail-error { margin-top: 8px; color: #f06060; }
+.agents-link { color: var(--accent); }
+
 #grid-group-toggle-btn {
   background: transparent;
   border: 1px solid var(--control-border);
@@ -3263,6 +3323,7 @@ body { display: flex; flex-direction: column; }
 
 /* ========== ADD PROJECT BUTTON ========== */
 #grid-toggle-btn,
+#agents-toggle-btn,
 #resort-btn,
 #add-project-btn {
   background: transparent;
@@ -3284,10 +3345,12 @@ body { display: flex; flex-direction: column; }
 }
 
 #grid-toggle-btn { margin-left: auto; }
+#agents-toggle-btn { margin-left: 2px; }
 #resort-btn { margin-left: 2px; }
 #add-project-btn { margin-left: 2px; }
 
 #grid-toggle-btn:hover,
+#agents-toggle-btn:hover,
 #resort-btn:hover,
 #add-project-btn:hover {
   background: var(--control-surface);
@@ -3295,7 +3358,8 @@ body { display: flex; flex-direction: column; }
   color: #888;
 }
 
-#grid-toggle-btn.active {
+#grid-toggle-btn.active,
+#agents-toggle-btn.active {
   background: rgba(128,136,255,0.1);
   border-color: rgba(128,136,255,0.3);
   color: var(--accent);
@@ -4059,6 +4123,11 @@ body { display: flex; flex-direction: column; }
   box-shadow: 0 16px 48px rgba(0,0,0,0.4);
 }
 
+.new-session-dialog.dispatch-agent-dialog {
+  max-height: calc(100vh - 32px);
+  overflow-y: auto;
+}
+
 .new-session-dialog .new-session-body {
   flex: 1 1 auto;
   min-height: 0;
@@ -4394,6 +4463,12 @@ body { display: flex; flex-direction: column; }
   white-space: nowrap;
 }
 
+.bg-badge {
+  display: inline-block; margin-right: 5px; padding: 0 5px;
+  border: 1px solid #5a4a7a; border-radius: 3px; color: #b39ddb;
+  font-size: 10px; line-height: 15px; vertical-align: middle;
+}
+
 /* Issue #212/#245 — see .ai/contexts/session-cache.md ("Remote hosts —
    freshness contract") and .ai/contexts/cli-session-state.md; shared by
    remote and local sessions, which carry the same status/statusUpdatedAt pair */
@@ -5134,6 +5209,7 @@ body.window-frameless.platform-darwin:not(.window-full-screen) #sidebar.collapse
 body.window-frameless :is(
   #terminal-header,
   #grid-viewer-header,
+  #agents-viewer-header,
   #stats-viewer-header,
   #settings-viewer-header,
   #jsonl-viewer-header,
@@ -5148,6 +5224,7 @@ body.window-frameless :is(
 body.window-frameless #sidebar.collapsed ~ #main :is(
   #terminal-header,
   #grid-viewer-header,
+  #agents-viewer-header,
   #stats-viewer-header,
   #settings-viewer-header,
   #jsonl-viewer-header,
@@ -5159,7 +5236,7 @@ body.window-frameless #sidebar.collapsed ~ #main :is(
 }
 
 body.window-frameless :is(button, input, select, textarea, a, [role="button"], [contenteditable]),
-body.window-frameless :is(#terminal-header-status, #terminal-header-id, #terminal-header-controls [data-header-kind], #jsonl-viewer-session-id, .viewer-toolbar-path),
+body.window-frameless :is(#terminal-header-status, #terminal-header-id, #terminal-header-controls [data-header-kind], #jsonl-viewer-session-id, .viewer-toolbar-path, #agents-viewer-header label),
 body.window-frameless :is(.new-session-popover, .terminal-context-menu, .new-session-overlay, .add-project-overlay, .whats-new-overlay, .jsonl-screenshot-fullscreen, #update-toast, .restore-toast) {
   -webkit-app-region: no-drag;
 }
diff --git a/public/terminal-manager.js b/public/terminal-manager.js
index 3912ee66..b66ebdbe 100644
--- a/public/terminal-manager.js
+++ b/public/terminal-manager.js
@@ -91,6 +91,11 @@ function setupTerminalKeyBindings(terminal, container, getSessionId, { onFind }
       return false;
     }
 
+    if (matchShortcut('agentsToggle', e, isMac, appShortcuts)) {
+      if (e.type === 'keydown') { e._handled = true; toggleAgentsView(); }
+      return false;
+    }
+
     // Toggle grid view (default Cmd/Ctrl+Shift+G)
     if (matchShortcut('gridToggle', e, isMac, appShortcuts)) {
       if (e.type === 'keydown') { e._handled = true; toggleGridView(); }
@@ -1139,6 +1144,7 @@ function showSession(sessionId) {
   lruTouch(sessionId);
 
   if (gridViewActive) {
+    if (typeof hideAgentsView === 'function' && agentsViewActive) hideAgentsView();
     // Ensure grid layout is set up (e.g. on first session after startup restore)
     if (!terminalsEl.classList.contains('grid-layout')) {
       showGridView();
diff --git a/test/agents-toggle-shortcut.test.js b/test/agents-toggle-shortcut.test.js
new file mode 100644
index 00000000..0f7780fd
--- /dev/null
+++ b/test/agents-toggle-shortcut.test.js
@@ -0,0 +1,14 @@
+'use strict';
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { DEFAULT_SHORTCUTS, SHORTCUT_DEFS, matchShortcut, normalizeShortcuts, formatBinding } = require('../public/shortcuts');
+
+test('agentsToggle defaults to Primary+Shift+A and is a rebindable key-family action', () => {
+  assert.deepEqual(DEFAULT_SHORTCUTS.agentsToggle, { primary: true, alt: false, shift: true, key: 'a' });
+  const def = SHORTCUT_DEFS.find(d => d.id === 'agentsToggle');
+  assert.equal(def.family, 'key');
+  assert.equal(formatBinding('agentsToggle', false, normalizeShortcuts(null)), 'Ctrl+Shift+A');
+  const e = { key: 'A', ctrlKey: true, shiftKey: true, altKey: false, metaKey: false };
+  assert.equal(matchShortcut('agentsToggle', e, false, normalizeShortcuts(null)), true);
+  assert.equal(matchShortcut('gridToggle', e, false, normalizeShortcuts(null)), false);
+});
diff --git a/test/agents-view-pure.test.js b/test/agents-view-pure.test.js
new file mode 100644
index 00000000..9c1bda67
--- /dev/null
+++ b/test/agents-view-pure.test.js
@@ -0,0 +1,268 @@
+// test/agents-view-pure.test.js — the decision helpers of the agents view. See .ai/contexts/bg-agents.md.
+'use strict';
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { renderSessionIcon } = require('../public/session-state');
+global.renderSessionIcon = renderSessionIcon;
+const { sortAgentEntries, agentRowIcon, agentVerbAvailability, formatTokens, formatAgentAge, agentsEntryKey, groupAgentEntries, normalizeAgentsGroupBy, AGENT_STATE_META, agentStateMeta,
+  agentsCollapseKey, parseCollapsedGroups, serializeCollapsedGroups, AGENTS_COLLAPSE_MAX } = require('../public/agents-view');
+
+const bg = (over) => ({ id: 'aaaaaaaa', sessionId: 's', kind: 'background', state: 'working', status: 'idle', startedAt: 100, ...over });
+
+test('sort: working and external-interactive first, then newest first, unknown start last', () => {
+  const sorted = sortAgentEntries([
+    bg({ id: 'd1', state: 'done', startedAt: 500 }),
+    bg({ id: 'w1', startedAt: 100 }),
+    { kind: 'interactive', sessionId: 'i1', state: null, status: 'busy', startedAt: 300 },
+    bg({ id: 'w2', startedAt: null }),
+    bg({ id: 'w3', startedAt: 200 }),
+  ]);
+  assert.deepEqual(sorted.map(e => e.id || e.sessionId), ['i1', 'w3', 'w1', 'w2', 'd1']);
+});
+
+test('sort: a blocked job is live and ranks with the working ones', () => {
+  const sorted = sortAgentEntries([
+    bg({ id: 's1', state: 'stopped', startedAt: 900 }),
+    bg({ id: 'b1', state: 'blocked', startedAt: 150 }),
+    bg({ id: 'w1', startedAt: 100 }),
+    bg({ id: 'd1', state: 'done', startedAt: 800 }),
+  ]);
+  assert.deepEqual(sorted.map(e => e.id), ['b1', 'w1', 's1', 'd1']);
+});
+
+test('row icon: busy spinner, waiting, idle for live rows; stale for finished ones', () => {
+  assert.equal(agentRowIcon(bg({ status: 'busy' })).slotClass, 'session-icon--busy');
+  assert.equal(agentRowIcon(bg({ status: 'waiting' })).slotClass, 'session-icon--waiting');
+  assert.equal(agentRowIcon(bg({ status: 'idle' })).slotClass, 'session-icon--idle');
+  assert.equal(agentRowIcon(bg({ state: 'done', status: 'busy' })).slotClass, 'session-icon--stale');
+  assert.equal(agentRowIcon(bg({ state: 'stopped', status: 'idle' })).slotClass, 'session-icon--stale');
+  assert.equal(agentRowIcon({ kind: 'interactive', status: 'busy' }).slotClass, 'session-icon--busy');
+});
+
+test('row icon: a blocked job shows the waiting dot whatever its status', () => {
+  assert.equal(agentRowIcon(bg({ state: 'blocked', status: 'idle' })).slotClass, 'session-icon--waiting');
+  assert.equal(agentRowIcon(bg({ state: 'blocked', status: null })).slotClass, 'session-icon--waiting');
+  assert.equal(agentRowIcon(bg({ state: 'blocked', status: 'busy' })).slotClass, 'session-icon--waiting');
+});
+
+test('verb availability follows the state, the kind and the daemon', () => {
+  assert.deepEqual(agentVerbAvailability(bg(), true), { transcript: true, attach: true, stop: true, respawn: false, rm: false });
+  assert.deepEqual(agentVerbAvailability(bg({ state: 'done' }), true), { transcript: true, attach: false, stop: false, respawn: true, rm: true });
+  assert.deepEqual(agentVerbAvailability(bg({ state: 'stopped' }), true), { transcript: true, attach: false, stop: false, respawn: true, rm: true });
+  assert.deepEqual(agentVerbAvailability(bg(), false), { transcript: true, attach: false, stop: false, respawn: false, rm: false });
+  assert.deepEqual(agentVerbAvailability({ kind: 'interactive', sessionId: 'i' }, true), { transcript: true, attach: false, stop: false, respawn: false, rm: false });
+  assert.equal(agentVerbAvailability(bg({ sessionId: null, state: 'done' }), true).transcript, false);
+});
+
+test('verb availability: a blocked job is live like a working one', () => {
+  assert.deepEqual(agentVerbAvailability(bg({ state: 'blocked' }), true), { transcript: true, attach: true, stop: true, respawn: false, rm: false });
+  assert.deepEqual(agentVerbAvailability(bg({ state: 'blocked' }), false), { transcript: true, attach: false, stop: false, respawn: false, rm: false });
+});
+
+test('a failed job is finished: sorts after the live rows, stale icon, Delete and Respawn allowed', () => {
+  const sorted = sortAgentEntries([bg({ id: 'f1', state: 'failed', startedAt: 900 }), bg({ id: 'w1', startedAt: 100 })]);
+  assert.deepEqual(sorted.map(e => e.id), ['w1', 'f1']);
+  assert.equal(agentRowIcon(bg({ state: 'failed', status: 'busy' })).slotClass, 'session-icon--stale');
+  assert.deepEqual(agentVerbAvailability(bg({ state: 'failed' }), true), { transcript: true, attach: false, stop: false, respawn: true, rm: true });
+});
+
+const ext = (over) => ({ id: null, sessionId: 'i', kind: 'interactive', state: null, status: 'busy', startedAt: 100, ...over });
+const ids = (groups) => groups.map(g => [g.label, g.entries.map(e => e.id || e.sessionId)]);
+
+test('group mode: none, state and project are kept; anything else (unset included) is state', () => {
+  assert.equal(normalizeAgentsGroupBy('state'), 'state');
+  assert.equal(normalizeAgentsGroupBy('project'), 'project');
+  assert.equal(normalizeAgentsGroupBy('none'), 'none');
+  assert.equal(normalizeAgentsGroupBy('bogus'), 'state');
+  assert.equal(normalizeAgentsGroupBy(null), 'state');
+  assert.equal(normalizeAgentsGroupBy(undefined), 'state');
+});
+
+test('state meta: one emoji and label per state group, in the group order', () => {
+  assert.deepEqual(Object.entries(AGENT_STATE_META).map(([k, m]) => [k, m.emoji, m.label]), [
+    ['working', '⚙️', 'Working'], ['blocked', '✋', 'Blocked'], ['done', '✅', 'Done'], ['stopped', '⏹️', 'Stopped'],
+    ['failed', '❌', 'Failed'], ['external', '🖥️', 'External'], ['unknown', '❓', 'Unknown'],
+  ]);
+  const every = Object.keys(AGENT_STATE_META).map((k) => (k === 'external' ? ext({ sessionId: k }) : bg({ id: k, state: k === 'unknown' ? null : k })));
+  for (const g of groupAgentEntries(every, 'state')) {
+    assert.ok(AGENT_STATE_META[g.key], `meta for ${g.key}`);
+    assert.equal(g.label, AGENT_STATE_META[g.key].label);
+  }
+  assert.equal(groupAgentEntries(every, 'state').length, 7);
+});
+
+test('state meta lookup: by state, null or unlisted is unknown, interactive is external', () => {
+  assert.equal(agentStateMeta(bg()).emoji, '⚙️');
+  assert.equal(agentStateMeta(bg({ state: 'failed' })).emoji, '❌');
+  assert.equal(agentStateMeta(bg({ state: null })).emoji, '❓');
+  assert.equal(agentStateMeta(bg({ state: 'weird' })).label, 'Unknown');
+  assert.equal(agentStateMeta(ext({ state: 'working' })).emoji, '🖥️');
+  assert.equal(agentStateMeta(ext()).key, 'external');
+});
+
+test('group none: one unlabelled group holding every entry in order', () => {
+  const entries = [bg({ id: 'w1' }), bg({ id: 'd1', state: 'done' })];
+  const groups = groupAgentEntries(entries, 'none');
+  assert.equal(groups.length, 1);
+  assert.equal(groups[0].label, '');
+  assert.deepEqual(groups[0].entries.map(e => e.id), ['w1', 'd1']);
+  assert.deepEqual(groupAgentEntries([], 'none'), []);
+  assert.deepEqual(groupAgentEntries([], 'state'), []);
+  assert.deepEqual(groupAgentEntries([], 'project'), []);
+});
+
+test('group by state: fixed order, external and unknown last, empty groups dropped, entry order kept', () => {
+  const groups = groupAgentEntries([
+    ext({ sessionId: 'i1' }),
+    bg({ id: 'f1', state: 'failed' }),
+    bg({ id: 'w1' }),
+    bg({ id: 'u1', state: null }),
+    bg({ id: 'd1', state: 'done' }),
+    bg({ id: 'w2' }),
+    bg({ id: 'b1', state: 'blocked' }),
+    bg({ id: 's1', state: 'stopped' }),
+  ], 'state');
+  assert.deepEqual(ids(groups), [
+    ['Working', ['w1', 'w2']], ['Blocked', ['b1']], ['Done', ['d1']], ['Stopped', ['s1']],
+    ['Failed', ['f1']], ['External', ['i1']], ['Unknown', ['u1']],
+  ]);
+  assert.deepEqual(groups.map(g => g.key), ['working', 'blocked', 'done', 'stopped', 'failed', 'external', 'unknown']);
+  assert.deepEqual(ids(groupAgentEntries([bg({ id: 'd1', state: 'done' })], 'state')), [['Done', ['d1']]]);
+});
+
+test('group by project: last path segment, full path as title, live groups first then alphabetical, no project last', () => {
+  const groups = groupAgentEntries([
+    bg({ id: 'd1', state: 'done', cwd: '/w/alpha' }),
+    bg({ id: 'w1', cwd: '/w/zeta' }),
+    bg({ id: 'd2', state: 'done', cwd: '/w/Beta/' }),
+    bg({ id: 'n1', state: 'done', cwd: null }),
+    bg({ id: 'd3', state: 'done', cwd: '/w/alpha' }),
+    ext({ sessionId: 'i1', cwd: '/w/mid' }),
+  ], 'project');
+  assert.deepEqual(ids(groups), [
+    ['mid', ['i1']], ['zeta', ['w1']], ['alpha', ['d1', 'd3']], ['Beta', ['d2']], ['No project', ['n1']],
+  ]);
+  assert.equal(groups[2].title, '/w/alpha');
+  assert.equal(groups[2].key, '/w/alpha');
+  assert.equal(groups[4].title, '');
+});
+
+test('group by project: two cwds with the same last segment stay separate, labelled with their parent', () => {
+  const groups = groupAgentEntries([
+    bg({ id: 'a', state: 'done', cwd: '/home/x/app' }),
+    bg({ id: 'b', state: 'done', cwd: '/srv/y/app' }),
+    bg({ id: 'c', state: 'done', cwd: 'C:\\code\\z\\app' }),
+    bg({ id: 'd', state: 'done', cwd: '/other' }),
+  ], 'project');
+  assert.deepEqual(ids(groups), [['app (x)', ['a']], ['app (y)', ['b']], ['app (z)', ['c']], ['other', ['d']]]);
+});
+
+test('group by project: same last segment and same parent fall back to the full path', () => {
+  const groups = groupAgentEntries([
+    bg({ id: 'a', state: 'done', cwd: '/a/p/app' }),
+    bg({ id: 'b', state: 'done', cwd: '/b/p/app' }),
+  ], 'project');
+  assert.deepEqual(ids(groups), [['/a/p/app', ['a']], ['/b/p/app', ['b']]]);
+});
+
+test('group by project: keyed by projectRoot, so the worktrees of one git project share a group; unrelated repos stay apart', () => {
+  const groups = groupAgentEntries([
+    bg({ id: 'a', state: 'done', cwd: '/w/app', projectRoot: '/w/app', worktreeRoot: '/w/app' }),
+    bg({ id: 'b', state: 'done', cwd: '/w/app/.claude/worktrees/x', projectRoot: '/w/app', worktreeRoot: '/w/app/.claude/worktrees/x' }),
+    bg({ id: 'c', state: 'done', cwd: '/elsewhere/wt-y/src', projectRoot: '/w/app', worktreeRoot: '/elsewhere/wt-y' }),
+    bg({ id: 'd', state: 'done', cwd: '/w/other', projectRoot: '/w/other', worktreeRoot: '/w/other' }),
+    bg({ id: 'e', state: 'done', cwd: '/w/legacy' }),
+    bg({ id: 'n', state: 'done', cwd: null, projectRoot: null }),
+  ], 'project');
+  assert.deepEqual(ids(groups), [['app', ['a', 'b', 'c']], ['legacy', ['e']], ['other', ['d']], ['No project', ['n']]]);
+  assert.equal(groups[0].key, '/w/app');
+  assert.equal(groups[0].title, '/w/app');
+  assert.equal(groups[0].children, undefined, 'no sub-groups without the option');
+});
+
+const wt = (id, worktreeRoot, over) => bg({ id, state: 'done', cwd: worktreeRoot, projectRoot: '/w/app', worktreeRoot, ...over });
+const sub = (groups) => groups.map(g => [g.label, g.entries.length, g.children ? g.children.map(c => [c.label, c.entries.map(e => e.id)]) : null]);
+
+test('worktree sub-groups: one per worktree, main first, live first, then alphabetical; the project keeps its total', () => {
+  const groups = groupAgentEntries([
+    wt('z1', '/w/app/.claude/worktrees/zeta'),
+    wt('m1', '/w/app', { cwd: '/w/app/src' }),
+    wt('a1', '/w/app/.claude/worktrees/alpha', { cwd: '/w/app/.claude/worktrees/alpha/deep/er' }),
+    wt('l1', '/w/app/.claude/worktrees/live', { state: 'working' }),
+    wt('m2', '/w/app'),
+    wt('a2', '/w/app/.claude/worktrees/alpha'),
+  ], 'project', { worktrees: true });
+  assert.deepEqual(sub(groups), [['app', 6, [['live', ['l1']], ['main', ['m1', 'm2']], ['alpha', ['a1', 'a2']], ['zeta', ['z1']]]]]);
+  const kids = groups[0].children;
+  assert.equal(kids[1].key, '/w/app');
+  assert.equal(kids[1].title, '/w/app');
+  assert.equal(kids[2].title, '/w/app/.claude/worktrees/alpha');
+});
+
+test('worktree sub-groups: a project in a single worktree stays flat, even a linked one', () => {
+  const groups = groupAgentEntries([
+    wt('a', '/w/app/.claude/worktrees/x'),
+    wt('b', '/w/app/.claude/worktrees/x', { cwd: '/w/app/.claude/worktrees/x/sub' }),
+    bg({ id: 'o', state: 'done', cwd: '/w/other', projectRoot: '/w/other', worktreeRoot: '/w/other' }),
+  ], 'project', { worktrees: true });
+  assert.deepEqual(sub(groups), [['app', 2, null], ['other', 1, null]]);
+});
+
+test('worktree sub-groups: equal directory names in one project are told apart by their parent, then the full path', () => {
+  const groups = groupAgentEntries([
+    wt('a', '/x/one/feat'),
+    wt('b', '/y/two/feat'),
+    wt('c', '/p/q/same'),
+    wt('d', '/r/q/same'),
+  ], 'project', { worktrees: true });
+  assert.deepEqual(sub(groups)[0][2], [['/p/q/same', ['c']], ['/r/q/same', ['d']], ['feat (one)', ['a']], ['feat (two)', ['b']]]);
+});
+
+test('worktree option is ignored outside project mode', () => {
+  const entries = [wt('a', '/w/app'), wt('b', '/w/app/.claude/worktrees/x')];
+  assert.ok(groupAgentEntries(entries, 'state', { worktrees: true }).every(g => !g.children));
+  assert.ok(groupAgentEntries(entries, 'none', { worktrees: true }).every(g => !g.children));
+});
+
+test('collapse keys are scoped by mode and level', () => {
+  assert.equal(agentsCollapseKey('state', { key: 'working' }), 'state:working');
+  assert.equal(agentsCollapseKey('project', { key: '/w/app' }), 'project:/w/app');
+  assert.equal(agentsCollapseKey('project', { key: '' }), 'project:');
+  assert.equal(agentsCollapseKey('worktree', { key: '/w/app/.claude/worktrees/x' }, '/w/app'), 'worktree:/w/app|/w/app/.claude/worktrees/x');
+  assert.notEqual(agentsCollapseKey('state', { key: 'x' }), agentsCollapseKey('project', { key: 'x' }));
+});
+
+test('stored collapsed groups: a JSON array of strings, anything else is empty, capped to the newest', () => {
+  assert.deepEqual(parseCollapsedGroups('["state:done","project:/a"]'), ['state:done', 'project:/a']);
+  assert.deepEqual(parseCollapsedGroups(null), []);
+  assert.deepEqual(parseCollapsedGroups(''), []);
+  assert.deepEqual(parseCollapsedGroups('{not json'), []);
+  assert.deepEqual(parseCollapsedGroups('{"a":1}'), []);
+  assert.deepEqual(parseCollapsedGroups('"state:done"'), []);
+  assert.deepEqual(parseCollapsedGroups('["a", 3, null, "a", "b"]'), ['a', 'b']);
+  const many = Array.from({ length: AGENTS_COLLAPSE_MAX + 5 }, (_, i) => 'k' + i);
+  const parsed = parseCollapsedGroups(JSON.stringify(many));
+  assert.equal(parsed.length, AGENTS_COLLAPSE_MAX);
+  assert.equal(parsed[0], 'k5');
+  assert.equal(parsed[parsed.length - 1], 'k' + (AGENTS_COLLAPSE_MAX + 4));
+  const out = JSON.parse(serializeCollapsedGroups(many));
+  assert.equal(out.length, AGENTS_COLLAPSE_MAX);
+  assert.equal(out[0], 'k5');
+  assert.deepEqual(JSON.parse(serializeCollapsedGroups(new Set(['x', 'y']))), ['x', 'y']);
+  assert.ok(AGENTS_COLLAPSE_MAX >= 100 && AGENTS_COLLAPSE_MAX <= 500);
+});
+
+test('formatting helpers', () => {
+  assert.equal(formatTokens(null), '');
+  assert.equal(formatTokens(274), '274');
+  assert.equal(formatTokens(172999), '173k');
+  assert.equal(formatTokens(2500000), '2.5M');
+  const now = 1_000_000_000;
+  assert.equal(formatAgentAge(null, now), '');
+  assert.equal(formatAgentAge(now - 30_000, now), '30s');
+  assert.equal(formatAgentAge(now - 12 * 60_000, now), '12 min');
+  assert.equal(formatAgentAge(now - 3 * 3_600_000, now), '3 h');
+  assert.equal(formatAgentAge(now - (2 * 24 + 6) * 3_600_000, now), '2d 6h');
+  assert.equal(agentsEntryKey(bg()), 'bg:aaaaaaaa');
+  assert.equal(agentsEntryKey({ kind: 'interactive', sessionId: 'x' }), 'int:x');
+});
diff --git a/test/bg-agents-ipc.test.js b/test/bg-agents-ipc.test.js
new file mode 100644
index 00000000..82a2be50
--- /dev/null
+++ b/test/bg-agents-ipc.test.js
@@ -0,0 +1,67 @@
+// test/bg-agents-ipc.test.js — the three handlers and the push. See .ai/contexts/bg-agents.md.
+'use strict';
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { init } = require('../bg-agents-ipc');
+
+function fakeIpc() {
+  const handlers = new Map();
+  return { handlers, ipcMain: { handle: (name, fn) => handlers.set(name, fn) } };
+}
+
+function fakeBgAgents() {
+  const calls = [];
+  let listener = null;
+  return {
+    calls,
+    start: () => { calls.push('start'); return true; },
+    reconcile: async () => { calls.push('reconcile'); return { roster: [], daemonReachable: true }; },
+    runVerb: async (verb, id) => { calls.push(['verb', verb, id]); return { ok: true }; },
+    dispatch: async (fields) => { calls.push(['dispatch', fields]); return { ok: true, id: 'aaaaaaaa' }; },
+    onChange: (l) => { listener = l; return () => { listener = null; }; },
+    fire: (snap) => listener && listener(snap),
+  };
+}
+
+test('get-bg-agents arms the watchers then reconciles; the verbs pass straight through', async () => {
+  const { handlers, ipcMain } = fakeIpc();
+  const bg = fakeBgAgents();
+  init({ ipcMain, bgAgents: bg, getMainWindow: () => null, log: { warn() {} } });
+  assert.deepEqual(await handlers.get('get-bg-agents')({}), { roster: [], daemonReachable: true });
+  assert.deepEqual(bg.calls, ['start', 'reconcile']);
+  assert.deepEqual(await handlers.get('bg-agent-verb')({}, 'stop', 'aaaaaaaa'), { ok: true });
+  assert.deepEqual(await handlers.get('dispatch-bg-agent')({}, { prompt: 'p', cwd: '/x' }), { ok: true, id: 'aaaaaaaa' });
+  assert.deepEqual(bg.calls.slice(2), [['verb', 'stop', 'aaaaaaaa'], ['dispatch', { prompt: 'p', cwd: '/x' }]]);
+});
+
+test('a roster change is pushed to the window on bg-agents-changed, and skipped when the window is gone', () => {
+  const { ipcMain } = fakeIpc();
+  const bg = fakeBgAgents();
+  const sent = [];
+  let window = { isDestroyed: () => false, webContents: { send: (ch, payload) => sent.push([ch, payload]) } };
+  init({ ipcMain, bgAgents: bg, getMainWindow: () => window, log: { warn() {} } });
+  bg.fire({ roster: [{ id: 'aaaaaaaa' }], daemonReachable: true });
+  assert.deepEqual(sent, [['bg-agents-changed', { roster: [{ id: 'aaaaaaaa' }], daemonReachable: true }]]);
+  window = null;
+  bg.fire({ roster: [], daemonReachable: false });
+  assert.equal(sent.length, 1);
+});
+
+test('get-bg-agents restores the push after stop() cleared it, without ever doubling it', async () => {
+  const { handlers, ipcMain } = fakeIpc();
+  const listeners = new Set();
+  const bg = {
+    start: () => true,
+    reconcile: async () => ({ roster: [], daemonReachable: true }),
+    onChange: (l) => { listeners.add(l); return () => listeners.delete(l); },
+    stop: () => listeners.clear(),
+  };
+  const sent = [];
+  const window = { isDestroyed: () => false, webContents: { send: (ch, payload) => sent.push([ch, payload]) } };
+  init({ ipcMain, bgAgents: bg, getMainWindow: () => window, log: { warn() {} } });
+  await handlers.get('get-bg-agents')({});
+  bg.stop();
+  await handlers.get('get-bg-agents')({});
+  for (const l of listeners) l({ roster: [], daemonReachable: true });
+  assert.deepEqual(sent, [['bg-agents-changed', { roster: [], daemonReachable: true }]]);
+});
diff --git a/test/bg-agents-roster.test.js b/test/bg-agents-roster.test.js
new file mode 100644
index 00000000..1507f9f0
--- /dev/null
+++ b/test/bg-agents-roster.test.js
@@ -0,0 +1,174 @@
+// test/bg-agents-roster.test.js — pure parsing and merging for the agents view.
+// See .ai/contexts/bg-agents.md.
+'use strict';
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const {
+  parseJobState, parseCliList, mergeRoster, dispatchArgs, parseDispatchOutput, JOB_ID_RE, stripShellNoise,
+} = require('../bg-agents-roster');
+
+const STATE = JSON.stringify({
+  state: 'done',
+  detail: 'backlog reviewed; awaiting !196 merge',
+  tempo: 'idle',
+  tokens: 172999,
+  fan: [{ id: 'a4a8', kind: 'agent', label: 'Spawn developer', startedAt: 1790590786510, doneAt: 1790590813354 }, 'junk'],
+  children: [{ id: '195', href: 'https://gitlab.com/x/-/merge_requests/195', kind: 'merge_request' }],
+  output: { result: 'no new action needed' },
+  template: 'fleet:em',
+  respawnFlags: ['--plugin-dir', '/x', '--agent', 'fleet:em', '--permission-mode', 'auto', '--name', 'em-platform', '--model', 'claude-sonnet-5'],
+  linkScanPath: '/home/u/.claude/projects/-home-u-p/bc3fd129-60bb-4bd2-8f38-63fecd1256e5.jsonl',
+});
+
+test('parseJobState keeps the fields the view shows and derives agent/model/name/sessionId', () => {
+  const job = parseJobState(STATE);
+  assert.equal(job.state, 'done');
+  assert.equal(job.detail, 'backlog reviewed; awaiting !196 merge');
+  assert.equal(job.tokens, 172999);
+  assert.deepEqual(job.fan, [{ id: 'a4a8', kind: 'agent', label: 'Spawn developer', startedAt: 1790590786510, doneAt: 1790590813354 }]);
+  assert.deepEqual(job.children, [{ id: '195', href: 'https://gitlab.com/x/-/merge_requests/195', kind: 'merge_request' }]);
+  assert.equal(job.result, 'no new action needed');
+  assert.equal(job.agent, 'fleet:em');
+  assert.equal(job.model, 'claude-sonnet-5');
+  assert.equal(job.name, 'em-platform');
+  assert.equal(job.sessionId, 'bc3fd129-60bb-4bd2-8f38-63fecd1256e5');
+});
+
+test('parseJobState: unknown state, missing output and garbage are tolerated', () => {
+  assert.equal(parseJobState(''), null);
+  assert.equal(parseJobState('[]'), null);
+  const job = parseJobState('{"state":"weird","fan":null}');
+  assert.equal(job.state, null);
+  assert.deepEqual(job.fan, []);
+  assert.equal(job.result, null);
+  assert.equal(job.sessionId, null);
+});
+
+test('parseCliList keeps background and interactive entries and drops the rest', () => {
+  const list = parseCliList(JSON.stringify([
+    { id: 'bc3fd129', pid: 346590, cwd: '/w', kind: 'background', startedAt: 1, sessionId: 's-bg', name: 'em', status: 'idle', state: 'working' },
+    { pid: 5, cwd: '/w', kind: 'interactive', startedAt: 2, sessionId: 's-int', name: 'n', status: 'busy' },
+    { kind: 'background', sessionId: '' },
+    'junk',
+  ]));
+  assert.equal(list.length, 2);
+  assert.deepEqual(list[0], { id: 'bc3fd129', sessionId: 's-bg', name: 'em', cwd: '/w', kind: 'background', state: 'working', status: 'idle', pid: 346590, startedAt: 1 });
+  assert.equal(list[1].kind, 'interactive');
+  assert.equal(list[1].id, null);
+  assert.equal(parseCliList('not json'), null);
+  assert.equal(parseCliList('{}'), null);
+});
+
+test('parseCliList tolerates login-shell noise printed around the JSON', () => {
+  const json = JSON.stringify([{ id: 'bc3fd129', kind: 'background', sessionId: 's-bg', state: 'working' }], null, 2);
+  const before = 'Now using node v22.1.0 (npm v10)\n[nvm] default alias set\n"The fortune cookie says: [sic]"\n';
+  const after = '\nlogout [done]\n';
+  for (const text of [before + json, json + after, before + json + after]) {
+    const list = parseCliList(text);
+    assert.ok(Array.isArray(list), text);
+    assert.equal(list.length, 1);
+    assert.equal(list[0].sessionId, 's-bg');
+  }
+  assert.equal(parseCliList('Now using node v22\n[not json]\ngarbage ]'), null);
+  assert.equal(parseCliList('fortune: be happy\n{"a":1}\n'), null);
+  assert.equal(parseCliList(''), null);
+});
+
+test('stripShellNoise drops the leading login-shell job-control lines and keeps the CLI stderr verbatim', () => {
+  const noise = 'bash: cannot set terminal process group (-1): Inappropriate ioctl for device\nbash: no job control in this shell\n';
+  assert.equal(stripShellNoise(noise + 'Error: session aaaaaaaa is not running\n  at x'), 'Error: session aaaaaaaa is not running\n  at x');
+  assert.equal(stripShellNoise('Error: bash: no job control in this shell is quoted here'), 'Error: bash: no job control in this shell is quoted here');
+  assert.equal(stripShellNoise(noise), '');
+  assert.equal(stripShellNoise(undefined), '');
+});
+
+function fixture() {
+  const cli = [
+    { id: 'aaaaaaaa', sessionId: 's-a', name: 'a', cwd: '/a', kind: 'background', state: 'working', status: 'idle', pid: 10, startedAt: 100 },
+    { id: 'bbbbbbbb', sessionId: 's-b', name: 'b', cwd: '/b', kind: 'background', state: 'done', status: null, pid: null, startedAt: 50 },
+    { id: null, sessionId: 's-own', name: 'own', cwd: '/o', kind: 'interactive', state: null, status: 'busy', pid: 20, startedAt: 70 },
+  ];
+  const jobs = new Map([
+    ['aaaaaaaa', parseJobState(JSON.stringify({ state: 'done', detail: 'stale detail', tokens: 5, respawnFlags: ['--agent', 'fleet:em'] }))],
+    ['cccccccc', parseJobState(JSON.stringify({ state: 'stopped', detail: 'orphan' }))],
+  ]);
+  const descriptors = [
+    { pid: 10, sessionId: 's-a', kind: 'bg', jobId: 'aaaaaaaa', agent: 'fleet:em', name: 'a', cwd: '/a', status: 'busy', startedAt: 100 },
+    { pid: 20, sessionId: 's-own', kind: 'interactive', jobId: null, agent: null, name: 'own', cwd: '/o', status: 'busy', startedAt: 70 },
+    { pid: 30, sessionId: 's-ext', kind: 'interactive', jobId: null, agent: null, name: 'ext', cwd: '/e', status: 'waiting', startedAt: 80 },
+    { pid: 40, sessionId: 's-nojob', kind: 'bg', jobId: 'dddddddd', agent: null, name: 'x', cwd: '/x', status: 'idle', startedAt: 90 },
+  ];
+  return { cli, jobs, descriptors, isOwnPid: (pid) => pid === 20, isAttachedHere: (id) => id === 'aaaaaaaa' };
+}
+
+test('mergeRoster: the CLI list decides which jobs exist; the job file state, being live, wins over the CLI snapshot', () => {
+  const roster = mergeRoster(fixture());
+  const ids = roster.map(e => e.kind === 'background' ? e.id : e.sessionId);
+  assert.deepEqual(ids, ['aaaaaaaa', 'bbbbbbbb', 's-ext']);
+  const a = roster[0];
+  assert.equal(a.state, 'done', 'the live state.json wins over the cached CLI state');
+  assert.equal(a.status, 'busy', 'the descriptor status wins over the CLI snapshot');
+  assert.equal(a.detail, 'stale detail');
+  assert.equal(a.tokens, 5);
+  assert.equal(a.agent, 'fleet:em');
+  assert.equal(a.attachedHere, true);
+  assert.equal(roster[1].attachedHere, false);
+  assert.equal(roster[1].detail, null, 'a job without a file still lists');
+  const ext = roster[2];
+  assert.equal(ext.kind, 'interactive');
+  assert.equal(ext.id, null);
+  assert.equal(ext.status, 'waiting');
+});
+
+test('mergeRoster without the CLI lists the jobs on disk instead', () => {
+  const f = fixture();
+  const roster = mergeRoster({ ...f, cli: null });
+  assert.deepEqual(roster.filter(e => e.kind === 'background').map(e => e.id).sort(), ['aaaaaaaa', 'cccccccc']);
+  const a = roster.find(e => e.id === 'aaaaaaaa');
+  assert.equal(a.state, 'done', 'file state stands when the CLI is unreachable');
+  assert.equal(a.sessionId, 's-a', 'the descriptor supplies the session id');
+  assert.equal(a.pid, 10);
+});
+
+test('dispatchArgs builds the argv in a fixed order and omits empty options', () => {
+  const r = dispatchArgs({ prompt: '  do the thing  ', name: 'n1', agent: 'fleet:em', permissionMode: 'auto', addDirs: '/a, /b', cwd: '/proj' });
+  assert.deepEqual(r, { ok: true, cwd: '/proj', args: ['--bg', '--name', 'n1', '--agent', 'fleet:em', '--permission-mode', 'auto', '--add-dir', '/a', '--add-dir', '/b', '--', 'do the thing'] });
+  const bare = dispatchArgs({ prompt: 'p', cwd: '/proj', name: '', agent: '  ', dangerouslySkipPermissions: true, permissionMode: 'auto' });
+  assert.deepEqual(bare.args, ['--bg', '--dangerously-skip-permissions', '--', 'p']);
+});
+
+test('dispatchArgs refuses an empty prompt, a missing cwd, and a prompt that looks like a flag', () => {
+  assert.equal(dispatchArgs({ prompt: '', cwd: '/p' }).ok, false);
+  assert.equal(dispatchArgs({ prompt: 'p' }).ok, false);
+  const flag = dispatchArgs({ prompt: '--help', cwd: '/p' });
+  assert.equal(flag.ok, false);
+  assert.match(flag.error, /cannot start with/);
+});
+
+test('parseDispatchOutput finds an eight-hex id anywhere in the output, or returns null', () => {
+  assert.equal(parseDispatchOutput('Started background session de3dfd18\nattach with claude attach de3dfd18\n'), 'de3dfd18');
+  assert.equal(parseDispatchOutput('de3dfd18'), 'de3dfd18');
+  assert.equal(parseDispatchOutput('deadbeefcafe is not an id, nor is 12345'), null);
+  assert.equal(parseDispatchOutput(''), null);
+  assert.ok(JOB_ID_RE.test('de3dfd18'));
+  assert.ok(!JOB_ID_RE.test('DE3DFD18'));
+});
+
+test('parseDispatchOutput reads the id from the output measured on CLI 2.1.285, ANSI colour included', () => {
+  const measured = 'backgrounded · \x1b[36m3f9a0c1e\x1b[39m · plan-check\n'
+    + '\x1b[2m  claude agents\n  claude attach 3f9a0c1e\n  claude logs 3f9a0c1e\n  claude stop 3f9a0c1e\x1b[22m\n';
+  assert.equal(parseDispatchOutput(measured), '3f9a0c1e');
+  assert.equal(parseDispatchOutput('backgrounded · plan-check\n'), null);
+});
+
+test('parseJobState and parseCliList keep the blocked state a job reports while it waits', () => {
+  assert.equal(parseJobState('{"state":"blocked","detail":"awaiting developer MR"}').state, 'blocked');
+  const [s] = parseCliList(JSON.stringify([{ id: 'aaaaaaaa', sessionId: 's1', kind: 'background', state: 'blocked' }]));
+  assert.equal(s.state, 'blocked');
+});
+
+test('parseJobState and parseCliList keep the failed state the daemon reports for a job that ended in error', () => {
+  assert.equal(parseJobState('{"state":"failed","detail":"crashed"}').state, 'failed');
+  const [s] = parseCliList(JSON.stringify([{ id: 'aaaaaaaa', sessionId: 's1', kind: 'background', state: 'failed' }]));
+  assert.equal(s.state, 'failed');
+});
diff --git a/test/bg-agents.test.js b/test/bg-agents.test.js
new file mode 100644
index 00000000..81527cad
--- /dev/null
+++ b/test/bg-agents.test.js
@@ -0,0 +1,386 @@
+// see .ai/contexts/bg-agents.md
+'use strict';
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const bgAgents = require('../bg-agents');
+
+function mkTmp() {
+  return fs.realpathSync.native(fs.mkdtempSync(path.join(os.tmpdir(), 'sw-bg-agents-')));
+}
+function rmTmp(dir) {
+  bgAgents.stop();
+  fs.rmSync(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
+}
+const silentLog = { info() {}, warn() {}, error() {}, debug() {} };
+const delay = (ms) => new Promise(r => setTimeout(r, ms));
+function waitFor(fn, maxMs = 4000) {
+  return new Promise((resolve, reject) => {
+    const start = Date.now();
+    (function poll() {
+      if (fn()) return resolve();
+      if (Date.now() - start > maxMs) return reject(new Error('timed out'));
+      setTimeout(poll, 20);
+    })();
+  });
+}
+
+function writeJob(dir, id, state) {
+  fs.mkdirSync(path.join(dir, id), { recursive: true });
+  fs.writeFileSync(path.join(dir, id, 'state.json'), JSON.stringify(state), 'utf8');
+}
+
+const CLI_LIST = [
+  { id: 'aaaaaaaa', sessionId: 's-a', name: 'a', cwd: '/a', kind: 'background', startedAt: 1, state: 'working', status: 'idle', pid: 10 },
+  { id: 'bbbbbbbb', sessionId: 's-b', name: 'b', cwd: '/b', kind: 'background', startedAt: 2, state: 'done' },
+];
+
+function fakeCli(overrides = {}) {
+  const calls = [];
+  const runClaude = async (argv, opts) => {
+    calls.push({ argv, opts });
+    if (overrides.fail) return { code: 1, stdout: '', stderr: 'boom' };
+    if (argv[0] === 'agents') return { code: 0, stdout: JSON.stringify(overrides.list || CLI_LIST), stderr: '' };
+    if (argv[0] === '--bg') return { code: 0, stdout: 'Started background session cccccccc\n', stderr: '' };
+    return { code: 0, stdout: '', stderr: '' };
+  };
+  return { calls, runClaude };
+}
+
+function fakeSessionState(descriptors = []) {
+  const listeners = new Set();
+  return {
+    listeners,
+    onDescriptorsChanged: (l) => { listeners.add(l); return () => listeners.delete(l); },
+    readAllDescriptors: () => descriptors,
+    ensureWatching: () => true,
+    fire() { for (const l of listeners) l(); },
+  };
+}
+
+function boot(dir, { cli = fakeCli(), sessionState = fakeSessionState(), attached = () => false, homeDir, resolveProjectRoots = async () => null } = {}) {
+  bgAgents.init({
+    jobsDir: dir, log: silentLog, runClaude: cli.runClaude, cliSessionState: sessionState, homeDir,
+    makeIsOwnPid: () => () => false, isAttachedHere: attached, resolveProjectRoots,
+  });
+  return { cli, sessionState };
+}
+
+test.afterEach(() => bgAgents.stop());
+
+test('reconcile runs `claude agents --json --all`, merges the job files, and reports the daemon reachable', async () => {
+  const dir = mkTmp();
+  try {
+    writeJob(dir, 'aaaaaaaa', { state: 'working', detail: 'reading rules', tokens: 42 });
+    const { cli } = boot(dir);
+    assert.equal(bgAgents.start(), true);
+    const snap = await bgAgents.reconcile();
+    assert.deepEqual(cli.calls[0].argv, ['agents', '--json', '--all']);
+    assert.equal(cli.calls[0].opts.timeout, bgAgents.LIST_TIMEOUT_MS);
+    assert.equal(snap.daemonReachable, true);
+    assert.deepEqual(snap.roster.map(e => e.id), ['aaaaaaaa', 'bbbbbbbb']);
+    assert.equal(snap.roster[0].detail, 'reading rules');
+    assert.equal(snap.roster[0].tokens, 42);
+  } finally { rmTmp(dir); }
+});
+
+test('a state.json rewrite reaches listeners once, coalesced, without another CLI call', async () => {
+  const dir = mkTmp();
+  try {
+    writeJob(dir, 'aaaaaaaa', { state: 'working', detail: 'one' });
+    const { cli } = boot(dir);
+    bgAgents.start();
+    await bgAgents.reconcile();
+    const seen = [];
+    bgAgents.onChange((snap) => seen.push(snap.roster.find(e => e.id === 'aaaaaaaa').detail));
+    const callsBefore = cli.calls.length;
+    writeJob(dir, 'aaaaaaaa', { state: 'working', detail: 'two' });
+    await waitFor(() => seen.includes('two'));
+    await delay(bgAgents.FLUSH_MS * 2);
+    assert.deepEqual(seen, ['two']);
+    assert.equal(cli.calls.length, callsBefore, 'a file change never spawns the CLI');
+  } finally { rmTmp(dir); }
+});
+
+test('a job directory that appears after start is watched too', async () => {
+  const dir = mkTmp();
+  try {
+    boot(dir);
+    bgAgents.start();
+    await bgAgents.reconcile();
+    const seen = [];
+    bgAgents.onChange((snap) => seen.push((snap.roster.find(e => e.id === 'bbbbbbbb') || {}).detail));
+    writeJob(dir, 'bbbbbbbb', { state: 'done', detail: 'late' });
+    await waitFor(() => seen.includes('late'));
+  } finally { rmTmp(dir); }
+});
+
+test('an empty state.json (mid-rewrite) keeps the previous value', async () => {
+  const dir = mkTmp();
+  try {
+    writeJob(dir, 'aaaaaaaa', { state: 'working', detail: 'kept' });
+    boot(dir);
+    bgAgents.start();
+    await bgAgents.reconcile();
+    fs.writeFileSync(path.join(dir, 'aaaaaaaa', 'state.json'), '', 'utf8');
+    await delay(bgAgents.FLUSH_MS * 3);
+    assert.equal(bgAgents.getSnapshot().roster[0].detail, 'kept');
+  } finally { rmTmp(dir); }
+});
+
+test('a descriptor change rebuilds the roster from readAllDescriptors', async () => {
+  const dir = mkTmp();
+  try {
+    const descriptors = [];
+    const sessionState = fakeSessionState(descriptors);
+    boot(dir, { sessionState });
+    bgAgents.start();
+    await bgAgents.reconcile();
+    const seen = [];
+    bgAgents.onChange((snap) => seen.push(snap.roster.map(e => e.sessionId).join(',')));
+    descriptors.push({ pid: 30, sessionId: 's-ext', kind: 'interactive', jobId: null, agent: null, name: 'ext', cwd: '/e', status: 'busy', startedAt: 3 });
+    sessionState.fire();
+    await waitFor(() => seen.some(s => s.includes('s-ext')));
+  } finally { rmTmp(dir); }
+});
+
+test('when the CLI fails the roster comes from the files and the daemon is reported unreachable', async () => {
+  const dir = mkTmp();
+  try {
+    writeJob(dir, 'cccccccc', { state: 'stopped', detail: 'from disk' });
+    boot(dir, { cli: fakeCli({ fail: true }) });
+    bgAgents.start();
+    const snap = await bgAgents.reconcile();
+    assert.equal(snap.daemonReachable, false);
+    assert.deepEqual(snap.roster.map(e => e.id), ['cccccccc']);
+  } finally { rmTmp(dir); }
+});
+
+test('runVerb spawns `claude <verb> <id>` in the session cwd when it exists, then reconciles', async () => {
+  const dir = mkTmp();
+  try {
+    const list = [{ ...CLI_LIST[0], cwd: dir }];
+    const { cli } = boot(dir, { cli: fakeCli({ list }) });
+    bgAgents.start();
+    await bgAgents.reconcile();
+    const r = await bgAgents.runVerb('stop', 'aaaaaaaa');
+    assert.deepEqual(r, { ok: true });
+    const verbCall = cli.calls.find(c => c.argv[0] === 'stop');
+    assert.deepEqual(verbCall.argv, ['stop', 'aaaaaaaa']);
+    assert.equal(verbCall.opts.cwd, dir);
+    assert.equal(verbCall.opts.timeout, bgAgents.VERB_TIMEOUT_MS);
+    assert.equal(cli.calls[cli.calls.length - 1].argv[0], 'agents', 'a verb is followed by a reconcile');
+  } finally { rmTmp(dir); }
+});
+
+test('runVerb runs rm from the home directory, never from the job cwd it may delete; respawn keeps the job cwd', async () => {
+  const dir = mkTmp();
+  const home = mkTmp();
+  try {
+    const list = [{ ...CLI_LIST[1], cwd: dir }];
+    const cli = fakeCli({ list });
+    boot(dir, { cli, homeDir: home });
+    bgAgents.start();
+    await bgAgents.reconcile();
+    assert.deepEqual(await bgAgents.runVerb('rm', 'bbbbbbbb'), { ok: true });
+    assert.equal(cli.calls.find(c => c.argv[0] === 'rm').opts.cwd, home);
+    assert.deepEqual(await bgAgents.runVerb('respawn', 'bbbbbbbb'), { ok: true });
+    assert.equal(cli.calls.find(c => c.argv[0] === 'respawn').opts.cwd, dir);
+  } finally {
+    rmTmp(dir);
+    rmTmp(home);
+  }
+});
+
+test('runVerb refuses an unknown verb or a malformed id before spawning anything', async () => {
+  const dir = mkTmp();
+  try {
+    const { cli } = boot(dir);
+    bgAgents.start();
+    assert.equal((await bgAgents.runVerb('kill', 'aaaaaaaa')).ok, false);
+    assert.equal((await bgAgents.runVerb('stop', '--all')).ok, false);
+    assert.equal((await bgAgents.runVerb('rm', 'AAAAAAAA')).ok, false);
+    assert.equal(cli.calls.length, 0);
+  } finally { rmTmp(dir); }
+});
+
+test('runVerb reports the CLI stderr when it fails', async () => {
+  const dir = mkTmp();
+  try {
+    boot(dir, { cli: fakeCli({ fail: true }) });
+    bgAgents.start();
+    const r = await bgAgents.runVerb('rm', 'aaaaaaaa');
+    assert.equal(r.ok, false);
+    assert.equal(r.error, 'boom');
+  } finally { rmTmp(dir); }
+});
+
+test('runVerb strips the login-shell job-control noise from the CLI stderr it reports', async () => {
+  const dir = mkTmp();
+  try {
+    const stderr = 'bash: cannot set terminal process group (-1): Inappropriate ioctl for device\nbash: no job control in this shell\nError: no such session\n';
+    const runClaude = async (argv) => (argv[0] === 'agents'
+      ? { code: 0, stdout: JSON.stringify(CLI_LIST), stderr: '' }
+      : { code: 1, stdout: '', stderr });
+    boot(dir, { cli: { calls: [], runClaude } });
+    bgAgents.start();
+    const r = await bgAgents.runVerb('rm', 'bbbbbbbb');
+    assert.equal(r.ok, false);
+    assert.equal(r.error, 'Error: no such session');
+  } finally { rmTmp(dir); }
+});
+
+test('a reconcile tolerates login-shell noise printed before the JSON list', async () => {
+  const dir = mkTmp();
+  try {
+    const runClaude = async () => ({ code: 0, stdout: 'Now using node v22\n' + JSON.stringify(CLI_LIST), stderr: '' });
+    boot(dir, { cli: { calls: [], runClaude } });
+    bgAgents.start();
+    const snap = await bgAgents.reconcile();
+    assert.equal(snap.daemonReachable, true);
+  } finally { rmTmp(dir); }
+});
+
+test('dispatch runs `claude --bg …` in the project directory and returns the printed id', async () => {
+  const dir = mkTmp();
+  try {
+    const { cli } = boot(dir);
+    bgAgents.start();
+    const r = await bgAgents.dispatch({ prompt: 'hello', name: 'n', cwd: dir });
+    assert.deepEqual(r, { ok: true, id: 'cccccccc' });
+    const call = cli.calls.find(c => c.argv[0] === '--bg');
+    assert.deepEqual(call.argv, ['--bg', '--name', 'n', '--', 'hello']);
+    assert.equal(call.opts.cwd, dir);
+    const missing = await bgAgents.dispatch({ prompt: 'hello', cwd: path.join(dir, 'nope') });
+    assert.equal(missing.ok, false);
+    assert.match(missing.error, /no longer exists/);
+  } finally { rmTmp(dir); }
+});
+
+function trackWatchers(t) {
+  const open = new Set();
+  const real = fs.watch;
+  t.mock.method(fs, 'watch', (...args) => {
+    const w = real.apply(fs, args);
+    open.add(w);
+    const close = w.close.bind(w);
+    w.close = () => { open.delete(w); close(); };
+    return w;
+  });
+  return open;
+}
+
+test('stop closes every watcher it opened', async (t) => {
+  const dir = mkTmp();
+  try {
+    writeJob(dir, 'aaaaaaaa', { state: 'working' });
+    writeJob(dir, 'bbbbbbbb', { state: 'done' });
+    const open = trackWatchers(t);
+    boot(dir);
+    bgAgents.start();
+    assert.equal(open.size, 3);
+    bgAgents.stop();
+    assert.equal(open.size, 0);
+  } finally { rmTmp(dir); }
+});
+
+test('a reconcile still running when stop() is called arms nothing and restores nothing', async (t) => {
+  const dir = mkTmp();
+  try {
+    writeJob(dir, 'aaaaaaaa', { state: 'working' });
+    writeJob(dir, 'bbbbbbbb', { state: 'done' });
+    const open = trackWatchers(t);
+    let release;
+    const gate = new Promise(r => { release = r; });
+    const runClaude = async () => { await gate; return { code: 0, stdout: JSON.stringify(CLI_LIST), stderr: '' }; };
+    boot(dir, { cli: { runClaude, calls: [] } });
+    bgAgents.start();
+    const pending = bgAgents.reconcile();
+    bgAgents.stop();
+    assert.equal(open.size, 0);
+    release();
+    const snap = await pending;
+    assert.equal(open.size, 0, 'no watcher armed after stop');
+    assert.equal(snap.daemonReachable, false);
+    assert.equal(bgAgents.getSnapshot().daemonReachable, false);
+    assert.deepEqual(bgAgents.getSnapshot().roster, []);
+  } finally { rmTmp(dir); }
+});
+
+for (const liveState of ['working', 'blocked']) {
+  test(`runVerb refuses rm and respawn on a ${liveState} session but allows stop`, async () => {
+    const dir = mkTmp();
+    try {
+      const list = [{ ...CLI_LIST[0], state: liveState, cwd: dir }];
+      const { cli } = boot(dir, { cli: fakeCli({ list }) });
+      bgAgents.start();
+      await bgAgents.reconcile();
+      const before = cli.calls.length;
+      assert.equal((await bgAgents.runVerb('rm', 'aaaaaaaa')).ok, false);
+      assert.equal((await bgAgents.runVerb('respawn', 'aaaaaaaa')).ok, false);
+      assert.equal(cli.calls.length, before);
+      assert.equal((await bgAgents.runVerb('stop', 'aaaaaaaa')).ok, true);
+    } finally { rmTmp(dir); }
+  });
+}
+
+test('roster entries carry projectRoot and worktreeRoot: the pattern or the cwd at once, the resolved roots after a change event', async () => {
+  const dir = mkTmp();
+  try {
+    const list = [
+      ...CLI_LIST,
+      { id: 'cccccccc', sessionId: 's-c', name: 'c', cwd: '/r/.claude/worktrees/x/src', kind: 'background', startedAt: 3, state: 'done' },
+    ];
+    const resolved = [];
+    let release;
+    const gate = new Promise((r) => { release = r; });
+    const resolveProjectRoots = async (cwd) => {
+      resolved.push(cwd);
+      await gate;
+      if (cwd === '/a') return { projectRoot: '/repo', worktreeRoot: '/repo/wt-a' };
+      if (cwd === '/i/sub') return { projectRoot: '/i', worktreeRoot: '/i' };
+      return { projectRoot: cwd, worktreeRoot: cwd };
+    };
+    const sessionState = fakeSessionState([{ pid: 99, sessionId: 's-i', cwd: '/i/sub', kind: 'interactive', status: 'idle', startedAt: 4 }]);
+    boot(dir, { cli: fakeCli({ list }), resolveProjectRoots, sessionState });
+    bgAgents.start();
+    const snap = await bgAgents.reconcile();
+    const by = (s, id) => s.roster.find(e => (e.id || e.sessionId) === id);
+    assert.deepEqual([by(snap, 'aaaaaaaa').projectRoot, by(snap, 'aaaaaaaa').worktreeRoot], ['/a', '/a']);
+    assert.deepEqual([by(snap, 'cccccccc').projectRoot, by(snap, 'cccccccc').worktreeRoot], ['/r', '/r/.claude/worktrees/x']);
+    const seen = [];
+    bgAgents.onChange((s) => seen.push(s));
+    release();
+    await waitFor(() => seen.length > 0);
+    const after = seen[seen.length - 1];
+    assert.deepEqual([by(after, 'aaaaaaaa').projectRoot, by(after, 'aaaaaaaa').worktreeRoot], ['/repo', '/repo/wt-a']);
+    const ext = after.roster.find(e => e.kind === 'interactive');
+    assert.deepEqual([ext.cwd, ext.projectRoot, ext.worktreeRoot], ['/i/sub', '/i', '/i']);
+    const before = resolved.length;
+    await bgAgents.reconcile();
+    await delay(bgAgents.FLUSH_MS * 2);
+    assert.equal(resolved.length, before, 'a known cwd is not resolved again');
+    assert.equal(new Set(resolved).size, resolved.length, 'each cwd resolved once');
+  } finally { rmTmp(dir); }
+});
+
+test('a resolver that throws or answers nothing leaves the cwd as the root, and is not retried', async () => {
+  const dir = mkTmp();
+  try {
+    let calls = 0;
+    const resolveProjectRoots = async (cwd) => { calls++; if (cwd === '/a') throw new Error('boom'); return null; };
+    boot(dir, { resolveProjectRoots });
+    bgAgents.start();
+    const snap = await bgAgents.reconcile();
+    await delay(bgAgents.FLUSH_MS * 2);
+    assert.equal(snap.roster.find(e => e.id === 'aaaaaaaa').projectRoot, '/a');
+    const n = calls;
+    await bgAgents.reconcile();
+    await delay(20);
+    assert.equal(calls, n);
+    assert.equal(bgAgents.getSnapshot().roster.find(e => e.id === 'bbbbbbbb').projectRoot, '/b');
+  } finally { rmTmp(dir); }
+});
diff --git a/test/canary-bg-agents-files.test.js b/test/canary-bg-agents-files.test.js
new file mode 100644
index 00000000..07830bd5
--- /dev/null
+++ b/test/canary-bg-agents-files.test.js
@@ -0,0 +1,53 @@
+// test/canary-bg-agents-files.test.js — canary over an external dependency.
+//
+// Pins the observed shape of ~/.claude/jobs/<id>/state.json, written by the
+// Claude CLI's daemon for every `claude --bg` session (CLI 2.1.285, Linux,
+// 2026-09-30). bg-agents-roster.js reads it for the agents view. Not a
+// documented interface: this test going red means the CLI changed, not that
+// Switchboard broke. Skips wherever the directory is absent.
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { JOB_STATES } = require('../bg-agents-roster');
+
+const JOBS_DIR = path.join(os.homedir(), '.claude', 'jobs');
+
+function listStateFiles() {
+  try {
+    return fs.readdirSync(JOBS_DIR)
+      .filter(n => /^[0-9a-f]{8}$/.test(n))
+      .map(n => path.join(JOBS_DIR, n, 'state.json'))
+      .filter(p => fs.existsSync(p));
+  } catch {
+    return [];
+  }
+}
+
+test('CANARY: the Claude CLI daemon still writes jobs/<id>/state.json in the shape the agents view reads', (t) => {
+  const files = listStateFiles();
+  if (files.length === 0) {
+    t.skip(`no ${JOBS_DIR}/<id>/state.json on this machine — nothing to pin`);
+    return;
+  }
+  for (const file of files) {
+    let raw;
+    try { raw = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { continue; }
+    const seen = `(${file})`;
+    if (!JOB_STATES.has(raw.state)) {
+      t.diagnostic(`unknown job state "${raw.state}" (known: ${[...JOB_STATES].join(', ')}) ${seen}; the view shows it as Unknown`);
+    }
+    assert.ok(raw.detail === undefined || raw.detail === null || typeof raw.detail === 'string',
+      `PINNED ASSUMPTION BROKEN: "detail" used to be a string, the one-line status the view shows ${seen}`);
+    assert.ok(raw.respawnFlags === undefined || Array.isArray(raw.respawnFlags),
+      `PINNED ASSUMPTION BROKEN: "respawnFlags" used to be the original argv (--agent, --model, --name) ${seen}`);
+    assert.ok(raw.linkScanPath === undefined || /\.jsonl$/.test(String(raw.linkScanPath)),
+      `PINNED ASSUMPTION BROKEN: "linkScanPath" used to end in the session's <sessionId>.jsonl ${seen}`);
+    assert.ok(raw.fan === undefined || raw.fan === null || Array.isArray(raw.fan),
+      `PINNED ASSUMPTION BROKEN: "fan" used to be an array of {id, kind, label, startedAt, doneAt} ${seen}`);
+  }
+});
diff --git a/test/canary-cli-session-state.test.js b/test/canary-cli-session-state.test.js
index f878f961..784f811d 100644
--- a/test/canary-cli-session-state.test.js
+++ b/test/canary-cli-session-state.test.js
@@ -67,3 +67,24 @@ test('CANARY: the Claude CLI still publishes per-session state we can read', (t)
     t.skip('every state file was mid-write — nothing to pin this run');
   }
 });
+
+test('CANARY: a background worker descriptor still carries kind "bg" and its short job id', (t) => {
+  const bg = [];
+  for (const name of listStateFiles()) {
+    try {
+      const raw = JSON.parse(fs.readFileSync(path.join(SESSIONS_DIR, name), 'utf8'));
+      if (raw && raw.kind === 'bg') bg.push({ name, raw });
+    } catch {}
+  }
+  if (bg.length === 0) {
+    t.skip('no kind:"bg" descriptor on this machine — start one with `claude --bg` to pin the shape');
+    return;
+  }
+  for (const { name, raw } of bg) {
+    const seen = `(${name}, CLI version ${raw.version || 'unknown'})`;
+    assert.match(String(raw.jobId), /^[0-9a-f]{8}$/,
+      `PINNED ASSUMPTION BROKEN: a bg descriptor used to carry "jobId", the eight-hex id that joins it to ~/.claude/jobs/<id> and to \`claude attach <id>\` ${seen}`);
+    assert.ok(raw.agent === undefined || typeof raw.agent === 'string',
+      `PINNED ASSUMPTION BROKEN: "agent" used to be a string when present ${seen}`);
+  }
+});
diff --git a/test/claude-binary.test.js b/test/claude-binary.test.js
new file mode 100644
index 00000000..ee4edd61
--- /dev/null
+++ b/test/claude-binary.test.js
@@ -0,0 +1,70 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { resolveWindowsClaude, escapeForCmd } = require('../claude-binary');
+
+const NPM = 'C:\\Users\\u\\AppData\\Roaming\\npm';
+const SHIM = '@ECHO off\r\nSET dp0=%~dp0\r\n"%_prog%"  "%dp0%\\node_modules\\@anthropic-ai\\claude-code\\cli.js" %*\r\n';
+
+function deps(files) {
+  return { exists: (p) => Object.prototype.hasOwnProperty.call(files, p), readFile: (p) => files[p] };
+}
+
+test('a claude.exe on PATH is run directly', () => {
+  const env = { PATH: 'C:\\bin;C:\\tools' };
+  const r = resolveWindowsClaude(['agents', '--json'], env, deps({ 'C:\\tools\\claude.exe': '' }));
+  assert.deepEqual(r, { program: 'C:\\tools\\claude.exe', args: ['agents', '--json'], verbatim: false });
+});
+
+test('an npm claude.cmd shim runs node on the cli.js it points to', () => {
+  const env = { PATH: `${NPM};C:\\node` };
+  const files = {
+    [`${NPM}\\claude.cmd`]: SHIM,
+    [`${NPM}\\node_modules\\@anthropic-ai\\claude-code\\cli.js`]: '',
+    'C:\\node\\node.exe': '',
+  };
+  const r = resolveWindowsClaude(['--bg', 'say "hi" & bye\nline two'], env, deps(files));
+  assert.equal(r.program, 'C:\\node\\node.exe');
+  assert.deepEqual(r.args, [`${NPM}\\node_modules\\@anthropic-ai\\claude-code\\cli.js`, '--bg', 'say "hi" & bye\nline two']);
+  assert.equal(r.verbatim, false);
+});
+
+test('a .cmd shim that cannot be unwrapped goes through cmd.exe with escaped arguments', () => {
+  const env = { PATH: NPM, ComSpec: 'C:\\Windows\\System32\\cmd.exe' };
+  const r = resolveWindowsClaude(['stop', 'aaaaaaaa'], env, deps({ [`${NPM}\\claude.cmd`]: 'unknown shim' }));
+  assert.equal(r.program, 'C:\\Windows\\System32\\cmd.exe');
+  assert.deepEqual(r.args.slice(0, 3), ['/d', '/s', '/c']);
+  assert.equal(r.verbatim, true);
+  assert.match(r.args[3], /claude\.cmd/);
+});
+
+test('through cmd.exe a multi-line argument is refused instead of being cut', () => {
+  const env = { PATH: NPM };
+  const r = resolveWindowsClaude(['--bg', 'a\nb'], env, deps({ [`${NPM}\\claude.cmd`]: 'unknown shim' }));
+  assert.match(r.error, /multi-line/);
+});
+
+test('no claude on PATH is reported', () => {
+  assert.match(resolveWindowsClaude(['agents'], { PATH: 'C:\\bin' }, deps({})).error, /not found/);
+});
+
+test('escapeForCmd quotes the argument and escapes the cmd metacharacters', () => {
+  assert.ok(escapeForCmd('a&b').includes('^&'));
+  assert.ok(!/(^|[^^])&/.test(escapeForCmd('a&b')));
+});
+
+test('the current npm shim, which points to bin\claude.exe, runs that exe directly', () => {
+  const shim = '@ECHO off\r\nSET dp0=%~dp0\r\n"%dp0%\\node_modules\\@anthropic-ai\\claude-code\\bin\\claude.exe"   %*\r\n';
+  const exe = `${NPM}\\node_modules\\@anthropic-ai\\claude-code\\bin\\claude.exe`;
+  const r = resolveWindowsClaude(['--bg', 'a\nb'], { PATH: NPM }, deps({ [`${NPM}\\claude.cmd`]: shim, [exe]: '' }));
+  assert.deepEqual(r, { program: exe, args: ['--bg', 'a\nb'], verbatim: false });
+});
+
+test('the extensionless sh shim npm leaves next to claude.cmd is never picked', () => {
+  const shim = '@ECHO off\r\nSET dp0=%~dp0\r\n"%dp0%\\node_modules\\@anthropic-ai\\claude-code\\bin\\claude.exe"   %*\r\n';
+  const exe = `${NPM}\\node_modules\\@anthropic-ai\\claude-code\\bin\\claude.exe`;
+  const files = { [`${NPM}\\claude`]: '#!/bin/sh', [`${NPM}\\claude.cmd`]: shim, [exe]: '' };
+  const r = resolveWindowsClaude(['agents'], { PATH: NPM }, deps(files));
+  assert.equal(r.program, exe);
+});
diff --git a/test/cli-session-live-elsewhere.test.js b/test/cli-session-live-elsewhere.test.js
index d7041d4a..0907190f 100644
--- a/test/cli-session-live-elsewhere.test.js
+++ b/test/cli-session-live-elsewhere.test.js
@@ -63,7 +63,7 @@ test('a session whose id is in a state file under a live pid is live elsewhere',
   writeState(dir, 4242);
   boot(dir);
   assert.deepEqual(await cliSessionState.liveElsewhere('sess-1', noPty),
-    { pid: 4242, cwd: '/work/proj', startedAt: 1790685077444 });
+    { pid: 4242, cwd: '/work/proj', startedAt: 1790685077444, kind: 'interactive', jobId: null });
 }));
 
 test('a session this instance holds a PTY for is not live elsewhere, even with a live state file', () => withDir(async (dir) => {
diff --git a/test/cli-session-state.test.js b/test/cli-session-state.test.js
index a174258a..b66247da 100644
--- a/test/cli-session-state.test.js
+++ b/test/cli-session-state.test.js
@@ -427,3 +427,65 @@ test('getStatus keeps returning the cached status within the 5s probe throttle e
     fs.rmSync(dir, { recursive: true, force: true });
   }
 });
+
+// --- Descriptor hooks for the agents view (see .ai/contexts/bg-agents.md) ---
+
+test('onDescriptorsChanged fires once per flushed batch, and the unsubscribe stops it', async () => {
+  const dir = mkTmp();
+  try {
+    boot(dir, oneSession());
+    let fired = 0;
+    const off = cliSessionState.onDescriptorsChanged(() => { fired++; });
+    writeState(dir, 4242, { status: 'busy', kind: 'bg', jobId: 'aaaaaaaa' });
+    writeState(dir, 4243, { status: 'idle', sessionId: 'sess-2' });
+    await waitFor(() => fired >= 1);
+    await delay(SETTLE_MS);
+    assert.equal(fired, 1, 'two writes inside one FLUSH_MS window are one notification');
+    off();
+    writeState(dir, 4242, { status: 'idle', kind: 'bg', jobId: 'aaaaaaaa' });
+    await delay(SETTLE_MS);
+    assert.equal(fired, 1);
+  } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+});
+
+test('readAllDescriptors returns the live descriptors with their kind, jobId and agent', () => {
+  const dir = mkTmp();
+  try {
+    writeState(dir, 10, { status: 'idle', kind: 'bg', jobId: 'bc3fd129', agent: 'fleet:em', name: 'em', startedAt: 5 });
+    writeState(dir, 11, { status: 'busy', kind: 'interactive', sessionId: 'sess-2' });
+    writeState(dir, 12, { status: 'busy', kind: 'interactive', sessionId: 'sess-dead' });
+    fs.writeFileSync(path.join(dir, '13.json'), '{not json', 'utf8');
+    boot(dir, oneSession(), { isProcessAlive: (pid) => pid !== 12 });
+    const all = cliSessionState.readAllDescriptors().sort((a, b) => a.pid - b.pid);
+    assert.deepEqual(all.map(d => d.pid), [10, 11]);
+    assert.deepEqual(all[0], { pid: 10, sessionId: 'sess-1', kind: 'bg', jobId: 'bc3fd129', agent: 'fleet:em', name: 'em', cwd: dir, status: 'idle', startedAt: 5 });
+    assert.equal(all[1].kind, 'interactive');
+    assert.equal(all[1].jobId, null);
+  } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+});
+
+test('liveElsewhere reports the descriptor kind and jobId, so a bg session can be attached instead of resumed', async () => {
+  const dir = mkTmp();
+  try {
+    writeState(dir, 4242, { status: 'idle', kind: 'bg', jobId: 'bc3fd129' });
+    boot(dir, new Map());
+    const live = await cliSessionState.liveElsewhere('sess-1', () => false, () => []);
+    assert.equal(live.pid, 4242);
+    assert.equal(live.kind, 'bg');
+    assert.equal(live.jobId, 'bc3fd129');
+    writeState(dir, 4242, { status: 'idle' });
+    const plain = await cliSessionState.liveElsewhere('sess-1', () => false, () => []);
+    assert.equal(plain.kind, null);
+    assert.equal(plain.jobId, null);
+  } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+});
+
+test('ownProcessFilter is exported and claims our own PTY pids', () => {
+  const dir = mkTmp();
+  try {
+    boot(dir, new Map());
+    const isOwn = cliSessionState.ownProcessFilter(() => [77]);
+    assert.equal(isOwn(77), true);
+    assert.equal(isOwn(78), false);
+  } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+});
diff --git a/test/dom-agents-view.test.js b/test/dom-agents-view.test.js
new file mode 100644
index 00000000..40d77296
--- /dev/null
+++ b/test/dom-agents-view.test.js
@@ -0,0 +1,835 @@
+// test/dom-agents-view.test.js — the agents view rendered in jsdom. See .ai/contexts/bg-agents.md.
+'use strict';
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const vm = require('node:vm');
+const { JSDOM } = require('jsdom');
+
+const PUBLIC = path.join(__dirname, '..', 'public');
+const HTML = `<!DOCTYPE html><html><body>
+  <div id="placeholder"></div>
+  <div id="terminal-area"><div id="terminal-header"></div><div id="grid-viewer"></div><div id="terminals"></div></div>
+  <div id="stats-viewer"></div><div id="memory-viewer"></div><div id="work-files-viewer"></div><div id="jsonl-viewer"></div>
+  <div id="settings-viewer"><div id="settings-viewer-title"></div><div id="settings-viewer-body"></div></div>
+  <div id="memory-content"></div><div id="work-files-content"></div>
+  <div id="agents-viewer" style="display:none;">
+    <div id="agents-viewer-header"><span id="agents-viewer-title">Agents</span><span id="agents-viewer-count"></span>
+      <label id="agents-finished-toggle"><input type="checkbox" id="agents-show-finished" checked> Finished</label>
+      <label id="agents-group-toggle">Group <select id="agents-group-by"><option value="none">None</option><option value="state" selected>State</option><option value="project">Project</option></select></label>
+      <label id="agents-worktrees-toggle" title="Sub-group each project by worktree"><input type="checkbox" id="agents-group-worktrees" checked> Worktrees</label>
+      <button id="agents-new-btn" type="button">New agent</button></div>
+    <div id="agents-viewer-banner" style="display:none;"></div>
+    <div id="agents-viewer-body"><div id="agents-list"></div><div id="agents-detail"></div></div>
+  </div>
+  <div id="sidebar-filters"><button id="resort-btn"></button></div>
+</body></html>`;
+
+function evalFile(dom, file) {
+  vm.runInContext(fs.readFileSync(file, 'utf8'), dom.getInternalVMContext(), { filename: file });
+}
+
+function setup({ storage = { agentsGroupBy: 'none' }, settingsPanel = false } = {}) {
+  const dom = new JSDOM(HTML, { url: 'http://localhost/', runScripts: 'outside-only', pretendToBeVisual: true });
+  const { window } = dom;
+  for (const [k, v] of Object.entries(storage)) window.localStorage.setItem(k, v);
+  const calls = { verbs: [], opened: [], jsonl: [], external: [], stopped: [], shown: [], sidebarRefreshes: 0, fetches: 0 };
+  let changedCb = null;
+  let snapshot = { roster: [], daemonReachable: true };
+  window.api = {
+    getBgAgents: async () => { calls.fetches++; return snapshot; },
+    bgAgentVerb: async (verb, id) => { calls.verbs.push([verb, id]); return { ok: verb !== 'rm', error: verb === 'rm' ? 'nope' : undefined }; },
+    onBgAgentsChanged: (cb) => { changedCb = cb; },
+    openExternal: async (href) => calls.external.push(href),
+    stopSession: async (id) => { calls.stopped.push(id); return { ok: true }; },
+    readMemory: async () => 'memory text',
+    readWorkFile: async () => 'work file text',
+    getSetting: async () => ({}),
+    setSetting: async () => ({ ok: true }),
+    getShellProfiles: async () => [],
+    getAppVersion: async () => '0.0.0',
+    onUpdaterEvent: () => {},
+    platform: 'linux',
+  };
+  const g = {
+    placeholder: window.document.getElementById('placeholder'),
+    terminalArea: window.document.getElementById('terminal-area'),
+    terminalHeader: window.document.getElementById('terminal-header'),
+    gridViewer: window.document.getElementById('grid-viewer'),
+    statsViewer: window.document.getElementById('stats-viewer'),
+    memoryViewer: window.document.getElementById('memory-viewer'),
+    workFilesViewer: window.document.getElementById('work-files-viewer'),
+    settingsViewer: window.document.getElementById('settings-viewer'),
+    jsonlViewer: window.document.getElementById('jsonl-viewer'),
+    resortBtn: window.document.getElementById('resort-btn'),
+    memoryContent: window.document.getElementById('memory-content'),
+    workFilesContent: window.document.getElementById('work-files-content'),
+    CSS: { escape: (s) => String(s).replace(/["\\]/g, '\\$&') },
+    memoryPanel: { open: () => {} },
+    workFilesPanel: { open: () => {} },
+    openSessions: new Map(),
+    sessionMap: new Map(),
+    activeSessionId: null,
+    gridViewActive: false,
+    showSession: (id) => calls.shown.push(id),
+    openSession: (session, opts) => calls.opened.push([session, opts]),
+    showJsonlViewer: (session) => calls.jsonl.push(session),
+    refreshSidebar: () => { calls.sidebarRefreshes++; },
+    fitAndScroll: () => {},
+    confirm: () => true,
+  };
+  for (const [k, v] of Object.entries(g)) Object.defineProperty(window, k, { value: v, writable: true, configurable: true });
+  vm.runInContext(fs.readFileSync(path.join(__dirname, '..', 'node_modules', 'morphdom', 'dist', 'morphdom-umd.js'), 'utf8'), dom.getInternalVMContext());
+  evalFile(dom, path.join(PUBLIC, 'utils.js'));
+  evalFile(dom, path.join(PUBLIC, 'session-state.js'));
+  evalFile(dom, path.join(PUBLIC, 'memory-workfiles-view.js'));
+  evalFile(dom, path.join(PUBLIC, 'agents-view.js'));
+  if (settingsPanel) {
+    evalFile(dom, path.join(PUBLIC, 'setting-defaults.js'));
+    evalFile(dom, path.join(PUBLIC, 'shortcuts.js'));
+    evalFile(dom, path.join(PUBLIC, 'terminal-themes.js'));
+    evalFile(dom, path.join(PUBLIC, 'settings-panel.js'));
+  }
+  window.initAgentsView();
+  const read = (expr) => vm.runInContext(expr, dom.getInternalVMContext());
+  return {
+    window, document: window.document, calls, read,
+    setSnapshot(s) { snapshot = s; },
+    emitChanged(s) { snapshot = s; changedCb(s); },
+    destroy() { window.close(); },
+  };
+}
+
+const ROSTER = [
+  { id: 'aaaaaaaa', sessionId: 's-a', name: 'em-platform', cwd: '/w/em', kind: 'background', state: 'working', status: 'idle', pid: 10, startedAt: Date.now() - 60_000, agent: 'fleet:em', model: 'sonnet', detail: 'awaiting !196', tempo: 'idle', tokens: 173000, fan: [{ id: 'f', kind: 'agent', label: 'Spawn developer', startedAt: 1, doneAt: 27_000 }], children: [{ id: '195', href: 'https://gitlab.example/mr/195', kind: 'mr' }], result: 'no action', attachedHere: false },
+  { id: 'bbbbbbbb', sessionId: 's-b', name: 'spike', cwd: '/w/f', kind: 'background', state: 'done', status: null, pid: null, startedAt: Date.now() - 3_600_000, agent: null, model: null, detail: null, tempo: null, tokens: 274, fan: [], children: [], result: null, attachedHere: false },
+  { id: null, sessionId: 's-i', name: 'lvds-1b', cwd: '/w/l', kind: 'interactive', state: null, status: 'busy', pid: 30, startedAt: Date.now() - 10_000, agent: null, model: null, detail: null, tempo: null, tokens: null, fan: [], children: [], result: null, attachedHere: false },
+];
+
+test('showing the view hides the terminal area, lists the roster sorted, and counts running/finished', async (t) => {
+  const ctx = setup(); t.after(() => ctx.destroy());
+  ctx.setSnapshot({ roster: ROSTER, daemonReachable: true });
+  await ctx.window.showAgentsView();
+  assert.equal(ctx.window.terminalArea.style.display, 'none');
+  assert.equal(ctx.document.getElementById('agents-viewer').style.display, 'flex');
+  assert.equal(ctx.read('agentsViewActive'), true);
+  const names = [...ctx.document.querySelectorAll('.agents-row-name')].map(el => el.textContent);
+  assert.deepEqual(names, ['lvds-1b', 'em-platform', 'spike']);
+  assert.equal(ctx.document.getElementById('agents-viewer-count').textContent, '1 running · 1 finished');
+  assert.equal(ctx.document.getElementById('agents-viewer-banner').style.display, 'none');
+  assert.equal(ctx.window.localStorage.getItem('agentsViewActive'), '1');
+});
+
+test('the Finished filter hides done and stopped jobs and is remembered', async (t) => {
+  const ctx = setup(); t.after(() => ctx.destroy());
+  ctx.setSnapshot({ roster: ROSTER, daemonReachable: true });
+  await ctx.window.showAgentsView();
+  const box = ctx.document.getElementById('agents-show-finished');
+  box.checked = false;
+  box.dispatchEvent(new ctx.window.Event('change', { bubbles: true }));
+  assert.deepEqual([...ctx.document.querySelectorAll('.agents-row-name')].map(el => el.textContent), ['lvds-1b', 'em-platform']);
+  assert.equal(ctx.window.localStorage.getItem('agentsShowFinished'), '0');
+});
+
+test('selecting a row renders its detail with the verbs disabled by state, and a roster update keeps the selection', async (t) => {
+  const ctx = setup(); t.after(() => ctx.destroy());
+  ctx.setSnapshot({ roster: ROSTER, daemonReachable: true });
+  await ctx.window.showAgentsView();
+  ctx.document.querySelector('.agents-row[data-key="bg:aaaaaaaa"]').click();
+  const detail = ctx.document.getElementById('agents-detail');
+  assert.match(detail.textContent, /awaiting !196/);
+  assert.match(detail.textContent, /173k tokens/);
+  assert.match(detail.textContent, /Spawn developer/);
+  assert.equal(detail.querySelector('[data-verb="rm"]').disabled, true);
+  assert.equal(detail.querySelector('[data-verb="stop"]').disabled, false);
+  assert.equal(detail.querySelector('[data-verb="attach"]').disabled, false);
+  ctx.emitChanged({ roster: [{ ...ROSTER[0], detail: 'changed' }, ROSTER[1], ROSTER[2]], daemonReachable: true });
+  assert.match(ctx.document.getElementById('agents-detail').textContent, /changed/);
+  assert.ok(ctx.document.querySelector('.agents-row[data-key="bg:aaaaaaaa"]').classList.contains('selected'));
+});
+
+test('the verbs: attach opens a tab keyed by the session id, transcript opens the viewer, stop calls the IPC, a failure shows in the detail', async (t) => {
+  const ctx = setup(); t.after(() => ctx.destroy());
+  ctx.setSnapshot({ roster: ROSTER, daemonReachable: true });
+  await ctx.window.showAgentsView();
+  ctx.document.querySelector('.agents-row[data-key="bg:aaaaaaaa"]').click();
+  const detail = ctx.document.getElementById('agents-detail');
+  detail.querySelector('[data-verb="attach"]').click();
+  assert.equal(ctx.calls.opened.length, 1);
+  assert.equal(ctx.calls.opened[0][0].sessionId, 's-a');
+  assert.deepEqual({ ...ctx.calls.opened[0][1] }, { type: 'attach', jobId: 'aaaaaaaa', cwd: '/w/em' });
+  detail.querySelector('[data-verb="transcript"]').click();
+  assert.equal(ctx.calls.jsonl[0].sessionId, 's-a');
+  await ctx.window.runAgentVerb('stop', ROSTER[0]);
+  assert.deepEqual(ctx.calls.verbs, [['stop', 'aaaaaaaa']]);
+  ctx.document.querySelector('.agents-row[data-key="bg:bbbbbbbb"]').click();
+  await ctx.window.runAgentVerb('rm', ROSTER[1]);
+  assert.match(ctx.document.getElementById('agents-detail').textContent, /nope/);
+});
+
+test('stop on a session attached here detaches the tab first', async (t) => {
+  const ctx = setup(); t.after(() => ctx.destroy());
+  await ctx.window.showAgentsView();
+  await ctx.window.runAgentVerb('stop', { ...ROSTER[0], attachedHere: true });
+  assert.deepEqual(ctx.calls.stopped, ['s-a']);
+  assert.deepEqual(ctx.calls.verbs, [['stop', 'aaaaaaaa']]);
+});
+
+test('an unreachable daemon shows the banner and disables every verb but Transcript; an empty roster shows the empty state', async (t) => {
+  const ctx = setup(); t.after(() => ctx.destroy());
+  ctx.setSnapshot({ roster: ROSTER, daemonReachable: false });
+  await ctx.window.showAgentsView();
+  assert.notEqual(ctx.document.getElementById('agents-viewer-banner').style.display, 'none');
+  ctx.document.querySelector('.agents-row[data-key="bg:aaaaaaaa"]').click();
+  const detail = ctx.document.getElementById('agents-detail');
+  assert.equal(detail.querySelector('[data-verb="stop"]').disabled, true);
+  assert.equal(detail.querySelector('[data-verb="transcript"]').disabled, false);
+  ctx.emitChanged({ roster: [], daemonReachable: true });
+  assert.match(ctx.document.getElementById('agents-list').textContent, /No background agents/);
+});
+
+test('hideAllViewers closes the view without restoring the terminal; hideAgentsView restores it', async (t) => {
+  const ctx = setup(); t.after(() => ctx.destroy());
+  ctx.window.activeSessionId = 'open-1';
+  ctx.window.openSessions.set('open-1', { closed: false });
+  await ctx.window.showAgentsView();
+  ctx.window.hideAllViewers();
+  assert.equal(ctx.read('agentsViewActive'), false);
+  assert.equal(ctx.document.getElementById('agents-viewer').style.display, 'none');
+  assert.deepEqual(ctx.calls.shown, [], 'no restore from hideAllViewers');
+  await ctx.window.showAgentsView();
+  ctx.window.hideAgentsView();
+  assert.deepEqual(ctx.calls.shown, ['open-1']);
+  assert.equal(ctx.window.terminalArea.style.display, '');
+});
+
+test('a roster push puts only the live jobs in bgAgentSessionIds and refreshes the sidebar only when the set changes', async (t) => {
+  const ctx = setup(); t.after(() => ctx.destroy());
+  ctx.emitChanged({ roster: ROSTER, daemonReachable: true });
+  assert.deepEqual([...ctx.read('bgAgentSessionIds')].sort(), ['s-a']);
+  assert.equal(ctx.calls.sidebarRefreshes, 1);
+  ctx.emitChanged({ roster: ROSTER, daemonReachable: true });
+  assert.equal(ctx.calls.sidebarRefreshes, 1);
+  ctx.emitChanged({ roster: [ROSTER[0], { ...ROSTER[1], state: 'blocked' }, ROSTER[2]], daemonReachable: true });
+  assert.deepEqual([...ctx.read('bgAgentSessionIds')].sort(), ['s-a', 's-b']);
+  assert.equal(ctx.calls.sidebarRefreshes, 2);
+  ctx.emitChanged({ roster: [{ ...ROSTER[0], state: 'done' }, ROSTER[1], ROSTER[2]], daemonReachable: true });
+  assert.deepEqual([...ctx.read('bgAgentSessionIds')], []);
+  assert.equal(ctx.calls.sidebarRefreshes, 3);
+});
+
+test('no roster fetch before the view is first opened; opening it fetches', async (t) => {
+  const ctx = setup(); t.after(() => ctx.destroy());
+  assert.equal(ctx.calls.fetches, 0);
+  await ctx.window.showAgentsView();
+  assert.equal(ctx.calls.fetches, 1);
+});
+
+test('attach from the view while the grid is shown closes the view onto the grid', async (t) => {
+  const ctx = setup(); t.after(() => ctx.destroy());
+  ctx.setSnapshot({ roster: ROSTER, daemonReachable: true });
+  await ctx.window.showAgentsView();
+  ctx.window.gridViewActive = true;
+  ctx.window.attachBgAgent(ROSTER[0]);
+  assert.equal(ctx.read('agentsViewActive'), false);
+  assert.equal(ctx.window.gridViewer.style.display, 'block');
+  assert.equal(ctx.calls.opened.length, 1);
+});
+
+test('a blocked job counts as running, sorts with the live rows and keeps only the live verbs', async (t) => {
+  const ctx = setup(); t.after(() => ctx.destroy());
+  const blocked = { ...ROSTER[0], id: 'cccccccc', sessionId: 's-c', name: 'asks', state: 'blocked', status: 'waiting', startedAt: Date.now() - 5_000 };
+  ctx.setSnapshot({ roster: [...ROSTER, blocked], daemonReachable: true });
+  await ctx.window.showAgentsView();
+  assert.deepEqual([...ctx.document.querySelectorAll('.agents-row-name')].map(el => el.textContent), ['asks', 'lvds-1b', 'em-platform', 'spike']);
+  assert.equal(ctx.document.getElementById('agents-viewer-count').textContent, '2 running · 1 finished');
+  const box = ctx.document.getElementById('agents-show-finished');
+  box.checked = false;
+  box.dispatchEvent(new ctx.window.Event('change', { bubbles: true }));
+  ctx.document.querySelector('.agents-row[data-key="bg:cccccccc"]').click();
+  const detail = ctx.document.getElementById('agents-detail');
+  assert.equal(detail.querySelector('[data-verb="attach"]').disabled, false);
+  assert.equal(detail.querySelector('[data-verb="stop"]').disabled, false);
+  assert.equal(detail.querySelector('[data-verb="respawn"]').disabled, true);
+  assert.equal(detail.querySelector('[data-verb="rm"]').disabled, true);
+  detail.querySelector('[data-verb="attach"]').click();
+  assert.deepEqual({ ...ctx.calls.opened[0][1] }, { type: 'attach', jobId: 'cccccccc', cwd: '/w/em' });
+});
+
+test('a failed job reads "failed", counts as finished and is hidden by the Finished filter', async (t) => {
+  const ctx = setup(); t.after(() => ctx.destroy());
+  const failed = { ...ROSTER[1], id: 'ffffffff', sessionId: 's-f', name: 'broke', state: 'failed' };
+  ctx.setSnapshot({ roster: [...ROSTER, failed], daemonReachable: true });
+  await ctx.window.showAgentsView();
+  const row = ctx.document.querySelector('.agents-row[data-key="bg:ffffffff"]');
+  assert.equal(row.querySelector('.agents-row-state').textContent, '❌ failed');
+  assert.equal(ctx.document.getElementById('agents-viewer-count').textContent, '1 running · 2 finished');
+  row.click();
+  const detail = ctx.document.getElementById('agents-detail');
+  assert.equal(detail.querySelector('[data-verb="rm"]').disabled, false);
+  assert.equal(detail.querySelector('[data-verb="respawn"]').disabled, false);
+  assert.equal(detail.querySelector('[data-verb="attach"]').disabled, true);
+  const box = ctx.document.getElementById('agents-show-finished');
+  box.checked = false;
+  box.dispatchEvent(new ctx.window.Event('change', { bubbles: true }));
+  assert.equal(ctx.document.querySelector('.agents-row[data-key="bg:ffffffff"]'), null);
+});
+
+function chooseGroupBy(ctx, mode) {
+  const sel = ctx.document.getElementById('agents-group-by');
+  sel.value = mode;
+  sel.dispatchEvent(new ctx.window.Event('change', { bubbles: true }));
+}
+
+function headText(el) {
+  return el.textContent.replace(/^[▾▸] /, '');
+}
+
+function listLayout(ctx) {
+  return [...ctx.document.getElementById('agents-list').children].map(el =>
+    el.classList.contains('agents-group-header') ? '# ' + headText(el)
+      : el.classList.contains('agents-subgroup-header') ? '## ' + headText(el)
+        : el.querySelector('.agents-row-name').textContent);
+}
+
+test('group by state: a header per non-empty group with its count, each row once, no header without the mode', async (t) => {
+  const ctx = setup(); t.after(() => ctx.destroy());
+  const failed = { ...ROSTER[1], id: 'ffffffff', sessionId: 's-f', name: 'broke', state: 'failed' };
+  ctx.setSnapshot({ roster: [...ROSTER, failed], daemonReachable: true });
+  await ctx.window.showAgentsView();
+  assert.equal(ctx.document.querySelectorAll('.agents-group-header').length, 0);
+  chooseGroupBy(ctx, 'state');
+  assert.deepEqual(listLayout(ctx), ['# ⚙️ Working · 1', 'em-platform', '# ✅ Done · 1', 'spike', '# ❌ Failed · 1', 'broke', '# 🖥️ External · 1', 'lvds-1b']);
+  assert.equal(ctx.document.querySelectorAll('.agents-row').length, 4);
+  assert.equal(ctx.window.localStorage.getItem('agentsGroupBy'), 'state');
+  chooseGroupBy(ctx, 'none');
+  assert.deepEqual(listLayout(ctx), ['lvds-1b', 'em-platform', 'spike', 'broke']);
+});
+
+test('group by project: headers labelled by the last segment with the full path as title, live groups first', async (t) => {
+  const ctx = setup(); t.after(() => ctx.destroy());
+  const second = { ...ROSTER[0], id: 'cccccccc', sessionId: 's-c', name: 'em-two', state: 'done', startedAt: Date.now() - 120_000 };
+  const homeless = { ...ROSTER[1], id: 'dddddddd', sessionId: 's-d', name: 'nowhere', cwd: null };
+  ctx.setSnapshot({ roster: [...ROSTER, second, homeless], daemonReachable: true });
+  await ctx.window.showAgentsView();
+  chooseGroupBy(ctx, 'project');
+  assert.deepEqual(listLayout(ctx), ['# em · 2', 'em-platform', 'em-two', '# l · 1', 'lvds-1b', '# f · 1', 'spike', '# No project · 1', 'nowhere']);
+  const head = ctx.document.querySelector('.agents-group-header');
+  assert.equal(head.getAttribute('title'), '/w/em');
+  assert.equal(ctx.window.localStorage.getItem('agentsGroupBy'), 'project');
+});
+
+test('the Finished filter applies before grouping: a group left empty is not shown', async (t) => {
+  const ctx = setup(); t.after(() => ctx.destroy());
+  ctx.setSnapshot({ roster: ROSTER, daemonReachable: true });
+  await ctx.window.showAgentsView();
+  chooseGroupBy(ctx, 'state');
+  const box = ctx.document.getElementById('agents-show-finished');
+  box.checked = false;
+  box.dispatchEvent(new ctx.window.Event('change', { bubbles: true }));
+  assert.deepEqual(listLayout(ctx), ['# ⚙️ Working · 1', 'em-platform', '# 🖥️ External · 1', 'lvds-1b']);
+  ctx.emitChanged({ roster: [], daemonReachable: true });
+  assert.equal(ctx.document.querySelectorAll('.agents-group-header').length, 0);
+  assert.match(ctx.document.getElementById('agents-list').textContent, /No background agents/);
+});
+
+test('the selected row stays selected across a regroup, and a click on a header toggles it without selecting a row', async (t) => {
+  const ctx = setup(); t.after(() => ctx.destroy());
+  ctx.setSnapshot({ roster: ROSTER, daemonReachable: true });
+  await ctx.window.showAgentsView();
+  ctx.document.querySelector('.agents-row[data-key="bg:bbbbbbbb"]').click();
+  chooseGroupBy(ctx, 'project');
+  assert.ok(ctx.document.querySelector('.agents-row[data-key="bg:bbbbbbbb"]').classList.contains('selected'));
+  chooseGroupBy(ctx, 'state');
+  assert.ok(ctx.document.querySelector('.agents-row[data-key="bg:bbbbbbbb"]').classList.contains('selected'));
+  ctx.document.querySelector('.agents-group-header').click();
+  assert.equal(ctx.document.querySelector('.agents-group-header').getAttribute('aria-expanded'), 'false');
+  assert.equal(ctx.read('agentsSelectedKey'), 'bg:bbbbbbbb');
+  assert.equal(ctx.document.querySelectorAll('.agents-row.selected').length, 1);
+  assert.match(ctx.document.getElementById('agents-detail').textContent, /spike/);
+  assert.equal(ctx.calls.verbs.length, 0);
+});
+
+function header(ctx, collapseKey) {
+  return [...ctx.document.querySelectorAll('[data-collapse]')].find(h => h.dataset.collapse === collapseKey);
+}
+
+function storedCollapsed(ctx) {
+  return JSON.parse(ctx.window.localStorage.getItem('agentsCollapsedGroups') || '[]');
+}
+
+test('collapse: a header click folds its rows, keeps label and count, flips the chevron and aria-expanded, and is remembered', async (t) => {
+  const ctx = setup({ storage: {} }); t.after(() => ctx.destroy());
+  ctx.setSnapshot({ roster: ROSTER, daemonReachable: true });
+  await ctx.window.showAgentsView();
+  const done = header(ctx, 'state:done');
+  assert.equal(done.getAttribute('role'), 'button');
+  assert.equal(done.getAttribute('tabindex'), '0');
+  assert.equal(done.getAttribute('aria-expanded'), 'true');
+  assert.equal(done.querySelector('.agents-group-chevron').textContent, '▾');
+  assert.equal(done.querySelector('.agents-group-chevron').getAttribute('aria-hidden'), 'true');
+  done.click();
+  assert.deepEqual(listLayout(ctx), ['# ⚙️ Working · 1', 'em-platform', '# ✅ Done · 1', '# 🖥️ External · 1', 'lvds-1b']);
+  const folded = header(ctx, 'state:done');
+  assert.equal(folded.getAttribute('aria-expanded'), 'false');
+  assert.equal(folded.querySelector('.agents-group-chevron').textContent, '▸');
+  assert.deepEqual(storedCollapsed(ctx), ['state:done']);
+  folded.click();
+  assert.deepEqual(listLayout(ctx), ['# ⚙️ Working · 1', 'em-platform', '# ✅ Done · 1', 'spike', '# 🖥️ External · 1', 'lvds-1b']);
+  assert.deepEqual(storedCollapsed(ctx), []);
+});
+
+test('collapse: Enter and Space on a focused header toggle it', async (t) => {
+  const ctx = setup({ storage: {} }); t.after(() => ctx.destroy());
+  ctx.setSnapshot({ roster: ROSTER, daemonReachable: true });
+  await ctx.window.showAgentsView();
+  const key = (k) => {
+    const ev = new ctx.window.KeyboardEvent('keydown', { key: k, bubbles: true, cancelable: true });
+    header(ctx, 'state:working').dispatchEvent(ev);
+    return ev;
+  };
+  const ev = key('Enter');
+  assert.equal(ev.defaultPrevented, true);
+  assert.equal(header(ctx, 'state:working').getAttribute('aria-expanded'), 'false');
+  key(' ');
+  assert.equal(header(ctx, 'state:working').getAttribute('aria-expanded'), 'true');
+  key('a');
+  assert.equal(header(ctx, 'state:working').getAttribute('aria-expanded'), 'true');
+});
+
+test('collapse: restored from storage, survives a roster push, a mode switch and the Finished filter; selection kept', async (t) => {
+  const ctx = setup({ storage: { agentsCollapsedGroups: '["state:done"]' } }); t.after(() => ctx.destroy());
+  ctx.setSnapshot({ roster: ROSTER, daemonReachable: true });
+  await ctx.window.showAgentsView();
+  assert.equal(ctx.document.querySelector('.agents-row[data-key="bg:bbbbbbbb"]'), null);
+  assert.equal(header(ctx, 'state:done').textContent.includes('· 1'), true);
+  ctx.emitChanged({ roster: [...ROSTER], daemonReachable: true });
+  assert.equal(ctx.document.querySelector('.agents-row[data-key="bg:bbbbbbbb"]'), null);
+  chooseGroupBy(ctx, 'project');
+  assert.ok(ctx.document.querySelector('.agents-row[data-key="bg:bbbbbbbb"]'), 'state:done does not fold a project');
+  ctx.document.querySelector('.agents-row[data-key="bg:aaaaaaaa"]').click();
+  header(ctx, 'project:/w/em').click();
+  assert.equal(ctx.document.querySelector('.agents-row[data-key="bg:aaaaaaaa"]'), null);
+  assert.equal(ctx.read('agentsSelectedKey'), 'bg:aaaaaaaa');
+  assert.match(ctx.document.getElementById('agents-detail').textContent, /em-platform/);
+  ctx.emitChanged({ roster: [{ ...ROSTER[0], detail: 'pushed' }, ROSTER[1], ROSTER[2]], daemonReachable: true });
+  assert.equal(ctx.read('agentsSelectedKey'), 'bg:aaaaaaaa');
+  assert.match(ctx.document.getElementById('agents-detail').textContent, /pushed/);
+  chooseGroupBy(ctx, 'state');
+  assert.equal(ctx.document.querySelector('.agents-row[data-key="bg:bbbbbbbb"]'), null);
+  const box = ctx.document.getElementById('agents-show-finished');
+  box.checked = false;
+  box.dispatchEvent(new ctx.window.Event('change', { bubbles: true }));
+  box.checked = true;
+  box.dispatchEvent(new ctx.window.Event('change', { bubbles: true }));
+  assert.equal(header(ctx, 'state:done').getAttribute('aria-expanded'), 'false');
+  assert.deepEqual(storedCollapsed(ctx).sort(), ['project:/w/em', 'state:done']);
+});
+
+test('collapse: invalid stored value collapses nothing; a throwing storage still toggles', async (t) => {
+  for (const bad of ['{nope', '{"a":1}', '42']) {
+    const ctx = setup({ storage: { agentsCollapsedGroups: bad } }); t.after(() => ctx.destroy());
+    ctx.setSnapshot({ roster: ROSTER, daemonReachable: true });
+    await ctx.window.showAgentsView();
+    assert.equal(ctx.document.querySelectorAll('[aria-expanded="false"]').length, 0, bad);
+    assert.equal(ctx.document.querySelectorAll('.agents-row').length, 3, bad);
+  }
+  const ctx = setup({ storage: {} }); t.after(() => ctx.destroy());
+  ctx.setSnapshot({ roster: ROSTER, daemonReachable: true });
+  await ctx.window.showAgentsView();
+  Object.defineProperty(ctx.window, 'localStorage', { configurable: true, get() { throw new Error('denied'); } });
+  header(ctx, 'state:done').click();
+  assert.equal(header(ctx, 'state:done').getAttribute('aria-expanded'), 'false');
+});
+
+test('collapse: a project folds its worktree sub-groups; a sub-group folds only its rows', async (t) => {
+  const ctx = setup({ storage: { agentsGroupBy: 'project' } }); t.after(() => ctx.destroy());
+  ctx.setSnapshot({ roster: APP_ROSTER, daemonReachable: true });
+  await ctx.window.showAgentsView();
+  const subKey = 'worktree:' + APP + '|' + APP + '/.claude/worktrees/x';
+  const sub = header(ctx, subKey);
+  assert.ok(sub && sub.classList.contains('agents-subgroup-header'));
+  assert.equal(sub.getAttribute('role'), 'button');
+  sub.click();
+  assert.deepEqual(listLayout(ctx), ['# app · 2', '## main · 1', 'on-main', '## x · 1', '# other · 1', 'other-repo']);
+  header(ctx, 'project:' + APP).click();
+  assert.deepEqual(listLayout(ctx), ['# app · 2', '# other · 1', 'other-repo']);
+  header(ctx, 'project:' + APP).click();
+  assert.deepEqual(listLayout(ctx), ['# app · 2', '## main · 1', 'on-main', '## x · 1', '# other · 1', 'other-repo']);
+  toggleWorktrees(ctx, false);
+  assert.deepEqual(listLayout(ctx), ['# app · 2', 'on-main', 'in-wt', '# other · 1', 'other-repo']);
+});
+
+test('collapse: quotes and class= payloads in a project path used as a collapse key inject nothing and round-trip', async (t) => {
+  const ctx = setup({ storage: { agentsGroupBy: 'project' } }); t.after(() => ctx.destroy());
+  const payload = 'x" class="agents-row" data-key="bg:aaaaaaaa" data-verb="stop" y=\'z';
+  const root = '/w/' + payload;
+  ctx.setSnapshot({ roster: [{ ...ROSTER[1], id: 'cccccccc', cwd: root, projectRoot: root, worktreeRoot: root }], daemonReachable: true });
+  await ctx.window.showAgentsView();
+  const head = header(ctx, 'project:' + root);
+  assert.ok(head);
+  assert.equal(head.className, 'agents-group-header');
+  assert.equal(head.hasAttribute('data-verb'), false);
+  assert.equal(head.hasAttribute('data-key'), false);
+  head.click();
+  assert.equal(ctx.read('agentsSelectedKey'), null);
+  assert.equal(ctx.calls.verbs.length, 0);
+  assert.deepEqual(storedCollapsed(ctx), ['project:' + root]);
+  assert.equal(ctx.document.querySelectorAll('.agents-row').length, 0);
+  const again = setup({ storage: { agentsGroupBy: 'project', agentsCollapsedGroups: ctx.window.localStorage.getItem('agentsCollapsedGroups') } });
+  t.after(() => again.destroy());
+  again.setSnapshot({ roster: [{ ...ROSTER[1], id: 'cccccccc', cwd: root, projectRoot: root, worktreeRoot: root }], daemonReachable: true });
+  await again.window.showAgentsView();
+  assert.equal(header(again, 'project:' + root).getAttribute('aria-expanded'), 'false');
+});
+
+test('collapse: the header looks clickable, focusable and does not select text', () => {
+  const css = fs.readFileSync(path.join(PUBLIC, 'style.css'), 'utf8');
+  assert.match(css, /\.agents-group-header,\s*\.agents-subgroup-header\s*\{[^}]*cursor:\s*pointer[^}]*user-select:\s*none/);
+  assert.match(css, /\.agents-group-header:focus-visible/);
+});
+
+test('the grouping is restored from storage; an invalid stored value falls back to state', async (t) => {
+  const ctx = setup({ storage: { agentsGroupBy: 'project' } }); t.after(() => ctx.destroy());
+  ctx.setSnapshot({ roster: ROSTER, daemonReachable: true });
+  await ctx.window.showAgentsView();
+  assert.equal(ctx.document.getElementById('agents-group-by').value, 'project');
+  assert.equal(ctx.document.querySelectorAll('.agents-group-header').length, 3);
+  const bad = setup({ storage: { agentsGroupBy: 'evil" onclick="x' } }); t.after(() => bad.destroy());
+  bad.setSnapshot({ roster: ROSTER, daemonReachable: true });
+  await bad.window.showAgentsView();
+  assert.equal(bad.document.getElementById('agents-group-by').value, 'state');
+  assert.equal(bad.document.querySelectorAll('.agents-group-header').length, 3);
+  assert.equal(bad.read('agentsGroupBy'), 'state');
+});
+
+test('a throwing localStorage leaves the grouping at state and choosing one still works', async (t) => {
+  const ctx = setup(); t.after(() => ctx.destroy());
+  ctx.setSnapshot({ roster: ROSTER, daemonReachable: true });
+  await ctx.window.showAgentsView();
+  Object.defineProperty(ctx.window, 'localStorage', { configurable: true, get() { throw new Error('denied'); } });
+  assert.equal(ctx.window.readAgentsGroupBy(), 'state');
+  chooseGroupBy(ctx, 'project');
+  assert.equal(ctx.read('agentsGroupBy'), 'project');
+  assert.equal(ctx.document.querySelectorAll('.agents-group-header').length, 3);
+});
+
+test('quotes and attribute payloads in a cwd used as a project group title cannot inject attributes', async (t) => {
+  const ctx = setup(); t.after(() => ctx.destroy());
+  const payload = 'x" class="agents-verb-btn" data-verb="stop" y=\'z';
+  const evil = { ...ROSTER[1], id: 'cccccccc', cwd: '/w/' + payload };
+  ctx.setSnapshot({ roster: [evil], daemonReachable: true });
+  await ctx.window.showAgentsView();
+  chooseGroupBy(ctx, 'project');
+  const head = ctx.document.querySelector('.agents-group-header');
+  assert.equal(head.getAttribute('title'), '/w/' + payload);
+  assert.equal(head.className, 'agents-group-header');
+  assert.equal(head.hasAttribute('data-verb'), false);
+  assert.equal(head.hasAttribute('y'), false);
+  assert.equal(headText(head), payload + ' · 1');
+  assert.equal(ctx.document.querySelectorAll('[data-verb]').length, 0);
+  head.click();
+  assert.equal(ctx.calls.verbs.length, 0);
+});
+
+test('with nothing stored the list is grouped by state, headers carrying emoji, label and count', async (t) => {
+  const ctx = setup({ storage: {} }); t.after(() => ctx.destroy());
+  const blocked = { ...ROSTER[0], id: 'cccccccc', sessionId: 's-c', name: 'asks', state: 'blocked', startedAt: Date.now() - 5_000 };
+  const stopped = { ...ROSTER[1], id: 'dddddddd', sessionId: 's-d', name: 'halted', state: 'stopped' };
+  const odd = { ...ROSTER[1], id: 'eeeeeeee', sessionId: 's-e', name: 'odd', state: null };
+  ctx.setSnapshot({ roster: [...ROSTER, blocked, stopped, odd], daemonReachable: true });
+  await ctx.window.showAgentsView();
+  assert.equal(ctx.read('agentsGroupBy'), 'state');
+  assert.equal(ctx.document.getElementById('agents-group-by').value, 'state');
+  assert.deepEqual(listLayout(ctx), ['# ⚙️ Working · 1', 'em-platform', '# ✋ Blocked · 1', 'asks', '# ✅ Done · 1', 'spike',
+    '# ⏹️ Stopped · 1', 'halted', '# 🖥️ External · 1', 'lvds-1b', '# ❓ Unknown · 1', 'odd']);
+  const emoji = ctx.document.querySelector('.agents-group-header .agents-group-emoji');
+  assert.equal(emoji.getAttribute('aria-hidden'), 'true');
+  assert.equal(emoji.textContent, '⚙️');
+  assert.equal(ctx.document.querySelector('.agents-group-header .agents-group-label').textContent, 'Working');
+  assert.equal(ctx.window.localStorage.getItem('agentsGroupBy'), null, 'the default is not written back');
+});
+
+test('a stored none or project is respected over the state default', async (t) => {
+  for (const mode of ['none', 'project']) {
+    const ctx = setup({ storage: { agentsGroupBy: mode } }); t.after(() => ctx.destroy());
+    ctx.setSnapshot({ roster: ROSTER, daemonReachable: true });
+    await ctx.window.showAgentsView();
+    assert.equal(ctx.document.getElementById('agents-group-by').value, mode);
+    assert.equal(ctx.document.querySelectorAll('.agents-group-header').length, mode === 'none' ? 0 : 3);
+    assert.equal(ctx.document.querySelectorAll('.agents-group-emoji').length, 0);
+  }
+});
+
+test('every row starts its state column with its state emoji in every grouping mode', async (t) => {
+  const ctx = setup(); t.after(() => ctx.destroy());
+  const failed = { ...ROSTER[1], id: 'ffffffff', sessionId: 's-f', name: 'broke', state: 'failed' };
+  const odd = { ...ROSTER[1], id: 'eeeeeeee', sessionId: 's-e', name: 'odd', state: null };
+  ctx.setSnapshot({ roster: [...ROSTER, failed, odd], daemonReachable: true });
+  await ctx.window.showAgentsView();
+  const expected = { 'em-platform': '⚙️ working · idle', spike: '✅ done', 'lvds-1b': '🖥️ external · busy', broke: '❌ failed', odd: '❓ ?' };
+  for (const mode of ['none', 'state', 'project']) {
+    chooseGroupBy(ctx, mode);
+    const got = Object.fromEntries([...ctx.document.querySelectorAll('.agents-row')].map(r =>
+      [r.querySelector('.agents-row-name').textContent, r.querySelector('.agents-row-state').textContent]));
+    assert.deepEqual(got, expected, mode);
+    assert.equal(ctx.document.querySelectorAll('.agents-row .agents-state-emoji[aria-hidden="true"]').length, 5, mode);
+    assert.equal(ctx.document.querySelectorAll('.agents-row .session-icon').length, 5, mode);
+  }
+});
+
+test('the group header is styled larger and semi-bold, its count secondary', () => {
+  const css = fs.readFileSync(path.join(PUBLIC, 'style.css'), 'utf8');
+  const rule = (sel) => {
+    const m = css.match(new RegExp('(^|\\n)' + sel.replace(/[.#-]/g, '\\$&') + '\\s*\\{([^}]*)\\}'));
+    return m ? m[2] : '';
+  };
+  const head = rule('.agents-group-header');
+  const size = head.match(/font-size:\s*([\d.]+)em/);
+  assert.ok(size && Number(size[1]) >= 1.15, 'header font-size of at least 1.15em');
+  assert.match(head, /font-weight:\s*600/);
+  assert.match(head, /padding:\s*\d+px/);
+  assert.match(rule('.agents-group-count'), /font-weight:\s*400/);
+  const html = fs.readFileSync(path.join(PUBLIC, 'index.html'), 'utf8');
+  assert.match(html, /<option value="state" selected>/);
+});
+
+const APP = '/w/app';
+const inApp = (id, name, worktreeRoot, over = {}) => ({ ...ROSTER[1], id, sessionId: 's-' + id, name, cwd: worktreeRoot, projectRoot: APP, worktreeRoot, ...over });
+const APP_ROSTER = [
+  inApp('a1aaaaaa', 'on-main', APP, { startedAt: Date.now() - 1000 }),
+  inApp('a2aaaaaa', 'in-wt', APP + '/.claude/worktrees/x', { cwd: APP + '/.claude/worktrees/x/src', startedAt: Date.now() - 2000 }),
+  { ...ROSTER[1], id: 'o1oooooo', sessionId: 's-o', name: 'other-repo', cwd: '/w/other', projectRoot: '/w/other', worktreeRoot: '/w/other' },
+];
+
+function toggleWorktrees(ctx, on) {
+  const box = ctx.document.getElementById('agents-group-worktrees');
+  box.checked = on;
+  box.dispatchEvent(new ctx.window.Event('change', { bubbles: true }));
+}
+
+test('project mode groups the worktrees of one git project under its root; unrelated repos stay apart', async (t) => {
+  const ctx = setup({ storage: { agentsGroupBy: 'project', agentsGroupWorktrees: '0' } }); t.after(() => ctx.destroy());
+  ctx.setSnapshot({ roster: APP_ROSTER, daemonReachable: true });
+  await ctx.window.showAgentsView();
+  assert.deepEqual(listLayout(ctx), ['# app · 2', 'on-main', 'in-wt', '# other · 1', 'other-repo']);
+  assert.equal(ctx.document.querySelector('.agents-group-header').getAttribute('title'), APP);
+});
+
+test('the Worktrees option is checked by default, sub-groups a project by worktree, and is remembered', async (t) => {
+  const ctx = setup({ storage: { agentsGroupBy: 'project' } }); t.after(() => ctx.destroy());
+  ctx.setSnapshot({ roster: APP_ROSTER, daemonReachable: true });
+  await ctx.window.showAgentsView();
+  const box = ctx.document.getElementById('agents-group-worktrees');
+  assert.equal(box.checked, true);
+  assert.equal(box.disabled, false);
+  assert.deepEqual(listLayout(ctx), ['# app · 2', '## main · 1', 'on-main', '## x · 1', 'in-wt', '# other · 1', 'other-repo']);
+  const subs = [...ctx.document.querySelectorAll('.agents-subgroup-header')];
+  assert.deepEqual(subs.map(h => h.getAttribute('title')), [APP, APP + '/.claude/worktrees/x']);
+  assert.equal(ctx.document.querySelectorAll('.agents-row').length, 3);
+  assert.equal(ctx.document.querySelectorAll('.agents-row.agents-row--nested').length, 2);
+  ctx.document.querySelector('.agents-row[data-key="bg:a2aaaaaa"]').click();
+  toggleWorktrees(ctx, false);
+  assert.equal(ctx.window.localStorage.getItem('agentsGroupWorktrees'), '0');
+  assert.deepEqual(listLayout(ctx), ['# app · 2', 'on-main', 'in-wt', '# other · 1', 'other-repo']);
+  assert.ok(ctx.document.querySelector('.agents-row[data-key="bg:a2aaaaaa"]').classList.contains('selected'));
+  toggleWorktrees(ctx, true);
+  assert.equal(ctx.window.localStorage.getItem('agentsGroupWorktrees'), '1');
+  assert.ok(ctx.document.querySelector('.agents-row[data-key="bg:a2aaaaaa"]').classList.contains('selected'));
+  ctx.document.querySelector('.agents-subgroup-header').click();
+  assert.equal(ctx.read('agentsSelectedKey'), 'bg:a2aaaaaa');
+  const off = setup({ storage: { agentsGroupBy: 'project', agentsGroupWorktrees: '0' } }); t.after(() => off.destroy());
+  assert.equal(off.document.getElementById('agents-group-worktrees').checked, false);
+});
+
+test('the Worktrees option is disabled outside project mode and changes nothing there', async (t) => {
+  const ctx = setup({ storage: {} }); t.after(() => ctx.destroy());
+  ctx.setSnapshot({ roster: APP_ROSTER, daemonReachable: true });
+  await ctx.window.showAgentsView();
+  const box = ctx.document.getElementById('agents-group-worktrees');
+  assert.equal(box.checked, true);
+  assert.equal(box.disabled, true);
+  assert.equal(ctx.document.querySelectorAll('.agents-subgroup-header').length, 0);
+  chooseGroupBy(ctx, 'none');
+  assert.equal(box.disabled, true);
+  chooseGroupBy(ctx, 'project');
+  assert.equal(box.disabled, false);
+  assert.equal(ctx.document.querySelectorAll('.agents-subgroup-header').length, 2);
+});
+
+test('quotes and attribute payloads in a worktree path cannot inject attributes into its sub-header', async (t) => {
+  const ctx = setup({ storage: { agentsGroupBy: 'project' } }); t.after(() => ctx.destroy());
+  const payload = 'x" class="agents-verb-btn" data-verb="stop" y=\'z';
+  const evilWt = APP + '/.claude/worktrees/' + payload;
+  ctx.setSnapshot({ roster: [APP_ROSTER[0], inApp('e1eeeeee', 'evil', evilWt)], daemonReachable: true });
+  await ctx.window.showAgentsView();
+  const head = [...ctx.document.querySelectorAll('.agents-subgroup-header')].find(h => h.getAttribute('title') === evilWt);
+  assert.ok(head);
+  assert.equal(head.className, 'agents-subgroup-header');
+  assert.equal(head.hasAttribute('data-verb'), false);
+  assert.equal(head.hasAttribute('y'), false);
+  assert.equal(headText(head), payload + ' · 1');
+  assert.equal(ctx.document.querySelectorAll('[data-verb]').length, 0);
+});
+
+test('the worktree sub-header is smaller than the project header and distinct from rows', () => {
+  const css = fs.readFileSync(path.join(PUBLIC, 'style.css'), 'utf8');
+  const m = css.match(/(^|\n)\.agents-subgroup-header\s*\{([^}]*)\}/);
+  assert.ok(m, 'a .agents-subgroup-header rule');
+  const size = m[2].match(/font-size:\s*([\d.]+)em/);
+  assert.ok(size && Number(size[1]) < 1.2 && Number(size[1]) >= 1, 'between the rows and the project header');
+  assert.match(m[2], /font-weight:\s*600/);
+  assert.match(m[2], /padding:[^;]*\d+px/);
+  const html = fs.readFileSync(path.join(PUBLIC, 'index.html'), 'utf8');
+  assert.match(html, /id="agents-group-worktrees" checked/);
+  assert.match(html, /title="Sub-group each project by worktree"/);
+});
+
+test('hiding a view that is not open leaves the persisted flag untouched', (t) => {
+  const ctx = setup({ storage: { agentsViewActive: '1' } }); t.after(() => ctx.destroy());
+  ctx.window.hideAllViewers();
+  ctx.window.hideAgentsView({ restore: false });
+  ctx.window.hideAgentsView();
+  assert.equal(ctx.window.localStorage.getItem('agentsViewActive'), '1');
+});
+
+test('a view open at the last run is reopened after the startup restore showed a session and the grid', async (t) => {
+  const ctx = setup({ storage: { agentsViewActive: '1' } }); t.after(() => ctx.destroy());
+  ctx.window.hideAgentsView({ restore: false });
+  ctx.window.hideAllViewers();
+  ctx.window.localStorage.setItem('agentsViewActive', '0');
+  await ctx.window.restoreAgentsViewAtStartup();
+  assert.equal(ctx.read('agentsViewActive'), true);
+  assert.equal(ctx.document.getElementById('agents-viewer').style.display, 'flex');
+  assert.equal(ctx.window.localStorage.getItem('agentsViewActive'), '1');
+});
+
+test('a view closed at the last run stays closed after the startup restore', async (t) => {
+  const ctx = setup(); t.after(() => ctx.destroy());
+  await ctx.window.restoreAgentsViewAtStartup();
+  assert.equal(ctx.read('agentsViewActive'), false);
+  assert.equal(ctx.calls.fetches, 0);
+});
+
+test('opening a memory file closes the agents view', async (t) => {
+  const ctx = setup(); t.after(() => ctx.destroy());
+  await ctx.window.showAgentsView();
+  await ctx.window.openMemory({ filePath: '/m/a.md', filename: 'a.md' });
+  assert.equal(ctx.read('agentsViewActive'), false);
+  assert.equal(ctx.document.getElementById('agents-viewer').style.display, 'none');
+  assert.equal(ctx.window.memoryViewer.style.display, 'flex');
+});
+
+test('opening a work file closes the agents view', async (t) => {
+  const ctx = setup(); t.after(() => ctx.destroy());
+  await ctx.window.showAgentsView();
+  await ctx.window.openWorkFile({ filePath: '/w/.work-files/a.md', filename: 'a.md' });
+  assert.equal(ctx.read('agentsViewActive'), false);
+  assert.equal(ctx.document.getElementById('agents-viewer').style.display, 'none');
+  assert.equal(ctx.window.workFilesViewer.style.display, 'flex');
+});
+
+test('opening the settings closes the agents view', async (t) => {
+  const ctx = setup({ settingsPanel: true }); t.after(() => ctx.destroy());
+  await ctx.window.showAgentsView();
+  await ctx.window.openSettingsViewer('global');
+  assert.equal(ctx.read('agentsViewActive'), false);
+  assert.equal(ctx.document.getElementById('agents-viewer').style.display, 'none');
+  assert.equal(ctx.window.settingsViewer.style.display, 'flex');
+});
+
+test('quotes in a name, cwd or href cannot inject attributes into the rows or the detail', async (t) => {
+  const ctx = setup(); t.after(() => ctx.destroy());
+  const payload = 'x" class="agents-verb-btn" data-verb="stop" y=\'z';
+  const evil = { ...ROSTER[1], id: 'cccccccc', name: payload, cwd: '/w/' + payload, children: [{ id: 'c', href: 'https://e.example/' + payload, kind: 'mr' }] };
+  ctx.setSnapshot({ roster: [evil], daemonReachable: true });
+  await ctx.window.showAgentsView();
+  const row = ctx.document.querySelector('.agents-row[data-key="bg:cccccccc"]');
+  assert.ok(row);
+  const cwdEl = row.querySelector('.agents-row-cwd');
+  assert.equal(cwdEl.getAttribute('title'), '/w/' + payload);
+  assert.equal(cwdEl.hasAttribute('data-verb'), false);
+  assert.equal(cwdEl.className, 'agents-row-cwd');
+  row.click();
+  const detail = ctx.document.getElementById('agents-detail');
+  const link = detail.querySelector('.agents-link');
+  assert.equal(link.getAttribute('data-href'), 'https://e.example/' + payload);
+  assert.equal(link.hasAttribute('data-verb'), false);
+  assert.equal(link.className, 'agents-link');
+  assert.equal(ctx.document.querySelectorAll('[data-verb="stop"]').length, 1);
+  assert.equal(ctx.document.querySelectorAll('.agents-verb-btn').length, 5);
+});
+
+test('a quote in a session id round-trips through the row key without injecting an attribute', async (t) => {
+  const ctx = setup(); t.after(() => ctx.destroy());
+  const sid = 'a" data-verb="stop';
+  ctx.setSnapshot({ roster: [{ ...ROSTER[2], sessionId: sid }], daemonReachable: true });
+  await ctx.window.showAgentsView();
+  const row = ctx.document.querySelector('.agents-row');
+  assert.equal(row.getAttribute('data-key'), 'int:' + sid);
+  assert.equal(row.hasAttribute('data-verb'), false);
+});
+
+test('the header wraps its controls so New agent stays reachable at narrow widths', () => {
+  const css = fs.readFileSync(path.join(PUBLIC, 'style.css'), 'utf8');
+  const header = css.match(/(^|\n)#agents-viewer-header\s*\{([^}]*)\}/);
+  assert.ok(header, 'a #agents-viewer-header rule');
+  assert.match(header[2], /flex-wrap:\s*wrap/);
+  const btn = css.match(/(^|\n)#agents-new-btn\s*\{([^}]*)\}/);
+  assert.ok(btn, 'a #agents-new-btn rule of its own');
+  assert.match(btn[2], /flex-shrink:\s*0/);
+  const main = css.match(/(^|\n)#main\s*\{([^}]*)\}/);
+  assert.ok(main, 'a #main rule');
+  assert.match(main[2], /min-width:\s*0/, 'the rows\' minimum width must not push #main past the window');
+});
+
+test('the header keeps its right end out from under the window controls', () => {
+  const css = fs.readFileSync(path.join(PUBLIC, 'style.css'), 'utf8');
+  const rules = [...css.matchAll(/body\.window-frameless[^{]*:is\(([^)]*)\)\s*\{([^}]*)\}/g)];
+  const right = rules.find(m => /strip-inset-right/.test(m[2]));
+  assert.ok(right, 'the rule that pads the headers by --strip-inset-right');
+  assert.match(right[1], /#agents-viewer-header/);
+  const left = rules.find(m => /strip-inset-left/.test(m[2]));
+  assert.ok(left, 'the rule that pads the headers by --strip-inset-left');
+  assert.match(left[1], /#agents-viewer-header/);
+  const noDrag = css.match(/body\.window-frameless :is\([^{]*#agents-viewer-header label[^{]*\{([^}]*)\}/);
+  assert.ok(noDrag, 'a no-drag rule that covers the header labels');
+  assert.match(noDrag[1], /app-region:\s*no-drag/);
+});
+
+const dblclick = (ctx, el) => el.dispatchEvent(new ctx.window.MouseEvent('dblclick', { bubbles: true }));
+
+test('a double click on a working or blocked row attaches, with the same options as the Attach button', async (t) => {
+  const ctx = setup(); t.after(() => ctx.destroy());
+  const blocked = { ...ROSTER[0], id: 'dddddddd', sessionId: 's-d', name: 'waits', state: 'blocked', cwd: '/w/d' };
+  ctx.setSnapshot({ roster: [...ROSTER, blocked], daemonReachable: true });
+  await ctx.window.showAgentsView();
+  dblclick(ctx, ctx.document.querySelector('.agents-row[data-key="bg:aaaaaaaa"]'));
+  assert.equal(ctx.calls.opened.length, 1);
+  assert.equal(ctx.calls.opened[0][0].sessionId, 's-a');
+  assert.deepEqual({ ...ctx.calls.opened[0][1] }, { type: 'attach', jobId: 'aaaaaaaa', cwd: '/w/em' });
+  dblclick(ctx, ctx.document.querySelector('.agents-row[data-key="bg:dddddddd"] .agents-row-state'));
+  assert.equal(ctx.calls.opened.length, 2, 'a double click on a cell of the row counts too');
+  assert.deepEqual({ ...ctx.calls.opened[1][1] }, { type: 'attach', jobId: 'dddddddd', cwd: '/w/d' });
+});
+
+test('a double click does nothing on a finished row, an external session, a header or a button', async (t) => {
+  const ctx = setup({ storage: {} }); t.after(() => ctx.destroy());
+  ctx.setSnapshot({ roster: ROSTER, daemonReachable: true });
+  await ctx.window.showAgentsView();
+  dblclick(ctx, ctx.document.querySelector('.agents-row[data-key="bg:bbbbbbbb"]'));
+  dblclick(ctx, ctx.document.querySelector('.agents-row[data-key="int:s-i"]'));
+  dblclick(ctx, ctx.document.querySelector('.agents-group-header'));
+  ctx.document.querySelector('.agents-row[data-key="bg:aaaaaaaa"]').click();
+  dblclick(ctx, ctx.document.querySelector('#agents-detail [data-verb="transcript"]'));
+  assert.equal(ctx.calls.opened.length, 0);
+});
+
+test('a double click does not attach while the daemon is not answering', async (t) => {
+  const ctx = setup(); t.after(() => ctx.destroy());
+  ctx.setSnapshot({ roster: ROSTER, daemonReachable: false });
+  await ctx.window.showAgentsView();
+  dblclick(ctx, ctx.document.querySelector('.agents-row[data-key="bg:aaaaaaaa"]'));
+  assert.equal(ctx.calls.opened.length, 0);
+});
diff --git a/test/dom-dispatch-dialog.test.js b/test/dom-dispatch-dialog.test.js
new file mode 100644
index 00000000..408bd3be
--- /dev/null
+++ b/test/dom-dispatch-dialog.test.js
@@ -0,0 +1,150 @@
+// test/dom-dispatch-dialog.test.js — the fields become exactly the dispatch payload. See .ai/contexts/bg-agents.md.
+'use strict';
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const vm = require('node:vm');
+const { JSDOM } = require('jsdom');
+
+const PUBLIC = path.join(__dirname, '..', 'public');
+const tick = () => new Promise(r => setTimeout(r, 0));
+
+function setup({ dispatchResult = { ok: true, id: 'cccccccc' }, projects, effective = { permissionMode: 'auto', addDirs: '' } } = {}) {
+  const dom = new JSDOM('<!DOCTYPE html><html><body></body></html>', { url: 'http://localhost/', runScripts: 'outside-only', pretendToBeVisual: true });
+  const { window } = dom;
+  const calls = { dispatched: [], selected: [] };
+  window.api = {
+    platform: 'linux',
+    getEffectiveSettings: async () => effective,
+    dispatchBgAgent: async (fields) => { calls.dispatched.push(fields); return dispatchResult; },
+  };
+  const g = {
+    cachedAllProjects: projects || [{ projectPath: '/w/one' }, { projectPath: '/w/two' }],
+    selectAgentsRow: (id) => calls.selected.push(id),
+    launchNewSession: () => {}, cachedProjects: [], sessionMap: new Map(), pendingSessions: new Map(),
+    openSessions: new Map(), activePtyIds: new Set(), refreshSidebar: () => {}, pollActiveSessions: () => {},
+  };
+  for (const [k, v] of Object.entries(g)) Object.defineProperty(window, k, { value: v, writable: true, configurable: true });
+  for (const f of ['setting-defaults.js', 'utils.js', 'icons.js', 'dialogs.js']) {
+    vm.runInContext(fs.readFileSync(path.join(PUBLIC, f), 'utf8'), dom.getInternalVMContext(), { filename: f });
+  }
+  return { window, document: window.document, calls, destroy: () => window.close() };
+}
+
+test('Start sends the trimmed fields with the chosen project and mode, then selects the new row', async (t) => {
+  const ctx = setup(); t.after(ctx.destroy);
+  await ctx.window.showDispatchAgentDialog({ projectPath: '/w/two' });
+  const d = ctx.document;
+  assert.equal(d.querySelector('#dad-project').value, '/w/two', 'the given project is preselected');
+  d.querySelector('#dad-prompt').value = '  review the backlog  ';
+  d.querySelector('#dad-name').value = 'em-1';
+  d.querySelector('#dad-agent').value = 'fleet:em';
+  d.querySelector('#dad-add-dirs').value = '/srv/a';
+  d.querySelector('.permission-option[data-mode="plan"]').click();
+  d.querySelector('.new-session-start-btn').click();
+  await tick(); await tick();
+  assert.deepEqual(JSON.parse(JSON.stringify(ctx.calls.dispatched)), [{ prompt: 'review the backlog', name: 'em-1', agent: 'fleet:em', cwd: '/w/two', permissionMode: 'plan', dangerouslySkipPermissions: false, addDirs: '/srv/a' }]);
+  assert.deepEqual(ctx.calls.selected, ['cccccccc']);
+  assert.equal(d.querySelector('.new-session-overlay'), null, 'the dialog closed');
+});
+
+test('an empty prompt never reaches main, and a failed dispatch keeps the dialog open with the error', async (t) => {
+  const ctx = setup({ dispatchResult: { ok: false, error: 'daemon said no' } }); t.after(ctx.destroy);
+  await ctx.window.showDispatchAgentDialog(null);
+  const d = ctx.document;
+  d.querySelector('.new-session-start-btn').click();
+  await tick();
+  assert.equal(ctx.calls.dispatched.length, 0);
+  assert.match(d.querySelector('#dad-error').textContent, /prompt/);
+  d.querySelector('#dad-prompt').value = 'go';
+  d.querySelector('.new-session-start-btn').click();
+  await tick(); await tick();
+  assert.equal(ctx.calls.dispatched.length, 1);
+  assert.equal(ctx.calls.dispatched[0].cwd, '/w/one', 'first project by default');
+  assert.match(d.querySelector('#dad-error').textContent, /daemon said no/);
+  assert.ok(d.querySelector('.new-session-overlay'), 'still open');
+});
+
+test('Enter inside the prompt does not start; Escape closes', async (t) => {
+  const ctx = setup(); t.after(ctx.destroy);
+  await ctx.window.showDispatchAgentDialog(null);
+  const d = ctx.document;
+  const prompt = d.querySelector('#dad-prompt');
+  prompt.value = 'x';
+  prompt.dispatchEvent(new ctx.window.KeyboardEvent('keydown', { key: 'Enter', bubbles: true }));
+  await tick();
+  assert.equal(ctx.calls.dispatched.length, 0);
+  d.dispatchEvent(new ctx.window.KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+  assert.equal(d.querySelector('.new-session-overlay'), null);
+});
+
+test('Enter on a focused button is left to the button: Enter on Cancel never starts; Enter elsewhere does', async (t) => {
+  const ctx = setup(); t.after(ctx.destroy);
+  await ctx.window.showDispatchAgentDialog(null);
+  const d = ctx.document;
+  d.querySelector('#dad-prompt').value = 'go';
+  d.querySelector('.new-session-cancel-btn').dispatchEvent(new ctx.window.KeyboardEvent('keydown', { key: 'Enter', bubbles: true }));
+  await tick(); await tick();
+  assert.equal(ctx.calls.dispatched.length, 0);
+  d.body.dispatchEvent(new ctx.window.KeyboardEvent('keydown', { key: 'Enter', bubbles: true }));
+  await tick(); await tick();
+  assert.equal(ctx.calls.dispatched.length, 1);
+});
+
+test('main refusing a prompt that starts with "-" is shown inline, the dialog stays open', async (t) => {
+  const ctx = setup({ dispatchResult: { ok: false, error: 'a prompt starting with "-" would be read as a flag' } }); t.after(ctx.destroy);
+  await ctx.window.showDispatchAgentDialog(null);
+  const d = ctx.document;
+  d.querySelector('#dad-prompt').value = '--help';
+  d.querySelector('.new-session-start-btn').click();
+  await tick(); await tick();
+  assert.equal(ctx.calls.dispatched[0].prompt, '--help');
+  assert.match(d.querySelector('#dad-error').textContent, /starting with "-"/);
+  assert.ok(d.querySelector('.new-session-overlay'), 'still open');
+  assert.equal(d.querySelector('.new-session-start-btn').disabled, false, 'Start usable again');
+});
+
+test('ok:true with a null id is a success: the dialog closes and no row is selected', async (t) => {
+  const ctx = setup({ dispatchResult: { ok: true, id: null } }); t.after(ctx.destroy);
+  await ctx.window.showDispatchAgentDialog(null);
+  const d = ctx.document;
+  d.querySelector('#dad-prompt').value = 'go';
+  d.querySelector('.new-session-start-btn').click();
+  await tick(); await tick();
+  assert.equal(ctx.calls.dispatched.length, 1);
+  assert.equal(d.querySelector('.new-session-overlay'), null, 'the dialog closed');
+  assert.equal(d.querySelector('#dad-error'), null);
+  assert.deepEqual(ctx.calls.selected, []);
+});
+
+test('a project path and add-dirs holding quotes and markup reach dispatch intact', async (t) => {
+  const odd = '/w/a"b\' onmouseover="x<img>';
+  const dirs = '/srv/"q" <b>';
+  const ctx = setup({ projects: [{ projectPath: odd }], effective: { addDirs: dirs } }); t.after(ctx.destroy);
+  await ctx.window.showDispatchAgentDialog(null);
+  const d = ctx.document;
+  const select = d.querySelector('#dad-project');
+  assert.equal(select.options.length, 1);
+  assert.equal(select.value, odd);
+  assert.equal(select.options[0].getAttribute('onmouseover'), null, 'no attribute injected');
+  assert.equal(d.querySelector('img'), null, 'no markup injected');
+  assert.equal(d.querySelector('#dad-add-dirs').value, dirs);
+  d.querySelector('#dad-prompt').value = 'go';
+  d.querySelector('.new-session-start-btn').click();
+  await tick(); await tick();
+  assert.equal(ctx.calls.dispatched[0].cwd, odd);
+  assert.equal(ctx.calls.dispatched[0].addDirs, dirs.trim());
+});
+
+test('the dialog scrolls inside the window when it is taller than the screen', async (t) => {
+  const ctx = setup(); t.after(ctx.destroy);
+  await ctx.window.showDispatchAgentDialog(null);
+  const dialog = ctx.document.querySelector('.new-session-dialog');
+  assert.ok(dialog.classList.contains('dispatch-agent-dialog'), 'the dialog carries its own class');
+  const css = fs.readFileSync(path.join(PUBLIC, 'style.css'), 'utf8');
+  const rule = css.match(/\.new-session-dialog\.dispatch-agent-dialog\s*\{([^}]*)\}/);
+  assert.ok(rule, 'a rule scoped to the dispatch dialog');
+  assert.match(rule[1], /max-height:\s*calc\(100vh\s*-\s*\d+px\)/);
+  assert.match(rule[1], /overflow-y:\s*auto/);
+});
diff --git a/test/dom-setup.js b/test/dom-setup.js
index 31a9f276..e3e798ab 100644
--- a/test/dom-setup.js
+++ b/test/dom-setup.js
@@ -171,6 +171,8 @@ function setupSidebarDom() {
     setActivity: read('setActivity'),
     // remote-activity-ui.js's per-session adapter state (const, not a window property — see .ai/contexts/session-state.md).
     remoteSessionStates: read('remoteSessionStates'),
+    read,
+    evalPublic(name) { evalInWindow(dom, path.join(PUBLIC_DIR, name)); },
     // Simulate the main process emitting subagent-spawned/subagent-completed
     // (session-transitions.js) by invoking the callback sidebar.js registered
     // via window.api.onSubagentSpawned/onSubagentCompleted at eval time.
diff --git a/test/dom-sidebar-bg-badge.test.js b/test/dom-sidebar-bg-badge.test.js
new file mode 100644
index 00000000..0f847752
--- /dev/null
+++ b/test/dom-sidebar-bg-badge.test.js
@@ -0,0 +1,41 @@
+'use strict';
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { setupSidebarDom, makeSampleProject } = require('./dom-setup');
+
+test('a row whose session id is in bgAgentSessionIds shows the bg badge; the others do not', (t) => {
+  const ctx = setupSidebarDom();
+  t.after(() => ctx.destroy());
+  Object.defineProperty(ctx.window, 'bgAgentSessionIds', { value: new Set(['s-top-1']), writable: true, configurable: true });
+  const project = makeSampleProject();
+  ctx.sidebar.renderProjects([project], false);
+  const badged = ctx.document.querySelector('[data-session-id="s-top-1"] .bg-badge');
+  assert.ok(badged, 'the badge is there');
+  assert.equal(badged.textContent, 'bg');
+  assert.equal(ctx.document.querySelector('[data-session-id="s-top-2"] .bg-badge'), null);
+});
+
+test('a roster snapshot badges only the live jobs: working and blocked, not done or stopped', (t) => {
+  const ctx = setupSidebarDom();
+  t.after(() => ctx.destroy());
+  ctx.evalPublic('agents-view.js');
+  const apply = ctx.read('applyAgentsSnapshot');
+  const project = makeSampleProject();
+  const ids = ['s-top-1', 's-top-2'];
+  const job = (id, sessionId, state) => ({ id, sessionId, kind: 'background', state });
+  apply({ roster: [job('aaaaaaaa', ids[0], 'working'), job('bbbbbbbb', ids[1], 'done')], daemonReachable: true });
+  ctx.sidebar.renderProjects([project], false);
+  assert.ok(ctx.document.querySelector(`[data-session-id="${ids[0]}"] .bg-badge`), 'a working job is badged');
+  assert.equal(ctx.document.querySelector(`[data-session-id="${ids[1]}"] .bg-badge`), null, 'a done job is not');
+  apply({ roster: [job('aaaaaaaa', ids[0], 'stopped'), job('bbbbbbbb', ids[1], 'blocked')], daemonReachable: true });
+  ctx.sidebar.renderProjects([project], false);
+  assert.equal(ctx.document.querySelector(`[data-session-id="${ids[0]}"] .bg-badge`), null, 'a stopped job is not');
+  assert.ok(ctx.document.querySelector(`[data-session-id="${ids[1]}"] .bg-badge`), 'a blocked job is badged');
+});
+
+test('without the roster global the sidebar renders as before', (t) => {
+  const ctx = setupSidebarDom();
+  t.after(() => ctx.destroy());
+  ctx.sidebar.renderProjects([makeSampleProject()], false);
+  assert.equal(ctx.document.querySelector('.bg-badge'), null);
+});
diff --git a/test/open-terminal-attach.test.js b/test/open-terminal-attach.test.js
new file mode 100644
index 00000000..1927990e
--- /dev/null
+++ b/test/open-terminal-attach.test.js
@@ -0,0 +1,52 @@
+// test/open-terminal-attach.test.js — main.js boots Electron, so these are source-level pins; see .ai/contexts/bg-agents.md.
+'use strict';
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const MAIN = fs.readFileSync(path.join(__dirname, '..', 'main.js'), 'utf8');
+const PRELOAD = fs.readFileSync(path.join(__dirname, '..', 'preload.js'), 'utf8');
+
+test('open-terminal builds `claude attach <id>` for an attach session and never a --resume', () => {
+  assert.match(MAIN, /const isAttach = sessionOptions\?\.type === 'attach';/);
+  assert.match(MAIN, /claudeArgs\.push\('attach', attachJobId\);/);
+  assert.match(MAIN, /if \(!isAttach && sessionOptions\?\.sandbox\)/);
+  assert.match(MAIN, /if \(!isAttach && sessionOptions\?\.preLaunchCmd\)/);
+  assert.match(MAIN, /if \(!isAttach && sessionOptions\?\.mcpEmulation !== false\)/);
+  assert.match(MAIN, /isAttach, attachJobId,/, 'the session record must carry both fields');
+});
+
+test('a reattach reports whether the live session is an attach, and the renderer keeps it on the tab', () => {
+  assert.match(MAIN, /ok: true, reattached: true, attach: !!session\.isAttach,/);
+  const APP = fs.readFileSync(path.join(__dirname, '..', 'public', 'app.js'), 'utf8');
+  const start = APP.indexOf('async function openSession(');
+  const body = APP.slice(start, APP.indexOf('\nasync function ', start + 10));
+  const openIdx = body.indexOf('await window.api.openTerminal(sessionId');
+  assert.ok(openIdx > 0);
+  assert.match(body.slice(openIdx), /if \(result\.reattached\) entry\.attach = !!result\.attach;/);
+});
+
+test('an attach job id is validated against the eight-hex shape before anything is spawned', () => {
+  assert.match(MAIN, /JOB_ID_RE\.test\(String\(sessionOptions\.jobId\)\)/);
+});
+
+test('stop-session detaches an attach session instead of killing it', () => {
+  const idx = MAIN.indexOf("ipcMain.handle('stop-session'");
+  const body = MAIN.slice(idx, idx + 600);
+  assert.match(body, /if \(session\.isAttach\)/);
+  assert.match(body, /detachPty\(session, sessionId\)/);
+  assert.match(body, /detached: true/);
+});
+
+test('the window closing releases the agents watchers', () => {
+  const idx = MAIN.indexOf("mainWindow.on('closed'");
+  assert.match(MAIN.slice(idx, idx + 900), /bgAgents\.stop\(\);/);
+});
+
+test('preload exposes the four agents-view entries', () => {
+  for (const name of ['getBgAgents', 'bgAgentVerb', 'dispatchBgAgent', 'onBgAgentsChanged']) {
+    assert.ok(PRELOAD.includes(name + ':'), `${name} missing from preload.js`);
+  }
+  assert.match(PRELOAD, /ipcRenderer\.on\('bg-agents-changed'/);
+});
diff --git a/test/project-root.test.js b/test/project-root.test.js
new file mode 100644
index 00000000..f7b3611e
--- /dev/null
+++ b/test/project-root.test.js
@@ -0,0 +1,120 @@
+// see .ai/contexts/bg-agents.md
+'use strict';
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const {
+  projectRootFromPattern, worktreeRootFromPattern, rootFromCommonDir, resolveProjectRoots, gitEnv, GIT_TIMEOUT_MS,
+} = require('../project-root');
+
+test('pattern: a cwd under <root>/.claude/worktrees/<name> resolves to <root>, any separator, nested, trailing slash', () => {
+  assert.equal(projectRootFromPattern('/home/u/repo/.claude/worktrees/feat'), '/home/u/repo');
+  assert.equal(projectRootFromPattern('/home/u/repo/.claude/worktrees/feat/'), '/home/u/repo');
+  assert.equal(projectRootFromPattern('/home/u/repo/.claude/worktrees/feat/src/lib'), '/home/u/repo');
+  assert.equal(projectRootFromPattern('C:\\code\\repo\\.claude\\worktrees\\feat'), 'C:\\code\\repo');
+  assert.equal(projectRootFromPattern('C:\\code\\repo\\.claude\\worktrees\\feat\\sub'), 'C:\\code\\repo');
+  assert.equal(projectRootFromPattern('/a/repo/.claude/worktrees/x/.claude/worktrees/y'), '/a/repo');
+});
+
+test('pattern: the worktree root is <root>/.claude/worktrees/<name>, whatever subdirectory the cwd is in', () => {
+  assert.equal(worktreeRootFromPattern('/home/u/repo/.claude/worktrees/feat'), '/home/u/repo/.claude/worktrees/feat');
+  assert.equal(worktreeRootFromPattern('/home/u/repo/.claude/worktrees/feat/'), '/home/u/repo/.claude/worktrees/feat');
+  assert.equal(worktreeRootFromPattern('/home/u/repo/.claude/worktrees/feat/src/lib'), '/home/u/repo/.claude/worktrees/feat');
+  assert.equal(worktreeRootFromPattern('C:\\code\\repo\\.claude\\worktrees\\feat\\sub'), 'C:\\code\\repo\\.claude\\worktrees\\feat');
+  assert.equal(worktreeRootFromPattern('/a/repo/.claude/worktrees/x/.claude/worktrees/y'), '/a/repo/.claude/worktrees/x');
+  assert.equal(worktreeRootFromPattern('/home/u/repo'), null);
+});
+
+test('pattern: anything else is not a match', () => {
+  assert.equal(projectRootFromPattern('/home/u/worktrees/feat'), null);
+  assert.equal(projectRootFromPattern('/home/u/repo/.worktrees/feat'), null);
+  assert.equal(projectRootFromPattern('/home/u/repo/claude/worktrees/feat'), null);
+  assert.equal(projectRootFromPattern('/home/u/repo/.claude/worktrees'), null);
+  assert.equal(projectRootFromPattern('/home/u/repo/.claude/worktrees/'), null);
+  assert.equal(projectRootFromPattern('/home/u/repo'), null);
+  assert.equal(projectRootFromPattern(''), null);
+  assert.equal(projectRootFromPattern(null), null);
+  assert.equal(worktreeRootFromPattern('/home/u/worktrees/feat'), null);
+});
+
+test('common dir: <root>/.git gives <root>; a bare repo or a submodule module dir gives null', () => {
+  assert.equal(rootFromCommonDir('/home/u/repo/.git'), '/home/u/repo');
+  assert.equal(rootFromCommonDir('/home/u/repo.git'), null);
+  assert.equal(rootFromCommonDir('/home/u/super/.git/modules/sub'), null);
+  assert.equal(rootFromCommonDir(''), null);
+});
+
+test('git env: GIT_* variables of the caller are dropped', () => {
+  const env = gitEnv({ PATH: '/bin', GIT_DIR: '/x/.git', GIT_INDEX_FILE: '/x/.git/index', HOME: '/h' });
+  assert.deepEqual(env, { PATH: '/bin', HOME: '/h' });
+});
+
+function hasGit() {
+  try { execFileSync('git', ['--version'], { stdio: 'ignore' }); return true; } catch { return false; }
+}
+
+function git(cwd, args) {
+  execFileSync('git', ['-c', 'user.email=t@t', '-c', 'user.name=t', '-c', 'init.defaultBranch=main', ...args],
+    { cwd, stdio: 'ignore', env: gitEnv(process.env) });
+}
+
+test('a real repo: main checkout, subdirectories and `git worktree add` directories resolve to the main root and their own worktree', async (t) => {
+  if (!hasGit()) { t.skip('git not available'); return; }
+  const tmp = fs.realpathSync.native(fs.mkdtempSync(path.join(os.tmpdir(), 'sw-project-root-')));
+  t.after(() => fs.rmSync(tmp, { recursive: true, force: true }));
+  const repo = path.join(tmp, 'repo');
+  fs.mkdirSync(path.join(repo, 'sub'), { recursive: true });
+  git(repo, ['init', '-q']);
+  git(repo, ['commit', '-q', '--allow-empty', '-m', 'init']);
+  const wt = path.join(tmp, 'elsewhere', 'wt-feat');
+  git(repo, ['worktree', 'add', '-q', wt]);
+  fs.mkdirSync(path.join(wt, 'deep', 'er'), { recursive: true });
+  const claudeWt = path.join(repo, '.claude', 'worktrees', 'agent-x');
+  git(repo, ['worktree', 'add', '-q', claudeWt]);
+  const plain = path.join(tmp, 'plain');
+  fs.mkdirSync(plain);
+  assert.deepEqual(await resolveProjectRoots(repo), { projectRoot: repo, worktreeRoot: repo });
+  assert.deepEqual(await resolveProjectRoots(path.join(repo, 'sub')), { projectRoot: repo, worktreeRoot: repo });
+  assert.deepEqual(await resolveProjectRoots(wt), { projectRoot: repo, worktreeRoot: wt });
+  assert.deepEqual(await resolveProjectRoots(path.join(wt, 'deep', 'er')), { projectRoot: repo, worktreeRoot: wt });
+  assert.deepEqual(await resolveProjectRoots(claudeWt), { projectRoot: repo, worktreeRoot: claudeWt });
+  assert.deepEqual(await resolveProjectRoots(plain), { projectRoot: plain, worktreeRoot: plain });
+});
+
+test('no git call for the pattern, a missing dir or an empty cwd; a failing or throwing runner falls back to the cwd', async () => {
+  const calls = [];
+  const execFile = (cmd, args, opts, cb) => { calls.push(args); cb(new Error('boom'), '', ''); };
+  assert.deepEqual(await resolveProjectRoots('/nope/repo/.claude/worktrees/gone/src', { execFile }),
+    { projectRoot: '/nope/repo', worktreeRoot: '/nope/repo/.claude/worktrees/gone' });
+  assert.deepEqual(await resolveProjectRoots('/nope/does-not-exist', { execFile }),
+    { projectRoot: '/nope/does-not-exist', worktreeRoot: '/nope/does-not-exist' });
+  assert.deepEqual(await resolveProjectRoots(null, { execFile }), { projectRoot: null, worktreeRoot: null });
+  assert.equal(calls.length, 0);
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'sw-project-root-'));
+  try {
+    assert.deepEqual(await resolveProjectRoots(tmp, { execFile }), { projectRoot: tmp, worktreeRoot: tmp });
+    assert.equal(calls.length, 1);
+    const thrower = () => { throw new Error('spawn failed'); };
+    assert.deepEqual(await resolveProjectRoots(tmp, { execFile: thrower }), { projectRoot: tmp, worktreeRoot: tmp });
+    const relative = (cmd, args, opts, cb) => cb(null, '.git\n' + tmp + '\n', '');
+    assert.deepEqual(await resolveProjectRoots(tmp, { execFile: relative }), { projectRoot: tmp, worktreeRoot: tmp });
+    const bare = (cmd, args, opts, cb) => cb(null, '/srv/x.git\n' + tmp + '\n', '');
+    assert.deepEqual(await resolveProjectRoots(tmp, { execFile: bare }), { projectRoot: tmp, worktreeRoot: tmp });
+    const seen = [];
+    const spy = (cmd, args, opts, cb) => { seen.push({ cmd, args, opts }); cb(null, path.join(tmp, '.git') + '\n' + tmp + '\n', ''); };
+    await resolveProjectRoots(tmp, { execFile: spy, env: { GIT_DIR: '/x', PATH: '/bin' } });
+    assert.equal(seen[0].cmd, 'git');
+    assert.deepEqual(seen[0].args, ['-C', tmp, 'rev-parse', '--git-common-dir', '--show-toplevel']);
+    assert.equal(seen[0].opts.cwd, tmp);
+    assert.equal(seen[0].opts.timeout, GIT_TIMEOUT_MS);
+    assert.ok(GIT_TIMEOUT_MS > 0 && GIT_TIMEOUT_MS <= 2000);
+    assert.equal(seen[0].opts.shell, undefined);
+    assert.equal(seen[0].opts.env.GIT_DIR, undefined);
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
diff --git a/test/pty-ops-detach.test.js b/test/pty-ops-detach.test.js
new file mode 100644
index 00000000..1348ab8c
--- /dev/null
+++ b/test/pty-ops-detach.test.js
@@ -0,0 +1,52 @@
+// see .ai/contexts/bg-agents.md
+'use strict';
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { detachPty } = require('../pty-ops');
+
+function fakeSession() {
+  const calls = { writes: [], kills: 0 };
+  const session = { exited: false, pty: { write: (d) => calls.writes.push(d), kill: () => { calls.kills++; } } };
+  return { session, calls };
+}
+
+test('detach writes Ctrl+Z and, when the client exits in time, never kills', () => {
+  const { session, calls } = fakeSession();
+  const timers = [];
+  const ok = detachPty(session, 's1', { graceMs: 2000, schedule: (fn, ms) => { timers.push({ fn, ms }); return { unref() {} }; } });
+  assert.equal(ok, true);
+  assert.deepEqual(calls.writes, ['\x1a']);
+  assert.equal(timers.length, 1);
+  assert.equal(timers[0].ms, 2000);
+  session.exited = true;
+  timers[0].fn();
+  assert.equal(calls.kills, 0);
+});
+
+test('detach kills once the grace period passes with the client still attached', () => {
+  const { session, calls } = fakeSession();
+  const timers = [];
+  detachPty(session, 's1', { schedule: (fn) => { timers.push(fn); return {}; } });
+  timers[0]();
+  assert.equal(calls.kills, 1);
+});
+
+test('detach on a pty that refuses the write falls back to a kill', () => {
+  const calls = { kills: 0 };
+  const session = { exited: false, pty: { write: () => { throw new Error('closed'); }, kill: () => { calls.kills++; } } };
+  const ok = detachPty(session, 's1', { schedule: () => { throw new Error('must not schedule'); } });
+  assert.equal(ok, true);
+  assert.equal(calls.kills, 1);
+});
+
+test('a second detach on the same session neither writes nor arms another timer', () => {
+  const { session, calls } = fakeSession();
+  const timers = [];
+  const schedule = (fn) => { timers.push(fn); return {}; };
+  detachPty(session, 's1', { schedule });
+  detachPty(session, 's1', { schedule });
+  assert.deepEqual(calls.writes, ['\x1a']);
+  assert.equal(timers.length, 1);
+  timers[0]();
+  assert.equal(calls.kills, 1);
+});
diff --git a/test/remote-ssh-spawn-sites.test.js b/test/remote-ssh-spawn-sites.test.js
index 6348aa94..ed417eca 100644
--- a/test/remote-ssh-spawn-sites.test.js
+++ b/test/remote-ssh-spawn-sites.test.js
@@ -32,6 +32,7 @@ const UNRESOLVED_ALLOWED = {
   'main.js': {
     spawnPty: 'node-pty wrapper: the shell of a local session, or the attach adapter\'s resolved ssh',
     runScheduleCommand: 'the shell of the schedule\'s shell profile',
+    runClaudeCommand: 'the shell profile running a local claude command (agents, --bg, stop, respawn, rm)',
   },
   'run-to-exit.js': {
     runToExit: 'exported wrapper; its callers are covered by the program-name test below',
diff --git a/test/resume-guard.test.js b/test/resume-guard.test.js
index 458c2a96..f87ef0c3 100644
--- a/test/resume-guard.test.js
+++ b/test/resume-guard.test.js
@@ -152,3 +152,38 @@ test('index.html loads the guard before app.js, preload exposes the check, main
   assert.match(read('main.js'),
     /ipcMain\.handle\('sessions-live-elsewhere', \(_event, sessionIds\) => cliSessionState\.liveElsewhereMany\(sessionIds, sessionHasPty, ptyPids\)\)/);
 });
+
+// --- Background sessions (see .ai/contexts/bg-agents.md) --------------------
+
+const LIVE_BG = { pid: 346590, cwd: '/w/em', startedAt: 1, kind: 'bg', jobId: 'bc3fd129' };
+
+test('a user click on a session the daemon runs answers "attach", without asking', async () => {
+  const api = makeApi(LIVE_BG);
+  const { confirm, messages } = makeConfirm(false);
+  assert.deepEqual(await guardResume(SESSION, { api, confirm }), { attach: 'bc3fd129', cwd: '/w/em' });
+  assert.equal(messages.length, 0);
+});
+
+test('an automatic resume of a session the daemon runs is still refused', async () => {
+  const api = makeApi(LIVE_BG);
+  const { confirm } = makeConfirm(true);
+  assert.equal(await guardResume(SESSION, { automatic: true, api, confirm }), false);
+});
+
+test('a live bg descriptor without a usable jobId is refused: no resume offer, no attach', async () => {
+  for (const jobId of [null, undefined, '']) {
+    const api = makeApi({ ...LIVE_BG, jobId });
+    const { confirm, messages } = makeConfirm(true);
+    assert.equal(await guardResume(SESSION, { api, confirm }), false);
+    assert.equal(messages.length, 0);
+  }
+});
+
+test('app.js turns the attach verdict into attach options and skips the guard for an explicit attach', () => {
+  const app = read('public/app.js');
+  assert.match(app, /customOptions\?\.type === 'attach'\s*\?\s*true\s*:\s*await guardResume\(/);
+  assert.match(app, /if \(verdict === false\) return false;/);
+  assert.match(app, /customOptions = \{ type: 'attach', jobId: verdict\.attach, cwd: verdict\.cwd \|\| projectPath \};/);
+  assert.match(app, /entry\.attach = resumeOptions\.type === 'attach';/);
+  assert.match(app, /if \(entry\.attach\) continue; \/\/ attach tabs are not restored/);
+});
diff --git a/test/stop-session-ui-attach.test.js b/test/stop-session-ui-attach.test.js
new file mode 100644
index 00000000..5f38488b
--- /dev/null
+++ b/test/stop-session-ui-attach.test.js
@@ -0,0 +1,14 @@
+'use strict';
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { resolveSessionStop } = require('../public/stop-session-ui');
+
+test('an attach tab asks to detach, not to stop, and stays local', () => {
+  const plan = resolveSessionStop({ sessionId: 's' }, { attach: true });
+  assert.equal(plan.remote, false);
+  assert.equal(plan.attach, true);
+  assert.match(plan.confirmText, /Detach/);
+  assert.match(plan.confirmText, /keeps running/);
+  assert.equal(resolveSessionStop({ sessionId: 's' }).attach, false);
+  assert.equal(resolveSessionStop({ sessionId: 's', remoteAlias: 'h' }, { attach: true }).remote, true);
+});
diff --git a/test/stop-session-ui.test.js b/test/stop-session-ui.test.js
index e3ac224c..d9da6abc 100644
--- a/test/stop-session-ui.test.js
+++ b/test/stop-session-ui.test.js
@@ -11,12 +11,12 @@ const { resolveSessionStop, isRemoteSessionAlive } = require('../public/stop-ses
 
 test('a local session (no remoteAlias) resolves to the plain stop dialog and the local IPC', () => {
   const plan = resolveSessionStop({ sessionId: 's1' });
-  assert.deepEqual(plan, { remote: false, alias: null, confirmText: 'Stop this session?' });
+  assert.deepEqual(plan, { remote: false, alias: null, attach: false, confirmText: 'Stop this session?' });
 });
 
 test('an undefined session (row not found) still resolves to the local stop, never throws', () => {
   const plan = resolveSessionStop(undefined);
-  assert.deepEqual(plan, { remote: false, alias: null, confirmText: 'Stop this session?' });
+  assert.deepEqual(plan, { remote: false, alias: null, attach: false, confirmText: 'Stop this session?' });
 });
 
 test('a remote session resolves to the remote IPC with the host alias named in the dialog text', () => {