pi-minimal-dispatch 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+## 0.2.0 — 2026-10-23
+
+Requires pi ≥ 1.4.0 (the MCP reach rules the validator encodes are pi
+1.4.0's documented `--tools` semantics).
+
+- `dispatch` no longer spawns blind MCP lanes: with MCP enabled, a lane whose
+  `tools` allowlist names neither `codemode` nor `tool_search` is rejected at
+  the tool boundary — pi's `--tools` allowlist replaces the whole selection,
+  and a lane never reaches MCP tools through anything else unless the server
+  has `direct` exposure (which dispatch cannot know). Pass `codemode`/
+  `tool_search` in `tools` or set `mcp: false`.
+- `tools` now accepts only a plain allowlist: `+name`/`-name` modifier lists
+  (pi applies them to its default selection, silently granting
+  `bash`/`edit`/`write`) and empty lists are rejected.
+- README and docs/API.md document the reach rule and both reach recipes; the
+  `mcp` schema text no longer claims MCP tools "stay reachable" by default.
+
+- `lanes` gained `action: "wait"` (+ `waitSec`, default 300, max 3600):
+  holds one call open, re-deriving at the `pollMs` cadence, until every lane
+  is terminal — replaces blind sleep-then-status polling (which wakes late
+  after settles); times out as a normal status result, honors cancellation.
+
+## 0.1.0 — 2026-10-23
+
+Initial release. Requires pi ≥ 1.3.0 (1.4.0 recommended — see README).
+
+- `dispatch` tool: detached lane spawning (own process group, argv array, no
+  shell wrapper) with synchronous brief/slug validation, atomic wave-slug
+  claim, per-lane model/deadline/tool allowlist, and a parentless deadline
+  leash (`timeout -k`).
+- `lanes` tool: stateless status/kill/collect over a wave's manifest + JSON
+  event streams — derived state with failure causes, start-time-guarded PID
+  liveness, TERM→KILL group kill with tombstones, and suspect-flagged
+  artifact collection.
+- Safe defaults: lanes run read-only (`read,grep,find,ls`) unless granted
+  more via `tools`, never load skills (`-ns`), and never receive the
+  `dispatch` tool themselves (child marker).
+- Statusbar line and `/lanes` command (TUI/RPC modes).
+- Configuration: user/project JSON files with per-call parameter precedence.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mike Cheung
+
+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,190 @@
-# Temporary Holding Version
+# pi-minimal-dispatch
 
-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.
+Minimal detached lane dispatch with **visible state** for the
+[pi coding agent](https://pi.dev) — two tools, one manifest, no framework.
+
+Dispatch sub-agents from a pi session without blocking it. Lanes run as
+detached `pi --mode json` processes in their own process groups, survive the
+dispatcher's death, and report live state derived from their event streams —
+never guessed from empty files.
+
+```
+wave 'survey':
+  docs   · running · 2 turns · tok 5703in/90out, $0.0009 · stop:toolUse · last 3.1s ago
+  review · settled · 4 turns · tok 12021in/310out, $0.0041 · stop:stop · last 12s ago
+```
+
+## Why
+
+Other pi subagent extensions run children inside the dispatcher's process and
+die with it — or need a server to keep them alive. **pi-minimal-dispatch lanes
+are plain `pi --mode json` processes in their own process groups that outlive
+the dispatcher, observable as plain files, collectible by any later session.**
+
+- `dispatch` returns the moment lanes are spawned — the dispatcher keeps working
+- **the deadline leash is GNU `timeout -k` around each process** — it fires even
+  after the dispatcher has exited
+- a later session re-adopts any wave from its manifest: `status`, `wait`, `kill`, `collect`
+- the final text is a file on disk (`<wave>-<name>.md`), not a block pasted back
+  into the parent's context
+
+It replaces hand-written bash dispatch (`pi --print @brief > out.md &`), which
+leaves the dispatcher blind while lanes run: the artifact stays empty until the
+lane exits (working and hung look identical), killing means signaling a wrapper
+PID of unclear ownership, a mangled spawn line dies silently, and truncation,
+crash, and never-started are indistinguishable after the fact.
+
+## Requirements
+
+- pi ≥ 1.4.0
+- **macOS or Linux** — Windows is not supported (the extension relies on POSIX
+  process groups, `ps`, and `timeout`)
+- GNU `timeout`: preinstalled on Linux; on macOS install it with
+  `brew install coreutils` (or configure `timeoutBin: "gtimeout"` — see
+  [Configuration](#configuration))
+- `ps` with `-o lstart=` (procps on Linux, built-in on macOS): standard on both
+- Lanes resolve the pi binary from the dispatcher's `PATH` (configurable)
+
+## Install
+
+```bash
+pi install npm:pi-minimal-dispatch                         # official (registry)
+pi install git:github.com/zhtmike/pi-minimal-dispatch      # tracks main — between releases
+pi -e ./src/index.ts                                       # try it for one invocation
+```
+
+## Try this first
+
+Write one brief file per lane (the lane's whole prompt — its goal, scope, and
+expected deliverable), then ask in plain language:
+
+```text
+Dispatch two lanes: docs summarizes the request-handling module, review audits src/auth.
+Wait for them to settle and collect the artifacts.
+```
+
+pi decides when to call the tools. A real session looks like:
+
+```text
+> dispatch  wave="survey" lanes=[{name:"docs", briefPath:".pi/work/survey-docs-brief.md",
+            model:"zai/glm-5.3-flash", mcp:false},
+            {name:"review", briefPath:".pi/work/survey-review-brief.md", mcp:false}]
+  wave 'survey' dispatched — 2/2 lanes spawned
+    docs: pid 99015 (deadline 900s)
+    review: pid 99016 (deadline 900s)
+  manifest: /abs/path/to/.pi/work/survey-manifest.json
+
+> lanes     wave="survey" action="wait"
+  docs · settled · 2 turns · tok 5703in/90out, $0.0009 · stop:stop · last 0.8s ago
+  review · settled · 4 turns · tok 12021in/310out, $0.0041 · stop:stop · last 2.1s ago
+
+> lanes     wave="survey" action="collect"
+  collect wave 'survey':
+    docs: /abs/path/to/.pi/work/survey-docs.md stop:stop
+    review: /abs/path/to/.pi/work/survey-review.md stop:stop
+```
+
+The ceremony is *write briefs → `dispatch` → `lanes wait` (or poll `status`) →
+`collect` → clean up*. For a quick single task: dispatch one lane and let a
+single `wait` call hold open until it settles — no sleep-then-poll guessing,
+no waking late after a settle. `dispatch` itself never blocks; waiting is an
+explicit, bounded `lanes` call (`waitSec`, default 300, max 3600) that returns
+the status table as soon as a poll finds every lane `settled`/`failed`
+(within one `pollMs`).
+
+**Steering** is kill + redispatch: briefs are files, so refine the brief and run
+a new wave (slugs are single-use). **Hang detection**: `lastEventAgeSec` is the
+signal — no event growth for ~2× the lane's normal turn latency ⇒ `kill` and
+redispatch.
+
+## API
+
+Two tools — full parameter, output, and configuration reference in
+[docs/API.md](docs/API.md).
+
+- **`dispatch`** `{wave, lanes[], workDir?}` — validate briefs and slugs, claim
+  the wave slug atomically, spawn every lane detached in its own process
+  group, return in under a second. Per-lane: `model`, `deadlineSec`, `tools`,
+  `noExtensions`, `mcp`.
+- **`lanes`** `{wave, action?, waitSec?, workDir?}` — stateless `status` /
+  `wait` / `kill` / `collect` over the wave's manifest; any session can re-adopt
+  a wave, including after the dispatcher exited.
+
+**Web/MCP reach**: the default lane is offline. MCP servers connecting grants
+nothing by themselves — a lane reaches their tools only through `codemode` or
+`tool_search` named in its `tools` (`codemode` scripts and `tool_search` wait
+for the servers they need; an `mcp__server__*` entry declares tools directly
+only when the server has `direct` exposure in `mcp.json`, so it is a scope,
+not a route). A lane that leaves MCP enabled without `codemode`/`tool_search`
+in `tools` would run blind, so `dispatch` rejects it — pass a route or set
+`mcp: false` (servers never connect). Entries reach pi verbatim, no shell
+quoting: `tools: "read,grep,find,ls,codemode"`. Plain names/patterns only:
+`+name`/`-name` modifier lists (which pi applies to its default selection,
+silently granting `bash`/`edit`/`write`) and empty lists are rejected too.
+
+## Configuration
+
+The lane protocol is fixed (`--mode json --no-session -ns` — lanes never load
+skills); every variable knob is configurable. Defaults come from the
+extension; user config `~/.pi/agent/pi-minimal-dispatch.json` and project
+config `.pi/pi-minimal-dispatch.json` override them, and per-call parameters
+win last: `workDir`, `deadlineSec` (900), `killGraceMs` (5000), `pollMs`
+(2000), `piBin`, `timeoutBin` (set `"gtimeout"` when coreutils isn't linked
+on macOS). Invalid files fail loudly at the next tool call. Full table and
+precedence rules: [docs/API.md](docs/API.md#configuration).
+
+## Status bar & `/lanes`
+
+While any tracked lane runs, the footer shows one line — e.g. `lanes: 2 running · 1 settled`
+— updated at the `pollMs` cadence and cleared when nothing is in flight.
+`/lanes` (optionally `/lanes <wave>`) prints the full status table for waves
+seen this session — an untracked wave name is resolved from the default
+workDir — and completes wave names. Both are TUI conveniences over the same
+derived state the `lanes` tool reports.
+
+## State model
+
+Each lane's status is derived on every call from its event stream, PID
+liveness (guarded by process start-time — a reused PID is never signaled),
+and the deadline. Never stored, never stale. `settled` means the
+`agent_settled` event was seen — **success is `collect` with
+`suspect: false`**; a death after the deadline is labeled `deadline` even
+when the process crashed. The statusbar and `/lanes` are TUI/RPC-only —
+`--print`/`--mode json` sessions see status through the `lanes` tool alone.
+
+| State | Meaning |
+|---|---|
+| `starting` | spawned, no session header yet |
+| `running` | events flowing (`overdue: true` once past deadline) |
+| `settled` | `agent_settled` emitted (any stop reason — success is `collect` with `suspect: false`) |
+| `failed` | cause: `spawn` (synchronous, nothing ran) · `killed` (tombstoned) · `deadline` (leash fired, even parentless) · `crashed` (`.err` tail attached) |
+
+## How it works
+
+- **Lane**: detached via an argv array (no `sh -c` wrapper to mangle) in its
+  own process group; the `timeout` wrapper is the deadline leash.
+- **Registry**: `<workDir>/<wave>-manifest.json`, created atomically (`wx` —
+  slug collisions and concurrent same-wave dispatches fail loudly). Plain
+  JSON on disk: pids, process start-times, deadlines, brief paths — everything
+  a later session needs to re-adopt the wave. The extension never deletes
+  wave artifacts; cleanup stays an explicit step.
+- **State**: derived on every call — never stored, never stale.
+
+## Testing
+
+```bash
+node tests/config.test.ts    # configuration precedence + validation
+node tests/derive.test.ts    # state derivation, wait loop, liveness guard, event parsing
+node tests/format.test.ts    # presentation formatters
+node tests/lane.test.ts      # slugs, briefs, argv, lane tool-contract validation
+bash tests/prove.sh          # integration: replays a live wave (bills models)
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Agent instructions live in
+[AGENTS.md](AGENTS.md).
+
+## License
+
+[MIT](LICENSE)

package/docs/API.md

@@ -0,0 +1,163 @@
+# API reference
+
+Full reference for the two tools, their structured outputs, and configuration.
+The lean overview lives in the [README](../README.md); the model-facing
+descriptions live in the tool schemas in [`src/index.ts`](../src/index.ts) —
+this document is the human-facing copy and must stay in sync with both.
+
+## `dispatch`
+
+Spawns a wave and returns in under a second. Lanes run
+`<timeoutBin> -k <graceSec> <deadlineSec> <piBin> --mode json --no-session -ns [flags] @<brief>`
+detached — the `--mode json --no-session -ns` triple is the fixed lane
+protocol (fresh process, JSON event stream, skills never loaded); `-k`
+escalates a caught SIGTERM to SIGKILL so a stalled dispose cannot outlive
+the leash. Events stream to `<workDir>/<wave>-<name>.events.jsonl`.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `wave` | string | — | Wave slug: `kebab-case`, max 64 chars, must not exist in `workDir` |
+| `lanes` | array | — | One entry per lane (min 1); lane slugs unique within the wave |
+| `lanes[].name` | string | — | Lane slug: `kebab-case`, max 64 chars |
+| `lanes[].briefPath` | string | — | Path to the lane's brief file (its `@file` prompt) |
+| `lanes[].model` | string? | pi default | Pin a model id; omitted: pi's **configured default model** — not the dispatcher session's active model |
+| `lanes[].deadlineSec` | number? | `deadlineSec` config (900) | Leash in seconds; holds even if the dispatcher is gone. Minimum 1 |
+| `lanes[].tools` | string? | `read,grep,find,ls` | Tool allowlist for `--tools` — plain names or `*` patterns; no `+name`/`-name` modifiers, no shell quoting, not empty. Add `bash` when a lane must run commands (bash can still invoke git). With MCP enabled, reach requires `codemode` or `tool_search` here — see [MCP and web reach](#mcp-and-web-reach) |
+| `lanes[].noExtensions` | boolean? | false | Pass `-ne` (drop extensions incl. MCP in the lane) |
+| `lanes[].mcp` | boolean? | enabled | Set `false` to pass `--no-mcp` (no MCP servers connect). With MCP enabled, `tools` must name `codemode` or `tool_search` or the call is rejected — servers connecting alone never declares MCP tools to the lane |
+| `workDir` | string? | `workDir` config (`.pi/work`) | Directory for manifest, events, and artifacts |
+
+**Result:** text summary plus `structuredContent` — `{ wave, manifestPath, lanes[] }`
+with each lane's pid, paths, and deadline. Spawned lanes stream events
+immediately; a lane that failed to spawn appears as `SPAWN ERROR: …`.
+
+**Errors** (the whole call fails, zero lanes spawned, no slug claimed):
+a brief file missing (all missing paths listed) · malformed or duplicate slugs ·
+`tools` that is not a plain allowlist (`+name`/`-name` modifiers, shell quoting,
+or an empty list) · a lane leaving MCP enabled while its `tools` names neither
+`codemode` nor `tool_search` · wave slug already exists · `timeoutBin`/`piBin`
+not found on `PATH`.
+
+### MCP and web reach
+
+`mcp` only controls whether servers connect; it never grants reach. A plain
+`--tools` allowlist replaces the whole selection, and pi declares a server's
+tools to the lane only through the routes below — anything else leaves
+connected servers as unreachable dead weight, so `dispatch` rejects a lane
+that leaves MCP enabled without one:
+
+- `codemode` — scripts reach every non-hidden server's tools and wait for the
+  servers they name: `tools: "read,grep,find,ls,codemode"`
+- `tool_search` — loads non-direct MCP tools on demand, waiting for all
+  servers when it runs
+
+An `mcp__server__*` entry is a *scope*, not a route: it keeps only that
+server's tools registered (for `codemode`/`tool_search` to use) and declares
+them directly **only when the server or tool has `direct` exposure** in
+`mcp.json` (`"exposure": "direct"` / `toolExposure`) — dispatch cannot know
+the lane's server exposures, so `mcp__` entries alone never satisfy the rule.
+For direct-exposure servers: `tools: "read,grep,find,ls,codemode,mcp__server__*"`
+declares the tools and keeps them callable from scripts. The MCP resource
+tools (`list_mcp_resources`, `list_mcp_resource_templates`,
+`read_mcp_resource`) are exposure-gated the same way and do not count either.
+
+Lanes that need no MCP set `mcp: false`. Entries reach pi verbatim (the
+allowlist is one argv value — no shell quoting), and `+name`/`-name` modifier
+lists are rejected because pi applies them to its default selection, silently
+granting `bash`/`edit`/`write`.
+
+**Recursion guard:** lanes run with `PI_MINIMAL_DISPATCH_CHILD=1` in their
+environment, and the extension's factory stays out of any process carrying that
+marker — a lane never gets the `dispatch` tool. `-ne` (`noExtensions`) remains
+the switch that drops all extensions and MCP in a lane. Every lane in a call is
+spawned; the caller bounds the wave.
+
+## `lanes`
+
+Stateless: every call reads the manifest fresh, so any session — including a
+fresh one after the dispatcher exited — sees the same truth.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `wave` | string | — | Wave slug |
+| `action` | string? | `"status"` | `"status"` \| `"wait"` \| `"kill"` \| `"collect"` |
+| `waitSec` | number? | `300` | `wait` only: max seconds to hold the call open (1–3600) |
+| `workDir` | string? | `workDir` config (`.pi/work`) | Directory holding the manifest |
+
+### `status`
+
+Per-lane `structuredContent` entries. Note: `settled` only means the
+`agent_settled` event was seen — success is `collect` returning
+`suspect: false`.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `name` | string | lane slug |
+| `state` | string | `starting` \| `running` \| `settled` \| `failed` |
+| `cause` | string? | for `failed`: `spawn` · `killed` · `deadline` · `crashed` |
+| `overdue` | boolean? | alive past its deadline (leash misfire) — informational |
+| `turns` | number | turn count so far |
+| `usage` | object | run totals summed over assistant messages: `{input, output, cacheRead, cacheWrite, cost}` |
+| `stopReason` | string? | last assistant stop reason (`stop` is clean) |
+| `lastEventAgeSec` | number? | seconds since the events file last grew — the stuck-lane signal |
+| `spawnError` | string? | why a `spawn`-failed lane never started |
+| `errTail` | string? | last lines of `.err` for `crashed` lanes |
+
+### `wait`
+
+Holds the tool call open, re-reading the manifest and re-deriving state every
+`pollMs`, until every lane is terminal (`settled` or `failed`), `waitSec`
+(default 300, max 3600) elapses, or the call is cancelled — then returns
+exactly the `status` payload. A timeout is **not** an error: lanes still
+running show as `running`, and the caller waits again (or proceeds to
+`kill`/`collect`, which refuse running lanes as usual). This replaces
+sleep-then-status polling, which guesses the duration and wakes late after a
+settle. `dispatch` still returns in under a second — blocking is always this
+explicit, bounded observation call, and the deadline leash needs no observer.
+
+### `kill`
+
+SIGTERM to each eligible lane's process group (never a
+start-time-mismatched/reused PID; settled lanes skipped), SIGKILL after the
+`killGraceMs` config grace, then a manifest tombstone so the kill survives
+re-adoption. Idempotent; honors tool-call cancellation during the grace wait.
+
+### `collect`
+
+For each finished lane, writes the final assistant message (text blocks
+concatenated) to `<wave>-<name>.md`. Entries carry
+`{ name, artifact, suspect, stopReason }`; `suspect: true` when the lane
+failed, the message is empty, or the stop reason was not clean — treat such an
+artifact as **not done** and read the file only to judge it, don't paste it
+back into the conversation. A refused lane (still running / never spawned) is
+a **successful** tool result carrying a per-lane `reason`, not an error.
+
+## Configuration
+
+The lane protocol itself is fixed — every lane runs `--mode json --no-session
+-ns` (fresh process, JSON event stream, skills unloaded) — while every
+**variable** knob is configurable. JSON files, later wins:
+
+1. defaults (documented in the tables above)
+2. `<agent-dir>/pi-minimal-dispatch.json` — user level (`~/.pi/agent`, or `$PI_CODING_AGENT_DIR`)
+3. `.pi/pi-minimal-dispatch.json` — project level (working directory)
+4. per-call tool parameters
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `workDir` | string | `.pi/work` | Default wave directory |
+| `deadlineSec` | number | `900` | Default lane leash (integer ≥ 1) |
+| `killGraceMs` | number | `5000` | SIGTERM→SIGKILL grace in the `kill` action; also the leash's `timeout -k` escalation (integer ≥ 100) |
+| `pollMs` | number | `2000` | Statusbar poll interval (integer ≥ 100) |
+| `piBin` | string | `"pi"` | Lane pi binary, resolved from `PATH` |
+| `timeoutBin` | string | `"timeout"` | Leash binary — set `"gtimeout"` if coreutils isn't linked on macOS |
+
+```json
+{
+	"deadlineSec": 600,
+	"timeoutBin": "gtimeout"
+}
+```
+
+Invalid files fail loudly at the next tool call: the error names the file and
+the valid keys/values. Unknown keys are rejected.

package/package.json

@@ -1,6 +1,43 @@
 {
-  "name": "pi-minimal-dispatch",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "pi-minimal-dispatch",
+	"version": "0.2.0",
+	"description": "Minimal detached lane dispatch with visible state for the pi coding agent — dispatch/lanes tools over a manifest + JSON-event protocol",
+	"author": "Mike Cheung",
+	"keywords": [
+		"pi-package",
+		"pi",
+		"agent",
+		"subagent",
+		"dispatch",
+		"orchestration"
+	],
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/zhtmike/pi-minimal-dispatch.git"
+	},
+	"bugs": {
+		"url": "https://github.com/zhtmike/pi-minimal-dispatch/issues"
+	},
+	"homepage": "https://github.com/zhtmike/pi-minimal-dispatch#readme",
+	"type": "module",
+	"engines": {
+		"node": ">=22.19.0"
+	},
+	"scripts": {
+		"test": "node tests/config.test.ts && node tests/derive.test.ts && node tests/format.test.ts && node tests/lane.test.ts",
+		"prepublishOnly": "npm test"
+	},
+	"files": [
+		"src",
+		"docs",
+		"CHANGELOG.md"
+	],
+	"peerDependencies": {
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-coding-agent": "*"
+	},
+	"pi": {
+		"extensions": ["./src/index.ts"]
+	}
+}

package/src/config.ts

@@ -0,0 +1,96 @@
+/**
+ * pi-minimal-dispatch configuration.
+ *
+ * Precedence (later wins): built-in defaults < `<agent-dir>/pi-minimal-dispatch.json`
+ * < `.pi/pi-minimal-dispatch.json` < tool-call parameters.
+ * The agent directory follows `PI_CODING_AGENT_DIR`, defaulting to `~/.pi/agent`.
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+export type DispatchConfig = {
+	/** Default wave directory; the `workDir` tool parameter overrides. */
+	workDir: string;
+	/** Default lane deadline (seconds); the per-lane `deadlineSec` overrides. Minimum 1. */
+	deadlineSec: number;
+	/** Milliseconds between SIGTERM and SIGKILL in the `kill` action. Minimum 100. */
+	killGraceMs: number;
+	/** Statusbar poll interval in milliseconds. Minimum 100. */
+	pollMs: number;
+	/** Lane binary, resolved from PATH. */
+	piBin: string;
+	/** Deadline-leash binary (GNU coreutils `timeout`, or e.g. `gtimeout`). */
+	timeoutBin: string;
+};
+
+export const DEFAULT_CONFIG: DispatchConfig = {
+	workDir: ".pi/work",
+	deadlineSec: 900,
+	killGraceMs: 5000,
+	pollMs: 2000,
+	piBin: "pi",
+	timeoutBin: "timeout",
+};
+
+const CONFIG_NAME = "pi-minimal-dispatch.json";
+
+/** Numeric floors guarding against degenerate values (instant kills, busy loops). */
+const MINIMA: Partial<Record<keyof DispatchConfig, number>> = {
+	deadlineSec: 1,
+	killGraceMs: 100,
+	pollMs: 100,
+};
+
+function readConfigFile(file: string): Record<string, unknown> {
+	let raw: string;
+	try {
+		raw = fs.readFileSync(file, "utf8");
+	} catch (e: any) {
+		if (e.code === "ENOENT") return {};
+		throw e;
+	}
+	if (raw.trim() === "") return {};
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (e: any) {
+		throw new Error(`invalid JSON in ${file}: ${e.message}`);
+	}
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+		throw new Error(`invalid config in ${file}: expected a JSON object`);
+	}
+	return parsed as Record<string, unknown>;
+}
+
+function applyOverrides(cfg: DispatchConfig, overrides: Record<string, unknown>, source: string): DispatchConfig {
+	const known = new Set(Object.keys(DEFAULT_CONFIG));
+	for (const [key, value] of Object.entries(overrides)) {
+		if (!known.has(key)) {
+			throw new Error(`unknown config key '${key}' in ${source} — valid keys: ${[...known].join(", ")}`);
+		}
+		const minimum = MINIMA[key as keyof DispatchConfig];
+		if (minimum !== undefined) {
+			if (typeof value !== "number" || !Number.isInteger(value) || value < minimum) {
+				throw new Error(`config key '${key}' in ${source} must be an integer >= ${minimum}, got ${JSON.stringify(value)}`);
+			}
+		} else if (typeof value !== "string" || value === "") {
+			throw new Error(`config key '${key}' in ${source} must be a non-empty string, got ${JSON.stringify(value)}`);
+		}
+		(cfg as Record<string, unknown>)[key] = value;
+	}
+	return cfg;
+}
+
+/**
+ * Load the effective configuration: defaults, then user file, then project file.
+ * Throws with the offending file path and valid choices on any invalid input.
+ */
+export function loadConfig(projectRoot: string = process.cwd()): DispatchConfig {
+	const agentDir = process.env.PI_CODING_AGENT_DIR ?? path.join(os.homedir(), ".pi", "agent");
+	let cfg = { ...DEFAULT_CONFIG };
+	cfg = applyOverrides(cfg, readConfigFile(path.join(agentDir, CONFIG_NAME)), path.join(agentDir, CONFIG_NAME));
+	cfg = applyOverrides(cfg, readConfigFile(path.join(projectRoot, ".pi", CONFIG_NAME)), path.join(projectRoot, ".pi", CONFIG_NAME));
+	return cfg;
+}