Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

fix: report a stopped background command as stopped, not as a failure (#457)

Yaowei Zheng725a48613397
diff --git a/changelog/unreleased/2026-08-24-background-stop-status.md b/changelog/unreleased/2026-08-24-background-stop-status.md
new file mode 100644
index 00000000..60fe9bce
--- /dev/null
+++ b/changelog/unreleased/2026-08-24-background-stop-status.md
@@ -0,0 +1,31 @@
+# A stopped background command is reported as stopped, not as a failure
+
+- **Date:** 2026-08-24
+- **Type:** fix
+- **Scope:** `core`, `web`, `docs`
+- **PR:** [#457](https://github.com/Prism-Shadow/penguin-harness/pull/457)
+
+[中文版](2026-08-24-background-stop-status.zh.md)
+
+A `run_in_background` command that ended on a SIGTERM reached the conversation as
+`Background command failed: … — terminated by signal SIGTERM`. A SIGTERM is almost always
+somebody stopping the process on purpose, and the model's reasonable response to a failed
+dev server is to start it again — undoing the stop that was just asked for. The report is
+still sent, with the wording it should have had.
+
+## Details
+
+- A command ended on purpose now reports the new `status: stopped`: the user's **Stop**
+ button in the Web App's process list, a stop signal that arrived from outside
+ (`SIGTERM`/`SIGINT`/`SIGHUP` — a Ctrl-C from a terminal sharing the process group, a
+ `pkill`, a supervisor shutting a dev server down), and a stop the harness forced (a
+ capacity eviction, an idle reap).
+- The notice reads `Background command stopped: … — stopped by SIGTERM`, and its
+ `[background_task_done]` block states in as many words that the process was ended on
+ purpose and must not be restarted unasked.
+- `failed` keeps the outcomes nobody asked for — a spawn error, a non-zero exit, a hard kill
+ or a fault signal — so an OOM kill still reads as the failure it is.
+- `input_command`'s `kill` on an already-exited process describes a stop signal the same way
+ ("stopped by SIGTERM" rather than "terminated by signal SIGTERM").
+- The Web App's notice card carries the third outcome: "Background command stopped", with a
+ muted square glyph instead of the red failure X.
diff --git a/changelog/unreleased/2026-08-24-background-stop-status.zh.md b/changelog/unreleased/2026-08-24-background-stop-status.zh.md
new file mode 100644
index 00000000..e505e4ef
--- /dev/null
+++ b/changelog/unreleased/2026-08-24-background-stop-status.zh.md
@@ -0,0 +1,26 @@
+# 被停止的后台命令回报为「已停止」而非「失败」
+
+- **Date:** 2026-08-24
+- **Type:** fix
+- **Scope:** `core`, `web`, `docs`
+- **PR:** [#457](https://github.com/Prism-Shadow/penguin-harness/pull/457)
+
+[English](2026-08-24-background-stop-status.md)
+
+以 `run_in_background` 启动、最终死于 SIGTERM 的命令,此前以
+`Background command failed: … — terminated by signal SIGTERM` 送达对话。SIGTERM 几乎总是有人
+主动把进程停掉,而面对「失败」的 dev server,模型合理的反应正是把它重新拉起来,把刚做的停止
+撤销。回报照发,只是换成它本该有的措辞。
+
+## 详情
+
+- 被人主动结束的命令改以新的 `status: stopped` 回报:用户在 Web App 进程列表按下的「停止」、
+ 从外部递来的停止信号(`SIGTERM`/`SIGINT`/`SIGHUP`——同进程组终端里的 Ctrl-C、`pkill`、停掉
+ dev server 的管理进程),以及 Harness 强制的停止(容量淘汰、空闲回收)。
+- 提示正文变为 `Background command stopped: … — stopped by SIGTERM`,其
+ `[background_task_done]` 块直白写明:该进程是被人主动结束的,无人要求就不要重启。
+- `failed` 留给无人要求的结局——spawn 错误、非零退出、硬杀与故障信号,OOM 杀进程依旧如实读作
+ 失败。
+- `input_command` 的 `kill` 作用于已退出的进程时,对停止信号采用同一套措辞(「stopped by
+ SIGTERM」而非「terminated by signal SIGTERM」)。
+- Web App 的提示卡片增加第三种结局:「后台命令已停止」,用中性的方块图标,而不是红色失败叉。
diff --git a/packages/core/src/environment/tools/command/index.ts b/packages/core/src/environment/tools/command/index.ts
index c7db5fe9..62c3e464 100644
--- a/packages/core/src/environment/tools/command/index.ts
+++ b/packages/core/src/environment/tools/command/index.ts
@@ -2,7 +2,7 @@
* Barrel for the long-running command session module.
*/
export { CommandSessionManager } from "./session-manager.js";
-export { ManagedSession, resultForExit } from "./session.js";
+export { ManagedSession, isStopSignal, resultForExit } from "./session.js";
export type { ProcessExit, SpawnOptions } from "./session.js";
export { resolveShell, sessionShell } from "./shell.js";
export type { ShellInvocation, ResolveShellOptions } from "./shell.js";
diff --git a/packages/core/src/environment/tools/command/session.ts b/packages/core/src/environment/tools/command/session.ts
index bc3e4d85..aaf9ee5a 100644
--- a/packages/core/src/environment/tools/command/session.ts
+++ b/packages/core/src/environment/tools/command/session.ts
@@ -262,6 +262,14 @@ export class ManagedSession {
get running(): boolean {
return !this.exited;
}
+ /**
+ * Whether a stop was asked of this session (`kill`/`killHard`) — the host's stop button, a
+ * capacity eviction, an idle reap. The exit that follows is a deliberate stop, never a
+ * crash, and the background completion report says so instead of calling it a failure.
+ */
+ get stopRequested(): boolean {
+ return this.killed;
+ }
/** OS pid of the shell leading the process group; null when the spawn itself failed. */
get pid(): number | null {
return typeof this.child.pid === "number" ? this.child.pid : null;
@@ -359,6 +367,19 @@ export class ManagedSession {
}
}
+/**
+ * Signals that mean "stop", as opposed to "something broke": the harness's own SIGTERM, a
+ * Ctrl-C from a terminal sharing the process group, a `pkill`, a supervisor shutting a dev
+ * server down. Dying from one of these is somebody's decision, not a fault — SIGKILL and the
+ * fault signals stay failures, so an OOM kill or a segfault still reads as one.
+ */
+const STOP_SIGNALS: ReadonlySet<string> = new Set(["SIGTERM", "SIGINT", "SIGHUP"]);
+
+/** Whether an exit signal means the process was deliberately stopped (see STOP_SIGNALS). */
+export function isStopSignal(signal: NodeJS.Signals | null | undefined): boolean {
+ return signal != null && STOP_SIGNALS.has(signal);
+}
+
/** Converts exit info into a tool result (the terminal marker is appended via `note`, outside the truncation, so it isn't lost with long output). */
export function resultForExit(exit: ProcessExit | null): ToolResult {
if (!exit) return { stopReason: "completed" };
diff --git a/packages/core/src/environment/tools/exec-command.ts b/packages/core/src/environment/tools/exec-command.ts
index 0a4a44d3..af729daa 100644
--- a/packages/core/src/environment/tools/exec-command.ts
+++ b/packages/core/src/environment/tools/exec-command.ts
@@ -23,7 +23,7 @@ import { partialToolCallOutput } from "../../omnimessage/index.js";
import type { OmniMessage } from "../../omnimessage/index.js";
import type { EnvironmentServices, ToolDefinitionConfig } from "../../interfaces.js";
import type { BuiltinTool, ToolExecutionContext, ToolResult } from "./types.js";
-import { DEFAULT_EXEC_YIELD_MS, resultForExit } from "./command/index.js";
+import { DEFAULT_EXEC_YIELD_MS, isStopSignal, resultForExit } from "./command/index.js";
import type { ManagedSession } from "./command/index.js";
import { clampYield, reportLabel, tailForReport } from "./background/index.js";
@@ -145,6 +145,15 @@ export function createExecCommandTool(
* goes to `services.backgroundDone` — the Session turns it into a harness user message.
* input_command's kill disarms it first (a deliberate kill reports its outcome synchronously), and a
* disposed Environment drops the event (see Environment.emitBackgroundDone).
+ *
+ * A stop still reports — the conversation has to learn the dev server it started is down —
+ * but as `stopped`, not `failed`: the user's stop button, a stop signal from outside (a
+ * Ctrl-C in the terminal sharing the process group, a `pkill`, a supervisor), the harness's
+ * own forced stops (a capacity eviction, an idle reap). Worded "failed — terminated by signal
+ * SIGTERM" they read like a crash, and the model's reasonable response to a crashed dev
+ * server is to start it again, undoing the stop somebody just asked for. Outcomes nobody
+ * asked for stay `failed`: a spawn error, a non-zero exit, a hard kill or a fault signal (an
+ * OOM kill, a segfault).
*/
export function armCommandDoneReport(
session: ManagedSession,
@@ -155,18 +164,20 @@ export function armCommandDoneReport(
if (!notify) return;
session.onceExited(() => {
const exit = session.exit;
+ const stopped = session.error === null && (session.stopRequested || isStopSignal(exit?.signal));
const failed =
- session.error !== null || exit?.signal != null || (exit !== null && exit.code !== 0);
+ !stopped &&
+ (session.error !== null || exit?.signal != null || (exit !== null && exit.code !== 0));
const detail = session.error
? `spawn error: ${session.error.message}`
: exit?.signal != null
- ? `terminated by signal ${exit.signal}`
+ ? `${stopped ? "stopped by" : "terminated by signal"} ${exit.signal}`
: `exit code ${exit?.code ?? "unknown"}`;
notify({
kind: "command",
id: processId,
label: reportLabel(session.cmd),
- status: failed ? "failed" : "completed",
+ status: stopped ? "stopped" : failed ? "failed" : "completed",
detail,
output: tailForReport(session.drainPending()),
});
diff --git a/packages/core/src/environment/tools/input-command.ts b/packages/core/src/environment/tools/input-command.ts
index 1467c5da..6d74d333 100644
--- a/packages/core/src/environment/tools/input-command.ts
+++ b/packages/core/src/environment/tools/input-command.ts
@@ -28,6 +28,7 @@ import type { BuiltinTool, ToolExecutionContext, ToolResult } from "./types.js";
import {
DEFAULT_EMPTY_POLL_YIELD_MS,
DEFAULT_WRITE_YIELD_MS,
+ isStopSignal,
resultForExit,
} from "./command/index.js";
import { clampYield } from "./background/index.js";
@@ -86,10 +87,12 @@ export function createInputCommandTool(
note: `[process ${processId} killed (SIGTERM to the process group, SIGKILL after a grace period)]`,
};
}
+ // Same vocabulary the completion report uses: a stop signal ended it on purpose,
+ // anything else broke it.
const status = session.error
? `spawn error: ${session.error.message}`
: exit?.signal != null
- ? `terminated by signal ${exit.signal}`
+ ? `${isStopSignal(exit.signal) ? "stopped by" : "terminated by signal"} ${exit.signal}`
: `exit code ${exit?.code ?? "unknown"}`;
return {
stopReason: "completed",
diff --git a/packages/core/src/interfaces.ts b/packages/core/src/interfaces.ts
index 3ba510c3..d808e5be 100644
--- a/packages/core/src/interfaces.ts
+++ b/packages/core/src/interfaces.ts
@@ -425,8 +425,13 @@ export interface BackgroundTaskDoneEvent {
id: string;
/** What was launched: the command string, or the subagent prompt's first line (display only, truncated by the producer). */
label: string;
- /** Terminal status of the run. */
- status: "completed" | "failed";
+ /**
+ * Terminal status of the run. `stopped` is a command somebody ended on purpose (a stop
+ * signal from outside, a capacity eviction) — settled, but not a failure to react to;
+ * `failed` stays for outcomes nobody asked for (a spawn error, a non-zero exit, a fault
+ * signal).
+ */
+ status: "completed" | "failed" | "stopped";
/** One-line terminal detail (exit code / signal / subagent note); empty when there is none. */
detail: string;
/** Tail of the yet-undelivered output at settle time (capped by the producer); empty when nothing was pending. */
diff --git a/packages/core/src/omnimessage/markers/origin-blocks.ts b/packages/core/src/omnimessage/markers/origin-blocks.ts
index 4545ac3f..6a4649a7 100644
--- a/packages/core/src/omnimessage/markers/origin-blocks.ts
+++ b/packages/core/src/omnimessage/markers/origin-blocks.ts
@@ -292,8 +292,12 @@ export interface BackgroundTaskDone {
kind: "command" | "subagent";
/** The registry handle the model already holds: `process_id` or `subagent_id`. */
id: string;
- /** Terminal status of the run. */
- status: "completed" | "failed";
+ /**
+ * Terminal status of the run. `stopped` is a command somebody ended on purpose (a stop
+ * signal from outside, a capacity eviction): settled, but nothing to react to — see the
+ * block's leading sentence, which tells the model so in as many words.
+ */
+ status: "completed" | "failed" | "stopped";
/** One-line terminal detail (exit code / signal / subagent note); empty when there is none. */
detail: string;
/**
@@ -320,7 +324,9 @@ export function buildBackgroundTaskDoneMessage(done: BackgroundTaskDone, body: s
const block = markerBlock(
MARKER_TAGS.backgroundTaskDone,
[
- "Automatic notification from the harness, not the user: a background task you started has finished.",
+ done.status === "stopped"
+ ? "Automatic notification from the harness, not the user: a background task you started was stopped on purpose — someone ended it, it did not crash. Do not restart it unless you are asked to."
+ : "Automatic notification from the harness, not the user: a background task you started has finished.",
`kind: ${done.kind}`,
`id: ${done.id}`,
`status: ${done.status}`,
@@ -350,7 +356,11 @@ export function parseBackgroundTaskDoneMessage(
for (const [key, value] of fieldLines(m[1]!, ["kind", "id", "status", "detail", "delivery"])) {
if (key === "kind" && (value === "command" || value === "subagent")) done.kind = value;
else if (key === "id") done.id = value;
- else if (key === "status" && (value === "completed" || value === "failed")) done.status = value;
+ else if (
+ key === "status" &&
+ (value === "completed" || value === "failed" || value === "stopped")
+ )
+ done.status = value;
else if (key === "detail") done.detail = value;
else if (key === "delivery" && value === "steering") done.delivery = value;
}
diff --git a/packages/core/src/session.ts b/packages/core/src/session.ts
index df1881e0..cc39e99d 100644
--- a/packages/core/src/session.ts
+++ b/packages/core/src/session.ts
@@ -194,7 +194,8 @@ const TITLE_ASSISTANT_MATERIAL_LIMIT = 1000;
function backgroundDoneNotice(event: BackgroundTaskDoneEvent, delivery?: "steering"): OmniMessage {
const what = event.kind === "command" ? "Background command" : "Background subagent";
const idField = event.kind === "command" ? "process_id" : "subagent_id";
- const verb = event.status === "completed" ? "finished" : "failed";
+ const verb =
+ event.status === "completed" ? "finished" : event.status === "stopped" ? "stopped" : "failed";
const detail = event.detail ? ` — ${event.detail}` : "";
const head = `${what} ${verb}: \`${event.label}\` (${idField} ${event.id})${detail}`;
const body = event.output.trim() ? `${head}\n\n${event.output}` : head;
diff --git a/packages/core/test/background-execution.test.ts b/packages/core/test/background-execution.test.ts
index 1da2bd79..c4238dcf 100644
--- a/packages/core/test/background-execution.test.ts
+++ b/packages/core/test/background-execution.test.ts
@@ -9,6 +9,8 @@ import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import path from "node:path";
import { Environment } from "../src/environment/index.js";
+import { armCommandDoneReport } from "../src/environment/tools/exec-command.js";
+import { ManagedSession } from "../src/environment/tools/command/index.js";
import { createSubagentTool } from "../src/environment/tools/run-subagent.js";
import { createInputSubagentTool } from "../src/environment/tools/input-subagent.js";
import { SubagentSessionManager } from "../src/environment/tools/subagent/index.js";
@@ -176,6 +178,26 @@ describe("[background_task_done] marker and the sender field", () => {
expect(stripLeadingMarkerBlocks(block)).toBe("body");
});
+ it("a stopped status reads as a deliberate stop, with the do-not-restart instruction", () => {
+ const stopped = buildBackgroundTaskDoneMessage(
+ { kind: "command", id: "proc-12ab34cd", status: "stopped", detail: "stopped by SIGTERM" },
+ "`pnpm dev` — stopped by SIGTERM",
+ );
+ expect(parseBackgroundTaskDoneMessage(stopped)!.done).toMatchObject({
+ status: "stopped",
+ detail: "stopped by SIGTERM",
+ });
+ expect(stopped).toContain("Do not restart it unless you are asked to.");
+ // Everything else keeps the plain "has finished" lead — a real failure still asks to be
+ // reacted to.
+ const failed = buildBackgroundTaskDoneMessage(
+ { kind: "command", id: "proc-12ab34cd", status: "failed", detail: "exit code 2" },
+ "",
+ );
+ expect(failed).toContain("has finished.");
+ expect(failed).not.toContain("Do not restart");
+ });
+
it("userText marks non-human senders and leaves human input unmarked", () => {
expect((userText("hi").payload as TextPayload).sender).toBeUndefined();
expect((userText("hi", "user").payload as TextPayload).sender).toBeUndefined();
@@ -271,6 +293,51 @@ describe("exec_command run_in_background", () => {
expect(legacy.output).toContain("Unknown tool: kill_command");
});
+ it.skipIf(process.platform === "win32")(
+ "a stop signal from outside reports stopped, not a signal failure",
+ async () => {
+ const { env } = await makeEnv();
+ const events: BackgroundTaskDoneEvent[] = [];
+ env.setBackgroundTaskListener((e) => events.push(e));
+ await runTool(env, "exec_command", { cmd: "sleep 30", run_in_background: true });
+ const pid = env.listBackgroundCommands()[0]!.pid!;
+ // Nobody told the harness: a Ctrl-C in a terminal sharing the group, a pkill, a
+ // supervisor stopping a dev server. Only the signal itself says it was deliberate —
+ // and read as a crash, the model's next move is to start the thing back up.
+ process.kill(pid, "SIGTERM");
+ await waitFor(() => events.length === 1);
+ expect(events[0]).toMatchObject({ status: "stopped", detail: "stopped by SIGTERM" });
+ },
+ );
+
+ it("the host's stop button still reports — as stopped, not as a signal failure", async () => {
+ const { env } = await makeEnv();
+ const events: BackgroundTaskDoneEvent[] = [];
+ env.setBackgroundTaskListener((e) => events.push(e));
+ const res = await runTool(env, "exec_command", { cmd: "sleep 30", run_in_background: true });
+ const id = extractProcessId(res.output);
+ // The user's stop from the Web App's process list: the conversation still hears about it
+ // — the dev server it started is down — it just must not hear "failed".
+ expect(env.killBackgroundCommand(id)).toBe(true);
+ await waitFor(() => events.length === 1);
+ expect(events[0]).toMatchObject({ id, status: "stopped" });
+ expect(env.killBackgroundCommand(id)).toBe(false);
+ });
+
+ it("a harness-forced stop (capacity eviction, idle reap) reports stopped", async () => {
+ // Those two paths kill through the registry rather than CommandSessionManager.kill, so
+ // their report stays armed — and must not blame the process for a stop the harness
+ // itself asked for, whatever the platform turns that kill into.
+ const { dir } = await makeEnv();
+ const events: BackgroundTaskDoneEvent[] = [];
+ const session = new ManagedSession({ cmd: "sleep 30", cwd: dir, env: process.env });
+ cleanups.push(() => session.killHard());
+ armCommandDoneReport(session, "proc-evicted", { backgroundDone: (e) => events.push(e) });
+ session.kill();
+ await waitFor(() => events.length === 1);
+ expect(events[0]).toMatchObject({ id: "proc-evicted", status: "stopped" });
+ });
+
it("dispose suppresses pending completion reports", async () => {
const dir = await mkdtemp(path.join(tmpdir(), "penguin-bg-"));
cleanups.push(() => rm(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 200 }));
@@ -707,6 +774,24 @@ describe("Session background notices", () => {
expect(session.hasPendingBackgroundNotices()).toBe(false);
});
+ it("a stopped command's notice says stopped, not failed", async () => {
+ const { environment, fire } = listenerEnvironment();
+ const session = new Session({
+ meta: META,
+ ...IMAGES,
+ bootstrap: async () => ({ tools: [], llm: new ReplyLLM(), mcp: [] }),
+ mcpServers: [],
+ environment,
+ });
+ fire({ ...DONE_EVENT, status: "stopped", detail: "stopped by SIGTERM" });
+ const text = (session.takeBackgroundNotices()[0]!.payload as TextPayload).text;
+ // The line the model reads first — "Background command failed … terminated by signal
+ // SIGTERM" was the whole problem.
+ expect(text).toContain("Background command stopped: `sleep 1` (process_id proc-11aa22bb)");
+ expect(text).toContain("stopped by SIGTERM");
+ expect(text).not.toContain("failed");
+ });
+
it("delivers a queued notice on the next run without a host signal for running tasks", async () => {
const { environment, fire } = listenerEnvironment();
const llm = new ReplyLLM();
diff --git a/packages/docs/content/tools.en.md b/packages/docs/content/tools.en.md
index a8b2ee1a..35602eb0 100644
--- a/packages/docs/content/tools.en.md
+++ b/packages/docs/content/tools.en.md
@@ -224,6 +224,8 @@ A task launched with `run_in_background: true` reports its completion as a **use
Delivery: while a Task is running, the report rides the next turn boundary — a final reply already streaming does not lose it, the Task simply continues for one more turn to react. While the Session is idle, the hosting server starts a new Task carrying the report (SDK embedders subscribe via `Session.onBackgroundNotice` / `takeBackgroundNotices`, or get it prepended to the next run). A command terminated through `input_command`'s `kill` sends no report — that call's own result already carries the outcome — and neither does a subagent round ended by an explicit `abort` (the aborter reads the outcome directly). Reports cover **model-initiated rounds only** — the `run_in_background` launch and `input_subagent` follow-ups; a round the user starts from the subagents panel is their own conversation with the child and sends no report (its answer text stays in the model-facing buffer for the next poll).
+A stop is reported, but not as a failure. A command ended on purpose reports `status: stopped` — the user's **Stop** button in the Web App's process list, a stop signal that arrived from outside (`SIGTERM`/`SIGINT`/`SIGHUP`: a Ctrl-C in a terminal sharing its process group, a `pkill`, a supervisor shutting a dev server down), or a stop the harness itself forced (a capacity eviction, an idle reap) — and its marker block says in as many words that nobody should restart it unasked. The conversation does need to hear that the dev server it started is down; worded `failed` it reads like a crash instead, and the reasonable response to a crashed dev server is to start it again, undoing the stop somebody just asked for. `failed` stays for outcomes nobody asked for: a spawn error, a non-zero exit, a hard kill or a fault signal (an OOM kill, a segfault).
+
A background subagent's lifecycle is decoupled from the call that launched it: its abort scope is its own (a per-run `abort` ends a round; the session itself leaves only with the parent Session, and even a capacity-released one can be revived), its messages stream to the frontend live through the launching Session (same origin-tagged channel a foreground window relays), and its tool approvals resolve through the launching call's own approval callback as a standing sink — so an `allow-all` launch runs unattended, and a failure still ends in a `status: failed` report rather than a child parked forever.
### Background session caps
diff --git a/packages/docs/content/tools.zh.md b/packages/docs/content/tools.zh.md
index cd56d98f..1d306286 100644
--- a/packages/docs/content/tools.zh.md
+++ b/packages/docs/content/tools.zh.md
@@ -222,6 +222,8 @@ Web App 的智能体面板用**与主对话相同的 composer**(子会话变
送达时机:Task 进行中时,回报搭乘下一个 turn 边界——即使最终回复已在流式输出,Task 也会为回应它再延续一个 turn。Session 空闲时,托管 Server 自动以该回报发起新 Task(SDK 嵌入方可订阅 `Session.onBackgroundNotice` / `takeBackgroundNotices`,否则回报并入下一次 run 的输入)。经 `input_command` 的 `kill` 终止的命令不发回报——该调用自身的结果已说明结局;被显式 `abort` 结束的子会话轮同样不发(打断者当场读到结局)。回报只覆盖**模型自己发起的轮**——`run_in_background` 的启动轮与 `input_subagent` 的续跑轮;用户从智能体面板发起的轮是用户与子会话自己的对话,不发回报(该轮答案文本留在模型面缓冲,下次轮询照常取得)。
+停止照样回报,只是不算失败。被人主动结束的命令回报 `status: stopped`——用户在 Web App 进程列表按下的「停止」、从外部递来的停止信号(`SIGTERM`/`SIGINT`/`SIGHUP`:同进程组终端里的 Ctrl-C、`pkill`、停掉 dev server 的管理进程),以及 Harness 自己强制的停止(容量淘汰、空闲回收)——其标记块直白地告知模型:无人要求就不要重启它。对话确实需要知道自己启动的 dev server 已经不在了;但若措辞为 `failed`,它读起来就像崩溃,而面对崩溃的 dev server,模型合理的反应正是把它重新拉起来,把别人刚做的停止撤销。`failed` 留给无人要求的结局:spawn 错误、非零退出、硬杀与故障信号(OOM 杀进程、段错误)。
+
后台 Subagent 的生命周期与发起它的调用解耦:中止范围只属于它自己(逐轮 `abort` 只结束一轮;会话只随父 Session 终结,容量释放的也可复活),其消息经发起 Session 实时流向前端(与前台窗口转发同一条 origin 通道),工具审批经发起调用自身的审批回调作为常驻 sink 解决——`allow-all` 下即发即忘可全程无人值守,失败也以 `status: failed` 的回报收尾,而不是子会话永久卡住。
### 后台会话上限
diff --git a/packages/docs/content/web-app.en.md b/packages/docs/content/web-app.en.md
index fdc8ad63..11ee8c6c 100644
--- a/packages/docs/content/web-app.en.md
+++ b/packages/docs/content/web-app.en.md
@@ -61,7 +61,7 @@ Pinning is offered only in the active list — the archived, subagent and schedu
The toolbar's right edge shows the Session's cumulative stats (tokens, cost, elapsed time); clicking them opens the details card — model, Session id (with a copy button beside it), Workspace, creation time and per-line statistics. Below those:
-- **Processes** — background processes the conversation started (`exec_command`s promoted past their yield window), one row each with the command, start time and pid — plus, on running rows, a link to the service the process serves when one was detected (the last local URL its output printed, else a listen-port probe of its process group). Running rows carry a **Stop** button (kills the whole process group and drops the row); exited rows keep their "exited" label and carry a **Remove** button that deletes the entry from the list. Removal is immediate and final: the entry leaves the runtime registry together with the output captured from that process, so afterwards the model can no longer be asked to read it — keep the row until you are done with its output.
+- **Processes** — background processes the conversation started (`exec_command`s promoted past their yield window), one row each with the command, start time and pid — plus, on running rows, a link to the service the process serves when one was detected (the last local URL its output printed, else a listen-port probe of its process group). Running rows carry a **Stop** button (kills the whole process group and drops the row) — the conversation is told the process is down, as **stopped** rather than failed, so the model knows the dev server is gone without reading it as a crash to restart; exited rows keep their "exited" label and carry a **Remove** button that deletes the entry from the list. Removal is immediate and final: the entry leaves the runtime registry together with the output captured from that process, so afterwards the model can no longer be asked to read it — keep the row until you are done with its output.
Copy buttons across the app confirm at the button itself: the copy icon flips to a check mark for a moment (no "Copied" text label).
diff --git a/packages/docs/content/web-app.zh.md b/packages/docs/content/web-app.zh.md
index e9a84442..baca1d99 100644
--- a/packages/docs/content/web-app.zh.md
+++ b/packages/docs/content/web-app.zh.md
@@ -61,7 +61,7 @@ penguin web
工具行最右侧显示会话累计统计(Token、费用、用时),点击即打开详情卡——模型、Session id(旁附复制按钮)、Workspace、创建时间与逐行统计。其下还有一节:
-- **会话进程**——对话启动的后台进程(超过 yield 窗口转入后台的 `exec_command`),逐行显示命令、启动时间与 pid;运行中的行在检测到进程所服务的地址时,还会附上可点击的服务链接(取其输出打印的最后一个本机 URL,否则对其进程组做监听端口探测)。运行中的行带「停止」按钮(杀停整个进程组并把该行从列表移除);已退出的行保留「已退出」标注,并带「移除」按钮,可把该条目从列表删除。移除立即生效且不可撤销:条目连同该进程已捕获的输出一起离开运行时注册表,之后无法再让模型读取那段输出——输出还有用时请先留着这一行。
+- **会话进程**——对话启动的后台进程(超过 yield 窗口转入后台的 `exec_command`),逐行显示命令、启动时间与 pid;运行中的行在检测到进程所服务的地址时,还会附上可点击的服务链接(取其输出打印的最后一个本机 URL,否则对其进程组做监听端口探测)。运行中的行带「停止」按钮(杀停整个进程组并把该行从列表移除)——对话会收到该进程已结束的回报,措辞是「已停止」而非失败,模型因此知道 dev server 没了,却不会把它读成需要重启的崩溃;已退出的行保留「已退出」标注,并带「移除」按钮,可把该条目从列表删除。移除立即生效且不可撤销:条目连同该进程已捕获的输出一起离开运行时注册表,之后无法再让模型读取那段输出——输出还有用时请先留着这一行。
全站的复制按钮在按钮自身给出反馈:复制成功后图标短暂切换为对勾(不再显示「已复制」文字)。
diff --git a/packages/web/src/components/ui/status-icon.tsx b/packages/web/src/components/ui/status-icon.tsx
index c0287f49..0ae02973 100644
--- a/packages/web/src/components/ui/status-icon.tsx
+++ b/packages/web/src/components/ui/status-icon.tsx
@@ -5,7 +5,7 @@
*/
import { toneInk } from "../../lib/tone";
-export type RunState = "running" | "waiting" | "done" | "failed";
+export type RunState = "running" | "waiting" | "done" | "failed" | "stopped";
const GLYPH: Record<Exclude<RunState, "running">, string> = {
// Hourglass (waiting for approval)
@@ -14,6 +14,8 @@ const GLYPH: Record<Exclude<RunState, "running">, string> = {
done: "M12 21a9 9 0 1 0 0-18 9 9 0 0 0 0 18zm-3.5-9.2 2.4 2.5 4.6-4.8",
// X (failed / interrupted)
failed: "M12 21a9 9 0 1 0 0-18 9 9 0 0 0 0 18zM9 9l6 6m0-6-6 6",
+ // Square (ended on purpose — neither a success to tick nor a fault to flag)
+ stopped: "M12 21a9 9 0 1 0 0-18 9 9 0 0 0 0 18zM8.5 8.5h7v7h-7z",
};
/** Shared status tones (lib/tone.ts): a settled row recedes, an unfinished one asks for a look. */
@@ -22,6 +24,8 @@ const TONE: Record<RunState, string> = {
waiting: toneInk.attention,
done: toneInk.muted,
failed: toneInk.danger,
+ // A stop is settled and expected: it recedes like "done" rather than flagging danger.
+ stopped: toneInk.muted,
};
export function StatusIcon({
diff --git a/packages/web/src/features/chat/background-done-banner.tsx b/packages/web/src/features/chat/background-done-banner.tsx
index 75df8a87..2f7750ca 100644
--- a/packages/web/src/features/chat/background-done-banner.tsx
+++ b/packages/web/src/features/chat/background-done-banner.tsx
@@ -17,14 +17,15 @@ import {
} from "./disclosure-row";
export function BackgroundDoneBanner({ done, body }: { done: BackgroundTaskDone; body: string }) {
- const ok = done.status === "completed";
+ const state =
+ done.status === "completed" ? "done" : done.status === "stopped" ? "stopped" : "failed";
return (
<div className={DISCLOSURE_CARD_CLASS}>
<DisclosureRow
variant="header"
sticky
- icon={<StatusIcon state={ok ? "done" : "failed"} label={done.status} />}
- label={S.chat.backgroundDone(done.kind, ok)}
+ icon={<StatusIcon state={state} label={done.status} />}
+ label={S.chat.backgroundDone(done.kind, done.status)}
>
<pre className={DISCLOSURE_OUTPUT_PRE_CLASS}>{body ? `${done.id}\n${body}` : done.id}</pre>
</DisclosureRow>
diff --git a/packages/web/src/lib/strings-en.ts b/packages/web/src/lib/strings-en.ts
index 6f78fcb5..50dd5e52 100644
--- a/packages/web/src/lib/strings-en.ts
+++ b/packages/web/src/lib/strings-en.ts
@@ -1585,14 +1585,11 @@ Scenarios:
modelLockedHint: "Type /model to switch models",
scheduledFrom: (name: string) => `Triggered by scheduled task "${name}"`,
/** One-line notice of a `[background_task_done]` harness message (run_in_background completion): the collapsed row's whole label. */
- backgroundDone: (kind: "command" | "subagent", ok: boolean) =>
- kind === "command"
- ? ok
- ? "Background command finished"
- : "Background command failed"
- : ok
- ? "Background task finished"
- : "Background task failed",
+ backgroundDone: (kind: "command" | "subagent", status: "completed" | "failed" | "stopped") => {
+ const what = kind === "command" ? "Background command" : "Background task";
+ if (status === "stopped") return `${what} stopped`;
+ return status === "completed" ? `${what} finished` : `${what} failed`;
+ },
emptyGreeting: "Start a new conversation",
/** Unified step-row titles (same header idiom as workRunning/workDone). */
mcpConnectTitle: "MCP connect",
diff --git a/packages/web/src/lib/strings.ts b/packages/web/src/lib/strings.ts
index 2619d94c..e15de1e3 100644
--- a/packages/web/src/lib/strings.ts
+++ b/packages/web/src/lib/strings.ts
@@ -1544,14 +1544,14 @@ Benchmark:
modelLockedHint: "输入 /model 切换模型",
scheduledFrom: (name: string) => `由定时任务「${name}」触发`,
/** One-line notice of a `[background_task_done]` harness message (run_in_background completion): the collapsed row's whole label. */
- backgroundDone: (kind: "command" | "subagent", ok: boolean): string =>
- kind === "command"
- ? ok
- ? "后台命令完成"
- : "后台命令失败"
- : ok
- ? "后台任务完成"
- : "后台任务失败",
+ backgroundDone: (
+ kind: "command" | "subagent",
+ status: "completed" | "failed" | "stopped",
+ ): string => {
+ const what = kind === "command" ? "后台命令" : "后台任务";
+ if (status === "stopped") return `${what}已停止`;
+ return status === "completed" ? `${what}完成` : `${what}失败`;
+ },
emptyGreeting: "开始一段新对话",
/** Unified step-row titles (same header idiom as workRunning/workDone). */
mcpConnectTitle: "MCP 连接",