auxilo-mcp 0.9.4 → 0.9.7

package/lib/extraction-index.js

@@ -0,0 +1,462 @@
+'use strict';
+
+/**
+ * Client-side extraction memory for SPEC3-F2.
+ *
+ * The index is local, append-only, and advisory. Every read or write failure
+ * fails open: extraction/submission continues without prompt memory or lexical
+ * filtering. The only shared detector is lib/similarity.js.
+ */
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { findNearDuplicate, scoreChannels } = require('./similarity.js');
+
+const DEFAULT_INDEX_PATH = path.join(os.homedir(), '.auxilo', 'extracted-index.jsonl');
+const HYDRATION_PAGE_SIZE = 500;
+const PROMPT_MEMORY_MAX_TOKENS = 1200;
+const PROMPT_MEMORY_MAX_ROWS = 40;
+const VALID_STATUSES = new Set(['approved', 'rejected', 'pending_review']);
+
+const MEMORY_INSTRUCTIONS = `PREVIOUSLY CAPTURED LESSONS
+The following lessons were already submitted by this account.
+A candidate that re-states any listed lesson — reworded, or a different facet of the same operational insight — is DROPPED, not relabeled and not "improved."
+Extract new facts about a listed lesson ONLY when the new fact would change what another agent does: it must create a behavioral difference, not merely a wording difference.
+Never discard a memory match invisibly. Put the complete candidate plus the matched lesson id/title in dedup_drops so the local runner can write its audit trail.`;
+
+const CATEGORY_HINTS = Object.freeze({
+  'data-processing': ['data', 'parse', 'parser', 'json', 'csv', 'transform', 'pipeline'],
+  'web-interaction': ['api', 'http', 'browser', 'gmail', 'webhook', 'request', 'response'],
+  'code-execution': ['code', 'script', 'python', 'node', 'shell', 'command', 'runtime'],
+  'storage-state': ['state', 'queue', 'database', 'storage', 'file', 'commit', 'cache'],
+  'payment-financial': ['payment', 'stripe', 'usdc', 'wallet', 'settlement', 'withdraw'],
+  monitoring: ['monitor', 'alert', 'health', 'log', 'metric', 'observability', 'incident'],
+});
+
+function loud(log, message) {
+  try {
+    (log || console.error)(`[extraction-index] ${message}`);
+  } catch {
+    // A broken logger must not turn advisory dedup into a submission blocker.
+  }
+}
+
+function normalizeTags(tags) {
+  return Array.isArray(tags) ? tags.slice(0, 8).map(String) : [];
+}
+
+function validIndexRow(row) {
+  return Boolean(
+    row &&
+    typeof row === 'object' &&
+    typeof row.title === 'string' &&
+    row.title.trim() &&
+    typeof row.category === 'string'
+  );
+}
+
+/**
+ * Read an append-only JSONL index. A malformed line is skipped and logged, but
+ * marks the read unusable so extraction fails open instead of trusting a
+ * partially corrupt memory/filter corpus.
+ */
+function readExtractionIndex(opts = {}) {
+  const indexPath = opts.indexPath || DEFAULT_INDEX_PATH;
+  const fsImpl = opts.fsImpl || fs;
+  let exists;
+  try {
+    exists = fsImpl.existsSync(indexPath);
+  } catch (error) {
+    loud(opts.log, `index existence check failed; dedup disabled for this run: ${error.message}`);
+    return { state: 'unreadable', usable: false, rows: [], bad_lines: 0 };
+  }
+  if (!exists) return { state: 'missing', usable: false, rows: [], bad_lines: 0 };
+
+  let raw;
+  try {
+    raw = fsImpl.readFileSync(indexPath, 'utf8');
+  } catch (error) {
+    loud(opts.log, `index read failed; dedup disabled for this run: ${error.message}`);
+    return { state: 'unreadable', usable: false, rows: [], bad_lines: 0 };
+  }
+
+  const rows = [];
+  let badLines = 0;
+  const lines = String(raw).split(/\r?\n/);
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index].trim();
+    if (!line) continue;
+    try {
+      const row = JSON.parse(line);
+      if (!validIndexRow(row)) throw new Error('missing title/category');
+      rows.push(row);
+    } catch (error) {
+      badLines += 1;
+      loud(opts.log, `skipping corrupt line ${index + 1} in ${indexPath}: ${error.message}`);
+    }
+  }
+
+  if (badLines > 0) {
+    loud(opts.log, `index contains ${badLines} corrupt line(s); prompt memory and lexical dedup are disabled for this run`);
+    return { state: 'corrupt', usable: false, rows, bad_lines: badLines };
+  }
+  return { state: 'ready', usable: true, rows, bad_lines: 0 };
+}
+
+function appendJsonlRows(rows, opts = {}) {
+  const indexPath = opts.indexPath || DEFAULT_INDEX_PATH;
+  const fsImpl = opts.fsImpl || fs;
+  try {
+    fsImpl.mkdirSync(path.dirname(indexPath), { recursive: true, mode: 0o700 });
+    if (!rows.length) {
+      const fd = fsImpl.openSync(indexPath, 'a', 0o600);
+      fsImpl.closeSync(fd);
+      return true;
+    }
+    const payload = rows.map((row) => JSON.stringify(row)).join('\n') + '\n';
+    fsImpl.appendFileSync(indexPath, payload, { encoding: 'utf8', mode: 0o600 });
+    return true;
+  } catch (error) {
+    loud(opts.log, `index append failed; extraction/submission continues: ${error.message}`);
+    return false;
+  }
+}
+
+function localIndexRow(learning, response = {}, opts = {}) {
+  const nowValue = typeof opts.now === 'function'
+    ? opts.now()
+    : (opts.now || new Date().toISOString());
+  const body = String(learning.body || '');
+  return {
+    title: String(learning.title || ''),
+    category: String(learning.category || ''),
+    tags: normalizeTags(learning.tags),
+    body_hash: crypto.createHash('sha256').update(body).digest('hex'),
+    body,
+    submitted_at: String(nowValue),
+    ...(typeof response.id === 'string' && response.id && { learning_id: response.id }),
+    ...(typeof response.status === 'string' && VALID_STATUSES.has(response.status) && {
+      status: response.status,
+    }),
+  };
+}
+
+/**
+ * Append only after POST /learn returns 2xx. A network/4xx failure remains
+ * retryable and is not allowed to poison the local dedup memory.
+ */
+function appendSubmittedLearning(learning, response = {}, opts = {}) {
+  if (!learning || typeof learning !== 'object') return false;
+  return appendJsonlRows([localIndexRow(learning, response, opts)], opts);
+}
+
+function hydratedIndexRow(learning) {
+  return {
+    title: String(learning.title || ''),
+    category: String(learning.category || ''),
+    tags: normalizeTags(learning.tags),
+    body_hash: null,
+    submitted_at: learning.created_at || null,
+    ...(typeof learning.id === 'string' && learning.id && { learning_id: learning.id }),
+    ...(typeof learning.status === 'string' && VALID_STATUSES.has(learning.status) && {
+      status: learning.status,
+    }),
+  };
+}
+
+/**
+ * Hydrate only a missing index from the caller's own metadata endpoint. The
+ * endpoint intentionally carries no body, so hydrated rows inform the prompt
+ * only; lexical filtering is limited to locally appended rows with a body.
+ */
+async function hydrateExtractionIndex(opts = {}) {
+  const indexPath = opts.indexPath || DEFAULT_INDEX_PATH;
+  const fsImpl = opts.fsImpl || fs;
+  try {
+    if (fsImpl.existsSync(indexPath)) return { hydrated: false, reason: 'not_fresh' };
+  } catch (error) {
+    loud(opts.log, `fresh-index check failed; hydration skipped: ${error.message}`);
+    return { hydrated: false, reason: 'unreadable' };
+  }
+
+  const fetchImpl = opts.fetchImpl || globalThis.fetch;
+  const baseUrl = String(opts.baseUrl || '').replace(/\/+$/, '');
+  const apiKey = opts.apiKey;
+  if (typeof fetchImpl !== 'function' || !baseUrl || !apiKey) {
+    loud(opts.log, 'fresh-machine hydration unavailable (missing fetch, base URL, or API key); extracting without memory');
+    return { hydrated: false, reason: 'unavailable' };
+  }
+
+  const hydratedRows = [];
+  let offset = 0;
+  try {
+    for (let page = 0; page < 10000; page += 1) {
+      const response = await fetchImpl(
+        `${baseUrl}/account/learnings?limit=${HYDRATION_PAGE_SIZE}&offset=${offset}`,
+        { headers: { 'X-API-Key': apiKey } }
+      );
+      if (!response || !response.ok) {
+        const status = response && Number.isFinite(response.status) ? response.status : 'unknown';
+        throw new Error(`GET /account/learnings returned ${status}`);
+      }
+      const payload = await response.json();
+      if (!payload || !Array.isArray(payload.learnings)) {
+        throw new Error('GET /account/learnings returned an invalid payload');
+      }
+      for (const row of payload.learnings) {
+        const hydrated = hydratedIndexRow(row);
+        if (!validIndexRow(hydrated)) {
+          loud(opts.log, 'skipping malformed hydration row from GET /account/learnings');
+          continue;
+        }
+        hydratedRows.push(hydrated);
+      }
+      offset += payload.learnings.length;
+      const total = Number.isFinite(payload.total) ? payload.total : null;
+      if (payload.learnings.length < HYDRATION_PAGE_SIZE ||
+          (total !== null && offset >= total)) break;
+      if (payload.learnings.length === 0) break;
+    }
+  } catch (error) {
+    loud(opts.log, `fresh-machine hydration failed; extracting without memory: ${error.message}`);
+    return { hydrated: false, reason: 'request_failed' };
+  }
+
+  if (!appendJsonlRows(hydratedRows, { indexPath, fsImpl, log: opts.log })) {
+    return { hydrated: false, reason: 'write_failed' };
+  }
+  loud(opts.log, `hydrated ${hydratedRows.length} own learning metadata row(s) into ${indexPath}`);
+  return { hydrated: true, count: hydratedRows.length };
+}
+
+async function loadIndexForExtraction(opts = {}) {
+  const first = readExtractionIndex(opts);
+  if (first.state !== 'missing') return first;
+  const hydration = await hydrateExtractionIndex(opts);
+  if (!hydration.hydrated) return first;
+  return readExtractionIndex(opts);
+}
+
+function estimatePromptTokens(text) {
+  return Math.ceil(Buffer.byteLength(String(text || ''), 'utf8') / 4);
+}
+
+function inferCategoryHints(transcript) {
+  const text = String(transcript || '').toLowerCase();
+  const scores = [];
+  for (const [category, words] of Object.entries(CATEGORY_HINTS)) {
+    let score = 0;
+    for (const word of words) {
+      const matches = text.match(new RegExp(`\\b${word.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'g'));
+      score += matches ? matches.length : 0;
+    }
+    if (score > 0) scores.push({ category, score });
+  }
+  scores.sort((a, b) => b.score - a.score || a.category.localeCompare(b.category));
+  if (!scores.length) return [];
+  const top = scores[0].score;
+  return scores.filter((entry) => entry.score === top).map((entry) => entry.category);
+}
+
+function submittedTime(row) {
+  const parsed = Date.parse(row.submitted_at || row.created_at || '');
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+function oneLineGist(row) {
+  if (typeof row.body === 'string' && row.body.trim()) {
+    const compact = row.body.replace(/\s+/g, ' ').trim();
+    const sentence = compact.match(/^(.{1,220}?[.!?])(?:\s|$)/);
+    return (sentence ? sentence[1] : compact.slice(0, 220)).trim();
+  }
+  const tags = normalizeTags(row.tags).filter(Boolean);
+  if (tags.length) return `Previously captured ${row.category} lesson tagged ${tags.join(', ')}.`;
+  return `Previously captured ${row.category} lesson.`;
+}
+
+function indexRowId(row, index = 0) {
+  return String(
+    row.learning_id ||
+    row.id ||
+    row.body_hash ||
+    `local-index-${index}`
+  );
+}
+
+function promptMemoryLine(row, index) {
+  const title = String(row.title || '').replace(/\s+/g, ' ').trim().slice(0, 180);
+  const gist = oneLineGist(row).slice(0, 240);
+  return `- [id:${indexRowId(row, index)} category:${row.category}] ${title} — ${gist}`;
+}
+
+/**
+ * Budget strategy: inferred same-category rows first, then most recent rows,
+ * with deterministic title/ID tie-breaking. The instruction header and rows
+ * together may never exceed maxTokens.
+ */
+function buildPromptMemory(rows, opts = {}) {
+  const maxTokens = Number.isFinite(opts.maxTokens)
+    ? Math.max(0, Math.floor(opts.maxTokens))
+    : PROMPT_MEMORY_MAX_TOKENS;
+  const maxRows = Number.isFinite(opts.maxRows)
+    ? Math.max(0, Math.floor(opts.maxRows))
+    : PROMPT_MEMORY_MAX_ROWS;
+  const hints = new Set(opts.categoryHints || inferCategoryHints(opts.transcript));
+  const eligible = (Array.isArray(rows) ? rows : [])
+    .filter(validIndexRow)
+    .slice()
+    .sort((a, b) => {
+      const aMatch = hints.has(a.category) ? 1 : 0;
+      const bMatch = hints.has(b.category) ? 1 : 0;
+      return bMatch - aMatch ||
+        submittedTime(b) - submittedTime(a) ||
+        String(a.title).localeCompare(String(b.title)) ||
+        String(a.learning_id || '').localeCompare(String(b.learning_id || ''));
+    });
+
+  if (!eligible.length || maxRows === 0 || estimatePromptTokens(MEMORY_INSTRUCTIONS) > maxTokens) {
+    return {
+      section: '',
+      estimated_tokens: 0,
+      included_count: 0,
+      included_rows: [],
+      category_hints: [...hints],
+    };
+  }
+
+  const lines = [];
+  const includedRows = [];
+  for (let index = 0; index < eligible.length; index += 1) {
+    const row = eligible[index];
+    if (lines.length >= maxRows) break;
+    const candidateLines = [...lines, promptMemoryLine(row, index)];
+    const candidate = `${MEMORY_INSTRUCTIONS}\n${candidateLines.join('\n')}\n\n`;
+    if (estimatePromptTokens(candidate) > maxTokens) break;
+    lines.push(candidateLines[candidateLines.length - 1]);
+    includedRows.push({
+      id: indexRowId(row, index),
+      title: row.title,
+      category: row.category,
+    });
+  }
+  if (!lines.length) {
+    return {
+      section: '',
+      estimated_tokens: 0,
+      included_count: 0,
+      included_rows: [],
+      category_hints: [...hints],
+    };
+  }
+  const section = `${MEMORY_INSTRUCTIONS}\n${lines.join('\n')}\n\n`;
+  return {
+    section,
+    estimated_tokens: estimatePromptTokens(section),
+    included_count: lines.length,
+    included_rows: includedRows,
+    category_hints: [...hints],
+  };
+}
+
+/**
+ * Rank index rows against one extracted candidate with the shared F1 scoring
+ * implementation. No flag threshold is applied: the score is used only for a
+ * deterministic candidate-anchored top-K list for the local judge.
+ */
+function rankIndexRowsForCandidate(candidate, rows, opts = {}) {
+  const topK = Number.isFinite(opts.topK)
+    ? Math.max(0, Math.floor(opts.topK))
+    : 10;
+  if (!candidate || topK === 0) return [];
+  return (Array.isArray(rows) ? rows : [])
+    .filter(validIndexRow)
+    .map((row, index) => {
+      const ranked = {
+        id: indexRowId(row, index),
+        title: row.title,
+        category: row.category,
+        body: typeof row.body === 'string' ? row.body : '',
+      };
+      const channels = scoreChannels(candidate, ranked);
+      return {
+        id: ranked.id,
+        title: ranked.title,
+        category: ranked.category,
+        similarity: channels.composite,
+        channels,
+      };
+    })
+    .sort((a, b) =>
+      b.similarity - a.similarity ||
+      a.id.localeCompare(b.id) ||
+      String(a.title).localeCompare(String(b.title))
+    )
+    .slice(0, topK);
+}
+
+/**
+ * Filter candidates against locally appended rows only. Hydrated metadata has
+ * no body and therefore never participates in lexical detection.
+ */
+function filterIndexedNearDuplicates(candidates, indexState, opts = {}) {
+  const input = Array.isArray(candidates) ? candidates : [];
+  if (!indexState || !indexState.usable) {
+    return { kept: input.slice(), dropped: [], disabled: true };
+  }
+  const localRows = indexState.rows
+    .filter((row) => typeof row.body === 'string' && row.body.trim())
+    .map((row, index) => ({
+      id: row.learning_id || `local-index-${index}`,
+      title: row.title,
+      body: row.body,
+      category: row.category,
+      status: row.status || null,
+    }));
+  if (!localRows.length) return { kept: input.slice(), dropped: [], disabled: false };
+
+  try {
+    const kept = [];
+    const dropped = [];
+    for (const candidate of input) {
+      const result = findNearDuplicate(candidate, localRows);
+      if (result.verdict === 'flag') {
+        const matchedRow = localRows.find((row) => row.id === result.match.id);
+        dropped.push({
+          candidate,
+          match: {
+            ...result.match,
+            title: matchedRow ? matchedRow.title : null,
+          },
+        });
+      } else {
+        kept.push(candidate);
+      }
+    }
+    return { kept, dropped, disabled: false };
+  } catch (error) {
+    loud(opts.log, `lexical dedup failed; keeping all extracted candidates: ${error.message}`);
+    return { kept: input.slice(), dropped: [], disabled: true };
+  }
+}
+
+module.exports = {
+  DEFAULT_INDEX_PATH,
+  HYDRATION_PAGE_SIZE,
+  PROMPT_MEMORY_MAX_TOKENS,
+  PROMPT_MEMORY_MAX_ROWS,
+  MEMORY_INSTRUCTIONS,
+  readExtractionIndex,
+  appendSubmittedLearning,
+  hydrateExtractionIndex,
+  loadIndexForExtraction,
+  buildPromptMemory,
+  estimatePromptTokens,
+  inferCategoryHints,
+  filterIndexedNearDuplicates,
+  rankIndexRowsForCandidate,
+  indexRowId,
+  localIndexRow,
+  hydratedIndexRow,
+};

package/lib/hook-status.js

@@ -0,0 +1,24 @@
+'use strict';
+
+/**
+ * True when a Claude Code SessionEnd collection contains an Auxilo extraction
+ * hook. Accepts both the legacy bare-command string and the current matcher
+ * group shape ({ hooks: [{ type: 'command', command }] }).
+ *
+ * @param {unknown} sessionEnd
+ * @returns {boolean}
+ */
+function hasAuxiloSessionEndHook(sessionEnd) {
+  if (!Array.isArray(sessionEnd)) return false;
+
+  return sessionEnd.some((entry) => {
+    if (typeof entry === 'string') return entry.includes('auxilo-extract');
+    if (!entry || typeof entry !== 'object' || !Array.isArray(entry.hooks)) return false;
+    return entry.hooks.some((hook) =>
+      hook && typeof hook === 'object' &&
+      typeof hook.command === 'string' &&
+      hook.command.includes('auxilo-extract'));
+  });
+}
+
+module.exports = { hasAuxiloSessionEndHook };

package/lib/installer.js

@@ -24,6 +24,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { hasAuxiloSessionEndHook } = require('./hook-status.js');
 
 // ─── Constants ──────────────────────────────────────────────────────────────
 
@@ -73,6 +74,10 @@ const RUNNER_STACK = Object.freeze([
   ['scripts/review-notice.js', 'scripts/review-notice.js', 0o755],
   ...sourceAdapterRows(),
   ['lib/sensitivity-filter.js', 'lib/sensitivity-filter.js', 0o644],
+  ['lib/extraction-index.js', 'lib/extraction-index.js', 0o644],
+  ['lib/similarity.js', 'lib/similarity.js', 0o644],
+  ['lib/hook-status.js', 'lib/hook-status.js', 0o644],
+  ['config/near-duplicate.json', 'config/near-duplicate.json', 0o644],
 ]);
 
 // ─── Client registry + detection (spec §LW-12 step 1; UC-0 expansion) ───────
@@ -1556,16 +1561,21 @@ async function getStatus(homeDir, opts = {}) {
   // 4. Sentinel + runner + hook install state
   const hookPath = hookScriptPathFor(homeDir);
   const runnerInstalled = fs.existsSync(path.join(binRootFor(homeDir), 'scripts', 'runner.js'));
+  let hookInstalled = false;
   let hookRegistered = false;
   try {
     const settings = JSON.parse(
       fs.readFileSync(path.join(homeDir, '.claude', 'settings.json'), 'utf-8')
     );
+    const sessionEnd = settings.hooks && settings.hooks.SessionEnd;
+    // SPEC3-A3: installation detection accepts both the legacy string and the
+    // current object shape through the same helper runner --status uses.
+    hookInstalled = hasAuxiloSessionEndHook(sessionEnd);
     // LW-17: only STRUCTURED entries count — Claude Code silently ignores
     // bare-string entries (the 0.8.1 dead-hook bug), so reporting one as
     // "registered" would mask exactly the failure this status exists to catch.
-    hookRegistered = Array.isArray(settings.hooks && settings.hooks.SessionEnd) &&
-      settings.hooks.SessionEnd.some((h) =>
+    hookRegistered = Array.isArray(sessionEnd) &&
+      sessionEnd.some((h) =>
         h && typeof h === 'object' && Array.isArray(h.hooks) && h.hooks.some(isAuxiloCommandHook));
   } catch { /* no settings */ }
 
@@ -1589,7 +1599,8 @@ async function getStatus(homeDir, opts = {}) {
     accountMode,
     sentinel: sentinelPresent(homeDir),
     runnerInstalled,
-    hookInstalled: fs.existsSync(hookPath),
+    hookInstalled,
+    hookScriptInstalled: fs.existsSync(hookPath),
     hookRegistered,
     // LW-18 layer 1b: SessionStart held-count notice
     noticeRegistered: sessionStartNoticeRegistered(homeDir),

package/lib/review.js

@@ -121,7 +121,7 @@ function formatFlags(l) {
 
 // ── Review-seamless additions (2026-07-18) ──────────────────────────────────
 //
-// Summary + bulk network calls, plus the pure approve-clean selection logic
+// Summary + bulk network calls, plus the pure approve-ready selection logic
 // shared by the CLI, the MCP auxilo_review tool, and the triage report script.
 // One selection implementation everywhere, so what a dry run PRINTS is exactly
 // what a confirmed run DOES.
@@ -129,8 +129,12 @@ function formatFlags(l) {
 /** Server-enforced max decisions per bulk call; clients chunk at this size. */
 const BULK_CHUNK = 100;
 
-/** Default approve-clean quality threshold (repo quality gate: total >= 14/20). */
+/** Default ready-to-publish quality threshold (repo quality gate: total >= 14/20). */
 const DEFAULT_QUALITY_THRESHOLD = 14;
+const LANE_READY = 'ready_to_publish';
+const LANE_NEEDS_SCORE = 'needs_score';
+const LANE_NEEDS_EYES = 'needs_your_eyes';
+const REVIEW_LANES = new Set([LANE_READY, LANE_NEEDS_SCORE, LANE_NEEDS_EYES]);
 
 /**
  * GET /account/pending/summary: compact triage rows + counts (no bodies).
@@ -233,46 +237,95 @@ function qualityClears(row, minQuality) {
 }
 
 /**
- * THE approve-clean selection. Operates on summary rows (screens_passed,
- * flags, quality) from GET /account/pending/summary.
+ * Resolve the server lane on a summary row. Old servers did not return lane;
+ * those rows fall back to the legacy screens+quality split and are marked as
+ * version-skewed so the caller can tell the operator.
  *
- * mode 'clean' (approve-clean): screens_passed AND quality >= minQuality.
- * mode 'all': every row EXCEPT screens-flagged ones unless includeFlagged
- * is set; no quality gate.
+ * @param {object} row
+ * @returns {{lane:string, version_skew:boolean}}
+ */
+function reviewLane(row) {
+  if (row && REVIEW_LANES.has(row.lane)) {
+    return { lane: row.lane, version_skew: false };
+  }
+  if (!row || !row.screens_passed) {
+    return { lane: LANE_NEEDS_EYES, version_skew: true };
+  }
+  return {
+    lane: qualityClears(row, DEFAULT_QUALITY_THRESHOLD) ? LANE_READY : LANE_NEEDS_SCORE,
+    version_skew: true,
+  };
+}
+
+/**
+ * THE approve-ready selection. The server's lane is authoritative:
+ *
+ * - threshold 14 (default): exactly rows in ready_to_publish
+ * - threshold >14: narrows within ready_to_publish
+ * - threshold <14: includes qualifying needs_score rows too
+ * - needs_your_eyes is excluded unless mode=all + includeFlagged
  *
  * Returns the selection plus what was excluded and why, so every confirmation
  * surface can show the operator the exact consequences before anything runs.
  *
  * @param {Array<object>} rows
- * @param {object} [opts]  { mode: 'clean'|'all', minQuality, includeFlagged }
- * @returns {{selected:Array<object>, excluded_flagged:Array<object>, excluded_low_quality:Array<object>, excluded_unscored:Array<object>, min_quality:number|null}}
+ * @param {object} [opts]  { mode: 'ready'|'clean'|'all', minQuality, includeFlagged }
+ * @returns {{selected:Array<object>, included_beyond_verdict:Array<object>, excluded_flagged:Array<object>, excluded_low_quality:Array<object>, excluded_unscored:Array<object>, min_quality:number|null, version_skew:boolean}}
  */
 function selectForBulkApprove(rows, opts = {}) {
-  const mode = opts.mode === 'all' ? 'all' : 'clean';
-  const minQuality = mode === 'clean'
+  const mode = opts.mode === 'all' ? 'all' : 'ready';
+  const minQuality = mode === 'ready'
     ? (Number.isFinite(opts.minQuality) ? opts.minQuality : DEFAULT_QUALITY_THRESHOLD)
     : null;
   const includeFlagged = mode === 'all' && opts.includeFlagged === true;
 
   const selected = [];
+  const included_beyond_verdict = [];
   const excluded_flagged = [];
   const excluded_low_quality = [];
   const excluded_unscored = [];
+  let version_skew = false;
 
   for (const row of rows || []) {
     if (!row || !row.id) continue;
-    if (!row.screens_passed && !includeFlagged) {
+    const resolved = reviewLane(row);
+    version_skew = version_skew || resolved.version_skew;
+
+    if (resolved.lane === LANE_NEEDS_EYES && !includeFlagged) {
       excluded_flagged.push(row);
       continue;
     }
-    if (mode === 'clean' && !qualityClears(row, minQuality)) {
-      (row.quality == null ? excluded_unscored : excluded_low_quality).push(row);
-      continue;
+
+    if (mode === 'ready') {
+      if (resolved.lane === LANE_READY) {
+        // At the server floor, consume the verdict verbatim. A stricter
+        // operator threshold may narrow it, but never broaden it.
+        if (minQuality > DEFAULT_QUALITY_THRESHOLD && !qualityClears(row, minQuality)) {
+          (row.quality == null ? excluded_unscored : excluded_low_quality).push(row);
+          continue;
+        }
+      } else if (resolved.lane === LANE_NEEDS_SCORE) {
+        if (minQuality < DEFAULT_QUALITY_THRESHOLD && qualityClears(row, minQuality)) {
+          included_beyond_verdict.push(row);
+        } else {
+          (row.quality == null ? excluded_unscored : excluded_low_quality).push(row);
+          continue;
+        }
+      }
     }
+
     selected.push(row);
   }
 
-  return { selected, excluded_flagged, excluded_low_quality, excluded_unscored, min_quality: minQuality };
+  return {
+    selected,
+    included_beyond_verdict,
+    excluded_flagged,
+    excluded_low_quality,
+    excluded_unscored,
+    min_quality: minQuality,
+    version_skew,
+  };
 }
 
 module.exports = {
@@ -287,5 +340,6 @@ module.exports = {
   chunkDecisions,
   submitBulkChunked,
   qualityClears,
+  reviewLane,
   selectForBulkApprove,
 };