session-orchestrator 3.22.0 → 3.24.0

package/scripts/lib/auto-dialectic.mjs

@@ -23,6 +23,7 @@ import { randomUUID } from 'node:crypto';
 import path from 'node:path';
 
 import { filterRealSessions } from './session-schema.mjs';
+import { emitEvent, sessionAttribution } from './events.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -245,6 +246,73 @@ export async function shouldDispatchAutoDialectic({
   };
 }
 
+// ---------------------------------------------------------------------------
+// Decision + mechanical telemetry (#1200 part c)
+// ---------------------------------------------------------------------------
+
+/**
+ * `shouldDispatchAutoDialectic()` plus a MECHANICAL `orchestrator.dialectic.nudge_decided`
+ * record, so the nudge decision is observable without depending on the
+ * session-end skill prose actually reaching the emit step (#1200: 0 records of
+ * this class across 164k fleet events despite the nudge firing every close).
+ *
+ * Contract-preserving wrapper: calls `shouldDispatchAutoDialectic()` unchanged
+ * and returns its decision object verbatim — the emit is a side effect bolted
+ * on, never a change to the decision logic or its return shape.
+ *
+ * Emits on ALL FOUR return paths (kill-switch, no-new-input,
+ * cadence-threshold-met, under-threshold) — best-effort, try/catch-wrapped,
+ * because `emitEvent()` throws `EventValidationError` on a malformed record
+ * and a telemetry failure must never change what the caller decides to do
+ * (same posture as `scripts/lib/reconcile/engine.mjs`'s `emitReconcileCompleted`
+ * wrapper).
+ *
+ * @param {object} args
+ * @param {string} args.repoRoot
+ * @param {number} [args.cadence=DEFAULT_CADENCE] `dialectic.cadence` from config.
+ * @param {object} [args.signals] Pre-computed signals (skips disk reads) — forwarded verbatim.
+ * @param {Function|null} [args.emitFn=emitEvent] DI hook for testing / disabling
+ *   emission; defaults to `emitEvent` from `./events.mjs`. Any error it throws
+ *   is swallowed — it never changes the returned decision.
+ * @param {boolean} [args.record=true] When `false`, no event is emitted at all —
+ *   for read-only PROBE callers (e.g. the session-end Phase 3.6.x tail-skip
+ *   aggregator, `scripts/lib/session-end/phase-skip.mjs`, whose documented
+ *   contract is side-effect-free) where the decision is computed for internal
+ *   branching only and must never itself be recorded as a nudge decision.
+ * @returns {Promise<{trigger:boolean, reason:string, signals:object}>}
+ */
+export async function decideAndRecordAutoDialectic({
+  repoRoot,
+  cadence = DEFAULT_CADENCE,
+  signals,
+  emitFn = emitEvent,
+  record = true,
+} = {}) {
+  const decision = await shouldDispatchAutoDialectic({ repoRoot, cadence, signals });
+
+  if (record && typeof emitFn === 'function') {
+    try {
+      await emitFn(
+        'orchestrator.dialectic.nudge_decided',
+        {
+          ...sessionAttribution(repoRoot),
+          decided: decision.trigger,
+          reason: decision.reason,
+          cadence,
+          sessions_since: decision.signals?.sessionsSinceLast,
+          learnings_since: decision.signals?.learningsSinceLast,
+        },
+        { repoRoot },
+      );
+    } catch {
+      // best-effort — a telemetry failure must never block or change the
+      // decision the caller already has in hand.
+    }
+  }
+
+  return decision;
+}
+
 // ---------------------------------------------------------------------------
 // last-run — atomic write
 // ---------------------------------------------------------------------------

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

@@ -36,6 +36,12 @@ 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';
+import { leaveSourceRoot } from '../session-transition.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 +553,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,23 +707,75 @@ 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).
  * @param {string} params.sessionId - Semantic session-ID matching SEMANTIC_ID_RE.
  * @param {string} params.branch    - Branch name (existing or new) matching ENTER_WORKTREE_BRANCH_RE.
  * @param {string} params.repoRoot  - Path to the source git repository (passed explicitly to avoid CWD drift per #219).
+ * @param {string} [params.rawSessionId] - The RAW (physical) session id that owns
+ *   the SOURCE root's `session.lock` and registry entry. Optional. When it is a
+ *   non-empty string, the source root is LEFT mechanically (#1170): after the
+ *   destination worktree provably exists, `leaveSourceRoot()` runs and its
+ *   result is reported as `left` in the return value. OMITTING it (strictly
+ *   `undefined`) preserves the pre-#1170 behaviour exactly — no teardown, no
+ *   `left` key, no WARN. Passing something UNUSABLE (`null`, `''`, a non-string —
+ *   `readLock({ repoRoot }).session_id` returns `null` on a missing/unreadable
+ *   lock, which is how this happens in practice) is NOT the same case: it WARNs
+ *   and reports `left: { ok: false, reason: 'raw-session-id-unusable' }`, because
+ *   a silent skip there is the phantom-owner state of #1069. NOT the semantic
+ *   `sessionId` above, which is a naming key, never an ownership key.
+ * @param {string} [params.reason='worktree-promotion'] - Departure reason
+ *   recorded verbatim in the `orchestrator.session.root_left` payload. Only used
+ *   when `rawSessionId` is given.
  * @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, left?: { ok: boolean, steps: object, reason?: string } }>}
+ *   `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). `left` is present on BOTH
+ *   success exits — and ONLY — when `rawSessionId` was supplied (including when
+ *   it was supplied unusable, where it reports the refusal).
  * @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 = {}) {
+export async function enterWorktree({
+  basePath,
+  sessionId,
+  branch,
+  repoRoot,
+  rawSessionId,
+  reason = 'worktree-promotion',
+} = {}, opts = {}) {
   // -------------------------------------------------------------------------
   // Step 1: Input validation (TypeError on any malformed param).
   // -------------------------------------------------------------------------
@@ -678,36 +864,150 @@ export async function enterWorktree({ basePath, sessionId, branch, repoRoot } =
     );
   }
 
+  // -------------------------------------------------------------------------
+  // Step 3b: The source-root departure (#1170), as a MECHANICAL step.
+  //
+  // Before #1170 this was skill PROSE at four sites: `enterWorktree()` created
+  // the destination and the coordinator was trusted to call `leaveSourceRoot()`
+  // afterwards. A step that only exists in prose is a step that is sometimes
+  // skipped — and skipping it is exactly the phantom-peer / double-live-lock
+  // state #1069 was filed about.
+  //
+  // Ordering is load-bearing and only runs on a proven-existing destination:
+  // every throw above leaves the source root untouched, because a departure
+  // from a root whose successor does not exist strands the session with no
+  // live root at all. `leaveSourceRoot()` never throws, so a failed teardown
+  // WARNs and is reported in `left` — it never fails the promotion.
+  // -------------------------------------------------------------------------
+  const departSourceRoot = async (result) => {
+    // NOT PASSED and PASSED-BUT-UNUSABLE are different callers with different
+    // bugs, and collapsing them re-opened #1069 silently. `undefined` is the
+    // documented opt-out (the autopilot callers, which own no source session):
+    // byte-identical pre-#1170 behaviour, no `left`, no WARN.
+    if (rawSessionId === undefined) return result;
+    // Anything else falsy or non-string means a caller INTENDED to depart and
+    // handed us something unusable. The documented derivation is
+    // `readLock({ repoRoot }).session_id`, which is `null` whenever the lock is
+    // missing or unreadable — so the realistic failure lands here, and before
+    // this branch it returned early with nothing on stderr: promotion succeeds,
+    // source root never deregistered, phantom owner (#1069).
+    if (typeof rawSessionId !== 'string' || rawSessionId.length === 0) {
+      const shown = rawSessionId === null
+        ? 'null'
+        : typeof rawSessionId === 'string' ? 'empty string' : typeof rawSessionId;
+      console.warn(
+        `enterWorktree: rawSessionId unusable (${shown}) — source root NOT departed; ` +
+          'read it via readLock({ repoRoot }).session_id',
+      );
+      result.left = { ok: false, reason: 'raw-session-id-unusable' };
+      return result;
+    }
+    const left = await leaveSourceRoot({
+      repoRoot,
+      sessionId: rawSessionId,
+      semanticSessionId: sessionId,
+      reason,
+    });
+    if (left.ok !== true) {
+      console.warn(`enterWorktree: leaveSourceRoot: ${left.reason ?? 'unknown'}`);
+    }
+    result.left = left;
+    return result;
+  };
+
   // -------------------------------------------------------------------------
   // Step 4: Idempotency — reuse if worktree already exists with .git.
   // -------------------------------------------------------------------------
   if (fs.existsSync(wtPath) && fs.existsSync(path.join(wtPath, '.git'))) {
-    return { wtPath, reused: true };
+    return await departSourceRoot({ wtPath, reused: true });
   }
 
   // -------------------------------------------------------------------------
-  // 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 await departSourceRoot(result);
+  }
+  return await departSourceRoot({ 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';
@@ -19,6 +20,7 @@ import { parseStateMd, parseRecommendations } from './state-md.mjs';
 import { normalizeSession, tailRealSessions } from './session-schema.mjs';
 import { parseBootstrapLock } from './bootstrap-lock-freshness.mjs';
 import { scanBacklog, DEFAULT_BACKLOG_LIMIT } from './backlog-scan.mjs';
+import { readCanonicalSessions } from './sessions-canonical.mjs';
 
 // ---------------------------------------------------------------------------
 // Public API
@@ -32,9 +34,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 +55,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 : [];
@@ -96,29 +114,31 @@ export async function buildLiveSignals(opts = {}) {
   let recentSessions = [];
 
   try {
-    if (existsSync(sessionsPath)) {
-      const raw = readFileSync(sessionsPath, 'utf8');
-      const lines = raw
-        .split('\n')
-        .map((l) => l.trim())
-        .filter((l) => l.length > 0);
-      // #834: parse ALL lines (not just the naive last-N) before windowing —
-      // `status: 'abandoned'` phantom stubs must be filtered out BEFORE the
-      // tail is taken, or sessionTailN silently means "last N LINES" instead
-      // of "last N REAL sessions". tailRealSessions() does the filter + tail.
-      const parsed = [];
-      for (const line of lines) {
-        try {
-          const obj = JSON.parse(line);
-          parsed.push(normalizeSession(obj));
-        } catch {
-          // Branch 4: skip malformed lines silently
-        }
-      }
-      recentSessions = tailRealSessions(parsed, sessionTailN);
-    }
+    // #1186: readCanonicalSessions applies the #1167 newest-wins-per-`session_id`
+    // / attestable-`supersedes` collapse BEFORE the tail is taken. The raw read
+    // this replaced parsed every line unconditionally (malformed lines skipped
+    // on JSON.parse failure only), so a duplicated `session_id` — a
+    // crash-recovery re-append, or the #1068 abandoned-stub/supersede pair —
+    // counted as TWO entries toward `sessionTailN`, silently narrowing the
+    // REAL window by however many duplicates sat in the file's tail.
+    //
+    // Behavioural change: a well-formed record with NO `session_id` (never
+    // legitimate per REQUIRED_FIELDS, but possible on a hand-edited or
+    // pre-schema legacy line) is now DROPPED rather than counted — it cannot
+    // be deduplicated by identity, so `canonicalizeSessions` excludes it (see
+    // sessions-canonical.mjs's own contract). Missing-file / unreadable-file
+    // handling (ENOENT vs EACCES/EISDIR, #1188) is delegated to the shared
+    // reader; both still degrade to `[]` here, matching Branch 3's contract.
+    const canonical = readCanonicalSessions({ filePath: sessionsPath });
+    const parsed = canonical.map((obj) => normalizeSession(obj));
+    // #834: `status: 'abandoned'` phantom stubs must still be filtered out
+    // BEFORE the tail is taken, or sessionTailN silently means "last N LINES"
+    // instead of "last N REAL sessions". tailRealSessions() does the filter +
+    // tail.
+    recentSessions = tailRealSessions(parsed, sessionTailN);
   } catch {
-    // Branch 3: file unreadable — recentSessions stays []
+    // Branch 3: file unreadable — recentSessions stays [] (readCanonicalSessions
+    // itself never throws, but the graceful-null contract is kept as a backstop).
   }
 
   // --- Branch 5: bootstrap.lock ---
@@ -137,7 +157,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
   }