@bridge4dev/runner 0.52.0 → 0.54.0

package/dist/supervisor.js

@@ -8,7 +8,7 @@ import { classifyFailure, isRepeatOfSameFailure, MAX_RETRIES_PER_SESSION, retryD
 import { evaluateRecipeCommand, maskSecrets, maskString } from './policy.js';
 import { agentPromptSizeLabel, inspectAgentPrompt, quotePath, readAgentPrompt, } from './agent-prompt.js';
 import { JournalStore } from './journal.js';
-import { deleteSessionBranch, ensurePreviewWorktree, ensureSessionWorktree, prepareDirectWorkspace, previewWorktreePath, removePreviewWorktree, removeSessionWorktree, repoKeyFor, sessionWorktreePath, validateWorkspacePath, } from './git.js';
+import { deleteSessionBranch, ensurePreviewWorktree, ensureSessionWorktree, prepareDirectWorkspace, previewWorktreePath, removePreviewWorktree, removeSessionWorktree, repoKeyFor, sessionWorktreePath, validateWorkspacePath, WorktreePrepareError, } from './git.js';
 import { readRecipeProposal } from './recipe.js';
 import { RECIPE_STEP_NAMES, parseProjectRecipe } from './recipe-schema.js';
 import { proposeCommitMessage } from './commit-message.js';
@@ -25,8 +25,9 @@ import { pruneNativeClaudeVersions } from './agent-cleanup.js';
 import { agentByDbValue } from './agent-registry.js';
 import { invalidateAgentVersions, measureAgentVersions, } from './agent-versions.js';
 import { rememberWorkspacePath } from './environment.js';
+import { hostLoadChangedEnough, hostLoadHeartbeatDue, readHostLoad, HOST_LOAD_HEARTBEAT_MS, HOST_LOAD_SAMPLE_INTERVAL_MS, } from './host-load.js';
 import { composeMessageWithAttachments, saveAttachments, } from './attachments.js';
-import { applyRewind, createCheckpoint, dropCheckpoints, listCheckpoints, previewRewind, pruneCheckpoints, } from './checkpoints.js';
+import { applyRewind, createCheckpoint, dropCheckpoints, listCheckpoints, MAX_BUSY_SESSIONS, previewRewind, pruneCheckpoints, } from './checkpoints.js';
 import { DeliverMessageArgsSchema, QuestionAnswerArgsSchema } from './protocol.js';
 import { availableModes, MODE_REFUSED_TEXT } from './adapters/types.js';
 /** Refusals shared by every checkpoint command (ticket #126). */
@@ -209,6 +210,21 @@ export class Supervisor {
         this.agentCleanupFirstTimer.unref?.();
         this.agentCleanupTimer = setInterval(() => this.sweepOldAgentVersions(), cleanupEvery);
         this.agentCleanupTimer.unref?.();
+        /**
+         * The machine's own load, sampled on a timer for the reason the seat report
+         * is: nothing on this side is an EVENT. Load is not something the runner
+         * does, it is something that happens to it — a `pnpm build` a person
+         * started over ssh, a neighbour container, this machine's own three agents
+         * — and there is no call site to hook. A tick that re-reads the truth is
+         * the only shape that cannot be forgotten.
+         *
+         * Nearly free, and quiet by default: two small files are read, and
+         * `publishHostLoad` returns without touching the socket unless the number
+         * actually moved (or the heartbeat came due).
+         */
+        this.hostLoadHeartbeatMs = opts.hostLoadHeartbeatMs ?? HOST_LOAD_HEARTBEAT_MS;
+        this.hostLoadTimer = setInterval(() => this.publishHostLoad(), opts.hostLoadSampleMs ?? HOST_LOAD_SAMPLE_INTERVAL_MS);
+        this.hostLoadTimer.unref?.();
     }
     /** How often the agent versions are re-derived. See the constructor. */
     static AGENT_VERSIONS_INTERVAL_MS = 60 * 60 * 1_000;
@@ -572,6 +588,53 @@ export class Supervisor {
             this.lastPublishedSlots = fingerprint;
         }
     }
+    /** The heartbeat window actually used — the constant, or a test's own. */
+    hostLoadHeartbeatMs;
+    hostLoadTimer;
+    /** The last measurement the API actually took from us, or `null` for «nothing yet». */
+    lastPublishedHostLoad = null;
+    /** When that frame went out, by this machine's clock. `0` = never. */
+    lastHostLoadSentAt = 0;
+    /**
+     * 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.
+     */
+    publishHostLoad() {
+        const sample = (this.opts.readHostLoad ?? readHostLoad)();
+        if (!sample)
+            return;
+        const now = Date.now();
+        const sinceLastSent = now - this.lastHostLoadSentAt;
+        // A backwards clock step is «due», not «early» — see `hostLoadHeartbeatDue`.
+        const heartbeatDue = hostLoadHeartbeatDue(sinceLastSent, this.hostLoadHeartbeatMs);
+        if (!heartbeatDue && !hostLoadChangedEnough(this.lastPublishedHostLoad, sample))
+            return;
+        if (this.ws.send({ type: 'host_load', ...sample })) {
+            this.lastPublishedHostLoad = sample;
+            this.lastHostLoadSentAt = now;
+        }
+    }
     async onFrame(frame) {
         switch (frame.type) {
             case 'hello_ack':
@@ -580,9 +643,17 @@ export class Supervisor {
                 // because it is only true while the socket is. Forget what we told the
                 // old one so the first tick after this reconnect actually sends.
                 this.lastPublishedSlots = '';
+                // Same rule for the load: the API keeps the measurement in Redis beside
+                // the socket, with a TTL shorter than our heartbeat, so a machine that
+                // has just come back has no load on its card at all. Forget what the
+                // last connection was told and say it again immediately — a card that
+                // is right only after five minutes of silence is not right.
+                this.lastPublishedHostLoad = null;
+                this.lastHostLoadSentAt = 0;
                 this.setMaxSessions(frame.maxSessions);
                 await this.reconcile(frame.sessions);
                 this.publishSlots();
+                this.publishHostLoad();
                 // A build that finished while the socket was down has its verdict
                 // sitting on disk. This is the moment it can be delivered.
                 this.flushVerifyReports();
@@ -839,10 +910,7 @@ export class Supervisor {
                 running.baseBranch = prepared.baseBranch;
         }
         catch (error) {
-            this.reportStatus(descriptor.id, 'FAILED', {
-                errorMessage: `Failed to prepare git worktree: ${maskSecretText(error)}`,
-            });
-            this.sessions.delete(descriptor.id);
+            this.workspacePrepareFailed(running, error, 'Failed to prepare git worktree');
             return;
         }
         // A session that is already past STARTING (re-sent because this runner
@@ -922,6 +990,50 @@ export class Supervisor {
             ...(descriptor.branchPlan ? { plan: descriptor.branchPlan } : {}),
         }));
     }
+    /**
+     * 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.
+     */
+    workspacePrepareFailed(running, error, prefix) {
+        const { descriptor } = running;
+        if (error instanceof WorktreePrepareError) {
+            if (error.baseSha && !running.baseSha)
+                running.baseSha = error.baseSha;
+            if (error.baseBranch && !running.baseBranch)
+                running.baseBranch = error.baseBranch;
+        }
+        const message = maskSecretText(error);
+        log.error('supervisor: the working folder could not be prepared', {
+            sessionId: descriptor.id,
+            workMode: descriptor.workMode ?? 'BRANCH',
+            code: error instanceof WorktreePrepareError ? error.code : 'unknown',
+            error: message,
+        });
+        this.sendEvent(running, 'error', {
+            message,
+            // Not an enum on either side (`RunnerEventPayloadSchema` is a record, and
+            // the dashboard carries whatever code it is given), so this stays a plain
+            // string and a new one costs nobody a deployment.
+            code: error instanceof WorktreePrepareError ? error.code : 'worktree_prepare_failed',
+        });
+        this.reportStatus(descriptor.id, 'FAILED', { errorMessage: `${prefix}: ${message}` });
+        this.sessions.delete(descriptor.id);
+    }
     /**
      * 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
@@ -1040,6 +1152,10 @@ export class Supervisor {
                 // (`resolveGitPolicy` gives both the restrictive reading), and passing it
                 // unconditionally keeps one code path instead of two.
                 gitPolicy: gitPolicyOf(descriptor),
+                // #361 п. 5: whether this session shares its folder with everybody else.
+                // Rides down for the same reason as `gitPolicy` — it lands in
+                // `PolicyContext` and it decides one line of the system prompt.
+                ...(descriptor.workMode ? { workMode: descriptor.workMode } : {}),
                 mode: running.mode,
                 ...(running.model ? { model: running.model } : {}),
                 ...(running.effort ? { effort: running.effort } : {}),
@@ -1726,7 +1842,8 @@ export 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 /
@@ -3106,17 +3223,42 @@ export 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.
      */
     async captureCheckpoint(running, kind, messageSeq) {
         const worktreePath = running.worktreePath;
-        if (!worktreePath || this.opts.checkpointsEnabled === false)
+        if (!worktreePath)
+            return;
+        if (this.opts.checkpointsEnabled === false) {
+            // Once per session: this is a machine-wide setting, not an event.
+            if (!running.checkpointsOffSaid) {
+                running.checkpointsOffSaid = true;
+                this.sendEvent(running, 'notice', {
+                    level: 'info',
+                    text: 'Restore points are switched off on this dev server, so this session cannot be rewound. A server administrator turns them back on.',
+                });
+            }
             return;
-        if (kind === 'TURN' && this.isWorktreeBusy(worktreePath))
+        }
+        if (kind === 'TURN' && this.isSessionMidTurn(running)) {
+            this.noticeOncePerTurn(running, 'checkpoint-self-busy', 'No restore point was taken for this step: this session was still answering when it was due.');
             return;
-        if (await this.isRepoLocked(worktreePath))
+        }
+        if (await this.isRepoLocked(worktreePath)) {
+            this.noticeOncePerTurn(running, 'checkpoint-repo-locked', 'No restore point was taken for this step: another git command holds this repository. It will be taken on the next one.');
             return;
+        }
         // The anchor and the conversation it names travel TOGETHER: a point
         // recorded against an older provider session stays usable, because the
         // rewind resumes the session the point names rather than whichever one the
@@ -3128,6 +3270,10 @@ export class Supervisor {
             kind,
             ...(messageSeq === undefined ? {} : { messageSeq }),
             ...(anchor ? { agentAnchor: anchor.anchor, agentSession: anchor.agentSession } : {}),
+            // A getter, not a value: taking the snapshot is not instantaneous, and
+            // «who was working while it was taken» is a question about the whole of
+            // that interval (#310).
+            busySessions: () => this.busyNeighbours(running),
         });
         if (this.isStale(running))
             return;
@@ -3140,6 +3286,16 @@ export class Supervisor {
                     text: 'This working tree is too large to take a restore point — rewind is unavailable for this step. Check that build output is in .gitignore.',
                 });
             }
+            else {
+                // Not a repository, or git refused: every time, because unlike the two
+                // conditions above this one does not clear itself.
+                this.sendEvent(running, 'notice', {
+                    level: 'warn',
+                    text: result.reason === 'not-a-repo'
+                        ? 'No restore point could be taken: this folder is not a git repository, so there is nothing to rewind to.'
+                        : 'No restore point could be taken for this step, so it cannot be rewound. The session itself is unaffected.',
+                });
+            }
             return;
         }
         this.sendEvent(running, 'checkpoint', {
@@ -3150,8 +3306,36 @@ export class Supervisor {
             canRewindContext: Boolean(result.record.agentAnchor),
             ...(messageSeq === undefined ? {} : { messageSeq }),
             ...(result.skippedFiles.length ? { skippedFiles: result.skippedFiles.slice(0, 20) } : {}),
+            // Only when non-empty (#310, gotcha 433): on this path the DASHBOARD
+            // reads an empty list as «the folder was quiet», which is the opposite
+            // convention to the rewind preview, where the presence of the key is the
+            // warning. Two paths, two conventions, both deliberate.
+            ...(result.record.busySessions?.length
+                ? { busySessions: result.record.busySessions.slice(0, MAX_BUSY_SESSIONS) }
+                : {}),
         });
     }
+    /**
+     * 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.
+     */
+    noticeOncePerTurn(running, key, text) {
+        running.noticesThisTurn ??= new Set();
+        if (running.noticesThisTurn.has(key))
+            return;
+        running.noticesThisTurn.add(key);
+        this.sendEvent(running, 'notice', { level: 'info', text });
+    }
     /**
      * Deliver messages that raced session start (already journaled).
      *
@@ -3225,7 +3409,7 @@ export class Supervisor {
             return;
         }
         const open = running.stopCycle;
-        if (open && ownsProcess(open, running.session) && !open.settled) {
+        if (open && Supervisor.stopInFlight(running)) {
             // #357 part 2, and invariant 2 of the pause plan. Ten frames arrive while
             // the CLI is waiting out a provider retry — from a phone and a laptop at
             // once, or from a person pressing a button that gave them no sign it had
@@ -3624,7 +3808,7 @@ export class Supervisor {
         // could not tell a tool RESULT from a tool starting, so the tail of the stop
         // read as a turn beginning.
         const cycle = running.stopCycle;
-        if (cycle && ownsProcess(cycle, running.session) && !cycle.settled) {
+        if (cycle && Supervisor.stopInFlight(running)) {
             log.info('supervisor: output under a pause belongs to the stop in flight', {
                 sessionId: running.descriptor.id,
                 phase: cycle.phase,
@@ -3746,12 +3930,17 @@ export class Supervisor {
         }
         await this.applyLiveSettings(running, model, mode, effort);
     }
-    /** 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.
+     */
     isMidTurn(running) {
-        return (running.lastReported === 'RUNNING' ||
-            running.lastReported === 'STARTING' ||
-            running.lastReported === 'WAITING_PERMISSION' ||
-            running.openQuestions.size > 0);
+        return (Supervisor.MID_TURN_STATUSES.includes(running.lastReported) || running.openQuestions.size > 0);
     }
     /** The three live setters, in the order that lets an explicit pick win. */
     async applyLiveSettings(running, model, mode, effort) {
@@ -4096,10 +4285,12 @@ export class Supervisor {
                             running.baseBranch = prepared.baseBranch;
                     }
                     catch (error) {
-                        this.reportStatus(descriptor.id, 'FAILED', {
-                            errorMessage: `Failed to restore session worktree: ${String(error instanceof Error ? error.message : error).slice(0, 500)}`,
-                        });
-                        this.sessions.delete(descriptor.id);
+                        // The same treatment as the start door (#360). Two doors doing one
+                        // thing is how the pause bug of #373 stayed half-fixed for a
+                        // release; this one used to mask its text differently AND emit no
+                        // feed event at all, so a session that could not be restored went
+                        // FAILED with nothing to read anywhere.
+                        this.workspacePrepareFailed(running, error, 'Failed to restore session worktree');
                         continue;
                     }
                     /**
@@ -4253,7 +4444,24 @@ export class Supervisor {
     }
     // ─── Commands ──────────────────────────────────────────────────────
     async runCommand(frame) {
-        const reply = (result) => this.ws.send({ type: 'command_result', requestId: frame.requestId, ...result });
+        // How long a command actually took on THIS machine. Nothing measured it
+        // before, which is why «the branch probe timed out after 4 s» could never be
+        // answered with «it takes 9 s on that server» or «it never arrived» — the
+        // two failures #316 turned out to be. One line, at INFO, per command.
+        const startedAt = Date.now();
+        let answered = false;
+        const reply = (result) => {
+            if (!answered) {
+                answered = true;
+                log.info('supervisor: command handled', {
+                    command: frame.name,
+                    ...(frame.sessionId ? { sessionId: frame.sessionId } : {}),
+                    elapsedMs: Date.now() - startedAt,
+                    ok: result.ok,
+                });
+            }
+            this.ws.send({ type: 'command_result', requestId: frame.requestId, ...result });
+        };
         try {
             switch (frame.name) {
                 case 'validate_path': {
@@ -4446,7 +4654,9 @@ export class Supervisor {
                     if (!running.worktreePath) {
                         return void reply({ ok: false, error: 'The session has no working folder yet' });
                     }
-                    if (this.isWorktreeBusy(running.worktreePath)) {
+                    // #310: this session's own turn, not the folder's. A neighbour
+                    // working next door marks the point; it does not forbid it.
+                    if (this.isSessionMidTurn(running)) {
                         return void reply({ ok: false, error: AGENT_BUSY });
                     }
                     const before = (await listCheckpoints(running.worktreePath, running.descriptor.id))
@@ -4477,6 +4687,12 @@ export class Supervisor {
                                 // conversation is still on disk.
                                 canRewindContext: Boolean(item.agentAnchor),
                                 ...(item.messageSeq === undefined ? {} : { messageSeq: item.messageSeq }),
+                                // The mark travels with the LIST as well as with the live event
+                                // (#310): the list is how a reloaded page rebuilds state, and a
+                                // mark that only ever rode the event would be lost there.
+                                ...(item.busySessions?.length
+                                    ? { busySessions: item.busySessions.slice(0, MAX_BUSY_SESSIONS) }
+                                    : {}),
                             })),
                         },
                     });
@@ -4507,8 +4723,18 @@ export class Supervisor {
                     if (ordinal === null || !running.worktreePath) {
                         return void reply({ ok: false, error: 'ordinal is required' });
                     }
+                    // The folder check STAYS here: this one writes files, and files are
+                    // shared. What changes is the sentence — `AGENT_BUSY` talks about
+                    // «the agent», meaning this session's own, and names nobody. When it
+                    // is a neighbour holding the folder, say so (#310).
                     if (this.isWorktreeBusy(running.worktreePath)) {
-                        return void reply({ ok: false, error: AGENT_BUSY });
+                        const neighbours = this.busyNeighbours(running);
+                        return void reply({
+                            ok: false,
+                            error: neighbours.length > 0
+                                ? `Another session in this folder is still working (${neighbours.join(', ')}), so the files cannot be put back until it stops. Only the conversation can be rewound.`
+                                : AGENT_BUSY,
+                        });
                     }
                     const confirmRaw = frame.args?.['confirmDeletes'];
                     const confirmDeletes = Array.isArray(confirmRaw)
@@ -4522,6 +4748,10 @@ export class Supervisor {
                         sessionId: running.descriptor.id,
                         ordinal,
                         confirmDeletes,
+                        // The safety point is a restore point like any other and gets the
+                        // same question asked of it. Non-empty only through the #373
+                        // window — the folder check above has already passed.
+                        busySessions: () => this.busyNeighbours(running),
                         ...(typeof expectedTreeOid === 'string' && expectedTreeOid
                             ? { expectedTreeOid }
                             : {}),
@@ -4532,12 +4762,20 @@ export class Supervisor {
                         createdAt: result.safety.createdAt,
                         fileCount: result.safety.fileCount,
                         canRewindContext: Boolean(result.safety.agentAnchor),
+                        ...(result.safety.busySessions?.length
+                            ? { busySessions: result.safety.busySessions.slice(0, MAX_BUSY_SESSIONS) }
+                            : {}),
                         // This frame IS the browser's offer of «Undo rewind» — the point it
                         // names belongs to no message, so there is nowhere else the offer
                         // could come from. Withheld when the rewind was itself an undo:
                         // going back again is a redo, and a button that quietly changes
                         // meaning after one press is worse than no button.
-                        undoable: result.rewoundToKind !== 'SAFETY',
+                        //
+                        // Also withheld when the safety point itself came out marked (#310).
+                        // That happens through the #373 window — a neighbour woke between
+                        // the folder check and the snapshot — and `applyRewind` refuses a
+                        // marked point, so the offer would be a button that cannot work.
+                        undoable: result.rewoundToKind !== 'SAFETY' && !(result.safety.busySessions?.length ?? 0),
                     });
                     this.sendEvent(running, 'system_note', {
                         code: 'files_rewound',
@@ -4553,7 +4791,11 @@ export class Supervisor {
                     if (ordinal === null || !running.worktreePath) {
                         return void reply({ ok: false, error: 'ordinal is required' });
                     }
-                    if (this.isWorktreeBusy(running.worktreePath)) {
+                    // #310: the conversation can be rewound whatever the neighbours are
+                    // doing — it touches no file of theirs. This session's OWN unfinished
+                    // turn still has to stop first: the rewind parks and relaunches this
+                    // very process, and the button is hidden mid-turn anyway.
+                    if (this.isSessionMidTurn(running)) {
                         return void reply({ ok: false, error: AGENT_BUSY });
                     }
                     const items = await listCheckpoints(running.worktreePath, running.descriptor.id);
@@ -5457,19 +5699,90 @@ export class Supervisor {
             return 'sessionId is required';
         return this.sessions.get(sessionId) ?? 'Unknown session';
     }
+    /**
+     * 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`.)
+     */
+    static MID_TURN_STATUSES = [
+        'STARTING',
+        'RUNNING',
+        'WAITING_PERMISSION',
+    ];
+    /**
+     * 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».
+     */
+    static stopInFlight(running) {
+        const cycle = running.stopCycle;
+        return cycle !== undefined && ownsProcess(cycle, running.session) && !cycle.settled;
+    }
+    static holdsTheTree(running) {
+        return Boolean(running.session) && Supervisor.MID_TURN_STATUSES.includes(running.lastReported);
+    }
     /** A session actively mid-turn in this worktree — git writes must wait. */
     isWorktreeBusy(worktreePath) {
         for (const running of this.sessions.values()) {
-            if (running.worktreePath !== worktreePath || !running.session)
+            if (running.worktreePath !== worktreePath)
                 continue;
-            if (running.lastReported === 'STARTING' ||
-                running.lastReported === 'RUNNING' ||
-                running.lastReported === 'WAITING_PERMISSION') {
+            if (Supervisor.holdsTheTree(running))
                 return true;
-            }
         }
         return false;
     }
+    /**
+     * 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.
+     */
+    isSessionMidTurn(running) {
+        return Supervisor.holdsTheTree(running);
+    }
+    /**
+     * 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.
+     */
+    busyNeighbours(running) {
+        const worktreePath = running.worktreePath;
+        if (!worktreePath)
+            return [];
+        const ids = [];
+        for (const other of this.sessions.values()) {
+            // By id as well as by identity: a session that was re-started under a
+            // higher epoch is a NEW entry for the SAME session, and it must not end
+            // up marking its own restore point with its own id.
+            if (other === running ||
+                other.descriptor.id === running.descriptor.id ||
+                other.worktreePath !== worktreePath) {
+                continue;
+            }
+            if (Supervisor.holdsTheTree(other) || Supervisor.stopInFlight(other)) {
+                ids.push(other.descriptor.id);
+            }
+            if (ids.length >= MAX_BUSY_SESSIONS)
+                break;
+        }
+        return ids;
+    }
     // ─── Outbound helpers ──────────────────────────────────────────────
     // Hard cap far below the API's 128KB Zod limit — an oversized payload would
     // be rejected forever and wedge the journal (QA-96 F2).
@@ -5511,6 +5824,11 @@ export class Supervisor {
         const running = this.sessions.get(sessionId);
         if (running) {
             running.lastReported = status;
+            // Coming to rest ends the busy period the once-per-turn notices were
+            // limited to: the next one is about a new answer and deserves saying.
+            if (!Supervisor.MID_TURN_STATUSES.includes(status)) {
+                delete running.noticesThisTurn;
+            }
             this.syncBudgetClock(running);
         }
         // The fork point rides along on the first frame after the branch was
@@ -5558,6 +5876,7 @@ export class Supervisor {
     /** Graceful daemon shutdown: kill agents, keep sessions resumable server-side. */
     shutdown() {
         clearInterval(this.slotsTimer);
+        clearInterval(this.hostLoadTimer);
         clearInterval(this.agentVersionsTimer);
         clearTimeout(this.agentCleanupFirstTimer);
         clearInterval(this.agentCleanupTimer);

package/dist/systemd-memory.d.ts

@@ -0,0 +1,35 @@
+import { type CgroupMemory, type MemoryFacts } from './service-unit.js';
+/**
+ * Read the unit's group, never the CLI's own `/proc/self` group. A missing
+ * reading is not an empty service: a timed-out user bus can belong to a busy
+ * machine. Raw `memory.current` deliberately survives beside the split, so the
+ * safety floor never depends on an estimate of how much can be reclaimed.
+ */
+export declare function unitMemoryReading(output: string, cgroupRoot?: string): CgroupMemory | null;
+/**
+ * Both units, measured through systemd, with the filesystem underneath.
+ *
+ * One helper so `doctor`, `doctor --fix`, `install-service` and the daemon's
+ * hourly re-measure cannot drift apart in what they measure — which is how the
+ * CLI once computed a ceiling 34 % away from the daemon's and the two rewrote
+ * the file forever.
+ *
+ * The fallback is not a second opinion, it is the same reading taken another
+ * way, and it is safe for every caller precisely because each reader
+ * self-identifies: `readOwnCgroupMemory` hands back null for any process that
+ * is not the service itself, so the daemon measures itself when the bus is
+ * unhappy and a CLI never mistakes its own `session-N.scope` for the service.
+ * Without it, one slow `systemctl` meant the daemon wrote no policy at all —
+ * for an hour, on the overloaded machine this policy exists to protect.
+ */
+export declare function readMemoryFactsFromSystemd(): Promise<MemoryReadings>;
+export interface MemoryReadings {
+    facts: MemoryFacts | null;
+    sessionsUsageBytes: number | null;
+}
+/** The half of the above that has no bus in it, so it can be tested. */
+export declare function memoryReadings(service: CgroupMemory | null, sessions: CgroupMemory | null, fromFilesystem?: {
+    own: () => CgroupMemory | null;
+    sessions: () => CgroupMemory | null;
+}): MemoryReadings;
+//# sourceMappingURL=systemd-memory.d.ts.map