session-orchestrator 3.21.0 → 3.23.0

package/scripts/lib/learnings/io.mjs

@@ -42,10 +42,20 @@ import {
  * append touches disk, so a bad write can never reach the file.
  *
  * @param {object} validated — already validated+normalized learning entry
+ * @param {{ legacyTolerant?: boolean }} [opts] — GitLab #386. When `true`,
+ *   a field that was ALREADY ABSENT on `validated` (e.g. a legacy record with
+ *   no `source_session`, tolerated by `readLearnings()`) stays tolerated after
+ *   the round-trip too — the re-validation call below runs in the same
+ *   tolerant mode. This does NOT weaken the #662 guarantee: a key that WAS
+ *   present on `validated` (even `undefined`) and is no longer a key on the
+ *   reparsed object is genuine JSON.stringify corruption, detected by the
+ *   dedicated `droppedKeys` check below and thrown regardless of
+ *   `legacyTolerant`. Default `false` — `appendLearning`'s single-record path
+ *   calls this with no options and is unaffected.
  * @returns {string} the verified JSONL line (newline-terminated)
  * @throws {ValidationError} when the serialized line does not round-trip
  */
-function serializeLearningLineChecked(validated) {
+function serializeLearningLineChecked(validated, { legacyTolerant = false } = {}) {
   let line;
   try {
     line = JSON.stringify(validated);
@@ -66,9 +76,23 @@ function serializeLearningLineChecked(validated) {
       `serialized learning line does not parse back as JSON: ${err.message}`
     );
   }
+  if (legacyTolerant) {
+    // A key that existed on `validated` (present, even as `undefined`) but
+    // vanished from `reparsed` was DROPPED by JSON.stringify — the exact
+    // undefined/NaN/etc. corruption #662 exists to catch. A key that was
+    // never on `validated` in the first place (the #386 legacy-field case)
+    // cannot appear here, because we only iterate `validated`'s own keys.
+    const droppedKeys = Object.keys(validated).filter((k) => !(k in reparsed));
+    if (droppedKeys.length > 0) {
+      throw new ValidationError(
+        `learning lost field(s) during JSON round-trip serialization ` +
+          `(non-serializable value?): ${droppedKeys.join(', ')}`
+      );
+    }
+  }
   // Re-validate the round-tripped shape — catches required fields that were
-  // present as `undefined`/`NaN` before stringify but vanished after.
-  validateLearning(reparsed);
+  // present as `undefined`/`NaN` before stringify but vanished/coerced after.
+  validateLearning(reparsed, { legacyTolerant });
   return line + '\n';
 }
 
@@ -203,29 +227,50 @@ async function rotateBackups(dir, baseName, keep = BACKUP_KEEP) {
  * - `backup` (default `true`): before the destructive rename, copy the current
  *   file to `${filePath}.bak-<ISO>`, then rotate to keep only the newest
  *   {@link BACKUP_KEEP}. Rotation is best-effort and never blocks the rewrite.
+ * - `legacyTolerant` (default `true`, GitLab #386): this function is a
+ *   ROUND-TRIP writer — its usual caller (`sweepExpiredLearnings` /
+ *   `pruneLearnings` in `expiry-sweep.mjs`) reads the store with
+ *   `readLearnings()` first, and that reader already tolerates a legacy
+ *   record missing e.g. `source_session` (WARN, pass through unchanged — see
+ *   `normalizeLearning`). Before this option existed, `rewriteLearnings()`
+ *   re-validated with the SAME strict gate `appendLearning()` uses for a
+ *   brand-new single record, so re-writing the unchanged KEEP batch of a
+ *   mechanical sweep could throw on data the reader itself had just accepted
+ *   — `sweep-expired-learnings --apply` failed on ANY store holding one such
+ *   record, even though the sweep never touches that record's fields. The
+ *   default is `true` precisely because the sweep/prune call sites cannot be
+ *   changed to opt in explicitly without touching `expiry-sweep.mjs`, which
+ *   passes no `legacyTolerant`; every field that genuinely CANNOT survive a
+ *   round-trip (a value JSON.stringify drops or coerces, e.g. `undefined`/
+ *   `NaN`) is still caught by the #662 checked serializer regardless of this
+ *   flag — see {@link serializeLearningLineChecked}. Pass `false` to restore
+ *   the pre-#386 fully-strict behaviour.
  *
  * @param {string} filePath
  * @param {object[]} entries
- * @param {{dryRun?: boolean, backup?: boolean}} [opts]
+ * @param {{dryRun?: boolean, backup?: boolean, legacyTolerant?: boolean}} [opts]
  * @returns {Promise<object[]>} validated entries (always returned, even dryRun)
  */
 export async function rewriteLearnings(
   filePath,
   entries,
-  { dryRun = false, backup = true } = {}
+  { dryRun = false, backup = true, legacyTolerant = true } = {}
 ) {
   const validated = entries.map((e) =>
-    validateLearning({
-      ...e,
-      schema_version: e?.schema_version ?? CURRENT_SCHEMA_VERSION,
-    })
+    validateLearning(
+      {
+        ...e,
+        schema_version: e?.schema_version ?? CURRENT_SCHEMA_VERSION,
+      },
+      { legacyTolerant }
+    )
   );
   // Pre-write round-trip self-validation (#662): serialize ALL entries through
   // the checked serializer before touching disk — a single bad entry throws
   // ValidationError and the file is left untouched (atomicity preserved because
   // we validate the full batch first, then write once). This runs even under
   // dryRun, so an invalid entry is still rejected on a dry probe.
-  const lines = validated.map((e) => serializeLearningLineChecked(e));
+  const lines = validated.map((e) => serializeLearningLineChecked(e, { legacyTolerant }));
 
   // dryRun (#721): validation has run; deliberately do NOT touch disk — no
   // rewrite, no backup — and hand the validated entries back to the caller.

package/scripts/lib/learnings/schema.mjs

@@ -59,7 +59,7 @@ export const CURRENT_ANONYMIZATION_VERSION = 1;
 
 /**
  * Type capability registry (Epic #723 I1, issue #733 Teil b) — the single
- * source of truth for every learning `type`'s TTL policy AND its two
+ * source of truth for every learning `type`'s TTL policy AND its three
  * cross-module capability axes. Before this registry existed, three modules
  * independently hand-maintained overlapping type lists that drifted out of
  * sync (`memory-proposals/schema.mjs` PROPOSAL_TYPES, `reconcile/eligibility.mjs`
@@ -76,39 +76,54 @@ export const CURRENT_ANONYMIZATION_VERSION = 1;
  *   - ruleConvertible:  may appear in `reconcile/eligibility.mjs` CONVERT_TYPES
  *                       (i.e. the reconcile engine may convert this type into a
  *                       conditional `.claude/rules/*.md` rule proposal).
+ *   - hostScoped:       this type's content is genuinely chip/OS-specific, so
+ *                       `reconcile/emitter.mjs` may copy a record's `host_class`
+ *                       through as the emitted rule's `host-class` activation
+ *                       axis (issue #1090; derived set: that module's
+ *                       HOST_SPECIFIC_TYPES). `false` for every general finding,
+ *                       whose `host_class` merely records the machine it was
+ *                       authored on and must never gate the rule.
+ *
+ * Every entry declares every axis explicitly — an omitted flag would read as
+ * `undefined` (falsy) and silently opt a new type out of a capability without
+ * anyone deciding that. Guarded by a test in
+ * `tests/lib/learnings-schema-normalization.test.mjs`.
  */
 export const LEARNING_TYPE_REGISTRY = Object.freeze({
-  'mode-selector-accuracy':      Object.freeze({ ttlDays: 30, agentProposable: true,  ruleConvertible: false }),
-  'hardware-pattern':            Object.freeze({ ttlDays: 60, agentProposable: true,  ruleConvertible: false }),
-  'fragile-file':                Object.freeze({ ttlDays: 45, agentProposable: true,  ruleConvertible: true  }),
-  'effective-sizing':            Object.freeze({ ttlDays: 45, agentProposable: true,  ruleConvertible: false }),
-  'recurring-issue':             Object.freeze({ ttlDays: 45, agentProposable: true,  ruleConvertible: true  }),
+  'mode-selector-accuracy':      Object.freeze({ ttlDays: 30, agentProposable: true,  ruleConvertible: false, hostScoped: false }),
+  // hardware-pattern is the ONLY hostScoped type today: its content IS the
+  // chip/OS, so gating the emitted rule by host-class is faithful rather than
+  // an accidental one-machine restriction (#1090).
+  'hardware-pattern':            Object.freeze({ ttlDays: 60, agentProposable: true,  ruleConvertible: false, hostScoped: true  }),
+  'fragile-file':                Object.freeze({ ttlDays: 45, agentProposable: true,  ruleConvertible: true,  hostScoped: false }),
+  'effective-sizing':            Object.freeze({ ttlDays: 45, agentProposable: true,  ruleConvertible: false, hostScoped: false }),
+  'recurring-issue':             Object.freeze({ ttlDays: 45, agentProposable: true,  ruleConvertible: true,  hostScoped: false }),
   // workflow-pattern / proven-pattern: flipped ruleConvertible false->true
   // (issue #900) — the real corpus census showed a large volume of live
   // `workflow-pattern`/`proven-pattern` records (post type-alias-normalization,
   // see LEARNING_TYPE_ALIASES below) that carried usable file_paths but were
   // structurally unconvertible before this flip.
-  'workflow-pattern':            Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: true  }),
-  'proven-pattern':              Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: true  }),
-  'anti-pattern':                Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: true  }),
-  'autopilot-effectiveness':     Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: false }),
+  'workflow-pattern':            Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: true,  hostScoped: false }),
+  'proven-pattern':              Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: true,  hostScoped: false }),
+  'anti-pattern':                Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: true,  hostScoped: false }),
+  'autopilot-effectiveness':     Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: false, hostScoped: false }),
   // autonomy-verdict (#683): repo/scope readiness synthesis from autopilot
   // effectiveness plus skill-judge signals. 90d matches the operational
   // autopilot-effectiveness horizon it depends on. Analyzer-only — never
   // agent-proposable.
-  'autonomy-verdict':            Object.freeze({ ttlDays: 90, agentProposable: false, ruleConvertible: false }),
+  'autonomy-verdict':            Object.freeze({ ttlDays: 90, agentProposable: false, ruleConvertible: false, hostScoped: false }),
   // domain-regression (#638): a sidecar-sourced regression flag (metric baseline→recent
   // delta) surfaced via /evolve extra-sources. 60d aligns with the moderate-decay tier
   // (hardware-pattern / default) — a regression signal should age out if it stops recurring.
-  'domain-regression':           Object.freeze({ ttlDays: 60, agentProposable: true,  ruleConvertible: false }),
-  'convention':                  Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: true  }),
-  'architecture-pattern':        Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: true  }),
-  'design-pattern':              Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: true  }),
+  'domain-regression':           Object.freeze({ ttlDays: 60, agentProposable: true,  ruleConvertible: false, hostScoped: false }),
+  'convention':                  Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: true,  hostScoped: false }),
+  'architecture-pattern':        Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: true,  hostScoped: false }),
+  'design-pattern':              Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: true,  hostScoped: false }),
   // fragile-pattern / stagnation-class-frequency: 0 live instances as of
   // 2026-07-02 (see reconcile/eligibility.mjs census) — CONVERT-eligible but
   // NOT agent-proposable (analyzer-synthesized classes, not agent-observed).
-  'fragile-pattern':             Object.freeze({ ttlDays: 45, agentProposable: false, ruleConvertible: true  }),
-  'stagnation-class-frequency':  Object.freeze({ ttlDays: 60, agentProposable: false, ruleConvertible: true  }),
+  'fragile-pattern':             Object.freeze({ ttlDays: 45, agentProposable: false, ruleConvertible: true,  hostScoped: false }),
+  'stagnation-class-frequency':  Object.freeze({ ttlDays: 60, agentProposable: false, ruleConvertible: true,  hostScoped: false }),
 });
 
 /**
@@ -215,47 +230,99 @@ export class ValidationError extends Error {
  * Throws ValidationError on contract violations. Does NOT mutate input.
  *
  * @param {object} entry — candidate learning
+ * @param {{ legacyTolerant?: boolean }} [opts] — GitLab #386. When `true`, a
+ *   value `normalizeLearning()` already passes through UNCHECKED (or merely
+ *   DEFAULTED, never validated) on read is no longer rejected here either:
+ *   an out-of-enum `schema_version` (measured against the real EventDrop.at
+ *   store: 3 live records carry `schema_version: 2`), the
+ *   LEGACY_REQUIRED_FIELDS presence check, the `confidence` range/type check
+ *   when NO `confidence` key is present, and the `scope`/`host_class`/
+ *   `anonymized` shape checks (measured live: a record with `scope:
+ *   "src/components/landing/mobile-sticky-cta.tsx"` — a producer bug that
+ *   wrote a file path into the scope column, which `normalizeLearning` never
+ *   validates and therefore never rejects). A field that IS present keeps
+ *   being validated regardless when its DATA TYPE can be silently corrupted
+ *   by a JSON round-trip (a present-but-malformed `confidence` still throws
+ *   — see io.mjs #662): this option relaxes "you must HAVE a valid value",
+ *   never "if a round-trip could have silently mangled it, that's fine too".
+ *   The privacy CONTRACT (`scope: 'public'` requiring `anonymized`/
+ *   `host_class` to be consistent) is NEVER relaxed — it only ever fires for
+ *   a record that genuinely claims `scope: 'public'`, which is exactly the
+ *   case a round-trip must not silently launder. Default `false` — every
+ *   existing direct caller (including `appendLearning`'s single-record write
+ *   path) is unaffected.
  * @returns {object} normalized entry with scope/host_class/anonymized defaulted
  */
-export function validateLearning(entry) {
+export function validateLearning(entry, { legacyTolerant = false } = {}) {
   if (!entry || typeof entry !== 'object') {
     throw new ValidationError('learning must be an object');
   }
 
   // schema_version: 0 (implicit/legacy), 1 (current). Both accepted.
+  // `normalizeLearning()` never validates this value on read (any value
+  // passes through as-is), so under legacyTolerant an ABSENT schema_version
+  // (defaults to the valid `0`) or one already present with SOME value is
+  // both fine — only a truly missing-AND-invalid combination cannot occur
+  // (missing defaults to 0, which is always valid), so in practice this skips
+  // the check whenever legacyTolerant is set and a non-legacy value survived
+  // a prior read (e.g. `schema_version: 2`, measured live in production).
   const schemaVersion = entry.schema_version ?? 0;
-  if (schemaVersion !== 0 && schemaVersion !== 1) {
+  if (!legacyTolerant && schemaVersion !== 0 && schemaVersion !== 1) {
     throw new ValidationError(
       `schema_version must be 0 (legacy) or 1, got: ${schemaVersion}`
     );
   }
 
-  for (const field of LEGACY_REQUIRED_FIELDS) {
-    if (!(field in entry)) {
-      throw new ValidationError(`learning missing required field: ${field}`);
+  if (!legacyTolerant) {
+    for (const field of LEGACY_REQUIRED_FIELDS) {
+      if (!(field in entry)) {
+        throw new ValidationError(`learning missing required field: ${field}`);
+      }
     }
   }
 
-  if (typeof entry.confidence !== 'number' || entry.confidence < 0 || entry.confidence > 1) {
-    throw new ValidationError(`confidence must be a number in [0, 1], got: ${entry.confidence}`);
+  // confidence carries its own type/range check in addition to the presence
+  // loop above, so it needs its own legacyTolerant gate: skip ONLY when the
+  // key is genuinely absent (mirrors the presence loop); a present-but-bad
+  // value (wrong type, out of range, or `null` after a JSON round-trip
+  // coerced a non-serializable value — see io.mjs #662) still throws under
+  // legacyTolerant, same as under strict mode.
+  if (!legacyTolerant || 'confidence' in entry) {
+    if (typeof entry.confidence !== 'number' || entry.confidence < 0 || entry.confidence > 1) {
+      throw new ValidationError(`confidence must be a number in [0, 1], got: ${entry.confidence}`);
+    }
   }
 
+  // scope/host_class/anonymized: `normalizeLearning()` only DEFAULTS an
+  // absent value (`d.scope ?? 'local'`, etc.) on read — it never validates a
+  // PRESENT one, so a corrupt legacy value round-trips silently today
+  // (measured live in production: a record with `scope:
+  // "src/components/landing/mobile-sticky-cta.tsx"` — evidently a producer
+  // bug that wrote a file path into the scope column). All three checks are
+  // therefore skipped under legacyTolerant. Unlike `confidence` (a number,
+  // where `NaN`/`Infinity` are non-JSON-safe and silently become `null`
+  // across a JSON round-trip — the #662 concern), a string/string-or-null/
+  // boolean value round-trips through JSON byte-for-byte, so there is no
+  // corresponding round-trip-corruption risk to guard against here.
   const scope = entry.scope ?? 'local';
-  if (!VALID_SCOPES.includes(scope)) {
+  if (!legacyTolerant && !VALID_SCOPES.includes(scope)) {
     throw new ValidationError(`scope must be one of ${VALID_SCOPES.join('|')}, got: ${scope}`);
   }
 
   const hostClass = entry.host_class ?? null;
-  if (hostClass !== null && typeof hostClass !== 'string') {
+  if (!legacyTolerant && hostClass !== null && typeof hostClass !== 'string') {
     throw new ValidationError(`host_class must be string or null, got: ${typeof hostClass}`);
   }
 
   const anonymized = entry.anonymized ?? false;
-  if (typeof anonymized !== 'boolean') {
+  if (!legacyTolerant && typeof anonymized !== 'boolean') {
     throw new ValidationError(`anonymized must be boolean, got: ${typeof anonymized}`);
   }
 
-  // Privacy contract
+  // Privacy contract — NEVER relaxed, legacyTolerant or not: an out-of-enum
+  // `scope` (garbage or otherwise) is by definition not `'public'`, so this
+  // pair only ever fires for a record that genuinely claims `scope: 'public'`
+  // — exactly the case a round-trip must not silently launder.
   if (scope === 'public' && !anonymized) {
     throw new ValidationError(
       'scope=public requires anonymized=true (privacy contract violation)'

package/scripts/lib/lock-reaper.mjs

@@ -68,6 +68,7 @@ import path from 'node:path';
 import { enumerateCandidates } from './dispatcher/enumerate.mjs';
 import { readLock, isLockLive, isPidAliveOnHost, LOCK_PATH, DEFAULT_TTL_HOURS } from './session-lock.mjs';
 import { emitEvent } from './events.mjs';
+import { hostnamesMatch, lockHostCandidate } from './host-identity.mjs';
 
 const REAPED_ARCHIVE_SUBDIR = '.orchestrator/tmp/reaped-locks';
 const REAPED_EVENT = 'orchestrator.session.lock.reaped';
@@ -463,7 +464,12 @@ async function evaluateRepo(repoRoot, { nowMs, dryRun, currentSessionId, reapMod
     };
   }
 
-  const ownHost = lock.host === D.hostname();
+  // #1072: alias-aware host identity. A raw comparison classified this
+  // machine's OWN orphaned lock as cross-host after a hostname flip, so it was
+  // never reaped and every subsequent session needed operator intervention.
+  // The invariant is unchanged for a genuinely foreign host: its name was never
+  // written into this machine's self-alias ledger, so it can never match.
+  const ownHost = hostnamesMatch(lockHostCandidate(lock), D.hostname());
 
   // Invariant (c): cross-host leases are NEVER auto-reaped — only listed.
   if (!ownHost) {

package/scripts/lib/locks/staging-fence-lock.mjs

@@ -28,6 +28,7 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 
 import { tryAcquireFileLock } from '../file-lock.mjs';
+import { hostnamesMatch, lockHostCandidate, stableHostname } from '../host-identity.mjs';
 import { nowIso, delay, parseLockBody } from './lock-body.mjs';
 
 // ---------------------------------------------------------------------------
@@ -67,7 +68,9 @@ function stagingFenceLockPathFor(repoRoot) {
 function buildStagingFenceLockBody({ holder }) {
   return {
     pid: process.pid,
+    // `host` raw + `host_id` normalised (#1072) — see buildStateLockBody.
     host: os.hostname(),
+    host_id: stableHostname(),
     acquiredAt: nowIso(),
     holder: typeof holder === 'string' && holder.length > 0 ? holder : `pid-${process.pid}`,
   };
@@ -178,7 +181,8 @@ export function releaseStagingFenceLock({ repoRoot, holder } = {}) {
 
   const ownerMatch = typeof holder === 'string' && holder.length > 0
     ? lock.holder === holder
-    : lock.pid === process.pid && lock.host === os.hostname();
+    // #1072: alias-aware host identity, not a raw os.hostname() comparison.
+    : lock.pid === process.pid && hostnamesMatch(lockHostCandidate(lock), os.hostname());
 
   if (!ownerMatch) {
     return { ok: false, reason: 'not-owner' };

package/scripts/lib/locks/state-md-lock.mjs

@@ -41,6 +41,7 @@ import crypto from 'node:crypto';
 
 import { _parseStateMdLock } from '../config/state-md-lock.mjs';
 import { tryAcquireFileLock } from '../file-lock.mjs';
+import { hostnamesMatch, lockHostCandidate, stableHostname } from '../host-identity.mjs';
 import { nowIso, delay, parseLockBody } from './lock-body.mjs';
 
 // ---------------------------------------------------------------------------
@@ -78,7 +79,11 @@ function stateLockPathFor(repoRoot) {
 function buildStateLockBody({ holder }) {
   return {
     pid: process.pid,
+    // `host` raw + `host_id` normalised (#1072). The written body comes from
+    // tryAcquireFileLock, which carries the same pair — this keeps the shape
+    // declared here truthful about what lands on disk.
     host: os.hostname(),
+    host_id: stableHostname(),
     acquiredAt: nowIso(),
     holder: typeof holder === 'string' && holder.length > 0 ? holder : `pid-${process.pid}`,
   };
@@ -224,7 +229,9 @@ export function releaseStateLock({ repoRoot, sessionId, holder } = {}) {
   const expectedHolder = holder ?? sessionId ?? null;
   const ownerMatch = expectedHolder !== null
     ? lock.holder === expectedHolder
-    : lock.pid === process.pid && lock.host === os.hostname();
+    // #1072: alias-aware host identity — a raw comparison strands the lock as
+    // 'not-owner' once os.hostname() flips spelling mid-session.
+    : lock.pid === process.pid && hostnamesMatch(lockHostCandidate(lock), os.hostname());
 
   if (!ownerMatch) {
     return { ok: false, reason: 'not-owner' };

package/scripts/lib/memory-banner.mjs

@@ -308,7 +308,7 @@ async function countMemoryFiles(dir) {
  *
  * @param {object} args
  * @param {string} args.repoRoot — absolute path
- * @param {string} [args.memoryDir] — defaults to `resolveMemoryDir()`
+ * @param {string} [args.memoryDir] — defaults to `resolveMemoryDir(repoRoot)`
  * @param {string} [args.learningsPath] — defaults to `<repoRoot>/.orchestrator/metrics/learnings.jsonl`
  * @param {Date}   [args.now] — injectable clock for tests
  * @param {{enabled?: boolean, 'half-life-days'?: number, 'floor-factor'?: number}} [args.evolveDecay]
@@ -326,9 +326,12 @@ export async function readBannerInputs({ repoRoot, memoryDir, learningsPath, now
   if (typeof repoRoot !== 'string' || repoRoot.length === 0) {
     throw new TypeError('readBannerInputs: repoRoot is required (absolute path)');
   }
+  // #1071: bind the memory dir to the SAME root as learnings/sessions/peer-cards
+  // below. Called with no argument it derived from the ambient `process.cwd()`,
+  // which reported `0 memory files` beside a 245-session count from `repoRoot`.
   const memDir = typeof memoryDir === 'string' && memoryDir.length > 0
     ? memoryDir
-    : resolveMemoryDir();
+    : resolveMemoryDir(repoRoot);
   const learningsFile = typeof learningsPath === 'string' && learningsPath.length > 0
     ? learningsPath
     : path.join(repoRoot, '.orchestrator', 'metrics', 'learnings.jsonl');

package/scripts/lib/memory-paths.mjs

@@ -15,17 +15,26 @@ import os from 'node:os';
 /**
  * Resolve the project-specific memory directory used by the Claude Code harness.
  *
- * Mirrors the harness convention: `~/.claude/projects/<encoded-cwd>/memory/`
- * where `<encoded-cwd>` is the cwd with BOTH `/` AND `.` replaced by `-`. The
- * dot replacement matters for users with a trailing-`.` in their home dir
- * (e.g. `/Users/<owner>.`) — without it the resolved path diverges from
+ * Mirrors the harness convention: `~/.claude/projects/<encoded-root>/memory/`
+ * where `<encoded-root>` is the project root with BOTH `/` AND `.` replaced by
+ * `-`. The dot replacement matters for users with a trailing-`.` in their home
+ * dir (e.g. `/Users/<owner>.`) — without it the resolved path diverges from
  * what the harness actually wrote.
  *
  * Verified empirically against `~/.claude/projects/` directory naming.
  *
+ * `repoRoot` is explicit (#1071) because every OTHER banner input is already
+ * bound to it: with the memory dir alone derived from the ambient `process.cwd()`,
+ * a caller reading sessions/learnings/peer-cards out of the primary checkout
+ * reported `0 memory files` whenever the process ran from a worktree or a
+ * subdirectory. Defaulted, so existing zero-arg callers keep their behaviour.
+ *
+ * @param {string} [repoRoot] — absolute project root; defaults to `process.cwd()`.
  * @returns {string} Absolute path to the memory directory (not guaranteed to exist).
  */
-export function resolveMemoryDir() {
-  const encoded = process.cwd().replaceAll('/', '-').replaceAll('.', '-');
+export function resolveMemoryDir(repoRoot = process.cwd()) {
+  const root =
+    typeof repoRoot === 'string' && repoRoot.length > 0 ? repoRoot : process.cwd();
+  const encoded = root.replaceAll('/', '-').replaceAll('.', '-');
   return path.join(os.homedir(), '.claude', 'projects', encoded, 'memory');
 }

package/scripts/lib/mode-selector/scoring.mjs

@@ -82,6 +82,57 @@ export function safeBootstrapLock(signals) {
     : null;
 }
 
+/**
+ * Read a session record's completion rate, tolerating both the shape
+ * `sessions.jsonl` actually writes and the legacy flat one.
+ *
+ * Production records nest it: `{effectiveness: {completion_rate: 0.77, …}}`.
+ * The top-level `completion_rate` key is ABSENT — not present-but-null, which
+ * an earlier revision of this comment claimed. Measured 2026-08-28 @ 7daa3d2
+ * over `.orchestrator/metrics/sessions.jsonl` (281 records):
+ * `jq -s '{hasTopLevelKey: ([.[]|select(has("completion_rate"))]|length), …}'`
+ * → `hasTopLevelKey: 0`, `nested: 182`, and 99 records carrying NO completion
+ * rate in either shape. Reading only the flat field therefore made every
+ * average 0 in production — see #1071.
+ *
+ * Precedence mirrors `completionOf()` in
+ * `scripts/lib/evolve/autopilot-effectiveness.mjs`: nested canonical fields
+ * first, flat legacy fields as a backward-compatible fallback for
+ * hand-written/pre-nesting records.
+ *
+ * @param {unknown} session
+ * @returns {number} completion rate, or 0 when unknown
+ */
+function completionRateOf(session) {
+  if (session === null || typeof session !== 'object') return 0;
+  const eff = (session.effectiveness !== null && typeof session.effectiveness === 'object')
+    ? session.effectiveness
+    : {};
+  const raw =
+    eff.completion_rate ?? eff.completion_ratio ?? session.completion_rate ?? session.completion_ratio;
+  return typeof raw === 'number' && !Number.isNaN(raw) ? raw : 0;
+}
+
+/**
+ * Mean completion rate across a session slice. Unknown values contribute 0 and
+ * the divisor stays the slice length — an incomplete slice can never inflate
+ * the average past the >= 0.9 bonus threshold.
+ *
+ * The divisor is the load-bearing half, not the numerator: 99 of the 281
+ * records in production carry no completion rate in EITHER shape (measured
+ * 2026-08-28 @ 7daa3d2), so a divisor of "known values only" would let a single
+ * 1.0 session beside two unknowns score a perfect 1.0 and hand out the trend
+ * bonus on one data point. Pinned by the divisor test in
+ * `tests/lib/mode-selector/scoring.test.mjs`.
+ *
+ * @param {any[]} sessions
+ * @returns {number}
+ */
+function avgCompletionRate(sessions) {
+  if (sessions.length === 0) return 0;
+  return sessions.reduce((sum, s) => sum + completionRateOf(s), 0) / sessions.length;
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -107,9 +158,7 @@ export function computeDelta(candidateMode, signals) {
       (s) => typeof s === 'object' && s !== null && s.session_type === candidateMode,
     );
     if (allMatch) {
-      const avgCompletion =
-        last3.reduce((sum, s) => sum + (typeof s.completion_rate === 'number' ? s.completion_rate : 0), 0) /
-        3;
+      const avgCompletion = avgCompletionRate(last3);
       trendBonus = avgCompletion >= 0.9 ? 0.15 : 0.075;
     }
   }
@@ -151,9 +200,7 @@ export function computeDelta(candidateMode, signals) {
         (s) => typeof s === 'object' && s !== null && s.session_type === otherMode,
       );
       if (allOther) {
-        const avgCompletion =
-          last3.reduce((sum, s) => sum + (typeof s.completion_rate === 'number' ? s.completion_rate : 0), 0) /
-          3;
+        const avgCompletion = avgCompletionRate(last3);
         if (avgCompletion >= 0.9) {
           penalty += 0.10;
           break; // only one other dominant mode possible