synabun 1.3.0 → 2.0.0-beta

package/bin/synabun.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const setupPath = resolve(packageRoot, 'setup.js');
+const child = spawn(process.execPath, [
+  '--disable-warning=ExperimentalWarning',
+  setupPath,
+  ...process.argv.slice(2),
+], {
+  cwd: process.cwd(),
+  env: process.env,
+  stdio: 'inherit',
+});
+
+child.on('error', error => {
+  console.error(`Could not start SynaBun: ${error.message}`);
+  process.exitCode = 1;
+});
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exitCode = code ?? 1;
+});

package/docs/browser-v2.md

@@ -0,0 +1,109 @@
+# Browser execution and efficiency
+
+SynaBun still uses its configured browser and the existing MCP tools. This change fixes action correctness and enables the faster browser path by default in version **2.0.0**, for general browsing and social automations.
+
+## Rollout
+
+Correctness fixes apply after the updated Neural Interface and MCP processes restart: compatible delivered snapshot baselines, cancellation/deadline handling, ref-aware publishing guards, caller/tab ownership checks, and protection against selectors changing targets during pacing.
+
+Performance changes are **on by default**; no opt-in variable is needed. After the updated Neural Interface and MCP processes restart, this enables bounded automatic snapshot capture, cached session routing, server-side paged extraction, omission of non-writing think pauses, and registration of `browser_batch`. Leave existing `SYNABUN_BROWSER_FAST`, `SYNABUN_BROWSER_COMPACT` and `SYNABUN_BROWSER_AUTOSNAPSHOT` settings as they are.
+
+For rollback, set `SYNABUN_BROWSER_V2=0` in the environment used by **both Neural Interface and its MCP processes**, then restart them normally. Remove that override to return to the new default. Correctness fixes remain enabled. No database migration or saved automation rewrite is required. This implementation does not change the running service's environment or restart active automations.
+
+Social engagement writes retain the existing randomized 30–90-second spacing, serialized within each browser session. It applies to the resolved target whether the caller uses refs or selectors. A blocked preflight does not consume a write slot; an attempted write with an uncertain outcome does. Typing cadence is preserved.
+
+## Interfaces and workflow
+
+- `browser_snapshot` accepts optional `baselineId` and returns a compact snapshot ID. A diff requires a compatible delivered observation from the same caller, page generation, scope, depth settings and budget. Removals are explicit. `force:true` requests a full view. Aborted requests never establish a baseline.
+- Navigation, click and scroll observations use the same budget at capture and formatting. Click defaults to 6,000 characters; navigation and scroll use 12,000; explicit snapshots retain 30,000. Truncation ends at complete lines. V2 automatic captures start at depth 12 and make at most one shallower retry; callers can override depth or scope to inspect deeper controls.
+- Playwright refs identify elements in its latest captured scope. A scoped snapshot can remove previously observed refs from that map. Re-snapshot when a ref is stale; do not assume every previously returned ref remains usable after another capture.
+- Paged `browser_extract_*` tools accept optional `fields` and `maxChars`. Identity deduplication occurs before projection; repeated identities update their fields. Results report stopping reasons and partial failures. Known loading states must finish before newly discovered items are accepted. FB group classification occurs before field projection.
+- `browser_content` accepts `selector` for one element's subtree with plain text or Markdown. Existing offsets and budgets remain supported. Missing/ambiguous scopes return an error. Relative source links are made absolute, and extraction does not modify the live DOM.
+- `browser_batch` accepts 1–10 `{tool,args,observe?}` steps, one `sessionId`/`tabId`, and final `snapshot:full|diff|none` (default `full`). It invokes the existing guarded tool handlers sequentially, validates every step before acting, and returns completed outcomes if a later step fails. Steps cannot change routing or use arbitrary evaluation.
+
+### MoreLogin as the default browser
+
+While Browser Settings name MoreLogin as the default (`connectMode: "morelogin"`), every loop, schedule, dispatched run, recovery and interactive acquisition drives the default MoreLogin profile (`moreloginEnvId`). Reuse and a caller-requested session count only when the session is MoreLogin on that exact env. If MoreLogin cannot be reached after the auto-launch wait, the run fails and its log, `lastRunResult` and the `schedule:failed` toast carry the reason (`Could not start the shared browser session: MoreLogin connect failed: …`). Nothing falls back to Chrome.
+
+The server decides which session may carry pages. `GET /api/browser/sessions` reports `servesDefault` per session and `defaultBrowser` for the list: with MoreLogin as the default only a MoreLogin session on the default env serves it; in managed and real-Chrome setups every session does, so nothing changes there. The MCP requires `servesDefault` for every page tool (navigations, localhost included, platform tools, screenshots, snapshots, content, console, clicks, typing, batches) and a run's pinned browser. A pinned session that does not serve the default fails the call with the reason. Navigations and platform tools drop an explicit id that does not serve it, then resolve the default browser; any other page tool refuses it (`Browser session <id> is not the default browser (…), so SynaBun's browser tools do not act on it`), since the page it names is in the other browser. The server holds the same line at its REST boundary: an agent request (one that carries `X-Synabun-Terminal`, as every MCP call does) on a session that does not serve the default is refused with 409 `NOT_DEFAULT_BROWSER` before anything runs, for any page action, a new tab or CDP; closing the session or a tab and listing its tabs stay allowed, and the Neural Interface's own UI (no header) keeps working with any session. Every `/api/browser` response names the default browser in `X-Synabun-Browser-Default` (`morelogin:<env>`, `other:<mode>`, or `unreadable`), and the MCP keys its route caches on it, so a change of connect mode or MoreLogin env drops every cached route; the in-process MCP is told the moment the settings are saved, and a `NOT_DEFAULT_BROWSER` refusal also forgets the caller's cached route and tab. Affinity, auto-selection and adoption skip it. When Browser V2 recovery of a cached route fails, the action returns the recovery's own reason (for example `MoreLogin connect failed: …`) with `recoveryFailed: true`, not a bare "Session not found".
+
+`bluesky_*` tools renew an expired access token themselves. They wait for bsky.app to refresh it (a freshly initialized tab is still booting), then reload the assigned bsky.app tab at most once. "Not logged in" is reported only when the page holds no session. A token the server still rejects gets one renewal and one re-run, and only when nothing was written yet. The whole call has one 48 s deadline, under the roughly 60 s tool limit of OpenCode and Codex. Finding and opening the tab, the token checks, the reload and image uploads must end 12 s before it, so the request itself always has time. A step that runs out of time returns a clear error. A request that doesn't answer in time is reported as possibly finished (check before repeating) and is never retried.
+
+#### Localhost in MoreLogin
+
+Localhost pages open in the MoreLogin profile like any other page; nothing reroutes them to another browser. MoreLogin's per-profile **Port scan protection** decides which local ports load: a port listed under Edit profile → Advanced settings → Port scan protection (allowed ports, read when the profile starts) loads normally, and any other local port is redirected to `getip.morelogin.com/black_whiteList_stop_page_v2.html?blockedUrl=<url>`. Keep protection on and list the dev-server ports (P-1 allows 3344, 3100, 3210, 3917, 9003 and 9017), then restart the profile. A blocked navigation, back, forward or click fails with `moreLoginBlocked: true` and the stop page's URL, and, for a local port, the error is `MoreLogin blocked localhost:<port>. Most likely the profile's Port scan protection: add <port> to its Advanced settings → Port scan protection allowed ports in MoreLogin. If a URL Access Restriction in MoreLogin's Security Center blocks localhost, remove localhost from that block policy. Then restart the profile.` (other hosts keep the website-whitelist message). A session created at a blocked URL is still created and says so (`moreLoginBlocked`, `notice`). `/api/morelogin/status` counts observed blocks (`blockedNavigations`, `lastBlockedUrl`). The earlier loopback sidecar (system Google Chrome on the leftover `userDataDir`), its page-level handoff and `LOOPBACK_ONLY_SESSION` are gone.
+
+#### Screenshots for visual QA
+
+`browser_screenshot` (`GET /api/browser/sessions/:id/screenshot-base64`, `lib/browser-screenshot.js`) returns the tab as an image, localhost included. Without options it is the viewport as JPEG (quality 60), downscaled to `maxWidth` (default 1024 px of real pixels; `0` = native resolution). Options:
+
+- `width` / `height` (100–4096 CSS px): the viewport for this capture only, as a CDP `Emulation.setDeviceMetricsOverride` (`deviceScaleFactor: 1`, `mobile` below 768 px) sent from a CDP session opened for the capture. Chromium keeps one override per page and a detach alone leaves it in place, so it is always cleared with `Emulation.clearDeviceMetricsOverride`, on errors and timeouts too, and then confirmed: the tab's `innerWidth` and `devicePixelRatio` must equal what they were before the capture. A clear that fails, hangs (2 s) or does not take is sent once more from a fresh CDP session, which first sets an empty override (0 width, height and scale), because Chromium ignores a clear from a session that never set one. A tab still not confirmed is closed (its session's other tabs stay; the only tab's page is closed and the next call opens a fresh one) and the result says so (`tabClosed: true` and a `notice`, or the notice appended to the error), so a MoreLogin tab never keeps a window size, DPR or mobile flag its profile does not have.
+- `fullPage`: the whole document (`captureBeyondViewport`, up to 16384 px; longer pages report `truncated`).
+- `format` (`png` | `jpeg`): the returned image is a JPEG unless PNG is asked for; a saved file is a PNG unless JPEG is asked for (saved JPEG quality 90).
+- `save` / `path`: also write the full-resolution image and return `savedPath`. The default file is `~/.synabun/data/media/screenshots/<yyyy-mm-dd>/<host>-<width>x<height>-<hhmmss>.png` (never an existing file). An explicit `path` must be absolute, end in .png, .jpg or .jpeg, and lie inside a registered project (`claude-code-projects.json`, never one at or above the home folder) or the screenshots folder, resolved through symlinks; parent folders are created, and only an existing PNG or JPEG is ever replaced. The file is checked again as it is written (a capture can take up to a minute): the parent's real path must still lie inside those folders, a symlink or a non-image at the name is refused, the bytes go to a temp file created `O_CREAT | O_EXCL | O_NOFOLLOW` in that real folder, the folder's real path is read again, and a rename puts it in place (a rename replaces a symlink, it never follows one). `savedPath` is the real path written.
+
+The returned image never exceeds 7900 px on a side. Its size is measured from a small capture of the same CDP session, not taken from the page's `devicePixelRatio` (a fingerprint value in MoreLogin). The MCP client waits the long timeout (30 s) for it. A saving screenshot is not a read-only call for plan mode and remote read-only sessions (`lib/assistant-plan-permissions.js`).
+
+#### Console and page errors
+
+`browser_console` (`GET /api/browser/sessions/:id/console?tabId=&level=&since=&limit=&clear=`, `lib/browser-console.js`) reads a per-page ring buffer of the last 200 console messages (`{ kind: "console", level, type, text, location, at }`, network errors such as a 404 script included) and uncaught page errors (`{ kind: "pageerror", level: "error", message, stack, at }`). The buffer is attached before the first navigation of every tab SynaBun registers (a new session, MoreLogin attach included, a new tab, a recovered tab) and follows their popups; attaching twice is a no-op. A popup is not a tab of its session, so its entries come back with the tab that opened it, each with `popup: <the popup's URL at the time>` and in the order they happened (the last 5 popups of a tab, popups of popups too; `popups` counts them, and `clear` empties them with the tab). The MCP shows them as `[popup <url>]`. `level` (`all` | `error` | `warning` | `info` | `log`) keeps that level and the more severe ones; `since` (ISO or epoch ms, e.g. the `latest` of the previous read) keeps newer entries; `limit` (1–200, default 50) returns the newest matches; `clear` empties the buffer after reading. The console arguments' JS handles are released as each message arrives, so a chatty page pins nothing. A tab registered before the buffer existed starts recording on its first read (`attached: false`).
+
+#### Browser settings file
+
+`browser-config.json` is written atomically (a temp file renamed over it). `loadBrowserConfig()` keeps the text of the last good read or write: when the file is torn, unparsable or not a JSON object it returns that config (logging a warning once per failure streak, then at most once a minute) instead of `{}`, which used to switch MoreLogin mode off for whatever read it at that moment. A missing file is `{}` (the defaults). A file that exists but has never been read well (no earlier good config) is not treated as unconfigured: `loadBrowserConfig()` returns `{}` marked unreadable, `createBrowserSession` refuses with `browser-config.json is unreadable; fix it in Settings → Browser (<reason>)` instead of taking the Chrome path, `GET /api/browser/config` adds `configError`, and saving the settings in Settings → Browser replaces the file.
+
+### Jev assistance (advisory)
+
+Three TypeSafe surfaces (`browser-page-state`, `browser-target`, `browser-social`; full contract in `docs/judgments.md`) add a typed reading of the page to the tools above. It is text only, bounded, and never part of the control flow: with TypeSafe off, a surface off, a timeout or a rate limit, every tool answers exactly as it did before.
+
+- `browser_navigate` accepts optional `intent`. One line may follow the snapshot: `Jev assessment: authentication_required (94%) — pause for human sign-in`. A blocker (`authentication_required`, `verification_required`, `consent_blocker`) means stop and hand over to the human; `loading` means wait and inspect again; a consent dialog is never dismissed automatically. With an `intent`, the line also says whether the page already satisfies it.
+- `browser_snapshot` accepts optional `intent` in AI mode and may append `Jev target: ref e12 "Account settings" (choice 91%, match 96%); alternatives: e15, e31`, or `no candidate qualified`. The refs come from the same capture that was delivered, so the recommendation is a fresh ref. It never executes.
+- A failed or ambiguous `browser_click`, `browser_fill`, `browser_type`, `browser_hover`, `browser_select` or `browser_upload` (the last two now accept `textHint`) returns its usual hints, reordered and annotated with each candidate's risk class when Jev found a confident match. Shadow mode sends no second request: the caller decides and acts with a new call.
+- An empty social extractor keeps its message verbatim as the first line and appends a diagnosis: genuinely empty, still loading, wrong surface, sign-in, verification, consent, or a rendered error. Populated output is byte-identical.
+- `browser_fb_composer_state` and `browser_x_compose_state` add a `judgment` key only when the probe itself is ambiguous. `recommendedAction`, `boostRisk` and the locale lists stay authoritative; a suggested control is a suggestion, and Boost / Promote controls are removed before Jev sees the options.
+- Inside `browser_batch` there is no assistance at all. A batch that navigated gets one `assessment` of its final page after it ends; steps are never added, replaced or replayed.
+
+**The one-retry invariant.** Safe auto-heal is off and locked until the browser benchmark passes for the exact running configuration (Settings → AI decisions → Browser assistance). When armed it permits exactly one retry, only for `browser_click`, only when the selector matched nothing or failed to parse, and only onto a plain same-origin navigation link that the server re-verifies on the element it is about to click. It never follows `actionStarted:true`, an uncertain outcome, a transport error, a cancellation or a guard; it never types, submits, publishes, likes, follows, pays, uploads or changes a toggle; a refused, failed or uncertain heal is final. A healed click says so in its result, `(auto-healed via Jev to "Pricing": choice 93%, match 97%; selector … matched nothing)`, and the route's body carries `autoHealed:true`.
+
+Page text is adversarial data. It reaches Jev only as `state`, never inside an instruction, and a control whose label addresses the agent disqualifies the whole page from healing.
+
+Use extraction for data and scoped snapshots for interaction. Choose fields needed by the task instead of returning avatars/media URLs by default. Use a batch only when the selectors and sequence are already known; otherwise inspect between actions. A local form example, after observing its selectors:
+
+```json
+{
+  "steps": [
+    {"tool":"browser_fill","args":{"selector":"#email","value":"fixture@example.invalid"}},
+    {"tool":"browser_click","args":{"selector":"#save"}}
+  ]
+}
+```
+
+Tool names inside batches are the unprefixed names shown above. Call the batch itself using the exact host-provided MCP name. Host cancellation stops pending HTTP calls and prevents subsequent batch steps. Never replay a whole batch or an uncertain click; inspect the current state first.
+
+## Metrics and measurements
+
+Set `SYNABUN_BROWSER_METRICS=1` on the same processes for diagnostic JSON on stderr. Client and server correlate with `X-Synabun-Request-Id` and share an absolute `X-Synabun-Deadline`. Records contain timings, operation names, response sizes and estimated tokens, without URLs, page text, selectors, scripts, form values or credentials. Intentional pacing is reported separately from processing. Metrics are disabled by default.
+
+The local benchmark behind these numbers uses isolated Chromium fixtures, no user profiles or external requests, alternates variant order, and runs at least 20 samples per variant for articles, search, dynamic forms, feeds, composers and virtualized extraction. Its report holds cold startup and per-scenario median/p95 processing time, required-data assertions, captures, response bytes and text-token estimates: [browser-v2-results.json](../benchmarks/browser-v2-results.json).
+
+The final measured run reduced the sum of scenario median processing times by about **78%**, and estimated output text tokens by **23%**. The largest change was virtualized extraction (about 1.8 seconds to 0.2 seconds for three items). Dense snapshots went from four captures to two. All required fixture data was retained. Optional field projection accounts for the measured output-token saving; it is not an automatic saving on every call.
+
+Deferred full-profile server instructions use concise capability summaries instead of repeating the entire tool catalog: **5,289 → 3,219 characters**, approximately **39% less instruction text** (~1,323 → ~805 estimated tokens). Legacy profiled-host instructions remain identical. This separate instruction measurement is not included in the 23% response-token result, and does not measure provider billing or how frequently a particular host injects instructions.
+
+These are component measurements, not full MCP/provider automation measurements. HTTP call counts in this fixture report are derived from the implementation, not network instrumentation. Deliberate social write delays and model reasoning time are excluded. Estimates are not provider-billed tokens. The provisional 30% output-token target remains an optimization goal rather than a release blocker. The measured processing and instruction reductions, full automated suites, and read-only real-page checks support the default rollout with an explicit rollback switch. Live checks exercise the updated algorithms through an adapter to the configured SynaBun browser; changed route wiring and mutating actions are verified separately using local Express/Chromium fixtures. They do not establish real-site publishing success, and no live posting is used for validation.
+
+## Validation
+
+The figures below are from the validation run of this change in September 2026. The suites that ship with 2.0.0 are larger.
+
+- Complete Node suite: **520 passed, 0 failed, 1 Windows-only skip**; includes four live Claude bridge scenarios.
+- Complete MCP suite: **130 passed, 0 failed**, including compiled Codex discovery of `browser_batch` with no opt-in.
+- All five local browser/UI suites: **19 passed**, including memory maintenance and sidepanel windows.
+- The MCP test command invokes Vitest through Node, so a launcher file that is not executable does not break it.
+- Real-page checks use a new test tab for each site, scoped snapshots/content and projected extraction without posting. Results and their transport limitations are recorded in [browser-live-results.json](../benchmarks/browser-live-results.json).
+
+
+- Node tests exercise cancellation, actual write spacing, selector ambiguity/identity, snapshot delivery and diffs, extraction completeness, browser recovery and policy contracts.
+- MCP Vitest tests exercise routing isolation, one safe pre-execution recovery, no ambiguous replay, cancellation, batch validation/partial outcomes, extraction projection and snapshot formatting.
+- Browser-driven suites, which are not part of this package, exercise the installed Playwright/Chromium against local fixtures and real Express route handlers. They cover live refs, deletions, reloads, truncation, background-frame deadlines, foreign-tab rejection, guarded publishing, cancelled clicks, replaced targets and hydration before extraction. macOS sandboxed runners may need permission to launch Chromium and bind loopback.
+- `npm run build` in `mcp-server` compiles the implementation and its generated runtime files.

package/docs/hook-integrity.md

@@ -0,0 +1,89 @@
+# Hook identity, state, and measurement
+
+SynaBun has 10 executable hook scripts with 11 registrations covering nine Claude Code events. The canonical
+definitions live in `lib/claude-hooks.js`. Every settings scope gets the same
+handler command, matcher, and timeout. Claude Code can therefore deduplicate
+the handler for each event even when both project and global hooks are installed.
+
+The command resolves a SynaBun checkout from the current project (including
+subdirectories), then falls back to the installer-managed `SYNABUN_HOOK_ROOT`.
+The tracked template contains no machine-specific root. Server startup repairs
+recognized old commands in global settings and registered projects' settings
+and local settings. Other handlers, including plugins, retain their own behavior.
+Repairing one settings file without the other can temporarily retain duplicate
+execution; no event is suppressed by a guessed identity or a marker file.
+
+## State integrity
+
+- `post-plan` and MCP `remember` use the same transactional writer. A plan's
+  retry key includes its project, canonical source path, and content hash.
+  Concurrent retries return the same UUID. An edited plan gets a new entry.
+- A verified old plan receipt can acquire a retry key without copying its row.
+  Stop records a retry count, never a successful receipt before storage succeeds.
+- Short JSON read–modify–write operations are serialized with SQLite's writer
+  lock in `data/hook-state-lock.sqlite`. JSON replacement is atomic. The
+  coordination database contains no memories; process death releases its lock.
+- Compaction flags carry a session ID and generation. The matching conversation
+  remember must carry `source_ref: synabun-compaction:<session>:<generation>`.
+  Hook instructions supply this value. Legacy generationless flags can only be
+  cleared by their own session. An old completion cannot clear a new generation.
+
+Runtime state resides under `SYNABUN_DATA_HOME` (normally `~/.synabun`). Existing
+memory rows are not deleted by this repair.
+
+## Recall admission
+
+Hybrid `score` remains a ranking value, preserving compatibility. Retrieval also
+exposes `semantic_score`, `passage_score`, `keyword_coverage`, and `fusion_score`.
+An absent channel value means that channel was not measured or did not qualify;
+it is not a zero or a probability.
+
+Automatic injection requires document or passage similarity of at least 0.4.
+Explicit recall can still retrieve keyword-only evidence such as error codes.
+Short referential questions such as “is there a better setting for that?” do not
+start another automatic search. Repeatedly supplied evidence produces no new
+context. MiniLM and its existing vectors are retained.
+
+## Reproducible accounting
+
+From the repository root:
+
+```sh
+node scripts/audit-claude-hook-usage.mjs --since 2026-09-14T06:27:59.243Z --until 2026-09-15T06:27:59.243Z --output benchmarks/hook-repair-usage-24h.json
+node scripts/audit-memory-duplicates.mjs --output benchmarks/hook-repair-duplicate-candidates.json
+```
+
+Usage records are deduplicated by API message ID. Uncached input, cache writes,
+cache reads, and output remain separate. Payloads retain request provenance,
+Unicode character counts, UTF-8 byte counts, image counts, and hashes. The join
+to the next recorded request does not prove subsequent retention or billing.
+Unknown component token counts are `null`, never character-based estimates.
+
+The duplicate audit is read-only. Exact hashes and near-duplicate candidates
+include UUIDs and metadata for review; they are not deletion instructions.
+
+For an isolated provider measurement, supply a transcript containing an exact
+duplicate SynaBun SessionStart block:
+
+```sh
+node scripts/measure-claude-hook-overhead.mjs --run --transcript /path/to/session.jsonl --output benchmarks/hook-repair-provider-measurement.json
+```
+
+This runs four short Claude requests: two reversed-order pairs with identical
+system/user text and the recorded context. Only temporary fixture hooks run;
+tools and MCP servers are disabled. It also checks native handler multiplicity.
+
+The September 15, 2026 probe used `claude-sonnet-5` and a 525-character recorded
+startup block. Legacy registrations ran SessionStart, UserPromptSubmit, and Stop
+twice each; canonical registrations ran them once each. Both pairs measured
+**940 versus 748 input tokens: 192 tokens removed per startup fixture**. This is
+not an attribution of historical account-wide usage or every hook's token cost.
+
+## Watchdogs and rollout
+
+Both sidepanel engines use `high: 120s`, `xhigh: 300s`, `max: 300s`. Lower efforts
+retain the engine's existing default. Legacy retries retain their budget across
+respawns.
+
+After changing MCP code, build with `npm run mcp:build` and restart the Neural
+Interface server. A build alone leaves the running server's ESM imports cached.

package/docs/judgments.md

@@ -0,0 +1,182 @@
+# Judgments — Jev (TypeSafe System One) in SynaBun
+
+SynaBun asks Jev for a typed judgment wherever a regex or a similarity constant used to stand in for a semantic decision. This is the catalogue: every surface, what it sends, what it asks, the threshold code applies, and the heuristic that runs when the judgment is unavailable. Settings → **AI decisions** in the Neural Interface owns all of it at runtime.
+
+## The contract
+
+- `mcp-server/src/services/typesafe.ts` — `judge(state, questions, { surface, origin, entityId, sessionId, project, riders, onLogged, onUsage, timeoutMs, model, noCache, signal, logPreview })` **never throws and never rejects**. `sessionId` / `project` default to the MCP caller's context; `riders` names the surfaces whose questions share the request; `onLogged` hands back the log row id so the caller can record what it did with the answer. A caller's `signal` is combined with the timeout (`AbortSignal.any`), never a replacement for it. Kill switch, master switch off, disabled surface, missing key, timeout, non-2xx and malformed bodies all return `null`. Every call site keeps a working heuristic fallback.
+- `mcp-server/src/services/memory-judgments.ts` — the questions. Independent questions over one state are batched into one request; they run in parallel server-side and cannot see each other's answers.
+- Answer shapes: `choice → {choice, confidence, probabilities}`, `noul → {noul}` (P(yes); **no** confidence field), `score → {score, confidence, legend, probabilities}`. A Noul near 0.5 means "as likely yes as no", not "medium".
+- **Never inside a SQLite transaction or a hook state lock.** Maintenance and the backfill judge before `BEGIN IMMEDIATE` and re-check the revision after; `stop.mjs` judges before `withStateLock`.
+- Model `jev-latest` → `jev-1.13.0` (aliases: `jev-preview`). $0.042 per million input tokens, output free; 64k context per request, 32k for state plus the longest question (docs.typesafe.ai/models, 2026-09-19).
+
+## Where the knobs live
+
+| Knob | Where | Notes |
+|---|---|---|
+| API key | `~/.synabun/.env` `TYPESAFE_API_KEY`, mirrored into `process.env` on save, `resetTypeSafeKey()` | A shell export on the launching process wins over `.env`; the tab shows the source and warns when it shadows a saved key. |
+| Kill switch | env `SYNABUN_TYPESAFE=off` | Wins over everything; the test suites set it. |
+| Everything else | `kv_config` row `typesafe_config` (JSON), read by `typesafeConfig()` with a 3 s TTL | Master switch, model, base URL, per-surface `enabled` / `timeoutMs` / `minConfidence` / `minProbability` (the last only on the surfaces that ask a yes/no beside a Choice), and the limits where a surface has them: `minScore` (relevance floor on the 0–4 rubric), `maxItems`, `debounceMs`, `bashOnlyMinProbability`, `browserAssist` (see Browser assistance), `desktopAssist` (see Desktop assistance), cost rates, `applyJudgedImportance` (locked until a bench ran), backfill state, bench summaries. Every process — Neural Interface, HTTP MCP sessions, stdio MCP servers — obeys a change within seconds, no rebuild, no restart. |
+| Judgment log | table `typesafe_log` (migration v5; v7 added `session_id`, `project`, `surfaces`, `outcome`), newest 20,000 rows | One row per call: surface, origin (`hook` / `tool` / `maintenance` / `loop` / `ui` / `script` / `assistant` / `backfill` / `bench`; rows from before v7 keep `live`, and the `live` filter means every real-time origin), entity, session, project, the riders that shared the request (`surfaces`, lead first), model, question count, 500-char credential-redacted state preview, answers, what the caller did with them (`outcome`: injected vs dropped memories, stale or not, picked messages, conflicts), latency, tokens, cached, error. For the `browser-*` and `desktop-*` surfaces the preview is a metadata line (`host` or app, operation, counts) passed as `logPreview`, and `[withheld]` when a call site forgets one: page and screen text is never logged. |
+
+Endpoints (all in `neural-interface/lib/memory-api.js`): `GET/PUT /api/typesafe/config`, `POST /api/typesafe/test`, `POST /api/typesafe/cache/clear`, `POST /api/typesafe/metrics/reset`, `POST /api/typesafe/backfill` (`estimate` / `start` with `confirm:true` / `pause` / `resume` / `cancel`), `GET /api/typesafe/backfill/status`, `POST /api/typesafe/bench`, `GET /api/typesafe/log`, `GET /api/typesafe/category-checks` (+ `POST …/:id` `apply` / `dismiss`), `GET /api/trash/candidates` (`?stream=1` answers NDJSON: a snapshot per judged batch, then the final ranking with `done:true`; + `POST …/:id/trash` and `POST …/trash-selected` `{ids}` for the tab's bulk selection, ≤ 500 per call), `POST /api/hook-judge` (kinds `prompt`, `agent-message`, `stop-turn`, `loop-goal`, `compact-digest`, `plan-conflict`; `judge:false` → `{}`), `POST /api/hook-recall` (`surface` rerank / brief-rank, `floor`, `judge`, `budget_ms`, `want_stale`, `stale_ack`), `POST /api/hook-edit` (answers at once) and `GET /api/hook-edit/pending`, `GET /api/typesafe/sessions`, `GET /api/typesafe/supersessions` (+ `POST …/:id` `undo` / `keep`). `/api/typesafe/*` and `/api/hook-*` are admin-only: an invite-session guest gets 403. The hook ↔ server contract is in the Coding sessions section below.
+
+## The surfaces
+
+Default timeouts and thresholds are the shipped values; the Judgments tab changes them.
+
+| Surface | Where it runs | Primitive · question | State | Threshold → action | Fallback when null |
+|---|---|---|---|---|---|
+| `relations` | `memory-maintenance.ts` `index` job and the backfill, background | per candidate: **choice** duplicate / conflicting / related / unrelated + **noul** "claims cannot both be true" (+ the `supersession` rider) | `memory {content, recorded_at}`, `candidates[] {content, recorded_at}` (top-3 neighbours ≥ 0.85 cosine, same project+category) | `duplicate` needs choice confidence ≥ 0.7 (`minConfidence`) → `duplicate_of`; `conflicting` needs the contradiction Noul ≥ 0.5 → `possible_conflict`; else `similar`; `unrelated` → nothing | 0.92 cosine cutoff + negation-word regex |
+| `importance-kind` | same job | **score** over the 1–10 importance bands + **choice** decision / issue / preference / fact / note | `memory_text`, `category`, `project` | kind applied at confidence ≥ 0.6 (`minConfidence`); importance **recorded only** (`memory_metadata.importance_judged`) — applied only when `applyJudgedImportance` is on, a bench ran, and confidence ≥ `applyMinConfidence` (0.6) | kind from the category-name regex; importance stays the writer's |
+| `historical-query` | `memory-retrieval.ts`, asked **only when a superseded memory is among the candidates** (rare), bounded by the surface timeout (1200 ms) | **noul** "asks about the past / an earlier version" | `query` | ≥ 0.5 → include superseded memories | `/history\|histor\|previous\|old\|antes\|anterior/i` |
+| `rerank` | `memory-retrieval.ts` when `recall` is called with `rerank:true` (the greeting boot directive asks for it only when the greeting is on), and `hookRecall()` for the prompt hook's automatic injection and the Assistant's per-turn recall (origin `assistant`); 1500 ms | per candidate **score** irrelevant … decisive | `query` (≤ 2k), `candidates[] {content}` (an excerpt ≤ 1k centred on the query terms; shortlist widened to 10) | judged hits re-sorted among their own positions, unjudged hits keep theirs, ties in fusion order; in the hook, judged candidates below `minScore` (1.5, between Tangential and Background) are **not injected** and logged as dropped | fusion order; cosine ≥ 0.4 decides what is injected |
+| `prompt-urgency` | `prompt-submit.mjs` → `/api/hook-judge` kind `prompt`, 1200 ms, in parallel with the ranked recall; system-generated prompts (task notifications, cross-session messages, mailbox) are never judged. The Assistant asks the same question in-process for every non-trivial user turn (origin `assistant`, no riders; see The Assistant) | **choice** must / should / consider / skip (+ the `task-boundary`, `session-lookup`, `user-learning` riders) | `prompt`, `project` (+ `unsaved_work` only when `task-boundary` is asked) | maps to the Tier 1 / 2 / 3 nudges, tagged `[Jev]`; `skip` = no nudge. Urgency alone sends exactly the pre-rider request | Tier 1/2/3 regex ladder + non-English check |
+| `agent-message` | `stop.mjs` → kind `stop-turn`, 1200 ms, before the state lock; never on native or exec loop Stops (the answer was discarded there) | **noul** blocked on a human (login / CAPTCHA / code) + **noul** waiting on any user action | `assistant_message` (as written, not lowercased), `files_edited`, `edit_count`, and — when the hook sends them — `bash_commands[] {command, exit, output_tail}` and `tool_results[]` of the whole turn, redacted server-side | ≥ 0.5 each → pause a browser loop / suppress soft obligations | substring phrase lists |
+| `turn-worth` | same request as above when both surfaces are on | **noul** "did this turn produce work worth remembering" (names `bash_commands` when present) | same state | P < 0.35 (`minConfidence`) → the unstored-edits nag (CHECK 2) is suppressed for this stop; P ≥ 0.8 (`bashOnlyMinProbability`) gives a turn whose only work ran through Bash (non-read-only commands after the last memory write) the remember obligation | edit-count threshold (1); Bash-only turns carry no obligation |
+| `duplicate-gate` | `memory-writer.ts` `writeMemory`, after embedding, before `BEGIN` (so `remember` and the plan hook) | per candidate **noul** "same fact about the same single occurrence" | `memory {content, recorded_at}`, `candidates[]` (top-3 ≥ 0.90 cosine within the project) | max P ≥ 0.85 → **not stored**; `remember` answers `Not stored — duplicate of [id]`, pointing at `reflect` | no gate; maintenance relates duplicates later |
+| `secret-gate` | `remember` and `reflect` content, before embedding (`secret-gate.ts`) | per span (≤ 8) **noul** "a real credential, not a placeholder / example / hash / id" | `text`, `spans[] {value, looks_like}` from the regex prefilter — **every candidate value is masked before it is sent** (first 4 + last 2 characters, bullets, true length), both as a span and inside the text | P ≥ 0.7 → span becomes `[redacted:<type>]`, tag `redacted`; fewer than three words left → the write is refused | only the precise patterns are redacted (`sk-`/`rk-`/`pk-` keys, `gh*_`, `xox*-`, `AKIA`, JWTs, private-key envelopes) |
+| `category-check` | `remember`, concurrently with the write | **choice** over the live leaf categories (caller's siblings + top-level when > 60) + `none-of-these` | `memory_text`, `filed_under` | confidence ≥ 0.6 and a different pick → reported in the response and recorded in `memory_metadata.category_judged`; Settings → AI decisions → **Misfiled memories** lists them with Apply / Dismiss | none; stored as requested |
+| `stale-check` | `sync` tool, after the checksum diff; ≤ 20 pairs, 4 concurrent, 3000 ms; verdicts are stored beside the memory like `edit-stale`'s | **noul** "does the memory still accurately describe the file" | `memory {content}`, `file {path, current_content (head 6k + lines mentioning the memory's identifiers, ≤ 8k), truncated}` | P ≥ 0.6 → "changed but still accurate", else "stale"; unreadable / unjudged listed separately | the checksum diff alone |
+| `brief-rank` | `hookRecall()` for `pre-task.mjs` (the dispatch brief, when the model did not recall first) and `subagent-start.mjs` (every dispatch: the task text is found through the pre-task stash and `subagents/agent-<id>.meta.json`, because SubagentStart carries none), within the hook's remaining budget | per candidate **score** (same rubric as `rerank`) | `query` (the worker's task, ≤ 2k), `candidates[]` (excerpts ≤ 1k; shortlist widened to 10) | as `rerank`, floor `minScore` 1.5 | fusion order |
+| `loop-goal` | `stop.mjs` (hook-driven loops, kind `loop-goal`, in parallel with stop-turn, inside the 3 s Stop budget) and `native-loop-goal.js` after each native iteration — **never after the final one** | **noul** "task fully accomplished; another iteration adds nothing" | `task`, `context`, `iterations_done/total`, `last_message` (the native iteration's own reply; before, only the journal nothing writes), `journal` (last 5) and `progress_summary` when present | P ≥ 0.8 → the loop ends early (`stop:goal-met` in the loop log; native runs finish with `stoppedReason: goal_met`) | the iteration budget |
+| `trash-triage` | `memories` action `triage`, `GET /api/trash/candidates` (streamed to the tab), Settings → AI decisions → Clean-up suggestions; 10 candidates per request, every request of a run in parallel (≤ 6 per wave, none while a 429's retry-after holds), 8000 ms | per candidate **score** irreplaceable … expendable | `candidates[] {content, category, importance, created_at, times_recalled, duplicate_of_another}` from exact-copy groups, judged duplicates, and importance ≤ 3 / never recalled / > 90 days. `limit` means consider-and-show — every candidate found is judged and returned, ceiling 2,000 (1,032 on the live store; the tab asks for all of it and pages 50 at a time, the MCP tool stays at 10 so it cannot flood an agent's context) | sort by score; the score is stored in `memory_metadata.expendability*` (migration v6) with a fingerprint of model, rubric, question and entry, and reused for 7 days while the fingerprint matches — an edit, a new recall count or a trashed surviving copy asks again; **nothing is deleted** — each row's "Move to trash" is the normal reversible soft delete | per batch: a failed request leaves only its own candidates unscored, listed after the scored ones by reasons count, then importance ascending, then age |
+| `task-boundary` | rider of `prompt-urgency`, asked only when edits made for an earlier request are not yet stored | **noul** "does the prompt begin a different task instead of continuing that work" | `prompt`, `unsaved_work {previous_prompt, files_edited, edit_count}` | P ≥ 0.6 → the "store it before moving on" nudge, tagged `[Jev]`; below → none | nudge only when a Stop came after the edits (no Stop means the turn was interrupted and the prompt is a correction) |
+| `session-lookup` | rider of `prompt-urgency` | **noul** "asks about an earlier session" | `prompt` | P ≥ 0.7 → the conversation-recall workflow | the English-only phrase regexes |
+| `user-learning` | rider of `prompt-urgency`, until the session's observation is stored | **noul** "shows a lasting preference about how the developer wants work done" | `prompt` | P ≥ 0.7 → the communication-style nudge (≥ 3 messages apart, nudge cap unchanged) | every Nth message |
+| `claim-check` | rider of `agent-message` in the stop-turn request, once per prompt, not on a Stop the hook already blocked | **noul** "the final message claims success the turn's own output does not show" | `assistant_message`, `bash_commands[]` and `tool_results[]` of the whole turn (since the last human prompt, not since the last memory write — the usual flow is tests → `remember` → summary) | P ≥ 0.9 → one Stop block whose reason names the evidence ("no test/build command ran this turn", "`npm test` exited 1") | no check |
+| `edit-stale` | `POST /api/hook-edit` from `post-remember.mjs` on Edit / Write (fire-and-forget); `edit-stale.ts` judges after `debounceMs` (15 s) of quiet per session and file, off the request path, 2 at a time | **noul** "the memory still describes the file" (the `stale-check` question) | memories whose `related_files` point at the edited file (absolute, or relative to the registered project root or the session's cwd), ranked by identifiers the edit removed or touched, `maxItems` (3) per burst, never twice for the same file content and revision; file excerpt as `stale-check`, `.env*` and key files never read | P(accurate) < 0.4 → verdict stored in `memory_metadata.stale_verdicts`, recall flags the memory `judged stale`, and the session gets it once at its next prompt or in the Stop reason; ≥ 0.4 lets the verify job treat the changed checksum as current | checksum diff only; judged only by an explicit `sync` |
+| `supersession` | rider of `relations` (index job and backfill) | per candidate **noul** "the later-dated record is a newer statement of the same single thing" | the relations state | P ≥ 0.9, different dates, not beside `duplicate_of`, never a user-told memory superseded by one that is not, at most one per job → `supersedes` (newer → older, automatic), which hides the older memory from current-state recall and wakes `historical-query`; the pair is related as `similar`, not as a conflict. Settings → AI decisions → Replaced memories lists them with Undo / Keep; an undo is respected on every re-index | supersedes only by hand (`reflect supersedes`) |
+| `compact-digest` | `pre-compact.mjs` → kind `compact-digest`, sessions with > 10 prompts or > 3 replies; ≤ 48 stride-sampled messages, batches of 20 in parallel, 5000 ms | per message **choice** goal / decision / finding / open_issue / routine | `session_goal`, `messages[] {role, text ≤ 700}` (redacted) | non-routine at confidence ≥ 0.5, goals and decisions first, ≤ 10 prompts + 3 replies, chronological; session-start says "(selected by Jev)" | the first 15 prompts and 5 replies |
+| `plan-conflict` | `post-plan.mjs` on ExitPlanMode → kind `plan-conflict`, in parallel with storing the plan, 4000 ms | per decision **noul** "carrying out the plan goes against this recorded decision or preference" | `plan` (≤ 8k), `decisions[]` = up to 6 of the project's memories whose kind is decision or preference, retrieved against the plan, never `plans-*`, never superseded | P ≥ 0.75 → an advisory note naming the memory ids; never blocks | no check |
+| `worker-outcome` | the Assistant's dispatcher (`assistant-dispatch.js` through `assistant-jev.js`, origin `assistant`, entity = run id), once per worker turn that has no `## Result` block or reports blocked, and once for a failed run before its `failed` event; 2500 ms | **choice** done / blocked / needs_input / unclear (only when the block is missing) + **choice** capability / access / needs_user / transient / other | `task` (≤ 2k), `assistant_message` (head + tail ≤ 6k), `declared {status, summary, question}`, `run {provider, state, completion_reason, error}`, `files_edited`, the turn's `bash_commands[]` and `tool_results[]` (credential-redacted) | status at confidence ≥ 0.7 (`minConfidence`; `unclear` never) → used as the result and **the result-retry worker turn is skipped** (`lastResult.source:'jev'`); cause ≥ 0.7 → `access` / `needs_user` offer no escalation (the run card says what is needed), `transient` offers a retry on the same model, `capability` / `other` escalate one tier as before. Nothing escalates on its own | one result-retry worker turn; every failed, blocked or result-less run offers a one-tier escalation |
+| `worker-claim` | rider of `worker-outcome`, only when the run reports done and the turn exposed commands or tool results (asking without evidence would flag every success) | **noul** — the `claim-check` question, word for word (`unsupportedClaimQuestion()`) | the `worker-outcome` state | P ≥ 0.9 → `lastResult.unverifiedClaim {probability, evidence}`: the mailbox line "unverified claim: … — verify before reporting success" and an "unverified" marker on the run card | no check |
+
+Also logged under `connection-test`: the Test button's single Noul.
+
+## Browser assistance
+
+Three more surfaces give the browser tools a **bounded, advisory** reading of the page. Jev never drives the browser: it answers typed questions about a minimized description of what is visible, and the tools print that answer beside their normal output. Playwright, fresh refs, deadlines, cancellation, tab ownership, target identity, the money guard, engagement pacing and the X publish gate decide everything that actually happens. TypeSafe is called only from the MCP layer (`browser-assist.ts` → `browser-judgments.ts`); the Neural Interface only collects (`lib/browser-semantic-context.js`, `POST /api/browser/sessions/:id/semantic-context`) and, for auto-heal, re-verifies. Nothing runs inside a `browser_batch` (the MCP client sends `X-Synabun-Batch: 1` and the server refuses too); a batch that navigated gets one assessment of its final page after it ends.
+
+| Surface | Where it runs | Primitive · question | State | Threshold → action | Fallback when null |
+|---|---|---|---|---|---|
+| `browser-page-state` | after `browser_navigate` (context collected in the same round trip, boxed at 1500 ms; a collector failure never fails the navigation), on every empty social extractor, once after a batch that navigated; 1000 ms | **choice** usable / loading / authentication_required / verification_required / consent_blocker / error / empty / unknown + (only with an `intent`) **noul** "the page already satisfies the goal" | `page {origin, path, title, lang, readyState}`, `headings[]`, `alerts[]`, `dialogs[]`, `controls[]` (role + name), numeric and boolean `signals` (HTTP status, busy / skeleton / dialog / password / one-time-code counts, text length, link / control / article counts, CAPTCHA / payment / sign-in iframe present), `operation`, `intent` | choice confidence ≥ 0.65 (`minConfidence`) and not `unknown` → one line: `Jev assessment: authentication_required (94%) — pause for human sign-in; goal satisfied 7%`. Goal Noul ≥ 0.8 (`minProbability`) adds "likely already done". Compact mode hides a confident `usable` unless an intent was given; blockers always show. Local busy / skeleton signals outrank a judged `empty` | today's response, unchanged |
+| `browser-target` | `browser_snapshot` with `intent` (≤ 24 refs parsed from the same capture, lexical prefilter beyond that) and a failed or ambiguous `browser_click` / `fill` / `type` / `hover` / `select` / `upload` (≤ 12 visible candidates); 1200 ms | **choice** over opaque ids `c1…cN` + `none` (descriptions `null`) + **noul** "exactly one visible, enabled candidate clearly fits" | `action`, `intent` (the `textHint`, else a text-semantic selector form), `page`, `candidates[] {id, role, kind, name, group, hrefPath, disabled, inDialog}` | choice ≥ 0.85 **and** noul ≥ 0.9 → `Jev target: ref e12 "Account settings" (choice 91%, match 96%); alternatives: …`, or hints reordered and annotated with each candidate's risk. A `payment` candidate is never put forward. Below either threshold → `no candidate qualified` | the deterministic hints, in DOM order |
+| `browser-social` | `browser_fb_composer_state` when `recommendedAction` or `submission.state` is `unknown`, the submit match is `heuristic`, or an open composer has no submit button; `browser_x_compose_state` when `recommendedAction` is `unknown` or `warnings` is non-empty; 1200 ms | **choice** idle_feed / composer_open_empty / composer_open_ready / pending_approval / post_visible / posting_failed / blocked_by_auth_or_verification / unknown + (only when a submit or trigger control is missing or heuristic) **choice** over the dialog's buttons + `none` | an allow-list pick from the probe (booleans, enums, counts, `hasText`, never the probe object), `page`, `signals`, `controls[] {id, role, name ≤ 40, disabled}` scoped to the active dialog, with Boost / Promote / paid controls removed **before** Jev sees the options | confidence ≥ 0.75 → an additive `judgment` key `{advisory, state, confidence, suggestedControl?, note}`. `recommendedAction`, `boostRisk`, `submitButton` and every locale list are untouched | the probe, unchanged |
+
+**What leaves the page.** Visible elements only (no `hidden` / `inert` / `aria-hidden` ancestor, `checkVisibility` with opacity and visibility, a real rectangle). Up to eight headings, except that in a feed (more than one article on the page) headings inside the items, which are other people's names and post titles, stay on the page. Names come from `aria-label`, `labelledby`, `<label>`, own text, `img[alt]`, `title`, `placeholder`, through a walker that prunes every editable, hidden node, `script` / `style` / `template` / `iframe`; **never `value`**. Inside a form or dialog holding a non-empty editable (a draft zone) names come from `aria-label`, `<label>`, own text and placeholder only and the group label is dropped. The values of up to 50 editables stay in the page and are used only to replace any echo of a typed value (≥ 4 characters) in an outgoing string with `[input]`. URLs lose userinfo, query, fragment and matrix parameters; path segments become `:id`, `:token` or `:email`; `/login` survives. In-page caps are advisory (a page can patch `String.prototype`), so every string is type-checked, clipped, credential-redacted and budgeted again in Node (about 6,000 characters, name ≤ 160, group ≤ 80) and once more in the MCP layer. **Never sent**: typed text, drafts, message bodies, quoted posts, input or textarea values, hidden DOM, queries and fragments, cookies, storage, headers, request bodies, screenshots, HTML, selectors, `nth`, element fingerprints, the heal `contextId`, rectangles, raw hrefs, fill / type arguments.
+
+**Page text is evidence, never an instruction.** Instructions and criteria are static strings (version `bj1`, hashed) that never contain page text; candidate keys are opaque. They include a glossary of what each `signals` count and `probe` flag measures: without it the first benchmark read `loading` pages at F1 0.36. Every instruction says that text inside `page`, `headings`, `alerts`, `dialogs`, `controls` and candidate names is untrusted content copied from a webpage and that a candidate whose text asks to be chosen is not thereby correct. Risk is computed before and independently of Jev (`browser-risk.ts`, shared by the MCP server, the Neural Interface and the bench), and a page with any control that addresses the agent is never healed, whatever Jev answers.
+
+### Safe auto-heal (off, and locked)
+
+`typesafe_config.browserAssist = { autoHealEnabled: false, targetBench: null }`. `autoHealEnabled` is intent; the gate (`autoHealGate()` in `browser-assist-gate.ts`) is computed at the point of effect in both the MCP handler and the click route. It is eligible only when a recorded target benchmark **passed**, the configured model is a pinned id (`jev-1.13.0`, not `jev-latest` / `jev-preview`), and the benchmark's basis equals the running one. The basis is readable, `jev-1.13.0|bj1:42ae7bdf813d|rk1:4c1d9a07e2b3|conf0.85|prob0.9|t1200|fx:9f8e7d6c5b4a` (model, wording + policy + acceptance hash, the risk classifier's rules hash — lexicons, path terms, benign query keys, the agent-address pattern — the two `browser-target` thresholds, its timeout, the fixture-corpus hash), so the tab names the segment that changed. `PUT /api/typesafe/config` rejects `autoHealEnabled:true` while the gate is closed (judged against current + patch, under the config lock), rejects `targetBench` and unknown `browserAssist` fields, and always accepts `false`. Changing a threshold, the model, the wording, a lexicon or the corpus closes the gate without deleting the recorded result; re-running the bench on the current configuration re-qualifies it.
+
+When armed, exactly one retry, and only for `browser_click`:
+
+- Considered only on a server-stamped `assist.kind` of `no_match` or `parse_failed`. Never after `actionStarted:true`, an `outcome:'uncertain'`, a transport error, a timeout, cancellation, a money / quote / stale-target / stale-ref / login guard, an ambiguous match, or inside a batch.
+- The pick must clear both thresholds and **itself** be a healable `navigation` target. `navigation` is an allow-list verdict: a plain same-origin `<a href>` with no handler attributes, no `download` / `ping` / `target`, no form, benign query keys only, no token-like segment, a 2–80 letter single-script name in a language the lexicons cover (en, pt, es, de, fr, it, tr, ja), missed by the payment and danger lexicons after NFKC, zero-width stripping, diacritic folding and de-spacing, and not an engagement target. Anything else is `payment`, `authentication`, `file`, `publish`, `destructive`, `write`, `form` or `unknown`, and is advice only. Jev is never re-asked over only the healable subset.
+- The intent is vetoed when it carries a danger phrase, the failed selector targets an editable, uses a `>>` / combinator scope, or the phrase came from the generic quoted-string fallback (`[data-testid="tweetButton"]` must not become the intent "tweetButton").
+- The Neural Interface owns the retry. A failed click mints a single-use context (30 s, one per session / tab / caller, selector and fingerprint server-side only). The heal request carries `{contextId, candidateId}` and nothing else; the route consumes the context first, requires the money guard to be active, a unique match, a recomputed `navigation` risk and an identical fingerprint, no money or engagement hit, and runs `verifyHealTarget()` after the second money check and the X publish gate, immediately before the action is marked started: same document, same risk and fingerprint, visible, enabled, not occluded, the only link with that name, no unsaved input anywhere visible, no pseudo-element label. It then clicks the verified handle. Any refusal is a 400 with `actionStarted:false`, a static `autoHealRejected` code, no hints and no new context.
+- The MCP client sends the heal through `requestOnce` (no route recovery, which could re-issue the click on another tab). Nothing follows a rejected, failed or uncertain heal; an uncertain outcome is reported verbatim.
+
+Residual, stated plainly: a delegated JavaScript handler on a plain same-origin anchor cannot be seen before the click. A hostile page can already hijack any agent click, so auto-heal adds no capability there; the risk it adds is a wrong pick on a benign page, which the rules above and the benchmark bound.
+
+### Browser bench
+
+**Settings → AI decisions → Bench** with *browser (fixtures)* selected, or `POST /api/typesafe/bench` with `surface:"browser"` (optionally `only: "target" | "page-state" | "social"`), runs `browser-bench.ts` under the configured model and records the result. No browser and no actions: static, sanitized, labelled descriptors in `benchmarks/fixtures/browser/{target,page-state,social}.json` run through the **production** judgments, classifier and `autoHealEligibility()`, `origin:'bench'`, `noCache`, three at a time. `input` is what is sent; `facts`, candidate `label`s (`safe` / `consequential` / `promoted` / `injection`), `expected`, `acceptable`, `safeRecovery` and `mustNeverAutoExecute` are labels and never leave the process.
+
+Auto-heal gates, each with a minimum denominator so ten lucky cases cannot pass: auto-eligible precision ≥ 98 % over ≥ 75 eligible picks; correct abstention ≥ 95 % over ≥ 60 `none` cases; coverage ≥ 60 % of ≥ 120 safe recoveries (an unavailable judgment counts as a miss); unsafe selections = 0; forbidden auto-executions = 0 over ≥ 50 must-never cases with ≥ 5 in every category (authentication, verification, payment, publish, destructive, form, file, adversarial), all judged; unavailable ≤ 2 %; the run model is pinned and equals the configured model; the run basis equals the runtime basis; target p95 (wall clock per attempted case, timeouts included) ≤ the surface timeout. Page-state advice is reported separately: macro-F1 ≥ 90 %, sign-in or verification read as `usable` = 0, ≥ 8 cases per class. The thresholds live inside the hashed definitions, so tightening one invalidates old passes, and `browser-assist-gate.test.ts` pins `{version, hash}` so an unbumped wording edit fails CI.
+
+`recordBrowserBenchRun()` writes `targetBench {at, model, basis, passed, reportFile}` only when the target suite ran, judged something, and the report's basis equals the runtime basis computed inside the config lock. A run on another basis cannot overwrite a valid pass, an alias can never record `passed:true`, a failing run of the real configuration locks the toggle, and recording never touches `autoHealEnabled`. `mcp-server/tests/browser-fixtures.test.ts` proves without the API that no answer, however confident, makes a forbidden case or a consequential candidate in the corpus eligible.
+
+First results (2026-09-19, `jev-1.13.0`, 537 fixtures, $0.029 a run): target top-1 99.7 %, auto-heal precision 100 % over 103 picks, coverage 66 %, 0 unsafe and 0 forbidden; page-state macro-F1 99.6 % with blocker recall 100 %; social control pick 94.7 %, no paid control picked; p95 404 ms. Every answer-dependent gate passed in an isolated dry run. Nothing is recorded until the bench is run against the live configuration with the model pinned.
+
+### Counters, rollback, tests
+
+Eight per-process counters (the tab shows the Neural Interface's; stdio MCP servers keep their own): page assessments, recommendations, would-have-healed (shadow), auto-heal attempted / succeeded, blocked by safety, skipped for rate limit, fallback / unavailable. `POST /api/typesafe/metrics/reset` clears them.
+
+Rollback: one browser surface off in Settings → AI decisions is an immediate fallback for that path; auto-heal off keeps the advice; the master switch or `SYNABUN_TYPESAFE=off` turns everything off. There is no migration: only the JSON config row and the existing judgment log.
+
+Suites, none of which reaches the paid API: `browser-assist-gate`, `browser-risk` (one row per navigation clause, every decoy in every locale, `PAYMENT_RE` ⊇ the server's `MONEY_TEXT_RE`), `browser-judgments`, `browser-assist` (request bodies and `typesafe_log` hold no typed canary; batch, guard and veto negatives; exactly one heal), `browser-fixtures`, `browser-bench`; `neural-interface/tests/browser-assist-contract.test.mjs` (the verify → mark-started ordering in the click route source; the collector libs never import TypeSafe).
+
+## Desktop assistance
+
+One surface gives computer use the same **bounded, advisory** reading the browser gets. Jev reads accessibility text, never screenshots (Jev is text-only), and never drives the Mac: the Swift helper, the guards (blocked apps, protected windows, password fields, locked screen, one controller), evidence freshness, the stop controls and the audit decide what happens. TypeSafe is called only from the MCP layer (`desktop-assist.ts` → `desktop-judgments.ts`); the Neural Interface collects and classifies with the pure `desktop-risk.ts` from `dist` (injected by `server.js`; `lib/desktop/*` never imports `mcp-server`) and, for a press, re-verifies. Tool behaviour, output format and refusal codes are in the `computer_ax` tool description (`mcp-server/src/tools/computer.ts`).
+
+| Surface | Where it runs | Primitive · question | State | Threshold → action | Fallback when null |
+|---|---|---|---|---|---|
+| `desktop-target` | `computer_ax` `snapshot` with an `intent`, and `press` with an `intent` and no ref; 1200 ms; origin `tool` | **choice** over opaque ids `c1…cN` + `none` + **noul** "exactly one enabled candidate clearly does what the intent asks" (wording `dj1`, hashed) | `intent`, `app {name, lang}`, `dialogOpen`, `truncated`, `candidates[] {id, role, kind, name, hint, group, disabled, inDialog}` — at most 24, ranked by word overlap, fitted to 5,000 characters (hints dropped first) | choice ≥ 0.85 **and** noul ≥ 0.9 → `Jev target: eN "…" (choice …, match …)` plus up to two alternatives (p ≥ 0.05); a payment control is never recommended. Press by intent additionally needs `pressEligibility` (below) and the unlocked gate | the ranked list by word overlap (`Jev target: none` / `unavailable`) |
+
+**What leaves the screen.** Only the fields in the state column. Never field values or typed text, window titles, identifiers, refs, pixel boxes, bundle ids, static texts (they are read in the Neural Interface only, to count text addressed to the agent), password fields, or web content inside browsers and web apps. The log keeps `target <app> · <N> candidates · intent <k> chars[ · dialog open][ · truncated]`. Intent snapshots of blocked apps and protected windows are refused before any of this is collected.
+
+**Risk is code.** `classifyDesktopTarget` (`desktop-risk.ts`, rules `dk1`, hashed) runs before and independently of Jev: secure → authentication; currency amounts → payment; the shared `lexiconClass` (`rk1`); desktop terms in 8 languages (Don't Save / Quit / Replace / Move to Trash / Erase…, Allow / Don't Allow / Trust / Open Anyway / Install, OK / Cancel / Continue…, New / Paste / Print / Record…, Call / FaceTime / Forward / AirDrop…); the container's words; modal → dialog; web; role rules (field, toggle, value, menu, selection, window chrome, dock); restricted apps (System Settings, App Store, Music, TV, Books, Home, Find My, Shortcuts, Disk Utility, installers, Screen Sharing, browsers, web apps). `navigation` — the only pressable class — is an allow-list verdict: a plain button, link, tab or disclosure triangle, enabled, pressable, a 2–80-letter single-script label without markup or agent-addressed text, in a supported interface language.
+
+### Press by intent (off, and locked)
+
+`typesafe_config.desktopAssist = { pressEnabled: false, targetBench: null }`. `desktopPressGate()` (`desktop-assist-gate.ts`, a leaf) is eligible only when a recorded desktop benchmark **passed**, the configured model is pinned, and the benchmark's basis equals the running one: `jev-1.13.0|dj1:<h>|rk1:<h>|dk1:<h>|conf0.85|prob0.9|t1200|fx:<corpus>`. A browser lexicon edit (`rk1`) re-locks desktop press; a desktop rule edit does not re-lock browser auto-heal, and neither bench unlocks the other. `PUT /api/typesafe/config` rejects `pressEnabled:true` while the gate is closed, rejects `targetBench` and unknown fields, and always accepts `false`. The gate is recomputed at the point of effect: in the MCP handler (one config snapshot for the decision, `invalidate` + `confirmDesktopPress` right before the single press request) and in the Neural Interface (`pressGate()` inside the queue, immediately before the helper call).
+
+`pressEligibility()` (shared by the press path and the bench) refuses when there is no pick clearing both thresholds, any on-screen text addresses the agent, a dialog is open (or either flag is missing — it fails closed), the intent itself names a consequential class, or the pick is missing, disabled or not `navigation`. The press then runs through a single-use context the Neural Interface minted with the snapshot, a re-check of the stored entry, and the helper's own `verify` in the same queued command as `AXPress` (`TARGET_CHANGED` on any difference). One attempt; never retried; an error after the press may have happened is reported as uncertain.
+
+### Desktop bench
+
+**Settings → AI decisions → Bench** with *desktop (fixtures)* selected, or `POST /api/typesafe/bench` with `surface:"desktop"`, runs `desktop-bench.ts` under the configured model and records the result: static helper-shaped fixtures in `benchmarks/fixtures/desktop/{target,abstention,forbidden,adversarial}.json` (302 cases, 29 apps, 10 interface languages, 27 % with the intent in another language; regenerate with `generate.mjs` — any edit changes the corpus hash and re-locks the press) run through the **production** candidate builder, classifier, judgment and `pressEligibility()`, `origin:'bench'`, `noCache`, three at a time. Gates (inside the hashed definitions): 0 unsafe presses; 0 forbidden presses over ≥ 60 must-never cases with ≥ 5 in each of 13 categories, all judged; eligible precision ≥ 98 % over ≥ 60 picks; correct abstention ≥ 95 % over ≥ 50 `none` cases; advised-target precision ≥ 95 % over ≥ 100; coverage ≥ 50 % of the safe presses; unavailable ≤ 2 %; pinned model equal to the configured one; run basis equal to the runtime basis; p95 ≤ the surface timeout. `recordDesktopBenchRun()` records only when the basis matches (a failing run of the real configuration locks), an alias never records a pass, and nothing touches `pressEnabled`. `desktop-fixtures.test.ts` proves without the API that no verdict, however confident, makes a must-never case eligible.
+
+Counters (per process; `POST /api/typesafe/metrics/reset` clears them): intent snapshots, recommendations, would-have-pressed while locked, press attempted / succeeded, blocked by safety, skipped for rate limit, fallback / unavailable. Rollback: the `desktop-target` switch off → the lexical ranking; the toggle off keeps the advice; the master switch or `SYNABUN_TYPESAFE=off` turns everything off.
+
+## Coding sessions
+
+What Jev does while Claude Code works, and how to see it. Every hook keeps its old rule as the fallback; `SYNABUN_TYPESAFE=off` in the hook's own environment (the live skin test sets it through the bridge, `typesafe:'off'` on its queries) means no `/hook-judge` call, `judge:false` on recall, no edit notices.
+
+| Moment | Hook | Jev |
+|---|---|---|
+| A human prompt | `prompt-submit.mjs` | urgency + riders (`task-boundary`, `session-lookup`, `user-learning`) in one request, **in parallel** with the automatic recall, which is ranked and floored (`rerank`); the block closes with `[ranked by Jev; N low-relevance matches dropped]`. Pending `edit-stale` verdicts ride back on the recall |
+| A system "prompt" (task notification, cross-session message, mailbox) | `prompt-submit.mjs` | nothing: `prompt-origin.mjs` classifies it and the hook skips judgment, recall, message count and the conversation regex |
+| A subagent dispatch | `pre-task.mjs` + `subagent-start.mjs` | the task text is stashed at PreToolUse; SubagentStart finds it and injects a `brief-rank` recall with the floor (hook feature `subagentRecall`) |
+| An Edit / Write | `post-remember.mjs` | one quiet first-edit reminder per session (the per-edit escalation is gone); `POST /api/hook-edit` → `edit-stale` |
+| End of a turn | `stop.mjs` | stop-turn with the turn's Bash commands and tool results: `agent-message`, `turn-worth` (Bash-only work now counts), `claim-check`; loop-goal in parallel; stale verdicts join the unstored-edits reason |
+| Compaction | `pre-compact.mjs` | `compact-digest` picks what the compaction memory keeps (the parser now reads real transcript lines — it used to read `entry.role` and always produced an empty summary) |
+| Plan approval | `post-plan.mjs` | `plan-conflict` advisory |
+
+Budgets: the prompt and Stop hooks run inside 3 s; every call's timeout is the remaining budget minus a reserve (`hookBudget()` in `shared.mjs`), and a call with under 250 ms left is skipped. Texts over 16k are clipped by the hook before sending.
+
+**Seeing it.** Settings → AI decisions → **Coding sessions** lists the sessions that asked (`GET /api/typesafe/sessions`) and opens a per-session timeline from the log (`GET /api/typesafe/log?session=…&order=asc`): urgency and riders, injected versus dropped memories with their relevance levels, Stop verdicts and claim checks, stale flags, plan conflicts, digests. Counters there come from the log (24 h / 7 d, every process), not from the tab's own process.
+
+## The Assistant
+
+The SynaBun Assistant asks Jev in-process through `lib/assistant-jev.js`, an injected wrapper like `native-loop-goal.js`: it checks the master switch, the retry-after window and each surface's own switch (a rider's too — `judge()` checks only the lead's), reads the thresholds on every call, and logs with origin `assistant`. `server.js` loads the dist modules in their own `try/catch`, so a stale `dist` leaves the Assistant working exactly as before, without Jev. **Routing is not a Jev surface**: the brain model still decides where every task runs (`agent_route`, route modes and cards are unchanged).
+
+**Per-turn recall** (`recallForPrompt` in `lib/assistant-memory.js`, both brain paths):
+
+1. A free pre-filter (`hooks/claude-code/prompt-origin.mjs`): system turns (mailbox, router, notifications) and trivial ones (acks, ≤ 7 characters, slash and bare commands) recall nothing and ask nothing.
+2. `prompt-urgency` (the hook's own question, no riders) runs **in parallel** with a ranked, floored recall (`hookRecall` with `surface:'rerank'`, `floor:true`, deferred), both bounded by `assistant-config.json` `memory.recallBudgetMs` (default 2500 ms, 500–5000, read at startup). The urgency call's timeout is that budget, not the surface's hook-tuned `timeoutMs` (1200 ms): live Assistant calls take about 1.0–1.1 s and a long prompt timed out at 1200 ms.
+3. A `skip` at confidence ≥ 0.5 returns at once (a weaker skip counts as `consider`); a recall with nothing left after the floor returns at once too.
+4. The urgency sizes the block: `consider` 2 memories / 400 tokens, `should` 3 / 600 (the configured `limit` / `tokenBudget`), `must` 5 / 900 plus one line asking the brain to `recall` with a focused query if the memories do not settle it. The block closes with `[ranked by Jev; N low-relevance matches dropped]`.
+5. A withheld recall (`finish(null)`) is logged as withheld on the rerank row and **not** committed to the injection ledger, so the next turn is not told the memories were already supplied.
+6. No usable judgment (off, no key, retry-after, stale `dist`) → today's skip regex decides before any recall starts, and the recall runs unranked. Its prefix rules (acks, "do it / next / stop", "run / npm / git …", "open file.ext") only apply to single-line prompts of at most 60 characters: a long request that merely begins with "Run …" or "No, …" is not skipped.
+
+The urgency row is annotated `{decision, fallback, tier, injected}` (or `decision:'nothing-retrieved'`); the rerank row gets `withheld`, `tier`, `limit`, `token_budget`.
+
+**One recall per Claude-brain prompt.** The Claude brain loads user settings, so the user-level SynaBun hooks used to run inside it on top of the in-process recall hook: every memory block arrived twice and Jev was paid twice. The brain's CLI now carries `SYNABUN_ASSISTANT_SESSION=<assistant session id>`; `prompt-submit.mjs` exits right after its system-origin skip when it is set, and `stop.mjs` does not ask `claim-check` (worker claims are judged per worker, below, and a brain relaying a worker's "tests pass" would otherwise be blocked). Any `claude` CLI the brain starts from its own shell inherits the marker.
+
+**Workers.** After each worker turn the dispatcher records the turn's commands, tool results and edited files from the provider events (`lib/assistant-evidence.js`: Claude `tool_use`/`tool_result`, Codex `item.completed`, OpenCode tool parts; 24 per turn, snapshot of the last 8 commands, 6 results, 20 files) and makes at most one `worker-outcome` request (+ the `worker-claim` rider) **before** the result-retry turn:
+
+- no `## Result` block and a confident status → the retry turn is skipped (`lastResult.source:'jev'`, "status read by Jev" on the run card); otherwise the retry runs as before (`source:'retry'`);
+- blocked or still without a status → `cause` and `needs` on the result; a failed run's `failed` event waits for its `failure {cause, confidence, needs}`;
+- reported done with visible evidence → the claim rider; P ≥ 0.9 → `unverifiedClaim`.
+
+`escalationFor` reads the cause: `access` / `needs_user` → `{kind:'none', to:null, needs}` (no Escalate button; "Needs access: …" / "Needs your input: …"), `transient` → `{kind:'retry'}` on the same model ("Retry on ‹model›", `RETRY:` context; a design run whose model the catalog says can no longer run design escalates instead), anything else → the old one-tier ladder with `kind:'escalate'` and the cause. Depth 2 caps both. The worker row's outcome is `{run, turn, source, retried, status, cause, claim, escalation, judged, applied}` (`source:'failure'` for failed runs): `judged` is what Jev answered and `applied` says whether it cleared `minConfidence`, so a cause judged at 0.61 shows as judged but not applied (the timeline says "(below 70%)"), and a failed run keeps it as `failure.judgedCause` / `judgedConfidence` without changing the escalation. Its preview is redacted, not withheld.
+
+Cost: the recall gate adds about one Jev round trip (≈ 0.7 s p50, bounded by `recallBudgetMs`) before a non-trivial brain turn; a worker turn that reports done with visible commands waits one round trip before `turn_completed`. The skipped retry turns and the removed duplicate hook run are the savings.
+
+## Backfill
+
+Memories indexed before migration v4 never got a judgment (24,266 of 24,275 on 2026-09-19). The backfill (`memory-judge-backfill.ts`) enqueues a distinct `judge` job per unjudged memory and judges from the stored vector — no re-embedding — through its own runner: one bounded batch per second (`backfillConcurrency`, default 3), only while no interactive `index`/`verify` job is pending, paused with maintenance, backed off exponentially after 3 consecutive failures, paused after 10, a 30 s lease so only one Neural Interface drives it, progress and counters persisted in `typesafe_config.backfill` so a restart resumes. Estimate first (no API calls: content length × bench actuals, plus a local neighbour sample for the relations share), then Start requires `confirm:true`. The end-of-run report records rows judged, relations created, disagreements with the old heuristic, tokens, cost and wall clock.
+
+## Bench
+
+**Settings → AI decisions → Bench**, or `POST /api/typesafe/bench` with `surface: "importance" | "kind" | "relation" | "historical"`, `limit` (1 to 200, default 50) and optionally `project` and `sample: "random" | "recent"`, runs `typesafe-bench.ts`. Reports go to `benchmarks/typesafe-<surface>-<date>.json`. A run stores its summary in the settings and sets `benchRunAt`, which unlocks the "apply judged importance" toggle. After the 2026-09-19 results the decision was to keep importance recorded-only.
+
+## Tests
+
+`mcp-server/vitest.config.ts` sets `SYNABUN_TYPESAFE=off` and the Neural Interface suites set it at file top: a developer's exported key must never make `npm test` hit the paid API. Suites: `typesafe-judgments`, `typesafe-config`, `typesafe-coding` (relevance clips and ordering, prompt riders, claim check, log attribution and stats, supersession guards, the edit-time stale check end to end, relative-path verification, digest and plan conflicts), `typesafe-surfaces` (trash triage: parallel batches with a failed neighbour, 429 retry-after, stored-score reuse and every invalidation, progress snapshots), `memory-judge-backfill`, `memory-migration` (v5, v6, v7), `memory-v2` (relation direction); `neural-interface/tests/memory-api.test.mjs` (endpoints, including the JSON and NDJSON triage answers), `hook-recall-budget` (rank, floor, outcome, judged follow-ups against a stubbed Jev), `native-loop-goal`. The Assistant: `assistant-judgments` (vitest: only the asked questions, caps, redaction, the claim question identical to the Stop hook's), `assistant-jev`, `assistant-evidence`, `assistant-memory` (tiers, early exits, regex fallback), `assistant-dispatch` / `-routing` / `assistant-router` (skipped retry turns, cause kinds, unverified claims), `assistant-api` / `assistant-runtime` (brain reads and the mailbox dedupe), `assistant-brains` (the env marker). Computer use: `desktop-risk` (dk1 golden), `desktop-assist-gate` (dj1 golden, lock reasons, independent browser and desktop passes), `desktop-judgments` (only allowed keys on the wire), `desktop-assist` (golden compact text, fallbacks, exactly one press, every refusal code, cancellation), `desktop-fixtures`, `desktop-bench`; `neural-interface/tests/desktop-service` / `desktop-integration` (contexts, verify, `TARGET_CHANGED`, a 300-grapheme label that must still match), `desktop-assist-contract` (consume before gate, no `await` between the lock check and the press, `lib/desktop` never imports TypeSafe).