@tablation/crew 0.80.0 → 0.81.0

package/crew.example.yaml

@@ -27,6 +27,21 @@ ship:
     # to disable (less latency/cost, no cycles reported).
     # maxThinkingTokens: 4096
 
+  # Optional (CREW-2821): how many agents this ship runs at once. `roleConcurrency`
+  # is the cap on runs of ONE role (default 1 per role, so unset behaves as it
+  # always has: dev beside qa, never two devs). `maxConcurrentAgents` is the
+  # ship-wide cap across every role. Default 2 when `roleConcurrency` is unset;
+  # when `roleConcurrency` is set and `maxConcurrentAgents` is not, it defaults
+  # to the SUM of the role caps (plus 1 for each of dev/design/qa/triage the map
+  # leaves out), so `roleConcurrency: { dev: 2, qa: 2 }` alone allows 6 runs.
+  # Set it explicitly to hold a machine-wide budget below that sum;
+  # `crew doctor` warns when it is lower than any single role's cap. Each run
+  # takes its own ticket (a per-ticket lock keeps two runs off the same one).
+  # `dev`, `design` and `qa` can run several; `triage` is always one at a time.
+  # The release route is unaffected: one release per repository at a time.
+  # maxConcurrentAgents: 4
+  # roleConcurrency: { dev: 2, qa: 2 }
+
   # Optional (CREW-1511): named toolchains — a harness adapter plus the binary
   # and model to run it with. The `agent:` block above keeps working and
   # defines an implicit toolchain named `claude`. Harnesses: claude, codex, gemini. See docs/toolchains.md.

package/dist/cli.js

@@ -2055,6 +2055,7 @@ var SHIP_KEYS = /* @__PURE__ */ new Set([
   "baseUrl",
   "apiKey",
   "maxConcurrentAgents",
+  "roleConcurrency",
   "streamRetentionDays",
   "eventsRotateBytes",
   "reposBasePath",
@@ -2364,10 +2365,34 @@ Create the first of those:
   if (declaredPlatform && !isShipPlatform(declaredPlatform)) {
     missing.add(`ship.platform must be one of macos|linux|windows (got "${declaredPlatform}")`);
   }
-  const maxConcurrentAgents = shipRaw.maxConcurrentAgents === void 0 ? 2 : Number(shipRaw.maxConcurrentAgents);
+  const maxConcurrentAgentsSet = shipRaw.maxConcurrentAgents !== void 0;
+  let maxConcurrentAgents = maxConcurrentAgentsSet ? Number(shipRaw.maxConcurrentAgents) : 2;
   if (!Number.isInteger(maxConcurrentAgents) || maxConcurrentAgents < 1) {
     missing.add(`ship.maxConcurrentAgents must be a positive integer (got "${shipRaw.maxConcurrentAgents}")`);
   }
+  const roleConcurrency = {};
+  const roleConcurrencyRaw = shipRaw.roleConcurrency;
+  if (roleConcurrencyRaw !== void 0 && roleConcurrencyRaw !== null) {
+    if (typeof roleConcurrencyRaw !== "object" || Array.isArray(roleConcurrencyRaw)) {
+      missing.add("ship.roleConcurrency must be a map of role to a positive integer");
+    } else {
+      for (const [role, v] of Object.entries(roleConcurrencyRaw)) {
+        if (!ROLE_NAMES.includes(role)) {
+          missing.add(`ship.roleConcurrency.${role} is not a role (expected one of ${ROLE_NAMES.join(", ")})`);
+          continue;
+        }
+        const n = Number(v);
+        if (!Number.isInteger(n) || n < 1) {
+          missing.add(`ship.roleConcurrency.${role} must be a positive integer (got "${String(v)}")`);
+          continue;
+        }
+        roleConcurrency[role] = n;
+      }
+    }
+  }
+  if (!maxConcurrentAgentsSet && Object.keys(roleConcurrency).length > 0) {
+    maxConcurrentAgents = ROLE_NAMES.filter((r) => r !== "pair").reduce((n, r) => n + (roleConcurrency[r] ?? 1), 0);
+  }
   const streamRetentionDays = shipRaw.streamRetentionDays === void 0 ? 7 : Number(shipRaw.streamRetentionDays);
   if (!Number.isInteger(streamRetentionDays) || streamRetentionDays < 1) {
     missing.add(`ship.streamRetentionDays must be a positive integer (got "${shipRaw.streamRetentionDays}")`);
@@ -2431,6 +2456,8 @@ Create the first of those:
       logFile: expand(shipRaw.logFile ?? join9(tmpdir(), "crew.log"), base),
       userAgent: shipRaw.userAgent ?? `Mozilla/5.0 CrewAgent/${crewVersion(crewHome)}`,
       maxConcurrentAgents,
+      maxConcurrentAgentsSet,
+      roleConcurrency,
       streamRetentionDays,
       eventsRotateBytes,
       relayHost: shipRaw.relayHost ? String(shipRaw.relayHost) : void 0,
@@ -4541,6 +4568,10 @@ function formatStaleOwnLock(scope, holder) {
   return `WARN lock ${scope} is held by ${holder}, but that process is gone \u2014 the next release cycle reclaims it
 `;
 }
+function roleCapWarnings(ship) {
+  if (!ship.maxConcurrentAgentsSet) return [];
+  return Object.entries(ship.roleConcurrency).filter(([, n]) => (n ?? 0) > ship.maxConcurrentAgents).map(([role, n]) => `ship.roleConcurrency.${role} is ${n}, above ship.maxConcurrentAgents (${ship.maxConcurrentAgents}); the ship-wide cap wins`);
+}
 
 // src/selftest.ts
 import { spawn as spawn3 } from "child_process";
@@ -5654,22 +5685,36 @@ var State = class _State {
     return { ok: false, heldBy };
   }
   /**
-   * The run lock (ISSUE-381): role-distinct AND capacity-limited, checked
-   * together.
+   * The run lock (ISSUE-381, CREW-2821): role-capped AND capacity-limited,
+   * checked together.
    *
-   * Role queues are disjoint by construction (`sliceFor`), so two sessions
-   * of the SAME role would collide on the same ticket if ever let run at
-   * once — that half is a plain exclusive lock, one per role name, and
-   * never relaxed. `max` is this machine's separate, configurable limit on
-   * how many DIFFERENT roles may run together; a role that clears its own
-   * lock but finds every slot taken must give the slot back its lock too,
-   * or a locked-but-not-running role would wedge itself out for the rest
-   * of the machine's uptime.
+   * Two sessions of one role must never take the same ticket. Before
+   * CREW-2821 that was guaranteed by an exclusive per-role lock; now the
+   * guarantee is the per-ticket lock (`acquireTicket`), so the role lock is a
+   * counted one: `roleMax` interchangeable slots, default 1. Slot 1 keeps the
+   * historical name `crew-role-<role>` (crew-macos reads it for the live pid),
+   * further slots are `crew-role-<role>-<n>`. `max` is this machine's separate
+   * limit on how many runs of ANY role may overlap; a role that clears its own
+   * lock but finds every slot taken must give its role lock back, or a
+   * locked-but-not-running role would wedge itself out for the rest of the
+   * machine's uptime.
    */
-  acquireRun(role, max) {
-    const roleLock = this.acquire(`crew-role-${role}`);
-    if (!roleLock.ok) {
-      return { ok: false, reason: `${role} is already running (pid ${roleLock.heldBy})` };
+  acquireRun(role, max, roleMax = 1) {
+    let roleLock;
+    const roleHolders = [];
+    for (let i = 1; i <= roleMax; i++) {
+      const got = this.acquire(i === 1 ? `crew-role-${role}` : `crew-role-${role}-${i}`);
+      if (got.ok) {
+        roleLock = got;
+        break;
+      }
+      roleHolders.push(got.heldBy);
+    }
+    if (!roleLock) {
+      return {
+        ok: false,
+        reason: roleMax === 1 ? `${role} is already running (pid ${roleHolders[0]})` : `${role} is already running ${roleMax} agents (its roleConcurrency cap; pid${roleHolders.length > 1 ? "s" : ""} ${[...new Set(roleHolders)].join(", ")})`
+      };
     }
     const slot = this.acquireN("crew-slot", max);
     if (!slot.ok) {
@@ -5684,6 +5729,27 @@ var State = class _State {
       roleLock.release();
     } };
   }
+  /**
+   * The per-ticket run lock (CREW-2821): held for the life of a run that works
+   * the ticket (`crew-ticket-<record id>`), so a second run of the same role
+   * on this ship walks past it instead of being handed the first run's
+   * ticket. Same stale-pid rule as every lock here.
+   */
+  acquireTicket(recordId) {
+    return this.acquire(`crew-ticket-${recordId}`);
+  }
+  /** Whether a live run on this ship holds `recordId`'s ticket lock. */
+  ticketInFlight(recordId) {
+    const file = this.path(`.${_State.safe(`crew-ticket-${recordId}`)}.lock`);
+    try {
+      const pid = Number.parseInt(readFileSync12(file, "utf8").trim(), 10);
+      if (!Number.isFinite(pid) || pid <= 0) return false;
+      process.kill(pid, 0);
+      return true;
+    } catch {
+      return false;
+    }
+  }
   /**
    * How many consecutive cycles the release phase has refused to deploy.
    *
@@ -7063,7 +7129,14 @@ function newBranchName(cfg, t, role) {
 function planRunWorktree(dir, cfg, t, role, opts = {}) {
   const { remote, base } = cfg.branch;
   const hasRemote = remoteConfigured(dir, remote);
-  if (hasRemote) fetchRemote(dir, remote);
+  if (hasRemote) {
+    const unlock = acquireCheckoutLock(dir);
+    try {
+      fetchRemote(dir, remote);
+    } finally {
+      unlock();
+    }
+  }
   const num = t.issue_id.replace(/^\D+/, "");
   const existing = worktreeForNumber(dir, num);
   const located = locateBranchForTicket(dir, cfg, t, role);
@@ -8373,6 +8446,7 @@ var AgentError = class extends Error {
 };
 var AgentSpawnError = class extends AgentError {
 };
+var digestPathFor = (stateDir, routeLabel, role, runId) => join19(stateDir, `digest-${routeLabel}-${role}${runId ? `-${runId}` : ""}.md`);
 function planAgentRun(o) {
   const briefPath = join19(o.route.promptsDir, "personas", `lane-${o.role}.md`);
   if (!existsSync18(briefPath)) {
@@ -8382,7 +8456,8 @@ function planAgentRun(o) {
   const usesCommon = !SELF_CONTAINED_ROLES.has(o.role) && existsSync18(commonPath);
   const now = o.now ?? (() => Date.now());
   const routeLabel = routeSlug(o.route.route);
-  const digestPath2 = join19(o.stateDir, `digest-${routeLabel}-${o.role}.md`);
+  const ownDigest = o.runId ? digestPathFor(o.stateDir, routeLabel, o.role, o.runId) : void 0;
+  const digestPath2 = ownDigest && existsSync18(ownDigest) ? ownDigest : digestPathFor(o.stateDir, routeLabel, o.role);
   let digest;
   let ageSeconds;
   if (existsSync18(digestPath2)) {
@@ -8413,7 +8488,7 @@ function planAgentRun(o) {
   });
   const promptSha = createHash3("sha256").update(expanded.text).digest("hex");
   const streamsDir = join19(o.stateDir, "streams");
-  const base = `${routeLabel}-${o.role}-${o.cycle}`;
+  const base = `${routeLabel}-${o.role}-${o.cycle}${o.runId ? `-${o.runId}` : ""}`;
   const seat = resolveSeat(o.ship, o.route, o.role, o.agentPersona ?? (o.agentModel ? { model: o.agentModel } : {}), o.repo);
   const { toolchain, model } = seat;
   const adapter = adapterFor(toolchain.harness);
@@ -10955,8 +11030,15 @@ async function decideCycle(o) {
   }
   return decision;
 }
-var digestPath = (stateDir, route, role) => join23(stateDir, `digest-${route}-${role}.md`);
-function writeDigest(o, d, role, stateDir) {
+var digestPath = (stateDir, route, role, runId) => join23(stateDir, `digest-${route}-${role}${runId ? `-${runId}` : ""}.md`);
+function otherRunsRemoved(tickets, own) {
+  if (!own) return tickets;
+  return tickets.filter((t) => t.id === own.ticket.id || !own.inFlight(t.id));
+}
+function ownRunBanner(own) {
+  return `**Your ticket for this run: ${own.ticket.issue_id}.** Work this one. Any other ticket a live run on this ship is already working has been left out of this digest: it belongs to that run.`;
+}
+function writeDigest(o, d, role, stateDir, runId, own) {
   const me = o.route.resolved?.seats[role];
   if (!me) return false;
   try {
@@ -11002,7 +11084,7 @@ function writeDigest(o, d, role, stateDir) {
         }
         return existingBranchForTicket(dir, repoFor(dir), t, role);
       },
-      tickets: role === "triage" ? triageSlice(d.tickets, o.route.resolved?.seats.triage, d.selectionInput.workModes) : withinWorkMode(sliceFor(d.tickets, role), d.selectionInput.workModes),
+      tickets: role === "triage" ? triageSlice(d.tickets, o.route.resolved?.seats.triage, d.selectionInput.workModes) : withinWorkMode(sliceFor(otherRunsRemoved(d.tickets, own), role), d.selectionInput.workModes),
       workModes: d.selectionInput.workModes,
       comments: d.comments,
       commentColumns: d.selectionInput.contract?.comments,
@@ -11021,8 +11103,11 @@ function writeDigest(o, d, role, stateDir) {
       blocked: d.blocked,
       blockerInfo: d.info
     };
-    const text = role === "qa" ? qaDigest(input) : buildingDigest(input);
-    const path = digestPath(stateDir, routeSlug(o.route.route), role);
+    const body = role === "qa" ? qaDigest(input) : buildingDigest(input);
+    const text = own ? `${ownRunBanner(own)}
+
+${body}` : body;
+    const path = digestPath(stateDir, routeSlug(o.route.route), role, runId);
     writeFileSync14(path, text);
     o.emit.emit(`queue digest written for ${role} (${Buffer.byteLength(text)} bytes)`, {
       data: { role, bytes: Buffer.byteLength(text) }
@@ -11063,7 +11148,7 @@ async function stampResumption(tracker, t, affinity) {
   }
   return { outcome: "unknown" };
 }
-async function resolveTopCandidate(tracker, candidates, seat, approvedStatus, buildingStatus, isServable, affinity) {
+async function resolveTopCandidate(tracker, candidates, seat, approvedStatus, buildingStatus, isServable, affinity, ticketLock) {
   const contended = [];
   const unservable = [];
   const held = [];
@@ -11076,41 +11161,58 @@ async function resolveTopCandidate(tracker, candidates, seat, approvedStatus, bu
       unservable.push(t.issue_id);
       continue;
     }
-    if (t.status !== approvedStatus) {
-      if (affinity?.isLiveHoldElsewhere?.(t)) {
-        return { ticket: t, claimed: false, contended, unservable, held, reaccepted: false, tookOverFrom: null };
-      }
-      if (affinity && t[affinity.column] !== affinity.shipId) {
-        const stamp = await stampResumption(tracker, t, affinity);
-        if (stamp.outcome === "stamped") {
-          return { ticket: stamp.ticket, claimed: false, contended, unservable, held, reaccepted: false, tookOverFrom: displacedHolder(t, affinity) };
-        }
-        (stamp.outcome === "held" ? held : contended).push(t.issue_id);
+    let releaseTicket;
+    if (ticketLock) {
+      const got = ticketLock(t);
+      if (!got) {
+        contended.push(t.issue_id);
         continue;
       }
+      releaseTicket = got;
+    }
+    const result = await resolveOne(tracker, t, seat, approvedStatus, buildingStatus, affinity, contended, unservable, held);
+    if (result === "walk") {
+      releaseTicket?.();
+      continue;
+    }
+    return releaseTicket ? { ...result, releaseTicket } : result;
+  }
+  return { ticket: null, claimed: false, contended, unservable, held, reaccepted: false, tookOverFrom: null };
+}
+async function resolveOne(tracker, t, seat, approvedStatus, buildingStatus, affinity, contended, unservable, held) {
+  if (t.status !== approvedStatus) {
+    if (affinity?.isLiveHoldElsewhere?.(t)) {
       return { ticket: t, claimed: false, contended, unservable, held, reaccepted: false, tookOverFrom: null };
     }
-    try {
-      const claimed = await tracker.updateTicket(
-        t.id,
-        {
-          status: buildingStatus,
-          assignee_id: seat,
-          ...affinity ? { [affinity.column]: affinity.shipId } : {}
-        },
-        t.updated_at
-      );
-      const reaccepted = !!affinity && t[affinity.column] === affinity.shipId;
-      return { ticket: { ...t, ...claimed }, claimed: true, contended, unservable, held, reaccepted, tookOverFrom: displacedHolder(t, affinity) };
-    } catch (e) {
-      if (e instanceof StaleWriteError6) {
-        contended.push(t.issue_id);
-        continue;
+    if (affinity && t[affinity.column] !== affinity.shipId) {
+      const stamp = await stampResumption(tracker, t, affinity);
+      if (stamp.outcome === "stamped") {
+        return { ticket: stamp.ticket, claimed: false, contended, unservable, held, reaccepted: false, tookOverFrom: displacedHolder(t, affinity) };
       }
-      throw e;
+      (stamp.outcome === "held" ? held : contended).push(t.issue_id);
+      return "walk";
     }
+    return { ticket: t, claimed: false, contended, unservable, held, reaccepted: false, tookOverFrom: null };
+  }
+  try {
+    const claimed = await tracker.updateTicket(
+      t.id,
+      {
+        status: buildingStatus,
+        assignee_id: seat,
+        ...affinity ? { [affinity.column]: affinity.shipId } : {}
+      },
+      t.updated_at
+    );
+    const reaccepted = !!affinity && t[affinity.column] === affinity.shipId;
+    return { ticket: { ...t, ...claimed }, claimed: true, contended, unservable, held, reaccepted, tookOverFrom: displacedHolder(t, affinity) };
+  } catch (e) {
+    if (e instanceof StaleWriteError6) {
+      contended.push(t.issue_id);
+      return "walk";
+    }
+    throw e;
   }
-  return { ticket: null, claimed: false, contended, unservable, held, reaccepted: false, tookOverFrom: null };
 }
 
 // src/conflict.ts
@@ -11975,6 +12077,27 @@ function planStamp(cwd, tickets, contract, fromSha, toSha, merged = /* @__PURE__
 function mergedAtFor(cwd, sha, fallback) {
   return cwd && commitDate(cwd, sha) || fallback;
 }
+async function applyMergeStamp(tracker, merged, tickets, emit, dryRun, cwd) {
+  let stamped = 0;
+  const at = (/* @__PURE__ */ new Date()).toISOString();
+  for (const ticket of tickets) {
+    const sha = merged.get(ticket.issue_id);
+    if (dryRun) {
+      emit.emit(`would stamp commit_sha${sha ? ` (${sha.slice(0, 8)})` : ""}`, { ticket: ticket.issue_id });
+      stamped++;
+      continue;
+    }
+    if (!sha || ticket.commit_sha === sha) continue;
+    try {
+      await tracker.updateTicket(ticket.id, { commit_sha: sha, merged_at: mergedAtFor(cwd, sha, at) });
+      emit.emit(`stamped commit_sha (${sha.slice(0, 8)})`, { ticket: ticket.issue_id });
+      stamped++;
+    } catch (e) {
+      emit.warn(`could not stamp commit_sha: ${e.message}`, { ticket: ticket.issue_id });
+    }
+  }
+  return stamped;
+}
 async function applyStamp(tracker, plan, version, contract, emit, dryRun, cwd) {
   let stamped = 0;
   const at = (/* @__PURE__ */ new Date()).toISOString();
@@ -11987,6 +12110,7 @@ async function applyStamp(tracker, plan, version, contract, emit, dryRun, cwd) {
       stamped++;
       continue;
     }
+    const recordMerge = !!sha && !ticket.commit_sha;
     try {
       await tracker.updateTicket(ticket.id, {
         status: contract.statuses.deployed,
@@ -11997,7 +12121,7 @@ async function applyStamp(tracker, plan, version, contract, emit, dryRun, cwd) {
         // ticket's record should mean the same thing regardless of which
         // release mode closed it (ISSUE-218). `merged_at` is the commit's own
         // date, not the stamp time (which trails the deploy in ci_* modes).
-        ...sha ? { commit_sha: sha, merged_at: mergedAtFor(cwd, sha, at) } : {}
+        ...recordMerge && sha ? { commit_sha: sha, merged_at: mergedAtFor(cwd, sha, at) } : {}
       });
       emit.emit(`stamped ${contract.statuses.deployed}${version ? ` (${version})` : ""}${shaNote}`, {
         ticket: ticket.issue_id
@@ -13072,6 +13196,13 @@ async function mergeAndRelease(o, decision, fresh, releaseBranch, isolated = fal
       }
     }
   }
+  if (o.repo.release.mode === "ci_auto" || o.repo.release.mode === "ci_manual") {
+    try {
+      await o.onBasePushed?.(merged);
+    } catch (e) {
+      o.emit.warn(`could not record merged tickets: ${e.message}`);
+    }
+  }
   let deployed = false;
   let integrated = false;
   if (o.repo.release.mode === "integrate") {
@@ -16741,6 +16872,7 @@ function describeCause(err) {
 // src/daemon.ts
 import { existsSync as existsSync33, mkdirSync as mkdirSync21, readFileSync as readFileSync30, readdirSync as readdirSync14, rmSync as rmSync14, statSync as statSync9, writeFileSync as writeFileSync22 } from "fs";
 import { join as join36 } from "path";
+import { randomBytes as randomBytes2 } from "crypto";
 
 // src/interrupted.ts
 import { existsSync as existsSync32, readdirSync as readdirSync13, readFileSync as readFileSync29 } from "fs";
@@ -16793,7 +16925,8 @@ async function reconcileRuns(o) {
     if (handled.has(streamPath)) continue;
     handled.add(streamPath);
     const isAlive = o.isAlive ?? runIsAlive;
-    const lock = isAlive(sidecar) ? o.state.acquireRun(sidecar.role, o.maxConcurrentAgents) : null;
+    const lock = isAlive(sidecar) ? o.state.acquireRun(sidecar.role, o.maxConcurrentAgents, o.roleConcurrency?.[sidecar.role] ?? 1) : null;
+    const ticketLock = isAlive(sidecar) && sidecar.ticketRecordId ? o.state.acquireTicket(sidecar.ticketRecordId) : null;
     const work = (async () => {
       try {
         const result = await reattachRun(streamPath, sidecar, o.emit, {
@@ -16813,6 +16946,7 @@ async function reconcileRuns(o) {
         o.emit.warn(`could not reattach ${sidecar.role} run ${streamPath}: ${e.message}`, { step: "agent" });
       } finally {
         if (lock?.ok) lock.release();
+        if (ticketLock?.ok) ticketLock.release();
       }
     })();
     if (isAlive(sidecar)) {
@@ -16937,6 +17071,7 @@ function configChangedAfter(files, startedAt) {
   }
   return null;
 }
+var TICKET_ROLES = /* @__PURE__ */ new Set(["dev", "design", "qa"]);
 var SPAWN_PARK_AFTER = 3;
 var SpawnBreaker = class {
   states = /* @__PURE__ */ new Map();
@@ -17034,46 +17169,69 @@ async function runOnePassUnguarded(o) {
   );
   const started = [];
   const skipped = [];
-  for (const role of order) {
-    if (!breaker.allows(role)) {
-      skipped.push({ role, reason: "agent recently failed to start \u2014 waiting before retry" });
-      continue;
-    }
-    const lock = o.state.acquireRun(role, o.maxConcurrentAgents);
-    if (!lock.ok) {
-      skipped.push({ role, reason: lock.reason });
-      continue;
-    }
-    started.push(role);
-    const run2 = spawn7(role, decision, ctx).then(() => {
-      breaker.recordSuccess(role);
-      clearShipAttention(o.state, `role_parked:${role}`);
-    }).catch(async (e) => {
-      const message = e.message;
-      if (!(e instanceof AgentSpawnError)) {
-        emit.warn(`${role} agent run failed: ${message}`, { step: "agent", role });
-        return;
+  const roleCap = (role) => TICKET_ROLES.has(role) ? o.roleConcurrency?.[role] ?? 1 : 1;
+  const live = new Map(order.map((r) => [r, 0]));
+  while (live.size) {
+    for (const role of order) {
+      const count = live.get(role);
+      if (count === void 0) continue;
+      if (!breaker.allows(role)) {
+        if (count === 0) skipped.push({ role, reason: "agent recently failed to start \u2014 waiting before retry" });
+        live.delete(role);
+        continue;
       }
-      const report = breaker.recordFailure(role, message);
-      if (report.firstOfMessage || report.parked) {
-        emit.warn(`${role} agent could not start: ${message}`, { step: "agent", role });
+      const lock = o.state.acquireRun(role, o.maxConcurrentAgents, roleCap(role));
+      if (!lock.ok) {
+        if (count === 0) skipped.push({ role, reason: lock.reason });
+        live.delete(role);
+        continue;
       }
-      if (report.parked) {
-        emit.error(
-          `${role} parked for ${Math.round(report.retryInMs / 1e3)}s after ${report.failures} consecutive failed starts \u2014 check that ship.agent.bin is installed and on PATH`
-        );
-        await raiseShipAttention({ state: o.state, emit, route: o.route, ship: o.ship }, {
-          kind: "role_parked",
-          key: `role_parked:${role}`,
-          message: `${role} agent is parked after ${report.failures} failed starts: ${message}`,
-          since: (/* @__PURE__ */ new Date()).toISOString()
-        });
+      started.push(role);
+      let ready = () => {
+      };
+      const settled = new Promise((resolve6) => {
+        ready = resolve6;
+      });
+      const run2 = spawn7(role, decision, ctx, { ready }).then(() => {
+        breaker.recordSuccess(role);
+        clearShipAttention(o.state, `role_parked:${role}`);
+      }).catch(async (e) => {
+        const message = e.message;
+        if (!(e instanceof AgentSpawnError)) {
+          emit.warn(`${role} agent run failed: ${message}`, { step: "agent", role });
+          return;
+        }
+        const report = breaker.recordFailure(role, message);
+        if (report.firstOfMessage || report.parked) {
+          emit.warn(`${role} agent could not start: ${message}`, { step: "agent", role });
+        }
+        if (report.parked) {
+          emit.error(
+            `${role} parked for ${Math.round(report.retryInMs / 1e3)}s after ${report.failures} consecutive failed starts \u2014 check that ship.agent.bin is installed and on PATH`
+          );
+          await raiseShipAttention({ state: o.state, emit, route: o.route, ship: o.ship }, {
+            kind: "role_parked",
+            key: `role_parked:${role}`,
+            message: `${role} agent is parked after ${report.failures} failed starts: ${message}`,
+            since: (/* @__PURE__ */ new Date()).toISOString()
+          });
+        }
+      }).finally(() => {
+        lock.release();
+        ready(false);
+      });
+      if (o.inFlight) {
+        const set = o.inFlight;
+        set.add(run2);
+        void run2.finally(() => set.delete(run2));
       }
-    }).finally(() => lock.release());
-    if (o.inFlight) {
-      const set = o.inFlight;
-      set.add(run2);
-      void run2.finally(() => set.delete(run2));
+      if (roleCap(role) <= 1) {
+        live.delete(role);
+        continue;
+      }
+      const tookTicket = await settled;
+      if (tookTicket && count + 1 < roleCap(role)) live.set(role, count + 1);
+      else live.delete(role);
     }
   }
   await publishShipAttention(o);
@@ -17122,6 +17280,7 @@ async function reconcileForRoute(ctx, o) {
     emit,
     state: o.state,
     maxConcurrentAgents: o.maxConcurrentAgents,
+    roleConcurrency: o.roleConcurrency,
     inFlight: o.inFlight,
     agentLogKey: async (role) => (await resolveSeatKey(route, role, ctx.getSessionStore)).apiKey,
     afterRun: async (sc, result) => {
@@ -17162,8 +17321,18 @@ async function reconcileForRoute(ctx, o) {
     }
   });
 }
-async function runRoleAgent(role, decision, ctx) {
+async function runRoleAgent(role, decision, ctx, hooks) {
+  const held = {};
+  try {
+    await runRoleAgentLocked(role, decision, ctx, hooks, held);
+  } finally {
+    held.release?.();
+    hooks?.ready(false);
+  }
+}
+async function runRoleAgentLocked(role, decision, ctx, hooks, held) {
   const { route, ship, emit } = ctx;
+  const runId = randomBytes2(3).toString("hex");
   const identity = await resolveSeatKey(route, role, ctx.getSessionStore);
   if (identity.kind === "ship" && SEAT_KEY_ROLES.includes(role)) {
     emit.warn(`${role} writes as the ship, not its own agent: ${identity.reason}`, { step: "agent", role });
@@ -17186,8 +17355,13 @@ async function runRoleAgent(role, decision, ctx) {
         claimStatuses(role, contract).approved,
         claimStatuses(role, contract).building,
         (t) => dirForRepo(route, t.repo_id) !== null,
-        withHoldCheck(await tracker.claimAffinity(), decision.selectionInput)
+        withHoldCheck(await tracker.claimAffinity(), decision.selectionInput),
+        (t) => {
+          const got = ctx.state.acquireTicket(t.id);
+          return got.ok ? got.release : null;
+        }
       );
+      held.release = result.releaseTicket;
       if (result.contended.length) {
         emit.emit(`claim contended for ${result.contended.join(", ")} \u2014 moved to the next candidate`, {
           step: "select",
@@ -17224,6 +17398,11 @@ async function runRoleAgent(role, decision, ctx) {
         if (idx >= 0) decision.tickets[idx] = result.ticket;
         writeDigest({ route, ship, state: ctx.state, emit }, decision, role, ship.stateDir);
       }
+      writeDigest({ route, ship, state: ctx.state, emit }, decision, role, ship.stateDir, runId, {
+        ticket: result.ticket,
+        inFlight: (id) => ctx.state.ticketInFlight(id)
+      });
+      hooks?.ready(true);
       ticketHint = result.ticket.issue_id;
       workingId = result.ticket.id;
       const target = repoTargetFor(route, result.ticket.repo_id);
@@ -17249,6 +17428,7 @@ async function runRoleAgent(role, decision, ctx) {
     environment: await buildEnvironment(route, ship, ticketHint),
     apiKey: identity.apiKey,
     cycle: emit.cycle,
+    runId,
     ticket: ticketHint,
     repo: ticketRepo,
     ticketRecordId: workingId,
@@ -18292,6 +18472,19 @@ ${changed2.map((c) => `  - ${c}
         skipTests: flag("skip-tests"),
         shell: cfg.ship.shell,
         mergeOnly: command === "merge",
+        // ci_* modes: record the merge on the board when it lands on base,
+        // not only once CI confirms the release live (CREW-2820).
+        onBasePushed: async (merged) => {
+          remit.enter("reconcile");
+          await applyMergeStamp(
+            tracker,
+            new Map(merged.map((m) => [m.ticket.issue_id, m.sha])),
+            merged.map((m) => m.ticket),
+            remit,
+            dryRun,
+            target.dir
+          );
+        },
         // `deploy` is the "go now" button: it exists for a commit a previous
         // deploy failed on, where nothing new will merge but the work is
         // genuinely unreleased.
@@ -18676,7 +18869,7 @@ ${cu.tail.trimEnd()}
 `);
           break;
         }
-        const fleetLock = state.acquireRun(w.role, cfg.ship.maxConcurrentAgents);
+        const fleetLock = state.acquireRun(w.role, cfg.ship.maxConcurrentAgents, cfg.ship.roleConcurrency[w.role] ?? 1);
         if (!fleetLock.ok) {
           wemit.emit(`${w.role} skipped this cycle \u2014 ${fleetLock.reason}`);
           if (!skipInlineRelease) await releaseFleet();
@@ -18699,8 +18892,20 @@ ${cu.tail.trimEnd()}
               claimStatuses(w.role, contract).approved,
               claimStatuses(w.role, contract).building,
               (t) => dirForRepo(w.route, t.repo_id) !== null,
-              withHoldCheck(await fleetTracker.claimAffinity(), w.decision.selectionInput)
+              withHoldCheck(await fleetTracker.claimAffinity(), w.decision.selectionInput),
+              (t) => {
+                const got = state.acquireTicket(t.id);
+                return got.ok ? got.release : null;
+              }
             );
+            if (result.releaseTicket) {
+              const roleLock = lock;
+              const releaseTicket = result.releaseTicket;
+              lock = { release: () => {
+                roleLock?.release();
+                releaseTicket();
+              } };
+            }
             if (result.contended.length) {
               wemit.emit(`claim contended for ${result.contended.join(", ")} \u2014 moved to the next candidate`, {
                 step: "select",
@@ -18872,7 +19077,7 @@ ${cu.tail.trimEnd()}
       const tracker2 = new Tracker(route, cfg.ship);
       while (current) {
         if (!dryRun) {
-          const got = state.acquireRun(current, cfg.ship.maxConcurrentAgents);
+          const got = state.acquireRun(current, cfg.ship.maxConcurrentAgents, cfg.ship.roleConcurrency[current] ?? 1);
           if (!got.ok) {
             emit.emit(`${current} skipped this cycle \u2014 ${got.reason}`);
             if (explicitRole) {
@@ -18900,8 +19105,20 @@ ${cu.tail.trimEnd()}
               claimStatuses(current, contract).approved,
               claimStatuses(current, contract).building,
               (t) => dirForRepo(route, t.repo_id) !== null,
-              withHoldCheck(await tracker2.claimAffinity(), decision.selectionInput)
+              withHoldCheck(await tracker2.claimAffinity(), decision.selectionInput),
+              (t) => {
+                const got = state.acquireTicket(t.id);
+                return got.ok ? got.release : null;
+              }
             );
+            if (result.releaseTicket) {
+              const roleLock = lock;
+              const releaseTicket = result.releaseTicket;
+              lock = { release: () => {
+                roleLock?.release();
+                releaseTicket();
+              } };
+            }
             if (result.contended.length) {
               emit.emit(`claim contended for ${result.contended.join(", ")} \u2014 moved to the next candidate`, {
                 step: "select",
@@ -19125,6 +19342,7 @@ ${cu.tail.trimEnd()}
           ship: cfg.ship,
           state,
           maxConcurrentAgents: cfg.ship.maxConcurrentAgents,
+          roleConcurrency: cfg.ship.roleConcurrency,
           spawnBreaker,
           configFile: cfg.configFile,
           newEmitter: () => new Emitter({
@@ -21600,6 +21818,7 @@ watermark:  ${state.watermark()}
             } else if (p.state === "ok") passed++;
           }
         }
+        for (const message of roleCapWarnings(cfg.ship)) problems.push({ severity: "note", kind: "role_cap_above_ship_cap", message });
         problems.push(...attentionProblems(openShipAttention(state), problems));
         if (problems.some((p) => p.severity === "blocker")) process.exitCode = 1;
         process.stdout.write(`${JSON.stringify({ offline: flag("offline"), pushAuth, tools: toolRows, problems, passed }, null, 2)}
@@ -21611,6 +21830,8 @@ watermark:  ${state.watermark()}
 routes:            ${cfg.routes.map((c) => c.route).join(", ")}
 `
       );
+      for (const w of roleCapWarnings(cfg.ship)) process.stdout.write(`role concurrency: WARN ${w}
+`);
       try {
         const evFile = eventFileFor(cfg.ship.stateDir);
         const evSize = existsSync34(evFile) ? statSync10(evFile).size : 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tablation/crew",
-  "version": "0.80.0",
+  "version": "0.81.0",
   "description": "A standing team of headless agents that picks work off a Tablation board, does it on a machine you control, and reports back.",
   "type": "module",
   "license": "MIT",