shraga 0.1.55 → 0.1.57

package/defaults/mcps/README.md

@@ -0,0 +1,41 @@
+# data/mcps/ — what is actually read, and when
+
+This directory holds **per-user MCP overlays only**. One file per user:
+
+    data/mcps/<uid>.json     →  read by getUserMcpConfig(uid)  (src/server/mcp.ts)
+
+Nothing else in this directory is loaded. There is **no `_global.json`** — a file by that name
+looks live and is not. Grep the loader before trusting any file here:
+
+    grep -rn "mcps/" src/server/mcp.ts
+
+## Where globals come from
+
+Global MCPs live in **`data/shraga.config.ts`** (legacy name `data/unclaw.config.ts`), read by
+`getGlobalMcpsFromConfig()`. The effective config for a user is:
+
+    { ...global (shraga.config.ts), ...user (mcps/<uid>.json) }     — the user overlay wins
+
+Only names present in the **global** config register as `/<name>` MCP commands
+(`listMcpCommands()`), and `PUT /api/mcps` strips any global name from a user overlay before
+saving — so a global MCP cannot be "added" by hand-writing a user file.
+
+## Cached vs live
+
+- `data/mcps/<uid>.json` — re-read on every call. Edit it and the next turn sees it.
+- `data/shraga.config.ts` — re-read when its mtime/size changes (`refreshConfig()` in
+  `src/server/shraga-config.ts`). Edit it and the next turn sees it too; **no restart needed**.
+  If the edited file fails to load, the process keeps the **last-good** config and logs
+  `[config] failed to load …` — check the server log before assuming your edit took.
+
+## Verify at runtime, don't assume
+
+    curl -sH "Authorization: Bearer $KEY" localhost:$PORT/api/mcps | jq 'keys'
+
+An entry with `"readonly": true` came from the global config; anything else is this user's overlay.
+
+## Why this file exists
+
+An intent-bearing commit ("lock agf-prod RTDB to read-only for the agent") once edited a
+`data/mcps/_global.json` that no loader has ever read. It was a silent no-op, and prod stayed
+writable until the gate was re-implemented in `shraga.config.ts`. Edit only what is read.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shraga",
-  "version": "0.1.55",
+  "version": "0.1.57",
   "description": "The teammate you delegate coding to — a self-hostable, multi-user AI coding agent web UI (Claude Code, with a pluggable engine seam).",
   "type": "module",
   "main": "./src/index.ts",

package/src/mcp-stdio-bridge.ts

@@ -1,11 +1,27 @@
 #!/usr/bin/env bun
 // stdio↔HTTP bridge for MCP (Streamable HTTP transport, maintains session ID)
 // Env: SHRAGA_URL + SHRAGA_API_KEY (preferred), or generic MCP_URL + MCP_API_KEY, or legacy UNCLAW_*
+//      MCP_EXTRA_HEADERS — optional JSON object of extra headers sent with every request,
+//      for servers that need a second credential beyond the bearer token (e.g. an
+//      upstream app behind a proxy that gates its own admin ops on its own header).
 const baseUrl = (process.env.SHRAGA_URL || process.env.MCP_URL || process.env.UNCLAW_URL || 'http://localhost:3033').replace(/\/$/, '');
 const mcpPath = process.env.SHRAGA_MCP_PATH || process.env.MCP_PATH || '/mcp';
 const apiKey = process.env.SHRAGA_API_KEY || process.env.MCP_API_KEY || process.env.UNCLAW_API_KEY;
 if (!apiKey) { console.error('[mcp-bridge] SHRAGA_API_KEY (or MCP_API_KEY/UNCLAW_API_KEY) is required'); process.exit(1); }
 
+let extraHeaders: Record<string, string> = {};
+if (process.env.MCP_EXTRA_HEADERS) {
+  try {
+    const parsed = JSON.parse(process.env.MCP_EXTRA_HEADERS);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('must be a JSON object');
+    extraHeaders = Object.fromEntries(Object.entries(parsed).map(([k, v]) => [k, String(v)]));
+  } catch (e: any) {
+    // Fail loudly: silently dropping a credential header would surface far away as a 403.
+    console.error(`[mcp-bridge] MCP_EXTRA_HEADERS is not a valid JSON object: ${e.message}`);
+    process.exit(1);
+  }
+}
+
 let sessionId: string | null = null;
 
 async function sendMessage(message: any): Promise<void> {
@@ -15,6 +31,7 @@ async function sendMessage(message: any): Promise<void> {
     'Accept': 'application/json, text/event-stream',
   };
   if (sessionId) headers['mcp-session-id'] = sessionId;
+  Object.assign(headers, extraHeaders);
 
   const res = await fetch(`${baseUrl}${mcpPath}`, {
     method: 'POST',

package/src/server/data-sync.ts

@@ -8,6 +8,64 @@ import { runTextQuery } from './sdk-utils.ts';
 const TAG = '[data-sync]';
 const DEPLOYMENT_ID_FILE = '.deployment-id';
 
+/** How long the LLM commit-message call may take before we fall back (ms). */
+const COMMIT_MSG_TIMEOUT_MS = 60_000;
+/** Warn if the push latch has been held longer than this — the 2026-08 outage's signature was silence. */
+const PUSHING_STUCK_MS = 5 * 60_000;
+
+/**
+ * Reject after `ms` so a hung subprocess can't hold the push latch forever.
+ * `onTimeout` runs on the timeout path only — use it to actually CANCEL the work
+ * (Promise.race alone abandons it, which orphaned one `claude` subprocess per timeout).
+ */
+export function withTimeout<T>(p: Promise<T>, ms: number, label: string, onTimeout?: () => void): Promise<T> {
+  let t: ReturnType<typeof setTimeout>;
+  return Promise.race([
+    p,
+    new Promise<T>((_, rej) => { t = setTimeout(() => { try { onTimeout?.(); } catch { /* cancel is best-effort */ } rej(new Error(`${label} timed out after ${ms}ms`)); }, ms); }),
+  ]).finally(() => clearTimeout(t!));
+}
+
+/** Deterministic, always-valid commit subject derived from the changed paths. */
+export function fallbackCommitMessage(files: string[]): string {
+  const names = files.filter(Boolean);
+  if (!names.length) return 'sync: update agent data';
+  const joined = `sync: ${names.join(', ')}`;
+  if (joined.length <= 72) return joined;
+  return `sync: ${names[0]} (+${names.length - 1} more)`.slice(0, 72);
+}
+
+// Only unambiguous "I'm about to explain" openers. Deliberately does NOT list common subject
+// starters like "the diff"/"this change" — those swallowed legitimate subjects
+// ("the diff view now renders inline"). Real prose is caught by the length guard below.
+const PROSE_PREAMBLE = /^(looking at|here'?s|here is|sure|certainly|based on|i'?ll|okay)\b/i;
+
+/**
+ * Pull a real commit subject out of a model reply. Bug 2026-08-26: the raw reply went straight to
+ * `git commit -m`, so a fence-only answer produced a commit literally titled "```".
+ * Returns '' when nothing usable is there — callers must use fallbackCommitMessage().
+ */
+export function extractCommitSubject(raw: string): string {
+  if (!raw) return '';
+  // Prefer the body of a fenced block if the model wrapped its answer in one.
+  const fenced = raw.match(/```[a-zA-Z]*\n([\s\S]*?)```/);
+  const body = fenced ? fenced[1] : raw.replace(/```[a-zA-Z]*/g, '');
+  for (const rawLine of body.split('\n')) {
+    let line = rawLine.trim();
+    if (!line) continue;
+    line = line.replace(/^(?:[-*>#]+|\d+[.)])\s*/, '').trim(); // bullets / numbered list / headings / quotes
+    line = line.replace(/^`+|`+$/g, '').trim();              // inline code ticks
+    line = line.replace(/^["'](.*)["']$/, '$1').trim();      // wrapping quotes
+    if (!line || /^`+$/.test(line) || line.includes('```')) continue;
+    if (line.length < 3) continue;
+    if (PROSE_PREAMBLE.test(line)) return '';                // model explained instead of answering
+    if (line.endsWith(':')) return '';                       // "Commit message:" style preamble
+    if (line.length > 72) return '';                         // longer than a subject line -> prose, never truncate
+    return line.slice(0, 72).trim();
+  }
+  return '';
+}
+
 export class DataSyncOptions {
   repoUrl = process.env.DATA_SYNC_REPO || '';
   branch = process.env.DATA_SYNC_BRANCH || 'main';
@@ -35,6 +93,7 @@ export class DataSync {
   private pending = new Set<string>();
   private timer: ReturnType<typeof setTimeout> | null = null;
   private pushing = false;
+  private pushingSince = 0;
   private pulling = false;
   private pullPending = false;
   private ready = false;
@@ -303,8 +362,14 @@ export class DataSync {
   }
 
   private async flush(): Promise<void> {
-    if (!this.pending.size || this.pushing) return;
+    if (!this.pending.size) return;
+    if (this.pushing) {
+      const held = Date.now() - this.pushingSince;
+      if (held > PUSHING_STUCK_MS) console.warn(`${TAG} Push latch held for ${Math.round(held / 1000)}s — sync is not pushing (pending: ${this.pending.size})`);
+      return;
+    }
     this.pushing = true;
+    this.pushingSince = Date.now();
     const files = [...this.pending];
     this.pending.clear();
     this.timer = null;
@@ -320,13 +385,13 @@ export class DataSync {
       }
 
       const status = await this.git('status', '--porcelain');
-      if (!status.trim()) { this.pushing = false; return; }
+      if (!status.trim()) return;
 
-      if (await this.guardMassDeletions('flush')) { this.pushing = false; return; }
+      if (await this.guardMassDeletions('flush')) return;
       const msg = await this.generateCommitMessage(files);
       await this.git('commit', '-m', msg).catch(() => {});
       const ahead = await this.git('rev-list', '--count', `origin/${this.options.branch}..HEAD`).catch(() => '0');
-      if (parseInt(ahead.trim()) === 0) { this.pushing = false; return; }
+      if (parseInt(ahead.trim()) === 0) return;
       await this.git('push', 'origin', this.options.branch).catch(async (err) => {
         console.warn(`${TAG} Push failed, pulling first:`, (err as Error).message);
         await this.pull();
@@ -336,26 +401,38 @@ export class DataSync {
       this.rebuildLog().catch(() => {});
     } catch (err) {
       console.error(`${TAG} Commit/push failed:`, (err as Error).message);
-    }
-    this.pushing = false;
-    if (this.pending.size && !this.timer) {
-      this.timer = setTimeout(() => this.flush(), 2000);
+    } finally {
+      // ALWAYS release the latch: any unsettled/throwing await used to wedge sync permanently,
+      // since every later flush() early-returns on `if (this.pushing) return`.
+      this.pushing = false;
+      if (this.pending.size && !this.timer) {
+        this.timer = setTimeout(() => this.flush(), 2000);
+      }
     }
   }
 
   private async generateCommitMessage(files: string[]): Promise<string> {
-    const fallback = `sync: ${files.join(', ')}`;
+    const fallback = fallbackCommitMessage(files);
     try {
       const diff = await this.git('diff', '--cached', '--stat').catch(() => '');
       const diffContent = await this.git('diff', '--cached', '--no-color', '-U2').catch(() => '');
       if (!diffContent.trim()) return fallback;
       const truncated = diffContent.slice(0, 3000);
-      const msg = await this.askClaude(
-        'Write a concise git commit message (max 72 chars, no quotes, no prefix like "feat:" or "sync:") for this change to an AI agent\'s behavioral config.\n' +
-        `Files: ${files.join(', ')}\nStats: ${diff}\n\nDiff:\n${truncated}`,
-        'haiku',
+      // Bounded: a hung `claude` subprocess used to wedge flush() forever (it holds the push latch).
+      const ac = new AbortController();
+      const msg = await withTimeout(
+        this.askClaude(
+          'Write a concise git commit message (max 72 chars, no quotes, no prefix like "feat:" or "sync:") for this change to an AI agent\'s behavioral config.\n' +
+          `Files: ${files.join(', ')}\nStats: ${diff}\n\nDiff:\n${truncated}`,
+          'haiku',
+          ac,
+        ),
+        Number(process.env.DATA_SYNC_COMMIT_MSG_TIMEOUT_MS) || COMMIT_MSG_TIMEOUT_MS,
+        'commit-message query',
+        () => ac.abort(),
       );
-      const line = msg.split('\n')[0].trim().slice(0, 72);
+      const line = extractCommitSubject(msg);
+      if (!line) console.warn(`${TAG} Unusable LLM commit msg, using fallback:`, JSON.stringify((msg || '').slice(0, 120)));
       return line || fallback;
     } catch (err) {
       console.warn(`${TAG} LLM commit msg failed:`, (err as Error).message);
@@ -586,8 +663,8 @@ export class DataSync {
    * which is unset on subscription-auth deployments — every merge-conflict resolution failed and
    * spammed owners via notifyOwners().
    */
-  private async askClaude(prompt: string, model: 'haiku' | 'sonnet' | 'opus' = 'sonnet'): Promise<string> {
-    return runTextQuery({ prompt, model, maxTurns: 1 });
+  private async askClaude(prompt: string, model: 'haiku' | 'sonnet' | 'opus' = 'sonnet', abortController?: AbortController): Promise<string> {
+    return runTextQuery({ prompt, model, maxTurns: 1, abortController });
   }
 
   private async getConflictedFiles(): Promise<string[]> {

package/src/server/engine/claude-code.ts

@@ -1,4 +1,5 @@
 import { query } from '@anthropic-ai/claude-agent-sdk';
+import { spawn } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { signInternalToken } from '../auth.ts';
@@ -118,18 +119,44 @@ function logCacheUsage(usage: any, model: string): void {
   console.log(`[claude] Cache: hit=${hitRate}% read=${read} write=${created} uncached=${fresh} out=${usage.output_tokens ?? 0} model=${model}`);
 }
 
+/** SDK spawn hook: same call the SDK would make, plus `detached` (own process group). See the
+ *  call site for why. Shape mirrors the SDK's own spawnLocalProcess return. */
+function spawnDetached(cfg: { command: string; args: string[]; cwd?: string; env: Record<string, string | undefined>; signal?: AbortSignal }) {
+  const child = spawn(cfg.command, cfg.args, {
+    cwd: cfg.cwd,
+    env: cfg.env,
+    signal: cfg.signal,
+    // Keep SDK debug output visible when it is asked for; otherwise the SDK's own default.
+    stdio: ['pipe', 'pipe', cfg.env.DEBUG_CLAUDE_AGENT_SDK ? 'inherit' : 'ignore'],
+    detached: true,
+    windowsHide: true,
+  });
+  return {
+    stdin: child.stdin,
+    stdout: child.stdout,
+    get killed() { return child.killed; },
+    get exitCode() { return child.exitCode; },
+    kill: child.kill.bind(child),
+    on: child.on.bind(child),
+    once: child.once.bind(child),
+    off: child.off.bind(child),
+  };
+}
+
 const INLINE_MIMES = new Set(['image/jpeg', 'image/png', 'image/gif', 'image/webp', 'application/pdf']);
 
 async function* buildAttachmentPrompt(text: string, attachments: { path: string; name: string; mimeType: string }[], sessionId: string): AsyncIterable<any> {
   const content: any[] = [];
   const fileRefs: string[] = [];
   const audioRefs: string[] = [];
+  const inlined: string[] = [];
   for (const att of attachments) {
     if (INLINE_MIMES.has(att.mimeType)) {
       try {
         const buf = readFileSync(att.path);
         const blockType = att.mimeType === 'application/pdf' ? 'document' : 'image';
         content.push({ type: blockType, source: { type: 'base64', media_type: att.mimeType, data: buf.toString('base64') } });
+        inlined.push(`${att.name} (${att.path})`);
       } catch (err) {
         console.error(`[claude] Failed to read attachment ${att.path}:`, err);
         fileRefs.push(`${att.name} (at ${att.path} — failed to read)`);
@@ -143,6 +170,12 @@ async function* buildAttachmentPrompt(text: string, attachments: { path: string;
   }
   if (audioRefs.length > 0) text += `\n\n[Audio attached — transcribe with the mcp-audio tool (post_audio_transcribe { file }) before answering]: ${audioRefs.join(', ')}`;
   if (fileRefs.length > 0) text += `\n\n[Attached files — use Read tool to access]: ${fileRefs.join(', ')}`;
+  // Say IN THE TEXT that the inlined blocks exist. `text` carries the whole conversation history, so
+  // the image blocks sit tens of thousands of tokens above the actual question and the model has
+  // answered "I don't see any images attached" to a message that had four — the transcript proves the
+  // blocks were sent. This line makes the prompt agree with its own content, and names the on-disk
+  // paths so the model can Read them if it still can't see a block.
+  if (inlined.length > 0) text += `\n\n[${inlined.length} file(s) are attached to THIS message and included above as image/document blocks — look at them: ${inlined.join(', ')}]`;
   content.push({ type: 'text', text });
   yield { type: 'user', message: { role: 'user', content }, parent_tool_use_id: null, session_id: sessionId };
 }
@@ -273,6 +306,14 @@ export class ClaudeCodeEngine implements AgentEngine {
     const addonSuffix = getPromptSuffix(opts.turnHints);
     options['systemPrompt'] = `${IMMUTABLE_SYSTEM_PROMPT}\n\n${userPrompt}${addonSuffix ? `\n\n${addonSuffix}` : ''}`;
     if (opts.abortController) options['abortController'] = opts.abortController;
+    // Spawn the CLI in its OWN process group. The service manager signals the whole JOB on restart
+    // (`launchctl kickstart -k`, `systemctl restart`), so an inherited process group means the child
+    // dies instantly with SIGTERM — surfacing mid-reply as `exited with code 143` and making the
+    // server's 90s drain (gracefulShutdown) protect nothing: it only ever waited for a turn that was
+    // already dead. Detached, the signal reaches the server alone and the drain can finish the turn.
+    // Teardown is unaffected: the SDK still kills the child on abort/close and on process exit.
+    options['spawnClaudeCodeProcess'] = spawnDetached;
+
     // Passed as a FILE, never as `options.mcpServers` — the SDK would put the whole config (every MCP
     // server's credentials) on the CLI's argv, where `ps` / `/proc` / journald expose it. See
     // writeMcpConfigFile. Setting both would re-add the argv copy, so it's one or the other.

package/src/server/sdk-utils.ts

@@ -9,6 +9,8 @@ export async function runTextQuery(opts: {
   model?: string;
   maxTurns?: number;
   systemPrompt?: string;
+  /** Passed to the SDK so a timed-out/cancelled call actually kills the `claude` subprocess. */
+  abortController?: AbortController;
 }): Promise<string> {
   const saved = process.env.CLAUDECODE;
   delete process.env.CLAUDECODE;
@@ -22,6 +24,7 @@ export async function runTextQuery(opts: {
         model,
         maxTurns: opts.maxTurns || 1,
         systemPrompt: opts.systemPrompt,
+        abortController: opts.abortController,
       },
     })) {
       const m = ev as any;

package/src/server/seed.ts

@@ -66,8 +66,16 @@ export function seedDefaults() {
     console.log(`[seed] Synced ${count} built-in subagent defs from defaults`);
   }
 
-  // MCPs dir: ensure it exists for per-user configs
+  // MCPs dir: ensure it exists for per-user configs, and ship the README that says what is
+  // actually read here. Load-bearing docs, not decoration: an operator once encoded a real
+  // security intent into a `data/mcps/_global.json` that no loader has ever opened, and the
+  // silent no-op left prod RTDB writable. Overwritten from defaults (like skills/extensions) —
+  // it's shipped documentation, not user data.
   mkdirSync(dataPath('mcps'), { recursive: true });
+  const mcpsReadme = path.join(DEFAULTS_DIR, 'mcps', 'README.md');
+  if (existsSync(mcpsReadme) && copyIfChanged(mcpsReadme, dataPath('mcps', 'README.md'))) {
+    console.log('[seed] Synced data/mcps/README.md from defaults');
+  }
 
   // Scripts: seed agent-facing scripts from defaults → data/scripts/
   const srcScripts = path.join(DEFAULTS_DIR, 'scripts');

package/src/server/self-upgrade/index.ts

@@ -72,6 +72,13 @@ export class SelfUpgrade {
       if (running.length) {
         reasons.push(`${running.length} scheduled job(s) still running (${running.join(', ')}) — restarting now would kill them mid-flight; retry when idle or pass {"force":true}`);
       }
+      // Same failure, other origin: an interactive Slack/web turn is not a scheduled job, so the
+      // check above never saw it and upgrades cut live replies off mid-sentence (143). Any held
+      // session lock means someone is mid-turn.
+      const turns = this.o.runningTurns();
+      if (turns) {
+        reasons.push(`${turns} agent turn(s) in flight — restarting now would cut the reply off mid-stream; retry when idle or pass {"force":true}`);
+      }
     }
     const pkgPath = path.join(this.o.appRoot, 'package.json');
 
@@ -254,6 +261,13 @@ export class SelfUpgradeOptions {
     catch (err) { console.warn(`${TAG} could not read running jobs:`, (err as Error).message); return []; }
   };
 
+  /** Interactive agent turns in flight (Slack/web/API), counted off the live session locks. Same
+   *  lazy+guarded shape as runningJobs, and injectable for the same reason. */
+  public runningTurns: () => number = () => {
+    try { return require('../sessions.ts').getActiveLockCount() as number; }
+    catch (err) { console.warn(`${TAG} could not read running turns:`, (err as Error).message); return 0; }
+  };
+
   /** Injectable so the preflight is testable without depending on the test host's PATH. */
   public hasPython3: () => boolean = () => {
     try { return spawnSync('python3', ['--version'], { stdio: 'ignore' }).status === 0; }

package/src/server/shraga-config.ts

@@ -1,4 +1,5 @@
-import { existsSync } from 'node:fs';
+import { existsSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import path from 'node:path';
 import { DATA_DIR, APP_ROOT } from './paths.ts';
 import type { McpServerConfig, McpConfig, McpHttpServerConfig } from './mcp.ts';
@@ -93,28 +94,151 @@ export function resolveConfigPath(): string | null {
 }
 
 let _cached: ShragaConfig | null = null;
+/** Config file the cache was built from, and its `mtimeMs:size` stamp. */
+let _cachedPath: string | null = null;
+let _cachedStamp = '';
+/** Stamp of the last version we failed to load — so a broken config logs once, not per call. */
+let _failedStamp = '';
+/** True once we've reported that a previously-present config file went missing (log once, not per call). */
+let _missingLogged = false;
 
-export async function loadShragaConfig(): Promise<ShragaConfig> {
-  if (_cached) return _cached;
+const _require = createRequire(import.meta.url);
+
+function stampOf(file: string): string {
+  try {
+    const st = statSync(file);
+    return `${st.mtimeMs}:${st.size}`;
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Load the config module SYNCHRONOUSLY, bypassing the runtime module cache.
+ *
+ * Busting `_cached` alone is not enough: `await import(p)` returns the SAME module object for a
+ * path already loaded, so an edited file is never re-evaluated (measured on Bun 1.3.10).
+ * `require` + a `require.cache` delete does re-evaluate — and being sync, it lets the sync
+ * consumers (`getGlobalMcpsFromConfig`, `getPublicOrigin`, …) pick up an edit with no call-site
+ * changes anywhere.
+ *
+ * Throws on a broken config; callers keep the last-good value.
+ */
+function readConfigSync(configPath: string): ShragaConfig {
+  // A 0-byte file is a TRUNCATED/FAILED WRITE, not an authored "no MCPs": `require` hands back `{}`
+  // for it without throwing, which would silently drop every global MCP. Fail loudly instead so the
+  // caller keeps the last-good value — and, because the stamp is not advanced, recovers by itself
+  // the moment the real content lands.
+  if (statSync(configPath).size === 0) {
+    throw new Error('config file is empty (0 bytes) — refusing to load it over the last-good config');
+  }
+  try {
+    // Delete by the RESOLVED key: the cache is keyed by the realpath, and DATA_DIR is often a
+    // symlinked path (macOS /var -> /private/var, or a symlinked data dir), so deleting the
+    // literal path silently misses and the stale module is returned.
+    const cache = _require.cache as Record<string, unknown> | undefined;
+    if (cache) {
+      delete cache[_require.resolve(configPath)];
+      delete cache[configPath];
+    }
+  } catch {
+    // A runtime without a mutable require.cache: fall through — the load below may still be fresh,
+    // and loadShragaConfig()'s async fallback covers the stale case.
+  }
+  const mod = _require(configPath);
+  return (mod?.default ?? {}) as ShragaConfig;
+}
+
+/**
+ * Re-read the config when the file changed on disk (mtime+size), so editing `shraga.config.ts`
+ * takes effect without restarting the process — the way editing `data/mcps/<uid>.json` already
+ * does. Returns the load error, or null.
+ *
+ * Fully synchronous, so two concurrent turns can never interleave into a torn cache.
+ */
+function refreshConfig(): unknown {
   const configPath = resolveConfigPath();
   if (!configPath) {
-    _cached = {};
-    return _cached;
+    // Cold start with no config at all: an empty config is the honest answer.
+    if (_cached === null) { _cached = {}; _cachedPath = null; _cachedStamp = ''; return null; }
+    // We HAD a config and the file is now gone — deleted, renamed, or a checkout/mount blip.
+    // Resetting the cache here would silently drop EVERY global MCP from a running process, with
+    // no log to explain it. Keep the last-good value (same policy as a config that fails to parse),
+    // say so once, and leave _cachedPath/_cachedStamp intact so a re-appearing file recovers.
+    if (_cachedPath !== null && !_missingLogged) {
+      _missingLogged = true;
+      console.error(
+        `[config] ${path.basename(_cachedPath)} is GONE from ${DATA_DIR} —`,
+        'KEEPING the last-good config in memory (global MCPs preserved)',
+      );
+    }
+    return null;
   }
+  _missingLogged = false;
+  const stamp = stampOf(configPath);
+  if (_cached !== null && configPath === _cachedPath && stamp === _cachedStamp) return null;
   try {
-    const mod = await import(configPath);
-    _cached = mod.default ?? {};
+    _cached = readConfigSync(configPath);
+    _cachedPath = configPath;
+    _cachedStamp = stamp;
+    _failedStamp = '';
+    return null;
   } catch (e) {
-    console.error(`[config] failed to load ${path.basename(configPath)}:`, e instanceof Error ? e.message : String(e));
-    _cached = {};
+    if (_failedStamp !== stamp) {
+      _failedStamp = stamp;
+      console.error(
+        `[config] failed to load ${path.basename(configPath)}:`,
+        e instanceof Error ? e.message : String(e),
+        _cached === null ? '— using an EMPTY config' : '— KEEPING the last-good config in memory',
+      );
+    }
+    // Never leave the process with no config, and never poison the cache with a broken file:
+    // keep the last-good value, and deliberately do NOT advance _cachedStamp so the next call
+    // retries (a fixed file recovers on its own).
+    if (_cached === null) { _cached = {}; _cachedPath = configPath; _cachedStamp = ''; }
+    return e;
+  }
+}
+
+/** Drop the cache so the next read re-evaluates the config file unconditionally. */
+export function invalidateShragaConfig(): void {
+  _cached = null;
+  _cachedPath = null;
+  _cachedStamp = '';
+  _failedStamp = '';
+}
+
+export async function loadShragaConfig(): Promise<ShragaConfig> {
+  const err = refreshConfig();
+  if (err) {
+    // `require` cannot load every valid ESM config (top-level await). Retry through the async
+    // loader — cache-busted, since a plain re-import of a loaded path returns the stale module.
+    const configPath = resolveConfigPath();
+    if (configPath) {
+      try {
+        const stamp = stampOf(configPath);
+        const mod = await import(`${configPath}?stamp=${encodeURIComponent(stamp)}`);
+        // We just awaited, so the world may have moved: another caller can have loaded a NEWER
+        // config synchronously while this import was in flight. Committing unconditionally would
+        // overwrite it with the older value AND stamp it as current — a lost update that hands the
+        // stale config to both callers. Commit only when the file on disk is still the version we
+        // imported and the cache has not already reached it.
+        if (stampOf(configPath) === stamp && _cachedStamp !== stamp) {
+          _cached = mod.default ?? {};
+          _cachedPath = configPath;
+          _cachedStamp = stamp;
+          _failedStamp = '';
+        }
+      } catch {
+        // Already logged by refreshConfig; last-good (or {}) stands.
+      }
+    }
   }
-  // Every path above assigns _cached a non-null value; `?? {}` satisfies the type
-  // without changing behavior (mirrors getShragaConfigSync below).
   return _cached ?? {};
 }
 
 export function getShragaConfigSync(): ShragaConfig {
-  if (!_cached) console.warn('[config] getShragaConfigSync called before loadShragaConfig — returning empty config');
+  refreshConfig();
   return _cached ?? {};
 }