@runminton/pi-async-bash 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RunMintOn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,124 @@
-# Temporary Holding Version
+# Async Bash
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Long bash commands no longer hold a tool call hostage.
+
+- Finishes within 63 seconds: returns the normal bash result.
+- Still running after 63 seconds: returns a task ID, the command keeps running, and the original session is notified when it ends.
+- Adds `bash_task` with `status` and `kill`.
+- No `background` parameter. The model never has to guess how long a command will take.
+
+## Install
+
+```bash
+pi install npm:@runminton/pi-async-bash
+```
+
+Or load it for one invocation without changing your settings:
+
+```bash
+pi -e npm:@runminton/pi-async-bash
+```
+
+Installing modifies your pi configuration explicitly through `pi install`. Loading with `-e` does not.
+
+Verified on pi 1.3.0, Node 22.23.2 and macOS. Implementation reuses pi's local shell backend; Windows is untested.
+
+Do not load another extension that overrides `bash` at the same time. pi 1.3.0 reports duplicate tools as a conflict and selects a definition by load order; it does not compose two execution backends. This extension honours the standard `shellPath`, `shellCommandPrefix` and `tool_call` restrictions. It does not compose another extension's private spawn hook, SSH or sandbox execution backend.
+
+With a version of `pi-compact-tool` that no longer overrides bash execution, async-bash executes and compact renders; both load orders work. Older compact versions still register bash and must be updated together.
+
+## Usage
+
+Normal bash parameters are unchanged:
+
+```typescript
+bash({ command: "npm run e2e", timeout: 600 })
+```
+
+If the command is still running after 63 seconds, the call returns:
+
+```text
+Still running after 63 seconds. Task: <task_id>
+Log: <absolute_log_path>
+You will be notified when it finishes. Do not poll.
+Continue work that does not depend on this result. If none remains, end your turn and resume when notified.
+```
+
+Then, on demand:
+
+```typescript
+bash_task({ task_id: "...", action: "status" })
+bash_task({ task_id: "...", action: "kill" })
+```
+
+New task IDs are 8 random hexadecimal characters, for example `a3f8c921`, regenerated on collision. Existing UUID tasks remain readable and controllable.
+
+| Action | Behaviour |
+|---|---|
+| status | Returns the status, log location and a bounded log tail |
+| kill | Stops the managed process group and returns after observing the result; a finished task keeps its original result |
+
+`timeout` is the execution limit for the whole command. A background handoff does not restart it. The 63 seconds are a waiting threshold, not an execution timeout.
+
+`bash_task` no longer supports `wait`, and `bash` gains no synchronous waiting parameter. After a running result, continue work that does not depend on it; when nothing is left, end the turn and resume when notified.
+
+## Footer
+
+In the TUI, current-session background tasks appear through pi's native status API. The footer itself is not replaced and compact is not required:
+
+```text
+BG 2 · 3m 12s / 1m 05s
+```
+
+Each duration counts from when its command actually started, including the foreground 63 seconds. Entries are ordered by start time and refresh every second; IDs are not shown. A finished task is removed immediately, and the status disappears when nothing is running. Foreground commands and `unknown` tasks from an earlier runtime are never counted.
+
+Narrow terminals drop spaces inside durations first, then report omitted entries as `+N`, for example `BG 2 · 3m12s / +1`. The native footer still applies its single-line truncation to all extension statuses.
+
+Switching sessions only shows tasks the current session owns or inherits by reference. The compact tool row shows `Backgrounded` to record that a handoff happened at that point; the footer shows what is running now, and the completion notification carries the final result.
+
+## Lifecycle
+
+- Before a task ID is returned, Escape cancels the running command.
+- After a task ID is returned, Escape does not stop that task; use kill.
+- `/tree`, session switching, fork/clone and reload do not stop tasks.
+- Completion notifications wake only the owning session. Returning to another branch adds state but does not replay the automatic notification.
+- fork/clone inherits the same task ID without copying the process; an inheriting session can query and stop it explicitly.
+- A normal pi exit stops tasks managed by the current process.
+- After a crash, task survival and cleanup are not promised. A new runtime marks executions it cannot confirm as `unknown`; it does not guess an exit code or adopt or stop anything based on a stale PID.
+- Long-running services usually never exit on their own. A `running` task does not mean a service is ready to accept requests.
+
+Automatic handoff releases only that one bash call. When the same batch contains other blocking tools, the current turn may still have to wait.
+
+## Output and state
+
+Complete stdout/stderr is saved to a log. Task metadata lives under pi's agent data directory in `extension-data/async-bash/` and is never written into the project. Ordinary short commands also produce a raw output log, but expose no task ID and create no background completion notification.
+
+Completion notifications and `status` include at most 100 log lines and 16 KiB. Restored context has a separate 16 KiB total budget and does not repeatedly inject full logs.
+
+Statuses are `running`, `exited`, `killed`, `timed_out`, `failed` and `unknown`. A non-zero exit is still `exited`, with the exit code kept separately. Querying a failed task with `status` is not itself a tool error; `kill` on a failing terminal state is marked as an error.
+
+Inside codemode:
+
+- Short bash calls return the original structured fields such as `output` and `exit_code`.
+- Long bash calls return `task_id`, `status: "running"`, `log_path` and similar fields, with a null exit code.
+- `bash_task` returns task status and a bounded `output`; scripts should check status and exit code.
+
+There is no automatic log cleanup, PTY, automatic retry, task list or cross-process task adoption. Termination is guaranteed only for the managed process group, excluding daemon descendants that deliberately leave it.
+
+## Development
+
+```bash
+npm ci
+npm run check
+npm test
+```
+
+Tests use a local deterministic provider, real AgentSessions, real CLI/RPC and real child processes. No external model API is called. The suite performs several real 63-second handoffs and usually takes four to five minutes.
+
+RPC tests print a temporary artifact directory that keeps each process's `events-<pid>.jsonl`, `stderr-<pid>.log`, session and command logs.
+
+Local implementation notes are in `TICKETS.md`, the acceptance contract in `SPEC.md`, and research evidence in `INVESTIGATION.md`.
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,141 @@
+import { join } from "node:path";
+import { Type } from "typebox";
+import { createBashToolDefinition, createLocalBashOperations, getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { eventId, getManager, type TaskRecord } from "./src/tasks.ts";
+import { installTaskStatus, taskReferences } from "./src/status.ts";
+
+function details(value: unknown): { task_id?: string; task_event_id?: string } {
+  return value && typeof value === "object" ? value : {};
+}
+
+export default function asyncBash(pi: ExtensionAPI) {
+  const definition = createBashToolDefinition(process.cwd());
+  const manager = getManager(join(getAgentDir(), "extension-data", "async-bash"));
+  const taskSchema = Type.Object({
+    task_id: Type.String(), status: Type.String(), log_path: Type.String(),
+    exit_code: Type.Union([Type.Number(), Type.Null()]), wall_time_seconds: Type.Number(),
+  }, { additionalProperties: true });
+  pi.registerTool<typeof definition.parameters, unknown>({
+    ...definition,
+    renderResult: undefined,
+    description: definition.description + " After 63 seconds, returns a running task instead of waiting. Completion is notified automatically.",
+    outputSchema: Type.Union([definition.outputSchema!, taskSchema]),
+    execute(id, input, signal, update, ctx) {
+      const settings = pi.getSettings();
+      const operations = createLocalBashOperations({ shellPath: settings.shellPath });
+      let foreground = true;
+      return manager.execute({
+        owner: ctx.sessionManager.getSessionId(), cwd: ctx.cwd, timeout: input.timeout, signal,
+        run: (taskSignal, log, started) => createBashToolDefinition(ctx.cwd, {
+          shellPath: settings.shellPath, commandPrefix: settings.shellCommandPrefix,
+          operations: {
+            exec(command, cwd, options) {
+              started();
+              return operations.exec(command, cwd, {
+                ...options,
+                onData(data) { log(data); options.onData(data); },
+              });
+            },
+          },
+        }).execute(id, input, taskSignal, (value) => { if (foreground) update?.(value); }, ctx),
+      }).then((result) => {
+        const id = details(result.details).task_id;
+        // Nested codemode results are not transcript toolResults; persist the reference on the branch too.
+        if (id) pi.appendEntry("async-bash-task", { task_id: id });
+        return result;
+      }).finally(() => { foreground = false; });
+    },
+  });
+  pi.registerTool({
+    name: "bash_task",
+    label: "bash task",
+    description: "Inspect or kill a bash task. Completion is notified automatically.",
+    parameters: Type.Object({
+      task_id: Type.String({ description: "Task ID returned by bash" }),
+      action: Type.Union([Type.Literal("status"), Type.Literal("kill")]),
+    }),
+    outputSchema: taskSchema,
+    execute: (_id, args, signal) => manager.control(args.task_id, args.action, signal),
+  });
+  let unbind = () => {};
+  pi.on("session_start", (_event, ctx) => {
+    unbind();
+    const disposeStatus = installTaskStatus(pi, ctx, manager);
+    const owner = ctx.sessionManager.getSessionId();
+    let active = true;
+    const queued = new Set<string>();
+    const seen = new Set<string>();
+    const pending = new Map<string, TaskRecord>();
+    for (const entry of ctx.sessionManager.getEntries()) {
+      const data = entry.type === "custom_message" ? details(entry.details) :
+        entry.type === "message" && entry.message.role === "toolResult" ? details(entry.message.details) : {};
+      if (data.task_event_id) seen.add(data.task_event_id);
+    }
+    const flush = (atTurnBoundary = false) => {
+      if (!active || (!atTurnBoundary && !ctx.isIdle())) return;
+      for (const [id, record] of pending) {
+        if (seen.has(id) || queued.has(id)) { pending.delete(id); continue; }
+        try {
+          const result = manager.describe(record);
+          queued.add(id);
+          pi.sendMessage({
+            customType: "async-bash-completion", content: [
+              { type: "text", text: "Background bash task finished. Use the result below to continue any dependent work." },
+              ...result.content,
+            ],
+            display: true, details: result.details,
+          }, { triggerTurn: true, deliverAs: "followUp" });
+          pending.delete(id);
+        } catch {
+          queued.delete(id);
+          // The persisted terminal state remains available to context/status if delivery fails.
+        }
+      }
+    };
+    const unsubscribe = manager.subscribe((record: TaskRecord) => {
+      if (record.owner_session_id !== owner) return;
+      const id = eventId(record);
+      if (seen.has(id) || queued.has(id)) return;
+      pending.set(id, record);
+      setImmediate(() => flush());
+    });
+    const offMessage = pi.on("message_end", (event) => {
+      const message = event.message;
+      const data = message.role === "custom" || message.role === "toolResult" ? details(message.details) : {};
+      if (data.task_event_id) {
+        seen.add(data.task_event_id);
+        pending.delete(data.task_event_id);
+      }
+    });
+    // Task results must reach the transcript before deciding whether another turn is necessary.
+    const offTurn = pi.on("turn_end", () => flush(true));
+    const offSettled = pi.on("agent_before_settle", () => flush(true));
+    unbind = () => { active = false; disposeStatus(); unsubscribe(); offMessage(); offTurn(); offSettled(); };
+  });
+  pi.on("context", (event, ctx) => {
+    const references = taskReferences(ctx.sessionManager.getBranch());
+    const visible = new Set(event.messages.flatMap((m) => {
+      const id = m.role === "custom" || m.role === "toolResult" ? details(m.details).task_event_id : undefined;
+      return id ? [id] : [];
+    }));
+    const summaries: string[] = [];
+    let bytes = 0;
+    for (const task of manager.forSession(ctx.sessionManager.getSessionId(), references)) {
+      if (task.status !== "running" && visible.has(eventId(task))) continue;
+      const line = `Task ${task.task_id}: ${task.status}; exit_code=${task.exit_code}; log=${task.log_path}`;
+      const size = Buffer.byteLength(line) + 1;
+      if (bytes + size > 16384) break;
+      summaries.push(line);
+      bytes += size;
+    }
+    if (!summaries.length) return;
+    return { messages: [{
+      role: "custom" as const, customType: "async-bash-state",
+      content: summaries.join("\n"), display: false, timestamp: Date.now(),
+    }, ...event.messages] };
+  });
+  pi.on("session_shutdown", async (event) => {
+    unbind();
+    if (event.reason === "quit") await manager.shutdown();
+  });
+}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@runminton/pi-async-bash",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Automatically hand long-running pi bash commands to a managed background task and resume the session when it finishes.",
+  "type": "module",
+  "license": "MIT",
+  "author": "RunMintOn",
+  "homepage": "https://github.com/RunMintOn/pi-async-bash#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RunMintOn/pi-async-bash.git"
+  },
+  "bugs": {
+    "url": "https://github.com/RunMintOn/pi-async-bash/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "bash",
+    "async",
+    "background-task"
+  ],
+  "pi": {
+    "extensions": ["./index.ts"]
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test --test-concurrency=1 test/*.test.mjs",
+    "check": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.19",
+    "typescript": "^5.9.3"
+  }
+}

package/src/status.ts

@@ -0,0 +1,78 @@
+import type { ExtensionAPI, ExtensionContext, SessionEntry } from "@earendil-works/pi-coding-agent";
+import type { TaskManager, TaskRecord } from "./tasks.ts";
+
+export function taskReferences(entries: readonly SessionEntry[]): Set<string> {
+  const ids = new Set<string>();
+  for (const entry of entries) {
+    const value = entry.type === "custom" && entry.customType === "async-bash-task" ? entry.data :
+      entry.type === "message" && entry.message.role === "toolResult" ? entry.message.details : undefined;
+    const id = value && typeof value === "object" && "task_id" in value ? value.task_id : undefined;
+    if (typeof id === "string") ids.add(id);
+  }
+  return ids;
+}
+
+function duration(milliseconds: number): string {
+  const seconds = Math.max(0, Math.floor(milliseconds / 1000));
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ${String(seconds % 60).padStart(2, "0")}s`;
+  return `${Math.floor(minutes / 60)}h ${String(minutes % 60).padStart(2, "0")}m ${String(seconds % 60).padStart(2, "0")}s`;
+}
+
+function backgroundStatus(tasks: readonly TaskRecord[], now: number, width: number): string | undefined {
+  if (!tasks.length) return undefined;
+  const ages = [...tasks].sort((a, b) => a.started_at - b.started_at)
+    .map(task => duration(now - task.started_at));
+  const variants = [ages, ages.map(age => age.replaceAll(" ", ""))];
+  const prefix = `BG ${tasks.length}`;
+  for (let shown = ages.length; shown > 0; shown--) {
+    for (const durations of variants) {
+      const text = `${prefix} · ${durations.slice(0, shown).join(" / ")}${shown < ages.length ? ` / +${ages.length - shown}` : ""}`;
+      if (text.length <= width) return text;
+    }
+  }
+  const compact = `${prefix} · +${ages.length}`;
+  return compact.length <= width ? compact : prefix;
+}
+
+export function installTaskStatus(pi: ExtensionAPI, ctx: ExtensionContext, manager: TaskManager): () => void {
+  if (ctx.mode !== "tui" || !ctx.hasUI) return () => {};
+  const owner = ctx.sessionManager.getSessionId();
+  let tasks: TaskRecord[] = [];
+  let timer: ReturnType<typeof setInterval> | undefined;
+  let last: string | undefined;
+  const update = () => {
+    // Keep the omission count visible if the native footer truncates other statuses.
+    const text = backgroundStatus(tasks, Date.now(), Math.max(0, (process.stdout.columns ?? 80) - 3));
+    if (text !== last) {
+      ctx.ui.setStatus("async-bash", text);
+      last = text;
+    }
+    if (tasks.length && !timer) timer = setInterval(update, 1000).unref();
+    if (!tasks.length && timer) { clearInterval(timer); timer = undefined; }
+  };
+  const refresh = () => {
+    const references = taskReferences(ctx.sessionManager.getBranch());
+    // Rebuild at lifecycle boundaries; ticking ages needs no disk or log reads.
+    tasks = [...manager.forSession(owner, references)].filter(task => task.status === "running");
+    update();
+  };
+  const off = [
+    pi.on("tool_execution_end", event => { if (event.toolName === "bash") refresh(); }),
+    pi.on("session_tree", refresh),
+    pi.on("session_compact", refresh),
+    manager.subscribe(record => {
+      tasks = tasks.filter(task => task.task_id !== record.task_id);
+      update();
+    }),
+  ];
+  process.stdout.on("resize", update);
+  refresh();
+  return () => {
+    for (const unsubscribe of off) unsubscribe();
+    process.stdout.off("resize", update);
+    if (timer) clearInterval(timer);
+    ctx.ui.setStatus("async-bash", undefined);
+  };
+}

package/src/tasks.ts

@@ -0,0 +1,275 @@
+import { randomBytes, randomUUID } from "node:crypto";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, renameSync, statSync, writeFileSync, writeSync } from "node:fs";
+import { join } from "node:path";
+import { truncateTail } from "@earendil-works/pi-coding-agent";
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+
+type Result = AgentToolResult<unknown> & { structuredContent?: unknown; isError?: boolean };
+export type TaskStatus = "running" | "exited" | "killed" | "timed_out" | "failed" | "unknown";
+export interface TaskRecord {
+  task_id: string;
+  owner_session_id: string;
+  cwd: string;
+  status: TaskStatus;
+  log_path: string;
+  started_at: number;
+  finished_at?: number;
+  exit_code: number | null;
+  total_bytes: number;
+  total_lines: number | null;
+  error?: string;
+}
+interface LiveTask {
+  record: TaskRecord;
+  controller: AbortController;
+  handed: boolean;
+  stopRequested: boolean;
+  done: Promise<void>;
+}
+type Outcome = { result: Result } | { error: Error };
+const handoffMs = 63_000;
+const taskIdPattern = /^(?:[0-9a-f]{8}|[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})$/;
+
+export function eventId(task: TaskRecord) {
+  return `${task.task_id}:terminal`;
+}
+
+function abortable<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const abort = () => { cleanup(); reject(new Error("Task control aborted.")); };
+    const cleanup = () => signal?.removeEventListener("abort", abort);
+    if (signal?.aborted) return abort();
+    signal?.addEventListener("abort", abort, { once: true });
+    promise.then((value) => { cleanup(); resolve(value); }, (error) => { cleanup(); reject(error); });
+  });
+}
+
+export class TaskManager {
+  private readonly instance = randomUUID();
+  private readonly live = new Map<string, LiveTask>();
+  private readonly listeners = new Set<(record: TaskRecord) => void>();
+  private closing = false;
+
+  constructor(private readonly directory: string) {
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+  }
+
+  private save(record: TaskRecord) {
+    const path = join(this.directory, `${record.task_id}.json`);
+    const temporary = `${path}.${this.instance}.tmp`;
+    writeFileSync(temporary, JSON.stringify(record), { mode: 0o600 });
+    renameSync(temporary, path);
+  }
+
+  subscribe(listener: (record: TaskRecord) => void) {
+    this.listeners.add(listener);
+    return () => { this.listeners.delete(listener); };
+  }
+
+  async execute(options: {
+    owner: string;
+    cwd: string;
+    timeout?: number;
+    signal?: AbortSignal;
+    run: (signal: AbortSignal, log: (data: Buffer) => void, started: () => void) => Promise<Result>;
+  }): Promise<Result> {
+    if (this.closing) throw new Error("pi is shutting down.");
+    let id: string;
+    let fd: number;
+    while (true) {
+      id = randomBytes(4).toString("hex");
+      if (this.live.has(id) || existsSync(join(this.directory, `${id}.json`))) continue;
+      try {
+        // Exclusive creation also reserves the ID against other pi processes.
+        fd = openSync(join(this.directory, `${id}.log`), "wx", 0o600);
+        break;
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      }
+    }
+    const record: TaskRecord = {
+      task_id: id, owner_session_id: options.owner,
+      cwd: options.cwd, status: "running", log_path: join(this.directory, `${id}.log`),
+      started_at: Date.now(), exit_code: null, total_bytes: 0, total_lines: 0,
+    };
+    const controller = new AbortController();
+    let finish!: () => void;
+    const task: LiveTask = {
+      record, controller, handed: false, stopRequested: false,
+      done: new Promise<void>((resolve) => { finish = resolve; }),
+    };
+    this.live.set(id, task);
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let lastByte: number | undefined;
+    let newlines = 0;
+    let logError: Error | undefined;
+    let release!: () => void;
+    const threshold = new Promise<"handoff">((resolve) => { release = () => resolve("handoff"); });
+    const abort = () => controller.abort();
+    if (options.signal?.aborted) abort();
+    options.signal?.addEventListener("abort", abort, { once: true });
+    const started = () => {
+      record.started_at = Date.now();
+      // A shorter execution timeout must settle as a foreground timeout.
+      if (options.timeout === undefined || options.timeout * 1000 > handoffMs) timer = setTimeout(release, handoffMs);
+    };
+    const log = (data: Buffer) => {
+      if (logError) return;
+      try {
+        let offset = 0;
+        while (offset < data.length) offset += writeSync(fd, data, offset, data.length - offset);
+        record.total_bytes += data.length;
+        for (const byte of data) if (byte === 10) newlines++;
+        if (data.length) lastByte = data[data.length - 1];
+        record.total_lines = newlines + (lastByte !== undefined && lastByte !== 10 ? 1 : 0);
+      } catch (error) {
+        logError = error instanceof Error ? error : new Error(String(error));
+        controller.abort();
+      }
+    };
+    const settle = (outcome: Outcome): Outcome => {
+      if (timer) clearTimeout(timer);
+      record.finished_at = Date.now();
+      if ("result" in outcome) {
+        const data = outcome.result.structuredContent as { exit_code?: number } | undefined;
+        record.exit_code = data?.exit_code ?? null;
+        record.status = "exited";
+      } else {
+        record.error = truncateTail(logError?.message ?? outcome.error.message, { maxLines: 1, maxBytes: 1024 }).content;
+        record.status = logError ? "failed" : task.stopRequested ? "killed" :
+          /Command timed out after [\d.]+ seconds$/.test(outcome.error.message) ? "timed_out" : "failed";
+      }
+      try {
+        closeSync(fd);
+        if (task.handed) this.save(record);
+      } catch (error) {
+        outcome = { error: error instanceof Error ? error : new Error(String(error)) };
+        record.error = `Cannot save task result: ${outcome.error.message}`;
+        record.status = "failed";
+      } finally {
+        this.live.delete(id);
+        finish();
+      }
+      if (task.handed) {
+        for (const listener of this.listeners) listener({ ...record });
+      }
+      return outcome;
+    };
+    const execution = Promise.resolve()
+      .then(() => options.run(controller.signal, log, started))
+      .then((result) => settle({ result }), (error: unknown) =>
+        settle({ error: error instanceof Error ? error : new Error(String(error)) }));
+    try {
+      const outcome = await Promise.race([execution, threshold]);
+      if (outcome !== "handoff" || record.status !== "running" || controller.signal.aborted || this.closing) {
+        const completed = outcome === "handoff" ? await execution : outcome;
+        if ("error" in completed) throw completed.error;
+        return completed.result;
+      }
+      // Persist before dropping the turn's abort listener: the reference is recoverable even if the turn aborts now.
+      this.save(record);
+      task.handed = true;
+      return {
+        content: [{ type: "text", text:
+          `Still running after 63 seconds. Task: ${id}\nLog: ${record.log_path}\n` +
+          "You will be notified when it finishes. Do not poll. " +
+          "Continue work that does not depend on this result. If none remains, end your turn and resume when notified.\n" +
+          "The task stops when pi exits; any execution timeout still applies." }],
+        details: { ...record },
+        structuredContent: { ...record, wall_time_seconds: (Date.now() - record.started_at) / 1000 },
+      };
+    } catch (error) {
+      if (record.status === "running") {
+        task.stopRequested = true;
+        controller.abort();
+        await execution;
+      }
+      throw error;
+    } finally {
+      options.signal?.removeEventListener("abort", abort);
+      if (timer) clearTimeout(timer);
+    }
+  }
+
+  get(id: string): TaskRecord {
+    if (!taskIdPattern.test(id)) throw new Error("Invalid task_id.");
+    const active = this.live.get(id);
+    if (active?.handed) return { ...active.record };
+    const path = join(this.directory, `${id}.json`);
+    if (!existsSync(path)) throw new Error(`Unknown task: ${id}`);
+    const record = JSON.parse(readFileSync(path, "utf8")) as TaskRecord;
+    if (record.task_id !== id) throw new Error(`Invalid task record: ${id}`);
+    if (record.status === "running") {
+      // Another pi process may still own it. Never adopt or kill based on a persisted PID.
+      return { ...record, status: "unknown", total_lines: null, error: "Execution belongs to an unavailable pi runtime; exit result is unknown." };
+    }
+    return record;
+  }
+
+  async control(id: string, action: "status" | "kill", signal?: AbortSignal): Promise<Result> {
+    let record = this.get(id);
+    if (action === "kill" && record.status === "running") {
+      const task = this.live.get(id)!;
+      task.stopRequested = true;
+      task.controller.abort();
+      await abortable(task.done, signal);
+      record = this.get(id);
+    }
+    return this.describe(record, action !== "status");
+  }
+
+  describe(record: TaskRecord, reportFailure = false): Result {
+    const size = statSync(record.log_path).size;
+    const fd = openSync(record.log_path, "r");
+    let tail: string;
+    try {
+      const bytes = Buffer.alloc(Math.min(size, 16384 + 4));
+      readSync(fd, bytes, 0, bytes.length, Math.max(0, size - bytes.length));
+      let offset = 0;
+      while (offset < bytes.length && (bytes[offset] & 0xc0) === 0x80) offset++;
+      tail = truncateTail(bytes.subarray(offset).toString("utf8"), { maxLines: 100, maxBytes: 16384 }).content;
+    } finally { closeSync(fd); }
+    const data = { ...record, total_bytes: size, output: tail, wall_time_seconds:
+      ((record.finished_at ?? Date.now()) - record.started_at) / 1000 };
+    return {
+      content: [{ type: "text", text: `Task ${record.task_id}: ${record.status}; exit_code=${record.exit_code}; ` +
+        `${data.wall_time_seconds.toFixed(1)}s\nLog: ${record.log_path} (${record.total_lines ?? "unknown"} lines, ${size} bytes)\n${tail}` }],
+      details: { ...data, ...(record.status !== "running" ? { task_event_id: eventId(record) } : {}) },
+      structuredContent: data,
+      ...(reportFailure && (record.status !== "exited" || record.exit_code !== 0) ? { isError: true } : {}),
+    };
+  }
+
+  *forSession(owner: string, references: Set<string>): Generator<TaskRecord> {
+    const emitted = new Set<string>();
+    for (const task of this.live.values()) {
+      if (task.handed && (task.record.owner_session_id === owner || references.has(task.record.task_id))) {
+        emitted.add(task.record.task_id);
+        yield { ...task.record };
+      }
+    }
+    for (const file of readdirSync(this.directory)) {
+      if (!file.endsWith(".json") || !taskIdPattern.test(file.slice(0, -5))) continue;
+      const id = file.slice(0, -5);
+      if (emitted.has(id)) continue;
+      const record = this.get(id);
+      if (record.owner_session_id === owner || references.has(id)) yield record;
+    }
+  }
+
+  async shutdown() {
+    this.closing = true;
+    const tasks = [...this.live.values()];
+    for (const task of tasks) { task.stopRequested = true; task.controller.abort(); }
+    await Promise.all(tasks.map((task) => task.done));
+  }
+}
+
+const key = Symbol.for("pi-async-bash.managers.v1");
+export function getManager(directory: string): TaskManager {
+  const globals = globalThis as typeof globalThis & { [key]?: Map<string, TaskManager> };
+  const managers = globals[key] ??= new Map();
+  let manager = managers.get(directory);
+  if (!manager) { manager = new TaskManager(directory); managers.set(directory, manager); }
+  return manager;
+}