@theronap/agnoclast-mcp 0.9.211 → 0.9.212

package/lib/diagnose.mjs

@@ -414,7 +414,9 @@ async function fetchCortexOnce(url, opts = {}, policy = {}) {
     sleep: sleepFn = sleep, random = Math.random, now = Date.now,
   } = policy
   const { timeoutMs: optTimeout, signal: callerSignal, ...rest } = opts
-  const baseHeaders = { ...(rest.headers ?? {}), 'x-cortex-client': CLIENT_ID }
+  // x-cortex-tool: the tool this request is for (the running one, else the path map) — the server
+  // counts calls per tool for staff usage stats (api_requests). A name only; arguments never travel.
+  const baseHeaders = { ...(rest.headers ?? {}), 'x-cortex-client': CLIENT_ID, 'x-cortex-tool': toolForUrl(url) }
   const fetchOpts = SESSION_KEY
     ? { ...rest, headers: { ...baseHeaders, 'x-cortex-session-key': SESSION_KEY } }
     : { ...rest, headers: baseHeaders }

package/lib/folder_decisions.mjs

@@ -0,0 +1,80 @@
+// THE FORCED FOLDER QUESTION AND THE DECLINE LIST — pure renderers (ADR-0077, 2026-10-05).
+//
+// The server refuses to file a GitHub unit until every changed path has an answer. The refusal is only
+// useful if the judge can answer it in ONE more call, so this prints every open question with what it
+// accepts, the candidate pages (and their tiers), any earlier decision being re-asked, and a
+// ready-to-edit `folderDecisions` value. Pure so CI can execute exactly what each refusal prints.
+
+const q = (s) => `"${s}"`
+
+/** The refusal text for a 409/400/403 from intake_materialize carrying ADR-0077 questions. */
+export function renderFolderQuestions(body) {
+  const lines = []
+  const questions = Array.isArray(body?.questions) ? body.questions : []
+  const pages = Array.isArray(body?.candidatePages) ? body.candidatePages : []
+  const head = {
+    folder_decisions_required: 'Not filed yet — these paths have no page and no decision. Answer each, then call again with folderDecisions.',
+    claim_tier_unconfirmed: 'Not filed yet — that page is narrower than accessible.',
+    folder_defer_not_allowed: 'Not filed yet — only a cold judge may defer.',
+    decline_never_needs_working_session: 'Not filed yet — a cold judge may not decline "never".',
+    folder_decision_unmatched: 'Not filed yet — an answer matched no open question.',
+    folder_claim_on_mother_page: 'Not filed yet — that is the repo\'s mother page.',
+    folder_claim_not_a_project_page: 'Not filed yet — code belongs on a project page.',
+    folder_claim_page_unresolved: 'Not filed yet — that page could not be resolved.',
+  }[body?.error] ?? `Not filed yet — ${body?.error ?? 'folder decision refused'}.`
+  lines.push(head)
+  if (typeof body?.detail === 'string') lines.push(body.detail)
+  if (body?.page?.tier) lines.push(`Page: ${q(body.page.title)} (${body.page.tier}) — ref ${body.page.ref}`)
+  const open = questions.filter((x) => !x.answered)
+  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'})`
+      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.`)
+      }
+    }
+  }
+  if (pages.length) {
+    lines.push('', 'Pages this unit is being filed onto (candidates — only if a page is ABOUT the folder):')
+    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' }))
+    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".')
+    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')
+}
+
+/** intake_materialize success: what the answers did. [] when nothing was asked. */
+export function renderFolderDecisionsApplied(fd) {
+  const applied = Array.isArray(fd?.applied) ? fd.applied : []
+  if (!applied.length) return []
+  const lines = [`Folder decisions applied (${applied.length}):`]
+  for (const op of applied) {
+    if (op.action === 'claim') lines.push(`  - claimed \`${op.identifier}\` onto ${q(op.page)} (${op.tier})`)
+    else if (op.action === 'decline') lines.push(`  - declined ${op.kind} \`${op.identifier}\` — "${op.reason}"`)
+    else lines.push(`  - deferred \`${op.identifier}\` to the next session that touches it`)
+  }
+  return lines
+}
+
+/** my_routing_claims / read_page: the declines, as lines. [] when there are none (or the server is older). */
+export function renderDeclines(declines, { heading = 'Declines' } = {}) {
+  const list = Array.isArray(declines) ? 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`
+    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/identifier_routes.mjs

@@ -10,6 +10,8 @@
 //
 // Pure so CI can execute what each state prints.
 
+import { renderDeclines } from './folder_decisions.mjs'
+
 const q = (s) => `"${s}"`
 const pageLabel = (h) => `${q(h.title)} (${h.kind}, ${h.tier})`
 
@@ -56,6 +58,8 @@ export function renderIdentifierResolution(out, { expand = false } = {}) {
   if (mentions.length) {
     lines.push(`Mentioned on (does not route): ${mentions.map((h) => q(h.title)).join(', ')}`)
   }
+  // ADR-0077: a decline on it or a folder above it decides whether a commit is ASKED about it.
+  lines.push(...renderDeclines(out.declines, { heading: 'Declined' }))
   const ev = out.events ?? { visibleCount: 0, recent: [] }
   lines.push(`· ${ev.visibleCount} tagged timeline event${ev.visibleCount === 1 ? '' : 's'} visible to you${ev.recent?.length ? ':' : expand ? '.' : ' — pass expand: true to list recent ones.'}`)
   for (const e of ev.recent ?? []) lines.push(`  - ${String(e.occurredAt).slice(0, 10)} · ${e.source} · ${e.summary}`)

package/lib/server.mjs

@@ -10,6 +10,7 @@ import { fetchCortex, classify, resolveBase, resolveEnvToken, setSessionKey, set
 import { REPORT_KINDS, REPORT_ISSUE_DESCRIPTION, fileIssue } from './report_issue.mjs'
 import { folderClaimLine } from './folder_claims.mjs'
 import { renderFolderClaimOffers, renderIdentifierResolution, renderUnroutedPathStamps } from './identifier_routes.mjs'
+import { renderDeclines, renderFolderDecisionsApplied, renderFolderQuestions } from './folder_decisions.mjs'
 import { resolveSessionKey, resolveLogSessionId } from './session_key.mjs'
 import { runSendImessage } from './imessage_send.mjs'
 import { formatGrepHits } from './grep_cli.mjs'
@@ -1225,7 +1226,8 @@ function renderNudge(payload) {
         '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: a unit does not finish until you looked for its OTHER homes. A call whose documentIds add nothing beyond the deterministic homes it gets anyway is REFUSED once — name the pages this unit is about (the design it implements, the project, the person), or go look, or say you looked with searchedForOtherHomes.',
+        '⚠ ADR-0051: a unit does not finish until you looked for its OTHER homes. A call whose documentIds add nothing beyond the deterministic homes it gets anyway is REFUSED once — name the pages this unit is about (the design it implements, the project, the person), or go look, or say you looked with searchedForOtherHomes. ' +
+        '⚠ 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.',
       inputSchema: {
         intakeItemId: z.string().describe('intake item uuid'),
         orgId: z.string().describe('destination brain org uuid'),
@@ -1250,6 +1252,17 @@ function renderNudge(payload) {
           'looking, not a way past the question. Measured 2026-09-25: 30 records filed through this verb in one afternoon with no ' +
           'judged page on any of them.',
         ),
+        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'),
+          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. ' +
+          'Send only after the server has listed the questions; claims and declines are written when the unit is filed.',
+        ),
       },
     },
     async (args) => {
@@ -1273,10 +1286,18 @@ function renderNudge(payload) {
           attachmentMeta: (args.documentIds ?? []).map(() => ({ origin: args.origin ?? 'llm' })),
           ...(args.governingPage ? { governingDocumentId: args.governingPage } : {}),
           ...(args.searchedForOtherHomes ? { searchedForOtherHomes: true } : {}),
+          ...(args.folderDecisions?.length ? { folderDecisions: args.folderDecisions } : {}),
         }),
       })
       if (!res.ok) {
         const body = await res.text()
+        // ADR-0077: the forced folder question. Every refusal from it carries the open questions, so
+        // print them in a form the judge can answer in ONE more call.
+        {
+          let parsed = null
+          try { parsed = JSON.parse(body) } catch { /* not JSON */ }
+          if (parsed && Array.isArray(parsed.questions)) return toolError(renderFolderQuestions(parsed))
+        }
         if (res.status === 409) {
           let err = null
           try { err = JSON.parse(body)?.error } catch { /* not JSON: fall through to the raw text */ }
@@ -1346,6 +1367,7 @@ function renderNudge(payload) {
       // did not happen, which is exactly the silence this whole path exists to remove.
       // ADR-0075 — the deepest unclaimed folder this unit sits in, offered for the feature page it was
       // filed onto. Never claimed by the server; the session decides.
+      lines.push(...renderFolderDecisionsApplied(body?.folderDecisions))
       lines.push(...renderFolderClaimOffers(body?.folderClaimOffers))
       if (body?.containerSkipped) {
         lines.push(`⚠ CONTAINER NOT APPLIED — ${body.containerSkipped}. The record exists but is not inside the event you named; place it with contain_record or leave it out.`)
@@ -2427,22 +2449,27 @@ function renderNudge(payload) {
   server.registerTool(
     'snooze_routing_claim',
     {
-      title: 'Stop surfacing one unclaimed source',
+      title: 'Decline an unclaimed source or path (never / not yet), or stop surfacing it',
       description: "Silence one identifier in the `Sources nothing has claimed` block at session start. Use it when a recurring source genuinely belongs nowhere — a scratch repo, a bot channel, someone else's project that happens to cc you. NOT for something you simply have not got to yet: that is what leaving it alone does. A snooze silences the NOTICE and routes nothing; the events keep landing exactly where they land today. The block already has a volume floor that keeps one-off identifiers out, so anything you see there is recurring by construction — which is precisely why no threshold can tell 'not yet decided' from 'decided: nowhere', and why this exists. Bounded to at most a year and defaulting to 90 days, because a repo that was noise in August may be the centre of the work by November. Identity namespaces (`email:`, `thread:`) are refused: they are never surfaced as claimable in the first place, so there is nothing to snooze.",
       inputSchema: {
         identifier: z.string().describe('the identifier exactly as the context block prints it, e.g. `repo:owner/name`'),
         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.'),
+        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.'),
+        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.'),
       },
     },
-    async ({ identifier, brain, days, reason }) => {
+    async ({ identifier, brain, days, reason, kind, remove }) => {
       let res
       try {
         res = await fetchCortex(`${BASE}/api/brain/snooze-routing-claim`, {
           method: 'POST',
           headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
-          body: JSON.stringify({ identifier, ...(brain ? { brain } : {}), ...(days ? { days } : {}), ...(reason ? { reason } : {}) }),
+          body: JSON.stringify({
+            identifier, ...(brain ? { brain } : {}), ...(days ? { days } : {}), ...(reason ? { reason } : {}),
+            ...(kind ? { kind } : {}), ...(remove ? { remove: true } : {}),
+          }),
         })
       } catch (e) {
         return toolError(`Could not snooze ${identifier}: ${e.message}`)
@@ -2453,7 +2480,10 @@ function renderNudge(payload) {
         const hint = out?.hint ? `\n${out.hint}` : ''
         return toolError(`Could not snooze ${identifier}: ${out?.error ?? res.status}${extra}${hint}`)
       }
-      return { content: [{ type: 'text', text: `${out.note}\nIf it should route somewhere after all, \`set_routing_identifier\` on the owning page overrides this — a claim always beats a snooze.` }] }
+      if (kind && !out?.kind) {
+        return toolError(`This server cannot record a ${kind} decline yet (it stored a plain snooze instead). Re-run after the server updates.`)
+      }
+      return { content: [{ type: 'text', text: `${out.note}\nIf it should route somewhere after all, \`set_routing_identifier\` on the owning page overrides this — a claim always beats a decline, and clears it.` }] }
     },
   )
 
@@ -3844,7 +3874,7 @@ function renderNudge(payload) {
       if (!res.ok) return toolError(`Could not read routing claims: ${out?.error ?? res.status}${out?.hint ? `\n${out.hint}` : ''}`)
 
       const groups = Array.isArray(out?.identifiers) ? out.identifiers : []
-      if (groups.length === 0) {
+      if (groups.length === 0 && !(Array.isArray(out?.declines) && out.declines.length)) {
         return { content: [{ type: 'text', text: 'No routing claims you can see. Nothing you own decides a brain for any identifier, so inbound mail resolves by nothing and stages.' }] }
       }
       const lines = []
@@ -3858,6 +3888,9 @@ function renderNudge(payload) {
           lines.push(`    ${c.brain} · ${page}${c.mine ? '' : ' · claimed by someone else'} · ${c.source} · ${String(c.createdAt).slice(0, 10)}`)
         }
       }
+      // ADR-0077: declines beside claims.
+      const declineLines = renderDeclines(out?.declines)
+      if (declineLines.length) lines.push('', ...declineLines)
       lines.push('')
       lines.push('— Exactly one brain routes. Zero or several STAGE, and a real message carries several identifiers, so one clean sender can still stage on another key it carries.')
       lines.push('— Before adding a claim: a second brain on the same identifier converts routing into staging. Claim the NARROWEST key the message carries (a repo or package), not the account it came from.')

package/package.json

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