@songsid/agend 2.3.1 → 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";
@@ -605,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;
     /**
@@ -1054,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). */
@@ -1846,6 +1936,7 @@ 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");
@@ -2124,6 +2215,10 @@ export class FleetManager {
                 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,
@@ -2217,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);
@@ -2279,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;
@@ -2320,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");
                 }
@@ -3004,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(() => {
@@ -4866,7 +4979,7 @@ export class FleetManager {
         return new WakeCoordinator({
             mode: target => this.deliveryWorkerMode(target),
             available: () => !this.shuttingDown && this.deliveryOutbox?.isOpen === true,
-            listPending: () => this.deliveryOutbox?.listPending() ?? [],
+            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),
@@ -6722,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 });
@@ -6731,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) {
@@ -6803,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
@@ -6831,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);
@@ -6865,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")
@@ -7418,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.
@@ -7996,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");
@@ -10666,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 } : {}) });
@@ -14760,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;
@@ -14785,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;
     /**
@@ -14800,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;
     }
     /**
@@ -14839,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 };
     }
@@ -14854,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,
@@ -14890,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 };
             },
@@ -14937,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;
     }
@@ -17764,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) {
@@ -20033,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;
@@ -20050,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;
@@ -20738,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.
      *
@@ -21988,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();
@@ -22088,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;
@@ -22143,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,
@@ -22290,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) {
@@ -22310,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)) {
@@ -22351,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] : []);