@tablation/crew 0.15.0 → 0.16.0

package/dist/cli.js

@@ -5657,6 +5657,128 @@ function spawnAgent(plan, emit) {
   });
 }
 
+// src/handoff-guard.ts
+var HANDOFF_BOUNCED_MARKER = "<!-- crew:handoff-bounced -->";
+var pushedEventBody = (sha, remote, branch) => `pushed ${sha} to ${remote}/${branch}`;
+function remoteTip(dir, remote, branch) {
+  const out = gitOk(dir, ["ls-remote", "--heads", remote, `refs/heads/${branch}`]);
+  if (out === null) return null;
+  return out.split("\n").find((l) => l.endsWith(`	refs/heads/${branch}`))?.split("	")[0] ?? "";
+}
+function inspectHandoff(dir, cfg, ticket, role) {
+  const remote = cfg.branch.remote;
+  if (!remoteConfigured(dir, remote)) return { kind: "unverified", why: `no remote \`${remote}\` configured` };
+  const branch = existingBranchForTicket(dir, cfg, ticket, role);
+  if (!branch) {
+    return {
+      kind: "bounce",
+      branch: null,
+      remote,
+      local: null,
+      origin: null,
+      reason: `no branch for this ticket exists in this checkout, so there is nothing on \`${remote}\` to hand to QA`
+    };
+  }
+  const wt = worktrees(dir).find((w) => w.branch === branch);
+  const local = wt ? headSha(wt.path) : gitOk(dir, ["rev-parse", `refs/heads/${branch}`]);
+  const origin = remoteTip(dir, remote, branch);
+  if (origin === null) return { kind: "unverified", why: `could not reach \`${remote}\` to check \`${branch}\`` };
+  if (!origin) {
+    return {
+      kind: "bounce",
+      branch,
+      remote,
+      local,
+      origin: null,
+      reason: `\`${branch}\` does not exist on \`${remote}\` \u2014 it was never pushed (or the push failed)`
+    };
+  }
+  if (origin !== local) {
+    return {
+      kind: "bounce",
+      branch,
+      remote,
+      local,
+      origin,
+      reason: `\`${remote}/${branch}\` is at \`${origin}\`, not at this worktree's HEAD \u2014 the latest commits were not pushed, or the remote moved`
+    };
+  }
+  return { kind: "pushed", branch, sha: origin, remote };
+}
+function bounceComment(v, shipName2) {
+  return `${HANDOFF_BOUNCED_MARKER}
+**Hand-off bounced: the branch is not on \`${v.remote}\` at the tip this ticket was built to.**
+
+${shipName2 ? `Ship: ${shipName2}
+` : ""}Local HEAD: ${v.local ? `\`${v.local}\`` : "(no local branch)"}
+\`${v.remote}\`: ${v.origin ? `\`${v.origin}\`` : v.branch ? "(branch missing)" : "(no branch to look for)"}
+
+${v.reason[0].toUpperCase()}${v.reason.slice(1)}. Set back to \`in_progress\`, still held by this ship; push with a plain \`git push --set-upstream ${v.remote} <branch>\` (never \`--force\`) and set \`fixed\` again.`;
+}
+async function enforceHandoff(i) {
+  try {
+    const t = await i.writer.ticket(i.ticketId);
+    if (t.status !== i.contract.statuses.handoff) return { kind: "not-handed-off" };
+    const log = { ticket: t.issue_id, step: "handoff" };
+    const v = inspectHandoff(i.dir, i.cfg, t, i.role);
+    if (v.kind === "unverified") {
+      i.log.warn(`${t.issue_id} is at ${t.status} but the push was not checked: ${v.why}`, log);
+      return { kind: "unverified", why: v.why };
+    }
+    if (v.kind === "pushed") {
+      await i.writer.postEvent(t.id, pushedEventBody(v.sha, v.remote, v.branch), i.seatId);
+      i.log.emit(`${t.issue_id} pushed at ${v.sha.slice(0, 7)} \u2014 handed on to QA`, log);
+      return { kind: "pushed", sha: v.sha };
+    }
+    const heldBy = i.hold ? t[i.hold.column] : void 0;
+    await i.writer.updateTicket(t.id, {
+      status: i.contract.statuses.building,
+      ...t.assignee_id ? {} : { assignee_id: i.seatId },
+      ...i.hold && !heldBy ? { [i.hold.column]: i.hold.shipId } : {}
+    });
+    await i.writer.postEvent(t.id, bounceComment(v, i.shipName), i.seatId).catch(() => {
+      i.log.warn("bounced, but the note failed to post", log);
+    });
+    i.log.warn(`${t.issue_id} bounced back to ${i.contract.statuses.building}: ${v.reason}`, log);
+    return { kind: "bounced" };
+  } catch (e) {
+    i.log.warn(`could not check the hand-off: ${e.message}`, { step: "handoff" });
+    return { kind: "failed", why: e.message };
+  }
+}
+async function guardRunHandoff(route, ship, tracker, role, workingId, log) {
+  if (role !== "dev" && role !== "design" || !workingId) return null;
+  const seatId = route.resolved?.seats[role];
+  if (!seatId) return null;
+  try {
+    const t = await tracker.ticket(workingId);
+    const target = repoTargetFor(route, t.repo_id);
+    if (!target) return null;
+    const o = route.repoOverrides[target.name];
+    const cfg = resolveRepoConfig(loadRepoConfig(target.dir), {
+      hooks: { ...route.hooks, ...o?.hooks },
+      labels: { ...route.labels, ...o?.labels },
+      branch: { ...route.branch, ...o?.branch }
+    }, target.dir);
+    const affinity = await tracker.claimAffinity();
+    return await enforceHandoff({
+      writer: tracker,
+      contract: tracker.contract,
+      ticketId: workingId,
+      role,
+      dir: target.dir,
+      cfg,
+      seatId,
+      shipName: ship.name,
+      hold: affinity ? { column: affinity.column, shipId: affinity.shipId } : void 0,
+      log
+    });
+  } catch (e) {
+    log.warn(`could not check the hand-off: ${e.message}`, { step: "handoff" });
+    return null;
+  }
+}
+
 // src/connect-wizard.ts
 import { delimiter, dirname as dirname6, join as join8 } from "path";
 import { accessSync as accessSync2, constants as constants2, existsSync as existsSync8, mkdirSync as mkdirSync6, writeFileSync as writeFileSync5 } from "fs";
@@ -9499,6 +9621,7 @@ async function runRoleAgent(role, decision, ctx) {
   }
   try {
     await spawnAgent(plan, emit);
+    await guardRunHandoff(route, ship, tracker, role, workingId, emit);
   } finally {
     if (memberId) {
       try {
@@ -10594,6 +10717,7 @@ ${changed2.map((c) => `  - ${c}
         }
         try {
           await spawnAgent(fleetPlan, wemit);
+          await guardRunHandoff(w.route, cfg.ship, fleetTracker, w.role, fleetWorkingId, wemit);
         } finally {
           dropLock();
           if (fleetMemberId) {
@@ -10804,6 +10928,7 @@ ${changed2.map((c) => `  - ${c}
         }
         try {
           await spawnAgent(plan, emit);
+          await guardRunHandoff(route, cfg.ship, tracker2, current, workingId, emit);
         } finally {
           dropLock();
           if (memberId) {

package/package.json

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

@@ -556,6 +556,12 @@ if `report_type` is either of those.
    `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.
+   The runner checks this when your session ends: if the ticket is at `fixed`
+   and `<remote>/<branch>` is missing or not at your worktree's HEAD, it sets
+   the ticket back to `in_progress` (still yours) with an event saying what it
+   found, and QA never sees it. When it matches, the runner records
+   `pushed <sha> to <remote>/<branch>` on the ticket itself; you still state the
+   sha in your last progress comment.
    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

@@ -62,6 +62,13 @@ human review, so "probably fine" is not a pass.
    `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.
+   **Name the sha you test.** Your starting comment states the
+   `<remote>/<branch>` tip you fetched. The runner records the pushed tip as an
+   event comment on the ticket, `pushed <sha> to <remote>/<branch>`; if the tip
+   you fetched differs from the latest such event, say so in that same comment
+   and verify the remote tip anyway — the remote is the only git truth, and the
+   difference is information, not a reason to refuse. If the branch is not on
+   the remote at all, bounce the ticket to `in_progress` with that reason.
 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

@@ -538,6 +538,12 @@ if `report_type` is either of those.
    `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.
+   The runner checks this when your session ends: if the ticket is at `fixed`
+   and `<remote>/<branch>` is missing or not at your worktree's HEAD, it sets
+   the ticket back to `in_progress` (still yours) with an event saying what it
+   found, and QA never sees it. When it matches, the runner records
+   `pushed <sha> to <remote>/<branch>` on the ticket itself; you still state the
+   sha in your last progress comment.
    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/dev-qa/personas/lane-qa.md

@@ -54,6 +54,13 @@ 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?
+   **Name the sha you test.** Your starting comment states the
+   `<remote>/<branch>` tip you fetched. The runner records the pushed tip as an
+   event comment on the ticket, `pushed <sha> to <remote>/<branch>`; if the tip
+   you fetched differs from the latest such event, say so in that same comment
+   and verify the remote tip anyway — the remote is the only git truth, and the
+   difference is information, not a reason to refuse. If the branch is not on
+   the remote at all, bounce the ticket to `in_progress` with that reason.
 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