auxilo-mcp 0.9.7 → 0.9.9

package/README.md

@@ -45,13 +45,16 @@ Extraction defaults to seamless: a draft that passes every screen (secrets, sens
 
 ```bash
 npx auxilo review --list           # show all three lanes and each exception reason
-npx auxilo review --approve-ready  # select exactly the server's ready_to_publish lane
-npx auxilo review                  # approve, reject, view, or skip one draft at a time
+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
 ```
 
-Every bulk approval 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. 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

@@ -551,8 +551,9 @@ function fit(s, width) {
 /** Short lane/flag codes for a summary row, e.g. 'ready' or 'inj+sens'. */
 function shortFlags(row) {
   const resolved = review.reviewLane(row);
-  if (resolved.lane === 'ready_to_publish') return 'ready';
-  if (resolved.lane === 'needs_score') return 'score';
+  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',
@@ -560,7 +561,7 @@ function shortFlags(row) {
     process_advice: 'advice',
     account_vocab: 'vocab',
   };
-  return (row.flags || []).map((f) => map[f] || f).join('+') || 'flagged';
+  return visibility.concat((row.flags || []).map((f) => map[f] || f)).join('+') || 'flagged';
 }
 
 /** One compact triage line (shared by the table and rapid mode). */
@@ -660,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) {
@@ -720,6 +721,9 @@ async function cmdReview(flags) {
     const minQuality = parseMinQuality(flags);
     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
@@ -742,6 +746,9 @@ async function cmdReview(flags) {
   if (flags.all) {
     const includeFlagged = flags['include-flagged'] === true;
     const sel = review.selectForBulkApprove(rows, { mode: 'all', includeFlagged });
+    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) {
@@ -755,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). ──
@@ -784,16 +815,16 @@ 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;
+  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);
@@ -806,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; }
@@ -814,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');
@@ -823,7 +857,7 @@ 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 ────────────────────────────────────────────────────────────
@@ -856,10 +890,16 @@ Flags:
   --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 approval path prints the exact list and requires typing its count.`,
+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.`,
@@ -902,6 +942,8 @@ Commands:
                                 (add --include-flagged to include that lane).
                                 Same typed-count confirmation.
               --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>

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/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;
@@ -210,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;
@@ -270,7 +275,7 @@ function reviewLane(row) {
  *
  * @param {Array<object>} rows
  * @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}}
+ * @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' : 'ready';
@@ -281,6 +286,7 @@ function selectForBulkApprove(rows, opts = {}) {
 
   const selected = [];
   const included_beyond_verdict = [];
+  const excluded_private = [];
   const excluded_flagged = [];
   const excluded_low_quality = [];
   const excluded_unscored = [];
@@ -288,6 +294,10 @@ function selectForBulkApprove(rows, opts = {}) {
 
   for (const row of rows || []) {
     if (!row || !row.id) continue;
+    if (row.visibility === 'private') {
+      excluded_private.push(row);
+      continue;
+    }
     const resolved = reviewLane(row);
     version_skew = version_skew || resolved.version_skew;
 
@@ -320,6 +330,7 @@ function selectForBulkApprove(rows, opts = {}) {
   return {
     selected,
     included_beyond_verdict,
+    excluded_private,
     excluded_flagged,
     excluded_low_quality,
     excluded_unscored,
@@ -328,6 +339,32 @@ function selectForBulkApprove(rows, opts = {}) {
   };
 }
 
+/**
+ * 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 = {
   DEFAULT_BASE_URL,
   BULK_CHUNK,
@@ -342,4 +379,5 @@ module.exports = {
   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.7' },
+  { name: 'auxilo', version: '0.9.9' },
   {
     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.7",
+  "version": "0.9.9",
   "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",

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 = {
@@ -535,11 +558,14 @@ async function runAnchoredJudge(candidates, indexState, opts = {}) {
 
 /**
  * Extract learnings locally. Returns { learnings: [...] } or { learnings: [], skipped }.
- * Only claude-code has a local extractor today; other clients rely on the agent's
- * proactive auxilo_contribute (MCP) call.
+ * Claude Code and Codex rollout captures use the existing client-local Claude
+ * extractor; other clients rely on the agent's proactive auxilo_contribute
+ * (MCP) call.
  */
+const EXTRACTABLE_SOURCES = new Set(['claude-code', 'codex-cli']);
+
 async function extractLocally(transcript, sourceType, opts = {}) {
-  if (sourceType && sourceType !== 'claude-code') {
+  if (sourceType && !EXTRACTABLE_SOURCES.has(sourceType)) {
     return { learnings: [], skipped: `local extraction not implemented for "${sourceType}" — agent contributes via auxilo_contribute` };
   }
 
@@ -570,6 +596,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 +666,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

@@ -59,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 {
@@ -70,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,
@@ -290,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}>}
  */
@@ -298,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;
@@ -320,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 }),
         }),
       });
@@ -341,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.
@@ -365,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,
     }));
@@ -378,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
@@ -924,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;
@@ -953,6 +973,7 @@ async function main() {
   let totalOversize = 0; // N1: oversize-cap skips (subset of totalSkipped)
   let totalFailed = 0;
   let totalHeld = 0;
+  const refusedBySource = new Map();
 
   for (const source of sources) {
     log(`[runner] Discovering sessions from ${source.label} (${source.type})...`);
@@ -1001,7 +1022,7 @@ async function main() {
 
       // UC-1 format-probe refusal: null = skip silently (not a failure).
       if (!transcriptData || typeof transcriptData.transcript !== 'string') {
-        log(`[runner]   Skipped — format probe refused (source=${source.type})`);
+        refusedBySource.set(source.type, (refusedBySource.get(source.type) || 0) + 1);
         totalSkipped++;
         ledgerMark(ledger, source.type, sessionRef.sessionId, 'probe-refused', sessionRef.mtime);
         continue;
@@ -1059,6 +1080,7 @@ async function main() {
         scrubReport: report,
         mtime: sessionRef.mtime,
         queuedAt: new Date().toISOString(),
+        ...(CAPTURE_VISIBILITY === 'private' && { capture_visibility: 'private' }),
       });
 
       try {
@@ -1077,6 +1099,9 @@ async function main() {
     }
   }
 
+  for (const [sourceType, count] of refusedBySource) {
+    log(`[runner] ${sourceType}: ${count} refused (non-user/format)`);
+  }
   saveLedger(ledger);
   log(`[runner] Summary: ${totalDiscovered} discovered, ${totalProcessed} processed, ${totalSkipped} skipped (${totalOversize} oversize), ${totalFailed} failed`);
   if (totalOversize > 0) {
@@ -1093,6 +1118,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,
 };
 

package/scripts/sources/codex-cli.js

@@ -0,0 +1,268 @@
+/**
+ * scripts/sources/codex-cli.js — Codex CLI + Desktop Transcript Source (UC-6)
+ *
+ * Best-effort UC-3 poll adapter.
+ * UC-3 disclaimer: format community-reverse-engineered; verified against live operator install 2026-07-26 (247 rollouts).
+ * Shape drift fails silent instead of producing a guessed transcript.
+ *
+ * Upstream context:
+ *   openai/codex#21639 — Codex Desktop hooks regression
+ *   openai/codex#24948 — rollout files can grow to multi-GB size
+ *   openai/codex#21660 — rollout files may be created with 0644 permissions
+ *
+ * Desktop embeds the CLI and shares its ~/.codex rollout store, so one source
+ * id deliberately covers both clients. Privacy-sensitive base instructions,
+ * world state (including AGENTS.md), reasoning, and duplicate event messages
+ * are never normalized into transcript output.
+ *
+ * @module sources/codex-cli
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { TranscriptSource } = require('./source.interface');
+
+const DEFAULT_QUIESCENCE_MS = 30 * 60 * 1000;
+const UUID_AT_END_RE = /([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/i;
+
+function resolveQuiescenceMs(env = process.env) {
+  const raw = env && env.AUXILO_CODEX_QUIESCENCE_MS;
+  if (raw === undefined || raw === null || raw === '') return DEFAULT_QUIESCENCE_MS;
+  const value = Number(raw);
+  return Number.isInteger(value) && value > 0 ? value : DEFAULT_QUIESCENCE_MS;
+}
+
+function rolloutSessionId(filePath) {
+  const name = path.basename(filePath);
+  const match = name.match(UUID_AT_END_RE);
+  return match ? match[1] : path.basename(name, path.extname(name));
+}
+
+function listRollouts(root, recursive) {
+  const found = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true });
+  } catch {
+    return found;
+  }
+  for (const entry of entries) {
+    const filePath = path.join(root, entry.name);
+    if (recursive && entry.isDirectory()) {
+      found.push(...listRollouts(filePath, true));
+      continue;
+    }
+    if (entry.isFile() && /^rollout-.*\.jsonl$/i.test(entry.name)) found.push(filePath);
+  }
+  return found;
+}
+
+function textContentItems(content) {
+  if (!Array.isArray(content)) return [];
+  return content
+    .filter((item) =>
+      item &&
+      typeof item === 'object' &&
+      ['input_text', 'output_text', 'text'].includes(item.type) &&
+      typeof item.text === 'string'
+    )
+    .map((item) => item.text);
+}
+
+function stringifyValue(value) {
+  if (value === undefined || value === null) return '';
+  if (typeof value === 'string') return value;
+  try { return JSON.stringify(value) ?? ''; } catch { return String(value); }
+}
+
+function oneLine(value) {
+  return stringifyValue(value).replace(/\s+/g, ' ').trim();
+}
+
+function toolOutputItems(payload) {
+  const output = payload.output !== undefined ? payload.output : payload.content;
+  if (typeof output === 'string') return [output];
+  if (Array.isArray(output)) {
+    return output.flatMap((item) => {
+      if (typeof item === 'string') return [item];
+      if (!item || typeof item !== 'object') return [];
+      if (typeof item.text === 'string') return [item.text];
+      if (typeof item.output === 'string') return [item.output];
+      if (typeof item.content === 'string') return [item.content];
+      return [];
+    });
+  }
+  if (output && typeof output === 'object') {
+    if (typeof output.text === 'string') return [output.text];
+    if (typeof output.output === 'string') return [output.output];
+  }
+  return [];
+}
+
+class CodexCliSource extends TranscriptSource {
+  static id = 'codex-cli';
+  static displayName = 'Codex (CLI + Desktop)';
+  static version = '1.0.0';
+
+  constructor(config = {}) {
+    super(config);
+    const homeDir = config.homeDir || os.homedir();
+    this.codexDir = config.codexDir || path.join(homeDir, '.codex');
+    this.sessionsDir = path.join(this.codexDir, 'sessions');
+    this.archivedSessionsDir = path.join(this.codexDir, 'archived_sessions');
+    this.env = config.env || process.env;
+  }
+
+  async detect() {
+    try {
+      return fs.statSync(this.sessionsDir).isDirectory();
+    } catch {
+      return false;
+    }
+  }
+
+  async discoverSessions({ since } = {}) {
+    const parsedSince = since ? Date.parse(since) : 0;
+    const sinceMs = Number.isFinite(parsedSince) ? parsedSince : 0;
+    const quiescentBefore = Date.now() - resolveQuiescenceMs(this.env);
+    const candidates = [
+      ...listRollouts(this.sessionsDir, true),
+      ...listRollouts(this.archivedSessionsDir, false),
+    ];
+    const sessions = [];
+
+    for (const filePath of candidates) {
+      try {
+        const stat = fs.statSync(filePath);
+        if (!stat.isFile()) continue;
+        if (stat.mtimeMs <= sinceMs || stat.mtimeMs >= quiescentBefore) continue;
+        sessions.push({
+          sessionId: rolloutSessionId(filePath),
+          path: filePath,
+          mtime: stat.mtime.toISOString(),
+          bytes: stat.size,
+        });
+      } catch {
+        // A rollout can disappear or become unreadable while the sweep walks.
+      }
+    }
+
+    return sessions.sort((a, b) =>
+      Date.parse(a.mtime) - Date.parse(b.mtime) || a.path.localeCompare(b.path)
+    );
+  }
+
+  async readSession(sessionRef) {
+    try {
+      return await this._readSession(sessionRef);
+    } catch {
+      // Gate-A F-A: the adapter contract is never-throw. A newly observed
+      // optional field or other shape drift refuses the whole rollout rather
+      // than escaping into the runner as a failed session.
+      return this._refuse(sessionRef && sessionRef.path, 'unexpected normalization error');
+    }
+  }
+
+  _readSession(sessionRef) {
+    const filePath = sessionRef && sessionRef.path;
+    let raw;
+    try {
+      raw = fs.readFileSync(filePath, 'utf8');
+    } catch {
+      return this._refuse(filePath, 'unreadable rollout');
+    }
+
+    const records = [];
+    for (const line of raw.split(/\r?\n/)) {
+      if (!line.trim()) continue;
+      try {
+        const record = JSON.parse(line);
+        if (record && typeof record === 'object') records.push(record);
+      } catch {
+        // Individual malformed records are ignored; the format probe below
+        // still requires a valid first record and at least two valid records.
+      }
+    }
+
+    if (records.length === 0 || records[0].type !== 'session_meta') {
+      return this._refuse(filePath, 'first parseable record is not session_meta');
+    }
+    const sessionMeta = records[0].payload;
+    if (!sessionMeta || typeof sessionMeta !== 'object') {
+      return this._refuse(filePath, 'session_meta payload missing');
+    }
+    if (sessionMeta.thread_source !== 'user') {
+      return this._refuse(filePath, 'non-user thread');
+    }
+    if (records.length < 2) {
+      return this._refuse(filePath, 'fewer than two parseable records');
+    }
+
+    const turns = [];
+    for (const record of records) {
+      if (record.type !== 'response_item') continue;
+      const payload = record.payload;
+      if (!payload || typeof payload !== 'object') continue;
+
+      if (payload.type === 'message') {
+        const role = payload.role === 'user'
+          ? 'User'
+          : payload.role === 'assistant'
+            ? 'Assistant'
+            : null;
+        if (!role) continue;
+        const text = textContentItems(payload.content).join('\n').trim();
+        if (text) turns.push(`${role}: ${text}`);
+        continue;
+      }
+
+      if (payload.type === 'custom_tool_call') {
+        const name = oneLine(payload.name || payload.tool_name || payload.tool || 'unknown');
+        const args = oneLine(payload.arguments).slice(0, 500);
+        turns.push(`Tool: ${name}${args ? ` ${args}` : ''}`);
+        continue;
+      }
+
+      if (payload.type === 'custom_tool_call_output') {
+        const items = toolOutputItems(payload)
+          .map((item) => String(item).slice(0, 2000))
+          .filter(Boolean);
+        if (items.length > 0) turns.push(`Tool result: ${items.join('\n')}`);
+      }
+    }
+
+    return {
+      transcript: turns.join('\n\n'),
+      metadata: {
+        sessionId: sessionRef.sessionId,
+        source: 'codex-cli',
+        mtime: sessionRef.mtime,
+        bytes: sessionRef.bytes,
+        originator: sessionMeta.originator,
+        cwd: sessionMeta.cwd,
+        model_provider: sessionMeta.model_provider,
+      },
+    };
+  }
+
+  _refuse(filePath, reason) {
+    // Gate-A F-B: sweeps summarize refusals once in runner.js. Per-file paths
+    // are available only under an explicit local debug opt-in.
+    if (this.env.AUXILO_CODEX_DEBUG === '1') {
+      process.stderr.write(`[codex-cli] format probe refused ${filePath || '(unknown)'} (${reason}) — skipping\n`);
+    }
+    return null;
+  }
+
+  async registerSessionEndHook(cb) { return null; }
+}
+
+module.exports = {
+  CodexCliSource,
+  DEFAULT_QUIESCENCE_MS,
+  resolveQuiescenceMs,
+  rolloutSessionId,
+};