pi-roundtable 0.29.0 → 0.29.2

package/CHANGELOG.md

@@ -5,6 +5,16 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.29.2] - 2026-10-31
+
+- Release for the web package's changes (see its changelog); no core behavior changes.
+
+## [0.29.1] - 2026-10-31
+
+### Added
+
+- Queued messages can be listed, edited and cancelled. A message sent while a turn runs that the turn did not take waits in the channel's queue (`QUEUED_MARK`); until its own turn starts, `ConversationPort.queued(channel)` lists it (`QueuedMessage`: `messageId`, `principalId`, `text`, `queuedAt`), `cancelQueued(channel, messageId, by)` makes its turn never run (the claim's `Admission.dropped` is called and the mark comes off), and `editQueued(channel, messageId, by, text)` admits it again with the new text, so the turn runs on that. `by` is the author's principal (`QueuedBy`); anyone else gets `forbidden`, and a message that started, was steered or was cancelled is `unknown` (`QueuedChange`). The three are optional on the port type, as `messageDeleted` is. A surface that reports a deleted queued message cancels it, and one that reports an edited one changes its text, through `SurfaceMessageEvents` as before: on Discord, deleting a queued message cancels it and editing it changes what its turn uses. `QUEUED_MARK` and `STEERED_MARK` are exported from the main entry.
+
 ## [0.29.0] - 2026-10-31
 
 ### Added

package/docs/plugins.md

@@ -2436,6 +2436,8 @@ When that record finds the author someone else than the claim admitted, such as
 
 A claim may also hear that a message it owns changed, through `onMessageDeleted(channel, messageId)` and `onMessageEdited(message)`, which a surface reports with the second argument of its `start` (`{ deleted, edited }`, a `SurfaceMessageEvents`). Discord reports both, including for a message the bot had not cached; a surface that cannot tell never calls them. The router delivers each as it comes, to the claim that owns the channel and no other, outside the channel's queue, so a running turn does not hold it up; a throw or rejection is logged and never fails the router. A delete carries only ids, and Discord's delete event does not say who wrote the message, so the claim hears the deletion of the bot's own messages too and ignores an id it does not know. An edit carries the message as it reads now, as an `InboundMessage`, without `speaker` or `peerBot` because nobody is resolved or admitted for it; the bot's own edits are not reported, nor is a change that leaves the text, the embeds and the attachments as they were, such as a pin. A bulk delete is reported as one delete per message.
 
+A message sent while a turn runs is first offered to that turn (`busy.steer`); one the turn does not take waits in the channel's queue with `QUEUED_MARK`, and until its own turn starts the conversation port can list, cancel and edit it: `queued(channel)` returns its waiting messages oldest first (`messageId`, the author's `principalId`, the `text` its turn will use, `queuedAt`); `cancelQueued(channel, messageId, { principalId })` makes its turn never run, calling the admission's `dropped` and removing the mark; `editQueued(channel, messageId, { principalId }, text)` admits the message again with the new text through the claim's `admit`, drops the old admission, and the turn runs on the new one. Only the message's author may (a different principal gets `forbidden`, and a message with no resolved author can be changed by no one). A message whose turn has started, was steered into the running turn, or was cancelled is `unknown`; an edit the claim would no longer admit is `refused` and the old text stays. The decision is made in one synchronous step, so a cancel or an edit and the start of the turn never both win. The surface's own copy of the message is the caller's to change. When a surface reports a queued message deleted or edited (`onMessageDeleted`, `onMessageEdited` above), the router cancels it or changes its text itself, without the author check since the surface says it happened: that is how deleting a queued Discord message cancels it. The three methods are optional on `ConversationPort`, as `messageDeleted` is.
+
 A claim may have `stop(channel)`, which stops the channel's running turn and returns whether one was running; the Stop button, `conversations.stop`, and every other stop go through it.
 The router calls only the owning claim's `stop`, returning `false` when that method is absent.
 Give `stop` to a claim whose conversations run turns that can be interrupted.
@@ -4566,6 +4568,11 @@ Import from the entries listed below; source area files are internal.
 | `Provisioning` | `pi-roundtable` | type |
 | `ProvisioningRule` | `pi-roundtable` | type |
 | `QueuePort` | `pi-roundtable` | type |
+| `QueuedBy` | `pi-roundtable` | type |
+| `QueuedChange` | `pi-roundtable` | type |
+| `QueuedMessage` | `pi-roundtable` | type |
+| `QUEUED_MARK` | `pi-roundtable` | value |
+| `STEERED_MARK` | `pi-roundtable` | value |
 | `QUESTIONNAIRE_LIMITS` | `pi-roundtable` | value |
 | `Questionnaire` | `pi-roundtable` | type |
 | `QuestionnaireAnswer` | `pi-roundtable` | type |

package/package.json

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

package/src/core/contract/channels.ts

@@ -109,6 +109,31 @@ export interface InboundMessage {
 export const STEERED_MARK = "↪️";
 export const QUEUED_MARK = "⏳";
 
+/** A message waiting in a channel's queue for its own turn (`ConversationPort.queued`). */
+export interface QueuedMessage {
+	/** The surface's id of the message, as `InboundMessage.messageId`. */
+	messageId: string;
+	/** The principal of the person who wrote it; absent when the router resolved none. */
+	principalId?: string;
+	/** What its turn will use: the text as last edited. */
+	text: string;
+	/** Epoch milliseconds when it was queued. */
+	queuedAt: number;
+}
+
+/** Who asks to change a queued message; only its author may. */
+export interface QueuedBy {
+	principalId: string;
+}
+
+/**
+ * What cancelling or editing a queued message came to. `unknown`: none is queued under that id,
+ * such as one whose turn has started, been cancelled, or been steered into the running turn.
+ * `forbidden`: it is queued, but not by that principal. `refused` (edit only): the claim would no
+ * longer take the message with the new text.
+ */
+export type QueuedChange = "done" | "unknown" | "forbidden" | "refused";
+
 /** How a turn nobody wrote in the channel ended. */
 export type ScheduledOutcome =
 	| { status: "ran" }
@@ -205,8 +230,8 @@ export type Admission =
 			run(): Promise<void>;
 			/**
 			 * Called instead of `run` when the router drops the message the claim admitted, because
-			 * its author, once recorded, was not who they were when admitted; frees what the claim
-			 * holds for it.
+			 * its author, once recorded, was not who they were when admitted, or because it was
+			 * cancelled or replaced by an edit while it waited; frees what the claim holds for it.
 			 */
 			dropped?(): void;
 			/** The log line when the turn throws. */
@@ -327,6 +352,34 @@ export interface ConversationPort {
 	): Promise<void>;
 	/** Tells the claim that owns the channel a message was edited (`ChannelClaim.onMessageEdited`); never rejects. */
 	messageEdited?(message: InboundMessage): Promise<void>;
+	/**
+	 * The messages waiting in the channel for their own turn, oldest first: a message sent during
+	 * a turn that the running turn did not take (`QUEUED_MARK`). One that started, was steered
+	 * into the running turn, or was cancelled is not listed. Optional so a port written before 0.28
+	 * still type-checks; the host's has it.
+	 */
+	queued?(channel: ChannelKey): readonly QueuedMessage[];
+	/**
+	 * Cancels a queued message so its turn never starts, for its author only. `unknown` once the
+	 * turn has started, so a caller can tell the person it is too late. The surface is told only
+	 * through the message's `QUEUED_MARK` being removed.
+	 */
+	cancelQueued?(
+		channel: ChannelKey,
+		messageId: string,
+		by: QueuedBy,
+	): QueuedChange;
+	/**
+	 * Replaces the text a queued message's turn will use, for its author only: the claim that
+	 * admitted the message admits it again with the new text, and the turn runs on that. The
+	 * surface's own copy of the message is the caller's to change.
+	 */
+	editQueued?(
+		channel: ChannelKey,
+		messageId: string,
+		by: QueuedBy,
+		text: string,
+	): QueuedChange;
 }
 
 /**

package/src/core/host-registration.ts

@@ -274,6 +274,10 @@ export class Linkage {
 			messageDeleted: (channel, id, space) =>
 				router().messageDeleted(channel, id, space),
 			messageEdited: (message) => router().messageEdited(message),
+			queued: (channel) => router().queued(channel),
+			cancelQueued: (channel, id, by) => router().cancelQueued(channel, id, by),
+			editQueued: (channel, id, by, text) =>
+				router().editQueued(channel, id, by, text),
 			background: (turn) => router().background(turn),
 			runsAs: (turn) => router().runsAs(turn),
 			target: (name) => router().target(name),

package/src/core/routing/actor-of.ts

@@ -0,0 +1,40 @@
+import type { InboundMessage } from "../contract/channels.ts";
+import { parseChannelKey } from "../contract/surface.ts";
+import type { ActorFacts } from "../identity/actor-facts.ts";
+import type { Logger } from "../log.ts";
+
+/**
+ * Who wrote the message, as its surface reports them; a surface that reports no `actor` has it
+ * read from the author fields under its own name, once warned (`warned` holds the surfaces
+ * already warned). None for a bot or an integration, unless the host lists the bot as a peer.
+ */
+export function actorOf(
+	message: InboundMessage,
+	warned: Set<string>,
+	logger: Logger,
+): ActorFacts | undefined {
+	if ((message.authorIsBot && !message.peerBot) || message.integration)
+		return undefined;
+	if (message.actor) return message.actor;
+	const { surface } = parseChannelKey(message.channel);
+	if (!warned.has(surface)) {
+		warned.add(surface);
+		logger.warn(
+			{ surface },
+			`deprecated: the ${surface} surface reports no InboundMessage.actor, so its authors are read from authorId, authorName, and authorRoleIds as ${surface} identities; set actor, as this goes away in 1.0`,
+		);
+	}
+	return {
+		provider: surface,
+		subject: message.authorId,
+		name: message.authorName,
+		surface,
+		...(message.authorRoleIds
+			? {
+					roles: message.authorRoleIds.map((role) => `${surface}:role:${role}`),
+				}
+			: {}),
+		...(message.space ? { space: message.space } : {}),
+		legacyId: message.authorId,
+	};
+}

package/src/core/routing/background-speaker.ts

@@ -0,0 +1,50 @@
+import type { BackgroundRunsAs, BackgroundTurn } from "../contract/channels.ts";
+import { IdentityError } from "../domain/errors.ts";
+import {
+	type IdentityService,
+	systemSpeaker,
+} from "../identity/identity-service.ts";
+import { SYSTEM_PRINCIPAL } from "../identity/principal-store.ts";
+import { isSystemTurn } from "./system-turns.ts";
+
+/**
+ * Who a background turn runs as, before its claim has the last word: the system principal for
+ * the host's own turn, at its tier; otherwise its author's principal, which the identity service
+ * checks and caps at the lower of the turn's tier and theirs. Why not, when it may not run;
+ * throws when the identity service cannot tell.
+ */
+export async function speakerOf(
+	turn: BackgroundTurn,
+	principals: Pick<IdentityService, "speakerFor"> | undefined,
+): Promise<BackgroundRunsAs> {
+	const { author, tier } = turn;
+	if (!author?.principalId || !tier)
+		return {
+			skipped:
+				"a background turn names its author's principal (author.principalId) and the tier it runs at (tier); this one does not",
+		};
+	if (author.principalId === SYSTEM_PRINCIPAL)
+		return isSystemTurn(turn)
+			? { speaker: { ...systemSpeaker(tier), name: author.name } }
+			: {
+					skipped: `only the host itself starts a turn as the system principal "${SYSTEM_PRINCIPAL}"`,
+				};
+	if (!principals)
+		return {
+			skipped: "the host has no identity service to check whom it runs as",
+		};
+	try {
+		const checked = await principals.speakerFor(author.principalId, tier);
+		return {
+			speaker: {
+				id: author.id,
+				name: author.name,
+				tier: checked.tier,
+				principalId: checked.principalId,
+			},
+		};
+	} catch (error) {
+		if (!(error instanceof IdentityError)) throw error;
+		return { skipped: error.message };
+	}
+}

package/src/core/routing/channel-router.ts

@@ -7,28 +7,27 @@ import {
 	type ConversationPort,
 	type InboundMessage,
 	QUEUED_MARK,
+	type QueuedBy,
+	type QueuedChange,
+	type QueuedMessage,
 	type ScheduledOutcome,
 	STEERED_MARK,
 } from "../contract/channels.ts";
-import { parseChannelKey, type SurfacePort } from "../contract/surface.ts";
-import { IdentityError } from "../domain/errors.ts";
+import type { SurfacePort } from "../contract/surface.ts";
 import { HostStoppingError, PluginError } from "../errors.ts";
 import { messages } from "../i18n/index.ts";
-import type { ActorFacts } from "../identity/actor-facts.ts";
 import type { Contact, ContactAssessor } from "../identity/contact.ts";
-import {
-	type IdentityService,
-	systemSpeaker,
-} from "../identity/identity-service.ts";
-import { SYSTEM_PRINCIPAL } from "../identity/principal-store.ts";
+import type { IdentityService } from "../identity/identity-service.ts";
 import type { Logger } from "../log.ts";
 import type { ChannelKey } from "../sessions.ts";
+import { actorOf } from "./actor-of.ts";
+import { speakerOf } from "./background-speaker.ts";
 import type { ChannelQueue } from "./channel-queue.ts";
 import { tellDeleted, tellEdited } from "./claim-events.ts";
 import { ForwardJoin } from "./forward-join.ts";
 import type { MessageObservers } from "./message-observers.ts";
 import { type PeerBots, peerFacts } from "./peer-bots.ts";
-import { isSystemTurn } from "./system-turns.ts";
+import { type QueuedEntry, QueuedMessages } from "./queued-messages.ts";
 
 export interface ChannelRouterOptions {
 	/** Claims in registration order; the router orders them by priority. */
@@ -82,6 +81,8 @@ export class ChannelRouter implements ConversationPort {
 	readonly #options: ChannelRouterOptions;
 	readonly #claims: readonly ChannelClaim[];
 	readonly #forwards: ForwardJoin;
+	/** The messages waiting for their own turn, so one can be cancelled or edited until it starts. */
+	readonly #queued: QueuedMessages;
 	/** Each channel's messages being admitted, so they reach their claim and the queue in the order they came. */
 	readonly #admitting = new Map<ChannelKey, Promise<unknown>>();
 	/** The surfaces already warned that their messages carry no actor. */
@@ -93,6 +94,7 @@ export class ChannelRouter implements ConversationPort {
 		this.#options = options;
 		this.#claims = orderClaims(options.claims);
 		this.#forwards = new ForwardJoin(options.forwardJoinMs);
+		this.#queued = new QueuedMessages(options.logger);
 	}
 
 	#owner(channel: ChannelKey, space?: string): ChannelClaim | undefined {
@@ -137,15 +139,16 @@ export class ChannelRouter implements ConversationPort {
 				);
 				return undefined;
 			}
-			const admission = await this.#admit(claim, message);
-			if (!admission) return undefined;
+			const admitted = await this.#admit(claim, message);
+			if (!admitted) return undefined;
+			const { admission } = admitted;
 			if (listed) peers?.answered(message.channel);
 			// Once the host shuts down only the turns already running finish: this one starts nothing.
 			if (this.#options.queue.closed) {
 				await this.#refuse(message, admission);
 				return undefined;
 			}
-			return this.#start(message, admission);
+			return this.#start(claim, admitted.message, admission);
 		});
 		await started?.done;
 	}
@@ -177,10 +180,10 @@ export class ChannelRouter implements ConversationPort {
 	async #admit(
 		claim: ChannelClaim,
 		message: InboundMessage,
-	): Promise<Admission | undefined> {
+	): Promise<{ admission: Admission; message: InboundMessage } | undefined> {
 		const { logger, contacts } = this.#options;
 		const { speaker: _given, ...facts } = message;
-		const actor = this.#actorOf(message);
+		const actor = actorOf(message, this.#warned, logger);
 		let contact: Contact | undefined;
 		if (actor && contacts)
 			try {
@@ -193,15 +196,16 @@ export class ChannelRouter implements ConversationPort {
 					"could not resolve who wrote a message; it reaches its claim as no one",
 				);
 			}
-		const admission = claim.admit(
-			contact
-				? { ...facts, speaker: Object.freeze({ ...contact.speaker }) }
-				: facts,
-		);
-		if (!admission || !contact) return admission;
+		const admittedAs: InboundMessage = contact
+			? { ...facts, speaker: Object.freeze({ ...contact.speaker }) }
+			: facts;
+		const admission = claim.admit(admittedAs);
+		if (!admission) return undefined;
+		if (!contact) return { admission, message: admittedAs };
 		try {
 			const taken = await contact.take();
-			if (taken?.principalId === contact.speaker.principalId) return admission;
+			if (taken?.principalId === contact.speaker.principalId)
+				return { admission, message: admittedAs };
 			logger.warn(
 				{ channel: message.channel },
 				"the author of a message was linked elsewhere, or refused, while it was admitted; it does not run",
@@ -221,40 +225,6 @@ export class ChannelRouter implements ConversationPort {
 		return undefined;
 	}
 
-	/**
-	 * Who wrote the message, as its surface reports them; a surface that reports no `actor` has it
-	 * read from the author fields under its own name, once warned. None for a bot or an
-	 * integration, unless the host lists the bot as a peer.
-	 */
-	#actorOf(message: InboundMessage): ActorFacts | undefined {
-		if ((message.authorIsBot && !message.peerBot) || message.integration)
-			return undefined;
-		if (message.actor) return message.actor;
-		const { surface } = parseChannelKey(message.channel);
-		if (!this.#warned.has(surface)) {
-			this.#warned.add(surface);
-			this.#options.logger.warn(
-				{ surface },
-				`deprecated: the ${surface} surface reports no InboundMessage.actor, so its authors are read from authorId, authorName, and authorRoleIds as ${surface} identities; set actor, as this goes away in 1.0`,
-			);
-		}
-		return {
-			provider: surface,
-			subject: message.authorId,
-			name: message.authorName,
-			surface,
-			...(message.authorRoleIds
-				? {
-						roles: message.authorRoleIds.map(
-							(role) => `${surface}:role:${role}`,
-						),
-					}
-				: {}),
-			...(message.space ? { space: message.space } : {}),
-			legacyId: message.authorId,
-		};
-	}
-
 	/**
 	 * Drops a message the host no longer starts a turn for because it is shutting down, and tells
 	 * its channel once that it restarts; no one is told for a bot's or an integration's message, such
@@ -287,6 +257,7 @@ export class ChannelRouter implements ConversationPort {
 	 * during a turn is first offered to it, then marked as waiting.
 	 */
 	async #start(
+		claim: ChannelClaim,
 		message: InboundMessage,
 		admission: Admission,
 	): Promise<{ done: Promise<void> }> {
@@ -298,39 +269,71 @@ export class ChannelRouter implements ConversationPort {
 			return { done };
 		}
 		const { busy } = admission;
-		let queued = false;
+		let waiting: QueuedEntry | undefined;
 		// A message during a turn is added to it when the turn takes it, otherwise marked as waiting.
 		if (busy && queue.size(message.channel) > 0) {
 			if (await busy.steer?.()) return { done: busy.react(STEERED_MARK) };
+			// Listed before the mark is placed, so a delete or cancel during that wait reaches it.
+			waiting = this.#queued.add(claim, message, admission);
 			await busy.react(QUEUED_MARK);
-			queued = true;
+			if (waiting.cancelled) return { done: Promise.resolve() };
 		}
 		const done = queue
 			.run(message.channel, () => {
-				if (queued) void busy?.unreact(QUEUED_MARK);
-				return admission.run();
+				if (!waiting) return admission.run();
+				// From here no cancel or edit reaches it: the turn has started or it was cancelled before.
+				if (!this.#queued.remove(waiting)) return Promise.resolve();
+				this.#queued.unmark(waiting);
+				return waiting.admission.run();
 			})
 			// pi-lens-ignore: no-unknown-parameters
 			.catch(async (error: unknown) => {
 				// The host began shutting down while this message waited behind a running turn.
 				if (error instanceof HostStoppingError) {
-					if (queued) void busy?.unreact(QUEUED_MARK);
-					return this.#refuse(message, admission);
+					if (waiting && !this.#queued.remove(waiting)) return undefined;
+					if (waiting) this.#queued.unmark(waiting);
+					return this.#refuse(
+						waiting?.message ?? message,
+						waiting?.admission ?? admission,
+					);
 				}
 				logger.error(
 					{ channel: message.channel, err: error },
-					admission.failure,
+					(waiting?.admission ?? admission).failure,
 				);
 			});
 		return { done };
 	}
 
+	queued(channel: ChannelKey): readonly QueuedMessage[] {
+		return this.#queued.list(channel);
+	}
+
+	cancelQueued(
+		channel: ChannelKey,
+		messageId: string,
+		by: QueuedBy,
+	): QueuedChange {
+		return this.#queued.cancel(channel, messageId, by, true);
+	}
+
+	editQueued(
+		channel: ChannelKey,
+		messageId: string,
+		by: QueuedBy,
+		text: string,
+	): QueuedChange {
+		return this.#queued.edit(channel, messageId, by, text);
+	}
+
 	/** Tells the claim that owns the channel a message was deleted; never rejects, never waits for the channel's queue. */
 	messageDeleted(
 		channel: ChannelKey,
 		messageId: string,
 		space?: string,
 	): Promise<void> {
+		// The surface says it is gone: no author check, and no mark to remove from a deleted message.
+		this.#queued.cancel(channel, messageId, undefined, false);
 		return tellDeleted(
 			this.#owner(channel, space),
 			channel,
@@ -341,6 +344,13 @@ export class ChannelRouter implements ConversationPort {
 
 	/** Tells the claim that owns the channel a message was edited; never rejects, never waits for the channel's queue. */
 	messageEdited(message: InboundMessage): Promise<void> {
+		// Only the author edits a message, so a queued one takes the new text without a check.
+		this.#queued.edit(
+			message.channel,
+			message.messageId,
+			undefined,
+			message.text,
+		);
 		return tellEdited(
 			this.#owner(message.channel, message.space),
 			message,
@@ -392,7 +402,7 @@ export class ChannelRouter implements ConversationPort {
 	 * service cannot tell.
 	 */
 	async runsAs(turn: BackgroundTurn): Promise<BackgroundRunsAs> {
-		const runs = await this.#speakerOf(turn);
+		const runs = await speakerOf(turn, this.#options.principals);
 		if ("skipped" in runs) return runs;
 		// The claim that owns the channel has the last word, so work that must not start for a turn it
 		// would skip, such as a schedule's precheck, does not.
@@ -403,40 +413,6 @@ export class ChannelRouter implements ConversationPort {
 		return refusal === undefined ? runs : { skipped: refusal };
 	}
 
-	async #speakerOf(turn: BackgroundTurn): Promise<BackgroundRunsAs> {
-		const { author, tier } = turn;
-		if (!author?.principalId || !tier)
-			return {
-				skipped:
-					"a background turn names its author's principal (author.principalId) and the tier it runs at (tier); this one does not",
-			};
-		if (author.principalId === SYSTEM_PRINCIPAL)
-			return isSystemTurn(turn)
-				? { speaker: { ...systemSpeaker(tier), name: author.name } }
-				: {
-						skipped: `only the host itself starts a turn as the system principal "${SYSTEM_PRINCIPAL}"`,
-					};
-		const { principals } = this.#options;
-		if (!principals)
-			return {
-				skipped: "the host has no identity service to check whom it runs as",
-			};
-		try {
-			const checked = await principals.speakerFor(author.principalId, tier);
-			return {
-				speaker: {
-					id: author.id,
-					name: author.name,
-					tier: checked.tier,
-					principalId: checked.principalId,
-				},
-			};
-		} catch (error) {
-			if (!(error instanceof IdentityError)) throw error;
-			return { skipped: error.message };
-		}
-	}
-
 	startFresh(channel: ChannelKey): Promise<string> {
 		return this.#options.queue.run(channel, async () => {
 			const claim = this.#owner(channel);

package/src/core/routing/queued-messages.ts

@@ -0,0 +1,151 @@
+import {
+	type Admission,
+	type ChannelClaim,
+	type InboundMessage,
+	QUEUED_MARK,
+	type QueuedBy,
+	type QueuedChange,
+	type QueuedMessage,
+} from "../contract/channels.ts";
+import type { Logger } from "../log.ts";
+import type { ChannelKey } from "../sessions.ts";
+
+type TurnAdmission = Extract<Admission, { kind: "turn" }>;
+
+/** A message waiting for its turn, with what runs it; `admission` and `message` follow its edits. */
+export interface QueuedEntry {
+	readonly claim: ChannelClaim;
+	/** The message as the claim last admitted it: the speaker the router resolved, the text as edited. */
+	message: InboundMessage;
+	admission: TurnAdmission;
+	readonly queuedAt: number;
+	/** Cancelled while it waited: its turn does not run. */
+	cancelled: boolean;
+}
+
+/**
+ * The messages waiting for their own turn, by channel and message id: the router adds one when
+ * the running turn did not take it and takes it out when its turn starts, so a cancel or an edit
+ * can only reach a message that has not started. Everything is synchronous, so no cancel or edit
+ * races the start of a turn: whichever runs first wins.
+ */
+export class QueuedMessages {
+	readonly #entries = new Map<ChannelKey, Map<string, QueuedEntry>>();
+	readonly #logger: Logger;
+	readonly #now: () => number;
+
+	constructor(logger: Logger, now: () => number = Date.now) {
+		this.#logger = logger;
+		this.#now = now;
+	}
+
+	add(
+		claim: ChannelClaim,
+		message: InboundMessage,
+		admission: TurnAdmission,
+	): QueuedEntry {
+		const entry: QueuedEntry = {
+			claim,
+			message,
+			admission,
+			queuedAt: this.#now(),
+			cancelled: false,
+		};
+		const channel = this.#entries.get(message.channel) ?? new Map();
+		channel.set(message.messageId, entry);
+		this.#entries.set(message.channel, channel);
+		return entry;
+	}
+
+	/** Takes the entry out of the queue's books as its turn starts or the host drops it; false when already out. */
+	remove(entry: QueuedEntry): boolean {
+		const { channel, messageId } = entry.message;
+		const held = this.#entries.get(channel);
+		if (held?.get(messageId) !== entry) return false;
+		held.delete(messageId);
+		if (held.size === 0) this.#entries.delete(channel);
+		return true;
+	}
+
+	list(channel: ChannelKey): readonly QueuedMessage[] {
+		return [...(this.#entries.get(channel)?.values() ?? [])].map((entry) => ({
+			messageId: entry.message.messageId,
+			...(entry.message.speaker
+				? { principalId: entry.message.speaker.principalId }
+				: {}),
+			text: entry.message.text,
+			queuedAt: entry.queuedAt,
+		}));
+	}
+
+	/**
+	 * Cancels the message so its turn never starts. `by` is checked against its author, and absent
+	 * when the surface itself says the message is gone, such as a deleted one. `unmark` removes the
+	 * waiting mark from the message, which a deleted message cannot take.
+	 */
+	cancel(
+		channel: ChannelKey,
+		messageId: string,
+		by: QueuedBy | undefined,
+		unmark: boolean,
+	): QueuedChange {
+		const entry = this.#entries.get(channel)?.get(messageId);
+		if (!entry) return "unknown";
+		if (by && !this.#authored(entry, by)) return "forbidden";
+		this.remove(entry);
+		entry.cancelled = true;
+		entry.admission.dropped?.();
+		if (unmark) this.unmark(entry);
+		return "done";
+	}
+
+	/**
+	 * Gives the message's turn the new text: the claim admits the message again with it. When the
+	 * claim no longer takes it, the old admission stays and the edit is refused.
+	 */
+	edit(
+		channel: ChannelKey,
+		messageId: string,
+		by: QueuedBy | undefined,
+		text: string,
+	): QueuedChange {
+		const entry = this.#entries.get(channel)?.get(messageId);
+		if (!entry) return "unknown";
+		if (by && !this.#authored(entry, by)) return "forbidden";
+		if (entry.message.text === text) return "done";
+		const message = { ...entry.message, text };
+		let next: Admission | undefined;
+		try {
+			next = entry.claim.admit(message);
+		} catch (error) {
+			this.#logger.warn(
+				{ channel, err: error },
+				"a claim failed to admit an edited queued message; the old text stays",
+			);
+		}
+		if (next?.kind !== "turn") return "refused";
+		const old = entry.admission;
+		entry.message = message;
+		entry.admission = next;
+		old.dropped?.();
+		return "done";
+	}
+
+	/** Removes the waiting mark; a failure is logged, since the message may be gone. */
+	unmark(entry: QueuedEntry): void {
+		const { channel } = entry.message;
+		entry.admission.busy
+			?.unreact(QUEUED_MARK)
+			.catch((error: unknown) =>
+				this.#logger.warn(
+					{ channel, err: error },
+					"the waiting mark of a queued message was not removed",
+				),
+			);
+	}
+
+	#authored(entry: QueuedEntry, by: QueuedBy): boolean {
+		const author = entry.message.speaker?.principalId;
+		return author !== undefined && author === by.principalId;
+	}
+}

package/src/index.ts

@@ -93,9 +93,13 @@ export type {
 	InboundMessage,
 	MessageObserver,
 	ObserveFilter,
+	QueuedBy,
+	QueuedChange,
+	QueuedMessage,
 	QueuePort,
 	ScheduledOutcome,
 } from "./core/contract/channels.ts";
+export { QUEUED_MARK, STEERED_MARK } from "./core/contract/channels.ts";
 export type {
 	ImageDrawer,
 	Judge,