pi-simple-background-tasks 0.2.0 → 0.3.0

package/FORK-CHANGES.md

@@ -12,11 +12,12 @@ This package is a **KISS fork** of
 
 ## Divergence summary
 
-Relative to the 2.6.9 source, the fork changes **63 files (31,260 lines removed, 3,704 added)**, ending with **13 source files**:
+Relative to the 2.6.9 source, the fork changes **69 files (34,235 lines removed, 5,275 added)**, ending with **14 source files** plus a 3-file `node:test` platform suite:
 
 | Subsystem (as in 2.6.9) | Fork |
 | --- | --- |
-| Background-task core: `registry`, `common`, `extension-api`, `durable-fs`, `task-durable`, `shell-policy`, `windows-taskkill`, `reload-shell-owner`, `ui/background-tasks-manager` | **Kept, simplified** |
+| Background-task core: `registry`, `common`, `extension-api`, `durable-fs`, `task-durable`, `shell-policy`, `windows-taskkill`, `ui/background-tasks-manager` | **Kept, simplified** |
+| `reload-shell-owner` (lease/nonce handoff protocol for reload survival) | **Removed** — replaced by the detached-spawn design below |
 | Fusion workflows (`src/core/fusion/*` + `fusion-extension.ts` + `fusion-child-extension.ts` + `ui/fusion-model-selector.ts`) | **Removed** (~15k lines) |
 | Delegate (`src/core/delegate/*` + `delegate-extension.ts` + `delegate-child-extension.ts`) | **Removed** (~5k lines) |
 | Claude/Anthropic impersonation (`anthropic-attribution*.ts`) | **Removed** (~3.7k lines) |
@@ -31,9 +32,15 @@ Relative to the 2.6.9 source, the fork changes **63 files (31,260 lines removed,
 
 ## What the fork adds / changes
 
+- **Single detached task path, survival without flags** — every task spawns fully detached: on POSIX in its own process group (no pipes, no in-process ownership); on Windows as an outer process created **by the WMI service** (`Win32_Process.Create`), because direct children of the Pi process — no matter how detached — die together with it through job/console-session teardown (reproduced on a real Windows 11 VM with `taskkill /F` on the Pi process; WMI-created processes survive it). Ownership facts (pid, pgid, wrapper-written `<id>.exit` marker) live in the on-disk metadata and the extension holds no output file descriptors: the spawned command itself redirects output and the wrapper records the exit code. Each activation adopts still-running records from disk; a same-process `/reload` or a full Pi restart never kills a running task, and a Pi session shutdown kills it deliberately. Upstream's `reload-shell-owner` lease/handoff protocol (`--survive-reload`) was removed along with its ~1.5k lines: there is exactly one launch path and nothing to negotiate per task.
+
+- **One Windows kill: `taskkill /T /F`** — the old two-phase ladder (graceful `taskkill /T` window-close termination, then `/F` escalation after a grace timer) is gone: console applications do not honor window-close termination, so the graceful phase could neither stop anything on Windows nor leave time to escalate during a session shutdown (the Pi process would exit first and the un-ref'd escalation timer would die with it). One forced tree kill, outcome checked once. Cap/timeout notices are appended after the tree is terminated because the child's own `1>` redirection holds the output file locked until then.
+
+- **Platform test suite** (`npm test`) — `tests/registry.test.ts` runs the registry against real processes on the platform it is executed on, with the node:test runner through tsx (no new dependencies): completion/exit markers, quoting, timeout and cap kills, detachment across a genuine parent exit, adoption of a dead activation's records, kill of adopted tasks with notification, and no-adoption of terminal records. The two launch races it found — reaping a task while its WMI spawn is still in flight, and flood bytes overwriting cap/timeout notices — had product fixes (see the git history). All tests pass on Linux (8 run, 1 windows-only skip) and on a real Windows 11 VM (8 run, 1 posix-only skip).
+
 - **`/clean` command + `bg_clean` tool** — delete finished tasks (`session` / `all` / `<id>`). New file `src/core/task-cleanup.ts`; empty run directories are removed after cleanup (tasks live under `~/.pi/agent/tasks`).
 - **Task runtime moved to `~/.pi/agent/tasks`** with the PI extension-config pattern (`pi-background-tasks.json`, `tasksDir`).
-- **KISS packaging** — single entry point `src/extension.ts`, no `dist/`, no tests, no docs tree; fork identity in `package.json`.
+- **KISS packaging** — single entry point `src/extension.ts`, no `dist/`, no docs tree; one `node:test` platform suite under `tests/` (`npm test`, not shipped to npm); fork identity in `package.json`.
 - **Task manager UI** — opens top-right as a fixed 96-column modal (96 % width left the box stuck left on wide terminals); `d` deletes the selected task; both shortcuts registered (Shift↓ / Ctrl+Alt+B); footer options contextual to the selected task; empty-state footer shows only sensible actions; task detail adapts to terminal height (modal title dropped); **f** toggles fullscreen (gated on terminal size), **w** toggles output wrap.
 - **`--agent` flag** removed from `/bg` (stale).
 - **Lazy module loader simplified.**

package/README.md

@@ -7,19 +7,22 @@ A KISS fork of [pi-background-tasks](https://github.com/ismailsaleekh/pi-backgro
 ## Features
 
 - **Run long jobs without blocking**: start a named shell command in the background, keep talking to Pi, and get a completion notification in chat when it finishes.
-- **Durable tasks**: task state is persisted under `~/.pi/agent/tasks`, so it survives session restarts.
+- **Durable tasks**: task state is persisted under `~/.pi/agent/tasks`, and every task spawns detached, so a same-process `/reload` or a full Pi restart never kills a running task — the next activation adopts it from disk.
+- **Deliberate lifecycle**: a Pi session shutdown kills running tasks by design; `/reload`, crashes and restarts never do.
 - **Task manager overlay**: a TUI panel lists running and recent tasks with status and bounded output (default **Shift↓**); **f** toggles fullscreen, **w** wraps long output lines.
-- **Survive Pi reloads**: opt in to keeping a shell task alive across a same-process `/reload`.
-- **Cross-platform**: POSIX shell and Windows (process-group kill).
+- **Cross-platform**: POSIX (own process group, `-pgid` kill authority) and Windows (detached via a WMI-created outer process, `taskkill /T /F` tree ownership, `cmd`-runner exit markers).
 
 ## Install
 
 ```bash
-# Global install from the git main branch
-pi install git:github.com/jlsalvador/pi-simple-background-tasks@main
+# Default install (npm)
+pi install npm:pi-simple-background-tasks
+
+# Project-local install (npm)
+pi install -l npm:pi-simple-background-tasks
 
-# Project-local install from git
-pi install git:github.com/jlsalvador/pi-simple-background-tasks@main -l
+# Or from the git main branch
+pi install git:github.com/jlsalvador/pi-simple-background-tasks@main
 ```
 
 ## Quick start
@@ -30,7 +33,7 @@ pi install git:github.com/jlsalvador/pi-simple-background-tasks@main -l
    /bg --name "Typecheck watch" npm run typecheck -- --watch
    ```
 
-   `/bg` starts a tracked shell task and returns the task id plus output path. User-launched `/bg` tasks notify in the UI but do not automatically wake a follow-up model turn. Add one leading `--survive-reload` only when the shell process must keep running across a same-process `/reload`.
+   `/bg` starts a tracked shell command and returns the task id plus output path. User-launched `/bg` tasks notify in the UI but do not automatically wake a follow-up model turn. Tasks survive `/reload` and Pi restarts unconditionally; quitting the agent kills them.
 
 2. List tasks or open the task manager:
 
@@ -58,7 +61,7 @@ pi install git:github.com/jlsalvador/pi-simple-background-tasks@main -l
 
 | Command | Purpose |
 | --- | --- |
-| `/bg [--survive-reload] [--name "name"] <command>` | Start a tracked shell command. |
+| `/bg [--name "name"] <command>` | Start a tracked shell command. |
 | `/jobs` | List running and recent tasks. |
 | `/tasks [id]` | Open the task manager overlay. |
 | `/logs <id> [maxBytes]` | Show bounded output from a task. |
@@ -94,8 +97,15 @@ Example:
 npm install
 npm run check   # tsc --noEmit && biome check .
 npm run fix     # biome check --write .
+npm test        # registry platform suite (tests/), run per-platform
 ```
 
+`npm test` verifies the detached-task promises (survival across a real parent
+exit, adoption, kills) with `node:test` against processes it genuinely spawns.
+Run it on the platform whose behavior you want to verify: on POSIX it exercises
+process groups and the group kill; on Windows it exercises WMI-created tasks,
+the cmd runner and `taskkill /T /F`. Only the platform-specific pieces skip.
+
 ## License
 
 ISC — see [LICENSE](LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-simple-background-tasks",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Durable background shell tasks for Pi. KISS fork of pi-background-tasks.",
   "type": "module",
   "license": "ISC",
@@ -32,7 +32,8 @@
   ],
   "scripts": {
     "check": "tsc --noEmit && biome check .",
-    "fix": "biome check --write ."
+    "fix": "biome check --write .",
+    "test": "tsx --test \"tests/*.test.ts\""
   },
   "pi": {
     "extensions": [

package/src/core/common.ts

@@ -1,8 +1,7 @@
-import { accessSync, constants, statSync, type WriteStream } from 'node:fs';
+import { accessSync, constants, statSync } from 'node:fs';
 import { open } from 'node:fs/promises';
 import { basename, delimiter, extname, isAbsolute, join, resolve, win32 } from 'node:path';
 import { DEFAULT_MAX_BYTES } from '@earendil-works/pi-coding-agent';
-import type { BackgroundTaskChildProcess } from './registry.js';
 
 export const TASK_STATUS_VALUES = ['running', 'completed', 'failed', 'killed'] as const;
 export const TERMINAL_TASK_STATUS_VALUES = ['completed', 'failed', 'killed'] as const;
@@ -10,7 +9,6 @@ export const TERMINAL_TASK_STATUS_VALUES = ['completed', 'failed', 'killed'] as
 export type TaskStatus = (typeof TASK_STATUS_VALUES)[number];
 export type TerminalTaskStatus = (typeof TERMINAL_TASK_STATUS_VALUES)[number];
 export type KillKind = 'user' | 'timeout' | 'output_cap' | 'shutdown';
-export type ReloadShellStopKind = KillKind | 'handoff_expired';
 
 export type TerminalPublicationState = 'pending' | 'delivered' | 'abandoned';
 export type TerminalPublicationAbandonReason =
@@ -18,178 +16,7 @@ export type TerminalPublicationAbandonReason =
   | 'publisher_closed'
   | 'gate_rejected'
   | 'retry_exhausted'
-  | 'retention_limit'
-  | 'reload_handoff_expired';
-
-export type ReloadSurvivalErrorCode =
-  | 'pi_bg_survive_reload_invalid'
-  | 'pi_bg_survive_reload_requires_non_agent'
-  | 'pi_bg_survive_reload_unsupported_task_kind'
-  | 'pi_bg_reload_owner_unavailable'
-  | 'pi_bg_reload_owner_protocol_incompatible'
-  | 'pi_bg_reload_owner_activation_conflict'
-  | 'pi_bg_reload_owner_stale_claim'
-  | 'pi_bg_reload_handoff_expired';
-
-export class ReloadSurvivalError extends Error {
-  constructor(
-    readonly code: ReloadSurvivalErrorCode,
-    message: string,
-  ) {
-    super(`${code}: ${message}`);
-    this.name = 'ReloadSurvivalError';
-  }
-}
-
-export interface ReloadSurvivalSnapshotV1 {
-  schemaVersion: 'pi-background-tasks.reload-shell.v1';
-  authority: 'same-process-live-owner';
-  hostPid: number;
-  sessionId: string;
-  cwdRealpath: string;
-  launchNonce: string;
-  completionId: string;
-  spawnedAt: number;
-  childPid: number;
-  timeoutDeadlineAt?: number | undefined;
-  outputCapBytes: number;
-  posixProcessGroupId?: number | undefined;
-  windowsTreeRootPid?: number | undefined;
-  leaseGeneration: number;
-  handoffCount: number;
-}
-
-export interface ReloadShellIdentityV1 {
-  readonly hostPid: number;
-  readonly sessionId: string;
-  readonly cwdRealpath: string;
-}
-
-export interface ReloadShellActivationLeaseV1 {
-  readonly protocol: 'pi-background-tasks.reload-shell-owner.v1';
-  readonly hubNonce: string;
-  readonly identityKey: string;
-  readonly generation: number;
-  readonly activationNonce: string;
-}
-
-export interface ReloadShellActivationClaimV1 {
-  readonly protocol: 'pi-background-tasks.reload-shell-owner.v1';
-  readonly hubNonce: string;
-  readonly claimNonce: string;
-  readonly identity: ReloadShellIdentityV1;
-  readonly identityKey: string;
-  readonly generation: number;
-  readonly activationNonce: string;
-  readonly expiresAt?: number | undefined;
-  readonly executions: readonly ReloadableShellExecutionV1[];
-}
-
-export interface ReloadShellProcessV1 {
-  readonly pid?: number | undefined;
-  stdout?:
-    | {
-        on(event: 'data', listener: (data: Buffer | string) => void): unknown;
-        off?(event: 'data', listener: (data: Buffer | string) => void): unknown;
-      }
-    | null
-    | undefined;
-  stderr?:
-    | {
-        on(event: 'data', listener: (data: Buffer | string) => void): unknown;
-        off?(event: 'data', listener: (data: Buffer | string) => void): unknown;
-      }
-    | null
-    | undefined;
-  kill(signal?: NodeJS.Signals): boolean;
-  on(event: 'error', listener: (error: Error) => void): unknown;
-  on(
-    event: 'close',
-    listener: (code: number | null, signal: NodeJS.Signals | null) => void,
-  ): unknown;
-  off?(event: 'error', listener: (error: Error) => void): unknown;
-  off?(
-    event: 'close',
-    listener: (code: number | null, signal: NodeJS.Signals | null) => void,
-  ): unknown;
-}
-
-export interface ReloadShellOwnerEventSinkV1 {
-  readonly onChanged: (execution: ReloadableShellExecutionV1) => void;
-  readonly onTerminal: (execution: ReloadableShellExecutionV1) => void;
-}
-
-export type ReloadShellNotificationState = 'disabled' | 'pending' | 'sending' | 'delivered';
-
-export interface ReloadableShellExecutionV1 {
-  readonly protocol: 'pi-background-tasks.reload-shell-owner.v1';
-  readonly launchNonce: string;
-  readonly completionId: string;
-  readonly task: BgTask;
-  child: ReloadShellProcessV1 | undefined;
-  outputStream: WriteStream | undefined;
-  readonly spawnedAt: number;
-  readonly timeoutDeadlineAt?: number | undefined;
-  readonly outputCapBytes: number;
-  readonly terminal: Promise<BgTask>;
-  readonly requestStop: (kind: ReloadShellStopKind, reason?: string) => Promise<BgTask>;
-  phase: 'starting' | 'running' | 'stop_requested' | 'finalizing' | 'terminal' | 'released';
-  closeObservation?:
-    | {
-        code: number | null;
-        signal: NodeJS.Signals | null;
-        observedAt: number;
-      }
-    | undefined;
-  admissionCommitted: boolean;
-  notificationState: ReloadShellNotificationState;
-  readonly commitInitialMetadata: (signal?: AbortSignal) => Promise<void>;
-  readonly failAdmission: (error: Error) => void;
-  readonly setOwnerEventSink: (sink: ReloadShellOwnerEventSinkV1 | undefined) => void;
-  readonly markAdmissionCommitted: (generation: number, handoffCount: number) => void;
-  readonly updateLeaseAudit: (generation: number, handoffCount: number) => void;
-  readonly abandonReloadHandoff: () => void;
-  readonly beginNotification: (lease: ReloadShellActivationLeaseV1) => string | undefined;
-  readonly finishNotification: (token: string, delivered: boolean) => void;
-  readonly releaseResources: () => void;
-}
-
-export interface ReloadShellHostAdapterV1 {
-  readonly activationNonce: string;
-  readonly onBound: (lease: ReloadShellActivationLeaseV1) => void;
-  readonly onChanged: (execution: ReloadableShellExecutionV1) => void;
-  readonly onTerminal: (execution: ReloadableShellExecutionV1) => void;
-}
-
-export interface ReloadShellOwnerHubV1 {
-  readonly protocol: 'pi-background-tasks.reload-shell-owner.v1';
-  readonly hubNonce: string;
-  beginActivation(
-    identity: ReloadShellIdentityV1,
-    startReason: string,
-    activationNonce: string,
-  ): ReloadShellActivationClaimV1;
-  commitActivation(
-    claim: ReloadShellActivationClaimV1,
-    adapter: ReloadShellHostAdapterV1,
-  ): ReloadShellActivationLeaseV1;
-  abortActivation(claim: ReloadShellActivationClaimV1, error: unknown): void;
-  beginReloadHandoff(lease: ReloadShellActivationLeaseV1): readonly ReloadableShellExecutionV1[];
-  releaseActivation(lease: ReloadShellActivationLeaseV1): void;
-  registerExecution(
-    lease: ReloadShellActivationLeaseV1,
-    execution: ReloadableShellExecutionV1,
-  ): void;
-  markAdmissionCommitted(
-    lease: ReloadShellActivationLeaseV1,
-    execution: ReloadableShellExecutionV1,
-  ): void;
-  releaseExecution(
-    leaseOrClaim: ReloadShellActivationLeaseV1 | ReloadShellActivationClaimV1,
-    execution: ReloadableShellExecutionV1,
-  ): void;
-  isCurrentLease(lease: ReloadShellActivationLeaseV1): boolean;
-}
+  | 'retention_limit';
 
 export interface BgTaskSnapshot {
   id: string;
@@ -204,9 +31,8 @@ export interface BgTaskSnapshot {
   exitCode?: number | null | undefined;
   signal?: string | null | undefined;
   pid?: number | undefined;
+  posixProcessGroupId?: number | undefined;
   bytesWritten: number;
-  surviveReload: boolean;
-  reloadSurvival?: ReloadSurvivalSnapshotV1 | undefined;
   error?: string | undefined;
   notified: boolean;
   notifyOnCompletion: boolean;
@@ -222,13 +48,18 @@ export interface BgTask extends Omit<BgTaskSnapshot, 'name'> {
   metadataAbsPath: string;
   eventsAbsPath?: string | undefined;
   stderrAbsPath?: string | undefined;
-  child?: BackgroundTaskChildProcess | undefined;
-  /** Immutable in-memory ownership captured from a detached POSIX spawn; never restored from metadata. */
+  /** POSIX group authority captured at spawn; never restored except by adoption. */
   ownedPosixProcessGroupId?: number | undefined;
   /** One-way latch preventing any later signal after group authority is released. */
   posixProcessGroupSignalAuthorityReleased?: boolean | undefined;
-  stream?: WriteStream | undefined;
-  timeoutHandle?: NodeJS.Timeout | undefined;
+  /** Absolute marker path; the wrapper writes the exit code here on settlement. */
+  exitMarkerAbsPath?: string | undefined;
+  /** False while the detached spawn is still in flight; the poller must not reap it then. */
+  launched?: boolean | undefined;
+  /** False only for an unclassified user shell launched without a wrapper. */
+  exitMarkerTrusted?: boolean | undefined;
+  runnerScriptFile?: string | undefined;
+  pollInFlight?: boolean | undefined;
   killKind?: KillKind | undefined;
   killSignalSent?: boolean | undefined;
   killEscalationTimer?: NodeJS.Timeout | undefined;
@@ -245,12 +76,6 @@ export interface BgTask extends Omit<BgTaskSnapshot, 'name'> {
   terminalPublishRetryHandle?: NodeJS.Timeout | undefined;
   /** Optional protocol barrier used by EventBus run requests so early child exits cannot publish before the run response is observable. */
   terminalPublicationGate?: Promise<void> | undefined;
-  /** In-memory same-process authority for an opted ordinary shell task; never serialized. */
-  reloadExecution?: ReloadableShellExecutionV1 | undefined;
-  /** Fresh-registry terminal host delivery state for an imported owner execution. */
-  reloadHostDeliveryInFlight?: boolean | undefined;
-  reloadHostDeliverySettled?: boolean | undefined;
-  reloadHostNotificationSettled?: boolean | undefined;
   metadataWriteChain?: Promise<void> | undefined;
   waiters: Array<() => void>;
 }
@@ -342,7 +167,6 @@ export interface StartTaskOptions {
   timeoutSeconds?: number | undefined;
   notifyOnCompletion?: boolean | undefined;
   triggerOnCompletion?: boolean | undefined;
-  surviveReload?: boolean | undefined;
   /** @internal EventBus protocol barrier; callers should not set this outside the extension service. */
   terminalPublicationGate?: Promise<void> | undefined;
 }
@@ -452,11 +276,9 @@ function parseNameValueAndRest(valueAndRest: string): { value: string; rest: str
 export function parseBgCommandArgs(args: string): {
   name?: string;
   command: string;
-  surviveReload: boolean;
 } {
   let input = args.trim();
   let name: string | undefined;
-  let surviveReload = false;
 
   while (input) {
     let consumed = false;
@@ -484,27 +306,25 @@ export function parseBgCommandArgs(args: string): {
     }
     if (consumed) continue;
 
+    // Legacy flag: recognized and silently dropped. Task survival across /reload
+    // is now the only behavior, so the flag has nothing left to toggle.
     if (
       input === '--survive-reload' ||
       input.startsWith('--survive-reload ') ||
-      input.startsWith('--survive-reload\t')
+      input.startsWith('--survive-reload\t') ||
+      input.startsWith('--survive-reload=')
     ) {
-      if (surviveReload) {
-        throw new ReloadSurvivalError(
-          'pi_bg_survive_reload_invalid',
-          '/bg accepts --survive-reload at most once',
-        );
+      if (input.startsWith('--survive-reload=')) {
+        // Legacy bare-flag-only policy: a `=` value was never honored, so the
+        // ignored flag consumes its whole value up to the next token.
+        const afterEquals = input.slice('--survive-reload='.length);
+        const valueEnd = afterEquals.search(/\s/u);
+        input = valueEnd === -1 ? '' : afterEquals.slice(valueEnd).trimStart();
+      } else {
+        input = input.slice('--survive-reload'.length).trimStart();
       }
-      surviveReload = true;
-      input = input.slice('--survive-reload'.length).trimStart();
       continue;
     }
-    if (input.startsWith('--survive-reload=')) {
-      throw new ReloadSurvivalError(
-        'pi_bg_survive_reload_invalid',
-        '/bg accepts only the bare --survive-reload flag',
-      );
-    }
 
     if (input === '--') {
       input = '';
@@ -517,7 +337,7 @@ export function parseBgCommandArgs(args: string): {
     break;
   }
 
-  return name ? { name, command: input, surviveReload } : { command: input, surviveReload };
+  return name ? { name, command: input } : { command: input };
 }
 
 export function formatDuration(ms: number): string {
@@ -850,9 +670,8 @@ export function snapshot(task: BgTask): BgTaskSnapshot {
     exitCode: task.exitCode,
     signal: task.signal,
     pid: task.pid,
+    posixProcessGroupId: task.ownedPosixProcessGroupId,
     bytesWritten: task.bytesWritten,
-    surviveReload: task.surviveReload === true,
-    reloadSurvival: task.reloadSurvival,
     error: task.error,
     notified: task.notified,
     notifyOnCompletion: task.notifyOnCompletion,