session-orchestrator 3.16.0 → 3.17.0

package/docs/telemetry.md

@@ -0,0 +1,158 @@
+# Telemetry
+
+Session Orchestrator ships an **optional, strictly opt-in** anonymous
+usage-telemetry client. This page is the transparency contract: exactly what
+is collected, what is never collected, how consent works, every kill switch,
+where the data goes, and how long it is kept. Nothing here is aspirational —
+it is the locked v1 schema and consent precedence this plugin implements.
+
+## TL;DR
+
+- **Off by default.** Nothing is sent until you explicitly consent.
+- **One prompt, ever.** An interactive session asks once, at most; the
+  answer is saved locally and never asked again (until you reset it).
+- **Trivial to turn off**, at any time, with an environment variable or a
+  one-line CLI command — no restart, no config-file archaeology.
+- **No CI/headless sends, ever.** Non-interactive sessions never prompt and
+  never send, regardless of prior consent state.
+- **Fully open source.** The client code and the ingest-server code both
+  live in this repository — nothing is a black box.
+- **Not the same thing as the local metrics used in marketing claims.** See
+  [Relationship to `telemetry-claims.md`](#relationship-to-telemetry-claimsmd)
+  below.
+
+## What we collect
+
+When telemetry is enabled and a batch is flushed, the payload is built from
+a strict field whitelist — nothing outside this list is ever included, and a
+projection unit test enforces the drop of any non-whitelisted input field.
+
+| Field | Meaning |
+|---|---|
+| `record_kind` | Always `"usage-ping"` for this record type. |
+| `schema_version` | Currently `1`. Additive-only evolution within a version — see [Schema evolution](#schema-evolution). |
+| `anon_id` | A random UUID, not derived from any machine identifier. Rotates every 90 days; the old ID is discarded, not linked to the new one. |
+| `sent_at` | Timestamp of the flush. |
+| `plugin_version` | The installed plugin's semver. |
+| `platform` | One of `claude`, `codex`, `cursor`, `pi`, `other`. |
+| `os` | Operating system family (e.g. `darwin`, `linux`, `win32`). |
+| `arch` | CPU architecture (e.g. `arm64`, `x64`). |
+| `node_major` | Major Node.js version in use. |
+| `ci` | Boolean — whether the run was detected as a CI environment. |
+| `fleet` | Boolean — whether this send came from an operator's own fleet-mode host (`owner.yaml` opt-in), as opposed to an external install. |
+| `session_type` | One of `housekeeping`, `feature`, `deep`, `other`. |
+| `duration_bucket` | One of `<15m`, `15-60m`, `1-3h`, `>3h` — a coarse bucket, never an exact duration. |
+| `skills[]` | Names of invoked skills, filtered against the shipped plugin roster — any name not in that roster becomes `"other"`. |
+| `commands[]` | Same filtering rule as `skills[]`. |
+
+## What we never collect
+
+This list is a hard invariant, not a deferral:
+
+- No repository names, no file paths, no git remotes.
+- No prompts, no session transcripts, no free-form text of any kind.
+- No command arguments — only whitelisted command/skill *names*, and only
+  from the shipped roster (anything else is reduced to `"other"`).
+- No hostnames.
+- No IP addresses stored. The ingest server uses the requester's IP
+  **transiently, in memory, only** to enforce a per-IP rate limit — it is
+  never written to disk, and access logging is disabled on the telemetry
+  vhost.
+- No email addresses, no git author identity, no account identifiers.
+
+If a skill or command name isn't part of the plugin's own shipped roster —
+including any custom or third-party skill you've added locally — it never
+leaves your machine; it is projected to `"other"` before the payload is
+built.
+
+## Consent & kill switches
+
+Precedence, highest wins:
+
+1. **`DO_NOT_TRACK`** — any non-empty value except `0`/`false` disables
+   telemetry unconditionally. This is the industry-standard signal and
+   overrides everything else, including a fleet force-enable.
+2. **`SO_TELEMETRY_DISABLED=1`** — explicit per-shell disable.
+3. **`SO_TELEMETRY=1`** — explicit per-shell force-enable (used for fleet
+   testing without touching the consent file).
+4. **`owner.yaml` `telemetry.enabled`** — host-local fleet-mode opt-in (see
+   below); has no effect on a machine without that file.
+5. **Saved consent** — `~/.config/session-orchestrator/telemetry.json`,
+   written the first time you answer the consent prompt. Never inside any
+   repository, never committed.
+6. **First-run prompt** — shown at most once, **interactively only**. A
+   headless or CI invocation never shows this prompt and never sends
+   telemetry, regardless of any saved state.
+
+If the consent file is corrupt or unreadable, the client fails **closed**:
+telemetry state degrades to "no consent" (nothing sent) rather than
+guessing, with a one-line stderr hint pointing at the CLI below.
+
+**CLI:**
+
+```bash
+node scripts/telemetry.mjs status    # show current consent + kill-switch state
+node scripts/telemetry.mjs enable    # opt in
+node scripts/telemetry.mjs disable   # opt out
+node scripts/telemetry.mjs show      # print the last built payload, don't send
+```
+
+**Debug flag:** set `SO_TELEMETRY_DEBUG=1` to print the exact payload that
+*would* be sent to stderr instead of sending it — useful for verifying the
+whitelist projection yourself before ever trusting it.
+
+**Fleet mode.** An operator running many repos on one host can set
+`telemetry.enabled: true` (and optionally `telemetry.fleet: true`) in their
+own `owner.yaml` — a host-local, never-committed file outside every repo —
+to enable telemetry across all adopted repos without a per-repo prompt.
+Records sent this way carry `fleet: true`. `DO_NOT_TRACK` and
+`SO_TELEMETRY_DISABLED=1` still win over fleet mode in the same shell.
+
+## Where it goes
+
+Consented payloads are sent as a batched `POST` to:
+
+```
+https://telemetry.session-orchestrator.com/v1/records
+```
+
+This endpoint is operated by the plugin's maintainer. The server-side code
+is open source in this same repository, under `server/ingest/` — a
+dependency-light Node service that validates the payload against the
+per-`record_kind` schema, stores it in SQLite, and rejects anything that
+doesn't fit the schema (unknown `record_kind`, oversized body, or a schema
+violation). There is no third-party analytics vendor in this path — no
+Segment, no Mixpanel, no Google Analytics.
+
+The send is fire-and-forget with a short timeout; if the endpoint is
+unreachable, the batch queues locally (bounded size, oldest entries dropped
+first) and retries later. Telemetry never blocks or slows down a session
+beyond that short timeout budget.
+
+## Retention
+
+- **Raw records:** kept 24 months, then pruned. The retention window exists
+  to support year-over-year product decisions (what to deepen, what to
+  sunset) without keeping data indefinitely.
+- **Aggregates:** kept indefinitely; aggregates carry no record-level
+  identifiers by construction.
+- **Anonymous ID rotation:** every 90 days, independent of retention — a
+  rotated ID cannot be linked back to the one it replaced.
+
+## Schema evolution
+
+The schema is **additive-only** within a given `schema_version`: new
+optional fields may appear, but no field is ever repurposed or removed
+without a version bump. The server accepts both the current and the
+immediately previous `schema_version`, so a slightly-outdated client is
+never hard-broken by a server-side schema update.
+
+## Relationship to `telemetry-claims.md`
+
+This page describes the **opt-in, client-side usage-telemetry pipeline**
+above. It is a distinct data flow from
+[`docs/telemetry/telemetry-claims.md`](telemetry/telemetry-claims.md), which
+documents the methodology behind the maintainer's separate **local, private**
+metrics aggregates (`.orchestrator/metrics/*.jsonl`, gitignored, never
+transmitted anywhere) used in marketing claims such as "645 orchestrated
+sessions." Neither pipeline feeds the other.

package/hooks/hooks-codex.json

@@ -7,7 +7,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🎯 Session Orchestrator v3.16.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
+            "command": "echo '🎯 Session Orchestrator v3.17.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
             "async": false
           },
           {

package/hooks/hooks.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🎯 Session Orchestrator v3.16.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
+            "command": "echo '🎯 Session Orchestrator v3.17.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
             "async": false
           },
           {

package/hooks/skill-invocation-telemetry.mjs

@@ -6,23 +6,35 @@
  * Fires when the Skill tool is invoked (a skill is selected). Writes a
  * selection record to `.orchestrator/metrics/skill-invocations.jsonl`.
  *
- * Decision flow:
+ * Decision flow (when run as the hook, not imported):
  *   1. shouldRunHook gate — exit 0 immediately when the hook is disabled.
  *   2. Read JSON payload from stdin: { tool_name, tool_input: { skill }, session_id }.
  *   3. Belt-and-suspenders guard: if tool_name !== "Skill", exit 0 immediately.
  *   4. Build a 'selected' record and call appendSkillInvocation().
- *   5. Output: nothing on stdout. Diagnostic errors to stderr only.
+ *   5. Daily-fallback telemetry flush check (Epic #841, #844) — non-blocking:
+ *      when a bounded offline queue has aged past 24h AND consent resolves to
+ *      send, spawn a detached child that runs `telemetry _flush`. Cheap by
+ *      construction (env kill-switch pre-check → queue+state stat → consent)
+ *      and never loads the roster on the hot hook path.
+ *   6. Output: nothing on stdout. Diagnostic errors to stderr only.
  *
  * Exit codes: 0 always (informational, never blocking).
+ *
+ * The module is import-safe: the self-execution block below is guarded so that a
+ * test can `import { maybeSpawnDailyFlush }` without triggering the hook's
+ * stdin-read + exit path.
  */
 
-import { shouldRunHook } from './_lib/profile-gate.mjs';
-// Exit 0 immediately when disabled via SO_HOOK_PROFILE / SO_DISABLED_HOOKS.
-if (!shouldRunHook('skill-invocation-telemetry')) process.exit(0);
-
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+
+import { shouldRunHook } from './_lib/profile-gate.mjs';
 import { appendSkillInvocation } from '../scripts/lib/skill-invocations-schema.mjs';
 import { SO_PROJECT_DIR } from '../scripts/lib/platform.mjs';
+import { shouldDailyFlush } from '../scripts/lib/telemetry/sync.mjs';
+import { resolveConsent, readTelemetryState } from '../scripts/lib/telemetry/consent.mjs';
+import { loadOwnerConfig } from '../scripts/lib/owner-yaml.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -30,10 +42,29 @@ import { SO_PROJECT_DIR } from '../scripts/lib/platform.mjs';
 
 const JSONL_PATH = path.join(SO_PROJECT_DIR, '.orchestrator', 'metrics', 'skill-invocations.jsonl');
 
+/** Absolute path to the telemetry CLI (carries the hidden `_flush` subcommand). */
+const TELEMETRY_CLI_PATH = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../scripts/telemetry.mjs',
+);
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * True when an env var carries a truthy "on" signal (present, non-empty, not
+ * '0'/'false'). Kept local so the hook does not pull anything extra from consent.mjs.
+ * @param {unknown} raw
+ * @returns {boolean}
+ */
+function isTruthyEnvFlag(raw) {
+  if (raw === undefined || raw === null) return false;
+  const t = String(raw).trim();
+  if (t === '' || t === '0') return false;
+  return t.toLowerCase() !== 'false';
+}
+
 /**
  * Read stdin to EOF (best-effort). Returns parsed JSON or null on failure.
  * Uses a 5 s timeout consistent with Claude Code hook contract.
@@ -61,6 +92,61 @@ function readStdinJson() {
   });
 }
 
+/**
+ * Non-blocking daily-fallback flush trigger. Ordered cheapest-first:
+ *   1. env kill-switches (no I/O) — DO_NOT_TRACK / SO_TELEMETRY_DISABLED.
+ *   2. shouldDailyFlush (one telemetry.json read + one queue stat) — the common
+ *      case (empty queue) returns here WITHOUT loading owner.yaml or the roster.
+ *   3. full consent resolution — spawn a detached `telemetry _flush` only when it
+ *      resolves to send.
+ *
+ * Never throws; the caller's hook must always exit 0.
+ *
+ * @param {object} [opts]
+ * @param {NodeJS.ProcessEnv} [opts.env]  Env source (default process.env).
+ * @param {typeof spawn} [opts.spawnFn]   Spawn function (test injection).
+ * @param {number} [opts.now]             Reference time epoch-ms (default Date.now()).
+ * @param {string} [opts.statePath]       telemetry.json path override (test injection).
+ * @param {string} [opts.queuePath]       queue path override (test injection).
+ * @returns {{ spawned: boolean, reason: string }}
+ */
+export function maybeSpawnDailyFlush({
+  env = process.env,
+  spawnFn = spawn,
+  now = Date.now(),
+  statePath,
+  queuePath,
+} = {}) {
+  try {
+    // 1. Cheapest gate: env kill-switches, no file I/O.
+    if (isTruthyEnvFlag(env?.DO_NOT_TRACK) || env?.SO_TELEMETRY_DISABLED === '1') {
+      return { spawned: false, reason: 'disabled-env' };
+    }
+
+    // 2. Cheap backlog check — bails out before owner.yaml load in the common case.
+    if (!shouldDailyFlush({ statePath, queuePath, now })) {
+      return { spawned: false, reason: 'not-due' };
+    }
+
+    // 3. Authoritative consent gate.
+    const ownerConfig = loadOwnerConfig().config;
+    const { record } = readTelemetryState({ path: statePath });
+    const consent = resolveConsent({ env, ownerConfig, state: record, interactive: false });
+    if (consent.send !== true) {
+      return { spawned: false, reason: 'gated' };
+    }
+
+    const child = spawnFn(process.execPath, [TELEMETRY_CLI_PATH, '_flush'], {
+      detached: true,
+      stdio: 'ignore',
+    });
+    if (child && typeof child.unref === 'function') child.unref();
+    return { spawned: true, reason: 'spawned' };
+  } catch {
+    return { spawned: false, reason: 'error' };
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
@@ -91,9 +177,22 @@ async function main() {
   };
 
   await appendSkillInvocation(JSONL_PATH, record);
+
+  // Daily-fallback telemetry flush — non-blocking, best-effort, never throws.
+  maybeSpawnDailyFlush();
 }
 
-// Exit 0 always — informational hook must never block the Skill tool.
-main().catch((err) => {
-  process.stderr.write(`[skill-invocation-telemetry] ERROR: ${err?.message ?? err}\n`);
-}).finally(() => process.exit(0));
+// ---------------------------------------------------------------------------
+// Self-execution guard — run only when invoked directly (not when imported).
+// ---------------------------------------------------------------------------
+
+const isMain = process.argv[1] === fileURLToPath(import.meta.url);
+if (isMain) {
+  // Exit 0 immediately when disabled via SO_HOOK_PROFILE / SO_DISABLED_HOOKS.
+  if (!shouldRunHook('skill-invocation-telemetry')) process.exit(0);
+
+  // Exit 0 always — informational hook must never block the Skill tool.
+  main().catch((err) => {
+    process.stderr.write(`[skill-invocation-telemetry] ERROR: ${err?.message ?? err}\n`);
+  }).finally(() => process.exit(0));
+}

package/package.json

@@ -1,16 +1,22 @@
 {
   "name": "session-orchestrator",
-  "version": "3.16.0",
+  "version": "3.17.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",
   "keywords": [
     "pi-package",
     "claude-code",
+    "claude-code-plugin",
     "codex",
     "cursor",
     "ai-agents",
-    "orchestration"
+    "agentic-coding",
+    "subagents",
+    "orchestration",
+    "developer-tools",
+    "mcp",
+    "llm"
   ],
   "engines": {
     "node": ">=24.0.0"
@@ -33,6 +39,7 @@
     ".codex-plugin/",
     ".cursor/",
     "docs/*.md",
+    "docs/telemetry/telemetry-claims.md",
     "NOTICE",
     "SECURITY.md",
     "!**/node_modules/**",
@@ -80,6 +87,9 @@
     "type": "git",
     "url": "git+https://github.com/Kanevry/session-orchestrator.git"
   },
+  "bugs": {
+    "url": "https://github.com/Kanevry/session-orchestrator/issues"
+  },
   "pi": {
     "extensions": [
       "./pi/extensions/session-orchestrator.ts"

package/scripts/compute-grounding-injection.sh

@@ -54,10 +54,25 @@ SESSION_ID="${SESSION_ID:-}"
 WAVE="${WAVE:-0}"
 AGENT_TYPE="${AGENT_TYPE:-}"
 
-# --- Build list of last 3 session_ids from sessions.jsonl ---
-
+# --- Build list of last 3 REAL session_ids from sessions.jsonl ---
+
+# Filter out phantom `status: 'abandoned'` stubs (#834, session-close-backfill
+# — 0 waves, seconds of runtime) BEFORE taking the tail. Otherwise a recent
+# phantom can evict the one real session carrying the stagnation evidence,
+# silently suppressing grounding injection for a genuinely stagnating file.
+#
+# `-R` (raw-input) + `fromjson?` parses each line individually and SKIPS
+# unparseable ones instead of aborting the whole stream — plain
+# `jq -c 'select(...)'` aborts at the FIRST malformed line (jq: parse error,
+# exit 5). sessions.jsonl is append-only from multiple writers, so a torn
+# write earlier in the file must not silently starve LAST_SESSIONS down to
+# "[]" (fail-closed-empty is still wrong here, just a quieter wrong than the
+# stale-session-id case this fixes) — the whole point is that corruption
+# anywhere in the file no longer poisons the tail. Mirrors the per-line
+# try/catch behaviour of the .mjs path (scripts/lib/session-schema/filters.mjs).
 # Extract session_id values (skip entries without one, skip empty lines)
-LAST_SESSIONS=$(tail -n 3 "$SESSIONS_JSONL" \
+LAST_SESSIONS=$(jq -R -c 'fromjson? | select(.status != "abandoned")' "$SESSIONS_JSONL" 2>/dev/null \
+  | tail -n 3 \
   | jq -r 'select(.session_id != null and .session_id != "") | .session_id' 2>/dev/null \
   | jq -R -s 'split("\n") | map(select(length > 0))' 2>/dev/null) || LAST_SESSIONS="[]"
 

package/scripts/dialectic-deriver.mjs

@@ -46,6 +46,7 @@ import { join } from 'node:path';
 import { randomBytes } from 'node:crypto';
 
 import { readPeerCards } from './lib/peer-cards/reader.mjs';
+import { filterRealSessions } from './lib/session-schema/filters.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -392,7 +393,11 @@ async function readTopLearnings(repoRoot, topN) {
 }
 
 /**
- * Read and rank sessions: sort by `completed_at` DESC, take last K.
+ * Read and rank sessions: filter out phantom `status: 'abandoned'` stubs
+ * (#834, session-close-backfill), sort by `completed_at` DESC, take last K.
+ *
+ * Without the filter, phantoms (0 waves, seconds of runtime) can displace
+ * REAL session context out of the K-window the derivation prompt sees.
  *
  * @param {string} repoRoot
  * @param {number} lastK
@@ -400,7 +405,7 @@ async function readTopLearnings(repoRoot, topN) {
  */
 async function readLastSessions(repoRoot, lastK) {
   const path = join(repoRoot, '.orchestrator', 'metrics', 'sessions.jsonl');
-  const entries = await readJsonlBestEffort(path);
+  const entries = filterRealSessions(await readJsonlBestEffort(path));
   entries.sort((a, b) => {
     const ta = typeof a?.completed_at === 'string' ? a.completed_at : '';
     const tb = typeof b?.completed_at === 'string' ? b.completed_at : '';

package/scripts/lib/auto-dialectic.mjs

@@ -22,6 +22,8 @@ import { existsSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import path from 'node:path';
 
+import { filterRealSessions } from './session-schema.mjs';
+
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -121,13 +123,20 @@ export async function readDialecticSignals({ repoRoot } = {}) {
     try {
       const raw = await readFile(sessionsPath, 'utf8');
       const lines = raw.split('\n').filter((l) => l.length > 0);
+      const entries = [];
       for (const line of lines) {
-        let entry;
         try {
-          entry = JSON.parse(line);
+          entries.push(JSON.parse(line));
         } catch {
           continue; // malformed line — skip silently
         }
+      }
+      // Abandoned-session filter (#834): mirrors auto-dream.mjs
+      // readDreamSignals() — phantom `status: 'abandoned'` stubs are
+      // legitimate DATA but not legitimate SIGNAL, and must not fire the
+      // /evolve --dialectic cadence off zero real work.
+      const realEntries = filterRealSessions(entries);
+      for (const entry of realEntries) {
         const startedAt = entry.started_at;
         if (typeof startedAt !== 'string' || startedAt.length === 0) continue;
         if (lastRunAt === null || startedAt > lastRunAt) {

package/scripts/lib/auto-dream.mjs

@@ -25,6 +25,8 @@ import { existsSync, statSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import path from 'node:path';
 
+import { filterRealSessions } from './session-schema.mjs';
+
 // ---------------------------------------------------------------------------
 // Signal reader — MEMORY.md size + sessions-since-last-cleanup
 // ---------------------------------------------------------------------------
@@ -74,8 +76,16 @@ export async function readDreamSignals({ repoRoot, memoryDir }) {
       }
     }
 
-    // Find the most recent memory_cleanup_at timestamp across all entries.
-    for (const entry of entries) {
+    // Abandoned-session filter (#834): sessions.jsonl carries phantom
+    // `status: 'abandoned'` stubs (session-close-backfill records for
+    // sessions that ended without a real close). They are legitimate DATA
+    // but not legitimate SIGNAL — a burst of abandoned stubs must not fire
+    // /memory-cleanup off zero real work. filterRealSessions() is the
+    // shared, tested implementation (scripts/lib/session-schema/filters.mjs).
+    const realEntries = filterRealSessions(entries);
+
+    // Find the most recent memory_cleanup_at timestamp across all REAL entries.
+    for (const entry of realEntries) {
       const ts = entry.memory_cleanup_at;
       if (typeof ts === 'string' && ts.length > 0) {
         if (lastCleanupAt === null || ts > lastCleanupAt) {
@@ -84,11 +94,12 @@ export async function readDreamSignals({ repoRoot, memoryDir }) {
       }
     }
 
-    // Count entries newer than the last cleanup (or total when no cleanup ever ran).
+    // Count REAL entries newer than the last cleanup (or total REAL entries
+    // when no cleanup ever ran).
     if (lastCleanupAt === null) {
-      sessionsSinceCleanup = entries.length;
+      sessionsSinceCleanup = realEntries.length;
     } else {
-      for (const entry of entries) {
+      for (const entry of realEntries) {
         const startedAt = entry.started_at;
         if (typeof startedAt === 'string' && startedAt > lastCleanupAt) {
           sessionsSinceCleanup += 1;

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

@@ -16,7 +16,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { parseStateMd, parseRecommendations } from './state-md.mjs';
-import { normalizeSession } from './session-schema.mjs';
+import { normalizeSession, tailRealSessions } from './session-schema.mjs';
 import { parseBootstrapLock } from './bootstrap-lock-freshness.mjs';
 import { scanBacklog } from './backlog-scan.mjs';
 
@@ -98,9 +98,12 @@ export async function buildLiveSignals(opts = {}) {
         .split('\n')
         .map((l) => l.trim())
         .filter((l) => l.length > 0);
-      const tail = lines.slice(-sessionTailN);
+      // #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 tail) {
+      for (const line of lines) {
         try {
           const obj = JSON.parse(line);
           parsed.push(normalizeSession(obj));
@@ -108,7 +111,7 @@ export async function buildLiveSignals(opts = {}) {
           // Branch 4: skip malformed lines silently
         }
       }
-      recentSessions = parsed;
+      recentSessions = tailRealSessions(parsed, sessionTailN);
     }
   } catch {
     // Branch 3: file unreadable — recentSessions stays []

package/scripts/lib/config/context-coverage.mjs

@@ -0,0 +1,82 @@
+import { matchBlockHeader } from './block-header.mjs';
+
+/**
+ * context-coverage.mjs — Parser for the top-level `context-coverage:` YAML block.
+ *
+ * Config block shape (see docs/session-config-template.md):
+ *   context-coverage:
+ *     enabled: false
+ *     mode: warn
+ *
+ * Modelled on `./docs-staleness.mjs`'s parser design (issue #781, Epic #774) —
+ * the block is scoped from the raw file content, independent of the
+ * `## Session Config` section boundary, so a baseline using either the plain
+ * `key:` header or the bold-bullet markdown rendering
+ * (`- **context-coverage:**`, tolerated via `matchBlockHeader()`) parses
+ * identically.
+ *
+ * ZERO imports other than `./block-header.mjs` — `tests/lib/config/cycle-guard.test.mjs`
+ * forbids importing `../config.mjs` from this directory; this module keeps a
+ * clean leaf with no other dependencies at all.
+ *
+ * Not registered in `scripts/lib/config.mjs` here — the coordinator wires
+ * `_parseContextCoverage` into the orchestrator's config-object assembly
+ * separately (see `context-coverage-banner.mjs`'s header for the exact
+ * import + call lines to add there).
+ *
+ * Shipped default: `{ enabled: false, mode: 'warn' }` — opt-in (issue #831).
+ */
+
+/**
+ * Parse the top-level `context-coverage:` YAML block from markdown content.
+ * Defaults: enabled=false, mode="warn". Malformed values fall back per key.
+ *
+ * @param {string} content — full file contents
+ * @returns {{enabled: boolean, mode: string}}
+ */
+export function _parseContextCoverage(content) {
+  const defaults = { enabled: false, mode: 'warn' };
+
+  const lines = content.split(/\r?\n/);
+  let inBlock = false;
+  const blockLines = [];
+
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/\r$/, '');
+    if (!inBlock) {
+      if (matchBlockHeader(line, 'context-coverage')) inBlock = true;
+      continue;
+    }
+    if (line.length > 0 && !/^\s/.test(line)) break;
+    blockLines.push(line);
+  }
+
+  if (blockLines.length === 0) return defaults;
+
+  let ccEnabled = false;
+  let ccMode = 'warn';
+
+  for (const rawLine of blockLines) {
+    const clean = rawLine.replace(/\s*#.*$/, '').replace(/\s+$/, '');
+    if (!clean.trim()) continue;
+
+    const kvMatch = clean.match(/^\s+([a-zA-Z_-]+):\s*(.*)/);
+    if (!kvMatch) continue;
+
+    const k = kvMatch[1];
+    let v = kvMatch[2].trim();
+    if (v.startsWith('"') && v.endsWith('"') && v.length >= 2) v = v.slice(1, -1);
+    else if (v.startsWith("'") && v.endsWith("'") && v.length >= 2) v = v.slice(1, -1);
+
+    switch (k) {
+      case 'enabled':
+        ccEnabled = v.toLowerCase() === 'true';
+        break;
+      case 'mode':
+        if (['strict', 'warn', 'off'].includes(v)) ccMode = v;
+        break;
+    }
+  }
+
+  return { enabled: ccEnabled, mode: ccMode };
+}