@jhizzard/termdeck 0.13.0 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhizzard/termdeck",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "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/client/public/app.js

@@ -10,6 +10,14 @@
       layout: '2x1',
       themes: {},
       config: {},
+      // Sprint 45 T4: serializable projection of the multi-agent registry
+      // (server's AGENT_ADAPTERS). Populated from GET /api/agent-adapters
+      // during init(). The launcher's command-shorthand parser reads this
+      // to detect which adapter (if any) a typed command should map to.
+      // Fallback list is the pre-Sprint-45 default so the launcher still
+      // works if the endpoint 404s on an older server during a rolling
+      // upgrade — Claude only, anchored binary match.
+      agentAdapters: [{ name: 'claude', sessionType: 'claude-code', binary: 'claude', costBand: 'pay-per-token' }],
       focusedId: null
     };
 
@@ -27,6 +35,17 @@
       state.config = await api('GET', '/api/config');
       updateRagIndicator();
 
+      // Sprint 45 T4: fetch the multi-agent adapter registry projection.
+      // Drives the launcher's command-shorthand → sessionType resolution
+      // below in launchTerminal(). Falls back to the bootstrap default
+      // (Claude only) if the endpoint isn't available on this server.
+      try {
+        const adapters = await api('GET', '/api/agent-adapters');
+        if (Array.isArray(adapters) && adapters.length > 0) {
+          state.agentAdapters = adapters;
+        }
+      } catch (_) { /* keep bootstrap fallback */ }
+
       // Populate project dropdown
       const sel = document.getElementById('promptProject');
       for (const name of Object.keys(state.config.projects || {})) {
@@ -2460,31 +2479,20 @@
         return;
       }
 
-      // Parse shorthand commands
-      let resolvedCommand = command;
-      let resolvedType = 'shell';
-      let resolvedCwd = undefined;
-
-      let resolvedProject = project || undefined;
-
-      if (/^claude\b/i.test(command) || /^cc\b/i.test(command)) {
-        resolvedType = 'claude-code';
-        const argMatch = command.match(/(?:claude|cc)\s+(?:code\s+)?(.+)/i);
-        if (argMatch) {
-          const arg = argMatch[1].trim();
-          // Check if arg is a known project name
-          if (state.config.projects && state.config.projects[arg]) {
-            resolvedProject = arg;
-          } else {
-            resolvedCwd = arg;
-          }
-        }
-        resolvedCommand = 'claude';
-      } else if (/^gemini\b/i.test(command)) {
-        resolvedType = 'gemini';
-      } else if (/^python3?\b.*(?:runserver|uvicorn|flask|gunicorn)/i.test(command)) {
-        resolvedType = 'python-server';
-      }
+      // Sprint 45 T4 + Sprint 46 T4: resolver extracted to
+      // packages/client/public/launcher-resolver.js so the same routing
+      // logic runs in the browser AND under `node --test` (see
+      // tests/launcher-resolver.test.js for the contract pin). Sprint 46
+      // T4 also extended the python-server preemptive regex to recognize
+      // `http.server` so the python topbar quick-launch button is typed
+      // correctly from the first frame.
+      const { resolvedCommand, resolvedType, resolvedCwd, resolvedProject } =
+        LauncherResolver.resolve(
+          command,
+          project,
+          state.agentAdapters,
+          state.config.projects
+        );
 
       const session = await api('POST', '/api/sessions', {
         command: resolvedCommand,
@@ -4449,18 +4457,28 @@
       for (const sess of data.sessions) {
         const id = sess.sessionId || sess.session_id || 'unknown';
         const shortId = id.slice(0, 8);
-        const type = sess.type || 'shell';
+        // Server (/api/transcripts/recent) returns { sessions: [{ session_id, chunks: [...] }] }
+        // with chunks already grouped per session in DESC created_at order. Type/project
+        // metadata isn't on the transcripts table — fall back to optional fields if any
+        // future server enrichment ships them.
+        const chunks = Array.isArray(sess.chunks) ? sess.chunks : [];
+        const type = sess.type || (chunks.length ? 'session' : 'shell');
         const project = sess.project || '';
-        const lines = sess.lines || sess.preview || [];
-        const lineCount = sess.totalLines || lines.length;
+        const totalChunks = sess.totalLines || chunks.length;
+        // Build preview from the most-recent chunks. Server returns DESC order, so
+        // the first 6 entries are the newest — reverse for natural top-down reading.
+        const previewChunks = chunks.slice(0, 6).reverse();
+        const previewText = sess.preview
+          ? (Array.isArray(sess.preview) ? sess.preview.join('\n') : String(sess.preview))
+          : previewChunks.map(c => (c && typeof c.content === 'string') ? c.content : '').join('');
         html += `<div class="transcript-session" data-session-id="${escapeHtml(id)}">
           <div class="ts-header">
             <span class="ts-id">${escapeHtml(shortId)}</span>
             <span class="ts-type">${escapeHtml(type)}</span>
             ${project ? `<span class="ts-project">${escapeHtml(project)}</span>` : ''}
-            <span class="ts-lines">${lineCount} lines</span>
+            <span class="ts-lines">${totalChunks} chunks</span>
           </div>
-          <pre class="ts-preview">${escapeHtml(lines.slice(-6).join('\n'))}</pre>
+          <pre class="ts-preview">${escapeHtml(previewText)}</pre>
         </div>`;
       }
       body.innerHTML = html;
@@ -4500,7 +4518,11 @@
         const id = result.sessionId || result.session_id || 'unknown';
         const shortId = id.slice(0, 8);
         const line = result.line || result.content || '';
-        const ts = result.timestamp ? new Date(result.timestamp).toLocaleTimeString() : '';
+        // Server (/api/transcripts/search) sends `created_at`; legacy `timestamp` kept
+        // as a fallback in case a future enrichment swaps the field name.
+        const tsSource = result.timestamp || result.created_at || '';
+        const tsDate = tsSource ? new Date(tsSource) : null;
+        const ts = (tsDate && !isNaN(tsDate.getTime())) ? tsDate.toLocaleTimeString() : '';
         html += `<div class="transcript-result" data-session-id="${escapeHtml(id)}">
           <div class="tr-meta">
             <span class="tr-session">${escapeHtml(shortId)}</span>

package/packages/client/public/graph.js

@@ -552,7 +552,7 @@
       .attr('stroke-width', 1.2)
       .attr('filter', 'url(#nodeGlow)')
       .style('cursor', 'pointer')
-      .on('mouseenter', (event, d) => onNodeHover(d.id))
+      .on('mouseenter', (event, d) => { onNodeHover(d.id); showNodeTooltip(event, d); })
       .on('mouseleave', () => onNodeHover(null))
       .on('click', (event, d) => onNodeClick(d))
       .call(window.d3.drag()
@@ -738,6 +738,28 @@
     tip.hidden = false;
     moveTooltip(event);
   }
+
+  // Sprint 46 T1 — node hover tooltip. Shows project (color-coded) + a short
+  // content snippet so the user can scan the graph without having to open the
+  // drawer for every node. Click still opens the full detail drawer.
+  function showNodeTooltip(event, node) {
+    const tip = $('graphTooltip');
+    if (!tip || !node) return;
+    const proj = node.project || 'global';
+    const text = escapeHtml(truncate(node.label || node.snippet || '(no content)', 80));
+    const meta = node.source_type ? `<span style="opacity:0.7">${escapeHtml(node.source_type)}</span>` : '';
+    tip.innerHTML = `<strong style="color:${hashHue(proj)}">${escapeHtml(proj)}</strong> ${meta} · ${text}`;
+    tip.hidden = false;
+    moveTooltip(event);
+  }
+
+  function escapeHtml(s) {
+    return String(s == null ? '' : s)
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;');
+  }
   function moveTooltip(event) {
     const tip = $('graphTooltip');
     if (tip.hidden) return;

package/packages/client/public/index.html

@@ -372,6 +372,7 @@
   <script src="https://cdn.jsdelivr.net/npm/@xterm/xterm@5.5.0/lib/xterm.min.js"></script>
   <script src="https://cdn.jsdelivr.net/npm/@xterm/addon-fit@0.10.0/lib/addon-fit.min.js"></script>
   <script src="https://cdn.jsdelivr.net/npm/@xterm/addon-web-links@0.11.0/lib/addon-web-links.min.js"></script>
+  <script src="launcher-resolver.js" defer></script>
   <script src="app.js" defer></script>
 </body>
 </html>

package/packages/client/public/launcher-resolver.js

@@ -0,0 +1,68 @@
+// TermDeck launcher resolver — extracted Sprint 46 T4
+//
+// Pure function: given (command, project, agentAdapters, projects),
+// returns the resolved spawn parameters the launcher POSTs to /api/sessions.
+// Lives in its own file so the same code runs in the browser (via
+// <script src="launcher-resolver.js">) AND under `node --test` (via
+// `require('.../launcher-resolver')`). Sprint 46 T4 added this extraction
+// to close a zero-coverage gap on the client-side routing logic — see
+// tests/launcher-resolver.test.js for the contract pin.
+//
+// Sprint 45 T4 refactor lives here too: registry-driven shorthand
+// resolution. Pre-Sprint-45 had hardcoded claude/cc/gemini/python branches;
+// now the type detection consults `agentAdapters` (loaded from
+// /api/agent-adapters at init), and only the Claude `cc` alias and the
+// python-server detection (no adapter exists) stay as special-cases.
+// Adapter matching uses an anchored prefix on the adapter's binary name
+// (`^binary\b`, case-insensitive) which fits all four Sprint-45 adapters
+// (claude / codex / gemini / grok) since each binary is uniquely named.
+
+(function (root, factory) {
+  if (typeof module === 'object' && module.exports) {
+    module.exports = factory();
+  } else {
+    root.LauncherResolver = factory();
+  }
+})(typeof self !== 'undefined' ? self : this, function () {
+  function resolve(command, project, agentAdapters, projects) {
+    let resolvedCommand = command;
+    let resolvedType = 'shell';
+    let resolvedCwd;
+    let resolvedProject = project || undefined;
+
+    let canonical = command;
+    if (/^cc\b/i.test(canonical)) {
+      canonical = canonical.replace(/^cc\b/i, 'claude');
+    }
+
+    const adapter = (agentAdapters || []).find((a) =>
+      a && a.binary && new RegExp(`^${a.binary}\\b`, 'i').test(canonical)
+    );
+
+    if (adapter) {
+      resolvedType = adapter.sessionType;
+      if (adapter.name === 'claude') {
+        const argMatch = canonical.match(/^claude\s+(?:code\s+)?(.+)/i);
+        if (argMatch) {
+          const arg = argMatch[1].trim();
+          if (projects && projects[arg]) {
+            resolvedProject = arg;
+          } else {
+            resolvedCwd = arg;
+          }
+        }
+        resolvedCommand = adapter.binary;
+      }
+    } else if (/^python3?\b.*(?:runserver|uvicorn|flask|gunicorn|http\.server)/i.test(canonical)) {
+      // Sprint 46 T4: extended `http\.server` so the python topbar
+      // quick-launch button is preemptively typed correctly. Without
+      // this, the badge flickers through `shell` for ~1s before
+      // session.js's runtime detection (`/Serving HTTP on/`) catches up.
+      resolvedType = 'python-server';
+    }
+
+    return { resolvedCommand, resolvedType, resolvedCwd, resolvedProject };
+  }
+
+  return { resolve };
+});

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

@@ -0,0 +1,199 @@
+// Codex CLI adapter — Sprint 45 T1
+//
+// Second adapter in the AGENT_ADAPTERS registry (see ./index.js). Sprint 44 T3
+// shipped the Claude adapter as the reference implementation; this file is the
+// recipe in `docs/AGENT-RUNTIMES.md` § 6 turned into running code for Codex
+// CLI (`/usr/local/bin/codex`, v0.125.0 verified 2026-05-01).
+//
+// This is *Codex-as-its-own-panel* — distinct from the existing
+// `codex@openai-codex` Claude Code plugin which is a delegate-from-Claude
+// pathway. Sprint 46 wires per-lane agent assignment; this lane just makes
+// `codex` work end-to-end inside a TermDeck panel: type detection, status
+// badge, transcript ingestion into Mnestra.
+//
+// Contract — see ./claude.js header for the full annotated shape.
+//
+// Pattern provenance:
+// • Codex CLI ships a Ratatui (Rust) TUI. The TUI redraws on each turn so the
+//   raw PTY stream is heavy in ANSI escapes; session.js stripAnsi() runs
+//   *before* these regexes, so the patterns assume cleaned text.
+// • The headless `codex exec` mode emits a documented sequence: a `--------`
+//   header block, `user` / `codex` speaker lines on their own row, function
+//   `exec_command` blocks, and a `tokens used` footer. The TUI mirrors these
+//   speaker shapes inside its rendered chat surface.
+// • Reasoning markers come from the JSONL `response_item.payload.type=reasoning`
+//   events that the TUI renders as a "Thinking…" status line.
+// • Apply-patch / exec markers come from `response_item.payload.type=function_call`
+//   entries with names like `apply_patch` and `exec_command`.
+//
+// Patterns are conservative defaults — Sprint 45 T4 / Sprint 46 will tune
+// against captured real-world TUI output. Snapshot tests in
+// tests/agent-adapter-codex.test.js pin the current behavior so any tuning
+// is an explicit, reviewed change.
+
+// ──────────────────────────────────────────────────────────────────────────
+// Patterns
+// ──────────────────────────────────────────────────────────────────────────
+
+// Codex prompt detection. Three shapes accepted:
+//   1. `codex>` literal (mirrors gemini's `gemini>` and the codex CLI's REPL
+//      prompt convention — used by `codex resume` interactive sessions).
+//   2. A bare `codex` line (the speaker label the TUI prints above an
+//      assistant turn AND that headless `codex exec` prints before the reply).
+//   3. The `--------` divider that wraps the codex header block in headless
+//      mode and bookends turns in the TUI.
+const PROMPT = /^(?:codex>\s|codex\s*$|--------\s*$)/m;
+
+// Reasoning indicator. Codex's TUI status line shows "Thinking" while the
+// model reasons; "Reasoning" appears in some headless transcripts; "Working"
+// is what `codex exec` prints for tool-loop progress.
+const THINKING = /\b(Thinking|Reasoning|Working)\b/;
+
+// File edit / patch markers. Codex applies diffs through the `apply_patch`
+// tool which the TUI renders as `Apply patch <file>` headers. Plain
+// Edit/Create/Update/Delete shapes are also kept so simple file ops register
+// (mirrors the Claude adapter's editing markers for cross-adapter parity).
+const EDITING = /^(Apply patch|Edit|Create|Update|Delete|Modified)\s/m;
+const EDITING_DETAIL = /^(Apply patch|Edit|Create|Update|Delete|Modified)\s+(.+)$/m;
+
+// Tool / shell-exec markers. Codex's TUI prefixes shell commands with `$`
+// (chat-shell convention), arrow `→` for read tool calls, and bare keywords
+// `exec` / `Running` / `Calling` for the phase between dispatch and result.
+// `exec_command` is Codex's function-call name (verified in rollout JSONL
+// 2026-05-01); the alternation handles both bare `exec` and the underscored
+// `exec_command` shape (the underscore is a word character so `exec\b`
+// alone wouldn't match `exec_command`).
+const TOOL = /^(?:\$\s|→\s|exec(?:_command\b|\b)|Running\b|Calling\b)/m;
+
+// Idle / waiting-for-input. The TUI returns to the bare `codex` speaker
+// label when it's done reasoning and waiting on the user.
+const IDLE = /^codex\s*$/m;
+
+// Error patterns — line-anchored to avoid mid-line "error" mentions in tool
+// output (grep results, test logs, file dumps) flagging false positives.
+// Same shape as Claude with codex-specific OpenAI-API failure modes added
+// (rate-limit 429, model-not-found, invalid_api_key) which surface as visible
+// strings in Codex's error reporting and would otherwise slip through.
+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|429\s+Too Many Requests|rate.?limit|invalid_api_key|model_not_found|insufficient_quota)\b|npm ERR!)/m;
+
+// ──────────────────────────────────────────────────────────────────────────
+// statusFor — Codex panel status. Order mirrors Claude's cascade:
+// thinking → editing → tool → idle. First match wins.
+// ──────────────────────────────────────────────────────────────────────────
+
+function statusFor(data) {
+  if (THINKING.test(data)) {
+    return { status: 'thinking', statusDetail: 'Codex is reasoning...' };
+  }
+  if (EDITING.test(data)) {
+    const match = data.match(EDITING_DETAIL);
+    return {
+      status: 'editing',
+      statusDetail: match ? `${match[1]} ${match[2]}` : 'Editing files',
+    };
+  }
+  if (TOOL.test(data)) {
+    return { status: 'active', statusDetail: 'Using tools' };
+  }
+  if (IDLE.test(data)) {
+    return { status: 'idle', statusDetail: 'Waiting for input' };
+  }
+  return null;
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// parseTranscript — Codex JSONL format.
+//
+// Each line is `{ timestamp, type, payload }`. We want only:
+//   type === 'response_item' && payload.type === 'message'
+// with payload.role in {user, assistant}. The 'developer' role carries the
+// permissions/sandbox prelude — skip. `event_msg` lines duplicate the
+// canonical message channel and additionally carry exec_command_end shell
+// output blocks — skip too.
+//
+// content is an array of { type: 'input_text' | 'output_text', text: string }
+// (sometimes plain `text`). Joined with spaces and truncated to 400 chars
+// per message (same cut-off Claude uses).
+// ──────────────────────────────────────────────────────────────────────────
+
+function parseTranscript(raw) {
+  if (typeof raw !== 'string' || raw.length === 0) return [];
+  const lines = raw.split('\n').filter(Boolean);
+  const messages = [];
+  for (const line of lines) {
+    let entry;
+    try { entry = JSON.parse(line); } catch (_) { continue; }
+    if (!entry || entry.type !== 'response_item') continue;
+    const p = entry.payload;
+    if (!p || p.type !== 'message') continue;
+    const role = p.role;
+    if (role !== 'user' && role !== 'assistant') continue;
+    const content = p.content;
+    let text = '';
+    if (typeof content === 'string') {
+      text = content;
+    } else if (Array.isArray(content)) {
+      text = content
+        .filter((c) => c && (c.type === 'input_text' || c.type === 'output_text' || c.type === 'text'))
+        .map((c) => c.text || '')
+        .join(' ');
+    }
+    if (text) messages.push({ role, content: text.slice(0, 400) });
+  }
+  return messages;
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// bootPromptTemplate — Codex variant of the Claude scaffold. Points at
+// AGENTS.md (Codex's instructional file) instead of CLAUDE.md. Sprint 46 T2
+// will refine per-agent prompts; this is the placeholder so the contract is
+// uniform across all four adapters.
+// ──────────────────────────────────────────────────────────────────────────
+
+function bootPromptTemplate(lane = {}, sprint = {}) {
+  const tn = lane.id || 'T?';
+  const sprintNum = sprint.number || '?';
+  const sprintName = sprint.name || 'unnamed';
+  const project = (lane.project || sprint.project || 'termdeck');
+  const briefing = lane.briefingPath || `docs/sprint-${sprintNum}-${sprintName}/${tn}-<lane>.md`;
+  return [
+    `You are ${tn} in Sprint ${sprintNum} (${sprintName}). Boot sequence:`,
+    `1. memory_recall(project="${project}", query="<topic>")`,
+    `2. memory_recall(query="<broader topic>")`,
+    `3. Read ~/.claude/CLAUDE.md and ./AGENTS.md`,
+    `4. Read docs/sprint-${sprintNum}-${sprintName}/PLANNING.md`,
+    `5. Read docs/sprint-${sprintNum}-${sprintName}/STATUS.md`,
+    `6. Read ${briefing}`,
+    '',
+    'Then begin. Stay in your lane. Post FINDING / FIX-PROPOSED / DONE in STATUS.md.',
+    "Don't bump versions, don't touch CHANGELOG, don't commit.",
+  ].join('\n');
+}
+
+const codexAdapter = {
+  name: 'codex',
+  sessionType: 'codex',
+  matches: (cmd) => typeof cmd === 'string' && /\bcodex\b/i.test(cmd),
+  spawn: {
+    binary: 'codex',
+    defaultArgs: [],
+    env: { OPENAI_API_KEY: process.env.OPENAI_API_KEY },
+  },
+  patterns: {
+    prompt: PROMPT,
+    thinking: THINKING,
+    editing: EDITING,
+    tool: TOOL,
+    idle: IDLE,
+    error: ERROR,
+  },
+  patternNames: {
+    error: 'codexErrorLineStart',
+  },
+  statusFor,
+  parseTranscript,
+  bootPromptTemplate,
+  costBand: 'pay-per-token',
+};
+
+module.exports = codexAdapter;

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

@@ -0,0 +1,158 @@
+// Gemini CLI adapter — Sprint 45 T2
+//
+// Lifts the previously-hardcoded gemini logic out of session.js into the
+// AGENT_ADAPTERS registry alongside the Claude adapter shipped in Sprint 44
+// T3. Behavior is bit-for-bit identical to the pre-Sprint-45 inline path:
+// same `^gemini>` prompt regex, same `Generating|Working` thinking regex,
+// same status strings ("Gemini is generating..." / "Waiting for input"),
+// same loose `/gemini/i` command-string match. parseTranscript is the new
+// capability — Gemini sessions previously didn't write to Mnestra because
+// the memory hook assumed Claude JSONL.
+//
+// Contract — see ./claude.js header for the full 7-field shape.
+//
+// Patterns intentionally omit `error`. The fallback in session.js
+// `_detectErrors` (`adapter.patterns.error || PATTERNS.error`) lets generic
+// prose-shape error detection continue to apply to Gemini sessions, which
+// matches the pre-Sprint-45 behavior. Sprint 46+ can layer in a Gemini-
+// specific line-anchored error pattern once we've observed enough TUI
+// output to know what false positives to dodge.
+
+// ──────────────────────────────────────────────────────────────────────────
+// Patterns — verbatim regexes lifted from session.js's PATTERNS.geminiCli
+// (lines 47-50). Reference-equal preservation matters because session.js
+// keeps a `PATTERNS.geminiCli` shim that points back at these regex
+// objects, the same way `PATTERNS.claudeCode.*` shimmed Sprint 44 T3.
+// ──────────────────────────────────────────────────────────────────────────
+
+const PROMPT = /^gemini>\s/m;
+const THINKING = /\b(Generating|Working)\b/;
+
+// ──────────────────────────────────────────────────────────────────────────
+// statusFor — replaces the `case 'gemini':` block of _updateStatus. Order
+// matches the legacy switch's `if/else if` cascade exactly: thinking wins,
+// then prompt → idle. No editing/tool/error branches in the legacy switch,
+// so statusFor has none either; null returns leave the status untouched
+// just like the legacy fall-through.
+// ──────────────────────────────────────────────────────────────────────────
+
+function statusFor(data) {
+  if (THINKING.test(data)) {
+    return { status: 'thinking', statusDetail: 'Gemini is generating...' };
+  }
+  if (PROMPT.test(data)) {
+    return { status: 'idle', statusDetail: 'Waiting for input' };
+  }
+  return null;
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// parseTranscript — Gemini CLI session JSON format (NOT JSONL).
+//
+// Captured shape (from `gemini -p "say hi"` 2026-05-01):
+//   {
+//     sessionId, projectHash, startTime, lastUpdated, kind,
+//     messages: [
+//       { id, timestamp, type: 'user',   content: [{ text: '...' }] },
+//       { id, timestamp, type: 'gemini', content: '...', thoughts, tokens, model },
+//       ...
+//     ]
+//   }
+//
+// The user role carries a content ARRAY of `{text}` parts; the gemini
+// (assistant) role carries a STRING. We normalize both to the Claude
+// adapter's output shape — `{ role: 'user'|'assistant', content: string }`
+// truncated to 400 chars — so the memory-hook summary builder doesn't have
+// to branch on adapter type.
+//
+// `type: 'gemini'` maps to `role: 'assistant'` for cross-adapter parity.
+// ──────────────────────────────────────────────────────────────────────────
+
+function parseTranscript(raw) {
+  if (typeof raw !== 'string' || raw.length === 0) return [];
+  let session;
+  try { session = JSON.parse(raw); } catch (_) { return []; }
+  if (!session || !Array.isArray(session.messages)) return [];
+
+  const messages = [];
+  for (const msg of session.messages) {
+    if (!msg || typeof msg !== 'object') continue;
+    let role;
+    if (msg.type === 'user') role = 'user';
+    else if (msg.type === 'gemini' || msg.type === 'assistant') role = 'assistant';
+    else continue;
+
+    const content = msg.content;
+    let text = '';
+    if (typeof content === 'string') {
+      text = content;
+    } else if (Array.isArray(content)) {
+      text = content
+        .filter((c) => c && typeof c.text === 'string')
+        .map((c) => c.text)
+        .join(' ');
+    }
+    if (text) messages.push({ role, content: text.slice(0, 400) });
+  }
+  return messages;
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// bootPromptTemplate — placeholder mirroring the Claude adapter's shape.
+// Points at GEMINI.md (the auto-generated mirror of CLAUDE.md per Sprint 44
+// T2's sync-agent-instructions.js script). Sprint 46 T2 will refine the
+// per-agent boot prompt — Gemini doesn't have Claude's `memory_recall` MCP
+// tool out-of-the-box, so the lane brief shape may need agent-specific
+// scaffolding. The placeholder here keeps the contract complete.
+// ──────────────────────────────────────────────────────────────────────────
+
+function bootPromptTemplate(lane = {}, sprint = {}) {
+  const tn = lane.id || 'T?';
+  const sprintNum = sprint.number || '?';
+  const sprintName = sprint.name || 'unnamed';
+  const project = (lane.project || sprint.project || 'termdeck');
+  const briefing = lane.briefingPath || `docs/sprint-${sprintNum}-${sprintName}/${tn}-<lane>.md`;
+  return [
+    `You are ${tn} in Sprint ${sprintNum} (${sprintName}). Boot sequence:`,
+    `1. memory_recall(project="${project}", query="<topic>")`,
+    `2. memory_recall(query="<broader topic>")`,
+    `3. Read ~/.claude/CLAUDE.md and ./GEMINI.md`,
+    `4. Read docs/sprint-${sprintNum}-${sprintName}/PLANNING.md`,
+    `5. Read docs/sprint-${sprintNum}-${sprintName}/STATUS.md`,
+    `6. Read ${briefing}`,
+    '',
+    'Then begin. Stay in your lane. Post FINDING / FIX-PROPOSED / DONE in STATUS.md.',
+    "Don't bump versions, don't touch CHANGELOG, don't commit.",
+  ].join('\n');
+}
+
+const geminiAdapter = {
+  name: 'gemini',
+  sessionType: 'gemini',
+  matches: (cmd) => typeof cmd === 'string' && /gemini/i.test(cmd),
+  spawn: {
+    binary: 'gemini',
+    defaultArgs: [],
+    // GEMINI_API_KEY is read via `process.env` at spawn time by index.js'
+    // PTY env merge — declared here for documentation / discoverability,
+    // not for in-adapter overriding. OAuth-personal is the typical auth
+    // path (settings.json `security.auth.selectedType: 'oauth-personal'`).
+    env: {},
+  },
+  patterns: {
+    prompt: PROMPT,
+    thinking: THINKING,
+    // editing / tool / error intentionally omitted — see header comment.
+  },
+  patternNames: {
+    // No adapter-owned error pattern → session.js falls back to the
+    // generic `PATTERNS.error` and the `'error'` diag label, which is
+    // exactly what gemini-typed sessions saw pre-Sprint-45.
+  },
+  statusFor,
+  parseTranscript,
+  bootPromptTemplate,
+  costBand: 'pay-per-token',
+};
+
+module.exports = geminiAdapter;