@amenophis1er/foreman 0.1.7 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amenophis1er/foreman",
-  "version": "0.1.7",
+  "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`; }

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/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));

package/src/deck.ts

@@ -759,6 +759,25 @@ async function artifactsFor(folder: string, runId: string, since: number | undef
   return out.slice(0, ARTIFACT_CAP);
 }
 
+/** Listed files per project tree. */
+const TREE_CAP = 2_000;
+
+/**
+ * The project's working tree as it stands: every file the deck would consider,
+ * minus `.foreman`, which is Foreman's own. No baseline, no diff — this is the
+ * view for a project between missions, where "what is in this folder" is the
+ * question and every run shares the answer.
+ */
+export async function projectTree(folder: string): Promise<{ files: DeckArtifact[]; truncated: boolean }> {
+  const { files, truncated } = await walk(folder, { skipWork: true, limit: TREE_CAP });
+  const out: DeckArtifact[] = [];
+  for (const f of files) {
+    if (f.rel === '.foreman' || f.rel.startsWith('.foreman/')) continue;
+    out.push({ path: f.rel, kind: artifactKind(f.rel), size: f.size, mtimeMs: f.mtimeMs });
+  }
+  return { files: out, truncated };
+}
+
 /**
  * Resolve an artifact path for serving, or null if it is not something the
  * deck may hand out. The jail is the realpath of `folder`: `..`, absolute
@@ -820,30 +839,37 @@ function sendJson(res: ServerResponse, code: number, body: unknown): void {
 }
 
 /**
- * `GET /runs/{id}/deck`, `GET /runs/{id}/artifact?path=<rel>` and
- * `GET /runs/{id}/preview/<rel>` (sandboxed render, see below). Returns
+ * `GET /runs/{id}/deck`, `GET /projects/{id}/tree`, `GET …/artifact?path=<rel>`
+ * and `GET …/preview/<rel>` (sandboxed render, see below). Returns
  * true when the URL was one of ours (whatever the outcome), false so the
  * caller's router falls through. `lookup` maps a run id to its folder; null
  * means unknown run, which is a 404 rather than an error.
  */
 export async function handleDeckRoute(
   req: IncomingMessage, res: ServerResponse, url: URL,
-  lookup: (runId: string) => Promise<{ folder: string } | null>,
+  lookup: (scope: 'runs' | 'projects', id: string) => Promise<{ folder: string } | null>,
 ): Promise<boolean> {
-  const m = url.pathname.match(/^\/runs\/([^/]+)\/(deck|artifact|preview)(?:\/(.*))?$/);
+  // The same jail and the same viewer serve two scopes: a run (its deck,
+  // relative to a baseline) and a project (its tree as it stands, no baseline).
+  const m = url.pathname.match(/^\/(runs|projects)\/([^/]+)\/(deck|tree|artifact|preview)(?:\/(.*))?$/);
   if (!m) return false;
-  const [, runId, what, previewRel] = m;
+  const [, scope, runId, what, previewRel] = m;
   if ((what === 'preview') !== (previewRel !== undefined)) return false;
+  if ((what === 'deck' && scope !== 'runs') || (what === 'tree' && scope !== 'projects')) return false;
   try {
     if (req.method !== 'GET') { sendJson(res, 405, { error: 'method not allowed' }); return true; }
     if (!RUN_ID_RE.test(runId)) { sendJson(res, 404, { error: 'not found' }); return true; }
-    const run = await lookup(runId);
+    const run = await lookup(scope as 'runs' | 'projects', runId);
     if (!run) { sendJson(res, 404, { error: 'not found' }); return true; }
 
     if (what === 'deck') {
       sendJson(res, 200, await deckFor(run.folder, runId));
       return true;
     }
+    if (what === 'tree') {
+      sendJson(res, 200, await projectTree(run.folder));
+      return true;
+    }
 
     if (what === 'preview') {
       // A rendered look at an HTML artifact. Files come out with their real

package/src/fleet-planner.ts

@@ -152,8 +152,9 @@ that project's planner; otherwise it comes to you.
 WHAT YOU CAN DO — through the tools, nothing else:
   - list_projects / project_detail / run_report: answer "how is X doing",
     "what needs me", "what happened to Y".
-  - create_project / link_project: a new folder under the projects root, or
-    an existing one, linked into the fleet.
+  - create_project / link_project: a new folder under the projects root, an
+    existing one, or a Git repository cloned under the root (link_project
+    with the URL), linked into the fleet.
   - open_planning: hand a request about an EXISTING codebase to that
     project's planner, which can read the folder. Use this whenever the right
     mission depends on what is already there. After you call it, that planner
@@ -280,8 +281,8 @@ export async function runFleetTurn(turn: FleetTurn): Promise<FleetResult> {
     tool('create_project', 'Create a new folder under the projects root and link it as a project. Use when the human wants to start something that has no home yet.',
       { name: z.string().describe('What to call it; becomes the folder name') },
       async ({ name }) => text(await safe(() => host.createProject(name)))),
-    tool('link_project', 'Link an existing folder as a project. The folder must already exist.',
-      { folder: z.string().describe('Absolute path, or ~/…') },
+    tool('link_project', 'Link an existing folder as a project — or clone a Git repository (a GitHub URL, a git@ URL, or owner/repo) under the projects root and link it. Cloning runs as the human with their own git credentials and can take a minute; wait for the result.',
+      { folder: z.string().describe('Absolute path, ~/…, or a Git repository URL') },
       async ({ folder }) => text(await safe(() => host.linkProject(folder)))),
     tool('open_planning', 'Hand the request to that project\'s planner, which can read the folder and will propose a mission. After this, the planner owns the conversation: tell the human in one line and stop.',
       {

package/src/gitwork.test.ts

@@ -0,0 +1,95 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { mkdtemp, writeFile } from 'node:fs/promises';
+import { closeMissionBranch, ensureMissionBranch, gitInfo, missionBranchName, startMissionBranch } from './gitwork.js';
+
+const sh = (cwd: string, ...args: string[]) => execFileSync('git', args, { cwd, stdio: 'pipe', env: { ...process.env, GIT_CONFIG_GLOBAL: '/dev/null' } }).toString();
+
+async function repo(): Promise<string> {
+  const dir = await mkdtemp(path.join(os.tmpdir(), 'gitwork-'));
+  sh(dir, 'init', '-q', '-b', 'main');
+  sh(dir, 'config', 'user.email', 'me@example.com');
+  sh(dir, 'config', 'user.name', 'Me');
+  await writeFile(path.join(dir, 'README.md'), 'hello\n');
+  sh(dir, 'add', '-A'); sh(dir, 'commit', '-q', '-m', 'init');
+  return dir;
+}
+
+test('missionBranchName: readable, bounded, unique per run', () => {
+  assert.equal(missionBranchName('Build Tick, a vanilla Pomodoro timer\nmore', '1788713434983-226123af'), 'foreman/build-tick-a-vanilla-pomodoro-timer-23af');
+  assert.match(missionBranchName('   \n!!!', 'run-xyz9'), /^foreman\/mission-xyz9$/);
+  assert.ok(missionBranchName('a '.repeat(80), 'r1').length < 60);
+});
+
+test('gitInfo: a plain folder is not a repo; a repo reports branch, head, dirty, remote', async () => {
+  const plain = await mkdtemp(path.join(os.tmpdir(), 'gitwork-plain-'));
+  assert.deepEqual(await gitInfo(plain), { repo: false });
+  const dir = await repo();
+  const info = await gitInfo(dir);
+  assert.equal(info.repo, true); assert.equal(info.branch, 'main'); assert.equal(info.dirty, false); assert.ok(info.head);
+  sh(dir, 'remote', 'add', 'origin', 'git@github.com:acme/widget.git');
+  await writeFile(path.join(dir, 'x.txt'), 'x');
+  const again = await gitInfo(dir);
+  assert.equal(again.dirty, true); assert.equal(again.remote, 'git@github.com:acme/widget.git');
+});
+
+test('a mission gets its own branch from the current one, and closing commits the work on it', async () => {
+  const dir = await repo();
+  const g = await startMissionBranch(dir, 'Add a footer to the page', 'run-1234abcd');
+  assert.ok(!('error' in g), JSON.stringify(g));
+  if ('error' in g) return;
+  assert.equal(g.branch, 'foreman/add-a-footer-to-the-page-abcd');
+  assert.equal(g.base, 'main');
+  assert.equal(sh(dir, 'rev-parse', '--abbrev-ref', 'HEAD').trim(), g.branch);
+
+  // Nothing to commit yet: no commit, zero commits ahead.
+  const idle = await closeMissionBranch(dir, g, 'foreman: nothing');
+  assert.equal(idle.committed, false); assert.equal(idle.commits, 0); assert.equal(idle.error, undefined);
+
+  await writeFile(path.join(dir, 'footer.html'), '<footer/>');
+  const closed = await closeMissionBranch(dir, g, 'foreman: Add a footer');
+  assert.equal(closed.committed, true); assert.equal(closed.commits, 1); assert.ok(closed.commit);
+  assert.equal(sh(dir, 'status', '--porcelain').trim(), '');
+  assert.match(sh(dir, 'log', '-1', '--format=%s'), /^foreman: Add a footer/);
+  // main is untouched.
+  assert.equal(sh(dir, 'rev-list', '--count', 'main').trim(), '1');
+});
+
+test('ensureMissionBranch goes back to the branch for a resume, and says why when it cannot', async () => {
+  const dir = await repo();
+  const g = await startMissionBranch(dir, 'Thing', 'run-1');
+  if ('error' in g) throw new Error(g.error);
+  sh(dir, 'checkout', '-q', 'main');
+  assert.equal(await ensureMissionBranch(dir, g.branch), null);
+  assert.equal(sh(dir, 'rev-parse', '--abbrev-ref', 'HEAD').trim(), g.branch);
+  assert.match((await ensureMissionBranch(dir, 'foreman/does-not-exist')) ?? '', /checkout/);
+});
+
+test('startMissionBranch on a plain folder says so instead of throwing', async () => {
+  const plain = await mkdtemp(path.join(os.tmpdir(), 'gitwork-plain2-'));
+  assert.deepEqual(await startMissionBranch(plain, 'x', 'r'), { error: 'not a git repository' });
+});
+
+test('remoteWebUrl and compareUrl: the three hosts people use, and a plain page elsewhere', async () => {
+  const { remoteWebUrl, compareUrl } = await import('./gitwork.js');
+  assert.deepEqual(remoteWebUrl('git@github.com:acme/widget.git'), { host: 'github.com', path: 'acme/widget', web: 'https://github.com/acme/widget' });
+  assert.deepEqual(remoteWebUrl('https://gitlab.com/group/sub/widget.git'), { host: 'gitlab.com', path: 'group/sub/widget', web: 'https://gitlab.com/group/sub/widget' });
+  assert.equal(remoteWebUrl(undefined), null);
+  assert.equal(compareUrl('git@github.com:acme/widget.git', 'main', 'foreman/x-1'), 'https://github.com/acme/widget/compare/main...foreman%2Fx-1?expand=1');
+  assert.match(compareUrl('https://gitlab.com/g/w.git', 'main', 'foreman/x') ?? '', /merge_requests\/new\?merge_request%5Bsource_branch%5D=foreman%2Fx/);
+  assert.match(compareUrl('git@bitbucket.org:t/w.git', 'main', 'foreman/x') ?? '', /pull-requests\/new\?source=foreman%2Fx&dest=main/);
+  assert.equal(compareUrl('https://git.example.com/a/b', 'main', 'x'), 'https://git.example.com/a/b');
+});
+
+test('prDraft: the run title, the brief, the boxes as the mission left them, and a footer', async () => {
+  const { prDraft } = await import('./gitwork.js');
+  const d = prDraft({ title: 'Add a footer', mission: 'Add a footer to the page.\nKeep it small.', costUsd: 0.42, costBasis: 'priced', git: { branch: 'foreman/add-a-footer-ab12', base: 'main', baseHead: null } },
+    '# Mission\n- [x] footer.html exists\n- [ ] linked from index\n');
+  assert.equal(d.title, 'Add a footer');
+  assert.match(d.body, /## Mission\n\nAdd a footer to the page\.\nKeep it small\./);
+  assert.match(d.body, /## Done when\n\n- \[x\] footer\.html exists\n- \[ \] linked from index/);
+  assert.match(d.body, /branch `foreman\/add-a-footer-ab12` from `main` · spend \$0\.42/);
+});