shraga 0.1.112 → 0.1.114

package/src/client/lib/backendHealth.ts

@@ -0,0 +1,230 @@
+/** Backend-health classifier + tiny store.
+ *
+ *  WHY this exists: a broken backend used to be INVISIBLE in the UI. When something other than shraga
+ *  answered the app's port (e.g. another project's dev server bound `127.0.0.1:3033` while shraga held
+ *  `*:3033` — macOS routes the loopback name to the MORE SPECIFIC bind, so the proxy fed every request
+ *  to the wrong process), the foreign server 404'd `/api/config`, `/api/workspace` and refused the `/ws`
+ *  upgrade. The UI rendered a normal-looking EMPTY shell: no workspace, no terminals, no error. Every
+ *  clue was in the browser console and nothing reached the screen.
+ *
+ *  The load-bearing signal is {@link SHRAGA_VERSION_HEADER}: the shraga server stamps it on EVERY
+ *  response including 404/401/5xx (src/server/boot.ts). So a response WITHOUT it did not come from
+ *  shraga at all — which turns an ambiguous "some 404" into the exact diagnosis "something else is
+ *  serving this port".
+ *
+ *  Producers report here from the SHARED helpers (`apiFetch`, `api`, `AgentSocket`) so every existing
+ *  call site benefits with no call-site change. The single consumer is <BackendStatusBanner />.
+ */
+import { logger } from '@/lib/debug';
+
+const log = logger.forComponent('BackendHealth');
+
+/** Identity header stamped by the shraga server on every response. Lowercase: `Headers` is
+ *  case-insensitive, but keeping it lowercase avoids any doubt about what we're matching. */
+export const SHRAGA_VERSION_HEADER = 'x-shraga-version';
+
+export type BackendFaultKind = 'wrong-backend' | 'server-error' | 'offline' | 'ws-down';
+
+export interface BackendFault {
+  kind: BackendFaultKind;
+  /** One-line headline for the banner. */
+  title: string;
+  /** Actionable next step — what the user should actually go do. */
+  hint: string;
+  /** The request that exposed the fault, when there is one. */
+  path?: string;
+  status?: number;
+}
+
+/** Fault sources are tracked SEPARATELY: HTTP recovering must not erase a still-broken WebSocket
+ *  (that is exactly the "terminals stay blank while the page looks fine" half of the incident). */
+type Source = 'http' | 'ws';
+const faults: Partial<Record<Source, BackendFault>> = {};
+const raisedAt: Partial<Record<Source, number>> = {};
+
+/** A raised fault does NOT vanish on the very next good response. The app polls continuously (pty cwd,
+ *  workspace, layout), so a single interleaved success would otherwise erase the banner milliseconds
+ *  after it appeared — leaving a user staring at a flicker they can neither read nor act on. Recovery
+ *  must therefore be CONFIRMED: several consecutive good responses AND a minimum time on screen. */
+/** ...and the SAME reasoning governs the WebSocket. An ordinary reconnect blip closes and re-opens in
+ *  a couple of seconds (backoff is ~1s * 2^attempt + jitter); painting and erasing an amber banner
+ *  inside that window is the flicker described above, not information. So a close is given
+ *  `wsGraceMs` to recover before it becomes a fault at all — which still catches the case that
+ *  motivated the feature, a socket that never comes back (including one wedged in CONNECTING, where
+ *  counting reconnect ATTEMPTS would never trip) — and a recovered socket serves the same
+ *  `minDwellMs` before the banner is taken down. */
+const DEFAULT_TIMING = { okStreakToClear: 3, minDwellMs: 5_000, wsGraceMs: 5_000 };
+type Timing = typeof DEFAULT_TIMING;
+let timing: Timing = { ...DEFAULT_TIMING };
+let okStreak = 0;
+/** The single pending ws timer: a delayed RAISE while no ws fault is shown, a delayed CLEAR while one
+ *  is (`faults.ws` disambiguates, and every path that changes that state cancels it first). */
+let wsTimer: ReturnType<typeof setTimeout> | null = null;
+function cancelWsTimer() {
+  if (wsTimer) { clearTimeout(wsTimer); wsTimer = null; }
+}
+
+/** Worst-first. `wrong-backend` outranks everything: when the port is hijacked the 404s and the dead
+ *  socket are SYMPTOMS, and showing either of those instead would send the user down the wrong path. */
+const PRECEDENCE: BackendFaultKind[] = ['wrong-backend', 'offline', 'server-error', 'ws-down'];
+
+type Listener = (fault: BackendFault | null) => void;
+const listeners = new Set<Listener>();
+
+export function currentFault(): BackendFault | null {
+  const present = (Object.values(faults) as BackendFault[]).filter(Boolean);
+  if (present.length === 0) return null;
+  return present.sort((a, b) => PRECEDENCE.indexOf(a.kind) - PRECEDENCE.indexOf(b.kind))[0];
+}
+
+function emit() {
+  const f = currentFault();
+  listeners.forEach((l) => l(f));
+}
+
+export function subscribeBackendHealth(listener: Listener): () => void {
+  listeners.add(listener);
+  listener(currentFault());
+  return () => { listeners.delete(listener); };
+}
+
+function set(source: Source, fault: BackendFault) {
+  const prev = faults[source];
+  faults[source] = fault;
+  // Restart the dwell when the fault CHANGES KIND too: a wrong-backend that supersedes an older
+  // server-error is a new message and needs its own time on screen, not the predecessor's leftovers.
+  if (prev?.kind !== fault.kind) raisedAt[source] = Date.now();
+  if (source === 'http') okStreak = 0;
+  // Log the transition only, not every repeat — a broken backend is polled continuously.
+  if (prev?.kind !== fault.kind || prev?.path !== fault.path || prev?.status !== fault.status) {
+    log.warn(`${fault.kind}: ${fault.title}`, { path: fault.path, status: fault.status });
+  }
+  emit();
+}
+
+function clear(source: Source) {
+  if (!faults[source]) return;
+  log.info(`${source} recovered`);
+  delete faults[source];
+  delete raisedAt[source];
+  emit();
+}
+
+/** Describe the origin the app believes it is talking to, for the wrong-backend message. */
+function originLabel(): string {
+  try { return window.location.origin; } catch { return 'this origin'; }
+}
+
+/**
+ * Classify a COMPLETED HTTP response from the shraga API. Call for ok and !ok alike — a wrong backend
+ * can answer `200` just as easily as `404`, so the identity header is checked first, unconditionally.
+ *
+ * `expect` lists statuses this CALL SITE treats as a normal, handled outcome (e.g. the pty-cwd poller,
+ * for which 404 means "that pane is gone" and is swallowed by design). An expected status is not a
+ * fault: raising a banner for a by-design 404 is the cry-wolf failure this whole module exists to
+ * avoid. It is checked AFTER the identity header, so a hijacker answering 404 is still caught.
+ */
+export function reportApiResponse(path: string, res: Response, expect?: readonly number[]): void {
+  if (!res.headers.has(SHRAGA_VERSION_HEADER)) {
+    set('http', {
+      kind: 'wrong-backend',
+      title: `${originLabel()} is being served by something that is not Shraga.`,
+      hint:
+        'Another process is almost certainly bound to the app port and shadowing the real server ' +
+        '(a more specific 127.0.0.1 bind wins over Shraga’s wildcard bind). Find it with ' +
+        '`lsof -nP -iTCP:<port> -sTCP:LISTEN`, stop it, then retry.',
+      path,
+      status: res.status,
+    });
+    return;
+  }
+  // Genuine shraga auth responses are the ORDINARY login/permission flow — never a banner. Checked
+  // after the header so a hijacker that answers 401 is still caught above.
+  if (res.status === 401 || res.status === 403) return;
+  // Handled by the caller — neither a fault nor evidence of recovery.
+  if (expect?.includes(res.status)) return;
+
+  if (!res.ok) {
+    set('http', {
+      kind: 'server-error',
+      title: `Shraga returned ${res.status} for ${path}.`,
+      hint: 'The server is reachable but this request failed. Retry; if it persists, check the server logs.',
+      path,
+      status: res.status,
+    });
+    return;
+  }
+  okStreak++;
+  if (faults.http && okStreak >= timing.okStreakToClear && Date.now() - (raisedAt.http ?? 0) >= timing.minDwellMs) {
+    clear('http');
+  }
+}
+
+/** Classify a request that never produced a response: network down, server unreachable, or aborted.
+ *
+ *  `timedOut` says the HELPER's OWN deadline fired (`apiFetch`'s `timeoutMs` controller). It is the
+ *  only thing that separates a genuine wedged server from a CALLER-initiated `abort()` — both surface
+ *  as an indistinguishable `AbortError`. A caller abort is ordinary control flow, not a fault: the tab
+ *  palette re-issues its search on every keystroke and aborts the in-flight one, so raising here
+ *  painted a red "cannot reach the server" banner for plain typing. Raise NOTHING for it.
+ */
+export function reportApiFailure(path: string, err: unknown, opts?: { timedOut?: boolean }): void {
+  const aborted = (err as { name?: string } | null)?.name === 'AbortError';
+  if (aborted && !opts?.timedOut) return;
+  set('http', {
+    kind: 'offline',
+    title: opts?.timedOut ? `Request to ${path} timed out.` : `Cannot reach the Shraga server.`,
+    hint: opts?.timedOut
+      ? 'The server accepted the connection but did not answer in time. It may be overloaded or wedged.'
+      : 'The network is down, or nothing is listening on the app port. Check your connection and that the server is running.',
+    path,
+  });
+}
+
+/** WebSocket health, reported by {@link AgentSocket}. A dead socket is why terminals and live updates
+ *  silently stop; without this the panes just stay blank.
+ *
+ *  A close does NOT raise on its own — it starts the grace window (see {@link DEFAULT_TIMING}). Only a
+ *  socket still down when the window expires is a fault the user can act on. */
+export function reportWsDown(code?: number): void {
+  // Already on screen: a re-close during the recovery dwell just keeps the banner up.
+  if (faults.ws) { cancelWsTimer(); return; }
+  // Grace already running from an earlier close in the same outage — don't restart it, or a socket
+  // that flaps every few seconds would push the deadline out forever and never raise.
+  if (wsTimer) return;
+  const raise = () => {
+    wsTimer = null;
+    set('ws', {
+      kind: 'ws-down',
+      title: 'Live connection lost — terminals and streaming updates are offline.',
+      hint:
+        code === 1006
+          ? 'The connection was refused or dropped without a close handshake, which usually means the ' +
+            'WebSocket upgrade never reached Shraga. Reconnecting…'
+          : 'Reconnecting…',
+      status: code,
+    });
+  };
+  if (timing.wsGraceMs <= 0) raise();
+  else wsTimer = setTimeout(raise, timing.wsGraceMs);
+}
+
+export function reportWsUp(): void {
+  cancelWsTimer(); // a blip that recovered inside the grace window never earned a banner
+  if (!faults.ws) return;
+  const remaining = timing.minDwellMs - (Date.now() - (raisedAt.ws ?? 0));
+  if (remaining <= 0) { clear('ws'); return; }
+  wsTimer = setTimeout(() => { wsTimer = null; clear('ws'); }, remaining);
+}
+
+/** Test seam — drop all state, and optionally shrink the timings so a test needn't wait seconds. */
+export function __resetBackendHealth(overrides?: Partial<Timing>): void {
+  cancelWsTimer();
+  timing = { ...DEFAULT_TIMING, ...overrides };
+  delete faults.http;
+  delete faults.ws;
+  delete raisedAt.http;
+  delete raisedAt.ws;
+  okStreak = 0;
+  emit();
+}

package/src/client/lib/debug.ts

@@ -0,0 +1,48 @@
+/** Component-scoped console logger.
+ *
+ *  `debug`/`verbose` are development output and are GATED per component — they print only when the
+ *  component's name (or `*`) appears in the comma-separated `DEBUG` localStorage key:
+ *      localStorage.setItem('DEBUG', 'BackendHealth,ws')
+ *  `info`/`warn`/`error` are operational and ALWAYS print. Use this instead of raw `console.*` so a
+ *  noisy module can be silenced without deleting the logging that diagnoses a live incident.
+ */
+
+type LogFn = (...args: unknown[]) => void;
+
+export interface ComponentLogger {
+  debug: LogFn;
+  verbose: LogFn;
+  info: LogFn;
+  warn: LogFn;
+  error: LogFn;
+}
+
+/** Read once per call rather than caching: a dev flipping `DEBUG` in devtools expects it to take
+ *  effect without a reload, and this only runs on a log call that is already about to hit console. */
+function gateAllows(component: string): boolean {
+  let raw: string | null = null;
+  try {
+    raw = localStorage.getItem('DEBUG');
+  } catch {
+    return false; // storage blocked (private mode / sandboxed iframe) — dev output is not worth throwing over
+  }
+  if (!raw) return false;
+  return raw
+    .split(',')
+    .map((s) => s.trim())
+    .some((s) => s === '*' || s === component);
+}
+
+export const logger = {
+  forComponent(component: string): ComponentLogger {
+    const tag = `[${component}]`;
+    const gated = (fn: LogFn): LogFn => (...args) => { if (gateAllows(component)) fn(tag, ...args); };
+    return {
+      debug: gated((...a) => console.debug(...a)),
+      verbose: gated((...a) => console.debug(...a)),
+      info: (...a) => console.info(tag, ...a),
+      warn: (...a) => console.warn(tag, ...a),
+      error: (...a) => console.error(tag, ...a),
+    };
+  },
+};

package/src/client/lib/sessionApi.ts

@@ -1,3 +1,4 @@
+import { reportApiFailure, reportApiResponse } from '@/lib/backendHealth';
 import { randomUUID } from '@/lib/utils';
 import type { ChatMessage, MessageBlock } from '@/hooks/useConversation';
 
@@ -15,24 +16,39 @@ export class ApiError extends Error {
   }
 }
 
-/** Authenticated fetch with bearer token + timeout. Throws `ApiError` (with `.status`) on !ok. */
+/** Authenticated fetch with bearer token + timeout. Throws `ApiError` (with `.status`) on !ok.
+ *
+ *  `expect` lists statuses this call site HANDLES as a normal outcome (it still throws — see `ApiError`
+ *  — the list only tells the backend-health classifier not to treat them as a fault). Use it wherever a
+ *  non-2xx is by design, or the shared banner cries wolf on routine traffic. */
 export async function apiFetch(
   path: string,
   getToken: () => Promise<string | null>,
-  init?: RequestInit & { timeoutMs?: number },
+  init?: RequestInit & { timeoutMs?: number; expect?: readonly number[] },
 ) {
   const token = await getToken();
   if (!token) throw new Error('No auth token');
   const timeout = init?.timeoutMs ?? 15_000;
   const controller = new AbortController();
   if (init?.signal) init.signal.addEventListener('abort', () => controller.abort());
-  const timer = setTimeout(() => controller.abort(), timeout);
+  // `timedOut` is the ONLY thing that distinguishes our own deadline from a caller's abort() — both
+  // reject with an identical AbortError, and only the former is a real backend fault.
+  let timedOut = false;
+  const timer = setTimeout(() => { timedOut = true; controller.abort(); }, timeout);
   try {
-    const res = await fetch(path, {
-      ...init,
-      signal: controller.signal,
-      headers: { Authorization: `Bearer ${token}`, ...init?.headers },
-    });
+    let res: Response;
+    try {
+      res = await fetch(path, {
+        ...init,
+        signal: controller.signal,
+        headers: { Authorization: `Bearer ${token}`, ...init?.headers },
+      });
+    } catch (err) {
+      // Single choke point: every apiFetch call site gets backend-fault surfacing for free.
+      reportApiFailure(path, err, { timedOut });
+      throw err;
+    }
+    reportApiResponse(path, res, init?.expect);
     if (!res.ok) throw new ApiError(res.status, res.statusText);
     return res;
   } finally {

package/src/client/lib/ws.ts

@@ -1,3 +1,8 @@
+import { reportWsDown, reportWsUp } from '@/lib/backendHealth';
+import { logger } from '@/lib/debug';
+
+const log = logger.forComponent('ws');
+
 /** Subprotocol marker used to carry a bearer token through a WebSocket handshake: open the socket as
  * `new WebSocket(url, [WS_AUTH_PROTOCOL, token])`. Browsers can't set headers on a WS handshake, and the
  * subprotocol list is the one field they can — used by the sidecar WS proxy (see authenticateWsUpgrade
@@ -72,7 +77,7 @@ export class AgentSocket {
     this.intentionalClose = false;
     const proto = location.protocol === 'https:' ? 'wss' : 'ws';
     const url = `${proto}://${location.host}/ws`;
-    console.log('[ws] connecting…');
+    log.debug('connecting…');
     this.ws = new WebSocket(url);
 
     this.ws.onopen = async () => {
@@ -81,11 +86,12 @@ export class AgentSocket {
       try {
         token = await this.tokenProvider();
       } catch (err) {
-        console.warn('[ws] token fetch failed', err);
+        log.warn('token fetch failed', err);
       }
       if (this.ws?.readyState !== WebSocket.OPEN) return;
-      console.log('[ws] open, sending auth');
+      log.debug('open, sending auth');
       this.ws.send(JSON.stringify({ type: 'auth', token }));
+      reportWsUp();
       if (this.reconnecting) {
         this.reconnecting = false;
         this.listeners.forEach((l) => l({ type: 'reconnected' }));
@@ -95,7 +101,7 @@ export class AgentSocket {
     this.ws.onmessage = (e) => {
       try {
         const data = JSON.parse(e.data) as ServerEvent;
-        if (data.type !== 'text_delta') console.log('[ws] ←', data.type);
+        if (data.type !== 'text_delta') log.verbose('←', data.type);
         if (data.type === 'auth_ok') {
           this.authRetries = 0;
           this.flushPending();
@@ -113,37 +119,38 @@ export class AgentSocket {
             this.intentionalClose = true;
           } else {
             this.authRetries++;
-            console.log(`[ws] auth failed (attempt ${this.authRetries}), will retry with fresh token`);
+            log.warn(`auth failed (attempt ${this.authRetries}), will retry with fresh token`);
           }
         }
         this.listeners.forEach((l) => l(data));
       } catch (err) {
-        console.warn('[ws] bad frame', err);
+        log.warn('bad frame', err);
       }
     };
 
     this.ws.onclose = (e) => {
-      console.log(`[ws] closed code=${e.code} intentional=${this.intentionalClose}`);
+      log.debug(`closed code=${e.code} intentional=${this.intentionalClose}`);
       if (!this.intentionalClose) {
         this.reconnecting = true;
         this.connectAttempts++;
+        reportWsDown(e.code);
         this.listeners.forEach((l) => l({ type: 'disconnected' }));
         const base = this.authRetries > 0 ? Math.min(2000 * this.authRetries, 10000) : Math.min(1000 * 2 ** this.connectAttempts, 30000);
         const jitter = Math.random() * 1000;
         const delay = base + jitter;
-        console.log(`[ws] reconnecting in ${(delay / 1000).toFixed(1)}s (attempt ${this.connectAttempts})`);
+        log.debug(`reconnecting in ${(delay / 1000).toFixed(1)}s (attempt ${this.connectAttempts})`);
         setTimeout(() => this.connect(this.tokenProvider), delay);
       }
     };
 
-    this.ws.onerror = (e) => console.warn('[ws] error', e);
+    this.ws.onerror = (e) => log.warn('error', e);
   }
 
   private flushPending() {
     if (this.pendingMessage) {
       const msg = this.pendingMessage;
       this.pendingMessage = null;
-      console.log('[ws] flushing pending message after reconnect');
+      log.debug('flushing pending message after reconnect');
       if (!this.send(msg)) {
         this.pendingMessage = msg;
       }
@@ -152,24 +159,25 @@ export class AgentSocket {
 
   disconnect() {
     this.intentionalClose = true;
+    reportWsUp(); // an intentional close is not a fault — don't leave a stale banner behind
     this.ws?.close();
     this.ws = null;
   }
 
   send(msg: object): boolean {
     if (this.ws?.readyState === WebSocket.OPEN) {
-      console.log('[ws] →', (msg as any).type);
+      log.verbose('→', (msg as any).type);
       this.ws.send(JSON.stringify(msg));
       return true;
     }
-    console.warn('[ws] send failed, readyState=', this.ws?.readyState);
+    log.warn('send failed, readyState=', this.ws?.readyState);
     return false;
   }
 
   sendOrQueue(msg: object): boolean {
     if (this.send(msg)) return true;
     this.pendingMessage = msg;
-    console.log('[ws] message queued for reconnect');
+    log.debug('message queued for reconnect');
     return false;
   }
 

package/src/index.ts

@@ -25,8 +25,10 @@ import type { AgentEngine, EngineModel, EngineStreamOpts } from './server/engine
 import type { ExtRegisterFn, ExtensionContext } from './server/extensions.ts';
 import type { WebhookOptions } from './server/events/webhook.ts';
 import type { ShragaEvent, ShragaEventMap, PayloadOf } from './server/events/types.ts';
+import type { PolicyOptions, PolicyFile } from './server/security/policy.ts';
 
 export type {
+  PolicyFile,
   ServerHandle,
   ServerFeature,
   FeatureContext,
@@ -67,6 +69,12 @@ export class ShragaOptions {
   runtimeRegistration?: boolean = false;
   /** Arbitrary extra environment to apply before boot (e.g. ANTHROPIC_API_KEY, SHRAGA_FEAT_*). */
   env?: Record<string, string>;
+  /** Security policy seams. `migrate` seeds `data/security/policy.json` ONCE, when it's first generated (no file, no
+   *  `.migrated` marker): it receives the default draft (legacy whitelist already bound as operator) and returns the
+   *  final draft. The result is validated and saved like any policy; an invalid draft or a throw fails closed (owners
+   *  only). Never runs on a PASSIVE standby (it runs on promotion if the file is still missing). Later edits go through
+   *  the Owner Console, not this hook. */
+  security?: { migrate?: PolicyOptions['migrate'] };
 }
 
 export interface ShragaInstance {
@@ -94,7 +102,7 @@ export interface ShragaInstance {
 
 class Shraga implements ShragaInstance {
   public options: ShragaOptions;
-  private reg: Required<BootRegistrations> = { features: [], engines: [], extensions: [], eventSubs: [] };
+  private reg: Required<Omit<BootRegistrations, 'security'>> ={ features: [], engines: [], extensions: [], eventSubs: [] };
   private handle: ServerHandle | null = null;
   private starting: Promise<ServerHandle> | null = null;
 
@@ -150,7 +158,7 @@ class Shraga implements ShragaInstance {
     if (this.starting) return this.starting;
     this.starting = (async () => {
       const { bootServer } = await import('./server/boot.ts');
-      this.handle = await bootServer(this.reg);
+      this.handle = await bootServer({ ...this.reg, security: this.options.security });
       return this.handle;
     })();
     return this.starting;

package/src/scripts/harden-audit.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# harden-audit.sh — make shraga's audit log append-only at the OS level. Linux + root. Idempotent: run it from cron.
+#
+#   sudo harden-audit.sh <DATA_DIR>                 (or DATA_DIR=<dir> sudo -E harden-audit.sh)
+#   root crontab, hourly:  17 * * * *  /app/node_modules/shraga/src/scripts/harden-audit.sh /app/data-prod
+#
+# `chattr +a` on <DATA_DIR>/audit/: the server user can still create month files and append, but can't delete or
+# rename any entry. `chattr +a` on each YYYY-MM.jsonl: it opens for append only — no truncate, no rewrite.
+# New files do NOT inherit +a (it is not in ext4's EXT4_FL_INHERITED nor XFS's inherited flags), so a new month's
+# file stays truncatable until the next run — hence hourly cron. Retention/rotation is a root-only op (chattr -a).
+# +a can't stop the server user from CREATING a month entry as a symlink/directory (planted). Those are never hardened:
+# they're reported and the script exits non-zero — after +a is applied to every valid file. The server refuses to
+# append through them and alerts owners. Remove one as root: chattr -a "$audit"; rm -r <entry>; re-run.
+set -euo pipefail
+
+[ "$(uname -s)" = Linux ] || { echo "harden-audit: Linux only (chattr) — nothing done" >&2; exit 1; }
+[ "$(id -u)" -eq 0 ] || { echo "harden-audit: must run as root (chattr +a needs CAP_LINUX_IMMUTABLE)" >&2; exit 1; }
+data="${1:-${DATA_DIR:-}}"
+[ -n "$data" ] || { echo "usage: $0 <DATA_DIR>" >&2; exit 2; }
+audit="$(realpath "$data")/audit"
+[ -d "$audit" ] && [ ! -L "$audit" ] || { echo "harden-audit: $audit is not a directory (start the server once first)" >&2; exit 1; }
+# Builds before tamper protection lock INSIDE the audit dir; in an append-only dir that lock can never be released.
+if [ -e "$audit/.lock" ]; then
+  {
+    echo "harden-audit: $audit/.lock exists — left by a pre-tamper-protection shraga (it locks inside the audit dir)."
+    echo "  1. Verify no old build is running against $data (e.g. ps -eo pid,args | grep shraga); upgrade or stop it."
+    if lsattr -d "$audit" 2>/dev/null | awk '{print $1}' | grep -q a; then
+      echo "  2. $audit is already append-only, so first: chattr -a '$audit'"
+      echo "  3. As root: rmdir '$audit/.lock'"
+    else
+      echo "  2. As root: rmdir '$audit/.lock'"
+    fi
+    echo "  Then re-run: $0 $data"
+  } >&2
+  exit 1
+fi
+
+chattr +a "$audit"
+shopt -s nullglob
+files=() bad=()
+for f in "$audit"/*.jsonl; do
+  if [ -f "$f" ] && [ ! -L "$f" ]; then files+=("$f"); else bad+=("$f"); fi
+done
+for f in "${files[@]}"; do chattr +a "$f"; done
+
+lsattr -d "$audit"
+[ ${#files[@]} -eq 0 ] || lsattr "${files[@]}"
+echo "harden-audit: $audit append-only (+${#files[@]} month files) — server can append, not truncate/delete/rename"
+
+if [ ${#bad[@]} -gt 0 ]; then
+  for f in "${bad[@]}"; do
+    echo "harden-audit: ERROR — $f is not a regular file ($(stat -c %F "$f" 2>/dev/null || echo unknown)$([ -L "$f" ] && echo " -> $(readlink "$f")")); possibly PLANTED to divert or disable auditing. NOT hardened. Inspect, then as root: chattr -a '$audit' && rm -r '$f' && $0 $data" >&2
+  done
+  exit 1
+fi

package/src/server/agent-config.ts

@@ -0,0 +1,34 @@
+// Agent config READ path (shared across users), as its own leaf module.
+//
+// Why it isn't in claude.ts: the security runtime reads a flag from it (`allowUntrustedReplies`, see
+// `mayReplyTo`), and claude.ts imports the runtime — plus the whole engine/skills/sessions graph. A leaf
+// that only touches fs + paths keeps that dependency one-way and cheap. The WRITE path stays in claude.ts
+// (it also has to tell data-sync, which pulls the Agent SDK).
+import { existsSync, readFileSync } from 'node:fs';
+import { dataPath } from './paths.ts';
+import type { AgentSettings as AgentConfig } from './shraga-config.ts';
+
+export const CONFIG_PATH = dataPath('agent-config.json');
+
+export const DEFAULT_CONFIG: AgentConfig = {
+  /** ToolSearch loads deferred MCP tools; without it, permission prompts / tool graph can block Meta Ads tools. */
+  allowedTools: ['Read', 'Edit', 'Bash', 'WebSearch', 'Glob', 'LS', 'ToolSearch'],
+  permissionMode: 'acceptEdits',
+  maxTurns: 15,
+  // Defaults are what a fresh self-hosted install runs before anyone touches the UI, so they favour
+  // cost/latency over ceiling. Both are overridable per-deployment via agent-config.json and per-send
+  // via directives — an operator who wants a bigger model sets it once; every operator pays for a default.
+  model: 'claude-sonnet-5',
+  effort: 'low',
+  // `allowUntrustedReplies` is deliberately absent: undefined = off, so a fresh install never auto-replies
+  // to an unverified sender, and an owner has to turn it on explicitly.
+};
+
+export function getAgentConfig(): AgentConfig {
+  // agent-config.json (UI-writable, git-tracked) is the single source of truth for agent settings.
+  let config = { ...DEFAULT_CONFIG };
+  if (existsSync(CONFIG_PATH)) {
+    try { Object.assign(config, JSON.parse(readFileSync(CONFIG_PATH, 'utf-8'))); } catch (e) { console.warn('[claude] failed to parse agent-config.json:', e); }
+  }
+  return config;
+}

package/src/server/api-key-routes.ts

@@ -0,0 +1,66 @@
+// API key list/create/delete, ONE implementation for both mounts: `/api/api-keys` (self) and `/api/owner/api-keys`
+// (owner console). Gates run per route, so mounting the router never gates unrelated requests.
+// Audit actor is always the caller's principal id. Store refusals (validation 400, PASSIVE 409) map to their status.
+import { Router, type Request, type RequestHandler, type Response } from 'express';
+import type { AuthUser } from './auth.ts';
+import { apiKeyStore, ApiKeyStoreError } from './api-keys.ts';
+import { security } from './security/runtime.ts';
+
+export class ApiKeyRoutesOptions {
+  base: string = '/api/api-keys';
+  gate: RequestHandler[] = [];
+  /** Extra gates for create/delete (after `gate`). */
+  writeGate: RequestHandler[] = [];
+  /** Owner console: sees/deletes every key and may set `role`/`expiresAt`. Self: own keys (all when the caller is an
+   *  owner, as before) and label only. */
+  asOwner: boolean = false;
+}
+
+const userOf = (req: Request) => (req as any).user as AuthUser;
+
+function fail(res: Response, e: any): void {
+  const status = e instanceof ApiKeyStoreError ? e.status : 400;
+  console.warn(`[api-keys] ${e?.message ?? e}`);
+  res.status(status).json({ error: e?.message ?? String(e) });
+}
+
+export function apiKeyRouter(options?: Partial<ApiKeyRoutesOptions>): Router {
+  const { base, gate, writeGate, asOwner } = { ...new ApiKeyRoutesOptions(), ...options };
+  const router = Router();
+  const isOwner = (u: AuthUser) => asOwner || u.isOwner;
+
+  router.get(base, ...gate, (req, res) => {
+    const user = userOf(req);
+    res.json({ keys: apiKeyStore().list({ uid: user.uid, isOwner: isOwner(user) }) });
+  });
+
+  /** Body: { label?, role?, expiresAt? (epoch ms) } — role/expiresAt honored on the owner mount only. Plaintext returned once. */
+  router.post(base, ...gate, ...writeGate, (req, res) => {
+    const user = userOf(req);
+    // Minting a key is minting a credential AS this identity — only an interactive login may (same rule as OAuth
+    // consent). Otherwise a role-capped or expiring key could mint itself an uncapped, non-expiring one.
+    const kind = user.principal?.kind ?? 'unknown';
+    if (kind !== 'user') {
+      console.warn(`[api-keys] create refused: non-interactive credential (${kind})`);
+      security()?.authDeny(`http:${base}`, `non-interactive:${kind}`, req.ip);
+      return void res.status(403).json({ error: 'Creating an API key requires an interactive login' });
+    }
+    const { label, role, expiresAt } = (req.body ?? {}) as { label?: string; role?: string; expiresAt?: number };
+    try {
+      const opts = asOwner ? { role, expiresAt } : {};
+      res.json(apiKeyStore().create(user.uid, user.email, label || 'Unnamed', { ...opts, actor: user.principal.id }));
+    } catch (e: any) { fail(res, e); }
+  });
+
+  router.delete(`${base}/:id`, ...gate, ...writeGate, (req: Request<{ id: string }>, res) => {
+    const user = userOf(req);
+    try {
+      const r = apiKeyStore().delete(req.params.id, user.uid, isOwner(user), user.principal.id);
+      if (r === 'not_found') return void res.status(404).json({ error: 'Key not found' });
+      if (r === 'forbidden') return void res.status(403).json({ error: 'Cannot delete another user\'s key' });
+      res.json({ ok: true });
+    } catch (e: any) { fail(res, e); }
+  });
+
+  return router;
+}