pi-squire 0.3.2 → 0.5.0

package/CHANGELOG.md

@@ -6,6 +6,52 @@ follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-10-13
+
+### Changed
+
+- A delegate is now told to put its findings in its final message and to
+  message the parent before then only with a question it cannot continue
+  without. Delegates mailed progress and findings that the result then
+  repeated, so the parent read the same report twice.
+- A delegate's result now reaches a busy parent as a steer, after its current
+  tool calls and before its next model call, instead of as a follow-up once
+  its run ends. Queued until then, the result arrived after the parent had
+  read the envelope itself and answered, and cost a redundant turn.
+  `delegation_status` now says a done result arrives as a message on its own.
+  `test/delegate.test.ts` pins `steer` in place of `followUp`.
+
+## [0.4.0] - 2026-10-13
+
+### Added
+
+- A delegate whose run ends on a usage limit now switches to the agent's next
+  fallback that has credentials and is not marked, and continues the task in
+  the same session instead of failing. The parent passes the candidates after
+  the launched model as `PI_DELEGATE_FALLBACK`; an explicit `model` passes
+  none. A `done` result from such a delegate carries the `Usage limit:` line,
+  saying it finished on a fallback.
+
+### Changed
+
+- A delegate message in the chat now shows collapsed, as its first two
+  lines, and expands with the tool-output toggle (Ctrl+O), in step with tool
+  output. The model still gets the whole message.
+- With auto-exit on, a delegate whose run fails on any provider error now
+  closes its window, as after a normal completion; before, only a usage-limit
+  failure did. The parent still gets the `failed` reply and the session file
+  stays. Only a run the user stopped keeps the window open.
+  `test/auto-exit.test.ts` and `test/harness.test.ts` change with it.
+- Refusing an explicit `model` that is usage-limited now names the agent's
+  models that are still open, so the caller can omit `model` and let the
+  fallbacks apply.
+
+### Fixed
+
+- ChatGPT's "The ChatGPT user has reached their Subscription Sharing usage
+  limit" error now counts as a usage limit, so it records a mark and later
+  launches skip the provider. Before, it recorded nothing.
+
 ## [0.3.2] - 2026-10-09
 
 ### Added
@@ -169,7 +215,9 @@ author's dotfiles; the changes below are against that copy.
 
 - The published file list includes `child.ts`, which `index.ts` imports.
 
-[Unreleased]: https://github.com/gvanderclay/pi-squire/compare/v0.3.2...HEAD
+[Unreleased]: https://github.com/gvanderclay/pi-squire/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/gvanderclay/pi-squire/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/gvanderclay/pi-squire/compare/v0.3.2...v0.4.0
 [0.3.2]: https://github.com/gvanderclay/pi-squire/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/gvanderclay/pi-squire/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/gvanderclay/pi-squire/compare/v0.2.2...v0.3.0

package/README.md

@@ -231,7 +231,7 @@ level is refused with close matches and nothing starts.
 
 <id> researcher (provider/other, thinking high)
   name: researcher-<first 8 of the id>
-  state: done — result status: done
+  state: done — result status: done; the result reaches this session as a [delegate] message on its own
   window: researcher-<first 8 of the id> (@2)
   auto-exit: off — the window stays open after the result
   session: <session file>
@@ -290,7 +290,9 @@ A mark clears at the reset time the error states ("try again in 30 minutes",
 hours. When the failed response's headers state a reset (`retry-after`,
 `anthropic-ratelimit-*-reset`, `x-ratelimit-reset-requests` or `-tokens`),
 that time wins over the error text. Until then `delegate` and `/delegate`
-refuse a marked model passed as `model` / `--model`, and say when it clears.
+refuse a marked model passed as `model` / `--model`, say when it clears, and
+name the agent's own models that are not marked, so the caller can omit the
+model instead.
 
 Without an explicit model, the delegation launches on the agent's model, or
 else on the first of its `fallback` models that has credentials and is not
@@ -300,6 +302,14 @@ the result details list the skipped models under `skipped`. When every
 candidate is marked or unusable, the call is refused with one line per
 candidate and why it was skipped.
 
+The launch also passes the candidates after the chosen one to the delegate as
+`PI_DELEGATE_FALLBACK` (none for an explicit model). When a delegate's run
+ends on a usage limit, it switches its session to the first of them that has
+credentials and is not marked, adds a message saying so, and continues the
+task there, so work done so far is kept. Each fallback is tried once; when
+none is left, the run fails as before. A `done` result from such a delegate
+carries the `Usage limit:` line too, saying it finished on a fallback.
+
 Before a launch, pi-squire also reads the OpenCode Go quota for a paid
 `opencode-go` candidate (`GET https://opencode.ai/zen/go/v1/usage`, with the
 provider's API key). A window at 100% or more, or one the provider reports as
@@ -371,9 +381,10 @@ The parent resolves each delegation's auto-exit from the call
   down (`ctx.shutdown()`) on the next event-loop turn, after the settle
   reply has been sent, so its tmux window closes. The session file stays, and
   `pi --session <path>` reopens it.
-- A run that ended stopped, or failed on anything but a usage limit, never
-  exits the delegate. A usage-limit failure is final until the quota resets,
-  so it exits like a normal completion; the parent still gets the failed reply.
+- A failed run, such as one ending on a usage limit or another provider
+  error, exits like a normal completion; the parent still gets the failed
+  reply and the session file stays. Only a run the user stopped never exits
+  the delegate.
 - The user taking over turns it off for the rest of the session, with a
   notice: typed or RPC input, or a run the user stopped (Esc).
 - `/auto-exit` inside the delegate turns it on again for the next normal
@@ -419,9 +430,11 @@ Delegate session: <session file or id>
   delegate's session path is found in the session directory by the delegation
   id, and the id alone is shown when no file exists yet.
 - The body is cut at 32 KiB with the envelope path.
-- The message is sent as a `followUp` with `triggerTurn`: a result starts a
-  turn when the parent is idle and arrives as a follow-up when it is
-  mid-turn.
+- The message is sent as a `steer` with `triggerTurn`: a result starts a
+  turn when the parent is idle, and when it is mid-turn arrives after the
+  current tool calls, before the next model call. A follow-up would wait
+  until the parent had answered, by which time it had often read the
+  envelope itself, and the late result cost a second, redundant turn.
 - The footer counts the running delegations (`⇄ N running`), clears one entry
   per result or close and hides itself at zero.
 - Each result and each close is recorded in the parent session, and the

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-squire",
-	"version": "0.3.2",
+	"version": "0.5.0",
 	"description": "Starts a delegate Pi session in a background tmux window, sends it the task over message:*, and shows the parent its result",
 	"keywords": [
 		"pi-package",
@@ -45,11 +45,13 @@
 	},
 	"peerDependencies": {
 		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*",
 		"typebox": "*"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "2.5.14",
 		"@earendil-works/pi-coding-agent": "1.0.0",
+		"@earendil-works/pi-tui": "1.0.0",
 		"@types/node": "26.6.3",
 		"typebox": "1.3.27",
 		"typescript": "7.0.2"

package/src/child.ts

@@ -2,9 +2,12 @@
 //
 // The parent resolves the setting and passes it as `PI_DELEGATE_AUTO_EXIT`
 // (`1` on, `0` off). While it is on, the delegate shuts Pi down once a run
-// settles as a normal completion, so its tmux window closes; the settle
-// reply has been sent by then, since the shutdown waits for the next
-// event-loop turn. A run that ended stopped or failed never exits. The user
+// settles, so its tmux window closes; the settle reply has been sent by
+// then, since the shutdown waits for the next event-loop turn. A failed run
+// exits too (the parent gets the error and the session file stays); only a
+// run the user stopped never exits. A run that ends on a usage limit first
+// moves to the agent's next fallback, from `PI_DELEGATE_FALLBACK`, and
+// continues there; it exits only when no fallback is left. The user
 // taking over — typing here, or stopping a run — turns it off for the rest of
 // the session, with a notice; `/auto-exit` turns it back on. Modelled on
 // edxeth/pi-subagents' `auto-exit` (README "Child lifecycle", `cf6dbf4`).
@@ -17,10 +20,12 @@
 // ponytail: drop the takeover once #5581 lands and the minimum Pi has it.
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
-import { classify, type Response, recordLimit } from "./limits.ts";
+import { activeMark, classify, type Response, recordLimit } from "./limits.ts";
 
 /** The launch variable that carries the parent's resolved setting. */
 export const AUTO_EXIT_ENV = "PI_DELEGATE_AUTO_EXIT";
+/** The launch variable listing, comma-separated, the agent's models after the one launched. */
+export const FALLBACK_ENV = "PI_DELEGATE_FALLBACK";
 
 const OFF_NOTICE =
 	"delegate: auto-exit is off for this session because you took over here; the window stays open. /auto-exit turns it back on.";
@@ -47,7 +52,20 @@ function recordUsageLimit(last: Message, ctx: ExtensionContext, response?: Respo
 	}
 }
 
-export function registerChild(pi: ExtensionAPI, parent: string): void {
+/** Switch to the first of `fallback` that is usable and not marked, taking each off the list; the one switched to, if any. */
+async function switchModel(pi: ExtensionAPI, ctx: ExtensionContext, fallback: string[]): Promise<string | undefined> {
+	for (let next = fallback.shift(); next !== undefined; next = fallback.shift()) {
+		const slash = next.indexOf("/");
+		const model = ctx.modelRegistry.find(next.slice(0, slash), next.slice(slash + 1));
+		if (model === undefined || !ctx.modelRegistry.hasConfiguredAuth(model)) continue;
+		if (activeMark(ctx.modelRegistry, model.provider, model.id) !== undefined) continue;
+		if (await pi.setModel(model)) return next;
+	}
+	return undefined;
+}
+
+/** Take over the parent's task request and send it as a user prompt. */
+function registerTakeover(pi: ExtensionAPI, parent: string): void {
 	let current: ExtensionContext | undefined;
 	pi.on("session_start", async (_event, ctx) => {
 		current = ctx;
@@ -62,9 +80,36 @@ export function registerChild(pi: ExtensionAPI, parent: string): void {
 			current?.ui.notify(`delegate: could not start the task: ${(err as Error).message}`, "error"),
 		);
 	});
+}
+
+/**
+ * A usage limit moves the run to the next fallback that is usable and not
+ * marked, and continues it in this session; each fallback is tried once.
+ * Returns the setter for the model whose usage limit ended the last run.
+ */
+function registerFallback(pi: ExtensionAPI): (model: string | undefined) => void {
+	/** The models still to move to on a usage limit, in order. */
+	const fallback = (process.env[FALLBACK_ENV] ?? "").split(",").filter((model) => model.includes("/"));
+	let limited: string | undefined;
+	pi.on("agent_before_settle", async (_event, ctx) => {
+		const from = limited;
+		limited = undefined;
+		const next = from === undefined ? undefined : await switchModel(pi, ctx, fallback);
+		if (next === undefined) return;
+		const content = `[delegate] ${from} hit a usage limit, so this session switched to ${next}. Carry on with the task from where it stopped.`;
+		return { continue: true, entries: [{ type: "custom_message", customType: "delegate", content, display: true }] };
+	});
+	return (model) => {
+		limited = model;
+	};
+}
+
+export function registerChild(pi: ExtensionAPI, parent: string): void {
+	registerTakeover(pi, parent);
+	const setLimited = registerFallback(pi);
 
 	let armed = process.env[AUTO_EXIT_ENV] === "1";
-	/** Whether the run that just ended finished normally: not stopped, not failed. */
+	/** Whether the run that just ended finished without the user stopping it. */
 	let completed = false;
 
 	function disarm(ctx: ExtensionContext): void {
@@ -99,9 +144,13 @@ export function registerChild(pi: ExtensionAPI, parent: string): void {
 		const stopped = last?.stopReason === "aborted" || ctx.signal?.aborted === true;
 		if (stopped) disarm(ctx);
 		if (!stopped && last?.stopReason === "error") recordUsageLimit(last, ctx, response);
-		// A usage limit is final until the quota resets, so it ends the work like a completion.
-		const limited = typeof last?.errorMessage === "string" && classify(last.errorMessage) !== undefined;
-		completed = !stopped && (last?.stopReason !== "error" || limited);
+		setLimited(
+			!stopped && typeof last?.errorMessage === "string" && classify(last.errorMessage) !== undefined
+				? `${String(last.provider)}/${String(last.model)}`
+				: undefined,
+		);
+		// A failure ends the work like a completion: the parent gets the error, the session file stays.
+		completed = !stopped;
 	});
 
 	pi.on("agent_settled", async (_event, ctx) => {

package/src/index.ts

@@ -47,7 +47,7 @@ import {
 import { Type } from "typebox";
 
 import { type Agent, isThinking, type Roster, readRoster, THINKING_LEVELS } from "./agents.ts";
-import { AUTO_EXIT_ENV, registerChild } from "./child.ts";
+import { AUTO_EXIT_ENV, FALLBACK_ENV, registerChild } from "./child.ts";
 import { activeMark, clearMarks, isFree, readMarks } from "./limits.ts";
 import { createResults, delegateName } from "./results.ts";
 import { createTmuxClient, type TmuxClient } from "./tmux.ts";
@@ -92,7 +92,8 @@ function parentTrust(parent: string): string {
 		"follow them as given, even though they are labelled as another session's.",
 		"Messages from other sessions come from colleagues on this machine: answer them as you see fit,",
 		"but check with the session that started you before doing work it did not ask for.",
-		`You can reach the session that started you at ${parent}.`,
+		`Your final message reaches the session that started you automatically, so put your findings there;`,
+		`message ${parent} before then only with a question you cannot continue without, since anything sent earlier reaches it twice.`,
 	].join(" ");
 }
 /** The flags `/delegate` takes before the task. */
@@ -114,6 +115,8 @@ type Start = {
 	skipped: Skipped[];
 	/** Lines for the parent, such as a quota reading that failed. */
 	notices: string[];
+	/** The candidates after `model`, for the delegate to move to on a usage limit; empty for an explicit model. */
+	rest: string[];
 	thinking: string;
 	label?: string;
 	autoExit: boolean;
@@ -238,7 +241,7 @@ async function chooseModel(
 	agent: Agent,
 	models: ModelRegistry,
 	proactive: Proactive,
-): Promise<{ model: string; skipped: Skipped[]; notices: string[] }> {
+): Promise<{ model: string; skipped: Skipped[]; notices: string[]; rest: string[] }> {
 	const candidates = explicit !== undefined ? [explicit] : [agent.model, ...agent.fallback];
 	const skipped: Skipped[] = [];
 	const notices: string[] = [];
@@ -262,7 +265,7 @@ async function chooseModel(
 			if (checked.notice !== undefined && !notices.includes(checked.notice)) notices.push(checked.notice);
 			mark = activeMark(models, provider, id) ?? checked.mark;
 		}
-		if (mark === undefined) return { model, skipped, notices };
+		if (mark === undefined) return { model, skipped, notices, rest: candidates.slice(candidates.indexOf(model) + 1) };
 		const what = mark.scope.includes("/") ? `model ${mark.scope}` : `provider ${mark.scope}`;
 		const until = new Date(mark.clearsAt).toISOString();
 		skipped.push({
@@ -273,11 +276,18 @@ async function chooseModel(
 	}
 	if (skipped.length === 1) {
 		const [only] = skipped;
-		throw new Error(
-			only.why.startsWith("usage-limited")
-				? `${only.model} is ${only.reason}. Clear marks with /delegate-clear.`
-				: only.reason,
-		);
+		if (!only.why.startsWith("usage-limited")) throw new Error(only.reason);
+		// An explicit model is never substituted, but the refusal names the agent's models still open.
+		const open = [agent.model, ...agent.fallback].filter((model) => {
+			if (model === only.model || modelProblem(model, models) !== undefined) return false;
+			const slash = model.indexOf("/");
+			return activeMark(models, model.slice(0, slash), model.slice(slash + 1)) === undefined;
+		});
+		const hint =
+			explicit !== undefined && open.length > 0
+				? ` Omit model to launch ${agent.name} on ${open[0]}${open.length > 1 ? ` (also open: ${open.slice(1).join(", ")})` : ""}, or clear marks with /delegate-clear.`
+				: " Clear marks with /delegate-clear.";
+		throw new Error(`${only.model} is ${only.reason}.${hint}`);
 	}
 	throw new Error(
 		`no model is available for agent ${agent.name}:\n${skipped.map((item) => `- ${item.model}: ${item.reason}`).join("\n")}\nClear marks with /delegate-clear.`,
@@ -399,7 +409,7 @@ export default function delegate(
 		}
 		if (request.task.trim() === "") throw new Error("a task is required");
 		const thinking = request.thinking ?? agent.thinking;
-		const { model, skipped, notices } = await chooseModel(request.model, agent, models, proactive);
+		const { model, skipped, notices, rest } = await chooseModel(request.model, agent, models, proactive);
 		const badThinking = thinkingProblem(thinking);
 		if (badThinking !== undefined) throw new Error(badThinking);
 		const badLabel = request.label === undefined ? undefined : labelProblem(request.label);
@@ -409,6 +419,7 @@ export default function delegate(
 			model,
 			skipped,
 			notices,
+			rest,
 			thinking,
 			label: request.label,
 			autoExit: request.autoExit ?? agent.autoExit,
@@ -459,6 +470,7 @@ export default function delegate(
 			[PARENT_ENV]: parent,
 			[AUTO_EXIT_ENV]: start.autoExit ? "1" : "0",
 		};
+		if (start.rest.length > 0) env[FALLBACK_ENV] = start.rest.join(",");
 		const sessionDir = process.env[SESSION_DIR_ENV];
 		if (sessionDir !== undefined && sessionDir !== "") env[SESSION_DIR_ENV] = sessionDir;
 		// Listeners may only append to `args` and add to `env`; there is no veto.

package/src/limits.ts

@@ -85,7 +85,7 @@ export function activeMark(models: Models, provider: string, id: string, now = D
 }
 
 const LIMIT_PATTERN =
-	/GoUsageLimitError|FreeUsageLimitError|Monthly usage limit reached|insufficient_quota|quota exceeded|subscription_sharing_usage_limit_exceeded|usage_limit_reached|usage limit reached|rate_limit_error/i;
+	/GoUsageLimitError|FreeUsageLimitError|Monthly usage limit reached|insufficient_quota|quota exceeded|subscription_sharing_usage_limit_exceeded|usage_limit_reached|usage limit reached|reached (?:their|your) .{0,40}usage limit|rate_limit_error/i;
 
 /** The reset time an error text states: "try again in N units", "retry after", or a `resets_at` field. */
 function statedReset(message: string, now: number): number | undefined {

package/src/results.ts

@@ -7,7 +7,13 @@
 import { readdirSync } from "node:fs";
 import { join } from "node:path";
 
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+	type ExtensionAPI,
+	type ExtensionContext,
+	keyText,
+	type MessageRenderer,
+} from "@earendil-works/pi-coding-agent";
+import { Box, Text } from "@earendil-works/pi-tui";
 
 import { readMarks } from "./limits.ts";
 
@@ -159,8 +165,8 @@ export function findSession(dir: string | undefined, id: string): string | undef
 	return name === undefined ? undefined : join(dir, name);
 }
 
-/** The line naming a usage-limit mark this delegation's failure recorded, if any. */
-function limitLine(id: string): string | undefined {
+/** The line naming a usage-limit mark this delegation recorded, if any; a `done` delegation finished on a fallback. */
+function limitLine(id: string, status: string): string | undefined {
 	const now = Date.now();
 	const mark = readMarks(now).find((item) => item.delegations.includes(id));
 	if (mark === undefined) return undefined;
@@ -168,7 +174,7 @@ function limitLine(id: string): string | undefined {
 	const until = new Date(mark.clearsAt).toISOString();
 	return `Usage limit: the delegate hit a usage limit on ${scope}; ${
 		mark.clearsAt > now ? `it is marked until ${until} and later delegations skip it.` : `it was marked until ${until}.`
-	}`;
+	}${status === "done" ? " It finished on a fallback model; its session names which." : ""}`;
 }
 
 /** The one message the parent sees for a settled delegation. */
@@ -190,7 +196,7 @@ function resultText(delegation: Delegation, payload: Inbound, session: string |
 	const cut = cap(reply.body, BODY_CAP);
 	const result =
 		cut === undefined ? reply.body : `${cut}\n[delegate] Body cut at 32 KiB; the full envelope is ${payload.path}`;
-	const limit = reply.status === "failed" ? limitLine(delegation.id) : undefined;
+	const limit = reply.status === "stopped" ? undefined : limitLine(delegation.id, reply.status);
 	return [
 		`[delegate] Result from ${delegation.agent} (${delegation.model}), delegation ${delegation.id}, request ${delegation.requestId}.`,
 		`Status: ${reply.status}`,
@@ -203,7 +209,24 @@ function resultText(delegation: Delegation, payload: Inbound, session: string |
 	].join("\n");
 }
 
+/**
+ * Collapsed, a delegate message shows its first two lines (who answered and the
+ * status) and a hint; expanded, Pi's default rendering of the whole message.
+ * The model always gets the full content. Ctrl+O toggles it with tool output.
+ */
+export const renderMessage: MessageRenderer = (message, { expanded, outputPad }, theme) => {
+	if (expanded || typeof message.content !== "string") return undefined;
+	const lines = message.content.split("\n");
+	const shown = lines.slice(0, 2).join("\n");
+	const hint =
+		lines.length > 2 ? `\n${theme.fg("dim", keyText("app.tools.expand"))}${theme.fg("muted", " to expand")}` : "";
+	const box = new Box(outputPad, 1, (text) => theme.bg("customMessageBg", text));
+	box.addChild(new Text(`${theme.fg("customMessageText", shown)}${hint}`, 0, 0));
+	return box;
+};
+
 export function createResults(pi: ExtensionAPI): Results {
+	pi.registerMessageRenderer(CUSTOM_TYPE, renderMessage);
 	/** Every recorded delegation by its id, in the order recorded. */
 	const byId = new Map<string, Recorded>();
 	/** The same records by their request's envelope id, for matching replies. */
@@ -312,9 +335,10 @@ export function createResults(pi: ExtensionAPI): Results {
 		const delegation = byRequest.get(requestId) as Recorded;
 		shown.add(reply.id);
 		const session = findSession(ctx?.sessionManager.getSessionDir(), delegation.id);
+		// Steer, not follow-up: a busy parent gets the result before its next model call, not after it has answered.
 		pi.sendMessage(
 			{ customType: CUSTOM_TYPE, content: resultText(delegation, payload, session), display: true },
-			{ triggerTurn: true, deliverAs: "followUp" },
+			{ triggerTurn: true, deliverAs: "steer" },
 		);
 		const result: Result = {
 			status: reply.status,

package/src/tracking.ts

@@ -90,7 +90,7 @@ function stateLine(state: DelegationState, record: Recorded): string {
 		case "gone":
 			return "closed without a result — the window is gone and no reply arrived; a late reply would make it done";
 		case "done":
-			return `done — result status: ${record.result?.status ?? "unknown"}`;
+			return `done — result status: ${record.result?.status ?? "unknown"}; the result reaches this session as a [delegate] message on its own`;
 		case "closed":
 			return "closed — delegation_close recorded it";
 		case "window-closed":