auxilo-mcp 0.9.6 → 0.9.8

package/README.md

@@ -33,7 +33,7 @@ Enable extraction and a session-end hook runs when your agent finishes a session
 1. The hook hands the runner the path to the session transcript.
 2. The runner reads the transcript on your machine and scrubs it with a fail-closed secret filter: 24 patterns covering API keys, tokens, private keys, JWTs, connection strings, cookies, email addresses, phone numbers, and internal IPs. If a rescan still finds a match, the run stops and nothing is sent.
 3. Your own model client (your claude CLI, on your subscription) drafts learnings from the scrubbed text and screens them again.
-4. Clean drafts publish to the marketplace with a 7-day retraction window. Anything a screen flags waits in your private pending queue instead.
+4. Drafts held for review appear in three server-defined lanes: **Ready to publish**, **Needs a score**, and **Needs your eyes**. The last lane includes the server's reason so you can inspect the exception directly.
 
 ### What never leaves your machine
 
@@ -41,15 +41,20 @@ Your raw transcripts. They are read and scrubbed on your machine, and they are n
 
 ### How publishing works
 
-Extraction defaults to seamless: a draft that passes every screen (secrets, sensitivity, injection, near-duplicate, quality) publishes right away, and you can retract it for 7 days. A draft that any screen flags waits in a pending queue only you can see.
+Extraction defaults to seamless: a draft that passes every screen (secrets, sensitivity, injection, near-duplicate, quality) publishes right away, and you can retract it for 7 days. A draft held for review waits in a pending queue only you can see, grouped by the server's Ready to publish / Needs a score / Needs your eyes verdict.
 
 ```bash
-npx auxilo review     # approve, reject, or skip each queued draft
-npx auxilo status     # clients, hooks, queue depth, consent state
-npx auxilo disable    # kill switch: extraction stops immediately
+npx auxilo review --list           # show all three lanes and each exception reason
+npx auxilo review --approve-ready  # approve public-destined ready_to_publish rows
+npx auxilo review --keep-private   # keep Needs your eyes owner-only at $0 recall
+npx auxilo review                  # approve, reject, keep private, view, or skip
+npx auxilo status                  # clients, hooks, queue depth, consent state
+npx auxilo disable                 # kill switch: extraction stops immediately
 ```
 
-Approve a queued draft and it goes live in the marketplace. Reject it and it stays private. Prefer approve-first for everything? Switch your account to manual mode in account settings and every draft waits for you.
+Every bulk decision prints the exact selection and requires you to type its count. `--min-quality 16` narrows the ready lane; values below 14 explicitly reach into Needs a score and print a warning before the same counted confirmation. Private-destined rows are excluded from approval: keep one private for owner-only $0 recall, or sanitize and promote a corrected replacement through public review. A private-destined row can never go public through Approve.
+
+Private extraction is opt-in: set `AUXILO_CAPTURE_VISIBILITY=private`, or set `"capture_visibility": "private"` in `~/.auxilo/credentials.json`. It can retain reusable non-technical candidates in your owner-only lane while preserving the same mandatory local sensitivity scrub and dedup pipeline. With the setting absent, extraction remains public-destined and technical-only.
 
 Extraction off? Your agent can still contribute in-session: tell it to submit a learning with the `auxilo_contribute` tool.
 

package/bin/auxilo-cli.js

@@ -32,19 +32,45 @@ const HOME = os.homedir();
 // question N+1 arrives with question N's buffer and the next prompt hangs
 // on EOF (the 0.8.1 consent step silently never completed).
 let sharedRl = null;
+let bufferedLines = [];
+let lineWaiters = [];
+let readlineEnded = false;
 function getRl() {
   if (!sharedRl) {
-    sharedRl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    readlineEnded = false;
+    sharedRl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      terminal: !!process.stdin.isTTY,
+    });
+    sharedRl.on('line', (line) => {
+      const answer = line.trim();
+      const waiter = lineWaiters.shift();
+      if (waiter) waiter(answer);
+      else bufferedLines.push(answer);
+    });
+    sharedRl.on('close', () => {
+      readlineEnded = true;
+      while (lineWaiters.length) lineWaiters.shift()('');
+    });
   }
   return sharedRl;
 }
 function closeRl() {
-  if (sharedRl) { sharedRl.close(); sharedRl = null; }
+  if (sharedRl) sharedRl.close();
+  sharedRl = null;
+  bufferedLines = [];
+  lineWaiters = [];
+  readlineEnded = false;
 }
 
 function ask(question) {
+  getRl();
+  process.stdout.write(question);
+  if (bufferedLines.length > 0) return Promise.resolve(bufferedLines.shift());
+  if (readlineEnded) return Promise.resolve('');
   return new Promise((resolve) => {
-    getRl().question(question, (answer) => resolve(answer.trim()));
+    lineWaiters.push(resolve);
   });
 }
 
@@ -509,7 +535,7 @@ async function cmdDisable(flags) {
 // Operates ONLY on the caller's own pending learnings (account-scoped API key).
 //
 // Review-seamless (2026-07-18): the default view is now a triage summary table
-// (quality desc, clean before flagged), with bulk modes that batch through
+// (quality-desc rows grouped into the server's three lanes), with bulk modes that batch through
 // POST /account/pending/bulk. HARD RULE for every bulk APPROVE path: print the
 // exact list and count first, then require the operator to TYPE THE COUNT.
 // There is no --yes bypass on any approve path; publishing always costs one
@@ -522,11 +548,20 @@ function fit(s, width) {
   return str.padEnd(width);
 }
 
-/** Short flag codes for a summary row: 'clean' or e.g. 'inj+sens'. */
+/** Short lane/flag codes for a summary row, e.g. 'ready' or 'inj+sens'. */
 function shortFlags(row) {
-  if (row.screens_passed) return 'clean';
-  const map = { injection: 'inj', content_sensitivity: 'sens', near_duplicate: 'dup' };
-  return (row.flags || []).map((f) => map[f] || f).join('+') || 'flagged';
+  const resolved = review.reviewLane(row);
+  const visibility = row.visibility === 'private' ? ['priv'] : [];
+  if (resolved.lane === 'ready_to_publish') return visibility.concat('ready').join('+');
+  if (resolved.lane === 'needs_score') return visibility.concat('score').join('+');
+  const map = {
+    injection: 'inj',
+    content_sensitivity: 'sens',
+    near_duplicate: 'dup',
+    process_advice: 'advice',
+    account_vocab: 'vocab',
+  };
+  return visibility.concat((row.flags || []).map((f) => map[f] || f)).join('+') || 'flagged';
 }
 
 /** One compact triage line (shared by the table and rapid mode). */
@@ -535,13 +570,41 @@ function triageLine(row, n, total) {
   return `  ${String(n).padStart(String(total).length)}. q=${q}  ${fit(shortFlags(row), 9)} ${fit(row.category || '', 20)} ${fit(row.title || '(no title)', 52)}`;
 }
 
-/** Print the triage summary: counts, then clean rows, then flagged rows. */
+function groupSummaryRows(summary) {
+  const groups = {
+    ready_to_publish: [],
+    needs_score: [],
+    needs_your_eyes: [],
+  };
+  let versionSkew = false;
+  for (const row of summary.items || []) {
+    const resolved = review.reviewLane(row);
+    versionSkew = versionSkew || resolved.version_skew;
+    groups[resolved.lane].push(row);
+  }
+  const serverCounts = summary.counts && summary.counts.by_lane;
+  const counts = !versionSkew && serverCounts
+    ? {
+        ready_to_publish: serverCounts.ready_to_publish || 0,
+        needs_score: serverCounts.needs_score || 0,
+        needs_your_eyes: serverCounts.needs_your_eyes || 0,
+      }
+    : {
+        ready_to_publish: groups.ready_to_publish.length,
+        needs_score: groups.needs_score.length,
+        needs_your_eyes: groups.needs_your_eyes.length,
+      };
+  return { groups, counts, versionSkew };
+}
+
+/** Print the triage summary in the server's three-lane order. */
 function printSummaryTable(summary) {
-  const items = summary.items || [];
-  const clean = items.filter((r) => r.screens_passed);
-  const flagged = items.filter((r) => !r.screens_passed);
+  const { groups, counts, versionSkew } = groupSummaryRows(summary);
 
-  console.log(`\n${summary.pending_count} learning(s) pending your review: ${clean.length} passed every platform screen, ${flagged.length} flagged.`);
+  console.log(`\n${summary.pending_count} learning(s) pending your review: ${counts.ready_to_publish} ready to publish, ${counts.needs_score} need a score, ${counts.needs_your_eyes} need your eyes.`);
+  if (versionSkew) {
+    console.log('VERSION SKEW: this server did not return lane on every row; using the legacy screens-and-quality fallback.');
+  }
   const bands = summary.counts && summary.counts.by_quality_band;
   if (bands) {
     console.log(`Quality bands: 18-20: ${bands['18-20'] || 0} · 14-17: ${bands['14-17'] || 0} · 10-13: ${bands['10-13'] || 0} · below 10: ${bands.below_10 || 0} · unscored: ${bands.unscored || 0}`);
@@ -550,13 +613,20 @@ function printSummaryTable(summary) {
     console.log(`Near-duplicate clusters among your pending items: ${summary.near_dup_clusters.length} (review these together)`);
   }
 
-  if (clean.length > 0) {
-    console.log(`\nCLEAN (passed every screen) - sorted by quality:`);
-    clean.forEach((r, i) => console.log(triageLine(r, i + 1, clean.length)));
+  if (groups.ready_to_publish.length > 0) {
+    console.log(`\nREADY TO PUBLISH (${counts.ready_to_publish}) - sorted by quality:`);
+    groups.ready_to_publish.forEach((r, i) => console.log(triageLine(r, i + 1, groups.ready_to_publish.length)));
   }
-  if (flagged.length > 0) {
-    console.log(`\nFLAGGED (a platform screen raised a signal) - review individually:`);
-    flagged.forEach((r, i) => console.log(triageLine(r, i + 1, flagged.length)));
+  if (groups.needs_score.length > 0) {
+    console.log(`\nNEEDS A SCORE (${counts.needs_score}) - score or review individually:`);
+    groups.needs_score.forEach((r, i) => console.log(triageLine(r, i + 1, groups.needs_score.length)));
+  }
+  if (groups.needs_your_eyes.length > 0) {
+    console.log(`\nNEEDS YOUR EYES (${counts.needs_your_eyes}) - review individually:`);
+    groups.needs_your_eyes.forEach((r, i) => {
+      console.log(triageLine(r, i + 1, groups.needs_your_eyes.length));
+      if (r.why) console.log(`     why: ${r.why}`);
+    });
   }
   console.log('');
 }
@@ -591,7 +661,7 @@ async function runBulk({ apiKey, baseUrl, rows, decision, reason }) {
     baseUrl,
     decisions,
     onChunk: ({ chunkIndex, chunkCount, response }) => {
-      console.log(`  chunk ${chunkIndex + 1}/${chunkCount}: approved ${response.approved || 0}, rejected ${response.rejected || 0}, already done ${response.idempotent || 0}, failed ${response.failed || 0}`);
+      console.log(`  chunk ${chunkIndex + 1}/${chunkCount}: approved ${response.approved || 0}, kept private ${response.kept_private || 0}, rejected ${response.rejected || 0}, already done ${response.idempotent || 0}, failed ${response.failed || 0}`);
     },
   });
   for (const r of totals.results) {
@@ -640,32 +710,49 @@ async function cmdReview(flags) {
   // ── --list: summary only, no mutations ────────────────────────────────────
   if (flags.list) return;
 
-  // ── --approve-clean: bulk-approve items that passed EVERY platform screen
-  //    AND clear the quality threshold. Typed-count confirmation, no bypass. ──
-  if (flags['approve-clean']) {
+  // ── --approve-ready: consume the server's ready_to_publish verdict.
+  //    --approve-clean remains a hidden compatibility alias. A stricter
+  //    threshold narrows the ready lane; a lower one explicitly reaches into
+  //    needs_score. Typed-count confirmation, no bypass. ─────────────────────
+  if (flags['approve-ready'] || flags['approve-clean']) {
+    if (flags['approve-clean']) {
+      console.log('Note: --approve-clean was renamed to --approve-ready; the old flag remains a compatibility alias.');
+    }
     const minQuality = parseMinQuality(flags);
-    const sel = review.selectForBulkApprove(rows, { mode: 'clean', minQuality });
-    console.log(`approve-clean selection: ${sel.selected.length} of ${rows.length} pending (threshold: quality >= ${minQuality}).`);
-    if (sel.excluded_flagged.length) console.log(`  excluded ${sel.excluded_flagged.length} screen-flagged item(s) (review those individually).`);
+    const sel = review.selectForBulkApprove(rows, { mode: 'ready', minQuality });
+    console.log(`approve-ready selection: ${sel.selected.length} of ${rows.length} pending (threshold: quality >= ${minQuality}).`);
+    if (sel.excluded_private.length) {
+      console.log(`  excluded ${sel.excluded_private.length} private-destined item(s); use [p]/--keep-private to keep them owner-only, or sanitize-promote them for public review.`);
+    }
+    if (minQuality < review.DEFAULT_QUALITY_THRESHOLD) {
+      const approvableCount = Number.isFinite(summary.approvable_count)
+        ? summary.approvable_count
+        : review.selectForBulkApprove(rows, { mode: 'ready' }).selected.length;
+      console.log(`WARNING: selection goes beyond the server's approvable verdict (approvable_count=${approvableCount}); including ${sel.included_beyond_verdict.length} items from needs_score.`);
+    }
+    if (sel.excluded_flagged.length) console.log(`  excluded ${sel.excluded_flagged.length} needs_your_eyes item(s) (review those individually).`);
     if (sel.excluded_low_quality.length) console.log(`  excluded ${sel.excluded_low_quality.length} below the quality threshold.`);
     if (sel.excluded_unscored.length) console.log(`  excluded ${sel.excluded_unscored.length} with no quality score (pass --min-quality 0 to include).`);
     if (sel.selected.length === 0) { console.log('Nothing qualifies. No changes made.'); return; }
 
     if (!await confirmByTypedCount(sel.selected, 'APPROVE and PUBLISH')) return;
     const totals = await runBulk({ apiKey, baseUrl, rows: sel.selected, decision: 'approve' });
-    console.log(`\nDone. Approved ${totals.approved} (already approved earlier: ${totals.idempotent}, failed: ${totals.failed}). Flagged and below-threshold items stay pending.`);
+    console.log(`\nDone. Approved ${totals.approved} (already approved earlier: ${totals.idempotent}, failed: ${totals.failed}). Items outside the selection stay pending.`);
     return;
   }
 
-  // ── --all: bulk-approve everything EXCEPT screen-flagged items unless
+  // ── --all: bulk-approve everything EXCEPT needs_your_eyes items unless
   //    --include-flagged. Typed-count confirmation, no bypass. ───────────────
   if (flags.all) {
     const includeFlagged = flags['include-flagged'] === true;
     const sel = review.selectForBulkApprove(rows, { mode: 'all', includeFlagged });
-    if (includeFlagged && sel.selected.some((r) => !r.screens_passed)) {
-      console.log('WARNING: --include-flagged is set. This selection INCLUDES items a platform screen flagged (possible injection, sensitive content, or near-duplicates). Approving publishes them publicly.');
+    if (sel.excluded_private.length) {
+      console.log(`Excluded ${sel.excluded_private.length} private-destined item(s); use [p]/--keep-private to keep them owner-only, or sanitize-promote them for public review.`);
+    }
+    if (includeFlagged && sel.selected.some((r) => review.reviewLane(r).lane === 'needs_your_eyes')) {
+      console.log('WARNING: --include-flagged is set. This selection INCLUDES needs_your_eyes items (possible injection, sensitive content, process advice, account vocabulary, or near-duplicates). Approving publishes them publicly.');
     } else if (sel.excluded_flagged.length) {
-      console.log(`Excluding ${sel.excluded_flagged.length} screen-flagged item(s) (pass --include-flagged to include them; safer to review those individually).`);
+      console.log(`Excluding ${sel.excluded_flagged.length} needs_your_eyes item(s) (pass --include-flagged to include them; safer to review those individually).`);
     }
     if (sel.selected.length === 0) { console.log('Nothing qualifies. No changes made.'); return; }
 
@@ -675,6 +762,30 @@ async function cmdReview(flags) {
     return;
   }
 
+  // ── --keep-private: finalize one explicit server lane as owner-only.
+  //    Defaults to needs_your_eyes. Because this never publishes, --yes may
+  //    bypass its counted confirmation; all approve paths retain the rail. ───
+  if (flags['keep-private']) {
+    let sel;
+    try {
+      sel = review.selectForKeepPrivate(rows, { lane: flags.lane });
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+    console.log(`keep-private selection: ${sel.selected.length} of ${rows.length} pending (lane: ${sel.lane}).`);
+    for (const lane of ['ready_to_publish', 'needs_score', 'needs_your_eyes']) {
+      const excluded = sel.excluded_by_lane[lane];
+      if (excluded.length) console.log(`  excluded ${excluded.length} ${lane} item(s).`);
+    }
+    if (sel.selected.length === 0) { console.log('Nothing qualifies. No changes made.'); return; }
+    const ok = flags.yes || await confirmByTypedCount(sel.selected, 'KEEP PRIVATE (owner-only, $0 recall)');
+    if (!ok) return;
+    const totals = await runBulk({ apiKey, baseUrl, rows: sel.selected, decision: 'keep_private' });
+    console.log(`\nDone. Kept private ${totals.kept_private} of ${sel.selected.length} (already done earlier: ${totals.idempotent}, failed: ${totals.failed}).`);
+    return;
+  }
+
   // ── --all-reject: bulk reject the whole batch (incident escape hatch).
   //    Now batched through the bulk endpoint. --yes keeps its scripted-incident
   //    bypass because rejection is the SAFE direction (nothing goes public). ──
@@ -704,16 +815,17 @@ async function cmdReview(flags) {
     process.exit(1);
   }
 
-  console.log('Rapid review. Per item: [y] approve (goes live) · [n] reject (stays private) · [v] view full body · [s] skip · [q] quit\n');
+  console.log('Rapid review. Per item: [y] approve (goes public) · [n] reject · [p] keep private (owner-only, $0 recall) · [v] view · [s] skip · [q] quit\n');
 
-  let approved = 0, rejected = 0, skipped = 0;
-  const ordered = rows; // clean-first, quality desc (server order preserved by printSummaryTable groups)
+  let approved = 0, keptPrivate = 0, rejected = 0, skipped = 0;
+  const ordered = rows; // quality-desc server order; the summary above groups lanes
   for (let i = 0; i < ordered.length; i++) {
     const row = ordered[i];
     console.log(triageLine(row, i + 1, ordered.length));
     let choice = '';
     for (;;) {
-      choice = (await ask('    [y/n/v/s/q]? ')).toLowerCase().slice(0, 1);
+      choice = (await ask('    [y/n/p/v/s/q]? ')).toLowerCase().slice(0, 1);
+      if (!choice && readlineEnded) choice = 'q';
       if (choice === 'v') {
         const full = bodies.get(row.id);
         console.log('    ------------------------------------------------------------');
@@ -725,7 +837,7 @@ async function cmdReview(flags) {
         console.log('    ------------------------------------------------------------');
         continue;
       }
-      if (['y', 'n', 's', 'q'].includes(choice)) break;
+      if (['y', 'n', 'p', 's', 'q'].includes(choice)) break;
     }
     if (choice === 'q') { console.log('  Stopping. Remaining items left pending.'); break; }
     if (choice === 's') { skipped += 1; continue; }
@@ -733,6 +845,9 @@ async function cmdReview(flags) {
       if (choice === 'y') {
         await review.submitDecision({ apiKey, baseUrl, id: row.id, decision: 'approve' });
         approved += 1; console.log('    ✓ approved, now live');
+      } else if (choice === 'p') {
+        await review.submitDecision({ apiKey, baseUrl, id: row.id, decision: 'keep_private' });
+        keptPrivate += 1; console.log('    ✓ kept private (owner-only)');
       } else {
         await review.submitDecision({ apiKey, baseUrl, id: row.id, decision: 'reject' });
         rejected += 1; console.log('    ✗ rejected, stays private');
@@ -742,12 +857,57 @@ async function cmdReview(flags) {
     }
   }
 
-  console.log(`\nReview complete: approved ${approved}, rejected ${rejected}, skipped ${skipped} of ${ordered.length}.`);
+  console.log(`\nReview complete: approved ${approved}, kept private ${keptPrivate}, rejected ${rejected}, skipped ${skipped} of ${ordered.length}.`);
 }
 
 // ─── Entry point ────────────────────────────────────────────────────────────
 
-function usage() {
+function usage(command) {
+  const blocks = {
+    setup: `Usage: auxilo setup [--re-auth] [--base-url <url>]
+
+Interactively detect clients, register Auxilo, sign in, install the optional
+extraction runner and SessionEnd hook, and record the extraction choice.`,
+    init: `Usage: auxilo init [--scope <read|earnings-read|contribute>] [--label <name>]
+                   [--env-file <path>] [--save] [--json] [--no-browser]
+                   [--base-url <url>]
+
+Mint a scoped API key for CI or a second machine without running full setup.`,
+    status: `Usage: auxilo status
+
+Show detected clients, auth, extraction mode, kill switch, SessionEnd hook,
+last sweep, and pending queue depth.`,
+    review: `Usage: auxilo review [flags]
+
+Render YOUR pending-review learnings in three server-defined lanes:
+Ready to publish, Needs a score, and Needs your eyes.
+
+Flags:
+  --list            show the three-lane summary only; make no changes
+  --approve-ready   select the server's ready_to_publish lane (default quality
+                    floor 14; a higher --min-quality narrows it, while a lower
+                    value explicitly reaches into needs_score)
+  --min-quality N   quality threshold for --approve-ready (0-20)
+  --all             approve everything except needs_your_eyes items
+  --include-flagged include needs_your_eyes with --all
+  --keep-private    keep one lane owner-only (default: needs_your_eyes)
+  --lane <lane>     lane for --keep-private: ready_to_publish, needs_score,
+                    or needs_your_eyes
+  --all-reject      reject the whole batch [--yes for scripted incident use]
+  --yes             bypass count only for --keep-private or --all-reject
+  --base-url <url>
+
+Every bulk path prints the exact list and requires typing its count. Approval
+never accepts --yes. Private-destined rows are excluded from approval; keep
+them private or sanitize-promote a corrected replacement.`,
+    disable: `Usage: auxilo disable [--base-url <url>]
+
+Disable background extraction locally and optionally revoke server consent.`,
+  };
+  if (command && blocks[command]) {
+    console.log(`\n${blocks[command]}\n`);
+    return;
+  }
   console.log(`
 Usage: auxilo <command>
 
@@ -771,18 +931,19 @@ Commands:
   status    Show install/auth/extraction status.
   review    Review YOUR pending-review learnings (from background extraction)
             and approve/reject before anything goes public. Default: triage
-            summary table first (quality desc, clean vs flagged), then rapid
-            y/n/s review.
+            summary first in the server's Ready to publish / Needs a score /
+            Needs your eyes lanes, then rapid y/n/s review.
             Flags:
               --list            summary table only, no changes
-              --approve-clean   bulk-approve items that passed EVERY platform
-                                screen AND quality >= threshold (default 14;
-                                tune with --min-quality N). Prints the exact
-                                list, then requires typing the count.
-              --all             bulk-approve everything EXCEPT screen-flagged
-                                items (add --include-flagged to include them).
+              --approve-ready   select the server's ready_to_publish lane
+                                (default floor 14; tune with --min-quality N).
+                                Prints the exact list, then requires its count.
+              --all             bulk-approve everything EXCEPT needs_your_eyes
+                                (add --include-flagged to include that lane).
                                 Same typed-count confirmation.
-              --min-quality N   quality threshold for --approve-clean (0-20)
+              --min-quality N   quality threshold for --approve-ready (0-20)
+              --keep-private    keep needs_your_eyes owner-only by default
+              --lane <lane>     choose a server lane for --keep-private
               --all-reject      reject the whole batch [--yes for scripted
                                 incident response; rejects stay private]
               --base-url <url>
@@ -797,6 +958,10 @@ Docs: https://auxilo.io · API: ${installer.DEFAULT_BASE_URL}
 
 async function main() {
   const cmd = process.argv[2];
+  const subcommandHelp = ['help', '--help', '-h'].includes(process.argv[3]);
+  if (['setup', 'init', 'status', 'review', 'disable'].includes(cmd) && subcommandHelp) {
+    return usage(cmd);
+  }
   const flags = parseFlags(process.argv);
   switch (cmd) {
     case 'setup': return cmdSetup(flags);
@@ -829,4 +994,12 @@ if (require.main === module) {
   run();
 }
 
-module.exports = { parseFlags, resolveBaseUrl, run };
+module.exports = {
+  parseFlags,
+  resolveBaseUrl,
+  shortFlags,
+  groupSummaryRows,
+  printSummaryTable,
+  usage,
+  run,
+};

package/lib/extraction-index.js

@@ -405,6 +405,7 @@ function filterIndexedNearDuplicates(candidates, indexState, opts = {}) {
   if (!indexState || !indexState.usable) {
     return { kept: input.slice(), dropped: [], disabled: true };
   }
+  const comparisonAccountId = opts.contributorAccountId || '__local_index_owner';
   const localRows = indexState.rows
     .filter((row) => typeof row.body === 'string' && row.body.trim())
     .map((row, index) => ({
@@ -413,6 +414,8 @@ function filterIndexedNearDuplicates(candidates, indexState, opts = {}) {
       body: row.body,
       category: row.category,
       status: row.status || null,
+      visibility: row.visibility,
+      contributor_account_id: row.contributor_account_id || comparisonAccountId,
     }));
   if (!localRows.length) return { kept: input.slice(), dropped: [], disabled: false };
 
@@ -420,7 +423,9 @@ function filterIndexedNearDuplicates(candidates, indexState, opts = {}) {
     const kept = [];
     const dropped = [];
     for (const candidate of input) {
-      const result = findNearDuplicate(candidate, localRows);
+      const result = findNearDuplicate(candidate, localRows, {
+        contributorAccountId: comparisonAccountId,
+      });
       if (result.verdict === 'flag') {
         const matchedRow = localRows.find((row) => row.id === result.match.id);
         dropped.push({

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 ──────────────────────────────────────────────────────────────
 
@@ -75,6 +76,7 @@ const RUNNER_STACK = Object.freeze([
   ['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],
 ]);
 
@@ -1559,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 */ }
 
@@ -1592,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

@@ -59,12 +59,12 @@ async function fetchPending(opts = {}) {
 }
 
 /**
- * POST /account/pending/:id/approve|reject — submit a self-review decision.
+ * POST /account/pending/:id/approve|reject|keep-private — submit a self-review decision.
  *
  * @param {object} opts
  * @param {string} opts.apiKey
  * @param {string} opts.id
- * @param {'approve'|'reject'} opts.decision
+ * @param {'approve'|'reject'|'keep_private'} opts.decision
  * @param {string} [opts.reason]    only sent on reject
  * @param {string} [opts.baseUrl]
  * @param {Function} [opts.fetchImpl]
@@ -74,8 +74,8 @@ async function submitDecision(opts = {}) {
   const { apiKey, id, decision, reason } = opts;
   if (!apiKey) throw new Error('submitDecision: apiKey is required');
   if (!id) throw new Error('submitDecision: id is required');
-  if (decision !== 'approve' && decision !== 'reject') {
-    throw new Error('submitDecision: decision must be "approve" or "reject"');
+  if (decision !== 'approve' && decision !== 'reject' && decision !== 'keep_private') {
+    throw new Error('submitDecision: decision must be "approve", "reject", or "keep_private"');
   }
   const baseUrl = normBase(opts.baseUrl);
   const fetchImpl = opts.fetchImpl || fetch;
@@ -89,10 +89,14 @@ async function submitDecision(opts = {}) {
     init.body = JSON.stringify(reason ? { reason } : {});
   }
 
-  const res = await fetchImpl(`${baseUrl}/account/pending/${encodeURIComponent(id)}/${decision}`, init);
+  const routeDecision = decision === 'keep_private' ? 'keep-private' : decision;
+  const res = await fetchImpl(`${baseUrl}/account/pending/${encodeURIComponent(id)}/${routeDecision}`, init);
   let body = {};
   try { body = await res.json(); } catch { /* non-JSON error body */ }
   if (!res.ok) {
+    if (decision === 'keep_private' && res.status === 400 && body.code === 'bad_decision') {
+      throw new Error('server predates the private tier — update the server');
+    }
     throw new Error(`${decision} failed for ${id} (HTTP ${res.status}): ${body.error || 'unknown error'}`);
   }
   return body;
@@ -121,7 +125,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 +133,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).
@@ -206,15 +214,16 @@ function chunkDecisions(list, size = BULK_CHUNK) {
  * stay applied; the endpoint is idempotent per id, so re-running is safe).
  *
  * @param {object} opts  { apiKey, decisions, baseUrl?, fetchImpl?, onChunk? }
- * @returns {Promise<{approved:number, rejected:number, idempotent:number, failed:number, results:Array<object>}>}
+ * @returns {Promise<{approved:number, kept_private:number, rejected:number, idempotent:number, failed:number, results:Array<object>}>}
  */
 async function submitBulkChunked(opts = {}) {
   const { decisions } = opts;
-  const totals = { approved: 0, rejected: 0, idempotent: 0, failed: 0, results: [] };
+  const totals = { approved: 0, kept_private: 0, rejected: 0, idempotent: 0, failed: 0, results: [] };
   const chunks = chunkDecisions(decisions || []);
   for (let i = 0; i < chunks.length; i++) {
     const resp = await submitBulk({ ...opts, decisions: chunks[i] });
     totals.approved += resp.approved || 0;
+    totals.kept_private += resp.kept_private || 0;
     totals.rejected += resp.rejected || 0;
     totals.idempotent += resp.idempotent || 0;
     totals.failed += resp.failed || 0;
@@ -233,46 +242,127 @@ 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_private: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_private = [];
   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) {
-      excluded_flagged.push(row);
+    if (row.visibility === 'private') {
+      excluded_private.push(row);
       continue;
     }
-    if (mode === 'clean' && !qualityClears(row, minQuality)) {
-      (row.quality == null ? excluded_unscored : excluded_low_quality).push(row);
+    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 === '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_private,
+    excluded_flagged,
+    excluded_low_quality,
+    excluded_unscored,
+    min_quality: minQuality,
+    version_skew,
+  };
+}
+
+/**
+ * Select one server lane to finalize as owner-only private. The default is
+ * needs_your_eyes; another lane requires an explicit --lane value.
+ */
+function selectForKeepPrivate(rows, opts = {}) {
+  const lane = opts.lane || LANE_NEEDS_EYES;
+  if (!REVIEW_LANES.has(lane)) {
+    throw new Error(`Invalid --lane "${lane}" (expected ${Array.from(REVIEW_LANES).join(', ')})`);
+  }
+  const selected = [];
+  const excluded_by_lane = {
+    [LANE_READY]: [],
+    [LANE_NEEDS_SCORE]: [],
+    [LANE_NEEDS_EYES]: [],
+  };
+  let version_skew = false;
+  for (const row of rows || []) {
+    if (!row || !row.id) continue;
+    const resolved = reviewLane(row);
+    version_skew = version_skew || resolved.version_skew;
+    if (resolved.lane === lane) selected.push(row);
+    else excluded_by_lane[resolved.lane].push(row);
+  }
+  return { selected, excluded_by_lane, lane, version_skew };
 }
 
 module.exports = {
@@ -287,5 +377,7 @@ module.exports = {
   chunkDecisions,
   submitBulkChunked,
   qualityClears,
+  reviewLane,
   selectForBulkApprove,
+  selectForKeepPrivate,
 };

package/lib/similarity.js

@@ -204,13 +204,39 @@ function similarityScore(a, b) {
 }
 
 /**
- * Scan the full catalog for a near-verbatim match of `candidate`.
- * Rejected and cross-category predecessors are intentionally included.
+ * SPEC3-G1 comparison-set doctrine. Public predecessors collide for every
+ * caller; any non-public predecessor (pending, rejected, retracted, or
+ * approved-private) is visible to duplicate screening only for its owner.
+ * Missing visibility is the zero-migration public default.
+ */
+function isPublicComparisonPredecessor(learning) {
+  return !!learning &&
+    (!learning.status || learning.status === 'approved') &&
+    learning.visibility !== 'private';
+}
+
+function isComparisonEligible(learning, contributorAccountId) {
+  if (isPublicComparisonPredecessor(learning)) return true;
+  return !!contributorAccountId &&
+    learning &&
+    learning.contributor_account_id === contributorAccountId;
+}
+
+function comparisonCatalog(catalog, contributorAccountId) {
+  return (catalog || []).filter((learning) =>
+    isComparisonEligible(learning, contributorAccountId));
+}
+
+/**
+ * Scan the caller-safe comparison catalog for a near-verbatim match.
+ * Public predecessors compare for everyone. Non-public predecessors compare
+ * only for their contributor account.
  *
  * @param {{title:string, body:string, category:string}} candidate
  * @param {Array<object>} catalog  existing learnings
  * @param {{flagThreshold?:number, tfCosineThreshold?:number,
- *   compositeThreshold?:number, excludeId?:string}} [opts]
+ *   compositeThreshold?:number, excludeId?:string,
+ *   contributorAccountId?:string}} [opts]
  * @returns {{verdict:'flag'|'clean', match: null|object}}
  */
 function findNearDuplicate(candidate, catalog, opts = {}) {
@@ -223,6 +249,7 @@ function findNearDuplicate(candidate, catalog, opts = {}) {
   for (const existing of catalog || []) {
     if (!existing) continue;
     if (opts.excludeId && existing.id === opts.excludeId) continue;
+    if (!isComparisonEligible(existing, opts.contributorAccountId)) continue;
 
     const channels = scorePrepared(candidatePrepared, prepareLearning(existing));
     const shingleFlagged = channels.d1 >= flagAt;
@@ -232,6 +259,7 @@ function findNearDuplicate(candidate, catalog, opts = {}) {
       best = {
         id: existing.id,
         status: existing.status || null,
+        visibility: existing.visibility === 'private' ? 'private' : 'public',
         category: existing.category || null,
         similarity: channels.composite,
         channel: shingleFlagged ? 'shingle' : 'near_verbatim',
@@ -251,6 +279,9 @@ function findNearDuplicate(candidate, catalog, opts = {}) {
 module.exports = {
   similarityScore,
   findNearDuplicate,
+  isPublicComparisonPredecessor,
+  isComparisonEligible,
+  comparisonCatalog,
   tokenize,
   tokenSet,
   jaccard,

package/mcp-server.js

@@ -134,10 +134,46 @@ function planApproveClean(summary, opts = {}) {
   };
 }
 
+// Private-tier counterpart to planApproveClean. Selection is delegated to the
+// same lib/review.js helper as the CLI; the default is needs_your_eyes.
+function planKeepPrivate(summary, opts = {}) {
+  const sel = reviewLib.selectForKeepPrivate((summary && summary.items) || [], {
+    lane: opts.lane,
+  });
+  const brief = (r) => ({
+    id: r.id,
+    title: r.title,
+    category: r.category,
+    quality: r.quality,
+    visibility: r.visibility,
+    lane: reviewLib.reviewLane(r).lane,
+  });
+  return {
+    dry_run: true,
+    lane: sel.lane,
+    pending_count: summary ? summary.pending_count : 0,
+    would_keep_private_count: sel.selected.length,
+    would_keep_private: sel.selected.map(brief),
+    excluded_by_lane: Object.fromEntries(
+      Object.entries(sel.excluded_by_lane).map(([lane, rows]) => [lane, rows.map(brief)])
+    ),
+    next_step: sel.selected.length > 0
+      ? `Show the operator this list and count (${sel.selected.length}). After confirmation, call auxilo_review again with {action:"keep_private", dry_run:false, confirm:true, expected_count:${sel.selected.length}}. Each item stays yours; owner-only recall at $0; never published.`
+      : 'Nothing is in the selected lane. No follow-up call needed.',
+  };
+}
+
+function keepPrivateDecisions(plan) {
+  return (plan && plan.would_keep_private || []).map((row) => ({
+    id: row.id,
+    decision: 'keep_private',
+  }));
+}
+
 // Review-seamless: POST one confirmed decision batch through the counted bulk
 // endpoint, chunked at the server cap. Used by approve/reject/approve_clean.
 async function postBulkChunks(headers, decisions) {
-  const totals = { approved: 0, rejected: 0, idempotent: 0, failed: 0, results: [] };
+  const totals = { approved: 0, kept_private: 0, rejected: 0, idempotent: 0, failed: 0, results: [] };
   for (const chunk of reviewLib.chunkDecisions(decisions)) {
     const resp = await fetch(`${AUXILO_BASE}/account/pending/bulk`, {
       method: 'POST',
@@ -151,6 +187,7 @@ async function postBulkChunks(headers, decisions) {
       return totals;
     }
     totals.approved += data.approved || 0;
+    totals.kept_private += data.kept_private || 0;
     totals.rejected += data.rejected || 0;
     totals.idempotent += data.idempotent || 0;
     totals.failed += data.failed || 0;
@@ -160,7 +197,7 @@ async function postBulkChunks(headers, decisions) {
 }
 
 const server = new Server(
-  { name: 'auxilo', version: '0.9.4' },
+  { name: 'auxilo', version: '0.9.8' },
   {
     capabilities: { tools: {} },
     instructions: `You are connected to Auxilo, a knowledge marketplace where AI agents buy and sell operational learnings.
@@ -394,21 +431,22 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'auxilo_review',
-      description: 'Review YOUR OWN pending-review learnings (from background extraction) so they can be approved to the public marketplace or rejected to stay private. Account-scoped: only the authenticated account\'s own pending items are ever visible or affected. ACTIONS: "list" returns the triage summary (counts incl. by_signal + compact rows with quality score, lane, a one-sentence why for flagged items, and platform screen verdicts: injection, content sensitivity, near-duplicate). "approve" / "reject" apply explicit decisions to the ids you pass (the operator must have named or confirmed these items). "approve_clean" selects every item that passed ALL platform screens AND has quality >= min_quality (default 14/20); it is DRY-RUN BY DEFAULT and returns exactly what WOULD be approved. "reject_by_signal" bulk-rejects every pending item carrying one flag signal (e.g. social_handle) — REJECT ONLY (items stay private; there is deliberately no bulk approve by class): the operator must confirm the signal AND its by_signal count from "list", and you pass that count as expected_count — the server refuses if the live selection differs. "sanitize" resubmits ONE operator-corrected item through EVERY screen with lineage (the original is retired to private, reason sanitize-resubmit; the replacement is ALWAYS held for the operator\'s explicit approval — never auto-published): only call it with a correction the operator reviewed. CONSENT CONTRACT: nothing goes public without the contributor\'s explicit approval. So before executing approve_clean you MUST show the operator the dry-run list and count and get their confirmation, then call again with dry_run:false, confirm:true, and expected_count set to the dry-run count. The server also enforces a counted-confirmation gate on every bulk call. Requires your configured API key (or session_token).',
+      description: 'Review YOUR OWN pending-review learnings (from background extraction) so they can be approved to the public marketplace, rejected, or kept private. Account-scoped: only the authenticated account\'s own pending items are ever visible or affected. ACTIONS: "list" returns the triage summary (counts incl. by_signal + compact rows with quality score, lane, a one-sentence why for flagged items, and platform screen verdicts: injection, content sensitivity, near-duplicate). "approve" / "reject" apply explicit decisions to the ids you pass (the operator must have named or confirmed these items). "keep_private" finalizes one id or the selected lane (needs_your_eyes by default): it stays yours; owner-only recall at $0; never published. Bulk keep_private is DRY-RUN BY DEFAULT and uses the same selection helper as the CLI. "approve_clean" selects every item that passed ALL platform screens AND has quality >= min_quality (default 14/20); it is DRY-RUN BY DEFAULT and returns exactly what WOULD be approved. "reject_by_signal" bulk-rejects every pending item carrying one flag signal (e.g. social_handle) — REJECT ONLY (items stay private; there is deliberately no bulk approve by class): the operator must confirm the signal AND its by_signal count from "list", and you pass that count as expected_count — the server refuses if the live selection differs. "sanitize" resubmits ONE operator-corrected item through EVERY screen with lineage (the original is retired to private, reason sanitize-resubmit; the replacement is ALWAYS held for the operator\'s explicit approval — never auto-published): only call it with a correction the operator reviewed. CONSENT CONTRACT: nothing goes public without the contributor\'s explicit approval. Before executing approve_clean or bulk keep_private, show the operator the dry-run list and count, then call again with dry_run:false, confirm:true, and expected_count set to the dry-run count. The server also enforces a counted-confirmation gate on every bulk call. Requires your configured API key (or session_token).',
       inputSchema: {
         type: 'object',
         properties: {
-          action: { type: 'string', enum: ['list', 'approve', 'reject', 'approve_clean', 'reject_by_signal', 'sanitize'], description: 'What to do. Start with "list".' },
+          action: { type: 'string', enum: ['list', 'approve', 'reject', 'keep_private', 'approve_clean', 'reject_by_signal', 'sanitize'], description: 'What to do. Start with "list".' },
           ids: { type: 'array', items: { type: 'string' }, description: 'Learning ids for action approve/reject. These must be items the operator explicitly chose.' },
           reason: { type: 'string', description: 'Optional rejection reason (actions reject / reject_by_signal; max 500 chars).' },
           signal: { type: 'string', description: 'reject_by_signal only. The flag signal to reject by (a name from counts.by_signal, e.g. social_handle, person_name, injection).' },
-          id: { type: 'string', description: 'sanitize only. The pending/rejected learning being corrected (operator-chosen).' },
+          id: { type: 'string', description: 'keep_private single-item or sanitize. The operator-chosen learning id.' },
           title: { type: 'string', description: 'sanitize only. Corrected title (omit to keep the original).' },
           body: { type: 'string', description: 'sanitize only. Corrected body (omit to keep the original). At least one of title/body is required.' },
           tags: { type: 'array', items: { type: 'string' }, description: 'sanitize only. Corrected tags (omit to keep the original).' },
-          dry_run: { type: 'boolean', description: 'approve_clean only. Default TRUE: report what would be approved without changing anything. Set false only together with confirm:true and expected_count after the operator confirmed the dry-run list.' },
-          confirm: { type: 'boolean', description: 'approve_clean only. Must be exactly true to execute. Never set this without the operator\'s explicit go-ahead on the dry-run output.' },
-          expected_count: { type: 'number', description: 'approve_clean execute + reject_by_signal. The count the operator confirmed (dry-run count / by_signal count), echoed back. If the live selection differs (queue changed), nothing is mutated.' },
+          lane: { type: 'string', enum: ['ready_to_publish', 'needs_score', 'needs_your_eyes'], description: 'keep_private bulk only. Lane to select; defaults to needs_your_eyes.' },
+          dry_run: { type: 'boolean', description: 'approve_clean or bulk keep_private. Default TRUE: report exactly what would change. Set false only with confirm:true and expected_count after operator confirmation.' },
+          confirm: { type: 'boolean', description: 'approve_clean or bulk keep_private. Must be exactly true to execute after operator confirmation.' },
+          expected_count: { type: 'number', description: 'approve_clean, bulk keep_private, or reject_by_signal. The confirmed selection count. If the live selection differs, nothing is mutated.' },
           min_quality: { type: 'number', description: 'approve_clean quality threshold 0-20 (default 14). 0 includes unscored items.' },
           session_token: { type: 'string', description: 'Optional JWT session token from /auth/verify. If omitted, your configured API key authenticates the account.' },
         },
@@ -665,6 +703,58 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           return text({ action: args.action, submitted: decisions.length, ...totals });
         }
 
+        if (args.action === 'keep_private') {
+          // A named id is an explicit single-item decision. It uses the
+          // existing single route and therefore surfaces server 4xx truth.
+          if (typeof args.id === 'string' && args.id) {
+            const resp = await fetch(
+              `${AUXILO_BASE}/account/pending/${encodeURIComponent(args.id)}/keep-private`,
+              { method: 'POST', headers }
+            );
+            const data = await resp.json();
+            return text(data);
+          }
+
+          const summaryResp = await fetch(`${AUXILO_BASE}/account/pending/summary`, { headers });
+          const summary = await summaryResp.json();
+          if (!summaryResp.ok) return text(summary);
+
+          let plan;
+          try {
+            plan = planKeepPrivate(summary, args);
+          } catch (err) {
+            return text({ error: err.message });
+          }
+          if (args.dry_run !== false || args.confirm !== true) {
+            return text(plan);
+          }
+          if (!Number.isInteger(args.expected_count)) {
+            return text({
+              error: 'expected_count is required to execute keep_private: echo the would_keep_private_count from the dry run.',
+              ...plan,
+            });
+          }
+          if (args.expected_count !== plan.would_keep_private_count) {
+            return text({
+              error: `Selection changed since the dry run (expected ${args.expected_count}, now ${plan.would_keep_private_count}). Nothing was changed. Re-run the dry run and re-confirm.`,
+              ...plan,
+            });
+          }
+          const decisions = keepPrivateDecisions(plan);
+          if (decisions.length === 0) {
+            return text({ action: 'keep_private', kept_private: 0, message: 'Nothing is in the selected lane.' });
+          }
+          const totals = await postBulkChunks(headers, decisions);
+          return text({
+            action: 'keep_private',
+            executed: true,
+            lane: plan.lane,
+            submitted: decisions.length,
+            ...totals,
+            note: 'These items stay yours; owner-only recall at $0; never published.',
+          });
+        }
+
         if (args.action === 'approve_clean') {
           const summaryResp = await fetch(`${AUXILO_BASE}/account/pending/summary`, { headers });
           const summary = await summaryResp.json();
@@ -752,7 +842,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           return text(await resp.json());
         }
 
-        return text({ error: `Unknown action: ${args.action}. Use list, approve, reject, approve_clean, reject_by_signal, or sanitize.` });
+        return text({ error: `Unknown action: ${args.action}. Use list, approve, reject, keep_private, approve_clean, reject_by_signal, or sanitize.` });
       }
 
       case 'get_knowledge_stats': {
@@ -775,7 +865,17 @@ function text(obj) {
 // LW-3(a): export the pure helpers so they can be unit-tested without starting
 // the stdio transport. When this file is required (not run directly), stop here
 // before the CLI dispatch and MCP startup below.
-module.exports = { fenceUnlockResult, UNTRUSTED_CONTENT_ADVISORY, baseHeaders, planApproveClean, unlockPaymentRequired, shapeWithdrawStatus, verifyWalletRequestBody };
+module.exports = {
+  fenceUnlockResult,
+  UNTRUSTED_CONTENT_ADVISORY,
+  baseHeaders,
+  planApproveClean,
+  planKeepPrivate,
+  keepPrivateDecisions,
+  unlockPaymentRequired,
+  shapeWithdrawStatus,
+  verifyWalletRequestBody,
+};
 if (require.main !== module) {
   return;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auxilo-mcp",
-  "version": "0.9.6",
+  "version": "0.9.8",
   "mcpName": "io.github.silent-architects/auxilo",
   "description": "MCP server for Auxilo. Your agent stops solving the same problem twice: auto-extracted learnings, free self-unlocks, and earnings when other agents unlock yours.",
   "main": "mcp-server.js",
@@ -13,6 +13,7 @@
     "bin/",
     "lib/installer.js",
     "lib/review.js",
+    "lib/hook-status.js",
     "lib/sensitivity-filter.js",
     "lib/extraction-index.js",
     "lib/similarity.js",

package/scripts/extract-local.js

@@ -32,6 +32,7 @@ const {
 // lists are duplicated here from lib/category-scope-migration.js (server truth);
 // test/ci5-scope-enforcement.test.js pins the copies equal.
 const CATEGORIES = ['data-processing', 'web-interaction', 'code-execution', 'storage-state', 'payment-financial', 'monitoring'];
+const PRIVATE_CATEGORIES = [...CATEGORIES, 'non-technical'];
 const RETIRED_CATEGORIES = ['communication', 'content-generation'];
 
 /**
@@ -76,6 +77,23 @@ Output STRICT JSON ONLY — an object with:
      "matched_title": "<exact matched title>"}
   Scope/quality/sensitivity skips are not dedup_drops.`;
 
+const PUBLIC_SCOPE_BLOCK = `HARD SCOPE RULE — TECHNICAL LEARNINGS ONLY (the marketplace accepts nothing else): extract ONLY technical/operational learnings — APIs, developer tools, code, infrastructure, data pipelines, monitoring/observability, payment/crypto TECHNOLOGY, debugging. NEVER extract interpersonal or communication strategy, copywriting/content/marketing insights, business or negotiation strategy, personal matters, or creative-writing technique — DROP such candidates entirely, do not relabel them. A technical learning about a messaging/email/notification API belongs under "web-interaction" or "code-execution"; content/data pipeline TECH belongs under "data-processing".
+
+SYSTEM-FACT TEST (CI-7): Extract ONLY when a system and a symptom are at the core — an error, an undocumented limitation, a reproducible behavior of an external tool/API/OS. If the candidate is advice about how to work (process, workflow, methodology, decision practice), do NOT extract it. "Odesli cannot resolve Tidal artist URLs" is a learning; "use a two-phase consultation workflow" is not, no matter how well it would score.`;
+
+const PRIVATE_SCOPE_BLOCK = `PRIVATE CAPTURE SCOPE — OWNER-ONLY: extract reusable technical OR non-technical operational learnings. Non-technical process, workflow, communication, content, business, or creative learnings may use category "non-technical"; do not drop a genuine reusable candidate solely because it is non-technical. This private lane is never published unless the owner later sanitizes and promotes an item through public review. The mandatory sensitivity screen still applies without exception.`;
+
+function promptBaseForVisibility(captureVisibility) {
+  if (captureVisibility !== 'private') return EXTRACTION_PROMPT_BASE;
+  return EXTRACTION_PROMPT_BASE
+    .replace(
+      "to publish to a PUBLIC knowledge marketplace read by other AI agents.",
+      "for the owner's private, owner-only knowledge lane."
+    )
+    .replace(PUBLIC_SCOPE_BLOCK, PRIVATE_SCOPE_BLOCK)
+    .replace(JSON.stringify(CATEGORIES), JSON.stringify(PRIVATE_CATEGORIES));
+}
+
 /** A1: rubric addendum — appended ONLY when scoreExtractionEnabled(). */
 const QUALITY_RUBRIC_ADDENDUM = `
   "quality_self_assessment": an object scoring the learning honestly on four
@@ -105,7 +123,7 @@ function buildExtractionPrompt(opts = {}) {
   const memory = typeof opts.previousLessonsSection === 'string'
     ? opts.previousLessonsSection
     : '';
-  return EXTRACTION_PROMPT_BASE +
+  return promptBaseForVisibility(opts.captureVisibility) +
     (withScore ? QUALITY_RUBRIC_ADDENDUM : '') +
     (memory ? `\n\n${memory}` : '') +
     PROMPT_SUFFIX;
@@ -144,6 +162,7 @@ function extractWithClaudeCode(transcript, opts = {}) {
     ? opts.prompt
     : buildExtractionPrompt({
       previousLessonsSection: opts.previousLessonsSection,
+      captureVisibility: opts.captureVisibility,
       ...(opts.scoreExtraction !== undefined && { scoreExtraction: opts.scoreExtraction }),
     });
   const input = prompt + String(transcript).slice(0, 200000);
@@ -226,11 +245,15 @@ function normalizeLearningArray(arr, opts = {}) {
   // would launder a non-tech candidate (e.g. one the model labeled
   // 'communication') into the catalog wearing a tech label. Category-based,
   // so it applies identically in BOTH score-gate states.
-  const inScope = shaped.filter(l => CATEGORIES.includes(l.category));
+  const allowedCategories = opts.captureVisibility === 'private' ? PRIVATE_CATEGORIES : CATEGORIES;
+  const inScope = shaped.filter(l => allowedCategories.includes(l.category));
   // Gate-A F5: make the drop observable — count to stderr (never stdout; the
   // hook log captures it) so a silently over-dropping prompt is diagnosable.
   const dropped = shaped.length - inScope.length;
-  if (dropped > 0) console.error(`[extract-local] dropped ${dropped} candidate(s) outside the technical category set (CI-5 scope)`);
+  if (dropped > 0) {
+    const scope = opts.captureVisibility === 'private' ? 'private category set' : 'technical category set (CI-5 scope)';
+    console.error(`[extract-local] dropped ${dropped} candidate(s) outside the ${scope}`);
+  }
   return inScope
     .map(l => {
       const out = {
@@ -570,6 +593,7 @@ async function extractLocally(transcript, sourceType, opts = {}) {
     };
   const prompt = buildExtractionPrompt({
     previousLessonsSection: promptMemory.section,
+    captureVisibility: opts.captureVisibility,
     ...(opts.scoreExtraction !== undefined && { scoreExtraction: opts.scoreExtraction }),
   });
   const invokeModel = typeof opts.invokeModel === 'function'
@@ -639,7 +663,7 @@ async function extractLocally(transcript, sourceType, opts = {}) {
 
 module.exports = {
   extractLocally, parseLearnings, parseExtractionOutput, resolveClaudeBin,
-  CATEGORIES, RETIRED_CATEGORIES,
+  CATEGORIES, PRIVATE_CATEGORIES, RETIRED_CATEGORIES,
   EXTRACTION_PROMPT, buildExtractionPrompt, scoreExtractionEnabled,
   validateQualityAssessment, QUALITY_DIMENSIONS,
   buildAnchoredJudgePrompt, parseJudgeDecisions, runAnchoredJudge,

package/scripts/runner.js

@@ -39,6 +39,7 @@ const crypto = require('crypto');
 const { spawn } = require('child_process');
 const { scanText, SENSITIVITY_FILTER_VERSION } = require('../lib/sensitivity-filter.js');
 const { appendSubmittedLearning } = require('../lib/extraction-index.js');
+const { hasAuxiloSessionEndHook } = require('../lib/hook-status.js');
 const { TranscriptSource } = require('./sources/source.interface.js');
 const { GenericJsonlSource } = require('./sources/generic-jsonl.js');
 
@@ -58,6 +59,13 @@ const CREDS_PATH = path.join(AUXILO_DIR, 'credentials.json');
  *   2. credentials.json .base_url
  *   3. http://localhost:49152 (dev default)
  */
+function resolveCaptureVisibility(env = {}, fileCreds = {}) {
+  const value = Object.prototype.hasOwnProperty.call(env, 'AUXILO_CAPTURE_VISIBILITY')
+    ? env.AUXILO_CAPTURE_VISIBILITY
+    : fileCreds.capture_visibility;
+  return value === 'private' ? 'private' : 'public';
+}
+
 function loadCredentials() {
   let fileCreds = {};
   try {
@@ -69,10 +77,16 @@ function loadCredentials() {
     apiKey: process.env.AUXILO_API_KEY || fileCreds.api_key || null,
     baseUrl: process.env.AUXILO_BASE_URL || fileCreds.base_url || 'http://localhost:49152',
     accountLabel: fileCreds.label || fileCreds.account_id || null,
+    captureVisibility: resolveCaptureVisibility(process.env, fileCreds),
   };
 }
 
-const { apiKey: API_KEY, baseUrl: BASE_URL, accountLabel: ACCOUNT_LABEL } = loadCredentials();
+const {
+  apiKey: API_KEY,
+  baseUrl: BASE_URL,
+  accountLabel: ACCOUNT_LABEL,
+  captureVisibility: CAPTURE_VISIBILITY,
+} = loadCredentials();
 
 // Parsing contract with jobs/daily-digest.js readLogRows(): digest-relevant log
 // lines must carry `account=` (builder attribution) and, on publish lines,
@@ -289,7 +303,7 @@ function listPendingFiles() {
  *
  * @param {Array<object>} learnings
  * @param {string} sourceType
- * @param {object} [opts]  { fetchImpl, baseUrl, apiKey, indexPath, now } —
+ * @param {object} [opts]  { fetchImpl, baseUrl, apiKey, captureVisibility, indexPath, now } —
  *   injectable for tests
  * @returns {Promise<{published:number, held:number, rejected:number}>}
  */
@@ -297,6 +311,7 @@ async function submitLearnings(learnings, sourceType, opts = {}) {
   const fetchImpl = opts.fetchImpl || fetch;
   const baseUrl = opts.baseUrl || BASE_URL;
   const apiKey = opts.apiKey !== undefined ? opts.apiKey : API_KEY;
+  const captureVisibility = opts.captureVisibility || CAPTURE_VISIBILITY;
 
   let published = 0;
   let held = 0;
@@ -319,6 +334,7 @@ async function submitLearnings(learnings, sourceType, opts = {}) {
           outcome: l.outcome,
           contributor_agent: `auxilo-hook/${sourceType}`,
           submission_channel: 'extraction',
+          ...(captureVisibility === 'private' && { visibility: 'private' }),
           ...(l.quality_self_assessment && { quality_self_assessment: l.quality_self_assessment }),
         }),
       });
@@ -340,7 +356,7 @@ async function submitLearnings(learnings, sourceType, opts = {}) {
   return { published, held, rejected };
 }
 
-async function postExtract(transcript, sessionId, sourceType, _scrubReport) {
+async function postExtract(transcript, sessionId, sourceType, _scrubReport, opts = {}) {
   // CLIENT-SIDE extraction (2026-07-02). Server /extract is deprecated (410) — Auxilo
   // does not pay to extract. The local model (via `claude -p`) extracts + self-screens
   // the already-client-scrubbed transcript, and we submit finished learnings to /learn.
@@ -364,8 +380,9 @@ async function postExtract(transcript, sessionId, sourceType, _scrubReport) {
       judge_prompt_tokens: judgePromptTokens = 0,
       judge_completion_tokens: judgeCompletionTokens = 0,
     } = await extractLocally(transcript, sourceType, {
-      baseUrl: BASE_URL,
-      apiKey: API_KEY,
+      baseUrl: opts.baseUrl || BASE_URL,
+      apiKey: opts.apiKey !== undefined ? opts.apiKey : API_KEY,
+      captureVisibility: opts.captureVisibility || CAPTURE_VISIBILITY,
       log,
       auditLog: auditDropLog,
     }));
@@ -377,7 +394,10 @@ async function postExtract(transcript, sessionId, sourceType, _scrubReport) {
     return { learnings_published: 0, learnings_held: 0, learnings_rejected: 0, extraction_id: 'client-skip' };
   }
 
-  const { published, held, rejected } = await submitLearnings(learnings, sourceType);
+  const { published, held, rejected } = await submitLearnings(learnings, sourceType, {
+    ...opts,
+    captureVisibility: opts.captureVisibility || CAPTURE_VISIBILITY,
+  });
   // NOTE: token-free prose — the digest-parsed `published=`/`held=`/`rejected=`
   // tokens live ONLY on the per-run caller log lines. This line previously
   // carried `published=` too and the digest double-counted every extraction
@@ -516,6 +536,7 @@ function sweeperManifest(repoRoot = path.resolve(__dirname, '..')) {
     ['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-side extraction (2026-07-02) — required by the sweep path since /extract went 410.
     // Missing from this manifest until 2026-07-19: installed sweepers crashed with
@@ -711,10 +732,10 @@ async function printStatus() {
   let hookInstalled = false;
   try {
     const settings = JSON.parse(fs.readFileSync(claudeSettingsPath, 'utf-8'));
-    hookInstalled = Array.isArray(settings.hooks?.SessionEnd) &&
-      settings.hooks.SessionEnd.some(h => h.includes('auxilo-extract'));
+    hookInstalled = hasAuxiloSessionEndHook(settings.hooks?.SessionEnd);
   } catch { /* no settings file */ }
   console.log(`Hook installed: ${hookInstalled ? 'yes' : 'no'}`);
+  console.log(`Settings inspected: ${claudeSettingsPath}`);
 
   // 5. Last sweep ran at
   console.log(`Last sweep: ${ledger.lastSweep || 'never'}`);
@@ -922,7 +943,8 @@ async function main() {
       try {
         const payload = JSON.parse(fs.readFileSync(qf, 'utf-8'));
         const result = await postExtract(
-          payload.transcript, payload.sessionId, payload.source, payload.scrubReport
+          payload.transcript, payload.sessionId, payload.source, payload.scrubReport,
+          { captureVisibility: payload.capture_visibility || CAPTURE_VISIBILITY }
         );
         log(`[runner] ✓ Flushed ${path.basename(qf)}: published=${result.learnings_published || 0} held=${result.learnings_held || 0} rejected=${result.learnings_rejected || 0} ${DIGEST_ACCOUNT}`);
         flushHeld += result.learnings_held || 0;
@@ -1057,6 +1079,7 @@ async function main() {
         scrubReport: report,
         mtime: sessionRef.mtime,
         queuedAt: new Date().toISOString(),
+        ...(CAPTURE_VISIBILITY === 'private' && { capture_visibility: 'private' }),
       });
 
       try {
@@ -1091,6 +1114,7 @@ module.exports = {
   loadLedger, saveLedger, ledgerHighWater, ledgerHas, ledgerMark,
   installHooks, installSweeper, installDigest, printStatus, scrubAndVerify, enumerateActiveSources,
   loadSources, SOURCES, sweeperManifest, submitLearnings, notifyHeld,
+  resolveCaptureVisibility, postExtract,
   KILL_SWITCH_PATH, PENDING_DIR, LEDGER_PATH,
 };