brainiac 0.0.32 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 484a1d79de556a1d190c22cbafe8db117c24e54f7a051c2a3fb4884b9979f435
-  data.tar.gz: c170d7271b21aa627f2e591f261628c3abfe731de1cef5c65581e23f4118f46f
+  metadata.gz: 82f144b517fd0197684d1912858134c0a6b440263cf2e6bb43d1c4e2651aec3a
+  data.tar.gz: 415ae3b9fad9b4d407e13147ce0c28286b8292897175f45c37d39b4dfbf2cccd
 SHA512:
-  metadata.gz: 78f90db425eaa92c1b3f4718845ea7449a6e267f86bad4873147d01625bf3759180f8f121521ed0ab70fc9c72563e6c4ca8f367dcf6364e91774623588cff911
-  data.tar.gz: 9ef305db5eb93589935780ef5a1bcd4063e018d86522a825fb500d3ff0e023ca1e145154196a92c768c934d2dcf9c4a77c4ef67ce729d0e93a537e8c91bf1d1a
+  metadata.gz: 567146d407026c606a08a9c3d592059a43f195f9785318d3763ad368aab002d16153a2b442cf778a06513b231327552201f71b1d7bb2680036214f0cf842e5cc
+  data.tar.gz: a41c6857915e2e9493f45fa0d49755e4958d6c4de6175a7171d7e25a8013ac3b3f498a7ab1933021c09b0bf3a5768bd1542176d59a0e4ad680e186ce7af74545

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    brainiac (0.0.32)
+    brainiac (0.1.0)
       puma (~> 7.2)
       rackup (~> 2.3)
       sinatra (~> 4.1)
@@ -11,22 +11,22 @@ GEM
   specs:
     ast (2.4.3)
     base64 (0.3.0)
-    json (2.19.9)
-    language_server-protocol (3.17.0.5)
+    json (2.21.2)
+    language_server-protocol (3.17.0.6)
     lint_roller (1.1.0)
     logger (1.7.0)
     minitest (5.27.0)
     mustermann (3.1.1)
     nio4r (2.7.5)
-    parallel (2.1.0)
-    parser (3.3.11.1)
+    parallel (2.2.0)
+    parser (3.3.12.0)
       ast (~> 2.4.1)
       racc
     prism (1.9.0)
     puma (7.2.1)
       nio4r (~> 2.0)
     racc (1.8.1)
-    rack (3.2.6)
+    rack (3.2.7)
     rack-protection (4.2.1)
       base64 (>= 0.1.0)
       logger (>= 1.6.0)
@@ -50,7 +50,7 @@ GEM
       rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.49.1)
+    rubocop-ast (1.50.0)
       parser (>= 3.3.7.2)
       prism (~> 1.7)
     rubocop-performance (1.26.1)
@@ -65,7 +65,7 @@ GEM
       rack-protection (= 4.2.1)
       rack-session (>= 2.0.0, < 3)
       tilt (~> 2.0)
-    tilt (2.7.0)
+    tilt (2.9.0)
     unicode-display_width (3.2.0)
       unicode-emoji (~> 4.1)
     unicode-emoji (4.2.0)
@@ -84,20 +84,20 @@ DEPENDENCIES
 CHECKSUMS
   ast (2.4.3) sha256=954615157c1d6a382bc27d690d973195e79db7f55e9765ac7c481c60bdb4d383
   base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
-  brainiac (0.0.32)
-  json (2.19.9) sha256=9b9025b7cdddafa38d316eca0b2358488e42d417045c1b90d216a9fefe46b79a
-  language_server-protocol (3.17.0.5) sha256=fd1e39a51a28bf3eec959379985a72e296e9f9acfce46f6a79d31ca8760803cc
+  brainiac (0.1.0)
+  json (2.21.2) sha256=1f1d3b7cf2b3ba1a69beca0bb6db13d5438b80bff3cd54cdaaa620b9b07c1c6a
+  language_server-protocol (3.17.0.6) sha256=5ef2c0c138f8267e1bc631d3328347d354f96724b0af22f2c79516120443b7f0
   lint_roller (1.1.0) sha256=2c0c845b632a7d172cb849cc90c1bce937a28c5c8ccccb50dfd46a485003cc87
   logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
   minitest (5.27.0) sha256=2d3b17f8a36fe7801c1adcffdbc38233b938eb0b4966e97a6739055a45fa77d5
   mustermann (3.1.1) sha256=4c6170c7234d5499c345562ba7c7dfe73e1754286dcc1abb053064d66a127198
   nio4r (2.7.5) sha256=6c90168e48fb5f8e768419c93abb94ba2b892a1d0602cb06eef16d8b7df1dca1
-  parallel (2.1.0) sha256=b35258865c2e31134c5ecb708beaaf6772adf9d5efae28e93e99260877b09356
-  parser (3.3.11.1) sha256=d17ace7aabe3e72c3cc94043714be27cc6f852f104d81aa284c2281aecc65d54
+  parallel (2.2.0) sha256=e1059c5fd7b649558a0aec38a769f06a42942bdb40503d005a59c352fe011cd8
+  parser (3.3.12.0) sha256=21a6d7f755d5a24dfbdc6e6b772e4e879a52e7631a88bc5a3a134606052c9828
   prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85
   puma (7.2.1) sha256=d7bf0e9cabd532e0d401e142cd94e3ac531e993610e2d80e6fbf9c26961414b0
   racc (1.8.1) sha256=4a7f6929691dbec8b5209a0b373bc2614882b55fc5d2e447a21aaa691303d62f
-  rack (3.2.6) sha256=5ed78e1f73b2e25679bec7d45ee2d4483cc4146eb1be0264fc4d94cb5ef212c2
+  rack (3.2.7) sha256=93e13e1c24f93556671d85d2d79fa228c3485815c50d7e2f265b5330c6528fb7
   rack-protection (4.2.1) sha256=cf6e2842df8c55f5e4d1a4be015e603e19e9bc3a7178bae58949ccbb58558bac
   rack-session (2.1.2) sha256=595434f8c0c3473ae7d7ac56ecda6cc6dfd9d37c0b2b5255330aa1576967ffe8
   rackup (2.3.1) sha256=6c79c26753778e90983761d677a48937ee3192b3ffef6bc963c0950f94688868
@@ -105,11 +105,11 @@ CHECKSUMS
   rake (13.4.2) sha256=cb825b2bd5f1f8e91ca37bddb4b9aaf345551b4731da62949be002fa89283701
   regexp_parser (2.12.0) sha256=35a916a1d63190ab5c9009457136ae5f3c0c7512d60291d0d1378ba18ce08ebb
   rubocop (1.88.0) sha256=e420ddf1662d0ef34bc8a2910ac4b396a7ddda0b51a708264405241734b08e0b
-  rubocop-ast (1.49.1) sha256=4412f3ee70f6fe4546cc489548e0f6fcf76cafcfa80fa03af67098ffed755035
+  rubocop-ast (1.50.0) sha256=b9ca88300da0803ee222ad20cdb30494c0a784eed06fdc35d254b06d662788db
   rubocop-performance (1.26.1) sha256=cd19b936ff196df85829d264b522fd4f98b6c89ad271fa52744a8c11b8f71834
   ruby-progressbar (1.13.0) sha256=80fc9c47a9b640d6834e0dc7b3c94c9df37f08cb072b7761e4a71e22cff29b33
   sinatra (4.2.1) sha256=b7aeb9b11d046b552972ade834f1f9be98b185fa8444480688e3627625377080
-  tilt (2.7.0) sha256=0d5b9ba69f6a36490c64b0eee9f6e9aad517e20dcc848800a06eb116f08c6ab3
+  tilt (2.9.0) sha256=da5735d0280bba96e9a91041bb14aee435ccad5c17b0fa519249ae543d9aa3a5
   unicode-display_width (3.2.0) sha256=0cdd96b5681a5949cdbc2c55e7b420facae74c4aaf9a9815eee1087cb1853c42
   unicode-emoji (4.2.0) sha256=519e69150f75652e40bf736106cfbc8f0f73aa3fb6a65afe62fefa7f80b0f80f
 

data/README.md

@@ -1270,6 +1270,32 @@ curl "http://localhost:4567/api/gif?q=excited"              # Search for GIFs (r
 curl http://localhost:4567/api/cron                         # Cron jobs and thread status
 curl http://localhost:4567/api/logs                         # Read log files
 curl http://localhost:4567/api/status                       # Active agent sessions (used by monitor)
+curl "http://localhost:4567/api/sessions/history?limit=25"  # Durable session history (survives restarts)
+```
+
+### Session History
+
+`/api/status` returns only *live* sessions plus the last 10 finished ones held in memory
+(wiped on every restart). For durable, restart-surviving history use
+`GET /api/sessions/history?limit=N`, backed by an append-only JSONL log at
+`~/.brainiac/session-history.jsonl`.
+
+Every finished agent session is recorded with timing, identity (agent, CLI, model, source),
+exit status, and — where the provider exposes it — **session heaviness**: context window
+usage and credits spent. Heaviness is captured at completion time via a provider-specific
+probe that is **declared in the provider config**, not hardcoded in brainiac. Add a
+`heaviness_probe` block to `~/.brainiac/cli-providers/<name>.json`:
+
+```json
+"heaviness_probe": { "type": "kiro_sqlite", "db_path": "~/.local/share/kiro-cli/data.sqlite3" }
+```
+
+`type` selects the probe strategy and `db_path` points at the provider's local usage store,
+so enabling/disabling a provider or moving its data store is pure JSON. kiro-cli ships with a
+`kiro_sqlite` probe (reads its local conversation sqlite, read-only). A genuinely new storage
+mechanism needs a small probe implementation in `lib/brainiac/session_history.rb`; providers
+with no `heaviness_probe` simply record timing + identity. The file is trimmed to the most
+recent 500 records.
 ```
 
 ## Development

data/lib/brainiac/helpers.rb

@@ -32,8 +32,10 @@ def load_cli_provider(provider_name)
   config["prompt_mode"] = raw["prompt_mode"] || "stdin"
   # Copy optional fields from raw config when present.
   # Each field controls a specific CLI behavior — see comments in the template.
-  %w[prompt_flag list_models_command resume_flag resume_args session_dir output_last_message_flag
-     cwd_flag config_override_flag effort_config_key effort_map].each do |key|
+  %w[prompt_flag list_models_command resume_flag resume_args resume_id_flag new_session_id_flag
+     session_list_command session_id_field session_directory_field session_updated_field
+     session_list_path session_dir output_last_message_flag cwd_flag config_override_flag
+     effort_config_key effort_map title_flag heaviness_probe].each do |key|
     next unless raw[key]
     next if raw[key].respond_to?(:empty?) && raw[key].empty?
 
@@ -247,6 +249,67 @@ def find_work_item_by_card(card_internal_id)
   nil
 end
 
+# Find a work item by worktree path. Returns [work_item_id, info] or nil.
+# Compares realpaths so symlink worktrees still match.
+def find_work_item_by_worktree(worktree)
+  return nil unless worktree
+
+  target = path_for_compare(worktree)
+  return nil unless target
+
+  map = load_work_item_map
+  map.each do |work_item_id, info|
+    next unless info.is_a?(Hash) && info["worktree"]
+    next unless path_for_compare(info["worktree"]) == target
+
+    return [work_item_id, info]
+  end
+  nil
+end
+
+def path_for_compare(path)
+  return nil unless path
+
+  File.realpath(path)
+rescue StandardError
+  File.expand_path(path.to_s)
+end
+
+# Key used in work_item["cli_sessions"] — the CLI binary basename (e.g. "opencode").
+def cli_session_key(agent_cli)
+  return nil if agent_cli.nil? || agent_cli.to_s.empty?
+
+  File.basename(agent_cli.to_s)
+end
+
+# Stored OpenCode/CLI session id for this work item + CLI, or nil.
+def cli_session_id_for(agent_cli:, worktree: nil, work_item_id: nil)
+  key = cli_session_key(agent_cli)
+  return nil unless key
+
+  info = find_work_item_by_id(work_item_id) if work_item_id
+  info ||= find_work_item_by_worktree(worktree)&.last
+  info&.dig("cli_sessions", key)
+end
+
+# Persist a CLI session id on the work item, keyed by CLI binary name.
+# Returns true if stored, false if no matching work item.
+def update_work_item_cli_session(agent_cli:, session_id:, worktree: nil, work_item_id: nil) # rubocop:disable Naming/PredicateMethod
+  key = cli_session_key(agent_cli)
+  return false unless key && session_id && !session_id.to_s.empty?
+
+  map = load_work_item_map
+  target_id = work_item_id
+  target_id ||= find_work_item_by_worktree(worktree)&.first
+  return false unless target_id && map[target_id]
+
+  map[target_id]["cli_sessions"] ||= {}
+  map[target_id]["cli_sessions"][key] = session_id.to_s
+  save_work_item_map(map)
+  LOG.info "[WorkItem] Stored #{key} session #{session_id} on #{target_id}"
+  true
+end
+
 # Register a new work item or update an existing one.
 # Returns the work item ID.
 def register_work_item(branch:, worktree: nil, project: nil, agent: nil, source: nil, source_data: {})
@@ -444,6 +507,74 @@ rescue StandardError => e
   nil
 end
 
+# Detect when an agent exited cleanly (exit 0) but produced no usable response.
+# This covers cases the crash path misses because the exit code is 0 — most notably a
+# CLI that prints a request/usage-limit notice and exits without doing any work.
+#
+# Returns a short human-readable reason string when the session yielded no response,
+# or nil when the session did produce output (i.e. nothing to surface).
+#
+# @param log_file [String, nil] Path to the agent's log file
+# @param output_content [String, nil] Structured output captured via --output-last-message, if any
+NO_OUTPUT_LIMIT_PATTERNS = [
+  /\bmonthly request limit reached\b/i,
+  /\brequest limit reached\b/i,
+  /\busage limit\b/i,
+  /\brate limit(?:ed|ing)?\b/i,
+  /\bquota (?:exceeded|reached)\b/i,
+  /\btoo many requests\b/i
+].freeze
+
+def detect_no_output_reason(log_file, output_content)
+  # If we captured a structured response, the session clearly produced output.
+  return nil if output_content && !output_content.strip.empty?
+
+  tail = extract_crash_snippet(log_file, max_lines: 40)
+  return nil if tail.nil?
+
+  limit_line = tail.lines.map(&:strip).reverse.find do |line|
+    NO_OUTPUT_LIMIT_PATTERNS.any? { |re| line.match?(re) }
+  end
+  return "hit a request/usage limit: #{limit_line}" if limit_line
+
+  # No structured output and no recognizable limit notice. Treat a log that carries no
+  # assistant text as "produced no response" so the channel isn't left silent. We can't
+  # parse every CLI's transcript here, so this is best-effort: only flag when the log is
+  # effectively empty of content beyond startup/boilerplate lines.
+  meaningful = tail.lines.map(&:strip).reject do |line|
+    line.empty? ||
+      line.start_with?("---", "▸") ||
+      line.match?(/all tools are now trusted/i) ||
+      line.match?(/mcp server did not load/i) ||
+      line.match?(/agents can sometimes do unexpected things/i) ||
+      line.match?(%r{learn more at https?://}i)
+  end
+  return "produced no response (log contained no agent output)" if meaningful.empty?
+
+  nil
+end
+
+# Surface a clean-exit-but-no-response session to the originating channel. Reuses the
+# crash notification delivery path (the :agent_crashed hook) so plugins deliver it the
+# same way they deliver failures, but frames it as "no response" rather than a crash.
+def notify_agent_no_output(reason:, log_file:, agent_name:, source:, source_context:, project_config:)
+  agent_display = agent_name || "Agent"
+  snippet = extract_crash_snippet(log_file)
+
+  handled = Brainiac.emit(:agent_crashed,
+                          exit_status: 0, log_file: log_file, agent_name: agent_display,
+                          source: source, source_context: source_context, project_config: project_config,
+                          snippet: snippet, no_output: true, no_output_reason: reason)
+
+  if handled.any?
+    LOG.info "[NoOutput] #{agent_display} #{reason} — notified via #{source}"
+  else
+    LOG.warn "[NoOutput] #{agent_display} #{reason} but no plugin handled notification (source: #{source})"
+  end
+rescue StandardError => e
+  LOG.error "[NoOutput] Unexpected error: #{e.message}"
+end
+
 # Notify the originating channel that an agent crashed.
 # source: :github, :discord, or plugin-registered sources
 # source_context: hash with channel-specific info needed to post the notification
@@ -561,11 +692,24 @@ end
 def resume_viable?(project_config:, cli_provider: nil, agent_name: nil, chdir: nil)
   resolved = resolve_project_cli_config(project_config, cli_provider_override: cli_provider, agent_name: agent_name)
   chdir ||= resolved["repo_path"]
+  return stored_cli_session_viable?(resolved, chdir) if resolved["resume_id_flag"]
   return false unless resolved["resume_flag"] || resolved["resume_args"]
 
   prior_session_exists?(chdir, resolved["agent_cli"], session_dir: resolved["session_dir"])
 end
 
+# True when this CLI resumes by session id AND the work item has a still-existing id.
+def stored_cli_session_viable?(resolved, chdir)
+  session_id = cli_session_id_for(agent_cli: resolved["agent_cli"], worktree: chdir)
+  return false if session_id.to_s.empty?
+  return true unless resolved["session_list_command"]
+
+  sessions = list_cli_sessions(resolved["session_list_command"], **session_list_fields(resolved))
+  return false unless sessions
+
+  sessions.any? { |s| s["id"] == session_id }
+end
+
 # Determine whether a session resume should actually happen.
 # Called by run_agent — plugins should NOT call this directly; pass `resume: true` to run_agent.
 #
@@ -573,8 +717,19 @@ end
 #   - :resume_args — when the provider uses subcommand-based resume (build_agent_cmd replaces default_args)
 #   - String (the resume flag) — when the provider uses flag-based resume (appended to cmd)
 #   - false — when resume was not requested or not viable
-def resolve_resume(resume, resolved, chdir)
-  return false unless resume && (resolved["resume_flag"] || resolved["resume_args"])
+def resolve_resume(resume, resolved, chdir, session_id: nil)
+  return false unless resume
+
+  if resolved["resume_id_flag"]
+    id = session_id.to_s.empty? ? cli_session_id_for(agent_cli: resolved["agent_cli"], worktree: chdir) : session_id
+    if id.to_s.empty?
+      LOG.info "[Dispatch] Resume requested but no stored #{resolved["agent_cli"]} session for #{chdir} — starting fresh"
+      return false
+    end
+    return { "flag" => resolved["resume_id_flag"], "id" => id }
+  end
+
+  return false unless resolved["resume_flag"] || resolved["resume_args"]
   if prior_session_exists?(chdir, resolved["agent_cli"], session_dir: resolved["session_dir"])
     # Return :resume_args when the provider uses subcommand-based resume (e.g. Codex exec resume)
     return resolved["resume_args"] ? :resume_args : resolved["resume_flag"]
@@ -584,6 +739,16 @@ def resolve_resume(resume, resolved, chdir)
   false
 end
 
+# Some CLIs (e.g. grok --session-id) let the caller name a new session up front.
+# Mint a UUID only on the first run, when we are not resuming an existing id.
+def mint_cli_session_id(resolved, stored_session:, resuming:)
+  return nil if resuming
+  return nil unless resolved["new_session_id_flag"]
+  return nil unless stored_session.to_s.empty?
+
+  SecureRandom.uuid
+end
+
 # Check if intent detection says to skip dispatching the agent.
 # Returns true if the message should be skipped, false otherwise.
 # Only runs if a raw message is provided, an agent is named, and intent is enabled.
@@ -619,8 +784,12 @@ def run_agent(prompt, project_config:, chdir: nil, log_name: "agent", model: nil
   effort ||= resolved["agent_effort"]
   agent_config_name = agent_name&.downcase&.gsub(/[^a-z0-9-]/, "-")
 
+  stored_session = cli_session_id_for(agent_cli: resolved["agent_cli"], worktree: chdir)
+  work_item_id = find_work_item_by_worktree(chdir)&.first
+
   # Auto-resume: only if the provider supports it AND a prior session exists for this CLI here.
-  should_resume = resolve_resume(resume, resolved, chdir)
+  should_resume = resolve_resume(resume, resolved, chdir, session_id: stored_session)
+  minted_session_id = mint_cli_session_id(resolved, stored_session: stored_session, resuming: should_resume)
 
   # Pre-dispatch hook — plugins can prep the working directory (e.g., copy config files, clean up)
   Brainiac.emit(:pre_dispatch, chdir: chdir, project_config: project_config, agent_name: agent_name)
@@ -634,37 +803,31 @@ def run_agent(prompt, project_config:, chdir: nil, log_name: "agent", model: nil
 
   cmd = build_agent_cmd(resolved, agent_config_name: agent_config_name, model: model, effort: effort,
                                   prompt_file: prompt_file, resume: should_resume,
-                                  output_file: output_file, chdir: chdir)
-  prompt_mode = resolved["prompt_mode"] || "stdin"
-
+                                  output_file: output_file, chdir: chdir, title: work_item_id,
+                                  new_session_id: minted_session_id)
   spawn_env = agent_env_for(agent_name).merge(env)
 
-  LOG.info "Running #{resolved["agent_cli"]} in #{chdir}, logging to #{log_file}"
-  LOG.info "Prompt: #{prompt_file} | Output: #{output_file || "none"} | Command: #{cmd.join(" ")}#{" (resuming session)" if should_resume}"
-  LOG.info "Injecting #{spawn_env.size} env var(s) for agent #{agent_name}: #{spawn_env.keys.join(", ")}" unless spawn_env.empty?
+  log_agent_launch(resolved: resolved, chdir: chdir, log_file: log_file, prompt_file: prompt_file,
+                   output_file: output_file, cmd: cmd, should_resume: should_resume,
+                   spawn_env: spawn_env, agent_name: agent_name)
 
   project_key_for_restart = PROJECTS.find { |_k, v| v == project_config }&.first
   head_before, status_before = capture_git_state(chdir) if project_key_for_restart == "brainiac"
 
-  pid = spawn(spawn_env, *cmd,
-              chdir: chdir,
-              **(prompt_mode == "stdin" ? { in: prompt_file } : {}),
-              out: [log_file, "w"],
-              err: %i[child out])
-
-  Thread.new do
-    Process.wait(pid)
-    handle_agent_completion(
-      pid: pid, agent_cli: resolved["agent_cli"], agent_config_name: agent_config_name,
-      agent_name: agent_name, log_file: log_file, log_name: log_name,
-      prompt_file: prompt_file, chdir: chdir, source: source,
-      source_context: source_context, project_config: project_config,
-      card_number: card_number, skip_column_move: skip_column_move,
-      output_file: output_file,
-      head_before: head_before, status_before: status_before,
-      project_key_for_restart: project_key_for_restart
-    )
-  end
+  started_at = Time.now
+  stdin_redirect = (resolved["prompt_mode"] || "stdin") == "stdin" ? { in: prompt_file } : {}
+  pid = spawn(spawn_env, *cmd, chdir: chdir, **stdin_redirect, out: [log_file, "w"], err: %i[child out])
+
+  spawn_completion_watcher(
+    pid: pid, agent_cli: resolved["agent_cli"], agent_config_name: agent_config_name,
+    agent_name: agent_name, log_file: log_file, log_name: log_name,
+    prompt_file: prompt_file, chdir: chdir, source: source,
+    source_context: source_context, project_config: project_config,
+    card_number: card_number, skip_column_move: skip_column_move,
+    output_file: output_file, resolved: resolved, minted_session_id: minted_session_id,
+    head_before: head_before, status_before: status_before,
+    project_key_for_restart: project_key_for_restart, model: model, started_at: started_at
+  )
 
   LOG.info "#{resolved["agent_cli"]} started (pid: #{pid}, agent: #{agent_config_name || "default"}, " \
            "model: #{model || "default"}), tail -f #{log_file}"
@@ -672,6 +835,28 @@ def run_agent(prompt, project_config:, chdir: nil, log_name: "agent", model: nil
   [pid, log_file]
 end
 
+# Spawn a background thread that waits for the agent process to finish and runs completion handling.
+def spawn_completion_watcher(**ctx)
+  thread = Thread.new do
+    Process.wait(ctx[:pid])
+    handle_agent_completion(**ctx)
+  end
+  # Without this, an unrescued exception anywhere in handle_agent_completion silently
+  # kills the thread and is never logged — which previously hid completion-path failures
+  # (e.g. a step raising before session history was archived).
+  thread.report_on_exception = true
+  thread
+end
+
+# Log the details of an agent launch (command, prompt/output files, injected env).
+def log_agent_launch(resolved:, chdir:, log_file:, prompt_file:, output_file:, cmd:, should_resume:, spawn_env:, agent_name:)
+  LOG.info "Running #{resolved["agent_cli"]} in #{chdir}, logging to #{log_file}"
+  LOG.info "Prompt: #{prompt_file} | Output: #{output_file || "none"} | Command: #{cmd.join(" ")}#{" (resuming session)" if should_resume}"
+  return if spawn_env.empty?
+
+  LOG.info "Injecting #{spawn_env.size} env var(s) for agent #{agent_name}: #{spawn_env.keys.join(", ")}"
+end
+
 # Write agent prompt to a temp file, return path.
 def write_agent_prompt_file(prompt, log_name, timestamp)
   prompt_dir = File.join(BRAINIAC_DIR, "tmp")
@@ -717,7 +902,8 @@ end
 # When chdir is provided and the provider has a cwd_flag, appends it so the CLI
 # itself switches to the working directory (e.g. `codex -C /path/to/project`).
 # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
-def build_agent_cmd(resolved, agent_config_name: nil, model: nil, effort: nil, prompt_file: nil, resume: false, output_file: nil, chdir: nil)
+def build_agent_cmd(resolved, agent_config_name: nil, model: nil, effort: nil, prompt_file: nil, resume: false,
+                    output_file: nil, chdir: nil, title: nil, new_session_id: nil)
   cmd = [resolved["agent_cli"]]
   # cwd_flag: pass the working directory as a CLI argument (e.g. -C for Codex CLI).
   # This is added early so it appears before subcommands/args (global option).
@@ -730,25 +916,44 @@ def build_agent_cmd(resolved, agent_config_name: nil, model: nil, effort: nil, p
   # e.g. "exec --full-auto" becomes "exec resume --last --full-auto"
   args = resume == :resume_args && resolved["resume_args"] ? resolved["resume_args"] : resolved["agent_cli_args"]
   cmd.concat(args.split)
-  # Only pass --model if the model is a valid ID for this provider.
-  # "auto" means "let the CLI choose" — skip passing it unless the provider explicitly maps it.
-  if model && resolved["agent_model_flag"] && !resolved["agent_model_flag"].empty?
-    allowed = resolved["allowed_models"] || {}
-    # If the model is a key in allowed_models, use the mapped value (e.g. "auto" -> "o4-mini")
-    # This handles cases where different projects use "auto" but each CLI provider maps it differently.
-    effective_model = allowed.key?(model) ? allowed[model] : model
-    is_known = allowed.value?(effective_model) || allowed.key?(effective_model)
-    cmd.push(resolved["agent_model_flag"], effective_model) if is_known
-  end
+  append_model_to_cmd(cmd, model, resolved)
   append_effort_to_cmd(cmd, effort, resolved) if effort
-  # Resume via flag (simple append, e.g. grok -c or kiro --resume) — only when not using resume_args
-  cmd.push(resume) if resume && resume != :resume_args && resume.is_a?(String)
+  cmd.push(resolved["title_flag"], title) if title && resolved["title_flag"]
+  if new_session_id && resolved["new_session_id_flag"] && !(resume.is_a?(Hash) || resume.is_a?(String) || resume == :resume_args)
+    cmd.push(resolved["new_session_id_flag"], new_session_id)
+  end
+  append_resume_to_cmd(cmd, resume)
   # prompt_mode: "flag" passes the prompt file path via the configured prompt_flag (e.g. --prompt-file).
   cmd.push(resolved["prompt_flag"], prompt_file) if prompt_file && resolved["prompt_mode"] == "flag" && resolved["prompt_flag"]
   # output_last_message_flag: capture the agent's final message to a file (e.g. codex exec -o <path>).
   cmd.push(resolved["output_last_message_flag"], output_file) if output_file && resolved["output_last_message_flag"]
   cmd
 end
+
+# Append the --model flag when a valid model ID is resolved for this provider.
+# "auto" means "let the CLI choose" — skip passing it unless the provider maps it.
+def append_model_to_cmd(cmd, model, resolved)
+  return unless model && resolved["agent_model_flag"] && !resolved["agent_model_flag"].empty?
+
+  allowed = resolved["allowed_models"] || {}
+  # If the model is a key in allowed_models, use the mapped value (e.g. "auto" -> "o4-mini").
+  # This handles cases where different projects use "auto" but each CLI provider maps it differently.
+  effective_model = allowed.key?(model) ? allowed[model] : model
+  is_known = allowed.value?(effective_model) || allowed.key?(effective_model)
+  cmd.push(resolved["agent_model_flag"], effective_model) if is_known
+end
+
+# Resume via --session <id> (OpenCode), a bare flag (grok -c), or resume_args (already applied).
+def append_resume_to_cmd(cmd, resume)
+  case resume
+  when Hash
+    flag = resume["flag"] || resume[:flag]
+    id = resume["id"] || resume[:id]
+    cmd.push(flag, id) if flag && id
+  when String
+    cmd.push(resume)
+  end
+end
 # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
 # Map a Brainiac effort level through the provider's effort_map (if any).
@@ -778,23 +983,130 @@ def append_effort_to_cmd(cmd, effort, resolved)
   end
 end
 
-# Append --model flag if the model is valid for this provider.
+# Parse a CLI session list as JSON, ignoring non-JSON prefixes (e.g. mise).
+# Normalizes OpenCode `{id, directory, updated}` and kiro `{sessionId, cwd, updatedAt}`
+# (including kiro's `[{cwd, sessions: [...]}]` envelopes) into a flat array of
+# `{ "id", "directory", "updated" }` hashes. Provider JSON can override field names.
+def parse_session_list_output(output, id_field: nil, directory_field: nil, updated_field: nil, list_path: nil)
+  return nil if output.nil? || output.strip.empty?
+
+  json_start = output.index("[") || output.index("{")
+  return nil unless json_start
+
+  data = JSON.parse(output[json_start..])
+  rows = data.is_a?(Array) ? data : Array(data["sessions"] || data["data"])
+  return nil unless rows.is_a?(Array)
+
+  flatten_session_rows(rows, id_field: id_field, directory_field: directory_field,
+                             updated_field: updated_field, list_path: list_path)
+rescue JSON::ParserError
+  nil
+end
+
+def flatten_session_rows(rows, id_field: nil, directory_field: nil, updated_field: nil, list_path: nil)
+  nested_key = list_path.to_s.empty? ? "sessions" : list_path
+  fields = { id_field: id_field, directory_field: directory_field, updated_field: updated_field }
+  rows.flat_map do |row|
+    next [] unless row.is_a?(Hash)
+
+    nested = row[nested_key]
+    if nested.is_a?(Array)
+      parent_dir = session_value(row, directory_field, %w[directory dir cwd])
+      nested.filter_map { |item| normalize_session_row(item, parent_dir: parent_dir, **fields) }
+    else
+      [normalize_session_row(row, **fields)].compact
+    end
+  end
+end
+
+def normalize_session_row(row, id_field: nil, directory_field: nil, updated_field: nil, parent_dir: nil)
+  return nil unless row.is_a?(Hash)
+
+  id = session_value(row, id_field, %w[id sessionId session_id])
+  return nil if id.to_s.empty?
+
+  {
+    "id" => id.to_s,
+    "directory" => session_value(row, directory_field, %w[directory dir cwd]) || parent_dir,
+    "updated" => session_value(row, updated_field, %w[updated time_updated updatedAt updated_at]) || 0
+  }
+end
+
+def session_value(row, explicit_field, fallbacks)
+  return row[explicit_field] if explicit_field && !explicit_field.to_s.empty? && row.key?(explicit_field)
+
+  fallbacks.each { |key| return row[key] if row.key?(key) }
+  nil
+end
+
+def session_list_fields(resolved)
+  {
+    id_field: resolved["session_id_field"],
+    directory_field: resolved["session_directory_field"],
+    updated_field: resolved["session_updated_field"],
+    list_path: resolved["session_list_path"]
+  }
+end
+
+def list_cli_sessions(command, **fields)
+  stdout, stderr, status = Open3.capture3(command)
+  unless status.success?
+    LOG.warn "[Session] session_list_command failed (exit #{status.exitstatus}): #{stderr.strip}"
+    return nil
+  end
+
+  parse_session_list_output(stdout, **fields)
+end
+
+# Most recently updated session whose directory matches chdir.
+# If no session has a directory (CLI already scoped the list to cwd), pick the newest overall.
+def select_session_id_for_directory(sessions, chdir)
+  return nil if sessions.nil? || sessions.empty?
+
+  with_ids = sessions.select { |session| session.is_a?(Hash) && !session["id"].to_s.empty? }
+  return nil if with_ids.empty?
+
+  if chdir
+    target = path_for_compare(chdir)
+    matching = with_ids.select { |session| session["directory"] && path_for_compare(session["directory"]) == target }
+    with_ids = matching unless matching.empty?
+  end
+
+  newest = with_ids.max_by { |session| session["updated"] || 0 }
+  newest && newest["id"]
+end
+
+# After a run, remember the CLI session id on the work item so later dispatches
+# can pass --session/--resume-id <id> instead of continuing whichever session was last globally.
+def capture_cli_session_id(resolved:, chdir:, minted_session_id: nil)
+  if minted_session_id
+    update_work_item_cli_session(agent_cli: resolved["agent_cli"], session_id: minted_session_id, worktree: chdir)
+    return
+  end
+  return unless resolved["session_list_command"] && resolved["resume_id_flag"]
+
+  sessions = list_cli_sessions(resolved["session_list_command"], **session_list_fields(resolved))
+  session_id = select_session_id_for_directory(sessions, chdir)
+  unless session_id
+    LOG.info "[Session] No CLI session found for #{chdir}"
+    return
+  end
+
+  update_work_item_cli_session(agent_cli: resolved["agent_cli"], session_id: session_id, worktree: chdir)
+end
+
 def handle_agent_completion(**ctx)
   agent_exit_status = $CHILD_STATUS.exitstatus
   agent_signaled = $CHILD_STATUS.signaled?
   LOG.info "#{ctx[:agent_cli]} finished (pid: #{ctx[:pid]}, exit: #{agent_exit_status})"
 
-  if ctx[:source] && agent_exit_status && agent_exit_status != 0 && !agent_signaled
-    notify_agent_crash(
-      exit_status: agent_exit_status, log_file: ctx[:log_file],
-      agent_name: ctx[:agent_name], source: ctx[:source], source_context: ctx[:source_context],
-      project_config: ctx[:project_config]
-    )
-  end
+  notify_crash_if_needed(ctx, agent_exit_status, agent_signaled)
 
   # Read structured output if the provider wrote to an output file (--output-last-message).
   output_content = read_output_file(ctx[:output_file])
 
+  capture_session_id_if_possible(ctx)
+
   # Emit lifecycle hook — plugins handle post-session actions (e.g., plugin moves card, appends footer)
   Brainiac.emit(:agent_completed,
                 card_number: ctx[:card_number] || ctx[:source_context]&.dig(:card_number),
@@ -813,22 +1125,96 @@ def handle_agent_completion(**ctx)
   # Clean up the output file after hook emission (content already captured above).
   FileUtils.rm_f(ctx[:output_file]) if ctx[:output_file]
 
+  run_post_completion_steps(ctx, exit_status: agent_exit_status, signaled: agent_signaled, output_content: output_content)
+end
+
+# Independent, best-effort steps that run after the lifecycle hook. Each is isolated via
+# completion_step so a failure in one (e.g. a raising notify path) can't abort the rest —
+# notably session-history archival, which must always run regardless of earlier steps.
+def run_post_completion_steps(ctx, exit_status:, signaled:, output_content:)
+  # Clean exit (0) but no usable response — e.g. the CLI hit a request/usage limit and
+  # bailed without doing work. The crash path only fires on non-zero exits, so this would
+  # otherwise be silent. Surface it to the originating channel.
+  completion_step("notify_no_output") do
+    notify_no_output_if_needed(ctx, exit_status: exit_status, signaled: signaled, output_content: output_content)
+  end
+
+  # Durable session history — record every finished session to disk (survives restarts),
+  # including provider-specific "heaviness" (context window usage + credits). Best-effort.
+  completion_step("archive_session_history") do
+    archive_session_history(ctx: ctx, exit_status: exit_status, signaled: signaled)
+  end
+
+  completion_step("qmd_update") { run_qmd_update(ctx[:agent_config_name]) }
+  completion_step("skill_candidate") { log_skill_candidate(ctx[:log_file]) }
+  completion_step("brain_push") { brain_push(message: "#{ctx[:agent_config_name] || "agent"}: #{ctx[:log_name]}") }
+  # check_brainiac_restart(ctx[:head_before], ctx[:status_before], ctx[:chdir], ctx[:project_key_for_restart], ctx[:agent_config_name])
+end
+
+# Run an independent post-completion step, logging and swallowing any failure so one
+# broken step (e.g. a plugin-facing call raising) can't abort the remaining steps —
+# notably session-history archival, which must not depend on earlier steps succeeding.
+def completion_step(name)
+  yield
+rescue StandardError => e
+  LOG.error "[Completion] step '#{name}' failed: #{e.class}: #{e.message}"
+  LOG.error "[Completion]   #{e.backtrace.first(3).join("\n  ")}" if e.backtrace
+  nil
+end
+
+# Surface a clean-exit session that produced no response, pulling fields from the
+# completion context. Only fires for exit 0 (non-zero already goes through the crash
+# path) with a source to notify. Extracted from handle_agent_completion.
+def notify_no_output_if_needed(ctx, exit_status:, signaled:, output_content:)
+  return unless ctx[:source]
+  return if signaled
+  return unless exit_status&.zero?
+
+  reason = detect_no_output_reason(ctx[:log_file], output_content)
+  return unless reason
+
+  notify_agent_no_output(
+    reason: reason, log_file: ctx[:log_file], agent_name: ctx[:agent_name],
+    source: ctx[:source], source_context: ctx[:source_context], project_config: ctx[:project_config]
+  )
+end
+
+# Capture the CLI session id after a run, if the provider and working dir are known.
+def capture_session_id_if_possible(ctx)
+  return unless ctx[:resolved] && ctx[:chdir]
+
+  capture_cli_session_id(resolved: ctx[:resolved], chdir: ctx[:chdir], minted_session_id: ctx[:minted_session_id])
+end
+
+# Notify plugins of a crashed agent session (non-zero exit, not signaled).
+def notify_crash_if_needed(ctx, agent_exit_status, agent_signaled)
+  return unless ctx[:source] && agent_exit_status && agent_exit_status != 0 && !agent_signaled
+
+  notify_agent_crash(
+    exit_status: agent_exit_status, log_file: ctx[:log_file],
+    agent_name: ctx[:agent_name], source: ctx[:source], source_context: ctx[:source_context],
+    project_config: ctx[:project_config]
+  )
+end
+
+# Run `qmd update` to reindex the brain after a session, logging the outcome.
+def run_qmd_update(agent_config_name)
   qmd_out, qmd_status = Open3.capture2e("qmd", "update")
   if qmd_status.success?
-    LOG.info "[Brain] qmd update completed after #{ctx[:agent_config_name] || "agent"} session"
+    LOG.info "[Brain] qmd update completed after #{agent_config_name || "agent"} session"
   else
     LOG.warn "[Brain] qmd update failed: #{qmd_out.strip}"
   end
+end
 
-  skill_candidate = detect_skill_candidate(ctx[:log_file])
-  if skill_candidate[:extract]
-    LOG.info "[Skills] Session qualifies for skill extraction " \
-             "(#{skill_candidate[:tool_calls]} tool calls, #{skill_candidate[:error_patterns]} error patterns) " \
-             "— agent was nudged via reflection prompt"
-  end
+# Log whether the session qualifies for skill extraction (agent nudged via reflection prompt).
+def log_skill_candidate(log_file)
+  skill_candidate = detect_skill_candidate(log_file)
+  return unless skill_candidate[:extract]
 
-  brain_push(message: "#{ctx[:agent_config_name] || "agent"}: #{ctx[:log_name]}")
-  # check_brainiac_restart(ctx[:head_before], ctx[:status_before], ctx[:chdir], ctx[:project_key_for_restart], ctx[:agent_config_name])
+  LOG.info "[Skills] Session qualifies for skill extraction " \
+           "(#{skill_candidate[:tool_calls]} tool calls, #{skill_candidate[:error_patterns]} error patterns) " \
+           "— agent was nudged via reflection prompt"
 end
 
 def check_brainiac_restart(head_before, status_before, chdir, project_key_for_restart, agent_config_name)

data/lib/brainiac/routes/api.rb

@@ -47,6 +47,54 @@ def format_recent_sessions
   end
 end
 
+# Whether a log file path is safe to serve over /api/logs.
+#
+# Agent sessions log into `<repo>/tmp` for the registered project, but most
+# real work (Fizzy cards, PR reviews, Discord agents) runs in a *worktree*
+# sibling directory named `<repo>--<suffix>` (e.g. `feature_parity--fizzy-1377-…`),
+# which is NOT under the registered repo_path. We therefore allow a log file
+# when it lives under any registered repo's `tmp/`, under any worktree sibling
+# of a registered repo (`<repo>--*/tmp/`), or under Brainiac's own `tmp/`.
+#
+# The worktree check is purely path-based (no filesystem globbing): the tmp
+# dir's grandparent directory must be a registered repo and the worktree name
+# must start with `<repo_basename>--`. This is cheap enough for the 2s log
+# poller and still matches even if the worktree was removed after the log was
+# written.
+def log_file_allowed?(log_file)
+  return true if log_allowed_repo_dirs.any? { |dir| log_file.start_with?(dir) }
+
+  log_file_in_worktree_tmp?(log_file)
+end
+
+def log_allowed_repo_dirs
+  dirs = PROJECTS.values.filter_map do |project|
+    repo_path = project["repo_path"]
+    (File.join(repo_path, "tmp") + File::SEPARATOR) if repo_path && !repo_path.empty?
+  end
+  dirs << (File.join(BRAINIAC_DIR, "tmp") + File::SEPARATOR)
+  dirs
+end
+
+# True when `log_file` sits in a `tmp/` dir of a worktree sibling of a
+# registered repo: `<parent>/<repo_basename>--<suffix>/tmp/...`.
+def log_file_in_worktree_tmp?(log_file)
+  tmp_dir = File.dirname(log_file)
+  return false unless File.basename(tmp_dir) == "tmp"
+
+  worktree = File.dirname(tmp_dir)
+  worktree_name = File.basename(worktree)
+  worktree_parent = File.dirname(worktree)
+
+  PROJECTS.values.any? do |project|
+    repo_path = project["repo_path"]
+    next false unless repo_path && !repo_path.empty?
+
+    File.dirname(repo_path) == worktree_parent &&
+      worktree_name.start_with?("#{File.basename(repo_path)}--")
+  end
+end
+
 def kill_child_process(target_pid)
   Process.kill("TERM", target_pid)
   Thread.new do
@@ -217,6 +265,13 @@ get "/api/status" do
   end
 end
 
+get "/api/sessions/history" do
+  content_type :json
+  limit = (params["limit"] || 50).to_i.clamp(1, SESSION_HISTORY_MAX)
+  history = read_session_history(limit: limit)
+  { history: history, count: history.size }.to_json
+end
+
 post "/api/sessions/kill/:card_key" do
   content_type :json
   card_key = params[:card_key]
@@ -255,9 +310,7 @@ get "/api/logs" do
   halt 400, "Invalid path" if log_file.include?("..") || !log_file.start_with?("/")
   halt 404, "File not found" unless File.exist?(log_file)
 
-  allowed = PROJECTS.values.map { |p| File.join(p["repo_path"], "tmp") }
-  allowed << File.join(BRAINIAC_DIR, "tmp")
-  halt 403, "Forbidden" unless allowed.any? { |dir| log_file.start_with?(dir) }
+  halt 403, "Forbidden" unless log_file_allowed?(log_file)
 
   all_lines = File.readlines(log_file).last(lines)
   all_lines.join.gsub(/\e\[[\d;]*[a-zA-Z]/, "").gsub(/\e\[\?[\d;]*[a-zA-Z]/, "")

data/lib/brainiac/session_history.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+# Durable session history + "session heaviness" tracking.
+#
+# The in-memory RECENT_SESSIONS (see sessions.rb) only holds the last 10 finished
+# sessions and is wiped on every brainiac restart. This module persists a durable,
+# append-only record of every completed agent session to disk so the monitor (and
+# anything else) can review real history: how long a session ran, which CLI/model it
+# used, where it came from, and — where the provider exposes it — how "heavy" the
+# session was (context window usage + credits spent).
+#
+# Storage: append-only JSONL at ~/.brainiac/session-history.jsonl (one record per line).
+# JSONL is chosen deliberately: appends are atomic-ish and cheap, the file survives
+# restarts, it's trivially tailable, and a corrupt line never poisons the whole file.
+# The file is trimmed to SESSION_HISTORY_MAX records to bound growth.
+
+SESSION_HISTORY_FILE = File.join(BRAINIAC_DIR, "session-history.jsonl")
+SESSION_HISTORY_MAX = 500
+SESSION_HISTORY_MUTEX = Mutex.new
+
+# Append a completed-session record to the durable history file.
+# `record` is a plain Hash; symbol keys are fine (serialized to JSON).
+# Best-effort: any failure is logged and swallowed — history is never allowed to
+# break the completion path.
+def record_session_history(record)
+  SESSION_HISTORY_MUTEX.synchronize do
+    FileUtils.mkdir_p(File.dirname(SESSION_HISTORY_FILE))
+    File.open(SESSION_HISTORY_FILE, "a") { |f| f.puts(JSON.generate(record)) }
+    trim_session_history!
+  end
+  LOG.info "[SessionHistory] Recorded session for #{record["agent"] || "?"} → #{SESSION_HISTORY_FILE}"
+  true
+rescue StandardError => e
+  LOG.warn "[SessionHistory] Failed to record session: #{e.class}: #{e.message}"
+  false
+end
+
+# Read the most recent `limit` session records, newest first.
+def read_session_history(limit: 50)
+  return [] unless File.exist?(SESSION_HISTORY_FILE)
+
+  lines = SESSION_HISTORY_MUTEX.synchronize { File.readlines(SESSION_HISTORY_FILE) }
+  records = lines.filter_map do |line|
+    line = line.strip
+    next if line.empty?
+
+    begin
+      JSON.parse(line)
+    rescue JSON::ParserError
+      nil
+    end
+  end
+  records.last(limit).reverse
+rescue StandardError => e
+  LOG.warn "[SessionHistory] Failed to read history: #{e.message}"
+  []
+end
+
+# Keep the history file bounded. Call inside SESSION_HISTORY_MUTEX.
+def trim_session_history!
+  lines = File.readlines(SESSION_HISTORY_FILE)
+  return if lines.size <= SESSION_HISTORY_MAX
+
+  File.write(SESSION_HISTORY_FILE, lines.last(SESSION_HISTORY_MAX).join)
+rescue StandardError => e
+  LOG.warn "[SessionHistory] Failed to trim history: #{e.message}"
+end
+
+# Build the durable history record for a finished session and append it.
+# Called from handle_agent_completion. Gathers timing, identity, and — via the
+# provider-specific heaviness probe — context/credit usage. Never raises.
+def archive_session_history(ctx:, exit_status:, signaled:)
+  started_at = ctx[:started_at]
+  finished_at = Time.now
+  heaviness = session_heaviness(resolved: ctx[:resolved], chdir: ctx[:chdir])
+  source_context = ctx[:source_context] || {}
+  card_key = ctx[:card_key] || source_context[:card_key]
+  channel_id = ctx[:channel_id] || source_context[:channel_id]
+
+  record = {
+    "recorded_at" => finished_at.utc.iso8601,
+    "agent" => ctx[:agent_name] || ctx[:agent_config_name] || "Unknown",
+    "card_key" => card_key,
+    "card_number" => ctx[:card_number] || source_context[:card_number],
+    "source" => ctx[:source]&.to_s,
+    "channel_id" => channel_id,
+    "log_file" => ctx[:log_file],
+    "cli" => ctx[:agent_cli],
+    "model" => ctx[:model],
+    "started_at" => started_at&.utc&.iso8601,
+    "finished_at" => finished_at.utc.iso8601,
+    "duration_seconds" => started_at ? (finished_at - started_at).to_i : nil,
+    "exit_status" => exit_status,
+    "signaled" => signaled
+  }
+  record.merge!(heaviness) if heaviness
+  record.compact!
+
+  record_session_history(record)
+end
+
+# --- Provider-generic session heaviness probe ---
+#
+# "How heavy was this session?" — context window usage + credits spent.
+# This is inherently provider-specific: each CLI stores (or doesn't store) usage
+# differently. Rather than hardcode any one CLI in this file, brainiac reads a
+# `heaviness_probe` block from the provider's cli-providers/<name>.json. That config
+# declares WHICH probe strategy to use and WHERE its data lives, e.g.:
+#
+#   "heaviness_probe": { "type": "kiro_sqlite", "db_path": "~/.local/share/kiro-cli/data.sqlite3" }
+#
+# The config controls the "what and where" (enable/disable a provider, point it at a
+# moved db) with zero code changes. The "how" for each probe TYPE lives here in Ruby —
+# a genuinely new storage mechanism (a provider that logs usage to JSON, an HTTP
+# endpoint, etc.) still needs a small probe implementation, but pointing kiro at a new
+# path or turning a provider's probe on/off is pure JSON.
+#
+# Providers with no `heaviness_probe` (or an unknown type) simply yield nil and the
+# history record carries timing/identity only.
+#
+# Returns a Hash of string-keyed heaviness fields, or nil if unavailable:
+#   context_window_tokens, context_usage_pct, context_used_tokens, credits_used
+def session_heaviness(resolved:, chdir:)
+  return nil unless resolved && chdir
+
+  probe = resolved["heaviness_probe"]
+  return nil unless probe.is_a?(Hash)
+
+  case probe["type"]
+  when "kiro_sqlite"
+    kiro_session_heaviness(chdir, db_path: probe["db_path"])
+  end
+rescue StandardError => e
+  LOG.warn "[SessionHistory] Heaviness probe failed for #{chdir}: #{e.message}"
+  nil
+end
+
+# kiro-cli persists every conversation in a local sqlite keyed by working directory.
+# Each conversation's JSON carries the model's context window, the latest request's
+# context-usage percentage, and per-request credit usage. We read it read-only via the
+# sqlite3 CLI (no gem dependency) and derive the heaviness fields. Best-effort: any
+# problem (missing db, no row for this cwd, malformed json) yields nil.
+#
+# The db location comes from the provider's heaviness_probe.db_path so it's not baked
+# into brainiac; KIRO_DEFAULT_DB_PATH is only the fallback.
+KIRO_DEFAULT_DB_PATH = File.join(Dir.home, ".local", "share", "kiro-cli", "data.sqlite3")
+
+def kiro_session_heaviness(chdir, db_path: nil)
+  db = File.expand_path(db_path || KIRO_DEFAULT_DB_PATH)
+  return nil unless File.exist?(db)
+
+  key = File.expand_path(chdir)
+  # The CTE picks the most recently updated conversation for this working directory,
+  # then we pull the model's context window, the latest request's context-usage %, and
+  # the summed credit spend. `.timeout` (via -cmd, so it doesn't emit output) keeps us
+  # from hanging if kiro-cli is mid-write.
+  sql = <<~SQL.gsub(/\s+/, " ").strip
+    WITH latest AS (
+      SELECT value FROM conversations_v2
+      WHERE key = #{sqlite_quote(key)} ORDER BY updated_at DESC LIMIT 1
+    )
+    SELECT
+      json_extract(value, '$.model_info.context_window_tokens'),
+      (SELECT r.value ->> 'context_usage_percentage'
+         FROM latest, json_each(json_extract(latest.value, '$.user_turn_metadata.requests')) r
+         ORDER BY CAST(r.key AS INTEGER) DESC LIMIT 1),
+      (SELECT ROUND(SUM(CAST(u.value ->> 'value' AS REAL)), 4)
+         FROM latest, json_each(json_extract(latest.value, '$.user_turn_metadata.usage_info')) u
+         WHERE (u.value ->> 'unit') = 'credit')
+    FROM latest;
+  SQL
+
+  out = ""
+  status = nil
+  Timeout.timeout(6) do
+    out, status = Open3.capture2(
+      "sqlite3", "-separator", "\t", "-cmd", ".timeout 3000",
+      "file:#{db}?mode=ro", sql
+    )
+  end
+  return nil unless status&.success?
+
+  row = out.strip
+  return nil if row.empty?
+
+  window, pct, credits = row.split("\t", 3)
+  window = window.to_i
+  return nil if window.zero?
+
+  pct = pct.to_f
+  fields = { "context_window_tokens" => window, "context_usage_pct" => pct.round(2) }
+  fields["context_used_tokens"] = (window * pct / 100.0).round if pct.positive?
+  fields["credits_used"] = credits.to_f.round(4) if credits && !credits.empty?
+  fields
+end
+
+# Single-quote a string for safe literal interpolation into SQLite SQL.
+def sqlite_quote(str)
+  "'#{str.to_s.gsub("'", "''")}'"
+end

data/lib/brainiac/version.rb

@@ -2,5 +2,5 @@
 
 module Brainiac
   # @return [String] the current gem version
-  VERSION = "0.0.32"
+  VERSION = "0.1.0"
 end

data/lib/brainiac.rb

@@ -5,6 +5,7 @@ require_relative "brainiac/agents"
 require_relative "brainiac/brain"
 require_relative "brainiac/skills"
 require_relative "brainiac/sessions"
+require_relative "brainiac/session_history"
 require_relative "brainiac/prompts"
 require_relative "brainiac/helpers"
 require_relative "brainiac/intent"

data/receiver.rb

@@ -19,6 +19,7 @@ require_relative "lib/brainiac/agents"
 require_relative "lib/brainiac/brain"
 require_relative "lib/brainiac/skills"
 require_relative "lib/brainiac/sessions"
+require_relative "lib/brainiac/session_history"
 require_relative "lib/brainiac/prompts"
 require_relative "lib/brainiac/helpers"
 require_relative "lib/brainiac/notifications"
@@ -100,6 +101,16 @@ configure do
 end
 
 LOG.info "[Brainiac] Starting v#{BRAINIAC_VERSION} on port #{settings.port} (#{settings.environment})"
+LOG.info "[Brainiac] Server root: #{SERVER_ROOT} (pid #{Process.pid})"
+
+# Warn loudly when the server is running from an installed gem rather than a git
+# checkout. During development this is almost always a mistake: `brainiac` on PATH
+# resolves to the gem's bin, so edits to a working checkout never take effect. Surfacing
+# it here turns a long "why won't my change apply" hunt into a one-line startup notice.
+if SERVER_ROOT.include?("/gems/")
+  LOG.warn "[Brainiac] Running from an installed GEM (#{SERVER_ROOT}) — not a git checkout. " \
+           "Local code changes will NOT be loaded. Run `ruby ./bin/brainiac server` from your checkout to test edits."
+end
 if intent_config["enabled"]
   LOG.info "[Intent] Enabled — model: #{intent_config["model"]}, endpoint: #{intent_config["endpoint"]}"
   begin

data/templates/cli-providers/kiro.json.example

@@ -18,5 +18,10 @@
     "qwen": "qwen3-coder-next",
     "auto": "auto"
   },
-  "efforts": ["low", "medium", "high", "xhigh", "max"]
+  "efforts": ["low", "medium", "high", "xhigh", "max"],
+  "heaviness_probe": {
+    "comment": "Optional. Lets brainiac record how 'heavy' a finished session was (context window usage + credits) in the durable session history. type selects the probe strategy; db_path points at the provider's local usage store. Omit this block to record timing/identity only.",
+    "type": "kiro_sqlite",
+    "db_path": "~/.local/share/kiro-cli/data.sqlite3"
+  }
 }

data/templates/cli-providers/opencode.json.example

@@ -0,0 +1,19 @@
+{
+  "binary": "opencode",
+  "default_args": "run --auto",
+  "agent_flag": null,
+  "model_flag": "--model",
+  "prompt_mode": "stdin",
+  "resume_id_flag": "--session",
+  "session_list_command": "opencode session list --format json",
+  "title_flag": "--title",
+  "list_models_command": "opencode models ollama",
+  "models": {
+    "qwen": "ollama/qwen3.6:latest",
+    "qwen36": "ollama/qwen3.6:latest",
+    "local": "ollama/qwen3.6:latest",
+    "gemma": "ollama/gemma3:12b",
+    "fast": "ollama/qwen3:4b",
+    "auto": "ollama/qwen3.6:latest"
+  }
+}

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: brainiac
 version: !ruby/object:Gem::Version
-  version: 0.0.32
+  version: 0.1.0
 platform: ruby
 authors:
 - Andy Davis
@@ -142,6 +142,7 @@ files:
 - lib/brainiac/prompts.rb
 - lib/brainiac/restart.rb
 - lib/brainiac/routes/api.rb
+- lib/brainiac/session_history.rb
 - lib/brainiac/sessions.rb
 - lib/brainiac/skills.rb
 - lib/brainiac/users.rb
@@ -166,6 +167,7 @@ files:
 - templates/cli-providers/gemini.json.example
 - templates/cli-providers/grok.json.example
 - templates/cli-providers/kiro.json.example
+- templates/cli-providers/opencode.json.example
 - templates/hooks/pre-commit
 - templates/plugins.json.example
 - templates/roles/code-reviewer.md.example