cardinal-ai 0.2.5 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea33d976c3ebc53402438e5dae5e6b480842034e1a77a1c58142d62ad1f347e2
-  data.tar.gz: 7571417a375ab611c9345a6b2d7ab6cea33233e668d90414edae44ea2d116048
+  metadata.gz: '079e999400eeaa39a8e7f7d8efdc4b3b114923cf0aaf190dcd15a6117a97d7b2'
+  data.tar.gz: 61343cc2e5c42fbf43f3eeb223da83af60d1e634f8424e69d032c9afd287aa02
 SHA512:
-  metadata.gz: db9ec21facb032331fd8686f772e1c1313e0e84388f675eb723e92847c0c7638325d2af5ff8d392f2536c292d0929a79f64e53f040ef1206bb74097477c1f9e1
-  data.tar.gz: c290a471053fc66929db5fe9b3219bb49dc85f2b953b4a33beab0878e261d7ed4e815dc5b1b57ca9f8346f2ba9a7e73f7607a30f1af08e09a6665311dfdd6811
+  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

@@ -79,6 +79,14 @@ a { color: var(--blue); text-decoration: none; }
   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); }

data/app/controllers/boards_controller.rb

@@ -5,11 +5,14 @@ class BoardsController < ApplicationController
 
   # 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. Ignored if a
-  # dive is already running.
+  # 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!
-    unless board.brief_working?
+    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)
@@ -17,6 +20,39 @@ class BoardsController < ApplicationController
     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
@@ -49,7 +85,20 @@ class BoardsController < ApplicationController
       ["Already up to date", true]
     else
       count, = Open3.capture2e("git", "-C", repo, "rev-list", "--count", "#{before.strip}..#{after.strip}")
-      ["Pulled #{helpers.pluralize(count.strip.to_i, "new commit")}", true]
+      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,
-      :footer_text, 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

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.
@@ -94,7 +106,11 @@ class Board < ApplicationRecord
   # underneath later without a migration.
   BRIEF_STALE_AT = 10 # commits behind → the "refresh me" red/flashing state
 
-  def brief_path = Rails.root.join(".cardinal", "repo-brief.md")
+  # 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)

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

data/app/models/column.rb

@@ -56,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.
@@ -113,6 +122,12 @@ 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)

data/app/services/agent/runner.rb

@@ -30,6 +30,21 @@ module Agent
       - Finish with a concise report: what you did, what to check, any open questions.
     RULES
 
+    # Column shell access OFF: the agent can read, search, and edit — nothing
+    # else. Enforced by the CLI tool list, not just these words.
+    RESTRICTED_EXECUTE_RULES = <<~RULES.freeze
+      ## Rules
+      - You have FILE TOOLS ONLY: read, search, edit, write. You cannot run shell
+        commands or git — do not attempt to; Cardinal commits and pushes your edits for you.
+      - Work only inside this repository checkout (you are already on the card's branch).
+      - Stay strictly within the card's scope. Prefer the smallest reasonable interpretation and note assumptions.
+      - If something must be RUN to finish the job (tests, generators, installs), do the file
+        work, then list the exact commands in your final report for the user to run.
+      - If you are blocked on a decision only the user can make, output a single line starting with
+        "QUESTION:" followed by the question, then stop immediately. Do not guess on genuinely ambiguous choices.
+      - Finish with a concise report: what you did, what to check, any open questions.
+    RULES
+
     def self.start(run) = new(run).start
     def self.resume(run, message, approve: false) = new(run).resume(message, approve: approve)
 
@@ -59,7 +74,7 @@ module Agent
       begin_segment!
       if run.phase == "plan" && approve
         run.update!(phase: "execute")
-        stream_agent(prompt: "Your plan is approved — execute it now.\n\n#{EXECUTE_RULES}",
+        stream_agent(prompt: "Your plan is approved — execute it now.\n\n#{execute_rules}",
                      mode: "execute", resuming: true)
       elsif run.phase == "plan"
         stream_agent(prompt: "Feedback on your plan:\n\n#{message}\n\nRevise the plan accordingly, present it, and stop again for approval. Stay in read-only mode.",
@@ -106,6 +121,9 @@ module Agent
         cmd += ["--max-turns", "3", "--tools", ""]
       else
         cmd += ["--max-turns", (column.max_turns.presence || DEFAULT_EXECUTE_TURNS).to_s]
+        # Shell access off: restrict to file tools — the sandbox is the tool
+        # list itself, not a request in the prompt.
+        cmd += ["--tools", "Read,Glob,Grep,Edit,Write"] unless column.shell_access?
       end
       cmd += ["--model", column.model] if column.model.present?
       cmd += ["--effort", column.effort] if column.effort.present?
@@ -205,6 +223,11 @@ module Agent
 
     def conclude_execute(workspace, result)
       accumulate_usage(result)
+      # A shell-less agent cannot commit its own edits — do it for it before
+      # any commit counting or salvage below.
+      unless column.shell_access?
+        workspace.commit_all!("Card ##{card.number}: #{card.title.truncate(60)}\n\nCommitted by Cardinal for a shell-less agent.")
+      end
       unless result[:success]
         # Budget exhaustion isn't failure — park and offer to continue (§8).
         # The session survives; an answer resumes it with a fresh turn budget.
@@ -334,10 +357,14 @@ module Agent
         #{conversation_excerpt.presence || "(none)"}
 
         #{"## Column instructions\n#{column.instructions}\n" if column.instructions.present?}
-        #{EXECUTE_RULES}
+        #{execute_rules}
       PROMPT
     end
 
+    def execute_rules
+      column.shell_access? ? EXECUTE_RULES : RESTRICTED_EXECUTE_RULES
+    end
+
     def plan_prompt
       <<~PROMPT
         You are the dedicated worker agent for card ##{card.number} of the Cardinal board: "#{card.title}".

data/app/services/agent/workspace.rb

@@ -74,6 +74,15 @@ module Agent
         end
       end
 
+      # Shell-less agents (column shell access off) edit files but cannot run
+      # git — the runner commits on their behalf when a segment ends.
+      def commit_all!(message)
+        return false if git_out(path, "status", "--porcelain").strip.empty?
+        git!(path, "add", "-A")
+        git!(path, "commit", "--quiet", "-m", message)
+        true
+      end
+
       # How the runner should spawn the agent process for this workspace.
       def agent_spawn(cmd) = [cmd, { chdir: path.to_s }]
 

data/app/views/boards/brief.html.erb

@@ -0,0 +1,48 @@
+<%= turbo_frame_tag "modal", data: { turbo_permanent: true } do %>
+  <div class="modal-backdrop" data-controller="modal" data-action="click->modal#backdrop">
+    <div class="modal modal-sm">
+      <header class="modal-header">
+        <h1>🔍 Repo brief</h1>
+        <button type="button" class="modal-close" data-action="modal#close" title="Close (Esc)">✕</button>
+      </header>
+      <div class="modal-body">
+        <p class="hint">
+          A deep dive is a one-shot, read-only agent (Read/Glob/Grep only — it cannot change
+          anything) that maps this repo into the brief below. Every worker agent gets the brief
+          in its prompt, so runs skip re-exploring the codebase. It costs one bounded AI call
+          using the planning column's model.
+        </p>
+
+        <% if @board.brief? %>
+          <p class="brief-meta">
+            Generated <%= @board.brief_generated_at&.strftime("%b %-d, %H:%M") %>
+            from <code><%= @board.brief_sha&.first(7) %></code>
+            with <%= @board.brief_model %>
+            <% behind = @board.commits_behind_brief %>
+            <% if behind&.positive? %>
+              · <span class="brief-behind"><%= pluralize(behind, "commit") %> behind HEAD</span>
+            <% else %>
+              · current with HEAD
+            <% end %>
+          </p>
+
+          <div class="brief-content">
+            <%= render_markdown(@board.repo_brief.to_s) %>
+          </div>
+        <% else %>
+          <p class="brief-meta">No brief yet — run a deep dive from the topbar.</p>
+        <% end %>
+
+        <div class="card-edit-actions">
+          <%= button_to "↻ Regenerate brief", deep_dive_board_path(force: 1),
+                form: { data: { turbo_frame: "_top" } },
+                disabled: @board.brief_working? %>
+        </div>
+        <p class="hint">
+          Regenerating replaces the brief. When the brief already matches HEAD the deep dive
+          button won't re-run it — only this button forces a fresh dive.
+        </p>
+      </div>
+    </div>
+  </div>
+<% end %>

data/app/views/boards/edit.html.erb

@@ -0,0 +1,29 @@
+<%= turbo_frame_tag "modal", data: { turbo_permanent: true } do %>
+  <div class="modal-backdrop" data-controller="modal" data-action="click->modal#backdrop">
+    <div class="modal modal-sm" data-controller="autosave">
+      <header class="modal-header">
+        <h1>⚙ Board settings
+            <span class="autosave-status" data-autosave-target="status"></span></h1>
+        <button type="button" class="modal-close" data-action="modal#close" title="Close (Esc)">✕</button>
+      </header>
+      <div class="modal-body">
+        <div id="board-form-errors"></div>
+
+        <%= form_with model: @board, url: board_path(autosave: 1), class: "card-edit",
+              data: { autosave_target: "form" } do |f| %>
+          <label>Board name</label>
+          <%= f.text_field :name %>
+
+          <label>Default branch <%= info_tip("The branch agents fork card branches from and Done merges pull requests toward. Detected from the repo at first boot; fix it here if that guess was wrong.") %></label>
+          <%= f.text_field :default_branch, placeholder: "main" %>
+        <% end %>
+
+        <label>Repository</label>
+        <p class="locked-field"><code><%= @board.repo_url.presence || "(no remote)" %></code></p>
+
+        <label>Local checkout</label>
+        <p class="locked-field"><code><%= @board.local_path %></code></p>
+      </div>
+    </div>
+  </div>
+<% end %>

data/app/views/boards/show.html.erb

@@ -2,30 +2,42 @@
 
 <header class="topbar">
   <div class="topbar-left">
-    <h1>Cardinal AI <span class="sep">▸</span> <%= @board.name %></h1>
+    <h1>Cardinal AI <span class="sep">▸</span> <span id="board-name"><%= @board.name %></span></h1>
+    <%= link_to "⚙", edit_board_path, data: { turbo_frame: "modal" }, class: "gear",
+          title: "Board settings — name, default branch" %>
     <%= button_to "⇣ Pull", pull_board_path, form_class: "pull-form",
           form: { title: "git pull --ff-only in #{@board.local_path} — fetch what Done has merged" },
           data: { turbo_submits_with: "⇣ Pulling…" }, class: "theme-toggle" %>
-    <span id="repo-pull-status"></span>
-  </div>
-  <div class="topbar-right">
     <%# Repo deep dive (card #12): one-shot read-only mapping of the repo, stored
         as a brief and injected into worker prompts. The button greys→reds as the
-        brief falls behind HEAD; a stale brief over-anchors, so it nags at 10+. %>
+        brief falls behind HEAD; a stale brief over-anchors, so it nags at 10+.
+        Once a brief exists the button opens it for inspection (the modal holds
+        the Regenerate action) — a fresh brief is never silently re-run. %>
     <% behind = @board.commits_behind_brief %>
-    <%= button_to deep_dive_board_path,
-          class: "deep-dive#{' stale-critical' if @board.brief_stale?}#{' working' if @board.brief_working?}",
-          disabled: @board.brief_working?,
-          style: @board.brief? ? "color: #{@board.brief_staleness_color}; border-color: #{@board.brief_staleness_color}" : nil,
-          title: @board.brief? ? "Repo brief from #{@board.brief_sha&.first(7)} · #{@board.brief_generated_at&.to_date}" : "Map this repo into a brief agents reuse — saves exploration on every run" do %>
-      <% if @board.brief_working? %>
+    <% if @board.brief_working? %>
+      <button type="button" class="deep-dive working" disabled>
         <span class="pulse-dot"></span> Deep dive · working…
-      <% elsif behind&.positive? %>
-        🔍 Deep dive · <%= behind %> commit<%= "s" if behind != 1 %> behind
-      <% else %>
+      </button>
+    <% elsif @board.brief? %>
+      <%= link_to brief_board_path, data: { turbo_frame: "modal" },
+            class: "deep-dive#{' stale-critical' if @board.brief_stale?}",
+            style: "color: #{@board.brief_staleness_color}; border-color: #{@board.brief_staleness_color}",
+            title: "Repo brief from #{@board.brief_sha&.first(7)} · #{@board.brief_generated_at&.to_date} — click to inspect" do %>
+        <% if behind&.positive? %>
+          🔍 Repo brief · <%= behind %> commit<%= "s" if behind != 1 %> behind
+        <% else %>
+          🔍 Repo brief
+        <% end %>
+      <% end %>
+    <% else %>
+      <%= button_to deep_dive_board_path, class: "deep-dive",
+            title: "Map this repo into a brief agents reuse — saves exploration on every run" do %>
         🔍 Deep dive
       <% end %>
     <% end %>
+    <span id="repo-pull-status"></span>
+  </div>
+  <div class="topbar-right">
     <button type="button" class="theme-toggle"
             data-controller="theme" data-action="theme#toggle">☀ Light</button>
     <% if ENV["CARDINAL_AUTH"].present? %>

data/app/views/columns/edit.html.erb

@@ -105,6 +105,14 @@
               <%= info_tip("The agent's first pass is read-only: it explores and proposes a plan, then waits. You approve with one click or reply to redirect. Your main safety rail.") %>
             </label>
 
+            <% if @column.execution? %>
+              <label class="check-row">
+                <%= f.check_box :shell, checked: @column.shell_access? %>
+                Shell access — the agent may run commands (tests, builds, git)
+                <%= info_tip("Unchecked: the agent gets file tools only (read, search, edit, write) and physically cannot execute anything — Cardinal commits and pushes its edits for it. Safer, but it can't run your tests or generators, and the agent process runs on this machine either way.") %>
+              </label>
+            <% end %>
+
             </div>
 
             <label>On-entry rules <%= info_tip("What happens when a card lands in this column, in plain English — e.g. \"start the worker agent\" or \"have an AI suggest tags and a better title\". Cardinal compiles it to rule actions when you save. Blank = the archetype's default behavior shown below.") %></label>

data/config/application.rb

@@ -22,7 +22,7 @@ require "securerandom"
 
 if ENV["CARDINAL_GEM"] == "1"
   # Installed-gem mode: no Bundler — load what Bundler.require would have.
-  %w[propshaft importmap-rails turbo-rails stimulus-rails redcarpet sqlite3].each { |g| require g }
+  %w[propshaft importmap-rails turbo-rails stimulus-rails redcarpet sqlite3 solid_queue solid_cable].each { |g| require g }
 else
   # Require the gems listed in Gemfile, including any gems
   # you've limited to :test, :development, or :production.

data/config/cable.yml

@@ -1,5 +1,13 @@
+# Jobs run in SolidQueue worker processes (forked by the puma plugin), so
+# Turbo broadcasts cross process boundaries — the async adapter can't carry
+# them. SolidCable (SQLite-backed pubsub) works in dev and prod alike.
 development:
-  adapter: async
+  adapter: solid_cable
+  connects_to:
+    database:
+      writing: cable
+  polling_interval: 0.1.seconds
+  message_retention: 1.day
 
 test:
   adapter: test

data/config/database.yml

@@ -6,8 +6,17 @@ default: &default
   timeout: 5000
 
 development:
-  <<: *default
-  database: <%= ENV.fetch("CARDINAL_DATA_DIR", ".cardinal") %>/cardinal.db
+  primary:
+    <<: *default
+    database: <%= ENV.fetch("CARDINAL_DATA_DIR", ".cardinal") %>/cardinal.db
+  queue:
+    <<: *default
+    database: <%= ENV.fetch("CARDINAL_DATA_DIR", ".cardinal") %>/queue.sqlite3
+    migrations_paths: db/queue_migrate
+  cable:
+    <<: *default
+    database: <%= ENV.fetch("CARDINAL_DATA_DIR", ".cardinal") %>/cable.sqlite3
+    migrations_paths: db/cable_migrate
 
 test:
   <<: *default

data/config/environments/development.rb

@@ -1,6 +1,11 @@
 require "active_support/core_ext/integer/time"
 
 Rails.application.configure do
+  # Durable jobs even in dev (dogfooding runs real agent work): SolidQueue in
+  # its own SQLite db; the puma plugin supervises workers — no extra service.
+  config.active_job.queue_adapter = :solid_queue
+  config.solid_queue.connects_to = { database: { writing: :queue } }
+
   # Settings specified here will take precedence over those in config/application.rb.
 
   # Make code changes take effect immediately without server restart.

data/config/environments/production.rb

@@ -50,7 +50,8 @@ Rails.application.configure do
   # config.cache_store = :mem_cache_store
 
   # Replace the default in-process and non-durable queuing backend for Active Job.
-  # config.active_job.queue_adapter = :resque
+  config.active_job.queue_adapter = :solid_queue
+  config.solid_queue.connects_to = { database: { writing: :queue } }
 
   # Ignore bad email addresses and do not raise email delivery errors.
   # Set this to true and configure the email server for immediate delivery to raise delivery errors.

data/config/puma.rb

@@ -35,7 +35,7 @@ port ENV.fetch("PORT", 3000)
 plugin :tmp_restart
 
 # Run the Solid Queue supervisor inside of Puma for single-server deployments.
-plugin :solid_queue if ENV["SOLID_QUEUE_IN_PUMA"]
+plugin :solid_queue if ENV.fetch("SOLID_QUEUE_IN_PUMA", "1") == "1" && !ENV["RAILS_ENV"].to_s.start_with?("test")
 
 # Specify the PID file. Defaults to tmp/pids/server.pid in development.
 # In other environments, only set the PID file if requested.

data/config/queue.yml

@@ -0,0 +1,18 @@
+default: &default
+  dispatchers:
+    - polling_interval: 1
+      batch_size: 500
+  workers:
+    - queues: "*"
+      threads: 3
+      processes: <%= ENV.fetch("JOB_CONCURRENCY", 1) %>
+      polling_interval: 0.1
+
+development:
+  <<: *default
+
+test:
+  <<: *default
+
+production:
+  <<: *default

data/config/recurring.yml

@@ -0,0 +1,15 @@
+# examples:
+#   periodic_cleanup:
+#     class: CleanSoftDeletedRecordsJob
+#     queue: background
+#     args: [ 1000, { batch_size: 500 } ]
+#     schedule: every hour
+#   periodic_cleanup_with_command:
+#     command: "SoftDeletedRecord.due.delete_all"
+#     priority: 2
+#     schedule: at 5am every day
+
+production:
+  clear_solid_queue_finished_jobs:
+    command: "SolidQueue::Job.clear_finished_in_batches(sleep_between_batches: 0.3)"
+    schedule: every hour at minute 12

data/config/routes.rb

@@ -1,9 +1,10 @@
 Rails.application.routes.draw do
   root "boards#show"
 
-  resource :board, only: :show do
+  resource :board, only: [:show, :edit, :update] do
     post :deep_dive
     post :pull
+    get :brief
   end
   resources :cards, only: [:new, :create, :show, :update, :destroy] do
     member do

data/db/cable_schema.rb

@@ -0,0 +1,11 @@
+ActiveRecord::Schema[7.1].define(version: 1) do
+  create_table "solid_cable_messages", force: :cascade do |t|
+    t.binary "channel", limit: 1024, null: false
+    t.binary "payload", limit: 536870912, null: false
+    t.datetime "created_at", null: false
+    t.integer "channel_hash", limit: 8, null: false
+    t.index ["channel"], name: "index_solid_cable_messages_on_channel"
+    t.index ["channel_hash"], name: "index_solid_cable_messages_on_channel_hash"
+    t.index ["created_at"], name: "index_solid_cable_messages_on_created_at"
+  end
+end

data/db/queue_schema.rb

@@ -0,0 +1,129 @@
+ActiveRecord::Schema[7.1].define(version: 1) do
+  create_table "solid_queue_blocked_executions", force: :cascade do |t|
+    t.bigint "job_id", null: false
+    t.string "queue_name", null: false
+    t.integer "priority", default: 0, null: false
+    t.string "concurrency_key", null: false
+    t.datetime "expires_at", null: false
+    t.datetime "created_at", null: false
+    t.index [ "concurrency_key", "priority", "job_id" ], name: "index_solid_queue_blocked_executions_for_release"
+    t.index [ "expires_at", "concurrency_key" ], name: "index_solid_queue_blocked_executions_for_maintenance"
+    t.index [ "job_id" ], name: "index_solid_queue_blocked_executions_on_job_id", unique: true
+  end
+
+  create_table "solid_queue_claimed_executions", force: :cascade do |t|
+    t.bigint "job_id", null: false
+    t.bigint "process_id"
+    t.datetime "created_at", null: false
+    t.index [ "job_id" ], name: "index_solid_queue_claimed_executions_on_job_id", unique: true
+    t.index [ "process_id", "job_id" ], name: "index_solid_queue_claimed_executions_on_process_id_and_job_id"
+  end
+
+  create_table "solid_queue_failed_executions", force: :cascade do |t|
+    t.bigint "job_id", null: false
+    t.text "error"
+    t.datetime "created_at", null: false
+    t.index [ "job_id" ], name: "index_solid_queue_failed_executions_on_job_id", unique: true
+  end
+
+  create_table "solid_queue_jobs", force: :cascade do |t|
+    t.string "queue_name", null: false
+    t.string "class_name", null: false
+    t.text "arguments"
+    t.integer "priority", default: 0, null: false
+    t.string "active_job_id"
+    t.datetime "scheduled_at"
+    t.datetime "finished_at"
+    t.string "concurrency_key"
+    t.datetime "created_at", null: false
+    t.datetime "updated_at", null: false
+    t.index [ "active_job_id" ], name: "index_solid_queue_jobs_on_active_job_id"
+    t.index [ "class_name" ], name: "index_solid_queue_jobs_on_class_name"
+    t.index [ "finished_at" ], name: "index_solid_queue_jobs_on_finished_at"
+    t.index [ "queue_name", "finished_at" ], name: "index_solid_queue_jobs_for_filtering"
+    t.index [ "scheduled_at", "finished_at" ], name: "index_solid_queue_jobs_for_alerting"
+  end
+
+  create_table "solid_queue_pauses", force: :cascade do |t|
+    t.string "queue_name", null: false
+    t.datetime "created_at", null: false
+    t.index [ "queue_name" ], name: "index_solid_queue_pauses_on_queue_name", unique: true
+  end
+
+  create_table "solid_queue_processes", force: :cascade do |t|
+    t.string "kind", null: false
+    t.datetime "last_heartbeat_at", null: false
+    t.bigint "supervisor_id"
+    t.integer "pid", null: false
+    t.string "hostname"
+    t.text "metadata"
+    t.datetime "created_at", null: false
+    t.string "name", null: false
+    t.index [ "last_heartbeat_at" ], name: "index_solid_queue_processes_on_last_heartbeat_at"
+    t.index [ "name", "supervisor_id" ], name: "index_solid_queue_processes_on_name_and_supervisor_id", unique: true
+    t.index [ "supervisor_id" ], name: "index_solid_queue_processes_on_supervisor_id"
+  end
+
+  create_table "solid_queue_ready_executions", force: :cascade do |t|
+    t.bigint "job_id", null: false
+    t.string "queue_name", null: false
+    t.integer "priority", default: 0, null: false
+    t.datetime "created_at", null: false
+    t.index [ "job_id" ], name: "index_solid_queue_ready_executions_on_job_id", unique: true
+    t.index [ "priority", "job_id" ], name: "index_solid_queue_poll_all"
+    t.index [ "queue_name", "priority", "job_id" ], name: "index_solid_queue_poll_by_queue"
+  end
+
+  create_table "solid_queue_recurring_executions", force: :cascade do |t|
+    t.bigint "job_id", null: false
+    t.string "task_key", null: false
+    t.datetime "run_at", null: false
+    t.datetime "created_at", null: false
+    t.index [ "job_id" ], name: "index_solid_queue_recurring_executions_on_job_id", unique: true
+    t.index [ "task_key", "run_at" ], name: "index_solid_queue_recurring_executions_on_task_key_and_run_at", unique: true
+  end
+
+  create_table "solid_queue_recurring_tasks", force: :cascade do |t|
+    t.string "key", null: false
+    t.string "schedule", null: false
+    t.string "command", limit: 2048
+    t.string "class_name"
+    t.text "arguments"
+    t.string "queue_name"
+    t.integer "priority", default: 0
+    t.boolean "static", default: true, null: false
+    t.text "description"
+    t.datetime "created_at", null: false
+    t.datetime "updated_at", null: false
+    t.index [ "key" ], name: "index_solid_queue_recurring_tasks_on_key", unique: true
+    t.index [ "static" ], name: "index_solid_queue_recurring_tasks_on_static"
+  end
+
+  create_table "solid_queue_scheduled_executions", force: :cascade do |t|
+    t.bigint "job_id", null: false
+    t.string "queue_name", null: false
+    t.integer "priority", default: 0, null: false
+    t.datetime "scheduled_at", null: false
+    t.datetime "created_at", null: false
+    t.index [ "job_id" ], name: "index_solid_queue_scheduled_executions_on_job_id", unique: true
+    t.index [ "scheduled_at", "priority", "job_id" ], name: "index_solid_queue_dispatch_all"
+  end
+
+  create_table "solid_queue_semaphores", force: :cascade do |t|
+    t.string "key", null: false
+    t.integer "value", default: 1, null: false
+    t.datetime "expires_at", null: false
+    t.datetime "created_at", null: false
+    t.datetime "updated_at", null: false
+    t.index [ "expires_at" ], name: "index_solid_queue_semaphores_on_expires_at"
+    t.index [ "key", "value" ], name: "index_solid_queue_semaphores_on_key_and_value"
+    t.index [ "key" ], name: "index_solid_queue_semaphores_on_key", unique: true
+  end
+
+  add_foreign_key "solid_queue_blocked_executions", "solid_queue_jobs", column: "job_id", on_delete: :cascade
+  add_foreign_key "solid_queue_claimed_executions", "solid_queue_jobs", column: "job_id", on_delete: :cascade
+  add_foreign_key "solid_queue_failed_executions", "solid_queue_jobs", column: "job_id", on_delete: :cascade
+  add_foreign_key "solid_queue_ready_executions", "solid_queue_jobs", column: "job_id", on_delete: :cascade
+  add_foreign_key "solid_queue_recurring_executions", "solid_queue_jobs", column: "job_id", on_delete: :cascade
+  add_foreign_key "solid_queue_scheduled_executions", "solid_queue_jobs", column: "job_id", on_delete: :cascade
+end

data/exe/cardinal

@@ -106,6 +106,9 @@ end
 # scaffolding inside the engine/gem directory — read-only for sudo installs).
 ENV["PIDFILE"] = File.join(TARGET, ".cardinal", "tmp", "server.pid")
 ENV["CARDINAL_SWEEPER"] = "1" # the sweeper initializer keys off Rails::Server otherwise
+# Localhost only: the board drives your logged-in gh/claude sessions, so it
+# must not be reachable by others on the network. CARDINAL_HOST=0.0.0.0
+# deliberately exposes it (e.g. to browse from a phone on your LAN).
 exec(RbConfig.ruby, "-S", "puma",
-     "-b", "tcp://0.0.0.0:#{ENV["PORT"]}",
+     "-b", "tcp://#{ENV.fetch("CARDINAL_HOST", "127.0.0.1")}:#{ENV["PORT"]}",
      File.join(HOME_DIR, "config.ru"))

data/lib/cardinal/version.rb

@@ -1,3 +1,3 @@
 module Cardinal
-  VERSION = "0.2.5"
+  VERSION = "0.2.6"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cardinal-ai
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.2.6
 platform: ruby
 authors:
 - Jason Ellis
@@ -121,6 +121,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.6'
+- !ruby/object:Gem::Dependency
+  name: solid_queue
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: solid_cable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 description: 'Cardinal AI is a local, per-repo AI Kanban tool: columns are policies,
   cards become Claude-powered worker agents, and work ships as pull requests. Run
   `cardinal` inside any git repository to get a board for it at http://localhost:4000.'
@@ -178,6 +206,8 @@ files:
 - app/services/rules.rb
 - app/services/rules/compiler.rb
 - app/services/run_sweeper.rb
+- app/views/boards/brief.html.erb
+- app/views/boards/edit.html.erb
 - app/views/boards/show.html.erb
 - app/views/cards/_card.html.erb
 - app/views/cards/_detail.html.erb
@@ -217,13 +247,17 @@ files:
 - config/initializers/run_sweeper.rb
 - config/locales/en.yml
 - config/puma.rb
+- config/queue.yml
+- config/recurring.yml
 - config/routes.rb
 - config/storage.yml
+- db/cable_schema.rb
 - db/migrate/20260703000001_create_cardinal_schema.rb
 - db/migrate/20260703000002_add_agent_runner_fields.rb
 - db/migrate/20260704000001_add_parent_to_cards.rb
 - db/migrate/20260704000002_add_assistant_session_to_cards.rb
 - db/migrate/20260704120000_add_repo_brief_to_boards.rb
+- db/queue_schema.rb
 - db/seeds.rb
 - docker/agent/Dockerfile
 - exe/cardinal