@edgehero/pi-dispatch 4.3.1 → 5.0.0

package/src/held-replies.mjs

@@ -0,0 +1,325 @@
+/**
+ * Held replies (issue #638, DES-AWAIT-INPUT-ENDS-THE-JOB, INT-STEER-INBOX-CONTRACT): an answer to a run that is parking
+ * right now is never swallowed.
+ *
+ * THE GAP IT CLOSES. A run armed with `run.awaitInput` posts its question as a forge comment itself, and only then calls
+ * the tool and ends. The processor parks it (promotes the session with the `parked` mark, releases the run's semantic
+ * window, posts the fixed comment, sets the parked marker), and only from then on does a reply start a resumed job. A
+ * person can answer in the seconds before that, and such a reply met one of two walls: deduplicated against the run
+ * that still holds the window (the receiver answered `deduplicated` and nothing ran), or, on an issue without the
+ * phrase, dropped by the filter because the marker was not on the issue yet (`no-trigger-phrase`). Both are held here
+ * instead, and the run's park takes the first one as its resumed job (held-settle.mjs).
+ *
+ * ONE module for both sides, exported as `@edgehero/pi-dispatch/held-replies` the way steer-inbox.mjs is: the worker
+ * registers its awaitInput runs live and settles them (held-settle.mjs), the receiver finds a target's live runs and
+ * holds a reply under one. Light on purpose (no queue library, no processor), because the receiver imports it.
+ *
+ * KEYS OF THEIR OWN, NOT THE STEER INBOX. A held reply is not a steer: the run it waits on has stopped taking input (it
+ * asked and is ending), and the job it becomes is a new run, never a message written into this one. Sharing
+ * `run:steer:target:*` would put every awaitInput run in front of `trySteer`, which would push a phrase comment into an
+ * inbox nothing reads (an awaitInput run need not be steer-armed); writing a held reply into `run:inbox:*` would let
+ * the relay frame it as a steer for a run that is already gone. So the keys are spelled apart, and nothing that reads
+ * one set reads the other (runId is `runIdOf(job)`, spelled through `sanitizeJobId`):
+ *   run:await:target:<the same 32-hex hash steerTargetKey makes>  ZSET runId -> expiresAtMs, PEXPIRE 60 s
+ *   run:await:open:<runId>        STRING host name, PX 30 s: the one authority on whether a run takes a held reply
+ *   run:held:<runId>              LIST of entry JSON { id, at, route, fallback }, append only, PEXPIRE 1 h
+ *   run:held:closed:<runId>       STRING, set by the settle's close, PX 1 h
+ *   run:await:parked:<the same 32-hex hash>  STRING the run id, PX 60 s: set by the park's close, so a reply delivered
+ *                                 after the run left its target is still routed as a parked reply
+ * The target hash is the steer one's, derived from it (`awaitTargetKeyOf`), never spelled again: a key computed two
+ * ways is a key that one day differs, and then a reply is held under a target no run registered.
+ *
+ * THE HOLD AND THE CLOSE ARE EACH ONE LUA SCRIPT, the steer inbox's push and close pair for its reason: `holdReply`
+ * refuses `closed` once the close ran and `gone` once the run stopped refreshing, and `closeHeld` sets `closed`, drops
+ * the liveness keys and returns the list in one step. So a reply is either in the close's reply (and the settle answers
+ * it) or refused at the hold (and the receiver answers exactly as it did before this feature). There is no interleaving
+ * in which a reply is accepted and then never seen.
+ *
+ * BOUNDED. At most HELD_MAX_ENTRIES per run, enforced in the script so concurrent receivers cannot race past it (the
+ * oldest entry is evicted to make room), and HELD_ENTRY_MAX_BYTES per entry, checked before Valkey is touched: an entry
+ * over it is refused, never cut, and the receiver falls back to today's answer.
+ *
+ * NEVER THROWS. Every export returns a value or `{ error }`: a validation refusal is `{ error: "refused", reason }`, a
+ * Valkey fault `{ error: <code> }`, naming no key and no value.
+ */
+
+import { steerTargetOf } from "./inbox-relay.mjs";
+import { sanitizeJobId } from "./run-history.mjs";
+import { STEER_ID_RE } from "./steer-framing.mjs";
+
+const STEER_TARGET_PREFIX = "run:steer:target:";
+export const AWAIT_TARGET_PREFIX = "run:await:target:";
+/** The open key's life: the keeper refreshes it every 2 s, so 30 s of silence means the run is gone. */
+export const AWAIT_OPEN_TTL_MS = 30 * 1000;
+/** The target pointer's own expiry, twice a member's score horizon (steer-inbox.mjs's STEER_TARGET_TTL_MS rule). */
+export const AWAIT_TARGET_TTL_MS = 60 * 1000;
+/**
+ * The held list and the closed key live an hour, above the 10-minute semantic window (queue.mjs SEMANTIC_WINDOW_MS):
+ * a reply can be held only while that window could swallow it, so an hour outlives every case, and a crashed worker
+ * leaves no residue past it.
+ */
+export const HELD_TTL_MS = 60 * 60 * 1000;
+/** The most replies one run holds: the first is started, the rest are answered once, so more buys nothing. */
+export const HELD_MAX_ENTRIES = 20;
+/**
+ * The most one entry may weigh as JSON. The fallback job carries the comment and the issue's title and body (a forge
+ * caps each near 64 K characters, so up to four times that in UTF-8, and JSON escaping can double it), so 1 MiB fits
+ * any real delivery and still bounds a run at HELD_MAX_ENTRIES MiB.
+ */
+export const HELD_ENTRY_MAX_BYTES = 1024 * 1024;
+export const HELD_ROUTES = Object.freeze(["dedup", "pre-label"]);
+export const HELD_OUTCOMES = Object.freeze(["ok", "dup", "closed", "gone"]);
+/**
+ * How long a target says "a run just parked here" after the park's take closed its list (review round 2). A phrase-free
+ * reply posted just before the label went on can be DELIVERED after the take, when the run is already off its target, so
+ * the receiver finds no live run and the filter dropped it for the missing label: lost. While this marker stands the
+ * receiver enqueues such a reply as an ordinary parked reply instead (it then coalesces against the taken job, or
+ * resumes the parked session itself). A minute covers webhook delivery delay; after it the label is on, and the reply
+ * routes normally.
+ */
+export const AWAIT_PARKED_TTL_MS = 60 * 1000;
+export const AWAIT_PARKED_PREFIX = "run:await:parked:";
+
+const HOST_MAX = 255;
+const nowOf = (now) => (typeof now === "function" ? now() : now);
+const isMs = (n) => Number.isSafeInteger(n) && n >= 0;
+const validRunId = (runId) => (typeof runId === "string" && runId !== "") || (Number.isSafeInteger(runId) && runId >= 0);
+const codeOf = (error) => (typeof error?.code === "string" && error.code !== "" ? error.code : "valkey");
+const refused = (reason) => ({ error: "refused", reason });
+const isAwaitTarget = (k) => typeof k === "string" && k.startsWith(AWAIT_TARGET_PREFIX) && /^[0-9a-f]{32}$/.test(k.slice(AWAIT_TARGET_PREFIX.length));
+
+/**
+ * The await target pointer for a job (job data as queued, `kind` included), or null for a local or cron job, a job with
+ * no target number, or anything not plain. The steer target's hash with this module's prefix: derived, never spelled.
+ */
+export function awaitTargetKeyOf(job, { targetOf = steerTargetOf } = {}) {
+	try {
+		const { targetKey } = targetOf(job);
+		if (typeof targetKey !== "string" || !targetKey.startsWith(STEER_TARGET_PREFIX)) return null;
+		return `${AWAIT_TARGET_PREFIX}${targetKey.slice(STEER_TARGET_PREFIX.length)}`;
+	} catch {
+		return null;
+	}
+}
+
+export function awaitOpenKey(runId) {
+	return `run:await:open:${sanitizeJobId(runId)}`;
+}
+
+export function heldKeys(runId) {
+	const id = sanitizeJobId(runId);
+	return { list: `run:held:${id}`, closed: `run:held:closed:${id}` };
+}
+
+/**
+ * The entry as the list stores it, or `{ refusal }`. Only the contract's fields, in a FIXED order with `id` first, so
+ * the hold script can recognise a listed id by the JSON's prefix without parsing it in Lua. `fallback` is the job the
+ * receiver would have enqueued (receiver/src/steer.mjs `fallbackJobOf`): it holds the comment and the issue text, which
+ * is why this list is read by the settle alone and never shown on any surface.
+ */
+export function normalizeHeldEntry(entry, now = Date.now) {
+	if (!entry || typeof entry !== "object" || Array.isArray(entry)) return { refusal: "the held reply is not an object" };
+	if (typeof entry.id !== "string" || !STEER_ID_RE.test(entry.id)) return { refusal: "the held reply id is not 32 lowercase hex characters" };
+	if (!HELD_ROUTES.includes(entry.route)) return { refusal: `the route is not one of ${HELD_ROUTES.join(", ")}` };
+	const at = entry.at === undefined ? nowOf(now) : entry.at;
+	if (!isMs(at)) return { refusal: "the held reply time is not a millisecond timestamp" };
+	const fb = entry.fallback;
+	if (!fb || typeof fb !== "object" || Array.isArray(fb)) return { refusal: "the fallback job is not an object" };
+	const out = { id: entry.id, at, route: entry.route, fallback: fb };
+	let json;
+	try {
+		json = JSON.stringify(out);
+	} catch {
+		return { refusal: "the fallback job does not serialise" };
+	}
+	if (typeof json !== "string") return { refusal: "the fallback job does not serialise" };
+	const bytes = Buffer.byteLength(json, "utf8");
+	if (bytes > HELD_ENTRY_MAX_BYTES) return { refusal: `the held reply is ${bytes} bytes, above the ${HELD_ENTRY_MAX_BYTES}-byte limit` };
+	return { entry: out, json };
+}
+
+// closed FIRST: the close also deletes the open key, and "the run has settled" is the truer of the two answers. Then
+// gone, then dup (an entry whose JSON starts with this id's prefix: a redelivered webhook GUID is the same reply).
+// AT THE CAP THE OLDEST ENTRY GOES, never the new one (review round 2): the keeper registers a run for its whole pickup,
+// so on a busy issue a long run's list fills with comments made long before the agent asked anything, and refusing the
+// newest (`full`, the first version) refused exactly the one reply likely to be the answer. The oldest is the one the
+// take's lookback would drop anyway (held-settle.mjs HELD_LOOKBACK_MS).
+// KEYS: open, closed, list. ARGV: id prefix, entry JSON, max entries, ttl ms.
+const HOLD_SCRIPT = `if redis.call('EXISTS', KEYS[2]) == 1 then return 'closed' end
+if redis.call('EXISTS', KEYS[1]) == 0 then return 'gone' end
+local items = redis.call('LRANGE', KEYS[3], 0, -1)
+for i = 1, #items do
+	if string.sub(items[i], 1, #ARGV[1]) == ARGV[1] then return 'dup' end
+end
+redis.call('RPUSH', KEYS[3], ARGV[2])
+redis.call('LTRIM', KEYS[3], -tonumber(ARGV[3]), -1)
+redis.call('PEXPIRE', KEYS[3], ARGV[4])
+return 'ok'`;
+
+/**
+ * Hold one reply for a live run: "ok", "dup", "closed" or "gone", else `{ error }` (at the cap the oldest entry is evicted). Validated before Valkey is
+ * touched. `ok` and `dup` mean the run's settle will see it; every other answer means it will not, and the caller
+ * answers exactly as it did before held replies existed.
+ */
+export async function holdReply({ redis, runId, entry, now = Date.now } = {}) {
+	if (!validRunId(runId)) return refused("no run id");
+	const norm = normalizeHeldEntry(entry, now);
+	if (norm.refusal) return refused(norm.refusal);
+	const k = heldKeys(runId);
+	try {
+		const r = await redis.eval(HOLD_SCRIPT, 3, awaitOpenKey(runId), k.closed, k.list, `{"id":"${norm.entry.id}"`, norm.json, String(HELD_MAX_ENTRIES), String(HELD_TTL_MS));
+		return HELD_OUTCOMES.includes(r) ? r : { error: "bad-reply" };
+	} catch (error) {
+		return { error: codeOf(error) };
+	}
+}
+
+// The settle's close. KEYS: closed, open, list[, target]. ARGV: target member (the raw runId), ttl ms. `first` says
+// whether THIS call made the closing transition: a run settled twice (the processor, then BullMQ's failed listener for
+// the same thrown failure) gets the list back both times, and only the first may act on it (steer-inbox.mjs's rule).
+// KEYS[5], when present, is the target's parked marker, set in the same script as the close (the park's take only), so
+// there is no instant in which the run is off its target and the marker is not yet up. ARGV[3]: its ttl ms.
+const CLOSE_SCRIPT = `local first = 1 - redis.call('EXISTS', KEYS[1])
+redis.call('SET', KEYS[1], '1', 'PX', ARGV[2])
+redis.call('DEL', KEYS[2])
+if #KEYS >= 4 then redis.call('ZREM', KEYS[4], ARGV[1]) end
+if #KEYS >= 5 then redis.call('SET', KEYS[5], ARGV[1], 'PX', ARGV[3]) end
+redis.call('PEXPIRE', KEYS[3], ARGV[2])
+return {redis.call('LRANGE', KEYS[3], 0, -1), first}`;
+
+/** The parked marker of an await target (`run:await:parked:<the same hex32>`), or null for anything else. */
+export function awaitParkedKeyOf(targetKey) {
+	return isAwaitTarget(targetKey) ? `${AWAIT_PARKED_PREFIX}${targetKey.slice(AWAIT_TARGET_PREFIX.length)}` : null;
+}
+
+/** Whether a run parked on this await target within AWAIT_PARKED_TTL_MS: true, false, or `{ error }`. */
+export async function recentlyParked({ redis, targetKey } = {}) {
+	const key = awaitParkedKeyOf(targetKey);
+	if (key === null) return refused("the target key is not an await target key");
+	try {
+		return Number(await redis.exists(key)) === 1;
+	} catch (error) {
+		return { error: codeOf(error) };
+	}
+}
+
+/** LRANGE reply to entries; a line that does not parse as an entry is dropped, never surfaced as text. */
+function entriesOf(list) {
+	const out = [];
+	for (const line of Array.isArray(list) ? list : []) {
+		try {
+			const e = JSON.parse(line);
+			if (e && typeof e === "object" && typeof e.id === "string" && STEER_ID_RE.test(e.id) && HELD_ROUTES.includes(e.route) && e.fallback && typeof e.fallback === "object") out.push(e);
+		} catch {}
+	}
+	return out;
+}
+
+/**
+ * The close (the park's take, else the settle at a FINAL outcome): `{ entries, first }`, every reply the run ever held, in the order held.
+ * After it every hold is refused. `targetKey` is the run's await pointer, null for a run without one.
+ */
+export async function closeHeld({ redis, runId, targetKey = null, parked = false } = {}) {
+	if (!validRunId(runId)) return refused("no run id");
+	if (targetKey !== null && !isAwaitTarget(targetKey)) return refused("the target key is not an await target key");
+	const k = heldKeys(runId);
+	// `parked` (the park's take): also raise the target's parked marker, in the same script.
+	const keys = [k.closed, awaitOpenKey(runId), k.list, ...(targetKey ? [targetKey, ...(parked === true ? [awaitParkedKeyOf(targetKey)] : [])] : [])];
+	try {
+		const r = await redis.eval(CLOSE_SCRIPT, keys.length, ...keys, String(runId), String(HELD_TTL_MS), String(AWAIT_PARKED_TTL_MS));
+		if (!Array.isArray(r) || r.length !== 2) return { error: "bad-reply" };
+		return { entries: entriesOf(r[0]), first: Number(r[1]) === 1 };
+	} catch (error) {
+		return { error: codeOf(error) };
+	}
+}
+
+// KEYS: list, closed. Acts only while `closed` exists, so no reply held for the new run can be in what it deletes.
+const RESET_SCRIPT = `if redis.call('EXISTS', KEYS[2]) == 0 then return 0 end
+redis.call('DEL', KEYS[1], KEYS[2])
+return 1`;
+
+/**
+ * Reset a CLOSED held list for a new run under the same run id (a console retry keeps the job id): the previous run is
+ * settled and its replies answered, and while its `closed` stood every hold for the new run would be refused for an
+ * hour. Called by the keeper before it registers, the steer relay's `resetClosedInbox` rule. `{ reset }` or `{ error }`.
+ */
+export async function resetClosedHeld({ redis, runId } = {}) {
+	if (!validRunId(runId)) return refused("no run id");
+	const k = heldKeys(runId);
+	try {
+		return { reset: Number(await redis.eval(RESET_SCRIPT, 2, k.list, k.closed)) === 1 };
+	} catch (error) {
+		return { error: codeOf(error) };
+	}
+}
+
+/**
+ * Register a run as live on its await target, or refresh it (the keeper calls this every 2 s): ONE MULTI that sets the
+ * open key (PX 30 s), scores the run in the target's ZSET at `now + 30 s` (PEXPIRE 60 s, members already expired
+ * dropped) and keeps the held list's hour. `targetKey` null for a run no forge reply can reach: nothing to register,
+ * so `{ ok: true }` without a call. `{ ok: true }` or `{ error }`.
+ */
+export async function registerAwaitLive({ redis, runId, targetKey, host, now = Date.now } = {}) {
+	if (!validRunId(runId)) return refused("no run id");
+	if (targetKey === null || targetKey === undefined) return { ok: true };
+	if (!isAwaitTarget(targetKey)) return refused("the target key is not an await target key");
+	if (typeof host !== "string" || host === "" || host.length > HOST_MAX) return refused("the host name is missing or too long");
+	const t = nowOf(now);
+	if (!isMs(t)) return refused("now is not a millisecond timestamp");
+	try {
+		const res = await redis
+			.multi()
+			.set(awaitOpenKey(runId), host, "PX", AWAIT_OPEN_TTL_MS)
+			.zremrangebyscore(targetKey, "-inf", t)
+			.zadd(targetKey, t + AWAIT_OPEN_TTL_MS, String(runId))
+			.pexpire(targetKey, AWAIT_TARGET_TTL_MS)
+			.pexpire(heldKeys(runId).list, HELD_TTL_MS)
+			.exec();
+		if (!Array.isArray(res)) return { error: "bad-reply" };
+		const failed = res.find(([err]) => err);
+		if (failed) return { error: codeOf(failed[0]) };
+		return { ok: true };
+	} catch (error) {
+		return { error: codeOf(error) };
+	}
+}
+
+/** The keeper's 2 s refresh: the same writes as `registerAwaitLive`, named apart so a log line says which. */
+export function refreshAwaitLive(args) {
+	return registerAwaitLive(args);
+}
+
+/** Drop the run from its target and delete the open key, now. Not a close: the held list stays for the settle. */
+export async function unregisterAwaitLive({ redis, runId, targetKey = null } = {}) {
+	if (!validRunId(runId)) return refused("no run id");
+	if (targetKey !== null && !isAwaitTarget(targetKey)) return refused("the target key is not an await target key");
+	try {
+		const m = redis.multi().del(awaitOpenKey(runId));
+		if (targetKey) m.zrem(targetKey, String(runId));
+		const res = await m.exec();
+		if (!Array.isArray(res)) return { error: "bad-reply" };
+		const failed = res.find(([err]) => err);
+		if (failed) return { error: codeOf(failed[0]) };
+		return { ok: true };
+	} catch (error) {
+		return { error: codeOf(error) };
+	}
+}
+
+/**
+ * The awaitInput runs live on a target: at most `limit` runIds whose score is after `now`, else `{ error }`. A member
+ * whose keeper stopped refreshing is ignored the moment its score passes, whatever the ZSET's own TTL says.
+ */
+export async function liveAwaitRunsForTarget({ redis, targetKey, now = Date.now, limit = 4 } = {}) {
+	if (!isAwaitTarget(targetKey)) return refused("the target key is not an await target key");
+	const t = nowOf(now);
+	if (!isMs(t)) return refused("now is not a millisecond timestamp");
+	const n = Number.isSafeInteger(limit) && limit > 0 ? Math.min(limit, 64) : 4;
+	try {
+		const r = await redis.zrangebyscore(targetKey, `(${t}`, "+inf", "LIMIT", 0, n);
+		return Array.isArray(r) ? r.filter((m) => typeof m === "string" && m !== "") : { error: "bad-reply" };
+	} catch (error) {
+		return { error: codeOf(error) };
+	}
+}

package/src/held-settle.mjs

@@ -0,0 +1,266 @@
+import { isFinalOutcome } from "./inbox-settle.mjs";
+import { enqueueForgeJob, QUEUE } from "./queue.mjs";
+import { runIdOf } from "./recovery-queue.mjs";
+import { sanitizeJobId } from "./run-history.mjs";
+import * as heldModule from "./held-replies.mjs";
+
+/**
+ * The worker's side of held replies (issue #638, DES-AWAIT-INPUT-ENDS-THE-JOB; the keys and the scripts are
+ * held-replies.mjs's): a keeper that keeps an awaitInput run reachable while it runs, the take inside the park that
+ * turns what it held into at most one resumed job, and the final settle that drops what a run that did not park held.
+ *
+ * WHY THE WORKER AND NOT THE RECEIVER DECIDES. The receiver only knows that a reply met a run that is still going; it
+ * cannot know whether that run will park (the agent may finish, fail, or be cancelled after asking). The worker learns
+ * it in the park sequence, or at the run's final outcome, so that is where a held reply becomes a job or is dropped. Dropping is today's
+ * coalescing exactly: a reply that met a run which then did NOT park was always deduplicated against it, and still is.
+ */
+
+/** The keeper's refresh period, the steer relay's: 2 s against a 30 s open key. */
+export const AWAIT_KEEPER_POLL_MS = 2_000;
+
+/**
+ * How far back before the park a held reply may have been written and still be taken as the answer (issue #638 review,
+ * M1). The keeper registers the run for its whole pickup, so without a bound a phrase-free comment made ten minutes
+ * into a long run, before the agent had asked anything, would be taken as "the answer" to a question posted later.
+ * Five minutes covers the seconds between the agent's question and the park with a wide margin; an older entry is
+ * dropped silently, which is the coalescing it always got. Residual, named: a comment written in the last five minutes
+ * before the question and not meant as an answer is taken as one (the resumed agent reads it as a reply and may ask
+ * again).
+ */
+export const HELD_LOOKBACK_MS = 5 * 60 * 1000;
+
+/**
+ * The one comment the replies after the first get, however many there are (fixed words, no mention, no quote of any
+ * reply). The first reply is the answer the parked run resumes with; a run asks for one answer, and starting a second
+ * resumed job from the same parked session would race the first for it.
+ */
+export const HELD_EXTRA_REPLY = "This run was waiting for one answer and took the first reply it was given. If this comment adds to it, comment again once the run has replied.";
+
+/** The comment when the held answer could not be started (an enqueue that failed): the reply is answered, never lost silently. */
+export const HELD_RESUME_FAILED_REPLY = "This run was waiting for an answer and could not start from the reply it was given. Comment again to answer it.";
+
+const codeOf = (e) => (typeof e?.code === "string" && e.code !== "" ? e.code : typeof e?.error === "string" ? e.error : "error");
+const targetNumber = (t) => (typeof t?.number === "number" ? t.number : typeof t?.number === "string" && /^[1-9][0-9]{0,15}$/.test(t.number) ? Number(t.number) : null);
+
+/** Whether a processor result is a run that PARKED: the completed branch's `reason: "awaiting-input"` (processor.mjs). */
+export function isParkedOutcome(result) {
+	return result !== null && typeof result === "object" && result.outcome === "completed" && result.reason === "awaiting-input";
+}
+
+/**
+ * `makeAwaitKeeper({ redis, job, host, now, log, pollMs, held })` -> `{ start(), stop() }`: keeps an awaitInput run
+ * live on its await target for the whole pickup (registered at start, refreshed every `pollMs`), so a reply in the
+ * seconds between the agent's question and the park can be held. Started by the processor only for a job whose
+ * `data.awaitInput === true` and whose target a forge reply can reach; stopped by the park's take, else at the settle
+ * (index.mjs).
+ *
+ * STOP LEAVES THE KEYS TO EXPIRE rather than deleting them: the settle's close removes them at a final outcome, and an
+ * attempt that will be retried (an InfraRetry with attempts left) keeps taking a held reply for the open key's 30 s,
+ * after which the receiver answers as it always did. Never throws; faults are logged once per step, by code.
+ */
+export function makeAwaitKeeper({ redis, job, host, now = Date.now, log = () => {}, pollMs = AWAIT_KEEPER_POLL_MS, held = heldModule } = {}) {
+	const runId = runIdOf(job);
+	const targetKey = held.awaitTargetKeyOf(job?.data ?? null);
+	const jobId = sanitizeJobId(job?.id);
+	let timer = null;
+	let running = null;
+	let stopped = false;
+	const said = new Set();
+	const fault = (step, code) => {
+		if (said.has(step)) return;
+		said.add(step);
+		log("held_keeper_fault", { jobId, step, code });
+	};
+	const refresh = async (step) => {
+		try {
+			const r = await held.refreshAwaitLive({ redis, runId, targetKey, host, now });
+			if (r?.error) fault(step, codeOf(r));
+		} catch (e) {
+			fault(step, codeOf(e));
+		}
+	};
+	const tick = () => {
+		if (running || stopped) return running ?? Promise.resolve();
+		running = refresh("refresh").finally(() => {
+			running = null;
+		});
+		return running;
+	};
+	return {
+		targetKey,
+		async start() {
+			if (timer !== null || stopped || targetKey === null) return;
+			// A closed list under this run id belongs to a run that already settled (a console retry keeps the job id).
+			const reset = await held.resetClosedHeld({ redis, runId });
+			if (reset?.error) fault("reset", codeOf(reset));
+			await refresh("register");
+			if (stopped) return;
+			timer = setInterval(() => void tick(), pollMs);
+			timer.unref?.();
+		},
+		async stop() {
+			stopped = true;
+			if (timer !== null) clearInterval(timer);
+			timer = null;
+			try {
+				await running;
+			} catch {}
+		},
+	};
+}
+
+/**
+ * `makeHeldSettle({ redis, queues, comment, log, now, enqueue, held })` -> `settleHeld({ job, runId, result, error,
+ * queueName })`, with `settleHeld.take({ job, runId, queueName })`: what an awaitInput run's held replies become.
+ *
+ * THE TAKE, INSIDE THE PARK (issue #638 review, H1). The processor's parked branch calls `take` after it has set the
+ * marker and released the window and before its comment (processor.mjs, the park sequence). `closeHeld` first (one
+ * script: no reply can be held after it, and every reply held before it is in its reply); only the FIRST close acts:
+ *   - entries older than HELD_LOOKBACK_MS before now are dropped silently (`held_replies_dropped`, `stale`);
+ *   - the first recent entry whose fallback names this run's forge, repo, target type and number (it was held under
+ *     them; one that does not is skipped with `held_reply_mismatch` and the next is tried) is enqueued as the resumed job
+ *     WITH the semantic window (`enqueueForgeJob`), on the queue that ran the run (a host queue stays on its host). The
+ *     window is the point: the park released this run's window a moment before, so the taken reply now holds it, and
+ *     every later answer (a phrase-free reply the marker routes, a phrase reply) is coalesced against that one job
+ *     instead of starting a second resumed run from the same parked transcript. An add the window swallowed against
+ *     ANOTHER job (an answer that came in between the release and the take, which is then the run) is not taken;
+ *     against THIS run's own job (the release failed) it is not taken either, and is answered as not started;
+ *   - every other recent entry gets ONE fixed comment, HELD_EXTRA_REPLY; when nothing could be started at all, one
+ *     HELD_RESUME_FAILED_REPLY instead (also when the close itself failed: an answer may have been held and lost).
+ * The take's close also raises the target's parked marker. Returns `{ resumed, answered, dropped, taken }`; the
+ * processor posts HELD_TAKEN_COMMENT instead of the parked comment when `taken` is set ("here" or "other").
+ *
+ * THE SETTLE, AT THE FINAL OUTCOME (the inbox settle's three sites and `isFinalOutcome`), is the backstop. After a take
+ * the list is closed and it acts on nothing (`first: false`), and when the take's own close failed it only drops
+ * (`afterTake`). Otherwise: a parked outcome whose take never ran (an unwired seam) gets the take's logic; ANY other outcome drops every held reply, which is exactly the coalescing a reply
+ * into a still-running run always got. That includes an operator cancel acknowledged before the result: the record says
+ * the run was cancelled, not parked, so its held answers are dropped (review, L2).
+ *
+ * Logs, ids and counts only: `held_reply_resumed { jobId, runId, n, queue }`, `held_replies_dropped { runId, n,
+ * stale? }`, `held_reply_mismatch { runId }`, `held_reply_not_taken { runId, survivingJobId }`, `held_reply_resume_failed
+ * { runId, queue, code }`, `held_settle_failed { jobId, code }`. Never throws; the counts or null.
+ */
+export function makeHeldSettle({ redis, queues, comment = async () => {}, log = () => {}, now = Date.now, enqueue = enqueueForgeJob, held = heldModule } = {}) {
+	const queueFor = (name) => {
+		if (typeof name === "string" && name.startsWith(`${QUEUE}@`) && typeof queues?.host === "function") return { queue: queues.host(name), name };
+		return { queue: queues?.shared?.(), name: QUEUE };
+	};
+	const answer = async (job, text) => {
+		try {
+			await comment({ ...job.data, id: job.id }, text);
+		} catch {}
+	};
+	// The same forge, repo, target type and number, and (review round 2) the same flow and command: the held fallback was
+	// held under this run's target, and one that would run different work is no answer to this run's question.
+	const sameTarget = (fields, d) => !((fields?.kind !== undefined && fields.kind !== d.kind) || fields?.repo !== d.repo || typeof fields?.target?.type !== "string" || fields.target.type !== d.target?.type || targetNumber(fields.target) === null || targetNumber(fields.target) !== targetNumber(d.target) || fields.flow !== d.flow || fields.command !== d.command);
+	const close = async (job, runId, { parked = false } = {}) => {
+		const closed = await held.closeHeld({ redis, runId, targetKey: held.awaitTargetKeyOf(job.data), parked });
+		if (!closed || closed.error) {
+			log("held_settle_failed", { jobId: sanitizeJobId(job.id), code: codeOf(closed) });
+			return null;
+		}
+		return { entries: Array.isArray(closed.entries) ? closed.entries : [], first: closed.first === true };
+	};
+
+	// The take's body, on entries a first close returned.
+	const start = async ({ job, runId, entries, queueName }) => {
+		// `taken`: "here" when this take started the resumed job, "other" when the window showed another job already is
+		// the answer (one that got in between the release and the take), null otherwise. Either word means the run has
+		// its resumed job, so the processor says so and a late steer message must not start a second one (review round 2).
+		const counts = { resumed: 0, answered: 0, dropped: 0, taken: null };
+		if (entries.length === 0) return counts;
+		const rid = sanitizeJobId(runId);
+		const t = typeof now === "function" ? now() : now;
+		const recent = entries.filter((e) => Number.isSafeInteger(e?.at) && e.at >= t - HELD_LOOKBACK_MS);
+		const stale = entries.length - recent.length;
+		if (stale > 0) {
+			counts.dropped = stale;
+			log("held_replies_dropped", { runId: rid, n: stale, stale });
+		}
+		if (recent.length === 0) return counts;
+		const route = queueFor(queueName ?? job.queueName);
+		let takenAt = -1;
+		let failed = false;
+		let tried = false;
+		for (let i = 0; i < recent.length; i++) {
+			const fields = recent[i].fallback;
+			if (!sameTarget(fields, job.data)) {
+				log("held_reply_mismatch", { runId: rid });
+				continue;
+			}
+			tried = true;
+			try {
+				if (!route.queue) throw Object.assign(new Error("no queue"), { code: "no-queue" });
+				// The queue's enqueue timestamp is later than the receiver's trusted receipt. Keep that receipt
+				// outside the payload so a held answer does not acquire artificial human waiting time.
+				const r = await enqueue(route.queue, job.data.kind, { ...fields, replyReceivedAt: recent[i].at });
+				if (r?.deduplicated === true) {
+					// Swallowed by the window: another job holds it (an answer between the release and the take, which is
+					// then the resumed run), or this run's own (its release failed, so nothing was started).
+					log("held_reply_not_taken", { runId: rid, survivingJobId: sanitizeJobId(r.survivingJobId) });
+					// The run's own job id, or its run id for a #645 recovery whose original holds the window.
+					failed = r.survivingJobId === job.id || r.survivingJobId === runId;
+					if (!failed) counts.taken = "other";
+				} else {
+					takenAt = i;
+					counts.resumed = 1;
+					counts.taken = "here";
+					log("held_reply_resumed", { jobId: sanitizeJobId(r?.jobId), runId: rid, n: recent.length, queue: route.name });
+				}
+			} catch (e) {
+				log("held_reply_resume_failed", { runId: rid, queue: route.name, code: codeOf(e) });
+				failed = true;
+			}
+			break;
+		}
+		const rest = recent.length - (takenAt >= 0 ? 1 : 0);
+		if (rest > 0) {
+			// "Took the first reply" is true when one was taken here or by the job that holds the window; otherwise the
+			// replies were not started at all and say so.
+			await answer(job, takenAt >= 0 || (tried && !failed) ? HELD_EXTRA_REPLY : HELD_RESUME_FAILED_REPLY);
+			counts.answered = rest;
+		}
+		return counts;
+	};
+
+	// `afterTake`: the park's take ran for this outcome (the processor says so). A take whose close FAILED already told the
+	// person nothing was started (HELD_RESUME_FAILED_REPLY), so a backstop close that succeeds afterwards must not start a
+	// job anyway and contradict it (review round 2): after a take, the backstop only ever drops.
+	async function settleHeld({ job, runId = runIdOf(job), result = null, error = null, queueName = null, afterTake = false } = {}) {
+		try {
+			if (job?.data?.awaitInput !== true) return null;
+			if (!isFinalOutcome({ job, result, error })) return null;
+			if (runId === null || runId === undefined || runId === "") return null;
+			const closed = await close(job, runId);
+			if (closed === null) return null;
+			if (!closed.first || closed.entries.length === 0) return { resumed: 0, answered: 0, dropped: 0, taken: null };
+			if (isParkedOutcome(result) && afterTake !== true) return await start({ job, runId, entries: closed.entries, queueName });
+			log("held_replies_dropped", { runId: sanitizeJobId(runId), n: closed.entries.length });
+			return { resumed: 0, answered: 0, dropped: closed.entries.length, taken: null };
+		} catch (e) {
+			log("held_settle_failed", { jobId: sanitizeJobId(job?.id ?? ""), code: codeOf(e) });
+			return null;
+		}
+	}
+
+	settleHeld.take = async function takeHeld({ job, runId = runIdOf(job), queueName = null } = {}) {
+		try {
+			if (job?.data?.awaitInput !== true) return null;
+			if (runId === null || runId === undefined || runId === "") return null;
+			// `parked`: the close also raises the target's parked marker (held-replies.mjs), so a reply delivered after the run
+			// left its target is routed as a parked reply rather than dropped for the label it raced.
+			const closed = await close(job, runId, { parked: true });
+			if (closed === null) {
+				// L1: the close failed, so a reply may have been held and will never be seen: say so once.
+				await answer(job, HELD_RESUME_FAILED_REPLY);
+				return null;
+			}
+			if (!closed.first) return { resumed: 0, answered: 0, dropped: 0, taken: null };
+			return await start({ job, runId, entries: closed.entries, queueName });
+		} catch (e) {
+			log("held_settle_failed", { jobId: sanitizeJobId(job?.id ?? ""), code: codeOf(e) });
+			return null;
+		}
+	};
+	return settleHeld;
+}