@bridge4dev/runner 0.52.0 → 0.54.0

package/dist/supervisor.d.ts

@@ -4,6 +4,7 @@ import { selfUpdate, type SelfUpdateOutcome } from './self-update.js';
 import { installAgent } from './agent-install.js';
 import { pruneNativeClaudeVersions } from './agent-cleanup.js';
 import { type AgentVersionsMeasurement } from './agent-versions.js';
+import { type HostLoadFrame } from './host-load.js';
 import type { RunnerWsClient } from './ws-client.js';
 import type { SessionDescriptor } from './protocol.js';
 import type { AgentAdapter } from './adapters/types.js';
@@ -122,6 +123,29 @@ export interface SupervisorOptions {
      * in production.
      */
     stopSettleMs?: number;
+    /**
+     * Test seam for the host-load measurement (§5.3).
+     *
+     * A seam because the real one reads THIS machine's `/proc`, and a test that
+     * had to arrange the kernel into «load 12.4, swap 98 % used» would not be
+     * written — so the rule this frame exists for (send only what moved) would
+     * go unverified on the one machine shape that matters.
+     */
+    readHostLoad?: () => HostLoadFrame | null;
+    /**
+     * How often `/proc` is sampled, in ms — a test seam over
+     * `HOST_LOAD_SAMPLE_INTERVAL_MS`, for the same reason `agentCleanupMs`
+     * exists: the real cadence is 30 s and this suite runs on real timers (fake
+     * ones fire the WS client's liveness watchdog and kill the socket). Never
+     * set in production.
+     */
+    hostLoadSampleMs?: number;
+    /**
+     * The heartbeat window, in ms — a test seam over `HOST_LOAD_HEARTBEAT_MS`.
+     * The real one is five minutes; without this seam «an unchanged machine
+     * still reports» would be an untested promise. Never set in production.
+     */
+    hostLoadHeartbeatMs?: number;
 }
 export declare class Supervisor {
     private readonly ws;
@@ -346,6 +370,39 @@ export declare class Supervisor {
      * it had room. Both were caught by the independent QA review of this change.
      */
     private publishSlots;
+    /** The heartbeat window actually used — the constant, or a test's own. */
+    private readonly hostLoadHeartbeatMs;
+    private readonly hostLoadTimer;
+    /** The last measurement the API actually took from us, or `null` for «nothing yet». */
+    private lastPublishedHostLoad;
+    /** When that frame went out, by this machine's clock. `0` = never. */
+    private lastHostLoadSentAt;
+    /**
+     * Tell the API what this machine's load looks like — when it is worth telling.
+     *
+     * Three ways a frame goes out, and each covers a hole the others leave:
+     *
+     *  - the value MOVED past a threshold (`hostLoadChangedEnough`) — the reason
+     *    the frame exists, and the only one that makes the card timely;
+     *  - the heartbeat came due — an idle machine still has to say «still here,
+     *    still idle», because the API expires the measurement after two minutes
+     *    and silence would otherwise turn «nothing is happening» into «we have no
+     *    idea» on a perfectly healthy card;
+     *  - nothing was ever sent on this connection (`hello_ack` clears the memory)
+     *    — a fresh socket knows nothing about what the last one was told.
+     *
+     * `null` from the sampler is a complete answer: not Linux, `/proc` masked, a
+     * kernel too old for `MemAvailable`. Nothing is sent and nothing is logged —
+     * a machine that cannot measure itself leaves the card saying «no data»,
+     * which is exactly what is true.
+     *
+     * Recorded ONLY when the socket took it, same as `publishSlots`: a frame
+     * dropped by a dead socket must not be remembered as sent, or a machine whose
+     * load never moves again would go silent until the heartbeat — and on a
+     * reconnect the API would have no measurement at all while this side believed
+     * it had one.
+     */
+    private publishHostLoad;
     private onFrame;
     private startSession;
     /**
@@ -359,6 +416,26 @@ export declare class Supervisor {
      * would be a lock bought for nothing.
      */
     private prepareWorkspace;
+    /**
+     * The working folder could not be built — say so in the feed, pin the fork
+     * point, and let the session go (#360).
+     *
+     * Both doors into `prepareWorkspace` end here. Three things happen in an
+     * order that is not free:
+     *
+     *  1. **The fork point is recorded first.** `git.ts` resolves it before it
+     *     writes anything, precisely so that a failure still knows it. Without it
+     *     the API keeps `base_sha = null` for the session's whole life, and
+     *     «Continue» can never prove the leftover branch is the empty one this
+     *     session created — which is the trap the ticket is about.
+     *  2. **The feed event goes out before the map entry is dropped**, because
+     *     `sendEvent` needs it. Until now neither door sent one: a failed start
+     *     was visible only as an `errorMessage` on the session row, and pressing
+     *     «Continue» wipes that.
+     *  3. **Then the status, then the entry.** A FAILED session is over, and a
+     *     leftover entry would hold one of the runner's few slots.
+     */
+    private workspacePrepareFailed;
     /**
      * Spin the adapter up — for a fresh session, a resume-on-next-message, or a
      * free CHAT session with no prompt at all (the agent boots, reports its
@@ -526,7 +603,8 @@ export declare class Supervisor {
     /**
      * Make room for one more agent process.
      *
-     * Up to `maxSessions` agents run side by side, each in its own worktree. Over
+     * Up to `maxSessions` agents run side by side — since session 16 most of them
+     * share the project folder rather than each having a worktree of its own. Over
      * that, idle-but-resumable sessions (REVIEW / WAITING_INPUT) are parked —
      * their provider session survives on disk and relaunches on the next message,
      * so parking costs context nothing. Only mid-turn sessions (RUNNING /
@@ -754,10 +832,35 @@ export declare class Supervisor {
      * 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;
+     *  - THIS session is mid-turn, so its own tree is being written as we read it;
      *  - a repo-mutating command holds the repository.
+     *
+     * «A neighbour in the same folder is working» used to be a fourth reason, and
+     * it was the wrong one (#310): in DIRECT mode the folder is shared by design,
+     * so that rule silently switched restore points off for everybody the moment
+     * a second session opened. The neighbours are recorded on the point instead —
+     * the conversation can always be rewound to it, the files cannot.
+     *
+     * Every refusal is now audible. A restore point that was never taken is
+     * invisible until the day somebody reaches for it, and «the button is not
+     * there» is not a sentence anybody can act on.
      */
     private captureCheckpoint;
+    /**
+     * Say something once per BUSY PERIOD, not once per message (#310).
+     *
+     * A folder held by a neighbour stays held for minutes, and a session mid-turn
+     * can be sent three follow-up notes inside one answer. Keying this on the
+     * message seq would have counted each of those as its own turn and said the
+     * same sentence three times — the noise the frequency policy exists to
+     * prevent. The set is cleared when the session next comes to rest
+     * (`reportStatus`), which is exactly when the reason stops being true.
+     *
+     * A SET of keys, not the last one said: two different reasons can both come
+     * up inside one period, and remembering only the most recent would let them
+     * take turns re-announcing each other.
+     */
+    private noticeOncePerTurn;
     /**
      * Deliver messages that raced session start (already journaled).
      *
@@ -887,7 +990,15 @@ export declare class Supervisor {
     private stopWorkUnderPause;
     /** 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? */
+    /**
+     * Is a turn (or a question the agent is parked on) in flight right now?
+     *
+     * The same status list as `holdsTheTree` plus one term: an open question
+     * parks the session without any of those statuses, and a live settings change
+     * must not land under it. Reading the shared array rather than spelling the
+     * statuses out again is the whole point of Р8 — a fourth waiting status has
+     * to arrive in one place, not four.
+     */
     private isMidTurn;
     /** The three live setters, in the order that lets an explicit pick win. */
     private applyLiveSettings;
@@ -976,8 +1087,50 @@ export declare class Supervisor {
      * has to branch on the type, so "I did not check" cannot compile.
      */
     private requireSession;
+    /**
+     * The statuses in which a session is holding its working tree (#310).
+     *
+     * One array, read by all three predicates below. There used to be one
+     * literal, then two would have been needed, and a third would have been
+     * written the day somebody added a waiting state — which is how «the agent
+     * is busy» and «the folder is busy» come to disagree about what busy means.
+     * (`rewindActionsLive` in the dashboard is a fourth reader and a deliberate
+     * mirror: the runner does not depend on `@devbridge/shared`.)
+     */
+    private static readonly MID_TURN_STATUSES;
+    /**
+     * Is a stop still in flight over this session's live process?
+     *
+     * Three terms, written out in three places before this: an open cycle, that
+     * cycle owning the process that is running NOW, and the cycle not yet
+     * settled. #373 is what makes it load-bearing — the resting status is
+     * published before the process dies, so this is the difference between «the
+     * session is quiet» and «the session is still writing files».
+     */
+    private static stopInFlight;
+    private static holdsTheTree;
     /** A session actively mid-turn in this worktree — git writes must wait. */
     private isWorktreeBusy;
+    /**
+     * Is THIS session mid-turn? (#310)
+     *
+     * The question `isWorktreeBusy` was answering in three places where the right
+     * question was this one. They are the same question only when a folder holds
+     * exactly one session — and DIRECT mode, the default since session 16, is
+     * precisely the arrangement in which it holds several. A restore point is a
+     * snapshot of this session's own conversation; a neighbour typing in the same
+     * folder is a reason to MARK it, not to refuse to take it.
+     */
+    private isSessionMidTurn;
+    /**
+     * Everybody else who is working in this folder right now (#310).
+     *
+     * Includes a neighbour whose stop is still running: after #373 the resting
+     * status is published BEFORE the process is actually gone, so a session that
+     * reports IDLE while its stop cycle still owns a live process is still
+     * writing files. Reading `lastReported` alone would call that folder quiet.
+     */
+    private busyNeighbours;
     private static readonly EVENT_PAYLOAD_CAP;
     /**
      * Journal an event, put it on the wire, and return it.