@hncode/hncode 0.5.1 → 0.5.4

package/src/team/spawn.js

@@ -0,0 +1,305 @@
+// Spawning a teammate and registering it as a background task.
+//
+// This is the equivalent of Claude Code's `spawnInProcessTeammate`: it creates the identity,
+// registers a task so the roster and `TaskList` can see it, and starts the run — without
+// awaiting it, because a teammate that blocks its lead's turn is not a teammate.
+//
+// THE TASK IS THE HANDLE
+// ----------------------
+// The registry is how everything else reaches a running teammate: `TaskList` lists them,
+// `TaskOutput` reads what they have said, `TaskStop` aborts one. Reusing it rather than adding a
+// parallel registry means a teammate shows up wherever background work already does.
+import { createTask, settleTask, appendTaskOutput } from '../agent-task.js';
+import { runAs, makeIdentity } from './context.js';
+import { runTeammate } from './runner.js';
+import { addMember, setMemberActive } from './team.js';
+import { updateMember } from './store.js';
+import { readTeamFile } from './store.js';
+import { TEAMMATE_MAX_STEPS, TEAM_LEAD_NAME } from './constants.js';
+import { requestPermission } from './permission.js';
+import { leadOf } from './team.js';
+
+/**
+ * One line describing what a tool call would do, for the permission prompt.
+ *
+ * A tool NAME tells the person nothing — "Bash" could be `ls` or `rm -rf`. These are the fields Claude
+ * Code checks, in the same order, because they are what the common tools put their intent in.
+ */
+function describeCall(toolName, args) {
+  const a = args && typeof args === 'object' ? args : {};
+  const desc = a.description || a.command || a.prompt || a.query || a.pattern || a.file_path || a.path;
+  if (desc) return String(desc).split('\n')[0].slice(0, 120);
+  return `${toolName} with no description`;
+}
+
+/** Live teammates, by agent id. The abort handle and the running promise. */
+const running = new Map();
+
+/** Every teammate currently running. */
+export function liveTeammates() {
+  return [...running.values()].map((r) => ({ name: r.name, teamName: r.teamName, taskId: r.taskId }));
+}
+
+/** Is a teammate with this name already running on this team? */
+export function isRunning(teamName, name) {
+  return [...running.values()].some((r) => r.teamName === teamName && r.name === name);
+}
+
+/**
+ * Spawn one teammate.
+ *
+ * Returns as soon as it is RUNNING — the promise it hands back resolves when the teammate
+ * finishes, and the caller is expected to not await it. Everything that needs to observe progress
+ * goes through the task registry.
+ */
+export function spawnTeammate({
+  teamName,
+  name,
+  prompt = '',
+  agentType = 'general',
+  model = '',
+  cfg,
+  toolNote,
+  // 0 = the member waits for work indefinitely; see `waitForMail`. The old default made a
+  // teammate quit after two quiet minutes, so a later instruction had nobody to reach.
+  idleTimeoutMs = 0,
+  maxSteps = TEAMMATE_MAX_STEPS,
+  cwd,
+  onEvent,
+  // Called when this teammate sends a message to the lead — that is, to the person using hncode. The
+  // TUI passes one so the text lands in their transcript as it is sent; see `SendMessage` for what went
+  // wrong without it.
+  onLeadMail,
+  tasks,
+  // 'ask' installs the permission round trip (see below). Anything else leaves the member able to
+  // run tools unattended — what a headless spawn wants.
+  permissionMode = '',
+}) {
+  const team = readTeamFile(teamName);
+  if (!team) return { ok: false, error: `no team "${teamName}"` };
+  if (isRunning(teamName, name)) return { ok: false, error: `"${name}" is already running` };
+
+  // Join the roster ONLY if this name is not on it yet.
+  //
+  // `/team add` calls `addMember` itself and THEN calls this spawner, so an unconditional second
+  // `addMember` here ran for a name the roster already held — and for the team's FIRST member
+  // that name IS `leadName`, which `addMember` refuses (`"…" is the lead of this team`). So the
+  // spawn failed and the member stayed a roster row with `taskId: null`: no agent, nothing that
+  // reads its inbox, and no reply to anything sent to it. That is the bug behind "I made a team
+  // and it never answers".
+  //
+  // A name that is already there is REUSED rather than re-added. `addMember` is still the way in
+  // for a caller that has not joined the member yet (the model's TeamCreate tool spawns names
+  // that are already on the roster too, and a direct API use may not be).
+  const existing = team.members.find((m) => m.name === name);
+  let member;
+  if (existing) {
+    member = existing;
+  } else {
+    const added = addMember(teamName, { name, agentType, model, prompt, cwd });
+    if (!added.ok) return { ok: false, error: added.error };
+    member = added.member;
+  }
+
+  // Registered like any other background task, so `TaskList` finds it.
+  // Registered in the CALLER's registry, not a fresh object: a task nothing can see is a
+  // task that never appears in TaskList. `{ tasks: {} }` was that mistake.
+  const registry = tasks || {};
+  const task = createTask({ tasks: registry }, 'teammate', {
+    description: `${name}: ${String(prompt || 'waiting for work').slice(0, 60)}`,
+    teamName,
+    memberName: name,
+    agentId: member.agentId,
+  });
+
+  // The member must point at its task, because `runTeammate` looks the task up BY that id.
+  // Leaving it unset sent the teammate to the unclaimed pool — empty on a fresh team — and it
+  // opened by asking the lead for work.
+  updateMember(teamName, name, { taskId: task.taskId });
+  const identity = makeIdentity({
+    name,
+    teamName,
+    color: member.color,
+    agentType,
+    model,
+  });
+
+  const abort = { aborted: false, listeners: [] };
+  const controller = {
+    abort() { abort.aborted = true; for (const l of abort.listeners) { try { l(); } catch { /* best effort */ } } },
+    get signal() { return abort; },
+  };
+  // TaskStop reaches a teammate through this handle. Without it the task had
+  // neither `_abort` nor `pid`, so a stop settled the task as 'killed' while
+  // the member kept polling its inbox forever.
+  task._abort = () => controller.abort();
+
+  appendTaskOutput(task, `[${name}] started on team "${teamName}"\n`);
+  onEvent && onEvent({ type: 'start', name, teamName, taskId: task.taskId, color: member.color });
+
+  // The run, wrapped in its own async identity. NOT awaited: the lead continues its turn while
+  // the teammate works, and the result arrives as a message.
+  // What this teammate runs ON. The per-member choice wins, then the subagent model, then the
+  // session's — the same order the chooser describes, so the row the user picked is the model
+  // that answers. `cfg.model` is what `new Agent` reads; putting the name only on the identity
+  // made the chooser cosmetic.
+  const runCfg = {
+    ...cfg,
+    model: member.model || cfg.subagentModel || cfg.model,
+    // Carried on the config so the teammate's own `SendMessage` can reach the TUI. This is the
+    // channel that makes a reply appear in the user's transcript the moment it is sent, instead of
+    // waiting for their next turn (see the tool's handler for what went wrong without it).
+    onLeadMail,
+  };
+  let ok = false;
+  const promise = runAs(identity, async () => {
+    try {
+      const result = await runTeammate({
+        teamName,
+        memberName: name,
+        cfg: runCfg,
+        maxSteps,
+        idleTimeoutMs,
+        toolNote: (who, toolName, args) => {
+          appendTaskOutput(task, `[${who}] ${toolName}\n`);
+          toolNote && toolNote(who, toolName, args);
+          onEvent && onEvent({ type: 'tool', name: who, tool: toolName });
+        },
+        shouldStop: () => abort.aborted,
+        onStart: () => onEvent && onEvent({ type: 'working', name }),
+        onFinish: () => onEvent && onEvent({ type: 'idle', name }),
+        // Relay the member's live output upward. The UI decides what to do with it; spawning only
+        // carries it, which keeps the display policy in one place.
+        onStream: (s) => onEvent && onEvent({ type: 'stream', name, stream: s }),
+        // THE PERMISSION ROUND TRIP: the member blocks here until the person answers through the lead's
+        // mailbox, and `requestPermission` polls for the matching `request_id`.
+        //
+        // Only installed when someone can actually answer — a headless spawn has no panel, and blocking
+        // for ten minutes on a question nobody can see would look like a hang.
+        askPermission: permissionMode === 'ask'
+          ? async (toolName, args) => {
+            const lead = leadOf(teamName) || TEAM_LEAD_NAME;
+            const verdict = await requestPermission({
+              teamName,
+              memberName: name,
+              leadName: lead,
+              toolName,
+              description: describeCall(toolName, args),
+              input: args && typeof args === 'object' ? args : {},
+              shouldStop: () => abort.aborted,
+            });
+            onEvent && onEvent({ type: 'permission', name, toolName, approved: verdict.approved });
+            return verdict;
+          }
+          : undefined,
+      });
+      ok = true;
+      appendTaskOutput(task, `[${name}] finished${result.idle ? ' (idle timeout)' : ''}\n`);
+      onEvent && onEvent({ type: 'finish', name, result });
+      return result;
+    } catch (e) {
+      const message = (e && e.message) || String(e);
+      appendTaskOutput(task, `[${name}] failed: ${message}\n`);
+      onEvent && onEvent({ type: 'error', name, error: message });
+      return { ok: false, error: message };
+    } finally {
+      // Settled with the OUTCOME. `settleTask` only touches a task that is still
+      // running, so a stop that already claimed it keeps its own status — but a
+      // teammate that threw was settled as 'completed', which put a green check on
+      // the panel next to a failure log line.
+      settleTask(task, ok ? 'completed' : 'failed');
+      running.delete(member.agentId);
+      setMemberActive(teamName, name, false);
+
+      // The member STAYS on the roster, and its inbox stays on disk.
+      //
+      // This used to call `removeTeammate`, on the reasoning that a finished teammate's name
+      // would make a later SendMessage look deliverable. That got it backwards: the name IS
+      // deliverable, because the member is idle and waiting — `runTeammate` ends its loop only
+      // when the team is stopping it. Removing it instead destroyed the roster entry AND the
+      // inbox (`removeTeammate` clears the mailbox), so an agent that had reported in and was
+      // waiting for an assignment disappeared along with anything it had said. That is why a
+      // team of four came back as one lead with no members and no mail.
+      //
+      // A member is taken off the roster by an explicit act: `TeamDelete`, `disbandTeam`, or
+      // the user's `/team remove`.
+    }
+  });
+
+  running.set(member.agentId, {
+    name,
+    teamName,
+    taskId: task.taskId,
+    controller,
+    promise,
+    color: member.color,
+  });
+
+  return { ok: true, member, taskId: task.taskId, promise, controller };
+}
+
+/**
+ * Spawn several, tolerating individual failures.
+ *
+ * One bad name must not stop the rest: a lead that asked for four members and got one is worse
+ * off than one that got three and was told which failed.
+ */
+export function spawnMany(teamName, members, opts) {
+  const started = [];
+  const failed = [];
+  for (const m of members) {
+    const r = spawnTeammate({
+      teamName, cwd: opts.cwd, cfg: opts.cfg, toolNote: opts.toolNote, onEvent: opts.onEvent,
+      onLeadMail: opts.onLeadMail,
+      // Carried through from the caller. `ask` installs the permission round trip; anything else leaves
+      // the member able to run tools unattended, which is what a headless spawn wants.
+      permissionMode: opts.permissionMode,
+      ...m,
+    });
+    if (r.ok) started.push({ name: m.name, taskId: r.taskId });
+    else failed.push({ name: m.name, error: r.error });
+  }
+  return { started, failed };
+}
+
+/** Stop a teammate by name. Returns false when nothing was running under it. */
+export function stopTeammate(teamName, name) {
+  for (const [id, r] of running) {
+    if (r.teamName === teamName && r.name === name) {
+      r.controller.abort();
+      running.delete(id);
+      return true;
+    }
+  }
+  return false;
+}
+
+/** Stop every teammate on a team. Used when the team is dissolved. */
+export function stopTeam(teamName) {
+  let n = 0;
+  for (const [id, r] of running) {
+    if (r.teamName !== teamName) continue;
+    r.controller.abort();
+    running.delete(id);
+    n++;
+  }
+  return n;
+}
+
+/**
+ * Wait for every teammate on a team to finish.
+ *
+ * Bounded, because a teammate that is idle-waiting will not finish on its own — the lead asking
+ * "are they done" must get an answer even if the answer is "no".
+ */
+export async function waitForTeam(teamName, timeoutMs = 60_000) {
+  const mine = [...running.values()].filter((r) => r.teamName === teamName);
+  if (!mine.length) return { done: 0, pending: 0 };
+  const all = Promise.allSettled(mine.map((r) => r.promise));
+  const raced = await Promise.race([
+    all.then(() => true),
+    new Promise((r) => setTimeout(() => r(false), timeoutMs)),
+  ]);
+  const pending = [...running.values()].filter((r) => r.teamName === teamName).length;
+  return { done: raced ? mine.length : mine.length - pending, pending, timedOut: !raced };
+}

package/src/team/store.js

@@ -0,0 +1,172 @@
+// Where a team lives on disk.
+//
+//   ~/.hncode/teams/<team>/config.json         the roster (TeamFile)
+//   ~/.hncode/teams/<team>/inboxes/<name>.json  one inbox per member
+//   ~/.hncode/tasks/<team>/                     the shared task list
+//
+// WHY FILES RATHER THAN MEMORY
+// ----------------------------
+// Every member runs in the same process, so a Map would be simpler — and would be wrong. The
+// roster has to survive the session that created it (a teammate outlives the turn that spawned
+// it, and `--continue` must find the team again), and the mailbox is the ONE channel members
+// share. Keeping both on disk means a member written to by another is never holding a stale
+// copy, and a crashed session leaves something a person can read.
+//
+// The layout mirrors Claude Code's (`~/.claude/teams/...`), so the mental model transfers and a
+// reader of either project recognises the other.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/** The per-user directory. Resolved per call so a test can redirect it after import. */
+function homeDir() {
+  return process.env.HNCODE_HOME || os.homedir();
+}
+
+export function teamsRoot() {
+  return path.join(homeDir(), '.hncode', 'teams');
+}
+
+export function tasksRoot() {
+  return path.join(homeDir(), '.hncode', 'tasks');
+}
+
+// A team name becomes a directory name, so it cannot be trusted as-is: `../` would escape the
+// teams directory, and a name with a slash would place the files somewhere else entirely.
+export function sanitizeName(name) {
+  return String(name == null ? '' : name).replace(/[^a-zA-Z0-9]/g, '-').toLowerCase();
+}
+
+export function teamDir(teamName) {
+  return path.join(teamsRoot(), sanitizeName(teamName));
+}
+
+export function teamFilePath(teamName) {
+  return path.join(teamDir(teamName), 'config.json');
+}
+
+export function inboxDir(teamName) {
+  return path.join(teamDir(teamName), 'inboxes');
+}
+
+export function inboxPath(teamName, agentName) {
+  return path.join(inboxDir(teamName), `${sanitizeName(agentName)}.json`);
+}
+
+export function teamTasksDir(teamName) {
+  return path.join(tasksRoot(), sanitizeName(teamName));
+}
+
+/** Every team on disk, newest first. Never throws. */
+export function listTeams() {
+  let entries;
+  try {
+    entries = fs.readdirSync(teamsRoot(), { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    const file = path.join(teamsRoot(), e.name, 'config.json');
+    try {
+      out.push(JSON.parse(fs.readFileSync(file, 'utf8')));
+    } catch { /* a half-written or removed team is skipped, not fatal */ }
+  }
+  return out.sort((a, b) => (b.createdAt || 0) - (a.createdAt || 0));
+}
+
+/** The roster, or null. Never throws.
+ *
+ *  Cached by (mtimeMs, size): the team panel renders this on EVERY frame, and a
+ *  readFileSync + JSON.parse per frame sat in the hottest path there is. A stat
+ *  per frame replaces the full read; any write (tmp+rename) changes the mtime,
+ *  so nothing stale survives. */
+let _teamCache = { key: '', team: null };
+export function readTeamFile(teamName) {
+  const file = teamFilePath(teamName);
+  let st = null;
+  try { st = fs.statSync(file); } catch { /* absent */ }
+  if (!st) return null;
+  const key = `${file}:${st.mtimeMs}:${st.size}`;
+  if (_teamCache.key === key) return _teamCache.team;
+  try {
+    const team = JSON.parse(fs.readFileSync(file, 'utf8'));
+    _teamCache = { key, team };
+    return team;
+  } catch {
+    _teamCache = { key: '', team: null };
+    return null;
+  }
+}
+
+/** Write the roster, creating the directory. Throws only on a real IO failure.
+ *
+ *  Atomic (tmp + rename), like every other team write: a plain writeFileSync
+ *  dying mid-write left a truncated config.json, and readTeamFile then returned
+ *  null — the whole team silently disappeared. */
+export function writeTeamFile(teamName, teamFile) {
+  fs.mkdirSync(teamDir(teamName), { recursive: true });
+  const target = teamFilePath(teamName);
+  const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(teamFile, null, 2), 'utf8');
+  try {
+    fs.renameSync(tmp, target);
+  } catch (e) {
+    try { fs.unlinkSync(tmp); } catch { /* nothing more to do */ }
+    throw e;
+  }
+  return teamFile;
+}
+
+/**
+ * Update one member, read-modify-write.
+ *
+ * Not a cached object: two members can be updated in the same tick (one goes idle while another
+ * starts), and a write from a borrowed copy would lose whichever change came first.
+ */
+export function updateMember(teamName, memberName, patch) {
+  const team = readTeamFile(teamName);
+  if (!team) return false;
+  const i = team.members.findIndex((m) => m.name === memberName);
+  if (i < 0) return false;
+  team.members[i] = { ...team.members[i], ...patch };
+  writeTeamFile(teamName, team);
+  return true;
+}
+
+/** Remove a member. Returns false when the team or the member is unknown. */
+export function removeMember(teamName, memberName) {
+  const team = readTeamFile(teamName);
+  if (!team) return false;
+  const before = team.members.length;
+  team.members = team.members.filter((m) => m.name !== memberName);
+  if (team.members.length === before) return false;
+  writeTeamFile(teamName, team);
+  return true;
+}
+
+/** Delete a team and its inboxes. The shared task list is left alone unless asked. */
+export function deleteTeam(teamName, { tasks = true } = {}) {
+  const remove = (p) => { try { fs.rmSync(p, { recursive: true, force: true }); return true; } catch { return false; } };
+  const ok = remove(teamDir(teamName));
+  if (tasks) remove(teamTasksDir(teamName));
+  return ok;
+}
+
+/**
+ * The id every teammate is addressed by: `<name>@<team>`.
+ *
+ * Deterministic on purpose — `team-lead@my-team` is derivable without asking, so a member that
+ * only knows the team name can still address the lead, and a teammate spawned twice under the
+ * same name does not accumulate two identities.
+ */
+export function formatAgentId(name, teamName) {
+  return `${sanitizeName(name)}@${sanitizeName(teamName)}`;
+}
+
+/** The name half of an agent id, or the id itself when it has no team. */
+export function agentNameOf(agentId) {
+  const at = String(agentId || '').indexOf('@');
+  return at < 0 ? String(agentId || '') : String(agentId).slice(0, at);
+}

package/src/team/tasks.js

@@ -0,0 +1,177 @@
+// The shared task list. One file per team, read and written by every member.
+//
+//   ~/.hncode/tasks/<team>/tasks.json   ->  Task[]
+//
+// WHY A SINGLE FILE RATHER THAN ONE PER TASK
+// ------------------------------------------
+// The list is what members read to decide what to do next: "is anything unclaimed", "am I
+// blocking someone". That question spans the whole list, so keeping it in one file makes the
+// common read a single parse instead of a directory walk with a parse per entry. A team's list
+// is small (tens of entries); it is not a work queue with thousands of items.
+//
+// CLAIMING IS A COMPARE-AND-SWAP
+// ------------------------------
+// Two members polling at the same moment must not both take the same task. The claim re-reads
+// the file, checks the owner is still unset, and only then writes — and because the write is a
+// temp-file rename (see mailbox.js), the loser's write is the one that sees the winner's.
+import fs from 'node:fs';
+import path from 'node:path';
+import { teamTasksDir } from './store.js';
+
+export const TASK_STATES = ['pending', 'in_progress', 'completed', 'blocked', 'cancelled'];
+
+function tasksFile(teamName) {
+  return path.join(teamTasksDir(teamName), 'tasks.json');
+}
+
+function writeAtomic(file, text) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tmp, text, 'utf8');
+  try {
+    fs.renameSync(tmp, file);
+  } catch (e) {
+    try { fs.unlinkSync(tmp); } catch { /* nothing to salvage */ }
+    throw e;
+  }
+}
+
+/** Every task, oldest first. Never throws. */
+// Cached by (mtimeMs, size) — the team panel reads the task list every frame,
+// and a stat per read replaces the full readFileSync + JSON.parse. writeTasks
+// goes through writeAtomic (rename), which always changes the mtime.
+let _tasksCache = { key: '', tasks: null };
+export function readTasks(teamName) {
+  const file = tasksFile(teamName);
+  let st = null;
+  try { st = fs.statSync(file); } catch { /* absent */ }
+  if (!st) return [];
+  const key = `${st.mtimeMs}:${st.size}`;
+  if (_tasksCache.key === key) return _tasksCache.tasks.slice();
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    const tasks = Array.isArray(parsed) ? parsed : [];
+    _tasksCache = { key, tasks };
+    return tasks.slice();
+  } catch {
+    _tasksCache = { key: '', tasks: null };
+    return [];
+  }
+}
+
+function writeTasks(teamName, tasks) {
+  writeAtomic(tasksFile(teamName), JSON.stringify(tasks, null, 2));
+  return tasks;
+}
+
+/** The next id, derived from what is already there so a restart cannot reuse one. */
+function nextId(tasks) {
+  let max = 0;
+  for (const t of tasks) {
+    const n = Number(String(t.id || '').replace(/^#/, ''));
+    if (Number.isFinite(n) && n > max) max = n;
+  }
+  return `#${max + 1}`;
+}
+
+/**
+ * Add a task and return it.
+ *
+ * `blockedBy` names other task ids. Kept as plain ids rather than resolved objects so a task can
+ * reference one that is not created yet — which is how a plan is written down in order.
+ */
+export function createTask(teamName, { subject, description = '', owner = null, blockedBy = [], createdBy = '' }) {
+  const tasks = readTasks(teamName);
+  const task = {
+    id: nextId(tasks),
+    subject: String(subject || '').trim() || '(untitled)',
+    description: String(description || ''),
+    status: 'pending',
+    owner: owner || null,
+    blockedBy: Array.isArray(blockedBy) ? blockedBy.map(String) : [],
+    createdBy: String(createdBy || ''),
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+  };
+  tasks.push(task);
+  writeTasks(teamName, tasks);
+  return task;
+}
+
+/** Update fields on a task. Returns the updated task, or null when the id is unknown. */
+export function updateTask(teamName, id, patch) {
+  const tasks = readTasks(teamName);
+  const i = tasks.findIndex((t) => t.id === id);
+  if (i < 0) return null;
+  const next = { ...tasks[i], ...patch, updatedAt: Date.now() };
+  if (patch.status && !TASK_STATES.includes(patch.status)) return null;
+  tasks[i] = next;
+  writeTasks(teamName, tasks);
+  return next;
+}
+
+/**
+ * Take a task, but only if nobody else has.
+ *
+ * Returns `{ ok: true, task }` on success, or `{ ok: false, reason }` naming what stopped it —
+ * a caller that cannot say WHY a claim failed leaves the model guessing between "someone beat
+ * me to it" and "that task does not exist", and the two need different next actions.
+ */
+export function claimTask(teamName, id, agentName) {
+  const tasks = readTasks(teamName);
+  const i = tasks.findIndex((t) => t.id === id);
+  if (i < 0) return { ok: false, reason: `no task ${id}` };
+
+  const t = tasks[i];
+  if (t.status === 'completed') return { ok: false, reason: `${id} is already completed` };
+  if (t.status === 'cancelled') return { ok: false, reason: `${id} was cancelled` };
+  if (t.owner && t.owner !== agentName) return { ok: false, reason: `${id} is already owned by ${t.owner}` };
+
+  // Blocked by another task that is not done. The dependency is the point of writing it down.
+  const blocking = (t.blockedBy || []).filter((dep) => {
+    const d = tasks.find((x) => x.id === dep);
+    return d && d.status !== 'completed' && d.status !== 'cancelled';
+  });
+  if (blocking.length) return { ok: false, reason: `${id} is blocked by ${blocking.join(', ')}` };
+
+  tasks[i] = { ...t, owner: agentName, status: 'in_progress', updatedAt: Date.now() };
+  writeTasks(teamName, tasks);
+  return { ok: true, task: tasks[i] };
+}
+
+/** Release a task back to the pool, keeping its history. */
+export function releaseTask(teamName, id, agentName) {
+  const t = readTasks(teamName).find((x) => x.id === id);
+  if (!t) return { ok: false, reason: `no task ${id}` };
+  if (t.owner && t.owner !== agentName) return { ok: false, reason: `${id} is owned by ${t.owner}, not ${agentName}` };
+  return { ok: true, task: updateTask(teamName, id, { owner: null, status: 'pending' }) };
+}
+
+/** The tasks nobody has taken, in order. */
+export function unclaimedTasks(teamName) {
+  return readTasks(teamName).filter((t) => !t.owner && t.status === 'pending');
+}
+
+/**
+ * The list as a model should read it.
+ *
+ * Compact and aligned rather than JSON: this goes into a prompt on every step, and the model
+ * needs the id, the state and the subject — not the timestamps or the creator.
+ */
+export function formatTasks(tasks) {
+  if (!tasks.length) return 'No tasks.';
+  const w = Math.max(...tasks.map((t) => t.id.length));
+  return tasks.map((t) => {
+    const owner = t.owner ? ` @${t.owner}` : '';
+    const blocked = (t.blockedBy || []).length ? ` (blocked by ${t.blockedBy.join(', ')})` : '';
+    return `${t.id.padEnd(w)}  ${t.status.padEnd(11)} ${t.subject}${owner}${blocked}`;
+  }).join('\n');
+}
+
+/** Counts per state, for a one-line summary. */
+export function taskSummary(tasks) {
+  const out = {};
+  for (const s of TASK_STATES) out[s] = 0;
+  for (const t of tasks) if (t.status in out) out[t.status]++;
+  return out;
+}