pi-tian-background-terminals 0.1.0 → 0.1.1

package/README.md

@@ -25,15 +25,16 @@ Parameters:
   whole process tree is terminated. There is no default runtime timeout.
 - `working_dir` — optional working directory; defaults to the current directory.
 - `title` — optional short `/ps` label; defaults to a bounded one-line command.
-- `yield_time_ms` — optional initial wait, default **10 seconds**, range
-  **250–30,000 ms**.
+- `yield-time_ms` — optional initial wait, default **10 seconds**. Integer values
+  are clamped to **250–30,000 ms** rather than rejected when out of range.
 
 Behavior:
 
 1. Resolve Bash using Pi's normal platform logic and preserve Pi's configured
    `shellPath` and `shellCommandPrefix` settings.
-2. Inject the same `PI_SESSION_ID`, `PI_SESSION_FILE`, `PI_PROVIDER`, `PI_MODEL`,
-   and `PI_REASONING_LEVEL` environment values as built-in Bash.
+2. Preserve Pi's managed `PATH` (`<agent-dir>/bin` is prepended unless already
+   present) and inject the same `PI_SESSION_ID`, `PI_SESSION_FILE`, `PI_PROVIDER`,
+   `PI_MODEL`, and `PI_REASONING_LEVEL` values as built-in Bash.
 3. Start the command with no interactive stdin and stream bounded progress in
    the normal Bash tool row.
 4. If it exits during `yield_time_ms`, return its final status and bounded
@@ -61,8 +62,8 @@ duplicate destructive side effects.
 While at least one terminal runs, a one-line widget renders above the editor.
 `/ps` opens a two-stage full-screen overlay:
 
-1. **List** — every tracked terminal; `↑/↓`/`j`/`k` select, `Enter` inspect,
-   `x` stop the selected running terminal, `Esc` close.
+1. **List** — every tracked terminal, newest first; `↑/↓`/`j`/`k` select,
+   `Enter` inspect, `x` stop the selected running terminal, `Esc` close.
 2. **Detail** — metadata, `t`-toggled stdout/stderr, live tailing, scrolling
    (`↑/↓`, `PgUp/PgDn`, `g`/`G`), and `x` to stop.
 
@@ -78,7 +79,8 @@ While at least one terminal runs, a one-line widget renders above the editor.
   retains a stable **256 KiB startup head** and rolling tail within a **2 MiB**
   cap. Omitted middle bytes are marked. Complete output spills from byte zero
   to an owner-only file (`0600` in a `0700` session directory), capped at
-  256 MiB per stream.
+  256 MiB per stream. A terminal's spill files are deleted when it is pruned
+  from the 32-entry history.
 - **Separate stdout and stderr.** Both streams are independently retained,
   spilled, inspected, and formatted.
 - **No interactive stdin.** Normal commands see EOF. The legacy WSL Bash
@@ -86,9 +88,10 @@ While at least one terminal runs, a one-line widget renders above the editor.
   immediately and cannot be used interactively.
 - **Process-tree termination.** POSIX children use their own process group;
   Windows uses `taskkill /T`. Shutdown and hard timeouts send SIGTERM and
-  escalate to SIGKILL after two seconds.
+  escalate to SIGKILL after two seconds. A synchronous process-exit tracker
+  also kills managed trees when a Pi crash bypasses normal extension cleanup.
 - **Session scoped.** `/new`, `/resume`, `/fork`, `/reload`, and quit terminate
-  every process tree and remove spill files.
+  every process tree and remove the remaining spill directory.
 
 The async core uses [Effect](https://effect.website) v4. Node
 `child_process` output remains callback-driven. See
@@ -105,8 +108,8 @@ Restart Pi or run `/reload` afterwards.
 
 ## Development
 
-This workspace uses Effect v4 and TypeScript 7 (`tsgo`), so it is checked in
-isolation:
+This workspace pins Effect `4.0.0-beta.101` and uses TypeScript 7 (`tsgo`), so
+it is checked in isolation:
 
 ```bash
 npm install -w pi-tian-background-terminals

package/docs/implementation-guide.md

@@ -12,8 +12,8 @@ Every model shell command goes through `bash`:
    timeout.
 2. Resolve Bash and Pi's shell settings.
 3. Spawn with no interactive stdin and capture stdout/stderr separately.
-4. Wait for a bounded initial yield period (default 10 seconds, accepted range
-   250–30,000 ms).
+4. Wait for a bounded initial yield period (default 10 seconds; integer inputs
+   are clamped to 250–30,000 ms).
 5. If the process settles during that wait, return its final state and output in
    the Bash result. A non-zero exit, kill, or timeout is a tool error.
 6. Otherwise return a terminal id and leave the process running.
@@ -46,7 +46,7 @@ It adds managed-execution controls:
 ```text
 working_dir    optional working directory
 title          optional /ps label
-yield_time_ms  optional initial wait, 250–30,000 ms
+yield_time_ms  optional initial wait; integers clamp to 250–30,000 ms
 ```
 
 The override supplies its own prompt snippet and guidelines because Pi does not
@@ -94,6 +94,9 @@ The tool preserves Pi's normal Bash behavior:
   normal fallback behavior.
 - `shellCommandPrefix` is prepended only to the script sent to Bash. The
   snapshot retains the exact model-supplied command.
+- The child `PATH` mirrors Pi's managed-shell behavior: `<agent-dir>/bin` is
+  prepended unless already present, keeping Pi-installed tools visible while
+  honoring `PI_CODING_AGENT_DIR`.
 - The tool reconstructs the same live session environment values:
   `PI_SESSION_ID`, `PI_SESSION_FILE`, `PI_PROVIDER`, `PI_MODEL`, and
   `PI_REASONING_LEVEL`. Inherited stale values are removed first.
@@ -110,6 +113,7 @@ index.ts                    Pi boundary, bash override, fallback, /ps
 src/domain.ts               Snapshot/status/error types
 src/manager.ts              Effect service and process lifecycle
 src/output.ts               Bounded head+tail stream retention
+src/process-tracker.ts      Synchronous abnormal-exit process-tree safety net
 src/prompt.ts               Tool metadata and model-facing formatting
 src/result-delivery.ts      Drain-once completion delivery map
 src/runtime.ts              ManagedRuntime and Effect→Promise boundary
@@ -153,7 +157,9 @@ A snapshot includes:
 `index.ts` first performs side-effect-free validation. It preserves the exact
 script text and trims only to reject an empty command and derive a title.
 Filesystem stat errors and non-directory paths are reported before manager
-resolution.
+resolution. The public schema accepts any integer `yield_time_ms`; the manager
+clamps it so an overconfident scheduling guess cannot reject the entire tool
+call.
 
 Manager execution has two calls:
 
@@ -247,7 +253,9 @@ The settle hook receives `(snapshot, consumed)`:
 
 The map is keyed by terminal id. `drain()` clears entries before delivery, so a
 result can be sent only once. A failed `pi.sendMessage` call re-defers the same
-id for a later `agent_settled` retry.
+id for a later `agent_settled` retry. Interactive mode does not write that
+failure through `console.error`, which would corrupt the active TUI frame;
+non-TUI modes retain the diagnostic.
 
 Delivery uses:
 
@@ -331,7 +339,10 @@ chunk; subsequent child output is flow-controlled by Node.
 
 Settlement waits for spill streams to flush before publishing the final
 snapshot. The flush wait is bounded so a broken filesystem cannot leave a
-terminal permanently running.
+terminal permanently running. When the 32-entry registry prunes a settled
+terminal, its scope closes first and both owned spill files are then unlinked.
+Still-tracked snapshots therefore keep valid full-log paths while session disk
+usage remains bounded by retained history rather than command count.
 
 ## 13. Process lifecycle and termination
 
@@ -356,6 +367,13 @@ reaps the process group.
 The entry scope is the single cleanup path for `/ps` stop, hard timeout,
 pruning, internal kill calls, and runtime disposal.
 
+Pi's detached-child tracker is internal and not exported. The manager therefore
+registers its own synchronous Node `exit` listener while live, tracks every
+spawned pid until close/scope cleanup, and sends a best-effort process-tree
+SIGKILL (`taskkill /F /T` on Windows) if an uncaught crash or emergency terminal
+exit bypasses `session_shutdown`. Runtime disposal removes the listener and
+sweeps any residual pid after normal bounded teardown.
+
 ## 14. Capacity and pruning
 
 At most eight terminals may run concurrently. Start reserves a slot
@@ -363,9 +381,10 @@ synchronously before spawning, so parallel tool calls cannot race through the
 cap. Reaching the cap is an explicit error; it does not bypass management via
 the foreground fallback.
 
-The registry retains at most 32 live/settled entries for `/ps`. When over the
-limit, it removes the oldest settled entries; running entries are never pruned.
-Small tombstones retain final kill-report facts across pruning races.
+The registry retains at most 32 live/settled entries for `/ps` and exposes them
+newest first. When over the limit, it removes the oldest settled entries and
+their spill files; running entries are never pruned. Small tombstones retain
+final kill-report facts across pruning races.
 
 ## 15. `/ps` UI
 
@@ -396,7 +415,9 @@ The manager finalizer runs `disposeAll`, which:
 5. waits for detached cleanup fibers within the shutdown bound;
 6. removes the private spill directory.
 
-The `disposed` check after process setup closes a child that raced with a
+After `disposeAll`, the manager scope releases the abnormal-exit tracker,
+removes its process listener, and synchronously kills any residual pid. The
+`disposed` check after process setup closes a child that raced with a
 teardown sweep, preventing an unregistered survivor.
 
 ## 17. Required tests
@@ -408,16 +429,17 @@ The package test suite covers:
 - yielded completion with exactly one automatic delivery;
 - safe pre-spawn foreground fallback;
 - non-zero commands executing only once, without fallback retry;
-- Pi session environment and command-prefix preservation;
+- Pi managed-bin `PATH`, session environment, and command-prefix preservation;
+- out-of-range integer yield waits reaching the manager clamp;
 - bounded streaming updates during the initial wait;
 - hard timeout status and tree termination;
 - Bash-specific syntax on the resolved shell;
 - abort leaving eventual completion deliverable;
-- process-tree kill and SIGKILL escalation;
-- session disposal and spill-directory cleanup;
+- process-tree kill, SIGKILL escalation, and abnormal process-exit cleanup;
+- session disposal, spill-directory cleanup, and per-entry pruning cleanup;
 - output head stability, rolling tail, UTF-8 boundaries, and omission counts;
 - complete spill capture beyond the memory cap;
-- drain-once result delivery;
+- drain-once result delivery without direct TUI stderr writes on retry;
 - `/ps` selection, sanitization, wrapping, and cache behavior.
 
 Validation commands:
@@ -428,3 +450,7 @@ npm test --workspace pi-tian-background-terminals
 npm run typecheck
 npm pack --dry-run --workspace pi-tian-background-terminals
 ```
+
+The publish workflow runs both typechecks and the package test suite before its
+publish loop. The prerelease Effect runtime is pinned exactly to the beta used
+by those checks so a consumer install cannot float to an unverified beta.

package/index.ts

@@ -25,6 +25,7 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import {
   createBashToolDefinition,
+  getAgentDir,
   getMarkdownTheme,
   SettingsManager,
 } from "@earendil-works/pi-coding-agent";
@@ -34,8 +35,6 @@ import { SpawnError, type TerminalSnapshot } from "./src/domain.ts";
 import {
   DEFAULT_YIELD_TIME_MS,
   MAX_RUNTIME_TIMEOUT_SECONDS,
-  MAX_YIELD_TIME_MS,
-  MIN_YIELD_TIME_MS,
   TerminalManager,
   type TerminalManagerShape,
 } from "./src/manager.ts";
@@ -68,6 +67,27 @@ const SESSION_ENV_KEYS = [
   "PI_REASONING_LEVEL",
 ] as const;
 
+function getPiShellEnv(): NodeJS.ProcessEnv {
+  // Mirrors Pi's internal getShellEnv(), which is not exported from the
+  // package root. Keep Pi-managed tools such as fd and rg visible to Bash.
+  const binDir = path.join(getAgentDir(), "bin");
+  const pathKey =
+    Object.keys(process.env).find((key) => key.toLowerCase() === "path") ??
+    "PATH";
+  const currentPath = process.env[pathKey] ?? "";
+  const hasBinDir = currentPath
+    .split(path.delimiter)
+    .filter(Boolean)
+    .includes(binDir);
+
+  return {
+    ...process.env,
+    [pathKey]: hasBinDir
+      ? currentPath
+      : [binDir, currentPath].filter(Boolean).join(path.delimiter),
+  };
+}
+
 export interface BackgroundTerminalsDependencies {
   readonly createRuntime?: typeof createTerminalRuntime;
   readonly createForegroundBash?: typeof createBashToolDefinition;
@@ -180,7 +200,9 @@ export function createBackgroundTerminalsExtension(
     } catch (error) {
       // Session may be shutting down, but retain the snapshot so any later
       // agent-settled flush can retry instead of silently dropping it.
-      console.error("background-terminals: failed to deliver result", error);
+      if (sessionContext?.mode !== "tui") {
+        console.error("background-terminals: failed to deliver result", error);
+      }
       return false;
     }
   };
@@ -273,8 +295,6 @@ export function createBackgroundTerminalsExtension(
       ),
       yield_time_ms: Type.Optional(
         Type.Integer({
-          minimum: MIN_YIELD_TIME_MS,
-          maximum: MAX_YIELD_TIME_MS,
           description: BASH_PARAMETER_DESCRIPTIONS.yieldTimeMs,
         }),
       ),
@@ -366,7 +386,7 @@ export function createBackgroundTerminalsExtension(
         return await runForegroundFallback(managerError, true);
       }
 
-      const env = { ...process.env };
+      const env = getPiShellEnv();
       for (const key of SESSION_ENV_KEYS) delete env[key];
       env.PI_SESSION_ID = ctx.sessionManager.getSessionId();
       const sessionFile = ctx.sessionManager.getSessionFile();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-tian-background-terminals",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Replace Pi's built-in Bash with automatic background yielding, exactly-once completion notifications, and a /ps viewer.",
   "type": "module",
   "keywords": [
@@ -40,7 +40,7 @@
     "test": "node --test --experimental-strip-types index.test.ts manager.test.ts output.test.ts prompt.test.ts result-delivery.test.ts ps.test.ts"
   },
   "dependencies": {
-    "effect": "^4.0.0-beta.99"
+    "effect": "4.0.0-beta.101"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",

package/src/manager.ts

@@ -35,6 +35,7 @@ import {
   type TerminalStatus,
 } from "./domain.ts";
 import { OutputBuffer } from "./output.ts";
+import { createDetachedChildTracker } from "./process-tracker.ts";
 
 export const MAX_RUNNING = 8;
 export const MAX_TRACKED = 32;
@@ -92,6 +93,8 @@ interface Entry {
   stdoutBuf: OutputBuffer;
   stderrBuf: OutputBuffer;
   spillStreams: fs.WriteStream[];
+  /** Immutable file ownership retained even if a spill becomes unavailable. */
+  spillPaths: string[];
   /** Set in the same synchronous effect that sends SIGTERM so a natural exit
    * before signaling keeps its truthful status. */
   killSignaled: boolean;
@@ -155,6 +158,7 @@ export interface KillResult {
 
 /** Synchronous bridge for the TUI. Snapshots are live objects; do not mutate. */
 export interface TerminalReadModel {
+  /** Tracked terminals ordered by creation time, newest first. */
   list(): ReadonlyArray<TerminalSnapshot>;
   get(id: string): TerminalSnapshot | undefined;
   size(): number;
@@ -187,6 +191,7 @@ export interface TerminalManagerShape {
   status(id: string): Effect.Effect<TerminalSnapshot, UnknownTerminalError>;
   /** Kill running terminals; resolves only after they have settled. */
   kill(ids: ReadonlyArray<string>): Effect.Effect<ReadonlyArray<KillResult>>;
+  /** Tracked terminals ordered by creation time, newest first. */
   readonly list: Effect.Effect<ReadonlyArray<TerminalSnapshot>>;
   readonly disposeAll: Effect.Effect<void>;
   readonly view: TerminalReadModel;
@@ -314,6 +319,10 @@ const makeManager = Effect.gen(function* () {
   // close interrupts any work that outlives the bounded disposeAll wait.
   const cleanupFibers = yield* FiberSet.make();
   const runCleanup = yield* FiberSet.runtime(cleanupFibers)();
+  const detachedChildren = yield* Effect.acquireRelease(
+    Effect.sync(createDetachedChildTracker),
+    (tracker) => Effect.sync(() => tracker.dispose()),
+  );
 
   const entries = new Map<string, Entry>();
   /** Small immutable tombstones preserve truthful kill reports if pruning
@@ -371,6 +380,19 @@ const makeManager = Effect.gen(function* () {
   const closeEntryScope = (entry: Entry) =>
     Scope.close(entry.scope, Exit.void).pipe(Effect.ignore);
 
+  const removeEntrySpills = (entry: Entry) =>
+    Effect.sync(() => {
+      for (const spillPath of entry.spillPaths) {
+        try {
+          fs.rmSync(spillPath, { force: true });
+        } catch {
+          // Best effort: disposeAll still removes the complete session dir.
+        }
+      }
+      entry.stdoutBuf.spillPath = undefined;
+      entry.stderrBuf.spillPath = undefined;
+    });
+
   const pruneSettled = () => {
     if (entries.size <= MAX_TRACKED) return;
     const candidates = [...entries.values()]
@@ -386,7 +408,9 @@ const makeManager = Effect.gen(function* () {
     for (const entry of candidates) {
       if (entries.size <= MAX_TRACKED) break;
       entries.delete(entry.snapshot.id);
-      runCleanup(closeEntryScope(entry));
+      runCleanup(
+        closeEntryScope(entry).pipe(Effect.andThen(removeEntrySpills(entry))),
+      );
     }
   };
 
@@ -640,6 +664,9 @@ const makeManager = Effect.gen(function* () {
             }),
         });
 
+        const childPid = child.pid;
+        if (childPid) detachedChildren.track(childPid);
+
         const id = `bt-${++counter}`;
         const entryRef = () => entries.get(id);
         const stdoutSpill = makeSpill(entryRef, id, "stdout", () =>
@@ -689,6 +716,9 @@ const makeManager = Effect.gen(function* () {
           spillStreams: [stdoutSpill?.file, stderrSpill?.file].filter(
             (file): file is fs.WriteStream => file !== undefined,
           ),
+          spillPaths: [stdoutSpill?.spillPath, stderrSpill?.spillPath].filter(
+            (spillPath): spillPath is string => spillPath !== undefined,
+          ),
           killSignaled: false,
           processErrored: false,
           exited: false,
@@ -733,6 +763,7 @@ const makeManager = Effect.gen(function* () {
           scheduleExitCleanup(entry);
         });
         child.once("close", (code, signal) => {
+          if (childPid) detachedChildren.untrack(childPid);
           entry.exited = true;
           entry.stdioClosed = true;
           // Only trust close's code/signal when 'exit' never fired (a spawn
@@ -783,6 +814,7 @@ const makeManager = Effect.gen(function* () {
                 yield* flushSpillStreams(entry);
                 settle(entry);
               }
+              if (childPid) detachedChildren.untrack(childPid);
             }),
           ),
           scope,
@@ -1017,8 +1049,11 @@ const makeManager = Effect.gen(function* () {
     yield* Effect.sync(() => notify());
   });
 
+  const listNewestFirst = () =>
+    Array.from(entries.values(), (entry) => entry.snapshot).reverse();
+
   const view: TerminalReadModel = {
-    list: () => [...entries.values()].map((entry) => entry.snapshot),
+    list: listNewestFirst,
     get: (id) => entries.get(id)?.snapshot,
     size: () => entries.size,
     subscribe: (listener) => {
@@ -1058,7 +1093,7 @@ const makeManager = Effect.gen(function* () {
     waitForSettlement,
     status,
     kill,
-    list: Effect.sync(() => [...entries.values()].map((e) => e.snapshot)),
+    list: Effect.sync(listNewestFirst),
     disposeAll,
     view,
   });

package/src/process-tracker.ts

@@ -0,0 +1,75 @@
+import { spawnSync } from "node:child_process";
+
+/**
+ * Synchronously kill a process tree during Node's `exit` event, where async
+ * cleanup cannot run. This mirrors Pi's internal detached-child safety net,
+ * which is not exported from the package root.
+ */
+function killProcessTreeSync(pid: number) {
+  if (process.platform === "win32") {
+    try {
+      spawnSync("taskkill", ["/F", "/T", "/PID", String(pid)], {
+        stdio: "ignore",
+        timeout: 5_000,
+        windowsHide: true,
+      });
+    } catch {
+      // Process may already be gone or taskkill may be unavailable.
+    }
+    return;
+  }
+
+  try {
+    process.kill(-pid, "SIGKILL");
+    return;
+  } catch {
+    // The process group may already be gone; try the leader as a fallback.
+  }
+  try {
+    process.kill(pid, "SIGKILL");
+  } catch {
+    // Process already exited.
+  }
+}
+
+export interface DetachedChildTracker {
+  track(pid: number): void;
+  untrack(pid: number): void;
+  /** Remove the process listener and synchronously kill any residual trees. */
+  dispose(): void;
+}
+
+/**
+ * Track process groups that must not survive a Pi crash or emergency exit.
+ * Graceful session teardown remains the primary cleanup path; this process
+ * listener is the last-resort path for exits that skip `session_shutdown`.
+ */
+export function createDetachedChildTracker(): DetachedChildTracker {
+  const pids = new Set<number>();
+  let disposed = false;
+
+  const sweep = () => {
+    const pending = [...pids];
+    pids.clear();
+    for (const pid of pending) killProcessTreeSync(pid);
+  };
+
+  process.on("exit", sweep);
+
+  return {
+    track(pid) {
+      if (!disposed && Number.isSafeInteger(pid) && pid > 0) pids.add(pid);
+    },
+    untrack(pid) {
+      pids.delete(pid);
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      process.off("exit", sweep);
+      // Scope teardown should already have terminated every tree. Sweep any
+      // residual pid synchronously in case bounded graceful cleanup failed.
+      sweep();
+    },
+  };
+}

package/src/prompt.ts

@@ -55,7 +55,7 @@ export const BASH_PARAMETER_DESCRIPTIONS = {
     "Optional short name shown in /ps. Defaults to a bounded one-line form of the command.",
   workingDir: "Working directory relative to the current directory, or an absolute path (default: current working directory)",
   yieldTimeMs:
-    `How long to wait for completion before returning a background terminal id (default ${DEFAULT_YIELD_TIME_MS} ms, range ${MIN_YIELD_TIME_MS}-${MAX_YIELD_TIME_MS} ms).`,
+    `How long to wait for completion before returning a background terminal id (default ${DEFAULT_YIELD_TIME_MS} ms; values are clamped to ${MIN_YIELD_TIME_MS}-${MAX_YIELD_TIME_MS} ms).`,
   timeout:
     `Optional hard total runtime timeout in seconds (no default, maximum ${MAX_RUNTIME_TIMEOUT_SECONDS}). Unlike yield_time_ms, this terminates the process tree.`,
 };