@songsid/agend 2.3.0 → 2.3.2-beta.1

package/dist/fleet-manager.js

@@ -1,3 +1,4 @@
+import { WorkingRecoveryCoordinator, WORKING_RECOVERY_KIND, buildWorkingRecoveryPrompt } from "./working-recovery.js";
 import { PUBLIC_TUNNEL_TOKEN_ENV, PUBLIC_TUNNEL_TOKEN_HINT, normalizePublicTunnelToken } from "./public-tunnel-config.js";
 import { humanOwnerObjectId, webHumanOrigin } from "./human-delivery-receipts.js";
 import { SettingsBaselines } from "./settings-baseline.js";
@@ -158,6 +159,7 @@ import { agendVersion } from "./agent-whats-new.js";
 import { OwnerCssStore } from "./web-owner-css-store.js";
 import { ThemeStore } from "./web-theme-store.js";
 import { OfficeStore, OfficeWriteLimiter } from "./web-office-store.js";
+import { OfficeSkinStore } from "./web-office-skins.js";
 import { WebAppearance } from "./web-appearance.js";
 import { WebEffectLibrary } from "./web-effect-library.js";
 import { WebEffectTrials } from "./web-effect-trials.js";
@@ -217,6 +219,8 @@ import { assertExplicitInstanceRemoval } from "./instance-removal.js";
 import { KNOWN_BACKENDS, validateFleetConfig } from "./config-validator.js";
 import { isRemovedBackend, removedBackendMessage } from "./backend/removed.js";
 import { presentationState, interactionSummary, sameInteractionOwner } from "./interaction-observation.js";
+import { describeSelfOom } from "./session-oom.js";
+import { assertNoSessionOomStop, readSessionOomStop, captureSessionOomRetry, clearSessionOomStopForRetry, SessionOomStoppedError, sessionOomStopHint } from "./session-oom-stop.js";
 import { idleGateTimeoutLog } from "./idle-gate-log.js";
 import { DEFAULT_STUCK_TIMEOUT_MS, readLastInboundAt } from "./daemon.js";
 import { clearPausedMarker, readPausedAt, readPauseReason, writePausedMarker } from "./pause-marker.js";
@@ -460,6 +464,7 @@ const EFFORT_SELECT_CALLBACK_PREFIX = "effort-select:";
 const BACKEND_SELECT_CALLBACK_PREFIX = "backend-select:";
 const INTERACTIVE_ASSIST_CALLBACK_PREFIX = "interactive-assist:";
 const EXIT_RESTART_CALLBACK_PREFIX = "exit-restart:";
+const OOM_RETRY_CALLBACK_PREFIX = "oom-retry:";
 /** #1386: how long a paused instance's marker reason is reused before it is read again (transitions drop it at once). */
 const NEEDS_PAUSE_TTL_MS = 10_000;
 const HANG_CALLBACK_PREFIX = "hang:";
@@ -471,7 +476,7 @@ const CLEAR_CONFIRM_CALLBACK_PREFIX = "clear-confirm:";
  * group's approval, tips, and the per-user /model and /effort menus (which are not nonce entries at all).
  */
 const WEB_MIRRORED_PROMPT_PREFIXES = new Set([
-    HANG_CALLBACK_PREFIX, EXIT_RESTART_CALLBACK_PREFIX, INTERACTIVE_ASSIST_CALLBACK_PREFIX,
+    HANG_CALLBACK_PREFIX, EXIT_RESTART_CALLBACK_PREFIX, OOM_RETRY_CALLBACK_PREFIX, INTERACTIVE_ASSIST_CALLBACK_PREFIX,
 ]);
 /**
  * Where a reply goes on a fleet with no chat platform (web track C4): it is "sent" by being shown in the
@@ -602,6 +607,89 @@ export class FleetManager {
     managerBootId = randomUUID();
     deliveryOutbox = null;
     deliveryOutboxRecovered = false;
+    workingRecovery = null;
+    workingRecoveryTimer = null;
+    workingRecoveryCause = "unknown_interruption";
+    recoveryEnabled(name) {
+        const own = this.fleetConfig?.instances[name]?.resume_interrupted_work;
+        return own ?? this.fleetConfig?.defaults?.resume_interrupted_work ?? true;
+    }
+    initializeWorkingRecovery(outbox) {
+        const store = outbox.workingRecovery;
+        this.workingRecoveryCause = store.beginRun(this.managerBootId, process.pid, Date.now());
+        this.workingRecovery = new WorkingRecoveryCoordinator({
+            store, now: () => performance.now(), active: () => this.startupComplete && !this.shuttingDown && outbox.isOpen,
+            pressure: () => {
+                const p = this.memoryPressure.snapshot();
+                return p.sampledAt === null || Date.now() - p.sampledAt > 60_000 ? { ...p, level: "unknown" } : p;
+            }, storm: () => this.stormWindow.isActive(),
+            enabled: name => this.recoveryEnabled(name),
+            live: name => {
+                const daemon = this.daemons.get(name);
+                if (this.sessionOomStopped(name))
+                    return { owner: "", configuration: "", sessionId: null, idle: false,
+                        paused: false, stopped: true, legacyPending: false, legacyCovered: false, nativeWork: false, cancelled: false, background: null };
+                return daemon?.getWorkingRecoveryState?.() ?? null;
+            },
+            card: id => this.scheduler?.db.board.findCard(id) ?? (this.scheduler ? undefined : null),
+            laneFree: name => !this.isInstanceRestarting(name) && !this.activeDurableTargets.has(name)
+                && outbox.countForTarget(name, ["queued", "retry_wait", "delivering", "submission_started", "reconciliation_pending"]) === 0,
+            admit: (episode, tasks, advisory) => outbox.admitWorkingRecovery(episode, buildWorkingRecoveryPrompt(tasks, this.workingRecoveryCause, advisory), advisory),
+            summary: (group, rows) => {
+                const general = this.findGeneralInstance();
+                if (!general || !this.daemons.has(general))
+                    return;
+                // Our own informational notice must not supersede General's recovery
+                // as unrelated pending work before it crosses the input boundary.
+                const generalEpisode = store.get(general);
+                if (generalEpisode?.outcome === "admitted" && generalEpisode.deliveryId) {
+                    const state = outbox.get(generalEpisode.deliveryId)?.state;
+                    if (!state || !["delivered", "uncertain", "failed", "cancelled"].includes(state))
+                        return;
+                }
+                const deferredAdvisories = rows.filter(row => row.outcome === "deferred"
+                    && (this.daemons.get(row.instance)?.getWorkingRecoveryState?.().background ?? null) === null)
+                    .map(row => `${row.instance} (${row.reason})`);
+                store.summary(group, () => outbox.admitSystemNotice(general, `working-recovery-summary:${group}`, `[system:working-recovery-summary] Observed cause: unknown interruption${this.workingRecoveryCause === "unknown_interruption" ? "" : `; prior requested action: ${this.workingRecoveryCause}`}. ${rows.length} interrupted instances; continuation queued ${rows.filter(r => r.outcome === "admitted").length}, excluded ${rows.filter(r => r.outcome === "excluded").length}, still deferred ${rows.filter(r => r.outcome === "deferred").length}. ${rows.filter(r => r.reason === "advisory_background_unknown").length ? `Advisory, background unknown: ${rows.filter(r => r.reason === "advisory_background_unknown").map(r => r.instance).join(", ")}. ` : ""}${deferredAdvisories.length ? `Deferred advisory candidates (background unknown; all other gates still apply): ${deferredAdvisories.join(", ")}. ` : ""}Details are in the Log. Deferred work remains eligible; no action or confirmation is requested.`));
+            },
+            log: (episode, outcome, reason) => {
+                const requestedAction = this.workingRecoveryCause === "unknown_interruption" ? null : this.workingRecoveryCause;
+                this.logger.info({ name: episode.instance, episode: episode.key, outcome, reason,
+                    observedCause: "unknown_interruption", requestedAction }, "Interrupted work recovery decision");
+                this.eventLog?.insert(episode.instance, "working_state", {
+                    message: `Interrupted work: ${outcome} (${reason}); observed cause unknown_interruption${requestedAction ? `; prior requested action ${requestedAction}` : ""}.`,
+                    reason, outcome, observedCause: "unknown_interruption", requestedAction
+                });
+            },
+        });
+        if (this.workingRecoveryTimer)
+            clearInterval(this.workingRecoveryTimer);
+        this.workingRecoveryTimer = setInterval(() => {
+            if (!outbox.isOpen || this.shuttingDown)
+                return;
+            try {
+                this.workingRecovery?.tick();
+                this.scheduleDeliveryOutboxPump();
+            }
+            catch {
+                this.logger.warn("Working recovery deferred: prerequisites or durable store unavailable");
+            }
+        }, 1_000);
+        this.workingRecoveryTimer.unref?.();
+    }
+    recoveryDeliveryEligible(row, writing = false) {
+        if (row.kind !== WORKING_RECOVERY_KIND)
+            return true;
+        const outbox = this.deliveryOutbox, episode = outbox?.workingRecovery.get(row.targetInstance);
+        if (!episode || episode.deliveryId !== row.deliveryId
+            || outbox.hasOtherPendingWork(row.targetInstance, row.deliveryId)
+            || this.workingRecovery?.verdict(episode).outcome === "excluded") {
+            outbox?.withdrawWorkingRecovery(row.deliveryId, "recovery superseded or no longer authorized before input");
+            return false;
+        }
+        return (writing ? this.workingRecovery?.accepts(row.targetInstance, episode.key)
+            : this.workingRecovery?.canDispatch(row.targetInstance, episode.key)) === true;
+    }
     /** Phase 2b: wakes paused targets for queued durable work (delivery_worker ≠ off). */
     wakeCoordinator = null;
     /**
@@ -759,6 +847,8 @@ export class FleetManager {
      * backend outage during a post-update herd). instanceName → pending retry.
      */
     startupRetries = new Map();
+    /** #2484: instances whose automatic startup retry is running now (between its timer and its outcome). */
+    startupRetriesRunning = new Set();
     /** Bumped by every explicit stop (incl. the stop half of a restart); fences the outage hand-off. */
     explicitStopGeneration = new Map();
     /** instanceName → outage hand-off currently executing; a repeat joins it. */
@@ -1049,7 +1139,12 @@ export class FleetManager {
     }
     officeStoreInstance;
     /** Fleet → Org chart → Office: the offices people made (web-offices.json, beside web-themes.json). */
-    get officeStore() { return (this.officeStoreInstance ??= new OfficeStore(this.dataDir)); }
+    get officeStore() { return (this.officeStoreInstance ??= new OfficeStore(this.dataDir, id => this.officeSkins.pack(id))); }
+    officeSkinsInstance;
+    /** #2513: the Office view's uploaded skin packs (<AGEND_HOME>/web-office-skins/). */
+    get officeSkins() { return (this.officeSkinsInstance ??= new OfficeSkinStore(this.dataDir)); }
+    /** How often a person may upload or delete a skin pack; memory only, as the offices' limiter. */
+    officeSkinWrites = new OfficeWriteLimiter(undefined, { perWindow: 10, windowMs: 60_000 });
     /** How often a person may save the offices (PUT /ui/offices); memory only, as the appearance limiter. */
     officeWrites = new OfficeWriteLimiter();
     /** #1629: the theme tools, a person's reset and lock, and the one appearance rate limiter (shared with effects). */
@@ -1792,7 +1887,7 @@ export class FleetManager {
                     ...(web && by.guest ? { web_guest: "1" } : {}), // #1920: "[user:… via web (guest), id:…]", as /ui/send
                     ...reactions.meta,
                 },
-            }, by.humanOrigin, button.label)) !== false;
+            }, by.humanOrigin, button.label, this.startRetryHoldFor(set.instance, inbound))) !== false;
         }
         finally {
             // Both false and throw reopen the choice in the controller. Finish the
@@ -1841,8 +1936,19 @@ export class FleetManager {
         }
         this.deliveryOutbox = outbox;
         this.deliveryOutboxRecovered = true;
+        this.initializeWorkingRecovery(outbox);
+        outbox.on("working_references", (names) => {
+            for (const name of names)
+                this.observeWorkingState(name, "obligations");
+        });
         outbox.on("admitted", () => { this.scheduleDeliveryOutboxPump(); this.wakeCoordinator?.kick(); });
         outbox.on("state", (event) => {
+            if (event.deliveryId) {
+                const row = outbox.get(event.deliveryId);
+                if (row)
+                    for (const name of new Set([row.sourceInstance, row.targetInstance]))
+                        this.observeWorkingState(name, "obligations");
+            }
             this.scheduleDeliveryOutboxPump();
             this.wakeCoordinator?.kick();
             if (event.deliveryId && event.state === "delivered") {
@@ -2001,8 +2107,19 @@ export class FleetManager {
                 : item),
         };
     }
+    /** A terminal OOM stop is not an auto-wakeable pause, including after a fleet restart. */
+    sessionOomStopped(name) {
+        return this.daemons.get(name)?.isSessionOomStopped?.() === true || readSessionOomStop(this.getInstanceDir(name)).blocked;
+    }
+    sessionOomStopReason(name) {
+        const state = readSessionOomStop(this.getInstanceDir(name));
+        return state.blocked ? sessionOomStopHint(state)
+            : this.daemons.get(name)?.notAcceptingReason?.() ?? sessionOomStopHint();
+    }
     /** #1641: why a target is not taking queued work right now, or null when nothing known holds it. */
     deliveryWaitingReason(target) {
+        if (this.sessionOomStopped(target))
+            return this.sessionOomStopReason(target);
         if (this.lifecycle.isPaused(target))
             return t("delivery.hold_state", "paused");
         return this.daemons.get(target)?.notAcceptingReason?.() ?? null;
@@ -2015,6 +2132,9 @@ export class FleetManager {
     }
     /** Called after a replacement Daemon object is installed in lifecycle.daemons. */
     onDaemonReady(name, daemonBootId) {
+        const daemon = this.daemons.get(name);
+        if (daemon?.bootId === daemonBootId)
+            this.listenForWorkingState(name, daemon);
         const outbox = this.deliveryOutbox;
         if (!outbox)
             return;
@@ -2038,6 +2158,86 @@ export class FleetManager {
         }
         this.scheduleDeliveryOutboxPump();
     }
+    workingStateListeners;
+    workingStateErrors;
+    /** Attach only to the published owner. Nothing here sends or resumes work. */
+    listenForWorkingState(name, daemon) {
+        if (typeof daemon.getWorkingStateObservation !== "function")
+            return;
+        this.workingStateListeners ??= new WeakSet();
+        if (this.workingStateListeners.has(daemon))
+            return;
+        this.workingStateListeners.add(daemon);
+        daemon.on("working_state", (event) => {
+            try {
+                if (this.daemons.get(name) !== daemon || !sameInteractionOwner(event.observation.owner, daemon.getInteractionSnapshot().owner))
+                    return;
+                this.observeWorkingState(name, event.reason, event.observation);
+            }
+            catch { /* A malformed/stale observation cannot affect the daemon. */ }
+        });
+        this.observeWorkingState(name, "published");
+    }
+    observeWorkingState(name, reason, supplied) {
+        const outbox = this.deliveryOutbox, daemon = this.daemons.get(name);
+        if (!outbox || !daemon || typeof daemon.getWorkingStateObservation !== "function")
+            return;
+        try {
+            const observation = supplied ?? daemon.getWorkingStateObservation();
+            if (!sameInteractionOwner(observation.owner, daemon.getInteractionSnapshot().owner))
+                return;
+            const references = [];
+            const unavailable = [];
+            let totalReferences = 0;
+            const board = this.scheduler?.db.board;
+            if (!board)
+                unavailable.push("tasks");
+            else
+                try {
+                    const tasks = board.listCards({ assignee: name, status: ["claimed", "blocked", "review"], limit: 16 });
+                    totalReferences += tasks.total;
+                    for (const card of tasks.cards)
+                        references.push({ kind: "task", id: card.uuid, version: card.version,
+                            status: card.status });
+                }
+                catch {
+                    unavailable.push("tasks");
+                }
+            try {
+                const obligations = outbox.workingObligations(name);
+                references.push(...obligations.references);
+                totalReferences += obligations.total;
+            }
+            catch {
+                unavailable.push("obligations");
+            }
+            const entry = outbox.observeWorkingState(name, { version: 1, reason, observedAt: Date.now(), observation,
+                lastActivityAt: this.lastActivity.get(name) ?? null, references, totalReferences, unavailable });
+            if (!entry)
+                return;
+            if (reason === "cancelled")
+                outbox.workingRecovery.cancel(name, observation.configuration, observation.sessionId);
+            if (entry.prior)
+                outbox.workingRecovery.discover(name, entry.prior);
+            const state = entry.current.observation.executionState ?? "unknown";
+            const counts = { tasks: entry.current.references.filter(r => r.kind === "task").length,
+                owed: entry.current.references.filter(r => r.kind === "owed").length,
+                waiting: entry.current.references.filter(r => r.kind === "waiting").length,
+                background: entry.current.observation.backgroundWork,
+                total: entry.current.totalReferences, unavailable: entry.current.unavailable };
+            this.logger.info({ name, state, reason, revision: entry.revision, ...counts }, "Working-state journal observed");
+            this.eventLog?.insert(name, "working_state", { state, reason, revision: entry.revision, ...counts,
+                message: `Observed ${state}; tasks ${counts.tasks}, replies owed ${counts.owed}, waiting ${counts.waiting}; ${counts.total} references${counts.background === true ? "; background work running" : ""}${unavailable.length ? "; some sources unavailable" : ""}. Journal only; no recovery action.` });
+            this.emitSseEvent("steps_tick", { instance: name });
+        }
+        catch {
+            this.workingStateErrors ??= new Set();
+            if (!this.workingStateErrors.has(name)) {
+                this.workingStateErrors.add(name);
+                this.logger.warn({ name }, "Could not persist working-state observation; delivery and restart behavior unchanged");
+            }
+        }
+    }
     /**
      * #926: the two reply-obligation safety nets. Idle owners with an unanswered
      * request get one reminder (after the grace); requesters get one overdue
@@ -2112,7 +2312,7 @@ export class FleetManager {
                 // Phase 2c: a lane a queue worker owns is never claimed here.
                 target => this.queueWorkers.has(target) || this.isInstanceRestarting(target) || this.wakeCoordinator?.blocksClaim(target)
                     ? null
-                    : this.daemons.get(target)?.bootId ?? null, this.activeDurableTargets);
+                    : this.daemons.get(target)?.bootId ?? null, this.activeDurableTargets, row => this.recoveryDeliveryEligible(row));
                 if (!claimed)
                     break;
                 this.activeDurableTargets.add(claimed.targetInstance);
@@ -2174,7 +2374,7 @@ export class FleetManager {
             available: () => !this.shuttingDown && this.deliveryOutbox?.isOpen === true,
             blocked: () => this.isInstanceRestarting(target) || this.wakeCoordinator?.blocksClaim(target) === true,
             daemonBootId: () => this.daemons.get(target)?.bootId ?? null,
-            claim: bootId => this.deliveryOutbox?.claimNext(this.managerBootId, candidate => candidate === target ? bootId : null, new Set()),
+            claim: bootId => this.deliveryOutbox?.claimNext(this.managerBootId, candidate => candidate === target ? bootId : null, new Set(), row => this.recoveryDeliveryEligible(row)),
             tryAcquireBudget: () => {
                 if (this.activeDurableTargets.size >= 8)
                     return false;
@@ -2215,7 +2415,24 @@ export class FleetManager {
         // including time spent waiting for a handoff/idle gate to return.
         try {
             let sent;
-            if (claimed.kind === "raw_paste") {
+            if (claimed.kind === WORKING_RECOVERY_KIND) {
+                const daemon = this.daemons.get(target), key = claimed.sourceKey.replace(/^working-recovery:/, "");
+                if (!daemon || typeof payload.content !== "string")
+                    throw new Error("Working recovery owner unavailable");
+                const release = this.workingRecovery?.reserveDispatch(target, key);
+                if (!release) {
+                    outbox.retryBeforeBegin(claimed.deliveryId, daemon.bootId, claimed.attemptNo, "working recovery pace or prerequisites pending", 5_000);
+                    return;
+                }
+                try {
+                    await daemon.deliverWorkingRecovery(payload.content, claimed, () => this.daemons.get(target) === daemon && this.recoveryDeliveryEligible(claimed, true));
+                }
+                finally {
+                    release();
+                }
+                sent = true;
+            }
+            else if (claimed.kind === "raw_paste") {
                 if (payload.type !== "raw_paste" || typeof payload.content !== "string") {
                     throw new Error("Durable raw_paste row has an invalid payload");
                 }
@@ -2899,6 +3116,7 @@ export class FleetManager {
     }
     /** SIGUSR1: full process reload. Names who asked (#1120). */
     onFullRestartSignal() {
+        this.recordWorkingRestartIntent("manual_restart");
         this.logger.info(`Received SIGUSR1, initiating full restart (process reload)... ${describeSignalSource(this.dataDir, "SIGUSR1")}`);
         this.gracefulShutdownForReload()
             .then(() => {
@@ -3725,7 +3943,7 @@ export class FleetManager {
                 finish(false);
         });
     }
-    async deliverWithIdleGate(instanceName, payload, timeoutMs, deliveryEpoch, noInlineWake = false, stillCurrent) {
+    async deliverWithIdleGate(instanceName, payload, timeoutMs, deliveryEpoch, noInlineWake = false, stillCurrent, onStartRetryHold) {
         if (this.shuttingDown || !this.deliveryCurrent(instanceName, deliveryEpoch, stillCurrent))
             return false;
         await this.holdDeliveryForStorm(instanceName, deliveryEpoch);
@@ -3764,7 +3982,7 @@ export class FleetManager {
             const log = idleGateTimeoutLog(instanceName, timeoutMs, this.instanceStateCache.get(instanceName), Date.now());
             this.logger[log.level](log.fields, log.message);
         }
-        const sent = await this.sendWhenConnected(instanceName, payload, deliveryEpoch, stillCurrent);
+        const sent = await this.sendWhenConnected(instanceName, payload, deliveryEpoch, stillCurrent, onStartRetryHold);
         if (!sent)
             return false;
         if (this.deliveryCurrent(instanceName, deliveryEpoch, stillCurrent)) {
@@ -3793,8 +4011,11 @@ export class FleetManager {
      * Ordering is preserved by serialising behind any waiter already queued for this
      * instance, *including* when the socket happens to be up: otherwise a message
      * arriving after the reconnect could overtake one that has been waiting for it.
+     *
+     * `onStartRetryHold` (#2484, a person's message): an instance in its own start-retry backoff is waited for until that
+     * retry brings it up, however long the backoff, and fails only once the retries give up.
      */
-    async sendWhenConnected(instanceName, payload, deliveryEpoch = this.getDeliveryEpoch(instanceName), stillCurrent) {
+    async sendWhenConnected(instanceName, payload, deliveryEpoch = this.getDeliveryEpoch(instanceName), stillCurrent, onStartRetryHold) {
         if (!this.deliveryCurrent(instanceName, deliveryEpoch, stillCurrent))
             return false;
         const queued = this.ipcWaitTails.get(instanceName);
@@ -3808,7 +4029,7 @@ export class FleetManager {
             .then(() => {
             if (!this.deliveryCurrent(instanceName, deliveryEpoch, stillCurrent))
                 return false;
-            return this.sendAfterIpcReturns(instanceName, payload, deliveryEpoch, stillCurrent);
+            return this.sendAfterIpcReturns(instanceName, payload, deliveryEpoch, stillCurrent, onStartRetryHold);
         });
         // The chain stores a settled-either-way promise so one failed delivery cannot
         // wedge every later one, and so `queued` above is safe to await unguarded.
@@ -3826,9 +4047,10 @@ export class FleetManager {
         }
     }
     /** Poll for the instance's IPC to come back, then send. Throws if it does not. */
-    async sendAfterIpcReturns(instanceName, payload, deliveryEpoch = this.getDeliveryEpoch(instanceName), stillCurrent) {
-        const deadline = Date.now() + IPC_RECONNECT_GRACE_MS;
+    async sendAfterIpcReturns(instanceName, payload, deliveryEpoch = this.getDeliveryEpoch(instanceName), stillCurrent, onStartRetryHold) {
+        let deadline = Date.now() + IPC_RECONNECT_GRACE_MS;
         let warned = false;
+        let held = false;
         for (;;) {
             if (!this.deliveryCurrent(instanceName, deliveryEpoch, stillCurrent))
                 return false;
@@ -3837,6 +4059,22 @@ export class FleetManager {
             const ipc = this.instanceIpcClients.get(instanceName);
             if (ipc?.connected && ipc.send(this.bindHumanReceiptPayload(instanceName, payload)))
                 return true;
+            // #2484: while the instance waits for (or runs) its own start retry, the grace runs from now — so the message is
+            // delivered once a retry brings it up, and fails only after the retries stop (they gave up, or a person stopped
+            // or paused it) and a last grace passes without it.
+            if (onStartRetryHold && this.inStartRetryBackoff(instanceName)) {
+                deadline = Math.max(deadline, Date.now() + IPC_RECONNECT_GRACE_MS);
+                if (!held) {
+                    held = true;
+                    this.logger.info({ instanceName, retry: this.startupRetries.get(instanceName)?.attempt }, "Instance is waiting for its start retry — holding the message until it is up");
+                    try {
+                        onStartRetryHold();
+                    }
+                    catch (err) {
+                        this.logger.debug({ err, instanceName }, "Start-retry hold notice failed");
+                    }
+                }
+            }
             if (Date.now() >= deadline) {
                 throw new Error(`Instance '${instanceName}' IPC is unavailable`);
             }
@@ -4222,6 +4460,18 @@ export class FleetManager {
                 this.deliveryOutbox?.markHumanReceiptUncertain(id, instanceName);
         }
     }
+    /**
+     * #2484: a person's message waits for its instance's own start retry (DeliveryOptions.onStartRetryHold), shown as
+     * queued on the message meanwhile. A ClassicBot room message (no `msg`) has no delivery-status reactions: it only waits.
+     */
+    startRetryHoldFor(instanceName, msg) {
+        return {
+            onStartRetryHold: () => {
+                if (msg?.chatId && msg.messageId)
+                    this.reactMessageStatus(instanceName, msg.chatId, msg.messageId, "queued", msg.threadId || undefined);
+            },
+        };
+    }
     /** Synchronous steer/btw handoff, using the same evidence and owner binding. */
     sendHumanControl(instanceName, payload, origin, originalBody) {
         const ipc = this.instanceIpcClients.get(instanceName);
@@ -4262,7 +4512,7 @@ export class FleetManager {
                     return false;
                 this.enforceWarmCap(instanceName); // woke one → evict a different LRU idle if over cap
             }
-            const sent = await this.sendWhenConnected(instanceName, deliveryPayload, deliveryEpoch, options.stillCurrent);
+            const sent = await this.sendWhenConnected(instanceName, deliveryPayload, deliveryEpoch, options.stillCurrent, options.onStartRetryHold);
             if (!sent)
                 return false;
             // A cross-instance item arriving before the daemon observes this turn as
@@ -4273,7 +4523,7 @@ export class FleetManager {
             return true;
         }
         const previous = this.idleGatedDeliveryTails.get(instanceName) ?? Promise.resolve();
-        const delivery = previous.catch(() => { }).then(() => this.deliverWithIdleGate(instanceName, deliveryPayload, options.idleTimeoutMs ?? 60_000, deliveryEpoch, options.noInlineWake === true, options.stillCurrent));
+        const delivery = previous.catch(() => { }).then(() => this.deliverWithIdleGate(instanceName, deliveryPayload, options.idleTimeoutMs ?? 60_000, deliveryEpoch, options.noInlineWake === true, options.stillCurrent, options.onStartRetryHold));
         this.idleGatedDeliveryTails.set(instanceName, delivery);
         try {
             return await delivery;
@@ -4729,8 +4979,8 @@ export class FleetManager {
         return new WakeCoordinator({
             mode: target => this.deliveryWorkerMode(target),
             available: () => !this.shuttingDown && this.deliveryOutbox?.isOpen === true,
-            listPending: () => this.deliveryOutbox?.listPending() ?? [],
-            isPaused: target => this.lifecycle.isPaused(target),
+            listPending: () => this.deliveryOutbox?.listPending().filter(row => row.kind !== WORKING_RECOVERY_KIND) ?? [],
+            isPaused: target => !this.sessionOomStopped(target) && this.lifecycle.isPaused(target),
             pauseReason: target => readPauseReason(this.getInstanceDir(target)),
             isRestarting: target => this.isInstanceRestarting(target),
             wake: async (target) => {
@@ -4742,7 +4992,7 @@ export class FleetManager {
             warmCap: () => this.fleetConfig?.defaults?.warm_cap ?? 0,
             warmOverflow: () => this.fleetConfig?.defaults?.warm_overflow ?? DEFAULT_WARM_OVERFLOW,
             wokeAt: target => this.lifecycle.wokeAtFor(target),
-            notAcceptingReason: target => this.daemons.get(target)?.notAcceptingReason?.() ?? null,
+            notAcceptingReason: target => this.sessionOomStopped(target) ? this.sessionOomStopReason(target) : this.daemons.get(target)?.notAcceptingReason?.() ?? null,
             notifyTarget: (target, text) => { this.notifyInstanceTopic(target, text); },
             notifySender: (source, text) => { this.notifyInstanceTopic(source, text); },
             kickPump: () => this.scheduleDeliveryOutboxPump(),
@@ -4797,7 +5047,12 @@ export class FleetManager {
      * is exactly the old lifecycle wake; otherwise it goes through the shared
      * slot admission and joins any wake already in flight for the target.
      */
-    async explicitWake(name, timeoutMs = 30_000) {
+    async explicitWake(name, timeoutMs = 30_000, retryStoppedSession = false) {
+        if (this.sessionOomStopped(name)) {
+            if (!retryStoppedSession)
+                throw new SessionOomStoppedError(false, readSessionOomStop(this.getInstanceDir(name)));
+            return this.restartSingleInstance(name, { explicit: true });
+        }
         const token = await this.acquireWakeSlot(name);
         try {
             await this.lifecycle.wake(name, timeoutMs);
@@ -4818,7 +5073,7 @@ export class FleetManager {
     }
     async changeInstancePauseState(name, action) {
         if (action === "wake") {
-            await this.explicitWake(name, 30_000);
+            await this.explicitWake(name, 30_000, true);
             this.enforceWarmCap(name); // manual wake still respects the fleet warm cap
             return "awake";
         }
@@ -4994,6 +5249,11 @@ export class FleetManager {
     /** Phase 2a: the caller's transition, for a start made from inside a restart or wake. */
     transition, execution) {
         execution?.assert();
+        if (this.sessionOomStopped(name)) {
+            if (resumePaused)
+                return this.restartSingleInstance(name, { explicit: true });
+            throw new SessionOomStoppedError(false, readSessionOomStop(this.getInstanceDir(name)));
+        }
         // CLI single-instance cold starts bypass startAll. Start diagnostics before
         // any lifecycle/wake work; a shutdown must not revive the stopped sampler.
         if (!this.shuttingDown)
@@ -5002,7 +5262,7 @@ export class FleetManager {
         // into a running instance — harmless, but noisy — or race this start).
         this.cancelStartupRetry(name);
         if (resumePaused && this.lifecycle.isPaused(name)) {
-            await this.explicitWake(name, 30_000);
+            await this.explicitWake(name, 30_000, true);
             // A successful wake clears the persisted pause marker and produces a
             // fresh instance_state snapshot.  Drop any stale process error left by a
             // pre-pause crash so /api/fleet and `agend ls` converge on running.
@@ -5022,7 +5282,7 @@ export class FleetManager {
             if (resumePaused) {
                 const status = this.getInstanceStatus(name);
                 if (status === "crashed" || status === "stopped") {
-                    await this.restartSingleInstance(name);
+                    await this.restartSingleInstance(name, { explicit: true });
                     return;
                 }
             }
@@ -5197,6 +5457,8 @@ export class FleetManager {
             // outcome. Retrying would start an instance the operator just stopped.
             if (err instanceof SupersededStartError)
                 return false;
+            if (err instanceof SessionOomStoppedError)
+                await this.notifySessionOomStop(name);
             if (this.stopOnUnsupportedCli(name, err, what))
                 return false;
             this.logger.error({ err, name }, `Failed to start ${what}`);
@@ -5217,6 +5479,11 @@ export class FleetManager {
     scheduleStartupRetry(name, attempt) {
         if (this.shuttingDown)
             return;
+        if (this.sessionOomStopped(name)) {
+            this.instanceProcessStatus.set(name, "stopped");
+            this.logger.warn({ name }, this.sessionOomStopReason(name));
+            return;
+        }
         if (this.startupRetries.has(name))
             return;
         const backoff = FleetManager.STARTUP_RETRY_BACKOFF_MS;
@@ -5244,6 +5511,12 @@ export class FleetManager {
         this.startupRetries.delete(name);
         this.logger.info({ name }, "Pending automatic startup retry cancelled");
     }
+    /** #2484: the instance's own start retry is scheduled or running, and no person paused it (a stop cancels the retry). */
+    inStartRetryBackoff(name) {
+        if (this.shuttingDown || this.lifecycle.isPaused(name))
+            return false;
+        return this.startupRetries.has(name) || this.startupRetriesRunning.has(name);
+    }
     /** Pending automatic retry, if any (status display / tests). */
     pendingStartupRetry(name) {
         const pending = this.startupRetries.get(name);
@@ -5294,6 +5567,8 @@ export class FleetManager {
         this.startupRetries.delete(name);
         if (this.shuttingDown)
             return;
+        if (this.sessionOomStopped(name))
+            return;
         if (!this.isConfiguredInstance(name))
             return; // removed from fleet.yaml / classic channel meanwhile
         if (this.lifecycle.isPaused(name) || this.daemons.has(name))
@@ -5309,6 +5584,7 @@ export class FleetManager {
         }
         const topicMode = this.fleetConfig?.channel?.mode === "topic"
             || !!this.fleetConfig?.channels?.some(channel => channel.mode === "topic");
+        this.startupRetriesRunning.add(name);
         try {
             await this.spawnGate.run({
                 instanceName: name,
@@ -5330,6 +5606,9 @@ export class FleetManager {
             this.logger.error({ err, name, attempt: attempt + 1 }, "Automatic startup retry failed");
             this.scheduleStartupRetry(name, attempt + 1);
         }
+        finally {
+            this.startupRetriesRunning.delete(name);
+        }
     }
     /** Fleet-topic (fleet.yaml) or ClassicBot (classic channel) — both are retryable; anything else is gone. */
     isConfiguredInstance(name) {
@@ -5655,12 +5934,29 @@ export class FleetManager {
     }
     /** Restart a single instance, reloading fleet.yaml first to pick up config changes. */
     async restartSingleInstance(name, opts) {
+        if (opts?.recoveryCurrent && !opts.recoveryCurrent())
+            throw new Error(t("exit.expired", name));
+        const retry = opts?.explicit ? opts.sessionOomRetry ?? captureSessionOomRetry(this.getInstanceDir(name)) : undefined;
+        if (opts?.sessionOomRetry) {
+            const current = captureSessionOomRetry(this.getInstanceDir(name));
+            // An unclear-cause stop intentionally has no tombstone. Only its live
+            // launch fence can authorize an absent-marker receipt; positive stops
+            // still require the offered durable revision.
+            if ((!retry?.revision && !opts.recoveryCurrent) || current.revision !== retry?.revision || current.legacyRevision !== retry?.legacyRevision)
+                throw new SessionOomStoppedError(true);
+        }
+        if (!opts?.explicit && this.sessionOomStopped(name))
+            throw new SessionOomStoppedError(false, readSessionOomStop(this.getInstanceDir(name)));
         // One restart at a time per instance. Multiple sources can ask concurrently
         // (MCP revival, /restart, pty_error, model failover); a second stop/start
         // interleaved with the first tears down the window the first just created.
         // Later callers join the in-flight restart instead — its opts win.
         const inFlight = this.restartsInFlight.get(name);
         if (inFlight) {
+            // Do not let a late explicit caller clear a stop belonging to the
+            // automatic flight it would join. That action must be retried afterwards.
+            if (retry && this.sessionOomStopped(name))
+                throw new SessionOomStoppedError(true);
             this.logger.info({ name }, "restartSingleInstance: joining the restart already in flight");
             // #1753: a credential-profile switch joining it still needs its conversation carried in that restart's stop →
             // start gap: handed to the restart while it has not reached the gap (and carries nothing else); otherwise not
@@ -5687,7 +5983,7 @@ export class FleetManager {
             workingDirectory,
             reason: "restart",
             stage: "lifecycle",
-        }, () => this.doRestartSingleInstance(name, opts, transition)))
+        }, () => this.doRestartSingleInstance(name, opts, transition, retry)))
             .finally(() => {
             this.restartsInFlight.delete(name);
             if (this.restartGaps.get(name) === gap)
@@ -5728,7 +6024,7 @@ export class FleetManager {
             this.lifecycle.clearActivitySeedNow(name);
         }
     }
-    async doRestartSingleInstance(name, opts, transition) {
+    async doRestartSingleInstance(name, opts, transition, retry) {
         if (this.configPath) {
             this.loadConfig(this.configPath);
             this.routing.rebuild(this.fleetConfig);
@@ -5746,7 +6042,7 @@ export class FleetManager {
         if (!wasPaused)
             this.restartsHoldingSlot.add(name);
         try {
-            await this.doRestartWithSlot(name, opts, transition, config, wasPaused);
+            await this.doRestartWithSlot(name, opts, transition, config, wasPaused, retry);
             // An explicit restart of a paused instance is an operator wake (§1.6):
             // its success lifts the coordinator's park/backoff (the level stays).
             // Automatic restarts never do.
@@ -5758,7 +6054,7 @@ export class FleetManager {
             this.releaseWakeSlot(name, slot);
         }
     }
-    async doRestartWithSlot(name, opts, transition, config, wasPaused) {
+    async doRestartWithSlot(name, opts, transition, config, wasPaused, retry) {
         const pausedAt = wasPaused ? (this.lifecycle.getLastPausedAt(name) ?? readPausedAt(this.getInstanceDir(name))) : null;
         const pauseReason = wasPaused ? readPauseReason(this.getInstanceDir(name)) : null;
         // #1753: the directory the CLI being stopped was launched in — its conversation is under that directory's key.
@@ -5766,6 +6062,12 @@ export class FleetManager {
         // Between the stop and the start: the old CLI's transcript is complete, the new one has not looked yet.
         /** `launching`: the login the start will use — read only when a switch is to be carried. */
         const betweenStopAndStart = async (launching) => {
+            // Clearing is synchronous, after the old daemon is stopped and inside
+            // this action's serialized transition; an unseen later stop is retained.
+            if (retry)
+                clearSessionOomStopForRetry(this.getInstanceDir(name), retry);
+            else
+                assertNoSessionOomStop(this.getInstanceDir(name));
             // #1753: this restart's own carry, or one a caller joined it with before this point (restartSingleInstance).
             const gap = this.restartGaps.get(name);
             const carry = gap?.carry ?? opts?.carry;
@@ -6533,7 +6835,8 @@ export class FleetManager {
                 const [adapterId, userId] = k.split("\u0000");
                 accounts.set(k, { adapterId, userId, sessions: 0, lastSeen: null });
             }
-        for (const key of Object.keys(cfg?.narrow ?? {})) {
+        // #2348: every granted account is listed too, signed in or not.
+        for (const key of [...Object.keys(cfg?.narrow ?? {}), ...Object.keys(cfg?.grants ?? {})]) {
             const at = key.indexOf(":"), adapterId = key.slice(0, at), userId = key.slice(at + 1), k = `${adapterId}\u0000${userId}`;
             if (at > 0 && !accounts.has(k))
                 accounts.set(k, { adapterId, userId, sessions: 0, lastSeen: null });
@@ -6542,10 +6845,153 @@ export class FleetManager {
             const owner = { adapterId: a.adapterId, userId: a.userId };
             const badge = this.guestBadge(owner);
             // `reach`: before narrowing — what Settings offers to narrow to (#2104 review: never an agent it cannot reach).
+            const grant = own(cfg?.grants, `${a.adapterId}:${a.userId}`);
+            const sent = this.guestCodeSent.get(`${a.adapterId}:${a.userId}`);
             return { ...a, name: badge.name, platform: badge.platform, scope: [...this.guestScope(owner)].sort(), reach: [...this.guestReach(owner)].sort(),
-                devices: devices.get(k) ?? 0, narrow: own(cfg?.narrow, `${a.adapterId}:${a.userId}`) ?? null };
+                devices: devices.get(k) ?? 0, narrow: own(cfg?.narrow, `${a.adapterId}:${a.userId}`) ?? null,
+                // #2348: the grant as fleet.yaml has it (null: none), and the last code an admin sent from Settings.
+                grant: grant ? { ...(grant.name ? { name: grant.name } : {}), instances: [...grant.instances] } : null,
+                ...(sent ? { code: { at: sent.at, outcome: sent.outcome.kind, ...(sent.outcome.kind === "sent" ? { expiresAt: sent.at + sent.outcome.expiresInMs } : {}),
+                        ...(sent.outcome.kind === "dm_failed" ? { reason: sent.outcome.reason, platform: sent.outcome.platform, ...(sent.outcome.startUrl ? { startUrl: sent.outcome.startUrl } : {}) } : {}) } } : {}) };
         }).sort((x, y) => (y.lastSeen ?? -1) - (x.lastSeen ?? -1));
-        return { enabled: cfg?.enabled === true, chat: cfg?.chat !== false, instances: Object.keys(this.fleetConfig?.instances ?? {}).sort(), connections, guests };
+        // #2348: `explicit` — grants are the scope (default deny); false: the derived scope of #1920, until grants are saved.
+        return { enabled: cfg?.enabled === true, chat: cfg?.chat !== false, explicit: cfg?.grants !== undefined, instances: Object.keys(this.fleetConfig?.instances ?? {}).sort(), connections, guests,
+            audit: this.guestAudit() };
+    }
+    /**
+     * #2499 review: the guest audit an admin reads — the newest grant changes and admin-sent codes from the event log
+     * (`fleet` rows: no agent's Log shows them). Through guestOverview only: Settings' admin gate, never over the public
+     * link, never a guest's. The person's name as the card shows it; a session handle stays on the server (`by` → whether
+     * a person saved it here or it was confirmed in General).
+     */
+    guestAudit(limit = FleetManager.GUEST_AUDIT_SHOWN) {
+        if (!this.eventLog)
+            return [];
+        // One read, newest first by row id: a total order (created_at is to the second), so the cap never drops a newer row.
+        let rows = [];
+        try {
+            rows = this.eventLog.latestOfTypes("fleet", ["guest_grant_changed", "guest_code_sent"], limit);
+        }
+        catch {
+            return [];
+        }
+        const names = (list) => (Array.isArray(list) ? list.filter((n) => typeof n === "string") : []);
+        return rows.flatMap((r) => {
+            const p = r.payload ?? {}, account = typeof p.account === "string" ? p.account : "";
+            const at = account.indexOf(":");
+            if (at <= 0)
+                return [];
+            const name = this.webPerson({ adapterId: account.slice(0, at), userId: account.slice(at + 1) }).name;
+            const when = Date.parse(r.created_at.includes("T") ? r.created_at : `${r.created_at.replace(" ", "T")}Z`);
+            return r.event_type === "guest_grant_changed"
+                ? [{ kind: "grant", at: when, account, name, via: p.via === "confirmed" ? "confirmed" : "direct", added: names(p.added), removed: names(p.removed),
+                        endedSessions: typeof p.endedSessions === "number" ? p.endedSessions : 0 }]
+                : [{ kind: "code", at: when, account, name, outcome: typeof p.outcome === "string" ? p.outcome : "unknown" }];
+        });
+    }
+    static GUEST_AUDIT_SHOWN = 20;
+    /**
+     * #2348: Settings → Guests' picker — the people AgEnD has seen in chat (seen_people, from human receipts: never a bot,
+     * never the web), without fleet admins (they sign in as admins) or accounts of a connection the fleet no longer has.
+     * Admin only (settings-api.ts), never over the public link.
+     */
+    guestPeople() {
+        const seen = this.deliveryOutbox?.isOpen ? this.deliveryOutbox.seenPeople() : [];
+        const people = seen.filter((p) => this.worlds.has(p.adapterId) && !this.isFleetAdmin(p.userId, p.adapterId)).map((p) => {
+            const owner = { adapterId: p.adapterId, userId: p.userId };
+            return { adapterId: p.adapterId, userId: p.userId, platform: this.worlds.get(p.adapterId)?.adapter.type ?? p.adapterId, username: p.username,
+                name: this.webPerson(owner).name, lastSeen: p.lastSeen, instances: p.instances.map((i) => i.name) };
+        });
+        return { people };
+    }
+    /**
+     * #2348: why this account may not be given a grant, or null. Only someone AgEnD has seen in chat, on a connection the
+     * fleet runs, who is not a fleet admin of it (an admin is never a guest).
+     */
+    guestGrantRefusal(adapterId, userId) {
+        if (!this.worlds.has(adapterId) && !this.fleetConfig?.channels?.some((c) => (c.id ?? c.type) === adapterId))
+            return "no such connection in this fleet";
+        if (this.isFleetAdmin(userId, adapterId))
+            return "a fleet admin signs in as an admin, not as a guest";
+        if (!this.deliveryOutbox?.isOpen || !this.deliveryOutbox.isSeenPerson(adapterId, userId))
+            return "only someone AgEnD has seen in chat can be given guest access";
+        return null;
+    }
+    /**
+     * #2348 delta §5: a grant changed with a save — one event-log entry per person, shown in Settings → Guests' Recent
+     * changes (guestOverview: admin-only, never over the public link or to a guest): who saved it (an admin's
+     * session handle, the header token, or null when replayed for a confirmation), whether it applied at once or was
+     * confirmed in General, the agents added and taken away, and the sessions a removal ended. Never message content.
+     */
+    noteGuestGrantChange(change) {
+        this.logger.info({ account: change.account, via: change.via, added: change.added.length, removed: change.removed.length }, "Guest access changed in Settings");
+        try {
+            this.eventLog?.insert("fleet", "guest_grant_changed", { ...change });
+        }
+        catch { /* the log line stands */ }
+    }
+    /** #2348: an admin's Send sign-in code, per admin (the caller): at most this many in ADMIN_CODE_WINDOW_MS. */
+    static ADMIN_CODE_MAX = 10;
+    static ADMIN_CODE_WINDOW_MS = 10 * 60_000;
+    adminCodeSends = new Map();
+    /** #2348: the last admin-sent code per account, for the Settings card ("Code sent 18:42 · expires 18:52", or why not). */
+    guestCodeSent = new Map();
+    /**
+     * #2348: Settings → Guests' "Send sign-in code" — a guest code to an account an admin granted access, by DM only (no
+     * chat to answer in, nothing posted anywhere). The same issuance as the person's own /web (one code per account, the
+     * code store's caps and breaker, the public link's audience when it is open) and the same once-a-minute limit per
+     * account, plus a per-admin cap. Refused without guest sign-in, for a fleet admin, or with nothing granted. Audited.
+     */
+    async sendGuestCodeByAdmin(owner, by, 
+    /** #2365 review: the initiating admin is still signed in and still an admin (settings-api re-checks the session). */
+    current = () => true) {
+        const guests = this.fleetConfig?.web?.guests;
+        if (guests?.enabled !== true)
+            return { status: 409, body: { ok: false, outcome: "guests_off", error: "Guest sign-in is off" } };
+        if (this.isFleetAdmin(owner.userId, owner.adapterId))
+            return { status: 409, body: { ok: false, outcome: "admin", error: "A fleet admin signs in as an admin" } };
+        if (!this.guestScope(owner).size)
+            return { status: 409, body: { ok: false, outcome: "nothing", error: "Nothing is granted to this person yet: save their access first" } };
+        const token = this.webToken;
+        const adapter = this.adapters.get(owner.adapterId);
+        if (this.shuttingDown || !token || !adapter)
+            return { status: 503, body: { ok: false, outcome: "starting", error: "AgEnD is starting or this connection is not running" } };
+        const key = `${owner.adapterId}\u0000${owner.userId}`, asked = this.guestCodeAskedAt.get(key);
+        const now = performance.now();
+        if (this.guestCodeInFlight.has(key) || (asked !== undefined && now - asked < 60_000)) {
+            return { status: 429, body: { ok: false, outcome: "wait", retryAfterMs: asked !== undefined ? Math.max(0, 60_000 - (now - asked)) : 60_000 } };
+        }
+        const mine = (this.adminCodeSends.get(by) ?? []).filter((at) => now - at < FleetManager.ADMIN_CODE_WINDOW_MS);
+        if (mine.length >= FleetManager.ADMIN_CODE_MAX)
+            return { status: 429, body: { ok: false, outcome: "admin_limit", retryAfterMs: FleetManager.ADMIN_CODE_WINDOW_MS - (now - mine[0]) } };
+        this.adminCodeSends.set(by, [...mine, now]);
+        while (this.adminCodeSends.size > 256)
+            this.adminCodeSends.delete(this.adminCodeSends.keys().next().value);
+        let outcome = { kind: "busy" };
+        this.guestCodeInFlight.add(key);
+        try {
+            await this.issueGuestCode({ replyHere: async () => undefined }, owner, key, adapter, token, (o) => { outcome = o; }, current);
+        }
+        finally {
+            this.guestCodeInFlight.delete(key);
+        }
+        const done = outcome;
+        // #2365 review: the admin's session ended (or stopped being an admin's) while the code was on its way: nothing was
+        // sent, or what was made is withdrawn — the answer says so, as to anyone no longer signed in.
+        if (done.kind === "revoked" && !current())
+            return { status: 401, body: { ok: false, outcome: "revoked", error: "no longer authorized" } };
+        this.guestCodeSent.set(`${owner.adapterId}:${owner.userId}`, { at: Date.now(), outcome: done });
+        while (this.guestCodeSent.size > 512)
+            this.guestCodeSent.delete(this.guestCodeSent.keys().next().value);
+        // Audited: who asked, for whom, what happened (never the code).
+        this.logger.info({ by, adapterId: owner.adapterId, outcome: done.kind }, "Guest sign-in code sent by an admin from Settings");
+        try {
+            this.eventLog?.insert("fleet", "guest_code_sent", { by, account: `${owner.adapterId}:${owner.userId}`, outcome: done.kind, instances: this.guestScope(owner).size });
+        }
+        catch { /* the log line stands */ }
+        const status = done.kind === "sent" ? 200 : done.kind === "dm_failed" ? 502 : 409;
+        return { status, body: { ok: done.kind === "sent", outcome: done.kind, ...(done.kind === "sent" ? { expiresAt: Date.now() + done.expiresInMs, publicLink: done.publicLink } : {}),
+                ...(done.kind === "dm_failed" ? { platform: done.platform, reason: done.reason, ...(done.startUrl ? { startUrl: done.startUrl } : {}) } : {}) } };
     }
     /** #1920 phase 3 (the app shell): a guest's chip — its web name, and its connection's platform (discord, telegram). */
     guestBadge(owner) {
@@ -6614,24 +7060,35 @@ export class FleetManager {
         return true;
     }
     /** guestWebCommand's issuance, one per account at a time; a revoke made meanwhile (either kind) ends it unissued. */
-    async issueGuestCode(ask, owner, key, adapter, token) {
+    async issueGuestCode(ask, owner, key, adapter, token, 
+    /** #2348: how it ended, for a caller with no chat to answer in (Settings → Guests' Send sign-in code). */
+    report = () => { }, 
+    /**
+     * #2365 review: the one who asked may still ask — for an admin's Send sign-in code, that admin's session as it is
+     * now. Asked with the revocation checks, after every wait: false ends the issuance, and withdraws its code if one was made.
+     */
+    stillAllowed = () => true) {
         const say = (text) => ask.replyHere(text).catch(() => undefined);
         const revokes = this.guestRevokes, accountRevokes = this.guestAccountRevokes.get(key) ?? 0;
-        const unrevoked = () => this.guestRevokes === revokes && (this.guestAccountRevokes.get(key) ?? 0) === accountRevokes;
+        const unrevoked = () => this.guestRevokes === revokes && (this.guestAccountRevokes.get(key) ?? 0) === accountRevokes && stillAllowed();
         // §3.2: its rooms are read at sign-in (bounded; never longer than the reads' own deadline).
         await withinBudget(this.refreshGuestRooms(owner, { mode: "force" }), performance.now() + 6_000).catch(() => undefined);
-        if (!unrevoked())
-            return; // revoked while its rooms were read: no code
+        if (!unrevoked()) {
+            report({ kind: "revoked" });
+            return;
+        } // revoked while its rooms were read: no code
         const scope = this.guestScope(owner);
         if (!scope.size) {
             const open = this.worlds.get(owner.adapterId)?.accessManager.getMode() === "open";
             await say(t(open ? "web.guest_not_set_up" : "web.guest_nothing"));
+            report({ kind: "nothing" });
             return;
         }
         this.initializeWebSessions();
         const codes = this.webGuestLoginCodes;
         if (codes.pausedForMs() > 0) {
             await say(t("web.guest_paused"));
+            report({ kind: "paused" });
             return;
         }
         // §5.5 (step 4b): with the public link open, the code works through it too (an admin opened it; a guest is still a
@@ -6642,6 +7099,7 @@ export class FleetManager {
             recipient: { adapterId: owner.adapterId, userId: owner.userId, ...(ask.username ? { username: ask.username } : {}) } });
         if (!login) {
             await say(t("web.guest_busy"));
+            report({ kind: "busy" });
             return;
         }
         this.guestCodeAskedAt.delete(key);
@@ -6676,13 +7134,17 @@ export class FleetManager {
                     throw new Error("guest no longer admitted");
                 await say(t("web.guest_sent"));
             }
+            report({ kind: "sent", expiresInMs: LOGIN_CODE_TTL_MS, publicLink: !!open });
         }
         catch (err) {
             codes.revokeIfCurrent(login.issuanceId); // this flow's code only, never a later one's
             this.logger.info({ err: err?.message, adapterId: owner.adapterId }, "Guest sign-in code was not delivered privately");
-            if (!unrevoked())
-                return; // revoked meanwhile: the revoke's own answer said so
+            if (!unrevoked()) {
+                report({ kind: "revoked" });
+                return;
+            } // revoked meanwhile: the revoke's own answer said so
             const start = adapter.type === "telegram" ? this.tgStartWebUrl(owner.adapterId) : null;
+            report({ kind: "dm_failed", platform: adapter.type, reason: String(err?.message ?? err).slice(0, 200), ...(start ? { startUrl: start } : {}) });
             // #1742 for guests (step 4b-3): its START button (a bare /start, or the link's /start web) then asks again, from
             // the DM — once, within the window.
             if (adapter.type === "telegram")
@@ -7229,6 +7691,7 @@ export class FleetManager {
         const startupStartedAt = Date.now();
         FleetManager.signalTarget = this;
         this.startupComplete = false;
+        this.workingRecovery?.reset();
         this.startupDashboard = null;
         // Cleared here, not at the end of doStopAll: a stop has an async tail, and
         // anything arriving during it is still part of the stop.
@@ -7807,12 +8270,17 @@ export class FleetManager {
         // health server — so `systemctl start` returned success while the fleet was
         // still deaf: no path existed for a user message to arrive.
         sdNotify("READY=1");
+        this.workingRecovery?.ready();
         // #2481: this version runs — the CLI's start-failure banner stops, and this is the version to go back to later.
         try {
             const { ownPackage, recordStarted } = await import("./start-failure.js");
             const version = ownPackage().version;
             if (version)
                 recordStarted(this.dataDir, version, process.pid, Date.now());
+            // #2481: a start completed — the failed tree an automatic restore kept for a report can go.
+            const prefix = ownPackage().prefix;
+            if (prefix)
+                void (await import("./mac-auto-restore.js")).pruneFailedTrees(prefix).catch(() => { });
         }
         catch (err) {
             this.logger.debug({ err }, "fleet-started record not written");
@@ -9702,7 +10170,7 @@ export class FleetManager {
                             ...generalReactions.meta,
                             ...extraMeta,
                         },
-                    }, msg.humanOrigin, msg.humanOriginalBody ?? msg.text);
+                    }, msg.humanOrigin, msg.humanOriginalBody ?? msg.text, this.startRetryHoldFor(generalInstance, msg));
                     generalReactions.consume();
                     this.afterUserInboundDelivered(generalInstance, msg);
                     this.logger.info(`${msg.username} → ${generalInstance}: ${(text ?? "").slice(0, 100)}`);
@@ -9798,7 +10266,7 @@ export class FleetManager {
                     ...reactions.meta,
                     ...extraMeta,
                 },
-            }, msg.humanOrigin, msg.humanOriginalBody ?? msg.text);
+            }, msg.humanOrigin, msg.humanOriginalBody ?? msg.text, this.startRetryHoldFor(instanceName, msg));
             // Only after the message actually went out. A failed delivery keeps the
             // reactions queued for the retry / the next message.
             reactions.consume();
@@ -10477,6 +10945,7 @@ export class FleetManager {
                         // overwritten with coordinates the target's adapter cannot address.
                         ...(foreignWorld ? {} : { chat_id: reply_chat_id, thread_id: reply_thread_id }),
                         user: "scheduler",
+                        source: "schedule",
                         ...(adapterId ? { adapter_id: adapterId } : {}),
                     },
                 }, { waitForIdle: true, ...(retryCurrent ? { stillCurrent: retryCurrent } : {}) });
@@ -14571,7 +15040,7 @@ export class FleetManager {
             ...(input.instance !== undefined ? { target: { adapterId: this.getInstanceAdapterId(input.instance) } } : {}),
             isAdmin: (userId, adapterId) => this.adminGate(userId, adapterId) === "ok",
             authorization: input.session ? this.sessionAuthorizationStore()?.get(input.session.handle) ?? null : null,
-            policy: { ...webAuthorityPolicy(this.fleetConfig?.web), enabled: state.enabled, loopbackOnly: state.loopbackOnly, namedLink: state.namedLink }, epoch: state.epoch, now: Date.now(),
+            policy: { ...webAuthorityPolicy(this.fleetConfig?.web), enabled: state.enabled, loopbackOnly: state.loopbackOnly, namedLink: state.namedLink, quickLink: state.quickLink }, epoch: state.epoch, now: Date.now(),
         });
     }
     sessionAuthorizations = null;
@@ -14596,13 +15065,13 @@ export class FleetManager {
             session, gateway, peer, tokenEpoch: this.webToken ? tokenEpoch(this.webToken) : null,
             isAdmin: (userId, adapterId) => this.adminGate(userId, adapterId) === "ok",
             authorization: { handle: session.handle, owner: session.owner, authorizedAt: now, until: now + policy.maxSessionMs, epoch: state.epoch },
-            policy: { ...policy, enabled: state.enabled, loopbackOnly: state.loopbackOnly, namedLink: state.namedLink }, epoch: state.epoch, now,
+            policy: { ...policy, enabled: state.enabled, loopbackOnly: state.loopbackOnly, namedLink: state.namedLink, quickLink: state.quickLink }, epoch: state.epoch, now,
         });
         if (check.refusal)
             return { ok: false, refusal: check.refusal };
         const live = new Set(this.webSessions?.list(undefined, () => true).map(r => r.handle) ?? []);
         store.prune(a => a.epoch === state.epoch && now <= Math.min(a.until, a.authorizedAt + policy.maxSessionMs) && live.has(a.handle));
-        return { ok: true, ...store.authorize(session.handle, session.owner, now, state.epoch, now + policy.maxSessionMs) };
+        return { ok: true, ...store.authorize(session.handle, session.owner, now, state.epoch, now + policy.maxSessionMs, peer) };
     }
     authorityStateStore = null;
     /**
@@ -14611,13 +15080,24 @@ export class FleetManager {
      */
     webAuthorityState() {
         if (!this.dataDir)
-            return { enabled: false, loopbackOnly: true, namedLink: false, epoch: 0 };
+            return { enabled: false, loopbackOnly: true, namedLink: false, quickLink: false, epoch: 0 };
         this.authorityStateStore ??= new AuthorityStateStore(join(this.dataDir, "web-authority.json"), this.logger, undefined, undefined, () => { this.ensureDeliveryOutbox?.(); return this.deliveryOutbox?.maxWebAuthorityEpoch() ?? 0; });
         const state = this.authorityStateStore.current(this.fleetConfig?.web?.verified_authority);
-        // #2453 (§0.2): the named-link option seen going off — the authority of every session over the link ends now, for
-        // good: their authorizations go (a later "on" can never bring one back without its account's Confirm).
-        if (state.namedLinkClosed)
-            this.sessionAuthorizationStore()?.prune(a => this.webSessions?.findByHandle(a.handle)?.surface === "local");
+        // #2453 (§0.2) / §0.3: a link's option seen going off — the authority of every session over that link ends now, for
+        // good: their authorizations go (a later "on" can never bring one back without its account's Confirm). A record from
+        // before §0.3 has no peer: over the gateway, only a named-link session could have been authorized then.
+        if (state.namedLinkClosed || state.quickLinkClosed) {
+            const ended = (a) => {
+                const session = this.webSessions?.findByHandle(a.handle);
+                if (!session)
+                    return true;
+                if (session.surface === "local")
+                    return false;
+                const peer = a.peer ?? "named_link";
+                return (!!state.namedLinkClosed && peer === "named_link") || (!!state.quickLinkClosed && peer === "quick_link");
+            };
+            this.sessionAuthorizationStore()?.prune(a => !ended(a));
+        }
         return state;
     }
     /**
@@ -14650,7 +15130,8 @@ export class FleetManager {
             .filter(a => a.epoch === state.epoch && sessions.has(a.handle) && now <= Math.min(a.until, a.authorizedAt + maxMs))
             .map(a => ({ handle: a.handle, label: sessions.get(a.handle).label, account: `${a.owner.adapterId}:${a.owner.userId}`, authorizedAt: a.authorizedAt,
             until: Math.min(a.until, a.authorizedAt + maxMs, sessions.get(a.handle).absoluteExpiry),
-            ...(sessions.get(a.handle).surface === "gateway" ? { named: true } : {}) })) : [];
+            // Over a link: the temporary one (§0.3), else the named one (a record from before §0.3 has no peer).
+            ...(sessions.get(a.handle).surface === "gateway" ? (a.peer === "quick_link" ? { quick: true } : { named: true }) : {}) })) : [];
         const host = this.fleetConfig?.web?.public_link?.hostname;
         return { state, configured, hours: VERIFIED_SESSION_HOURS, lanHosts, authorized, namedHost: typeof host === "string" && host ? host : null };
     }
@@ -14665,9 +15146,17 @@ export class FleetManager {
         const adapterOf = (adapterId) => this.adapters.get(adapterId) ?? this.worlds.get(adapterId)?.adapter;
         // The host's clock, with its zone: the person may read the DM on a phone in another one.
         const when = (ms) => new Date(ms).toLocaleString(undefined, { timeZoneName: "short" });
+        const quickHost = () => { try {
+            const u = this.publicWebLink?.openSignin()?.url;
+            return u ? new URL(u).host : "?";
+        }
+        catch {
+            return "?";
+        } };
         const where = (peer) => peer === "named_link"
             ? t("web_auth.peer_named_link", String(this.fleetConfig?.web?.public_link?.hostname ?? "?")) // §0.2: the internet
-            : t(peer === "loopback" ? "web_auth.peer_loopback" : "web_auth.peer_lan");
+            : peer === "quick_link" ? t("web_auth.peer_quick_link", quickHost()) // §0.3: the internet
+                : t(peer === "loopback" ? "web_auth.peer_loopback" : "web_auth.peer_lan");
         return this.authorizationRequests = new SessionAuthorizationRequests({
             now: () => performance.now(), wallNow: () => Date.now(),
             maxSessionMs: () => webAuthorityPolicy(this.fleetConfig?.web).maxSessionMs,
@@ -14701,8 +15190,8 @@ export class FleetManager {
                 const record = this.webSessions?.findByHandle(handle);
                 if (!record)
                     return { ok: false, refusal: "session_gone" };
-                // §0.2: a named-link session is judged as the gateway request it is (its exposure still the current one).
-                const r = this.authorizeWebSession(record, peer, peer === "named_link");
+                // §0.2 / §0.3: a session over a link is judged as the gateway request it is (its exposure still the current one).
+                const r = this.authorizeWebSession(record, peer, peer === "named_link" || peer === "quick_link");
                 // What the card says: the end of the authorization, or the session's own end when that comes first.
                 return r.ok ? { ok: true, until: Math.min(r.authorization.until, record.absoluteExpiry) } : { ok: false, refusal: r.refusal };
             },
@@ -14748,7 +15237,7 @@ export class FleetManager {
             session: s, gateway: input.gateway, peer: input.peer, tokenEpoch: this.webToken ? tokenEpoch(this.webToken) : null,
             isAdmin: (userId, adapterId) => this.adminGate(userId, adapterId) === "ok",
             authorization: s?.owner ? { handle: s.handle, owner: s.owner, authorizedAt: now, until: now + policy.maxSessionMs, epoch: state.epoch } : null,
-            policy: { ...policy, enabled: state.enabled, loopbackOnly: state.loopbackOnly, namedLink: state.namedLink }, epoch: state.epoch, now,
+            policy: { ...policy, enabled: state.enabled, loopbackOnly: state.loopbackOnly, namedLink: state.namedLink, quickLink: state.quickLink }, epoch: state.epoch, now,
         });
         return r.refusal;
     }
@@ -15021,14 +15510,42 @@ export class FleetManager {
     /** A clean exit is intentional from the CLI's perspective, but often not from
      * the operator's. Keep the instance notice passive and put the action in the
      * same-world General topic where an administrator can make the choice. */
-    async notifyNormalExit(instanceName) {
-        this.notifyInstanceTopic(instanceName, t("exit.instance_notice", instanceName) + placeSuffix({ kind: "general" }, "General"));
+    async notifySessionOomStop(instanceName, unclear = false) {
+        await this.notifyNormalExit(instanceName, unclear ? "unclear" : true);
+    }
+    async notifyNormalExit(instanceName, oom = false) {
+        const daemon = oom === "unclear" ? this.daemons.get(instanceName) : undefined;
+        const owner = daemon ? { ...daemon.getInteractionSnapshot().owner } : undefined;
+        const current = daemon && owner ? () => this.daemons.get(instanceName) === daemon
+            && daemon.isUnclearOomStopped() && sameInteractionOwner(owner, daemon.getInteractionSnapshot().owner) : undefined;
+        if (oom === "unclear" && !current?.())
+            return;
+        const state = oom ? readSessionOomStop(this.getInstanceDir(instanceName)) : null;
+        if (oom === "unclear" && state?.blocked)
+            return;
+        const proof = state?.blocked ? state.record?.evidence ?? state.evidence : undefined;
+        if (oom === true && !proof)
+            return;
+        const sessionOomRetry = oom ? captureSessionOomRetry(this.getInstanceDir(instanceName)) : undefined;
+        if (oom && [...this.pendingNonceButtons.values()].some(p => p.prefix === OOM_RETRY_CALLBACK_PREFIX
+            && p.instanceName === instanceName && p.sessionOomRetry?.revision === sessionOomRetry?.revision
+            && (oom !== "unclear" || p.confirmationCurrent?.() === true)))
+            return;
+        const prefix = oom ? OOM_RETRY_CALLBACK_PREFIX : EXIT_RESTART_CALLBACK_PREFIX;
+        const message = oom === "unclear" ? t("inst.oom_unclear_choice", instanceName) : oom && proof
+            ? t("inst.session_oom_choice", instanceName, describeSelfOom(proof))
+            : t("exit.general_notice", placeRef({ kind: "instance", name: instanceName }, instanceName));
+        const choices = oom
+            ? [{ action: "resume", label: t("inst.session_oom_resume") }, { action: "fresh", label: t("inst.session_oom_fresh") }]
+            : [{ action: "restart", label: t("exit.restart") }, { action: "ignore", label: t("exit.ignore") }];
+        const extra = sessionOomRetry ? { sessionOomRetry, ...(current ? { confirmationCurrent: current } : {}) } : undefined;
+        this.notifyInstanceTopic(instanceName, (oom ? message : t("exit.instance_notice", instanceName)) + placeSuffix({ kind: "general" }, "General"));
         const web = this.webOnlyPromptPlace();
         if (web) {
             await this.postNonceButtonPrompt({
-                prefix: EXIT_RESTART_CALLBACK_PREFIX, alertType: "exit_restart", instanceName, ...web,
-                message: t("exit.general_notice", placeRef({ kind: "instance", name: instanceName }, instanceName)),
-                choices: [{ action: "restart", label: t("exit.restart") }, { action: "ignore", label: t("exit.ignore") }],
+                prefix, alertType: "exit_restart", instanceName, ...web,
+                message, extra,
+                choices,
                 expiredText: t("exit.expired", instanceName),
             });
             return;
@@ -15049,37 +15566,36 @@ export class FleetManager {
             return;
         }
         await this.postNonceButtonPrompt({
-            prefix: EXIT_RESTART_CALLBACK_PREFIX,
+            prefix,
             alertType: "exit_restart",
             instanceName,
             adapter,
             adapterId,
             chatId,
             threadId,
-            message: t("exit.general_notice", placeRef({ kind: "instance", name: instanceName }, instanceName)),
-            choices: [
-                { action: "restart", label: t("exit.restart") },
-                { action: "ignore", label: t("exit.ignore") },
-            ],
+            message, extra,
+            choices,
             expiredText: t("exit.expired", instanceName),
         });
     }
     /** Consume a clean-exit Restart/Ignore button exactly once. */
     async handleExitRestartPrompt(data, callbackAdapterId, receivingAdapter) {
-        const claimed = this.consumeNonceCallback(EXIT_RESTART_CALLBACK_PREFIX, /^exit-restart:([0-9a-f]+):(restart|ignore)$/, data, callbackAdapterId, receivingAdapter);
+        const oom = data.callbackData.startsWith(OOM_RETRY_CALLBACK_PREFIX);
+        const claimed = this.consumeNonceCallback(oom ? OOM_RETRY_CALLBACK_PREFIX : EXIT_RESTART_CALLBACK_PREFIX, oom ? /^oom-retry:([0-9a-f]+):(resume|fresh)$/ : /^exit-restart:([0-9a-f]+):(restart|ignore)$/, data, callbackAdapterId, receivingAdapter);
         if (claimed === null)
             return false;
         if (claimed === "consumed")
             return true;
         const { entry: pending, action } = claimed;
-        this.eventLog?.insert(pending.instanceName, "normal_exit_action", { action, userId: data.userId });
+        this.eventLog?.insert(pending.instanceName, oom ? "session_oom_action" : "normal_exit_action", { action, userId: data.userId });
         if (action === "ignore") {
             await this.retireNonceButtons(pending, pending.messageId ?? data.messageId, t("exit.ignored", pending.instanceName));
             return true;
         }
         await this.retireNonceButtons(pending, pending.messageId ?? data.messageId, t("exit.restarting", pending.instanceName));
         try {
-            await this.restartSingleInstance(pending.instanceName);
+            await this.restartSingleInstance(pending.instanceName, { explicit: true, ...(oom ? { freshStart: action === "fresh", sessionOomRetry: pending.sessionOomRetry,
+                    ...(pending.confirmationCurrent ? { recoveryCurrent: pending.confirmationCurrent } : {}) } : {}) });
             await pending.adapter.editMessage(pending.chatId, pending.messageId ?? data.messageId, t("exit.restarted", pending.instanceName), pending.threadId);
         }
         catch (err) {
@@ -16910,6 +17426,10 @@ export class FleetManager {
             log: (level, message, extra) => this.logger[level](extra ?? {}, message),
         });
         db.board.onChange(({ rev, ids, projects, wakes }) => {
+            // Refresh both old and new owners on reassignment; wakes are not an ownership index.
+            if (ids.length)
+                for (const name of this.daemons.keys())
+                    this.observeWorkingState(name, "tasks");
             this.emitSseEvent("tasks", { rev, ids, projects });
             waker.note(wakes);
             // step 3: cards waiting for the person are Needs you items; #2355 review: a project's lead routes them too.
@@ -17008,7 +17528,7 @@ export class FleetManager {
         }
         await this.retireNonceButtons(pending, pending.messageId ?? data.messageId, t("hang.restarting", pending.instanceName));
         try {
-            await this.restartSingleInstance(pending.instanceName);
+            await this.restartSingleInstance(pending.instanceName, { explicit: true });
             await pending.adapter.editMessage(pending.chatId, pending.messageId ?? data.messageId, t("hang.restarted", pending.instanceName), pending.threadId);
         }
         catch (err) {
@@ -17544,7 +18064,12 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
             const isPrimaryAdapter = !mentionWorld || mentionWorld.adapter === this.adapter;
             const adapterBotUserId = mentionWorld?.botUserId ?? (isPrimaryAdapter ? this.botUserId : undefined);
             const mentionTag = adapterBotUserId ? `<@${adapterBotUserId}>` : null;
-            const isMentioned = mentionTag && text.includes(mentionTag);
+            // #2551: a native reply to one of THIS bot's messages is addressed to it, as a mention is (a Discord reply carries
+            // its ping in the reference, not the text). One hop only: a reply to a message of ours that itself answered a bot
+            // (or the sender) is a chain of bots answering each other — a mention still carries it on. A reply to our answer
+            // to a person is the ordinary handoff, and is addressed.
+            const repliesToUs = !!adapterBotUserId && msg.replyToAuthorId === adapterBotUserId && msg.replyToChain !== true;
+            const isMentioned = (mentionTag && text.includes(mentionTag)) || repliesToUs;
             if (!isMentioned) {
                 // Bare attachment (no @mention) — already saved above; just acknowledge.
                 if (saved) {
@@ -17780,7 +18305,7 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
                 content: fullText,
                 targetSession: instanceName,
                 meta,
-            }, msg.humanOrigin, msg.humanOriginalBody ?? text);
+            }, msg.humanOrigin, msg.humanOriginalBody ?? text, this.startRetryHoldFor(instanceName));
             reactions.consume();
         }
         catch (err) {
@@ -19738,7 +20263,12 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
         // also sees the channel's messages.
         if (adapterId)
             this.bindInstanceAdapter(instanceName, adapterId);
-        await this.startClassicInstance(instanceName, classicChannels.getBackend(channelId, adapterId, this.fleetConfig?.defaults?.backend), classicChannels.getPreTaskCommand(channelId, adapterId), classicChannels.getModel(channelId, adapterId, this.fleetConfig?.defaults?.model), classicChannels.getAutoPauseAfter(channelId, adapterId, this.fleetConfig?.defaults?.auto_pause_after));
+        if (this.sessionOomStopped(instanceName)) {
+            await this.restartSingleInstance(instanceName, { explicit: true });
+        }
+        else {
+            await this.startClassicInstance(instanceName, classicChannels.getBackend(channelId, adapterId, this.fleetConfig?.defaults?.backend), classicChannels.getPreTaskCommand(channelId, adapterId), classicChannels.getModel(channelId, adapterId, this.fleetConfig?.defaults?.model), classicChannels.getAutoPauseAfter(channelId, adapterId, this.fleetConfig?.defaults?.auto_pause_after));
+        }
         this.reregisterClassicChannels();
         // Auto-enable collab for Discord classic channels (TG uses @mention directly without collab mode)
         if (guildId && !classicChannels.isCollab(channelId, adapterId)) {
@@ -19808,6 +20338,22 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
     }
     tmuxExecHelperTimer = null;
     stopAllInFlight = null;
+    /** Signal-handler continuation, after successful graceful shutdown only. */
+    noteRequestedShutdown() {
+        const progress = readUpdateProgress(this.dataDir)?.progress;
+        const update = progress && updateProgressOperation(progress) === "update"
+            && ["installed", "stopping", "starting"].includes(progress.stage);
+        this.recordWorkingRestartIntent(update ? "update" : "manual_restart");
+    }
+    recordWorkingRestartIntent(cause) {
+        this.workingRecoveryCause = cause;
+        try {
+            this.deliveryOutbox?.workingRecovery.requested(this.managerBootId, cause);
+        }
+        catch {
+            this.logger.warn("Could not record requested restart; next recovery will report an unknown interruption");
+        }
+    }
     /** Stops release memory. Reassess between batches without waiting for recovery. */
     async stopInstancesInBatches(entries, stop) {
         let index = 0;
@@ -19825,15 +20371,25 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
         }
     }
     async doStopAll() {
+        // The scheduler closes before individual daemons stop. Preserve the owned
+        // task/reply boundary while those stores are still available, not a later
+        // shutdown snapshot whose unavailable sources cannot authorize recovery.
+        for (const name of this.daemons.keys())
+            this.observeWorkingState(name, "before_stop");
         this.startupMemoryDeadline?.stop();
         this.startupMemoryDeadline = null;
         this.startupComplete = false;
+        this.workingRecovery?.reset();
         this.startupDashboard = null;
         this.reloadPending = false;
         // Before anything is stopped: everything that dies from here on dies
         // because we asked it to. Set synchronously — doStopAll runs to its first
         // await in the same tick as the signal handler, so no event can slip in.
         this.shuttingDown = true;
+        this.workingRecovery?.reset();
+        if (this.workingRecoveryTimer)
+            clearInterval(this.workingRecoveryTimer);
+        this.workingRecoveryTimer = null;
         if (this.updateProgressTimer) {
             clearInterval(this.updateProgressTimer);
             this.updateProgressTimer = null;
@@ -20513,6 +21069,27 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
     fleetSignatureMismatchKeys() {
         return this.fleetSignatureMismatch;
     }
+    /**
+     * #2347 restart flow: saved changes that take effect only after AgEnD restarts — the startup-only keys fleet.yaml
+     * now differs on, and the newest apply job whose fleet row can carry the restart (`job_id`, null when none can: a
+     * hand edit, or a job past its retention). Null when nothing is pending, and when a restart could not clear it
+     * (the signature mismatch the panel reports instead). The same test requestSettingsSelfRestart makes.
+     */
+    settingsRestartPending() {
+        if (this.appliedFleetLevel === null || this.fleetSignatureMismatch)
+            return null;
+        const next = this.nextFleetConfig();
+        if (this.appliedFleetLevel === this.fleetLevelSignature(next))
+            return null;
+        let job = null;
+        // A job whose restart was asked for already has its row in flight ("running"), so it is never offered again.
+        for (const candidate of this.applyJobs.all()) {
+            const row = candidate.targets.find(item => item.target === APPLY_FLEET_TARGET);
+            if (row?.status === "restart-required" && (!job || candidate.startedAt >= job.startedAt))
+                job = candidate;
+        }
+        return { keys: fleetLevelDifferences(this.startupFleetConfig, next), job_id: job ? job.id : null };
+    }
     /**
      * Restart AgEnD itself on behalf of a Settings apply.
      *
@@ -21763,6 +22340,8 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
             this.logger.info("No instances to restart");
             return;
         }
+        this.recordWorkingRestartIntent("manual_restart");
+        this.workingRecovery?.reset();
         this.logger.info(`Graceful restart: waiting for ${instanceNames.length} instances to idle...`);
         const groupId = this.fleetConfig?.channel?.group_id;
         const generalName = this.findGeneralInstance();
@@ -21863,7 +22442,16 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
                 this.startStatuslineWatcher(name);
             }
         }
+        this.workingRecovery?.ready();
         this.logger.info("Graceful restart complete");
+        // The in-process interval keeps its label, but a later unrelated process
+        // crash must not inherit this completed request as its shutdown intent.
+        try {
+            this.deliveryOutbox?.workingRecovery.clearRequested(this.managerBootId);
+        }
+        catch {
+            this.logger.warn("Could not clear completed in-process restart intent");
+        }
         const configuredNames = this.configuredStartupInstanceNames(fleet, topicMode);
         const total = configuredNames.length;
         const started = configuredNames.filter(name => this.daemons.has(name)).length;
@@ -21918,6 +22506,7 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
                     }
                     const ipc = this.instanceIpcClients.get(name);
                     if (ipc?.connected) {
+                        daemon?.noteLegacyRestartReminder?.();
                         ipc.send({
                             type: "fleet_inbound",
                             content: msg,
@@ -22065,6 +22654,11 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
         const guests = this.fleetConfig?.web?.guests;
         if (!owner || guests?.enabled !== true)
             return NO_GUEST_SCOPE;
+        // #2348: explicit grants, once the key exists, are the whole scope — no narrowing on top (a grant is already exact).
+        if (guests.grants !== undefined) {
+            const granted = this.guestReach(owner);
+            return granted.size ? granted : NO_GUEST_SCOPE;
+        }
         const scope = new Set(this.guestReach(owner));
         const narrow = guests.narrow && Object.hasOwn(guests.narrow, `${owner.adapterId}:${owner.userId}`) ? guests.narrow[`${owner.adapterId}:${owner.userId}`] : undefined;
         if (narrow) {
@@ -22085,6 +22679,20 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
         const scope = new Set();
         if (guests?.enabled !== true)
             return scope;
+        // #2348: with explicit grants, what an admin granted this account — of the instances that exist now (fleet.yaml's, or
+        // a ClassicBot room's) — and nothing else: no connection access, no room membership, no open_instances.
+        if (guests.grants !== undefined) {
+            const key = `${owner.adapterId}:${owner.userId}`;
+            const grant = Object.hasOwn(guests.grants, key) ? guests.grants[key] : undefined;
+            if (!grant || !Array.isArray(grant.instances))
+                return scope;
+            const rooms = new Set((this.classicChannels?.getAll() ?? []).map((r) => r.instanceName));
+            for (const name of grant.instances) {
+                if ((this.fleetConfig?.instances && Object.hasOwn(this.fleetConfig.instances, name)) || rooms.has(name))
+                    scope.add(name);
+            }
+            return scope;
+        }
         const own = (map, key) => (map && Object.hasOwn(map, key) ? map[key] : undefined);
         const world = this.worlds.get(owner.adapterId);
         if (world && world.accessManager.isAllowed(owner.userId)) {
@@ -22126,7 +22734,9 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
         const owner = record.owner;
         if (this.guestScope(owner).size)
             return "ok";
-        if (owner && this.fleetConfig?.web?.guests?.enabled === true) {
+        // #2348: with explicit grants no room's membership can give anything: nothing granted is gone, not pending. Nor does
+        // a connection's start matter: grants are config (and ClassicBot rooms), read without the adapter.
+        if (owner && this.fleetConfig?.web?.guests?.enabled === true && this.fleetConfig.web.guests.grants === undefined) {
             // Before adapters initialize, topic scope is unknown, not revoked. Keep the returning cookie but grant no
             // request until its configured world exists. Removed connections and initialized denied access stay final.
             const channels = this.fleetConfig.channels ?? (this.fleetConfig.channel ? [this.fleetConfig.channel] : []);