@naiba/pi-durable-background-tasks 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 naiba
+
+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,60 @@
-# Temporary Holding Version
+# Pi Durable Background Tasks
 
-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.
+Supervised background shell commands for Pi Durable. No delegated agents, model configuration, or implicit model calls.
+
+**Initial development version. Linux only; requires Python 3.9+ and Linux pidfd support.**
+
+```sh
+bun add @naiba/pi-durable-background-tasks
+```
+
+## Usage
+
+```ts
+import {BackgroundTasks} from "@naiba/pi-durable-background-tasks";
+import {backgroundTasksExtension} from "@naiba/pi-durable-background-tasks/pi";
+
+const tasks = new BackgroundTasks("/persistent/session/background");
+registry.install(backgroundTasksExtension(tasks, "/workspace"));
+// Register your normal Pi beforeTool approval policy. This package does not bypass it.
+const unsubscribe = tasks.subscribe(() => render(tasks.list()));
+// Host shutdown must await cleanup:
+await tasks.close();
+unsubscribe();
+```
+
+Tools: `background_start`, `background_status`, `background_output`, `background_wait`, `background_stop`.
+Wait requires `timeout_ms` between 1 and 600000. Observation timeout/cancellation does not stop the command. Commands have no implicit execution deadline.
+
+The core API works without creating a model session. `start` requires a stable `requestId`; repeats return the original record and mismatching arguments are rejected. Recovered records never automatically relaunch a command. Use one service instance per directory and one writer process; concurrent writers are not supported.
+
+## Process ownership
+
+Each command has a Linux Python subreaper supervisor. A private stdin pipe ties ownership to the host: explicit stop or host pipe loss (including host SIGKILL) initiates cleanup. The supervisor reaps descendants, including ordinary double-fork/setsid escapes. TERM gets a grace interval before KILL; pidfd signalling avoids signalling a recycled PID. Even normal shell completion cleans up descendants before publishing a settled result.
+
+This is **lifecycle management, not an OS security sandbox**. Privileged or hostile commands can kill the supervisor, leave its PID namespace, or start processes through an external daemon. Killing both the supervisor and host, uninterruptible kernel tasks, machine failure, and external-service side effects are not covered. Use delegated cgroups/container isolation for stronger enforcement. A supervisor without confirmed cleanup yields `unknown`, never fabricated success. The service never kills from a persisted PID after restart.
+
+Records and logs survive reopening; live process continuity across host restart is deliberately not promised. Recovered active records become `unknown`. No automatic model wakeup or replay occurs. Hosts choose how to consume lifecycle events and display unknown execution ownership.
+
+Output reads are bounded to 64 KiB, with byte offsets. Logs are retained without automatic deletion; configure filesystem quotas at the host level. Commands run with inherited environment and host permissions. Do not expose this service directly to untrusted clients; isolate task directories by session and authorize every tool/HTTP action.
+
+## Development
+
+```sh
+bun install
+bun run build
+bun test
+```
+
+Tests exercise real Linux processes rather than mocked cancellation. The build includes the Python supervisor beside the JavaScript distribution.
+
+## Publishing
+
+Releases use `.github/workflows/publish.yml` on pushed `v*` tags, with npm Trusted Publishing (OIDC); no npm token secret is required. Configure this package's GitHub Actions trusted publisher on npm:
+
+- Organization or user: `naiba`
+- Repository: `pi-durable-background-tasks`
+- Workflow filename: `publish.yml`
+- Environment: leave empty (the workflow does not declare an environment)
+
+Update `package.json` to a new stable version, refresh `bun.lock` if needed, commit and push, then push the matching tag (for example, `v0.1.1` for version `0.1.1`). The workflow rejects mismatching or prerelease versions, runs type checks, build and process tests, then publishes publicly with provenance. Published versions are immutable: `0.1.0` already exists and must not be republished. Never move a published release tag. There is no manual-dispatch publish path.

package/dist/index.d.ts

@@ -0,0 +1,88 @@
+export type BackgroundTask = {
+    id: string;
+    command: string;
+    cwd: string;
+    name: string;
+    status: "starting" | "running" | "stopping" | "completed" | "failed" | "stopped" | "unknown";
+    createdAt: string;
+    updatedAt: string;
+    exitCode?: number | null;
+    error?: string;
+};
+export declare class BackgroundTasks {
+    private python;
+    private records;
+    private owned;
+    private listeners;
+    private closed;
+    readonly directory: string;
+    constructor(directory: string, python?: string);
+    subscribe(listener: () => void): () => void;
+    list(): {
+        id: string;
+        command: string;
+        cwd: string;
+        name: string;
+        status: "starting" | "running" | "stopping" | "completed" | "failed" | "stopped" | "unknown";
+        createdAt: string;
+        updatedAt: string;
+        exitCode?: number | null;
+        error?: string;
+    }[];
+    get(id: string): {
+        id: string;
+        command: string;
+        cwd: string;
+        name: string;
+        status: "starting" | "running" | "stopping" | "completed" | "failed" | "stopped" | "unknown";
+        createdAt: string;
+        updatedAt: string;
+        exitCode?: number | null;
+        error?: string;
+    };
+    get active(): boolean;
+    private update;
+    start(input: {
+        requestId: string;
+        command: string;
+        cwd: string;
+        name?: string;
+    }): {
+        id: string;
+        command: string;
+        cwd: string;
+        name: string;
+        status: "starting" | "running" | "stopping" | "completed" | "failed" | "stopped" | "unknown";
+        createdAt: string;
+        updatedAt: string;
+        exitCode?: number | null;
+        error?: string;
+    };
+    output(id: string, offset?: number, limit?: number): Promise<{
+        text: string;
+        nextOffset: number;
+    }>;
+    wait(id: string, timeoutMs: number, signal?: AbortSignal): Promise<{
+        id: string;
+        command: string;
+        cwd: string;
+        name: string;
+        status: "starting" | "running" | "stopping" | "completed" | "failed" | "stopped" | "unknown";
+        createdAt: string;
+        updatedAt: string;
+        exitCode?: number | null;
+        error?: string;
+    }>;
+    stop(id: string): Promise<{
+        id: string;
+        command: string;
+        cwd: string;
+        name: string;
+        status: "starting" | "running" | "stopping" | "completed" | "failed" | "stopped" | "unknown";
+        createdAt: string;
+        updatedAt: string;
+        exitCode?: number | null;
+        error?: string;
+    }>;
+    close(): Promise<void>;
+}

package/dist/index.js

@@ -0,0 +1,165 @@
+import { spawn } from "node:child_process";
+import { mkdirSync, readFileSync, readdirSync, writeFileSync, renameSync } from "node:fs";
+import { open } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createHash } from "node:crypto";
+export class BackgroundTasks {
+    python;
+    records = new Map();
+    owned = new Map();
+    listeners = new Set();
+    closed = false;
+    directory;
+    constructor(directory, python = "python3") {
+        this.python = python;
+        if (process.platform !== "linux")
+            throw new Error("Background task supervision currently requires Linux");
+        this.directory = resolve(directory);
+        mkdirSync(this.directory, { recursive: true, mode: 0o700 });
+        for (const file of readdirSync(this.directory).filter(value => /^[a-f0-9]{64}\.json$/.test(value))) {
+            const task = JSON.parse(readFileSync(join(this.directory, file), "utf8"));
+            if (task.id + ".json" !== file)
+                throw new Error("Invalid background task identity");
+            this.records.set(task.id, task);
+            // Persisted PIDs are never used for control after restart: ownership is unknown.
+            if (["starting", "running", "stopping"].includes(task.status))
+                this.update(task, { status: "unknown", error: "Host restarted; command is not replayed and process ownership cannot be confirmed" });
+        }
+    }
+    subscribe(listener) { this.listeners.add(listener); return () => { this.listeners.delete(listener); }; }
+    list() { return [...this.records.values()].map(task => ({ ...task })); }
+    get(id) { const task = this.records.get(id); if (!task)
+        throw new Error("Background task not found"); return { ...task }; }
+    get active() { return this.owned.size > 0; }
+    update(task, changes = {}) {
+        Object.assign(task, changes, { updatedAt: new Date().toISOString() });
+        const path = join(this.directory, task.id + ".json");
+        writeFileSync(path + ".pending", JSON.stringify(task), { mode: 0o600 });
+        renameSync(path + ".pending", path);
+        for (const listener of this.listeners) {
+            try {
+                listener();
+            }
+            catch { /* Observers cannot break process cleanup. */ }
+        }
+    }
+    start(input) {
+        if (this.closed)
+            throw new Error("Background task service is closed");
+        if (!input.requestId || !input.command.trim())
+            throw new Error("requestId and command are required");
+        const id = createHash("sha256").update(input.requestId).digest("hex");
+        const cwd = resolve(input.cwd), name = input.name || input.command.slice(0, 100);
+        const existing = this.records.get(id);
+        if (existing) {
+            if (existing.command !== input.command || existing.cwd !== cwd || existing.name !== name)
+                throw new Error("Request identity conflicts with earlier command");
+            return { ...existing };
+        }
+        const task = { id, command: input.command, cwd, name, status: "starting", createdAt: new Date().toISOString(), updatedAt: new Date().toISOString() };
+        this.records.set(id, task);
+        this.update(task);
+        const child = spawn(this.python, [fileURLToPath(new URL("./process-supervisor.py", import.meta.url))], { stdio: "pipe" });
+        let finish;
+        const done = new Promise(resolve => { finish = resolve; });
+        this.owned.set(id, { child, done });
+        let buffer = "", diagnostic = "", settled = false;
+        child.stdout.on("data", chunk => {
+            buffer += chunk.toString();
+            for (let position; (position = buffer.indexOf("\n")) >= 0;) {
+                const line = buffer.slice(0, position);
+                buffer = buffer.slice(position + 1);
+                try {
+                    const event = JSON.parse(line);
+                    if (event.event === "started" && task.status === "starting")
+                        this.update(task, { status: "running" });
+                    if (event.event === "settled") {
+                        settled = true;
+                        this.update(task, { status: event.status, exitCode: event.exitCode });
+                    }
+                }
+                catch {
+                    diagnostic = "Invalid supervisor response";
+                    child.stdin.end();
+                }
+            }
+        });
+        child.stderr.on("data", chunk => { diagnostic = (diagnostic + chunk.toString()).slice(-4000); });
+        child.stdin.on("error", () => { });
+        child.on("error", error => { diagnostic = error.message; });
+        child.on("close", () => {
+            try {
+                if (!settled)
+                    this.update(task, { status: "unknown", error: diagnostic || "Supervisor exited without confirming cleanup" });
+            }
+            finally {
+                this.owned.delete(id);
+                finish();
+                for (const listener of this.listeners) {
+                    try {
+                        listener();
+                    }
+                    catch { }
+                }
+            }
+        });
+        child.stdin.write(JSON.stringify({ command: task.command, cwd, log: join(this.directory, id + ".log") }) + "\n");
+        return { ...task };
+    }
+    async output(id, offset = 0, limit = 32768) {
+        this.get(id);
+        if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isInteger(limit) || limit < 1 || limit > 65536)
+            throw new Error("Invalid output bounds");
+        let file;
+        try {
+            file = await open(join(this.directory, id + ".log"), "r");
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return { text: "", nextOffset: offset };
+            throw error;
+        }
+        try {
+            const buffer = Buffer.alloc(limit);
+            const { bytesRead } = await file.read(buffer, 0, limit, offset);
+            return { text: buffer.subarray(0, bytesRead).toString("utf8"), nextOffset: offset + bytesRead };
+        }
+        finally {
+            await file.close();
+        }
+    }
+    async wait(id, timeoutMs, signal) {
+        this.get(id);
+        if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 600000)
+            throw new Error("timeoutMs must be 1..600000");
+        signal?.throwIfAborted();
+        const owner = this.owned.get(id);
+        if (!owner)
+            return this.get(id);
+        await new Promise((resolve, reject) => {
+            const finish = () => { clearTimeout(timer); signal?.removeEventListener("abort", abort); resolve(); };
+            const abort = () => { clearTimeout(timer); signal?.removeEventListener("abort", abort); reject(signal?.reason); };
+            const timer = setTimeout(finish, timeoutMs);
+            signal?.addEventListener("abort", abort, { once: true });
+            void owner.done.then(finish);
+        });
+        return this.get(id);
+    }
+    async stop(id) {
+        const task = this.records.get(id);
+        if (!task)
+            throw new Error("Background task not found");
+        const owner = this.owned.get(id);
+        if (!owner) {
+            if (task.status === "unknown")
+                throw new Error("Cannot stop a process without verified ownership");
+            return { ...task };
+        }
+        this.update(task, { status: "stopping" });
+        owner.child.stdin.end();
+        await owner.done;
+        return this.get(id);
+    }
+    async close() { this.closed = true; await Promise.all([...this.owned.keys()].map(id => this.stop(id))); }
+}

package/dist/pi.d.ts

@@ -0,0 +1,3 @@
+import { Type } from "@earendil-works/pi-ai";
+import { BackgroundTasks } from "./index.js";
+export declare function backgroundTasksExtension(service: BackgroundTasks, cwd: string): import("@earendil-works/pi-durable").Extension<import("@earendil-works/pi-durable").ToolRegistration<Type.TObject<{}>, import("@earendil-works/chord").JsonValue>>;

package/dist/pi.js

@@ -0,0 +1,19 @@
+import { defineExtension, defineTool } from "@earendil-works/pi-durable";
+import { Type } from "@earendil-works/pi-ai";
+const result = (value) => ({ content: [{ type: "text", text: JSON.stringify(value) }] });
+export function backgroundTasksExtension(service, cwd) {
+    return defineExtension({ name: "background-tasks", tools: [
+            defineTool({ name: "background_start", description: "Start a supervised background shell command. Returns immediately; no model delegation. Commands do not survive host loss. Approval belongs to the host tool policy.", replay: "unsafe",
+                parameters: Type.Object({ command: Type.String(), name: Type.Optional(Type.String()) }),
+                execute: async (args, api) => result(service.start({ ...args, cwd, requestId: String(api.taskId) })) }),
+            defineTool({ name: "background_status", description: "List background commands owned by this session.", replay: "safe", parameters: Type.Object({}), execute: async () => result(service.list()) }),
+            defineTool({ name: "background_output", description: "Read bounded background output using byte offsets.", replay: "safe",
+                parameters: Type.Object({ id: Type.String(), offset: Type.Optional(Type.Integer({ minimum: 0 })), limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 65536 })) }),
+                execute: async (args) => result(await service.output(args.id, args.offset, args.limit)) }),
+            defineTool({ name: "background_wait", description: "Wait for a background command. Explicit timeout ends observation only, not execution.", replay: "safe",
+                parameters: Type.Object({ id: Type.String(), timeout_ms: Type.Integer({ minimum: 1, maximum: 600000 }) }),
+                execute: async (args, api, ctx) => result(await service.wait(args.id, args.timeout_ms, ctx.abortSignal)) }),
+            defineTool({ name: "background_stop", description: "Stop a session-owned command and reap its descendants. Returns after supervisor cleanup.", replay: "unsafe",
+                parameters: Type.Object({ id: Type.String() }), execute: async (args) => result(await service.stop(args.id)) }),
+        ] });
+}

package/dist/process-supervisor.py

@@ -0,0 +1,94 @@
+"""Linux command owner. EOF on the host pipe means cleanup, never detach."""
+import ctypes
+import json
+import os
+import selectors
+import signal
+import subprocess
+import sys
+import time
+
+
+def children():
+    # Subreaper adoption keeps double-fork/setsid descendants under our ownership.
+    found = set()
+    pending = [os.getpid()]
+    while pending:
+        parent = pending.pop()
+        try:
+            with open(f"/proc/{parent}/task/{parent}/children") as stream:
+                direct = [int(value) for value in stream.read().split()]
+        except FileNotFoundError:
+            continue
+        for pid in direct:
+            if pid not in found:
+                found.add(pid)
+                pending.append(pid)
+    return found
+
+
+def reap():
+    while True:
+        try:
+            if os.waitpid(-1, os.WNOHANG)[0] == 0:
+                return
+        except ChildProcessError:
+            return
+
+
+def cleanup(grace):
+    deadline = time.monotonic() + grace
+    while True:
+        owned = children()
+        if not owned:
+            reap()
+            return
+        for pid in owned:
+            try:
+                # pidfds prevent a recycled PID from targeting an unrelated process.
+                fd = os.pidfd_open(pid)
+                try:
+                    if pid in children():
+                        signal.pidfd_send_signal(fd, signal.SIGTERM if time.monotonic() < deadline else signal.SIGKILL)
+                finally:
+                    os.close(fd)
+            except ProcessLookupError:
+                pass
+        reap()
+        time.sleep(0.02)
+
+
+def main():
+    libc = ctypes.CDLL(None, use_errno=True)
+    if libc.prctl(36, 1, 0, 0, 0) != 0:  # PR_SET_CHILD_SUBREAPER
+        raise OSError(ctypes.get_errno(), "Cannot become a child subreaper")
+    os.umask(0o077)
+    config = json.loads(sys.stdin.buffer.readline())
+    stopped = False
+    def stop(signum, frame):
+        nonlocal stopped
+        stopped = True
+    signal.signal(signal.SIGTERM, stop)
+    signal.signal(signal.SIGINT, stop)
+    selector = selectors.DefaultSelector()
+    selector.register(sys.stdin, selectors.EVENT_READ)
+    process = None
+    try:
+        with open(config["log"], "ab", buffering=0) as output:
+            process = subprocess.Popen(["/bin/sh", "-c", config["command"]], cwd=config["cwd"],
+                stdin=subprocess.DEVNULL, stdout=output, stderr=output, start_new_session=True)
+            print(json.dumps({"event": "started", "pid": process.pid}), flush=True)
+            while process.poll() is None and not stopped:
+                if selector.select(0.05):
+                    # A stop byte OR EOF (including host SIGKILL) requests cleanup.
+                    os.read(sys.stdin.fileno(), 4096)
+                    stopped = True
+            exit_code = process.poll()
+    finally:
+        cleanup(config.get("graceSeconds", 1))
+        selector.close()
+    print(json.dumps({"event": "settled", "status": "stopped" if stopped else "completed" if exit_code == 0 else "failed", "exitCode": exit_code}), flush=True)
+
+
+if __name__ == "__main__":
+    main()

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@naiba/pi-durable-background-tasks",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Background shell tools for Pi Durable; no model delegation",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/naiba/pi-durable-background-tasks.git"
+  },
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./pi": {
+      "bun": "./src/pi.ts",
+      "types": "./src/pi.ts",
+      "default": "./dist/pi.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc && cp src/process-supervisor.py dist/process-supervisor.py",
+    "test": "bun test",
+    "check": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-durable": "^1.0.4",
+    "@earendil-works/pi-ai": "^1.0.4"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@types/bun": "latest",
+    "typescript": "~5.9.3",
+    "@earendil-works/pi-durable": "1.0.4",
+    "@earendil-works/pi-ai": "1.0.4"
+  }
+}

package/src/index.ts

@@ -0,0 +1,99 @@
+import {spawn, type ChildProcessWithoutNullStreams} from "node:child_process";
+import {mkdirSync, readFileSync, readdirSync, writeFileSync, renameSync} from "node:fs";
+import {open} from "node:fs/promises";
+import {join, resolve} from "node:path";
+import {fileURLToPath} from "node:url";
+import {createHash} from "node:crypto";
+
+export type BackgroundTask = {
+ id:string; command:string; cwd:string; name:string;
+ status:"starting"|"running"|"stopping"|"completed"|"failed"|"stopped"|"unknown";
+ createdAt:string; updatedAt:string; exitCode?:number|null; error?:string;
+};
+type Owned = {child:ChildProcessWithoutNullStreams; done:Promise<void>};
+export class BackgroundTasks {
+ private records = new Map<string,BackgroundTask>();
+ private owned = new Map<string,Owned>();
+ private listeners = new Set<()=>void>();
+ private closed=false;
+ readonly directory:string;
+ constructor(directory:string, private python="python3") {
+  if(process.platform!=="linux")throw new Error("Background task supervision currently requires Linux");
+  this.directory=resolve(directory);mkdirSync(this.directory,{recursive:true,mode:0o700});
+  for(const file of readdirSync(this.directory).filter(value=>/^[a-f0-9]{64}\.json$/.test(value))){
+   const task=JSON.parse(readFileSync(join(this.directory,file),"utf8")) as BackgroundTask;
+   if(task.id+".json"!==file)throw new Error("Invalid background task identity");
+   this.records.set(task.id,task);
+   // Persisted PIDs are never used for control after restart: ownership is unknown.
+   if(["starting","running","stopping"].includes(task.status))this.update(task,{status:"unknown",error:"Host restarted; command is not replayed and process ownership cannot be confirmed"});
+  }
+ }
+ subscribe(listener:()=>void){this.listeners.add(listener);return ()=>{this.listeners.delete(listener);};}
+ list(){return [...this.records.values()].map(task=>({...task}));}
+ get(id:string){const task=this.records.get(id);if(!task)throw new Error("Background task not found");return {...task};}
+ get active(){return this.owned.size>0;}
+ private update(task:BackgroundTask, changes:Partial<BackgroundTask>={}){
+  Object.assign(task,changes,{updatedAt:new Date().toISOString()});
+  const path=join(this.directory,task.id+".json");
+  writeFileSync(path+".pending",JSON.stringify(task),{mode:0o600});renameSync(path+".pending",path);
+  for(const listener of this.listeners){try{listener();}catch{/* Observers cannot break process cleanup. */}}
+ }
+ start(input:{requestId:string;command:string;cwd:string;name?:string}){
+  if(this.closed)throw new Error("Background task service is closed");
+  if(!input.requestId || !input.command.trim())throw new Error("requestId and command are required");
+  const id=createHash("sha256").update(input.requestId).digest("hex");
+  const cwd=resolve(input.cwd),name=input.name||input.command.slice(0,100);
+  const existing=this.records.get(id);
+  if(existing){if(existing.command!==input.command||existing.cwd!==cwd||existing.name!==name)throw new Error("Request identity conflicts with earlier command");return {...existing};}
+  const task:BackgroundTask={id,command:input.command,cwd,name,status:"starting",createdAt:new Date().toISOString(),updatedAt:new Date().toISOString()};
+  this.records.set(id,task);this.update(task);
+  const child=spawn(this.python,[fileURLToPath(new URL("./process-supervisor.py",import.meta.url))],{stdio:"pipe"});
+  let finish!:()=>void;const done=new Promise<void>(resolve=>{finish=resolve;});
+  this.owned.set(id,{child,done});
+  let buffer="",diagnostic="",settled=false;
+  child.stdout.on("data",chunk=>{
+   buffer+=chunk.toString();
+   for(let position;(position=buffer.indexOf("\n"))>=0;){
+    const line=buffer.slice(0,position);buffer=buffer.slice(position+1);
+    try{const event=JSON.parse(line);
+     if(event.event==="started"&&task.status==="starting")this.update(task,{status:"running"});
+     if(event.event==="settled"){settled=true;this.update(task,{status:event.status,exitCode:event.exitCode});}
+    }catch{diagnostic="Invalid supervisor response";child.stdin.end();}
+   }
+  });
+  child.stderr.on("data",chunk=>{diagnostic=(diagnostic+chunk.toString()).slice(-4000);});
+  child.stdin.on("error",()=>{/* close/error below owns final state */});
+  child.on("error",error=>{diagnostic=error.message;});
+  child.on("close",()=>{
+   try{if(!settled)this.update(task,{status:"unknown",error:diagnostic||"Supervisor exited without confirming cleanup"});}
+   finally{this.owned.delete(id);finish();for(const listener of this.listeners){try{listener();}catch{}}}
+  });
+  child.stdin.write(JSON.stringify({command:task.command,cwd,log:join(this.directory,id+".log")})+"\n");
+  return {...task};
+ }
+ async output(id:string,offset=0,limit=32768){
+  this.get(id);
+  if(!Number.isSafeInteger(offset)||offset<0||!Number.isInteger(limit)||limit<1||limit>65536)throw new Error("Invalid output bounds");
+  let file;try{file=await open(join(this.directory,id+".log"),"r");}catch(error){if((error as NodeJS.ErrnoException).code==="ENOENT")return {text:"",nextOffset:offset};throw error;}
+  try{const buffer=Buffer.alloc(limit);const {bytesRead}=await file.read(buffer,0,limit,offset);return {text:buffer.subarray(0,bytesRead).toString("utf8"),nextOffset:offset+bytesRead};}finally{await file.close();}
+ }
+ async wait(id:string,timeoutMs:number,signal?:AbortSignal){
+  this.get(id);
+  if(!Number.isInteger(timeoutMs)||timeoutMs<1||timeoutMs>600000)throw new Error("timeoutMs must be 1..600000");
+  signal?.throwIfAborted();
+  const owner=this.owned.get(id);if(!owner)return this.get(id);
+  await new Promise<void>((resolve,reject)=>{
+   const finish=()=>{clearTimeout(timer);signal?.removeEventListener("abort",abort);resolve();};
+   const abort=()=>{clearTimeout(timer);signal?.removeEventListener("abort",abort);reject(signal?.reason);};
+   const timer=setTimeout(finish,timeoutMs);signal?.addEventListener("abort",abort,{once:true});void owner.done.then(finish);
+  });
+  return this.get(id);
+ }
+ async stop(id:string){
+  const task=this.records.get(id);if(!task)throw new Error("Background task not found");
+  const owner=this.owned.get(id);
+  if(!owner){if(task.status==="unknown")throw new Error("Cannot stop a process without verified ownership");return {...task};}
+  this.update(task,{status:"stopping"});owner.child.stdin.end();await owner.done;return this.get(id);
+ }
+ async close(){this.closed=true;await Promise.all([...this.owned.keys()].map(id=>this.stop(id)));}
+}

package/src/pi.ts

@@ -0,0 +1,20 @@
+import {defineExtension,defineTool} from "@earendil-works/pi-durable";
+import {Type} from "@earendil-works/pi-ai";
+import {BackgroundTasks} from "./index.js";
+const result=(value:unknown)=>({content:[{type:"text" as const,text:JSON.stringify(value)}]});
+export function backgroundTasksExtension(service:BackgroundTasks,cwd:string){
+ return defineExtension({name:"background-tasks",tools:[
+  defineTool({name:"background_start",description:"Start a supervised background shell command. Returns immediately; no model delegation. Commands do not survive host loss. Approval belongs to the host tool policy.",replay:"unsafe",
+   parameters:Type.Object({command:Type.String(),name:Type.Optional(Type.String())}),
+   execute:async(args,api)=>result(service.start({...args,cwd,requestId:String(api.taskId)}))}),
+  defineTool({name:"background_status",description:"List background commands owned by this session.",replay:"safe",parameters:Type.Object({}),execute:async()=>result(service.list())}),
+  defineTool({name:"background_output",description:"Read bounded background output using byte offsets.",replay:"safe",
+   parameters:Type.Object({id:Type.String(),offset:Type.Optional(Type.Integer({minimum:0})),limit:Type.Optional(Type.Integer({minimum:1,maximum:65536}))}),
+   execute:async(args)=>result(await service.output(args.id,args.offset,args.limit))}),
+  defineTool({name:"background_wait",description:"Wait for a background command. Explicit timeout ends observation only, not execution.",replay:"safe",
+   parameters:Type.Object({id:Type.String(),timeout_ms:Type.Integer({minimum:1,maximum:600000})}),
+   execute:async(args,api,ctx)=>result(await service.wait(args.id,args.timeout_ms,ctx.abortSignal))}),
+  defineTool({name:"background_stop",description:"Stop a session-owned command and reap its descendants. Returns after supervisor cleanup.",replay:"unsafe",
+   parameters:Type.Object({id:Type.String()}),execute:async(args)=>result(await service.stop(args.id))}),
+ ]});
+}

package/src/process-supervisor.py

@@ -0,0 +1,94 @@
+"""Linux command owner. EOF on the host pipe means cleanup, never detach."""
+import ctypes
+import json
+import os
+import selectors
+import signal
+import subprocess
+import sys
+import time
+
+
+def children():
+    # Subreaper adoption keeps double-fork/setsid descendants under our ownership.
+    found = set()
+    pending = [os.getpid()]
+    while pending:
+        parent = pending.pop()
+        try:
+            with open(f"/proc/{parent}/task/{parent}/children") as stream:
+                direct = [int(value) for value in stream.read().split()]
+        except FileNotFoundError:
+            continue
+        for pid in direct:
+            if pid not in found:
+                found.add(pid)
+                pending.append(pid)
+    return found
+
+
+def reap():
+    while True:
+        try:
+            if os.waitpid(-1, os.WNOHANG)[0] == 0:
+                return
+        except ChildProcessError:
+            return
+
+
+def cleanup(grace):
+    deadline = time.monotonic() + grace
+    while True:
+        owned = children()
+        if not owned:
+            reap()
+            return
+        for pid in owned:
+            try:
+                # pidfds prevent a recycled PID from targeting an unrelated process.
+                fd = os.pidfd_open(pid)
+                try:
+                    if pid in children():
+                        signal.pidfd_send_signal(fd, signal.SIGTERM if time.monotonic() < deadline else signal.SIGKILL)
+                finally:
+                    os.close(fd)
+            except ProcessLookupError:
+                pass
+        reap()
+        time.sleep(0.02)
+
+
+def main():
+    libc = ctypes.CDLL(None, use_errno=True)
+    if libc.prctl(36, 1, 0, 0, 0) != 0:  # PR_SET_CHILD_SUBREAPER
+        raise OSError(ctypes.get_errno(), "Cannot become a child subreaper")
+    os.umask(0o077)
+    config = json.loads(sys.stdin.buffer.readline())
+    stopped = False
+    def stop(signum, frame):
+        nonlocal stopped
+        stopped = True
+    signal.signal(signal.SIGTERM, stop)
+    signal.signal(signal.SIGINT, stop)
+    selector = selectors.DefaultSelector()
+    selector.register(sys.stdin, selectors.EVENT_READ)
+    process = None
+    try:
+        with open(config["log"], "ab", buffering=0) as output:
+            process = subprocess.Popen(["/bin/sh", "-c", config["command"]], cwd=config["cwd"],
+                stdin=subprocess.DEVNULL, stdout=output, stderr=output, start_new_session=True)
+            print(json.dumps({"event": "started", "pid": process.pid}), flush=True)
+            while process.poll() is None and not stopped:
+                if selector.select(0.05):
+                    # A stop byte OR EOF (including host SIGKILL) requests cleanup.
+                    os.read(sys.stdin.fileno(), 4096)
+                    stopped = True
+            exit_code = process.poll()
+    finally:
+        cleanup(config.get("graceSeconds", 1))
+        selector.close()
+    print(json.dumps({"event": "settled", "status": "stopped" if stopped else "completed" if exit_code == 0 else "failed", "exitCode": exit_code}), flush=True)
+
+
+if __name__ == "__main__":
+    main()