pi-roundtable-coding 0.7.3 → 0.7.4

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+## [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

@@ -166,7 +166,8 @@ 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. |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable-coding",
-	"version": "0.7.3",
+	"version": "0.7.4",
 	"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.4",
 		"typescript": "7.0.2"
 	}
 }

package/src/coding-desk.ts

@@ -121,18 +121,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,
@@ -180,7 +188,7 @@ export class CodingDesk {
 		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 +205,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,10 +230,11 @@ export class CodingDesk {
 				} catch {
 					/* A failed card never authorizes the call. */
 				}
-				if (answer !== "approved") {
+				// A call the owner declined is settled, not held for the report.
+				if (answer === "held") {
 					if (held.length < MAX_HELD_ENTRIES) {
 						const entry = bounded(
-							`${answer}: ${call.action}: ${call.tool} ${call.input}`,
+							`${call.action}: ${call.tool} ${call.input}`,
 							MAX_HELD_CHARS,
 						);
 						held.push(entry);
@@ -246,22 +255,22 @@ export class CodingDesk {
 				review,
 			);
 			if (controller.signal.aborted)
-				throw new AgentError("The worker was stopped.");
+				throw new AgentError("the worker was stopped");
 			outcome = { ok: true, report: bounded(report, MAX_REPORT_CHARS) };
 		} 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();

package/src/coding-plugin.ts

@@ -32,6 +32,7 @@ import {
 	type ChangeReport,
 	type CloneCommand,
 	RepoShelf,
+	type RepoSummary,
 	reportPost,
 } from "./repo-shelf.ts";
 
@@ -46,7 +47,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,6 +91,8 @@ 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;
@@ -170,14 +190,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 +227,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 +268,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 +300,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 +328,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

@@ -12,6 +12,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

@@ -23,6 +23,7 @@ interface WorkerMessage {
 	tool?: string;
 	input?: Record<string, unknown>;
 	report?: string;
+	message?: string;
 }
 function isMessage(value: unknown): value is WorkerMessage {
 	return (
@@ -46,9 +47,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 +78,11 @@ 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, 2_000);
 					} else if (
 						value.type === "call" &&
 						Number.isSafeInteger(value.id) &&
@@ -124,7 +131,7 @@ 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);
 			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 {
@@ -92,7 +92,7 @@ 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([
+	const { err, code } = await run([
 		"gh",
 		"repo",
 		"clone",
@@ -103,7 +103,7 @@ export const ghClone: CloneCommand = async (repo, dir) => {
 	]);
 	if (code !== 0)
 		throw new AgentError(
-			`Cloning ${repo} failed (exit ${code}); check the host's Git login.`,
+			`Cloning ${repo} failed: ${scrubDiagnostic(err) || `exit ${code}`}`,
 		);
 };
 
@@ -328,7 +328,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 +338,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 +480,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) || `exit ${code}`}`,
 			);
 		return out;
 	}

package/src/worker-entry.ts

@@ -112,7 +112,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) {
@@ -136,7 +136,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,18 @@
-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,
 	) {
-		let message = "The coding worker was stopped.";
+		const reason = detail ? scrubDiagnostic(detail) : "";
+		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);