@evandu/super-pi 0.1.146 → 0.1.147

package/dist/server/application/session-orchestrator-service.js

@@ -2,8 +2,20 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { capText } from "../workflow.js";
 import { assertSessionCwdInsideWorkspace } from "../session-cwd.js";
+import { SessionWatchdog } from "./session-watchdog.js";
+import { isLengthExceededError } from "../turn-failure.js";
+import { LENGTH_CONTINUATION_PROMPT } from "../length-continuation.js";
 export const SESSION_OUTPUT_CHAR_LIMIT = 64 * 1024;
 export const sessionResultRelativePath = (conversationId) => `.super-pi/session-results/${conversationId}.md`;
+/**
+ * HOW MANY TIMES A CHILD MAY BE TOLD TO CONTINUE AFTER ITS OUTPUT WAS TRUNCATED.
+ *
+ * The bound is not about tokens - it is about a model that truncates on EVERY response. Three
+ * continuations cover the ordinary case (a long answer split across a few responses) and stop the
+ * pathological one. Past the bound the child is reported as unfinished, which is a true sentence
+ * about what happened, instead of a loop that never ends.
+ */
+export const MAX_LENGTH_CONTINUATIONS = 3;
 /**
  * Orchestrator service coordinating sibling and child conversations.
  *
@@ -16,12 +28,76 @@ export class SessionOrchestratorService {
     runService;
     ledger;
     broadcaster;
-    constructor(store, conversationService, runService, ledger, broadcaster) {
+    watchdog;
+    /**
+     * HOW MANY TIMES EACH CHILD HAS BEEN TOLD TO CONTINUE AFTER A TRUNCATION.
+     *
+     * Per child rather than per dispatch, so a child that is given several tasks cannot extend itself
+     * indefinitely by being handed a new task each time it runs out of output budget. The entry is
+     * dropped as soon as the child finishes, so a child that continues successfully starts fresh on
+     * its next task.
+     */
+    lengthContinuations = new Map();
+    /**
+     * THE CHILDREN THAT HAVE ALREADY REPORTED THEIR OWN RESULT TO THEIR PARENT.
+     *
+     * A child can report explicitly - the `report` action - and that report is the child's own
+     * statement of what it did. When the child's turn then ends, the automatic completion report
+     * would deliver the same thing a second time, so the automatic path steps aside for a child that
+     * is in this set.
+     *
+     * The entry is added only by a TERMINAL report (`completed` / `failed`), because an interim
+     * update is not the child's final word: the task is still running, and the parent will want to
+     * hear how it ended.
+     */
+    reportedChildren = new Set();
+    constructor(store, conversationService, runService, ledger, broadcaster, watchdog) {
         this.store = store;
         this.conversationService = conversationService;
         this.runService = runService;
         this.ledger = ledger;
         this.broadcaster = broadcaster;
+        this.watchdog = watchdog ?? new SessionWatchdog({
+            onTimeout: async (event) => {
+                await this.handleWatchdogTimeout(event);
+            },
+            workspacePath: (workspaceId) => this.store.workspace(workspaceId)?.path,
+            workspaceIds: () => this.store.workspaces().map((w) => w.id),
+            isChildWorking: (childConversationId) => {
+                const conversation = this.store.conversation(childConversationId);
+                return conversation ? (conversation.status === "running" || conversation.status === "waiting") : false;
+            },
+            warn: (message) => console.warn(message),
+        });
+    }
+    /**
+     * The watchdog timer fired: the child has been silent for longer than the parent declared.
+     * Delivers a reminder message to the parent session. Does NOT interrupt or abort the child session.
+     */
+    async handleWatchdogTimeout(event) {
+        const { childConversationId, parentConversationId, timeoutSeconds, elapsedSeconds, childWorking } = event;
+        const conversation = this.store.conversation(childConversationId);
+        const workspace = conversation ? this.store.workspace(conversation.workspaceId) : undefined;
+        const statusText = childWorking ? "运行中" : "空闲";
+        const minutes = Math.max(1, Math.round(elapsedSeconds / 60));
+        const output = `[Watchdog 提醒] 子会话 ${childConversationId} 已经超过 ${elapsedSeconds} 秒（约 ${minutes} 分钟）未汇报。当前状态：${statusText}。如果需要，你可以主动查看子会话状态或打断其执行。`;
+        const resultPath = sessionResultRelativePath(childConversationId);
+        if (workspace) {
+            try {
+                const resultDirectory = join(workspace.path, ".super-pi", "session-results");
+                await mkdir(resultDirectory, { recursive: true });
+                await writeFile(join(resultDirectory, `${childConversationId}.md`), output, "utf8");
+            }
+            catch (error) {
+                console.warn(`Super Pi: writing watchdog result file failed for ${childConversationId}:`, error instanceof Error ? error.message : String(error));
+            }
+        }
+        await this.runService.enqueueSessionResult({
+            conversationId: childConversationId,
+            parentConversationId,
+            output,
+            resultPath,
+        });
     }
     /**
      * Spawns a new sibling conversation and immediately dispatches its initial task.
@@ -71,6 +147,16 @@ export class SessionOrchestratorService {
             task: options.task,
             status: "idle",
         });
+        // Arm silence watchdog if configured and session has a direct parent
+        const watchdogTimeout = options.watchdogTimeoutSeconds ?? options.watchdog_timeout_seconds ?? options.watchdogSeconds;
+        if (watchdogTimeout && watchdogTimeout > 0 && options.parentConversationId) {
+            await this.watchdog.arm({
+                childConversationId: conversationId,
+                parentConversationId: options.parentConversationId,
+                workspaceId,
+                timeoutSeconds: watchdogTimeout,
+            });
+        }
         // Immediately dispatch initial work
         const prompt = options.initialPrompt ?? options.task;
         if (prompt && prompt.trim()) {
@@ -106,17 +192,62 @@ export class SessionOrchestratorService {
                 failure = error;
                 await this.runService.waitForConversationIdle(conversationId);
             }
+            // A TRUNCATED ANSWER IS NOT A DEAD CHILD. The model filled its single-response output budget
+            // and stopped mid-sentence; everything it said is already on the child's transcript, and the
+            // work it was doing is NOT over. Treating that as a failure is what killed the child: the run
+            // service stamped the conversation `failed`, the orchestrator reported a failure to the
+            // parent, and a task that was one turn from done was thrown away.
+            //
+            // So a length stop is CONTINUED, not reported. The child is told to pick up where the output
+            // stopped, and it runs again. The bound is real: a model that truncates forever would
+            // otherwise loop until the watchdog gave up, and a task that cannot finish is better REPORTED
+            // as unfinished than retried until the server falls over.
+            //
+            // A CONTINUED CHILD IS NOT A FAILED ONE, SO THE FAILURE IS CLEARED. Everything below reads
+            // `failure` to decide what the parent is told and what the ledger records; a child that
+            // finished its answer has neither a failure to report nor a result to hand over - the parent
+            // reads the child's session, exactly as it does for a child that finished normally.
+            if (failure !== undefined && isLengthExceededError(failure)) {
+                const continued = await this.continueAfterLengthStop(conversationId, failure);
+                if (continued)
+                    failure = undefined;
+            }
+            // THE RESULT FILE IS ALWAYS WRITTEN, AND THE PARENT IS ALWAYS TOLD.
+            //
+            // The file is the child's product and the reader may open it. The report is a message to the
+            // parent, and it goes out WHETHER THE CHILD SUCCEEDED OR FAILED - because a parent that
+            // delegated a task has to be told how it went. A parent that heard nothing would wait forever,
+            // or would have to poll the child's session to find out, which is exactly what the automatic
+            // report exists to avoid.
+            //
+            // The envelope already tells the two apart: `state="completed"` with `<task_result>` for a
+            // child that finished, `state="error"` with `<task_error>` for one that broke. Reporting only
+            // the failures was a real defect - it left a parent that had successfully delegated a task
+            // staring at an empty transcript, and the child looking finished to everyone except the one
+            // person waiting for it.
             try {
                 const result = await this.persistSessionResult(conversationId, failure);
                 if (result) {
                     const current = this.store.conversation(conversationId);
-                    await this.runService.enqueueSessionResult({
-                        conversationId,
-                        parentConversationId: current?.parentConversationId,
-                        output: result.output,
-                        resultPath: result.resultPath,
-                        ...(failure !== undefined ? { error: result.output } : {}),
-                    });
+                    // AN INTERRUPTED CHILD HAS NO RESULT TO REPORT. "stopped" means somebody pressed stop, and
+                    // the half-finished answer that was on screen is not a result anybody stated. The parent is
+                    // told nothing, which is right: the child can be asked again, and then it reports.
+                    const interrupted = current?.status === "stopped";
+                    // A CHILD THAT REPORTED ITSELF IS NOT REPORTED TWICE. The explicit report is the child's
+                    // own statement of what it did, so the automatic completion steps aside for it.
+                    const alreadyReported = this.reportedChildren.has(conversationId);
+                    if (!interrupted && !alreadyReported) {
+                        await this.runService.enqueueSessionResult({
+                            conversationId,
+                            parentConversationId: current?.parentConversationId,
+                            output: result.output,
+                            resultPath: result.resultPath,
+                            // THE ERROR GOES ONLY WHEN THERE IS ONE. `enqueueSessionResult` reads the presence of
+                            // `error` as "this failed", so a successful report must NOT carry the key - carrying it
+                            // with the output would tell the parent the child failed.
+                            ...(failure !== undefined ? { error: result.output } : {}),
+                        });
+                    }
                 }
             }
             catch (error) {
@@ -136,11 +267,174 @@ export class SessionOrchestratorService {
             void completion.catch(() => undefined);
         return { conversationId };
     }
+    /**
+     * THE CHILD'S OUTPUT WAS CUT OFF. TELL IT TO CARRY ON, AND LET IT.
+     *
+     * This is the recovery for a length stop, and it exists because a truncated answer is not a
+     * finished one. The child has already said most of what it had to say - that text is on its
+     * transcript - so the work left to do is the tail of the answer, not the whole of it.
+     *
+     * WHY THE CONTINUATION IS A NEW TURN RATHER THAN A RESUME OF THE SAME ONE. Pi has already settled
+     * the turn that was truncated: the model stopped, the message was written, the run ended. There is
+     * no live turn to resume, so the only way to get more output is to ask again - and asking again in
+     * the SAME conversation is what makes the continuation work, because the child's own partial
+     * answer is in its context and the model can see exactly where it stopped.
+     *
+     * WHY IT IS AN AGENT-SENT ORDER RATHER THAN A USER MESSAGE. The person never typed this, and the
+     * child's transcript must not show words under their name that they never said - the same reason
+     * `dispatch` uses `enqueueAndRunAsAgent` in the first place.
+     *
+     * Returns true when the child was continued (and the caller must NOT report a failure), and false
+     * when the continuation could not be made or the bound was reached - in which case the caller
+     * reports the original failure, which is then the honest description of what happened.
+     */
+    async continueAfterLengthStop(conversationId, failure) {
+        if (!this.store.conversation(conversationId))
+            return false;
+        // THE LOOP, BECAUSE A CONTINUATION CAN BE TRUNCATED TOO. A long answer often needs more than
+        // one continuation: each response fills its own output budget, so a three-part answer runs out
+        // of room twice before it is done. The bound counts every continuation this child has been
+        // given, so the loop cannot run forever - a model that truncates on EVERY response reaches
+        // the bound and is reported as unfinished, which is the honest sentence about what happened.
+        for (;;) {
+            const used = this.lengthContinuations.get(conversationId) ?? 0;
+            if (used >= MAX_LENGTH_CONTINUATIONS) {
+                console.warn(`Super Pi: session ${conversationId} hit the output limit ${MAX_LENGTH_CONTINUATIONS} times; reporting it as unfinished.`);
+                this.lengthContinuations.delete(conversationId);
+                return false;
+            }
+            this.lengthContinuations.set(conversationId, used + 1);
+            const reason = failure instanceof Error ? failure.message : String(failure);
+            console.warn(`Super Pi: session ${conversationId} was truncated (${reason}); asking it to continue (${used + 1}/${MAX_LENGTH_CONTINUATIONS}).`);
+            let continuationFailure;
+            try {
+                // THE ORDER GOES IN AS A SYSTEM MESSAGE, AND THE RUN IS WAITED FOR. The child must be given
+                // the chance to finish before anything is reported to the parent - otherwise the parent would
+                // receive a result that is missing the tail the child was about to write.
+                await this.runService.enqueueAndRunAsAgent(conversationId, LENGTH_CONTINUATION_PROMPT);
+                await this.runService.waitForConversationIdle(conversationId);
+            }
+            catch (error) {
+                continuationFailure = error;
+            }
+            if (continuationFailure !== undefined) {
+                // A CONTINUATION THAT IS ITSELF TRUNCATED IS THE SAME SITUATION AGAIN, AND THE LOOP
+                // CONTINUES. It is only a different thing when the continuation failed for a reason that
+                // is NOT the output limit - a provider error, a refused tool - and those are the child's
+                // real failure, reported through the normal path below.
+                if (isLengthExceededError(continuationFailure)) {
+                    failure = continuationFailure;
+                    continue;
+                }
+                console.warn(`Super Pi: continuing session ${conversationId} failed:`, continuationFailure instanceof Error ? continuationFailure.message : String(continuationFailure));
+                this.lengthContinuations.delete(conversationId);
+                return false;
+            }
+            // THE CHILD SETTLED WITHOUT ANOTHER TRUNCATION. Its work is done: the answer on its transcript
+            // is now complete, and there is nothing to report to the parent - the parent reads the child's
+            // result from the session itself, exactly as it does for a child that finished normally.
+            //
+            // THE WARNING IS CLEARED HERE. It described the answer that was cut short, and the child has
+            // now finished that answer; leaving it up would tell the reader the answer is still truncated
+            // when it is not.
+            await this.store.setWarningReason(conversationId, undefined);
+            this.lengthContinuations.delete(conversationId);
+            this.ledger.update(conversationId, { status: "completed" });
+            return true;
+        }
+    }
+    /**
+     * Explicit report from a child session to its direct parent.
+     * Can be called multiple times at any point during execution.
+     */
+    async report(childConversationId, options) {
+        const conversation = this.store.conversation(childConversationId);
+        if (!conversation) {
+            throw new Error(`找不到会话：${childConversationId}`);
+        }
+        const parentConversationId = conversation.parentConversationId;
+        if (!parentConversationId) {
+            throw new Error(`会话 ${childConversationId} 没有直属父会话，无法汇报`);
+        }
+        const parent = this.store.conversation(parentConversationId);
+        if (!parent) {
+            throw new Error(`直属父会话 ${parentConversationId} 不存在`);
+        }
+        const content = options.content ?? "";
+        const status = options.status ?? "in_progress";
+        const failed = status === "failed";
+        const workspace = this.store.workspace(conversation.workspaceId);
+        const resultPath = sessionResultRelativePath(childConversationId);
+        if (workspace) {
+            const resultDirectory = join(workspace.path, ".super-pi", "session-results");
+            await mkdir(resultDirectory, { recursive: true });
+            await writeFile(join(resultDirectory, `${childConversationId}.md`), content, "utf8");
+        }
+        await this.runService.enqueueSessionResult({
+            conversationId: childConversationId,
+            parentConversationId,
+            output: content,
+            resultPath,
+            ...(failed ? { error: content } : {}),
+        });
+        // THE CHILD HAS NOW SPOKEN FOR ITSELF. The automatic report that fires when the child's turn
+        // ends would otherwise repeat what was just delivered - the parent would receive the same
+        // answer twice, once as the child's own report and once as the automatic completion.
+        //
+        // An EXPLICIT report is the child's own statement of what it did, so it is the better of the
+        // two and the automatic one steps aside. A report that is NOT terminal (an interim update)
+        // does not silence the automatic report: the child is still working, and the parent will want
+        // to hear how the task ended.
+        if (status === "completed" || status === "failed") {
+            this.reportedChildren.add(childConversationId);
+            await this.watchdog.cancel(childConversationId);
+        }
+        else {
+            await this.watchdog.noteSignal(childConversationId);
+        }
+        return { delivered: true, parentConversationId };
+    }
+    /**
+     * Sets or updates a silence watchdog timer on a child session.
+     */
+    async setWatchdog(options) {
+        const child = this.store.conversation(options.childConversationId);
+        if (!child) {
+            throw new Error(`找不到会话：${options.childConversationId}`);
+        }
+        await this.watchdog.arm({
+            childConversationId: options.childConversationId,
+            parentConversationId: options.parentConversationId,
+            workspaceId: child.workspaceId,
+            timeoutSeconds: options.timeoutSeconds,
+        });
+        return { ok: true, childConversationId: options.childConversationId, timeoutSeconds: options.timeoutSeconds };
+    }
+    /**
+     * Cancels a silence watchdog timer on a child session.
+     */
+    async cancelWatchdog(childConversationId) {
+        await this.watchdog.cancel(childConversationId);
+        return { ok: true };
+    }
+    /**
+     * Re-arms persisted watchdogs from disk.
+     */
+    async restoreWatchdogs() {
+        await this.watchdog.restore();
+    }
     async persistSessionResult(conversationId, failure) {
         const conversation = this.store.conversation(conversationId);
         const workspace = conversation ? this.store.workspace(conversation.workspaceId) : undefined;
         if (!conversation || !workspace)
             return undefined;
+        // THE FILE IS THE CHILD'S PRODUCT, AND THE REPORT USES IT. They used to be the same thing, and
+        // the split is what the user asked for:
+        //   - the FILE is written on every turn, so the reader can open it and `status(includeOutput)`
+        //     can return what the child actually produced;
+        //   - the REPORT to the parent carries that same text, because the parent is waiting for an
+        //     answer. A failure reports the DIAGNOSIS rather than whatever the model managed to say,
+        //     because a broken turn's last words are not a diagnosis of why it broke.
         const output = failure !== undefined
             ? (failure instanceof Error ? failure.message : String(failure))
             : ([...conversation.messages].reverse().find((message) => message.role === "assistant")?.content ?? "");
@@ -360,6 +654,7 @@ export class SessionOrchestratorService {
             mode = "all";
         }
         this.ledger.update(conversationId, { status: "stopped" });
+        await this.watchdog.cancel(conversationId);
         return { stopped: true, mode };
     }
     /**

package/dist/server/application/session-watchdog.d.ts

@@ -0,0 +1,159 @@
+/**
+ * THE WATCHDOG: A TIMER THAT SAYS "THE CHILD WENT QUIET".
+ *
+ * WHAT IT IS. A parent session declares, for one child session, how long it is willing to wait for a
+ * report before it wants to be told. When that silence runs out, the parent receives ONE message - a
+ * reminder - and the clock starts again. That is the whole contract.
+ *
+ * WHAT IT IS NOT. It has no power over the child. It does not stop the run, does not cancel a queue,
+ * does not send anything to the child. Interrupting is the PARENT's decision, and the parent has the
+ * tools for it (`session_stop`, `session_dispatch`). A watchdog that killed the run would take away the
+ * one judgement the user asked to keep: "父节点可以接受暂时不回报，然后让 watchdog 下一次再反馈".
+ *
+ * WHY THE REPORT ARRIVES AS A MESSAGE AND NOT AS AN EVENT. The parent is a conversation, and a
+ * conversation only knows something when a message says so. A watchdog that pushed a state change would
+ * leave the parent's model uninformed - it would keep waiting for a report that was never going to come,
+ * because the child had simply decided not to send one.
+ *
+ * WHY THE STATE IS ON DISK. The parent declared an expectation ("I want to hear from this child within
+ * five minutes"). An expectation that evaporates when the server restarts is worse than no watchdog at
+ * all: the parent believes it is being watched, and it is not. So the state lives in the workspace, next
+ * to the other `.super-pi/` artefacts, and the timers are re-armed when the server comes back.
+ */
+/** One watchdog: the parent that declared it, the child it watches, and the clock. */
+export interface WatchdogEntry {
+    /** The child session being watched. */
+    childConversationId: string;
+    /** The session the reminder is delivered to. */
+    parentConversationId: string;
+    /** The workspace whose `.super-pi/watchdogs.json` holds this entry. */
+    workspaceId: string;
+    /** How long a silence lasts before the parent is reminded. */
+    timeoutSeconds: number;
+    /** When the last sign of life was. A report moves it; the clock runs from here. */
+    lastSignalAt: number;
+    /** Whether the parent has ALREADY been told that the child is no longer working. */
+    endedReminded: boolean;
+}
+/** What the owner of a watchdog is told when the clock runs out. */
+export interface WatchdogTimeout {
+    childConversationId: string;
+    parentConversationId: string;
+    timeoutSeconds: number;
+    /** How long the silence actually was, in seconds. */
+    elapsedSeconds: number;
+    /** Whether the child still has work in flight when the clock ran out. */
+    childWorking: boolean;
+}
+/** The file name the state lives under, inside the workspace's `.super-pi` directory. */
+export declare const WATCHDOG_STATE_FILE = "watchdogs.json";
+/** The longest silence a parent may declare: a day. Beyond that it is not a watchdog, it is a plan. */
+export declare const WATCHDOG_MAX_TIMEOUT_SECONDS = 86400;
+/** The shortest silence a parent may declare. One second is a test's value, not a parent's. */
+export declare const WATCHDOG_MIN_TIMEOUT_SECONDS = 1;
+/**
+ * What the watchdog needs from the server it lives in.
+ *
+ * The watchdog knows NOTHING about sessions: it counts seconds and asks its owner to deliver a message.
+ * The owner is the session orchestrator, which is the only thing that knows how a message reaches a
+ * parent conversation.
+ */
+export interface WatchdogHost {
+    /** Delivers the reminder to the parent. */
+    onTimeout: (event: WatchdogTimeout) => Promise<void> | void;
+    /** The workspace directory a workspace's state file lives in. */
+    workspacePath: (workspaceId: string) => string | undefined;
+    /** Every workspace id the server knows about. */
+    workspaceIds: () => string[];
+    /** Whether the child still has work in flight: a live turn, or a queued message waiting for one. */
+    isChildWorking: (childConversationId: string) => boolean;
+    /** Where complaints go. */
+    warn?: (message: string) => void;
+}
+/**
+ * The watchdog manager: the timers, the state, and the state file.
+ *
+ * ONE WATCHDOG PER CHILD. The parent declares a duration for a child, and the duration belongs to that
+ * child - not to the pair of sessions in general - because "how long may this child be quiet" is a
+ * property of that child, and the parent may well declare different expectations for different children.
+ */
+export declare class SessionWatchdog {
+    private readonly host;
+    private readonly entries;
+    private readonly timers;
+    /** One write chain per workspace, so two watchdogs in one workspace cannot interleave a write. */
+    private readonly writes;
+    constructor(host: WatchdogHost);
+    /**
+     * Declares (or re-declares) the watchdog for a child.
+     *
+     * `timeoutSeconds` of 0 CANCELS the watchdog: "I am no longer waiting for a report from this one".
+     * That is the only way a parent takes the expectation back, and it is deliberately explicit - a
+     * watchdog that quietly switched itself off would leave the parent believing it was still watched.
+     */
+    arm(input: {
+        childConversationId: string;
+        parentConversationId: string;
+        workspaceId: string;
+        timeoutSeconds: number;
+    }): Promise<void>;
+    /**
+     * Records a sign of life: the child reported, so the clock starts again.
+     *
+     * A REPORT RESETS THE CLOCK, IT DOES NOT CANCEL THE WATCHDOG. The parent asked to hear from this
+     * child while the child was working; a report that says "the first stage is done, I am continuing"
+     * must not be read as "the work is over". Cancelling on the first report would turn the watchdog into
+     * a one-shot device, and the whole point of the parent's declaration is that it holds for as long as
+     * the child is out of sight.
+     */
+    noteSignal(childConversationId: string): Promise<void>;
+    /** Takes the watchdog away. The parent is no longer waiting. */
+    cancel(childConversationId: string): Promise<void>;
+    /** The watchdogs that are currently armed. */
+    list(): WatchdogEntry[];
+    /** The watchdog on one child, if there is one. */
+    get(childConversationId: string): WatchdogEntry | undefined;
+    /**
+     * Re-arms the watchdogs that were on disk when the server stopped.
+     *
+     * A watchdog whose silence had ALREADY run out while the server was down fires as soon as it comes
+     * back: the parent asked to be told after N minutes of silence, and the silence did happen. The
+     * remaining time is measured from the last sign of life, not from the restart.
+     */
+    restore(): Promise<void>;
+    /** Stops every timer. The process is going away; the state stays on disk. */
+    dispose(): void;
+    /**
+     * Arms the timer for one entry.
+     *
+     * THE TIMER IS UNREF'D. A pending reminder must not keep the Node process alive: the server is
+     * allowed to shut down with a watchdog in flight, and the state is on disk anyway.
+     */
+    private schedule;
+    private clearTimer;
+    /**
+     * The clock ran out.
+     *
+     * THE CHILD'S STATE DECIDES WHETHER THIS IS A REPEAT, AND THE REPEAT IS NOT LOUDER - IT IS THE
+     * SAME. Every interval the parent gets the same reminder, because the parent's need is the same:
+     * "I still have no news". An interval that grew would make the watchdog quietest exactly when the
+     * child has been silent longest, which is backwards.
+     *
+     * THE ONE EXCEPTION IS A CHILD THAT IS NO LONGER WORKING. A child whose turn ended without reporting
+     * is not going to report: the turn is over. The parent is told once that the child has gone quiet
+     * AND stopped, and the watchdog then takes itself off - a reminder that repeats for a child that
+     * cannot speak any more is noise, not information.
+     */
+    private fire;
+    /** The path of one workspace's state file, or undefined when the workspace is unknown. */
+    private statePath;
+    /**
+     * Writes one workspace's state file.
+     *
+     * THE WRITES ARE SERIALIZED PER WORKSPACE. Two watchdogs in one workspace each rewrite the same
+     * file, and an interleaved pair of writes would leave a file that describes one watchdog twice and
+     * loses the other.
+     */
+    private persist;
+    private writeStateFile;
+}