@bridge4dev/runner 0.27.0 → 0.30.0

package/dist/supervisor.d.ts

@@ -39,6 +39,14 @@ export interface SupervisorOptions {
     verifyEnabled?: boolean;
     /** Test seam for the one-shot commit-message run. */
     proposeCommitMessage?: typeof proposeCommitMessage;
+    /**
+     * `[checkpoints] enabled` from the runner's own config (ticket #126), by the
+     * same rule as `[verify] enabled`: restore points are copies of the working
+     * tree kept on this machine, so the machine's owner has the last word on
+     * whether they are taken at all. `false` means the capability is not
+     * announced and no rewind can be started.
+     */
+    checkpointsEnabled?: boolean;
 }
 export declare class Supervisor {
     private readonly ws;
@@ -61,6 +69,17 @@ export declare class Supervisor {
     private readonly authRelay;
     /** Serialises repo-mutating git commands per workspace repo (QA-99 MAJOR-1). */
     private readonly repoLocks;
+    /**
+     * Repo keys with work in flight right now (ticket #126).
+     *
+     * A checkpoint deliberately does NOT take the repo lock — it only reads the
+     * worktree, and queueing a user's message behind a 150-second push would be
+     * a plain regression. What it does instead is decline to run while a
+     * mutating command holds the repo: a snapshot taken halfway through an apply
+     * would be a state that never existed, and offering to restore it is worse
+     * than having no restore point for that one message.
+     */
+    private readonly repoLockDepth;
     /** An update is installing right now — a second one would fight it. */
     private selfUpdateInFlight;
     /** Session 14: one project-recipe run per machine, and its verdict queue. */
@@ -198,6 +217,14 @@ export declare class Supervisor {
      * slot.
      */
     private isParkable;
+    /**
+     * Stop the agent process but keep the session resumable.
+     *
+     * `quiet` is for the callers that say it better themselves: a conversation
+     * rewind parks the session too, and announcing «the runner switched to
+     * another session» there is simply untrue — nothing switched, the user
+     * rewound (ticket #126).
+     */
     private park;
     private forwardEvent;
     /**
@@ -210,6 +237,16 @@ export declare class Supervisor {
      */
     private onQuestionAnswer;
     private onUserMessage;
+    /**
+     * Queue a message that no agent can take yet, and say so in the feed
+     * (ticket #125).
+     *
+     * Every queueing decision goes through here so the browser's idea of "this
+     * one can still be taken back" cannot drift from the runner's. Records with
+     * no seq — orphans, and anything written by a runner older than 0.28.0 —
+     * stay silent: they have no name the browser could quote back.
+     */
+    private queueMessage;
     /**
      * Run delivery work for one session, strictly after whatever is already
      * queued for it. Order is the whole point: two messages typed seconds apart
@@ -235,6 +272,39 @@ export declare class Supervisor {
      * the message is retired from disk only once an agent has it.
      */
     private deliverMessage;
+    /**
+     * Nothing could take the message: put it back where it came from.
+     *
+     * Records that were already held keep their identity (and their queued
+     * announcement); a first-time refusal mints one and announces it.
+     */
+    private requeue;
+    /**
+     * Where this session's conversation stands, live process or not (ticket #126).
+     *
+     * Reads the running agent when there is one and remembers what it said;
+     * falls back to that memory when there is not. The provider session id is
+     * checked on the way out rather than on the way in: an anchor minted before
+     * a fork is not wrong, it simply belongs to a conversation this session no
+     * longer has.
+     */
+    private currentAnchor;
+    /**
+     * Take a restore point in front of the work that is about to start
+     * (ticket #126).
+     *
+     * Called from the delivery chain — which is already asynchronous because of
+     * attachments — rather than from `deliverMessage`, which is synchronous and
+     * has five exits. Never throws and never blocks delivery: a message must
+     * reach the agent whether or not a restore point could be taken.
+     *
+     * Three reasons it declines, and each of them is a state in which a snapshot
+     * would be a lie rather than a restore point:
+     *  - the machine's owner switched checkpoints off;
+     *  - the agent is mid-turn, so the tree is being written to as we read it;
+     *  - a repo-mutating command holds the repository.
+     */
+    private captureCheckpoint;
     /**
      * Deliver messages that raced session start (already journaled).
      *
@@ -247,6 +317,10 @@ export declare class Supervisor {
     private interruptSession;
     /** Live model / interaction-mode switch (persisted for the next relaunch). */
     private applySettings;
+    /** Is a turn (or a question the agent is parked on) in flight right now? */
+    private isMidTurn;
+    /** The three live setters, in the order that lets an explicit pick win. */
+    private applyLiveSettings;
     private stopSession;
     private reconcile;
     /**
@@ -263,15 +337,31 @@ export declare class Supervisor {
      * mark the other session failed (QA-99 MAJOR-1).
      */
     private withRepoLock;
+    /** Is a repo-mutating command queued or running for this path right now? */
+    private isRepoLocked;
     /**
      * Same lock, keyed by the shared repository rather than by whichever path the
      * caller happened to have. A worktree commit and a workspace squash-merge
      * touch one repo, so they must take one key (see `repoKeyFor`).
      */
     private withRepoLockFor;
+    /**
+     * The live session this command names, or the sentence to refuse it with.
+     *
+     * A string return is deliberately unmistakable for a session: every caller
+     * has to branch on the type, so "I did not check" cannot compile.
+     */
+    private requireSession;
     /** A session actively mid-turn in this worktree — git writes must wait. */
     private isWorktreeBusy;
     private static readonly EVENT_PAYLOAD_CAP;
+    /**
+     * Journal an event, put it on the wire, and return it.
+     *
+     * The return value matters since ticket #125: the seq assigned here is the
+     * only name the browser and the runner share for one message, so the caller
+     * that echoes a user bubble has to be able to read it back.
+     */
     private sendEvent;
     private reportStatus;
     /** Graceful daemon shutdown: kill agents, keep sessions resumable server-side. */