@edgehero/pi-dispatch 4.3.0 → 5.0.0

package/src/capacity-records.mjs

@@ -23,8 +23,9 @@
  *     written before that key, recreated by a worker that does not know it, or whose key was lost, vouches for nothing
  *     older), the deepest window any writer keeps
  *     (`mirrorWindowMs(0)`), the fleet horizon (`runs:horizon`, raised by every writer whose trim removed runs, by its
- *     OWN retention or the count cap, so a peer with a short retention cuts everyone's history and says so), the oldest
- *     run at the `RUNS_INDEX_MAX` cap when that run ended after the window began, and the newest run whose body has
+ *     OWN retention or its own count cap, so a peer with a short retention cuts everyone's history and says so), the oldest
+ *     run when the index is at the cap (`indexMax`, the deployment's `PI_RUN_MIRROR_MAX_RUNS`; see `readMirrorWindow`)
+ *     and that run ended after the window began, and the newest run whose body has
  *     expired while its index member stayed (its writer has not trimmed since). Any of these past the window's start
  *     makes it `truncated`. The start is the one bound that survives losing the mirror's keys: a flushed or replaced
  *     Valkey, or an index that expired, loses the horizon with the runs, and the next write recreates an index whose
@@ -35,21 +36,41 @@
  * only. Every Valkey call is bounded (`bounded`, host-registry.mjs' reason: this client QUEUES a command while offline
  * rather than rejecting it, so an unbounded await is a hang, not an error).
  *
+ * A record from a NEWER pi-dispatch (issue #761, run-history.mjs `recordReadable`) is not read by either source: a
+ * capacity report adds up slot time and sizes, fields whose meaning that release may have changed. It is skipped and
+ * COUNTED (`newerSkipped`, and a reason naming the count), so the report says it is partial rather than reading a
+ * busy host as idle. Each source skips its own before the merge, so an older attempt's readable copy of the same job
+ * (a retry that landed on a newer host) still counts its own slot. The merged count is of distinct job ids, the key
+ * `mergeRuns` keeps one record per: a host rolled back from a newer release holds its own newer records both on disk
+ * and in the mirror, and each is one record the report did not read, not two.
+ *
  * Never throws.
  */
 
 import { readdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { READ_SCRIPT, RUNS_HORIZON, RUNS_HORIZON_MEMBER, RUNS_INDEX, RUNS_INDEX_MAX, RUNS_SINCE, mergeRuns, mirrorWindowMs, runRecordKey } from "./run-mirror.mjs";
+import { recordReadable } from "./run-history.mjs";
 import { SIZING_RECORD_MAX_BYTES } from "./size-records.mjs";
 
-/** How many record bodies one MGET asks for: a full mirror is ten round trips, never one 5,000-key command. */
+/**
+ * How many record bodies one MGET asks for: a full mirror at the default cap of 5,000 runs is ten round trips, never one
+ * 5,000-key command, and at the 20,000 ceiling (`RUN_MIRROR_MAX_RUNS_MAX`) forty.
+ */
 export const CAPACITY_MGET_CHUNK = 500;
 /** How long one Valkey call may take before the mirror is read as unreachable. */
 export const CAPACITY_OP_TIMEOUT_MS = 2_000;
 
 const DAY_MS = 24 * 60 * 60 * 1000;
 
+/**
+ * A source's newer-release fields: `newerSkipped` (how many) and `newerIds` (their job ids, which the merged count
+ * de-duplicates), both absent when there are none, so a whole-result comparison of a read without one is unchanged.
+ */
+function newerOf(ids) {
+	return ids.length > 0 ? { newerSkipped: ids.length, newerIds: ids } : {};
+}
+
 /** Reject rather than wait forever (host-registry.mjs `bounded`). */
 function bounded(promise, ms) {
 	return new Promise((resolve, reject) => {
@@ -63,9 +84,21 @@ function bounded(promise, ms) {
 
 /**
  * The mirror's records that ended after `sinceMs`: `{ records, state, fromMs, truncated, skipped }`, `state` "ok", "off"
- * or "unreachable (<reason>)", `fromMs` where its history starts (see the header). Never throws.
+ * or "unreachable (<reason>)", `fromMs` where its history starts (see the header), plus `newerSkipped`, how many
+ * records from a newer pi-dispatch were left out, and `newerIds`, their job ids, only when there were any. A newer
+ * record with no job id is not counted: `mergeRuns` keeps no record without one, so it is none the report would read.
+ * Never throws.
+ *
+ * `indexMax` is the deployment's run index cap (`PI_RUN_MIRROR_MAX_RUNS`, issue #761; the built-in 5,000 when not
+ * given). An index at or over it may have been cut by count, so its history starts no earlier than its oldest run. The
+ * cap the reader is told, not the built-in one: an index of a raised cap that holds 6,000 runs was never trimmed, and
+ * reading it against 5,000 marked a whole history as cut. A count trim since issue #599 also raises the horizon, which
+ * says the same; this clause is for a writer from before that, which trimmed at the built-in 5,000 and recorded no
+ * horizon. A reader told a cap above that writer's misses its cut (a fleet that still runs such a worker caps the
+ * index at 5,000 anyway); one told a lower cap than the fleet's reads its history as starting at the oldest run, which
+ * errs toward missing history, never toward idle time.
  */
-export async function readMirrorWindow(redis, { sinceMs, nowMs, timeoutMs = CAPACITY_OP_TIMEOUT_MS, chunk = CAPACITY_MGET_CHUNK } = {}) {
+export async function readMirrorWindow(redis, { sinceMs, nowMs, timeoutMs = CAPACITY_OP_TIMEOUT_MS, chunk = CAPACITY_MGET_CHUNK, indexMax = RUNS_INDEX_MAX } = {}) {
 	const none = (state) => ({ records: [], state, fromMs: null, truncated: false, skipped: 0 });
 	if (!redis) return none("off");
 	try {
@@ -84,6 +117,7 @@ export async function readMirrorWindow(redis, { sinceMs, nowMs, timeoutMs = CAPA
 		for (let i = 0; i < ids.length; i += 2) members.push({ id: ids[i], score: Number(ids[i + 1]) });
 		const records = [];
 		let skipped = 0;
+		const newerIds = [];
 		let expiredMs = NaN;
 		for (let i = 0; i < members.length; i += chunk) {
 			const part = members.slice(i, i + chunk);
@@ -102,7 +136,9 @@ export async function readMirrorWindow(redis, { sinceMs, nowMs, timeoutMs = CAPA
 				}
 				try {
 					const record = JSON.parse(raw);
-					if (record !== null && typeof record === "object" && !Array.isArray(record)) records.push(record);
+					if (record === null || typeof record !== "object" || Array.isArray(record)) return;
+					if (recordReadable(record)) records.push(record);
+					else if (typeof record.jobId === "string" && record.jobId !== "") newerIds.push(record.jobId);
 				} catch {
 					// unparseable is not showable
 				}
@@ -114,20 +150,27 @@ export async function readMirrorWindow(redis, { sinceMs, nowMs, timeoutMs = CAPA
 		if (Number.isFinite(startMs)) fromMs = Math.max(fromMs, startMs);
 		else if (Number.isFinite(oldestMs)) fromMs = Math.max(fromMs, oldestMs);
 		if (Number.isFinite(horizonMs)) fromMs = Math.max(fromMs, horizonMs);
-		if (size >= RUNS_INDEX_MAX && Number.isFinite(oldestMs)) fromMs = Math.max(fromMs, oldestMs);
+		if (size >= indexMax && Number.isFinite(oldestMs)) fromMs = Math.max(fromMs, oldestMs);
 		if (Number.isFinite(expiredMs)) fromMs = Math.max(fromMs, expiredMs);
 		fromMs = Math.min(fromMs, nowMs);
-		return { records, state: "ok", fromMs, truncated: fromMs > sinceMs, skipped };
+		return { records, state: "ok", fromMs, truncated: fromMs > sinceMs, skipped, ...newerOf(newerIds) };
 	} catch (err) {
 		return none(`unreachable (${err?.message ?? "error"})`);
 	}
 }
 
 /**
- * This host's records that ended after `sinceMs`: `{ records, skipped, unreachable, absent }`. `fs` is `{ readdirSync,
+ * This host's records that ended after `sinceMs`: `{ records, skipped, unreachable, absent }`, plus `newerSkipped`, how
+ * many records of the window from a newer pi-dispatch were left out, and `newerIds`, their job ids, only when there
+ * were any. `fs` is `{ readdirSync,
  * statSync, readFileSync }`.
+ *
+ * `deadlineAt` (issue #761, doctor's dollar window check): an instant on `clock` past which no further file is opened,
+ * the result then carrying `cutShort: true`. The loop is synchronous, so a bound raced against it from outside could
+ * not stop it; this one is checked before each file. A read cut short returns fewer records, which for every caller
+ * that passes it only lowers what it adds up. Absent, every file is read, as before.
  */
-export function readLocalWindow(logsDir, { sinceMs, fs = { readdirSync, readFileSync, statSync } } = {}) {
+export function readLocalWindow(logsDir, { sinceMs, fs = { readdirSync, readFileSync, statSync }, deadlineAt = null, clock = Date.now } = {}) {
 	let names;
 	try {
 		names = fs.readdirSync(logsDir);
@@ -137,8 +180,14 @@ export function readLocalWindow(logsDir, { sinceMs, fs = { readdirSync, readFile
 	}
 	const records = [];
 	let skipped = 0;
+	const newerIds = [];
+	let cutShort = false;
 	for (const name of names) {
 		if (typeof name !== "string" || !name.endsWith(".json")) continue;
+		if (Number.isFinite(deadlineAt) && clock() > deadlineAt) {
+			cutShort = true;
+			break;
+		}
 		try {
 			const path = join(logsDir, name);
 			const st = fs.statSync(path);
@@ -156,24 +205,30 @@ export function readLocalWindow(logsDir, { sinceMs, fs = { readdirSync, readFile
 			}
 			const record = JSON.parse(buf.toString("utf8"));
 			if (record === null || typeof record !== "object" || Array.isArray(record) || typeof record.jobId !== "string") continue;
+			// `endedAt` is in the stable core, so a newer record is judged against the window before it is skipped: only one
+			// the report would have read is counted.
 			const end = Date.parse(record.endedAt ?? "");
-			if (Number.isFinite(end) && end > sinceMs) records.push(record);
+			if (!Number.isFinite(end) || end <= sinceMs) continue;
+			if (recordReadable(record)) records.push(record);
+			else newerIds.push(record.jobId);
 		} catch {
 			// unparseable, or reaped between the listing and the read
 		}
 	}
-	return { records, skipped, unreachable: null, absent: false };
+	return { records, skipped, unreachable: null, absent: false, ...newerOf(newerIds), ...(cutShort ? { cutShort: true } : {}) };
 }
 
 /**
  * The records of the window `[sinceMs, nowMs]` from both sources, merged, and what each covers: `{ records, mirrorState,
  * coverage }`,
  * `coverage` being `{ source, reason, localHost, localHosts, local: { fromMs } | null, mirror: { fromMs, truncated,
- * hosts } | null, skipped }` as `computeCapacity` reads it. `redis` may be null (no Valkey to ask); `noMirrorReason` then
- * says why, in place of "no run mirror". `localHost` is this host's name. Never throws.
+ * hosts } | null, skipped }` as `computeCapacity` reads it, plus `newerSkipped` when records from a newer pi-dispatch
+ * were left out (the reason then names how many). `redis` may be null (no Valkey to ask); `noMirrorReason` then
+ * says why, in place of "no run mirror". `localHost` is this host's name. `indexMax` is the deployment's run index cap
+ * (`readMirrorWindow`; capacity-cli.mjs `deploymentFacts` reads it). Never throws.
  */
-export async function readCapacityRecords({ redis = null, logsDir, sinceMs, nowMs, fs, retentionDays = 0, localHost = null, noMirrorReason = null, timeoutMs = CAPACITY_OP_TIMEOUT_MS, chunk = CAPACITY_MGET_CHUNK } = {}) {
-	const mirror = await readMirrorWindow(redis, { sinceMs, nowMs, timeoutMs, chunk });
+export async function readCapacityRecords({ redis = null, logsDir, sinceMs, nowMs, fs, retentionDays = 0, localHost = null, noMirrorReason = null, timeoutMs = CAPACITY_OP_TIMEOUT_MS, chunk = CAPACITY_MGET_CHUNK, indexMax = RUNS_INDEX_MAX } = {}) {
+	const mirror = await readMirrorWindow(redis, { sinceMs, nowMs, timeoutMs, chunk, indexMax });
 	const local = readLocalWindow(logsDir, { sinceMs, ...(fs ? { fs } : {}) });
 	const mirrored = mirror.state === "ok";
 	const days = Number(retentionDays);
@@ -189,6 +244,9 @@ export async function readCapacityRecords({ redis = null, logsDir, sinceMs, nowM
 	if (local.unreachable) reasons.push(local.unreachable);
 	const skipped = local.skipped + mirror.skipped;
 	if (skipped > 0) reasons.push(`${skipped} record${skipped === 1 ? "" : "s"} over ${SIZING_RECORD_MAX_BYTES / 1024} KiB skipped`);
+	// Distinct job ids, as the records are merged (the header): the same newer record on disk and in the mirror is one.
+	const newerSkipped = new Set([...(local.newerIds ?? []), ...(mirror.newerIds ?? [])]).size;
+	if (newerSkipped > 0) reasons.push(`${newerSkipped} record${newerSkipped === 1 ? "" : "s"} from a newer pi-dispatch not read`);
 	const hostsOf = (records) => [...new Set(records.map((r) => r.host).filter((h) => typeof h === "string" && h !== ""))].sort();
 	return {
 		// One per job id, the later end winning (a retry can land on another host); `Infinity` keeps every run, since the
@@ -204,6 +262,7 @@ export async function readCapacityRecords({ redis = null, logsDir, sinceMs, nowM
 			local: localRead ? { fromMs: localFromMs } : null,
 			mirror: mirrored ? { fromMs: mirror.fromMs, truncated: mirror.truncated, hosts: hostsOf(mirror.records) } : null,
 			skipped,
+			...(newerSkipped > 0 ? { newerSkipped } : {}),
 		},
 	};
 }

package/src/capacity.mjs

@@ -424,6 +424,8 @@ export function computeCapacity({ records = [], live = [], windowStartMs, nowMs,
 		}
 	}
 
+	const fleetSegments = [];
+	const fleetWaits = [];
 	const hosts = [];
 	const totals = zeroCounts();
 	const notShared = [];
@@ -511,6 +513,8 @@ export function computeCapacity({ records = [], live = [], windowStartMs, nowMs,
 		const segment = (a, b, n) => {
 			if (b <= a) return;
 			const cap = capAt(a);
+			const memoryKnown = positiveInt(cap.memMiB) && [...active].every((i) => h.runs[i].size !== null);
+			fleetSegments.push({ start: a, end: b, jobs: n, slots: cap.slots, memory: memoryKnown ? [...active].reduce((sum, i) => sum + h.runs[i].size.memMiB, 0) : null, budget: positiveInt(cap.memMiB) ? cap.memMiB : null });
 			// CPU used in this segment: each running job's measured time spread over its wall, together never more than
 			// the host's CPUs. Past it, every share is cut in proportion and the runs are counted as clamped.
 			const parts = [];
@@ -596,6 +600,7 @@ export function computeCapacity({ records = [], live = [], windowStartMs, nowMs,
 		const other = rest.length === 0 ? null : { count: rest.length, runMs: Number(rest.reduce((s, [, p]) => s + p.runMs, 0n)), cpuMs: Number(rest.reduce((s, [, p]) => s + p.cpuUsec, 0n) / 1000n) };
 
 		for (const [k, v] of Object.entries(h.counts)) totals[k] += v;
+		fleetWaits.push(...h.waits);
 		const waits = [...h.waits].sort((a, b) => a - b);
 		hosts.push({
 			name,
@@ -632,6 +637,7 @@ export function computeCapacity({ records = [], live = [], windowStartMs, nowMs,
 	const liveRowMissing = isHostName(coverage.localHost) && names.has(coverage.localHost) && !liveByName.has(coverage.localHost) ? coverage.localHost : null;
 	return {
 		v: CAPACITY_REPORT_VERSION,
+		fleet: fleetCapacity(fleetSegments, fleetWaits, { windowStartMs, nowMs, incomplete: hosts.some((h) => !h.shared || h.missingMs > 0 || h.coverage.liveUnreadable > 0) || unreadable > 0 || withoutHost > 0 || coverage.reason != null }),
 		window: { fromMs: windowStartMs, toMs: nowMs, bucketMs },
 		coverage: {
 			source: typeof coverage.source === "string" ? coverage.source : "records",
@@ -652,3 +658,62 @@ export function computeCapacity({ records = [], live = [], windowStartMs, nowMs,
 		hosts,
 	};
 }
+
+/** Aggregate the same covered segments as the host report, never an average of host percentages or percentiles. */
+function fleetCapacity(segments, waits, { windowStartMs, nowMs, incomplete }) {
+	const hourMs = 60 * 60 * 1000;
+	const events = [];
+	let occupied = 0n;
+	let available = 0n;
+	for (const s of segments) {
+		if (s.slots === null) incomplete = true;
+		else {
+			occupied += BigInt(s.jobs) * BigInt(s.end - s.start);
+			available += BigInt(s.slots) * BigInt(s.end - s.start);
+		}
+		if (s.memory === null || s.budget === null) incomplete = true;
+		events.push({ at: s.start, delta: 1, segment: s }, { at: s.end, delta: -1, segment: s });
+	}
+	events.sort((a, b) => a.at - b.at || a.delta - b.delta);
+	const hours = new Map();
+	let jobs = 0;
+	let memory = 0;
+	let budget = 0;
+	let unknownMemory = 0;
+	let peak = 0;
+	let peakAtMs = null;
+	let at = windowStartMs;
+	const count = (end) => {
+		if (end <= at) return;
+		if (jobs > peak) { peak = jobs; peakAtMs = at; }
+		for (let t = at; t < end;) {
+			const key = Math.floor(t / hourMs) * hourMs;
+			const stop = Math.min(end, key + hourMs);
+			const len = BigInt(stop - t);
+			const h = hours.get(key) ?? { runMs: 0n, memory: 0n, budget: 0n, unknown: false };
+			h.runMs += BigInt(jobs) * len;
+			h.memory += BigInt(memory) * len;
+			h.budget += BigInt(budget) * len;
+			h.unknown ||= unknownMemory > 0;
+			hours.set(key, h);
+			t = stop;
+		}
+	};
+	for (const e of events) {
+		count(e.at);
+		at = e.at;
+		jobs += e.delta * e.segment.jobs;
+		memory += e.delta * (e.segment.memory ?? 0);
+		budget += e.delta * (e.segment.budget ?? 0);
+		if (e.segment.memory === null || e.segment.budget === null) unknownMemory += e.delta;
+	}
+	count(nowMs);
+	const busiest = [...hours].sort((a, b) => a[1].runMs === b[1].runMs ? a[0] - b[0] : a[1].runMs > b[1].runMs ? -1 : 1)[0];
+	waits.sort((a, b) => a - b);
+	return {
+		busyPerMille: perMille(occupied, available), peak, peakAtMs,
+		waits: { n: waits.length, p50Ms: waits.length ? rank(waits, 50) : null, p95Ms: waits.length ? rank(waits, 95) : null },
+		promisedMemPerMille: busiest && !busiest[1].unknown ? perMille(busiest[1].memory, busiest[1].budget) : null,
+		busiestHourMs: busiest?.[0] ?? null, incomplete,
+	};
+}

package/src/chat-cli.mjs

@@ -0,0 +1,288 @@
+/**
+ * `pi-dispatch chat <run-id | issue-or-PR-url | session-key> [--fork] [--force] [--tools] [--pi <path>] [--console <addr>] [--yes]`
+ * (issue #647, REQ-TERMINAL-CHAT): open a run's chat in this terminal.
+ *
+ * THREE ARGUMENT CLASSES, told apart by shape alone (`classifyChatTarget`):
+ *   - a session key (32 lowercase hex) is ALWAYS the fork, on this host, with no console at all: a key names a stored
+ *     transcript and nothing else, so there is no run to ask about;
+ *   - an http(s) URL is an issue or pull request on a forge, which the console resolves to its newest run (`?url=`);
+ *   - anything else in the run-id charset is a job id (`?id=`).
+ *
+ * THE MODE IS THE CONSOLE'S (`/api/run`'s `mode`, from the one rule `chatModeOf` that the web Chat panel and
+ * `/dispatch chat` share), so the terminal can never disagree with the page about what a run is: `live` attaches,
+ * `reply` answers a parked run, `fork` forks a finished one, and `null` prints the console's sentence (`says`: queued,
+ * unknown, already answered) and exits 1. `--fork` forces the fork; with a run id whose record this host's run history
+ * holds, that needs no console either. The record a fork judges comes from the local run history when present (the
+ * record the worker wrote here), else from `/api/run`'s `run`.
+ *
+ * A live attach that ends (the run finished while watched) asks `/api/run` again and goes on in the new mode, so
+ * watching a run that parks drops straight into its reply box.
+ *
+ * A CONSOLE OFF THIS MACHINE IS A QUESTION FIRST. The console speaks plain HTTP, so signing in to an address that is not
+ * loopback or a unix socket sends the token readable to the whole path. Such an address (only `--console` or
+ * `PI_CONSOLE_URL` can name one; `consoleAddressOf` refuses it from a `.env`) gets a warning naming the host and a y/N
+ * whose default is no, before the token is read or sent; `--yes` answers it for a script (the warning still prints).
+ */
+import { parseArgs } from "node:util";
+import { homedir } from "node:os";
+import { askHidden, askYesNo, consoleAddressOf, consoleToken, dotenvTrustRefusal, makeConsoleClient } from "./console-client.mjs";
+import { SESSION_KEY_PATTERN } from "./session-key.mjs";
+
+/** The usage line, shared with the CLI's own usage text (a test holds both). */
+export const CHAT_USAGE = "pi-dispatch chat <run-id | issue-or-PR-url | session-key> [--fork] [--force] [--tools] [--pi <path>] [--console <addr>] [--yes]";
+
+/** The longest issue or pull request URL taken, the console's `?url=` limit (`/dispatch chat`'s, which a test holds to it). */
+export const CHAT_URL_MAX = 2048;
+
+/** A job id as the worker mints it (the console's charset). */
+const RUN_ID_RE = /^[A-Za-z0-9._:-]{1,200}$/;
+
+/** How many times, 2 s apart, a run that just ended is asked again before its new mode is taken as it stands. */
+const SETTLE_TRIES = 5;
+const SETTLE_MS = 2000;
+
+/** The deployment keys this command reads, each only where it is needed. */
+export const CHAT_DEPLOYMENT_KEYS = Object.freeze(["PI_CONSOLE_LISTEN", "PI_SESSIONS_DIR", "PI_LOGS_DIR"]);
+
+/**
+ * What the argument names: `{kind: "key", key}`, `{kind: "url", url}`, `{kind: "id", id}`, or `{refusal}`. A key is
+ * tested first, so a 32-hex string is never read as a job id (job ids that are pure hex of that length are not minted).
+ */
+export function classifyChatTarget(arg) {
+	const s = typeof arg === "string" ? arg.trim() : "";
+	if (s === "") return { refusal: `name a run: ${CHAT_USAGE}` };
+	if (SESSION_KEY_PATTERN.test(s)) return { kind: "key", key: s };
+	if (/^https?:\/\//i.test(s)) {
+		if (s.length > CHAT_URL_MAX) return { refusal: `the URL is longer than ${CHAT_URL_MAX} characters` };
+		try {
+			new URL(s);
+		} catch {
+			return { refusal: "the URL does not parse" };
+		}
+		return { kind: "url", url: s };
+	}
+	if (RUN_ID_RE.test(s)) return { kind: "id", id: s };
+	return { refusal: "the argument is neither a run id (letters, digits and . _ : -), an issue or pull request URL, nor a 32-hex session key" };
+}
+
+/**
+ * One line of console-supplied text, made safe for this terminal: the view's scrub (no pi-tui is loaded for it), then
+ * every line break folded to a space, so a multi-line refusal cannot draw a second, fake line of output.
+ */
+async function safe(text) {
+	const { scrubForTerminal } = await import("./chat-view.mjs");
+	return scrubForTerminal(text, { maxBytes: 4096 }).replace(/\s*\n\s*/g, " ");
+}
+
+/**
+ * Run the command. Seams: `env` (this shell's), `out`/`err` (line writers), `deploymentEnv` (cli.mjs's
+ * `cliDeploymentEnv`, handed in so this module does not import the CLI's entry), `cwd`, `home`, and `deps` for tests:
+ * `makeClient`, `askToken`, `ask`, `readRecord`, `runLive`, `runReply`, `question`, `fork` (`{plan, run}`), `sleep`,
+ * `envTrust` (`dotenvTrustRefusal` of `cwd` by default).
+ * Returns the exit code.
+ */
+export async function runChat(argv, { env = process.env, out = (l) => process.stdout.write(`${l}\n`), err = (l) => process.stderr.write(`${l}\n`), deploymentEnv, cwd = process.cwd(), home = homedir(), deps = {} } = {}) {
+	let parsed;
+	try {
+		parsed = parseArgs({
+			args: argv,
+			allowPositionals: true,
+			options: { "fork-as-job": { type: "boolean", default: false }, entry: { type: "string" }, position: { type: "string" }, model: { type: "string" }, provider: { type: "string" }, thinking: { type: "string" }, message: { type: "string" }, fork: { type: "boolean", default: false }, force: { type: "boolean", default: false }, tools: { type: "boolean", default: false }, pi: { type: "string" }, console: { type: "string" }, yes: { type: "boolean", default: false } },
+		});
+	} catch (e) {
+		err(`error: ${e.message}\n  ${CHAT_USAGE}`);
+		return 1;
+	}
+	const { values, positionals } = parsed;
+	if (positionals.length !== 1) {
+		err(`error: ${positionals.length === 0 ? "name a run" : "chat takes one run"}\n  ${CHAT_USAGE}`);
+		return 1;
+	}
+	const target = classifyChatTarget(positionals[0]);
+	if (target.refusal) {
+		err(`error: ${target.refusal}`);
+		return 1;
+	}
+	if (values["fork-as-job"] && (values.fork || target.kind === "key" || values.force || values.tools || values.pi)) {
+		err("error: --fork-as-job needs a run id or issue URL and cannot use local-fork options");
+		return 1;
+	}
+	if (!values["fork-as-job"] && ["entry", "position", "model", "provider", "thinking", "message"].some((k) => values[k] !== undefined)) {
+		err("error: entry, position, model, provider, thinking and message options need --fork-as-job");
+		return 1;
+	}
+	const deployment = (keys) => (typeof deploymentEnv === "function" ? deploymentEnv(env, keys, { cwd }) : { env });
+	const forkOpts = { values, env, out, err, cwd, home, deployment, deps };
+
+	if (target.kind === "key") return forkRun({ ...forkOpts, record: null, key: target.key, newerRunOnTarget: null });
+
+	// --fork with a run id this host's history holds needs no console: the record is here.
+	if (values.fork && target.kind === "id") {
+		const local = await readLocalRecord(target.id, { deployment, deps });
+		if (local.problem) {
+			err(`error: ${local.problem}`);
+			return 1;
+		}
+		if (local.record) return forkRun({ ...forkOpts, record: local.record, key: null, newerRunOnTarget: null });
+	}
+
+	const where = consoleAddressOf({ flag: values.console ?? null, env, deployment: () => deployment(["PI_CONSOLE_LISTEN"]), envTrust: deps.envTrust ?? (() => dotenvTrustRefusal({ dir: cwd })) });
+	if (where.refusal) {
+		err(`error: ${await safe(where.refusal)}`);
+		return 1;
+	}
+	if (!where.loopback) {
+		err(`warning: ${where.address.shown} is not on this machine, and the console speaks plain HTTP: the console token goes over the network to it unencrypted, readable to anything on the path. A tunnel to a loopback address (ssh -L 4790:127.0.0.1:4790 <host>) keeps it private.`);
+		const ok = values.yes || (await (deps.ask ?? ((q) => askYesNo(q)))(`Send the console token to ${where.address.shown} anyway? [y/N] `));
+		if (!ok) {
+			err("error: not signed in; nothing was sent");
+			return 1;
+		}
+	}
+	const tok = await consoleToken({ env, askHidden: deps.askToken ?? ((q) => askHidden(q)) });
+	if (tok.refusal) {
+		err(`error: ${tok.refusal}`);
+		return 1;
+	}
+	const client = (deps.makeClient ?? makeConsoleClient)({ address: where.address, token: tok.token });
+	const lookup = target.kind === "url" ? { url: target.url } : { id: target.id };
+	try {
+		const who = await client.whoami();
+		let info = await lookupRun(client, lookup, { err });
+		if (!info) return 1;
+		if (values["fork-as-job"]) return managedFork({ client, info, who, values, deps, out, err });
+		for (let round = 0; round < 8; round += 1) {
+			const mode = values.fork ? "fork" : info.mode;
+			if (mode === "fork") {
+				const id = typeof info.run?.jobId === "string" ? info.run.jobId : null;
+				const local = id ? await readLocalRecord(id, { deployment, deps }) : { record: null };
+				if (local.problem) {
+					err(`error: ${local.problem}`);
+					return 1;
+				}
+				return forkRun({ ...forkOpts, record: local.record ?? info.run ?? null, key: null, newerRunOnTarget: typeof info.newerRunOnTarget === "string" ? info.newerRunOnTarget : null });
+			}
+			if (mode === "live") {
+				const pi = await (deps.loadPiTui ?? (async () => (await import("./chat-view.mjs")).loadPiTui()))();
+				const terminal = deps.terminal ?? new pi.ProcessTerminal();
+				const runLive = deps.runLive ?? (await import("./chat-view.mjs")).runLiveView;
+				const got = await runLive({ client, lookup, info, who, pi, terminal });
+				if (got.detached) {
+					out("detached; the run goes on");
+					return 0;
+				}
+				info = await settle(client, lookup, got.info ?? info, deps.sleep);
+				out(`the run is no longer live (${await safe(info.state ?? "?")})`);
+				continue;
+			}
+			if (mode === "reply") {
+				const view = await import("./chat-view.mjs");
+				const question = await (deps.question ?? view.questionOf)({ client, info, who });
+				const pi = await (deps.loadPiTui ?? view.loadPiTui)();
+				const terminal = deps.terminal ?? new pi.ProcessTerminal();
+				const got = await (deps.runReply ?? view.runReplyView)({ client, info, who, question, pi, terminal });
+				if (got.detached) {
+					out("left without answering");
+					return 0;
+				}
+				const jobs = Array.isArray(got.result?.jobIds) ? got.result.jobIds.map(String) : [];
+				out(`answered: the run resumes${jobs.length > 0 ? ` as ${await safe(jobs.join(", "))}` : ""}; follow it with pi-dispatch chat ${await safe(jobs[0] ?? info.run?.jobId ?? "<run-id>")}`);
+				return 0;
+			}
+			err(`error: ${await safe(typeof info.says === "string" && info.says !== "" ? info.says : "this run has no chat to open")}`);
+			return 1;
+		}
+		err("error: the run kept changing mode; open it again");
+		return 1;
+	} catch (e) {
+		err(`error: ${await safe(e?.message ?? "the console could not be asked")}`);
+		return 1;
+	}
+}
+
+/** `/api/run` for `lookup`: its JSON, or null after printing the console's refusal (and an Azure item's candidates). */
+async function lookupRun(client, lookup, { err }) {
+	const got = await client.run(lookup);
+	if (got.status === 200 && got.json && typeof got.json === "object") return got.json;
+	const sentence = typeof got.json?.error === "string" ? got.json.error : `the console answered ${got.status}`;
+	err(`error: ${await safe(sentence)}`);
+	const candidates = Array.isArray(got.json?.candidates) ? got.json.candidates.slice(0, 20) : [];
+	for (const c of candidates) {
+		const line = typeof c === "string" ? c : [c?.jobId ?? c?.id, c?.target, c?.url].filter((v) => typeof v === "string").join("  ");
+		if (line !== "") err(`  ${await safe(line)}`);
+	}
+	if (candidates.length > 0) err("  name one of them: pi-dispatch chat <run-id>");
+	return null;
+}
+
+/** After a live view ends, ask again until the run has left `live` (its record may land a moment after `done`). */
+async function settle(client, lookup, info, sleep = (ms) => new Promise((r) => setTimeout(r, ms))) {
+	let current = info;
+	for (let i = 0; i < SETTLE_TRIES && current?.mode === "live"; i += 1) {
+		await sleep(SETTLE_MS);
+		const got = await client.run(lookup).catch(() => null);
+		if (got?.status === 200 && got.json) current = got.json;
+	}
+	if (current?.mode === "live") return { ...current, mode: null, says: "the run's stream ended but the console still shows it live; open it again in a moment" };
+	return current;
+}
+
+/** This host's record of `jobId` (the run history the worker writes): `{record}` (null when absent) or `{problem}`. */
+async function readLocalRecord(jobId, { deployment, deps }) {
+	let read = deps.readRecord;
+	if (typeof read !== "function") {
+		const d = deployment(["PI_LOGS_DIR"]);
+		if (d.problem) return { problem: `${d.problem}, so this host's run history cannot be found` };
+		const [{ makeReadRecord }, { logsDirPath }] = await Promise.all([import("./run-history.mjs"), import("./config.mjs")]);
+		read = makeReadRecord({ logsDir: logsDirPath(d.env) });
+	}
+	const got = read(jobId);
+	// An unreadable file (`UNREADABLE_RECORD` names no job), or another job's record under a sanitized name that
+	// collides, is no record: the console's copy is asked instead.
+	return { record: got !== null && typeof got === "object" && got.jobId === jobId ? got : null };
+}
+
+/** The fork: plan, then run, printing refusals as sentences. */
+async function forkRun({ values, env, out, err, cwd, home, deployment, deps, record, key, newerRunOnTarget }) {
+	const fork = deps.fork ?? (await import("./chat-fork.mjs"));
+	const d = deployment(["PI_SESSIONS_DIR"]);
+	if (d.problem) {
+		err(`error: ${d.problem}, so the session store cannot be found`);
+		return 1;
+	}
+	const pi = fork.resolvePiBinary({ flag: values.pi ?? null, env });
+	const piVersion = pi.path ? fork.piVersionOf(pi.path, { env }) : null;
+	const planned = fork.planFork({ record, key, env: d.env, force: values.force, newerRunOnTarget, pi, piVersion });
+	if (planned.refusal) {
+		err(`error: ${await safe(planned.refusal)}`);
+		return 1;
+	}
+	const { agentDirFrom } = await import("./host-pi.mjs");
+	return fork.runFork({ plan: planned.plan, out, ask: deps.ask ?? ((q) => askYesNo(q)), agentDir: agentDirFrom(env), cwd, home, tools: values.tools, env });
+}
+
+/** Managed execution uses the console's exact paid preview and confirm pipeline. */
+async function managedFork({ client, info, who, values, deps, out, err }) {
+	if (who.role !== "operator" || who.readOnly) {
+		err("error: a managed fork needs an operator on a writable console");
+		return 1;
+	}
+	const jobId = info.run?.jobId;
+	if (!values.entry) {
+		const got = await client.getJson(`/api/fork-points?id=${encodeURIComponent(jobId ?? "")}`);
+		if (got.status !== 200) {
+			err(`error: ${await safe(got.json?.error ?? "fork points unavailable")}`);
+			return 1;
+		}
+		for (const e of got.json.entries ?? []) if (e.positions?.length) out(await safe(`${e.id} ${e.role ?? e.type} (${e.positions.join(", ")})`));
+		out("Choose a supported entry: add --entry <id> --position before|at to --fork-as-job");
+		return 0;
+	}
+	const body = { jobId, entry: values.entry, position: values.position ?? "before" };
+	for (const key of ["model", "provider", "thinking", "message"]) if (values[key] !== undefined) body[key] = values[key];
+	const got = await client.act("run-fork", body, { print: (line) => out(String(line).replace(/[\u0000-\u001f\u007f-\u009f]/g, " ")), confirm: async () => values.yes || (await (deps.ask ?? askYesNo)("Queue this paid fork? [y/N] ")) });
+	if (got.refusal) { err(`error: ${await safe(got.refusal)}`); return 1; }
+	if (got.declined) { out("left without queuing a fork"); return 0; }
+	out("fork queued; the original run and branch are preserved");
+	return 0;
+}