@oar-sh/oar 0.9.11 → 0.9.12

package/CHANGELOG.md

@@ -3,6 +3,132 @@
 All notable changes to OAR are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow semver.
 
+## [0.9.12] — 2026-10-18
+
+Highlights: a background command or monitor in the task panel opens a
+console with its output, live, in colour and with secrets blanked, paging
+back through the whole log and with its own **Stop**. Task rows say when a
+task has gone quiet ("no output for 12 min", amber after a time you set in
+Settings) and show a **✓ 412 ✘ 2** chip when the output is a test run;
+sub-agent rows count their steps, and agents read a task's output on a
+paired relay with `remote_relay` `read_task_output`. Long conversations open
+and page back fast, and switching away and back, or reloading, returns to
+the message you were reading, older pages included; new messages wait below
+a place far up the history instead of skipping the ones in between.
+
+### Upgrade notes
+
+- Migration 0017 (two indexes for the history of long conversations) runs by
+  itself on the first start. The Node.js requirement is unchanged (22.13 or
+  newer), and no setting or config key needs changing.
+- Two new settings in **Settings › General**: **Mark a background task as
+  quiet after** (10 minutes by default, for the relay) and **Messages kept
+  per conversation for switching back** (200 by default, per browser).
+- **Claude background commands may run for 2 hours** before Claude Code
+  stops them, and up to 8 hours when Claude asks; **Settings › Providers ›
+  Claude** sets the limit. OAR now sets `BASH_DEFAULT_TIMEOUT_MS`, `BASH_MAX_TIMEOUT_MS` and
+  `CLAUDE_CODE_AUTO_BACKGROUND_TIMEOUT_MS` for the Claude sessions it starts,
+  so values of these in the relay's environment no longer apply. Commands
+  that start with `sleep`, and sub-agents' commands, are not moved to the
+  background after 2 minutes and may block a turn up to the limit.
+
+### Added
+
+- **Click a background command to watch its output.** A backgrounded shell
+  command or monitor in the composer's task panel opens a console: the last
+  2,000 lines, following live, with **Load earlier** paging back through the
+  whole log (about 5 MB at most). Progress-bar redraws collapse to their last
+  state, repeated lines fold into one with ×N, colours are kept and other
+  control codes dropped, secrets are blanked, and the console has its own
+  **Stop**. A finished command keeps a dimmed ✓/✘ row for an hour so a failed
+  run can still be read. Claude reads the file its CLI writes for the command,
+  Copilot a detached shell's log or an attached shell's recent output, and
+  Grok now lists its terminals as tasks. A session started before this
+  release names no output file; its console says so and that a restart of
+  the session helps.
+- **Task rows say when a task has gone quiet** ("no output for 12 min", amber
+  after **Settings › General › Mark a background task as quiet after**, 10
+  minutes by default) and show a **✓ 412 ✘ 2** chip when the output is a
+  vitest, Playwright, node:test, jest, pytest or turbo run (also through
+  pnpm); the console header's chip jumps to the first failure, and a run
+  that ends shows its final counts within a moment.
+- **Sub-agent rows in the task panel show their step count** ("22 steps"), as
+  the rows in the reply already did.
+- **Settings › Providers › Claude › Claude background command limit** (30
+  minutes to 8 hours, 2 hours by default) sets how long a command Claude runs
+  in the background may take before Claude Code stops it, when Claude gives it
+  no timeout of its own; Claude may still ask for up to 8 hours for one
+  command. A foreground command moves to the background after 2 minutes, so
+  the turn goes on while it runs. Claude is also told to write the output of
+  long runs to a log file instead of piping it into `tail`, and to start runs
+  that must survive a session restart with `nohup`. A change applies to Claude
+  sessions started afterwards; Claude Cloud is not affected.
+- **`remote_relay` action `read_task_output`** gives agents the same tail,
+  quiet time and counts of a task on a relay they may read; `read_session`
+  lists the task ids with that health.
+
+### Changed
+
+- **Long conversations open and scroll back fast.** A history page used to
+  load and prepare every message of the conversation, so a chat with a few
+  thousand messages took about two seconds per page and per live refresh. The
+  relay now reads only the requested page from the database (migration 0017
+  adds the indexes for it), so a page loads in well under a tenth of a second
+  however long the conversation is.
+- Switching back to a conversation already viewed in this tab draws it at
+  once from what the page kept of it; the relay's fresh answer is merged into
+  it when it arrives.
+- **Settings › General › Messages kept per conversation for switching back**
+  (200 by default, 100 to 1,000 or no limit, saved in this browser) sets how
+  many loaded messages each of the last eight conversations keeps.
+- **The conversation list shows activity by the title's colour.** The three
+  animated dots after a working session's title are gone: a ready session
+  that runs a turn or background work keeps the bright green title, an idle
+  one turns a darker green (a muted green in the light theme), and the chat
+  header follows the same rule. Question, error, offline and archived titles
+  keep their colours.
+- The npm package guard allows 7.5 MiB unpacked and 510 entries (was 7.25
+  MiB and 490); the task console, the transcript's handling of new
+  messages below a place far up the history, the Copilot task report and the
+  Claude background command limit grew the server and the app to about 7.37
+  MiB and 505 entries.
+
+### Fixed
+
+- **Copilot background tasks report how they ended.** Finished shells and
+  sub-agents of Copilot's SDK engine showed the status *unknown* and no exit
+  code, in the task data agents read and wherever the end is shown. The
+  worker now reports completed, failed or cancelled, a shell's exit code, and
+  a sub-agent's result (or its error) as its summary; a passing status line
+  such as *Thinking…* is no longer kept as the final summary.
+- **Cancel on a usage-limit pause removes the relay's held follow-up from the
+  open conversation at once.** The *Automatic message from OAR* row was
+  deleted on the relay but stayed on the page, and in what the page kept for
+  switching back, until a reload. A row deleted while you were elsewhere
+  leaves too, also when it was the conversation's newest.
+
+- **Switching away from a long conversation and back keeps your place.** After
+  loading older messages and scrolling back into them, a switch to another
+  conversation and back lost the reading position: with more than 100 messages
+  loaded the oldest were dropped, and messages written meanwhile moved the view
+  by as many rows. The page now remembers the message you were reading and
+  keeps the loaded messages, so you come back to the same message at the same
+  place, older pages included; after a reload it opens at that message too.
+- **New messages no longer skip the ones in between while you read far up.**
+  Opened at a pin, a search result or the place you were reading after a
+  reload, a conversation shows the messages around it. A message or reply that
+  arrived then was put right under them, and the messages between were never
+  loaded when you scrolled down, only the jump-to-bottom button brought them.
+  Now new messages wait: the button counts them, and scrolling down loads
+  every message in between, in order, before them. A reply still being
+  written shows once you are there. A message you send from there takes you
+  to the end, where it, its reply and everything in between show.
+- **Images that load late no longer push the message you are reading down.**
+  In a browser without scroll anchoring (Safari, for one), pictures above
+  your place that arrived after a switch back, a reload or an older page moved
+  the text by their height. The transcript now holds your place while they
+  load, and lets go as soon as you scroll.
+
 ## [0.9.11] — 2026-10-17
 
 Highlights: sessions an agent starts now sit in a group under the session

package/README.md

@@ -45,29 +45,29 @@ flowchart LR
 <table>
 <tr>
 <td width="42%" rowspan="4" valign="top">
-<a href="https://oar.sh/assets/shots/cfmail-mobile.png?v=0.9.11"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-mobile.light.png?v=0.9.11"><img src="https://oar.sh/assets/shots/cfmail-mobile.png?v=0.9.11" alt="OAR on a phone: a finished agent turn in a conversation, with the composer below"></picture></a>
+<a href="https://oar.sh/assets/shots/cfmail-mobile.png?v=0.9.12"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-mobile.light.png?v=0.9.12"><img src="https://oar.sh/assets/shots/cfmail-mobile.png?v=0.9.12" alt="OAR on a phone: a finished agent turn in a conversation, with the composer below"></picture></a>
 <br><sub>On a phone: the same conversations, installable as an app.</sub>
 </td>
 <td width="58%" valign="top">
-<a href="https://oar.sh/assets/shots/cfmail-agents.png?v=0.9.11"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-agents.light.png?v=0.9.11"><img src="https://oar.sh/assets/shots/cfmail-agents.png?v=0.9.11" alt="Background subagents running in parallel in the task panel, each with live token counts, elapsed time, and its own Stop button"></picture></a>
+<a href="https://oar.sh/assets/shots/cfmail-agents.png?v=0.9.12"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-agents.light.png?v=0.9.12"><img src="https://oar.sh/assets/shots/cfmail-agents.png?v=0.9.12" alt="Background subagents running in parallel in the task panel, each with live token counts, elapsed time, and its own Stop button"></picture></a>
 <br><sub>Agents working in parallel, each with live token counts and its own Stop.</sub>
 </td>
 </tr>
 <tr>
 <td valign="top">
-<a href="https://oar.sh/assets/shots/cfmail-question.png?v=0.9.11"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-question.light.png?v=0.9.11"><img src="https://oar.sh/assets/shots/cfmail-question.png?v=0.9.11" alt="A question card in the middle of a turn: the agent offers several choices and a free-text reply"></picture></a>
+<a href="https://oar.sh/assets/shots/cfmail-question.png?v=0.9.12"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-question.light.png?v=0.9.12"><img src="https://oar.sh/assets/shots/cfmail-question.png?v=0.9.12" alt="A question card in the middle of a turn: the agent offers several choices and a free-text reply"></picture></a>
 <br><sub>When the agent needs a decision, it asks, and waits for your answer.</sub>
 </td>
 </tr>
 <tr>
 <td valign="top">
-<a href="https://oar.sh/assets/shots/pingcf-thoughts.png?v=0.9.11"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/pingcf-thoughts.light.png?v=0.9.11"><img src="https://oar.sh/assets/shots/pingcf-thoughts.png?v=0.9.11" alt="An expanded Thoughts block showing the agent's reasoning above its reply"></picture></a>
+<a href="https://oar.sh/assets/shots/pingcf-thoughts.png?v=0.9.12"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/pingcf-thoughts.light.png?v=0.9.12"><img src="https://oar.sh/assets/shots/pingcf-thoughts.png?v=0.9.12" alt="An expanded Thoughts block showing the agent's reasoning above its reply"></picture></a>
 <br><sub>Read the reasoning, not just the answer.</sub>
 </td>
 </tr>
 <tr>
 <td valign="top">
-<a href="https://oar.sh/assets/shots/pagewright-watching.png?v=0.9.11"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/pagewright-watching.light.png?v=0.9.11"><img src="https://oar.sh/assets/shots/pagewright-watching.png?v=0.9.11" alt="A session watching two other sessions: a finished reply arrives as a compact relay-event row, the watching 2 sessions list is open with Unsubscribe, and a request to also watch a session on a paired relay waits on an Allow / Deny card"></picture></a>
+<a href="https://oar.sh/assets/shots/pagewright-watching.png?v=0.9.12"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/pagewright-watching.light.png?v=0.9.12"><img src="https://oar.sh/assets/shots/pagewright-watching.png?v=0.9.12" alt="A session watching two other sessions: a finished reply arrives as a compact relay-event row, the watching 2 sessions list is open with Unsubscribe, and a request to also watch a session on a paired relay waits on an Allow / Deny card"></picture></a>
 <br><sub>Agents that watch agents: woken by events, approving nothing.</sub>
 </td>
 </tr>
@@ -116,11 +116,11 @@ API keys are entered in **⚙️ Settings** and stay on the relay host. The Clau
 <table>
 <tr>
 <td width="62%" valign="top">
-<a href="https://oar.sh/assets/shots/cfmail-steering.png?v=0.9.11"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-steering.light.png?v=0.9.11"><img src="https://oar.sh/assets/shots/cfmail-steering.png?v=0.9.11" alt="A running Claude turn with a message steered into it mid-turn, the reply streaming with its tool calls, and the Steer button in the composer"></picture></a>
+<a href="https://oar.sh/assets/shots/cfmail-steering.png?v=0.9.12"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-steering.light.png?v=0.9.12"><img src="https://oar.sh/assets/shots/cfmail-steering.png?v=0.9.12" alt="A running Claude turn with a message steered into it mid-turn, the reply streaming with its tool calls, and the Steer button in the composer"></picture></a>
 <br><sub>Send a message while the agent works, and it steers the running turn.</sub>
 </td>
 <td width="38%" valign="top">
-<a href="https://oar.sh/assets/shots/usage-copilot-compact.png?v=0.9.11"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/usage-copilot-compact.light.png?v=0.9.11"><img src="https://oar.sh/assets/shots/usage-copilot-compact.png?v=0.9.11" alt="The GitHub Copilot card in Check Usage: premium requests and plan quota with reset dates, and the cost of the last turn"></picture></a>
+<a href="https://oar.sh/assets/shots/usage-copilot-compact.png?v=0.9.12"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/usage-copilot-compact.light.png?v=0.9.12"><img src="https://oar.sh/assets/shots/usage-copilot-compact.png?v=0.9.12" alt="The GitHub Copilot card in Check Usage: premium requests and plan quota with reset dates, and the cost of the last turn"></picture></a>
 <br><sub>What each plan has left, in one place.</sub>
 </td>
 </tr>
@@ -129,7 +129,7 @@ API keys are entered in **⚙️ Settings** and stay on the relay host. The Clau
 - **Watch a turn live**: the reply, the agent's thoughts and every tool call appear as they happen, and each sub-agent gets a bubble of its own. **Stop** is always one tap away ([While a turn runs](docs/web-ui.md#while-a-turn-runs)).
 - **Steer or queue**: a message sent during a turn goes into it (Claude, Copilot) or waits behind it ([While a turn runs](docs/web-ui.md#while-a-turn-runs)).
 - **Answer questions**: the agent asks on a card with one-click choices, checkmarks or free text, and waits for you ([Question cards](docs/web-ui.md#question-cards)).
-- **Background work**: a task panel lists the commands and sub-agents that outlive a reply, each with its own **Stop** and its full record ([Background tasks](docs/web-ui.md#background-tasks)).
+- **Background work**: a task panel lists the commands and sub-agents that outlive a reply, each with its own **Stop** and its full record; a command's console shows its output live, says when it has gone quiet and counts a test run's passes and failures ([Background tasks](docs/web-ui.md#background-tasks)).
 - **Choose how the agent works**: `ask`, `plan`, `agent` or `autopilot`, plus model and reasoning effort, per message ([Relay modes](docs/web-ui.md#relay-modes)).
 - **Files and git**: browse the workspace, preview files, review git changes in a diff viewer, and publish a dev server as a preview link ([Files, git, and previews](docs/web-ui.md#files-git-and-previews), [preview servers](docs/preview-servers.md)).
 - **Usage and context**: plan limits and credits of every provider, and what fills the model's context window ([Usage and context](docs/web-ui.md#usage-and-context)).
@@ -137,7 +137,7 @@ API keys are entered in **⚙️ Settings** and stay on the relay host. The Clau
 - **Share** a conversation as a read-only link, hide single messages and the host's paths from it, and see when it was opened ([Sharing](docs/web-ui.md#sharing)).
 - **On your phone**: install OAR as an app and get push notifications ([Notifications and the app](docs/web-ui.md#notifications-and-the-app)).
 
-The full tour is in [Using the web UI](docs/web-ui.md); every setting and config key is in [Settings and configuration](docs/configuration.md). What changed in each release is in the [changelog](CHANGELOG.md), with [0.9.11](CHANGELOG.md#0911--2026-10-17) as the latest.
+The full tour is in [Using the web UI](docs/web-ui.md); every setting and config key is in [Settings and configuration](docs/configuration.md). What changed in each release is in the [changelog](CHANGELOG.md), with [0.9.12](CHANGELOG.md#0912--2026-10-18) as the latest.
 
 ## Remote access
 
@@ -188,7 +188,7 @@ flowchart LR
 
 You stay in charge: per paired relay you decide whether agents may only read, also prompt, or do everything, and in the `ask` and `plan` modes every write asks you first. A subscription only notifies; it approves nothing.
 
-<p><a href="https://oar.sh/assets/shots/pagewright-cross-relay.png?v=0.9.11"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/pagewright-cross-relay.light.png?v=0.9.11"><img src="https://oar.sh/assets/shots/pagewright-cross-relay.png?v=0.9.11" alt="A session watching two sessions on a paired relay: a reply arrives as a relay-event row, and after a short outage the events the other relay kept arrive as one replayed row" width="720"></picture></a></p>
+<p><a href="https://oar.sh/assets/shots/pagewright-cross-relay.png?v=0.9.12"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/pagewright-cross-relay.light.png?v=0.9.12"><img src="https://oar.sh/assets/shots/pagewright-cross-relay.png?v=0.9.12" alt="A session watching two sessions on a paired relay: a reply arrives as a relay-event row, and after a short outage the events the other relay kept arrive as one replayed row" width="720"></picture></a></p>
 
 How pairing, permissions and limits work is in [Agents working together](docs/agents-together.md).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oar-sh/oar",
-  "version": "0.9.11",
+  "version": "0.9.12",
   "type": "module",
   "description": "OAR — Open Agent Relay: drive your local coding agents from any browser",
   "license": "MIT",

package/server/README.md

@@ -899,7 +899,12 @@ turn processing, or queued and not held by a usage-limit pause; `background_only
 `subagent` | `shell`, `description`, `startedAt`, `lastActivityAt`, `status` `running` |
 `completed` | `failed` | `stopped`, `exitCode`, `summary`, `endedAt`) and `lastActivityAt`.
 `remote_relay`'s `list_sessions` and `read_session` pass them on as `state`, `tasks` and
-`lastActivityAt`; `active` stays and is true for background work too.
+`lastActivityAt`; `active` stays and is true for background work too. `read_session` adds to each
+task its `taskId`, `output` (whether it has output to read) and, for a task with an output file,
+`health` (`minutesSinceOutput`, `quiet`, `quietAfterMinutes`, test-run `counts`);
+`read_task_output {session, task_id, lines?}` (read permission; default 200 lines, at most 500 or
+32 KB) reads the end of that output through `GET /api/conversation/:id/background-task/:taskId/output`,
+scrubbed of credentials.
 
 ### Browser
 
@@ -1301,8 +1306,8 @@ Queue metrics include `parkedCount` for turns deferred behind restart/rebind gat
 | GET | `/api/usage` | Unified plan usage: one card per configured provider (`providers[]` with `meters`, `details`, `links`) built from the live Copilot quota, the Claude worker's latest stored snapshot, and the derived Cursor cycle totals. A provider that cannot be read yields an unavailable card rather than failing the response, so the modal always renders. While Claude Cloud is on, the Claude card's windows are read live from the account, and a Claude Cloud card is added (credit meters, the relay's cloud spend, and the cost of the conversation named by `?conversationId=` when it is a cloud one); a card may carry `notes[]` (a line of text with an optional https link), and a meter `severity` and `resetKind: 'expiry'`. Legacy top-level Copilot quota fields are spread alongside `providers` for cached clients; `?legacy=1` returns the Copilot-only snapshot on its own |
 | GET | `/api/settings/cursor-allowance` | Read the manual Cursor plan allowances (`cursorModelsUsd`, `otherModelsUsd`, `resetDay`) |
 | POST | `/api/settings/cursor-allowance` | Set the Cursor pool allowances and billing reset day; `null` clears an allowance, and `resetAccounting: true` re-baselines the derived spend tracking |
-| GET | `/api/settings/claude` | Read Claude provider settings (`enabled`, `model`, `models`, `availableModels`) |
-| POST | `/api/settings/claude` | Enable/disable Claude, set the default model or the enabled model subset; triggers discovery and unstarted-conversation reconciliation |
+| GET | `/api/settings/claude` | Read Claude provider settings (`enabled`, `model`, `models`, `availableModels`, `attributionMode`, `backgroundCommandLimitMinutes` with the slider bounds `backgroundCommandLimitMinMinutes`, `backgroundCommandLimitMaxMinutes`, `backgroundCommandLimitStepMinutes`, `backgroundCommandLimitDefaultMinutes`) |
+| POST | `/api/settings/claude` | Enable/disable Claude, set the default model, the enabled model subset, the attribution mode or `backgroundCommandLimitMinutes` (clamped to 30…480 and snapped to 30-minute steps; not a number is `400`; read by Claude sessions spawned afterwards); triggers discovery and unstarted-conversation reconciliation |
 | GET | `/api/settings/claude-cloud` | Read Claude Cloud settings: `{ enabled, defaultModel, environmentId, environments: [{ id, name }] \| null, environmentsError, account: { loggedIn, email, orgName, subscriptionType } \| null, token: { source, hasToken, expiresAt }, models }`. `token` says where the login is read from (`env`, `file`, `none`) and when it runs out, never the token. `environments` is `null` while the provider is off or the host has no login: nothing is asked of Anthropic then |
 | POST | `/api/settings/claude-cloud` | `{ enabled?, defaultModel?, environmentId? }` → `{ ok: true, …the GET body }`. Enabling without a Claude login on the host is `400` with `code: 'claude_cloud_login_missing'`; an empty `environmentId` clears the stored one. Emits `claude_cloud_settings_updated` |
 | GET | `/api/settings/cursor` | Read Cursor provider settings — same shape as Claude's: `models` is the enabled subset, `availableModels` the full discovered list, plus per-model `efforts` |
@@ -1937,6 +1942,15 @@ the watched one `subscriber_relay_id`, `subscriber_relay_name`, `subscriber_watc
 `subscriber_watcher_title`, `last_pull_at`, `dropped_count`) and `relay_event_links` (per paired
 relay the fetch cursor and the link's health). See [Across paired relays](#across-paired-relays).
 
+`0017-conversation-history-indexes.mjs` adds two indexes and nothing else:
+`queue(response_message_id)` for the sub-agent records of each reply on a history page, and
+`messages(conversation_id, timestamp, id)` for selecting the page itself. `GET
+/api/conversation/:id` and the shared view select the requested page in SQL in conversation order
+(timestamp, then id) and hydrate only its replies, so a page costs the same in a conversation of
+any length. A conversation with a row whose timestamp is not the relay's ISO form
+(`YYYY-MM-DDTHH:MM:SS.mmmZ`) or whose id is not lowercase letters, digits and dashes is paged the
+old way: every row loaded, the page cut afterwards.
+
 `0007-claude-cloud.mjs` adds the storage of [Claude Cloud](#claude-cloud-provider) conversations.
 It is additive and idempotent, runs on every boot, and a failure is logged and retried on the next
 one:

package/server/claude-worker/claude-remote-relay-tool.mjs

@@ -81,6 +81,8 @@ export const REMOTE_RELAY_TOOL_ZOD_SHAPE = {
   subscription_id: text('subscription_id'),
   watcher: text('watcher'),
   from: text('from'),
+  task_id: text('task_id'),
+  lines: number('lines'),
 };
 
 export function createRemoteRelayToolDefinition({ api, getConversationId = () => '', dbg = () => {} } = {}) {

package/server/claude-worker/claude-sdk-adapter.mjs

@@ -1,5 +1,6 @@
 import { createSdkMcpServer, query } from '@anthropic-ai/claude-agent-sdk';
 
+import { formatClaudeBackgroundCommandLimitLabel } from '../../shared/claude-background-command-limit.mjs';
 import { parseThinkingDisplay } from '../../shared/claude-thinking.mjs';
 import { MEDIA_EMBED_INSTRUCTION_TEXT } from '../../shared/media-embed-instructions.mjs';
 import { REMOTE_RELAY_TOOL_CALL_TIMEOUT_MS } from '../../shared/remote-relay-tool-core.mjs';
@@ -136,11 +137,57 @@ export function permissionModeForRelayMode(relayMode) {
   return 'default';
 }
 
-export function systemPromptForRelayMode(relayMode) {
+// Bash timeouts the CLI reads from its environment (measured against CLI
+// 2.1.292). BASH_DEFAULT_TIMEOUT_MS is the only lever on the background
+// default (`max(30 min, BASH_DEFAULT_TIMEOUT_MS)`), but it also becomes the
+// foreground default; CLAUDE_CODE_AUTO_BACKGROUND_TIMEOUT_MS therefore caps a
+// main-agent foreground command at 2 min and then moves it to the background
+// instead of letting it block the turn. BASH_MAX_TIMEOUT_MS lifts the ceiling
+// an explicit `timeout` may ask for (foreground and background) to 8 h.
+// Commands that start with `sleep` are never moved to the background by the
+// CLI, and subagents get no auto-background; both run in the foreground for
+// up to the default.
+export const CLAUDE_BASH_MAX_TIMEOUT_MS = 8 * 3_600_000;
+export const CLAUDE_AUTO_BACKGROUND_TIMEOUT_MS = 120_000;
+
+/**
+ * The environment a Claude CLI spawn gets, or null to inherit the worker's
+ * own. `env` REPLACES the subprocess environment in the SDK, so the base is
+ * spread in.
+ */
+export function claudeSpawnEnv({ backgroundCommandLimitMs = null, baseEnv = process.env } = {}) {
+  const limit = Number(backgroundCommandLimitMs);
+  if (backgroundCommandLimitMs === null || !Number.isFinite(limit) || limit <= 0) return null;
+  return {
+    ...baseEnv,
+    BASH_DEFAULT_TIMEOUT_MS: String(Math.round(limit)),
+    BASH_MAX_TIMEOUT_MS: String(Math.max(CLAUDE_BASH_MAX_TIMEOUT_MS, Math.round(limit))),
+    CLAUDE_CODE_AUTO_BACKGROUND_TIMEOUT_MS: String(CLAUDE_AUTO_BACKGROUND_TIMEOUT_MS),
+  };
+}
+
+/** How to run long commands, with the session's limit when it is known. */
+export function longCommandInstructionText(backgroundCommandLimitMs = null) {
+  const limit = Number(backgroundCommandLimitMs);
+  const known = backgroundCommandLimitMs !== null && Number.isFinite(limit) && limit > 0;
+  const limitClause = known
+    ? `Background Bash commands are stopped after ${formatClaudeBackgroundCommandLimitLabel(limit / 60_000)} unless you pass a longer timeout (up to 8 h); `
+    : 'For long background Bash commands, ';
+  return `${limitClause}write the full output to a log file instead of piping it into tail or head, `
+    + 'since the pipe holds the output back and loses it if the command is stopped. '
+    + 'Start runs that must survive a session restart detached with nohup and a log file.';
+}
+
+export function systemPromptForRelayMode(relayMode, { backgroundCommandLimitMs = null } = {}) {
   const mode = String(relayMode || 'agent').trim().toLowerCase();
   // The media-embed capability rides every session — unlike the mode nudges it
-  // is renderer knowledge the model cannot discover any other way.
-  const append = [MEDIA_EMBED_INSTRUCTION_TEXT, MODE_SYSTEM_PROMPT_APPEND[mode]]
+  // is renderer knowledge the model cannot discover any other way. The long
+  // command note rides every session too: the limit is the relay's setting.
+  const append = [
+    MEDIA_EMBED_INSTRUCTION_TEXT,
+    longCommandInstructionText(backgroundCommandLimitMs),
+    MODE_SYSTEM_PROMPT_APPEND[mode],
+  ]
     .filter(Boolean)
     .join('\n\n');
   return {
@@ -233,6 +280,10 @@ export function startClaudeSession({
   autoCompactWindow = null,
   thinkingEnabled = null,
   attribution = null,
+  // How long a backgrounded Bash command may run without its own timeout
+  // (ms, the relay's setting); null leaves the CLI's defaults and the
+  // worker's environment alone.
+  backgroundCommandLimitMs = null,
   thinkingDisplay = '',
   abortController,
   canUseTool,
@@ -259,14 +310,16 @@ export function startClaudeSession({
   const relayMcpServer = typeof api === 'function'
     ? createRelayMcpServer({ api, getConversationId, dbg, remoteRelayTool: remoteRelayTool === true })
     : null;
+  const env = claudeSpawnEnv({ backgroundCommandLimitMs });
   const options = {
     cwd,
     permissionMode: permissionModeForRelayMode(relayMode),
-    systemPrompt: systemPromptForRelayMode(relayMode),
+    systemPrompt: systemPromptForRelayMode(relayMode, { backgroundCommandLimitMs: env ? backgroundCommandLimitMs : null }),
     includePartialMessages: true,
     forwardSubagentText: true,
     ...(effortOption ? { effort: effortOption } : {}),
     ...(spawnSettings ? { settings: spawnSettings } : {}),
+    ...(env ? { env } : {}),
     ...(normalizedModel && normalizedModel !== 'auto' ? { model: String(model).trim() } : {}),
     ...(String(resume || '').trim() ? { resume: String(resume).trim() } : {}),
     ...(abortController ? { abortController } : {}),

package/server/claude-worker/claude-session-process.mjs

@@ -58,6 +58,13 @@ import {
   withSlashCommandGuardContent,
 } from '../../shared/slash-command-guard.mjs';
 import { createUsageLimitTracker } from '../../shared/claude-usage-limit.mjs';
+import {
+  discoverTaskOutputPaths,
+  exitCodeFromSummary,
+  isShellTaskType,
+  outputDirOf,
+  usableOutputPath,
+} from './task-output-discovery.mjs';
 
 /**
  * Which system-prompt append a relay mode gets (claude-sdk-adapter's
@@ -77,6 +84,8 @@ export { STEER_FOLDED_TEXT, STEER_STOPPED_TEXT };
 /** Task types that run a model of their own (vs. bash/monitor/workflow). */
 const AGENT_TASK_TYPES = new Set(['local_agent', 'agent', 'subagent']);
 const MAX_TASK_TOOL_CALL_CHARS = 300;
+/** Output paths remembered per process (one per backgrounded shell). */
+const MAX_TASK_OUTPUT_PATHS = 200;
 
 // ---------------------------------------------------------------------------
 // Workflow progress sources (CLI 2.1.226 on-disk formats)
@@ -460,6 +469,10 @@ export function createClaudeSessionRunner({
   // leaves the CLI's own attribution. Piggybacked on deliveries like the
   // window above.
   getAttribution = () => null,
+  // How long a backgrounded Bash command may run without its own timeout
+  // (ms; the relay's Claude setting). Read at spawn only: the CLI takes it
+  // from its environment, so a change applies to the next process.
+  getBackgroundCommandLimitMs = () => null,
   // The per-conversation thinking state ({enabled, display}); read per turn
   // like the window, so a settings change reaches a running process on its
   // next delivery.
@@ -1769,6 +1782,9 @@ export function createClaudeSessionRunner({
           // The workflow digest (poller below) rides the same row; the relay
           // sanitizer whitelists and re-clamps it before storing.
           ...(task.workflowProgress ? { workflowProgress: task.workflowProgress } : {}),
+          ...(agentLike && Number.isInteger(task.steps) ? { steps: task.steps } : {}),
+          // Where the relay reads the task's console from.
+          ...(isShellTaskType(task.taskType) ? taskOutputFields(processRef, taskId) : {}),
         };
       });
       return postTaskSet({ tasks, ...(resync ? { resync: true } : {}) }).catch((error) => {
@@ -1788,6 +1804,89 @@ export function createClaudeSessionRunner({
     return Promise.resolve();
   }
 
+  // ---------------------------------------------------------------------------
+  // Task output files
+  //
+  // The relay reads a shell task's console straight from the file the CLI
+  // writes (`<tasks dir>/<taskId>.output`); the worker only names it. Bash
+  // results announce the path (task-output-discovery.mjs); a Monitor result
+  // does not, but its file follows the same scheme next to any known one, and
+  // is named only once it exists. Without a path the relay falls back to the
+  // CLI's `getTaskOutput` snapshot (task_output_snapshot control).
+
+  function rememberTaskOutputPath(processRef, taskId, outputPath) {
+    const id = String(taskId || '').trim();
+    const usable = usableOutputPath(outputPath);
+    if (!id || !usable) return false;
+    const dir = outputDirOf(usable);
+    if (dir) processRef.taskOutputDir = dir;
+    // The first path a task names wins, here as on the relay.
+    if (processRef.taskOutputPaths.has(id)) return false;
+    processRef.taskOutputPaths.set(id, usable);
+    while (processRef.taskOutputPaths.size > MAX_TASK_OUTPUT_PATHS) {
+      processRef.taskOutputPaths.delete(processRef.taskOutputPaths.keys().next().value);
+    }
+    return true;
+  }
+
+  function taskOutputFields(processRef, taskId) {
+    const known = processRef.taskOutputPaths.get(taskId);
+    if (known) return { outputPath: known, outputKind: 'file' };
+    if (processRef.taskOutputDir) {
+      const candidate = nodePath.join(processRef.taskOutputDir, `${taskId}.output`);
+      let exists = false;
+      try { exists = nodeFs.existsSync(candidate); } catch {}
+      if (exists && rememberTaskOutputPath(processRef, taskId, candidate)) {
+        return { outputPath: candidate, outputKind: 'file' };
+      }
+    }
+    return { outputKind: 'snapshot' };
+  }
+
+  /** A backgrounded Bash/Monitor result: note its file, and show it on the live row. */
+  function recordTaskOutputPaths(sdkMessage) {
+    let liveChanged = false;
+    for (const { taskId, outputPath } of discoverTaskOutputPaths(sdkMessage)) {
+      if (rememberTaskOutputPath(proc, taskId, outputPath) && proc.liveTasks.has(taskId)) liveChanged = true;
+    }
+    if (liveChanged) publishBackgroundTasks();
+  }
+
+  /**
+   * The relay's fallback for a shell task with no file: the CLI's last 8 KiB
+   * (`Query.getTaskOutput`, implemented in sdk.mjs though sdk.d.ts does not
+   * declare it), posted for the relay to serve. Asked once per viewer open.
+   */
+  async function snapshotTaskOutput(taskId) {
+    const id = String(taskId || '').trim();
+    const processRef = proc;
+    if (!id || typeof processRef?.turn?.getTaskOutput !== 'function') {
+      dbg('task output snapshot unavailable', id || '(no task)');
+      return false;
+    }
+    let answer;
+    try {
+      answer = await processRef.turn.getTaskOutput(id);
+    } catch (error) {
+      dbg('getTaskOutput failed', id, error?.message || String(error));
+      return false;
+    }
+    const output = typeof answer?.output === 'string' ? answer.output : '';
+    const totalBytes = Number(answer?.total_bytes);
+    try {
+      await api('POST', `/api/background-tasks/${encodeURIComponent(id)}/output-snapshot`, {
+        conversationId: sdkSessionId,
+        output,
+        totalBytes: Number.isFinite(totalBytes) && totalBytes >= 0 ? totalBytes : Buffer.byteLength(output),
+        truncated: answer?.truncated === true,
+      });
+      return true;
+    } catch (error) {
+      dbg('task output snapshot post failed', id, error?.message || String(error));
+      return false;
+    }
+  }
+
   // ---------------------------------------------------------------------------
   // Workflow progress poller
   //
@@ -2226,6 +2325,11 @@ export function createClaudeSessionRunner({
       recordSubagentActivity(sdkMessage);
       return;
     }
+    if (type === 'user') {
+      // Any agent's backgrounded shell, the main thread's or a subagent's.
+      recordTaskOutputPaths(sdkMessage);
+      return;
+    }
     if (type !== 'system') return;
     const subtype = String(sdkMessage.subtype || '');
     if (subtype === 'init') {
@@ -2524,6 +2628,9 @@ export function createClaudeSessionRunner({
         known.toolUseId = String(sdkMessage.tool_use_id || '').trim() || known.toolUseId || '';
         const totalTokens = Number(sdkMessage.usage?.total_tokens);
         if (Number.isFinite(totalTokens)) known.totalTokens = totalTokens;
+        // The sub-agent's tool calls so far: the panel row's step count.
+        const toolUses = Number(sdkMessage.usage?.tool_uses);
+        if (Number.isFinite(toolUses) && toolUses >= 0) known.steps = Math.floor(toolUses);
         publishBackgroundTasks({ throttled: true });
       }
       return;
@@ -2543,6 +2650,16 @@ export function createClaudeSessionRunner({
         // tell its watchers the end. A failed post is kept and sent again.
         const published = proc.liveTasks.get(taskId) || proc.departedTasks.get(taskId) || null;
         proc.departedTasks.delete(taskId);
+        // A shell's file and exit code make the relay's ended row: its
+        // console stays readable after the task is gone.
+        rememberTaskOutputPath(proc, taskId, sdkMessage.output_file);
+        const shellLike = isShellTaskType(published?.taskType);
+        const outputPath = shellLike ? (proc.taskOutputPaths.get(taskId) || '') : '';
+        const exitCode = shellLike ? exitCodeFromSummary(sdkMessage.summary) : null;
+        const toolUses = Number(sdkMessage.usage?.tool_uses);
+        const steps = AGENT_TASK_TYPES.has(String(published?.taskType || '')) && Number.isFinite(toolUses) && toolUses >= 0
+          ? Math.floor(toolUses)
+          : null;
         void keptTaskSettles.post('/api/background-task-settled', {
           conversationId: sdkSessionId,
           taskId,
@@ -2555,6 +2672,9 @@ export function createClaudeSessionRunner({
             taskType: String(published.taskType || ''),
             startedAt: published.startedAt || null,
           } : {}),
+          ...(outputPath ? { outputPath } : {}),
+          ...(exitCode !== null ? { exitCode } : {}),
+          ...(steps !== null ? { steps } : {}),
         });
       }
       // A settled session-level task means the CLI is about to dequeue a
@@ -3365,6 +3485,7 @@ export function createClaudeSessionRunner({
     const thinkingEnabled = parseThinkingEnabled(thinkingState.enabled);
     const thinkingDisplay = parseThinkingDisplay(thinkingState.display);
     const attribution = getAttribution() || null;
+    const backgroundCommandLimitMs = getBackgroundCommandLimitMs() ?? null;
     const abortController = new AbortController();
     const processRef = {
       turn: null,
@@ -3391,6 +3512,11 @@ export function createClaudeSessionRunner({
       // taskId → the row of a task that left the live set, until its
       // notification arrives.
       departedTasks: new Map(),
+      // taskId → the file a shell task's output goes to (first named wins),
+      // and the directory of the last one seen: a Monitor task's file sits
+      // next to it.
+      taskOutputPaths: new Map(),
+      taskOutputDir: '',
       // taskId → { runId, labels, digestJson } for live local_workflow tasks;
       // pruned by syncWorkflowPoller when a task leaves the live set.
       workflowStates: new Map(),
@@ -3538,6 +3664,7 @@ export function createClaudeSessionRunner({
       thinkingEnabled,
       thinkingDisplay,
       attribution,
+      backgroundCommandLimitMs,
       abortController,
       canUseTool,
       pathToClaudeCodeExecutable,
@@ -4121,6 +4248,7 @@ export function createClaudeSessionRunner({
     isTurnActive,
     stopBackgroundTask,
     stopBackgroundTaskByToolUseId,
+    snapshotTaskOutput,
     backgroundTaskIds,
     resyncBackgroundTasks,
     flushKeptTaskSettles,