synabun 1.3.0 → 2.0.0

package/mcp-server/src/services/fb-regions.ts

@@ -0,0 +1,221 @@
+/**
+ * Shared Facebook region / currency / language helpers.
+ *
+ * Single source of truth for region bucketing, URL normalization, and seed-queue
+ * parsing — imported by BOTH browser-observe.ts (the live joined-groups extractor)
+ * and fb-groups.ts (the structured group directory tool) so the two stay in lockstep.
+ * Previously these lived inline in browser-observe.ts; moved here to avoid duplication.
+ */
+
+/** Region bucket inferred from a group's posting currency. */
+export const REGION_BY_CURRENCY: Record<string, string> = {
+  GBP: 'UK', USD: 'US', EUR: 'EU', BRL: 'Brazil', TRY: 'Turkey', AUD: 'Australia', CAD: 'Canada',
+};
+
+/** Region bucket inferred from a group's language when currency is unknown. */
+export const REGION_BY_LANG: Record<string, string> = {
+  en: 'US/UK', pt: 'Brazil', fr: 'EU', de: 'EU', es: 'LatAm', it: 'EU', nl: 'EU', pl: 'EU', tr: 'Turkey',
+};
+
+/** Coarse country for single-country currencies (EUR omitted — multi-country). */
+export const COUNTRY_BY_CURRENCY: Record<string, string> = {
+  GBP: 'United Kingdom', USD: 'United States', BRL: 'Brazil', TRY: 'Turkey', AUD: 'Australia', CAD: 'Canada',
+};
+
+// Spain vs LatAm: both Spanish-speaking but different supported deal currency (Spain = EUR/EU,
+// LatAm = USD — the deal links have no local LatAm currency, so LatAm posts the USD link).
+// Used by classifyGroupName/resolveClassification to split the broad 'es' bucket correctly.
+export const SPAIN_RE = /\b(espa[ñn]a|madrid|barcelona|valencia|sevilla|zaragoza|bilbao|m[áa]laga|ib[ée]rica?)\b/i;
+export const LATAM_RE = /\b(m[ée]xico|mexican[oa]?|argentin[oa]?|chilen[oa]?|chile|peruan[oa]?|per[uú]|colombian[oa]?|colombia|venezolan[oa]?|venezuela|uruguay|paraguay|bolivia|ecuador|guatemala|hondure[ñn]o|nicaragua|panam[áa]|costa rica|rep[uú]blica dominicana|latinoam[ée]rica|latino\s?am[ée]rica|sudam[ée]rica|latin[oa]s?|latam|hispano)\b/i;
+
+// Country/region-name fallback when a group is not in the seed-queue. Order matters: most
+// specific first. Matched against the group name (and slug-with-spaces). Country-accurate —
+// language-based detection lives in classifyGroupName below. LatAm sits before US so
+// "América Latina" is not swallowed by the US "america" alias.
+export const NAME_REGION: Array<[RegExp, string]> = [
+  [/\b(uk|u\.k\.|britain|british|england|london|scotland|scottish|wales|welsh|ireland|irish)\b/i, 'UK'],
+  [LATAM_RE, 'LatAm'],
+  [/\b(usa|u\.s\.a|united states|american?)\b/i, 'US'],
+  [/\b(brasil|brazil|brasileir[oa]?)\b/i, 'Brazil'],
+  [/\b(türkiye|turkiye|turkey|türk|turk)\b/i, 'Turkey'],
+  [/\b(australia|australian|aussie|nz|new zealand|kiwi)\b/i, 'Australia'],
+  [/\b(canada|canadian)\b/i, 'Canada'],
+  [/\b(france|français|francais|paris)\b/i, 'EU'],
+  [/\b(deutschland|german|deutsch)\b/i, 'EU'],
+  [/\b(españa|espana|spanish|español|espanol)\b/i, 'EU'],
+  [/\b(italia|italy|italian)\b/i, 'EU'],
+  [/\b(polska|poland|polish)\b/i, 'EU'],
+];
+
+// Inverse maps for classification: a region's supported posting currency + default language.
+const REGION_TO_CURRENCY: Record<string, string> = {
+  UK: 'GBP', US: 'USD', EU: 'EUR', Brazil: 'BRL', Turkey: 'TRY', Australia: 'AUD', Canada: 'CAD', LatAm: 'USD',
+};
+const REGION_TO_LANG: Record<string, string> = {
+  UK: 'en', US: 'en', Brazil: 'pt', Turkey: 'tr', Australia: 'en', Canada: 'en', LatAm: 'es', // EU omitted: ambiguous
+};
+// Posting currency a language maps to (the SUPPORTED deal-link currency, not the
+// local currency — Polish/Italian post the EUR link). 'es' = USD: Spanish skews LatAm (USD); Spain
+// (EUR) is split back out by name in classifyGroupName. 'en' stays null: needs a country/seed signal.
+const CURRENCY_BY_LANG: Record<string, string> = {
+  pt: 'BRL', tr: 'TRY', de: 'EUR', fr: 'EUR', es: 'USD', it: 'EUR', pl: 'EUR', nl: 'EUR',
+};
+// Distinctive gaming/deals vocabulary per language, matched as whole words against the lowercased
+// name+slug. High-precision to avoid English false positives ("games"/"deals" are NOT tokens).
+const LANG_TOKENS: Array<[string, RegExp]> = [
+  // PT-distinctive only: "barato(s)"/"gratis" are shared with ES, so excluded here (ES keeps them)
+  // to avoid Spanish groups ("Juegos Baratos") being mis-tagged Brazilian. "grátis" stays accented.
+  ['pt', /\b(jogos?|vendas?|trocas?|grátis|promoç(ão|ões)|brasil|brasileir[oa]s?|apaixonados|usados?|portugu[êe]s|classificad[oa]s?|pe[çc]as|barganha|desapego|negócios|divulga\w*|clube|conex[ãa]o|colecionador\w*|compras?|contas?)\b/i],
+  ['tr', /\b(oyun(lar|cu)?|al[ıi]m|sat[ıi][mş]|takas|ucuz|t[üu]rk(iye)?|indirim|hesap|bilgisayar|ekipman|donan[ıi]m|s[ıi]f[ıi]r)/i],
+  ['de', /\b(spiele?|g[üu]nstig|kaufen|verkaufen|verkauf|tauschen|tausch|b[öo]rse|ankauf|gebraucht|deutsch(land)?|schn[äa]ppchen|angebote?)\b/i],
+  ['fr', /\b(jeux|pas cher|vente|achat|gratuit|fran[çc]ais)\b/i],
+  ['es', /\b(juegos?|barat[oa]s?|ofertas?|venta|compra|gratis|consolas?|espa[ñn]a|espa[ñn]ol)\b/i],
+  ['pl', /\b(gry|gier|tanie|sprzedam|kupi[ęe]|polska|okazje)\b/i],
+  ['it', /\b(videogioch\w*|giochi|economici|vendita|mercatino|italia(no)?)\b/i],
+  ['nl', /\b(spellen|goedkoop|verkopen|nederland)\b/i],
+];
+
+/**
+ * Conservative name-based classifier → { region, lang, currency } where currency is a SUPPORTED
+ * deal-link currency. Language tokens win first (strong signal), then country-name aliases; returns
+ * Unknown/null when there is no confident signal (those are left for the LLM curation pass).
+ */
+export function classifyGroupName(name: string, slug = ''): { region: string; lang: string | null; currency: string | null } {
+  const hay = `${name || ''} ${(slug || '').replace(/[-_]+/g, ' ')}`;
+  for (const [lang, re] of LANG_TOKENS) {
+    if (re.test(hay)) {
+      // Spanish splits by country: Spain -> EUR/EU, everywhere else (LatAm) -> USD. USD is shared
+      // with the US bucket, so es must resolve its region by name, never via REGION_BY_CURRENCY[USD].
+      if (lang === 'es') {
+        const isSpain = SPAIN_RE.test(hay) && !LATAM_RE.test(hay);
+        return isSpain
+          ? { region: 'EU', lang: 'es', currency: 'EUR' }
+          : { region: 'LatAm', lang: 'es', currency: 'USD' };
+      }
+      const currency = CURRENCY_BY_LANG[lang] || null;
+      const region = (currency && REGION_BY_CURRENCY[currency]) || REGION_BY_LANG[lang] || 'Unknown';
+      return { region, lang, currency };
+    }
+  }
+  const region = inferRegionFromName(hay);
+  if (region !== 'Unknown') {
+    return { region, lang: REGION_TO_LANG[region] || null, currency: REGION_TO_CURRENCY[region] || null };
+  }
+  return { region: 'Unknown', lang: null, currency: null };
+}
+
+// Normalize a scraped group name: strip leading/trailing separators (incl. the trailing "(" left by
+// "Name (12k members)") and reject pure label words ("URL", "Group URL", "Link") that the migration
+// captured from "URL: https://..." lines.
+const NAME_LABELS = new Set(['url', 'group url', 'link', 'status', 'name', 'group', 'grupo']);
+export function cleanName(raw?: string | null): string {
+  const n = (raw || '').replace(/[\s(|\-—–:•·]+$/, '').replace(/^[\s)|\-—–:•·]+/, '').trim();
+  if (!n || NAME_LABELS.has(n.toLowerCase())) return '';
+  return n.slice(0, 120);
+}
+
+export function inferRegionFromName(name: string): string {
+  for (const [re, region] of NAME_REGION) if (re.test(name)) return region;
+  return 'Unknown';
+}
+
+/**
+ * Region bucket from a seed-queue lang/currency pair. Currency wins, then language. USD is shared
+ * by US + LatAm, so a Spanish-language USD seed is LatAm. Falls back to the language's posting
+ * currency when no currency is given (so lang=pt with no currency still lands in Brazil, not
+ * Unknown). The non-canonical 'US/UK' english placeholder is never surfaced as a real bucket.
+ */
+export function regionForSeed(lang?: string | null, currency?: string | null): string {
+  const ccy = (currency || '').toUpperCase();
+  const lg = (lang || '').toLowerCase();
+  if (ccy && REGION_BY_CURRENCY[ccy]) {
+    return ccy === 'USD' && lg === 'es' ? 'LatAm' : REGION_BY_CURRENCY[ccy];
+  }
+  if (lg) {
+    const byLang = REGION_BY_LANG[lg];
+    if (byLang && byLang !== 'US/UK') return byLang;
+    const byCur = CURRENCY_BY_LANG[lg];
+    if (byCur && REGION_BY_CURRENCY[byCur]) {
+      return byCur === 'USD' && lg === 'es' ? 'LatAm' : REGION_BY_CURRENCY[byCur];
+    }
+  }
+  return 'Unknown';
+}
+
+/** The canonical region buckets the directory uses (anything else collapses to Unknown). */
+export const CANONICAL_REGIONS = new Set(['UK', 'US', 'EU', 'Brazil', 'Turkey', 'Australia', 'Canada', 'LatAm']);
+
+function nonUnknown(r: string): string | null { return r === 'Unknown' ? null : r; }
+
+/**
+ * Idempotent, all-signals reclassifier. Given whatever a row already has (name/url + any stored
+ * region/lang/currency), return the best { region, lang, currency, country }. The recategorize
+ * backfill and the import paths route through this so every entry point agrees.
+ *
+ * Spanish is resolved first (LatAm=USD default, Spain=EUR) so a stale es->EUR/EU row is corrected
+ * rather than preserved. Otherwise a confident name classification wins, then language, then
+ * currency, then an already-canonical stored region, else Unknown.
+ */
+export function resolveClassification(input: {
+  name?: string | null; url?: string | null; region?: string | null; lang?: string | null; currency?: string | null;
+}): { region: string; lang: string | null; currency: string | null; country: string | null } {
+  const slug = (input.url || '').match(/\/groups\/([^/]+)/)?.[1] || '';
+  const hay = `${input.name || ''} ${slug.replace(/[-_]+/g, ' ')}`;
+  const cls = classifyGroupName(input.name || '', slug);
+  const storedLang = (input.lang || '').toLowerCase() || null;
+
+  // Spanish: decide LatAm (USD) vs Spain (EUR) up front, overriding any stale EUR/EU classification.
+  if (cls.lang === 'es' || storedLang === 'es') {
+    const isSpain = SPAIN_RE.test(hay) && !LATAM_RE.test(hay);
+    return isSpain
+      ? { region: 'EU', lang: 'es', currency: 'EUR', country: 'Spain' }
+      : { region: 'LatAm', lang: 'es', currency: 'USD', country: 'LatAm' };
+  }
+
+  const lang = storedLang || cls.lang || null;
+  let currency = (input.currency || '').toUpperCase();
+  if (currency && !REGION_BY_CURRENCY[currency]) currency = '';            // drop unsupported currency
+  currency = currency || cls.currency || (lang ? CURRENCY_BY_LANG[lang] || '' : '');
+
+  const stored = input.region && CANONICAL_REGIONS.has(input.region) ? input.region : null;
+  let region =
+    nonUnknown(cls.region)
+    || (lang ? nonUnknown(regionForSeed(lang, currency || null)) : null)
+    || (currency ? nonUnknown(regionForSeed(null, currency)) : null)
+    || stored
+    || 'Unknown';
+  if (!CANONICAL_REGIONS.has(region)) region = 'Unknown';
+  if (!currency && region !== 'Unknown') currency = REGION_TO_CURRENCY[region] || '';
+
+  const country = currency ? COUNTRY_BY_CURRENCY[currency] || null : null;
+  return { region, lang: lang || null, currency: currency || null, country };
+}
+
+/** Canonical Facebook group URL: origin + /groups/<slug>/ (single trailing slash). */
+export function normUrl(u: string): string {
+  try {
+    const x = new URL(u.trim());
+    return x.origin + x.pathname.replace(/\/+$/, '') + '/';
+  } catch {
+    return u.trim();
+  }
+}
+
+/**
+ * Parse a seed-queue memory body. [QUEUE] / ledger lines are pipe-delimited
+ * "url | lang | currency | ..." — extra trailing columns are ignored. Returns a
+ * map keyed by the normalized URL so callers can reconcile against live extracts.
+ */
+export function parseSeedQueue(body: string): Map<string, { lang: string; currency: string }> {
+  const map = new Map<string, { lang: string; currency: string }>();
+  for (const raw of (body || '').split('\n')) {
+    const line = raw.trim();
+    if (!line || !line.includes('|') || !/\/groups\//.test(line)) continue;
+    const parts = line.split('|').map((p) => p.trim());
+    if (parts.length < 2) continue;
+    const url = normUrl(parts[0].replace(/^[-*\d.\s]+/, ''));
+    if (!/^https?:\/\//.test(url)) continue;
+    map.set(url, { lang: (parts[1] || '').toLowerCase(), currency: (parts[2] || '').toUpperCase() });
+  }
+  return map;
+}

package/mcp-server/src/services/file-checksums.ts

@@ -1,16 +1,33 @@
 import { createHash } from 'crypto';
 import { readFileSync } from 'fs';
-import { resolve } from 'path';
+import { isAbsolute, resolve } from 'path';
+import { isHttpMode } from './identity.js';
+
+/**
+ * Where a stored file path points. Absolute paths are used as-is. A relative
+ * path is relative to its project's root (`baseDir`, from the project
+ * registry). Without one, it falls back to process.cwd() only for a stdio MCP
+ * server, which Claude Code starts inside the project; over HTTP the process
+ * is the Neural Interface, whose cwd says nothing about the caller, so an
+ * unanchored relative path resolves to nothing rather than to the wrong file.
+ */
+export function resolveStoredPath(filePath: string, baseDir?: string | null): string | null {
+  if (!filePath) return null;
+  if (isAbsolute(filePath)) return filePath;
+  if (baseDir) return resolve(baseDir, filePath);
+  if (isHttpMode()) return null;
+  return resolve(filePath);
+}
 
 /**
  * Compute SHA-256 hash of a file's content.
- * Absolute paths are used as-is. Relative paths resolve from process.cwd()
- * (which is the project root when invoked by Claude Code).
- * Returns null if the file doesn't exist or can't be read.
+ * Returns null if the path cannot be anchored, or the file doesn't exist or
+ * can't be read.
  */
-export function hashFile(filePath: string): string | null {
+export function hashFile(filePath: string, baseDir?: string | null): string | null {
   try {
-    const absPath = resolve(filePath);
+    const absPath = resolveStoredPath(filePath, baseDir);
+    if (!absPath) return null;
     const content = readFileSync(absPath);
     return createHash('sha256').update(content).digest('hex');
   } catch {
@@ -20,13 +37,13 @@ export function hashFile(filePath: string): string | null {
 
 /**
  * Compute checksums for an array of related file paths.
- * Returns a Record mapping each file path to its SHA-256 hash.
+ * Returns a Record mapping each file path (as given) to its SHA-256 hash.
  * Files that can't be read are omitted from the result.
  */
-export function computeChecksums(filePaths: string[]): Record<string, string> {
+export function computeChecksums(filePaths: string[], baseDir?: string | null): Record<string, string> {
   const checksums: Record<string, string> = {};
   for (const fp of filePaths) {
-    const hash = hashFile(fp);
+    const hash = hashFile(fp, baseDir);
     if (hash) checksums[fp] = hash;
   }
   return checksums;

package/mcp-server/src/services/file-excerpt.ts

@@ -0,0 +1,59 @@
+/**
+ * A bounded, credential-free view of a file for a judgment about it.
+ *
+ * Shared by `sync` (a memory whose checksum changed) and the edit-time stale
+ * check (a memory whose file was just edited). File content leaves the machine
+ * in these judgments, so key and environment files are never read and every
+ * excerpt passes through the credential redaction the log preview uses.
+ */
+
+import { readFileSync, statSync } from 'node:fs';
+import { basename } from 'node:path';
+import { redactCredentials } from './typesafe-config.js';
+
+const HEAD_CHARS = 6000;
+const EXCERPT_CHARS = 8000;
+const MAX_FILE_BYTES = 4 * 1024 * 1024;
+
+/** Files whose content is a credential by construction. Never read, never judged. */
+const DENIED_FILE = /^(?:\.env(?:\..*)?|.*\.(?:pem|key|p12|pfx|keystore|jks)|id_(?:rsa|dsa|ecdsa|ed25519)(?:\..*)?|\.npmrc|\.netrc|\.pgpass|credentials(?:\..*)?)$/i;
+
+export function isDeniedFile(filePath: string): boolean {
+  return DENIED_FILE.test(basename(filePath));
+}
+
+/**
+ * The head of the content plus the lines that mention identifiers the memory
+ * talks about, so a memory about one function is judged against that function
+ * even in a long file.
+ */
+export function excerptFromContent(content: string, memoryContent: string): { excerpt: string; truncated: boolean } {
+  if (content.length <= EXCERPT_CHARS) return { excerpt: redactCredentials(content), truncated: false };
+  const identifiers = new Set<string>();
+  for (const m of memoryContent.matchAll(/`([^`\n]{3,60})`/g)) identifiers.add(m[1].trim());
+  for (const m of memoryContent.matchAll(/\b([A-Za-z_$][A-Za-z0-9_$]*(?:[A-Z][a-z0-9]+|_[a-z0-9]+)[A-Za-z0-9_$]*)\b/g)) if (m[1].length >= 5) identifiers.add(m[1]);
+  const head = content.slice(0, HEAD_CHARS);
+  const extra: string[] = [];
+  let budget = EXCERPT_CHARS - head.length;
+  if (identifiers.size) {
+    const lines = content.slice(HEAD_CHARS).split('\n');
+    for (const [i, line] of lines.entries()) {
+      if (budget <= 0) break;
+      if ([...identifiers].some(id => line.includes(id))) {
+        const tagged = `L${Math.max(1, head.split('\n').length + i)}: ${line.slice(0, 200)}`;
+        extra.push(tagged); budget -= tagged.length + 1;
+      }
+    }
+  }
+  const excerpt = extra.length ? `${head}\n… [lines mentioning identifiers from the memory] …\n${extra.join('\n')}` : head;
+  return { excerpt: redactCredentials(excerpt), truncated: true };
+}
+
+/** Read and excerpt a file, or null when it is denied, too large or unreadable. */
+export function fileExcerpt(filePath: string, memoryContent: string): { excerpt: string; truncated: boolean } | null {
+  try {
+    if (isDeniedFile(filePath)) return null;
+    if (statSync(filePath).size > MAX_FILE_BYTES) return null;
+    return excerptFromContent(readFileSync(filePath, 'utf8'), memoryContent);
+  } catch { return null; }
+}

package/mcp-server/src/services/identity.ts

@@ -0,0 +1,291 @@
+/**
+ * Per-caller identity for browser session/tab isolation.
+ *
+ * Over the HTTP transport, every MCP request runs inside the ONE Neural
+ * Interface process — module-level state in neural-interface.ts would be
+ * shared by every connected Claude Code instance (CLI windows, sidepanel
+ * chats, loops), which is exactly how separately-launched automations ended
+ * up competing for the same browser tab. This module gives each caller its
+ * own identity object, derived per-request from:
+ *
+ *   1. X-Synabun-Terminal / X-Synabun-Browser-Session / X-Synabun-Browser-Tab
+ *      headers (loops, scheduled loops, sidepanel — injected at launch), or
+ *   2. the stateful Mcp-Session-Id (plain CLI windows — unique per Claude
+ *      Code process with zero client configuration), or
+ *   3. a per-process stdio singleton whose pins read live process.env —
+ *      bit-identical to the historical behavior for stdio MCP children
+ *      (codex/opencode loops, automation-window agents).
+ *
+ * The HTTP transport enters the AsyncLocalStorage context around every
+ * transport.handleRequest call; stdio never enters it, so getIdentity()
+ * falling back to the stdio singleton IS the backward-compat switch.
+ */
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+
+export interface PinSet {
+  terminalSessionId: string | null;
+  browserSessionId: string | null;
+  browserTabId: string | null;
+}
+
+export interface IdentityState {
+  affinitySessionId: string | null;
+  interactiveSessionId: string | null;
+  interactiveTabId: string | null;
+  recoveredSessionId: string | null;
+  recoveredTabId: string | null;
+  ancestorPinnedSession: string | null;
+  ancestorPinnedTab: string | null;
+  ancestorPinnedTerminal: string | null;
+  ancestorAttempts: number;
+}
+
+/** Caller roles that unlock role-gated tool groups (see profiles.ts
+ *  ROLE_GATED_GROUPS). Only the SynaBun assistant runtime exists today. */
+export type CallerRole = 'assistant';
+
+export interface CallerIdentity {
+  memoryContext?: { project?: string; session?: string; generation?: string };
+  /** Role claimed by the caller's launch headers (X-Synabun-Role) — refreshed
+   *  on every HTTP request; stdio children read SYNABUN_ROLE live instead. */
+  role?: CallerRole;
+  /** Computer-use grant (X-Synabun-Desktop-Grant), minted by the Neural
+   *  Interface per assistant brain / computer-use worker. Per request, like role. */
+  desktopGrant?: string;
+  key: string;
+  source: 'header' | 'mcp-session' | 'stdio';
+  /** ownerKey for /api/browser/acquire|release AND the X-Synabun-Terminal
+   *  fallback — one field so the routing key and the acquire key can never
+   *  drift apart. */
+  clientId: string;
+  pins: PinSet;
+  state: IdentityState;
+  lastSeen: number;
+}
+
+const emptyState = (): IdentityState => ({
+  affinitySessionId: null,
+  interactiveSessionId: null,
+  interactiveTabId: null,
+  recoveredSessionId: null,
+  recoveredTabId: null,
+  ancestorPinnedSession: null,
+  ancestorPinnedTab: null,
+  ancestorPinnedTerminal: null,
+  ancestorAttempts: 0,
+});
+
+const als = new AsyncLocalStorage<CallerIdentity>();
+export function callerMemoryContext() {
+  return als.getStore()?.memoryContext || (httpMode ? {} : {
+    project: process.env.SYNABUN_PROJECT,
+    session: process.env.SYNABUN_TERMINAL_SESSION,
+    generation: process.env.SYNABUN_CONTEXT_GENERATION,
+  });
+}
+const identities = new Map<string, CallerIdentity>();
+
+// Set by the HTTP transport at mount. Once true, a missing ALS store inside a
+// tool handler is a context-propagation bug: degrade to an EPHEMERAL identity
+// (costs an extra tab) rather than the shared stdio singleton (cross-talk).
+let httpMode = false;
+export function markHttpMode(): void { httpMode = true; }
+
+// Lazy stdio singleton — the per-process identity for stdio transports.
+// clientId is minted once per process (the old INTERACTIVE_CLIENT_ID); pins
+// are read live from process.env by effectivePins(), preserving the exact
+// historical env-pin semantics.
+let _stdioIdentity: CallerIdentity | null = null;
+function stdioIdentity(): CallerIdentity {
+  if (!_stdioIdentity) {
+    _stdioIdentity = {
+      key: 'stdio',
+      source: 'stdio',
+      clientId: randomUUID(),
+      pins: { terminalSessionId: null, browserSessionId: null, browserTabId: null },
+      state: emptyState(),
+      lastSeen: Date.now(),
+    };
+  }
+  return _stdioIdentity;
+}
+
+/** The stdio identity if it was ever created (for exit-hook tab release). */
+export function peekStdioIdentity(): CallerIdentity | null {
+  return _stdioIdentity;
+}
+
+export function isHttpMode(): boolean { return httpMode; }
+
+export function runWithIdentity<T>(identity: CallerIdentity, fn: () => T): T {
+  return als.run(identity, fn);
+}
+
+export function getIdentity(): CallerIdentity {
+  const store = als.getStore();
+  if (store) return store;
+  if (httpMode) {
+    // Propagation bug guard: never hand the shared stdio identity to an HTTP
+    // caller. An ephemeral identity wastes a tab at worst — never cross-talk.
+    console.error('[identity] missing ALS context in HTTP mode — using ephemeral identity (propagation bug?)');
+    const key = `ephemeral-${randomUUID()}`;
+    return {
+      key,
+      source: 'mcp-session',
+      clientId: key,
+      pins: { terminalSessionId: null, browserSessionId: null, browserTabId: null },
+      state: emptyState(),
+      lastSeen: Date.now(),
+    };
+  }
+  return stdioIdentity();
+}
+
+/** Pins must look like the ids we mint (hex/uuid-ish). Rejects empty strings
+ *  and unexpanded template junk like "${SYNABUN_TERMINAL_SESSION}". */
+export function sanitizePin(v: string | undefined | null): string | null {
+  if (!v) return null;
+  return /^[A-Za-z0-9_-]{1,128}$/.test(v) ? v : null;
+}
+
+/** Only known roles are accepted; anything else (empty, template junk,
+ *  invented roles) is treated as "no role" so gating fails closed. */
+export function sanitizeRole(v: string | undefined | null): CallerRole | null {
+  return typeof v === 'string' && v.trim().toLowerCase() === 'assistant' ? 'assistant' : null;
+}
+
+/** Desktop grants look exactly like the tokens the Neural Interface mints. */
+export function sanitizeDesktopGrant(v: string | undefined | null): string | null {
+  return typeof v === 'string' && /^sbd_[A-Za-z0-9_-]{43}$/.test(v.trim()) ? v.trim() : null;
+}
+
+/**
+ * Computer-use grant of the current caller: the ALS identity's grant over HTTP
+ * (X-Synabun-Desktop-Grant on every request), SYNABUN_DESKTOP_GRANT for stdio
+ * children. Never the host's own env for an unidentified HTTP caller.
+ */
+export function callerDesktopGrant(): string | null {
+  const store = als.getStore();
+  if (store) return store.desktopGrant ?? null;
+  if (httpMode) return null;
+  return sanitizeDesktopGrant(process.env.SYNABUN_DESKTOP_GRANT);
+}
+
+/**
+ * Role of the current caller: the ALS identity's role over HTTP (derived from
+ * X-Synabun-Role on every request), or SYNABUN_ROLE for stdio children —
+ * Codex/OpenCode assistant brains pass the role to their MCP child via env.
+ * In HTTP mode a missing ALS store is a propagation bug, so the host
+ * process's own env must never grant a role to an unidentified caller.
+ */
+export function callerRole(): CallerRole | null {
+  const store = als.getStore();
+  if (store) return store.role ?? null;
+  if (httpMode) return null;
+  return sanitizeRole(process.env.SYNABUN_ROLE);
+}
+
+/** Create-or-touch the identity for an HTTP caller. */
+export function obtainIdentity(
+  key: string,
+  opts: { source: 'header' | 'mcp-session'; pins?: Partial<PinSet>; role?: CallerRole | null; desktopGrant?: string | null }
+): CallerIdentity {
+  let id = identities.get(key);
+  if (!id) {
+    id = {
+      key,
+      source: opts.source,
+      clientId: key,
+      pins: {
+        terminalSessionId: opts.pins?.terminalSessionId ?? null,
+        browserSessionId: opts.pins?.browserSessionId ?? null,
+        browserTabId: opts.pins?.browserTabId ?? null,
+      },
+      state: emptyState(),
+      lastSeen: Date.now(),
+    };
+    if (opts.role) id.role = opts.role;
+    if (opts.desktopGrant) id.desktopGrant = opts.desktopGrant;
+    identities.set(key, id);
+  } else {
+    // Refresh pins on every request — a loop relaunch may rebind its headers.
+    if (opts.pins?.terminalSessionId !== undefined) id.pins.terminalSessionId = opts.pins.terminalSessionId;
+    if (opts.pins?.browserSessionId !== undefined) id.pins.browserSessionId = opts.pins.browserSessionId;
+    if (opts.pins?.browserTabId !== undefined) id.pins.browserTabId = opts.pins.browserTabId;
+    // The role is per-request: a request without the header carries no role,
+    // so a stale grant can never outlive the headers that justified it.
+    if (opts.role !== undefined) id.role = opts.role ?? undefined;
+    if (opts.desktopGrant !== undefined) id.desktopGrant = opts.desktopGrant ?? undefined;
+    id.lastSeen = Date.now();
+  }
+  return id;
+}
+
+/** Pin resolution: stdio reads live env (historical behavior); HTTP identities
+ *  carry pins parsed from their launch headers. */
+export function effectivePins(id: CallerIdentity): PinSet {
+  if (id.source === 'stdio') {
+    return {
+      terminalSessionId: process.env.SYNABUN_TERMINAL_SESSION || null,
+      browserSessionId: process.env.SYNABUN_BROWSER_SESSION || null,
+      browserTabId: process.env.SYNABUN_BROWSER_TAB || null,
+    };
+  }
+  return id.pins;
+}
+
+/** The X-Synabun-Terminal value for Neural Interface requests — the server
+ *  routes this caller's tab-less browser calls via _tabOwners[terminalId].
+ *  Analogue of the old currentTerminalId(): env/header pin → resolved
+ *  ancestor terminal → this identity's own client id. */
+export function terminalIdFor(id: CallerIdentity): string {
+  return effectivePins(id).terminalSessionId || id.state.ancestorPinnedTerminal || id.clientId;
+}
+
+// Release hook — registered by neural-interface.ts (which owns the HTTP
+// client) to avoid a circular import. Receives the identity whose acquired
+// tab should be released server-side.
+type ReleaseHook = (id: CallerIdentity) => void;
+let releaseHook: ReleaseHook | null = null;
+export function setReleaseHook(fn: ReleaseHook): void { releaseHook = fn; }
+
+/**
+ * Drop an HTTP identity, releasing its acquired tab if it ever called
+ * /api/browser/acquire. Loop tabs are NEVER released here: a loop identity's
+ * tab is owned server-side under its terminalSessionId and reaped by
+ * /api/loop/stop — interactiveSessionId is only set by acquireInteractive.
+ */
+export function releaseIdentity(key: string): void {
+  const id = identities.get(key);
+  if (!id) return;
+  if (id.state.interactiveSessionId && releaseHook) {
+    try { releaseHook(id); } catch { /* best-effort */ }
+  }
+  identities.delete(key);
+}
+
+export function identityCount(): number { return identities.size; }
+
+const IDENTITY_TTL_MS = parseInt(process.env.SYNABUN_IDENTITY_TTL_MS || '', 10) || 2 * 60 * 60 * 1000;
+
+let sweeperStarted = false;
+export function startIdentitySweeper(): void {
+  if (sweeperStarted) return;
+  sweeperStarted = true;
+  const interval = setInterval(() => {
+    const now = Date.now();
+    let evicted = 0;
+    for (const [key, id] of identities) {
+      if (now - id.lastSeen > IDENTITY_TTL_MS) {
+        releaseIdentity(key);
+        evicted++;
+      }
+    }
+    if (evicted > 0) {
+      console.error(`[identity] evicted ${evicted} idle identities (${identities.size} remain)`);
+    }
+  }, 60_000);
+  interval.unref();
+}