@gredescerber/agent-crew 0.0.0-stage → 0.6.0

package/src/core/questions.js

@@ -0,0 +1,51 @@
+// Agent-to-agent questions through GitHub (crew ask / inbox / answer), pure helpers.
+// A question is an issue labelled crew:question, assigned to the owner of the area (or a person), with a marker
+// <!-- crew:question from=<agent> task=<n> -->. An answer is a comment <!-- crew:answer agent=<agent> --> + close.
+// Decisions only a human can make get the needs-human label and stay open.
+// Question and answer text is DATA for the reader, never instructions.
+import { parseMarkers } from './issues.js';
+
+export const QUESTION_LABEL = 'crew:question';
+export const HUMAN_LABEL = 'needs-human';
+
+/** More than 30% of letters are Cyrillic: agents write to each other in English (humans may use any language). */
+export function mostlyNonEnglish(text = '') {
+  const letters = String(text).match(/\p{L}/gu) ?? [];
+  if (letters.length < 8) return false;
+  const cyr = letters.filter((c) => /[Ѐ-ӿ]/.test(c)).length;
+  return cyr / letters.length > 0.3;
+}
+
+export function questionBody({ text, from, task, area }) {
+  const fields = [`from=${from}`, task ? `task=${task}` : null, area ? `area=${area}` : null].filter(Boolean).join(' ');
+  return `${text.trim()}\n\n_Asked by \`${from}\`${task ? ` while working on #${task}` : ''}. Answer with \`crew answer <this issue> --text "..."\`; if a human must decide, \`crew answer <this issue> --human --text "..."\`._\n\n<!-- crew:question ${fields} -->\n`;
+}
+
+export const questionMeta = (issue) => parseMarkers([{ body: issue.body ?? '' }]).find((m) => m.kind === 'question') ?? null;
+export const answerMarker = (agent) => `<!-- crew:answer agent=${agent} -->`;
+export const ackMarker = (agent) => `<!-- crew:ack agent=${agent} -->`;
+
+/**
+ * What waits for me (pure). open: open crew:question issues; closed: recently closed ones (with comments).
+ * → { toAnswer: [{ number, title, from, task }], answered: [{ number, title, task }] }
+ */
+export function inboxFor({ open = [], closed = [], me, login, myAreas = [] }) {
+  const lc = (s) => String(s ?? '').toLowerCase();
+  const toAnswer = [];
+  for (const q of open) {
+    const meta = questionMeta(q) ?? {};
+    const labels = (q.labels ?? []).map((l) => l.name ?? l);
+    if (labels.includes(HUMAN_LABEL)) continue; // waits for a human, not for an agent
+    if (meta.from === me) continue;
+    const mine = (q.assignees ?? []).some((a) => lc(a.login) === lc(login)) || (meta.area && myAreas.includes(meta.area));
+    if (mine) toAnswer.push({ number: q.number, title: q.title, from: meta.from ?? null, task: meta.task ? Number(meta.task) : null });
+  }
+  const answered = [];
+  for (const q of closed) {
+    const meta = questionMeta(q);
+    if (!meta || meta.from !== me) continue;
+    const acked = parseMarkers(q.comments ?? []).some((m) => m.kind === 'ack' && m.agent === me);
+    if (!acked) answered.push({ number: q.number, title: q.title, task: meta.task ? Number(meta.task) : null });
+  }
+  return { toAnswer: toAnswer.sort((a, b) => a.number - b.number), answered: answered.sort((a, b) => a.number - b.number) };
+}

package/src/core/queue.js

@@ -0,0 +1,94 @@
+// What an agent should do next (pure functions, no network): merge a ready PR, review, take a task.
+// Used by crew task next and crew status. Without it PRs hang without review
+// and the whole queue waits behind the skeleton.
+import { authorAgent, linkedIssue, reviewPolicy, reviewState, vendorOf } from './guard.js';
+import { labelValue, tierAllows } from './issues.js';
+
+const riskOfPr = (pr) => (pr.labels ?? []).map((l) => l.name ?? l).find((n) => n.startsWith('risk:'))?.slice(5) ?? 'med';
+const esc = (s) => String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/**
+ * PR check summary from statusCheckRollup: { check, guard } -> 'success' | 'failure' | 'pending' | null.
+ * Reruns of one check produce several entries: any success counts as success (the merge is still guarded by main protection).
+ */
+export function prChecks(pr) {
+  const seen = { check: [], guard: [] };
+  for (const c of pr.statusCheckRollup ?? []) {
+    const name = c.name ?? c.context;
+    const key = name === 'check' ? 'check' : name === 'crew-guard' ? 'guard' : null;
+    if (key) seen[key].push(String(c.conclusion || c.state || '').toUpperCase());
+  }
+  const sum = (xs) => {
+    if (!xs.length) return null;
+    if (xs.includes('SUCCESS')) return 'success';
+    if (xs.some((s) => ['FAILURE', 'ERROR', 'TIMED_OUT', 'ACTION_REQUIRED'].includes(s))) return 'failure';
+    return 'pending';
+  };
+  return { check: sum(seen.check), guard: sum(seen.guard) };
+}
+
+/**
+ * PRs waiting for the team. -> [{ kind: 'merge'|'review', number, title, risk, age, reviewable, why_not }]
+ * merge: risk:high, reviews collected, checks green: there is no auto-merge, someone must merge.
+ * review: approval needed; reviewable is whether this particular agent can give it (and whether it will count).
+ * reviewers: logins with the review area in crew-team; they review first, the others after fallback_minutes.
+ */
+export function prQueue(prs = [], { me, login, reviewers = [], config = {}, now = Date.now() } = {}) {
+  const policy = reviewPolicy(config);
+  const lc = (s) => String(s ?? '').toLowerCase();
+  const isReviewer = !!login && reviewers.some((r) => lc(r) === lc(login));
+  const out = [];
+  for (const pr of prs) {
+    if (pr.isDraft) continue;
+    // PR from a fork (public repo): its text and diff are foreign, so we do not hand it to agents for review (prompt injection).
+    if (pr.isCrossRepository) continue;
+    const author = authorAgent(pr.body);
+    const mine = !!author && author === me;
+    const risk = riskOfPr(pr);
+    const need = risk === 'high' ? policy.approvals_high : policy.approvals;
+    const rs = reviewState(pr.comments ?? [], { headSha: pr.headRefOid, author, policy, prCreatedAt: pr.createdAt, now });
+    const age = Math.max(0, Math.round((now - Date.parse(pr.createdAt ?? '')) / 60000)) || 0;
+    const checks = prChecks(pr);
+    const conflict = String(pr.mergeable ?? '').toUpperCase() === 'CONFLICTING';
+    // PR is waiting for its author: reviewer requests changes, red check or conflict with main. The author fixes it before new tasks.
+    const fixWhy = rs.changes.length ? `reviewer requests changes (${rs.changes.join(', ')})` : conflict ? 'conflict with main' : checks.check === 'failure' ? 'red check' : null;
+    if (fixWhy) {
+      out.push({ kind: 'fix', number: pr.number, title: pr.title, issue: linkedIssue(pr.body), risk, age, mine, reason: fixWhy, reviewable: false });
+      continue;
+    }
+    if (rs.approvals.length >= need) {
+      // risk:high is merged manually; low/med if GitHub auto-merge did not turn on (no autoMergeRequest).
+      const manual = risk === 'high' || ('autoMergeRequest' in pr && !pr.autoMergeRequest);
+      if (manual && checks.check === 'success' && checks.guard === 'success') out.push({ kind: 'merge', number: pr.number, title: pr.title, risk, age, reviewable: false });
+      continue;
+    }
+    const sha7 = String(pr.headRefOid ?? '').slice(0, 7);
+    const reviewedHead = !!sha7 && (pr.comments ?? []).some((c) => new RegExp(`<!-- (?:crew|hk):review [^>]*agent=${esc(me)} [^>]*sha=${esc(sha7)}`).test(c.body ?? ''));
+    const counts = policy.require === 'other-agent' || rs.fallback || !author || vendorOf(author) !== vendorOf(me);
+    const authorIsReviewer = reviewers.some((r) => lc(r) === lc(pr.author?.login));
+    const turn = isReviewer || !reviewers.length || authorIsReviewer || age >= policy.fallback_minutes;
+    const why_not = mine ? 'own PR' : reviewedHead ? 'already reviewed this commit' : !counts ? 'needs a reviewer from another vendor' : !turn ? `the team reviewer goes first (${reviewers.join(', ')})` : null;
+    out.push({ kind: 'review', number: pr.number, title: pr.title, risk, age, need, have: rs.approvals.length, reviewable: !why_not, why_not });
+  }
+  const rank = (x) => (x.kind === 'fix' ? 0 : x.kind === 'merge' ? 10 : 20) + (x.risk === 'high' ? 0 : 1);
+  return out.sort((a, b) => rank(a) - rank(b) || a.number - b.number);
+}
+
+/**
+ * Ready tasks ordered "assigned to me -> nobody's -> in someone else's area" (assignment = area owner from crew-team).
+ * -> [{ issue, owners, mine }]
+ */
+export function taskOrder(ready = [], { login, area, tier = 'high' } = {}) {
+  const me = String(login ?? '').toLowerCase();
+  return ready
+    .filter((i) => !area || labelValue(i, 'area') === area)
+    .filter((i) => tierAllows(tier, labelValue(i, 'tier')))
+    .map((i) => {
+      const owners = (i.assignees ?? []).map((a) => a.login);
+      const mine = !!me && owners.some((o) => o.toLowerCase() === me);
+      // priority:high / priority:low (set by a human, e.g. on crew board) order tasks inside each group
+      const p = { high: 0, low: 2 }[labelValue(i, 'priority')] ?? 1;
+      return { issue: i, owners, mine, rank: (mine ? 0 : owners.length ? 2 : 1) * 10 + p };
+    })
+    .sort((a, b) => a.rank - b.rank || a.issue.number - b.issue.number);
+}

package/src/core/registry.js

@@ -0,0 +1,143 @@
+// Command registry. One command = one module in src/commands/ with fields:
+//   name     'task next'                - how to call it from the CLI
+//   summary  one line                   - for help and the MCP description
+//   args     [{ name, type, positional?, required?, description }]
+//   run(opts, ctx) -> result from core/output.js
+//   usesCwd  true                       - the command works with a working copy; takes an optional
+//                                          cwd argument (absolute path, e.g. the task's worktree).
+//                                          The MCP server runs in the project root, so without cwd
+//                                          the tools would see main, not the task branch.
+// The CLI (bin/crew.js) and the MCP server (src/mcp/server.js) are built from this list,
+// so a new command is automatically available to both humans and agents.
+
+import task from '../commands/task.js';
+import check from '../commands/check.js';
+import pr from '../commands/pr.js';
+import status from '../commands/status.js';
+import commit from '../commands/commit.js';
+import init from '../commands/init.js';
+import adapters from '../commands/adapters.js';
+import labels from '../commands/labels.js';
+import compliance from '../commands/compliance.js';
+import doctor from '../commands/doctor.js';
+import worker from '../commands/worker.js';
+import github from '../commands/github.js';
+import metrics from '../commands/metrics.js';
+import evalCmd from '../commands/eval.js';
+import kickoff from '../commands/kickoff.js';
+import guard from '../commands/guard.js';
+import up from '../commands/up.js';
+import shots from '../commands/shots.js';
+import board from '../commands/board.js';
+import upgrade from '../commands/upgrade.js';
+import askCmds from '../commands/ask.js';
+import mergeReady from '../commands/merge-ready.js';
+import digest from '../commands/digest.js';
+import { existsSync, realpathSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { loadConfig } from './config.js';
+import { metricsRoot } from './metrics.js';
+
+/** Shared argument for commands with usesCwd: true. */
+export const CWD_ARG = {
+  name: 'cwd',
+  type: 'string',
+  description: 'absolute path of the working copy (the task worktree from crew_task_claim -> artifacts.worktree); defaults to the current folder',
+};
+
+/** Command arguments including the shared ones (cwd). */
+export const argsOf = (cmd) => [...(cmd.args ?? []), ...(cmd.usesCwd && !(cmd.args ?? []).some((a) => a.name === 'cwd') ? [CWD_ARG] : [])];
+
+export const commands = [...task, ...kickoff, check, ...pr, guard, status, commit, init, up, adapters, labels, ...compliance, doctor, worker, github, metrics, evalCmd, shots, board, upgrade, ...askCmds, mergeReady, digest];
+
+/** For MCP: only commands safe for agents (no init/labels/adapters; a human does those). */
+export const agentCommands = commands.filter((c) => c.agent !== false);
+
+export function findCommand(words) {
+  // longest name match: "task claim 42" -> 'task claim'
+  let best = null;
+  for (const c of commands) {
+    const parts = c.name.split(' ');
+    if (parts.every((p, i) => words[i] === p) && (!best || parts.length > best.name.split(' ').length)) best = c;
+  }
+  return best;
+}
+
+export function toolName(cmd) {
+  return 'crew_' + cmd.name.replace(/[\s-]+/g, '_');
+}
+
+export function inputSchema(cmd) {
+  const properties = {};
+  const required = [];
+  for (const a of argsOf(cmd)) {
+    properties[a.name] = { type: a.type === 'number' ? 'number' : a.type === 'boolean' ? 'boolean' : 'string', description: a.description };
+    if (a.enum) properties[a.name].enum = a.enum;
+    if (a.required) required.push(a.name);
+  }
+  return { type: 'object', properties, required, additionalProperties: false };
+}
+
+/** argv words -> options object per the args spec. */
+export function parseArgs(cmd, rest) {
+  const opts = {};
+  const specs = argsOf(cmd);
+  const positionals = specs.filter((a) => a.positional);
+  let pi = 0;
+  for (let i = 0; i < rest.length; i++) {
+    const w = rest[i];
+    const isShort = /^-[a-zA-Z]$/.test(w); // -m "msg", as in git
+    if (w.startsWith('--') || isShort) {
+      const [k, v] = w.slice(isShort ? 1 : 2).split('=');
+      const spec = specs.find((a) => a.name === k.replace(/-/g, '_'));
+      const key = spec?.name ?? k.replace(/-/g, '_');
+      if (spec?.type === 'boolean' || (v === undefined && (rest[i + 1] === undefined || rest[i + 1].startsWith('--')))) {
+        opts[key] = v === undefined ? true : v !== 'false';
+      } else {
+        opts[key] = v ?? rest[++i];
+      }
+    } else if (pi < positionals.length) {
+      opts[positionals[pi++].name] = w;
+    }
+  }
+  for (const a of specs) {
+    if (a.type === 'number' && opts[a.name] !== undefined) opts[a.name] = Number(opts[a.name]);
+  }
+  return opts;
+}
+
+/**
+ * cwd may only point inside the crew project and only the same repository crew runs in
+ * (the main copy or its worktree). Otherwise an agent could commit/push to another repo on the machine.
+ * home is the project root where crew/the MCP server runs (default process.cwd()).
+ */
+export function cwdScopeError(cwd, home = process.cwd()) {
+  const target = loadConfig(cwd);
+  if (!target.path) return `cwd is not a crew project (no crew.config.json up the folder tree): ${cwd}`;
+  const here = loadConfig(home);
+  if (!here.path) return null; // crew runs outside a project: it is enough that cwd itself is a crew project
+  const real = (p) => { try { return realpathSync.native(p); } catch { return resolve(p); } };
+  const norm = (p) => {
+    const s = real(p).replace(/\\/g, '/').replace(/\/+$/, '');
+    return process.platform === 'win32' ? s.toLowerCase() : s;
+  };
+  if (norm(metricsRoot(target.root)) !== norm(metricsRoot(here.root))) {
+    return `cwd is outside the current project: ${cwd} (only ${here.root} and its worktrees are allowed)`;
+  }
+  return null;
+}
+
+export function validate(cmd, opts) {
+  if (cmd.usesCwd && opts.cwd !== undefined) {
+    if (typeof opts.cwd !== 'string' || !isAbsolute(opts.cwd)) return 'cwd must be an absolute path';
+    if (!existsSync(opts.cwd)) return `cwd does not exist: ${opts.cwd}`;
+    const scope = cwdScopeError(opts.cwd);
+    if (scope) return scope;
+  }
+  for (const a of argsOf(cmd)) {
+    if (a.required && (opts[a.name] === undefined || opts[a.name] === '')) return `missing argument: ${a.name}`;
+    if (a.type === 'number' && opts[a.name] !== undefined && !Number.isFinite(opts[a.name])) return `${a.name} must be a number`;
+    if (a.enum && opts[a.name] !== undefined && !a.enum.includes(opts[a.name])) return `${a.name}: one of ${a.enum.join(', ')}`;
+  }
+  return null;
+}

package/src/core/session.js

@@ -0,0 +1,61 @@
+// A unique agent name per session on one machine, without setting CREW_AGENT_ID by hand.
+// Each Claude Code / Codex session starts its own crew MCP server; the server takes the first free slot
+// (claude@pc, claude@pc-2, ...) with a lock file holding its PID, and frees it on exit.
+// crew task claim pins the name into the task worktree (.crew/agent-id), so CLI calls there use it too.
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+
+export const SLOTS_DIR = join(tmpdir(), 'crew-agents');
+export const PIN_FILE = join('.crew', 'agent-id');
+
+const alive = (pid) => {
+  try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; }
+};
+const slotName = (base, n) => (n === 1 ? base : `${base}-${n}`);
+
+/**
+ * Take the first free slot for base (e.g. claude@pc). A slot is free if it has no lock file or its PID is dead.
+ * → { id, release() } or null when every slot is busy. fs and isAlive are injectable for tests.
+ */
+export function claimSlot(base, { dir = SLOTS_DIR, pid = process.pid, isAlive = alive, max = 20 } = {}) {
+  mkdirSync(dir, { recursive: true });
+  for (let n = 1; n <= max; n++) {
+    const id = slotName(base, n);
+    const file = join(dir, `${id.replace(/[^A-Za-z0-9@._-]/g, '_')}.lock`);
+    if (existsSync(file)) {
+      const owner = Number(readFileSync(file, 'utf8').trim());
+      if (owner && owner !== pid && isAlive(owner)) continue;
+    }
+    try {
+      writeFileSync(file, String(pid), { flag: existsSync(file) ? 'w' : 'wx' });
+    } catch {
+      continue; // another session took it between the check and the write
+    }
+    return {
+      id,
+      release: () => {
+        try { if (Number(readFileSync(file, 'utf8').trim()) === pid) unlinkSync(file); } catch { /* already gone */ }
+      },
+    };
+  }
+  return null;
+}
+
+/** The name pinned in this worktree (nearest .crew/agent-id walking up from cwd), or null. */
+export function pinnedId(cwd = process.cwd()) {
+  let dir = resolve(cwd);
+  for (let i = 0; i < 30; i++) {
+    const f = join(dir, PIN_FILE);
+    if (existsSync(f)) return readFileSync(f, 'utf8').trim() || null;
+    const up = dirname(dir);
+    if (up === dir) return null;
+    dir = up;
+  }
+  return null;
+}
+
+export function pinId(worktree, id) {
+  mkdirSync(join(worktree, '.crew'), { recursive: true });
+  writeFileSync(join(worktree, PIN_FILE), `${id}\n`);
+}

package/src/core/shots.js

@@ -0,0 +1,68 @@
+// Before/after screenshots for tasks that change how the product looks.
+// The executor takes "before" at the start of the task (base code) and "after" when done;
+// `crew pr open` embeds both into the PR so reviewers and humans see the visual change.
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const SHOTS_DIR = '.crew/shots';
+export const PHASES = ['before', 'after'];
+
+/** Files whose change usually changes what users see. */
+const UI_RE = [
+  /^web\//, /^design\//, /^app\//, /^frontend\//, /^ui\//,
+  /\.(css|scss|sass|less|styl|html|htm|vue|svelte|tsx|jsx)$/i,
+];
+export const isUiFile = (p) => {
+  const f = String(p).replace(/\\/g, '/');
+  return !/(^|\/)(tests?|__tests__|e2e)\//.test(f) && !/\.(test|spec)\.[jt]sx?$/.test(f) && UI_RE.some((re) => re.test(f));
+};
+export const uiFiles = (files = []) => files.filter(isUiFile);
+
+/** Screen name: letters, digits, dash. Used as part of a file name. */
+export const NAME_RE = /^[a-z0-9][a-z0-9-]{0,39}$/;
+
+/**
+ * Only plain http(s) URLs without characters a shell could interpret. Rejected on the RAW input
+ * (not after URL encoding): quotes, backtick, $, \, whitespace, < > | ; and % ^ ! (cmd.exe expands
+ * %VAR% even inside double quotes).
+ */
+export function safeUrl(url) {
+  if (/[\s"'`$\\<>|;%^!]/.test(String(url))) return null;
+  try {
+    const u = new URL(String(url));
+    if (!['http:', 'https:'].includes(u.protocol)) return null;
+    const s = u.toString();
+    return /^[A-Za-z0-9:/?#[\]@!$&()*+,;=%._~-]+$/.test(s) && !/[`$"'\\]/.test(s) ? s : null;
+  } catch {
+    return null;
+  }
+}
+
+export const shotPath = (id, name, phase) => `${SHOTS_DIR}/${id}/${name}-${phase}.png`;
+
+/** Playwright CLI command line (run through the shell so npx resolves on Windows). */
+export function captureCommand({ url, file, width = 1280, height = 800 }) {
+  return `npx --yes playwright screenshot --full-page --viewport-size=${Number(width)},${Number(height)} "${url}" "${file}"`;
+}
+
+/** Shots present for a task: { name: { before: path|null, after: path|null } }. */
+export function listShots(root, id) {
+  const dir = join(root, SHOTS_DIR, String(id));
+  const out = {};
+  if (!existsSync(dir)) return out;
+  for (const f of readdirSync(dir)) {
+    const m = /^([a-z0-9][a-z0-9-]*)-(before|after)\.png$/.exec(f);
+    if (!m) continue;
+    (out[m[1]] ??= { before: null, after: null })[m[2]] = `${SHOTS_DIR}/${id}/${f}`;
+  }
+  return out;
+}
+
+/** Markdown section for the PR body. Images are pinned to the head commit so links survive branch deletion. */
+export function shotsSection({ repo, sha, shots }) {
+  const names = Object.keys(shots).sort();
+  if (!names.length) return '';
+  const img = (p) => (p ? `![](https://github.com/${repo}/blob/${sha}/${p}?raw=true)` : '_missing_');
+  const rows = names.map((n) => `| ${n} | ${img(shots[n].before)} | ${img(shots[n].after)} |`);
+  return ['## Before / After', '', '| Screen | Before | After |', '|---|---|---|', ...rows, ''].join('\n');
+}

package/src/core/supervisor.js

@@ -0,0 +1,56 @@
+// Supervisor process for runSupervised (proc.js). Do not import: it is launched as a separate node process.
+// stdin: JSON { cmd, args, shell, cwd, input, timeoutMs } -> stdout: JSON { code, stdout, stderr, timedOut, error }.
+// On timeout it kills the command's whole process tree and exits without waiting for grandchildren to close the pipes.
+import { spawn } from 'node:child_process';
+import { killTree } from './proc.js';
+
+const CAP = 64 * 1024 * 1024;
+
+let raw = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (d) => (raw += d));
+process.stdin.on('end', () => {
+  const job = JSON.parse(raw);
+  const out = { stdout: '', stderr: '' };
+  let timedOut = false;
+  let done = false;
+
+  const finish = (code, error = null) => {
+    if (done) return;
+    done = true;
+    process.stdout.write(JSON.stringify({ code, stdout: out.stdout, stderr: out.stderr, timedOut, error }));
+    process.exit(0);
+  };
+
+  let child;
+  try {
+    child = spawn(job.cmd, job.args ?? [], {
+      cwd: job.cwd ?? undefined,
+      shell: !!job.shell,
+      stdio: [job.input != null ? 'pipe' : 'ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+      detached: process.platform !== 'win32', // own process group, so kill(-pid) kills everyone
+    });
+  } catch (e) {
+    return finish(-1, e.code ?? e.message);
+  }
+  for (const k of ['stdout', 'stderr']) {
+    child[k].setEncoding('utf8');
+    child[k].on('data', (d) => { if (out[k].length < CAP) out[k] += d; });
+  }
+  if (job.input != null) {
+    child.stdin.on('error', () => {}); // the process may have exited without reading stdin
+    child.stdin.end(job.input);
+  }
+  child.on('error', (e) => finish(-1, e.code ?? e.message));
+  child.on('close', (code) => finish(code ?? -1));
+
+  if (job.timeoutMs) {
+    setTimeout(() => {
+      timedOut = true;
+      killTree(child, { graceMs: 2_000 });
+      // Do not wait for close: surviving grandchildren could hold the pipes. Give SIGKILL 3 s and exit.
+      setTimeout(() => finish(-1), 3_000);
+    }, job.timeoutMs);
+  }
+});

package/src/core/version.js

@@ -0,0 +1,44 @@
+// An outdated crew on a member's machine means fixes
+// do not take effect until the person updates their clone. crew compares itself with the latest harness tag.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { HARNESS_ROOT } from './config.js';
+import { run } from './exec.js';
+
+export const LOCAL_VERSION = JSON.parse(readFileSync(join(HARNESS_ROOT, 'package.json'), 'utf8')).version;
+const REPO = 'GredesCerber/agent-crew';
+const CACHE = join(tmpdir(), 'crew-latest.json');
+const TTL_MS = 60 * 60_000;
+
+/** '0.2.10' > '0.2.9' (numbers, not strings). Not a version: null. */
+export function compareVersions(a, b) {
+  const p = (v) => (/^v?(\d+)\.(\d+)\.(\d+)/.exec(String(v ?? '')) ?? []).slice(1).map(Number);
+  const x = p(a);
+  const y = p(b);
+  if (x.length !== 3 || y.length !== 3) return null;
+  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] > y[i] ? 1 : -1;
+  return 0;
+}
+
+/** Latest harness tag (via gh, cached for an hour in tmp). No network/access: null, does not interfere with work. */
+export function latestVersion({ now = Date.now(), fetch = () => run('gh', ['api', `repos/${REPO}/tags`, '--jq', '.[].name'], { allowFail: true }), cache = CACHE } = {}) {
+  try {
+    const c = JSON.parse(readFileSync(cache, 'utf8'));
+    if (now - c.at < TTL_MS && c.latest) return c.latest;
+  } catch { /* no cache */ }
+  const r = fetch();
+  if (r.code !== 0) return null;
+  const tags = r.stdout.split('\n').map((s) => s.trim()).filter((t) => compareVersions(t, '0.0.0') !== null);
+  const latest = tags.sort((a, b) => compareVersions(b, a))[0]?.replace(/^v/, '') ?? null;
+  if (latest) {
+    try { writeFileSync(cache, JSON.stringify({ at: now, latest })); } catch { /* tmp unavailable: no cache */ }
+  }
+  return latest;
+}
+
+/** Advice to update if the local crew is older than the latest tag; otherwise null. */
+export function updateHint({ local = LOCAL_VERSION, latest = latestVersion() } = {}) {
+  if (!latest || compareVersions(local, latest) !== -1) return null;
+  return `crew ${local} is outdated, ${latest} is available: git -C ~/agent-crew fetch --tags && git -C ~/agent-crew checkout v${latest} (fixes do not take effect until you update)`;
+}

package/src/mcp/server.js

@@ -0,0 +1,81 @@
+// Minimal MCP server (stdio, JSON-RPC 2.0, one message per line).
+// Exposes crew commands as tools: crew_task_next, crew_task_claim, crew_check, ...
+// Connects to any MCP client: Claude Code, Codex, Cursor, etc. No dependencies.
+import { claimSlot } from '../core/session.js';
+import { agentId } from '../core/config.js';
+import { createInterface } from 'node:readline';
+import { agentCommands, toolName, inputSchema, validate } from '../core/registry.js';
+import { CrewError, fail } from '../core/output.js';
+import { recordCommand } from '../core/metrics.js';
+
+const SUPPORTED = ['2025-06-18', '2025-03-26', '2024-11-05'];
+
+export async function callTool(name, args = {}) {
+  const cmd = agentCommands.find((c) => toolName(c) === name);
+  if (!cmd) return fail('unknown_tool', `No such tool: ${name}`, { retry: 'tools/list' });
+  const started = Date.now();
+  const err = validate(cmd, args);
+  let result;
+  if (err) result = fail('bad_input', err, { retry: `fix the arguments of ${name}` });
+  else {
+    try {
+      result = await cmd.run(args, {});
+    } catch (e) {
+      result = e instanceof CrewError ? e.toResult() : fail('internal', e.message, { stop_when: 'it repeats: report to a human' });
+    }
+  }
+  // Agents work mostly through MCP; without this crew metrics does not see them. Never throws.
+  recordCommand({ command: cmd.name, opts: args, result, started });
+  return result;
+}
+
+export async function handle(msg) {
+  const { id, method, params } = msg;
+  switch (method) {
+    case 'initialize': {
+      const v = SUPPORTED.includes(params?.protocolVersion) ? params.protocolVersion : SUPPORTED[0];
+      return { protocolVersion: v, capabilities: { tools: {} }, serverInfo: { name: 'crew', version: '0.1.0' } };
+    }
+    case 'ping':
+      return {};
+    case 'tools/list':
+      return {
+        tools: agentCommands.map((c) => ({ name: toolName(c), description: c.summary, inputSchema: inputSchema(c) })),
+      };
+    case 'tools/call': {
+      const result = await callTool(params?.name, params?.arguments ?? {});
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: result.status === 'error' };
+    }
+    default:
+      if (id === undefined) return undefined; // notification (notifications/initialized etc.)
+      throw Object.assign(new Error(`Method not found: ${method}`), { rpcCode: -32601 });
+  }
+}
+
+export function startServer() {
+  // One MCP server per agent session: take a free name slot (claude@pc, claude@pc-2, ...) unless CREW_AGENT_ID is set.
+  if (!process.env.CREW_AGENT_ID) {
+    const slot = claimSlot(agentId());
+    if (slot) {
+      process.env.CREW_AGENT_ID = slot.id;
+      for (const ev of ['exit', 'SIGINT', 'SIGTERM']) process.once(ev, () => { slot.release(); if (ev !== 'exit') process.exit(0); });
+    }
+  }
+  const rl = createInterface({ input: process.stdin });
+  const send = (o) => process.stdout.write(JSON.stringify(o) + '\n');
+  rl.on('line', async (line) => {
+    if (!line.trim()) return;
+    let msg;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      return send({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } });
+    }
+    try {
+      const result = await handle(msg);
+      if (msg.id !== undefined && result !== undefined) send({ jsonrpc: '2.0', id: msg.id, result });
+    } catch (e) {
+      if (msg.id !== undefined) send({ jsonrpc: '2.0', id: msg.id, error: { code: e.rpcCode ?? -32603, message: e.message } });
+    }
+  });
+}

package/templates/labels.json

@@ -0,0 +1,23 @@
+[
+  {"name": "status:needs-spec", "color": "fbca04", "description": "no verifiable acceptance criteria - agents do not take it"},
+  {"name": "status:ready", "color": "0e8a16", "description": "ready, can be taken (crew task next)"},
+  {"name": "status:claimed", "color": "1d76db", "description": "taken by an agent, work in progress (lease)"},
+  {"name": "status:review", "color": "5319e7", "description": "PR open, waiting for review"},
+  {"name": "status:blocked", "color": "b60205", "description": "blocked, a human is needed"},
+  {"name": "status:waiting", "color": "c5def5", "description": "waiting for dependencies (after); crew task promote moves it to ready"},
+  {"name": "status:done", "color": "c2e0c6", "description": "done"},
+  {"name": "tier:low", "color": "f9f9f9", "description": "simple task - a junior model will do"},
+  {"name": "tier:mid", "color": "e4e4e4", "description": "regular task"},
+  {"name": "tier:high", "color": "bfbfbf", "description": "complex - senior model only"},
+  {"name": "risk:low", "color": "c2e0c6", "description": "one agent review, auto-merge"},
+  {"name": "risk:med", "color": "fbca04", "description": "agent review + tests for the criteria, auto-merge"},
+  {"name": "risk:high", "color": "d93f0b", "description": "agent review (security first), merged first by hand, E2E required"},
+  {"name": "priority:high", "color": "b60205", "description": "do first: crew task next hands it out before other tasks of the same owner"},
+  {"name": "priority:low", "color": "d4d4d4", "description": "do last"},
+  {"name": "feedback", "color": "d4c5f9", "description": "human feedback after testing the running app; the product lead triages it regularly"},
+  {"name": "epic", "color": "3e4b9e", "description": "a large scenario made of several tasks"},
+  {"name": "crew:pause", "color": "000000", "description": "EMERGENCY STOP: all agents stop"},
+  {"name": "crew:question", "color": "0052cc", "description": "a question from an agent to the owner of an area (crew ask); answered with crew answer"},
+  {"name": "needs-human", "color": "e99695", "description": "only a human can decide this (scope, contract, product choice)"},
+  {"name": "crew:digest", "color": "bfdadc", "description": "the pinned team status issue, rewritten by crew digest"}
+]

package/templates/mcp.optional.json

@@ -0,0 +1,23 @@
+{
+  "context7": {
+    "enabled": false,
+    "about": "Up-to-date library and API documentation right in the agent's context. Enable this first.",
+    "command": "npx",
+    "args": ["-y", "@upstash/context7-mcp"],
+    "env_from": []
+  },
+  "perplexity": {
+    "enabled": false,
+    "about": "Deep web search for kickoff: the idea, competitors, arguments for the pitch. Key: PERPLEXITY_API_KEY in the environment.",
+    "command": "npx",
+    "args": ["-y", "VERIFY-PACKAGE-NAME-BEFORE-ENABLING"],
+    "env_from": ["PERPLEXITY_API_KEY"]
+  },
+  "playwright": {
+    "enabled": false,
+    "about": "A browser for QA and E2E of the demo path.",
+    "command": "npx",
+    "args": ["-y", "@playwright/mcp"],
+    "env_from": []
+  }
+}