@pi-unipi/unipi 3.0.0-alpha.29 → 3.0.0-alpha.30

package/CHANGELOG.md

@@ -6,6 +6,24 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [3.0.0-alpha.30] — 2026-10-05
+
+### Changed
+- `watchdog`: **on by default, for bash calls only.** A bash call that still looks stuck after the first check (2 min) is handed to a background task, never killed by default; background tasks and other tools stay unwatched unless you turn them on. (UNI-107)
+- `watchdog`: bash calls are judged by process activity (no CPU, disk or output on two checks), a jev "will it finish on its own?" score on two checks in a row, or jev expecting the command to take seconds; a time limit written in the command (`timeout N`, `sleep N &&`, a bounded `seq … sleep` loop) holds every trigger off until it passes. Checks every 3 min after the first at 2 min. On a 20-case holdout: 9/10 stuck caught, 0/10 false (majority of 3 jev runs). Detached bash cards show `→ background task <id>` instead of an exit footer. (UNI-107)
+- `watchdog`: a bash call that looks stuck is no longer killed by default: the call returns to the agent at once with the output so far, and the command keeps running as a background task the agent can check (`bg_logs`) or stop (`bg_kill`); its completion wakes the agent as usual. New watchdog action `background` (the default; `kill` and `warn` stay available) and `/unipi:bg-detach [reason]` to send the running bash call to the background by hand. (UNI-107)
+- `kanboard`: agents can unblock tasks to Todo or resume a blocked task through `start`, with the usual claim and session limits. (UNI-105)
+- `kanboard`: unblocking and review rework no longer require a description; empty notes produce clean activity text. (UNI-106)
+- `kanboard`: agent-created labels must reuse existing project labels unless `--new-label` explicitly allows a new one; matching preserves stored spelling. (UNI-100)
+- `kanboard`: removed the board's Task defaults tab and legacy Blocking setting, preserving the other board settings. (UNI-101)
+- `kanboard`: `/unipi:kanboard show <lane>` filters the chat board, with lane and `--all` argument autocomplete. (UNI-102)
+- `background-tasks`: launch and completion notices use width-fitted one-line chips in every render style; expanded views retain command, output and task details. (UNI-103)
+- `compactor`: `/unipi:compact-then <prompt>` compacts before continuing, preserving next-turn versus after-run queue behavior while streaming. (UNI-104)
+- `utility`: **warnings share one collapsed shape.** Harness warning panels (Progress guard, watchdog, Kanboard unfinished-task, …) render label + synopsis + `Ctrl+O: full message (N rendered rows)` in regular/advanced; simple mode compresses them to the single label line (`▏ ⚠ UniPi · Source · Title`). Expanded views add the body; the advanced origin footer is dropped for warnings. Tool-result annotations with `severity: "warning"` (Fusion edit/shell nudges, Kanboard R1 reminder) trade the old plain two-line header for the same rail+fill panel — in simple mode just one rail line under the tool row.
+
+### Fixed
+- `fusion`: the shell-delegation nudge no longer re-arms on every new prompt (the reason it kept reappearing after each prompt). It now fires at most once per handoff gap: after a nudge, only a completed `sidekick`/`read_subagent` handoff re-arms it. The per-prompt streak reset stays, so a carried-over count still cannot fire early. Synopsis reads "Non-trivial shell work since last handoff" again — which is now literally true. (follow-up to UNI-87)
+
 ## [3.0.0-alpha.29] — 2026-10-04
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/unipi",
-  "version": "3.0.0-alpha.29",
+  "version": "3.0.0-alpha.30",
   "description": "All-in-one extension suite for Pi coding agent",
   "type": "module",
   "license": "MIT",
@@ -83,26 +83,26 @@
     "typebox": "^1.1.38"
   },
   "dependencies": {
-    "@pi-unipi/ask-user": "3.0.0-alpha.29",
-    "@pi-unipi/background-tasks": "3.0.0-alpha.29",
-    "@pi-unipi/btw": "3.0.0-alpha.29",
-    "@pi-unipi/command-enchantment": "3.0.0-alpha.29",
-    "@pi-unipi/compactor": "3.0.0-alpha.29",
-    "@pi-unipi/core": "3.0.0-alpha.29",
-    "@pi-unipi/footer": "3.0.0-alpha.29",
-    "@pi-unipi/fusion": "3.0.0-alpha.29",
-    "@pi-unipi/info-screen": "3.0.0-alpha.29",
-    "@pi-unipi/input-shortcuts": "3.0.0-alpha.29",
-    "@pi-unipi/kanboard": "3.0.0-alpha.29",
-    "@pi-unipi/mcp": "3.0.0-alpha.29",
-    "@pi-unipi/memory": "3.0.0-alpha.29",
-    "@pi-unipi/notify": "3.0.0-alpha.29",
-    "@pi-unipi/skill-registry": "3.0.0-alpha.29",
-    "@pi-unipi/subagents": "3.0.0-alpha.29",
-    "@pi-unipi/updater": "3.0.0-alpha.29",
-    "@pi-unipi/utility": "3.0.0-alpha.29",
-    "@pi-unipi/web-api": "3.0.0-alpha.29",
-    "@pi-unipi/workflow": "3.0.0-alpha.29"
+    "@pi-unipi/ask-user": "3.0.0-alpha.30",
+    "@pi-unipi/background-tasks": "3.0.0-alpha.30",
+    "@pi-unipi/btw": "3.0.0-alpha.30",
+    "@pi-unipi/command-enchantment": "3.0.0-alpha.30",
+    "@pi-unipi/compactor": "3.0.0-alpha.30",
+    "@pi-unipi/core": "3.0.0-alpha.30",
+    "@pi-unipi/footer": "3.0.0-alpha.30",
+    "@pi-unipi/fusion": "3.0.0-alpha.30",
+    "@pi-unipi/info-screen": "3.0.0-alpha.30",
+    "@pi-unipi/input-shortcuts": "3.0.0-alpha.30",
+    "@pi-unipi/kanboard": "3.0.0-alpha.30",
+    "@pi-unipi/mcp": "3.0.0-alpha.30",
+    "@pi-unipi/memory": "3.0.0-alpha.30",
+    "@pi-unipi/notify": "3.0.0-alpha.30",
+    "@pi-unipi/skill-registry": "3.0.0-alpha.30",
+    "@pi-unipi/subagents": "3.0.0-alpha.30",
+    "@pi-unipi/updater": "3.0.0-alpha.30",
+    "@pi-unipi/utility": "3.0.0-alpha.30",
+    "@pi-unipi/web-api": "3.0.0-alpha.30",
+    "@pi-unipi/workflow": "3.0.0-alpha.30"
   },
   "devDependencies": {
     "@earendil-works/pi-agent-core": "^0.87.1",

package/packages/ask-user/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/ask-user",
-  "version": "3.0.0-alpha.29",
+  "version": "3.0.0-alpha.30",
   "description": "Structured user input tool for Pi coding agent — single-select, multi-select, freeform",
   "type": "module",
   "main": "index.ts",
@@ -40,7 +40,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "3.0.0-alpha.29"
+    "@pi-unipi/core": "3.0.0-alpha.30"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.87.1",

package/packages/autocomplete/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/command-enchantment",
-  "version": "3.0.0-alpha.29",
+  "version": "3.0.0-alpha.30",
   "description": "Enhanced TUI autocomplete for /unipi:* commands — colored, sorted, and grouped by package",
   "type": "module",
   "main": "src/index.ts",

package/packages/autocomplete/src/constants.ts

@@ -75,6 +75,7 @@ export const COMMAND_REGISTRY: Record<string, string> = {
   "unipi:doctor":     "utility",
   "unipi:answer":     "utility",
   "unipi:summarize":  "utility",
+  "unipi:move":       "utility",
 
   // skill-registry
   "unipi:skills":     "skill-registry",
@@ -162,6 +163,7 @@ export const COMMAND_DESCRIPTIONS: Record<string, string> = {
   "unipi:answer":     "Answer the last reply — fixed input under the scrollable reply, per question, or web form",
   "unipi:summarize":  "Summarize your last reply again (answer first, then findings, open items, questions). Add text to ask about it",
   "unipi:skills":     "Manage skills — on/off per project, listed or not, the skill vault",
+  "unipi:move":       "Re-link sessions, trust, worktrees, boards and memories after moving this project",
 
   "unipi:kanboard":        "Kanboard — capture tasks, run them, open the board",
   "unipi:kanboard-add":    "Kanboard — capture a task into Backlog",

package/packages/background-tasks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/background-tasks",
-  "version": "3.0.0-alpha.29",
+  "version": "3.0.0-alpha.30",
   "description": "Background tasks for UniPi — durable shell jobs and delegated background agents with a footer dock",
   "type": "module",
   "main": "src/index.ts",
@@ -10,7 +10,7 @@
   },
   "dependencies": {
     "@earendil-works/pi-ai": "^0.87.1",
-    "@pi-unipi/core": "3.0.0-alpha.29",
+    "@pi-unipi/core": "3.0.0-alpha.30",
     "turndown": "^7.2.4"
   },
   "devDependencies": {

package/packages/background-tasks/src/cards.ts

@@ -1,12 +1,22 @@
 /**
- * @pi-unipi/background-tasks — tinted chat cards
+ * @pi-unipi/background-tasks — chat cards (badge + leader, no tinted box)
  *
- * Background-task launch/completion messages were plain single lines that got
- * lost in the transcript. These helpers render them as padded, background-
- * tinted boxes (same visual language as pi's tool cards) so a user scanning
- * the chat can spot "a bg task started here" / "it finished here" at a glance.
+ * Background-task launch/completion messages render as one dotted-leader line
+ * (same visual language as @pi-unipi/core's badge/leader kit used elsewhere —
+ * subagents, etc.): a padded four-letter accent chip, the bold task name, a
+ * dotted leader, and a dim right side.
+ *
+ *    BG   Run full test suite ························· started · wakes agent
+ *    DONE Run full test suite ························· exit 0 · 25s · agent woken
+ *    FAIL Run full test suite ························· exit 101 · 12s · agent woken
+ *    STOP Run full test suite ························· killed · 4s
+ *
+ * Collapsed is the chip line only. Expanded adds: the dim `$ command` line, an
+ * error line in error color, output tail lines, and the dim output path + id.
  */
-import { Box, Text } from "@earendil-works/pi-tui";
+import type { Component } from "@earendil-works/pi-tui";
+import { truncateToWidth } from "@earendil-works/pi-tui";
+import { badge, leader, STATE_COLOR, type RunState } from "@pi-unipi/core";
 import { formatDuration, taskDisplayName, type BgTaskSnapshot } from "./types.js";
 
 type ThemeLike = {
@@ -15,62 +25,79 @@ type ThemeLike = {
   bold: (text: string) => string;
 };
 
-type CardTone = "pending" | "success" | "error";
+/** Width-aware component — same shape as subagents' `lines()` helper. */
+const lines = (render: (w: number) => string[]): Component => ({ invalidate() {}, render });
 
-const BG_FOR_TONE: Record<CardTone, string> = {
-  pending: "toolPendingBg",
-  success: "toolSuccessBg",
-  error: "toolErrorBg",
+const CHIP: Record<"running" | "completed" | "failed" | "killed", string> = {
+  running: "BG  ",
+  completed: "DONE",
+  failed: "FAIL",
+  killed: "STOP",
 };
 
-function toneFor(status: BgTaskSnapshot["status"]): CardTone {
-  if (status === "running") return "pending";
-  if (status === "completed") return "success";
-  return "error";
+function runStateFor(status: BgTaskSnapshot["status"]): RunState {
+  if (status === "running") return "running";
+  if (status === "completed") return "completed";
+  if (status === "killed") return "cancelled";
+  return "failed";
 }
 
-function statusGlyph(theme: ThemeLike, status: BgTaskSnapshot["status"]): string {
-  if (status === "running") return theme.fg("accent", "●");
-  if (status === "completed") return theme.fg("success", "✓");
-  if (status === "killed") return theme.fg("warning", "■");
-  return theme.fg("error", "✗");
+function chip(theme: ThemeLike, status: BgTaskSnapshot["status"]): string {
+  return badge(theme, STATE_COLOR[runStateFor(status)], CHIP[status]);
 }
 
-function card(theme: ThemeLike, tone: CardTone, lines: string[]): Box {
-  const box = new Box(1, 0, (text) => theme.bg(BG_FOR_TONE[tone], text));
-  box.addChild(new Text(lines.join("\n"), 0, 0));
-  return box;
+function head(theme: ThemeLike, task: BgTaskSnapshot, right: string, width: number): string {
+  return leader(theme, `${chip(theme, task.status)} ${theme.bold(taskDisplayName(task))}`, theme.fg("dim", right), width);
 }
 
-/** `bg_run` result card: "● bg started <name> (id) · will wake agent" */
-export function renderLaunchCard(theme: ThemeLike, task: BgTaskSnapshot): Box {
-  const wake = task.triggerOnCompletion
-    ? theme.fg("dim", " · wakes agent on completion")
-    : task.notifyOnCompletion
-      ? theme.fg("dim", " · notifies on completion")
-      : theme.fg("dim", " · silent");
-  const head = `${statusGlyph(theme, "running")} ${theme.fg("accent", theme.bold("bg started"))} ${theme.fg("accent", taskDisplayName(task))} ${theme.fg("dim", `(${task.id})`)}${wake}`;
-  const cmd = theme.fg("dim", `$ ${task.command.length > 120 ? `${task.command.slice(0, 120)}…` : task.command}`);
-  return card(theme, "pending", [head, cmd]);
+function commandLine(theme: ThemeLike, task: BgTaskSnapshot, width: number): string {
+  const text = `  $ ${task.command.length > 120 ? `${task.command.slice(0, 120)}…` : task.command}`;
+  return truncateToWidth(theme.fg("dim", text), width, "…");
 }
 
-/** Completion notification card: "✓ bg done <name> · exit 0 · 25s" + last output lines */
-export function renderCompletionCard(theme: ThemeLike, task: BgTaskSnapshot | undefined): Box {
+/** `bg_run` result card: `BG   <name> ···· started · wakes agent`. */
+export function renderLaunchCard(theme: ThemeLike, task: BgTaskSnapshot, expanded = false): Component {
+  const wake = task.triggerOnCompletion ? "wakes agent" : task.notifyOnCompletion ? "notifies" : "silent";
+  return lines((w) => {
+    const out = [head(theme, task, `started · ${wake}`, w)];
+    if (!expanded) return out;
+    out.push(commandLine(theme, task, w));
+    if (task.error) out.push(truncateToWidth(theme.fg("error", `  ${task.error}`), w, "…"));
+    for (const line of task.outputTail ?? []) out.push(truncateToWidth(theme.fg("toolOutput", `  ${line}`), w, "…"));
+    out.push(truncateToWidth(theme.fg("dim", `  ${task.outputPath}`), w, "…"));
+    out.push(truncateToWidth(theme.fg("dim", `  (${task.id})`), w, "…"));
+    return out;
+  });
+}
+
+/** Completion notification card: `DONE <name> ···· exit 0 · 25s · agent woken` + tail. */
+export function renderCompletionCard(
+  theme: ThemeLike,
+  task: BgTaskSnapshot | undefined,
+  expanded = false,
+): Component {
   if (task === undefined) {
-    return card(theme, "success", [`${theme.fg("success", "✓")} ${theme.fg("accent", theme.bold("bg done"))}`]);
+    return lines((w) => [leader(theme, `${badge(theme, STATE_COLOR.completed, "DONE")} ${theme.bold("bg task")}`, "", w)]);
   }
-  const tone = toneFor(task.status);
-  const label =
-    task.status === "completed" ? "bg done" : task.status === "killed" ? "bg stopped" : "bg failed";
   const meta: string[] = [];
-  if (task.exitCode !== undefined && task.exitCode !== null) meta.push(`exit ${String(task.exitCode)}`);
-  if (task.endTime !== undefined) meta.push(formatDuration(task.endTime - task.startTime));
-  if (task.triggerOnCompletion) meta.push("agent woken");
-  const head = `${statusGlyph(theme, task.status)} ${theme.fg(tone === "error" ? "error" : "success", theme.bold(label))} ${theme.fg("accent", taskDisplayName(task))} ${theme.fg("dim", `(${task.id})`)}${meta.length > 0 ? theme.fg("dim", ` · ${meta.join(" · ")}`) : ""}`;
-  const lines = [head];
-  if (task.error) lines.push(theme.fg("error", task.error));
-  const tail = task.outputTail ?? [];
-  for (const line of tail) lines.push(theme.fg("toolOutput", `  ${line}`));
-  lines.push(theme.fg("dim", `  ${task.outputPath}`));
-  return card(theme, tone, lines);
+  if (task.status === "killed") {
+    if (task.endTime !== undefined) meta.push(formatDuration(task.endTime - task.startTime));
+    meta.unshift("killed");
+  } else {
+    if (task.exitCode !== undefined && task.exitCode !== null) meta.push(`exit ${String(task.exitCode)}`);
+    else if (task.status === "failed") meta.push(task.error ? "error" : "failed");
+    if (task.endTime !== undefined) meta.push(formatDuration(task.endTime - task.startTime));
+    if (task.triggerOnCompletion) meta.push("agent woken");
+  }
+  return lines((w) => {
+    const out = [head(theme, task, meta.join(" · "), w)];
+    if (!expanded) return out;
+    out.push(commandLine(theme, task, w));
+    if (task.error) out.push(truncateToWidth(theme.fg("error", `  ${task.error}`), w, "…"));
+    const tail = task.outputTail ?? [];
+    for (const line of tail) out.push(truncateToWidth(theme.fg("toolOutput", `  ${line}`), w, "…"));
+    out.push(truncateToWidth(theme.fg("dim", `  ${task.outputPath}`), w, "…"));
+    out.push(truncateToWidth(theme.fg("dim", `  (${task.id})`), w, "…"));
+    return out;
+  });
 }

package/packages/background-tasks/src/child-process.ts

@@ -16,7 +16,7 @@ export type ChildStdin = Writable;
 export interface OutputEventSource {
   on(event: "data", listener: (data: Buffer | string) => void): unknown;
   on(event: "end", listener: () => void): unknown;
-  [Symbol.asyncIterator](): AsyncIterableIterator<Buffer>;
+  [Symbol.asyncIterator]?(): AsyncIterableIterator<Buffer>;
 }
 
 /** Minimal child-process surface the registry drives. */

package/packages/background-tasks/src/index.ts

@@ -10,7 +10,15 @@
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { createSpinnerLine, isChildProcess, registerWaitSource, setHerdrWorking } from "@pi-unipi/core";
+import {
+  createSpinnerLine,
+  isChildProcess,
+  registerWaitSource,
+  setHerdrWorking,
+  setBashBackgroundAdopter,
+  type BashBackgroundRequest,
+  type BashDetachResult,
+} from "@pi-unipi/core";
 import { loadBackgroundTasksConfig } from "./config.js";
 import { BackgroundTaskRegistry } from "./registry.js";
 import {
@@ -274,12 +282,42 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
     clearFinishedNotices,
   });
 
+  // Core handoff adapter: when pi's bash tool decides a running command
+  // should move to the background (watchdog-driven or otherwise), core calls
+  // this callback with the already-running child. We adopt it as a standard
+  // background task via `adoptRunningProcess` and mark it watchdogAdopted so
+  // the watchdog itself skips automatic kills on the now-registry-owned task.
+  function bashBackgroundAdopter(request: BashBackgroundRequest): Promise<BashDetachResult | null> {
+    const ctx = currentCtx;
+    if (!ctx) return Promise.resolve(null);
+    return registry
+      .adoptRunningProcess(ctx, request.child, {
+        command: request.command,
+        stop: request.stop,
+        startTime: request.startTime,
+        initialOutput: request.initialOutput,
+        notifyOnCompletion: true,
+        triggerOnCompletion: true,
+      })
+      .then((task) => {
+        updateUi(ctx);
+        return { taskId: task.id, outputPath: task.outputPath };
+      })
+      .catch((error: unknown) => {
+        console.error(
+          `[background-tasks] bash background adoption failed: ${error instanceof Error ? error.message : String(error)}`,
+        );
+        return null;
+      });
+  }
+
   pi.on("session_start", async (_event, ctx) => {
     registry.setShuttingDown(false);
     wakeLineInstalled = false; // pi clears extension widgets on reload/new session
     setSharedTaskRegistry(registry);
     currentCtx = ctx;
     await registry.ensureRuntimeDir(ctx);
+    setBashBackgroundAdopter(bashBackgroundAdopter);
     updateUi(ctx);
     if (statusInterval) clearInterval(statusInterval);
     statusInterval = setInterval(() => {
@@ -291,6 +329,7 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
     registry.setShuttingDown(true);
     wakeLineInstalled = false;
     clearSharedTaskRegistry();
+    setBashBackgroundAdopter(null);
     currentCtx = undefined;
     if (statusInterval) {
       clearInterval(statusInterval);

package/packages/background-tasks/src/registry.ts

@@ -22,6 +22,7 @@ import {
   shellQuote,
   snapshot,
   taskDisplayName,
+  type AdoptRunningProcessOptions,
   type BgLogsDetails,
   type BgTask,
   type BgTaskSnapshot,
@@ -830,68 +831,170 @@ export class BackgroundTaskRegistry {
 
       task.child = child;
       task.pid = child.pid;
+      this.wireChildProcess(task, child, timeoutSeconds);
 
-      child.stdout?.on('data', (data) => {
-        this.appendChildOutput(task, data, 'stdout');
-      });
-      child.stderr?.on('data', (data) => {
-        this.appendChildOutput(task, data, 'stderr');
-      });
+      await this.writeMetadata(task);
+      this.onChange();
+      return task;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.writeNotice(task, `\n[background task spawn exception: ${message}]\n`);
+      await this.finalizeTask(task, 'failed', null, undefined, message);
+      throw new Error(`Failed to start background task: ${message}`);
+    }
+  }
 
-      child.on('error', (error) => {
-        this.writeNotice(task, `\n[background task spawn error: ${error.message}]\n`);
-        void this.finalizeTask(task, 'failed', null, undefined, error.message);
-      });
+  /**
+   * Adopt an already-running child process (e.g. a bash call handed off by
+   * core's `setBashBackgroundAdopter`) as a standard background task, without
+   * spawning anything ourselves. Shares all post-spawn wiring (output
+   * capture, close/error handling, timeout, metadata, notification) with
+   * `startTask` via `wireChildProcess`; the only difference is that the
+   * caller already owns a live `child` and may have buffered output that
+   * preceded adoption.
+   */
+  async adoptRunningProcess(
+    ctx: BackgroundTaskContext,
+    child: BackgroundTaskChildProcess,
+    options: AdoptRunningProcessOptions,
+  ): Promise<BgTask> {
+    const normalizedCommand = options.command.trim();
+    if (!normalizedCommand) throw new Error('Background command is empty');
+    if (this.shuttingDown)
+      throw new Error('Cannot adopt a background task while Pi is shutting down');
 
-      child.on('close', (code, signalName) => {
-        let status: TaskStatus;
-        let error: string | undefined;
-        if (task.killKind === 'user' || task.killKind === 'shutdown') {
-          status = 'killed';
-        } else if (task.killKind === 'timeout') {
-          status = 'failed';
-          error = task.error ?? `Timed out after ${String(timeoutSeconds)}s`;
-        } else if (task.killKind === 'output_cap') {
-          status = 'failed';
-          error = task.error ?? `Output exceeded cap of ${formatSize(this.maxOutputBytes)}`;
-        } else if ((code ?? 0) === 0) {
-          status = 'completed';
-        } else {
-          status = 'failed';
-          const exitCode = code === null ? 'null' : String(code);
-          error = `Exited with code ${exitCode}${signalName ? ` (${signalName})` : ''}`;
-        }
-        void this.finalizeTask(task, status, code, signalName, error);
-      });
+    const dir = await this.ensureRuntimeDir(ctx);
+    const id = this.makeTaskIdFn();
+    const outputAbsPath = join(dir.abs, `${id}.output`);
+    const metadataAbsPath = join(dir.abs, `${id}.json`);
+    const outputPath = join(dir.display, `${id}.output`);
+    const taskName =
+      normalizeTaskName(options.name) ?? deriveTaskNameFromCommand(normalizedCommand);
 
-      if (timeoutSeconds !== undefined) {
-        task.timeoutHandle = setTimeout(() => {
-          if (task.status !== 'running') return;
-          task.killKind = 'timeout';
-          task.error = `Timed out after ${String(timeoutSeconds)}s`;
-          this.writeNotice(task, `\n[background task timeout: ${task.error}]\n`);
-          try {
-            this.requestKill(task, 'SIGTERM');
-          } catch (error) {
-            void this.finalizeTask(
-              task,
-              'failed',
-              null,
-              undefined,
-              `${task.error}; kill failed: ${error instanceof Error ? error.message : String(error)}`,
-            );
-          }
-        }, timeoutSeconds * 1000);
+    const task: BgTask = {
+      id,
+      name: taskName,
+      command: normalizedCommand,
+      description: undefined,
+      status: 'running',
+      outputPath,
+      outputAbsPath,
+      metadataAbsPath,
+      cwd: ctx.cwd,
+      startTime: options.startTime,
+      exitCode: undefined,
+      pid: child.pid,
+      bytesWritten: 0,
+      isAgent: false,
+      notified: false,
+      notifyOnCompletion: options.notifyOnCompletion ?? true,
+      triggerOnCompletion: options.triggerOnCompletion ?? false,
+      timeoutSeconds: undefined,
+      terminalPublicationGate: undefined,
+      watchdogAdopted: true,
+      waiters: [],
+    };
+    this.tasks.set(id, task);
+
+    const stream = createWriteStream(outputAbsPath, { flags: 'a', encoding: 'utf8' });
+    task.stream = stream;
+    stream.on('error', (error) => {
+      task.error = `Output file write failed: ${error.message}`;
+      if (task.status === 'running') {
+        task.killKind = 'output_cap';
+        try {
+          this.requestKill(task, 'SIGTERM');
+        } catch (killError) {
+          void this.finalizeTask(
+            task,
+            'failed',
+            null,
+            undefined,
+            `${task.error}; kill failed: ${killError instanceof Error ? killError.message : String(killError)}`,
+          );
+        }
       }
+    });
 
+    try {
+      task.child = child;
+      task.externalStop = options.stop;
+      task.pid = undefined;
+      if (options.initialOutput) this.writeNotice(task, options.initialOutput);
+      this.wireChildProcess(task, child, undefined);
       await this.writeMetadata(task);
       this.onChange();
       return task;
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      this.writeNotice(task, `\n[background task spawn exception: ${message}]\n`);
+      this.writeNotice(task, `\n[background task adoption exception: ${message}]\n`);
       await this.finalizeTask(task, 'failed', null, undefined, message);
-      throw new Error(`Failed to start background task: ${message}`);
+      throw new Error(`Failed to adopt background task: ${message}`);
+    }
+  }
+
+  /**
+   * Shared post-spawn wiring: output capture, error/close handling, and the
+   * optional timeout escalation. Used by both `startTask` (fresh spawn) and
+   * `adoptRunningProcess` (already-running child) so the finalize/close
+   * semantics never drift between the two paths.
+   */
+  private wireChildProcess(
+    task: BgTask,
+    child: BackgroundTaskChildProcess,
+    timeoutSeconds: number | undefined,
+  ): void {
+    child.stdout?.on('data', (data) => {
+      this.appendChildOutput(task, data, 'stdout');
+    });
+    child.stderr?.on('data', (data) => {
+      this.appendChildOutput(task, data, 'stderr');
+    });
+
+    child.on('error', (error) => {
+      this.writeNotice(task, `\n[background task spawn error: ${error.message}]\n`);
+      void this.finalizeTask(task, 'failed', null, undefined, error.message);
+    });
+
+    child.on('close', (code, signalName) => {
+      let status: TaskStatus;
+      let error: string | undefined;
+      if (task.killKind === 'user' || task.killKind === 'shutdown') {
+        status = 'killed';
+      } else if (task.killKind === 'timeout') {
+        status = 'failed';
+        error = task.error ?? `Timed out after ${String(timeoutSeconds)}s`;
+      } else if (task.killKind === 'output_cap') {
+        status = 'failed';
+        error = task.error ?? `Output exceeded cap of ${formatSize(this.maxOutputBytes)}`;
+      } else if (code === 0 && !signalName) {
+        status = 'completed';
+      } else {
+        status = 'failed';
+        const exitCode = code === null ? 'null' : String(code);
+        error = `Exited with code ${exitCode}${signalName ? ` (${signalName})` : ''}`;
+      }
+      void this.finalizeTask(task, status, code, signalName, error);
+    });
+
+    if (timeoutSeconds !== undefined) {
+      task.timeoutHandle = setTimeout(() => {
+        if (task.status !== 'running') return;
+        task.killKind = 'timeout';
+        task.error = `Timed out after ${String(timeoutSeconds)}s`;
+        this.writeNotice(task, `\n[background task timeout: ${task.error}]\n`);
+        try {
+          this.requestKill(task, 'SIGTERM');
+        } catch (error) {
+          void this.finalizeTask(
+            task,
+            'failed',
+            null,
+            undefined,
+            `${task.error}; kill failed: ${error instanceof Error ? error.message : String(error)}`,
+          );
+        }
+      }, timeoutSeconds * 1000);
     }
   }
 
@@ -1471,6 +1574,11 @@ export class BackgroundTaskRegistry {
     if (task.status !== 'running') {
       throw new Error(`Task ${task.id} is ${task.status}, not running`);
     }
+    if (task.externalStop) {
+      task.externalStop();
+      task.killSignalSent = true;
+      return;
+    }
     if (!task.child) {
       throw new Error(`Task ${task.id} has no child process handle`);
     }