@theronap/cortex-mcp 0.9.88 → 0.9.90

package/lib/server.mjs

@@ -192,34 +192,179 @@ export async function runServer(version) {
     'log_session',
     {
       title: 'Log this session to Agnoclast',
-      description: 'Persist a CURATED summary of this work session as its durable Agnoclast record (authoritative — supersedes the auto-capture hook). Call at session close after composing the summary. Pass sessionId (the Claude Code session id) if you have it so this dedupes with the auto-capture of the same session.',
+      description: 'Persist a CURATED summary of this work session as its durable Agnoclast record (authoritative — supersedes the auto-capture hook). Call at session close after composing the summary. Pass sessionId (the Claude Code session id) so this dedupes with the auto-capture of the same session. If you belong to more than one brain you MUST name one — without a brain a session log has no route and is STAGED rather than recorded. **If the session touched work belonging to different brains, pass `segments` instead of `summary` and split it** — one segment per brain, each summary standing on its own and never alluding to the others. Reports every segment individually; a partial result is reported as PARTIAL, never as success.',
       inputSchema: {
-        summary: z.string().describe('the curated session summary (what was done, decided, left open) — becomes the durable record'),
+        summary: z.string().optional().describe('the curated session summary — the single-brain form. Omit when passing `segments`'),
+        segments: z.array(z.object({
+          brain: z.string().describe('destination brain for this half of the session (name or org id)'),
+          summary: z.string().describe('a summary that stands ON ITS OWN. It must not mention, allude to, or imply that other segments exist — "the rest of this session covered personal projects" leaks in prose exactly what splitting was meant to contain'),
+          title: z.string().optional(),
+          project: z.string().optional(),
+        })).optional().describe('SPLIT the log, one entry per brain. Use whenever a session touched work belonging to different brains: a session is a container of time, not a topic, and every single-brain answer is wrong — filing it all in the org brain exposes personal work to colleagues, filing it all in the personal one denies the org its record, and summarizing half silently drops the other half. Max ONE segment per brain (they share this session\'s dedupe key, so two aimed at the same brain would overwrite each other). When a chunk is ambiguous, put it in the MORE PRIVATE brain — a misfile there is private, a misfile the other way is visible to everyone in the org.'),
         project: z.string().optional().describe('project key/name this session worked in'),
         title: z.string().optional().describe('short title for the session'),
-        sessionId: z.string().optional().describe('the Claude Code session id (dedupes with the auto-capture hook of the same session)'),
+        sessionId: z.string().optional().describe('the Claude Code session id — shared by every segment, and the only thing pairing them. Deliberately NOT a link: segments never reference each other, so a reader cleared for one brain cannot tell the others exist, while you can join on it across brains'),
+        brain: z.string().optional().describe('which brain to record this session in (name or org id, one of your own). REQUIRED IN EFFECT for a multi-brain member: session-class sources route only by an explicit brain or a sole membership, so omitting it stages the log instead of recording it.'),
+        privacy: z.enum(['accessible', 'scoped', 'confidential']).optional().describe('tier this record AT WRITE TIME. Use when the summary names confidential work (a candidate evaluation, a security finding) — safer than letting it land org-visible and re-tiering after, which leaves it readable in between.'),
       },
     },
-    async ({ summary, project, title, sessionId }) => {
-      const res = await fetchCortex(`${BASE}/api/ingest`, {
-        method: 'POST',
-        headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
-        body: JSON.stringify({
-          source: 'claude-code',
-          captureSource: 'skill',
-          summary,
-          ...(project ? { project } : {}),
-          ...(title ? { title } : {}),
-          ...(sessionId ? { sessionId } : {}),
-          payload: { via: 'log_session' },
-        }),
-      })
-      if (!res.ok) {
-        const body = await res.text()
-        throw new Error(classify(res.status, res.headers.get('content-type'), body, res.headers.get('x-vercel-id')).message)
+    async ({ summary, segments, project, title, sessionId, brain, privacy }) => {
+      // A session is a container of TIME, not a topic (ADR-0029 step 4). Normalize to a list of
+      // segments; the single-brain call is just a one-segment list.
+      const list = Array.isArray(segments) && segments.length
+        ? segments.map((s) => ({ brain: s.brain, summary: s.summary, title: s.title ?? title, project: s.project ?? project }))
+        : (summary ? [{ brain, summary, title, project }] : null)
+      if (!list) {
+        return toolError('Pass `summary` (single brain) or a non-empty `segments` array (one entry per brain).')
+      }
+
+      // Records are unique on the ORG-SCOPED (org_id, dedupe_key) and every segment carries this
+      // session's dedupe key. Cross-brain segments therefore never collide — that constraint is what
+      // makes the whole design work — but two aimed at the SAME brain would silently merge and lose
+      // one. Refuse instead of letting that happen quietly.
+      const seenBrain = new Set()
+      for (const s of list) {
+        const k = String(s.brain ?? '').trim().toLowerCase()
+        if (seenBrain.has(k)) {
+          return toolError(`Two segments target the same brain (${s.brain}). They share this session's dedupe key, so the second would overwrite the first — merge them into one segment.`)
+        }
+        seenBrain.add(k)
+      }
+
+      let brainIndex = null
+      const orgIdFor = async (nameOrId) => {
+        if (!nameOrId) return null
+        if (!brainIndex) {
+          try {
+            const r = await fetchCortex(`${BASE}/api/brains`, { headers: { Authorization: `Bearer ${TOKEN}` } })
+            brainIndex = r.ok ? ((await r.json().catch(() => ({}))).brains ?? []) : []
+          } catch {
+            brainIndex = []
+          }
+        }
+        const q = String(nameOrId).trim().toLowerCase()
+        const hit = brainIndex.find(
+          (b) => String(b.orgId ?? '').toLowerCase() === q || String(b.name ?? '').toLowerCase() === q,
+        )
+        return hit?.orgId ?? null
       }
-      const j = await res.json().catch(() => ({}))
-      return { content: [{ type: 'text', text: `Logged to Agnoclast (authoritative): "${j.title ?? title ?? 'session'}" — ${j.inserted ? 'new record' : 'updated existing'}.` }] }
+
+      const lines = []
+      let failures = 0
+
+      for (const seg of list) {
+        const where = seg.brain ?? '(no brain named)'
+        let res
+        try {
+          res = await fetchCortex(`${BASE}/api/ingest`, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+              source: 'claude-code',
+              captureSource: 'skill',
+              summary: seg.summary,
+              ...(seg.project ? { project: seg.project } : {}),
+              ...(seg.title ? { title: seg.title } : {}),
+              ...(sessionId ? { sessionId } : {}),
+              // ADR-0022 deleted the write pointer, so a session-class source routes ONLY by an
+              // explicit brain or a sole membership — anything else STAGES. This tool never sent one,
+              // so every close-out from a multi-brain member landed in staged_records instead of the
+              // org. Measured 2026-08-09: 86 staged rows, not drainable by /api/staged/promote.
+              ...(seg.brain ? { brain: seg.brain } : {}),
+              ...(privacy ? { privacy } : {}),
+              payload: { via: 'log_session' },
+            }),
+          })
+        } catch (e) {
+          failures++
+          lines.push(`✗ ${where}: ${e.message}`)
+          continue
+        }
+        if (!res.ok) {
+          const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
+          failures++
+          lines.push(`✗ ${where}: ${d.message}`)
+          continue
+        }
+        const j = await res.json().catch(() => ({}))
+
+        // NEVER report a non-record as "logged". `staged` and `skipped` are 200 OK responses that
+        // wrote no record, and this used to print "Logged … updated existing" for both, because
+        // `j.inserted` is merely falsy on a staged write.
+        if (j.staged) {
+          const why = j.reason === 'no_route_for_source' && !seg.brain
+            ? 'no brain named and you belong to more than one, so it had nowhere to route'
+            : `reason: ${j.reason ?? 'unknown'}`
+          failures++
+          lines.push(`✗ ${where}: NOT LOGGED — staged, not recorded (${why}). Re-run this segment with brain:"<name>" — staged session logs cannot be drained by /api/staged/promote.`)
+          continue
+        }
+        if (j.skipped) {
+          failures++
+          lines.push(`✗ ${where}: NOT LOGGED — server skipped the write: ${j.skipped}`)
+          continue
+        }
+
+        // Gate 4 routes a session log into PRIVATE INTAKE rather than straight to records, answering
+        // `via:"private_intake"` with an intakeItemId and no id. The previous check fell through to
+        // "no record id" and reported NOT LOGGED over a write that had landed — a false negative that
+        // drives retries, and retries against ingest make duplicates.
+        //
+        // Materializing here is not an optimization. Close-out is the ONLY moment the destination
+        // brain is known; a unit left in intake goes cleanup-due in a day and becomes an item no later
+        // session has the authority to route, because deciding which brain half of someone's session
+        // belongs in is exactly the judgment a stranger cannot make.
+        if (!j.id && j.via === 'private_intake' && j.intakeItemId) {
+          const orgId = await orgIdFor(seg.brain)
+          if (!orgId) {
+            failures++
+            lines.push(`✗ ${where}: captured to intake as ${j.intakeItemId}, but that brain did not resolve to an org id — materialize it by hand`)
+            continue
+          }
+          let m
+          try {
+            m = await fetchCortex(`${BASE}/api/intake/materialize`, {
+              method: 'POST',
+              headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+              body: JSON.stringify({
+                intakeItemId: j.intakeItemId,
+                orgId,
+                title: seg.title,
+                summary: seg.summary,
+                source: 'claude-code',
+                recordType: 'ai_session',
+                origin: 'session',
+              }),
+            })
+          } catch (e) {
+            failures++
+            lines.push(`✗ ${where}: intake ${j.intakeItemId} NOT materialized — ${e.message}`)
+            continue
+          }
+          const mj = await m.json().catch(() => ({}))
+          if (!m.ok || !mj.recordId) {
+            failures++
+            lines.push(`✗ ${where}: intake ${j.intakeItemId} NOT materialized — ${mj.error ?? m.status}`)
+            continue
+          }
+          lines.push(`✓ ${where}: record ${mj.recordId}`)
+          continue
+        }
+
+        if (!j.id) {
+          failures++
+          lines.push(`✗ ${where}: NOT LOGGED — no record id. Raw: ${JSON.stringify(j).slice(0, 200)}`)
+          continue
+        }
+        lines.push(`✓ ${where}: record ${j.id}${j.inserted ? '' : ' (updated existing)'}`)
+      }
+
+      // Partial success is a real outcome once there is more than one segment, and "3 of 4 landed"
+      // must never read as done — that is the same silent-loss shape this whole path was repaired for.
+      const head = failures === 0
+        ? `Logged ${lines.length} segment${lines.length === 1 ? '' : 's'}.`
+        : `PARTIAL — ${lines.length - failures} of ${lines.length} segments logged, ${failures} FAILED. A partly-logged session is not a logged session; re-run the failed segments.`
+      return { content: [{ type: 'text', text: `${head}\n${lines.join('\n')}` }] }
     },
   )
 
@@ -457,7 +602,7 @@ export async function runServer(version) {
         source: z.string().optional(),
         recordType: z.string().optional(),
         dedupeKey: z.string().optional(),
-        origin: z.enum(['deterministic', 'llm', 'user']).optional(),
+        origin: z.enum(['deterministic', 'llm', 'user', 'session']).optional(),
       },
     },
     async (args) => {
@@ -525,11 +670,89 @@ export async function runServer(version) {
     },
   )
 
+  server.registerTool(
+    'intake_defer',
+    {
+      title: 'Defer a private intake item to the owner',
+      description:
+        'The THIRD terminal outcome, and the right one whenever the honest answer is "this is not mine to decide." Use it when a claimed unit is someone else\'s private content, when the destination brain is a real judgment call rather than a lookup, or when publishing and destroying are both wrong — a stranger\'s message thread, a photo you cannot place, an email whose brain depends on context only the owner has. Destroys NOTHING: the unit stays encrypted and intact, its state becomes `awaiting_user`, and your `question` is what the owner actually sees. Prefer this over letting a lease lapse — a lapsed lease says nothing, increments `attempts`, and hands the identical dead end to the next session. Requires the claim, one item per call.',
+      inputSchema: {
+        intakeItemId: z.string().describe('intake item uuid from intake_claim'),
+        question: z.string().describe('what you need the owner to decide, in their words not yours — this is the entire message they get, so "which brain should this iMessage thread go to, if any?" beats "needs triage"'),
+      },
+    },
+    async ({ intakeItemId, question }) => {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/intake/defer`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ intakeItemId, question }),
+        })
+      } catch (e) {
+        return toolError(`Could not defer: ${e.message}`)
+      }
+      const out = await res.json().catch(() => null)
+      if (!res.ok) {
+        if (out?.error === 'not_claimed') {
+          return toolError('You do not hold a claim on that item — intake_claim it first, so the question follows from having read it.')
+        }
+        if (out?.error === 'already_terminal') {
+          return toolError(`Nothing left to ask about: ${out?.detail ?? 'the unit is already materialized or discarded'}.`)
+        }
+        return toolError(`Could not defer: ${out?.error ?? res.status}${out?.detail ? ` — ${out.detail}` : ''}`)
+      }
+      if (out?.alreadyDeferred) {
+        return { content: [{ type: 'text', text: 'Already awaiting the owner — nothing to do.' }] }
+      }
+      return { content: [{ type: 'text', text: 'Deferred to the owner. Content preserved, question queued in intake_cleanup_status.openQuestions, and the unit no longer gates cleanup.' }] }
+    },
+  )
+
+  server.registerTool(
+    'intake_release',
+    {
+      title: 'Hand an intake claim back',
+      description:
+        'Give a claimed unit back to the queue WITHOUT deciding anything. This is not a fourth outcome — materialize, discard and defer resolve a unit; release just ends your hold on it. Use it when you claimed more than you can act on, or when the unit turns out to belong to work you are not doing. Prefer it over letting the lease expire: a lapse and a crash are indistinguishable in the ledger, so silently timing out costs the pile the one signal that says a session looked and chose to pass. Use intake_defer instead when the unit needs the OWNER to decide — release puts it back in front of the next session, which will hit whatever wall you did.',
+      inputSchema: {
+        intakeItemId: z.string().describe('intake item uuid from intake_claim'),
+        reason: z.string().describe('why you are handing it back — "claimed too broadly", "not related to this session\'s work". Recorded on the claim, and the only thing distinguishing this from a lapsed lease'),
+      },
+    },
+    async ({ intakeItemId, reason }) => {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/intake/release`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ intakeItemId, reason }),
+        })
+      } catch (e) {
+        return toolError(`Could not release: ${e.message}`)
+      }
+      const out = await res.json().catch(() => null)
+      if (!res.ok) {
+        if (out?.error === 'not_claimed') {
+          return toolError('You do not hold a claim on that item — there is nothing to hand back.')
+        }
+        if (out?.error === 'awaiting_user') {
+          return toolError('That unit is already deferred to the owner. Releasing it would orphan the open question — leave it, or have the owner answer it.')
+        }
+        if (out?.error === 'already_terminal') {
+          return toolError(`Nothing to release: ${out?.detail ?? 'the unit is already materialized or discarded'}.`)
+        }
+        return toolError(`Could not release: ${out?.error ?? res.status}${out?.detail ? ` — ${out.detail}` : ''}`)
+      }
+      return { content: [{ type: 'text', text: 'Released. The unit is back in the queue as pending, and your lease is gone.' }] }
+    },
+  )
+
   server.registerTool(
     'intake_cleanup_status',
     {
       title: 'Private intake cleanup status',
-      description: 'Counts of pending/claimed/awaiting/cleanup-due intake items plus open clarifying questions for the owner.',
+      description: 'Counts of pending/claimed/awaiting/cleanup-due intake items, open clarifying questions for the owner, and `needsAttention` — units that keep coming back, with attempts / releases / deferrals / lapses each broken out. A high `lapses` means sessions claimed that unit and neither resolved it nor handed it back; a `deferrals` above 1 means the owner has already been asked more than once. Both are the OWNER\'s signal to act on, not yours — surface them rather than trying to clear them yourself.',
       inputSchema: {},
     },
     async () => {
@@ -1489,14 +1712,16 @@ export async function runServer(version) {
         project: z.string().optional().describe('project key to filter to (e.g. "cortex")'),
         since_days: z.number().optional().describe('only records from the last N days'),
         limit: z.number().optional().describe('max rows (1-50, default 20)'),
+        session: z.string().optional().describe('a session id — returns every record that session produced, INCLUDING the separate halves of a log that was split across brains. Segmented logs share a sessionId and never link to each other, so this is the only way to reassemble one. RLS-scoped: you get the halves you are cleared for and cannot tell whether others exist'),
       },
     },
-    async ({ type, project, since_days, limit }) => {
+    async ({ type, project, since_days, limit, session }) => {
       const qs = new URLSearchParams()
       if (type) qs.set('type', type)
       if (project) qs.set('project', project)
       if (since_days != null) qs.set('since_days', String(since_days))
       if (limit != null) qs.set('limit', String(limit))
+      if (session) qs.set('session', session)
       let res
       try {
         res = await fetchCortex(`${BASE}/api/records?${qs}`, { headers: { Authorization: `Bearer ${TOKEN}` } })
@@ -1792,7 +2017,16 @@ export async function runServer(version) {
       const out = await res.json().catch(() => null)
       if (!res.ok) {
         if (out?.error === 'already_claimed') {
-          return toolError(`Another live session is already holding that record (${String(out.heldBy).slice(0, 16)}…). Leave it to them.`)
+          // Name the holder when the server knows it. The fallback matters: `heldBy` is absent when
+          // nothing holds a live lease, which means the record was not claimable rather than taken —
+          // printing "another session has it" there sends the reader chasing a session that does not
+          // exist. (This branch printed a bare `undefined` until 2026-08-14; the field was renamed
+          // server-side and the tool was never updated, which is the whole reason it says both now.)
+          if (out.heldBy) {
+            const until = out.heldUntil ? `, lease to ${out.heldUntil}` : ''
+            return toolError(`Session ${String(out.heldBy).slice(0, 16)}… is holding that record${until}. Leave it to them.`)
+          }
+          return toolError(out.detail || 'Could not claim that record and no session holds it — re-run pending_records; it may have been resolved already.')
         }
         return toolError(`Could not claim record: ${out?.error ?? res.status}`)
       }

package/package.json

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

package/skills/log/SKILL.md

@@ -36,9 +36,22 @@ No arguments. Read the conversation context.
    session's authoritative Agnoclast record (`capture_source='skill'`). The background auto-capture is a
    fallback and will not overwrite it; passing the same `sessionId` the auto-capture uses dedupes them
    onto one record. This — not the raw-transcript re-derivation — is the canonical record going forward.
-4. **Confirm + flag privacy** — `log_session` returns a confirmation; if it errors, tell the user to
-   run `npx -y @theronap/cortex-mcp doctor`. If any record from this session should be confidential,
-   note it so the user can mark it (`set_record_privacy`). Default is org-visible under access rules.
+
+   ⚠ **If you belong to more than one brain, pass `brain`.** ADR-0022 deleted the write pointer, so a
+   session-class source routes only by an explicit brain or a sole membership — omit it and the log is
+   **STAGED, not recorded**, and staged session logs are not drainable by `/api/staged/promote`. Pick the
+   brain the work was actually in (`my_brains` shows what each holds). This silently swallowed 86 close-outs
+   before it was caught on 2026-08-09.
+4. **Confirm + flag privacy** — **read the result text, do not assume it succeeded.** `log_session` now
+   answers `NOT LOGGED — STAGED…` or `NOT LOGGED — the server skipped…` when no record was written; only a
+   message carrying a record id means it landed. (It previously printed "Logged … updated existing" for a
+   staged write, because `inserted` is merely falsy when nothing is recorded — an agent reported a session
+   as saved when it was not.) If it errors, tell the user to run `npx -y @theronap/cortex-mcp doctor`.
+
+   If any record from this session should be confidential, prefer passing `privacy: "confidential"` on the
+   `log_session` call itself so it is tiered **at write time** rather than landing org-visible and being
+   corrected after. Otherwise note it so the user can mark it (`set_record_privacy`). Default is org-visible
+   under access rules.
 5. **Sweep the wiki (author what you now understand)** — the HARD backstop for live authoring
    ([[cortex-wiki-authoring-spec]] D2). For each node whose understanding meaningfully advanced this
    session (the project(s) worked on, people you coordinated with, and yourself when your own focus