@theronap/cortex-mcp 0.9.105 → 0.9.107

package/lib/folder_claims.mjs

@@ -0,0 +1,66 @@
+// The read_page footer line about FOLDER CLAIMS — pure, so CI can execute the decision.
+//
+// WHY THIS EXISTS. A page claiming a whole repo and a page claiming `web/lib/engine/` read
+// identically, and the difference decides where every future commit lands and what tier it gets.
+// Measured against prod 2026-08-22: 88 Agnoclast pages carry a `[[repo:…]]` stamp and 10 hold any
+// path claim, so ~78 silently take delivery of the entire monorepo — `cortex` alone governs 66%.
+//
+// WHY THE FOOTER AND NOT A BACKLOG, A SCRIPT, OR A MINING PASS. It cannot be mined. Today's
+// attachments come FROM the mother route, so mining them re-derives the mother (circular for
+// `cortex` and `Theron Peterson`); and for every other page a commit spanning two packages makes all
+// of its paths look like evidence for both (`cortex-mcp` mines to `web/app/api/` at 52 records — it
+// is a package). Co-occurrence is not aboutness. Which folders a page is ABOUT is judgment, and the
+// 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
+// the D9 signal as the failure mode to avoid.
+
+/**
+ * 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 claims      ALL routing claims the node holds (repo: and file:), from the server
+ * @returns the line to append, or null
+ */
+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`, 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
+
+  // 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.`
+  }
+
+  // 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 null
+}

package/lib/server.mjs

@@ -6,6 +6,7 @@ import { homedir } from 'os'
 import { join } from 'path'
 import { createHash, randomUUID } from 'crypto'
 import { fetchCortex, classify, resolveBase, resolveEnvToken, setSessionKey } from './diagnose.mjs'
+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'
@@ -516,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',
     {
@@ -1260,6 +1297,23 @@ export async function runServer(version) {
         const allBody = m.tiers.flatMap((t) => (t.sections ?? []).map((s) => s.body)).join('\n')
         const stamps = [...new Set((allBody.match(/\[\[repo:[a-z0-9][a-z0-9-]*\/[a-z0-9_.-]+\]\]/gi) ?? []).map((s) => s.toLowerCase()))]
         if (stamps.length) footer += `\n— This page carries ${stamps.join(', ')} — \`read_page "${name}"\` with history: true for its event timeline (page = present, timeline = history).`
+        // FOLDER CLAIMS (2026-08-22). A page claiming a whole repo and a page claiming
+        // `web/lib/engine/` read identically, and the difference decides where every future commit
+        // lands. Measured that day: 88 Agnoclast pages carry a repo stamp, 10 hold any path claim —
+        // so ~78 silently take delivery of the entire monorepo, and `cortex` alone governs 66%.
+        //
+        // WHY THE FOOTER RATHER THAN A BACKLOG OR A SCRIPT. This cannot be mined: today's attachments
+        // come FROM the mother route, so mining them re-derives the mother (circular), and for
+        // everyone else a commit spanning two packages makes all its paths look like evidence for
+        // both pages (`cortex-mcp` mines to `web/app/api/` at 52 records — it is a package). Which
+        // folders a page is ABOUT is judgment, and the agent holding the page open is the one with
+        // the context to make it. Same reasoning as the backlog nudge two lines down, and the same
+        // 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.
+        // 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
         // unedited — so there is no threshold logic here to drift out of sync. It rides in the footer

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@theronap/cortex-mcp",
-  "version": "0.9.105",
-  "description": "Connect your AI assistant to Cortex \u2014 your org's projects, activity, gaps, and directives, scoped to you.",
+  "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": {
     "cortex-mcp": "bin/cortex-mcp.mjs"
@@ -29,8 +29,8 @@
   ],
   "license": "MIT",
   "scripts": {
-    "release": "node scripts/release.mjs release",
-    "promote": "node scripts/release.mjs promote",
-    "rollback": "node scripts/release.mjs rollback"
+    "release": "bash scripts/release.sh",
+    "promote": "bash scripts/promote.sh",
+    "rollback": "bash scripts/rollback.sh"
   }
 }