@jhizzard/termdeck 1.4.0 → 1.6.0

package/packages/server/src/index.js

@@ -10,7 +10,6 @@ const os = require('os');
 const fs = require('fs');
 const dns = require('dns');
 const { spawn: spawnChild } = require('child_process');
-const { v4: uuidv4 } = require('uuid');
 const { createCachedLookup, createFailureLogger } = require('./rumen-pool-resilience');
 
 // Conditional imports (graceful fallback if not installed yet)
@@ -29,7 +28,7 @@ try {
     console.error('[db] better-sqlite3 native ABI mismatch (Node was upgraded after install).');
     console.error('[db] TermDeck cannot serve memory features without a working SQLite.');
     console.error('[db] Fix:');
-    console.error('       cd "$(npm root -g)/@jhizzard/termdeck" && npm rebuild better-sqlite3');
+    process.stderr.write('       cd "$(npm root -g)/@jhizzard/termdeck" && npm rebuild better-sqlite3\n');
     console.error('[db] Then restart TermDeck. Aborting.');
     process.exit(1);
   }
@@ -94,6 +93,13 @@ const { themes, statusColors } = require('./themes');
 const { loadConfig, addProject, removeProject, updateConfig } = require('./config');
 const { createAuthMiddleware, verifyWebSocketUpgrade, hasAuth } = require('./auth');
 const { createSprintRoutes } = require('./sprint-routes');
+const { createSprintInjectRoutes } = require('./sprints/inject');
+// Sprint 69 T1 — boot-prompt template engine. Exposed at the public surface
+// so external callers (T2's inject route, integration tests, future tools)
+// can do `require('@termdeck/server').templateEngine` instead of reaching
+// into the internal `./templates/template-engine` path.
+const templateEngine = require('./templates/template-engine');
+const { createSprintNudgeRoutes } = require('./sprints/nudge');
 const { createGraphRoutes } = require('./graph-routes');
 const { createProjectsRoutes } = require('./projects-routes');
 const orchestrationPreview = require('./orchestration-preview');
@@ -210,13 +216,13 @@ function _defaultSpawnSessionEndHookImpl(hookPath, payload, env) {
     env,
   });
   child.on('error', (err) => {
-    console.error('[onPanelClose] hook spawn error:', err && err.message ? err.message : err);
+    console.error('[panel-close] hook spawn error:', err && err.message ? err.message : err);
   });
   try {
     child.stdin.write(JSON.stringify(payload));
     child.stdin.end();
   } catch (err) {
-    console.error('[onPanelClose] hook stdin write failed:', err && err.message ? err.message : err);
+    console.error('[panel-close] hook stdin write failed:', err && err.message ? err.message : err);
   }
   child.unref();
   return child;
@@ -292,7 +298,7 @@ async function onPanelClose(session) {
       ...readTermdeckSecretsForPty(),
     });
   } catch (err) {
-    console.error('[onPanelClose] error:', err && err.message ? err.message : err);
+    console.error('[panel-close] error:', err && err.message ? err.message : err);
   }
 }
 
@@ -367,7 +373,7 @@ async function onPanelPeriodicCapture(session) {
     session._periodicCapture.lastSize = stat.size;
     session._periodicCapture.lastFireMs = Date.now();
   } catch (err) {
-    console.error('[onPanelPeriodicCapture] error:', err && err.message ? err.message : err);
+    console.error('[periodic-capture] error:', err && err.message ? err.message : err);
   }
 }
 
@@ -424,7 +430,7 @@ function _getT2DestFor() {
 
 function _termdeckVersion() {
   try { return require('../../../package.json').version; }
-  catch { return '0.0.0'; }
+  catch (err) { console.error('[version] package.json read failed:', err); return '0.0.0'; }
 }
 
 // Sprint 60 v1.0.14 (Item 3) — safe PTY resize. Brad's 2026-05-07 r730 crash
@@ -432,7 +438,7 @@ function _termdeckVersion() {
 // EBADF/ENOTTY` per 13h uptime. Race: WS `resize` message arrives for a PTY
 // that pty-reaper has already closed (or the child has exited), and
 // `pty.resize()` ioctls a stale fd. The error is race-expected, not a bug,
-// but the noisy console.error trace pollutes diagnostics and obscures real
+// but the noisy stderr trace pollutes diagnostics and obscures real
 // errors. This helper guards against the race and downgrades the known
 // race-class errors (EBADF, ENOTTY) to a silent return. Set
 // TERMDECK_DEBUG_PTY_RACES=1 to log to console.debug for diagnostics.
@@ -1457,7 +1463,7 @@ function createServer(config) {
             session._periodicCapture = { lastSize: 0, lastFireMs: 0, timer: null };
             session._periodicCapture.timer = setInterval(() => {
               onPanelPeriodicCapture(session).catch((err) => {
-                console.error('[onPanelPeriodicCapture] async error:', err && err.message ? err.message : err);
+                console.error('[periodic-capture] async error:', err && err.message ? err.message : err);
               });
             }, intervalMs);
             // Don't keep the event loop alive solely for this timer — the PTY
@@ -1549,7 +1555,7 @@ function createServer(config) {
           // skip-claude + skip-when-no-transcript. Fire-and-forget; any
           // error logs and never blocks teardown.
           onPanelClose(session).catch((err) => {
-            console.error('[onPanelClose] async error:', err && err.message ? err.message : err);
+            console.error('[panel-close] async error:', err && err.message ? err.message : err);
           });
 
           // Sprint 59 T4-CODEX UPLOAD-AUDIT-CONCERN closure: blow away the
@@ -1735,6 +1741,14 @@ function createServer(config) {
     spawnTerminalSession,
     getSession: (id) => sessions.get(id),
   });
+  createSprintInjectRoutes({
+    app,
+    getSession: (id) => sessions.get(id),
+  });
+  createSprintNudgeRoutes({
+    app,
+    getSession: (id) => sessions.get(id),
+  });
 
   // Graph endpoints (Sprint 38 T4) — knowledge-graph view backing graph.html.
   // Reuses the daily-driver pg pool (same DATABASE_URL serves memory_items +
@@ -1754,7 +1768,19 @@ function createServer(config) {
 
   // PATCH /api/sessions/:id - update session metadata
   app.patch('/api/sessions/:id', (req, res) => {
-    const session = sessions.updateMeta(req.params.id, req.body);
+    // Sprint 66 T1 (Task 1.2) — `role` is PATCH-mutable so an operator can tag
+    // a live panel as orchestrator in place. Validate it exactly as POST
+    // /api/sessions does (index.js — the `invalid_role` 400 above): an absent
+    // field is fine, any present value must be in ALLOWED_SESSION_ROLES
+    // (orchestrator/worker/reviewer/auditor/null) — an unknown value is a 400
+    // so a typo surfaces immediately rather than silently mis-tagging the
+    // panel. Validation runs BEFORE updateMeta so a bad role never reaches the
+    // whitelist apply or the SQLite write.
+    const body = req.body || {};
+    if (body.role !== undefined && !ALLOWED_SESSION_ROLES.includes(body.role)) {
+      return res.status(400).json({ ok: false, code: 'invalid_role', allowed: ALLOWED_SESSION_ROLES });
+    }
+    const session = sessions.updateMeta(req.params.id, body);
     if (!session) return res.status(404).json({ error: 'Session not found' });
     res.json(session.toJSON());
   });
@@ -2023,7 +2049,7 @@ function createServer(config) {
       return res.status(410).json({ error: 'PTY is gone (session exited)' });
     }
 
-    const { cols, rows } = req.body;
+    const { cols, rows } = req.body || {};
     try {
       const resized = safelyResizePty(session, cols, rows);
       if (!resized) {
@@ -2603,7 +2629,7 @@ function createServer(config) {
 
   // POST /api/ai/query - query Mnestra memory via the bridge (direct|webhook|mcp)
   app.post('/api/ai/query', async (req, res) => {
-    let { question, sessionId, project } = req.body;
+    let { question, sessionId, project } = req.body || {};
     if (!question) return res.status(400).json({ error: 'Missing question' });
 
     let searchAll = false;
@@ -2758,8 +2784,9 @@ function createServer(config) {
     });
   }, 2000);
 
-  // Fallback route → serve index.html
-  app.get('*', (req, res) => {
+  // Fallback route → serve index.html. Express 5: named wildcard '/{*splat}'
+  // (path-to-regexp v8 — a bare '*' throws at registration; this matches all paths incl. root).
+  app.get('/{*splat}', (req, res) => {
     res.sendFile(path.join(clientDir, 'index.html'));
   });
 
@@ -3050,6 +3077,10 @@ module.exports = {
   SECRETS_EXCLUDED_FROM_PTY,
   // Sprint 65 T2 (2.1) — operator-role whitelist, exported for the route fence.
   ALLOWED_SESSION_ROLES,
+  // Sprint 69 T1 — boot-prompt template engine. Exported so T2's inject
+  // endpoint and integration tests can import without traversing the
+  // internal `./templates/template-engine` path.
+  templateEngine,
   // Sprint 50 T1 — exported for unit testing the per-agent SessionEnd
   // hook trigger (skip-claude, no-transcript, no-hook-installed,
   // payload shape, fire-and-forget).

package/packages/server/src/orchestration-preview.js

@@ -187,7 +187,7 @@ async function generateScaffolding({ name, projects, cwd, force, initProject, te
   // Refuse on existing non-empty dir without force, mirroring T2's CLI semantics.
   if (fs.existsSync(targetPath)) {
     const entries = (() => {
-      try { return fs.readdirSync(targetPath); } catch { return []; }
+      try { return fs.readdirSync(targetPath); } catch (err) { console.error('[orch-preview] readdir failed:', err); return []; }
     })();
     const nonEmpty = entries.length > 0;
     if (nonEmpty && !force) {

package/packages/server/src/parked-detection.js

@@ -0,0 +1,50 @@
+/**
+ * Parked-lane detection for TermDeck.
+ *
+ * Algorithm:
+ * - If session status is not "active", it's not parked (it might be thinking, editing, or exited).
+ * - If lastActivity was within the last 5 minutes, it's genuinely active.
+ * - Otherwise, parse the trailing output buffer for Claude Code's completion banners.
+ * - If matched, it's parked.
+ *
+ * Completion banners (Claude Code):
+ * - "Cogitated for 1m 2s"
+ * - "Churned for 5m 10s"
+ * - Verbs: Cogitated, Churned, Brewed, Cooked, Mused, Pondered, Wandered, Crafted.
+ */
+
+const { stripAnsi } = require('./transcripts');
+
+function detectParked(session) {
+  if (!session || !session.meta) return false;
+
+  // Only "active" (PTY-wise) sessions can be "parked" (semantic-wise).
+  // "thinking" or "editing" statuses are already semantic indicators
+  // of work-in-progress.
+  if (session.meta.status !== 'active') return false;
+
+  const now = Date.now();
+  const lastActivity = new Date(session.meta.lastActivity).getTime();
+  const ageMs = now - lastActivity;
+
+  // Threshold: 5 minutes.
+  const FIVE_MIN_MS = 5 * 60 * 1000;
+  if (ageMs < FIVE_MIN_MS) return false;
+
+  // Read the session's output buffer (last ~4KB preserved in Session.analyzeOutput).
+  const buffer = session._outputBuffer || '';
+  if (!buffer) return false;
+
+  // Strip ANSI to match the plain-text banner
+  const cleanBuffer = stripAnsi(buffer);
+
+  // Regex per BRIEF + PLANNING:
+  // (Cogitated|Churned|Brewed|Cooked|Mused|Pondered|Wandered|Crafted) for \d+m \d+s
+  const PARKED_BANNER_RE = /(?:Cogitated|Churned|Brewed|Cooked|Mused|Pondered|Wandered|Crafted) for \d+m \d+s/i;
+
+  // Look in the last ~1000 chars of the cleaned buffer.
+  const tail = cleanBuffer.slice(-1000);
+  return PARKED_BANNER_RE.test(tail);
+}
+
+module.exports = { detectParked };

package/packages/server/src/session.js

@@ -10,7 +10,7 @@
 // metadata broadcast in index.js untouched — `s.meta.theme` already returns
 // the right thing whenever index.js dereferences it.
 
-const { v4: uuidv4 } = require('uuid');
+const { randomUUID } = require('crypto');
 const os = require('os');
 const path = require('path');
 const { resolveTheme } = require('./theme-resolver');
@@ -18,6 +18,8 @@ const flashbackDiag = require('./flashback-diag');
 const geminiAdapter = require('./agent-adapters/gemini');
 const { detectAdapter, getAdapterForSessionType } = require('./agent-adapters');
 
+const { detectParked } = require("./parked-detection");
+
 // Strip ANSI escape codes for pattern matching
 function stripAnsi(str) {
   return str
@@ -135,7 +137,7 @@ const PATTERNS = {
 
 class Session {
   constructor(options) {
-    this.id = options.id || uuidv4();
+    this.id = options.id || randomUUID();
     this.pid = null;
     this.pty = null;
     this.ws = null;
@@ -540,8 +542,10 @@ class Session {
       if (ageMs > Session.STALE_STATUS_THRESHOLD_MS) {
         meta.status = 'idle';
         meta.statusDetail = '';
+        meta.parked = true;
       }
     }
+    meta.parked = detectParked(this);
     return {
       id: this.id,
       pid: this.pid,
@@ -634,7 +638,15 @@ class SessionManager {
     'label',
     'project',
     'ragEnabled',
-    'flashbackEnabled'
+    'flashbackEnabled',
+    // Sprint 66 T1 (Task 1.2) — `role` is now PATCH-mutable so an operator can
+    // tag a live panel as orchestrator in place (Brad's existing orch panel
+    // was spawned with no role and had no way to set one short of a raw-API
+    // destroy + recreate). The PATCH /api/sessions/:id route validates the
+    // value against ALLOWED_SESSION_ROLES before this whitelist is consulted —
+    // the same "route validates, model trusts" boundary as POST /api/sessions
+    // and the Session constructor.
+    'role'
   ]);
 
   updateMeta(id, updates) {
@@ -657,6 +669,16 @@ class SessionManager {
         .run(applied.theme == null ? null : applied.theme, id);
     }
 
+    // Sprint 66 T1 (Task 1.2) — persist a role change to SQLite so a panel
+    // tagged orchestrator via PATCH keeps the role across a server restart /
+    // dashboard reload, exactly as a spawn-time role does. create() writes the
+    // `role` column on INSERT; this is its UPDATE counterpart. The column was
+    // added by Sprint 65 T2 (CREATE TABLE + a PRAGMA-guarded ALTER migration).
+    if ('role' in applied && this.db) {
+      this.db.prepare('UPDATE sessions SET role = ? WHERE id = ?')
+        .run(applied.role == null ? null : applied.role, id);
+    }
+
     this._emit('session:updated', session);
     return session;
   }

package/packages/server/src/sprint-inject.js

@@ -233,7 +233,7 @@ async function injectSprintPrompts({
           } else {
             anyPending = true;
           }
-        } catch {
+        } catch (_err) {
           anyPending = true;
         }
       }
@@ -257,7 +257,7 @@ async function injectSprintPrompts({
         const s = await getStatus(lane.sessionId);
         lane.finalStatus = s && s.status ? s.status : lane.finalStatus;
         if (lane.finalStatus === 'thinking') lane.verified = true;
-      } catch {
+      } catch (_err) {
         // ignore
       }
     }

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

@@ -22,6 +22,7 @@ const os = require('os');
 const { execFileSync } = require('child_process');
 
 const { injectSprintPrompts } = require('./sprint-inject');
+const { parseStatusMd: parseStatusMdV2 } = require('./sprints/status-parser');
 
 const SLUG_RE = /^[a-z0-9][a-z0-9-]{0,40}$/;
 
@@ -428,6 +429,22 @@ function createSprintRoutes({ app, config, spawnTerminalSession, getSession }) {
     res.json({ project, sprints });
   });
 
+
+  // GET /api/sprints/status?file=<path> — new structured parser (Sprint 69 T3)
+  app.get('/api/sprints/status', (req, res) => {
+    const filePath = req.query.file;
+    if (!filePath) return res.status(400).json({ error: 'file query param required' });
+    if (!fs.existsSync(filePath)) {
+      return res.status(404).json({ error: `file not found: ${filePath}` });
+    }
+    try {
+      const parsed = parseStatusMdV2(filePath);
+      res.json(parsed);
+    } catch (err) {
+      res.status(500).json({ error: `parse failed: ${err.message}` });
+    }
+  });
+
   // GET /api/sprints/:name/status?project=foo — parse STATUS.md per-lane.
   app.get('/api/sprints/:name/status', (req, res) => {
     const project = req.query.project;

package/packages/server/src/sprints/inject.js

@@ -0,0 +1,323 @@
+'use strict';
+
+const DEFAULT_SUBMIT_OPTIONS = {
+  gapMs: 250,
+  settleMs: 400,
+  snapshotDelayMs: 5000,
+};
+
+const ALLOWED_ROLES = new Set(['worker', 'auditor', 'orchestrator']);
+
+class SprintRequestError extends Error {
+  constructor(message, statusCode = 400, details = {}) {
+    super(message);
+    this.name = 'SprintRequestError';
+    this.statusCode = statusCode;
+    this.details = details;
+  }
+}
+
+function defaultSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function normalizeCliType(type) {
+  if (type === 'claude') return 'claude-code';
+  return type || 'shell';
+}
+
+function validateInjectBody(body) {
+  const input = isPlainObject(body) ? body : {};
+  if (!Array.isArray(input.panels) || input.panels.length === 0) {
+    throw new SprintRequestError('panels must be a non-empty array');
+  }
+  if (!isPlainObject(input.variables)) {
+    throw new SprintRequestError('variables must be an object');
+  }
+
+  const panels = input.panels.map((panel, index) => {
+    if (!isPlainObject(panel)) {
+      throw new SprintRequestError(`panels[${index}] must be an object`);
+    }
+    const tag = typeof panel.tag === 'string' ? panel.tag.trim() : '';
+    const sessionId = typeof panel.sessionId === 'string' ? panel.sessionId.trim() : '';
+    const role = typeof panel.role === 'string' ? panel.role.trim() : '';
+    const laneBrief = typeof panel.lane_brief === 'string' ? panel.lane_brief.trim() : '';
+
+    if (!tag) throw new SprintRequestError(`panels[${index}].tag is required`);
+    if (!sessionId) throw new SprintRequestError(`panels[${index}].sessionId is required`);
+    if (!ALLOWED_ROLES.has(role)) {
+      throw new SprintRequestError(
+        `panels[${index}].role must be one of: ${Array.from(ALLOWED_ROLES).join(', ')}`,
+      );
+    }
+    if (!laneBrief) throw new SprintRequestError(`panels[${index}].lane_brief is required`);
+
+    return { tag, sessionId, role, lane_brief: laneBrief };
+  });
+
+  return { panels, variables: { ...input.variables } };
+}
+
+function resolvePanelSessions(panels, getSession) {
+  if (typeof getSession !== 'function') {
+    throw new Error('getSession(sessionId) callback required');
+  }
+  return panels.map((panel) => {
+    const session = getSession(panel.sessionId);
+    if (!session) {
+      throw new SprintRequestError(`session not found: ${panel.sessionId}`, 400, {
+        code: 'invalid_session',
+        tag: panel.tag,
+        sessionId: panel.sessionId,
+      });
+    }
+    return session;
+  });
+}
+
+function defaultLoadTemplate(cliType, role, variables) {
+  // T1 owns this module in Sprint 69. Resolve lazily so T2's route can load
+  // before T1's engine has landed; endpoint calls surface a clear error.
+  const engine = require('../templates/template-engine');
+  if (!engine || typeof engine.loadTemplate !== 'function') {
+    throw new Error('template-engine must export loadTemplate(cliType, role, variables)');
+  }
+  return engine.loadTemplate(cliType, role, variables);
+}
+
+function normalizeMissingVariables(err) {
+  if (!err) return [];
+  const raw =
+    err.missingVariables
+    || err.missing_variables
+    || err.variables
+    || err.variableNames
+    || err.missing;
+  if (Array.isArray(raw)) return raw.map(String);
+  if (typeof raw === 'string' && raw) return [raw];
+  return [];
+}
+
+function mapTemplateError(err) {
+  const message = err && err.message ? err.message : String(err);
+  const missingVariables = normalizeMissingVariables(err);
+  const lower = message.toLowerCase();
+  const name = err && err.name;
+  const code = err && err.code;
+
+  if (code === 'MODULE_NOT_FOUND' && /template-engine/.test(message)) {
+    return new SprintRequestError('template engine unavailable', 503, {
+      code: 'template_engine_unavailable',
+      detail: message,
+    });
+  }
+
+  if (
+    name === 'MissingVariableError'
+    || code === 'missing_variable'
+    || code === 'missing_variables'
+    || missingVariables.length > 0
+    || (lower.includes('missing') && lower.includes('variable'))
+  ) {
+    return new SprintRequestError(message, 400, {
+      code: 'missing_template_variables',
+      missingVariables,
+    });
+  }
+
+  if (
+    code === 'unknown_template'
+    || code === 'unknown_cli_type'
+    || code === 'unknown_role'
+    || lower.includes('unknown template')
+    || lower.includes('unknown cli')
+    || lower.includes('unknown role')
+    || lower.includes('template not found')
+  ) {
+    return new SprintRequestError(message, 400, { code: 'template_error' });
+  }
+
+  return err;
+}
+
+async function renderInjectPanels({ panels, variables, sessions, loadTemplate }) {
+  const loader = loadTemplate || defaultLoadTemplate;
+  const rendered = [];
+
+  for (let i = 0; i < panels.length; i++) {
+    const panel = panels[i];
+    const session = sessions[i];
+    const cliType = normalizeCliType(session && session.meta && session.meta.type);
+    const templateVars = {
+      ...variables,
+      lane_brief: panel.lane_brief,
+      lane_tag: panel.tag,
+    };
+
+    try {
+      const text = await Promise.resolve(loader(cliType, panel.role, templateVars));
+      if (typeof text !== 'string') {
+        throw new Error('loadTemplate must return a string');
+      }
+      rendered.push({ ...panel, cliType, text });
+    } catch (err) {
+      throw mapTemplateError(err);
+    }
+  }
+
+  return rendered;
+}
+
+function sessionSnapshot(panel, session) {
+  const meta = (session && session.meta) || {};
+  return {
+    tag: panel.tag,
+    sessionId: panel.sessionId,
+    status: meta.status || null,
+    statusDetail: meta.statusDetail || '',
+    lastActivity: meta.lastActivity || null,
+  };
+}
+
+function createDefaultWriteInput(getSession) {
+  return async ({ sessionId, text }) => {
+    const session = getSession(sessionId);
+    if (!session) {
+      throw new SprintRequestError(`session not found: ${sessionId}`, 400, {
+        code: 'invalid_session',
+        sessionId,
+      });
+    }
+    if (!session.pty || (session.meta && session.meta.status === 'exited')) {
+      throw new SprintRequestError(`Panel ${sessionId} has exited`, 410, {
+        code: 'panel_exited',
+        sessionId,
+      });
+    }
+    try {
+      session.pty.write(text);
+      if (typeof session.trackInput === 'function') session.trackInput(text);
+      session.meta.replyCount = (session.meta.replyCount || 0) + 1;
+      return { ok: true, bytes: text.length, replyCount: session.meta.replyCount };
+    } catch (err) {
+      throw new SprintRequestError(err && err.message ? err.message : String(err), 500, {
+        code: 'write_failed',
+        sessionId,
+      });
+    }
+  };
+}
+
+async function runTwoStageSubmit({
+  panels,
+  getSession,
+  writeInput,
+  sleep,
+  options,
+  source,
+}) {
+  const opts = { ...DEFAULT_SUBMIT_OPTIONS, ...(options || {}) };
+  const wait = sleep || defaultSleep;
+  const write = writeInput || createDefaultWriteInput(getSession);
+
+  if (!Array.isArray(panels) || panels.length === 0) {
+    throw new SprintRequestError('panels must be a non-empty array');
+  }
+
+  for (let i = 0; i < panels.length; i++) {
+    const panel = panels[i];
+    await write({
+      sessionId: panel.sessionId,
+      text: `\x1b[200~${panel.text}\x1b[201~`,
+      source: source || 'sprint',
+      stage: 'paste',
+      panel,
+    });
+    if (i < panels.length - 1) await wait(opts.gapMs);
+  }
+
+  await wait(opts.settleMs);
+
+  for (let i = 0; i < panels.length; i++) {
+    const panel = panels[i];
+    await write({
+      sessionId: panel.sessionId,
+      text: '\r',
+      source: source || 'sprint',
+      stage: 'submit',
+      panel,
+    });
+    if (i < panels.length - 1) await wait(opts.gapMs);
+  }
+
+  if (opts.snapshotDelayMs > 0) await wait(opts.snapshotDelayMs);
+
+  return panels.map((panel) => sessionSnapshot(panel, getSession(panel.sessionId)));
+}
+
+function sendError(res, err) {
+  const mapped = err instanceof SprintRequestError ? err : new SprintRequestError(
+    err && err.message ? err.message : String(err),
+    err && err.statusCode ? err.statusCode : 500,
+    err && err.details ? err.details : {},
+  );
+  return res.status(mapped.statusCode).json({
+    ok: false,
+    error: mapped.message,
+    ...(mapped.details || {}),
+  });
+}
+
+function createSprintInjectHandler({ getSession, loadTemplate, writeInput, sleep, options } = {}) {
+  return async (req, res) => {
+    let parsed;
+    let sessions;
+    try {
+      parsed = validateInjectBody(req.body || {});
+      sessions = resolvePanelSessions(parsed.panels, getSession);
+      const rendered = await renderInjectPanels({
+        panels: parsed.panels,
+        variables: parsed.variables,
+        sessions,
+        loadTemplate,
+      });
+      const snapshots = await runTwoStageSubmit({
+        panels: rendered,
+        getSession,
+        writeInput,
+        sleep,
+        options,
+        source: 'sprint-inject',
+      });
+      return res.json({ ok: true, panels: snapshots });
+    } catch (err) {
+      return sendError(res, err);
+    }
+  };
+}
+
+function createSprintInjectRoutes(opts) {
+  if (!opts || !opts.app) throw new Error('app required');
+  opts.app.post('/api/sprints/inject', createSprintInjectHandler(opts));
+}
+
+module.exports = {
+  ALLOWED_ROLES,
+  DEFAULT_SUBMIT_OPTIONS,
+  SprintRequestError,
+  createDefaultWriteInput,
+  createSprintInjectHandler,
+  createSprintInjectRoutes,
+  defaultLoadTemplate,
+  normalizeCliType,
+  renderInjectPanels,
+  resolvePanelSessions,
+  runTwoStageSubmit,
+  sendError,
+  validateInjectBody,
+};