fedipod 1.40.0 → 1.42.0

package/run-agent.mjs

@@ -16,731 +16,28 @@
 //   node run-agent.mjs                      # or: bin/fedipod.mjs run
 //
 // Env: AP_HOME (credential dir + local log, default ~/.fedipod, or
-//      ~/.activitypod on an install that predates the rename — see lib/home.mjs),
+//      ~/.activitypod on an install that predates the rename — see lib/device/home.mjs),
 //      AP_PORT (UI/API/admin, default 8030),
 //      AP_GATE_TOKEN (optional loopback gate; absent → open, loopback-only).
 //
 // Until `bin/fedipod.mjs setup` has minted a credential the agent idles:
 // UI + admin up, no federation.
 
+
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 
-import { PodStore } from './lib/core/store.mjs';
-import { apRoot, rootOf, writeJsonAtomic } from './lib/device/home.mjs';
+import { Agent } from './lib/core/agent.mjs';
+import { apRoot, rootOf } from './lib/device/home.mjs';
+import { writeJsonAtomic } from './lib/shared/files.mjs';
 import { ensureTrustedTls } from './lib/device/certs.mjs';
-import { storageFor } from './lib/core/storage.mjs';
-import { resolveKeys } from './lib/core/keys.mjs';
-import { completeGatewayMove } from './lib/device/gateway-move.mjs';
-import { RemotePod } from './lib/device/remote.mjs';
-import { Deliverer } from './lib/core/deliver.mjs';
-import { Publisher } from './lib/core/publisher/index.mjs';
-import { Intake } from './lib/core/intake/index.mjs';
-import { C2S } from './lib/client/c2s.mjs';
-import { TagFeed } from './lib/connections/tagfeed.mjs';
-import { ImportWorker } from './lib/connections/import.mjs';
-import { Atproto } from './lib/connections/atproto.mjs';
-import { FediAccounts } from './lib/connections/fediacct.mjs';
-import { vaultsFor } from './lib/connections/vault.mjs';
-import { AcctFeed } from './lib/connections/acctfeed.mjs';
-import { BskyFeed } from './lib/connections/bskyfeed.mjs';
-import { BskyGroup } from './lib/connections/bskygroup.mjs';
-import { Lease } from './lib/core/lease.mjs';
-import { publishDue } from './lib/core/scheduled.mjs';
 import { startAdmin } from './lib/device/admin/index.mjs';
 import { exposureProblem, hostLabel } from './lib/shared/guard.mjs';
 import { pendingSteps } from './lib/device/migrate.mjs';
-import { apUrls, assertionKeyId , publicHandle } from './lib/core/wire.mjs';
-import { followActor, unfollowActor, resolveHandle } from './lib/core/social.mjs';
-import * as podInbox from './lib/pod/inbox.mjs';
-
-export class Agent {
-  constructor({ home, log }) {
-    this.home = home;
-    this.log = log;
-    this.logRing = [];
-    this.store = new PodStore({ log });
-  }
-
-  readCredential() {
-    try { return JSON.parse(fs.readFileSync(path.join(this.home, 'credential.json'), 'utf8')); }
-    catch { return null; }
-  }
-
-  configured() { return !!this.remote && !!this.store.getConfig(); }
-
-  // Where the private half lives. `privateRoot` in the credential file names a
-  // container — by default a plain directory beside the credential, and a pod
-  // on this machine if you move it there. Absent means on the pod, so an
-  // existing install is untouched.
-  privateUrls(cred, urls = this.urls) {
-    if (!cred.privateRoot) {
-      return { state: urls.state, archive: urls.home + 'inbox-archive/', elsewhere: false };
-    }
-    const base = cred.privateRoot.endsWith('/') ? cred.privateRoot : cred.privateRoot + '/';
-    return { state: base + 'ap-state/', archive: base + 'inbox-archive/', elsewhere: true };
-  }
-
-  // A container to keep the private half in. On the pod it is reached with the
-  // credential; a local pod plainly, with a token header when it is gated
-  // (dk's is); a directory is not reached over anything at all.
-  privateStorage(cred, which, urls = this.urls) {
-    const url = this.privateUrls(cred, urls)[which];
-    if (!cred.privateRoot) return storageFor(url, (u, i) => this.remote.fetch(u, i));
-    const token = process.env.AP_STATE_TOKEN || '';
-    return storageFor(url, (u, i) => fetch(u, token
-      ? { ...i, headers: { ...(i?.headers || {}), 'x-dk-token': token } }
-      : i));
-  }
-
-  logLines(n = 100) { return this.logRing.slice(-n); }
-
-  status() {
-    const cfg = this.store.getConfig();
-    const contacts = this.store.getContacts();
-    return {
-      configured: this.configured(),
-      mode: !this.configured() ? 'unconfigured' : this.viewer ? 'viewer' : 'active',
-      kind: cfg?.kind || 'person',
-      handle: cfg?.handle || null,
-      actor: this.urls?.actor || null,
-      followers: contacts.followers.length,
-      following: contacts.following.length,
-      queue: this.store.getQueue().length,
-      deadLetters: this.store.getDeadLetters().length,
-      blockedDomains: this.store.getBlocklist().domains.length,
-      push: this.intake?.wsState || 'n/a',
-      // Measured by the last sweep from the listing it already fetched, so
-      // asking costs nothing. What the admin page prompts on.
-      inbox: this.intake?.inboxStats || null,
-      lastDrain: this.intake?.lastDrain || null,
-      tagfeed: this.tagfeed
-        ? { ...this.tagfeed.config(), lastSweep: this.tagfeed.lastSweep, lastAdded: this.tagfeed.lastAdded }
-        : null,
-      atproto: this.atproto?.status() || null,
-      // Anyone asking whether this agent is hammering their server can read the
-      // answer here instead of in their access log.
-      podRequests: this.remote?.stats?.() || null,
-      update: this.updateInfo || null,
-      inboxCooldownFor: this.intake?.drainCooldownUntil
-        ? Math.max(0, Math.round((this.intake.drainCooldownUntil - Date.now()) / 1000)) : 0,
-      stateSkipped: this.store.lastSkipped || [],
-    };
-  }
-
-  // First-run provisioning, called by the setup CLI after the credential file
-  // is written: containers, owner-only ACLs on the private trees, config into
-  // pod state. publishProfile (via connect) handles the public wire ACLs.
-  async bootstrap({ handle, name, root, kind, approveJoins = false, summary, icon, gateway }) {
-    const cred = this.readCredential();
-    if (!cred) throw new Error('no credential — run setup first');
-    if (!this.remote) {
-      this.remote = new RemotePod(cred, { log: this.log, home: this.home });
-      await this.remote.warmup();
-    }
-    this.urls = apUrls(cred.remotePod, root);
-    const priv = this.privateUrls(cred);
-    const stateStore = this.privateStorage(cred, 'state');
-    // The pod's own ap-state/ is provisioned either way: even when the rest of
-    // the private half lives elsewhere, lease.json stays here, because a lease
-    // in a pod only one machine can reach coordinates nothing.
-    await this.remote.putJson(this.urls.state + '.keep', { keep: true }, 'application/json');
-    await this.remote.setAcl(this.urls.home, []);
-    await this.remote.setAcl(this.urls.state, []);
-    if (priv.elsewhere) {
-      const r = await stateStore.write('.keep', '{"keep":true}\n', 'application/json');
-      if (!r.ok) throw new Error(`private store ${stateStore.base}.keep → ${r.why}`);
-      this.log(`private state lives at ${cred.privateRoot} (${stateStore.kind})`);
-    }
-    this.store.attach(stateStore);
-    // Re-running setup must not destroy state set afterwards (the UI
-    // password, above all), so load what is there and merge into it.
-    await this.store.load().catch(() => {});
-    const existing = this.store.getConfig() || {};
-    this.store.setConfig({
-      ...existing,
-      remotePod: cred.remotePod, handle, name: name || existing.name || handle,
-      issuer: cred.issuerOrigin, ...(root ? { root } : {}),
-      ...(kind ? { kind } : {}),
-      ...(approveJoins ? { approveJoins: true } : {}),
-      ...(summary ? { summary } : {}), ...(icon ? { icon } : {}),
-      // Set before the first publish, so the actor never advertises the pod
-      // inbox only to rename it a moment later.
-      ...(gateway ? { gateway } : {}),
-    });
-    await this.store.flush();
-  }
-
-  // Cache the handle in agent.json, merging so the port survives. Nothing
-  // outside this process can read pod state, so this file is the only place a
-  // sibling — or the next start, before it connects — can learn the name to
-  // build this identity's origin from.
-  recordHandle(handle) {
-    if (!handle || !this.home) return;
-    const file = path.join(this.home, 'agent.json');
-    let rec = {};
-    try { rec = JSON.parse(fs.readFileSync(file, 'utf8')) || {}; } catch { /* first run */ }
-    if (rec.handle === handle) return;
-    try { writeJsonAtomic(file, { ...rec, handle }, { mode: 0o644 }); }
-    catch { /* the agent still runs; its links are just bare */ }
-  }
-
-  // Bring federation up from the credential file + pod state. `name` (from
-  // `run --name "…"`) updates the display name other servers show, without
-  // the collateral of re-running setup.
-  // `act: false` reads the identity and stops. Everything a confirmation prompt
-  // needs — the handle, the host, the follow counts — is in pod state that is
-  // loaded by then, while acquiring the lease, draining the inbox, subscribing a
-  // notification channel, probing the ACLs and sweeping the tag feed are all
-  // things a command you are about to decline should never have spent. The
-  // command calls connect() again, without the flag, if you say yes.
-  async connect({ name = null, repair = true, act = true } = {}) {
-    const cred = this.readCredential();
-    if (!cred) return false;
-    if (!this.remote) {
-      this.remote = new RemotePod(cred, { log: this.log, home: this.home });
-      await this.remote.warmup();
-    }
-    const probeUrls = apUrls(cred.remotePod, cred.root);
-    // Load until it actually succeeds: attaching is not the same as having
-    // read the state, and a retry that skipped the load would see an empty
-    // cache and wrongly conclude the agent was never set up.
-    if (!this.store.storage) this.store.attach(this.privateStorage(cred, 'state', probeUrls));
-    if (!this.stateLoaded) {
-      await this.store.load();
-      this.stateLoaded = true;
-    }
-    let config = this.store.getConfig();
-    if (!config) { this.log('credential present but pod state empty — run setup'); return false; }
-    // The store had to be attached from the credential, because only the config
-    // it holds says where the state really lives. If the two disagree,
-    // everything past here reads one tree and writes another.
-    // Only meaningful when the state follows the pod. With privateRoot set it
-    // is pinned by configuration and a moved pod does not move it.
-    if (!cred.privateRoot && apUrls(config.remotePod, config.root).state !== probeUrls.state) {
-      const moved = apUrls(config.remotePod, config.root).state;
-      this.log(`state tree moved (${probeUrls.state} → ${moved}) — reattaching`);
-      this.store.attach(storageFor(moved, (u, i) => this.remote.fetch(u, i)));
-      await this.store.load();
-      config = this.store.getConfig();
-      if (!config) { this.log('no state at the pod its own config names — run setup'); return false; }
-    }
-    // Resurrecting a tombstoned actor would contradict the Delete every server
-    // has already acted on, so a retired identity stays retired.
-    if (config.retiredAt) {
-      this.log(`this actor was retired on ${config.retiredAt} — run setup for a new identity`);
-      return false;
-    }
-    // A rename is a merge into the existing config, never a rewrite — the
-    // UI password and anything else set later must survive it.
-    if (name && name !== config.name) {
-      this.store.setConfig({ ...config, name });
-      config = this.store.getConfig();
-      this.renamed = true;                   // republish the actor once connected
-      this.log(`display name set to "${name}"`);
-    }
-    // A fronted identity (config.gateway.frontActor) advertises its ids on a
-    // shared domain; RemotePod gets the map so writes still land on the pod.
-    const publicBase = config.gateway?.frontActor
-      ? config.gateway.frontActor.replace(/ap\/actor\/?$/, '') : null;
-    this.urls = apUrls(config.remotePod, config.root, { publicBase });
-    if (this.urls.toPod) this.remote.setUrlMap(this.urls.toPod);
-    // The agent answers at <handle>.localhost too, so each identity on a
-    // machine gets a browser origin of its own. Known only now: the admin
-    // server was listening before any of this was read.
-    this.authorities?.setHandle(config.handle);
-    // And write it down beside the port. Everything that links to this identity
-    // from OUTSIDE the process builds the origin from agent.json — the Actors
-    // list, a sibling's page, the next start — and an identity set up before the
-    // handle was recorded has only a port there, so every one of those links
-    // came out bare. Pod state is the authority; this is the cache of it.
-    this.recordHandle(config.handle);
-
-    // Said once, where the config is finally known. Exposure without a gate
-    // token is refused before the socket opens (startAgent), so reaching here
-    // means the token is set and the whole surface is behind it. A UI password
-    // is the second, per-person half: without one, anyone who has the token
-    // gets a client bearer for the asking.
-    // An install made before the shape changed goes on working, which is why
-    // nothing here refuses — but it should not go on SILENTLY. The whole reason
-    // this is said out loud is that bbba587 changed a default and every install
-    // that already existed kept the old layout with nothing to show for it.
-    const pending = pendingSteps(cred);
-    for (const step of pending) {
-      this.log(`this identity is on an older layout: ${step.what} (${step.why}). `
-        + 'Run `fedipod upgrade` to see what is pending.');
-    }
-    // The record page says the same thing on its software row — the log is
-    // read by nobody who lives in the GUI.
-    this.pendingUpgrade = pending.map(s => s.what);
-
-    if (process.env.AP_ALLOWED_HOSTS && !config.uiPassword) {
-      this.log('WARNING: AP_ALLOWED_HOSTS is set and no UI password is — anyone holding '
-        + 'AP_GATE_TOKEN can mint a client token. Run `fedipod passwd`.');
-    }
-
-    if (!act) return true;                   // reading only — see the note above
-
-    // Exactly one agent may act on a pod (inbox drains are destructive
-    // reads); later arrivals become read-only viewers of the same state.
-    // Deliberately the REMOTE pod's ap-state/, never privateRoot's: a lease
-    // that only one machine can reach is not a lease.
-    this.lease = new Lease({
-      url: this.urls.state + 'lease.json',
-      fetchImpl: (u, i) => this.remote.fetch(u, i), log: this.log,
-    });
-    this.viewer = !(await this.lease.acquire());
-
-    // Keys are LOCAL by default (the pod host never holds them); `setup
-    // --keys pod` opts into sharing them through the pod so several devices
-    // can sign as the same actor. Per-machine choice, so it rides in the
-    // credential file rather than pod state.
-    const keys = await resolveKeys(this.store, {
-      localDir: cred.keysMode === 'pod' ? null : this.home,
-      rotate: !!cred.rotateKeyOnce,
-      actorId: this.urls.actor,
-      log: this.log,
-      // Consulted only when no key material exists anywhere: if the actor
-      // already publishes a key, minting a new one would break federation.
-      actorHasKey: async () => {
-        const doc = await this.remote.getJson(this.urls.actor).catch(() => null);
-        return !!doc?.publicKey?.publicKeyPem;
-      },
-    });
-    if (cred.rotateKeyOnce) {                       // one-shot flag
-      const { rotateKeyOnce, ...rest } = cred;
-      writeJsonAtomic(path.join(this.home, 'credential.json'), rest);
-    }
-    // connect() can run more than once — connectWithRetry retries after a throw,
-    // and the CLI connects for real after its confirmation. Deliverer arms a
-    // 60s queue timer in its constructor and Intake owns a poll timer and a
-    // websocket, so replacing them without stopping the old ones leaves both
-    // ticking for the life of the process.
-    this.intake?.stop();
-    this.deliverer?.stop();
-    this.tagfeed?.stop();
-    clearInterval(this.schedTimer);
-    this.publisher?.stopPolls();
-    this.deliverer = new Deliverer({
-      store: this.store, rsaPrivate: keys.rsaPrivate, keyId: this.urls.actor + '#main-key',
-      actorId: this.urls.actor, edPrivate: keys.edPrivate,
-      proofKeyId: assertionKeyId(this.urls),
-      log: this.log, passive: this.viewer,
-      onGone: () => this.publisher.publishCollections({ followers: true }),
-    });
-    this.publisher = new Publisher({
-      config, remote: this.remote, store: this.store,
-      deliverer: this.deliverer, publicKeyPem: keys.rsaPublicPem,
-      assertionKey: keys.edPublicMultibase, log: this.log,
-      resolveMention: (h) => resolveHandle(this, h),
-      resolveActor: (u) => this.intake.fetchAP(u),
-      // Inside a pod server the client surface answers on the pod's own
-      // origin, so it can be advertised. Standalone it is on loopback, and
-      // naming it in a world-readable actor would send clients nowhere.
-      clientOrigin: this.embedded ? this.urls.base : null,
-    });
-    // Intake is constructed even for viewers — its signed fetchAP powers
-    // search/deref; start() (draining) is active-only.
-    // The dispatcher the admin surface also builds; this one is for what the
-    // Gateway's outbox door took on the owner's behalf and the drain finds.
-    this.c2s = new C2S({ agent: this, log: this.log });
-    this.intake = new Intake({
-      config, urls: this.urls, remote: this.remote, store: this.store,
-      deliverer: this.deliverer, publisher: this.publisher, log: this.log, lease: this.lease,
-      archive: this.privateStorage(cred, 'archive'),
-      push: !this.embedded, pollSeconds: this.pollSeconds || null,
-      ownerPost: (a, o) => this.c2s.dispatch(a, o),
-    });
-    // The CSV-import worker: paced, resumable, armed only while active.
-    this.importer?.stop();
-    this.importer = new ImportWorker({ agent: this, log: this.log });
-    // Where the credentials for accounts held on OTHER servers are kept.
-    const vaults = vaultsFor({ embedded: this.embedded, home: this.home, store: this.store });
-    // The Bluesky connection, when one exists. Stamped to this actor; a
-    // credential connected for another identity is treated as absent.
-    this.atproto = new Atproto({
-      localDir: this.home, actorId: this.urls.actor, log: this.log, vault: vaults.bluesky,
-    });
-    this.publisher.atproto = this.atproto;
-    // Fediverse accounts the owner holds elsewhere. Same custody rules as the
-    // Bluesky credential, and the same absence when stamped for someone else.
-    this.fediaccts = new FediAccounts({
-      localDir: this.home, actorId: this.urls.actor, log: this.log,
-      vault: vaults.fedi, apps: vaults.apps,
-    });
-    this.acctfeed?.stop();
-    this.acctfeed = null;
-    this.bskyfeed?.stop();
-    this.bskyfeed = null;
-    this.bskygroup = null;
-    this.intake.bskyGroup = null;
-    if (this.viewer) {
-      this.startViewer();
-      this.log(this.lease.denied === 'unreadable'
-        ? `the pod cannot be read, so the lease is unknown — viewing as @${config.handle} (read-only)`
-        : `another agent is active for this pod — viewing as @${config.handle} (read-only)`);
-      return true;
-    }
-    await this.startActive({ repair });
-    return true;
-  }
-
-  // Claim the lease from whoever holds it and start acting. For the case where
-  // the holder is gone but its lease has not expired — a crash, or a one-shot
-  // command that exited without releasing — the only alternative is waiting out
-  // the TTL, which is five minutes.
-  async takeOver() {
-    if (!this.viewer) return false;
-    if (!await this.lease.takeover()) return false;
-    this.log('took the lease over');
-    await this.startActive({ promoted: true });
-    return true;
-  }
-
-  // Mint a replacement signing key and republish the actor that advertises it.
-  // These are one operation: a rotation without the republish leaves remote
-  // servers verifying against a key we no longer hold, which fails every
-  // delivery silently. The live deliverer and publisher are updated too, so the
-  // running agent signs with the new key from here on.
-  async rotateKey() {
-    const cred = this.readCredential();
-    const before = this.publisher.publicKeyPem;
-    const keys = await resolveKeys(this.store, {
-      localDir: cred.keysMode === 'pod' ? null : this.home,
-      rotate: true,
-      actorId: this.urls.actor,
-      log: this.log,
-    });
-    this.publisher.publicKeyPem = keys.rsaPublicPem;
-    this.publisher.assertionKey = keys.edPublicMultibase;
-    this.deliverer.rsaPrivate = keys.rsaPrivate;
-    this.deliverer.edPrivate = keys.edPrivate;
-    await this.publisher.publishProfile();
-    return { changed: before !== keys.rsaPublicPem, publicKeyPem: keys.rsaPublicPem };
-  }
-
-  // Park: as quiet as a pod can be while keeping its name, and revivable.
-  // The following list is snapshotted FIRST — unfollowing is what stops the
-  // traffic at source, but it also destroys the only record of who was being
-  // followed, and "until I want to revive it" needs that record.
-  async park({ unfollow = unfollowActor } = {}) {
-    const following = await this._snapshotFollowing();
-    const r = await this.quiesce({ unfollow });
-    this.log(`parked: ${r.unfollowed} unfollow(s) recorded for revival, inbox closed`);
-    return { ...r, snapshot: following.length };
-  }
-
-  // Undo a park: re-open the inbox, then re-follow everyone from the snapshot.
-  // Each Follow needs the far end to Accept, so this is a request, not a
-  // restoration — some will not come back, which is the nature of the thing.
-  async revive({ follow = followActor } = {}) {
-    const parked = this.store.read('parked.json', null);
-    await this.publisher.openInbox();
-    let refollowed = 0;
-    for (const f of parked?.following || []) {
-      try { await follow(this, f.actor); refollowed++; }
-      catch (e) { this.log(`re-follow ${f.actor} failed: ${e.message}`); }
-    }
-    if (parked) this.store.remove('parked.json').catch(() => {});
-    await this.store.flush();
-    this.log(`revived: inbox open, ${refollowed}/${parked?.following?.length || 0} follow(s) re-sent`);
-    return { refollowed, of: parked?.following?.length || 0, parkedAt: parked?.parkedAt || null };
-  }
 
-  // The follow graph, written down before it is torn down. Both going quiet
-  // and moving away unfollow everyone, and the record page offers "active"
-  // afterwards for either — so both have to leave something to come back from,
-  // or setting it back re-follows nobody and says so only in a count.
-  async _snapshotFollowing() {
-    const following = this.store.getContacts().following;
-    this.store.write('parked.json', {
-      parkedAt: new Date().toISOString(),
-      following: following.map(f => ({ actor: f.actor, handle: f.handle || null })),
-    });
-    await this.store.flush();
-    return following;
-  }
-
-  // Keep the handle, take no more mail. Unfollowing is what actually stops the
-  // volume — every account you follow pushes its posts into your inbox — and
-  // closing the inbox handles the rest, which no follow graph can gate:
-  // stranger mentions, new follow requests, outright spam.
-  // `unfollow` is injectable so this is testable without a live pod.
-  async quiesce({ unfollow = unfollowActor } = {}) {
-    const following = this.store.getContacts().following.map(f => f.actor);
-    let unfollowed = 0;
-    for (const actor of following) {
-      try { await unfollow(this, actor); unfollowed++; }
-      catch (e) { this.log(`unfollow ${actor} failed: ${e.message}`); }
-    }
-    const quiescedAt = await this.publisher.closeInbox();
-    this.log(`quiesced: unfollowed ${unfollowed}/${following.length}, inbox closed`);
-    return { unfollowed, following: following.length, quiescedAt };
-  }
-
-  // Same, plus the fediverse-native redirect: followers are migrated to the
-  // target by their own servers, and the old handle keeps resolving.
-  async moveTo(target, { unfollow = unfollowActor } = {}) {
-    const moved = await this.publisher.publishMove(target);
-    const snapshot = await this._snapshotFollowing();
-    const quiesced = await this.quiesce({ unfollow });
-    return { ...moved, ...quiesced, snapshot: snapshot.length };
-  }
-
-  // True when it had to republish. Authenticated read: the question here is
-  // whether the document EXISTS, not whether the world can see it —
-  // verifyPublicSurface answers that one.
-  async ensureActorPublished() {
-    const doc = await this.remote.getJson(this.urls.actor);
-    if (doc?.id) return false;
-    this.log('actor document missing from the pod — republishing');
-    await this.publisher.publishProfile({ force: true });   // the digest cannot know this
-    return true;
-  }
-
-  // The featured collection was once written only on the first pin, so an
-  // account from before then has none, and every server that shows the
-  // profile is refused and asks again. One authenticated GET; the empty
-  // collection goes up when the pod lacks it. True when it had to.
-  async ensureFeaturedPublished() {
-    const doc = await this.remote.getJson(this.urls.featured);
-    if (doc?.id) return false;
-    this.log('featured collection missing from the pod — publishing it');
-    await this.publisher.publishFeatured();
-    return true;
-  }
-
-  // The inbox's door must be open to the world (or to the gateway alone, in
-  // locked mode) or nothing anyone sends ever lands. The permission is written
-  // at setup, and a container made again later — a root move, a pod rebuilt —
-  // came back without it: the group's inbox on fp2 refused every delivery for
-  // nine days while its agent ran on, healthy-looking. One write per start,
-  // and it is idempotent.
-  async ensureInboxOpen() {
-    const g = this.store.getConfig()?.gateway;
-    const posture = g?.mode === 'locked' && g.webId ? { gatewayWebId: g.webId } : 'open';
-    await podInbox.setPosture(this.remote, this.urls, posture);
-    return posture;
-  }
-
-  // Read-only mode: refresh the state cache periodically, and take over the
-  // moment the active agent's lease frees.
-  startViewer() {
-    this.viewer = true;
-    // Five minutes, not one: with revalidation a quiet refresh is a single 304,
-    // but a viewer still has no reason to ask twelve times an hour.
-    this.refreshTimer = setInterval(async () => {
-      try {
-        if (this.viewer && await this.lease.acquire()) {
-          this.log('lease freed — promoting to ACTIVE');
-          await this.startActive({ promoted: true });
-          return;
-        }
-        if (this.viewer) await this.store.load();
-      } catch (e) { this.log(`viewer refresh: ${e.message}`); }
-    }, Math.round(5 * 60_000 * (0.85 + Math.random() * 0.3)));
-    this.refreshTimer.unref?.();
-  }
-
-  // The acting half: lease renewal, inbox drain, tag feed, delivery queue.
-  // Called at connect when the lease is ours, or on viewer promotion.
-  async startActive({ repair = true, promoted = false } = {}) {
-    this.viewer = false;
-    clearInterval(this.refreshTimer);
-    if (promoted) await this.refreshBeforeActing();
-    // Own posts the outbox names and the timeline index lacks come back here,
-    // before anything acts on the index.
-    await this.publisher.healStatuses().catch(e => this.log(`healing the timeline index: ${e.message}`));
-    // Likes made before the liked list existed become its first entries.
-    try { this.publisher.backfillLiked(); } catch (e) { this.log(`liked list: ${e.message}`); }
-    this.lease.onLost = () => this.demote();
-    this.lease.startRenewal();
-    this.deliverer.startQueue();
-    // Parked: no draining (the inbox is closed anyway) and no tag feed, so
-    // starting the agent by accident does not undo the quiet.
-    if (this.store.getConfig()?.quiescedAt) {
-      this.log('parked — not draining or polling; run `fedipod revive` to resume');
-      return;                                // renewal is already running, above
-    }
-    await this.intake.start();
-    // An address that moved here from another gateway, whose move was left
-    // pending (the old gateway could not be told): try again now that this
-    // agent acts and the actor is published.
-    completeGatewayMove(this).catch(e => this.log(`gateway move: ${e.message}`));
-    // Reused, not replaced: demote() stops this instance but does not clear it,
-    // so constructing a new one over the top orphaned the old chain beyond the
-    // reach of any later stop().
-    this.tagfeed ||= new TagFeed({ store: this.store, intake: this.intake, log: this.log });
-    this.tagfeed.start();
-    this.startBsky();
-    this.startAccts();
-    // Scheduled posts and polls whose time is up: a 30s sweep does what has
-    // come due (lib/core/scheduled.mjs).
-    clearInterval(this.schedTimer);
-    this.schedTimer = setInterval(() => {
-      publishDue(this.store, this.publisher, this.log).catch(err => this.log(`scheduled: ${err.message}`));
-    }, 30_000);
-    this.schedTimer.unref();
-    // A CSV import interrupted by a restart or a handoff picks back up here.
-    this.importer?.resume();
-    // The identity the fediverse actually sees: a fronted actor's name and
-    // host are the front's, not the pod's.
-    this.log(`federating as @${publicHandle(this.store.getConfig())}@${new URL(this.urls.actor).host}`);
-    if (this.renamed) {
-      // The display name lives in the actor document, so a rename only
-      // reaches other servers once that is republished.
-      this.renamed = false;
-      this.publisher.publishProfile()
-        .then(() => this.log('actor document republished with the new display name'))
-        .catch(e => this.log(`republish after rename failed: ${e.message}`));
-    }
-    // bootstrap writes the owner-only ACLs once, at setup, and nothing else
-    // ever returns to them — so check on every start that the private trees
-    // really are private, and repair them if not. Off the critical path.
-    this.publisher.ensurePrivateAcls()
-      .catch(e => this.log(`private-ACL check failed: ${e.message}`));
-    // A publish that died half-way leaves an actor nobody can fetch while
-    // everything here looks healthy — one GET to find out, and republishing
-    // is idempotent.
-    // Skipped during setup, which publishes the profile itself a moment later:
-    // running both meant every first run wrote the whole wire face twice.
-    if (repair) {
-      this.ensureActorPublished()
-        .catch(e => this.log(`actor check failed: ${e.message}`));
-      this.ensureFeaturedPublished()
-        .catch(e => this.log(`featured check failed: ${e.message}`));
-      this.ensureInboxOpen()
-        .catch(e => this.log(`inbox door check failed: ${e.message}`));
-      // The human page, rewritten only when what it shows has changed: one
-      // local digest compare, and a write the first time after an upgrade.
-      this.publisher.publishProfilePage()
-        .catch(e => this.log(`profile page: ${e.message}`));
-    }
-    this.seedFollowNotifications().catch(e => this.log(`notification seeding failed: ${e.message}`));
-  }
-
-  // Re-read state before acting on what we hold. A viewer's cache is kept
-  // current by revalidation against the CONTAINER, whose ETag vouches for its
-  // children existing rather than for their contents — so a peer rewriting
-  // contacts.json or statuses.json in place moves nothing this agent would
-  // notice. Only on promotion, never on a timer, and only documents that really
-  // changed come back with a body.
-  async refreshBeforeActing() {
-    if (!this.store.storage) return;
-    await this.store.load({ force: true })
-      .catch(e => this.log(`state refresh on promotion: ${e.message}`));
-  }
-
-  // Another device claimed the lease (its user acted there) — stand down to
-  // viewer so exactly one agent keeps draining.
-  // The Bluesky mirror poll, only ever running when an account is connected.
-  // Reused, not replaced, for the same orphaned-timer reason as tagfeed.
-  startBsky() {
-    if (this.viewer || !this.atproto?.connected()) return;
-    if (this.store.getConfig()?.quiescedAt) return;
-    // A group's account is the group's presence on Bluesky: follows are joins,
-    // mentions are submissions, and both ride the notification hook.
-    if (this.store.getConfig()?.kind === 'group') {
-      this.bskygroup ||= new BskyGroup({
-        store: this.store, atproto: this.atproto, intake: this.intake,
-        publisher: this.publisher, log: this.log,
-      });
-      this.intake.bskyGroup = this.bskygroup;
-    }
-    this.bskyfeed ||= new BskyFeed({
-      store: this.store, atproto: this.atproto, log: this.log,
-      onNotification: async (n) => {
-        if (!this.bskygroup) return;
-        if (n.reason === 'follow') await this.bskygroup.onFollow(n.author);
-        else await this.bskygroup.onMention(n);
-      },
-    });
-    this.bskyfeed.start();
-  }
-
-  stopBsky() { this.bskyfeed?.stop(); }
-
-  // The connected fediverse accounts' poll, only ever running when at least
-  // one is connected. Reused, not replaced, for the same orphaned-timer reason
-  // as tagfeed.
-  startAccts() {
-    if (this.viewer || !this.fediaccts?.connected()) return;
-    if (this.store.getConfig()?.quiescedAt) return;
-    this.acctfeed ||= new AcctFeed({
-      store: this.store, accounts: this.fediaccts, log: this.log,
-    });
-    this.acctfeed.start();
-  }
-
-  stopAccts() { this.acctfeed?.stop(); }
-
-  // Connecting or disconnecting an account changes what there is to poll, and
-  // the last one going leaves a timer with nothing to ask.
-  restartAccts() {
-    this.stopAccts();
-    this.startAccts();
-  }
-
-  demote() {
-    if (this.viewer) return;
-    this.log('another device took over — demoting to viewer');
-    this.intake?.stop();
-    this.tagfeed?.stop();
-    this.bskyfeed?.stop();
-    this.acctfeed?.stop();
-    this.deliverer?.stop();
-    this.importer?.stop();
-    clearInterval(this.schedTimer);
-    this.publisher?.stopPolls();
-    // The lease too: standing down means standing down. Left renewing, a viewer
-    // keeps writing to the pod on the active agent's behalf and can win the
-    // lease back on a conditional PUT it had no business making.
-    this.lease?.stopRenewal();
-    this.startViewer();
-  }
-
-  // A user acting on this viewer outranks the idle active agent elsewhere:
-  // claim the lease now (writes are safe immediately — publishing never
-  // touches the inbox), but hold the destructive inbox drain until the old
-  // active has seen the loss at its next renewal and demoted.
-  async requestTakeover() {
-    if (!this.viewer) return true;
-    if (!(await this.lease.takeover())) return false;
-    this.log('taking over from the other device (user action here)');
-    this.viewer = false;
-    clearInterval(this.refreshTimer);
-    this.lease.onLost = () => this.demote();
-    this.lease.startRenewal();
-    this.deliverer.startQueue();
-    setTimeout(async () => {
-      if (this.viewer) return;                 // lost it again in the meantime
-      try {
-        await this.refreshBeforeActing();
-        await this.intake.start();
-        this.tagfeed ||= new TagFeed({ store: this.store, intake: this.intake, log: this.log });
-        this.tagfeed.start();
-        this.startBsky();
-    this.startAccts();
-        // A stranded CSV import resumes here too — startActive is not on the
-        // takeover path, so without this the rows sat pending until a restart.
-        this.importer?.resume();
-        this.log('takeover complete — draining resumed on this device');
-      } catch (e) { this.log(`takeover drain start: ${e.message}`); }
-    }, 35_000).unref?.();                      // > one renewal interval: old agent has demoted
-    return true;
-  }
-
-  // A first run inherits followers without ever having seen them arrive, so
-  // the notifications list starts empty where it should start full.
-  async seedFollowNotifications() {
-    if (this.store.has('notifications.json')) return;
-    for (const f of this.store.getContacts().followers) {
-      this.store.addNotification({ type: 'follow', actor: f.actor });
-    }
-  }
-}
+// The class is imported from here by the callers that always did.
+export { Agent };
 
 // Two megabytes is a few weeks of an ordinary agent's chatter, and small
 // enough that reading the whole thing is still reasonable.
@@ -759,10 +56,17 @@ export async function startAgent({
   // directory, same unit, same startup — a different thing to run. Its
   // credential says so, and running the agent over it would publish a person
   // where a forum lives.
-  const { isForumHome, runForum } = await import('./packages/fedipod-bb/src/run.mjs');
-  if (isForumHome(home)) {
+  // The forum package is beside this file in a checkout and absent from an
+  // installed fedipod; a home that holds a forum needs it, a person's does not.
+  let forum = null;
+  try {
+    forum = await import('./packages/fedipod-bb/src/run.mjs');
+  } catch (e) {
+    if (e?.code !== 'ERR_MODULE_NOT_FOUND') throw e;
+  }
+  if (forum?.isForumHome(home)) {
     console.log(`[bb:${port}] this home holds a forum — running it`);
-    return runForum({ home, port, log: (...a) => console.log(`[bb:${port}]`, ...a) });
+    return forum.runForum({ home, port, log: (...a) => console.log(`[bb:${port}]`, ...a) });
   }
   // connect() sets this from pod state a moment later, but the browser may
   // already be opening — seed it from what setup recorded so the named origin
@@ -782,7 +86,7 @@ export async function startAgent({
     } catch { /* the agent still runs; it is just harder to find */ }
   }
   const logFile = path.join(home, 'agent.log');
-  const agent = new Agent({ home, log: () => {} });
+  const agent = new Agent({ home, log: () => {}, upgradeCheck: pendingSteps });
   // The port on every line. Agents sharing a home share agent.log, and without
   // it there is no way to tell which one wrote what — a viewer's startup reads
   // as the active one's work.