@gredescerber/agent-crew 0.0.0-stage → 0.5.0

package/src/commands/task.js

@@ -0,0 +1,569 @@
+// crew task next | claim | release | status | heartbeat | sweep | promote
+import { basename, join, resolve } from 'node:path';
+import { cpSync, existsSync, readFileSync, realpathSync } from 'node:fs';
+import { ok, warn, fail } from '../core/output.js';
+import { git, run, ghJson } from '../core/exec.js';
+import { loadConfig, agentId } from '../core/config.js';
+import {
+  listIssues, viewIssue, setStatus, comment, marker, currentOwner, parseMarkers, ownerState, safeText,
+  labelValue, tierAllows, slugify, isStale, pauseIssues, PAUSE_LABEL, STATUS, TIERS,
+} from '../core/issues.js';
+import { prQueue, taskOrder } from '../core/queue.js';
+import { updateHint } from '../core/version.js';
+import { DEFAULT_PRD, parsePrd, teamReviewers } from '../core/prd.js';
+
+/** claimed without a claim marker (the label was set by hand): activity is the issue updatedAt or a push to the branch. */
+const isStaleNoOwner = (issue, lastCommitAt, now, leaseMinutes) =>
+  isStale({ issueUpdatedAt: issue.updatedAt, lastCommitAt, now, leaseMinutes });
+
+/**
+ * Local (uncommitted) agent configs from the .gitignore section "# crew: local files":
+ * .mcp.json, .codex/config.toml, .claude/skills/, .claude/agents/, .agents/skills/ …
+ * git worktree does not carry them over, and without them the agent in a task worktree is left without the crew MCP and skills.
+ */
+export function localAgentFiles(root) {
+  const p = join(root, '.gitignore');
+  if (!existsSync(p)) return [];
+  const lines = readFileSync(p, 'utf8').split(/\r?\n/);
+  const start = lines.findIndex((l) => l.trim() === '# crew: local files');
+  if (start < 0) return [];
+  const out = [];
+  for (const l of lines.slice(start + 1)) {
+    const t = l.trim();
+    if (!t || t.startsWith('#')) break;
+    if (t === '.crew/' || t.startsWith('!')) continue;
+    out.push(t.replace(/\/+$/, ''));
+  }
+  return out;
+}
+
+/** Copy the local agent configs from the root into the worktree (overwriting, so they stay fresh). */
+export function syncLocalFiles(root, worktree) {
+  if (samePath(root, worktree)) return [];
+  const copied = [];
+  for (const rel of localAgentFiles(root)) {
+    const src = join(root, rel);
+    if (!existsSync(src)) continue;
+    cpSync(src, join(worktree, rel), { recursive: true, force: true });
+    copied.push(rel);
+  }
+  return copied;
+}
+
+import { taskMarkers } from '../core/guard.js';
+
+/** The "task is not yours" response for release / heartbeat / status. */
+const notOwner = (id, owner, me, cmd) =>
+  fail('not_owner', `#${id} is held by ${owner}, not you (${me})`, {
+    cause_hint: 'wrong task number, or CREW_AGENT differs from the one used at claim',
+    retry: 'crew status — check your task number',
+    stop_when: `this is really needed (a human is clearing a backlog) — ${cmd} --force`,
+  });
+
+/**
+ * Emergency stop in code, not only in the AGENTS.md text: while an issue crew:pause is open,
+ * task next / task claim refuse. Returns fail('paused') or null.
+ */
+export function pauseGuard(issues = listIssues({ label: PAUSE_LABEL })) {
+  const p = pauseIssues(issues);
+  if (!p.length) return null;
+  const refs = p.map((i) => `#${i.number}`).join(', ');
+  return fail('paused', `Emergency stop: issue ${refs} with label ${PAUSE_LABEL} is open`, {
+    cause_hint: `a human stopped all agents: ${p.map((i) => `#${i.number} ${i.title ?? ''}`.trim()).join('; ')}`,
+    retry: 'crew task next — only after a human closes the crew:pause issue',
+    stop_when: 'always — wait until a human closes the crew:pause issue',
+    next_actions: ['finish the current step (crew commit), do not take new tasks', 'stop and wait for the human'],
+    artifacts: { pause_issues: p.map((i) => i.number) },
+  });
+}
+
+/** Date of the last commit on the task branch origin/crew/<id>-* (ISO) or null. Needs a fresh fetch. */
+export function lastBranchCommitAt(id, root) {
+  const r = git(
+    ['for-each-ref', '--sort=-committerdate', '--count=1', '--format=%(committerdate:iso-strict)', `refs/remotes/origin/crew/${id}-*`],
+    { cwd: root, allowFail: true },
+  );
+  return r.code === 0 && r.stdout ? r.stdout.split('\n')[0].trim() : null;
+}
+
+const next = {
+  name: 'task next',
+  summary: 'Hand out the next free task (status:ready) for an area and model tier',
+  args: [
+    { name: 'area', type: 'string', description: 'area: web, api, ... (empty = any)' },
+    { name: 'tier', type: 'string', enum: TIERS, description: 'worker model tier: low takes only simple tasks' },
+    { name: 'tasks_only', type: 'boolean', description: 'tasks only, no PR review or merge (for crew worker)' },
+    { name: 'wait', type: 'number', description: 'no work — wait up to N minutes, checking once a minute (loop in a Codex chat: crew task next --wait 20)' },
+  ],
+  run(opts = {}, deps = {}) {
+    const minutes = Math.max(0, Math.min(Number(opts.wait) || 0, 120));
+    const now = deps.now ?? Date.now;
+    const sleep = deps.sleepSync ?? ((ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms));
+    const until = now() + minutes * 60_000;
+    // Outdated crew on a member machine: fixes do not apply. We tell the human and do not block the task.
+    const hint = deps.updateHint ? deps.updateHint() : deps.config ? null : updateHint();
+    const withHint = (r) => (hint && r.next_actions ? { ...r, next_actions: [...r.next_actions, `tell the human: ${hint}`] } : r);
+    for (;;) {
+      const r = this.once(opts, deps);
+      const idle = r.status === 'warning' && r.artifacts?.idle === true;
+      if (!idle || now() >= until) return withHint(idle && minutes ? { ...r, summary: `${r.summary} (waited ${minutes} min)` } : r);
+      sleep(Math.min(60_000, until - now()));
+    }
+  },
+  once({ area, tier = 'high', tasks_only = false } = {}, deps = {}) {
+    const paused = (deps.pauseGuard ?? pauseGuard)();
+    if (paused) return paused;
+    const { config, root } = deps.config ? { config: deps.config, root: deps.root } : loadConfig();
+    const me = deps.me ?? agentId();
+    const login = deps.login !== undefined ? deps.login : myLogin();
+    const team = deps.team !== undefined ? deps.team : teamFromPrd(root);
+
+    // 1. First unblock the team: merge a ready risk:high PR, do a review.
+    if (!tasks_only) {
+      const prs = deps.prs ?? openPrs(root);
+      const q = prQueue(prs, { me, login, reviewers: teamReviewers(team), config });
+      // My own PR that is waiting on me (fixes, red check, conflict) comes before everything: other tasks are queued behind it.
+      const fix = q.find((x) => x.kind === 'fix' && x.mine);
+      if (fix) {
+        const id = fix.issue ?? '<issue>';
+        return ok(`Your own PR first: #${fix.number} ${fix.title}: ${fix.reason}`, {
+          artifacts: { kind: 'fix', pr: fix.number, issue: fix.issue, reason: fix.reason },
+          next_actions: [
+            `go back to the worktree of task #${id} (lease lost — crew task claim ${id})`,
+            fix.reason === 'conflict with main' ? 'git fetch origin && git merge origin/main — resolve the conflict in your area' : `gh pr view ${fix.number} --comments — what the reviewer asks for / why the check is red`,
+            'crew commit -m "fix: ..." → crew check → crew pr open (pushes to the same PR)',
+            'crew task next',
+          ],
+        });
+      }
+      const merge = q.find((x) => x.kind === 'merge');
+      if (merge) {
+        return ok(`Merge the ready PR #${merge.number} ${merge.title} (${merge.risk}, review and checks are green)`, {
+          artifacts: { kind: 'merge', pr: merge.number, risk: merge.risk },
+          next_actions: [`gh pr merge ${merge.number} --merge --delete-branch`, 'crew task next'],
+        });
+      }
+      const rv = q.find((x) => x.kind === 'review' && x.reviewable);
+      if (rv) {
+        return ok(`Review first: PR #${rv.number} ${rv.title} (${rv.risk}, approvals ${rv.have}/${rv.need}, waiting ${rv.age} min)`, {
+          artifacts: { kind: 'review', pr: rv.number, risk: rv.risk, waiting_min: rv.age },
+          next_actions: [`skill crew-review: gh pr view ${rv.number}, gh pr diff ${rv.number}`, `crew pr review ${rv.number} --verdict approve|changes --note "..."`, 'crew task next'],
+        });
+      }
+    }
+
+    // 2. Tasks: assigned to me (my area from crew-team) → unassigned → other areas.
+    const ready = taskOrder(deps.ready ?? listIssues({ label: 'status:ready' }), { login, area, tier });
+    if (!ready.length) {
+      return warn('No free tasks', {
+        artifacts: { idle: true },
+        next_actions: ['crew task next --wait 20 — wait for work (it checks once a minute)', 'or crew status — see what is blocked'],
+      });
+    }
+    const { issue: t, owners, mine } = ready[0];
+    const whose = mine || !owners.length ? '' : ` — area ${labelValue(t, 'area')}, owner ${owners.join(', ')}: they have no tasks of their own, help them`;
+    return ok(`Next task: #${t.number} ${t.title}${whose}`, {
+      artifacts: { kind: 'task', issue: t.number, area: labelValue(t, 'area'), tier: labelValue(t, 'tier') ?? 'mid', queue: ready.length, mine, owners },
+      next_actions: [`crew task claim ${t.number}`],
+    });
+  },
+};
+
+/** My GitHub login (for tasks assigned to me). No network/gh — null: ordering is just by number. */
+function myLogin() {
+  const r = run('gh', ['api', 'user', '--jq', '.login'], { allowFail: true });
+  return r.code === 0 ? r.stdout.trim() || null : null;
+}
+
+/** The crew-team block from docs/prd.md in the current checkout (the captain publishes the PRD to main during kickoff --apply). */
+function teamFromPrd(root) {
+  const p = join(root ?? '.', DEFAULT_PRD);
+  return existsSync(p) ? parsePrd(readFileSync(p, 'utf8')).team : null;
+}
+
+/** Open PRs with what the queue needs: body (author agent), comments (reviews), checks. */
+function openPrs(root) {
+  return ghJson(['pr', 'list', '--state', 'open', '--limit', '50', '--json', 'number,title,body,headRefOid,createdAt,isDraft,author,labels,comments,statusCheckRollup,mergeable,isCrossRepository,autoMergeRequest'], { cwd: root, allowFail: true }) ?? [];
+}
+
+/**
+ * What to do after claim. A CLI user does cd, while the MCP server lives in the project root —
+ * so the crew_check / crew_commit / crew_pr_open tools must be passed cwd = worktree explicitly.
+ */
+export function claimNextActions(id, worktree) {
+  const cwdJson = JSON.stringify(worktree);
+  return [
+    `cd ${worktree}`,
+    `MCP: pass cwd: ${cwdJson} to every crew_check, crew_commit, crew_pr_open (otherwise they run in the project root, not on the task branch)`,
+    `read the task: gh issue view ${id}`,
+    'tests from the acceptance criteria first, then the implementation',
+    'crew check',
+    'crew commit -m "..." and crew pr open',
+  ];
+}
+
+const claim = {
+  name: 'task claim',
+  summary: 'Claim a task: status:claimed label, lease, branch and worktree',
+  usesCwd: true,
+  args: [
+    { name: 'id', type: 'number', positional: true, required: true, description: 'issue number' },
+    { name: 'no_worktree', type: 'boolean', description: 'do not create a worktree, just a branch in the current folder' },
+  ],
+  run({ id, no_worktree, cwd }) {
+    const paused = pauseGuard();
+    if (paused) return paused;
+    const { config, root } = loadConfig(cwd);
+    const issue = viewIssue(id);
+    const st = labelValue(issue, 'status');
+    if (st !== 'ready') {
+      return fail('not_ready', `#${id} has status ${st ?? 'none'}, cannot be claimed`, {
+        cause_hint: st === 'needs-spec' ? 'the task has no proper acceptance criteria'
+          : st === 'waiting' ? 'the task is waiting on dependencies (after #N) — crew task promote moves it to ready when they close'
+          : 'the task is already claimed or is not ready',
+        retry: 'crew task next',
+        stop_when: '3 conflicts in a row — tell the human',
+      });
+    }
+    const me = agentId();
+    // Tests and code are written by different agents: whoever took the tests task for this task does not take its code.
+    const tm = taskMarkers(issue.body ?? '');
+    if (tm.testsIssue) {
+      const testsIssue = viewIssue(tm.testsIssue);
+      if (parseMarkers(testsIssue?.comments ?? []).some((m) => m.kind === 'claim' && m.agent === me)) {
+        return fail('same_agent_tests', `You wrote the acceptance tests for #${id} (#${tm.testsIssue}) — another agent writes its code`, {
+          cause_hint: 'for risk:high, tests and implementation are done by different agents, otherwise the tests get fitted to the code',
+          retry: 'crew task next',
+          stop_when: 'there are no other agents — a human decides who takes the task',
+        });
+      }
+    }
+    // Dangling owner: the agent crashed between the claim marker and the label change (task is ready but "taken"),
+    // or it is my own old claim. A live foreign owner is left alone; an expired one is cleared.
+    git(['fetch', '--quiet', 'origin', `+refs/heads/crew/${id}-*:refs/remotes/origin/crew/${id}-*`], { cwd: root, allowFail: true });
+    const prev = ownerState(issue.comments ?? [], { lastCommitAt: lastBranchCommitAt(id, root), leaseMinutes: config.lease_minutes });
+    if (prev.owner && prev.owner.agent !== me && !prev.stale) {
+      return fail('claim_conflict', `#${id} is already claimed by ${prev.owner.agent} (activity ${prev.lastActivityAt ?? '?'})`, {
+        cause_hint: 'the task has a live owner — the status label has not been updated yet or the agent is about to set it',
+        retry: 'crew task next',
+        stop_when: `3 conflicts in a row; the task frees itself after ${config.lease_minutes} min without owner activity`,
+      });
+    }
+    if (prev.owner) {
+      const why = prev.owner.agent === me ? 'my previous claim' : `the lease of ${prev.owner.agent} went stale`;
+      comment(id, `${marker('release', { agent: me, at: new Date().toISOString(), of: prev.owner.agent })}\n↩️ Cleared a dangling claim (${why}).`);
+    }
+    const at = new Date().toISOString();
+    comment(id, `${marker('claim', { agent: me, at })}\n🤖 Claimed the task: \`${me}\`. Lease ${config.lease_minutes} min — extended by \`crew check\`, \`crew commit\` and \`crew task heartbeat\`.`);
+    // Race protection: the first claim after the last release wins.
+    const owner = currentOwner(viewIssue(id).comments);
+    if (owner && (owner.agent !== me || owner.at !== at)) {
+      return fail('claim_conflict', `#${id} is already claimed by ${owner.agent}`, {
+        cause_hint: 'two agents claimed the task at the same time, the first one won',
+        retry: 'crew task next',
+        stop_when: '3 conflicts in a row',
+      });
+    }
+    setStatus(id, 'claimed', { from: ['ready'] });
+    run('gh', ['issue', 'edit', String(id), '--add-assignee', '@me'], { allowFail: true });
+
+    let ws;
+    try {
+      ws = prepareWorkspace({ root, id, title: issue.title, no_worktree });
+    } catch (e) {
+      // Rollback: the task must not stay stuck in claimed until sweep (~45 min).
+      comment(id, `${marker('release', { agent: me, at: new Date().toISOString() })}\n↩️ Could not prepare the branch/worktree; the task was returned to the queue.`);
+      setStatus(id, 'ready', { from: ['claimed'] });
+      run('gh', ['issue', 'edit', String(id), '--remove-assignee', '@me'], { allowFail: true });
+      return fail('workspace_failed', `Could not prepare a working copy for #${id}`, {
+        cause_hint: e.recovery?.cause_hint || e.message,
+        retry: 'crew task next',
+        stop_when: 'the same error twice — tell the human (git worktree list, git branch)',
+      });
+    }
+    const next_actions = claimNextActions(id, ws.worktree);
+    if (ws.reused) next_actions.unshift('the branch/worktree remain from a previous attempt — run git status and git log first, continue from what is there');
+    return ok(`Claimed #${id}: ${issue.title}${ws.reused ? ' (continuing a previous attempt)' : ''}`, {
+      artifacts: { issue: id, branch: ws.branch, worktree: ws.worktree, agent: me, reused: ws.reused, local_files: ws.copied ?? [] },
+      next_actions,
+    });
+  },
+};
+
+/**
+ * Branch crew/<id>-* and worktree for a task. Claiming again (after release/timeout) reuses
+ * the existing branch and worktree instead of failing on `git worktree add -b`. Throws CrewError on a git failure.
+ * → { branch, worktree, reused }
+ */
+export function prepareWorkspace({ root, id, title, no_worktree = false }) {
+  git(['fetch', 'origin'], { cwd: root, allowFail: true });
+  const existing = git(['for-each-ref', '--format=%(refname:short)', `refs/heads/crew/${id}-*`], { cwd: root, allowFail: true })
+    .stdout.split('\n').map((s) => s.trim()).filter((b) => b.startsWith(`crew/${id}-`));
+  const branch = existing[0] ?? `crew/${id}-${slugify(title ?? '')}`;
+  const base = git(['rev-parse', '--verify', 'origin/main'], { cwd: root, allowFail: true }).code === 0 ? 'origin/main' : 'HEAD';
+
+  if (no_worktree) {
+    git(existing.length ? ['checkout', branch] : ['checkout', '-b', branch, base], { cwd: root });
+    return { branch, worktree: root, reused: existing.length > 0 };
+  }
+
+  const worktree = resolve(root, '..', `${basename(root)}-wt-${id}`);
+  git(['worktree', 'prune'], { cwd: root, allowFail: true }); // forget worktrees whose folders were deleted
+  const registered = parseWorktrees(git(['worktree', 'list', '--porcelain'], { cwd: root }).stdout);
+  const here = registered.find((w) => samePath(w.path, worktree));
+  if (here) {
+    if (here.branch !== branch) {
+      git(['checkout', branch], { cwd: worktree });
+    }
+    return { branch, worktree, reused: true, copied: syncLocalFiles(root, worktree) };
+  }
+  git(existing.length ? ['worktree', 'add', worktree, branch] : ['worktree', 'add', '-b', branch, worktree, base], { cwd: root });
+  return { branch, worktree, reused: existing.length > 0, copied: syncLocalFiles(root, worktree) };
+}
+
+function parseWorktrees(porcelain) {
+  const list = [];
+  for (const block of porcelain.split(/\r?\n\r?\n/)) {
+    const path = /^worktree (.+)$/m.exec(block)?.[1];
+    if (!path) continue;
+    list.push({ path, branch: /^branch refs\/heads\/(.+)$/m.exec(block)?.[1] ?? null });
+  }
+  return list;
+}
+
+// realpath: on Windows the same path can appear in short (GREDES~1) and full form.
+const samePath = (a, b) => {
+  const real = (p) => { try { return realpathSync.native(p); } catch { return resolve(p); } };
+  const norm = (p) => real(p).replace(/\\/g, '/').replace(/\/+$/, '');
+  return process.platform === 'win32' ? norm(a).toLowerCase() === norm(b).toLowerCase() : norm(a) === norm(b);
+};
+
+/** Return to the queue; dependencies are injected in tests, with no GitHub calls. */
+export function releaseTask({ id, note = '', force = false }, {
+  me = agentId(), view = viewIssue, post = comment, updateStatus = setStatus, execute = run,
+} = {}) {
+  const issue = view(id);
+  if (!force) {
+    const owner = currentOwner(issue?.comments ?? []);
+    if (owner && owner.agent !== me) return notOwner(id, owner.agent, me, `crew task release ${id}`);
+  }
+  post(id, `${marker('release', { agent: me, at: new Date().toISOString() })}\n↩️ The task was returned to the queue. ${safeText(note)}`);
+  updateStatus(id, 'ready', { from: ['claimed', 'blocked'] });
+  // @me in sweep is the Actions bot. The task is free again: we remove its actual assignees.
+  const assignees = (issue?.assignees ?? []).map((a) => a.login).filter(Boolean);
+  if (assignees.length) execute('gh', ['issue', 'edit', String(id), '--remove-assignee', assignees.join(',')], { allowFail: true });
+  return ok(`#${id} is back in the queue`, { next_actions: ['crew task next'] });
+}
+
+const release = {
+  name: 'task release',
+  summary: 'Return a task to the queue (could not cope / not my area)',
+  args: [
+    { name: 'id', type: 'number', positional: true, required: true, description: 'issue number' },
+    { name: 'note', type: 'string', description: 'what I got done and why I am handing it back' },
+    { name: 'force', type: 'boolean', description: 'return someone else task (for humans and sweep)' },
+  ],
+  run: releaseTask,
+};
+
+const status = {
+  name: 'task status',
+  summary: 'Change a task status and leave a handoff (what is done, what is left)',
+  args: [
+    { name: 'id', type: 'number', positional: true, required: true, description: 'issue number' },
+    { name: 'state', type: 'string', positional: true, required: true, enum: STATUS, description: 'new status' },
+    { name: 'note', type: 'string', description: 'handoff: what is done, what is left, where the artifacts are' },
+    { name: 'force', type: 'boolean', description: 'change the status of someone else task (for humans)' },
+  ],
+  run({ id, state, note = '', force = false }) {
+    if (state === 'claimed') {
+      return fail('use_claim', 'Status claimed is set only via crew task claim', {
+        cause_hint: 'a claim is a lease with a marker and a worktree, not just a label',
+        retry: `crew task claim ${id}`,
+      });
+    }
+    const me = agentId();
+    if (!force) {
+      const owner = currentOwner(viewIssue(id)?.comments ?? []);
+      if (owner && owner.agent !== me) return notOwner(id, owner.agent, me, `crew task status ${id} ${state}`);
+    }
+    if (['blocked', 'needs-spec'].includes(state) && !note) {
+      return fail('note_required', `status ${state} requires --note`, {
+        cause_hint: 'without a description the next agent or human will not understand what happened',
+        retry: `crew task status ${id} ${state} --note "..."`,
+      });
+    }
+    setStatus(id, state, { from: STATUS });
+    comment(id, `${marker('status', { agent: me, state, at: new Date().toISOString() })}\n📋 **${state}** — ${safeText(note)}`);
+    return ok(`#${id} → ${state}`, { next_actions: state === 'review' || state === 'done' ? ['crew task next'] : ['crew status'] });
+  },
+};
+
+const heartbeat = {
+  name: 'task heartbeat',
+  summary: 'Extend the task lease (I am still working)',
+  args: [{ name: 'id', type: 'number', positional: true, required: true, description: 'issue number' }],
+  run({ id }) {
+    const me = agentId();
+    const owner = currentOwner(viewIssue(id)?.comments ?? []);
+    if (!owner || owner.agent !== me) {
+      return fail('lease_lost', `#${id} is not your task${owner ? ` — held by ${owner.agent}` : ' — it was returned to the queue'}, nothing to extend`, {
+        retry: `crew task claim ${id} (if it is ready again) or crew task next`,
+        stop_when: 'another agent claimed the task — do not push your branch',
+      });
+    }
+    comment(id, marker('heartbeat', { agent: me, at: new Date().toISOString() }));
+    return ok(`Lease of #${id} extended`);
+  },
+};
+
+const sweep = {
+  name: 'task sweep',
+  summary: 'Return tasks with an expired lease to the queue (for scheduled GitHub Actions)',
+  agent: false,
+  args: [{ name: 'dry_run', type: 'boolean', description: 'show only' }],
+  run({ dry_run }) {
+    const { config, root } = loadConfig();
+    // Pushes to the task branch also count as activity: we fetch only crew/* branches (no noise, no checkout).
+    git(['fetch', '--quiet', 'origin', '+refs/heads/crew/*:refs/remotes/origin/crew/*'], { cwd: root, allowFail: true });
+    const now = Date.now();
+    const stale = [];
+    for (const i of listIssues({ label: 'status:claimed' })) {
+      const full = viewIssue(i.number);
+      // Activity is counted only from owner markers (and pushes to the task branch):
+      // the marker of the loser in a claim_conflict does not extend the winner lease.
+      // Without a claim marker (label set by hand) — by the issue updatedAt.
+      const st = ownerState(full.comments ?? [], { lastCommitAt: lastBranchCommitAt(i.number, root), now, leaseMinutes: config.lease_minutes });
+      const verdict = st.owner ? st.stale : isStaleNoOwner(full, lastBranchCommitAt(i.number, root), now, config.lease_minutes);
+      if (verdict) stale.push(i.number);
+    }
+    if (!dry_run) for (const n of stale) release.run({ id: n, force: true, note: `lease expired (> ${config.lease_minutes} min without activity)` });
+    // Also — waiting → ready for tasks whose dependencies are closed (a safety net for the promote job in crew.yml).
+    const pr = promote.run({ dry_run });
+    const promoted = pr.artifacts?.promoted ?? [];
+    const summary = [
+      stale.length ? `Expired leases: ${stale.length}${dry_run ? ' (dry run)' : ', returned'}` : 'No expired leases',
+      promoted.length ? `to ready: ${promoted.map((n) => `#${n}`).join(', ')}` : null,
+    ].filter(Boolean).join('; ');
+    return ok(summary, { artifacts: { stale, promoted } });
+  },
+};
+
+/** Numbers from the marker <!-- crew:after issues=12,13 --> in the issue body (or null if there is no marker). */
+export function afterIssues(body = '') {
+  const m = parseMarkers([{ body }]).find((x) => x.kind === 'after');
+  if (!m) return null;
+  return String(m.issues ?? '').split(',').map((x) => Number(x)).filter((n) => Number.isInteger(n) && n > 0);
+}
+
+/**
+ * Which waiting tasks to move to ready (pure function).
+ * waiting: [{ number, body }]; stateOf: Map(number → 'OPEN'|'CLOSED').
+ * A dependency missing from the list counts as not closed — we do not unlock blindly.
+ * → { promote: [{ number, after }], wait: [{ number, pending }], no_marker: [number] }
+ */
+export function decidePromotions(waiting = [], stateOf = new Map()) {
+  const out = { promote: [], wait: [], no_marker: [] };
+  for (const i of waiting) {
+    const after = afterIssues(i.body ?? '');
+    if (!after) { out.no_marker.push(i.number); continue; }
+    const pending = after.filter((n) => String(stateOf.get(n) ?? '').toUpperCase() !== 'CLOSED');
+    if (pending.length) out.wait.push({ number: i.number, pending });
+    else out.promote.push({ number: i.number, after });
+  }
+  return out;
+}
+
+const promote = {
+  name: 'task promote',
+  summary: 'Move status:waiting → ready when all dependencies (crew:after) are closed (for GitHub Actions)',
+  agent: false,
+  args: [{ name: 'dry_run', type: 'boolean', description: 'show only' }],
+  run({ dry_run }) {
+    const waiting = ghJson(['issue', 'list', '--state', 'open', '--label', 'status:waiting', '--limit', '500', '--json', 'number,title,body,labels']) ?? [];
+    if (!waiting.length) return ok('No tasks in waiting', { artifacts: { promoted: [], waiting: [] } });
+    const all = ghJson(['issue', 'list', '--state', 'all', '--limit', '1000', '--json', 'number,state']) ?? [];
+    const d = decidePromotions(waiting, new Map(all.map((i) => [i.number, i.state])));
+    if (!dry_run) {
+      for (const p of d.promote) {
+        setStatus(p.number, 'ready', { from: ['waiting'] });
+        comment(p.number, `${marker('status', { agent: agentId(), state: 'ready', at: new Date().toISOString() })}
+🟢 Dependencies closed (${p.after.map((n) => `#${n}`).join(', ')}) — the task is ready to be claimed.`);
+      }
+    }
+    const promoted = d.promote.map((p) => p.number);
+    const artifacts = { promoted, waiting: d.wait, no_marker: d.no_marker };
+    const summary = promoted.length ? `To ready: ${promoted.map((n) => `#${n}`).join(', ')}${dry_run ? ' (dry run)' : ''}` : 'No waiting task is ready yet';
+    return d.no_marker.length
+      ? warn(`${summary}; without a crew:after marker: ${d.no_marker.map((n) => `#${n}`).join(', ')}`, {
+        artifacts,
+        next_actions: ['dependencies of tasks without a marker are unknown — a human moves them to ready by hand (crew task status <id> ready)'],
+      })
+      : ok(summary, { artifacts });
+  },
+};
+
+/** `git worktree list --porcelain` → [{ path, branch, id }] only for task branches crew/<id>-* (unlike parseWorktrees). */
+export function taskWorktrees(porcelain = '') {
+  const out = [];
+  for (const block of porcelain.split(/\r?\n\r?\n/)) {
+    const path = /^worktree (.+)$/m.exec(block)?.[1]?.trim();
+    const branch = /^branch refs\/heads\/(.+)$/m.exec(block)?.[1]?.trim();
+    const id = Number(/^crew\/(\d+)-/.exec(branch ?? '')?.[1]);
+    if (path && branch && id) out.push({ path, branch, id });
+  }
+  return out;
+}
+
+/**
+ * What to delete (pure function). We delete only the folder of a task that is closed, with no uncommitted changes
+ * and no commits missing from origin/main or from the branch on GitHub. Everything else is kept, with the reason.
+ */
+export function planCleanup(worktrees, { issueState, dirty, unsaved }) {
+  return worktrees.map((w) => {
+    const state = issueState(w.id);
+    const why = state !== 'CLOSED' ? `task #${w.id} is still ${state ? state.toLowerCase() : 'not found'}`
+      : dirty(w) ? 'has uncommitted changes'
+        : unsaved(w) ? 'has commits that are neither in main nor on GitHub'
+          : null;
+    return { ...w, remove: !why, why };
+  });
+}
+
+const cleanup = {
+  name: 'task cleanup',
+  summary: 'Remove the folders (worktrees) of closed tasks: with no uncommitted changes and with the work already saved in main or on GitHub',
+  args: [{ name: 'dry_run', type: 'boolean', description: 'show only what would be removed' }],
+  run({ dry_run = false } = {}) {
+    const { root } = loadConfig();
+    git(['fetch', '--quiet', 'origin'], { cwd: root, allowFail: true });
+    const wts = taskWorktrees(git(['worktree', 'list', '--porcelain'], { cwd: root }).stdout);
+    const states = new Map();
+    const plan = planCleanup(wts, {
+      issueState: (id) => {
+        if (!states.has(id)) states.set(id, ghJson(['issue', 'view', String(id), '--json', 'state'], { cwd: root, allowFail: true })?.state ?? null);
+        return states.get(id);
+      },
+      dirty: (w) => git(['status', '--porcelain'], { cwd: w.path, allowFail: true }).stdout.trim() !== '',
+      // branch commits that are neither in origin/main nor in its copy on GitHub (if the branch was not deleted)
+      unsaved: (w) => git(['log', '--oneline', `${w.branch}`, '--not', 'origin/main', '--remotes=origin'], { cwd: root, allowFail: true }).stdout.trim() !== '',
+    });
+    const removed = [];
+    if (!dry_run) {
+      for (const w of plan.filter((p) => p.remove)) {
+        const r = git(['worktree', 'remove', w.path], { cwd: root, allowFail: true });
+        if (r.code !== 0) { w.remove = false; w.why = `git worktree remove: ${(r.stderr || r.stdout).split('\n')[0]}`; continue; }
+        git(['branch', '-D', w.branch], { cwd: root, allowFail: true }); // the work is already in main or on GitHub (checked above)
+        removed.push(w.path);
+      }
+    }
+    const kept = plan.filter((p) => !p.remove).map((p) => `${p.path} — ${p.why}`);
+    const would = plan.filter((p) => p.remove).map((p) => p.path);
+    return ok(dry_run ? `Task folders to remove: ${would.length}, kept: ${kept.length} (dry-run)` : `Task folders removed: ${removed.length}, kept: ${kept.length}`, {
+      artifacts: { removed, would_remove: dry_run ? would : [], kept },
+      next_actions: kept.length ? ['kept ones — see the reason in kept; a human needs to save or discard uncommitted work'] : ['crew task next'],
+    });
+  },
+};
+
+export default [next, claim, release, status, heartbeat, sweep, promote, cleanup];