@theronap/agnoclast-mcp 0.9.150 → 0.9.152

package/lib/server.mjs

@@ -78,6 +78,55 @@ export const sectionCurrencyStamp = (s, day) => {
 // invisible on exactly the sections that were healthy.
 export const renderSection = (s, day) => `### ${s.heading}${sectionCurrencyStamp(s, day)}\n${s.body}`
 
+/**
+ * ADR-0062 §5.1. A materialize PREVIEW goes to its own route: a server too old to know it answers 404,
+ * where /api/intake/materialize would ignore a `mode` it does not know and publish.
+ */
+export function intakeMaterializePath(mode) {
+  return mode === 'preview' ? '/api/intake/preview' : '/api/intake/materialize'
+}
+
+/** ADR-0062 §5.2. Which page governs a materialized record, and who chose it — or '' for an older server. */
+export function renderGoverningLine(governing) {
+  if (!governing || typeof governing !== 'object') return ''
+  const name = governing.title || 'a page'
+  const who = governing.designatedBy === 'session' ? 'chosen by you'
+    : governing.designatedBy === 'human' ? 'chosen by a person'
+    : 'chosen by the ranking — pass governingPage to decide it yourself'
+  return `Governed by ${name} (${governing.tier}) — ${who}.`
+}
+
+/** The one line a preview leads with, so it cannot be mistaken for a publish. */
+export function renderIntakePreviewLine(body) {
+  const p = (body && typeof body === 'object' && body.placement) || {}
+  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'}.`
+}
+
+// TOP-OF-PAGE NOTES — ADR-0065's size note, and ADR-0064 §3's "Also visible to you" callout.
+//
+// ⚠ PRINTED VERBATIM, NEVER COMPOSED HERE. The server decides whether a note fires and what it says
+// (`headerNotes` on /api/brain/page), so changing a threshold or a sentence is a deploy, not an npm release
+// plus a desktop pin bump. An older server sends no field, and this prints nothing.
+//
+// ⚠ AT THE TOP, NOT IN THE FOOTER. Claude Code saves an over-cap tool result to a file and the agent reads
+// it from offset 0, so the footer of a huge page is the part nobody reaches — and these notes exist for
+// exactly those pages. Shared by read_page and project_status so the two cannot drift, which is how every
+// earlier fix to this file's page rendering landed on one surface and not the other.
+// v1 SCOPE (Theron, 2026-09-16): page splitting moves to v2 and the server refuses it with
+// `splitting_unavailable`. split_page is not registered, so agents do not see a verb that can only refuse.
+// The definition stays for v2: flip this together with the server's SPLITTING_AVAILABLE.
+export const SPLIT_PAGE_TOOL_AVAILABLE = false
+
+export const renderHeaderNotes = (notes) => {
+  const lines = (Array.isArray(notes) ? notes : [])
+    .filter((n) => typeof n === 'string' && n.trim() !== '')
+    .map((n) => n.replace(/\s*\n\s*/g, ' ').trim())
+  return lines.length ? `\n\n${lines.join('\n')}` : ''
+}
+
 // gate5_status's transport half, pulled out of the tool handler so it can be exercised directly rather
 // than only string-matched (gate5_status_transport.drift.test.mjs). Takes the raw fetch Response from
 // /api/gates/5/status; the registerTool callback's only remaining job is fetching it. Same three
@@ -860,7 +909,8 @@ function renderNudge(payload) {
     {
       title: 'Claim private intake items',
       description:
-        'Claim a lease on private intake items (relevance or cleanup). Returns decrypted payloads for the lease holder only. Requires x-cortex-session-key (set automatically by this MCP server). Aged work never blocks a claim: the response reports cleanupDueCount and how far behind the oldest unit is, and servicing it is expected but always your call. Claiming is a commitment to process — hand back anything you will not finish with intake_release, or intake_defer if it is the owner\'s decision to make.',
+        'Claim a lease on private intake items (relevance or cleanup). Returns decrypted payloads for the lease holder only. Requires x-cortex-session-key (set automatically by this MCP server). Aged work never blocks a claim: the response reports cleanupDueCount and how far behind the oldest unit is, and servicing it is expected but always your call. Claiming is a commitment to process — hand back anything you will not finish with intake_release, or intake_defer if it is the owner\'s decision to make. ' +
+        'YOU ARE THE JUDGE of every unit you claim (ADR-0062): nothing is published until you materialize, and materializing is when it becomes visible. Each unit carries a `proposal` — the brain its signals point to and, for that brain, the pages it would attach to, the page that would govern it, and the `tier` it would be born with — computed without writing anything. Decide the brain, the pages (confirm, drop or add), which page should govern (the page whose reasons for restricting its audience fit the content, not a person page), and obligations. Pages only tighten a tier; if a record should be LOOSER than `tierReason.baseline`, that is the owner\'s call — intake_defer with the question.',
       inputSchema: {
         claimKind: z.enum(['relevance', 'cleanup']).optional().describe('default relevance'),
         limit: z.number().optional().describe('max items (default 10). Ignored when intakeItemIds is given.'),
@@ -930,7 +980,9 @@ function renderNudge(payload) {
     {
       title: 'Materialize a private intake item',
       description:
-        'Atomically publish a claimed intake item into one brain. Deterministic identifier homes in that brain are always attached; documentIds may add further pages. Sets record confidentiality to the strictest attached page tier. Never writes private intake into search/history before this call.',
+        '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.',
       inputSchema: {
         intakeItemId: z.string().describe('intake item uuid'),
         orgId: z.string().describe('destination brain org uuid'),
@@ -941,10 +993,21 @@ function renderNudge(payload) {
         recordType: z.string().optional(),
         dedupeKey: z.string().optional(),
         origin: z.enum(['deterministic', 'llm', 'user', 'session']).optional(),
+        governingPage: z.string().optional().describe(
+          'the page that should GOVERN this record (ADR-0062) — a page `ref:` or document id, and one of documentIds. ' +
+          'Choose the page whose reasons for restricting its audience fit the content; never a person page. It can only ' +
+          'tighten the record, and the ranking will not move it. Omit to leave the choice to the ranking.',
+        ),
+        mode: z.enum(['preview', 'apply']).optional().describe(
+          '"preview": report the pages, governing page and tier this call would produce, and write nothing. Default "apply".',
+        ),
       },
     },
     async (args) => {
-      const res = await fetchCortex(`${BASE}/api/intake/materialize`, {
+      // A preview goes to its OWN route: a server too old to know it answers 404, where the materialize
+      // route would ignore a `mode` it does not know and publish.
+      const preview = args.mode === 'preview'
+      const res = await fetchCortex(`${BASE}${intakeMaterializePath(args.mode)}`, {
         method: 'POST',
         headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
         body: JSON.stringify({
@@ -959,13 +1022,20 @@ function renderNudge(payload) {
             dedupe_key: args.dedupeKey,
           },
           attachmentMeta: (args.documentIds ?? []).map(() => ({ origin: args.origin ?? 'llm' })),
+          ...(args.governingPage ? { governingDocumentId: args.governingPage } : {}),
         }),
       })
       if (!res.ok) {
         const body = await res.text()
+        if (preview && res.status === 404) {
+          return toolError('This server cannot preview a materialization yet — nothing was written. Materialize without mode, or wait for the server to update.')
+        }
         return toolError(body)
       }
       const body = await res.json()
+      if (preview) {
+        return { content: [{ type: 'text', text: `${renderIntakePreviewLine(body)}\n\n${JSON.stringify(body, null, 2)}` }] }
+      }
       // WHERE THE SESSION'S OWN WORK LANDED, in words rather than buried in the JSON dump.
       //
       // Three outcomes that look identical in raw JSON and mean completely different things:
@@ -982,6 +1052,8 @@ function renderNudge(payload) {
       // the ordinary case (observed 2026-09-03 on the first handoff record materialised). Silence is
       // correct here, and it also covers a server too old to send the field at all.
       const lines = []
+      const governingLine = renderGoverningLine(body?.governing)
+      if (governingLine) lines.push(governingLine)
       const sa = body?.sessionAttachments
       if (sa === null) {
         lines.push('⚠ Session-page attachment FAILED for this record — it was written, but not filed under the pages this session worked on. Re-run the reconciler.')
@@ -1348,7 +1420,7 @@ function renderNudge(payload) {
           return [head, secs].filter(Boolean).join('\n')
               })
               const brainTag = matches.length > 1 ? ` · brain: ${m.brain}` : ''
-              return `# ${m.title ?? key} (authored page${brainTag})\n\n${blocks.join('\n\n---\n\n')}`
+              return `# ${m.title ?? key} (authored page${brainTag})${renderHeaderNotes(m.headerNotes)}\n\n${blocks.join('\n\n---\n\n')}`
             }
             return { content: [{ type: 'text', text: matches.map(renderMatch).join('\n\n═══\n\n') }] }
           }
@@ -1579,7 +1651,7 @@ function renderNudge(payload) {
         // Always emitted, not only in the multi-brain case: the ref is what makes the brain question
         // moot, so withholding it until brains collide is exactly backwards.
         const refLine = m.ref ? `\nref: ${m.ref}` : ''
-        return `# ${m.title ?? name} (full authored page${brainTag})${refLine}\n\n${blocks.join('\n\n---\n\n')}\n\n${footer}`
+        return `# ${m.title ?? name} (full authored page${brainTag})${refLine}${renderHeaderNotes(m.headerNotes)}\n\n${blocks.join('\n\n---\n\n')}\n\n${footer}`
       }
       // ── THE PRE-CLAIM NUDGE ───────────────────────────────────────────────────────────────────
       //
@@ -1863,19 +1935,19 @@ function renderNudge(payload) {
     },
   )
 
-  server.registerTool(
+  if (SPLIT_PAGE_TOOL_AVAILABLE) server.registerTool(
     'split_page',
     {
       title: 'Move sections onto a new child page',
-      description: 'SPLIT a page: move whole sections onto a NEW page, leaving the original in place. Use it when a page has grown past what can be read in one turn — a correctness problem, not just a cost one, because an agent that cannot read the whole authority answers from part of it (a head page and its governing page disagreed about a gate status for a week that way). Measured across 480 pages: 5.2% of them hold a third of all authored text, so this targets the tail, not routine hygiene. It does NOT make pages go wrong less often — corrections scale roughly linearly with size — it changes what each one COSTS: fixing a claim on the 165k-char page means reading ~42,000 tokens; on a 20k child, ~5,000. WHAT IT NEVER DOES, each for a measured reason: never retires the original (a split is 1→2 and `superseded_by` holds one successor, and the original keeps receiving traffic with no narrower match); never moves governance (attaching a record to the child does not change its tier); never rewrites inbound [[links]] (the splitter cannot know which half a link meant — the reader following it does); never links the child FROM the source, because where that link goes is prose. GUARDS: the child is created BEFORE the source is trimmed, so a mid-way failure duplicates sections rather than losing them; `headings` must match the STORED heading exactly, INCLUDING any `· as of <date>` suffix (the rendered page shows a second `as of` stamp that is not part of it); moving every section is refused as a rename; and a STRICTER child is refused, because access is the union of attachments capped by the governing page — the child would look private while its evidence stayed readable. The child copies the parent tier and grants and gets an `In short` section. Reversible via `page_history` + `rollback_page`.',
+      description: 'SPLIT a page: move whole sections onto a NEW page, leaving the original in place. Use it when a page has outgrown one read — an agent that cannot read the whole authority answers from part of it. It targets the tail (5.2% of pages hold a third of all authored text), not routine hygiene, and it does not make pages go wrong less often: it makes each fix cheaper (~42,000 tokens to read a 165k-char page, ~5,000 for a 20k child). It NEVER retires the original, moves governance, rewrites inbound [[links]] (the reader following one knows which half it meant), or links the child FROM the source. EVERY REFUSAL IS DECIDED BEFORE ANYTHING IS WRITTEN (ADR-0064 §7): you need EDIT access to the version you read (edit_forbidden); pages with several tier versions are paused (multi_version_page); `headings` must match the STORED heading exactly, INCLUDING any `· as of <date>` suffix, and a heading two sections share is refused (ambiguous_heading); moving every section is refused as a rename; `new_title` must not name any existing or archived page (title_taken); a STRICTER child is refused, and a LOOSER one needs the source page\'s owner (widening_requires_owner); oversize sections and identity identifiers are refused (too_large, identity_claim). The child keeps the source page\'s OWNER, tier and grants, so the same people can read it, and gets an `In short` section. If a split stops after the child exists (source_trim_failed), finish with `merge_sections` (`from` only) for each heading in `remaining` — never re-run split_page. Reversible via `page_history` + `rollback_page`.',
       inputSchema: {
         name: z.string().describe('the exact page name to split, as read_page shows it'),
-        headings: z.array(z.string()).min(1).describe('the headings of the sections to MOVE, matched EXACTLY against the stored heading — include any `· as of <date>` suffix. Everything not listed stays on the original.'),
-        new_title: z.string().describe('the title of the new child page. It must not already exist in this brain.'),
+        headings: z.array(z.string()).min(1).describe('the headings of the sections to MOVE, matched EXACTLY against the stored heading — include any `· as of <date>` suffix. A heading two sections share is refused: rename one with rename_section first. Everything not listed stays on the original.'),
+        new_title: z.string().describe('the title of the new child page. It must not name ANY existing page in this brain, or an archived project: a split never adopts or revives one.'),
         base_version: z.string().describe('the `version` read_page prints for the SOURCE page (64-hex). REQUIRED — it is the concurrency check AND how the right brain is resolved.'),
         reason: z.string().describe('WHY you are splitting, in one short phrase — recorded in page_history. Say what outgrew the page.'),
-        owner: z.string().optional().describe('user id to own the child. Defaults to you, and the response says so when it does — worth setting deliberately, because ownership transfer has no reachable path once an owner is deactivated.'),
-        tier: z.enum(['accessible', 'scoped', 'confidential']).optional().describe('omit to COPY the source page tier, which is almost always right. A LOOSER tier is a deliberate widening; a STRICTER one is refused, since a split cannot tighten access.'),
+        owner: z.string().optional().describe('omit to keep the SOURCE page\'s owner, so the child has exactly the same audience — almost always right. Naming a different user is an ownership change: it needs the page owner, or someone above them who can read the page, and must be an active member of this brain.'),
+        tier: z.enum(['accessible', 'scoped', 'confidential']).optional().describe('omit to COPY the source page tier, which is almost always right. A LOOSER tier widens who can read the moved text, so only the source page\'s owner may choose it; a STRICTER one is refused, since a split cannot tighten access.'),
       },
     },
     async ({ name, headings, new_title, base_version, reason, owner, tier }) => {
@@ -1895,20 +1967,25 @@ function renderNudge(payload) {
       const out = await res.json().catch(() => null)
       if (!res.ok) {
         // `child_created` + `remaining` is the one failure worth reading carefully: it means the split
-        // is HALF DONE and nothing was lost. Surface it first so the caller finishes rather than retries
-        // from the top, which would 409 on the now-taken title and look like a different problem.
+        // is HALF DONE and nothing was lost. Surface it first so the caller FINISHES with merge_sections
+        // (`from` only) rather than re-running split_page, which refuses the now-taken title (ADR-0064 §7.4).
         const extra = [
           out?.child_created ? `the child "${out.child_created}" EXISTS and holds every moved section — nothing was lost` : '',
-          Array.isArray(out?.remaining) ? `still on BOTH pages, re-run for these: ${out.remaining.join(' · ')}` : '',
+          Array.isArray(out?.remaining) ? `still on BOTH pages — finish with merge_sections (\`from\` only) for each, do NOT re-run split_page: ${out.remaining.join(' · ')}` : '',
           Array.isArray(out?.detail) ? `detail: ${out.detail.join(' · ')}` : '',
           out?.message ?? '',
         ].filter(Boolean).join('\n')
         const hint = out?.hint ? `\n${out.hint}` : ''
         return toolError(`Could not split "${name}": ${out?.error ?? res.status}${extra ? `\n${extra}` : ''}${hint}`)
       }
-      const ownerNote = out.owner_defaulted
-        ? '\n⚠ The child is owned by you because no `owner` was given. Set one deliberately if it should belong to someone else — transfer is unreachable once an owner is deactivated.'
-        : ''
+      // ADR-0064 §7.5: an omitted owner now keeps the SOURCE page's owner, and the server's `note` says so.
+      // Only a NAMED owner changes the audience, so that is the one worth a warning. `owner_defaulted` is
+      // still read for a server older than #1041, where it meant the child fell to the caller.
+      const ownerNote = out.owner_changed
+        ? '\n⚠ The child is owned by the member you named, which changes who can read it if it is scoped or confidential.'
+        : out.owner_defaulted
+          ? '\n⚠ The child is owned by you because no `owner` was given. Set one deliberately if it should belong to someone else — transfer is unreachable once an owner is deactivated.'
+          : ''
       const grants = out.grants_copied ? ` ${out.grants_copied} access grant(s) copied.` : ''
       return { content: [{ type: 'text', text: `Split "${name}" (${out.brain} · ${out.tier} tier) → new page "${out.child}". Moved: ${out.moved.join(' · ')}.${grants} Child version: ${out.version}\n${out.note}\nNEXT: ${out.next}${ownerNote}\nReversible: \`page_history "${name}"\` then \`rollback_page\` restores the source; the child can be retired with set_page_validity.` }] }
     },

package/package.json

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