@gredescerber/agent-crew 0.0.0-stage → 0.6.0

package/src/commands/worker.js

@@ -0,0 +1,322 @@
+// crew worker — the agent runs the task loop on its own, without a UI.
+// task next → task claim → headless agent in the task worktree → check the issue status → next task.
+// A new agent process per task = a context reset at the phase boundary.
+// Started by a human (agent: false): the agent does not need to be able to spawn other agents via MCP.
+import { spawn as nodeSpawn } from 'node:child_process';
+import { createWriteStream, mkdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { ok, warn, fail, CrewError } from '../core/output.js';
+import { run as exec } from '../core/exec.js';
+import { killTree } from '../core/proc.js';
+import { recordCommand } from '../core/metrics.js';
+import { loadConfig, machineName } from '../core/config.js';
+import { viewIssue, labelValue, TIERS } from '../core/issues.js';
+import { loadAdapter } from './adapters.js';
+import taskCommands from './task.js';
+
+const WAIT_MS = 5 * 60_000;
+const SUCCESS = ['review', 'done'];
+const HANDOFF = ['blocked', 'needs-spec'];
+
+/**
+ * Prompt for a single task. One line, without the characters " & | < > ^ % —
+ * on Windows the argument goes through cmd /c, where a newline and these characters break the command.
+ */
+export function taskPrompt({ id, branch }) {
+  return [
+    `You are an agent of a crew team. Task issue #${id} is already claimed by you: status claimed, branch ${branch ?? `crew/${id}-...`}, the current folder is its worktree.`,
+    `Work only on issue #${id} and only in this folder, strictly following the crew-workflow skill, starting with the Understand step: gh issue view ${id}.`,
+    'Do not call crew task next or crew task claim — the worker will hand out the next task.',
+    `For long work, run crew task heartbeat ${id} about every 30 minutes.`,
+    `Finish with exactly one of: crew pr open — the task goes to review; crew task status ${id} blocked --note with a description; crew task status ${id} needs-spec --note with a question.`,
+    'Then end your work.',
+  ].join(' ');
+}
+
+/** Call a crew command as a function: CrewError → a crew/v1 result, not an exception. */
+async function call(fn, opts) {
+  try {
+    return await fn(opts);
+  } catch (e) {
+    return e instanceof CrewError ? e.toResult() : fail('internal', e.message, { stop_when: 'it keeps happening — tell the human' });
+  }
+}
+
+const fmtDuration = (ms) => {
+  const s = Math.round(ms / 1000);
+  return s >= 60 ? `${Math.floor(s / 60)}m ${s % 60}s` : `${s}s`;
+};
+
+
+/** Run the agent: stdout/stderr → log file, prompt → stdin, killed on timeout. */
+export function spawnAgent(spec, { cwd, env, timeoutMs, logFile }) {
+  return new Promise((done) => {
+    let out = 'ignore';
+    if (logFile) {
+      mkdirSync(dirname(logFile), { recursive: true });
+      out = createWriteStream(logFile);
+    }
+    let child;
+    try {
+      child = nodeSpawn(spec.cmd, spec.args, {
+        cwd,
+        env: { ...process.env, ...env },
+        stdio: [spec.input != null ? 'pipe' : 'ignore', 'pipe', 'pipe'],
+        shell: false,
+        windowsHide: true,
+        detached: process.platform !== 'win32', // own process group → the whole tree can be killed
+      });
+    } catch (e) {
+      done({ code: -1, timedOut: false, error: e.message });
+      return;
+    }
+    if (out !== 'ignore') { child.stdout.pipe(out, { end: false }); child.stderr.pipe(out, { end: false }); }
+    else { child.stdout.resume(); child.stderr.resume(); }
+    if (spec.input != null) child.stdin.end(spec.input);
+    let timedOut = false;
+    const timer = setTimeout(() => { timedOut = true; killTree(child); }, timeoutMs);
+    let settled = false;
+    const finish = (r) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (out !== 'ignore') out.end();
+      done(r);
+    };
+    child.on('error', (e) => finish({ code: -1, timedOut, error: e.message }));
+    child.on('close', (code, signal) => finish({ code: code ?? -1, signal, timedOut }));
+  });
+}
+
+/**
+ * A crew command as a function + recording the event in .crew/metrics.jsonl (as in the CLI and MCP).
+ * Without this, the worker claim/release are invisible in crew metrics and the completion rate of worker agents is wrong.
+ */
+export function recorded(cmd) {
+  return async (o) => {
+    const started = Date.now();
+    try {
+      const result = await cmd.run(o);
+      recordCommand({ command: cmd.name, opts: o, result, started });
+      return result;
+    } catch (e) {
+      const result = e instanceof CrewError ? e.toResult() : fail('internal', e.message);
+      recordCommand({ command: cmd.name, opts: o, result, started });
+      throw e;
+    }
+  };
+}
+
+function defaultDeps() {
+  const byName = Object.fromEntries(taskCommands.map((c) => [c.name, c]));
+  return {
+    next: recorded(byName['task next']),
+    claim: recorded(byName['task claim']),
+    release: recorded(byName['task release']),
+    viewIssue,
+    spawn: spawnAgent,
+    adapters: { load: loadAdapter },
+    loadConfig,
+    gitCommonDir: (cwd) => {
+      const r = exec('git', ['rev-parse', '--git-common-dir'], { cwd, allowFail: true });
+      return r.code === 0 && r.stdout ? resolve(cwd, r.stdout) : null;
+    },
+    sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+    log: (line) => process.stderr.write(`[crew worker] ${line}\n`),
+    now: () => Date.now(),
+  };
+}
+
+async function getAdapter(adapters, host) {
+  if (!adapters) return null;
+  if (typeof adapters.load === 'function') return adapters.load(host);
+  return adapters[host] ?? null;
+}
+
+/** The worker loop. deps are stubbed in tests: { next, claim, release, viewIssue, spawn, adapters, ... }. */
+export async function runWorker(opts, deps = {}) {
+  const d = { ...defaultDeps(), ...deps };
+  const {
+    host, area, tier = 'high', dry_run, wait,
+    max_tasks = 5, max_failures = 3, task_timeout_min = 60,
+  } = opts;
+
+  const adapter = await getAdapter(d.adapters, host);
+  if (!adapter?.headless) {
+    return fail('unknown_host', `No adapter with headless() for: ${host}`, {
+      cause_hint: 'adapters live in adapters/<host>/adapter.js',
+      retry: 'crew worker --host codex  (or claude)',
+      stop_when: 'the required host is not among the adapters',
+    });
+  }
+  const { config, root } = d.loadConfig();
+  const model = opts.model || config.tiers?.[tier]?.[host] || undefined;
+  const agent = `${host}/${model || 'default'}`;
+
+  const done = [];
+  const failed = [];
+  const handed = [];
+  let failStreak = 0;
+  let conflicts = 0;
+  let stopped_reason = null;
+  let started = 0;
+
+  const prevAgent = process.env.CREW_AGENT;
+  const prevAgentId = process.env.CREW_AGENT_ID;
+  process.env.CREW_AGENT = agent; // the worker claim/release run as the same agent as the child process
+  // Unique id: two workers of the same model on one machine are different agents (lease, review).
+  const agentUid = `${agent}@${machineName()}-w${process.pid}`;
+  process.env.CREW_AGENT_ID = agentUid;
+  const result = (extra = {}) => ({ done, failed, blocked: handed, stopped_reason, agent, ...extra });
+
+  try {
+    while (started < max_tasks) {
+      const nx = await call(d.next, { area, tier, tasks_only: true });
+      if (nx.status === 'error') {
+        if (nx.error?.code === 'paused') { stopped_reason = 'paused'; break; }
+        return fail(nx.error?.code ?? 'next_failed', `Worker stopped: ${nx.summary}`, {
+          ...(nx.error ?? {}),
+          artifacts: result({ stopped_reason: 'next_failed' }),
+        });
+      }
+      if (nx.status === 'warning' || !nx.artifacts?.issue) {
+        if (wait) {
+          d.log(`queue is empty, waiting ${WAIT_MS / 60_000} min`);
+          await d.sleep(WAIT_MS);
+          continue;
+        }
+        stopped_reason = 'no_tasks';
+        break;
+      }
+      const id = nx.artifacts.issue;
+
+      if (dry_run) {
+        const spec = adapter.headless({ prompt: taskPrompt({ id }), model, cwd: '<worktree>', writableDirs: [] });
+        return ok(`Dry run: would take #${id} and start ${host}`, {
+          artifacts: { issue: id, agent, command: [spec.cmd, ...spec.args].join(' '), prompt: taskPrompt({ id }) },
+          next_actions: [`crew worker --host ${host}${area ? ` --area ${area}` : ''} — run for real`],
+        });
+      }
+
+      const cl = await call(d.claim, { id });
+      if (cl.status === 'error') {
+        const code = cl.error?.code;
+        if (code === 'paused') { stopped_reason = 'paused'; break; }
+        if (code === 'claim_conflict' || code === 'not_ready') {
+          if (++conflicts >= 3) { stopped_reason = 'claim_conflicts'; break; }
+          d.log(`#${id}: ${cl.summary} — taking the next one`);
+          continue;
+        }
+        if (code === 'workspace_failed') {
+          // the claim has already been rolled back (the task is ready again) — we count it as a failure and do not stop the worker.
+          failed.push(id);
+          failStreak++;
+          d.log(`#${id}: ✖ ${cl.summary}, failures in a row: ${failStreak}/${max_failures}`);
+          if (failStreak >= max_failures) { stopped_reason = 'max_failures'; break; }
+          continue;
+        }
+        return fail(code ?? 'claim_failed', `Worker stopped: ${cl.summary}`, {
+          ...(cl.error ?? {}),
+          artifacts: result({ stopped_reason: 'claim_failed', issue: id }),
+        });
+      }
+      conflicts = 0;
+      started++;
+      const worktree = cl.artifacts?.worktree ?? root;
+      const commonDir = d.gitCommonDir?.(worktree);
+      const spec = adapter.headless({
+        prompt: taskPrompt({ id, branch: cl.artifacts?.branch }),
+        model,
+        cwd: worktree,
+        writableDirs: commonDir ? [commonDir] : [],
+      });
+      const logFile = join(root, '.crew', 'logs', `worker-${id}-${new Date().toISOString().replace(/[:.]/g, '-')}.log`);
+      d.log(`#${id}: starting ${agent} in ${worktree}`);
+      const t0 = d.now();
+      const res = await d.spawn(spec, {
+        cwd: worktree,
+        env: { ...spec.env, CREW_AGENT: agent, CREW_AGENT_ID: agentUid },
+        timeoutMs: task_timeout_min * 60_000,
+        logFile,
+      });
+      const took = fmtDuration(d.now() - t0);
+
+      if (res.error) {
+        await call(d.release, { id, note: `crew worker: could not start ${host}: ${res.error}` });
+        failed.push(id);
+        d.log(`#${id}: ✖ agent failed to start (${res.error})`);
+        return fail('tool_missing', `Could not start ${host}: ${res.error}`, {
+          cause_hint: `${spec.cmd} was not found or does not start; task #${id} was returned to the queue`,
+          retry: 'crew doctor',
+          stop_when: `${host} is not installed`,
+          artifacts: result({ stopped_reason: 'spawn_failed' }),
+        });
+      }
+
+      const issue = await call(d.viewIssue, id);
+      const state = issue?.labels ? labelValue(issue, 'status') : null;
+      const closed = issue?.state === 'CLOSED';
+
+      if (closed || SUCCESS.includes(state)) {
+        done.push(id);
+        failStreak = 0;
+        d.log(`#${id}: ✔ ${closed ? 'closed' : state} in ${took}`);
+      } else if (HANDOFF.includes(state)) {
+        handed.push({ issue: id, status: state });
+        failStreak = 0;
+        d.log(`#${id}: ! ${state} in ${took} — handoff to the issue`);
+      } else {
+        const why = res.timedOut ? `timeout ${task_timeout_min} min` : `agent exited with code ${res.code}, status ${state ?? 'unknown'}`;
+        if (state === 'claimed') await call(d.release, { id, note: `crew worker: ${why}. Log: ${logFile}` });
+        failed.push(id);
+        failStreak++;
+        d.log(`#${id}: ✖ ${why} (${took}), failures in a row: ${failStreak}/${max_failures}`);
+        if (failStreak >= max_failures) { stopped_reason = 'max_failures'; break; }
+      }
+    }
+    if (!stopped_reason) stopped_reason = 'max_tasks';
+  } finally {
+    if (prevAgent === undefined) delete process.env.CREW_AGENT;
+    else process.env.CREW_AGENT = prevAgent;
+    if (prevAgentId === undefined) delete process.env.CREW_AGENT_ID;
+    else process.env.CREW_AGENT_ID = prevAgentId;
+  }
+
+  const reasonText = {
+    paused: 'paused (issue crew:pause)',
+    no_tasks: 'queue is empty',
+    max_tasks: `task limit reached (${max_tasks})`,
+    max_failures: `${max_failures} failures in a row`,
+    claim_conflicts: '3 claim conflicts in a row',
+  }[stopped_reason];
+  const summary = `Worker ${agent} stopped: ${reasonText}. Delivered: ${done.length}, failures: ${failed.length}, handoffs: ${handed.length}`;
+  const next_actions = {
+    paused: ['wait until crew:pause is lifted and run crew worker again'],
+    no_tasks: ['crew status — what is blocked', `crew worker --host ${host} --wait — wait for new tasks`],
+    max_tasks: [`crew worker --host ${host} — next batch`],
+    max_failures: ['read the logs in .crew/logs/worker-*.log and the comments on the tasks', 'crew status'],
+    claim_conflicts: ['crew status — who else is claiming tasks', 'tell the human'],
+  }[stopped_reason];
+  const bad = stopped_reason === 'max_failures' || stopped_reason === 'claim_conflicts';
+  return (bad ? warn : ok)(summary, { artifacts: result(), next_actions });
+}
+
+export default {
+  name: 'worker',
+  summary: 'Run an agent (claude/codex) without a UI: it takes tasks one at a time, a new session per task',
+  agent: false,
+  args: [
+    { name: 'host', type: 'string', required: true, description: 'which agent: claude, codex' },
+    { name: 'area', type: 'string', description: 'task area: web, api, ... (empty = any)' },
+    { name: 'tier', type: 'string', enum: TIERS, description: 'model tier (default high); the model comes from crew.config.json → tiers' },
+    { name: 'model', type: 'string', description: 'a specific model (overrides tier)' },
+    { name: 'max_tasks', type: 'number', description: 'maximum number of tasks to take (default 5)' },
+    { name: 'max_failures', type: 'number', description: 'stop after N failures in a row (default 3)' },
+    { name: 'task_timeout_min', type: 'number', description: 'kill the agent after N minutes on a task (default 60)' },
+    { name: 'wait', type: 'boolean', description: 'if the queue is empty — wait for new tasks (polls every 5 min)' },
+    { name: 'dry_run', type: 'boolean', description: 'only show which task it would take and with which command' },
+  ],
+  run(opts) {
+    return runWorker(opts);
+  },
+};

package/src/core/board.js

@@ -0,0 +1,127 @@
+// Task board for humans (crew board): see the queue and steer it by hand without spending agent tokens.
+// Pure functions: the model shown on the page, and the gh arguments for each action the page can request.
+import { labelValue } from './issues.js';
+import { prQueue } from './queue.js';
+import { LOGIN_RE } from './prd.js';
+
+export const COLUMNS = ['ready', 'claimed', 'review', 'waiting', 'blocked', 'needs-spec'];
+export const PRIORITIES = ['high', 'normal', 'low'];
+/** Statuses a human may set from the board. claimed/review belong to the agent's lease and PR flow. */
+export const BOARD_STATUSES = ['ready', 'blocked', 'needs-spec', 'waiting'];
+
+const prio = (i) => labelValue(i, 'priority') ?? 'normal';
+
+export function boardModel({ issues = [], prs = [], members = [], config = {}, now = Date.now() } = {}) {
+  const columns = Object.fromEntries(COLUMNS.map((c) => [c, []]));
+  const other = [];
+  for (const i of issues) {
+    const status = labelValue(i, 'status');
+    if ((i.labels ?? []).some((l) => l.name === 'epic')) continue;
+    const card = {
+      number: i.number,
+      title: i.title,
+      status,
+      area: labelValue(i, 'area'),
+      tier: labelValue(i, 'tier'),
+      risk: labelValue(i, 'risk'),
+      priority: prio(i),
+      assignees: (i.assignees ?? []).map((a) => a.login),
+      idle_min: Math.max(0, Math.round((now - Date.parse(i.updatedAt ?? '')) / 60000)) || 0,
+    };
+    (columns[status] ?? other).push(card);
+  }
+  const order = { high: 0, normal: 1, low: 2 };
+  for (const c of COLUMNS) columns[c].sort((a, b) => order[a.priority] - order[b.priority] || a.number - b.number);
+  const queue = prQueue(prs, { me: 'board', login: null, reviewers: [], config, now }).map((x) => ({
+    kind: x.kind, number: x.number, title: x.title, risk: x.risk, age_min: x.age, reason: x.reason ?? null, have: x.have ?? null, need: x.need ?? null,
+  }));
+  return { columns, untracked: other.length, prs: queue, members: [...new Set(members)].sort((a, b) => a.localeCompare(b)), generated_at: new Date(now).toISOString() };
+}
+
+/**
+ * gh arguments for one board action, or { error }. Everything is validated here because the page
+ * is only a convenience: the server never passes page input to gh unchecked.
+ * current: the issue as listed ({ number, labels, assignees }).
+ */
+export function actionArgs({ op, value }, current, { members = [] } = {}) {
+  if (!current || !Number.isInteger(current.number)) return { error: 'unknown issue' };
+  const n = String(current.number);
+  const labels = (current.labels ?? []).map((l) => l.name);
+  if (op === 'assign') {
+    const to = String(value ?? '');
+    const now = (current.assignees ?? []).map((a) => a.login);
+    if (to && (!LOGIN_RE.test(to) || !members.some((m) => m.toLowerCase() === to.toLowerCase()))) return { error: `${to} is not a member of this repo` };
+    const args = ['issue', 'edit', n];
+    for (const a of now) if (a.toLowerCase() !== to.toLowerCase()) args.push('--remove-assignee', a);
+    if (to && !now.some((a) => a.toLowerCase() === to.toLowerCase())) args.push('--add-assignee', to);
+    return args.length > 3 ? { args } : { noop: true };
+  }
+  if (op === 'status') {
+    const to = String(value ?? '');
+    if (!BOARD_STATUSES.includes(to)) return { error: `status must be one of ${BOARD_STATUSES.join(', ')}` };
+    const from = labels.filter((l) => l.startsWith('status:')).map((l) => l.slice(7));
+    if (from.some((s) => s === 'claimed' || s === 'review')) {
+      return { error: `#${n} is ${from.join(',')}: an agent holds it — use crew task release ${n} --force first` };
+    }
+    if (from.length === 1 && from[0] === to) return { noop: true };
+    const args = ['issue', 'edit', n, '--add-label', `status:${to}`];
+    for (const f of from) if (f !== to) args.push('--remove-label', `status:${f}`);
+    return { args };
+  }
+  if (op === 'priority') {
+    const to = String(value ?? '');
+    if (!PRIORITIES.includes(to)) return { error: `priority must be one of ${PRIORITIES.join(', ')}` };
+    const args = ['issue', 'edit', n];
+    for (const l of labels.filter((x) => x.startsWith('priority:') && x !== `priority:${to}`)) args.push('--remove-label', l);
+    if (to !== 'normal' && !labels.includes(`priority:${to}`)) args.push('--add-label', `priority:${to}`);
+    return args.length > 3 ? { args } : { noop: true };
+  }
+  return { error: `unknown action ${op}` };
+}
+
+const esc = (s) => String(s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+
+/** The board page. Data comes from /api/board; actions go to /api/action with the per-run token. */
+export function renderPage({ token, repo }) {
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>crew board — ${esc(repo)}</title>
+<style>
+:root{--bg:#f6f7f9;--card:#fff;--ink:#1d2433;--muted:#667085;--line:#e3e6ec;--hi:#d92d20}
+@media (prefers-color-scheme:dark){:root{--bg:#111418;--card:#1a1f26;--ink:#e6e9ef;--muted:#98a2b3;--line:#2a313b}}
+*{box-sizing:border-box}body{margin:0;font:14px/1.4 system-ui,sans-serif;background:var(--bg);color:var(--ink)}
+header{display:flex;gap:12px;align-items:center;padding:12px 16px;border-bottom:1px solid var(--line);flex-wrap:wrap}
+header h1{font-size:16px;margin:0}.muted{color:var(--muted)}
+main{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:12px;padding:12px 16px}
+section h2,#prs h2{font-size:12px;text-transform:uppercase;letter-spacing:.06em;color:var(--muted);margin:4px 0 8px}
+.card{background:var(--card);border:1px solid var(--line);border-radius:8px;padding:10px;margin-bottom:8px}
+.card a{color:var(--ink);text-decoration:none;font-weight:600}.meta{color:var(--muted);font-size:12px;margin:4px 0 6px}
+.prio-high{border-left:4px solid var(--hi)}.prio-low{opacity:.75}
+.row{display:flex;gap:6px;flex-wrap:wrap}select{font:inherit;font-size:12px;padding:2px 4px;border-radius:6px;border:1px solid var(--line);background:var(--card);color:var(--ink)}
+#prs{padding:0 16px 16px}#prs a{color:var(--ink)}#prs li{margin:4px 0}#msg{color:var(--hi)}
+</style></head><body>
+<header><h1>crew board</h1><span class="muted">${esc(repo)}</span><span class="muted" id="time"></span><span id="msg"></span></header>
+<main id="cols"></main>
+<div id="prs"><h2>Pull requests waiting</h2><ul id="prlist"></ul></div>
+<script>
+const TOKEN=${JSON.stringify(token)};const REPO=${JSON.stringify(repo)};
+const COLS=${JSON.stringify(COLUMNS)};const ST=${JSON.stringify(BOARD_STATUSES)};const PR=${JSON.stringify(PRIORITIES)};
+const e=(t,a={},...k)=>{const n=document.createElement(t);for(const[x,y]of Object.entries(a)){if(x==='on')for(const[ev,f]of Object.entries(y))n.addEventListener(ev,f);else n.setAttribute(x,y)}for(const c of k)n.append(c);return n};
+const sel=(opts,cur,on)=>{const s=e('select',{on:{change:()=>on(s.value)}});for(const[v,l]of opts){const o=e('option',{value:v},l);if(v===cur)o.selected=true;s.append(o)}return s};
+async function act(issue,op,value){const r=await fetch('/api/action',{method:'POST',headers:{'content-type':'application/json','x-crew-token':TOKEN},body:JSON.stringify({issue,op,value})});const j=await r.json();document.getElementById('msg').textContent=j.error||'';load()}
+async function load(){const r=await fetch('/api/board',{headers:{'x-crew-token':TOKEN}});const m=await r.json();if(m.error){document.getElementById('msg').textContent=m.error;return}
+document.getElementById('time').textContent='updated '+new Date(m.generated_at).toLocaleTimeString();
+const cols=document.getElementById('cols');cols.replaceChildren();
+for(const c of COLS){const s=e('section',{},e('h2',{},c+' ('+m.columns[c].length+')'));
+for(const t of m.columns[c]){const who=[['','unassigned'],...m.members.map(x=>[x,x])];
+const ctl=e('div',{class:'row'},sel(who,t.assignees[0]||'',v=>act(t.number,'assign',v)),sel(PR.map(p=>[p,p]),t.priority,v=>act(t.number,'priority',v)));
+if(ST.includes(t.status))ctl.append(sel(ST.map(x=>[x,x]),t.status,v=>act(t.number,'status',v)));
+s.append(e('div',{class:'card prio-'+t.priority},e('a',{href:'https://github.com/'+REPO+'/issues/'+t.number,target:'_blank',rel:'noopener'},'#'+t.number+' '+t.title),
+e('div',{class:'meta'},[t.area&&('area:'+t.area),t.risk&&('risk:'+t.risk),t.tier&&('tier:'+t.tier),t.assignees.length?('@'+t.assignees.join(' @')):'no owner',t.idle_min+' min'].filter(Boolean).join(' · ')),ctl))}
+cols.append(s)}
+const ul=document.getElementById('prlist');ul.replaceChildren();
+for(const p of m.prs)ul.append(e('li',{},e('a',{href:'https://github.com/'+REPO+'/pull/'+p.number,target:'_blank',rel:'noopener'},'#'+p.number+' '+p.title),' — '+(p.kind==='review'?('waiting for review '+p.age_min+' min ('+p.have+'/'+p.need+')'):p.kind==='merge'?'ready to merge':('waiting for the author: '+p.reason))));
+if(!m.prs.length)ul.append(e('li',{class:'muted'},'none'))}
+load();setInterval(load,30000);
+</script></body></html>`;
+}

package/src/core/config.js

@@ -0,0 +1,83 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { hostname } from 'node:os';
+import { pinnedId } from './session.js';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const HARNESS_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+export const DEFAULT_CONFIG = {
+  // Areas = directories. An agent with --area web only touches web/**.
+  // e2e: acceptance and E2E tests, including tests/pending/** (test tasks for risk:high).
+  areas: {
+    web: ['web/**'],
+    api: ['api/**'],
+    contracts: ['contracts/**'],
+    e2e: ['tests/e2e/**', 'tests/acceptance/**', 'tests/pending/**'],
+    infra: ['infra/**', '.github/**'],
+    // Not code: designer mockups and styles, researcher notes. Styles web/src/styles/** are shared with web.
+    design: ['design/**', 'web/src/styles/**'],
+    research: ['docs/research/**'],
+  },
+  // What `crew check` runs (in order). An empty string or missing entry means the step is skipped.
+  check: [],
+  // Task lease: how many minutes without activity before the task returns to the queue.
+  lease_minutes: 45,
+  // Model tiers -> concrete models per vendor (crew worker passes them to --model). Codex: Sol -> Terra -> Luna.
+  tiers: {
+    high: { claude: 'opus', codex: 'gpt-6.1-sol' },
+    mid: { claude: 'sonnet', codex: 'gpt-6.1-terra' },
+    low: { claude: 'haiku', codex: 'gpt-6-luna' },
+  },
+  hosts: ['claude', 'codex'],
+  // Agent review instead of a human approve button (checked by crew guard / the crew-guard status).
+  // Who reviews first is the review area in the PRD crew-team block (usually the captain); crew task next gives them PRs before tasks.
+  //   require: other-vendor means a reviewer from another vendor; other-agent means any other agent (team with Claude only).
+  //   Default is other-vendor when there is more than one host. If no other-vendor reviewer shows up within fallback_minutes,
+  //   any other agent counts (so PRs do not hang).
+  review: { approvals: 1, approvals_high: 1, fallback_minutes: 30 },
+  event: null, // path to events/<name>.json when a hackathon is running
+};
+
+/** Find crew.config.json walking up from cwd. Returns { config, root } (root = project root). */
+export function loadConfig(cwd = process.cwd()) {
+  let dir = resolve(cwd);
+  for (;;) {
+    const p = join(dir, 'crew.config.json');
+    if (existsSync(p)) {
+      const user = JSON.parse(readFileSync(p, 'utf8'));
+      return { config: { ...DEFAULT_CONFIG, ...user }, root: dir, path: p };
+    }
+    const up = dirname(dir);
+    if (up === dir) return { config: { ...DEFAULT_CONFIG }, root: resolve(cwd), path: null };
+    dir = up;
+  }
+}
+
+export function loadEvent(config, root) {
+  if (!config.event) return null;
+  const p = resolve(root, config.event);
+  return existsSync(p) ? JSON.parse(readFileSync(p, 'utf8')) : null;
+}
+
+/** Short machine name for the agent id: "petya-laptop". */
+export const machineName = () =>
+  (hostname().split('.')[0] || 'host').toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-|-$/g, '').slice(0, 24) || 'host';
+
+/**
+ * Agent id: <vendor>[/<model>]@<machine>, e.g. claude@petya-laptop, codex/gpt-x@masha-pc.
+ * CREW_AGENT sets vendor/model (adapters set it; for all Claude agents it is just "claude"),
+ * the machine is appended automatically, otherwise three Claudes on three laptops would be one agent
+ * (another agent's lease would be taken for your own, and review by "another agent" would be impossible).
+ * For several sessions on one machine, give each its own CREW_AGENT_ID (claude@petya-2).
+ */
+export function agentId(env = process.env) {
+  if (env.CREW_AGENT_ID) return env.CREW_AGENT_ID;
+  // A task worktree remembers who claimed it (crew task claim), so CLI calls there act as the same session.
+  if (env === process.env) {
+    const pinned = pinnedId();
+    if (pinned) return pinned;
+  }
+  const base = env.CREW_AGENT || 'human';
+  return base.includes('@') ? base : `${base}@${machineName()}`;
+}

package/src/core/digest.js

@@ -0,0 +1,67 @@
+// Team digest without an LLM: what waits for a human, stale leases, PRs, idle members. `crew digest` prints it;
+// the sweep job posts it to one pinned issue every 15 minutes, so no agent session has to poll the repo.
+import { labelValue } from './issues.js';
+import { prQueue } from './queue.js';
+import { questionMeta, HUMAN_LABEL, QUESTION_LABEL } from './questions.js';
+
+export const DIGEST_LABEL = 'crew:digest';
+export const DIGEST_TITLE = 'crew digest: team status';
+export const DIGEST_MARKER = '<!-- crew:digest -->';
+
+const minsSince = (now, iso) => Math.max(0, Math.round((now - Date.parse(iso ?? '')) / 60000)) || 0;
+const names = (xs) => (xs ?? []).map((x) => x.name);
+
+/** -> { sections: [{ key, title, lines }], counts } (pure, no network). */
+export function digestModel({ issues = [], prs = [], questions = [], team = null, config = {}, now = Date.now() } = {}) {
+  const lease = config.lease_minutes ?? 45;
+  const reviewWait = config.review?.fallback_minutes ?? 30;
+  const st = (i) => labelValue(i, 'status');
+  const who = (i) => (i.assignees ?? []).map((a) => `@${a.login}`).join(' ') || 'no owner';
+  const tasks = issues.filter((i) => !names(i.labels).some((n) => ['epic', QUESTION_LABEL, DIGEST_LABEL].includes(n)));
+  const ready = tasks.filter((i) => st(i) === 'ready');
+  const claimed = tasks.filter((i) => st(i) === 'claimed');
+
+  const human = questions.filter((q) => names(q.labels).includes(HUMAN_LABEL))
+    .map((q) => `#${q.number} ${q.title} (asked by ${questionMeta(q)?.from ?? 'an agent'})`);
+  const blocked = tasks.filter((i) => ['blocked', 'needs-spec'].includes(st(i))).map((i) => `#${i.number} ${i.title} (${st(i)}, ${who(i)})`);
+  const stale = claimed.filter((i) => minsSince(now, i.updatedAt) > lease)
+    .map((i) => `#${i.number} ${i.title} (${who(i)}, quiet ${minsSince(now, i.updatedAt)} min, lease ${lease})`);
+  const prLines = prQueue(prs, { me: 'crew-digest', login: null, reviewers: [], config, now }).map((x) =>
+    x.kind === 'fix' ? `#${x.number} ${x.title}: waits for its author (${x.reason})`
+      : x.kind === 'merge' ? `#${x.number} ${x.title}: ready to merge`
+        : `#${x.number} ${x.title}: waits for review ${x.age} min${x.age > reviewWait ? ' (slow)' : ''}`);
+  const unanswered = questions.filter((q) => !names(q.labels).includes(HUMAN_LABEL))
+    .map((q) => `#${q.number} ${q.title} (to ${who(q)}, ${minsSince(now, q.createdAt ?? q.updatedAt)} min)`);
+  const idle = [];
+  for (const m of team?.members ?? []) {
+    const lc = m.login.toLowerCase();
+    const mine = (i) => (i.assignees ?? []).some((a) => a.login.toLowerCase() === lc);
+    if (claimed.some(mine)) continue;
+    const waiting = ready.filter(mine).length;
+    idle.push(`@${m.login}: nothing in progress, ${waiting ? `${waiting} ready task(s) assigned` : 'no ready tasks assigned'}`);
+  }
+
+  const sections = [
+    { key: 'human', title: 'Needs a human', lines: [...human, ...blocked] },
+    { key: 'stale', title: 'Stale leases', lines: stale },
+    { key: 'prs', title: 'Pull requests', lines: prLines },
+    { key: 'questions', title: 'Open questions between agents', lines: unanswered },
+    { key: 'idle', title: 'Idle members', lines: idle },
+  ];
+  return {
+    sections,
+    counts: { ready: ready.length, claimed: claimed.length, human: human.length + blocked.length, stale: stale.length, prs: prLines.length, questions: unanswered.length, idle: idle.length },
+  };
+}
+
+/** Markdown for the pinned issue (and the terminal). */
+export function renderDigest(model, { now = Date.now() } = {}) {
+  const c = model.counts;
+  const stamp = new Date(now).toISOString().replace('T', ' ').slice(0, 16);
+  const out = [DIGEST_MARKER, `_Updated ${stamp} UTC by \`crew digest\` (no LLM). Edits here are overwritten._`, '',
+    `**${c.ready}** ready · **${c.claimed}** in progress · **${c.human}** need a human · **${c.stale}** stale · **${c.prs}** PRs waiting`, ''];
+  // The issue is rewritten every 15 minutes: break @mentions (ours and any in titles) so nobody gets pinged each time.
+  const quiet = (l) => l.replace(/@(?=[\w-])/g, '@​');
+  for (const s of model.sections) out.push(`### ${s.title}`, ...(s.lines.length ? s.lines.map((l) => `- ${quiet(l)}`) : ['- none']), '');
+  return out.join('\n');
+}

package/src/core/exec.js

@@ -0,0 +1,50 @@
+import { spawnSync } from 'node:child_process';
+import { CrewError } from './output.js';
+import { runSupervised } from './proc.js';
+
+/** Run an external command without a shell (cross-platform, no injection). */
+export function run(cmd, args = [], { cwd, allowFail = false, input } = {}) {
+  const res = spawnSync(cmd, args, {
+    cwd,
+    input,
+    encoding: 'utf8',
+    shell: false,
+    windowsHide: true,
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  if (res.error) {
+    if (allowFail) return { code: -1, stdout: '', stderr: String(res.error.message) };
+    throw new CrewError('tool_missing', `failed to run ${cmd}`, {
+      cause_hint: res.error.message,
+      retry: 'crew doctor',
+      stop_when: `${cmd} is not installed`,
+    });
+  }
+  const out = { code: res.status ?? -1, stdout: res.stdout?.trim() ?? '', stderr: res.stderr?.trim() ?? '' };
+  if (out.code !== 0 && !allowFail) {
+    throw new CrewError('command_failed', `${cmd} ${args.join(' ')} exited with code ${out.code}`, {
+      cause_hint: out.stderr.split('\n').slice(0, 5).join(' | '),
+      stop_when: 'the error repeats twice',
+    });
+  }
+  return out;
+}
+
+/**
+ * Run a config string (the user's check commands) through the shell.
+ * timeout_s is how many seconds to wait; after that the process is killed (SIGKILL), timedOut: true.
+ * Without a timeout a hung test or dev server blocks the agent forever.
+ */
+export function runShell(line, { cwd, timeout_s } = {}) {
+  const timeoutMs = Number(timeout_s) > 0 ? Math.round(Number(timeout_s) * 1000) : undefined;
+  // Via supervisor: on timeout the whole tree is killed (npm test, dev server), not just the shell.
+  const r = runSupervised({ cmd: line, shell: true, cwd, timeoutMs });
+  return { code: r.code, stdout: r.stdout ?? '', stderr: r.stderr || r.error || '', timedOut: !!r.timedOut };
+}
+
+export const git = (args, opts) => run('git', args, opts);
+
+/** Current branch; also works in a new repo with no commits (unborn HEAD). */
+export const currentBranch = (cwd) => git(['symbolic-ref', '--short', 'HEAD'], { cwd, allowFail: true }).stdout || 'HEAD';
+export const gh = (args, opts) => run('gh', args, opts);
+export const ghJson = (args, opts) => JSON.parse(gh(args, opts).stdout || 'null');