session-orchestrator 3.23.0 → 3.24.0

package/scripts/lib/reconcile/engine.mjs

@@ -33,10 +33,16 @@
  * the engine performs is into the reconcile-candidates sidecar (via
  * idempotency.mjs), and even that is skipped under `dryRun`.
  *
- * ── never-throws contract ────────────────────────────────────────────────────
- * `runReconcile` NEVER throws to its caller. A per-learning emit/render failure
- * degrades to a recorded rejection (never a crash); any unexpected top-level
- * error returns a zeroed result with an `error` field.
+ * ── never-throws contract (PIPELINE errors only) ─────────────────────────────
+ * Once the pipeline is running, `runReconcile` NEVER throws to its caller: a
+ * per-learning emit/render failure degrades to a recorded rejection (never a
+ * crash), and any unexpected top-level pipeline error returns a zeroed result
+ * with an `error` field. The ONE exception is a caller-INPUT validation error
+ * at the very top of `runReconcile` — an explicitly-passed `trigger` outside
+ * `KNOWN_TRIGGERS` (issue #1201 Part A) THROWS synchronously before the
+ * pipeline ever starts, the same class of failure as passing a malformed
+ * `params` object to any other function in this codebase; see
+ * `assertKnownTrigger` below.
  *
  * Plain Node ESM, no external deps — Node 20+ stdlib + the four siblings only.
  *
@@ -463,7 +469,7 @@ function defaultReadMaterializedProvenance(repoRoot) {
  * @param {boolean} [opts.dryRun]         - when true, compute proposals but SKIP the merge entirely.
  * @returns {Promise<ReconcileResult>}
  */
-export async function runReconcile(
+async function runReconcileInner(
   {
     repoRoot,
     ruleExpiryDays,
@@ -780,3 +786,228 @@ export async function runReconcile(
     return zeroedResult(msg);
   }
 }
+
+/**
+ * Ledger name of the reconcile run event (issue #1192). Catalogued in
+ * `docs/events-schema.md`; `events-schema.mjs` needs no registration — it
+ * validates the NAME shape only, and this name already satisfies it.
+ */
+export const RECONCILE_EVENT = 'orchestrator.reconcile.completed';
+
+/**
+ * Closed enum of `trigger` values a caller may explicitly pass to
+ * {@link runReconcile} (issue #1201 Part A / Discovery D8). Two of the three
+ * real call sites pinned `trigger` by PROSE inside a `.md` skill file —
+ * `skill` (`skills/reconcile/SKILL.md`) and `session-end`
+ * (`skills/session-end/phase-3-6-tail.md`) — where nothing enforced the
+ * string ever matched this list; only `phase-skip`
+ * (`scripts/lib/session-end/phase-skip.mjs`) pinned it in code. The two `.md`
+ * callers are migrated onto {@link runReconcileFromSkill} /
+ * {@link runReconcileAtSessionEnd} in this same change, so "prose sets the
+ * trigger" stops being possible for them at all.
+ */
+export const KNOWN_TRIGGERS = Object.freeze(['skill', 'session-end', 'phase-skip']);
+
+/**
+ * Reject an explicitly-passed `trigger` that is not in {@link KNOWN_TRIGGERS}
+ * — including the literal `'unknown'`, which is a DEFAULT this module mints
+ * for an ABSENT trigger, never a value a caller should pass on purpose. An
+ * absent trigger (`undefined`) is deliberately let through unchanged: it is
+ * legacy behaviour for a caller that has not yet been migrated onto a pinned
+ * wrapper, and `buildReconcilePayload` already defaults it to `'unknown'` so
+ * the per-trigger denominator in the ledger stays honest about which runs are
+ * unattributed rather than silently breaking them.
+ *
+ * BV-004 revisit trigger: `scripts/lib/session-end/phase-skip.mjs` is the one
+ * remaining caller passing `trigger: 'phase-skip'` as a hand-written literal
+ * rather than through {@link runReconcileFromPhaseSkip} (out of this task's
+ * file scope) — once every caller is migrated onto a pinned wrapper, flip the
+ * absent-trigger default below from "let it run" to a throw, closing the last
+ * legacy path.
+ *
+ * @param {unknown} trigger
+ * @throws {Error} when `trigger` is defined but not in `KNOWN_TRIGGERS`.
+ * @returns {void}
+ */
+export function assertKnownTrigger(trigger) {
+  if (trigger === undefined) return;
+  if (!KNOWN_TRIGGERS.includes(trigger)) {
+    throw new Error(
+      `runReconcile: invalid trigger ${JSON.stringify(trigger)} — must be one of: ` +
+        `${KNOWN_TRIGGERS.join(', ')} (or omitted entirely, for a not-yet-migrated caller).`,
+    );
+  }
+}
+
+/** Clamp for the `reason` string on the abort path — a message can be long. */
+const REASON_MAX_CHARS = 300;
+
+/** The closed target enum `resolveEffectiveTargets` recognises. */
+const KNOWN_TARGETS = ['repo-local', 'baseline'];
+
+/**
+ * Build the `orchestrator.reconcile.completed` payload from a finished run.
+ *
+ * Counter fields are written INCLUDING `0`: each was MEASURED over the whole
+ * run, so a written zero is the payload (same contract as the vault-mirror run
+ * event). The two absence-preserving exceptions are `store_records_dropped`
+ * (absent ⇒ the candidate store was never inspected — dryRun, empty
+ * short-circuit, error path) and `targets` (absent ⇒ the caller asserted no
+ * target list). `aborted`/`reason` appear only when the never-throws guard
+ * fired; their absence means "ran to the end", never "unknown".
+ *
+ * @param {ReconcileResult} result
+ * @param {{ trigger?: string, targets?: string[], dryRun?: boolean, durationMs: number }} ctx
+ * @returns {Record<string, unknown>}
+ */
+function buildReconcilePayload(result, ctx) {
+  const summary = (result && result.summary) || {};
+  /** @type {Record<string, unknown>} */
+  const payload = {
+    trigger: typeof ctx.trigger === 'string' && ctx.trigger.trim() !== '' ? ctx.trigger : 'unknown',
+    dry_run: ctx.dryRun === true,
+    learnings_total: summary.totalLearnings ?? 0,
+    eligible: summary.eligible ?? 0,
+    proposals: summary.proposed ?? 0,
+    rejected: summary.rejected ?? 0,
+    capped: summary.capped ?? 0,
+    already_materialized: summary.alreadyMaterialized ?? 0,
+    written: summary.written === true,
+    duration_ms: ctx.durationMs,
+  };
+  // `targets` originates in operator-authored Session Config (`reconcile.targets`)
+  // and is unbounded there. Allowlisted to the CLOSED enum `resolveEffectiveTargets`
+  // recognises before it enters the ledger and the optional Clank webhook (Q2-F4):
+  // anything else is not a target this engine can act on, so recording it would
+  // be a verbatim echo of untrusted text, never a measurement. Omitted when empty.
+  const targets = Array.isArray(ctx.targets)
+    ? [...new Set(ctx.targets.filter((t) => KNOWN_TARGETS.includes(t)))]
+    : [];
+  if (targets.length > 0) payload.targets = targets;
+  if (typeof summary.skipped === 'number') payload.store_records_dropped = summary.skipped;
+  if (typeof result?.error === 'string' && result.error !== '') {
+    payload.aborted = 'engine-error';
+    payload.reason = result.error.slice(0, REASON_MAX_CHARS);
+  }
+  return payload;
+}
+
+/**
+ * Record one reconcile run in the repo's event ledger — best-effort.
+ *
+ * Refuses the ambient `SO_PROJECT_DIR` destination when no `repoRoot` was
+ * given: most engine tests call `runReconcile` without one, and a fallback
+ * would append synthetic records to the operator's REAL fleet ledger on every
+ * `npm test` (#1119, `scripts/lib/express-path.mjs`). Diagnostics on stderr.
+ *
+ * @param {ReconcileResult} result
+ * @param {{ repoRoot?: string, trigger?: string, targets?: string[], dryRun?: boolean, durationMs: number }} ctx
+ */
+async function emitReconcileCompleted(result, ctx) {
+  const { repoRoot } = ctx;
+  if (typeof repoRoot !== 'string' || repoRoot.trim() === '') {
+    process.stderr.write(
+      `reconcile: skipped ${RECONCILE_EVENT} — no repoRoot given; ` +
+        'refusing the ambient SO_PROJECT_DIR destination (#1119).\n',
+    );
+    return;
+  }
+  const { emitEvent } = await import('../events.mjs');
+  await emitEvent(RECONCILE_EVENT, buildReconcilePayload(result, ctx), { repoRoot });
+}
+
+/**
+ * Public boundary: run the reconciliation pipeline and record the run.
+ *
+ * A thin WRAPPER, deliberately: the pipeline has three return points (empty
+ * short-circuit, normal tail, never-throws catch), and an inline emit would
+ * miss two of them — including the empty corpus and the error path, the two
+ * runs an operator most needs recorded (`.claude/rules/host-resources.md`
+ * § HR-105). Same shape as `runNarrativeMirror` + `mirrorNarrative` in
+ * `scripts/lib/vault-status/narrative-mirror.mjs`.
+ *
+ * The emit is wrapped in try/catch because `emitEvent` THROWS
+ * `EventValidationError` on an invalid record — without the catch, telemetry
+ * would break this function's never-throws contract. The pipeline's result is
+ * returned UNTOUCHED whether or not the ledger accepted the record.
+ *
+ * @param {Object} [params] - see {@link runReconcileInner}, plus:
+ * @param {'skill'|'session-end'|'phase-skip'} [params.trigger] - which caller
+ *        invoked this run; recorded ALWAYS (default `'unknown'` when omitted) so
+ *        the per-trigger denominator is complete. Not read by the pipeline.
+ *        VALIDATED against {@link KNOWN_TRIGGERS} via {@link assertKnownTrigger}
+ *        when explicitly passed — an unknown string, including the literal
+ *        `'unknown'`, THROWS synchronously; an absent trigger is still let
+ *        through unchanged (issue #1201 Part A — see `assertKnownTrigger`'s
+ *        BV-004 revisit-trigger note for why the absent case is not also a
+ *        throw yet). Prefer {@link runReconcileFromSkill},
+ *        {@link runReconcileAtSessionEnd}, or {@link runReconcileFromPhaseSkip}
+ *        over passing `trigger` here directly.
+ * @param {string[]} [params.targets] - the caller's effective target list
+ *        (`resolveEffectiveTargets`); recorded when non-empty, omitted otherwise.
+ *        Not read by the pipeline.
+ * @param {Object} [opts] - see {@link runReconcileInner}.
+ * @returns {Promise<ReconcileResult>}
+ */
+export async function runReconcile(params = {}, opts = {}) {
+  assertKnownTrigger(params.trigger);
+  const t0 = Date.now();
+  const result = await runReconcileInner(params, opts);
+  try {
+    await emitReconcileCompleted(result, {
+      repoRoot: params.repoRoot,
+      trigger: params.trigger,
+      targets: params.targets,
+      dryRun: params.dryRun === true || opts.dryRun === true,
+      durationMs: Date.now() - t0,
+    });
+  } catch {
+    // Best-effort telemetry — never the reason a reconcile run fails.
+  }
+  return result;
+}
+
+/**
+ * Pin `trigger: 'skill'` in code for the `/reconcile` skill (Phase 2.3,
+ * `skills/reconcile/SKILL.md`) — the skill's own `.md` prose no longer sets
+ * the trigger string itself (issue #1201 Part A). Any `trigger` the caller
+ * passes in `params` is OVERWRITTEN; every other field forwards unchanged.
+ *
+ * @param {Object} [params] - see {@link runReconcile} `params`.
+ * @param {Object} [opts] - see {@link runReconcile} `opts` (DI seams).
+ * @returns {Promise<ReconcileResult>}
+ */
+export async function runReconcileFromSkill(params = {}, opts = {}) {
+  return runReconcile({ ...params, trigger: 'skill' }, opts);
+}
+
+/**
+ * Pin `trigger: 'session-end'` in code for session-end Phase 3.6.8
+ * (`skills/session-end/phase-3-6-tail.md`) — see
+ * {@link runReconcileFromSkill} for the rationale and contract.
+ *
+ * @param {Object} [params] - see {@link runReconcile} `params`.
+ * @param {Object} [opts] - see {@link runReconcile} `opts` (DI seams).
+ * @returns {Promise<ReconcileResult>}
+ */
+export async function runReconcileAtSessionEnd(params = {}, opts = {}) {
+  return runReconcile({ ...params, trigger: 'session-end' }, opts);
+}
+
+/**
+ * Pin `trigger: 'phase-skip'` in code for the session-end skip-plan
+ * aggregator (`scripts/lib/session-end/phase-skip.mjs`, the highest-volume
+ * probe-only caller) — see {@link runReconcileFromSkill} for the rationale
+ * and contract. NOT YET wired into `phase-skip.mjs` itself, which is out of
+ * this task's file scope and still passes `trigger: 'phase-skip'` as a
+ * hand-written literal directly to `runReconcile`; exported here so that
+ * migration is a one-line import swap (see `assertKnownTrigger`'s BV-004
+ * revisit-trigger note).
+ *
+ * @param {Object} [params] - see {@link runReconcile} `params`.
+ * @param {Object} [opts] - see {@link runReconcile} `opts` (DI seams).
+ * @returns {Promise<ReconcileResult>}
+ */
+export async function runReconcileFromPhaseSkip(params = {}, opts = {}) {
+  return runReconcile({ ...params, trigger: 'phase-skip' }, opts);
+}

package/scripts/lib/scope-gate.mjs

@@ -918,6 +918,28 @@ export function suggestForScopeViolation(relPath, allowedCsv) {
   );
 }
 
+/**
+ * Prefix that marks an aggregate-sidecar record as a PEER SESSION's declared
+ * scope rather than one of this wave's own agents (#1195).
+ *
+ * SSOT: this constant lives here — in the module both the `--union` helper and
+ * `hooks/post-bash-write-verify.mjs` already import — so the union exclusion
+ * below and the hook's peer-write notice can never disagree about what a peer
+ * record IS.
+ */
+export const PEER_RECORD_PREFIX = 'peer-session-';
+
+/**
+ * Is this record id a PEER SESSION's record (see {@link PEER_RECORD_PREFIX})?
+ * Fail-closed: a non-string id is not a peer record.
+ *
+ * @param {unknown} id
+ * @returns {boolean}
+ */
+export function isPeerRecordId(id) {
+  return typeof id === 'string' && id.startsWith(PEER_RECORD_PREFIX);
+}
+
 /**
  * Merge many agents' declared file scopes into ONE deduplicated, order-stable
  * list — the mechanical form of "allowedPaths is the UNION of all agent file
@@ -943,6 +965,19 @@ export function suggestForScopeViolation(relPath, allowedCsv) {
  * non-array / non-object members and non-string, empty entries are skipped.
  * Pure, sync, no I/O — hook-safe per the module header.
  *
+ * PEER RECORDS ARE EXCLUDED (#1195 follow-through). A record whose id starts
+ * with `peer-session-` declares a territory NO agent of this wave may write —
+ * it exists so a peer's paths take part in the DISJOINTNESS check and so
+ * `hooks/post-bash-write-verify.mjs` can name a peer write instead of alarming
+ * about it. Unioning it into `allowedPaths` would do the exact inverse: Gate 7
+ * (`hooks/enforce-scope.mjs`) would GRANT every agent of the wave write access
+ * to the peer's files, and the hook's peer branch would become dead code (a
+ * peer path can only reach it while it is OUTSIDE `allowedPaths`). The
+ * exclusion lives HERE — the one helper `--union` runs — rather than in the
+ * CLI, so every consumer of the union inherits it.
+ * `findScopeCollisions` deliberately does NOT filter: a peer/agent path
+ * collision is a real collision and must surface.
+ *
  * @param {Array<string[]|{id?: string, files?: string[]}>} scopes
  * @returns {string[]} deduplicated union in first-seen order
  */
@@ -954,6 +989,7 @@ export function unionFileScopes(scopes) {
     let files = null;
     if (Array.isArray(scope)) files = scope;
     else if (scope !== null && typeof scope === 'object' && Array.isArray(scope.files)) {
+      if (isPeerRecordId(scope.id)) continue;
       files = scope.files;
     }
     if (files === null) continue;

package/scripts/lib/session-close-backfill.mjs

@@ -153,18 +153,33 @@ function collectSessionEvents(events, { sessionId, semanticSessionId }) {
 
   let mode = null;
   let semanticFromLock = null;
-
-  // First pass — lock.acquired bridges the UUID set + carries mode + semantic.
+  // #1167 — the SECOND semantic bridge. `orchestrator.session.ended` carries
+  // `semantic_session_id` alongside the raw UUID since #1068 AC1, but nothing
+  // read it: a session that LOST the lock-acquire race emits no lock.acquired,
+  // so the lock bridge above resolved null and the caller fell through to the
+  // synthetic-id mint — writing a SECOND `abandoned` stub for a session the
+  // SessionEnd hook had already recorded under its semantic id. Measured
+  // 2026-09-02 @ c3ab480: 8 such duplicate pairs in sessions.jsonl.
+  let semanticFromEvents = null;
+
+  // First pass — bridge the UUID set + carry mode + semantic id. lock.acquired
+  // is the original bridge; session.ended is the #1167 addition.
   for (const ev of events) {
-    if (ev.event !== EVENT_LOCK_ACQUIRED) continue;
+    const isLock = ev.event === EVENT_LOCK_ACQUIRED;
+    const isEnded = ev.event === EVENT_ENDED && typeof ev.semantic_session_id === 'string';
+    if (!isLock && !isEnded) continue;
     const matchesUuid = isUuid(sessionId) && ev.session_id === sessionId;
     const matchesSemantic =
       (semanticSessionId && ev.semantic_session_id === semanticSessionId) ||
       (!isUuid(sessionId) && sessionId && ev.semantic_session_id === sessionId);
     if (!matchesUuid && !matchesSemantic) continue;
     if (typeof ev.session_id === 'string') uuids.add(ev.session_id);
-    if (typeof ev.mode === 'string') mode = ev.mode;
-    if (typeof ev.semantic_session_id === 'string') semanticFromLock = ev.semantic_session_id;
+    if (isLock) {
+      if (typeof ev.mode === 'string') mode = ev.mode;
+      if (typeof ev.semantic_session_id === 'string') semanticFromLock = ev.semantic_session_id;
+    } else {
+      semanticFromEvents = ev.semantic_session_id;
+    }
   }
 
   // Second pass — started + terminal timestamps from every matched UUID.
@@ -200,7 +215,18 @@ function collectSessionEvents(events, { sessionId, semanticSessionId }) {
     }
   }
 
-  return { uuids, mode, semanticFromLock, startedAt, branch, project, lastTerminalMs, earliestMs, lastEventMs };
+  return {
+    uuids,
+    mode,
+    semanticFromLock,
+    semanticFromEvents,
+    startedAt,
+    branch,
+    project,
+    lastTerminalMs,
+    earliestMs,
+    lastEventMs,
+  };
 }
 
 /**
@@ -256,7 +282,7 @@ function isCandidateDeadByAge({ relaxDeadByAge, assumeDeadBeforeMs, lastEventMs,
  * this record replaces. It is emitted only when non-null, so every existing
  * record shape is byte-identical to before.
  */
-function synthesizeRecord({ recordId, synthetic, gathered, nowMs, status = 'abandoned', backfillSource = 'events-jsonl', supersedes = null }) {
+function synthesizeRecord({ recordId, synthetic, gathered, nowMs, status = 'abandoned', backfillSource = 'events-jsonl', supersedes = null, rawSessionId = null }) {
   const startedIso = canonicalIso(gathered.startedAt, gathered.earliestMs ?? nowMs);
   const startedMs = Date.parse(startedIso);
   // completed_at is events-attested, never the backfill-run wall-clock (#914 R1).
@@ -329,6 +355,13 @@ function synthesizeRecord({ recordId, synthetic, gathered, nowMs, status = 'aban
   // "historische Stub-Provenance bleibt erhalten"). Readers resolve one
   // canonical state per id by taking the NEWEST record for that id.
   if (typeof supersedes === 'string' && supersedes.length > 0) record.supersedes = supersedes;
+  // #1167 — the harness UUID this record was reconstructed from, when known.
+  // Additive and optional (the schema validates unknown keys pass-through, see
+  // session-schema/validator.mjs `_validateOptionalFields`): it is the ONLY key
+  // that lets a reader join a semantic record back to its raw uuid. Measured
+  // 2026-09-02 @ c3ab480: 0 of 286 existing records carry it, which is exactly
+  // why the two backfill writers could not see each other's work.
+  if (typeof rawSessionId === 'string' && rawSessionId.length > 0) record.raw_session_id = rawSessionId;
   return record;
 }
 
@@ -535,8 +568,11 @@ export async function backfillAbandonedSession({
 
       // -- Resolve a deferred id from the lock bridge or a synthetic mint ------
       if (recordId === null) {
-        if (gathered.semanticFromLock) {
-          recordId = gathered.semanticFromLock;
+        // Prefer the lock bridge (it also carries `mode`), then the #1167
+        // session.ended bridge. Only when NEITHER attests a semantic id do we
+        // mint a synthetic one — that fallback was the duplicate-stub source.
+        if (gathered.semanticFromLock || gathered.semanticFromEvents) {
+          recordId = gathered.semanticFromLock || gathered.semanticFromEvents;
         } else {
           // No semantic bridge — mint a synthetic id. Both components are STABLE
           // across re-runs so dedupe/marker suppress a double write (idempotency
@@ -619,7 +655,13 @@ export async function backfillAbandonedSession({
       }
 
       // -- Synthesize + validate (round-trip gate) BEFORE any disk mutation ---
-      const record = synthesizeRecord({ recordId, synthetic, gathered, nowMs });
+      const record = synthesizeRecord({
+        recordId,
+        synthetic,
+        gathered,
+        nowMs,
+        rawSessionId: isUuid(sessionId) ? sessionId : null,
+      });
       let validated;
       try {
         validated = validateSession(record);
@@ -845,6 +887,13 @@ export async function backfillCompletedFromStateMd({
         status: 'completed',
         backfillSource: 'state-md-completed',
         supersedes,
+        // #1167 — the abandoned path stamps this; so must the authoritative
+        // one, or the join key exists on exactly the weaker half of the pair.
+        // `gathered.uuids` is bridged from lock.acquired / session.ended, so it
+        // normally holds EXACTLY the one uuid this semantic id ran under. Two
+        // (or zero) means the bridge is ambiguous — omit rather than guess, the
+        // same fail-quiet posture as `isUuid(sessionId) ? sessionId : null`.
+        rawSessionId: gathered.uuids?.size === 1 ? [...gathered.uuids][0] : null,
       });
       let validated;
       try {

package/scripts/lib/session-discovery.mjs

@@ -32,6 +32,28 @@
  *   - Lock takes precedence over registry (more detail per session); registry
  *     supplements missing per-worktree entries (e.g., when the hook ran but
  *     the prose Phase 1.2 acquire was skipped).
+ *   - A live local session.lock does NOT supersede same-repo registry entries
+ *     with a different raw session_id (GH#67 candidate fix, measured 2026-09-02
+ *     and NOT adopted): the session lock is advisory, so a second session can
+ *     and demonstrably does run in the same working copy without holding it.
+ *     Filtering those entries out hides genuine same-working-copy peers — the
+ *     #1085 semantic-alias boundary (tests/integration/session-identity-
+ *     boundaries.test.mjs) and 7 peer-discovery cases pin exactly that
+ *     visibility. Any GH#67 fix must discriminate finished-but-fresh entries
+ *     some other way; do not re-attempt lock-ownership supersession here.
+ *     See ADR-0014 (docs/adr/0014-peer-visibility-under-advisory-lock.md) for
+ *     the annotate-never-filter decision and the 9-test refutation of the
+ *     filtering alternative.
+ *   - The adopted GH#67 shape is therefore ADDITIVE ANNOTATION, never a filter.
+ *     Registry-sourced sessions carry `registryOnly: true` plus
+ *     `lockSuperseded` / `lockOwnerId`. `lockSuperseded: true` means: a LIVE
+ *     lock at this repoRoot is owned by a different raw session_id than this
+ *     registry entry. It is a HINT, not a verdict — the lock is advisory, so
+ *     the entry may still be a live session that lost the acquire race (#1085
+ *     contract). Consumers deciding a worktree-PROMOTION_OFFER downgrade such
+ *     a peer to an advisory line (GH#67); consumers counting or displaying
+ *     peers keep it. Lock-sourced sessions carry none of the three fields, so
+ *     their objects stay byte-identical to the pre-GH#67 shape.
  *
  * Timeout + A1 fallback:
  *   - listWorktrees() is raced against DEFAULT_DISCOVERY_TIMEOUT_MS (2 s).
@@ -93,10 +115,24 @@ function sessionFromLock(lock, worktreePath, branch = '') {
  * does not record per-worktree paths — only repo-path-hashes. Branch is
  * passed through from the registry entry when available.
  *
+ * GH#67 annotation (additive, never a filter — see the module header): every
+ * registry-sourced session carries `registryOnly: true` and the pair
+ * `lockSuperseded` / `lockOwnerId`. `lockSuperseded: true` says a LIVE lock at
+ * this repoRoot is owned by a DIFFERENT raw session_id than this entry — a
+ * HINT that the entry may be a finished-but-still-fresh task (the GH#67 case:
+ * Codex emits no SessionEnd, so the registry entry outlives the task by up to
+ * `freshnessMin`). It is not a verdict: the lock is advisory, so the entry may
+ * equally be a live session that never acquired it (#1085). Consumers deciding
+ * a worktree PROMOTION_OFFER downgrade such a peer to an advisory line;
+ * consumers counting or displaying peers keep it unchanged.
+ *
  * @param {object} entry    Registry entry.
  * @param {string} repoRoot Discovery repoRoot (used as worktreePath fallback).
+ * @param {object} [ctx]
+ * @param {string|null} [ctx.lockOwnerId] Raw session_id owning a LIVE lock at
+ *   repoRoot, or null when there is no live local lock.
  */
-function sessionFromRegistryEntry(entry, repoRoot) {
+function sessionFromRegistryEntry(entry, repoRoot, { lockOwnerId = null } = {}) {
   return {
     worktreePath: repoRoot,
     sessionId:    entry.session_id,
@@ -111,6 +147,11 @@ function sessionFromRegistryEntry(entry, repoRoot) {
     // single machine, so consumers comparing hosts need the normalised form.
     host_id:      stableHostname(),
     branch:       typeof entry.branch === 'string' ? entry.branch : '',
+    // GH#67 additive annotation (see the JSDoc above). Lock-sourced sessions
+    // deliberately carry none of these three fields.
+    registryOnly: true,
+    lockSuperseded: lockOwnerId !== null && entry.session_id !== lockOwnerId,
+    lockOwnerId,
   };
 }
 
@@ -177,7 +218,10 @@ function dedupeBySessionId(sessions) {
  * @param {Function} [opts.registryReader]      DI hook replacing readRegistry() for tests.
  * @param {number}   [opts.freshnessMin=15]     Registry-entry freshness threshold in minutes.
  * @param {number}   [opts.now]                 ms-since-epoch (test seam for heartbeat freshness).
- * @returns {Promise<Array<{worktreePath:string,sessionId:string,mode:string,startedAt:string,pid:number,host:string,host_id:string,branch:string}>>}
+ * @returns {Promise<Array<{worktreePath:string,sessionId:string,mode:string,startedAt:string,pid:number,host:string,host_id:string,branch:string,registryOnly?:boolean,lockSuperseded?:boolean,lockOwnerId?:string|null}>>}
+ *   The last three fields appear ONLY on registry-sourced sessions (GH#67
+ *   annotation — see `sessionFromRegistryEntry`); lock-sourced sessions omit
+ *   them entirely.
  */
 export async function discoverActiveSessions(repoRoot, opts = {}) {
   const listWorktreesFn = opts.listWorktreesImpl ?? listWorktrees;
@@ -232,10 +276,20 @@ export async function discoverActiveSessions(repoRoot, opts = {}) {
   try {
     const allEntries = await registryReaderFn();
     const myRepoHash = repoPathHash(repoRoot);
+    // GH#67: who (if anyone) holds a LIVE lock at this repoRoot right now.
+    // Read once, outside the map — it is a property of the repo, not of an
+    // entry. A stale lock proves nothing, so it yields null.
+    const localLock = readLock({ repoRoot });
+    const lockOwnerId = (
+      localLock
+      && isLockLive(localLock, nowMs)
+      && typeof localLock.session_id === 'string'
+      && localLock.session_id
+    ) ? localLock.session_id : null;
     registrySessions = allEntries
       .filter((e) => e && e.repo_path_hash === myRepoHash)
       .filter((e) => isRegistryEntryFresh(e, { freshnessMin, now: nowMs }))
-      .map((e) => sessionFromRegistryEntry(e, repoRoot));
+      .map((e) => sessionFromRegistryEntry(e, repoRoot, { lockOwnerId }));
   } catch {
     // Registry read failure → keep going with lock-only results.
     registrySessions = [];

package/scripts/lib/session-end/phase-skip.mjs

@@ -55,7 +55,7 @@ import { sweepExpiredLearnings } from '../learnings/expiry-sweep.mjs';
 import { shouldDispatchAutoDream } from '../auto-dream.mjs';
 import { shouldDispatchAutoDialectic } from '../auto-dialectic.mjs';
 import { readSkillInvocations } from '../skill-invocations-schema.mjs';
-import { runReconcile, resolveEffectiveTargets } from '../reconcile/engine.mjs';
+import { runReconcileFromPhaseSkip, resolveEffectiveTargets } from '../reconcile/engine.mjs';
 import { resolveMemoryDir } from '../memory-paths.mjs';
 
 // ---------------------------------------------------------------------------
@@ -285,7 +285,7 @@ async function decideReconcile({ repoRoot, cfg }) {
     if (!existsSync(learningsPath)) {
       return mkSkip(phase, 'learnings.jsonl absent', 'learnings.jsonl');
     }
-    const { proposals, summary, error } = await runReconcile({
+    const { proposals, summary, error } = await runReconcileFromPhaseSkip({
       repoRoot,
       ruleExpiryDays: cfg?.reconcile?.['rule-expiry-days'] ?? undefined,
       minRuleDays: cfg?.reconcile?.['min-rule-days'] ?? undefined,

package/scripts/lib/session-identity/own-session.mjs

@@ -120,6 +120,61 @@ export function readOwnSessionIds(repoRoot, { hookInput = null } = {}) {
   return ids;
 }
 
+/**
+ * The ids that name this session and are PROCESS-LOCAL — tiers 1 and 2 only,
+ * never the lock and never STATE.md.
+ *
+ * A sibling of {@link readOwnSessionIds}, not a replacement: the two answer
+ * different questions and the difference is the whole point.
+ *
+ *   - `readOwnSessionIds()` answers *"could this id name me?"* and unions three
+ *     tiers, the third of which IS `session.lock`. That union is correct when
+ *     the thing being classified was written by some OTHER process (a wave-scope
+ *     manifest), because every id this process can legitimately claim counts.
+ *   - This function answers *"which process is emitting right now?"*, and for
+ *     that question the lock is **vacuous**: when the candidate ids under
+ *     judgement are the lock's OWN values, a membership test against a set that
+ *     contains the lock matches by construction — a peer-owned lock would
+ *     classify as `own` 100% of the time.
+ *
+ * **STATE.md is excluded for the same reason, and this is the #1177-FX1 fix.**
+ * `.claude/STATE.md` is a SHARED working-copy artefact written by whichever
+ * session owns the working copy — normally the lock holder. So when a peer holds
+ * the lock, the peer also wrote STATE.md, and the two "independent" witnesses
+ * agree with each other about the PEER. Unioning a shared-file witness with a
+ * process-local one lets the weaker witness carry the verdict while a
+ * disagreeing process-local id cannot veto it (measured: lock=peer +
+ * STATE.md=peer + `CLAUDE_CODE_SESSION_ID`=me stamped the PEER's ids). Tiering
+ * rather than unioning is the fix — a better signal REPLACES a worse one
+ * (`.claude/rules/host-resources.md` § HR-102).
+ *
+ * Never throws.
+ *
+ * @param {{ env?: object, hookInput?: object|null }} [opts]
+ * @param {object} [opts.env=process.env] — injectable for tests.
+ * @param {object|null} [opts.hookInput=null] — the harness's statement about
+ *   THIS invocation, when the caller is a hook.
+ * @returns {string[]} possibly EMPTY — an empty result means "this process
+ *   cannot prove who it is", which callers must treat as unprovable rather
+ *   than as a match.
+ */
+export function readProcessLocalSessionIds({ env = process.env, hookInput = null } = {}) {
+  const ids = [];
+  const add = (value) => {
+    const trimmed = typeof value === 'string' ? value.trim() : '';
+    if (trimmed && !ids.includes(trimmed)) ids.push(trimmed);
+  };
+
+  // Tier 1 — the harness's statement about THIS invocation.
+  if (hookInput && typeof hookInput === 'object') {
+    for (const key of ['session_id', 'sessionId', 'parent_session_id']) add(hookInput[key]);
+  }
+  // Tier 2 — process-scoped env var.
+  add(env?.CLAUDE_CODE_SESSION_ID);
+
+  return ids;
+}
+
 /**
  * Decide whether a wave-scope manifest belongs to THIS session.
  *
@@ -141,7 +196,13 @@ export function readOwnSessionIds(repoRoot, { hookInput = null } = {}) {
  *
  * @param {unknown} scope — parsed wave-scope manifest (any shape; a non-object
  *   simply yields no ids, hence `'unknown'`).
- * @param {Set<string>} ownIds — from {@link readOwnSessionIds}.
+ * @param {Set<string>} ownIds — from EITHER producer, depending on what is
+ *   being judged: {@link readOwnSessionIds} when every id this process could
+ *   legitimately claim counts, or `new Set(`{@link readProcessLocalSessionIds}
+ *   `(...))` when the lock tier would match vacuously — which is the case for a
+ *   wave-scope manifest in a checkout shared by two sessions (#1194). Note the
+ *   latter returns a `string[]`: a bare array is NOT a Set and folds to the
+ *   empty set below, yielding `'unknown'` for every manifest.
  * @returns {{ verdict: 'own'|'foreign'|'unknown', manifestIds: string[] }}
  */
 export function classifyManifestSession(scope, ownIds) {

package/scripts/lib/session-transition.mjs

@@ -134,7 +134,7 @@ export const LOCK_RELEASED_EVENT = 'orchestrator.session.lock.released';
  *   lock owned by someone else, an unparseable lock, a registry entry pinned to
  *   a different root, a registry unlink that failed, a contradictory owner
  *   proof, or a filesystem error. Callers WARN on it and continue; see the
- *   `parallel-aware: leaveSourceRoot: <reason>` contract in
+ *   `enterWorktree: leaveSourceRoot: <reason>` contract in
  *   `skills/_shared/parallel-aware-auq.md`.
  *
  *   `reason` is present whenever something other than a full clean teardown