@tablation/crew 0.10.1 → 0.11.0

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { resolve as resolve4, dirname as dirname9, join as join19, basename as basename7 } from "path";
+import { resolve as resolve4, dirname as dirname10, join as join19, basename as basename7 } from "path";
 import { fileURLToPath } from "url";
 import { hostname as hostname2, homedir as homedir5 } from "os";
 import { spawnSync as spawnSync3 } from "child_process";
@@ -2323,9 +2323,14 @@ function programFromPlist(text) {
   const args = [...block[1].matchAll(/<string>([\s\S]*?)<\/string>/g)].map((m) => xmlUnescape(m[1]));
   return args.find((a) => a.endsWith("/bin/crew")) ?? args[0] ?? null;
 }
-function listLaunchdUnits(dir = launchAgentsDir()) {
-  if (!existsSync5(dir)) return [];
-  return readdirSync(dir).filter((f) => f.startsWith(CREW_LAUNCHD_PREFIX) && f.endsWith(".plist")).sort().map((f) => {
+function loadedCrewLabels() {
+  const list = spawnSync("launchctl", ["list"], { encoding: "utf8" });
+  if (list.status !== 0) return [];
+  return [...parseLaunchctlList(list.stdout ?? "").keys()].filter((l) => l.startsWith(CREW_LAUNCHD_PREFIX));
+}
+function listLaunchdUnits(dir = launchAgentsDir(), loaded = []) {
+  const files = existsSync5(dir) ? readdirSync(dir) : [];
+  const units = files.filter((f) => f.startsWith(CREW_LAUNCHD_PREFIX) && f.endsWith(".plist")).sort().map((f) => {
     const plistPath = join5(dir, f);
     let program = null;
     try {
@@ -2339,10 +2344,16 @@ function listLaunchdUnits(dir = launchAgentsDir()) {
       programExists: program !== null && existsSync5(program)
     };
   });
+  const seen = new Set(units.map((u) => u.label));
+  for (const label of [...loaded].sort()) {
+    if (!label.startsWith(CREW_LAUNCHD_PREFIX) || seen.has(label)) continue;
+    units.push({ label, plistPath: join5(dir, `${label}.plist`), program: null, programExists: false, orphan: true });
+  }
+  return units;
 }
-function foreignLaunchdUnits(crewHome, dir) {
+function foreignLaunchdUnits(crewHome, dir, loaded) {
   const own = new Set(["run", "release", "passengers"].map((job) => labelFor(crewHome, job)));
-  return listLaunchdUnits(dir).filter((u) => !own.has(u.label));
+  return listLaunchdUnits(dir, loaded).filter((u) => !own.has(u.label));
 }
 function removeLaunchdUnit(unit, dryRun, log) {
   if (dryRun) {
@@ -2354,9 +2365,9 @@ function removeLaunchdUnit(unit, dryRun, log) {
   if (existsSync5(unit.plistPath)) unlinkSync(unit.plistPath);
   log.emit(`removed ${unit.label} (${unit.plistPath})`);
 }
-function clearForeignLaunchdUnits(crewHome, replace, dryRun, log, dir) {
-  const foreign = foreignLaunchdUnits(crewHome, dir);
-  const blocking = foreign.filter((u) => u.program === null || u.programExists);
+function clearForeignLaunchdUnits(crewHome, replace, dryRun, log, dir, loaded) {
+  const foreign = foreignLaunchdUnits(crewHome, dir, loaded);
+  const blocking = foreign.filter((u) => !u.orphan && (u.program === null || u.programExists));
   if (blocking.length > 0 && !replace) {
     log.warn(
       `two crew installs target this machine: ${blocking.map((u) => `${u.label} runs ${u.program ?? "an unreadable ProgramArguments"}`).join("; ")}. Run \`crew uninstall\` from the other one, or pass --replace.`
@@ -2364,14 +2375,14 @@ function clearForeignLaunchdUnits(crewHome, replace, dryRun, log, dir) {
     return false;
   }
   for (const unit of foreign) {
-    const why = unit.program === null ? "replacing a unit with no readable ProgramArguments" : unit.programExists ? "replacing a live other install" : "removing a stale unit whose program is gone";
+    const why = unit.orphan ? "removing a loaded job whose plist is gone" : unit.program === null ? "replacing a unit with no readable ProgramArguments" : unit.programExists ? "replacing a live other install" : "removing a stale unit whose program is gone";
     log.emit(`${why}: ${unit.label}`);
     removeLaunchdUnit(unit, dryRun, log);
   }
   return true;
 }
-function removeAllLaunchdUnits(dryRun, log, dir) {
-  for (const unit of listLaunchdUnits(dir)) removeLaunchdUnit(unit, dryRun, log);
+function removeAllLaunchdUnits(dryRun, log, dir, loaded) {
+  for (const unit of listLaunchdUnits(dir, loaded)) removeLaunchdUnit(unit, dryRun, log);
 }
 function parseLaunchctlList(text) {
   const jobs = /* @__PURE__ */ new Map();
@@ -2383,13 +2394,13 @@ function parseLaunchctlList(text) {
   return jobs;
 }
 function describeForeignLaunchdUnits(crewHome, dir) {
-  const foreign = foreignLaunchdUnits(crewHome, dir);
-  if (foreign.length === 0) return [];
   const list = spawnSync("launchctl", ["list"], { encoding: "utf8" });
   const jobs = parseLaunchctlList(list.status === 0 ? list.stdout ?? "" : "");
+  const foreign = foreignLaunchdUnits(crewHome, dir, jobs.keys());
   return foreign.map((u) => {
     const status2 = jobs.get(u.label);
     const loaded = status2 ? `loaded, last exit ${status2.lastExit}` : "not loaded";
+    if (u.orphan) return `  ${u.label}: ${loaded}; plist gone \u2014 stale: \`crew install\` removes it`;
     const program = u.program ? `${u.program} (${u.programExists ? "present" : "GONE"})` : "no readable ProgramArguments";
     const stale = status2 && !u.programExists ? " \u2014 stale: `crew install` removes it" : "";
     return `  ${u.label}: ${loaded}; runs ${program}${stale}`;
@@ -3980,16 +3991,20 @@ function refreshBaseBranch(cwd, remote, base, dryRun = false) {
   const [behindStr, aheadStr] = counts.split(/\s+/);
   const behind = Number.parseInt(behindStr ?? "0", 10);
   const ahead = Number.parseInt(aheadStr ?? "0", 10);
+  const named = () => {
+    const subjects = (gitOk(cwd, ["log", "--format=%h %s", "-5", `${upstream}..${base}`]) ?? "").split("\n").filter(Boolean);
+    return subjects.length ? `: ${subjects.join("; ")}${ahead > subjects.length ? "; \u2026" : ""}` : "";
+  };
   if (ahead > 0 && behind > 0) {
     return {
       action: "diverged",
       ahead,
       behind,
-      detail: `${base} has diverged from ${upstream} (${ahead} ahead, ${behind} behind)`
+      detail: `${base} has diverged from ${upstream} (${ahead} ahead, ${behind} behind)${named()}`
     };
   }
   if (behind === 0 && ahead > 0) {
-    return { action: "ahead", ahead, detail: `${base} has ${ahead} commit(s) ${upstream} does not` };
+    return { action: "ahead", ahead, detail: `${base} has ${ahead} commit(s) ${upstream} does not${named()}` };
   }
   if (behind === 0) return { action: "level", detail: `${base} is level with ${upstream}` };
   if (dryRun) {
@@ -4004,8 +4019,22 @@ function refreshBaseBranch(cwd, remote, base, dryRun = false) {
     detail: `fast-forwarded ${base} to ${upstream} (${behind} commit(s) from elsewhere)`
   };
 }
-function pushBranch(cwd, remote, branch) {
-  git(cwd, ["push", remote, branch]);
+function recoverStrandedReleaseCheckouts(cwd) {
+  gitOk(cwd, ["worktree", "prune"]);
+  const out = gitOk(cwd, ["worktree", "list", "--porcelain"]) ?? "";
+  let path = "";
+  for (const line of out.split("\n")) {
+    if (line.startsWith("worktree ")) path = line.slice("worktree ".length);
+    else if (line.startsWith("branch refs/heads/crew/release-") && path) {
+      gitOk(cwd, ["worktree", "remove", "--force", path]);
+    }
+  }
+  const stranded = (gitOk(cwd, ["for-each-ref", "--format=%(refname:short)", "refs/heads/crew/release-*"]) ?? "").split("\n").filter(Boolean);
+  for (const b of stranded) gitOk(cwd, ["branch", "-q", "-D", b]);
+  return stranded;
+}
+function pushBranch(cwd, remote, branch, dst = branch) {
+  git(cwd, ["push", remote, `${branch}:${dst}`]);
 }
 function worktrees(cwd) {
   const out = gitOk(cwd, ["worktree", "list", "--porcelain"]) ?? "";
@@ -5442,8 +5471,9 @@ Wrote ${o.configPath}.
 }
 
 // src/release-run.ts
-import { readFileSync as readFileSync7, writeFileSync as writeFileSync6, existsSync as existsSync9 } from "fs";
-import { join as join9 } from "path";
+import { readFileSync as readFileSync7, writeFileSync as writeFileSync6, existsSync as existsSync9, copyFileSync, mkdirSync as mkdirSync7, mkdtempSync, rmSync as rmSync2 } from "fs";
+import { dirname as dirname7, join as join9 } from "path";
+import { tmpdir as tmpdir2 } from "os";
 
 // src/release.ts
 function describeUnplaceable(unplaceable, verifiedStatus) {
@@ -6018,6 +6048,31 @@ async function confirmLastRelease(o, decision) {
   if (!confirmed) o.emit.warn(`${decision.lastTag} is still not confirmed live \u2014 tickets stay verified`);
   return { confirmed, version };
 }
+function openReleaseCheckout(o) {
+  const { remote, base } = o.repo.branch;
+  const branch = `crew/release-${Date.now()}`;
+  const root = mkdtempSync(join9(tmpdir2(), "crew-release-"));
+  const dir = join9(root, "checkout");
+  const close = () => {
+    gitOk(o.cwd, ["worktree", "remove", "--force", dir]);
+    rmSync2(root, { recursive: true, force: true });
+    gitOk(o.cwd, ["worktree", "prune"]);
+    gitOk(o.cwd, ["branch", "-D", branch]);
+  };
+  try {
+    git(o.cwd, ["worktree", "add", "-q", "-b", branch, dir, `${remote}/${base}`]);
+  } catch (e) {
+    close();
+    throw e;
+  }
+  for (const f of o.repo.worktrees.copy) {
+    const src = join9(o.cwd, f);
+    if (!existsSync9(src)) continue;
+    mkdirSync7(dirname7(join9(dir, f)), { recursive: true });
+    copyFileSync(src, join9(dir, f));
+  }
+  return { dir, branch, close };
+}
 async function runRelease(o) {
   const scoped = (msg) => o.scope ? `${o.scope}: ${msg}` : msg;
   const tagPattern = o.repo.release.tagPattern ?? "v*";
@@ -6064,6 +6119,33 @@ async function runRelease(o) {
     const externalClosures = await confirmExternalReleased(o, landed);
     return { merged: [], deployed: false, stopped: "external", decision, externalClosures };
   }
+  const { remote, base } = o.repo.branch;
+  if (o.dryRun || o.mergeOnly || !remoteBranchExists(o.cwd, remote, base)) {
+    return mergeAndRelease(o, decision, fresh);
+  }
+  let checkout;
+  const stranded = recoverStrandedReleaseCheckouts(o.cwd);
+  if (stranded.length > 0) o.emit.warn(scoped(`dropped release checkout(s) stranded by a crash: ${stranded.join(", ")}`));
+  try {
+    checkout = openReleaseCheckout(o);
+  } catch (e) {
+    o.emit.error(scoped(`could not cut a release checkout from ${remote}/${base} \u2014 ${e.message}`));
+    return { merged: [], deployed: false, stopped: "release checkout failed", decision };
+  }
+  try {
+    return await mergeAndRelease({ ...o, cwd: checkout.dir }, decision, fresh, checkout.branch);
+  } finally {
+    checkout.close();
+    const refreshed = refreshBaseBranch(o.cwd, remote, base);
+    if (refreshed.action === "fast-forwarded" && o.repo.hooks.build) {
+      const r = await hook(o, "build");
+      if (r && r.code !== 0) {
+        o.emit.warn(scoped(`rebuilding the primary checkout after the release failed (exit ${r.code}) \u2014 its dist/ is stale until \`${o.repo.hooks.build}\` is run there`));
+      }
+    }
+  }
+}
+async function mergeAndRelease(o, decision, fresh, releaseBranch) {
   o.emit.enter("merge");
   const merged = [];
   const conflicts = [];
@@ -6225,6 +6307,16 @@ async function runRelease(o) {
       }
     }
   }
+  if (releaseBranch && !o.dryRun) {
+    const { remote, base } = o.repo.branch;
+    if (fetchRemote(o.cwd, remote) && remoteBranchExists(o.cwd, remote, base)) {
+      const moved = resolve2(o.cwd, `${remote}/${base}`);
+      if (moved && !isAncestor(o.cwd, moved, "HEAD")) {
+        o.emit.warn(`${remote}/${base} moved during the release \u2014 discarding it; the tickets stay verified and the next cycle retries`);
+        return { merged, conflicts, unbuildable, version, deployed: false, decision, stopped: "base branch moved during release" };
+      }
+    }
+  }
   let deployed = false;
   let integrated = false;
   if (o.repo.release.mode === "integrate") {
@@ -6254,7 +6346,7 @@ async function runRelease(o) {
       o.emit.emit(`would push ${o.repo.branch.base} to ${o.repo.branch.remote}`);
     } else {
       try {
-        pushBranch(o.cwd, o.repo.branch.remote, o.repo.branch.base);
+        pushBranch(o.cwd, o.repo.branch.remote, releaseBranch ?? o.repo.branch.base, o.repo.branch.base);
         o.emit.emit(`pushed ${o.repo.branch.base} to ${o.repo.branch.remote}`);
       } catch (e) {
         o.emit.error(
@@ -8009,7 +8101,7 @@ function applyRemoteBranchCleanup(cwd, remote, branches2, dryRun, log) {
 }
 
 // src/stream-sweep.ts
-import { existsSync as existsSync15, readdirSync as readdirSync3, rmSync as rmSync2, statSync as statSync6 } from "fs";
+import { existsSync as existsSync15, readdirSync as readdirSync3, rmSync as rmSync3, statSync as statSync6 } from "fs";
 import { join as join14 } from "path";
 var DAY_MS = 24 * 60 * 60 * 1e3;
 function planStreamSweep(stateDir, retentionDays, now = Date.now()) {
@@ -8032,7 +8124,7 @@ function applyStreamSweep(paths, dryRun, log) {
       continue;
     }
     try {
-      rmSync2(path, { force: true });
+      rmSync3(path, { force: true });
       removed++;
       log.emit(`removed stream artifact ${path}`, { step: "worktree" });
     } catch (e) {
@@ -8043,14 +8135,14 @@ function applyStreamSweep(paths, dryRun, log) {
 }
 
 // src/cli.ts
-import { readFileSync as readFileSync14, existsSync as existsSync19, mkdirSync as mkdirSync10, writeFileSync as writeFileSync9, unlinkSync as unlinkSync5, copyFileSync, renameSync } from "fs";
+import { readFileSync as readFileSync14, existsSync as existsSync19, mkdirSync as mkdirSync11, writeFileSync as writeFileSync9, unlinkSync as unlinkSync5, copyFileSync as copyFileSync2, 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 existsSync16, mkdirSync as mkdirSync7, readFileSync as readFileSync11, chmodSync } from "fs";
-import { dirname as dirname8, join as join15 } from "path";
+import { existsSync as existsSync16, mkdirSync as mkdirSync8, readFileSync as readFileSync11, chmodSync } from "fs";
+import { dirname as dirname9, join as join15 } from "path";
 var SshKeyError = class extends Error {
 };
 function shipSshKeyPathFor(stateDir) {
@@ -8060,7 +8152,7 @@ function ensureShipSshKeypair(stateDir) {
   const privateKeyPath = shipSshKeyPathFor(stateDir);
   const publicKeyPath = `${privateKeyPath}.pub`;
   if (!existsSync16(privateKeyPath)) {
-    mkdirSync7(dirname8(privateKeyPath), { recursive: true });
+    mkdirSync8(dirname9(privateKeyPath), { recursive: true });
     try {
       execFileSync3("ssh-keygen", [
         "-t",
@@ -8297,7 +8389,7 @@ function syncAllPassengerCheckouts(cfg) {
 
 // src/tunnel.ts
 import { spawn as spawn3 } from "child_process";
-import { existsSync as existsSync17, mkdirSync as mkdirSync8, readFileSync as readFileSync12, writeFileSync as writeFileSync7, unlinkSync as unlinkSync3, readdirSync as readdirSync4 } from "fs";
+import { existsSync as existsSync17, mkdirSync as mkdirSync9, readFileSync as readFileSync12, writeFileSync as writeFileSync7, unlinkSync as unlinkSync3, readdirSync as readdirSync4 } from "fs";
 import { randomInt } from "crypto";
 import { join as join16 } from "path";
 var DEFAULT_SPAWN_OPTIONS = { stdio: "ignore", detached: true };
@@ -8379,7 +8471,7 @@ function readPersistedTunnel(stateDir, workspaceId) {
 }
 function writePersistedTunnel(stateDir, state) {
   const path = tunnelStatePath(stateDir, state.workspaceId);
-  mkdirSync8(join16(stateDir, "passengers"), { recursive: true });
+  mkdirSync9(join16(stateDir, "passengers"), { recursive: true });
   writeFileSync7(path, `${JSON.stringify(state, null, 2)}
 `);
 }
@@ -8599,7 +8691,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 existsSync18, mkdirSync as mkdirSync9, readFileSync as readFileSync13, writeFileSync as writeFileSync8, unlinkSync as unlinkSync4, readdirSync as readdirSync5 } from "fs";
+import { existsSync as existsSync18, mkdirSync as mkdirSync10, readFileSync as readFileSync13, writeFileSync as writeFileSync8, unlinkSync as unlinkSync4, readdirSync as readdirSync5 } from "fs";
 import { join as join17 } from "path";
 
 // src/secret-compare.ts
@@ -8702,7 +8794,7 @@ function readPersistedSyncDaemon(stateDir, workspaceId) {
 }
 function writePersistedSyncDaemon(stateDir, state) {
   const path = syncDaemonStatePath(stateDir, state.workspaceId);
-  mkdirSync9(join17(stateDir, "passengers"), { recursive: true });
+  mkdirSync10(join17(stateDir, "passengers"), { recursive: true });
   writeFileSync8(path, `${JSON.stringify(state, null, 2)}
 `);
 }
@@ -9066,7 +9158,7 @@ async function buildEnvironment(route, ship, ticket) {
 }
 
 // src/cli.ts
-var CREW_HOME = isCompiledBinary(import.meta.url) ? dirname9(process.execPath) : resolve4(dirname9(fileURLToPath(import.meta.url)), "..");
+var CREW_HOME = isCompiledBinary(import.meta.url) ? dirname10(process.execPath) : resolve4(dirname10(fileURLToPath(import.meta.url)), "..");
 var RELEASE_LOCK_TTL_MS = 20 * 60 * 1e3;
 var CYCLE_SECONDS = 120;
 var STALE_CYCLES = 3;
@@ -9516,7 +9608,7 @@ if (command === "passenger-sync-daemon") {
 `),
         warn: (m) => process.stderr.write(`crew install: ${m}
 `)
-      });
+      }, void 0, loadedCrewLabels());
       if (!ok) return false;
     }
     const installPathProblem = cfg.routes.some((r) => r.enabled && r.hostPassengers) ? dockerPathProblem(cfg.ship) : void 0;
@@ -10518,7 +10610,7 @@ ${changed2.map((c) => `  - ${c}
         const raw = existsSync19(resolvedPath) ? JSON.parse(readFileSync14(resolvedPath, "utf8")) : {};
         raw.agentPersonas = personaResult.agentPersonas;
         raw.agentSkills = skillResult.agentSkills;
-        mkdirSync10(dirOf(resolvedPath), { recursive: true });
+        mkdirSync11(dirOf(resolvedPath), { recursive: true });
         writeFileSync9(resolvedPath, `${JSON.stringify(raw, null, 2)}
 `);
       }
@@ -10566,7 +10658,7 @@ ${changed2.map((c) => `  - ${c}
         const resolvedPath = resolvedPathFor(cfg.ship.stateDir, target.route);
         const raw = existsSync19(resolvedPath) ? JSON.parse(readFileSync14(resolvedPath, "utf8")) : {};
         raw.agentSkills = result.agentSkills;
-        mkdirSync10(dirOf(resolvedPath), { recursive: true });
+        mkdirSync11(dirOf(resolvedPath), { recursive: true });
         writeFileSync9(resolvedPath, `${JSON.stringify(raw, null, 2)}
 `);
       }
@@ -10610,7 +10702,7 @@ ${changed2.map((c) => `  - ${c}
       }
       const originOf = (dir) => gitOk(dir, ["remote", "get-url", "origin"]) ?? void 0;
       const text = configText;
-      const base = dirname9(cfg.configFile);
+      const base = dirname10(cfg.configFile);
       try {
         if (sub === "list") {
           const repos = configuredRepos(text, routeName, base);
@@ -10971,8 +11063,8 @@ Signed in as ${result.identity.email} \u2014 minted an API key in workspace "${r
           process.stderr.write(`(dry run) would write resolved ids to ${resolvedPath}
 `);
         } else {
-          mkdirSync10(dirname9(resolvedPath), { recursive: true });
-          if (hadPreviousFile) copyFileSync(resolvedPath, `${resolvedPath}.bak`);
+          mkdirSync11(dirname10(resolvedPath), { recursive: true });
+          if (hadPreviousFile) copyFileSync2(resolvedPath, `${resolvedPath}.bak`);
           const tmpPath = `${resolvedPath}.tmp${process.pid}`;
           writeFileSync9(tmpPath, `${JSON.stringify(resolved, null, 2)}
 `);
@@ -10988,7 +11080,7 @@ Signed in as ${result.identity.email} \u2014 minted an API key in workspace "${r
             process.stderr.write(`(dry run) would write the minted API key to ${apiKeyFile}
 `);
           } else {
-            mkdirSync10(dirname9(apiKeyFile), { recursive: true });
+            mkdirSync11(dirname10(apiKeyFile), { recursive: true });
             writeFileSync9(apiKeyFile, `${apiKeyVar}=${apiKey}
 `, { mode: 384 });
             process.stderr.write(`API key written to ${apiKeyFile}
@@ -11444,7 +11536,7 @@ Signed in as ${result.identity.email} \u2014 minted an API key in workspace "${r
 `),
           warn: (m) => process.stderr.write(`crew uninstall: ${m}
 `)
-        });
+        }, void 0, loadedCrewLabels());
       }
       break;
     }

package/package.json

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

@@ -353,9 +353,12 @@ if `report_type` is either of those.
    reconcile it yourself. Post a comment on the ticket naming the repo and the
    counts `crew sync` printed, leave the ticket as you found it, and end the
    run — the operator reconciles the checkout. Otherwise, from
-   the primary checkout, `git worktree add` a sibling worktree for this
-   ticket, on a new branch cut from the base branch's current HEAD. The
-   digest's `worktree` and `branch` columns give this ticket's own directory
+   the primary checkout, `git worktree add <dir> -b <branch> <remote>/<base>`
+   a sibling worktree for this ticket, on a new branch cut from the base
+   branch's REMOTE-TRACKING ref (`origin/main`, say), never from the primary
+   checkout's own local base — that copy is a cache of the remote, and a
+   local commit on it would be carried into every ticket cut from it
+   (CREW-1383). The digest's `worktree` and `branch` columns give this ticket's own directory
    and branch name — use them verbatim. The Environment section names the
    base branch and describes the general pattern, but its own worked example
    is illustrative only (rendered before any ticket is chosen, so it cannot

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

@@ -334,8 +334,12 @@ if `report_type` is either of those.
    reconcile it yourself. Post a comment on the ticket naming the repo and the
    counts `crew sync` printed, leave the ticket as you found it, and end the
    run — the operator reconciles the checkout. Otherwise, from
-   the primary checkout, `git worktree add` a sibling worktree for this
-   ticket, on a new branch cut from the base branch's current HEAD. The
+   the primary checkout, `git worktree add <dir> -b <branch> <remote>/<base>`
+   a sibling worktree for this ticket, on a new branch cut from the base
+   branch's REMOTE-TRACKING ref (`origin/main`, say), never from the primary
+   checkout's own local base — that copy is a cache of the remote, and a
+   local commit on it would be carried into every ticket cut from it
+   (CREW-1383). The
    digest's `worktree` and `branch` columns give this ticket's own directory
    and branch name — use them verbatim. The Environment section names the
    base branch and describes the general pattern, but its own worked example