pi-roundtable-coding 0.7.3 → 0.7.5

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## [Unreleased]
 
+## [0.7.5] - 2026-10-03
+
+- Add `workerBlockText`, `limits` and `diagnosticChars`; git, gh and worker error text and the report and held-action bounds can be raised or lifted by the host.
+
+## [0.7.4] - 2026-10-03
+
+- Add `toolText` and `presentation.list`, accept a 7–40 character sha prefix in `repo_push`, name git and gh stderr (scrubbed) in failures, carry a worker's own error text into the report, restore the earlier timeout, stop and refusal wording, stop listing declined calls as held, and report the channels the service works for.
+
 ## [0.7.3] - 2026-10-03
 
 - Hook caller model/thinking/origin/channel, owner policy, clone adoption, threaded approvals and report formatting through options, and add `pushHoldText` for the held `repo_push` card.

package/README.md

@@ -121,7 +121,7 @@ Without `threads`, the resolved report channel's prompts are used.
 `timeoutMs` must be positive and finite, and at most 2,147,483,647 ms to fit the host timer.
 An approved call runs; a declined, expired, missing or failed card blocks it and instructs the worker not to retry or work around the refusal.
 Unapproved actions appear in the report rather than running later automatically.
-Worker answers are capped at 20,000 characters; the Held list keeps ten entries of at most 1,000 characters each, with explicit truncation and omission notices.
+By default worker answers are capped at 20,000 characters and the Held list keeps ten entries of at most 1,000 characters each, with explicit truncation and omission notices; `limits` changes each bound.
 Worker failures expose only a structured exit category and numeric code, never stderr or provider diagnostics.
 Card expiration is determined by the host's surface implementation, not this package.
 
@@ -166,11 +166,15 @@ The `CODING` service exposes `shelf: RepoShelf` and `desk: CodingDesk` for trust
 | `adoptClones` | `[]` | Startup `{ from, repo }` moves of standalone clones; existing shelf destinations are never replaced. |
 | `resolveRun` | configured model/thinking, caller channel | Per-caller model, thinking, report channel and optional thread origin. |
 | `postChangeReport` | caller surface reply | Post the record using the calling identity and channel. |
-| `presentation` | English package text | Separate change-report post/result text and task-start/omitted-skill wording. |
+| `presentation` | English package text | Separate change-report post/result text, task-start/omitted-skill wording, and the `repo_list` result (`list(repos, { shelfDir, fetched })`). |
+| `toolText` | package wording | Trusted description and argument descriptions for each repository tool, as `{ repo_task: { description, parameters: { task: "…" } } }`; it never changes a tool's arguments or approval rules. |
 | `threads` | none | Public `DispatchThreads`-compatible progress and approval thread port. |
 | `threadText` | English package text | Thread introduction, held-action notice, approval title and final report. |
 | `workerWorkspace` | individual clone | Trusted shell-policy write boundary; not an OS sandbox. |
 | `workerPrompt` | generic worker instructions | Trusted standing prompt replacement; it cannot bypass approval or cleanup. |
+| `workerBlockText` | "The owner declined / has not approved this call. Do not retry it or work around it; list it under Held in your report." | Trusted wording of what the worker reads when a call is declined or held, from `(answer, action)`; it never changes who is held, and the desk lists only unanswered calls as held. |
+| `limits` | 20,000 report characters, 10 held entries of 1,000 characters | `{ reportChars?, heldEntries?, heldChars? }`: what a report keeps of a long run; each is a whole number of at least 1, or `Infinity` for no bound. |
+| `diagnosticChars` | `600` | Longest git, gh and worker error text kept in a failure; a whole number of at least 1, or `Infinity`. |
 | `skipUnavailableCarriedSkills` | `false` | Skip and disclose unavailable implicit skills; explicit skill requests still refuse them. |
 | `workerPackages` | `[]` | Absolute installed extension paths. |
 | `agentDir` | Pi host directory | Pi credentials and model configuration. |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable-coding",
-	"version": "0.7.3",
+	"version": "0.7.5",
 	"description": "Repository shelves and owner-approved Pi coding workers for pi-roundtable",
 	"type": "module",
 	"license": "MIT",
@@ -44,7 +44,7 @@
 		"@earendil-works/pi-ai": ">=1.0.0 <2",
 		"@biomejs/biome": "2.5.15",
 		"@types/bun": "1.4.2",
-		"pi-roundtable": "0.7.3",
+		"pi-roundtable": "0.7.5",
 		"typescript": "7.0.2"
 	}
 }

package/src/coding-desk.ts

@@ -64,6 +64,26 @@ export interface CodingDeskOptions {
 	deliver(result: CodingResult): Promise<void>;
 	logger: Logger;
 	timeoutMs?: number;
+	limits?: CodingLimits;
+}
+/** What a coding report keeps of a long run; each is a count of characters or entries, or `Infinity` for no bound. */
+export interface CodingLimits {
+	/** Longest worker report, and longest thread report; default 20,000 characters. */
+	reportChars?: number;
+	/** Held actions listed in the report, the rest counted; default 10. */
+	heldEntries?: number;
+	/** Longest held-action entry; default 1,000 characters. */
+	heldChars?: number;
+}
+export function checkLimit(name: string, value: number | undefined): void {
+	if (
+		value !== undefined &&
+		value !== Number.POSITIVE_INFINITY &&
+		(!Number.isSafeInteger(value) || value < 1)
+	)
+		throw new Error(
+			`${name} must be a whole number of at least 1, or Infinity; got ${value}.`,
+		);
 }
 export const MAX_CODING_TASK_CHARS = 8_000;
 const MAX_REPORT_CHARS = 20_000;
@@ -121,18 +141,26 @@ export class CodingDesk {
 	): Promise<CodingJob> {
 		if (this.#stopped) throw new AgentError("The coding desk is stopped.");
 		const task = request.task.trim();
-		if (!task || task.length > MAX_CODING_TASK_CHARS)
+		if (!task) throw new AgentError("The task is required.");
+		if (task.length > MAX_CODING_TASK_CHARS)
 			throw new AgentError(
-				`The task must contain 1–${MAX_CODING_TASK_CHARS} characters.`,
+				`The task is ${task.length} characters; keep it within ${MAX_CODING_TASK_CHARS}.`,
 			);
 		const dir = this.#options.shelf.dirOf(request.repo);
-		this.checkIdle(request.repo);
-		if (
-			[...this.#running.values()].filter(
-				({ job }) => job.channel === request.channel,
-			).length >= 3
-		)
-			throw new AgentError("This channel already has three coding workers.");
+		const busy = [...this.#running.values()].find(
+			({ job }) => job.repo === request.repo,
+		);
+		if (busy)
+			throw new AgentError(
+				`Coding task #${busy.job.id} is still working in ${request.repo}; one worker runs per repository.`,
+			);
+		const inChannel = [...this.#running.values()].filter(
+			({ job }) => job.channel === request.channel,
+		).length;
+		if (inChannel >= 3)
+			throw new AgentError(
+				`This channel already has ${inChannel} coding workers running; wait for one to report back.`,
+			);
 		const job: CodingJob = {
 			...request,
 			task,
@@ -174,13 +202,17 @@ export class CodingDesk {
 		const slot = promptSlot();
 		const held: string[] = [];
 		let omittedHeld = 0;
+		const maxReport = this.#options.limits?.reportChars ?? MAX_REPORT_CHARS;
+		const maxHeldEntries =
+			this.#options.limits?.heldEntries ?? MAX_HELD_ENTRIES;
+		const maxHeldChars = this.#options.limits?.heldChars ?? MAX_HELD_CHARS;
 		let cancel = () => {};
 		let timedOut = false;
 		let outcome: CodingResult["outcome"];
 		try {
 			job.startHead = (await shelf.state(job.repo)).head;
 			if (controller.signal.aborted)
-				throw new AgentError("The worker was stopped.");
+				throw new AgentError("the worker was stopped");
 			if (threads) {
 				try {
 					const thread = await threads.open(
@@ -197,7 +229,7 @@ export class CodingDesk {
 				}
 			}
 			if (controller.signal.aborted)
-				throw new AgentError("The worker was stopped.");
+				throw new AgentError("the worker was stopped");
 			slot.bind(
 				threads
 					? job.thread && prompts?.(job.thread.channel)
@@ -222,11 +254,12 @@ export class CodingDesk {
 				} catch {
 					/* A failed card never authorizes the call. */
 				}
-				if (answer !== "approved") {
-					if (held.length < MAX_HELD_ENTRIES) {
+				// A call the owner declined is settled, not held for the report.
+				if (answer === "held") {
+					if (held.length < maxHeldEntries) {
 						const entry = bounded(
-							`${answer}: ${call.action}: ${call.tool} ${call.input}`,
-							MAX_HELD_CHARS,
+							`${call.action}: ${call.tool} ${call.input}`,
+							maxHeldChars,
 						);
 						held.push(entry);
 						try {
@@ -246,22 +279,22 @@ export class CodingDesk {
 				review,
 			);
 			if (controller.signal.aborted)
-				throw new AgentError("The worker was stopped.");
-			outcome = { ok: true, report: bounded(report, MAX_REPORT_CHARS) };
+				throw new AgentError("the worker was stopped");
+			outcome = { ok: true, report: bounded(report, maxReport) };
 		} catch (error) {
-			// Only structured, fixed diagnostics can cross the worker boundary.
+			// The host's own refusals and the worker's scrubbed, bounded error text reach the report.
 			let message =
 				"The worker failed; inspect the clone and worker configuration on the host.";
+			if (error instanceof AgentError) message = error.message;
 			if (error instanceof CodingWorkerFailure) {
-				message = error.message;
 				this.#options.logger.warn(
 					{ job: job.id, category: error.category, exitCode: error.exitCode },
 					"Coding worker failed.",
 				);
 			}
-			if (controller.signal.aborted) message = "The worker was stopped.";
+			if (controller.signal.aborted) message = "the worker was stopped";
 			if (timedOut)
-				message = `Work timeout after ${timeoutMs} ms (owner wait excluded).`;
+				message = `the worker ran out of time (${Math.round(timeoutMs / 60_000)} minutes)`;
 			outcome = { ok: false, error: message };
 		} finally {
 			cancel();
@@ -293,7 +326,7 @@ export class CodingDesk {
 				bounded(
 					threadText?.report?.(result) ??
 						codingReport(result, job.startedAt.toISOString()),
-					MAX_REPORT_CHARS,
+					maxReport,
 				),
 			);
 		} catch {

package/src/coding-plugin.ts

@@ -21,9 +21,11 @@ import { Type } from "typebox";
 import {
 	CodingDesk,
 	type CodingJob,
+	type CodingLimits,
 	type CodingResult,
 	type CodingThreadText,
 	type CodingWorker,
+	checkLimit,
 	codingReport,
 	MAX_CODING_TASK_CHARS,
 } from "./coding-desk.ts";
@@ -32,6 +34,7 @@ import {
 	type ChangeReport,
 	type CloneCommand,
 	RepoShelf,
+	type RepoSummary,
 	reportPost,
 } from "./repo-shelf.ts";
 
@@ -46,7 +49,24 @@ export interface CodingRun {
 	channel: ChannelKey;
 	origin?: ChannelKey;
 }
+export type RepoToolName =
+	| "repo_list"
+	| "repo_add"
+	| "repo_change_report"
+	| "repo_push"
+	| "repo_task";
+/** Trusted wording of one repository tool, as the model reads it; unset fields keep the defaults. */
+export interface CodingToolText {
+	description?: string;
+	/** Argument descriptions by argument name. */
+	parameters?: Record<string, string>;
+}
 export interface CodingPresentation {
+	/** The repo_list result; unset: the managed clones as JSON. */
+	list?(
+		repos: (RepoSummary & { skills: string[] })[],
+		context: { shelfDir: string; fetched: boolean },
+	): string;
 	/** Separate the owner's posted record from the model's shipping instructions. */
 	changeReport?(
 		report: ChangeReport,
@@ -73,10 +93,18 @@ export interface CodingOptions {
 	/** Post change reports in the caller's identity/channel rather than the default surface. */
 	postChangeReport?: (turn: ToolTurn, text: string) => Promise<void>;
 	presentation?: CodingPresentation;
+	/** Trusted wording of the repository tools' descriptions and arguments. */
+	toolText?: Partial<Record<RepoToolName, CodingToolText>>;
 	threads?: Pick<DispatchThreads, "open">;
 	threadText?: CodingThreadText;
 	workerWorkspace?: string;
 	workerPrompt?: (dir: string) => string;
+	/** How much of a long run a report keeps; see `CodingLimits`. */
+	limits?: CodingLimits;
+	/** Longest git, gh and worker error text kept in a failure, in characters; default 600. */
+	diagnosticChars?: number;
+	/** Trusted wording of what the worker reads when a call is declined or held; see `PiCodingWorkerOptions.blockText`. */
+	workerBlockText?: (answer: "declined" | "held", action: string) => string;
 	/** Opt in to skipping unavailable implicit skills; explicit requests always fail closed. */
 	skipUnavailableCarriedSkills?: boolean;
 	/** Absolute installed extension package paths. Default: none. */
@@ -106,6 +134,16 @@ export function coding(options: CodingOptions) {
 	if (!options.shelfDir.trim()) throw new PluginError("shelfDir is required.");
 	if (!/^[^/\s]+\/\S+$/.test(options.model))
 		throw new PluginError("model must be provider/model-id.");
+	try {
+		checkLimit("limits.reportChars", options.limits?.reportChars);
+		checkLimit("limits.heldEntries", options.limits?.heldEntries);
+		checkLimit("limits.heldChars", options.limits?.heldChars);
+		checkLimit("diagnosticChars", options.diagnosticChars);
+	} catch (error) {
+		throw new PluginError(
+			error instanceof Error ? error.message : String(error),
+		);
+	}
 	const ownerRepos = new Set(options.ownerRepos ?? []);
 	for (const repo of ownerRepos) checkRepoName(repo);
 	const ownerOwned = (repo: string): boolean => {
@@ -116,7 +154,9 @@ export function coding(options: CodingOptions) {
 		name: "coding",
 		provides: [CODING],
 		setup(context) {
-			const shelf = new RepoShelf(options.shelfDir, options.clone);
+			const shelf = new RepoShelf(options.shelfDir, options.clone, {
+				diagnosticChars: options.diagnosticChars,
+			});
 			for (const adoption of options.adoptClones ?? [])
 				shelf.adopt(adoption.from, adoption.repo);
 			const skills = context.services.find(SKILLS);
@@ -127,6 +167,8 @@ export function coding(options: CodingOptions) {
 					agentDir: options.agentDir,
 					workspace: options.workerWorkspace,
 					prompt: options.workerPrompt,
+					blockText: options.workerBlockText,
+					diagnosticChars: options.diagnosticChars,
 					holds: (tool, input, scope) =>
 						options.holds?.(tool, input, scope) ??
 						context.sessions().holds(tool, input, scope),
@@ -135,6 +177,7 @@ export function coding(options: CodingOptions) {
 				shelf,
 				worker,
 				timeoutMs: options.timeoutMs,
+				limits: options.limits,
 				logger: context.logger,
 				threads: options.threads,
 				threadText: options.threadText,
@@ -170,14 +213,21 @@ export function coding(options: CodingOptions) {
 				}
 			}
 			context.services.provide(CODING, { shelf, desk });
-			const repoSchema = Type.String({
-				description: "A managed repository, owner/repo.",
-			});
+			const textOf = (tool: RepoToolName) => options.toolText?.[tool];
+			const describe = (tool: RepoToolName, fallback: string) =>
+				textOf(tool)?.description ?? fallback;
+			const about = (tool: RepoToolName, name: string, fallback?: string) => {
+				const description = textOf(tool)?.parameters?.[name] ?? fallback;
+				return description ? { description } : {};
+			};
+			const repoSchema = (tool: RepoToolName) =>
+				Type.String(about(tool, "repo", "A managed repository, owner/repo."));
 			return {
 				services: [
 					{
 						name: "coding-desk",
-						busy: () => desk.busy(),
+						// The host names the channels whose work a shutdown waits for or aborts.
+						busy: () => desk.runningChannels(),
 						stop: () => desk.stop(),
 					},
 				],
@@ -200,30 +250,39 @@ export function coding(options: CodingOptions) {
 					defineTool({
 						name: "repo_list",
 						minTier: "owner",
-						description:
+						description: describe(
+							"repo_list",
 							"List managed clones, branch, upstream counts, dirty files, last commit, summary, CI hints and linked skills. Fetch first only when requested.",
-						parameters: Type.Object({ fetch: Type.Optional(Type.Boolean()) }),
+						),
+						parameters: Type.Object({
+							fetch: Type.Optional(Type.Boolean(about("repo_list", "fetch"))),
+						}),
 						run: ({ fetch }) =>
 							refusal(async () => {
-								const repos = await shelf.list(fetch === true);
+								const repos = (await shelf.list(fetch === true)).map(
+									(repo) => ({
+										...repo,
+										skills: skills?.linkedFrom(repo.repo) ?? [],
+									}),
+								);
+								if (options.presentation?.list)
+									return options.presentation.list(repos, {
+										shelfDir: shelf.dir,
+										fetched: fetch === true,
+									});
 								return repos.length
-									? JSON.stringify(
-											repos.map((repo) => ({
-												...repo,
-												skills: skills?.linkedFrom(repo.repo) ?? [],
-											})),
-											null,
-											2,
-										)
+									? JSON.stringify(repos, null, 2)
 									: `No managed repositories in ${shelf.dir}; use repo_add.`;
 							}),
 					}),
 					defineTool({
 						name: "repo_add",
 						minTier: "owner",
-						description:
+						description: describe(
+							"repo_add",
 							"Clone owner/repo into the shelf using the host's Git login (GitHub CLI by default).",
-						parameters: Type.Object({ repo: repoSchema }),
+						),
+						parameters: Type.Object({ repo: repoSchema("repo_add") }),
 						run: ({ repo }) =>
 							refusal(
 								async () => `Cloned ${repo} into ${await shelf.add(repo)}.`,
@@ -232,9 +291,13 @@ export function coding(options: CodingOptions) {
 					defineTool({
 						name: "repo_change_report",
 						minTier: "owner",
-						description:
+						description: describe(
+							"repo_change_report",
 							"Fetch and report commits and changed files for the default branch. Requires a clean, ahead-only clone. Review checks before requesting this report.",
-						parameters: Type.Object({ repo: repoSchema }),
+						),
+						parameters: Type.Object({
+							repo: repoSchema("repo_change_report"),
+						}),
 						run: ({ repo }, turn) =>
 							refusal(() =>
 								ship(repo, async () => {
@@ -260,11 +323,16 @@ export function coding(options: CodingOptions) {
 					defineTool({
 						name: "repo_push",
 						minTier: "owner",
-						description:
-							"Push the exact full SHA from the latest change report to its default branch, without force. Held for owner approval unless the trusted host policy explicitly marks the clone owner-owned.",
+						description: describe(
+							"repo_push",
+							"Push the SHA from the latest change report to its default branch, without force. Held for owner approval unless the trusted host policy explicitly marks the clone owner-owned.",
+						),
 						parameters: Type.Object({
-							repo: repoSchema,
-							sha: Type.String({ pattern: "^[0-9a-f]{40}$" }),
+							repo: repoSchema("repo_push"),
+							sha: Type.String({
+								pattern: "^[0-9a-f]{7,40}$",
+								...about("repo_push", "sha"),
+							}),
 						}),
 						hold: ({ repo, sha }) =>
 							ownerOwned(repo)
@@ -283,15 +351,20 @@ export function coding(options: CodingOptions) {
 					defineTool({
 						name: "repo_task",
 						minTier: "owner",
-						description:
+						description: describe(
+							"repo_task",
 							"Start one background Pi coding worker in a clone. The worker reads repository instructions, edits, checks and commits; shipping uses a separate report and approval. Report returns to this channel.",
+						),
 						parameters: Type.Object({
-							repo: repoSchema,
+							repo: repoSchema("repo_task"),
 							task: Type.String({
 								minLength: 1,
 								maxLength: MAX_CODING_TASK_CHARS,
+								...about("repo_task", "task"),
 							}),
-							skills: Type.Optional(Type.Array(Type.String())),
+							skills: Type.Optional(
+								Type.Array(Type.String(), about("repo_task", "skills")),
+							),
 						}),
 						run: ({ repo, task, skills: names }, turn) =>
 							refusal(async () => {

package/src/index.ts

@@ -1,6 +1,7 @@
 export type {
 	CodingDeskOptions,
 	CodingJob,
+	CodingLimits,
 	CodingResult,
 	CodingThreadText,
 	CodingWorker,
@@ -12,6 +13,8 @@ export type {
 	CodingPresentation,
 	CodingRun,
 	CodingService,
+	CodingToolText,
+	RepoToolName,
 } from "./coding-plugin.ts";
 export { CODING, coding } from "./coding-plugin.ts";
 export type { PiCodingWorkerOptions } from "./pi-coding-worker.ts";

package/src/pi-coding-worker.ts

@@ -16,6 +16,13 @@ export interface PiCodingWorkerOptions {
 	workspace?: string;
 	/** Trusted host standing prompt, replacing the generic worker instructions. */
 	prompt?: (dir: string) => string;
+	/**
+	 * Trusted wording of what the worker reads when a call is not approved, given what the call
+	 * would do. Default: the owner declined or has not approved it; list it under Held in the report.
+	 */
+	blockText?: (answer: "declined" | "held", action: string) => string;
+	/** Longest worker error text kept for the report, in characters; default 600. */
+	diagnosticChars?: number;
 }
 interface WorkerMessage {
 	type: string;
@@ -23,6 +30,7 @@ interface WorkerMessage {
 	tool?: string;
 	input?: Record<string, unknown>;
 	report?: string;
+	message?: string;
 }
 function isMessage(value: unknown): value is WorkerMessage {
 	return (
@@ -46,9 +54,10 @@ export class PiCodingWorker implements CodingWorker {
 	): Promise<string> {
 		if (process.platform === "win32")
 			throw new AgentError("Coding workers require a POSIX host.");
-		if (signal.aborted) throw new AgentError("The worker was stopped.");
+		if (signal.aborted) throw new AgentError("the worker was stopped");
 		const prompt = this.#options.prompt?.(job.dir);
 		let report: string | undefined;
+		let failure: string | undefined;
 		const child = Bun.spawn(
 			[
 				process.execPath,
@@ -76,6 +85,16 @@ export class PiCodingWorker implements CodingWorker {
 						typeof value.report === "string"
 					) {
 						report = value.report;
+					} else if (
+						value.type === "failure" &&
+						typeof value.message === "string"
+					) {
+						failure = value.message.slice(
+							0,
+							this.#options.diagnosticChars === undefined
+								? 2_000
+								: this.#options.diagnosticChars * 4,
+						);
 					} else if (
 						value.type === "call" &&
 						Number.isSafeInteger(value.id) &&
@@ -86,6 +105,7 @@ export class PiCodingWorker implements CodingWorker {
 						const { id, tool, input } = value;
 						void (async () => {
 							let answer: HeldCallAnswer = "held";
+							let reason: string | undefined;
 							try {
 								const context = {
 									workspace: this.#options.workspace ?? job.dir,
@@ -101,12 +121,19 @@ export class PiCodingWorker implements CodingWorker {
 												action,
 											})
 										: "approved";
+									if (action && answer !== "approved")
+										reason = this.#options.blockText?.(answer, action);
 								}
 							} catch {
 								/* Fail closed. */
 							}
 							if (!signal.aborted && child.exitCode === null)
-								proc.send({ type: "answer", id, answer });
+								proc.send({
+									type: "answer",
+									id,
+									answer,
+									...(reason ? { reason } : {}),
+								});
 						})();
 					}
 				},
@@ -124,7 +151,13 @@ export class PiCodingWorker implements CodingWorker {
 			if (signal.aborted) kill();
 			const code = await child.exited;
 			if (signal.aborted) throw new CodingWorkerFailure("stopped");
-			if (code !== 0) throw new CodingWorkerFailure("exit", code);
+			if (code !== 0)
+				throw new CodingWorkerFailure(
+					"exit",
+					code,
+					failure,
+					this.#options.diagnosticChars,
+				);
 			if (!report?.trim()) throw new CodingWorkerFailure("missing-report");
 			return report;
 		} finally {

package/src/repo-shelf.ts

@@ -12,7 +12,7 @@ import {
 	renameSync,
 } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
-import { AgentError, checkRepoName } from "pi-roundtable/kit";
+import { AgentError, checkRepoName, scrubDiagnostic } from "pi-roundtable/kit";
 
 /** What a clone would push to its default branch (repos-and-skills spec behavior 10). */
 export interface ChangeReport {
@@ -87,25 +87,28 @@ async function run(
 	return { out: out.trimEnd(), err: err.trim(), code };
 }
 
-/** Clones with gh, which authenticates with the host's GH_TOKEN. */
-export const ghClone: CloneCommand = async (repo, dir) => {
-	checkRepoName(repo);
-	if (repo.startsWith("-"))
-		throw new AgentError("Repository owner cannot start with a dash.");
-	const { code } = await run([
-		"gh",
-		"repo",
-		"clone",
-		repo,
-		dir,
-		"--",
-		"--quiet",
-	]);
-	if (code !== 0)
-		throw new AgentError(
-			`Cloning ${repo} failed (exit ${code}); check the host's Git login.`,
-		);
-};
+/** Clones with gh, which authenticates with the host's GH_TOKEN; a failure's stderr is cut at `diagnosticChars`. */
+const ghCloneWith =
+	(diagnosticChars?: number): CloneCommand =>
+	async (repo, dir) => {
+		checkRepoName(repo);
+		if (repo.startsWith("-"))
+			throw new AgentError("Repository owner cannot start with a dash.");
+		const { err, code } = await run([
+			"gh",
+			"repo",
+			"clone",
+			repo,
+			dir,
+			"--",
+			"--quiet",
+		]);
+		if (code !== 0)
+			throw new AgentError(
+				`Cloning ${repo} failed: ${scrubDiagnostic(err, diagnosticChars) || `exit ${code}`}`,
+			);
+	};
+export const ghClone: CloneCommand = ghCloneWith();
 
 const MAX_METADATA_BYTES = 65_536;
 
@@ -175,9 +178,16 @@ export class RepoShelf {
 	readonly #reports = new Map<string, ChangeReport>();
 	readonly #adding = new Set<string>();
 
-	constructor(dir: string, clone: CloneCommand = ghClone) {
+	readonly #diagnosticChars: number | undefined;
+
+	constructor(
+		dir: string,
+		clone?: CloneCommand,
+		options: { diagnosticChars?: number | undefined } = {},
+	) {
 		this.dir = resolve(dir);
-		this.#clone = clone;
+		this.#diagnosticChars = options.diagnosticChars;
+		this.#clone = clone ?? ghCloneWith(options.diagnosticChars);
 	}
 
 	/** Adopt an existing standalone clone at startup; an existing destination is never replaced. */
@@ -328,7 +338,7 @@ export class RepoShelf {
 	/** A synchronous hold description from the latest report, safe to show on an owner card. */
 	pushDescription(repo: string, sha: string): string {
 		const report = this.#reports.get(repo);
-		if (!report || report.sha !== sha)
+		if (!report || !/^[0-9a-f]{7,40}$/.test(sha) || !report.sha.startsWith(sha))
 			return `Push ${repo} commit ${sha}; request a fresh change report first`;
 		return `Push ${repo} commit ${sha} to ${report.target}, branch ${report.branch}`;
 	}
@@ -338,7 +348,11 @@ export class RepoShelf {
 		const dir = this.dirOf(repo);
 		const head = await this.#git(dir, "rev-parse", "HEAD");
 		const report = this.#reports.get(repo);
-		if (!report || report.sha !== sha || head !== sha)
+		if (
+			!/^[0-9a-f]{7,40}$/.test(sha) ||
+			!report?.sha.startsWith(sha) ||
+			head !== report.sha
+		)
 			throw new AgentError(
 				`${sha} is not HEAD of ${repo} (HEAD is ${head.slice(0, 12)}); report again with repo_change_report.`,
 			);
@@ -476,10 +490,10 @@ export class RepoShelf {
 	}
 
 	async #git(dir: string, ...args: string[]): Promise<string> {
-		const { out, code } = await run(["git", "-C", dir, ...args]);
+		const { out, err, code } = await run(["git", "-C", dir, ...args]);
 		if (code !== 0)
 			throw new AgentError(
-				`git ${args[0]} failed (exit ${code}); check the clone and the host's Git login.`,
+				`git ${args[0]} failed in ${dir}: ${scrubDiagnostic(err, this.#diagnosticChars) || `exit ${code}`}`,
 			);
 		return out;
 	}

package/src/worker-entry.ts

@@ -31,7 +31,10 @@ export function codingWorkerPrompt(dir: string): string {
 		"Report changes and reasons, commits, checks and outcomes, held actions, and remaining work.",
 	].join("\n\n");
 }
-const answers = new Map<number, (answer: HeldCallAnswer) => void>();
+const answers = new Map<
+	number,
+	(answer: HeldCallAnswer, reason?: string) => void
+>();
 let nextId = 1;
 let started = false;
 async function run({
@@ -76,8 +79,11 @@ async function run({
 				factory: (pi) => {
 					pi.on("tool_call", async (event) => {
 						const id = nextId++;
-						const answer = await new Promise<HeldCallAnswer>((resolve) => {
-							answers.set(id, resolve);
+						const { answer, reason } = await new Promise<{
+							answer: HeldCallAnswer;
+							reason?: string | undefined;
+						}>((resolve) => {
+							answers.set(id, (answer, reason) => resolve({ answer, reason }));
 							process.send?.({
 								type: "call",
 								id,
@@ -88,7 +94,9 @@ async function run({
 						if (answer !== "approved")
 							return {
 								block: true,
-								reason: `The owner ${answer === "declined" ? "declined" : "has not approved"} this call. Do not retry it or work around it; list it under Held in your report.`,
+								reason:
+									reason ??
+									`The owner ${answer === "declined" ? "declined" : "has not approved"} this call. Do not retry it or work around it; list it under Held in your report.`,
 							};
 						return undefined;
 					});
@@ -112,7 +120,7 @@ async function run({
 		model: job.model,
 		task: job.task,
 		signal: new AbortController().signal,
-		aborted: "The worker was stopped.",
+		aborted: "the worker was stopped",
 	});
 }
 if (process.send) {
@@ -128,7 +136,12 @@ if (process.send) {
 				message.answer === "declined" ||
 				message.answer === "held")
 		) {
-			answers.get(message.id)?.(message.answer);
+			answers.get(message.id)?.(
+				message.answer,
+				"reason" in message && typeof message.reason === "string"
+					? message.reason
+					: undefined,
+			);
 			answers.delete(message.id);
 		} else if (message.type === "start" && !started) {
 			started = true;
@@ -136,7 +149,14 @@ if (process.send) {
 				(report) => {
 					process.send?.({ type: "report", report }, () => process.exit(0));
 				},
-				() => process.exit(1),
+				(error: unknown) =>
+					process.send?.(
+						{
+							type: "failure",
+							message: error instanceof Error ? error.message : String(error),
+						},
+						() => process.exit(1),
+					),
 			);
 		}
 	});

package/src/worker-failure.ts

@@ -1,14 +1,19 @@
-import { AgentError } from "pi-roundtable/kit";
+import { AgentError, scrubDiagnostic } from "pi-roundtable/kit";
 
-/** Structured diagnostics never carry provider responses, stderr or credentials. */
+/** Worker diagnostics reach the owner scrubbed of credentials and bounded; stderr and raw responses never do. */
 export class CodingWorkerFailure extends AgentError {
 	constructor(
 		readonly category: "stopped" | "exit" | "missing-report",
 		readonly exitCode?: number,
+		detail?: string,
+		diagnosticChars?: number,
 	) {
-		let message = "The coding worker was stopped.";
+		const reason = detail ? scrubDiagnostic(detail, diagnosticChars) : "";
+		let message = "the worker was stopped";
 		if (category === "exit")
-			message = `The coding worker exited (code ${exitCode}); check its model, login and package configuration.`;
+			message =
+				reason ||
+				`The coding worker exited (code ${exitCode}); check its model, login and package configuration.`;
 		if (category === "missing-report")
 			message = "The coding worker returned no report.";
 		super(message);