@jhizzard/termdeck 1.0.12 → 1.0.13

package/README.md

@@ -1,5 +1,7 @@
 # TermDeck
 
+[![Install Smoke](https://github.com/jhizzard/termdeck/workflows/install-smoke/badge.svg)](https://github.com/jhizzard/termdeck/actions/workflows/install-smoke.yml)
+
 > **The terminal that remembers what you fixed last month.**
 
 A browser-based terminal multiplexer with an onboarding tour, rich per-panel metadata, and **Flashback** — automatic recall of similar past errors, surfaced the moment a panel hits a problem. No asking, no querying, no manual search. TermDeck notices you're stuck and offers the memory.
@@ -16,6 +18,8 @@ npx @jhizzard/termdeck
 
 Ninety seconds, one command. Node 18+ is all you need — prebuilt binaries mean no C++ toolchain. Your browser opens automatically at `http://127.0.0.1:3000`, an onboarding tour walks you through every button, and you're launching real PTY shells, Claude Code, Python servers, or anything else a normal terminal can run.
 
+> **Linux x64 — one-line caveat.** If `npm config get omit` returns `optional`, append `--include=optional` to any global TermDeck or `@anthropic-ai/claude-code` install (`npm install -g @jhizzard/termdeck --include=optional`). On macOS this is unnecessary. Full explanation in [docs/GETTING-STARTED.md § Linux x64 install hint](docs/GETTING-STARTED.md#linux-x64-install-hint).
+
 This is **Tier 1**. Works immediately, fully local, no accounts, no credentials, no database. You get the full dashboard — 7 grid layouts, 8 themes, per-panel metadata overlays, terminal switcher, reply button, status logs, session history in local SQLite. **Flashback is silent at this tier** because there's no memory store to query.
 
 First-time user? The **config** button in the toolbar shows what's set up and what's next — click it for a live view of each tier's status with guided next steps.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhizzard/termdeck",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "description": "Browser-based terminal multiplexer with metadata overlays, panel flashback memory recall, and AI-aware session management",
   "bin": {
     "termdeck": "./packages/cli/src/index.js"

package/packages/cli/src/doctor.js

@@ -160,6 +160,32 @@ function _compareSemver(a, b) {
   return 0;
 }
 
+// Sprint 58 T2 (Brad #4) — Mnestra-version probe used to gate the hybrid-
+// search RPC name in `_runSchemaCheck`. Mnestra ≤ 0.3.x exposes
+// `search_memories(...)`; Mnestra ≥ 0.4.0 renamed it to
+// `memory_hybrid_search(...)`. Pre-fix doctor hard-coded `search_memories`,
+// false-flagging RED on every install at Mnestra 0.4.0+. Reuses
+// `_detectInstalled` (the same `npm ls -g` probe the version-check section
+// already runs). Returns the installed version string or null if not
+// detectable. Exposed as its own module export so unit tests can monkey-
+// patch it independently of the rest of the doctor pipeline.
+async function _detectMnestraVersion() {
+  return module.exports._detectInstalled('@jhizzard/mnestra');
+}
+
+// Sprint 58 T2 (Brad #4) — RPC names to probe for the Mnestra hybrid-search
+// function, gated on the installed Mnestra version.
+//   ≥ 0.4.0       → ['memory_hybrid_search']
+//   ≤ 0.3.x       → ['search_memories']
+//   null/unknown  → ['memory_hybrid_search', 'search_memories'] (probe both;
+//                    GREEN if either exists — graceful on offline / non-
+//                    globally-installed cases).
+function _selectHybridSearchRpcNames(mnestraVersion) {
+  if (!mnestraVersion) return ['memory_hybrid_search', 'search_memories'];
+  if (_compareSemver(mnestraVersion, '0.4.0') >= 0) return ['memory_hybrid_search'];
+  return ['search_memories'];
+}
+
 function classifyRow(installed, latest) {
   if (latest === null) return STATUS.NETWORK_ERROR;
   if (installed === null) return STATUS.NOT_INSTALLED;
@@ -354,13 +380,45 @@ async function _runSchemaCheck(opts = {}) {
       status: (await probeSchema(client, SCHEMA_QUERIES.column('memory_items', 'source_session_id'))) ? 'pass' : 'fail',
       hint: `migration 007 adds it — run: npm cache clean --force && npm i -g @jhizzard/termdeck@latest && termdeck init --mnestra --yes`,
     });
-    for (const fn of ['match_memories', 'search_memories', 'memory_status_aggregation']) {
-      modern.push({
-        label: `${fn}() RPC`,
-        status: (await probeSchema(client, SCHEMA_QUERIES.rpc(fn))) ? 'pass' : 'fail',
-        hint: `migration 005/006 creates it — re-run: termdeck init --mnestra --yes`,
-      });
+    modern.push({
+      label: `match_memories() RPC`,
+      status: (await probeSchema(client, SCHEMA_QUERIES.rpc('match_memories'))) ? 'pass' : 'fail',
+      hint: `migration 005/006 creates it — re-run: termdeck init --mnestra --yes`,
+    });
+
+    // Sprint 58 T2 (Brad #4): version-gate the hybrid-search RPC name. The
+    // function was renamed `search_memories` → `memory_hybrid_search` at
+    // Mnestra 0.4.0. Pre-fix doctor probed only the legacy name, so every
+    // install at Mnestra ≥ 0.4.0 reported false-RED here. The version is
+    // passed in by `doctor()` (which already detected it for the version-
+    // check table); when called standalone, we self-detect.
+    const mnestraVersion = optsObj.mnestraVersion !== undefined
+      ? optsObj.mnestraVersion
+      : await module.exports._detectMnestraVersion();
+    const hybridProbeNames = _selectHybridSearchRpcNames(mnestraVersion);
+    const hybridProbeLabel = hybridProbeNames.length === 1
+      ? `${hybridProbeNames[0]}() RPC`
+      : `${hybridProbeNames.join(' or ')}() RPC`;
+    let hybridOk = false;
+    for (const name of hybridProbeNames) {
+      if (await probeSchema(client, SCHEMA_QUERIES.rpc(name))) {
+        hybridOk = true;
+        break;
+      }
     }
+    modern.push({
+      label: hybridProbeLabel,
+      status: hybridOk ? 'pass' : 'fail',
+      hint: mnestraVersion
+        ? `Mnestra ${mnestraVersion} expects ${hybridProbeNames[0]}() — re-run: termdeck init --mnestra --yes`
+        : `migration 005 (legacy) or 015+ (modern) creates it — re-run: termdeck init --mnestra --yes`,
+    });
+
+    modern.push({
+      label: `memory_status_aggregation() RPC`,
+      status: (await probeSchema(client, SCHEMA_QUERIES.rpc('memory_status_aggregation'))) ? 'pass' : 'fail',
+      hint: `migration 005/006 creates it — re-run: termdeck init --mnestra --yes`,
+    });
 
     // Mnestra legacy (Sprint 35 T2 ships these via 008_legacy_rag_tables.sql)
     const legacy = sections[1].checks;
@@ -510,10 +568,15 @@ async function doctor(argv) {
   );
 
   // Sprint 35 T3: schema check (skippable for tests / offline runs).
+  // Sprint 58 T2 (Brad #4): pass the already-detected Mnestra version
+  // through so `_runSchemaCheck` doesn't re-shell-out to `npm ls -g`. The
+  // version-check section detected it a few lines up; reuse it.
   let schema = null;
   if (!opts.noSchema) {
+    const mnestraRow = rows.find((r) => r.package === '@jhizzard/mnestra');
+    const mnestraVersion = mnestraRow ? mnestraRow.installed : null;
     try {
-      schema = await module.exports._runSchemaCheck();
+      schema = await module.exports._runSchemaCheck({ mnestraVersion });
     } catch (err) {
       schema = {
         skipped: false,
@@ -559,6 +622,8 @@ module.exports = doctor;
 module.exports._detectInstalled = _detectInstalled;
 module.exports._fetchLatest = _fetchLatest;
 module.exports._compareSemver = _compareSemver;
+module.exports._detectMnestraVersion = _detectMnestraVersion;
+module.exports._selectHybridSearchRpcNames = _selectHybridSearchRpcNames;
 module.exports._runSchemaCheck = _runSchemaCheck;
 module.exports.STACK_PACKAGES = STACK_PACKAGES;
 module.exports.STATUS = STATUS;

package/packages/cli/src/index.js

@@ -14,7 +14,93 @@
 const path = require('path');
 const fs = require('fs');
 const os = require('os');
-const { exec, execSync } = require('child_process');
+const { exec, execSync, spawn } = require('child_process');
+
+// Sprint 59 — Brad #1 nohup-secrets bootstrap.
+//
+// Brad's environment: `nohup termdeck --no-stack ...` from a shell that has
+// NOT sourced ~/.termdeck/secrets.env. In-process `setenv()` (which Node's
+// loadSecretsEnv() uses) updates libc's `environ` pointer but does NOT
+// propagate to /proc/<pid>/environ on Linux glibc — the kernel reads from
+// the env_start..env_end memory range fixed at execve() time, and new keys
+// added via setenv() get heap-allocated outside that range. A probe that
+// introspects /proc therefore sees the empty initial env.
+//
+// Fix: when launched in non-TTY mode (nohup detaches stdin/stdout/stderr)
+// AND secrets.env exists with at least one key not already in process.env,
+// spawn a detached child node with the merged env and exit the parent. The
+// child's /proc/<pid>/environ contains the merged keys because spawn() goes
+// through fork+execve(), which sets the kernel env range with the new env.
+//
+// Guards (must ALL be true to spawn-and-exit):
+//   1. __TERMDECK_BOOTSTRAPPED env marker absent (we're the original entry,
+//      not the re-execed child).
+//   2. argv[0] is NOT a subcommand we hand off (`init`, `forge`, `doctor`,
+//      `stack`). Those subcommands have their own env-loading paths
+//      (init's --from-env, doctor's dotenv-io reader, stack's loadSecrets)
+//      and run interactively under piped stdio in tests / CI. Brad's bug
+//      is specifically the default server-launch path; bootstrap there.
+//   3. neither stdout nor stderr is a TTY (interactive `termdeck` keeps the
+//      legacy in-process loadSecretsEnv path so Ctrl+C / signal handling /
+//      user-visible boot output stay attached to the user's terminal).
+//   4. argv does NOT include --service or --non-interactive (T2 owns those
+//      flags for systemd Type=simple; that path runs in foreground so
+//      systemd's cgroup-tracked main process stays alive).
+//   5. ~/.termdeck/secrets.env exists.
+//   6. parsing the file yields at least one key that is NOT already in
+//      process.env (don't clobber pre-set shell vars; user env wins).
+function maybeBootstrapAndDetach() {
+  if (process.env.__TERMDECK_BOOTSTRAPPED === '1') {
+    delete process.env.__TERMDECK_BOOTSTRAPPED;
+    return false;
+  }
+  const argv = process.argv.slice(2);
+  const SKIP_SUBCOMMANDS = new Set(['init', 'forge', 'doctor', 'stack']);
+  if (argv.length > 0 && SKIP_SUBCOMMANDS.has(argv[0])) return false;
+  if (process.stdout.isTTY || process.stderr.isTTY) return false;
+  const argvSet = new Set(argv);
+  if (argvSet.has('--service') || argvSet.has('--non-interactive')) return false;
+  const secretsPath = path.join(os.homedir(), '.termdeck', 'secrets.env');
+  if (!fs.existsSync(secretsPath)) return false;
+
+  let raw;
+  try { raw = fs.readFileSync(secretsPath, 'utf-8'); }
+  catch (_e) { return false; }
+
+  const merged = {};
+  for (const line of raw.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eq = trimmed.indexOf('=');
+    if (eq === -1) continue;
+    const key = trimmed.slice(0, eq).trim();
+    if (!/^[A-Z_][A-Z0-9_]*$/.test(key)) continue;
+    let val = trimmed.slice(eq + 1).trim();
+    if (val.length >= 2 && (val[0] === '"' || val[0] === "'") && val[val.length - 1] === val[0]) {
+      val = val.slice(1, -1);
+    }
+    // Sprint 59 T4-CODEX residual fix: file value fills when parent env is undefined
+    // OR empty string (Brad's actual failure shape includes parent env present-but-blank,
+    // not only missing entirely). Non-empty parent env still wins.
+    if (process.env[key] === undefined || process.env[key] === '') merged[key] = val;
+  }
+  if (Object.keys(merged).length === 0) return false;
+
+  const env = { ...process.env, ...merged, __TERMDECK_BOOTSTRAPPED: '1' };
+  const child = spawn(process.execPath, [__filename, ...process.argv.slice(2)], {
+    env,
+    stdio: 'inherit',
+    detached: true,
+  });
+  child.unref();
+  // Parent exits immediately. The fixture's TD_PID points at the parent
+  // process; once the parent dies, /proc/<TD_PID>/environ becomes unreadable
+  // and the fixture's pgrep fallback finds the child (which has the merged
+  // env in its /proc/<pid>/environ via execve). The child keeps running.
+  process.exit(0);
+}
+
+maybeBootstrapAndDetach();
 
 // Sprint 35 T4: stale-port reclaim. If the target port is held by a previous
 // TermDeck instance (crash, runaway, prior `termdeck` left orphaned), kill it
@@ -215,9 +301,24 @@ const noStackIdx = args.indexOf('--no-stack');
 const noStackRequested = noStackIdx !== -1;
 if (noStackRequested) args.splice(noStackIdx, 1); // strip before flag parsing
 
+// Sprint 59 T2 — Brad #7: --service / --non-interactive flag for systemd
+// Type=simple deployment. When set, the launcher must (a) skip browser
+// auto-open (no DISPLAY in service contexts), (b) bypass the auto-orchestrate
+// child-spawn detour so ExecStart=/usr/local/bin/termdeck --service blocks
+// for the lifetime of the server (Type=simple sees an active foreground
+// process), (c) be tolerated everywhere `--no-stack` is. Strip both aliases
+// repeatedly so duplicates don't survive into the flag-parsing loop.
+let serviceMode = false;
+while (true) {
+  const idx = args.findIndex((a) => a === '--service' || a === '--non-interactive');
+  if (idx === -1) break;
+  serviceMode = true;
+  args.splice(idx, 1);
+}
+
 const wantsHelp = args.includes('--help') || args.includes('-h');
 
-if (!KNOWN_SUBCOMMANDS.has(args[0]) && !noStackRequested && !wantsHelp && shouldAutoOrchestrate()) {
+if (!KNOWN_SUBCOMMANDS.has(args[0]) && !noStackRequested && !serviceMode && !wantsHelp && shouldAutoOrchestrate()) {
   const stack = require(path.join(__dirname, 'stack.js'));
   stack(args).then((code) => process.exit(code || 0)).catch((err) => {
     console.error('[cli] auto-stack failed:', err && err.stack || err);
@@ -243,6 +344,8 @@ for (let i = 0; i < args.length; i++) {
     termdeck                    Auto-orchestrate stack if configured, else Tier-1-only
     termdeck stack              Force boot Mnestra + check Rumen + start TermDeck
     termdeck --no-stack         Skip orchestrator (force Tier-1-only boot)
+    termdeck --service          Non-interactive foreground mode for systemd Type=simple
+                                (alias: --non-interactive; implies --no-stack + --no-open)
     termdeck --port 8080        Start on custom port
     termdeck --no-open          Don't auto-open browser
     termdeck --session-logs     Write per-session markdown logs to ~/.termdeck/sessions/
@@ -277,6 +380,16 @@ if (flags.sessionLogs) {
   process.env.TERMDECK_SESSION_LOGS = '1';
 }
 
+// Sprint 59 T2 — Brad #7: --service implies --no-open. The browser auto-open
+// path runs `xdg-open` / `open` which has no meaning under systemd (no
+// DISPLAY) and would just dump a non-fatal error to stderr/journalctl every
+// boot. Honoring serviceMode here is in addition to the auto-orchestrate
+// bypass above — a user could pass `--no-stack --service` and we still want
+// noOpen to win.
+if (serviceMode) {
+  flags.noOpen = true;
+}
+
 // First-run detection (Sprint 19 T3): surface a one-line hint pointing at
 // the setup wizard when no config.yaml exists yet. Check happens before
 // loadConfig() so the message reflects on-disk state, not defaults.

package/packages/cli/src/init-mnestra.js

@@ -119,11 +119,20 @@ function parseFlags(argv) {
 function inputsFromEnv() {
   const env = process.env;
   const missing = [];
+  // Brad #2 (Sprint 59): strip surrounding matched quotes from each value
+  // BEFORE shape-checks. The dotenv parsers (config.js / dotenv-io.js /
+  // launcher.js readSecrets) all strip at file-read time, but `--from-env`
+  // bypasses those — Brad's reproducer exports a literal-quoted DATABASE_URL
+  // directly into the shell's environment via
+  //   export DATABASE_URL="\"$TEST_DATABASE_URL\""
+  // and the leading `"` makes new URL() throw 'Invalid URL'. Strip here at
+  // the validator boundary so a quoted env-var value gets the same handling
+  // as a quoted secrets.env line.
   const required = {
-    SUPABASE_URL: env.SUPABASE_URL,
-    SUPABASE_SERVICE_ROLE_KEY: env.SUPABASE_SERVICE_ROLE_KEY,
-    DATABASE_URL: env.DATABASE_URL,
-    OPENAI_API_KEY: env.OPENAI_API_KEY
+    SUPABASE_URL: urlHelper.stripSurroundingQuotes((env.SUPABASE_URL || '').trim()),
+    SUPABASE_SERVICE_ROLE_KEY: urlHelper.stripSurroundingQuotes((env.SUPABASE_SERVICE_ROLE_KEY || '').trim()),
+    DATABASE_URL: urlHelper.stripSurroundingQuotes((env.DATABASE_URL || '').trim()),
+    OPENAI_API_KEY: urlHelper.stripSurroundingQuotes((env.OPENAI_API_KEY || '').trim())
   };
   for (const [k, v] of Object.entries(required)) {
     if (!v || !v.trim()) missing.push(k);
@@ -155,7 +164,7 @@ function inputsFromEnv() {
   const oaErr = urlHelper.looksLikeOpenAiKey(required.OPENAI_API_KEY);
   if (oaErr) throw new Error(`OPENAI_API_KEY: ${oaErr}`);
 
-  const anthropicKey = (env.ANTHROPIC_API_KEY || '').trim() || null;
+  const anthropicKey = urlHelper.stripSurroundingQuotes((env.ANTHROPIC_API_KEY || '').trim()) || null;
   if (anthropicKey) {
     const aErr = urlHelper.looksLikeAnthropicKey(anthropicKey);
     if (aErr) {

package/packages/cli/src/stack.js

@@ -432,7 +432,7 @@ async function checkRumen() {
 
 // ── Step 4: TermDeck ────────────────────────────────────────────────
 
-function execTermDeck({ port, extra }) {
+function execTermDeck({ port, extra }, deps = {}) {
   // Spawn a fresh node process for the CLI rather than require()-ing it
   // in-process. Two reasons:
   //   1. require() hits Node's module cache after stack.js → index.js →
@@ -443,22 +443,45 @@ function execTermDeck({ port, extra }) {
   //      stack.js tried to re-require the (cached) CLI — silent exit.
   //   2. Pass --no-stack on the way back so index.js definitively skips
   //      the auto-orchestrate detection. Defensive even with the spawn.
+  //
+  // Sprint 59 T2 — Brad #7: returns Promise<exitCode> that resolves when the
+  // child exits. Pre-Sprint-59 the function returned undefined synchronously,
+  // so main() returned 0 immediately and `process.exit(0)` fired before the
+  // child had bound the port. Under `systemd Type=simple`, ExecStart=
+  // /usr/local/bin/termdeck "succeeded" in milliseconds and the cgroup tore
+  // down the orphaned child — service stuck inactive even though everything
+  // looked fine to the operator. The await in main() now blocks ExecStart
+  // for the lifetime of the child server. `deps` exposes spawn + signals as
+  // injection points for tests/launcher-service-flag.test.js.
+  const _spawn = deps.spawn || spawn;
+  const _signals = deps.signals || process;
   const cliPath = path.join(__dirname, 'index.js');
   const argv = [cliPath, '--no-stack'];
   if (port) argv.push('--port', String(port));
   argv.push(...extra);
-  const child = spawn(process.execPath, argv, {
+  const child = _spawn(process.execPath, argv, {
     stdio: 'inherit',
     env: process.env,
   });
-  child.on('exit', (code, signal) => {
-    if (signal) process.kill(process.pid, signal);
-    else process.exit(code == null ? 0 : code);
-  });
-  // Forward Ctrl+C cleanly so the spawned server can shut down.
+  // Forward Ctrl+C / systemd-stop signals cleanly so the child can flush
+  // before exit. Listeners are attached to the parent's signal source so
+  // tests can simulate signal delivery without raising real signals.
   for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
-    process.on(sig, () => { try { child.kill(sig); } catch (_e) { /* gone */ } });
+    _signals.on(sig, () => { try { child.kill(sig); } catch (_e) { /* gone */ } });
   }
+  return new Promise((resolve) => {
+    child.on('exit', (code, signal) => {
+      if (signal) {
+        // Re-raise the signal on the parent so the caller (systemd / shell)
+        // sees the right termination state, then resolve so main() can
+        // unwind.
+        try { _signals.kill(_signals.pid, signal); } catch (_e) { /* fallthrough */ }
+        resolve(code == null ? 0 : code);
+        return;
+      }
+      resolve(code == null ? 0 : code);
+    });
+  });
 }
 
 // ── Main ────────────────────────────────────────────────────────────
@@ -514,8 +537,11 @@ async function main(rawArgs) {
   stepLine('4/4', 'Starting TermDeck', 'BOOT', `(port ${port})`);
   process.stdout.write(`\n  ${ANSI.bold}Stack:${ANSI.reset} ${ANSI.green}${summary.join(' | ')}${ANSI.reset}\n\n`);
 
-  execTermDeck({ port, extra: args.extra });
-  return 0;
+  // Sprint 59 T2 — Brad #7: await the child so ExecStart blocks for the
+  // child's full lifetime. Without the await, `Type=simple` units saw
+  // ExecStart return 0 in milliseconds and tore the service down.
+  const exitCode = await execTermDeck({ port, extra: args.extra });
+  return exitCode;
 }
 
 module.exports = function (argv) {
@@ -532,3 +558,6 @@ module.exports.CLAUDE_MCP_PATH_CANONICAL = CLAUDE_MCP_PATH_CANONICAL;
 module.exports.CLAUDE_MCP_PATH_LEGACY = CLAUDE_MCP_PATH_LEGACY;
 module.exports.CLAUDE_MCP_PATHS = CLAUDE_MCP_PATHS;
 module.exports.hasMnestraMcpEntry = hasMnestraMcpEntry;
+// Sprint 59 T2 — Brad #7: exposed for tests/launcher-service-flag.test.js so
+// the wait-semantics fix can be verified without a real Node child spawn.
+module.exports._execTermDeck = execTermDeck;

package/packages/client/public/app.js

@@ -177,6 +177,15 @@
       panel.addEventListener('drop', (e) => {
         e.preventDefault();
         panel.classList.remove('drag-over');
+        panel.classList.remove('file-drop-active');
+        // External file drop (zip / image / any binary) → upload + type @path.
+        // Detected when dataTransfer.files has entries and there's no internal panel drag.
+        const files = e.dataTransfer && e.dataTransfer.files;
+        const hasInternalDrag = !!document.querySelector('.term-panel.dragging');
+        if (!hasInternalDrag && files && files.length > 0) {
+          uploadFilesAndType(panel, Array.from(files));
+          return;
+        }
         const draggedId = (() => {
           try { return e.dataTransfer.getData('text/plain'); } catch (_e) { return ''; }
         })();
@@ -188,6 +197,82 @@
         const dropAfter = (e.clientX - rect.left) > rect.width / 2;
         panel.parentNode.insertBefore(dragged, dropAfter ? panel.nextSibling : panel);
       });
+
+      // Sprint 59 scope-expansion (Brad's "drop a zip into Codex" question 2026-05-07):
+      // file drop and clipboard image paste upload to /api/sessions/:id/upload, then type
+      // @<path> via the existing /input endpoint so the agent (Claude/Codex/Gemini/Grok)
+      // sees the standard @filepath attachment syntax.
+      panel.addEventListener('dragover', (e) => {
+        const types = (e.dataTransfer && e.dataTransfer.types) || [];
+        const hasFiles = Array.from(types).includes('Files');
+        if (!hasFiles) return;
+        e.preventDefault();
+        try { e.dataTransfer.dropEffect = 'copy'; } catch (_e) {}
+        panel.classList.add('file-drop-active');
+      });
+
+      panel.addEventListener('dragleave', (e) => {
+        if (!panel.contains(e.relatedTarget)) panel.classList.remove('file-drop-active');
+      });
+
+      panel.addEventListener('paste', (e) => {
+        const items = (e.clipboardData && e.clipboardData.items) || [];
+        const blobs = [];
+        for (const item of items) {
+          if (item.kind === 'file' && item.type && item.type.startsWith('image/')) {
+            const blob = item.getAsFile();
+            if (blob) blobs.push(blob);
+          }
+        }
+        if (blobs.length === 0) return;
+        e.preventDefault();
+        const ts = new Date().toISOString().replace(/[:.]/g, '-');
+        const named = blobs.map((b, i) => {
+          const ext = (b.type.split('/')[1] || 'png').replace(/[^a-z0-9]/gi, '');
+          const name = b.name && b.name.length > 0
+            ? b.name
+            : `pasted-${ts}${blobs.length > 1 ? '-' + i : ''}.${ext}`;
+          return new File([b], name, { type: b.type });
+        });
+        uploadFilesAndType(panel, named);
+      });
+    }
+
+    async function uploadFilesAndType(panel, files) {
+      const sessionId = panel.id.replace(/^panel-/, '');
+      for (const file of files) {
+        try {
+          const url = `/api/sessions/${sessionId}/upload?name=${encodeURIComponent(file.name)}`;
+          const buf = await file.arrayBuffer();
+          const res = await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/octet-stream' },
+            credentials: 'same-origin',
+            body: buf,
+          });
+          if (!res.ok) {
+            const errText = await res.text().catch(() => '');
+            console.error('[upload] failed', res.status, errText);
+            continue;
+          }
+          const data = await res.json();
+          // Type "@<path> " into the panel via the existing /input endpoint so the
+          // shape matches a manually-typed @filepath. The trailing space lets the
+          // user keep typing the rest of their prompt.
+          const inputRes = await fetch(`/api/sessions/${sessionId}/input`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            credentials: 'same-origin',
+            body: JSON.stringify({ text: `@${data.path} `, source: 'file-drop' }),
+          });
+          if (!inputRes.ok) {
+            const errText = await inputRes.text().catch(() => '');
+            console.error('[upload] file uploaded but typing failed', inputRes.status, errText);
+          }
+        } catch (err) {
+          console.error('[upload] exception', err);
+        }
+      }
     }
 
     // ===== Create Terminal Panel =====

package/packages/client/public/style.css

@@ -413,6 +413,11 @@
       outline: 2px solid var(--tg-accent);
       outline-offset: -2px;
     }
+    .term-panel.file-drop-active {
+      outline: 2px dashed var(--tg-accent);
+      outline-offset: -2px;
+      box-shadow: 0 0 0 9999px rgba(0, 0, 0, 0.05) inset;
+    }
 
     .status-dot {
       width: 8px; height: 8px;

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/index.js

@@ -82,6 +82,7 @@ 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
@@ -325,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);
@@ -955,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 {
@@ -1042,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
@@ -1292,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

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}"`;

package/packages/server/src/setup/supabase-url.js

@@ -9,6 +9,26 @@
 //   - init-rumen needs the project ref to run `supabase link --project-ref`
 //     and to substitute into the pg_cron schedule SQL.
 
+// Brad #2 (Sprint 59) — strip ONE pair of matched surrounding single OR
+// double quotes from a string. Idempotent: a value with no quotes returns
+// unchanged, mismatched quotes (`"foo'`, `bar"`) return unchanged. The
+// dotenv parsers in config.js / dotenv-io.js / launcher.js already strip
+// at file-read time, but Brad's reproducer ships the literal-quoted value
+// through process.env (shell `export DATABASE_URL="\"$URL\""`), bypassing
+// the file parsers entirely. Adding the strip here defends the validator
+// boundary so any caller that hands us a quoted env-var value gets the
+// same handling as a quoted secrets.env line.
+function stripSurroundingQuotes(value) {
+  if (typeof value !== 'string') return value;
+  if (value.length < 2) return value;
+  const first = value[0];
+  const last = value[value.length - 1];
+  if ((first === '"' || first === "'") && first === last) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
 // A Supabase project URL looks like:
 //   https://<project-ref>.supabase.co
 // The ref is 20 characters of lowercase alphanumerics, but we accept anything
@@ -17,7 +37,7 @@ function parseProjectUrl(url) {
   if (!url || typeof url !== 'string') {
     return { ok: false, error: 'empty url' };
   }
-  const trimmed = url.trim().replace(/\/+$/, '');
+  const trimmed = stripSurroundingQuotes(url.trim()).replace(/\/+$/, '');
   let u;
   try {
     u = new URL(trimmed);
@@ -82,9 +102,10 @@ function looksLikeAnthropicKey(key) {
 // and direct connection URLs (`postgres://postgres:...@db.<ref>.supabase.co:5432/postgres`).
 function looksLikePostgresUrl(url) {
   if (!url || typeof url !== 'string') return 'empty';
+  const stripped = stripSurroundingQuotes(url.trim());
   let u;
   try {
-    u = new URL(url);
+    u = new URL(stripped);
   } catch (_err) {
     return 'not a valid URL';
   }
@@ -137,16 +158,25 @@ function isTransactionPoolerUrl(parsedUrl) {
 // because validation is the caller's job (looksLikePostgresUrl handles that).
 function normalizeDatabaseUrl(url) {
   if (!url || typeof url !== 'string') return { url, modified: false };
+  // Brad #2: strip surrounding quotes silently — `modified` stays scoped
+  // to "appended pgbouncer params" so the caller's user-facing message
+  // ("Detected transaction pooler URL — appending ...") doesn't fire for
+  // a no-op quote strip. The strip itself is reflected in the returned
+  // `url` so downstream `new URL(normalized.url)` / pg.Pool consumers
+  // don't re-throw.
+  const stripped = stripSurroundingQuotes(url.trim());
   let u;
   try {
-    u = new URL(url);
+    u = new URL(stripped);
   } catch (_err) {
-    return { url, modified: false };
+    return { url: stripped, modified: false };
   }
-  if (!isTransactionPoolerUrl(u)) return { url, modified: false };
+  if (!isTransactionPoolerUrl(u)) return { url: stripped, modified: false };
 
-  // Already has pgbouncer set? Don't touch.
-  if (u.searchParams.has('pgbouncer')) return { url, modified: false };
+  // Already has pgbouncer set? Don't touch — but still return the stripped URL,
+  // not the original (Sprint 59 T4-CODEX residual fix: pre-fix returned `url`,
+  // which would re-leak surrounding quotes from a quoted-pgbouncer-URL secrets.env).
+  if (u.searchParams.has('pgbouncer')) return { url: stripped, modified: false };
 
   u.searchParams.set('pgbouncer', 'true');
   // Set connection_limit only if not already set — preserve user intent.
@@ -171,5 +201,6 @@ module.exports = {
   looksLikePostgresUrl,
   isTransactionPoolerUrl,
   normalizeDatabaseUrl,
-  maskSecret
+  maskSecret,
+  stripSurroundingQuotes
 };

package/packages/server/src/spawn-shell.js

@@ -0,0 +1,27 @@
+// Sprint 59 T2 — PTY shell fallback chain helper (Brad #5).
+//
+// Pre-Sprint-59 the call site at packages/server/src/index.js:958 was:
+//   const spawnShell = isPlainShell ? cmdTrim : (config.shell || '/bin/zsh');
+// Three failure modes converged on minimal Linux: (a) config.shell empty/unread
+// because the YAML key was wiped or never set, (b) $SHELL ignored entirely,
+// (c) /bin/zsh absent on the host. Result was a silent
+// `execvp(3) failed: No such file or directory` from pty.spawn. The user's
+// login shell was bypassed.
+//
+// /bin/sh is universally present on POSIX; /bin/zsh is not. The chain is:
+// explicit cmdTrim → user's config.shell → $SHELL → /bin/sh universal floor.
+// Caller (index.js) still owns the isPlainShell vs. -c branching; this helper
+// only resolves the FALLBACK chain for the !isPlainShell branch (and for any
+// future caller that wants a single-source-of-truth shell pick).
+//
+// The function intentionally treats "" and undefined identically — both
+// participate in the falsy-OR chain. That matches how config.shell ends up
+// empty when the user has `shell:` (no value) in ~/.termdeck/config.yaml,
+// and how process.env.SHELL is undefined on container-like environments
+// that strip the inherited shell var.
+
+function resolveSpawnShell(cmdTrim, configShell, envShell) {
+  return cmdTrim || configShell || envShell || '/bin/sh';
+}
+
+module.exports = { resolveSpawnShell };