session-orchestrator 3.23.0 → 3.24.0

package/hooks/subagent-telemetry.mjs

@@ -85,6 +85,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { appendSubagent } from '../scripts/lib/subagents-schema.mjs';
 import { SO_PROJECT_DIR } from '../scripts/lib/platform.mjs';
+import { resolveSubagentSidecar } from './_lib/subagent-paths.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -489,38 +490,22 @@ function extractTranscriptUsage(transcriptPath) {
  * Derive the path of the subagent's OWN transcript from the parent transcript
  * path the harness sends on stdin (#949).
  *
- * The `transcript_path` in a SubagentStop payload is the PARENT session
- * transcript — `<transcriptDir>/<parent_session_id>.jsonl`. Alongside it the
- * harness maintains one file per real Task subagent at
- * `<transcriptDir>/<parent_session_id>/subagents/agent-<agent_id>.jsonl`
- * (plus an `agent-<agent_id>.meta.json` carrying `agentType`). Verified against
- * live transcripts on 2026-07-31.
- *
- * Returns null — never the parent path — when the derivation is not possible.
- * Falling back to `transcript_path` IS the #949 defect: it makes every stop
- * inherit the parent's running token totals, so the caller must record null
- * instead (an honest absence).
- *
- * The agent_id is charset-restricted before it is interpolated into a path.
- * Real ids are hex-ish tokens (e.g. `a60348a01ca982b4c`); anything else is
- * rejected rather than sanitised, so no payload value can traverse out of the
- * `subagents/` directory.
+ * Thin wrapper over the consolidated derivation (#1196) —
+ * `hooks/_lib/subagent-paths.mjs` `resolveSubagentSidecar()` — which now
+ * applies a `{1,64}` bound to `agentId` (STRICTER than this file's prior
+ * unbounded `+` charset check; see that module's header for the full
+ * divergence table). Returns null — never the parent path — when the
+ * derivation is not possible. Falling back to `transcript_path` IS the #949
+ * defect: it makes every stop inherit the parent's running token totals, so
+ * the caller must record null instead (an honest absence).
  *
  * @param {string|undefined|null} parentTranscriptPath — stdin `transcript_path`
  * @param {string} agentId — the stopping agent's id
  * @returns {string|null} absolute candidate path, or null when underivable
  */
 function resolveSubagentTranscriptPath(parentTranscriptPath, agentId) {
-  if (typeof parentTranscriptPath !== 'string' || !parentTranscriptPath.trim()) return null;
-  if (typeof agentId !== 'string' || !/^[A-Za-z0-9_-]+$/.test(agentId)) return null;
-  // 'unknown' is the no-usable-id fallback — it names no file.
-  if (agentId === 'unknown') return null;
-
-  const dir = path.dirname(parentTranscriptPath);
-  const base = path.basename(parentTranscriptPath).replace(/\.jsonl$/i, '');
-  if (!base || base === '.' || base === '..') return null;
-
-  return path.join(dir, base, 'subagents', `agent-${agentId}.jsonl`);
+  const sidecar = resolveSubagentSidecar({ transcriptPath: parentTranscriptPath, agentId });
+  return sidecar === null ? null : sidecar.transcript;
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "session-orchestrator",
-  "version": "3.23.0",
+  "version": "3.24.0",
   "description": "Loop engineering for AI coding agents — turn ad-hoc sessions into a repeatable research → plan → wave-execute → close loop with verification gates. Runs on Claude Code, Codex CLI, Cursor, and Pi.",
   "type": "module",
   "homepage": "https://session-orchestrator.com",

package/scripts/autopilot.mjs

@@ -47,6 +47,7 @@ import { selectMode } from './lib/mode-selector.mjs';
 import { probe, evaluate, DEFAULT_RESOURCE_THRESHOLDS } from './lib/resource-probe.mjs';
 import { detectPeers } from './lib/session-registry.mjs';
 import { normalizeSession } from './lib/session-schema.mjs';
+import { readCanonicalSessions } from './lib/sessions-canonical.mjs';
 
 // ---------------------------------------------------------------------------
 // CLI-level flag extraction
@@ -174,17 +175,29 @@ const branch = detectBranch();
 const SESSIONS_JSONL_PATH = resolve('.orchestrator/metrics/sessions.jsonl');
 
 /**
- * Count the number of non-empty lines in sessions.jsonl. Returns 0 if missing.
- * @returns {number}
+ * Set of the DISTINCT session identities currently recorded in sessions.jsonl.
+ * Empty set when the file is missing or unreadable.
+ *
+ * Identities, not lines (#1167): the ledger is append-only, so one physical
+ * session can occupy two lines (an abandoned stub plus the authoritative
+ * record that supersedes it, or the systemic double-stub pair). The
+ * pre/post comparison below asks "did the session I just spawned record
+ * itself?", and a raw line count answers that question wrong in BOTH
+ * directions — a duplicate pair looks like two sessions, while a supersede
+ * append (+1 line, −1 stub) leaves a canonical COUNT unchanged. Comparing the
+ * id SETS is immune to both.
+ *
+ * @returns {Set<string>}
  */
-function countSessionLines() {
-  if (!existsSync(SESSIONS_JSONL_PATH)) return 0;
-  try {
-    const raw = readFileSync(SESSIONS_JSONL_PATH, 'utf8');
-    return raw.split('\n').filter((l) => l.trim().length > 0).length;
-  } catch {
-    return 0;
+function readSessionIds() {
+  if (!existsSync(SESSIONS_JSONL_PATH)) return new Set();
+  const ids = new Set();
+  for (const rec of readCanonicalSessions({ filePath: SESSIONS_JSONL_PATH })) {
+    if (typeof rec.session_id === 'string' && rec.session_id.length > 0) {
+      ids.add(rec.session_id);
+    }
   }
+  return ids;
 }
 
 /**
@@ -249,7 +262,7 @@ async function modeSelector() {
  * @returns {Promise<{session_id: string, agent_summary?: object, effectiveness?: object}>}
  */
 async function sessionRunner({ mode, autopilotRunId }) {
-  const preCount = countSessionLines();
+  const preIds = readSessionIds();
 
   await new Promise((res, rej) => {
     const childStdio = hasVerbose
@@ -281,8 +294,9 @@ async function sessionRunner({ mode, autopilotRunId }) {
     });
   });
 
-  const postCount = countSessionLines();
-  if (postCount === preCount) {
+  const postIds = readSessionIds();
+  const appeared = [...postIds].some((id) => !preIds.has(id));
+  if (!appeared) {
     throw new Error('no session record appended');
   }
 

package/scripts/backfill-abandoned-sessions.mjs

@@ -42,10 +42,12 @@ import { parseArgs } from 'node:util';
 import { fileURLToPath } from 'node:url';
 
 import { backfillAbandonedSession, isUuid } from './lib/session-close-backfill.mjs';
+import { emitEvent } from './lib/events.mjs';
 import { SO_PROJECT_DIR } from './lib/platform.mjs';
 
 const LOCK_ACQUIRED = 'orchestrator.session.lock.acquired';
 const SESSION_STARTED = 'orchestrator.session.started';
+const SESSION_ENDED = 'orchestrator.session.ended';
 
 /**
  * Default cap on how many candidates may reach the (expensive) shared core in a
@@ -54,12 +56,31 @@ const SESSION_STARTED = 'orchestrator.session.started';
  */
 export const SESSION_START_LIMIT = 25;
 
-/** Read a JSONL file into parsed objects; missing → []; malformed lines skipped. */
+/**
+ * Read a JSONL file into parsed objects; MISSING (ENOENT) → `[]` silently,
+ * UNREADABLE (EACCES/EISDIR/…) → `[]` with a stderr WARN (#1188); malformed
+ * lines skipped.
+ */
 function readJsonl(filePath) {
   let raw;
   try {
     raw = fs.readFileSync(filePath, 'utf8');
-  } catch {
+  } catch (err) {
+    // #1188 — ENOENT and EACCES/EISDIR are different facts: a missing ledger is
+    // the ordinary fresh-repo case; an UNREADABLE one previously read as "no
+    // records" and made every downstream count silently wrong. Same split as
+    // readLockDetailed (session-lock.mjs § absent vs unreadable).
+    if (!err || err.code !== 'ENOENT') {
+      process.stderr.write(
+        `⚠ backfill-abandoned-sessions: cannot read ${filePath} ` +
+          `(${err?.code ?? '?'}: ${err?.message ?? String(err)}) — ` +
+          'treating as EMPTY, counts below are floors\n',
+      );
+    }
+    // CEILING (BV-004): still [] rather than throw — this runs on the
+    // SessionStart path (SESSION_START_LIMIT), where a permissions fault must
+    // not crash the session start. REVISIT if the warn rate in events.jsonl
+    // shows masked corruption.
     return [];
   }
   const out = [];
@@ -86,16 +107,22 @@ function readJsonl(filePath) {
 export function planSessions({ repoRoot }) {
   const events = readJsonl(path.join(repoRoot, '.orchestrator', 'metrics', 'events.jsonl'));
 
-  const semanticByUuid = new Map();
+  // Two independent UUID -> semantic bridges (#1167). `lock.acquired` is the
+  // original one, but a session that LOST the lock-acquire race never emits it;
+  // its `session.ended` event carries `semantic_session_id` all the same (since
+  // #1068 AC1) and was never read here. Without that second bridge the
+  // candidate resolved semantic=null and the shared core minted a SYNTHETIC id,
+  // writing a duplicate stub beside the record the SessionEnd hook had already
+  // written under the real semantic id (measured 2026-09-02 @ c3ab480: 8 pairs).
+  // lock.acquired keeps precedence — it is the older, mode-carrying attestation.
+  const semanticFromLock = new Map();
+  const semanticFromEnded = new Map();
   for (const ev of events) {
-    if (
-      ev.event === LOCK_ACQUIRED &&
-      typeof ev.session_id === 'string' &&
-      typeof ev.semantic_session_id === 'string'
-    ) {
-      semanticByUuid.set(ev.session_id, ev.semantic_session_id);
-    }
+    if (typeof ev.session_id !== 'string' || typeof ev.semantic_session_id !== 'string') continue;
+    if (ev.event === LOCK_ACQUIRED) semanticFromLock.set(ev.session_id, ev.semantic_session_id);
+    else if (ev.event === SESSION_ENDED) semanticFromEnded.set(ev.session_id, ev.semantic_session_id);
   }
+  const semanticByUuid = new Map([...semanticFromEnded, ...semanticFromLock]);
 
   const seen = new Set();
   const plan = [];
@@ -133,7 +160,14 @@ function readRecordedIds(repoRoot) {
   const records = readJsonl(path.join(repoRoot, '.orchestrator', 'metrics', 'sessions.jsonl'));
   const ids = new Set();
   for (const r of records) {
-    if (r && typeof r.session_id === 'string') ids.add(r.session_id);
+    if (!r) continue;
+    if (typeof r.session_id === 'string') ids.add(r.session_id);
+    // #1167 — a backfilled record now stamps the harness UUID it was
+    // reconstructed from. Indexing it lets a bare-UUID candidate be recognised
+    // as already-recorded even though the record itself is keyed semantically —
+    // the join that was structurally impossible while the field was absent
+    // (0 of 286 records carried it, measured 2026-09-02 @ c3ab480).
+    if (typeof r.raw_session_id === 'string') ids.add(r.raw_session_id);
   }
   return ids;
 }
@@ -238,6 +272,7 @@ export async function runMigration({
       case 'backfilled':
         summary.backfilled += 1;
         if (res.deadByAge) summary.dead_by_age += 1;
+        await emitBackfillCompleted(repoRoot, item, res);
         // Keep the pre-filter snapshot in step with what we just wrote, so a
         // second candidate bridging to the SAME semantic id is skipped cheaply
         // instead of re-entering the core (which would reach the same verdict).
@@ -263,6 +298,40 @@ export async function runMigration({
   return summary;
 }
 
+/**
+ * Emit `orchestrator.session.backfill_completed` for a record THIS path wrote
+ * (#1167). Mirrors the payload of `hooks/on-session-end.mjs::emitBackfillOutcome`
+ * so both writers are queryable with one filter.
+ *
+ * Until now the startup/CLI path wrote records SILENTLY: only the SessionEnd
+ * hook emitted the event, so nothing in the event stream distinguished "the
+ * backfill never ran" from "the backfill ran here". Best-effort by contract —
+ * observability must never fail a migration run.
+ *
+ * @param {string} repoRoot
+ * @param {{sessionId: string, semanticSessionId: string|null}} item
+ * @param {{action: string, sessionId?: string, supersedes?: string, error?: string}} res
+ */
+async function emitBackfillCompleted(repoRoot, item, res) {
+  try {
+    await emitEvent(
+      'orchestrator.session.backfill_completed',
+      {
+        kind: 'abandoned',
+        action: typeof res?.action === 'string' ? res.action : 'unknown',
+        ...(typeof item?.sessionId === 'string' ? { session_id: item.sessionId } : {}),
+        ...(typeof item?.semanticSessionId === 'string'
+          ? { semantic_session_id: item.semanticSessionId }
+          : {}),
+        ...(typeof res?.sessionId === 'string' ? { record_id: res.sessionId } : {}),
+        ...(typeof res?.supersedes === 'string' ? { supersedes: res.supersedes } : {}),
+        ...(typeof res?.error === 'string' ? { reason: res.error } : {}),
+      },
+      { repoRoot },
+    );
+  } catch { /* observability is best-effort */ }
+}
+
 /**
  * SessionStart entry point (#926) — decouple the backfill from the /close path.
  *

package/scripts/emit-event.mjs

@@ -22,7 +22,8 @@
  *
  * Exit codes (per .claude/rules/cli-design.md):
  *   0 — success (event emitted)
- *   1 — user/input error (missing --type, malformed --payload JSON, non-object payload)
+ *   1 — user/input error (missing --type, malformed --payload JSON, non-object
+ *       payload, or a record rejected by validateEventRecord — #1177)
  *   2 — system error (write failure, unexpected internal error)
  *
  * Data → stdout (only with --json). Diagnostics → stderr (always). Related: #611.
@@ -49,7 +50,8 @@ Flags:
 
 Exit codes:
   0 — success
-  1 — user/input error (missing --type, malformed --payload, non-object payload)
+  1 — user/input error (missing --type, malformed --payload, non-object payload,
+      or an event record rejected by the events schema)
   2 — system error (write failure / internal error)
 `;
 
@@ -147,6 +149,12 @@ try {
 try {
   await emitEvent(type, payload, filePath ? { filePath } : {});
 } catch (err) {
+  // A schema-validation rejection is a USER/INPUT error (bad --type or a
+  // payload key colliding with the schema) — exit 1, not 2. Nothing was
+  // written: emitEvent validates before it touches the filesystem (#1177).
+  if (err?.name === 'EventValidationError') {
+    fail(`invalid event: ${err.message}`, 1, jsonMode);
+  }
   // Write/IO failures are system errors (exit 2).
   fail(`failed to emit event: ${err.message}`, 2, jsonMode);
 }

package/scripts/lib/auq/parse.mjs

@@ -82,6 +82,7 @@ import {
   RECOMMENDED_MARKERS,
   isRecommendedOption,
 } from './schema.mjs';
+import { scanFenceBlocks } from '../validate/markdown-fences.mjs';
 
 // ---------------------------------------------------------------------------
 // Korpus-Abgrenzung
@@ -330,42 +331,17 @@ function lineOfOffset(starts, offset) {
 }
 
 /**
- * Zaun-Anker. **Zeilenanfangs-verankert** — ohne den Anker schließt
+ * Zerlegt eine Markdown-Datei in Code-Zaun-Blöcke. **Zeilenanfangs- UND
+ * -ende-verankert** (`{ wholeLine: true }`, gemeinsamer Zaun-Tracker
+ * `../validate/markdown-fences.mjs`, #1181) — ohne den Anker schließt
  * `skills/discovery/SKILL.md:373` seinen eigenen Block mitten im Fragetext
  * (Falle 1).
- */
-export const FENCE_LINE_PATTERN = /^[ \t]*(`{3,}|~{3,})[ \t]*([^\s`~]*)[ \t]*$/u;
-
-/**
- * Zerlegt eine Markdown-Datei in Code-Zaun-Blöcke.
  *
  * @param {string} content
  * @returns {Array<{openLine: number, closeLine: number, lang: string, bodyLines: string[], bodyStartLine: number}>}
  */
 export function fencesOf(content) {
-  const lines = content.split('\n');
-  const fences = [];
-  let open = null;
-  for (let i = 0; i < lines.length; i++) {
-    const m = FENCE_LINE_PATTERN.exec(lines[i]);
-    if (!m) continue;
-    if (open === null) {
-      open = { marker: m[1][0], len: m[1].length, lang: m[2] || '', startIdx: i };
-      continue;
-    }
-    // Ein schließender Zaun muss dasselbe Zeichen und mindestens dieselbe
-    // Länge haben — sonst beendet ein ```js-Zaun einen ````-Block.
-    if (m[1][0] !== open.marker || m[1].length < open.len || m[2]) continue;
-    fences.push({
-      openLine: open.startIdx + 1,
-      closeLine: i + 1,
-      lang: open.lang,
-      bodyLines: lines.slice(open.startIdx + 1, i),
-      bodyStartLine: open.startIdx + 2,
-    });
-    open = null;
-  }
-  return fences;
+  return scanFenceBlocks(content, { wholeLine: true });
 }
 
 // ---------------------------------------------------------------------------

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

@@ -37,6 +37,7 @@ 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.
@@ -731,6 +732,21 @@ function writePromotionMarker({ wtPath, sourceRoot, sessionId, branch }) {
  * @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')`.
  * Every freshly created worktree also gets a `.orchestrator/promoted-from.json`
@@ -739,18 +755,27 @@ function writePromotionMarker({ wtPath, sourceRoot, sessionId, branch }) {
  * 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 }>}
+ * @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).
+ *   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).
   // -------------------------------------------------------------------------
@@ -839,11 +864,62 @@ 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 });
   }
 
   // -------------------------------------------------------------------------
@@ -931,7 +1007,7 @@ export async function enterWorktree({ basePath, sessionId, branch, repoRoot } =
     // 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 await departSourceRoot(result);
   }
-  return { wtPath, reused: false, branch };
+  return await departSourceRoot({ wtPath, reused: false, branch });
 }

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

@@ -20,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
@@ -113,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 ---