From ccb5b3e100a2b996d4cc61f4261b59c1728f481d Mon Sep 17 00:00:00 2001
From: muyu <muyu@minimaxi.com>
Date: Wed, 23 Sep 2026 20:22:05 +0800
Subject: [PATCH 1/3] feat: improve local Bash execution contracts

---
 docs/tui-capabilities.md                      |  19 +
 .../agent-tools/src/desktop/builtin-defs.ts   |  35 +-
 packages/agent-tools/src/desktop/index.ts     |   5 +
 .../src/desktop/local-bash-contract.ts        |  83 ++
 .../src/desktop/local-bash-input.ts           |  14 +
 .../src/desktop/local-bash-result.ts          |  99 ++
 .../src/desktop/local-bash-timing.ts          |  62 ++
 .../agent-tools/src/desktop/local-pi-tools.ts | 235 +++--
 .../src/desktop/local-task-control.ts         |  52 +-
 .../agent-tools/src/desktop/output-limit.ts   |   4 +-
 packages/agent-tools/src/desktop/types.ts     |   3 +
 .../test/desktop/local-bash-output.test.ts    | 207 ++++
 .../test/desktop/local-bash-timeout.test.ts   | 506 +++++++++
 .../desktop/local-task-output-polling.test.ts | 445 ++++++++
 .../agents/_default/prompt-base-all.md.hbs    |   7 +-
 .../agents/_default/prompt-base-windows.md    |  47 +-
 .../_default/prompt-base-windows.md.hbs       |  47 +-
 .../service/background-bash/executor.test.ts  | 233 +++++
 .../src/service/background-bash/executor.ts   |  60 +-
 .../assembly/local-turn-tool-catalog.ts       |  23 +
 .../agent-host/execution/executor.test.ts     |  21 +-
 .../agent-host/execution/executor.ts          |   6 +-
 .../test/unit/agent/builtin/catalog.test.ts   |  24 +
 .../src/background-task/bash-output-writer.ts |  25 +-
 .../src/background-task/bash-runner.ts        | 184 ++--
 .../background-task/bash-task-settlement.ts   | 172 ++++
 .../src/background-task/service.ts            |  55 +-
 .../src/background-task/task-stop.ts          |  66 ++
 .../test/unit/child-bash-lifecycle.test.ts    |  32 +-
 ...background-bash-review-regressions.test.ts | 430 ++++++++
 .../unit/local-background-bash-runner.test.ts | 959 ++++++++++++++++++
 .../local-background-task-stop-races.test.ts  | 119 +++
 .../transcript/presentation/tool-summary.ts   |   1 +
 .../tui/src/tui/transcript/tool-evidence.ts   |   9 +-
 .../tui/test/unit/tui-tool-evidence.test.ts   | 264 +++++
 .../tui/test/unit/tui-tool-summary.test.ts    |  54 +
 release/public-source.json                    |  15 +
 test/vitest-suites.json                       |  11 +-
 third_party/pi-mono/MINIMAX_CHANGES.md        |   8 +
 .../coding-agent/src/core/tools/bash.ts       | 215 +++-
 .../coding-agent/src/core/tools/index.ts      |   2 +
 .../src/core/tools/output-accumulator.ts      |  48 +-
 .../packages/coding-agent/src/index.ts        |   2 +
 .../coding-agent/src/utils/child-process.ts   |  27 +-
 .../test/bash-process-observation.test.ts     |  61 +-
 .../packages/coding-agent/test/tools.test.ts  |  37 +
 46 files changed, 4605 insertions(+), 428 deletions(-)
 create mode 100644 packages/agent-tools/src/desktop/local-bash-contract.ts
 create mode 100644 packages/agent-tools/src/desktop/local-bash-input.ts
 create mode 100644 packages/agent-tools/src/desktop/local-bash-result.ts
 create mode 100644 packages/agent-tools/src/desktop/local-bash-timing.ts
 create mode 100644 packages/agent-tools/test/desktop/local-bash-output.test.ts
 create mode 100644 packages/agent-tools/test/desktop/local-bash-timeout.test.ts
 create mode 100644 packages/agent-tools/test/desktop/local-task-output-polling.test.ts
 create mode 100644 packages/local-runtime-v2/src/service/background-bash/executor.test.ts
 create mode 100644 packages/local-runtime/src/background-task/bash-task-settlement.ts
 create mode 100644 packages/local-runtime/src/background-task/task-stop.ts
 create mode 100644 packages/local-runtime/test/unit/local-background-bash-review-regressions.test.ts
 create mode 100644 packages/local-runtime/test/unit/local-background-bash-runner.test.ts
 create mode 100644 packages/local-runtime/test/unit/local-background-task-stop-races.test.ts
 create mode 100644 packages/tui/test/unit/tui-tool-evidence.test.ts
 create mode 100644 packages/tui/test/unit/tui-tool-summary.test.ts

diff --git a/docs/tui-capabilities.md b/docs/tui-capabilities.md
index 9ced4ea3..85e1b3aa 100644
--- a/docs/tui-capabilities.md
+++ b/docs/tui-capabilities.md
@@ -21,6 +21,25 @@ The evidence column summarizes the historical TUI 0.3.11 restoration record from
 | Files, shell, subagents, sessions, headless, ACP | Actual runtime retained | BYOK, file reads, session resume, ACP, sandbox, and status protocol tests |
 | Built-in skills, MCP, plugin tools | Original TUI assets and activation conditions retained | Asset build, plugin, and MCP tests; no claim that every skill has passed a real task |
 
+## Local Bash execution
+
+When the current turn includes native `task_output`, foreground Bash waits up to
+60 seconds before returning the same command's background task ID. Its total
+command timeout defaults to 600 seconds and is capped at 600 seconds; a shorter
+requested timeout applies. Backgrounding and output reads preserve the original
+deadline. Without native `task_output`, Bash stays in the foreground with a
+120-second default and a 300-second cap, and its schema omits `run_in_background`.
+Explicit background commands use the requested timeout; when omitted, the
+existing 30-minute runtime watchdog applies.
+
+Only exit code zero is success. Results retain available exit, signal, timeout,
+cancellation, and partial-output facts. Large output keeps its original beginning
+and end within a 24 KiB first-response text budget, with a full-log reference when
+persistence succeeds. `task_output` reads use byte offsets; a successful read can
+report a failed command. Stop failures and incomplete logs are reported separately.
+An optional `description` supplies the TUI summary while execution and permission
+checks continue to use the original command.
+
 ## Skill directory links
 
 Workspace `.agents/skills`, `.claude/skills`, and `.minimax/skills` support
diff --git a/packages/agent-tools/src/desktop/builtin-defs.ts b/packages/agent-tools/src/desktop/builtin-defs.ts
index ebc13739..24fb62a7 100644
--- a/packages/agent-tools/src/desktop/builtin-defs.ts
+++ b/packages/agent-tools/src/desktop/builtin-defs.ts
@@ -4,6 +4,7 @@ import type { ToolDefinition } from '@mavis/agent-core/tools';
 
 import { createMavisOperationClassifier } from '../shared/mavis-operation-classifier.js';
 import { LOCAL_MAVIS_COMMANDS } from './local-mavis-commands.js';
+import { BashDescriptionSchema } from './local-bash-input.js';
 import { prepareAskUserArguments } from './prepare-ask-user-arguments.js';
 
 import {
@@ -102,33 +103,17 @@ export const LocalEditToolDef = {
 } as const satisfies ToolDefinition;
 export type LocalEditToolInput = Static<typeof LocalEditToolDef.schema>;
 
-const _isWindows = process.platform === 'win32';
-const MAX_BACKGROUND_BASH_TIMEOUT_SECONDS = 2_147_483;
-
 export const LocalBashToolDef = {
   name: 'bash',
   executionMode: 'sequential',
   description: [
-    'Executes a command in a fresh local shell and returns its output.',
+    'Executes a shell command and returns its output.',
     '',
-    '- Each call starts in the session workspace. `cd` and shell state do not persist between calls; use absolute paths or change directories within the same command.',
-    '- Use dedicated `read`, `write`, `edit`, `grep`, and `glob` tools for file operations. Do not use shell commands for file reading, searching, or modification unless the user explicitly requests it or you have verified that the dedicated tools cannot perform the required operation. Use `bash` for processes, git, package managers, builds, tests, and necessary pipelines.',
-    '- The shell is non-interactive: no TTY or stdin prompts. Run non-interactive commands yourself; check `--help` for suitable flags before asking the user to run one. Leave physical authorization (OAuth consent, MFA, hardware keys) to the user.',
-    '- Use `run_in_background` for long commands. Do not increase timeouts to mask hung commands. A returned task id refers to the original process; do not rerun it. Use `task_query` or `task_output` to inspect progress and `task_stop` to cancel.',
+    '- Each call starts in the session workspace. Changes to the working directory and shell state (variables and functions) do not persist between calls. If a command requires a different working directory, change directories within the same call.',
+    '- Use dedicated `read`, `write`, `edit`, `grep`, and `glob` tools for file operations. Do not use shell commands for file reading, searching, or modification unless the user explicitly requests it or you have verified that the dedicated tools cannot perform the required operation. Use `bash` for processes, git, package managers, builds, tests, and pipelines.',
+    '- The shell is non-interactive: no TTY or stdin prompts. For commands that require interaction, check `--help` for non-interactive options before asking the user to run them. Leave physical authorization (OAuth consent, MFA, hardware keys) to the user.',
     '- For file or directory deletion, use one top-level `rm -- <path> ...`; the local runtime routes it through recoverable deletion.',
     '- Do not bypass recoverable deletion with absolute paths to deletion commands or inline scripts. If it fails, report the failure instead of falling back to permanent deletion. Permission checks still apply.',
-    ...(_isWindows
-      ? [
-          '',
-          'Windows shell:',
-          '- PowerShell is preferred; Bash is a fallback when PowerShell is unavailable. Match the selected shell syntax.',
-          '- For PowerShell, use `$env:VAR`; do not use `export`, `/dev/null`, heredocs, `sed -i`, or `&&`. Do not wrap commands in `powershell -Command`.',
-          "- Start multi-statement PowerShell scripts with `$ErrorActionPreference = 'Stop'`. Use single quotes for literals and regex patterns. Do NOT use Bash-style backslash escapes.",
-          '- For native program failures in PowerShell, check `$LASTEXITCODE` or enable `$PSNativeCommandUseErrorActionPreference` when available.',
-          '- Avoid `Get-Content | ... | Set-Content` file-editing pipelines. Prefer file tools or a script with explicit UTF-8 encoding for batch changes. If Get-Content/Set-Content are needed, specify `-Encoding UTF8`; PowerShell 5.1 writes a BOM.',
-          '- If a CLI is missing, check `.cmd` or `.ps1` wrappers. If `bash` opens WSL or produces garbled output, switch to direct `node`/`python` execution or a verified Git Bash path. After two failures with the same approach, change strategy.',
-        ]
-      : []),
     '',
     '# Git',
     '- Interactive flags (`-i`, e.g. `git rebase -i`, `git add -i`) are not supported in this environment.',
@@ -137,19 +122,19 @@ export const LocalBashToolDef = {
   ].join('\n'),
   schema: Type.Object({
     command: Type.String({
-      description: 'Shell command line to execute locally.',
+      description: 'The command to execute',
     }),
+    description: BashDescriptionSchema,
     timeout: Type.Optional(
       Type.Number({
-        maximum: MAX_BACKGROUND_BASH_TIMEOUT_SECONDS,
+        exclusiveMinimum: 0,
         description:
-          'Timeout in seconds. Foreground: default 120s, max 300s. Use run_in_background for longer commands. Background tasks use the requested timeout, subject to a runtime watchdog.',
+          'Total command timeout in seconds. Foreground-only: default 120s, max 300s. Foreground with automatic backgrounding: default/max 600s, including foreground time. Explicit background: uses the specified timeout, or a 30-minute limit if omitted.',
       }),
     ),
     run_in_background: Type.Optional(
       Type.Boolean({
-        description:
-          'Start in the background and return a task id immediately. Foreground commands may also return a task id after 15s without restarting the process.',
+        description: 'Set to true to run this command in the background.',
       }),
     ),
   }),
diff --git a/packages/agent-tools/src/desktop/index.ts b/packages/agent-tools/src/desktop/index.ts
index 5b289f55..7d8b8875 100644
--- a/packages/agent-tools/src/desktop/index.ts
+++ b/packages/agent-tools/src/desktop/index.ts
@@ -49,6 +49,10 @@ export * from './local-ask-user.js';
 export * from './local-feature-enable.js';
 export * from './local-browser.js';
 export * from './local-pi-tools.js';
+export * from './local-bash-result.js';
+export * from './local-bash-timing.js';
+export * from './local-bash-input.js';
+export * from './local-bash-contract.js';
 export { executeLocalHostTrashIfRequested } from './host-trash-executor.js';
 export type { LocalHostTrashRuntime } from './host-trash-executor.js';
 export * from './local-glob.js';
@@ -198,3 +202,4 @@ export {
   CloudSessionReadError,
   type CloudSessionReaderOptions,
 } from './cloud-session-reader.js';
+export { DESKTOP_BASH_PREVIEW_BYTES } from './output-limit.js';
diff --git a/packages/agent-tools/src/desktop/local-bash-contract.ts b/packages/agent-tools/src/desktop/local-bash-contract.ts
new file mode 100644
index 00000000..fd1e210a
--- /dev/null
+++ b/packages/agent-tools/src/desktop/local-bash-contract.ts
@@ -0,0 +1,83 @@
+import { getShellConfig } from '@earendil-works/pi-coding-agent/shell';
+import type { ToolDefinition } from '@mavis/agent-core/tools';
+import { Clone, Type } from '@sinclair/typebox';
+
+import { LocalBashToolDef } from './builtin-defs.js';
+import {
+  DEFAULT_FOREGROUND_BASH_SOFT_YIELD_MS,
+  DEFAULT_FOREGROUND_BASH_TIMEOUT_SECONDS,
+  MAX_FOREGROUND_BASH_TIMEOUT_SECONDS,
+  MAX_MANAGED_BASH_TIMEOUT_SECONDS,
+} from './local-bash-timing.js';
+
+export interface LocalBashTurnCapabilities {
+  readonly background: boolean;
+  readonly shell: ReturnType<typeof getShellConfig>['type'] | 'unavailable';
+}
+
+export function resolveLocalBashShell(): LocalBashTurnCapabilities['shell'] {
+  try {
+    return getShellConfig().type;
+  } catch {
+    return 'unavailable';
+  }
+}
+
+/** A fresh definition for the final admitted Turn inventory. */
+export function createLocalBashToolDefinition(
+  capabilities: LocalBashTurnCapabilities,
+): ToolDefinition {
+  const base = Clone(LocalBashToolDef.schema);
+  const schema = capabilities.background ? base : Type.Omit(base, ['run_in_background']);
+  schema.properties.timeout.description = capabilities.background
+    ? `Total command timeout in seconds. Foreground with automatic backgrounding: default/max ${MAX_MANAGED_BASH_TIMEOUT_SECONDS}s, including foreground time. Explicit background: uses the specified timeout, or a 30-minute limit if omitted.`
+    : `Timeout in seconds. Foreground: default ${DEFAULT_FOREGROUND_BASH_TIMEOUT_SECONDS}s; values above ${MAX_FOREGROUND_BASH_TIMEOUT_SECONDS}s are capped.`;
+  return {
+    ...LocalBashToolDef,
+    schema,
+    description: `${LocalBashToolDef.description}\n\n${renderBashUsage(capabilities)}`,
+  };
+}
+
+function renderBashUsage(capabilities: LocalBashTurnCapabilities): string {
+  return [
+    ...(capabilities.background
+      ? [
+          `- Foreground calls wait up to ${DEFAULT_FOREGROUND_BASH_SOFT_YIELD_MS / 1000}s, then return a task_id if unfinished. The same command continues in the background; do not start it again.`,
+          '- Set run_in_background=true to return a task_id without waiting for completion.',
+          '- Background completion notifies you automatically. Continue independent work; use task_output for current output and task_stop, when available, to cancel.',
+          '- Backgrounding and reading output do not reset the command timeout.',
+        ]
+      : ['- This Turn supports foreground execution only.']),
+    "- Large output preserves the beginning and end. Follow the result's instructions to read omitted output.",
+    ...shellRules(capabilities.shell),
+  ].join('\n');
+}
+
+function shellRules(shell: LocalBashTurnCapabilities['shell']): string[] {
+  if (shell === 'unavailable')
+    return [
+      '- No local shell was resolved. Do not assume Bash or PowerShell syntax is executable.',
+    ];
+  if (shell === 'bash')
+    return [
+      '- Selected shell: Bash. Use Bash syntax, including on Windows when Bash is the selected fallback.',
+    ];
+  if (shell === 'sh')
+    return [
+      '- Selected shell: POSIX sh. Use POSIX shell syntax; Bash arrays, [[ ... ]] and process substitution are unavailable.',
+    ];
+  return [
+    shell === 'pwsh'
+      ? '- Selected shell: PowerShell 7 (pwsh). Pipeline-chain operators && and || are supported; use PowerShell quoting and variable syntax.'
+      : '- Selected shell: Windows PowerShell 5.1. The && and || operators are unsupported; use separate statements and explicit success checks.',
+    '- Use $env:VAR and single quotes for literals/regex. Do not use Bash export, /dev/null, heredocs, sed -i, or backslash quoting. Do not wrap ordinary commands in powershell -Command or cmd /c.',
+    "- Start multi-statement scripts with $ErrorActionPreference = 'Stop'. Check $LASTEXITCODE after native programs, or enable $PSNativeCommandUseErrorActionPreference when available.",
+    `- Prefer dedicated file tools. If shell file I/O is necessary, specify UTF-8 and avoid Get-Content | ... | Set-Content editing pipelines.${
+      shell === 'powershell'
+        ? ' PowerShell 5.1 -Encoding UTF8 writes a BOM.'
+        : ' PowerShell 7 defaults to UTF-8 without BOM.'
+    }`,
+    '- If a CLI is missing, check .cmd/.ps1 wrappers. Change strategy after repeated syntax failures.',
+  ];
+}
diff --git a/packages/agent-tools/src/desktop/local-bash-input.ts b/packages/agent-tools/src/desktop/local-bash-input.ts
new file mode 100644
index 00000000..aba2d6f8
--- /dev/null
+++ b/packages/agent-tools/src/desktop/local-bash-input.ts
@@ -0,0 +1,14 @@
+import { Type } from '@sinclair/typebox';
+
+export const BashDescriptionSchema = Type.Optional(
+  Type.String({
+    description: 'A short description of what this command does.',
+  }),
+);
+
+export function resolveBashDescription(description: unknown, command: string): string {
+  if (description !== undefined && typeof description !== 'string') {
+    throw new Error('Bash description must be a string.');
+  }
+  return description || command;
+}
diff --git a/packages/agent-tools/src/desktop/local-bash-result.ts b/packages/agent-tools/src/desktop/local-bash-result.ts
new file mode 100644
index 00000000..ca29c048
--- /dev/null
+++ b/packages/agent-tools/src/desktop/local-bash-result.ts
@@ -0,0 +1,99 @@
+import {
+  BashExecutionError,
+  type BashExecutionOutcome,
+  type BashToolDetails,
+} from '@earendil-works/pi-coding-agent/tools';
+import type { AgentToolResult } from '@earendil-works/pi-agent-core';
+
+import type { LocalBackgroundBashExecutorResult } from './types.js';
+
+export interface LocalBashExecutionOutcome extends Omit<BashExecutionOutcome, 'reason'> {
+  reason: BashExecutionOutcome['reason'] | 'preflight_failed' | 'watchdog_timeout';
+}
+
+export function localBashResultFromPi(
+  result: AgentToolResult<unknown>,
+): LocalBackgroundBashExecutorResult {
+  const details = (result.details ?? {}) as Record<string, unknown>;
+  const execution = readBashExecutionOutcome(details);
+  return {
+    text: result.content
+      .filter((part): part is { type: 'text'; text: string } => part.type === 'text')
+      .map((part) => part.text)
+      .join('\n'),
+    details,
+    ...(execution && execution.status !== 'succeeded' ? { isError: true } : {}),
+  };
+}
+
+export function localBashResultFromError(
+  error: unknown,
+  signal?: AbortSignal,
+): LocalBackgroundBashExecutorResult {
+  const details: BashToolDetails = error instanceof BashExecutionError ? error.details : {};
+  const cause = error instanceof BashExecutionError ? error.cause : error;
+  const causeRecord =
+    cause && typeof cause === 'object' ? (cause as Record<string, unknown>) : undefined;
+  const errorCode = typeof causeRecord?.code === 'string' ? causeRecord.code : undefined;
+  const preflight =
+    errorCode?.startsWith('SANDBOX_') &&
+    (causeRecord?.stage === undefined ||
+      ['init', 'parse', 'invocation', 'pre-spawn'].includes(String(causeRecord.stage)));
+  const text = error instanceof Error ? error.message : String(error);
+  const execution: LocalBashExecutionOutcome = {
+    status: signal?.aborted ? 'canceled' : 'failed',
+    reason: signal?.aborted ? 'canceled' : 'unknown',
+    exitCode: null,
+    message: text,
+    ...(errorCode ? { errorCode } : {}),
+    ...details.execution,
+    ...(preflight ? { reason: 'preflight_failed' as const } : {}),
+  };
+  if (execution.status === 'canceled' && !execution.cancellationReason && signal?.aborted) {
+    execution.cancellationReason =
+      signal.reason instanceof Error
+        ? signal.reason.message
+        : typeof signal.reason === 'string'
+          ? signal.reason
+          : undefined;
+  }
+  return { text, details: { ...details, execution }, isError: true };
+}
+
+export function readBashExecutionOutcome(details: unknown): LocalBashExecutionOutcome | undefined {
+  if (!details || typeof details !== 'object' || !('execution' in details)) return undefined;
+  const execution = details.execution;
+  if (!execution || typeof execution !== 'object') return undefined;
+  const value = execution as Record<string, unknown>;
+  if (
+    typeof value.status !== 'string' ||
+    !['succeeded', 'failed', 'canceled'].includes(value.status) ||
+    typeof value.reason !== 'string' ||
+    ![
+      'exited',
+      'signaled',
+      'command_timeout',
+      'canceled',
+      'spawn_failed',
+      'unknown',
+      'preflight_failed',
+      'watchdog_timeout',
+    ].includes(value.reason) ||
+    !(
+      value.exitCode === null ||
+      (typeof value.exitCode === 'number' && Number.isInteger(value.exitCode))
+    ) ||
+    [value.signal, value.errorCode, value.message, value.cancellationReason].some(
+      (field) => field !== undefined && typeof field !== 'string',
+    )
+  )
+    return undefined;
+  return execution as LocalBashExecutionOutcome;
+}
+
+export function formatBashExecutionOutcome(execution: LocalBashExecutionOutcome): string {
+  if (execution.message) return execution.message;
+  if (execution.signal) return `Command terminated by signal ${execution.signal}`;
+  if (execution.exitCode !== null) return `Command exited with code ${execution.exitCode}`;
+  return `Command ${execution.status} (${execution.reason})`;
+}
diff --git a/packages/agent-tools/src/desktop/local-bash-timing.ts b/packages/agent-tools/src/desktop/local-bash-timing.ts
new file mode 100644
index 00000000..57710fff
--- /dev/null
+++ b/packages/agent-tools/src/desktop/local-bash-timing.ts
@@ -0,0 +1,62 @@
+import type { ToolResult } from '@mavis/agent-core/tools';
+
+export const DEFAULT_FOREGROUND_BASH_TIMEOUT_SECONDS = 120;
+export const MAX_FOREGROUND_BASH_TIMEOUT_SECONDS = 300;
+export const MAX_MANAGED_BASH_TIMEOUT_SECONDS = 600;
+export const MAX_BASH_TIMEOUT_SECONDS = 2_147_483;
+export const DEFAULT_FOREGROUND_BASH_SOFT_YIELD_MS = 60_000;
+
+export interface LocalBashTiming {
+  commandTimeoutSeconds?: number;
+  requestedTimeoutSeconds?: number;
+  commandTimerStartedAt?: number;
+  commandDeadlineAt?: number;
+}
+
+export function resolveLocalBashTiming(
+  timeout: number | undefined,
+  mode: 'direct_foreground' | 'managed_foreground' | 'explicit_background',
+): LocalBashTiming {
+  if (
+    timeout !== undefined &&
+    (!Number.isFinite(timeout) || timeout <= 0 || timeout > MAX_BASH_TIMEOUT_SECONDS)
+  ) {
+    throw new Error(
+      `timeout must be a finite positive number of seconds, at most ${MAX_BASH_TIMEOUT_SECONDS}.`,
+    );
+  }
+  const commandTimeoutSeconds =
+    mode === 'explicit_background'
+      ? timeout
+      : mode === 'managed_foreground'
+        ? Math.min(timeout ?? MAX_MANAGED_BASH_TIMEOUT_SECONDS, MAX_MANAGED_BASH_TIMEOUT_SECONDS)
+        : Math.min(
+            timeout ?? DEFAULT_FOREGROUND_BASH_TIMEOUT_SECONDS,
+            MAX_FOREGROUND_BASH_TIMEOUT_SECONDS,
+          );
+  return {
+    commandTimeoutSeconds,
+    ...(timeout !== undefined && timeout !== commandTimeoutSeconds
+      ? { requestedTimeoutSeconds: timeout }
+      : {}),
+  };
+}
+
+export function validateBashCommand(command: string): void {
+  if (typeof command !== 'string' || command.trim().length === 0) {
+    throw new Error('command must be a non-empty shell command.');
+  }
+}
+
+export function withLocalBashTiming(result: ToolResult, timing: LocalBashTiming): ToolResult {
+  const text =
+    timing.requestedTimeoutSeconds !== undefined
+      ? `${result.text}\n\n[bash timeout: requested ${timing.requestedTimeoutSeconds}s; effective ${timing.commandTimeoutSeconds}s command limit.]`
+      : result.text;
+  return {
+    ...result,
+    text,
+    content: [{ type: 'text', text }],
+    details: { ...result.details, timing: { ...(result.details?.timing as object), ...timing } },
+  };
+}
diff --git a/packages/agent-tools/src/desktop/local-pi-tools.ts b/packages/agent-tools/src/desktop/local-pi-tools.ts
index 81c0c3ed..a206248c 100644
--- a/packages/agent-tools/src/desktop/local-pi-tools.ts
+++ b/packages/agent-tools/src/desktop/local-pi-tools.ts
@@ -21,6 +21,19 @@ import { isAbsolute, resolve as resolvePath } from 'node:path';
 import { homedir, release } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { randomUUID } from 'node:crypto';
+import { resolveBashDescription } from './local-bash-input.js';
+import {
+  DEFAULT_FOREGROUND_BASH_SOFT_YIELD_MS,
+  resolveLocalBashTiming,
+  validateBashCommand,
+  withLocalBashTiming,
+  type LocalBashTiming,
+} from './local-bash-timing.js';
+import {
+  localBashResultFromError,
+  localBashResultFromPi,
+  readBashExecutionOutcome,
+} from './local-bash-result.js';
 
 import {
   LocalBashToolDef,
@@ -65,6 +78,7 @@ import { buildWriteToolResult, createCapturingWriteOperations } from '../shared/
 import {
   applyDesktopTextLimit,
   DESKTOP_BASH_MAX_BYTES,
+  DESKTOP_BASH_PREVIEW_BYTES,
   DESKTOP_READ_TEXT_MAX_BYTES,
   limitDesktopHeadTailLines,
   limitDesktopPrefixLines,
@@ -372,6 +386,11 @@ export class LocalBashTool implements ToolImpl<
     // The background executor and the pi-turn-runner fallback apply the same
     // hook — keep the three spawn sites in sync.
     this.tool = createBashTool(workspaceRoot, {
+      output: {
+        strategy: 'head_tail',
+        maxBytes: DESKTOP_BASH_PREVIEW_BYTES,
+        maxLines: Number.MAX_SAFE_INTEGER,
+      },
       spawnHook: (ctx) => {
         const { env, removed } = sanitizeBashSubprocessEnv(ctx.env, this.envPolicy);
         this.lastEnvRemoved = removed;
@@ -386,6 +405,49 @@ export class LocalBashTool implements ToolImpl<
     signal?: AbortSignal,
   ): Promise<ToolResult> {
     if (signal?.aborted) throw new Error('Operation aborted');
+    let timing: LocalBashTiming;
+    let description: string;
+    try {
+      description = resolveBashDescription(input.description, input.command);
+      validateBashCommand(input.command);
+      timing = resolveLocalBashTiming(
+        input.timeout,
+        input.run_in_background
+          ? 'explicit_background'
+          : ctx.canConsumeBackgroundBashOutput === true &&
+              ctx.allowBashAutoPromotion !== false &&
+              this.backgroundAdapter?.runManagedForeground
+            ? 'managed_foreground'
+            : 'direct_foreground',
+      );
+    } catch (error) {
+      const text = error instanceof Error ? error.message : String(error);
+      return {
+        tool_name: LocalBashToolDef.name,
+        text,
+        content: [{ type: 'text', text }],
+        isError: true,
+        details: { status: 'invalid_input', error_code: 'BASH_INVALID_INPUT' },
+      };
+    }
+    try {
+      const result = await this.executeValidated(ctx, { ...input, description }, timing, signal);
+      return { ...result, details: { ...result.details, description } };
+    } catch (error) {
+      if (error instanceof Error) {
+        const details = (error as Error & { details?: Record<string, unknown> }).details;
+        Object.assign(error, { details: { ...details, description } });
+      }
+      throw error;
+    }
+  }
+
+  private async executeValidated(
+    ctx: LocalRuntimeToolContext,
+    input: LocalBashToolInput,
+    timing: LocalBashTiming,
+    signal?: AbortSignal,
+  ): Promise<ToolResult> {
     if (input.run_in_background === true && ctx.canConsumeBackgroundBashOutput !== true) {
       return unavailableBackgroundBashOutputResult();
     }
@@ -426,16 +488,24 @@ export class LocalBashTool implements ToolImpl<
       return backgroundBashToolResult(
         started.taskId,
         'started',
-        this.consumeEnvSanitizationHint(started.details),
+        this.consumeEnvSanitizationHint({
+          ...started.details,
+          description: input.description,
+          timing: { ...timing, ...(started.details?.timing as object) },
+        }),
       );
     }
 
     const { run_in_background: _runInBackground, ...rest } = input;
-    const foregroundInput = { ...rest, timeout: resolveForegroundTimeout(rest) };
-    if (ctx.allowBashAutoPromotion !== false && this.backgroundAdapter?.runManagedForeground) {
+    const foregroundInput = { ...rest, timeout: timing.commandTimeoutSeconds };
+    if (
+      ctx.canConsumeBackgroundBashOutput === true &&
+      ctx.allowBashAutoPromotion !== false &&
+      this.backgroundAdapter?.runManagedForeground
+    ) {
       const managed = await this.backgroundAdapter.runManagedForeground(
         ctx,
-        foregroundInput,
+        rest,
         DEFAULT_FOREGROUND_BASH_SOFT_YIELD_MS,
         signal,
       );
@@ -444,7 +514,11 @@ export class LocalBashTool implements ToolImpl<
           return backgroundBashToolResult(
             managed.taskId,
             'auto_promoted',
-            this.consumeEnvSanitizationHint(managed.details),
+            this.consumeEnvSanitizationHint({
+              ...managed.details,
+              description: input.description,
+              timing: { ...timing, ...(managed.details?.timing as object) },
+            }),
           );
         }
         const text = `<bash_error>${managed.errorMessage ?? 'Local managed bash failed to start'}</bash_error>`;
@@ -460,27 +534,36 @@ export class LocalBashTool implements ToolImpl<
         typeof managed.details?.fullOutputPath === 'string'
           ? managed.details.fullOutputPath
           : undefined;
-      const limited = limitDesktopBashOutput(managed.text, managedFullOutputPath);
+
       const managedDetails = this.consumeEnvSanitizationHint(managed.details);
-      return applyDesktopTextLimit(
-        {
+      const result = withLocalBashTiming(
+        withCompatibleBashToolResponseFromPiDetails({
           tool_name: LocalBashToolDef.name,
           text: managed.text,
           content: [{ type: 'text', text: managed.text }],
           details: {
             ...managedDetails,
-            status: 'completed',
+            status: readBashExecutionOutcome(managedDetails)?.status ?? 'completed',
             task_id: managed.taskId,
           },
           ...(managed.isError ? { isError: true } : {}),
-        },
-        limited,
+        }),
+        timing,
+      );
+      return applyDesktopTextLimit(
+        result,
+        limitDesktopBashOutput(result.text, managedFullOutputPath, result.details, managed.taskId),
       );
     }
     let result: ToolResult;
     try {
       const tool = this.sandboxOperationsFactory
         ? createBashTool(this.workspaceRoot, {
+            output: {
+              strategy: 'head_tail',
+              maxBytes: DESKTOP_BASH_PREVIEW_BYTES,
+              maxLines: Number.MAX_SAFE_INTEGER,
+            },
             operations: this.sandboxOperationsFactory.create({
               identity: directForegroundIdentity(ctx),
               workspaceRoot: this.workspaceRoot,
@@ -493,28 +576,29 @@ export class LocalBashTool implements ToolImpl<
           })
         : this.tool;
       const res = await tool.execute('', foregroundInput, signal);
-      result = withCompatibleBashToolResponseFromPiDetails(
-        toToolResult(LocalBashToolDef.name, res),
-      );
+      const completed = localBashResultFromPi(res);
+      result = withCompatibleBashToolResponseFromPiDetails({
+        tool_name: LocalBashToolDef.name,
+        ...completed,
+        content: [{ type: 'text', text: completed.text }],
+      });
     } catch (error) {
       if (signal?.aborted || (error instanceof Error && error.name === 'AbortError')) {
         throw error;
       }
-      const text = error instanceof Error ? error.message : String(error);
-      const fullOutputPath = extractBashFullOutputPath(text);
-      result = {
+      const failed = localBashResultFromError(error, signal);
+      result = withCompatibleBashToolResponseFromPiDetails({
         tool_name: LocalBashToolDef.name,
-        text,
-        content: [{ type: 'text', text }],
-        ...(fullOutputPath ? { details: { fullOutputPath } } : {}),
-        isError: true,
-      };
+        ...failed,
+        content: [{ type: 'text', text: failed.text }],
+      });
     }
+    result = withLocalBashTiming(result, timing);
     const fullOutputPath =
       typeof result.details?.fullOutputPath === 'string'
         ? result.details.fullOutputPath
         : undefined;
-    const limited = limitDesktopBashOutput(result.text, fullOutputPath);
+    const limited = limitDesktopBashOutput(result.text, fullOutputPath, result.details);
     result = applyDesktopTextLimit(result, limited);
     result.details = this.consumeEnvSanitizationHint({
       ...(result.details ?? {}),
@@ -550,57 +634,67 @@ function directForegroundIdentity(ctx: LocalRuntimeToolContext): LocalSandboxInv
   };
 }
 
-function limitDesktopBashOutput(text: string, fullOutputPath?: string) {
-  const limited = limitDesktopHeadTailLines(text, {
+function limitDesktopBashOutput(
+  text: string,
+  fullOutputPath?: string,
+  details?: Record<string, unknown>,
+  taskId?: string,
+) {
+  const output = details?.output as { rawBytes?: number; persistenceError?: string } | undefined;
+  let previewText = text;
+  if (!taskId) {
+    if ((details?.truncation as { truncated?: boolean } | undefined)?.truncated) {
+      previewText += `\n\n[desktop bash output truncated: original_bytes=${output?.rawBytes}; original head+tail shown.${fullOutputPath ? ` Full output: ${fullOutputPath}` : ''}]`;
+    }
+    if (output?.persistenceError) {
+      previewText += `\n\n[Output persistence failed; complete output is unavailable: ${output.persistenceError}]`;
+    }
+  }
+  const limited = limitDesktopHeadTailLines(previewText, {
     maxBytes: DESKTOP_BASH_MAX_BYTES,
     notice: ({ originalBytes }) =>
       fullOutputPath
         ? `[desktop bash output truncated: original_bytes=${originalBytes}; head+tail shown; boundary lines may be UTF-8 byte-truncated; Full output: ${fullOutputPath}]`
-        : `[desktop bash output truncated: original_bytes=${originalBytes}; head+tail shown; boundary lines may be UTF-8 byte-truncated; rerun with a narrower command or redirect output to a file and use read.]`,
+        : `[desktop bash output truncated: original_bytes=${originalBytes}; head+tail shown; boundary lines may be UTF-8 byte-truncated.]`,
   });
+  if (
+    limited.truncation ||
+    (details?.truncation as { truncated?: boolean } | undefined)?.truncated
+  ) {
+    limited.truncation = {
+      truncated: true,
+      has_more: true,
+      strategy: 'head_tail_lines',
+      original_bytes:
+        output?.rawBytes ?? limited.truncation?.original_bytes ?? Buffer.byteLength(text, 'utf8'),
+      returned_bytes: Buffer.byteLength(limited.text, 'utf8'),
+      max_bytes: DESKTOP_BASH_MAX_BYTES,
+    };
+  }
   return withDesktopOutputContinuation(limited, {
-    continuation_hint: fullOutputPath
+    continuation_hint: taskId
       ? {
-          tool: 'read',
-          preserve_args: ['path'],
-          instruction: `Read the full output at ${fullOutputPath}; continue long reads with the returned next_offset.`,
+          tool: 'task_output',
+          preserve_args: ['task_id'],
+          instruction: `Read task ${taskId} with task_output; continue with its next_offset (UTF-8 log file bytes). Check output persistence status before treating the log as complete.`,
         }
-      : {
-          tool: 'bash',
-          preserve_args: [],
-          instruction:
-            'Do not blindly rerun a potentially side-effecting command; narrow it or redirect output to a file, then use read.',
-        },
+      : fullOutputPath
+        ? {
+            tool: 'read',
+            preserve_args: ['path'],
+            instruction: `Read the full output at ${fullOutputPath}; continue long reads with the returned next_offset.`,
+          }
+        : {
+            tool: 'bash',
+            preserve_args: [],
+            instruction:
+              'Do not blindly rerun a potentially side-effecting command; narrow it or redirect output to a file, then use read.',
+          },
   });
 }
 
-function extractBashFullOutputPath(text: string): string | undefined {
-  const matches = [...text.matchAll(/Full output:\s*(.+?)\](?:\n|$)/gi)];
-  const path = matches.at(-1)?.[1]?.trim();
-  return path || undefined;
-}
-
-/**
- * Default foreground timeout (seconds) applied when the model omits `timeout`.
- * Restores main's historical 120s bound so interactive/blocking foreground
- * commands (e.g. `lark-cli auth login`) cannot hang forever. Background tasks
- * (`run_in_background: true`) are intentionally NOT bounded by this.
- */
-export const DEFAULT_FOREGROUND_BASH_TIMEOUT_SECONDS = 120;
-export const MAX_FOREGROUND_BASH_TIMEOUT_SECONDS = 300;
-export const DEFAULT_FOREGROUND_BASH_SOFT_YIELD_MS = 15_000;
-
-/**
- * Keep interactive foreground commands bounded. Missing, non-finite and
- * non-positive values use the 120s default; larger values are capped at 5m.
- * Longer commands should opt into background execution explicitly.
- */
 export function resolveForegroundTimeout(input: { timeout?: number }): number {
-  const requested = input.timeout;
-  if (requested === undefined || !Number.isFinite(requested) || requested <= 0) {
-    return DEFAULT_FOREGROUND_BASH_TIMEOUT_SECONDS;
-  }
-  return Math.min(requested, MAX_FOREGROUND_BASH_TIMEOUT_SECONDS);
+  return resolveLocalBashTiming(input.timeout, 'direct_foreground').commandTimeoutSeconds!;
 }
 
 function backgroundBashToolResult(
@@ -611,8 +705,15 @@ function backgroundBashToolResult(
   const lead =
     status === 'auto_promoted'
       ? 'The command is still running and was yielded to a managed background task without restarting it.'
-      : 'Started local background bash task.';
-  const text = `<bash_background task_id="${taskId}">\n${lead} The owning conversation will automatically resume when it finishes; use task_query/task_output to inspect incremental output and task_stop to cancel it.\n</bash_background>`;
+      : 'Background Bash task accepted; command startup may still be in progress.';
+  const timing = details.timing as LocalBashTiming | undefined;
+  const timingText =
+    timing?.commandTimeoutSeconds !== undefined
+      ? ` Command limit: ${timing.commandTimeoutSeconds}s total; yielding does not reset it.`
+      : '';
+  const purpose =
+    typeof details.description === 'string' ? `Purpose: ${details.description}\n` : '';
+  const text = `<bash_background task_id="${taskId}">\n${purpose}${lead}${timingText} The owning conversation will automatically resume when it finishes; use task_output to inspect incremental output, and task_stop to cancel if that tool is available.\n</bash_background>`;
   return {
     tool_name: LocalBashToolDef.name,
     text,
@@ -735,3 +836,9 @@ async function pathExists(filePath: string): Promise<boolean> {
 function isFsNotFoundError(err: unknown): boolean {
   return typeof err === 'object' && err !== null && (err as { code?: unknown }).code === 'ENOENT';
 }
+
+export {
+  DEFAULT_FOREGROUND_BASH_TIMEOUT_SECONDS,
+  MAX_FOREGROUND_BASH_TIMEOUT_SECONDS,
+  DEFAULT_FOREGROUND_BASH_SOFT_YIELD_MS,
+} from './local-bash-timing.js';
diff --git a/packages/agent-tools/src/desktop/local-task-control.ts b/packages/agent-tools/src/desktop/local-task-control.ts
index 48f7f18b..cb05921f 100644
--- a/packages/agent-tools/src/desktop/local-task-control.ts
+++ b/packages/agent-tools/src/desktop/local-task-control.ts
@@ -14,6 +14,7 @@ import type {
   LocalTaskControlAdapter,
   LocalTaskOutputReadResult,
 } from './types.js';
+import { formatBashExecutionOutcome, readBashExecutionOutcome } from './local-bash-result.js';
 
 const MAX_TASK_OUTPUT_WAIT_MS = 30_000;
 
@@ -82,6 +83,13 @@ export class LocalTaskOutputTool implements ToolImpl<
       ...(signal ? { signal } : {}),
     });
     const status = read.status ?? task.status;
+    const snapshot = read.task ?? task;
+    const execution = readBashExecutionOutcome(snapshot.metadata?.bashDetails);
+    const output = (snapshot.metadata?.bashDetails as Record<string, unknown> | undefined)?.output;
+    const persistenceHint =
+      (output as { persistence?: string } | undefined)?.persistence === 'incomplete'
+        ? '<task_output_hint>Output persistence is incomplete; this log may be missing command output.</task_output_hint>\n'
+        : '';
     const body = read.content || '(no output yet)';
     const cursor = [
       ...(read.nextOffset === undefined ? [] : [`next_offset="${read.nextOffset}"`]),
@@ -94,10 +102,18 @@ export class LocalTaskOutputTool implements ToolImpl<
         ? ''
         : '<task_output_hint>Your requested wait_ms exceeded 30000 ms and was capped at 30000 ms (30 seconds). This output read reached its wait limit; the background task was not stopped. Use wait_ms=30000 or less for future reads.</task_output_hint>\n';
     const hint = signal?.aborted ? '' : this.pollingHint(ctx, input.task_id, { ...read, status });
-    const text = `<task_output status="${status}">\n${receipt}${waitLimitHint}${hint}${body}\n</task_output>`;
-    return ok(LocalTaskOutputToolDef.name, text, {
+    const outcome = execution
+      ? `<bash_status>${formatBashExecutionOutcome(execution)}</bash_status>\n`
+      : '';
+    const text = `<task_output status="${status}">\n${receipt}${waitLimitHint}${persistenceHint}${hint}${outcome}${body}\n</task_output>`;
+    const result = ok(LocalTaskOutputToolDef.name, text, {
       task_id: input.task_id,
       status,
+      ...(execution ? { execution } : {}),
+      ...(output ? { output } : {}),
+      timing:
+        (snapshot.metadata?.bashDetails as Record<string, unknown> | undefined)?.timing ??
+        snapshot.metadata?.timing,
       effective_wait_ms: effectiveWaitMs,
       wait_ms_clamped: waitMsClamped,
       ...(read.timedOut === undefined ? {} : { timed_out: read.timedOut }),
@@ -105,6 +121,7 @@ export class LocalTaskOutputTool implements ToolImpl<
       ...(read.truncated === undefined ? {} : { truncated: read.truncated }),
       ...(read.summary ? { summary: read.summary } : {}),
     });
+    return result;
   }
 
   private pollingHint(
@@ -152,8 +169,21 @@ export class LocalTaskStopTool implements ToolImpl<
   async execute(ctx: LocalRuntimeToolContext, input: LocalTaskStopToolInput): Promise<ToolResult> {
     const task = await this.adapter.stop(ctx, input.task_id, input.reason);
     if (!task) return notFound(LocalTaskStopToolDef.name, input.task_id);
-    const text = `<task_stop status="${task.status}">\nStop requested for ${input.task_id}.\n</task_stop>`;
-    return ok(LocalTaskStopToolDef.name, text, { task_id: input.task_id, status: task.status });
+    const stopError =
+      task.metadata?.stopError ??
+      (task.lastError?.code === 'TASK_STOP_FAILED' ? task.lastError : undefined);
+    const message = stopError
+      ? `Stop failed for ${input.task_id}: ${(stopError as { message: string }).message}. Process cleanup could not be confirmed.`
+      : `Task ${input.task_id} is ${task.status}.`;
+    const text = `<task_stop status="${task.status}">\n${message}\n</task_stop>`;
+    return {
+      ...ok(LocalTaskStopToolDef.name, text, {
+        task_id: input.task_id,
+        status: task.status,
+        ...(stopError ? { stopError } : {}),
+      }),
+      ...(stopError ? { isError: true } : {}),
+    };
   }
 }
 
@@ -167,16 +197,28 @@ function renderTask(task: BackgroundTask): string {
     ...(mode ? [`execution_mode=${mode}`] : []),
   ];
   const lineageText = lineage.length === 0 ? '' : ` (${lineage.join(' ')})`;
-  return `- ${task.taskId} [${task.kind}/${task.status}]${description}${lineageText}`;
+  const execution = readBashExecutionOutcome(task.metadata?.bashDetails);
+  const outcome = execution ? ` — ${formatBashExecutionOutcome(execution)}` : '';
+  const output = (task.metadata?.bashDetails as { output?: { persistence?: string } } | undefined)
+    ?.output;
+  const persistence = output?.persistence === 'incomplete' ? ' — output log incomplete' : '';
+  return `- ${task.taskId} [${task.kind}/${task.status}]${description}${lineageText}${outcome}${persistence}`;
 }
 
 function summarizeTask(task: BackgroundTask): Record<string, unknown> {
   const sessionId = childSessionId(task);
   const mode = executionMode(task);
+  const execution = readBashExecutionOutcome(task.metadata?.bashDetails);
   return {
     task_id: task.taskId,
     kind: task.kind,
     status: task.status,
+    ...(execution ? { execution } : {}),
+    output: (task.metadata?.bashDetails as Record<string, unknown> | undefined)?.output,
+    timing:
+      (task.metadata?.bashDetails as Record<string, unknown> | undefined)?.timing ??
+      task.metadata?.timing,
+    ...(task.metadata?.stopError ? { stopError: task.metadata.stopError } : {}),
     // Handle recovery after the first receipt scrolled out of context. Only a
     // subagent task that really owns a child Session gets a session handle.
     ...(sessionId ? { session_id: sessionId } : {}),
diff --git a/packages/agent-tools/src/desktop/output-limit.ts b/packages/agent-tools/src/desktop/output-limit.ts
index b7225c83..eaf2e971 100644
--- a/packages/agent-tools/src/desktop/output-limit.ts
+++ b/packages/agent-tools/src/desktop/output-limit.ts
@@ -3,12 +3,14 @@ import type { ToolResult, ToolResultContent } from '@mavis/agent-core/tools';
 export const DESKTOP_GREP_CONTENT_MAX_BYTES = 16 * 1024;
 export const DESKTOP_READ_TEXT_MAX_BYTES = 24 * 1024;
 export const DESKTOP_BASH_MAX_BYTES = 24 * 1024;
+// Leave room for exit/timing receipts and the readable output reference.
+export const DESKTOP_BASH_PREVIEW_BYTES = DESKTOP_BASH_MAX_BYTES - 2048;
 
 export type DesktopOutputLimitStrategy = 'prefix_lines' | 'head_tail_lines';
 export type DesktopOutputOffsetUnit = 'line' | 'match' | 'file';
 
 export interface DesktopOutputContinuationHint {
-  tool: 'read' | 'grep' | 'glob' | 'mavis' | 'bash';
+  tool: 'read' | 'grep' | 'glob' | 'mavis' | 'bash' | 'task_output';
   preserve_args: readonly string[];
   instruction: string;
 }
diff --git a/packages/agent-tools/src/desktop/types.ts b/packages/agent-tools/src/desktop/types.ts
index 20f6f0b6..69f02edb 100644
--- a/packages/agent-tools/src/desktop/types.ts
+++ b/packages/agent-tools/src/desktop/types.ts
@@ -322,6 +322,7 @@ export interface LocalSandboxBashOperationsFactory {
 export interface LocalBackgroundBashExecutorResult {
   text: string;
   details?: Record<string, unknown>;
+  isError?: boolean;
 }
 
 export interface LocalBackgroundBashExecutor {
@@ -434,6 +435,8 @@ export interface LocalTaskOutputReadOptions extends TaskOutputReadOptions {
 export interface LocalTaskOutputReadResult extends TaskOutputReadResult {
   /** Status read from the same post-wait snapshot as the returned output. */
   status?: BackgroundTaskStatus;
+  /** Task facts from the same post-wait snapshot as status. */
+  task?: BackgroundTask;
   timedOut?: boolean;
 }
 
diff --git a/packages/agent-tools/test/desktop/local-bash-output.test.ts b/packages/agent-tools/test/desktop/local-bash-output.test.ts
new file mode 100644
index 00000000..ef3228c8
--- /dev/null
+++ b/packages/agent-tools/test/desktop/local-bash-output.test.ts
@@ -0,0 +1,207 @@
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { LocalBashTool } from '../../src/desktop/local-pi-tools.js';
+import { DESKTOP_BASH_MAX_BYTES } from '../../src/desktop/output-limit.js';
+import { readPluginHookCompatibleToolResponse } from '../../src/plugin-hooks/vendor-tool-response.js';
+import type { LocalRuntimeToolContext } from '../../src/desktop/types.js';
+
+const SESSION_CTX = {
+  sessionId: 'sess-test',
+  turnId: 'turn-test',
+} satisfies LocalRuntimeToolContext;
+
+describe('LocalBashTool — foreground output truncation', () => {
+  let workspace: string;
+
+  beforeEach(async () => {
+    workspace = await mkdtemp(join(tmpdir(), 'bash-output-'));
+  });
+  afterEach(async () => {
+    await rm(workspace, { recursive: true, force: true });
+  });
+
+  it('preserves exact stdout and stderr for Compatible PostToolUse', async () => {
+    const tool = new LocalBashTool(workspace, undefined, { mode: 'off' });
+    const result = await tool.execute(SESSION_CTX, {
+      command: "printf 'from-stdout'; printf 'from-stderr' >&2",
+    });
+
+    expect(readPluginHookCompatibleToolResponse(result)).toEqual({
+      stdout: 'from-stdout',
+      stderr: 'from-stderr',
+      interrupted: false,
+    });
+  });
+
+  it('short output is returned verbatim, not truncated', async () => {
+    const tool = new LocalBashTool(workspace, undefined, { mode: 'off' });
+    const result = await tool.execute(SESSION_CTX, { command: 'printf "a\\nb\\nc\\n"' });
+    expect(result.tool_name).toBe('bash');
+    expect(result.isError).toBeFalsy();
+    expect(result.text).toContain('a');
+    expect(result.text.toLowerCase()).not.toContain('full output:');
+  });
+
+  it.skipIf(process.platform === 'win32')('reports signal termination as a failed tool result with partial output', async () => {
+    const tool = new LocalBashTool(workspace, undefined, { mode: 'off' });
+    const result = await tool.execute(SESSION_CTX, {
+      command: "printf 'partial-output'; kill -TERM $$",
+      timeout: 3,
+    });
+
+    expect(result.isError).toBe(true);
+    expect(result.text).toContain('partial-output');
+    expect(result.text).toContain('Command terminated by signal SIGTERM');
+    expect(result.details).toMatchObject({
+      execution: { status: 'failed', reason: 'signaled', exitCode: null, signal: 'SIGTERM' },
+      processOutput: { stdout: 'partial-output', stderr: '' },
+    });
+  });
+
+  it('preserves original head and tail with one readable full output file', async () => {
+    const tool = new LocalBashTool(workspace, undefined, { mode: 'off' });
+    const script = `for(let i=0;i<400;i++) console.log('row-'+i+'-'+'x'.repeat(90))`;
+    const command = `${JSON.stringify(process.execPath)} -e ${JSON.stringify(script)}`;
+    const result = await tool.execute(SESSION_CTX, { command });
+
+    expect(Buffer.byteLength(result.text, 'utf8')).toBeLessThanOrEqual(
+      DESKTOP_BASH_MAX_BYTES,
+    );
+    expect(result.text).toContain('row-0-');
+    expect(result.text).toContain('row-399-');
+    expect(result.text).not.toContain('row-200-');
+    expect(result.text.toLowerCase()).toContain('full output:');
+    const full = await readFile(result.details?.fullOutputPath as string, 'utf8');
+    expect(full).toContain('row-200-');
+    expect(result.details?.output).toMatchObject({ rawBytes: Buffer.byteLength(full), persistence: 'complete' });
+    expect(result.details?.desktop_output_truncation).toMatchObject({
+      truncated: true,
+      has_more: true,
+      strategy: 'head_tail_lines',
+      max_bytes: DESKTOP_BASH_MAX_BYTES,
+      continuation_hint: {
+        tool: 'read',
+        preserve_args: ['path'],
+      },
+    });
+    expect(result.details?.desktop_output_truncation).not.toHaveProperty('next_offset');
+    expect(result.details?.desktop_output_truncation).not.toHaveProperty('offset_unit');
+  });
+
+  it('caps a thrown timeout result while preserving the error ToolResult status', async () => {
+    const tool = new LocalBashTool(workspace, undefined, { mode: 'off' });
+    const innerExecute = vi
+      .spyOn((tool as unknown as { tool: { execute: unknown } }).tool, 'execute')
+      .mockRejectedValue(
+        new Error(
+          `${'timeout-output\n'.repeat(2_000)}\n\nCommand timed out after 1 seconds`,
+        ),
+      );
+
+    const result = await tool.execute(SESSION_CTX, { command: 'ignored', timeout: 1 });
+
+    expect(innerExecute).toHaveBeenCalledOnce();
+    expect(result.isError).toBe(true);
+    expect(Buffer.byteLength(result.text, 'utf8')).toBeLessThanOrEqual(
+      DESKTOP_BASH_MAX_BYTES,
+    );
+    expect(result.text).toContain('Command timed out after 1 seconds');
+    expect(result.text).toContain('desktop bash output truncated');
+    expect(result.details?.desktop_output_truncation).toMatchObject({
+      truncated: true,
+      has_more: true,
+      strategy: 'head_tail_lines',
+      max_bytes: DESKTOP_BASH_MAX_BYTES,
+      continuation_hint: {
+        tool: 'bash',
+        preserve_args: [],
+      },
+    });
+  });
+
+  it('still propagates an active AbortSignal instead of converting cancellation to a tool result', async () => {
+    const tool = new LocalBashTool(workspace, undefined, { mode: 'off' });
+    const controller = new AbortController();
+    vi.spyOn((tool as unknown as { tool: { execute: unknown } }).tool, 'execute').mockImplementation(
+      async () => {
+        controller.abort();
+        throw new Error('Command aborted');
+      },
+    );
+
+    await expect(
+      tool.execute(SESSION_CTX, { command: 'ignored' }, controller.signal),
+    ).rejects.toThrow('Command aborted');
+  });
+
+  it('caps a large nonzero-exit result while preserving the error ToolResult status', async () => {
+    const tool = new LocalBashTool(workspace, undefined, { mode: 'off' });
+    const script = `for(let i=0;i<400;i++) console.error('error-row-'+i+'-'+'e'.repeat(90)); process.exit(7)`;
+    const command = `${JSON.stringify(process.execPath)} -e ${JSON.stringify(script)}`;
+    const result = await tool.execute(SESSION_CTX, { command });
+
+    expect(result.isError).toBe(true);
+    expect(Buffer.byteLength(result.text, 'utf8')).toBeLessThanOrEqual(
+      DESKTOP_BASH_MAX_BYTES,
+    );
+    expect(result.text).toContain('error-row-0-');
+    expect(result.text).toContain('error-row-399-');
+    expect(result.text).not.toContain('error-row-200-');
+    expect(result.text).toContain('Command exited with code 7');
+    expect(result.details).toMatchObject({
+      execution: { status: 'failed', reason: 'exited', exitCode: 7 },
+      processOutput: { exitCode: 7, interrupted: false },
+    });
+    expect(result.text).toContain('desktop bash output truncated');
+    expect(result.details?.desktop_output_truncation).toMatchObject({
+      truncated: true,
+      has_more: true,
+      strategy: 'head_tail_lines',
+      max_bytes: DESKTOP_BASH_MAX_BYTES,
+      continuation_hint: {
+        tool: 'read',
+        preserve_args: ['path'],
+      },
+    });
+  });
+
+  it('output beyond 2000 lines retains the original first and last lines', async () => {
+    const tool = new LocalBashTool(workspace, undefined, { mode: 'off' });
+    const script = `for(let i=0;i<3000;i++) console.log('spill-row-'+i+'-'+'z'.repeat(50))`;
+    const command = `${JSON.stringify(process.execPath)} -e ${JSON.stringify(script)}`;
+    const result = await tool.execute(SESSION_CTX, { command });
+
+    const lower = result.text.toLowerCase();
+    expect(lower).toContain('full output:');
+    expect(lower).toContain('original head+tail');
+    expect(Buffer.byteLength(result.text, 'utf8')).toBeLessThanOrEqual(
+      DESKTOP_BASH_MAX_BYTES,
+    );
+
+    expect(result.text).toContain('spill-row-2999-');
+    expect(result.text).toContain('spill-row-0-');
+    expect(result.details?.desktop_output_truncation).toMatchObject({
+      truncated: true,
+      has_more: true,
+      strategy: 'head_tail_lines',
+      max_bytes: DESKTOP_BASH_MAX_BYTES,
+      continuation_hint: {
+        tool: 'read',
+        preserve_args: ['path'],
+      },
+    });
+
+    // Recover the spilled path from the footer and confirm it holds the FULL output.
+    const m = result.text.match(/full output:\s*(.+?)\]/i);
+    expect(m).not.toBeNull();
+    const full = await readFile((m as RegExpMatchArray)[1].trim(), 'utf-8');
+    const fullLines = full.split('\n').filter((l) => l.length > 0);
+    expect(fullLines).toHaveLength(3000); // complete output, not the 50 KiB tail
+    expect(fullLines[0]).toContain('spill-row-0-');
+    expect(fullLines[fullLines.length - 1]).toContain('spill-row-2999-');
+  });
+});
diff --git a/packages/agent-tools/test/desktop/local-bash-timeout.test.ts b/packages/agent-tools/test/desktop/local-bash-timeout.test.ts
new file mode 100644
index 00000000..e409ad9b
--- /dev/null
+++ b/packages/agent-tools/test/desktop/local-bash-timeout.test.ts
@@ -0,0 +1,506 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { Value } from '@sinclair/typebox/value';
+
+import { LocalBashToolDef } from '../../src/desktop/builtin-defs.js';
+import { createLocalBashToolDefinition } from '../../src/desktop/local-bash-contract.js';
+import {
+  DEFAULT_FOREGROUND_BASH_TIMEOUT_SECONDS,
+  DEFAULT_FOREGROUND_BASH_SOFT_YIELD_MS,
+  LocalBashTool,
+  MAX_FOREGROUND_BASH_TIMEOUT_SECONDS,
+  resolveForegroundTimeout,
+} from '../../src/desktop/local-pi-tools.js';
+import type {
+  LocalBashAdapter,
+  LocalBashBackgroundStartResult,
+  LocalRuntimeToolContext,
+  LocalSandboxBashOperationsFactory,
+} from '../../src/desktop/types.js';
+
+const SESSION_CTX = {
+  sessionId: 'sess-test',
+  turnId: 'turn-test',
+} satisfies LocalRuntimeToolContext;
+
+function timeoutDescription(): string {
+  const props = (LocalBashToolDef.schema as { properties: Record<string, { description?: string }> })
+    .properties;
+  return props.timeout?.description ?? '';
+}
+
+describe('resolveForegroundTimeout (bounded foreground helper)', () => {
+  // TS-1 (P0): omitted timeout → 120s default.
+  it('defaults to 120 seconds when timeout is omitted', () => {
+    expect(resolveForegroundTimeout({})).toBe(120);
+    expect(resolveForegroundTimeout({})).toBe(DEFAULT_FOREGROUND_BASH_TIMEOUT_SECONDS);
+    expect(DEFAULT_FOREGROUND_BASH_TIMEOUT_SECONDS).toBe(120);
+  });
+
+  it('defaults to 120 seconds when timeout is explicitly undefined', () => {
+    expect(resolveForegroundTimeout({ timeout: undefined })).toBe(120);
+  });
+
+  it('honors a positive timeout up to the 300-second foreground cap', () => {
+    expect(resolveForegroundTimeout({ timeout: 5 })).toBe(5);
+    expect(resolveForegroundTimeout({ timeout: 100000 })).toBe(300);
+    expect(MAX_FOREGROUND_BASH_TIMEOUT_SECONDS).toBe(300);
+  });
+
+  it.each([0, -5, NaN, Infinity, 2_147_484])('rejects an invalid timeout %s before execution', (timeout) => {
+    expect(() => resolveForegroundTimeout({ timeout })).toThrow('finite positive');
+  });
+
+  it('preserves fractional seconds', () => {
+    expect(resolveForegroundTimeout({ timeout: 0.125 })).toBe(0.125);
+  });
+});
+
+it('requires a positive timeout in the shared schema', () => {
+  expect(Value.Check(LocalBashToolDef.schema, { description: '运行测试命令', command: 'echo ok', timeout: 0.5 })).toBe(true);
+  expect(Value.Check(LocalBashToolDef.schema, { description: '运行测试命令', command: 'echo ok', timeout: 0 })).toBe(false);
+});
+
+describe('LocalBashTool input timing contract', () => {
+  it.each([null, 42, false])('rejects non-string description %j before dispatch', async (description) => {
+    const startBackground = vi.fn();
+    const runManagedForeground = vi.fn();
+    const tool = new LocalBashTool('/tmp/workspace', { startBackground, runManagedForeground }, { mode: 'off' });
+    const input = { command: 'echo ok', description };
+    expect(Value.Check(LocalBashToolDef.schema, input)).toBe(false);
+    const result = await tool.execute({ ...SESSION_CTX, canConsumeBackgroundBashOutput: true }, input as never);
+    expect(result).toMatchObject({ isError: true, details: { error_code: 'BASH_INVALID_INPUT' } });
+    expect(startBackground).not.toHaveBeenCalled();
+    expect(runManagedForeground).not.toHaveBeenCalled();
+  });
+
+  it.each([undefined, ''])('uses the command when description is %j', async (description) => {
+    const startBackground = vi.fn(async () => ({ status: 'started' as const, taskId: 'task-description' }));
+    const tool = new LocalBashTool('/tmp/workspace', { startBackground }, { mode: 'off' });
+    const result = await tool.execute({ ...SESSION_CTX, canConsumeBackgroundBashOutput: true }, {
+      command: 'echo exact', description, run_in_background: true,
+    });
+    expect(startBackground.mock.calls[0]?.[1]).toMatchObject({ command: 'echo exact', description: 'echo exact' });
+    expect(result.details?.description).toBe('echo exact');
+  });
+
+  it('keeps the purpose separate from the executable command', async () => {
+    const startBackground = vi.fn(async () => ({ status: 'started' as const, taskId: 'task-description' }));
+    const tool = new LocalBashTool('/tmp/workspace', { startBackground }, { mode: 'off' });
+    const result = await tool.execute({ ...SESSION_CTX, canConsumeBackgroundBashOutput: true }, {
+      command: ' echo exact ', description: '检查工作区状态', run_in_background: true,
+    });
+    expect(startBackground.mock.calls[0]?.[1]).toMatchObject({ command: ' echo exact ', description: '检查工作区状态' });
+    expect(result.text).toContain('Purpose: 检查工作区状态');
+    expect(result.details?.description).toBe('检查工作区状态');
+  });
+
+  it.each([false, true])('rejects invalid parameters without dispatching (background=%s)', async (background) => {
+    const startBackground = vi.fn();
+    const runManagedForeground = vi.fn();
+    const tool = new LocalBashTool('/tmp/workspace', { startBackground, runManagedForeground }, { mode: 'off' });
+    for (const input of [{ description: '运行测试命令', command: 'echo ok', timeout: 0 }, { description: '运行测试命令', command: 'echo ok', timeout: Infinity }, { description: '运行测试命令', command: '   ' }]) {
+      const result = await tool.execute({ ...SESSION_CTX, canConsumeBackgroundBashOutput: true }, { ...input, run_in_background: background });
+      expect(result).toMatchObject({ isError: true, details: { error_code: 'BASH_INVALID_INPUT' } });
+    }
+    expect(startBackground).not.toHaveBeenCalled();
+    expect(runManagedForeground).not.toHaveBeenCalled();
+  });
+
+  it('reports a capped foreground timeout while preserving the command text', async () => {
+    const tool = new LocalBashTool('/tmp/workspace', undefined, { mode: 'off' });
+    const execute = vi.spyOn((tool as unknown as { tool: { execute: unknown } }).tool, 'execute')
+      .mockResolvedValue({ content: [{ type: 'text', text: 'ok' }], details: {} } as never);
+    const result = await tool.execute(SESSION_CTX, { description: '运行测试命令', command: ' echo ok ', timeout: 600 });
+    expect(execute.mock.calls[0]?.[1]).toEqual({ description: '运行测试命令', command: ' echo ok ', timeout: 300 });
+    expect(result.details).toMatchObject({ timing: { requestedTimeoutSeconds: 600, commandTimeoutSeconds: 300 } });
+    expect(result.text).toContain('requested 600s; effective 300s');
+  });
+});
+
+describe('LocalBashTool.execute — background path', () => {
+  // TS-3 (P0): run_in_background:true (no timeout) → 120 default NOT applied;
+  // dispatches to the background adapter with the input untouched.
+  it('dispatches to the background adapter without injecting the 120s default', async () => {
+    const started: LocalBashBackgroundStartResult = {
+      status: 'started',
+      taskId: 'task-1',
+      details: { envSanitized: ['MAVIS_ACCESS_TOKEN'] },
+    };
+    const startBackground = vi.fn(
+      async (): Promise<LocalBashBackgroundStartResult> => started,
+    );
+    const adapter: LocalBashAdapter = { startBackground };
+    const tool = new LocalBashTool('/tmp/does-not-matter', adapter, { mode: 'off' });
+
+    const result = await tool.execute({ ...SESSION_CTX, canConsumeBackgroundBashOutput: true }, {
+      description: '运行测试命令',
+      command: 'echo hi',
+      run_in_background: true,
+    });
+
+    expect(startBackground).toHaveBeenCalledTimes(1);
+    const forwarded = startBackground.mock.calls[0]?.[1];
+    // Background path must receive the input verbatim — no 120 injected.
+    expect(forwarded).toEqual({ description: '运行测试命令', command: 'echo hi', run_in_background: true });
+    expect((forwarded as { timeout?: number }).timeout).toBeUndefined();
+    expect(result.details).toMatchObject({
+      status: 'started',
+      task_id: 'task-1',
+      envSanitized: ['MAVIS_ACCESS_TOKEN'],
+    });
+  });
+});
+
+describe('LocalBashTool.execute — foreground path forwarding (TS-4)', () => {
+  // TS-4 (P1): forwarded foreground input carries resolved timeout and NO
+  // run_in_background key. We spy on the inner pi tool to capture the forward.
+  it('forwards resolved timeout and strips run_in_background', async () => {
+    const tool = new LocalBashTool('/tmp/does-not-matter', undefined, { mode: 'off' });
+    const innerExecute = vi
+      .spyOn((tool as unknown as { tool: { execute: unknown } }).tool, 'execute')
+      .mockResolvedValue({ content: [{ type: 'text', text: 'ok' }], details: {} } as never);
+
+    await tool.execute(SESSION_CTX, { description: '运行测试命令', command: 'echo hi', run_in_background: false });
+
+    expect(innerExecute).toHaveBeenCalledTimes(1);
+    const forwarded = (innerExecute.mock.calls[0] as unknown[])[1] as Record<string, unknown>;
+    expect(forwarded).toEqual({ description: '运行测试命令', command: 'echo hi', timeout: 120 });
+    expect(forwarded).not.toHaveProperty('run_in_background');
+  });
+
+  it('forwards an explicit timeout unchanged and strips run_in_background', async () => {
+    const tool = new LocalBashTool('/tmp/does-not-matter', undefined, { mode: 'off' });
+    const innerExecute = vi
+      .spyOn((tool as unknown as { tool: { execute: unknown } }).tool, 'execute')
+      .mockResolvedValue({ content: [{ type: 'text', text: 'ok' }], details: {} } as never);
+
+    await tool.execute(SESSION_CTX, { description: '运行测试命令', command: 'echo hi', timeout: 7 });
+
+    const forwarded = (innerExecute.mock.calls[0] as unknown[])[1] as Record<string, unknown>;
+    expect(forwarded).toEqual({ description: '运行测试命令', command: 'echo hi', timeout: 7 });
+    expect(forwarded).not.toHaveProperty('run_in_background');
+  });
+
+  it('carries the trusted Explore read-only restriction through direct foreground identity', async () => {
+    const create = vi.fn<LocalSandboxBashOperationsFactory['create']>(() => ({
+      exec: async () => ({ exitCode: 0 }),
+    }));
+    const tool = new LocalBashTool(
+      '/tmp/does-not-matter',
+      undefined,
+      { mode: 'off' },
+      undefined,
+      { create },
+    );
+    const ctx = {
+      ...SESSION_CTX,
+      toolCallId: 'call-direct',
+      forceReadOnlyFilesystem: true,
+    };
+
+    await tool.execute(ctx, { description: '运行测试命令', command: 'true' });
+
+    expect(create).toHaveBeenCalledWith({
+      identity: {
+        operationClass: 'direct_foreground',
+        invocationId: 'call-direct',
+        sessionId: 'sess-test',
+        turnId: 'turn-test',
+        toolCallId: 'call-direct',
+        forceReadOnlyFilesystem: true,
+      },
+      workspaceRoot: '/tmp/does-not-matter',
+    });
+  });
+
+  it('uses a unique runtime id without leaking command text when old callers omit toolCallId', async () => {
+    const create = vi.fn<LocalSandboxBashOperationsFactory['create']>(() => ({
+      exec: async () => ({ exitCode: 0 }),
+    }));
+    const tool = new LocalBashTool(
+      '/tmp/does-not-matter',
+      undefined,
+      { mode: 'off' },
+      undefined,
+      { create },
+    );
+
+    await tool.execute(SESSION_CTX, { description: '运行测试命令', command: 'secret-command-one' });
+    await tool.execute(SESSION_CTX, { description: '运行测试命令', command: 'secret-command-two' });
+
+    const identities = create.mock.calls.map(([input]) => input.identity);
+    expect(identities).toHaveLength(2);
+    expect(identities[0]).toMatchObject({
+      operationClass: 'direct_foreground',
+      sessionId: 'sess-test',
+      turnId: 'turn-test',
+    });
+    expect(identities[0]?.invocationId).toMatch(/^runtime_[0-9a-f-]{36}$/);
+    expect(identities[1]?.invocationId).not.toBe(identities[0]?.invocationId);
+    expect(JSON.stringify(identities)).not.toContain('secret-command');
+  });
+});
+
+describe('LocalBashTool.execute — managed foreground soft yield', () => {
+  it.each([0, 7])('returns direct output and exit code %i when native output is absent', async (exitCode) => {
+    const runManagedForeground = vi.fn();
+    const tool = new LocalBashTool('/tmp/workspace', { startBackground: vi.fn(), runManagedForeground }, { mode: 'off' }, undefined, {
+      create: () => ({ exec: async (_command, _cwd, opts) => {
+        opts.onData(Buffer.from('direct stdout and stderr'));
+        return { exitCode };
+      } }),
+    });
+    const result = await tool.execute({ ...SESSION_CTX, allowBashAutoPromotion: true }, { description: '运行测试命令', command: 'controlled command' });
+    expect(runManagedForeground).not.toHaveBeenCalled();
+    expect(result.text).toContain('direct stdout and stderr');
+    expect(Boolean(result.isError)).toBe(exitCode !== 0);
+    expect(result.details?.task_id).toBeUndefined();
+  });
+
+  it('forwards cancellation to foreground operations when promotion is disabled', async () => {
+    const controller = new AbortController();
+    let started!: () => void;
+    const ready = new Promise<void>((resolve) => { started = resolve; });
+    const runManagedForeground = vi.fn();
+    const tool = new LocalBashTool('/tmp/workspace', { startBackground: vi.fn(), runManagedForeground }, { mode: 'off' }, undefined, {
+      create: () => ({ exec: async (_command, _cwd, opts) => {
+        expect(opts.signal).toBe(controller.signal);
+        return new Promise<never>((_, reject) => {
+          opts.signal?.addEventListener('abort', () => reject(new Error('aborted')), { once: true });
+          started();
+        });
+      } }),
+    });
+    const pending = tool.execute({ ...SESSION_CTX, allowBashAutoPromotion: false }, { description: '运行测试命令', command: 'controlled command' }, controller.signal);
+    const rejection = expect(pending).rejects.toThrow(/abort/i);
+    await ready;
+    controller.abort();
+    await rejection;
+    expect(runManagedForeground).not.toHaveBeenCalled();
+  });
+
+  it('refuses explicit background Bash before starting a task when native output is unavailable', async () => {
+    const startBackground = vi.fn(async () => ({ status: 'started' as const, taskId: 'unexpected' }));
+    const tool = new LocalBashTool(
+      '/tmp/workspace',
+      { startBackground, runManagedForeground: vi.fn() },
+      { mode: 'off' },
+    );
+
+    const result = await tool.execute(
+      { ...SESSION_CTX, canConsumeBackgroundBashOutput: false },
+      { description: '运行测试命令', command: 'controlled command', run_in_background: true },
+    );
+
+    expect(result).toMatchObject({
+      isError: true,
+      details: {
+        status: 'background_output_unavailable',
+        error_code: 'BASH_BACKGROUND_OUTPUT_UNAVAILABLE',
+      },
+    });
+    expect(result.text).toContain('missing task_output');
+    expect(result.text).toContain('foreground instead');
+    expect(startBackground).not.toHaveBeenCalled();
+  });
+
+  it('allows explicit background execution when native output is admitted', async () => {
+    const startBackground = vi.fn(async () => ({ status: 'started' as const, taskId: 'explicit-task' }));
+    const tool = new LocalBashTool('/tmp/workspace', { startBackground, runManagedForeground: vi.fn() }, { mode: 'off' });
+    const result = await tool.execute(
+      {
+        ...SESSION_CTX,
+        allowBashAutoPromotion: false,
+        canConsumeBackgroundBashOutput: true,
+      },
+      { description: '运行测试命令', command: 'controlled command', run_in_background: true },
+    );
+    expect(startBackground).toHaveBeenCalledOnce();
+    expect(result.details).toMatchObject({ status: 'started', task_id: 'explicit-task' });
+  });
+
+  it('fails closed for explicit background execution when the catalog fact is absent', async () => {
+    const startBackground = vi.fn(async () => ({ status: 'started' as const, taskId: 'explicit-task' }));
+    const tool = new LocalBashTool('/tmp/workspace', { startBackground, runManagedForeground: vi.fn() }, { mode: 'off' });
+    const result = await tool.execute(
+      { ...SESSION_CTX, allowBashAutoPromotion: false },
+      { description: '运行测试命令', command: 'controlled command', run_in_background: true },
+    );
+
+    expect(result).toMatchObject({
+      isError: true,
+      details: {
+        status: 'background_output_unavailable',
+        error_code: 'BASH_BACKGROUND_OUTPUT_UNAVAILABLE',
+      },
+    });
+    expect(startBackground).not.toHaveBeenCalled();
+  });
+
+  it('returns a completed managed command inline', async () => {
+    const runManagedForeground = vi.fn(async () => ({
+      status: 'completed' as const,
+      taskId: 'task-fast',
+      text: 'ok',
+    }));
+    const tool = new LocalBashTool('/tmp/does-not-matter', {
+      startBackground: vi.fn(),
+      runManagedForeground,
+    }, { mode: 'off' });
+
+    const result = await tool.execute({ ...SESSION_CTX, canConsumeBackgroundBashOutput: true }, { description: '运行测试命令', command: 'echo ok' });
+
+    expect(runManagedForeground).toHaveBeenCalledWith(
+      { ...SESSION_CTX, canConsumeBackgroundBashOutput: true },
+      { description: '运行测试命令', command: 'echo ok' },
+      DEFAULT_FOREGROUND_BASH_SOFT_YIELD_MS,
+      undefined,
+    );
+    expect(result).toMatchObject({ text: 'ok', details: { status: 'completed', task_id: 'task-fast' } });
+  });
+
+  it('reports managed env sanitization once per tool instance', async () => {
+    const runManagedForeground = vi.fn(async () => ({
+      status: 'completed' as const,
+      taskId: 'task-fast',
+      text: 'ok',
+      details: { envSanitized: ['MAVIS_ACCESS_TOKEN'] },
+    }));
+    const tool = new LocalBashTool('/tmp/does-not-matter', {
+      startBackground: vi.fn(),
+      runManagedForeground,
+    }, { mode: 'off' });
+
+    const first = await tool.execute({ ...SESSION_CTX, canConsumeBackgroundBashOutput: true }, { description: '运行测试命令', command: 'echo first' });
+    const second = await tool.execute({ ...SESSION_CTX, canConsumeBackgroundBashOutput: true }, { description: '运行测试命令', command: 'echo second' });
+
+    expect(first.details?.envSanitized).toEqual(['MAVIS_ACCESS_TOKEN']);
+    expect(second.details?.envSanitized).toBeUndefined();
+  });
+
+  it('returns the same task handle when a slow command is auto-promoted', async () => {
+    const tool = new LocalBashTool('/tmp/does-not-matter', {
+      startBackground: vi.fn(),
+      runManagedForeground: vi.fn(async () => ({
+        status: 'auto_promoted' as const,
+        taskId: 'task-slow',
+        details: { envSanitized: ['MAVIS_ACCESS_TOKEN'] },
+      })),
+    }, { mode: 'off' });
+
+    const result = await tool.execute({ ...SESSION_CTX, canConsumeBackgroundBashOutput: true }, { description: '运行测试命令', command: 'sleep 30' });
+
+    expect(result.details).toEqual({
+      description: '运行测试命令',
+      status: 'auto_promoted',
+      task_id: 'task-slow',
+      timing: {
+        commandTimeoutSeconds: 600,
+      },
+      envSanitized: ['MAVIS_ACCESS_TOKEN'],
+    });
+    expect(result.text).toContain('without restarting it');
+    expect(result.text).toContain('Command limit: 600s total; yielding does not reset it.');
+  });
+});
+
+describe('LocalBashTool.execute — real foreground ops', () => {
+  let workspace: string;
+
+  beforeEach(async () => {
+    workspace = await mkdtemp(join(tmpdir(), 'local-bash-'));
+  });
+  afterEach(async () => {
+    await rm(workspace, { recursive: true, force: true });
+  });
+
+  it('returns real output after the 60 second yield window when the Turn has no native task_output', async () => {
+    const runManagedForeground = vi.fn(async () => ({ status: 'auto_promoted' as const, taskId: 'unexpected-task' }));
+    const tool = new LocalBashTool(workspace, { startBackground: vi.fn(), runManagedForeground }, { mode: 'off' });
+    const startedAt = Date.now();
+    const result = await tool.execute({ ...SESSION_CTX, allowBashAutoPromotion: false }, {
+      description: '运行测试命令',
+      command: `node -e "setTimeout(() => { console.log('foreground-after-threshold'); console.error('stderr-after-threshold'); }, 61000)"`,
+      timeout: 90,
+    });
+    expect(Date.now() - startedAt).toBeGreaterThanOrEqual(60_000);
+    expect(runManagedForeground).not.toHaveBeenCalled();
+    expect(result.text).toContain('foreground-after-threshold');
+    expect(result.text).toContain('stderr-after-threshold');
+    expect(result.isError).toBeFalsy();
+    expect(result.details?.task_id).toBeUndefined();
+  }, 90_000);
+
+  // TS-5 (P1): fast foreground command with no timeout completes normally.
+  it('runs a fast foreground command with no timeout and returns real output', async () => {
+    const tool = new LocalBashTool(workspace, undefined, { mode: 'off' });
+    const result = await tool.execute(SESSION_CTX, { description: '运行测试命令', command: 'echo hi' });
+    expect(result.tool_name).toBe('bash');
+    expect(result.text).toContain('hi');
+    expect(result.isError).toBeFalsy();
+  });
+
+  // TS-6 (P1): timeout-hit surfaces the vendored error text. Driven with a very
+  // short explicit timeout against a sleep to stay fast and non-flaky.
+  it('surfaces the vendored "Command timed out after N seconds" text', async () => {
+    const tool = new LocalBashTool(workspace, undefined, { mode: 'off' });
+    const result = await tool.execute(SESSION_CTX, { description: '运行测试命令', command: 'sleep 5', timeout: 1 });
+    expect(result.isError).toBe(true);
+    expect(result.text).toMatch(/Command timed out after 1 seconds/);
+  });
+});
+
+describe('LocalBashToolDef timeout description (TS-7)', () => {
+  it('documents seconds, foreground limits, and background yielding', () => {
+    const desc = timeoutDescription();
+    expect(desc).not.toContain('host-defined');
+    expect(desc).toContain('seconds');
+    expect(desc).toContain('120');
+    expect(desc).toContain('300');
+    expect(desc).toContain('600');
+    expect(desc).toContain('including foreground time');
+    expect(desc.toLowerCase()).toContain('foreground');
+    const backgroundDesc = createLocalBashToolDefinition({ background: true, shell: 'bash' }).description;
+    expect(backgroundDesc).toContain('return a task_id if unfinished');
+    expect(backgroundDesc).toContain('60s');
+  });
+
+});
+
+describe('per-Turn Bash contract', () => {
+  it('keeps definitions isolated while hiding background parameters without native output', () => {
+    const original = JSON.stringify(LocalBashToolDef);
+    const enabled = createLocalBashToolDefinition({ background: true, shell: 'bash' });
+    const disabled = createLocalBashToolDefinition({ background: false, shell: 'bash' });
+    expect(enabled.schema.properties).toHaveProperty('run_in_background');
+    expect(disabled.schema.properties).not.toHaveProperty('run_in_background');
+    expect(JSON.stringify(disabled.schema)).not.toContain('run_in_background');
+    expect(enabled.description).toContain('Backgrounding and reading output do not reset the command timeout.');
+    expect(disabled.description).toContain('foreground execution only');
+    expect(disabled.schema.required).toEqual(['command']);
+    expect(enabled.schema.properties.timeout.description).toContain('default/max 600s');
+    expect(enabled.schema.properties.timeout.description).toContain('including foreground time');
+    expect(disabled.schema.properties.timeout.description).toContain('default 120s; values above 300s are capped');
+    expect(JSON.stringify(LocalBashToolDef)).toBe(original);
+    expect(enabled.schema.properties.timeout).not.toBe(LocalBashToolDef.schema.properties.timeout);
+    expect(disabled.description).toContain('report the failure instead of falling back to permanent deletion');
+    expect(disabled.description).toContain('dedicated `read`, `write`, `edit`, `grep`, and `glob`');
+  });
+
+  it.each([
+    ['bash', 'Selected shell: Bash', 'PowerShell 5.1'],
+    ['sh', 'Selected shell: POSIX sh', 'Selected shell: Bash'],
+    ['powershell', 'The && and || operators are unsupported', 'operators && and || are supported'],
+    ['pwsh', 'operators && and || are supported', 'operators are unsupported'],
+    ['unavailable', 'No local shell was resolved', 'Selected shell: Bash'],
+  ] as const)('describes the selected %s shell capabilities', (shell, expected, excluded) => {
+    const tool = createLocalBashToolDefinition({ background: true, shell });
+    expect(tool.description).toContain(expected);
+    expect(tool.description).not.toContain(excluded);
+    expect(tool.description).toContain('Backgrounding and reading output do not reset the command timeout.');
+  });
+});
diff --git a/packages/agent-tools/test/desktop/local-task-output-polling.test.ts b/packages/agent-tools/test/desktop/local-task-output-polling.test.ts
new file mode 100644
index 00000000..83a404e8
--- /dev/null
+++ b/packages/agent-tools/test/desktop/local-task-output-polling.test.ts
@@ -0,0 +1,445 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import type { BackgroundTask } from '@mavis/background-task';
+import { PiTurnRunner } from '@mavis/agent-core/pi-turn-runner';
+import type { RuntimeTool } from '@mavis/agent-core/tools';
+import type { StreamFn } from '@earendil-works/pi-agent-core';
+import type { Api, AssistantMessage, Model } from '@earendil-works/pi-ai';
+
+import { LocalTaskOutputToolDef } from '../../src/desktop/builtin-defs.js';
+import { LocalTaskOutputTool } from '../../src/desktop/local-task-control.js';
+import type {
+  LocalRuntimeToolContext,
+  LocalTaskControlAdapter,
+  LocalTaskOutputReadResult,
+} from '../../src/desktop/types.js';
+
+const context: LocalRuntimeToolContext = { sessionId: 'owner', turnId: 'turn-1' };
+const replay = { task_id: 'bg_1', offset: 0, wait_ms: 30_000 };
+const running: LocalTaskOutputReadResult = {
+  content: 'Compiling\n',
+  status: 'running',
+  nextOffset: 312,
+  truncated: false,
+  timedOut: false,
+};
+
+function fixture() {
+  const get = vi.fn<LocalTaskControlAdapter['get']>(async (ctx, taskId) => ({
+    taskId,
+    ownerSessionId: ctx.sessionId,
+    kind: 'bash',
+    status: 'running',
+    createdAt: 1,
+    updatedAt: 1,
+  }));
+  const readOutput = vi.fn<LocalTaskControlAdapter['readOutput']>(async () => ({ ...running }));
+  const adapter: LocalTaskControlAdapter = {
+    get,
+    readOutput,
+    list: async () => ({ items: [] }),
+    stop: async () => undefined,
+  };
+  return { tool: new LocalTaskOutputTool(adapter), get, readOutput };
+}
+
+it('shows incomplete persistence even when the command itself succeeded', async () => {
+  const { tool, get, readOutput } = fixture();
+  get.mockResolvedValue({
+    taskId: 'bg_1', ownerSessionId: 'owner', kind: 'bash', status: 'succeeded', createdAt: 1, updatedAt: 2,
+    metadata: { bashDetails: { output: { persistence: 'incomplete', rawBytes: 1234 } } },
+  });
+  readOutput.mockResolvedValue({ content: 'saved portion', status: 'succeeded', nextOffset: 100 });
+  const result = await tool.execute(context, { task_id: 'bg_1' });
+  expect(result.text).toContain('Output persistence is incomplete');
+  expect(result.text).toContain('saved portion');
+  expect(result.details?.output).toMatchObject({ rawBytes: 1234 });
+});
+
+const piTestModel: Model<Api> = {
+  id: 'test-model',
+  name: 'test-model',
+  api: 'anthropic-messages',
+  provider: 'test-provider',
+  baseUrl: 'https://example.invalid',
+  reasoning: false,
+  input: ['text'],
+  cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+  contextWindow: 200_000,
+  maxTokens: 8_192,
+};
+
+function assistantMessage(
+  content: AssistantMessage['content'],
+  stopReason: AssistantMessage['stopReason'],
+): AssistantMessage {
+  return {
+    role: 'assistant',
+    content,
+    api: piTestModel.api,
+    provider: piTestModel.provider,
+    model: piTestModel.id,
+    usage: {
+      input: 1,
+      output: 1,
+      cacheRead: 0,
+      cacheWrite: 0,
+      totalTokens: 2,
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+    },
+    stopReason,
+    timestamp: 0,
+  };
+}
+
+function resultOnlyStream(message: AssistantMessage) {
+  return {
+    async *[Symbol.asyncIterator]() {
+      yield { type: 'done', reason: message.stopReason, message };
+    },
+    async result() {
+      return message;
+    },
+  } as never;
+}
+
+function piToolCallStream(
+  calls: readonly { readonly id: string; readonly arguments: Record<string, unknown> }[],
+): StreamFn {
+  let invocation = 0;
+  return (async () => {
+    const message =
+      invocation++ === 0
+        ? assistantMessage(
+            calls.map((call) => ({
+              type: 'toolCall',
+              id: call.id,
+              name: 'task_output',
+              arguments: call.arguments,
+            })),
+            'toolUse',
+          )
+        : assistantMessage([{ type: 'text', text: 'done' }], 'stop');
+    return resultOnlyStream(message);
+  }) as StreamFn;
+}
+
+it.each(['succeeded', 'failed', 'canceled', 'lost'] as const)(
+  'successfully reads output from a %s task',
+  async (status) => {
+    const { tool, get, readOutput } = fixture();
+    get.mockResolvedValue({
+      taskId: 'bg_1',
+      ownerSessionId: 'owner',
+      kind: 'bash',
+      status,
+      createdAt: 1,
+      updatedAt: 2,
+    });
+    readOutput.mockResolvedValue({ content: 'saved command output', status, nextOffset: 20 });
+    const result = await tool.execute(context, { task_id: 'bg_1' });
+    expect(result.isError).not.toBe(true);
+    expect(result.details).toMatchObject({ task_id: 'bg_1', status, next_offset: 20 });
+    expect(result.text).toContain('saved command output');
+  },
+);
+
+describe('task_output polling guidance', () => {
+  it('lets Pi validate raw task_output arguments before executing capped waits', async () => {
+    const readOutput = vi.fn<LocalTaskControlAdapter['readOutput']>(async () => ({
+      content: '',
+      status: 'running',
+      timedOut: true,
+    }));
+    const adapter: LocalTaskControlAdapter = {
+      get: async () => ({
+        taskId: 'bg_1',
+        ownerSessionId: context.sessionId,
+        kind: 'bash',
+        status: 'running',
+        createdAt: 1,
+        updatedAt: 1,
+      }),
+      readOutput,
+      list: async () => ({ items: [] }),
+      stop: async () => undefined,
+    };
+    const rawCalls = [
+      { id: 'oversized-60', arguments: { task_id: 'bg_1', wait_ms: 60_000 } },
+      { id: 'oversized-120', arguments: { task_id: 'bg_1', wait_ms: 120_000 } },
+      { id: 'oversized-300', arguments: { task_id: 'bg_1', wait_ms: 300_000 } },
+      { id: 'negative', arguments: { task_id: 'bg_1', wait_ms: -1 } },
+      { id: 'fraction', arguments: { task_id: 'bg_1', wait_ms: 0.5 } },
+      { id: 'string', arguments: { task_id: 'bg_1', wait_ms: '60000' } },
+      { id: 'null', arguments: { task_id: 'bg_1', wait_ms: null } },
+      { id: 'infinity', arguments: { task_id: 'bg_1', wait_ms: Number.POSITIVE_INFINITY } },
+      { id: 'nan', arguments: { task_id: 'bg_1', wait_ms: Number.NaN } },
+    ];
+    const history: unknown[] = [];
+    const stepResults: unknown[] = [];
+    const tool: RuntimeTool = {
+      def: LocalTaskOutputToolDef,
+      impl: new LocalTaskOutputTool(adapter),
+      source: 'builtin',
+    };
+
+    await new PiTurnRunner().runTurn({
+      sessionId: context.sessionId,
+      turnId: context.turnId,
+      workspaceDir: '/workspace',
+      systemPrompt: '',
+      userMessage: { text: 'read task output' },
+      llm: { model: piTestModel, streamFn: piToolCallStream(rawCalls) },
+      eventWriter: { pushRuntime: () => undefined, appendEvents: () => undefined },
+      toolConfig: { tools: [tool], disableBuiltinToolFallback: true, context },
+      hooks: {
+        onStepEndHook: [
+          ({ toolResults }) => {
+            stepResults.push(...structuredClone(toolResults));
+          },
+        ],
+        onHistoryChangedHook: [
+          ({ reason, messages }) => {
+            if (reason === 'messageDelta') history.push(...structuredClone(messages));
+          },
+        ],
+      },
+    });
+
+    expect(readOutput).toHaveBeenCalledTimes(3);
+    for (const [, , options] of readOutput.mock.calls) {
+      expect(options).toMatchObject({ waitMs: 30_000 });
+    }
+    const invalidCallIds = new Set(rawCalls.slice(3).map((call) => call.id));
+    const invalidResults = (
+      stepResults as Array<{
+        readonly toolCallId: string;
+        readonly isError: boolean;
+      }>
+    ).filter((result) => invalidCallIds.has(result.toolCallId));
+    expect(invalidResults).toHaveLength(invalidCallIds.size);
+    expect(invalidResults.every((result) => result.isError)).toBe(true);
+    const assistant = history.find(
+      (message): message is { readonly role: 'assistant'; readonly content: readonly unknown[] } =>
+        typeof message === 'object' &&
+        message !== null &&
+        (message as { role?: unknown }).role === 'assistant',
+    );
+    expect(assistant?.content).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          id: 'oversized-60',
+          arguments: { task_id: 'bg_1', wait_ms: 60_000 },
+        }),
+        expect.objectContaining({
+          id: 'oversized-120',
+          arguments: { task_id: 'bg_1', wait_ms: 120_000 },
+        }),
+        expect.objectContaining({
+          id: 'oversized-300',
+          arguments: { task_id: 'bg_1', wait_ms: 300_000 },
+        }),
+      ]),
+    );
+  });
+
+  it('corrects repeated offset=0 reads with the returned cursor without changing replay semantics', async () => {
+    const { tool, readOutput } = fixture();
+    const first = await tool.execute(context, replay);
+    const repeated = await tool.execute(context, replay);
+
+    expect(first.text).not.toContain('<task_output_hint>');
+    expect(repeated.text).toContain('Task status and next_offset are unchanged');
+    expect(repeated.text).toContain('task_output({"task_id":"bg_1","offset":312,"wait_ms":30000})');
+    expect(repeated.text).toContain('offset=0 replays existing output');
+    expect(repeated.text).toContain(running.content);
+    expect(repeated.details).toEqual(first.details);
+    expect(repeated.content).toEqual([{ type: 'text', text: repeated.text }]);
+    expect(readOutput.mock.calls.map(([, , options]) => options)).toEqual([
+      { offset: 0, waitMs: 30_000 },
+      { offset: 0, waitMs: 30_000 },
+    ]);
+    expect(replay.offset).toBe(0);
+  });
+
+  it.each([undefined, 0])('corrects unchanged empty reads with wait_ms=%s', async (waitMs) => {
+    const { tool, readOutput } = fixture();
+    readOutput.mockResolvedValue({ content: '', nextOffset: 312, status: 'running' });
+    const input = { task_id: 'bg_1', offset: 312, ...(waitMs === undefined ? {} : { wait_ms: waitMs }) };
+    await tool.execute(context, input);
+    const repeated = await tool.execute(context, input);
+
+    expect(repeated.text).toContain('"offset":312,"wait_ms":30000');
+    expect(repeated.text).toContain('(no output yet)');
+    expect(readOutput).toHaveBeenLastCalledWith(context, 'bg_1', {
+      offset: 312,
+      waitMs: waitMs ?? 0,
+    });
+  });
+
+  it('preserves automatic cursor reads while providing an explicit recovery call', async () => {
+    const { tool, readOutput } = fixture();
+    readOutput.mockResolvedValue({ content: '', nextOffset: 312, status: 'running' });
+    await tool.execute(context, { task_id: 'bg_1' });
+    const repeated = await tool.execute(context, { task_id: 'bg_1' });
+
+    expect(repeated.text).toContain('"offset":312,"wait_ms":30000');
+    expect(readOutput).toHaveBeenLastCalledWith(context, 'bg_1', { waitMs: 0 });
+    expect(repeated.details).toMatchObject({ effective_wait_ms: 0, wait_ms_clamped: false });
+  });
+
+  it.each([30_001, 60_000, 300_000])(
+    'caps oversized wait_ms=%s while preserving the requested value for diagnostics',
+    async (waitMs) => {
+      const { tool, readOutput } = fixture();
+      readOutput.mockResolvedValue({ ...running, content: '', timedOut: true });
+      const input = { task_id: 'bg_1', offset: 312, wait_ms: waitMs };
+
+      const result = await tool.execute(context, input);
+
+      expect(input.wait_ms).toBe(waitMs);
+      expect(readOutput).toHaveBeenCalledWith(context, 'bg_1', { offset: 312, waitMs: 30_000 });
+      expect(result.text).toContain(
+        '<task_output_hint>Your requested wait_ms exceeded 30000 ms and was capped at 30000 ms (30 seconds). This output read reached its wait limit; the background task was not stopped. Use wait_ms=30000 or less for future reads.</task_output_hint>',
+      );
+      expect(result.details).toMatchObject({
+        effective_wait_ms: 30_000,
+        wait_ms_clamped: true,
+        timed_out: true,
+      });
+    },
+  );
+
+  it.each([
+    { read: { ...running, timedOut: true }, waitMs: 30_000 },
+    { read: { ...running, timedOut: false }, waitMs: 60_000 },
+    { read: { ...running, status: 'succeeded' as const, timedOut: false }, waitMs: 60_000 },
+  ])(
+    'does not describe a cap timeout when the read returns early: %j',
+    async ({ read, waitMs }) => {
+      const { tool, readOutput } = fixture();
+      readOutput.mockResolvedValue(read);
+
+      const result = await tool.execute(context, { task_id: 'bg_1', wait_ms: waitMs });
+
+      expect(result.text).not.toContain('Your requested wait_ms exceeded 30000 ms');
+      expect(result.details).toMatchObject({
+        effective_wait_ms: waitMs > 30_000 ? 30_000 : waitMs,
+        wait_ms_clamped: waitMs > 30_000,
+      });
+    },
+  );
+
+  it('does not describe a capped wait as timed out after cancellation', async () => {
+    const { tool, readOutput } = fixture();
+    const controller = new AbortController();
+    controller.abort();
+    readOutput.mockResolvedValue({ ...running, content: '', timedOut: true });
+
+    const result = await tool.execute(
+      context,
+      { task_id: 'bg_1', wait_ms: 60_000 },
+      controller.signal,
+    );
+
+    expect(result.text).not.toContain('Your requested wait_ms exceeded 30000 ms');
+    expect(result.details).toMatchObject({ effective_wait_ms: 30_000, wait_ms_clamped: true });
+  });
+
+  it('does not warn on a normal long-poll timeout but still detects the following immediate check', async () => {
+    const { tool, readOutput } = fixture();
+    readOutput.mockResolvedValue({ ...running, content: '', timedOut: true });
+    await tool.execute(context, { ...replay, offset: 312 });
+    const timeout = await tool.execute(context, { ...replay, offset: 312 });
+    expect(timeout.text).not.toContain('<task_output_hint>');
+    expect(timeout.details).toMatchObject({ timed_out: true, next_offset: 312 });
+
+    readOutput.mockResolvedValue({ ...running, content: '', timedOut: undefined });
+    const immediate = await tool.execute(context, { task_id: 'bg_1', offset: 312 });
+    expect(immediate.text).toContain('<task_output_hint>');
+  });
+
+  it('resets the comparison when output advances or task status changes', async () => {
+    const { tool, readOutput } = fixture();
+    await tool.execute(context, replay);
+    readOutput.mockResolvedValue({ ...running, nextOffset: 344 });
+    expect((await tool.execute(context, replay)).text).not.toContain('<task_output_hint>');
+    readOutput.mockResolvedValue({ ...running, nextOffset: 344, status: 'stopping' });
+    expect((await tool.execute(context, replay)).text).not.toContain('<task_output_hint>');
+    expect((await tool.execute(context, replay)).text).toContain('"offset":344');
+  });
+
+  it.each<BackgroundTask['status']>(['succeeded', 'failed', 'canceled', 'lost'])(
+    'does not recommend waiting on a %s task and forgets the previous active read',
+    async (status) => {
+      const { tool, readOutput } = fixture();
+      await tool.execute(context, replay);
+      readOutput.mockResolvedValue({ ...running, status });
+      expect((await tool.execute(context, replay)).text).not.toContain('<task_output_hint>');
+      expect((await tool.execute(context, replay)).text).not.toContain('<task_output_hint>');
+      readOutput.mockResolvedValue(running);
+      expect((await tool.execute(context, replay)).text).not.toContain('<task_output_hint>');
+    },
+  );
+
+  it.each([
+    { ctx: { ...context, sessionId: 'other-owner' }, input: replay },
+    { ctx: { ...context, turnId: 'turn-2' }, input: replay },
+    { ctx: context, input: { ...replay, task_id: 'bg_2' } },
+  ])('only compares consecutive reads of the same session, Turn and task: %j', async ({ ctx, input }) => {
+    const { tool } = fixture();
+    await tool.execute(context, replay);
+    expect((await tool.execute(ctx, input)).text).not.toContain('<task_output_hint>');
+    expect((await tool.execute(context, replay)).text).not.toContain('<task_output_hint>');
+    expect((await tool.execute(context, replay)).text).toContain('<task_output_hint>');
+  });
+
+  it.each([undefined, -1, 0.5, Number.NaN, Number.POSITIVE_INFINITY])(
+    'never invents continuation arguments for an invalid cursor %s',
+    async (nextOffset) => {
+      const { tool, readOutput } = fixture();
+      await tool.execute(context, replay);
+      readOutput.mockResolvedValue({ ...running, nextOffset });
+      await tool.execute(context, replay);
+      expect((await tool.execute(context, replay)).text).not.toContain('<task_output_hint>');
+      readOutput.mockResolvedValue(running);
+      expect((await tool.execute(context, replay)).text).not.toContain('<task_output_hint>');
+    },
+  );
+
+  it('clears the comparison on task-not-found without turning it into polling advice', async () => {
+    const { tool, get } = fixture();
+    await tool.execute(context, replay);
+    get.mockResolvedValueOnce(undefined);
+    const missing = await tool.execute(context, replay);
+    expect(missing.isError).toBe(true);
+    expect(missing.details).toMatchObject({ effective_wait_ms: 30_000, wait_ms_clamped: false });
+    expect(missing.text).not.toContain('<task_output_hint>');
+    expect((await tool.execute(context, replay)).text).not.toContain('<task_output_hint>');
+  });
+
+  it('does not learn a failed or canceled read and forwards cancellation unchanged', async () => {
+    const { tool, readOutput } = fixture();
+    readOutput.mockRejectedValueOnce(new Error('read failed'));
+    await expect(tool.execute(context, replay)).rejects.toThrow('read failed');
+    const controller = new AbortController();
+    controller.abort();
+    const canceled = await tool.execute(context, replay, controller.signal);
+    expect(canceled.text).not.toContain('<task_output_hint>');
+    expect(readOutput).toHaveBeenLastCalledWith(context, 'bg_1', {
+      offset: 0, waitMs: 30_000, signal: controller.signal,
+    });
+    expect((await tool.execute(context, replay)).text).not.toContain('<task_output_hint>');
+    expect((await tool.execute(context, replay)).text).toContain('<task_output_hint>');
+  });
+
+  it('preserves truncated replay output and points to the next page without claiming the task is finished', async () => {
+    const { tool, readOutput } = fixture();
+    readOutput.mockResolvedValue({ ...running, truncated: true });
+    await tool.execute(context, replay);
+    const repeated = await tool.execute(context, replay);
+    expect(repeated.text).toContain(running.content);
+    expect(repeated.text).toContain('"offset":312');
+    expect(repeated.details).toMatchObject({ truncated: true, status: 'running', next_offset: 312 });
+  });
+});
diff --git a/packages/local-runtime-v2/assets/agents/_default/prompt-base-all.md.hbs b/packages/local-runtime-v2/assets/agents/_default/prompt-base-all.md.hbs
index 37ed2a9e..b3adedcd 100644
--- a/packages/local-runtime-v2/assets/agents/_default/prompt-base-all.md.hbs
+++ b/packages/local-runtime-v2/assets/agents/_default/prompt-base-all.md.hbs
@@ -192,12 +192,7 @@ When the user's latest message contains the exact phrase `Prompt 灰度验证`,
 ### Non-interactive shell
 
 - Your shell is **non-interactive** — no TTY, no stdin, no prompt. Commands that wait for stdin
-  or require a terminal UI will hang forever.
-
-### Bash timeout
-
-- Bash `timeout` is measured in seconds. Foreground commands default to 120s, are capped at 300s, and yield to the same managed background process after 15s so the turn is not blocked. Start builds, tests, installs, downloads, servers, or diagnostics expected to take longer as background tasks up front; inspect their incremental output with the task tools.
-  Do not use excessively large timeouts to mask hung commands, and do not rerun a command after it yields—the returned task is the original process.
+  or require a terminal UI may fail or wait until the command timeout. Use non-interactive flags.
 
 ```bash
 # BAD — interactive commands hang
diff --git a/packages/local-runtime-v2/assets/agents/_default/prompt-base-windows.md b/packages/local-runtime-v2/assets/agents/_default/prompt-base-windows.md
index 79c46841..6e4bb0d8 100644
--- a/packages/local-runtime-v2/assets/agents/_default/prompt-base-windows.md
+++ b/packages/local-runtime-v2/assets/agents/_default/prompt-base-windows.md
@@ -1,45 +1,6 @@
 ## Windows Shell Constraints
 
-### PowerShell only
-
-- Use **PowerShell syntax only**. Do NOT use legacy DOS / `cmd.exe` commands (`cmd`, `cmd /c`,
-  `dir`, `type`, `copy`, `move`, `del`, `erase`, `rd`, `rmdir`, etc.). Use full PowerShell
-  cmdlets instead (`Get-ChildItem`, `Copy-Item`, `Move-Item`, `New-Item`).
-- The bash tool already runs the command through the selected Windows shell. Do not wrap ordinary
-  bash-tool commands in `powershell -Command`. If you truly must launch a nested `pwsh`/PowerShell
-  process, prefer `pwsh -NoProfile -NonInteractive -Command '<script>'` and keep the outer
-  `-Command` payload single-quoted so `$variables` are not expanded by the parent PowerShell.
-- For deletion, do not use shell delete commands; use the Trash tool or move files to a backup
-  location.
-- For multi-statement PowerShell scripts, start with `$ErrorActionPreference = 'Stop'`. When the
-  script runs native programs and must fail on non-zero exit codes, set
-  `$PSNativeCommandUseErrorActionPreference = $true` when available, or check `$LASTEXITCODE`
-  explicitly after the native command.
-- Do NOT use Bash-style `\"` to escape double quotes inside PowerShell strings. Use PowerShell
-  quoting rules: single quotes for literal text, doubled single quotes inside single-quoted strings,
-  double quotes only when interpolation is intended, and the backtick only for PowerShell escapes.
-- Wrap regex/search patterns in single quotes, especially for `rg` / `Select-String` patterns
-  containing `|`, `(`, `)`, `\`, `$`, or other PowerShell metacharacters. Prefer the dedicated
-  grep tool for repository searches; when shell search is necessary, keep the command simple and
-  split complex pipelines into separate tool calls.
-
-### File content operations — encoding safety
-
-- **Prefer the Read / Write / Edit tools for focused file reads and edits** — they operate directly
-  in UTF-8 and bypass shell encoding issues entirely. This is the default approach for ordinary
-  file content work; use the batch-edit exception below when dedicated tools are not efficient.
-- **Do NOT use `Get-Content | … | Set-Content` pipelines to modify file contents.** Windows
-  PowerShell 5.1 defaults to the system ANSI code page (e.g. GBK / CP936 on Chinese Windows).
-  Without `-Encoding UTF8`, `Get-Content` silently mis-decodes UTF-8 multi-byte characters as
-  ANSI, and `Set-Content` writes the corrupted data back — destroying CJK comments, strings,
-  and even line structure in source files. The corruption is **silent** (no error, no warning).
-- If you must use `Get-Content` or `Set-Content` in a shell command (e.g. reading a small config
-  value), **always** pass `-Encoding UTF8`. Be aware that PowerShell 5.1's `-Encoding UTF8`
-  adds a BOM (`EF BB BF`), which may affect some tools.
-- For batch file modifications that dedicated tools cannot express efficiently, generate a
-  **Python script** (with `encoding='utf-8'`) instead of a PowerShell pipeline.
-
-### Deliverable verification
-
-- To verify that a local deliverable exists before sending it, use
-  `Test-Path -Path <path> -PathType Leaf` or read the file back.
+- Use the shell identified by the current Bash tool and follow its syntax and encoding guidance.
+- The tool already launches the selected shell. Use non-interactive CLI flags and avoid redundant `powershell -Command` or `cmd /c` wrappers.
+- Prefer dedicated `read`, `write`, `edit`, `grep`, and `glob` tools. For unavoidable shell file I/O, follow the selected shell's UTF-8 guidance; PowerShell 5.1 `-Encoding UTF8` writes a BOM. Avoid `Get-Content | ... | Set-Content` editing pipelines.
+- Recoverable deletion uses one top-level `rm -- "<target1>" "<target2>"`; Runtime routes it through the trusted launcher. If it fails, report the failure. Never bypass it with permanent deletion or another script. Permission checks still apply.
diff --git a/packages/local-runtime-v2/assets/agents/_default/prompt-base-windows.md.hbs b/packages/local-runtime-v2/assets/agents/_default/prompt-base-windows.md.hbs
index 79c46841..6e4bb0d8 100644
--- a/packages/local-runtime-v2/assets/agents/_default/prompt-base-windows.md.hbs
+++ b/packages/local-runtime-v2/assets/agents/_default/prompt-base-windows.md.hbs
@@ -1,45 +1,6 @@
 ## Windows Shell Constraints
 
-### PowerShell only
-
-- Use **PowerShell syntax only**. Do NOT use legacy DOS / `cmd.exe` commands (`cmd`, `cmd /c`,
-  `dir`, `type`, `copy`, `move`, `del`, `erase`, `rd`, `rmdir`, etc.). Use full PowerShell
-  cmdlets instead (`Get-ChildItem`, `Copy-Item`, `Move-Item`, `New-Item`).
-- The bash tool already runs the command through the selected Windows shell. Do not wrap ordinary
-  bash-tool commands in `powershell -Command`. If you truly must launch a nested `pwsh`/PowerShell
-  process, prefer `pwsh -NoProfile -NonInteractive -Command '<script>'` and keep the outer
-  `-Command` payload single-quoted so `$variables` are not expanded by the parent PowerShell.
-- For deletion, do not use shell delete commands; use the Trash tool or move files to a backup
-  location.
-- For multi-statement PowerShell scripts, start with `$ErrorActionPreference = 'Stop'`. When the
-  script runs native programs and must fail on non-zero exit codes, set
-  `$PSNativeCommandUseErrorActionPreference = $true` when available, or check `$LASTEXITCODE`
-  explicitly after the native command.
-- Do NOT use Bash-style `\"` to escape double quotes inside PowerShell strings. Use PowerShell
-  quoting rules: single quotes for literal text, doubled single quotes inside single-quoted strings,
-  double quotes only when interpolation is intended, and the backtick only for PowerShell escapes.
-- Wrap regex/search patterns in single quotes, especially for `rg` / `Select-String` patterns
-  containing `|`, `(`, `)`, `\`, `$`, or other PowerShell metacharacters. Prefer the dedicated
-  grep tool for repository searches; when shell search is necessary, keep the command simple and
-  split complex pipelines into separate tool calls.
-
-### File content operations — encoding safety
-
-- **Prefer the Read / Write / Edit tools for focused file reads and edits** — they operate directly
-  in UTF-8 and bypass shell encoding issues entirely. This is the default approach for ordinary
-  file content work; use the batch-edit exception below when dedicated tools are not efficient.
-- **Do NOT use `Get-Content | … | Set-Content` pipelines to modify file contents.** Windows
-  PowerShell 5.1 defaults to the system ANSI code page (e.g. GBK / CP936 on Chinese Windows).
-  Without `-Encoding UTF8`, `Get-Content` silently mis-decodes UTF-8 multi-byte characters as
-  ANSI, and `Set-Content` writes the corrupted data back — destroying CJK comments, strings,
-  and even line structure in source files. The corruption is **silent** (no error, no warning).
-- If you must use `Get-Content` or `Set-Content` in a shell command (e.g. reading a small config
-  value), **always** pass `-Encoding UTF8`. Be aware that PowerShell 5.1's `-Encoding UTF8`
-  adds a BOM (`EF BB BF`), which may affect some tools.
-- For batch file modifications that dedicated tools cannot express efficiently, generate a
-  **Python script** (with `encoding='utf-8'`) instead of a PowerShell pipeline.
-
-### Deliverable verification
-
-- To verify that a local deliverable exists before sending it, use
-  `Test-Path -Path <path> -PathType Leaf` or read the file back.
+- Use the shell identified by the current Bash tool and follow its syntax and encoding guidance.
+- The tool already launches the selected shell. Use non-interactive CLI flags and avoid redundant `powershell -Command` or `cmd /c` wrappers.
+- Prefer dedicated `read`, `write`, `edit`, `grep`, and `glob` tools. For unavoidable shell file I/O, follow the selected shell's UTF-8 guidance; PowerShell 5.1 `-Encoding UTF8` writes a BOM. Avoid `Get-Content | ... | Set-Content` editing pipelines.
+- Recoverable deletion uses one top-level `rm -- "<target1>" "<target2>"`; Runtime routes it through the trusted launcher. If it fails, report the failure. Never bypass it with permanent deletion or another script. Permission checks still apply.
diff --git a/packages/local-runtime-v2/src/service/background-bash/executor.test.ts b/packages/local-runtime-v2/src/service/background-bash/executor.test.ts
new file mode 100644
index 00000000..6a47c3ed
--- /dev/null
+++ b/packages/local-runtime-v2/src/service/background-bash/executor.test.ts
@@ -0,0 +1,233 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import type { BashOperations } from '@earendil-works/pi-coding-agent/tools';
+import { resolveBashEnvPolicy } from '@mavis/agent-core/bash-subprocess-env';
+import type { LocalSandboxInvocationIdentity } from '@mavis/agent-tools/desktop';
+
+import { createLocalBackgroundBashExecutor } from './executor.js';
+
+const identity: LocalSandboxInvocationIdentity = {
+  operationClass: 'managed_foreground',
+  invocationId: 'task-1',
+  sessionId: 'session-1',
+  turnId: 'turn-1',
+  toolCallId: 'tool-1',
+  taskId: 'task-1',
+};
+
+it('streams a single complete log while returning bounded original head and tail', async () => {
+  const raw = Buffer.from(`FIRST汉${'中文'.repeat(20_000)}LAST末`);
+  let persisted = '';
+  let bytes = 0;
+  const executor = createLocalBackgroundBashExecutor(
+    {
+      create: () => ({
+        separatesOutputStreams: true,
+        exec: async (_command, _cwd, options) => {
+          for (let i = 0; i < raw.length; i += 31)
+            options.onData(raw.subarray(i, i + 31), 'stdout');
+          return { exitCode: 7 };
+        },
+      }),
+    },
+    { mode: 'off' },
+  );
+  const result = await executor.execute({
+    identity,
+    workspaceRoot: process.cwd(),
+    command: 'test',
+    signal: new AbortController().signal,
+    onOutput: (text, byteLength) => {
+      persisted += text;
+      bytes += byteLength ?? 0;
+    },
+  });
+  expect(persisted).toBe(raw.toString('utf8'));
+  expect(bytes).toBe(raw.length);
+  expect(result.text).toContain('FIRST汉');
+  expect(result.text).toContain('LAST末');
+  expect(result.text).not.toContain('�');
+  expect(Buffer.byteLength(result.text)).toBeLessThan(24 * 1024);
+  expect(result.isError).toBe(true);
+  expect(result.details?.fullOutputPath).toBeUndefined();
+  expect(result.details?.output).toMatchObject({ rawBytes: raw.length, persistence: 'host' });
+});
+
+describe('createLocalBackgroundBashExecutor', () => {
+  const seeded: string[] = [];
+
+  afterEach(() => {
+    for (const name of seeded.splice(0)) delete process.env[name];
+  });
+
+  it('hands the running callback to the operations path instead of firing it first', async () => {
+    const events: string[] = [];
+    const onPreflightComplete = () => {
+      events.push('preflight');
+    };
+    const create = vi.fn(
+      (input: { onPreflightComplete?: () => void | Promise<void> }): BashOperations => ({
+        separatesOutputStreams: true,
+        exec: async (_command, _cwd, options) => {
+          await input.onPreflightComplete?.();
+          events.push('exec');
+          options.onData(Buffer.from('ok'), 'stdout');
+          return { exitCode: 0 };
+        },
+      }),
+    );
+    const executor = createLocalBackgroundBashExecutor({ create }, { mode: 'off' });
+
+    const result = await executor.execute({
+      identity,
+      workspaceRoot: process.cwd(),
+      command: 'echo ok',
+      signal: new AbortController().signal,
+      onPreflightComplete,
+    });
+
+    expect(create).toHaveBeenCalledWith({
+      identity,
+      workspaceRoot: process.cwd(),
+      onPreflightComplete,
+    });
+    expect(events).toEqual(['preflight', 'exec']);
+    expect(result.text).toContain('ok');
+    expect(result.details).toMatchObject({
+      execution: { status: 'succeeded', reason: 'exited', exitCode: 0 },
+      processOutput: { stdout: 'ok', stderr: '', exitCode: 0 },
+    });
+  });
+
+  it('returns failed execution facts and split output without losing them to an exception', async () => {
+    const executor = createLocalBackgroundBashExecutor(
+      {
+        create: () => ({
+          separatesOutputStreams: true,
+          exec: async (_command, _cwd, options) => {
+            options.onData(Buffer.from('out'), 'stdout');
+            options.onData(Buffer.from('err'), 'stderr');
+            return { exitCode: 7 };
+          },
+        }),
+      },
+      { mode: 'off' },
+    );
+    const result = await executor.execute({
+      identity,
+      workspaceRoot: process.cwd(),
+      command: 'unused',
+      signal: new AbortController().signal,
+    });
+    expect(result).toMatchObject({
+      isError: true,
+      details: {
+        execution: { status: 'failed', reason: 'exited', exitCode: 7 },
+        processOutput: { stdout: 'out', stderr: 'err', exitCode: 7 },
+      },
+    });
+    expect(result.text).toContain('Command exited with code 7');
+  });
+
+  it('never marks the task running when the operations factory rejects admission', async () => {
+    const onPreflightComplete = vi.fn();
+    const admissionFailure = new Error('Sandbox Bash operations are unavailable');
+    const executor = createLocalBackgroundBashExecutor(
+      {
+        create: () => {
+          throw admissionFailure;
+        },
+      },
+      { mode: 'off' },
+    );
+
+    await expect(
+      executor.execute({
+        identity,
+        workspaceRoot: process.cwd(),
+        command: 'echo ok',
+        signal: new AbortController().signal,
+        onPreflightComplete,
+      }),
+    ).rejects.toBe(admissionFailure);
+    expect(onPreflightComplete).not.toHaveBeenCalled();
+  });
+
+  it('preserves a sandbox preflight error code without marking execution as started', async () => {
+    const onPreflightComplete = vi.fn();
+    const executor = createLocalBackgroundBashExecutor(
+      {
+        create: () => ({
+          exec: async () => {
+            throw Object.assign(new Error('Sandbox wrapping failed'), {
+              code: 'SANDBOX_WRAP_FAILED',
+              stage: 'pre-spawn',
+            });
+          },
+        }),
+      },
+      { mode: 'off' },
+    );
+    const result = await executor.execute({
+      identity,
+      workspaceRoot: process.cwd(),
+      command: 'unused',
+      signal: new AbortController().signal,
+      onPreflightComplete,
+    });
+    expect(result).toMatchObject({
+      isError: true,
+      text: 'Sandbox wrapping failed',
+      details: {
+        execution: {
+          status: 'failed',
+          reason: 'preflight_failed',
+          exitCode: null,
+          errorCode: 'SANDBOX_WRAP_FAILED',
+        },
+      },
+    });
+    expect(onPreflightComplete).not.toHaveBeenCalled();
+  });
+
+  it('keeps the shared Bash env sanitizer in the moved executor', async () => {
+    process.env.MAVIS_BASH_ENV_SANITIZE = 'strict';
+    process.env.MAVIS_ACCESS_TOKEN = 'background-boundary-secret';
+    process.env.SANDBOX_BACKGROUND_SECRET_TOKEN = 'background-pattern-secret';
+    process.env.SANDBOX_BACKGROUND_KEEP = 'background-visible';
+    seeded.push(
+      'MAVIS_BASH_ENV_SANITIZE',
+      'MAVIS_ACCESS_TOKEN',
+      'SANDBOX_BACKGROUND_SECRET_TOKEN',
+      'SANDBOX_BACKGROUND_KEEP',
+    );
+    let childEnv: NodeJS.ProcessEnv | undefined;
+    const executor = createLocalBackgroundBashExecutor(
+      {
+        create: () => ({
+          exec: async (_command, _cwd, options) => {
+            childEnv = options.env;
+            return { exitCode: 0 };
+          },
+        }),
+      },
+      // The moved executor must keep honouring the shared resolution chain
+      // (MAVIS_BASH_ENV_SANITIZE seeded above), now supplied by the caller.
+      resolveBashEnvPolicy(),
+    );
+
+    const result = await executor.execute({
+      identity: { ...identity, operationClass: 'explicit_background' },
+      workspaceRoot: process.cwd(),
+      command: 'true',
+      signal: new AbortController().signal,
+    });
+
+    expect(childEnv?.MAVIS_ACCESS_TOKEN).toBeUndefined();
+    expect(childEnv?.SANDBOX_BACKGROUND_SECRET_TOKEN).toBeUndefined();
+    expect(childEnv?.SANDBOX_BACKGROUND_KEEP).toBe('background-visible');
+    expect(result.details?.envSanitized).toEqual(
+      expect.arrayContaining(['MAVIS_ACCESS_TOKEN', 'SANDBOX_BACKGROUND_SECRET_TOKEN']),
+    );
+  });
+});
diff --git a/packages/local-runtime-v2/src/service/background-bash/executor.ts b/packages/local-runtime-v2/src/service/background-bash/executor.ts
index a80dabb6..4db207a6 100644
--- a/packages/local-runtime-v2/src/service/background-bash/executor.ts
+++ b/packages/local-runtime-v2/src/service/background-bash/executor.ts
@@ -1,11 +1,13 @@
 import { StringDecoder } from 'node:string_decoder';
 
 import { createBashTool, type BashOperations } from '@earendil-works/pi-coding-agent/tools';
+import { createBashEnvSpawnHook, type BashEnvPolicy } from '@mavis/agent-core/bash-subprocess-env';
 import {
-  createBashEnvSpawnHook,
-  type BashEnvPolicy,
-} from '@mavis/agent-core/bash-subprocess-env';
-import type { LocalSandboxBashOperationsFactory } from '@mavis/agent-tools/desktop';
+  localBashResultFromError,
+  localBashResultFromPi,
+  DESKTOP_BASH_PREVIEW_BYTES,
+  type LocalSandboxBashOperationsFactory,
+} from '@mavis/agent-tools/desktop';
 
 import type { LocalBackgroundBashExecutor } from './contracts.js';
 
@@ -38,9 +40,25 @@ export function createLocalBackgroundBashExecutor(
         combined: new StringDecoder('utf8'),
       };
       const operations: BashOperations = {
+        separatesOutputStreams: localOperations.separatesOutputStreams,
         exec: (command, cwd, options) =>
           localOperations.exec(command, cwd, {
             ...options,
+            onProcessEvent: (event) => {
+              options.onProcessEvent?.(event);
+              if (
+                event.type === 'timer_started' &&
+                event.atMs !== undefined &&
+                input.timeout !== undefined
+              ) {
+                input.onDetails?.({
+                  timing: {
+                    commandTimerStartedAt: event.atMs,
+                    commandDeadlineAt: event.atMs + input.timeout * 1000,
+                  },
+                });
+              }
+            },
             onData: (data, stream) => {
               options.onData(data, stream);
               input.onOutput?.(decoders[stream ?? 'combined'].write(data), data.length);
@@ -49,35 +67,37 @@ export function createLocalBackgroundBashExecutor(
       };
       let envSanitized: string[] = [];
       const tool = createBashTool(input.workspaceRoot, {
+        output: {
+          strategy: 'head_tail',
+          maxBytes: DESKTOP_BASH_PREVIEW_BYTES,
+          maxLines: Number.MAX_SAFE_INTEGER,
+          persistOutput: false,
+        },
         operations,
         spawnHook: createBashEnvSpawnHook(envPolicy, (removed) => {
           envSanitized = removed;
           if (removed.length > 0) input.onDetails?.({ envSanitized: removed });
         }),
       });
-      let result;
       try {
-        result = await tool.execute(
-          '',
-          { command: input.command, timeout: input.timeout },
-          input.signal,
+        const result = localBashResultFromPi(
+          await tool.execute('', { command: input.command, timeout: input.timeout }, input.signal),
         );
+        return {
+          ...result,
+          details: { ...result.details, ...(envSanitized.length > 0 ? { envSanitized } : {}) },
+        };
+      } catch (error) {
+        const result = localBashResultFromError(error, input.signal);
+        return {
+          ...result,
+          details: { ...result.details, ...(envSanitized.length > 0 ? { envSanitized } : {}) },
+        };
       } finally {
         input.onOutput?.(decoders.stdout.end(), 0);
         input.onOutput?.(decoders.stderr.end(), 0);
         input.onOutput?.(decoders.combined.end(), 0);
       }
-      const text = result.content
-        .filter((content): content is { type: 'text'; text: string } => content.type === 'text')
-        .map((content) => content.text)
-        .join('\n');
-      return {
-        text,
-        details: {
-          ...((result.details ?? {}) as Record<string, unknown>),
-          ...(envSanitized.length > 0 ? { envSanitized } : {}),
-        },
-      };
     },
   };
 }
diff --git a/packages/local-runtime-v2/src/service/turn-system/agent-host/assembly/local-turn-tool-catalog.ts b/packages/local-runtime-v2/src/service/turn-system/agent-host/assembly/local-turn-tool-catalog.ts
index 14ef7000..4bca123e 100644
--- a/packages/local-runtime-v2/src/service/turn-system/agent-host/assembly/local-turn-tool-catalog.ts
+++ b/packages/local-runtime-v2/src/service/turn-system/agent-host/assembly/local-turn-tool-catalog.ts
@@ -1,4 +1,8 @@
 import type { RuntimeTool, RuntimeToolSource } from '@mavis/agent-core/tools';
+import {
+  createLocalBashToolDefinition,
+  resolveLocalBashShell,
+} from '@mavis/agent-tools/desktop';
 import {
   filterCanonicalBuiltinMcpEntries,
   filterCanonicalNativeToolCeiling,
@@ -23,6 +27,25 @@ import type {
   LocalAgentExecutionProfile,
 } from '../preparation/contracts.js';
 
+export function prepareBashTurnTools(admittedTools: readonly RuntimeTool[], background: boolean) {
+  const hasNativeBash = admittedTools.some(
+    (tool) => tool.def.name === 'bash' && (tool.source === undefined || tool.source === 'builtin'),
+  );
+  const bashCapabilities = {
+    background,
+    shell: hasNativeBash ? resolveLocalBashShell() : ('unavailable' as const),
+  };
+  return admittedTools.map((tool) => {
+    if (tool.def.name !== 'bash' || (tool.source !== undefined && tool.source !== 'builtin'))
+      return tool;
+    const definition = createLocalBashToolDefinition(bashCapabilities);
+    return {
+      ...tool,
+      def: { ...tool.def, schema: definition.schema, description: definition.description },
+    };
+  });
+}
+
 export interface LocalTurnRawToolSources {
   readonly nativeTools: readonly RuntimeTool[];
   readonly mcpEntries: readonly McpToolEntry[];
diff --git a/packages/local-runtime-v2/src/service/turn-system/agent-host/execution/executor.test.ts b/packages/local-runtime-v2/src/service/turn-system/agent-host/execution/executor.test.ts
index 9ade9d71..151012d6 100644
--- a/packages/local-runtime-v2/src/service/turn-system/agent-host/execution/executor.test.ts
+++ b/packages/local-runtime-v2/src/service/turn-system/agent-host/execution/executor.test.ts
@@ -946,9 +946,16 @@ describe("LocalRuntimeTurnExecutor Bash output capability", () => {
             "Expected the native Bash tool and its Turn context to remain admitted",
           );
         }
+        const properties = admittedBash.def.schema.properties as Record<string, unknown>;
+        expect('run_in_background' in properties).toBe(allowed);
+        expect(admittedBash.def.description).toContain(
+          allowed ? 'task_output' : 'foreground execution only',
+        );
+        expect(bash.def.schema.properties).toHaveProperty('run_in_background');
+        expect(admittedBash.def.schema).not.toBe(bash.def.schema);
         const result = await admittedBash.impl.execute(
           toolContext,
-          { command: "controlled command" },
+          { description: '运行测试命令', command: 'controlled command' },
           runInput.signal,
         );
         if (allowed) expect(result.details?.status).toBe("auto_promoted");
@@ -958,7 +965,11 @@ describe("LocalRuntimeTurnExecutor Bash output capability", () => {
         }
         const backgroundResult = await admittedBash.impl.execute(
           toolContext,
-          { command: "controlled background command", run_in_background: true },
+          {
+            description: '运行测试命令',
+            command: 'controlled background command',
+            run_in_background: true,
+          },
           runInput.signal,
         );
         if (allowed) {
@@ -989,7 +1000,9 @@ describe("LocalRuntimeTurnExecutor Bash output capability", () => {
       expect(direct).toHaveBeenCalledTimes(allowed ? 0 : 1);
     },
   );
+});
 
+describe('LocalRuntimeTurnExecutor native output provenance', () => {
   it.each([
     { source: undefined, allowed: true },
     { source: "builtin" as const, allowed: true },
@@ -1034,10 +1047,12 @@ describe("LocalRuntimeTurnExecutor Bash output capability", () => {
               "Expected the native Bash tool and its Turn context to remain admitted",
             );
           }
+          expect('run_in_background' in admittedBash.def.schema.properties).toBe(allowed);
           const result = await admittedBash.impl.execute(
             toolContext,
             {
-              command: "controlled background command",
+              description: '运行测试命令',
+              command: 'controlled background command',
               run_in_background: true,
             },
             runInput.signal,
diff --git a/packages/local-runtime-v2/src/service/turn-system/agent-host/execution/executor.ts b/packages/local-runtime-v2/src/service/turn-system/agent-host/execution/executor.ts
index 7833cb4d..5d366408 100644
--- a/packages/local-runtime-v2/src/service/turn-system/agent-host/execution/executor.ts
+++ b/packages/local-runtime-v2/src/service/turn-system/agent-host/execution/executor.ts
@@ -16,6 +16,7 @@ import {
   toPiUserMessage,
 } from '@mavis/agent-core/pi-turn-runner';
 import { type RuntimeTool, type ToolExecutionContext } from '@mavis/agent-core/tools';
+import { prepareBashTurnTools } from '../assembly/local-turn-tool-catalog.js';
 import { buildCompletedTerminalStatusEvent } from '@mavis/agent-core/event-bridge';
 import {
   beginLocalPluginHookTurn,
@@ -473,14 +474,15 @@ export class LocalRuntimeTurnExecutor<
     });
     const readTaskOutputTaskIds = new Set<string>();
     const toolResolution = preparedExecution.toolResolution;
-    const tools = applyProcessLocalToolResultPolicy(
+    const admittedTools = applyProcessLocalToolResultPolicy(
       validateRoutedTurnTools(input.assembly.tools),
       this.options.cliProductPolicy === true,
     );
-    const canConsumeBackgroundBashOutput = tools.some(
+    const canConsumeBackgroundBashOutput = admittedTools.some(
       (tool) =>
         tool.def.name === 'task_output' && (tool.source === undefined || tool.source === 'builtin'),
     );
+    const tools = prepareBashTurnTools(admittedTools, canConsumeBackgroundBashOutput);
     const toolContext = {
       ...toolResolution.context,
       ...(input.pluginHooks?.length
diff --git a/packages/local-runtime-v2/test/unit/agent/builtin/catalog.test.ts b/packages/local-runtime-v2/test/unit/agent/builtin/catalog.test.ts
index 2b1805f0..980e3ded 100644
--- a/packages/local-runtime-v2/test/unit/agent/builtin/catalog.test.ts
+++ b/packages/local-runtime-v2/test/unit/agent/builtin/catalog.test.ts
@@ -1496,3 +1496,27 @@ describe("BuiltinAgentCatalog prompt modes", () => {
     );
   });
 });
+
+describe('Bash prompt contract across product surfaces', () => {
+  it.each([
+    { agentName: 'worker', surface: 'task-child', promptProfile: undefined },
+    { agentName: 'mavis', surface: 'interactive', promptProfile: 'desktop' },
+    { agentName: 'mavis', surface: 'cli', promptProfile: 'tui' },
+    { agentName: 'worker', surface: 'task-child', promptProfile: 'tui' },
+  ] as const)(
+    'renders capability-neutral base guidance for $agentName / $surface / $promptProfile',
+    async (profile) => {
+      const catalog = new BuiltinAgentCatalog();
+      const rendered = await catalog.render({
+        ...profile,
+        appMode: 'coding',
+        locale: 'zh-CN',
+        promptChannel: 'online',
+        capabilities: resolveAgentCapabilities({ tools: ['bash'] }),
+      });
+      const text = [rendered.corePrompt, rendered.surfacePrompt].join('\n');
+      expect(text).not.toContain('and yield to the same managed background process after 15s');
+      expect(text).not.toContain('PowerShell syntax only');
+    },
+  );
+});
diff --git a/packages/local-runtime/src/background-task/bash-output-writer.ts b/packages/local-runtime/src/background-task/bash-output-writer.ts
index 7dd86677..209bce4a 100644
--- a/packages/local-runtime/src/background-task/bash-output-writer.ts
+++ b/packages/local-runtime/src/background-task/bash-output-writer.ts
@@ -23,6 +23,7 @@ export class BackgroundBashOutputWriter {
   private recoveryOffset = 0;
   private recoveryContent = '';
   private droppedRecoveryBytes = 0;
+  private omittedBytes = 0;
   private retryTimer: NodeJS.Timeout | undefined;
   private retryDelayMs = INITIAL_RECOVERY_RETRY_MS;
   private settling = false;
@@ -55,10 +56,11 @@ export class BackgroundBashOutputWriter {
     this.beginSettlement();
     await this.flush();
     if (!this.streamedOutput && !this.rawOutputAccounting) {
-      this.outputBytes = Buffer.byteLength(result.text, 'utf8');
+      const facts = result.details?.output as { rawBytes?: number } | undefined;
+      this.outputBytes = facts?.rawBytes ?? Buffer.byteLength(result.text, 'utf8');
     }
     if (!this.persistenceIncomplete) {
-      return this.lastOutputRef ?? (await this.tryAppend(result.text, 'final_result'));
+      return this.lastOutputRef ?? (await this.appendTerminalOutput(result.text));
     }
     try {
       return await this.repairPendingOutput();
@@ -83,6 +85,21 @@ export class BackgroundBashOutputWriter {
     return this.appendTerminalOutput(content);
   }
 
+  describePersistence(outputRef?: TaskOutputRef): {
+    rawBytes: number;
+    persistence: 'complete' | 'incomplete';
+    omittedBytes: number;
+  } {
+    return {
+      rawBytes: this.outputBytes,
+      persistence:
+        !this.persistenceIncomplete && this.omittedBytes === 0 && outputRef
+          ? 'complete'
+          : 'incomplete',
+      omittedBytes: this.omittedBytes,
+    };
+  }
+
   private startDrain(): void {
     // Once the bounded window overflows, defer its omission marker until the
     // executor settles. This freezes the byte count while it is persisted and
@@ -155,10 +172,12 @@ export class BackgroundBashOutputWriter {
       retained = retained.slice(0, -1);
     }
     this.recoveryContent += retained;
-    this.droppedRecoveryBytes += Math.max(
+    const droppedBytes = Math.max(
       0,
       Buffer.byteLength(content, 'utf8') - Buffer.byteLength(retained, 'utf8'),
     );
+    this.droppedRecoveryBytes += droppedBytes;
+    this.omittedBytes += droppedBytes;
   }
 
   warn(operation: string, error: unknown): void {
diff --git a/packages/local-runtime/src/background-task/bash-runner.ts b/packages/local-runtime/src/background-task/bash-runner.ts
index 1646794f..ffe08b0f 100644
--- a/packages/local-runtime/src/background-task/bash-runner.ts
+++ b/packages/local-runtime/src/background-task/bash-runner.ts
@@ -1,20 +1,20 @@
-import type {
-  LocalBashAdapter,
-  LocalBashBackgroundStartResult,
-  LocalBashManagedForegroundResult,
-  LocalBashToolInput,
-  LocalRuntimeToolContext,
+import {
+  localBashResultFromError,
+  readBashExecutionOutcome,
+  resolveLocalBashTiming,
+  validateBashCommand,
+  resolveBashDescription,
+  type LocalBashTiming,
+  type LocalBashAdapter,
+  type LocalBashBackgroundStartResult,
+  type LocalBashManagedForegroundResult,
+  type LocalBashToolInput,
+  type LocalRuntimeToolContext,
 } from '@mavis/agent-tools/desktop';
 
 import type { LocalSessionRecord } from '../sessions/controller.js';
 import type { LocalTaskRunnerHostWithSessionLookup } from '../api/local-task-host.js';
-import {
-  createBackgroundTaskId,
-  normalizeTaskError,
-  type BackgroundTask,
-  type BackgroundTaskPatch,
-  type TaskOutputRef,
-} from './domain.js';
+import { createBackgroundTaskId, type BackgroundTask } from './domain.js';
 import { scheduleLocalBackgroundTaskDelivery } from './delivery.js';
 import { admitBackgroundTask, shutdownBackgroundTasks } from './lifecycle.js';
 import {
@@ -26,6 +26,11 @@ import {
   type LocalBackgroundBashCompletion,
 } from './bash-runner-lifecycle.js';
 import { BackgroundBashOutputWriter } from './bash-output-writer.js';
+import {
+  settleBackgroundBashTask,
+  settleFailedBackgroundBash,
+  withTaskOutputReceipt,
+} from './bash-task-settlement.js';
 import { capBackgroundBashMaxRunMs, resolveBackgroundBashMaxRunMs } from './bash-runner-limits.js';
 import {
   DEFAULT_LOCAL_BACKGROUND_BASH_EXECUTOR,
@@ -166,7 +171,9 @@ export async function runManagedForegroundLocalBash(input: {
       );
       recordSoftYieldMetric(input.host, started.taskId, completion.durationMs, 'completed');
       if (completion.status === 'canceled') {
-        throw managedBashAbortError(input.signal, completion.text);
+        throw Object.assign(managedBashAbortError(input.signal, completion.text), {
+          details: completion.details,
+        });
       }
       return {
         status: 'completed',
@@ -214,16 +221,18 @@ export async function runManagedForegroundLocalBash(input: {
 }
 
 async function startAdmittedBackgroundLocalBash(
-  input: Parameters<typeof startBackgroundLocalBash>[0],
+  input: Parameters<typeof startBackgroundLocalBash>[0] & { softYieldMs?: number },
   controller: AbortController,
   admission: ReturnType<typeof admitBackgroundTask>,
   executionMode: 'explicit_background' | 'managed_foreground',
 ): Promise<StartedLocalBackgroundBash> {
+  validateBashCommand(input.bashInput.command);
+  const timing = resolveLocalBashTiming(input.bashInput.timeout, executionMode);
   const taskId = createBackgroundTaskId();
   const now = input.host.nowMs();
-  const description = commandHead(input.bashInput.command);
+  const description = resolveBashDescription(input.bashInput.description, input.bashInput.command);
   const maxRunMs = capBackgroundBashMaxRunMs(
-    input.maxRunMs ?? resolveBackgroundBashMaxRunMs(input.bashInput.timeout),
+    input.maxRunMs ?? resolveBackgroundBashMaxRunMs(timing.commandTimeoutSeconds),
   );
   await input.host.backgroundTaskService.create({
     taskId,
@@ -240,17 +249,20 @@ async function startAdmittedBackgroundLocalBash(
       command: input.bashInput.command,
       ...(input.bashInput.timeout ? { timeoutSeconds: input.bashInput.timeout } : {}),
       maxRunMs,
+      timing,
       executionMode,
     },
   });
 
-  let startedDetails: Record<string, unknown> | undefined;
+  let startedDetails: Record<string, unknown> | undefined = { description };
   const settled = runBackgroundLocalBashCommand({
     host: input.host,
     parentSession: input.parentSession,
     taskId,
     command: input.bashInput.command,
-    timeout: input.bashInput.timeout,
+    description,
+    timeout: timing.commandTimeoutSeconds,
+    timing,
     maxRunMs,
     executionMode,
     toolCtx: input.toolCtx,
@@ -307,7 +319,9 @@ async function runBackgroundLocalBashCommand(input: {
   parentSession: LocalSessionRecord;
   taskId: string;
   command: string;
+  description: string;
   timeout?: number;
+  timing: LocalBashTiming;
   maxRunMs?: number;
   executionMode: 'explicit_background' | 'managed_foreground';
   toolCtx: LocalRuntimeToolContext;
@@ -329,6 +343,8 @@ async function runBackgroundLocalBashCommand(input: {
   const maxRunMs = capBackgroundBashMaxRunMs(
     input.maxRunMs ?? resolveBackgroundBashMaxRunMs(input.timeout),
   );
+  const timing = { ...input.timing };
+  input.onStartedDetails({ timing });
   let timedOut = false;
   const watchdog = setTimeout(() => {
     if (controller.signal.aborted) return;
@@ -336,7 +352,7 @@ async function runBackgroundLocalBashCommand(input: {
     controller.abort('TIMEOUT');
   }, maxRunMs);
   try {
-    const result = await input.executor.execute({
+    const executed = await input.executor.execute({
       identity: {
         operationClass: input.executionMode,
         invocationId: input.taskId,
@@ -357,9 +373,25 @@ async function runBackgroundLocalBashCommand(input: {
         });
       },
       onOutput: output.push,
-      onDetails: input.onStartedDetails,
+      onDetails: (details) => {
+        Object.assign(timing, details.timing);
+        input.onStartedDetails({ ...details, timing: { ...timing } });
+      },
     });
+    const result = {
+      ...executed,
+      details: {
+        ...executed.details,
+        description: input.description,
+        timing: { ...timing, ...(executed.details?.timing as object) },
+      },
+    };
+    const execution = readBashExecutionOutcome(result.details);
+    if (result.isError || (execution && execution.status !== 'succeeded')) {
+      return await settleFailedBackgroundBash(input, output, result, startedAt, timedOut, maxRunMs);
+    }
     const outputRef = await output.settleSuccess(result);
+    const completed = withTaskOutputReceipt(result, output, outputRef, input.taskId);
     const terminal = await settleBackgroundBashTask({
       host: input.host,
       output,
@@ -369,120 +401,46 @@ async function runBackgroundLocalBashCommand(input: {
       outputRef,
       lastError: undefined,
       metadata: {
-        ...(result.details ? { bashDetails: result.details } : {}),
+        bashDetails: completed.details,
         outputBytes: output.outputBytes,
       },
     });
     try {
-      await input.host.backgroundTaskService.finalizeOutput(input.taskId, result.text);
+      await input.host.backgroundTaskService.finalizeOutput(input.taskId, completed.text);
     } catch (error) {
       output.warn('finalize', error);
     }
     return {
       taskId: input.taskId,
       status: 'succeeded',
-      text: result.text,
-      ...(result.details ? { details: result.details } : {}),
+      text: completed.text,
+      details: completed.details,
       endedAt: terminal.endedAt,
       durationMs: terminal.durationMs,
       outputBytes: output.outputBytes,
     };
   } catch (error) {
-    const aborted = controller.signal.aborted;
-    // A maxRunMs abort is a governance timeout (failed), not a user cancel.
-    const status = timedOut ? 'failed' : aborted ? 'canceled' : 'failed';
-    const errorCode = timedOut ? 'TIMEOUT' : aborted ? 'BASH_CANCELED' : 'BASH_FAILED';
-    const errorText = timedOut
-      ? `Background bash timed out after ${maxRunMs}ms (exceeded maxRunMs): ${formatError(error)}`
-      : `Background bash ${aborted ? 'canceled' : 'failed'}: ${formatError(error)}`;
-    const terminalText = output.streamedOutput
-      ? `\n<bash_status>${errorText}</bash_status>\n`
-      : errorText;
-    const text = output.streamedOutput
-      ? `${output.streamedTextForError}${terminalText}`
-      : errorText;
-    const outputRef = await output.settleFailure(terminalText);
-    const lastError = timedOut
-      ? { message: `Background bash exceeded maxRunMs (${maxRunMs}ms)`, code: 'TIMEOUT' }
-      : normalizeTaskError(aborted ? controller.signal.reason : error, errorCode);
-    const terminal = await settleBackgroundBashTask({
-      host: input.host,
-      output,
-      taskId: input.taskId,
-      startedAt,
-      status,
-      outputRef,
-      lastError,
-      metadata: {
-        outputBytes: output.outputBytes,
-      },
-    });
-    return {
-      taskId: input.taskId,
-      status,
-      text,
-      isError: true,
-      endedAt: terminal.endedAt,
-      durationMs: terminal.durationMs,
-      outputBytes: output.outputBytes,
+    const failed = localBashResultFromError(error, controller.signal);
+    failed.details = {
+      ...failed.details,
+      description: input.description,
+      timing: { ...timing, ...(failed.details?.timing as object) },
     };
+    if (
+      output.streamedOutput &&
+      !readBashExecutionOutcome(
+        error && typeof error === 'object' && 'details' in error ? error.details : undefined,
+      )
+    ) {
+      failed.text = `${output.streamedTextForError}\n${failed.text}`;
+    }
+    return await settleFailedBackgroundBash(input, output, failed, startedAt, timedOut, maxRunMs);
   } finally {
     clearTimeout(watchdog);
     activeBackgroundBash.delete(input.taskId);
   }
 }
 
-async function settleBackgroundBashTask(input: {
-  host: LocalTaskRunnerHostWithSessionLookup;
-  output: BackgroundBashOutputWriter;
-  taskId: string;
-  startedAt: number;
-  status: LocalBackgroundBashCompletion['status'];
-  outputRef?: TaskOutputRef;
-  lastError: BackgroundTaskPatch['lastError'];
-  metadata: Record<string, unknown>;
-}): Promise<{ endedAt: number; durationMs: number }> {
-  const endedAt = input.host.nowMs();
-  const durationMs = Math.max(0, endedAt - input.startedAt);
-  const completion = await input.host.backgroundTaskService.patchIfNotTerminal(input.taskId, {
-    status: input.status,
-    endedAt,
-    ...(input.outputRef ? { outputRef: input.outputRef } : {}),
-    lastError: input.lastError,
-    metadata: {
-      ...input.metadata,
-      durationMs,
-      cacheTtlExceeded: durationMs >= 300_000,
-    },
-  });
-  if (!completion.patched && input.outputRef) {
-    try {
-      await patchTerminalBashOutput(input.host, input.taskId, input.outputRef);
-    } catch (error) {
-      input.output.warn('patch terminal', error);
-    }
-  }
-  return { endedAt, durationMs };
-}
-
-async function patchTerminalBashOutput(
-  host: LocalTaskRunnerHostWithSessionLookup,
-  taskId: string,
-  outputRef: TaskOutputRef,
-): Promise<void> {
-  const existing = await host.backgroundTaskService.get(taskId);
-  if (!existing) return;
-  await host.backgroundTaskService.patch(taskId, {
-    outputRef,
-    endedAt: existing.endedAt ?? host.nowMs(),
-  });
-}
-
-function commandHead(command: string): string {
-  const firstLine = command.trim().split(/\r?\n/, 1)[0] ?? '';
-  return firstLine.length <= 80 ? firstLine : `${firstLine.slice(0, 77)}...`;
-}
-
 function formatError(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
diff --git a/packages/local-runtime/src/background-task/bash-task-settlement.ts b/packages/local-runtime/src/background-task/bash-task-settlement.ts
new file mode 100644
index 00000000..6bcdc908
--- /dev/null
+++ b/packages/local-runtime/src/background-task/bash-task-settlement.ts
@@ -0,0 +1,172 @@
+import {
+  formatBashExecutionOutcome,
+  readBashExecutionOutcome,
+  type LocalBashExecutionOutcome,
+  type LocalBackgroundBashExecutorResult,
+} from '@mavis/agent-tools/desktop';
+
+import type { LocalTaskRunnerHostWithSessionLookup } from '../api/local-task-host.js';
+import type { BackgroundTaskPatch, TaskOutputRef } from './domain.js';
+import type { LocalBackgroundBashCompletion } from './bash-runner-lifecycle.js';
+import { BackgroundBashOutputWriter } from './bash-output-writer.js';
+
+export async function settleFailedBackgroundBash(
+  input: {
+    host: LocalTaskRunnerHostWithSessionLookup;
+    taskId: string;
+    controller: AbortController;
+  },
+  output: BackgroundBashOutputWriter,
+  result: LocalBackgroundBashExecutorResult,
+  startedAt: number,
+  watchdogTimedOut: boolean,
+  maxRunMs: number,
+): Promise<LocalBackgroundBashCompletion> {
+  const observed = readBashExecutionOutcome(result.details);
+  const execution: LocalBashExecutionOutcome = {
+    ...(observed ?? {
+      status: 'failed',
+      reason: 'unknown',
+      exitCode: null,
+      message: result.text,
+    }),
+  };
+  if (watchdogTimedOut) {
+    Object.assign(execution, {
+      status: 'failed',
+      reason: 'watchdog_timeout',
+      errorCode: 'TIMEOUT',
+      message: `Background bash timed out after ${maxRunMs}ms (exceeded maxRunMs)`,
+    });
+  } else if (!observed && input.controller.signal.aborted) {
+    execution.status = 'canceled';
+    execution.reason = 'canceled';
+  }
+  const errorText = formatBashExecutionOutcome(execution);
+  const text = watchdogTimedOut ? `${result.text}\n\n${errorText}` : result.text;
+  const status = execution.status === 'canceled' ? 'canceled' : 'failed';
+  const statusText = watchdogTimedOut ? errorText : `Background bash ${status}: ${errorText}`;
+  const terminalText = output.streamedOutput
+    ? `\n<bash_status>${statusText}</bash_status>\n`
+    : result.text === errorText
+      ? statusText
+      : `${text}\n\n${statusText}`;
+  const outputRef = await output.settleFailure(terminalText);
+  const completed = withTaskOutputReceipt(
+    { text, details: { ...result.details, execution } },
+    output,
+    outputRef,
+    input.taskId,
+  );
+  const details = completed.details;
+  const terminal = await settleBackgroundBashTask({
+    host: input.host,
+    output,
+    taskId: input.taskId,
+    startedAt,
+    status,
+    outputRef,
+    lastError: {
+      message: status === 'canceled' ? (execution.cancellationReason ?? errorText) : errorText,
+      code:
+        execution.errorCode ??
+        (execution.reason === 'command_timeout'
+          ? 'BASH_TIMEOUT'
+          : status === 'canceled'
+            ? 'BASH_CANCELED'
+            : 'BASH_FAILED'),
+    },
+    metadata: { bashDetails: details, outputBytes: output.outputBytes },
+  });
+  return {
+    taskId: input.taskId,
+    status,
+    text: completed.text,
+    details,
+    isError: true,
+    endedAt: terminal.endedAt,
+    durationMs: terminal.durationMs,
+    outputBytes: output.outputBytes,
+  };
+}
+
+export function withTaskOutputReceipt(
+  result: LocalBackgroundBashExecutorResult,
+  writer: BackgroundBashOutputWriter,
+  outputRef: TaskOutputRef | undefined,
+  taskId: string,
+): LocalBackgroundBashExecutorResult & { details: Record<string, unknown> } {
+  const facts = writer.describePersistence(outputRef);
+  const { fullOutputPath: _oldPath, ...details } = result.details ?? {};
+  const fullOutputPath =
+    facts.persistence === 'complete' && outputRef?.kind === 'file' ? outputRef.uri : undefined;
+  const truncated = (details.truncation as { truncated?: boolean } | undefined)?.truncated;
+  const receipt =
+    facts.persistence === 'incomplete'
+      ? `[Output persistence incomplete; the log may be missing output. Use task_output with task_id=${taskId} for the saved portion; do not assume a complete log.]`
+      : truncated
+        ? `[Full output: task_output with task_id=${taskId}; continue with next_offset (log file bytes).]`
+        : '';
+  return {
+    ...result,
+    text: receipt ? `${result.text}\n\n${receipt}` : result.text,
+    details: {
+      ...details,
+      ...(fullOutputPath ? { fullOutputPath } : {}),
+      ...(details.processOutput
+        ? {
+            processOutput: { ...(details.processOutput as object), rawOutputPath: fullOutputPath },
+          }
+        : {}),
+      output: { ...(details.output as object), ...facts },
+    },
+  };
+}
+
+export async function settleBackgroundBashTask(input: {
+  host: LocalTaskRunnerHostWithSessionLookup;
+  output: BackgroundBashOutputWriter;
+  taskId: string;
+  startedAt: number;
+  status: LocalBackgroundBashCompletion['status'];
+  outputRef?: TaskOutputRef;
+  lastError: BackgroundTaskPatch['lastError'];
+  metadata: Record<string, unknown>;
+}): Promise<{ endedAt: number; durationMs: number }> {
+  const endedAt = input.host.nowMs();
+  const durationMs = Math.max(0, endedAt - input.startedAt);
+  const completion = await input.host.backgroundTaskService.patchIfNotTerminal(input.taskId, {
+    status: input.status,
+    endedAt,
+    ...(input.outputRef ? { outputRef: input.outputRef } : {}),
+    lastError: input.lastError,
+    metadata: {
+      ...input.metadata,
+      durationMs,
+      cacheTtlExceeded: durationMs >= 300_000,
+    },
+  });
+  if (!completion.patched) {
+    try {
+      await patchTerminalBashResult(input.host, input.taskId, input.outputRef, input.metadata);
+    } catch (error) {
+      input.output.warn('patch terminal', error);
+    }
+  }
+  return { endedAt, durationMs };
+}
+
+async function patchTerminalBashResult(
+  host: LocalTaskRunnerHostWithSessionLookup,
+  taskId: string,
+  outputRef: TaskOutputRef | undefined,
+  metadata: Record<string, unknown>,
+): Promise<void> {
+  const existing = await host.backgroundTaskService.get(taskId);
+  if (!existing) return;
+  await host.backgroundTaskService.patch(taskId, {
+    ...(outputRef ? { outputRef } : {}),
+    metadata,
+    endedAt: existing.endedAt ?? host.nowMs(),
+  });
+}
diff --git a/packages/local-runtime/src/background-task/service.ts b/packages/local-runtime/src/background-task/service.ts
index bc39fb80..f1d4d546 100644
--- a/packages/local-runtime/src/background-task/service.ts
+++ b/packages/local-runtime/src/background-task/service.ts
@@ -1,9 +1,9 @@
 import { waitForChildBashTaskChange } from './child-bash-lifecycle.js';
+import { performTaskStop } from './task-stop.js';
 import {
   createTaskLifecycleEventId,
   InvalidTaskStatusTransitionError,
   isTerminalTaskStatus,
-  normalizeTaskError,
   type BackgroundTask,
   type BackgroundTaskCheckpointSnapshot,
   type BackgroundTaskReminderSnapshot,
@@ -244,13 +244,14 @@ export class LocalBackgroundTaskService implements LocalTaskControlAdapter {
           return {
             ...read,
             status: task.status,
+            task,
             ...(waitMs > 0 ? { timedOut: false } : {}),
           };
         }
 
         const remainingMs = deadline - Date.now();
         if (remainingMs <= 0) {
-          return { ...read, status: task.status, timedOut: true };
+          return { ...read, status: task.status, task, timedOut: true };
         }
         const outcome = await waiter!.wait(remainingMs);
         if (outcome === 'timeout') {
@@ -258,7 +259,7 @@ export class LocalBackgroundTaskService implements LocalTaskControlAdapter {
           const latestRead = await this.outputStore.read(taskId, readOptions);
           return {
             ...latestRead,
-            ...(latestTask ? { status: latestTask.status } : {}),
+            ...(latestTask ? { status: latestTask.status, task: latestTask } : {}),
             timedOut: true,
           };
         }
@@ -286,7 +287,18 @@ export class LocalBackgroundTaskService implements LocalTaskControlAdapter {
     // make every concurrent caller reuse its settled terminal result.
     const pendingAfterRead = this.stopRequests.get(taskId);
     if (pendingAfterRead) return pendingAfterRead;
-    const stopping = this.performStop(task, reason);
+    const stopping = performTaskStop(
+      {
+        store: this.store,
+        nowMs: this.nowMs,
+        stopRuntime: this.stopRuntime,
+        patchStatusIfNotTerminal: (current, status, patch) =>
+          this.patchStatusIfNotTerminal(current, status, patch),
+        emit: (current, type, payload) => this.emit(current, type, payload),
+      },
+      task,
+      reason,
+    );
     this.stopRequests.set(taskId, stopping);
     try {
       return await stopping;
@@ -295,41 +307,6 @@ export class LocalBackgroundTaskService implements LocalTaskControlAdapter {
     }
   }
 
-  private async performStop(task: BackgroundTask, reason?: string): Promise<BackgroundTask> {
-    const taskId = task.taskId;
-    const stoppingResult = await this.patchStatusIfNotTerminal(task, 'stopping', {
-      updatedAt: this.nowMs(),
-      ...(reason ? { lastError: { message: reason, code: 'TASK_STOP_REQUESTED' } } : {}),
-    });
-    if (!stoppingResult.patched) return stoppingResult.task;
-    const stopping = stoppingResult.task;
-    await this.emit(stopping, 'stop_requested', { reason });
-    try {
-      await this.stopRuntime?.(stopping, reason);
-      const settled = await this.store.get(taskId);
-      if (settled && isTerminalTaskStatus(settled.status)) return settled;
-      const canceledResult = await this.patchStatusIfNotTerminal(stopping, 'canceled', {
-        endedAt: this.nowMs(),
-        ...(reason ? { lastError: { message: reason, code: 'TASK_CANCELED' } } : {}),
-      });
-      if (!canceledResult.patched) return canceledResult.task;
-      const canceled = canceledResult.task;
-      await this.emit(canceled, 'completed', { status: 'canceled' });
-      return canceled;
-    } catch (error) {
-      const settled = await this.store.get(taskId);
-      if (settled && isTerminalTaskStatus(settled.status)) return settled;
-      const canceledResult = await this.patchStatusIfNotTerminal(stopping, 'canceled', {
-        endedAt: this.nowMs(),
-        lastError: normalizeTaskError(error, 'TASK_STOP_FAILED'),
-      });
-      if (!canceledResult.patched) return canceledResult.task;
-      const canceled = canceledResult.task;
-      await this.emit(canceled, 'completed', { status: 'canceled', stopFailed: true });
-      return canceled;
-    }
-  }
-
   async patch(taskId: string, patch: BackgroundTaskPatch): Promise<BackgroundTask> {
     const task = await this.store.patch(taskId, patch);
     if (patch.status) {
diff --git a/packages/local-runtime/src/background-task/task-stop.ts b/packages/local-runtime/src/background-task/task-stop.ts
new file mode 100644
index 00000000..21ceaec7
--- /dev/null
+++ b/packages/local-runtime/src/background-task/task-stop.ts
@@ -0,0 +1,66 @@
+import {
+  isTerminalTaskStatus,
+  normalizeTaskError,
+  type BackgroundTask,
+  type BackgroundTaskPatch,
+  type BackgroundTaskStatus,
+  type TaskStore,
+} from './domain.js';
+
+interface TaskStopContext {
+  store: Pick<TaskStore, 'get' | 'patch'>;
+  nowMs(): number;
+  stopRuntime?: (task: BackgroundTask, reason?: string) => Promise<void>;
+  patchStatusIfNotTerminal(
+    task: BackgroundTask,
+    status: BackgroundTaskStatus,
+    patch: Omit<BackgroundTaskPatch, 'status'>,
+  ): Promise<{ task: BackgroundTask; patched: boolean }>;
+  emit(
+    task: BackgroundTask,
+    type: 'stop_requested' | 'completed',
+    payload: Record<string, unknown>,
+  ): Promise<void>;
+}
+
+export async function performTaskStop(
+  context: TaskStopContext,
+  task: BackgroundTask,
+  reason?: string,
+): Promise<BackgroundTask> {
+  const taskId = task.taskId;
+  const stoppingResult = await context.patchStatusIfNotTerminal(task, 'stopping', {
+    updatedAt: context.nowMs(),
+    ...(reason ? { lastError: { message: reason, code: 'TASK_STOP_REQUESTED' } } : {}),
+  });
+  if (!stoppingResult.patched) return stoppingResult.task;
+  const stopping = stoppingResult.task;
+  await context.emit(stopping, 'stop_requested', { reason });
+  try {
+    await context.stopRuntime?.(stopping, reason);
+    const settled = await context.store.get(taskId);
+    if (settled && isTerminalTaskStatus(settled.status)) return settled;
+    const canceledResult = await context.patchStatusIfNotTerminal(stopping, 'canceled', {
+      endedAt: context.nowMs(),
+      ...(reason ? { lastError: { message: reason, code: 'TASK_CANCELED' } } : {}),
+    });
+    if (!canceledResult.patched) return canceledResult.task;
+    const canceled = canceledResult.task;
+    await context.emit(canceled, 'completed', { status: 'canceled' });
+    return canceled;
+  } catch (error) {
+    const stopError = normalizeTaskError(error, 'TASK_STOP_FAILED');
+    const settled = await context.store.patch(taskId, {
+      metadata: { stopError },
+    });
+    if (isTerminalTaskStatus(settled.status)) return settled;
+    const canceledResult = await context.patchStatusIfNotTerminal(stopping, 'canceled', {
+      endedAt: context.nowMs(),
+      lastError: stopError,
+    });
+    if (!canceledResult.patched) return canceledResult.task;
+    const canceled = canceledResult.task;
+    await context.emit(canceled, 'completed', { status: 'canceled', stopFailed: true });
+    return canceled;
+  }
+}
diff --git a/packages/local-runtime/test/unit/child-bash-lifecycle.test.ts b/packages/local-runtime/test/unit/child-bash-lifecycle.test.ts
index 87097d83..4ce07865 100644
--- a/packages/local-runtime/test/unit/child-bash-lifecycle.test.ts
+++ b/packages/local-runtime/test/unit/child-bash-lifecycle.test.ts
@@ -188,12 +188,12 @@ describe('child Bash lifecycle', () => {
         mode === 'explicit'
           ? await adapter.startBackground(
               toolContext('child'),
-              { command, run_in_background: true },
+              { description: '运行测试命令', command, run_in_background: true },
               controller.signal,
             )
           : await adapter.runManagedForeground!(
               toolContext('child'),
-              { command },
+              { description: '运行测试命令', command },
               1,
               controller.signal,
             );
@@ -220,7 +220,7 @@ describe('child Bash lifecycle', () => {
 });
 
 describe('real child Bash boundaries', () => {
-  it('uses the actual 15 second LocalBashTool soft yield and then recovers output', async () => {
+  it('keeps the 600 second command deadline across the actual 60 second soft yield', async () => {
     const { dataDir, host, lifecycle, service, controller } = await fixture();
     const session = {
       ...parentSessionRecord(dataDir),
@@ -238,23 +238,40 @@ describe('real child Bash boundaries', () => {
     const startedAt = Date.now();
     try {
       const receipt = await tool.execute(
-        toolContext('child'),
+        { ...toolContext('child'), canConsumeBackgroundBashOutput: true },
         {
-          command: nodeCommand("setTimeout(() => console.log('after-real-soft-yield'), 16500)"),
+          description: '运行测试命令',
+          command: nodeCommand("setTimeout(() => console.log('after-real-soft-yield'), 61500)"),
         },
         controller.signal,
       );
       expect(receipt.details).toMatchObject({ status: 'auto_promoted' });
-      expect(Date.now() - startedAt).toBeGreaterThanOrEqual(15000);
+      expect(Date.now() - startedAt).toBeGreaterThanOrEqual(60000);
+      const timing = receipt.details?.timing as {
+        commandTimeoutSeconds: number;
+        commandTimerStartedAt: number;
+        commandDeadlineAt: number;
+      };
+      expect(timing.commandTimeoutSeconds).toBe(600);
+      expect(timing.commandTimerStartedAt).toBeGreaterThanOrEqual(startedAt);
+      expect(timing.commandDeadlineAt - timing.commandTimerStartedAt).toBe(600_000);
+      expect(timing.commandDeadlineAt - Date.now()).toBeLessThan(550_000);
       const taskId = String(receipt.details?.task_id);
       expect(await lifecycle.poll({ ...poll, wait: true })).toContain(taskId);
       expect((await service.readOutput(toolContext('child'), taskId)).content).toContain(
         'after-real-soft-yield',
       );
+      expect((await service.get(taskId))?.metadata?.bashDetails).toMatchObject({
+        timing: {
+          commandTimeoutSeconds: 600,
+          commandTimerStartedAt: timing.commandTimerStartedAt,
+          commandDeadlineAt: timing.commandDeadlineAt,
+        },
+      });
     } finally {
       await lifecycle.close();
     }
-  }, 30000);
+  }, 90000);
   it.each(['failure', 'timeout', 'cancel'] as const)(
     'preserves real shell %s and cleans up the process',
     async (mode) => {
@@ -277,6 +294,7 @@ describe('real child Bash boundaries', () => {
       const receipt = await adapter.startBackground(
         toolContext('child'),
         {
+          description: '运行测试命令',
           command: nodeCommand(script),
           ...(mode === 'timeout' ? { timeout: 1 } : {}),
         },
diff --git a/packages/local-runtime/test/unit/local-background-bash-review-regressions.test.ts b/packages/local-runtime/test/unit/local-background-bash-review-regressions.test.ts
new file mode 100644
index 00000000..2dfdecc7
--- /dev/null
+++ b/packages/local-runtime/test/unit/local-background-bash-review-regressions.test.ts
@@ -0,0 +1,430 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { describe, expect, it } from 'vitest';
+
+import {
+  runManagedForegroundLocalBash,
+  startBackgroundLocalBash,
+} from '../../src/background-task/bash-runner.js';
+import { recordBashMetrics } from '../../src/background-task/bash-runner-lifecycle.js';
+import { BackgroundBashOutputWriter } from '../../src/background-task/bash-output-writer.js';
+import type { LocalTaskRunnerHostWithSessionLookup } from '../../src/api/local-task-host.js';
+import { LocalBackgroundTaskService } from '../../src/background-task/service.js';
+import {
+  FsLocalTaskOutputStore,
+  SqliteLocalBackgroundTaskStore,
+} from '../../src/background-task/store.js';
+import { closeLocalRuntimeDb } from '../../src/persistence/db.js';
+import {
+  backgroundBashHost,
+  parentSessionRecord,
+  toolContext,
+  waitForTaskStatus,
+} from './background-task-test-helpers.js';
+
+describe('local background bash review regressions', () => {
+  it('records Bash completion correlation even when the metrics client throws', () => {
+    const recorded: unknown[] = [];
+    const host = {
+      metricsClient: {
+        counter: () => {
+          throw new Error('metrics unavailable');
+        },
+      },
+      matrixLogger: {
+        warn: () => {
+          throw new Error('logger unavailable');
+        },
+      },
+      recordSessionBashCompletion: (sessionId: string, completion: unknown) =>
+        recorded.push({ sessionId, completion }),
+    } as unknown as LocalTaskRunnerHostWithSessionLookup;
+
+    expect(() =>
+      recordBashMetrics(
+        host,
+        'session-a',
+        {
+          taskId: 'task-a',
+          status: 'succeeded',
+          text: '',
+          endedAt: 2_000,
+          durationMs: 1_000,
+          outputBytes: 0,
+        },
+        'managed_foreground',
+      ),
+    ).not.toThrow();
+
+    expect(recorded).toEqual([
+      { sessionId: 'session-a', completion: { endedAt: 2_000, durationMs: 1_000 } },
+    ]);
+  });
+
+  it('aligns arbitrary byte offsets before returning a four-byte UTF-8 code point', async () => {
+    const dataDir = await mkdtemp(join(tmpdir(), 'local-background-bash-utf8-range-'));
+    try {
+      const outputStore = new FsLocalTaskOutputStore(dataDir);
+      await outputStore.append({ taskId: 'utf8-offset', content: '😀😀' });
+
+      const page = await outputStore.read('utf8-offset', { offset: 1, limitBytes: 1 });
+      const fractionalPage = await outputStore.read('utf8-offset', {
+        offset: 1.5,
+        limitBytes: 1,
+      });
+
+      expect(page.content).toBe('😀');
+      expect(page.content).not.toContain('�');
+      expect(page.nextOffset).toBe(8);
+      expect(page.truncated).toBe(false);
+      expect(fractionalPage).toMatchObject(page);
+    } finally {
+      await rm(dataDir, { recursive: true, force: true });
+    }
+  });
+
+  it('propagates a parent abort from managed foreground instead of returning completed', async () => {
+    const dataDir = await mkdtemp(join(tmpdir(), 'local-managed-bash-parent-abort-'));
+    try {
+      const service = new LocalBackgroundTaskService({
+        store: new SqliteLocalBackgroundTaskStore(dataDir, () => 71_000),
+        outputStore: new FsLocalTaskOutputStore(dataDir),
+        nowMs: () => 71_000,
+      });
+      const host = backgroundBashHost(service, dataDir);
+      const parentAbort = new AbortController();
+      let markExecutorStarted!: () => void;
+      const executorStarted = new Promise<void>((resolve) => {
+        markExecutorStarted = resolve;
+      });
+      const result = runManagedForegroundLocalBash({
+        host,
+        parentSession: parentSessionRecord(dataDir),
+        toolCtx: toolContext('session-a'),
+        bashInput: { command: 'wait for cancel', timeout: 120 },
+        softYieldMs: 5_000,
+        signal: parentAbort.signal,
+        executor: {
+          execute: ({ signal }) =>
+            new Promise((_resolve, reject) => {
+              signal.addEventListener('abort', () => reject(signal.reason), { once: true });
+              markExecutorStarted();
+            }),
+        },
+      });
+
+      await executorStarted;
+      const abortError = Object.assign(new Error('Operation aborted'), { name: 'AbortError' });
+      parentAbort.abort(abortError);
+
+      await expect(result).rejects.toBe(abortError);
+      const tasks = await service.list({ ownerSessionId: 'session-a' });
+      expect(tasks.items).toHaveLength(1);
+      expect(tasks.items[0]?.status).toBe('canceled');
+    } finally {
+      closeLocalRuntimeDb(dataDir);
+      await rm(dataDir, { recursive: true, force: true });
+    }
+  });
+
+  it('repairs task output after a streamed append fails mid-command', async () => {
+    const dataDir = await mkdtemp(join(tmpdir(), 'local-background-bash-output-repair-'));
+    try {
+      const backingOutputStore = new FsLocalTaskOutputStore(dataDir);
+      let appendCount = 0;
+      const service = new LocalBackgroundTaskService({
+        store: new SqliteLocalBackgroundTaskStore(dataDir, () => 72_000),
+        outputStore: {
+          append: async (chunk) => {
+            appendCount += 1;
+            if (appendCount === 2) throw new Error('transient output append failure');
+            return backingOutputStore.append(chunk);
+          },
+          read: (taskId, options) => backingOutputStore.read(taskId, options),
+          tail: (taskId, limitBytes) => backingOutputStore.tail(taskId, limitBytes),
+          finalize: (taskId, summary) => backingOutputStore.finalize(taskId, summary),
+        },
+        nowMs: () => 72_000,
+      });
+      const host = backgroundBashHost(service, dataDir);
+      const first = `${'a'.repeat(65_535)}中`;
+      const expected = `${first}second\n`;
+      const secondEmitted = deferred<void>();
+      const releaseExecutor = deferred<void>();
+      const started = await startBackgroundLocalBash({
+        host,
+        parentSession: parentSessionRecord(dataDir),
+        toolCtx: toolContext('session-a'),
+        bashInput: { command: 'stream with transient persistence failure' },
+        executor: {
+          execute: async ({ onOutput, onPreflightComplete }) => {
+            await onPreflightComplete?.();
+            onOutput?.(first);
+            await new Promise<void>((resolve) => setImmediate(resolve));
+            onOutput?.('second\n');
+            secondEmitted.resolve();
+            await releaseExecutor.promise;
+            return { text: expected };
+          },
+        },
+      });
+
+      await secondEmitted.promise;
+      await expect
+        .poll(async () => {
+          const output = await service.readOutput(toolContext('session-a'), started.taskId!, {
+            offset: 0,
+            limitBytes: Buffer.byteLength(expected, 'utf8') + 1,
+          });
+          return output.content;
+        })
+        .toBe(expected);
+      expect((await service.get(toolContext('session-a'), started.taskId!))?.status).toBe(
+        'running',
+      );
+      releaseExecutor.resolve();
+      await waitForTaskStatus(service, started.taskId!, 'succeeded');
+      const output = await service.readOutput(toolContext('session-a'), started.taskId!, {
+        offset: 0,
+        limitBytes: Buffer.byteLength(expected, 'utf8') + 1,
+      });
+      expect(output.content).toBe(expected);
+
+      const firstPage = await service.readOutput(toolContext('session-a'), started.taskId!, {
+        offset: 0,
+        limitBytes: 65_536,
+      });
+      const secondPage = await service.readOutput(toolContext('session-a'), started.taskId!, {
+        offset: firstPage.nextOffset,
+        limitBytes: 65_536,
+      });
+      expect(firstPage.content + secondPage.content).toBe(expected);
+      expect(firstPage.content + secondPage.content).not.toContain('�');
+    } finally {
+      closeLocalRuntimeDb(dataDir);
+      await rm(dataDir, { recursive: true, force: true });
+    }
+  });
+
+  it('bounds recovery after persistent output failure and records an omission marker', async () => {
+    const firstAppendFailed = deferred<void>();
+    const allowRecoveryRead = deferred<void>();
+    const appendedPayloads: string[] = [];
+    let persisted = '';
+    let appendAttempts = 0;
+    const host = {
+      nowMs: () => 72_250,
+      matrixLogger: { warn: () => undefined },
+      backgroundTaskService: {
+        appendOutput: async ({ content }: { content: string }) => {
+          appendAttempts += 1;
+          appendedPayloads.push(content);
+          if (appendAttempts === 1) {
+            firstAppendFailed.resolve();
+            throw new Error('persistent output append failure');
+          }
+          persisted += content;
+          return {
+            taskId: 'bounded-recovery',
+            kind: 'memory',
+            uri: 'memory://bounded-recovery',
+            offset: Buffer.byteLength(persisted, 'utf8'),
+          };
+        },
+        readOutput: async (_taskId: string, options: { offset?: number }) => {
+          await allowRecoveryRead.promise;
+          const offset = options.offset ?? 0;
+          const bytes = Buffer.from(persisted, 'utf8');
+          const content = bytes.subarray(offset).toString('utf8');
+          return {
+            content,
+            nextOffset: bytes.length,
+            truncated: false,
+            outputRef: {
+              taskId: 'bounded-recovery',
+              kind: 'memory',
+              uri: 'memory://bounded-recovery',
+              offset: bytes.length,
+            },
+          };
+        },
+      },
+    } as unknown as LocalTaskRunnerHostWithSessionLookup;
+    const writer = new BackgroundBashOutputWriter(host, 'session-a', 'bounded-recovery');
+
+    writer.push('seed');
+    await firstAppendFailed.promise;
+    const recoveryState = writer as unknown as {
+      persistenceIncomplete: boolean;
+      recoveryContent: string;
+      droppedRecoveryBytes: number;
+    };
+    await expect.poll(() => recoveryState.persistenceIncomplete).toBe(true);
+    for (let index = 0; index < 8; index += 1) writer.push('x'.repeat(1024 * 1024));
+    expect(recoveryState.recoveryContent.length).toBe(1024 * 1024);
+    expect(recoveryState.droppedRecoveryBytes).toBe(7_340_036);
+    allowRecoveryRead.resolve();
+    const outputRef = await writer.settleSuccess({ text: '' });
+    expect(writer.describePersistence(outputRef)).toMatchObject({ persistence: 'incomplete', omittedBytes: 7_340_036, rawBytes: 8 * 1024 * 1024 + 4 });
+
+    expect(Math.max(...appendedPayloads.map((content) => content.length))).toBeLessThan(
+      2 * 1024 * 1024,
+    );
+    expect(persisted).toContain('omitted 7340036 bytes');
+    expect(persisted.length).toBeLessThan(2 * 1024 * 1024);
+  });
+
+  it('repairs the failure reason when its terminal append also fails transiently', async () => {
+    let appendAttempts = 0;
+    let persisted = '';
+    const host = {
+      nowMs: () => 72_375,
+      matrixLogger: { warn: () => undefined },
+      backgroundTaskService: {
+        appendOutput: async ({ content }: { content: string }) => {
+          appendAttempts += 1;
+          if (appendAttempts === 1 || appendAttempts === 3) {
+            throw new Error('transient output append failure');
+          }
+          persisted += content;
+          return {
+            taskId: 'terminal-recovery',
+            kind: 'memory',
+            uri: 'memory://terminal-recovery',
+            offset: Buffer.byteLength(persisted, 'utf8'),
+          };
+        },
+        readOutput: async (_taskId: string, options: { offset?: number }) => {
+          const offset = options.offset ?? 0;
+          const bytes = Buffer.from(persisted, 'utf8');
+          return {
+            content: bytes.subarray(offset).toString('utf8'),
+            nextOffset: bytes.length,
+            truncated: false,
+            outputRef: {
+              taskId: 'terminal-recovery',
+              kind: 'memory',
+              uri: 'memory://terminal-recovery',
+              offset: bytes.length,
+            },
+          };
+        },
+      },
+    } as unknown as LocalTaskRunnerHostWithSessionLookup;
+    const writer = new BackgroundBashOutputWriter(host, 'session-a', 'terminal-recovery');
+    const terminal = '\n<bash_status>Background bash failed: exit 7</bash_status>\n';
+
+    writer.push('streamed suffix');
+    await writer.settleFailure(terminal);
+
+    expect(appendAttempts).toBe(4);
+    expect(persisted).toBe(`streamed suffix${terminal}`);
+  });
+
+  it('repairs failed task output after a streamed append fails mid-command', async () => {
+    const dataDir = await mkdtemp(join(tmpdir(), 'local-background-bash-failed-output-repair-'));
+    try {
+      const backingOutputStore = new FsLocalTaskOutputStore(dataDir);
+      let appendCount = 0;
+      const service = new LocalBackgroundTaskService({
+        store: new SqliteLocalBackgroundTaskStore(dataDir, () => 72_500),
+        outputStore: {
+          append: async (chunk) => {
+            appendCount += 1;
+            if (appendCount === 2) throw new Error('transient output append failure');
+            return backingOutputStore.append(chunk);
+          },
+          read: (taskId, options) => backingOutputStore.read(taskId, options),
+          tail: (taskId, limitBytes) => backingOutputStore.tail(taskId, limitBytes),
+          finalize: (taskId, summary) => backingOutputStore.finalize(taskId, summary),
+        },
+        nowMs: () => 72_500,
+      });
+      const host = backgroundBashHost(service, dataDir);
+      const started = await startBackgroundLocalBash({
+        host,
+        parentSession: parentSessionRecord(dataDir),
+        toolCtx: toolContext('session-a'),
+        bashInput: { command: 'stream then fail' },
+        executor: {
+          execute: async ({ onOutput }) => {
+            onOutput?.('first\n');
+            await new Promise<void>((resolve) => setImmediate(resolve));
+            onOutput?.('second\n');
+            throw new Error('exit 7');
+          },
+        },
+      });
+
+      await waitForTaskStatus(service, started.taskId!, 'failed');
+      const output = await service.readOutput(toolContext('session-a'), started.taskId!, {
+        limitBytes: 64 * 1024,
+      });
+      expect(output.content).toContain('first\nsecond\n');
+      expect(output.content).toContain('<bash_status>Background bash failed: exit 7</bash_status>');
+    } finally {
+      closeLocalRuntimeDb(dataDir);
+      await rm(dataDir, { recursive: true, force: true });
+    }
+  });
+
+  it('coalesces bursty streamed output instead of queuing one persistence promise per chunk', async () => {
+    const dataDir = await mkdtemp(join(tmpdir(), 'local-background-bash-output-burst-'));
+    try {
+      const backingOutputStore = new FsLocalTaskOutputStore(dataDir);
+      let appendCount = 0;
+      const service = new LocalBackgroundTaskService({
+        store: new SqliteLocalBackgroundTaskStore(dataDir, () => 73_000),
+        outputStore: {
+          append: async (chunk) => {
+            appendCount += 1;
+            await new Promise<void>((resolve) => setImmediate(resolve));
+            return backingOutputStore.append(chunk);
+          },
+          read: (taskId, options) => backingOutputStore.read(taskId, options),
+          tail: (taskId, limitBytes) => backingOutputStore.tail(taskId, limitBytes),
+          finalize: (taskId, summary) => backingOutputStore.finalize(taskId, summary),
+        },
+        nowMs: () => 73_000,
+      });
+      const host = backgroundBashHost(service, dataDir);
+      const chunks = Array.from({ length: 1_000 }, (_, index) => `${index}\n`);
+      const expected = chunks.join('');
+      const started = await startBackgroundLocalBash({
+        host,
+        parentSession: parentSessionRecord(dataDir),
+        toolCtx: toolContext('session-a'),
+        bashInput: { command: 'emit burst' },
+        executor: {
+          execute: async ({ onOutput }) => {
+            for (const chunk of chunks) onOutput?.(chunk);
+            return { text: expected };
+          },
+        },
+      });
+
+      await waitForTaskStatus(service, started.taskId!, 'succeeded');
+      const output = await service.readOutput(toolContext('session-a'), started.taskId!, {
+        limitBytes: Buffer.byteLength(expected, 'utf8') + 1,
+      });
+      expect(output.content).toBe(expected);
+      expect(appendCount).toBeLessThan(10);
+    } finally {
+      closeLocalRuntimeDb(dataDir);
+      await rm(dataDir, { recursive: true, force: true });
+    }
+  });
+});
+
+function deferred<T>(): {
+  promise: Promise<T>;
+  resolve(value: T | PromiseLike<T>): void;
+} {
+  let resolve!: (value: T | PromiseLike<T>) => void;
+  const promise = new Promise<T>((settle) => {
+    resolve = settle;
+  });
+  return { promise, resolve };
+}
diff --git a/packages/local-runtime/test/unit/local-background-bash-runner.test.ts b/packages/local-runtime/test/unit/local-background-bash-runner.test.ts
new file mode 100644
index 00000000..41cbfde4
--- /dev/null
+++ b/packages/local-runtime/test/unit/local-background-bash-runner.test.ts
@@ -0,0 +1,959 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { describe, expect, it, vi } from 'vitest';
+import { createLocalBashOperations } from '@earendil-works/pi-coding-agent/tools';
+import { LocalBashTool, LocalTaskOutputTool, LocalTaskQueryTool } from '@mavis/agent-tools/desktop';
+
+import {
+  DEFAULT_BACKGROUND_BASH_MAX_RUN_MS,
+  MAX_BACKGROUND_BASH_MAX_RUN_MS,
+  buildLocalBashAdapter,
+  resolveBackgroundBashMaxRunMs,
+  runManagedForegroundLocalBash,
+  startBackgroundLocalBash,
+  stopBackgroundLocalBashTask,
+  type LocalBackgroundBashExecutor,
+} from '../../src/background-task/bash-runner.js';
+import { createLocalBackgroundBashExecutor } from '../../../local-runtime-v2/src/service/background-bash/executor.js';
+import { LocalBackgroundTaskService } from '../../src/background-task/service.js';
+import {
+  FsLocalTaskOutputStore,
+  SqliteLocalBackgroundTaskStore,
+} from '../../src/background-task/store.js';
+import { closeLocalRuntimeDb } from '../../src/persistence/db.js';
+import { logger } from '../../src/common/logger.js';
+import {
+  backgroundBashHost,
+  parentSessionRecord,
+  taskRecord,
+  taskStoreWithPatch,
+  toolContext,
+  waitForTaskOutput,
+  waitForTaskStatus,
+} from './background-task-test-helpers.js';
+
+const MOVED_LOCAL_BACKGROUND_BASH_EXECUTOR = createLocalBackgroundBashExecutor(
+  {
+    create: (input) =>
+      createLocalBashOperations({
+        parentDeathGuard: input.identity.operationClass !== 'direct_foreground',
+      }),
+  },
+  { mode: 'off' },
+);
+
+describe('local background bash runner', () => {
+  it.skipIf(process.platform === 'win32').each([
+    {
+      description: '运行测试命令',
+      command: "printf 'partial-output'; exit 0",
+      status: 'succeeded',
+      reason: 'exited',
+      exitCode: 0,
+    },
+    { description: '运行测试命令', command: "printf 'partial-output'; exit 7", status: 'failed', reason: 'exited', exitCode: 7 },
+    {
+      description: '运行测试命令',
+      command: "printf 'partial-output'; kill -TERM $$",
+      status: 'failed',
+      reason: 'signaled',
+      exitCode: null,
+      signal: 'SIGTERM',
+    },
+    {
+      description: '运行测试命令',
+      command: "printf 'partial-output'; sleep 2",
+      timeout: 0.1,
+      status: 'failed',
+      reason: 'command_timeout',
+      exitCode: null,
+    },
+  ] as const)(
+    'preserves the same execution facts across all Bash modes: $reason / $exitCode',
+    async (scenario) => {
+      const dataDir = await mkdtemp(join(tmpdir(), 'local-bash-result-contract-'));
+      try {
+        const service = new LocalBackgroundTaskService({
+          store: new SqliteLocalBackgroundTaskStore(dataDir),
+          outputStore: new FsLocalTaskOutputStore(dataDir),
+        });
+        const host = backgroundBashHost(service, dataDir);
+        const ctx = { ...toolContext('session-a'), canConsumeBackgroundBashOutput: true };
+        const args = {
+          description: '运行测试命令',
+          command: scenario.command,
+          timeout: 'timeout' in scenario ? scenario.timeout : 3,
+        };
+        const direct = await new LocalBashTool(dataDir, undefined, { mode: 'off' }).execute(
+          ctx,
+          args,
+        );
+        const managed = await new LocalBashTool(
+          dataDir,
+          buildLocalBashAdapter(host, parentSessionRecord(dataDir), MOVED_LOCAL_BACKGROUND_BASH_EXECUTOR),
+          { mode: 'off' },
+        ).execute(ctx, args);
+        const started = await startBackgroundLocalBash({
+          host,
+          parentSession: parentSessionRecord(dataDir),
+          toolCtx: ctx,
+          bashInput: { ...args, run_in_background: true },
+          executor: MOVED_LOCAL_BACKGROUND_BASH_EXECUTOR,
+        });
+        const task = await waitForTaskStatus(service, started.taskId!, scenario.status);
+        const expected = {
+          status: scenario.status,
+          reason: scenario.reason,
+          exitCode: scenario.exitCode,
+          ...('signal' in scenario ? { signal: scenario.signal } : {}),
+        };
+        expect(direct.details).toMatchObject({ execution: expected, timing: { commandTimeoutSeconds: args.timeout, commandTimerStartedAt: expect.any(Number), commandDeadlineAt: expect.any(Number) } });
+        expect(managed.details).toMatchObject({ status: scenario.status, execution: expected });
+        expect(task.metadata?.bashDetails).toMatchObject({ execution: expected });
+        expect(direct.isError === true).toBe(scenario.status === 'failed');
+        expect(managed.isError === true).toBe(scenario.status === 'failed');
+        expect(direct.text).toContain('partial-output');
+        expect(managed.text).toBe(direct.text);
+        expect(managed.details?.processOutput).toMatchObject({ stdout: 'partial-output', stderr: '' });
+        const output = await new LocalTaskOutputTool(service).execute(ctx, {
+          task_id: task.taskId,
+        });
+        expect(output.details).toMatchObject({ execution: expected });
+        expect(output.isError).not.toBe(true);
+        expect(output.text).toContain('partial-output');
+        const query = await new LocalTaskQueryTool(service).execute(ctx, { task_id: task.taskId });
+        expect(query.details).toMatchObject({ task: { execution: expected } });
+        if (scenario.status === 'failed') expect(task.lastError?.message).toBeTruthy();
+      } finally {
+        closeLocalRuntimeDb(dataDir);
+        await rm(dataDir, { recursive: true, force: true });
+      }
+    },
+  );
+
+  it.each(['visible', 'hidden'] as const)(
+    'enables both background paths for %s task children',
+    (visibility) => {
+      const adapter = buildLocalBashAdapter({} as Parameters<typeof buildLocalBashAdapter>[0], {
+        ...parentSessionRecord('/tmp/workspace'),
+        sessionType: 'branch',
+        sessionKind: 'task',
+        parentSessionId: 'parent',
+        visibility,
+      });
+      expect(adapter.startBackground).toBeTypeOf('function');
+      expect(adapter.runManagedForeground).toBeTypeOf('function');
+    },
+  );
+
+  it('keeps managed foreground soft-yield enabled for ordinary sessions', () => {
+    const adapter = buildLocalBashAdapter(
+      {} as Parameters<typeof buildLocalBashAdapter>[0],
+      parentSessionRecord('/tmp/workspace'),
+    );
+
+    expect(adapter.runManagedForeground).toBeTypeOf('function');
+  });
+
+  it('reaches succeeded even when output persistence and finalization fail', async () => {
+    const dataDir = await mkdtemp(join(tmpdir(), 'local-background-bash-output-failure-'));
+    try {
+      const store = new SqliteLocalBackgroundTaskStore(dataDir, () => 29_000);
+      const backingOutputStore = new FsLocalTaskOutputStore(dataDir);
+      const service = new LocalBackgroundTaskService({
+        store,
+        outputStore: {
+          append: async () => {
+            throw new Error('output append unavailable');
+          },
+          read: (taskId, options) => backingOutputStore.read(taskId, options),
+          tail: (taskId, limitBytes) => backingOutputStore.tail(taskId, limitBytes),
+          finalize: async () => {
+            throw new Error('output finalize unavailable');
+          },
+        },
+        nowMs: () => 29_000,
+      });
+      const host = backgroundBashHost(service, dataDir);
+      const started = await startBackgroundLocalBash({
+        host,
+        parentSession: parentSessionRecord(dataDir),
+        toolCtx: toolContext('session-a'),
+        bashInput: { description: '运行测试命令', command: 'echo durable-status', run_in_background: true },
+        executor: { execute: async () => ({ text: 'durable-status\n' }) },
+      });
+
+      const task = await waitForTaskStatus(service, started.taskId!, 'succeeded');
+      expect(task.outputRef).toBeUndefined();
+      expect(task.metadata?.bashDetails).toMatchObject({ output: { persistence: 'incomplete' } });
+      expect(task.metadata?.bashDetails).not.toHaveProperty('fullOutputPath');
+      expect(task.lastError).toBeUndefined();
+    } finally {
+      closeLocalRuntimeDb(dataDir);
+      await rm(dataDir, { recursive: true, force: true });
+    }
+  });
+
+  it('reaches failed even when the failure output cannot be persisted', async () => {
+    const dataDir = await mkdtemp(join(tmpdir(), 'local-background-bash-failure-output-'));
+    try {
+      const store = new SqliteLocalBackgroundTaskStore(dataDir, () => 29_250);
+      const backingOutputStore = new FsLocalTaskOutputStore(dataDir);
+      const service = new LocalBackgroundTaskService({
+        store,
+        outputStore: {
+          append: async () => {
+            throw new Error('output append unavailable');
+          },
+          read: (taskId, options) => backingOutputStore.read(taskId, options),
+          tail: (taskId, limitBytes) => backingOutputStore.tail(taskId, limitBytes),
+          finalize: (taskId, summary) => backingOutputStore.finalize(taskId, summary),
+        },
+        nowMs: () => 29_250,
+      });
+      const host = backgroundBashHost(service, dataDir);
+      const started = await startBackgroundLocalBash({
+        host,
+        parentSession: parentSessionRecord(dataDir),
+        toolCtx: toolContext('session-a'),
+        bashInput: { description: '运行测试命令', command: 'exit 7', run_in_background: true },
+        executor: {
+          execute: async () => {
+            throw new Error('exit 7');
+          },
+        },
+      });
+
+      const task = await waitForTaskStatus(service, started.taskId!, 'failed');
+      expect(task.outputRef).toBeUndefined();
+      expect(task.metadata?.bashDetails).toMatchObject({ output: { persistence: 'incomplete' } });
+      expect(task.metadata?.bashDetails).not.toHaveProperty('fullOutputPath');
+      expect(task.lastError?.code).toBe('BASH_FAILED');
+    } finally {
+      closeLocalRuntimeDb(dataDir);
+      await rm(dataDir, { recursive: true, force: true });
+    }
+  });
+
+  it('still stops the runtime when the stop_requested event cannot be persisted', async () => {
+    const dataDir = await mkdtemp(join(tmpdir(), 'local-background-stop-event-failure-'));
+    const warn = vi.spyOn(logger, 'warn').mockImplementation(() => {
+      throw new Error('logger unavailable');
+    });
+    try {
+      const store = new SqliteLocalBackgroundTaskStore(dataDir, () => 29_500);
+      const trackingStore = taskStoreWithPatch(store, async () => undefined);
+      const appendEvent = trackingStore.appendEvent.bind(trackingStore);
+      trackingStore.appendEvent = async (event) => {
+        if (event.type === 'stop_requested') throw new Error('event store unavailable');
+        await appendEvent(event);
+      };
+      let stopped = false;
+      const service = new LocalBackgroundTaskService({
+        store: trackingStore,
+        outputStore: new FsLocalTaskOutputStore(dataDir),
+        nowMs: () => 29_500,
+        stopRuntime: async () => {
+          stopped = true;
+        },
+      });
+      await store.create(taskRecord('running-task', 'session-a', { status: 'running' }));
+
+      await expect(service.stop('running-task', 'user stopped')).resolves.toMatchObject({
+        status: 'canceled',
+      });
+      expect(stopped).toBe(true);
+      expect(warn).toHaveBeenCalledWith(
+        expect.objectContaining({ lifecycleType: 'stop_requested' }),
+        'Failed to persist background task lifecycle event',
+      );
+    } finally {
+      warn.mockRestore();
+      closeLocalRuntimeDb(dataDir);
+      await rm(dataDir, { recursive: true, force: true });
+    }
+  });
+
+  it('streams output while the task is still running without duplicating the final snapshot', async () => {
+    const dataDir = await mkdtemp(join(tmpdir(), 'local-background-bash-stream-'));
+    try {
+      const service = new LocalBackgroundTaskService({
+        store: new SqliteLocalBackgroundTaskStore(dataDir, () => 30_000),
+        outputStore: new FsLocalTaskOutputStore(dataDir),
+        nowMs: () => 30_000,
+      });
+      const host = backgroundBashHost(service, dataDir);
+      let finish!: () => void;
+      const executor: LocalBackgroundBashExecutor = {
+        execute: async ({ onOutput, onPreflightComplete }) => {
+          await onPreflightComplete?.();
+          onOutput?.('first\n');
+          await new Promise<void>((resolve) => {
+            finish = resolve;
+          });
+          onOutput?.('second\n');
+          return { text: 'first\nsecond\n' };
+        },
+      };
+
+      const started = await startBackgroundLocalBash({
+        host,
+        parentSession: parentSessionRecord(dataDir),
+        toolCtx: toolContext('session-a'),
+        bashInput: { description: '运行测试命令', command: 'stream', run_in_background: true },
+        executor,
+      });
+
+      await expect(waitForTaskOutput(service, started.taskId!, 'first')).resolves.toContain('first');
+      expect((await service.get(toolContext('session-a'), started.taskId!))?.status).toBe('running');
+      finish();
+      await waitForTaskStatus(service, started.taskId!, 'succeeded');
+      const output = await service.readOutput(toolContext('session-a'), started.taskId!, { offset: 0 });
+      expect(output.content).toBe('first\nsecond\n');
+    } finally {
+      closeLocalRuntimeDb(dataDir);
+      await rm(dataDir, { recursive: true, force: true });
+    }
+  });
+
+  it('returns a fast managed command inline and suppresses its completion wake-up', async () => {
+    const dataDir = await mkdtemp(join(tmpdir(), 'local-managed-bash-fast-'));
+    try {
+      const service = new LocalBackgroundTaskService({
+        store: new SqliteLocalBackgroundTaskStore(dataDir, () => 32_000),
+        outputStore: new FsLocalTaskOutputStore(dataDir),
+        nowMs: () => 32_000,
+      });
+      const host = backgroundBashHost(service, dataDir);
+      let managedIdentity: Parameters<LocalBackgroundBashExecutor['execute']>[0]['identity'];
+      const result = await runManagedForegroundLocalBash({
+        host,
+        parentSession: parentSessionRecord(dataDir),
+        toolCtx: { ...toolContext('session-a'), forceReadOnlyFilesystem: true },
+        bashInput: { description: '运行测试命令', command: 'echo fast', timeout: 120 },
+        softYieldMs: 50,
+        executor: {
+          execute: async ({ identity, onPreflightComplete }) => {
+            managedIdentity = identity;
+            await onPreflightComplete?.();
+            return { text: 'fast\n' };
+          },
+        },
+      });
+
+      expect(result).toMatchObject({ status: 'completed', text: 'fast\n' });
+      expect(managedIdentity!).toEqual({
+        operationClass: 'managed_foreground',
+        invocationId: result.taskId,
+        sessionId: 'session-a',
+        turnId: 'turn-session-a',
+        toolCallId: 'call-session-a',
+        taskId: result.taskId,
+        forceReadOnlyFilesystem: true,
+      });
+      const task = await service.get(toolContext('session-a'), result.taskId!);
+      expect(task).toMatchObject({ status: 'succeeded', deliveredAt: 32_000 });
+      expect(task?.metadata).toMatchObject({ completionOrigin: 'foreground' });
+    } finally {
+      closeLocalRuntimeDb(dataDir);
+      await rm(dataDir, { recursive: true, force: true });
+    }
+  });
+
+  it.each([
+    { timeout: undefined, effectiveTimeout: 600 },
+    { timeout: 45, effectiveTimeout: 45 },
+    { timeout: 600, effectiveTimeout: 600 },
+    { timeout: 900, effectiveTimeout: 600 },
+  ])('soft-yields with total command timeout $effectiveTimeout for requested $timeout', async ({ timeout, effectiveTimeout }) => {
+    const dataDir = await mkdtemp(join(tmpdir(), 'local-managed-bash-slow-'));
+    try {
+      const service = new LocalBackgroundTaskService({
+        store: new SqliteLocalBackgroundTaskStore(dataDir, () => 33_000),
+        outputStore: new FsLocalTaskOutputStore(dataDir),
+        nowMs: () => 33_000,
+      });
+      const host = backgroundBashHost(service, dataDir);
+      let finish!: () => void;
+      let dispatchedTimeout: number | undefined;
+      const result = await runManagedForegroundLocalBash({
+        host,
+        parentSession: parentSessionRecord(dataDir),
+        toolCtx: toolContext('session-a'),
+        bashInput: { description: '运行测试命令', command: 'slow', timeout },
+        softYieldMs: 10,
+        executor: {
+          execute: async ({ onPreflightComplete, timeout: commandTimeout }) => {
+            dispatchedTimeout = commandTimeout;
+            await onPreflightComplete?.();
+            return new Promise((resolve) => {
+              finish = () => resolve({ text: 'done\n' });
+            });
+          },
+        },
+      });
+
+      expect(result).toMatchObject({ status: 'auto_promoted', details: { description: '运行测试命令' } });
+      expect(dispatchedTimeout).toBe(effectiveTimeout);
+      expect(result.details).toMatchObject({ timing: { commandTimeoutSeconds: effectiveTimeout } });
+      expect((await service.get(result.taskId!))?.description).toBe('运行测试命令');
+      expect((await service.get(toolContext('session-a'), result.taskId!))?.status).toBe('running');
+      finish();
+      await waitForTaskStatus(service, result.taskId!, 'succeeded');
+      expect((await service.get(toolContext('session-a'), result.taskId!))?.metadata).toMatchObject({
+        executionMode: 'auto_promoted',
+        bashDetails: { timing: { commandTimeoutSeconds: effectiveTimeout } },
+      });
+    } finally {
+      closeLocalRuntimeDb(dataDir);
+      await rm(dataDir, { recursive: true, force: true });
+    }
+  });
+
+  it('returns spawn-time env sanitization details on an auto-promoted command', async () => {
+    const dataDir = await mkdtemp(join(tmpdir(), 'local-managed-bash-env-hint-'));
+    process.env.MAVIS_ACCESS_TOKEN = 'must-not-reach-child';
+    try {
+      const service = new LocalBackgroundTaskService({
+        store: new SqliteLocalBackgroundTaskStore(dataDir, () => 33_500),
+        outputStore: new FsLocalTaskOutputStore(dataDir),
+        nowMs: () => 33_500,
+      });
+      const host = backgroundBashHost(service, dataDir);
+      const result = await runManagedForegroundLocalBash({
+        host,
+        parentSession: parentSessionRecord(dataDir),
+        toolCtx: toolContext('session-a'),
+        bashInput: { description: '运行测试命令', command: 'sleep 0.1; echo done', timeout: 120 },
+        softYieldMs: 10,
+        executor: MOVED_LOCAL_BACKGROUND_BASH_EXECUTOR,
+      });
+
+      expect(result).toMatchObject({
+        status: 'auto_promoted',
+        details: { envSanitized: expect.arrayContaining(['MAVIS_ACCESS_TOKEN']) },
+      });
+      await waitForTaskStatus(service, result.taskId!, 'succeeded');
+    } finally {
+      delete process.env.MAVIS_ACCESS_TOKEN;
+      closeLocalRuntimeDb(dataDir);
+      await rm(dataDir, { recursive: true, force: true });
+    }
+  });
+
+  it('runs local bash in the background and stores final output', async () => {
+    const dataDir = await mkdtemp(join(tmpdir(), 'local-background-bash-'));
+    try {
+      const service = new LocalBackgroundTaskService({
+        store: new SqliteLocalBackgroundTaskStore(dataDir, () => 31_000),
+        outputStore: new FsLocalTaskOutputStore(dataDir),
+        nowMs: () => 31_000,
+      });
+      const host = backgroundBashHost(service, dataDir);
+      let explicitIdentity: Parameters<LocalBackgroundBashExecutor['execute']>[0]['identity'];
+      const executor: LocalBackgroundBashExecutor = {
+        execute: async ({ command, identity, onPreflightComplete }) => {
+          explicitIdentity = identity;
+          await onPreflightComplete?.();
+          return { text: `ran:${command}` };
+        },
+      };
+
+      const started = await startBackgroundLocalBash({
+        host,
+        parentSession: parentSessionRecord(dataDir),
+        toolCtx: { ...toolContext('session-a'), forceReadOnlyFilesystem: true },
+        bashInput: { description: '运行测试命令', command: 'echo ok', run_in_background: true },
+        executor,
+      });
+
+      expect(started.status).toBe('started');
+      const task = await waitForTaskStatus(service, started.taskId!, 'succeeded');
+      expect(task).toMatchObject({ kind: 'bash', description: '运行测试命令' });
+      expect(explicitIdentity!).toEqual({
+        operationClass: 'explicit_background',
+        invocationId: started.taskId,
+        sessionId: 'session-a',
+        turnId: 'turn-session-a',
+        toolCallId: 'call-session-a',
+        taskId: started.taskId,
+        forceReadOnlyFilesystem: true,
+      });
+      await expect(service.readOutput(toolContext('session-a'), started.taskId!)).resolves.toMatchObject({
+        content: 'ran:echo ok',
+      });
+    } finally {
+      closeLocalRuntimeDb(dataDir);
+      await rm(dataDir, { recursive: true, force: true });
+    }
+  });
+
+  it('aborts a running background bash task through the shared task stop path', async () => {
+    const dataDir = await mkdtemp(join(tmpdir(), 'local-background-bash-stop-'));
+    try {
+      const store = new SqliteLocalBackgroundTaskStore(dataDir, () => 41_000);
+      const service = new LocalBackgroundTaskService({
+        store,
+        outputStore: new FsLocalTaskOutputStore(dataDir),
+        nowMs: () => 41_000,
+        stopRuntime: stopBackgroundLocalBashTask,
+      });
+      const host = backgroundBashHost(service, dataDir);
+      let aborted = false;
+      const executor: LocalBackgroundBashExecutor = {
+        execute: ({ signal }) =>
+          new Promise((_resolve, reject) => {
+            signal.addEventListener('abort', () => {
+              aborted = true;
+              reject(new Error('aborted'));
+            });
+          }),
+      };
+
+      const started = await startBackgroundLocalBash({
+        host,
+        parentSession: parentSessionRecord(dataDir),
+        toolCtx: toolContext('session-a'),
+        bashInput: { description: '运行测试命令', command: 'sleep 100', run_in_background: true },
+        executor,
+      });
+
+      await service.stop(toolContext('session-a'), started.taskId!, 'user stopped');
+      const task = await waitForTaskStatus(service, started.taskId!, 'canceled');
+      expect(aborted).toBe(true);
+      expect(task).toMatchObject({ kind: 'bash', status: 'canceled' });
+      await expect(
+        waitForTaskOutput(service, started.taskId!, 'Background bash canceled'),
+      ).resolves.toContain('Background bash canceled');
+    } finally {
+      closeLocalRuntimeDb(dataDir);
+      await rm(dataDir, { recursive: true, force: true });
+    }
+  });
+
+  it('keeps task_stop in stopping until runner cleanup and final output settle', async () => {
+    const dataDir = await mkdtemp(join(tmpdir(), 'local-background-bash-stop-settle-'));
+    try {
+      const service = new LocalBackgroundTaskService({
+        store: new SqliteLocalBackgroundTaskStore(dataDir, () => 42_000),
+        outputStore: new FsLocalTaskOutputStore(dataDir),
+        nowMs: () => 42_000,
+        stopRuntime: stopBackgroundLocalBashTask,
+      });
+      const host = backgroundBashHost(service, dataDir);
+      let releaseCleanup!: () => void;
+      const cleanupGate = new Promise<void>((resolve) => {
+        releaseCleanup = resolve;
+      });
+      const executor: LocalBackgroundBashExecutor = {
+        execute: ({ signal, onOutput }) =>
+          new Promise((_resolve, reject) => {
+            signal.addEventListener('abort', () => {
+              void cleanupGate.then(() => {
+                onOutput?.('cleanup-finished\n');
+                reject(new Error('aborted after cleanup'));
+              });
+            });
+          }),
+      };
+
+      const started = await startBackgroundLocalBash({
+        host,
+        parentSession: parentSessionRecord(dataDir),
+        toolCtx: toolContext('session-a'),
+        bashInput: { description: '运行测试命令', command: 'deferred-cleanup', run_in_background: true },
+        executor,
+      });
+
+      let stopSettled = false;
+      const stopping = service
+        .stop(toolContext('session-a'), started.taskId!, 'user stopped')
+        .then((task) => {
+          stopSettled = true;
+          return task;
+        });
+      await new Promise((resolve) => setTimeout(resolve, 0));
+      expect(stopSettled).toBe(false);
+      expect((await service.get(toolContext('session-a'), started.taskId!))?.status).toBe(
+        'stopping',
+      );
+
+      releaseCleanup();
+      await expect(stopping).resolves.toMatchObject({ status: 'canceled' });
+      await expect(service.readOutput(toolContext('session-a'), started.taskId!)).resolves.toMatchObject({
+        status: 'canceled',
+        content: expect.stringContaining('cleanup-finished'),
+      });
+    } finally {
+      closeLocalRuntimeDb(dataDir);
+      await rm(dataDir, { recursive: true, force: true });
+    }
+  });
+
+  it('keeps a user stop canceled when cleanup outlives the maxRun watchdog', async () => {
+    const dataDir = await mkdtemp(join(tmpdir(), 'local-background-bash-stop-watchdog-'));
+    try {
+      const store = new SqliteLocalBackgroundTaskStore(dataDir, () => 43_000);
+      const completedEvents: string[] = [];
+      const trackingStore = taskStoreWithPatch(store, async () => undefined);
+      const appendEvent = trackingStore.appendEvent.bind(trackingStore);
+      trackingStore.appendEvent = async (event) => {
+        if (event.type === 'completed') completedEvents.push(event.type);
+        await appendEvent(event);
+      };
+      const service = new LocalBackgroundTaskService({
+        store: trackingStore,
+        outputStore: new FsLocalTaskOutputStore(dataDir),
+        nowMs: () => 43_000,
+        stopRuntime: stopBackgroundLocalBashTask,
+      });
+      const host = backgroundBashHost(service, dataDir);
+      let releaseCleanup!: () => void;
+      const cleanupGate = new Promise<void>((resolve) => {
+        releaseCleanup = resolve;
+      });
+      const executor: LocalBackgroundBashExecutor = {
+        execute: ({ signal }) =>
+          new Promise((_resolve, reject) => {
+            signal.addEventListener('abort', () => {
+              void cleanupGate.then(() => reject(new Error('stopped after cleanup')));
+            });
+          }),
+      };
+
+      const started = await startBackgroundLocalBash({
+        host,
+        parentSession: parentSessionRecord(dataDir),
+        toolCtx: toolContext('session-a'),
+        bashInput: { description: '运行测试命令', command: 'slow-cleanup', run_in_background: true },
+        executor,
+        maxRunMs: 20,
+      });
+      const stopping = service.stop(toolContext('session-a'), started.taskId!, 'user stopped');
+      await new Promise((resolve) => setTimeout(resolve, 50));
+      releaseCleanup();
+
+      await expect(stopping).resolves.toMatchObject({
+        status: 'canceled',
+        lastError: { code: 'BASH_CANCELED' },
+      });
+      expect(completedEvents).toEqual(['completed']);
+    } finally {
+      closeLocalRuntimeDb(dataDir);
+      await rm(dataDir, { recursive: true, force: true });
+    }
+  });
+
+  it('clears a stop-request marker when the command wins the race and succeeds', async () => {
+    const dataDir = await mkdtemp(join(tmpdir(), 'local-background-bash-stop-success-'));
+    try {
+      const service = new LocalBackgroundTaskService({
+        store: new SqliteLocalBackgroundTaskStore(dataDir, () => 44_000),
+        outputStore: new FsLocalTaskOutputStore(dataDir),
+        nowMs: () => 44_000,
+        stopRuntime: stopBackgroundLocalBashTask,
+      });
+      const host = backgroundBashHost(service, dataDir);
+      const executor: LocalBackgroundBashExecutor = {
+        execute: ({ signal }) =>
+          new Promise((resolve) => {
+            signal.addEventListener('abort', () => resolve({ text: 'finished anyway' }));
+          }),
+      };
+
+      const started = await startBackgroundLocalBash({
+        host,
+        parentSession: parentSessionRecord(dataDir),
+        toolCtx: toolContext('session-a'),
+        bashInput: { description: '运行测试命令', command: 'finish-on-stop', run_in_background: true },
+        executor,
+      });
+      const stopped = await service.stop(
+        toolContext('session-a'),
+        started.taskId!,
+        'user stopped',
+      );
+
+      expect(stopped).toMatchObject({ status: 'succeeded' });
+      expect(stopped?.lastError).toBeUndefined();
+    } finally {
+      closeLocalRuntimeDb(dataDir);
+      await rm(dataDir, { recursive: true, force: true });
+    }
+  });
+
+  // L7 regression: task_stop must let the bash `trap ... TERM` cleanup run
+  // before the process dies. The runner aborts the controller, pi delivers
+  // SIGTERM to the process group first (was: immediate uncatchable SIGKILL), so
+  // the trap fires and its output reaches the task before the graceful exit.
+  // Real child process + real pi bash tool; Unix signal semantics only.
+  it.skipIf(process.platform === 'win32')(
+    'L7: task_stop lets the bash TERM trap run cleanup (SIGTERM→grace, not immediate SIGKILL)',
+    async () => {
+      const dataDir = await mkdtemp(join(tmpdir(), 'local-background-bash-trap-'));
+      try {
+        const service = new LocalBackgroundTaskService({
+          store: new SqliteLocalBackgroundTaskStore(dataDir, () => 61_000),
+          outputStore: new FsLocalTaskOutputStore(dataDir),
+          nowMs: () => 61_000,
+          stopRuntime: stopBackgroundLocalBashTask,
+        });
+        const host = backgroundBashHost(service, dataDir);
+        const command =
+          "trap 'echo CLEANUP-RAN; exit 0' TERM INT; echo started; while true; do sleep 0.2; done";
+
+        const started = await startBackgroundLocalBash({
+          host,
+          parentSession: parentSessionRecord(dataDir),
+          toolCtx: toolContext('session-a'),
+          bashInput: { description: '运行测试命令', command, run_in_background: true },
+          executor: MOVED_LOCAL_BACKGROUND_BASH_EXECUTOR,
+        });
+
+        // Incremental output is persisted while the process runs, so wait for
+        // the shell's first line before stopping and exercising its TERM trap.
+        await waitForTaskOutput(service, started.taskId!, 'started');
+        await service.stop(toolContext('session-a'), started.taskId!, 'user stopped');
+
+        const output = await waitForTaskOutput(service, started.taskId!, 'CLEANUP-RAN');
+        expect(output).toContain('CLEANUP-RAN');
+        const task = await waitForTaskStatus(service, started.taskId!, 'canceled');
+        expect(task).toMatchObject({ kind: 'bash', status: 'canceled' });
+        expect(task.metadata?.bashDetails).toMatchObject({
+          execution: {
+            status: 'canceled', reason: 'canceled', exitCode: 0, cancellationReason: 'user stopped',
+          },
+          processOutput: { interrupted: true, stdout: expect.stringContaining('CLEANUP-RAN') },
+        });
+        const reported = await new LocalTaskOutputTool(service).execute(toolContext('session-a'), {
+          task_id: started.taskId!,
+        });
+        expect(reported.isError).not.toBe(true);
+        expect(reported.details).toMatchObject({ execution: { status: 'canceled', reason: 'canceled' } });
+      } finally {
+        closeLocalRuntimeDb(dataDir);
+        await rm(dataDir, { recursive: true, force: true });
+      }
+    },
+  );
+
+  it('BG-U01: kills a runaway background bash at maxRunMs → failed + TIMEOUT (not canceled)', async () => {
+    const dataDir = await mkdtemp(join(tmpdir(), 'local-background-bash-maxrun-'));
+    try {
+      const service = new LocalBackgroundTaskService({
+        store: new SqliteLocalBackgroundTaskStore(dataDir, () => 51_000),
+        outputStore: new FsLocalTaskOutputStore(dataDir),
+        nowMs: () => 51_000,
+        stopRuntime: stopBackgroundLocalBashTask,
+      });
+      const host = backgroundBashHost(service, dataDir);
+      let aborted = false;
+      // Executor hangs until the watchdog aborts it — mimics a stuck command.
+      const executor: LocalBackgroundBashExecutor = {
+        execute: ({ signal }) =>
+          new Promise((_resolve, reject) => {
+            signal.addEventListener('abort', () => {
+              aborted = true;
+              reject(new Error('aborted'));
+            });
+          }),
+      };
+
+      const started = await startBackgroundLocalBash({
+        host,
+        parentSession: parentSessionRecord(dataDir),
+        toolCtx: toolContext('session-a'),
+        bashInput: { description: '运行测试命令', command: 'sleep 100000', run_in_background: true },
+        executor,
+        maxRunMs: 50,
+      });
+
+      const task = await waitForTaskStatus(service, started.taskId!, 'failed');
+      expect(aborted).toBe(true);
+      expect(task.status).toBe('failed');
+      expect(task.lastError?.code).toBe('TIMEOUT');
+      expect(task.lastError?.message).toContain('maxRunMs');
+      expect(task.metadata?.bashDetails).toMatchObject({
+        execution: { status: 'failed', reason: 'watchdog_timeout', errorCode: 'TIMEOUT' },
+      });
+      await expect(
+        waitForTaskOutput(service, started.taskId!, 'timed out'),
+      ).resolves.toContain('timed out');
+    } finally {
+      closeLocalRuntimeDb(dataDir);
+      await rm(dataDir, { recursive: true, force: true });
+    }
+  });
+
+  it('BG-U03: watchdog is cleared when the command finishes in time (no late false timeout)', async () => {
+    const dataDir = await mkdtemp(join(tmpdir(), 'local-background-bash-maxrun-clear-'));
+    try {
+      const service = new LocalBackgroundTaskService({
+        store: new SqliteLocalBackgroundTaskStore(dataDir, () => 52_000),
+        outputStore: new FsLocalTaskOutputStore(dataDir),
+        nowMs: () => 52_000,
+      });
+      const host = backgroundBashHost(service, dataDir);
+      const executor: LocalBackgroundBashExecutor = {
+        execute: async ({ command }) => ({ text: `ran:${command}` }),
+      };
+
+      const started = await startBackgroundLocalBash({
+        host,
+        parentSession: parentSessionRecord(dataDir),
+        toolCtx: toolContext('session-a'),
+        bashInput: { description: '运行测试命令', command: 'echo quick', run_in_background: true },
+        executor,
+        maxRunMs: 40,
+      });
+
+      const task = await waitForTaskStatus(service, started.taskId!, 'succeeded');
+      expect(task.status).toBe('succeeded');
+      // Give any un-cleared watchdog a chance to (wrongly) fire, then re-read.
+      await new Promise((resolve) => setTimeout(resolve, 80));
+      const after = await service.get(toolContext('session-a'), started.taskId!);
+      expect(after?.status).toBe('succeeded');
+    } finally {
+      closeLocalRuntimeDb(dataDir);
+      await rm(dataDir, { recursive: true, force: true });
+    }
+  });
+
+  it('BG-U08: user stop still yields canceled (not TIMEOUT) even with a maxRunMs set', async () => {
+    const dataDir = await mkdtemp(join(tmpdir(), 'local-background-bash-stop-vs-maxrun-'));
+    try {
+      const service = new LocalBackgroundTaskService({
+        store: new SqliteLocalBackgroundTaskStore(dataDir, () => 53_000),
+        outputStore: new FsLocalTaskOutputStore(dataDir),
+        nowMs: () => 53_000,
+        stopRuntime: stopBackgroundLocalBashTask,
+      });
+      const host = backgroundBashHost(service, dataDir);
+      const executor: LocalBackgroundBashExecutor = {
+        execute: ({ signal }) =>
+          new Promise((_resolve, reject) => {
+            signal.addEventListener('abort', () => reject(new Error('aborted')));
+          }),
+      };
+
+      const started = await startBackgroundLocalBash({
+        host,
+        parentSession: parentSessionRecord(dataDir),
+        toolCtx: toolContext('session-a'),
+        bashInput: { description: '运行测试命令', command: 'sleep 100000', run_in_background: true },
+        executor,
+        maxRunMs: 60_000,
+      });
+
+      await service.stop(toolContext('session-a'), started.taskId!, 'user stopped');
+      const task = await waitForTaskStatus(service, started.taskId!, 'canceled');
+      expect(task.status).toBe('canceled');
+      expect(task.lastError?.code).not.toBe('TIMEOUT');
+      // Wait for the runner's async output append to settle before cleanup so
+      // the SQLite dir is quiescent (avoids an ENOTEMPTY rmdir race).
+      await waitForTaskOutput(service, started.taskId!, 'Background bash canceled');
+    } finally {
+      closeLocalRuntimeDb(dataDir);
+      await rm(dataDir, { recursive: true, force: true });
+    }
+  });
+
+  it('BG-U07: a fast executor failure is BASH_FAILED, not a TIMEOUT (watchdog stays clear)', async () => {
+    const dataDir = await mkdtemp(join(tmpdir(), 'local-background-bash-fail-'));
+    try {
+      const service = new LocalBackgroundTaskService({
+        store: new SqliteLocalBackgroundTaskStore(dataDir, () => 54_000),
+        outputStore: new FsLocalTaskOutputStore(dataDir),
+        nowMs: () => 54_000,
+      });
+      const host = backgroundBashHost(service, dataDir);
+      const executor: LocalBackgroundBashExecutor = {
+        execute: async () => {
+          throw new Error('boom');
+        },
+      };
+
+      const started = await startBackgroundLocalBash({
+        host,
+        parentSession: parentSessionRecord(dataDir),
+        toolCtx: toolContext('session-a'),
+        bashInput: { description: '运行测试命令', command: 'false', run_in_background: true },
+        executor,
+        maxRunMs: 60_000,
+      });
+
+      const task = await waitForTaskStatus(service, started.taskId!, 'failed');
+      expect(task.lastError?.code).toBe('BASH_FAILED');
+      expect(task.lastError?.code).not.toBe('TIMEOUT');
+      // Give a (wrongly-armed) watchdog time to misfire, then confirm no flip.
+      await new Promise((resolve) => setTimeout(resolve, 30));
+      const after = await service.get(toolContext('session-a'), started.taskId!);
+      expect(after?.status).toBe('failed');
+    } finally {
+      closeLocalRuntimeDb(dataDir);
+      await rm(dataDir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('resolveBackgroundBashMaxRunMs', () => {
+  it('defaults to the 30-min ceiling when no timeout is given', () => {
+    expect(resolveBackgroundBashMaxRunMs(undefined)).toBe(DEFAULT_BACKGROUND_BASH_MAX_RUN_MS);
+    expect(DEFAULT_BACKGROUND_BASH_MAX_RUN_MS).toBe(30 * 60 * 1000);
+  });
+
+  it('never undercuts an explicit longer timeout (raises the ceiling to match)', () => {
+    // 60-min explicit timeout must not be killed by the 30-min default.
+    expect(resolveBackgroundBashMaxRunMs(60 * 60)).toBe(60 * 60 * 1000);
+  });
+
+  it('keeps the default ceiling when the explicit timeout is shorter', () => {
+    expect(resolveBackgroundBashMaxRunMs(60)).toBe(DEFAULT_BACKGROUND_BASH_MAX_RUN_MS);
+  });
+
+  it('treats 0 / negative timeout as "no explicit value" → default ceiling', () => {
+    expect(resolveBackgroundBashMaxRunMs(0)).toBe(DEFAULT_BACKGROUND_BASH_MAX_RUN_MS);
+    expect(resolveBackgroundBashMaxRunMs(-5)).toBe(DEFAULT_BACKGROUND_BASH_MAX_RUN_MS);
+  });
+
+  it('caps explicit timeouts at the maximum delay supported by Node timers', () => {
+    expect(resolveBackgroundBashMaxRunMs(2_147_484)).toBe(MAX_BACKGROUND_BASH_MAX_RUN_MS);
+    expect(MAX_BACKGROUND_BASH_MAX_RUN_MS).toBe(2_147_483_647);
+  });
+});
+
+describe('reconcileStartupLostTasks — idempotence (learned from kimi reconcile.test)', () => {
+  it('a second reconcile pass is a no-op: no re-transition, no duplicate completion events', async () => {
+    const dataDir = await mkdtemp(join(tmpdir(), 'local-background-reconcile-idem-'));
+    try {
+      const store = new SqliteLocalBackgroundTaskStore(dataDir, () => 61_000);
+      const events: string[] = [];
+      const trackingStore = taskStoreWithPatch(store, async () => undefined);
+      // Wrap appendEvent to count completion emissions for the orphan.
+      const originalAppend = trackingStore.appendEvent.bind(trackingStore);
+      trackingStore.appendEvent = async (event) => {
+        if (event.taskId === 'orphan' && event.type === 'completed') events.push(event.type);
+        return originalAppend(event);
+      };
+      const service = new LocalBackgroundTaskService({
+        store: trackingStore,
+        outputStore: new FsLocalTaskOutputStore(dataDir),
+        nowMs: () => 62_000,
+      });
+      await store.create(taskRecord('orphan', 'session-a', { status: 'running', createdAt: 1_000 }));
+
+      const first = await service.reconcileStartupLostTasks({ reason: 'restarted' });
+      expect(first.map((t) => t.taskId)).toEqual(['orphan']);
+      expect(first[0]!.status).toBe('lost');
+
+      const second = await service.reconcileStartupLostTasks({ reason: 'restarted' });
+      expect(second).toEqual([]); // already terminal → not re-collected
+      expect(events).toEqual(['completed']); // exactly one completion event
+    } finally {
+      closeLocalRuntimeDb(dataDir);
+      await rm(dataDir, { recursive: true, force: true });
+    }
+  });
+});
diff --git a/packages/local-runtime/test/unit/local-background-task-stop-races.test.ts b/packages/local-runtime/test/unit/local-background-task-stop-races.test.ts
new file mode 100644
index 00000000..afb6b805
--- /dev/null
+++ b/packages/local-runtime/test/unit/local-background-task-stop-races.test.ts
@@ -0,0 +1,119 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { describe, expect, it } from 'vitest';
+import { LocalTaskStopTool } from '@mavis/agent-tools/desktop';
+
+import { LocalBackgroundTaskService } from '../../src/background-task/service.js';
+import {
+  FsLocalTaskOutputStore,
+  SqliteLocalBackgroundTaskStore,
+} from '../../src/background-task/store.js';
+import { closeLocalRuntimeDb } from '../../src/persistence/db.js';
+import { taskRecord, taskStoreWithPatch, toolContext } from './background-task-test-helpers.js';
+
+describe('local background task stop concurrency', () => {
+  it.each(['running', 'succeeded', 'failed'] as const)(
+    'reports stop failure without overwriting a concurrent %s outcome',
+    async (outcome) => {
+      const dataDir = await mkdtemp(join(tmpdir(), 'local-background-stop-failure-'));
+      try {
+        const store = new SqliteLocalBackgroundTaskStore(dataDir);
+        const service = new LocalBackgroundTaskService({
+          store,
+          outputStore: new FsLocalTaskOutputStore(dataDir),
+          stopRuntime: async () => {
+            if (outcome !== 'running')
+              await service.patch('stop-failure', {
+                status: outcome,
+                endedAt: 10,
+                lastError:
+                  outcome === 'failed'
+                    ? { code: 'BASH_FAILED', message: 'command failed' }
+                    : undefined,
+              });
+            throw new Error('runtime cleanup failed');
+          },
+        });
+        await store.create(
+          taskRecord('stop-failure', 'session-a', { kind: 'bash', status: 'running' }),
+        );
+        const result = await new LocalTaskStopTool(service).execute(toolContext('session-a'), {
+          task_id: 'stop-failure',
+        });
+        expect(result.isError).toBe(true);
+        expect(result.text).toContain('runtime cleanup failed');
+        expect(result.text).toContain('Process cleanup could not be confirmed');
+        expect(result.details).toMatchObject({
+          status: outcome === 'running' ? 'canceled' : outcome,
+          stopError: { code: 'TASK_STOP_FAILED', message: 'runtime cleanup failed' },
+        });
+        const persisted = await store.get('stop-failure');
+        expect(persisted?.metadata?.stopError).toMatchObject({ code: 'TASK_STOP_FAILED' });
+        if (outcome === 'failed')
+          expect(persisted?.lastError).toEqual({ code: 'BASH_FAILED', message: 'command failed' });
+        const repeated = await new LocalTaskStopTool(service).execute(toolContext('session-a'), {
+          task_id: 'stop-failure',
+        });
+        expect(repeated.isError).toBe(true);
+      } finally {
+        closeLocalRuntimeDb(dataDir);
+        await rm(dataDir, { recursive: true, force: true });
+      }
+    },
+  );
+
+  it('coalesces concurrent task_stop calls into one runtime stop and one completion event', async () => {
+    const dataDir = await mkdtemp(join(tmpdir(), 'local-background-stop-race-'));
+    try {
+      const store = new SqliteLocalBackgroundTaskStore(dataDir, () => 70_000);
+      const trackingStore = taskStoreWithPatch(store, async () => undefined);
+      const appendEvent = trackingStore.appendEvent.bind(trackingStore);
+      let completedEvents = 0;
+      trackingStore.appendEvent = async (event) => {
+        if (event.type === 'completed') completedEvents += 1;
+        await appendEvent(event);
+      };
+      let stopCalls = 0;
+      let reportStopEntered!: () => void;
+      const stopEntered = new Promise<void>((resolve) => {
+        reportStopEntered = resolve;
+      });
+      let releaseStop!: () => void;
+      const stopGate = new Promise<void>((resolve) => {
+        releaseStop = resolve;
+      });
+      const service = new LocalBackgroundTaskService({
+        store: trackingStore,
+        outputStore: new FsLocalTaskOutputStore(dataDir),
+        nowMs: () => 70_000,
+        stopRuntime: async () => {
+          stopCalls += 1;
+          reportStopEntered();
+          await stopGate;
+        },
+      });
+      await store.create(taskRecord('running-task', 'session-a', { status: 'running' }));
+
+      const first = service.stop('running-task', 'reason-a');
+      await stopEntered;
+      const second = service.stop('running-task', 'reason-b');
+      await Promise.resolve();
+      expect(stopCalls).toBe(1);
+
+      releaseStop();
+      const [firstResult, secondResult] = await Promise.all([first, second]);
+      expect(firstResult).toMatchObject({
+        status: 'canceled',
+        lastError: { code: 'TASK_CANCELED', message: 'reason-a' },
+      });
+      expect(secondResult).toEqual(firstResult);
+      expect(stopCalls).toBe(1);
+      expect(completedEvents).toBe(1);
+    } finally {
+      closeLocalRuntimeDb(dataDir);
+      await rm(dataDir, { recursive: true, force: true });
+    }
+  });
+});
diff --git a/packages/tui/src/tui/transcript/presentation/tool-summary.ts b/packages/tui/src/tui/transcript/presentation/tool-summary.ts
index 8e93f2e2..182adfb2 100644
--- a/packages/tui/src/tui/transcript/presentation/tool-summary.ts
+++ b/packages/tui/src/tui/transcript/presentation/tool-summary.ts
@@ -39,6 +39,7 @@ export function formatTuiToolSummary(value: string): string {
           typeof candidate === 'string' && Boolean(candidate.trim()),
       );
       if (typeof parsed.command === 'string' && parsed.command.trim()) {
+        if (typeof description === 'string' && description.trim()) return firstLine(description);
         const command = firstLine(parsed.command);
         return scope ? `${command} · in ${firstLine(scope)}` : command;
       }
diff --git a/packages/tui/src/tui/transcript/tool-evidence.ts b/packages/tui/src/tui/transcript/tool-evidence.ts
index 5b708e02..3358558d 100644
--- a/packages/tui/src/tui/transcript/tool-evidence.ts
+++ b/packages/tui/src/tui/transcript/tool-evidence.ts
@@ -20,6 +20,7 @@ export interface TranscriptToolEvidence {
 }
 
 interface ToolArguments {
+  readonly description?: string;
   readonly path?: string;
   readonly query?: string;
   readonly taskId?: string;
@@ -163,7 +164,7 @@ function presentBackgroundBashEvidence(
       : { lines: [] as readonly string[] };
   const taskId = BASH_BACKGROUND_TASK_ID_PATTERN.exec(cell.detail ?? '')?.[1];
   return {
-    ...(taskId ? { summary: taskId } : {}),
+    summary: [parseToolArguments(cell.content).description, taskId].filter(Boolean).join(' · '),
     lines: [...commandEvidence.lines, ...failureEvidence.lines],
     handlesDetail: true,
   };
@@ -222,7 +223,10 @@ function presentShellEvidence(
   }
 
   return {
-    summary: composeShellSummary(command, shellOutputSummary(output.length, cell.status)),
+    summary: composeShellSummary(
+      parseToolArguments(cell.content).description || command,
+      shellOutputSummary(output.length, cell.status),
+    ),
     lines,
     handlesDetail: true,
   };
@@ -371,6 +375,7 @@ function parseToolArguments(content: string): ToolArguments {
   if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
   const record = value as Readonly<Record<string, unknown>>;
   return {
+    description: summarizeShellCommand(stringValue(record.description)),
     path: stringValue(record.path) ?? stringValue(record.filePath) ?? stringValue(record.file_path),
     query: stringValue(record.query) ?? stringValue(record.pattern),
     taskId: stringValue(record.task_id),
diff --git a/packages/tui/test/unit/tui-tool-evidence.test.ts b/packages/tui/test/unit/tui-tool-evidence.test.ts
new file mode 100644
index 00000000..4c826fc5
--- /dev/null
+++ b/packages/tui/test/unit/tui-tool-evidence.test.ts
@@ -0,0 +1,264 @@
+import { stripVTControlCharacters } from 'node:util';
+
+import { describe, expect, it } from 'vitest';
+
+import { renderTuiStructuredPreview } from '../../src/tui/transcript/presentation/structured-preview.js';
+import { syntaxLanguageForPath } from '../../src/tui/transcript/presentation/syntax-highlight.js';
+import { createTranscriptCell } from '../../src/tui/transcript/model.js';
+import {
+  resolveTranscriptToolDefinition,
+  type TranscriptToolDefinition,
+} from '../../src/tui/transcript/tool-definitions.js';
+import { presentTranscriptToolEvidence } from '../../src/tui/transcript/tool-evidence.js';
+import { MINIMAX_CODE_DARK_THEME, MINIMAX_CODE_LIGHT_THEME } from '../../src/tui/theme/palettes.js';
+import {
+  applyTuiRenderTheme,
+  createTuiChalk,
+  getTuiThemeSnapshot,
+  tuiColors,
+} from '../../src/tui/theme/runtime.js';
+
+function definitionFor(title: string): TranscriptToolDefinition {
+  const definition = resolveTranscriptToolDefinition(title);
+  if (!definition) throw new Error(`Missing tool definition for ${title}`);
+  return definition;
+}
+
+describe('transcript tool evidence', () => {
+  it('uses the command purpose as its summary and keeps the executable source in details', () => {
+    const evidence = presentTranscriptToolEvidence(createTranscriptCell({
+      id: 'bash-purpose', kind: 'tool', status: 'succeeded', title: 'bash',
+      content: JSON.stringify({ command: 'pnpm test', description: '验证 Bash 回归' }),
+      detail: 'passed', createdAtMs: 1,
+    }), definitionFor('bash'), { width: 80, prefix: '    ', displayMode: 'preview' });
+    expect(evidence.summary).toContain('验证 Bash 回归');
+    expect(stripVTControlCharacters(evidence.lines.join('\n'))).toContain('$ pnpm test');
+  });
+  it('renders a highlighted shell command separately from its quieter output', () => {
+    const evidence = presentTranscriptToolEvidence(
+      createTranscriptCell({
+        id: 'shell',
+        kind: 'tool',
+        status: 'succeeded',
+        title: 'bash',
+        content: JSON.stringify({ command: 'if test -f package.json; then echo "ready"; fi' }),
+        detail: 'package.json\nready',
+        createdAtMs: 1,
+      }),
+      definitionFor('bash'),
+      { width: 80, prefix: '    ', displayMode: 'preview' },
+    );
+
+    const plain = stripVTControlCharacters(evidence.lines.join('\n'));
+    expect(evidence.summary).toBe('if test -f package.json; then echo "ready"; fi · 2 output lines');
+    expect(plain).toContain('$ if test -f package.json; then echo "ready"; fi');
+    expect(plain).toContain('│ package.json');
+    expect(plain).toContain('│ ready');
+    expect(syntaxLanguageForPath('script.sh')).toBe('bash');
+  });
+
+  it('uses executable-focused shell highlighting in expanded transcript evidence', () => {
+    const original = getTuiThemeSnapshot();
+    const originalPalette =
+      original.appearance === 'light' ? MINIMAX_CODE_LIGHT_THEME : MINIMAX_CODE_DARK_THEME;
+    applyTuiRenderTheme(MINIMAX_CODE_DARK_THEME, 3);
+
+    try {
+      const evidence = presentTranscriptToolEvidence(
+        createTranscriptCell({
+          id: 'shell-executable-highlights',
+          kind: 'tool',
+          status: 'succeeded',
+          title: 'bash',
+          content: JSON.stringify({ command: 'cp source target && rm target | mv backup restored' }),
+          detail: undefined,
+          createdAtMs: 1,
+        }),
+        definitionFor('bash'),
+        { width: 80, prefix: '    ', displayMode: 'expanded' },
+      );
+      const rendered = evidence.lines.join('\n');
+      const ansi = createTuiChalk({ colorLevel: 3 });
+
+      expect(rendered).toContain(ansi.bold.hex(tuiColors.accent)('cp'));
+      expect(rendered).toContain(ansi.bold.hex(tuiColors.accent)('rm'));
+      expect(rendered).toContain(ansi.bold.hex(tuiColors.accent)('mv'));
+    } finally {
+      applyTuiRenderTheme(originalPalette, original.colorLevel);
+    }
+  });
+
+  it('keeps only the first line of a multiline shell command in the summary', () => {
+    const evidence = presentTranscriptToolEvidence(
+      createTranscriptCell({
+        id: 'shell-multiline',
+        kind: 'tool',
+        status: 'succeeded',
+        title: 'bash',
+        content: JSON.stringify({ command: "git commit -F - <<'EOF'\nsubject line\nEOF" }),
+        detail: undefined,
+        createdAtMs: 1,
+      }),
+      definitionFor('bash'),
+      { width: 80, prefix: '    ', displayMode: 'collapsed' },
+    );
+
+    expect(evidence.summary).toBe("git commit -F - <<'EOF'… · no output");
+    expect(evidence.summary).not.toContain('subject line');
+  });
+
+  it('syntax-highlights Read output from the requested file type with a stable line gutter', () => {
+    const evidence = presentTranscriptToolEvidence(
+      createTranscriptCell({
+        id: 'read',
+        kind: 'tool',
+        status: 'succeeded',
+        title: 'read',
+        content: JSON.stringify({ path: 'src/server.ts', offset: 12 }),
+        detail: 'const port = 3000;\nexport { port };',
+        createdAtMs: 1,
+      }),
+      definitionFor('read'),
+      { width: 80, prefix: '    ', displayMode: 'preview' },
+    );
+
+    const plain = stripVTControlCharacters(evidence.lines.join('\n'));
+    expect(evidence.summary).toBe('src/server.ts · 2 lines');
+    expect(plain).toContain('12 │ const port = 3000;');
+    expect(plain).toContain('13 │ export { port };');
+    expect(syntaxLanguageForPath('src/server.ts')).toBe('typescript');
+  });
+
+  it('keeps the newest shell output while running and head plus tail after completion', () => {
+    const output = Array.from({ length: 8 }, (_, index) => `line-${index + 1}`).join('\n');
+    const running = presentTranscriptToolEvidence(
+      createTranscriptCell({
+        id: 'running',
+        kind: 'tool',
+        status: 'running',
+        title: 'bash',
+        content: JSON.stringify({ command: 'pnpm test' }),
+        detail: output,
+        createdAtMs: 1,
+      }),
+      definitionFor('bash'),
+      { width: 80, prefix: '    ', displayMode: 'preview' },
+    );
+    const completed = presentTranscriptToolEvidence(
+      createTranscriptCell({
+        id: 'completed',
+        kind: 'tool',
+        status: 'succeeded',
+        title: 'bash',
+        content: JSON.stringify({ command: 'pnpm test' }),
+        detail: output,
+        createdAtMs: 1,
+      }),
+      definitionFor('bash'),
+      { width: 80, prefix: '    ', displayMode: 'preview' },
+    );
+
+    const runningPlain = stripVTControlCharacters(running.lines.join('\n'));
+    expect(runningPlain).not.toContain('line-1');
+    expect(runningPlain).toContain('line-8');
+    expect(runningPlain).toContain('5 earlier lines');
+
+    const completedPlain = stripVTControlCharacters(completed.lines.join('\n'));
+    expect(completedPlain).toContain('line-1');
+    expect(completedPlain).toContain('line-8');
+    expect(completedPlain).toContain('5 lines hidden');
+  });
+
+  it('summarizes search results and shows a small path sample', () => {
+    const evidence = presentTranscriptToolEvidence(
+      createTranscriptCell({
+        id: 'grep',
+        kind: 'tool',
+        status: 'succeeded',
+        title: 'grep',
+        content: JSON.stringify({ pattern: 'renderTool', path: 'packages/tui' }),
+        detail: [
+          'packages/tui/src/a.ts:12:renderTool()',
+          'packages/tui/src/b.ts:4:renderTool()',
+          'packages/tui/src/c.ts:9:renderTool()',
+          'packages/tui/src/d.ts:2:renderTool()',
+        ].join('\n'),
+        createdAtMs: 1,
+      }),
+      definitionFor('grep'),
+      { width: 80, prefix: '    ', displayMode: 'preview' },
+    );
+
+    const plain = stripVTControlCharacters(evidence.lines.join('\n'));
+    expect(evidence.summary).toBe('renderTool · 4 matches');
+    expect(plain).toContain('packages/tui/src/a.ts:12');
+    expect(plain).toContain('1 more match');
+    expect(plain).not.toContain('packages/tui/src/d.ts:2');
+  });
+
+  it('keeps failed Read output as an error instead of pretending it is source code', () => {
+    const evidence = presentTranscriptToolEvidence(
+      createTranscriptCell({
+        id: 'read-failed',
+        kind: 'tool',
+        status: 'failed',
+        title: 'read',
+        content: JSON.stringify({ path: 'src/missing.ts' }),
+        detail: 'ENOENT: file not found',
+        createdAtMs: 1,
+      }),
+      definitionFor('read'),
+      { width: 80, prefix: '    ', displayMode: 'preview' },
+    );
+
+    const plain = stripVTControlCharacters(evidence.lines.join('\n'));
+    expect(evidence.summary).toBe('src/missing.ts');
+    expect(plain).toContain('× ENOENT: file not found');
+    expect(plain).not.toContain('1 │');
+  });
+
+  it('pretty-prints structured fallback results without dumping one-line JSON', () => {
+    const evidence = presentTranscriptToolEvidence(
+      createTranscriptCell({
+        id: 'mcp',
+        kind: 'tool',
+        status: 'succeeded',
+        title: 'mcp__repo__inspect',
+        content: JSON.stringify({ path: 'src' }),
+        detail: JSON.stringify({ files: 12, status: 'ready' }),
+        createdAtMs: 1,
+      }),
+      definitionFor('mcp__repo__inspect'),
+      { width: 80, prefix: '    ', displayMode: 'expanded' },
+    );
+
+    const plain = stripVTControlCharacters(evidence.lines.join('\n'));
+    expect(plain).toContain('│ {');
+    expect(plain).toContain('"files": 12');
+    expect(plain).toContain('"status": "ready"');
+    expect(plain).not.toContain('{"files":12');
+  });
+
+  it('syntax-highlights file structured previews instead of painting the body uniformly', () => {
+    const rendered = renderTuiStructuredPreview(
+      {
+        schemaVersion: 1,
+        state: 'applied',
+        blocks: [
+          {
+            kind: 'file',
+            path: 'src/config.ts',
+            content: 'export const enabled = true;',
+            lineCount: 1,
+            truncated: false,
+          },
+        ],
+      },
+      80,
+      { maxBodyLines: 3 },
+    ).join('\n');
+
+    expect(stripVTControlCharacters(rendered)).toContain('1 export const enabled = true;');
+    expect(syntaxLanguageForPath('src/config.ts')).toBe('typescript');
+  });
+});
diff --git a/packages/tui/test/unit/tui-tool-summary.test.ts b/packages/tui/test/unit/tui-tool-summary.test.ts
new file mode 100644
index 00000000..b3c478da
--- /dev/null
+++ b/packages/tui/test/unit/tui-tool-summary.test.ts
@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest';
+import { stripVTControlCharacters } from 'node:util';
+import { formatTuiToolSummary } from '../../src/tui/transcript/presentation/tool-summary.js';
+import { TranscriptView } from '../../src/tui/transcript/view.js';
+import { createTranscriptCell } from '../../src/tui/transcript/model.js';
+
+describe('tool operation summaries', () => {
+  it.each([
+    [{ pattern: 'watchStream', path: 'src' }, 'watchStream in src'],
+    [{ query: 'watchStream', file_path: 'src/app.ts' }, 'watchStream in src/app.ts'],
+    [{ command: 'pnpm test', cwd: 'packages/tui' }, 'pnpm test · in packages/tui'],
+    [{ command: 'pnpm test', description: '验证 Bash 回归' }, '验证 Bash 回归'],
+    [{ path: 'src/app.ts' }, 'src/app.ts'],
+    [{ pattern: '\x1b[31m中文\x1b[0m\nsecond', path: 'src' }, '中文 in src'],
+  ])('shows the operation and its scope: %j', (input, expected) => {
+    expect(formatTuiToolSummary(JSON.stringify(input))).toBe(expected);
+  });
+
+  it('retains an earlier failed attempt when the same read later succeeds', () => {
+    const cells = ['failed', 'succeeded'].map((status, index) => createTranscriptCell({
+      id: `read-${index}`, kind: 'tool', title: 'read',
+      status: status === 'failed' ? 'failed' : 'succeeded',
+      content: JSON.stringify({ path: 'src/app.ts' }),
+      detail: index === 0 ? 'Permission denied' : 'Read succeeded',
+      turnId: 'turn', createdAtMs: index,
+    }));
+    const view = new TranscriptView(() => cells);
+    const compact = stripVTControlCharacters(view.render(80).join('\n'));
+    expect(compact).toContain('Read 1 file');
+    expect(compact).toContain('1 failed');
+    expect(compact).toContain('2 calls');
+    view.toggleDetailMode();
+    const detailed = stripVTControlCharacters(view.render(80).join('\n'));
+    expect(detailed).toContain('Permission denied');
+    expect(detailed).toContain('Read succeeded');
+  });
+
+  it('keeps different queries and tools on the same path distinct', () => {
+    const cells = [
+      { title: 'read', input: { path: 'src' } },
+      { title: 'grep', input: { path: 'src', pattern: 'first' } },
+      { title: 'grep', input: { path: 'src', pattern: 'second' } },
+    ].map(({ title, input }, index) => createTranscriptCell({
+      id: `tool-${index}`, kind: 'tool', title, status: 'succeeded',
+      content: JSON.stringify(input), turnId: 'turn', createdAtMs: index,
+    }));
+    const view = new TranscriptView(() => cells);
+    expect(stripVTControlCharacters(view.render(80).join('\n'))).toContain('Explored 3 operations');
+    view.toggleDetailMode();
+    const detailed = stripVTControlCharacters(view.render(80).join('\n'));
+    expect(detailed).toContain('first in src');
+    expect(detailed).toContain('second in src');
+  });
+});
diff --git a/release/public-source.json b/release/public-source.json
index 9748e819..826bcf0c 100644
--- a/release/public-source.json
+++ b/release/public-source.json
@@ -337,6 +337,10 @@
     "packages/agent-tools/src/desktop/host-trash-executor.ts",
     "packages/agent-tools/src/desktop/index.ts",
     "packages/agent-tools/src/desktop/local-ask-user.ts",
+    "packages/agent-tools/src/desktop/local-bash-contract.ts",
+    "packages/agent-tools/src/desktop/local-bash-input.ts",
+    "packages/agent-tools/src/desktop/local-bash-result.ts",
+    "packages/agent-tools/src/desktop/local-bash-timing.ts",
     "packages/agent-tools/src/desktop/local-browser.ts",
     "packages/agent-tools/src/desktop/local-code-review.ts",
     "packages/agent-tools/src/desktop/local-feature-enable.ts",
@@ -402,6 +406,9 @@
     "packages/agent-tools/src/shared/rg-sensitive.ts",
     "packages/agent-tools/src/shared/web-search.ts",
     "packages/agent-tools/src/shared/write-capture.ts",
+    "packages/agent-tools/test/desktop/local-bash-output.test.ts",
+    "packages/agent-tools/test/desktop/local-bash-timeout.test.ts",
+    "packages/agent-tools/test/desktop/local-task-output-polling.test.ts",
     "packages/browser-core/package.json",
     "packages/browser-core/src/browser-action-artifacts.ts",
     "packages/browser-core/src/browser-action-helpers.ts",
@@ -796,6 +803,7 @@
     "packages/local-runtime-v2/src/service/agent/storage/legacy-custom-identity-receipt.ts",
     "packages/local-runtime-v2/src/service/agent/storage/runtime-index.ts",
     "packages/local-runtime-v2/src/service/background-bash/contracts.ts",
+    "packages/local-runtime-v2/src/service/background-bash/executor.test.ts",
     "packages/local-runtime-v2/src/service/background-bash/executor.ts",
     "packages/local-runtime-v2/src/service/background-bash/index.ts",
     "packages/local-runtime-v2/src/service/background-bash/initialize.ts",
@@ -2117,6 +2125,7 @@
     "packages/local-runtime/src/background-task/bash-runner-lifecycle.ts",
     "packages/local-runtime/src/background-task/bash-runner-limits.ts",
     "packages/local-runtime/src/background-task/bash-runner.ts",
+    "packages/local-runtime/src/background-task/bash-task-settlement.ts",
     "packages/local-runtime/src/background-task/checkpoint-snapshot.ts",
     "packages/local-runtime/src/background-task/child-bash-lifecycle.ts",
     "packages/local-runtime/src/background-task/conversation-delivery.ts",
@@ -2134,6 +2143,7 @@
     "packages/local-runtime/src/background-task/store.ts",
     "packages/local-runtime/src/background-task/subagent-task-row.ts",
     "packages/local-runtime/src/background-task/task-query.ts",
+    "packages/local-runtime/src/background-task/task-stop.ts",
     "packages/local-runtime/src/background-task/task-waiter-registry.ts",
     "packages/local-runtime/src/background-task/terminal.ts",
     "packages/local-runtime/src/background-task/turn-id.ts",
@@ -2645,6 +2655,9 @@
     "packages/local-runtime/test/unit/content-safety-api-v2.test.ts",
     "packages/local-runtime/test/unit/content-safety-turn-v2.test.ts",
     "packages/local-runtime/test/unit/error-reporting-privacy.test.ts",
+    "packages/local-runtime/test/unit/local-background-bash-review-regressions.test.ts",
+    "packages/local-runtime/test/unit/local-background-bash-runner.test.ts",
+    "packages/local-runtime/test/unit/local-background-task-stop-races.test.ts",
     "packages/local-runtime/test/unit/local-background-task-task-output-polling-reminder.test.ts",
     "packages/local-runtime/test/unit/local-memory-edit-literal.test.ts",
     "packages/local-runtime/test/unit/local-native-tools.test.ts",
@@ -3291,7 +3304,9 @@
     "packages/tui/test/unit/tui-terminal-image-paste.test.ts",
     "packages/tui/test/unit/tui-terminal-text-paste.test.ts",
     "packages/tui/test/unit/tui-thinking-preview.test.ts",
+    "packages/tui/test/unit/tui-tool-evidence.test.ts",
     "packages/tui/test/unit/tui-tool-preview-diff-omitted.test.ts",
+    "packages/tui/test/unit/tui-tool-summary.test.ts",
     "packages/tui/test/unit/tui-transcript-presentation.test.ts",
     "packages/tui/test/unit/tui-transcript-view.test.ts",
     "packages/tui/test/unit/tui-workspace-status-line.test.ts",
diff --git a/test/vitest-suites.json b/test/vitest-suites.json
index 5bc27008..c6771c48 100644
--- a/test/vitest-suites.json
+++ b/test/vitest-suites.json
@@ -176,7 +176,16 @@
       "packages/tui/test/unit/tui/theme/palettes.test.ts",
       "packages/tui/test/unit/tui/theme/runtime.test.ts",
       "packages/tui/test/unit/tui-plugin-mentions.test.ts",
-      "packages/local-runtime-v2/src/service/turn-system/agent-host/assembly/local-turn-plugin-capabilities.test.ts"
+      "packages/local-runtime-v2/src/service/turn-system/agent-host/assembly/local-turn-plugin-capabilities.test.ts",
+      "packages/agent-tools/test/desktop/local-bash-output.test.ts",
+      "packages/agent-tools/test/desktop/local-bash-timeout.test.ts",
+      "packages/agent-tools/test/desktop/local-task-output-polling.test.ts",
+      "packages/local-runtime/test/unit/local-background-bash-runner.test.ts",
+      "packages/local-runtime/test/unit/local-background-bash-review-regressions.test.ts",
+      "packages/local-runtime/test/unit/local-background-task-stop-races.test.ts",
+      "packages/local-runtime-v2/src/service/background-bash/executor.test.ts",
+      "packages/tui/test/unit/tui-tool-evidence.test.ts",
+      "packages/tui/test/unit/tui-tool-summary.test.ts"
     ],
     "status-contract": [
       "packages/tui/test/unit/tui-build-mode-contract.test.ts"
diff --git a/third_party/pi-mono/MINIMAX_CHANGES.md b/third_party/pi-mono/MINIMAX_CHANGES.md
index d81c2b27..391ec23a 100644
--- a/third_party/pi-mono/MINIMAX_CHANGES.md
+++ b/third_party/pi-mono/MINIMAX_CHANGES.md
@@ -13,6 +13,14 @@ This directory vendors `pi-mono` as source so MiniMax can patch, validate, and s
 
 No upstream source files are changed in the baseline import.
 
+### 2026-09-23 — preserve Bash execution facts and bounded output
+
+- Affected package: `packages/coding-agent` (`@earendil-works/pi-coding-agent`), Bash execution, child-process observation, and output accumulation.
+- Change: require exit code zero for success; preserve signals, cancellation reasons, timeout deadlines, and partial output in structured success and failure results. Add an optional original head-and-tail preview and host-owned persistence so managed commands use one complete log. Report persistence failures separately from the process outcome.
+- The existing exit-code-only helper and default tail preview remain compatible. Process cleanup and command timers retain their existing lifecycle.
+- Provenance: shared MiniMax Bash implementation, adapted to the standalone source distribution. Existing upstream notices and licenses apply; no new dependency is introduced. Upstream PR: not opened.
+- Regression coverage: the declared local Bash output, timeout, background executor, runner, stop-race, and child-lifecycle tests exercise the vendored implementation through its product consumers. Vendored upstream suites remain outside this distribution's verification; real-model and Windows acceptance are separate.
+
 ### 2026-09-21 — report why the edit unified patch was omitted
 
 - Reason: the unified patch is a second, independently timed Myers run over the same input as the display diff. When only that run ran out of time, `details` held a diff, no patch, and no `diffOmitted` — consumers could not tell an omitted patch apart from a tool that never produces one.
diff --git a/third_party/pi-mono/packages/coding-agent/src/core/tools/bash.ts b/third_party/pi-mono/packages/coding-agent/src/core/tools/bash.ts
index bca3b8e7..0c029092 100644
--- a/third_party/pi-mono/packages/coding-agent/src/core/tools/bash.ts
+++ b/third_party/pi-mono/packages/coding-agent/src/core/tools/bash.ts
@@ -8,7 +8,7 @@ import { type Static, Type } from "typebox";
 import { keyHint } from "../../modes/interactive/components/keybinding-hints.ts";
 import { truncateToVisualLines } from "../../modes/interactive/components/visual-truncate.ts";
 import { theme } from "../../modes/interactive/theme/theme.ts";
-import { waitForChildProcess } from "../../utils/child-process.ts";
+import { waitForChildProcess, waitForChildProcessExit } from "../../utils/child-process.ts";
 import {
 	armParentDeathGuard,
 	getShellConfig,
@@ -20,7 +20,7 @@ import {
 	untrackDetachedChildPid,
 } from "../../utils/shell.ts";
 import type { ToolDefinition, ToolRenderResultOptions } from "../extensions/types.ts";
-import { OutputAccumulator } from "./output-accumulator.ts";
+import { OutputAccumulator, type OutputAccumulatorOptions } from "./output-accumulator.ts";
 import { getTextOutput, invalidArgText, str } from "./render-utils.ts";
 import { wrapToolDefinition } from "./tool-definition-wrapper.ts";
 import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, type TruncationResult } from "./truncate.ts";
@@ -38,10 +38,41 @@ export type BashToolInput = Static<typeof bashSchema>;
 export interface BashToolDetails {
 	truncation?: TruncationResult;
 	fullOutputPath?: string;
+	execution?: BashExecutionOutcome;
+	timing?: { commandTimerStartedAt: number; commandDeadlineAt: number };
+	output?: {
+		rawBytes: number;
+		persistence: "inline" | "complete" | "incomplete" | "host";
+		persistenceError?: string;
+	};
 	/** Exact process facts retained for consumers that need split streams. */
 	processOutput?: BashProcessOutput;
 }
 
+export interface BashExecutionOutcome {
+	status: "succeeded" | "failed" | "canceled";
+	reason: "exited" | "signaled" | "command_timeout" | "canceled" | "spawn_failed" | "unknown";
+	exitCode: number | null;
+	signal?: NodeJS.Signals;
+	errorCode?: string;
+	cancellationReason?: string;
+	/** Failure explanation without duplicating captured command output. */
+	message?: string;
+}
+
+/** Carries the same output and execution facts as a successful Bash result. */
+export class BashExecutionError extends Error {
+	readonly details: BashToolDetails & { execution: BashExecutionOutcome };
+	readonly code?: string;
+
+	constructor(message: string, details: BashToolDetails & { execution: BashExecutionOutcome }, options?: ErrorOptions) {
+		super(message, options);
+		this.name = "BashExecutionError";
+		this.details = details;
+		this.code = details.execution.errorCode;
+	}
+}
+
 export interface BashProcessOutput {
 	stdout: string;
 	stderr: string;
@@ -64,7 +95,7 @@ export interface BashOperations {
 	 * @param command The command to execute
 	 * @param cwd Working directory
 	 * @param options Execution options
-	 * @returns Promise resolving to exit code (null if killed)
+	 * @returns Promise resolving to the exit code and, when available, terminating signal
 	 */
 	exec: (
 		command: string,
@@ -76,11 +107,12 @@ export interface BashOperations {
 			env?: NodeJS.ProcessEnv;
 			/** Best-effort process facts. A launcher spawn does not prove the user command started. */
 			onProcessEvent?: (event: {
-				type: "spawned" | "spawn_failed" | "timeout" | "command_dispatched";
+				type: "spawned" | "spawn_failed" | "timeout" | "command_dispatched" | "timer_started";
+				atMs?: number;
 				processRole: "shell" | "guardian_launcher";
 			}) => void;
 		},
-	) => Promise<{ exitCode: number | null }>;
+	) => Promise<{ exitCode: number | null; signal?: NodeJS.Signals | null }>;
 }
 
 const GUARDED_SHELL_LAUNCHER_SOURCE = String.raw`
@@ -207,9 +239,9 @@ export function createLocalBashOperations(options?: {
 	return {
 		separatesOutputStreams: true,
 		exec: async (command, cwd, { onData, signal, timeout, env, onProcessEvent }) => {
-			const observe = (type: "spawned" | "spawn_failed" | "timeout" | "command_dispatched") => {
+			const observe = (type: "spawned" | "spawn_failed" | "timeout" | "command_dispatched" | "timer_started", atMs?: number) => {
 				try {
-					onProcessEvent?.({ type, processRole: options?.parentDeathGuard ? "guardian_launcher" : "shell" });
+					onProcessEvent?.({ type, processRole: options?.parentDeathGuard ? "guardian_launcher" : "shell", ...(atMs === undefined ? {} : { atMs }) });
 				} catch {
 					// Observers never control execution.
 				}
@@ -295,7 +327,7 @@ export function createLocalBashOperations(options?: {
 			child.stderr?.on("data", (data: Buffer) => onData(data, "stderr"));
 			child.stdin?.on("error", () => undefined);
 			if (!guardRequired && stdinCommand !== undefined) child.stdin?.end(stdinCommand);
-			const childCompletion = waitForChildProcess(child);
+			const childCompletion = waitForChildProcessExit(child);
 			let timedOut = false;
 			let timeoutHandle: NodeJS.Timeout | undefined;
 			// Stop/timeout send SIGTERM to the process group first so shell
@@ -349,22 +381,41 @@ export function createLocalBashOperations(options?: {
 				}
 				// Set timeout if provided.
 				if (timeout !== undefined && timeout > 0) {
+					const timerStartedAt = Date.now();
 					timeoutHandle = setTimeout(() => {
 						timedOut = true;
 						observe("timeout");
 						scheduleGracefulKill();
 					}, timeout * 1000);
+					observe("timer_started", timerStartedAt);
 				}
 				// Handle shell spawn errors and wait for the process to terminate without hanging
 				// on inherited stdio handles held by detached descendants.
-				const exitCode = await childCompletion;
+				const termination = await childCompletion;
 				if (signal?.aborted) {
-					throw new Error("aborted");
+					throw new BashExecutionError("aborted", {
+						execution: {
+							...termination,
+							signal: termination.signal ?? undefined,
+							status: "canceled",
+							reason: "canceled",
+							cancellationReason: formatCancellationReason(signal),
+							message: "Command aborted",
+						},
+					});
 				}
 				if (timedOut) {
-					throw new Error(`timeout:${timeout}`);
+					throw new BashExecutionError(`timeout:${timeout}`, {
+						execution: {
+							...termination,
+							signal: termination.signal ?? undefined,
+							status: "failed",
+							reason: "command_timeout",
+							message: `Command timed out after ${timeout} seconds`,
+						},
+					});
 				}
-				return { exitCode };
+				return termination;
 			} finally {
 				if (timeoutHandle) clearTimeout(timeoutHandle);
 				if (signal) signal.removeEventListener("abort", onAbort);
@@ -404,6 +455,13 @@ export function createLocalBashOperations(options?: {
 	};
 }
 
+function formatCancellationReason(signal?: AbortSignal): string | undefined {
+	if (!signal?.aborted) return undefined;
+	return signal.reason instanceof Error
+		? signal.reason.message
+		: typeof signal.reason === "string" ? signal.reason : undefined;
+}
+
 function wrapConstrainedWindowsPowerShellCommand(): {
 	launcher: string;
 	environmentVariable: string;
@@ -480,6 +538,8 @@ function resolveSpawnContext(command: string, cwd: string, spawnHook?: BashSpawn
 }
 
 export interface BashToolOptions {
+	/** Host-specific preview and persistence policy; defaults retain Pi's tail preview. */
+	output?: OutputAccumulatorOptions;
 	/** Custom operations for command execution. Default: local shell */
 	operations?: BashOperations;
 	/** Command prefix prepended to every command (for example shell setup commands) */
@@ -683,12 +743,13 @@ export function createBashToolDefinition(
 		) {
 			const resolvedCommand = commandPrefix ? `${commandPrefix}\n${command}` : command;
 			const spawnContext = resolveSpawnContext(resolvedCommand, cwd, spawnHook);
-			const output = new OutputAccumulator({ tempFilePrefix: "pi-bash" });
+			const output = new OutputAccumulator({ tempFilePrefix: "pi-bash", ...options?.output });
 			const stdout = new BashProcessStreamCapture();
 			const stderr = new BashProcessStreamCapture();
 			let updateTimer: NodeJS.Timeout | undefined;
 			let updateDirty = false;
 			let lastUpdateAt = 0;
+			let timing: BashToolDetails["timing"];
 
 			const emitOutputUpdate = () => {
 				if (!onUpdate || !updateDirty) return;
@@ -741,11 +802,17 @@ export function createBashToolDefinition(
 				output.finish();
 				clearUpdateTimer();
 				emitOutputUpdate();
-				const snapshot = output.snapshot({ persistIfTruncated: true });
 				const stdoutSnapshot = stdout.snapshot();
 				const stderrSnapshot = stderr.snapshot();
-				await output.closeTempFile();
-				return { snapshot, stdoutSnapshot, stderrSnapshot };
+				let persistenceError: string | undefined;
+				try {
+					await output.closeTempFile();
+				} catch (error) {
+					if (!options?.output) throw error;
+					persistenceError = error instanceof Error ? error.message : String(error);
+				}
+				const snapshot = output.snapshot({ persistIfTruncated: true });
+				return { snapshot, stdoutSnapshot, stderrSnapshot, persistenceError };
 			};
 
 			const formatOutput = (finished: Awaited<ReturnType<typeof finishOutput>>, emptyText = "(no output)") => {
@@ -753,6 +820,9 @@ export function createBashToolDefinition(
 				const truncation = snapshot.truncation;
 				let text = snapshot.content || emptyText;
 				let details: BashToolDetails | undefined;
+				if (options?.output?.strategy === "head_tail") {
+					return { text, details: { ...(truncation.truncated ? { truncation } : {}), fullOutputPath: snapshot.fullOutputPath } };
+				}
 				if (truncation.truncated) {
 					details = { truncation, fullOutputPath: snapshot.fullOutputPath };
 					const startLine = truncation.totalLines - truncation.outputLines + 1;
@@ -770,49 +840,118 @@ export function createBashToolDefinition(
 			};
 
 			const appendStatus = (text: string, status: string) => `${text ? `${text}\n\n` : ""}${status}`;
+			const resultDetails = (
+				finished: Awaited<ReturnType<typeof finishOutput>>,
+				execution: BashExecutionOutcome,
+			): BashToolDetails & { execution: BashExecutionOutcome } => ({
+				...formatOutput(finished).details,
+				execution,
+				...(timing ? { timing } : {}),
+				...(options?.output ? { output: {
+					rawBytes: finished.snapshot.rawBytes,
+					persistence: finished.persistenceError ? "incomplete" as const
+						: options.output.persistOutput === false ? "host" as const
+							: finished.snapshot.fullOutputPath ? "complete" as const : "inline" as const,
+					...(finished.persistenceError ? { persistenceError: finished.persistenceError } : {}),
+				} } : {}),
+				...(ops.separatesOutputStreams
+					? {
+							processOutput: {
+								stdout: finished.stdoutSnapshot.content,
+								stderr: finished.stderrSnapshot.content,
+								exitCode: execution.exitCode,
+								interrupted: execution.reason === "canceled" || execution.reason === "command_timeout",
+								stdoutTruncated: finished.stdoutSnapshot.truncated,
+								stderrTruncated: finished.stderrSnapshot.truncated,
+								rawOutputPath: finished.snapshot.fullOutputPath,
+							},
+						}
+					: {}),
+			});
 
 			try {
 				let exitCode: number | null;
+				let exitSignal: NodeJS.Signals | null | undefined;
+				let spawnFailed = false;
 				try {
 					const result = await ops.exec(spawnContext.command, spawnContext.cwd, {
 						onData: handleData,
 						signal,
 						timeout,
 						env: spawnContext.env,
+						onProcessEvent: (event) => {
+							if (event.type === "spawn_failed") spawnFailed = true;
+							if (event.type === "timer_started" && event.atMs !== undefined && timeout !== undefined) {
+								timing = { commandTimerStartedAt: event.atMs, commandDeadlineAt: event.atMs + timeout * 1000 };
+							}
+						},
 					});
 					exitCode = result.exitCode;
+					exitSignal = result.signal;
 				} catch (err) {
 					const finished = await finishOutput();
 					const { text } = formatOutput(finished, "");
-					if (err instanceof Error && err.message === "aborted") {
-						throw new Error(appendStatus(text, "Command aborted"));
-					}
-					if (err instanceof Error && err.message.startsWith("timeout:")) {
-						const timeoutSecs = err.message.split(":")[1];
-						throw new Error(appendStatus(text, `Command timed out after ${timeoutSecs} seconds`));
+					let execution: BashExecutionOutcome;
+					if (err instanceof BashExecutionError) execution = err.details.execution;
+					else {
+						const message = err instanceof Error ? err.message : String(err);
+						const errorCode =
+							err instanceof Error && "code" in err && typeof err.code === "string"
+								? err.code
+								: undefined;
+						// Preserve the existing custom-operations protocol; native operations carry typed facts.
+						const canceled = signal?.aborted || message === "aborted";
+						const legacyTimeout = message.startsWith("timeout:")
+							? message.slice("timeout:".length)
+							: undefined;
+						execution = {
+							status: canceled ? "canceled" : "failed",
+							reason: canceled
+								? "canceled"
+								: legacyTimeout !== undefined
+									? "command_timeout"
+									: spawnFailed
+										? "spawn_failed"
+										: "unknown",
+							exitCode: null,
+							...(canceled ? { cancellationReason: formatCancellationReason(signal) } : {}),
+							...(errorCode ? { errorCode } : {}),
+							message: canceled
+								? "Command aborted"
+								: legacyTimeout !== undefined
+									? `Command timed out after ${legacyTimeout} seconds`
+									: message,
+						};
 					}
-					throw err;
+					throw new BashExecutionError(
+						appendStatus(text, execution.message ?? "Command failed"),
+						resultDetails(finished, execution),
+						{ cause: err },
+					);
 				}
 
 				const finished = await finishOutput();
-				const { text: outputText, details } = formatOutput(finished);
-				if (exitCode !== 0 && exitCode !== null) {
-					throw new Error(appendStatus(outputText, `Command exited with code ${exitCode}`));
+				const { text: outputText } = formatOutput(finished);
+				const execution: BashExecutionOutcome = {
+					status: !exitSignal && exitCode === 0 ? "succeeded" : "failed",
+					reason: exitSignal ? "signaled" : exitCode === null ? "unknown" : "exited",
+					exitCode,
+					...(exitSignal ? { signal: exitSignal } : {}),
+				};
+				if (execution.status !== "succeeded") {
+					execution.message = exitSignal
+						? `Command terminated by signal ${exitSignal}`
+						: exitCode === null
+							? "Command terminated without an exit code"
+							: `Command exited with code ${exitCode}`;
+					throw new BashExecutionError(
+						appendStatus(outputText, execution.message),
+						resultDetails(finished, execution),
+					);
 				}
-				const processOutput = ops.separatesOutputStreams
-					? {
-							stdout: finished.stdoutSnapshot.content,
-							stderr: finished.stderrSnapshot.content,
-							exitCode,
-							interrupted: false,
-							stdoutTruncated: finished.stdoutSnapshot.truncated,
-							stderrTruncated: finished.stderrSnapshot.truncated,
-							rawOutputPath: finished.snapshot.fullOutputPath,
-						}
-					: undefined;
 				return {
 					content: [{ type: "text", text: outputText }],
-					details: details || processOutput ? { ...details, processOutput } : undefined,
+					details: resultDetails(finished, execution),
 				};
 			} finally {
 				clearUpdateTimer();
diff --git a/third_party/pi-mono/packages/coding-agent/src/core/tools/index.ts b/third_party/pi-mono/packages/coding-agent/src/core/tools/index.ts
index e55f9140..a0756e80 100644
--- a/third_party/pi-mono/packages/coding-agent/src/core/tools/index.ts
+++ b/third_party/pi-mono/packages/coding-agent/src/core/tools/index.ts
@@ -1,4 +1,6 @@
 export {
+	BashExecutionError,
+	type BashExecutionOutcome,
 	type BashOperations,
 	type BashSpawnContext,
 	type BashSpawnHook,
diff --git a/third_party/pi-mono/packages/coding-agent/src/core/tools/output-accumulator.ts b/third_party/pi-mono/packages/coding-agent/src/core/tools/output-accumulator.ts
index e044770f..1af489a1 100644
--- a/third_party/pi-mono/packages/coding-agent/src/core/tools/output-accumulator.ts
+++ b/third_party/pi-mono/packages/coding-agent/src/core/tools/output-accumulator.ts
@@ -3,18 +3,22 @@ import { createWriteStream, type WriteStream } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { TextDecoder } from "node:util";
-import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, type TruncationResult, truncateTail } from "./truncate.ts";
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, type TruncationResult, truncateHead, truncateTail } from "./truncate.ts";
 
 export interface OutputAccumulatorOptions {
 	maxLines?: number;
 	maxBytes?: number;
 	tempFilePrefix?: string;
+	strategy?: "tail" | "head_tail";
+	/** Disable when the host already owns the complete output log. */
+	persistOutput?: boolean;
 }
 
 export interface OutputSnapshot {
 	content: string;
 	truncation: TruncationResult;
 	fullOutputPath?: string;
+	rawBytes: number;
 }
 
 function defaultTempFilePath(prefix: string): string {
@@ -38,10 +42,15 @@ export class OutputAccumulator {
 	private readonly maxBytes: number;
 	private readonly maxRollingBytes: number;
 	private readonly tempFilePrefix: string;
+	private readonly strategy: "tail" | "head_tail";
+	private readonly persistOutput: boolean;
 	private readonly decoders = new Map<string, TextDecoder>();
 
 	private decodedChunks: Buffer[] = [];
 	private tailText = "";
+	private headText = "";
+	private headBytes = 0;
+	private headClosed = false;
 	private tailBytes = 0;
 	private tailStartsAtLineBoundary = true;
 	private totalRawBytes = 0;
@@ -54,12 +63,15 @@ export class OutputAccumulator {
 
 	private tempFilePath: string | undefined;
 	private tempFileStream: WriteStream | undefined;
+	private tempFileError: Error | undefined;
 
 	constructor(options: OutputAccumulatorOptions = {}) {
 		this.maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
 		this.maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
 		this.maxRollingBytes = Math.max(this.maxBytes * 2, 1);
 		this.tempFilePrefix = options.tempFilePrefix ?? "pi-output";
+		this.strategy = options.strategy ?? "tail";
+		this.persistOutput = options.persistOutput !== false;
 	}
 
 	append(data: Buffer, stream: "stdout" | "stderr" | "combined" = "combined"): void {
@@ -90,11 +102,21 @@ export class OutputAccumulator {
 	}
 
 	snapshot(options: { persistIfTruncated?: boolean } = {}): OutputSnapshot {
-		const tailTruncation = truncateTail(this.getSnapshotText(), {
+		let tailTruncation = truncateTail(this.getSnapshotText(), {
 			maxLines: this.maxLines,
 			maxBytes: this.maxBytes,
 		});
 		const truncated = this.totalLines > this.maxLines || this.totalDecodedBytes > this.maxBytes;
+		if (this.strategy === "head_tail" && truncated) {
+			const marker = "\n\n[... output omitted ...]\n\n";
+			const budget = Math.max(0, this.maxBytes - byteLength(marker));
+			const headBudget = Math.floor(budget * 0.45);
+			const head = truncateHead(this.headText, { maxBytes: headBudget, maxLines: this.maxLines }).content
+				|| utf8Prefix(this.headText, headBudget);
+			const tail = truncateTail(this.tailText, { maxBytes: budget - headBudget, maxLines: this.maxLines }).content;
+			const content = utf8Prefix(head + marker + tail, this.maxBytes);
+			tailTruncation = { ...tailTruncation, content, outputBytes: byteLength(content), outputLines: content.split("\n").length };
+		}
 		const truncatedBy = truncated
 			? (tailTruncation.truncatedBy ?? (this.totalDecodedBytes > this.maxBytes ? "bytes" : "lines"))
 			: null;
@@ -115,11 +137,13 @@ export class OutputAccumulator {
 		return {
 			content: truncation.content,
 			truncation,
-			fullOutputPath: this.tempFilePath,
+			fullOutputPath: this.tempFileError ? undefined : this.tempFilePath,
+			rawBytes: this.totalRawBytes,
 		};
 	}
 
 	async closeTempFile(): Promise<void> {
+		if (this.tempFileError) throw this.tempFileError;
 		if (!this.tempFileStream) {
 			return;
 		}
@@ -153,6 +177,11 @@ export class OutputAccumulator {
 
 		const bytes = byteLength(text);
 		this.totalDecodedBytes += bytes;
+		if (this.strategy === "head_tail" && !this.headClosed) {
+			this.headClosed = this.headBytes + bytes >= this.maxBytes;
+			this.headText += utf8Prefix(text, this.maxBytes - this.headBytes);
+			this.headBytes = byteLength(this.headText);
+		}
 		this.tailText += text;
 		this.tailBytes += bytes;
 		if (this.tailBytes > this.maxRollingBytes * 2) {
@@ -179,6 +208,7 @@ export class OutputAccumulator {
 
 	private appendDecodedChunk(text: string): void {
 		this.appendDecodedText(text);
+		if (!this.persistOutput || this.tempFileError) return;
 		if (this.tempFileStream || this.shouldUseTempFile()) {
 			this.ensureTempFile();
 			if (text.length > 0) this.tempFileStream?.write(text, "utf-8");
@@ -220,14 +250,24 @@ export class OutputAccumulator {
 	}
 
 	private ensureTempFile(): void {
-		if (this.tempFilePath) {
+		if (!this.persistOutput || this.tempFilePath) {
 			return;
 		}
 		this.tempFilePath = defaultTempFilePath(this.tempFilePrefix);
 		this.tempFileStream = createWriteStream(this.tempFilePath);
+		this.tempFileStream.on("error", (error) => {
+			this.tempFileError = error;
+		});
 		for (const chunk of this.decodedChunks) {
 			this.tempFileStream.write(chunk);
 		}
 		this.decodedChunks = [];
 	}
 }
+
+function utf8Prefix(text: string, maxBytes: number): string {
+	const buffer = Buffer.from(text, "utf8");
+	let end = Math.min(buffer.length, Math.max(0, maxBytes));
+	while (end > 0 && (buffer[end] & 0xc0) === 0x80) end--;
+	return buffer.subarray(0, end).toString("utf8");
+}
diff --git a/third_party/pi-mono/packages/coding-agent/src/index.ts b/third_party/pi-mono/packages/coding-agent/src/index.ts
index 958c7ebb..a18600d6 100644
--- a/third_party/pi-mono/packages/coding-agent/src/index.ts
+++ b/third_party/pi-mono/packages/coding-agent/src/index.ts
@@ -240,6 +240,8 @@ export {
 export { createSyntheticSourceInfo } from "./core/source-info.ts";
 // Tools
 export {
+	BashExecutionError,
+	type BashExecutionOutcome,
 	type BashOperations,
 	type BashSpawnContext,
 	type BashSpawnHook,
diff --git a/third_party/pi-mono/packages/coding-agent/src/utils/child-process.ts b/third_party/pi-mono/packages/coding-agent/src/utils/child-process.ts
index 3d97d3da..d68d3e4d 100644
--- a/third_party/pi-mono/packages/coding-agent/src/utils/child-process.ts
+++ b/third_party/pi-mono/packages/coding-agent/src/utils/child-process.ts
@@ -15,6 +15,11 @@ import crossSpawn from "cross-spawn";
 
 const EXIT_STDIO_GRACE_MS = 100;
 
+export interface ChildProcessExit {
+	exitCode: number | null;
+	signal: NodeJS.Signals | null;
+}
+
 export function spawnProcess(
 	command: string,
 	args: string[],
@@ -43,11 +48,12 @@ export function spawnProcessSync(
  * though the original process is already gone. We wait briefly for stdio to end,
  * then forcibly stop tracking the inherited handles.
  */
-export function waitForChildProcess(child: ChildProcess): Promise<number | null> {
+export function waitForChildProcessExit(child: ChildProcess): Promise<ChildProcessExit> {
 	return new Promise((resolve, reject) => {
 		let settled = false;
 		let exited = false;
 		let exitCode: number | null = null;
+		let exitSignal: NodeJS.Signals | null = null;
 		let postExitTimer: NodeJS.Timeout | undefined;
 		let stdoutEnded = child.stdout === null;
 		let stderrEnded = child.stderr === null;
@@ -64,19 +70,19 @@ export function waitForChildProcess(child: ChildProcess): Promise<number | null>
 			child.stderr?.removeListener("end", onStderrEnd);
 		};
 
-		const finalize = (code: number | null) => {
+		const finalize = (code: number | null, signal: NodeJS.Signals | null) => {
 			if (settled) return;
 			settled = true;
 			cleanup();
 			child.stdout?.destroy();
 			child.stderr?.destroy();
-			resolve(code);
+			resolve({ exitCode: code, signal });
 		};
 
 		const maybeFinalizeAfterExit = () => {
 			if (!exited || settled) return;
 			if (stdoutEnded && stderrEnded) {
-				finalize(exitCode);
+				finalize(exitCode, exitSignal);
 			}
 		};
 
@@ -97,17 +103,18 @@ export function waitForChildProcess(child: ChildProcess): Promise<number | null>
 			reject(err);
 		};
 
-		const onExit = (code: number | null) => {
+		const onExit = (code: number | null, signal: NodeJS.Signals | null = null) => {
 			exited = true;
 			exitCode = code;
+			exitSignal = signal;
 			maybeFinalizeAfterExit();
 			if (!settled) {
-				postExitTimer = setTimeout(() => finalize(code), EXIT_STDIO_GRACE_MS);
+				postExitTimer = setTimeout(() => finalize(code, signal), EXIT_STDIO_GRACE_MS);
 			}
 		};
 
-		const onClose = (code: number | null) => {
-			finalize(code);
+		const onClose = (code: number | null, signal: NodeJS.Signals | null = null) => {
+			finalize(code, signal);
 		};
 
 		child.stdout?.once("end", onStdoutEnd);
@@ -117,3 +124,7 @@ export function waitForChildProcess(child: ChildProcess): Promise<number | null>
 		child.once("close", onClose);
 	});
 }
+
+export async function waitForChildProcess(child: ChildProcess): Promise<number | null> {
+	return (await waitForChildProcessExit(child)).exitCode;
+}
diff --git a/third_party/pi-mono/packages/coding-agent/test/bash-process-observation.test.ts b/third_party/pi-mono/packages/coding-agent/test/bash-process-observation.test.ts
index 09e9364b..d16fcf28 100644
--- a/third_party/pi-mono/packages/coding-agent/test/bash-process-observation.test.ts
+++ b/third_party/pi-mono/packages/coding-agent/test/bash-process-observation.test.ts
@@ -1,8 +1,66 @@
 import { tmpdir } from "node:os";
 import { describe, expect, it, vi } from "vitest";
-import { createLocalBashOperations } from "../src/core/tools/bash.js";
+import { BashExecutionError, createBashTool, createLocalBashOperations } from "../src/core/tools/bash.js";
 
 describe("local Bash process observations", () => {
+  it.skipIf(process.platform === "win32")("preserves a real terminating signal and rejects the interrupted command", async () => {
+    const result = await createLocalBashOperations().exec("kill -TERM $$", tmpdir(), { onData: () => {} });
+    expect(result).toEqual({ exitCode: null, signal: "SIGTERM" });
+    const failed = createBashTool(tmpdir()).execute("signal-exit", {
+      command: "printf 'partial-output'; kill -TERM $$", timeout: 3,
+    });
+    await expect(failed).rejects.toBeInstanceOf(BashExecutionError);
+    await expect(failed).rejects.toMatchObject({
+      message: "partial-output\n\nCommand terminated by signal SIGTERM",
+      details: {
+        execution: { status: "failed", reason: "signaled", exitCode: null, signal: "SIGTERM" },
+        processOutput: { stdout: "partial-output", stderr: "", exitCode: null },
+      },
+    });
+  });
+  it("keeps separate streams and the exit code on failed commands", async () => {
+    const tool = createBashTool(tmpdir(), { operations: {
+      separatesOutputStreams: true,
+      exec: async (_command, _cwd, options) => {
+        options.onData(Buffer.from("out"), "stdout");
+        options.onData(Buffer.from("err"), "stderr");
+        return { exitCode: 7 };
+      },
+    } });
+    await expect(tool.execute("failed", { command: "unused" })).rejects.toMatchObject({
+      details: {
+        execution: { status: "failed", reason: "exited", exitCode: 7 },
+        processOutput: { stdout: "out", stderr: "err", exitCode: 7, interrupted: false },
+      },
+    });
+  });
+  it("rejects an unknown exit while retaining output from custom operations", async () => {
+    const tool = createBashTool(tmpdir(), {
+      operations: { exec: async (_command, _cwd, options) => {
+        options.onData(Buffer.from("partial-output"));
+        return { exitCode: null };
+      } },
+    });
+    await expect(tool.execute("unknown-exit", { command: "unused" })).rejects.toThrow(
+      "partial-output\n\nCommand terminated without an exit code",
+    );
+  });
+  it("preserves a spawn failure code without inventing an exit code", async () => {
+    const tool = createBashTool(tmpdir(), {
+      operations: {
+        exec: async (_command, _cwd, options) => {
+          options.onProcessEvent?.({ type: "spawn_failed", processRole: "shell" });
+          throw Object.assign(new Error("spawn failed"), { code: "ENOENT" });
+        },
+      },
+    });
+    await expect(tool.execute("spawn-error", { command: "unused" })).rejects.toMatchObject({
+      code: "ENOENT",
+      details: {
+        execution: { status: "failed", reason: "spawn_failed", exitCode: null, errorCode: "ENOENT" },
+      },
+    });
+  });
   it("observes a real shell spawn without changing a nonzero exit", async () => {
     const onProcessEvent = vi.fn();
     const result = await createLocalBashOperations().exec("exit 7", tmpdir(), { onData: () => {}, onProcessEvent });
@@ -22,6 +80,7 @@ describe("local Bash process observations", () => {
     await expect(createLocalBashOperations().exec(command, tmpdir(), {
       onData: () => {}, timeout: 0.05, onProcessEvent,
     })).rejects.toThrow("timeout:");
+    expect(onProcessEvent).toHaveBeenCalledWith({ type: "timer_started", processRole: "shell", atMs: expect.any(Number) });
     expect(onProcessEvent).toHaveBeenCalledWith({ type: "timeout", processRole: "shell" });
   });
 });
diff --git a/third_party/pi-mono/packages/coding-agent/test/tools.test.ts b/third_party/pi-mono/packages/coding-agent/test/tools.test.ts
index 4f651c81..bfeb027d 100644
--- a/third_party/pi-mono/packages/coding-agent/test/tools.test.ts
+++ b/third_party/pi-mono/packages/coding-agent/test/tools.test.ts
@@ -470,6 +470,39 @@ describe("Coding Agent Tools", () => {
 			rmSync(snapshot.fullOutputPath!, { force: true });
 		});
 
+		it("keeps bounded original head and tail with split UTF-8 and host persistence", async () => {
+			const accumulator = new OutputAccumulator({ strategy: "head_tail", maxBytes: 128, persistOutput: false });
+			const raw = Buffer.from("FIRST汉" + "中".repeat(10000) + "TAIL末");
+			for (let i = 0; i < raw.length; i += 7) accumulator.append(raw.subarray(i, i + 7), "stdout");
+			accumulator.finish();
+			await accumulator.closeTempFile();
+			const snapshot = accumulator.snapshot({ persistIfTruncated: true });
+			expect(snapshot.content).toContain("FIRST汉");
+			expect(snapshot.content).toContain("TAIL末");
+			expect(snapshot.content).not.toContain("�");
+			expect(Buffer.byteLength(snapshot.content)).toBeLessThanOrEqual(128);
+			expect(snapshot.rawBytes).toBe(raw.length);
+			expect(snapshot.fullOutputPath).toBeUndefined();
+		});
+
+		it("reports an early spill error without advertising a full file or losing the preview", async () => {
+			const tool = createBashToolDefinition(testDir, {
+				output: { strategy: "head_tail", maxBytes: 128, tempFilePrefix: `missing-${Date.now()}/pi` },
+				operations: { exec: async (_command, _cwd, options) => {
+					options.onData(Buffer.from("FIRST" + "x".repeat(1000) + "TAIL"));
+					await new Promise((resolve) => setTimeout(resolve, 20));
+					return { exitCode: 0 };
+				} },
+			});
+			const result = await tool.execute("spill-error", { command: "test" });
+			expect(getTextOutput(result)).toContain("FIRST");
+			expect(getTextOutput(result)).toContain("TAIL");
+			expect(result.details?.output?.persistenceError).toBeTruthy();
+			expect(result.details?.fullOutputPath).toBeUndefined();
+			expect(result.details?.output?.persistence).toBe("incomplete");
+			expect(result.details?.execution?.exitCode).toBe(0);
+		});
+
 		it("describes the command as the current shell rather than always calling it Bash", () => {
 			const definition = createBashToolDefinition(testDir, { operations: { exec: async () => ({ exitCode: 0 }) } });
 			const commandDescription = (definition.parameters as { properties?: { command?: { description?: string } } }).properties
@@ -542,6 +575,10 @@ describe("Coding Agent Tools", () => {
 				}
 
 				expect(error).toBeInstanceOf(Error);
+				expect(error).toMatchObject({ details: {
+					execution: { reason: testCase.error.startsWith("timeout:") ? "command_timeout" : "canceled" },
+					fullOutputPath: expect.any(String),
+				} });
 				const message = (error as Error).message;
 				expect(message).toContain(testCase.expected);
 				expect(message).toMatch(/\[Showing lines \d+-\d+ of \d+\. Full output: /);

From 0dab5f875e3a80f0c1fe1b6770ceb8501415f060 Mon Sep 17 00:00:00 2001
From: muyu <muyu@minimaxi.com>
Date: Wed, 23 Sep 2026 20:51:36 +0800
Subject: [PATCH 2/3] test: reuse existing suites for Bash regressions

---
 .../test/desktop/local-bash-output.test.ts    | 207 ----
 .../test/desktop/local-bash-timeout.test.ts   | 506 ---------
 .../desktop/local-task-output-polling.test.ts | 445 --------
 .../service/background-bash/executor.test.ts  | 233 -----
 .../agent-host/execution/executor.test.ts     |  13 +-
 .../test/unit/child-bash-lifecycle.test.ts    |   6 +-
 ...background-bash-review-regressions.test.ts | 430 --------
 .../unit/local-background-bash-runner.test.ts | 959 ------------------
 .../local-background-task-stop-races.test.ts  | 119 ---
 .../tui/test/unit/tui-tool-evidence.test.ts   | 264 -----
 .../tui/test/unit/tui-tool-summary.test.ts    |  54 -
 release/public-source.json                    |   9 -
 test/vitest-suites.json                       |  11 +-
 third_party/pi-mono/MINIMAX_CHANGES.md        |   2 +-
 14 files changed, 7 insertions(+), 3251 deletions(-)
 delete mode 100644 packages/agent-tools/test/desktop/local-bash-output.test.ts
 delete mode 100644 packages/agent-tools/test/desktop/local-bash-timeout.test.ts
 delete mode 100644 packages/agent-tools/test/desktop/local-task-output-polling.test.ts
 delete mode 100644 packages/local-runtime-v2/src/service/background-bash/executor.test.ts
 delete mode 100644 packages/local-runtime/test/unit/local-background-bash-review-regressions.test.ts
 delete mode 100644 packages/local-runtime/test/unit/local-background-bash-runner.test.ts
 delete mode 100644 packages/local-runtime/test/unit/local-background-task-stop-races.test.ts
 delete mode 100644 packages/tui/test/unit/tui-tool-evidence.test.ts
 delete mode 100644 packages/tui/test/unit/tui-tool-summary.test.ts

diff --git a/packages/agent-tools/test/desktop/local-bash-output.test.ts b/packages/agent-tools/test/desktop/local-bash-output.test.ts
deleted file mode 100644
index ef3228c8..00000000
--- a/packages/agent-tools/test/desktop/local-bash-output.test.ts
+++ /dev/null
@@ -1,207 +0,0 @@
-import { mkdtemp, readFile, rm } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-
-import { LocalBashTool } from '../../src/desktop/local-pi-tools.js';
-import { DESKTOP_BASH_MAX_BYTES } from '../../src/desktop/output-limit.js';
-import { readPluginHookCompatibleToolResponse } from '../../src/plugin-hooks/vendor-tool-response.js';
-import type { LocalRuntimeToolContext } from '../../src/desktop/types.js';
-
-const SESSION_CTX = {
-  sessionId: 'sess-test',
-  turnId: 'turn-test',
-} satisfies LocalRuntimeToolContext;
-
-describe('LocalBashTool — foreground output truncation', () => {
-  let workspace: string;
-
-  beforeEach(async () => {
-    workspace = await mkdtemp(join(tmpdir(), 'bash-output-'));
-  });
-  afterEach(async () => {
-    await rm(workspace, { recursive: true, force: true });
-  });
-
-  it('preserves exact stdout and stderr for Compatible PostToolUse', async () => {
-    const tool = new LocalBashTool(workspace, undefined, { mode: 'off' });
-    const result = await tool.execute(SESSION_CTX, {
-      command: "printf 'from-stdout'; printf 'from-stderr' >&2",
-    });
-
-    expect(readPluginHookCompatibleToolResponse(result)).toEqual({
-      stdout: 'from-stdout',
-      stderr: 'from-stderr',
-      interrupted: false,
-    });
-  });
-
-  it('short output is returned verbatim, not truncated', async () => {
-    const tool = new LocalBashTool(workspace, undefined, { mode: 'off' });
-    const result = await tool.execute(SESSION_CTX, { command: 'printf "a\\nb\\nc\\n"' });
-    expect(result.tool_name).toBe('bash');
-    expect(result.isError).toBeFalsy();
-    expect(result.text).toContain('a');
-    expect(result.text.toLowerCase()).not.toContain('full output:');
-  });
-
-  it.skipIf(process.platform === 'win32')('reports signal termination as a failed tool result with partial output', async () => {
-    const tool = new LocalBashTool(workspace, undefined, { mode: 'off' });
-    const result = await tool.execute(SESSION_CTX, {
-      command: "printf 'partial-output'; kill -TERM $$",
-      timeout: 3,
-    });
-
-    expect(result.isError).toBe(true);
-    expect(result.text).toContain('partial-output');
-    expect(result.text).toContain('Command terminated by signal SIGTERM');
-    expect(result.details).toMatchObject({
-      execution: { status: 'failed', reason: 'signaled', exitCode: null, signal: 'SIGTERM' },
-      processOutput: { stdout: 'partial-output', stderr: '' },
-    });
-  });
-
-  it('preserves original head and tail with one readable full output file', async () => {
-    const tool = new LocalBashTool(workspace, undefined, { mode: 'off' });
-    const script = `for(let i=0;i<400;i++) console.log('row-'+i+'-'+'x'.repeat(90))`;
-    const command = `${JSON.stringify(process.execPath)} -e ${JSON.stringify(script)}`;
-    const result = await tool.execute(SESSION_CTX, { command });
-
-    expect(Buffer.byteLength(result.text, 'utf8')).toBeLessThanOrEqual(
-      DESKTOP_BASH_MAX_BYTES,
-    );
-    expect(result.text).toContain('row-0-');
-    expect(result.text).toContain('row-399-');
-    expect(result.text).not.toContain('row-200-');
-    expect(result.text.toLowerCase()).toContain('full output:');
-    const full = await readFile(result.details?.fullOutputPath as string, 'utf8');
-    expect(full).toContain('row-200-');
-    expect(result.details?.output).toMatchObject({ rawBytes: Buffer.byteLength(full), persistence: 'complete' });
-    expect(result.details?.desktop_output_truncation).toMatchObject({
-      truncated: true,
-      has_more: true,
-      strategy: 'head_tail_lines',
-      max_bytes: DESKTOP_BASH_MAX_BYTES,
-      continuation_hint: {
-        tool: 'read',
-        preserve_args: ['path'],
-      },
-    });
-    expect(result.details?.desktop_output_truncation).not.toHaveProperty('next_offset');
-    expect(result.details?.desktop_output_truncation).not.toHaveProperty('offset_unit');
-  });
-
-  it('caps a thrown timeout result while preserving the error ToolResult status', async () => {
-    const tool = new LocalBashTool(workspace, undefined, { mode: 'off' });
-    const innerExecute = vi
-      .spyOn((tool as unknown as { tool: { execute: unknown } }).tool, 'execute')
-      .mockRejectedValue(
-        new Error(
-          `${'timeout-output\n'.repeat(2_000)}\n\nCommand timed out after 1 seconds`,
-        ),
-      );
-
-    const result = await tool.execute(SESSION_CTX, { command: 'ignored', timeout: 1 });
-
-    expect(innerExecute).toHaveBeenCalledOnce();
-    expect(result.isError).toBe(true);
-    expect(Buffer.byteLength(result.text, 'utf8')).toBeLessThanOrEqual(
-      DESKTOP_BASH_MAX_BYTES,
-    );
-    expect(result.text).toContain('Command timed out after 1 seconds');
-    expect(result.text).toContain('desktop bash output truncated');
-    expect(result.details?.desktop_output_truncation).toMatchObject({
-      truncated: true,
-      has_more: true,
-      strategy: 'head_tail_lines',
-      max_bytes: DESKTOP_BASH_MAX_BYTES,
-      continuation_hint: {
-        tool: 'bash',
-        preserve_args: [],
-      },
-    });
-  });
-
-  it('still propagates an active AbortSignal instead of converting cancellation to a tool result', async () => {
-    const tool = new LocalBashTool(workspace, undefined, { mode: 'off' });
-    const controller = new AbortController();
-    vi.spyOn((tool as unknown as { tool: { execute: unknown } }).tool, 'execute').mockImplementation(
-      async () => {
-        controller.abort();
-        throw new Error('Command aborted');
-      },
-    );
-
-    await expect(
-      tool.execute(SESSION_CTX, { command: 'ignored' }, controller.signal),
-    ).rejects.toThrow('Command aborted');
-  });
-
-  it('caps a large nonzero-exit result while preserving the error ToolResult status', async () => {
-    const tool = new LocalBashTool(workspace, undefined, { mode: 'off' });
-    const script = `for(let i=0;i<400;i++) console.error('error-row-'+i+'-'+'e'.repeat(90)); process.exit(7)`;
-    const command = `${JSON.stringify(process.execPath)} -e ${JSON.stringify(script)}`;
-    const result = await tool.execute(SESSION_CTX, { command });
-
-    expect(result.isError).toBe(true);
-    expect(Buffer.byteLength(result.text, 'utf8')).toBeLessThanOrEqual(
-      DESKTOP_BASH_MAX_BYTES,
-    );
-    expect(result.text).toContain('error-row-0-');
-    expect(result.text).toContain('error-row-399-');
-    expect(result.text).not.toContain('error-row-200-');
-    expect(result.text).toContain('Command exited with code 7');
-    expect(result.details).toMatchObject({
-      execution: { status: 'failed', reason: 'exited', exitCode: 7 },
-      processOutput: { exitCode: 7, interrupted: false },
-    });
-    expect(result.text).toContain('desktop bash output truncated');
-    expect(result.details?.desktop_output_truncation).toMatchObject({
-      truncated: true,
-      has_more: true,
-      strategy: 'head_tail_lines',
-      max_bytes: DESKTOP_BASH_MAX_BYTES,
-      continuation_hint: {
-        tool: 'read',
-        preserve_args: ['path'],
-      },
-    });
-  });
-
-  it('output beyond 2000 lines retains the original first and last lines', async () => {
-    const tool = new LocalBashTool(workspace, undefined, { mode: 'off' });
-    const script = `for(let i=0;i<3000;i++) console.log('spill-row-'+i+'-'+'z'.repeat(50))`;
-    const command = `${JSON.stringify(process.execPath)} -e ${JSON.stringify(script)}`;
-    const result = await tool.execute(SESSION_CTX, { command });
-
-    const lower = result.text.toLowerCase();
-    expect(lower).toContain('full output:');
-    expect(lower).toContain('original head+tail');
-    expect(Buffer.byteLength(result.text, 'utf8')).toBeLessThanOrEqual(
-      DESKTOP_BASH_MAX_BYTES,
-    );
-
-    expect(result.text).toContain('spill-row-2999-');
-    expect(result.text).toContain('spill-row-0-');
-    expect(result.details?.desktop_output_truncation).toMatchObject({
-      truncated: true,
-      has_more: true,
-      strategy: 'head_tail_lines',
-      max_bytes: DESKTOP_BASH_MAX_BYTES,
-      continuation_hint: {
-        tool: 'read',
-        preserve_args: ['path'],
-      },
-    });
-
-    // Recover the spilled path from the footer and confirm it holds the FULL output.
-    const m = result.text.match(/full output:\s*(.+?)\]/i);
-    expect(m).not.toBeNull();
-    const full = await readFile((m as RegExpMatchArray)[1].trim(), 'utf-8');
-    const fullLines = full.split('\n').filter((l) => l.length > 0);
-    expect(fullLines).toHaveLength(3000); // complete output, not the 50 KiB tail
-    expect(fullLines[0]).toContain('spill-row-0-');
-    expect(fullLines[fullLines.length - 1]).toContain('spill-row-2999-');
-  });
-});
diff --git a/packages/agent-tools/test/desktop/local-bash-timeout.test.ts b/packages/agent-tools/test/desktop/local-bash-timeout.test.ts
deleted file mode 100644
index e409ad9b..00000000
--- a/packages/agent-tools/test/desktop/local-bash-timeout.test.ts
+++ /dev/null
@@ -1,506 +0,0 @@
-import { mkdtemp, rm } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { Value } from '@sinclair/typebox/value';
-
-import { LocalBashToolDef } from '../../src/desktop/builtin-defs.js';
-import { createLocalBashToolDefinition } from '../../src/desktop/local-bash-contract.js';
-import {
-  DEFAULT_FOREGROUND_BASH_TIMEOUT_SECONDS,
-  DEFAULT_FOREGROUND_BASH_SOFT_YIELD_MS,
-  LocalBashTool,
-  MAX_FOREGROUND_BASH_TIMEOUT_SECONDS,
-  resolveForegroundTimeout,
-} from '../../src/desktop/local-pi-tools.js';
-import type {
-  LocalBashAdapter,
-  LocalBashBackgroundStartResult,
-  LocalRuntimeToolContext,
-  LocalSandboxBashOperationsFactory,
-} from '../../src/desktop/types.js';
-
-const SESSION_CTX = {
-  sessionId: 'sess-test',
-  turnId: 'turn-test',
-} satisfies LocalRuntimeToolContext;
-
-function timeoutDescription(): string {
-  const props = (LocalBashToolDef.schema as { properties: Record<string, { description?: string }> })
-    .properties;
-  return props.timeout?.description ?? '';
-}
-
-describe('resolveForegroundTimeout (bounded foreground helper)', () => {
-  // TS-1 (P0): omitted timeout → 120s default.
-  it('defaults to 120 seconds when timeout is omitted', () => {
-    expect(resolveForegroundTimeout({})).toBe(120);
-    expect(resolveForegroundTimeout({})).toBe(DEFAULT_FOREGROUND_BASH_TIMEOUT_SECONDS);
-    expect(DEFAULT_FOREGROUND_BASH_TIMEOUT_SECONDS).toBe(120);
-  });
-
-  it('defaults to 120 seconds when timeout is explicitly undefined', () => {
-    expect(resolveForegroundTimeout({ timeout: undefined })).toBe(120);
-  });
-
-  it('honors a positive timeout up to the 300-second foreground cap', () => {
-    expect(resolveForegroundTimeout({ timeout: 5 })).toBe(5);
-    expect(resolveForegroundTimeout({ timeout: 100000 })).toBe(300);
-    expect(MAX_FOREGROUND_BASH_TIMEOUT_SECONDS).toBe(300);
-  });
-
-  it.each([0, -5, NaN, Infinity, 2_147_484])('rejects an invalid timeout %s before execution', (timeout) => {
-    expect(() => resolveForegroundTimeout({ timeout })).toThrow('finite positive');
-  });
-
-  it('preserves fractional seconds', () => {
-    expect(resolveForegroundTimeout({ timeout: 0.125 })).toBe(0.125);
-  });
-});
-
-it('requires a positive timeout in the shared schema', () => {
-  expect(Value.Check(LocalBashToolDef.schema, { description: '运行测试命令', command: 'echo ok', timeout: 0.5 })).toBe(true);
-  expect(Value.Check(LocalBashToolDef.schema, { description: '运行测试命令', command: 'echo ok', timeout: 0 })).toBe(false);
-});
-
-describe('LocalBashTool input timing contract', () => {
-  it.each([null, 42, false])('rejects non-string description %j before dispatch', async (description) => {
-    const startBackground = vi.fn();
-    const runManagedForeground = vi.fn();
-    const tool = new LocalBashTool('/tmp/workspace', { startBackground, runManagedForeground }, { mode: 'off' });
-    const input = { command: 'echo ok', description };
-    expect(Value.Check(LocalBashToolDef.schema, input)).toBe(false);
-    const result = await tool.execute({ ...SESSION_CTX, canConsumeBackgroundBashOutput: true }, input as never);
-    expect(result).toMatchObject({ isError: true, details: { error_code: 'BASH_INVALID_INPUT' } });
-    expect(startBackground).not.toHaveBeenCalled();
-    expect(runManagedForeground).not.toHaveBeenCalled();
-  });
-
-  it.each([undefined, ''])('uses the command when description is %j', async (description) => {
-    const startBackground = vi.fn(async () => ({ status: 'started' as const, taskId: 'task-description' }));
-    const tool = new LocalBashTool('/tmp/workspace', { startBackground }, { mode: 'off' });
-    const result = await tool.execute({ ...SESSION_CTX, canConsumeBackgroundBashOutput: true }, {
-      command: 'echo exact', description, run_in_background: true,
-    });
-    expect(startBackground.mock.calls[0]?.[1]).toMatchObject({ command: 'echo exact', description: 'echo exact' });
-    expect(result.details?.description).toBe('echo exact');
-  });
-
-  it('keeps the purpose separate from the executable command', async () => {
-    const startBackground = vi.fn(async () => ({ status: 'started' as const, taskId: 'task-description' }));
-    const tool = new LocalBashTool('/tmp/workspace', { startBackground }, { mode: 'off' });
-    const result = await tool.execute({ ...SESSION_CTX, canConsumeBackgroundBashOutput: true }, {
-      command: ' echo exact ', description: '检查工作区状态', run_in_background: true,
-    });
-    expect(startBackground.mock.calls[0]?.[1]).toMatchObject({ command: ' echo exact ', description: '检查工作区状态' });
-    expect(result.text).toContain('Purpose: 检查工作区状态');
-    expect(result.details?.description).toBe('检查工作区状态');
-  });
-
-  it.each([false, true])('rejects invalid parameters without dispatching (background=%s)', async (background) => {
-    const startBackground = vi.fn();
-    const runManagedForeground = vi.fn();
-    const tool = new LocalBashTool('/tmp/workspace', { startBackground, runManagedForeground }, { mode: 'off' });
-    for (const input of [{ description: '运行测试命令', command: 'echo ok', timeout: 0 }, { description: '运行测试命令', command: 'echo ok', timeout: Infinity }, { description: '运行测试命令', command: '   ' }]) {
-      const result = await tool.execute({ ...SESSION_CTX, canConsumeBackgroundBashOutput: true }, { ...input, run_in_background: background });
-      expect(result).toMatchObject({ isError: true, details: { error_code: 'BASH_INVALID_INPUT' } });
-    }
-    expect(startBackground).not.toHaveBeenCalled();
-    expect(runManagedForeground).not.toHaveBeenCalled();
-  });
-
-  it('reports a capped foreground timeout while preserving the command text', async () => {
-    const tool = new LocalBashTool('/tmp/workspace', undefined, { mode: 'off' });
-    const execute = vi.spyOn((tool as unknown as { tool: { execute: unknown } }).tool, 'execute')
-      .mockResolvedValue({ content: [{ type: 'text', text: 'ok' }], details: {} } as never);
-    const result = await tool.execute(SESSION_CTX, { description: '运行测试命令', command: ' echo ok ', timeout: 600 });
-    expect(execute.mock.calls[0]?.[1]).toEqual({ description: '运行测试命令', command: ' echo ok ', timeout: 300 });
-    expect(result.details).toMatchObject({ timing: { requestedTimeoutSeconds: 600, commandTimeoutSeconds: 300 } });
-    expect(result.text).toContain('requested 600s; effective 300s');
-  });
-});
-
-describe('LocalBashTool.execute — background path', () => {
-  // TS-3 (P0): run_in_background:true (no timeout) → 120 default NOT applied;
-  // dispatches to the background adapter with the input untouched.
-  it('dispatches to the background adapter without injecting the 120s default', async () => {
-    const started: LocalBashBackgroundStartResult = {
-      status: 'started',
-      taskId: 'task-1',
-      details: { envSanitized: ['MAVIS_ACCESS_TOKEN'] },
-    };
-    const startBackground = vi.fn(
-      async (): Promise<LocalBashBackgroundStartResult> => started,
-    );
-    const adapter: LocalBashAdapter = { startBackground };
-    const tool = new LocalBashTool('/tmp/does-not-matter', adapter, { mode: 'off' });
-
-    const result = await tool.execute({ ...SESSION_CTX, canConsumeBackgroundBashOutput: true }, {
-      description: '运行测试命令',
-      command: 'echo hi',
-      run_in_background: true,
-    });
-
-    expect(startBackground).toHaveBeenCalledTimes(1);
-    const forwarded = startBackground.mock.calls[0]?.[1];
-    // Background path must receive the input verbatim — no 120 injected.
-    expect(forwarded).toEqual({ description: '运行测试命令', command: 'echo hi', run_in_background: true });
-    expect((forwarded as { timeout?: number }).timeout).toBeUndefined();
-    expect(result.details).toMatchObject({
-      status: 'started',
-      task_id: 'task-1',
-      envSanitized: ['MAVIS_ACCESS_TOKEN'],
-    });
-  });
-});
-
-describe('LocalBashTool.execute — foreground path forwarding (TS-4)', () => {
-  // TS-4 (P1): forwarded foreground input carries resolved timeout and NO
-  // run_in_background key. We spy on the inner pi tool to capture the forward.
-  it('forwards resolved timeout and strips run_in_background', async () => {
-    const tool = new LocalBashTool('/tmp/does-not-matter', undefined, { mode: 'off' });
-    const innerExecute = vi
-      .spyOn((tool as unknown as { tool: { execute: unknown } }).tool, 'execute')
-      .mockResolvedValue({ content: [{ type: 'text', text: 'ok' }], details: {} } as never);
-
-    await tool.execute(SESSION_CTX, { description: '运行测试命令', command: 'echo hi', run_in_background: false });
-
-    expect(innerExecute).toHaveBeenCalledTimes(1);
-    const forwarded = (innerExecute.mock.calls[0] as unknown[])[1] as Record<string, unknown>;
-    expect(forwarded).toEqual({ description: '运行测试命令', command: 'echo hi', timeout: 120 });
-    expect(forwarded).not.toHaveProperty('run_in_background');
-  });
-
-  it('forwards an explicit timeout unchanged and strips run_in_background', async () => {
-    const tool = new LocalBashTool('/tmp/does-not-matter', undefined, { mode: 'off' });
-    const innerExecute = vi
-      .spyOn((tool as unknown as { tool: { execute: unknown } }).tool, 'execute')
-      .mockResolvedValue({ content: [{ type: 'text', text: 'ok' }], details: {} } as never);
-
-    await tool.execute(SESSION_CTX, { description: '运行测试命令', command: 'echo hi', timeout: 7 });
-
-    const forwarded = (innerExecute.mock.calls[0] as unknown[])[1] as Record<string, unknown>;
-    expect(forwarded).toEqual({ description: '运行测试命令', command: 'echo hi', timeout: 7 });
-    expect(forwarded).not.toHaveProperty('run_in_background');
-  });
-
-  it('carries the trusted Explore read-only restriction through direct foreground identity', async () => {
-    const create = vi.fn<LocalSandboxBashOperationsFactory['create']>(() => ({
-      exec: async () => ({ exitCode: 0 }),
-    }));
-    const tool = new LocalBashTool(
-      '/tmp/does-not-matter',
-      undefined,
-      { mode: 'off' },
-      undefined,
-      { create },
-    );
-    const ctx = {
-      ...SESSION_CTX,
-      toolCallId: 'call-direct',
-      forceReadOnlyFilesystem: true,
-    };
-
-    await tool.execute(ctx, { description: '运行测试命令', command: 'true' });
-
-    expect(create).toHaveBeenCalledWith({
-      identity: {
-        operationClass: 'direct_foreground',
-        invocationId: 'call-direct',
-        sessionId: 'sess-test',
-        turnId: 'turn-test',
-        toolCallId: 'call-direct',
-        forceReadOnlyFilesystem: true,
-      },
-      workspaceRoot: '/tmp/does-not-matter',
-    });
-  });
-
-  it('uses a unique runtime id without leaking command text when old callers omit toolCallId', async () => {
-    const create = vi.fn<LocalSandboxBashOperationsFactory['create']>(() => ({
-      exec: async () => ({ exitCode: 0 }),
-    }));
-    const tool = new LocalBashTool(
-      '/tmp/does-not-matter',
-      undefined,
-      { mode: 'off' },
-      undefined,
-      { create },
-    );
-
-    await tool.execute(SESSION_CTX, { description: '运行测试命令', command: 'secret-command-one' });
-    await tool.execute(SESSION_CTX, { description: '运行测试命令', command: 'secret-command-two' });
-
-    const identities = create.mock.calls.map(([input]) => input.identity);
-    expect(identities).toHaveLength(2);
-    expect(identities[0]).toMatchObject({
-      operationClass: 'direct_foreground',
-      sessionId: 'sess-test',
-      turnId: 'turn-test',
-    });
-    expect(identities[0]?.invocationId).toMatch(/^runtime_[0-9a-f-]{36}$/);
-    expect(identities[1]?.invocationId).not.toBe(identities[0]?.invocationId);
-    expect(JSON.stringify(identities)).not.toContain('secret-command');
-  });
-});
-
-describe('LocalBashTool.execute — managed foreground soft yield', () => {
-  it.each([0, 7])('returns direct output and exit code %i when native output is absent', async (exitCode) => {
-    const runManagedForeground = vi.fn();
-    const tool = new LocalBashTool('/tmp/workspace', { startBackground: vi.fn(), runManagedForeground }, { mode: 'off' }, undefined, {
-      create: () => ({ exec: async (_command, _cwd, opts) => {
-        opts.onData(Buffer.from('direct stdout and stderr'));
-        return { exitCode };
-      } }),
-    });
-    const result = await tool.execute({ ...SESSION_CTX, allowBashAutoPromotion: true }, { description: '运行测试命令', command: 'controlled command' });
-    expect(runManagedForeground).not.toHaveBeenCalled();
-    expect(result.text).toContain('direct stdout and stderr');
-    expect(Boolean(result.isError)).toBe(exitCode !== 0);
-    expect(result.details?.task_id).toBeUndefined();
-  });
-
-  it('forwards cancellation to foreground operations when promotion is disabled', async () => {
-    const controller = new AbortController();
-    let started!: () => void;
-    const ready = new Promise<void>((resolve) => { started = resolve; });
-    const runManagedForeground = vi.fn();
-    const tool = new LocalBashTool('/tmp/workspace', { startBackground: vi.fn(), runManagedForeground }, { mode: 'off' }, undefined, {
-      create: () => ({ exec: async (_command, _cwd, opts) => {
-        expect(opts.signal).toBe(controller.signal);
-        return new Promise<never>((_, reject) => {
-          opts.signal?.addEventListener('abort', () => reject(new Error('aborted')), { once: true });
-          started();
-        });
-      } }),
-    });
-    const pending = tool.execute({ ...SESSION_CTX, allowBashAutoPromotion: false }, { description: '运行测试命令', command: 'controlled command' }, controller.signal);
-    const rejection = expect(pending).rejects.toThrow(/abort/i);
-    await ready;
-    controller.abort();
-    await rejection;
-    expect(runManagedForeground).not.toHaveBeenCalled();
-  });
-
-  it('refuses explicit background Bash before starting a task when native output is unavailable', async () => {
-    const startBackground = vi.fn(async () => ({ status: 'started' as const, taskId: 'unexpected' }));
-    const tool = new LocalBashTool(
-      '/tmp/workspace',
-      { startBackground, runManagedForeground: vi.fn() },
-      { mode: 'off' },
-    );
-
-    const result = await tool.execute(
-      { ...SESSION_CTX, canConsumeBackgroundBashOutput: false },
-      { description: '运行测试命令', command: 'controlled command', run_in_background: true },
-    );
-
-    expect(result).toMatchObject({
-      isError: true,
-      details: {
-        status: 'background_output_unavailable',
-        error_code: 'BASH_BACKGROUND_OUTPUT_UNAVAILABLE',
-      },
-    });
-    expect(result.text).toContain('missing task_output');
-    expect(result.text).toContain('foreground instead');
-    expect(startBackground).not.toHaveBeenCalled();
-  });
-
-  it('allows explicit background execution when native output is admitted', async () => {
-    const startBackground = vi.fn(async () => ({ status: 'started' as const, taskId: 'explicit-task' }));
-    const tool = new LocalBashTool('/tmp/workspace', { startBackground, runManagedForeground: vi.fn() }, { mode: 'off' });
-    const result = await tool.execute(
-      {
-        ...SESSION_CTX,
-        allowBashAutoPromotion: false,
-        canConsumeBackgroundBashOutput: true,
-      },
-      { description: '运行测试命令', command: 'controlled command', run_in_background: true },
-    );
-    expect(startBackground).toHaveBeenCalledOnce();
-    expect(result.details).toMatchObject({ status: 'started', task_id: 'explicit-task' });
-  });
-
-  it('fails closed for explicit background execution when the catalog fact is absent', async () => {
-    const startBackground = vi.fn(async () => ({ status: 'started' as const, taskId: 'explicit-task' }));
-    const tool = new LocalBashTool('/tmp/workspace', { startBackground, runManagedForeground: vi.fn() }, { mode: 'off' });
-    const result = await tool.execute(
-      { ...SESSION_CTX, allowBashAutoPromotion: false },
-      { description: '运行测试命令', command: 'controlled command', run_in_background: true },
-    );
-
-    expect(result).toMatchObject({
-      isError: true,
-      details: {
-        status: 'background_output_unavailable',
-        error_code: 'BASH_BACKGROUND_OUTPUT_UNAVAILABLE',
-      },
-    });
-    expect(startBackground).not.toHaveBeenCalled();
-  });
-
-  it('returns a completed managed command inline', async () => {
-    const runManagedForeground = vi.fn(async () => ({
-      status: 'completed' as const,
-      taskId: 'task-fast',
-      text: 'ok',
-    }));
-    const tool = new LocalBashTool('/tmp/does-not-matter', {
-      startBackground: vi.fn(),
-      runManagedForeground,
-    }, { mode: 'off' });
-
-    const result = await tool.execute({ ...SESSION_CTX, canConsumeBackgroundBashOutput: true }, { description: '运行测试命令', command: 'echo ok' });
-
-    expect(runManagedForeground).toHaveBeenCalledWith(
-      { ...SESSION_CTX, canConsumeBackgroundBashOutput: true },
-      { description: '运行测试命令', command: 'echo ok' },
-      DEFAULT_FOREGROUND_BASH_SOFT_YIELD_MS,
-      undefined,
-    );
-    expect(result).toMatchObject({ text: 'ok', details: { status: 'completed', task_id: 'task-fast' } });
-  });
-
-  it('reports managed env sanitization once per tool instance', async () => {
-    const runManagedForeground = vi.fn(async () => ({
-      status: 'completed' as const,
-      taskId: 'task-fast',
-      text: 'ok',
-      details: { envSanitized: ['MAVIS_ACCESS_TOKEN'] },
-    }));
-    const tool = new LocalBashTool('/tmp/does-not-matter', {
-      startBackground: vi.fn(),
-      runManagedForeground,
-    }, { mode: 'off' });
-
-    const first = await tool.execute({ ...SESSION_CTX, canConsumeBackgroundBashOutput: true }, { description: '运行测试命令', command: 'echo first' });
-    const second = await tool.execute({ ...SESSION_CTX, canConsumeBackgroundBashOutput: true }, { description: '运行测试命令', command: 'echo second' });
-
-    expect(first.details?.envSanitized).toEqual(['MAVIS_ACCESS_TOKEN']);
-    expect(second.details?.envSanitized).toBeUndefined();
-  });
-
-  it('returns the same task handle when a slow command is auto-promoted', async () => {
-    const tool = new LocalBashTool('/tmp/does-not-matter', {
-      startBackground: vi.fn(),
-      runManagedForeground: vi.fn(async () => ({
-        status: 'auto_promoted' as const,
-        taskId: 'task-slow',
-        details: { envSanitized: ['MAVIS_ACCESS_TOKEN'] },
-      })),
-    }, { mode: 'off' });
-
-    const result = await tool.execute({ ...SESSION_CTX, canConsumeBackgroundBashOutput: true }, { description: '运行测试命令', command: 'sleep 30' });
-
-    expect(result.details).toEqual({
-      description: '运行测试命令',
-      status: 'auto_promoted',
-      task_id: 'task-slow',
-      timing: {
-        commandTimeoutSeconds: 600,
-      },
-      envSanitized: ['MAVIS_ACCESS_TOKEN'],
-    });
-    expect(result.text).toContain('without restarting it');
-    expect(result.text).toContain('Command limit: 600s total; yielding does not reset it.');
-  });
-});
-
-describe('LocalBashTool.execute — real foreground ops', () => {
-  let workspace: string;
-
-  beforeEach(async () => {
-    workspace = await mkdtemp(join(tmpdir(), 'local-bash-'));
-  });
-  afterEach(async () => {
-    await rm(workspace, { recursive: true, force: true });
-  });
-
-  it('returns real output after the 60 second yield window when the Turn has no native task_output', async () => {
-    const runManagedForeground = vi.fn(async () => ({ status: 'auto_promoted' as const, taskId: 'unexpected-task' }));
-    const tool = new LocalBashTool(workspace, { startBackground: vi.fn(), runManagedForeground }, { mode: 'off' });
-    const startedAt = Date.now();
-    const result = await tool.execute({ ...SESSION_CTX, allowBashAutoPromotion: false }, {
-      description: '运行测试命令',
-      command: `node -e "setTimeout(() => { console.log('foreground-after-threshold'); console.error('stderr-after-threshold'); }, 61000)"`,
-      timeout: 90,
-    });
-    expect(Date.now() - startedAt).toBeGreaterThanOrEqual(60_000);
-    expect(runManagedForeground).not.toHaveBeenCalled();
-    expect(result.text).toContain('foreground-after-threshold');
-    expect(result.text).toContain('stderr-after-threshold');
-    expect(result.isError).toBeFalsy();
-    expect(result.details?.task_id).toBeUndefined();
-  }, 90_000);
-
-  // TS-5 (P1): fast foreground command with no timeout completes normally.
-  it('runs a fast foreground command with no timeout and returns real output', async () => {
-    const tool = new LocalBashTool(workspace, undefined, { mode: 'off' });
-    const result = await tool.execute(SESSION_CTX, { description: '运行测试命令', command: 'echo hi' });
-    expect(result.tool_name).toBe('bash');
-    expect(result.text).toContain('hi');
-    expect(result.isError).toBeFalsy();
-  });
-
-  // TS-6 (P1): timeout-hit surfaces the vendored error text. Driven with a very
-  // short explicit timeout against a sleep to stay fast and non-flaky.
-  it('surfaces the vendored "Command timed out after N seconds" text', async () => {
-    const tool = new LocalBashTool(workspace, undefined, { mode: 'off' });
-    const result = await tool.execute(SESSION_CTX, { description: '运行测试命令', command: 'sleep 5', timeout: 1 });
-    expect(result.isError).toBe(true);
-    expect(result.text).toMatch(/Command timed out after 1 seconds/);
-  });
-});
-
-describe('LocalBashToolDef timeout description (TS-7)', () => {
-  it('documents seconds, foreground limits, and background yielding', () => {
-    const desc = timeoutDescription();
-    expect(desc).not.toContain('host-defined');
-    expect(desc).toContain('seconds');
-    expect(desc).toContain('120');
-    expect(desc).toContain('300');
-    expect(desc).toContain('600');
-    expect(desc).toContain('including foreground time');
-    expect(desc.toLowerCase()).toContain('foreground');
-    const backgroundDesc = createLocalBashToolDefinition({ background: true, shell: 'bash' }).description;
-    expect(backgroundDesc).toContain('return a task_id if unfinished');
-    expect(backgroundDesc).toContain('60s');
-  });
-
-});
-
-describe('per-Turn Bash contract', () => {
-  it('keeps definitions isolated while hiding background parameters without native output', () => {
-    const original = JSON.stringify(LocalBashToolDef);
-    const enabled = createLocalBashToolDefinition({ background: true, shell: 'bash' });
-    const disabled = createLocalBashToolDefinition({ background: false, shell: 'bash' });
-    expect(enabled.schema.properties).toHaveProperty('run_in_background');
-    expect(disabled.schema.properties).not.toHaveProperty('run_in_background');
-    expect(JSON.stringify(disabled.schema)).not.toContain('run_in_background');
-    expect(enabled.description).toContain('Backgrounding and reading output do not reset the command timeout.');
-    expect(disabled.description).toContain('foreground execution only');
-    expect(disabled.schema.required).toEqual(['command']);
-    expect(enabled.schema.properties.timeout.description).toContain('default/max 600s');
-    expect(enabled.schema.properties.timeout.description).toContain('including foreground time');
-    expect(disabled.schema.properties.timeout.description).toContain('default 120s; values above 300s are capped');
-    expect(JSON.stringify(LocalBashToolDef)).toBe(original);
-    expect(enabled.schema.properties.timeout).not.toBe(LocalBashToolDef.schema.properties.timeout);
-    expect(disabled.description).toContain('report the failure instead of falling back to permanent deletion');
-    expect(disabled.description).toContain('dedicated `read`, `write`, `edit`, `grep`, and `glob`');
-  });
-
-  it.each([
-    ['bash', 'Selected shell: Bash', 'PowerShell 5.1'],
-    ['sh', 'Selected shell: POSIX sh', 'Selected shell: Bash'],
-    ['powershell', 'The && and || operators are unsupported', 'operators && and || are supported'],
-    ['pwsh', 'operators && and || are supported', 'operators are unsupported'],
-    ['unavailable', 'No local shell was resolved', 'Selected shell: Bash'],
-  ] as const)('describes the selected %s shell capabilities', (shell, expected, excluded) => {
-    const tool = createLocalBashToolDefinition({ background: true, shell });
-    expect(tool.description).toContain(expected);
-    expect(tool.description).not.toContain(excluded);
-    expect(tool.description).toContain('Backgrounding and reading output do not reset the command timeout.');
-  });
-});
diff --git a/packages/agent-tools/test/desktop/local-task-output-polling.test.ts b/packages/agent-tools/test/desktop/local-task-output-polling.test.ts
deleted file mode 100644
index 83a404e8..00000000
--- a/packages/agent-tools/test/desktop/local-task-output-polling.test.ts
+++ /dev/null
@@ -1,445 +0,0 @@
-import { describe, expect, it, vi } from 'vitest';
-
-import type { BackgroundTask } from '@mavis/background-task';
-import { PiTurnRunner } from '@mavis/agent-core/pi-turn-runner';
-import type { RuntimeTool } from '@mavis/agent-core/tools';
-import type { StreamFn } from '@earendil-works/pi-agent-core';
-import type { Api, AssistantMessage, Model } from '@earendil-works/pi-ai';
-
-import { LocalTaskOutputToolDef } from '../../src/desktop/builtin-defs.js';
-import { LocalTaskOutputTool } from '../../src/desktop/local-task-control.js';
-import type {
-  LocalRuntimeToolContext,
-  LocalTaskControlAdapter,
-  LocalTaskOutputReadResult,
-} from '../../src/desktop/types.js';
-
-const context: LocalRuntimeToolContext = { sessionId: 'owner', turnId: 'turn-1' };
-const replay = { task_id: 'bg_1', offset: 0, wait_ms: 30_000 };
-const running: LocalTaskOutputReadResult = {
-  content: 'Compiling\n',
-  status: 'running',
-  nextOffset: 312,
-  truncated: false,
-  timedOut: false,
-};
-
-function fixture() {
-  const get = vi.fn<LocalTaskControlAdapter['get']>(async (ctx, taskId) => ({
-    taskId,
-    ownerSessionId: ctx.sessionId,
-    kind: 'bash',
-    status: 'running',
-    createdAt: 1,
-    updatedAt: 1,
-  }));
-  const readOutput = vi.fn<LocalTaskControlAdapter['readOutput']>(async () => ({ ...running }));
-  const adapter: LocalTaskControlAdapter = {
-    get,
-    readOutput,
-    list: async () => ({ items: [] }),
-    stop: async () => undefined,
-  };
-  return { tool: new LocalTaskOutputTool(adapter), get, readOutput };
-}
-
-it('shows incomplete persistence even when the command itself succeeded', async () => {
-  const { tool, get, readOutput } = fixture();
-  get.mockResolvedValue({
-    taskId: 'bg_1', ownerSessionId: 'owner', kind: 'bash', status: 'succeeded', createdAt: 1, updatedAt: 2,
-    metadata: { bashDetails: { output: { persistence: 'incomplete', rawBytes: 1234 } } },
-  });
-  readOutput.mockResolvedValue({ content: 'saved portion', status: 'succeeded', nextOffset: 100 });
-  const result = await tool.execute(context, { task_id: 'bg_1' });
-  expect(result.text).toContain('Output persistence is incomplete');
-  expect(result.text).toContain('saved portion');
-  expect(result.details?.output).toMatchObject({ rawBytes: 1234 });
-});
-
-const piTestModel: Model<Api> = {
-  id: 'test-model',
-  name: 'test-model',
-  api: 'anthropic-messages',
-  provider: 'test-provider',
-  baseUrl: 'https://example.invalid',
-  reasoning: false,
-  input: ['text'],
-  cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-  contextWindow: 200_000,
-  maxTokens: 8_192,
-};
-
-function assistantMessage(
-  content: AssistantMessage['content'],
-  stopReason: AssistantMessage['stopReason'],
-): AssistantMessage {
-  return {
-    role: 'assistant',
-    content,
-    api: piTestModel.api,
-    provider: piTestModel.provider,
-    model: piTestModel.id,
-    usage: {
-      input: 1,
-      output: 1,
-      cacheRead: 0,
-      cacheWrite: 0,
-      totalTokens: 2,
-      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
-    },
-    stopReason,
-    timestamp: 0,
-  };
-}
-
-function resultOnlyStream(message: AssistantMessage) {
-  return {
-    async *[Symbol.asyncIterator]() {
-      yield { type: 'done', reason: message.stopReason, message };
-    },
-    async result() {
-      return message;
-    },
-  } as never;
-}
-
-function piToolCallStream(
-  calls: readonly { readonly id: string; readonly arguments: Record<string, unknown> }[],
-): StreamFn {
-  let invocation = 0;
-  return (async () => {
-    const message =
-      invocation++ === 0
-        ? assistantMessage(
-            calls.map((call) => ({
-              type: 'toolCall',
-              id: call.id,
-              name: 'task_output',
-              arguments: call.arguments,
-            })),
-            'toolUse',
-          )
-        : assistantMessage([{ type: 'text', text: 'done' }], 'stop');
-    return resultOnlyStream(message);
-  }) as StreamFn;
-}
-
-it.each(['succeeded', 'failed', 'canceled', 'lost'] as const)(
-  'successfully reads output from a %s task',
-  async (status) => {
-    const { tool, get, readOutput } = fixture();
-    get.mockResolvedValue({
-      taskId: 'bg_1',
-      ownerSessionId: 'owner',
-      kind: 'bash',
-      status,
-      createdAt: 1,
-      updatedAt: 2,
-    });
-    readOutput.mockResolvedValue({ content: 'saved command output', status, nextOffset: 20 });
-    const result = await tool.execute(context, { task_id: 'bg_1' });
-    expect(result.isError).not.toBe(true);
-    expect(result.details).toMatchObject({ task_id: 'bg_1', status, next_offset: 20 });
-    expect(result.text).toContain('saved command output');
-  },
-);
-
-describe('task_output polling guidance', () => {
-  it('lets Pi validate raw task_output arguments before executing capped waits', async () => {
-    const readOutput = vi.fn<LocalTaskControlAdapter['readOutput']>(async () => ({
-      content: '',
-      status: 'running',
-      timedOut: true,
-    }));
-    const adapter: LocalTaskControlAdapter = {
-      get: async () => ({
-        taskId: 'bg_1',
-        ownerSessionId: context.sessionId,
-        kind: 'bash',
-        status: 'running',
-        createdAt: 1,
-        updatedAt: 1,
-      }),
-      readOutput,
-      list: async () => ({ items: [] }),
-      stop: async () => undefined,
-    };
-    const rawCalls = [
-      { id: 'oversized-60', arguments: { task_id: 'bg_1', wait_ms: 60_000 } },
-      { id: 'oversized-120', arguments: { task_id: 'bg_1', wait_ms: 120_000 } },
-      { id: 'oversized-300', arguments: { task_id: 'bg_1', wait_ms: 300_000 } },
-      { id: 'negative', arguments: { task_id: 'bg_1', wait_ms: -1 } },
-      { id: 'fraction', arguments: { task_id: 'bg_1', wait_ms: 0.5 } },
-      { id: 'string', arguments: { task_id: 'bg_1', wait_ms: '60000' } },
-      { id: 'null', arguments: { task_id: 'bg_1', wait_ms: null } },
-      { id: 'infinity', arguments: { task_id: 'bg_1', wait_ms: Number.POSITIVE_INFINITY } },
-      { id: 'nan', arguments: { task_id: 'bg_1', wait_ms: Number.NaN } },
-    ];
-    const history: unknown[] = [];
-    const stepResults: unknown[] = [];
-    const tool: RuntimeTool = {
-      def: LocalTaskOutputToolDef,
-      impl: new LocalTaskOutputTool(adapter),
-      source: 'builtin',
-    };
-
-    await new PiTurnRunner().runTurn({
-      sessionId: context.sessionId,
-      turnId: context.turnId,
-      workspaceDir: '/workspace',
-      systemPrompt: '',
-      userMessage: { text: 'read task output' },
-      llm: { model: piTestModel, streamFn: piToolCallStream(rawCalls) },
-      eventWriter: { pushRuntime: () => undefined, appendEvents: () => undefined },
-      toolConfig: { tools: [tool], disableBuiltinToolFallback: true, context },
-      hooks: {
-        onStepEndHook: [
-          ({ toolResults }) => {
-            stepResults.push(...structuredClone(toolResults));
-          },
-        ],
-        onHistoryChangedHook: [
-          ({ reason, messages }) => {
-            if (reason === 'messageDelta') history.push(...structuredClone(messages));
-          },
-        ],
-      },
-    });
-
-    expect(readOutput).toHaveBeenCalledTimes(3);
-    for (const [, , options] of readOutput.mock.calls) {
-      expect(options).toMatchObject({ waitMs: 30_000 });
-    }
-    const invalidCallIds = new Set(rawCalls.slice(3).map((call) => call.id));
-    const invalidResults = (
-      stepResults as Array<{
-        readonly toolCallId: string;
-        readonly isError: boolean;
-      }>
-    ).filter((result) => invalidCallIds.has(result.toolCallId));
-    expect(invalidResults).toHaveLength(invalidCallIds.size);
-    expect(invalidResults.every((result) => result.isError)).toBe(true);
-    const assistant = history.find(
-      (message): message is { readonly role: 'assistant'; readonly content: readonly unknown[] } =>
-        typeof message === 'object' &&
-        message !== null &&
-        (message as { role?: unknown }).role === 'assistant',
-    );
-    expect(assistant?.content).toEqual(
-      expect.arrayContaining([
-        expect.objectContaining({
-          id: 'oversized-60',
-          arguments: { task_id: 'bg_1', wait_ms: 60_000 },
-        }),
-        expect.objectContaining({
-          id: 'oversized-120',
-          arguments: { task_id: 'bg_1', wait_ms: 120_000 },
-        }),
-        expect.objectContaining({
-          id: 'oversized-300',
-          arguments: { task_id: 'bg_1', wait_ms: 300_000 },
-        }),
-      ]),
-    );
-  });
-
-  it('corrects repeated offset=0 reads with the returned cursor without changing replay semantics', async () => {
-    const { tool, readOutput } = fixture();
-    const first = await tool.execute(context, replay);
-    const repeated = await tool.execute(context, replay);
-
-    expect(first.text).not.toContain('<task_output_hint>');
-    expect(repeated.text).toContain('Task status and next_offset are unchanged');
-    expect(repeated.text).toContain('task_output({"task_id":"bg_1","offset":312,"wait_ms":30000})');
-    expect(repeated.text).toContain('offset=0 replays existing output');
-    expect(repeated.text).toContain(running.content);
-    expect(repeated.details).toEqual(first.details);
-    expect(repeated.content).toEqual([{ type: 'text', text: repeated.text }]);
-    expect(readOutput.mock.calls.map(([, , options]) => options)).toEqual([
-      { offset: 0, waitMs: 30_000 },
-      { offset: 0, waitMs: 30_000 },
-    ]);
-    expect(replay.offset).toBe(0);
-  });
-
-  it.each([undefined, 0])('corrects unchanged empty reads with wait_ms=%s', async (waitMs) => {
-    const { tool, readOutput } = fixture();
-    readOutput.mockResolvedValue({ content: '', nextOffset: 312, status: 'running' });
-    const input = { task_id: 'bg_1', offset: 312, ...(waitMs === undefined ? {} : { wait_ms: waitMs }) };
-    await tool.execute(context, input);
-    const repeated = await tool.execute(context, input);
-
-    expect(repeated.text).toContain('"offset":312,"wait_ms":30000');
-    expect(repeated.text).toContain('(no output yet)');
-    expect(readOutput).toHaveBeenLastCalledWith(context, 'bg_1', {
-      offset: 312,
-      waitMs: waitMs ?? 0,
-    });
-  });
-
-  it('preserves automatic cursor reads while providing an explicit recovery call', async () => {
-    const { tool, readOutput } = fixture();
-    readOutput.mockResolvedValue({ content: '', nextOffset: 312, status: 'running' });
-    await tool.execute(context, { task_id: 'bg_1' });
-    const repeated = await tool.execute(context, { task_id: 'bg_1' });
-
-    expect(repeated.text).toContain('"offset":312,"wait_ms":30000');
-    expect(readOutput).toHaveBeenLastCalledWith(context, 'bg_1', { waitMs: 0 });
-    expect(repeated.details).toMatchObject({ effective_wait_ms: 0, wait_ms_clamped: false });
-  });
-
-  it.each([30_001, 60_000, 300_000])(
-    'caps oversized wait_ms=%s while preserving the requested value for diagnostics',
-    async (waitMs) => {
-      const { tool, readOutput } = fixture();
-      readOutput.mockResolvedValue({ ...running, content: '', timedOut: true });
-      const input = { task_id: 'bg_1', offset: 312, wait_ms: waitMs };
-
-      const result = await tool.execute(context, input);
-
-      expect(input.wait_ms).toBe(waitMs);
-      expect(readOutput).toHaveBeenCalledWith(context, 'bg_1', { offset: 312, waitMs: 30_000 });
-      expect(result.text).toContain(
-        '<task_output_hint>Your requested wait_ms exceeded 30000 ms and was capped at 30000 ms (30 seconds). This output read reached its wait limit; the background task was not stopped. Use wait_ms=30000 or less for future reads.</task_output_hint>',
-      );
-      expect(result.details).toMatchObject({
-        effective_wait_ms: 30_000,
-        wait_ms_clamped: true,
-        timed_out: true,
-      });
-    },
-  );
-
-  it.each([
-    { read: { ...running, timedOut: true }, waitMs: 30_000 },
-    { read: { ...running, timedOut: false }, waitMs: 60_000 },
-    { read: { ...running, status: 'succeeded' as const, timedOut: false }, waitMs: 60_000 },
-  ])(
-    'does not describe a cap timeout when the read returns early: %j',
-    async ({ read, waitMs }) => {
-      const { tool, readOutput } = fixture();
-      readOutput.mockResolvedValue(read);
-
-      const result = await tool.execute(context, { task_id: 'bg_1', wait_ms: waitMs });
-
-      expect(result.text).not.toContain('Your requested wait_ms exceeded 30000 ms');
-      expect(result.details).toMatchObject({
-        effective_wait_ms: waitMs > 30_000 ? 30_000 : waitMs,
-        wait_ms_clamped: waitMs > 30_000,
-      });
-    },
-  );
-
-  it('does not describe a capped wait as timed out after cancellation', async () => {
-    const { tool, readOutput } = fixture();
-    const controller = new AbortController();
-    controller.abort();
-    readOutput.mockResolvedValue({ ...running, content: '', timedOut: true });
-
-    const result = await tool.execute(
-      context,
-      { task_id: 'bg_1', wait_ms: 60_000 },
-      controller.signal,
-    );
-
-    expect(result.text).not.toContain('Your requested wait_ms exceeded 30000 ms');
-    expect(result.details).toMatchObject({ effective_wait_ms: 30_000, wait_ms_clamped: true });
-  });
-
-  it('does not warn on a normal long-poll timeout but still detects the following immediate check', async () => {
-    const { tool, readOutput } = fixture();
-    readOutput.mockResolvedValue({ ...running, content: '', timedOut: true });
-    await tool.execute(context, { ...replay, offset: 312 });
-    const timeout = await tool.execute(context, { ...replay, offset: 312 });
-    expect(timeout.text).not.toContain('<task_output_hint>');
-    expect(timeout.details).toMatchObject({ timed_out: true, next_offset: 312 });
-
-    readOutput.mockResolvedValue({ ...running, content: '', timedOut: undefined });
-    const immediate = await tool.execute(context, { task_id: 'bg_1', offset: 312 });
-    expect(immediate.text).toContain('<task_output_hint>');
-  });
-
-  it('resets the comparison when output advances or task status changes', async () => {
-    const { tool, readOutput } = fixture();
-    await tool.execute(context, replay);
-    readOutput.mockResolvedValue({ ...running, nextOffset: 344 });
-    expect((await tool.execute(context, replay)).text).not.toContain('<task_output_hint>');
-    readOutput.mockResolvedValue({ ...running, nextOffset: 344, status: 'stopping' });
-    expect((await tool.execute(context, replay)).text).not.toContain('<task_output_hint>');
-    expect((await tool.execute(context, replay)).text).toContain('"offset":344');
-  });
-
-  it.each<BackgroundTask['status']>(['succeeded', 'failed', 'canceled', 'lost'])(
-    'does not recommend waiting on a %s task and forgets the previous active read',
-    async (status) => {
-      const { tool, readOutput } = fixture();
-      await tool.execute(context, replay);
-      readOutput.mockResolvedValue({ ...running, status });
-      expect((await tool.execute(context, replay)).text).not.toContain('<task_output_hint>');
-      expect((await tool.execute(context, replay)).text).not.toContain('<task_output_hint>');
-      readOutput.mockResolvedValue(running);
-      expect((await tool.execute(context, replay)).text).not.toContain('<task_output_hint>');
-    },
-  );
-
-  it.each([
-    { ctx: { ...context, sessionId: 'other-owner' }, input: replay },
-    { ctx: { ...context, turnId: 'turn-2' }, input: replay },
-    { ctx: context, input: { ...replay, task_id: 'bg_2' } },
-  ])('only compares consecutive reads of the same session, Turn and task: %j', async ({ ctx, input }) => {
-    const { tool } = fixture();
-    await tool.execute(context, replay);
-    expect((await tool.execute(ctx, input)).text).not.toContain('<task_output_hint>');
-    expect((await tool.execute(context, replay)).text).not.toContain('<task_output_hint>');
-    expect((await tool.execute(context, replay)).text).toContain('<task_output_hint>');
-  });
-
-  it.each([undefined, -1, 0.5, Number.NaN, Number.POSITIVE_INFINITY])(
-    'never invents continuation arguments for an invalid cursor %s',
-    async (nextOffset) => {
-      const { tool, readOutput } = fixture();
-      await tool.execute(context, replay);
-      readOutput.mockResolvedValue({ ...running, nextOffset });
-      await tool.execute(context, replay);
-      expect((await tool.execute(context, replay)).text).not.toContain('<task_output_hint>');
-      readOutput.mockResolvedValue(running);
-      expect((await tool.execute(context, replay)).text).not.toContain('<task_output_hint>');
-    },
-  );
-
-  it('clears the comparison on task-not-found without turning it into polling advice', async () => {
-    const { tool, get } = fixture();
-    await tool.execute(context, replay);
-    get.mockResolvedValueOnce(undefined);
-    const missing = await tool.execute(context, replay);
-    expect(missing.isError).toBe(true);
-    expect(missing.details).toMatchObject({ effective_wait_ms: 30_000, wait_ms_clamped: false });
-    expect(missing.text).not.toContain('<task_output_hint>');
-    expect((await tool.execute(context, replay)).text).not.toContain('<task_output_hint>');
-  });
-
-  it('does not learn a failed or canceled read and forwards cancellation unchanged', async () => {
-    const { tool, readOutput } = fixture();
-    readOutput.mockRejectedValueOnce(new Error('read failed'));
-    await expect(tool.execute(context, replay)).rejects.toThrow('read failed');
-    const controller = new AbortController();
-    controller.abort();
-    const canceled = await tool.execute(context, replay, controller.signal);
-    expect(canceled.text).not.toContain('<task_output_hint>');
-    expect(readOutput).toHaveBeenLastCalledWith(context, 'bg_1', {
-      offset: 0, waitMs: 30_000, signal: controller.signal,
-    });
-    expect((await tool.execute(context, replay)).text).not.toContain('<task_output_hint>');
-    expect((await tool.execute(context, replay)).text).toContain('<task_output_hint>');
-  });
-
-  it('preserves truncated replay output and points to the next page without claiming the task is finished', async () => {
-    const { tool, readOutput } = fixture();
-    readOutput.mockResolvedValue({ ...running, truncated: true });
-    await tool.execute(context, replay);
-    const repeated = await tool.execute(context, replay);
-    expect(repeated.text).toContain(running.content);
-    expect(repeated.text).toContain('"offset":312');
-    expect(repeated.details).toMatchObject({ truncated: true, status: 'running', next_offset: 312 });
-  });
-});
diff --git a/packages/local-runtime-v2/src/service/background-bash/executor.test.ts b/packages/local-runtime-v2/src/service/background-bash/executor.test.ts
deleted file mode 100644
index 6a47c3ed..00000000
--- a/packages/local-runtime-v2/src/service/background-bash/executor.test.ts
+++ /dev/null
@@ -1,233 +0,0 @@
-import { afterEach, describe, expect, it, vi } from 'vitest';
-
-import type { BashOperations } from '@earendil-works/pi-coding-agent/tools';
-import { resolveBashEnvPolicy } from '@mavis/agent-core/bash-subprocess-env';
-import type { LocalSandboxInvocationIdentity } from '@mavis/agent-tools/desktop';
-
-import { createLocalBackgroundBashExecutor } from './executor.js';
-
-const identity: LocalSandboxInvocationIdentity = {
-  operationClass: 'managed_foreground',
-  invocationId: 'task-1',
-  sessionId: 'session-1',
-  turnId: 'turn-1',
-  toolCallId: 'tool-1',
-  taskId: 'task-1',
-};
-
-it('streams a single complete log while returning bounded original head and tail', async () => {
-  const raw = Buffer.from(`FIRST汉${'中文'.repeat(20_000)}LAST末`);
-  let persisted = '';
-  let bytes = 0;
-  const executor = createLocalBackgroundBashExecutor(
-    {
-      create: () => ({
-        separatesOutputStreams: true,
-        exec: async (_command, _cwd, options) => {
-          for (let i = 0; i < raw.length; i += 31)
-            options.onData(raw.subarray(i, i + 31), 'stdout');
-          return { exitCode: 7 };
-        },
-      }),
-    },
-    { mode: 'off' },
-  );
-  const result = await executor.execute({
-    identity,
-    workspaceRoot: process.cwd(),
-    command: 'test',
-    signal: new AbortController().signal,
-    onOutput: (text, byteLength) => {
-      persisted += text;
-      bytes += byteLength ?? 0;
-    },
-  });
-  expect(persisted).toBe(raw.toString('utf8'));
-  expect(bytes).toBe(raw.length);
-  expect(result.text).toContain('FIRST汉');
-  expect(result.text).toContain('LAST末');
-  expect(result.text).not.toContain('�');
-  expect(Buffer.byteLength(result.text)).toBeLessThan(24 * 1024);
-  expect(result.isError).toBe(true);
-  expect(result.details?.fullOutputPath).toBeUndefined();
-  expect(result.details?.output).toMatchObject({ rawBytes: raw.length, persistence: 'host' });
-});
-
-describe('createLocalBackgroundBashExecutor', () => {
-  const seeded: string[] = [];
-
-  afterEach(() => {
-    for (const name of seeded.splice(0)) delete process.env[name];
-  });
-
-  it('hands the running callback to the operations path instead of firing it first', async () => {
-    const events: string[] = [];
-    const onPreflightComplete = () => {
-      events.push('preflight');
-    };
-    const create = vi.fn(
-      (input: { onPreflightComplete?: () => void | Promise<void> }): BashOperations => ({
-        separatesOutputStreams: true,
-        exec: async (_command, _cwd, options) => {
-          await input.onPreflightComplete?.();
-          events.push('exec');
-          options.onData(Buffer.from('ok'), 'stdout');
-          return { exitCode: 0 };
-        },
-      }),
-    );
-    const executor = createLocalBackgroundBashExecutor({ create }, { mode: 'off' });
-
-    const result = await executor.execute({
-      identity,
-      workspaceRoot: process.cwd(),
-      command: 'echo ok',
-      signal: new AbortController().signal,
-      onPreflightComplete,
-    });
-
-    expect(create).toHaveBeenCalledWith({
-      identity,
-      workspaceRoot: process.cwd(),
-      onPreflightComplete,
-    });
-    expect(events).toEqual(['preflight', 'exec']);
-    expect(result.text).toContain('ok');
-    expect(result.details).toMatchObject({
-      execution: { status: 'succeeded', reason: 'exited', exitCode: 0 },
-      processOutput: { stdout: 'ok', stderr: '', exitCode: 0 },
-    });
-  });
-
-  it('returns failed execution facts and split output without losing them to an exception', async () => {
-    const executor = createLocalBackgroundBashExecutor(
-      {
-        create: () => ({
-          separatesOutputStreams: true,
-          exec: async (_command, _cwd, options) => {
-            options.onData(Buffer.from('out'), 'stdout');
-            options.onData(Buffer.from('err'), 'stderr');
-            return { exitCode: 7 };
-          },
-        }),
-      },
-      { mode: 'off' },
-    );
-    const result = await executor.execute({
-      identity,
-      workspaceRoot: process.cwd(),
-      command: 'unused',
-      signal: new AbortController().signal,
-    });
-    expect(result).toMatchObject({
-      isError: true,
-      details: {
-        execution: { status: 'failed', reason: 'exited', exitCode: 7 },
-        processOutput: { stdout: 'out', stderr: 'err', exitCode: 7 },
-      },
-    });
-    expect(result.text).toContain('Command exited with code 7');
-  });
-
-  it('never marks the task running when the operations factory rejects admission', async () => {
-    const onPreflightComplete = vi.fn();
-    const admissionFailure = new Error('Sandbox Bash operations are unavailable');
-    const executor = createLocalBackgroundBashExecutor(
-      {
-        create: () => {
-          throw admissionFailure;
-        },
-      },
-      { mode: 'off' },
-    );
-
-    await expect(
-      executor.execute({
-        identity,
-        workspaceRoot: process.cwd(),
-        command: 'echo ok',
-        signal: new AbortController().signal,
-        onPreflightComplete,
-      }),
-    ).rejects.toBe(admissionFailure);
-    expect(onPreflightComplete).not.toHaveBeenCalled();
-  });
-
-  it('preserves a sandbox preflight error code without marking execution as started', async () => {
-    const onPreflightComplete = vi.fn();
-    const executor = createLocalBackgroundBashExecutor(
-      {
-        create: () => ({
-          exec: async () => {
-            throw Object.assign(new Error('Sandbox wrapping failed'), {
-              code: 'SANDBOX_WRAP_FAILED',
-              stage: 'pre-spawn',
-            });
-          },
-        }),
-      },
-      { mode: 'off' },
-    );
-    const result = await executor.execute({
-      identity,
-      workspaceRoot: process.cwd(),
-      command: 'unused',
-      signal: new AbortController().signal,
-      onPreflightComplete,
-    });
-    expect(result).toMatchObject({
-      isError: true,
-      text: 'Sandbox wrapping failed',
-      details: {
-        execution: {
-          status: 'failed',
-          reason: 'preflight_failed',
-          exitCode: null,
-          errorCode: 'SANDBOX_WRAP_FAILED',
-        },
-      },
-    });
-    expect(onPreflightComplete).not.toHaveBeenCalled();
-  });
-
-  it('keeps the shared Bash env sanitizer in the moved executor', async () => {
-    process.env.MAVIS_BASH_ENV_SANITIZE = 'strict';
-    process.env.MAVIS_ACCESS_TOKEN = 'background-boundary-secret';
-    process.env.SANDBOX_BACKGROUND_SECRET_TOKEN = 'background-pattern-secret';
-    process.env.SANDBOX_BACKGROUND_KEEP = 'background-visible';
-    seeded.push(
-      'MAVIS_BASH_ENV_SANITIZE',
-      'MAVIS_ACCESS_TOKEN',
-      'SANDBOX_BACKGROUND_SECRET_TOKEN',
-      'SANDBOX_BACKGROUND_KEEP',
-    );
-    let childEnv: NodeJS.ProcessEnv | undefined;
-    const executor = createLocalBackgroundBashExecutor(
-      {
-        create: () => ({
-          exec: async (_command, _cwd, options) => {
-            childEnv = options.env;
-            return { exitCode: 0 };
-          },
-        }),
-      },
-      // The moved executor must keep honouring the shared resolution chain
-      // (MAVIS_BASH_ENV_SANITIZE seeded above), now supplied by the caller.
-      resolveBashEnvPolicy(),
-    );
-
-    const result = await executor.execute({
-      identity: { ...identity, operationClass: 'explicit_background' },
-      workspaceRoot: process.cwd(),
-      command: 'true',
-      signal: new AbortController().signal,
-    });
-
-    expect(childEnv?.MAVIS_ACCESS_TOKEN).toBeUndefined();
-    expect(childEnv?.SANDBOX_BACKGROUND_SECRET_TOKEN).toBeUndefined();
-    expect(childEnv?.SANDBOX_BACKGROUND_KEEP).toBe('background-visible');
-    expect(result.details?.envSanitized).toEqual(
-      expect.arrayContaining(['MAVIS_ACCESS_TOKEN', 'SANDBOX_BACKGROUND_SECRET_TOKEN']),
-    );
-  });
-});
diff --git a/packages/local-runtime-v2/src/service/turn-system/agent-host/execution/executor.test.ts b/packages/local-runtime-v2/src/service/turn-system/agent-host/execution/executor.test.ts
index 151012d6..3c57db5f 100644
--- a/packages/local-runtime-v2/src/service/turn-system/agent-host/execution/executor.test.ts
+++ b/packages/local-runtime-v2/src/service/turn-system/agent-host/execution/executor.test.ts
@@ -955,7 +955,7 @@ describe("LocalRuntimeTurnExecutor Bash output capability", () => {
         expect(admittedBash.def.schema).not.toBe(bash.def.schema);
         const result = await admittedBash.impl.execute(
           toolContext,
-          { description: '运行测试命令', command: 'controlled command' },
+          { command: "controlled command" },
           runInput.signal,
         );
         if (allowed) expect(result.details?.status).toBe("auto_promoted");
@@ -965,11 +965,7 @@ describe("LocalRuntimeTurnExecutor Bash output capability", () => {
         }
         const backgroundResult = await admittedBash.impl.execute(
           toolContext,
-          {
-            description: '运行测试命令',
-            command: 'controlled background command',
-            run_in_background: true,
-          },
+          { command: "controlled background command", run_in_background: true },
           runInput.signal,
         );
         if (allowed) {
@@ -1000,9 +996,7 @@ describe("LocalRuntimeTurnExecutor Bash output capability", () => {
       expect(direct).toHaveBeenCalledTimes(allowed ? 0 : 1);
     },
   );
-});
 
-describe('LocalRuntimeTurnExecutor native output provenance', () => {
   it.each([
     { source: undefined, allowed: true },
     { source: "builtin" as const, allowed: true },
@@ -1051,8 +1045,7 @@ describe('LocalRuntimeTurnExecutor native output provenance', () => {
           const result = await admittedBash.impl.execute(
             toolContext,
             {
-              description: '运行测试命令',
-              command: 'controlled background command',
+              command: "controlled background command",
               run_in_background: true,
             },
             runInput.signal,
diff --git a/packages/local-runtime/test/unit/child-bash-lifecycle.test.ts b/packages/local-runtime/test/unit/child-bash-lifecycle.test.ts
index 4ce07865..f956363a 100644
--- a/packages/local-runtime/test/unit/child-bash-lifecycle.test.ts
+++ b/packages/local-runtime/test/unit/child-bash-lifecycle.test.ts
@@ -188,12 +188,12 @@ describe('child Bash lifecycle', () => {
         mode === 'explicit'
           ? await adapter.startBackground(
               toolContext('child'),
-              { description: '运行测试命令', command, run_in_background: true },
+              { command, run_in_background: true },
               controller.signal,
             )
           : await adapter.runManagedForeground!(
               toolContext('child'),
-              { description: '运行测试命令', command },
+              { command },
               1,
               controller.signal,
             );
@@ -240,7 +240,6 @@ describe('real child Bash boundaries', () => {
       const receipt = await tool.execute(
         { ...toolContext('child'), canConsumeBackgroundBashOutput: true },
         {
-          description: '运行测试命令',
           command: nodeCommand("setTimeout(() => console.log('after-real-soft-yield'), 61500)"),
         },
         controller.signal,
@@ -294,7 +293,6 @@ describe('real child Bash boundaries', () => {
       const receipt = await adapter.startBackground(
         toolContext('child'),
         {
-          description: '运行测试命令',
           command: nodeCommand(script),
           ...(mode === 'timeout' ? { timeout: 1 } : {}),
         },
diff --git a/packages/local-runtime/test/unit/local-background-bash-review-regressions.test.ts b/packages/local-runtime/test/unit/local-background-bash-review-regressions.test.ts
deleted file mode 100644
index 2dfdecc7..00000000
--- a/packages/local-runtime/test/unit/local-background-bash-review-regressions.test.ts
+++ /dev/null
@@ -1,430 +0,0 @@
-import { mkdtemp, rm } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-
-import { describe, expect, it } from 'vitest';
-
-import {
-  runManagedForegroundLocalBash,
-  startBackgroundLocalBash,
-} from '../../src/background-task/bash-runner.js';
-import { recordBashMetrics } from '../../src/background-task/bash-runner-lifecycle.js';
-import { BackgroundBashOutputWriter } from '../../src/background-task/bash-output-writer.js';
-import type { LocalTaskRunnerHostWithSessionLookup } from '../../src/api/local-task-host.js';
-import { LocalBackgroundTaskService } from '../../src/background-task/service.js';
-import {
-  FsLocalTaskOutputStore,
-  SqliteLocalBackgroundTaskStore,
-} from '../../src/background-task/store.js';
-import { closeLocalRuntimeDb } from '../../src/persistence/db.js';
-import {
-  backgroundBashHost,
-  parentSessionRecord,
-  toolContext,
-  waitForTaskStatus,
-} from './background-task-test-helpers.js';
-
-describe('local background bash review regressions', () => {
-  it('records Bash completion correlation even when the metrics client throws', () => {
-    const recorded: unknown[] = [];
-    const host = {
-      metricsClient: {
-        counter: () => {
-          throw new Error('metrics unavailable');
-        },
-      },
-      matrixLogger: {
-        warn: () => {
-          throw new Error('logger unavailable');
-        },
-      },
-      recordSessionBashCompletion: (sessionId: string, completion: unknown) =>
-        recorded.push({ sessionId, completion }),
-    } as unknown as LocalTaskRunnerHostWithSessionLookup;
-
-    expect(() =>
-      recordBashMetrics(
-        host,
-        'session-a',
-        {
-          taskId: 'task-a',
-          status: 'succeeded',
-          text: '',
-          endedAt: 2_000,
-          durationMs: 1_000,
-          outputBytes: 0,
-        },
-        'managed_foreground',
-      ),
-    ).not.toThrow();
-
-    expect(recorded).toEqual([
-      { sessionId: 'session-a', completion: { endedAt: 2_000, durationMs: 1_000 } },
-    ]);
-  });
-
-  it('aligns arbitrary byte offsets before returning a four-byte UTF-8 code point', async () => {
-    const dataDir = await mkdtemp(join(tmpdir(), 'local-background-bash-utf8-range-'));
-    try {
-      const outputStore = new FsLocalTaskOutputStore(dataDir);
-      await outputStore.append({ taskId: 'utf8-offset', content: '😀😀' });
-
-      const page = await outputStore.read('utf8-offset', { offset: 1, limitBytes: 1 });
-      const fractionalPage = await outputStore.read('utf8-offset', {
-        offset: 1.5,
-        limitBytes: 1,
-      });
-
-      expect(page.content).toBe('😀');
-      expect(page.content).not.toContain('�');
-      expect(page.nextOffset).toBe(8);
-      expect(page.truncated).toBe(false);
-      expect(fractionalPage).toMatchObject(page);
-    } finally {
-      await rm(dataDir, { recursive: true, force: true });
-    }
-  });
-
-  it('propagates a parent abort from managed foreground instead of returning completed', async () => {
-    const dataDir = await mkdtemp(join(tmpdir(), 'local-managed-bash-parent-abort-'));
-    try {
-      const service = new LocalBackgroundTaskService({
-        store: new SqliteLocalBackgroundTaskStore(dataDir, () => 71_000),
-        outputStore: new FsLocalTaskOutputStore(dataDir),
-        nowMs: () => 71_000,
-      });
-      const host = backgroundBashHost(service, dataDir);
-      const parentAbort = new AbortController();
-      let markExecutorStarted!: () => void;
-      const executorStarted = new Promise<void>((resolve) => {
-        markExecutorStarted = resolve;
-      });
-      const result = runManagedForegroundLocalBash({
-        host,
-        parentSession: parentSessionRecord(dataDir),
-        toolCtx: toolContext('session-a'),
-        bashInput: { command: 'wait for cancel', timeout: 120 },
-        softYieldMs: 5_000,
-        signal: parentAbort.signal,
-        executor: {
-          execute: ({ signal }) =>
-            new Promise((_resolve, reject) => {
-              signal.addEventListener('abort', () => reject(signal.reason), { once: true });
-              markExecutorStarted();
-            }),
-        },
-      });
-
-      await executorStarted;
-      const abortError = Object.assign(new Error('Operation aborted'), { name: 'AbortError' });
-      parentAbort.abort(abortError);
-
-      await expect(result).rejects.toBe(abortError);
-      const tasks = await service.list({ ownerSessionId: 'session-a' });
-      expect(tasks.items).toHaveLength(1);
-      expect(tasks.items[0]?.status).toBe('canceled');
-    } finally {
-      closeLocalRuntimeDb(dataDir);
-      await rm(dataDir, { recursive: true, force: true });
-    }
-  });
-
-  it('repairs task output after a streamed append fails mid-command', async () => {
-    const dataDir = await mkdtemp(join(tmpdir(), 'local-background-bash-output-repair-'));
-    try {
-      const backingOutputStore = new FsLocalTaskOutputStore(dataDir);
-      let appendCount = 0;
-      const service = new LocalBackgroundTaskService({
-        store: new SqliteLocalBackgroundTaskStore(dataDir, () => 72_000),
-        outputStore: {
-          append: async (chunk) => {
-            appendCount += 1;
-            if (appendCount === 2) throw new Error('transient output append failure');
-            return backingOutputStore.append(chunk);
-          },
-          read: (taskId, options) => backingOutputStore.read(taskId, options),
-          tail: (taskId, limitBytes) => backingOutputStore.tail(taskId, limitBytes),
-          finalize: (taskId, summary) => backingOutputStore.finalize(taskId, summary),
-        },
-        nowMs: () => 72_000,
-      });
-      const host = backgroundBashHost(service, dataDir);
-      const first = `${'a'.repeat(65_535)}中`;
-      const expected = `${first}second\n`;
-      const secondEmitted = deferred<void>();
-      const releaseExecutor = deferred<void>();
-      const started = await startBackgroundLocalBash({
-        host,
-        parentSession: parentSessionRecord(dataDir),
-        toolCtx: toolContext('session-a'),
-        bashInput: { command: 'stream with transient persistence failure' },
-        executor: {
-          execute: async ({ onOutput, onPreflightComplete }) => {
-            await onPreflightComplete?.();
-            onOutput?.(first);
-            await new Promise<void>((resolve) => setImmediate(resolve));
-            onOutput?.('second\n');
-            secondEmitted.resolve();
-            await releaseExecutor.promise;
-            return { text: expected };
-          },
-        },
-      });
-
-      await secondEmitted.promise;
-      await expect
-        .poll(async () => {
-          const output = await service.readOutput(toolContext('session-a'), started.taskId!, {
-            offset: 0,
-            limitBytes: Buffer.byteLength(expected, 'utf8') + 1,
-          });
-          return output.content;
-        })
-        .toBe(expected);
-      expect((await service.get(toolContext('session-a'), started.taskId!))?.status).toBe(
-        'running',
-      );
-      releaseExecutor.resolve();
-      await waitForTaskStatus(service, started.taskId!, 'succeeded');
-      const output = await service.readOutput(toolContext('session-a'), started.taskId!, {
-        offset: 0,
-        limitBytes: Buffer.byteLength(expected, 'utf8') + 1,
-      });
-      expect(output.content).toBe(expected);
-
-      const firstPage = await service.readOutput(toolContext('session-a'), started.taskId!, {
-        offset: 0,
-        limitBytes: 65_536,
-      });
-      const secondPage = await service.readOutput(toolContext('session-a'), started.taskId!, {
-        offset: firstPage.nextOffset,
-        limitBytes: 65_536,
-      });
-      expect(firstPage.content + secondPage.content).toBe(expected);
-      expect(firstPage.content + secondPage.content).not.toContain('�');
-    } finally {
-      closeLocalRuntimeDb(dataDir);
-      await rm(dataDir, { recursive: true, force: true });
-    }
-  });
-
-  it('bounds recovery after persistent output failure and records an omission marker', async () => {
-    const firstAppendFailed = deferred<void>();
-    const allowRecoveryRead = deferred<void>();
-    const appendedPayloads: string[] = [];
-    let persisted = '';
-    let appendAttempts = 0;
-    const host = {
-      nowMs: () => 72_250,
-      matrixLogger: { warn: () => undefined },
-      backgroundTaskService: {
-        appendOutput: async ({ content }: { content: string }) => {
-          appendAttempts += 1;
-          appendedPayloads.push(content);
-          if (appendAttempts === 1) {
-            firstAppendFailed.resolve();
-            throw new Error('persistent output append failure');
-          }
-          persisted += content;
-          return {
-            taskId: 'bounded-recovery',
-            kind: 'memory',
-            uri: 'memory://bounded-recovery',
-            offset: Buffer.byteLength(persisted, 'utf8'),
-          };
-        },
-        readOutput: async (_taskId: string, options: { offset?: number }) => {
-          await allowRecoveryRead.promise;
-          const offset = options.offset ?? 0;
-          const bytes = Buffer.from(persisted, 'utf8');
-          const content = bytes.subarray(offset).toString('utf8');
-          return {
-            content,
-            nextOffset: bytes.length,
-            truncated: false,
-            outputRef: {
-              taskId: 'bounded-recovery',
-              kind: 'memory',
-              uri: 'memory://bounded-recovery',
-              offset: bytes.length,
-            },
-          };
-        },
-      },
-    } as unknown as LocalTaskRunnerHostWithSessionLookup;
-    const writer = new BackgroundBashOutputWriter(host, 'session-a', 'bounded-recovery');
-
-    writer.push('seed');
-    await firstAppendFailed.promise;
-    const recoveryState = writer as unknown as {
-      persistenceIncomplete: boolean;
-      recoveryContent: string;
-      droppedRecoveryBytes: number;
-    };
-    await expect.poll(() => recoveryState.persistenceIncomplete).toBe(true);
-    for (let index = 0; index < 8; index += 1) writer.push('x'.repeat(1024 * 1024));
-    expect(recoveryState.recoveryContent.length).toBe(1024 * 1024);
-    expect(recoveryState.droppedRecoveryBytes).toBe(7_340_036);
-    allowRecoveryRead.resolve();
-    const outputRef = await writer.settleSuccess({ text: '' });
-    expect(writer.describePersistence(outputRef)).toMatchObject({ persistence: 'incomplete', omittedBytes: 7_340_036, rawBytes: 8 * 1024 * 1024 + 4 });
-
-    expect(Math.max(...appendedPayloads.map((content) => content.length))).toBeLessThan(
-      2 * 1024 * 1024,
-    );
-    expect(persisted).toContain('omitted 7340036 bytes');
-    expect(persisted.length).toBeLessThan(2 * 1024 * 1024);
-  });
-
-  it('repairs the failure reason when its terminal append also fails transiently', async () => {
-    let appendAttempts = 0;
-    let persisted = '';
-    const host = {
-      nowMs: () => 72_375,
-      matrixLogger: { warn: () => undefined },
-      backgroundTaskService: {
-        appendOutput: async ({ content }: { content: string }) => {
-          appendAttempts += 1;
-          if (appendAttempts === 1 || appendAttempts === 3) {
-            throw new Error('transient output append failure');
-          }
-          persisted += content;
-          return {
-            taskId: 'terminal-recovery',
-            kind: 'memory',
-            uri: 'memory://terminal-recovery',
-            offset: Buffer.byteLength(persisted, 'utf8'),
-          };
-        },
-        readOutput: async (_taskId: string, options: { offset?: number }) => {
-          const offset = options.offset ?? 0;
-          const bytes = Buffer.from(persisted, 'utf8');
-          return {
-            content: bytes.subarray(offset).toString('utf8'),
-            nextOffset: bytes.length,
-            truncated: false,
-            outputRef: {
-              taskId: 'terminal-recovery',
-              kind: 'memory',
-              uri: 'memory://terminal-recovery',
-              offset: bytes.length,
-            },
-          };
-        },
-      },
-    } as unknown as LocalTaskRunnerHostWithSessionLookup;
-    const writer = new BackgroundBashOutputWriter(host, 'session-a', 'terminal-recovery');
-    const terminal = '\n<bash_status>Background bash failed: exit 7</bash_status>\n';
-
-    writer.push('streamed suffix');
-    await writer.settleFailure(terminal);
-
-    expect(appendAttempts).toBe(4);
-    expect(persisted).toBe(`streamed suffix${terminal}`);
-  });
-
-  it('repairs failed task output after a streamed append fails mid-command', async () => {
-    const dataDir = await mkdtemp(join(tmpdir(), 'local-background-bash-failed-output-repair-'));
-    try {
-      const backingOutputStore = new FsLocalTaskOutputStore(dataDir);
-      let appendCount = 0;
-      const service = new LocalBackgroundTaskService({
-        store: new SqliteLocalBackgroundTaskStore(dataDir, () => 72_500),
-        outputStore: {
-          append: async (chunk) => {
-            appendCount += 1;
-            if (appendCount === 2) throw new Error('transient output append failure');
-            return backingOutputStore.append(chunk);
-          },
-          read: (taskId, options) => backingOutputStore.read(taskId, options),
-          tail: (taskId, limitBytes) => backingOutputStore.tail(taskId, limitBytes),
-          finalize: (taskId, summary) => backingOutputStore.finalize(taskId, summary),
-        },
-        nowMs: () => 72_500,
-      });
-      const host = backgroundBashHost(service, dataDir);
-      const started = await startBackgroundLocalBash({
-        host,
-        parentSession: parentSessionRecord(dataDir),
-        toolCtx: toolContext('session-a'),
-        bashInput: { command: 'stream then fail' },
-        executor: {
-          execute: async ({ onOutput }) => {
-            onOutput?.('first\n');
-            await new Promise<void>((resolve) => setImmediate(resolve));
-            onOutput?.('second\n');
-            throw new Error('exit 7');
-          },
-        },
-      });
-
-      await waitForTaskStatus(service, started.taskId!, 'failed');
-      const output = await service.readOutput(toolContext('session-a'), started.taskId!, {
-        limitBytes: 64 * 1024,
-      });
-      expect(output.content).toContain('first\nsecond\n');
-      expect(output.content).toContain('<bash_status>Background bash failed: exit 7</bash_status>');
-    } finally {
-      closeLocalRuntimeDb(dataDir);
-      await rm(dataDir, { recursive: true, force: true });
-    }
-  });
-
-  it('coalesces bursty streamed output instead of queuing one persistence promise per chunk', async () => {
-    const dataDir = await mkdtemp(join(tmpdir(), 'local-background-bash-output-burst-'));
-    try {
-      const backingOutputStore = new FsLocalTaskOutputStore(dataDir);
-      let appendCount = 0;
-      const service = new LocalBackgroundTaskService({
-        store: new SqliteLocalBackgroundTaskStore(dataDir, () => 73_000),
-        outputStore: {
-          append: async (chunk) => {
-            appendCount += 1;
-            await new Promise<void>((resolve) => setImmediate(resolve));
-            return backingOutputStore.append(chunk);
-          },
-          read: (taskId, options) => backingOutputStore.read(taskId, options),
-          tail: (taskId, limitBytes) => backingOutputStore.tail(taskId, limitBytes),
-          finalize: (taskId, summary) => backingOutputStore.finalize(taskId, summary),
-        },
-        nowMs: () => 73_000,
-      });
-      const host = backgroundBashHost(service, dataDir);
-      const chunks = Array.from({ length: 1_000 }, (_, index) => `${index}\n`);
-      const expected = chunks.join('');
-      const started = await startBackgroundLocalBash({
-        host,
-        parentSession: parentSessionRecord(dataDir),
-        toolCtx: toolContext('session-a'),
-        bashInput: { command: 'emit burst' },
-        executor: {
-          execute: async ({ onOutput }) => {
-            for (const chunk of chunks) onOutput?.(chunk);
-            return { text: expected };
-          },
-        },
-      });
-
-      await waitForTaskStatus(service, started.taskId!, 'succeeded');
-      const output = await service.readOutput(toolContext('session-a'), started.taskId!, {
-        limitBytes: Buffer.byteLength(expected, 'utf8') + 1,
-      });
-      expect(output.content).toBe(expected);
-      expect(appendCount).toBeLessThan(10);
-    } finally {
-      closeLocalRuntimeDb(dataDir);
-      await rm(dataDir, { recursive: true, force: true });
-    }
-  });
-});
-
-function deferred<T>(): {
-  promise: Promise<T>;
-  resolve(value: T | PromiseLike<T>): void;
-} {
-  let resolve!: (value: T | PromiseLike<T>) => void;
-  const promise = new Promise<T>((settle) => {
-    resolve = settle;
-  });
-  return { promise, resolve };
-}
diff --git a/packages/local-runtime/test/unit/local-background-bash-runner.test.ts b/packages/local-runtime/test/unit/local-background-bash-runner.test.ts
deleted file mode 100644
index 41cbfde4..00000000
--- a/packages/local-runtime/test/unit/local-background-bash-runner.test.ts
+++ /dev/null
@@ -1,959 +0,0 @@
-import { mkdtemp, rm } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-
-import { describe, expect, it, vi } from 'vitest';
-import { createLocalBashOperations } from '@earendil-works/pi-coding-agent/tools';
-import { LocalBashTool, LocalTaskOutputTool, LocalTaskQueryTool } from '@mavis/agent-tools/desktop';
-
-import {
-  DEFAULT_BACKGROUND_BASH_MAX_RUN_MS,
-  MAX_BACKGROUND_BASH_MAX_RUN_MS,
-  buildLocalBashAdapter,
-  resolveBackgroundBashMaxRunMs,
-  runManagedForegroundLocalBash,
-  startBackgroundLocalBash,
-  stopBackgroundLocalBashTask,
-  type LocalBackgroundBashExecutor,
-} from '../../src/background-task/bash-runner.js';
-import { createLocalBackgroundBashExecutor } from '../../../local-runtime-v2/src/service/background-bash/executor.js';
-import { LocalBackgroundTaskService } from '../../src/background-task/service.js';
-import {
-  FsLocalTaskOutputStore,
-  SqliteLocalBackgroundTaskStore,
-} from '../../src/background-task/store.js';
-import { closeLocalRuntimeDb } from '../../src/persistence/db.js';
-import { logger } from '../../src/common/logger.js';
-import {
-  backgroundBashHost,
-  parentSessionRecord,
-  taskRecord,
-  taskStoreWithPatch,
-  toolContext,
-  waitForTaskOutput,
-  waitForTaskStatus,
-} from './background-task-test-helpers.js';
-
-const MOVED_LOCAL_BACKGROUND_BASH_EXECUTOR = createLocalBackgroundBashExecutor(
-  {
-    create: (input) =>
-      createLocalBashOperations({
-        parentDeathGuard: input.identity.operationClass !== 'direct_foreground',
-      }),
-  },
-  { mode: 'off' },
-);
-
-describe('local background bash runner', () => {
-  it.skipIf(process.platform === 'win32').each([
-    {
-      description: '运行测试命令',
-      command: "printf 'partial-output'; exit 0",
-      status: 'succeeded',
-      reason: 'exited',
-      exitCode: 0,
-    },
-    { description: '运行测试命令', command: "printf 'partial-output'; exit 7", status: 'failed', reason: 'exited', exitCode: 7 },
-    {
-      description: '运行测试命令',
-      command: "printf 'partial-output'; kill -TERM $$",
-      status: 'failed',
-      reason: 'signaled',
-      exitCode: null,
-      signal: 'SIGTERM',
-    },
-    {
-      description: '运行测试命令',
-      command: "printf 'partial-output'; sleep 2",
-      timeout: 0.1,
-      status: 'failed',
-      reason: 'command_timeout',
-      exitCode: null,
-    },
-  ] as const)(
-    'preserves the same execution facts across all Bash modes: $reason / $exitCode',
-    async (scenario) => {
-      const dataDir = await mkdtemp(join(tmpdir(), 'local-bash-result-contract-'));
-      try {
-        const service = new LocalBackgroundTaskService({
-          store: new SqliteLocalBackgroundTaskStore(dataDir),
-          outputStore: new FsLocalTaskOutputStore(dataDir),
-        });
-        const host = backgroundBashHost(service, dataDir);
-        const ctx = { ...toolContext('session-a'), canConsumeBackgroundBashOutput: true };
-        const args = {
-          description: '运行测试命令',
-          command: scenario.command,
-          timeout: 'timeout' in scenario ? scenario.timeout : 3,
-        };
-        const direct = await new LocalBashTool(dataDir, undefined, { mode: 'off' }).execute(
-          ctx,
-          args,
-        );
-        const managed = await new LocalBashTool(
-          dataDir,
-          buildLocalBashAdapter(host, parentSessionRecord(dataDir), MOVED_LOCAL_BACKGROUND_BASH_EXECUTOR),
-          { mode: 'off' },
-        ).execute(ctx, args);
-        const started = await startBackgroundLocalBash({
-          host,
-          parentSession: parentSessionRecord(dataDir),
-          toolCtx: ctx,
-          bashInput: { ...args, run_in_background: true },
-          executor: MOVED_LOCAL_BACKGROUND_BASH_EXECUTOR,
-        });
-        const task = await waitForTaskStatus(service, started.taskId!, scenario.status);
-        const expected = {
-          status: scenario.status,
-          reason: scenario.reason,
-          exitCode: scenario.exitCode,
-          ...('signal' in scenario ? { signal: scenario.signal } : {}),
-        };
-        expect(direct.details).toMatchObject({ execution: expected, timing: { commandTimeoutSeconds: args.timeout, commandTimerStartedAt: expect.any(Number), commandDeadlineAt: expect.any(Number) } });
-        expect(managed.details).toMatchObject({ status: scenario.status, execution: expected });
-        expect(task.metadata?.bashDetails).toMatchObject({ execution: expected });
-        expect(direct.isError === true).toBe(scenario.status === 'failed');
-        expect(managed.isError === true).toBe(scenario.status === 'failed');
-        expect(direct.text).toContain('partial-output');
-        expect(managed.text).toBe(direct.text);
-        expect(managed.details?.processOutput).toMatchObject({ stdout: 'partial-output', stderr: '' });
-        const output = await new LocalTaskOutputTool(service).execute(ctx, {
-          task_id: task.taskId,
-        });
-        expect(output.details).toMatchObject({ execution: expected });
-        expect(output.isError).not.toBe(true);
-        expect(output.text).toContain('partial-output');
-        const query = await new LocalTaskQueryTool(service).execute(ctx, { task_id: task.taskId });
-        expect(query.details).toMatchObject({ task: { execution: expected } });
-        if (scenario.status === 'failed') expect(task.lastError?.message).toBeTruthy();
-      } finally {
-        closeLocalRuntimeDb(dataDir);
-        await rm(dataDir, { recursive: true, force: true });
-      }
-    },
-  );
-
-  it.each(['visible', 'hidden'] as const)(
-    'enables both background paths for %s task children',
-    (visibility) => {
-      const adapter = buildLocalBashAdapter({} as Parameters<typeof buildLocalBashAdapter>[0], {
-        ...parentSessionRecord('/tmp/workspace'),
-        sessionType: 'branch',
-        sessionKind: 'task',
-        parentSessionId: 'parent',
-        visibility,
-      });
-      expect(adapter.startBackground).toBeTypeOf('function');
-      expect(adapter.runManagedForeground).toBeTypeOf('function');
-    },
-  );
-
-  it('keeps managed foreground soft-yield enabled for ordinary sessions', () => {
-    const adapter = buildLocalBashAdapter(
-      {} as Parameters<typeof buildLocalBashAdapter>[0],
-      parentSessionRecord('/tmp/workspace'),
-    );
-
-    expect(adapter.runManagedForeground).toBeTypeOf('function');
-  });
-
-  it('reaches succeeded even when output persistence and finalization fail', async () => {
-    const dataDir = await mkdtemp(join(tmpdir(), 'local-background-bash-output-failure-'));
-    try {
-      const store = new SqliteLocalBackgroundTaskStore(dataDir, () => 29_000);
-      const backingOutputStore = new FsLocalTaskOutputStore(dataDir);
-      const service = new LocalBackgroundTaskService({
-        store,
-        outputStore: {
-          append: async () => {
-            throw new Error('output append unavailable');
-          },
-          read: (taskId, options) => backingOutputStore.read(taskId, options),
-          tail: (taskId, limitBytes) => backingOutputStore.tail(taskId, limitBytes),
-          finalize: async () => {
-            throw new Error('output finalize unavailable');
-          },
-        },
-        nowMs: () => 29_000,
-      });
-      const host = backgroundBashHost(service, dataDir);
-      const started = await startBackgroundLocalBash({
-        host,
-        parentSession: parentSessionRecord(dataDir),
-        toolCtx: toolContext('session-a'),
-        bashInput: { description: '运行测试命令', command: 'echo durable-status', run_in_background: true },
-        executor: { execute: async () => ({ text: 'durable-status\n' }) },
-      });
-
-      const task = await waitForTaskStatus(service, started.taskId!, 'succeeded');
-      expect(task.outputRef).toBeUndefined();
-      expect(task.metadata?.bashDetails).toMatchObject({ output: { persistence: 'incomplete' } });
-      expect(task.metadata?.bashDetails).not.toHaveProperty('fullOutputPath');
-      expect(task.lastError).toBeUndefined();
-    } finally {
-      closeLocalRuntimeDb(dataDir);
-      await rm(dataDir, { recursive: true, force: true });
-    }
-  });
-
-  it('reaches failed even when the failure output cannot be persisted', async () => {
-    const dataDir = await mkdtemp(join(tmpdir(), 'local-background-bash-failure-output-'));
-    try {
-      const store = new SqliteLocalBackgroundTaskStore(dataDir, () => 29_250);
-      const backingOutputStore = new FsLocalTaskOutputStore(dataDir);
-      const service = new LocalBackgroundTaskService({
-        store,
-        outputStore: {
-          append: async () => {
-            throw new Error('output append unavailable');
-          },
-          read: (taskId, options) => backingOutputStore.read(taskId, options),
-          tail: (taskId, limitBytes) => backingOutputStore.tail(taskId, limitBytes),
-          finalize: (taskId, summary) => backingOutputStore.finalize(taskId, summary),
-        },
-        nowMs: () => 29_250,
-      });
-      const host = backgroundBashHost(service, dataDir);
-      const started = await startBackgroundLocalBash({
-        host,
-        parentSession: parentSessionRecord(dataDir),
-        toolCtx: toolContext('session-a'),
-        bashInput: { description: '运行测试命令', command: 'exit 7', run_in_background: true },
-        executor: {
-          execute: async () => {
-            throw new Error('exit 7');
-          },
-        },
-      });
-
-      const task = await waitForTaskStatus(service, started.taskId!, 'failed');
-      expect(task.outputRef).toBeUndefined();
-      expect(task.metadata?.bashDetails).toMatchObject({ output: { persistence: 'incomplete' } });
-      expect(task.metadata?.bashDetails).not.toHaveProperty('fullOutputPath');
-      expect(task.lastError?.code).toBe('BASH_FAILED');
-    } finally {
-      closeLocalRuntimeDb(dataDir);
-      await rm(dataDir, { recursive: true, force: true });
-    }
-  });
-
-  it('still stops the runtime when the stop_requested event cannot be persisted', async () => {
-    const dataDir = await mkdtemp(join(tmpdir(), 'local-background-stop-event-failure-'));
-    const warn = vi.spyOn(logger, 'warn').mockImplementation(() => {
-      throw new Error('logger unavailable');
-    });
-    try {
-      const store = new SqliteLocalBackgroundTaskStore(dataDir, () => 29_500);
-      const trackingStore = taskStoreWithPatch(store, async () => undefined);
-      const appendEvent = trackingStore.appendEvent.bind(trackingStore);
-      trackingStore.appendEvent = async (event) => {
-        if (event.type === 'stop_requested') throw new Error('event store unavailable');
-        await appendEvent(event);
-      };
-      let stopped = false;
-      const service = new LocalBackgroundTaskService({
-        store: trackingStore,
-        outputStore: new FsLocalTaskOutputStore(dataDir),
-        nowMs: () => 29_500,
-        stopRuntime: async () => {
-          stopped = true;
-        },
-      });
-      await store.create(taskRecord('running-task', 'session-a', { status: 'running' }));
-
-      await expect(service.stop('running-task', 'user stopped')).resolves.toMatchObject({
-        status: 'canceled',
-      });
-      expect(stopped).toBe(true);
-      expect(warn).toHaveBeenCalledWith(
-        expect.objectContaining({ lifecycleType: 'stop_requested' }),
-        'Failed to persist background task lifecycle event',
-      );
-    } finally {
-      warn.mockRestore();
-      closeLocalRuntimeDb(dataDir);
-      await rm(dataDir, { recursive: true, force: true });
-    }
-  });
-
-  it('streams output while the task is still running without duplicating the final snapshot', async () => {
-    const dataDir = await mkdtemp(join(tmpdir(), 'local-background-bash-stream-'));
-    try {
-      const service = new LocalBackgroundTaskService({
-        store: new SqliteLocalBackgroundTaskStore(dataDir, () => 30_000),
-        outputStore: new FsLocalTaskOutputStore(dataDir),
-        nowMs: () => 30_000,
-      });
-      const host = backgroundBashHost(service, dataDir);
-      let finish!: () => void;
-      const executor: LocalBackgroundBashExecutor = {
-        execute: async ({ onOutput, onPreflightComplete }) => {
-          await onPreflightComplete?.();
-          onOutput?.('first\n');
-          await new Promise<void>((resolve) => {
-            finish = resolve;
-          });
-          onOutput?.('second\n');
-          return { text: 'first\nsecond\n' };
-        },
-      };
-
-      const started = await startBackgroundLocalBash({
-        host,
-        parentSession: parentSessionRecord(dataDir),
-        toolCtx: toolContext('session-a'),
-        bashInput: { description: '运行测试命令', command: 'stream', run_in_background: true },
-        executor,
-      });
-
-      await expect(waitForTaskOutput(service, started.taskId!, 'first')).resolves.toContain('first');
-      expect((await service.get(toolContext('session-a'), started.taskId!))?.status).toBe('running');
-      finish();
-      await waitForTaskStatus(service, started.taskId!, 'succeeded');
-      const output = await service.readOutput(toolContext('session-a'), started.taskId!, { offset: 0 });
-      expect(output.content).toBe('first\nsecond\n');
-    } finally {
-      closeLocalRuntimeDb(dataDir);
-      await rm(dataDir, { recursive: true, force: true });
-    }
-  });
-
-  it('returns a fast managed command inline and suppresses its completion wake-up', async () => {
-    const dataDir = await mkdtemp(join(tmpdir(), 'local-managed-bash-fast-'));
-    try {
-      const service = new LocalBackgroundTaskService({
-        store: new SqliteLocalBackgroundTaskStore(dataDir, () => 32_000),
-        outputStore: new FsLocalTaskOutputStore(dataDir),
-        nowMs: () => 32_000,
-      });
-      const host = backgroundBashHost(service, dataDir);
-      let managedIdentity: Parameters<LocalBackgroundBashExecutor['execute']>[0]['identity'];
-      const result = await runManagedForegroundLocalBash({
-        host,
-        parentSession: parentSessionRecord(dataDir),
-        toolCtx: { ...toolContext('session-a'), forceReadOnlyFilesystem: true },
-        bashInput: { description: '运行测试命令', command: 'echo fast', timeout: 120 },
-        softYieldMs: 50,
-        executor: {
-          execute: async ({ identity, onPreflightComplete }) => {
-            managedIdentity = identity;
-            await onPreflightComplete?.();
-            return { text: 'fast\n' };
-          },
-        },
-      });
-
-      expect(result).toMatchObject({ status: 'completed', text: 'fast\n' });
-      expect(managedIdentity!).toEqual({
-        operationClass: 'managed_foreground',
-        invocationId: result.taskId,
-        sessionId: 'session-a',
-        turnId: 'turn-session-a',
-        toolCallId: 'call-session-a',
-        taskId: result.taskId,
-        forceReadOnlyFilesystem: true,
-      });
-      const task = await service.get(toolContext('session-a'), result.taskId!);
-      expect(task).toMatchObject({ status: 'succeeded', deliveredAt: 32_000 });
-      expect(task?.metadata).toMatchObject({ completionOrigin: 'foreground' });
-    } finally {
-      closeLocalRuntimeDb(dataDir);
-      await rm(dataDir, { recursive: true, force: true });
-    }
-  });
-
-  it.each([
-    { timeout: undefined, effectiveTimeout: 600 },
-    { timeout: 45, effectiveTimeout: 45 },
-    { timeout: 600, effectiveTimeout: 600 },
-    { timeout: 900, effectiveTimeout: 600 },
-  ])('soft-yields with total command timeout $effectiveTimeout for requested $timeout', async ({ timeout, effectiveTimeout }) => {
-    const dataDir = await mkdtemp(join(tmpdir(), 'local-managed-bash-slow-'));
-    try {
-      const service = new LocalBackgroundTaskService({
-        store: new SqliteLocalBackgroundTaskStore(dataDir, () => 33_000),
-        outputStore: new FsLocalTaskOutputStore(dataDir),
-        nowMs: () => 33_000,
-      });
-      const host = backgroundBashHost(service, dataDir);
-      let finish!: () => void;
-      let dispatchedTimeout: number | undefined;
-      const result = await runManagedForegroundLocalBash({
-        host,
-        parentSession: parentSessionRecord(dataDir),
-        toolCtx: toolContext('session-a'),
-        bashInput: { description: '运行测试命令', command: 'slow', timeout },
-        softYieldMs: 10,
-        executor: {
-          execute: async ({ onPreflightComplete, timeout: commandTimeout }) => {
-            dispatchedTimeout = commandTimeout;
-            await onPreflightComplete?.();
-            return new Promise((resolve) => {
-              finish = () => resolve({ text: 'done\n' });
-            });
-          },
-        },
-      });
-
-      expect(result).toMatchObject({ status: 'auto_promoted', details: { description: '运行测试命令' } });
-      expect(dispatchedTimeout).toBe(effectiveTimeout);
-      expect(result.details).toMatchObject({ timing: { commandTimeoutSeconds: effectiveTimeout } });
-      expect((await service.get(result.taskId!))?.description).toBe('运行测试命令');
-      expect((await service.get(toolContext('session-a'), result.taskId!))?.status).toBe('running');
-      finish();
-      await waitForTaskStatus(service, result.taskId!, 'succeeded');
-      expect((await service.get(toolContext('session-a'), result.taskId!))?.metadata).toMatchObject({
-        executionMode: 'auto_promoted',
-        bashDetails: { timing: { commandTimeoutSeconds: effectiveTimeout } },
-      });
-    } finally {
-      closeLocalRuntimeDb(dataDir);
-      await rm(dataDir, { recursive: true, force: true });
-    }
-  });
-
-  it('returns spawn-time env sanitization details on an auto-promoted command', async () => {
-    const dataDir = await mkdtemp(join(tmpdir(), 'local-managed-bash-env-hint-'));
-    process.env.MAVIS_ACCESS_TOKEN = 'must-not-reach-child';
-    try {
-      const service = new LocalBackgroundTaskService({
-        store: new SqliteLocalBackgroundTaskStore(dataDir, () => 33_500),
-        outputStore: new FsLocalTaskOutputStore(dataDir),
-        nowMs: () => 33_500,
-      });
-      const host = backgroundBashHost(service, dataDir);
-      const result = await runManagedForegroundLocalBash({
-        host,
-        parentSession: parentSessionRecord(dataDir),
-        toolCtx: toolContext('session-a'),
-        bashInput: { description: '运行测试命令', command: 'sleep 0.1; echo done', timeout: 120 },
-        softYieldMs: 10,
-        executor: MOVED_LOCAL_BACKGROUND_BASH_EXECUTOR,
-      });
-
-      expect(result).toMatchObject({
-        status: 'auto_promoted',
-        details: { envSanitized: expect.arrayContaining(['MAVIS_ACCESS_TOKEN']) },
-      });
-      await waitForTaskStatus(service, result.taskId!, 'succeeded');
-    } finally {
-      delete process.env.MAVIS_ACCESS_TOKEN;
-      closeLocalRuntimeDb(dataDir);
-      await rm(dataDir, { recursive: true, force: true });
-    }
-  });
-
-  it('runs local bash in the background and stores final output', async () => {
-    const dataDir = await mkdtemp(join(tmpdir(), 'local-background-bash-'));
-    try {
-      const service = new LocalBackgroundTaskService({
-        store: new SqliteLocalBackgroundTaskStore(dataDir, () => 31_000),
-        outputStore: new FsLocalTaskOutputStore(dataDir),
-        nowMs: () => 31_000,
-      });
-      const host = backgroundBashHost(service, dataDir);
-      let explicitIdentity: Parameters<LocalBackgroundBashExecutor['execute']>[0]['identity'];
-      const executor: LocalBackgroundBashExecutor = {
-        execute: async ({ command, identity, onPreflightComplete }) => {
-          explicitIdentity = identity;
-          await onPreflightComplete?.();
-          return { text: `ran:${command}` };
-        },
-      };
-
-      const started = await startBackgroundLocalBash({
-        host,
-        parentSession: parentSessionRecord(dataDir),
-        toolCtx: { ...toolContext('session-a'), forceReadOnlyFilesystem: true },
-        bashInput: { description: '运行测试命令', command: 'echo ok', run_in_background: true },
-        executor,
-      });
-
-      expect(started.status).toBe('started');
-      const task = await waitForTaskStatus(service, started.taskId!, 'succeeded');
-      expect(task).toMatchObject({ kind: 'bash', description: '运行测试命令' });
-      expect(explicitIdentity!).toEqual({
-        operationClass: 'explicit_background',
-        invocationId: started.taskId,
-        sessionId: 'session-a',
-        turnId: 'turn-session-a',
-        toolCallId: 'call-session-a',
-        taskId: started.taskId,
-        forceReadOnlyFilesystem: true,
-      });
-      await expect(service.readOutput(toolContext('session-a'), started.taskId!)).resolves.toMatchObject({
-        content: 'ran:echo ok',
-      });
-    } finally {
-      closeLocalRuntimeDb(dataDir);
-      await rm(dataDir, { recursive: true, force: true });
-    }
-  });
-
-  it('aborts a running background bash task through the shared task stop path', async () => {
-    const dataDir = await mkdtemp(join(tmpdir(), 'local-background-bash-stop-'));
-    try {
-      const store = new SqliteLocalBackgroundTaskStore(dataDir, () => 41_000);
-      const service = new LocalBackgroundTaskService({
-        store,
-        outputStore: new FsLocalTaskOutputStore(dataDir),
-        nowMs: () => 41_000,
-        stopRuntime: stopBackgroundLocalBashTask,
-      });
-      const host = backgroundBashHost(service, dataDir);
-      let aborted = false;
-      const executor: LocalBackgroundBashExecutor = {
-        execute: ({ signal }) =>
-          new Promise((_resolve, reject) => {
-            signal.addEventListener('abort', () => {
-              aborted = true;
-              reject(new Error('aborted'));
-            });
-          }),
-      };
-
-      const started = await startBackgroundLocalBash({
-        host,
-        parentSession: parentSessionRecord(dataDir),
-        toolCtx: toolContext('session-a'),
-        bashInput: { description: '运行测试命令', command: 'sleep 100', run_in_background: true },
-        executor,
-      });
-
-      await service.stop(toolContext('session-a'), started.taskId!, 'user stopped');
-      const task = await waitForTaskStatus(service, started.taskId!, 'canceled');
-      expect(aborted).toBe(true);
-      expect(task).toMatchObject({ kind: 'bash', status: 'canceled' });
-      await expect(
-        waitForTaskOutput(service, started.taskId!, 'Background bash canceled'),
-      ).resolves.toContain('Background bash canceled');
-    } finally {
-      closeLocalRuntimeDb(dataDir);
-      await rm(dataDir, { recursive: true, force: true });
-    }
-  });
-
-  it('keeps task_stop in stopping until runner cleanup and final output settle', async () => {
-    const dataDir = await mkdtemp(join(tmpdir(), 'local-background-bash-stop-settle-'));
-    try {
-      const service = new LocalBackgroundTaskService({
-        store: new SqliteLocalBackgroundTaskStore(dataDir, () => 42_000),
-        outputStore: new FsLocalTaskOutputStore(dataDir),
-        nowMs: () => 42_000,
-        stopRuntime: stopBackgroundLocalBashTask,
-      });
-      const host = backgroundBashHost(service, dataDir);
-      let releaseCleanup!: () => void;
-      const cleanupGate = new Promise<void>((resolve) => {
-        releaseCleanup = resolve;
-      });
-      const executor: LocalBackgroundBashExecutor = {
-        execute: ({ signal, onOutput }) =>
-          new Promise((_resolve, reject) => {
-            signal.addEventListener('abort', () => {
-              void cleanupGate.then(() => {
-                onOutput?.('cleanup-finished\n');
-                reject(new Error('aborted after cleanup'));
-              });
-            });
-          }),
-      };
-
-      const started = await startBackgroundLocalBash({
-        host,
-        parentSession: parentSessionRecord(dataDir),
-        toolCtx: toolContext('session-a'),
-        bashInput: { description: '运行测试命令', command: 'deferred-cleanup', run_in_background: true },
-        executor,
-      });
-
-      let stopSettled = false;
-      const stopping = service
-        .stop(toolContext('session-a'), started.taskId!, 'user stopped')
-        .then((task) => {
-          stopSettled = true;
-          return task;
-        });
-      await new Promise((resolve) => setTimeout(resolve, 0));
-      expect(stopSettled).toBe(false);
-      expect((await service.get(toolContext('session-a'), started.taskId!))?.status).toBe(
-        'stopping',
-      );
-
-      releaseCleanup();
-      await expect(stopping).resolves.toMatchObject({ status: 'canceled' });
-      await expect(service.readOutput(toolContext('session-a'), started.taskId!)).resolves.toMatchObject({
-        status: 'canceled',
-        content: expect.stringContaining('cleanup-finished'),
-      });
-    } finally {
-      closeLocalRuntimeDb(dataDir);
-      await rm(dataDir, { recursive: true, force: true });
-    }
-  });
-
-  it('keeps a user stop canceled when cleanup outlives the maxRun watchdog', async () => {
-    const dataDir = await mkdtemp(join(tmpdir(), 'local-background-bash-stop-watchdog-'));
-    try {
-      const store = new SqliteLocalBackgroundTaskStore(dataDir, () => 43_000);
-      const completedEvents: string[] = [];
-      const trackingStore = taskStoreWithPatch(store, async () => undefined);
-      const appendEvent = trackingStore.appendEvent.bind(trackingStore);
-      trackingStore.appendEvent = async (event) => {
-        if (event.type === 'completed') completedEvents.push(event.type);
-        await appendEvent(event);
-      };
-      const service = new LocalBackgroundTaskService({
-        store: trackingStore,
-        outputStore: new FsLocalTaskOutputStore(dataDir),
-        nowMs: () => 43_000,
-        stopRuntime: stopBackgroundLocalBashTask,
-      });
-      const host = backgroundBashHost(service, dataDir);
-      let releaseCleanup!: () => void;
-      const cleanupGate = new Promise<void>((resolve) => {
-        releaseCleanup = resolve;
-      });
-      const executor: LocalBackgroundBashExecutor = {
-        execute: ({ signal }) =>
-          new Promise((_resolve, reject) => {
-            signal.addEventListener('abort', () => {
-              void cleanupGate.then(() => reject(new Error('stopped after cleanup')));
-            });
-          }),
-      };
-
-      const started = await startBackgroundLocalBash({
-        host,
-        parentSession: parentSessionRecord(dataDir),
-        toolCtx: toolContext('session-a'),
-        bashInput: { description: '运行测试命令', command: 'slow-cleanup', run_in_background: true },
-        executor,
-        maxRunMs: 20,
-      });
-      const stopping = service.stop(toolContext('session-a'), started.taskId!, 'user stopped');
-      await new Promise((resolve) => setTimeout(resolve, 50));
-      releaseCleanup();
-
-      await expect(stopping).resolves.toMatchObject({
-        status: 'canceled',
-        lastError: { code: 'BASH_CANCELED' },
-      });
-      expect(completedEvents).toEqual(['completed']);
-    } finally {
-      closeLocalRuntimeDb(dataDir);
-      await rm(dataDir, { recursive: true, force: true });
-    }
-  });
-
-  it('clears a stop-request marker when the command wins the race and succeeds', async () => {
-    const dataDir = await mkdtemp(join(tmpdir(), 'local-background-bash-stop-success-'));
-    try {
-      const service = new LocalBackgroundTaskService({
-        store: new SqliteLocalBackgroundTaskStore(dataDir, () => 44_000),
-        outputStore: new FsLocalTaskOutputStore(dataDir),
-        nowMs: () => 44_000,
-        stopRuntime: stopBackgroundLocalBashTask,
-      });
-      const host = backgroundBashHost(service, dataDir);
-      const executor: LocalBackgroundBashExecutor = {
-        execute: ({ signal }) =>
-          new Promise((resolve) => {
-            signal.addEventListener('abort', () => resolve({ text: 'finished anyway' }));
-          }),
-      };
-
-      const started = await startBackgroundLocalBash({
-        host,
-        parentSession: parentSessionRecord(dataDir),
-        toolCtx: toolContext('session-a'),
-        bashInput: { description: '运行测试命令', command: 'finish-on-stop', run_in_background: true },
-        executor,
-      });
-      const stopped = await service.stop(
-        toolContext('session-a'),
-        started.taskId!,
-        'user stopped',
-      );
-
-      expect(stopped).toMatchObject({ status: 'succeeded' });
-      expect(stopped?.lastError).toBeUndefined();
-    } finally {
-      closeLocalRuntimeDb(dataDir);
-      await rm(dataDir, { recursive: true, force: true });
-    }
-  });
-
-  // L7 regression: task_stop must let the bash `trap ... TERM` cleanup run
-  // before the process dies. The runner aborts the controller, pi delivers
-  // SIGTERM to the process group first (was: immediate uncatchable SIGKILL), so
-  // the trap fires and its output reaches the task before the graceful exit.
-  // Real child process + real pi bash tool; Unix signal semantics only.
-  it.skipIf(process.platform === 'win32')(
-    'L7: task_stop lets the bash TERM trap run cleanup (SIGTERM→grace, not immediate SIGKILL)',
-    async () => {
-      const dataDir = await mkdtemp(join(tmpdir(), 'local-background-bash-trap-'));
-      try {
-        const service = new LocalBackgroundTaskService({
-          store: new SqliteLocalBackgroundTaskStore(dataDir, () => 61_000),
-          outputStore: new FsLocalTaskOutputStore(dataDir),
-          nowMs: () => 61_000,
-          stopRuntime: stopBackgroundLocalBashTask,
-        });
-        const host = backgroundBashHost(service, dataDir);
-        const command =
-          "trap 'echo CLEANUP-RAN; exit 0' TERM INT; echo started; while true; do sleep 0.2; done";
-
-        const started = await startBackgroundLocalBash({
-          host,
-          parentSession: parentSessionRecord(dataDir),
-          toolCtx: toolContext('session-a'),
-          bashInput: { description: '运行测试命令', command, run_in_background: true },
-          executor: MOVED_LOCAL_BACKGROUND_BASH_EXECUTOR,
-        });
-
-        // Incremental output is persisted while the process runs, so wait for
-        // the shell's first line before stopping and exercising its TERM trap.
-        await waitForTaskOutput(service, started.taskId!, 'started');
-        await service.stop(toolContext('session-a'), started.taskId!, 'user stopped');
-
-        const output = await waitForTaskOutput(service, started.taskId!, 'CLEANUP-RAN');
-        expect(output).toContain('CLEANUP-RAN');
-        const task = await waitForTaskStatus(service, started.taskId!, 'canceled');
-        expect(task).toMatchObject({ kind: 'bash', status: 'canceled' });
-        expect(task.metadata?.bashDetails).toMatchObject({
-          execution: {
-            status: 'canceled', reason: 'canceled', exitCode: 0, cancellationReason: 'user stopped',
-          },
-          processOutput: { interrupted: true, stdout: expect.stringContaining('CLEANUP-RAN') },
-        });
-        const reported = await new LocalTaskOutputTool(service).execute(toolContext('session-a'), {
-          task_id: started.taskId!,
-        });
-        expect(reported.isError).not.toBe(true);
-        expect(reported.details).toMatchObject({ execution: { status: 'canceled', reason: 'canceled' } });
-      } finally {
-        closeLocalRuntimeDb(dataDir);
-        await rm(dataDir, { recursive: true, force: true });
-      }
-    },
-  );
-
-  it('BG-U01: kills a runaway background bash at maxRunMs → failed + TIMEOUT (not canceled)', async () => {
-    const dataDir = await mkdtemp(join(tmpdir(), 'local-background-bash-maxrun-'));
-    try {
-      const service = new LocalBackgroundTaskService({
-        store: new SqliteLocalBackgroundTaskStore(dataDir, () => 51_000),
-        outputStore: new FsLocalTaskOutputStore(dataDir),
-        nowMs: () => 51_000,
-        stopRuntime: stopBackgroundLocalBashTask,
-      });
-      const host = backgroundBashHost(service, dataDir);
-      let aborted = false;
-      // Executor hangs until the watchdog aborts it — mimics a stuck command.
-      const executor: LocalBackgroundBashExecutor = {
-        execute: ({ signal }) =>
-          new Promise((_resolve, reject) => {
-            signal.addEventListener('abort', () => {
-              aborted = true;
-              reject(new Error('aborted'));
-            });
-          }),
-      };
-
-      const started = await startBackgroundLocalBash({
-        host,
-        parentSession: parentSessionRecord(dataDir),
-        toolCtx: toolContext('session-a'),
-        bashInput: { description: '运行测试命令', command: 'sleep 100000', run_in_background: true },
-        executor,
-        maxRunMs: 50,
-      });
-
-      const task = await waitForTaskStatus(service, started.taskId!, 'failed');
-      expect(aborted).toBe(true);
-      expect(task.status).toBe('failed');
-      expect(task.lastError?.code).toBe('TIMEOUT');
-      expect(task.lastError?.message).toContain('maxRunMs');
-      expect(task.metadata?.bashDetails).toMatchObject({
-        execution: { status: 'failed', reason: 'watchdog_timeout', errorCode: 'TIMEOUT' },
-      });
-      await expect(
-        waitForTaskOutput(service, started.taskId!, 'timed out'),
-      ).resolves.toContain('timed out');
-    } finally {
-      closeLocalRuntimeDb(dataDir);
-      await rm(dataDir, { recursive: true, force: true });
-    }
-  });
-
-  it('BG-U03: watchdog is cleared when the command finishes in time (no late false timeout)', async () => {
-    const dataDir = await mkdtemp(join(tmpdir(), 'local-background-bash-maxrun-clear-'));
-    try {
-      const service = new LocalBackgroundTaskService({
-        store: new SqliteLocalBackgroundTaskStore(dataDir, () => 52_000),
-        outputStore: new FsLocalTaskOutputStore(dataDir),
-        nowMs: () => 52_000,
-      });
-      const host = backgroundBashHost(service, dataDir);
-      const executor: LocalBackgroundBashExecutor = {
-        execute: async ({ command }) => ({ text: `ran:${command}` }),
-      };
-
-      const started = await startBackgroundLocalBash({
-        host,
-        parentSession: parentSessionRecord(dataDir),
-        toolCtx: toolContext('session-a'),
-        bashInput: { description: '运行测试命令', command: 'echo quick', run_in_background: true },
-        executor,
-        maxRunMs: 40,
-      });
-
-      const task = await waitForTaskStatus(service, started.taskId!, 'succeeded');
-      expect(task.status).toBe('succeeded');
-      // Give any un-cleared watchdog a chance to (wrongly) fire, then re-read.
-      await new Promise((resolve) => setTimeout(resolve, 80));
-      const after = await service.get(toolContext('session-a'), started.taskId!);
-      expect(after?.status).toBe('succeeded');
-    } finally {
-      closeLocalRuntimeDb(dataDir);
-      await rm(dataDir, { recursive: true, force: true });
-    }
-  });
-
-  it('BG-U08: user stop still yields canceled (not TIMEOUT) even with a maxRunMs set', async () => {
-    const dataDir = await mkdtemp(join(tmpdir(), 'local-background-bash-stop-vs-maxrun-'));
-    try {
-      const service = new LocalBackgroundTaskService({
-        store: new SqliteLocalBackgroundTaskStore(dataDir, () => 53_000),
-        outputStore: new FsLocalTaskOutputStore(dataDir),
-        nowMs: () => 53_000,
-        stopRuntime: stopBackgroundLocalBashTask,
-      });
-      const host = backgroundBashHost(service, dataDir);
-      const executor: LocalBackgroundBashExecutor = {
-        execute: ({ signal }) =>
-          new Promise((_resolve, reject) => {
-            signal.addEventListener('abort', () => reject(new Error('aborted')));
-          }),
-      };
-
-      const started = await startBackgroundLocalBash({
-        host,
-        parentSession: parentSessionRecord(dataDir),
-        toolCtx: toolContext('session-a'),
-        bashInput: { description: '运行测试命令', command: 'sleep 100000', run_in_background: true },
-        executor,
-        maxRunMs: 60_000,
-      });
-
-      await service.stop(toolContext('session-a'), started.taskId!, 'user stopped');
-      const task = await waitForTaskStatus(service, started.taskId!, 'canceled');
-      expect(task.status).toBe('canceled');
-      expect(task.lastError?.code).not.toBe('TIMEOUT');
-      // Wait for the runner's async output append to settle before cleanup so
-      // the SQLite dir is quiescent (avoids an ENOTEMPTY rmdir race).
-      await waitForTaskOutput(service, started.taskId!, 'Background bash canceled');
-    } finally {
-      closeLocalRuntimeDb(dataDir);
-      await rm(dataDir, { recursive: true, force: true });
-    }
-  });
-
-  it('BG-U07: a fast executor failure is BASH_FAILED, not a TIMEOUT (watchdog stays clear)', async () => {
-    const dataDir = await mkdtemp(join(tmpdir(), 'local-background-bash-fail-'));
-    try {
-      const service = new LocalBackgroundTaskService({
-        store: new SqliteLocalBackgroundTaskStore(dataDir, () => 54_000),
-        outputStore: new FsLocalTaskOutputStore(dataDir),
-        nowMs: () => 54_000,
-      });
-      const host = backgroundBashHost(service, dataDir);
-      const executor: LocalBackgroundBashExecutor = {
-        execute: async () => {
-          throw new Error('boom');
-        },
-      };
-
-      const started = await startBackgroundLocalBash({
-        host,
-        parentSession: parentSessionRecord(dataDir),
-        toolCtx: toolContext('session-a'),
-        bashInput: { description: '运行测试命令', command: 'false', run_in_background: true },
-        executor,
-        maxRunMs: 60_000,
-      });
-
-      const task = await waitForTaskStatus(service, started.taskId!, 'failed');
-      expect(task.lastError?.code).toBe('BASH_FAILED');
-      expect(task.lastError?.code).not.toBe('TIMEOUT');
-      // Give a (wrongly-armed) watchdog time to misfire, then confirm no flip.
-      await new Promise((resolve) => setTimeout(resolve, 30));
-      const after = await service.get(toolContext('session-a'), started.taskId!);
-      expect(after?.status).toBe('failed');
-    } finally {
-      closeLocalRuntimeDb(dataDir);
-      await rm(dataDir, { recursive: true, force: true });
-    }
-  });
-});
-
-describe('resolveBackgroundBashMaxRunMs', () => {
-  it('defaults to the 30-min ceiling when no timeout is given', () => {
-    expect(resolveBackgroundBashMaxRunMs(undefined)).toBe(DEFAULT_BACKGROUND_BASH_MAX_RUN_MS);
-    expect(DEFAULT_BACKGROUND_BASH_MAX_RUN_MS).toBe(30 * 60 * 1000);
-  });
-
-  it('never undercuts an explicit longer timeout (raises the ceiling to match)', () => {
-    // 60-min explicit timeout must not be killed by the 30-min default.
-    expect(resolveBackgroundBashMaxRunMs(60 * 60)).toBe(60 * 60 * 1000);
-  });
-
-  it('keeps the default ceiling when the explicit timeout is shorter', () => {
-    expect(resolveBackgroundBashMaxRunMs(60)).toBe(DEFAULT_BACKGROUND_BASH_MAX_RUN_MS);
-  });
-
-  it('treats 0 / negative timeout as "no explicit value" → default ceiling', () => {
-    expect(resolveBackgroundBashMaxRunMs(0)).toBe(DEFAULT_BACKGROUND_BASH_MAX_RUN_MS);
-    expect(resolveBackgroundBashMaxRunMs(-5)).toBe(DEFAULT_BACKGROUND_BASH_MAX_RUN_MS);
-  });
-
-  it('caps explicit timeouts at the maximum delay supported by Node timers', () => {
-    expect(resolveBackgroundBashMaxRunMs(2_147_484)).toBe(MAX_BACKGROUND_BASH_MAX_RUN_MS);
-    expect(MAX_BACKGROUND_BASH_MAX_RUN_MS).toBe(2_147_483_647);
-  });
-});
-
-describe('reconcileStartupLostTasks — idempotence (learned from kimi reconcile.test)', () => {
-  it('a second reconcile pass is a no-op: no re-transition, no duplicate completion events', async () => {
-    const dataDir = await mkdtemp(join(tmpdir(), 'local-background-reconcile-idem-'));
-    try {
-      const store = new SqliteLocalBackgroundTaskStore(dataDir, () => 61_000);
-      const events: string[] = [];
-      const trackingStore = taskStoreWithPatch(store, async () => undefined);
-      // Wrap appendEvent to count completion emissions for the orphan.
-      const originalAppend = trackingStore.appendEvent.bind(trackingStore);
-      trackingStore.appendEvent = async (event) => {
-        if (event.taskId === 'orphan' && event.type === 'completed') events.push(event.type);
-        return originalAppend(event);
-      };
-      const service = new LocalBackgroundTaskService({
-        store: trackingStore,
-        outputStore: new FsLocalTaskOutputStore(dataDir),
-        nowMs: () => 62_000,
-      });
-      await store.create(taskRecord('orphan', 'session-a', { status: 'running', createdAt: 1_000 }));
-
-      const first = await service.reconcileStartupLostTasks({ reason: 'restarted' });
-      expect(first.map((t) => t.taskId)).toEqual(['orphan']);
-      expect(first[0]!.status).toBe('lost');
-
-      const second = await service.reconcileStartupLostTasks({ reason: 'restarted' });
-      expect(second).toEqual([]); // already terminal → not re-collected
-      expect(events).toEqual(['completed']); // exactly one completion event
-    } finally {
-      closeLocalRuntimeDb(dataDir);
-      await rm(dataDir, { recursive: true, force: true });
-    }
-  });
-});
diff --git a/packages/local-runtime/test/unit/local-background-task-stop-races.test.ts b/packages/local-runtime/test/unit/local-background-task-stop-races.test.ts
deleted file mode 100644
index afb6b805..00000000
--- a/packages/local-runtime/test/unit/local-background-task-stop-races.test.ts
+++ /dev/null
@@ -1,119 +0,0 @@
-import { mkdtemp, rm } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-
-import { describe, expect, it } from 'vitest';
-import { LocalTaskStopTool } from '@mavis/agent-tools/desktop';
-
-import { LocalBackgroundTaskService } from '../../src/background-task/service.js';
-import {
-  FsLocalTaskOutputStore,
-  SqliteLocalBackgroundTaskStore,
-} from '../../src/background-task/store.js';
-import { closeLocalRuntimeDb } from '../../src/persistence/db.js';
-import { taskRecord, taskStoreWithPatch, toolContext } from './background-task-test-helpers.js';
-
-describe('local background task stop concurrency', () => {
-  it.each(['running', 'succeeded', 'failed'] as const)(
-    'reports stop failure without overwriting a concurrent %s outcome',
-    async (outcome) => {
-      const dataDir = await mkdtemp(join(tmpdir(), 'local-background-stop-failure-'));
-      try {
-        const store = new SqliteLocalBackgroundTaskStore(dataDir);
-        const service = new LocalBackgroundTaskService({
-          store,
-          outputStore: new FsLocalTaskOutputStore(dataDir),
-          stopRuntime: async () => {
-            if (outcome !== 'running')
-              await service.patch('stop-failure', {
-                status: outcome,
-                endedAt: 10,
-                lastError:
-                  outcome === 'failed'
-                    ? { code: 'BASH_FAILED', message: 'command failed' }
-                    : undefined,
-              });
-            throw new Error('runtime cleanup failed');
-          },
-        });
-        await store.create(
-          taskRecord('stop-failure', 'session-a', { kind: 'bash', status: 'running' }),
-        );
-        const result = await new LocalTaskStopTool(service).execute(toolContext('session-a'), {
-          task_id: 'stop-failure',
-        });
-        expect(result.isError).toBe(true);
-        expect(result.text).toContain('runtime cleanup failed');
-        expect(result.text).toContain('Process cleanup could not be confirmed');
-        expect(result.details).toMatchObject({
-          status: outcome === 'running' ? 'canceled' : outcome,
-          stopError: { code: 'TASK_STOP_FAILED', message: 'runtime cleanup failed' },
-        });
-        const persisted = await store.get('stop-failure');
-        expect(persisted?.metadata?.stopError).toMatchObject({ code: 'TASK_STOP_FAILED' });
-        if (outcome === 'failed')
-          expect(persisted?.lastError).toEqual({ code: 'BASH_FAILED', message: 'command failed' });
-        const repeated = await new LocalTaskStopTool(service).execute(toolContext('session-a'), {
-          task_id: 'stop-failure',
-        });
-        expect(repeated.isError).toBe(true);
-      } finally {
-        closeLocalRuntimeDb(dataDir);
-        await rm(dataDir, { recursive: true, force: true });
-      }
-    },
-  );
-
-  it('coalesces concurrent task_stop calls into one runtime stop and one completion event', async () => {
-    const dataDir = await mkdtemp(join(tmpdir(), 'local-background-stop-race-'));
-    try {
-      const store = new SqliteLocalBackgroundTaskStore(dataDir, () => 70_000);
-      const trackingStore = taskStoreWithPatch(store, async () => undefined);
-      const appendEvent = trackingStore.appendEvent.bind(trackingStore);
-      let completedEvents = 0;
-      trackingStore.appendEvent = async (event) => {
-        if (event.type === 'completed') completedEvents += 1;
-        await appendEvent(event);
-      };
-      let stopCalls = 0;
-      let reportStopEntered!: () => void;
-      const stopEntered = new Promise<void>((resolve) => {
-        reportStopEntered = resolve;
-      });
-      let releaseStop!: () => void;
-      const stopGate = new Promise<void>((resolve) => {
-        releaseStop = resolve;
-      });
-      const service = new LocalBackgroundTaskService({
-        store: trackingStore,
-        outputStore: new FsLocalTaskOutputStore(dataDir),
-        nowMs: () => 70_000,
-        stopRuntime: async () => {
-          stopCalls += 1;
-          reportStopEntered();
-          await stopGate;
-        },
-      });
-      await store.create(taskRecord('running-task', 'session-a', { status: 'running' }));
-
-      const first = service.stop('running-task', 'reason-a');
-      await stopEntered;
-      const second = service.stop('running-task', 'reason-b');
-      await Promise.resolve();
-      expect(stopCalls).toBe(1);
-
-      releaseStop();
-      const [firstResult, secondResult] = await Promise.all([first, second]);
-      expect(firstResult).toMatchObject({
-        status: 'canceled',
-        lastError: { code: 'TASK_CANCELED', message: 'reason-a' },
-      });
-      expect(secondResult).toEqual(firstResult);
-      expect(stopCalls).toBe(1);
-      expect(completedEvents).toBe(1);
-    } finally {
-      closeLocalRuntimeDb(dataDir);
-      await rm(dataDir, { recursive: true, force: true });
-    }
-  });
-});
diff --git a/packages/tui/test/unit/tui-tool-evidence.test.ts b/packages/tui/test/unit/tui-tool-evidence.test.ts
deleted file mode 100644
index 4c826fc5..00000000
--- a/packages/tui/test/unit/tui-tool-evidence.test.ts
+++ /dev/null
@@ -1,264 +0,0 @@
-import { stripVTControlCharacters } from 'node:util';
-
-import { describe, expect, it } from 'vitest';
-
-import { renderTuiStructuredPreview } from '../../src/tui/transcript/presentation/structured-preview.js';
-import { syntaxLanguageForPath } from '../../src/tui/transcript/presentation/syntax-highlight.js';
-import { createTranscriptCell } from '../../src/tui/transcript/model.js';
-import {
-  resolveTranscriptToolDefinition,
-  type TranscriptToolDefinition,
-} from '../../src/tui/transcript/tool-definitions.js';
-import { presentTranscriptToolEvidence } from '../../src/tui/transcript/tool-evidence.js';
-import { MINIMAX_CODE_DARK_THEME, MINIMAX_CODE_LIGHT_THEME } from '../../src/tui/theme/palettes.js';
-import {
-  applyTuiRenderTheme,
-  createTuiChalk,
-  getTuiThemeSnapshot,
-  tuiColors,
-} from '../../src/tui/theme/runtime.js';
-
-function definitionFor(title: string): TranscriptToolDefinition {
-  const definition = resolveTranscriptToolDefinition(title);
-  if (!definition) throw new Error(`Missing tool definition for ${title}`);
-  return definition;
-}
-
-describe('transcript tool evidence', () => {
-  it('uses the command purpose as its summary and keeps the executable source in details', () => {
-    const evidence = presentTranscriptToolEvidence(createTranscriptCell({
-      id: 'bash-purpose', kind: 'tool', status: 'succeeded', title: 'bash',
-      content: JSON.stringify({ command: 'pnpm test', description: '验证 Bash 回归' }),
-      detail: 'passed', createdAtMs: 1,
-    }), definitionFor('bash'), { width: 80, prefix: '    ', displayMode: 'preview' });
-    expect(evidence.summary).toContain('验证 Bash 回归');
-    expect(stripVTControlCharacters(evidence.lines.join('\n'))).toContain('$ pnpm test');
-  });
-  it('renders a highlighted shell command separately from its quieter output', () => {
-    const evidence = presentTranscriptToolEvidence(
-      createTranscriptCell({
-        id: 'shell',
-        kind: 'tool',
-        status: 'succeeded',
-        title: 'bash',
-        content: JSON.stringify({ command: 'if test -f package.json; then echo "ready"; fi' }),
-        detail: 'package.json\nready',
-        createdAtMs: 1,
-      }),
-      definitionFor('bash'),
-      { width: 80, prefix: '    ', displayMode: 'preview' },
-    );
-
-    const plain = stripVTControlCharacters(evidence.lines.join('\n'));
-    expect(evidence.summary).toBe('if test -f package.json; then echo "ready"; fi · 2 output lines');
-    expect(plain).toContain('$ if test -f package.json; then echo "ready"; fi');
-    expect(plain).toContain('│ package.json');
-    expect(plain).toContain('│ ready');
-    expect(syntaxLanguageForPath('script.sh')).toBe('bash');
-  });
-
-  it('uses executable-focused shell highlighting in expanded transcript evidence', () => {
-    const original = getTuiThemeSnapshot();
-    const originalPalette =
-      original.appearance === 'light' ? MINIMAX_CODE_LIGHT_THEME : MINIMAX_CODE_DARK_THEME;
-    applyTuiRenderTheme(MINIMAX_CODE_DARK_THEME, 3);
-
-    try {
-      const evidence = presentTranscriptToolEvidence(
-        createTranscriptCell({
-          id: 'shell-executable-highlights',
-          kind: 'tool',
-          status: 'succeeded',
-          title: 'bash',
-          content: JSON.stringify({ command: 'cp source target && rm target | mv backup restored' }),
-          detail: undefined,
-          createdAtMs: 1,
-        }),
-        definitionFor('bash'),
-        { width: 80, prefix: '    ', displayMode: 'expanded' },
-      );
-      const rendered = evidence.lines.join('\n');
-      const ansi = createTuiChalk({ colorLevel: 3 });
-
-      expect(rendered).toContain(ansi.bold.hex(tuiColors.accent)('cp'));
-      expect(rendered).toContain(ansi.bold.hex(tuiColors.accent)('rm'));
-      expect(rendered).toContain(ansi.bold.hex(tuiColors.accent)('mv'));
-    } finally {
-      applyTuiRenderTheme(originalPalette, original.colorLevel);
-    }
-  });
-
-  it('keeps only the first line of a multiline shell command in the summary', () => {
-    const evidence = presentTranscriptToolEvidence(
-      createTranscriptCell({
-        id: 'shell-multiline',
-        kind: 'tool',
-        status: 'succeeded',
-        title: 'bash',
-        content: JSON.stringify({ command: "git commit -F - <<'EOF'\nsubject line\nEOF" }),
-        detail: undefined,
-        createdAtMs: 1,
-      }),
-      definitionFor('bash'),
-      { width: 80, prefix: '    ', displayMode: 'collapsed' },
-    );
-
-    expect(evidence.summary).toBe("git commit -F - <<'EOF'… · no output");
-    expect(evidence.summary).not.toContain('subject line');
-  });
-
-  it('syntax-highlights Read output from the requested file type with a stable line gutter', () => {
-    const evidence = presentTranscriptToolEvidence(
-      createTranscriptCell({
-        id: 'read',
-        kind: 'tool',
-        status: 'succeeded',
-        title: 'read',
-        content: JSON.stringify({ path: 'src/server.ts', offset: 12 }),
-        detail: 'const port = 3000;\nexport { port };',
-        createdAtMs: 1,
-      }),
-      definitionFor('read'),
-      { width: 80, prefix: '    ', displayMode: 'preview' },
-    );
-
-    const plain = stripVTControlCharacters(evidence.lines.join('\n'));
-    expect(evidence.summary).toBe('src/server.ts · 2 lines');
-    expect(plain).toContain('12 │ const port = 3000;');
-    expect(plain).toContain('13 │ export { port };');
-    expect(syntaxLanguageForPath('src/server.ts')).toBe('typescript');
-  });
-
-  it('keeps the newest shell output while running and head plus tail after completion', () => {
-    const output = Array.from({ length: 8 }, (_, index) => `line-${index + 1}`).join('\n');
-    const running = presentTranscriptToolEvidence(
-      createTranscriptCell({
-        id: 'running',
-        kind: 'tool',
-        status: 'running',
-        title: 'bash',
-        content: JSON.stringify({ command: 'pnpm test' }),
-        detail: output,
-        createdAtMs: 1,
-      }),
-      definitionFor('bash'),
-      { width: 80, prefix: '    ', displayMode: 'preview' },
-    );
-    const completed = presentTranscriptToolEvidence(
-      createTranscriptCell({
-        id: 'completed',
-        kind: 'tool',
-        status: 'succeeded',
-        title: 'bash',
-        content: JSON.stringify({ command: 'pnpm test' }),
-        detail: output,
-        createdAtMs: 1,
-      }),
-      definitionFor('bash'),
-      { width: 80, prefix: '    ', displayMode: 'preview' },
-    );
-
-    const runningPlain = stripVTControlCharacters(running.lines.join('\n'));
-    expect(runningPlain).not.toContain('line-1');
-    expect(runningPlain).toContain('line-8');
-    expect(runningPlain).toContain('5 earlier lines');
-
-    const completedPlain = stripVTControlCharacters(completed.lines.join('\n'));
-    expect(completedPlain).toContain('line-1');
-    expect(completedPlain).toContain('line-8');
-    expect(completedPlain).toContain('5 lines hidden');
-  });
-
-  it('summarizes search results and shows a small path sample', () => {
-    const evidence = presentTranscriptToolEvidence(
-      createTranscriptCell({
-        id: 'grep',
-        kind: 'tool',
-        status: 'succeeded',
-        title: 'grep',
-        content: JSON.stringify({ pattern: 'renderTool', path: 'packages/tui' }),
-        detail: [
-          'packages/tui/src/a.ts:12:renderTool()',
-          'packages/tui/src/b.ts:4:renderTool()',
-          'packages/tui/src/c.ts:9:renderTool()',
-          'packages/tui/src/d.ts:2:renderTool()',
-        ].join('\n'),
-        createdAtMs: 1,
-      }),
-      definitionFor('grep'),
-      { width: 80, prefix: '    ', displayMode: 'preview' },
-    );
-
-    const plain = stripVTControlCharacters(evidence.lines.join('\n'));
-    expect(evidence.summary).toBe('renderTool · 4 matches');
-    expect(plain).toContain('packages/tui/src/a.ts:12');
-    expect(plain).toContain('1 more match');
-    expect(plain).not.toContain('packages/tui/src/d.ts:2');
-  });
-
-  it('keeps failed Read output as an error instead of pretending it is source code', () => {
-    const evidence = presentTranscriptToolEvidence(
-      createTranscriptCell({
-        id: 'read-failed',
-        kind: 'tool',
-        status: 'failed',
-        title: 'read',
-        content: JSON.stringify({ path: 'src/missing.ts' }),
-        detail: 'ENOENT: file not found',
-        createdAtMs: 1,
-      }),
-      definitionFor('read'),
-      { width: 80, prefix: '    ', displayMode: 'preview' },
-    );
-
-    const plain = stripVTControlCharacters(evidence.lines.join('\n'));
-    expect(evidence.summary).toBe('src/missing.ts');
-    expect(plain).toContain('× ENOENT: file not found');
-    expect(plain).not.toContain('1 │');
-  });
-
-  it('pretty-prints structured fallback results without dumping one-line JSON', () => {
-    const evidence = presentTranscriptToolEvidence(
-      createTranscriptCell({
-        id: 'mcp',
-        kind: 'tool',
-        status: 'succeeded',
-        title: 'mcp__repo__inspect',
-        content: JSON.stringify({ path: 'src' }),
-        detail: JSON.stringify({ files: 12, status: 'ready' }),
-        createdAtMs: 1,
-      }),
-      definitionFor('mcp__repo__inspect'),
-      { width: 80, prefix: '    ', displayMode: 'expanded' },
-    );
-
-    const plain = stripVTControlCharacters(evidence.lines.join('\n'));
-    expect(plain).toContain('│ {');
-    expect(plain).toContain('"files": 12');
-    expect(plain).toContain('"status": "ready"');
-    expect(plain).not.toContain('{"files":12');
-  });
-
-  it('syntax-highlights file structured previews instead of painting the body uniformly', () => {
-    const rendered = renderTuiStructuredPreview(
-      {
-        schemaVersion: 1,
-        state: 'applied',
-        blocks: [
-          {
-            kind: 'file',
-            path: 'src/config.ts',
-            content: 'export const enabled = true;',
-            lineCount: 1,
-            truncated: false,
-          },
-        ],
-      },
-      80,
-      { maxBodyLines: 3 },
-    ).join('\n');
-
-    expect(stripVTControlCharacters(rendered)).toContain('1 export const enabled = true;');
-    expect(syntaxLanguageForPath('src/config.ts')).toBe('typescript');
-  });
-});
diff --git a/packages/tui/test/unit/tui-tool-summary.test.ts b/packages/tui/test/unit/tui-tool-summary.test.ts
deleted file mode 100644
index b3c478da..00000000
--- a/packages/tui/test/unit/tui-tool-summary.test.ts
+++ /dev/null
@@ -1,54 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { stripVTControlCharacters } from 'node:util';
-import { formatTuiToolSummary } from '../../src/tui/transcript/presentation/tool-summary.js';
-import { TranscriptView } from '../../src/tui/transcript/view.js';
-import { createTranscriptCell } from '../../src/tui/transcript/model.js';
-
-describe('tool operation summaries', () => {
-  it.each([
-    [{ pattern: 'watchStream', path: 'src' }, 'watchStream in src'],
-    [{ query: 'watchStream', file_path: 'src/app.ts' }, 'watchStream in src/app.ts'],
-    [{ command: 'pnpm test', cwd: 'packages/tui' }, 'pnpm test · in packages/tui'],
-    [{ command: 'pnpm test', description: '验证 Bash 回归' }, '验证 Bash 回归'],
-    [{ path: 'src/app.ts' }, 'src/app.ts'],
-    [{ pattern: '\x1b[31m中文\x1b[0m\nsecond', path: 'src' }, '中文 in src'],
-  ])('shows the operation and its scope: %j', (input, expected) => {
-    expect(formatTuiToolSummary(JSON.stringify(input))).toBe(expected);
-  });
-
-  it('retains an earlier failed attempt when the same read later succeeds', () => {
-    const cells = ['failed', 'succeeded'].map((status, index) => createTranscriptCell({
-      id: `read-${index}`, kind: 'tool', title: 'read',
-      status: status === 'failed' ? 'failed' : 'succeeded',
-      content: JSON.stringify({ path: 'src/app.ts' }),
-      detail: index === 0 ? 'Permission denied' : 'Read succeeded',
-      turnId: 'turn', createdAtMs: index,
-    }));
-    const view = new TranscriptView(() => cells);
-    const compact = stripVTControlCharacters(view.render(80).join('\n'));
-    expect(compact).toContain('Read 1 file');
-    expect(compact).toContain('1 failed');
-    expect(compact).toContain('2 calls');
-    view.toggleDetailMode();
-    const detailed = stripVTControlCharacters(view.render(80).join('\n'));
-    expect(detailed).toContain('Permission denied');
-    expect(detailed).toContain('Read succeeded');
-  });
-
-  it('keeps different queries and tools on the same path distinct', () => {
-    const cells = [
-      { title: 'read', input: { path: 'src' } },
-      { title: 'grep', input: { path: 'src', pattern: 'first' } },
-      { title: 'grep', input: { path: 'src', pattern: 'second' } },
-    ].map(({ title, input }, index) => createTranscriptCell({
-      id: `tool-${index}`, kind: 'tool', title, status: 'succeeded',
-      content: JSON.stringify(input), turnId: 'turn', createdAtMs: index,
-    }));
-    const view = new TranscriptView(() => cells);
-    expect(stripVTControlCharacters(view.render(80).join('\n'))).toContain('Explored 3 operations');
-    view.toggleDetailMode();
-    const detailed = stripVTControlCharacters(view.render(80).join('\n'));
-    expect(detailed).toContain('first in src');
-    expect(detailed).toContain('second in src');
-  });
-});
diff --git a/release/public-source.json b/release/public-source.json
index 826bcf0c..1cec79d2 100644
--- a/release/public-source.json
+++ b/release/public-source.json
@@ -406,9 +406,6 @@
     "packages/agent-tools/src/shared/rg-sensitive.ts",
     "packages/agent-tools/src/shared/web-search.ts",
     "packages/agent-tools/src/shared/write-capture.ts",
-    "packages/agent-tools/test/desktop/local-bash-output.test.ts",
-    "packages/agent-tools/test/desktop/local-bash-timeout.test.ts",
-    "packages/agent-tools/test/desktop/local-task-output-polling.test.ts",
     "packages/browser-core/package.json",
     "packages/browser-core/src/browser-action-artifacts.ts",
     "packages/browser-core/src/browser-action-helpers.ts",
@@ -803,7 +800,6 @@
     "packages/local-runtime-v2/src/service/agent/storage/legacy-custom-identity-receipt.ts",
     "packages/local-runtime-v2/src/service/agent/storage/runtime-index.ts",
     "packages/local-runtime-v2/src/service/background-bash/contracts.ts",
-    "packages/local-runtime-v2/src/service/background-bash/executor.test.ts",
     "packages/local-runtime-v2/src/service/background-bash/executor.ts",
     "packages/local-runtime-v2/src/service/background-bash/index.ts",
     "packages/local-runtime-v2/src/service/background-bash/initialize.ts",
@@ -2655,9 +2651,6 @@
     "packages/local-runtime/test/unit/content-safety-api-v2.test.ts",
     "packages/local-runtime/test/unit/content-safety-turn-v2.test.ts",
     "packages/local-runtime/test/unit/error-reporting-privacy.test.ts",
-    "packages/local-runtime/test/unit/local-background-bash-review-regressions.test.ts",
-    "packages/local-runtime/test/unit/local-background-bash-runner.test.ts",
-    "packages/local-runtime/test/unit/local-background-task-stop-races.test.ts",
     "packages/local-runtime/test/unit/local-background-task-task-output-polling-reminder.test.ts",
     "packages/local-runtime/test/unit/local-memory-edit-literal.test.ts",
     "packages/local-runtime/test/unit/local-native-tools.test.ts",
@@ -3304,9 +3297,7 @@
     "packages/tui/test/unit/tui-terminal-image-paste.test.ts",
     "packages/tui/test/unit/tui-terminal-text-paste.test.ts",
     "packages/tui/test/unit/tui-thinking-preview.test.ts",
-    "packages/tui/test/unit/tui-tool-evidence.test.ts",
     "packages/tui/test/unit/tui-tool-preview-diff-omitted.test.ts",
-    "packages/tui/test/unit/tui-tool-summary.test.ts",
     "packages/tui/test/unit/tui-transcript-presentation.test.ts",
     "packages/tui/test/unit/tui-transcript-view.test.ts",
     "packages/tui/test/unit/tui-workspace-status-line.test.ts",
diff --git a/test/vitest-suites.json b/test/vitest-suites.json
index c6771c48..5bc27008 100644
--- a/test/vitest-suites.json
+++ b/test/vitest-suites.json
@@ -176,16 +176,7 @@
       "packages/tui/test/unit/tui/theme/palettes.test.ts",
       "packages/tui/test/unit/tui/theme/runtime.test.ts",
       "packages/tui/test/unit/tui-plugin-mentions.test.ts",
-      "packages/local-runtime-v2/src/service/turn-system/agent-host/assembly/local-turn-plugin-capabilities.test.ts",
-      "packages/agent-tools/test/desktop/local-bash-output.test.ts",
-      "packages/agent-tools/test/desktop/local-bash-timeout.test.ts",
-      "packages/agent-tools/test/desktop/local-task-output-polling.test.ts",
-      "packages/local-runtime/test/unit/local-background-bash-runner.test.ts",
-      "packages/local-runtime/test/unit/local-background-bash-review-regressions.test.ts",
-      "packages/local-runtime/test/unit/local-background-task-stop-races.test.ts",
-      "packages/local-runtime-v2/src/service/background-bash/executor.test.ts",
-      "packages/tui/test/unit/tui-tool-evidence.test.ts",
-      "packages/tui/test/unit/tui-tool-summary.test.ts"
+      "packages/local-runtime-v2/src/service/turn-system/agent-host/assembly/local-turn-plugin-capabilities.test.ts"
     ],
     "status-contract": [
       "packages/tui/test/unit/tui-build-mode-contract.test.ts"
diff --git a/third_party/pi-mono/MINIMAX_CHANGES.md b/third_party/pi-mono/MINIMAX_CHANGES.md
index 391ec23a..ecd6608b 100644
--- a/third_party/pi-mono/MINIMAX_CHANGES.md
+++ b/third_party/pi-mono/MINIMAX_CHANGES.md
@@ -19,7 +19,7 @@ No upstream source files are changed in the baseline import.
 - Change: require exit code zero for success; preserve signals, cancellation reasons, timeout deadlines, and partial output in structured success and failure results. Add an optional original head-and-tail preview and host-owned persistence so managed commands use one complete log. Report persistence failures separately from the process outcome.
 - The existing exit-code-only helper and default tail preview remain compatible. Process cleanup and command timers retain their existing lifecycle.
 - Provenance: shared MiniMax Bash implementation, adapted to the standalone source distribution. Existing upstream notices and licenses apply; no new dependency is introduced. Upstream PR: not opened.
-- Regression coverage: the declared local Bash output, timeout, background executor, runner, stop-race, and child-lifecycle tests exercise the vendored implementation through its product consumers. Vendored upstream suites remain outside this distribution's verification; real-model and Windows acceptance are separate.
+- Regression coverage: the existing child Bash lifecycle, turn executor, and built-in catalog tests cover command deadlines, native output capability gating, and rendered prompt guidance. Vendored upstream suites remain outside this distribution's verification; real-model and Windows acceptance are separate.
 
 ### 2026-09-21 — report why the edit unified patch was omitted
 

From 9cb9d8ca7556e5d69b1d68fbeadcaae071d36605 Mon Sep 17 00:00:00 2001
From: muyu <muyu@minimaxi.com>
Date: Wed, 23 Sep 2026 21:27:13 +0800
Subject: [PATCH 3/3] fix: bound background Bash receipt purpose

---
 .../agent-tools/src/desktop/local-pi-tools.ts |  7 ++-
 .../agent-host/execution/executor.test.ts     | 48 +++++++++++++++++++
 2 files changed, 54 insertions(+), 1 deletion(-)

diff --git a/packages/agent-tools/src/desktop/local-pi-tools.ts b/packages/agent-tools/src/desktop/local-pi-tools.ts
index a206248c..3d86bf4b 100644
--- a/packages/agent-tools/src/desktop/local-pi-tools.ts
+++ b/packages/agent-tools/src/desktop/local-pi-tools.ts
@@ -712,7 +712,12 @@ function backgroundBashToolResult(
       ? ` Command limit: ${timing.commandTimeoutSeconds}s total; yielding does not reset it.`
       : '';
   const purpose =
-    typeof details.description === 'string' ? `Purpose: ${details.description}\n` : '';
+    typeof details.description === 'string'
+      ? `Purpose: ${limitDesktopHeadTailLines(details.description, {
+          maxBytes: 1024,
+          notice: () => '[purpose truncated]',
+        }).text}\n`
+      : '';
   const text = `<bash_background task_id="${taskId}">\n${purpose}${lead}${timingText} The owning conversation will automatically resume when it finishes; use task_output to inspect incremental output, and task_stop to cancel if that tool is available.\n</bash_background>`;
   return {
     tool_name: LocalBashToolDef.name,
diff --git a/packages/local-runtime-v2/src/service/turn-system/agent-host/execution/executor.test.ts b/packages/local-runtime-v2/src/service/turn-system/agent-host/execution/executor.test.ts
index 3c57db5f..6b716d09 100644
--- a/packages/local-runtime-v2/src/service/turn-system/agent-host/execution/executor.test.ts
+++ b/packages/local-runtime-v2/src/service/turn-system/agent-host/execution/executor.test.ts
@@ -820,6 +820,54 @@ describe("LocalRuntimeTurnExecutor Plugin prompt admission", () => {
 });
 
 describe("LocalRuntimeTurnExecutor Bash output capability", () => {
+  it.each([true, false])(
+    "bounds Bash receipt purpose text (run_in_background=%s)",
+    async (runInBackground) => {
+      const startBackground = vi.fn(async (_ctx: unknown, _input: unknown) => ({
+        status: "started" as const,
+        taskId: "receipt-task",
+      }));
+      const runManagedForeground = vi.fn(async (_ctx: unknown, _input: unknown) => ({
+        status: "auto_promoted" as const,
+        taskId: "receipt-task",
+      }));
+      const tool = new LocalBashTool(
+        "/tmp/workspace",
+        { startBackground, runManagedForeground },
+        { mode: "off" },
+      );
+      const command = "echo " + "x".repeat(100_000);
+      for (const description of [undefined, "说明🙂".repeat(20_000), "Inspect workspace"]) {
+        const result = await tool.execute(
+          {
+            sessionId: "session-1",
+            turnId: "turn-1",
+            canConsumeBackgroundBashOutput: true,
+          },
+          { command, description, timeout: 600, run_in_background: runInBackground },
+        );
+        expect(Buffer.byteLength(result.text, "utf8")).toBeLessThanOrEqual(24 * 1024);
+        expect(result.text).not.toContain("\uFFFD");
+        for (const retained of [
+          'task_id="receipt-task"', "Command limit: 600s", "task_output", "task_stop",
+        ]) {
+          expect(result.text).toContain(retained);
+        }
+        expect(result.text).toContain(
+          description === "Inspect workspace"
+            ? "Purpose: Inspect workspace\n"
+            : "[purpose truncated]",
+        );
+        expect(result.content).toEqual([{ type: "text", text: result.text }]);
+        expect(result.details?.description).toBe(description ?? command);
+        const adapter = runInBackground ? startBackground : runManagedForeground;
+        expect(adapter.mock.lastCall?.[1]).toMatchObject({
+          command, description: description ?? command,
+        });
+      }
+    },
+  );
+
   it.each([
     {
       name: "custom bash-only selector",