pi-harness-runtime 1.1.459 → 1.1.461

package/CHANGELOG.md

@@ -2,6 +2,83 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [1.1.461](https://github.com/ManotLuijiu/pi-harness-runtime/compare/v1.1.448...v1.1.461) (2026-10-28)
+
+
+### Features
+
+* **delegation:** a child is only a child when it really ran ([ac4e678](https://github.com/ManotLuijiu/pi-harness-runtime/commit/ac4e6782d7d4bc4941e458425c8a9f38a51fc9d4))
+* **delegation:** the scope of a request is measured before it is judged ([684b6a5](https://github.com/ManotLuijiu/pi-harness-runtime/commit/684b6a55184f63d3be24c48dcecfb0b13410dc15))
+* **honcho:** the memory service speaks the native MCP of Pi ([f9f740c](https://github.com/ManotLuijiu/pi-harness-runtime/commit/f9f740c12869bae4c4380afbe8c76e12388bb744))
+* **jev:** the pending question carries the ask and the answer ([a792133](https://github.com/ManotLuijiu/pi-harness-runtime/commit/a792133e517fb8c12d3363e98942f3af30270f27))
+* **jev:** the pending question counts down to the decision ([d0cc171](https://github.com/ManotLuijiu/pi-harness-runtime/commit/d0cc171223986b2d32c670b6c1c74712fe0a4ad8))
+* **keys:** the key files are repaired when their permissions are unsafe ([e9c2c26](https://github.com/ManotLuijiu/pi-harness-runtime/commit/e9c2c26b287665b56ed749de269737e8403bb8af))
+* **merge:** a manual run can leave the merge to the pull request event ([b3d1950](https://github.com/ManotLuijiu/pi-harness-runtime/commit/b3d1950b5941c78ccd56951acdafd1d4afbe1bff))
+* **phase:** the agent owns the todo list and the harness says so ([c489370](https://github.com/ManotLuijiu/pi-harness-runtime/commit/c489370bd7926aece8cb1a77aa20ca2d2672f1fb))
+* **review:** the review starts on its own when the implementation is done ([04f51f5](https://github.com/ManotLuijiu/pi-harness-runtime/commit/04f51f599cd3222b6c74dd8fadb1373bd72d9bd7))
+* **status:** the status line names the phase, the progress and the children ([0167bf3](https://github.com/ManotLuijiu/pi-harness-runtime/commit/0167bf396a0b987c1d44f3b869351976a951dd65))
+* **test:** the task waits for the final tier of the validation plan ([fa147db](https://github.com/ManotLuijiu/pi-harness-runtime/commit/fa147dbf7d50d56e6ea48c6d8fbb4fcb190caf8a))
+* **validation:** a large job starts with a measured pilot ([425964b](https://github.com/ManotLuijiu/pi-harness-runtime/commit/425964b04a3d4fa02adfabed47ff62c5ec2b9c28))
+* **validation:** the size of a job is a fact, not a phrase ([8aa6c11](https://github.com/ManotLuijiu/pi-harness-runtime/commit/8aa6c119565d0f8412dc8aeafa6b295d47d3f093))
+
+
+### Bug Fixes
+
+* **ci:** every run of a required check counts, and the worst one decides ([da9e0da](https://github.com/ManotLuijiu/pi-harness-runtime/commit/da9e0da6b0ca29cb320764fd5fc1b8a8dee8b1e0))
+* **ci:** the newest attempt of a run decides, not the attempt that failed ([9d7adcc](https://github.com/ManotLuijiu/pi-harness-runtime/commit/9d7adcc31cbacc517c3c1a9bcd3956be94c908ef))
+* **hooks:** a tag is checked through the commit behind it ([c823e8e](https://github.com/ManotLuijiu/pi-harness-runtime/commit/c823e8e1f6973c62b5449a97c101759a4d5cbba5))
+* **jev:** a session switch ends the wait of the old session ([ca03d39](https://github.com/ManotLuijiu/pi-harness-runtime/commit/ca03d399c0d4a1b2dd428ac39836ab53c0e51ab6))
+* **jev:** the alternatives of a question are parsed without a quadratic pattern ([63016a3](https://github.com/ManotLuijiu/pi-harness-runtime/commit/63016a3f0488acb801990dd46770c00d382b5858))
+* **keys:** the key directory is audited as a tree ([081cc75](https://github.com/ManotLuijiu/pi-harness-runtime/commit/081cc75ac8ceff36b0d619c3f76371dc08459d3c))
+* **merge:** the boolean input is read as a boolean ([971b716](https://github.com/ManotLuijiu/pi-harness-runtime/commit/971b7169a43db382dbdeb6bb9bab02ab56e0351c))
+* **merge:** the manual job needs the right of the merge ([7ba685e](https://github.com/ManotLuijiu/pi-harness-runtime/commit/7ba685ec43d815f90aa35b742579e87e76c69209))
+* **merge:** the merge of the pull request is the GraphQL mutation ([972bab4](https://github.com/ManotLuijiu/pi-harness-runtime/commit/972bab4b0f7faf1b0047f3bb767ef6db3de4b2fa))
+* **merge:** the workflow merges the pull request the gates cleared ([d7639ec](https://github.com/ManotLuijiu/pi-harness-runtime/commit/d7639ec9b83723510acb4a5c4e23d5d6167c3af6))
+* **release:** a manual release keeps the version of its manifest ([122e661](https://github.com/ManotLuijiu/pi-harness-runtime/commit/122e661ea48cb8aff14c71dbd0221a4cf0ba4c8e))
+* **release:** the alignment names the reason of a failure ([5814dd0](https://github.com/ManotLuijiu/pi-harness-runtime/commit/5814dd0b780f5839cf8011ed0cbbbb31e7eb0418))
+* **release:** the channels of the package name the release ([a7a273f](https://github.com/ManotLuijiu/pi-harness-runtime/commit/a7a273ffe8398e2b5b07ef1c321777de41792c6e))
+* **release:** the release publishes and leaves the channels alone ([5871746](https://github.com/ManotLuijiu/pi-harness-runtime/commit/5871746589c1281d855dbeb591b02419fa43f22e))
+* **release:** the release pull request names the version of its branch ([a846e83](https://github.com/ManotLuijiu/pi-harness-runtime/commit/a846e83e6de6e529f4bca05e869db0b5eebb37c5))
+* **release:** the release scans the tree of the commit it publishes ([7d47a0b](https://github.com/ManotLuijiu/pi-harness-runtime/commit/7d47a0b5406480a1e1d3a52623a76aabd1e2d0ba))
+
+### [1.1.460](https://github.com/ManotLuijiu/pi-harness-runtime/compare/v1.1.448...v1.1.460) (2026-10-28)
+
+
+### Features
+
+* **delegation:** a child is only a child when it really ran ([ac4e678](https://github.com/ManotLuijiu/pi-harness-runtime/commit/ac4e6782d7d4bc4941e458425c8a9f38a51fc9d4))
+* **delegation:** the scope of a request is measured before it is judged ([684b6a5](https://github.com/ManotLuijiu/pi-harness-runtime/commit/684b6a55184f63d3be24c48dcecfb0b13410dc15))
+* **honcho:** the memory service speaks the native MCP of Pi ([f9f740c](https://github.com/ManotLuijiu/pi-harness-runtime/commit/f9f740c12869bae4c4380afbe8c76e12388bb744))
+* **jev:** the pending question carries the ask and the answer ([a792133](https://github.com/ManotLuijiu/pi-harness-runtime/commit/a792133e517fb8c12d3363e98942f3af30270f27))
+* **jev:** the pending question counts down to the decision ([d0cc171](https://github.com/ManotLuijiu/pi-harness-runtime/commit/d0cc171223986b2d32c670b6c1c74712fe0a4ad8))
+* **keys:** the key files are repaired when their permissions are unsafe ([e9c2c26](https://github.com/ManotLuijiu/pi-harness-runtime/commit/e9c2c26b287665b56ed749de269737e8403bb8af))
+* **merge:** a manual run can leave the merge to the pull request event ([b3d1950](https://github.com/ManotLuijiu/pi-harness-runtime/commit/b3d1950b5941c78ccd56951acdafd1d4afbe1bff))
+* **phase:** the agent owns the todo list and the harness says so ([c489370](https://github.com/ManotLuijiu/pi-harness-runtime/commit/c489370bd7926aece8cb1a77aa20ca2d2672f1fb))
+* **review:** the review starts on its own when the implementation is done ([04f51f5](https://github.com/ManotLuijiu/pi-harness-runtime/commit/04f51f599cd3222b6c74dd8fadb1373bd72d9bd7))
+* **status:** the status line names the phase, the progress and the children ([0167bf3](https://github.com/ManotLuijiu/pi-harness-runtime/commit/0167bf396a0b987c1d44f3b869351976a951dd65))
+* **test:** the task waits for the final tier of the validation plan ([fa147db](https://github.com/ManotLuijiu/pi-harness-runtime/commit/fa147dbf7d50d56e6ea48c6d8fbb4fcb190caf8a))
+* **validation:** a large job starts with a measured pilot ([425964b](https://github.com/ManotLuijiu/pi-harness-runtime/commit/425964b04a3d4fa02adfabed47ff62c5ec2b9c28))
+* **validation:** the size of a job is a fact, not a phrase ([8aa6c11](https://github.com/ManotLuijiu/pi-harness-runtime/commit/8aa6c119565d0f8412dc8aeafa6b295d47d3f093))
+
+
+### Bug Fixes
+
+* **ci:** every run of a required check counts, and the worst one decides ([da9e0da](https://github.com/ManotLuijiu/pi-harness-runtime/commit/da9e0da6b0ca29cb320764fd5fc1b8a8dee8b1e0))
+* **ci:** the newest attempt of a run decides, not the attempt that failed ([9d7adcc](https://github.com/ManotLuijiu/pi-harness-runtime/commit/9d7adcc31cbacc517c3c1a9bcd3956be94c908ef))
+* **hooks:** a tag is checked through the commit behind it ([c823e8e](https://github.com/ManotLuijiu/pi-harness-runtime/commit/c823e8e1f6973c62b5449a97c101759a4d5cbba5))
+* **jev:** the alternatives of a question are parsed without a quadratic pattern ([63016a3](https://github.com/ManotLuijiu/pi-harness-runtime/commit/63016a3f0488acb801990dd46770c00d382b5858))
+* **keys:** the key directory is audited as a tree ([081cc75](https://github.com/ManotLuijiu/pi-harness-runtime/commit/081cc75ac8ceff36b0d619c3f76371dc08459d3c))
+* **merge:** the boolean input is read as a boolean ([971b716](https://github.com/ManotLuijiu/pi-harness-runtime/commit/971b7169a43db382dbdeb6bb9bab02ab56e0351c))
+* **merge:** the manual job needs the right of the merge ([7ba685e](https://github.com/ManotLuijiu/pi-harness-runtime/commit/7ba685ec43d815f90aa35b742579e87e76c69209))
+* **merge:** the merge of the pull request is the GraphQL mutation ([972bab4](https://github.com/ManotLuijiu/pi-harness-runtime/commit/972bab4b0f7faf1b0047f3bb767ef6db3de4b2fa))
+* **merge:** the workflow merges the pull request the gates cleared ([d7639ec](https://github.com/ManotLuijiu/pi-harness-runtime/commit/d7639ec9b83723510acb4a5c4e23d5d6167c3af6))
+* **release:** a manual release keeps the version of its manifest ([122e661](https://github.com/ManotLuijiu/pi-harness-runtime/commit/122e661ea48cb8aff14c71dbd0221a4cf0ba4c8e))
+* **release:** the alignment names the reason of a failure ([5814dd0](https://github.com/ManotLuijiu/pi-harness-runtime/commit/5814dd0b780f5839cf8011ed0cbbbb31e7eb0418))
+* **release:** the channels of the package name the release ([a7a273f](https://github.com/ManotLuijiu/pi-harness-runtime/commit/a7a273ffe8398e2b5b07ef1c321777de41792c6e))
+* **release:** the release publishes and leaves the channels alone ([5871746](https://github.com/ManotLuijiu/pi-harness-runtime/commit/5871746589c1281d855dbeb591b02419fa43f22e))
+* **release:** the release pull request names the version of its branch ([a846e83](https://github.com/ManotLuijiu/pi-harness-runtime/commit/a846e83e6de6e529f4bca05e869db0b5eebb37c5))
+* **release:** the release scans the tree of the commit it publishes ([7d47a0b](https://github.com/ManotLuijiu/pi-harness-runtime/commit/7d47a0b5406480a1e1d3a52623a76aabd1e2d0ba))
+
 ### [1.1.459](https://github.com/ManotLuijiu/pi-harness-runtime/compare/v1.1.448...v1.1.459) (2026-10-28)
 
 

package/harness/pending-countdown.ts

@@ -0,0 +1,348 @@
+/**
+ * The live countdown of a pending question.
+ *
+ * The harness asks a human a question and waits. The wait has a deadline,
+ * and the countdown shows the remaining time in the status row of the TUI
+ * and starts the decision of the judge exactly at that deadline.
+ *
+ * The module owns the two policies of the wait:
+ *
+ * - the first countdown counts down to the deadline of the decision, which
+ *   is derived from the moment the wait started,
+ * - the recheck counts down to the next attempt, after the judge asked to
+ *   wait longer.
+ *
+ * The caller cannot pass a deadline of its own: the displayed deadline and
+ * the deadline the judge uses therefore cannot drift apart.
+ *
+ * The countdown is bound to one request. Every start replaces the previous
+ * binding and every stop releases the timer, so there is never more than
+ * one countdown and never a timer without a request.
+ */
+
+/** What the countdown counts to. */
+export type CountdownMode = "initial" | "recheck";
+
+/** The state of the countdown that is drawn in the status row. */
+export interface CountdownView {
+	/** The request the countdown belongs to. */
+	requestId: string;
+	/** The milliseconds that are left. Never negative. */
+	remainingMs: number;
+	/** The remaining time as "MM:SS". */
+	remaining: string;
+	/** What the countdown counts to. */
+	mode: CountdownMode;
+}
+
+/** The dependencies of a countdown. */
+export interface PendingCountdownDeps {
+	/** Draw the countdown in the status row. */
+	render: (view: CountdownView) => void;
+	/** The deadline was reached and the decision is due. */
+	onDeadline: (requestId: string) => void;
+	/**
+	 * Is the request still the pending one?
+	 *
+	 * A tick of a question that was answered or replaced in the meantime
+	 * must not redraw its status and must not trigger a decision.
+	 */
+	isPending: (requestId: string) => boolean;
+	/** A failing callback of the countdown is reported here. */
+	onError?: (error: unknown) => void;
+	/** The wait is over: the status row is cleared. */
+	onStop?: (requestId: string | null) => void;
+	/** The minutes the judge waits for a human answer. */
+	waitMinutes: number;
+	/** The milliseconds until the next attempt after the judge asked to wait. */
+	recheckIntervalMs: number;
+	/** The clock (the tests drive it). */
+	now?: () => number;
+	/** The timer that drives the ticks (the tests drive it). */
+	setInterval?: (callback: () => void, ms: number) => unknown;
+	/** The timer that stops the ticks (the tests drive it). */
+	clearInterval?: (handle: unknown) => void;
+	/** The tick interval in milliseconds. */
+	tickMs?: number;
+}
+
+/** The milliseconds between two ticks of the display. */
+const COUNTDOWN_TICK_MS = 1_000;
+
+/**
+ * The smallest tick interval.
+ *
+ * A shorter interval would repaint the status row faster than a reader can
+ * follow it and would waste the event loop of the harness.
+ */
+const MIN_TICK_MS = 100;
+
+/**
+ * The deadline of the decision.
+ *
+ * The deadline is derived from the moment the wait started, so the
+ * countdown and the judge share one timestamp.
+ */
+export function decisionDeadlineAt(startedAt: number, waitMinutes: number): number {
+	const minutes = Number.isFinite(waitMinutes) ? Math.max(0, waitMinutes) : 0;
+	const started = Number.isFinite(startedAt) ? startedAt : 0;
+	return started + minutes * 60_000;
+}
+
+/**
+ * The remaining time as "MM:SS".
+ *
+ * A time that is not a number is shown as an empty countdown: a status row
+ * must never claim a time that does not exist.
+ */
+export function formatRemainingTime(remainingMs: number): string {
+	const safeMs = Number.isFinite(remainingMs) ? Math.max(0, remainingMs) : 0;
+	const totalSeconds = Math.floor(safeMs / 1_000);
+	const minutes = Math.floor(totalSeconds / 60);
+	const seconds = totalSeconds % 60;
+	return `${String(minutes).padStart(2, "0")}:${String(seconds).padStart(2, "0")}`;
+}
+
+/** The binding of a running countdown. */
+interface CountdownBinding {
+	requestId: string;
+	deadlineAt: number;
+	mode: CountdownMode;
+}
+
+/**
+ * The countdown of one pending question.
+ *
+ * The countdown renders at once: the status row must show the remaining
+ * time without waiting for the first tick.
+ */
+export class PendingQuestionCountdown {
+	private readonly deps: PendingCountdownDeps;
+	private readonly now: () => number;
+	private readonly startTimer: (callback: () => void, ms: number) => unknown;
+	private readonly stopTimer: (handle: unknown) => void;
+	private readonly tickMs: number;
+	private handle: unknown = null;
+	private binding: CountdownBinding | null = null;
+	/**
+	 * Bumped on every start and every stop.
+	 *
+	 * A tick of an older generation belongs to a binding that is gone: it is
+	 * ignored instead of redrawing a status or triggering a decision.
+	 */
+	private generation = 0;
+	/**
+	 * True while the countdown owns the wait.
+	 *
+	 * The countdown stays engaged after its deadline fired, until the
+	 * decision path stops it or replaces it. The fallback poll uses this to
+	 * stay out of the way of the accurate timer.
+	 */
+	private engaged = false;
+	/**
+	 * True when the deadline fired and the decision did not start yet.
+	 *
+	 * The countdown owns the wait in that state, but it has no timer: the
+	 * caller arms it again when the decision did not start.
+	 */
+	private deadlineFired = false;
+
+	constructor(deps: PendingCountdownDeps) {
+		this.deps = deps;
+		this.now = deps.now ?? (() => Date.now());
+		this.startTimer =
+			deps.setInterval ??
+			((callback, ms) => setInterval(callback, ms) as unknown);
+		this.stopTimer =
+			deps.clearInterval ??
+			((handle) => clearInterval(handle as NodeJS.Timeout));
+		this.tickMs = Math.max(MIN_TICK_MS, deps.tickMs ?? COUNTDOWN_TICK_MS);
+	}
+
+	/** Does the countdown own the current wait? */
+	get active(): boolean {
+		return this.engaged;
+	}
+
+	/** Did the deadline fire and is the decision still due? */
+	get fired(): boolean {
+		return this.deadlineFired;
+	}
+
+	/** The request the countdown belongs to. */
+	get requestId(): string | null {
+		return this.binding?.requestId ?? null;
+	}
+
+	/** What the countdown counts to. */
+	get mode(): CountdownMode | null {
+		return this.binding?.mode ?? null;
+	}
+
+	/**
+	 * Start the countdown of a request, or replace the running one.
+	 *
+	 * The deadline of the decision is derived from the moment the wait
+	 * started: the caller passes that timestamp, the countdown computes the
+	 * deadline. The countdown and the judge therefore share one timestamp.
+	 */
+	start(requestId: string, startedAt: number): void {
+		this.begin(requestId, decisionDeadlineAt(startedAt, this.deps.waitMinutes), "initial");
+	}
+
+	/**
+	 * Start the countdown of the next attempt.
+	 *
+	 * The judge asked to wait longer: the countdown counts down to the next
+	 * attempt instead of to the deadline of the decision.
+	 */
+	startRecheck(requestId: string): void {
+		this.begin(requestId, this.now() + this.deps.recheckIntervalMs, "recheck");
+	}
+
+	/**
+	 * Stop the countdown and release its timer.
+	 *
+	 * Stopping is idempotent: a countdown that is not running can be stopped
+	 * as often as the cleanup paths need. The status row is cleared with it,
+	 * so a dead countdown never leaves a row that claims a decision is due.
+	 */
+	stop(): void {
+		const requestId = this.binding?.requestId ?? null;
+		this.engaged = false;
+		this.deadlineFired = false;
+		this.generation += 1;
+		this.clearTimer();
+		this.binding = null;
+		this.safeCall(() => this.deps.onStop?.(requestId));
+	}
+
+	/** Bind the countdown to a request and start its timer. */
+	private begin(requestId: string, deadlineAt: number, mode: CountdownMode): void {
+		this.clearTimer();
+		this.generation += 1;
+		const generation = this.generation;
+		this.binding = { requestId, deadlineAt, mode };
+		this.engaged = true;
+		this.deadlineFired = false;
+		try {
+			this.handle = this.startTimer(() => this.tick(generation), this.tickMs);
+		} catch (error) {
+			// The timer could not be created: the countdown owns nothing, so
+			// it must not claim the wait. The row of the countdown is
+			// cleared with it, so no row claims a decision that is not due.
+			this.engaged = false;
+			this.binding = null;
+			this.safeCall(() => this.deps.onStop?.(requestId));
+			this.report(error);
+			return;
+		}
+		this.tick(generation);
+	}
+
+	/**
+	 * One tick of the countdown.
+	 *
+	 * The tick is a no-op when it belongs to a binding that is gone, or
+	 * when the request it counts for is no longer the pending one.
+	 */
+	private tick(generation: number): void {
+		if (!this.engaged || generation !== this.generation) return;
+		const binding = this.binding;
+		if (!binding) return;
+
+		let remainingMs: number;
+		try {
+			if (!this.deps.isPending(binding.requestId)) {
+				// The question was answered or replaced: the countdown of
+				// that question is over.
+				this.stop();
+				return;
+			}
+			// The callback may have stopped the countdown: the binding of
+			// this tick is gone and must not be drawn any more.
+			if (!this.engaged || generation !== this.generation) return;
+			remainingMs = Math.max(0, binding.deadlineAt - this.now());
+		} catch (error) {
+			// A failing callback must never escape the timer: the countdown
+			// stops and the failure is reported.
+			this.stop();
+			this.report(error);
+			return;
+		}
+
+		if (remainingMs <= 0) {
+			// The deadline is reached. The timer stops, the countdown stays
+			// engaged until the decision path stops it or replaces it, so
+			// the fallback poll does not start a second decision.
+			this.clearTimer();
+			this.deadlineFired = true;
+			// The countdown reaches its zero before the decision starts.
+			this.safeRender({
+				requestId: binding.requestId,
+				remainingMs: 0,
+				remaining: formatRemainingTime(0),
+				mode: binding.mode,
+			});
+			// A failing decision handler must not leave a countdown that owns
+			// the wait without a timer: the countdown stops, so the fallback
+			// poll can take over.
+			try {
+				this.deps.onDeadline(binding.requestId);
+			} catch (error) {
+				this.stop();
+				this.report(error);
+			}
+			return;
+		}
+
+		this.safeRender({
+			requestId: binding.requestId,
+			remainingMs,
+			remaining: formatRemainingTime(remainingMs),
+			mode: binding.mode,
+		});
+	}
+
+	/** Draw the countdown, and report a failing status row. */
+	private safeRender(view: CountdownView): void {
+		try {
+			this.deps.render(view);
+		} catch (error) {
+			this.stop();
+			this.report(error);
+		}
+	}
+
+	/** Run a callback of the countdown without letting it escape. */
+	private safeCall(action: () => void): void {
+		try {
+			action();
+		} catch (error) {
+			this.report(error);
+		}
+	}
+
+	/** Report a failure without letting the report escape. */
+	private report(error: unknown): void {
+		try {
+			this.deps.onError?.(error);
+		} catch {
+			// The report of a failure must not become a new failure.
+		}
+	}
+
+	/** Release the timer of the countdown. */
+	private clearTimer(): void {
+		if (this.handle === null) return;
+		const handle = this.handle;
+		this.handle = null;
+		try {
+			this.stopTimer(handle);
+		} catch (error) {
+			// The timer is already released from the point of view of the
+			// countdown: the failure is reported, nothing is left behind.
+			this.report(error);
+		}
+	}
+}

package/harness/pending-wait.ts

@@ -0,0 +1,69 @@
+/**
+ * The end of a wait for a pending question.
+ *
+ * The countdown, the wait state and the pending question belong together:
+ * when one of them ends, the others end with it. A wait that outlives its
+ * question lets the judge decide about a question that belongs to a session
+ * that is gone - the fallback poll would ask about a question nobody can
+ * answer any more.
+ *
+ * The helper owns that release, so every way out of a wait ends the same
+ * way.
+ */
+
+/** The question that is waiting for an answer. */
+export interface PendingWaitQuestion {
+	requestId: string;
+	state: string;
+}
+
+/** The pieces of the harness that the release of a wait touches. */
+export interface PendingWaitOwner {
+	/** The question that is waiting for an answer, if there is one. */
+	currentQuestion(): PendingWaitQuestion | null | undefined;
+	/**
+	 * Close the question.
+	 *
+	 * Returns true when the question was closed. A question that is not
+	 * pending any more needs no closing.
+	 */
+	expireQuestion(requestId: string, reason: string): boolean;
+	/** Clear the wait state: the wait is over. */
+	clearWait(): void;
+	/** Stop the countdown of the wait and release its timer. */
+	stopCountdown(): void;
+	/** Clear the status row of the wait. */
+	clearStatus(): void;
+	/** Record the transition of the question. */
+	logTransition(requestId: string, outcome: string, reason: string): void;
+}
+
+/**
+ * End the wait for a pending question.
+ *
+ * The question is closed first, so nothing can decide about it any more,
+ * and the wait state follows. The reason names the way out, so the log of
+ * the transition says why the question was closed.
+ */
+export function endPendingWait(reason: string, owner: PendingWaitOwner): void {
+	// The countdown of the question is over with the wait: a tick of it
+	// must not draw a status and must not start a decision.
+	owner.stopCountdown();
+
+	// The question is closed explicitly, so the buttons of that request do
+	// not stay open and look like a request that is still waiting.
+	const question = owner.currentQuestion();
+	if (question && question.state === "pending") {
+		const expired = owner.expireQuestion(question.requestId, reason) === true;
+		owner.logTransition(
+			question.requestId,
+			expired ? "expired" : "closed",
+			reason,
+		);
+	}
+
+	// The wait state is over with the question: the judge is not asked
+	// about a question of a session that is gone.
+	owner.clearWait();
+	owner.clearStatus();
+}