claude-code-session-manager 0.25.1 → 0.27.0

package/src/main/lib/definitionOfDone.cjs

@@ -11,7 +11,7 @@ const crypto = require('node:crypto');
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
-const { spawn } = require('node:child_process');
+const { spawn, spawnSync } = require('node:child_process');
 const { splitFrontmatter } = require('./prdFrontmatter.cjs');
 
 // Regex identifying meta/dod slugs that must NOT influence the batchKey.
@@ -313,4 +313,233 @@ async function reverifyBatch(jobs, { timeoutMs = 60_000, batchTimeoutMs = 600_00
   return results;
 }
 
-module.exports = { batchKey, reportPathFor, reportExists, extractAcCommand, reverifyAc, reverifyBatch };
+// ─── Risk heuristics ──────────────────────────────────────────────────────────
+// Conservative keyword/path matches — false positives are fine (they only add
+// a "review recommended" line); the cost of a miss on a money path is higher.
+const RISK_HEURISTICS = [
+  { surface: 'money-path', re: /money|trade|order|position|price|payment/i },
+  { surface: 'auth',       re: /auth|token|credential|secret/i },
+  { surface: 'migration',  re: /migration|schema|alembic|\.sql/i },
+];
+
+/**
+ * Extract a named heading section from a PRD body string.
+ * Returns the lines under the heading until the next sibling/parent heading.
+ * Complexity: O(L) where L = number of lines in body (bounded PRD document).
+ *
+ * @param {string} body
+ * @param {string} headingText  Case-insensitive heading to find.
+ * @returns {string}
+ */
+function _extractSection(body, headingText) {
+  const escapedHeading = headingText.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const headingRe = new RegExp(`^#+\\s+${escapedHeading}`, 'i');
+  const lines = body.split('\n');
+  let inSection = false;
+  let headingLevel = 0;
+  const sectionLines = [];
+
+  for (const line of lines) {
+    if (/^#+\s/.test(line)) {
+      const level = line.match(/^(#+)/)[1].length;
+      if (headingRe.test(line)) {
+        inSection = true;
+        headingLevel = level;
+      } else if (inSection && level <= headingLevel) {
+        inSection = false;
+      }
+      continue;
+    }
+    if (inSection) sectionLines.push(line);
+  }
+
+  return sectionLines.join('\n');
+}
+
+/**
+ * Inspect the files each job touched and flag risk surfaces.
+ *
+ * For each job:
+ *   1. If job.landedCommit is set, run `git show --name-only` (bounded by
+ *      gitTimeoutMs) to obtain changed file paths.
+ *   2. Otherwise fall back to the text of the PRD's `# Implementation notes`
+ *      section which authors are expected to list the files they plan to touch.
+ * Then check the candidate text against RISK_HEURISTICS (keyword/path match).
+ *
+ * Complexity: O(n * H) where n = jobs.length, H = RISK_HEURISTICS.length (3,
+ * a constant). Not user-scaled data — the scheduler queue is bounded.
+ *
+ * @param {Array<{ slug: string, cwd: string, landedCommit?: string }>} jobs
+ * @param {{ prdsDir?: string, gitTimeoutMs?: number }} opts
+ * @returns {Array<{ slug: string, surfaces: string[] }>}  Only jobs with ≥1 hit.
+ */
+function flagRiskySurfaces(jobs, { prdsDir, gitTimeoutMs = 10_000 } = {}) {
+  const resolvedPrdsDir = prdsDir ?? PRDS_DIR;
+  const results = [];
+
+  for (const job of jobs) {
+    let candidateText = '';
+
+    // 1. Try git commit — bounded by gitTimeoutMs.
+    if (job.landedCommit && job.cwd) {
+      try {
+        const r = spawnSync(
+          'git',
+          ['-C', job.cwd, 'show', '--name-only', '--format=', job.landedCommit],
+          { timeout: gitTimeoutMs, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }
+        );
+        if (r.status === 0 && r.stdout) candidateText = r.stdout;
+      } catch { /* fall through to PRD body */ }
+    }
+
+    // 2. Fallback: PRD # Implementation notes section.
+    // Guard: slug must contain only safe chars to prevent path traversal via a
+    // corrupted queue.json entry (e.g. slug: "../../.ssh/id_rsa").
+    if (!candidateText && job.slug && /^[\w-]+$/.test(job.slug)) {
+      try {
+        const raw = fs.readFileSync(path.join(resolvedPrdsDir, `${job.slug}.md`), 'utf8');
+        const body = splitFrontmatter(raw).body;
+        candidateText = _extractSection(body, 'Implementation notes');
+      } catch { /* no candidate text — skip */ }
+    }
+
+    if (!candidateText) continue;
+
+    // 3. Apply risk heuristics (O(H), constant).
+    const surfaces = RISK_HEURISTICS
+      .filter(h => h.re.test(candidateText))
+      .map(h => h.surface);
+
+    if (surfaces.length > 0) results.push({ slug: job.slug, surfaces });
+  }
+
+  return results;
+}
+
+// ─── Atomic write helper ───────────────────────────────────────────────────────
+// Re-implements the tmp+rename recipe from config.cjs writeTextAtomic (sync
+// variant), avoiding an import of Electron IPC code in a pure-node context.
+// Cross-ref: src/main/config.cjs writeJsonSync (same pattern).
+function _writeFileAtomic(absPath, text) {
+  const tmp = `${absPath}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  try {
+    fs.writeFileSync(tmp, text, 'utf8');
+    fs.renameSync(tmp, absPath);
+  } catch (err) {
+    try { fs.unlinkSync(tmp); } catch { /* tmp never created or already gone */ }
+    throw err;
+  }
+}
+
+const STATUS_EMOJI = { pass: '✅', fail: '❌', unverifiable: '⚠️' };
+
+/**
+ * Write a definition-of-done report for a completed batch.
+ *
+ * The report contains:
+ *   (a) a per-PRD AC table (slug · pass/fail/unverifiable),
+ *   (b) a risk-flag summary,
+ *   (c) a "needs human attention" list with a one-line recommendation per entry.
+ *
+ * The report is written atomically (tmp + rename) to avoid partial reads.
+ * Each call mints a fresh timestamped directory under runsDir, so two calls
+ * with the same key produce two separate files; use reportExists() to gate
+ * before calling.
+ *
+ * @param {string} key  Output of batchKey().
+ * @param {{
+ *   acResults: Array<{ slug: string, status: string, code: number|null, ms: number }>,
+ *   riskFlags:  Array<{ slug: string, surfaces: string[] }>,
+ *   runsDir?:  string,
+ * }} opts
+ * @returns {string}  Absolute path of the written report.
+ */
+function writeReport(key, { acResults = [], riskFlags = [], runsDir } = {}) {
+  if (!/^[0-9a-f]+$/.test(key)) throw new Error(`invalid batchKey: ${key}`);
+
+  const resolvedRunsDir = runsDir ?? RUNS_DIR;
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  const dir = path.join(resolvedRunsDir, ts);
+  const reportPath = path.join(dir, `definition-of-done-${key}.md`);
+
+  // ── AC table ────────────────────────────────────────────────────────────────
+  const acRows = acResults.map(r => {
+    const emoji = STATUS_EMOJI[r.status] ?? '';
+    return `| ${r.slug} | ${emoji} ${r.status} |`;
+  });
+  const acTable = [
+    '| Slug | Status |',
+    '|------|--------|',
+    ...acRows,
+  ].join('\n');
+
+  // ── Risk flags table ─────────────────────────────────────────────────────────
+  let riskSection;
+  if (riskFlags.length === 0) {
+    riskSection = '_No risk surfaces detected._';
+  } else {
+    riskSection = [
+      '| Slug | Surfaces |',
+      '|------|----------|',
+      ...riskFlags.map(r => `| ${r.slug} | ${r.surfaces.join(', ')} |`),
+    ].join('\n');
+  }
+
+  // ── Needs human attention ────────────────────────────────────────────────────
+  const attentionLines = [];
+  for (const r of acResults) {
+    if (r.status === 'fail') {
+      attentionLines.push(`- **${r.slug}** — AC failed; run \`/code-review\` on ${r.slug}`);
+    } else if (r.status === 'unverifiable') {
+      attentionLines.push(`- **${r.slug}** — unverifiable AC; manual inspection recommended for ${r.slug}`);
+    }
+  }
+  for (const r of riskFlags) {
+    attentionLines.push(
+      `- **${r.slug}** — touches ${r.surfaces.join(', ')}; run \`/code-review\` on ${r.slug} — ${r.surfaces.join('/')} path`
+    );
+  }
+  const attentionSection = attentionLines.length > 0
+    ? attentionLines.join('\n')
+    : '_None — all checks passed and no risk surfaces detected._';
+
+  // ── Assemble report ──────────────────────────────────────────────────────────
+  const report = [
+    `# Definition of Done — batch ${key}`,
+    '',
+    `Generated: ${new Date().toISOString()}`,
+    '',
+    '> **Note:** This report flags surfaces for human review.',
+    '> Deep LLM code-review is **recommended, not auto-run** — the gate detects',
+    '> and flags; humans or `/code-review` do the deep pass.',
+    '',
+    '## AC Results',
+    '',
+    acTable,
+    '',
+    '## Risk Flags',
+    '',
+    riskSection,
+    '',
+    '## Needs Human Attention',
+    '',
+    attentionSection,
+    '',
+  ].join('\n');
+
+  fs.mkdirSync(dir, { recursive: true });
+  _writeFileAtomic(reportPath, report);
+
+  return reportPath;
+}
+
+module.exports = {
+  batchKey,
+  reportPathFor,
+  reportExists,
+  extractAcCommand,
+  reverifyAc,
+  reverifyBatch,
+  flagRiskySurfaces,
+  writeReport,
+};

package/src/main/lib/dodDrainHook.cjs

@@ -0,0 +1,81 @@
+'use strict';
+
+/**
+ * dodDrainHook.cjs — definition-of-done gate that fires at queue drain.
+ *
+ * Extracted so the scheduler can call it fire-and-forget (non-blocking)
+ * while tests drive it directly with await.
+ *
+ * Kill-switch: SM_DOD_DISABLE=1 (mirrors SM_SUPERVISOR_DISABLE convention).
+ * Loop-safe: batchKey excludes dod/meta slugs; reportExists() + _inFlight
+ * dedup make re-drains over the same completed set a single fs-stat no-op,
+ * even when tickQueue fires twice in quick succession before the first
+ * reverifyBatch completes.
+ * Non-blocking: callers should fire-and-forget via .catch(); this function
+ * never throws to the caller (errors are logged instead).
+ */
+
+const {
+  batchKey,
+  reportExists,
+  reverifyBatch,
+  flagRiskySurfaces,
+  writeReport,
+} = require('./definitionOfDone.cjs');
+
+// Track keys whose DoD pass is currently in-flight.
+// Prevents concurrent tickQueue drains from spawning duplicate reverifyBatch
+// runs for the same completed set before the first one has written its report.
+const _inFlight = new Set();
+
+/**
+ * Run the definition-of-done gate when the scheduler queue drains.
+ *
+ * Guards (in order, fast-fail):
+ *   1. SM_DOD_DISABLE=1 → skip
+ *   2. state.paused (covers rate-limit) → defer, no report
+ *   3. cancelToken.cancelled → skip
+ *   4. No completed jobs → nothing to verify
+ *   5. reportExists(key) → already done for this batch, no-op
+ *   6. _inFlight.has(key) → concurrent drain for same batch, no-op
+ *   7. cancelToken.cancelled re-checked after reverifyBatch (up to 600s)
+ *
+ * Complexity: O(n) over completed jobs for batchKey + reverifyBatch;
+ * reportExists is O(d) where d = number of run subdirectories (bounded).
+ *
+ * @param {{ paused: object|null, jobs: Array }} state   Scheduler queue state.
+ * @param {{
+ *   cancelToken?: { cancelled: boolean },
+ *   prdsDir?:     string,
+ *   runsDir?:     string,
+ * }} opts
+ * @returns {Promise<void>}
+ */
+async function runDefinitionOfDoneOnDrain(state, opts = {}) {
+  const { cancelToken = {}, prdsDir, runsDir } = opts;
+
+  if (process.env.SM_DOD_DISABLE === '1') return;
+  if (state.paused) return;
+  if (cancelToken.cancelled) return;
+
+  const completedJobs = (state.jobs || []).filter(j => j.status === 'completed');
+  if (completedJobs.length === 0) return;
+
+  const key = batchKey(completedJobs);
+
+  if (reportExists(key, runsDir)) return;
+  if (_inFlight.has(key)) return;
+
+  _inFlight.add(key);
+  try {
+    const acResults = await reverifyBatch(completedJobs, { prdsDir });
+    // Re-check after the slow await — scheduler may have stopped mid-flight.
+    if (cancelToken.cancelled) return;
+    const riskFlags = flagRiskySurfaces(completedJobs, { prdsDir });
+    writeReport(key, { acResults, riskFlags, runsDir });
+  } finally {
+    _inFlight.delete(key);
+  }
+}
+
+module.exports = { runDefinitionOfDoneOnDrain };

package/src/main/scheduler.cjs

@@ -65,6 +65,7 @@ const {
   MAX_JOB_DURATION_MS,
 } = require('./lib/schedulerConfig.cjs');
 const { pickForProject, pickNextBatch, DEFAULT_PROJECT_CWD } = require('./lib/schedulerBatch.cjs');
+const { runDefinitionOfDoneOnDrain } = require('./lib/dodDrainHook.cjs');
 
 const MAX_INVESTIGATION_DURATION_MS = 30 * 60_000;
 
@@ -220,9 +221,27 @@ const ENV_CAP = process.env.SM_SCHEDULER_MAX_CONCURRENCY
   ? Math.max(1, Math.min(20, parseInt(process.env.SM_SCHEDULER_MAX_CONCURRENCY, 10) || 3))
   : null;
 
-// Each headless claude -p process can grow past 1 GB; require 1.5 GB headroom
-// per running+pending slot to avoid OOM (incident 2026-06-10).
-const MIN_FREE_MB_PER_JOB = 1500;
+// Each headless claude -p job can shell out to tsc/vite/pytest and grow well
+// past 1 GB at peak; reserve 2.5 GB per running+pending slot. Raised from 1.5 GB
+// after the 2026-06-16 OOM: 3 concurrent cross-project jobs + their build
+// subprocesses pushed a 24 GB host ~10 GB into swap and the OOM killer took
+// Electron — every pty got SIGHUP (code=0 signal=1).
+const MIN_FREE_MB_PER_JOB = 2500;
+
+// Absolute headroom kept free for the Electron host (main + renderer + GPU) and
+// the OS — NEVER lent to jobs. Without it the gate green-lights a job whenever
+// MemAvailable is just above per-job need, starving the very process that owns
+// the ptys; that's the one the OOM killer then reaps. Subtracted from
+// MemAvailable before the per-job gate runs. See availableForJobs().
+const RESERVED_HOST_MB = 3000;
+
+// oom_score_adj applied to each spawned claude -p job (range -1000..1000;
+// Electron inherits the default 0). A positive bias makes the kernel OOM killer
+// prefer a disposable, restartable job over Electron — whose death SIGHUPs every
+// pty and drops the sleep inhibitor. The job's build subprocesses (tsc/vite)
+// inherit it, so the actual memory hogs are the preferred victims. The gate caps
+// how many START; this decides who dies if a spike slips through anyway.
+const OOM_SCORE_ADJ_JOB = 500;
 
 const DEFAULT_CONFIG = {
   offsetMinutes: 15,
@@ -276,6 +295,33 @@ function memoryLimitedBatchSize(availableMb, minPerJob, runningCount, batchLen)
   return allowed;
 }
 
+/**
+ * Memory available to LAUNCH jobs with: MemAvailable minus the host reserve,
+ * floored at 0. Keeping the host reserve out of the job budget is what stops the
+ * gate from green-lighting a job into an OOM that kills Electron. Fails open
+ * (Infinity) on non-Linux where MemAvailable is unknown. Exported for tests.
+ */
+function availableForJobs(availableMb, reservedHostMb) {
+  if (availableMb === Infinity) return Infinity;
+  return Math.max(0, availableMb - reservedHostMb);
+}
+
+/**
+ * Bias a spawned job's oom_score_adj up so the kernel OOM killer sacrifices the
+ * (restartable) job before Electron. Raising a child's OWN score is privilege-
+ * free; lowering Electron's would need CAP_SYS_RESOURCE. Linux-only, best-effort
+ * — the job may have already exited (write ENOENTs), which is fine. See the
+ * 2026-06-16 OOM-kills-Electron incident.
+ */
+function biasJobOomScore(pid) {
+  if (process.platform !== 'linux' || !pid) return;
+  try {
+    fs.writeFileSync(`/proc/${pid}/oom_score_adj`, String(OOM_SCORE_ADJ_JOB));
+  } catch {
+    /* job already exited, or /proc unavailable — best-effort hardening only */
+  }
+}
+
 // ---------- fs helpers ----------
 
 /**
@@ -1037,6 +1083,8 @@ async function executeJob(job, runDir, defaultCwd, onPid) {
 
     if (child) {
       safeLog(`[scheduler] spawned pid=${child.pid} sessionId=${sessionId} (process group)\n\n`);
+      // Make this job the OOM killer's preferred victim over Electron.
+      biasJobOomScore(child.pid);
       // Fire-and-forget pid persistence — best effort.
       if (onPid) onPid(child.pid, sessionId, cwd).catch(() => {});
     }
@@ -1413,19 +1461,22 @@ async function spawnJob(job, runId, runDir, defaultCwd) {
     await broadcast();
 
     if (actuallyFailed && failedJobSnapshot) {
-      // Transient-failure detector: SIGTERM/SIGKILL within 45s = almost
-      // always external kill (user-initiated app restart, OOM-kill, manual
-      // process kill, Electron HMR). The PRD itself didn't fail; the run was
-      // interrupted before it could do meaningful work. Spawning an Opus
-      // investigator on these is wasted tokens AND pollutes the queue with
-      // redundant fix-PRDs (real example 2026-05-21: 07-agent-view-... got
-      // SIGTERMed at 10s by an app restart, the rename had already been done
-      // anyway). The 45s cutoff (was 30s) catches Electron-HMR borderline
-      // cases like PRD 26 SIGTERM'd at 33s — that was 3s over the old cutoff
-      // and fell through to a fix-PRD that just acknowledged the work was
-      // already done. Auto-retry up to 2x before falling through to investigation.
+      // Transient-failure detector. A 143/137 exit is ALWAYS a signal kill — the
+      // agent never self-exits with those — so the only question is WHO killed it.
+      // The scheduler's own intentional kills before the idle watchdog are the
+      // result-tail post-success kill (which maps back to exit 0, so it never
+      // reaches here) and the rare supervisor kill-agent. The idle-output
+      // watchdog only fires at IDLE_OUTPUT_KILL_MS (20 min) of stalled output,
+      // and the deadman at 4 h. THEREFORE any 143/137 with a run shorter than the
+      // idle threshold is an EXTERNAL/transient kill — an app restart (incl. our
+      // own self-restart on publish/HMR — see feedback 2026-06-15-01), an
+      // OOM-kill, or a manual kill — not a real failure. Re-queue it (bounded)
+      // instead of marking it failed + spawning a spurious fix-plan. (Was 45 s,
+      // which wrongly hard-failed externally-killed jobs like 115 SIGTERM'd at
+      // 67 s.) Genuine watchdog kills (idle ≥20 min, deadman 4 h) run longer than
+      // the threshold and still fall through to investigation.
       const ec = failedJobSnapshot.exitCode;
-      const transient = (ec === 143 || ec === 137) && res.durationMs < 45_000;
+      const transient = (ec === 143 || ec === 137) && res.durationMs < IDLE_OUTPUT_KILL_MS;
       const retries = failedJobSnapshot.transientRetries ?? 0;
       if (transient && retries < 2) {
         console.log(`[scheduler] transient failure (exit=${ec} dur=${res.durationMs}ms) — auto-retry ${retries + 1}/2 for ${job.slug}`);
@@ -1469,20 +1520,31 @@ function tickQueue() {
     await reconcile(state);
     const cap = ENV_CAP ?? state.config.concurrencyCap;
     const batch = pickNextBatch(state.jobs, runningSet, cap);
-    if (batch.length === 0) return;
+    if (batch.length === 0) {
+      // Queue drained — run the definition-of-done gate fire-and-forget.
+      // Non-blocking: does not hold the mutate lock; errors are logged, not thrown.
+      runDefinitionOfDoneOnDrain(state, { cancelToken }).catch((err) => {
+        console.log(`[scheduler] dod-drain: ${err?.message ?? String(err)}`);
+      });
+      return;
+    }
 
     const availableMb = getAvailableMemMb();
-    const allowed = memoryLimitedBatchSize(availableMb, MIN_FREE_MB_PER_JOB, runningSet.size, batch.length);
+    // Reserve a fixed slice for the Electron host before the per-job gate, so a
+    // job is never started into the host's own headroom (that path OOM-kills
+    // Electron and SIGHUPs every pty — 2026-06-16 incident).
+    const jobBudgetMb = availableForJobs(availableMb, RESERVED_HOST_MB);
+    const allowed = memoryLimitedBatchSize(jobBudgetMb, MIN_FREE_MB_PER_JOB, runningSet.size, batch.length);
     if (allowed === 0) {
-      const threshold = MIN_FREE_MB_PER_JOB * (runningSet.size + 1);
-      console.log(`[scheduler] memory gate: available=${availableMb} MB < threshold=${threshold} MB — deferring ${batch.length} job(s)`);
+      const threshold = RESERVED_HOST_MB + MIN_FREE_MB_PER_JOB * (runningSet.size + 1);
+      console.log(`[scheduler] memory gate: available=${availableMb} MB < threshold=${threshold} MB (host reserve ${RESERVED_HOST_MB} + ${MIN_FREE_MB_PER_JOB}/job × ${runningSet.size + 1}) — deferring ${batch.length} job(s)`);
       lastMemGate = { availableMb, threshold, deferred: true, at: new Date().toISOString() };
       return;
     }
     const gatedBatch = batch.slice(0, allowed);
     if (gatedBatch.length < batch.length) {
-      console.log(`[scheduler] memory gate: available=${availableMb} MB — clamped batch ${batch.length} → ${gatedBatch.length}`);
-      lastMemGate = { availableMb, threshold: MIN_FREE_MB_PER_JOB * (runningSet.size + gatedBatch.length), deferred: false, clamped: true, at: new Date().toISOString() };
+      console.log(`[scheduler] memory gate: available=${availableMb} MB — clamped batch ${batch.length} → ${gatedBatch.length} (host reserve ${RESERVED_HOST_MB} + ${MIN_FREE_MB_PER_JOB}/job)`);
+      lastMemGate = { availableMb, threshold: RESERVED_HOST_MB + MIN_FREE_MB_PER_JOB * (runningSet.size + gatedBatch.length), deferred: false, clamped: true, at: new Date().toISOString() };
     } else {
       // Ungated full batch: clear stale gate snapshot so status doesn't show
       // a stale deferral from a previous tick.
@@ -2153,6 +2215,7 @@ async function init() {
     for (const j of s.jobs) counts[j.status] = (counts[j.status] || 0) + 1;
     appendHeartbeat({
       ts: Date.now(),
+      pid: process.pid,
       counts,
       paused: s.paused ? { reason: s.paused.reason, resumeAt: s.paused.resumeAt } : null,
       nextReset: cachedNextReset,
@@ -2290,4 +2353,4 @@ const remote = {
   },
 };
 
-module.exports = { registerScheduleHandlers, attachWindow, init, ROOT, PRDS_DIR, selectHistoryJobs, parsePorcelain, FINISH_PROTOCOL, remote, pickNextBatch, pickForProject, reapDeadRunningJobs, pollRecoveryClearSource, memoryLimitedBatchSize, reverifyNeedsReview, isRescanCandidate };
+module.exports = { registerScheduleHandlers, attachWindow, init, ROOT, PRDS_DIR, selectHistoryJobs, parsePorcelain, FINISH_PROTOCOL, remote, pickNextBatch, pickForProject, reapDeadRunningJobs, pollRecoveryClearSource, memoryLimitedBatchSize, availableForJobs, reverifyNeedsReview, isRescanCandidate };

package/src/preload/api.d.ts

@@ -533,16 +533,17 @@ export interface RepoAnalyzeResult {
 }
 export interface RepoAnalyzeError { ok: false; error: string }
 
-export interface HiveRole { label: string; prompt: string }
-export interface Hive {
+export interface RecipeStep { agentName: string; note?: string }
+export interface Recipe {
   slug: string;
   name: string;
   description: string;
-  roles: HiveRole[];
-  defaultPlan?: string;
+  brief?: string;
+  steps: RecipeStep[];
 }
-export interface HiveListResult { hives: Hive[]; error: string | null }
-export interface HiveGetResult { hive: Hive | null; error: string | null }
+// Channel keeps legacy "hives" name; concept is now "recipe".
+export interface HiveListResult { hives: Recipe[]; error: string | null }
+export interface HiveGetResult { hive: Recipe | null; error: string | null }
 export interface HiveMutationResult { ok: boolean; error: string | null }
 
 export interface WatcherInfo {
@@ -975,7 +976,7 @@ export interface SessionManagerAPI {
   hives: {
     list: () => Promise<HiveListResult>;
     get: (slug: string) => Promise<HiveGetResult>;
-    save: (slug: string, hive: Hive) => Promise<HiveMutationResult>;
+    save: (slug: string, hive: Recipe) => Promise<HiveMutationResult>;
     delete: (slug: string) => Promise<HiveMutationResult>;
   };
   history: {