@theronap/agnoclast-mcp 0.9.256 → 0.9.258

package/lib/filing_obligations.mjs

@@ -74,16 +74,42 @@ export function renderFilingObligations(o) {
   }
   if (o.write?.undated) lines.push(`⚠ ${o.write.undated} of them has no date, so nothing will raise it by time.`)
   if (o.write?.unhomed) lines.push(`⚠ ${o.write.unhomed} could not be placed: the record is on no page.`)
-  if (Array.isArray(o.unverified) && o.unverified.length) {
+  // 2026-10-23: the server reports EACH candidate. Name every one it will not write as sent, and why.
+  const notAsSent = renderObligationItems(o.items, { onlyNotProposed: true })
+  if (notAsSent.length) {
+    lines.push(...notAsSent)
+  } else if (Array.isArray(o.unverified) && o.unverified.length) {
     lines.push(
       `⚠ NOT written — not in this text word for word: ${o.unverified.map((e) => `"${e}"`).join('; ')}. ` +
       "Quote the text's own sentence (propose_obligation with this record id).",
     )
   }
-  if (o.malformed) lines.push(`⚠ ${o.malformed} malformed obligation(s) were dropped.`)
+  if (o.malformed && !Array.isArray(o.items)) lines.push(`⚠ ${o.malformed} malformed obligation(s) were dropped.`)
+  if (o.write?.kept) lines.push(`${o.write.kept} matched an obligation the person already acted on — left as they left it, not written again.`)
   return lines
 }
 
+/**
+ * PURE. One line per obligation the server judged (`items`, server 2026-10-23): proposed, deduped (and against
+ * what), or rejected (and why). `onlyNotProposed` keeps just the ones that will NOT be written as sent. Empty
+ * for a server that sends no `items`, so an older server never reads as "nothing dropped".
+ */
+export function renderObligationItems(items, { onlyNotProposed = false } = {}) {
+  if (!Array.isArray(items) || items.length === 0) return []
+  const shown = onlyNotProposed ? items.filter((x) => x?.outcome !== 'proposed') : items
+  if (shown.length === 0) return []
+  const label = (x) => `obligations[${x.index}]${x.subject ? ` "${x.subject}"` : ''}`
+  const line = (x) => x.outcome === 'proposed'
+    ? `  · ${label(x)} — proposed`
+    : x.outcome === 'deduped'
+      ? `  · ${label(x)} — deduped: same sentence as ${x.against ?? 'another in this filing'} (one proposal, not two)`
+      : `  ⚠ ${label(x)} — REJECTED, not written: ${x.reason ?? 'refused'}`
+  const p = items.filter((x) => x?.outcome === 'proposed').length
+  const d = items.filter((x) => x?.outcome === 'deduped').length
+  const r = items.filter((x) => x?.outcome === 'rejected').length
+  return [`Obligations sent: ${items.length} — ${p} proposed, ${d} deduped, ${r} rejected:`, ...shown.map(line)]
+}
+
 /** PURE. The same, folded onto one line for a batch's per-unit detail. */
 export function filingObligationsBrief(o) {
   if (!o || typeof o !== 'object') return ''
@@ -91,6 +117,15 @@ export function filingObligationsBrief(o) {
   const bits = []
   if (o.sent === 0) bits.push('asks nothing')
   else if (o.write?.proposed) bits.push(`${o.write.proposed} obligation(s) proposed`)
-  if (Array.isArray(o.unverified) && o.unverified.length) bits.push(`⚠ ${o.unverified.length} quote(s) not in the text, not written`)
+  if (Array.isArray(o.items)) {
+    // 2026-10-23: name each one not written as sent, so a batch never hides which was dropped.
+    for (const x of o.items) {
+      if (x?.outcome === 'deduped') bits.push(`obligations[${x.index}] deduped (same sentence as ${x.against ?? 'another'})`)
+      if (x?.outcome === 'rejected') bits.push(`⚠ obligations[${x.index}] rejected: ${x.reason ?? 'refused'}`)
+    }
+  } else if (Array.isArray(o.unverified) && o.unverified.length) {
+    bits.push(`⚠ ${o.unverified.length} quote(s) not in the text, not written`)
+  }
+  if (o.write?.kept) bits.push(`${o.write.kept} already acted on, left as is`)
   return bits.length ? ` · ${bits.join(', ')}` : ''
 }

package/lib/folder_decisions.mjs

@@ -29,13 +29,16 @@ export function renderFolderQuestions(body) {
   if (open.length) {
     lines.push('', `Open (${open.length}):`)
     for (const x of open) {
-      const what = x.kind === 'file' ? `file in grab-bag \`${x.grabBag ?? '?'}\`` : `folder (${x.files?.length ?? 0} changed file${x.files?.length === 1 ? '' : 's'})`
+      const what = `folder (${x.files?.length ?? 0} changed file${x.files?.length === 1 ? '' : 's'})`
       lines.push(`- \`${x.identifier}\` — ${what}`)
       if (Array.isArray(x.answerWith) && x.answerWith.length > 1) {
         lines.push(`    may also be answered at: ${x.answerWith.slice(1).map((a) => `\`${a}\``).join(', ')}`)
       }
       if (x.earlier) {
-        lines.push(`    asked before: declined ${x.earlier.kind} on \`${x.earlier.identifier}\`${x.earlier.decidedBy ? ` by ${x.earlier.decidedBy}` : ''} ${String(x.earlier.decidedAt).slice(0, 10)} — "${x.earlier.reason ?? ''}". That decision has lapsed.`)
+        const why = x.earlier.kind === 'not_yet'
+          ? '"not yet" is no longer an answer for a GitHub folder — choose its page, or never.'
+          : 'That decision has lapsed.'
+        lines.push(`    asked before: declined ${x.earlier.kind} on \`${x.earlier.identifier}\`${x.earlier.decidedBy ? ` by ${x.earlier.decidedBy}` : ''} ${String(x.earlier.decidedAt).slice(0, 10)} — "${x.earlier.reason ?? ''}". ${why}`)
       }
     }
   }
@@ -44,11 +47,10 @@ export function renderFolderQuestions(body) {
     for (const p of pages) lines.push(`- ${q(p.title)} (${p.tier}) — ref ${p.ref}${p.tier !== 'accessible' ? ' — needs confirmTier: true' : ''}`)
   }
   if (open.length) {
-    const example = open.slice(0, 3).map((x) => (pages[0]
-      ? { identifier: x.identifier, claim: pages[0].ref }
-      : { identifier: x.identifier, decline: 'not_yet', reason: 'why it belongs to no page' }))
+    // Never a `never` in the example: it is permanent, so it must be typed on purpose, not copied.
+    const example = open.slice(0, 3).map((x) => ({ identifier: x.identifier, claim: pages[0]?.ref ?? '<ref of the page about this folder>' }))
     lines.push('', `Answer shape: folderDecisions: ${JSON.stringify(example)}`)
-    lines.push('No page fits? Author a small area page about the folder (`author`), then claim onto its ref. Generated/vendored/lockfiles/fixtures: decline "never".')
+    lines.push('No page fits? Author a small area page about the folder (`author`), then claim onto its ref. Belongs to no page (generated/vendored/lockfiles/fixtures)? {identifier, decline: "never", reason} — permanent until someone claims it. There is no "not yet".')
     if (body?.cold) lines.push('You are a cold judge here: {identifier, defer: true} hands a question to the next session that touches it.')
   }
   return lines.join('\n')
@@ -73,7 +75,10 @@ export function renderDeclines(declines, { heading = 'Declines' } = {}) {
   if (!list.length) return []
   const lines = [`${heading} (${list.length}) — a decline covers the identifier and everything under it:`]
   for (const d of list) {
-    const state = d.active ? (d.kind === 'never' ? 'never' : d.kind === 'not_yet' ? 'not yet' : 'snoozed') : `${d.kind}, lapsed — will be asked again`
+    const retiredPath = d.kind === 'not_yet' && String(d.identifier).startsWith('file:')
+    const state = retiredPath
+      ? 'not yet — retired for GitHub paths, asked again at the next commit there'
+      : d.active ? (d.kind === 'never' ? 'never' : d.kind === 'not_yet' ? 'not yet' : 'snoozed') : `${d.kind}, lapsed — will be asked again`
     lines.push(`  ${d.active ? '⊘' : '·'} \`${d.identifier}\`${d.brain ? ` · ${d.brain}` : ''} — ${state}${d.reason ? ` — "${d.reason}"` : ''}${d.decidedBy ? ` · ${d.decidedBy}` : ''}${d.cold ? ' (cold judge)' : ''} · ${String(d.decidedAt).slice(0, 10)}`)
   }
   return lines

package/lib/intake_batch_render.mjs

@@ -24,3 +24,15 @@ export function renderConversationOffer(x, why = '', looked = '') {
   return `    - 📱 ${x.conversation.count} texts in one conversation · newest ${x.hoursAgo}h ago · ${ids}${why}${looked}\n` +
     '      decide them together: `intake_look` the newest, `intake_claim` them all, then file them in one `intake_materialize` (intakeItemIds) — one record each'
 }
+
+/**
+ * A batch PREVIEW (2026-10-23), per id: until then a preview with intakeItemIds covered only the first id, so
+ * the other units' obligations were never checked and nothing said so. Each unit is previewed on its own call
+ * with its own obligations; `line` is that unit's rendered preview. Nothing is written by any of them.
+ */
+export function renderPreviewBatch(results) {
+  const refuse = results.filter((r) => !r.ok || r.wouldApply === false)
+  return `PREVIEW of a batch of ${results.length} — nothing was written. ` +
+    `${results.length - refuse.length} would file as sent, ${refuse.length} would not.\n` +
+    results.map((r) => `\n── ${r.id}\n${r.ok ? r.line : `✗ preview failed — ${r.detail}`}`).join('\n')
+}

package/lib/locked_tools.mjs

@@ -22,7 +22,7 @@ export const REGULAR_ONLY_TOOLS = [
   'list_records', 'read_record', 'timeline_pull', 'record_status', 'set_record_notes', 'set_record_privacy',
   'relabel_record_people', 'supersede_record', 'move_record', 'contain_record', 'pending_records', 'claim_record',
   'route_record', 'unroute_record', 'request_file', 'get_file', 'create_custom_source', 'search_spam_email',
-  'gmail_modify', 'draft_email_reply', 'request_send_email', 'send_imessage', 'create_brain', 'add_to_brain',
+  'gmail_modify', 'draft_email_reply', 'request_send_email', 'send_imessage', 'add_to_brain',
 ]
 
 /** What a locked tool answers when the check itself could not be made. Nothing was run. */

package/lib/server.mjs

@@ -24,9 +24,9 @@ import { spawnObligationWorker } from './obligations_worker.mjs'
 import { renderObligations, renderPageObligations, tierReads, who } from './obligations_render.mjs'
 import { renderLeaveQuestion, renderLeft, renderRemovalQuestion, renderRemoved } from './member_remove_render.mjs'
 import { renderSettings } from './settings_render.mjs'
-import { renderConversationOffer, renderMaterializeBatch } from './intake_batch_render.mjs'
+import { renderConversationOffer, renderMaterializeBatch, renderPreviewBatch } from './intake_batch_render.mjs'
 import { intakeIdFrom, requireIntakeId, INTAKE_ID_ALIAS_NOTE } from './intake_id_alias.mjs'
-import { obligationsForUnits, renderFilingObligations, filingObligationsBrief, OBLIGATIONS_UNANSWERED_TEXT } from './filing_obligations.mjs'
+import { obligationsForUnits, renderFilingObligations, renderObligationItems, filingObligationsBrief, OBLIGATIONS_UNANSWERED_TEXT } from './filing_obligations.mjs'
 import { renderRecord, READ_RECORD_DEFAULT_CHARS, READ_RECORD_PARTS } from './record_render.mjs'
 import { formatCreated, formatDryRun, formatSources, homeFromArgs, pickSource, renderHomeProblem } from './custom_sources.mjs'
 import { formatSeriesRefusal, formatSeriesUpdated } from './series_render.mjs'
@@ -183,7 +183,26 @@ export function renderIntakePreviewLine(body) {
   const pages = Array.isArray(p.pages) ? p.pages.length : 0
   const g = p.governing
   const gov = g ? `${g.title || g.kind} (${g.tier})${p.governingJudged ? ', your choice' : ''}` : 'none'
-  return `PREVIEW — nothing was written. Would attach ${pages} page(s); governing: ${gov}; born ${p.tier ?? 'unknown'}.`
+  const lines = [`PREVIEW — nothing was written. Would attach ${pages} page(s); governing: ${gov}; born ${p.tier ?? 'unknown'}.`]
+  // 2026-10-23: whether apply would take THIS body, and what it would do with each answer sent. Every line
+  // below is printed only when the server sent its field, so an older server renders exactly as before.
+  if (body?.wouldApply === false && Array.isArray(body.applyWouldRefuse)) {
+    for (const r of body.applyWouldRefuse) lines.push(`⚠ apply would REFUSE this call: ${r?.error}${r?.detail ? ` — ${r.detail}` : ''}`)
+  } else if (body?.wouldApply === true) {
+    lines.push('Apply would accept this call as sent.')
+  }
+  const fd = body?.folderDecisions
+  if (fd && Array.isArray(fd.answers)) {
+    const ok = fd.answers.filter((a) => a.verdict === 'accepted')
+    const bad = fd.answers.filter((a) => a.verdict === 'rejected')
+    const open = Array.isArray(fd.open) ? fd.open : []
+    lines.push(`Folder answers: ${ok.length} accepted, ${bad.length} rejected; ${open.length} question(s) still open.`)
+    for (const a of ok) lines.push(`  ✓ folderDecisions[${a.index}] ${a.action} \`${a.identifier}\`${a.page ? ` onto "${a.page.title}" (${a.page.tier})` : ''} — answers ${(a.answers ?? []).length}`)
+    for (const a of bad) lines.push(`  ✗ folderDecisions[${a.index}] ${a.action ?? '?'} \`${a.identifier ?? '?'}\` — ${a.error}${a.detail ? `: ${a.detail}` : ''}`)
+    for (const q of open) lines.push(`  ? still open: \`${q.identifier}\``)
+  }
+  lines.push(...renderObligationItems(body?.obligations?.items))
+  return lines.join('\n')
 }
 
 // TOP-OF-PAGE NOTES — ADR-0065's size note, and ADR-0064 §3's "Also visible to you" callout.
@@ -1304,12 +1323,12 @@ function renderNudge(payload) {
     {
       title: 'Materialize a private intake item',
       description:
-        'Atomically publish a claimed intake item into one brain — the disclosure moment (ADR-0062). Deterministic identifier homes in that brain are always attached; documentIds may add further pages. The record is born at the strictest of its source baseline, what the producer asked for, and every attached page; a source floor (iMessage, claude-code) pins it. ' +
-        'Name the governing page with governingPage (one of documentIds, never a person page) — otherwise the ranking picks it. ' +
-        'Pass mode "preview" first when your choice differs from the claim\'s proposal: it returns the pages, the governing page and the tier this exact call would produce, and writes nothing. Never writes private intake into search/history before this call. ' +
-        '⚠ ADR-0051 — BEFORE you file, look for this unit\'s OTHER homes: the pages it is about beyond what an identifier matched (the design it implements, the project, the person, the decision it bears on). grep or read for them, then name them in documentIds. A call that names nothing beyond the deterministic homes still FILES, on those homes only, and says so — add pages later with route_record. ' +
-        '⚠ A meeting or lecture TRANSCRIPT files with NOTES in `summary` (Theron, 2026-10-08): the gist, decisions, action items and dates, names spelled right. Without them the call is REFUSED; the transcript itself is kept on the record unchanged. ' +
-        '⚠ ADR-0077: a GitHub commit or PR does not finish until every changed path has an answer. If a changed file\'s deepest folder (or, in a grab-bag folder like web/lib/engine/ or db/supabase/, the file itself) has no claim and no decline, the call is REFUSED with the open questions; answer each in folderDecisions and call again.',
+        'Atomically publish a claimed intake item into one brain — the disclosure moment (ADR-0062). Deterministic identifier homes there are always attached; documentIds add pages. The record is born at the strictest of its source baseline, the producer\'s ask and every attached page; a source floor (iMessage, claude-code) pins it. ' +
+        'Name the governing page with governingPage (one of documentIds, never a person page), else the ranking picks it. ' +
+        'Pass mode "preview" when your choice differs from the proposal: it returns the pages, governing page and tier this exact call would produce, whether apply would accept it (folderDecisions and obligations included), and writes nothing. Never writes private intake into search/history before this call. ' +
+        '⚠ ADR-0051 — BEFORE you file, look for this unit\'s OTHER homes: the pages it is about beyond what an identifier matched (the design, project, person or decision). grep or read for them and name them in documentIds. A call naming nothing beyond the deterministic homes still FILES on those only, and says so — add pages later with route_record. ' +
+        '⚠ A meeting or lecture TRANSCRIPT files with NOTES in `summary`: gist, decisions, action items, dates, names spelled right — else REFUSED; the transcript is kept unchanged. ' +
+        '⚠ ADR-0077: a GitHub commit or PR does not finish until every changed AREA FOLDER has an answer; unanswered, the call is REFUSED with the open questions. Answer each in folderDecisions (a page to claim it onto, or decline "never") and call again. A "never" on a folder also silences every unclaimed subfolder beneath it, so use it only when nothing under that folder deserves its own page. An earlier "not_yet" (`earlier`) no longer answers a GitHub folder question: claim the folder onto a page about it, or decline "never". A file directly in a grab-bag folder (e.g. db/supabase/) is never asked about.',
       inputSchema: {
         intakeItemId: z.string().optional().describe('intake item uuid (required — intake_item_id is accepted too)'),
         intake_item_id: z.string().optional().describe(INTAKE_ID_ALIAS_NOTE),
@@ -1318,7 +1337,7 @@ function renderNudge(payload) {
           'Any units you hold a live claim on may be batched, even from separate intake_claim calls — except that texts from ' +
           'DIFFERENT text conversations never share a batch. Claim them with `intake_claim`, then pass ' +
           'the first as intakeItemId and the rest here. title/summary/dedupeKey are ignored in a batch (each unit keeps its ' +
-          'own), and a preview covers intakeItemId only. Each id is reported separately; a failure never hides behind a success.',
+          'own), and a preview covers every id, each with its own obligations. Each id is reported separately; a failure never hides behind a success.',
         ),
         orgId: z.string().describe('destination brain org uuid'),
         documentIds: z.array(z.string()).optional().describe('additional pages in orgId — each a page TITLE exactly as read_page shows it, its `ref:`, or a brain_documents id (deterministic homes are merged automatically). A title that matches no page, or more than one, is refused with the candidates listed'),
@@ -1347,12 +1366,12 @@ function renderNudge(payload) {
         folderDecisions: z.array(z.object({
           identifier: z.string().describe('the open question\'s identifier, or a folder above it that its answerWith lists'),
           claim: z.string().optional().describe('page `ref:` (or document id) of a project page ABOUT this path — never the repo\'s mother page, a person or a user page'),
-          decline: z.enum(['never', 'not_yet']).optional().describe('never = generated/build output, lockfiles, fixtures, vendored code; not_yet = asked again after 10 more commits or 90 days'),
+          decline: z.enum(['never']).optional().describe('never = belongs to no page (generated/build output, lockfiles, fixtures, vendored code). Permanent until someone claims the folder onto a page. There is no "not yet" for a GitHub folder: pick the page it is about, or never'),
           reason: z.string().optional().describe('required with decline: why it belongs to no page — the next session asked will read it'),
           defer: z.boolean().optional().describe('cold judges only (a cleanup lease): hand the question to the next session that touches it'),
           confirmTier: z.boolean().optional().describe('required to claim onto a page narrower than accessible — its tier will govern every future commit there'),
         })).optional().describe(
-          'ADR-0077: one answer per open folder question from a refused call — exactly one of claim, decline or defer each. ' +
+          'ADR-0077: one answer per open folder question from a refused call — exactly one of claim, decline ("never") or defer (cold judges only) each. ' +
           'Send only after the server has listed the questions; claims and declines are written when the unit is filed.',
         ),
         obligations: z.array(z.object({
@@ -1382,6 +1401,43 @@ function renderNudge(payload) {
       const ob = obligationsForUnits(batch, args.obligations)
       if (ob.errors.length) return toolError(`Nothing was filed — fix these obligations first:\n${ob.errors.map((e) => `  · ${e}`).join('\n')}`)
       const obligationsFor = (id) => (ob.byUnit ? { obligations: ob.byUnit.get(id) ?? [] } : {})
+      // A BATCH PREVIEW (2026-10-23): every id, each on its own preview call with ITS OWN obligations — the
+      // same body the batch apply below sends, so what it reports is what apply would do. Until then a preview
+      // covered intakeItemId only, and the other units' obligations were silently never checked.
+      if (batch.length > 1 && args.mode === 'preview') {
+        const results = []
+        for (const id of batch) {
+          try {
+            const r = await fetchCortex(`${BASE}${intakeMaterializePath('preview')}`, {
+              method: 'POST',
+              headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+              body: JSON.stringify({
+                intakeItemId: id,
+                orgId: args.orgId,
+                documentIds: args.documentIds ?? [],
+                record: { source: args.source, record_type: args.recordType },
+                attachmentMeta: (args.documentIds ?? []).map(() => ({ origin: args.origin ?? 'llm' })),
+                ...(args.governingPage ? { governingDocumentId: args.governingPage } : {}),
+                ...(args.searchedForOtherHomes ? { searchedForOtherHomes: true } : {}),
+                sameBatchAs: batch[0],
+                ...obligationsFor(id),
+              }),
+            })
+            const o = await r.json().catch(() => null)
+            if (r.status === 404 && !o?.error) {
+              results.push({ id, ok: false, detail: 'this server cannot preview a materialization yet — nothing was written' })
+            } else if (!r.ok) {
+              results.push({ id, ok: false, detail: `${o?.error ?? `HTTP ${r.status}`}${o?.hint ? ` — ${o.hint}` : o?.detail ? ` — ${o.detail}` : ''}` })
+            } else {
+              results.push({ id, ok: true, wouldApply: o?.wouldApply, line: renderIntakePreviewLine(o), body: o })
+            }
+          } catch (e) {
+            results.push({ id, ok: false, detail: e.message })
+          }
+        }
+        const notes = ob.notes.length ? `\n${ob.notes.map((n) => `⚠ ${n}`).join('\n')}` : ''
+        return { content: [{ type: 'text', text: `${renderPreviewBatch(results)}${notes}\n\n${JSON.stringify(results.map((r) => r.body ?? { id: r.id, error: r.detail }), null, 2)}` }] }
+      }
       if (batch.length > 1 && args.mode !== 'preview') {
         const results = []
         for (const id of batch) {
@@ -2714,7 +2770,7 @@ function renderNudge(payload) {
         brain: z.string().optional().describe('which brain to stop surfacing it in. Required when you belong to more than one — the call refuses rather than picking.'),
         days: z.number().optional().describe('how long to stay quiet (1-365, default 90).'),
         reason: z.string().optional().describe('why it belongs nowhere, in one phrase — the next person to see it resurface will want this. REQUIRED with kind.'),
-        kind: z.enum(['never', 'not_yet']).optional().describe('ADR-0077: record a DECLINE instead of silencing the notice. never = generated/build output, lockfiles, fixtures, vendored code (a cold judge — a session holding cleanup leases — may not write it); not_yet = asked again after 10 more commits touch it or 90 days. A decline covers the identifier and everything under it, and claiming the identifier clears it.'),
+        kind: z.enum(['never', 'not_yet']).optional().describe('ADR-0077: record a DECLINE instead of silencing the notice. never = generated/build output, lockfiles, fixtures, vendored code (a cold judge — a session holding cleanup leases — may not write it); not_yet = asked again after 10 more commits touch it or 90 days — NOT for a GitHub path (file:…), which takes a page or never (2026-10-22). A decline covers the identifier and everything under it, and claiming the identifier clears it.'),
         remove: z.boolean().optional().describe('ADR-0077: UN-decline — delete the decline (or snooze) on this identifier, so the next commit that touches it is asked again.'),
       },
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theronap/agnoclast-mcp",
-  "version": "0.9.256",
+  "version": "0.9.258",
   "description": "Connect your AI assistant to Cortex — your org's projects, activity, gaps, and directives, scoped to you.",
   "type": "module",
   "bin": {