@oddessentials/agent-guild 0.31.0 → 0.33.0

package/README.md

@@ -195,8 +195,11 @@ of them from the box at its top; it starts on the repository the focused
 terminal's folder is a clone of. **Issues** lists, opens, edits and closes
 issues. **Actions** shows the latest workflow runs and whether one is still
 going, refreshing while it is on screen. **Pull requests** lists the open
-ones. **Repositories** lists and creates repositories and clones them over SSH
-with a key Agent Guild keeps for each account. On a wide window the side panel
+ones. **Branches** lists every remote branch of the selected repository, with
+its default and protected branches marked. Filter by name, copy a branch name,
+or open it on GitHub. Larger lists load progressively; **Refresh** checks for
+changes while keeping your place in the list. **Repositories** lists and creates
+repositories and clones them over SSH with a key Agent Guild keeps for each account. On a wide window the side panel
 makes room for itself; on a smaller one it lies over the cards, and over the
 terminals when they would get too narrow. Drag its edge to resize it. Escape
 or **Close** puts it away.
@@ -218,6 +221,17 @@ a stop or restart, remains unavailable after a brief recovery check, or a
 new version is discovered after the initial version check. Session activity
 and assistant responses have no sounds:
 the providers do not yet offer consistently reliable completion signals.
+**Launch at sign-in**, in the same menu, starts the session manager in the
+background whenever you sign in to the computer running Agent Guild; open
+the page as usual afterwards. On Windows it is an entry in Task Manager's
+Startup apps, on macOS a background item named Agent Guild under System
+Settings › General › Login Items & Extensions, and on Linux an entry named
+Agent Guild in the desktop's startup settings, so it needs a desktop session
+there: a server reached over SSH does not start it. macOS keeps its own
+switch for that item, which Agent Guild cannot read: switched off there, it
+does not start even while **Launch at sign-in** is checked. While it is on,
+the setting says when it last ran at sign-in and whether the session manager
+started then.
 
 The browser tab icon adds a rotating green ring whenever any session card says
 **Working**, including Shell and task cards. It mirrors the cards' terminal
@@ -277,8 +291,9 @@ turn on **Agent reporting** on its card once, which installs an Agent Guild
 plugin into Antigravity. It reports the model and the conversation, but no
 helper agents or shell commands. Grok Build cannot take hooks for one session yet; add the hooks
 from [examples/grok-hooks.json](examples/grok-hooks.json) to see its agents.
-When a tool's hooks do not run, because hooks are turned off, restricted by
-an administrator or not trusted for the folder, the card says so.
+When a tool's hooks have not reported some time after a prompt was sent,
+because hooks are turned off, restricted by an administrator or not trusted
+for the folder, the card says so.
 
 The card also names the model, from the hooks, from `--model` or from the
 tool's screen.
@@ -305,6 +320,29 @@ Any other tool or script can report agents and its model too. See
 * Usage meters are fetched by the manager with each tool's own sign-in. The
   page only receives percentages. On macOS the first lookup may ask for
   keychain access to the "Claude Code-credentials" item; choose Always Allow.
+* **Launch at sign-in** writes outside the data folder only while it is on:
+  the `AgentGuild` value under
+  `HKCU\Software\Microsoft\Windows\CurrentVersion\Run` on Windows, which
+  runs `autostart.js` from the data folder through `wscript.exe` so no
+  console window opens;
+  `~/Library/LaunchAgents/com.oddessentials.agent-guild.plist` on macOS,
+  which runs the `Agent Guild` script in the data folder so that macOS lists
+  it by that name; and `~/.config/autostart/agent-guild.desktop` on Linux,
+  which runs `autostart.sh` from the data folder. On Linux, a Node.js,
+  package or data folder path holding `"`, `` ` ``, `$` or `\` cannot be
+  used, because desktops read those differently in a startup entry; the
+  setting then says so. Each sign-in touches `sign-in-attempt` and records
+  its outcome in `sign-in.json` in the data folder.
+  Turning it off removes them, and an entry whose Agent Guild package has
+  been uninstalled or moved removes itself at the next sign-in. With nvm,
+  the package lives in the Node.js version's folder, so uninstalling that
+  version counts as uninstalling Agent Guild; a Homebrew Node.js upgrade
+  does not. On macOS and Linux what the entry runs at sign-in, including a
+  missing Node.js, is appended to `manager.log`.
+  The entry saves the manager's listening port, including the assigned port
+  when started with `AGENT_GUILD_PORT=0`. Enabled entries are updated when
+  the manager starts. A macOS entry disabled through `launchctl` stays off
+  until you explicitly turn **Launch at sign-in** back on.
 
 The manager makes these outbound requests, and none of them carry your code
 or prompts:

package/bin/agent-guild.mjs

@@ -13,12 +13,14 @@ import { spawn } from 'node:child_process';
 import {
   DEFAULT_HOST,
   VERSION,
+  dataDir,
   loadOrCreateToken,
   paths,
   readRuntimeFile,
   resolvePort,
 } from '../src/manager/config.mjs';
 import { spawnManager } from '../src/manager/launch.mjs';
+import { recordSignIn } from '../src/manager/autostart.mjs';
 
 function usage() {
   console.log(`Usage: agent-guild [command] [--no-browser]
@@ -122,8 +124,10 @@ async function ensureManager({ port = null } = {}) {
   throw new Error(`the session manager did not start.${details ? `\n\nRecent log (${paths.log}):\n${details}` : ''}`);
 }
 
-async function cmdOpen({ browser }) {
+/** `signIn`: run by the sign-in entry, which shows the page whether a manager answered. */
+async function cmdOpen({ browser, signIn = false }) {
   const { url, started, version } = await ensureManager();
+  if (signIn) recordSignIn(dataDir(), started ? 'started' : 'running');
   const token = loadOrCreateToken();
   const target = pageUrl(url, token);
   console.log(started ? `Session manager started at ${url}` : `Session manager already running at ${url}`);
@@ -132,7 +136,8 @@ async function cmdOpen({ browser }) {
   if (browser) {
     openBrowser(target);
     console.log('Opening Agent Guild in your browser. You can close the page at any time; sessions keep running.');
-  } else {
+  } else if (!signIn) {
+    // A sign-in entry's output goes to manager.log, which needs no token.
     console.log(`Open: ${target}`);
   }
 }
@@ -248,7 +253,7 @@ async function main() {
   if (flags.has('-h') || flags.has('--help') || command === 'help') return usage();
 
   switch (command) {
-    case 'open': return cmdOpen({ browser: !flags.has('--no-browser') });
+    case 'open': return cmdOpen({ browser: !flags.has('--no-browser'), signIn: flags.has('--sign-in') });
     case 'start': {
       await import('../src/manager/main.mjs').then(async (m) => {
         process.on('uncaughtException', (err) => console.error('[manager] unexpected error:', err));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oddessentials/agent-guild",
-  "version": "0.31.0",
+  "version": "0.33.0",
   "description": "Launch and watch AI coding-assistant terminal sessions from one local web page. A bundled session manager owns the terminals so the page can close and reconnect.",
   "license": "MIT",
   "repository": {

package/src/manager/autostart.mjs

@@ -0,0 +1,492 @@
+// Starting the session manager when the user signs in to the computer.
+//
+// Each platform gets one per-user entry that runs `agent-guild open
+// --no-browser`, which starts a background manager unless one answers:
+//
+// * Windows: a value under HKCU's Run key. It runs a JScript wrapper in the
+//   data folder through wscript.exe, which starts Node.js with no console
+//   window; running node.exe directly would flash one at every sign-in.
+// * macOS: a LaunchAgent with RunAtLoad. It runs a script named Agent Guild
+//   in the data folder, which System Settings lists by that name; running
+//   sh directly would list it as "sh". AbandonProcessGroup keeps launchd
+//   from killing the manager once the launching command exits.
+// * Linux: an XDG autostart entry, run when a desktop session starts. It
+//   runs a script in the data folder, as on macOS: desktops read Exec lines
+//   by different rules (systemd's autostart generator keeps a backslash that
+//   GLib removes), so the line holds only paths that read the same in all.
+//
+// Each launcher touches a file in the data folder before it starts Node.js,
+// and `open --sign-in` records whether a manager then answered, so the page
+// can say whether the last sign-in started the manager.
+//
+// The entry and the OS's enabled state record whether autostart is on, so
+// a user who turns it off outside the app sees it off here too.
+// Its paths are absolute, so a running manager rewrites an entry that is on
+// at every start: a Node.js version switch or a reinstall then takes effect
+// at the next sign-in. npm runs no script when a package is uninstalled, so
+// an entry whose package script is gone removes itself at sign-in instead
+// of failing there at every sign-in after. A missing Node.js alone keeps
+// the entry: the next manager to start points it at its own. Homebrew's
+// Node.js is named by its opt link, which an upgrade keeps, rather than by
+// the versioned Cellar folder the upgrade deletes.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { DEFAULT_PORT } from './config.mjs';
+
+export const ARGS = ['open', '--no-browser', '--sign-in'];
+export const WINDOWS_RUN_KEY = 'HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run';
+export const WINDOWS_APPROVED_KEY = 'HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\StartupApproved\\Run';
+export const WINDOWS_VALUE = 'AgentGuild';
+export const WINDOWS_WRAPPER = 'autostart.js';
+export const LAUNCH_AGENT_LABEL = 'com.oddessentials.agent-guild';
+export const MAC_LAUNCHER = 'Agent Guild';
+export const LINUX_LAUNCHER = 'autostart.sh';
+/** Touched by an entry each time it runs at sign-in. */
+export const SIGN_IN_ATTEMPT = 'sign-in-attempt';
+/** What `open --sign-in` found: `{ at, outcome }`. */
+export const SIGN_IN_RESULT = 'sign-in.json';
+/** How long after an entry runs a manager may take to answer before it counts as not started. */
+export const SIGN_IN_WAIT_MS = 30000;
+/** File times may be rounded, so a result this much older than its attempt still belongs to it. */
+const CLOCK_SLACK_MS = 2000;
+const OUTCOMES = new Set(['started', 'running']);
+/**
+ * macOS keeps its own switch for the item, which only an app signed to use
+ * SMAppService can read, so the page says where it is instead.
+ */
+export const MAC_NOTE = 'Starts the session manager in the background when you sign in to this Mac. The page does not open. macOS also lists it as Agent Guild under System Settings › General › Login Items & Extensions; switched off there, it does not start even while this is checked.';
+export const LINUX_NOTE = 'Starts the session manager in the background when you sign in to a desktop session on this computer. The page does not open. A computer with no desktop session, such as a server reached over SSH, does not start it. Desktop startup settings list it as Agent Guild.';
+/** Added to LINUX_NOTE when the manager itself was not started from a desktop session. */
+export const LINUX_NO_DESKTOP = 'This manager was not started from a desktop session, so this computer may not have one.';
+/** Characters that systemd's autostart generator and GLib read differently in an Exec line. */
+const EXEC_UNSAFE = /["`$\\]/;
+
+const failure = (message) => Object.assign(new Error(message), { status: 500, code: 'autostart_failed' });
+
+function portString(port) {
+  if (!Number.isInteger(port) || port < 1 || port > 65535) throw failure('The manager must be listening before saving its startup port.');
+  return String(port);
+}
+
+/** A JScript string literal: JSON's escapes, with everything outside ASCII as \u escapes so the file's code page cannot matter. */
+function jsString(value) {
+  return JSON.stringify(value).replace(/[\u007f-\uffff]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+}
+
+/**
+ * The JScript that wscript.exe runs at sign-in: the launcher with its
+ * window hidden (0), not waited for; or, once the package is gone, the
+ * removal of the Run value, its Task Manager setting and this file.
+ * `runKey` and `approvedKey` are replaceable in tests.
+ */
+export function windowsWrapper({ execPath, script, attempt, port = DEFAULT_PORT, runKey = WINDOWS_RUN_KEY, approvedKey = WINDOWS_APPROVED_KEY }) {
+  const command = [execPath, script].map((p) => `"${p}"`).concat(ARGS).join(' ');
+  return [
+    '// Agent Guild: starts the session manager at sign-in without a console window.',
+    'var files = new ActiveXObject("Scripting.FileSystemObject");',
+    'var shell = new ActiveXObject("WScript.Shell");',
+    `if (files.FileExists(${jsString(script)})) {`,
+    `  try { files.CreateTextFile(${jsString(attempt)}, true).Close(); } catch (e) {}`,
+    `  shell.Environment("Process")("AGENT_GUILD_PORT") = ${jsString(portString(port))};`,
+    `  shell.Run(${jsString(command)}, 0, false);`,
+    '} else {',
+    '  // Agent Guild is no longer installed here: remove this sign-in entry.',
+    `  try { shell.RegDelete(${jsString(`${runKey}\\${WINDOWS_VALUE}`)}); } catch (e) {}`,
+    `  try { shell.RegDelete(${jsString(`${approvedKey}\\${WINDOWS_VALUE}`)}); } catch (e) {}`,
+    '  try { files.DeleteFile(WScript.ScriptFullName); } catch (e) {}',
+    '}',
+    '',
+  ].join('\r\n');
+}
+
+/** The Run value's command line. */
+export function windowsRunCommand({ env, wrapper }) {
+  const wscript = path.win32.join(env.SystemRoot || env.SYSTEMROOT || env.WINDIR || 'C:\\Windows', 'System32', 'wscript.exe');
+  return `"${wscript}" //B //NoLogo "${wrapper}"`;
+}
+
+/**
+ * The sh launcher a macOS or Linux entry runs from the data folder, with
+ * Node.js, the package script, the entry's own file, the saved port, the
+ * manager log and the sign-in attempt file as its arguments, so no path is
+ * ever part of the script text. Its output, a missing Node.js included, is
+ * appended to the log when the log can be opened; the subshell tries first
+ * because a failed `exec` redirection would end sh before it starts
+ * anything. Once the package is gone it removes the entry and itself.
+ */
+export const POSIX_LAUNCHER = [
+  '#!/bin/sh',
+  '# Agent Guild: starts the session manager at sign-in. Its sign-in entry runs it',
+  '# with Node.js, the package script, the entry, the port, the log and a file it touches.',
+  'node="$1"; shift',
+  `if [ -f "$1" ]; then touch "$5" 2>/dev/null; if (exec >>"$4") 2>/dev/null; then exec >>"$4" 2>&1; echo "--- sign-in $(date -u +%Y-%m-%dT%H:%M:%SZ) ---"; fi; AGENT_GUILD_PORT="$3" exec "$node" "$1" ${ARGS.join(' ')}; fi`,
+  'rm -f "$2" "$0"',
+  '',
+].join('\n');
+
+/** What a macOS or Linux entry passes its launcher: Node.js, then the paths and port it reads. */
+function launchArgs({ execPath, script, file, port = DEFAULT_PORT, log, attempt }) {
+  return [execPath, script, file, portString(port), log, attempt];
+}
+
+/** The Linux entry's command line: sh, the launcher, then the arguments it reads. */
+export function posixCommand({ launcher, ...paths }) {
+  return ['/bin/sh', launcher, ...launchArgs(paths)];
+}
+
+/**
+ * Homebrew runs Node.js from `<prefix>/Cellar/<formula>/<version>`, which
+ * the next upgrade deletes. `<prefix>/opt/<formula>` follows the formula
+ * across upgrades, so it names Node.js instead when it leads to the same file.
+ */
+export function stableExecPath(execPath, realpath = fs.realpathSync) {
+  const match = execPath.match(/^(.+)\/Cellar\/([^/]+)\/[^/]+\/bin\/node$/);
+  if (!match) return execPath;
+  const opt = `${match[1]}/opt/${match[2]}/bin/node`;
+  try {
+    return realpath(opt) === realpath(execPath) ? opt : execPath;
+  } catch {
+    return execPath;
+  }
+}
+
+const xml = (value) => value.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
+
+export function launchAgentPlist({ launcher, execPath, script, file, port, log, attempt }) {
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+    '<plist version="1.0">',
+    '<dict>',
+    `  <key>Label</key><string>${LAUNCH_AGENT_LABEL}</string>`,
+    '  <key>ProgramArguments</key>',
+    '  <array>',
+    ...[launcher, ...launchArgs({ execPath, script, file, port, log, attempt })].map((arg) => `    <string>${xml(arg)}</string>`),
+    '  </array>',
+    '  <key>RunAtLoad</key><true/>',
+    '  <key>AbandonProcessGroup</key><true/>',
+    '</dict>',
+    '</plist>',
+    '',
+  ].join('\n');
+}
+
+/**
+ * One Exec argument, quoted by the Desktop Entry rules: `"`, `` ` ``, `$`
+ * and `\` are escaped inside the quotes, and the string-value escape then
+ * doubles every backslash again. `%` is the field-code prefix, so it is doubled.
+ * Entries refuse paths with the escaped characters, which systemd's
+ * autostart generator reads differently, so in practice only `%` changes.
+ */
+export function desktopArg(value) {
+  const quoted = `"${value.replace(/["`$\\]/g, (c) => `\\${c}`)}"`;
+  return quoted.replace(/\\/g, '\\\\').replace(/%/g, '%%');
+}
+
+export function desktopEntry(paths) {
+  return [
+    '[Desktop Entry]',
+    'Type=Application',
+    'Name=Agent Guild',
+    'Comment=Starts the Agent Guild session manager',
+    `Exec=${posixCommand(paths).map(desktopArg).join(' ')}`,
+    'Terminal=false',
+    'X-GNOME-Autostart-enabled=true',
+    '',
+  ].join('\n');
+}
+
+/** Whether a desktop entry is on: present and not hidden or turned off by a desktop's startup settings. */
+export function desktopEntryEnabled(text) {
+  return !/^Hidden\s*=\s*true\s*$/m.test(text) && !/^X-GNOME-Autostart-enabled\s*=\s*false\s*$/m.test(text);
+}
+
+/** Windows keeps a Task Manager "Disabled" in StartupApproved: an odd first byte means off. */
+export function approvedDisabled(stdout) {
+  const hex = String(stdout).match(new RegExp(`^\\s*${WINDOWS_VALUE}\\s+REG_BINARY\\s+([0-9A-F]{2})`, 'mi'))?.[1];
+  return hex !== undefined && (parseInt(hex, 16) & 1) === 1;
+}
+
+/** launchctl has used both booleans and enabled/disabled in its override list. */
+export function launchAgentDisabled(stdout) {
+  const body = String(stdout).match(/^\s*disabled services = \{([\s\S]*)\}\s*$/)?.[1];
+  if (body === undefined) throw failure('Unrecognized launchd startup settings.');
+  let disabled = false;
+  for (const line of body.split('\n').filter((row) => row.trim())) {
+    const row = line.match(/^\s*"([^"]+)"\s*=>\s*(true|false|enabled|disabled)\s*$/);
+    if (!row) throw failure('Unrecognized launchd startup settings.');
+    if (row[1] === LAUNCH_AGENT_LABEL) disabled = row[2] === 'true' || row[2] === 'disabled';
+  }
+  return disabled;
+}
+
+function runCommand(command) {
+  return (args) => new Promise((resolve) => {
+    execFile(command, args, { windowsHide: true, timeout: 10000 }, (err, stdout, stderr) => {
+      resolve({ status: err ? (typeof err.code === 'number' ? err.code : 1) : 0, stdout, stderr: stderr || err?.message || '' });
+    });
+  });
+}
+
+async function readText(file) {
+  try {
+    return await fs.promises.readFile(file, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+/**
+ * Writes `contents` unless the file already holds exactly that, with `mode`
+ * whatever the umask. The default is writable only by its owner: launchd
+ * skips an agent that others can write.
+ */
+async function writeIfChanged(file, contents, mode = 0o644) {
+  if ((await readText(file)) === contents) {
+    if (((await fs.promises.stat(file)).mode & 0o777) !== mode) await fs.promises.chmod(file, mode);
+    return;
+  }
+  await fs.promises.mkdir(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  await fs.promises.writeFile(tmp, contents);
+  await fs.promises.chmod(tmp, mode);
+  await fs.promises.rename(tmp, file);
+}
+
+/**
+ * What the entry did at the last sign-in it ran at, or null when it has not
+ * run since it was turned on: `{ at, outcome }`, where `outcome` is
+ * `started` or `running` (a manager already answered) as `open --sign-in`
+ * recorded it, `starting` while a manager may still be coming up, and
+ * `failed` once none answered in time.
+ */
+export async function lastSignIn(dataDir, now = Date.now()) {
+  let attempt;
+  try {
+    attempt = (await fs.promises.stat(path.join(dataDir, SIGN_IN_ATTEMPT))).mtimeMs;
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+  let result = null;
+  try {
+    result = JSON.parse(await readText(path.join(dataDir, SIGN_IN_RESULT)));
+  } catch { /* unreadable reads as none */ }
+  if (Number.isFinite(result?.at) && OUTCOMES.has(result.outcome) && result.at >= attempt - CLOCK_SLACK_MS) {
+    return { at: new Date(result.at).toISOString(), outcome: result.outcome };
+  }
+  return { at: new Date(attempt).toISOString(), outcome: now - attempt < SIGN_IN_WAIT_MS ? 'starting' : 'failed' };
+}
+
+/** Records what `open --sign-in` found; best effort, since the manager runs either way. */
+export function recordSignIn(dataDir, outcome, now = Date.now()) {
+  try {
+    const file = path.join(dataDir, SIGN_IN_RESULT);
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify({ at: now, outcome }));
+    fs.renameSync(tmp, file);
+  } catch { /* nothing to report it to */ }
+}
+
+async function clearSignIns(dataDir) {
+  await fs.promises.rm(path.join(dataDir, SIGN_IN_ATTEMPT), { force: true });
+  await fs.promises.rm(path.join(dataDir, SIGN_IN_RESULT), { force: true });
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.script  bin/agent-guild.mjs of the package that is running
+ * @param {string} opts.dataDir  where the Windows wrapper is kept
+ * @param {string} [opts.log]  the manager log a macOS or Linux entry appends to
+ * @param {() => number} [opts.getPort]  the bound port, read only when writing an entry
+ * @param {string|null} [opts.unavailable]  a reason autostart cannot be offered, which turns it off here
+ * @param {(args: string[]) => Promise<{ status: number, stdout: string, stderr: string }>} [opts.reg]  reg.exe, replaceable in tests
+ * @param {(args: string[]) => Promise<{ status: number, stdout: string, stderr: string }>} [opts.launchctl]  launchctl, replaceable in tests
+ */
+export function createAutostart({
+  platform = process.platform,
+  env = process.env,
+  home = os.homedir(),
+  release = os.release(),
+  execPath = process.execPath,
+  script,
+  dataDir,
+  log = path.join(dataDir, 'manager.log'),
+  getPort = () => DEFAULT_PORT,
+  unavailable = null,
+  reg = runCommand(path.win32.join(env.SystemRoot || env.SYSTEMROOT || env.WINDIR || 'C:\\Windows', 'System32', 'reg.exe')),
+  uid = process.getuid?.(),
+  launchctl = runCommand('/bin/launchctl'),
+}) {
+  const entryExecPath = platform === 'win32' ? execPath : stableExecPath(execPath);
+  const attempt = path.join(dataDir, SIGN_IN_ATTEMPT);
+  const command = () => ({ execPath: entryExecPath, script, port: getPort(), log, attempt });
+  let note = null;
+  let unusable = null;
+  let refreshError = null;
+  let queue = Promise.resolve();
+  /** One change or check at a time, so two clicks cannot interleave their writes. */
+  const serial = (fn) => {
+    const run = queue.then(fn, fn);
+    queue = run.catch(() => {});
+    return run;
+  };
+
+  let target = null;
+  if (unavailable) {
+    // Offered nowhere: `reason` says why.
+  } else if (platform === 'win32') {
+    const wrapper = path.join(dataDir, WINDOWS_WRAPPER);
+    const approved = async () => {
+      // Clears a Task Manager "Disabled", which would otherwise outrank the Run value.
+      const r = await reg(['delete', WINDOWS_APPROVED_KEY, '/v', WINDOWS_VALUE, '/f']);
+      if (r.status !== 0 && (await reg(['query', WINDOWS_APPROVED_KEY, '/v', WINDOWS_VALUE])).status === 0) {
+        throw failure(`Could not clear the Task Manager startup setting: ${r.stderr.trim()}`);
+      }
+    };
+    target = {
+      async enabled() {
+        if ((await reg(['query', WINDOWS_RUN_KEY, '/v', WINDOWS_VALUE])).status !== 0) return false;
+        const state = await reg(['query', WINDOWS_APPROVED_KEY, '/v', WINDOWS_VALUE]);
+        return !(state.status === 0 && approvedDisabled(state.stdout));
+      },
+      write: () => writeIfChanged(wrapper, windowsWrapper(command())),
+      async enable() {
+        await this.write();
+        const r = await reg(['add', WINDOWS_RUN_KEY, '/v', WINDOWS_VALUE, '/t', 'REG_SZ', '/d', windowsRunCommand({ env, wrapper }), '/f']);
+        if (r.status !== 0) throw failure(`Could not add the startup entry: ${r.stderr.trim()}`);
+        await approved();
+      },
+      async disable() {
+        const r = await reg(['delete', WINDOWS_RUN_KEY, '/v', WINDOWS_VALUE, '/f']);
+        if (r.status !== 0 && (await reg(['query', WINDOWS_RUN_KEY, '/v', WINDOWS_VALUE])).status === 0) {
+          throw failure(`Could not remove the startup entry: ${r.stderr.trim()}`);
+        }
+        await reg(['delete', WINDOWS_APPROVED_KEY, '/v', WINDOWS_VALUE, '/f']);
+        await fs.promises.rm(wrapper, { force: true });
+      },
+    };
+  } else if (platform === 'darwin') {
+    const file = path.join(home, 'Library', 'LaunchAgents', `${LAUNCH_AGENT_LABEL}.plist`);
+    const launcher = path.join(dataDir, MAC_LAUNCHER);
+    const domain = `gui/${uid}`;
+    const disabled = async () => {
+      if (!Number.isInteger(uid) || uid < 0) throw failure('Could not determine the macOS user.');
+      const r = await launchctl(['print-disabled', domain]);
+      if (r.status !== 0) throw failure(`Could not read launchd startup settings: ${r.stderr.trim()}`);
+      return launchAgentDisabled(r.stdout);
+    };
+    target = {
+      async enabled() {
+        return (await readText(file)) !== null && !(await disabled());
+      },
+      async write() {
+        await writeIfChanged(launcher, POSIX_LAUNCHER, 0o755);
+        await writeIfChanged(file, launchAgentPlist({ ...command(), launcher, file }));
+      },
+      async enable() {
+        const previous = await readText(file);
+        // Check the domain before writing an entry we might be unable to enable.
+        await disabled();
+        await this.write();
+        try {
+          const r = await launchctl(['enable', `${domain}/${LAUNCH_AGENT_LABEL}`]);
+          if (r.status !== 0) throw failure(`Could not enable the launchd startup setting: ${r.stderr.trim()}`);
+          if (await disabled()) throw failure('launchd did not enable the startup setting.');
+        } catch (err) {
+          try {
+            if (previous === null) await this.disable();
+            else await writeIfChanged(file, previous);
+          } catch (restoreError) {
+            throw failure(`${err.message} Could not restore the previous startup entry: ${restoreError.message}`);
+          }
+          throw err;
+        }
+      },
+      async disable() {
+        await fs.promises.rm(file, { force: true });
+        await fs.promises.rm(launcher, { force: true });
+      },
+    };
+  } else if (platform === 'linux' && !(env.WSL_DISTRO_NAME || /microsoft|wsl/i.test(release))) {
+    const file = path.join(env.XDG_CONFIG_HOME || path.join(home, '.config'), 'autostart', 'agent-guild.desktop');
+    const launcher = path.join(dataDir, LINUX_LAUNCHER);
+    const unsafe = [entryExecPath, script, file, launcher, log, attempt].find((p) => EXEC_UNSAFE.test(p));
+    if (unsafe) {
+      unusable = `Not available because this path holds a character (", \`, $ or \\) that desktops read differently in a startup entry: ${unsafe}`;
+    } else {
+      const desktop = env.XDG_CURRENT_DESKTOP || env.WAYLAND_DISPLAY || env.DISPLAY;
+      note = desktop ? LINUX_NOTE : `${LINUX_NOTE} ${LINUX_NO_DESKTOP}`;
+      target = {
+        async enabled() {
+          const text = await readText(file);
+          return text !== null && desktopEntryEnabled(text);
+        },
+        async write() {
+          await writeIfChanged(launcher, POSIX_LAUNCHER, 0o755);
+          await writeIfChanged(file, desktopEntry({ ...command(), launcher, file }));
+        },
+        enable() { return this.write(); },
+        async disable() {
+          await fs.promises.rm(file, { force: true });
+          await fs.promises.rm(launcher, { force: true });
+        },
+      };
+    }
+  }
+  if (platform === 'darwin') note = MAC_NOTE;
+  const reason = target ? null
+    : unavailable || unusable || (platform === 'linux' ? 'Not available in WSL. Start Agent Guild from Windows to launch it at sign-in.'
+      : 'Not available on this operating system.');
+
+  const describe = async () => {
+    if (!target) return { available: false, enabled: false, reason };
+    try {
+      const enabled = await target.enabled();
+      return {
+        available: true,
+        enabled,
+        reason: enabled ? refreshError : null,
+        ...(note && { note }),
+        // An unreadable record never keeps the setting from being turned off.
+        lastRun: enabled ? await lastSignIn(dataDir).catch(() => null) : null,
+        log,
+      };
+    } catch (err) {
+      return { available: false, enabled: false, reason: `Could not read the startup setting: ${err.message}` };
+    }
+  };
+
+  return {
+    describe: () => serial(describe),
+    /** Turns autostart on or off and resolves to the new description. */
+    set: (enabled) => serial(async () => {
+      if (!target) throw Object.assign(new Error(reason), { status: 409, code: 'autostart_unavailable' });
+      try {
+        // A fresh start says it has not run yet rather than report an earlier time it was on.
+        if (!enabled || !(await target.enabled().catch(() => false))) await clearSignIns(dataDir);
+        await (enabled ? target.enable() : target.disable());
+        refreshError = null;
+        const state = await describe();
+        if (!state.available || state.enabled !== enabled) throw failure(state.reason || 'Could not verify the startup setting.');
+        return state;
+      } catch (err) {
+        throw err.code === 'autostart_failed' ? err : failure(`Could not change the startup setting: ${err.message}`);
+      }
+    }),
+    /** Points an entry that is on at this manager's Node.js, package and port. */
+    refresh: () => serial(async () => {
+      try {
+        if (target && await target.enabled()) await target.write();
+        refreshError = null;
+      } catch (err) {
+        refreshError = `Could not update the sign-in entry: ${err.message}`;
+        throw err;
+      }
+    }),
+  };
+}

package/src/manager/github-views.mjs

@@ -1,4 +1,4 @@
-// Issues, Actions runs and open pull requests of one repository, read with a
+// Branches, Issues, Actions runs and open pull requests of one repository, read with a
 // signed-in account. Reading and editing stay shallow: GitHub's page is the full view.
 
 import { nextLink, parseRepo } from './github.mjs';
@@ -114,6 +114,42 @@ export function createViews(github) {
   }
 
   return {
+    async branches(accountId, owner, name, { page = '1' } = {}) {
+      if (!/^[1-9]\d*$/.test(String(page)) || !Number.isSafeInteger(Number(page))) {
+        throw refusal(400, 'bad_page', 'page must be a positive integer');
+      }
+      page = Number(page);
+      // One metadata read per listing, never a protection request per branch.
+      const [listing, metadata] = await Promise.all([
+        call(accountId, owner, name, `/branches?per_page=100&page=${page}`),
+        page === 1 ? call(accountId, owner, name, '').then(({ body }) => ({ body }), (error) => ({ error: error.message })) : null,
+      ]);
+      const { body, res, repo } = listing;
+      if (!Array.isArray(body)) throw refusal(502, 'github_error', 'GitHub did not return a branch list');
+      let nextPage = null;
+      const next = nextLink(res.headers.get('link'));
+      if (next) {
+        // Reconstruct our own route; never send credentials to a supplied Link URL.
+        try { nextPage = Number(new URL(next).searchParams.get('page')); } catch { /* rejected below */ }
+        if (!Number.isSafeInteger(nextPage) || nextPage <= page) {
+          throw refusal(502, 'github_error', 'GitHub returned an invalid next page for branches');
+        }
+      }
+      const branches = body.filter((item) => typeof item?.name === 'string' && item.name.length > 0).map((item) => ({
+        name: item.name,
+        sha: typeof item.commit?.sha === 'string' && /^[a-f0-9]{40,64}$/i.test(item.commit.sha) ? item.commit.sha : null,
+        protected: item.protected === true,
+        url: `${WEB}/${repo.fullName}/tree/${encodeURIComponent(item.name)}`,
+      }));
+      return {
+        branches, nextPage,
+        defaultBranch: typeof metadata?.body?.default_branch === 'string' ? metadata.body.default_branch : null,
+        metadataError: metadata?.error ?? null,
+        fetchedAt: new Date().toISOString(),
+        url: `${WEB}/${repo.fullName}/branches`,
+      };
+    },
+
     async issues(accountId, owner, name, { state = 'open' } = {}) {
       if (state !== 'open' && state !== 'closed' && state !== 'all') throw refusal(400, 'bad_state', 'state must be open, closed or all');
       const { body, res, repo } = await call(accountId, owner, name, `/issues?state=${state}&per_page=${PAGE}&sort=updated&direction=desc`);