@maxiaochao/pi-toolkit 0.13.4 → 0.13.6

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 2026-10-22 - v0.13.6
+
+- background-tasks v0.1.1: batch unread completions at tool boundaries, preserve interrupted runs, and provide non-polling startup guidance
+
+## 2026-10-22 - v0.13.5
+
+- herdr-subagents v0.7.4: preserve Codex patch editing in child allowlists and hide the parent shortcut footer hint
+- Herdr Subagents: hide the child parent-navigation footer hint while keeping `Alt+P`, `/parent`, and other extensions' editor status.
+- Herdr Subagents: permit `apply_patch` in edit-capable child CLI allowlists so editor switching does not remove the only active editing tool; preserve read-only limits and native fallback.
+
 ## 2026-10-22 - v0.13.4
 
 - herdr-subagents v0.7.3: keep Persona selection lists concise
@@ -13,6 +23,10 @@
 
 ## Unreleased
 
+- Background Tasks: expose the approved non-polling startup guidance to direct and Codemode callers. Retain results after a user interrupt without restarting the agent, then hand them to the next user-message run; verify native tool batches, interrupts and compaction cancellation without changing Pi itself.
+- Background Tasks: merge unread completions at the next safe tool boundary, consume pending reminders on terminal-output reads, and show actual completion times. Preserve automatic idle notification without adding a pause switch or changing Herdr execution/global queue settings.
+- Background Tasks: reduce busy-session notification checks with exponential backoff capped at 30 seconds, without expiring unread results or delaying normal tool-boundary delivery.
+
 - Herdr Subagents: show only Persona names and descriptions in model-facing selection lists, preserving diagnostics and detailed user-facing inspection.
 - Make Agent Team user-invoked only through `/skill:agent-team`, hidden from automatic model selection.
 - Add `npm run release:check -- vX.Y.Z` to wait for GitHub publication and verify exact npm versions, remote tags, integrity, and all tarball contents against the release commit, including coordinated child releases.

package/README.md

@@ -40,8 +40,12 @@ Restart Pi after updating. `pi update --extensions` has the same effect when upd
 
 Each child README owns its feature description, motivation or upstream alignment, examples, screenshots/demos, configuration, and test documentation.
 
+Background Tasks combines unread completions after any current tool batch, before the next model request, including when the main agent waits for a synchronous subagent. Idle completions wake the main agent automatically, except after a user interrupt: results remain available until the next user-message run. Reading a finished task's `output` through the tool consumes its pending reminder. Startup guidance tells direct and Codemode callers to continue independent work or end the turn, not query to wait. See [completion delivery](packages/background-tasks/README.md#user-controls-and-status).
+
 Codex Edit personal routing rules belong in `~/.pi/agent/codex-edit.json`, not inside `node_modules`. User fields override bundled defaults; `models` replaces the complete default list. The file survives package updates and is shared by parent sessions and explicitly configured subagents using the same agent directory. Use `/reload` after editing it, and start new subagents. See [Codex Edit configuration](packages/codex-edit/README.md#configuration).
 
+Child panes keep `Alt+P` and `/parent` navigation without a persistent shortcut footer hint. Editor status remains owned by the loaded editor extension.
+
 Herdr Subagents tasks require an explicit `agent` Persona; no default `worker` is selected. Choose `reviewer` for independent reviews of proposals, designs, documents, implementations, or analysis; `explorer` for codebase investigation; `worker` for file-changing work; and `analyst` for charter-defined agent-team roles. Control `list` returns names and descriptions for selection, plus configuration diagnostics when present; use `/herdr-subagents agents` and `settings` for detailed configuration. See [built-in Personas](packages/herdr-subagents/README.md#built-in-personas) for selection guidance and the distinction between parent-facing descriptions and child instructions. Personas can opt into local extension files or npm/git Pi packages through `extensions`. Set top-level `defaultExtensions` in `~/.pi/agent/herdr-subagents.json` (or project `.pi/herdr-subagents.json`) to share a fallback list; Persona-specific lists take precedence, and `[]` clears inherited sources. This uses native Pi package semantics: package-provided skills, prompt templates, and themes may also load, and `--no-skills` does not exclude explicitly selected package skills. See the [extension-source contract](packages/herdr-subagents/README.md#explicit-extension-sources-and-pi-packages) for precedence, isolation, and examples. The [real Herdr smoke test](packages/herdr-subagents/TESTING.md) preserves the configured analyst model and explicit authentication extensions while isolating unrelated settings.
 
 Multiple standalone children may be installed together. `pi-openai-account-pool` may also be installed alongside the complete toolkit because the toolkit does not embed it. Every other child in the table above, including `pi-background-tasks`, is embedded, so a second install exposes the same resource twice.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.13.4",
+  "version": "0.13.6",
   "description": "Personal pi coding agent toolkit: background tasks, scheduler, /btw, /cache_export, apply_patch, browser automation, and bundled theme/skills.",
   "type": "module",
   "workspaces": [

package/packages/background-tasks/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 2026-10-22 - v0.1.1
+
+- batch unread completions at tool boundaries, preserve interrupted runs, and provide non-polling startup guidance
+- Include the approved non-polling startup guidance in the tool description, model-visible start result and Codemode's structured result. Keep ordinary output reads separate from waiting.
+- Follow OMP's user-interrupt semantics: retain pending and later results without restarting the stopped agent, then hand unread results to the next user-message run. Do not confuse manual-compaction cancellation with an agent interrupt; add no switch or waiting tool.
+- Cover direct native tool batches as well as Codemode, and real user interrupts before/after shell completion. Determine native compaction cancellation from lifecycle state instead of error wording.
+- Deliver pending completions together after the current tool batch, before the next model request, instead of queuing one follow-up turn per task after the final report. Idle completions still wake the main agent automatically.
+- Consume pending reminders when tool callers read terminal output, show actual completion times, and clear pending notification timers on session changes. Keep process/subagent execution and global queue settings unchanged; add no notification pause switch.
+- Add a real-Pi four-completion queue regression with direct nested/Codemode reads, alongside deterministic busy/idle, consumption and abort/error checks.
+- Back off busy-session notification checks through 1/2/4/8/16/30-second intervals, capped at 30 seconds without a retry limit or unread-result expiry. Tool boundaries still deliver immediately; fresh batches reset the delay. Keep the generic idle check instead of subscribing to individual busy-operation events.
+- Verify native Pi manual compaction success, summary failure and cancellation with real shell jobs finishing during an offline summary request; pending results wake the main agent once after compaction, without another user prompt.
+
 ## 2026-10-20 - v0.1.0
 
 - bundle background shell tasks with runtime limits, bounded logs, completion notifications and /bg controls

package/packages/background-tasks/README.md

@@ -12,6 +12,8 @@ A command such as `sleep 60; python3 ...` can spend most of its time waiting to
 
 It uses Pi's public `createLocalBashOperations()` backend for shell execution and process-group cancellation. It adds session ownership, bounded logs, status, and completion messages. It neither replaces Bash nor starts another model or Herdr pane.
 
+Completion delivery follows [oh-my-pi's yield-queue approach](https://github.com/can1357/oh-my-pi/blob/3a2758b68f7c8e6bdf22c3a76b86c8675e5e0c9e/packages/coding-agent/src/session/yield-queue.ts): retain results, combine them at a safe boundary, and filter consumed results before delivery. This package uses Pi's public extension API, not patched host code; a local idle retry covers busy operations that expose no final agent boundary.
+
 ## Install and update
 
 Requires Pi **1.3.0 or later**.
@@ -27,8 +29,22 @@ The complete `@maxiaochao/pi-toolkit` package **bundles and enables Background T
 
 ```text
 background_task({ action: "start", command: "sleep 10; printf 'checks complete\\n'", description: "Delayed check", timeout: 120 })
-background_task({ action: "list" })
+```
+
+Each accepted start includes this exact guidance in the tool's text and `structuredContent.guidance`. The tool description carries it too, including for Codemode discovery:
+
+> 完成会自动通知。现在不要查询等待；继续其他独立工作，没有其他工作就结束当前轮，收到通知后再取结果。
+
+After the completion notification, read the result:
+
+```text
 background_task({ action: "output", id: "<returned-task-id>" })
+```
+
+The tool also supports listing and cancellation:
+
+```text
+background_task({ action: "list" })
 background_task({ action: "cancel", id: "<returned-task-id>" })
 ```
 
@@ -57,7 +73,22 @@ The commands inspect the same jobs without asking a model to perform the operati
 
 A fixed widget **above the editor** shows each task's ID, status, elapsed time, runtime limit and description. It coexists with Scheduler, Todo, and Herdr widgets. Finished rows remain for five seconds; hiding a row does not delete its record. RPC gets a compact active count; non-interactive tools work without the widget.
 
-Completion, failure, cancellation, timeout and output-limit termination each send one `followUp` message to the main agent. It waits for the current turn, rather than interrupting it. Notifications contain metadata and a log path, **not the output body**. The agent can call output when it needs the details.
+Completion, failure, cancellation, timeout and output-limit termination update the widget immediately. The extension holds pending completion metadata until it can deliver it safely:
+
+- While the main agent is busy, completions are combined into one message after the current tool batch returns, before the next model request. This includes waiting for a synchronous Herdr subagent; it does not cancel or interrupt that subagent.
+- While idle, pending completions are combined on the next event-loop tick and wake the main agent once. Jobs that finish after that batch can produce another notification. Pi's global steering/follow-up queue settings are unchanged.
+- If another operation such as manual compaction keeps the session busy without an agent boundary, one local timer retries after 1, 2, 4, 8, 16, then 30 seconds, staying at 30 seconds thereafter. There is no retry-count limit or expiry that discards unread results. This does not call a model or poll shell output.
+- Normal tool/settlement boundaries still deliver immediately, without waiting for the retry timer. Without a boundary, an idle session can wait up to the current retry interval (at most 30 seconds, subject to native timer delays). Once a batch is delivered or fully consumed, the next batch starts with an immediate check and fresh backoff.
+- A successful tool `output` read of a finished task consumes its pending reminder, including failed tasks. This applies to direct and Codemode callers; a script that reads and filters a result has consumed it even if it does not print it. A running snapshot, `list`, a failed log read, or a user `/bg output` inspection does not consume the main agent's reminder. Consumption does not mean the task passed validation.
+- Aborted/error boundaries do not request continuation or replay a previously scheduled wake. An error does not suppress later completions.
+- A user interrupt keeps the agent stopped: accepted jobs still run, but even later completions cannot restart it. Unread results remain queryable and are handed to the next user-message run before its first model request. Another extension's custom wake does not release this interrupt state; a new user-message run or session replacement does. This adds no notification pause switch.
+- Cancelling manual compaction is separate from interrupting the agent. Pending completions still wake an otherwise-idle session after compaction succeeds, fails or is cancelled.
+
+Pi's public interrupted-run event does not include the abort reason. In particular, starting `/compact` during an active run first interrupts that run. This package preserves that interruption until the next user-message run; it does not infer that compaction grants permission to restart the agent. Compaction started while already idle does not create this interrupted-run state.
+
+Each message includes actual completion times, statuses and log paths, **not the output body**. The agent can call output when it needs details. Completions that arrive near final settlement are checked again before the run settles. No per-task `followUp` messages are left behind the main agent's final report.
+
+Pi reports asynchronous message/run-start failures through its extension error channel. This extension does not automatically replay a message after such a failure; task metadata and captured logs remain queryable for the lifetime of the session.
 
 ## Output and safety limits
 
@@ -85,21 +116,21 @@ const started = await tools.background_task({
   command: "sleep 10; printf 'done\\n'",
   timeout: 120,
 });
-text(started.task);
+text(started);
 ```
 
-Later scripts can list, read, or cancel the job. This does not hold a Codemode worker open. Merely starting an unawaited Bash call is different: Codemode cancels unfinished nested calls when its script ends.
+This prints the startup guidance as well as the task. Continue independent work or end the turn; do not keep a Codemode worker open to sleep or poll for completion. After notification, another script can read the result. Merely starting an unawaited Bash call is different: Codemode cancels unfinished nested calls when its script ends.
 
 The tool description is compact. This package adds no `promptGuidelines` or extra global system-prompt rules.
 
 ## Lifetime and scope
 
 - Exit, new/resumed/forked sessions and reload terminate active tasks, remove the widget and timers, and delete this package's captured logs. Commands' own files are left alone. History is not restored.
-- Aborting the main agent's current turn does not cancel an accepted job. Use cancel or `/bg cancel`.
+- Aborting the main agent's current turn does not cancel an accepted job, but its completion cannot automatically restart the interrupted agent. Use cancel or `/bg cancel` to stop the job itself.
 - Cancellation and runtime limits stop the native shell process group. Scripts must wait for their own work. Daemonized/detached commands (`nohup`, `setsid`, self-backgrounding processes), existing PID adoption, PTYs and interactive stdin are not supported.
 - This is a distinct **local execution** tool. A third-party sandbox or remote backend installed only for Bash does not automatically cover it. Enable it only where direct local shell execution is permitted.
 - It is not an OS sandbox: CPU/memory quotas, cleanup after SIGKILL/power loss, automatic retries, deadline renewal and persistence are out of scope. Native signal delivery and timers are best-effort.
-- A completion message already queued in Pi cannot be selectively withdrawn. Shutdown prevents new messages from old jobs; it cannot retract one already delivered to the host.
+- Pending reminders and notification timers are cleared on session shutdown. Once a completion is delivered into conversation history, reading output does not erase that history. Messages queued by an older installed version cannot be selectively withdrawn by this version.
 
 ## Remove
 

package/packages/background-tasks/TESTING.md

@@ -13,7 +13,14 @@ Tests use Node's built-in test runner. They resolve host peers from the installe
 - `tasks.mjs`: fake execution and clock at the task-manager interface; immediate return, two slots, validation, timeout/cancel races, final failure, disk budgets, write errors, bounded history and shutdown.
 - `output.mjs`: compares both output views with the real host Bash tool. Covers line/byte limits, long lines, empty output, missing final newline, UTF-8 split across chunks, invalid UTF-8 and logs larger than 1 MiB.
 - `processes.mjs`: the native backend, a multi-line Python log check, non-blocking concurrency, PID-observed process-tree cleanup, silent busy-loop timeout and the default 32 MiB disk limit.
-- `extension.mjs`: real extension registration with fake execution/clock; schema errors, command parity, parent-signal independence, followUp, no output in notifications, above-editor placement, five-second retention, narrow/CJK rendering, coexistence and non-TUI modes.
+- `extension.mjs`: real extension registration with fake execution/clock; schema errors, command parity, parent-signal independence, merged busy/idle notifications, terminal-output consumption and failed-read retention, abort/error boundaries, manual-compaction-style busy intervals without agent boundaries, other extensions' draft preservation, no output in notifications, above-editor placement, five-second retention, narrow/CJK rendering, coexistence and non-TUI modes. Checks the exact approved startup guidance in both return paths and the tool description; verifies 24-hour retention after an interrupt, output consumption while stopped, custom-wake isolation and restoration of automatic delivery by a new user-message run.
+- `notifications.mjs`: isolated real Pi with direct tool batches or its native Codemode tool, default one-at-a-time queues and an offline provider. Four actual failing shell jobs finish while a synchronous tool stands in for a subagent. The next model request gets one merged notification, excluding zero, one or four consumed terminal outputs; no extra requests follow the final report. Also verifies that native Codemode and the next model request receive the exact startup guidance. The blocking tool is a fixture, not a real Herdr child. `BG_TEST_EXTENSION=/absolute/path/to/background-tasks.ts` can run the queue regressions against an older implementation.
+- `compaction.mjs`: isolated native Pi SDK sessions call `session.compact()`, the same manual-compaction entry point used by `/compact` and RPC. Real shell jobs exit during a held offline summary request. Covers successful native compaction, a provider summary error and `abortCompaction()` cancellation; each must retain the pending completion while busy and automatically deliver it once afterward, without another user prompt. Checks actual compaction lifecycle/events, saved compaction entries, completion timestamps/logs and exactly one automatic conversation request. Uses real timers and native `isIdle`/`isCompacting`, not injected busy state or replacement compaction results; no paid model call or TUI keyboard invocation of `/compact`. `BG_TEST_EXTENSION` also supports a negative-control extension.
+- `interruptions.mjs`: isolated native Pi SDK sessions call the real `session.abort()` while a foreground tool is held. A real shell finishes before or after the interrupt; terminal timestamps verify the ordering. Native `agent_settled.aborted` must confirm the stop; no completion may start another model request. A new user prompt sees the retained completion in its first request, reads the real failed task's output, and finishes without duplicate delivery or extension errors. A third case starts actual manual compaction while the foreground tool is held: Pi itself interrupts the active agent, which must stay stopped even after compaction and background completion. The public abort event has no reason field, so the extension preserves this native interruption rather than guessing its source. `BG_TEST_EXTENSION` supports a negative control without interrupt suppression.
+
+Compaction cancellation assertions use native lifecycle `aborted` flags and the absence of a saved compaction entry, not version-dependent error strings. Agent interruption is a different state and is tested separately.
+
+Notification retry tests use the injected clock and session-idle interface. They check the 1/2/4/8/16/30-second delays, the repeated 30-second cap, retention across 24 hours of busy time, one timer shared by new completions, immediate boundary delivery, fresh-batch reset, and cleanup on terminal reads, abort/error boundaries and session replacement. No compression-event subscription or notification pause action is introduced. Offline fixtures prove guidance delivery, not that a live model always obeys it; no paid/live-model anti-polling evaluation is part of this suite.
 
 Load-test uses an isolated temporary agent directory, the production extension and an offline fixture provider. It does not access real provider credentials or alter the user's installed packages. From the workspace, `npm --prefix packages/background-tasks run load-test -- --toolkit` loads the complete toolkit directory through its manifest and verifies exactly one background-task tool; the root load-test runs this check too.
 
@@ -25,7 +32,7 @@ Requires Python 3 with the existing `pexpect` module; process fixtures use Bash,
 python3 packages/background-tasks/tests/tui-smoke.py .cache/verification/background-tui
 ```
 
-This starts a real Pi in a PTY with the production extension, Scheduler, the built-in Codemode tool and a deterministic fixture provider. It checks two jobs, rejection of a third, Codemode completion while jobs remain alive, explicit output, cancellation, automatic main-agent followUp, reload/new/quit cleanup and log removal. No network model calls occur. Mocked UI tests separately verify the exact five-second boundary.
+This starts a real Pi in a PTY with the production extension, Scheduler, the built-in Codemode tool and a deterministic fixture provider. It checks two jobs, rejection of a third, Codemode completion while jobs remain alive, explicit output, cancellation, automatic main-agent notification, reload/new/quit cleanup and log removal. It observes both persisted boundary entries and idle custom messages by unique session-entry ID, and rejects duplicate notifications. No network model calls occur. Mocked UI tests separately verify the exact five-second boundary.
 
 Results and the actual ANSI stream are stored under the chosen evidence directory. Real screenshots require an isolated X11 terminal window, `gnome-terminal.real`, `xwininfo` and ImageMagick `import`:
 

package/packages/background-tasks/extensions/background-tasks.ts

@@ -1,5 +1,5 @@
 import { StringEnum } from "@earendil-works/pi-ai";
-import { createLocalBashOperations, type BashOperations, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { createLocalBashOperations, type AgentBeforeSettleEvent, type BashOperations, type ExtensionAPI, type ExtensionContext, type TurnEndEvent } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { stripVTControlCharacters } from "node:util";
 import { Type } from "typebox";
@@ -7,6 +7,7 @@ import { BackgroundTasks, errorText, summary, systemClock, type Clock, type Task
 import { BackgroundWidget, FINISHED_VISIBLE_MS, WIDGET_KEY, duration, visibleTasks } from "../src/widget.ts";
 
 const actions = ["start", "list", "output", "cancel"] as const;
+const startGuidance = "完成会自动通知。现在不要查询等待；继续其他独立工作，没有其他工作就结束当前轮，收到通知后再取结果。";
 type Action = typeof actions[number];
 interface Params {
 	action: Action;
@@ -34,6 +35,7 @@ const OutputSchema = Type.Object({
 	action: Type.Optional(StringEnum(actions)), task: Type.Optional(TaskSchema), tasks: Type.Optional(Type.Array(TaskSchema)),
 	running: Type.Optional(Type.Number()), total: Type.Optional(Type.Number()), omitted: Type.Optional(Type.Number()),
 	output: Type.Optional(Type.String()), truncated: Type.Optional(Type.Boolean()), full_output_path: Type.Optional(Type.String()),
+	guidance: Type.Optional(Type.String()),
 	error: Type.Optional(Type.String()),
 });
 
@@ -62,8 +64,78 @@ export default function (pi: ExtensionAPI, dependencies: { operations?: BashOper
 	let context: ExtensionContext | undefined;
 	let generation = 0;
 	let timer: unknown;
+	let notificationTimer: unknown;
+	let completedNormally = true;
+	let interrupted = false;
+	const pending = new Map<string, TaskSnapshot>();
 	let mounted: { widget: BackgroundWidget; tui: { requestRender(): void } } | undefined;
 
+	const clearNotificationTimer = () => {
+		if (notificationTimer !== undefined) clock.clearTimeout(notificationTimer);
+		notificationTimer = undefined;
+	};
+	const takeNotification = () => {
+		clearNotificationTimer();
+		if (pending.size === 0) return;
+		const tasks = [...pending.values()].sort((a, b) => a.ended_at! - b.ended_at!);
+		pending.clear();
+		return {
+			customType: "background-task-finished", display: true,
+			details: { tasks, ...(tasks.length === 1 ? { task: tasks[0] } : {}) },
+			content: `[Background task finished]\n${tasks.map((task) =>
+				`${formatTask(task)}\nEnded at: ${new Date(task.ended_at!).toISOString()}${task.reason ? `\nReason: ${task.reason}` : ""}\nCaptured log: ${task.log_path}${task.capture_complete ? "" : "\nOutput capture is incomplete."}`
+			).join("\n\n")}`,
+		};
+	};
+	const scheduleNotification = (delay = 0) => {
+		if (interrupted || notificationTimer !== undefined || pending.size === 0) return;
+		const epoch = generation;
+		notificationTimer = clock.setTimeout(() => {
+			notificationTimer = undefined;
+			if (generation !== epoch || !context) return;
+			if (!context.isIdle()) {
+				// Manual compaction has no agent boundary when it finishes.
+				// Keep one wake pending, without expiring unread results or polling every second.
+				scheduleNotification(Math.min(delay === 0 ? 1000 : delay * 2, 30_000));
+				return;
+			}
+			const message = takeNotification();
+			if (!message) return;
+			try { pi.sendMessage(message, { triggerTurn: true, deliverAs: "steer" }); }
+			catch (error) {
+				// Native Pi reports async send/run failures itself; this covers synchronous adapters.
+				for (const task of message.details.tasks) pending.set(task.id, task);
+				console.error(`Background completion notification failed: ${errorText(error)}`);
+			}
+		}, delay);
+	};
+	const deliverAtBoundary = (event: TurnEndEvent | AgentBeforeSettleEvent) => {
+		completedNormally = event.outcome === "completed";
+		if (event.outcome === "aborted") interrupted = true;
+		if (!completedNormally || interrupted) {
+			clearNotificationTimer();
+			return;
+		}
+		const message = takeNotification();
+		if (message) return { entries: [...event.entries, { type: "custom_message" as const, ...message }], continue: true };
+	};
+	pi.on("turn_end", deliverAtBoundary);
+	pi.on("agent_before_settle", deliverAtBoundary);
+	pi.on("before_agent_start", (event) => {
+		if (event.messageType !== "user" || !interrupted) return;
+		// Only a new user prompt releases an interrupt, not another extension's custom wake.
+		interrupted = false;
+		const message = takeNotification();
+		if (message) return { message };
+	});
+	pi.on("agent_settled", (event) => {
+		if (event.aborted) {
+			interrupted = true;
+			clearNotificationTimer();
+		}
+		if (!event.aborted && completedNormally) scheduleNotification();
+	});
+
 	const clearTimer = () => {
 		if (timer !== undefined) clock.clearTimeout(timer);
 		timer = undefined;
@@ -107,6 +179,10 @@ export default function (pi: ExtensionAPI, dependencies: { operations?: BashOper
 		manager = undefined;
 		context = undefined;
 		clearTimer();
+		clearNotificationTimer();
+		pending.clear();
+		completedNormally = true;
+		interrupted = false;
 		try {
 			if (previousContext?.hasUI) {
 				previousContext.ui.setStatus(WIDGET_KEY, undefined);
@@ -124,10 +200,8 @@ export default function (pi: ExtensionAPI, dependencies: { operations?: BashOper
 			onChange() { if (generation === epoch) refresh(); },
 			onComplete(task) {
 				if (generation !== epoch || !context) return;
-				pi.sendMessage({
-					customType: "background-task-finished", display: true, details: { task },
-					content: `[Background task finished]\n${formatTask(task)}${task.reason ? `\nReason: ${task.reason}` : ""}\nCaptured log: ${task.log_path}${task.capture_complete ? "" : "\nOutput capture is incomplete."}`,
-				}, { triggerTurn: true, deliverAs: "followUp" });
+				pending.set(task.id, task);
+				scheduleNotification();
 			},
 		});
 	});
@@ -139,8 +213,8 @@ export default function (pi: ExtensionAPI, dependencies: { operations?: BashOper
 		if (params.action === "start") {
 			const task = manager.start({ command: params.command!, description: params.description, cwd: params.cwd, timeout: params.timeout }, cwd);
 			return {
-				text: `Started ${formatTask(task)}\nLog: ${task.log_path}\nAt most 2 tasks run at once. Tasks stop on session changes, reload, or exit; captured logs are then removed.`,
-				data: { action: params.action, task }, details: { action: params.action, task }, isError: false,
+				text: `Started ${formatTask(task)}\n${startGuidance}\nLog: ${task.log_path}\nAt most 2 tasks run at once. Tasks stop on session changes, reload, or exit; captured logs are then removed.`,
+				data: { action: params.action, task, guidance: startGuidance }, details: { action: params.action, task }, isError: false,
 			};
 		}
 		if (params.action === "list") {
@@ -166,13 +240,19 @@ export default function (pi: ExtensionAPI, dependencies: { operations?: BashOper
 
 	pi.registerTool({
 		name: "background_task", label: "Background task",
-		description: "Start shell commands as background tasks and return task IDs immediately. Supports status, output, and cancellation; notifies the main agent on completion.",
+		description: `Start shell commands as background tasks and return task IDs immediately. Supports status, output, and cancellation. After start: ${startGuidance}`,
 		parameters: Parameters, outputSchema: OutputSchema,
 		annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
 		async execute(_id, params, signal, _onUpdate, ctx) {
 			try {
 				if (signal?.aborted) throw new Error("Tool call aborted before task acceptance");
 				const result = await perform(params, ctx?.cwd ?? context?.cwd ?? process.cwd());
+				// A terminal result was consumed by this tool's caller (including Codemode).
+				// User /bg inspections and running snapshots do not acknowledge completion.
+				if (params.action === "output" && "task" in result.data && result.data.task.status !== "running") {
+					pending.delete(result.data.task.id);
+					if (pending.size === 0) clearNotificationTimer();
+				}
 				return { content: [{ type: "text" as const, text: result.text }], structuredContent: result.data, details: result.details, isError: result.isError };
 			} catch (error) {
 				const message = errorText(error);

package/packages/background-tasks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-background-tasks",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Session-scoped background shell tasks with completion notifications for Pi.",
   "type": "module",
   "keywords": [
@@ -34,7 +34,7 @@
     "typebox": "*"
   },
   "scripts": {
-    "test": "node --experimental-strip-types --import ./tests/runtime.mjs --test tests/tasks.mjs tests/output.mjs tests/processes.mjs tests/extension.mjs",
+    "test": "node --experimental-strip-types --import ./tests/runtime.mjs --test tests/tasks.mjs tests/output.mjs tests/processes.mjs tests/extension.mjs tests/notifications.mjs tests/compaction.mjs tests/interruptions.mjs",
     "load-test": "node --experimental-strip-types tests/load.mjs"
   },
   "publishConfig": {

package/packages/background-tasks/tests/compaction.mjs

@@ -0,0 +1,167 @@
+import assert from "node:assert/strict";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { test } from "node:test";
+import { pathToFileURL } from "node:url";
+import "./runtime.mjs";
+
+const { createAgentSession, DefaultResourceLoader, ModelRuntime, SessionManager, SettingsManager } = await import("@earendil-works/pi-coding-agent");
+const { createAssistantMessageEventStream } = await import("@earendil-works/pi-ai");
+const { default: register } = await import(process.env.BG_TEST_EXTENSION
+	? pathToFileURL(process.env.BG_TEST_EXTENSION).href : new URL("../extensions/background-tasks.ts", import.meta.url).href);
+
+async function waitFor(check, label) {
+	for (let i = 0; i < 1000; i++) {
+		if (check()) return;
+		await delay(10);
+	}
+	throw new Error(`Timed out waiting for ${label}`);
+}
+
+for (const outcome of ["success", "failure", "cancel"]) {
+	test(`real Pi manual compaction ${outcome} delivers a job completed during summarization once, without another user prompt`, { timeout: 20000 }, async (t) => {
+		const directory = mkdtempSync(join(tmpdir(), "pi-bg-compact-"));
+		const release = join(directory, "release");
+		const exited = join(directory, "exited");
+		const finishSummary = Promise.withResolvers();
+		const requests = [], lifecycle = [], events = [], errors = [];
+		let session, startedTask;
+		try {
+			const modelRuntime = await ModelRuntime.create({ authPath: join(directory, "auth.json"), modelsPath: join(directory, "models.json"), refreshOnCreate: false });
+			modelRuntime.registerProvider("bg-compaction", {
+				name: "Offline real-compaction fixture", baseUrl: "http://127.0.0.1:1", api: "bg-compaction", apiKey: "fixture-not-a-secret",
+				models: [{ id: "deterministic", name: "Offline fixture", reasoning: false, input: ["text"], contextWindow: 128000, maxTokens: 4096, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 } }],
+				streamSimple(model, context, options) {
+					const stream = createAssistantMessageEventStream();
+					const compacting = session.isCompacting;
+					requests.push({ compacting, messages: context.messages });
+					void (async () => {
+						const message = { role: "assistant", api: model.api, provider: model.provider, model: model.id, timestamp: Date.now(), content: [], stopReason: "stop",
+							usage: { input: 1, output: 1, cacheRead: 0, cacheWrite: 0, totalTokens: 2, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } } };
+						try {
+							if (compacting) {
+								assert.ok(options.signal, "native summarization supplies its cancellation signal");
+								writeFileSync(release, "release background shell\n");
+								const aborted = () => finishSummary.resolve();
+								options.signal.addEventListener("abort", aborted, { once: true });
+								try { await finishSummary.promise; }
+								finally { options.signal.removeEventListener("abort", aborted); }
+								if (options.signal.aborted) {
+									message.stopReason = "aborted";
+									message.errorMessage = "Fixture summary aborted";
+								} else if (outcome === "failure") {
+									message.stopReason = "error";
+									message.errorMessage = "Fixture summary failure";
+								} else message.content.push({ type: "text", text: "## Goal\nVerify compaction delivery.\n## Progress\nA background shell remains owned by this session." });
+							} else {
+								const last = context.messages.at(-1);
+								const text = typeof last.content === "string" ? last.content : last.content.filter((block) => block.type === "text").map((block) => block.text).join("\n");
+								if (last.role === "user" && text.includes("START_COMPACTION_JOB")) {
+									message.stopReason = "toolUse";
+									message.content.push({ type: "toolCall", id: "compaction-start", name: "background_task", arguments: {
+										action: "start", command: "while [ ! -f release ]; do sleep 0.01; done; printf 'finished during compaction\\n'; printf done > exited; exit 7", description: "Finishes during native compaction", timeout: 10,
+									} });
+								} else message.content.push({ type: "text", text: text.includes("[Background task finished]") ? "COMPLETION_ACK" : "JOB_ACCEPTED" });
+							}
+						} catch (error) {
+							message.stopReason = "error";
+							message.errorMessage = String(error);
+						}
+						stream.push({ type: "start", partial: message });
+						if (["error", "aborted"].includes(message.stopReason)) stream.push({ type: "error", reason: message.stopReason, error: message });
+						else stream.push({ type: "done", reason: message.stopReason, message });
+					})();
+					return stream;
+				},
+			});
+			const settingsManager = SettingsManager.inMemory({ compaction: { enabled: false, keepRecentTokens: 128 }, retry: { enabled: false }, cacheWarming: "off" });
+			const resourceLoader = new DefaultResourceLoader({
+				cwd: directory, agentDir: directory, settingsManager,
+				noExtensions: true, noSkills: true, noPromptTemplates: true, noThemes: true, noContextFiles: true,
+				extensionFactories: [register, (pi) => {
+					for (const type of ["session_before_compact", "session_compact", "session_compact_failed"]) pi.on(type, (event, ctx) => {
+						lifecycle.push({ type, reason: event.reason, aborted: event.aborted, fromExtension: event.fromExtension, idle: ctx.isIdle() });
+					});
+				}],
+			});
+			await resourceLoader.reload();
+			const created = await createAgentSession({ cwd: directory, agentDir: directory, modelRuntime, model: modelRuntime.getModel("bg-compaction", "deterministic"), thinkingLevel: "off", resourceLoader, settingsManager, sessionManager: SessionManager.inMemory(directory), tools: ["background_task"] });
+			session = created.session;
+			assert.deepEqual(created.extensionsResult.errors, []);
+			session.extensionRunner.onError((error) => errors.push(error));
+			session.subscribe((event) => {
+				events.push({ ...event, observedAt: Date.now() });
+				if (event.type === "tool_execution_end" && event.toolName === "background_task") startedTask = event.result.structuredContent.task;
+			});
+			await session.bindExtensions({});
+			await session.prompt("Earlier context to summarize: " + "background verification history ".repeat(200));
+			await session.prompt("START_COMPACTION_JOB");
+			assert.equal(startedTask?.status, "running");
+			assert.equal(session.isIdle, true);
+			const notifications = () => session.sessionManager.getBranch().filter((entry) => entry.type === "custom_message" && entry.customType === "background-task-finished");
+			const conversationRequests = () => requests.filter((request) => !request.compacting);
+			const before = conversationRequests().length;
+			// This is the same public manual-compaction entry point used by /compact and RPC.
+			const compacting = session.compact("COMPACTION_DELIVERY_FIXTURE").then((value) => ({ value }), (error) => ({ error }));
+			await waitFor(() => lifecycle.some((event) => event.type === "session_before_compact"), "native compaction start");
+			await waitFor(() => requests.some((request) => request.compacting), "native summarizer request");
+			await waitFor(() => existsSync(exited), "real background shell exit marker");
+			await delay(1250); // Let the real first retry run while native compaction is still busy.
+			assert.equal(session.isCompacting, true);
+			assert.equal(session.isIdle, false);
+			assert.equal(notifications().length, 0, "completion cannot interrupt native compaction");
+			assert.equal(conversationRequests().length, before, "busy retries must not start another conversation request");
+			if (outcome === "cancel") session.abortCompaction();
+			else finishSummary.resolve();
+			const result = await compacting;
+			if (outcome === "success") {
+				assert.equal(result.error, undefined);
+				assert.match(result.value.summary, /Verify compaction delivery/);
+			} else {
+				assert.ok(result.error, "native compaction must reject on failure or cancellation");
+				if (outcome === "failure") assert.match(result.error.message, /Fixture summary failure/);
+			}
+			assert.equal(session.isCompacting, false);
+			assert.deepEqual(lifecycle.map((event) => event.type), ["session_before_compact", outcome === "success" ? "session_compact" : "session_compact_failed"]);
+			assert.ok(lifecycle.every((event) => event.reason === "manual"));
+			assert.equal(lifecycle[1].fromExtension, false, "the fixture must not supply a replacement compaction result");
+			if (outcome !== "success") assert.equal(lifecycle[1].aborted, outcome === "cancel");
+			await waitFor(() => notifications().length > 0, "automatic completion delivery after compaction");
+			await session.waitForIdle();
+			await delay(50);
+			assert.equal(notifications().length, 1);
+			assert.equal(conversationRequests().length, before + 1, "no user prompt is submitted after compact()");
+			const notification = notifications()[0];
+			const task = notification.details.tasks[0];
+			assert.equal(task.id, startedTask.id);
+			assert.equal(task.status, "failed");
+			assert.equal(task.exit_code, 7);
+			assert.match(readFileSync(task.log_path, "utf8"), /finished during compaction/);
+			const start = events.find((event) => event.type === "compaction_start");
+			const end = events.find((event) => event.type === "compaction_end");
+			assert.ok(start && end, "native compaction lifecycle must actually run");
+			assert.ok(task.ended_at >= start.observedAt && task.ended_at <= end.observedAt, "the actual task completed during compaction, not beforehand");
+			assert.equal(end.aborted, outcome === "cancel");
+			assert.equal(session.sessionManager.getBranch().filter((entry) => entry.type === "compaction").length, outcome === "success" ? 1 : 0);
+			assert.equal(session.getLastAssistantText(), "COMPLETION_ACK");
+			assert.deepEqual(errors, []);
+			t.diagnostic(JSON.stringify({
+				outcome, lifecycle, taskCompletedDuringCompaction: true,
+				summaryRequests: requests.filter((request) => request.compacting).length,
+				automaticConversationRequests: conversationRequests().length - before,
+				completionEntries: notifications().length,
+			}));
+		} finally {
+			finishSummary.resolve();
+			if (session) {
+				session.abortCompaction();
+				await session.abort();
+				await session.extensionRunner.emit({ type: "session_shutdown", reason: "quit" });
+				session.dispose();
+			}
+			rmSync(directory, { recursive: true, force: true });
+		}
+	});
+}