instar 1.2.75 → 1.2.76

package/dist/server/usherRoutes.js

@@ -0,0 +1,40 @@
+/**
+ * Usher HTTP routes — the read-only pull surface for the Usher's re-surface
+ * signals + precision metrics (rung 4). Signal-only: consumers PULL; the Usher
+ * never pushes to chat and never injects.
+ *
+ *   GET /usher/signals?topicId=N   — recent re-surface suggestions
+ *   GET /usher/metrics?topicId=N   — fired / acted precision funnel
+ *
+ * Operator-facing (INTERNAL_PREFIXES). Spec: docs/specs/cwa-usher.md §3–4.
+ */
+import { Router } from 'express';
+import { z } from 'zod';
+const TopicIdParam = z.coerce.number().int().nonnegative();
+export function createUsherRoutes(deps) {
+    const router = Router();
+    const store = deps.signalStore;
+    if (!store) {
+        router.use('/usher', (_req, res) => res.status(503).json({ error: 'usher disabled' }));
+        return router;
+    }
+    router.get('/usher/signals', (req, res) => {
+        const parsed = TopicIdParam.safeParse(req.query.topicId);
+        if (!parsed.success)
+            return res.status(400).json({ error: 'topicId query param required' });
+        const limit = Math.min(50, Math.max(1, Number(req.query.limit) || 20));
+        res.json({ topicId: parsed.data, signals: store.getSignals(parsed.data, limit) });
+    });
+    router.get('/usher/metrics', (req, res) => {
+        const parsed = TopicIdParam.safeParse(req.query.topicId);
+        if (!parsed.success)
+            return res.status(400).json({ error: 'topicId query param required' });
+        const m = store.getMetrics(parsed.data);
+        // Precision = acted / fired (the read that gates rung 5; paired externally
+        // with the human-as-detector miss-map for the "what it missed" half).
+        const precision = m.fired > 0 ? m.acted / m.fired : null;
+        res.json({ topicId: parsed.data, metrics: { ...m, precision } });
+    });
+    return router;
+}
+//# sourceMappingURL=usherRoutes.js.map

package/dist/server/usherRoutes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usherRoutes.js","sourceRoot":"","sources":["../../src/server/usherRoutes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAEjC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC;AAE3D,MAAM,UAAU,iBAAiB,CAAC,IAA8C;IAC9E,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC;IACxB,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC;IAE/B,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,gBAAgB,EAAE,CAAC,CAAC,CAAC;QACvF,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,MAAM,CAAC,GAAG,CAAC,gBAAgB,EAAE,CAAC,GAAY,EAAE,GAAa,EAAE,EAAE;QAC3D,MAAM,MAAM,GAAG,YAAY,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACzD,IAAI,CAAC,MAAM,CAAC,OAAO;YAAE,OAAO,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,8BAA8B,EAAE,CAAC,CAAC;QAC5F,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QACvE,GAAG,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC;IACpF,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,GAAG,CAAC,gBAAgB,EAAE,CAAC,GAAY,EAAE,GAAa,EAAE,EAAE;QAC3D,MAAM,MAAM,GAAG,YAAY,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACzD,IAAI,CAAC,MAAM,CAAC,OAAO;YAAE,OAAO,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,8BAA8B,EAAE,CAAC,CAAC;QAC5F,MAAM,CAAC,GAAG,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACxC,2EAA2E;QAC3E,sEAAsE;QACtE,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;QACzD,GAAG,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,GAAG,CAAC,EAAE,SAAS,EAAE,EAAE,CAAC,CAAC;IACnE,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.2.75",
+  "version": "1.2.76",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-25T09:19:12.673Z",
-  "instarVersion": "1.2.75",
+  "generatedAt": "2026-05-25T19:10:38.599Z",
+  "instarVersion": "1.2.76",
   "entryCount": 191,
   "entries": {
     "hook:session-start": {
@@ -1440,7 +1440,7 @@
       "type": "subsystem",
       "domain": "server",
       "sourcePath": "src/server/AgentServer.ts",
-      "contentHash": "038365abc27a181166c64817b88b92dd4cd4fdcf33d9444040da91ba9f821f5b",
+      "contentHash": "074c270761f1a6bd512d77c09465217087d169a19d012a9b2bf76d270b5811e5",
       "since": "2025-01-01"
     },
     "subsystem:session-manager": {

package/upgrades/1.2.76.md

@@ -0,0 +1,64 @@
+# Upgrade Guide — the Usher (a quiet mid-task reminder)
+
+<!-- bump: minor -->
+<!-- minor = new features, new APIs, new capabilities (backwards-compatible) -->
+
+## What Changed
+
+**I now notice, mid-conversation, when something we set aside earlier matters again.**
+
+The memory and briefing only get consulted at two moments — when a session starts
+and right before I send a message. Between those, a context can fade out of view
+and then become relevant again, and nothing pulled it back. The Usher fills that
+gap: on each substantive message, it does one cheap check — "did this just make a
+faded, tracked context relevant again?" — and if so it leaves a quiet reminder on
+a side board.
+
+The deliberate, important part: **it is signal-only.** It writes suggestions to a
+read-only surface that's pulled (an endpoint / the dashboard); it never pushes to
+chat and never forces anything into my context. And before any future step is
+allowed to let it actually interrupt mid-task, we **measure how often its
+reminders were useful** (a precision number = acted ÷ fired) and pair that with
+the human-as-detector heat map for what it missed. The data has to earn the right
+to interrupt — that precision is written in as the hard precondition for the next
+rung.
+
+It's bounded and safe by construction: one cheap check per substantive message
+(rate-limited, backs off under quota pressure, skipped when nothing's faded),
+fire-and-forget so it can never slow a reply, and degrade-safe (no model, no
+candidates, or an error → no reminder, never a crash). On by default, with a
+kill-switch.
+
+**Evidence**: 19 new tests (13 unit — prompt/parse + refId validation, degrade
+paths, all watcher branches incl. never-throws, and the signal store; 6 boot-path
+route tests — the pull surface is alive, returns signals + precision, 503 when
+disabled, and a wiring-integrity guard that the watcher is attached to the live
+message callback). The discoverability/config suites stay green. `tsc` + lint
+clean (incl. the no-raw-model-call guard).
+
+Spec: `docs/specs/cwa-usher.md` (approved; Claude-authored + manual review —
+fuller multi-model review advisable, especially the precision definition that
+gates rung 5; caveat ratified). ELI16: `docs/specs/cwa-usher.eli16.md`.
+Side-effects: `upgrades/side-effects/cwa-usher.md`.
+
+## What to Tell Your User
+
+- **Quiet reminders when something's relevant again**: "If we set something aside
+  and it suddenly matters again mid-conversation, I'll leave a quiet note about it
+  on a side board — I won't interrupt you with it yet. We'll first check those
+  notes are actually useful before letting them ever interrupt."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Mid-task re-surface signals | Automatic (signal-only); read at `GET /usher/signals?topicId=N` |
+| Usher precision metrics | `GET /usher/metrics?topicId=N` → fired / acted / precision |
+
+## Evidence
+
+Not a bug fix — a new signal-only capability. Verified by 19 tests including 6
+that boot the real AgentServer and confirm the pull surface returns signals +
+precision and 503s when disabled, plus a wiring-integrity guard that server.ts
+attaches the watcher to the live message callback. By construction it has no
+inject/block path. `tsc` + lint clean.

package/upgrades/side-effects/cwa-usher.md

@@ -0,0 +1,82 @@
+# Side-effects review — the Usher (rung 4, signal-only)
+
+**Scope**: A signal-only mid-task watcher that re-surfaces faded-but-now-relevant
+context. Per the ratified spec (`docs/specs/cwa-usher.md`): on each substantive
+inbound turn, query the faded tail of the topic-intent store, ask a cheap LLM
+whether the turn re-activates any, and emit re-surface SIGNALS to a read-only pull
+surface. It NEVER injects (rung 5, gated on the Usher's measured precision).
+
+**Files touched**:
+- `src/core/UsherSignalStore.ts` — NEW. File-backed per-topic store of signals +
+  precision metrics (fired/acted); atomic writes; best-effort (never throws);
+  capped at 50 signals/topic.
+- `src/core/Usher.ts` — NEW. `buildUsherPrompt`/`parseUsherResponse` (anti-injection,
+  refId-validated), `createUsherCheckFn` (injected provider, degrade-safe),
+  `usherCheckTurn`/`createUsherLoop` (pre-filter reuse, shed/rate gates, faded-tail
+  = observation-tier refs, fire-and-forget, never-throws). Reacts to USER turns only.
+- `src/server/usherRoutes.ts` — NEW. `GET /usher/signals` + `GET /usher/metrics`
+  (with precision = acted/fired). 503-stub when the store is absent.
+- `src/server/AgentServer.ts` — new optional `usherSignalStore`; mount the routes.
+- `src/commands/server.ts` — construct `UsherSignalStore` (unless disabled); chain
+  the Usher loop onto `onMessageLogged` AFTER the capture chain (reusing the
+  queued subscription provider + LlmQueue); pass the store to AgentServer.
+- `src/server/CapabilityIndex.ts` — `usher` → `INTERNAL_PREFIXES`.
+- `src/config/ConfigDefaults.ts` + `src/core/types.ts` — `usher.enabled` default true.
+- Tests: unit (Usher + store) + boot-path route tests + the discoverability scan
+  now includes `usherRoutes.ts`.
+
+**Under-block**: The Usher only *emits suggestions to a pull surface* — it blocks
+nothing. Its checks are gated (pre-filter, shed, rate ceiling) and every gate
+fails toward "no signal", so it can't suppress anything either. RefIds are
+validated against the candidate set (a poisoned/hallucinated id is dropped).
+
+**Over-block**: None possible — there is no `block`/`inject` path in the code.
+A false signal costs one line on a side board the consumer pulls.
+
+**Level-of-abstraction fit**: The Usher reuses the established seam
+(`onMessageLogged`), the topic-intent store's faded tail (observation-tier refs),
+the queued subscription provider (never a raw client), and the capture loop's
+pre-filter — it adds a watcher + a pull surface, not a new subsystem. "Faded" is
+defined precisely as below-briefing-tier (observation), the genuine re-warm case.
+
+**Signal vs authority (defining constraint)**: The Usher is a pure signal
+producer. Authority to act on a signal (mid-task injection) is withheld for rung
+5, which the spec makes conditional on the Usher's measured precision. The surface
+is PULL (endpoint/dashboard), never a chat push — so even a noisy Usher can't
+train anyone to tune it out (Near-Silent).
+
+**Interactions**:
+- Chained AFTER the capture loop on the single-assignment `onMessageLogged`
+  property (prior callback preserved — verified by the wiring-integrity source
+  guard). Fire-and-forget (`void usherLoop(...)`) so Usher latency never reaches
+  the delivery path.
+- One fast-tier LLM call per substantive USER turn, background lane on the shared
+  LlmQueue, rate-limited (20/60s/topic), skipped under QuotaTracker pressure, and
+  skipped entirely when the topic has no faded candidates — same cost envelope as
+  capture. Agent turns are skipped (capture handles those).
+- `precision = acted/fired` on `/usher/metrics` is the read that rung 5's spec
+  will cite as its precondition; pairs with the human-as-detector miss-map.
+- Construction broadened nothing — the assembler/capture wiring is unchanged; the
+  Usher is purely additive within the existing `sharedIntelligence` block.
+
+**External surfaces**: `GET /usher/signals`, `GET /usher/metrics` (INTERNAL
+prefix). New config `usher.enabled` (default true). New modules `Usher.ts`,
+`UsherSignalStore.ts`. No injection, no chat push, no change to existing routes.
+
+**Deferred (tracked)**: mid-task injection (`cwa-injection`, gated on this
+rung's precision), per-tool-call seam (`cwa-usher-tool-seam`), capability/standards
+descriptors as candidates (`cwa-capability-index-context`).
+
+**Rollback cost**: Low, strictly additive. Remove the watcher wiring + routes +
+store; nothing depends on it (rung 5 isn't built). Kill-switch `usher.enabled:
+false` stops the watcher (routes 503). No data migration.
+
+**Migration parity**: Additive watcher wiring + routes + config default
+(existence-checked) + INTERNAL prefix — all server-side (every agent on update).
+The signal store is created lazily; no schema migration. No hook/template/skill change.
+
+**Convergence honesty**: Claude-authored + manual review; multi-model tooling
+absent on host. The Usher is deliberately the safe half (signal-only, pull
+surface, precision-measured before rung 5 earns authority), but a fuller review —
+especially of the `acted` precision definition that gates rung 5 — remains
+advisable before relying on it.