session-orchestrator 3.21.0 → 3.23.0

package/scripts/lib/autopilot/worktree-pipeline.mjs

@@ -36,6 +36,11 @@ import { acquire, release, buildLockOwnerProof } from '../session-lock.mjs';
 import { emitEvent } from '../events.mjs';
 import { main as gcMain } from '../../gc-stale-worktrees.mjs';
 import { SEMANTIC_ID_RE } from '../session-id.mjs';
+import { repoPathHash } from '../session-registry.mjs';
+// Marker location is owned by its READER (session-end Phase 4a) — importing the
+// constant from there keeps writer and reader on one string. The dependency runs
+// heavy→lean (this pipeline → the dependency-free cleanup helper), never back.
+import { PROMOTION_MARKER_RELPATH } from '../session-end/worktree-cleanup.mjs';
 
 // ---------------------------------------------------------------------------
 // Type definitions
@@ -547,6 +552,134 @@ export async function runStoryPipeline(context, opts = {}) {
 /** Valid git branch character set — mirrors isValidBranch from session-id.mjs. */
 const ENTER_WORKTREE_BRANCH_RE = /^[a-zA-Z0-9._/-]+$/;
 
+/**
+ * Raised when the promotion branch `so/<sessionId>` is already checked out by
+ * another worktree. Refusing is the point: adopting a foreign target worktree
+ * would put two sessions on one branch (PSA-002 territory), so the caller gets
+ * the conflicting path by name instead of a silent takeover.
+ */
+export class WorktreePromotionBranchError extends Error {
+  /**
+   * @param {string} message
+   * @param {{branch: string, checkedOutAt: string}} detail
+   */
+  constructor(message, { branch, checkedOutAt } = {}) {
+    super(message);
+    this.name = 'WorktreePromotionBranchError';
+    this.branch = branch;
+    this.checkedOutAt = checkedOutAt;
+  }
+}
+
+/**
+ * Map of branch name → worktree path for every branch currently checked out by
+ * ANY worktree of `repoRoot` (#1067).
+ *
+ * Deliberately NOT `listWorktrees()` from `../worktree/listing.mjs`: that helper
+ * runs `git worktree list --porcelain` in `process.cwd()` (it has no repo
+ * parameter), and `enterWorktree` takes `repoRoot` explicitly precisely to avoid
+ * CWD drift (#219) — so reusing it would query whichever repo the process
+ * happens to sit in. Its `$` seam also has a different shape (`$({cwd})` returns
+ * the tag) than `enterWorktree`'s (`exec` IS the tag), so the two cannot share
+ * one injected executor. Only the `branch` lines are parsed here; `HEAD`,
+ * `detached`, `bare` and `locked` records carry nothing this decision needs.
+ *
+ * @param {Function} exec      zx-like template-tag executor (the DI seam).
+ * @param {string} repoRoot    Absolute path to the source git repository.
+ * @returns {Promise<Map<string, string>>} Branch names (without the
+ *   `refs/heads/` prefix) → the worktree path that has them checked out.
+ *   Empty on git failure — the caller then behaves exactly as it did before this
+ *   check existed, so a broken listing degrades to git's own loud
+ *   `already used by worktree` error rather than to a silent wrong branch.
+ */
+async function listCheckedOutBranches(exec, repoRoot) {
+  let stdout;
+  try {
+    const result = await exec`git -C ${repoRoot} worktree list --porcelain`;
+    stdout = String(result?.stdout ?? '');
+  } catch {
+    return new Map();
+  }
+
+  const branches = new Map();
+  let currentPath = null;
+  for (const rawLine of stdout.split('\n')) {
+    const line = rawLine.trimEnd();
+    const wtMatch = /^worktree (.+)$/.exec(line);
+    if (wtMatch) {
+      currentPath = wtMatch[1];
+      continue;
+    }
+    const branchMatch = /^branch refs\/heads\/(.+)$/.exec(line);
+    if (branchMatch) branches.set(branchMatch[1], currentPath ?? '');
+  }
+  return branches;
+}
+
+/**
+ * Does `<ref>` resolve in `repoRoot`? Wraps `git rev-parse --verify --quiet`.
+ *
+ * @param {Function} exec
+ * @param {string} repoRoot
+ * @param {string} ref
+ * @returns {Promise<boolean>} false on any git failure (the ref is absent, or
+ *   git could not be asked — both lead to the create-new path, whose failure
+ *   mode is git's own loud error rather than a silent wrong checkout).
+ */
+async function refExists(exec, repoRoot, ref) {
+  try {
+    await exec`git -C ${repoRoot} rev-parse --verify --quiet ${ref}`;
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Record, inside the freshly created worktree, that it was auto-promoted —
+ * and from where. Best-effort: a failure to write the marker degrades Phase 4a
+ * detection to the legacy basename key, it never fails the promotion itself.
+ *
+ * No absolute source path is stored: `source_root_hash` is `repoPathHash()`, the
+ * same stable SHA-256 the session registry uses to correlate repos without
+ * exposing the operator's filesystem layout.
+ *
+ * @param {object} params
+ * @param {string} params.wtPath        Freshly created worktree.
+ * @param {string} params.sourceRoot    Resolved source checkout.
+ * @param {string} params.sessionId     Session label the worktree was created for.
+ * @param {string} params.branch        Branch the worktree actually landed on.
+ * @returns {boolean} true when the marker was written.
+ */
+function writePromotionMarker({ wtPath, sourceRoot, sessionId, branch }) {
+  try {
+    const markerPath = path.join(wtPath, PROMOTION_MARKER_RELPATH);
+    fs.mkdirSync(path.dirname(markerPath), { recursive: true });
+    fs.writeFileSync(
+      markerPath,
+      JSON.stringify(
+        {
+          source_root_hash: repoPathHash(sourceRoot),
+          source_root_basename: path.basename(sourceRoot),
+          source_session_id: sessionId,
+          branch,
+          promoted_at: new Date().toISOString(),
+        },
+        null,
+        2,
+      ) + '\n',
+      'utf8',
+    );
+    return true;
+  } catch (err) {
+    console.warn(
+      `enterWorktree: could not write promotion marker in ${wtPath} (${err.message}) — ` +
+        'session-end Phase 4a falls back to basename detection',
+    );
+    return false;
+  }
+}
+
 /**
  * Create a sibling git worktree for Worktree-Auto-Promotion (#574, Epic #568 P3.1).
  *
@@ -573,10 +706,25 @@ const ENTER_WORKTREE_BRANCH_RE = /^[a-zA-Z0-9._/-]+$/;
  * check as `setupWorktree` (CWE-23 / SEC-013 defence-in-depth). Throws
  * `WorktreeBoundaryError` if the computed path escapes `basePath`.
  *
- * Branch handling: if the branch already exists (verified via
- * `git rev-parse --verify <branch>`), use `git worktree add <wtPath> <branch>`
- * (reuse). Otherwise use `git worktree add -b <branch> <wtPath>` (create new).
- * This differs from `setupWorktree`, which always passes `-b`.
+ * Branch handling — three cases, decided in this order (#1067):
+ *  1. `<branch>` is already checked out by ANY worktree of `repoRoot` (the
+ *     normal session-start Phase 0.5 case, where `branch` is the CURRENT HEAD):
+ *     git refuses a second checkout of the same branch
+ *     (`fatal: '<branch>' is already used by worktree at '<repoRoot>'`). Treat
+ *     `<branch>` as a START POINT only and create a fresh promotion branch
+ *     `so/<sessionId>` at it: `git worktree add -b so/<sessionId> <wtPath> <branch>`.
+ *     The source branch and the source worktree are left untouched.
+ *     If `so/<sessionId>` ALREADY exists (a worktree directory was removed but
+ *     its branch survived), it is REUSED — `git worktree add <wtPath>
+ *     so/<sessionId>`, `reusedBranch: true` in the return — because `-b` would
+ *     abort with `fatal: a branch named 'so/<sessionId>' already exists`.
+ *     If it exists AND is checked out by some worktree, this throws
+ *     `WorktreePromotionBranchError` naming that path: adopting a foreign
+ *     target worktree is refused, never silently taken over.
+ *  2. `<branch>` exists but is not checked out (verified via
+ *     `git rev-parse --verify <branch>`): `git worktree add <wtPath> <branch>`.
+ *  3. `<branch>` does not exist: `git worktree add -b <branch> <wtPath>`.
+ * Cases 2/3 differ from `setupWorktree`, which always passes `-b`.
  *
  * @param {object} params
  * @param {string} params.basePath  - Parent directory where the new worktree goes (absolute).
@@ -585,9 +733,22 @@ const ENTER_WORKTREE_BRANCH_RE = /^[a-zA-Z0-9._/-]+$/;
  * @param {string} params.repoRoot  - Path to the source git repository (passed explicitly to avoid CWD drift per #219).
  * @param {object} [opts]
  * @param {Function} [opts.$]       - zx-like template-tag executor (DI seam); falls back to lazy `await import('zx')`.
- * @returns {Promise<{ wtPath: string, reused: boolean }>}
+ * Every freshly created worktree also gets a `.orchestrator/promoted-from.json`
+ * marker (see {@link PROMOTION_MARKER_RELPATH}) so session-end Phase 4a can
+ * still recognise it after the #1069 process boundary hands the worktree to a
+ * session with a different id. Marker writing is best-effort and never fails
+ * the promotion.
+ *
+ * @returns {Promise<{ wtPath: string, reused: boolean, branch?: string, promotedFrom?: string, reusedBranch?: true }>}
+ *   `branch` is the branch the new worktree actually landed on — equal to the
+ *   `branch` param except in case 1 above, where it is `so/<sessionId>` and
+ *   `promotedFrom` carries the requested source branch. `reusedBranch` is
+ *   present (and `true`) only when an existing `so/<sessionId>` was checked out
+ *   rather than created. All three are absent on the `reused: true` path (no
+ *   branch was chosen — the worktree pre-existed).
  * @throws {TypeError} when any required param is missing or fails validation.
  * @throws {WorktreeBoundaryError} when the computed worktree path escapes `basePath`.
+ * @throws {WorktreePromotionBranchError} when `so/<sessionId>` is checked out elsewhere.
  */
 export async function enterWorktree({ basePath, sessionId, branch, repoRoot } = {}, opts = {}) {
   // -------------------------------------------------------------------------
@@ -686,28 +847,91 @@ export async function enterWorktree({ basePath, sessionId, branch, repoRoot } =
   }
 
   // -------------------------------------------------------------------------
-  // Step 5: Detect whether branch already exists, then `git worktree add`.
+  // Step 5: Is `branch` already checked out elsewhere? (#1067)
+  //
+  // Phase 0.5 passes the CURRENT HEAD as `branch`, so in the normal promotion
+  // case it is checked out by `repoRoot` itself and git would refuse a second
+  // checkout. Then `branch` is only a start point and the worktree lands on a
+  // fresh `so/<sessionId>`; the source branch/worktree stay untouched.
   // -------------------------------------------------------------------------
-  let branchExists = false;
-  try {
-    await exec`git -C ${repoRoot} rev-parse --verify ${branch}`;
-    branchExists = true;
-  } catch {
-    // Branch does not exist — fall through to create-new path with `-b`.
+  const checkedOutBranches = await listCheckedOutBranches(exec, repoRoot);
+  const promoted = checkedOutBranches.has(branch);
+  const targetBranch = promoted ? `so/${sessionId}` : branch;
+
+  // -------------------------------------------------------------------------
+  // Step 6: Decide the `git worktree add` argv.
+  //
+  // On the promotion path the target is `so/<sessionId>`, which can be in any
+  // of THREE states — and only the first was handled before:
+  //   (a) absent           → create it at `<branch>`: `add -b so/<id> <wt> <branch>`
+  //   (b) exists, free     → REUSE it: `add <wt> so/<id>`. This is the survivor
+  //       of a worktree whose directory was removed while its branch stayed
+  //       behind (`git worktree remove` does not delete the branch); `-b` would
+  //       abort Phase 0.5 with `fatal: a branch named 'so/<id>' already exists`.
+  //   (c) exists, checked out elsewhere → REFUSE. Adopting a foreign target
+  //       worktree is exactly what Phase 0.5 must not do.
+  // -------------------------------------------------------------------------
+  let reusedBranch = false;
+  if (promoted) {
+    const checkedOutAt = checkedOutBranches.get(targetBranch);
+    if (checkedOutAt !== undefined) {
+      throw new WorktreePromotionBranchError(
+        `enterWorktree: promotion branch '${targetBranch}' is already checked out at '${checkedOutAt}' — refusing to adopt a foreign worktree`,
+        { branch: targetBranch, checkedOutAt },
+      );
+    }
+    reusedBranch = await refExists(exec, repoRoot, `refs/heads/${targetBranch}`);
   }
 
-  if (branchExists) {
+  // A branch that a worktree has checked out exists by construction, so the
+  // source-branch rev-parse probe is skipped on the promotion path.
+  let branchExists = promoted;
+  if (!promoted) {
+    try {
+      await exec`git -C ${repoRoot} rev-parse --verify ${branch}`;
+      branchExists = true;
+    } catch {
+      // Branch does not exist — fall through to create-new path with `-b`.
+    }
+  }
+
+  if (promoted && reusedBranch) {
+    await exec`git -C ${repoRoot} worktree add ${wtPath} ${targetBranch}`;
+  } else if (promoted) {
+    await exec`git -C ${repoRoot} worktree add -b ${targetBranch} ${wtPath} ${branch}`;
+  } else if (branchExists) {
     await exec`git -C ${repoRoot} worktree add ${wtPath} ${branch}`;
   } else {
     await exec`git -C ${repoRoot} worktree add -b ${branch} ${wtPath}`;
   }
 
   // -------------------------------------------------------------------------
-  // Step 6: WARN to stderr (PRD §3 P3 Gherkin row-1 + #574 DoD).
+  // Step 6b: Record the promotion FACT inside the new worktree (#1069 boundary).
+  // Session-end Phase 4a runs in a session whose id is NOT this one, so nothing
+  // in the path or the branch identifies the worktree to it — the marker does.
+  // -------------------------------------------------------------------------
+  writePromotionMarker({
+    wtPath,
+    sourceRoot: resolvedRepoRoot,
+    sessionId,
+    branch: targetBranch,
+  });
+
+  // -------------------------------------------------------------------------
+  // Step 7: WARN to stderr (PRD §3 P3 Gherkin row-1 + #574 DoD).
   // -------------------------------------------------------------------------
   console.warn(
-    `enterWorktree: created sibling worktree at ${wtPath} (branch=${branch}, sessionId=${sessionId})`,
+    promoted
+      ? `enterWorktree: created sibling worktree at ${wtPath} (branch=${targetBranch}, promoted from ${branch}, sessionId=${sessionId})`
+      : `enterWorktree: created sibling worktree at ${wtPath} (branch=${branch}, sessionId=${sessionId})`,
   );
 
-  return { wtPath, reused: false };
+  if (promoted) {
+    const result = { wtPath, reused: false, branch: targetBranch, promotedFrom: branch };
+    // Present only when it happened, so the common shape stays byte-identical
+    // for every existing consumer and strict-equality pin.
+    if (reusedBranch) result.reusedBranch = true;
+    return result;
+  }
+  return { wtPath, reused: false, branch };
 }

package/scripts/lib/build-live-signals.mjs

@@ -10,7 +10,8 @@
  *  - Synchronous file I/O for STATE.md / sessions.jsonl / bootstrap.lock.
  *    The async wrapper exists only because `scanBacklog` is async.
  *  - Logging is NOT this helper's job — silent graceful-null on every error.
- *  - Paths are resolved absolutely from process.cwd() if relative.
+ *  - Relative paths resolve against `opts.repoRoot` (which itself defaults to
+ *    process.cwd()); an explicit ABSOLUTE path always wins over the root.
  */
 
 import { existsSync, readFileSync } from 'node:fs';
@@ -32,9 +33,16 @@ import { scanBacklog, DEFAULT_BACKLOG_LIMIT } from './backlog-scan.mjs';
  * null/[] value to the Signals object.
  *
  * @param {object} [opts]
- * @param {string} [opts.statePath]      — defaults to '.claude/STATE.md'
- * @param {string} [opts.sessionsPath]   — defaults to '.orchestrator/metrics/sessions.jsonl'
- * @param {string} [opts.lockPath]       — defaults to '.orchestrator/bootstrap.lock'
+ * @param {string} [opts.repoRoot]       — absolute project root every relative
+ *   path below resolves against, and the root forwarded to `scanBacklog`.
+ *   Defaults to `process.cwd()`. Without it (#1071) a caller running from a
+ *   worktree or a subdirectory silently read a DIFFERENT repo's STATE.md and
+ *   sessions.jsonl than the one it was reporting on — measured as
+ *   `recentSessions: []` against a checkout holding 245 session records.
+ *   An explicit absolute `statePath`/`sessionsPath`/`lockPath` still wins.
+ * @param {string} [opts.statePath]      — defaults to '<repoRoot>/.claude/STATE.md'
+ * @param {string} [opts.sessionsPath]   — defaults to '<repoRoot>/.orchestrator/metrics/sessions.jsonl'
+ * @param {string} [opts.lockPath]       — defaults to '<repoRoot>/.orchestrator/bootstrap.lock'
  * @param {Array}  [opts.learnings]      — pre-surfaced top-N learnings; defaults to []
  * @param {number} [opts.backlogLimit]   — passed to scanBacklog; defaults to
  *   `DEFAULT_BACKLOG_LIMIT` from backlog-scan.mjs (never a local copy of that
@@ -46,15 +54,24 @@ import { scanBacklog, DEFAULT_BACKLOG_LIMIT } from './backlog-scan.mjs';
  * @returns {Promise<import('./mode-selector.mjs').Signals>}
  */
 export async function buildLiveSignals(opts = {}) {
+  const repoRoot =
+    typeof opts.repoRoot === 'string' && opts.repoRoot.length > 0
+      ? opts.repoRoot
+      : process.cwd();
+  // `resolve(root, p)` returns `p` unchanged when `p` is absolute — explicit
+  // per-file overrides therefore keep precedence over repoRoot.
   const statePath = resolve(
+    repoRoot,
     typeof opts.statePath === 'string' ? opts.statePath : '.claude/STATE.md'
   );
   const sessionsPath = resolve(
+    repoRoot,
     typeof opts.sessionsPath === 'string'
       ? opts.sessionsPath
       : '.orchestrator/metrics/sessions.jsonl'
   );
   const lockPath = resolve(
+    repoRoot,
     typeof opts.lockPath === 'string' ? opts.lockPath : '.orchestrator/bootstrap.lock'
   );
   const learnings = Array.isArray(opts.learnings) ? opts.learnings : [];
@@ -137,7 +154,9 @@ export async function buildLiveSignals(opts = {}) {
   let backlog = null;
 
   try {
-    backlog = await _scan({ limit: backlogLimit });
+    // `repoRoot` is forwarded so VCS detection and the `-R` host-pinning spec
+    // inside scanBacklog answer about the SAME repo the signals describe.
+    backlog = await _scan({ limit: backlogLimit, repoRoot });
   } catch {
     // Branch 6: scanBacklog threw — backlog stays null
   }