@theronap/cortex-mcp 0.9.149 → 0.9.151

package/lib/redact.mjs

@@ -1,5 +1,6 @@
 // redact.mjs — strip high-confidence credential patterns from text BEFORE it leaves
-// the machine (capture POSTs a transcript tail to the org). A leaked secret in a
+// the machine or is stored (hydrate sends the prompt; capture feeds the transcript tail to
+// the local summarizer and the local queue — since D8 it never POSTs the tail). A leaked secret in a
 // transcript — a user pastes an API key, a tool reads a config file holding one, or
 // (the 2026-06-22 finding) a login token sits inlined in a hook command — must never
 // be transmitted or stored. Conservative by design: targets known secret SHAPES so it

package/lib/server.mjs

@@ -10,6 +10,7 @@ import { folderClaimLine } from './folder_claims.mjs'
 import { resolveSessionKey, resolveLogSessionId } from './session_key.mjs'
 import { runSendImessage } from './imessage_send.mjs'
 import { formatGrepHits } from './grep_cli.mjs'
+import { buildProposal, renderProposal, withAskNotice } from './propose_obligation.mjs'
 import { renderCaptureStatus } from './capture_status.mjs'
 import { renderTriage } from './red_link_triage.mjs'
 import { runCodeGraphQuery } from './code_graph_cli.mjs'
@@ -77,6 +78,23 @@ 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}`
 
+// 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.
+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
@@ -823,7 +841,7 @@ function renderNudge(payload) {
         sections.push(`Unclaimed records (${records.length}) from other sources — newest first:\n${lines.join('\n')}`)
       }
 
-      return { content: [{ type: 'text', text: sections.join('\n\n') }] }
+      return { content: [{ type: 'text', text: withAskNotice(sections.join('\n\n')) }] }
     },
   )
 
@@ -1169,7 +1187,7 @@ function renderNudge(payload) {
         if (out?.error === 'not_found') return toolError('No such intake unit in your account.')
         return toolError(`Could not look: ${out?.error ?? res.status}${out?.detail ? ` — ${out.detail}` : ''}`)
       }
-      return { content: [{ type: 'text', text: JSON.stringify(out, null, 2) }] }
+      return { content: [{ type: 'text', text: withAskNotice(JSON.stringify(out, null, 2)) }] }
     },
   )
 
@@ -1347,7 +1365,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') }] }
           }
@@ -1578,7 +1596,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 ───────────────────────────────────────────────────────────────────
       //
@@ -1866,15 +1884,15 @@ function renderNudge(payload) {
     '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 }) => {
@@ -1894,20 +1912,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.` }] }
     },
@@ -2036,8 +2059,14 @@ function renderNudge(payload) {
         }
         lines.push('', 'Claim with set_routing_identifier on the page whose subject HAS that identifier.')
       }
+      // THREE OUTCOMES, ALL LEGITIMATE (ADR-0038 amendment, Theron 2026-09-11: "we need to make it an
+      // option for the agent to discard emails entirely or to create pages"). Naming only placement left an
+      // agent with no honest move for junk mail or for a subject that has no page yet — so it either
+      // mis-filed onto the nearest page or left the queue to grow. 6 of 19 arrivals sat exactly there.
       lines.push('', 'Place one with place_staged_record (staged_id + pages). The pages decide the brain, which decides who can read it.')
-      return { content: [{ type: 'text', text: lines.join('\n') }] }
+      lines.push('No page fits? `author` the page it needs, then place onto it. Junk? `discard_staged` (reversible, dry-run by default).')
+      lines.push('A default brain is NOT the answer for content — one standing rule cannot decide disclosure for mail nobody has read.')
+      return { content: [{ type: 'text', text: withAskNotice(lines.join('\n')) }] }
     },
   )
 
@@ -2202,6 +2231,49 @@ function renderNudge(payload) {
     },
   )
 
+  server.registerTool(
+    'propose_obligation',
+    {
+      title: 'Propose something a record asks of this person',
+      description:
+        'Propose an obligation you found while READING — with the sentence that asks for it. This is the verb for ' +
+        '"this email asks Theron for a call on Friday": it lands as a PROPOSAL the person confirms or dismisses, never ' +
+        'as a commitment they made. Use it whenever something you read asks this person for something and no obligation ' +
+        'covers it yet. ⚠ NOT the same tool as `track_obligation`, which records what the PERSON says they owe and ' +
+        'carries no evidence — proposing through that verb makes a machine guess indistinguishable from their own word. ' +
+        '⚠ `evidence` must be the VERBATIM sentence from that record, not your paraphrase: it is the whole reviewable ' +
+        'unit, and the person decides on the strength of it. ⚠ NEVER INVENT A DATE. Copy the words that say when into ' +
+        '`due_phrase` ("by Tuesday the 22nd", "this week") and the server works the date out against the record\'s own ' +
+        'date; pass `due_at` only when you are reading a date the record states. No date is a proposal with no date, ' +
+        'which is honest and still shows up.',
+      inputSchema: {
+        record: z.string().describe('the record the ask came from — an id from my_day, timeline_pull, list_records or find_sessions'),
+        subject: z.string().describe('what must be done, one short phrase'),
+        evidence: z.string().describe('the VERBATIM sentence from that record that asks for it'),
+        due_phrase: z.string().optional().describe('the words that say WHEN, copied from the evidence sentence — the server resolves them'),
+        due_at: z.string().optional().describe('YYYY-MM-DD, or YYYY-MM-DDTHH:MM when a time is stated. Only a date the record states.'),
+        obligated_party: z.enum(['self', 'other', 'none']).optional().describe('self (default) = this person owes it; other = someone else; none = nobody'),
+      },
+    },
+    async ({ record, subject, evidence, due_phrase, due_at, obligated_party }) => {
+      const built = buildProposal({ subject, evidence, due_phrase, due_at, obligated_party })
+      if (built.error) return toolError(`Not proposed: ${built.error}`)
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/obligations/candidates`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ recordId: record, obligations: [built.candidate] }),
+        })
+      } catch (e) { return toolError(`Could not reach obligations: ${e.message}`) }
+      const out = await res.json().catch(() => null)
+      if (res.status === 404) return toolError('No such record of yours — pass a record id you can see (my_day, timeline_pull, list_records).')
+      if (res.status === 409) return toolError('That capture is still sealed in private intake; materialize it first, then propose against its record.')
+      if (!res.ok) return toolError(`Could not propose: ${out?.error ?? res.status}`)
+      return { content: [{ type: 'text', text: renderProposal(out, built.candidate, built.note) }] }
+    },
+  )
+
   server.registerTool(
     'resolve_obligation',
     {
@@ -3157,7 +3229,7 @@ function renderNudge(payload) {
         return toolError(`Could not build daily log: ${d.message}`)
       }
       const { text } = await res.json()
-      return { content: [{ type: 'text', text }] }
+      return { content: [{ type: 'text', text: withAskNotice(text) }] }
     },
   )
 

package/package.json

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