conductor-remote 1.35.2 → 1.36.1

package/dist-node/src/nosleep-helper.js

@@ -0,0 +1,249 @@
+// The root half of `nosleep`, in one place.
+//
+// The same POSIX-sh body runs two ways: piped to `sudo sh -c` (asks for your
+// password) or as the root-owned helper `nosleep setup` installs (doesn't). Keeping
+// one copy is what stops those two paths from drifting into different restore
+// behaviour, which is the half that matters — an un-restored `disablesleep` leaves
+// a Mac that can never sleep again.
+//
+// It reads its arguments rather than having them interpolated in, because the
+// installed helper is a fixed file that a sudoers rule names: the duration has to
+// arrive at run time, and the rule grants the path with no argument pattern. So the
+// script validates its own input (digits only) instead of trusting the caller.
+//
+// Strip-clean (plain-node type-stripping), stdlib-only — see CLAUDE.md.
+// biome-ignore-all lint/suspicious/noTemplateCurlyInString: the shell body is full of POSIX parameter expansions (${1:-0}, ${sb:-1}) in ordinary strings — that is the point, not a mis-typed template literal.
+import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import { promisify } from 'node:util';
+const execFileP = promisify(execFile);
+/** Absolute path of the root-owned helper. Must sit in a directory only root can write. */
+export const HELPER_PATH = '/usr/local/libexec/conductor-remote-nosleep';
+/**
+ * Where the armed window records itself: `<pid> <expiry-epoch> <start-token>` (expiry
+ * 0 = until killed). Written by root, mode 0644, because the relay has to *read* it on
+ * every status poll and a sudo round-trip per poll would be absurd. It is the lock as
+ * well as the record — see the one-owner note on NOSLEEP_BODY.
+ *
+ * The third field is the process's own start time with the spaces squeezed out, and it
+ * is what makes the pid trustworthy. A pid alone is not an identity: a window killed
+ * with SIGKILL leaves this file behind, macOS recycles pids freely, and the helper runs
+ * as root — so `kill -0` succeeds against whatever inherited the number, and `--stop`
+ * would then SIGTERM an unrelated root process. Readers that only want the pid and the
+ * expiry (`src/nosleep.ts` ▸ readPidfile) can ignore it; a two-field file from an older
+ * version still parses, and skips the check.
+ */
+export const PIDFILE_PATH = '/var/run/conductor-remote-nosleep.pid';
+/**
+ * sudo's `@includedir` skips any drop-in whose name contains a dot or ends in `~`,
+ * silently — so this filename has neither, and adding an extension would install a
+ * file that reads fine and never takes effect.
+ */
+export const SUDOERS_PATH = '/etc/sudoers.d/conductor-remote';
+/**
+ * `$1` = seconds to stay awake, 0 = until killed, or one of `--check` / `--stop`.
+ * `$2` = optional display label ("90m") echoed back in the confirmation, validated to
+ * the same charset the CLI accepts so nothing arbitrary reaches the terminal.
+ *
+ * Restore is on the EXIT trap only; INT/TERM/HUP just `exit`, so a signal can't run
+ * the restore twice. The captured values are read *before* anything changes and put
+ * back verbatim — never defaults, or a `standby 0` somebody set on purpose gets
+ * clobbered. `sleep` runs in the background with an explicit `wait` because a
+ * foreground `sleep` makes the shell defer its trap until the sleep ends, which for
+ * a 2h window means SIGTERM does nothing for 2h.
+ *
+ * **Exactly one window may be armed**, and arming takes over rather than refusing.
+ * Capture-and-restore is only correct for a single owner: a second window would
+ * capture the *first* one's already-flipped values (standby 0, disablesleep 1) and
+ * "restore" those on its way out, leaving a Mac that can never sleep again. So a new
+ * arm signals the incumbent and waits for its restore to land before capturing. That
+ * is also why the phone arming a window kills one you left running in a terminal —
+ * intended, and the reason `--stop` exists rather than a plain `kill`, since the
+ * armed process runs as root and you can't signal it yourself.
+ *
+ * **That wait is bounded, so it must fail closed.** Waiting forever would hang the
+ * relay's arm request; capturing anyway is the one move that produces the permanent
+ * failure above, and it is reachable — an incumbent stuck in `pmset`, or a pid that
+ * was recycled while the record went stale, never answers the signal. So the wait
+ * expiring is an error (exit 75, EX_TEMPFAIL), not a green light. Refusing to arm
+ * costs a phone tap. Capturing the flipped values costs a Mac that cannot sleep,
+ * silently, with nothing armed to point at.
+ */
+export const NOSLEEP_BODY = [
+    'set -u',
+    '',
+    `pidfile=${PIDFILE_PATH}`,
+    '',
+    // A pid is not an identity — see the PIDFILE_PATH note. Squeezing the spaces out of
+    // `lstart` makes it one whitespace-delimited token, so the record stays a single
+    // awk-readable line and a stale pid that has been recycled fails to match.
+    'procStart() { ps -p "$1" -o lstart= 2>/dev/null | tr -d \' \\n\'; }',
+    '',
+    '# The pid of the armed window, or empty when nothing valid is recorded.',
+    'armedPid() {',
+    '\t[ -f "$pidfile" ] || return 0',
+    '\tset -- $(awk \'NR==1{print $1, $2, $3}\' "$pidfile" 2>/dev/null)',
+    '\tp=${1:-}',
+    '\ttok=${3:-}',
+    '\tcase "$p" in \'\' | *[!0-9]*) return 0 ;; esac',
+    '\tkill -0 "$p" 2>/dev/null || return 0',
+    // No token means a record from an older version: fall back to the pid alone rather
+    // than treating a live window as absent, which would let a second one arm alongside it.
+    '\tif [ -n "$tok" ] && [ "$(procStart "$p")" != "$tok" ]; then return 0; fi',
+    '\techo "$p"',
+    '}',
+    '',
+    'arg=${1:-0}',
+    // The probe `helperReady()` runs. It has to be the real path under the real sudo
+    // rule — the files being present proves nothing, since a drop-in with the wrong
+    // mode or a name includedir skips sits there looking installed and does nothing.
+    'if [ "$arg" = --check ]; then echo ok; exit 0; fi',
+    // Disarm. Root-only by necessity: the armed process runs as root, so nothing the
+    // relay does as itself can signal it. Reached through the same sudoers rule.
+    'if [ "$arg" = --stop ]; then',
+    '\tp=$(armedPid)',
+    '\tif [ -n "$p" ]; then kill -TERM "$p" 2>/dev/null; echo stopped; else rm -f "$pidfile"; echo idle; fi',
+    '\texit 0',
+    'fi',
+    'secs=$arg',
+    'label=${2:-}',
+    "case \"$secs\" in '' | *[!0-9]*) echo 'nosleep: seconds must be digits (0 = until killed)' >&2; exit 64 ;; esac",
+    'case "$label" in *[!0-9smh]*) label=\'\' ;; esac',
+    '',
+    '# Take over from any incumbent BEFORE capturing, or we would capture its flipped',
+    '# values and restore those — the one way this leaves a Mac unable to sleep.',
+    'old=$(armedPid)',
+    'if [ -n "$old" ] && [ "$old" != "$$" ]; then',
+    '\tkill -TERM "$old" 2>/dev/null',
+    '\tn=0',
+    '\twhile kill -0 "$old" 2>/dev/null && [ "$n" -lt 50 ]; do sleep 0.1; n=$((n + 1)); done',
+    // Fail closed. Capturing now would read the incumbent's flipped values and "restore"
+    // those on the way out, which is the permanent no-sleep this whole block exists to stop.
+    '\tif kill -0 "$old" 2>/dev/null; then',
+    '\t\techo "nosleep: the armed window ($old) did not stop within 5s; refusing to arm" >&2',
+    '\t\texit 75',
+    '\tfi',
+    'fi',
+    '',
+    '# Per-source values live in the Battery Power block; disablesleep is global.',
+    'battval() { pmset -g custom | awk -v k="$1" \'/^Battery Power:/{b=1;next} /^AC Power:/{b=0} b&&$1==k{print $2;exit}\'; }',
+    'sb=$(battval standby)',
+    'pn=$(battval powernap)',
+    "ds=$(pmset -g | awk '/SleepDisabled/{print $2;exit}')",
+    '',
+    "sleeper=''",
+    'cleanup() {',
+    '\tif [ -n "$sleeper" ]; then kill "$sleeper" 2>/dev/null || true; fi',
+    '\tpmset -b standby "${sb:-1}" powernap "${pn:-1}"',
+    '\tpmset -a disablesleep "${ds:-0}"',
+    // Only clear the record if it is still ours: a successor that already took over
+    // has written its own, and wiping that would strand it as invisible.
+    '\tif [ "$(awk \'NR==1{print $1}\' "$pidfile" 2>/dev/null)" = "$$" ]; then rm -f "$pidfile"; fi',
+    '}',
+    '# Armed before anything changes, so even a pmset that fails half-way reverts.',
+    'trap cleanup EXIT',
+    "trap 'exit 130' INT",
+    "trap 'exit 143' TERM HUP",
+    '',
+    'pmset -b standby 0 powernap 0',
+    'pmset -a disablesleep 1',
+    '',
+    'until=0',
+    'if [ "$secs" -gt 0 ]; then until=$(( $(date +%s) + secs )); fi',
+    // 0644 so the relay can poll the state without a sudo round-trip per tick.
+    'printf \'%s %s %s\\n\' "$$" "$until" "$(procStart $$)" > "$pidfile" && chmod 644 "$pidfile"',
+    '',
+    '# A long window is ambiguous without the weekday: "until 15:45" reads as today.',
+    'clock() {',
+    '\tif [ "$(date -r "$1" \'+%j\')" = "$(date \'+%j\')" ]; then date -r "$1" \'+%H:%M\'; else date -r "$1" \'+%a %H:%M\'; fi',
+    '}',
+    '',
+    // Printed from in here, after pmset applies: it is the only signal that the
+    // password landed and the setting actually took. The clock starts here too, not
+    // when the command was typed.
+    "echo ''",
+    'if [ "$secs" -gt 0 ]; then',
+    '\tsuffix=""',
+    '\tif [ -n "$label" ]; then suffix="$label, "; fi',
+    '\techo "✓ Sleep disabled until $(clock "$until") (${suffix}incl. lid closed). Ctrl-C to restore."',
+    '\tsleep "$secs" &',
+    'else',
+    '\techo "✓ Sleep disabled at $(date \'+%H:%M\') (incl. lid closed) — until you press Ctrl-C."',
+    '\tsleep 2147483647 &',
+    'fi',
+    'sleeper=$!',
+    'wait "$sleeper"'
+].join('\n');
+/** The helper as installed: the shared body with a shebang and a note on where it came from. */
+export function helperFile() {
+    return [
+        '#!/bin/sh',
+        '# conductor-remote nosleep helper — installed by `conductor-remote nosleep setup`.',
+        '#',
+        `# Runs as root via a scoped NOPASSWD rule in ${SUDOERS_PATH}. That rule is only`,
+        '# as safe as this file: it MUST stay root-owned and non-writable by anyone else, or',
+        '# granting it passwordless root grants passwordless root to everything.',
+        '# Remove both with `conductor-remote nosleep setup --uninstall`.',
+        '',
+        NOSLEEP_BODY,
+        ''
+    ].join('\n');
+}
+/**
+ * The helper as it exists on disk, or null when it isn't installed. Compared against
+ * `helperFile()` to catch the copy going stale: the package self-updates and this
+ * file deliberately does not follow, so drift is a thing to report, never to fix
+ * behind the user's back (see the supply-chain note in nosleep-setup.ts).
+ */
+export function installedHelper() {
+    try {
+        return fs.readFileSync(HELPER_PATH, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * True when the helper will actually run as root without a password.
+ *
+ * It runs the real command under the real rule, because every cheaper check lies.
+ * `sudo -l <cmd>` answers "may this user run it", which is yes for anyone holding
+ * blanket `(ALL) ALL` whether or not NOPASSWD applies (measured on this Mac: an
+ * unlisted `/usr/bin/pmset` still listed clean). `-k` is what makes the answer
+ * about the rule instead of a warm timestamp: it ignores cached credentials for
+ * this call only, without clearing them, so probing doesn't cost the user a
+ * re-prompt. `--check` exits before touching pmset, so the probe has no effect.
+ *
+ * Async because it sits behind two token-gated routes and the relay is one thread. A
+ * synchronous `sudo` here stops every poll on the phone for as long as it takes, and the
+ * 5s ceiling is the whole budget when sudo is slow to answer.
+ */
+export async function helperReady() {
+    try {
+        const { stdout } = await execFileP('sudo', ['-n', '-k', HELPER_PATH, '--check'], {
+            encoding: 'utf8',
+            timeout: 5000
+        });
+        return stdout.trim() === 'ok';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The sudoers drop-in. One command, named absolutely, no argument wildcard — the
+ * helper validates its own arguments, and a wildcard here would be the usual way
+ * this kind of rule turns into a root shell.
+ */
+export function sudoersFile(user) {
+    return [
+        '# conductor-remote — installed by `conductor-remote nosleep setup`.',
+        '#',
+        `# Lets ${user} arm and restore lid-closed sleep with no password, which is what`,
+        '# lets the relay do it: the login LaunchAgent has no TTY to prompt on.',
+        '# Scoped to exactly one root-owned command. Undo: `conductor-remote nosleep setup --uninstall`.',
+        `Cmnd_Alias CONDUCTOR_REMOTE_NOSLEEP = ${HELPER_PATH}`,
+        `${user} ALL=(root) NOPASSWD: CONDUCTOR_REMOTE_NOSLEEP`,
+        ''
+    ].join('\n');
+}

package/dist-node/src/nosleep.js

@@ -0,0 +1,142 @@
+/**
+ * Arming lid-closed wakefulness from the phone.
+ *
+ * This is the one relay capability that needs root, and it only exists at all because
+ * `nosleep setup` installed a scoped NOPASSWD rule: the LaunchAgent has no TTY, so
+ * without that rule there is no prompt to answer and nothing here can work. Every
+ * function below degrades to "not available" rather than failing loudly when the rule
+ * isn't installed, because that is the normal state for anyone who hasn't opted in.
+ *
+ * Two properties matter and neither is obvious:
+ *
+ *  - **The armed window must outlive this process.** `autoupdate` deliberately
+ *    `exit()`s to reload and launchd restarts us; if the helper were an ordinary child
+ *    it would die with us and silently restore sleep, which is exactly the moment the
+ *    phone is relying on it. So it is spawned detached (its own session), and the
+ *    relay finds it again after a restart by reading the pidfile rather than by
+ *    holding a handle.
+ *  - **Liveness can't be checked the usual way.** The armed process runs as root, so
+ *    `kill(pid, 0)` from this process raises EPERM rather than succeeding. EPERM means
+ *    it is alive and not ours; ESRCH means it is gone. Treating EPERM as dead would
+ *    report every armed window as idle.
+ *
+ * Stdlib only, strip-clean — see CLAUDE.md.
+ */
+import { execFile, spawn } from 'node:child_process';
+import fs from 'node:fs';
+import { promisify } from 'node:util';
+import { HELPER_PATH, helperReady, PIDFILE_PATH } from "./nosleep-helper.js";
+const execFileP = promisify(execFile);
+/** Longest window the API will arm. A phone tap should never be able to disable sleep forever. */
+export const MAX_SECONDS = 12 * 3600;
+/**
+ * Whether `pid` exists. EPERM is the interesting case: the armed helper runs as root, so
+ * signalling it from here is refused, and that refusal is itself proof it is alive.
+ */
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+/** Parse `<pid> <expiry-epoch-seconds>`; expiry 0 means "until stopped". */
+function readPidfile() {
+    let raw;
+    try {
+        raw = fs.readFileSync(PIDFILE_PATH, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    const [pidRaw, untilRaw] = raw.trim().split(/\s+/);
+    const pid = Number(pidRaw);
+    if (!Number.isInteger(pid) || pid <= 0)
+        return null;
+    const untilSec = Number(untilRaw);
+    return { pid, until: Number.isFinite(untilSec) && untilSec > 0 ? untilSec * 1000 : null };
+}
+/**
+ * Armed-ness on its own: a local file read plus a signal probe, no subprocess at all.
+ *
+ * Split out from `nosleepState()` because the wait loops below poll it several times a
+ * second. `nosleepState()` falls through to `helperReady()` whenever nothing is armed,
+ * which is exactly the state a loop *waiting* for an arm sits in, so polling it would fire
+ * a synchronous sudo on every pass — fifty per arm, each one blocking the relay's single
+ * thread. The loops already know the grant works; they checked before spawning.
+ */
+function armedRecord() {
+    const rec = readPidfile();
+    return rec && alive(rec.pid) ? rec : null;
+}
+function armedState(rec) {
+    return { available: true, armed: true, until: rec.until, pid: rec.pid };
+}
+/**
+ * Current state. `helperReady()` shells out to sudo, so it is only consulted when nothing
+ * is armed — an armed window is itself proof the grant works.
+ */
+export async function nosleepState() {
+    const rec = armedRecord();
+    if (rec)
+        return armedState(rec);
+    return { available: await helperReady(), armed: false, until: null, pid: null };
+}
+function unavailable() {
+    return {
+        ok: false,
+        error: 'Passwordless nosleep isn’t installed. Run `conductor-remote nosleep setup` on the Mac.',
+        state: { available: false, armed: false, until: null, pid: null }
+    };
+}
+/**
+ * Arm for `seconds` (0 = until stopped). Arming while already armed replaces the window
+ * rather than stacking — the helper enforces that, and it has to, since two owners would
+ * restore each other's flipped values and leave sleep disabled for good.
+ */
+export async function armNoSleep(seconds) {
+    if (!(await helperReady()))
+        return unavailable();
+    // Floor of 1, not 0. The helper reads 0 as "until killed", so anything under a second
+    // truncates straight past MAX_SECONDS into a window nothing ever closes — which is the
+    // one thing the cap exists to prevent.
+    const secs = Math.min(MAX_SECONDS, Math.max(1, Math.trunc(seconds)));
+    // Detached, own session, no stdio: it has to survive this relay's own restarts,
+    // which autoupdate performs routinely and without warning.
+    const child = spawn('sudo', ['-n', HELPER_PATH, String(secs), ''], {
+        detached: true,
+        stdio: 'ignore'
+    });
+    child.unref();
+    // The helper writes its pidfile only after pmset actually applied, so waiting for the
+    // file is what turns "we launched something" into "sleep is genuinely blocked". A
+    // takeover adds its own wait for the incumbent to restore, hence the generous ceiling.
+    const deadline = Date.now() + 10_000;
+    while (Date.now() < deadline) {
+        const rec = armedRecord();
+        if (rec)
+            return { ok: true, state: armedState(rec) };
+        await new Promise(r => setTimeout(r, 200));
+    }
+    return { ok: false, error: 'nosleep did not report itself armed within 10s', state: await nosleepState() };
+}
+/** Disarm. Goes through the helper because the armed process is root and we can't signal it. */
+export async function disarmNoSleep() {
+    if (!(await helperReady()))
+        return unavailable();
+    try {
+        await execFileP('sudo', ['-n', HELPER_PATH, '--stop'], { timeout: 10_000 });
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err), state: await nosleepState() };
+    }
+    const deadline = Date.now() + 8000;
+    while (Date.now() < deadline) {
+        if (!armedRecord())
+            return { ok: true, state: { available: true, armed: false, until: null, pid: null } };
+        await new Promise(r => setTimeout(r, 200));
+    }
+    return { ok: false, error: 'nosleep is still armed after --stop', state: await nosleepState() };
+}

package/dist-node/src/server.js

@@ -11,11 +11,14 @@ import { startFunnelWatchdog } from "./funnel-watchdog.js";
 import { workspaceDiff } from "./git.js";
 import { installLogCapture, isManaged, LOG_FILE_NAMES, logFiles, processStartedAt, recentLogs, redactSecrets, tailLogFile } from "./logbuf.js";
 import { mergePr } from "./merge.js";
+import { armNoSleep, disarmNoSleep, MAX_SECONDS as NOSLEEP_MAX_SECONDS, nosleepState } from "./nosleep.js";
 import { notifyAll, notifyDevice, pushConfig, startNotifier, subscribeDevice, unsubscribeDevice } from "./notify.js";
 import { ParkedPromptQueue } from "./parked.js";
 import { attachPrStatus } from "./pr.js";
 import { Reads } from "./reads.js";
+import { readSettings, writeSettings } from "./settings.js";
 import { driftWarningLines, tailscaleBin } from "./tailscale.js";
+import { autoJoinHotspotMode, currentSsid, looksLikeHotspot, preferredNetworks } from "./wifi.js";
 import { createWorkspace, describeActuator, EFFORT_LABELS, listAgentModels, lockBlocked, newChat, pickActuator, retryWontHelp, screenLocked, setAgentOptions, setRestartGuard, setWorkspaceStatus, WORKSPACE_STATUS_LABELS } from "./writes.js";
 // Before anything that logs: from here on every console line is also kept in memory for
 // `GET /api/logs`, so the phone can read why a send failed without ssh-ing into the Mac.
@@ -419,6 +422,68 @@ const server = http.createServer(async (req, res) => {
         if (req.method === 'GET' && pathname === '/api/repos') {
             return json(req, res, 200, { repos: reads.listRepos() });
         }
+        // GET /api/settings — relay preferences plus what the phone needs to edit them:
+        // the SSIDs this Mac already holds credentials for, so the picker offers a choice
+        // instead of asking someone to type a network name from memory on a phone keyboard.
+        // `ssid` is best-effort and often null (macOS gates it behind Location Services).
+        if (req.method === 'GET' && pathname === '/api/settings') {
+            // Four subprocesses, all concurrent: this is the one route that shells out more
+            // than once, and serialising them would put the phone's polls behind the sum.
+            const [known, current, autoJoinHotspot, nosleep] = await Promise.all([
+                preferredNetworks(),
+                currentSsid(),
+                // macOS's own Auto-join Hotspot setting. On "Never" the Mac won't reach for
+                // your phone unprompted, which no amount of relay code can substitute for.
+                autoJoinHotspotMode(),
+                nosleepState()
+            ]);
+            return json(req, res, 200, {
+                settings: readSettings(),
+                wifi: {
+                    current,
+                    known,
+                    // A guess from the name, never a fact — see wifi.ts. It only sorts the picker.
+                    likelyHotspots: known.filter(looksLikeHotspot),
+                    autoJoinHotspot
+                },
+                nosleep: { ...nosleep, maxSeconds: NOSLEEP_MAX_SECONDS }
+            });
+        }
+        // PATCH /api/settings { fallbackSsids?, autoRejoin? } — merge and persist.
+        if (req.method === 'PATCH' && pathname === '/api/settings') {
+            const body = JSON.parse((await readBody(req)) || '{}');
+            const patch = {};
+            if (Array.isArray(body.fallbackSsids))
+                patch.fallbackSsids = body.fallbackSsids;
+            if (typeof body.autoRejoin === 'boolean')
+                patch.autoRejoin = body.autoRejoin;
+            if (Object.keys(patch).length === 0)
+                return json(req, res, 400, { error: 'nothing to change' });
+            return json(req, res, 200, { settings: writeSettings(patch) });
+        }
+        // GET /api/nosleep — is the Mac being held awake, and can this relay do it at all
+        if (req.method === 'GET' && pathname === '/api/nosleep') {
+            return json(req, res, 200, { ...(await nosleepState()), maxSeconds: NOSLEEP_MAX_SECONDS });
+        }
+        // POST /api/nosleep { seconds } — hold this Mac awake, lid closed, for a bounded window.
+        // Only works once `conductor-remote nosleep setup` has installed the scoped sudoers
+        // rule; without it there is no way for a TTY-less daemon to reach root, and the
+        // response says so rather than failing vaguely.
+        if (req.method === 'POST' && pathname === '/api/nosleep') {
+            const body = JSON.parse((await readBody(req)) || '{}');
+            const seconds = Number(body.seconds);
+            // Whole seconds, not just "> 0": the helper reads 0 as "until killed", and 0.4
+            // truncates to 0 — an unbounded window from a request that looked bounded.
+            if (!Number.isInteger(seconds) || seconds < 1)
+                return json(req, res, 400, { error: 'need a whole number of seconds >= 1' });
+            const result = await armNoSleep(seconds);
+            return json(req, res, result.ok ? 200 : result.state.available ? 502 : 409, result);
+        }
+        // DELETE /api/nosleep — let it sleep again now, rather than at the window's end
+        if (req.method === 'DELETE' && pathname === '/api/nosleep') {
+            const result = await disarmNoSleep();
+            return json(req, res, result.ok ? 200 : result.state.available ? 502 : 409, result);
+        }
         // GET /api/logs?file=&limit= — the relay's own log, so a phone can diagnose a failed send
         // without reaching the Mac. Default is this process's captured console (ordered, timestamped);
         // `file` tails the daemon's stdout/stderr on disk, which is the only place the *previous*

package/dist-node/src/settings.js

@@ -0,0 +1,63 @@
+/**
+ * The relay's own preferences, set from the phone.
+ *
+ * Persisted beside the token and the parked queues (`stateDir()/settings.json`) for the
+ * same reason those are: the daemon restarts itself on every self-update, and anything
+ * held in memory is a preference that quietly reverts.
+ *
+ * **Nothing secret goes in here.** The file is plain JSON at rest and its contents flow
+ * back out through a token-gated API, so the Wi-Fi entries are SSIDs only — macOS already
+ * holds the credentials for any network it has joined, and `src/wifi.ts` never passes a
+ * password. An SSID the Mac doesn't know is reported as unjoinable rather than stored
+ * with one.
+ *
+ * Stdlib only, strip-clean — see CLAUDE.md.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { stateDir } from "./config.js";
+const DEFAULTS = { fallbackSsids: [], autoRejoin: false };
+function settingsPath() {
+    return path.join(stateDir(), 'settings.json');
+}
+/** Coerce anything (a hand-edited file, an older shape, a bad PATCH) into a valid Settings. */
+function sanitize(raw) {
+    const obj = (raw ?? {});
+    const ssids = Array.isArray(obj.fallbackSsids) ? obj.fallbackSsids : [];
+    return {
+        // An SSID is at most 32 bytes; anything longer is not one. Deduped and capped so a
+        // runaway list can't turn the rejoin branch into a minutes-long walk.
+        fallbackSsids: [
+            ...new Set(ssids.filter((s) => typeof s === 'string' && !!s.trim()).map(s => s.trim()))
+        ]
+            .filter(s => s.length <= 32)
+            .slice(0, 8),
+        autoRejoin: obj.autoRejoin === true
+    };
+}
+let cache = null;
+export function readSettings() {
+    if (cache)
+        return cache;
+    try {
+        cache = sanitize(JSON.parse(fs.readFileSync(settingsPath(), 'utf8')));
+    }
+    catch {
+        cache = { ...DEFAULTS };
+    }
+    return cache;
+}
+/** Merge a partial patch over what's stored and persist. Returns the settings as they now are. */
+export function writeSettings(patch) {
+    const next = sanitize({ ...readSettings(), ...patch });
+    const file = settingsPath();
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, `${JSON.stringify(next, null, '\t')}\n`, { mode: 0o600 });
+    }
+    catch (err) {
+        console.warn(`⚠ could not persist settings (${err instanceof Error ? err.message : err})`);
+    }
+    cache = next;
+    return next;
+}