awayteam 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Awayteam Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,130 @@
+# awayteam
+
+**Run a fleet of coding agents overnight. Wake up to a report.**
+
+awayteam turns one machine into an overnight ops desk for AI coding agents: it works
+through a plain-file task board, gives every task its own git worktree and branch,
+survives rate-limit errors with backoff, and hands you a morning report of branches
+ready for review. It uses the agent CLIs you already pay for — **Claude Code, Codex CLI**
+— so overnight runs cost no more than your existing subscription.
+
+Nothing is ever merged for you. Agents work on branches; you review.
+
+```console
+$ awayteam up --jobs 3 --window 8h
+[23:00:14] w1 claimed 001-fix-login-crash.md
+[23:00:15] w2 claimed 002-slug-dashes.md
+[23:00:16] w3 claimed 003-words-empty.md
+[23:01:10] w1 done    001-fix-login-crash.md (attempt 1) -> away/001-fix-login-crash
+[23:04:47] w2 retry   002-slug-dashes.md attempt 2 next, backoff 4m   # rate limit, handled
+...
+run complete - board boards/jobs (3 workers, claude) - done 6, failed 1, abandoned 0, queued 0
+report: .awayteam/reports/2026-08-31.md
+```
+
+## Quick start
+
+```console
+$ cd your-repo
+$ npm install -g awayteam
+$ awayteam init
+$ awayteam up
+$ awayteam report
+```
+
+`init` detects which agent CLIs are installed, writes `awayteam.config.json`, and seeds a
+demo board you can watch end-to-end before trusting it with real work.
+
+## How it works
+
+**The board is a folder.** Tasks are markdown files; directories are the state:
+
+```
+boards/jobs/
+  todo/           <-> agents pick from here
+  in-progress/
+  done/
+  failed/
+```
+
+```markdown
+---
+status: todo
+---
+slugify("a   b") currently produces "a---b". Fix lib/slug.js so repeated
+separators collapse to one dash. Add tests. Run `npm test`, then commit.
+
+Commit message: 001: collapse repeated dashes in slugify
+```
+
+Claiming a task is an atomic rename, so any number of parallel workers race the same
+board safely — no locks, no database, and the board itself is diffable in git.
+
+**Every task is isolated.** `awayteam` gives each worker its own git worktree and a
+branch like `away/001-fix-login-crash`. A crashed or misbehaved agent cannot touch
+your working tree or anyone else's work. There is no auto-merge and no remote push.
+
+**The report is generated from git.** Commits, diffstats, the exact review command —
+per task, plus the honest failures with their stderr.
+
+```markdown
+### 001-hello
+branch `away/001-hello` - 1 attempt(s) - Done.
+- `hello.txt` created with content `awayteam was here`
+- Committed as `d97db6f awayteam smoke task` on `away/001-hello`
+
+review: `git log -p fe61cf552..away/001-hello`
+```
+
+## Overnight recipe
+
+Run it from a terminal that stays open (tmux), or schedule it:
+
+```cron
+# launchd/cron: nightly at 23:00, report waiting at 07:00
+0 23 * * * cd /srv/myapi && /usr/local/bin/awayteam up --window 7h >> .awayteam/up.log 2>&1
+```
+
+Cheap VMs work the same way — see the Ops Pack for ready-made cloud + notification setups.
+
+## Safety model
+
+- Agents are clones of your own CLI logins. No servers, no API keys stored by awayteam.
+- Permission bypass is **off by default**; for overnight runs you either enable
+  `bypass_permissions` per repo or pre-approve allowed commands in your agent CLI's
+  own settings (recommended — e.g. Claude Code's `settings.json` allowlist).
+- Work happens in throwaway worktrees on `away/*` branches. Merge only what you review.
+- Rate limits: detected, chunked, retried with exponential backoff — so your fixed
+  subscription does the most work per dollar instead of dying at 2 AM.
+
+## Commands
+
+| command | what it does |
+|---|---|
+| `awayteam init` | detect agent CLIs, write config, seed demo board |
+| `awayteam up` | run the fleet (until board is empty or the window ends) |
+| `awayteam status` | live view of the fleet from another terminal |
+| `awayteam stop [--now]` | finish running tasks, then stop / kill now |
+| `awayteam report` | render the latest morning report |
+
+Flags: `--jobs N`, `--board DIR`, `--window 8h`, `--adapter claude|codex|stub`.
+
+Notify hook: `notify_command` in `awayteam.config.json` receives run events as JSON on
+stdin — point it at Slack, Telegram, or mail.
+
+## Writing your own adapter
+
+An adapter is ~20 lines: `{ cmdFor(task, cfg), parse(result) }`. See `lib/adapters/`
+(`claude.js` and `codex.js` ship in the box).
+
+## The Ops Pack (paid)
+
+The free core above is the whole engine, unlimited. The Ops Pack adds curated job
+boards and the ops glue: bug-sweep, test-gap, doc-sync and content-machine packs,
+cloud VM provisioning recipes (Ubuntu, launchd/cron), notification integrations
+(Slack/Telegram/mail), and the Operator's Runbook. [Ops Pack](https://gumroad.com/l/awayteam)
+or [done-for-you setup](https://gumroad.com/l/awayteam-dfy).
+
+## License
+
+MIT.

package/bin/awayteam.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+const { main } = require('../lib/cli');
+
+main(process.argv.slice(2))
+  .then((code) => {
+    process.exitCode = typeof code === 'number' ? code : 0;
+  })
+  .catch((err) => {
+    console.error(err && err.message ? `awayteam: ${err.message}` : String(err));
+    process.exit(1);
+  });

package/lib/adapters/claude.js

@@ -0,0 +1,35 @@
+// claude adapter — runs `claude -p` headless. The prompt (task body) goes in
+// over stdin (task bodies can be long), results come back as one JSON line.
+//
+// Permission modes: `claude -p` headless sessions cannot ask interactive
+// permission questions — without pre-approved permissions or the bypass flag
+// the agent will stall or refuse. awayteam default is bypass OFF; see README
+// "Safety" for the trade-offs before switching it on overnight.
+function cmdFor(task, cfg) {
+  const args = ['-p', '--output-format', 'json'];
+  if (cfg.bypass_permissions) args.unshift('--dangerously-skip-permissions');
+  for (const a of cfg.claude_args || []) args.push(a);
+  return { cmd: ['claude', ...args], stdin: task.body + '\n' };
+}
+
+// `claude -p --output-format json` emits one JSON object per line; the final
+// line carries the run result. Scan backwards for the last parseable one.
+function parse({ exitCode, stdout }) {
+  const lines = stdout.trim().split('\n').filter(Boolean);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    try {
+      const obj = JSON.parse(lines[i]);
+      if (typeof obj.result === 'string' || typeof obj.is_error === 'boolean') {
+        return {
+          ok: !obj.is_error && exitCode === 0,
+          summary: String(obj.result || '').trim().slice(0, 400),
+        };
+      }
+    } catch (err) {
+      // not JSON — keep scanning backwards
+    }
+  }
+  return { ok: exitCode === 0, summary: stdout.trim().slice(0, 400) || '(no output)' };
+}
+
+module.exports = { name: 'claude', cmdFor, parse };

package/lib/adapters/codex.js

@@ -0,0 +1,21 @@
+// codex adapter — runs `codex exec` headless. exec mode never asks for
+// approval; the sandbox flag decides how much it may touch. workspace-write
+// is the minimum needed to edit files + commit inside the task worktree.
+function cmdFor(task, cfg) {
+  const args = ['exec'];
+  if (cfg.bypass_permissions) args.push('--dangerously-bypass-approvals-and-sandbox');
+  else args.push('-s', 'workspace-write');
+  for (const a of cfg.codex_args || []) args.push(a);
+  args.push(task.body);
+  return { cmd: ['codex', ...args], stdin: null };
+}
+
+// exec prints a human-readable session log; the last non-empty line is the
+// closest thing to a result. Exit code is the authoritative verdict.
+function parse({ exitCode, stdout }) {
+  const lines = stdout.trim().split('\n').filter(Boolean);
+  const summary = (lines.length ? lines[lines.length - 1] : '').trim().slice(0, 200);
+  return { ok: exitCode === 0, summary: summary || '(no output)' };
+}
+
+module.exports = { name: 'codex', cmdFor, parse };

package/lib/adapters/index.js

@@ -0,0 +1,18 @@
+// adapter registry. An adapter is { name, cmdFor(task, cfg), parse(result) }.
+// cmdFor returns { cmd: [argv0, ...args], stdin?, cwdHint? } — supervisor
+// always runs it with cwd set to the task's worktree.
+const stub = require('./stub');
+const claude = require('./claude');
+const codex = require('./codex');
+
+const REGISTRY = { stub, claude, codex };
+
+function getAdapter(name) {
+  const a = REGISTRY[name];
+  if (!a) {
+    throw new Error(`Unknown adapter "${name}" — available: ${Object.keys(REGISTRY).join(', ')}`);
+  }
+  return a;
+}
+
+module.exports = { REGISTRY, getAdapter };

package/lib/adapters/stub-agent.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+// stub-agent.js — stands in for a real agent CLI in tests and dry runs.
+// Behavior is steered by directives embedded in the task file (argv[2]):
+//   <!-- stub:fail -->      print a plain error and exit 1
+//   <!-- stub:ratelimit --> print a usage-limit error and exit 1 (retryable)
+// On success it simulates real work: writes a file into the worktree and
+// commits it, so the report has receipts to show.
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const GIT_STUB_ENV = {
+  GIT_AUTHOR_NAME: 'Awayteam Stub',
+  GIT_AUTHOR_EMAIL: 'stub@awayteam.dev',
+  GIT_COMMITTER_NAME: 'Awayteam Stub',
+  GIT_COMMITTER_EMAIL: 'stub@awayteam.dev',
+};
+
+const taskPath = process.argv[2];
+const body = fs.readFileSync(taskPath, 'utf8');
+const slug = path.basename(taskPath, '.md');
+const cwd = process.cwd(); // a awayteam worktree
+
+if (/<!--\s*stub:ratelimit\s*-->/.test(body)) {
+  console.error('error: usage limit reached, try again later');
+  process.exit(1);
+}
+
+if (/<!--\s*stub:fail\s*-->/.test(body)) {
+  console.error('stub: deliberate failure');
+  process.exit(1);
+}
+
+const file = `stub-${slug}.txt`;
+fs.writeFileSync(path.join(cwd, file), `done by awayteam stub for ${slug}\n`);
+execFileSync('git', ['add', '-A'], { cwd });
+execFileSync('git', ['commit', '-m', `stub: ${slug}`], { cwd, env: { ...process.env, ...GIT_STUB_ENV } });
+console.log(`AWAYTEAM_RESULT ok wrote ${file}`);

package/lib/adapters/stub.js

@@ -0,0 +1,23 @@
+// stub adapter — a deterministic fake agent CLI. It exists so the whole
+// fleet loop can be tested and demoed without touching a real provider.
+// The "agent" is stub-agent.js; failure modes are driven by directives
+// embedded in the task body.
+const path = require('path');
+
+const STUB_AGENT_PATH = path.join(__dirname, 'stub-agent.js');
+
+function cmdFor(task, cfg) {
+  return {
+    cmd: [process.execPath, STUB_AGENT_PATH, task.path],
+    stdin: null,
+  };
+}
+
+// stub-agent prints a final `AWAYTEAM_RESULT <status>` line.
+function parse({ exitCode, stdout }) {
+  const m = stdout.match(/AWAYTEAM_RESULT\s+(\w+)/);
+  const outcome = m ? m[1] : exitCode === 0 ? 'ok' : 'failed';
+  return { ok: outcome === 'ok', summary: `stub: ${outcome}` };
+}
+
+module.exports = { name: 'stub', cmdFor, parse };

package/lib/board.js

@@ -0,0 +1,140 @@
+// board.js — the task board state machine.
+//
+// Board layout (one board per job pack):
+//   boards/<pack>/todo/*.md
+//   boards/<pack>/in-progress/*.md
+//   boards/<pack>/done/*.md
+//   boards/<pack>/failed/*.md
+//
+// Tasks are plain markdown files with `---key: value---` front matter; the
+// SUBDIRECTORY IS THE STATUS. Claiming is an atomic rename from todo/ into
+// in-progress/, so parallel workers race safely: the loser of a claim gets
+// ENOENT on its source file and simply tries the next one. No locks, no DB.
+const fs = require('fs');
+const path = require('path');
+
+const STATUSES = ['todo', 'in-progress', 'done', 'failed'];
+
+// --- task file format ---------------------------------------------------------
+
+function parseTask(text) {
+  const meta = {};
+  const lines = text.split('\n');
+  let i = 0;
+  if ((lines[0] || '').trim() !== '---') return { meta, body: text.trim() };
+  for (i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === '---') { i++; break; }
+    const m = lines[i].match(/^([\w-]+):\s*(.*)$/);
+    if (m) meta[m[1]] = m[2];
+  }
+  return { meta, body: lines.slice(i).join('\n').trim() };
+}
+
+function renderTask({ meta, body }) {
+  const fm = Object.entries(meta).map(([k, v]) => `${k}: ${v}`);
+  return ['---', ...fm, '---', '', body, ''].join('\n');
+}
+
+function loadTask(filePath) {
+  return parseTask(fs.readFileSync(filePath, 'utf8'));
+}
+
+// tmp + atomic rename so a reader never sees a half-written front matter.
+function writeTask(filePath, task) {
+  const tmp = filePath + '.tmp';
+  fs.writeFileSync(tmp, renderTask(task));
+  fs.renameSync(tmp, filePath);
+}
+
+// --- board operations ---------------------------------------------------------
+
+function statusDir(boardDir, status) {
+  const d = path.join(boardDir, status);
+  fs.mkdirSync(d, { recursive: true });
+  return d;
+}
+
+function listTasks(boardDir, status) {
+  try {
+    return fs.readdirSync(path.join(boardDir, status)).filter((f) => f.endsWith('.md')).sort();
+  } catch (err) {
+    if (err.code === 'ENOENT') return [];
+    throw err;
+  }
+}
+
+function boardCounts(boardDir) {
+  const counts = {};
+  for (const s of STATUSES) counts[s] = listTasks(boardDir, s).length;
+  return counts;
+}
+
+function slugOf(fileName) {
+  return fileName.replace(/\.md$/, '');
+}
+
+// Returns the claimed task ({ name, path, slug, meta, body }) or null.
+function claimNext(boardDir, workerId, stamp) {
+  const todo = statusDir(boardDir, 'todo');
+  const names = listTasks(boardDir, 'todo');
+  for (const name of names) {
+    const dst = path.join(statusDir(boardDir, 'in-progress'), name);
+    try {
+      fs.renameSync(path.join(todo, name), dst);
+    } catch (err) {
+      if (err.code === 'ENOENT') continue; // lost the race — next task
+      throw err;
+    }
+    const task = loadTask(dst);
+    task.meta.worker = workerId;
+    task.meta.claimed_at = stamp || new Date().toISOString();
+    if (!task.meta.attempts) task.meta.attempts = '0';
+    writeTask(dst, task);
+    return {
+      pack: path.basename(boardDir),
+      name,
+      path: dst,
+      slug: slugOf(name),
+      meta: task.meta,
+      body: task.body,
+    };
+  }
+  return null;
+}
+
+// Moves a task to another status dir, patching front matter in place first.
+function setTaskStatus(task, to, patch = {}) {
+  const boardDir = path.dirname(path.dirname(task.path));
+  const from = path.basename(path.dirname(task.path));
+  Object.assign(task.meta, { status: to, updated_at: new Date().toISOString() }, patch);
+  writeTask(task.path, task);
+  if (from !== to) {
+    const dst = path.join(statusDir(boardDir, to), path.basename(task.path));
+    fs.renameSync(task.path, dst);
+    task.path = dst;
+  }
+  return task;
+}
+
+function seedBoard(boardDir, tasks) {
+  for (const s of STATUSES) statusDir(boardDir, s);
+  for (const t of tasks) {
+    const file = path.join(statusDir(boardDir, 'todo'), t.name);
+    if (!fs.existsSync(file)) writeTask(file, { meta: { status: 'todo', attempts: 0 }, body: t.body });
+  }
+  return boardDir;
+}
+
+module.exports = {
+  STATUSES,
+  parseTask,
+  renderTask,
+  loadTask,
+  writeTask,
+  listTasks,
+  boardCounts,
+  claimNext,
+  setTaskStatus,
+  seedBoard,
+  slugOf,
+};

package/lib/cli.js

@@ -0,0 +1,173 @@
+// cli.js — command dispatch and receipt printing. bin/awayteam.js is a
+// two-liner; everything user-visible lives here.
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const config = require('./config');
+const board = require('./board');
+const wt = require('./worktree');
+const { runFleet } = require('./supervisor');
+const { buildReport } = require('./report');
+const { showStatus } = require('./status');
+const { stopFleet } = require('./stopctl');
+
+const HELP = `awayteam - run overnight agent fleets, wake up to a report.
+
+  awayteam init             detect agent CLIs, write awayteam.config.json + demo board
+  awayteam up               run the fleet (until the board is empty or the window ends)
+      --jobs N              parallel workers            (config default: 2)
+      --board DIR           task board directory       (config default: boards/demo)
+      --window 8h           stop starting new work after this long
+      --adapter NAME        override adapter for this run
+  awayteam status           live view of the fleet (from another terminal)
+  awayteam stop [--now]     finish running tasks then stop / kill immediately
+  awayteam report           render the latest morning report
+
+Adapters: claude, codex, stub (simulated - for tests and dry runs).
+Isolation: every task runs in its own git worktree + branch. Nothing is merged for you.
+Safety: agent permission bypass is OFF by default. See README before enabling overnight.`;
+
+const stamp = () => new Date().toISOString().slice(11, 19);
+
+function parseWindow(s) {
+  const m = /^(\d+)(h|m|s)$/.exec(s);
+  if (!m) throw new Error(`bad --window "${s}" — use e.g. 8h, 90m, 45s`);
+  const mult = { h: 1, m: 1 / 60, s: 1 / 3600 };
+  return parseInt(m[1], 10) * mult[m[2]];
+}
+
+function parseFlags(rest) {
+  const out = {};
+  const need = (i) => {
+    const v = rest[i + 1];
+    if (v === undefined) throw new Error(`flag ${rest[i]} needs a value`);
+    return v;
+  };
+  for (let i = 0; i < rest.length; i++) {
+    const k = rest[i];
+    const need = () => {
+      const v = rest[i + 1];
+      if (v === undefined) throw new Error(`flag ${k} needs a value`);
+      i += 1; // consume the value
+      return v;
+    };
+    if (k === '--jobs') out.jobs = parseInt(need(), 10);
+    else if (k === '--window') out.windowHours = parseWindow(need());
+    else if (k === '--board') out.board = need();
+    else if (k === '--adapter') out.adapter = need();
+    else throw new Error(`unknown flag: ${k}`);
+  }
+  return out;
+}
+
+const DEMO_TASK = {
+  name: '001-demo-hello.md',
+  body: [
+    'Create a file named `demo.txt` containing the line "hello from awayteam",',
+    'then commit the file.',
+    '',
+    'This task exists so you can watch a full run end-to-end (claim -> worktree',
+    '-> commit -> report) before pointing awayteam at your real backlog.',
+  ].join('\n'),
+};
+
+function cmdInit() {
+  const repoRoot = process.cwd();
+  wt.assertRepo(repoRoot);
+
+  const probe = (bin, args) => {
+    try {
+      execFileSync(bin, args, { timeout: 5000, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+      return true;
+    } catch (err) {
+      return false;
+    }
+  };
+
+  let adapter = null;
+  if (probe('claude', ['--version'])) adapter = 'claude';
+  else if (probe('codex', ['--version'])) adapter = 'codex';
+  const cfgFile = config.writeConfig(repoRoot, adapter ? { adapter } : {});
+  const boardDir = board.seedBoard(path.join(repoRoot, config.DEFAULTS.board), [DEMO_TASK]);
+
+  console.log(`config: ${cfgFile} (adapter: ${adapter || 'stub'})`);
+  console.log(`board:  ${path.relative(repoRoot, boardDir)} (1 demo task)`);
+  console.log(`repo:   ${repoRoot}`);
+  if (!adapter) {
+    console.log('');
+    console.log('No supported agent CLI found on PATH (looked for: claude).');
+    console.log('Falling back to the stub adapter — the full loop works, the agents are simulated.');
+  }
+  console.log('');
+  console.log('next:');
+  console.log('  awayteam up          run the fleet now');
+  console.log('  awayteam status      watch from another terminal');
+  console.log('  awayteam report      read the morning report');
+  return 0;
+}
+
+async function cmdUp(flags) {
+  const repoRoot = process.cwd();
+  const cfg = config.loadConfig(repoRoot);
+
+  const run = await runFleet(repoRoot, cfg, {
+    ...flags,
+    onEvent(kind, e) {
+      const t = `[${stamp()}] ${e.worker} `;
+      if (kind === 'claimed') console.log(`${t}claimed ${e.task}`);
+      else if (kind === 'done') console.log(`${t}done    ${e.task} (attempt ${e.attempts}) -> ${e.branch}`);
+      else if (kind === 'backoff') console.log(`${t}retry   ${e.task} attempt ${e.attempts + 1} next, backoff ${Math.round(e.delay_ms / 60e3) || e.delay_ms + 's'}`);
+      else if (kind === 'failed') console.log(`${t}FAIL    ${e.task} (${e.reason}, exit ${e.exit_code})`);
+      else if (kind === 'abandoned') console.log(`${t}stopped ${e.task} — left in-progress`);
+      else console.log(`${t}${kind} ${e.task || ''}`);
+    },
+  });
+
+  const r = buildReport(repoRoot);
+  const { done, failed, abandoned, queued } = r.summary;
+  console.log('');
+  console.log(`run complete - ${started(run)} - done ${done}, failed ${failed}, abandoned ${abandoned}, queued ${queued}`);
+  console.log(`report: ${path.relative(repoRoot, r.file)}`);
+  return 0;
+}
+
+function started(run) {
+  return `board ${run.board} (${run.jobs} workers, ${run.adapter})`;
+}
+
+function cmdReport() {
+  const repoRoot = process.cwd();
+  const r = buildReport(repoRoot);
+  console.log(`report: ${path.relative(repoRoot, r.file)}`);
+  console.log('');
+  console.log(r.markdown);
+  return 0;
+}
+
+async function main(argv) {
+  const [cmd, ...rest] = argv;
+  switch (cmd === undefined ? 'help' : cmd) {
+    case '-h':
+    case '--help':
+    case 'help':
+      console.log(HELP);
+      return 0;
+    case 'init':
+      return cmdInit();
+    case 'up':
+      return cmdUp(parseFlags(rest));
+    case 'status':
+      showStatus(process.cwd());
+      return 0;
+    case 'stop':
+      stopFleet(process.cwd(), { now: rest.includes('--now') });
+      return 0;
+    case 'report':
+      return cmdReport();
+    default:
+      throw new Error(`unknown command: ${cmd}\n\n${HELP}`);
+  }
+}
+
+module.exports = { main, parseFlags, parseWindow };

package/lib/config.js

@@ -0,0 +1,43 @@
+// config.js — awayteam.config.json loading. One flat object, sane defaults,
+// explicit on disk so users can diff/inspect exactly what a run used.
+const fs = require('fs');
+const path = require('path');
+
+const FILE = 'awayteam.config.json';
+
+const DEFAULTS = {
+  adapter: 'stub', // stub | claude | codex
+  jobs: 2,
+  board: 'boards/demo',
+  window_hours: 8, // stop starting NEW work after this many hours
+  max_attempts: 3, // executions per task before it is marked failed
+  backoff_base_seconds: 120, // rate-limit backoff base: 2m, 4m, 8m ...
+  task_timeout_minutes: 120, // kill an agent process stuck this long (0 = off)
+  bypass_permissions: false, // god mode for the agent CLI; off by default, on purpose
+  notify_command: '', // shell command; run events arrive as JSON on stdin
+  claude_args: [], // extra args passed to `claude`
+  codex_args: [],
+};
+
+function configPath(repoRoot) {
+  return path.join(repoRoot, FILE);
+}
+
+function loadConfig(repoRoot) {
+  const p = configPath(repoRoot);
+  if (!fs.existsSync(p)) {
+    throw new Error(`No ${FILE} in ${repoRoot} — run \`awayteam init\` first.`);
+  }
+  const raw = JSON.parse(fs.readFileSync(p, 'utf8'));
+  return { ...DEFAULTS, ...raw };
+}
+
+function writeConfig(repoRoot, patch) {
+  const p = configPath(repoRoot);
+  const base = fs.existsSync(p) ? JSON.parse(fs.readFileSync(p, 'utf8')) : {};
+  const merged = { ...DEFAULTS, ...base, ...patch };
+  fs.writeFileSync(p, JSON.stringify(merged, null, 2) + '\n');
+  return p;
+}
+
+module.exports = { DEFAULTS, FILE, configPath, loadConfig, writeConfig };

package/lib/notify.js

@@ -0,0 +1,20 @@
+// notify.js — fire-and-forget notification hook. Config points at any shell
+// command; run events arrive as JSON on stdin. Slack webhook, Telegram curl,
+// sendmail — whatever the operator wants, awayteam collects nothing.
+const { spawn } = require('child_process');
+
+function callNotify(cfg, payload) {
+  const cmd = ((cfg && cfg.notify_command) || '').trim();
+  if (!cmd) return false;
+  try {
+    const child = spawn('sh', ['-c', cmd], { stdio: ['pipe', 'ignore', 'ignore'], detached: true });
+    child.stdin.end(JSON.stringify(payload) + '\n');
+    child.unref();
+    return true;
+  } catch (err) {
+    console.error(`[notify] hook failed: ${err.message}`);
+    return false;
+  }
+}
+
+module.exports = { callNotify };

package/lib/proc.js

@@ -0,0 +1,57 @@
+// proc.js — async child process helper. The supervisor runs N workers as
+// cooperative async loops in one process, so agent CLIs must be spawned
+// (not spawnSync) or the whole fleet would serialize.
+const { spawn } = require('child_process');
+
+// resolves { exitCode, stdout, stderr, pid, timedOut }
+function runCapture(cmd, { cwd, input, env, timeoutMs } = {}) {
+  return new Promise((resolve) => {
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    let timedOut = false;
+
+    const child = spawn(cmd[0], cmd.slice(1), {
+      cwd,
+      env: env || process.env,
+      detached: true, // own process group, so a timed-out agent dies with its children
+    });
+
+    // Cap captured output — an agent that chatters should not OOM us.
+    const append = (want) => (d) => {
+      if (want === 'out' && stdout.length < 2e6) stdout += d;
+      if (want === 'err' && stderr.length < 2e6) {
+        stderr += d;
+        if (stderr.length >= 2e6) stderr += '\n... (truncated)';
+      }
+    };
+
+    child.stdout.on('data', append('out'));
+    child.stderr.on('data', append('err'));
+
+    const timer = timeoutMs
+      ? setTimeout(() => {
+          timedOut = true;
+          try { process.kill(-child.pid, 'SIGTERM'); } catch (err) { child.kill('SIGTERM'); }
+        }, timeoutMs)
+      : null;
+
+    const finish = (exitCode) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      resolve({ exitCode, stdout, stderr, pid: child.pid, timedOut });
+    };
+
+    child.on('error', (err) => {
+      stderr += `\nspawn error: ${err.message}`;
+      finish(127);
+    });
+    child.on('close', (code) => finish(code ?? (timedOut ? 124 : 1)));
+
+    if (input != null) child.stdin.write(input);
+    child.stdin.end();
+  });
+}
+
+module.exports = { runCapture };

package/lib/ratelimit.js

@@ -0,0 +1,21 @@
+// ratelimit.js — classify why an agent CLI exited nonzero. Rate limits are
+// retryable with backoff (that is the whole overnight game); everything else
+// fails immediately so the morning report can show the stderr.
+const RATE_LIMIT_PATTERNS = [
+  /rate[- ]?limit/i,
+  /usage[- ]?limit/i,
+  /too many requests/i,
+  /\b429\b/,
+  /overloaded/i,
+  /quota/i,
+  /exhausted/i,
+];
+
+function classifyExit({ exitCode, stdout, stderr }) {
+  if (exitCode === 0 && !/\b(is_error":\s*true)\b/.test(stdout)) return 'success';
+  const text = `${stdout}\n${stderr}`;
+  if (RATE_LIMIT_PATTERNS.some((re) => re.test(text))) return 'rate-limit';
+  return 'error';
+}
+
+module.exports = { classifyExit, RATE_LIMIT_PATTERNS };

package/lib/report.js

@@ -0,0 +1,123 @@
+// report.js — the morning report: what the fleet did while you slept.
+// Board outcomes first, then per-branch receipts (commits, diffstat, review
+// command) pulled from git history so the report survives worktree cleanup.
+const fs = require('fs');
+const path = require('path');
+const boardMod = require('./board');
+const wt = require('./worktree');
+
+function reportsDir(repoRoot) {
+  return path.join(repoRoot, '.awayteam', 'reports');
+}
+
+function latestRunFile(repoRoot) {
+  const dir = path.join(repoRoot, '.awayteam', 'runs');
+  const files = fs.existsSync(dir) ? fs.readdirSync(dir).filter((f) => f.endsWith('.json')).sort() : [];
+  if (!files.length) throw new Error('No awayteam runs recorded yet — run `awayteam up` first.');
+  return path.join(dir, files[files.length - 1]);
+}
+
+function buildReport(repoRoot, { runFile } = {}) {
+  const file = runFile || latestRunFile(repoRoot);
+  const run = JSON.parse(fs.readFileSync(file, 'utf8'));
+  const boardDir = path.resolve(repoRoot, run.board);
+  const done = run.results.filter((r) => r.status === 'done');
+  const failed = run.results.filter((r) => r.status.startsWith('failed'));
+  const abandoned = run.results.filter((r) => r.status === 'abandoned');
+  const queued = boardMod.listTasks(boardDir, 'todo');
+  const held = boardMod.listTasks(boardDir, 'in-progress');
+
+  const L = [];
+  L.push(`# Awayteam report — ${run.ended_at.slice(0, 10)}`);
+  L.push('');
+  L.push(`- window: \`${run.started_at}\` -> \`${run.ended_at}\``);
+  L.push(`- workers: ${run.jobs} - adapter: \`${run.adapter}\` - board: \`${run.board}\``);
+  L.push('');
+  L.push('## Outcomes');
+  L.push('');
+  L.push('| task | status | branch | attempts | exit |');
+  L.push('|---|---|---|---|---|');
+  for (const r of run.results) {
+    L.push(`| ${r.task} | ${r.status} | \`${r.branch}\` | ${r.attempts} | ${r.exit_code ?? '-'} |`);
+  }
+  for (const t of held) L.push(`| ${t} | in-progress | - | - | - |`);
+  if (!run.results.length && !queued.length && !held.length) L.push('| (no work found) | - | - | - | - |');
+  L.push('');
+
+  if (done.length) {
+    L.push('## Ready for review');
+    for (const r of done) {
+      L.push('');
+      L.push(`### ${r.task.replace(/\.md$/, '')}`);
+      L.push('');
+      L.push(`branch \`${r.branch}\` - ${r.attempts} attempt(s)${r.summary ? ` - ${r.summary}` : ''}`);
+      const log = wt.commitLog(repoRoot, run.start_head, r.branch).trim();
+      if (log) {
+        L.push('');
+        L.push('```');
+        L.push(log);
+        L.push('```');
+      }
+      const stat = wt.diffStat(repoRoot, run.start_head, r.branch).trim();
+      if (stat) {
+        L.push('');
+        L.push('```');
+        L.push(stat);
+        L.push('```');
+      }
+      L.push('');
+      L.push(`review: \`git log -p ${run.start_head.slice(0, 9)}..${r.branch}\``);
+    }
+  }
+
+  if (failed.length) {
+    L.push('');
+    L.push('## Failed');
+    for (const r of failed) {
+      L.push('');
+      L.push(`### ${r.task.replace(/\.md$/, '')}`);
+      L.push('');
+      L.push(`branch \`${r.branch}\` - ${r.attempts} attempt(s) - exit ${r.exit_code ?? '?'}`);
+      if (r.error) {
+        L.push('');
+        L.push('```');
+        L.push(r.error);
+        L.push('```');
+      }
+      const stat = wt.diffStat(repoRoot, run.start_head, r.branch).trim();
+      if (stat) L.push('partial work exists on the branch - inspect before retrying.');
+    }
+  }
+
+  if (abandoned.length) {
+    L.push('');
+    L.push('## Stopped mid-task (left in-progress for the next run)');
+    for (const r of abandoned) L.push(`- ${r.task}`);
+  }
+
+  if (queued.length) {
+    L.push('');
+    L.push('## Still queued');
+    L.push('');
+    for (const t of queued) L.push(`- ${t}`);
+  }
+
+  const md = L.join('\n') + '\n';
+  const out = path.join(reportsDir(repoRoot), `${run.ended_at.slice(0, 10)}.md`);
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  fs.writeFileSync(out + '.tmp', md);
+  fs.renameSync(out + '.tmp', out);
+  return {
+    markdown: md,
+    file: out,
+    summary: {
+      done: done.length,
+      failed: failed.length,
+      abandoned: abandoned.length,
+      queued: queued.length,
+      held: held.length,
+    },
+  };
+}
+
+module.exports = { buildReport, latestRunFile };

package/lib/status.js

@@ -0,0 +1,52 @@
+// status.js — live view of a run, read from the .awayteam state files.
+// Works from any other terminal while `awayteam up` is running.
+const fs = require('fs');
+const path = require('path');
+const boardMod = require('./board');
+
+const fleetPath = (repoRoot, ...p) => path.join(repoRoot, '.awayteam', ...p);
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (err) {
+    return null;
+  }
+}
+
+function showStatus(repoRoot) {
+  const fleetFile = fleetPath(repoRoot, 'fleet.json');
+  const fleet = readJson(fleetFile);
+  if (!fleet) {
+    console.log('No active fleet (no .awayteam/fleet.json) — run `awayteam up` or `awayteam report`.');
+    return;
+  }
+
+  const stopped = fs.existsSync(fleetPath(repoRoot, 'stop.flag'));
+  const hours = ((Date.now() - Date.parse(fleet.started_at)) / 3600e3).toFixed(2);
+  console.log(`fleet: running ${hours}h (pid ${fleet.pid}) - adapter: ${fleet.adapter} - board: ${fleet.board}`);
+  console.log(stopped ? 'stop flag set — no new tasks will start' : '');
+
+  const wdir = fleetPath(repoRoot, 'workers');
+  const files = fs.existsSync(wdir) ? fs.readdirSync(wdir).filter((f) => f.endsWith('.json')).sort() : [];
+  if (!files.length) console.log('workers: (none recorded)');
+  for (const f of files) {
+    const w = readJson(path.join(wdir, f));
+    if (!w) continue;
+    const bits = [w.phase];
+    if (w.task) bits.push(`${w.task} (attempt ${w.attempts ?? '?'})`);
+    if (w.phase === 'backoff') bits.push(`resume in ${Math.round(w.resume_in_ms / 600e3) / 10}m`);
+    bits.push(w.ts);
+    console.log(`  ${w.id}  ${bits.join('  ')}`);
+  }
+
+  try {
+    const counts = boardMod.boardCounts(path.resolve(repoRoot, fleet.board));
+    const parts = boardMod.STATUSES.map((s) => `${s}: ${counts[s]}`).join(' - ');
+    console.log(`board: ${parts}`);
+  } catch (err) {
+    console.log(`board: unreadable (${err.message})`);
+  }
+}
+
+module.exports = { showStatus };

package/lib/stopctl.js

@@ -0,0 +1,46 @@
+// stopctl.js — graceful stop: drop a flag that workers honor at the task
+// boundary. `--now` additionally kills the fleet process and the agent
+// processes it spawned (recorded as agent_pid in the worker state files).
+const fs = require('fs');
+const path = require('path');
+
+const fleetPath = (repoRoot, ...p) => path.join(repoRoot, '.awayteam', ...p);
+
+function stopFleet(repoRoot, { now = false } = {}) {
+  const file = fleetPath(repoRoot, 'fleet.json');
+  if (!fs.existsSync(file)) {
+    throw new Error('No active fleet (no .awayteam/fleet.json).');
+  }
+  const fleet = JSON.parse(fs.readFileSync(file, 'utf8'));
+
+  fs.writeFileSync(fleetPath(repoRoot, 'stop.flag'), new Date().toISOString());
+  if (!now) {
+    console.log('stop flag set - workers finish their current task, then exit.');
+    return;
+  }
+
+  // Kill what the workers are running, then the fleet itself.
+  const wdir = fleetPath(repoRoot, 'workers');
+  const files = fs.existsSync(wdir) ? fs.readdirSync(wdir).filter((f) => f.endsWith('.json')) : [];
+  for (const f of files) {
+    try {
+      const w = JSON.parse(fs.readFileSync(path.join(wdir, f), 'utf8'));
+      if (!w.agent_pid) continue;
+      try {
+        process.kill(-w.agent_pid, 'SIGTERM'); // detached spawn => own process group
+        console.log(`killed agent ${w.agent_pid} (${w.task || f})`);
+      } catch (err) {
+        try { process.kill(w.agent_pid, 'SIGTERM'); } catch (e2) { /* already gone */ }
+      }
+    } catch (err) { /* unreadable state file — skip */ }
+  }
+  try {
+    process.kill(fleet.pid, 'SIGTERM');
+    console.log('SIGTERM sent to the fleet process.');
+  } catch (err) {
+    console.log('fleet process already gone.');
+  }
+  console.log('Tasks left in-progress stay in-progress — the next run picks them up.');
+}
+
+module.exports = { stopFleet };

package/lib/supervisor.js

@@ -0,0 +1,183 @@
+// supervisor.js — runs the fleet: N async workers over one shared board.
+// Per task: claim -> worktree -> run adapter -> classify -> done / failed /
+// rate-limit backoff (same task, same worktree, up to max_attempts).
+// Receipts go three places: the task file front matter, the worker state
+// file (.awayteam/workers/), and the run record (.awayteam/runs/).
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const board = require('./board');
+const adapters = require('./adapters');
+const wt = require('./worktree');
+const { runCapture } = require('./proc');
+const { classifyExit } = require('./ratelimit');
+const { callNotify } = require('./notify');
+
+const fleetPath = (repoRoot, ...parts) => path.join(repoRoot, '.awayteam', ...parts);
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+async function runFleet(repoRoot, cfg, overrides = {}) {
+  wt.assertRepo(repoRoot);
+
+  const jobs = Math.max(1, overrides.jobs ?? cfg.jobs);
+  const boardDir = path.resolve(repoRoot, overrides.board ?? cfg.board);
+  const windowHours = overrides.windowHours ?? cfg.window_hours;
+  const maxAttempts = overrides.maxAttempts ?? cfg.max_attempts;
+  const backoffBaseMs = (overrides.backoffBaseSeconds ?? cfg.backoff_base_seconds) * 1000;
+  const backoffCapMs = overrides.backoffCapMs ?? 15 * 60e3;
+  const idleWaitMs = overrides.idleWaitMs ?? 750;
+  const taskTimeoutMs = cfg.task_timeout_minutes > 0 ? cfg.task_timeout_minutes * 60e3 : 0;
+  const adapter = adapters.getAdapter(overrides.adapter ?? cfg.adapter);
+  const onEvent = overrides.onEvent || (() => {});
+
+  fs.mkdirSync(fleetPath(repoRoot, 'runs'), { recursive: true });
+  fs.mkdirSync(fleetPath(repoRoot, 'workers'), { recursive: true });
+  try { fs.unlinkSync(fleetPath(repoRoot, 'stop.flag')); } catch (err) { /* fresh run */ }
+
+  const startedAt = new Date().toISOString();
+  const deadline = Date.now() + windowHours * 3600e3;
+  const startHead = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: repoRoot, encoding: 'utf8' }).trim();
+
+  // fleet state for `status` / `stop`
+  fs.writeFileSync(
+    fleetPath(repoRoot, 'fleet.json'),
+    JSON.stringify(
+      {
+        pid: process.pid,
+        started_at: startedAt,
+        jobs,
+        board: path.relative(repoRoot, boardDir),
+        window_end: new Date(deadline).toISOString(),
+        adapter: adapter.name,
+      },
+      null,
+      2
+    ) + '\n'
+  );
+
+  const stopped = () => fs.existsSync(fleetPath(repoRoot, 'stop.flag'));
+  const results = [];
+
+  async function worker(id) {
+    const wid = `w${id}`;
+    const statePath = fleetPath(repoRoot, 'workers', `${wid}.json`);
+    const setState = (s) =>
+      fs.writeFileSync(statePath, JSON.stringify({ id: wid, ...s, ts: new Date().toISOString() }, null, 2));
+    setState({ phase: 'starting' });
+
+    while (true) {
+      if (stopped()) { setState({ phase: 'stopped' }); return; }
+      if (Date.now() >= deadline) { setState({ phase: 'window-ended' }); return; }
+
+      const task = board.claimNext(boardDir, wid, new Date().toISOString());
+      if (!task) {
+        if (board.boardCounts(boardDir).todo === 0) { setState({ phase: 'board-empty' }); return; }
+        await sleep(idleWaitMs);
+        continue;
+      }
+      const branch = wt.branchFor(task.name.replace(/\.md$/, ''));
+      const workDir = wt.createWorktree(repoRoot, wid, branch);
+      setState({ phase: 'running', task: task.name, branch, attempts: 0 });
+      onEvent('claimed', { worker: wid, task: task.name, attempts: 1 });
+
+      let attempts = 0;
+      let summary = '';
+      let lastExit = null;
+      let finalStatus = 'abandoned'; // stopped/window ended mid-task
+      let lastErr = '';
+
+      while (true) {
+        if (stopped() || Date.now() >= deadline) break; //leave in-progress, report shows it
+        attempts += 1;
+        board.setTaskStatus(task, 'in-progress', { attempts, branch });
+        const inv = adapter.cmdFor(task, cfg);
+        const res = await runCapture(inv.cmd, {
+          cwd: workDir,
+          input: inv.stdin,
+          timeoutMs: taskTimeoutMs,
+          env: { ...process.env, AWAYTEAM_WORKER: wid },
+        });
+        setState({ phase: 'running', task: task.name, branch, attempts, agent_pid: res.pid });
+        lastExit = res.exitCode;
+
+        const cls = classifyExit(res);
+        let parsed = { ok: false, summary: '' };
+        if (cls === 'success') {
+          try { parsed = adapter.parse(res); } catch (err) { parsed = { ok: false, summary: `parse error: ${err.message}` }; }
+          if (parsed.ok) {
+            summary = String(parsed.summary || '').slice(0, 200);
+            board.setTaskStatus(task, 'done', { attempts, branch, exit_code: 0, summary });
+            onEvent('done', { worker: wid, task: task.name, branch, attempts });
+            callNotify(cfg, { event: 'task-done', task: task.name, worker: wid, branch });
+            finalStatus = 'done';
+            break;
+          }
+        }
+
+        if ((cls === 'rate-limit' || parsed.retryable) && attempts < maxAttempts && !stopped() && Date.now() < deadline) {
+          const delay = Math.min(backoffBaseMs * 2 ** (attempts - 1), backoffCapMs);
+          setState({ phase: 'backoff', task: task.name, branch, attempts, resume_in_ms: delay });
+          onEvent('backoff', { worker: wid, task: task.name, attempts, delay_ms: delay });
+          await sleep(delay);
+          continue; // same task, same worktree — the agent can pick up where it left off
+        }
+
+        lastErr = `${res.stderr || res.stdout || 'no output'}`.trim().split('\n').slice(-8).join('\n').slice(0, 800);
+        board.setTaskStatus(task, 'failed', {
+          attempts,
+          branch,
+          exit_code: lastExit ?? 'n/a',
+          error: cls,
+          detail: lastErr.slice(0, 200),
+        });
+        onEvent('failed', { worker: wid, task: task.name, branch, attempts, reason: cls, exit_code: lastExit });
+        callNotify(cfg, { event: 'task-failed', task: task.name, worker: wid, branch, reason: cls });
+        finalStatus = cls === 'rate-limit' ? 'failed-rate-limit' : 'failed';
+        break;
+      }
+
+      if (finalStatus === 'abandoned') {
+        // stopped or window ended mid-task — leave it in-progress for the next run
+        onEvent('abandoned', { worker: wid, task: task.name, branch, attempts });
+      }
+      setState({ phase: 'idle', task: task.name });
+      results.push({
+        task: task.name,
+        pack: task.pack,
+        worker: wid,
+        branch,
+        status: finalStatus,
+        attempts,
+        exit_code: lastExit,
+        summary,
+        error: lastErr,
+      });
+    }
+  }
+
+  const ids = Array.from({ length: jobs }, (_, i) => i + 1);
+  await Promise.all(ids.map((i) => worker(i)));
+
+  const run = {
+    started_at: startedAt,
+    ended_at: new Date().toISOString(),
+    jobs,
+    adapter: adapter.name,
+    board: path.relative(repoRoot, boardDir),
+    start_head: startHead,
+    results,
+  };
+  const runFile = fleetPath(repoRoot, 'runs', `${startedAt.replace(/[:.]/g, '-')}.json`);
+  fs.writeFileSync(runFile, JSON.stringify(run, null, 2) + '\n');
+
+  fs.rmSync(fleetPath(repoRoot, 'workers'), { recursive: true, force: true });
+  try { fs.unlinkSync(fleetPath(repoRoot, 'fleet.json')); } catch (err) { /* already gone */ }
+
+  // Worktree dirs are per-run scratch; the branches (and commits) live on.
+  for (let i = 1; i <= jobs; i++) wt.removeWorktree(repoRoot, wt.wtPath(repoRoot, `w${i}`));
+  try { fs.rmdirSync(fleetPath(repoRoot, 'wt')); } catch (err) { /* still has something — leave it */ }
+
+  return run;
+}
+
+module.exports = { runFleet };

package/lib/worktree.js

@@ -0,0 +1,89 @@
+// worktree.js — git worktree + branch per worker. Every agent works in its
+// own checkout on its own branch; nothing touches the parent tree and nothing
+// merges for you. The morning report hands you the branches, you do the merge.
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+function git(repoRoot, args) {
+  return execFileSync('git', args, { cwd: repoRoot, encoding: 'utf8' });
+}
+
+function assertRepo(repoRoot) {
+  try {
+    git(repoRoot, ['rev-parse', '--is-inside-work-tree']);
+  } catch (err) {
+    throw new Error(`Not a git repository: ${repoRoot}`);
+  }
+  try {
+    git(repoRoot, ['rev-parse', 'HEAD']);
+  } catch (err) {
+    throw new Error('Repository has no commits — commit something first.');
+  }
+}
+
+function wtPath(repoRoot, name) {
+  return path.join(repoRoot, '.awayteam', 'wt', name);
+}
+
+function branchFor(slug) {
+  return `away/${slug}`;
+}
+
+// Creates (or resets) a worktree checked out on `branch`, freshly based on the
+// current HEAD. -B resets the branch if it exists, so retries start clean.
+function createWorktree(repoRoot, name, branch) {
+  const dir = wtPath(repoRoot, name);
+  fs.mkdirSync(path.dirname(dir), { recursive: true });
+  if (fs.existsSync(dir)) {
+    try {
+      git(repoRoot, ['worktree', 'remove', '--force', dir]);
+    } catch (err) {
+      fs.rmSync(dir, { recursive: true, force: true });
+      try { git(repoRoot, ['worktree', 'prune']); } catch (e) { /* prune is best-effort */ }
+    }
+  }
+  git(repoRoot, ['worktree', 'add', '-B', branch, dir, 'HEAD']);
+  return dir;
+}
+
+function removeWorktree(repoRoot, dir) {
+  if (!fs.existsSync(dir)) return;
+  try {
+    git(repoRoot, ['worktree', 'remove', '--force', dir]);
+  } catch (err) {
+    fs.rmSync(dir, { recursive: true, force: true });
+    try { git(repoRoot, ['worktree', 'prune']); } catch (e) { /* best-effort */ }
+  }
+}
+
+function commitLog(repoRoot, base, branch, limit = 10) {
+  try {
+    return git(repoRoot, ['log', '--oneline', `${base}..${branch}`, '-n', String(limit)]);
+  } catch (err) {
+    return '';
+  }
+}
+
+function diffStat(repoRoot, base, branch) {
+  try {
+    return git(repoRoot, ['diff', '--stat', `${base}..${branch}`]);
+  } catch (err) {
+    return '';
+  }
+}
+
+// Branches that survived the run (they exist in the repo even after the
+// worktree dir is gone).
+function listBranches(repoRoot, prefix = 'away/') {
+  try {
+    return git(repoRoot, ['for-each-ref', '--format=%(refname:short)', `refs/heads/${prefix}*`])
+      .split('\n')
+      .map((s) => s.trim())
+      .filter(Boolean);
+  } catch (err) {
+    return [];
+  }
+}
+
+module.exports = { assertRepo, branchFor, commitLog, createWorktree, diffStat, listBranches, removeWorktree, wtPath };

package/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "awayteam",
+  "version": "0.1.0",
+  "description": "Overnight coding-agent ops kit: run N agents on one machine, wake up to a report. Works with the agent CLIs you already have.",
+  "license": "MIT",
+  "bin": { "awayteam": "bin/awayteam.js" },
+  "main": "lib/cli.js",
+  "scripts": { "test": "node --test test/*.test.js" },
+  "engines": { "node": ">=20" },
+  "keywords": ["ai", "agents", "automation", "cli", "overnight", "workflows"],
+  "files": ["bin", "lib", "README.md", "LICENSE"]
+}