@oddessentials/agent-guild 0.32.0 → 0.33.0

package/src/manager/server.mjs

@@ -115,6 +115,8 @@ export function createManagerServer({
   extraHosts = [],
   extraOrigins = [],
   remoteAccess = null,
+  /** Starting the manager at sign-in, or null where it is not offered. */
+  autostart = null,
   /** In-memory when omitted, so a test server never reads the user's notes file. */
   notes = createNotesStore(),
   folderOpener = createFolderOpener({ resolveCwd: (cwd) => manager.resolveCwd(cwd) }),
@@ -276,6 +278,15 @@ export function createManagerServer({
       return sendJson(res, 202, { remoteAccess: operation });
     }
 
+    if (autostart && route === '/autostart' && method === 'GET') {
+      return sendJson(res, 200, { autostart: await autostart.describe() });
+    }
+    if (autostart && route === '/autostart' && method === 'PUT') {
+      const { enabled } = await readJsonBody(req);
+      if (typeof enabled !== 'boolean') throw new HttpError(400, 'enabled must be true or false', 'bad_request');
+      return sendJson(res, 200, { autostart: await autostart.set(enabled) });
+    }
+
     if (route === '/info' && method === 'GET') {
       selfUpdate?.refresh().catch(() => {});
       return sendJson(res, 200, {

package/src/manager/session.mjs

@@ -23,6 +23,10 @@ const REPORTING_STATES = new Set(['pending', 'active', 'unavailable', 'setup_req
 const SHELL_EVENTS = new Set(['start', 'waiting', 'asked', 'background', 'end', 'running', 'reset']);
 const MAX_SHELLS = 256;
 const MAX_ENDED_TASKS = 256;
+// Keys and reports a terminal sends as escape sequences: X10 mouse reports (three raw bytes after ESC [ M), other CSI
+// and SS3 sequences, OSC and DCS strings (to their end, or the next ESC, so a large paste is scanned once), and ESC
+// with one character (Alt+key). Bracketed paste markers are CSI, so pasted text is kept.
+const ESCAPE_SEQUENCE = /\x1b\[M[\s\S]{3}|\x1b\[[0-?]*[ -/]*[@-~]|\x1bO[\s\S]|\x1b[\]P][^\x07\x1b]*(?:\x07|\x1b\\)?|\x1b[\s\S]?/g;
 
 /**
  * Colours reported to programs that query them (OSC 10/11/12), matching the
@@ -91,6 +95,7 @@ export class Session extends EventEmitter {
     this.reportingTimeoutMs = opts.reportingTimeoutMs ?? 30000;
     this.reporting = REPORTING_STATES.has(opts.reporting?.state) ? { state: opts.reporting.state, reason: opts.reporting.reason ?? null } : null;
     this._reportingTimer = null;
+    this._typedSinceEnter = false;
     this.shellDisplayDelayMs = opts.shellDisplayDelayMs ?? 600;
     this.shells = new Map();
     this._shellSeq = 0;
@@ -309,12 +314,12 @@ export class Session extends EventEmitter {
 
   input(data) {
     this.write(data);
-    if (this.reporting?.state === 'pending' && !this._reportingTimer && typeof data === 'string' && /[\r\n]/.test(data)) {
+    if (this.reporting?.state === 'pending' && !this._reportingTimer && typeof data === 'string' && this._sendsTypedLine(data)) {
       this._reportingTimer = setTimeout(() => {
         if (this.reporting?.state !== 'pending' || this.status !== 'running') return;
         this.reporting = {
           state: 'unavailable',
-          reason: `${this.provider.tool} has not run Agent Guild's reporting hooks yet. That is expected while it signs in or sets up; otherwise its hooks may be turned off, restricted by an administrator, or not trusted for this folder.`,
+          reason: `No report from ${this.provider.tool}'s hooks yet. They report once a prompt is sent; that can wait while ${this.provider.tool} signs in or sets up. If a prompt was sent and this stays, its hooks may be turned off, restricted by an administrator, or not trusted for this folder.`,
         };
         this._changed();
       }, this.reportingTimeoutMs);
@@ -322,6 +327,26 @@ export class Session extends EventEmitter {
     }
   }
 
+  /**
+   * Whether this input sends a line with something typed on it, the way a
+   * prompt is sent. An Enter on an empty line, or after only keys that send
+   * escape sequences (arrows in a menu, focus and mouse reports), is not a
+   * prompt; nor is one after Ctrl+C or Ctrl+U, which clear the line. Text
+   * may arrive one key at a time, so what was typed carries over.
+   */
+  _sendsTypedLine(data) {
+    const keys = data.replace(ESCAPE_SEQUENCE, '');
+    let sent = false;
+    for (const ch of keys) {
+      if (ch === '\r' || ch === '\n') {
+        sent ||= this._typedSinceEnter;
+        this._typedSinceEnter = false;
+      } else if (ch === '\x03' || ch === '\x15') this._typedSinceEnter = false;
+      else if (ch >= ' ' && ch !== '\x7f') this._typedSinceEnter = true;
+    }
+    return sent;
+  }
+
   _reply(data) {
     this.write(data);
   }

package/src/manager/shell-env.mjs

@@ -1,10 +1,16 @@
-// Recover the user's real PATH on macOS and Linux.
+// Recover the user's real PATH and locale on macOS and Linux.
 //
 // An app started from Finder, the Dock, or a login item does not inherit the
 // PATH that the user's shell profile builds (Homebrew, nvm, ~/.local/bin, ...),
 // which is exactly where CLI coding tools usually live. Like VS Code, we ask
 // the user's login shell for its PATH and merge it in.
+//
+// launchd starts a sign-in manager with no locale at all, where Terminal.app
+// would set LANG to the region's UTF-8 locale. Without one, tmux writes
+// non-ASCII characters as underscores, so a macOS manager with no locale
+// takes Terminal.app's, and there a locale the login shell exports wins.
 
+import fs from 'node:fs';
 import { execFile, spawn, spawnSync } from 'node:child_process';
 import path from 'node:path';
 
@@ -24,17 +30,31 @@ export function mergePathLists(primary, secondary, delimiter = path.delimiter) {
   return out.join(delimiter);
 }
 
-/** Pull PATH out of `env` output captured between the two markers. */
-export function parsePathFromEnvOutput(stdout) {
+/** The variables that choose a locale, in the order they take effect. */
+export const LOCALE_VARS = ['LC_ALL', 'LC_CTYPE', 'LANG'];
+
+/** The non-empty `names` in `env` output captured between the two markers, or null without the markers. */
+export function parseEnvOutput(stdout, names) {
   if (typeof stdout !== 'string') return null;
   const start = stdout.indexOf(START);
   const end = stdout.indexOf(END, start);
   if (start === -1 || end === -1) return null;
-  const line = stdout.slice(start + START.length, end).split(/\r?\n/).find((l) => l.startsWith('PATH='));
-  return line ? line.slice('PATH='.length) : null;
+  const found = {};
+  for (const line of stdout.slice(start + START.length, end).split(/\r?\n/)) {
+    const eq = line.indexOf('=');
+    const name = line.slice(0, eq);
+    if (eq > 0 && names.includes(name) && line.length > eq + 1 && !(name in found)) found[name] = line.slice(eq + 1);
+  }
+  return found;
 }
 
-export function loginShellPath({ shell = process.env.SHELL, timeoutMs = 8000 } = {}) {
+/** Pull PATH out of `env` output captured between the two markers. */
+export function parsePathFromEnvOutput(stdout) {
+  return parseEnvOutput(stdout, ['PATH'])?.PATH ?? null;
+}
+
+/** PATH and the locale variables the user's login shell exports, or null. */
+export function loginShellEnv({ shell, env = process.env, timeoutMs = 8000 } = {}) {
   if (process.platform === 'win32' || !shell) return null;
   // Read the exported PATH from `env` rather than expanding $PATH: fish, for
   // one, expands "$PATH" to a space-separated list.
@@ -42,10 +62,26 @@ export function loginShellPath({ shell = process.env.SHELL, timeoutMs = 8000 } =
     encoding: 'utf8',
     timeout: timeoutMs,
     stdio: ['ignore', 'pipe', 'ignore'],
-    env: { ...process.env, AGENT_GUILD_RESOLVING_ENV: '1' },
+    env: { ...env, AGENT_GUILD_RESOLVING_ENV: '1' },
   });
   if (result.error) return null;
-  return parsePathFromEnvOutput(result.stdout);
+  return parseEnvOutput(result.stdout, ['PATH', ...LOCALE_VARS]);
+}
+
+function readAppleLocale() {
+  const result = spawnSync('/usr/bin/defaults', ['read', '-g', 'AppleLocale'], { encoding: 'utf8', timeout: 2000, stdio: ['ignore', 'pipe', 'ignore'] });
+  return result.error ? null : result.stdout;
+}
+
+/**
+ * The locale Terminal.app gives its shells: the system region's UTF-8 locale,
+ * or en_US.UTF-8 when macOS has none for it. `AppleLocale` may carry a script
+ * (`zh-Hans_CN`) and options (`en_US@rg=gbzzzz`), which locale names do not.
+ */
+export function macLocale({ read = readAppleLocale, exists = (name) => fs.existsSync(path.join('/usr/share/locale', name)) } = {}) {
+  const region = String(read() || '').trim().split('@')[0].replace(/-[A-Za-z]+(?=_)/, '');
+  const name = `${region}.UTF-8`;
+  return /^[A-Za-z]+_[A-Za-z]+$/.test(region) && exists(name) ? name : 'en_US.UTF-8';
 }
 
 /**
@@ -59,11 +95,15 @@ export function trimPathExt(env, platform = process.platform) {
   return env;
 }
 
-export function resolveBaseEnv() {
-  const env = trimPathExt({ ...process.env });
-  if (process.env.AGENT_GUILD_SKIP_SHELL_ENV === '1') return env;
-  const shellPath = loginShellPath();
-  if (shellPath) env.PATH = mergePathLists(shellPath, env.PATH);
+/** `platform`, `env`, `shellEnv` and `locale` are replaceable in tests. */
+export function resolveBaseEnv({ platform = process.platform, env: source = process.env, shellEnv = loginShellEnv, locale = macLocale } = {}) {
+  const env = trimPathExt({ ...source }, platform);
+  // Set before asking the shell, so macOS's /etc/zprofile keeps it rather than putting its C.UTF-8 in its place.
+  if (platform === 'darwin' && !LOCALE_VARS.some((name) => env[name])) env.LANG = locale();
+  if (env.AGENT_GUILD_SKIP_SHELL_ENV === '1') return env;
+  const shell = shellEnv({ shell: env.SHELL, env }) || {};
+  if (shell.PATH) env.PATH = mergePathLists(shell.PATH, env.PATH);
+  if (platform === 'darwin') for (const name of LOCALE_VARS) if (shell[name]) env[name] = shell[name];
   return env;
 }
 

package/src/manager/uninstall.mjs

@@ -68,8 +68,11 @@ function launchChain(launcher) {
   return chain;
 }
 
-function removeFile(file) {
-  fs.rmSync(file, { recursive: true, force: true, maxRetries: 3 });
+/** Deletes a file or folder, and a link as the link itself even when its target is already gone. */
+export function removeFile(file) {
+  // Some Node releases (24.13.0 among them) silently keep a dangling link that rmSync is asked to force.
+  if (fs.lstatSync(file, { throwIfNoEntry: false })?.isSymbolicLink()) fs.unlinkSync(file);
+  else fs.rmSync(file, { recursive: true, force: true, maxRetries: 3 });
 }
 
 export function runPlan(
@@ -111,6 +114,8 @@ export function runPlan(
     } catch (err) {
       throw Object.assign(err, { file });
     }
+    // Never report a removal that did not happen.
+    if (exists(file)) throw Object.assign(new Error('it is still there'), { file });
   };
   const prune = (dir) => {
     for (const name of fs.readdirSync(dir)) {

package/src/manager/usage.mjs

@@ -139,7 +139,7 @@ export async function fetchClaudeUsage({ accessToken, plan = null, version = nul
     },
     signal: AbortSignal.timeout(10000),
   });
-  if (!res.ok) throw httpUsageError(res.status, 'sign in again in Claude Code');
+  if (!res.ok) throw await httpUsageError(res, 'sign in again in Claude Code');
   const body = await res.json();
   const windows = [];
   for (const [key, label] of [['five_hour', '5-hour'], ['seven_day', '7-day'], ['seven_day_opus', '7-day Opus'], ['seven_day_sonnet', '7-day Sonnet']]) {
@@ -210,7 +210,7 @@ export async function fetchCodexUsage({ accessToken, accountId = null, fetchImpl
   const headers = { Authorization: `Bearer ${accessToken}`, Accept: 'application/json', 'User-Agent': 'agent-guild' };
   if (accountId) headers['ChatGPT-Account-Id'] = accountId;
   const res = await fetchImpl(CODEX_USAGE_URL, { headers, signal: AbortSignal.timeout(10000) });
-  if (!res.ok) throw httpUsageError(res.status, 'sign in again in Codex CLI');
+  if (!res.ok) throw await httpUsageError(res, 'sign in again in Codex CLI');
   const body = await res.json();
   const windows = codexWindows(body?.rate_limit ?? body?.rateLimit);
   // Limits metered apart from the plan's main windows, one entry per
@@ -279,10 +279,94 @@ export async function commandUsage({ command, args = [] }, env, platform = proce
   return { plan: body.plan ? String(body.plan).slice(0, 40) : null, windows };
 }
 
-function httpUsageError(status, signInHint) {
-  if (status === 401 || status === 403) return new UsageError(`usage endpoint refused the sign-in (HTTP ${status}); ${signInHint}`);
-  if (status === 429) return Object.assign(new UsageError('usage endpoint is rate limiting requests; retrying later'), { rateLimited: true });
-  return new UsageError(`usage endpoint answered HTTP ${status}`);
+// JWTs, API keys, bearer credentials and other long opaque strings never reach a message or the log.
+const SECRET_LIKE = /\beyJ[\w-]+\.[\w-]+(?:\.[\w-]*)?|\b(?:sk|rk|pk)-[\w-]{8,}|\bBearer\s+\S+|[\w+/=-]{40,}/gi;
+
+/** One line of at most `max` characters from a response body, without markup or anything credential-like. */
+export function excerpt(text, max = 200) {
+  if (typeof text !== 'string') return '';
+  return text
+    .replace(/<(script|style)\b[\s\S]*?<\/\1\s*>/gi, ' ')
+    .replace(/<[^>]*>/g, ' ')
+    .replace(SECRET_LIKE, '[redacted]')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, max);
+}
+
+/** The error message a JSON body carries, in the shapes the vendors use, else null. */
+function jsonMessage(text) {
+  let body;
+  try { body = JSON.parse(text); } catch { return null; }
+  const error = body?.error;
+  const message = firstText(error?.message, typeof error === 'string' ? error : null, body?.error_description, body?.detail, body?.message);
+  return message ? excerpt(message, 120) || null : null;
+}
+
+/** How much of a failed reply is read: enough for any error message or the start of a challenge page. */
+export const ERROR_BODY_LIMIT = 16 * 1024;
+
+/**
+ * The start of a reply's body as text, at most about `limit` bytes, the rest
+ * left unread. A reply-like object without a body stream is read with text().
+ */
+export async function readStart(res, limit = ERROR_BODY_LIMIT) {
+  const reader = res.body?.getReader?.();
+  if (!reader) return typeof res.text === 'function' ? res.text() : '';
+  const decoder = new TextDecoder();
+  let text = '';
+  let size = 0;
+  try {
+    while (size < limit) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      text += decoder.decode(value, { stream: true });
+    }
+  } finally {
+    // Ends the download of whatever is left; the result does not matter.
+    reader.cancel().catch(() => {});
+  }
+  return (text + decoder.decode()).slice(0, limit);
+}
+
+/**
+ * The error for a failed usage request. A 401 means the token was refused;
+ * a 403 that Cloudflare answered means the request was blocked before the
+ * token was looked at, usually because of the network it came from, so it
+ * gets no sign-in advice. `detail` is what the manager log records.
+ */
+async function httpUsageError(res, signInHint) {
+  const { status } = res;
+  const header = (name) => { try { return res.headers?.get?.(name) ?? null; } catch { return null; } };
+  let text = '';
+  try { text = await readStart(res); } catch { /* the body is optional */ }
+  const server = header('server');
+  const detail = { status, server: excerpt(server, 80) || null, ray: excerpt(header('cf-ray'), 80) || null, body: excerpt(text) };
+  const error = (message, extra = {}) => Object.assign(new UsageError(message), { detail }, extra);
+  if (status === 401) return error(`usage endpoint refused the sign-in (HTTP 401); ${signInHint}`);
+  if (status === 403) {
+    const blocked = header('cf-mitigated') !== null || (/cloudflare/i.test(server ?? '') && /html/i.test(header('content-type') ?? ''));
+    if (blocked) return error('usage endpoint blocked this network (HTTP 403), not a sign-in problem; usually a VPN, proxy or exit node, and it clears by itself');
+    const message = jsonMessage(text);
+    return error(`usage endpoint refused access (HTTP 403${message ? `: ${message}` : ''}); if this continues, ${signInHint}`);
+  }
+  if (status === 429) return error('usage endpoint is rate limiting requests; retrying later', { rateLimited: true });
+  return error(`usage endpoint answered HTTP ${status}`);
+}
+
+/**
+ * What the manager log adds to a failed lookup's message, which already
+ * names the HTTP status: the reply's headers and body for a vendor failure,
+ * '' when there is nothing more to say, and null for a failure that needs
+ * no log entry, such as no sign-in.
+ */
+function failureDetail(err) {
+  if (err.detail) {
+    const { server, ray, body } = err.detail;
+    return [server && `server=${server}`, ray && `cf-ray=${ray}`, body && `body="${body}"`].filter(Boolean).join(' ');
+  }
+  return err instanceof UsageError || err.notSignedIn ? null : '';
 }
 
 // ---- monitor ----------------------------------------------------------------
@@ -295,15 +379,19 @@ export class UsageMonitor {
    * @param {Function} [opts.fetchImpl]
    * @param {number} [opts.ttlMs]
    * @param {object} [opts.readers]  credential readers, replaceable in tests
+   * @param {(line: string) => void} [opts.log]  where vendor and network failures are recorded
    */
-  constructor({ registry, env = process.env, platform = process.platform, fetchImpl = fetch, ttlMs = USAGE_TTL_MS, readers = {} } = {}) {
+  constructor({ registry, env = process.env, platform = process.platform, fetchImpl = fetch, ttlMs = USAGE_TTL_MS, readers = {}, log = console.warn } = {}) {
     this.registry = registry;
     this.env = env;
     this.platform = platform;
     this.fetchImpl = fetchImpl;
     this.ttlMs = ttlMs;
     this.readers = { claude: readClaudeCredentials, codex: readCodexCredentials, ...readers };
+    this.log = log;
     this.cache = new Map();
+    /** Account key → the failure last logged for it, so a failure that persists is logged once and its end once. */
+    this.logged = new Map();
   }
 
   /** Snapshots for every account of every provider that has a usage source. */
@@ -322,7 +410,8 @@ export class UsageMonitor {
     const now = Date.now();
     if (entry?.inflight) return entry.inflight;
     if (entry && now - entry.at < entry.ttl) return Promise.resolve(entry.snapshot);
-    const inflight = this._fetch(provider, account).then((snapshot) => {
+    const inflight = this._fetch(provider, account).then(({ snapshot, failure }) => {
+      this._record(`${provider.id}/${account.id}`, snapshot.error, failure);
       const ttl = snapshot.rateLimited ? RATE_LIMITED_TTL_MS : this.ttlMs;
       this.cache.set(key, { snapshot, at: Date.now(), ttl });
       return snapshot;
@@ -331,6 +420,20 @@ export class UsageMonitor {
     return inflight;
   }
 
+  /** Log a vendor or network failure when it starts or changes, and once when lookups succeed again. */
+  _record(key, error, failure) {
+    const previous = this.logged.get(key);
+    if (failure !== null) {
+      if (previous === error) return;
+      this.logged.set(key, error);
+      this.log(`[usage] ${key}: ${error}${failure ? ` (${failure})` : ''}`);
+    } else if (previous !== undefined) {
+      this.logged.delete(key);
+      if (!error) this.log(`[usage] ${key}: usage lookups work again`);
+    }
+  }
+
+  /** Resolves to `{ snapshot, failure }`: the snapshot for clients and, for a vendor or network failure, its log detail (else null). */
   async _fetch(provider, account) {
     const base = { providerId: provider.id, accountId: account.id, plan: null, windows: [], credits: null, signedIn: null, fetchedAt: new Date().toISOString(), error: null };
     const env = { ...this.env, ...provider.env, ...account.env };
@@ -352,10 +455,13 @@ export class UsageMonitor {
       } else {
         result = await commandUsage(provider.usage, env, this.platform);
       }
-      return { ...base, signedIn, ...result };
+      return { snapshot: { ...base, signedIn, ...result }, failure: null };
     } catch (err) {
       const message = err instanceof UsageError ? err.message : `usage check failed: ${err.name === 'TimeoutError' ? 'timed out' : err.message}`;
-      return { ...base, signedIn: err.notSignedIn ? false : signedIn, error: message, ...(err.rateLimited ? { rateLimited: true } : {}) };
+      return {
+        snapshot: { ...base, signedIn: err.notSignedIn ? false : signedIn, error: message, ...(err.rateLimited ? { rateLimited: true } : {}) },
+        failure: failureDetail(err),
+      };
     }
   }
 }

package/web/app.js

@@ -4,7 +4,7 @@
 import { SOUNDS, MAX_ALERT_AGE_MS, playOnce, rearmSound, managerLossWatcher, stopWatcher, updateWatcher } from './alerts.js';
 import { TerminalCopy } from './terminal-copy.js';
 import { TerminalControls, bindTerminalViewport } from './terminal-controls.js';
-import { topbarInline, dockMode, clampDockWidth, stageBesideDock, splitMode, clampRatio, bindSplitter, DOCK_MIN, SPLIT_RATIO_MIN } from './layout.js';
+import { topbarInline, dockMode, clampDockWidth, stageBesideDock, splitMode, clampRatio, bindSplitter, bindVisibleViewport, DOCK_MIN, SPLIT_RATIO_MIN } from './layout.js';
 import { highlightParts, rankRepos, recentFirst, remember, repoForOrigin, repoKey } from './repo-search.js';
 import { createActivityFavicon, isSessionWorking } from './activity-favicon.js';
 import { createRemoteAccessUI } from './remote-access.js';
@@ -299,6 +299,69 @@ function alertSound(name, key, at = Date.now(), fresh = () => true, related = []
   });
 }
 
+const AUTOSTART_NOTE = 'Starts the session manager in the background when you sign in to the computer running Agent Guild. The page does not open.';
+let autostartRequest = 0;
+let autostartChanging = false;
+
+/** What the entry did at the last sign-in it ran at, or '' while it is off. */
+function autostartRun(autostart) {
+  if (!autostart?.available || !autostart.enabled) return '';
+  const run = autostart.lastRun;
+  if (!run) return 'Has not run at a sign-in yet.';
+  const at = new Date(run.at).toLocaleString([], { dateStyle: 'medium', timeStyle: 'short' });
+  if (run.outcome === 'started') return `Last ran at sign-in on ${at} and started the session manager.`;
+  if (run.outcome === 'running') return `Last ran at sign-in on ${at}; the session manager was already running.`;
+  if (run.outcome === 'starting') return `Starting the session manager for the sign-in on ${at}…`;
+  return `Last ran at sign-in on ${at}, but the session manager did not start.${autostart.log ? ` See ${autostart.log}.` : ''}`;
+}
+
+/** The manager's sign-in setting; hidden when the manager has none. */
+function renderAutostart(autostart) {
+  $('autostart-choice').hidden = !autostart;
+  $('autostart').checked = Boolean(autostart?.enabled);
+  $('autostart').disabled = !autostart?.available;
+  $('autostart-note').textContent = autostart?.reason || autostart?.note || AUTOSTART_NOTE;
+  const run = autostartRun(autostart);
+  $('autostart-run').textContent = run;
+  $('autostart-run').hidden = !run;
+  $('autostart-run').dataset.outcome = autostart?.enabled ? autostart.lastRun?.outcome ?? 'none' : '';
+}
+
+async function loadAutostart({ afterChange = false } = {}) {
+  if (!state.connected || (autostartChanging && !afterChange)) return;
+  const request = ++autostartRequest;
+  $('autostart').disabled = true;
+  try {
+    const { autostart } = await api('GET', '/autostart');
+    if (request === autostartRequest) renderAutostart(autostart);
+  } catch (err) {
+    if (request !== autostartRequest) return;
+    if (err instanceof AuthError) showAuth(err.message);
+    else if (err.code === 'not_found') renderAutostart(null);
+    else renderAutostart({ available: false, enabled: false, reason: `Could not read the startup setting: ${err.message}` });
+  }
+}
+
+async function changeAutostart(input) {
+  if (autostartChanging) return;
+  autostartChanging = true;
+  ++autostartRequest;
+  const enabled = input.checked;
+  input.disabled = true;
+  try {
+    renderAutostart((await api('PUT', '/autostart', { enabled })).autostart);
+  } catch (err) {
+    if (err instanceof AuthError) showAuth(err.message);
+    else {
+      toast(err.message);
+      // An OS operation can partly succeed. Read back what actually happened.
+      await loadAutostart({ afterChange: true });
+    }
+  } finally {
+    autostartChanging = false;
+  }
+}
+
 function changeSound(input) {
   save(SOUND_KEY, input.checked ? 'on' : null);
   prepareSounds();
@@ -3704,9 +3767,14 @@ async function loadBranches({ resume = false } = {}) {
       }
       for (const branch of result.branches) request.rows.set(branch.name, branch);
       request.nextPage = result.nextPage;
-      request.received = true;
-      request.value = { ...result, branches: [...request.rows.values()],
-        defaultBranch: request.defaultBranch, metadataError: request.metadataError };
+      // First loads display each page. A refresh keeps the previous list until
+      // every page arrives, so later-page rows and the reading position survive.
+      // `received` means the displayed value belongs to this listing generation.
+      if (!request.value || request.received || request.nextPage === null) {
+        request.received = true;
+        request.value = { ...result, branches: [...request.rows.values()],
+          defaultBranch: request.defaultBranch, metadataError: request.metadataError };
+      }
       renderGitHubViews();
     }
   } catch (err) {
@@ -3774,7 +3842,7 @@ function renderBranches({ preserveAnchor = true } = {}) {
   const branches = (value?.branches ?? []).filter((b) => b.name.toLocaleLowerCase().includes(query)).sort((a, b) =>
     Number(b.name === value.defaultBranch) - Number(a.name === value.defaultBranch)
       || a.name.localeCompare(b.name) || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
-  const complete = Boolean(value && value.nextPage === null && (!slot.error || slot.received));
+  const complete = Boolean(slot?.received && value?.nextPage === null);
   const count = value?.branches.length ?? 0;
   let status = !value ? (slot?.error ? 'Branches could not be loaded.' : 'Loading branches…')
     : query ? `${branches.length} of ${count} loaded branches match.`
@@ -3879,7 +3947,17 @@ function setPickerOpen(open) {
   input.setAttribute('aria-expanded', String(open));
   $('github-repo-list').hidden = !open;
   if (!open) input.removeAttribute('aria-activedescendant');
-  else renderPickerList();
+  else {
+    fitPickerList();
+    renderPickerList();
+  }
+}
+
+// The list stays inside the visible part of the dock, so no option sits under an on-screen keyboard.
+function fitPickerList() {
+  if (!githubPick.open) return;
+  const room = $('dock').getBoundingClientRect().bottom - $('github-repo').getBoundingClientRect().bottom - 12;
+  $('github-repo-list').style.setProperty('--picker-room', `${Math.max(120, Math.floor(room))}px`);
 }
 
 function highlighted(text, query) {
@@ -5041,6 +5119,7 @@ const terminalControls = new TerminalControls({
   },
 });
 bindTerminalViewport($('terminal-panel'), $('terminal-controls'));
+bindVisibleViewport($('dock'), 'dock', { fitted: fitPickerList });
 
 const terminalCopy = new TerminalCopy({
   opener: $('panel-copy'), dialog: $('terminal-copy'),
@@ -5984,6 +6063,7 @@ $('settings-menu').addEventListener('change', (e) => {
   else if (e.target.name === 'theme') changeTheme(e.target);
   else if (e.target.name === 'sound') changeSound(e.target);
   else if (e.target.name === 'voice') changeVoice(e.target);
+  else if (e.target.name === 'autostart') changeAutostart(e.target);
 });
 /**
  * Runs `opened` once a menu shows and `closed` once it hides. Chrome skips the toggle event of a menu
@@ -6003,6 +6083,7 @@ function returnFocus(menu, invoker) {
   if ((!at || at === document.body || menu.contains(at)) && invoker?.checkVisibility?.()) invoker.focus();
 }
 onMenu($('settings-menu'), (menu) => {
+  loadAutostart();
   placeMenu(menu, $('settings'));
   menu.querySelector('input:checked')?.focus();
 }, (menu) => returnFocus(menu, $('settings')));

package/web/index.html

@@ -46,6 +46,12 @@
             <legend>Sound</legend>
             <label class="choice" title="Plays when the session manager stops, remains unavailable after a brief recovery check, or a new Agent Guild update is discovered. Click or type on this page to allow playback."><input id="sound" type="checkbox" name="sound"><span class="sound-alerts">Alert sounds</span></label>
           </fieldset>
+          <fieldset id="autostart-choice" hidden>
+            <legend>Startup</legend>
+            <label class="choice"><input id="autostart" type="checkbox" name="autostart"><span class="autostart">Launch at sign-in</span></label>
+            <p id="autostart-note" class="voice-note"></p>
+            <p id="autostart-run" class="voice-note autostart-run" role="status" hidden></p>
+          </fieldset>
           <fieldset id="voice-choice" hidden>
             <legend>Voice</legend>
             <label class="choice"><input id="voice" type="checkbox" name="voice"><span class="voice-input">Voice input</span></label>

package/web/layout.js

@@ -73,3 +73,39 @@ export function bindSplitter(handle, { axis = () => 'x', start, move, end, step
     end();
   });
 }
+
+/**
+ * Publishes the part of the window an on-screen keyboard leaves visible as
+ * `--<name>-viewport-top`, `--<name>-viewport-bottom` and `--<name>-viewport-height`
+ * on `element` while `shown()` holds. iOS Safari keeps fixed elements at their full
+ * height under its keyboard and pans the page beneath them, so they must fit themselves.
+ * `fitted(height)` runs after each update, with null while the element is not shown.
+ */
+export function bindVisibleViewport(element, name, { shown = () => !element.hidden, watch = [element], fitted = () => {} } = {}) {
+  const viewport = window.visualViewport;
+  const props = ['top', 'bottom', 'height'].map((edge) => `--${name}-viewport-${edge}`);
+  let frame;
+  const update = () => {
+    if (!shown()) {
+      for (const prop of props) element.style.removeProperty(prop);
+      return fitted(null);
+    }
+    // Magnification belongs to the browser; it must not resize the layout.
+    if (viewport && Math.abs(viewport.scale - 1) > 0.01) return;
+    const top = viewport?.offsetTop || 0;
+    const height = viewport?.height ?? innerHeight;
+    element.style.setProperty(props[0], `${top}px`);
+    element.style.setProperty(props[1], `${Math.max(0, innerHeight - top - height)}px`);
+    element.style.setProperty(props[2], `${height}px`);
+    fitted(height);
+  };
+  const schedule = () => { cancelAnimationFrame(frame); frame = requestAnimationFrame(update); };
+  viewport?.addEventListener('resize', schedule);
+  viewport?.addEventListener('scroll', schedule);
+  addEventListener('resize', schedule);
+  addEventListener('pageshow', schedule);
+  const observer = new MutationObserver(schedule);
+  for (const watched of watch) observer.observe(watched, { attributes: true, attributeFilter: ['hidden'] });
+  schedule();
+  return schedule;
+}

package/web/styles.css

@@ -23,6 +23,7 @@
   --icon-sun: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round'%3E%3Ccircle cx='12' cy='12' r='4.2'/%3E%3Cpath d='M12 2.5v2.2M12 19.3v2.2M2.5 12h2.2M19.3 12h2.2M5.3 5.3l1.6 1.6M17.1 17.1l1.6 1.6M5.3 18.7l1.6-1.6M17.1 6.9l1.6-1.6'/%3E%3C/svg%3E");
   --icon-moon: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linejoin='round'%3E%3Cpath d='M19.5 14.6A8 8 0 0 1 9.4 4.5a8 8 0 1 0 10.1 10.1z'/%3E%3C/svg%3E");
   --icon-mic: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Crect x='9' y='3' width='6' height='11' rx='3'/%3E%3Cpath d='M5.5 11a6.5 6.5 0 0 0 13 0M12 17.5V21'/%3E%3C/svg%3E");
+  --icon-power: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round'%3E%3Cpath d='M12 3v8.5'/%3E%3Cpath d='M7 6.2a7.5 7.5 0 1 0 10 0'/%3E%3C/svg%3E");
   --icon-sound: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M4 9.5h3.5L12 5.5v13l-4.5-4H4z'/%3E%3Cpath d='M15.5 9a4.2 4.2 0 0 1 0 6M18.3 6.5a8 8 0 0 1 0 11'/%3E%3C/svg%3E");
   --icon-external:url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2.2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M7 17L17 7M9 7h8v8'/%3E%3C/svg%3E");
   --icon-cloud: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linejoin='round'%3E%3Cpath d='M7 18.5h10.5a4 4 0 0 0 .6-7.96A6 6 0 0 0 6.5 9.6 4.5 4.5 0 0 0 7 18.5z'/%3E%3C/svg%3E");
@@ -392,7 +393,10 @@ main { max-width: calc(1200px + var(--dock-space, 0px)); margin: 0 auto; padding
 .settings-menu .choice > .mode-dark::before { mask-image: var(--icon-moon); }
 .settings-menu .choice > .sound-alerts::before { mask-image: var(--icon-sound); }
 .settings-menu .choice > .voice-input::before { mask-image: var(--icon-mic); }
+.settings-menu .choice > .autostart::before { mask-image: var(--icon-power); }
 .voice-note { margin: 0 8px 6px; max-width: 26ch; color: var(--muted); font-size: 0.75rem; line-height: 1.35; }
+.autostart-run { overflow-wrap: anywhere; }
+.autostart-run[data-outcome="failed"] { color: var(--danger); }
 .notes-open::before { mask-image: var(--icon-notes); }
 .notes-open[aria-pressed="true"], .github-toggle[aria-pressed="true"] { border-color: var(--accent); color: var(--accent); }
 .menu-button::after { margin-left: 0.45em; transform: rotate(90deg); transition: transform 0.15s var(--ease); }
@@ -872,7 +876,7 @@ a.news-link:visited { color: var(--muted); }
 .github-combo input:focus-visible { outline: 2px solid var(--focus); outline-offset: 1px; }
 .github-combo input::placeholder { font-weight: 400; }
 .github-repo-list {
-  position: absolute; z-index: 5; left: 0; right: 0; top: calc(100% + 4px); max-height: min(26rem, 60dvh); overflow: auto;
+  position: absolute; z-index: 5; left: 0; right: 0; top: calc(100% + 4px); max-height: min(26rem, 60dvh, var(--picker-room, 26rem)); overflow: auto;
   margin: 0; padding: 4px; list-style: none; background: var(--surface); color: var(--text);
   border: 1px solid var(--border); border-radius: var(--radius); box-shadow: 0 12px 32px rgba(0, 0, 0, 0.28);
 }
@@ -961,7 +965,8 @@ a.btn.github-out::after {
 .toast .toast-action { margin-left: 12px; padding: 2px 10px; background: transparent; box-shadow: none; color: inherit; border-color: currentColor; }
 
 .dock {
-  position: fixed; top: var(--topbar-h, 56px); right: 0; bottom: 0; z-index: 12; width: var(--dock-w, 420px); max-width: 100vw;
+  /* Above an on-screen keyboard, which the page publishes as --dock-viewport-*. */
+  position: fixed; top: max(var(--topbar-h, 56px), var(--dock-viewport-top, 0px)); right: 0; bottom: var(--dock-viewport-bottom, 0px); z-index: 12; width: var(--dock-w, 420px); max-width: 100vw;
   display: flex; flex-direction: column; background: var(--surface); color: var(--text);
   border-left: 1px solid var(--border); box-shadow: -16px 0 48px rgba(0, 0, 0, 0.25);
 }