@timqi/pier 0.1.0 → 0.1.1

package/dist/secrets.js

@@ -1,19 +1,9 @@
-// Layer-1 secret encryption: the credentials Pier must read by itself
-// (channel tokens, provider API keys, OAuth tokens) are stored as ciphertext
-// and pass through here. Two keys, standard envelope: a KEK from
-// `~/.pier/master.key` wraps a DEK, and only the DEK touches data — so
-// rotating the KEK rewrites one file and zero data rows. The KEK is either a
-// `vt://` record (decrypted through vt, one approval per process start) or a
-// raw key in the file (the no-vt fallback — same at-rest level as the
-// plaintext files it replaces, and the mode is the operator's explicit
-// choice, never a silent downgrade).
-//
-// Both keys live in `master.key` (JSON: kek, wrapped dek, dek id), not the
-// database: rotation is then a single atomic rename, with no crash window
-// where the file holds the new KEK and the database a DEK wrapped by the old
-// one. Layer 2 — secrets needing per-use approval — never passes through
-// here: those stay `vt://` strings Pier cannot read, and the agent runs vt
-// itself.
+// Layer-1 secret encryption for the credentials Pier must read by itself.
+// Standard envelope: a KEK from `master.key` (a `vt://` record, or a raw key in
+// file mode — the operator's explicit choice) wraps a DEK, and only the DEK
+// touches data, so rotating the KEK rewrites one file and zero rows. Both keys
+// live in that one file so rotation is a single atomic rename. Layer 2
+// (per-use approval) never passes here: the agent runs vt itself.
 import { spawn } from "node:child_process";
 import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
 import { chmodSync, readFileSync, renameSync, writeFileSync } from "node:fs";
@@ -22,6 +12,9 @@ import { pierPath } from "./paths.js";
 const log = logger("secrets");
 const KEY_BYTES = 32; // AES-256
 const IV_BYTES = 12; // GCM standard nonce
+/** Anything not matching predates sealing: honored as plaintext, and re-sealed
+ *  by whichever store owns the row. */
+export const isSealed = (blob) => /^v1:[0-9a-f]{8}:/.test(blob);
 export class Secrets {
     path;
     vt;
@@ -39,18 +32,12 @@ export class Secrets {
     get mode() {
         return this.#file ? (this.#file.kek.startsWith("vt://") ? "vt" : "file") : undefined;
     }
-    /** Why decrypt is refused right now — "" once unlocked. Shown in the
-     *  Console's Security tab, which is where a refused unlock gets repaired. */
     get lockedReason() {
         return this.#lockedReason;
     }
-    /**
-     * Load master.key — created on first boot, file mode, so an unattended
-     * start needs no ceremony; vt mode is entered later via rotate. Throws on a
-     * failed vt approval or a corrupt file, and remembers why: the process must
-     * keep serving (web is how the operator unlocks or repairs), but every
-     * refused decrypt names the reason instead of pretending to be empty.
-     */
+    /** Created on first boot in file mode, so an unattended start needs no
+     *  ceremony. Throws and remembers why: the process must keep serving (web is
+     *  how the operator repairs), and every refused decrypt names the reason. */
     async unlock() {
         try {
             let raw;
@@ -58,9 +45,8 @@ export class Secrets {
                 raw = readFileSync(this.path, "utf8");
             }
             catch (err) {
-                // Only a missing file means first boot. Any other read error (EACCES,
-                // EISDIR…) must not fall through to #create(), which would rename a
-                // fresh key over the existing one and destroy every sealed credential.
+                // Only ENOENT is first boot: any other error falling through to
+                // #create() would rename a fresh key over the existing one.
                 if (err.code !== "ENOENT")
                     throw err;
                 this.#file = this.#create();
@@ -98,12 +84,8 @@ export class Secrets {
             throw new Error(`sealed by unknown key ${dekId}, have ${file.dekId}`);
         return open(dek, rest.join(":"), `v1:${dekId}`).toString("utf8");
     }
-    /**
-     * New KEK, same DEK: every stored envelope stays valid. `mode` switches how
-     * the new KEK is protected (entering vt mode runs `vt create`, one
-     * approval); omitted, the current mode is kept. The rewrapped file lands by
-     * atomic rename — a crash leaves either the old working file or the new one.
-     */
+    /** New KEK, same DEK: every stored envelope stays valid. Omitted `mode`
+     *  keeps the current one. */
     async rotateKek(mode = this.mode ?? "file") {
         const { file } = this.#unlocked();
         const kek = randomBytes(KEY_BYTES);
@@ -119,16 +101,10 @@ export class Secrets {
         this.#file = next;
         log.info(`KEK rotated (${mode} mode, dek ${file.dekId} unchanged)`);
     }
-    /**
-     * What vt says about itself. A refused or impossible unlock is almost never
-     * Pier's fault — missing binary, no agent listening, config pointing
-     * elsewhere — and `lockedReason` only carries the last error. Read-only, so
-     * it is safe to run while locked; vt's own report is the repair instruction.
-     */
+    /** Read-only, safe while locked; vt's own report is the repair instruction. */
     doctor() {
         return this.vt.doctor();
     }
-    /** First boot: random KEK and DEK, file mode. */
     #create() {
         const kek = randomBytes(KEY_BYTES);
         const dekId = randomBytes(4).toString("hex");
@@ -170,8 +146,6 @@ function open(key, sealed, aad) {
     decipher.setAuthTag(tag);
     return Buffer.concat([decipher.update(ct), decipher.final()]);
 }
-/** The real vt CLI. Absent binary or denied approval both surface as the
- *  spawn/exit error — unlock() records it and the operator reads it. */
 const vtCli = {
     read: (record) => run("vt", ["read", record]),
     create: async (plaintext) => {
@@ -181,8 +155,7 @@ const vtCli = {
             throw new Error("vt create printed no vt:// record");
         return record;
     },
-    // Bounded: doctor probes an agent socket and a worker over the network, and
-    // a hung probe would leave the Console waiting on a diagnosis forever.
+    // doctor probes over the network; a hung probe would hang the Console.
     doctor: () => run("vt", ["doctor"], undefined, 15_000),
 };
 function run(cmd, args, stdin, timeoutMs) {

package/dist/service.js

@@ -1,32 +1,22 @@
-// The systemd user unit Pier writes for itself.
-//
-// A *user* unit, not a system one: Pier runs as you, reads your Pi
-// configuration and drives sessions in your own directories. As root or a
-// dedicated service user it would be an agent that cannot touch the files you
-// wanted it to work on.
-//
-// Writing this file is a command rather than a page of documentation to copy
-// because two of its lines are only knowable at runtime: the absolute path of
-// the node that is running (systemd starts with a minimal PATH, so a node
-// installed by fnm/nvm/asdf is not on it) and the absolute path of the
-// installed entry point.
+// The systemd *user* unit Pier writes for itself: Pier runs as you, so it can
+// touch the files you wanted it to work on. Written by a command because two
+// lines are only knowable at runtime — the absolute node (systemd's minimal
+// PATH has no fnm/nvm node) and the installed entry point.
 import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, rmdirSync, rmSync, writeFileSync } from "node:fs";
 import { homedir, userInfo } from "node:os";
 import { dirname, join } from "node:path";
 export const UNIT_NAME = "pier.service";
 const UPDATE_UNIT_NAME = "pier-update.service";
-/** `~/.config/systemd/user/pier.service` — where a user unit belongs. */
 export const unitPath = (home = homedir()) => join(home, ".config", "systemd", "user", UNIT_NAME);
-/** The drop-in Pier writes once and never touches again: what the unit may
- *  consume is the operator's call, not ours. */
+/** Written once and never touched again: what the unit may consume is the
+ *  operator's call. */
 export const limitsPath = (home = homedir()) => join(dirname(unitPath(home)), `${UNIT_NAME}.d`, "limits.conf");
-/** The oneshot that installs a new version, beside the unit it restarts. */
 export const updateUnitPath = (home = homedir()) => join(dirname(unitPath(home)), UPDATE_UNIT_NAME);
-/** Runtime-only effective state for the updater, regenerated before each run. */
+/** Regenerated before each updater run. */
 export const updateRuntimePath = (home = homedir()) => join(dirname(unitPath(home)), `${UPDATE_UNIT_NAME}.d`, "runtime.conf");
-/** Quote one systemd word. Percent is doubled because specifier expansion runs
- * after parsing; dollar is doubled only for command lines. */
+/** Percent is doubled because specifier expansion runs after parsing; dollar
+ *  only for command lines. */
 function quote(value, command = false) {
     if (/[\0\r\n]/.test(value))
         throw new Error("systemd values cannot contain control characters");
@@ -36,14 +26,9 @@ function quote(value, command = false) {
     return `"${escaped}"`;
 }
 const environment = (key, value) => `Environment=${quote(`${key}=${value}`)}`;
-/** The PATH both units carry: the recorded node first, then the shell that ran
- * the install (`pier service install` is typed in that shell, so its own PATH
- * *is* the login one), with the standard directories as a floor.
- *
- * Recorded at install rather than sourced from a login shell at start, which
- * would hand a dotfile the power to decide whether Pier boots and which node
- * npm installs into. Relative entries are dropped: they would resolve against
- * WorkingDirectory, which is not where the operator was standing. */
+/** Recorded at install rather than sourced from a login shell at start, which
+ *  would hand a dotfile the power to decide whether Pier boots. Relative
+ *  entries would resolve against WorkingDirectory, so they are dropped. */
 function pathEnv(execPath, shellPath) {
     const seen = new Set();
     return [dirname(execPath), ...(shellPath ?? "").split(":"), "/usr/local/bin", "/usr/bin", "/bin"]
@@ -86,8 +71,7 @@ SyslogIdentifier=pier
 WantedBy=default.target
 `;
 }
-/** The 0.0.1 unit did not record npm. This one-time bridge can only use npm
- * beside its recorded Node; a forced reinstall writes the exact executable. */
+/** A unit that recorded no npm: the bridge assumes npm beside its Node. */
 function legacyOptions(home) {
     const text = readFileSync(unitPath(home), "utf8");
     const start = text.match(/^ExecStart=(\S+) (\S+)$/m);
@@ -105,14 +89,9 @@ function legacyOptions(home) {
         ...(pierHome ? { pierHome } : {}),
     };
 }
-/** A separate cgroup snapshots the database, updates the exact npm
- * installation recorded at install time, and only then restarts Pier.
- *
- * Both slow steps run while the service is still up, so the downtime is one
- * stop and one start rather than the ~10s an install takes. The snapshot is
- * consistent on a live database — `VACUUM INTO` off a read-only connection
- * (db.ts) — and it still runs from the tree npm is about to replace, so the
- * copy carries the version whose schema it pairs with. */
+/** Snapshot and install run while the service is still up, so downtime is one
+ *  stop and one start. The snapshot runs from the tree npm is about to replace,
+ *  so the copy carries the version whose schema it pairs with. */
 export function renderUpdateUnit(options) {
     const { execPath, npmPath, entry, pierHome, shellPath } = options;
     const cli = join(dirname(entry), "cli.js");
@@ -140,12 +119,8 @@ ExecStart=systemctl --user stop ${UNIT_NAME}
 ExecStopPost=systemctl --user start ${UNIT_NAME}
 `;
 }
-/**
- * Sized as a share of the machine, not as "how much should Pier need": the
- * limit covers node, every subagent and every command a turn ran, and it
- * exists to protect the OS and sshd outside it. Written commented so the
- * operator tuning it can see what each line buys.
- */
+/** A share of the machine, not "how much Pier needs": the limit covers every
+ *  command a turn ran, and exists to protect the OS and sshd outside it. */
 function renderLimits() {
     return `[Service]
 # Soft ceiling: past this the kernel reclaims hard and lets the unit crawl
@@ -164,8 +139,6 @@ OOMScoreAdjust=200
 OOMPolicy=continue
 `;
 }
-/** A command failure is printed here and propagated by its caller. Linger is
- * the only deliberately best-effort step. */
 const runner = (say) => (argv) => {
     try {
         execFileSync(argv[0], argv.slice(1), { stdio: "pipe" });
@@ -202,8 +175,8 @@ export function install(options) {
     }
     if (!run(["systemctl", "--user", "daemon-reload"]))
         return false;
-    // Without lingering, the user manager stops at logout and takes every
-    // scheduled task with it. It can need a polkit prompt, hence best-effort.
+    // Without lingering the user manager stops at logout, taking every scheduled
+    // task with it. It can need a polkit prompt, hence best-effort.
     if (!run(["loginctl", "enable-linger", userInfo().username])) {
         say(`  run it yourself so Pier survives logout: loginctl enable-linger ${userInfo().username}`);
     }
@@ -218,20 +191,13 @@ export function install(options) {
     say(`started. The first run prints a password once: journalctl --user -u pier -e`);
     return true;
 }
-/**
- * Why the installed updater could not do its job, or `null` when nothing is
- * wrong. Checked while Pier is still alive, because the alternative is finding
- * out at the next restart, from a service that no longer starts.
- *
- * The absolute node and npm paths in the unit are deliberate — systemd's PATH
- * has neither — but they pin the unit to one directory of one version manager.
- * `fnm install 26 && fnm uninstall 24` leaves ExecStart naming a Node that is
- * gone; the running process survives (Linux keeps a deleted binary mapped),
- * so nothing would notice until the update, or the next boot, failed.
- */
+/** The absolute node and npm paths pin the unit to one version manager's
+ *  directory: `fnm uninstall 24` leaves ExecStart naming a Node that is gone,
+ *  and the running process survives it (Linux keeps a deleted binary mapped),
+ *  so nothing would notice until the next boot failed. */
 export function updaterProblem(home = homedir()) {
     if (!existsSync(unitPath(home)))
-        return null; // not a service install; nothing to check
+        return null; // not a service install
     const path = updateUnitPath(home);
     let unit;
     if (existsSync(path)) {
@@ -243,9 +209,7 @@ export function updaterProblem(home = homedir()) {
         }
     }
     else {
-        // A 0.0.1 install: startUpdate generates the updater from the main unit,
-        // so a missing file is only a problem when that bridge cannot either —
-        // and the generated text gets the same executable check below.
+        // startUpdate generates a missing updater from the main unit; check that text.
         try {
             unit = renderUpdateUnit(legacyOptions(home));
         }
@@ -253,10 +217,8 @@ export function updaterProblem(home = homedir()) {
             return `${UPDATE_UNIT_NAME} is missing — run: pier service install --force`;
         }
     }
-    // The one line that names both executables, quoted and escaped by quote().
-    // Unparseable means hand-edited, which is not this function's business to
-    // judge; the escaping is undone before existsSync sees a path (a `%` or `$`
-    // in it would otherwise read as gone on a working updater).
+    // Unparseable means hand-edited, not this function's to judge. Unescaped
+    // before existsSync: a `%` or `$` in the path would otherwise read as gone.
     const install = unit.match(/^ExecStart="((?:\\.|[^"\r\n])+)" "((?:\\.|[^"\r\n])+)" install -g/m);
     if (!install)
         return null;
@@ -278,16 +240,14 @@ function runningPierHome(home) {
             ?.slice("PIER_HOME=".length);
         return value || join(home, ".pier");
     }
-    // Installed but stopped: the unit file records any override (quoted and
-    // escaped since 0.0.2, bare in the 0.0.1 shape) — undo quote()'s escaping
-    // or the drop-in would carry `%%`/`\\"` into a real path.
+    // Installed but stopped: the unit records any override, quoted or bare;
+    // undo quote()'s escaping or the drop-in would carry `%%` into a real path.
     const raw = readFileSync(unitPath(home), "utf8")
         .match(/^Environment="?PIER_HOME=((?:\\.|[^"\r\n])+)"?$/m)?.[1];
     const fromUnit = raw?.replaceAll("%%", "%").replace(/\\(.)/g, "$1");
     return fromUnit || join(home, ".pier");
 }
-/** Start the updater recorded at install time. Its tiny drop-in captures the
- * running service's effective home, including an operator override. */
+/** The drop-in captures the running service's effective home, override included. */
 export function startUpdate(options) {
     const { home = homedir(), say } = options;
     const run = options.exec ?? runner(say);
@@ -334,8 +294,6 @@ export function uninstall(home = homedir(), say = console.log, exec) {
         }
     }
     const ok = run(["systemctl", "--user", "daemon-reload"]);
-    // Left alone on purpose: the database, the boards, and linger — none of them
-    // are this command's to decide about.
     say(`$PIER_HOME is untouched; linger is still enabled.`);
     return ok;
 }

package/dist/settings.js

@@ -1,33 +1,18 @@
 // Instance settings: the facts about *this* Pier that are neither a credential
-// nor per-session — the public URL (nothing in the process can discover it:
-// a Host header is whatever a proxy passed on) and the operator's model menu.
-//
-// A key-value table, so the next setting is not the next table and not a third
-// kind of storage. It used to be a JSON file, justified by "the agent reads it
-// too" — the agent is told the URL in its system prompt (core/reply.ts), and
-// nothing outside this process ever opened that file.
+// nor per-session. A key-value table, so the next setting is not the next table.
 import { isThinkingLevel } from "./core/types.js";
 import { pierDb, transact } from "./db.js";
 import { logger } from "./log.js";
-// The one place the custom-tool vocabulary lives (names, ubix sources, the
-// names Pier already owns). Imported rather than copied: a second validator
-// would be the third-copy bug one release later, and tools.ts is root-layer
-// like this file, so nothing crosses a seam.
 import { normalizeCustomTools } from "./tools.js";
 const log = logger("settings");
-/**
- * `""` clears it, `null` rejects it. Rejecting rather than repairing: a
- * mistyped host quietly turned into a URL produces board links that 404 for
- * the person they were sent to, and the sender never finds out.
- */
+/** `""` clears it, `null` rejects it: a mistyped host quietly turned into a URL
+ *  produces board links that 404 for the person they were sent to. */
 export function normalizePublicUrl(raw) {
     const text = raw.trim();
     if (!text)
         return "";
     let url;
     try {
-        // Scheme-less input is the common way to type a host, and https is the
-        // only guess worth making for something on the internet.
         url = new URL(text.includes("://") ? text : `https://${text}`);
     }
     catch {
@@ -39,12 +24,8 @@ export function normalizePublicUrl(raw) {
         return null;
     return `${url.origin}${url.pathname}`.replace(/\/+$/, "");
 }
-/**
- * Boundary check for a menu, rejecting rather than repairing (same contract as
- * `normalizePublicUrl`): a silently "fixed" entry would advertise a model the
- * operator never picked. Notes are capped — they are one line of intent, and
- * every session that asks for the menu pays for their tokens.
- */
+/** Rejecting rather than repairing: a "fixed" entry would advertise a model the
+ *  operator never picked. Notes are capped; every session pays for their tokens. */
 export function normalizeModelMenu(raw) {
     if (!Array.isArray(raw) || raw.length > 32)
         return null;
@@ -54,9 +35,8 @@ export function normalizeModelMenu(raw) {
         if (!ref)
             return null;
         const { thinking, note } = item;
-        // The one thing repaired rather than rejected, because it is not input:
-        // entries stored (or exported by an instance) before the level was
-        // required have none, and dropping the menu over it would lose the pins.
+        // Repaired, not rejected: rows stored before the level was required have
+        // none, and dropping the menu over it would lose the pins.
         const level = thinking === undefined ? "medium" : thinking;
         if (!isThinkingLevel(level))
             return null;
@@ -71,9 +51,8 @@ export function normalizeModelMenu(raw) {
     }
     return menu;
 }
-/** One model reference, rejecting rather than repairing — the menu above is
- *  built from these. Existence is not checked here: the catalog is the
- *  agent's, and a model that went away is reported by the call that fails. */
+/** Existence is not checked: the catalog is the agent's, and a model that went
+ *  away is reported by the call that fails. */
 export function normalizeModelRef(raw) {
     if (typeof raw !== "object" || raw === null)
         return null;
@@ -84,19 +63,12 @@ export function normalizeModelRef(raw) {
         return null;
     return { provider: provider.trim(), id: id.trim() };
 }
-/**
- * Shape only — an unknown name is not an error here. This file must not know
- * what Pier bundles (that catalog is code, and importing it would drag the Pi
- * SDK into the instance layer); agent/ matches the names it recognizes and
- * ignores the rest, which is also what keeps a downgrade from losing a
- * setting it cannot currently explain.
- */
+/** Shape only: the catalog is code behind the Pi SDK, and an unknown name is
+ *  ignored there, so a downgrade cannot lose a setting it cannot explain. */
 export function normalizeExtensions(raw) {
     return normalizeNames(raw);
 }
-/** Same shape, same contract, same cap — the managed-tool set (src/tools.ts).
- *  Shape only again: tools.ts owns the catalog, and a name it does not know is
- *  ignored there rather than rejected here, so a downgrade cannot lose one. */
+/** Shape only, for the same reason: tools.ts owns the catalog. */
 export function normalizeTools(raw) {
     return normalizeNames(raw);
 }
@@ -128,17 +100,11 @@ export class SettingsStore {
             autoUpdate: this.#value("autoUpdate") === "1",
             extensions: this.#json("extensions", normalizeExtensions, "a list of names") ?? [],
             tools: this.#json("tools", normalizeTools, "a list of names") ?? [],
-            // `"drop"`: a stored row whose name the bundled catalog has since taken
-            // is redundant, not malformed — rejecting the setting over it would take
-            // every other tool declared beside it (see normalizeCustomTools).
-            customTools: this.#json("customTools", (raw) => normalizeCustomTools(raw, [], "drop"), "a list of {name, spec}") ?? [],
+            // `"drop"`: a row the bundled catalog has since taken is redundant, not malformed.
+            customTools: this.#json("customTools", (raw) => normalizeCustomTools(raw, [], "drop"), "a list of {name, toml}") ?? [],
         };
     }
-    /**
-     * A JSON-valued row, validated on the way out. Only a hand-edited row can be
-     * malformed, and it is named rather than silently served as the empty value:
-     * a setting that stopped applying without saying so is the bug this logs.
-     */
+    /** A malformed row is named, not silently served as the empty value (§5). */
     #json(key, normalize, expected) {
         const raw = this.#value(key);
         if (!raw)
@@ -156,19 +122,16 @@ export class SettingsStore {
             log.warn(`settings.${key} is not ${expected} — ignoring it`);
         return value;
     }
-    /** Store an already-normalized value — validation belongs at the boundary
-     *  that received it, so this never has to guess what the caller meant. */
+    /** Setters take already-normalized values: validation belongs at the boundary. */
     setPublicUrl(publicUrl) {
         this.#set("publicUrl", publicUrl);
         return this.get();
     }
-    /** Same contract: hand this `normalizeModelMenu`'s output, not raw input. */
     setModelMenu(menu) {
         this.#set("modelMenu", JSON.stringify(menu));
         return this.get();
     }
-    /** Same contract: hand this `normalizeModelRef`'s output; null switches
-     *  auto-titling off. */
+    /** null switches auto-titling off. */
     setTitleModel(ref) {
         this.#set("titleModel", ref ? JSON.stringify(ref) : "");
         return this.get();
@@ -177,27 +140,20 @@ export class SettingsStore {
         this.#set("autoUpdate", on ? "1" : "0");
         return this.get();
     }
-    /** Same contract again: hand this `normalizeExtensions`'s output. */
     setExtensions(names) {
         this.#set("extensions", JSON.stringify(names));
         return this.get();
     }
-    /** Same contract again: hand this `normalizeTools`'s output. */
     setTools(names) {
         this.#set("tools", JSON.stringify(names));
         return this.get();
     }
-    /** Same contract again: hand this `normalizeCustomTools`'s output. */
     setCustomTools(tools) {
         this.#set("customTools", JSON.stringify(tools));
         return this.get();
     }
-    /**
-     * Several setters as one write. A request that declares a tool *and* the
-     * switch that turns it on must not be able to store one without the other:
-     * half of that pair is a switch nobody can explain — on and undeclared, or
-     * declared and invisible.
-     */
+    /** A request that declares a tool and switches it on must not store one
+     *  without the other. */
     transact(work) {
         return transact(this.#db, work);
     }

package/dist/tasks/agent.js

@@ -1,17 +1,15 @@
-// A run that *is* a Pi session: which session it opens (fresh or reused),
-// what the child is told before the prompt, and how many may run at once. The
-// concurrency caps are here rather than in execution.ts because they bound
-// agents specifically — a bash run costs a process, an agent run costs a
-// model's context and someone's rate limit.
+// A run that *is* a Pi session: which session it opens, what the child is told
+// before the prompt, and how many may run at once (an agent run costs a
+// model's context and someone's rate limit, so the caps are here).
 import { quietLabel, splitReply } from "../core/reply.js";
 import { logger } from "../log.js";
 import { runSource } from "./callbacks.js";
-const MAX_ACTIVE_AGENTS = 4;
+// Agent runs are I/O-bound: the cap is there for API pressure and runaway
+// fan-out, not for this machine's CPU.
+const MAX_ACTIVE_AGENTS = 6;
 const log = logger("tasks");
-/** What a child cannot know unless told. Every session gets the chat-surface
- * contract (<pier>/AGENTS.md), task runs included — so the delegation prompt
- * says which of it does not apply here, and a supervised run how to reach the
- * agent that is waiting on it. Skipped on resume: the session already saw it. */
+/** Every session gets the chat-surface contract, task runs included, so the
+ *  delegation prompt says which of it does not apply. Skipped on resume. */
 const preamble = (run) => {
     // A cron/watch task with a session callback is read by an agent too.
     const audience = run.invokedBySessionId
@@ -55,35 +53,25 @@ export class AgentTaskRunner {
                 // A reused session may have become busy while we waited for a slot.
                 await this.waitUntilIdle(session, signal);
                 signal.throwIfAborted();
-                // Task requests come seconds apart — the 1h Anthropic cache-write premium
-                // never earns its 2× back, so task runs use the 5m TTL. Set here, not in
-                // resolveSession: this covers create, reuse and resume alike, on
-                // every attempt — and only after the session is idle, so a reused
-                // interactive session's in-flight turn keeps its 1h writes.
+                // Task requests come seconds apart, so the 1h cache-write premium never
+                // earns back; after idle, so a reused session's in-flight turn keeps its 1h.
                 session.setCacheRetention("short");
                 start();
-                // No input is no block: `<task_input>\nnull\n</task_input>` is four
-                // lines telling the agent nothing, on every run that has no input.
-                // Compact for the same reason tool results are (agent/pi.ts), and
-                // `<\/` is the same JSON — a value cannot close the fence early.
+                // No input is no block. `<\/` is the same JSON, so a value cannot close
+                // the fence early.
                 const input = run.input === undefined || run.input === null
                     ? ""
                     : `\n\n<task_input>\n${JSON.stringify(run.input).replaceAll("</task_input>", "<\\/task_input>")}\n</task_input>`;
                 const prompt = run.context.resumePrompt ?? `${preamble(run)}${action.prompt}${input}`;
                 run.context.sessionId = session.id;
                 run.context.model = session.model;
-                // The level the session settled on, not the one the task asked for:
-                // an unspecified effort inherits the caller's, and the card in the
-                // subagent's own transcript should say which one that was.
+                // The level the session settled on: an unspecified effort inherits the caller's.
                 run.context.thinking = session.thinkingLevel;
                 run.context.renderedPrompt = prompt;
                 this.store.saveRun(run);
                 let text = "";
-                // Not only what the turn said but how it ended: a provider outage ends
-                // it with an empty reply, and a run that settles on that reports "no
-                // reply" — the one wording for a turn that *chose* to say nothing, so
-                // the outage arrives at the caller looking like an answer (§5b). Pi has
-                // already retried by the time this lands; the run only reports.
+                // How it ended, too: a provider outage ends with an empty reply, which
+                // would otherwise report as a turn that chose to say nothing (§5).
                 let failure;
                 const unsubscribe = session.subscribe((event) => {
                     if (event.type === "turn-end") {
@@ -113,27 +101,21 @@ export class AgentTaskRunner {
                     await this.untilAborted(turn, signal);
                     if (signal.aborted)
                         throw new Error("cancelled");
-                    // Before the fallback below: on a reused session that reads the
-                    // *previous* turn's answer back out of history and reports it as
-                    // this run's result.
+                    // Before the fallback: on a reused session it would read the previous
+                    // turn's answer back as this run's result.
                     if (failure)
                         throw new Error(failure);
                     if (!text) {
                         const history = await this.untilAborted(session.history(), signal);
                         text = [...history].reverse().find((turn) => turn.role === "assistant")?.text ?? "";
                     }
-                    // The chat contract is injected into task sessions too, so a child's
-                    // reply may carry chat-only markup. The result is read by a
-                    // supervisor or the Console, never a chat renderer: buttons are
-                    // dropped, and a turn that said nothing names which kind of nothing
-                    // it was (principle 5b) instead of storing an empty result.
+                    // The result is read by a supervisor, never a chat renderer: buttons
+                    // are dropped, and an empty turn names which kind of nothing (§5).
                     const reply = splitReply(text);
                     return { type: "agent", text: reply.text || quietLabel(reply.silence), sessionId: session.id };
                 }
                 finally {
-                    // The run is what earns "short"; a reused interactive session goes
-                    // back to chat afterwards. For task-created sessions this is moot —
-                    // idle until the next run downgrades them again.
+                    // A reused interactive session goes back to chat afterwards.
                     session.setCacheRetention("long");
                     signal.removeEventListener("abort", abort);
                     unsubscribe();
@@ -150,9 +132,8 @@ export class AgentTaskRunner {
             return this.untilAborted(this.router.ensure({ channelId: "task", conversationId: run.targetSessionId }), signal);
         }
         const policy = action.session;
-        // Definitions stored before fork was removed still say `"fork"`. Refused by
-        // name: every directory this could pick instead is a guess at what the
-        // author meant, and a child in the wrong tree edits real files.
+        // Stored definitions may still say `"fork"`. Refused by name: any directory
+        // picked instead is a guess, and a child in the wrong tree edits real files.
         if (run.sessionMode === "fork" || policy.mode === "fork") {
             throw new Error(`task "${run.context.definition.name}" uses the removed fork session mode; recreate it with {"mode":"fresh","cwd":"/abs/path"}`);
         }
@@ -172,10 +153,8 @@ export class AgentTaskRunner {
             thinking: action.launch?.thinking,
         };
         const opening = this.factory.create(opts).then(async (session) => {
-            // SDK creation cannot be cancelled. A late session still belongs to
-            // this run; read back its terminal row so delivery updates are preserved.
-            // Remember it on the live run too: cancellation's final save can race
-            // this callback before it finishes writing the terminal record.
+            // SDK creation cannot be cancelled; a late session still belongs to this
+            // run. Cancellation's final save can race this callback, so both records get it.
             run.targetSessionId = session.id;
             run.context.sessionId = session.id;
             run.context.cwd = cwd;