cardinal-ai 0.2.4 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9765ce8a3b88ca8a2d72dcdaa766d67d42b0b1f1304ce44551fb0b31a8b62f84
-  data.tar.gz: 6bbd3904403e6e91b83a684d134c15ad402a98ab27f4600d6424752033565b0b
+  metadata.gz: '079e999400eeaa39a8e7f7d8efdc4b3b114923cf0aaf190dcd15a6117a97d7b2'
+  data.tar.gz: 61343cc2e5c42fbf43f3eeb223da83af60d1e634f8424e69d032c9afd287aa02
 SHA512:
-  metadata.gz: b91c51d2d12d2df7d7d1f81b7d8547545ed68cac112f4d844dd4666626ccb34081397dc038fa4620a8b0e76e804b18c64608d96c92be657238958bf4bf3540ff
-  data.tar.gz: 1e71c84583f3c6f02b3315ce7fa4abce078117dcb47ceb13a15a1641c3a90651673db22015c63ab8c1ca2e0683c136b50ac278b695e7144d34d7f7d2bf8378fc
+  metadata.gz: 1acb0d147c37615d1daf946a8e3aebbbdec636511cf6781a835ed4b73b61b1f3b57aff903273b160b75df66b263857cc83e7ef38f8b71841a7f8f3ebea8877e6
+  data.tar.gz: 5ab7bddf1b68f55466825914a1d0eb7a697e02a5c7e0e3a4d0dcfe306ee673c65a17f9f5e2bf09425c002ccd02809d32ce30e2f0a2ececdd2c93b8d0139932c5

data/README.md

@@ -43,12 +43,26 @@ That's the whole setup. Now:
 4. **Review** — read the final report and the pull request. Say what's wrong in the
    card's conversation to send it back, or approve.
 5. **QA** — the pull request goes live for formal review on GitHub.
-6. **Drag to Done** — the pull request merges. Shipped.
+6. **Drag to Done** — the pull request merges. Shipped. (If the project has CI and it's
+   red or still running, Cardinal refuses to merge and tells you why on the card.)
 
 Every column has a ⚙ gear where you can change the rules — which AI model works there,
 how many cards can run at once, spending limits, and what happens when a card arrives
 (written in plain English; Cardinal figures out the rest).
 
+### The deep dive
+
+The **🔍 Deep dive** button in the topbar sends a read-only agent (it can look, never
+touch) through your repo once and saves what it learns as a **repo brief** — what the
+project is, where things live, how to build and test it, the traps to avoid. Every worker
+agent gets the brief with its assignment, so agents skip re-exploring your codebase on
+every single card. It costs one AI call.
+
+Once a brief exists the button shows **🔍 Repo brief** — click it to read exactly what
+agents are being told, and to regenerate it. The button drifts from grey toward red as
+commits land that the brief hasn't seen; Cardinal won't silently re-run a dive that's
+already current.
+
 ## Good to know
 
 - Everything Cardinal knows about a project lives in a `.cardinal/` folder inside it,
@@ -57,6 +71,11 @@ how many cards can run at once, spending limits, and what happens when a card ar
   `cardinal logout` to unlink).
 - Agents can only push to their own card branches — merging is always your drag.
 - AI usage bills the Claude account you linked, the same as using Claude Code.
+- The board is only reachable from **your own machine** (localhost). To browse it from
+  another device on your network — a phone or tablet — start with `CARDINAL_HOST=0.0.0.0
+  cardinal`, and know that anyone on that network can then drive your board.
+- In a worker column's ⚙ gear you can turn off **Shell access**: the agent can then only
+  read and edit files — it can't run commands — and Cardinal commits its work for it.
 
 ## For developers
 

data/app/assets/stylesheets/cardinal.css

@@ -52,6 +52,7 @@ a { color: var(--blue); text-decoration: none; }
 }
 .topbar h1 { font-size: 16px; margin: 0; font-weight: 600; }
 .topbar h1 .sep { color: var(--accent); margin: 0 4px; }
+.topbar-left { display: flex; align-items: center; gap: 12px; }
 .topbar-right { display: flex; align-items: center; gap: 14px; }
 
 .theme-toggle {
@@ -60,6 +61,37 @@ a { color: var(--blue); text-decoration: none; }
 }
 .theme-toggle:hover { color: var(--text); border-color: var(--text-dim); }
 
+/* Repo deep dive button (card #12). Inline color/border come from the board's
+   staleness gradient (grey → red over 10 commits); .stale-critical flashes to
+   nag a refresh once the brief is too far behind HEAD to trust. */
+.topbar-right form.button_to { display: inline-flex; margin: 0; }
+.deep-dive {
+  display: inline-flex; align-items: center; gap: 6px;
+  background: transparent; border: 1px solid var(--border); border-radius: 6px;
+  color: var(--text-dim); font-weight: 600; padding: 5px 10px; line-height: 1;
+  cursor: pointer; white-space: nowrap;
+}
+.deep-dive:hover:not(:disabled) { filter: brightness(1.25); }
+.deep-dive:disabled { cursor: default; opacity: .8; }
+.deep-dive.stale-critical { animation: stale-flash 1.1s ease-in-out infinite; }
+@keyframes stale-flash {
+  0%, 100% { opacity: 1; box-shadow: 0 0 0 0 rgba(212, 51, 51, .55); }
+  50%      { opacity: .7; box-shadow: 0 0 0 3px rgba(212, 51, 51, 0); }
+}
+
+.brief-meta { font-size: 12px; color: var(--text-dim); }
+.brief-behind { color: var(--amber); }
+.brief-content {
+  background: var(--surface); border: 1px solid var(--border); border-radius: 8px;
+  padding: 4px 14px; margin: 10px 0; max-height: 50vh; overflow-y: auto;
+  font-size: 13px;
+}
+
+.pull-form { display: inline; }
+#repo-pull-status { font-size: 0.85rem; }
+#repo-pull-status .pull-ok  { color: var(--green); }
+#repo-pull-status .pull-err { color: var(--red); }
+
 .attention summary {
   cursor: pointer;
   color: var(--amber);
@@ -154,6 +186,10 @@ button, input[type="submit"] {
 body.dragging .drop-hint { display: block; }
 .ticker { font-size: 11px; color: var(--text-dim); margin: 0 4px 8px; }
 
+.column-footer { margin-top: 8px; padding-top: 8px; border-top: 1px solid var(--border); font-size: 11px; color: var(--text-dim); }
+.footer-row { display: flex; justify-content: space-between; gap: 8px; padding: 1px 4px; }
+.footer-value { font-variant-numeric: tabular-nums; color: var(--text); }
+
 .cards { min-height: 40px; display: flex; flex-direction: column; gap: 8px; flex: 1; overflow-y: auto; }
 .cards-clickable { cursor: pointer; }
 .agent-chip { color: var(--blue); }

data/app/controllers/boards_controller.rb

@@ -2,4 +2,103 @@ class BoardsController < ApplicationController
   def show
     @board = Board.includes(columns: :cards).first!
   end
+
+  # Kick off the repo deep dive (card #12). Non-blocking: flip the board into
+  # its "Working" state, morph the topbar so the button reflects it, and let
+  # DeepDiveJob do the read-only exploration in the background. Skipped when a
+  # dive is already running, or when the brief already matches HEAD — nothing
+  # changed, so a re-dive would just burn a run (the brief modal's Regenerate
+  # button passes force=1 to override).
+  def deep_dive
+    board = Board.first!
+    fresh = board.brief? && board.commits_behind_brief == 0
+    unless board.brief_working? || (fresh && params[:force].blank?)
+      board.update!(brief_status: "working")
+      board.broadcast_refresh_to board
+      DeepDiveJob.perform_later(board)
+    end
+    redirect_to root_path
+  end
+
+  # Board settings gear (the board-level analog of the column gear): name and
+  # default branch — the branch agents fork from and Done merges toward.
+  def edit
+    @board = Board.first!
+    redirect_to root_path and return unless turbo_frame_request?
+  end
+
+  def update
+    board = Board.first!
+    attrs = params.require(:board).permit(:name, :default_branch)
+    board.update!(
+      name: attrs[:name].presence || board.name,
+      default_branch: attrs[:default_branch].presence || board.default_branch
+    )
+    board.broadcast_refresh_to board
+    if params[:autosave]
+      render turbo_stream: [
+        turbo_stream.update("board-name", board.name),
+        turbo_stream.update("board-form-errors", "")
+      ]
+    else
+      redirect_to root_path
+    end
+  end
+
+  # Inspect the repo brief: what the deep dive wrote, when, from which SHA.
+  def brief
+    @board = Board.first!
+    redirect_to root_path and return unless turbo_frame_request?
+
+    render :brief
+  end
+
+  # Cards reaching Done merge PRs on GitHub, so the checkout Cardinal runs
+  # against falls behind. The topbar Pull button fast-forwards it. --ff-only
+  # on purpose: never invent merge commits or rebase local work — if the tree
+  # has diverged, say so and let the human sort it out in a real terminal.
+  def pull
+    board = Board.first!
+    message, ok = pull_repo(board)
+    render turbo_stream: turbo_stream.update(
+      "repo-pull-status",
+      helpers.tag.span(message, class: ok ? "pull-ok" : "pull-err")
+    )
+  end
+
+  private
+
+  def pull_repo(board)
+    repo = board.local_path.presence
+    return ["No local repo path on this board", false] unless repo && Dir.exist?(File.join(repo, ".git"))
+
+    before, = Open3.capture2e("git", "-C", repo, "rev-parse", "HEAD")
+    out, status = Open3.capture2e("git", "-C", repo, "pull", "--ff-only")
+    unless status.success?
+      # Surface git's own reason (diverged, offline, auth) — the last
+      # non-blank line is usually the one that matters.
+      return [out.lines.map(&:strip).reject(&:blank?).last.to_s.truncate(120), false]
+    end
+
+    after, = Open3.capture2e("git", "-C", repo, "rev-parse", "HEAD")
+    if before.strip == after.strip
+      ["Already up to date", true]
+    else
+      count, = Open3.capture2e("git", "-C", repo, "rev-list", "--count", "#{before.strip}..#{after.strip}")
+      migrated = run_pending_migrations
+      note = migrated.positive? ? " · ran #{helpers.pluralize(migrated, "migration")}" : ""
+      ["Pulled #{helpers.pluralize(count.strip.to_i, "new commit")}#{note}", true]
+    end
+  end
+
+  # When the board's repo IS this Cardinal instance (dogfooding) a pull can
+  # bring schema changes; without this the running server 500s until someone
+  # runs db:migrate by hand. A no-op everywhere else — `cardinal up` already
+  # covers cold boots via db:prepare.
+  def run_pending_migrations
+    context = ActiveRecord::Base.connection_pool.migration_context
+    pending = context.migrations.map(&:version) - context.get_all_versions
+    context.migrate if pending.any?
+    pending.size
+  end
 end

data/app/controllers/columns_controller.rb

@@ -26,7 +26,7 @@ class ColumnsController < ApplicationController
       :name, :archetype, :instructions, :model, :effort,
       :concurrency_limit, :max_turns, :timeout_minutes, :plan_approval,
       :on_entry_text, :on_entry_json, :color, :custom_color, :arrivals, :ai,
-      accepts_from: []
+      :shell, :footer_text, accepts_from: []
     )
 
     policy = @column.policy.dup
@@ -38,6 +38,7 @@ class ColumnsController < ApplicationController
     policy["plan_approval"] = attrs[:plan_approval] == "1"
     policy["arrivals"] = attrs[:arrivals].presence_in(%w[top bottom])
     policy["ai"] = (attrs[:ai] == "1") if attrs.key?(:ai) # inbox forms omit it — never AI anyway
+    policy["shell"] = (attrs[:shell] == "1") if attrs.key?(:shell) # worker shell access (execution gear only)
     # Accept policy (card #15): store allowed source column ids as strings.
     # EXPLICIT ONLY — an empty list means the column accepts from nowhere.
     policy["accepts_from"] = attrs[:accepts_from].to_a.map(&:to_s).reject(&:blank?).presence
@@ -74,6 +75,14 @@ class ColumnsController < ApplicationController
       policy.delete("on_entry_text")
     end
 
+    # Footer (card #18): one row per line as "Label | compute". A blank compute
+    # is a static label; a compute must be one Column knows how to aggregate.
+    begin
+      policy["footer"] = parse_footer(attrs[:footer_text])
+    rescue ArgumentError => e
+      return column_error(e.message)
+    end
+
     @column.update!(
       name: attrs[:name].presence || @column.name,
       archetype: new_archetype,
@@ -126,5 +135,21 @@ class ColumnsController < ApplicationController
 
   private
 
+  # "Label | compute" lines → [{"label" =>, "compute" =>}]. Returns nil when
+  # empty so the key is dropped by policy.compact. Raises ArgumentError on an
+  # unknown compute key, mirroring the on_entry validation path.
+  def parse_footer(text)
+    rows = text.to_s.lines.filter_map do |line|
+      next if line.strip.blank?
+      label, compute = line.split("|", 2).map(&:strip)
+      compute = compute.to_s
+      if compute.present? && !Column::FOOTER_COMPUTES.include?(compute)
+        raise ArgumentError, "Footer compute \"#{compute}\" is not one of: #{Column::FOOTER_COMPUTES.join(', ')}"
+      end
+      { "label" => label.to_s, "compute" => compute.presence }.compact
+    end
+    rows.presence
+  end
+
   def set_column = @column = Column.find(params[:id])
 end

data/app/helpers/application_helper.rb

@@ -26,6 +26,14 @@ module ApplicationHelper
     MARKDOWN.render(text.to_s).html_safe
   end
 
+  # Render a column's stored footer config (array of {label, compute} hashes)
+  # back into the "Label | compute" line format the gear textarea edits.
+  def footer_config_text(column)
+    Array(column.footer).map do |row|
+      [row["label"], row["compute"].presence].compact.join(" | ")
+    end.join("\n")
+  end
+
   def info_tip(text)
     tag.span("i", class: "info",
              data: { controller: "tooltip", tooltip_text_value: text,

data/app/jobs/deep_dive_job.rb

@@ -0,0 +1,64 @@
+# Opt-in repo deep dive (card #12): a one-shot, read-only agent (the same
+# cheap ClaudeCli tier the planning assistant uses — Read/Glob/Grep, no
+# workspace) that maps the board's repo into a compact "repo brief". The brief
+# is written to .cardinal/repo-brief.md and injected into every worker prompt,
+# converting the per-run exploration tax into a one-time cost.
+class DeepDiveJob < ApplicationJob
+  queue_as :default
+
+  # Enough turns to walk the tree and read a handful of key files, not enough
+  # to wander. ClaudeCli wraps up from context if it hits the cap.
+  MAX_TURNS = 30
+  FALLBACK_MODEL = "claude-haiku-4-5-20251001".freeze
+
+  PROMPT = <<~PROMPT.freeze
+    Map this repository as a concise "repo brief" for other AI agents who will
+    work in it. The whole point is to save tokens later, so be dense and skip
+    the obvious — every line must earn its place.
+
+    Explore with your read-only tools, then output ONLY flat markdown with these
+    sections (drop any that genuinely don't apply):
+
+    ## Overview
+    One short paragraph: what this project is and its shape.
+    ## Directory Structure
+    The top-level directories and what each is for (one line each).
+    ## Key Directories
+    The few places most work actually happens, and what lives there.
+    ## Build & Test
+    The exact commands to install, build, run, and test.
+    ## Key Conventions
+    Naming, patterns, and idioms an agent must follow to match the codebase.
+    ## Tech Stack
+    Languages, frameworks, and notable libraries with their role.
+    ## Gotchas
+    Non-obvious traps, footguns, and constraints worth knowing before editing.
+
+    Do not include a preamble, closing remarks, or anything outside these sections.
+  PROMPT
+
+  def perform(board)
+    repo = board.local_path.presence
+    return clear_working(board) unless ClaudeCli.available? && repo
+
+    sha = board.head_sha
+    model = board.columns.find_by(archetype: "planning")&.model.presence || FALLBACK_MODEL
+
+    brief = ClaudeCli.prompt(PROMPT, model:, tools: "Read,Glob,Grep", cwd: repo, max_turns: MAX_TURNS)
+
+    File.write(board.brief_path, brief.to_s)
+    board.update!(brief_sha: sha, brief_generated_at: Time.current,
+                  brief_model: model, brief_status: nil)
+    board.broadcast_refresh_to board
+  rescue StandardError
+    # A failed dive must not leave the button stuck on "Working" forever.
+    clear_working(board)
+  end
+
+  private
+
+  def clear_working(board)
+    board.update!(brief_status: nil)
+    board.broadcast_refresh_to board
+  end
+end

data/app/jobs/merge_pr_job.rb

@@ -6,6 +6,7 @@ class MergePrJob < ApplicationJob
   def perform(card_id)
     card = Card.find(card_id)
     return if card.pr_url.blank? || card.pr_state == "merged"
+    return unless checks_green?(card)
 
     # Best-effort undraft — a QA column may already have done it, and gh
     # errors on an already-ready PR; the merge step is the real gate.
@@ -18,6 +19,27 @@ class MergePrJob < ApplicationJob
 
   private
 
+  # The merge gate: never ship over failing CI. A repo with no checks
+  # configured passes (nothing to gate on); failing or still-running checks
+  # park the card as blocked with the reason — drag it out and back into Done
+  # to retry once CI is green.
+  def checks_green?(card)
+    out, status = Open3.capture2e("gh", "pr", "checks", card.pr_url)
+    return true if status.success?
+    return true if out.match?(/no checks reported/i)
+
+    reason =
+      if status.exitstatus == 8
+        "CI checks are still running — not merged. Drag out of Done and back once they finish."
+      else
+        failing = out.lines.map(&:strip).grep(/fail/i).first(3).join("; ").presence || out.strip.truncate(160)
+        "CI checks failing — not merged. #{failing}"
+      end
+    card.log!("error", text: reason)
+    card.update!(status: "blocked")
+    false
+  end
+
   def run_step(card, cmd)
     out, status = Open3.capture2e(*cmd)
     return true if status.success?

data/app/jobs/resume_run_job.rb

@@ -20,6 +20,13 @@ class ResumeRunJob < ApplicationJob
       return
     end
 
+    # Atomic claim (§ races): two finishing runs can both kick the queue and
+    # double-fire this job — exactly one claimer resumes the session. The
+    # claim value is "running", which is what a resume sets anyway.
+    return unless Run.where(id: run.id, status: "needs_input")
+                     .update_all(status: "running", updated_at: Time.current) == 1
+    run.reload
+
     if (pending = run.briefing["pending_resume"])
       run.update!(briefing: run.briefing.except("pending_resume"))
       message = [pending["message"], message].compact_blank.join("\n\n")

data/app/jobs/start_run_job.rb

@@ -3,11 +3,26 @@ class StartRunJob < ApplicationJob
 
   def perform(card_id)
     card = Card.find(card_id)
-    return unless card.queued? && card.column.execution? && card.column.ai?
-    return if card.column.at_wip_limit? # stays queued; kicked when a slot frees
+    column = card.column
+    return unless column.execution? && column.ai?
+    return if column.at_wip_limit? # stays queued; kicked when a slot frees
 
-    session = card.agent_sessions.create!(status: "provisioning", model: card.column.model)
-    run = session.runs.create!(status: "queued", briefing: { "card" => card.title, "column" => card.column.name })
+    # Atomic claim (§ races): two kicks can enqueue this job twice for the
+    # same card; exactly one claimer flips queued→working, the rest no-op.
+    return unless Card.where(id: card.id, status: "queued")
+                      .update_all(status: "working", updated_at: Time.current) == 1
+    card.reload.touch # update_all skips callbacks — nudge the board broadcast
+
+    # Re-check AFTER claiming: claims are atomic, so an over-subscribed slot
+    # shows up as strictly more running than allowed and the loser un-claims
+    # back into the queue (the next kick retries it).
+    if column.at_wip_limit_exceeded?
+      card.update!(status: "queued")
+      return
+    end
+
+    session = card.agent_sessions.create!(status: "provisioning", model: column.model)
+    run = session.runs.create!(status: "queued", briefing: { "card" => card.title, "column" => column.name })
     Agent::Runner.start(run)
   end
 end

data/app/models/board.rb

@@ -60,18 +60,30 @@ class Board < ApplicationRecord
     # Raw configured URL (get-url applies insteadOf rewrites, which can embed
     # credential-helper tokens); strip any userinfo defensively either way.
     origin, origin_ok = Open3.capture2e("git", "-C", repo_path, "config", "--get", "remote.origin.url")
-    branch, branch_ok = Open3.capture2e("git", "-C", repo_path, "rev-parse", "--abbrev-ref", "HEAD")
 
     board = create!(
       name: File.basename(repo_path),
       repo_url: origin_ok.success? ? sanitize_remote_url(origin.strip) : nil,
-      default_branch: branch_ok.success? && branch.strip.present? ? branch.strip : "main",
+      default_branch: detect_default_branch(repo_path),
       local_path: repo_path
     )
     board.install_default_columns!
     board
   end
 
+  # The REMOTE's default branch, not whatever happened to be checked out when
+  # `cardinal up` first ran — launching from a feature branch must not make
+  # Done merge toward that feature branch forever. Fallback chain: origin's
+  # HEAD → current branch → "main". Editable later in board settings.
+  def self.detect_default_branch(repo_path)
+    head, ok = Open3.capture2e("git", "-C", repo_path, "symbolic-ref", "refs/remotes/origin/HEAD")
+    return head.strip.delete_prefix("refs/remotes/origin/") if ok.success? && head.strip.present?
+
+    # symbolic-ref, not rev-parse: works even on an unborn branch (fresh init).
+    branch, ok = Open3.capture2e("git", "-C", repo_path, "symbolic-ref", "--short", "HEAD")
+    ok.success? && branch.strip.present? ? branch.strip : "main"
+  end
+
   def self.sanitize_remote_url(url)
     # Drop any userinfo (tokens from credential-helper rewrites). Regex, not
     # URI#userinfo= — Ruby 3.4's RFC3986 parser silently ignores that setter.
@@ -83,6 +95,67 @@ class Board < ApplicationRecord
     cards.pluck(:tags).flatten.compact.uniq.sort
   end
 
+  # --- Repo brief (card #12) ---------------------------------------------
+  # A one-time deep dive that maps the repo, stored as flat markdown in
+  # .cardinal/ (never the host repo) and injected into worker prompts to
+  # spare each run the exploration tax. Metadata (which SHA/model/when) lives
+  # on the board so staleness can be judged against the current HEAD.
+  #
+  # Storage is a file + metadata, not one text column, so a structure
+  # provider (the Graphify child card) can slot a richer representation in
+  # underneath later without a migration.
+  BRIEF_STALE_AT = 10 # commits behind → the "refresh me" red/flashing state
+
+  # Honor CARDINAL_DATA_DIR: in gem mode Rails.root is the installed gem
+  # (read-only); the instance's data lives in the target repo's .cardinal/.
+  def brief_path
+    Pathname(File.expand_path(ENV["CARDINAL_DATA_DIR"].presence || Rails.root.join(".cardinal"))).join("repo-brief.md")
+  end
+
+  def repo_brief
+    File.read(brief_path) if File.exist?(brief_path)
+  end
+
+  def brief?
+    brief_sha.present? && File.exist?(brief_path)
+  end
+
+  def brief_working? = brief_status == "working"
+
+  # HEAD of the board's repo right now — the yardstick staleness measures against.
+  def head_sha
+    return nil if local_path.blank?
+    out, ok = Open3.capture2e("git", "-C", local_path, "rev-parse", "HEAD")
+    ok.success? ? out.strip : nil
+  end
+
+  # How many commits landed since the brief was generated. nil when there's
+  # no brief (nothing to be stale against) or the SHA is unknown to the repo.
+  def commits_behind_brief
+    return @commits_behind_brief if defined?(@commits_behind_brief)
+    @commits_behind_brief =
+      if brief_sha.blank? || local_path.blank?
+        nil
+      else
+        out, ok = Open3.capture2e("git", "-C", local_path, "rev-list", "--count", "#{brief_sha}..HEAD")
+        ok.success? ? out.strip.to_i : nil
+      end
+  end
+
+  def brief_stale? = (commits_behind_brief || 0) >= BRIEF_STALE_AT
+
+  # Grey → red interpolation over 0..BRIEF_STALE_AT commits behind, emitted
+  # as a validated hex into the button's inline style (mirrors Column#safe_color).
+  # Deep red once the brief is stale enough to over-anchor on.
+  def brief_staleness_color
+    behind = commits_behind_brief || 0
+    grey = [0x8a, 0x8a, 0x8a]
+    red  = [0xd4, 0x33, 0x33]
+    t = [behind.to_f / BRIEF_STALE_AT, 1.0].min
+    rgb = grey.zip(red).map { |g, r| (g + (r - g) * t).round }
+    format("#%02x%02x%02x", *rgb)
+  end
+
   # Cards currently waiting on the human, ordered by urgency — feeds the
   # attention inbox in the board header.
   def attention_cards

data/app/models/card.rb

@@ -11,7 +11,7 @@ class Card < ApplicationRecord
     "planning"  => %w[draft discussing archived],
     "execution" => %w[queued working needs_input blocked failed work_complete archived],
     "review"    => %w[in_review changes_requested approved archived],
-    "terminal"  => %w[done archived]
+    "terminal"  => %w[done blocked archived] # blocked: merge gate refused (CI red/pending)
   }.freeze
 
   belongs_to :board
@@ -29,6 +29,9 @@ class Card < ApplicationRecord
   validate :status_legal_for_column
 
   before_validation :assign_number_and_position, on: :create
+  # Optional git fields left blank on the new-card form arrive as "" — store
+  # them as nil so "no PR/branch" is one state, not two ("" renders footers).
+  normalizes :branch_name, :pr_url, with: ->(v) { v.strip.presence }
 
   after_commit -> { broadcast_refresh_to board }
 

data/app/models/column.rb

@@ -35,7 +35,12 @@ class Column < ApplicationRecord
   store_accessor :policy, :instructions, :model, :effort, :concurrency_limit,
                  :plan_approval, :budget_per_run_cents, :timeout_minutes,
                  :max_turns, :tools, :on_entry, :on_success, :color, :arrivals,
-                 :accepts_from
+                 :accepts_from, :footer
+
+  # Aggregations a footer row may compute over the column's cards (card #18).
+  # A compute key not listed here renders blank, so config that outruns the
+  # code degrades gracefully instead of erroring.
+  FOOTER_COMPUTES = %w[sum_cost sum_tokens count_cards].freeze
 
   # Only ever emit a validated hex color into inline styles.
   def safe_color
@@ -51,6 +56,15 @@ class Column < ApplicationRecord
     policy["ai"] != false
   end
 
+  # Worker shell access (execution columns). ON (default): the agent gets the
+  # full toolset — shell, git, everything — inside its workspace clone, which
+  # means it can also touch the host beyond the clone. OFF: file tools only
+  # (read/search/edit); it physically cannot execute commands, and Cardinal
+  # commits and pushes its edits for it.
+  def shell_access?
+    policy["shell"] != false
+  end
+
   # Which columns may move cards INTO this one (§ accept policy, card #15).
   # Stored as an array of column-id strings. EXPLICIT ONLY: an empty list
   # means this column accepts from nowhere — there is no permissive default.
@@ -58,6 +72,24 @@ class Column < ApplicationRecord
     Array(accepts_from).map(&:to_s).include?(source_column.id.to_s)
   end
 
+  # Rows rendered under the cards (card #18). Footer config is an array of
+  # {"label" => "Total cost:", "compute" => "sum_cost"} hashes; each row pairs
+  # static label text with an optional computed aggregate over this column's
+  # cards. Returns [] when unconfigured, so existing columns render no footer.
+  def footer_rows
+    rows = Array(footer).filter_map do |row|
+      label = row["label"].to_s
+      value = footer_value(row["compute"])
+      next if label.blank? && value.blank?
+      { label:, value: }
+    end
+    # AI columns advertise their active model as a final auto-row (card #32).
+    # Guarded on model presence so an AI column without one adds nothing,
+    # rather than emitting a "Model:" row with a blank value.
+    rows << { label: "Model:", value: model_short } if ai? && model.present?
+    rows
+  end
+
   # Start the next queued card when a run slot frees up. A queued card whose
   # run parked and already has its answer recorded resumes instead of
   # starting fresh.
@@ -90,6 +122,27 @@ class Column < ApplicationRecord
     execution? && concurrency_limit.present? && running_count >= concurrency_limit.to_i
   end
 
+  # Post-claim variant (§ races): a starter first claims working atomically,
+  # THEN checks — over-subscription reads as strictly more running than allowed.
+  def at_wip_limit_exceeded?
+    execution? && concurrency_limit.present? && running_count > concurrency_limit.to_i
+  end
+
+  # Aggregate a single footer row over the runs/cards in this column (card #18).
+  # Unknown keys return "" so the row shows just its static label.
+  def footer_value(compute)
+    case compute.to_s
+    when "sum_cost"
+      "$%.2f" % column_runs.sum(:cost)
+    when "sum_tokens"
+      ActiveSupport::NumberHelper.number_to_delimited(column_runs.sum("input_tokens + output_tokens"))
+    when "count_cards"
+      cards.count.to_s
+    else
+      ""
+    end
+  end
+
   # The built-in role contract for AI servicing this archetype — shown
   # read-only in the gear modal so the Instructions field is understood as
   # ADDING to this, never replacing it. Enforced in code, not editable.
@@ -131,4 +184,11 @@ class Column < ApplicationRecord
     when "terminal"  then "Closes it — PR merged and branch deleted, if there is one"
     end
   end
+
+  private
+
+  # Every run belonging to a card in this column, for footer aggregation.
+  def column_runs
+    Run.joins(agent_session: :card).where(cards: { column_id: id })
+  end
 end