@theronap/cortex-mcp 0.9.142 → 0.9.143

package/lib/doctor.mjs

@@ -3,6 +3,7 @@ import { homedir } from 'os'
 import { join } from 'path'
 import { checkToken, checkSkills, resolveBase, resolveTokenSource } from './diagnose.mjs'
 import { renderRenameNotice } from './rename_notice.mjs'
+import { detectSurface, renderSurface } from './surface.mjs'
 
 // `npx @theronap/cortex-mcp doctor` — a live, one-command health check.
 //
@@ -21,13 +22,27 @@ export const resolveToken = resolveTokenSource
 // signal inside Claude Code itself (three-machine dry-run finding 2026-06-09: with no
 // indicator, a user can't tell whether their sessions are flowing to the org).
 // Always returns 0 — a status line must never break a session start.
+//
+// The surface line is printed from a `finally` so no branch below can skip it. That includes the
+// early returns and the "connected" line, which a person in Claude's Home tab also sees: the token is
+// fine there, and the app they are looking at still cannot use it. See surface.mjs.
 export async function runStatus() {
-  const base = resolveBase(process.env.CORTEX_URL)
   const out = (m) => process.stdout.write(m + '\n')
+  try {
+    await statusLine(out)
+  } finally {
+    const surface = renderSurface(detectSurface(process.env), 'status')
+    if (surface) out(surface)
+  }
+  return 0
+}
+
+async function statusLine(out) {
+  const base = resolveBase(process.env.CORTEX_URL)
   const { token } = resolveToken()
   if (!token) {
     out('Agnoclast: NOT connected — no token found. Run: npx -y @theronap/cortex-mcp setup <token>')
-    return 0
+    return
   }
   try {
     const r = await checkToken(token, base)
@@ -40,7 +55,7 @@ export async function runStatus() {
       // warning that contradicts it.
       if (r.captureNotice?.message) {
         out(`Agnoclast: ⚠ ${r.captureNotice.message}`)
-        return 0
+        return
       }
       const n = typeof r.projectCount === 'number' ? ` · ${r.projectCount} project${r.projectCount === 1 ? '' : 's'} visible` : ''
       out(`Agnoclast: connected — sessions on this machine are captured to your org${n}.`)
@@ -58,12 +73,24 @@ export async function runStatus() {
   } catch (e) {
     out(`Agnoclast: status check failed (${e?.message ?? String(e)}) — run doctor.`)
   }
-  return 0
 }
 
+// The surface block goes LAST, from a `finally`, for the same reason as in runStatus: all three
+// verdicts (PASS, PARTIAL, FAIL) can be printed to a person in Claude's Home tab, and PASS is the
+// one that misled. It says "reopen Claude Code", and reopening the Claude app can put them straight
+// back in Home. The exit code is unchanged: not being able to see the surface is not a failure.
 export async function runDoctor() {
-  const base = resolveBase(process.env.CORTEX_URL)
   const out = (m) => process.stdout.write(m + '\n')
+  try {
+    return await doctorChecks(out)
+  } finally {
+    out(renderSurface(detectSurface(process.env), 'doctor'))
+    out('')
+  }
+}
+
+async function doctorChecks(out) {
+  const base = resolveBase(process.env.CORTEX_URL)
 
   out('')
   out('Agnoclast doctor — checking your connection…')

package/lib/obligations_render.mjs

@@ -0,0 +1,39 @@
+// PURE: what my_obligations prints. Out of server.mjs so the labelling below can be tested — the tool
+// handler itself is reachable by no test.
+//
+// 🔴 A PROPOSAL MUST NOT READ AS SOMETHING THE PERSON ENTERED. ADR-0059 extraction writes rows in state
+// `proposed`, and listObligations returns the owner's own proposals alongside confirmed ones — by
+// design, since a proposal nobody sees is a silent drop. Until 2026-09-10 this renderer printed them
+// all under "N open:" with no mark, so two lines extracted from a lecture (one of them wrongly dated)
+// looked exactly like obligations the person had written down. It is labelled here, and the header
+// says what to do with a wrong one.
+//
+// `dueAt` arrives in the OWNER's zone with its offset (web/lib/engine/due_dates.ts), so slice(0, 10)
+// below is the owner's calendar date and new Date() is still the exact instant.
+export function renderObligations(obs, now = Date.now()) {
+  if (!obs?.length) return 'Nothing open.'
+  const proposed = obs.filter((o) => o.state === 'proposed').length
+  const lines = [
+    proposed
+      ? `${obs.length} open — ${proposed} of them PROPOSED: extracted from a record, not entered by you. A wrong one: resolve_obligation with state "cancelled".`
+      : `${obs.length} open:`,
+    '',
+  ]
+  for (const o of obs) {
+    const overdue = o.dueAt && new Date(o.dueAt).getTime() <= now
+    const when = o.dueAt ? `${overdue ? 'OVERDUE ' : 'due '}${o.dueAt.slice(0, 10)}` : 'no deadline'
+    lines.push(`${o.id}`)
+    lines.push(`  ${o.subject}  — ${when}${o.state === 'snoozed' ? ' (snooze expired)' : ''}${o.state === 'proposed' ? '  [PROPOSED]' : ''}`)
+    // ⚠ EVIDENCE IS RENDERED AS A QUESTION, NEVER AS A VERDICT. The phrasing is the feature:
+    // "is this done?" costs the reader a second, "you still owe this" about finished work costs
+    // the channel its credibility.
+    if (o.evidence?.length) {
+      lines.push(`  ❓ ${o.evidence.length} record(s) suggest this may already be done — check, then resolve_obligation:`)
+      for (const e of o.evidence.slice(0, 3)) {
+        lines.push(`      ${e.occurredAt.slice(0, 10)}  ${e.title ?? '(untitled)'}${e.viaIdentifier ? `  [${e.viaIdentifier}]` : ''}`)
+      }
+    }
+    lines.push('')
+  }
+  return lines.join('\n')
+}

package/lib/server.mjs

@@ -15,6 +15,7 @@ import { renderTriage } from './red_link_triage.mjs'
 import { runCodeGraphQuery } from './code_graph_cli.mjs'
 import { repoFullNameFrom } from './capture.mjs'
 import { spawnObligationWorker } from './obligations_worker.mjs'
+import { renderObligations } from './obligations_render.mjs'
 
 // Reactive red-link triage (Mechanism 2). On a read_page miss, ask the server whether the name is a
 // tracked wanted page, whether a bare node exists for it, and whether it's a deliberately demoted page,
@@ -2123,27 +2124,7 @@ function renderNudge(payload) {
       const out = await res.json().catch(() => null)
       if (!res.ok) return toolError(`Could not list: ${out?.error ?? res.status}`)
       const obs = out?.obligations ?? []
-      if (!obs.length) return { content: [{ type: 'text', text: 'Nothing open.' }] }
-
-      const now = Date.now()
-      const lines = [`${obs.length} open:`, '']
-      for (const o of obs) {
-        const overdue = o.dueAt && new Date(o.dueAt).getTime() <= now
-        const when = o.dueAt ? `${overdue ? 'OVERDUE ' : 'due '}${o.dueAt.slice(0, 10)}` : 'no deadline'
-        lines.push(`${o.id}`)
-        lines.push(`  ${o.subject}  \u2014 ${when}${o.state === 'snoozed' ? ' (snooze expired)' : ''}`)
-        // \u26a0 EVIDENCE IS RENDERED AS A QUESTION, NEVER AS A VERDICT. The phrasing is the feature:
-        // "is this done?" costs the reader a second, "you still owe this" about finished work costs
-        // the channel its credibility.
-        if (o.evidence?.length) {
-          lines.push(`  \u2753 ${o.evidence.length} record(s) suggest this may already be done \u2014 check, then resolve_obligation:`)
-          for (const e of o.evidence.slice(0, 3)) {
-            lines.push(`      ${e.occurredAt.slice(0, 10)}  ${e.title ?? '(untitled)'}${e.viaIdentifier ? `  [${e.viaIdentifier}]` : ''}`)
-          }
-        }
-        lines.push('')
-      }
-      return { content: [{ type: 'text', text: lines.join('\n') }] }
+      return { content: [{ type: 'text', text: renderObligations(obs) }] }
     },
   )
 

package/lib/surface.mjs

@@ -0,0 +1,94 @@
+// Which app is running `doctor` / `status` — and, when that cannot be told, the requirement, plainly.
+//
+// WHY THIS EXISTS (T23, v1 scope lock, added 2026-09-09). A new seat lost about an hour to being in
+// the Claude desktop app's Home tab instead of its Code tab. Everything Agnoclast installs lives in
+// Claude Code's own config: the server in ~/.claude.json, the hooks in ~/.claude/settings.json. Home
+// reads neither, so nothing connected and nothing said why. `doctor` and `status` both ran in that
+// state and neither mentioned the one fact that mattered. `doctor` printed PASS, because the token
+// was fine, then told the person to "reopen Claude Code", which put them back in Home.
+//
+// WHAT CAN BE DETECTED. Verified against the Claude Code 2.1.260 binary on 2026-09-10, not assumed:
+//   CLAUDECODE="1"          Claude Code puts this in the environment of every hook command, MCP
+//                           server and shell command it starts. Present means Claude Code started us.
+//   CLAUDE_CODE_ENTRYPOINT  Claude Code sets it at startup when its launcher has not: 'cli', or
+//                           'sdk-cli' for `claude -p`. Launchers set their own: 'claude-desktop' (the
+//                           desktop app's Code tab), 'claude-vscode', 'local-agent', 'remote', 'sdk-ts'.
+//
+// WHAT CANNOT: Home. Home never starts this process, so no process running `doctor` or `status` is
+// ever "in Home". A person in Home who runs `doctor` does it from a terminal, and that terminal looks
+// like every other terminal. So a missing signal means UNKNOWN, never "fine", and UNKNOWN prints the
+// requirement. That is the T23 acceptance criterion: the message appears when the surface is absent,
+// rather than merely being able to appear.
+//
+// ⚠ Only the entrypoints below count as a place Agnoclast is known to work. Claude Code also runs
+// underneath other products ('local-agent', 'remote*', 'sdk-ts', ...), and whether those load the
+// user's ~/.claude.json has not been verified. They get the requirement, not a ✓. A wrong ✓ hides the
+// message from the one person who needed it. A wrong ⚠ costs a line that begins "If that's where
+// you are".
+//
+// Deliberately NOT used, each for a reason:
+//   ~/.claude.json wiring      `doctor` already reports it as "token source", and it was just as
+//                              present in the Home incident. Wired is not a fact about where you are.
+//   /api/session-ping          keyed by person + cwd, not by machine; says "some host started the
+//                              server recently", not "the app you are looking at can"; and it adds a
+//                              network round trip to a SessionStart hook already measured at 4.6s.
+//   ~/.cortex/presence.json    written only after a SUCCESSFUL hydrate, so a missing file cannot tell
+//                              "never used Code here" from "hydrate failed". It is history, not location.
+//   Claude.app installed       says nothing about which tab is open.
+//
+// Pure: no I/O. The caller passes the environment in.
+
+/** Entrypoints known to be Claude Code proper, i.e. Claude Code reading this user's own config. */
+const CODE_ENTRYPOINTS = {
+  'cli': 'Claude Code in a terminal',
+  'sdk-cli': 'Claude Code in a terminal',
+  'claude-desktop': 'the Code tab of the Claude desktop app',
+  'claude-desktop-3p': 'the Code tab of the Claude desktop app',
+  'claude-vscode': 'the Claude Code editor extension',
+}
+
+// ONE text, two renderings. `status` joins these into one line; `doctor` prints them wrapped. Keeping
+// a single source matters: capture_status.mjs records two copies of one answer that had already
+// drifted apart. Written for someone who has never heard of a terminal flag or a config file.
+//
+// "If you use Claude" is load-bearing. `install` also wires Codex, Cursor and Antigravity, so an
+// unqualified "Agnoclast only works in Claude Code" would be false for those seats. "Home or Chat"
+// names both labels: the desktop app's own policy code calls the surface "Chat", and the seat that
+// prompted this called it "Home".
+export const REQUIREMENT_LINES = [
+  'If you use Claude, Agnoclast only works in Claude Code: the Code tab of the Claude',
+  'desktop app, Claude Code in a terminal, or the Claude Code extension for VS Code or',
+  "JetBrains. The Claude app's Home or Chat tab can't start Agnoclast, so nothing",
+  "connects there and nothing tells you why. If that's where you are, switch to the",
+  'Code tab.',
+]
+
+/**
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {{ surface: 'code', where: string, entrypoint: string|null } | { surface: 'unknown', entrypoint: string|null }}
+ */
+export function detectSurface(env = process.env) {
+  const entrypoint = env?.CLAUDE_CODE_ENTRYPOINT || null
+  // Exactly "1", which is the only value Claude Code writes. Stricter than Claude Code's own truthiness
+  // check on purpose, because a false positive here suppresses the requirement.
+  if (env?.CLAUDECODE !== '1') return { surface: 'unknown', entrypoint }
+  // A Claude Code old enough not to set an entrypoint was still Claude Code reading this user's config.
+  if (!entrypoint) return { surface: 'code', where: 'Claude Code', entrypoint: null }
+  const where = CODE_ENTRYPOINTS[entrypoint]
+  return where ? { surface: 'code', where, entrypoint } : { surface: 'unknown', entrypoint }
+}
+
+/**
+ * What to print about the surface. Returns '' when there is nothing to say.
+ *   status: silent inside Claude Code. It runs as a SessionStart hook, its stdout lands in the model's
+ *           context every session, and there the requirement is already met.
+ *   doctor: always says something. A ✓ when the surface is known, the requirement when it is not.
+ * @param {ReturnType<typeof detectSurface>} detection
+ * @param {'doctor'|'status'} mode
+ */
+export function renderSurface(detection, mode) {
+  const known = detection?.surface === 'code'
+  if (mode === 'status') return known ? '' : `Agnoclast: ⚠ ${REQUIREMENT_LINES.join(' ')}`
+  if (known) return `  ✓ app       — running inside ${detection.where}, where Agnoclast works.`
+  return REQUIREMENT_LINES.map((l, i) => (i === 0 ? `  ⚠ ${l}` : `    ${l}`)).join('\n')
+}

package/package.json

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