@jhizzard/termdeck 0.12.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhizzard/termdeck",
-  "version": "0.12.0",
+  "version": "0.14.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"
@@ -30,7 +30,8 @@
     "start": "NODE_ENV=production node packages/cli/src/index.js",
     "test": "node --test packages/server/tests/**/*.test.js",
     "install:app": "bash install.sh",
-    "sync-rumen-functions": "bash scripts/sync-rumen-functions.sh"
+    "sync-rumen-functions": "bash scripts/sync-rumen-functions.sh",
+    "sync:agents": "node scripts/sync-agent-instructions.js"
   },
   "dependencies": {
     "@homebridge/node-pty-prebuilt-multiarch": "^0.13.1",

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,29 +2479,54 @@
         return;
       }
 
-      // Parse shorthand commands
+      // Sprint 45 T4: registry-driven shorthand resolution. Pre-Sprint-45
+      // had hardcoded claude/cc/gemini/python branches here; now the type
+      // detection consults state.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 below. 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.
       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;
+      // Claude `cc` alias normalization. Documented Claude shorthand —
+      // does not generalize to other adapters, so it stays in client UX,
+      // not in the server-side adapter contract.
+      let canonical = command;
+      if (/^cc\b/i.test(canonical)) {
+        canonical = canonical.replace(/^cc\b/i, 'claude');
+      }
+
+      const adapter = (state.agentAdapters || []).find((a) =>
+        a && a.binary && new RegExp(`^${a.binary}\\b`, 'i').test(canonical)
+      );
+
+      if (adapter) {
+        resolvedType = adapter.sessionType;
+        // Claude shorthand: `claude <project-or-cwd>` rewrites to `claude`
+        // and routes the trailing arg into either the project dropdown
+        // (if it's a known project name) or the cwd parameter. Other
+        // adapters' arg-parsing — codex sub-commands, gemini -p flag,
+        // grok --model — pass through unchanged via resolvedCommand.
+        if (adapter.name === 'claude') {
+          const argMatch = canonical.match(/^claude\s+(?:code\s+)?(.+)/i);
+          if (argMatch) {
+            const arg = argMatch[1].trim();
+            if (state.config.projects && state.config.projects[arg]) {
+              resolvedProject = arg;
+            } else {
+              resolvedCwd = arg;
+            }
           }
+          resolvedCommand = adapter.binary;
         }
-        resolvedCommand = 'claude';
-      } else if (/^gemini\b/i.test(command)) {
-        resolvedType = 'gemini';
-      } else if (/^python3?\b.*(?:runserver|uvicorn|flask|gunicorn)/i.test(command)) {
+      } else if (/^python3?\b.*(?:runserver|uvicorn|flask|gunicorn)/i.test(canonical)) {
+        // python-server is a server SUBTYPE for status badges, not an
+        // agent adapter. No registry entry for it; detection stays here.
         resolvedType = 'python-server';
       }
 

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

@@ -0,0 +1,158 @@
+// Claude Code adapter — Sprint 44 T3
+//
+// First adapter in the AGENT_ADAPTERS registry (see ./index.js). Lifts the
+// claude-code logic that previously lived as hardcoded branches in
+// packages/server/src/session.js. Behavior is bit-for-bit identical to the
+// pre-Sprint-44 inline path: same regexes, same status strings, same
+// transcript-parser cut-offs. Sprint 45 adds Codex / Gemini / Grok adapters
+// alongside this one; Sprint 46 wires per-lane agent assignment in 4+1.
+//
+// Contract (memorialization doc § 4 + lane brief T3):
+//   {
+//     name:           string,                     // adapter id used in registry
+//     sessionType:    string,                     // session.meta.type produced
+//     matches:        (cmd) => boolean,           // command-string detection
+//     spawn:          { binary, defaultArgs, env },
+//     patterns:       { prompt, thinking, editing, tool, idle, error },
+//     patternNames:   { error: string },          // diag-event label preservation
+//     statusFor:      (data) => { status, statusDetail } | null,
+//     parseTranscript:(raw) => Memory[],          // for memory-session-end hook
+//     bootPromptTemplate: (lane, sprint) => string,
+//     costBand:       'free' | 'pay-per-token' | 'subscription',
+//   }
+//
+// `statusFor` returns null when no pattern matches — preserves the original
+// "no change" semantics for the claude-code switch case. Caller leaves
+// `meta.status` and `meta.statusDetail` untouched on null.
+
+// ──────────────────────────────────────────────────────────────────────────
+// Patterns — verbatim regexes lifted from session.js so the adapter and the
+// shim remain reference-equal. Don't redeclare these elsewhere; import from
+// the adapter so future tweaks land in one place.
+// ──────────────────────────────────────────────────────────────────────────
+
+const PROMPT = /^[>❯]\s/m;
+const THINKING = /\b(thinking|Thinking)\b/;
+const EDITING = /^(Edit|Create|Update|Delete)\s/m;
+const EDITING_DETAIL = /^(Edit|Create|Update|Delete)\s+(.+)$/m;
+const TOOL = /^⏺\s/m;
+const IDLE = /^>\s*$/m;
+
+// errorLineStart from session.js — line-anchored variant for claude-code
+// 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;
+
+// ──────────────────────────────────────────────────────────────────────────
+// statusFor — replaces the `case 'claude-code':` block of _updateStatus.
+// Order matters: thinking → editing → tool → idle. First match wins, exactly
+// as the original switch did with cascading `else if`s.
+// ──────────────────────────────────────────────────────────────────────────
+
+function statusFor(data) {
+  if (THINKING.test(data)) {
+    return { status: 'thinking', statusDetail: 'Claude 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 — Claude Code JSONL format, lifted from
+// packages/stack-installer/assets/hooks/memory-session-end.js:88-102.
+// Emits records of shape { role: 'user'|'assistant', content: string }
+// truncated to 400 chars per message. The hook itself remains the consumer
+// in Sprint 44; Sprint 45 T4 wires it to read from this adapter so other
+// agents can plug in their own format parsers.
+// ──────────────────────────────────────────────────────────────────────────
+
+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 msg;
+    try { msg = JSON.parse(line); } catch (_) { continue; }
+    const role = msg && msg.message && msg.message.role;
+    if (role !== 'user' && role !== 'assistant') continue;
+    const content = msg.message.content;
+    let text = '';
+    if (typeof content === 'string') {
+      text = content;
+    } else if (Array.isArray(content)) {
+      text = content
+        .filter((c) => c && c.type === 'text')
+        .map((c) => c.text)
+        .join(' ');
+    }
+    if (text) messages.push({ role, content: text.slice(0, 400) });
+  }
+  return messages;
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// bootPromptTemplate — minimal scaffold matching the global-CLAUDE.md 4+1
+// boot block. Sprint 46 T2 will refine per-agent prompts; this is the
+// placeholder so the adapter contract is complete in Sprint 44.
+// ──────────────────────────────────────────────────────────────────────────
+
+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 ./CLAUDE.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 claudeAdapter = {
+  name: 'claude',
+  sessionType: 'claude-code',
+  matches: (cmd) => typeof cmd === 'string' && /claude/i.test(cmd),
+  spawn: {
+    binary: 'claude',
+    defaultArgs: [],
+    env: {},
+  },
+  patterns: {
+    prompt: PROMPT,
+    thinking: THINKING,
+    editing: EDITING,
+    tool: TOOL,
+    idle: IDLE,
+    error: ERROR,
+  },
+  patternNames: {
+    error: 'errorLineStart',
+  },
+  statusFor,
+  parseTranscript,
+  bootPromptTemplate,
+  costBand: 'pay-per-token',
+};
+
+module.exports = claudeAdapter;

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;