pi-background-tasks 0.3.0 → 0.6.0

package/PUBLISHING.md

@@ -32,8 +32,8 @@ npm publish --access public
 Pi install smoke after publish:
 
 ```bash
-pi -e npm:pi-background-tasks@0.3.0 --offline --no-tools --no-session -p "/jobs"
-pi install npm:pi-background-tasks@0.3.0
+pi -e npm:pi-background-tasks@0.6.0 --offline --no-tools --no-session -p "/jobs"
+pi install npm:pi-background-tasks@0.6.0
 ```
 
 ## Publish to git
@@ -48,15 +48,15 @@ git commit -m "Release pi-background-tasks"
 git branch -M main
 git remote add origin git@github.com:ismailsaleekh/pi-background-tasks.git
 git push -u origin main
-git tag v0.3.0
-git push origin v0.3.0
+git tag v0.6.0
+git push origin v0.6.0
 ```
 
 Pi install smoke after git tag:
 
 ```bash
-pi -e git:github.com/ismailsaleekh/pi-background-tasks@v0.3.0 --offline --no-tools --no-session -p "/jobs"
-pi install git:github.com/ismailsaleekh/pi-background-tasks@v0.3.0
+pi -e git:github.com/ismailsaleekh/pi-background-tasks@v0.6.0 --offline --no-tools --no-session -p "/jobs"
+pi install git:github.com/ismailsaleekh/pi-background-tasks@v0.6.0
 ```
 
 ## pi.dev/packages

package/README.md

@@ -9,19 +9,19 @@ This package adds named, tracked background shell jobs with durable output files
 From npm after publish:
 
 ```bash
-pi install npm:pi-background-tasks@0.3.0
+pi install npm:pi-background-tasks@0.6.0
 ```
 
 From git after pushing this package to its standalone repository and tagging:
 
 ```bash
-pi install git:github.com/ismailsaleekh/pi-background-tasks@v0.3.0
+pi install git:github.com/ismailsaleekh/pi-background-tasks@v0.6.0
 ```
 
 For project-local install:
 
 ```bash
-pi install -l npm:pi-background-tasks@0.3.0
+pi install -l npm:pi-background-tasks@0.6.0
 ```
 
 ## Commands
@@ -32,6 +32,7 @@ pi install -l npm:pi-background-tasks@0.3.0
 - `/kill <id>` — stop a running task.
 - `/tasks` or `/bg-tasks` — fallback command to open the task manager UI.
 - `/bg-clear` — clear finished background-task footer notices.
+- `/bg-update` — print update instructions when a newer published version exists (instruct-only; never self-installs).
 
 ## Footer dock UX
 
@@ -45,6 +46,10 @@ bg 2 done · Shift↓ · /bg-clear
 
 Press `Shift+Down` to open the focused bottom dock. Arrow keys are captured only while the dock is focused. Each task row shows the latest context-window usage reported by that specific background task, for example `ctx 21.0%/200k`; tasks that do not report their own context show `ctx —` rather than the parent Pi session's usage. Background Pi-agent tasks also surface the LLM model they ran (`model gpt-5.5` in the compact row, fully-qualified such as `openai-codex/gpt-5.5` in the detail view), cumulative token usage (`tok 1.6k`), and tool-use counts (`tools 2/1 failed`) in the dock and detail view; missing model/token/tool telemetry is omitted in rows and shown as “not reported by this background task” in details. When a background command is explicitly marked as an agent and invokes a print/json child agent such as `pi -p ...` through the normal shell command name, the extension wraps that child Pi process with `--mode json`, parses real assistant usage/tool execution events, and emits task-owned telemetry automatically — including the model reported by the child assistant turns.
 
+### Agent activity transcript
+
+For those wrapped background Pi agents, the task output file and the dock's detail **Output tail** show a live, human-readable transcript of what the agent is actually doing — assistant messages, `→ tool args` calls, `… reasoning`, and `✗ tool failed` errors — as the agent loop runs. The machine telemetry (context/token/tool/model) is parsed out of the child stream and surfaced only as the metrics above and in `bg_status`/metadata, so the focused window reflects the agent's real activity rather than its raw instrumentation JSON. Child stderr is passed through to the transcript verbatim. Non-agent tasks and agent commands that cannot be wrapped (for example a path-qualified `pi`) keep streaming their raw stdout/stderr unchanged.
+
 Finished-task badges intentionally remain visible until acknowledged. The reliable clear path is `/bg-clear`, which works in every terminal and clears finished background-task footer notices without opening the dock. `Ctrl+Alt+C` is still registered as an optional terminal-dependent fallback shortcut, but the footer advertises `/bg-clear` because some macOS terminals do not transmit `Ctrl+Alt+C` distinctly.
 
 Dock controls:
@@ -54,8 +59,8 @@ Dock controls:
 | `Shift+Down` | Open focused background-task dock |
 | `/bg-clear` | Clear finished-task footer notices from the main UI |
 | `Ctrl+Alt+C` | Optional terminal-dependent shortcut for `/bg-clear` |
-| `↑` / `↓` | Select task |
-| `PageUp` / `PageDown` | Page task list |
+| `↑` / `↓` | Select task (list) · scroll the output tail (detail) |
+| `PageUp` / `PageDown` | Page the task list (list) · page the output tail (detail) |
 | `Enter` / `→` | Inspect logs/details |
 | `←` | Return from details to list |
 | `h` | Toggle recent history |
@@ -65,6 +70,21 @@ Dock controls:
 | `R` | Rerun selected command |
 | `c` | Show copyable output path |
 | `x` / `Esc` / `q` | Close dock |
+| `/bg-update` | Print update instructions when a newer version is published |
+
+In the detail view the **Output tail** is scrollable: `↑`/`↓` and `PageUp`/`PageDown` move through the loaded output (a generous bounded window, not just the last lines). Scrolling up pauses the live tail and freezes the view so it stays stable as new output arrives; the status line shows your position (e.g. `lines 46–57 of 60`). Scrolling back to the bottom (or pressing `r`) resumes live tailing.
+
+### Update-available notice
+
+When a newer version of `pi-background-tasks` has been published to npm, the footer appends a compact, instruct-only segment after the entry hint:
+
+```text
+bg 1 running · 1 failed · Shift↓ · /bg-clear · ⬆ v0.7.0 /bg-update
+```
+
+When no tasks are active, the notice still appears on its own (`bg ⬆ v0.7.0 /bg-update`) so the update hint is visible. The segment is rendered only when a strictly newer published version exists; `/bg-update` prints the npm and git update commands and never installs or self-updates.
+
+The lookup runs at most once per session on `session_start`, is time-boxed, and is fully offline-safe: it never blocks or errors the footer/session, and on an offline or failed lookup it simply renders no segment (it never pins a misleading version). The check is skipped entirely when `PI_OFFLINE=1`, and can be disabled explicitly with `PI_BG_DISABLE_UPDATE_CHECK=1`. Set `PI_BG_REGISTRY_URL` to point the check at a registry mirror instead of `https://registry.npmjs.org`.
 
 ## LLM tools
 

package/TESTING.md

@@ -71,9 +71,11 @@ Tests must not use the user's real `~/.pi/agent`.
 Implemented coverage includes:
 
 - tools: `bg_run`, `bg_status`, `bg_logs`, `bg_kill`, including required `isAgent` schema/runtime validation, unknown/ambiguous IDs, completed-kill failure, legacy no-name preparation, head/tail truncation, and notification on/off behavior
-- commands: `/bg`, `/jobs`, `/logs`, `/kill`, `/tasks`, `/bg-tasks`, `/bg-clear` discovery, happy paths, `/bg --agent` parsing, finished-notice clearing, malformed `/bg`, unknown/ambiguous IDs, completed-task `/kill`, byte-limit normalization, and RPC no-hang fallback behavior
-- shortcut/UI: component coverage for focused dock list/detail/key handling, empty/history/unread states, paging, close aliases, stop/stop-all/rerun/path actions, missing output files; SDK coverage for explicit `/bg-clear` finished-notice clearing, `/bg-clear` footer hinting, optional `Ctrl+Alt+C` fallback shortcut registration, and mixed failed/stopped/done/focused footer status; RPC coverage that `/bg-clear` works as a terminal-independent clear path; and PTY coverage for `/tasks`, `/bg-tasks`, real `Shift+Down`, arrows, page keys, detail/back/history/stop/stop-all/rerun/path/close, failed unread badges, and running/completed/failed/killed rerun paths
+- commands: `/bg`, `/jobs`, `/logs`, `/kill`, `/tasks`, `/bg-tasks`, `/bg-clear`, `/bg-update` discovery, happy paths, `/bg --agent` parsing, finished-notice clearing, malformed `/bg`, unknown/ambiguous IDs, completed-task `/kill`, byte-limit normalization, and RPC no-hang fallback behavior
+- update-available notice: semver parse/compare/precedence, `formatUpdateSegment`, npm/`package.json` payload narrowing, and injected-fetch success/404/throw/timeout (unit); localhost-registry footer segment (idle + appended to an active footer), `/bg-update` non-installing instructions, and opt-out/offline/already-current/registry-failure no-segment-and-no-throw paths (SDK); `/bg-update` discovery and offline instructions (RPC). The check is one-shot on `session_start`, time-boxed, offline-safe, gated by `PI_OFFLINE`/`PI_BG_DISABLE_UPDATE_CHECK`, and `PI_BG_REGISTRY_URL` overrides the registry endpoint
+- shortcut/UI: component coverage for focused dock list/detail/key handling, detail output-tail scrolling (arrow/page scroll, follow-pause-on-scroll, `lines X–Y of N` position indicator, resume-follow-at-bottom, and no-scroll when output fits), empty/history/unread states, paging, close aliases, stop/stop-all/rerun/path actions, missing output files; SDK coverage for explicit `/bg-clear` finished-notice clearing, `/bg-clear` footer hinting, optional `Ctrl+Alt+C` fallback shortcut registration, and mixed failed/stopped/done/focused footer status; RPC coverage that `/bg-clear` works as a terminal-independent clear path; and PTY coverage for `/tasks`, `/bg-tasks`, real `Shift+Down`, arrows, page keys, detail/back/history/stop/stop-all/rerun/path/close, failed unread badges, and running/completed/failed/killed rerun paths
 - runtime files: output and metadata files under `.pi/tasks/`, persisted `isAgent` classification, task-owned context-window telemetry snapshots, cumulative background Pi-agent token usage, tool-use counts, agent model identifier (preferring the fully-qualified `provider/model` form), explicit `isAgent:true` telemetry wrapping for background `pi` agents, `isAgent:false` non-wrapping for scripts, real child `pi --mode json` tool-event parsing, split/large telemetry ingestion, metadata after completion/failure, local tarball install contents
+- agent activity transcript: pure `parseAgentActivity`/`formatAgentActivityLine` coverage (assistant text, reasoning, tool start with arg summary, silent successful tool end, `✗ tool failed` errors, truncation, invalid/non-activity narrowing); registry-unit coverage that wrapped-agent stdout is reconstructed across split chunks into the human-readable transcript while telemetry/activity control JSON is stripped from the output file (telemetry fields still updated), stderr passes through, and the trailing partial line is flushed on finalize; SDK coverage that fake and real child `pi --mode json` runs surface `→ tool`/`✗ tool failed`/assistant text in `bg_logs` with no control JSON leaking into the visible output
 - safety: kill, already-finished kill failure, timeout failure, spawn failure, low output-cap failure, multi-task shutdown cleanup, process-group kill fallback, Windows child-kill behavior, SIGKILL escalation, duplicate finalization/notification races, metadata/notification failure handling, and pruning
 - agent loop: deterministic scripted-provider coverage for actual `bg_run` completion follow-up turns, `/bg` display-only behavior, `notifyOnCompletion:false`, and failed-task notification error fields
 - package: manifest, docs, `pi.extensions`, peer dependency/import parity, packed runtime files, tarball-install smoke, and artifact exclusion
@@ -85,6 +87,7 @@ Implemented coverage includes:
 - `/tasks` and `/bg-tasks` open the focused dock and close with `x`.
 - A named `/bg` task appears in the dock when opened with xterm `Shift+Down` (`ESC [ 1 ; 2 B`).
 - Secondary dock keys work in a real TUI: arrows, page keys, detail/back, history, stop selected, stop-all confirmation, rerun, output path, and failed/unread history surfacing.
+- Detail output-tail scrolling works with real arrow/page keys: opening a 60-line task's detail and pressing `↑` shows the `lines X–Y of N` position indicator and pauses the live tail.
 
 The detail-view `Model:` line and the compact `model <id>` dock row are also exercised deterministically by the component layer (`tests/component/background-tasks-manager.test.ts`), which is the lowest reliable layer for dock rendering.
 

package/TEST_PLAN.md

@@ -12,7 +12,7 @@ This package follows:
 |---|---|
 | Package | `pi-background-tasks` |
 | Extension entrypoint | `extensions/background-tasks.ts` |
-| Public commands | `/bg`, `/jobs`, `/logs`, `/kill`, `/tasks`, `/bg-tasks`, `/bg-clear` |
+| Public commands | `/bg`, `/jobs`, `/logs`, `/kill`, `/tasks`, `/bg-tasks`, `/bg-clear`, `/bg-update` |
 | Public tools | `bg_run`, `bg_status`, `bg_logs`, `bg_kill` |
 | Shortcuts | `Shift+Down`; optional fallback `Ctrl+Alt+C` |
 | Custom UI | footer status + focused bottom dock overlay |
@@ -54,20 +54,22 @@ This package follows:
 | Per-task token usage | background Pi-agent telemetry + `bg_status`/metadata/dock row/detail | yes | yes |  | yes |  |  |  | SDK verifies cumulative input/output/cache read/cache write/total token usage from explicit telemetry, fake `isAgent:true` wrapped child events, and real child `pi --mode json` with scripted provider; component verifies row/detail rendering. |
 | Per-task tool-use counts | background Pi-agent telemetry + `bg_status`/metadata/dock row/detail | yes | yes |  | yes |  |  |  | SDK verifies total/failed/by-name tool counts from fake and real child Pi `tool_execution_start/end` events, including failed tools; component verifies row/detail rendering. |
 | Per-task agent model | background Pi-agent telemetry + `bg_status`/metadata/dock row/detail | yes | yes |  | yes |  |  |  | Unit verifies `formatModelSummary`/snapshot-list rendering and telemetry ingestion of `model`; SDK verifies the model is captured from explicit telemetry, fake `isAgent:true` wrapped child `message_end` events (qualified `provider/model`), and a real child `pi --mode json` run (bare child model re-qualified from `--model`), plus that non-agent tasks report no model; component verifies compact `model <id>` row, fully-qualified `Model:` detail, and the “not reported by this background task” placeholder. |
+| Agent activity transcript | wrapped Pi-agent output file + dock detail tail + `bg_logs` | yes | yes |  |  |  |  |  | Unit covers `parseAgentActivity`/`formatAgentActivityLine` for assistant text, reasoning, tool start (arrow + collapsed/truncated arg summary), and tool end (silent success, `✗ tool failed[: error]`), plus blank/invalid/non-activity narrowing. Registry unit verifies wrapped-agent stdout is reconstructed across split chunks into the transcript, `background-task-telemetry`/`-context-usage`/`-activity` control lines are stripped from the output file while still updating telemetry fields, child stderr passes through verbatim, and the trailing partial line is flushed on finalize. SDK verifies fake and real child `pi --mode json` runs render `→ tool`, `✗ tool failed`, and assistant text in `bg_logs` while keeping the telemetry/activity control JSON out of the visible output. |
 | Focused dock list | overlay component |  |  |  | yes | yes |  |  | Selection/actions/history tested; PTY covers arrows, page keys, ordering with multiple tasks, failed/unread badges, and `/bg-tasks` fallback. |
-| Focused dock detail | overlay component |  |  |  | yes |  |  |  | Tail read, output box, return-to-list tested. |
+| Focused dock detail | overlay component |  |  |  | yes | yes |  |  | Tail read, output box, and return-to-list tested. Component also verifies output-tail scrolling: ↑/↓ + PageUp/PageDown move through the loaded window, scrolling up pauses the live tail and shows a `lines X–Y of N` position, paging back to the bottom resumes follow, and output that fits the window never enters scroll mode. PTY drives the real arrow/page scroll keys in the detail tail. |
 | Dock stop selected | `k` |  |  |  | yes |  |  |  | Component. |
 | Dock stop all | `a`/`K` |  |  |  | yes | yes |  |  | Component and PTY confirmation. |
 | Dock rerun | `R` |  |  |  | yes | yes |  |  | Component plus PTY running/completed/failed/killed rerun paths. |
 | Dock close | `x`/`Esc`/`q` |  |  |  | yes | yes |  |  | Component + PTY. |
 | Shortcut opens dock | `Shift+Down` |  | registration |  |  | yes |  |  | PTY sends xterm `ESC [ 1 ; 2 B`. |
 | Clear finished notices | `/bg-clear`, optional `Ctrl+Alt+C` fallback |  | yes | yes |  |  |  |  | `/bg-clear` is the canonical terminal-independent path and is advertised in the footer. SDK invokes the slash-command handler and verifies fallback shortcut registration; RPC verifies `/bg-clear` clears finished notices; finished notices remain until explicit clear. |
+| Update-available footer notice | `⬆ v<latest> /bg-update` footer segment + `/bg-update` command | yes | yes | yes |  |  |  |  | Unit covers semver parse/compare/precedence, `isNewerVersion`, `formatUpdateSegment`, npm/`package.json` payload narrowing, injected-fetch success/404/throw/timeout, and `package.json` read/degrade. SDK uses a localhost registry to verify the idle and append-to-active footer segment, `/bg-update` non-installing instructions, and that opt-out (`PI_BG_DISABLE_UPDATE_CHECK=1`), offline (`PI_OFFLINE=1`), already-current, and registry-failure paths render no segment and never throw. RPC verifies `/bg-update` discovery and offline non-installing instructions. The check is one-shot per `session_start`, time-boxed, offline-safe, and never runs on the status tick. |
 | Runtime output files | `.pi/tasks/...output` | yes | yes |  |  |  |  |  | SDK asserts existence. |
 | Runtime metadata files | `.pi/tasks/...json` | yes | yes |  |  |  |  |  | SDK asserts shape/status/name/context usage; registry unit tests cover metadata failure/update ordering. |
 | Timeout kills task | `timeoutSeconds` |  | yes |  |  |  |  |  | SDK. |
 | Output cap kills task | `PI_BG_MAX_OUTPUT_BYTES` |  |  | yes |  |  |  |  | RPC runs with a low cap and asserts failed status/log notice. |
 | Shutdown cleanup | `session_shutdown` | yes | yes |  |  |  |  |  | SDK asserts multiple running tasks become killed; registry tests cover shared stop/wait behavior. |
-| Process lifecycle/races | registry core | yes | yes | yes |  | yes |  | yes | Unit tests cover process-group fallback, Windows fallback, SIGKILL escalation, duplicate finalization/notification races, notification/metadata failures, pruning, malformed telemetry, split telemetry chunks, and large telemetry records above the old 16KiB buffer; SDK/RPC cover runtime spawn/timeout/output-cap/shutdown; scripted provider covers wakeup integration. |
+| Process lifecycle/races | registry core | yes | yes | yes |  | yes |  | yes | Unit tests cover process-group fallback, Windows fallback, SIGKILL escalation, duplicate finalization/notification races, notification/metadata failures, pruning, malformed telemetry, split telemetry chunks, large telemetry records above the old 16KiB buffer, and wrapped-agent transcript/telemetry separation with split-chunk and trailing-partial flush; SDK/RPC cover runtime spawn/timeout/output-cap/shutdown; scripted provider covers wakeup integration. |
 | Package manifest | `package.json` |  |  |  |  |  | yes |  | Keywords, `pi.extensions`, files. |
 | Pack contents | `npm pack --dry-run` |  |  |  |  |  | yes |  | Runtime files included. |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-background-tasks",
-  "version": "0.3.0",
+  "version": "0.6.0",
   "description": "Claude-Code-like named background shell task manager for Pi: bg_run tools, /bg commands, Shift+Down footer dock, bounded logs, kill/timeout safety, and completion wakeups.",
   "type": "module",
   "license": "ISC",

package/src/core/common.ts

@@ -64,6 +64,10 @@ export type BgTask = Omit<BgTaskSnapshot, "name"> & {
 	capExceeded?: boolean | undefined;
 	finalized?: boolean | undefined;
 	contextUsageBuffer?: string | undefined;
+	/** True when this task launched a telemetry-wrapped Pi agent; its stdout carries control lines, not raw output. */
+	telemetryWrapped?: boolean | undefined;
+	/** Partial trailing stdout line held between chunks while reconstructing wrapped-agent control lines. */
+	agentStdoutBuffer?: string | undefined;
 	waiters: Array<() => void>;
 };
 
@@ -299,6 +303,81 @@ export function formatModelSummary(model?: string): string | undefined {
 	return `model=${model}`;
 }
 
+/**
+ * Human-readable activity transcript for telemetry-wrapped Pi agents.
+ *
+ * The wrapper emits one `background-task-activity` control line per meaningful
+ * child-agent event (assistant text, reasoning, tool start, tool end) so the
+ * registry can render "what the agent is actually doing" into the task output
+ * file instead of leaking raw telemetry JSON. Both the parser and the formatter
+ * are pure so the visible transcript is fully unit-testable.
+ */
+export const AGENT_ACTIVITY_TYPE = "background-task-activity";
+const AGENT_ACTIVITY_DETAIL_MAX = 80;
+
+export type AgentActivity =
+	| { kind: "assistant_text"; text: string }
+	| { kind: "reasoning"; text: string }
+	| { kind: "tool_start"; tool: string; argsSummary: string }
+	| { kind: "tool_end"; tool: string; isError: boolean; error?: string };
+
+function readActivityString(record: Record<string, unknown>, key: string): string | undefined {
+	const value = record[key];
+	return typeof value === "string" ? value : undefined;
+}
+
+/** Narrow a parsed `background-task-activity` control payload into a typed {@link AgentActivity}. */
+export function parseAgentActivity(payload: unknown): AgentActivity | undefined {
+	if (typeof payload !== "object" || payload === null) return undefined;
+	const record = payload as Record<string, unknown>;
+	if (record["type"] !== AGENT_ACTIVITY_TYPE) return undefined;
+	const kind = record["kind"];
+	if (kind === "assistant_text" || kind === "reasoning") {
+		const text = readActivityString(record, "text");
+		if (text === undefined) return undefined;
+		return { kind, text };
+	}
+	if (kind === "tool_start") {
+		const tool = readActivityString(record, "tool");
+		if (!tool) return undefined;
+		return { kind, tool, argsSummary: readActivityString(record, "argsSummary") ?? "" };
+	}
+	if (kind === "tool_end") {
+		const tool = readActivityString(record, "tool");
+		if (!tool) return undefined;
+		const activity: AgentActivity = { kind, tool, isError: record["isError"] === true };
+		const error = readActivityString(record, "error");
+		if (error !== undefined && error.trim().length > 0) activity.error = error;
+		return activity;
+	}
+	return undefined;
+}
+
+/**
+ * Render an {@link AgentActivity} into a single transcript line, or `undefined`
+ * when the event carries nothing worth showing (blank text, a successful tool
+ * end). Successful tool ends are intentionally silent: the matching `→` start
+ * line already announced the call, and the next line implies completion.
+ */
+export function formatAgentActivityLine(activity: AgentActivity): string | undefined {
+	if (activity.kind === "assistant_text") {
+		const text = activity.text.replace(/\s+$/u, "");
+		return text.trim().length > 0 ? text : undefined;
+	}
+	if (activity.kind === "reasoning") {
+		const text = activity.text.replace(/\s+$/u, "");
+		return text.trim().length > 0 ? `\u2026 ${text}` : undefined;
+	}
+	if (activity.kind === "tool_start") {
+		const summary = compactWhitespace(activity.argsSummary);
+		const suffix = summary.length > 0 ? ` ${truncateChars(summary, AGENT_ACTIVITY_DETAIL_MAX)}` : "";
+		return `\u2192 ${activity.tool}${suffix}`;
+	}
+	if (!activity.isError) return undefined;
+	const detail = activity.error ? `: ${truncateChars(compactWhitespace(activity.error), AGENT_ACTIVITY_DETAIL_MAX)}` : "";
+	return `\u2717 ${activity.tool} failed${detail}`;
+}
+
 export function shellQuote(value: string): string {
 	return `'${value.replace(/'/g, `'"'"'`)}'`;
 }
@@ -395,3 +474,75 @@ export async function boundedRead(
 export function escapeXml(value: string): string {
 	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
+
+export const UPDATE_COMMAND = "/bg-update";
+
+type ParsedSemver = {
+	major: number;
+	minor: number;
+	patch: number;
+	prerelease: string[];
+};
+
+const SEMVER_PATTERN = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+
+export function parseSemver(value: string): ParsedSemver | undefined {
+	if (typeof value !== "string") return undefined;
+	const match = value.trim().match(SEMVER_PATTERN);
+	if (!match) return undefined;
+	const major = Number(match[1]);
+	const minor = Number(match[2]);
+	const patch = Number(match[3]);
+	if (!Number.isInteger(major) || !Number.isInteger(minor) || !Number.isInteger(patch)) return undefined;
+	const prerelease = match[4] ? match[4].split(".") : [];
+	return { major, minor, patch, prerelease };
+}
+
+function comparePrerelease(a: string[], b: string[]): number {
+	if (a.length === 0 && b.length === 0) return 0;
+	// A version without prerelease identifiers outranks the same core with prerelease identifiers.
+	if (a.length === 0) return 1;
+	if (b.length === 0) return -1;
+	const shared = Math.min(a.length, b.length);
+	for (let i = 0; i < shared; i++) {
+		const idA = a[i];
+		const idB = b[i];
+		if (idA === undefined || idB === undefined) break;
+		if (idA === idB) continue;
+		const numericA = /^\d+$/.test(idA);
+		const numericB = /^\d+$/.test(idB);
+		if (numericA && numericB) {
+			const diff = Number(idA) - Number(idB);
+			if (diff !== 0) return diff < 0 ? -1 : 1;
+			continue;
+		}
+		// Numeric identifiers always have lower precedence than non-numeric identifiers.
+		if (numericA) return -1;
+		if (numericB) return 1;
+		return idA < idB ? -1 : 1;
+	}
+	if (a.length === b.length) return 0;
+	return a.length < b.length ? -1 : 1;
+}
+
+/** Compare two semver strings. Returns -1/0/1, or undefined when either side is not valid semver. */
+export function compareSemver(a: string, b: string): number | undefined {
+	const left = parseSemver(a);
+	const right = parseSemver(b);
+	if (!left || !right) return undefined;
+	if (left.major !== right.major) return left.major < right.major ? -1 : 1;
+	if (left.minor !== right.minor) return left.minor < right.minor ? -1 : 1;
+	if (left.patch !== right.patch) return left.patch < right.patch ? -1 : 1;
+	return comparePrerelease(left.prerelease, right.prerelease);
+}
+
+export function isNewerVersion(latest: string, current: string): boolean {
+	return compareSemver(latest, current) === 1;
+}
+
+/** Footer segment shown only when a newer published version exists; undefined otherwise. */
+export function formatUpdateSegment(latest: string | undefined, current: string): string | undefined {
+	if (!latest) return undefined;
+	if (!isNewerVersion(latest, current)) return undefined;
+	return `\u2b06 v${latest} ${UPDATE_COMMAND}`;
+}

package/src/core/registry.ts

@@ -9,8 +9,10 @@ import {
 	boundedRead,
 	deriveTaskNameFromCommand,
 	escapeXml,
+	formatAgentActivityLine,
 	formatDuration,
 	normalizeTaskName,
+	parseAgentActivity,
 	sanitizePathSegment,
 	shellInvocation,
 	shellQuote,
@@ -221,6 +223,36 @@ function emitUnifiedTelemetry(payload) {
   process.stdout.write(JSON.stringify(out) + "\\n");
 }
 
+function emitActivity(activity) {
+  process.stdout.write(JSON.stringify({ type: "background-task-activity", ...activity }) + "\\n");
+}
+
+function summarizeArgs(args) {
+  if (!args || typeof args !== "object") return "";
+  const pick = (value) => {
+    if (typeof value === "string" && value.trim()) return value.trim().slice(0, 200);
+    if (typeof value === "number" && Number.isFinite(value)) return String(value);
+    return undefined;
+  };
+  const preferred = ["path", "file_path", "file", "filename", "command", "cmd", "pattern", "query", "url", "name", "value", "text", "message"];
+  for (const key of preferred) { const summary = pick(args[key]); if (summary) return summary; }
+  for (const key of Object.keys(args)) { const summary = pick(args[key]); if (summary) return summary; }
+  return "";
+}
+
+function emitAssistantActivity(message) {
+  const content = message && Array.isArray(message.content) ? message.content : [];
+  for (const part of content) {
+    if (!part || typeof part !== "object") continue;
+    if (part.type === "text" && typeof part.text === "string" && part.text.trim()) {
+      emitActivity({ kind: "assistant_text", text: part.text });
+    } else if (part.type === "thinking" || part.type === "reasoning") {
+      const text = typeof part.text === "string" ? part.text : (typeof part.thinking === "string" ? part.thinking : "");
+      if (text.trim()) emitActivity({ kind: "reasoning", text: text });
+    }
+  }
+}
+
 function resolveModelName(fromMessage, fromArgs, providerFromArgs) {
   const message = fromMessage ? String(fromMessage) : "";
   const args = fromArgs ? String(fromArgs) : "";
@@ -320,7 +352,6 @@ function emitToolTelemetry() {
 const parsed = parseInvocation(process.argv.slice(2));
 const child = spawn("pi", parsed.args, { stdio: ["ignore", "pipe", "pipe"], env: process.env });
 let buffer = "";
-let finalText = "";
 
 if (!parsed.parseJson) {
   child.stdout.pipe(process.stdout);
@@ -338,7 +369,6 @@ child.on("error", (error) => {
 });
 child.on("close", (code, signal) => {
   if (parsed.parseJson && buffer.trim()) processLine(buffer);
-  if (finalText) process.stdout.write(finalText.endsWith("\\n") ? finalText : finalText + "\\n");
   if (signal) process.kill(process.pid, signal);
   process.exit(code ?? 0);
 });
@@ -353,22 +383,23 @@ function processLine(line) {
     return;
   }
   if (event.type === "tool_execution_start") {
-    markToolStarted(event.toolCallId || event.tool_call_id, event.toolName || event.tool_name);
+    const toolName = event.toolName || event.tool_name || "tool";
+    markToolStarted(event.toolCallId || event.tool_call_id, toolName);
+    emitActivity({ kind: "tool_start", tool: String(toolName), argsSummary: summarizeArgs(event.args || event.arguments || event.input || event.parameters) });
     emitToolTelemetry();
     return;
   }
   if (event.type === "tool_execution_end") {
+    const toolName = event.toolName || event.tool_name || "tool";
     if (event.isError) markToolFailed(event.toolCallId || event.tool_call_id);
+    emitActivity({ kind: "tool_end", tool: String(toolName), isError: !!event.isError, error: typeof event.error === "string" ? event.error : undefined });
     emitToolTelemetry();
     return;
   }
   if (event.type === "message_end" && event.message && event.message.role === "assistant") {
+    emitAssistantActivity(event.message);
     countToolCallsFromMessage(event.message);
     emitMessageTelemetry(event.message, parsed.model, parsed.provider);
-    finalText = (event.message.content || [])
-      .filter((part) => part && part.type === "text" && part.text)
-      .map((part) => part.text)
-      .join("\\n");
   }
 }
 `;
@@ -458,6 +489,13 @@ function normalizeToolUsage(value: unknown): TaskToolUsage | undefined {
 	return total > 0 || failed > 0 ? { total, failed, byName } : undefined;
 }
 
+type TelemetryDelta = {
+	context?: TaskContextUsage | undefined;
+	tokens?: TaskTokenUsage | undefined;
+	tools?: TaskToolUsage | undefined;
+	model?: string | undefined;
+};
+
 export class BackgroundTaskRegistry {
 	private readonly tasks = new Map<string, BgTask>();
 	private runtimeDir: RuntimeDir | undefined;
@@ -585,6 +623,7 @@ export class BackgroundTaskRegistry {
 				const wrapperAbsPath = join(dir.abs, `${id}.pi-telemetry-wrapper.cjs`);
 				await writeFile(wrapperAbsPath, createPiTelemetryWrapperSource(buildModelWindowIndex(ctx)), "utf8");
 				commandToSpawn = `pi() { node ${shellQuote(wrapperAbsPath)} "$@"; }\n${normalizedCommand}`;
+				task.telemetryWrapped = true;
 			}
 			const invocation = shellInvocation(commandToSpawn, this.platform, this.env);
 			const child = this.spawn(invocation.shell, invocation.args, {
@@ -598,11 +637,11 @@ export class BackgroundTaskRegistry {
 			task.child = child;
 			task.pid = child.pid;
 
-			child.stdout?.on("data", (data) => this.appendToOutput(task, data));
-			child.stderr?.on("data", (data) => this.appendToOutput(task, data));
+			child.stdout?.on("data", (data) => this.appendChildOutput(task, data, "stdout"));
+			child.stderr?.on("data", (data) => this.appendChildOutput(task, data, "stderr"));
 
 			child.on("error", (error) => {
-				this.appendToOutput(task, `\n[background task spawn error: ${error.message}]\n`);
+				this.writeNotice(task, `\n[background task spawn error: ${error.message}]\n`);
 				void this.finalizeTask(task, "failed", null, undefined, error.message);
 			});
 
@@ -631,7 +670,7 @@ export class BackgroundTaskRegistry {
 					if (task.status !== "running") return;
 					task.killKind = "timeout";
 					task.error = `Timed out after ${timeoutSeconds}s`;
-					this.appendToOutput(task, `\n[background task timeout: ${task.error}]\n`);
+					this.writeNotice(task, `\n[background task timeout: ${task.error}]\n`);
 					try {
 						this.requestKill(task, "SIGTERM");
 					} catch (error) {
@@ -645,7 +684,7 @@ export class BackgroundTaskRegistry {
 			return task;
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);
-			this.appendToOutput(task, `\n[background task spawn exception: ${message}]\n`);
+			this.writeNotice(task, `\n[background task spawn exception: ${message}]\n`);
 			await this.finalizeTask(task, "failed", null, undefined, message);
 			throw new Error(`Failed to start background task: ${message}`);
 		}
@@ -760,11 +799,16 @@ export class BackgroundTaskRegistry {
 		if (lastXmlOpen > lastXmlClose) retained = telemetryText.slice(lastXmlOpen);
 		task.contextUsageBuffer = retained.slice(-TELEMETRY_BUFFER_CHARS);
 
+		this.commitTelemetry(task, { context: latestContext, tokens: latestTokens, tools: latestTools, model: latestModel });
+	}
+
+	/** Apply the latest parsed telemetry to a task, persisting metadata and notifying the UI only on change. */
+	private commitTelemetry(task: BgTask, next: TelemetryDelta): void {
 		const before = JSON.stringify({ contextUsage: task.contextUsage, tokenUsage: task.tokenUsage, toolUsage: task.toolUsage, model: task.model });
-		task.contextUsage = latestContext;
-		task.tokenUsage = latestTokens;
-		task.toolUsage = latestTools;
-		task.model = latestModel;
+		if (next.context !== undefined) task.contextUsage = next.context;
+		if (next.tokens !== undefined) task.tokenUsage = next.tokens;
+		if (next.tools !== undefined) task.toolUsage = next.tools;
+		if (next.model !== undefined) task.model = next.model;
 		const after = JSON.stringify({ contextUsage: task.contextUsage, tokenUsage: task.tokenUsage, toolUsage: task.toolUsage, model: task.model });
 		if (before !== after) {
 			this.onChange();
@@ -774,11 +818,10 @@ export class BackgroundTaskRegistry {
 		}
 	}
 
-	private appendToOutput(task: BgTask, data: Buffer | string): void {
+	/** Cap-enforcing sink for all persisted task output; terminates the task once the byte cap is exceeded. */
+	private writeToStream(task: BgTask, buffer: Buffer): void {
 		if (!task.stream || task.stream.destroyed) return;
-		const buffer = Buffer.isBuffer(data) ? data : Buffer.from(data, "utf8");
 		if (buffer.length === 0) return;
-		this.ingestTelemetry(task, buffer.toString("utf8"));
 
 		const nextBytes = task.bytesWritten + buffer.length;
 		if (nextBytes <= this.maxOutputBytes) {
@@ -809,6 +852,95 @@ export class BackgroundTaskRegistry {
 		}
 	}
 
+	/** Persist an internally generated notice (spawn/timeout/cap diagnostics) verbatim. */
+	private writeNotice(task: BgTask, text: string): void {
+		if (!text) return;
+		this.writeToStream(task, Buffer.from(text, "utf8"));
+	}
+
+	private appendChildOutput(task: BgTask, data: Buffer | string, source: "stdout" | "stderr"): void {
+		if (!task.stream || task.stream.destroyed) return;
+		const buffer = Buffer.isBuffer(data) ? data : Buffer.from(data, "utf8");
+		if (buffer.length === 0) return;
+		if (task.telemetryWrapped) {
+			// Wrapped Pi agents stream control lines on stdout (telemetry + activity); child
+			// stderr is raw diagnostics and is always passed through to the transcript verbatim.
+			if (source === "stdout") this.processAgentStdout(task, buffer.toString("utf8"));
+			else this.writeToStream(task, buffer);
+			return;
+		}
+		this.ingestTelemetry(task, buffer.toString("utf8"));
+		this.writeToStream(task, buffer);
+	}
+
+	/** Reconstruct wrapped-agent stdout into whole control lines, routing telemetry to metrics and activity to the transcript. */
+	private processAgentStdout(task: BgTask, text: string): void {
+		const buffered = `${task.agentStdoutBuffer ?? ""}${text}`;
+		const lastNewline = buffered.lastIndexOf("\n");
+		task.agentStdoutBuffer = lastNewline >= 0 ? buffered.slice(lastNewline + 1) : buffered;
+		if (lastNewline < 0) return;
+		const latest: TelemetryDelta = {};
+		for (const line of buffered.slice(0, lastNewline).split("\n")) this.consumeAgentLine(task, line, latest);
+		this.commitTelemetry(task, latest);
+	}
+
+	/** Flush a trailing partial wrapped-agent line on finalize so the last transcript fragment is never lost. */
+	private flushAgentStdout(task: BgTask): void {
+		const remainder = task.agentStdoutBuffer;
+		if (!remainder) return;
+		task.agentStdoutBuffer = "";
+		const latest: TelemetryDelta = {};
+		this.consumeAgentLine(task, remainder, latest);
+		this.commitTelemetry(task, latest);
+	}
+
+	private consumeAgentLine(task: BgTask, rawLine: string, latest: TelemetryDelta): void {
+		const line = rawLine.replace(/\r$/, "");
+		const trimmed = line.trim();
+		if (!trimmed) return;
+		if (!trimmed.startsWith("{") || !trimmed.endsWith("}")) {
+			this.writeNotice(task, `${line}\n`);
+			return;
+		}
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(trimmed);
+		} catch {
+			this.writeNotice(task, `${line}\n`);
+			return;
+		}
+		if (typeof parsed !== "object" || parsed === null) {
+			this.writeNotice(task, `${line}\n`);
+			return;
+		}
+		const record = parsed as Record<string, unknown>;
+		const type = record["type"];
+		if (type === "background-task-context-usage") {
+			const context = normalizeContextUsage(parsed);
+			if (context) latest.context = context;
+			return;
+		}
+		if (type === "background-task-telemetry") {
+			const context = normalizeContextUsage(record["contextUsage"]);
+			if (context) latest.context = context;
+			const tokens = normalizeTokenUsage(record["tokenUsage"]);
+			if (tokens) latest.tokens = tokens;
+			const tools = normalizeToolUsage(record["toolUsage"]);
+			if (tools) latest.tools = tools;
+			const model = normalizeModel(record["model"]);
+			if (model) latest.model = model;
+			return;
+		}
+		const activity = parseAgentActivity(parsed);
+		if (activity) {
+			const formatted = formatAgentActivityLine(activity);
+			if (formatted) this.writeNotice(task, `${formatted}\n`);
+			return;
+		}
+		// Unknown JSON object: pass through to the transcript rather than silently dropping it.
+		this.writeNotice(task, `${line}\n`);
+	}
+
 	private requestKill(task: BgTask, signal: NodeJS.Signals = "SIGTERM"): void {
 		if (task.status !== "running") {
 			throw new Error(`Task ${task.id} is ${task.status}, not running`);
@@ -921,6 +1053,7 @@ export class BackgroundTaskRegistry {
 		task.signal = signal ?? null;
 		task.endTime = this.now();
 		if (error) task.error = error;
+		if (task.telemetryWrapped) this.flushAgentStdout(task);
 		if (task.stream && !task.stream.destroyed) task.stream.end();
 
 		for (const waiter of task.waiters.splice(0)) waiter();

package/src/core/update-check.ts

@@ -0,0 +1,99 @@
+import { readFileSync } from "node:fs";
+
+/**
+ * Typed, offline-safe boundary for the "update available" footer notice.
+ *
+ * All network access flows through an injectable {@link FetchLike} so unit tests
+ * never touch the real npm registry. Every failure path (offline, timeout, bad
+ * status, malformed payload) resolves to `undefined` and never throws, so the
+ * footer/session can never hang or error because of an update check.
+ */
+
+export const DEFAULT_NPM_REGISTRY_URL = "https://registry.npmjs.org";
+export const DEFAULT_UPDATE_TIMEOUT_MS = 2000;
+
+export type FetchResponseLike = {
+	readonly ok: boolean;
+	readonly status: number;
+	json(): Promise<unknown>;
+};
+
+export type FetchLike = (url: string, init: { signal: AbortSignal }) => Promise<FetchResponseLike>;
+
+export type FetchLatestVersionOptions = {
+	packageName: string;
+	registryUrl?: string;
+	timeoutMs?: number;
+	fetchImpl?: FetchLike;
+	onError?: (error: Error) => void;
+};
+
+export type PackageInfo = {
+	name?: string;
+	version?: string;
+};
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+	if (typeof value !== "object" || value === null) return undefined;
+	return value as Record<string, unknown>;
+}
+
+function readNonEmptyString(record: Record<string, unknown>, key: string): string | undefined {
+	const value = record[key];
+	if (typeof value !== "string") return undefined;
+	const trimmed = value.trim();
+	return trimmed.length > 0 ? trimmed : undefined;
+}
+
+/** Narrow an npm registry `<pkg>/latest` JSON payload to its `version` string. */
+export function parseLatestVersionPayload(payload: unknown): string | undefined {
+	const record = asRecord(payload);
+	if (!record) return undefined;
+	return readNonEmptyString(record, "version");
+}
+
+/** Narrow a parsed `package.json` payload to the fields this extension needs. */
+export function parsePackageInfo(payload: unknown): PackageInfo {
+	const record = asRecord(payload);
+	if (!record) return {};
+	const info: PackageInfo = {};
+	const name = readNonEmptyString(record, "name");
+	const version = readNonEmptyString(record, "version");
+	if (name !== undefined) info.name = name;
+	if (version !== undefined) info.version = version;
+	return info;
+}
+
+const realFetch: FetchLike = (url, init) => fetch(url, init);
+
+/** Time-boxed, never-throwing lookup of the latest published version of a package. */
+export async function fetchLatestVersion(options: FetchLatestVersionOptions): Promise<string | undefined> {
+	const registryUrl = (options.registryUrl ?? DEFAULT_NPM_REGISTRY_URL).replace(/\/+$/, "");
+	const timeoutMs = options.timeoutMs ?? DEFAULT_UPDATE_TIMEOUT_MS;
+	const doFetch = options.fetchImpl ?? realFetch;
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), timeoutMs);
+	try {
+		const url = `${registryUrl}/${encodeURIComponent(options.packageName)}/latest`;
+		const response = await doFetch(url, { signal: controller.signal });
+		if (!response.ok) return undefined;
+		const payload = await response.json();
+		return parseLatestVersionPayload(payload);
+	} catch (error) {
+		options.onError?.(error instanceof Error ? error : new Error(String(error)));
+		return undefined;
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
+/** Read `name`/`version` from a local `package.json`, returning `{}` on every failure. */
+export function readPackageInfo(packageJsonUrl: URL | string, onError?: (error: Error) => void): PackageInfo {
+	try {
+		const parsed: unknown = JSON.parse(readFileSync(packageJsonUrl, "utf8"));
+		return parsePackageInfo(parsed);
+	} catch (error) {
+		onError?.(error instanceof Error ? error : new Error(String(error)));
+		return {};
+	}
+}

package/src/extension.ts

@@ -7,6 +7,8 @@ import {
 	MAX_LOG_BYTES,
 	deriveTaskNameFromCommand,
 	formatSnapshotList,
+	formatUpdateSegment,
+	isNewerVersion,
 	normalizeMaxBytes,
 	normalizeTaskName,
 	parseBgCommandArgs,
@@ -20,6 +22,7 @@ import {
 	type BgTaskSnapshot,
 	type StartTaskOptions,
 } from "./core/common.js";
+import { fetchLatestVersion, readPackageInfo, type FetchLatestVersionOptions } from "./core/update-check.js";
 import { BackgroundTaskRegistry } from "./core/registry.js";
 import { BackgroundTasksManager, type BackgroundTaskForUi, type TaskManagerResult } from "./ui/background-tasks-manager.js";
 
@@ -35,6 +38,13 @@ import { BackgroundTasksManager, type BackgroundTaskForUi, type TaskManagerResul
 
 const STATUS_INTERVAL_MS = 1000;
 const COMMAND_PREVIEW_CHARS = 90;
+const GIT_INSTALL_TARGET = "git:github.com/ismailsaleekh/pi-background-tasks";
+
+const packageInfo = readPackageInfo(new URL("../package.json", import.meta.url), (error) => {
+	console.error(`[background-tasks] failed to read package version: ${error.message}`);
+});
+const PACKAGE_NAME = packageInfo.name ?? "pi-background-tasks";
+const PACKAGE_VERSION = packageInfo.version;
 const LIGHT_BLUE_BG = "\x1b[48;2;183;223;255m";
 const LIGHT_BLUE_FG = "\x1b[38;2;11;70;110m";
 const ANSI_RESET = "\x1b[0m";
@@ -88,6 +98,8 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
 	let currentCtx: ExtensionContext | undefined;
 	let dockOpen = false;
 	let statusInterval: NodeJS.Timeout | undefined;
+	let latestKnownVersion: string | undefined;
+	let updateCheckStarted = false;
 
 	const registry = new BackgroundTaskRegistry({
 		onChange: () => updateUi(),
@@ -129,9 +141,10 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
 			const unseenStopped = allTasks.filter((task) => task.status === "killed" && !seenTaskIds.has(task.id));
 			const unseenDone = allTasks.filter((task) => task.status === "completed" && !seenTaskIds.has(task.id));
 			const unseenFinishedCount = unseenFailed.length + unseenStopped.length + unseenDone.length;
+			const updateSegment = formatUpdateSegment(latestKnownVersion, PACKAGE_VERSION ?? "");
 			ctx.ui.setWidget("background-tasks", undefined);
 			if (running.length === 0 && unseenFinishedCount === 0) {
-				ctx.ui.setStatus("background-tasks", undefined);
+				ctx.ui.setStatus("background-tasks", updateSegment ? lightBlue(` bg ${updateSegment} `) : undefined);
 				return;
 			}
 
@@ -141,7 +154,9 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
 			if (unseenStopped.length > 0) parts.push(`${unseenStopped.length} stopped`);
 			if (unseenDone.length > 0) parts.push(`${unseenDone.length} done`);
 			const entryHint = dockOpen ? "focused" : `Shift↓${unseenFinishedCount > 0 ? " · /bg-clear" : ""}`;
-			const label = ` bg ${parts.join(" · ")} · ${entryHint} `;
+			const segments = [...parts, entryHint];
+			if (updateSegment) segments.push(updateSegment);
+			const label = ` bg ${segments.join(" · ")} `;
 			ctx.ui.setStatus("background-tasks", lightBlue(label));
 		} catch (error) {
 			console.error(`[background-tasks] UI update failed: ${error instanceof Error ? error.message : String(error)}`);
@@ -227,6 +242,26 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
 		return new Text(`${theme.fg(color, `[bg ${status}]`)} ${theme.fg("accent", name)} ${theme.fg("dim", `(${id})`)}${output}${error}`, 0, 0);
 	});
 
+	async function scheduleUpdateCheck(ctx: ExtensionContext): Promise<void> {
+		if (updateCheckStarted) return;
+		updateCheckStarted = true;
+		const env = process.env;
+		if (env["PI_BG_DISABLE_UPDATE_CHECK"] === "1") return;
+		if (env["PI_OFFLINE"] === "1") return;
+		if (!PACKAGE_VERSION) return;
+		const options: FetchLatestVersionOptions = {
+			packageName: PACKAGE_NAME,
+			onError: (error) => console.error(`[background-tasks] update check skipped: ${error.message}`),
+		};
+		const registryUrl = env["PI_BG_REGISTRY_URL"];
+		if (registryUrl) options.registryUrl = registryUrl;
+		const latest = await fetchLatestVersion(options);
+		if (latest && isNewerVersion(latest, PACKAGE_VERSION)) {
+			latestKnownVersion = latest;
+			updateUi(ctx);
+		}
+	}
+
 	pi.on("session_start", async (_event, ctx) => {
 		registry.setShuttingDown(false);
 		currentCtx = ctx;
@@ -234,6 +269,8 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
 		updateUi(ctx);
 		if (statusInterval) clearInterval(statusInterval);
 		statusInterval = setInterval(() => updateUi(), STATUS_INTERVAL_MS);
+		// One-shot, non-blocking: never awaited on the session-start path or the status tick.
+		void scheduleUpdateCheck(ctx);
 	});
 
 	pi.on("session_shutdown", async (_event, ctx) => {
@@ -301,6 +338,28 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
 		},
 	});
 
+	pi.registerCommand("bg-update", {
+		description: "Show how to update pi-background-tasks to the latest published version",
+		handler: async (_args, ctx) => {
+			const current = PACKAGE_VERSION ?? "unknown";
+			const latest = latestKnownVersion;
+			const pinnedNpm = latest ? `${PACKAGE_NAME}@${latest}` : `${PACKAGE_NAME}@<version>`;
+			const pinnedGit = latest ? `${GIT_INSTALL_TARGET}@v${latest}` : `${GIT_INSTALL_TARGET}@<tag>`;
+			const lines = [
+				latest
+					? `pi-background-tasks ${current} is installed; ${latest} is the latest published version.`
+					: `pi-background-tasks ${current} is installed.`,
+				"Update from npm:",
+				`  pi install npm:${PACKAGE_NAME}@latest`,
+				`  pi install npm:${pinnedNpm}`,
+				"Or update from git tags:",
+				`  pi install ${pinnedGit}`,
+				"This command only prints update instructions; it does not install or self-update.",
+			];
+			ctx.ui.notify(lines.join("\n"), "info");
+		},
+	});
+
 	pi.registerShortcut("shift+down" satisfies KeyId, {
 		description: "Open focused background task footer dock",
 		handler: async (ctx) => {

package/src/ui/background-tasks-manager.ts

@@ -16,7 +16,10 @@ export type BackgroundTaskForUi = BgTaskSnapshot & { name: string; outputAbsPath
 type BgTask = BackgroundTaskForUi;
 
 const STATUS_INTERVAL_MS = 1000;
-const DETAIL_TAIL_BYTES = 8 * 1024;
+// Detail-view scrollback reservoir. Larger than the model-facing log cap because
+// this is a UI-only read; a local 128KiB tail read per second is negligible and
+// gives thousands of lines of scrollback when the user pauses the live tail.
+const DETAIL_TAIL_BYTES = 128 * 1024;
 const LIST_VISIBLE_ROWS = 14;
 const DETAIL_VISIBLE_OUTPUT_LINES = 12;
 const LIGHT_BLUE_BG = "\x1b[48;2;183;223;255m";
@@ -28,6 +31,11 @@ function formatTime(timestamp: number): string {
 	return new Date(timestamp).toLocaleTimeString();
 }
 
+/** Normalize raw output bytes into display lines, dropping only the trailing empty line from a final newline. */
+function toOutputLines(content: string): string[] {
+	return content.replace(/\r/g, "").split("\n").filter((line, index, array) => line.length > 0 || index < array.length - 1);
+}
+
 function padAnsi(value: string, width: number): string {
 	return value + " ".repeat(Math.max(0, width - visibleWidth(value)));
 }
@@ -168,7 +176,9 @@ export class BackgroundTasksManager implements Component {
 	private listScroll = 0;
 	private detailTaskId: string | undefined;
 	private showHistory = false;
-	private tailText = "";
+	private detailLines: string[] = [];
+	private detailFollow = true;
+	private detailScrollTop = 0;
 	private tailBytesRead = 0;
 	private tailTotalBytes = 0;
 	private tailTruncated = false;
@@ -309,7 +319,25 @@ export class BackgroundTasksManager implements Component {
 			this.tui.requestRender();
 			return;
 		}
+		if (matchesKey(data, "up")) {
+			this.scrollDetail(-1);
+			return;
+		}
+		if (matchesKey(data, "down")) {
+			this.scrollDetail(1);
+			return;
+		}
+		if (matchesKey(data, "pageUp")) {
+			this.scrollDetail(-DETAIL_VISIBLE_OUTPUT_LINES);
+			return;
+		}
+		if (matchesKey(data, "pageDown")) {
+			this.scrollDetail(DETAIL_VISIBLE_OUTPUT_LINES);
+			return;
+		}
 		if (data === "r") {
+			this.detailFollow = true;
+			this.detailScrollTop = 0;
 			void this.refreshTail();
 			return;
 		}
@@ -343,7 +371,9 @@ export class BackgroundTasksManager implements Component {
 	private openDetail(taskId: string): void {
 		this.detailTaskId = taskId;
 		this.mode = "detail";
-		this.tailText = "";
+		this.detailLines = [];
+		this.detailFollow = true;
+		this.detailScrollTop = 0;
 		this.tailError = undefined;
 		this.options.markSeen(taskId);
 		void this.refreshTail();
@@ -425,20 +455,40 @@ export class BackgroundTasksManager implements Component {
 		this.tui.requestRender();
 	}
 
+	/** Scroll the detail output window. Scrolling up pauses the live tail; reaching the bottom resumes it. */
+	private scrollDetail(delta: number): void {
+		const maxTop = Math.max(0, this.detailLines.length - DETAIL_VISIBLE_OUTPUT_LINES);
+		if (maxTop === 0) return;
+		if (this.detailFollow) {
+			this.detailFollow = false;
+			this.detailScrollTop = maxTop;
+		}
+		this.detailScrollTop = Math.min(maxTop, Math.max(0, this.detailScrollTop + delta));
+		if (this.detailScrollTop >= maxTop) {
+			this.detailFollow = true;
+			this.detailScrollTop = 0;
+			void this.refreshTail();
+		}
+		this.tui.requestRender();
+	}
+
 	private async refreshTail(): Promise<void> {
 		const task = this.detailTask();
 		if (!task) return;
+		// While the user has scrolled up, the buffer is frozen so their view stays stable.
+		if (!this.detailFollow) return;
 		try {
 			if (!existsSync(task.outputAbsPath)) {
-				this.tailText = "";
+				this.detailLines = [];
 				this.tailBytesRead = 0;
 				this.tailTotalBytes = 0;
 				this.tailTruncated = false;
 				this.tailError = `Output file not found: ${task.outputPath}`;
+				this.tui.requestRender();
 				return;
 			}
 			const read = await boundedRead(task.outputAbsPath, DETAIL_TAIL_BYTES, true);
-			this.tailText = read.content;
+			this.detailLines = toOutputLines(read.content);
 			this.tailBytesRead = read.bytesRead;
 			this.tailTotalBytes = read.totalBytes;
 			this.tailTruncated = read.truncated;
@@ -593,7 +643,7 @@ export class BackgroundTasksManager implements Component {
 		body.push(...this.renderOutputBox(width - 4));
 		if (this.actionMessage) body.push(this.theme.fg("warning", ` ${this.actionMessage}`));
 		const subtitle = `${task.id} · ${task.status === "running" ? "live tail refreshes every second" : "final output"}`;
-		const footer = ` ${this.theme.fg("dim", "← list · r refresh · k stop · R rerun · c path · x close")}`;
+		const footer = ` ${this.theme.fg("dim", "↑/↓ scroll · ← list · r refresh · k stop · R rerun · c path · x close")}`;
 		return this.frame(`bg: ${truncateChars(name, 64)}`, subtitle, body, footer, width);
 	}
 
@@ -605,18 +655,30 @@ export class BackgroundTasksManager implements Component {
 		const lines = [top];
 		if (this.tailError) {
 			lines.push(row(this.theme.fg("error", this.tailError)));
-		} else if (!this.tailText) {
+		} else if (this.detailLines.length === 0) {
 			lines.push(row(this.theme.fg("dim", "No output yet")));
 		} else {
-			const outputLines = this.tailText.replace(/\r/g, "").split("\n").filter((line, index, array) => line.length > 0 || index < array.length - 1);
-			const visible = outputLines.slice(-DETAIL_VISIBLE_OUTPUT_LINES);
-			for (const line of visible) lines.push(row(this.theme.fg("toolOutput", line)));
+			const maxTop = Math.max(0, this.detailLines.length - DETAIL_VISIBLE_OUTPUT_LINES);
+			const start = this.detailFollow ? maxTop : Math.min(this.detailScrollTop, maxTop);
+			const windowLines = this.detailLines.slice(start, start + DETAIL_VISIBLE_OUTPUT_LINES);
+			for (const line of windowLines) lines.push(row(this.theme.fg("toolOutput", line)));
 		}
 		while (lines.length < DETAIL_VISIBLE_OUTPUT_LINES + 1) lines.push(row());
 		lines.push(bottom);
-		const suffix = this.tailTruncated ? ` of ${formatSize(this.tailTotalBytes)}` : "";
-		lines.push(` ${this.theme.fg("dim", `Showing tail ${formatSize(this.tailBytesRead)}${suffix}`)}`);
+		lines.push(` ${this.theme.fg("dim", this.outputStatusLine())}`);
 		return lines;
 	}
+
+	private outputStatusLine(): string {
+		const total = this.detailLines.length;
+		if (!this.detailFollow && total > 0) {
+			const maxTop = Math.max(0, total - DETAIL_VISIBLE_OUTPUT_LINES);
+			const start = Math.min(this.detailScrollTop, maxTop);
+			const end = Math.min(total, start + DETAIL_VISIBLE_OUTPUT_LINES);
+			return `lines ${start + 1}\u2013${end} of ${total} · ↑/↓ PgUp/PgDn scroll · ↓ at bottom follows`;
+		}
+		const suffix = this.tailTruncated ? ` of ${formatSize(this.tailTotalBytes)}` : "";
+		return `following tail ${formatSize(this.tailBytesRead)}${suffix} · ↑ scroll`;
+	}
 }