@amenophis1er/foreman 0.1.6 → 0.1.8

package/README.md

@@ -69,6 +69,7 @@ exits. Nothing blocks unless it says so.
 | Variable | Meaning | Default |
 |---|---|---|
 | `PORT` | listen port | `4177` |
+| `FOREMAN_SERVICES_PORT` | the port dev servers the crew exposed are proxied on — their own origin, so a page the crew built cannot call Foreman's API | `PORT` + 1 |
 | `FOREMAN_HOME` | state directory: runs, settings, logs | `~/.foreman` |
 | `FOREMAN_BIND` | `auto` (loopback + Tailscale when present), `local`, or `all` | `auto` |
 | `FOREMAN_BROWSER` | browser for missions: `chrome`, `chromium`, `msedge`, `firefox` | `chrome` |
@@ -94,7 +95,8 @@ exits. Nothing blocks unless it says so.
 4. **Files.** What the run changed, against a baseline taken at start (git
    ref or snapshot), with diffs; what it produced — screenshots, logs, work
    files — viewable in place, arrow keys to step through; any dev server the
-   crew exposed, one click away. HTML renders in a sandbox with its own
+   crew exposed, one click away — on its own port, and so its own origin, so a
+   page an agent wrote cannot turn around and call Foreman's API. HTML renders in a sandbox with its own
    scripts, so a built page is a page, not a source listing.
 5. **Next.** A finished run is a starting point: **Plan the next step** opens
    a new planning conversation already seeded with what was built, the
@@ -128,7 +130,11 @@ itself. A local model is `free`. A cloud model with no published price is
 `unpriced`, and the meter shows what is true instead: tokens in, tokens out,
 turns. The one exception is a dated table of OpenAI's list prices, visible in
 `src/openai-prices.ts` with the day it was checked. Budget caps bind on
-dollars where dollars are real and on wall clock always.
+dollars where dollars are real and on wall clock always — and, on a run that
+is `free` or `unpriced`, on tokens too: 20M by default across input, output and
+cache, because turns and minutes alone do not notice a director whose turns
+are cheap and enormous. A priced run is never ended by tokens; its budget is
+its cap.
 
 Which account pays is printed at startup and shown wherever a mission can be
 started. Pin it with `FOREMAN_CLAUDE_CONFIG_DIR`; assert it with
@@ -224,7 +230,7 @@ result.
 ```sh
 npm ci && npm run setup      # dependencies, then the dashboard build
 npm start                    # serves http://localhost:4177
-npm test                     # 299 tests, node:test
+npm test                     # 360 tests, node:test
 npm run typecheck            # server and dashboard
 npm run dev                  # API + Vite together
 scripts/dev-restart.sh       # restarts the server only when nothing would be lost

package/bin/foreman.mjs

@@ -33,6 +33,7 @@ const USAGE = `foreman ${pkg.version}
 
   foreman uninstall          Remove the service and the background server; keeps ~/.foreman
   foreman uninstall --purge --yes   …and delete ~/.foreman (every run's history) too
+  foreman completion install Tab-completion for these commands (zsh, bash, fish); or "completion zsh" to print it
   foreman --version | --help
 
 Environment:
@@ -55,7 +56,7 @@ if (command === '--help' || command === '-h' || command === 'help') {
 } else if (command === 'start') {
   register();
   await import(new URL('../src/server.ts', import.meta.url).href);
-} else if (['doctor', 'open', 'service', 'up', 'down', 'stop', 'restart', 'status', 'logs', 'uninstall', 'update'].includes(command)) {
+} else if (['doctor', 'open', 'service', 'up', 'down', 'stop', 'restart', 'status', 'logs', 'uninstall', 'update', 'completion'].includes(command)) {
   register();
   const { runCli } = await import(new URL('../src/cli.ts', import.meta.url).href);
   process.exitCode = await runCli(command, rest, { version: pkg.version, bin: new URL(import.meta.url) });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amenophis1er/foreman",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Autonomous mission runner on the Claude Agent SDK: a director plans, delegates to workers, verifies, and reports — from one dashboard, your phone, or the CLI.",
   "keywords": [
     "claude",

package/src/browser.ts

@@ -0,0 +1,188 @@
+/**
+ * The browser missions get, and how one is installed when there is none.
+ *
+ * The crew's browser is Playwright's MCP in headless mode with its own
+ * profile — never the person's Chrome. Which executable it drives used to be
+ * a fixed channel: Chrome unless FOREMAN_BROWSER said otherwise. On a machine
+ * with no Chrome that failed even after a director had downloaded Playwright's
+ * own Chromium, because nothing looked for it. Now the choice is detected:
+ * FOREMAN_BROWSER when set, else the machine's Chrome, else the Chromium
+ * Playwright installs — and that last one can be installed from the setup
+ * page, as the user, into Playwright's own cache, no root needed.
+ */
+import os from 'node:os';
+import path from 'node:path';
+import { access } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { execFile, spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+/** The Playwright MCP's entry point, shipped as Foreman's own dependency. */
+export const PLAYWRIGHT_MCP_CLI = fileURLToPath(new URL('../node_modules/@playwright/mcp/cli.js', import.meta.url));
+
+export type BrowserChannel = 'chrome' | 'msedge' | 'firefox' | 'chromium';
+
+export interface BrowserFound {
+  channel: BrowserChannel;
+  path: string;
+  /** What to call it in a sentence. */
+  label: string;
+}
+
+const exists = (p: string) => access(p, constants.F_OK).then(() => true, () => false);
+
+/** The playwright-core the MCP itself uses — the one whose Chromium build the MCP can drive. */
+function playwrightCore(): { dir: string; chromiumPath: string | null } | null {
+  try {
+    const req = createRequire(PLAYWRIGHT_MCP_CLI);
+    const dir = path.dirname(req.resolve('playwright-core/package.json'));
+    let chromiumPath: string | null = null;
+    try {
+      chromiumPath = (req('playwright-core') as { chromium: { executablePath(): string } }).chromium.executablePath();
+    } catch { /* no build registered */ }
+    return { dir, chromiumPath };
+  } catch {
+    return null;
+  }
+}
+
+function candidates(channel: Exclude<BrowserChannel, 'chromium'>): string[] {
+  const mac = process.platform === 'darwin';
+  const win = process.platform === 'win32';
+  switch (channel) {
+    case 'chrome':
+      return mac
+        ? ['/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', path.join(os.homedir(), 'Applications/Google Chrome.app/Contents/MacOS/Google Chrome')]
+        : win
+          ? [
+              path.join(process.env.ProgramFiles ?? 'C:\\Program Files', 'Google', 'Chrome', 'Application', 'chrome.exe'),
+              path.join(process.env['ProgramFiles(x86)'] ?? 'C:\\Program Files (x86)', 'Google', 'Chrome', 'Application', 'chrome.exe'),
+              path.join(process.env.LOCALAPPDATA ?? '', 'Google', 'Chrome', 'Application', 'chrome.exe'),
+            ]
+          : ['/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/opt/google/chrome/chrome', '/usr/bin/chromium', '/usr/bin/chromium-browser', '/snap/bin/chromium'];
+    case 'msedge':
+      return mac ? ['/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge']
+        : win ? [path.join(process.env['ProgramFiles(x86)'] ?? 'C:\\Program Files (x86)', 'Microsoft', 'Edge', 'Application', 'msedge.exe')]
+        : ['/usr/bin/microsoft-edge', '/usr/bin/microsoft-edge-stable'];
+    case 'firefox':
+      return mac ? ['/Applications/Firefox.app/Contents/MacOS/firefox'] : ['/usr/bin/firefox'];
+  }
+}
+
+const LABEL: Record<BrowserChannel, string> = { chrome: 'Google Chrome', msedge: 'Microsoft Edge', firefox: 'Firefox', chromium: 'Playwright Chromium' };
+
+async function find(channel: BrowserChannel): Promise<BrowserFound | null> {
+  if (channel === 'chromium') {
+    const p = playwrightCore()?.chromiumPath ?? null;
+    return p && (await exists(p)) ? { channel, path: p, label: LABEL.chromium } : null;
+  }
+  for (const p of candidates(channel)) if (await exists(p)) return { channel, path: p, label: LABEL[channel] };
+  return null;
+}
+
+/**
+ * The browser missions will run on, or null when there is none. Honours
+ * FOREMAN_BROWSER as a pin (an explicit choice is never silently replaced);
+ * otherwise Chrome, then Playwright's Chromium, in that order — Chrome needs
+ * no download and is what most machines have.
+ */
+export async function detectBrowser(): Promise<BrowserFound | null> {
+  const pinned = (process.env.FOREMAN_BROWSER || '').toLowerCase() as BrowserChannel | '';
+  if (pinned) return (['chrome', 'msedge', 'firefox', 'chromium'] as BrowserChannel[]).includes(pinned) ? find(pinned) : null;
+  return (await find('chrome')) ?? (await find('chromium'));
+}
+
+/**
+ * Can the executable actually start? On Linux a downloaded Chromium is a
+ * file that exists and a browser that does not: the system libraries it links
+ * against (glib, nss, …) are packages, and a slim machine lacks them. `--version`
+ * exits at once either way and fails with the loader's own message when they
+ * are missing. Only asked on Linux; elsewhere the download is the browser.
+ */
+export function browserStarts(executable: string): Promise<string | null> {
+  if (process.platform !== 'linux') return Promise.resolve(null);
+  return new Promise((resolve) => {
+    execFile(executable, ['--version'], { timeout: 8000 }, (err, _stdout, stderr) => {
+      if (!err) return resolve(null);
+      const text = String(stderr || err.message).trim().split('\n').pop() ?? '';
+      const lib = /error while loading shared libraries: ([^:]+)/.exec(text)?.[1];
+      resolve(lib ? `missing system library ${lib}` : text || 'it did not start');
+    });
+  });
+}
+
+/** The preflight row for the browser, from the same detection the crew gets. */
+export async function browserCheck(): Promise<{ status: 'ok' | 'warn'; detail: string; fix?: string }> {
+  const pinned = process.env.FOREMAN_BROWSER;
+  const found = await detectBrowser();
+  if (found) {
+    const broken = await browserStarts(found.path);
+    if (!broken) return { status: 'ok', detail: `${found.label} — ${found.path}` };
+    return {
+      status: 'warn',
+      detail: `${found.label} is installed but cannot start: ${broken}`,
+      // Root, once, and not something Foreman will do itself.
+      fix: 'The libraries are system packages and need root once: sudo npx playwright install-deps chromium',
+    };
+  }
+  return {
+    status: 'warn',
+    detail: pinned
+      ? `FOREMAN_BROWSER=${pinned} but no such browser was found; missions with browser on will fail`
+      : 'no Google Chrome or Playwright Chromium found; missions with browser on will fail',
+    fix: pinned
+      ? 'Install it, or unset FOREMAN_BROWSER to let Foreman pick'
+      : 'Install Google Chrome, or install Playwright Chromium from the dashboard\'s setup page (or: npx playwright install chromium)',
+  };
+}
+
+/**
+ * Installs Playwright's Chromium with playwright-core's own CLI — the same
+ * package the MCP loads, so the build it downloads is the one it can drive.
+ * Runs as the user, into Playwright's cache under the home directory; no
+ * root. Resolves to null on success or one sentence on failure. Progress
+ * lines (download percentages) are passed on as they arrive.
+ *
+ * On Linux the download can succeed while the system libraries Chromium
+ * needs are missing; those need root (`playwright install-deps`), which this
+ * never asks for — the message says so when it looks that way.
+ */
+export function installChromium(onProgress?: (line: string) => void, timeoutMs = 10 * 60_000): Promise<string | null> {
+  const core = playwrightCore();
+  if (!core) return Promise.resolve('Playwright is not available in this install of Foreman.');
+  const cli = path.join(core.dir, 'cli.js');
+  return new Promise((resolve) => {
+    let out = '';
+    let settled = false;
+    const done = (v: string | null) => { if (!settled) { settled = true; resolve(v); } };
+    let child;
+    try {
+      child = spawn(process.execPath, [cli, 'install', 'chromium'], { stdio: ['ignore', 'pipe', 'pipe'], env: process.env });
+    } catch (err) {
+      return done(`Could not start the installer: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const timer = setTimeout(() => { child.kill('SIGKILL'); done(`The download took longer than ${Math.round(timeoutMs / 60_000)} minutes and was stopped.`); }, timeoutMs);
+    const onData = (buf: Buffer) => {
+      const text = buf.toString();
+      out += text;
+      if (out.length > 64_000) out = out.slice(-32_000);
+      for (const piece of text.split(/[\r\n]+/)) {
+        const line = piece.trim();
+        if (line) onProgress?.(line);
+      }
+    };
+    child.stdout.on('data', onData);
+    child.stderr.on('data', onData);
+    child.on('error', (err) => { clearTimeout(timer); done(`Could not run the installer: ${err.message}`); });
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      if (code === 0) return done(null);
+      const last = out.trim().split('\n').filter(Boolean).pop() ?? '';
+      const hint = process.platform === 'linux' && /install-deps|missing dependencies|libnss|shared libraries/i.test(out)
+        ? ' Chromium is downloaded but some system libraries are missing; they need root: sudo npx playwright install-deps chromium.'
+        : '';
+      done(`The installer exited with code ${code}${last ? `: ${last}` : ''}.${hint}`);
+    });
+  });
+}

package/src/cli.ts

@@ -23,6 +23,11 @@ import { detectTailscale } from './tailscale.js';
 import { PACKAGE, checkForUpdate, currentVersion } from './update.js';
 
 const PORT = Number(process.env.PORT ?? 4177);
+/** The second listener, for exposed dev servers — same default as the server's. */
+const SERVICES_PORT = (() => {
+  const n = Number(process.env.FOREMAN_SERVICES_PORT);
+  return Number.isInteger(n) && n >= 1 && n <= 65535 ? n : PORT + 1;
+})();
 const HOME_DIR = process.env.FOREMAN_HOME || path.join(os.homedir(), '.foreman');
 const LABEL = 'dev.foreman.server';
 const PID_FILE = path.join(HOME_DIR, 'foreman.pid');
@@ -321,7 +326,7 @@ async function update(bin: string, flags: string[]): Promise<number> {
 async function doctor(): Promise<number> {
   const tailnet = await detectTailscale(PORT);
   const distDir = fileURLToPath(new URL('../ui/dist', import.meta.url));
-  const checks = await preflight({ port: PORT, foremanHome: HOME_DIR, distDir, tailnet });
+  const checks = await preflight({ port: PORT, servicesPort: SERVICES_PORT, foremanHome: HOME_DIR, distDir, tailnet });
   // Port-in-use is an error for `start` and a fact for `doctor`: it usually means Foreman is already up.
   for (const c of checks) {
     if (c.name.startsWith('Port') && c.status === 'error') { c.status = 'warn'; c.detail = 'in use — Foreman is probably already running'; c.fix = `foreman open · or PORT=${PORT + 1} foreman`; }
@@ -493,6 +498,19 @@ export async function runCli(command: string, rest: string[], ctx: { version: st
     case 'uninstall': return uninstall(rest);
     case 'status': return status();
     case 'doctor': return doctor();
+    case 'completion': {
+      const { completionScript, detectShell, installCompletion } = await import('./completion.js');
+      const arg = rest[0];
+      if (arg === 'zsh' || arg === 'bash' || arg === 'fish') { process.stdout.write(completionScript(arg)); return 0; }
+      if (arg === 'install') {
+        const shell = (rest[1] === 'zsh' || rest[1] === 'bash' || rest[1] === 'fish') ? rest[1] : detectShell();
+        if (!shell) { console.error('Could not tell your shell from $SHELL. Say which: foreman completion install zsh|bash|fish'); return 1; }
+        console.log(await installCompletion(shell));
+        return 0;
+      }
+      console.error('Usage: foreman completion zsh|bash|fish   (prints the script)\n       foreman completion install [zsh|bash|fish]   (adds it to your shell rc, once)');
+      return 1;
+    }
     case 'open': return open();
     case 'service': {
       const sub = rest[0];

package/src/clone.test.ts

@@ -0,0 +1,35 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { explainGitFailure, looksLikeRepoUrl, parseRepoUrl } from './clone.js';
+
+test('parseRepoUrl: the forms people paste all name the same repository', () => {
+  for (const s of ['https://github.com/acme/widget', 'https://github.com/acme/widget.git', 'https://github.com/acme/widget/', 'https://github.com/acme/widget/tree/main/src', 'acme/widget']) {
+    assert.deepEqual(parseRepoUrl(s), { url: 'https://github.com/acme/widget.git', name: 'widget', host: 'github.com' }, s);
+  }
+  assert.deepEqual(parseRepoUrl('git@github.com:acme/widget.git'), { url: 'git@github.com:acme/widget.git', name: 'widget', host: 'github.com' });
+  assert.deepEqual(parseRepoUrl('git@gitlab.com:group/sub/widget'), { url: 'git@gitlab.com:group/sub/widget.git', name: 'widget', host: 'gitlab.com' });
+  assert.deepEqual(parseRepoUrl('ssh://git@bitbucket.org:7999/proj/widget.git'), { url: 'ssh://git@bitbucket.org:7999/proj/widget.git', name: 'widget', host: 'bitbucket.org' });
+});
+
+test('parseRepoUrl: not a repository', () => {
+  for (const s of ['', 'https://github.com/acme', '/Users/me/Projects/x', '~/Projects/x', './x', 'just words here', 'https://example.com']) {
+    assert.equal(parseRepoUrl(s), null, s);
+  }
+});
+
+test('looksLikeRepoUrl separates repositories from folder paths for the shared link verbs', () => {
+  assert.equal(looksLikeRepoUrl('https://github.com/acme/widget'), true);
+  assert.equal(looksLikeRepoUrl('git@github.com:acme/widget.git'), true);
+  assert.equal(looksLikeRepoUrl('acme/widget'), true);
+  assert.equal(looksLikeRepoUrl('~/Projects/widget'), false);
+  assert.equal(looksLikeRepoUrl('/Users/me/widget'), false);
+  assert.equal(looksLikeRepoUrl('./widget'), false);
+});
+
+test('explainGitFailure turns stderr into one sentence a person can act on', () => {
+  const ref = { url: 'https://github.com/acme/secret.git', name: 'secret', host: 'github.com' };
+  assert.match(explainGitFailure('Cloning into...\nfatal: could not read Username for https://github.com: terminal prompts disabled', ref), /could not authenticate to github.com/);
+  assert.match(explainGitFailure('ERROR: Repository not found.\nfatal: Could not read from remote repository.', ref), /not found/);
+  assert.match(explainGitFailure("fatal: unable to access 'x': Could not resolve host: github.com", ref), /Could not reach github.com/);
+  assert.match(explainGitFailure('fatal: something odd', ref), /git clone failed: something odd/);
+});

package/src/clone.ts

@@ -0,0 +1,129 @@
+/**
+ * Linking a project that is not on this machine yet: a Git URL becomes a
+ * folder under the projects root, then the folder is linked like any other.
+ *
+ * Foreman runs `git clone` as the user — their SSH keys, credential helper
+ * and `gh auth` all apply, and Foreman never sees, asks for or stores a
+ * token. Prompts are disabled so a private repository with no credentials
+ * fails in seconds with git's own message instead of hanging on a password
+ * question nobody can see.
+ */
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+
+export interface RepoRef {
+  /** The URL git will be given, normalised. */
+  url: string;
+  /** Folder name under the projects root: the repository's name. */
+  name: string;
+  host: string;
+}
+
+/**
+ * Accepts the forms people paste: `https://github.com/o/r`, with or without
+ * `.git` or a trailing slash, `git@github.com:o/r.git`, `ssh://git@host/o/r`,
+ * and the shorthand `owner/repo`, which means GitHub. Anything else is null.
+ */
+export function parseRepoUrl(input: string): RepoRef | null {
+  const s = input.trim();
+  if (!s || /\s/.test(s)) return null;
+  let m = /^(?:https?:\/\/)([^/\s]+)\/(.+?)(?:\.git)?\/?$/i.exec(s);
+  if (m) {
+    const host = m[1].toLowerCase();
+    const segs = m[2].split('/').filter(Boolean);
+    if (segs.length < 2) return null;
+    // A web URL to a page inside the repo (tree/…, blob/…) still names the repo.
+    const repo = segs.slice(0, 2).join('/');
+    return { url: `https://${host}/${repo}.git`, name: safeName(segs[1]), host };
+  }
+  m = /^git@([^:\s]+):(.+?)(?:\.git)?\/?$/i.exec(s);
+  if (m) {
+    const segs = m[2].split('/').filter(Boolean);
+    if (segs.length < 1) return null;
+    return { url: s.endsWith('.git') ? s : `${s.replace(/\/$/, '')}.git`, name: safeName(segs[segs.length - 1]), host: m[1].toLowerCase() };
+  }
+  m = /^ssh:\/\/(?:[^@/\s]+@)?([^/\s:]+)(?::\d+)?\/(.+?)(?:\.git)?\/?$/i.exec(s);
+  if (m) {
+    const segs = m[2].split('/').filter(Boolean);
+    if (segs.length < 1) return null;
+    return { url: s, name: safeName(segs[segs.length - 1]), host: m[1].toLowerCase() };
+  }
+  m = /^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(s);
+  if (m && !s.startsWith('.') && !s.startsWith('/')) {
+    return { url: `https://github.com/${m[1]}/${m[2]}.git`, name: safeName(m[2]), host: 'github.com' };
+  }
+  return null;
+}
+
+/** Does this look like a repository rather than a folder path? Cheap gate for the shared "link" verbs. */
+export function looksLikeRepoUrl(input: string): boolean {
+  const s = input.trim();
+  return /^(https?:\/\/|git@|ssh:\/\/)/i.test(s) || (/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(s) && !s.startsWith('.') && !s.startsWith('~'));
+}
+
+function safeName(raw: string): string {
+  return raw.replace(/\.git$/i, '').replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^[-.]+|[-.]+$/g, '').slice(0, 80) || 'repo';
+}
+
+/** Git's stderr, reduced to the one line a person needs. */
+export function explainGitFailure(stderr: string, ref: RepoRef): string {
+  const t = stderr.trim();
+  if (/could not read Username|Authentication failed|terminal prompts disabled|Permission denied \(publickey\)|could not read Password/i.test(t)) {
+    return `Git could not authenticate to ${ref.host}. For a private repository, set up a credential helper or gh auth, or use the SSH URL with a key this machine has.`;
+  }
+  if (/Repository not found|not found|does not exist/i.test(t)) return `Git says the repository was not found at ${ref.url}. Check the URL — or it is private and this machine cannot see it.`;
+  if (/Could not resolve host|unable to access/i.test(t)) return `Could not reach ${ref.host}: ${t.split('\n').pop() ?? t}`;
+  if (/Remote branch .* not found/i.test(t)) return t.split('\n').find((l) => /Remote branch/.test(l)) ?? t;
+  const last = t.split('\n').filter((l) => l.trim() && !/^Cloning into/.test(l)).pop();
+  return last ? `git clone failed: ${last.replace(/^fatal:\s*/i, '')}` : 'git clone failed.';
+}
+
+export interface CloneOptions {
+  ref: RepoRef;
+  dest: string;
+  branch?: string;
+  /** Git's progress lines ("Receiving objects: 42%"), as they arrive. */
+  onProgress?: (line: string) => void;
+  timeoutMs?: number;
+}
+
+/**
+ * `git clone --progress [-b branch] url dest`, as the user. Resolves to null
+ * on success or to one explanatory sentence on failure. Never throws.
+ */
+export function cloneRepo(opts: CloneOptions): Promise<string | null> {
+  const { ref, dest, branch, onProgress, timeoutMs = 15 * 60_000 } = opts;
+  if (branch && !/^[A-Za-z0-9._\/-]{1,200}$/.test(branch)) return Promise.resolve('That branch name is not one git accepts.');
+  const args = ['clone', '--progress', ...(branch ? ['--branch', branch] : []), '--', ref.url, dest];
+  return new Promise((resolve) => {
+    let stderr = '';
+    let settled = false;
+    const done = (v: string | null) => { if (!settled) { settled = true; resolve(v); } };
+    let child;
+    try {
+      child = spawn('git', args, {
+        cwd: path.dirname(dest),
+        env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_ASKPASS: 'echo', SSH_ASKPASS: 'echo', GIT_SSH_COMMAND: process.env.GIT_SSH_COMMAND ?? 'ssh -o BatchMode=yes' },
+        stdio: ['ignore', 'ignore', 'pipe'],
+      });
+    } catch (err) {
+      return done(`Could not start git: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const timer = setTimeout(() => { child.kill('SIGKILL'); done(`git clone took longer than ${Math.round(timeoutMs / 60_000)} minutes and was stopped.`); }, timeoutMs);
+    child.stderr.on('data', (buf: Buffer) => {
+      const text = buf.toString();
+      stderr += text;
+      if (stderr.length > 64_000) stderr = stderr.slice(-32_000);
+      // Progress arrives as carriage-return-separated updates on one line.
+      for (const piece of text.split(/[\r\n]+/)) {
+        const line = piece.trim();
+        if (line && /(objects|deltas|Cloning|Updating|Checking)/i.test(line)) onProgress?.(line);
+      }
+    });
+    child.on('error', (err) => { clearTimeout(timer); done(`Could not run git: ${err.message}. Is git installed?`); });
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      done(code === 0 ? null : explainGitFailure(stderr, ref));
+    });
+  });
+}

package/src/completion.test.ts

@@ -0,0 +1,30 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { COMMANDS, SERVICE_COMMANDS, completionScript, detectShell, installTarget } from './completion.js';
+
+test('every shell script names every command and the service verbs', () => {
+  for (const shell of ['zsh', 'bash', 'fish'] as const) {
+    const s = completionScript(shell);
+    for (const [c] of COMMANDS) assert.ok(s.includes(c), `${shell} lacks ${c}`);
+    for (const c of SERVICE_COMMANDS) assert.ok(s.includes(c), `${shell} lacks service ${c}`);
+    const flags = shell === 'fish' ? ['-l force', '-l purge'] : ['--force', '--purge'];
+    for (const f of flags) assert.ok(s.includes(f), `${shell} lacks flag ${f}`);
+  }
+  assert.match(completionScript('zsh'), /^#compdef foreman\n/);
+  assert.match(completionScript('zsh'), /compdef _foreman foreman\n$/);
+  assert.match(completionScript('bash'), /complete -F _foreman foreman\n$/);
+  assert.match(completionScript('fish'), /^complete -c foreman -f\n/);
+});
+
+test('detectShell reads $SHELL and ignores anything else', () => {
+  assert.equal(detectShell({ SHELL: '/bin/zsh' }), 'zsh');
+  assert.equal(detectShell({ SHELL: '/opt/homebrew/bin/fish' }), 'fish');
+  assert.equal(detectShell({ SHELL: '/bin/tcsh' }), null);
+  assert.equal(detectShell({}), null);
+});
+
+test('installTarget: rc line for zsh and bash, a completions file for fish', () => {
+  assert.deepEqual(installTarget('zsh', '/home/u'), { file: '/home/u/.zshrc', line: 'eval "$(foreman completion zsh)" # foreman completion' });
+  assert.equal(installTarget('bash', '/home/u').file, '/home/u/.bashrc');
+  assert.deepEqual(installTarget('fish', '/home/u'), { file: '/home/u/.config/fish/completions/foreman.fish' });
+});

package/src/completion.ts

@@ -0,0 +1,113 @@
+/**
+ * Shell completion for the `foreman` command.
+ *
+ * `foreman completion <shell>` prints a script; `foreman completion install`
+ * wires it into the shell's rc file, once, behind a marker — the only file
+ * outside ~/.foreman the CLI ever writes, and only when asked by name.
+ */
+import os from 'node:os';
+import path from 'node:path';
+import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+
+export type Shell = 'zsh' | 'bash' | 'fish';
+
+/** Every top-level command with the one line the menu shows for it. Keep in step with bin/foreman.mjs USAGE. */
+export const COMMANDS: Array<[string, string]> = [
+  ['start', 'Start in this terminal'],
+  ['up', 'Start in the background'],
+  ['stop', 'Stop it, however it was started'],
+  ['restart', 'Stop and start it again the same way'],
+  ['status', 'Is a server up, on which port, started how'],
+  ['logs', 'Tail the log'],
+  ['open', 'Open the dashboard in your browser'],
+  ['doctor', 'Check credentials, providers, browser, port, Tailscale'],
+  ['update', 'Install the latest version and restart'],
+  ['service', 'Keep Foreman running at login'],
+  ['uninstall', 'Remove the service and the background server'],
+  ['completion', 'Shell completion: zsh, bash, fish, or install'],
+  ['help', 'Show usage'],
+  ['version', 'Print the version'],
+];
+export const SERVICE_COMMANDS = ['install', 'uninstall', 'start', 'stop', 'restart', 'status', 'logs'];
+export const COMPLETION_ARGS = ['zsh', 'bash', 'fish', 'install'];
+const FLAGS: Record<string, string[]> = { update: ['--force'], uninstall: ['--purge', '--yes'] };
+
+const q = (s: string) => `'${s.replace(/'/g, "'\\''")}'`;
+
+export function completionScript(shell: Shell): string {
+  const names = COMMANDS.map(([c]) => c).join(' ');
+  if (shell === 'zsh') {
+    return [
+      '#compdef foreman',
+      '_foreman() {',
+      '  local -a cmds',
+      `  cmds=(${COMMANDS.map(([c, d]) => q(`${c}:${d}`)).join(' ')})`,
+      '  if (( CURRENT == 2 )); then _describe -t commands "foreman command" cmds; return; fi',
+      '  case "${words[2]}" in',
+      `    service) local -a svc; svc=(${SERVICE_COMMANDS.map(q).join(' ')}); _describe -t commands "service command" svc ;;`,
+      `    completion) local -a sh; sh=(${COMPLETION_ARGS.map(q).join(' ')}); _describe -t commands "shell" sh ;;`,
+      ...Object.entries(FLAGS).map(([c, f]) => `    ${c}) local -a fl; fl=(${f.map(q).join(' ')}); _describe -t options "flag" fl ;;`),
+      '  esac',
+      '}',
+      'compdef _foreman foreman',
+      '',
+    ].join('\n');
+  }
+  if (shell === 'bash') {
+    return [
+      '_foreman() {',
+      '  local cur prev',
+      '  cur="${COMP_WORDS[COMP_CWORD]}"',
+      '  prev="${COMP_WORDS[COMP_CWORD-1]}"',
+      `  if [ "$COMP_CWORD" -eq 1 ]; then COMPREPLY=( $(compgen -W "${names}" -- "$cur") ); return; fi`,
+      '  case "$prev" in',
+      `    service) COMPREPLY=( $(compgen -W "${SERVICE_COMMANDS.join(' ')}" -- "$cur") ) ;;`,
+      `    completion) COMPREPLY=( $(compgen -W "${COMPLETION_ARGS.join(' ')}" -- "$cur") ) ;;`,
+      ...Object.entries(FLAGS).map(([c, f]) => `    ${c}) COMPREPLY=( $(compgen -W "${f.join(' ')}" -- "$cur") ) ;;`),
+      '  esac',
+      '}',
+      'complete -F _foreman foreman',
+      '',
+    ].join('\n');
+  }
+  return [
+    'complete -c foreman -f',
+    ...COMMANDS.map(([c, d]) => `complete -c foreman -n __fish_use_subcommand -a ${c} -d ${q(d)}`),
+    `complete -c foreman -n '__fish_seen_subcommand_from service' -a '${SERVICE_COMMANDS.join(' ')}'`,
+    `complete -c foreman -n '__fish_seen_subcommand_from completion' -a '${COMPLETION_ARGS.join(' ')}'`,
+    ...Object.entries(FLAGS).flatMap(([c, f]) => f.map((flag) => `complete -c foreman -n '__fish_seen_subcommand_from ${c}' -l ${flag.replace(/^--/, '')}`)),
+    '',
+  ].join('\n');
+}
+
+/** The user's shell from $SHELL, or null when it is none of the three. */
+export function detectShell(env: NodeJS.ProcessEnv = process.env): Shell | null {
+  const name = path.basename(env.SHELL ?? '');
+  return name === 'zsh' || name === 'bash' || name === 'fish' ? name : null;
+}
+
+const MARKER = '# foreman completion';
+
+/**
+ * Where the hook goes, and what it is. zsh and bash source the script at
+ * shell start; fish loads a file from its completions directory on demand.
+ */
+export function installTarget(shell: Shell, home = os.homedir()): { file: string; line?: string } {
+  if (shell === 'fish') return { file: path.join(home, '.config', 'fish', 'completions', 'foreman.fish') };
+  const file = shell === 'zsh' ? path.join(home, '.zshrc') : path.join(home, '.bashrc');
+  return { file, line: `eval "$(foreman completion ${shell})" ${MARKER}` };
+}
+
+/** Idempotent: a second install finds the marker and changes nothing. Returns what happened. */
+export async function installCompletion(shell: Shell, home = os.homedir()): Promise<string> {
+  const target = installTarget(shell, home);
+  if (!target.line) {
+    await mkdir(path.dirname(target.file), { recursive: true });
+    await writeFile(target.file, completionScript('fish'));
+    return `Wrote ${target.file}. Open a new fish shell.`;
+  }
+  const current = await readFile(target.file, 'utf8').catch(() => '');
+  if (current.includes(MARKER)) return `Already installed in ${target.file}.`;
+  await appendFile(target.file, `${current.endsWith('\n') || !current ? '' : '\n'}${target.line}\n`);
+  return `Added one line to ${target.file}. Open a new shell, or run: source ${target.file}`;
+}

package/src/deck.test.ts

@@ -306,7 +306,7 @@ test('handleDeckRoute: matches only its two routes, 404s unknown runs and bad pa
   const runs: Record<string, { folder: string }> = { 'run-1': { folder } };
   const server = http.createServer(async (req, res) => {
     const url = new URL(req.url ?? '/', 'http://localhost');
-    const handled = await handleDeckRoute(req, res, url, async (id) => runs[id] ?? null);
+    const handled = await handleDeckRoute(req, res, url, async (_scope, id) => runs[id] ?? null);
     // A status no deck response ever uses, so the test can see "fell through".
     if (!handled) { res.writeHead(418); res.end(); }
   });
@@ -372,7 +372,7 @@ test('preview route: real types inside a CSP sandbox, still jailed', async () =>
   await writeFile(path.join(dir, 'styles.css'), 'body{margin:0}');
   await writeFile(path.join(dir, 'app.js'), 'fetch("data.json")');
   const server = http.createServer((req, res) => {
-    void handleDeckRoute(req, res, new URL(req.url ?? '/', 'http://x'), async (id) => id === 'run-1' ? { folder: dir } : null)
+    void handleDeckRoute(req, res, new URL(req.url ?? '/', 'http://x'), async (_scope, id) => id === 'run-1' ? { folder: dir } : null)
       .then((handled) => { if (!handled) { res.statusCode = 404; res.end(); } });
   });
   await new Promise<void>((r) => server.listen(0, '127.0.0.1', r));