@tablation/crew 0.1.7 → 0.3.0

package/README.md

@@ -211,7 +211,7 @@ crew pause|resume [route] [R]  pause everything, or one role
 crew log [route]               tail the log
 crew inbox [--member NAME]    your tickets across every workspace
 crew connect WS[/PROJECT]     resolve a workspace/project's ids into the state tree
-crew repos add ROUTE PATH     attach a local checkout to a route in crew.yaml, creating its Repos row if missing (--dry-run previews)
+crew repos add [ROUTE] [NAME] [PATH]  attach a local checkout to a route in crew.yaml, creating its Repos row if missing (--dry-run previews)
 crew repos list ROUTE         the checkouts a route has, and the tracker Repos row each matches
 crew install                  write and load this platform's scheduler unit
 crew uninstall                unload and remove it

package/dist/cli.js

@@ -2746,7 +2746,7 @@ function qaDigest(i) {
     "## 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. **MISSING** means the branch is gone and there is\nnothing 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**`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),
     "\n### Awaiting verification, in pick order\n",
@@ -2813,6 +2813,13 @@ function branches(cwd, pattern) {
   return out ? out.split("\n").filter(Boolean) : [];
 }
 function branchForIssue(cwd, issueKey, templates = { name: "issue-{number}" }, render2 = (t) => t.replace(/\{number\}/g, issueKey.replace(/^\D+/, ""))) {
+  for (const c of branchCandidates(issueKey, templates, render2)) {
+    const found = branches(cwd, c);
+    if (found.length) return found[0];
+  }
+  return null;
+}
+function branchCandidates(issueKey, templates, render2) {
   const num = issueKey.replace(/^\D+/, "");
   const unpadded = String(Number.parseInt(num, 10));
   const candidates = [];
@@ -2827,12 +2834,31 @@ function branchForIssue(cwd, issueKey, templates = { name: "issue-{number}" }, r
   }
   candidates.push(`issue-${num}`);
   if (num !== unpadded) candidates.push(`issue-${unpadded}`);
-  for (const c of [...new Set(candidates)]) {
-    const found = branches(cwd, c);
-    if (found.length) return found[0];
+  return [...new Set(candidates)];
+}
+function remoteBranchForIssue(cwd, remote, issueKey, templates = { name: "issue-{number}" }, render2 = (t) => t.replace(/\{number\}/g, issueKey.replace(/^\D+/, ""))) {
+  const prefix = `refs/remotes/${remote}/`;
+  for (const c of branchCandidates(issueKey, templates, render2)) {
+    const out = gitOk(cwd, ["for-each-ref", "--format=%(refname)", `${prefix}${c}`]);
+    const hit = out?.split("\n").filter((r) => r.startsWith(prefix) && r !== `${prefix}HEAD`)[0];
+    if (hit) return hit.slice(prefix.length);
   }
   return null;
 }
+function materializeRemoteBranch(cwd, remote, branch) {
+  if (!remoteBranchExists(cwd, remote, branch)) {
+    return gitOk(cwd, ["rev-parse", "-q", "--verify", `refs/heads/${branch}`]) !== null;
+  }
+  if (gitOk(cwd, ["rev-parse", "-q", "--verify", `refs/heads/${branch}`]) === null) {
+    return gitOk(cwd, ["branch", "--track", branch, `${remote}/${branch}`]) !== null;
+  }
+  gitOk(cwd, ["fetch", "--quiet", remote, `${branch}:${branch}`]);
+  return true;
+}
+function deleteRemoteBranch(cwd, remote, branch) {
+  if (!remoteBranchExists(cwd, remote, branch)) return true;
+  return gitOk(cwd, ["push", remote, "--delete", branch]) !== null;
+}
 function worktreeForNumber(cwd, num) {
   const re = new RegExp(`(?:^|-)${num}$`);
   return worktrees(cwd).find((w) => re.test(basename3(w.path))) ?? null;
@@ -3138,11 +3164,32 @@ function worktreeForTicket(dir, cfg, t, role) {
   const number = t.issue_id.replace(/^\D+/, "");
   return effectiveWorktreeDirName(cfg, dir, branchName, number);
 }
-function existingBranchForTicket(dir, cfg, t, role) {
+function branchTemplates(cfg, t) {
   const { prefix } = ticketBranchContext(t);
   const name = effectiveBranchTemplate(cfg, prefix);
   const push = cfg.provenance["branch.push"] === "default" ? name : cfg.branch.push;
-  return branchForIssue(dir, t.issue_id, { name, push }, branchRenderer(t, role));
+  return { name, push };
+}
+function existingBranchForTicket(dir, cfg, t, role) {
+  return branchForIssue(dir, t.issue_id, branchTemplates(cfg, t), branchRenderer(t, role));
+}
+function locateBranchForTicket(dir, cfg, t, role, fetchedDirs) {
+  const local = existingBranchForTicket(dir, cfg, t, role);
+  if (local) return { branch: local, where: "local" };
+  const remote = cfg.branch.remote;
+  if (!remoteConfigured(dir, remote)) return null;
+  if (fetchedDirs && !fetchedDirs.has(dir)) {
+    fetchedDirs.add(dir);
+    fetchRemote(dir, remote);
+  }
+  const found = remoteBranchForIssue(dir, remote, t.issue_id, branchTemplates(cfg, t), branchRenderer(t, role));
+  return found ? { branch: found, where: "remote" } : null;
+}
+function materializeBranchForTicket(dir, cfg, t, role) {
+  const loc = locateBranchForTicket(dir, cfg, t, role);
+  if (!loc) return null;
+  materializeRemoteBranch(dir, cfg.branch.remote, loc.branch);
+  return loc.branch;
 }
 
 // src/poll.ts
@@ -3312,6 +3359,7 @@ function writeDigest(o, d, role, stateDir) {
       repoCache.set(dir, cfg);
       return cfg;
     };
+    const fetchedDirs = /* @__PURE__ */ new Set();
     const dirFor = (t) => dirForRepo(o.route, t.repo_id);
     const render2 = (t) => branchRenderer(t, role);
     const input = {
@@ -3336,6 +3384,10 @@ function writeDigest(o, d, role, stateDir) {
       existingBranchFor: (t) => {
         const dir = dirFor(t);
         if (!dir) return null;
+        if (role === "qa") {
+          const loc = locateBranchForTicket(dir, repoFor(dir), t, role, fetchedDirs);
+          return loc ? loc.where === "remote" ? `${loc.branch} (on ${repoFor(dir).branch.remote} only)` : loc.branch : null;
+        }
         return existingBranchForTicket(dir, repoFor(dir), t, role);
       },
       tickets: role === "triage" ? d.tickets.filter((t) => t.assignee_id === o.route.resolved?.seats.triage) : sliceFor(d.tickets, role),
@@ -3510,9 +3562,17 @@ async function applyConflictBounce(writer, b, contract, memberId, log, dryRun) {
 
 // src/stranded-verified.ts
 var STRANDED_MARKER = "<!-- crew:stranded-verified -->";
+var STRANDED_ESCALATE_AFTER_MS = 30 * 60 * 1e3;
 var priorStrandedFlags = (ticket, comments) => comments.filter((c) => c.ticket_id === ticket.id && (c.body ?? "").includes(STRANDED_MARKER)).length;
 function planStrandedVerified(candidate, base, remote, comments) {
-  return { candidate, base, remote, priorFlags: priorStrandedFlags(candidate.ticket, comments) };
+  const stamps = comments.filter((c) => c.ticket_id === candidate.ticket.id && (c.body ?? "").includes(STRANDED_MARKER)).map((c) => Date.parse(c.created_at)).filter((n) => !Number.isNaN(n));
+  return {
+    candidate,
+    base,
+    remote,
+    priorFlags: priorStrandedFlags(candidate.ticket, comments),
+    lastFlaggedAt: stamps.length ? Math.max(...stamps) : void 0
+  };
 }
 function flagComment(s) {
   const key = s.candidate.ticket.issue_id;
@@ -3528,12 +3588,16 @@ function escalateComment2(s) {
   return `${STRANDED_MARKER}
 **Still nothing to merge \u2014 stopping rather than repeating.**
 
-\`${key}\` was flagged as stranded at \`verified\` on an earlier cycle and still has no branch on this ship and no commit on \`${s.base}\` naming its key (searched \`${s.remote}/${s.base}\`). This needs a person: either the work landed under a commit that doesn't name the key and this ticket can simply close, or the branch is gone and the work needs redoing.
+\`${key}\` was flagged as stranded at \`verified\` on an earlier cycle and still has no branch on this ship or on \`${s.remote}\` and no commit on \`${s.base}\` naming its key (searched \`${s.remote}/${s.base}\`). This needs a person: either the work landed under a commit that doesn't name the key and this ticket can simply close, or the branch is gone and the work needs redoing.
 
 The crew will not close this on its own.`;
 }
-async function applyStrandedVerified(writer, s, contract, operatorId, memberId, log, dryRun) {
+async function applyStrandedVerified(writer, s, contract, operatorId, memberId, log, dryRun, now = Date.now()) {
   const t = { ticket: s.candidate.ticket.issue_id, step: "merge" };
+  if (s.priorFlags > 0 && s.lastFlaggedAt !== void 0 && now - s.lastFlaggedAt < STRANDED_ESCALATE_AFTER_MS) {
+    log.emit("flagged as stranded recently \u2014 not escalating yet", t);
+    return { kind: "waiting" };
+  }
   if (s.priorFlags > 0) {
     if (dryRun) {
       log.emit(`would escalate to ${contract.statuses.needsHuman} \u2014 flagged before`, t);
@@ -5313,7 +5377,7 @@ function refreshBase(o) {
       return { ok: true };
     case "fetch-failed":
       o.emit.warn(`${r.detail} \u2014 releasing from what this ship already has`);
-      return { ok: true };
+      return { ok: true, stale: true };
     case "would-fast-forward":
     case "fast-forwarded":
       o.emit.emit(r.detail);
@@ -5356,7 +5420,10 @@ async function runRelease(o) {
   const decision = decideRelease(o.cwd, o.tickets, o.contract, {
     tagPattern,
     base: o.repo.branch.base,
-    branchFor: (t) => existingBranchForTicket(o.cwd, o.repo, t)
+    // 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)
   });
   if (!fresh.ok) {
     o.emit.error(scoped(`refusing to release \u2014 ${fresh.why}; a person has to reconcile the two`));
@@ -5405,7 +5472,9 @@ async function runRelease(o) {
         );
       } else {
         o.emit.emit("verified but has no branch and nothing on the base names it \u2014 nothing to merge", { ticket: c.ticket.issue_id });
-        unbuildable.push(c);
+        if (fresh.ok && fresh.stale) {
+          o.emit.warn("not flagging as stranded \u2014 the remote could not be fetched, so the branch may exist there", { ticket: c.ticket.issue_id });
+        } else unbuildable.push(c);
       }
       continue;
     }
@@ -7042,6 +7111,27 @@ function matchRepoName(origin, resolved) {
   }
   return void 0;
 }
+function routeNamesOf(text) {
+  const routes = parseDocument(text).get("routes", true);
+  if (!isSeq(routes)) return [];
+  return routes.items.flatMap((i) => isMap(i) && typeof i.get("route") === "string" ? [i.get("route")] : []);
+}
+function parseAddArgs(args, routes, isDir) {
+  const rest = [...args];
+  let route;
+  if (rest.length > 0 && routes.includes(rest[0])) route = rest.shift();
+  else if (rest.length > 0 && /^[^/\s]+\/[^/\s]+$/.test(rest[0]) && !isDir(rest[0])) {
+    throw new ReposError(`no route "${rest[0]}" in the config (have: ${routes.join(", ") || "none"})`);
+  }
+  if (!route) {
+    if (routes.length === 1) route = routes[0];
+    else throw new ReposError(routes.length === 0 ? "the config has no routes \u2014 run `crew connect` first" : `several routes are configured; name one: ${routes.join(", ")}`);
+  }
+  if (rest.length > 2) throw new ReposError("too many arguments: expected [route] [name] [path]");
+  if (rest.length === 2) return { route, name: rest[0], path: rest[1] };
+  if (rest.length === 1) return isDir(rest[0]) ? { route, path: rest[0] } : { route, name: rest[0], path: "." };
+  return { route, path: "." };
+}
 function expandDir(p, base) {
   const home = p === "~" ? homedir3() : p.startsWith("~/") ? `${homedir3()}/${p.slice(2)}` : p;
   return resolve3(base, home);
@@ -7081,7 +7171,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 ?? basename5(target);
+  const name = matched ?? i.name ?? normalizeRemote(i.origin)?.split("/").pop() ?? basename5(target);
   let warning;
   if (!matched) {
     const known = Object.values(i.resolved?.repoNames ?? {});
@@ -7178,6 +7268,7 @@ function schedulerInstalled(plan, exists, crontab) {
 }
 
 // src/worktree-sweep.ts
+import { existsSync as existsSync14 } from "fs";
 import { basename as basename6 } from "path";
 function planWorktreeSweep(target, tickets, contract) {
   const terminal = new Set(contract.statuses.resolved.filter((s) => s !== contract.statuses.verified));
@@ -7197,10 +7288,24 @@ function planWorktreeSweep(target, tickets, contract) {
   }
   return actions;
 }
-async function applyWorktreeSweep(cwd, actions, dryRun, log) {
+async function applyWorktreeSweep(cwd, actions, dryRun, log, remote = "origin") {
   let removed = 0;
   let keptBranches = 0;
   for (const a of actions) {
+    if (!dryRun && existsSync14(a.path)) {
+      let dirty = false;
+      try {
+        dirty = status(a.path).length > 0;
+      } catch {
+      }
+      if (dirty) {
+        log.warn(
+          `not removing worktree ${a.path} for ${a.ticket.issue_id} (${a.ticket.status}): it has uncommitted changes`,
+          { ticket: a.ticket.issue_id, step: "worktree" }
+        );
+        continue;
+      }
+    }
     const n = Number(a.ticket.issue_id.replace(/^\D+/, ""));
     const pids = pidsInWorktree(a.path, n);
     if (pids.length) {
@@ -7220,7 +7325,12 @@ async function applyWorktreeSweep(cwd, actions, dryRun, log) {
       continue;
     }
     gitOk(cwd, ["worktree", "remove", "--force", a.path]);
-    if (!a.keepBranch && a.branch) gitOk(cwd, ["branch", "-D", a.branch]);
+    if (!a.keepBranch && a.branch) {
+      gitOk(cwd, ["branch", "-D", a.branch]);
+      if (remoteConfigured(cwd, remote) && !deleteRemoteBranch(cwd, remote, a.branch)) {
+        log.warn(`could not delete ${remote}/${a.branch} \u2014 leaving it for the next sweep`, { ticket: a.ticket.issue_id, step: "worktree" });
+      }
+    }
     log.emit(
       `removed worktree for ${a.ticket.issue_id} (${a.ticket.status}); ${branchNote}`,
       { ticket: a.ticket.issue_id, step: "worktree" }
@@ -7229,14 +7339,53 @@ async function applyWorktreeSweep(cwd, actions, dryRun, log) {
   }
   return { removed, keptBranches };
 }
+function planRemoteBranchCleanup(cwd, remote, base, tickets, contract) {
+  if (!remoteConfigured(cwd, remote)) return [];
+  const stems = /* @__PURE__ */ new Set();
+  for (const t of tickets) {
+    if (t.status !== contract.statuses.deployed) continue;
+    const num = t.issue_id.replace(/^\D+/, "");
+    const unpadded = String(Number.parseInt(num, 10));
+    const prefixes = ["issue", t.project_issue_prefix?.toLowerCase()].filter((p) => !!p);
+    for (const p of prefixes) {
+      stems.add(`${p}-${num}`);
+      stems.add(`${p}-${unpadded}`);
+    }
+  }
+  if (stems.size === 0) return [];
+  const prefix = `refs/remotes/${remote}/`;
+  const refs = (gitOk(cwd, ["for-each-ref", "--format=%(refname)", prefix]) ?? "").split("\n").filter(Boolean);
+  const out = [];
+  for (const ref of refs) {
+    const name = ref.slice(prefix.length);
+    if (name === "HEAD" || name === base) continue;
+    const m = /^(.+?-\d+)(?:-.*)?$/.exec(name);
+    if (m && stems.has(m[1])) out.push(name);
+  }
+  return out;
+}
+function applyRemoteBranchCleanup(cwd, remote, branches2, dryRun, log) {
+  let deleted = 0;
+  for (const b of branches2) {
+    if (dryRun) {
+      log.emit(`would delete ${remote}/${b} \u2014 its ticket is deployed`, { step: "worktree" });
+      continue;
+    }
+    if (deleteRemoteBranch(cwd, remote, b)) {
+      deleted++;
+      log.emit(`deleted ${remote}/${b} \u2014 its ticket is deployed`, { step: "worktree" });
+    } else log.warn(`could not delete ${remote}/${b} \u2014 leaving it for the next sweep`, { step: "worktree" });
+  }
+  return deleted;
+}
 
 // src/stream-sweep.ts
-import { existsSync as existsSync14, readdirSync as readdirSync2, rmSync as rmSync2, statSync as statSync4 } from "fs";
+import { existsSync as existsSync15, readdirSync as readdirSync2, rmSync as rmSync2, statSync as statSync4 } from "fs";
 import { join as join13 } from "path";
 var DAY_MS = 24 * 60 * 60 * 1e3;
 function planStreamSweep(stateDir, retentionDays, now = Date.now()) {
   const dir = join13(stateDir, "streams");
-  if (!existsSync14(dir)) return [];
+  if (!existsSync15(dir)) return [];
   const cutoff = now - retentionDays * DAY_MS;
   return readdirSync2(dir).map((name) => join13(dir, name)).filter((path) => {
     try {
@@ -7265,13 +7414,13 @@ function applyStreamSweep(paths, dryRun, log) {
 }
 
 // src/cli.ts
-import { readFileSync as readFileSync12, existsSync as existsSync18, mkdirSync as mkdirSync10, writeFileSync as writeFileSync9, unlinkSync as unlinkSync5, copyFileSync, renameSync } from "fs";
+import { readFileSync as readFileSync12, existsSync as existsSync19, mkdirSync as mkdirSync10, writeFileSync as writeFileSync9, unlinkSync as unlinkSync5, copyFileSync, renameSync } from "fs";
 import { createInterface } from "readline/promises";
 import { dirname as dirOf, resolve as resolvePath } from "path";
 
 // src/ssh-keys.ts
 import { execFileSync as execFileSync3 } from "child_process";
-import { existsSync as existsSync15, mkdirSync as mkdirSync7, readFileSync as readFileSync9, chmodSync } from "fs";
+import { existsSync as existsSync16, mkdirSync as mkdirSync7, readFileSync as readFileSync9, chmodSync } from "fs";
 import { dirname as dirname8, join as join14 } from "path";
 var SshKeyError = class extends Error {
 };
@@ -7281,7 +7430,7 @@ function shipSshKeyPathFor(stateDir) {
 function ensureShipSshKeypair(stateDir) {
   const privateKeyPath = shipSshKeyPathFor(stateDir);
   const publicKeyPath = `${privateKeyPath}.pub`;
-  if (!existsSync15(privateKeyPath)) {
+  if (!existsSync16(privateKeyPath)) {
     mkdirSync7(dirname8(privateKeyPath), { recursive: true });
     try {
       execFileSync3("ssh-keygen", [
@@ -7302,7 +7451,7 @@ function ensureShipSshKeypair(stateDir) {
     }
     chmodSync(privateKeyPath, 384);
   }
-  if (!existsSync15(publicKeyPath)) {
+  if (!existsSync16(publicKeyPath)) {
     throw new SshKeyError(`${privateKeyPath} exists but ${publicKeyPath} does not \u2014 regenerate or restore it`);
   }
   const publicKey = readFileSync9(publicKeyPath, "utf8").trim();
@@ -7495,7 +7644,7 @@ function syncAllPassengerCheckouts(cfg) {
 
 // src/tunnel.ts
 import { spawn as spawn3 } from "child_process";
-import { existsSync as existsSync16, mkdirSync as mkdirSync8, readFileSync as readFileSync10, writeFileSync as writeFileSync7, unlinkSync as unlinkSync3, readdirSync as readdirSync3 } from "fs";
+import { existsSync as existsSync17, mkdirSync as mkdirSync8, readFileSync as readFileSync10, writeFileSync as writeFileSync7, unlinkSync as unlinkSync3, readdirSync as readdirSync3 } from "fs";
 import { randomInt } from "crypto";
 import { join as join15 } from "path";
 var DEFAULT_SPAWN_OPTIONS = { stdio: "ignore", detached: true };
@@ -7568,7 +7717,7 @@ function tunnelStatePath(stateDir, workspaceId) {
 }
 function readPersistedTunnel(stateDir, workspaceId) {
   const path = tunnelStatePath(stateDir, workspaceId);
-  if (!existsSync16(path)) return void 0;
+  if (!existsSync17(path)) return void 0;
   try {
     return JSON.parse(readFileSync10(path, "utf8"));
   } catch {
@@ -7676,7 +7825,7 @@ function syncPassengerTunnels(plans, relayHost, relayPort, privateKeyPath, state
 }
 function readAllPersistedWorkspaceIds(stateDir) {
   const dir = join15(stateDir, "passengers");
-  if (!existsSync16(dir)) return [];
+  if (!existsSync17(dir)) return [];
   return readdirSync3(dir).filter((f) => f.endsWith(".json") && !f.endsWith("-sync.json")).map((f) => f.slice(0, -".json".length));
 }
 
@@ -7797,7 +7946,7 @@ async function unregisterEndpoint(workspaceId, info, d) {
 import { createServer as createHttpServer } from "http";
 import { spawn as spawn4 } from "child_process";
 import { randomBytes } from "crypto";
-import { existsSync as existsSync17, mkdirSync as mkdirSync9, readFileSync as readFileSync11, writeFileSync as writeFileSync8, unlinkSync as unlinkSync4, readdirSync as readdirSync4 } from "fs";
+import { existsSync as existsSync18, mkdirSync as mkdirSync9, readFileSync as readFileSync11, writeFileSync as writeFileSync8, unlinkSync as unlinkSync4, readdirSync as readdirSync4 } from "fs";
 import { join as join16 } from "path";
 
 // src/secret-compare.ts
@@ -7891,7 +8040,7 @@ function syncDaemonStatePath(stateDir, workspaceId) {
 }
 function readPersistedSyncDaemon(stateDir, workspaceId) {
   const path = syncDaemonStatePath(stateDir, workspaceId);
-  if (!existsSync17(path)) return void 0;
+  if (!existsSync18(path)) return void 0;
   try {
     return JSON.parse(readFileSync11(path, "utf8"));
   } catch {
@@ -7922,7 +8071,7 @@ function waitForExit(pid, alive, timeoutMs = 5e3) {
 }
 function readAllPersistedSyncWorkspaceIds(stateDir) {
   const dir = join16(stateDir, "passengers");
-  if (!existsSync17(dir)) return [];
+  if (!existsSync18(dir)) return [];
   const suffix = "-sync.json";
   return readdirSync4(dir).filter((f) => f.endsWith(suffix)).map((f) => f.slice(0, -suffix.length));
 }
@@ -8327,7 +8476,7 @@ function usage() {
   crew agents sync [route] [--force]   push crew's personas AND skill files into the workspace Agents/Agent Skills tables (--force overwrites even a diverged persona)
   crew agents prompt R [route] print one persona's current prompt (e.g. R=pair, for a SessionStart hook)
   crew skills sync [route]      push only crew's skill files (e.g. grill-me) into the workspace Agent Skills table
-  crew repos add ROUTE PATH     attach a local checkout to a route in crew.yaml (--dry-run previews)
+  crew repos add [ROUTE] [NAME] [PATH]  attach a local checkout to a route in crew.yaml (--dry-run previews)
   crew repos list ROUTE         the checkouts a route has, with the tracker's Repos row each matches
   crew logbook list [route]     recent Agent Log entries, filterable by --role/--ticket
   crew logbook show [route] ID [--prompt]   one entry; --prompt reconstructs and verifies its prompt
@@ -8634,7 +8783,7 @@ if (command === "passenger-sync-daemon") {
     if (host === "linux" && hasSystemd) {
       const label = labelFor(CREW_HOME, "run");
       const staleTimer = join18(homedir4(), ".config", "systemd", "user", `${label}.timer`);
-      if (existsSync18(staleTimer)) {
+      if (existsSync19(staleTimer)) {
         process.stdout.write(
           `removing stale run timer from before the persistent-service cutover: ${staleTimer}${dryRun ? " (dry run)" : ""}
 `
@@ -8659,7 +8808,7 @@ if (command === "passenger-sync-daemon") {
     const tracker = new Tracker(c, cfg.ship);
     problems.push(...validateContract(tracker.contract).map((p) => `contract: ${p}`));
     for (const r of await resolvedRepos(c)) {
-      if (!existsSync18(r.dir)) problems.push(`repo ${r.name}: ${r.dir} is missing on disk`);
+      if (!existsSync19(r.dir)) problems.push(`repo ${r.name}: ${r.dir} is missing on disk`);
       if (!satisfies(host, r.config.platform)) problems.push(`repo ${r.name}: requires ${r.config.platform}, this host is ${host}`);
       problems.push(...validateEffective(r.config).map((p) => `repo ${r.name}: ${p}`));
     }
@@ -8677,7 +8826,7 @@ if (command === "passenger-sync-daemon") {
   }
   async function doctorFix(o) {
     const routes = await Promise.all(routesInScope(cfg.routes, named).map((c) => gatherHealth({ route: c.route, enabled: c.enabled, hasRepos: reposOf(c).length > 0 }, () => routeProblems(c))));
-    const unitExists = (p) => existsSync18(p);
+    const unitExists = (p) => existsSync19(p);
     const crontab = o.host === "linux" ? spawnSync2("crontab", ["-l"], { encoding: "utf8" }).stdout ?? "" : "";
     const schedulerAbsent = o.host !== "windows" ? !schedulerInstalled(planInstall(cfg.ship, CREW_HOME, o.host, detectSystemd(), "run"), unitExists, crontab) : true;
     const plan = planFix({ routes, schedulerAbsent, host: o.host });
@@ -8897,9 +9046,11 @@ ${changed2.map((c) => `  - ${c}
         const actions = planWorktreeSweep(target, scoped, tracker.contract);
         if (actions.length) {
           remit.enter("worktree");
-          const r = await applyWorktreeSweep(target.dir, actions, dryRun, remit);
+          const r = await applyWorktreeSweep(target.dir, actions, dryRun, remit, repo.branch.remote);
           remit.emit(`swept ${r.removed} worktree(s), kept ${r.keptBranches} branch(es)`, { step: "worktree" });
         }
+        const stale = planRemoteBranchCleanup(target.dir, repo.branch.remote, repo.branch.base, scoped, tracker.contract);
+        if (stale.length) applyRemoteBranchCleanup(target.dir, repo.branch.remote, stale, dryRun, remit);
       } catch (e) {
         remit.warn(`worktree sweep failed: ${e.message}`, { step: "worktree" });
       }
@@ -9553,7 +9704,7 @@ ${changed2.map((c) => `  - ${c}
 `);
       if (!dryRun) {
         const resolvedPath = resolvedPathFor(cfg.ship.stateDir, target.route);
-        const raw = existsSync18(resolvedPath) ? JSON.parse(readFileSync12(resolvedPath, "utf8")) : {};
+        const raw = existsSync19(resolvedPath) ? JSON.parse(readFileSync12(resolvedPath, "utf8")) : {};
         raw.agentPersonas = personaResult.agentPersonas;
         raw.agentSkills = skillResult.agentSkills;
         mkdirSync10(dirOf(resolvedPath), { recursive: true });
@@ -9602,7 +9753,7 @@ ${changed2.map((c) => `  - ${c}
 `);
       if (!dryRun) {
         const resolvedPath = resolvedPathFor(cfg.ship.stateDir, target.route);
-        const raw = existsSync18(resolvedPath) ? JSON.parse(readFileSync12(resolvedPath, "utf8")) : {};
+        const raw = existsSync19(resolvedPath) ? JSON.parse(readFileSync12(resolvedPath, "utf8")) : {};
         raw.agentSkills = result.agentSkills;
         mkdirSync10(dirOf(resolvedPath), { recursive: true });
         writeFileSync9(resolvedPath, `${JSON.stringify(raw, null, 2)}
@@ -9613,22 +9764,41 @@ ${changed2.map((c) => `  - ${c}
     }
     case "repos": {
       const sub = positional[1];
-      const routeName = positional[2];
       const usage2 = () => {
-        process.stderr.write("crew repos add <workspace/project> <path> [--name N] [--project P] [--dry-run] [--no-create]\ncrew repos list <workspace/project>\n");
+        process.stderr.write("crew repos add [workspace/project] [name] [path] [--name N] [--project P] [--dry-run] [--no-create]\ncrew repos list <workspace/project>\n");
         process.exit(2);
       };
-      if (sub !== "add" && sub !== "list" || !routeName || sub === "add" && !positional[3]) usage2();
+      if (sub !== "add" && sub !== "list") usage2();
+      const configText = readFileSync12(cfg.configFile, "utf8");
+      let routeName = positional[2];
+      let addPath = ".";
+      let addName;
+      if (sub === "list" && !routeName) usage2();
+      if (sub === "add") {
+        try {
+          const a = parseAddArgs(positional.slice(2), routeNamesOf(configText), (p) => existsSync19(resolvePath(p.replace(/^~(?=\/|$)/, homedir4()))));
+          routeName = a.route;
+          addPath = a.path;
+          addName = a.name;
+        } catch (e) {
+          if (e instanceof ReposError) {
+            process.stderr.write(`crew repos: ${e.message}
+`);
+            process.exit(2);
+          }
+          throw e;
+        }
+      }
       const resolvedFile = resolvedPathFor(cfg.ship.stateDir, routeName);
       let resolvedRemotes;
-      if (existsSync18(resolvedFile)) {
+      if (existsSync19(resolvedFile)) {
         try {
           resolvedRemotes = JSON.parse(readFileSync12(resolvedFile, "utf8"));
         } catch {
         }
       }
       const originOf = (dir) => gitOk(dir, ["remote", "get-url", "origin"]) ?? void 0;
-      const text = readFileSync12(cfg.configFile, "utf8");
+      const text = configText;
       const base = dirname9(cfg.configFile);
       try {
         if (sub === "list") {
@@ -9638,14 +9808,14 @@ ${changed2.map((c) => `  - ${c}
           for (const r of repos) {
             const origin2 = originOf(r.dir);
             const row = matchRepoName(origin2, resolvedRemotes);
-            const note = !existsSync18(r.dir) ? "missing on disk" : row ? `Repos row: ${row}` : `no Repos row matches ${normalizeRemote(origin2) ?? "this checkout (no origin remote)"}`;
+            const note = !existsSync19(r.dir) ? "missing on disk" : row ? `Repos row: ${row}` : `no Repos row matches ${normalizeRemote(origin2) ?? "this checkout (no origin remote)"}`;
             process.stdout.write(`${r.name}	${r.dir}	${note}
 `);
           }
           break;
         }
-        const target = resolvePath(positional[3].replace(/^~(?=\/|$)/, homedir4()));
-        const top = existsSync18(target) ? gitOk(target, ["rev-parse", "--show-toplevel"]) : null;
+        const target = resolvePath(addPath.replace(/^~(?=\/|$)/, homedir4()));
+        const top = existsSync19(target) ? gitOk(target, ["rev-parse", "--show-toplevel"]) : null;
         if (!top) throw new ReposError(`${target} is not a git checkout`);
         const origin = originOf(top);
         const plan = planRepoAdd({
@@ -9655,7 +9825,7 @@ ${changed2.map((c) => `  - ${c}
           path: top,
           origin,
           resolved: resolvedRemotes,
-          name: value("name"),
+          name: value("name") ?? addName,
           nameForExisting: (d) => matchRepoName(originOf(d), resolvedRemotes)
         });
         let rowTracker;
@@ -9693,7 +9863,7 @@ ${changed2.map((c) => `  - ${c}
           const created = await rowTracker.createRepoRow(rowPayload);
           process.stdout.write(`created Repos row ${String(rowPayload.name)} (${String(rowPayload.remote)}) ${created.id}
 `);
-          if (existsSync18(resolvedFile)) {
+          if (existsSync19(resolvedFile)) {
             const raw = JSON.parse(readFileSync12(resolvedFile, "utf8"));
             raw.repoNames = { ...raw.repoNames, [created.id]: String(rowPayload.name) };
             raw.repoRemotes = { ...raw.repoRemotes, [created.id]: String(rowPayload.remote) };
@@ -9926,7 +10096,7 @@ Signed in as ${result.identity.email} \u2014 minted an API key in workspace "${r
           operator = await pickOperator(found.holds);
         }
         let previous;
-        const hadPreviousFile = existsSync18(resolvedPath);
+        const hadPreviousFile = existsSync19(resolvedPath);
         if (hadPreviousFile) {
           try {
             previous = JSON.parse(readFileSync12(resolvedPath, "utf8"));
@@ -10182,9 +10352,14 @@ Signed in as ${result.identity.email} \u2014 minted an API key in workspace "${r
       const { byRepo } = ticketsByRepo(route, terminal);
       for (const r of await resolvedRepos(route)) {
         const actions = planWorktreeSweep(r, byRepo.get(r.name) ?? [], tracker.contract);
+        const stale = planRemoteBranchCleanup(r.dir, r.config.branch.remote, r.config.branch.base, byRepo.get(r.name) ?? [], tracker.contract);
+        if (stale.length) {
+          anything = true;
+          applyRemoteBranchCleanup(r.dir, r.config.branch.remote, stale, dryRun, emit);
+        }
         if (!actions.length) continue;
         anything = true;
-        const res = await applyWorktreeSweep(r.dir, actions, dryRun, emit);
+        const res = await applyWorktreeSweep(r.dir, actions, dryRun, emit, r.config.branch.remote);
         emit.emit(
           `swept ${res.removed} worktree(s) for ${r.name}, kept ${res.keptBranches} branch(es)`,
           { step: "worktree" }
@@ -10240,8 +10415,17 @@ Signed in as ${result.identity.email} \u2014 minted an API key in workspace "${r
         break;
       }
       gitOk(target.dir, ["worktree", "remove", "--force", wt]);
-      if (branch) gitOk(target.dir, ["branch", "-D", branch]);
-      else emit.warn(`no branch found for ISSUE-${n} in ${target.name} \u2014 worktree removed, nothing to delete`);
+      if (branch) {
+        gitOk(target.dir, ["branch", "-D", branch]);
+        const { remote, base } = target.config.branch;
+        if (remoteConfigured(target.dir, remote) && remoteBranchExists(target.dir, remote, branch)) {
+          if (findKeyInRange(target.dir, `ISSUE-${n}`, `${remote}/${base}`)) {
+            emit.emit(deleteRemoteBranch(target.dir, remote, branch) ? `deleted ${remote}/${branch}` : `could not delete ${remote}/${branch}`);
+          } else {
+            emit.warn(`${remote}/${branch} kept \u2014 nothing on ${remote}/${base} names ISSUE-${n} yet, so it may be the only copy`);
+          }
+        }
+      } else emit.warn(`no branch found for ISSUE-${n} in ${target.name} \u2014 worktree removed, nothing to delete`);
       emit.emit(`dropped ISSUE-${n} from ${target.name}`);
       break;
     }

package/package.json

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

@@ -191,6 +191,12 @@ since your last comment: an answer to a question, new direction, or a
   comment is what clears you to act again, not the flag itself. Clearing
   `needs_planning`/`needs_review` is always the operator's move, never
   yours, whatever you find when you resume.
+- **Before resuming in an existing worktree, run `crew sync`** (it fetches and
+  fast-forwards every worktree branch that tracks a remote, never merging or
+  rebasing) — another ship may have pushed to the branch since you left it.
+  If it reports your branch as diverged (local commits not on the remote AND
+  the remote has moved), stop: comment on the ticket with what it printed and
+  set `needs_info`; do not merge or rebase it yourself.
 - A ticket QA has bounced back to you comes in as `in_progress`,
   reassigned to your row, with a comment saying what still fails. Treat
   that exactly like new direction from a hold: read the comment, fix what
@@ -520,6 +526,15 @@ if `report_type` is either of those.
    part).
 9. Set the ticket's `status` to `fixed` once you have verified it yourself,
    and **clear `assignee_id`** — that pair is the hand-off to the QA lane.
+   **Push the branch first, in the same step:**
+   `git push --set-upstream <remote> <branch>` from the worktree (the remote is
+   `origin` unless the repo's `.crew.yaml` says otherwise; a repo with no remote
+   configured has nothing to push to, so say so in your comment and skip it).
+   Another ship may be the one that verifies and releases this ticket, and a
+   branch that never left this machine looks MISSING to it. A bounce back to
+   `in_progress` and the next `fixed` push again — a plain fast-forward, never
+   `--force`; if the push is rejected, someone else moved the branch, so stop
+   and say so on the ticket instead of forcing it.
    Leave the worktree and branch exactly where they are, unmerged: QA boots
    *your worktree* on its derived ports to test the fix, so removing it
    would leave QA nothing to test. Your last progress comment is what QA

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

@@ -50,6 +50,12 @@ human review, so "probably fine" is not a pass.
    Does the change actually do what the comment claims? Does it handle the
    empty/error/permission path, or only the happy one? Does it touch
    anything the ticket never mentioned?
+   **A branch on the remote is testable.** The builder may be on another ship:
+   the digest's `branch` column then reads `<name> (on origin only)` and no
+   worktree exists here yet. Cut one from the remote branch —
+   `git worktree add <the digest's worktree> <name>` from the ticket's repo
+   checkout (git creates the local tracking branch) — and carry on. Only
+   **MISSING** (gone locally and on the remote) means there is nothing to test.
 5. **Run it.** The builder left its worktree in place for you: `cd` into it,
    `nvm use` if the repository pins a version, and `eval` the **`ports`** hook
    for this worktree's own ports (anything already listening on them is a dead

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

@@ -172,6 +172,12 @@ since your last comment: an answer to a question, new direction, or a
   to leave such tickets alone, which — combined with the poll not waking
   for them — left ISSUE-049 parked for hours mid-implementation with no
   question outstanding, restartable only by someone commenting on it.
+- **Before resuming in an existing worktree, run `crew sync`** (it fetches and
+  fast-forwards every worktree branch that tracks a remote, never merging or
+  rebasing) — another ship may have pushed to the branch since you left it.
+  If it reports your branch as diverged (local commits not on the remote AND
+  the remote has moved), stop: comment on the ticket with what it printed and
+  set `needs_info`; do not merge or rebase it yourself.
 - A ticket QA has bounced back to you comes in as `in_progress`,
   reassigned to your row, with a comment saying what still fails. Treat
   that exactly like new direction from a hold: read the comment, fix what
@@ -501,6 +507,15 @@ if `report_type` is either of those.
    part).
 9. Set the ticket's `status` to `fixed` once you have verified it yourself,
    and **clear `assignee_id`** — that pair is the hand-off to the QA lane.
+   **Push the branch first, in the same step:**
+   `git push --set-upstream <remote> <branch>` from the worktree (the remote is
+   `origin` unless the repo's `.crew.yaml` says otherwise; a repo with no remote
+   configured has nothing to push to, so say so in your comment and skip it).
+   Another ship may be the one that verifies and releases this ticket, and a
+   branch that never left this machine looks MISSING to it. A bounce back to
+   `in_progress` and the next `fixed` push again — a plain fast-forward, never
+   `--force`; if the push is rejected, someone else moved the branch, so stop
+   and say so on the ticket instead of forcing it.
    Leave the worktree and branch exactly where they are, unmerged: QA boots
    *your worktree* on its derived ports to test the fix, so removing it
    would leave QA nothing to test. Your last progress comment is what QA