mandala-computer-mcp 0.1.1 → 0.4.0

package/dist/tools/events.js

@@ -23,7 +23,7 @@ const KNOWN_TYPES = [
     'window.focused',
     'window.blurred',
     'clipboard.changed',
-    // The one type nobody is sent unasked (platform OPL-3927). It is here so a
+    // The one type nobody is sent unasked (OPL-3927). It is here so a
     // model reading this list knows it exists; a wait that names it and nothing
     // else, on a stream watching nothing, is answered with the sentence that says
     // how to make one arrive rather than with a timeout.
@@ -56,6 +56,8 @@ const KNOWN_TYPES = [
 const MAX_WAIT_S = 55;
 /** How long a first call gives the socket to reach its opening frame. */
 const ATTACH_MS = 20_000;
+/** Optional context must not hold an already-consumed event answer indefinitely. */
+const RECONCILE_MS = 2_000;
 /**
  * Wait for a subscription to say something about itself, inside a budget.
  *
@@ -93,20 +95,87 @@ async function attached(sub, cancel, deadline) {
  * the caller already has, and a windows listing that 409s because the guest is
  * busy must not turn a delivered event into a failed tool call.
  */
-async function reconcile(session, id, signal) {
-    const api = session.api.with(signal);
-    const state = {};
-    const [windows, computer] = await Promise.allSettled([
-        api.json('GET', P.computerAction(id, 'windows')),
-        api.json('GET', P.computer(id)),
+async function reconcile(session, id, cancel, deadline) {
+    const signal = AbortSignal.any([
+        AbortSignal.timeout(RECONCILE_MS),
+        ...(cancel ? [cancel] : []),
+        ...(deadline ? [deadline] : []),
     ]);
-    if (windows.status === 'fulfilled')
-        state.windows_now = windows.value;
-    if (computer.status === 'fulfilled') {
-        state.computer_now = withoutCredentials(unwrapComputer(computer.value));
+    const state = {};
+    if (!signal.aborted) {
+        const api = session.api.with(signal);
+        let end = () => { };
+        const expired = new Promise((resolve) => {
+            end = resolve;
+            signal.addEventListener('abort', end, { once: true });
+        });
+        try {
+            // Keep whichever half arrived before the deadline. The race also bounds
+            // embedders whose fetch implementation does not honour cancellation.
+            await Promise.race([
+                expired,
+                Promise.allSettled([
+                    api.json('GET', P.computerAction(id, 'windows')).then((windows) => {
+                        if (!signal.aborted)
+                            state.windows_now = windows;
+                    }),
+                    api.json('GET', P.computer(id)).then((computer) => {
+                        if (!signal.aborted) {
+                            state.computer_now = withoutCredentials(unwrapComputer(computer));
+                        }
+                    }),
+                ]),
+            ]);
+        }
+        finally {
+            signal.removeEventListener('abort', end);
+        }
+    }
+    if (!('windows_now' in state) || !('computer_now' in state)) {
+        state.reconciliation_note = reconciled(state).trim();
     }
     return state;
 }
+/** No continuity claim based solely on capabilities cached from an old socket. */
+function connectionNote(sub, version) {
+    if (sub.state.status === 'stopped') {
+        return 'The event stream has stopped. These are the events buffered so far; call again for the remaining events and the reason it stopped.';
+    }
+    if (!sub.connected) {
+        return 'The event stream is reconnecting. These are the events buffered so far; more history may arrive on replay, so silence here is not an answer about what the computer did. Call again.';
+    }
+    if (version === undefined || version !== sub.connectionVersion) {
+        return 'The event stream was interrupted during this wait and has reopened. These are the events buffered so far; replayed events will be returned as they arrive. Call again to keep waiting.';
+    }
+    return '';
+}
+/**
+ * The sentence that points at the reconciliation — naming only the keys it
+ * actually produced.
+ *
+ * `reconcile` assigns each key on a fulfilled read and swallows the rest, so
+ * `{}` is a real return value: the windows read 409s while the guest is busy,
+ * the computer read fails, or the caller's own signal aborts both. Naming
+ * `windows_now` and `computer_now` regardless sends a model looking for two
+ * keys that are not in the payload — a wasted turn on the one answer that is
+ * already admitting a hole, and the tool that has to be believed about holes.
+ */
+function reconciled(extras) {
+    const reads = [
+        { key: 'windows_now', tool: 'list_windows' },
+        { key: 'computer_now', tool: 'get_computer' },
+    ];
+    const here = reads.filter((r) => r.key in extras).map((r) => r.key);
+    const absent = reads.filter((r) => !(r.key in extras)).map((r) => r.tool);
+    if (!here.length) {
+        return (' See lost for what is known about it. Where the computer actually stands could NOT be read ' +
+            'just now, so it is not in this answer — call list_windows and get_computer for what the ' +
+            'missing events would have told you.');
+    }
+    return (` See lost for what is known about it, and ${here.join(' and ')} for where the computer ` +
+        `actually stands, which is what the missing events would have told you.` +
+        (absent.length ? ` The other half could not be read just now — call ${absent[0]} for it.` : ''));
+}
 /**
  * Why a computer is missing part of the guest half, in words.
  *
@@ -143,7 +212,7 @@ function guestHalf(can) {
         // too, so a computer reporting it plainly has one.
         return ('It does report the desktop half, which needs the same terminal channel a file watch runs ' +
             'over — so the channel is there and it is the file watch that is missing. The host holding ' +
-            'this computer predates them (platform OPL-3927), and there is nothing to do about that ' +
+            'this computer predates them (OPL-3927), and there is nothing to do about that ' +
             'from here.');
     }
     if (files && desktop) {
@@ -193,7 +262,7 @@ function name(ev) {
     return detail ? `${ev.type} (${detail})` : ev.type;
 }
 /** The body these tools answer with, minus the keys there is nothing to say about. */
-function body(id, d, watching) {
+function body(id, d, sub, watching) {
     const out = { computer: id, events: d.events, cursor: d.cursor };
     if (d.more)
         out.more_waiting = d.more;
@@ -204,14 +273,22 @@ function body(id, d, watching) {
     // another call can evict it, and a reconnect can find it disarmed. A reader
     // that had to remember which of four trees was live from a call several turns
     // ago is a reader that will get it wrong.
-    if (watching?.length)
-        out.watching = watching;
+    if (watching?.length) {
+        out.watching = watching.map((watch) => ({ ...watch, armed: watch.armed && sub.connected }));
+    }
     // Only where it is news. `can_emit` is what stops a model waiting for
     // something this machine will never produce, and the opening frame is the one
     // place that answer exists — but repeating it on every poll would be a field
     // that means nothing on the ninety-ninth call.
+    //
+    // Read from the LIVE list rather than from the greeting that seeded it. A
+    // `capabilities` frame replaces what `hello` advertised and goes both ways —
+    // a guest that turns out to have no watcher withdraws the half `hello`
+    // promised — and one landing between the opening frame and this subscription's
+    // first read would otherwise publish, exactly once and never again, a
+    // vocabulary that contradicts the one every refusal path here already acts on.
     if (d.attached && d.hello) {
-        out.can_emit = d.hello.events;
+        out.can_emit = sub.eventTypes ?? d.hello.events;
         if (d.hello.windows)
             out.windows_on_attach = d.hello.windows;
     }
@@ -255,8 +332,22 @@ function stopped(session, id, reason, sub, read) {
     const d = sub.read(read);
     const n = d.events.length;
     const drained = !d.more;
+    // The sub this call drained, named, so the drop cannot take a replacement.
+    // Two calls on one computer overlap by design here, and a second one holding
+    // a handle this one has already dropped would otherwise close the fresh
+    // stream opened in between.
     if (drained)
-        session.events.drop(id, reason, true);
+        session.events.drop(id, reason, true, sub);
+    // KNOWN GAP on the `!drained` side of that same overlap: if this call is the
+    // one holding the older handle, "call again for them" is a promise this
+    // server cannot keep. The next call resolves through `EventHub.open()`, which
+    // returns the subscription now in `#subs` — the replacement — and the events
+    // still in THIS one's ring are unreachable from that moment. Reaching it
+    // needs two calls overlapping on one computer with the older one parked
+    // mid-wait, which is why it has no test. Anything written here has to be
+    // narrower than "a fresh stream is running, there is nothing to fix": that
+    // sentence was tried, and it both dropped the disclosure above and reported a
+    // replacement that had itself stopped as healthy.
     const held = n
         ? `${n} event${n === 1 ? '' : 's'} had already arrived before it stopped and ${n === 1 ? 'is' : 'are'} ` +
             (drained
@@ -275,7 +366,7 @@ function stopped(session, id, reason, sub, read) {
     // Without the watch set, deliberately. This stream has stopped, so a tree
     // it was carrying is a tree nothing is watching — and `watching` reports
     // `armed` from the last opening frame, which would read as live.
-    n || d.loss ? body(id, d) : undefined);
+    n || d.loss ? body(id, d, sub) : undefined);
 }
 /**
  * A stream that has not yet got as far as its opening frame.
@@ -357,6 +448,21 @@ export const registerEvents = (server, session) => {
         // had already taken — the same defect one tool over, with a ring in this
         // session instead of a cursor in the guest. Nothing is created and nothing
         // is destroyed, which is what made the annotation look right.
+        // No readOnlyHint, for the reason above — and BOTH other flags set,
+        // because the spec's defaults are wrong in one direction and unstated in
+        // the other the moment readOnlyHint is absent (OPL-4516).
+        //
+        // destructiveHint would default to TRUE, so without it this asks a host
+        // whether it may perform DESTRUCTIVE UPDATES in order to read.
+        // `cursor_position` and `read_file` set it for that reason; these were not
+        // revisited with them.
+        //
+        // idempotentHint is FALSE, which is the difference from those two, and it
+        // is set rather than left to its default for the same reason as the other:
+        // a host reading an absent flag as "unknown, safe to retry" would retry a
+        // timed-out poll and silently drop what the first attempt consumed, which
+        // is the harm the paragraph above it is about.
+        annotations: { destructiveHint: false, idempotentHint: false },
     }, ({ computer_id, types, pid, timeout_s, since, limit }, extra) => guarded(async () => {
         const id = session.resolve(computer_id);
         const sub = session.events.open(id);
@@ -374,14 +480,16 @@ export const registerEvents = (server, session) => {
         // point in this call, and a `state` captured before the wait is a
         // statement about a moment that has passed.
         const opening = sub.state;
+        // A cancelled call must not drain a stopped subscription's final
+        // buffered delivery into an answer its caller can no longer receive.
+        if (extra.signal?.aborted)
+            return cancelledDuringAttach(id);
         if (opening.status === 'stopped') {
             return stopped(session, id, opening.reason, sub, { since, limit });
         }
-        // A caller who hung up is not a stream that failed to open.
-        if (extra.signal?.aborted)
-            return cancelledDuringAttach(id);
         if (!sub.eventTypes)
             return unattached(id, Date.now() - started);
+        const connection = sub.connected ? sub.connectionVersion : undefined;
         // A `pid` on its own means the exit of THAT command. Without this the
         // filter below reads "anything that is not a process.exited passes",
         // and `wait_for_event({pid: 99})` — which is how the argument's own
@@ -504,12 +612,13 @@ export const registerEvents = (server, session) => {
         const waited = Math.round((Date.now() - started) / 1000);
         if (hit === undefined) {
             if (extra.signal?.aborted) {
-                return refused(`Cancelled while waiting on ${id}. The stream is still open and still buffering — ` +
-                    `nothing was missed.`);
+                return refused(`Cancelled while waiting on ${id}. Buffered events remain available on the next call. ` +
+                    (connectionNote(sub, connection) || 'The stream is still open and buffering.'));
+            }
+            const stoppedWhileWaiting = sub.state;
+            if (stoppedWhileWaiting.status === 'stopped') {
+                return stopped(session, id, stoppedWhileWaiting.reason, sub, { since, limit });
             }
-            const now = sub.state;
-            if (now.status === 'stopped')
-                return stopped(session, id, now.reason, sub, { since, limit });
             // Asked again, because the wait that just ended is long enough for a
             // `capabilities` frame to have arrived inside it. A withdrawal that
             // happened while parked is still the reason nothing came, and saying
@@ -525,8 +634,19 @@ export const registerEvents = (server, session) => {
             // which is an answer, and it comes with the cursor that makes asking
             // again cost nothing. Reporting it as a failure would teach a model to
             // stop asking — back to the screenshot loop this tool exists to end.
+            const needsReconciliation = sub.needsReconciliation({ since, limit });
+            const recovered = needsReconciliation
+                ? await reconcile(session, id, extra.signal, deadline)
+                : {};
+            if (extra.signal?.aborted) {
+                return refused(`Cancelled while waiting on ${id}. Buffered events remain available on the next call. ` +
+                    (connectionNote(sub, connection) || 'The stream is still open and buffering.'));
+            }
+            const now = sub.state;
+            if (now.status === 'stopped')
+                return stopped(session, id, now.reason, sub, { since, limit });
             const d = sub.read({ since, limit });
-            const extras = d.loss ? await reconcile(session, id, extra.signal) : {};
+            const extras = d.loss ? recovered : {};
             // What did NOT match still happened, and this read has just handed it
             // over — so the sentence has to name it. Saying "nothing happened"
             // over a payload holding three events is the one thing a model must
@@ -537,6 +657,11 @@ export const registerEvents = (server, session) => {
                 ? ` ${d.events.length} other event${d.events.length === 1 ? '' : 's'} did happen and ` +
                     `${d.events.length === 1 ? 'is' : 'are'} below.`
                 : '';
+            const interrupted = connectionNote(sub, connection);
+            if (interrupted || d.loss) {
+                return said(`${interrupted || `No matching event is buffered on ${id}.`}${others}` +
+                    (d.loss ? reconciled(extras) : ''), { ...body(id, d, sub, sub.watching), ...extras });
+            }
             return said(`Nothing ${wanted ? `matching ${[...wanted].join(' or ')} ` : ''}happened on ${id} in ` +
                 `${timeout_s}s.${others} This server kept listening the whole time and is still ` +
                 `listening — nothing was missed and nothing is being missed now. Call again to ` +
@@ -545,20 +670,35 @@ export const registerEvents = (server, session) => {
                 // wait was real: what must not happen is a model reading "nothing
                 // happened" as covering a type nothing was ever going to send.
                 (unwatched() ? ` One thing was NOT being waited for: ${nominate()}` : '') +
-                (d.loss ? ' Some events were lost before they could be read — see lost.' : ''), { ...body(id, d, sub.watching), ...extras });
+                (d.loss ? ' Some events were lost before they could be read — see lost.' : ''), { ...body(id, d, sub, sub.watching), ...extras });
+        }
+        const needsReconciliation = sub.needsReconciliation({ since, limit, through: hit });
+        const recovered = needsReconciliation
+            ? await reconcile(session, id, extra.signal, deadline)
+            : {};
+        if (extra.signal?.aborted) {
+            return refused(`Cancelled while waiting on ${id}. Buffered events remain available on the next call. ` +
+                (connectionNote(sub, connection) || 'The stream is still open and buffering.'));
         }
         const d = sub.read({ since, limit, through: hit });
         const last = d.events[d.events.length - 1];
-        const extras = d.loss ? await reconcile(session, id, extra.signal) : {};
+        const extras = d.loss ? recovered : {};
         const before = d.events.length - 1;
         // Empty when another call on this computer consumed the matched event
         // first: the ring is one buffer with one delivered cursor, and two
         // overlapping waits can both match before either reads. Naming an event
         // over an empty list would be an event the caller is never shown.
         if (!last) {
+            if (d.loss) {
+                return said(`An event on ${id} matched this wait, but the matching event is no longer in this ` +
+                    `call's delivery. Some buffered history was lost before it could be read, so do ` +
+                    `not assume another reader safely received the match.` +
+                    reconciled(extras) +
+                    ` Call again for the events that remain buffered.`, { ...body(id, d, sub, sub.watching), ...extras });
+            }
             return said(`Something happened on ${id} and another call on this computer was handed it before ` +
                 `this one could read it — the events are in that call's answer, not below. Nothing ` +
-                `is lost; look there, or call again for whatever comes next.`, { ...body(id, d, sub.watching), ...extras });
+                `is lost; look there, or call again for whatever comes next.`, { ...body(id, d, sub, sub.watching), ...extras });
         }
         return said(`${name(last)} on ${id} after ${waited}s` +
             (before > 0 ? `, and ${before} before it` : '') +
@@ -568,7 +708,7 @@ export const registerEvents = (server, session) => {
                     'and computer.ready is announced once per desktop session — so the real event had ' +
                     'happened before there was anything here to hear it, and waiting for it would have ' +
                     'waited forever.'
-                : ''), { ...body(id, d, sub.watching), ...extras });
+                : ''), { ...body(id, d, sub, sub.watching), ...extras });
     }));
     /**
      * What one `file.changed` says, in a sentence.
@@ -691,6 +831,21 @@ export const registerEvents = (server, session) => {
         // tree out of the watch set. A client treating the hint as licence to
         // retry a call that timed out would silently drop events and, on the
         // fifth distinct path, silently stop watching the first.
+        // No readOnlyHint, for the two reasons above — and destructiveHint TRUE,
+        // which is where this parts company with the three consuming reads beside
+        // it (OPL-4516).
+        //
+        // The spec reads `false` as "performs only additive updates", and this does
+        // not: a nomination past MAX_WATCHES evicts the least recent tree and
+        // deletes its armed, lost and host state, so a fifth call ends event
+        // delivery on the first with nothing said. Claiming additive-only would be
+        // the same false all-clear the missing readOnlyHint already avoids — a host
+        // that auto-approves non-destructive tools would let the model do it with
+        // nobody asked. Same value the absent annotation defaulted to, said out
+        // loud so it reads as a decision rather than an omission.
+        //
+        // idempotentHint false for the reason the others set it: this consumes.
+        annotations: { destructiveHint: true, idempotentHint: false },
     }, ({ computer_id, path, timeout_s, since, limit }, extra) => guarded(async () => {
         const id = session.resolve(computer_id);
         // Before anything is opened. A path this host will not accept is a 400
@@ -715,11 +870,11 @@ export const registerEvents = (server, session) => {
         const started = Date.now();
         await attached(sub, extra.signal, deadline);
         const opening = sub.state;
+        if (extra.signal?.aborted)
+            return cancelledDuringAttach(id);
         if (opening.status === 'stopped') {
             return stopped(session, id, opening.reason, sub, { since, limit });
         }
-        if (extra.signal?.aborted)
-            return cancelledDuringAttach(id);
         if (!sub.eventTypes)
             return unattached(id, Date.now() - started);
         // Asked before the tree is nominated, because a computer that cannot
@@ -748,11 +903,11 @@ export const registerEvents = (server, session) => {
         if (!sub.nominationLive(root)) {
             await sub.nominated(root, deadline, extra.signal);
             const after = sub.state;
+            if (extra.signal?.aborted)
+                return cancelledWhileArming(id, root);
             if (after.status === 'stopped') {
                 return stopped(session, id, after.reason, sub, { since, limit });
             }
-            if (extra.signal?.aborted)
-                return cancelledWhileArming(id, root);
             // ASKED FIRST, all four of them, because each is an answer and the
             // timeout below is only the absence of one. A tree the host would not
             // carry, one another call evicted, or a computer that has stopped
@@ -777,7 +932,7 @@ export const registerEvents = (server, session) => {
         if (sub.watchesHonoured === false) {
             return refused(`${id} opened its event stream but said nothing about ${root}, so this server cannot ` +
                 `tell whether the tree is being watched — and a wait would be a wait on silence. The ` +
-                `host holding this computer may predate file watches (platform OPL-3927). Use exec ` +
+                `host holding this computer may predate file watches (OPL-3927). Use exec ` +
                 `to look at the directory instead.` +
                 evicted);
         }
@@ -786,10 +941,10 @@ export const registerEvents = (server, session) => {
             await sub.armedWait(root, deadline, extra.signal);
         if (!sub.isArmed(root)) {
             const now = sub.state;
-            if (now.status === 'stopped')
-                return stopped(session, id, now.reason, sub, { since, limit });
             if (extra.signal?.aborted)
                 return cancelledWhileArming(id, wire);
+            if (now.status === 'stopped')
+                return stopped(session, id, now.reason, sub, { since, limit });
             // Asked before the sentence below, all four of them, because that
             // sentence says the nomination stands and this tree is still coming
             // up — and every word of it is false when the tree has been evicted
@@ -817,6 +972,7 @@ export const registerEvents = (server, session) => {
         // whatever happened in between was never reported and the tree has to
         // be re-read.
         const generation = sub.armGeneration(root);
+        const connection = sub.connected ? sub.connectionVersion : undefined;
         // Said once, on the first answer about a tree this subscription
         // inherited from one that went away. A tree is watched by the
         // CONNECTION, so the idle reap that took the previous subscription also
@@ -839,6 +995,49 @@ export const registerEvents = (server, session) => {
                 `a watch lives on the connection. Anything that changed in that window was never ` +
                 `reported and cannot be. Re-read the directory with exec if it matters.`
             : '';
+        // Kept by the subscription rather than inferred from this call's
+        // generation snapshot. A re-arm can arrive while no tool call exists,
+        // and snapshotting after it would otherwise erase the only evidence of
+        // the unreported window. Delete the marker here, where its explanation
+        // is rendered, so unrelated reads and cancelled waits cannot consume it.
+        const rearmNotice = () => `The watch on ${wire} was re-armed after an interruption — a stop and a start, a ` +
+            `guest reboot, a broker replaced. Reporting starts again HERE, and nothing that ` +
+            `happened to the tree while it was down was reported or ever will be. Re-read the ` +
+            `directory with exec if that window matters, then call again to keep waiting.`;
+        const cancelledWait = () => refused(`Cancelled while waiting on ${wire}. Nothing was missed by the cancellation — this ` +
+            `server holds the stream and its buffer between calls — but nothing was checked ` +
+            `about the watch either, so call again for an answer about the tree.` +
+            interrupted());
+        if (sub.hasUndisclosedRearm(root)) {
+            const needsReconciliation = sub.needsReconciliation({ since, limit });
+            const recovered = needsReconciliation
+                ? await reconcile(session, id, extra.signal, deadline)
+                : {};
+            if (extra.signal?.aborted)
+                return cancelledWait();
+            const after = sub.state;
+            if (after.status === 'stopped')
+                return stopped(session, id, after.reason, sub, { since, limit });
+            const d = sub.read({ since, limit });
+            const extras = d.loss ? recovered : {};
+            const answer = { ...body(id, d, sub, sub.watching), watch: wire, ...extras };
+            const why = settled(sub, id, root, wire, () => interrupted() + evicted, answer);
+            if (why)
+                return why;
+            // A competing same-tree wait may have explained it while reconcile
+            // was in flight. Only the call that claims the marker repeats it.
+            if (sub.takeUndisclosedRearm(root)) {
+                return said(rearmNotice() + interrupted() + renamed + evicted, answer);
+            }
+            return said(`Another call on ${id} reported the watch interruption while this call was ` +
+                `reconciling it. This call's delivery is below.` +
+                (d.loss
+                    ? ` Some buffered history was lost before it could be read.${reconciled(extras)}`
+                    : ` No buffered event was dropped.`) +
+                interrupted() +
+                renamed +
+                evicted, answer);
+        }
         // When the waiting actually started, which is not when the call did.
         // `timeout_s` bounds the whole call — it has to, because a client
         // cancels a request that outlives its own timeout — so a call that
@@ -892,38 +1091,45 @@ export const registerEvents = (server, session) => {
                 // call did not check and which a cancel racing an eviction or a
                 // shed makes false. What IS true is the part that matters: the
                 // buffer is on this side and nothing in it went anywhere.
-                return refused(`Cancelled while waiting on ${wire}. Nothing was missed by the cancellation — this ` +
-                    `server holds the stream and its buffer between calls — but nothing was checked ` +
-                    `about the watch either, so call again for an answer about the tree.` +
-                    interrupted());
+                return cancelledWait();
             }
             const now = sub.state;
             if (now.status === 'stopped')
                 return stopped(session, id, now.reason, sub, { since, limit });
+            const needsReconciliation = sub.needsReconciliation({ since, limit });
+            const recovered = needsReconciliation
+                ? await reconcile(session, id, extra.signal, deadline)
+                : {};
+            if (extra.signal?.aborted)
+                return cancelledWait();
+            const after = sub.state;
+            if (after.status === 'stopped')
+                return stopped(session, id, after.reason, sub, { since, limit });
             const d = sub.read({ since, limit });
-            const extras = d.loss ? await reconcile(session, id, extra.signal) : {};
-            const answer = { ...body(id, d, sub.watching), watch: wire, ...extras };
+            const extras = d.loss ? recovered : {};
+            const answer = { ...body(id, d, sub, sub.watching), watch: wire, ...extras };
             // THESE FIRST, and in this order, because each would otherwise be
-            // described as something else. Evicting a tree does not reset its arm
-            // generation — that is kept monotonic on purpose — but it does take
-            // the tree out of the watch set, and the generation branch below would
-            // call that a re-arm and invite the caller to go on waiting on a tree
-            // nothing nominates. A tree the host would not carry is missing from
+            // described as something else. Evicting a tree drops its arm
+            // generation along with the rest of its metadata, so the generation
+            // branch below reads an eviction as a change and would call it a
+            // re-arm — inviting the caller to go on waiting on a tree nothing
+            // nominates. Membership is what that actually is, and `settled` is
+            // where it is asked. A tree the host would not carry is missing from
             // the set for a quite different reason, which is why the refusal is
             // asked about ahead of the membership.
+            //
+            // Generations stay unambiguous across a re-nomination because they
+            // come from a subscription-wide counter: a tree that comes back gets
+            // a number no waiter can be holding, rather than restarting at one.
             const why = settled(sub, id, root, wire, () => interrupted() + evicted, {
-                ...body(id, d, sub.watching),
+                ...body(id, d, sub, sub.watching),
                 ...extras,
             });
             if (why)
                 return why;
             if (sub.armGeneration(root) !== generation) {
-                return said(`The watch on ${wire} was re-armed after an interruption — a stop and a start, a ` +
-                    `guest reboot, a broker replaced. Reporting starts again HERE, and nothing that ` +
-                    `happened to the tree while it was down was reported or ever will be. Re-read the ` +
-                    `directory with exec if that window matters, then call again to keep waiting.` +
-                    interrupted() +
-                    evicted, answer);
+                sub.takeUndisclosedRearm(root);
+                return said(rearmNotice() + interrupted() + evicted, answer);
             }
             if (!sub.isArmed(root)) {
                 return refused(`${wire} on ${id} stopped being watched while this call was waiting, so NOTHING can ` +
@@ -959,6 +1165,15 @@ export const registerEvents = (server, session) => {
                     interrupted() +
                     evicted, answer);
             }
+            const connectionChanged = connectionNote(sub, connection);
+            if (connectionChanged || d.loss) {
+                return said(`${connectionChanged || `No file change is buffered for ${wire}.`} ` +
+                    `A quiet directory cannot be confirmed for this whole wait.` +
+                    (d.loss ? reconciled(extras) : '') +
+                    interrupted() +
+                    renamed +
+                    evicted, answer);
+            }
             // NOT an error, for the reason wait_for_event's timeout is not: the
             // tree was being watched for the whole of it, so "nothing changed" is
             // an answer rather than an absence of one. This is the sentence the
@@ -977,19 +1192,50 @@ export const registerEvents = (server, session) => {
                 evicted +
                 (d.loss ? ' Some events were lost before they could be read — see lost.' : ''), answer);
         }
+        const needsReconciliation = sub.needsReconciliation({ since, limit, through: hit });
+        const recovered = needsReconciliation
+            ? await reconcile(session, id, extra.signal, deadline)
+            : {};
+        if (extra.signal?.aborted)
+            return cancelledWait();
         const d = sub.read({ since, limit, through: hit });
         const last = d.events[d.events.length - 1];
-        const extras = d.loss ? await reconcile(session, id, extra.signal) : {};
+        const extras = d.loss ? recovered : {};
         const earlier = d.events.length - 1;
         // The one `lost` that is not a re-read: it says the tree is not being
         // watched, so it is the request failing rather than the watch reporting.
         // It arrives as an ordinary file.changed and would otherwise be
         // described by changeLine, which has nothing useful to say about it.
         if ((last?.data?.lost ?? '') === 'unwatchable') {
-            return refused(`${unwatchable(wire)} It was being watched until now; from here it is not.` +
+            // Only when the tree is not being watched NOW. An `unwatchable` sits
+            // in the ring until something reads it, and a caller who created the
+            // directory and called again re-nominates: the guest answers the new
+            // nomination with an arm, and this marker — already reported to the
+            // call that refused on it — is then describing a watch that has since
+            // been replaced. Handed back as the answer it refuses a second time
+            // over a directory that plainly exists, which is the same false
+            // "not there yet" the re-nomination exists to clear, one call later.
+            //
+            // `isArmed` is what tells the two apart, and it is exact rather than a
+            // proxy: `unwatchable` is the one `lost` that disarms, so a tree still
+            // carrying this marker as its live state reads false here, while one
+            // the guest has since armed reads true. Said with the re-arm's own
+            // sentence, because that is what happened and the window is genuinely
+            // unreported either way.
+            if (!sub.isArmed(root)) {
+                return refused(`${unwatchable(wire)} It was being watched until now; from here it is not.` +
+                    interrupted() +
+                    renamed +
+                    evicted, { ...body(id, d, sub, sub.watching), watch: wire, ...extras });
+            }
+            return said(`${wire} on ${id} was not watchable when this stream last asked — it was reported ` +
+                `missing or unreadable — and it is being watched now: the nomination was retried and ` +
+                `the guest armed it. Reporting starts HERE, so nothing that happened under it before ` +
+                `this was reported or ever will be. Re-read the directory with exec if that window ` +
+                `matters, then call again to wait for what comes next.` +
                 interrupted() +
                 renamed +
-                evicted, { ...body(id, d, sub.watching), watch: wire, ...extras });
+                evicted, { ...body(id, d, sub, sub.watching), watch: wire, ...extras });
         }
         // A `through` read can come back empty when another call on this
         // computer consumed the matched event first — the ring is one buffer
@@ -997,19 +1243,29 @@ export const registerEvents = (server, session) => {
         // before either reads. Announcing "a change" over an empty list would be
         // a change the caller is never shown.
         if (!last) {
+            if (d.loss) {
+                return said(`A file change under ${wire} on ${id} matched this wait, but the matching event is ` +
+                    `no longer in this call's delivery. Some buffered history was lost before it ` +
+                    `could be read, so do not assume another reader safely received the match.` +
+                    reconciled(extras) +
+                    ` Re-read the directory with exec, then call again for whatever comes next.` +
+                    interrupted() +
+                    renamed +
+                    evicted, { ...body(id, d, sub, sub.watching), watch: wire, ...extras });
+            }
             return said(`Something changed under ${wire} on ${id}, and another call on this computer was ` +
                 `handed it before this one could read it — the events are in that call's answer, ` +
                 `not below. Nothing is lost; look there, or call again for whatever comes next.` +
                 interrupted() +
                 renamed +
-                evicted, { ...body(id, d, sub.watching), watch: wire, ...extras });
+                evicted, { ...body(id, d, sub, sub.watching), watch: wire, ...extras });
         }
         return said(`${changeLine(last, id)} after ${waited}s` +
             (earlier > 0 ? `, and ${earlier} event${earlier === 1 ? '' : 's'} before it` : '') +
             '.' +
             interrupted() +
             renamed +
-            evicted, { ...body(id, d, sub.watching), watch: wire, ...extras });
+            evicted, { ...body(id, d, sub, sub.watching), watch: wire, ...extras });
     }));
     server.registerTool('poll_events', {
         title: 'Read what has happened',
@@ -1036,6 +1292,21 @@ export const registerEvents = (server, session) => {
         // had already taken — the same defect one tool over, with a ring in this
         // session instead of a cursor in the guest. Nothing is created and nothing
         // is destroyed, which is what made the annotation look right.
+        // No readOnlyHint, for the reason above — and BOTH other flags set,
+        // because the spec's defaults are wrong in one direction and unstated in
+        // the other the moment readOnlyHint is absent (OPL-4516).
+        //
+        // destructiveHint would default to TRUE, so without it this asks a host
+        // whether it may perform DESTRUCTIVE UPDATES in order to read.
+        // `cursor_position` and `read_file` set it for that reason; these were not
+        // revisited with them.
+        //
+        // idempotentHint is FALSE, which is the difference from those two, and it
+        // is set rather than left to its default for the same reason as the other:
+        // a host reading an absent flag as "unknown, safe to retry" would retry a
+        // timed-out poll and silently drop what the first attempt consumed, which
+        // is the harm the paragraph above it is about.
+        annotations: { destructiveHint: false, idempotentHint: false },
     }, ({ computer_id, since, limit }, extra) => guarded(async () => {
         const id = session.resolve(computer_id);
         const sub = session.events.open(id);
@@ -1046,15 +1317,34 @@ export const registerEvents = (server, session) => {
         const started = Date.now();
         await attached(sub, extra.signal);
         const state = sub.state;
+        if (extra.signal?.aborted)
+            return cancelledDuringAttach(id);
         if (state.status === 'stopped') {
             return stopped(session, id, state.reason, sub, { since, limit });
         }
-        if (extra.signal?.aborted)
-            return cancelledDuringAttach(id);
         if (!sub.eventTypes)
             return unattached(id, Date.now() - started);
+        const connection = sub.connected ? sub.connectionVersion : undefined;
+        const needsReconciliation = sub.needsReconciliation({ since, limit });
+        const recovered = needsReconciliation ? await reconcile(session, id, extra.signal) : {};
+        if (extra.signal?.aborted) {
+            return refused(`Cancelled while reading events on ${id}. Buffered events remain available on the next ` +
+                `call. ` +
+                (connectionNote(sub, connection) || 'The stream is still open and buffering.'));
+        }
+        const after = sub.state;
+        if (after.status === 'stopped') {
+            return stopped(session, id, after.reason, sub, { since, limit });
+        }
         const d = sub.read({ since, limit });
-        const extras = d.loss ? await reconcile(session, id, extra.signal) : {};
+        const extras = d.loss ? recovered : {};
+        const interruption = connectionNote(sub, connection);
+        if (interruption) {
+            return said(interruption + (d.loss ? reconciled(extras) : ''), {
+                ...body(id, d, sub, sub.watching),
+                ...extras,
+            });
+        }
         if (!d.events.length) {
             // The one case where "this is an answer rather than a gap" is exactly
             // wrong: a gap whose surviving events were all read already leaves an
@@ -1062,16 +1352,16 @@ export const registerEvents = (server, session) => {
             // either way; the sentence has to agree with it.
             if (d.loss) {
                 return said(`Nothing new on ${id} that survived — there is a hole in the history here, and what ` +
-                    `was in it is gone. See lost for what is known about it, and windows_now and ` +
-                    `computer_now for where the computer actually stands, which is what the missing ` +
-                    `events would have told you.`, { ...body(id, d, sub.watching), ...extras });
+                    `was in it is gone.${reconciled(extras)}`, { ...body(id, d, sub, sub.watching), ...extras });
             }
             return said(`Nothing new on ${id}. The stream is open and buffering, so this is an answer rather ` +
-                `than a gap: nothing has been reported since you last read.`, { ...body(id, d, sub.watching), ...extras });
+                `than a gap: nothing has been reported since you last read.`, { ...body(id, d, sub, sub.watching), ...extras });
         }
         const kinds = [...new Set(d.events.map((e) => e.type))].join(', ');
         return said(`${d.events.length} event${d.events.length === 1 ? '' : 's'} on ${id}: ${kinds}.` +
-            (d.more ? ` ${d.more} more are buffered — call again for them.` : ''), { ...body(id, d, sub.watching), ...extras });
+            (d.more
+                ? ` ${d.more} more ${d.more === 1 ? 'is' : 'are'} buffered — call again for ${d.more === 1 ? 'it' : 'them'}.`
+                : ''), { ...body(id, d, sub, sub.watching), ...extras });
     }));
 };
 //# sourceMappingURL=events.js.map