pi-roundtable 0.22.0 → 0.22.1

package/CHANGELOG.md

@@ -5,6 +5,12 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.22.1] - 2026-10-21
+
+### Changed
+
+- A turn that reaches its time limit asks before it ends (`pi-roundtable`). When the built-in runtime's 10-minute budget or 30-minute cap fires on a turn that can show the owner a card, the turn keeps working and a card names the limit, the work time, what the turn is doing (the running tool and for how long, waiting on the model, or compacting) and the tools so far, with **Continue** (another full budget from the answer; at the cap the cap moves too) and **Cancel**. No answer within 5 minutes aborts the turn; a turn that finishes first closes the card and replies as usual. A turn that cannot show a card is aborted as before. An aborted turn now fails with `TurnTimeoutError` (an `AgentRunError`, with the reason as `TurnTimeout`: its `TurnLimit`, work time, running tools, tools so far and `TurnTimeoutEnd`), its log warning carries the same fields, and the posted failure says why instead of the generic notice. `ApprovalOptions` gains `wording` (`ApprovalWording`: the buttons' labels and the footers) for a card that is not an approval; the Discord cards honour it. `PiAgentRuntimeOptions` gains `turnTimeoutCardMs`, the card's grace period; the runtime plugin still passes none of the limits, so they stay fixed. See [the turn limits](docs/plugins.md#what-happens-when-the-bot-starts-and-stops).
+
 ## [0.22.0] - 2026-10-21
 
 ### Added

package/docs/plugins.md

@@ -3526,7 +3526,10 @@ On `SIGTERM` or `SIGINT` the bot takes no new work at once, finishes what runs,
 `shutdown()` returns exit code `0`, or `1` if a listener, service, or pool failed to stop.
 Every call shares the same shutdown.
 Give the service manager a stop timeout longer than the drain limit plus about a minute for the steps after it, such as systemd's `TimeoutStopSec=5min` with the default three-minute drain; a shorter one has the manager kill the process in the middle of the drain.
-The built-in runtime aborts a turn that works 10 minutes, not counting time spent waiting on the owner's cards. Each message steered into the running turn gives it the full 10 minutes again from that moment, up to a cap of 30 minutes of work for the whole turn; once the cap is reached the turn takes no more steering, so a message waits for the next turn, and the turn is aborted as on its timeout. Both limits are fixed: the runtime plugin passes no option for them, so a host cannot change them, and a limit that waiting on an owner's card pushed back can fire up to a second late. The log says `steer renewed the turn's time budget` with `deadlineMs`, the work time left, and the timeout warning names the limit that fired (`limit: "turn"` or `"turnMax"`). Task workers (`task.timeoutMs`), coding workers (`workTimeout`) and sandbox guests (their own `turnTimeoutMs`) keep their own limits, which steering does not renew.
+The built-in runtime limits a turn to 10 minutes of work, not counting time spent waiting on the owner's cards. Each message steered into the running turn gives it the full 10 minutes again from that moment, up to a cap of 30 minutes of work for the whole turn; once the cap is reached the turn takes no more steering, so a message waits for the next turn.
+When a limit fires on a turn that can show a card (an owner's turn or a report turn on a surface with cards, the same turns that can ask with `ask_user` or an approval card), the turn is not aborted: it keeps working and a card asks the owner whether to go on. The card names the limit, how long the turn has worked, what it is doing now (the tool running and for how long, or waiting on the model, or compacting the conversation) and the tools it called so far, by name and count, never their inputs. **Continue** gives the turn another full 10 minutes from the answer; at the cap it moves the cap too, to 10 minutes from the answer, so the owner can keep going in steps. **Cancel** aborts the turn. With no answer within 5 minutes of wall time the turn is aborted. The time the card is open counts as work, unlike an `ask_user` or approval card, because the turn keeps working; while it is open the turn takes no steering. If the turn finishes first, the card closes saying so and the reply is posted as usual; a press after that gets the usual "no longer valid" reply. The card's buttons come from `ApprovalOptions.wording` on `Prompts.confirm`, with `supersede` closing it, so a surface that shows approvals shows it; one that ignores `wording` shows its own approve and decline labels.
+A turn that cannot show a card (a schedule's turn, a member's turn, a turn without a surface) is aborted at once, as before. Either way an aborted turn fails with a `TurnTimeoutError` (an `AgentRunError`) whose `timeout` (`TurnTimeout`) holds the limit, the work time, the running tools, whether it was compacting, the tools so far, and how it ended (`end`: `"timeout"`, `"cancelled"` by the owner, or `"unanswered"`); its message says the same in English, and the failure the conversation posts says it in the host's language instead of the generic failure notice.
+The limits are fixed: the runtime plugin passes no option for them, nor for the card's grace period (`turnTimeoutMs`, `turnMaxMs` and `turnTimeoutCardMs` of `PiAgentRuntimeOptions`, for a host that builds the runtime itself), and a limit that waiting on an owner's card pushed back can fire up to a second late. The log says `steer renewed the turn's time budget` with `deadlineMs`, the work time left; `turn reached its time limit; asking the owner` when the card is posted; `owner continued the turn past its time limit` on Continue; and the warning `turn timed out; aborting` names the limit that fired (`limit: "turn"` or `"turnMax"`) with `workedMs`, `running`, `compacting`, `tools` and `end`. Task workers (`task.timeoutMs`), coding workers (`workTimeout`) and sandbox guests (their own `turnTimeoutMs`) keep their own limits, which steering does not renew and which post no card.
 A turn whose model ignores its abort (a subprocess that does not exit) is given up on too: a turn that outlives its timeout, or is stopped, gets `turnAbortGraceMs` (15 seconds by default) to end, and then its session is disposed of and the turn is reported failed, so it cannot hold the queue.
 `listen()`, called by the command line and a host's own entry point, exits the process with that code.
 
@@ -3737,6 +3740,7 @@ Import from the entries listed below; source area files are internal.
 | `ApprovalDetails` | `pi-roundtable` | type |
 | `ApprovalFile` | `pi-roundtable` | type |
 | `ApprovalOptions` | `pi-roundtable` | type |
+| `ApprovalWording` | `pi-roundtable` | type |
 | `ApprovedBy` | `pi-roundtable` | type |
 | `AskOption` | `pi-roundtable` | type |
 | `AskSupport` | `pi-roundtable` | type |
@@ -3963,6 +3967,10 @@ Import from the entries listed below; source area files are internal.
 | `TurnRequest` | `pi-roundtable` | type |
 | `TurnResult` | `pi-roundtable` | type |
 | `TurnSelection` | `pi-roundtable` | type |
+| `TurnLimit` | `pi-roundtable` | type |
+| `TurnTimeout` | `pi-roundtable` | type |
+| `TurnTimeoutEnd` | `pi-roundtable` | type |
+| `TurnTimeoutError` | `pi-roundtable` | value |
 | `WebSocketAccept` | `pi-roundtable` | type |
 | `WebSocketRoute` | `pi-roundtable` | type |
 | `WebSocketSendResult` | `pi-roundtable` | type |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable",
-	"version": "0.22.0",
+	"version": "0.22.1",
 	"description": "A plugin-driven Pi agent server for one owner, reached through Discord or the web",
 	"type": "module",
 	"license": "MIT",

package/src/core/agents/team-turns.ts

@@ -8,7 +8,7 @@ import type {
 import { AgentError } from "../domain/errors.ts";
 import type { InterimPosts } from "../domain/interim.ts";
 import type { AgentTurnScope } from "../domain/ports.ts";
-import { messages } from "../i18n/index.ts";
+import { failureNotice } from "../presentation/failure-notice.ts";
 import { splitReply } from "../presentation/reply-splitter.ts";
 import { thinkingLine } from "../presentation/thinking-line.ts";
 import { withReplyFiles } from "../reply-files.ts";
@@ -35,11 +35,6 @@ import {
 
 export { MAX_CHAIN_MESSAGES, type TeamTurnsOptions };
 
-/** What a failed turn posts: the stopped notice for a stop, the failure notice otherwise. */
-function noticeOf(result: { stopped?: true }): string {
-	return result.stopped ? messages().stoppedNotice : messages().failureNotice;
-}
-
 /**
  * The agent team's turns: owner messages, background turns, group rounds, and messages between
  * agents, each posted under the answering agent's name.
@@ -246,7 +241,7 @@ export class TeamTurns {
 					: undefined;
 			await this.#post(postTo, this.#current(agent), {
 				...(thinking ? { thinking } : {}),
-				chunks: result.ok ? splitReply(result.text) : [noticeOf(result)],
+				chunks: result.ok ? splitReply(result.text) : [failureNotice(result)],
 				...(result.ok && result.files?.length ? { files: result.files } : {}),
 			});
 		} catch (error) {

package/src/core/discord/owner-card-rows.ts

@@ -123,23 +123,27 @@ export function answeredLine(answer: OwnerAnswer): string {
 	return messages().cardAnswered(parts);
 }
 
-/** An approval's controls: run, cancel, and, when the card offers a copy, a copy button that stays usable once it ended. */
+/**
+ * An approval's controls: run, cancel, or the labels its wording gives, and, when the card offers
+ * a copy, a copy button that stays usable once it ended.
+ */
 export function approvalRows(
 	id: string,
 	disabled: boolean,
 	copy: { label: string } | undefined,
+	labels?: { approve: string; decline: string },
 ): Rows {
 	return [
 		new ActionRowBuilder<ButtonBuilder>().addComponents(
 			new ButtonBuilder()
 				.setCustomId(`${CARD_PREFIX}${id}:yes`)
-				.setLabel(messages().cardRunLabel)
+				.setLabel(labels?.approve ?? messages().cardRunLabel)
 				.setEmoji("✅")
 				.setStyle(ButtonStyle.Success)
 				.setDisabled(disabled),
 			new ButtonBuilder()
 				.setCustomId(`${CARD_PREFIX}${id}:no`)
-				.setLabel(messages().cardCancelLabel)
+				.setLabel(labels?.decline ?? messages().cardCancelLabel)
 				.setEmoji("❌")
 				.setStyle(ButtonStyle.Secondary)
 				.setDisabled(disabled),

package/src/core/discord/owner-card-types.ts

@@ -83,6 +83,8 @@ export interface OpenCard {
 	mention?: boolean;
 	/** Who may answer, and what to tell someone else who presses it. */
 	audience: Audience;
+	/** An approval card's footers once approved or declined, where its wording gives them. */
+	outcomes?: { approved: string; declined: string };
 }
 
 /** What `#post` needs to post one card; `T` is what the card resolves with. */
@@ -101,6 +103,8 @@ export interface CardSpec<T> {
 	build?(id: string, footer: string, disabled: boolean): CardPayload;
 	rows?(id: string, disabled: boolean): Rows;
 	footer: string;
+	/** An approval card's footers once approved or declined, where its wording gives them. */
+	outcomes?: { approved: string; declined: string };
 	wait?: {
 		pending: T;
 		late(

package/src/core/discord/owner-cards.ts

@@ -175,8 +175,10 @@ export class OwnerCards implements InteractionModule {
 						sections: [message],
 						...(options?.supersede ? { supersede: options.supersede } : {}),
 						...(copy ? { copy: copy.text } : {}),
-						rows: (id, disabled) => approvalRows(id, disabled, copy),
-						footer: messages().cardApprovalFooter,
+						rows: (id, disabled) =>
+							approvalRows(id, disabled, copy, options?.wording),
+						footer: options?.wording?.footer ?? messages().cardApprovalFooter,
+						...(options?.wording ? { outcomes: options.wording } : {}),
 					},
 				);
 			},
@@ -296,6 +298,7 @@ export class OwnerCards implements InteractionModule {
 				...(card.question ? { question: card.question } : {}),
 				...(card.form ? { form: card.form } : {}),
 				...(card.previews ? { previews: card.previews } : {}),
+				...(card.outcomes ? { outcomes: card.outcomes } : {}),
 			};
 			this.#open.set(id, open);
 			this.#options
@@ -417,7 +420,11 @@ export class OwnerCards implements InteractionModule {
 				return true;
 			}
 			await interaction.update(
-				card.view(approved ? messages().cardApproved : messages().cardDeclined),
+				card.view(
+					approved
+						? (card.outcomes?.approved ?? messages().cardApproved)
+						: (card.outcomes?.declined ?? messages().cardDeclined),
+				),
 			);
 			return true;
 		}

package/src/core/domain/turn-timeout.ts

@@ -0,0 +1,38 @@
+import { AgentRunError } from "./errors.ts";
+
+/** Which limit a turn reached: its budget since the start or the last steer, or its cap. */
+export type TurnLimit = "turn" | "turnMax";
+
+/**
+ * How a timed-out turn ended: at its limit with no card to ask on (`timeout`), cancelled on the
+ * timeout card (`cancelled`), or with the card unanswered in its grace period (`unanswered`).
+ */
+export type TurnTimeoutEnd = "timeout" | "cancelled" | "unanswered";
+
+/** Why a turn hit a time limit, as data: which limit, how long it worked, and what it was doing. */
+export interface TurnTimeout {
+	limit: TurnLimit;
+	/** The limit's length: the budget, or the cap as the owner's Continues raised it. */
+	limitMs: number;
+	/** The turn's work so far, not counting time spent waiting on the owner's other cards. */
+	workedMs: number;
+	/** The tools running, the longest-running first, each with how long it has run. */
+	running: { tool: string; ms: number }[];
+	compacting: boolean;
+	/** Every tool called so far, by name, with how often. */
+	tools: [string, number][];
+	/** How long the timeout card waits for an answer. */
+	graceMs: number;
+	end: TurnTimeoutEnd;
+}
+
+/** A turn aborted at a time limit; `timeout` says why, and the message says it in English. */
+export class TurnTimeoutError extends AgentRunError {
+	override name = "TurnTimeoutError";
+	constructor(
+		readonly timeout: TurnTimeout,
+		message: string,
+	) {
+		super(message);
+	}
+}

package/src/core/i18n/en.ts

@@ -7,6 +7,7 @@ import { discordEn } from "./discord.ts";
 import { ownerEn } from "./owner.ts";
 import { schedulesEn } from "./schedules.ts";
 import { timeZonesEn } from "./time-zones.ts";
+import { turnTimeoutEn } from "./turn-timeout.ts";
 import type { CatalogContext } from "./types.ts";
 
 export type Messages = ReturnType<typeof createEn>;
@@ -23,5 +24,6 @@ export function createEn(ctx: CatalogContext) {
 		...dashboardEn(ctx),
 		...channelsEn(ctx),
 		...discordEn(ctx),
+		...turnTimeoutEn(),
 	};
 }

package/src/core/i18n/turn-timeout.ts

@@ -0,0 +1,131 @@
+import type { TurnTimeout } from "../domain/turn-timeout.ts";
+
+/** A duration in whole seconds, as "3 min 12 s", "45 s", or "1 h 5 min". */
+function durationEn(ms: number): string {
+	const s = Math.max(0, Math.round(ms / 1000));
+	const h = Math.floor(s / 3600);
+	const m = Math.floor((s % 3600) / 60);
+	const sec = s % 60;
+	if (h > 0) return m > 0 ? `${h} h ${m} min` : `${h} h`;
+	if (m > 0) return sec > 0 ? `${m} min ${sec} s` : `${m} min`;
+	return `${sec} s`;
+}
+
+function durationZh(ms: number): string {
+	const s = Math.max(0, Math.round(ms / 1000));
+	const h = Math.floor(s / 3600);
+	const m = Math.floor((s % 3600) / 60);
+	const sec = s % 60;
+	if (h > 0) return m > 0 ? `${h} 小時 ${m} 分` : `${h} 小時`;
+	if (m > 0) return sec > 0 ? `${m} 分 ${sec} 秒` : `${m} 分`;
+	return `${sec} 秒`;
+}
+
+/** The tools called so far, as the interim tool line shows them. */
+function toolList(tools: TurnTimeout["tools"], separator: string): string {
+	return tools
+		.map(([name, count]) => (count > 1 ? `${name} ×${count}` : name))
+		.join(separator);
+}
+
+/** The timeout card and the notice a turn posts when it ends at a time limit. */
+export function turnTimeoutEn() {
+	const doing = (t: TurnTimeout) =>
+		t.running.length > 0
+			? t.running
+					.map(({ tool, ms }) => `${tool}, running for ${durationEn(ms)}`)
+					.join("; ")
+			: t.compacting
+				? "compacting the conversation"
+				: "waiting on the model";
+	const limit = (t: TurnTimeout) =>
+		t.limit === "turn"
+			? `its time limit of ${durationEn(t.limitMs)} (since it started or since the last message steered into it)`
+			: `its cap of ${durationEn(t.limitMs)} of work in all`;
+	const tools = (t: TurnTimeout) =>
+		t.tools.length > 0 ? `Tools so far: ${toolList(t.tools, " · ")}.` : "";
+	return {
+		turnTimeoutTitle: "⏱️ This turn is taking long",
+		turnTimeoutQuestion: (t: TurnTimeout, budgetMs: number) =>
+			[
+				`It reached ${limit(t)} and has worked ${durationEn(t.workedMs)}.`,
+				`Now: ${doing(t)}.`,
+				tools(t),
+				`It keeps working while this card is open. Continue gives it another ${durationEn(budgetMs)}; Cancel stops it. With no answer in ${durationEn(t.graceMs)} it stops.`,
+			]
+				.filter(Boolean)
+				.join("\n"),
+		turnTimeoutContinue: "Continue",
+		turnTimeoutCancel: "Cancel",
+		turnTimeoutFooter:
+			"The turn is still working; answer whenever you are ready.",
+		turnTimeoutContinued: "▶️ Continued.",
+		turnTimeoutCancelled: "❌ Cancelled; the turn stops.",
+		turnTimeoutFinished: "✅ The turn finished; nothing to answer.",
+		turnTimeoutUnanswered: (t: TurnTimeout) =>
+			`⏱️ No answer in ${durationEn(t.graceMs)}; the turn was stopped.`,
+		turnTimedOutNotice: (t: TurnTimeout) => {
+			const what =
+				t.running.length > 0
+					? `while ${t.running.map(({ tool, ms }) => `${tool} was running (${durationEn(ms)})`).join(" and ")}`
+					: `while ${doing(t)}`;
+			const head =
+				t.end === "cancelled"
+					? `⏱️ Cancelled by the owner after ${durationEn(t.workedMs)} ${what}.`
+					: t.end === "unanswered"
+						? `⏱️ No answer to the timeout card in ${durationEn(t.graceMs)}, so the turn was stopped after ${durationEn(t.workedMs)} ${what}.`
+						: `⏱️ The turn reached ${limit(t)} and was stopped after ${durationEn(t.workedMs)} ${what}.`;
+			return [head, tools(t)].filter(Boolean).join(" ");
+		},
+	};
+}
+
+export function turnTimeoutZhTW(): ReturnType<typeof turnTimeoutEn> {
+	const doing = (t: TurnTimeout) =>
+		t.running.length > 0
+			? t.running
+					.map(({ tool, ms }) => `${tool}，已執行 ${durationZh(ms)}`)
+					.join("；")
+			: t.compacting
+				? "正在壓縮對話"
+				: "正在等模型回應";
+	const limit = (t: TurnTimeout) =>
+		t.limit === "turn"
+			? `時間上限 ${durationZh(t.limitMs)}（從開始或最後一則插入的訊息算起）`
+			: `總工作時間上限 ${durationZh(t.limitMs)}`;
+	const tools = (t: TurnTimeout) =>
+		t.tools.length > 0 ? `目前用過的工具：${toolList(t.tools, " · ")}。` : "";
+	return {
+		turnTimeoutTitle: "⏱️ 這一輪做得比較久",
+		turnTimeoutQuestion: (t: TurnTimeout, budgetMs: number) =>
+			[
+				`已達到${limit(t)}，已工作 ${durationZh(t.workedMs)}。`,
+				`現在：${doing(t)}。`,
+				tools(t),
+				`這張卡片開著時它會繼續工作。按「繼續」再給它 ${durationZh(budgetMs)}；按「取消」停止。${durationZh(t.graceMs)}內沒有回答就會停止。`,
+			]
+				.filter(Boolean)
+				.join("\n"),
+		turnTimeoutContinue: "繼續",
+		turnTimeoutCancel: "取消",
+		turnTimeoutFooter: "這一輪仍在工作；準備好再回答即可。",
+		turnTimeoutContinued: "▶️ 已繼續。",
+		turnTimeoutCancelled: "❌ 已取消，這一輪會停止。",
+		turnTimeoutFinished: "✅ 這一輪已完成，不需要回答。",
+		turnTimeoutUnanswered: (t: TurnTimeout) =>
+			`⏱️ ${durationZh(t.graceMs)}內沒有回答，這一輪已停止。`,
+		turnTimedOutNotice: (t: TurnTimeout) => {
+			const what =
+				t.running.length > 0
+					? `當時 ${t.running.map(({ tool, ms }) => `${tool} 正在執行（${durationZh(ms)}）`).join("、")}`
+					: `當時${doing(t)}`;
+			const head =
+				t.end === "cancelled"
+					? `⏱️ 擁有者在工作 ${durationZh(t.workedMs)} 後取消了這一輪，${what}。`
+					: t.end === "unanswered"
+						? `⏱️ 逾時卡片在 ${durationZh(t.graceMs)}內沒有回答，這一輪在工作 ${durationZh(t.workedMs)} 後停止，${what}。`
+						: `⏱️ 這一輪達到${limit(t)}，在工作 ${durationZh(t.workedMs)} 後停止，${what}。`;
+			return [head, tools(t)].filter(Boolean).join(" ");
+		},
+	};
+}

package/src/core/i18n/zh-tw.ts

@@ -8,6 +8,7 @@ import type { Messages } from "./en.ts";
 import { ownerZhTW } from "./owner.ts";
 import { schedulesZhTW } from "./schedules.ts";
 import { timeZonesZhTW } from "./time-zones.ts";
+import { turnTimeoutZhTW } from "./turn-timeout.ts";
 import type { CatalogContext } from "./types.ts";
 
 /** The Traditional Chinese catalog. */
@@ -22,5 +23,6 @@ export function createZhTW(ctx: CatalogContext): Messages {
 		...dashboardZhTW(ctx),
 		...channelsZhTW(ctx),
 		...discordZhTW(ctx),
+		...turnTimeoutZhTW(),
 	};
 }

package/src/core/interactions/prompts.ts

@@ -128,6 +128,23 @@ export interface ApprovalOptions {
 	 * withdrawn call whatever the card answers.
 	 */
 	supersede?: AbortSignal;
+	/**
+	 * The card's own words, for a card that asks something other than whether to run an action,
+	 * such as a turn's timeout card; a surface that cannot show them keeps its own.
+	 */
+	wording?: ApprovalWording;
+}
+
+/** A card's words in place of an approval's; see `ApprovalOptions.wording`. */
+export interface ApprovalWording {
+	/** The labels of the controls that answer approved and declined. */
+	approve: string;
+	decline: string;
+	/** The footer while the card is open. */
+	footer: string;
+	/** The footer once it was answered approved, or declined. */
+	approved: string;
+	declined: string;
 }
 
 /** The longest footer a withdrawn card shows, in characters. */

package/src/core/presentation/failure-notice.ts

@@ -0,0 +1,13 @@
+import { TurnTimeoutError } from "../domain/turn-timeout.ts";
+import { messages } from "../i18n/index.ts";
+
+/** What a failed turn posts: the stopped notice for a stop, the reason for a time limit, else the failure notice. */
+export function failureNotice(result: {
+	error: Error;
+	stopped?: true;
+}): string {
+	if (result.stopped) return messages().stoppedNotice;
+	if (result.error instanceof TurnTimeoutError)
+		return messages().turnTimedOutNotice(result.error.timeout);
+	return messages().failureNotice;
+}

package/src/core/routing/conversation-turns.ts

@@ -10,10 +10,10 @@ import type { TurnResult } from "../domain/conversation.ts";
 import type { TurnConversation } from "../domain/ports.ts";
 import type { TurnProgress } from "../domain/progress.ts";
 import { HostStoppingError, PluginError } from "../errors.ts";
-import { messages } from "../i18n/index.ts";
 import { SYSTEM_PRINCIPAL } from "../identity/principal-store.ts";
 import type { Logger } from "../log.ts";
 import type { EventSink } from "../plugin.ts";
+import { failureNotice } from "../presentation/failure-notice.ts";
 import { splitReply } from "../presentation/reply-splitter.ts";
 import { thinkingLine } from "../presentation/thinking-line.ts";
 import { withReplyFiles } from "../reply-files.ts";
@@ -239,12 +239,7 @@ export function conversationTurns(
 
 /** The default post: the answer with its thinking line, or the failure or stopped notice. */
 function replyOf(result: TurnResult) {
-	if (!result.ok)
-		return {
-			chunks: [
-				result.stopped ? messages().stoppedNotice : messages().failureNotice,
-			],
-		};
+	if (!result.ok) return { chunks: [failureNotice(result)] };
 	const thinking = result.thinking ? thinkingLine(result.thinking) : undefined;
 	return {
 		...(thinking ? { thinking } : {}),

package/src/core/runtime/pi-agent-runtime.ts

@@ -48,7 +48,8 @@ import { promptImages, SteerableRun } from "./steerable-run.ts";
 import { thinkingLevel } from "./thinking-level.ts";
 import { runningCalls } from "./tool-call-scope.ts";
 import { transcriptOf, turnAnswer, unspokenTurn } from "./turn-answer.ts";
-import { runtimeTurnBudget, type TurnBudget } from "./turn-budget.ts";
+import type { TurnBudget } from "./turn-budget.ts";
+import { promptFailed, turnLimits } from "./turn-limits.ts";
 import { progressReporter } from "./turn-progress.ts";
 import { wrapUpTurn } from "./turn-wrapup.ts";
 import { workerReport } from "./worker-task.ts";
@@ -240,6 +241,10 @@ export class PiAgentRuntime implements AgentRuntime {
 		const interim = interimPoster(request, this.#options);
 		// The caller's live view: the text as it streams and each tool, never the thinking.
 		const slot = this.#sessions.slot(key);
+		// Its time limit, not counting time waiting on the owner's cards, follows what it does to say why it fired.
+		const limits = turnLimits(this.#options, slot, request.channel, () =>
+			guard.abort(),
+		);
 		const progress = request.progress
 			? progressReporter(request.progress, {
 					refusalOf: (id) => slot.refusalOf(id),
@@ -247,6 +252,7 @@ export class PiAgentRuntime implements AgentRuntime {
 			: undefined;
 		const unsubscribe = session.subscribe((event) => {
 			progress?.observe(event);
+			limits.observe(event);
 			if (event.type === "tool_execution_start") {
 				toolCalls.push(event.toolName);
 				interim?.toolStart(event.toolName);
@@ -275,10 +281,7 @@ export class PiAgentRuntime implements AgentRuntime {
 				this.#sessions.drop(key, channelSession);
 			},
 		});
-		// Time spent waiting on the owner's cards does not count towards the timeout or the cap.
-		const budget = runtimeTurnBudget(this.#options, slot, request.channel, () =>
-			guard.abort(),
-		);
+		const { budget } = limits;
 		this.#budgets.set(key, budget);
 		const running = new SteerableRun(
 			session,
@@ -307,10 +310,7 @@ export class PiAgentRuntime implements AgentRuntime {
 		} catch (error) {
 			if (running.stopped)
 				return { ok: false, error: new AgentRunError(STOPPED), stopped: true };
-			return {
-				ok: false,
-				error: new AgentRunError(`prompt failed: ${String(error)}`),
-			};
+			return limits.failure() ?? promptFailed(error);
 		} finally {
 			this.#running.delete(key);
 			this.#budgets.delete(key);
@@ -335,7 +335,7 @@ export class PiAgentRuntime implements AgentRuntime {
 
 		if (running.stopped)
 			return { ok: false, error: new AgentRunError(STOPPED), stopped: true };
-		return turnAnswer(turnMessages, running.steered);
+		return limits.failure() ?? turnAnswer(turnMessages, running.steered);
 	}
 
 	async steer(

package/src/core/runtime/prompt-slot.ts

@@ -99,6 +99,14 @@ export class PromptSlot {
 		};
 	}
 
+	/**
+	 * The turn's prompts as bound, an open card not counted as waiting; for a card the turn keeps
+	 * working beside, such as the one its time limit posts.
+	 */
+	get cards(): Prompts | undefined {
+		return this.#prompts;
+	}
+
 	/** Time this turn has spent with at least one card open. */
 	waitedMs(now = Date.now()): number {
 		return this.#waited + (this.#open > 0 ? now - this.#openSince : 0);

package/src/core/runtime/runtime-types.ts

@@ -89,17 +89,25 @@ export interface PiAgentRuntimeOptions {
 	/** The lowest tier that may use each tool; the default names the core's tools and leaves the rest to the owner. */
 	toolTiers?: ToolTiers;
 	/**
-	 * A run that works longer, not counting time spent waiting on the owner's cards, is aborted and
-	 * reported as failed; default 10 minutes. Each message steered into the turn gives it this
+	 * A run that works longer, not counting time spent waiting on the owner's cards, asks the owner
+	 * on a card whether to go on (see `turnTimeoutCardMs`), or, when it cannot show one, is aborted
+	 * and reported as failed with the reason; default 10 minutes. Each message steered into the turn gives it this
 	 * budget again from that moment, up to `turnMaxMs`.
 	 */
 	turnTimeoutMs?: number;
 	/**
 	 * The most one turn may work in all, however often it is steered, not counting time spent
 	 * waiting on the owner's cards; default three times `turnTimeoutMs`. Once it is reached the turn
-	 * takes no more steering (the message waits for the next turn) and is aborted as on its timeout.
+	 * takes no more steering (the message waits for the next turn) and asks or is aborted as on its
+	 * timeout; the owner's Continue moves the cap to a full `turnTimeoutMs` from then.
 	 */
 	turnMaxMs?: number;
+	/**
+	 * How long the card a turn posts when it reaches `turnTimeoutMs` or `turnMaxMs` waits for the
+	 * owner's Continue or Cancel, in wall time, while the turn keeps working; default 5 minutes. With
+	 * no answer by then the turn is aborted. A turn that cannot show a card is aborted at once.
+	 */
+	turnTimeoutCardMs?: number;
 	/**
 	 * How long a turn that was aborted, by its timeout or a stop, gets to end before its session is
 	 * disposed of and the turn is reported failed; default 15 seconds. A model that ignores the

package/src/core/runtime/turn-activity.ts

@@ -0,0 +1,42 @@
+import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+
+/** What a turn was doing at one moment: tools running and for how long, or compacting, or neither (the model). */
+export interface TurnActivity {
+	/** The tools running, the longest-running first, each with how long it has run. */
+	running: { tool: string; ms: number }[];
+	compacting: boolean;
+	/** Every tool called so far, by name, with how often, in the order first called. */
+	tools: [string, number][];
+}
+
+/** Follows a turn's events to say, when asked, what it is doing; never its inputs. */
+export interface ActivityTracker {
+	observe(event: AgentSessionEvent): void;
+	now(at: number): TurnActivity;
+}
+
+export function activityTracker(
+	clock: () => number = Date.now,
+): ActivityTracker {
+	const running = new Map<string, { tool: string; since: number }>();
+	const tools = new Map<string, number>();
+	let compacting = false;
+	return {
+		observe(event) {
+			if (event.type === "tool_execution_start") {
+				running.set(event.toolCallId, { tool: event.toolName, since: clock() });
+				tools.set(event.toolName, (tools.get(event.toolName) ?? 0) + 1);
+			} else if (event.type === "tool_execution_end") {
+				running.delete(event.toolCallId);
+			} else if (event.type === "compaction_start") compacting = true;
+			else if (event.type === "compaction_end") compacting = false;
+		},
+		now: (at) => ({
+			running: [...running.values()]
+				.sort((a, b) => a.since - b.since)
+				.map(({ tool, since }) => ({ tool, ms: at - since })),
+			compacting,
+			tools: [...tools],
+		}),
+	};
+}

package/src/core/runtime/turn-budget.ts

@@ -1,9 +1,16 @@
+import type {
+	TurnLimit,
+	TurnTimeout,
+	TurnTimeoutEnd,
+} from "../domain/turn-timeout.ts";
+import { messages } from "../i18n/index.ts";
+import type { Approval } from "../interactions/prompts.ts";
 import type { ChannelKey } from "../sessions.ts";
 import type { PromptSlot } from "./prompt-slot.ts";
 import type { PiAgentRuntimeOptions } from "./runtime-types.ts";
+import type { ActivityTracker } from "./turn-activity.ts";
 
-/** Which limit ended a turn: its budget since the start or the last steer, or its cap. */
-export type TurnLimit = "turn" | "turnMax";
+export type { TurnLimit };
 
 /** A turn's time limit, which a steered message renews up to a cap on the whole turn. */
 export interface TurnBudget {
@@ -12,8 +19,15 @@ export interface TurnBudget {
 	 * or undefined when the cap is reached and the turn takes no more steering.
 	 */
 	renew(): number | undefined;
-	/** Whether the turn has worked up to its cap. */
+	/**
+	 * After a limit fired, gives the turn its full budget again from now, as the owner's Continue
+	 * does; with `raiseCap` the cap moves too, to a full budget from now.
+	 */
+	extend(raiseCap: boolean): void;
+	/** Whether the turn has worked up to its cap, or a limit fired and was not extended. */
 	capped(): boolean;
+	/** The turn's work so far, not counting time the slot spent waiting on cards. */
+	workedMs(): number;
 	cancel(): void;
 }
 
@@ -43,13 +57,13 @@ const REARM_FLOOR_MS = 1_000;
 /**
  * Calls `expire` once the turn has worked `ms` since it started or since its last renewal, or
  * `maxMs` in all, whichever comes first; time the slot spent waiting on the owner's cards counts
- * towards neither. `expire` is told which limit fired.
+ * towards neither. `expire` is told which limit fired and its length.
  */
 export function turnBudget(
 	ms: number,
 	maxMs: number,
 	slot: Pick<PromptSlot, "waitedMs">,
-	expire: (limit: TurnLimit) => void,
+	expire: (limit: TurnLimit, limitMs: number) => void,
 	clock: BudgetClock = REAL_CLOCK,
 ): TurnBudget {
 	const started = clock.now();
@@ -57,7 +71,8 @@ export function turnBudget(
 		const now = clock.now();
 		return now - started - slot.waitedMs(now);
 	};
-	let deadline = Math.min(ms, maxMs);
+	let cap = maxMs;
+	let deadline = Math.min(ms, cap);
 	let cancelTimer: (() => void) | undefined;
 	let expired = false;
 	const arm = (delay: number) => {
@@ -65,47 +80,172 @@ export function turnBudget(
 			const left = deadline - worked();
 			if (left > 0) return arm(Math.max(left, REARM_FLOOR_MS));
 			expired = true;
-			expire(deadline >= maxMs ? "turnMax" : "turn");
+			if (deadline >= cap) expire("turnMax", cap);
+			else expire("turn", ms);
 		}, delay);
 	};
 	arm(deadline);
 	return {
 		renew() {
 			const now = worked();
-			if (expired || now >= maxMs) return undefined;
-			deadline = Math.min(now + ms, maxMs);
+			if (expired || now >= cap) return undefined;
+			deadline = Math.min(now + ms, cap);
 			cancelTimer?.();
 			arm(deadline - now);
 			return deadline - now;
 		},
-		capped: () => expired || worked() >= maxMs,
+		extend(raiseCap) {
+			const now = worked();
+			if (raiseCap) cap = Math.max(cap, now + ms);
+			deadline = Math.min(now + ms, cap);
+			expired = false;
+			cancelTimer?.();
+			arm(Math.max(deadline - now, REARM_FLOOR_MS));
+		},
+		capped: () => expired || worked() >= cap,
+		workedMs: worked,
 		cancel: () => cancelTimer?.(),
 	};
 }
 
+/** What the runtime's turn budget needs besides its options: what the turn is doing, and its clock. */
+export interface TurnBudgetSeams {
+	activity: Pick<ActivityTracker, "now">;
+	clock?: BudgetClock;
+}
+
 /**
  * The time limit of one turn of the built-in runtime, from its options: `turnTimeoutMs` (default
- * 10 minutes) renewed by each steer up to `turnMaxMs` (default three times that). It logs each
- * renewal and, when a limit fires, which one before it calls `abort`.
+ * 10 minutes) renewed by each steer up to `turnMaxMs` (default three times that). When a limit
+ * fires on a turn that can show the owner a card, the turn keeps working and a card asks whether
+ * to go on: Continue extends the limit that fired by a full budget from then, Cancel aborts, and
+ * no answer within `turnTimeoutCardMs` (default 5 minutes, wall time) aborts. The card closes
+ * when the turn ends first. Without a card the turn is aborted at once. `abort` is told why.
  */
 export function runtimeTurnBudget(
 	options: Pick<
 		PiAgentRuntimeOptions,
-		"turnTimeoutMs" | "turnMaxMs" | "logger"
+		"turnTimeoutMs" | "turnMaxMs" | "turnTimeoutCardMs" | "logger"
 	>,
-	slot: Pick<PromptSlot, "waitedMs">,
+	slot: Pick<PromptSlot, "waitedMs" | "cards">,
 	channel: ChannelKey,
-	abort: () => void,
+	abort: (timeout: TurnTimeout) => void,
+	seams: TurnBudgetSeams,
 ): TurnBudget {
 	const { logger, turnTimeoutMs = 10 * 60_000 } = options;
 	const turnMaxMs = options.turnMaxMs ?? 3 * turnTimeoutMs;
-	const budget = turnBudget(turnTimeoutMs, turnMaxMs, slot, (limit) => {
+	const graceMs = options.turnTimeoutCardMs ?? 5 * 60_000;
+	const clock = seams.clock ?? REAL_CLOCK;
+	/** Closes the open timeout card, if any, with the footer given. */
+	let closeCard: ((footer: string) => void) | undefined;
+	const reason = (
+		limit: TurnLimit,
+		limitMs: number,
+		end: TurnTimeoutEnd,
+	): TurnTimeout => ({
+		limit,
+		limitMs,
+		workedMs: budget.workedMs(),
+		...seams.activity.now(clock.now()),
+		graceMs,
+		end,
+	});
+	const stop = (timeout: TurnTimeout) => {
 		logger.warn(
-			{ channel, limit, turnTimeoutMs, turnMaxMs },
+			{
+				channel,
+				limit: timeout.limit,
+				turnTimeoutMs,
+				turnMaxMs,
+				workedMs: timeout.workedMs,
+				running: timeout.running,
+				compacting: timeout.compacting,
+				tools: timeout.tools,
+				end: timeout.end,
+			},
 			"turn timed out; aborting",
 		);
-		abort();
-	});
+		abort(timeout);
+	};
+	const budget = turnBudget(
+		turnTimeoutMs,
+		turnMaxMs,
+		slot,
+		(limit, limitMs) => {
+			const prompts = slot.cards;
+			if (!prompts) return stop(reason(limit, limitMs, "timeout"));
+			const m = messages();
+			const asked = reason(limit, limitMs, "timeout");
+			logger.info(
+				{
+					channel,
+					limit,
+					workedMs: asked.workedMs,
+					running: asked.running,
+				},
+				"turn reached its time limit; asking the owner",
+			);
+			const controller = new AbortController();
+			let open = true;
+			const settle = () => {
+				if (!open) return false;
+				open = false;
+				closeCard = undefined;
+				cancelGrace();
+				return true;
+			};
+			const cancelGrace = clock.schedule(() => {
+				if (!settle()) return;
+				const timeout = reason(limit, limitMs, "unanswered");
+				controller.abort(m.turnTimeoutUnanswered(timeout));
+				stop(timeout);
+			}, graceMs);
+			closeCard = (footer) => {
+				if (settle()) controller.abort(footer);
+			};
+			const answered = (approval: Approval) => {
+				if (!settle()) return;
+				if (approval === "approved") {
+					budget.extend(limit === "turnMax");
+					logger.info(
+						{ channel, limit, workedMs: budget.workedMs() },
+						"owner continued the turn past its time limit",
+					);
+				} else
+					stop(
+						reason(
+							limit,
+							limitMs,
+							approval === "declined" ? "cancelled" : "timeout",
+						),
+					);
+			};
+			prompts
+				.confirm(
+					m.turnTimeoutTitle,
+					m.turnTimeoutQuestion(asked, turnTimeoutMs),
+					undefined,
+					"owner",
+					undefined,
+					undefined,
+					{
+						supersede: controller.signal,
+						wording: {
+							approve: m.turnTimeoutContinue,
+							decline: m.turnTimeoutCancel,
+							footer: m.turnTimeoutFooter,
+							approved: m.turnTimeoutContinued,
+							declined: m.turnTimeoutCancelled,
+						},
+					},
+				)
+				.then(answered, (error: unknown) => {
+					logger.warn({ channel, err: error }, "timeout card failed");
+					answered("unavailable");
+				});
+		},
+		clock,
+	);
 	return {
 		...budget,
 		renew() {
@@ -117,5 +257,9 @@ export function runtimeTurnBudget(
 				);
 			return deadlineMs;
 		},
+		cancel() {
+			budget.cancel();
+			closeCard?.(messages().turnTimeoutFinished);
+		},
 	};
 }

package/src/core/runtime/turn-limits.ts

@@ -0,0 +1,61 @@
+import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+import type { TurnResult } from "../domain/conversation.ts";
+import { AgentRunError } from "../domain/errors.ts";
+import { type TurnTimeout, TurnTimeoutError } from "../domain/turn-timeout.ts";
+import { catalogFor } from "../i18n/index.ts";
+import type { ChannelKey } from "../sessions.ts";
+import type { PromptSlot } from "./prompt-slot.ts";
+import { activityTracker } from "./turn-activity.ts";
+import { runtimeTurnBudget, type TurnBudget } from "./turn-budget.ts";
+
+/** One turn's time limit, with what it follows of the turn to say why it fired. */
+export interface TurnLimits {
+	budget: TurnBudget;
+	/** Follows the turn's events: its tools and its compactions. */
+	observe(event: AgentSessionEvent): void;
+	/** The turn's failure when a limit aborted it, its reason as a `TurnTimeoutError`; else undefined. */
+	failure(): TurnResult | undefined;
+}
+
+/** The answer to a turn whose prompt threw, when no limit aborted it. */
+export function promptFailed(error: unknown): TurnResult {
+	return {
+		ok: false,
+		error: new AgentRunError(`prompt failed: ${String(error)}`),
+	};
+}
+
+/** A timed-out turn's reason in English, for its error and the logs. */
+export function timeoutMessage(timeout: TurnTimeout): string {
+	return catalogFor("en").turnTimedOutNotice(timeout);
+}
+
+/** The time limit of a turn of the built-in runtime; see `runtimeTurnBudget`. `abort` aborts the turn. */
+export function turnLimits(
+	options: Parameters<typeof runtimeTurnBudget>[0],
+	slot: Pick<PromptSlot, "waitedMs" | "cards">,
+	channel: ChannelKey,
+	abort: () => void,
+): TurnLimits {
+	const activity = activityTracker();
+	let timedOut: TurnTimeout | undefined;
+	const budget = runtimeTurnBudget(
+		options,
+		slot,
+		channel,
+		(timeout) => {
+			timedOut = timeout;
+			abort();
+		},
+		{ activity },
+	);
+	return {
+		budget,
+		observe: (event) => activity.observe(event),
+		failure: () =>
+			timedOut && {
+				ok: false,
+				error: new TurnTimeoutError(timedOut, timeoutMessage(timedOut)),
+			},
+	};
+}

package/src/index.ts

@@ -139,6 +139,12 @@ export type {
 } from "./core/domain/interim.ts";
 export type { TurnConversation, TurnRequest } from "./core/domain/ports.ts";
 export type { HoldRefusal, TurnProgress } from "./core/domain/progress.ts";
+export {
+	type TurnLimit,
+	type TurnTimeout,
+	type TurnTimeoutEnd,
+	TurnTimeoutError,
+} from "./core/domain/turn-timeout.ts";
 export type { DrainOptions } from "./core/drain.ts";
 export {
 	HostStoppingError,
@@ -194,6 +200,7 @@ export type {
 	ApprovalDetails,
 	ApprovalFile,
 	ApprovalOptions,
+	ApprovalWording,
 	ApprovedBy,
 	AskOption,
 	AskSupport,