@jhizzard/termdeck 1.0.11 → 1.0.13

package/packages/server/src/agent-adapters/claude.js

@@ -47,7 +47,34 @@ const IDLE = /^>\s*$/m;
 // sessions whose tool output (grep results, test logs, file dumps) routinely
 // mentions "Error" mid-line without representing an actual failure.
 // Sprint 40 T2 added mixed-case `Fatal` + the special-cased `npm ERR!` shape.
-const ERROR = /^\s*(?:(?:error|Error|ERROR|exception|Exception|Traceback|fatal|Fatal|FATAL|segmentation fault|panic|EACCES|ECONNREFUSED|ENOENT|command not found|undefined reference|cannot find module|failed with exit code|No such file or directory|Permission denied)\b|npm ERR!)/m;
+//
+// Sprint 57 T1 (F-T2-3): tightened from `\b`-after-keyword to require a
+// trailing colon + content for prose-shape keywords. The pre-Sprint-57
+// pattern matched line-start prose like "Error handling docs" and
+// "Error handling pattern" (`Error` + space, `\b` satisfied) — Sprint 55
+// T2 + T4 logged 196 fires / 22 dismissed (11%) on the daily-driver
+// project, mostly from boot-prompt content + markdown headings tripping
+// the pattern. The new shape mirrors the proven `PATTERNS.error` rule in
+// session.js (already locked by `tests/analyzer-error-fixtures.test.js`):
+// real errors say `Error: <msg>`, not bare `Error`.
+//
+// Kept as structural shapes (no colon required — the structure itself
+// disambiguates):
+//   • `Traceback (most recent call last):`
+//   • `npm ERR!`
+//   • `error[Ennn]:` (Rust borrow-checker / clippy errors)
+//   • `failed with exit code <digit>` (CI failure marker; trailing
+//     digit eliminates the "the build failed with exit code N last
+//     time" prose false positive)
+//
+// Removed entirely (caught by `PATTERNS.shellError` as the secondary
+// fallback in `_detectErrors` when they appear in real
+// `<cmd>: <path>: <phrase>` shape):
+//   • `command not found`, `undefined reference`, `cannot find module`
+//   • `No such file or directory`, `Permission denied`
+//   • `segmentation fault` (also covered by `\s*Segmentation fault\b`
+//     in shellError)
+const ERROR = /^\s*(?:(?:error|Error|ERROR|exception|Exception|fatal|Fatal|FATAL|EACCES|ECONNREFUSED|ENOENT|panic):\s+\S|Traceback \(most recent call last\):|npm ERR!|error\[E\d+\]:|failed with exit code\s+\d+\b)/m;
 
 // ──────────────────────────────────────────────────────────────────────────
 // statusFor — replaces the `case 'claude-code':` block of _updateStatus.

package/packages/server/src/config.js

@@ -59,8 +59,10 @@ function loadSecretsEnv() {
     const parsed = parseDotenv(raw);
     const keys = [];
     for (const [k, v] of Object.entries(parsed)) {
-      // Do not clobber pre-set process env; shell wins.
-      if (process.env[k] === undefined) {
+      // Do not clobber pre-set process env; shell wins. Sprint 59 T4-CODEX residual
+      // fix: also fill when parent env is empty string (Brad's actual failure shape
+      // includes DATABASE_URL= in the parent service environment, not only missing).
+      if (process.env[k] === undefined || process.env[k] === '') {
         process.env[k] = v;
       }
       keys.push(k);

package/packages/server/src/flashback-diag.js

@@ -156,6 +156,83 @@ function markClickedThrough(db, eventId) {
   }
 }
 
+// Sprint 57 T1 (#4): negative-feedback persistence read-side. Returns true
+// when ANY prior flashback_events row for this memory_id (`top_hit_id`)
+// has `dismissed_at` set — meaning the user previously dismissed (or
+// click-through-then-implicitly-dismissed) a flashback featuring this
+// same memory. The proactive emit path uses this to skip already-dismissed
+// memories before sending the next `proactive_memory` frame, so a
+// low-confidence hit the user marked "Not relevant" stops resurfacing.
+//
+// Scope is global (no `session_id` filter) — user intent is "this memory
+// isn't useful," not "this memory isn't useful in THIS session." Matches
+// the Sprint 55 T4-Codex audit-addendum brief shape
+// (`WHERE NOT EXISTS (... memory_id = X AND dismissed_at IS NOT NULL)`),
+// adapted to the actual schema column name `top_hit_id`.
+//
+// SAFE when db is null (returns false → caller falls back to default emit
+// path, identical to pre-Sprint-57 behavior) and when memoryId is empty
+// or non-string (returns false). Errors are caught and logged — must
+// never break the live emit path.
+function isMemoryDismissed(db, memoryId) {
+  if (!db || !memoryId || typeof memoryId !== 'string') return false;
+  try {
+    const row = db.prepare(`
+      SELECT 1 AS hit FROM flashback_events
+       WHERE top_hit_id = ? AND dismissed_at IS NOT NULL
+       LIMIT 1
+    `).get(memoryId);
+    return Boolean(row);
+  } catch (err) {
+    console.warn('[flashback-diag] isMemoryDismissed SELECT failed:', err.message);
+    return false;
+  }
+}
+
+// Sprint 57 T1 (#4): pure selection helper used by the proactive-emit path
+// in `packages/server/src/index.js`. Walks the score-ordered Mnestra
+// candidate list and returns:
+//   { hit, dismissedCount, scannedCount }
+// where:
+//   • hit          — the first candidate whose `candidate.id` is not in
+//                    the dismissed set (or null when every candidate was
+//                    dismissed / the list is empty)
+//   • dismissedCount — how many candidates were skipped because their
+//                    memory id is in the dismissed set
+//   • scannedCount — how many candidates were inspected before stopping
+//                    (= dismissedCount + 1 when a hit was returned;
+//                    = list length when nothing matched)
+//
+// Extracting this from `index.js` lets the integration path (see Sprint 57
+// T4-CODEX 14:24 ET audit) be tested directly without spawning a real PTY
+// + WS + Mnestra bridge. The pre-extraction inline version was unreachable
+// from a unit test.
+//
+// SAFE on null db (returns the first candidate without filtering — same
+// semantics as pre-Sprint-57 `memories[0]`) so non-DB installs still get
+// the legacy default-pick behavior. Empty / non-array memories returns
+// the empty-skip shape `{ hit: null, dismissedCount: 0, scannedCount: 0 }`.
+function pickNextNonDismissed(db, memories) {
+  const list = Array.isArray(memories) ? memories : [];
+  if (list.length === 0) {
+    return { hit: null, dismissedCount: 0, scannedCount: 0 };
+  }
+  if (!db) {
+    return { hit: list[0] || null, dismissedCount: 0, scannedCount: 1 };
+  }
+  let dismissedCount = 0;
+  let scannedCount = 0;
+  for (const candidate of list) {
+    scannedCount += 1;
+    if (candidate && candidate.id && isMemoryDismissed(db, candidate.id)) {
+      dismissedCount += 1;
+      continue;
+    }
+    return { hit: candidate || null, dismissedCount, scannedCount };
+  }
+  return { hit: null, dismissedCount, scannedCount };
+}
+
 // Reads the most-recent N flashback fires, optionally filtered to events
 // fired at-or-after the `since` ISO timestamp. Hard cap of 500 rows so
 // pathological queries can't OOM the dashboard.
@@ -220,6 +297,8 @@ module.exports = {
   recordFlashback,
   markDismissed,
   markClickedThrough,
+  isMemoryDismissed,
+  pickNextNonDismissed,
   getRecentFlashbacks,
   getFunnelStats,
 };

package/packages/server/src/graph-routes.js

@@ -114,6 +114,36 @@ function disabledPayload(extra = {}) {
   return Object.assign({ enabled: false, reason: 'DATABASE_URL not configured' }, extra);
 }
 
+// Sprint 57 T2 — opaque cursor for /api/graph/all pagination (F-T2-4).
+// The Sprint 55 sweep measured 1.2 MB / 862 ms for the single-shot all-projects
+// graph response. Cursor pagination lets callers fetch progressive pages while
+// preserving backward-compat: a no-cursor / no-limit request still returns the
+// historical single-shot ceiling (MAX_NODES_GLOBAL nodes).
+//
+// Cursor encodes the (created_at, id) row-key of the last item returned so the
+// next page resumes after it. Composite key disambiguates rows that share a
+// created_at timestamp.
+function encodeCursor(createdAt, id) {
+  if (!createdAt || !id) return null;
+  const iso = createdAt instanceof Date ? createdAt.toISOString() : String(createdAt);
+  return Buffer.from(JSON.stringify({ createdAt: iso, id })).toString('base64');
+}
+
+function decodeCursor(raw) {
+  if (raw == null || raw === '') return null;
+  try {
+    const json = Buffer.from(String(raw), 'base64').toString('utf8');
+    const obj = JSON.parse(json);
+    if (!obj || typeof obj.createdAt !== 'string' || typeof obj.id !== 'string') return null;
+    if (!UUID_RE.test(obj.id)) return null;
+    const t = new Date(obj.createdAt);
+    if (Number.isNaN(t.getTime())) return null;
+    return { createdAt: obj.createdAt, id: obj.id };
+  } catch (_e) {
+    return null;
+  }
+}
+
 async function fetchProjectGraph(pool, projectName) {
   // One round-trip:
   //   1. nodes for the project (with degree computed via subquery so we don't
@@ -162,12 +192,30 @@ async function fetchProjectGraph(pool, projectName) {
   return { nodes, edges };
 }
 
-async function fetchAllGraph(pool) {
+async function fetchAllGraph(pool, opts = {}) {
   // Sprint 41 T3 — backs the "All projects" picker option in /graph.html.
-  // Returns the most-recent MAX_NODES_GLOBAL active+non-archived memories plus
-  // every edge whose endpoints both land in the result set. `totalAvailable`
+  // Returns active+non-archived memories ordered by `(created_at DESC, id DESC)`
+  // plus every edge whose endpoints both land in the result set. `totalAvailable`
   // and `truncated` let the client surface a toast when the corpus overflows
   // the cap.
+  //
+  // Sprint 57 T2 (F-T2-4) — cursor pagination is now the DEFAULT path, not
+  // opt-in. Default page is 200 rows (matches the Sprint 55 measurement that
+  // 1.2 MB / 862 ms single-shot was the user-visible bug). Callers may pass
+  // `opts.limit` to override (capped at MAX_NODES_GLOBAL=2000). When
+  // `opts.cursor` is present, returns rows strictly past that (created_at,
+  // id) row-key. The returned `nextCursor` is non-null when more rows exist;
+  // clients loop until `nextCursor === null`. ORCH CLARIFICATION 14:21 ET:
+  // the default-payload bug doesn't close until pagination applies by
+  // default, so opt-in-only is not enough.
+  const DEFAULT_PAGE = 200;
+  const cursor = opts.cursor || null;
+  let limit = opts.limit;
+  if (limit == null || !Number.isFinite(Number(limit))) {
+    limit = DEFAULT_PAGE;
+  }
+  limit = Math.max(1, Math.min(MAX_NODES_GLOBAL, Math.floor(Number(limit))));
+
   const totalSql = `
     SELECT COUNT(*)::int AS c
       FROM memory_items
@@ -176,27 +224,62 @@ async function fetchAllGraph(pool) {
   const totalRes = await pool.query(totalSql);
   const totalAvailable = Number(totalRes.rows[0]?.c || 0);
 
-  const nodesSql = `
-    WITH all_nodes AS (
-      SELECT ${NODE_COLUMNS_SQL}
-        FROM memory_items
-       WHERE is_active = TRUE AND archived = FALSE
-       ORDER BY created_at DESC
-       LIMIT ${MAX_NODES_GLOBAL}
-    )
-    SELECT
-      n.*,
-      COALESCE((
-        SELECT COUNT(*)::int
-          FROM memory_relationships r
-         WHERE r.source_id = n.id OR r.target_id = n.id
-      ), 0) AS degree
-      FROM all_nodes n
-  `;
-  const nodesRes = await pool.query(nodesSql);
-  const nodes = nodesRes.rows.map(rowToNode);
+  // Fetch limit+1 rows so we know whether a next page exists without an extra
+  // count query. The +1 row is dropped before mapping.
+  let nodesSql;
+  let nodesParams;
+  if (cursor) {
+    nodesSql = `
+      WITH all_nodes AS (
+        SELECT ${NODE_COLUMNS_SQL}
+          FROM memory_items
+         WHERE is_active = TRUE AND archived = FALSE
+           AND (created_at, id) < ($1::timestamptz, $2::uuid)
+         ORDER BY created_at DESC, id DESC
+         LIMIT ${limit + 1}
+      )
+      SELECT
+        n.*,
+        COALESCE((
+          SELECT COUNT(*)::int
+            FROM memory_relationships r
+           WHERE r.source_id = n.id OR r.target_id = n.id
+        ), 0) AS degree
+        FROM all_nodes n
+    `;
+    nodesParams = [cursor.createdAt, cursor.id];
+  } else {
+    nodesSql = `
+      WITH all_nodes AS (
+        SELECT ${NODE_COLUMNS_SQL}
+          FROM memory_items
+         WHERE is_active = TRUE AND archived = FALSE
+         ORDER BY created_at DESC, id DESC
+         LIMIT ${limit + 1}
+      )
+      SELECT
+        n.*,
+        COALESCE((
+          SELECT COUNT(*)::int
+            FROM memory_relationships r
+           WHERE r.source_id = n.id OR r.target_id = n.id
+        ), 0) AS degree
+        FROM all_nodes n
+    `;
+    nodesParams = [];
+  }
+  const nodesRes = await pool.query(nodesSql, nodesParams);
+  let rows = nodesRes.rows;
+  const hasMore = rows.length > limit;
+  if (hasMore) rows = rows.slice(0, limit);
+  const nodes = rows.map(rowToNode);
+  let nextCursor = null;
+  if (hasMore && rows.length > 0) {
+    const last = rows[rows.length - 1];
+    nextCursor = encodeCursor(last.created_at, last.id);
+  }
   if (nodes.length === 0) {
-    return { nodes: [], edges: [], totalAvailable, truncated: false };
+    return { nodes: [], edges: [], totalAvailable, truncated: false, nextCursor: null };
   }
   const ids = nodes.map((n) => n.id);
 
@@ -208,11 +291,18 @@ async function fetchAllGraph(pool) {
   `;
   const edgesRes = await pool.query(edgesSql, [ids]);
   const edges = edgesRes.rows.map(rowToEdge);
+  // `truncated` preserves the pre-Sprint-57 semantic for the no-cursor case
+  // ("the corpus has more rows than this single-shot response can carry").
+  // For paginated callers, `nextCursor !== null` is the more-pages signal;
+  // `truncated` always returns false on cursor pages so a single-shot client
+  // doesn't mistakenly read intermediate page boundaries as global truncation.
+  const truncated = !cursor && totalAvailable > MAX_NODES_GLOBAL;
   return {
     nodes,
     edges,
     totalAvailable,
-    truncated: totalAvailable > MAX_NODES_GLOBAL,
+    truncated,
+    nextCursor,
   };
 }
 
@@ -537,10 +627,34 @@ function createGraphRoutes({ app, getPool }) {
         edges: [],
         totalAvailable: 0,
         truncated: false,
+        nextCursor: null,
       }));
     }
+    // Sprint 57 T2 — cursor pagination IS the default path (F-T2-4).
+    // No-cursor / no-limit requests get the first 200-row page; clients
+    // loop via `nextCursor` to fetch additional pages. ORCH CLARIFICATION
+    // 14:21 ET: pagination must apply by default, not opt-in, so the
+    // 1.2 MB / 862 ms single-shot payload measured in Sprint 55 is the
+    // bug we're closing. A malformed `cursor` returns 400 rather than
+    // silently restarting from page 1, so pagination loops can't
+    // accidentally infinite-loop on garbled tokens.
+    let cursor = null;
+    if (req.query.cursor != null && req.query.cursor !== '') {
+      cursor = decodeCursor(req.query.cursor);
+      if (!cursor) {
+        return res.status(400).json({ error: 'invalid cursor' });
+      }
+    }
+    let limit = null;
+    if (req.query.limit != null && req.query.limit !== '') {
+      const n = Number(req.query.limit);
+      if (!Number.isFinite(n) || n < 1) {
+        return res.status(400).json({ error: 'invalid limit' });
+      }
+      limit = n;
+    }
     try {
-      const { nodes, edges, totalAvailable, truncated } = await fetchAllGraph(pool);
+      const { nodes, edges, totalAvailable, truncated, nextCursor } = await fetchAllGraph(pool, { cursor, limit });
       const byType = {};
       for (const e of edges) {
         byType[e.kind] = (byType[e.kind] || 0) + 1;
@@ -558,6 +672,7 @@ function createGraphRoutes({ app, getPool }) {
         edges,
         totalAvailable,
         truncated,
+        nextCursor,
       });
     } catch (err) {
       console.warn('[graph] /api/graph/all failed:', err.message);
@@ -646,6 +761,8 @@ module.exports = {
   rowToEdge,
   rowToFullMemory,
   snippet,
+  encodeCursor,
+  decodeCursor,
   UUID_RE,
   PROJECT_RE,
   MAX_NODES_PER_PROJECT,

package/packages/server/src/index.js

@@ -81,6 +81,8 @@ const { createProjectsRoutes } = require('./projects-routes');
 const orchestrationPreview = require('./orchestration-preview');
 const { createPtyReaper } = require('./pty-reaper');
 const { AGENT_ADAPTERS } = require('./agent-adapters');
+const { deriveRagMode } = require('./rag-mode');
+const { resolveSpawnShell } = require('./spawn-shell');
 
 // Sprint 48 T4 deliverable 2: PTY env-var propagation.
 // Reads ~/.termdeck/secrets.env once per server lifetime so each PTY spawn
@@ -324,6 +326,26 @@ function createServer(config) {
       if (orphaned.changes > 0) {
         console.log(`[db] Marked ${orphaned.changes} orphaned session(s) as exited`);
       }
+      // Sprint 59 T4-CODEX cleanup: reap upload tempdirs whose owning session is
+      // exited or unknown (crashed processes, hard kills, pre-this-version dirs).
+      try {
+        const uploadsRoot = path.join(os.tmpdir(), 'termdeck-uploads');
+        if (fs.existsSync(uploadsRoot)) {
+          const liveIds = new Set();
+          try {
+            for (const row of db.prepare('SELECT id FROM sessions WHERE exited_at IS NULL').all()) {
+              liveIds.add(row.id);
+            }
+          } catch (_e) { /* live-set empty → all dirs are stale */ }
+          let reaped = 0;
+          for (const dir of fs.readdirSync(uploadsRoot)) {
+            if (!liveIds.has(dir)) {
+              try { fs.rmSync(path.join(uploadsRoot, dir), { recursive: true, force: true }); reaped++; } catch (_e) {}
+            }
+          }
+          if (reaped > 0) console.log(`[uploads] Reaped ${reaped} stale upload tempdir(s)`);
+        }
+      } catch (_err) { /* non-blocking */ }
       console.log('[db] SQLite initialized');
     } catch (err) {
       console.warn('[db] SQLite init failed:', err.message);
@@ -954,7 +976,13 @@ function createServer(config) {
       const PLAIN_SHELLS = /^(zsh|bash|fish|sh|dash|tcsh|ksh|csh|pwsh|powershell)$/i;
       const isPlainShell = PLAIN_SHELLS.test(cmdTrim);
 
-      const spawnShell = isPlainShell ? cmdTrim : (config.shell || '/bin/zsh');
+      // Sprint 59 T2 — Brad #5: resolveSpawnShell chains config.shell →
+      // $SHELL → /bin/sh so a host without zsh (Alpine, minimal Ubuntu after
+      // `apt remove zsh`) still spawns a working interactive shell instead of
+      // failing silently from execvp(/bin/zsh).
+      const spawnShell = isPlainShell
+        ? cmdTrim
+        : resolveSpawnShell('', config.shell, process.env.SHELL);
       const args = (cmdTrim && !isPlainShell) ? ['-c', cmdTrim] : [];
 
       try {
@@ -1041,6 +1069,14 @@ function createServer(config) {
           onPanelClose(session).catch((err) => {
             console.error('[onPanelClose] async error:', err && err.message ? err.message : err);
           });
+
+          // Sprint 59 T4-CODEX UPLOAD-AUDIT-CONCERN closure: blow away the
+          // per-session upload tempdir so dropped files don't outlive the panel
+          // that received them. Fire-and-forget; never blocks teardown.
+          try {
+            const sessUploadDir = path.join(os.tmpdir(), 'termdeck-uploads', session.id);
+            fs.rmSync(sessUploadDir, { recursive: true, force: true });
+          } catch (_err) { /* non-blocking */ }
         });
 
         // Wire command logging to SQLite + RAG
@@ -1082,17 +1118,32 @@ function createServer(config) {
             const memories = (result && result.memories) || [];
             const count = memories.length;
             console.log(`[flashback] query returned ${count} matches for session ${sess.id}`);
-            const hit = memories[0];
+            // Sprint 57 T1 (#4): negative-feedback persistence. Skip any
+            // memory the user previously dismissed (across all sessions);
+            // iterate candidates in score order, first non-dismissed wins.
+            // Without this, a low-confidence match the user marked
+            // "Not relevant" would resurface on the next error fire —
+            // exactly the resurfacing-after-dismiss bug Sprint 55 T2 + T4
+            // diagnosed (T4 audit addendum: index.js:1058-1100 emits
+            // memories[0] without consulting dismissed history). Selection
+            // logic lives in `flashbackDiag.pickNextNonDismissed` so the
+            // integration shape stays testable without a live PTY.
+            const { hit, dismissedCount } =
+              flashbackDiag.pickNextNonDismissed(db, memories);
             const wsReadyState = sess.ws ? sess.ws.readyState : null;
             if (!hit) {
-              console.log(`[flashback] no matches — skipping proactive_memory send for session ${sess.id}`);
+              const allDismissed = count > 0 && dismissedCount === count;
+              const outcome = allDismissed ? 'dropped_dismissed' : 'dropped_empty';
+              console.log(`[flashback] ${allDismissed
+                ? `all ${count} candidate(s) previously dismissed`
+                : 'no matches'} — skipping proactive_memory send for session ${sess.id}`);
               flashbackDiag.log({
                 sessionId: sess.id,
                 event: 'proactive_memory_emit',
                 ws_ready_state: wsReadyState,
                 frame_size_bytes: 0,
-                result_count_in_frame: 0,
-                outcome: 'dropped_empty',
+                result_count_in_frame: allDismissed ? dismissedCount : 0,
+                outcome,
               });
               return;
             }
@@ -1276,6 +1327,47 @@ function createServer(config) {
     res.json({ ok: true, bytes: normalized.length, replyCount: session.meta.replyCount });
   });
 
+  // POST /api/sessions/:id/upload?name=<filename> - File drop / clipboard image paste
+  // Body: raw octet-stream of the file content (max 50MB).
+  // Writes to /tmp/termdeck-uploads/<sessionId>/<sanitizedName>, returns {ok, path, name, size}.
+  // Client typically follows up with POST /api/sessions/:id/input { text: "@<path> " } so
+  // the agent (Claude/Codex/Gemini/Grok) sees the standard @filepath attachment syntax.
+  // Added Sprint 59 (2026-05-07) to close Brad's "how do I drop a zip into Codex" gap.
+  app.post('/api/sessions/:id/upload',
+    express.raw({ type: '*/*', limit: '50mb' }),
+    (req, res) => {
+      const session = sessions.get(req.params.id);
+      if (!session) return res.status(404).json({ error: 'Session not found' });
+      if (session.meta.status === 'exited' || !session.pty) {
+        return res.status(404).json({ error: 'Session is exited' });
+      }
+
+      const rawName = (req.query.name || '').toString();
+      if (!rawName) return res.status(400).json({ error: 'Missing ?name=' });
+      // Sanitize: strip path traversal + control chars; cap at 200 chars.
+      // Replace anything not alphanumeric / dash / underscore / dot / space with _
+      const safeName = rawName
+        .replace(/[\x00-\x1f\x7f/\\]/g, '_')
+        .replace(/^\.+/, '_')
+        .replace(/\.\.+/g, '_')
+        .slice(0, 200) || 'upload.bin';
+
+      if (!Buffer.isBuffer(req.body) || req.body.length === 0) {
+        return res.status(400).json({ error: 'Empty body' });
+      }
+
+      const uploadsRoot = path.join(os.tmpdir(), 'termdeck-uploads', session.id);
+      try {
+        fs.mkdirSync(uploadsRoot, { recursive: true, mode: 0o700 });
+        const fullPath = path.join(uploadsRoot, safeName);
+        fs.writeFileSync(fullPath, req.body, { mode: 0o600 });
+        res.json({ ok: true, path: fullPath, name: safeName, size: req.body.length });
+      } catch (err) {
+        return res.status(500).json({ error: err.message });
+      }
+    }
+  );
+
   // POST /api/sessions/:id/poke - PTY-flush recovery endpoint
   // Body: { methods?: ('sigcont' | 'bracketed-paste' | 'cr-flood' | 'all')[] }  default ['all']
   // Used to recover from the post-stop PTY delivery gap where injected input via /input
@@ -1492,6 +1584,11 @@ function createServer(config) {
       ragConfigEnabled: !!(config.rag && config.rag.enabled),
       ragSupabaseConfigured: !!(config.rag?.supabaseUrl && config.rag?.supabaseKey),
       aiQueryAvailable: !!(config.rag?.supabaseUrl && config.rag?.supabaseKey && config.rag?.openaiApiKey),
+      // Sprint 57 T2 (F-T2-2 + F-T2-6) — derived 3-state enum: 'off' |
+      // 'pending' | 'active'. Single source of truth across /api/config,
+      // /api/rag/status, /api/status. Replaces per-client derivation of
+      // the "RAG · on / pending / mcp-only" label.
+      ragMode: deriveRagMode(rag, config),
       statusColors,
       firstRun
     };
@@ -1644,7 +1741,9 @@ function createServer(config) {
       byType,
       uptime: process.uptime(),
       memory: process.memoryUsage(),
-      ragEnabled: rag.enabled
+      ragEnabled: rag.enabled,
+      // Sprint 57 T2 — single-source-of-truth ragMode enum (see rag-mode.js).
+      ragMode: deriveRagMode(rag, config)
     });
   });
 
@@ -1660,11 +1759,16 @@ function createServer(config) {
 
   // GET /api/rag/status - RAG system status
   app.get('/api/rag/status', (req, res) => {
-    if (!db) return res.json({ enabled: false, localEvents: 0, unsynced: 0 });
+    if (!db) return res.json({ enabled: false, ragMode: deriveRagMode(rag, config), localEvents: 0, unsynced: 0 });
     const total = db.prepare('SELECT COUNT(*) as n FROM rag_events').get().n;
     const unsynced = db.prepare('SELECT COUNT(*) as n FROM rag_events WHERE synced = 0').get().n;
     res.json({
       enabled: rag.enabled,
+      // Sprint 57 T2 — single-source-of-truth ragMode enum. Programmatic
+      // clients (CLI, MCP, CI) consume this directly instead of re-deriving
+      // from the flat `enabled` boolean which can't distinguish "MCP-only by
+      // intent" from "intent on but Supabase missing."
+      ragMode: deriveRagMode(rag, config),
       supabaseConfigured: !!(rag.supabaseUrl),
       localEvents: total,
       unsynced,

package/packages/server/src/rag-mode.js

@@ -0,0 +1,43 @@
+'use strict';
+
+// Sprint 57 T2 (F-T2-2 + F-T2-6) — single source of truth for the RAG mode
+// enum surfaced across /api/config, /api/rag/status, and /api/status.
+//
+// Sprint 55's T2 sweep found the three endpoints exposed inconsistent
+// shapes: /api/config carried four booleans (ragEnabled, ragConfigEnabled,
+// ragSupabaseConfigured, aiQueryAvailable) and the dashboard derived a
+// 3-state label (`RAG · on` / `pending` / `mcp-only`) from them, while
+// /api/rag/status and /api/status only exposed a flat `enabled` boolean —
+// programmatic clients (CLI, MCP wrapper, CI smoke tests, future Telegram
+// bot) couldn't distinguish "MCP-only by user intent" from "intent on but
+// Supabase missing." Every client re-derived its own mode rule, which is
+// the cross-endpoint inconsistency Sprint 57 closes.
+//
+// Direction (a) per orchestrator GREEN-LIGHT 2026-05-05 14:16 ET: keep the
+// existing booleans on /api/config (backward compat), add a single derived
+// `ragMode` enum on all three endpoints. The enum is computed once via
+// `deriveRagMode(rag, config)` and consumed directly by the dashboard's
+// `updateRagIndicator()`.
+//
+// Returns:
+//   "off"     — user opted into MCP-only mode (intent=false). Memory tools
+//               still work via MCP; the in-CLI `termdeck flashback`
+//               command + hybrid search are disabled. UI label "RAG · mcp-only".
+//   "pending" — user enabled RAG in config.yaml but the runtime isn't
+//               actually serving (Supabase missing/unreachable at boot,
+//               or otherwise not effective). UI label "RAG · pending".
+//   "active"  — RAG fully operational (effective=true). UI label "RAG · on".
+//
+// Forward-compat: future fourth states (e.g. "degraded" for partial
+// Supabase failure modes) MUST extend this union, not replace it. New
+// endpoints should consume `ragMode` rather than re-derive from booleans
+// — that's the whole point of the helper.
+function deriveRagMode(rag, config) {
+  const effective = !!(rag && rag.enabled);
+  const intent = !!(config && config.rag && config.rag.enabled);
+  if (effective) return 'active';
+  if (intent) return 'pending';
+  return 'off';
+}
+
+module.exports = { deriveRagMode };

package/packages/server/src/setup/dotenv-io.js

@@ -40,13 +40,22 @@ function readSecretsRaw(filepath = SECRETS_PATH) {
 }
 
 // Escape a value for safe re-serialization. Wraps in double quotes if the
-// value contains whitespace, `#`, or `"`. Always safe to wrap — we wrap when
-// in doubt to avoid ambiguity with the dotenv parser.
+// value contains whitespace, `#`, or a quote char. `=` was previously in the
+// regex but excluded after Sprint 59 Brad #2 — every Postgres URL with query
+// params (e.g. `?sslmode=require`) contains `=`, and dotenv splits a line on
+// the FIRST `=` only, so subsequent `=` chars in the value need no quoting.
+// Quoting URLs broke the "writer must never add surrounding quotes to a
+// DATABASE_URL" contract; the value still round-tripped because every reader
+// strips matching quotes, but a downstream consumer that sourced the file
+// via `set -a; . secrets.env` and didn't strip would see a literal-quoted
+// value re-introduced into process.env. Keeping the regex tight to actual
+// dotenv ambiguities (whitespace, `#` for comments, embedded quote chars)
+// avoids that round-trip-but-not-quite class of bug at the source.
 function formatValue(value) {
   if (value == null) return '';
   const str = String(value);
   if (str === '') return '';
-  const needsQuoting = /[\s#"'=]/.test(str);
+  const needsQuoting = /[\s#"']/.test(str);
   if (!needsQuoting) return str;
   const escaped = str.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
   return `"${escaped}"`;