@tablation/crew 0.24.0 → 0.26.0

package/crew.example.yaml

@@ -76,6 +76,12 @@ routes:
 
     worktreePrefix: "myproject-issue-"
 
+    # A repo may also be written as an object to name its worktree directory
+    # for this ship only (CREW-1504) — a template over {dir} {issue} {number}
+    # {key} {slug} {tag} {prefix} {role}. Outranks the repo's own
+    # `worktrees.name`, which outranks worktreePrefix; see docs/REPO_SPEC.md.
+    #   My Product: { dir: "/home/me/src/my-product", worktreeName: "{dir}-{issue}" }
+
     # Opt this route's ship into Host Passengers for this route's workspace
     # (ISSUE-644): `crew connect` syncs this onto that workspace's own Ships
     # row. Config-truth lives here, on the machine — never edit a Ships row
@@ -100,6 +106,9 @@ routes:
     # Only needed for a self-hosted tracker.
     # baseUrl: "https://app.tablation.com"
     apiKey: "REPLACE_ME"             # or omit if `ship.apiKey` covers this workspace too
+    # With no apiKey (and no apiKeyFile/apiKeyVar) crew reads CREW_API_KEY from
+    # its process environment. Under launchd that must be set in the job's own
+    # environment, not exported from an interactive shell.
 
     # Where release state should be SHOWN is a fact about this machine and the
     # person watching it, not about the code — so unlike every other hook,

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { resolve as resolve4, dirname as dirname11, join as join20, basename as basename7 } from "path";
+import { resolve as resolve4, dirname as dirname11, join as join20, basename as basename8 } from "path";
 import { fileURLToPath } from "url";
 import { hostname as hostname2, homedir as homedir5 } from "os";
 import { spawnSync as spawnSync3 } from "child_process";
@@ -84,6 +84,27 @@ var TOP_LEVEL = /* @__PURE__ */ new Set([
 ]);
 var BRANCH_KEYS = /* @__PURE__ */ new Set(["base", "name", "push", "remote"]);
 var PLACEHOLDER = /\{(key|number|slug|role|prefix|tag)\}/g;
+var WORKTREE_PLACEHOLDERS = ["dir", "issue", "number", "key", "slug", "role", "prefix", "tag"];
+function worktreeNameProblem(template) {
+  const valid = `Valid placeholders: ${WORKTREE_PLACEHOLDERS.map((p) => `{${p}}`).join(" ")}.`;
+  if (template.trim() === "") return `must be a non-empty string. ${valid}`;
+  if (/[/\\]/.test(template)) {
+    return "must not contain a path separator \u2014 a worktree is cut beside the checkout, not inside a directory of its own";
+  }
+  const stripped = template.replace(/\{([^{}]*)\}/g, (_m, name) => {
+    if (!WORKTREE_PLACEHOLDERS.includes(name)) return "\0";
+    return "";
+  });
+  if (stripped.includes("\0")) {
+    const bad = [...template.matchAll(/\{([^{}]*)\}/g)].map((m) => m[1] ?? "").filter((n) => !WORKTREE_PLACEHOLDERS.includes(n));
+    return `names unknown placeholder ${bad.map((b) => `{${b}}`).join(", ")}. ${valid}`;
+  }
+  if (/[{}]/.test(stripped)) return `has an unbalanced brace. ${valid}`;
+  if (!/\{(issue|number|key|slug|tag)\}/.test(template)) {
+    return "names no per-ticket placeholder \u2014 every ticket would get the same worktree. Use at least one of {issue} {number} {key} {slug} {tag}.";
+  }
+  return null;
+}
 var RELEASE_KEYS = /* @__PURE__ */ new Set([
   "mode",
   "ship",
@@ -132,7 +153,7 @@ function parseRepoConfig(text, file) {
   rejectUnknown(raw.release?.ci, CI_KEYS, "release.ci", file);
   rejectUnknown(raw.release?.verify, VERIFY_KEYS, "release.verify", file);
   rejectUnknown(raw.branch, BRANCH_KEYS, "branch", file);
-  rejectUnknown(raw.worktrees, /* @__PURE__ */ new Set(["copy", "prefix"]), "worktrees", file);
+  rejectUnknown(raw.worktrees, /* @__PURE__ */ new Set(["copy", "prefix", "name"]), "worktrees", file);
   rejectUnknown(raw.docs, /* @__PURE__ */ new Set(["triagePolicy", "designGuide"]), "docs", file);
   if (raw.version === void 0) throw new RepoConfigError(`${file}: version is required`);
   if (raw.version !== SPEC_VERSION) {
@@ -167,7 +188,13 @@ function parseRepoConfig(text, file) {
       `${file}: worktrees.prefix ("${prefixRaw}") must not contain a path separator \u2014 a worktree is cut beside the checkout, not inside a directory of its own`
     );
   }
+  const nameRaw = raw.worktrees?.name;
+  if (nameRaw !== void 0) {
+    const problem = typeof nameRaw === "string" ? worktreeNameProblem(nameRaw) : "must be a string";
+    if (problem) throw new RepoConfigError(`${file}: worktrees.name ("${String(nameRaw)}") ${problem}`);
+  }
   const worktrees2 = {
+    ...nameRaw !== void 0 ? { name: String(nameRaw) } : {},
     copy: (copyRaw ?? []).map((c) => String(c)),
     // Empty means "not declared" here; the effective config fills it in, since
     // only that layer knows the ship's setting and the checkout's directory.
@@ -358,6 +385,10 @@ function renderBranchName(template, ctx) {
     }
   });
 }
+function renderWorktreeName(template, ctx) {
+  const issue = (ctx.tag ?? ctx.key).toLowerCase();
+  return renderBranchName(template.replace(/\{dir\}/g, ctx.dir).replace(/\{issue\}/g, issue), ctx);
+}
 function defaultWorktreePrefix(dir) {
   const name = basename(dir.replace(/[/\\]+$/, ""));
   return name ? `${name}-issue-` : "issue-";
@@ -389,6 +420,10 @@ function resolveRepoConfig(repo, ship, dir) {
     provenance[key] = "default";
     return fallback;
   };
+  if (ship?.worktrees?.nameOverride) {
+    if (repo?.worktrees.name) shadowed.push("worktrees.name");
+    provenance["worktrees.name"] = "ship";
+  } else if (repo?.worktrees.name) provenance["worktrees.name"] = "repo";
   const hooks = {};
   const labels = {};
   for (const h of HOOK_NAMES) {
@@ -424,7 +459,8 @@ function resolveRepoConfig(repo, ship, dir) {
         repo?.worktrees.prefix || void 0,
         ship?.worktrees?.prefix,
         defaultWorktreePrefix(dir)
-      )
+      ),
+      ...ship?.worktrees?.nameOverride || repo?.worktrees.name ? { name: ship?.worktrees?.nameOverride || repo?.worktrees.name } : {}
     },
     docs: repo?.docs ?? {},
     branch: {
@@ -525,7 +561,8 @@ function effectiveBranchTemplate(cfg, prefix) {
   if (cfg.provenance["branch.name"] !== "default") return cfg.branch.name;
   return prefix ? "{prefix}-{number}" : "issue-{number}";
 }
-function effectiveWorktreeDirName(cfg, dir, branchName, number) {
+function effectiveWorktreeDirName(cfg, dir, branchName, number, renderName) {
+  if (cfg.worktrees.name && renderName) return renderName(cfg.worktrees.name);
   if (cfg.provenance["worktrees.prefix"] !== "default") return `${cfg.worktrees.prefix}${number}`;
   return `${basename(dir.replace(/[/\\]+$/, ""))}-${branchName}`;
 }
@@ -623,7 +660,12 @@ var ROUTE_KEYS = /* @__PURE__ */ new Set([
   "promptSet",
   "hostPassengers"
 ]);
-var REPO_ENTRY_KEYS = /* @__PURE__ */ new Set(["dir", "hooks", "labels", "release", "branch", "hostPassengers"]);
+function parseWorktreeName(v, where, file) {
+  const problem = typeof v === "string" ? worktreeNameProblem(v) : "must be a string";
+  if (problem) throw new ConfigError(`${file}: ${where}.worktreeName ("${String(v)}") ${problem}`);
+  return String(v);
+}
+var REPO_ENTRY_KEYS = /* @__PURE__ */ new Set(["dir", "hooks", "labels", "release", "branch", "hostPassengers", "worktreeName"]);
 var BRANCH_OVERRIDE_KEYS = /* @__PURE__ */ new Set(["base", "name", "push", "remote"]);
 var RELEASE_OVERRIDE_KEYS = /* @__PURE__ */ new Set([
   "mode",
@@ -959,7 +1001,7 @@ function parseOneRoute(c, where, file, base, stateDir, raw, missing, crewHome) {
         const e = entry;
         rejectUnknownKeys(e, REPO_ENTRY_KEYS, `${where}.repos.${name}`, file);
         repoDirs[name] = expand(String(missing.req(e.dir, `${where}.repos.${name}.dir`) || ""), base);
-        if (e.hooks || e.labels || e.release || e.branch || e.hostPassengers !== void 0) {
+        if (e.hooks || e.labels || e.release || e.branch || e.hostPassengers !== void 0 || e.worktreeName !== void 0) {
           repoOverrides[name] = {
             hooks: e.hooks,
             labels: e.labels,
@@ -969,7 +1011,8 @@ function parseOneRoute(c, where, file, base, stateDir, raw, missing, crewHome) {
             // shape as one that never had the key, and existing callers
             // compare this literally.
             ...e.branch ? { branch: parseBranchOverride(e.branch, `${where}.repos.${name}`, file) } : {},
-            ...e.hostPassengers !== void 0 ? { hostPassengers: e.hostPassengers === true } : {}
+            ...e.hostPassengers !== void 0 ? { hostPassengers: e.hostPassengers === true } : {},
+            ...e.worktreeName !== void 0 ? { worktreeName: parseWorktreeName(e.worktreeName, `${where}.repos.${name}`, file) } : {}
           };
         }
       } else {
@@ -1065,8 +1108,10 @@ function resolveApiKey(r) {
       if (m) return (m[1] ?? "").trim().replace(/^["']|["']$/g, "");
     }
   }
+  const fromEnv = process.env.CREW_API_KEY?.trim();
+  if (fromEnv) return fromEnv;
   throw new ConfigError(
-    `route "${r.route}": no API key (apiKey, or ${r.apiKeyVar ?? "VAR"} in ${r.apiKeyFile ?? "<unset>"})`
+    `route "${r.route}": no API key (looked for, in order: apiKey; ${r.apiKeyVar ?? "VAR"} in ${r.apiKeyFile ?? "<unset>"}; CREW_API_KEY in the environment)`
   );
 }
 var KEYCHAIN_ELIGIBLE_ROUTES = /* @__PURE__ */ new WeakSet();
@@ -1475,6 +1520,7 @@ var State = class _State {
     const failed = `.deploy-failed-sha-${suffix}`;
     const gateFailed = `.test-gate-failed-${suffix}`;
     const gateReported = `.test-gate-reported-${suffix}`;
+    const heldReported = `.release-held-${suffix}`;
     const read = (f) => {
       try {
         return readFileSync3(this.path(f), "utf8").trim() || null;
@@ -1525,6 +1571,20 @@ var State = class _State {
         rmSync(this.path(gateFailed), { force: true });
       },
       /** Whether the board was already told about this head's red gate. */
+      heldReported: () => {
+        try {
+          return readFileSync3(this.path(heldReported), "utf8").replace(/\n$/, "") || null;
+        } catch {
+          return null;
+        }
+      },
+      noteHeldReported: (signature) => {
+        writeFileSync(this.path(heldReported), `${signature}
+`);
+      },
+      clearHeldReported: () => {
+        rmSync(this.path(heldReported), { force: true });
+      },
       testGateReported: (sha) => read(gateReported) === sha,
       noteTestGateReported: (sha) => {
         writeFileSync(this.path(gateReported), `${sha}
@@ -3934,15 +3994,18 @@ function blockerInfoMap(tickets, extra = []) {
 }
 function computeBlockedIds(tickets, info) {
   const blocked = /* @__PURE__ */ new Set();
-  for (const t of tickets) {
-    const unresolved = (t.blocked_by ?? []).some((id) => {
-      const status2 = info[id]?.status;
-      return status2 !== void 0 && !RESOLVED_STATUSES.has(status2);
-    });
-    if (unresolved) blocked.add(t.id);
-  }
+  for (const t of tickets) if (unresolvedBlockers(t, info).length > 0) blocked.add(t.id);
   return blocked;
 }
+function unresolvedBlockers(t, info) {
+  return (t.blocked_by ?? []).filter((id) => {
+    const status2 = info[id]?.status;
+    return status2 !== void 0 && !RESOLVED_STATUSES.has(status2);
+  });
+}
+function describeUnresolved(t, info) {
+  return unresolvedBlockers(t, info).map((id) => `${info[id]?.issue_tag ?? info[id]?.issue_id ?? "?"} (${info[id]?.status ?? "unknown"})`).join(", ");
+}
 function sweepDiagnostics(tickets, info) {
   const dangling = [];
   const selfBlocked = [];
@@ -4258,9 +4321,12 @@ function buildingRoleHasWork(role, i) {
   }
   return { hasWork: false, reason: "nothing startable and no new comments" };
 }
+function qaCandidates(i) {
+  return withinWorkMode(notHeldByOtherShip(qaSlice(i.tickets), i), i.workModes).filter((t) => !isHeld(t, i.holds) && !i.blocked.has(t.id));
+}
 function qaRoleHasWork(i) {
   if (!i.seats.qa) return { hasWork: false, reason: "this ship does not crew that role" };
-  const n = withinWorkMode(notHeldByOtherShip(qaSlice(i.tickets), i), i.workModes).filter((t) => !isHeld(t, i.holds)).length;
+  const n = qaCandidates(i).length;
   return n > 0 ? { hasWork: true, reason: `${n} ticket(s) awaiting or in verification` } : { hasWork: false, reason: "nothing awaiting verification" };
 }
 function triageRoleHasWork(i) {
@@ -4276,7 +4342,7 @@ function roleHasWork(role, i) {
   return buildingRoleHasWork(role, i);
 }
 function roleCandidates(role, i) {
-  if (role === "qa") return withinWorkMode(notHeldByOtherShip(qaSlice(i.tickets), i), i.workModes).filter((t) => !isHeld(t, i.holds));
+  if (role === "qa") return qaCandidates(i);
   if (role === "triage") return triageSlice(i.tickets, i.seats.triage, i.workModes).filter((t) => !isHeld(t, i.holds));
   if (role === "pair") return [];
   const me = i.seats[role];
@@ -4610,19 +4676,35 @@ function qaDigest(i) {
     const repo = i.dirFor ? dir ?? "**NO CHECKOUT**" : "";
     return `| ${displayKey2(t)} | ${repo} | ${modeCell(t, i)} | ${t.status} | ${builtBy(t)} | ${who(t, i)} | ${filedBy(t, i)} | ${t.severity ?? "\u2014"} | ${t.priority ?? "\u2014"} | p${effectivePriority(t)} | ${branchCell(t)} | ${worktreeCell(t)} | ${t.updated_at.slice(0, 16)}Z | ${lastComment(i, t.id)} | ${n > 0 ? `**${n} new**` : "\u2014"} |`;
   };
+  const waiting = i.tickets.filter((t) => (t.status === "qa" || t.status === "fixed") && i.blocked.has(t.id));
+  const takeable = (status2) => i.tickets.filter((t) => t.status === status2 && !i.blocked.has(t.id));
+  const waitingTable = waiting.length === 0 ? "" : `
+### Waiting on blockers \u2014 not yours to verify yet
+
+A \`fixed\` or \`qa\` ticket whose \`Blocked by\` names something not yet resolved
+(\`verified\`, \`closed_deployed\`, \`closed_wont_fix\` or \`closed_duplicate\`) is held out of
+verification: its change needs the blocker released first. It becomes yours on
+the first poll after the last blocker resolves. No one needs to change the ticket.
+
+| ticket | status | blocked by |
+|---|---|---|
+${waiting.map((t) => `| ${displayKey2(t)} | ${t.status} | ${blockers(t, i)} |`).join("\n")}
+`;
   return stream([
     "## Current queue \u2014 built for you by the poll\n",
     '\nAlready filtered to your lane: every ticket at `qa` ("Verification" \u2014\nyours, unfinished) or `fixed` (nobody has checked it yet), from both\nbuilding lanes. Ticket bodies are deliberately omitted: fetch the full\nrecord and the comments of the one ticket you actually pick up. **Do not\nre-fetch the whole tracker.** This digest comes from the same API call the\npoll just made, moments ago.\n',
     '\n"new since last poll" counts comments from someone other than you since\nthe poll watermark \u2014 the same signal that woke this run.\n',
     "\n**`repo` is the checkout the ticket's work happens in** \u2014 an area spans\nseveral repositories, so the worktree you verify in sits beside THAT\ndirectory, not beside whichever one this session started in. A ticket\nmarked **NO CHECKOUT** is not yours: this ship has no clone of its\nrepository, and another ship may serve it.\n\n**`branch` is that repository's own branch for the ticket**, found there\nrather than derived. **`<name> (on origin only)`** means another ship built it\nand pushed it: it is testable \u2014 cut a worktree from the remote branch\n(`git worktree add <worktree> <name>`). **MISSING** means the branch is gone\nlocally AND on the remote, so there is nothing left to verify \u2014 say so on the ticket. A `\u2014` means the branch\ncould not be looked for at all, because the repo has no checkout here.\n\n**`worktree` is where that branch should be checked out**, `<repo>/../<worktree>`\n\u2014 rendered the same way the dev/design digest computes it, so you land in\nthe same directory the building lane used.\n",
     "\n### Still in verification \u2014 yours, unfinished (take these first)\n",
-    table(i.tickets.filter((t) => t.status === "qa"), i, header, row),
+    table(takeable("qa"), i, header, row),
     "\n### Awaiting verification, in pick order\n",
-    table(i.tickets.filter((t) => t.status === "fixed"), i, header, row)
+    table(takeable("fixed"), i, header, row),
+    ...waitingTable ? [waitingTable] : []
   ]);
 }
 
 // src/ticket-branch.ts
+import { basename as basename4 } from "path";
 function branchRenderer(t, role) {
   const { tag, prefix } = ticketBranchContext(t);
   return (template) => renderBranchName(template, { key: t.issue_id, title: t.title ?? void 0, role, tag, prefix });
@@ -4631,7 +4713,15 @@ function worktreeForTicket(dir, cfg, t, role) {
   const { prefix } = ticketBranchContext(t);
   const branchName = branchRenderer(t, role)(effectiveBranchTemplate(cfg, prefix));
   const number = t.issue_id.replace(/^\D+/, "");
-  return effectiveWorktreeDirName(cfg, dir, branchName, number);
+  const { tag } = ticketBranchContext(t);
+  return effectiveWorktreeDirName(cfg, dir, branchName, number, (template) => renderWorktreeName(template, {
+    dir: basename4(dir.replace(/[/\\]+$/, "")),
+    key: t.issue_id,
+    title: t.title ?? void 0,
+    role,
+    tag,
+    prefix
+  }));
 }
 function branchTemplates(cfg, t) {
   const { prefix } = ticketBranchContext(t);
@@ -4947,7 +5037,9 @@ function writeDigest(o, d, role, stateDir) {
     const repoFor = (dir) => {
       const hit = repoCache.get(dir);
       if (hit) return hit;
-      const cfg = resolveRepoConfig(loadRepoConfig(dir), void 0, dir);
+      const target = reposOf(o.route).find((r) => r.dir === dir);
+      const nameOverride = target ? o.route.repoOverrides[target.name]?.worktreeName : void 0;
+      const cfg = resolveRepoConfig(loadRepoConfig(dir), nameOverride ? { worktrees: { nameOverride } } : void 0, dir);
       repoCache.set(dir, cfg);
       return cfg;
     };
@@ -5312,7 +5404,7 @@ import { join as join7, dirname as dirname5 } from "path";
 import { createHash as createHash2 } from "crypto";
 
 // src/environment.ts
-import { basename as basename4 } from "path";
+import { basename as basename5 } from "path";
 var API_KEY_VAR = "CREW_API_KEY";
 function authorshipBullets(a, contract) {
   if (!a) return [];
@@ -5363,8 +5455,16 @@ function repoSection(r, key, heading) {
   const repo = r.config;
   const branchTemplate = effectiveBranchTemplate(repo, repoPrefix(repo));
   const branchName = branchExample(repo, key);
-  const worktreeName = effectiveWorktreeDirName(repo, r.dir, branchName, key.replace(/^\D+/, ""));
-  const worktreePattern = repo.provenance["worktrees.prefix"] !== "default" ? `${repo.worktrees.prefix}<number>` : `${basename4(r.dir.replace(/[/\\]+$/, ""))}-<branch>`;
+  const checkoutName = basename5(r.dir.replace(/[/\\]+$/, ""));
+  const worktreeName = effectiveWorktreeDirName(
+    repo,
+    r.dir,
+    branchName,
+    key.replace(/^\D+/, ""),
+    // The example ticket has no tag of its own, so `{issue}` is the key.
+    (template) => renderWorktreeName(template, { dir: checkoutName, key, title: "Fix the widget", role: "dev", prefix: repoPrefix(repo) })
+  );
+  const worktreePattern = repo.worktrees.name ?? (repo.provenance["worktrees.prefix"] !== "default" ? `${repo.worktrees.prefix}<number>` : `${checkoutName}-<branch>`);
   const lines = [
     "",
     heading,
@@ -6337,7 +6437,8 @@ async function guardRunHandoff(route, ship, tracker, role, workingId, log) {
     const cfg = resolveRepoConfig(loadRepoConfig(target.dir), {
       hooks: { ...route.hooks, ...o?.hooks },
       labels: { ...route.labels, ...o?.labels },
-      branch: { ...route.branch, ...o?.branch }
+      branch: { ...route.branch, ...o?.branch },
+      worktrees: { nameOverride: o?.worktreeName }
     }, target.dir);
     if (role === "qa") {
       await retireRunWorktree(tracker, target.dir, cfg, t, role, seatId, ship.name, log);
@@ -6562,10 +6663,16 @@ function checkGuards(cwd, base = "main") {
     detail: `working tree has ${changes.length} change(s)${untrackedNote}: ${names}${more}`
   };
 }
+function heldByBlockers(tickets, verifiedStatus, info) {
+  if (!info) return [];
+  return tickets.filter((t) => t.status === verifiedStatus && unresolvedBlockers(t, info).length > 0).map((ticket) => ({ ticket, blockers: describeUnresolved(ticket, info) }));
+}
+var describeHeld = (held) => held.map((h) => `${h.ticket.issue_tag ?? h.ticket.issue_id} held: blocked by ${h.blockers}`);
 var CHANGELOG_LINE = /^Changelog:[ \t]*(.*)$/gm;
 var BUMP_LINE = /^Bump:[ \t]*(major|minor|patch)\b/gim;
-function planMerge(cwd, tickets, contract, lastReleased, branchFor = (t) => branchForIssue(cwd, t.issue_id), base = "main") {
-  const verified = tickets.filter((t) => t.status === contract.statuses.verified).sort((a, b) => Number.parseInt(a.issue_id.replace(/^\D+/, ""), 10) - Number.parseInt(b.issue_id.replace(/^\D+/, ""), 10));
+function planMerge(cwd, tickets, contract, lastReleased, branchFor = (t) => branchForIssue(cwd, t.issue_id), base = "main", blockerInfo) {
+  const held = new Set(heldByBlockers(tickets, contract.statuses.verified, blockerInfo).map((h) => h.ticket.id));
+  const verified = tickets.filter((t) => t.status === contract.statuses.verified && !held.has(t.id)).sort((a, b) => Number.parseInt(a.issue_id.replace(/^\D+/, ""), 10) - Number.parseInt(b.issue_id.replace(/^\D+/, ""), 10));
   return verified.map((ticket) => {
     const branch = branchFor(ticket);
     if (!branch) {
@@ -6683,12 +6790,13 @@ function decideRelease(cwd, tickets, contract, opts = {}) {
   const lastTag = latestReleaseTag(cwd, pattern, "HEAD");
   const lastReleased = lastTag ? tagCommit(cwd, lastTag) : null;
   const head = resolve2(cwd, "HEAD") ?? "";
-  const merges = block ? [] : planMerge(cwd, tickets, contract, lastReleased, opts.branchFor ?? ((t) => branchForIssue(cwd, t.issue_id)), base);
+  const merges = block ? [] : planMerge(cwd, tickets, contract, lastReleased, opts.branchFor ?? ((t) => branchForIssue(cwd, t.issue_id)), base, opts.blockerInfo);
   const unreleasedCommits = lastReleased ? countCommits(cwd, `${lastReleased}..HEAD`) : 0;
   const unreleasedWork = lastReleased ? (gitOk(cwd, ["log", "--format=%s", `${lastReleased}..HEAD`]) ?? "").split("\n").filter((l) => l && !RELEASE_COMMIT_SUBJECT.test(l)).length : 0;
   return {
     block,
     merges,
+    held: heldByBlockers(tickets, contract.statuses.verified, opts.blockerInfo),
     head,
     lastTag,
     lastReleased,
@@ -7293,6 +7401,17 @@ function openReleaseCheckout(o) {
   }
   return { dir, branch, close };
 }
+function reportHeld(o, held) {
+  if (held.length === 0) {
+    o.state?.clearHeldReported?.();
+    return;
+  }
+  const lines = describeHeld(held);
+  const signature = lines.join("\n");
+  if (o.dryRun || o.state?.heldReported?.() === signature) return;
+  for (const line of lines) o.emit.emit(line, { step: "release" });
+  o.state?.noteHeldReported?.(signature);
+}
 async function runRelease(o) {
   const scoped = (msg) => o.scope ? `${o.scope}: ${msg}` : msg;
   const tagPattern = o.repo.release.tagPattern ?? "v*";
@@ -7301,11 +7420,13 @@ async function runRelease(o) {
   const decision = decideRelease(o.cwd, o.tickets, o.contract, {
     tagPattern,
     base: o.repo.branch.base,
+    blockerInfo: o.blockerInfo,
     // CREW-1364: a branch another ship built and pushed at `fixed` exists
     // here only on the remote. Materialize it so the squash below has a ref.
     // A dry run only looks.
     branchFor: (t) => o.dryRun ? locateBranchForTicket(o.cwd, o.repo, t)?.branch ?? null : materializeBranchForTicket(o.cwd, o.repo, t)
   });
+  reportHeld(o, decision.held);
   if (!fresh.ok) {
     o.emit.error(scoped(`refusing to release \u2014 ${fresh.why}; a person has to reconcile the two`));
     return { merged: [], conflicts: [], deployed: false, stopped: fresh.why, decision };
@@ -8974,7 +9095,7 @@ async function showLogEntry(route, entryId, opts = {}) {
 
 // src/repos-cmd.ts
 import { homedir as homedir3 } from "os";
-import { basename as basename5, resolve as resolve3 } from "path";
+import { basename as basename6, resolve as resolve3 } from "path";
 import { isMap, isSeq, parseDocument, stringify as stringify2 } from "yaml";
 var ReposError = class extends Error {
 };
@@ -9046,7 +9167,7 @@ function configuredRepos(text, route, base) {
     });
   }
   const dir = m.get("dir");
-  return dir ? [{ name: basename5(String(dir)), dir: expandDir(String(dir), base) }] : [];
+  return dir ? [{ name: basename6(String(dir)), dir: expandDir(String(dir), base) }] : [];
 }
 function planRepoAdd(i) {
   const doc = parseDocument(i.text);
@@ -9058,7 +9179,7 @@ function planRepoAdd(i) {
     throw new ReposError(`${target} is already configured on route ${i.route}`);
   }
   const matched = matchRepoName(i.origin, i.resolved);
-  const name = matched ?? i.name ?? normalizeRemote(i.origin)?.split("/").pop() ?? basename5(target);
+  const name = matched ?? i.name ?? normalizeRemote(i.origin)?.split("/").pop() ?? basename6(target);
   let warning;
   if (!matched) {
     const known = Object.values(i.resolved?.repoNames ?? {});
@@ -9222,14 +9343,14 @@ function schedulerInstalled(plan, exists, crontab) {
 
 // src/worktree-sweep.ts
 import { existsSync as existsSync15 } from "fs";
-import { basename as basename6 } from "path";
+import { basename as basename7 } from "path";
 function planWorktreeSweep(target, tickets, contract) {
   const terminal = new Set(contract.statuses.resolved.filter((s) => s !== contract.statuses.verified));
   const verified = contract.statuses.verified;
   const byNumber = new Map(tickets.map((t) => [t.issue_id.replace(/^\D+/, ""), t]));
   const actions = [];
   for (const w of worktrees(target.dir)) {
-    const m = /(?:^|-)(\d+)$/.exec(basename6(w.path));
+    const m = /(?:^|-)(\d+)$/.exec(basename7(w.path));
     if (!m) continue;
     const ticket = byNumber.get(m[1]);
     if (!ticket) continue;
@@ -10432,7 +10553,8 @@ async function buildEnvironment(route, ship, ticket) {
       config: resolveRepoConfig(loadRepoConfig(t.dir), {
         hooks: { ...route.hooks, ...o?.hooks },
         labels: { ...route.labels, ...o?.labels },
-        branch: { ...route.branch, ...o?.branch }
+        branch: { ...route.branch, ...o?.branch },
+        worktrees: { nameOverride: o?.worktreeName }
       }, t.dir)
     };
   });
@@ -11027,7 +11149,7 @@ ${changed2.map((c) => `  - ${c}
           // that declares its own `worktrees.prefix` shadows either, and
           // `doctor` reports that the way it reports every other shadowed
           // setting.
-          worktrees: { prefix: shipWorktreePrefixFor(c) ?? await areaWorktreePrefix(c, id) }
+          worktrees: { prefix: shipWorktreePrefixFor(c) ?? await areaWorktreePrefix(c, id), nameOverride: o?.worktreeName }
         }, t.dir)
       };
     }));
@@ -11084,7 +11206,7 @@ ${changed2.map((c) => `  - ${c}
         labels: { ...c.labels, ...o?.labels },
         release: mergeRouteRelease(c.release, o?.release),
         branch: { ...c.branch, ...o?.branch },
-        worktrees: { prefix: shipWorktreePrefixFor(c) }
+        worktrees: { prefix: shipWorktreePrefixFor(c), nameOverride: o?.worktreeName }
       }, target.dir);
       const problems = validateEffective(repo);
       for (const p of problems) remit.warn(`${scope}: ${p}`);
@@ -11166,11 +11288,13 @@ ${changed2.map((c) => `  - ${c}
         releaseModes
       );
       reportUnplaceable(c.route, unplaceable, tracker.contract.statuses.verified, remit);
+      const blockerInfo = blockerInfoMap(all, await tracker.ticketsByIds(missingBlockerIds(all)));
       const outcome = await runRelease({
         cwd: target.dir,
         repo,
         contract: tracker.contract,
         tickets,
+        blockerInfo,
         emit: remit,
         scope,
         state: state.release(scope),
@@ -13135,7 +13259,7 @@ Signed in as ${result.identity.email} \u2014 minted an API key in workspace "${r
               // `synthesis-tabl-123`. `worktreePrefix` above is kept for
               // config-provenance display; this is the field that actually
               // describes where a worktree lands by default.
-              worktreeDirPattern: r.config.provenance["worktrees.prefix"] !== "default" ? `${r.config.worktrees.prefix}<number>` : `${basename7(r.dir.replace(/[/\\]+$/, ""))}-<branch>`,
+              worktreeDirPattern: r.config.worktrees.name ?? (r.config.provenance["worktrees.prefix"] !== "default" ? `${r.config.worktrees.prefix}<number>` : `${basename8(r.dir.replace(/[/\\]+$/, ""))}-<branch>`),
               worktreeParent: resolvePath(r.dir, "..")
             })),
             waiting: waiting ? { ticket: waiting.ticket, since: waiting.since, streak: fairness.streak() } : null
@@ -13187,6 +13311,17 @@ watermark:  ${state.watermark()}
 `);
         process.stdout.write(`releaser:   ${r.name} \u2014 ${await releaserLine(statusTracker, route.route, r.name, r.config.release)}
 `);
+      }
+      try {
+        const open = await statusTracker.openTickets();
+        const held = heldByBlockers(
+          open,
+          statusTracker.contract.statuses.verified,
+          blockerInfoMap(open, await statusTracker.ticketsByIds(missingBlockerIds(open)))
+        );
+        for (const line of describeHeld(held)) process.stdout.write(`release:    ${line}
+`);
+      } catch {
       }
       if (waiting) {
         process.stdout.write(
@@ -13223,10 +13358,10 @@ routes:            ${cfg.routes.map((c) => c.route).join(", ")}
       );
       for (const r of await resolvedRepos(route)) {
         const { config } = r;
-        const worktreePattern = config.provenance["worktrees.prefix"] !== "default" ? `${config.worktrees.prefix}<number>` : `${basename7(r.dir.replace(/[/\\]+$/, ""))}-${effectiveBranchTemplate(config, void 0)}`;
+        const worktreePattern = config.worktrees.name ?? (config.provenance["worktrees.prefix"] !== "default" ? `${config.worktrees.prefix}<number>` : `${basename8(r.dir.replace(/[/\\]+$/, ""))}-${effectiveBranchTemplate(config, void 0)}`);
         process.stdout.write(
           `${`repo ${r.name}:`.padEnd(19)}${r.dir}
-                   worktrees at ../${worktreePattern} (${config.provenance["worktrees.prefix"] ?? "default"}), branch ${config.branch.name}
+                   worktrees at ../${worktreePattern} (${config.provenance["worktrees.name"] ?? config.provenance["worktrees.prefix"] ?? "default"}), branch ${config.branch.name}
                    requires ${config.platform} \u2014 ${satisfies(host, config.platform) ? "OK" : "MISMATCH"}
 `
         );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tablation/crew",
-  "version": "0.24.0",
+  "version": "0.26.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",

package/prompts/default/personas/common.md

@@ -684,9 +684,42 @@ post. They record who filed the ticket and from where. The block lists a column
 only when this workspace has it, so a column it does not name is not yours to set.
 
 Name the ticket you were working when you noticed it in the new ticket's
-description. Only put it in the new ticket's `blocked by` column if your
-own ticket genuinely cannot proceed without the new one being fixed
-first — merely having noticed it nearby is not a dependency.
+description. Only add the new ticket to **your own ticket's** `blocked_by`
+(the column named `blocked by` in the Environment section) if your own
+ticket genuinely cannot proceed without the new one being fixed first —
+merely having noticed it nearby is not a dependency. The dependency always
+points from the ticket that waits to the ticket it waits on, never the
+other way round.
+
+### Work your ticket needs in another repository
+
+Out-of-scope breakage and **in-scope work that lives somewhere else** are
+different things. If your ticket's acceptance depends on a change in another
+repository (or on a change this repository cannot make), do not ship a
+stand-in for the missing piece and hand the ticket off. A stand-in whose UI,
+docs or hints promise behaviour the dependency has not delivered is a defect
+that QA passes and the release phase ships. Instead:
+
+1. File that work as its own ticket in the owning repository's project (the
+   Environment section names the projects and repos; if the owning repo is
+   not listed there, file it against the project and say which repo in the
+   description), setting `repo_id`, `project_id`, `filed_by_id` and
+   `ship_id` as in the filing block, and naming your ticket in its
+   description.
+2. Add the new ticket's id to **your own ticket's** `blocked_by`.
+3. Post a comment on your ticket naming each dependency and what it must
+   deliver.
+4. Set your ticket back to `accepted`. The poll's sweep parks it at
+   `blocked` and restores it to `accepted` once every blocker resolves.
+   In a `hybrid` project keep `assignee_id` as your own seat (an unassigned
+   hybrid ticket is off limits to every lane); in an `automatic` project
+   clear it as for any other re-queue.
+5. Leave the branch and worktree in place, committed and pushed if they hold
+   work, so the lane that resumes the ticket continues from them.
+
+Hand a ticket off as `fixed` only when the branch works against
+dependencies that are already released. A hand-off comment that says "worth
+separate tickets" for work the ticket needs is a hand-off that is not ready.
 
 ## Step 4 — you never merge, and you never deploy
 

package/prompts/default/personas/lane-design.md

@@ -82,6 +82,12 @@ stopping for this run, do the following instead:
     is actually blocked on the operator's input, not as a substitute for
     the ordinary ending above.
 
+  Before you post, check the comment: it must not name needed-but-unfiled
+  work. A design that depends on a change in another repository files that
+  ticket and links it in your ticket's `blocked_by` (see "Work your ticket
+  needs in another repository"), rather than listing it as a loose
+  follow-up.
+
   Either way, stop this ticket's work for this run once the flag is set and
   the comment posted. The operator reviews what you posted and takes it
   from there:

package/prompts/default/personas/lane-dev.md

@@ -24,4 +24,11 @@ release phase merges and ships it) or hands it back to you as `in_progress`
 with a comment saying what still fails. Take that bounce seriously — it is
 the only reading your work gets before it is deployed.
 
-**No extra steps.** Follow the shared policy as written.
+**Before you hand a ticket to QA, check the hand-off comment.** It must not
+name needed-but-unfiled work: anything the ticket's acceptance depends on in
+another repository is a filed ticket in your ticket's `blocked_by` (see "Work
+your ticket needs in another repository"), not a line saying "worth separate
+tickets". If it would name such work, the ticket goes back to `accepted`
+instead of forward to `fixed`.
+
+**No extra steps.** Otherwise follow the shared policy as written.

package/prompts/default/personas/lane-qa.md

@@ -117,6 +117,13 @@ human review, so "probably fine" is not a pass.
    Missing or stale docs are a reason to bounce the ticket back to the dev
    seat, with a comment naming the page that needs the change. If the
    repository names no such location, skip this check.
+7b. **Check the hand-off for needed-but-unfiled work.** If the dev or design
+   comment names work that is needed in another repository (or that this
+   repository cannot do) and no ticket for it exists in the ticket's
+   `blocked_by`, that is a bounce: say so in your comment and ask for the
+   ticket and the `blocked_by` link. A shipped stand-in whose UI, docs or
+   hints promise behaviour the dependency has not yet delivered is a defect
+   even if every test passes. Bounce it like any other failure (step 8).
 7a. **Ask whether the fix is covered.** A behaviour change with no test that
    would catch its regression is worth naming in your comment; whether it
    is worth bouncing the ticket over is your judgement, and depends on how

package/prompts/dev-qa/personas/common.md

@@ -666,9 +666,42 @@ post. They record who filed the ticket and from where. The block lists a column
 only when this workspace has it, so a column it does not name is not yours to set.
 
 Name the ticket you were working when you noticed it in the new ticket's
-description. Only put it in the new ticket's `blocked by` column if your
-own ticket genuinely cannot proceed without the new one being fixed
-first — merely having noticed it nearby is not a dependency.
+description. Only add the new ticket to **your own ticket's** `blocked_by`
+(the column named `blocked by` in the Environment section) if your own
+ticket genuinely cannot proceed without the new one being fixed first —
+merely having noticed it nearby is not a dependency. The dependency always
+points from the ticket that waits to the ticket it waits on, never the
+other way round.
+
+### Work your ticket needs in another repository
+
+Out-of-scope breakage and **in-scope work that lives somewhere else** are
+different things. If your ticket's acceptance depends on a change in another
+repository (or on a change this repository cannot make), do not ship a
+stand-in for the missing piece and hand the ticket off. A stand-in whose UI,
+docs or hints promise behaviour the dependency has not delivered is a defect
+that QA passes and the release phase ships. Instead:
+
+1. File that work as its own ticket in the owning repository's project (the
+   Environment section names the projects and repos; if the owning repo is
+   not listed there, file it against the project and say which repo in the
+   description), setting `repo_id`, `project_id`, `filed_by_id` and
+   `ship_id` as in the filing block, and naming your ticket in its
+   description.
+2. Add the new ticket's id to **your own ticket's** `blocked_by`.
+3. Post a comment on your ticket naming each dependency and what it must
+   deliver.
+4. Set your ticket back to `accepted`. The poll's sweep parks it at
+   `blocked` and restores it to `accepted` once every blocker resolves.
+   In a `hybrid` project keep `assignee_id` as your own seat (an unassigned
+   hybrid ticket is off limits to every lane); in an `automatic` project
+   clear it as for any other re-queue.
+5. Leave the branch and worktree in place, committed and pushed if they hold
+   work, so the lane that resumes the ticket continues from them.
+
+Hand a ticket off as `fixed` only when the branch works against
+dependencies that are already released. A hand-off comment that says "worth
+separate tickets" for work the ticket needs is a hand-off that is not ready.
 
 ## Step 4 — you never merge, and you never deploy
 

package/prompts/dev-qa/personas/lane-dev.md

@@ -23,4 +23,11 @@ release phase merges and ships it) or hands it back to you as `in_progress`
 with a comment saying what still fails. Take that bounce seriously — it is
 the only reading your work gets before it is deployed.
 
-**No extra steps.** Follow the shared policy as written.
+**Before you hand a ticket to QA, check the hand-off comment.** It must not
+name needed-but-unfiled work: anything the ticket's acceptance depends on in
+another repository is a filed ticket in your ticket's `blocked_by` (see "Work
+your ticket needs in another repository"), not a line saying "worth separate
+tickets". If it would name such work, the ticket goes back to `accepted`
+instead of forward to `fixed`.
+
+**No extra steps.** Otherwise follow the shared policy as written.

package/prompts/dev-qa/personas/lane-qa.md

@@ -104,6 +104,13 @@ human review, so "probably fine" is not a pass.
    Missing or stale docs are a reason to bounce the ticket back to the dev
    seat, with a comment naming the page that needs the change. If the
    repository names no such location, skip this check.
+7b. **Check the hand-off for needed-but-unfiled work.** If the dev or design
+   comment names work that is needed in another repository (or that this
+   repository cannot do) and no ticket for it exists in the ticket's
+   `blocked_by`, that is a bounce: say so in your comment and ask for the
+   ticket and the `blocked_by` link. A shipped stand-in whose UI, docs or
+   hints promise behaviour the dependency has not yet delivered is a defect
+   even if every test passes. Bounce it like any other failure (step 8).
 7a. **Ask whether the fix is covered.** A behaviour change with no test that
    would catch its regression is worth naming in your comment; whether it
    is worth bouncing the ticket over is your judgement, and depends on how