mandala-computer-mcp 0.1.1 → 0.4.0

package/dist/events.js

@@ -1,7 +1,7 @@
 /**
  * What a computer is doing, held open on this side of the model.
  *
- * `GET computers/:id/events` (platform OPL-3785) is a websocket that says what
+ * `GET computers/:id/events` (OPL-3785) is a websocket that says what
  * a computer is doing without being asked, so that an agent stops paying for a
  * screenshot to learn that nothing has changed. Every other client of that
  * stream hands it to its caller as an iterator, because every other caller sits
@@ -25,13 +25,13 @@
  * doorbell an addition to this file rather than a replacement for it, and one
  * whose bell nothing on the other end rings yet.
  *
- * Written against the `events_url` entry in the platform's `web/lib/apidoc.ts`,
- * which is the reference this must not contradict.
+ * Written against the `events_url` entry in the platform's API reference,
+ * which is what this must not contradict.
  */
 import { posix } from 'node:path';
 import { WebSocket as UndiciWebSocket } from 'undici';
 import { isTransientForPoll, MandalaError } from './errors.js';
-import { unwrapComputer } from './format.js';
+import { nothingAdmitted, unwrapComputer } from './format.js';
 import * as P from './paths.js';
 /**
  * undici's `WebSocket`, not Node's global one.
@@ -179,6 +179,8 @@ export class Subscription {
     #nextIndex = 0;
     /** The index after the last event handed to the model. */
     #delivered = 0;
+    /** The cursor immediately before the oldest event still in the ring. */
+    #beforeOldestCursor;
     /** Set once the model has read anything at all, so a first read can say so. */
     #read = false;
     #loss;
@@ -196,6 +198,8 @@ export class Subscription {
     /** The cursor after the last event actually handed to the model. */
     #deliveredCursor;
     #hello;
+    /** The buffer position after the greeting's cursor, retained across eviction. */
+    #helloFrom = 0;
     #types;
     /**
      * The trees nominated on this stream, oldest nomination first.
@@ -238,6 +242,12 @@ export class Subscription {
      * changed.
      */
     #armGen = new Map();
+    /** Next subscription-wide arm identity; active paths alone retain theirs. */
+    #nextArmGen = 0;
+    /** Trees that have armed at least once in this subscription. */
+    #everArmed = new Set();
+    /** Re-arms a file-wait response has not explained yet. */
+    #undisclosedRearm = new Set();
     /**
      * The STANDING loss on each tree, cleared when it arms.
      *
@@ -266,29 +276,19 @@ export class Subscription {
      * Trees a connection carrying them would not open, PROVEN so.
      *
      * Proven means the experiment came back positive — see {@link #cleared}: the
-     * tree was withheld, the same stream opened without it, and there is nothing
-     * else the difference could be. A tree merely suspected is
-     * {@link #shedCandidate} and is not in here.
+     * tree failed when added to a known working set, then that same set opened
+     * without it. A tree still being tested is not in here.
      */
     #watchRefused = new Set();
     /**
-     * The tree currently withheld from the URL to find out whether it is the
-     * reason nothing will open. `undefined` when no experiment is running.
+     * A bounded search for nominations the host will not carry.
      *
-     * It stays in {@link #watches} throughout, which is what keeps a caller from
-     * being told its tree was evicted to make room for somebody else's — this is
-     * a suspicion, not a decision about what the caller asked for.
+     * The last successful set is tried first. Once that opens, each addition is
+     * added back alone. A failed addition is removed once more for confirmation,
+     * so a host outage during the probe cannot turn an innocent tree into a
+     * refusal. Nominations stay in {@link #watches} throughout the experiment.
      */
-    #shedCandidate;
-    /**
-     * Whether a watch has been ruled out as the reason connections are failing.
-     *
-     * Set when an experiment comes back negative, cleared the moment anything
-     * greets. Without it a host that is simply DOWN would shed its way through
-     * every tree in the set two failures at a time, reporting each in turn as one
-     * the host would not carry.
-     */
-    #shedRuledOut = false;
+    #watchRecovery;
     /** What the last connection that reached an opening frame was carrying. */
     #lastGood = [];
     /** Consecutive connections that never reached an opening frame while watching. */
@@ -318,6 +318,8 @@ export class Subscription {
      */
     #sent = [];
     #greeted = false;
+    /** Monotonic so overlapping waits can each detect a connection interruption. */
+    #connectionVersion = 0;
     /**
      * Whether the socket now closing was closed by THIS side to re-nominate.
      *
@@ -384,6 +386,13 @@ export class Subscription {
     get state() {
         return this.#state;
     }
+    /** Cached capabilities survive a disconnect; this describes the current connection. */
+    get connected() {
+        return this.#greeted && this.#state.status === 'open';
+    }
+    get connectionVersion() {
+        return this.#connectionVersion;
+    }
     get idleMs() {
         return Date.now() - this.#lastUsed;
     }
@@ -421,6 +430,14 @@ export class Subscription {
     armGeneration(path) {
         return this.#armGen.get(path) ?? 0;
     }
+    /** Whether a completed re-arm still needs to be explained to this tree's caller. */
+    hasUndisclosedRearm(path) {
+        return this.#undisclosedRearm.has(path);
+    }
+    /** Claim a re-arm for the response that is about to explain it. */
+    takeUndisclosedRearm(path) {
+        return this.#undisclosedRearm.delete(path);
+    }
     /** The last thing this tree said it had lost, if it has said one since arming. */
     lostFor(path) {
         return this.#watchLost.get(path);
@@ -508,11 +525,36 @@ export class Subscription {
         // its tree limit, and the directory may since exist. "Call again" is the
         // advice every one of those refusals gives, so calling again has to mean
         // something.
-        const retrying = this.#watchRefused.delete(path) || this.#shedCandidate === path;
-        if (this.#shedCandidate === path)
-            this.#shedCandidate = undefined;
+        // `unwatchable` belongs in this list and was the one condition missing from
+        // it. It is the only standing loss a nomination can lift — the guest decides
+        // watchability when it is ASKED, which is at nomination time, so a directory
+        // that has since been created is answered for only by asking again. Left
+        // out, the tree stayed in `#sent`, the early return below skipped the
+        // reopen, and the clearing on the next connection's `hello` was unreachable:
+        // `wait_for_file_change` refused every later call on a tree that was by then
+        // perfectly watchable, while its own refusal ended by promising that calling
+        // again would find it armed.
+        //
+        // Deleted here, exactly as `#watchRefused` is, and for the same reason: the
+        // reopen below IS the act of asking again, so the old answer must not still
+        // be standing while the new one is in flight. Left in place it reopens and
+        // then defeats itself — `armedWait` returns on a standing `unwatchable`
+        // before the new connection can greet, so the retry costs a round trip and
+        // changes nothing. Nothing is carried forward wrongly by dropping it: a
+        // guest whose directory is still missing answers `unwatchable` again on the
+        // connection this opens, and a reopen that never greets leaves the wait to
+        // end on its own deadline, which is what the refused retry beside it does.
+        const unwatchable = this.#watchLost.get(path) === 'unwatchable';
+        if (unwatchable)
+            this.#watchLost.delete(path);
+        // A fresh request supersedes an in-flight diagnosis. The next connection
+        // carries the newly requested set and, if needed, diagnoses that set from
+        // the beginning rather than applying a conclusion to a set that changed.
+        const recovering = this.#watchRecovery !== undefined;
+        if (recovering)
+            this.#watchRecovery = undefined;
+        const retrying = this.#watchRefused.delete(path) || recovering || unwatchable;
         this.#upgradeFailures = 0;
-        this.#shedRuledOut = false;
         const at = this.#watches.indexOf(path);
         if (at >= 0) {
             // Most recently asked about goes last, so the eviction below always takes
@@ -525,8 +567,7 @@ export class Subscription {
             // reopen for. A tree being retried is neither.
             if (!retrying && this.#sent.includes(path))
                 return {};
-            this.#renominate = true;
-            this.#socket?.close();
+            this.#reopen();
             this.#wakeAll();
             return {};
         }
@@ -539,29 +580,42 @@ export class Subscription {
                 this.#watchLost.delete(evicted);
                 this.#hostName.delete(evicted);
                 this.#interrupted.delete(evicted);
+                this.#everArmed.delete(evicted);
+                this.#undisclosedRearm.delete(evicted);
                 this.#watchRefused.delete(evicted);
-                // An experiment about a tree nobody nominates any more has nothing left
-                // to prove, and letting it finish would file a refusal against a path
-                // this stream is no longer asking for.
-                if (this.#shedCandidate === evicted)
-                    this.#shedCandidate = undefined;
-                // The arm generation is deliberately NOT deleted. It has to stay
-                // monotonic per path, because a waiter parked on this tree is holding a
-                // number from before the eviction: reset to zero and re-nominated, the
-                // tree would come back at one and that waiter would read an eviction as
-                // a re-arm — "reporting starts here, re-read the tree" about a tree that
-                // had simply been taken away from it. Eviction is told by membership,
-                // which is what `nominates` is for.
+                // Historical paths retain no metadata. Generation identities come from
+                // a subscription-wide counter, so deleting this entry still cannot let
+                // an older waiter confuse a later re-nomination with its original arm.
+                this.#armGen.delete(evicted);
             }
         }
-        // Closed rather than aborted: `#loop` is still running and its next turn
-        // reads `#watches` for the new connection. The flag is what keeps that turn
-        // from paying the reconnect floor for a reconnection this side chose.
-        this.#renominate = true;
-        this.#socket?.close();
+        this.#reopen();
         this.#wakeAll();
         return { evicted };
     }
+    /**
+     * End the current connection so the next one carries the new watch set.
+     *
+     * Closed rather than aborted: `#loop` is still running and its next turn
+     * reads `#watches` for the new connection. `#renominate` is what keeps that
+     * turn from paying the reconnect floor for a reconnection this side chose.
+     *
+     * The flag is set ONLY when there is a socket to close, because that is what
+     * it claims: the connection now ending was ended by this side. Between
+     * connections there is none — `finish()` clears `#socket` the moment one
+     * ends, and the loop then spends a `GET /computers/:id` and a sleep before
+     * assigning the next — and a flag set in that window is consumed by the
+     * outcome of a connection this side did not cut short. That connection's
+     * failure to reach its opening frame is genuine evidence about the host, and
+     * swallowing it skips the backoff step, the `#blamed()` that would eventually
+     * shed the tree responsible, and the floor in front of the immediate retry.
+     */
+    #reopen() {
+        if (!this.#socket)
+            return;
+        this.#renominate = true;
+        this.#socket.close();
+    }
     /** Open the socket, if it is not already open. Returns at once. */
     start() {
         if (this.#running)
@@ -594,7 +648,12 @@ export class Subscription {
         this.touch();
         const attached = !this.#read;
         this.#read = true;
-        const from = this.resolveFrom(opts.since);
+        // The one place a gap the `since` cursor implies is turned into a standing
+        // loss, because this is the call that hands it to the model. Establishing it
+        // in the placement itself would stamp it on the subscription from every
+        // preview — and a preview whose caller then cancels, or a concurrent read on
+        // the same subscription, would take the gap away with it.
+        const { from, loss: standing } = this.#place(opts.since);
         const end = opts.through !== undefined ? opts.through + 1 : this.#nextIndex;
         const window = this.#ring.filter((b) => b.index >= from && b.index < end);
         // The OLDEST `limit`, not the newest, and the position advances only over
@@ -625,12 +684,12 @@ export class Subscription {
                 // An unknown count plus a known one is still unknown. Adding the two
                 // would report a precise number for a hole nobody can measure, which
                 // is the one thing a loss report must not do.
-                events: this.#loss?.events === null ? null : (this.#loss?.events ?? 0) + omitted,
-                reason: this.#loss
-                    ? `${this.#loss.reason}; and ${omitted} more than limit allowed were stepped over to reach the event you waited for`
+                events: standing?.events === null ? null : (standing?.events ?? 0) + omitted,
+                reason: standing
+                    ? `${standing.reason}; and ${omitted} more than limit allowed were stepped over to reach the event you waited for`
                     : `${omitted} events older than the one you waited for did not fit in limit and were stepped over`,
             }
-            : this.#loss;
+            : standing;
         this.#loss = undefined;
         return {
             events: batch.map((b) => b.event),
@@ -641,6 +700,33 @@ export class Subscription {
             attached,
         };
     }
+    /**
+     * Whether this read needs the current computer state attached to its loss.
+     *
+     * Asked before {@link read}, because reconciliation awaits network reads and
+     * a caller can cancel during them. Consuming first would advance the shared
+     * cursor and clear the loss into a response that caller never receives.
+     *
+     * A pure preview, and that is load-bearing rather than tidiness. It sees the
+     * gap an unplaceable `since` implies, but it does not record one: a subscription
+     * is shared by every call on its computer, so a predicate that stamped `#loss`
+     * would hand that gap to whichever call read next — the cancelled caller's hole
+     * reported against a later read that named a different cursor, or none at all.
+     */
+    needsReconciliation(opts) {
+        const { from, loss } = this.#place(opts.since);
+        if (loss)
+            return true;
+        if (opts.through === undefined)
+            return false;
+        const end = opts.through + 1;
+        let count = 0;
+        for (const buffered of this.#ring) {
+            if (buffered.index >= from && buffered.index < end)
+                count++;
+        }
+        return count > opts.limit;
+    }
     /**
      * Where a read or a wait starts: the model's own place, or the cursor it named.
      *
@@ -650,33 +736,75 @@ export class Subscription {
      * server holds, and saying so is the whole of the gap discipline — never a
      * frame the model has to interpret, always a sentence and, from the tool, the
      * state it would otherwise have gone to reconcile against.
+     *
+     * Reads nothing back into the subscription: see {@link #place}, which is where
+     * the sentence that gap discipline owes the model is composed, and {@link read},
+     * which is the only caller allowed to make it standing.
      */
     resolveFrom(since) {
+        return this.#place(since).from;
+    }
+    /**
+     * Placing a `since` cursor, and the loss a read from there would report.
+     *
+     * Pure. The returned `loss` is the standing loss MERGED with whatever this
+     * cursor implies, so a caller that reports it reports one hole rather than two
+     * overlapping accounts of the same evicted prefix — and a caller that only
+     * wanted the position, or only wanted to know whether there is a hole, leaves
+     * the subscription exactly as it found it.
+     */
+    #place(since) {
         // Where the model is, which is not where the socket is: it may be four
         // turns behind, and everything between the two is exactly what it has not
         // been handed yet.
-        if (since === undefined)
-            return Math.max(this.#delivered, this.#oldest);
+        if (since === undefined) {
+            return { from: Math.max(this.#delivered, this.#oldest), loss: this.#loss };
+        }
         const at = this.#ring.findIndex((b) => b.event.cursor === since);
         if (at >= 0)
-            return this.#ring[at].index + 1;
-        // The position at the moment this connection attached, which is
-        // legitimately older than anything in the ring on a quiet computer. The one
-        // deliberate rewind: a caller asking for it is asking to be re-sent this
-        // connection's whole buffer, and saying so exactly.
-        if (since === this.#hello?.cursor)
-            return this.#oldest;
+            return { from: this.#ring[at].index + 1, loss: this.#loss };
+        // An opening cursor can outlive everything that followed it in the ring.
+        // Evicting already delivered events is harmless for implicit reads, but a
+        // deliberate rewind asks for those events again and must hear about the hole.
+        if (since === this.#hello?.cursor) {
+            const missing = Math.max(0, this.#oldest - this.#helloFrom);
+            const loss = missing && this.#loss?.events !== null
+                ? {
+                    // Unread overflow and this rewind describe overlapping evicted
+                    // prefixes. Count their union, rather than adding the same loss twice.
+                    events: Math.max(missing, this.#loss?.events ?? 0),
+                    reason: 'events requested from that opening cursor were dropped from this session’s buffer',
+                }
+                : this.#loss;
+            return { from: Math.max(this.#helloFrom, this.#oldest), loss };
+        }
+        // An empty `through` read can advance the delivery position to the oldest
+        // survivor without handing over an event. Its cursor is the predecessor
+        // retained during eviction, which is no longer in the ring but is still an
+        // exact, lossless place from which to resume those survivors.
+        if (since === this.#beforeOldestCursor)
+            return { from: this.#oldest, loss: this.#loss };
         // Otherwise: the unread frontier, NOT the oldest thing still in the ring.
         // A delivered event stays in the ring until the cap evicts it, so answering
         // an unplaceable cursor with `#oldest` re-sent events the model already
         // had — while attaching a loss note that said they "were not kept", which
         // was false about exactly the events being re-sent.
-        this.#loss ??= {
-            events: null,
-            reason: 'that cursor is not a place this session can find, so whatever happened between it and ' +
-                'the events below was not kept here',
+        //
+        // `events: null` whatever else is standing, and that is the same rule
+        // {@link read} applies to its own overflow: a cursor this session cannot
+        // place may be any distance back, so a count taken from this buffer offered
+        // as the size of that hole would be a precise answer to a question nobody
+        // can measure. The standing reason is kept alongside, because an eviction
+        // here and an unplaceable cursor are two true things about one gap.
+        const unplaceable = 'that cursor is not a place this session can find, so whatever happened between it and ' +
+            'the events below was not kept here';
+        return {
+            from: Math.max(this.#delivered, this.#oldest),
+            loss: {
+                events: null,
+                reason: this.#loss ? `${this.#loss.reason}; and ${unplaceable}` : unplaceable,
+            },
         };
-        return Math.max(this.#delivered, this.#oldest);
     }
     /**
      * Wait for an event this predicate accepts, or for the deadline.
@@ -814,12 +942,42 @@ export class Subscription {
             cancel?.addEventListener('abort', done, { once: true });
         });
     }
-    /** The cursor for a position, or the connection's own when nothing was read. */
+    /**
+     * The cursor for a position — WHERE THE CALLER IS, which is not always where
+     * the socket is.
+     *
+     * The last event handed over answers it whenever there was one. When there was
+     * not, the answer is still the model's own place and not `#resume`, which is
+     * after the last event this connection RECEIVED. The two are the same on an
+     * ordinary empty poll, and that is why the difference went unnoticed: no
+     * `through`, an empty window means the position has caught up with the ring.
+     *
+     * A `through` read is the case where they part. A wait resolves on an event
+     * and reads up to it, and by then another call on the same computer — which
+     * these tools are built to allow — may already have taken it: the window comes
+     * back empty while `more` is still positive. Answering `#resume` there hands
+     * back `more_waiting: N` beside a cursor that, passed in as `since`, resolves
+     * PAST those N events, with no loss to say they were skipped. So the position
+     * is read off the ring at `#delivered`, which is the one place that agrees
+     * with the `more` in the same answer.
+     */
     #position(last) {
         const cursor = last?.event.cursor;
         if (typeof cursor === 'string' && cursor)
             return cursor;
-        return this.#resume ?? this.#hello?.cursor ?? '';
+        const at = this.#ring.find((b) => b.index === this.#delivered - 1)?.event.cursor;
+        if (typeof at === 'string' && at)
+            return at;
+        if (this.#delivered === this.#oldest && this.#beforeOldestCursor) {
+            return this.#beforeOldestCursor;
+        }
+        // Nothing in the ring to place it by: either nothing has been delivered on
+        // this stream at all, or the event the position sits after has been evicted.
+        // The last cursor DELIVERED, or the frontier where this subscription
+        // started before anything has been handed over. Both follow the same rule
+        // as {@link resumeCursor}: a position behind the receive head may replay,
+        // while a position ahead of unread records silently skips them.
+        return this.#deliveredCursor ?? this.#start ?? this.#hello?.cursor ?? '';
     }
     #wakeAll() {
         for (const wake of [...this.#wake])
@@ -827,8 +985,15 @@ export class Subscription {
     }
     #push(event) {
         this.#ring.push({ index: this.#nextIndex++, event });
+        // A resumed stream may replay the greeting's cursor after the greeting.
+        // Once that event arrives, its position is stronger than the initial frontier.
+        if (event.cursor === this.#hello?.cursor)
+            this.#helloFrom = this.#nextIndex;
         if (this.#ring.length > MAX_BUFFERED) {
             const evicted = this.#ring.splice(0, this.#ring.length - MAX_BUFFERED);
+            const beforeOldest = evicted[evicted.length - 1]?.event.cursor;
+            this.#beforeOldestCursor =
+                typeof beforeOldest === 'string' && beforeOldest ? beforeOldest : undefined;
             // Only what the model had not been handed is a loss. Dropping events it
             // already read is the ring doing its job, and counting those would report
             // a hole where there is none.
@@ -909,6 +1074,11 @@ export class Subscription {
             // tree, under an arming the caller is already waiting on.
             if (this.#renominate) {
                 this.#renominate = false;
+                // Recovery often closes a fallback or successful probe immediately
+                // after its greeting. It still proved the host reachable, so discard
+                // the failure backoff accumulated before that greeting.
+                if (reached)
+                    backoff = BACKOFF_MS;
                 continue;
             }
             // A connection that got as far as its opening frame is not a failure,
@@ -966,22 +1136,55 @@ export class Subscription {
             throw err;
         }
         const status = c.status ?? 'unknown';
-        if (status === 'suspended') {
+        // SETTLING IS FOREVER, so each of these has to be a state nobody is already
+        // moving out of. `status` cannot say that on its own: it is read from the
+        // guest process, and a start that has been ADMITTED has no process yet, so
+        // it reads `stopped` through a cold boot and `suspended` through a resume —
+        // whose session record is spent only on the way out of a start that worked.
+        // A stream opened against a computer mid-resume used to die permanently and
+        // name the resume as the reason (OPL-4631). nothingAdmitted is the
+        // platform's own word for idle, and absence of the field is not that word.
+        if (status === 'suspended' && nothingAdmitted(c)) {
             throw new SettledError(`${this.computerId} suspended, and the event stream is the one part of this API that does ` +
                 'not resume a computer for you. Listening is not using, so a computer nobody touches ' +
                 'suspends underneath its own stream. start_computer, then ask again.');
         }
-        if (status === 'stopped' || status === 'build-failed') {
-            throw new SettledError(`${this.computerId} is ${status}, and only a running computer has an event stream. ` +
+        // Two terminal answers, and they are not the same answer. A disk that was
+        // never finished is not started by anybody — the platform's own remedy is
+        // "delete it and build it again" — so telling that caller to start_computer
+        // sends them at a call that refuses them (Codex review).
+        if (status === 'build-failed') {
+            throw new SettledError(`${this.computerId}'s disk was never finished, so there is nothing to stream and nothing ` +
+                'to start. Delete it and build it again.');
+        }
+        if (status === 'stopped' && nothingAdmitted(c)) {
+            throw new SettledError(`${this.computerId} is stopped, and only a running computer has an event stream. ` +
                 'start_computer, then ask again.');
         }
+        // A computer whose disk was unlinked by a deletion that stopped partway
+        // will never start again — the reference says so, and says deleting it
+        // again is what clears it — so it belongs with the terminal states rather
+        // than in the backoff below (Codex review).
+        if (status === 'half-removed') {
+            throw new SettledError(`${this.computerId} is half-removed: its disk is gone, it will never start again, and ` +
+                'only deleting it again clears it. There is nothing to stream.');
+        }
         if (status !== 'running') {
-            // `starting`, `moving`, `creating` — states that clear on their own, so
-            // they get the backoff rather than the refusal. Settling on everything
-            // that was not `running` broke the flow the README advertises: a
-            // create_computer followed at once by wait_for_event("computer.ready")
-            // meets `starting`, which is the ordinary weather of a machine coming up
-            // and is precisely what the caller is waiting through.
+            // What is left is a state that MAY clear, which is a weaker claim than
+            // the one this comment used to make and the honest one: `building`; a
+            // `stopped` or `suspended` computer whose start has been admitted and is
+            // loading; and the two readings that are not answers at all — a status
+            // this client does not know, and a stopped or suspended computer whose
+            // pool the host did not report. Retrying those is right for the same
+            // reason waiting is: nothing here has said the machine will not come up.
+            // What it is not is a promise that one will.
+            //
+            // That last pair is what this branch was FOR, and it could not reach it.
+            // The comment here used to name `starting`, `moving` and `creating`; the
+            // platform reports none of them — its statuses are `running`, `stopped`,
+            // `suspended`, `building`, `build-failed` and `half-removed` — so the
+            // flow it described, a create_computer followed at once by
+            // wait_for_event("computer.ready"), met `stopped` and settled above.
             throw new MandalaError(`${this.computerId} is ${status}; waiting for it to be running`);
         }
         const vnc = c.vnc;
@@ -1073,12 +1276,17 @@ export class Subscription {
                 // `watching` is measured against, and what says whether a nomination
                 // made a moment ago is on this connection or on the next one.
                 //
-                // The nominations MINUS whatever is being withheld: a tree proven to be
-                // one this host will not carry, and the one currently under suspicion
-                // for it. Both stay in `#watches`, because they are still what the
-                // caller asked for and the difference belongs on the wire rather than
-                // in this client's record of the request.
-                this.#sent = this.#watches.filter((w) => !this.#watchRefused.has(w) && w !== this.#shedCandidate);
+                // Proven refusals stay off the wire. During diagnosis, the last working
+                // set is sent alone or with exactly one candidate; all nominations stay
+                // in `#watches`, because an experiment is not an eviction.
+                const recovery = this.#watchRecovery;
+                const included = recovery
+                    ? new Set([
+                        ...recovery.baseline,
+                        ...(recovery.phase === 'probe' && recovery.candidate ? [recovery.candidate] : []),
+                    ])
+                    : undefined;
+                this.#sent = this.#watches.filter((w) => !this.#watchRefused.has(w) && (!included || included.has(w)));
                 for (const w of this.#sent)
                     target.searchParams.append('watch', w);
                 socket = this.#socketFor(target.toString());
@@ -1100,6 +1308,8 @@ export class Subscription {
                 // A connection that has ended is not carrying anything, whatever it was
                 // greeted with. Without this the window between one connection ending
                 // and the next opening reads as a tree still on the wire.
+                if (opened)
+                    this.#connectionVersion++;
                 this.#greeted = false;
                 if (this.#socket === socket)
                     this.#socket = undefined;
@@ -1166,6 +1376,15 @@ export class Subscription {
             windows: Array.isArray(frame.windows) ? frame.windows : undefined,
             watching: watched(frame.watching),
         };
+        const buffered = this.#ring.find((b) => b.event.cursor === hello.cursor);
+        if (buffered)
+            this.#helloFrom = buffered.index + 1;
+        else if (hello.cursor === this.#beforeOldestCursor)
+            this.#helloFrom = this.#oldest;
+        else if (hello.cursor !== this.#hello?.cursor)
+            this.#helloFrom = this.#nextIndex;
+        // The same greeting on a reconnect must retain its original frontier,
+        // including any history that has since been evicted.
         this.#hello = hello;
         this.#types = hello.events;
         this.#greeted = true;
@@ -1173,7 +1392,7 @@ export class Subscription {
         // could be observed from otherwise — and a connection that WORKS does not
         // end for minutes or hours. An experiment whose positive result was only
         // read on the way out is an experiment with no result.
-        this.#cleared();
+        const continueWatchRecovery = this.#cleared();
         this.#adoptWatching(hello.watching);
         this.#resume ??= hello.cursor || undefined;
         this.#start ??= hello.cursor || undefined;
@@ -1194,6 +1413,12 @@ export class Subscription {
         // that is a new session. One extra readiness is the cheaper wrong answer.
         if (hello.ready && !resuming)
             this.#pushReady(hello.cursor);
+        // Advance only after this greeting has been fully adopted. Closing in
+        // `#cleared` would let its remaining work set `open` and armed state after
+        // the socket had already finished, briefly making an intermediate probe
+        // look like the connection about to replace it.
+        if (continueWatchRecovery)
+            this.#reopen();
         this.#wakeAll();
     }
     /**
@@ -1241,6 +1466,11 @@ export class Subscription {
         }
         sent.forEach((nominated, i) => {
             const w = watching[i];
+            // Keep the original index: `watching[i]` answers `sent[i]`, even when an
+            // earlier nomination was evicted while this connection was closing.
+            // The evicted entry itself must write nothing back into active metadata.
+            if (!this.#watches.includes(nominated))
+                return;
             if (w.path !== nominated)
                 this.#hostName.set(nominated, w.path);
             armed.set(nominated, w.armed);
@@ -1258,7 +1488,7 @@ export class Subscription {
             // would drop a permanent condition that nothing puts back. `hello.watching`
             // has no field for it, so the flag is the only record there is.
             if (w.armed && !this.isArmed(nominated)) {
-                this.#bumpArm(nominated);
+                this.#armedTransition(nominated);
                 this.#watchLost.delete(nominated);
             }
             else if (this.#watchLost.get(nominated) === 'unwatchable') {
@@ -1285,53 +1515,117 @@ export class Subscription {
      * reconnecting forever with nothing ever saying why.
      *
      * But a host that is down fails in exactly the same way, so two missed
-     * handshakes are not proof of anything. The experiment is: drop the newest
-     * tree and try again WITHOUT it. If that connection greets, the tree was the
-     * problem and this server can say so. If it fails too, the tree was innocent
-     * — it goes back, and nothing is claimed about the host beyond its being
-     * unreachable, which the reconnect loop was already handling.
+     * handshakes are not proof of anything. Recovery first returns to the last
+     * set that opened. If that fallback opens, each new nomination is added back
+     * alone. A candidate that fails is withheld once more and blamed only when
+     * the known-good set opens again. If that set also fails, recovery keeps it
+     * as the reconnect target and retests the candidate after the host returns.
      */
     #cleared() {
-        // Whatever was withheld is now proven guilty: this is the same stream
-        // without it, and it opened.
-        if (this.#shedCandidate !== undefined) {
-            this.#watchRefused.add(this.#shedCandidate);
-            this.#shedCandidate = undefined;
+        const recovery = this.#watchRecovery;
+        if (!recovery) {
+            this.#lastGood = [...this.#sent];
+            this.#upgradeFailures = 0;
+            return false;
+        }
+        // A `fallback` that opens proves only that the host is up and that the last
+        // working set still works. It is deliberately NOT a branch here, not even
+        // for a single addition: the full set failed twice, and a host that was down
+        // for those two attempts fails exactly as a refused nomination does, so the
+        // one thing the fallback opening cannot tell us is which of the two it was.
+        // Filing the only pending tree as refused from here read an outage as a
+        // refusal — the addition fell out of the watch set, and the model was told
+        // this host would not carry a tree it would have carried. The probe below
+        // costs one round trip and answers the question instead of guessing at it.
+        if (recovery.phase === 'recover') {
+            // A fallback failed too, so the outage made the preceding evidence
+            // ambiguous. Now that the known-good set is back, test that candidate
+            // again instead of filing a refusal from before the outage.
+            recovery.candidate ??= recovery.pending.shift();
+            if (recovery.candidate !== undefined) {
+                recovery.phase = 'probe';
+                this.#lastGood = [...recovery.baseline];
+                this.#upgradeFailures = 0;
+                return true;
+            }
+        }
+        else if (recovery.phase === 'probe' && recovery.candidate !== undefined) {
+            // This candidate opened beside the known-good set, so retain it while the
+            // remaining additions are tested.
+            recovery.baseline.push(recovery.candidate);
+        }
+        else if (recovery.phase === 'confirm' && recovery.candidate !== undefined) {
+            // The candidate failed beside this set and the same set has now reopened
+            // without it. Only here is a refusal proven.
+            this.#watchRefused.add(recovery.candidate);
         }
-        this.#lastGood = [...this.#sent];
+        recovery.candidate = undefined;
+        const next = recovery.pending.shift();
+        if (next !== undefined) {
+            recovery.candidate = next;
+            recovery.phase = 'probe';
+            this.#lastGood = [...recovery.baseline];
+            this.#upgradeFailures = 0;
+            return true;
+        }
+        this.#lastGood = [...recovery.baseline];
+        this.#watchRecovery = undefined;
         this.#upgradeFailures = 0;
-        this.#shedRuledOut = false;
+        return false;
     }
     /** @see {@link #cleared} — the other half, for a connection that never greeted. */
     #blamed() {
-        if (this.#shedCandidate !== undefined) {
-            // The experiment came back negative. The tree goes back on the URL and
-            // watches stop being blamed until something connects — otherwise a host
-            // that is simply down would shed its way through every tree in the set,
-            // reporting each in turn as one the host would not carry.
-            this.#shedCandidate = undefined;
-            this.#shedRuledOut = true;
+        const recovery = this.#watchRecovery;
+        if (recovery?.phase === 'probe') {
+            // A failed probe alone is not proof: the host may have gone down after
+            // the fallback opened. Retry the known-good set before blaming the tree.
+            recovery.phase = 'confirm';
+            this.#upgradeFailures = 0;
+            this.#wakeAll();
+            return;
+        }
+        if (recovery) {
+            // The known-good set failed too, so this is a host outage rather than
+            // evidence against a watch. Keep reconnecting that set; once it opens,
+            // the ambiguous candidate is probed again from fresh evidence.
+            recovery.phase = 'recover';
             this.#upgradeFailures = 0;
             this.#wakeAll();
             return;
         }
-        if (!this.#sent.length || this.#shedRuledOut)
+        if (!this.#sent.length)
             return;
         if (++this.#upgradeFailures < WATCH_SHED_AFTER)
             return;
         this.#upgradeFailures = 0;
-        // Whatever changed since this stream last worked, and only then the newest.
-        // After an LRU refresh "newest" means "most recently asked about", which is
-        // the opposite of a good suspect: the tree a caller keeps asking about is
-        // the one least likely to be new. What the last connection that actually
-        // greeted was carrying is the real before-and-after.
         const carried = this.#sent;
-        this.#shedCandidate =
-            carried.find((w) => !this.#lastGood.includes(w)) ?? carried[carried.length - 1];
+        const baseline = this.#lastGood.filter((watch) => carried.includes(watch) && !this.#watchRefused.has(watch));
+        let pending = carried.filter((watch) => !baseline.includes(watch));
+        // If an unchanged set stops opening, retain the old single-watch experiment:
+        // remove one tree and see whether the rest still opens. This can detect a
+        // watch the host stopped accepting without reading an outage as a refusal.
+        if (!pending.length) {
+            const candidate = carried[carried.length - 1];
+            pending = [candidate];
+            baseline.splice(baseline.indexOf(candidate), 1);
+        }
+        this.#watchRecovery = { baseline, pending, phase: 'fallback' };
         this.#wakeAll();
     }
     #bumpArm(path) {
-        this.#armGen.set(path, (this.#armGen.get(path) ?? 0) + 1);
+        if (!this.#watches.includes(path))
+            return;
+        this.#armGen.set(path, ++this.#nextArmGen);
+    }
+    /** Record an arm, retaining later arms until a file wait explains their gap. */
+    #armedTransition(path) {
+        if (!this.#watches.includes(path))
+            return;
+        if (this.#everArmed.has(path))
+            this.#undisclosedRearm.add(path);
+        else
+            this.#everArmed.add(path);
+        this.#bumpArm(path);
     }
     /**
      * What a `file.changed` says about the TREE, as opposed to about a file.
@@ -1375,7 +1669,7 @@ export class Subscription {
             // clears the flag when the link goes down — and the wait that should have
             // said "re-read the tree" would have gone on waiting on a tree whose
             // history had a hole in it.
-            this.#bumpArm(watch);
+            this.#armedTransition(watch);
             this.#armed.set(watch, true);
             return;
         }
@@ -1535,11 +1829,25 @@ export class EventHub {
      * resume — reaped for idleness, stopped on a computer somebody suspended —
      * and one there is nothing left to resume: a deleted computer's cursor names
      * a position in a stream that no longer exists.
+     *
+     * `expect` is the subscription the caller drained, and dropping BY IDENTITY
+     * rather than by id is what makes this safe under the concurrency these tools
+     * are designed for. Two calls on one computer overlap by design — a
+     * `wait_for_event` parked while a `poll_events` runs — and each holds its own
+     * handle. Without the check: A finds its stream stopped, drains it and drops
+     * it; the model's next call opens a fresh, healthy S2; B, still holding the
+     * stale S1, wakes, sees the status it recorded, drains an empty ring and
+     * drops — closing S2, a stream nothing was wrong with, out from under whoever
+     * had just opened it. Looked up by id, `drop` had no way to tell the two
+     * apart. A caller with no handle to name (the idle sweep passes the entry it
+     * is iterating) still drops whatever is there.
      */
-    drop(computerId, reason, remember = false) {
+    drop(computerId, reason, remember = false, expect) {
         const sub = this.#subs.get(computerId);
         if (!sub)
             return;
+        if (expect !== undefined && sub !== expect)
+            return;
         const at = sub.resumeCursor;
         const watches = sub.nominations;
         sub.close(reason);
@@ -1580,7 +1888,7 @@ export class EventHub {
                 // be reported once. The idle window is what eventually takes it.
                 if (sub.idleMs < IDLE_REAP_MS)
                     continue;
-                this.drop(id, 'nothing asked about this computer for five minutes', true);
+                this.drop(id, 'nothing asked about this computer for five minutes', true, sub);
             }
             if (!this.#subs.size)
                 this.#stopSweep();