@sebastianandreasson/pi-autonomous-agents 0.5.0 → 0.5.2

package/README.md

@@ -1,58 +1,79 @@
-# PI Harness
+# PI Autonomous Agents
 
-`pi-harness` is a portable CLI/workflow package for running a local PI-based unattended loop with:
+`@sebastianandreasson/pi-autonomous-agents` is an npm package for running a bounded unattended [PI](https://pi.dev/) workflow inside another repository.
 
-- a `developer` pass
-- a fast verification step
-- a skeptical `tester` pass
-- optional periodic multimodal visual review
-- tester-owned final commit by default
+It orchestrates:
 
-The package is intentionally generic. It does not know how to navigate or test a specific app on its own.
+- a `developer` turn
+- a fast local verification step
+- an independent `tester` turn
+- an optional focused `developerFix` turn when verification/tester finds a real issue
+- optional periodic visual review from screenshots
 
-## What Belongs In The Package
+The package is intentionally generic. It handles supervision, prompts, runtime state, telemetry, retries, and guardrails. The consuming repo still owns its own tasks, instructions, tests, model endpoints, and screenshot capture flow.
 
-- supervisor/orchestration
-- PI adapter/runtime integration
+## Install
+
+```bash
+npm install -D @sebastianandreasson/pi-autonomous-agents
+```
+
+Then in the consuming repo, tell your agent:
+
+```text
+Find SETUP.md in @sebastianandreasson/pi-autonomous-agents and set everything up for this repository.
+```
+
+The package ships a top-level [SETUP.md](./SETUP.md) specifically for that workflow.
+
+## What This Package Owns
+
+- unattended loop orchestration
+- PI adapter integration
 - config loading
-- telemetry
-- loop guards, timeout guards, and retries
-- tester feedback + visual feedback handoff
-- optional legacy harness git finalize step for `commitMode: "plan"`
-- multimodal visual review client
+- prompt assembly
+- verification/tester/visual-review handoff
+- timeout and loop guards
+- telemetry and run summaries
+- runtime isolation and stale-run recovery
 
-## What Stays Per Project
+## What Each Repo Must Provide
 
 - `TODOS.md`
-- project instructions
-- browser tests
-- visual capture flow
-- app-specific verification commands
-- app/server startup scripts
+- repo-specific `pi/DEVELOPER.md`
+- repo-specific `pi/TESTER.md`
+- a fast bounded `testCommand`
+- model configuration that actually matches the local/cloud providers in use
+- optionally a screenshot capture command for visual review
+
+## Quick Start In A Repo
 
-## Layout
+The normal setup shape is:
 
 ```text
-packages/pi-harness/
-  package.json
-  pi.config.json
-  templates/DEVELOPER.md
-  templates/TESTER.md
-  docs/PI_SUPERVISOR.md
-  src/
-    cli.mjs
-    pi-client.mjs
-    pi-config.mjs
-    pi-prompts.mjs
-    pi-repo.mjs
-    pi-report.mjs
-    pi-rpc-adapter.mjs
-    pi-supervisor.mjs
-    pi-telemetry.mjs
-    pi-visual-once.mjs
-    pi-visual-review.mjs
+TODOS.md
+pi.config.json
+pi/
+  DEVELOPER.md
+  TESTER.md
+```
+
+Typical scripts:
+
+```json
+{
+  "scripts": {
+    "pi:mock": "PI_CONFIG_FILE=pi.config.json PI_TRANSPORT=mock PI_TEST_CMD= pi-harness once",
+    "pi:once": "PI_CONFIG_FILE=pi.config.json pi-harness once",
+    "pi:run": "PI_CONFIG_FILE=pi.config.json pi-harness run",
+    "pi:report": "PI_CONFIG_FILE=pi.config.json pi-harness report",
+    "pi:visual:once": "PI_CONFIG_FILE=pi.config.json pi-harness visual-once"
+  }
+}
 ```
 
+Start from [templates/pi.config.example.json](./templates/pi.config.example.json), [templates/DEVELOPER.md](./templates/DEVELOPER.md), [templates/TESTER.md](./templates/TESTER.md), and [templates/gitignore.fragment](./templates/gitignore.fragment).
+
 ## CLI
 
 ```bash
@@ -65,65 +86,213 @@ pi-harness adapter
 pi-harness visual-review-worker
 ```
 
-Use `PI_CONFIG_FILE` to point the harness at a project-local config file. If you do not provide one, the bundled generic `pi.config.json` is used as a fallback.
-
-## Setup In Another Repo
-
-After installing the package:
+Use `PI_CONFIG_FILE` to point at the repo-local config file:
 
 ```bash
-npm install -D @sebastianandreasson/pi-autonomous-agents
+PI_CONFIG_FILE=pi.config.json pi-harness once
 ```
 
-you can tell another agent in that repo:
-
-```text
-Find SETUP.md in @sebastianandreasson/pi-autonomous-agents and set everything up for this repository.
+If `PI_CONFIG_FILE` is not set, the package falls back to the bundled generic [pi.config.json](./pi.config.json).
+
+## Core Workflow
+
+Each real iteration works like this:
+
+1. `developer` implements one unchecked task from `TODOS.md`.
+2. The harness runs the configured fast verification command.
+3. If verification passes, `tester` reviews the change independently.
+4. If tester or verification fails, the findings go back to `developerFix` for one focused repair pass.
+5. If tester reaches `PASS`, tester creates the final commit directly by default.
+6. Every `N` successful iterations, optional visual review can inspect screenshots and veto the success if it finds a real problem.
+
+The default commit model is `commitMode: "agent"`. The older harness-managed parsed commit-plan flow still exists as `commitMode: "plan"`, but it is now a compatibility mode rather than the default.
+
+## Recommended Model Setup
+
+The package supports:
+
+- one default text model via `piModel`
+- one default visual-review model via `visualReviewModel`
+- optional per-role overrides via `roleModels`
+- per-model endpoint config in `models`
+
+Typical pattern:
+
+- local model for `developer`
+- local model for `developerRetry`
+- local model for `developerFix`
+- local or slightly stronger model for `tester`
+- stronger frontier model only for `visualReview`
+
+Example:
+
+```json
+{
+  "piModel": "local/text-model",
+  "visualReviewModel": "cloud/vision-model",
+  "models": {
+    "local/text-model": {
+      "baseUrl": "http://localhost:8000/v1",
+      "apiKey": "local",
+      "vision": false
+    },
+    "local/tester-model": {
+      "baseUrl": "http://localhost:8000/v1",
+      "apiKey": "local",
+      "vision": false
+    },
+    "cloud/vision-model": {
+      "baseUrl": "https://api.openai.com/v1",
+      "apiKeyEnv": "OPENAI_API_KEY",
+      "vision": true
+    }
+  },
+  "roleModels": {
+    "developer": "local/text-model",
+    "developerRetry": "local/text-model",
+    "developerFix": "local/text-model",
+    "tester": "local/tester-model",
+    "visualReview": "cloud/vision-model"
+  }
+}
 ```
 
-The package ships a top-level [SETUP.md](./SETUP.md) specifically for that workflow.
+Important:
+
+- do not guess model ids
+- if using a custom OpenAI-compatible provider, verify `<baseUrl>/models`
+- if using PI models directly, verify `pi --list-models`
+- if `PI_CODING_AGENT_DIR` points at a repo-local PI home, make sure it is bootstrapped and contains `models.json`
+
+The harness now preflights those checks before starting a real run.
+
+## Important Config Fields
+
+Common fields in `pi.config.json`:
 
-If you want to wipe all harness-generated state and start over cleanly in a repo, run:
+- `taskFile`
+- `developerInstructionsFile`
+- `testerInstructionsFile`
+- `transport`
+- `adapterCommand`
+- `piModel`
+- `models`
+- `roleModels`
+- `commitMode`
+- `promptMode`
+- `testCommand`
+- `visualReviewEnabled`
+- `visualCaptureCommand`
+- `continueAfterSeconds`
+- `toolContinueAfterSeconds`
+- `noEventTimeoutSeconds`
+- `toolNoEventTimeoutSeconds`
+- `largeFileWarningLines`
+- `largeSpecWarningLines`
 
-```bash
-PI_CONFIG_FILE=pi.config.json pi-harness clear-history
-```
+Key defaults:
+
+- `transport`: `adapter`
+- `commitMode`: `agent`
+- `promptMode`: `compact`
+- `piTools`: `read,edit,write,find,ls,bash`
+- `continueAfterSeconds`: `300`
+- `toolContinueAfterSeconds`: `900`
+- `noEventTimeoutSeconds`: `900`
+- `toolNoEventTimeoutSeconds`: `1800`
+
+## Prompt and Tooling Behavior
+
+The package is optimized for local models by default:
+
+- prompts are compacted before handoff
+- changed-file lists and feedback excerpts are capped
+- prompts prefer `read` for source inspection
+- shell is intended for `git`, tests, and narrow diagnostics
+- the adapter warns on obvious oversized shell-based file reads
+- the supervisor emits large-file/spec warnings when touched files are getting risky
+
+This is deliberate. Large monolith files, huge e2e specs, and broad TODO items are one of the main causes of local-model drift and retry loops.
+
+Recommended repo shape:
+
+- keep TODO items very small and implementation-shaped
+- split giant stores/modules before they become constant edit hotspots
+- split ever-growing end-to-end specs into scenario files
+- keep the default `testCommand` to a bounded smoke check, not a multi-minute happy-path run
 
-The command removes configured harness history/runtime files and verifies that no configured history paths remain afterward.
+## Runtime Isolation And Recovery
 
-For prompt debugging, the harness also writes the exact assembled prompt for the current role to `.pi-last-prompt.txt` by default.
-For flow debugging, it also writes a machine-readable `.pi-last-iteration.json` summary with the selected task, tester verdict, commit-plan state, and terminal reason.
-For run isolation, the supervisor also maintains `.pi-runtime/active-run.json` and stores PI sessions plus per-run telemetry under `.pi-runtime/runs/<runId>/`.
+Recent versions of the package isolate each run more aggressively:
 
-## Generic Contracts
+- active ownership lock at `.pi-runtime/active-run.json`
+- per-run runtime directory under `.pi-runtime/runs/<runId>/`
+- per-run PI sessions and telemetry
+- `runId` added to telemetry
+- in-progress iteration state persisted before agent work starts
+- stale run locks recovered when the owning PID is gone
+- timeout cleanup kills the full spawned process group, not only the direct child
+- parent-death watchers shut down orphaned supervisor and adapter layers instead of letting them continue under `PPID 1`
 
-- `taskFile`: usually `TODOS.md`
-- `developerInstructionsFile`: per-project developer instructions
-- `testerInstructionsFile`: per-project tester instructions
-- `roleModels`: optional per-role model overrides
-- `commitMode`: `agent` by default, `plan` only for legacy harness-managed commit parsing
-- `promptMode`: `compact` by default
-- `testCommand`: fast verification command
-- `visualCaptureCommand`: project-defined screenshot capture command
-- `visualFeedbackFile`: latest visual-review handoff
-- `testerFeedbackFile`: latest tester-review handoff
+That is meant to prevent orphaned timed-out agents or concurrent supervisors from corrupting shared state.
 
-For unattended loops, keep `testCommand` fast and bounded, such as a smoke suite. Long real-time Playwright happy-path specs belong in an explicit nightly or post-run lane, not the default developer/tester inner loop.
+## Debugging Artifacts
 
-Keep TODO items extremely small and implementation-shaped when using weaker local models. Broad tasks tend to produce much longer turns, more retries, and more tester drift than narrow one-step tasks.
+Useful files during a run:
 
-The adapter heartbeat is PI-RPC-event based. Streaming shell output does not count as progress on its own, so long-running tools should rely on the tool-aware watchdog thresholds rather than terminal streaming.
+- `.pi-last-prompt.txt`
+  Exact assembled prompt for the current role.
+- `.pi-last-output.txt`
+  Latest agent output snapshot.
+- `.pi-last-verification.txt`
+  Latest verification output snapshot.
+- `.pi-last-iteration.json`
+  Structured summary of the last completed iteration.
+- `.pi-state.json`
+  Persistent harness state, including in-progress iteration data.
+- `pi.log`
+  Main run log.
+- `pi_telemetry.jsonl`
+- `pi_telemetry.csv`
+- `.pi-runtime/active-run.json`
+- `.pi-runtime/runs/<runId>/...`
 
-The supervisor now enforces single-run ownership per repo/config. If a stale run crashed mid-iteration, the next run recovers the unfinished iteration number from `.pi-state.json` instead of silently rolling forward.
+`pi-harness report` summarizes recent telemetry and surfaces things like terminal reasons and large-file warnings.
 
-`piModel` remains the default text model, but you can override specific roles with `roleModels` such as `developer`, `developerRetry`, `developerFix`, `tester`, and `visualReview`. `testerCommit` is only relevant if you opt back into `commitMode: "plan"`.
+## Visual Review Contract
 
-By default, successful tester passes should stage and create the commit directly in the same PI turn. The old commit-plan parsing flow is still available as `commitMode: "plan"`, but it is now a compatibility mode rather than the default.
+Visual review is optional and generic. The harness does not know how to navigate your app.
 
-Prompt/context handoff is compact by default. The harness now caps prior feedback excerpts, changed-file lists, verification excerpts, and prompt note handoff. If needed, tune `maxPromptChangedFiles`, `maxVisualFeedbackLines`, `maxTesterFeedbackLines`, `maxPromptNotesLines`, and `maxVerificationExcerptLines`.
+If enabled, your repo must provide a real screenshot capture command that writes a manifest under the configured capture directory. The manifest shape is documented in [docs/PI_SUPERVISOR.md](./docs/PI_SUPERVISOR.md).
 
-The default coding tool mix is now safer for local models: `read,edit,write,find,ls,bash`. Prompts explicitly steer source inspection toward `read` and reserve shell usage for `git`, tests, and narrow diagnostics.
+Visual review should be used as a periodic audit, not as the default inner-loop gate.
+
+## Resetting Harness State
+
+If you want to wipe harness-generated state and start fresh:
 
-The harness also emits lightweight large-file warnings for touched source/spec files and carries them into `.pi-last-iteration.json`, `pi-harness report`, and relevant prompts. Tune `largeFileWarningLines` and `largeSpecWarningLines` if needed.
+```bash
+PI_CONFIG_FILE=pi.config.json pi-harness clear-history
+```
+
+That clears configured harness runtime/history artifacts and verifies they are gone. It does not remove project source files.
+
+## Docs
+
+- [SETUP.md](./SETUP.md)
+  Agent-facing setup instructions for consuming repos.
+- [docs/PI_SUPERVISOR.md](./docs/PI_SUPERVISOR.md)
+  More detailed flow, adapter, and runtime documentation.
+- [templates/PROJECT_SETUP.md](./templates/PROJECT_SETUP.md)
+  Minimal consuming-repo layout summary.
+
+## Development
+
+In this package repo:
+
+```bash
+npm run check
+npm test
+```
 
-The harness expects screenshot capture to produce a `manifest.json` plus image files under the configured visual capture directory.
+The package requires Node `>=20`.

package/docs/PI_SUPERVISOR.md

@@ -222,6 +222,7 @@ The built-in adapter mitigates obvious local loops by watching PI RPC tool event
 - a soft `continue` can be sent after inactivity
 - a separate tool-aware watchdog can tolerate long-running `bash` or browser work without treating the turn as dead
 - a hard no-event timeout aborts a wedged turn instead of hanging indefinitely
+- parent-loss shutdown tears down the owned supervisor/adapter/PI child tree instead of allowing orphaned background runs
 
 Important: terminal streaming does not reset the heartbeat by itself. The watchdog keys off PI RPC events and active tool state, not raw shell output.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sebastianandreasson/pi-autonomous-agents",
   "private": false,
-  "version": "0.5.0",
+  "version": "0.5.2",
   "type": "module",
   "description": "Portable unattended PI harness for developer/tester/visual-review loops.",
   "license": "MIT",
@@ -16,8 +16,8 @@
     "pi-harness": "./src/cli.mjs"
   },
   "scripts": {
-    "check": "node --check src/cli.mjs && node --check src/pi-clear-history.mjs && node --check src/pi-client.mjs && node --check src/pi-config.mjs && node --check src/pi-flow.mjs && node --check src/pi-heartbeat.mjs && node --check src/pi-history.mjs && node --check src/pi-preflight.mjs && node --check src/pi-prompts.mjs && node --check src/pi-repo.mjs && node --check src/pi-report.mjs && node --check src/pi-rpc-adapter.mjs && node --check src/pi-supervisor.mjs && node --check src/pi-telemetry.mjs && node --check src/pi-visual-once.mjs && node --check src/pi-visual-review.mjs && node --check src/index.mjs && node --check test/pi-heartbeat.test.mjs && node --check test/pi-role-models.test.mjs && node --check test/pi-flow.test.mjs && node --check test/pi-history.test.mjs && node --check test/pi-prompts.test.mjs && node --check test/pi-preflight.test.mjs && node --check test/pi-repo.test.mjs && node --check test/pi-telemetry.test.mjs",
-    "test": "node --test test/pi-heartbeat.test.mjs test/pi-role-models.test.mjs test/pi-flow.test.mjs test/pi-history.test.mjs test/pi-prompts.test.mjs test/pi-preflight.test.mjs test/pi-repo.test.mjs test/pi-telemetry.test.mjs"
+    "check": "node --check src/cli.mjs && node --check src/pi-clear-history.mjs && node --check src/pi-client.mjs && node --check src/pi-config.mjs && node --check src/pi-flow.mjs && node --check src/pi-heartbeat.mjs && node --check src/pi-history.mjs && node --check src/pi-preflight.mjs && node --check src/pi-prompts.mjs && node --check src/pi-repo.mjs && node --check src/pi-report.mjs && node --check src/pi-rpc-adapter.mjs && node --check src/pi-supervisor.mjs && node --check src/pi-telemetry.mjs && node --check src/pi-visual-once.mjs && node --check src/pi-visual-review.mjs && node --check src/index.mjs && node --check test/pi-heartbeat.test.mjs && node --check test/pi-lifecycle.test.mjs && node --check test/pi-role-models.test.mjs && node --check test/pi-flow.test.mjs && node --check test/pi-history.test.mjs && node --check test/pi-prompts.test.mjs && node --check test/pi-preflight.test.mjs && node --check test/pi-repo.test.mjs && node --check test/pi-telemetry.test.mjs && node --check test/fixtures/fake-pi.mjs",
+    "test": "node --test test/pi-heartbeat.test.mjs test/pi-lifecycle.test.mjs test/pi-role-models.test.mjs test/pi-flow.test.mjs test/pi-history.test.mjs test/pi-prompts.test.mjs test/pi-preflight.test.mjs test/pi-repo.test.mjs test/pi-telemetry.test.mjs"
   },
   "files": [
     "src",

package/src/cli.mjs

@@ -4,6 +4,11 @@ import path from 'node:path'
 import { spawn } from 'node:child_process'
 import process from 'node:process'
 import { fileURLToPath } from 'node:url'
+import {
+  registerOwnedChildProcess,
+  signalChildProcess,
+  watchParentProcess,
+} from './pi-repo.mjs'
 
 const scriptDir = path.dirname(fileURLToPath(import.meta.url))
 
@@ -36,10 +41,53 @@ function main() {
     env: process.env,
     stdio: 'inherit',
   })
+  registerOwnedChildProcess(child)
+
+  let shuttingDown = false
+  let forceKillTimer = null
+  const stopWatchingParent = watchParentProcess(() => {
+    shutdown({
+      signal: 'SIGTERM',
+      exitCode: 1,
+    })
+  })
+
+  function shutdown({
+    signal,
+    exitCode,
+  }) {
+    if (shuttingDown) {
+      return
+    }
+
+    shuttingDown = true
+    stopWatchingParent()
+    signalChildProcess(child.pid, signal)
+    forceKillTimer = setTimeout(() => {
+      signalChildProcess(child.pid, 'SIGKILL')
+    }, 1000)
+    if (typeof forceKillTimer.unref === 'function') {
+      forceKillTimer.unref()
+    }
+    process.exitCode = exitCode
+  }
+
+  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+    process.on(signal, () => {
+      shutdown({
+        signal,
+        exitCode: 128,
+      })
+    })
+  }
 
   child.on('exit', (code, signal) => {
+    stopWatchingParent()
+    if (forceKillTimer) {
+      clearTimeout(forceKillTimer)
+    }
     if (signal) {
-      process.kill(process.pid, signal)
+      process.exitCode = 128
       return
     }
     process.exitCode = code ?? 1

package/src/pi-repo.mjs

@@ -114,6 +114,57 @@ export function isProcessRunning(pid) {
   }
 }
 
+const ownedChildren = new Map()
+
+export function registerOwnedChildProcess(child, options = {}) {
+  const pid = normalizePid(child?.pid)
+  if (pid <= 0) {
+    return () => {}
+  }
+
+  const entry = {
+    useProcessGroup: options.useProcessGroup === true && process.platform !== 'win32',
+  }
+  ownedChildren.set(pid, entry)
+
+  const unregister = () => {
+    ownedChildren.delete(pid)
+  }
+
+  if (typeof child?.once === 'function') {
+    child.once('exit', unregister)
+    child.once('close', unregister)
+  }
+
+  return unregister
+}
+
+export function signalChildProcess(pid, signal, options = {}) {
+  const normalizedPid = normalizePid(pid)
+  if (normalizedPid <= 0) {
+    return false
+  }
+
+  try {
+    if (options.useProcessGroup === true && process.platform !== 'win32') {
+      process.kill(-normalizedPid, signal)
+    } else {
+      process.kill(normalizedPid, signal)
+    }
+    return true
+  } catch {
+    return false
+  }
+}
+
+export function signalOwnedChildProcesses(signal) {
+  let handled = false
+  for (const [pid, entry] of [...ownedChildren.entries()]) {
+    handled = signalChildProcess(pid, signal, entry) || handled
+  }
+  return handled
+}
+
 export async function readJsonFile(filePath, fallback = null) {
   try {
     const raw = await fs.readFile(filePath, 'utf8')
@@ -211,20 +262,45 @@ export async function releaseRunLock(lockFile, runId) {
 }
 
 export function signalProcessTree(pid, signal) {
-  const normalizedPid = normalizePid(pid)
-  if (normalizedPid <= 0) {
-    return false
+  return signalChildProcess(pid, signal, { useProcessGroup: true })
+}
+
+export function watchParentProcess(onParentExit, options = {}) {
+  const expectedParentPid = normalizePid(options.parentPid ?? process.ppid)
+  if (expectedParentPid <= 0 || typeof onParentExit !== 'function') {
+    return () => {}
   }
 
-  try {
-    if (process.platform !== 'win32') {
-      process.kill(-normalizedPid, signal)
-    } else {
-      process.kill(normalizedPid, signal)
+  let active = true
+  const intervalMs = Number.isFinite(Number(options.intervalMs))
+    ? Math.max(100, Number(options.intervalMs))
+    : 1000
+
+  const interval = setInterval(() => {
+    if (!active) {
+      return
     }
-    return true
-  } catch {
-    return false
+
+    const currentParentPid = normalizePid(process.ppid)
+    if (currentParentPid === expectedParentPid && currentParentPid > 1) {
+      return
+    }
+
+    active = false
+    clearInterval(interval)
+    onParentExit({
+      expectedParentPid,
+      currentParentPid,
+    })
+  }, intervalMs)
+
+  if (typeof interval.unref === 'function') {
+    interval.unref()
+  }
+
+  return () => {
+    active = false
+    clearInterval(interval)
   }
 }
 
@@ -474,6 +550,9 @@ export async function runShellCommand({
       detached: process.platform !== 'win32',
       stdio: ['pipe', 'pipe', 'pipe'],
     })
+    const unregisterChild = registerOwnedChildProcess(child, {
+      useProcessGroup: process.platform !== 'win32',
+    })
 
     let stdout = ''
     let stderr = ''
@@ -506,6 +585,7 @@ export async function runShellCommand({
     })
 
     child.on('error', (error) => {
+      unregisterChild()
       if (killTimer) {
         clearTimeout(killTimer)
       }
@@ -524,6 +604,7 @@ export async function runShellCommand({
     })
 
     child.on('close', (code) => {
+      unregisterChild()
       if (killTimer) {
         clearTimeout(killTimer)
       }

package/src/pi-rpc-adapter.mjs

@@ -10,7 +10,12 @@ import {
   getHeartbeatDecision,
   resolveHeartbeatConfig,
 } from './pi-heartbeat.mjs'
-import { signalProcessTree } from './pi-repo.mjs'
+import {
+  registerOwnedChildProcess,
+  signalOwnedChildProcesses,
+  signalProcessTree,
+  watchParentProcess,
+} from './pi-repo.mjs'
 
 function createJsonlReader(stream, onLine) {
   const rl = createInterface({ input: stream })
@@ -155,6 +160,9 @@ async function run() {
     detached: process.platform !== 'win32',
     stdio: ['pipe', 'pipe', 'pipe'],
   })
+  registerOwnedChildProcess(child, {
+    useProcessGroup: process.platform !== 'win32',
+  })
 
   let stderr = ''
   const events = []
@@ -197,6 +205,36 @@ async function run() {
   let continueAttempted = false
   let continueAccepted = false
   let continueRejected = false
+  let shutdownRequested = false
+  let shutdownReason = ''
+  let shutdownEscalationTimer = null
+
+  const requestShutdown = (reason, signal = 'SIGTERM') => {
+    if (shutdownRequested) {
+      return
+    }
+
+    shutdownRequested = true
+    shutdownReason = String(reason ?? 'adapter_shutdown')
+    closeAssistantLine()
+    signalOwnedChildProcesses(signal)
+    shutdownEscalationTimer = setTimeout(() => {
+      signalOwnedChildProcesses('SIGKILL')
+    }, 1000)
+    if (typeof shutdownEscalationTimer.unref === 'function') {
+      shutdownEscalationTimer.unref()
+    }
+  }
+
+  const stopWatchingParent = watchParentProcess(() => {
+    requestShutdown('parent_exit', 'SIGTERM')
+  })
+
+  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+    process.on(signal, () => {
+      requestShutdown(signal, signal)
+    })
+  }
 
   const writeLive = (text) => {
     if (!streamTerminal) {
@@ -460,6 +498,26 @@ async function run() {
 
     await waitForAgentEnd()
 
+    if (shutdownRequested) {
+      console.log(JSON.stringify({
+        sessionId: request.sessionId ?? '',
+        sessionFile: request.sessionFile ?? '',
+        status: 'failed',
+        output: '',
+        notes: shutdownReason,
+        role: '',
+        model: requestedModel,
+        toolCalls: 0,
+        toolErrors: 0,
+        messageUpdates: 0,
+        stopReason: '',
+        loopDetected: false,
+        loopSignature: '',
+        terminalReason: 'adapter_shutdown',
+      }))
+      return
+    }
+
     if (heartbeatTimedOut) {
       const toolCalls = events.filter((event) => event.type === 'tool_execution_start').length
       const toolErrors = events.filter((event) => event.type === 'tool_execution_end' && event.isError).length
@@ -571,9 +629,13 @@ async function run() {
       terminalReason,
     }))
   } finally {
+    stopWatchingParent()
     if (heartbeatInterval) {
       clearInterval(heartbeatInterval)
     }
+    if (shutdownEscalationTimer) {
+      clearTimeout(shutdownEscalationTimer)
+    }
     stopReading()
     for (const current of pending.values()) {
       current.reject(new Error('RPC adapter shutting down'))

package/src/pi-supervisor.mjs

@@ -30,11 +30,13 @@ import {
   releaseRunLock,
   runVerification,
   runShellCommand,
+  signalOwnedChildProcesses,
   stageFiles,
   unstageFiles,
   updateRunLock,
   runVisualCapture,
   timestamp,
+  watchParentProcess,
   writeChangedFiles,
   writeSessionId,
   writeState,
@@ -49,13 +51,30 @@ import {
 import { runStartupPreflight } from './pi-preflight.mjs'
 
 let stopRequested = false
+let shutdownEscalationTimer = null
 
-process.on('SIGINT', () => {
+function requestStop() {
   stopRequested = true
-})
+  signalOwnedChildProcesses('SIGTERM')
+
+  if (!shutdownEscalationTimer) {
+    shutdownEscalationTimer = setTimeout(() => {
+      signalOwnedChildProcesses('SIGKILL')
+    }, 1000)
+    if (typeof shutdownEscalationTimer.unref === 'function') {
+      shutdownEscalationTimer.unref()
+    }
+  }
+}
 
-process.on('SIGTERM', () => {
-  stopRequested = true
+for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+  process.on(signal, () => {
+    requestStop()
+  })
+}
+
+const stopWatchingParent = watchParentProcess(() => {
+  requestStop()
 })
 
 function sleep(seconds) {
@@ -1728,6 +1747,10 @@ async function main() {
       await appendLog(config.logFile, 'Stop requested by signal')
     }
   } finally {
+    stopWatchingParent()
+    if (shutdownEscalationTimer) {
+      clearTimeout(shutdownEscalationTimer)
+    }
     await updateRunOwnership(config, {
       status: stopRequested ? 'stopped' : 'finished',
       heartbeatAt: timestamp(),