@join-pantheon/cli 0.32.1 → 0.33.0-rc.2

package/dist/notice-windows.js

@@ -0,0 +1,323 @@
+import { execFileSync, spawn, spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve, win32 } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CONFIG_DIR } from "./config.js";
+import { userEntry } from "./install.js";
+import { childNodeFlags } from "./managed.js";
+import { borrowedProfile } from "./service.js";
+import { CLM_GUARD, GIVE_UP_CODE, hostChildRunning, hostFiles, userSid } from "./win-host.js";
+import { aumidRegistered, buildUri, handlerCommand, handlerEntry, PANTHEON_AUMID, realRegIo, registerUriHandler, uriKey, } from "./uri-handler.js";
+const HERE = fileURLToPath(new URL(".", import.meta.url));
+export const POWERSHELL_AUMID = "{1AC14E77-02E7-4E5D-B744-2EB1AE5198B7}\\WindowsPowerShell\\v1.0\\powershell.exe";
+export const windowsIconPath = () => resolve(HERE, "..", "helper", "windows", "pantheon.ico");
+export const windowsTrayScriptPath = () => resolve(HERE, "..", "helper", "windows", "pantheon-tray.ps1");
+export const TOAST_CAPS = { heading: 80, context: 120, body: 320, who: 80, button: 24 };
+export const BALLOON_CAPS = { title: 63, text: 255 };
+export function toastText(s, max) {
+    const clean = (s ?? "")
+        .replace(/[\t\n\r\v\f]/g, " ")
+        .replace(/[\u0000-\u001f\u007f-\u009f\ufffe\uffff]/g, "")
+        .replace(/[\ud800-\udbff](?![\udc00-\udfff])|(?<![\ud800-\udbff])[\udc00-\udfff]/g, "")
+        .replace(/\s+/g, " ")
+        .trim();
+    const chars = [...clean];
+    return chars.length <= max ? clean : `${chars.slice(0, max - 1).join("").trimEnd()}…`;
+}
+export function xmlEscape(s) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+export function toastButtons(notice, key) {
+    const space = notice.space;
+    const d = notice.details ?? {};
+    const out = [];
+    const add = (content, uri) => { if (uri)
+        out.push({ content, uri }); };
+    if (notice.kind === "decision" && d.decision) {
+        add("Done", buildUri("done", { decision: d.decision, act: d.act, space }, key));
+        add("Explain", buildUri("explain", { decision: d.decision, act: d.act, space }, key));
+    }
+    else if (d.act) {
+        add("Show details", buildUri("details", { act: d.act, decision: d.decision, space }, key));
+    }
+    add("Open board", buildUri("board", {}, key));
+    return out;
+}
+export function toastTag(notice) {
+    const id = notice.details?.decision ?? notice.details?.act ?? "";
+    return /^[A-Za-z0-9_]{1,60}$/.test(id) ? id : "";
+}
+export function toastFields(notice, key) {
+    const lines = [toastText(notice.heading, TOAST_CAPS.heading) || "Pantheon"];
+    const context = toastText(notice.context, TOAST_CAPS.context);
+    const body = toastText(notice.body, TOAST_CAPS.body);
+    if (context)
+        lines.push(context);
+    if (body)
+        lines.push(body);
+    return {
+        lines,
+        who: toastText(notice.who, TOAST_CAPS.who),
+        launch: buildUri("board", {}, key),
+        buttons: toastButtons(notice, key).map((b) => ({ content: toastText(b.content, TOAST_CAPS.button), uri: b.uri })),
+        scenario: notice.ttl === 0 ? "reminder" : "",
+        duration: notice.ttl !== 0 && notice.ttl > 7 ? "long" : "",
+        silent: !notice.sound,
+    };
+}
+export function toastXmlFrom(t) {
+    const attrs = [
+        `activationType="protocol"`, `launch="${xmlEscape(t.launch)}"`,
+        t.scenario ? `scenario="${t.scenario}"` : t.duration ? `duration="${t.duration}"` : "",
+    ].filter(Boolean).join(" ");
+    return [
+        `<toast ${attrs}>`,
+        `<visual><binding template="ToastGeneric">`,
+        ...t.lines.map((l) => `<text>${xmlEscape(l)}</text>`),
+        ...(t.who ? [`<text placement="attribution">${xmlEscape(t.who)}</text>`] : []),
+        `</binding></visual>`,
+        ...(t.buttons.length ? [
+            `<actions>`,
+            ...t.buttons.map((b) => `<action content="${xmlEscape(b.content)}" activationType="protocol" arguments="${xmlEscape(b.uri)}"/>`),
+            `</actions>`,
+        ] : []),
+        t.silent ? `<audio silent="true"/>` : "",
+        `</toast>`,
+    ].filter(Boolean).join("");
+}
+export function toastXml(notice, key) {
+    return toastXmlFrom(toastFields(notice, key));
+}
+export const windowsNoticeScriptPath = () => resolve(HERE, "..", "helper", "windows", "pantheon-notice.ps1");
+const b64 = (s) => Buffer.from(s, "utf8").toString("base64");
+const psQuote = (s) => `'${s.replace(/'/g, "''")}'`;
+export function powershellPath(env = process.env) {
+    return win32.join(env.SystemRoot || env.windir || "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+}
+export function powershellArgs(script, mode) {
+    return ["-NoProfile", "-NonInteractive", "-Command", `${CLM_GUARD}; & ([scriptblock]::Create([IO.File]::ReadAllText(${psQuote(script)}))) -Mode ${mode}`];
+}
+export function balloonText(notice) {
+    const title = toastText(notice.heading, BALLOON_CAPS.title) || "Pantheon";
+    const text = toastText([notice.context, notice.body].filter(Boolean).join(" — "), BALLOON_CAPS.text) || toastText(notice.who, BALLOON_CAPS.text) || "Open Pantheon";
+    return { title, text };
+}
+const aboutOf = (notice) => `${notice.kind}${notice.details?.decision ? ` ${notice.details.decision}` : notice.details?.act ? ` ${notice.details.act}` : ""}`;
+export function queuedNotice(notice, key, aumids, now = Date.now()) {
+    return { v: 2, at: now, about: aboutOf(notice), toast: toastFields(notice, key), tag: toastTag(notice), aumids, balloon: balloonText(notice) };
+}
+export function toastCall(notice, key, aumids, env = process.env, script = windowsNoticeScriptPath()) {
+    return {
+        file: powershellPath(env),
+        args: powershellArgs(script, "toast"),
+        env: { PANTHEON_TOAST_XML: b64(toastXml(notice, key)), PANTHEON_TOAST_TAG: toastTag(notice), PANTHEON_TOAST_AUMIDS: aumids.join(";") },
+    };
+}
+export function balloonCall(notice, icon, env = process.env, script = windowsNoticeScriptPath()) {
+    const { title, text } = balloonText(notice);
+    return {
+        file: powershellPath(env),
+        args: powershellArgs(script, "balloon"),
+        env: { PANTHEON_BALLOON_TITLE: b64(title), PANTHEON_BALLOON_TEXT: b64(text), ...(icon ? { PANTHEON_BALLOON_ICON: icon } : {}) },
+    };
+}
+export const QUEUE_STALE_MS = 30_000;
+export function trayTakesNotices(home, now = Date.now()) {
+    if (!hostChildRunning("tray", home, now))
+        return false;
+    const dir = hostFiles(home).notices;
+    const skipped = skippedNotices(home);
+    try {
+        for (const n of readdirSync(dir)) {
+            if (!n.endsWith(".json"))
+                continue;
+            try {
+                const mtime = statSync(join(dir, n)).mtimeMs;
+                if (now - mtime <= QUEUE_STALE_MS)
+                    continue;
+                const s = skipped.get(n);
+                if (s !== undefined && Math.abs(s - Math.floor(mtime)) <= 1)
+                    continue;
+                return false;
+            }
+            catch { }
+        }
+    }
+    catch { }
+    return true;
+}
+export function skippedNotices(home) {
+    const out = new Map();
+    let text = "";
+    try {
+        text = readFileSync(hostFiles(home).noticesSkipped, "utf8");
+    }
+    catch {
+        return out;
+    }
+    for (const line of text.split(/\r?\n/)) {
+        const m = /^([0-9A-Za-z._-]+\.json)\t(\d{1,16})$/.exec(line.trim());
+        if (m)
+            out.set(m[1], Number(m[2]));
+    }
+    return out;
+}
+export function ownerOnlyAclArgs(dir, sid) {
+    return [dir, "/inheritance:r", "/grant:r", `*${sid}:(OI)(CI)F`];
+}
+function realQueueDirDeps() {
+    const exec = (c, a) => execFileSync(c, a, { encoding: "utf8", windowsHide: true, stdio: ["ignore", "pipe", "pipe"], timeout: 15_000 });
+    return {
+        platform: process.platform,
+        sid: () => userSid(exec),
+        icacls: (args) => { exec(win32.join(process.env.SystemRoot || process.env.windir || "C:\\Windows", "System32", "icacls.exe"), args); },
+    };
+}
+export function ensureQueueDir(dir, deps = realQueueDirDeps()) {
+    if (existsSync(dir))
+        return;
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    if (deps.platform !== "win32")
+        return;
+    try {
+        const sid = deps.sid();
+        if (!sid)
+            throw new Error("could not tell which user this is (whoami), so the alert queue cannot be made private");
+        deps.icacls(ownerOnlyAclArgs(dir, sid));
+        for (const n of readdirSync(dir))
+            rmSync(join(dir, n), { recursive: true, force: true });
+    }
+    catch (e) {
+        rmSync(dir, { recursive: true, force: true });
+        throw e;
+    }
+}
+export function enqueueNotice(home, q, deps) {
+    const dir = hostFiles(home).notices;
+    ensureQueueDir(dir, deps);
+    const name = `${q.at}-${randomBytes(4).toString("hex")}`;
+    const tmp = join(dir, `${name}.tmp`);
+    const f = join(dir, `${name}.json`);
+    writeFileSync(tmp, JSON.stringify(q), { mode: 0o600, flag: "wx" });
+    try {
+        renameSync(tmp, f);
+    }
+    catch (e) {
+        rmSync(tmp, { force: true });
+        throw e;
+    }
+    return f;
+}
+export const NOTICE_COOLDOWN_MS = 5 * 60_000;
+export const CLM_COOLDOWN_MS = 6 * 3600_000;
+let coolUntil = 0;
+let handler = null;
+export function resetWindowsNoticeState() { coolUntil = 0; handler = null; }
+export function ensureUriHandler(io = realRegIo(() => borrowedProfile()), entry = userEntry("win32"), o = {}) {
+    const command = handlerCommand(handlerEntry(entry, o.flags ?? childNodeFlags()), o.home === undefined ? nonDefaultPantheonHome() : o.home);
+    if (!command)
+        return { ok: false, aumid: false, line: "pantheon: links not registered — no node.exe and cli.js to name (a pantheon.cmd is never registered)" };
+    const icon = windowsIconPath();
+    const r = registerUriHandler(command, io, existsSync(icon) ? icon : undefined);
+    return { ok: r.ok, aumid: r.ok && aumidRegistered(io), line: r.line };
+}
+function nonDefaultPantheonHome() {
+    return resolve(CONFIG_DIR).toLowerCase() === resolve(join(homedir(), ".pantheon")).toLowerCase() ? null : resolve(CONFIG_DIR);
+}
+function logTo(home) {
+    return (line) => {
+        try {
+            mkdirSync(join(home, "logs"), { recursive: true });
+            appendFileSync(join(home, "logs", "alerts.log"), `${new Date().toISOString()} ${line}\n`, { mode: 0o600 });
+        }
+        catch { }
+    };
+}
+function realDeps(home) {
+    const icon = windowsIconPath();
+    const childEnv = (call) => ({ ...process.env, PANTHEON_HOME: home, ...call.env });
+    return {
+        trayReady: () => trayTakesNotices(home),
+        enqueue: (q) => { enqueueNotice(home, q); },
+        run: (call, timeoutMs) => {
+            const r = spawnSync(call.file, call.args, { env: childEnv(call), windowsHide: true, timeout: timeoutMs, stdio: ["ignore", "pipe", "pipe"], encoding: "utf8" });
+            const said = (r.stdout ?? "").trim().split(/\r?\n/).filter(Boolean).join(" | ");
+            if (said)
+                logTo(home)(`toast: ${said.slice(0, 300)}`);
+            return r.error ? null : r.status;
+        },
+        detach: (call) => {
+            try {
+                const c = spawn(call.file, call.args, { env: childEnv(call), windowsHide: true, detached: true, stdio: "ignore" });
+                c.on("error", () => { });
+                c.unref();
+                return typeof c.pid === "number";
+            }
+            catch {
+                return false;
+            }
+        },
+        ensureHandler: () => {
+            const r = ensureUriHandler();
+            logTo(home)(`links: ${r.line}`);
+            return { aumid: r.aumid };
+        },
+        markClm: () => { try {
+            const f = hostFiles(home);
+            mkdirSync(f.dir, { recursive: true });
+            writeFileSync(f.clm, new Date().toISOString());
+        }
+        catch { } },
+        log: logTo(home),
+        icon: existsSync(icon) ? icon : null,
+        now: Date.now,
+    };
+}
+export function showWindowsNotice(notice, home, deps = realDeps(home)) {
+    if (deps.now() < coolUntil)
+        return false;
+    if (!handler) {
+        try {
+            handler = deps.ensureHandler();
+        }
+        catch {
+            handler = { aumid: false };
+        }
+    }
+    const key = uriKey(home);
+    const aumids = handler.aumid ? [PANTHEON_AUMID, POWERSHELL_AUMID] : [POWERSHELL_AUMID];
+    const about = aboutOf(notice);
+    if (deps.trayReady()) {
+        try {
+            deps.enqueue(queuedNotice(notice, key, aumids, deps.now()));
+            deps.log(`handed to the tray: ${about}`);
+            return true;
+        }
+        catch (e) {
+            deps.log(`could not hand ${about} to the tray (${e.message.split("\n")[0]}) — showing it directly`);
+        }
+    }
+    const code = deps.run(toastCall(notice, key, aumids), 15_000);
+    if (code === 0) {
+        deps.log(`shown: ${about}`);
+        return true;
+    }
+    if (code === GIVE_UP_CODE) {
+        deps.markClm();
+        coolUntil = deps.now() + CLM_COOLDOWN_MS;
+        deps.log(`not shown: ${about} — PowerShell runs in Constrained Language Mode here (an IT policy), which refuses Windows alerts; pantheon board shows the same. Next try in ${CLM_COOLDOWN_MS / 3600_000} hours`);
+        return false;
+    }
+    if (code === 3 || code === 4) {
+        if (deps.detach(balloonCall(notice, deps.icon))) {
+            deps.log(`handed to a balloon: ${about} (toast exit ${code})`);
+            return true;
+        }
+    }
+    coolUntil = deps.now() + NOTICE_COOLDOWN_MS;
+    deps.log(`not shown: ${about} — toast exit ${code ?? "timeout or no PowerShell"}; next try in ${NOTICE_COOLDOWN_MS / 60_000} minutes`);
+    return false;
+}
+//# sourceMappingURL=notice-windows.js.map

package/dist/notifier.js

@@ -1,3 +1,5 @@
+import { showWindowsNotice } from "./notice-windows.js";
+import { showLinuxNotice } from "./notice-linux.js";
 import { spawn } from "node:child_process";
 import { helperStale, installHelper } from "./helpers-build.js";
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
@@ -107,6 +109,10 @@ export function preferredTool(profile, tools, home = CONFIG_DIR) {
     return profile.agent.primary_surface;
 }
 export function sendDesktopNotification(notice, home = CONFIG_DIR) {
+    if (platform() === "win32")
+        return showWindowsNotice(notice, home);
+    if (platform() === "linux")
+        return showLinuxNotice(notice, home);
     if (platform() !== "darwin")
         return false;
     const binary = hudBinaryPath(home);
@@ -154,12 +160,15 @@ export class HumanNotifier {
                 : [];
             const tools = installedTools();
             const peerOf = (from) => from ? { member: from, agent: client.roster.find((m) => m.id === from)?.agent } : undefined;
-            const withLabel = (n) => this.opts.label ? { ...n, context: n.context ? `${this.opts.label} · ${n.context}` : this.opts.label } : n;
+            const withLabel = (n) => {
+                const labelled = this.opts.label ? { ...n, context: n.context ? `${this.opts.label} · ${n.context}` : this.opts.label } : n;
+                return platform() === "darwin" ? labelled : { ...labelled, space: this.cfg.space };
+            };
             for (const obligation of due) {
                 const isReminder = state.notified_at[obligation.id] !== undefined;
                 const act = client.seenAct(obligation.ref);
                 const notice = withLabel(composeDecision(obligation, act, obligation.goal ? client.goals.get(obligation.goal) : undefined, peerOf(act?.from), { tools, preferred: preferredTool(profile, tools), now: now(), member: this.cfg.member }));
-                const ok = send(notice);
+                const ok = await send(notice);
                 if (ok) {
                     state.notified_at[obligation.id] = now();
                     if (isReminder)
@@ -182,7 +191,7 @@ export class HumanNotifier {
                     const forMe = (r.to?.includes(this.cfg.member) ?? false) || (goal?.members.includes(this.cfg.member) ?? false);
                     if (!forMe)
                         continue;
-                    const ok = send(withLabel(composeDelivery(r, goal, peerOf(r.from), { tools, preferred: preferredTool(profile, tools), now: now() })));
+                    const ok = await send(withLabel(composeDelivery(r, goal, peerOf(r.from), { tools, preferred: preferredTool(profile, tools), now: now() })));
                     if (ok) {
                         state.notified_at[`act:${r.id}`] = now();
                         writeState(stateFile, state);

package/dist/quickstart.js

@@ -1,12 +1,13 @@
 import { execFileSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import { createServer } from "node:net";
-import { basename, dirname, join as pathJoin, resolve as resolvePath } from "node:path";
+import { basename, join as pathJoin, resolve as resolvePath } from "node:path";
 import { homedir, hostname, platform, userInfo } from "node:os";
 import { lookup } from "node:dns/promises";
 import { describeNetError } from "./network.js";
 import { PantheonClient } from "./client.js";
 import { holdsRepo } from "./repo-find.js";
+import { folderFacts, folderRefusal, folderRefusalHere, isInside, isTemporaryRefusal } from "./folder-guard.js";
 import { load, loadAll, identity, save, toInvite, resolveFor, repoInfo, bindRepo, bindFolder, folderBinding, DEFAULT_RELAY } from "./config.js";
 import { commandsChosen, loadProfile, wakeChosen, wakeDefault } from "./profile.js";
 import { newKeypair } from "./identity.js";
@@ -14,6 +15,7 @@ import { installForUser } from "./install.js";
 import { writeIntent, installHooks } from "./notify.js";
 import { detectAvailable, agentById, agentsNeedingUnsandboxed } from "./agents.js";
 import { installService, servicesUnavailable } from "./service.js";
+import { clearTrayQuit } from "./win-host.js";
 import { ensureNativeNotifier } from "./notifier.js";
 import { ensureTrayBinary, writeTrayCommands } from "./tray.js";
 import { desktopUnavailable, ephemeralWarning, hostEnv } from "./host-env.js";
@@ -39,7 +41,7 @@ export function wireUp(opts, deps = {}) {
     const ensureTray = deps.ensureTray ?? ensureTrayBinary;
     const host = deps.host ?? hostEnv();
     const noServices = servicesUnavailable(host.platform);
-    const tools = installForUser().map((t) => ({ tool: t.tool, status: t.status }));
+    const tools = installForUser(undefined, undefined, { direct: true }).map((t) => ({ tool: t.tool, status: t.status }));
     const granted = [];
     const warnings = [];
     if (host.ephemeral)
@@ -66,9 +68,12 @@ export function wireUp(opts, deps = {}) {
     }
     else if (opts.notifications) {
         try {
-            ensureNotifier();
+            const mac = host.platform === "darwin";
+            if (mac)
+                ensureNotifier();
             const why = notLoaded(installSvc("notifier", homedir(), []));
-            writeTrayCommands();
+            if (mac)
+                writeTrayCommands();
             if (why) {
                 tools.push({ tool: "notifications", status: `installed, not running: ${why}` });
                 warnings.push(`human notifications are installed but not running (${why}). Try \`pantheon service restart notifier\``);
@@ -84,8 +89,13 @@ export function wireUp(opts, deps = {}) {
     else {
         tools.push({ tool: "notifications", status: "off (--no-notifications) — human escalations only appear in pantheon status" });
     }
-    if (opts.menubar && !host.desktop) {
-        tools.push({ tool: "menu bar", status: desktopUnavailable(host, "the menu bar") });
+    const noMenubar = desktopUnavailable(host, "the menu bar");
+    if (opts.menubar && noMenubar) {
+        tools.push({ tool: "menu bar", status: noMenubar });
+    }
+    else if (opts.menubar && host.platform === "win32") {
+        const wasQuit = clearTrayQuit();
+        tools.push({ tool: "tray", status: `comes with the background host — the Pantheon icon in the notification area${wasQuit ? " (you had quit it; it shows again)" : ""}` });
     }
     else if (opts.menubar) {
         try {
@@ -491,6 +501,8 @@ export async function start(opts) {
                 bindFolder(process.cwd(), c.spaceId);
                 folderBound = process.cwd();
             }
+            else if (!repo && c.spaceId)
+                temporaryFolderNote(process.cwd(), opts.log, c.space);
             if (repo && c.spaceId) {
                 const { replaced } = bindRepo(repo, c.spaceId);
                 const was = replaced ?? (here.binding && here.binding.space !== c.spaceId ? here.binding : null);
@@ -578,6 +590,8 @@ export async function join(opts) {
         bindFolder(process.cwd(), cfg.spaceId);
         opts.log(`  folder     ${process.cwd()} → bound to "${cfg.space}"   (agents opened here speak in it; no git needed)`);
     }
+    else if (!repo && cfg.spaceId)
+        temporaryFolderNote(process.cwd(), opts.log, cfg.space);
     if (repo && cfg.spaceId) {
         const { replaced } = bindRepo(repo, cfg.spaceId);
         if (replaced)
@@ -605,10 +619,8 @@ export function bindableFolder(dir) {
     catch {
         return resolvePath(d);
     } };
-    const here = real(dir), home = real(homedir());
-    if (dirname(here) === here || here === home || home.startsWith(here.endsWith("/") ? here : `${here}/`))
-        return false;
-    if (["Downloads", "Desktop", "Documents", "Library", "tmp"].some((n) => here === pathJoin(home, n)))
+    const here = real(dir);
+    if (folderRefusal(here, folderFacts()))
         return false;
     try {
         if (holdsRepo(here))
@@ -619,12 +631,17 @@ export function bindableFolder(dir) {
     }
     try {
         const f = loadAll();
-        if (Object.values(f?.bindings ?? {}).some((b) => { const p = real(b.path); return p !== here && p.startsWith(`${here}/`); }))
+        if (Object.values(f?.bindings ?? {}).some((b) => { const p = real(b.path); return isInside(p, here) && !isInside(here, p); }))
             return false;
     }
     catch { }
     return true;
 }
+function temporaryFolderNote(dir, log, team) {
+    const r = folderRefusalHere(dir);
+    if (isTemporaryRefusal(r))
+        log(`  folder     not bound — ${r.why.replace("<team>", team)}`);
+}
 function detectAgent() {
     const found = detectAvailable();
     return found[0]?.backend.id ?? "unknown";

package/dist/relay.js

@@ -6,14 +6,14 @@ import { join } from "node:path";
 import { WebSocketServer } from "ws";
 import { badRemote, Inbound, isContinuationFor, LIMITS, newId, PROTOCOL_VERSION, RELAY_FEATURES, SENDABLE, shouldDeferToHuman, } from "./protocol.js";
 import { VERSION } from "./version.js";
-import { installerScript, InstallerGate } from "./installer.js";
+import { compareVersions, INSTALLER_MIN_CLI, isVersion, installerScript, InstallerGate } from "./installer.js";
 import { installerLine } from "./managed.js";
 import { Ledger, SpaceFull } from "./ledger.js";
 import { fingerprint, newNonce, verifyChallenge, verifyActivity, verifyAccount, verifyRead, actPayload, goalPayload, verifyBytes, verifyDelegate, canonicalJson } from "./identity.js";
 import { Accounts, normalizeUsername, validEmail, validUsername } from "./accounts.js";
 import { emailSenderFromEnv } from "./email.js";
 import { Allowlist, RosterUnreadable } from "./roster-file.js";
-import { StateStore, ensurePrivateDir } from "./store.js";
+import { StateStore, ensurePrivateDir, setWaitForDisk, takeSlowestDiskWait, waitsForDisk } from "./store.js";
 import { activity, mergeActivity, feed, noteRefusal, refusalsSince, countActs, spaceHealth, fleetReport, ESCALATIONS, MESSAGE_ACTS, ACT_TONE, DAY } from "./admin-stats.js";
 import { fmtLimit, inviteLimit, parseLimits, planLimits, PLAN_NAME } from "./plans.js";
 import { FEEDBACK_ADDRESS } from "./feedback.js";
@@ -366,8 +366,35 @@ function withoutFromRepo(meta) {
     const { from_repo: _f, ...rest } = meta;
     return rest;
 }
+export function upgradeHoldFrom(raw, relayVersion, log = () => { }) {
+    const v = (raw ?? "").trim();
+    if (!v)
+        return null;
+    if (!isVersion(v)) {
+        log(`! PANTHEON_HOLD_UPGRADES_AT is "${v}", which is not a version — ignored, upgrades are not held`);
+        return null;
+    }
+    if (v.includes("-")) {
+        log(`! PANTHEON_HOLD_UPGRADES_AT is ${v}, a prerelease — ignored; hold at a release (x.y.z)`);
+        return null;
+    }
+    if (compareVersions(v, relayVersion) > 0) {
+        log(`! PANTHEON_HOLD_UPGRADES_AT is ${v}, newer than this relay (${relayVersion}) — ignored`);
+        return null;
+    }
+    if (compareVersions(v, INSTALLER_MIN_CLI) < 0) {
+        log(`! PANTHEON_HOLD_UPGRADES_AT is ${v}, older than ${INSTALLER_MIN_CLI}, the oldest release the installer serves — ignored`);
+        return null;
+    }
+    log(`* upgrades held at ${v}: workers will not move past it, and new installs get it (this relay runs ${relayVersion})`);
+    return v;
+}
+export function advertisedPkg(hold, relayVersion) {
+    return hold ?? (relayVersion.includes("-") ? null : relayVersion);
+}
 export class Relay {
     opts;
+    advertisedPkg() { return advertisedPkg(this.upgradeHold, VERSION); }
     spaces = new Map();
     dataDir;
     log;
@@ -410,6 +437,9 @@ export class Relay {
     });
     wss = new WebSocketServer({ noServer: true, maxPayload: 256 * 1024 });
     heartbeat;
+    lagTimer;
+    lagMax = 0;
+    fsyncOff = false;
     compactedAt = new Map();
     sessionSeq = 0;
     spaceCreates = new Map();
@@ -437,11 +467,17 @@ export class Relay {
     rotateOnRemove;
     backupTimer;
     installerGate;
+    upgradeHold;
     get features() { return this.opts.features ?? RELAY_FEATURES; }
     constructor(opts = {}) {
         this.opts = opts;
         this.dataDir = opts.dataDir ?? "./pantheon-data";
         this.log = opts.log ?? ((l) => console.error(l));
+        if ((opts.fsync ?? process.env.PANTHEON_RELAY_FSYNC) === "off" && waitsForDisk()) {
+            setWaitForDisk(false);
+            this.fsyncOff = true;
+            this.log("* PANTHEON_RELAY_FSYNC=off: writes go to the operating system at once but the relay does not wait for the disk to confirm them (a relay crash loses nothing; a host power loss can lose the last seconds)");
+        }
         ensurePrivateDir(this.dataDir);
         this.maxLedgerBytes = opts.spaceMaxBytes
             ?? (Number(process.env.PANTHEON_SPACE_MAX_BYTES) > 0 ? Number(process.env.PANTHEON_SPACE_MAX_BYTES) : SPACE_MAX_BYTES_DEFAULT);
@@ -474,7 +510,8 @@ export class Relay {
             spaceMinAgeMs: opts.spaceLimits?.spaceMinAgeMs ?? LIMITS.spaceMinAgeMs,
         };
         this.rotateOnRemove = opts.rotateOnRemove ?? process.env.PANTHEON_ROTATE_ON_REMOVE === "1";
-        this.installerGate = opts.installerGate ?? new InstallerGate({ log: this.log });
+        this.upgradeHold = upgradeHoldFrom(opts.upgradeHoldAt ?? process.env.PANTHEON_HOLD_UPGRADES_AT, VERSION, this.log);
+        this.installerGate = opts.installerGate ?? new InstallerGate({ log: this.log, ...(this.upgradeHold ? { version: this.upgradeHold } : {}) });
         this.busyTtlMs = opts.activityBusyTtlMs ?? LIMITS.activityBusyTtlMs;
         this.pruneMs = opts.activityPruneMs ?? LIMITS.activityPruneMs;
         const readsEnv = (process.env.PANTHEON_READS ?? "").trim().toLowerCase();
@@ -495,7 +532,10 @@ export class Relay {
         const host = this.opts.host ?? "0.0.0.0";
         return new Promise((resolve) => {
             this.http.listen(want, host, () => {
-                this.heartbeat = setInterval(() => this.sweep(), 15_000);
+                this.heartbeat = setInterval(() => { this.sweep(); this.noteStalls(); }, 15_000);
+                let last = Date.now();
+                this.lagTimer = setInterval(() => { const now = Date.now(); this.lagMax = Math.max(this.lagMax, now - last - 500); last = now; }, 500);
+                this.lagTimer.unref?.();
                 this.startBackups();
                 const addr = this.http.address();
                 const port = typeof addr === "object" && addr ? addr.port : want;
@@ -519,6 +559,12 @@ export class Relay {
             this.accounts.close();
         if (this.heartbeat)
             clearInterval(this.heartbeat);
+        if (this.lagTimer)
+            clearInterval(this.lagTimer);
+        if (this.fsyncOff) {
+            setWaitForDisk(true);
+            this.fsyncOff = false;
+        }
         for (const ws of this.wss.clients)
             ws.terminate();
         await new Promise((r) => this.wss.close(() => r()));
@@ -591,7 +637,9 @@ export class Relay {
                 ok: !sf,
                 ...(sf ? { storage: { error: sf.message, where: sf.where, at: new Date(sf.at).toISOString() } } : {}),
                 v: PROTOCOL_VERSION,
-                pkg: VERSION,
+                ...(this.advertisedPkg() ? { pkg: this.advertisedPkg() } : {}),
+                ...(this.advertisedPkg() !== VERSION ? { relay_pkg: VERSION } : {}),
+                ...(this.upgradeHold ? { upgrades_held_at: this.upgradeHold } : {}),
                 ...(commit ? { commit } : {}),
                 ...(adminView && this.unbound.size ? { unbound_spaces: [...this.unbound].sort() } : {}),
                 space_count: this.spaces.size,
@@ -781,7 +829,7 @@ export class Relay {
                 if (url.searchParams.get("format") === "json")
                     return this.json(res, 200, { relay: VERSION, relay_age_ms: relayAgeMs, generated: Date.now(), spaces: rows });
                 res.writeHead(200, { "content-type": "text/plain; charset=utf-8" });
-                return void res.end(fleetReport(rows, VERSION, Date.now(), relayAgeMs) + "\n");
+                return void res.end(fleetReport(rows, this.upgradeHold ?? VERSION, Date.now(), relayAgeMs) + "\n");
             }
             if (url.pathname === "/admin/export") {
                 if (!authed)
@@ -1288,7 +1336,7 @@ button:hover{background:#1d4ed8}.err{color:var(--bad);margin-top:12px}
             out.push(spaceHealth({
                 name: sp.name, records: sp.ledger.all(), members: sp.allow.all(),
                 online: sessions.length, interactive: sessions.filter((x) => x.role === "interactive").length,
-                relayPkg: VERSION, now, relayAgeMs: now - this.startedAt,
+                relayPkg: this.upgradeHold ?? VERSION, now, relayAgeMs: now - this.startedAt,
             }));
         }
         let files = [];
@@ -1307,7 +1355,7 @@ button:hover{background:#1d4ed8}.err{color:var(--bad);margin-top:12px}
                 members = new Allowlist(this.dataDir, safe).all();
             }
             catch { }
-            out.push(spaceHealth({ name: safe, records: this.sleepingRecords(safe), members, online: 0, interactive: 0, relayPkg: VERSION, now, relayAgeMs: now - this.startedAt }));
+            out.push(spaceHealth({ name: safe, records: this.sleepingRecords(safe), members, online: 0, interactive: 0, relayPkg: this.upgradeHold ?? VERSION, now, relayAgeMs: now - this.startedAt }));
         }
         return out;
     }
@@ -1951,7 +1999,7 @@ button:hover{background:#1d4ed8}.err{color:var(--bad);margin-top:12px}
 ${ADMIN_CSS}
 <header>
   <h1>pantheon · admin</h1>
-  <span class=meta>${esc(this.opts.host ?? "relay")} · pkg ${VERSION} · up ${upMin < 60 ? upMin + "m" : Math.round(upMin / 60) + "h"}</span>
+  <span class=meta>${esc(this.opts.host ?? "relay")} · pkg ${VERSION}${this.upgradeHold ? ` · upgrades held at ${esc(this.upgradeHold)}` : ""} · up ${upMin < 60 ? upMin + "m" : Math.round(upMin / 60) + "h"}</span>
   <span class=links><a href="/admin/export?table=audit&format=csv">export audit CSV</a><a href="/admin/export?table=accounts&format=json">accounts JSON</a><a href="/admin/backup">download backup</a><a href="/admin/logout">sign out</a></span>
 </header>
 <nav class=jump aria-label="Sections"><a href="#s-activity">Activity</a><a href="#s-spaces">Spaces</a><a href="#s-accounts">Accounts</a><a href="#s-plans">Plans</a><a href="#s-sessions">Sessions</a><a href="#s-blocks">Blocked</a><a href="#s-codes">Codes</a><a href="#s-audit">Audit log</a></nav>
@@ -3244,6 +3292,13 @@ pantheon start</code></pre>
         } });
         ws.on("error", () => { });
     }
+    noteStalls() {
+        const worst = this.lagMax;
+        this.lagMax = 0;
+        const disk = takeSlowestDiskWait();
+        if (worst >= 1000)
+            this.log(`! the relay could not answer for up to ${(worst / 1000).toFixed(1)} s in the last 15 s${disk ? ` (longest disk wait ${(disk / 1000).toFixed(1)} s)` : ""}`);
+    }
     sweep() {
         for (const ws of this.wss.clients) {
             const s = ws;