@theronap/cortex-mcp 0.9.106 → 0.9.107

package/lib/folder_claims.mjs

@@ -13,6 +13,15 @@
 // agent holding the page open is the one with the context to make it — the same argument, and the
 // same evidence, as the per-node backlog nudge that ships beside it.
 //
+// ⚠ CORRECTED 2026-08-22, HOURS AFTER SHIPPING. The first version said "every commit to that repo
+// routes here" to every page carrying a [[repo:…]] body stamp. That is true of exactly ONE page.
+// Measured: 88 pages carry the stamp; **one** (`cortex`) holds a `repo:` ROUTE. A body stamp stopped
+// being an attach home when ADR-0026 moved homes into page_routing_identifiers — it still feeds the
+// node TIMELINE (node_timeline.ts unions identifier-derived events with explicit attachments) but
+// files nothing. So the notice was telling 87 pages to stem a flood that was not happening, and an
+// agent acting on it would have added folder claims to pages that receive no commits at all. Three
+// states, three different true things to say.
+//
 // SELF-EXTINGUISHING BY DESIGN. Once a claim exists the line stops asking and starts reviewing, so a
 // page that has been narrowed does not keep nagging every reader forever. That is the difference
 // between a nudge and wallpaper, and this repo has already recorded the day-one backlog saturating
@@ -22,27 +31,36 @@
  * PURE. The footer line for a page's folder claims, or null when there is nothing worth saying.
  *
  * @param stamps      repo stamps found in the page body, e.g. ['[[repo:theronap/cortex]]']
- * @param pathRoutes  `file:` claims the node holds, from the server
+ * @param claims      ALL routing claims the node holds (repo: and file:), from the server
  * @returns the line to append, or null
  */
-export function folderClaimLine(stamps, pathRoutes) {
+export function folderClaimLine(stamps, claims) {
   // ⚠ SILENCE WHEN THE SERVER DID NOT ANSWER, which is not the same as "no claims". A client newer
-  // than its server gets `undefined` here, and treating that as an empty array would tell every
-  // repo-stamped page to add folder claims — including the ones that already have them, whose claims
-  // this build simply cannot see. Say nothing rather than something confidently wrong; the line
-  // reappears on its own once the server is serving the field.
-  if (pathRoutes === undefined || pathRoutes === null) return null
+  // than its server gets `undefined`, and treating that as an empty list would tell every stamped
+  // page something false about claims this build cannot see. The line reappears on its own once the
+  // server serves the field.
+  if (claims === undefined || claims === null) return null
 
+  const list = Array.isArray(claims) ? claims.filter((c) => typeof c === 'string' && c) : []
+  const paths = list.filter((c) => c.startsWith('file:'))
+  const repos = list.filter((c) => c.startsWith('repo:'))
   const hasStamp = Array.isArray(stamps) && stamps.length > 0
-  const routes = Array.isArray(pathRoutes) ? pathRoutes.filter((r) => typeof r === 'string' && r) : []
 
-  // Nothing to say about a page that claims no repo and no folders — it is not in this population,
-  // and a line here would be noise on every unrelated page in the wiki.
-  if (!hasStamp && !routes.length) return null
+  // Narrowed already: show the claims and ask whether they are right. Applies whether or not a
+  // repo: route also exists — the specific claims are what a reader can actually judge.
+  if (paths.length) {
+    return `Folder claims on this page: ${paths.join(', ')}. If one of these is not actually what this page is about, correct it — a wrong claim quietly routes other people's commits here and sets their tier.`
+  }
+
+  // The genuine catch-all: it holds the repo ROUTE, so every commit really does get filed here.
+  if (repos.length) {
+    return `⚠ This page holds the repo route ${repos.join(', ')} and no folder claims, so EVERY commit to that repo is filed here — it is the catch-all. If you can tell which folders this page is actually about, claim them with \`set_routing_identifier\` (\`file:owner/repo:path/to/dir/\` — the trailing slash makes it a subtree). Claims are additive, so narrowing never drops the catch-all placement.`
+  }
 
-  if (routes.length) {
-    return `Folder claims on this page: ${routes.join(', ')}. If one of these is not actually what this page is about, correct it — a wrong claim quietly routes other people's commits here and sets their tier.`
+  // Body stamp only: a timeline, but no attachments. Saying "commits route here" would be false.
+  if (hasStamp) {
+    return `This page carries a repo stamp but claims no folders, so this repo's commits appear in its TIMELINE and none are filed to it. If specific folders or files belong to this page, claim them with \`set_routing_identifier\` (\`file:owner/repo:path/to/dir/\` — the trailing slash makes it a subtree) and they will start landing here. Many pages are about a decision rather than a directory; if that is this one, there is nothing to claim.`
   }
 
-  return `⚠ This page claims a WHOLE REPO and no folders within it, so every commit to that repo routes here. If you can tell which folders or files this page is actually about, claim them with \`set_routing_identifier\` (\`file:owner/repo:path/to/dir/\` — the trailing slash is what makes it a subtree). Claims are additive and reversible, and a narrower claim also decides the tier of records that land on it. Judge from what the page IS about, not from what happens to be attached to it.`
+  return null
 }

package/lib/server.mjs

@@ -517,6 +517,42 @@ export async function runServer(version) {
     },
   )
 
+  server.registerTool(
+    'gate4_status',
+    {
+      title: 'Gate 4 claim-coverage monitor',
+      description: 'Read the aggregate-only Gate 4 status for this brain — what SHARE of the records that arrived in the window have reached a claim, and who claimed them. The metric is coverage (claimed / arrived), never a count of claiming sessions: measured across brains, claiming-session count tracks where a backlog is being drained rather than whether the stream is being kept up with, and the brain with the fewest claimers had the best coverage. The denominator is always reported beside the ratio, because "nothing arrived to claim" and "plenty arrived and nothing was claimed" are opposite conditions that a bare percentage renders identical. Below 30 arrived records the ratio is withheld as `insufficient_volume` rather than stated. Session / sweep / unattributed claims are broken out, and the session share is reported but never thresholded — the alarm is on total coverage, and whether a clause about SESSIONS is satisfied by an automated sweep is a human judgment. It never exposes record ids, titles, payloads, reasons or session keys. "regressed" means coverage has fallen and gate 4 must NOT be considered closed.',
+      inputSchema: {
+        days: z.number().optional().describe('rolling window in days (1-90, default 14)'),
+        brain: z.string().optional().describe('brain name or org id when you belong to more than one brain; omit for a sole brain'),
+      },
+    },
+    async ({ days, brain }) => {
+      const qs = new URLSearchParams()
+      if (days != null) qs.set('days', String(days))
+      if (brain) qs.set('brain', brain)
+      const suffix = qs.size ? `?${qs}` : ''
+      const res = await fetchCortex(`${BASE}/api/gates/4/status${suffix}`, { headers: { Authorization: `Bearer ${TOKEN}` } })
+      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 status = await res.json()
+      const pct = (x) => `${(x * 100).toFixed(1)}%`
+      // The denominator and the claim breakdown are in EVERY branch, including the healthy one. A
+      // reader must never be handed a ratio without the count it was taken over.
+      const shape = `${status.arrived} records arrived in ${status.days}d (excluding the last ${status.settlingHours}h, which the daily sweep has not reached yet) — ${status.unclaimed} unclaimed, ${status.sessionClaimed} session-claimed, ${status.sweepClaimed} swept, ${status.unattributedClaimed} unattributed`
+      const text = status.status === 'insufficient_volume'
+        ? `Gate 4 coverage is NOT MEASURABLE for this brain: ${shape}. Below ${status.minArrivedRecords} arrivals the ratio is noise, so none is reported — this is not a low score, it is no score.`
+        : status.status === 'regressed'
+          ? `⚠ Gate 4 has REGRESSED: coverage ${pct(status.coverage)} of ${shape}. That is under the ${pct(status.regressedBelow)} floor — the claim clause closed ${status.gateClosedAt} does NOT currently hold and the gate must not be treated as closed. Sessions accounted for ${pct(status.sessionShare)} of arrivals. Find what stopped claiming before citing the clause.`
+          : status.machineEvidenceReady
+            ? `Gate 4's claim coverage holds: ${pct(status.coverage)} of ${shape}. Sessions accounted for ${pct(status.sessionShare)} of arrivals — if that is near zero, an automated sweep is carrying a clause about sessions, which is a human judgment and not something this monitor decides. Closed ${status.gateClosedAt}; this is the evidence continuing to hold, not a new closure.`
+            : `Gate 4 coverage is ${pct(status.coverage)} of ${shape} — above the ${pct(status.regressedBelow)} alarm floor but below the ${pct(status.healthyAt)} the closure rested on. Sessions accounted for ${pct(status.sessionShare)} of arrivals. Not an alarm and not evidence; re-check before citing the clause as live.`
+      return { content: [{ type: 'text', text }] }
+    },
+  )
+
   server.registerTool(
     'session_context',
     {
@@ -1275,7 +1311,8 @@ export async function runServer(version) {
         // evidence: a session read a page through a [[link]], saw the footer, and repaired the page.
         // The ask is deliberately self-extinguishing — once a claim exists the line changes to a
         // review prompt rather than a request, so a corrected page stops nagging.
-        const claimLine = folderClaimLine(stamps, m.pathRoutes)
+        // routingClaims (0.9.107+) carries repo: AND file:; pathRoutes is the 0.9.106 file:-only field.
+        const claimLine = folderClaimLine(stamps, m.routingClaims ?? m.pathRoutes)
         if (claimLine) footer += `\n— ${claimLine}`
         // Gate 4's per-node backlog nudge (also gate 3's KWA-36). The SERVER decides whether this
         // fires — it sends `nudge` only when 25+ records are unclaimed AND the page has gone 7+ days

package/package.json

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