@fradser/pi-agent-teams 0.10.0 → 1.0.0

package/src/state.ts

@@ -1,23 +1,46 @@
+import { isTaskReplaced } from "@fradser/pi-tasks";
 /**
  * Team state management for the current session only: the teammate roster,
- * the in-memory task board, and the single leader inbox. The leader process
- * is the sole writer of this snapshot and of board.json.
+ * the in-memory task storage, and the single leader inbox. The leader process
+ * is the sole writer of this snapshot and of tasks.json.
  */
 
-import { randomUUID } from "node:crypto";
+import { nonEmpty } from "@fradser/pi-kit";
 import {
   messageTitle,
   TEAM_RUNTIME_VERSION,
-  type BoardTask,
-  type WorkerAssignment,
   type MailboxMessage,
-  type TaskIntent,
-  type Teammate,
   type TeamState,
   type WorkerReportEvent,
-  type WorkerUsage,
 } from "./types.ts";
-import { nonEmpty } from "@fradser/pi-kit";
+// The roster — one child process per entry, its lifecycle, and the revisions that
+// say when it changed — is an execution fact, so it lives in @fradser/pi-subagents
+// with the spawner that creates those processes. This module keeps the snapshot,
+// the leader inbox, and the tasks callback, and points `agents` at the roster's
+// own map by identity so no snapshot schema changes and no version bump is needed.
+import {
+  assignAgent,
+  getAgent,
+  livingAgents,
+  agents as roster,
+  progressRevision as rosterProgressRevision,
+  resetRoster,
+  rosterRevision as currentRosterRevision,
+  type Agent,
+} from "@fradser/pi-subagents";
+// The Work Item graph and resource rules are pure and live in @fradser/pi-tasks, so the
+// leader, the worker, and any tasks-only consumer share one implementation.
+// `activeAssignmentConflict` below is the roster-backed policy on top of
+// `resourcesConflict`, and stays here because it reads the roster.
+import {
+  bindTask,
+  configureTaskStore,
+  createTask,
+  discardTask,
+  resourcesConflict,
+  tasks as storedTasks,
+  type WorkAssignment as WorkerAssignment,
+} from "@fradser/pi-tasks";
 
 export const MAX_LEADER_MAILBOX_MESSAGES = 4096;
 /** Total mailbox body bytes retained for forensics. A count cap alone lets a few
@@ -27,13 +50,12 @@ export const MAX_LEADER_MAILBOX_BYTES = 8 * 1024 * 1024;
 export const MAX_PEER_DELIVERED_IDS = 512;
 /** Bounded forensic routing history; mailbox files retain the full peer transcript. */
 export const MAX_PEER_DELIVERY_STATES = 4096;
-export const MAX_TASK_DEPENDENCIES = 32;
 
 function emptyState(): TeamState {
   return {
     runtimeVersion: TEAM_RUNTIME_VERSION,
-    teammates: {},
-    tasks: emptyTaskMap(),
+    agents: roster,
+    tasks: storedTasks,
     leaderMailbox: [],
     messageCounter: 0,
     workerEventOffsets: {},
@@ -50,198 +72,98 @@ function nextMessageId(): string {
   return `msg_${++state.messageCounter}`;
 }
 
-/** Task maps must not inherit Object.prototype: slug ids like "constructor"
- *  are legal task ids and must never alias inherited properties. */
-function emptyTaskMap(): Record<string, BoardTask> {
-  return Object.create(null);
-}
-
 export function resetState(): void {
+  for (const id of Object.keys(storedTasks)) delete storedTasks[id];
+  resetRoster();
   state = emptyState();
-  rosterRevisionCounter++;
-  boardRevisionCounter++;
+  tasksRevisionCounter++;
   stateRevisionCounter++;
 }
 
 // ── Persistence revisions ────────────────────────────────────────
 // state.ts owns every in-memory mutation, so it is the one place that can say
 // exactly which artifact changed. Stream progress is counted separately: a
-// running teammate must not force the roster, the board, or the debug snapshot
+// running teammate must not force the roster, the tasks, or the debug snapshot
 // to be rewritten on every token. Every persisted mutation in this module bumps
 // one of these counters, so a mutation that forgets to bump would not be written
 // until something else changed — add the bump with any new mutator.
 let stateRevisionCounter = 0;
-let rosterRevisionCounter = 0;
-let boardRevisionCounter = 0;
-let progressRevisionCounter = 0;
-
-/** Revision of the whole snapshot: roster, board, mailbox, and offsets. */
+let tasksRevisionCounter = 0;
+
+/** Revision of the whole snapshot: roster, tasks, mailbox, and offsets.
+ *
+ * Composed rather than single-sourced, because the roster now has its own counter
+ * in another package. Every input is monotonic, so the sum changes whenever any
+ * of them does, which is the only property the snapshot writer relies on: it
+ * compares against the last written value and rewrites on inequality. */
 export function stateRevision(): number {
-  return stateRevisionCounter;
+  return stateRevisionCounter + currentRosterRevision() + tasksRevisionCounter;
 }
 
-/** Revision of the worker-readable roster. */
-export function rosterRevision(): number {
-  return rosterRevisionCounter;
-}
+/** Revision of the worker-readable roster, owned by @fradser/pi-subagents. */
+export { currentRosterRevision as rosterRevision };
 
-/** Revision of the persisted board. */
-export function boardRevision(): number {
-  return boardRevisionCounter;
+/** Revision of the persisted tasks. */
+export function tasksRevision(): number {
+  return tasksRevisionCounter;
 }
 
 /** Revision of streamed progress only; never persisted on its own. */
-export function progressRevision(): number {
-  return progressRevisionCounter;
-}
+export { rosterProgressRevision as progressRevision };
 
-/** Record a board change made outside this module's task mutators. */
-export function markBoardChanged(): void {
-  boardRevisionCounter++;
+/** Record a task set change made outside this module's task mutators. */
+export function markTasksChanged(): void {
+  tasksRevisionCounter++;
   stateRevisionCounter++;
 }
 
-// ── Team default model ──────────────────────────────────────
+/** Drop per-spawn replay metadata once its final snapshot was persisted.
+ *  Snapshot bookkeeping rather than roster state, so it stays here even though
+ *  the roster itself moved. */
+export function clearWorkerRunEvents(workerName: string, spawnId: string): void {
+  const outboxKey = `${workerName}:${spawnId}`;
+  delete state.workerEventOffsets[outboxKey];
+  for (const id of Object.keys(state.workerEventIds)) {
+    if (id.startsWith(`${spawnId}:`)) delete state.workerEventIds[id];
+  }
+}
+
+// ── Session settings ─────────────────────────────────────────────
 
-/** The unified teammate model for this session, or undefined when Pi picks. */
+/** The unified model for later spawns, or undefined when Pi picks.
+ *
+ * Deliberately session state rather than roster state: it is a setting the
+ * snapshot persists for forensics and resume, so moving it with the roster would
+ * have given the roster a second source of truth that no snapshot records. The
+ * spawner reads it through the re-export below. */
 export function getTeamDefaultModel(): string | undefined {
   return state.defaultModel;
 }
 
-/** Set (or clear with undefined) the unified teammate model for later spawns. */
+/** Set (or clear with undefined) the unified model for later spawns. */
 export function setTeamDefaultModel(ref: string | undefined): void {
   state.defaultModel = nonEmpty(ref);
   stateRevisionCounter++;
 }
 
-// ── Roster queries ────────────────────────────────────────────────
-
-const NAME_PATTERN = /^[a-z][a-z0-9._-]{0,63}$/i;
-
-export function isValidTeammateName(name: string): boolean {
-  return NAME_PATTERN.test(name);
-}
-
-export function getTeammate(name: string): Teammate | undefined {
-  return state.teammates[name];
-}
-
-export function listTeammates(): Teammate[] {
-  return Object.values(state.teammates).sort((a, b) => a.createdAt - b.createdAt);
-}
-
-export function livingTeammates(): Teammate[] {
-  return listTeammates().filter((t) => t.status !== "stopped");
-}
-
-export function idleTeammates(): Teammate[] {
-  return livingTeammates().filter((t) => t.status === "idle");
-}
-
-export function registerTeammate(teammate: Teammate): { ok: true } | { ok: false; error: string } {
-  if (!isValidTeammateName(teammate.name)) {
-    return { ok: false, error: `Invalid teammate name "${teammate.name}". Use letters, digits, dots, dashes, underscores.` };
-  }
-  if (livingTeammates().some((t) => t.name === teammate.name)) {
-    return { ok: false, error: `A living teammate named "${teammate.name}" already exists.` };
-  }
-  state.teammates[teammate.name] = teammate;
-  rosterRevisionCounter++;
-  stateRevisionCounter++;
-  return { ok: true };
-}
-
-/** Fields whose change is stream progress rather than persisted state. A
- *  progress tick must not republish the roster or the board. */
-const VOLATILE_TEAMMATE_FIELDS = new Set<string>([
-  "liveText",
-  "liveThinking",
-  "activeTool",
-  "turns",
-  "sequenceEnded",
-  "modelOutputSeen",
-  "usage",
-  "lastOutputAt",
-  "updatedAt",
-  "lastNoticeAt",
-  "noticedTaskIds",
-]);
-
-export function updateTeammate(name: string, patch: Partial<Teammate>): Teammate | undefined {
-  const teammate = state.teammates[name];
-  if (!teammate) return undefined;
-  const changed = (Object.keys(patch) as Array<keyof Teammate>)
-    .filter((field) => !Object.is(teammate[field], patch[field]));
-  Object.assign(teammate, patch, { updatedAt: Date.now() });
-  if (patch.status === "stopped") teammate.stoppedAt = Date.now();
-  // Republishing a roster that only streamed progress is pure write churn.
-  if (changed.some((field) => !VOLATILE_TEAMMATE_FIELDS.has(field as string))) {
-    rosterRevisionCounter++;
-    stateRevisionCounter++;
-  } else if (changed.length > 0) {
-    progressRevisionCounter++;
-  }
-  return teammate;
-}
-
-/** Merge streaming child-process progress into a living teammate. */
-export function assignTeammate(
-  name: string,
-  assignment: WorkerAssignment | undefined,
-  currentTaskId?: string,
-): Teammate | undefined {
-  const teammate = getTeammate(name);
-  if (!teammate) return undefined;
-  const lastAssignment = assignment ?? teammate.assignment ?? teammate.lastAssignment;
-  const lastTaskId = currentTaskId ?? teammate.currentTaskId ?? teammate.lastTaskId;
-  return updateTeammate(name, { assignment, currentTaskId, lastAssignment, lastTaskId,
-    ...(assignment && assignment.id !== teammate.assignment?.id ? { reportSequenceEnded: false } : {}),
-  });
-}
-
-export function updateTeammateProgress(
-  name: string,
-  spawnId: string,
-  progress: Pick<Teammate, "liveText" | "activeTool" | "liveThinking" | "turns"> & {
-    sequenceEnded?: boolean;
-    modelOutputSeen?: boolean;
-    usage?: WorkerUsage;
-  },
-): boolean {
-  const teammate = state.teammates[name];
-  if (!teammate || teammate.spawnId !== spawnId) return false;
-  const changed = teammate.liveText !== progress.liveText
-    || teammate.activeTool !== progress.activeTool
-    || teammate.liveThinking !== progress.liveThinking
-    || teammate.turns !== progress.turns
-    || (progress.sequenceEnded !== undefined && teammate.sequenceEnded !== progress.sequenceEnded)
-    || (progress.modelOutputSeen === true && teammate.modelOutputSeen !== true);
-  teammate.liveText = progress.liveText;
-  teammate.activeTool = progress.activeTool;
-  teammate.liveThinking = progress.liveThinking;
-  teammate.turns = progress.turns;
-  if (progress.sequenceEnded !== undefined) teammate.sequenceEnded = progress.sequenceEnded;
-  if (progress.modelOutputSeen) teammate.modelOutputSeen = true;
-  if (progress.usage) teammate.usage = progress.usage;
-  if (teammate.status === "starting") {
-    teammate.status = progress.sequenceEnded ? "idle" : "working";
-    // A status transition is roster state, not stream noise.
-    rosterRevisionCounter++;
-    stateRevisionCounter++;
-  }
-  teammate.updatedAt = Date.now();
-  if (changed) progressRevisionCounter++;
-  return true;
-}
-
-/** Drop per-spawn replay metadata once its final snapshot was persisted. */
-export function clearWorkerRunEvents(workerName: string, spawnId: string): void {
-  const outboxKey = `${workerName}:${spawnId}`;
-  delete state.workerEventOffsets[outboxKey];
-  for (const id of Object.keys(state.workerEventIds)) {
-    if (id.startsWith(`${spawnId}:`)) delete state.workerEventIds[id];
-  }
-}
+// ── Roster (owned by @fradser/pi-subagents) ───────────────────────
+//
+// A child process is an execution fact, so the roster lives with the spawner.
+// Re-exported here because the coordination vocabulary reads this module as its
+// entry point, and every existing consumer imports it from here.
+
+export {
+  assignAgent,
+  getAgent,
+  idleAgents,
+  isValidAgentName,
+  listAgents,
+  livingAgents,
+  registerAgent,
+  updateAgent,
+  updateAgentProgress,
+  agents,
+} from "@fradser/pi-subagents";
 
 /** Drop the oldest mailbox entries until both the count and byte caps hold. */
 function trimLeaderMailbox(): void {
@@ -268,7 +190,7 @@ export function deliverToLeader(msg: Omit<MailboxMessage, "id" | "timestamp">):
 
 /** Apply a validated report event exactly once by event id. */
 export function receiveWorkerMessage(event: WorkerReportEvent, options?: { archived?: boolean }): boolean {
-  const sender = getTeammate(event.worker);
+  const sender = getAgent(event.worker);
   if (!sender || sender.spawnId !== event.spawnId) return false;
   if (state.leaderMailbox.some((message) => message.id === event.id)) return false;
   state.leaderMailbox.push({
@@ -328,446 +250,75 @@ export function getPeerDeliveryState(messageId: string): "queued" | "routed" | "
   return state.peerDeliveryStates?.[messageId];
 }
 
-// ── Board: creation and queries ───────────────────────────────────
+// ── Tasks: creation and queries ───────────────────────────────────
 
 /** Maximum characters in a generated slug task id (suffix included). */
-const MAX_TASK_ID_LENGTH = 48;
-
-/** A readable, filesystem-safe id derived from the subject:
- *  "Polish login flow" -> "polish-login-flow"; duplicates get -2, -3, ... */
-export function taskIdFromSubject(subject: string, taken: ReadonlySet<string>): string {
-  const base = subject
-    .toLowerCase()
-    .replace(/[^\p{L}\p{N}]+/gu, "-")
-    .replace(/^-+|-+$/g, "")
-    .slice(0, MAX_TASK_ID_LENGTH)
-    .replace(/-+$/g, "") || "task";
-  let id = base;
-  for (let n = 2; taken.has(id); n++) {
-    const suffix = `-${n}`;
-    id = base.slice(0, Math.max(1, MAX_TASK_ID_LENGTH - suffix.length)).replace(/-+$/g, "") + suffix;
-  }
-  return id;
-}
-
-export function normalizeResources(resources: readonly string[] | undefined): string[] {
-  return [...new Set((resources ?? [])
-    .map((resource) => resource.trim().replace(/^\/+|\/+$/g, ""))
-    .filter(Boolean))]
-    .sort();
-}
-
-/** Follow an obsolete dependency to its latest replacement. An invalid persisted
- * chain is rejected rather than silently making a future task unclaimable. */
-export function canonicalDependency(taskId: string, tasks: Record<string, BoardTask>): string | undefined {
-  const seen = new Set<string>();
-  let current = taskId;
-  while (true) {
-    if (seen.has(current)) return undefined;
-    seen.add(current);
-    const task = tasks[current];
-    if (!task) return undefined;
-    if (task.status !== "superseded") return current;
-    if (!task.supersededBy) return undefined;
-    current = task.supersededBy;
-  }
-}
-
-function canonicalDependencies(
-  dependencies: readonly string[],
-  tasks: Record<string, BoardTask>,
-): string[] | undefined {
-  const canonical: string[] = [];
-  for (const dependency of dependencies) {
-    const resolved = canonicalDependency(dependency, tasks);
-    if (!resolved) return undefined;
-    if (!canonical.includes(resolved)) canonical.push(resolved);
-  }
-  return canonical;
-}
-
-function hasDependencyCycle(graph: Map<string, readonly string[]>): boolean {
-  const visiting = new Set<string>();
-  const visited = new Set<string>();
-  const visit = (taskId: string): boolean => {
-    if (visiting.has(taskId)) return true;
-    if (visited.has(taskId)) return false;
-    visiting.add(taskId);
-    for (const dependency of graph.get(taskId) ?? []) {
-      if (graph.has(dependency) && visit(dependency)) return true;
-    }
-    visiting.delete(taskId);
-    visited.add(taskId);
-    return false;
-  };
-  return [...graph.keys()].some(visit);
-}
-
-/** `firmware/sub-node` conflicts with itself and descendants such as
- * `firmware/sub-node/app`; unrelated siblings stay concurrently claimable. */
-export function resourcesConflict(left: readonly string[], right: readonly string[]): boolean {
-  return left.some((a) => right.some((b) => a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`)));
-}
-
 export function activeAssignmentConflict(
   resources: readonly string[],
   exceptWorker?: string,
-): Teammate | undefined {
+): Agent | undefined {
   if (resources.length === 0) return undefined;
-  return livingTeammates().find((teammate) => {
+  return livingAgents().find((teammate) => {
     if (teammate.name === exceptWorker) return false;
     const assignment = teammate.assignment;
     const retainsWorkAuthority = teammate.currentTaskId !== undefined
-      && ["claimed", "superseded"].includes(state.tasks[teammate.currentTaskId]?.status ?? "");
+      && (state.tasks[teammate.currentTaskId]?.status === "in_progress" || isTaskReplaced(state.tasks[teammate.currentTaskId]));
     return assignment !== undefined
       && (!assignment.closed || retainsWorkAuthority)
       && resourcesConflict(resources, assignment.resources);
   });
 }
 
-export function createTask(input: {
-  id?: string;
-  subject: string;
-  description?: string;
-  dependsOn?: string[];
-  verify?: string;
-  resources?: string[];
-  supersedes?: string[];
-}): { ok: true; task: BoardTask; superseded: BoardTask[] } | { ok: false; error: string } {
-  const subject = input.subject.trim();
-  if (!subject) return { ok: false, error: "Task subject must not be empty." };
-  const requestedDependencies = [...new Set(input.dependsOn ?? [])];
-  const requestedSupersedes = [...new Set(input.supersedes ?? [])];
-  if (requestedDependencies.length > MAX_TASK_DEPENDENCIES) {
-    return { ok: false, error: `Task depends on more than ${MAX_TASK_DEPENDENCIES} tasks.` };
-  }
-  for (const taskId of [...requestedDependencies, ...requestedSupersedes]) {
-    if (!state.tasks[taskId]) return { ok: false, error: `Task references unknown task "${taskId}".` };
-  }
-  const completedTarget = requestedSupersedes.find((taskId) => state.tasks[taskId]?.status === "completed");
-  if (completedTarget) {
-    return { ok: false, error: `Task cannot supersede completed task "${completedTarget}".` };
-  }
-  const dependsOn = canonicalDependencies(requestedDependencies, state.tasks);
-  const supersedes = canonicalDependencies(requestedSupersedes, state.tasks);
-  if (!dependsOn || !supersedes) return { ok: false, error: "Task dependency or supersession chain is invalid or cyclic." };
-  const canonicalCompletedTarget = supersedes.find((taskId) => state.tasks[taskId]?.status === "completed");
-  if (canonicalCompletedTarget) {
-    return { ok: false, error: `Task cannot supersede completed task "${canonicalCompletedTarget}".` };
-  }
-  const selfReplacement = supersedes.find((taskId) => dependsOn.includes(taskId));
-  if (selfReplacement) {
-    return { ok: false, error: `Task cannot both depend on and supersede "${selfReplacement}".` };
-  }
-
-  const id = input.id ?? taskIdFromSubject(subject, new Set(Object.keys(state.tasks)));
-  if (state.tasks[id]) return { ok: false, error: `Task id "${id}" already exists.` };
-  const migrations = new Map<string, string[]>();
-  for (const dependent of Object.values(state.tasks)) {
-    if (dependent.status === "completed" || dependent.status === "superseded") continue;
-    const migrated = dependent.dependsOn.map((dependency) => supersedes.includes(dependency) ? id : dependency);
-    if (migrated.some((dependency, index) => dependency !== dependent.dependsOn[index])) {
-      migrations.set(dependent.id, [...new Set(migrated)]);
-    }
-  }
-  const prospectiveGraph = new Map<string, readonly string[]>();
-  for (const existing of Object.values(state.tasks)) {
-    prospectiveGraph.set(existing.id, migrations.get(existing.id) ?? existing.dependsOn);
-  }
-  prospectiveGraph.set(id, dependsOn);
-  if (hasDependencyCycle(prospectiveGraph)) {
-    return { ok: false, error: "Task supersession would create a dependency cycle." };
-  }
-
-  const task: BoardTask = {
-    id,
-    subject,
-    description: input.description?.trim() || undefined,
-    dependsOn,
-    verify: input.verify?.trim() || undefined,
-    resources: normalizeResources(input.resources),
-    status: "pending",
-    createdAt: Date.now(),
-    updatedAt: Date.now(),
-  };
-  state.tasks[id] = task;
-  boardRevisionCounter++;
-  stateRevisionCounter++;
-  const superseded: BoardTask[] = [];
-  for (const oldId of supersedes) {
-    const old = state.tasks[oldId];
-    if (!old || old.status === "completed" || old.status === "superseded") continue;
-    old.status = "superseded";
-    old.supersededBy = id;
-    // A living holder keeps the claim and assignment until it acknowledges
-    // cancellation or stops. Releasing its resource before it receives the
-    // stop instruction would let replacement work race active file writes.
-    old.updatedAt = Date.now();
-    superseded.push(old);
-  }
-  for (const [dependentId, migratedDependencies] of migrations) {
-    const dependent = state.tasks[dependentId];
-    if (!dependent) continue;
-    dependent.dependsOn = migratedDependencies;
-    dependent.updatedAt = Date.now();
-  }
-  return { ok: true, task, superseded };
-}
-
-export function getTask(taskId: string): BoardTask | undefined {
-  return state.tasks[taskId];
-}
-
-export function listTasks(): BoardTask[] {
-  return Object.values(state.tasks).sort((a, b) => a.id.localeCompare(b.id));
-}
-
-export function pendingTasks(): BoardTask[] {
-  return listTasks().filter((task) => task.status === "pending");
-}
-
-export function claimableTasks(): BoardTask[] {
-  return pendingTasks().filter((task) => !task.recoveryRequired && taskDependenciesMet(task));
-}
-
-export function taskDependenciesMet(task: BoardTask): boolean {
-  return task.status === "pending" && task.dependsOn.every((dep) => state.tasks[dep]?.status === "completed");
-}
-
-export function createDirectWork(input: {
-  id: string;
-  subject: string;
-  description?: string;
-  resources: string[];
-  verify?: string;
-  workerName: string;
-  assignment: WorkerAssignment;
-}): { ok: true; task: BoardTask } | { ok: false; error: string } {
-  const created = createTask({
-    id: input.id,
-    subject: input.subject,
-    description: input.description,
-    resources: input.resources,
-    verify: input.verify,
-  });
-  if (!created.ok) return created;
-  const task = created.task;
-  const worker = getTeammate(input.workerName);
-  if (!worker || worker.assignment || activeAssignmentConflict(task.resources, input.workerName)) {
-    // The Work is rolled back here, so its id would render as an unresolvable
-    // handle: name the work a person can recognize instead.
-    const reason = !worker
-      ? `@${input.workerName} is not a registered teammate`
-      : worker.assignment
-        ? `@${input.workerName} already owns ${worker.assignment.kind} assignment "${worker.assignment.id}"`
-        : `its resources conflict with active Work`;
-    delete state.tasks[task.id];
-    return { ok: false, error: `Cannot bind direct Work "${input.subject}" to @${input.workerName}: ${reason}.` };
-  }
-  task.status = "claimed";
-  task.claimedBy = input.workerName;
-  task.updatedAt = Date.now();
-  boardRevisionCounter++;
-  stateRevisionCounter++;
-  assignTeammate(input.workerName, input.assignment, task.id);
-  return { ok: true, task };
-}
-
-export function discardDirectWork(taskId: string, workerName: string): boolean {
-  const task = state.tasks[taskId];
-  if (!task || task.status !== "claimed" || task.claimedBy !== workerName) return false;
-  delete state.tasks[taskId];
-  boardRevisionCounter++;
-  stateRevisionCounter++;
-  return true;
-}
-
-export function reclaimDirectWork(
-  taskId: string,
-  workerName: string,
-  assignment: WorkerAssignment,
-  expectedState: "pending" | "completed" | "claimed",
-  allowActiveAssignment = false,
-): { ok: true } | { ok: false; error: string } {
-  const task = state.tasks[taskId];
-  const worker = getTeammate(workerName);
-  const retainsSupersededWork = worker?.currentTaskId !== undefined
-    && state.tasks[worker.currentTaskId]?.status === "superseded";
-  if (!task || task.status !== expectedState || !worker || retainsSupersededWork || (!allowActiveAssignment && worker.assignment && !worker.assignment.closed)) {
-    return { ok: false, error: `Unable to reclaim direct Work Item "${taskId}".` };
-  }
-  const conflict = activeAssignmentConflict(task.resources, workerName);
-  if (conflict) return { ok: false, error: `Resource conflict with @${conflict.name}'s active assignment.` };
-  task.status = "claimed";
-  task.claimedBy = workerName;
-  task.result = undefined;
-  task.errorMessage = undefined;
-  task.recoveryRequired = undefined;
-  task.completedAt = undefined;
-  task.updatedAt = Date.now();
-  boardRevisionCounter++;
-  stateRevisionCounter++;
-  assignTeammate(workerName, assignment, task.id);
-  return { ok: true };
-}
-
-export function setTaskClaimed(taskId: string, workerName: string): BoardTask | undefined {
-  const task = state.tasks[taskId];
-  const teammate = getTeammate(workerName);
-  if (!task || !teammate || task.status !== "pending" || task.recoveryRequired || !taskDependenciesMet(task)) return undefined;
-  if (teammate.assignment) return undefined;
-  if (activeAssignmentConflict(task.resources, workerName)) return undefined;
-  task.status = "claimed";
-  task.claimedBy = workerName;
-  task.updatedAt = Date.now();
-  boardRevisionCounter++;
-  stateRevisionCounter++;
-  assignTeammate(workerName, { id: `board:${randomUUID()}`, kind: "board", resources: task.resources }, task.id);
-  return task;
-}
-
-/** Release a claimed task back to pending. A superseded holder instead
- * acknowledges cancellation: the task stays superseded but frees resources.
- * `recoveryRequired` marks an attempt that ran and did not succeed (failure,
- * crash, or stop), so it waits for a deliberate Leader assignment instead of
- * being re-offered. A harness start failure that happened before the attempt
- * reached the worker stays ordinarily claimable; a deliberate Leader release
- * passes `false` for the same reason. */
-export function claimedDependents(workId: string): BoardTask[] {
-  const reverse = new Map<string, string[]>();
-  for (const task of Object.values(state.tasks)) {
-    for (const dependency of task.dependsOn) {
-      const dependents = reverse.get(dependency) ?? [];
-      dependents.push(task.id);
-      reverse.set(dependency, dependents);
-    }
-  }
-  const visited = new Set<string>();
-  const pending = [...(reverse.get(workId) ?? [])];
-  const claimed: BoardTask[] = [];
-  while (pending.length > 0) {
-    const id = pending.shift()!;
-    if (visited.has(id)) continue;
-    visited.add(id);
-    const task = state.tasks[id];
-    if (!task) continue;
-    if (task.status === "claimed" || (task.status === "superseded" && task.claimedBy !== undefined)) claimed.push(task);
-    pending.push(...(reverse.get(id) ?? []));
-  }
-  return claimed.sort((left, right) => left.id.localeCompare(right.id));
-}
-
-export function reopenCompletedWork(workId: string): { ok: true; task: BoardTask } | { ok: false; error: string } {
-  const task = state.tasks[workId];
-  if (!task || task.status !== "completed") return { ok: false, error: `Work Item "${workId}" is not completed.` };
-  const blockers = claimedDependents(workId);
-  if (blockers.length > 0) return { ok: false, error: `Work Item "${workId}" has active dependent Work: ${blockers.map((blocker) => blocker.id).join(", ")}.` };
-  task.status = "pending";
-  task.claimedBy = undefined;
-  task.result = undefined;
-  task.deferredMessages = undefined;
-  task.errorMessage = undefined;
-  task.recoveryRequired = undefined;
-  task.completedAt = undefined;
-  task.updatedAt = Date.now();
-  boardRevisionCounter++;
-  stateRevisionCounter++;
-  return { ok: true, task };
-}
+// ── Tasks (delegated to pi-tasks) ────────────────────────────────
+//
+// There is deliberately no `release` here. A lease is given back on completion,
+// on process exit, and on stop; the runtime's own half-start reverts go through
+// `revertUndeliveredTake`, and a holder that must free a lease it is not giving
+// up uses `acknowledgeSupersession`. Those name what happened instead of offering
+// one verb that can take any task from anyone.
+export {
+  createTask, getTask, listTasks, pendingTasks, claimableTasks, taskDependenciesMet,
+  takeTask, claimedDependents, reopenTask, failTasksHeldBy,
+  applyClaimIntent, revertUndeliveredTake, bindTask, discardTask,
+  acknowledgeSupersession, completeTaskWithOutcome,
+  applySubmissionIntent, loadTasks, setTaskContext,
+} from "@fradser/pi-tasks";
+export type { WorkAssignment as WorkerAssignment } from "@fradser/pi-tasks";
 
-export function releaseTask(taskId: string, errorMessage: string | undefined, recoveryRequired: boolean): BoardTask | undefined {
-  const task = state.tasks[taskId];
-  if (!task || (task.status !== "claimed" && task.status !== "superseded")) return undefined;
-  const holder = task.claimedBy;
-  if (task.status === "claimed") task.status = "pending";
-  task.claimedBy = undefined;
-  task.recoveryRequired = task.status === "pending" && recoveryRequired ? true : undefined;
-  if (errorMessage !== undefined) task.errorMessage = errorMessage;
-  task.updatedAt = Date.now();
-  boardRevisionCounter++;
-  stateRevisionCounter++;
-  if (holder) assignTeammate(holder, undefined, undefined);
-  return task;
-}
-
-export function completeTask(taskId: string, result?: string): BoardTask | undefined {
-  const task = state.tasks[taskId];
-  if (!task || task.status !== "claimed") return undefined;
-  const holder = task.claimedBy;
-  task.status = "completed";
-  task.claimedBy = undefined;
-  task.result = result;
-  task.errorMessage = undefined;
-  task.recoveryRequired = undefined;
-  task.completedAt = Date.now();
-  task.updatedAt = Date.now();
-  boardRevisionCounter++;
-  stateRevisionCounter++;
-  if (holder) assignTeammate(holder, undefined, undefined);
-  return task;
-}
-
-/** Release every task held by a named teammate (crash or shutdown). */
-export function releaseTasksOf(workerName: string, reason: string): BoardTask[] {
-  const released: BoardTask[] = [];
-  for (const task of listTasks()) {
-    if ((task.status === "claimed" || task.status === "superseded") && task.claimedBy === workerName) {
-      releaseTask(task.id, reason, true);
-      released.push(task);
+/**
+ * Create a Task and bind it to a named holder in one step, rolling the creation
+ * back if the bind is refused.
+ *
+ * Composed here rather than offered by the tasks, because it is a coordinator's
+ * move: the task store states what must be done and takes only what a holder chose to
+ * take, while this names a holder and mints its lease. The rollback matters —
+ * without it a refusal would leave a Task whose id resolves to nothing.
+ */
+export function createBoundWork(input: {
+    id: string;
+    subject: string;
+    description?: string;
+    resources?: string[];
+    verify?: string;
+    holder: string;
+    assignment: WorkerAssignment;
+  }): { ok: true; task: import("@fradser/pi-tasks").Task } | { ok: false; reason: string } {
+    const created = createTask({
+      id: input.id,
+      recordKind: "execution",
+      subject: input.subject,
+      ...(input.description ? { description: input.description } : {}),
+      ...(input.resources ? { resources: input.resources } : {}),
+      ...(input.verify ? { verify: input.verify } : {}),
+    });
+    if (!created.ok) return { ok: false, reason: created.reason };
+    const bound = bindTask(input.id, input.holder, input.assignment, { from: ["pending"] });
+    if (!bound.ok) {
+      discardTask(input.id, input.holder);
+      return { ok: false, reason: bound.reason };
     }
+    return { ok: true, task: bound.task };
   }
-  return released;
-}
-
-/** Apply a validated claim intent from a marker file. */
-export function applyClaimIntent(intent: TaskIntent): { applied: boolean; reason?: string } {
-  const task = state.tasks[intent.taskId];
-  const teammate = getTeammate(intent.worker);
-  if (!task) return { applied: false, reason: `unknown task "${intent.taskId}"` };
-  if (!teammate || teammate.spawnId !== intent.spawnId || teammate.status === "stopped") {
-    return { applied: false, reason: `worker "${intent.worker}" is not a living current incarnation` };
-  }
-  if (teammate.assignment) {
-    const state = teammate.assignment.closed ? "closed pending leader reopen" : "active";
-    return { applied: false, reason: `@${intent.worker} already owns ${state} ${teammate.assignment.kind} assignment "${teammate.assignment.id}"` };
-  }
-  if (task.status === "claimed") return { applied: false, reason: `task "${intent.taskId}" is already claimed` };
-  if (task.status === "completed" || task.status === "superseded") return { applied: false, reason: `task "${intent.taskId}" is ${task.status}` };
-  if (task.recoveryRequired) return { applied: false, reason: `task "${intent.taskId}" requires explicit leader Work assignment after failure` };
-  if (!taskDependenciesMet(task)) return { applied: false, reason: `task "${intent.taskId}" has unmet dependencies` };
-  const conflict = activeAssignmentConflict(task.resources, intent.worker);
-  if (conflict) return { applied: false, reason: `resource conflict with @${conflict.name}'s ${conflict.assignment?.kind} assignment "${conflict.assignment?.id}"` };
-  if (!setTaskClaimed(intent.taskId, intent.worker)) return { applied: false, reason: `task "${intent.taskId}" could not be claimed` };
-  return { applied: true };
-}
-
-/** Validate and apply a submission intent; verify gating happens in the caller. */
-export function applySubmissionIntent(intent: TaskIntent): { ok: boolean; error?: string } {
-  if (intent.status !== "completed" && intent.status !== "failed") {
-    return { ok: false, error: `task "${intent.taskId}" has invalid submission status` };
-  }
-  const teammate = getTeammate(intent.worker);
-  if (!teammate || teammate.spawnId !== intent.spawnId || teammate.status === "stopped") {
-    return { ok: false, error: `worker "${intent.worker}" is not a living current incarnation` };
-  }
-  const task = state.tasks[intent.taskId];
-  if (!task) return { ok: false, error: `unknown task "${intent.taskId}"` };
-  if (task.status !== "claimed" && task.status !== "superseded") {
-    return { ok: false, error: `task "${intent.taskId}" is not claimed` };
-  }
-  if (task.claimedBy !== intent.worker) {
-    return { ok: false, error: `task "${intent.taskId}" is claimed by ${task.claimedBy ?? "someone else"}` };
-  }
-  if (task.status === "superseded" && intent.status !== "failed") {
-    return { ok: false, error: `task "${intent.taskId}" was superseded by "${task.supersededBy ?? "a replacement"}"; submit failed to acknowledge cancellation` };
-  }
-  if (intent.status === "failed") {
-    releaseTask(intent.taskId, intent.result?.trim() || "Agent reported failure.", true);
-    return { ok: true };
-  }
-  completeTask(intent.taskId, intent.result?.trim() || undefined);
-  return { ok: true };
-}
 
 // ── State inspection ──────────────────────────────────────────────
 
@@ -775,27 +326,21 @@ export function getState(): TeamState {
   return state;
 }
 
-/** Load a persisted board into memory on resume; claims die with their holders. */
-export function loadBoard(tasks: Record<string, BoardTask>): number {
-  let reloaded = 0;
-  for (const task of Object.values(tasks)) {
-    const orphanedHolding = task.status === "claimed" || task.status === "superseded";
-    const restored: BoardTask = {
-      ...task,
-      resources: normalizeResources(task.resources),
-      status: task.status === "claimed" ? "pending" : task.status,
-      recoveryRequired: task.status === "claimed" ? true : task.recoveryRequired,
-      // Runtime workers and assignments die with the session. Superseded work
-      // remains visible for audit but cannot retain a dead holder/resource lock.
-      claimedBy: orphanedHolding ? undefined : task.claimedBy,
-      updatedAt: Date.now(),
-    };
-    state.tasks[restored.id] = restored;
-    reloaded++;
-  }
-  if (reloaded > 0) {
-    boardRevisionCounter++;
-    stateRevisionCounter++;
-  }
-  return reloaded;
-}
+configureTaskStore({
+  get: (name) => {
+    const t = getAgent(name);
+    return t ? { name: t.name, spawnId: t.spawnId, status: t.status,
+                assignment: t.assignment, currentTaskId: t.currentTaskId } : undefined;
+  },
+  // A stopped agent holds nothing, and a replaced one is not the incarnation that
+  // published the intent. Only the roster knows either, which is why the tasks
+  // asks rather than comparing spawn ids itself.
+  current: (name, incarnation) => {
+    const t = getAgent(name);
+    if (!t || t.status === "stopped") return false;
+    return incarnation === undefined || t.spawnId === incarnation;
+  },
+  conflicting: (resources, except) => activeAssignmentConflict(resources, except),
+  sync: (name, assignment, taskId) => { assignAgent(name, assignment, taskId); },
+  changed: () => { tasksRevisionCounter++; stateRevisionCounter++; },
+});