@hearsay-tools/squawk 0.0.0-stage → 0.17.0-dev.5682

package/dist/workflows/run/worker-orphans.js

@@ -0,0 +1,275 @@
+import { agentTmpDirLocationEvidence } from '../../runs/agent-tmpdir.js';
+import { processGroupAlive, processGroupOf, signalProcessGroup } from '../../core/session-process.js';
+import { noJitter, ORPHAN_BACKOFF, retryDelayMs } from '../../delegation/retry-backoff.js';
+import { inspectExecutionGeneration, isCurrentProcess, processesWithCwdUnder, processStartToken, recordedGroupSignalable, recordedProcessLive, sharedCwdScan } from '../../delegation/process-liveness.js';
+/** How long a non-gone orphan probe stands before the next scan. */
+const ORPHAN_PROBE_CACHE_MS = 2_000;
+export class WorkerOrphans {
+    context;
+    host;
+    orphanBackoff = ORPHAN_BACKOFF;
+    orphanTermGraceMs = 10_000;
+    constructor(context, host) {
+        this.context = context;
+        this.host = host;
+    }
+    forgetBlockers(runId) {
+        this.orphanBlockers.delete(runId);
+        this.reportedOrphanBlockers.delete(runId);
+    }
+    dispose() {
+        this.orphanDue.clear();
+        clearTimeout(this.orphanTimer);
+        this.orphanTimer = undefined;
+        this.orphanProbes.clear();
+        this.orphanBlockers.clear();
+        this.reportedOrphanBlockers.clear();
+    }
+    /** #469: the generation a dead controller left `starting`, if this manager may judge it. A
+     * generation this process controls is never judged here: the in-memory execution map owns it,
+     * and a disposed manager's still-running sessions look like orphans. `busy` is transient (this
+     * manager holds the run); `unknown` is a present record that proves nothing. */
+    orphanState(runId, admitting = false) {
+        const run = this.context.store.getRun(runId);
+        if (run?.delegation?.role !== 'worker' || this.context.disposed())
+            return { state: 'none' };
+        if (this.host.holds(runId, admitting))
+            return { state: 'busy' };
+        const proof = this.context.store.readWorkerExecution(runId);
+        if (proof?.phase !== 'starting')
+            return { state: 'none' };
+        const record = this.context.store.readWorkerProcesses(runId, proof.generation);
+        // A present record that proves nothing (unreadable, malformed, another generation) blocks both
+        // finalization and reaping; only an absent one is legacy, scan-only evidence.
+        if (record === 'unknown')
+            return { state: 'unknown' };
+        if (record !== 'absent' && isCurrentProcess(record.controller))
+            return { state: 'none' };
+        // Legacy execution proof also considers scratch holders; cleanup uses a separate strict proof.
+        const locations = agentTmpDirLocationEvidence(this.context.dataDir, runId);
+        return { state: 'orphan', generation: proof.generation, ...(record === 'absent' ? {} : { record }),
+            paths: [run.delegation.workspace.path, ...locations.paths], pathsComplete: locations.complete };
+    }
+    orphanedWorkerGeneration(runId, admitting = false) {
+        const orphan = this.orphanState(runId, admitting);
+        return orphan.state === 'orphan' ? orphan : undefined;
+    }
+    /** Settles a crashed generation after exit proof. Sync and signal-free; recovery, resume,
+     * delivery, collect and destroy then take their normal paths.
+     * A non-gone probe is cached briefly: on darwin the scan is a synchronous `lsof` on the event loop. */
+    settleOrphanedWorkerExecution(runId, opts = {}) {
+        const orphan = this.orphanedWorkerGeneration(runId, opts.admitting);
+        if (!orphan)
+            return false;
+        const cached = this.orphanProbes.get(runId);
+        if (!opts.fresh && cached?.generation === orphan.generation && Date.now() - cached.at < ORPHAN_PROBE_CACHE_MS)
+            return false;
+        const probe = inspectExecutionGeneration({ ...orphan, cwds: opts.cwds });
+        if (probe.liveness !== 'gone') {
+            this.orphanProbes.set(runId, { generation: orphan.generation, at: Date.now(), probe });
+            return false;
+        }
+        // A stale `alive` must not outlive a `gone` probe, even when the commit below fails.
+        this.orphanProbes.delete(runId);
+        try {
+            if (!this.context.store.commitWorkerExecutionComplete(runId, orphan.generation))
+                return false;
+        }
+        catch {
+            return false;
+        }
+        this.orphanProbes.delete(runId);
+        this.orphanBlockers.delete(runId);
+        this.reportedOrphanBlockers.delete(runId);
+        this.clearOrphanReprobe(runId);
+        this.context.store.appendEvent(runId, { type: 'lifecycle', message: "the interrupted worker's processes are gone; its execution was finalized" });
+        this.host.reapTerminalScratch(runId);
+        return true;
+    }
+    orphanProbes = new Map();
+    /** Pending orphan reprobes by run id. One timer serves them all (hearsay-tools/cezarion#879). */
+    orphanDue = new Map();
+    orphanTimer;
+    /** The `at` the timer was armed for; with the clock, it decides what a tick takes. */
+    orphanArmedFor = 0;
+    orphanBlockers = new Map();
+    reportedOrphanBlockers = new Map();
+    /** #469: a survivor that dies after recovery has no other wake source (no exit callback for a
+     * process another cezar spawned). Unref'd; finalization's `run` event then lets worker waits and
+     * outcomes observe it. Every 15 s for the first 15 minutes, then backing off to hourly
+     * (hearsay-tools/cezarion#879), so a long-lived survivor is still noticed when it exits. One
+     * timer serves every orphan, and a tick shares one `/proc` scan across them. A tick while this
+     * manager holds the run is skipped; only terminal reasons (proof settled, generation changed,
+     * run gone, unknown record, dispose) stop it. */
+    armOrphanReprobe(runId) {
+        const armed = this.orphanedWorkerGeneration(runId);
+        if (this.context.disposed() || this.orphanDue.has(runId) || !armed)
+            return;
+        this.orphanDue.set(runId, { generation: armed.generation, at: Date.now() + retryDelayMs(0, this.orphanBackoff, noJitter), attempts: 0 });
+        this.wakeOrphanReprobes();
+    }
+    wakeOrphanReprobes() {
+        clearTimeout(this.orphanTimer);
+        this.orphanTimer = undefined;
+        if (this.context.disposed() || !this.orphanDue.size)
+            return;
+        let next = Infinity;
+        for (const { at } of this.orphanDue.values())
+            next = Math.min(next, at);
+        this.orphanArmedFor = next;
+        this.orphanTimer = setTimeout(() => this.orphanReprobeTick(), Math.max(0, next - Date.now()));
+        this.orphanTimer.unref?.();
+    }
+    orphanReprobeTick() {
+        this.orphanTimer = undefined;
+        if (this.context.disposed())
+            return;
+        // Orphans due within 5 % of the fast cadence ride along, so near neighbours share the scan, and
+        // every orphan this tick keeps is re-armed from the same instant, so they stay together.
+        const now = Date.now();
+        const dueBy = Math.max(this.orphanArmedFor, now) + this.orphanBackoff.fastMs / 20;
+        const cwds = sharedCwdScan();
+        for (const [runId, pending] of [...this.orphanDue]) {
+            if (pending.at > dueBy)
+                continue;
+            this.orphanDue.delete(runId);
+            const orphan = this.orphanState(runId);
+            let attempts = pending.attempts;
+            if (orphan.state !== 'busy') {
+                // Ticks are seconds apart, so the brief probe cache would only skip them: probe fresh.
+                if (orphan.state !== 'orphan' || orphan.generation !== pending.generation ||
+                    this.host.settleOrphanedWorkerExecution(runId, { fresh: true, cwds }))
+                    continue;
+                attempts++;
+            }
+            this.orphanDue.set(runId, { ...pending, attempts, at: now + retryDelayMs(attempts, this.orphanBackoff, noJitter) });
+        }
+        this.wakeOrphanReprobes();
+    }
+    clearOrphanReprobe(runId) {
+        this.orphanDue.delete(runId);
+    }
+    /** Why the last destroy could not prove termination (#469), and whether that differs from the
+     * reason last reported, so a retry loop appends one lifecycle event per distinct blocker set. */
+    takeWorkerTerminationBlocker(runId) {
+        const blocker = this.orphanBlockers.get(runId);
+        if (!blocker)
+            return undefined;
+        const key = JSON.stringify(blocker);
+        const changed = this.reportedOrphanBlockers.get(runId) !== key;
+        this.reportedOrphanBlockers.set(runId, key);
+        return { blocker, changed };
+    }
+    /** Continue over a live orphan names what still runs; other refusals keep the generic text. */
+    orphanAdmissionRefusal(runId) {
+        const orphan = this.orphanedWorkerGeneration(runId, true);
+        const probe = orphan && this.orphanProbes.get(runId);
+        if (!probe || probe.generation !== orphan.generation)
+            return undefined;
+        if (probe.probe.controller !== undefined)
+            return `the worker is still controlled by a live cezar (pid ${probe.probe.controller})`;
+        const pid = probe.probe.pids[0];
+        return pid === undefined ? undefined : `a process of the previous execution is still running (pid ${pid})`;
+    }
+    /** Destroy only (#469): signal the recorded, token-verified survivors of a generation whose
+     * controller is proven dead, then finalize on `gone`. Scan-only processes are never signalled. */
+    async reapOrphanedWorker(runId, timeoutMs) {
+        const deadline = Date.now() + Math.min(30_000, Math.max(0, Number.isFinite(timeoutMs) ? timeoutMs : 0));
+        this.orphanBlockers.delete(runId);
+        const initial = this.orphanState(runId);
+        if (initial.state === 'unknown') {
+            this.orphanBlockers.set(runId, { kind: 'unreadable' });
+            return;
+        }
+        const orphan = this.orphanedWorkerGeneration(runId);
+        if (!orphan || this.host.settleOrphanedWorkerExecution(runId, { fresh: true }))
+            return;
+        const same = () => this.orphanedWorkerGeneration(runId)?.generation === orphan.generation;
+        // >= 500 ms: every probe may be a synchronous darwin `lsof`.
+        const pause = () => new Promise(resolve => setTimeout(resolve, Math.max(0, Math.min(500, deadline - Date.now()))));
+        // A live controller is another cezar's: nothing to signal or wait for. Otherwise signal only
+        // recorded, token-verified survivors and recorded session groups (none for a legacy
+        // record-less generation), then wait for readable cwd holders until the deadline.
+        if (!orphan.record || !recordedProcessLive(orphan.record.controller)) {
+            if (orphan.record) {
+                const { processes } = orphan.record;
+                await this.terminateRecorded({
+                    pids: processes.filter(entry => entry.pgid === undefined && entry.startToken !== undefined && recordedProcessLive(entry)),
+                    groups: processes.filter(entry => entry.pgid !== undefined),
+                    paths: orphan.paths,
+                }, deadline, pause, same);
+            }
+            while (!this.host.settleOrphanedWorkerExecution(runId, { fresh: true }) && Date.now() < deadline && same())
+                await pause();
+        }
+        if (!same())
+            return;
+        const probe = this.orphanProbes.get(runId)?.probe;
+        if (probe?.controller !== undefined)
+            this.orphanBlockers.set(runId, { kind: 'controller', pid: probe.controller });
+        else if (probe?.pids.length)
+            this.orphanBlockers.set(runId, { kind: 'processes', pids: probe.pids });
+    }
+    /** Destroy only: SIGTERM recorded survivors, then SIGKILL what outlives `orphanTermGraceMs`.
+     * `pids` are signalled by token-verified pid; `groups` are session leaders whose whole process
+     * group is signalled (hearsay-tools/cezarion#890), so what an agent left behind exits with it. A
+     * dead leader's group counts only while a process holding `paths` is in it. Every signal
+     * re-verifies first: a reused PID or group number is never touched. */
+    async terminateRecorded(targets, deadline, pause, current = () => true) {
+        const holders = processesWithCwdUnder(targets.paths);
+        const holderGroups = () => { return (holders === 'unknown' ? [] : holders).map(processGroupOf).filter((pgid) => pgid !== undefined); };
+        const groups = targets.groups.filter(entry => recordedGroupSignalable(entry, holderGroups()) && processGroupAlive(entry.pgid));
+        const living = () => targets.pids.some(recordedProcessLive) || groups.some(entry => processGroupAlive(entry.pgid));
+        const signal = (name) => {
+            for (const entry of targets.pids) {
+                if (!current())
+                    return;
+                if (processStartToken(entry.pid) === entry.startToken)
+                    try {
+                        process.kill(entry.pid, name);
+                    }
+                    catch { /* already gone */ }
+            }
+            const evidence = holderGroups();
+            for (const entry of groups) {
+                if (!current())
+                    return;
+                if (recordedGroupSignalable(entry, evidence))
+                    signalProcessGroup(entry.pgid, name);
+            }
+        };
+        if (!living())
+            return;
+        signal('SIGTERM');
+        const killAt = Math.min(deadline, Date.now() + this.orphanTermGraceMs);
+        while (Date.now() < killAt && living())
+            await pause();
+        if (living())
+            signal('SIGKILL');
+    }
+    /** Destroy of a finished generation (hearsay-tools/cezarion#890): a dev server or watcher its
+     * agent left in its process group holds the worktree, and nothing else ties it to the worker.
+     * A record whose controller is another live cezar is not ours to act on. */
+    async terminateFinishedWorkerGroups(runId, timeoutMs) {
+        const proof = this.context.store.readWorkerExecution(runId);
+        if (proof?.phase !== 'complete')
+            return;
+        const record = this.context.store.readWorkerProcesses(runId, proof.generation);
+        const run = this.context.store.getRun(runId);
+        if (typeof record === 'string' || run?.delegation?.role !== 'worker' ||
+            (recordedProcessLive(record.controller) && !isCurrentProcess(record.controller)))
+            return;
+        const groups = record.processes.filter(entry => entry.pgid !== undefined);
+        if (!groups.length)
+            return;
+        const deadline = Date.now() + Math.min(30_000, Math.max(0, Number.isFinite(timeoutMs) ? timeoutMs : 0));
+        const pause = () => new Promise(resolve => setTimeout(resolve, Math.max(0, Math.min(100, deadline - Date.now()))));
+        const paths = [run.delegation.workspace.path, ...agentTmpDirLocationEvidence(this.context.dataDir, runId).paths];
+        await this.terminateRecorded({ pids: [], groups, paths }, deadline, pause);
+    }
+}
+/** #469: admission refused because a process of the previous generation still runs. */
+export class WorkerOrphanAliveError extends Error {
+}
+export const admissionError = (error, fallback) => error instanceof WorkerOrphanAliveError ? error.message : fallback;
+//# sourceMappingURL=worker-orphans.js.map

package/dist/workflows/run/worker-orphans.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-orphans.js","sourceRoot":"","sources":["../../../src/workflows/run/worker-orphans.ts"],"names":[],"mappings":"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"}

package/dist/workflows/run/worker-questions.d.ts

@@ -0,0 +1,169 @@
+import type { RunModuleContext } from './types.ts';
+import type { ActiveRun } from '../active-run.ts';
+import type { RunRecord } from '../../runs/store.ts';
+import type { ConversationState } from '../../contract/index.js';
+import type { ConversationMessage } from '../../contract/index.js';
+import type { AgentInput } from '../../contract/index.js';
+import type { HumanWaitEntry, WaitVia } from '../../contract/index.js';
+import type { AskRequest } from '../../core/ask.ts';
+interface WorkerQuestionsHost {
+    active(id: string): ActiveRun | undefined;
+    deliverConversationInput(id: string): void;
+    chargeAutomaticWake(id: string): number;
+    countAutomaticWakes(id: string): number;
+    hasQueuedAgentInputs(id: string): boolean;
+    providerOwnsInboxInput(id: string, input: string): boolean;
+    reconcileWorkerWaits(id?: string): void;
+    openHumanAlias(id: string, state: ActiveRun | undefined, via: WaitVia, card?: AskRequest): HumanWaitEntry | undefined;
+    prepareHumanAsk(state: ActiveRun): void;
+    markHumanWaitSurfaced(id: string, wait: HumanWaitEntry, card?: AskRequest): void;
+    withdrawCezarHumanWaits(id: string): void;
+    routeWorkerQuestion(id: string): void;
+    noticeParkedWorker(id: string): void;
+    retireUnreadParentQuestion(id: string, request: string): void;
+    deleteUnreadInput(id: string, input: string): void;
+    updatePendingHumanAsk(id: string, value: boolean): void;
+}
+type HumanAnswerBudget = {
+    spent: number;
+};
+/** Who answers a worker's pending question: its parent, or Cezar when a live parent cannot take it
+ *  (hearsay-tools/cezarion#2410). Never a human. */
+export type QuestionAnswerSource = 'parent' | 'cezar';
+/** Why a worker's question closed unanswered (hearsay-tools/cezarion#2410). */
+export type QuestionCloseReason = 'parent-stopped' | 'worker-stopped' | 'undeliverable';
+/** The undelivered input that answers a worker's pending question, and who sent it. */
+export interface QuestionAnswer {
+    askSeq: number;
+    input: AgentInput;
+    source: QuestionAnswerSource;
+}
+/** A worker's second turn end with no wait or done asks its parent, as a routed open question
+ *  (hearsay-tools/cezarion#1301). */
+export declare const WORKER_FALLBACK_QUESTION: (workerId: string) => string;
+export declare const WORKER_FALLBACK_HEADER = "Worker idle";
+export declare class WorkerQuestions {
+    private readonly context;
+    private readonly host;
+    private readonly maxAutoContinues;
+    constructor(context: RunModuleContext, host: WorkerQuestionsHost, maxAutoContinues: number);
+    /** A worker's pending question goes to its owning parent as a conversation request (#505). The
+     * worker still parks on its ask; only the parent's reply answers it. A question with no live
+     * parent, or a worker that stopped, closes; one a live parent cannot take gets Cezar's answer
+     * with the reason (hearsay-tools/cezarion#2410). Routing is idempotent: the message ID derives
+     * from the ask seq. */
+    routeWorkerQuestion(workerId: string): void;
+    /** A routed question whose parent record can no longer be read gets Cezar's answer. A reply the
+     *  parent sent before goes first, so the worker takes one answer. A reply a live inbox claim still
+     *  holds stays, and Cezar does not answer beside it: the next pass after it is taken does. A failed
+     *  write leaves this for the next pass too. */
+    private answerForUnreadableParent;
+    /** The ID of Cezar's answer to a worker question that could not reach its parent: one per ask, so
+     *  a restart that routes again finds it instead of answering twice. */
+    undeliveredAnswerId(workerId: string, askSeq: number): string;
+    /** Cezar's answer to this ask, when one was queued (hearsay-tools/cezarion#2410). */
+    private undeliveredAnswer;
+    /**
+     * A live parent cannot take the worker's question (hearsay-tools/cezarion#2410): Cezar answers it
+     * with the reason through the answer seam a parent's reply uses, so the worker decides what to do
+     * next and no human card holds it. The answer is queued with its automatic-wake charge, so a
+     * worker that asks again cannot loop past the budget. Cezar's own "Worker idle" question, a spent
+     * budget or a queue that refuses the answer closes the question instead, and the worker parks.
+     */
+    answerUndelivered(workerId: string, askSeq: number, reason: string): void;
+    /** The answers queued for the worker's pending question that it has not taken: the parent's
+     *  replies to the routed question, and Cezar's answer when it was not delivered. */
+    private queuedAnswerIds;
+    /** The transcript shows the question as not delivered once, after the answer that settles it is queued. */
+    private recordUndelivered;
+    /** The worker's pending question closes unanswered (hearsay-tools/cezarion#2410), and Cezar's own
+     *  human wait for it goes. Idempotent: a question that already closed is left alone. */
+    closeQuestion(workerId: string, askSeq: number, reason: QuestionCloseReason, detail?: string): void;
+    /**
+     * A worker parked before finishing while its parent waits on it tells the parent why
+     * (hearsay-tools/cezarion#1327): Cezar posts a progress message from the worker, which wakes the
+     * parent and closes no wait. A parked question needs none, since the question itself goes to the
+     * parent. At most one notice per parent wait (`parkNoticeId`), and none when the turn that
+     * parked already messaged the parent, Cezar's own notice included. The message and the parent's
+     * input commit together; a crash before that commit leaves the recovery sweep to post it.
+     */
+    noticeParkedWorker(workerId: string): void;
+    /** A worker parked before finishing: waiting, not stopping or complete, with no pending question
+     *  and no queued input. */
+    parkedBeforeFinishing(worker: RunRecord): boolean;
+    /** The ledger and the parent's inbox keep room as `service.send` counts it, beside open
+     *  questions' replies. When either is full, the worker's log says so once per wait. */
+    parkNoticeAtCapacity(workerId: string, waitId: string, root: RunRecord, state: ConversationState): boolean;
+    /** Recovery's pass over family members: a question (#505) or a park notice
+     *  (hearsay-tools/cezarion#1327) that a crash caught before or after its commit to the parent
+     *  still reaches it. The worker waits settle between the two, so a notice selects only a wait
+     *  that is still open. */
+    recoverWorkerMessages(families: readonly RunRecord[], familyRootId: string | undefined): void;
+    /** `noticeParkedWorker` for every worker a family's root owns. */
+    noticeParkedWorkers(rootId: string): void;
+    /** The worker's pending ask when it went to the parent (a legacy human fallback excluded). */
+    routedAsk(runId: string): {
+        askSeq: number;
+        message: ConversationMessage;
+    } | undefined;
+    /** The one reader of what answers a worker's pending question (hearsay-tools/cezarion#2410):
+     *  waking, delivering, reopening and recording an answer all read it here. */
+    pendingAnswer(runId: string): QuestionAnswer | undefined;
+    /** Who sent `input` as the answer to the worker's pending question; undefined when it is no answer. */
+    answerSource(runId: string, input: AgentInput): QuestionAnswerSource | undefined;
+    /** The worker's pending question belongs to its parent or to Cezar: no human answers it. The
+     *  worker's own routing marker decides, so a parent ledger that cannot be read hides nothing. */
+    answeredElsewhere(runId: string): boolean;
+    /** A routed question settled without a reply can never be answered by the parent any more: it
+     * closes (hearsay-tools/cezarion#2410). A question its worker stopped on, or a reply a stopped
+     * worker never took, closes as `worker-stopped`; one the parent's end settled closes as
+     * `parent-stopped`. A superseded fallback question closes through `supersedeWorkerFallback`. */
+    retireSettledQuestions(parentId: string): void;
+    /** Why a routed question with this outcome closes, or undefined while it still stands: a reply
+     *  waiting for a live worker answers it, one a stopped worker never took does not. */
+    private settledQuestionClose;
+    /** Routed questions this parent has not answered yet, by asking worker. */
+    unansweredQuestions(parentId: string): {
+        workerId: string;
+        messageId: string;
+    }[];
+    /** The parent settled (hearsay-tools/cezarion#2410): every open question of its workers closes
+     * with it, never moving to a human. The request outcome lands first, so a crash before the
+     * worker's close repeats this, and the close finds nothing left to do. */
+    closeRoutedQuestions(parentId: string): void;
+    /** The parent can still read a message from its worker. */
+    parentTakesMessages(parent: RunRecord): boolean;
+    /**
+     * A worker that ended a second turn with no wait or done after its no-wait nudge
+     * (hearsay-tools/cezarion#1301): Cezar's `no-wait` human wait carries one open question, raised
+     * as `ask.requested` so `routeWorkerQuestion` takes it to the parent as a request. The parent's
+     * reply resumes the worker through the answer seam, charged to the worker's budget; a parent that
+     * cannot take it closes it (hearsay-tools/cezarion#2410), and the worker parks. A full wait list
+     * opens none and the worker parks as before.
+     */
+    askParentForWorker(runId: string, state: ActiveRun, stepId: string | undefined): void;
+    /** The worker's pending question is the one `askParentForWorker` raised. */
+    isWorkerFallbackAsk(runId: string, askSeq: number): boolean;
+    /** The worker's pending question is Cezar's fallback question. */
+    pendingWorkerFallback(runId: string): boolean;
+    /** The parent's reply to a worker's fallback question resumed it: one automatic wake, so a
+     *  parent and worker cannot go back and forth past the budget (hearsay-tools/cezarion#1301). */
+    chargeWorkerFallbackReply(runId: string, beforeHumanReset?: HumanAnswerBudget): void;
+    /**
+     * Cezar's fallback question is Cezar's, not the worker's (hearsay-tools/cezarion#1301): what the
+     * plain park it replaced let through still goes through. A parent's input, a Continue or a closed
+     * session supersedes it: its routed request gets an outcome, so it no longer holds the parent's
+     * done, the parent's unread copy is retired, and only then does the question close unanswered
+     * (`human-ask-closed`, `superseded`) and Cezar's wait go. Each step is idempotent and the close
+     * comes last, so a failed write leaves the question pending and the next supersession, or
+     * recovery, finishes it. A question the worker asked itself is never superseded. True when it
+     * closed.
+     */
+    supersedeWorkerFallback(runId: string): boolean;
+    /** An input its run no longer owes: the parent's copy of a superseded fallback question, or a
+     *  worker's queued answer to a question that closed. One it has not read is retired, so neither a
+     *  wake nor a restart's replay of unread input delivers it. One a provider or an inbox read
+     *  already holds is left to them. */
+    retireUnreadParentQuestion(parentId: string, requestId: string): void;
+}
+export {};