@theronap/cortex-mcp 0.9.142 → 0.9.144

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/edge_extract.mjs

@@ -170,8 +170,9 @@ const PAGES_FRAGMENT =
 const OBLIGATIONS_FRAGMENT =
   '"obligations" (array of things someone must DO by a date, stated in this session. Each an object ' +
   'with "subject" (what must be done, one short phrase), ' +
-  '"due_at" (ISO 8601 date or datetime if one is stated, otherwise null — do NOT invent or infer a ' +
-  'date that was not said), ' +
+  '"due_at" (a DATE, YYYY-MM-DD, when only a day is stated; a date-time, YYYY-MM-DDTHH:MM, ONLY when a ' +
+  'time of day is actually said; otherwise null — do NOT invent or infer a date or a time that was not ' +
+  'said. A day with no time is kept as a bare date and treated as all-day), ' +
   '"evidence" (the sentence from the session that says so, copied EXACTLY and VERBATIM — it is ' +
   'checked against the transcript and the whole item is discarded if it does not match), ' +
   '"obligated_party" (exactly one of: "self" if the person whose session this is must do it; ' +

package/lib/obligations_render.mjs

@@ -0,0 +1,57 @@
+// 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.
+//
+// ADR-0059 §5.2 (Theron, 2026-09-10): a deadline with no stated time is ALL DAY, starting 00:00 local.
+// It prints "(all day)" instead of a time, reads DUE TODAY for the whole of its day, and turns OVERDUE
+// only at `overdueAfter` (the next local midnight). Without `overdueAfter`, the old rule — overdue at
+// dueAt — would call an all-day deadline OVERDUE from the first minute of its own day. A server older
+// than these fields sends neither, and gets exactly the old output.
+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 when = describeDue(o, now)
+    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')
+}
+
+function describeDue(o, now) {
+  if (!o.dueAt) return 'no deadline'
+  const day = o.dueAt.slice(0, 10)
+  const flagged = typeof o.dueAllDay === 'boolean' // absent = a server older than all-day deadlines
+  const at = new Date(o.dueAt).getTime()
+  const after = o.overdueAfter ? new Date(o.overdueAfter).getTime() : at
+  if (!flagged) return `${at <= now ? 'OVERDUE ' : 'due '}${day}`
+  const what = o.dueAllDay ? `${day} (all day)` : `${day} ${o.dueAt.slice(11, 16)}`
+  if (after <= now) return `OVERDUE ${what}`
+  if (o.dueAllDay && at <= now) return `DUE TODAY ${what}`
+  return `due ${what}`
+}

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,
@@ -76,6 +77,28 @@ 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}`
 
+// 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
+// branches the drift test names: 404 (a deployment older than this tool), a generic non-ok response
+// (classified and thrown, same as every other tool here), and 200 with or without a usable `text`.
+export async function gate5StatusFromResponse(res) {
+  // A deployment older than this tool has no such route. That is a real state (the package and the
+  // web deploy move independently — #693) and it must read as "no reading", not as an error dump.
+  if (res.status === 404) {
+    return { content: [{ type: 'text', text: 'This tool is newer than the deployment it is talking to: /api/gates/5/status does not exist there yet, so NO reading was taken. This is not an all-clear. Re-check once the console has redeployed.' }] }
+  }
+  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)
+  }
+  const body = await res.json()
+  const text = typeof body?.text === 'string' && body.text.trim()
+    ? body.text
+    : 'gate5_status received a response with no reading in it, so NO reading was taken. This is not an all-clear.'
+  return { content: [{ type: 'text', text }] }
+}
+
 // The Agnoclast MCP server (stdio). Serves the signed-in employee's scoped org
 // context to their AI assistant. CORTEX_TOKEN identifies the user + org.
 
@@ -673,6 +696,27 @@ function renderNudge(payload) {
     },
   )
 
+  // ── gate5_status — v1 gate 5's operator-access alarm (scope lock D3) ─────────────────────────────
+  //
+  // THE VERDICT AND THE WORDS ARE RENDERED SERVER-SIDE, and that is the design rather than a shortcut.
+  // gate2_status and gate3_status build their prose here, in the client, and both ended up with wrong
+  // sentences frozen in published seats that could only be shimmed around from the route (see the
+  // notes above them). /api/gates/5/status returns the finished `text`, so its wording and verdict
+  // logic deploy with the web app. This handler only transports it, and its one rule is that "no
+  // reading" must never come out as silence or as an all-clear.
+  server.registerTool(
+    'gate5_status',
+    {
+      title: 'Gate 5 operator-access alarm (ops staff only)',
+      description: 'Read v1 gate 5\'s operator-access alarm: privileged database sessions (postgres / supabase_admin, sampled every 30s) that NO break-glass declaration covers, counted since a dated, attributed, expiring baseline (ADR-0060 option 1, accepted by Theron Peterson 2026-09-10). Aggregate-only — counts by likely source, the newest unexplained time and the window; never addresses, org names or session contents. OPS STAFF ONLY: the data is cross-org, so any other caller gets an operator-only answer, which is neither an alarm nor an all-clear. It also checks this app\'s OWN database connection: if the app itself is being recorded as operator access, the alarm is reported NOT ARMED rather than red or green. A failed read is reported as NO READING, never as clean. It decides nothing — gate 5 closes by Theron\'s decision, and what it cannot see is listed on [[Agnoclast v1 — the currency gate]].',
+      inputSchema: {},
+    },
+    async () => {
+      const res = await fetchCortex(`${BASE}/api/gates/5/status`, { headers: { Authorization: `Bearer ${TOKEN}` } })
+      return gate5StatusFromResponse(res)
+    },
+  )
+
   server.registerTool(
     'session_context',
     {
@@ -2123,27 +2167,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.144",
   "description": "Connect your AI assistant to Cortex — your org's projects, activity, gaps, and directives, scoped to you.",
   "type": "module",
   "bin": {