diff --git a/.github/eval/gbrain-eval.mjs b/.github/eval/gbrain-eval.mjs
new file mode 100644
index 00000000..21344743
--- /dev/null
+++ b/.github/eval/gbrain-eval.mjs
@@ -0,0 +1,178 @@
+/**
+ * gbrain Knowledge Persistence Eval
+ *
+ * Writes 5 apra-fleet facts to gbrain (PGLite — zero external deps),
+ * reads them back by slug, and verifies the content is intact.
+ *
+ * This proves:
+ *   1. `apra-fleet install --with-gbrain` produces a working gbrain install
+ *   2. gbrain persists knowledge durably in PGLite (no API key, no server)
+ *   3. Knowledge is faithfully retrievable (5/5 roundtrip)
+ *
+ * Exit 0 = PASS (5/5 roundtrip), Exit 1 = FAIL.
+ * Writes a Markdown scorecard to $GITHUB_STEP_SUMMARY when running in CI.
+ */
+
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import fs from 'fs';
+
+// ---------------------------------------------------------------------------
+// Test dataset — 5 apra-fleet facts
+// ---------------------------------------------------------------------------
+const FACTS = [
+  {
+    id: 'port',
+    content: 'The apra-fleet MCP server listens on port 3000 by default.',
+    keywords: ['port 3000', '3000'],
+  },
+  {
+    id: 'ssh-remote',
+    content: 'Fleet members can be local agents or SSH remote machines registered with a hostname and username.',
+    keywords: ['SSH remote', 'hostname'],
+  },
+  {
+    id: 'execute-prompt',
+    content: 'The execute_prompt tool dispatches a task to a Claude Code agent and waits for its response.',
+    keywords: ['execute_prompt', 'Claude Code'],
+  },
+  {
+    id: 'pglite',
+    content: 'gbrain uses PGLite for local storage — no external database server is required when running in local mode.',
+    keywords: ['PGLite', 'no external database'],
+  },
+  {
+    id: 'reviewer',
+    content: 'The fleet reviewer template checks code for security vulnerabilities and test coverage before approving.',
+    keywords: ['security vulnerabilities', 'test coverage'],
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function extractText(result) {
+  if (!result || !result.content) return '';
+  return result.content
+    .filter(c => c.type === 'text')
+    .map(c => c.text)
+    .join('\n');
+}
+
+function extractJson(text) {
+  try { return JSON.parse(text); } catch { return null; }
+}
+
+function verifyContent(responseText, fact) {
+  const parsed = extractJson(responseText);
+  // get_page returns JSON with compiled_truth or slug fields
+  const candidate = parsed
+    ? JSON.stringify(parsed).toLowerCase()
+    : responseText.toLowerCase();
+  return fact.keywords.some(kw => candidate.includes(kw.toLowerCase()));
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+async function main() {
+  const gbrain = process.env.GBRAIN_CMD || 'gbrain';
+
+  const transport = new StdioClientTransport({
+    command: gbrain,
+    args: ['serve'],
+    env: {
+      ...process.env,
+      PATH: `${process.env.HOME}/.bun/bin:${process.env.PATH || ''}`,
+    },
+  });
+
+  const client = new Client({ name: 'gbrain-eval', version: '1.0.0' }, { capabilities: {} });
+
+  console.log('Connecting to gbrain MCP server...');
+  await client.connect(transport);
+
+  // Print server identity
+  try {
+    const identity = await client.callTool({ name: 'get_brain_identity', arguments: {} });
+    console.log(`Connected: ${extractText(identity).slice(0, 120)}\n`);
+  } catch {
+    console.log('Connected.\n');
+  }
+
+  // -- Seed ------------------------------------------------------------------
+  console.log('=== Writing facts (put_page) ===');
+  const writeResults = [];
+  for (const fact of FACTS) {
+    const result = await client.callTool({
+      name: 'put_page',
+      arguments: {
+        slug: `eval/${fact.id}`,
+        content: `---\ntags: [eval, apra-fleet]\n---\n${fact.content}`,
+      },
+    });
+    const text = extractText(result);
+    const parsed = extractJson(text);
+    const status = parsed?.status ?? text.slice(0, 40);
+    const ok = text.includes('created') || text.includes('updated');
+    writeResults.push({ id: fact.id, ok, status });
+    console.log(`  [${ok ? 'OK  ' : 'FAIL'}] ${fact.id}: ${status}`);
+  }
+
+  // -- Read back -------------------------------------------------------------
+  console.log('\n=== Reading facts back (get_page) ===');
+  const rows = [];
+
+  for (const fact of FACTS) {
+    const result = await client.callTool({
+      name: 'get_page',
+      arguments: { slug: `eval/${fact.id}` },
+    });
+    const text = extractText(result);
+    const match = verifyContent(text, fact);
+    rows.push({ id: fact.id, match, snippet: text.slice(0, 120).replace(/\n/g, ' ') });
+    console.log(`  [${match ? 'MATCH' : 'MISS '}] ${fact.id}`);
+    if (!match) console.log(`          response: ${text.slice(0, 120)}`);
+  }
+
+  await client.close();
+
+  // -- Score -----------------------------------------------------------------
+  const hits = rows.filter(r => r.match).length;
+  const total = rows.length;
+  const pct = Math.round((hits / total) * 100);
+  const pass = hits === total; // 5/5 required for persistence eval
+
+  // -- Report ----------------------------------------------------------------
+  const lines = [
+    '## gbrain Knowledge Persistence Eval',
+    '',
+    `**Score: ${hits}/${total} (${pct}%) — ${pass ? '✅ PASS' : '❌ FAIL'}**`,
+    '',
+    '| Fact | Content slug | Stored + Retrieved |',
+    '|------|-------------|-------------------|',
+    ...rows.map(r => `| \`${r.id}\` | \`eval/${r.id}\` | ${r.match ? '✅ OK' : '❌ FAIL'} |`),
+    '',
+    '### What this demonstrates',
+    '- `apra-fleet install --with-gbrain` produces a working gbrain install',
+    '- gbrain persists knowledge in **PGLite** — zero external deps, no API key',
+    '- Knowledge is faithfully retrieved by slug (deterministic roundtrip)',
+    `- Fleet agents with \`gbrain: true\` get persistent memory across sessions`,
+  ];
+
+  const report = lines.join('\n');
+  console.log('\n' + report);
+
+  const summaryFile = process.env.GITHUB_STEP_SUMMARY;
+  if (summaryFile) {
+    fs.appendFileSync(summaryFile, report + '\n');
+    console.log('\nScorecard written to step summary.');
+  }
+
+  process.exit(pass ? 0 : 1);
+}
+
+main().catch(err => {
+  console.error('Eval error:', err.message || err);
+  process.exit(1);
+});
diff --git a/.github/workflows/fleet-e2e-compat.yml b/.github/workflows/fleet-e2e-compat.yml
new file mode 100644
index 00000000..62461140
--- /dev/null
+++ b/.github/workflows/fleet-e2e-compat.yml
@@ -0,0 +1,338 @@
+name: Fleet E2E Test Suite (compat)
+
+on:
+  workflow_dispatch:
+    inputs:
+      suite:
+        description: 'Test suite to run (s1-s6). Start with s1 to validate setup.'
+        required: true
+        type: choice
+        options: [s1, s2, s3, s4, s5, s6]
+
+jobs:
+  e2e:
+    name: 'Fleet E2E – ${{ inputs.suite }}'
+    # Runner label is derived from suites.json pm.runner field.
+    # Each self-hosted runner must be registered with label fleet-windows / fleet-linux / fleet-macos.
+    runs-on:
+      - self-hosted
+      - ${{ inputs.suite == 's1' && 'fleet-windows' || inputs.suite == 's2' && 'fleet-linux' || inputs.suite == 's3' && 'fleet-macos' || inputs.suite == 's4' && 'fleet-windows' || inputs.suite == 's5' && 'fleet-linux' || 'fleet-macos' }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      # ── Create run directory ───────────────────────────────────────────────
+      # All test artifacts go here — never inside the repo checkout.
+      # Sibling of the checkout: <runner-work>/<repo>/testRuns/<run_id>-<attempt>
+      - name: Create run directory
+        shell: bash
+        run: |
+          RUN_DIR="$(dirname "$GITHUB_WORKSPACE")/testRuns/${{ github.run_id }}-${{ github.run_attempt }}"
+          mkdir -p "$RUN_DIR/logs"
+          echo "RUN_DIR=$RUN_DIR" >> "$GITHUB_ENV"
+          echo "Run directory: $RUN_DIR"
+
+      # ── Step 1: Load suite config ──────────────────────────────────────────
+      - name: Check runner prerequisites
+        shell: bash
+        run: |
+          jq --version || { echo "::error::jq is not installed on this runner"; exit 1; }
+
+      - name: Load suite config
+        id: suite
+        shell: bash
+        run: |
+          SUITE='${{ inputs.suite }}'
+          CONFIG=$(cat .github/e2e/suites.json)
+          MEMBERS=$(cat .github/e2e/members.json)
+
+          PM_PROVIDER=$(echo $CONFIG | jq -r ".suites.$SUITE.pm.provider")
+          PM_OS=$(echo $CONFIG      | jq -r ".suites.$SUITE.pm.os")
+          DOER_OS=$(echo $CONFIG    | jq -r ".suites.$SUITE.doer.os")
+          DOER_PROV=$(echo $CONFIG  | jq -r ".suites.$SUITE.doer.provider")
+          REV_OS=$(echo $CONFIG     | jq -r ".suites.$SUITE.reviewer.os")
+          REV_PROV=$(echo $CONFIG   | jq -r ".suites.$SUITE.reviewer.provider")
+          VCS=$(echo $CONFIG        | jq -r ".suites.$SUITE.vcs")
+
+          DOER_HOST=$(echo $MEMBERS   | jq -r ".$DOER_OS.host")
+          DOER_USER=$(echo $MEMBERS   | jq -r ".$DOER_OS.username")
+          DOER_FOLDER=$(echo $MEMBERS | jq -r ".$DOER_OS.work_folder")
+          REV_HOST=$(echo $MEMBERS    | jq -r ".$REV_OS.host")
+          REV_USER=$(echo $MEMBERS    | jq -r ".$REV_OS.username")
+          REV_FOLDER=$(echo $MEMBERS  | jq -r ".$REV_OS.work_folder")
+          TOY_URL=$(echo $MEMBERS     | jq -r ".toy_projects.$VCS")
+
+          echo "pm_provider=$PM_PROVIDER"   >> $GITHUB_OUTPUT
+          echo "pm_os=$PM_OS"               >> $GITHUB_OUTPUT
+          echo "doer_os=$DOER_OS"           >> $GITHUB_OUTPUT
+          echo "doer_provider=$DOER_PROV"   >> $GITHUB_OUTPUT
+          echo "doer_host=$DOER_HOST"       >> $GITHUB_OUTPUT
+          echo "doer_user=$DOER_USER"       >> $GITHUB_OUTPUT
+          echo "doer_folder=$DOER_FOLDER"   >> $GITHUB_OUTPUT
+          echo "reviewer_os=$REV_OS"        >> $GITHUB_OUTPUT
+          echo "reviewer_provider=$REV_PROV" >> $GITHUB_OUTPUT
+          echo "reviewer_host=$REV_HOST"    >> $GITHUB_OUTPUT
+          echo "reviewer_user=$REV_USER"    >> $GITHUB_OUTPUT
+          echo "reviewer_folder=$REV_FOLDER" >> $GITHUB_OUTPUT
+          echo "vcs=$VCS"                   >> $GITHUB_OUTPUT
+          echo "toy_url=$TOY_URL"           >> $GITHUB_OUTPUT
+
+      # ── Step 2: Build and install fleet binary on PM runner ───────────────
+      # Must come before credential seeding — seed step needs fleet on PATH.
+      # Build from source so all three platforms (Windows/Linux/macOS x86_64)
+      # work without any artifact download.
+      - name: Build and install fleet binary on PM
+        shell: bash
+        run: |
+          npm ci
+          npm run build:binary
+          if [ "$RUNNER_OS" = "Windows" ]; then
+            BIN=$(ls dist/apra-fleet-installer-*.exe | head -1)
+          else
+            BIN=$(ls dist/apra-fleet-installer-* | grep -v -E '\.(blob|cjs|json|exe)$' | head -1)
+          fi
+          chmod +x "$BIN" 2>/dev/null || true
+          "$BIN" install --force
+          if [ "$RUNNER_OS" = "Windows" ]; then
+            INSTALLED_BIN="$HOME/.apra-fleet/bin/apra-fleet.exe"
+          else
+            INSTALLED_BIN="$HOME/.apra-fleet/bin/apra-fleet"
+          fi
+          "$INSTALLED_BIN" --version
+
+      # ── Step 3: Seed fleet credential store ───────────────────────────────
+      - name: Seed fleet credential store
+        shell: bash
+        run: |
+          check_secret() { [ -n "$1" ] || { echo "::error::$2 secret is not set or is empty"; exit 1; }; }
+          check_secret "$E2E_ACRED"     "E2E_ACRED"
+          check_secret "$E2E_GH_TOKEN"  "E2E_GH_TOKEN"
+          check_secret "$E2E_BB_TOKEN"  "E2E_BB_TOKEN"
+          check_secret "$E2E_BB_USER"   "E2E_BB_USER"
+          check_secret "$E2E_ADO_TOKEN" "E2E_ADO_TOKEN"
+
+          if [ "$RUNNER_OS" = "Windows" ]; then
+            FLEET_BIN="$HOME/.apra-fleet/bin/apra-fleet.exe"
+          else
+            FLEET_BIN="$HOME/.apra-fleet/bin/apra-fleet"
+          fi
+          echo "$E2E_BB_TOKEN"    | "$FLEET_BIN" secret --set e2e_bb_token    --persist -y
+          echo "$E2E_BB_USER"     | "$FLEET_BIN" secret --set e2e_bb_user     --persist -y
+          echo "$E2E_GH_TOKEN"    | "$FLEET_BIN" secret --set e2e_gh_token    --persist -y
+          echo "$E2E_ADO_TOKEN"   | "$FLEET_BIN" secret --set e2e_ado_token   --persist -y
+          echo "$E2E_ACRED"       | "$FLEET_BIN" secret --set E2E_ACRED       --persist -y
+        env:
+          E2E_BB_TOKEN:   ${{ secrets.E2E_BB_TOKEN }}
+          E2E_BB_USER:    ${{ secrets.E2E_BB_USER }}
+          E2E_GH_TOKEN:   ${{ secrets.E2E_GH_TOKEN }}
+          E2E_ADO_TOKEN:  ${{ secrets.E2E_ADO_TOKEN }}
+          E2E_ACRED:      ${{ secrets.E2E_ACRED }}
+
+      # ── Step 3a: Clear PM claude settings of member-role residue ────────────
+      # This runner may also be registered as a fleet member. compose_permissions
+      # writes .claude/settings.local.json to the member's work_folder with
+      # apra-fleet disabled. Claude Code walks up from RUN_DIR (which is nested
+      # inside the work_folder) and finds that file, polluting the PM session.
+      # Delete it before the PM runs — compose_permissions recreates it on next
+      # member use, and the PM needs apra-fleet MCP enabled.
+      - name: Clear PM claude settings of member-role residue
+        shell: bash
+        run: |
+          dir="$GITHUB_WORKSPACE"
+          while [ "$(dirname "$dir")" != "$dir" ]; do
+            dir="$(dirname "$dir")"
+            cfg="$dir/.claude/settings.local.json"
+            if [ -f "$cfg" ]; then
+              rm -f "$cfg"
+              echo "Removed: $cfg"
+            fi
+          done
+          echo "Done."
+
+      # ── Step 3b: Smoke-test PM LLM auth + apra-fleet MCP ────────────────
+      # Fail fast if LLM auth is expired OR the fleet MCP server is not loaded.
+      # No point running a 45-minute test without a working fleet connection.
+      - name: Smoke-test PM LLM auth and fleet MCP
+        shell: bash
+        run: |
+          PROMPT="What is the version of the apra-fleet MCP server installed? If the tool is not available reply with: not installed"
+          PROVIDER='${{ steps.suite.outputs.pm_provider }}'
+          check_mcp() {
+            local output="$1" provider="$2"
+            if echo "$output" | grep -qi "not installed"; then
+              echo "::error::apra-fleet MCP not loaded on $provider. Ensure fleet is installed on this runner."
+              exit 1
+            fi
+            if ! echo "$output" | grep -qE 'v?[0-9]+\.[0-9]+'; then
+              echo "::error::apra-fleet MCP responded but version not recognised. Output: $output"
+              exit 1
+            fi
+          }
+          if [ "$PROVIDER" = "claude" ]; then
+            output=$(claude -p "$PROMPT" --model haiku 2>&1)
+            echo "$output"
+            check_mcp "$output" "claude"
+            echo "PM claude auth OK — fleet MCP responding"
+          elif [ "$PROVIDER" = "gemini" ]; then
+            output=$(gemini -p "$PROMPT" --model auto 2>&1)
+            echo "$output"
+            check_mcp "$output" "gemini"
+            echo "PM gemini auth OK — fleet MCP responding"
+          fi
+
+      # ── Step 3c: Purge fleet daemon logs ──────────────────────────────────
+      # Clear any logs from previous runs so we can collect exactly the files
+      # produced by this run — handles fleet restarts during the test cleanly.
+      - name: Purge fleet daemon logs
+        shell: bash
+        run: |
+          if [ "$RUNNER_OS" = "Windows" ]; then
+            LOG_DIR="$(cygpath "$USERPROFILE")/.apra-fleet/data/logs"
+          else
+            LOG_DIR="$HOME/.apra-fleet/data/logs"
+          fi
+          rm -f "$LOG_DIR"/fleet-*.log
+          echo "Fleet logs purged from $LOG_DIR"
+
+      # ── Step 4: Render test script with suite context ─────────────────────
+      - name: Render test script
+        shell: bash
+        run: |
+          # Folder paths may contain backslashes (Windows) which GNU sed interprets
+          # as escape sequences (\U = uppercase, \a = BEL, etc.) in replacements.
+          # Escape each backslash to \\ before passing to sed.
+          DOER_FOLDER='${{ steps.suite.outputs.doer_folder }}'
+          REVIEWER_FOLDER='${{ steps.suite.outputs.reviewer_folder }}'
+          DOER_FOLDER_SED="${DOER_FOLDER//\\/\\\\}"
+          REVIEWER_FOLDER_SED="${REVIEWER_FOLDER//\\/\\\\}"
+
+          sed \
+            -e 's|{{SUITE_ID}}|${{ inputs.suite }}|g' \
+            -e 's|{{PM_OS}}|${{ steps.suite.outputs.pm_os }}|g' \
+            -e 's|{{PM_PROVIDER}}|${{ steps.suite.outputs.pm_provider }}|g' \
+            -e 's|{{DOER_HOST}}|${{ steps.suite.outputs.doer_host }}|g' \
+            -e 's|{{DOER_USER}}|${{ steps.suite.outputs.doer_user }}|g' \
+            -e 's|{{DOER_OS}}|${{ steps.suite.outputs.doer_os }}|g' \
+            -e 's|{{DOER_PROVIDER}}|${{ steps.suite.outputs.doer_provider }}|g' \
+            -e 's|{{REVIEWER_HOST}}|${{ steps.suite.outputs.reviewer_host }}|g' \
+            -e 's|{{REVIEWER_USER}}|${{ steps.suite.outputs.reviewer_user }}|g' \
+            -e 's|{{REVIEWER_OS}}|${{ steps.suite.outputs.reviewer_os }}|g' \
+            -e 's|{{REVIEWER_PROVIDER}}|${{ steps.suite.outputs.reviewer_provider }}|g' \
+            -e 's|{{TOY_PROJECT_URL}}|${{ steps.suite.outputs.toy_url }}|g' \
+            -e 's|{{VCS}}|${{ steps.suite.outputs.vcs }}|g' \
+            -e 's|{{BRANCH_PREFIX}}|e2e-${{ inputs.suite }}-${{ github.run_id }}|g' \
+            -e "s|{{DOER_FOLDER}}|${DOER_FOLDER_SED}|g" \
+            -e "s|{{REVIEWER_FOLDER}}|${REVIEWER_FOLDER_SED}|g" \
+            .github/e2e/test-script.md > "$RUN_DIR/rendered-test-script.md"
+
+      # ── Step 5: Run the LLM-driven test (T1–T5) ──────────────────────────────
+      - name: Run fleet e2e (${{ steps.suite.outputs.pm_provider }})
+        id: e2e
+        shell: bash
+        run: |
+          PROVIDER='${{ steps.suite.outputs.pm_provider }}'
+          cd "$RUN_DIR"
+          if [ "$PROVIDER" = "claude" ]; then
+            claude \
+              -p "$(cat "$RUN_DIR/rendered-test-script.md")" \
+              --output-format stream-json \
+              --verbose \
+              --max-turns 80 \
+              > "$RUN_DIR/raw-output.txt" 2>&1 || true
+          else
+            gemini \
+              --output-format stream-json \
+              -p "$(cat "$RUN_DIR/rendered-test-script.md")" \
+              > "$RUN_DIR/raw-output.txt" 2>&1 || true
+          fi
+
+          if [ ! -s "$RUN_DIR/raw-output.txt" ]; then
+            echo "::error::LLM produced no output — check auth and MCP connectivity"
+          fi
+
+          # Extract PM session ID from the stream-json system init event.
+          SESSION_ID=$(grep -m1 '"type":"system"' "$RUN_DIR/raw-output.txt" \
+            | jq -r '.session_id // ""' 2>/dev/null || true)
+          echo "session_id=$SESSION_ID" >> "$GITHUB_OUTPUT"
+          echo "PM session_id: $SESSION_ID"
+
+          # Assemble results.json from CHECKPOINT lines emitted during the run.
+          node "$GITHUB_WORKSPACE/.github/e2e/extract-results.mjs" "$RUN_DIR/raw-output.txt" \
+            '${{ inputs.suite }}' \
+            '${{ steps.suite.outputs.pm_os }}' \
+            '${{ steps.suite.outputs.pm_provider }}' \
+            > "$RUN_DIR/results.json" \
+            || echo '{"overall":"FAIL","error":"extract-results.mjs failed"}' > "$RUN_DIR/results.json"
+
+      # ── Step 5b: Collect fleet daemon logs ────────────────────────────────
+      # Collect all fleet-*.log files produced since the purge step.
+      # Multiple files appear if fleet restarted during the test; concatenate
+      # them all into fleet-pm.log so extract-telemetry.js sees one stream.
+      - name: Collect fleet daemon logs
+        if: always()
+        shell: bash
+        run: |
+          if [ "$RUNNER_OS" = "Windows" ]; then
+            LOG_DIR="$(cygpath "$USERPROFILE")/.apra-fleet/data/logs"
+          else
+            LOG_DIR="$HOME/.apra-fleet/data/logs"
+          fi
+          count=$(ls "$LOG_DIR"/fleet-*.log 2>/dev/null | wc -l)
+          if [ "$count" -gt 0 ]; then
+            cat "$LOG_DIR"/fleet-*.log > "$RUN_DIR/logs/fleet-pm.log"
+            echo "Collected $count fleet log file(s) → fleet-pm.log ($(wc -l < "$RUN_DIR/logs/fleet-pm.log") lines)"
+          else
+            echo "No fleet logs found in $LOG_DIR"
+          fi
+
+      # ── Step 5c: Extract telemetry ────────────────────────────────────────
+      # Primary: logs/fleet-pm.log execute_prompt exit lines (in=N out=N elapsed=Nms).
+      # Fallback: member session JSONLs.
+      - name: Extract telemetry
+        if: always()
+        shell: bash
+        run: |
+          [ -n "$RUN_DIR" ] && cd "$RUN_DIR" || exit 1
+          node "$GITHUB_WORKSPACE/.github/e2e/extract-telemetry.js"
+
+      # ── Step 6: Post job summary ───────────────────────────────────────────
+      - name: Post job summary
+        if: always()
+        shell: bash
+        run: |
+          [ -n "$RUN_DIR" ] && cd "$RUN_DIR" || exit 1
+          node "$GITHUB_WORKSPACE/.github/e2e/post-summary.mjs"
+        env:
+          SUITE: ${{ inputs.suite }}
+
+      # ── Step 7: T6 teardown ────────────────────────────────────────────────
+      # Runs always — remove any fleet members left over from the test run.
+      # Housekeeping only: result does not feed into the test report.
+      - name: T6 — Teardown
+        if: always()
+        shell: bash
+        run: |
+          PROVIDER='${{ steps.suite.outputs.pm_provider }}'
+          if [ "$PROVIDER" = "claude" ]; then
+            claude \
+              -p "$(cat "$GITHUB_WORKSPACE/.github/e2e/t6-teardown.md")" \
+              --max-turns 15 \
+              > "$RUN_DIR/t6-output.txt" 2>&1 || true
+          else
+            timeout 120 gemini \
+              -p "$(cat "$GITHUB_WORKSPACE/.github/e2e/t6-teardown.md")" \
+              > "$RUN_DIR/t6-output.txt" 2>&1 || true
+          fi
+          tail -3 "$RUN_DIR/t6-output.txt" || true
+          if ! grep -q "T6: PASS" "$RUN_DIR/t6-output.txt" 2>/dev/null; then
+            echo "::warning::T6 teardown did not confirm success — fleet members may still be registered"
+          fi
+
+      # ── Step 8: Upload artifacts ───────────────────────────────────────────
+      - name: Upload results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: e2e-${{ inputs.suite }}-${{ github.run_id }}
+          path: ${{ env.RUN_DIR }}
diff --git a/.github/workflows/fleet-e2e.yml b/.github/workflows/fleet-e2e.yml
index 86fbf430..3233de84 100644
--- a/.github/workflows/fleet-e2e.yml
+++ b/.github/workflows/fleet-e2e.yml
@@ -164,7 +164,7 @@ jobs:
               echo "::error::apra-fleet MCP not loaded on $provider. Ensure fleet is installed on this runner."
               exit 1
             fi
-            if ! echo "$output" | grep -qE 'v[0-9]+\.[0-9]+'; then
+            if ! echo "$output" | grep -qE 'v?[0-9]+\.[0-9]+'; then
               echo "::error::apra-fleet MCP responded but version not recognised. Output: $output"
               exit 1
             fi
diff --git a/.github/workflows/gbrain-eval.yml b/.github/workflows/gbrain-eval.yml
new file mode 100644
index 00000000..8a496a98
--- /dev/null
+++ b/.github/workflows/gbrain-eval.yml
@@ -0,0 +1,77 @@
+name: gbrain Eval
+
+# Demonstrates gbrain value: seeds apra-fleet facts, runs BM25 recall queries,
+# and posts a scorecard to the job summary.
+#
+# Triggers:
+#   - Automatically on push to feat/gbrain* branches
+#   - Manually via workflow_dispatch (can be run on any branch)
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - 'feat/gbrain*'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  gbrain-eval:
+    name: gbrain BM25 Recall Eval
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js 22.x
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+          cache: npm
+
+      - name: Install dependencies (for MCP SDK)
+        run: npm ci
+
+      # ── Install bun ─────────────────────────────────────────────────────────
+      - name: Install bun
+        run: |
+          curl -fsSL https://bun.sh/install | bash
+          echo "$HOME/.bun/bin" >> "$GITHUB_PATH"
+
+      # ── Install gbrain ───────────────────────────────────────────────────────
+      # Mirrors what `apra-fleet install --with-gbrain` does on a real member:
+      # git clone → bun install → bun link → gbrain available on PATH
+      - name: Install gbrain
+        run: |
+          git clone https://github.com/garrytan/gbrain.git ~/gbrain
+          cd ~/gbrain
+          ~/.bun/bin/bun install --frozen-lockfile
+          ~/.bun/bin/bun link
+          echo "Installed: $(~/.bun/bin/gbrain --version 2>&1 || ~/.bun/bin/bun run ~/gbrain/src/cli.ts --version 2>&1 || echo unknown)"
+
+      # ── Initialize gbrain (PGLite, no embedding — BM25 keyword mode) ────────
+      # Write config directly (avoids interactive prompts) then run migrate-only
+      # to create the schema. No API key or embedding model needed.
+      - name: Initialize gbrain (PGLite, BM25 mode)
+        run: |
+          mkdir -p ~/.gbrain
+          printf '{"engine":"pglite","database_path":"%s/.gbrain/brain.pglite"}\n' "$HOME" > ~/.gbrain/config.json
+          cat ~/.gbrain/config.json
+          # Apply schema migrations only — does not clobber config or prompt for keys
+          gbrain init --migrate-only || ~/.bun/bin/bun run ~/gbrain/src/cli.ts init --migrate-only
+          echo "gbrain ready (PGLite + BM25 keyword mode)"
+
+      # ── Run eval ─────────────────────────────────────────────────────────────
+      # Seeds 5 apra-fleet facts, runs 5 recall queries, scores keyword overlap.
+      # Writes Markdown scorecard to $GITHUB_STEP_SUMMARY.
+      # Exit 1 if fewer than 2/5 facts recalled (hard failure).
+      - name: Run gbrain recall eval
+        run: node .github/eval/gbrain-eval.mjs
+        env:
+          GBRAIN_CMD: gbrain
diff --git a/README.md b/README.md
index d2dff443..7ff9cc1e 100644
--- a/README.md
+++ b/README.md
@@ -555,6 +555,89 @@ Pairs two members — one builds, one reviews. The PM handles git transport betw
 | `/pm pair <member> <member>` | Pair doer and reviewer |
 | `/pm deploy <member>` | Run deployment steps |
 
+## gbrain Integration
+
+[gbrain](https://github.com/Apra-Labs/gbrain) is a knowledge and code intelligence server that fleet members can connect to for persistent memory, semantic code search, and durable async job execution.
+
+### Installation
+
+gbrain is launched automatically via `npx -y gbrain` on first use. To use a custom binary, set environment variables before starting apra-fleet:
+
+```bash
+export GBRAIN_COMMAND=/path/to/gbrain
+export GBRAIN_ARGS="--port 9000"   # space-separated args (optional)
+```
+
+### Per-member opt-in
+
+gbrain is opt-in per member. Enable it when registering or updating a member:
+
+```
+"Register alice with gbrain enabled"
+"Update alice — enable gbrain"
+```
+
+Equivalent tool calls:
+- `register_member` with `gbrain: true`
+- `update_member` with `gbrain: true`
+
+### Available tools (12)
+
+**Brain (knowledge base)**
+
+| Tool | Description |
+|------|-------------|
+| `brain_query` | Query the member's knowledge base with a natural-language search |
+| `brain_write` | Write a fact or document into the member's knowledge base |
+
+**Code analysis**
+
+| Tool | Description |
+|------|-------------|
+| `code_def` | Find the definition of a symbol in the member's codebase |
+| `code_refs` | Find all references to a symbol |
+| `code_callers` | Find all callers of a function |
+| `code_callees` | Find all callees (functions called by) a function |
+
+**Minions job queue**
+
+| Tool | Description |
+|------|-------------|
+| `jobs_submit` | Submit a task to the durable async job queue |
+| `jobs_list` | List jobs, optionally filtered by status |
+| `jobs_stats` | Get aggregate job statistics (counts by status, average duration) |
+| `jobs_work` | Mark a job as complete with a result |
+
+**Course correction (global — no gbrain member check)**
+
+| Tool | Description |
+|------|-------------|
+| `course_correction_capture` | Persist a course correction so future agents avoid the same mistake |
+| `course_correction_recall` | Recall past course corrections by semantic search query |
+
+### Routing guidance
+
+- **`jobs_submit`** — use for durable async work that can survive process restarts (long-running tasks, CI jobs, batch processing). Results are polled via `jobs_list` / `jobs_work`.
+- **`execute_prompt`** — use for interactive, real-time LLM tasks where you need a live response. Not durable across restarts.
+
+Rule of thumb: if the work takes longer than a single prompt session or must survive crashes, use `jobs_submit`. For everything else, use `execute_prompt`.
+
+### PGLite vs Postgres
+
+gbrain stores data in a local PGLite database by default. This is suitable for local development and single-member setups.
+
+For **Minions job queue** features (`jobs_submit`, `jobs_list`, `jobs_stats`, `jobs_work`), a full **Postgres** instance is required — PGLite does not support the concurrent access patterns the job queue relies on. Set `GBRAIN_DB_URL` to a Postgres connection string to use Postgres.
+
+### Reviewer workflow
+
+When a reviewer member has `gbrain: true`, the PM skill automatically appends brain-aware instructions to the reviewer template. The reviewer will:
+
+1. Query `brain_query` for past corrections relevant to the diff being reviewed
+2. Surface any matching patterns as part of the review feedback
+3. Call `course_correction_capture` if the review uncovers a new mistake pattern worth preserving
+
+This creates a feedback loop where reviewer insights accumulate in the brain and improve future reviews automatically.
+
 ## Troubleshooting
 
 **Member shows as offline?**
diff --git a/feedback-gbrain.md b/feedback-gbrain.md
new file mode 100644
index 00000000..9f8fc7a6
--- /dev/null
+++ b/feedback-gbrain.md
@@ -0,0 +1,81 @@
+# gbrain Integration Plan — Reviewer Feedback
+
+## Finding 1: Wrong gbrain tool names
+
+**Issue:** PLAN.md used hyphenated gbrain tool names (`brain-query`, `code-callers`, `minions-dispatch`, `minions-status`) but gbrain's canonical tool names use underscores.
+
+**Correct names:** `brain_query`, `brain_write`, `code_callers`, `code_callees`, `code_def`, `code_refs`, `jobs_submit`, `jobs_list`, `jobs_stats`, `jobs_work`.
+
+**Impact:** `minions-dispatch` and `minions-status` don't exist at all in gbrain — the actual tools are `jobs_submit`, `jobs_list`, `jobs_stats`, `jobs_work` (four tools, not two). This also changes the tool count from 10 to 12.
+
+**Doer:** fixed in commit a5d21d5 + eab88d0 — replaced all hyphenated tool names with underscore versions; replaced `minions-dispatch`/`minions-status` with the four `jobs_*` tools throughout PLAN.md; updated tool counts and mapping notes.
+
+---
+
+## Finding 2: Template conditionals
+
+**Issue:** PLAN.md used Handlebars-style `{{#if gbrain}}...{{/if}}` conditionals in the reviewer template, but the PM skill only supports simple `{{PLACEHOLDER}}` token substitution.
+
+**Correct approach:** Use `<!-- OPTIONAL: gbrain -->...<!-- /OPTIONAL: gbrain -->` HTML comment markers. The PM template renderer strips these sections when gbrain is not enabled.
+
+**Doer:** fixed in commit a5d21d5 + eab88d0 — replaced all `{{#if gbrain}}` references with `<!-- OPTIONAL: gbrain -->` marker approach; added `src/services/template-renderer.ts` to Task 5.1 file list; updated Notes section.
+
+---
+
+## Finding 3: Wire course correction into PM sprint flow
+
+**Issue:** `course_correction_capture` was defined as a tool (Task 5.3) and service (Task 5.2) but never wired into the PM sprint execution flow. Corrections would only be captured if someone manually called the tool.
+
+**Correct approach:** Add explicit `course_correction_capture` call-sites in sprint templates (`single-pair-sprint.md`, `doer-reviewer.md`) at post-iteration review checkpoints, wrapped in `<!-- OPTIONAL: gbrain -->` blocks.
+
+**Doer:** fixed in commit a5d21d5 + eab88d0 — added Task 5.4 (wire course_correction_capture into sprint templates) with template-based approach; renumbered former Task 5.4 to Task 5.5.
+
+---
+
+## Finding 4: Move shared helpers earlier
+
+**Issue:** Shared helpers (`assertGbrainEnabled`, `callGbrainTool`) were deferred to Phase 6 Task 6.1, but the pattern first appears in Phase 2. This would mean Phases 2-5 all inline their own gbrain checks, then Phase 6 refactors them — unnecessary churn.
+
+**Correct approach:** Create helpers in Phase 2 (new Task 2.0) so all subsequent phases use them from the start. Task 6.1 becomes a DRY audit rather than an extraction.
+
+**Doer:** fixed in commit a5d21d5 + eab88d0 — added Task 2.0 (create shared gbrain helpers) in Phase 2; reduced Task 6.1 to a DRY audit; updated Task 3.1 to reference Task 2.0 helpers.
+
+---
+
+## Finding 5: Phase 1 tier monotonicity
+
+**Issue:** Phase 1 tier sequence violates monotonicity: Task 1.1 (cheap) → Task 1.2 (cheap) → Task 1.3 (premium) → Task 1.4 (standard). A tier downgrade within the phase indicates a structural issue with task ordering or tier assignments.
+
+**Correct approach:** Promote Task 1.4 to premium tier. Tests for the premium client service (mocked child process, MCP client lifecycle, reconnection) justify premium tier. This makes the sequence: cheap → cheap → premium → premium.
+
+**Doer:** fixed — promoted Task 1.4 tier from standard to premium. Sequence is now cheap → cheap → premium → premium.
+
+---
+
+## Phase 1 Code Re-Review
+
+**Verdict: APPROVED**
+
+**Date:** 2026-05-13
+**Trigger:** Re-review after doer addressed CHANGES NEEDED from commit 4870ccc (missing listMembers/memberDetail display tests).
+**Fix commit:** bc85296 — added 6 new tests to `tests/gbrain-config.test.ts`.
+
+### Checklist
+
+- [x] `npm run build` — passes clean
+- [x] `npm test` — 1317 passed, 2 failed (pre-existing time-utils, known/acceptable), 13 skipped
+- [x] 6 display tests cover all required scenarios:
+  1. listMembers compact shows `gbrain=enabled` for gbrain member
+  2. listMembers compact omits `gbrain=enabled` for non-gbrain member
+  3. listMembers JSON includes `gbrain` field
+  4. memberDetail compact shows `gbrain=enabled` for gbrain member
+  5. memberDetail compact omits `gbrain=enabled` for non-gbrain member
+  6. memberDetail JSON includes `gbrain` field
+- [x] Source scan (types.ts, register-member.ts, update-member.ts, list-members.ts, member-detail.ts, gbrain-client.ts) — clean, consistent, no issues
+
+### Notes
+
+- Tests use proper mocking (mockTestConnection, mockExecCommand) for memberDetail probes
+- Compact display correctly shows gbrain only when enabled (reduces noise)
+- JSON display always includes the field for programmatic consumers
+- All Phase 1 tasks (T1.1–T1.4) are complete and verified
diff --git a/llms-full.txt b/llms-full.txt
index 16ecd8e7..2073b913 100644
--- a/llms-full.txt
+++ b/llms-full.txt
@@ -558,6 +558,89 @@ Pairs two members — one builds, one reviews. The PM handles git transport betw
 | `/pm pair <member> <member>` | Pair doer and reviewer |
 | `/pm deploy <member>` | Run deployment steps |
 
+## gbrain Integration
+
+[gbrain](https://github.com/Apra-Labs/gbrain) is a knowledge and code intelligence server that fleet members can connect to for persistent memory, semantic code search, and durable async job execution.
+
+### Installation
+
+gbrain is launched automatically via `npx -y gbrain` on first use. To use a custom binary, set environment variables before starting apra-fleet:
+
+```bash
+export GBRAIN_COMMAND=/path/to/gbrain
+export GBRAIN_ARGS="--port 9000"   # space-separated args (optional)
+```
+
+### Per-member opt-in
+
+gbrain is opt-in per member. Enable it when registering or updating a member:
+
+```
+"Register alice with gbrain enabled"
+"Update alice — enable gbrain"
+```
+
+Equivalent tool calls:
+- `register_member` with `gbrain: true`
+- `update_member` with `gbrain: true`
+
+### Available tools (12)
+
+**Brain (knowledge base)**
+
+| Tool | Description |
+|------|-------------|
+| `brain_query` | Query the member's knowledge base with a natural-language search |
+| `brain_write` | Write a fact or document into the member's knowledge base |
+
+**Code analysis**
+
+| Tool | Description |
+|------|-------------|
+| `code_def` | Find the definition of a symbol in the member's codebase |
+| `code_refs` | Find all references to a symbol |
+| `code_callers` | Find all callers of a function |
+| `code_callees` | Find all callees (functions called by) a function |
+
+**Minions job queue**
+
+| Tool | Description |
+|------|-------------|
+| `jobs_submit` | Submit a task to the durable async job queue |
+| `jobs_list` | List jobs, optionally filtered by status |
+| `jobs_stats` | Get aggregate job statistics (counts by status, average duration) |
+| `jobs_work` | Mark a job as complete with a result |
+
+**Course correction (global — no gbrain member check)**
+
+| Tool | Description |
+|------|-------------|
+| `course_correction_capture` | Persist a course correction so future agents avoid the same mistake |
+| `course_correction_recall` | Recall past course corrections by semantic search query |
+
+### Routing guidance
+
+- **`jobs_submit`** — use for durable async work that can survive process restarts (long-running tasks, CI jobs, batch processing). Results are polled via `jobs_list` / `jobs_work`.
+- **`execute_prompt`** — use for interactive, real-time LLM tasks where you need a live response. Not durable across restarts.
+
+Rule of thumb: if the work takes longer than a single prompt session or must survive crashes, use `jobs_submit`. For everything else, use `execute_prompt`.
+
+### PGLite vs Postgres
+
+gbrain stores data in a local PGLite database by default. This is suitable for local development and single-member setups.
+
+For **Minions job queue** features (`jobs_submit`, `jobs_list`, `jobs_stats`, `jobs_work`), a full **Postgres** instance is required — PGLite does not support the concurrent access patterns the job queue relies on. Set `GBRAIN_DB_URL` to a Postgres connection string to use Postgres.
+
+### Reviewer workflow
+
+When a reviewer member has `gbrain: true`, the PM skill automatically appends brain-aware instructions to the reviewer template. The reviewer will:
+
+1. Query `brain_query` for past corrections relevant to the diff being reviewed
+2. Surface any matching patterns as part of the review feedback
+3. Call `course_correction_capture` if the review uncovers a new mistake pattern worth preserving
+
+This creates a feedback loop where reviewer insights accumulate in the brain and improve future reviews automatically.
+
 ## Troubleshooting
 
 **Member shows as offline?**
diff --git a/skills/pm/doer-reviewer.md b/skills/pm/doer-reviewer.md
index eda0e661..7e11fc43 100644
--- a/skills/pm/doer-reviewer.md
+++ b/skills/pm/doer-reviewer.md
@@ -1,123 +1,124 @@
-# Doer-Reviewer Loop
-
-## Setup Checklist
-
-1. Record pair in `<project>/status.md`. Multiple pairs per project is normal.
-2. Override icons via `update_member` — doer gets circle, reviewer gets square, same color.
-3. Compose and deliver permissions per `permissions.md` (fleet skill) for each member's role.
-4. Send the role-specific agent context file via `send_files` before dispatch.
-   - Call `compose_permissions` before every dispatch regardless of unattended mode.
-   - For provider-specific unattended flag behaviour, see the fleet SKILL.md unattended modes section.
-   - Prefer `unattended='auto'` over `'dangerous'` — `auto` scopes bypass to explicitly listed operations; `dangerous` skips all checks globally.
-   - See `context-file.md` for provider filename lookup and role templates. Planning and plan review are dispatched as inline prompts — no agent context file needed for those phases.
-
-**Model tier check:** Dispatch reviews at `model=premium`. For doers, PM reads `tasks[i].tier` from `planned.json` and passes `model: <tier>` to `execute_prompt` — no hardcoded default. User override always wins.
-
-## Pre-flight Checks
-
-### Before any dispatch
-Verify member is on the correct branch with a clean working tree:
-1. `fleet_status` — confirm member is idle
-2. `execute_command → git status && git branch --show-current` — confirm clean tree and correct branch
-
-Do not dispatch to a member on the wrong branch or with uncommitted source code changes.
-
-### Before review dispatch
-Verify reviewer is at the correct commit before starting review:
-1. `execute_command → git rev-parse HEAD` on reviewer — must match doer's pushed HEAD SHA
-2. If SHA doesn't match: run `git fetch origin && git reset --hard origin/<branch>` on reviewer, then re-verify
-
-## Flow
-
-1. Doer works, commits and pushes deliverables at every turn → STOPS at every VERIFY checkpoint
-
-   **Doer session rules:**
-   - **New phase (`nextTask.phase !== lastDispatchedPhase`):** use `resume=false`
-   - **Same phase (`nextTask.phase === lastDispatchedPhase`):** use `resume=true`
-
-2. **PM handles git transport via `execute_command`** — never delegate to prompts:
-   - Dev side: `git push origin <branch>` — verify push succeeded
-   - Rev side: `git fetch origin && git checkout <branch> && git reset --hard origin/<branch>`
-
-3. **PM dispatches REVIEWER at every VERIFY checkpoint** — PM never self-reviews. Most context docs are committed in repository. PM sends any other required background information  to reviewer via `send_files`. Then dispatches reviewer with `resume=false` (fresh session).
-
-   **Reviewer workflow rules:**
-   - **During planning stage prep reviewer in parallel while doer works** — send requirements, set up branch, start a context-reading session on reviewer. Use session resume to send updated docs at handoff when doer is ready.
-   - **During execution phase**: for each new phase's review use `resume=false` for the reviewer.
-   - **Verify SHA before dispatching review** — `execute_command → git rev-parse HEAD` on reviewer must match doer's pushed HEAD (see Pre-flight Checks above).
-
-4. Reviewer reads deliverables + diff, conducts cumulative review (all phases up to current, not just the latest) per its agent context file. Commits findings to feedback.md, pushes, and outputs verdict: APPROVED or CHANGES NEEDED
-5. PM reads verdict:
-   - **APPROVED** → proceed to next phase (or sprint completion if all phases done)
-   - **CHANGES NEEDED** → PM sends feedback to doer → doer fixes → back to step 1 → PM re-dispatches REVIEWER
-6. Loop until all phases APPROVED
-7. **Sprint completion** — See cleanup.md.
-
-## Resume Rule
-
-**Doer dispatches** — resume is derived from `planned.json` phase numbers via `lastDispatchedPhase` in `status.md`, not manually reasoned:
-
-| Condition | resume |
-|-----------|--------|
-| `nextTask.phase === lastDispatchedPhase` | `true` |
-| `nextTask.phase !== lastDispatchedPhase` (new phase) | `false` |
-| After reviewer CHANGES NEEDED → doer fix | `true` |
-| Role switch (doer ↔ reviewer) | `false` |
-
-**All dispatches:**
-
-| Dispatch | resume |
-|----------|--------|
-| Initial plan generation | `false` |
-| Plan revision (any feedback iteration) | `true` |
-| Initial review dispatch | `false` |
-| Re-review after CHANGES NEEDED + doer fixes | `true` |
-| Role switch (doer → reviewer, or reviewer → doer) | `false` |
-| After `stop_prompt` cancellation | `false` | Session state unreliable after kill; start fresh |
-| After session timed out mid-grant | `true` | Fleet auto-recovers (stale-session retry), but member restarts without prior context |
-
-**Note:** A role switch always requires sending the new agent context file before dispatch. Never resume across a role switch.
-
-## Safeguards
-
-| Safeguard | Trigger | PM Action | Limit |
-|-----------|---------|-----------|-------|
-| max_turns budget | Every `execute_prompt` dispatch | Session ends naturally at turn limit | Set per dispatch in `execute_prompt` |
-| PM retry limit | Same dispatch fails (error, no output) | Retry up to 3×, then pause sprint + flag user | 3 retries per dispatch |
-| Doer-reviewer cycle limit | Reviewer returns CHANGES NEEDED | Re-dispatch doer with feedback; if 3 cycles don't resolve all HIGH items, pause sprint + flag user | 3 cycles per phase |
-| Model escalation | Zero progress after session resets | Reset session and resume; after 2 resets with zero progress: escalate model (cheap→standard→premium). Still zero after premium? Flag user | 2 resets per model tier |
-
-**When to escalate to user:**
-- After 3 retries on the same dispatch with no progress
-- After 3 doer-reviewer cycles with unresolved HIGH items
-- After premium model still shows zero progress after 2 resets
-
-## Git as transport
-
-- Doers commit: deliverables, PLAN.md, progress.json, project docs. When fixing review findings, doer also annotates feedback.md — adding `**Doer:** fixed in commit <sha> — <what changed>` under each addressed finding — then commits feedback.md. Doer never rewrites feedback.md content.
-- Reviewers commit: feedback.md (full content — see tpl-reviewer.md for format)
-- The member agent context file is NEVER committed — see `context-file.md`
-
-## Permissions
-
-Compose and deliver permissions per `permissions.md` (fleet skill). Recompose when switching roles (e.g. doer↔reviewer). Each provider gets its native permission config — `compose_permissions` handles the format automatically.
-
-**Mid-sprint denial:** If a member is blocked by a permission denial, call `compose_permissions` with `grant: [<denied permission>]` and `project_folder` — this grants the missing permission, delivers the updated config, and appends to the ledger so future phases and sprints start with it already included. Then resume the member with `resume=true`. Never bypass by running the denied
-command yourself via `execute_command`. Act on the grant promptly — the inactivity
-timer (transport-level, applies to all providers) fires on stdout silence. If it fires
-while you are composing permissions, `resume=true` still succeeds via stale-session
-auto-recovery, but the member restarts without its in-progress context.
-
-**Cancelling a running session:** Use `stop_prompt` when a member is working on the wrong
-thing, stuck in a loop, or dispatched with incorrect instructions. Always follow immediately
-with `resume=false` to start a clean session.
-
-Note: `stop_prompt` (a fleet MCP tool) kills the member's LLM process. This is distinct from
-stopping a background orchestration sub-task within the PM's own session — the latter mechanism
-is harness-dependent and not a fleet concept.
-
-## PM responsibilities
-
-- Distribute work across pairs based on cohesion (high cohesion within a pair, loose coupling between pairs)
-- Don't wait for user between doer and reviewer handoffs, autonomously keep progressing the project unless blockers are observed
-
+# Doer-Reviewer Loop
+
+## Setup Checklist
+
+1. Record pair in `<project>/status.md`. Multiple pairs per project is normal.
+2. Override icons via `update_member` — doer gets circle, reviewer gets square, same color.
+3. Compose and deliver permissions per `permissions.md` (fleet skill) for each member's role.
+4. Send the role-specific agent context file via `send_files` before dispatch.
+   - Call `compose_permissions` before every dispatch regardless of unattended mode.
+   - For provider-specific unattended flag behaviour, see the fleet SKILL.md unattended modes section.
+   - Prefer `unattended='auto'` over `'dangerous'` — `auto` scopes bypass to explicitly listed operations; `dangerous` skips all checks globally.
+   - See `context-file.md` for provider filename lookup and role templates. Planning and plan review are dispatched as inline prompts — no agent context file needed for those phases.
+
+**Model tier check:** Dispatch reviews at `model=premium`. For doers, PM reads `tasks[i].tier` from `planned.json` and passes `model: <tier>` to `execute_prompt` — no hardcoded default. User override always wins.
+
+## Pre-flight Checks
+
+### Before any dispatch
+Verify member is on the correct branch with a clean working tree:
+1. `fleet_status` — confirm member is idle
+2. `execute_command → git status && git branch --show-current` — confirm clean tree and correct branch
+
+Do not dispatch to a member on the wrong branch or with uncommitted source code changes.
+
+### Before review dispatch
+Verify reviewer is at the correct commit before starting review:
+1. `execute_command → git rev-parse HEAD` on reviewer — must match doer's pushed HEAD SHA
+2. If SHA doesn't match: run `git fetch origin && git reset --hard origin/<branch>` on reviewer, then re-verify
+
+## Flow
+
+1. Doer works, commits and pushes deliverables at every turn → STOPS at every VERIFY checkpoint
+
+   **Doer session rules:**
+   - **New phase (`nextTask.phase !== lastDispatchedPhase`):** use `resume=false`
+   - **Same phase (`nextTask.phase === lastDispatchedPhase`):** use `resume=true`
+
+2. **PM handles git transport via `execute_command`** — never delegate to prompts:
+   - Dev side: `git push origin <branch>` — verify push succeeded
+   - Rev side: `git fetch origin && git checkout <branch> && git reset --hard origin/<branch>`
+
+3. **PM dispatches REVIEWER at every VERIFY checkpoint** — PM never self-reviews. Most context docs are committed in repository. PM sends any other required background information  to reviewer via `send_files`. Then dispatches reviewer with `resume=false` (fresh session).
+
+   **Reviewer workflow rules:**
+   - **During planning stage prep reviewer in parallel while doer works** — send requirements, set up branch, start a context-reading session on reviewer. Use session resume to send updated docs at handoff when doer is ready.
+   - **During execution phase**: for each new phase's review use `resume=false` for the reviewer.
+   - **Verify SHA before dispatching review** — `execute_command → git rev-parse HEAD` on reviewer must match doer's pushed HEAD (see Pre-flight Checks above).
+
+4. Reviewer reads deliverables + diff, conducts cumulative review (all phases up to current, not just the latest) per its agent context file. Commits findings to feedback.md, pushes, and outputs verdict: APPROVED or CHANGES NEEDED
+5. PM reads verdict:
+   - **APPROVED** → proceed to next phase (or sprint completion if all phases done)
+   - **CHANGES NEEDED** → PM sends feedback to doer → doer fixes → back to step 1 → PM re-dispatches REVIEWER
+     - If the user has provided a modification or correction to the original plan alongside the CHANGES NEEDED verdict: call `course_correction_capture` with `attempted` = the original approach and `correction` = the user-specified change before re-dispatching. This persists the correction to brain so future sprints and agents avoid the same mistake.
+6. Loop until all phases APPROVED
+7. **Sprint completion** — See cleanup.md.
+
+## Resume Rule
+
+**Doer dispatches** — resume is derived from `planned.json` phase numbers via `lastDispatchedPhase` in `status.md`, not manually reasoned:
+
+| Condition | resume |
+|-----------|--------|
+| `nextTask.phase === lastDispatchedPhase` | `true` |
+| `nextTask.phase !== lastDispatchedPhase` (new phase) | `false` |
+| After reviewer CHANGES NEEDED → doer fix | `true` |
+| Role switch (doer ↔ reviewer) | `false` |
+
+**All dispatches:**
+
+| Dispatch | resume |
+|----------|--------|
+| Initial plan generation | `false` |
+| Plan revision (any feedback iteration) | `true` |
+| Initial review dispatch | `false` |
+| Re-review after CHANGES NEEDED + doer fixes | `true` |
+| Role switch (doer → reviewer, or reviewer → doer) | `false` |
+| After `stop_prompt` cancellation | `false` | Session state unreliable after kill; start fresh |
+| After session timed out mid-grant | `true` | Fleet auto-recovers (stale-session retry), but member restarts without prior context |
+
+**Note:** A role switch always requires sending the new agent context file before dispatch. Never resume across a role switch.
+
+## Safeguards
+
+| Safeguard | Trigger | PM Action | Limit |
+|-----------|---------|-----------|-------|
+| max_turns budget | Every `execute_prompt` dispatch | Session ends naturally at turn limit | Set per dispatch in `execute_prompt` |
+| PM retry limit | Same dispatch fails (error, no output) | Retry up to 3×, then pause sprint + flag user | 3 retries per dispatch |
+| Doer-reviewer cycle limit | Reviewer returns CHANGES NEEDED | Re-dispatch doer with feedback; if 3 cycles don't resolve all HIGH items, pause sprint + flag user | 3 cycles per phase |
+| Model escalation | Zero progress after session resets | Reset session and resume; after 2 resets with zero progress: escalate model (cheap→standard→premium). Still zero after premium? Flag user | 2 resets per model tier |
+
+**When to escalate to user:**
+- After 3 retries on the same dispatch with no progress
+- After 3 doer-reviewer cycles with unresolved HIGH items
+- After premium model still shows zero progress after 2 resets
+
+## Git as transport
+
+- Doers commit: deliverables, PLAN.md, progress.json, project docs. When fixing review findings, doer also annotates feedback.md — adding `**Doer:** fixed in commit <sha> — <what changed>` under each addressed finding — then commits feedback.md. Doer never rewrites feedback.md content.
+- Reviewers commit: feedback.md (full content — see tpl-reviewer.md for format)
+- The member agent context file is NEVER committed — see `context-file.md`
+
+## Permissions
+
+Compose and deliver permissions per `permissions.md` (fleet skill). Recompose when switching roles (e.g. doer↔reviewer). Each provider gets its native permission config — `compose_permissions` handles the format automatically.
+
+**Mid-sprint denial:** If a member is blocked by a permission denial, call `compose_permissions` with `grant: [<denied permission>]` and `project_folder` — this grants the missing permission, delivers the updated config, and appends to the ledger so future phases and sprints start with it already included. Then resume the member with `resume=true`. Never bypass by running the denied
+command yourself via `execute_command`. Act on the grant promptly — the inactivity
+timer (transport-level, applies to all providers) fires on stdout silence. If it fires
+while you are composing permissions, `resume=true` still succeeds via stale-session
+auto-recovery, but the member restarts without its in-progress context.
+
+**Cancelling a running session:** Use `stop_prompt` when a member is working on the wrong
+thing, stuck in a loop, or dispatched with incorrect instructions. Always follow immediately
+with `resume=false` to start a clean session.
+
+Note: `stop_prompt` (a fleet MCP tool) kills the member's LLM process. This is distinct from
+stopping a background orchestration sub-task within the PM's own session — the latter mechanism
+is harness-dependent and not a fleet concept.
+
+## PM responsibilities
+
+- Distribute work across pairs based on cohesion (high cohesion within a pair, loose coupling between pairs)
+- Don't wait for user between doer and reviewer handoffs, autonomously keep progressing the project unless blockers are observed
+
diff --git a/skills/pm/single-pair-sprint.md b/skills/pm/single-pair-sprint.md
index 4fb627b2..488a9b21 100644
--- a/skills/pm/single-pair-sprint.md
+++ b/skills/pm/single-pair-sprint.md
@@ -1,178 +1,179 @@
-# Running a Sprint
-
-A sprint is a focused unit of work executed by a doer/reviewer pair against a codebase. This document covers the full lifecycle from initiation to PR raise.
-
-## Lifecycle
-
-```
-vision → requirements → design → plan → development → testing → deployment
-```
-
-PM drives work through these phases in order. Don't skip, don't stall between them.
-
----
-
-## Phase 1 — Requirements
-
-Write `<project>/requirements.md`. Quality bar:
-- Include full issue details — code locations, root causes, impact data
-- Never summarize into 2-3 line descriptions — include full issue text, code locations, root causes
-- Front-load risk — the riskiest assumption must be validated in Task 1 of the plan
-
----
-
-## Phase 2 — Plan Generation
-
-**Branch naming:** choose a name that makes the purpose of the branch immediately clear — `sprint/<description>`, `feat/<description>`, `bug_fix/<short_description>`, etc. PM records this as `{{branch}}` in the agent context file before dispatch.
-
-1. Send `requirements.md` and `tpl-plan.md` to doer via `send_files`
-2. Dispatch `plan-prompt.md` via `execute_prompt` (wrapped in background Agent)
-3. Run doer-reviewer loop (see `doer-reviewer.md`) using `tpl-reviewer-plan.md` for the reviewer
-4. Iterate until plan passes quality criteria
-5. Once APPROVED: save `planned.json` in `<project>/` — this is the immutable original, never modify it
-6. **Beads: push plan tasks** — for each task in PLAN.md, create a Beads task and wire dependencies:
-   ```bash
-   bd create "T1.1: <title>" -p 1 --parent <epic-id> --assignee <doer>   # → task-id
-   bd create "T1.2: <title>" -p 2 --parent <epic-id> --assignee <doer>   # → task-id
-   bd dep add <T1.2-id> <T1.1-id>                       # T1.2 blocked until T1.1 done
-   ```
-   Record all task IDs in `<project>/status.md` Beads section. See `beads.md`.
-7. Proceed to Phase 3
-
----
-
-## Phase 3 — Execution
-
-### Task Harness
-
-The task harness is the set of files sent to the doer's `work_folder` root via `send_files` to bootstrap execution:
-
-1. **Agent context file** — from `tpl-doer.md`. See `context-file.md` for filename and delivery rules.
-2. **PLAN.md** — implementation plan with phases and tasks
-3. **progress.json** — task tracker (generated from PLAN.md per `tpl-progress.json`)
-4. **Project docs** — `requirements.md`, `design.md`, and any other docs the doer needs. Doer commits these to the branch. Re-send via `send_files` if PM-side docs are updated mid-sprint.
-
-`progress.json` is the living state. Always query it for current status.
-
-### Per-Task Dispatch Algorithm
-
-Before each doer dispatch, PM reads `planned.json` and `progress.json`:
-
-```
-nextTask = planned.json.tasks.find(t => t.status === "pending")
-tier     = nextTask.tier
-resume   = (nextTask.phase === lastDispatchedPhase)   // from status.md
-```
-
-Dispatch ONE task at `model: <tier>`. PM records `lastDispatchedPhase = nextTask.phase` in `status.md` after each dispatch.
-
-### Execution Loop
-
-```
-PM sends task harness → dispatches doer (resume per data-driven rule, model=nextTask.tier)
-  → bd update <task-id> --status in_progress --assignee <doer>
-  → doer reads progress.json → executes next pending task → commits → updates progress.json
-  → hits VERIFY checkpoint → STOPS → PM reads progress.json
-  → bd close <verify-id>
-  → PM dispatches REVIEWER (model=premium) → reviewer reads deliverables + diff → commits verdict to feedback.md → pushes
-  → APPROVED: PM dispatches doer for next task (resume=true if same phase) → repeat
-  → CHANGES NEEDED: bd create "<finding>" -p 0 --parent <epic-id> --assignee <doer> per HIGH finding → PM sends feedback to doer → doer fixes → bd close <finding-id> → PM re-dispatches REVIEWER → repeat
-  → all tasks done → move to next phase or completion
-```
-
-### Session Rules
-
-| Dispatch | resume |
-|----------|--------|
-| New phase (`nextTask.phase !== lastDispatchedPhase`) | `false` |
-| Same phase (`nextTask.phase === lastDispatchedPhase`) | `true` |
-| After reviewer CHANGES NEEDED → doer fix | `true` |
-| Initial review dispatch | `false` |
-| Re-review after fixes | `true` |
-| Role switch (doer↔reviewer) | `false` |
-
-**Data-driven resume rule** — derived from `planned.json` phase numbers, not manually reasoned:
-
-| Condition | resume |
-|-----------|--------|
-| `nextTask.phase === lastDispatchedPhase` | `true` |
-| `nextTask.phase !== lastDispatchedPhase` (new phase) | `false` |
-| After reviewer CHANGES NEEDED → doer fix | `true` |
-| Role switch (doer ↔ reviewer) | `false` |
-
-### Permissions
-
-Before kicking off execution, compose and deliver permissions for each member's role (see the fleet skill, `permissions.md`). Recompose on every role switch.
-
-**Mid-sprint denial:** If a member is blocked by a permission denial, call `compose_permissions` with `grant: [<denied permission>]` and `project_folder` — this grants the missing permission, delivers the updated config, and appends to the ledger so future phases and sprints start with it already included. Then resume the member with `resume=true`. Never bypass by running the denied command yourself via `execute_command`.
-
-### Monitoring
-
-- Check progress: `execute_command → cat progress.json`
-- Check git: `execute_command → git log --oneline -10`
-- Members may blow past VERIFY checkpoints if context gets large — dispatch a review immediately when caught
-- Long-running branches: check drift with `git log <branch>..origin/main --oneline`. If main moved, instruct rebase + retest
-- After every review verdict: create low-priority Beads tasks for unaddressed MEDIUM/LOW findings and deferred scope items (`bd create "<item>" -p 3 --parent <epic-id>` — see `backlog-item.md` for required description fields)
-- Deferred items from user ("add to backlog", "defer this"): `bd create "<description>" -p 3 --parent <epic-id>`
-
-### Safeguards
-
-| Safeguard | Trigger | PM Action | Limit |
-|-----------|---------|-----------|-------|
-| Max-turns budget | Every dispatch | Session ends naturally at turn limit | Set per dispatch in `execute_prompt` |
-| PM retry limit | Same dispatch fails (error, no output) | Retry up to 3×, then pause + flag user | 3 retries per dispatch |
-| Doer-reviewer cycle limit | Reviewer returns CHANGES NEEDED | Re-dispatch doer with feedback; if 3 cycles don't resolve all HIGH items, pause + flag user | 3 cycles per phase |
-| Model escalation | Zero progress after resets | Reset and resume; after 2 resets with zero progress: escalate model (`cheap`→`standard`→`premium`). Still zero? Flag user | 2 resets per model tier |
-
----
-
-## Phase 4 — Deployment
-
-Run `<project>/deploy.md` steps on the member via `execute_command`. Verification and rollback steps must be defined in `deploy.md` by the user — follow them exactly. On failure, execute the rollback steps in `deploy.md` and flag the user.
-
----
-
-## Sprint Completion
-
-When all phases are APPROVED:
-
-1. **Documentation Harvest** — Dispatch a member to extract long-term knowledge from `requirements.md`, `design.md`, and `PLAN.md` into `docs/`. Structure inside `docs/` is content-driven (e.g. `docs/architecture.md`, `docs/features/<name>.md`). Extract: architecture decisions, feature design, key trade-offs, API contracts. Do NOT extract: task lists, code-line references, debug notes, implementation steps. Member commits the docs/ output to the branch. Then dispatch reviewer to review the harvest — verify it captures durable knowledge and nothing transient slipped in. Iterate until APPROVED.
-
-2. **Cleanup and raise PR** — See cleanup.md.
-
-   STOP: Sprint is complete. Do not merge the PR. Surface the PR URL and CI status to the user and await explicit instruction to merge.
-
-3. **Deferred items** — any unresolved MEDIUM/LOW findings or deferred scope from this sprint should already be in Beads as low-priority tasks. Verify with `bd list --all --pretty`.
-
-4. **Update status.md** — mark sprint complete, record member states. Clear `lastDispatchedPhase`.
-
----
-
-## Recovery After PM Restart
-
-When the PM session ends unexpectedly, remote agent CLI processes are killed (SSH channel close → SIGHUP). Partial work may be uncommitted.
-
-**Step 0 — Global triage:** Run `bd list --all --pretty` first for PM dispatch state across all projects (no file reads needed for orientation). Then `fleet_status` to check member connectivity. **Important:** Beads reflects PM actions (dispatch/close), not member execution — always follow up with `cat progress.json` per member to confirm actual completion state. A task marked `in_progress` in Beads may be incomplete on disk if the member crashed mid-task.
-
-For each member in the project:
-1. `execute_command → cat progress.json` — what tasks are completed/pending/blocked?
-   - **On reviewer members:** progress.json is not authoritative — it reflects the doer's task state at last sync. Check `git log --oneline -- feedback.md` for reviewer progress instead.
-2. `execute_command → git log --oneline -5` — any commits since last known state?
-3. `execute_command → git status` — uncommitted changes?
-4. Compare against local `<project>/status.md` — what did PM last know? Check `lastDispatchedPhase` to determine resume vs. fresh-session for next dispatch.
-
-Present a per-member state summary before acting:
-
-| Member | PM last knew | Actual state | Delta | Action |
-|--------|-------------|--------------|-------|--------|
-| <name> | <phase/task from status.md> | <last commit + progress summary> | <what changed> | auto-resume / escalate |
-
-**Auto-resume** (PM acts immediately, no user input needed):
-- **Checkpoint reached, review pending** → dispatch reviewer now
-- **Mid-task with commits, clear next step** → resume doer with `resume=true`
-- **No progress, member idle** → re-dispatch from last known state
-
-**Escalate to user** (ambiguous or risky — present options and wait):
-- **Uncommitted changes of unknown origin** → "member has uncommitted work not matching any known task. Commit and resume, or discard?"
-- **Conflicting state** (progress.json says complete but git shows no commits) → "state inconsistency detected. Investigate or reset?"
-- **Zero progress after re-dispatch** → "member made no progress after re-dispatch. Escalate model or reassign?"
+# Running a Sprint
+
+A sprint is a focused unit of work executed by a doer/reviewer pair against a codebase. This document covers the full lifecycle from initiation to PR raise.
+
+## Lifecycle
+
+```
+vision → requirements → design → plan → development → testing → deployment
+```
+
+PM drives work through these phases in order. Don't skip, don't stall between them.
+
+---
+
+## Phase 1 — Requirements
+
+Write `<project>/requirements.md`. Quality bar:
+- Include full issue details — code locations, root causes, impact data
+- Never summarize into 2-3 line descriptions — include full issue text, code locations, root causes
+- Front-load risk — the riskiest assumption must be validated in Task 1 of the plan
+
+---
+
+## Phase 2 — Plan Generation
+
+**Branch naming:** choose a name that makes the purpose of the branch immediately clear — `sprint/<description>`, `feat/<description>`, `bug_fix/<short_description>`, etc. PM records this as `{{branch}}` in the agent context file before dispatch.
+
+1. Send `requirements.md` and `tpl-plan.md` to doer via `send_files`
+2. Dispatch `plan-prompt.md` via `execute_prompt` (wrapped in background Agent)
+3. Run doer-reviewer loop (see `doer-reviewer.md`) using `tpl-reviewer-plan.md` for the reviewer
+4. Iterate until plan passes quality criteria
+5. Once APPROVED: save `planned.json` in `<project>/` — this is the immutable original, never modify it
+6. **Beads: push plan tasks** — for each task in PLAN.md, create a Beads task and wire dependencies:
+   ```bash
+   bd create "T1.1: <title>" -p 1 --parent <epic-id> --assignee <doer>   # → task-id
+   bd create "T1.2: <title>" -p 2 --parent <epic-id> --assignee <doer>   # → task-id
+   bd dep add <T1.2-id> <T1.1-id>                       # T1.2 blocked until T1.1 done
+   ```
+   Record all task IDs in `<project>/status.md` Beads section. See `beads.md`.
+7. Proceed to Phase 3
+
+---
+
+## Phase 3 — Execution
+
+### Task Harness
+
+The task harness is the set of files sent to the doer's `work_folder` root via `send_files` to bootstrap execution:
+
+1. **Agent context file** — from `tpl-doer.md`. See `context-file.md` for filename and delivery rules.
+2. **PLAN.md** — implementation plan with phases and tasks
+3. **progress.json** — task tracker (generated from PLAN.md per `tpl-progress.json`)
+4. **Project docs** — `requirements.md`, `design.md`, and any other docs the doer needs. Doer commits these to the branch. Re-send via `send_files` if PM-side docs are updated mid-sprint.
+
+`progress.json` is the living state. Always query it for current status.
+
+### Per-Task Dispatch Algorithm
+
+Before each doer dispatch, PM reads `planned.json` and `progress.json`:
+
+```
+nextTask = planned.json.tasks.find(t => t.status === "pending")
+tier     = nextTask.tier
+resume   = (nextTask.phase === lastDispatchedPhase)   // from status.md
+```
+
+Dispatch ONE task at `model: <tier>`. PM records `lastDispatchedPhase = nextTask.phase` in `status.md` after each dispatch.
+
+### Execution Loop
+
+```
+PM sends task harness → dispatches doer (resume per data-driven rule, model=nextTask.tier)
+  → bd update <task-id> --status in_progress --assignee <doer>
+  → doer reads progress.json → executes next pending task → commits → updates progress.json
+  → hits VERIFY checkpoint → STOPS → PM reads progress.json
+  → bd close <verify-id>
+  → PM dispatches REVIEWER (model=premium) → reviewer reads deliverables + diff → commits verdict to feedback.md → pushes
+  → APPROVED: PM dispatches doer for next task (resume=true if same phase) → repeat
+  → CHANGES NEEDED: bd create "<finding>" -p 0 --parent <epic-id> --assignee <doer> per HIGH finding → PM sends feedback to doer → doer fixes → bd close <finding-id> → PM re-dispatches REVIEWER → repeat
+  → If user interrupts or corrects the plan mid-sprint: call `course_correction_capture` with the attempted approach and the user-specified correction before resuming. This persists the correction to brain so future agents avoid the same mistake.
+  → all tasks done → move to next phase or completion
+```
+
+### Session Rules
+
+| Dispatch | resume |
+|----------|--------|
+| New phase (`nextTask.phase !== lastDispatchedPhase`) | `false` |
+| Same phase (`nextTask.phase === lastDispatchedPhase`) | `true` |
+| After reviewer CHANGES NEEDED → doer fix | `true` |
+| Initial review dispatch | `false` |
+| Re-review after fixes | `true` |
+| Role switch (doer↔reviewer) | `false` |
+
+**Data-driven resume rule** — derived from `planned.json` phase numbers, not manually reasoned:
+
+| Condition | resume |
+|-----------|--------|
+| `nextTask.phase === lastDispatchedPhase` | `true` |
+| `nextTask.phase !== lastDispatchedPhase` (new phase) | `false` |
+| After reviewer CHANGES NEEDED → doer fix | `true` |
+| Role switch (doer ↔ reviewer) | `false` |
+
+### Permissions
+
+Before kicking off execution, compose and deliver permissions for each member's role (see the fleet skill, `permissions.md`). Recompose on every role switch.
+
+**Mid-sprint denial:** If a member is blocked by a permission denial, call `compose_permissions` with `grant: [<denied permission>]` and `project_folder` — this grants the missing permission, delivers the updated config, and appends to the ledger so future phases and sprints start with it already included. Then resume the member with `resume=true`. Never bypass by running the denied command yourself via `execute_command`.
+
+### Monitoring
+
+- Check progress: `execute_command → cat progress.json`
+- Check git: `execute_command → git log --oneline -10`
+- Members may blow past VERIFY checkpoints if context gets large — dispatch a review immediately when caught
+- Long-running branches: check drift with `git log <branch>..origin/main --oneline`. If main moved, instruct rebase + retest
+- After every review verdict: create low-priority Beads tasks for unaddressed MEDIUM/LOW findings and deferred scope items (`bd create "<item>" -p 3 --parent <epic-id>` — see `backlog-item.md` for required description fields)
+- Deferred items from user ("add to backlog", "defer this"): `bd create "<description>" -p 3 --parent <epic-id>`
+
+### Safeguards
+
+| Safeguard | Trigger | PM Action | Limit |
+|-----------|---------|-----------|-------|
+| Max-turns budget | Every dispatch | Session ends naturally at turn limit | Set per dispatch in `execute_prompt` |
+| PM retry limit | Same dispatch fails (error, no output) | Retry up to 3×, then pause + flag user | 3 retries per dispatch |
+| Doer-reviewer cycle limit | Reviewer returns CHANGES NEEDED | Re-dispatch doer with feedback; if 3 cycles don't resolve all HIGH items, pause + flag user | 3 cycles per phase |
+| Model escalation | Zero progress after resets | Reset and resume; after 2 resets with zero progress: escalate model (`cheap`→`standard`→`premium`). Still zero? Flag user | 2 resets per model tier |
+
+---
+
+## Phase 4 — Deployment
+
+Run `<project>/deploy.md` steps on the member via `execute_command`. Verification and rollback steps must be defined in `deploy.md` by the user — follow them exactly. On failure, execute the rollback steps in `deploy.md` and flag the user.
+
+---
+
+## Sprint Completion
+
+When all phases are APPROVED:
+
+1. **Documentation Harvest** — Dispatch a member to extract long-term knowledge from `requirements.md`, `design.md`, and `PLAN.md` into `docs/`. Structure inside `docs/` is content-driven (e.g. `docs/architecture.md`, `docs/features/<name>.md`). Extract: architecture decisions, feature design, key trade-offs, API contracts. Do NOT extract: task lists, code-line references, debug notes, implementation steps. Member commits the docs/ output to the branch. Then dispatch reviewer to review the harvest — verify it captures durable knowledge and nothing transient slipped in. Iterate until APPROVED.
+
+2. **Cleanup and raise PR** — See cleanup.md.
+
+   STOP: Sprint is complete. Do not merge the PR. Surface the PR URL and CI status to the user and await explicit instruction to merge.
+
+3. **Deferred items** — any unresolved MEDIUM/LOW findings or deferred scope from this sprint should already be in Beads as low-priority tasks. Verify with `bd list --all --pretty`.
+
+4. **Update status.md** — mark sprint complete, record member states. Clear `lastDispatchedPhase`.
+
+---
+
+## Recovery After PM Restart
+
+When the PM session ends unexpectedly, remote agent CLI processes are killed (SSH channel close → SIGHUP). Partial work may be uncommitted.
+
+**Step 0 — Global triage:** Run `bd list --all --pretty` first for PM dispatch state across all projects (no file reads needed for orientation). Then `fleet_status` to check member connectivity. **Important:** Beads reflects PM actions (dispatch/close), not member execution — always follow up with `cat progress.json` per member to confirm actual completion state. A task marked `in_progress` in Beads may be incomplete on disk if the member crashed mid-task.
+
+For each member in the project:
+1. `execute_command → cat progress.json` — what tasks are completed/pending/blocked?
+   - **On reviewer members:** progress.json is not authoritative — it reflects the doer's task state at last sync. Check `git log --oneline -- feedback.md` for reviewer progress instead.
+2. `execute_command → git log --oneline -5` — any commits since last known state?
+3. `execute_command → git status` — uncommitted changes?
+4. Compare against local `<project>/status.md` — what did PM last know? Check `lastDispatchedPhase` to determine resume vs. fresh-session for next dispatch.
+
+Present a per-member state summary before acting:
+
+| Member | PM last knew | Actual state | Delta | Action |
+|--------|-------------|--------------|-------|--------|
+| <name> | <phase/task from status.md> | <last commit + progress summary> | <what changed> | auto-resume / escalate |
+
+**Auto-resume** (PM acts immediately, no user input needed):
+- **Checkpoint reached, review pending** → dispatch reviewer now
+- **Mid-task with commits, clear next step** → resume doer with `resume=true`
+- **No progress, member idle** → re-dispatch from last known state
+
+**Escalate to user** (ambiguous or risky — present options and wait):
+- **Uncommitted changes of unknown origin** → "member has uncommitted work not matching any known task. Commit and resume, or discard?"
+- **Conflicting state** (progress.json says complete but git shows no commits) → "state inconsistency detected. Investigate or reset?"
+- **Zero progress after re-dispatch** → "member made no progress after re-dispatch. Escalate model or reassign?"
diff --git a/skills/pm/tpl-reviewer.md b/skills/pm/tpl-reviewer.md
index 702fccbd..567897b3 100644
--- a/skills/pm/tpl-reviewer.md
+++ b/skills/pm/tpl-reviewer.md
@@ -1,72 +1,81 @@
-# {{PROJECT_NAME}} — Code Review
-
-## Context Recovery
-Before starting any review: `git log --oneline {{base_branch}}..{{branch}}`
-
-## Review Model
-You are reviewing work tracked in PLAN.md and progress.json.
-
-Review scope covers all phases from Phase 1 through the current phase — not just the latest diff. Code written in earlier phases may have regressed or been invalidated by later changes.
-
-## On each review
-
-1. Run `git log --oneline -- feedback.md` then `git show <sha>` on prior versions to understand previous findings and how the doer addressed them. Incorporate the doer's responses into your review notes so the full picture is captured in the new write-up.
-2. Read progress.json — identify which tasks are marked completed since last review
-3. Read PLAN.md, requirements.md, and any design docs in the work folder — verify code aligns with requirements intent, not just plan mechanics
-4. `git diff` the relevant commits against the base branch
-5. Check each completed task against its "done" criteria in PLAN.md
-6. Run the project build step first, then run ALL tests (unit, integration, e2e). Both must pass — if either fails, CHANGES NEEDED.
-7. Verify CI passes for the latest push — if CI is red, CHANGES NEEDED regardless of code quality
-8. Check for regressions in previously approved phases
-
-## What to check
-
-- Does the code match what PLAN.md specified?
-- Does the code solve what requirements.md asked for?
-- Do tests pass? Are new tests added for new behavior?
-- Test quality: flag overlapping/redundant tests that add no value. Flag untested exposed surfaces (public APIs, error paths, edge cases). Phase does not close until test coverage is meaningful, not just present
-- Are there security issues (injection, auth bypass, secrets in code)?
-- Is the code consistent with existing patterns and conventions?
-- Are docs updated if behavior changed?
-- Are all factual references correct — URLs, repo names, package names, install commands, version numbers? Members hallucinate these; spot-check against known sources.
-- **File hygiene:** Run `git diff --name-only {{base_branch}}..{{branch}}`. For every file added, modified, or deleted — you must be able to justify it against the sprint requirements. If you cannot, flag CHANGES NEEDED. Common unjustifiable patterns:
-  - Temp/scratch: `*.tmp`, `*.txt`, `*.base64`
-  - Tool/security configs: `.gemini/`, `.claude/settings.json`, `permissions.json`
-  - Unrelated scripts or stale artifacts: `plan-NNN.md`, `requirements-NNN.md`, `progress-NNN.json`
-  - Tracked agent context: `GEMINI.md`, `CLAUDE.md`, `AGENTS.md`, `COPILOT-INSTRUCTIONS.md` (ensure gitignored)
-
-  Permit only source, tests, and active sprint tracking (`PLAN.md`, `progress.json`, `requirements.md`, `feedback.md`, design docs). When in doubt, flag it.
-
-## Output
-
-Overwrite feedback.md with this structure:
-
-```
-# {{sprint_name}} — Code Review
-
-**Reviewer:** {{member_name}}
-**Date:** YYYY-MM-DD HH:MM:SS+TZ
-**Verdict:** APPROVED | CHANGES NEEDED
-
-> See the recent git history of this file to understand the context of this review.
-
----
-
-## <Review section>
-
-<Detailed narrative. PASS/FAIL/NOTE inline. Explain what you found, where, and why it matters.>
-
----
-
-## Summary
-
-<Synthesize what passed, what must change, what is deferred.>
-```
-
-If verdict is CHANGES NEEDED: the doer annotates each relevant section with `**Doer:** fixed in commit <sha> — <what changed>` before requesting re-review.
-
-Commit feedback.md and push.
-
-## Rules
-- NEVER push to the base branch (main, master, or integration branch) — always work on feature branches
-- NEVER commit this agent context file (CLAUDE.md / GEMINI.md / AGENTS.md / COPILOT-INSTRUCTIONS.md) — it is role-specific and not shared
+# {{PROJECT_NAME}} — Code Review
+
+## Context Recovery
+Before starting any review: `git log --oneline {{base_branch}}..{{branch}}`
+
+## Brain-Aware Review (gbrain enabled)
+
+If the project has gbrain enabled, run these steps before reviewing each changed file:
+
+- Query brain for known context: "what do we know about this module/symbol?" — use `brain_query` with the file or symbol name to surface prior findings, architectural notes, and past corrections.
+- Use `code_callers` and `code_refs` to assess blast radius of changes — a small change to a widely-called function warrants deeper scrutiny.
+- Check brain for past corrections related to the changed areas: query `course_correction_recall` (or `brain_query` on the `course-corrections` collection) with the module name to surface any prior user-corrected approaches before flagging findings.
+
+## Review Model
+You are reviewing work tracked in PLAN.md and progress.json.
+
+Review scope covers all phases from Phase 1 through the current phase — not just the latest diff. Code written in earlier phases may have regressed or been invalidated by later changes.
+
+## On each review
+
+1. Run `git log --oneline -- feedback.md` then `git show <sha>` on prior versions to understand previous findings and how the doer addressed them. Incorporate the doer's responses into your review notes so the full picture is captured in the new write-up.
+2. Read progress.json — identify which tasks are marked completed since last review
+3. Read PLAN.md, requirements.md, and any design docs in the work folder — verify code aligns with requirements intent, not just plan mechanics
+4. `git diff` the relevant commits against the base branch
+5. Check each completed task against its "done" criteria in PLAN.md
+6. Run the project build step first, then run ALL tests (unit, integration, e2e). Both must pass — if either fails, CHANGES NEEDED.
+7. Verify CI passes for the latest push — if CI is red, CHANGES NEEDED regardless of code quality
+8. Check for regressions in previously approved phases
+
+## What to check
+
+- Does the code match what PLAN.md specified?
+- Does the code solve what requirements.md asked for?
+- Do tests pass? Are new tests added for new behavior?
+- Test quality: flag overlapping/redundant tests that add no value. Flag untested exposed surfaces (public APIs, error paths, edge cases). Phase does not close until test coverage is meaningful, not just present
+- Are there security issues (injection, auth bypass, secrets in code)?
+- Is the code consistent with existing patterns and conventions?
+- Are docs updated if behavior changed?
+- Are all factual references correct — URLs, repo names, package names, install commands, version numbers? Members hallucinate these; spot-check against known sources.
+- **If gbrain enabled:** check brain for known issues with changed symbols — run `brain_query` (or `course_correction_recall`) on key changed symbols to surface any previously-recorded corrections before flagging findings.
+- **File hygiene:** Run `git diff --name-only {{base_branch}}..{{branch}}`. For every file added, modified, or deleted — you must be able to justify it against the sprint requirements. If you cannot, flag CHANGES NEEDED. Common unjustifiable patterns:
+  - Temp/scratch: `*.tmp`, `*.txt`, `*.base64`
+  - Tool/security configs: `.gemini/`, `.claude/settings.json`, `permissions.json`
+  - Unrelated scripts or stale artifacts: `plan-NNN.md`, `requirements-NNN.md`, `progress-NNN.json`
+  - Tracked agent context: `GEMINI.md`, `CLAUDE.md`, `AGENTS.md`, `COPILOT-INSTRUCTIONS.md` (ensure gitignored)
+
+  Permit only source, tests, and active sprint tracking (`PLAN.md`, `progress.json`, `requirements.md`, `feedback.md`, design docs). When in doubt, flag it.
+
+## Output
+
+Overwrite feedback.md with this structure:
+
+```
+# {{sprint_name}} — Code Review
+
+**Reviewer:** {{member_name}}
+**Date:** YYYY-MM-DD HH:MM:SS+TZ
+**Verdict:** APPROVED | CHANGES NEEDED
+
+> See the recent git history of this file to understand the context of this review.
+
+---
+
+## <Review section>
+
+<Detailed narrative. PASS/FAIL/NOTE inline. Explain what you found, where, and why it matters.>
+
+---
+
+## Summary
+
+<Synthesize what passed, what must change, what is deferred.>
+```
+
+If verdict is CHANGES NEEDED: the doer annotates each relevant section with `**Doer:** fixed in commit <sha> — <what changed>` before requesting re-review.
+
+Commit feedback.md and push.
+
+## Rules
+- NEVER push to the base branch (main, master, or integration branch) — always work on feature branches
+- NEVER commit this agent context file (CLAUDE.md / GEMINI.md / AGENTS.md / COPILOT-INSTRUCTIONS.md) — it is role-specific and not shared
diff --git a/src/cli/install.ts b/src/cli/install.ts
index c3c7a938..1b2e3350 100644
--- a/src/cli/install.ts
+++ b/src/cli/install.ts
@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { execSync, execFileSync } from 'node:child_process';
 import { serverVersion } from '../version.js';
@@ -276,6 +277,57 @@ export function killApraFleet(): void {
   }
 }
 
+export function installGbrain(): void {
+  const homeDir = os.homedir();
+  const gbrainDir = path.join(homeDir, 'gbrain');
+
+  // Step 1: Check bun is available
+  try {
+    execFileSync('bun', ['--version'], { stdio: 'pipe', shell: true });
+  } catch {
+    console.warn('  ⚠ gbrain install skipped — bun not found. Install bun first: https://bun.sh');
+    return;
+  }
+
+  // Step 2: Check if already installed
+  if (fs.existsSync(gbrainDir)) {
+    // Already cloned — just verify it works
+    try {
+      execFileSync('gbrain', ['--version'], { stdio: 'pipe', shell: true });
+      console.log('  ✓ gbrain already installed');
+      return;
+    } catch {
+      // Exists but not in PATH — re-link
+      console.log('  gbrain dir exists, re-linking...');
+    }
+  } else {
+    // Clone
+    console.log('  Cloning gbrain...');
+    execFileSync('git', ['clone', 'https://github.com/garrytan/gbrain.git', gbrainDir], { stdio: 'inherit', shell: true });
+  }
+
+  // Step 3: bun install + bun link
+  console.log('  Running bun install...');
+  try {
+    execFileSync('bun', ['install'], { cwd: gbrainDir, stdio: 'inherit', shell: true });
+  } catch {
+    // postinstall script fails on Windows — benign, packages are still installed
+  }
+  console.log('  Linking gbrain CLI...');
+  execFileSync('bun', ['link'], { cwd: gbrainDir, stdio: 'inherit', shell: true });
+
+  // Step 4: verify
+  let gbrainVersion = 'installed';
+  try {
+    const v = execFileSync('gbrain', ['--version'], { stdio: 'pipe', encoding: 'utf-8', shell: true });
+    gbrainVersion = (v as string).trim() || 'installed';
+  } catch {
+    gbrainVersion = 'linked (restart shell to use gbrain in PATH)';
+  }
+  console.log(`  ✓ gbrain ${gbrainVersion}`);
+  console.log('  Next: run `gbrain init` to create your brain database.');
+}
+
 export async function runInstall(args: string[]): Promise<void> {
   // --help / -h guard — must come first, before any side effects (#142)
   if (args.includes('--help') || args.includes('-h')) {
@@ -292,6 +344,7 @@ Usage:
   apra-fleet install --no-skill        Same as --skill none
   apra-fleet install --force           Stop a running server before installing
   apra-fleet install --llm <provider>  Target LLM provider: claude (default), gemini, codex, copilot
+  apra-fleet install --with-gbrain    Install gbrain alongside fleet (git clone + bun link)
   apra-fleet install --help            Show this help
 
 Options:
@@ -359,9 +412,12 @@ Options:
   // Parse --force flag
   const force = args.includes('--force');
 
+  // Parse --with-gbrain flag
+  const withGbrain = args.includes('--with-gbrain');
+
   // Reject unknown flags to catch typos early
   const knownFlagPrefixes = ['--llm=', '--skill='];
-  const knownFlagExact = new Set(['--llm', '--skill', '--no-skill', '--force', '--help', '-h']);
+  const knownFlagExact = new Set(['--llm', '--skill', '--no-skill', '--force', '--with-gbrain', '--help', '-h']);
   for (const a of args) {
     if (knownFlagExact.has(a)) continue;
     if (knownFlagPrefixes.some(p => a.startsWith(p))) continue;
@@ -372,7 +428,8 @@ Options:
 
   const installFleet = skillMode === 'fleet' || skillMode === 'pm' || skillMode === 'all';
   const installPm = skillMode === 'pm' || skillMode === 'all';
-  const totalSteps = (installFleet && installPm) ? 8 : installFleet ? 7 : installPm ? 8 : 6;
+  const baseSteps = (installFleet && installPm) ? 8 : installFleet ? 7 : installPm ? 8 : 6;
+  const totalSteps = withGbrain ? baseSteps + 1 : baseSteps;
 
   if (llm === 'gemini' && (installFleet || installPm)) {
     console.warn(`\n⚠ Note: Gemini does not support background agents. If you plan to use Gemini as the\n  PM/orchestrator, fleet operations will run sequentially (no parallel dispatch).\n  For best orchestration performance, consider using Claude. See docs for details.\n`);
@@ -523,7 +580,7 @@ ${killHint}
   // --- Step 8: Install Beads task tracker ---
   // shell:true required on Windows — npm global packages install as .cmd wrappers
   // that cannot be directly spawned by Node without a shell
-  console.log(`  [${totalSteps}/${totalSteps}] Installing Beads task tracker...`);
+  console.log(`  [${baseSteps}/${totalSteps}] Installing Beads task tracker...`);
   try {
     // Check if already installed
     try {
@@ -538,6 +595,12 @@ ${killHint}
     console.warn('  ⚠ Beads install skipped — npm not available or install failed');
   }
 
+  // --- Step 9: Install gbrain (optional) ---
+  if (withGbrain) {
+    console.log(`  [${totalSteps}/${totalSteps}] Installing gbrain...`);
+    installGbrain();
+  }
+
   // Finalize permissions
   mergePermissions(paths);
 
@@ -553,6 +616,16 @@ ${killHint}
     beadsVersion = 'not available';
   }
 
+  let gbrainStatus = '';
+  if (withGbrain) {
+    try {
+      const gv = execFileSync('gbrain', ['--version'], { stdio: 'pipe', encoding: 'utf-8', shell: true });
+      gbrainStatus = (gv as string).trim() || 'installed';
+    } catch {
+      gbrainStatus = 'linked (restart shell to use gbrain in PATH)';
+    }
+  }
+
   const instructions = llm === 'claude' ? 'Run /mcp in Claude Code to load the server.' : `Restart ${paths.name} to load the server.`;
   const forceNote = force ? '\nRestart Claude Code to reload the MCP server.' : '';
   console.log(`
@@ -561,7 +634,7 @@ Apra Fleet ${serverVersion} installed successfully for ${paths.name}.
   Hooks:       ${HOOKS_DIR}
   Scripts:     ${SCRIPTS_DIR}
   Settings:    ${paths.settingsFile}${installFleet ? `\n  Fleet Skill: ${paths.fleetSkillsDir}` : ''}${installPm ? `\n  PM Skill:    ${paths.skillsDir}` : ''}
-  Beads:       ${beadsVersion}
+  Beads:       ${beadsVersion}${withGbrain ? `\n  gbrain:      ${gbrainStatus}` : ''}
 
 ${instructions}${forceNote}
 `);
diff --git a/src/index.ts b/src/index.ts
index f6570402..3eee1970 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,279 +1,319 @@
-#!/usr/bin/env node
-
-import { serverVersion } from './version.js';
-import { logLine, logError } from './utils/log-helpers.js';
-
-// --- CLI dispatch (before MCP server imports to keep --version fast) ---
-const arg = process.argv[2];
-
-if (arg === '--version' || arg === '-v') {
-  console.log(`apra-fleet ${serverVersion}`);
-  process.exit(0);
-}
-
-if (arg === '--help' || arg === '-h') {
-  console.log(`apra-fleet ${serverVersion}
-
-Usage:
-  apra-fleet                  Start MCP server (stdio)
-  apra-fleet update           Check for and install latest update
-  apra-fleet update --check   Check for update
-  apra-fleet install                   Install binary + hooks + statusline + MCP + fleet & PM skills (default)
-  apra-fleet install --skill all       Same as bare install (all skills)
-  apra-fleet install --skill fleet     Install fleet skill only
-  apra-fleet install --skill pm        Install PM skill (also installs fleet — PM depends on fleet)
-  apra-fleet install --skill none      Skip skill installation
-  apra-fleet install --no-skill        Same as --skill none
-  apra-fleet uninstall                 Remove binary, hooks, and MCP registration
-  apra-fleet secret --set <name>       Deliver a secret to a waiting request
-  apra-fleet secret --list             List secrets
-  apra-fleet secret --delete <name>    Delete a secret
-  apra-fleet --version        Print version
-  apra-fleet --help           Show this help`);
-  process.exit(0);
-}
-
-if (arg === 'install') {
-  // Dynamic import so MCP deps aren't loaded for install
-  import('./cli/install.js')
-    .then(m => m.runInstall(process.argv.slice(3)))
-    .catch(err => { logError('cli', `Install failed: ${err.message}`); process.exit(1); });
-} else if (arg === 'secret') {
-  import('./cli/secret.js')
-    .then(m => m.runSecret(process.argv.slice(3)))
-    .catch(err => { logError('cli', `Secret failed: ${err.message}`); process.exit(1); });
-} else if (arg === 'uninstall') {
-  import('./cli/uninstall.js')
-    .then(m => m.runUninstall(process.argv.slice(3)))
-    .catch(err => { logError('cli', `Uninstall failed: ${err.message}`); process.exit(1); });
-} else if (arg === 'auth') {
-  import('./cli/auth.js')
-    .then(m => m.runAuth(process.argv.slice(3)))
-    .catch(err => { logError('cli', `Auth failed: ${err.message}`); process.exit(1); });
-} else if (arg === 'update') {
-  const rest = process.argv.slice(3);
-  if (rest.includes('--help') || rest.includes('-h')) {
-    console.log(`apra-fleet update
-
-Usage:
-  apra-fleet update           Check for and install latest update
-  apra-fleet update --check   Check for update without installing
-  apra-fleet update --help    Show this help`);
-    process.exit(0);
-  }
-  if (rest.includes('--check')) {
-    import('./services/update-check.js')
-      .then(async m => {
-        await m.checkForUpdate();
-        const notice = m.getUpdateNotice();
-        if (notice) console.log(notice);
-        else console.log('apra-fleet is up to date.');
-      })
-      .catch(err => { logError('cli', `Update check failed: ${err.message}`); process.exit(1); });
-  } else {
-    import('./cli/update.js')
-      .then(m => m.runUpdate())
-      .catch(err => { logError('cli', `Update failed: ${err.message}`); process.exit(1); });
-  }
-} else if (arg === undefined || arg === '--stdio') {
-  // Default: start MCP server
-  startServer();
-} else {
-  console.error(`Error: unknown option '${arg}'`);
-  console.error(`\nRun 'apra-fleet --help' for usage.`);
-  process.exit(1);
-}
-
-async function startServer() {
-  const { McpServer } = await import('@modelcontextprotocol/sdk/server/mcp.js');
-  const { StdioServerTransport } = await import('@modelcontextprotocol/sdk/server/stdio.js');
-
-  // Load onboarding state once at server startup (in-memory singleton)
-  const { loadOnboardingState, resetSessionFlags, getFirstRunPreamble, isJsonResponse, isActiveTool, getOnboardingNudge, getWelcomeBackPreamble } = await import('./services/onboarding.js');
-  const { VERBATIM_INSTRUCTIONS } = await import('./onboarding/text.js');
-  const { getAllAgents: getAgentsForStartup } = await import('./services/registry.js');
-  // Pass current member count so upgrade detection works: existing registry + no onboarding.json → skip banner
-  loadOnboardingState(getAgentsForStartup().length);
-  resetSessionFlags();
-
-  // Tool schemas and handlers
-  const { registerMemberSchema, registerMember } = await import('./tools/register-member.js');
-  const { listMembersSchema, listMembers } = await import('./tools/list-members.js');
-  const { removeMemberSchema, removeMember } = await import('./tools/remove-member.js');
-  const { updateMemberSchema, updateMember } = await import('./tools/update-member.js');
-  const { sendFilesSchema, sendFiles } = await import('./tools/send-files.js');
-  const { receiveFilesSchema, receiveFiles } = await import('./tools/receive-files.js');
-  const { executePromptSchema, executePrompt } = await import('./tools/execute-prompt.js');
-  const { executeCommandSchema, executeCommand } = await import('./tools/execute-command.js');
-  const { provisionAuthSchema, provisionAuth } = await import('./tools/provision-auth.js');
-  const { setupSSHKeySchema, setupSSHKey } = await import('./tools/setup-ssh-key.js');
-  const { setupGitAppSchema, setupGitApp } = await import('./tools/setup-git-app.js');
-  const { provisionVcsAuthSchema, provisionVcsAuth } = await import('./tools/provision-vcs-auth.js');
-  const { revokeVcsAuthSchema, revokeVcsAuth } = await import('./tools/revoke-vcs-auth.js');
-  const { fleetStatusSchema, fleetStatus } = await import('./tools/check-status.js');
-  const { memberDetailSchema, memberDetail } = await import('./tools/member-detail.js');
-  const { updateAgentCliSchema, updateAgentCli } = await import('./tools/update-agent-cli.js');
-  const { shutdownServerSchema, shutdownServer } = await import('./tools/shutdown-server.js');
-  const { composePermissionsSchema, composePermissions } = await import('./tools/compose-permissions.js');
-  const { cloudControlSchema, cloudControl } = await import('./tools/cloud-control.js');
-  const { monitorTaskSchema, monitorTask } = await import('./tools/monitor-task.js');
-  const { stopPromptSchema, stopPrompt } = await import('./tools/stop-prompt.js');
-  const { versionSchema, version } = await import('./tools/version.js');
-  const { credentialStoreSetSchema, credentialStoreSet } = await import('./tools/credential-store-set.js');
-  const { credentialStoreListSchema, credentialStoreList } = await import('./tools/credential-store-list.js');
-  const { credentialStoreDeleteSchema, credentialStoreDelete } = await import('./tools/credential-store-delete.js');
-  const { credentialStoreUpdateSchema, credentialStoreUpdate } = await import('./tools/credential-store-update.js');
-  const { closeAllConnections } = await import('./services/ssh.js');
-  const { idleManager } = await import('./services/cloud/idle-manager.js');
-  const { cleanupStaleTasks } = await import('./services/task-cleanup.js');
-  const { checkForUpdate } = await import('./services/update-check.js');
-  const { purgeExpiredCredentials } = await import('./services/credential-store.js');
-  const { getStallDetector } = await import('./services/stall/index.js');
-
-  // serverVersion is "v0.0.1_abc123" — strip 'v' prefix for semver-like version field
-  const versionNum = serverVersion.startsWith('v') ? serverVersion.slice(1) : serverVersion;
-
-  let capturedClientInfo: any = null;
-
-  const server = new McpServer(
-    { name: `apra fleet server ${serverVersion}`, version: versionNum },
-    {
-      capabilities: { logging: {} },
-      instructions: VERBATIM_INSTRUCTIONS,
-    },
-  );
-
-  // Capture MCP clientInfo during initialize handshake for logging
-  const originalInitialize = (server as any).initialize?.bind(server);
-  if (originalInitialize) {
-    (server as any).initialize = async function (request: any) {
-      capturedClientInfo = request.clientInfo ?? null;
-      return originalInitialize(request);
-    };
-  }
-
-  // --- Onboarding helpers ---
-  // isActiveTool guards passive tools (version, shutdown_server) from consuming the banner.
-  // First-run banner bypasses the JSON check — passive guard is sufficient protection.
-  // Welcome-back and nudges still respect the JSON check.
-
-  async function sendOnboardingNotification(srv: typeof server, text: string): Promise<void> {
-    try {
-      await srv.server.sendLoggingMessage({
-        level: 'info',
-        logger: 'apra-fleet-onboarding',
-        data: text,
-      });
-    } catch (e: unknown) {
-      const msg = (e instanceof Error ? e.message : String(e));
-      if (!/logging|method not found|not supported/i.test(msg)) {
-        process.stderr.write(`[apra-fleet] onboarding notification failed: ${msg}\n`);
-      }
-    }
-  }
-
-  function sanitizeToolResult(s: string): string {
-    return s.replace(/<\/?apra-fleet-display[^>]*(?:>|$)/gi, '[tag-stripped]');
-  }
-
-  function getOnboardingPreamble(toolName: string, isJson: boolean): string | null {
-    if (!isActiveTool(toolName)) return null;
-    // First-run banner always shows regardless of response format
-    const banner = getFirstRunPreamble();
-    if (banner) return banner;
-    // Welcome-back still respects JSON check
-    if (isJson) return null;
-    return getWelcomeBackPreamble();
-  }
-
-  function wrapTool(toolName: string, handler: (input: any, extra?: any) => Promise<string>) {
-    return async (input: any, extra?: any) => {
-      const result = await handler(input, extra);
-      const isJson = isJsonResponse(result);
-      const preamble = getOnboardingPreamble(toolName, isJson);
-      const suffix = isJson ? null : getOnboardingNudge(toolName, input, result);
-
-      // Channel 1: out-of-band notifications (best effort, never throws)
-      if (preamble) void sendOnboardingNotification(server, preamble);
-      if (suffix)   void sendOnboardingNotification(server, suffix);
-
-      // Channel 2 + 3: content blocks with markers + audience annotation
-      const content: Array<{ type: 'text'; text: string; annotations?: { audience?: ('user' | 'assistant')[]; priority?: number } }> = [];
-      if (preamble) {
-        content.push({ type: 'text' as const, text: `<apra-fleet-display>\n${preamble}\n</apra-fleet-display>`, annotations: { audience: ['user'], priority: 1 } });
-      }
-      content.push({ type: 'text' as const, text: sanitizeToolResult(result) });
-      if (suffix) {
-        content.push({ type: 'text' as const, text: `<apra-fleet-display>\n${suffix}\n</apra-fleet-display>`, annotations: { audience: ['user'], priority: 0.8 } });
-      }
-      return { content };
-    };
-  }
-
-  // --- Core Member Management ---
-  server.tool('register_member', 'Add a machine to the fleet. Use member_type "local" for this machine or "remote" for a machine reachable over SSH. Choose the AI provider the member will use for prompts.', registerMemberSchema.shape, wrapTool('register_member', (input) => registerMember(input as any)));
-  server.tool('list_members', 'List all fleet members and their current status. Use format="json" for structured data.', listMembersSchema.shape, wrapTool('list_members', (input) => listMembers(input as any)));
-  server.tool('remove_member', 'Remove a member from the fleet.', removeMemberSchema.shape, wrapTool('remove_member', (input) => removeMember(input as any)));
-  server.tool('update_member', "Change a member's name, connection details, working directory, AI provider, or other settings.", updateMemberSchema.shape, wrapTool('update_member', (input) => updateMember(input as any)));
-
-  // --- File Operations ---
-  server.tool('send_files', 'Transfer local files to a member. Always batch multiple files into a single call — never invoke repeatedly for individual files.', sendFilesSchema.shape, wrapTool('send_files', (input, extra) => sendFiles(input as any, extra)));
-  server.tool('receive_files', 'Download files from a member to a local directory. Always batch multiple files into a single call — never invoke repeatedly for individual files.', receiveFilesSchema.shape, wrapTool('receive_files', (input, extra) => receiveFiles(input as any, extra)));
-
-  // --- Prompt Execution ---
-  server.tool('execute_prompt', 'IMP: Never call this tool directly. Always wrap in a background subagent: Agent(run_in_background=true). Run an AI prompt on a member. Supports session resume for multi-turn conversations.', executePromptSchema.shape, wrapTool('execute_prompt', (input, extra) => executePrompt(input as any, extra)));
-  server.tool('execute_command', 'IMP: Never call this tool directly. Always wrap in a background subagent: Agent(run_in_background=true). Run a shell command on a member. Use for quick tasks like installing packages, checking versions, or running scripts.', executeCommandSchema.shape, wrapTool('execute_command', (input, extra) => executeCommand(input as any, extra)));
-
-  // --- Authentication & SSH ---
-  server.tool('provision_llm_auth', "Authenticate a fleet member so it can run prompts. Copies your current login session to the member, or deploys an API key if provided. Run this before execute_prompt if the member reports no authentication.", provisionAuthSchema.shape, wrapTool('provision_llm_auth', (input) => provisionAuth(input as any)));
-  server.tool('setup_ssh_key', 'Generate an SSH key pair and migrate a member from password to key-based authentication.', setupSSHKeySchema.shape, wrapTool('setup_ssh_key', (input) => setupSSHKey(input as any)));
-  server.tool('setup_git_app', "One-time setup: register a GitHub App for git token minting. Requires a GitHub App ID, private key (.pem) file path, and installation ID. The app must already be created at github.com/organizations/{org}/settings/apps.", setupGitAppSchema.shape, wrapTool('setup_git_app', (input) => setupGitApp(input as any)));
-  server.tool('provision_vcs_auth', 'Set up git access credentials on a member. Supports GitHub, Bitbucket, and Azure DevOps. Tests connectivity after setup.', provisionVcsAuthSchema.shape, wrapTool('provision_vcs_auth', (input) => provisionVcsAuth(input as any)));
-  server.tool('revoke_vcs_auth', 'Remove VCS credentials from a member. Specify the provider (github, bitbucket, or azure-devops) to revoke.', revokeVcsAuthSchema.shape, wrapTool('revoke_vcs_auth', (input) => revokeVcsAuth(input as any)));
-
-  // --- Status & Monitoring ---
-  server.tool('fleet_status', 'Get status of all fleet members. Use json format for structured data.', fleetStatusSchema.shape, wrapTool('fleet_status', (input) => fleetStatus(input as any)));
-  server.tool('member_detail', 'Get detailed status for one member: connectivity, AI version, authentication, active session, resources, and git branch.', memberDetailSchema.shape, wrapTool('member_detail', (input) => memberDetail(input as any)));
-
-  // --- Maintenance ---
-  server.tool('update_llm_cli', "Update or install the AI provider CLI on members. Omit member to update all online members at once. Use install_if_missing to install on members that don't have it yet.", updateAgentCliSchema.shape, wrapTool('update_llm_cli', (input) => updateAgentCli(input as any)));
-  server.tool('shutdown_server', 'Gracefully shut down the MCP server. Run /mcp afterwards to start a fresh instance with the latest code.', shutdownServerSchema.shape, wrapTool('shutdown_server', () => shutdownServer()));
-  server.tool('version', 'Returns the installed apra-fleet server version', versionSchema.shape, wrapTool('version', () => version()));
-
-  // --- Permissions ---
-  server.tool('compose_permissions', 'Set up and deliver the right permissions to a member for their role. Automatically tailors permissions to the project type. Use grant to add specific permissions mid-sprint without a full recompose.', composePermissionsSchema.shape, wrapTool('compose_permissions', (input) => composePermissions(input as any)));
-
-  // --- Cloud Control ---
-  server.tool('cloud_control', 'Manually start, stop, or check status of a cloud fleet member. Start waits until the member is ready; stop is immediate.', cloudControlSchema.shape, wrapTool('cloud_control', (input) => cloudControl(input as any)));
-  server.tool('monitor_task', 'Check status of a long-running background task on a cloud member. Optionally stop the cloud instance automatically when the task completes.', monitorTaskSchema.shape, wrapTool('monitor_task', (input) => monitorTask(input as any)));
-
-  // --- Agent Lifecycle ---
-  server.tool('stop_prompt', 'Kill the active LLM process on a member. Always call TaskStop on the dispatching background agent after calling this.', stopPromptSchema.shape, wrapTool('stop_prompt', (input) => stopPrompt(input as any)));
-  // --- Credential Store ---
-  server.tool('credential_store_set', 'Collect a secret from the user out-of-band and store it. Returns a handle (sec://NAME) and scope. Use {{secure.NAME}} tokens in execute_command to inject the value.', credentialStoreSetSchema.shape, wrapTool('credential_store_set', (input) => credentialStoreSet(input as any)));
-  server.tool('credential_store_list', 'List all stored credentials (names and metadata only — no values).', credentialStoreListSchema.shape, wrapTool('credential_store_list', () => credentialStoreList()));
-  server.tool('credential_store_delete', 'Delete a named credential from the store (both session and persistent tiers).', credentialStoreDeleteSchema.shape, wrapTool('credential_store_delete', (input) => credentialStoreDelete(input as any)));
-  server.tool('credential_store_update', 'Update metadata (members, TTL, network policy) on an existing credential without re-entering the secret.', credentialStoreUpdateSchema.shape, wrapTool('credential_store_update', (input) => credentialStoreUpdate(input as any)));
-
-  // --- Start Server ---
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
-
-  const { FLEET_DIR } = await import('./paths.js');
-  const stallDetector = getStallDetector();
-  stallDetector.start();
-
-  const clientStr = capturedClientInfo?.name ? ` client=${capturedClientInfo.name}` : '';
-  const versionStr = capturedClientInfo?.version ? ` version=${capturedClientInfo.version}` : '';
-  const pidStr = ` pid=${process.pid} ppid=${process.ppid}`;
-  logLine('startup', `apra-fleet ${serverVersion} started${clientStr}${versionStr}${pidStr} FLEET_DIR=${FLEET_DIR}`);
-
-  idleManager.start();
-  void cleanupStaleTasks();
-  purgeExpiredCredentials();
-  void checkForUpdate();
-
-  const { cleanupAuthSocket } = await import('./services/auth-socket.js');
-  process.on('SIGINT', () => { cleanupAuthSocket().then(() => { closeAllConnections(); stallDetector.stop(); process.exit(0); }); });
-  process.on('SIGTERM', () => { cleanupAuthSocket().then(() => { closeAllConnections(); stallDetector.stop(); process.exit(0); }); });
-}
+#!/usr/bin/env node
+
+import { serverVersion } from './version.js';
+import { logLine, logError } from './utils/log-helpers.js';
+
+// --- CLI dispatch (before MCP server imports to keep --version fast) ---
+const arg = process.argv[2];
+
+if (arg === '--version' || arg === '-v') {
+  console.log(`apra-fleet ${serverVersion}`);
+  process.exit(0);
+}
+
+if (arg === '--help' || arg === '-h') {
+  console.log(`apra-fleet ${serverVersion}
+
+Usage:
+  apra-fleet                  Start MCP server (stdio)
+  apra-fleet update           Check for and install latest update
+  apra-fleet update --check   Check for update
+  apra-fleet install                   Install binary + hooks + statusline + MCP + fleet & PM skills (default)
+  apra-fleet install --skill all       Same as bare install (all skills)
+  apra-fleet install --skill fleet     Install fleet skill only
+  apra-fleet install --skill pm        Install PM skill (also installs fleet — PM depends on fleet)
+  apra-fleet install --skill none      Skip skill installation
+  apra-fleet install --no-skill        Same as --skill none
+  apra-fleet uninstall                 Remove binary, hooks, and MCP registration
+  apra-fleet secret --set <name>       Deliver a secret to a waiting request
+  apra-fleet secret --list             List secrets
+  apra-fleet secret --delete <name>    Delete a secret
+  apra-fleet --version        Print version
+  apra-fleet --help           Show this help`);
+  process.exit(0);
+}
+
+if (arg === 'install') {
+  // Dynamic import so MCP deps aren't loaded for install
+  import('./cli/install.js')
+    .then(m => m.runInstall(process.argv.slice(3)))
+    .catch(err => { logError('cli', `Install failed: ${err.message}`); process.exit(1); });
+} else if (arg === 'secret') {
+  import('./cli/secret.js')
+    .then(m => m.runSecret(process.argv.slice(3)))
+    .catch(err => { logError('cli', `Secret failed: ${err.message}`); process.exit(1); });
+} else if (arg === 'uninstall') {
+  import('./cli/uninstall.js')
+    .then(m => m.runUninstall(process.argv.slice(3)))
+    .catch(err => { logError('cli', `Uninstall failed: ${err.message}`); process.exit(1); });
+} else if (arg === 'auth') {
+  import('./cli/auth.js')
+    .then(m => m.runAuth(process.argv.slice(3)))
+    .catch(err => { logError('cli', `Auth failed: ${err.message}`); process.exit(1); });
+} else if (arg === 'update') {
+  const rest = process.argv.slice(3);
+  if (rest.includes('--help') || rest.includes('-h')) {
+    console.log(`apra-fleet update
+
+Usage:
+  apra-fleet update           Check for and install latest update
+  apra-fleet update --check   Check for update without installing
+  apra-fleet update --help    Show this help`);
+    process.exit(0);
+  }
+  if (rest.includes('--check')) {
+    import('./services/update-check.js')
+      .then(async m => {
+        await m.checkForUpdate();
+        const notice = m.getUpdateNotice();
+        if (notice) console.log(notice);
+        else console.log('apra-fleet is up to date.');
+      })
+      .catch(err => { logError('cli', `Update check failed: ${err.message}`); process.exit(1); });
+  } else {
+    import('./cli/update.js')
+      .then(m => m.runUpdate())
+      .catch(err => { logError('cli', `Update failed: ${err.message}`); process.exit(1); });
+  }
+} else if (arg === undefined || arg === '--stdio') {
+  // Default: start MCP server
+  startServer();
+} else {
+  console.error(`Error: unknown option '${arg}'`);
+  console.error(`\nRun 'apra-fleet --help' for usage.`);
+  process.exit(1);
+}
+
+async function startServer() {
+  const { McpServer } = await import('@modelcontextprotocol/sdk/server/mcp.js');
+  const { StdioServerTransport } = await import('@modelcontextprotocol/sdk/server/stdio.js');
+
+  // Load onboarding state once at server startup (in-memory singleton)
+  const { loadOnboardingState, resetSessionFlags, getFirstRunPreamble, isJsonResponse, isActiveTool, getOnboardingNudge, getWelcomeBackPreamble } = await import('./services/onboarding.js');
+  const { VERBATIM_INSTRUCTIONS } = await import('./onboarding/text.js');
+  const { getAllAgents: getAgentsForStartup } = await import('./services/registry.js');
+  // Pass current member count so upgrade detection works: existing registry + no onboarding.json → skip banner
+  loadOnboardingState(getAgentsForStartup().length);
+  resetSessionFlags();
+
+  // Tool schemas and handlers
+  const { registerMemberSchema, registerMember } = await import('./tools/register-member.js');
+  const { listMembersSchema, listMembers } = await import('./tools/list-members.js');
+  const { removeMemberSchema, removeMember } = await import('./tools/remove-member.js');
+  const { updateMemberSchema, updateMember } = await import('./tools/update-member.js');
+  const { sendFilesSchema, sendFiles } = await import('./tools/send-files.js');
+  const { receiveFilesSchema, receiveFiles } = await import('./tools/receive-files.js');
+  const { executePromptSchema, executePrompt } = await import('./tools/execute-prompt.js');
+  const { executeCommandSchema, executeCommand } = await import('./tools/execute-command.js');
+  const { provisionAuthSchema, provisionAuth } = await import('./tools/provision-auth.js');
+  const { setupSSHKeySchema, setupSSHKey } = await import('./tools/setup-ssh-key.js');
+  const { setupGitAppSchema, setupGitApp } = await import('./tools/setup-git-app.js');
+  const { provisionVcsAuthSchema, provisionVcsAuth } = await import('./tools/provision-vcs-auth.js');
+  const { revokeVcsAuthSchema, revokeVcsAuth } = await import('./tools/revoke-vcs-auth.js');
+  const { fleetStatusSchema, fleetStatus } = await import('./tools/check-status.js');
+  const { memberDetailSchema, memberDetail } = await import('./tools/member-detail.js');
+  const { updateAgentCliSchema, updateAgentCli } = await import('./tools/update-agent-cli.js');
+  const { shutdownServerSchema, shutdownServer } = await import('./tools/shutdown-server.js');
+  const { composePermissionsSchema, composePermissions } = await import('./tools/compose-permissions.js');
+  const { cloudControlSchema, cloudControl } = await import('./tools/cloud-control.js');
+  const { monitorTaskSchema, monitorTask } = await import('./tools/monitor-task.js');
+  const { stopPromptSchema, stopPrompt } = await import('./tools/stop-prompt.js');
+  const { versionSchema, version } = await import('./tools/version.js');
+  const { credentialStoreSetSchema, credentialStoreSet } = await import('./tools/credential-store-set.js');
+  const { credentialStoreListSchema, credentialStoreList } = await import('./tools/credential-store-list.js');
+  const { credentialStoreDeleteSchema, credentialStoreDelete } = await import('./tools/credential-store-delete.js');
+  const { credentialStoreUpdateSchema, credentialStoreUpdate } = await import('./tools/credential-store-update.js');
+  const { brainQuerySchema, brainQuery } = await import('./tools/brain-query.js');
+  const { brainWriteSchema, brainWrite } = await import('./tools/brain-write.js');
+  const { codeDefSchema, codeDef } = await import('./tools/code-def.js');
+  const { codeRefsSchema, codeRefs } = await import('./tools/code-refs.js');
+  const { codeCallersSchema, codeCallers } = await import('./tools/code-callers.js');
+  const { codeCalleesSchema, codeCallees } = await import('./tools/code-callees.js');
+  const { jobsSubmitSchema, jobsSubmit } = await import('./tools/jobs-submit.js');
+  const { jobsListSchema, jobsList } = await import('./tools/jobs-list.js');
+  const { jobsStatsSchema, jobsStats } = await import('./tools/jobs-stats.js');
+  const { jobsWorkSchema, jobsWork } = await import('./tools/jobs-work.js');
+  const { courseCorrectionCaptureSchema, courseCorrectionCapture, courseCorrectionRecallSchema, courseCorrectionRecall } = await import('./tools/course-correction.js');
+  const { closeAllConnections } = await import('./services/ssh.js');
+  const { idleManager } = await import('./services/cloud/idle-manager.js');
+  const { cleanupStaleTasks } = await import('./services/task-cleanup.js');
+  const { checkForUpdate } = await import('./services/update-check.js');
+  const { purgeExpiredCredentials } = await import('./services/credential-store.js');
+  const { getStallDetector } = await import('./services/stall/index.js');
+
+  // serverVersion is "v0.0.1_abc123" — strip 'v' prefix for semver-like version field
+  const versionNum = serverVersion.startsWith('v') ? serverVersion.slice(1) : serverVersion;
+
+  let capturedClientInfo: any = null;
+
+  const server = new McpServer(
+    { name: `apra fleet server ${serverVersion}`, version: versionNum },
+    {
+      capabilities: { logging: {} },
+      instructions: VERBATIM_INSTRUCTIONS,
+    },
+  );
+
+  // Capture MCP clientInfo during initialize handshake for logging
+  const originalInitialize = (server as any).initialize?.bind(server);
+  if (originalInitialize) {
+    (server as any).initialize = async function (request: any) {
+      capturedClientInfo = request.clientInfo ?? null;
+      return originalInitialize(request);
+    };
+  }
+
+  // --- Onboarding helpers ---
+  // isActiveTool guards passive tools (version, shutdown_server) from consuming the banner.
+  // First-run banner bypasses the JSON check — passive guard is sufficient protection.
+  // Welcome-back and nudges still respect the JSON check.
+
+  async function sendOnboardingNotification(srv: typeof server, text: string): Promise<void> {
+    try {
+      await srv.server.sendLoggingMessage({
+        level: 'info',
+        logger: 'apra-fleet-onboarding',
+        data: text,
+      });
+    } catch (e: unknown) {
+      const msg = (e instanceof Error ? e.message : String(e));
+      if (!/logging|method not found|not supported/i.test(msg)) {
+        process.stderr.write(`[apra-fleet] onboarding notification failed: ${msg}\n`);
+      }
+    }
+  }
+
+  function sanitizeToolResult(s: string): string {
+    return s.replace(/<\/?apra-fleet-display[^>]*(?:>|$)/gi, '[tag-stripped]');
+  }
+
+  function getOnboardingPreamble(toolName: string, isJson: boolean): string | null {
+    if (!isActiveTool(toolName)) return null;
+    // First-run banner always shows regardless of response format
+    const banner = getFirstRunPreamble();
+    if (banner) return banner;
+    // Welcome-back still respects JSON check
+    if (isJson) return null;
+    return getWelcomeBackPreamble();
+  }
+
+  function wrapTool(toolName: string, handler: (input: any, extra?: any) => Promise<string>) {
+    return async (input: any, extra?: any) => {
+      const result = await handler(input, extra);
+      const isJson = isJsonResponse(result);
+      const preamble = getOnboardingPreamble(toolName, isJson);
+      const suffix = isJson ? null : getOnboardingNudge(toolName, input, result);
+
+      // Channel 1: out-of-band notifications (best effort, never throws)
+      if (preamble) void sendOnboardingNotification(server, preamble);
+      if (suffix)   void sendOnboardingNotification(server, suffix);
+
+      // Channel 2 + 3: content blocks with markers + audience annotation
+      const content: Array<{ type: 'text'; text: string; annotations?: { audience?: ('user' | 'assistant')[]; priority?: number } }> = [];
+      if (preamble) {
+        content.push({ type: 'text' as const, text: `<apra-fleet-display>\n${preamble}\n</apra-fleet-display>`, annotations: { audience: ['user'], priority: 1 } });
+      }
+      content.push({ type: 'text' as const, text: sanitizeToolResult(result) });
+      if (suffix) {
+        content.push({ type: 'text' as const, text: `<apra-fleet-display>\n${suffix}\n</apra-fleet-display>`, annotations: { audience: ['user'], priority: 0.8 } });
+      }
+      return { content };
+    };
+  }
+
+  // --- Core Member Management ---
+  server.tool('register_member', 'Add a machine to the fleet. Use member_type "local" for this machine or "remote" for a machine reachable over SSH. Choose the AI provider the member will use for prompts.', registerMemberSchema.shape, wrapTool('register_member', (input) => registerMember(input as any)));
+  server.tool('list_members', 'List all fleet members and their current status. Use format="json" for structured data.', listMembersSchema.shape, wrapTool('list_members', (input) => listMembers(input as any)));
+  server.tool('remove_member', 'Remove a member from the fleet.', removeMemberSchema.shape, wrapTool('remove_member', (input) => removeMember(input as any)));
+  server.tool('update_member', "Change a member's name, connection details, working directory, AI provider, or other settings.", updateMemberSchema.shape, wrapTool('update_member', (input) => updateMember(input as any)));
+
+  // --- File Operations ---
+  server.tool('send_files', 'Transfer local files to a member. Always batch multiple files into a single call — never invoke repeatedly for individual files.', sendFilesSchema.shape, wrapTool('send_files', (input, extra) => sendFiles(input as any, extra)));
+  server.tool('receive_files', 'Download files from a member to a local directory. Always batch multiple files into a single call — never invoke repeatedly for individual files.', receiveFilesSchema.shape, wrapTool('receive_files', (input, extra) => receiveFiles(input as any, extra)));
+
+  // --- Prompt Execution ---
+  server.tool('execute_prompt', 'IMP: Never call this tool directly. Always wrap in a background subagent: Agent(run_in_background=true). Run an AI prompt on a member. Supports session resume for multi-turn conversations.', executePromptSchema.shape, wrapTool('execute_prompt', (input, extra) => executePrompt(input as any, extra)));
+  server.tool('execute_command', 'IMP: Never call this tool directly. Always wrap in a background subagent: Agent(run_in_background=true). Run a shell command on a member. Use for quick tasks like installing packages, checking versions, or running scripts.', executeCommandSchema.shape, wrapTool('execute_command', (input, extra) => executeCommand(input as any, extra)));
+
+  // --- Authentication & SSH ---
+  server.tool('provision_llm_auth', "Authenticate a fleet member so it can run prompts. Copies your current login session to the member, or deploys an API key if provided. Run this before execute_prompt if the member reports no authentication.", provisionAuthSchema.shape, wrapTool('provision_llm_auth', (input) => provisionAuth(input as any)));
+  server.tool('setup_ssh_key', 'Generate an SSH key pair and migrate a member from password to key-based authentication.', setupSSHKeySchema.shape, wrapTool('setup_ssh_key', (input) => setupSSHKey(input as any)));
+  server.tool('setup_git_app', "One-time setup: register a GitHub App for git token minting. Requires a GitHub App ID, private key (.pem) file path, and installation ID. The app must already be created at github.com/organizations/{org}/settings/apps.", setupGitAppSchema.shape, wrapTool('setup_git_app', (input) => setupGitApp(input as any)));
+  server.tool('provision_vcs_auth', 'Set up git access credentials on a member. Supports GitHub, Bitbucket, and Azure DevOps. Tests connectivity after setup.', provisionVcsAuthSchema.shape, wrapTool('provision_vcs_auth', (input) => provisionVcsAuth(input as any)));
+  server.tool('revoke_vcs_auth', 'Remove VCS credentials from a member. Specify the provider (github, bitbucket, or azure-devops) to revoke.', revokeVcsAuthSchema.shape, wrapTool('revoke_vcs_auth', (input) => revokeVcsAuth(input as any)));
+
+  // --- Status & Monitoring ---
+  server.tool('fleet_status', 'Get status of all fleet members. Use json format for structured data.', fleetStatusSchema.shape, wrapTool('fleet_status', (input) => fleetStatus(input as any)));
+  server.tool('member_detail', 'Get detailed status for one member: connectivity, AI version, authentication, active session, resources, and git branch.', memberDetailSchema.shape, wrapTool('member_detail', (input) => memberDetail(input as any)));
+
+  // --- Maintenance ---
+  server.tool('update_llm_cli', "Update or install the AI provider CLI on members. Omit member to update all online members at once. Use install_if_missing to install on members that don't have it yet.", updateAgentCliSchema.shape, wrapTool('update_llm_cli', (input) => updateAgentCli(input as any)));
+  server.tool('shutdown_server', 'Gracefully shut down the MCP server. Run /mcp afterwards to start a fresh instance with the latest code.', shutdownServerSchema.shape, wrapTool('shutdown_server', () => shutdownServer()));
+  server.tool('version', 'Returns the installed apra-fleet server version', versionSchema.shape, wrapTool('version', () => version()));
+
+  // --- Permissions ---
+  server.tool('compose_permissions', 'Set up and deliver the right permissions to a member for their role. Automatically tailors permissions to the project type. Use grant to add specific permissions mid-sprint without a full recompose.', composePermissionsSchema.shape, wrapTool('compose_permissions', (input) => composePermissions(input as any)));
+
+  // --- Cloud Control ---
+  server.tool('cloud_control', 'Manually start, stop, or check status of a cloud fleet member. Start waits until the member is ready; stop is immediate.', cloudControlSchema.shape, wrapTool('cloud_control', (input) => cloudControl(input as any)));
+  server.tool('monitor_task', 'Check status of a long-running background task on a cloud member. Optionally stop the cloud instance automatically when the task completes.', monitorTaskSchema.shape, wrapTool('monitor_task', (input) => monitorTask(input as any)));
+
+  // --- Agent Lifecycle ---
+  server.tool('stop_prompt', 'Kill the active LLM process on a member. Always call TaskStop on the dispatching background agent after calling this.', stopPromptSchema.shape, wrapTool('stop_prompt', (input) => stopPrompt(input as any)));
+  // --- Credential Store ---
+  server.tool('credential_store_set', 'Collect a secret from the user out-of-band and store it. Returns a handle (sec://NAME) and scope. Use {{secure.NAME}} tokens in execute_command to inject the value.', credentialStoreSetSchema.shape, wrapTool('credential_store_set', (input) => credentialStoreSet(input as any)));
+  server.tool('credential_store_list', 'List all stored credentials (names and metadata only — no values).', credentialStoreListSchema.shape, wrapTool('credential_store_list', () => credentialStoreList()));
+  server.tool('credential_store_delete', 'Delete a named credential from the store (both session and persistent tiers).', credentialStoreDeleteSchema.shape, wrapTool('credential_store_delete', (input) => credentialStoreDelete(input as any)));
+  server.tool('credential_store_update', 'Update metadata (members, TTL, network policy) on an existing credential without re-entering the secret.', credentialStoreUpdateSchema.shape, wrapTool('credential_store_update', (input) => credentialStoreUpdate(input as any)));
+
+  // --- gbrain tools ---
+  server.tool('brain_query', 'Query the gbrain knowledge base for a member. Member must have gbrain enabled.', brainQuerySchema.shape, wrapTool('brain_query', (input) => brainQuery(input as any)));
+  server.tool('brain_write', 'Write knowledge to the gbrain brain for a member. Member must have gbrain enabled.', brainWriteSchema.shape, wrapTool('brain_write', (input) => brainWrite(input as any)));
+
+  // --- code analysis tools ---
+  server.tool('code_def', 'Find the definition of a symbol in the member\'s codebase. Member must have gbrain enabled.', codeDefSchema.shape, wrapTool('code_def', (input) => codeDef(input as any)));
+  server.tool('code_refs', 'Find all references to a symbol in the member\'s codebase. Member must have gbrain enabled.', codeRefsSchema.shape, wrapTool('code_refs', (input) => codeRefs(input as any)));
+  server.tool('code_callers', 'Find all callers of a function in the member\'s codebase. Member must have gbrain enabled.', codeCallersSchema.shape, wrapTool('code_callers', (input) => codeCallers(input as any)));
+  server.tool('code_callees', 'Find all callees of a function in the member\'s codebase. Member must have gbrain enabled.', codeCalleesSchema.shape, wrapTool('code_callees', (input) => codeCallees(input as any)));
+
+  // --- Minions job queue tools ---
+  server.tool('jobs_submit', 'Submit a task to the Minions job queue. Member must have gbrain enabled. For immediate work, use execute_prompt instead.', jobsSubmitSchema.shape, wrapTool('jobs_submit', (input) => jobsSubmit(input as any)));
+  server.tool('jobs_list', 'List jobs in the Minions queue, optionally filtered by status. Member must have gbrain enabled.', jobsListSchema.shape, wrapTool('jobs_list', (input) => jobsList(input as any)));
+  server.tool('jobs_stats', 'Get aggregate job queue statistics (counts by status, avg duration). Member must have gbrain enabled.', jobsStatsSchema.shape, wrapTool('jobs_stats', (input) => jobsStats(input as any)));
+  server.tool('jobs_work', 'Mark a Minions job as complete with a result. Member must have gbrain enabled.', jobsWorkSchema.shape, wrapTool('jobs_work', (input) => jobsWork(input as any)));
+
+  // --- Course correction tools ---
+  server.tool('course_correction_capture', 'Persist a course correction to the brain so future agents avoid the same mistake. No member or gbrain check needed — global brain op.', courseCorrectionCaptureSchema.shape, wrapTool('course_correction_capture', (input) => courseCorrectionCapture(input as any)));
+  server.tool('course_correction_recall', 'Recall past course corrections from the brain. Returns relevant past corrections or empty string if none found.', courseCorrectionRecallSchema.shape, wrapTool('course_correction_recall', (input) => courseCorrectionRecall(input as any)));
+
+  // --- Start Server ---
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  const { FLEET_DIR } = await import('./paths.js');
+  const stallDetector = getStallDetector();
+  stallDetector.start();
+
+  const clientStr = capturedClientInfo?.name ? ` client=${capturedClientInfo.name}` : '';
+  const versionStr = capturedClientInfo?.version ? ` version=${capturedClientInfo.version}` : '';
+  const pidStr = ` pid=${process.pid} ppid=${process.ppid}`;
+  logLine('startup', `apra-fleet ${serverVersion} started${clientStr}${versionStr}${pidStr} FLEET_DIR=${FLEET_DIR}`);
+
+  idleManager.start();
+  void cleanupStaleTasks();
+  purgeExpiredCredentials();
+  void checkForUpdate();
+
+  const { cleanupAuthSocket } = await import('./services/auth-socket.js');
+  const { getGbrainClient } = await import('./services/gbrain-client.js');
+  const gracefulShutdown = () => {
+    cleanupAuthSocket().then(async () => {
+      closeAllConnections();
+      stallDetector.stop();
+      await getGbrainClient().disconnect();
+      process.exit(0);
+    });
+  };
+  process.on('SIGINT', gracefulShutdown);
+  process.on('SIGTERM', gracefulShutdown);
+}
diff --git a/src/services/course-correction.ts b/src/services/course-correction.ts
new file mode 100644
index 00000000..521601d2
--- /dev/null
+++ b/src/services/course-correction.ts
@@ -0,0 +1,52 @@
+import { getGbrainClient } from './gbrain-client.js';
+
+export interface CourseCorrectionContext {
+  repo?: string;
+  member?: string;
+  attempted: string;
+  correction: string;
+  reason?: string;
+}
+
+/**
+ * Persist a course correction to the gbrain brain.
+ * Silent no-op if gbrain is not available.
+ */
+export async function captureCorrection(context: CourseCorrectionContext): Promise<void> {
+  const parts: string[] = [];
+  if (context.repo) parts.push(`On repo ${context.repo},`);
+  parts.push(`approach "${context.attempted}" was attempted.`);
+  parts.push(`User corrected to "${context.correction}".`);
+  if (context.reason) parts.push(`Because: ${context.reason}`);
+  const content = parts.join(' ');
+
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  const memberTag = context.member ? `\nmember: ${context.member}` : '';
+  const frontmatter = `---\ntags: [course-corrections]${memberTag}\n---\n`;
+
+  try {
+    await getGbrainClient().callTool('put_page', {
+      slug: `course-corrections/${ts}`,
+      content: frontmatter + content,
+    });
+  } catch {
+    // Silent no-op — gbrain may not be running
+  }
+}
+
+/**
+ * Recall past course corrections from the gbrain brain.
+ * Returns empty string if gbrain is not available.
+ */
+export async function recallCorrections(context: { repo?: string; query: string }): Promise<string> {
+  const queryParts: string[] = [];
+  if (context.repo) queryParts.push(`repo:${context.repo}`);
+  queryParts.push(context.query);
+  const query = queryParts.join(' ');
+
+  try {
+    return await getGbrainClient().callTool('search', { query });
+  } catch {
+    return '';
+  }
+}
diff --git a/src/services/gbrain-client.ts b/src/services/gbrain-client.ts
new file mode 100644
index 00000000..cb6f2632
--- /dev/null
+++ b/src/services/gbrain-client.ts
@@ -0,0 +1,132 @@
+// MCP client types are imported lazily inside connect() to avoid loading the
+// client SDK (and its ajv/ajv-formats transitive deps) at server startup time.
+// Loading it eagerly caused the fleet binary to crash on Linux SEA when the
+// MCP client SDK's AJV integration ran top-level initialisation code.
+
+export interface GbrainClientOptions {
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+}
+
+const DEFAULT_COMMAND = 'gbrain';
+const DEFAULT_ARGS = ['serve'];
+
+let instance: GbrainClient | null = null;
+
+export class GbrainClient {
+  private client: any | null = null;
+  private transport: any | null = null;
+  private availableTools: string[] = [];
+  private connected = false;
+  private options: Required<GbrainClientOptions>;
+
+  constructor(options: GbrainClientOptions = {}) {
+    this.options = {
+      command: options.command ?? process.env.GBRAIN_COMMAND ?? DEFAULT_COMMAND,
+      args: options.args ?? (process.env.GBRAIN_ARGS ? process.env.GBRAIN_ARGS.split(' ') : DEFAULT_ARGS),
+      env: options.env ?? {},
+    };
+  }
+
+  async connect(): Promise<void> {
+    if (this.connected) return;
+
+    // Lazy-load MCP client SDK — keeps it out of the server startup path
+    const { Client } = await import('@modelcontextprotocol/sdk/client/index.js');
+    const { StdioClientTransport } = await import('@modelcontextprotocol/sdk/client/stdio.js');
+
+    this.transport = new StdioClientTransport({
+      command: this.options.command,
+      args: this.options.args,
+      env: { ...process.env, ...this.options.env } as Record<string, string>,
+    });
+
+    this.client = new Client({ name: 'apra-fleet', version: '1.0.0' });
+
+    await this.client.connect(this.transport);
+    this.connected = true;
+
+    // Validate connection by listing available tools
+    const result = await this.client.listTools();
+    this.availableTools = result.tools.map((t: { name: string }) => t.name);
+  }
+
+  async disconnect(): Promise<void> {
+    if (!this.connected || !this.client) return;
+
+    try {
+      await this.client.close();
+    } catch {
+      // Ignore close errors — process may already be dead
+    }
+    this.client = null;
+    this.transport = null;
+    this.availableTools = [];
+    this.connected = false;
+  }
+
+  async callTool(toolName: string, args: Record<string, unknown> = {}): Promise<string> {
+    // Lazy reconnect on stale connection
+    if (!this.connected || !this.client) {
+      try {
+        await this.connect();
+      } catch (err) {
+        throw new Error(
+          `gbrain is not available — is the process running? Error: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
+
+    try {
+      const result = await this.client!.callTool({ name: toolName, arguments: args });
+      // Extract text content from MCP result
+      if (result.isError) {
+        const text = Array.isArray(result.content)
+          ? result.content
+              .filter((c: any): c is { type: 'text'; text: string } => c.type === 'text')
+              .map((c: any) => c.text)
+              .join('\n')
+          : String(result.content);
+        throw new Error(`gbrain tool '${toolName}' returned error: ${text}`);
+      }
+      if (Array.isArray(result.content)) {
+        return result.content
+          .filter((c: any): c is { type: 'text'; text: string } => c.type === 'text')
+          .map((c: any) => c.text)
+          .join('\n');
+      }
+      return String(result.content ?? '');
+    } catch (err) {
+      if (err instanceof Error && err.message.startsWith('gbrain tool')) throw err;
+      // Connection may have dropped — mark as disconnected for lazy reconnect
+      this.connected = false;
+      this.client = null;
+      this.transport = null;
+      throw new Error(
+        `gbrain call failed for '${toolName}' — connection may have dropped. Error: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+
+  isConnected(): boolean {
+    return this.connected;
+  }
+
+  getAvailableTools(): string[] {
+    return [...this.availableTools];
+  }
+}
+
+/** Get or create the singleton gbrain client instance. */
+export function getGbrainClient(options?: GbrainClientOptions): GbrainClient {
+  if (!instance) {
+    instance = new GbrainClient(options);
+  }
+  return instance;
+}
+
+/** Reset the singleton (for testing). */
+export function _resetGbrainClient(): void {
+  instance = null;
+}
diff --git a/src/tools/brain-query.ts b/src/tools/brain-query.ts
new file mode 100644
index 00000000..2f88f8ad
--- /dev/null
+++ b/src/tools/brain-query.ts
@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import { memberIdentifier, resolveMember } from '../utils/resolve-member.js';
+import { assertGbrainEnabled, callGbrainTool } from '../utils/gbrain-helpers.js';
+
+export const brainQuerySchema = z.object({
+  ...memberIdentifier,
+  query: z.string().describe('The question or query to ask the brain'),
+  collection: z.string().optional().describe('Optional brain collection or namespace to query'),
+});
+
+export type BrainQueryInput = z.infer<typeof brainQuerySchema>;
+
+export async function brainQuery(input: BrainQueryInput): Promise<string> {
+  const agentOrError = resolveMember(input.member_id, input.member_name);
+  if (typeof agentOrError === 'string') return agentOrError;
+
+  const gbrainError = assertGbrainEnabled(agentOrError);
+  if (gbrainError) return gbrainError;
+
+  // gbrain exposes keyword-only full-text search as "search".
+  // The collection filter is not natively supported; pass as part of the query.
+  const q = input.collection ? `${input.query} tags:${input.collection}` : input.query;
+  return callGbrainTool('search', { query: q });
+}
diff --git a/src/tools/brain-write.ts b/src/tools/brain-write.ts
new file mode 100644
index 00000000..f9496566
--- /dev/null
+++ b/src/tools/brain-write.ts
@@ -0,0 +1,34 @@
+import { z } from 'zod';
+import { memberIdentifier, resolveMember } from '../utils/resolve-member.js';
+import { assertGbrainEnabled, callGbrainTool } from '../utils/gbrain-helpers.js';
+
+export const brainWriteSchema = z.object({
+  ...memberIdentifier,
+  content: z.string().describe('The knowledge or information to store in the brain'),
+  collection: z.string().optional().describe('Optional brain collection or namespace'),
+  metadata: z.string().optional().describe('Optional JSON metadata to attach to the stored knowledge'),
+});
+
+export type BrainWriteInput = z.infer<typeof brainWriteSchema>;
+
+export async function brainWrite(input: BrainWriteInput): Promise<string> {
+  const agentOrError = resolveMember(input.member_id, input.member_name);
+  if (typeof agentOrError === 'string') return agentOrError;
+
+  const gbrainError = assertGbrainEnabled(agentOrError);
+  if (gbrainError) return gbrainError;
+
+  // gbrain stores pages via put_page. Generate a unique slug under the
+  // collection namespace (or "notes" if none given). Metadata is embedded
+  // in YAML frontmatter inside the content.
+  const ns = input.collection ?? 'notes';
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  const slug = `${ns}/${ts}`;
+  const frontmatter = input.metadata
+    ? `---\ntags: [${ns}]\nmetadata: ${input.metadata}\n---\n`
+    : `---\ntags: [${ns}]\n---\n`;
+  return callGbrainTool('put_page', {
+    slug,
+    content: frontmatter + input.content,
+  });
+}
diff --git a/src/tools/code-callees.ts b/src/tools/code-callees.ts
new file mode 100644
index 00000000..975efc2d
--- /dev/null
+++ b/src/tools/code-callees.ts
@@ -0,0 +1,21 @@
+import { z } from 'zod';
+import { memberIdentifier, resolveMember } from '../utils/resolve-member.js';
+import { assertGbrainEnabled, callGbrainTool } from '../utils/gbrain-helpers.js';
+
+export const codeCalleesSchema = z.object({
+  ...memberIdentifier,
+  symbol: z.string().describe('The function to find callees of'),
+});
+
+export type CodeCalleesInput = z.infer<typeof codeCalleesSchema>;
+
+export async function codeCallees(input: CodeCalleesInput): Promise<string> {
+  const agentOrError = resolveMember(input.member_id, input.member_name);
+  if (typeof agentOrError === 'string') return agentOrError;
+
+  const gbrainError = assertGbrainEnabled(agentOrError);
+  if (gbrainError) return gbrainError;
+
+  // gbrain exposes callees via the "query" tool with near_symbol anchor.
+  return callGbrainTool('query', { query: `functions called by ${input.symbol}`, near_symbol: input.symbol, walk_depth: 1 });
+}
diff --git a/src/tools/code-callers.ts b/src/tools/code-callers.ts
new file mode 100644
index 00000000..0d596757
--- /dev/null
+++ b/src/tools/code-callers.ts
@@ -0,0 +1,21 @@
+import { z } from 'zod';
+import { memberIdentifier, resolveMember } from '../utils/resolve-member.js';
+import { assertGbrainEnabled, callGbrainTool } from '../utils/gbrain-helpers.js';
+
+export const codeCallersSchema = z.object({
+  ...memberIdentifier,
+  symbol: z.string().describe('The function to find callers of'),
+});
+
+export type CodeCallersInput = z.infer<typeof codeCallersSchema>;
+
+export async function codeCallers(input: CodeCallersInput): Promise<string> {
+  const agentOrError = resolveMember(input.member_id, input.member_name);
+  if (typeof agentOrError === 'string') return agentOrError;
+
+  const gbrainError = assertGbrainEnabled(agentOrError);
+  if (gbrainError) return gbrainError;
+
+  // gbrain exposes callers via the "query" tool with near_symbol anchor.
+  return callGbrainTool('query', { query: `callers of ${input.symbol}`, near_symbol: input.symbol, walk_depth: 1 });
+}
diff --git a/src/tools/code-def.ts b/src/tools/code-def.ts
new file mode 100644
index 00000000..01ca16b7
--- /dev/null
+++ b/src/tools/code-def.ts
@@ -0,0 +1,21 @@
+import { z } from 'zod';
+import { memberIdentifier, resolveMember } from '../utils/resolve-member.js';
+import { assertGbrainEnabled, callGbrainTool } from '../utils/gbrain-helpers.js';
+
+export const codeDefSchema = z.object({
+  ...memberIdentifier,
+  symbol: z.string().describe('The symbol (function, class, variable, etc.) to find the definition of'),
+});
+
+export type CodeDefInput = z.infer<typeof codeDefSchema>;
+
+export async function codeDef(input: CodeDefInput): Promise<string> {
+  const agentOrError = resolveMember(input.member_id, input.member_name);
+  if (typeof agentOrError === 'string') return agentOrError;
+
+  const gbrainError = assertGbrainEnabled(agentOrError);
+  if (gbrainError) return gbrainError;
+
+  // gbrain exposes symbol lookup via the "query" tool with near_symbol anchor.
+  return callGbrainTool('query', { near_symbol: input.symbol, walk_depth: 1, detail: 'high' });
+}
diff --git a/src/tools/code-refs.ts b/src/tools/code-refs.ts
new file mode 100644
index 00000000..ea26a26f
--- /dev/null
+++ b/src/tools/code-refs.ts
@@ -0,0 +1,21 @@
+import { z } from 'zod';
+import { memberIdentifier, resolveMember } from '../utils/resolve-member.js';
+import { assertGbrainEnabled, callGbrainTool } from '../utils/gbrain-helpers.js';
+
+export const codeRefsSchema = z.object({
+  ...memberIdentifier,
+  symbol: z.string().describe('The symbol to find all references to'),
+});
+
+export type CodeRefsInput = z.infer<typeof codeRefsSchema>;
+
+export async function codeRefs(input: CodeRefsInput): Promise<string> {
+  const agentOrError = resolveMember(input.member_id, input.member_name);
+  if (typeof agentOrError === 'string') return agentOrError;
+
+  const gbrainError = assertGbrainEnabled(agentOrError);
+  if (gbrainError) return gbrainError;
+
+  // gbrain exposes cross-references via the "query" tool with near_symbol + walk.
+  return callGbrainTool('query', { near_symbol: input.symbol, walk_depth: 2 });
+}
diff --git a/src/tools/course-correction.ts b/src/tools/course-correction.ts
new file mode 100644
index 00000000..77d6b8f7
--- /dev/null
+++ b/src/tools/course-correction.ts
@@ -0,0 +1,34 @@
+import { z } from 'zod';
+import { captureCorrection, recallCorrections } from '../services/course-correction.js';
+
+export const courseCorrectionCaptureSchema = z.object({
+  attempted: z.string().describe('The approach that was attempted'),
+  correction: z.string().describe('The corrected approach the user specified'),
+  reason: z.string().optional().describe('Why the original approach was wrong'),
+  repo: z.string().optional().describe('Repository context (e.g. owner/repo)'),
+  member_name: z.string().optional().describe('Name of the member that made the attempt'),
+});
+
+export type CourseCorrectionCaptureInput = z.infer<typeof courseCorrectionCaptureSchema>;
+
+export async function courseCorrectionCapture(input: CourseCorrectionCaptureInput): Promise<string> {
+  await captureCorrection({
+    attempted: input.attempted,
+    correction: input.correction,
+    reason: input.reason,
+    repo: input.repo,
+    member: input.member_name,
+  });
+  return 'Course correction captured.';
+}
+
+export const courseCorrectionRecallSchema = z.object({
+  query: z.string().describe('Search query to look up past corrections'),
+  repo: z.string().optional().describe('Narrow results to a specific repository'),
+});
+
+export type CourseCorrectionRecallInput = z.infer<typeof courseCorrectionRecallSchema>;
+
+export async function courseCorrectionRecall(input: CourseCorrectionRecallInput): Promise<string> {
+  return recallCorrections({ query: input.query, repo: input.repo });
+}
diff --git a/src/tools/jobs-list.ts b/src/tools/jobs-list.ts
new file mode 100644
index 00000000..71fb0d13
--- /dev/null
+++ b/src/tools/jobs-list.ts
@@ -0,0 +1,23 @@
+import { z } from 'zod';
+import { memberIdentifier, resolveMember } from '../utils/resolve-member.js';
+import { assertGbrainEnabled, callGbrainTool } from '../utils/gbrain-helpers.js';
+
+export const jobsListSchema = z.object({
+  ...memberIdentifier,
+  status: z.string().optional().describe('Filter jobs by status (queued, running, completed, failed, cancelled)'),
+});
+
+export type JobsListInput = z.infer<typeof jobsListSchema>;
+
+export async function jobsList(input: JobsListInput): Promise<string> {
+  const agentOrError = resolveMember(input.member_id, input.member_name);
+  if (typeof agentOrError === 'string') return agentOrError;
+
+  const gbrainError = assertGbrainEnabled(agentOrError);
+  if (gbrainError) return gbrainError;
+
+  // gbrain's internal job queue is exposed via "list_jobs".
+  return callGbrainTool('list_jobs', {
+    ...(input.status ? { status: input.status } : {}),
+  });
+}
diff --git a/src/tools/jobs-stats.ts b/src/tools/jobs-stats.ts
new file mode 100644
index 00000000..0dcd4064
--- /dev/null
+++ b/src/tools/jobs-stats.ts
@@ -0,0 +1,21 @@
+import { z } from 'zod';
+import { memberIdentifier, resolveMember } from '../utils/resolve-member.js';
+import { assertGbrainEnabled, callGbrainTool } from '../utils/gbrain-helpers.js';
+
+export const jobsStatsSchema = z.object({
+  ...memberIdentifier,
+});
+
+export type JobsStatsInput = z.infer<typeof jobsStatsSchema>;
+
+export async function jobsStats(input: JobsStatsInput): Promise<string> {
+  const agentOrError = resolveMember(input.member_id, input.member_name);
+  if (typeof agentOrError === 'string') return agentOrError;
+
+  const gbrainError = assertGbrainEnabled(agentOrError);
+  if (gbrainError) return gbrainError;
+
+  // gbrain does not expose a dedicated stats endpoint; delegate to list_jobs
+  // and let the caller interpret the counts from the returned job list.
+  return callGbrainTool('list_jobs', { limit: 100 });
+}
diff --git a/src/tools/jobs-submit.ts b/src/tools/jobs-submit.ts
new file mode 100644
index 00000000..e0933dc5
--- /dev/null
+++ b/src/tools/jobs-submit.ts
@@ -0,0 +1,26 @@
+import { z } from 'zod';
+import { memberIdentifier, resolveMember } from '../utils/resolve-member.js';
+import { assertGbrainEnabled, callGbrainTool } from '../utils/gbrain-helpers.js';
+
+export const jobsSubmitSchema = z.object({
+  ...memberIdentifier,
+  task: z.string().describe('The task description to submit to the job queue'),
+  priority: z.number().optional().describe('Job priority (0=critical, 4=backlog, default 2)'),
+});
+
+export type JobsSubmitInput = z.infer<typeof jobsSubmitSchema>;
+
+export async function jobsSubmit(input: JobsSubmitInput): Promise<string> {
+  const agentOrError = resolveMember(input.member_id, input.member_name);
+  if (typeof agentOrError === 'string') return agentOrError;
+
+  const gbrainError = assertGbrainEnabled(agentOrError);
+  if (gbrainError) return `${gbrainError} For immediate work, use execute_prompt instead.`;
+
+  // gbrain's internal job queue is exposed via "submit_job".
+  return callGbrainTool('submit_job', {
+    name: 'autopilot-cycle',
+    data: { task: input.task },
+    ...(input.priority !== undefined ? { priority: input.priority } : {}),
+  });
+}
diff --git a/src/tools/jobs-work.ts b/src/tools/jobs-work.ts
new file mode 100644
index 00000000..8c9e7b88
--- /dev/null
+++ b/src/tools/jobs-work.ts
@@ -0,0 +1,26 @@
+import { z } from 'zod';
+import { memberIdentifier, resolveMember } from '../utils/resolve-member.js';
+import { assertGbrainEnabled, callGbrainTool } from '../utils/gbrain-helpers.js';
+
+export const jobsWorkSchema = z.object({
+  ...memberIdentifier,
+  job_id: z.string().describe('The ID of the job to mark as complete'),
+  result: z.string().describe('The result or output of the completed job'),
+});
+
+export type JobsWorkInput = z.infer<typeof jobsWorkSchema>;
+
+export async function jobsWork(input: JobsWorkInput): Promise<string> {
+  const agentOrError = resolveMember(input.member_id, input.member_name);
+  if (typeof agentOrError === 'string') return agentOrError;
+
+  const gbrainError = assertGbrainEnabled(agentOrError);
+  if (gbrainError) return gbrainError;
+
+  // gbrain manages job lifecycle internally; there is no manual job completion
+  // tool. Persist the result as a brain page under the jobs namespace instead.
+  return callGbrainTool('put_page', {
+    slug: `jobs/${input.job_id}`,
+    content: `---\ntags: [jobs, completed]\n---\n${input.result}`,
+  });
+}
diff --git a/src/tools/list-members.ts b/src/tools/list-members.ts
index e98051eb..9c83fbff 100644
--- a/src/tools/list-members.ts
+++ b/src/tools/list-members.ts
@@ -85,6 +85,7 @@ export async function listMembers(input?: ListMembersInput): Promise<string> {
         os: a.os ?? 'unknown',
         folder: a.workFolder,
         llmProvider: a.llmProvider ?? 'claude',
+        gbrain: a.gbrain ?? false,
         llm_auth: authStatuses[i],
         ssh_auth: a.agentType === 'local' ? undefined : a.authType,
         session: a.sessionId ?? null,
@@ -100,8 +101,11 @@ export async function listMembers(input?: ListMembersInput): Promise<string> {
     const icon = a.icon ?? DEFAULT_ICON;
     const host = a.agentType === 'local' ? 'local' : `${a.host}:${a.port}`;
     const authStatus = authStatuses[i];
-    
+
     t += `  ${icon} ${a.friendlyName}: ${a.id} | ${host} | ${a.os ?? '?'} | provider=${a.llmProvider ?? 'claude'}`;
+    if (a.gbrain) {
+      t += ` | gbrain=enabled`;
+    }
     if (a.agentType !== 'local') {
       t += ` | user=${a.username} | ssh=${a.authType}`;
       if (authStatus !== 'offline' && authStatus !== 'N/A') {
diff --git a/src/tools/member-detail.ts b/src/tools/member-detail.ts
index d28dd43f..d1011719 100644
--- a/src/tools/member-detail.ts
+++ b/src/tools/member-detail.ts
@@ -39,6 +39,7 @@ export async function memberDetail(input: MemberDetailInput): Promise<string> {
     username: agent.username ?? undefined,
     os,
     folder: agent.workFolder,
+    gbrain: agent.gbrain ?? false,
   };
 
   // -- Cloud Info (parallel with connectivity check) --
@@ -257,7 +258,8 @@ export async function memberDetail(input: MemberDetailInput): Promise<string> {
 
   const icon = agent.icon ?? DEFAULT_ICON;
   const userStr = agent.username ? ` | user=${agent.username}` : '';
-  let t = `${icon} ${agent.friendlyName} (${agent.agentType})${userStr} | ${connStatus} | os=${os} | provider=${agent.llmProvider ?? 'claude'} | cli=${cli.version}\n`;
+  const gbrainStr = agent.gbrain ? ' | gbrain=enabled' : '';
+  let t = `${icon} ${agent.friendlyName} (${agent.agentType})${userStr} | ${connStatus} | os=${os} | provider=${agent.llmProvider ?? 'claude'} | cli=${cli.version}${gbrainStr}\n`;
   const tokenStr = agent.tokenUsage ? ` | tokens=in:${agent.tokenUsage.input} out:${agent.tokenUsage.output}` : '';
   t += `  auth=${authStr} | session=${sessId} (${sessStatus}) | last=${agent.lastUsed ?? 'never'}${tokenStr}\n`;
   const branchStr = branch ? ` | branch=${branch}` : '';
diff --git a/src/tools/register-member.ts b/src/tools/register-member.ts
index 400c0c21..13301951 100644
--- a/src/tools/register-member.ts
+++ b/src/tools/register-member.ts
@@ -42,6 +42,7 @@ export const registerMemberSchema = z.object({
   cloud_activity_command: z.string().min(1).optional().describe('Custom shell command for workload detection. Must output "busy" or "idle" on stdout. Checked after GPU, before process check. Useful for CPU-intensive tasks, downloads, or any non-GPU workload.'),
   llm_provider: z.enum(['claude', 'gemini', 'codex', 'copilot']).optional().default('claude').describe('LLM provider for this member (default: "claude"). Determines which CLI is used for execute_prompt, provision_llm_auth, and update_llm_cli.'),
   unattended: z.union([z.literal(false), z.literal('auto'), z.literal('dangerous')]).optional().describe('Permission mode for unattended execution. false (default) = interactive prompts; "auto" = auto-approve safe operations; "dangerous" = skip all permission checks.'),
+  gbrain: z.boolean().optional().default(false).describe('Enable gbrain integration for this member (default: false)'),
 });
 
 export type RegisterMemberInput = z.infer<typeof registerMemberSchema>;
@@ -174,6 +175,7 @@ export async function registerMember(input: RegisterMemberInput): Promise<string
     cloud: cloudConfig,
     llmProvider: input.llm_provider ?? 'claude',
     unattended: input.unattended ?? false,
+    gbrain: input.gbrain ?? false,
   };
 
   // --- SSH-dependent steps (skipped for stopped cloud instances) ---
diff --git a/src/tools/update-member.ts b/src/tools/update-member.ts
index 94eb1396..1804b9dc 100644
--- a/src/tools/update-member.ts
+++ b/src/tools/update-member.ts
@@ -43,6 +43,7 @@ export const updateMemberSchema = z.object({
   cloud_activity_command: z.string().optional().describe('Custom shell command for workload detection. Must output "busy" or "idle". Pass empty string to clear.'),
   llm_provider: z.enum(['claude', 'gemini', 'codex', 'copilot']).optional().describe('Change the LLM provider for this member.'),
   unattended: z.union([z.literal(false), z.literal('auto'), z.literal('dangerous')]).optional().describe('Permission mode for unattended execution. false = interactive prompts; "auto" = auto-approve safe operations; "dangerous" = skip all permission checks.'),
+  gbrain: z.boolean().optional().describe('Enable or disable gbrain integration for this member'),
 });
 
 export type UpdateMemberInput = z.infer<typeof updateMemberSchema>;
@@ -120,6 +121,7 @@ export async function updateMember(input: UpdateMemberInput): Promise<string> {
   if (input.friendly_name) updates.friendlyName = input.friendly_name;
   if (input.llm_provider !== undefined) updates.llmProvider = input.llm_provider;
   if (input.unattended !== undefined) updates.unattended = input.unattended;
+  if (input.gbrain !== undefined) updates.gbrain = input.gbrain;
   if (input.host) updates.host = input.host;
   if (input.port) updates.port = input.port;
   if (input.username) updates.username = input.username;
diff --git a/src/types.ts b/src/types.ts
index 20de1fb5..3f2f129b 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -30,6 +30,7 @@ export interface Agent {
   tokenUsage?: { input: number; output: number };
   unattended?: false | 'auto' | 'dangerous';
   lastLlmActivityAt?: string;  // ISO 8601
+  gbrain?: boolean;
 }
 
 export interface GitHubAppConfig {
diff --git a/src/utils/gbrain-helpers.ts b/src/utils/gbrain-helpers.ts
new file mode 100644
index 00000000..1c15c5ec
--- /dev/null
+++ b/src/utils/gbrain-helpers.ts
@@ -0,0 +1,29 @@
+import { getGbrainClient } from '../services/gbrain-client.js';
+import type { Agent } from '../types.js';
+
+/**
+ * Check if gbrain is enabled on an agent.
+ * Returns null if OK, or an error string if not enabled.
+ */
+export function assertGbrainEnabled(agent: Agent): string | null {
+  if (!agent.gbrain) {
+    return `gbrain is not enabled on this member. Use update_member to enable it.`;
+  }
+  return null;
+}
+
+/**
+ * Proxy a tool call to the gbrain MCP server with standard error handling.
+ */
+export async function callGbrainTool(toolName: string, args: Record<string, unknown>): Promise<string> {
+  const client = getGbrainClient();
+  try {
+    return await client.callTool(toolName, args);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes('gbrain is not available')) {
+      return `gbrain server is not available. Ensure it is running — see docs.`;
+    }
+    return `gbrain tool '${toolName}' failed: ${msg}`;
+  }
+}
diff --git a/tests/brain-tools.test.ts b/tests/brain-tools.test.ts
new file mode 100644
index 00000000..e58b1d7a
--- /dev/null
+++ b/tests/brain-tools.test.ts
@@ -0,0 +1,151 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { makeTestAgent, backupAndResetRegistry, restoreRegistry } from './test-helpers.js';
+import { addAgent } from '../src/services/registry.js';
+import { brainQuery } from '../src/tools/brain-query.js';
+import { brainWrite } from '../src/tools/brain-write.js';
+
+// Mock the gbrain client singleton
+const mockCallTool = vi.fn<(toolName: string, args: Record<string, unknown>) => Promise<string>>();
+
+vi.mock('../src/services/gbrain-client.js', () => ({
+  getGbrainClient: () => ({ callTool: mockCallTool }),
+  _resetGbrainClient: vi.fn(),
+}));
+
+beforeEach(() => {
+  backupAndResetRegistry();
+  vi.clearAllMocks();
+});
+afterEach(() => restoreRegistry());
+
+// ---------------------------------------------------------------------------
+// brain_query — delegates to gbrain "search" (BM25 keyword search)
+// ---------------------------------------------------------------------------
+
+describe('brain_query', () => {
+  it('returns brain result for a gbrain-enabled member', async () => {
+    const agent = makeTestAgent({ gbrain: true });
+    addAgent(agent);
+    mockCallTool.mockResolvedValue('The answer is 42');
+
+    const result = await brainQuery({ member_id: agent.id, query: 'what is life?' });
+
+    expect(mockCallTool).toHaveBeenCalledWith('search', { query: 'what is life?' });
+    expect(result).toBe('The answer is 42');
+  });
+
+  it('appends collection as tag filter when provided', async () => {
+    const agent = makeTestAgent({ gbrain: true });
+    addAgent(agent);
+    mockCallTool.mockResolvedValue('result');
+
+    await brainQuery({ member_id: agent.id, query: 'hello', collection: 'docs' });
+
+    expect(mockCallTool).toHaveBeenCalledWith('search', { query: 'hello tags:docs' });
+  });
+
+  it('returns error when member does not have gbrain enabled', async () => {
+    const agent = makeTestAgent({ gbrain: false });
+    addAgent(agent);
+
+    const result = await brainQuery({ member_id: agent.id, query: 'what?' });
+
+    expect(result).toContain('gbrain is not enabled');
+    expect(mockCallTool).not.toHaveBeenCalled();
+  });
+
+  it('returns error when member has no gbrain field', async () => {
+    const agent = makeTestAgent();
+    addAgent(agent);
+
+    const result = await brainQuery({ member_id: agent.id, query: 'what?' });
+
+    expect(result).toContain('gbrain is not enabled');
+    expect(mockCallTool).not.toHaveBeenCalled();
+  });
+
+  it('returns error when member is not found', async () => {
+    const result = await brainQuery({ member_id: 'nonexistent-id', query: 'what?' });
+
+    expect(result).toContain('not found');
+    expect(mockCallTool).not.toHaveBeenCalled();
+  });
+
+  it('returns error when gbrain server is unavailable', async () => {
+    const agent = makeTestAgent({ gbrain: true });
+    addAgent(agent);
+    mockCallTool.mockRejectedValue(new Error('gbrain is not available — is the process running?'));
+
+    const result = await brainQuery({ member_id: agent.id, query: 'hello' });
+
+    expect(result).toContain('gbrain server is not available');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// brain_write — delegates to gbrain "put_page" with slug + frontmatter
+// ---------------------------------------------------------------------------
+
+describe('brain_write', () => {
+  it('writes to brain for a gbrain-enabled member', async () => {
+    const agent = makeTestAgent({ gbrain: true });
+    addAgent(agent);
+    mockCallTool.mockResolvedValue('Stored successfully');
+
+    const result = await brainWrite({ member_id: agent.id, content: 'important knowledge' });
+
+    expect(mockCallTool).toHaveBeenCalledWith('put_page', expect.objectContaining({
+      slug: expect.stringContaining('notes/'),
+      content: expect.stringContaining('important knowledge'),
+    }));
+    expect(result).toBe('Stored successfully');
+  });
+
+  it('uses collection as namespace in slug and frontmatter', async () => {
+    const agent = makeTestAgent({ gbrain: true });
+    addAgent(agent);
+    mockCallTool.mockResolvedValue('ok');
+
+    await brainWrite({
+      member_id: agent.id,
+      content: 'stuff',
+      collection: 'docs',
+      metadata: '{"source":"test"}',
+    });
+
+    expect(mockCallTool).toHaveBeenCalledWith('put_page', expect.objectContaining({
+      slug: expect.stringContaining('docs/'),
+      content: expect.stringContaining('stuff'),
+    }));
+    const callArgs = mockCallTool.mock.calls[0][1] as { content: string };
+    expect(callArgs.content).toContain('tags: [docs]');
+    expect(callArgs.content).toContain('{"source":"test"}');
+  });
+
+  it('returns error when member does not have gbrain enabled', async () => {
+    const agent = makeTestAgent({ gbrain: false });
+    addAgent(agent);
+
+    const result = await brainWrite({ member_id: agent.id, content: 'stuff' });
+
+    expect(result).toContain('gbrain is not enabled');
+    expect(mockCallTool).not.toHaveBeenCalled();
+  });
+
+  it('returns error when member is not found', async () => {
+    const result = await brainWrite({ member_id: 'nonexistent-id', content: 'stuff' });
+
+    expect(result).toContain('not found');
+    expect(mockCallTool).not.toHaveBeenCalled();
+  });
+
+  it('returns error when gbrain server is unavailable', async () => {
+    const agent = makeTestAgent({ gbrain: true });
+    addAgent(agent);
+    mockCallTool.mockRejectedValue(new Error('gbrain is not available — is the process running?'));
+
+    const result = await brainWrite({ member_id: agent.id, content: 'stuff' });
+
+    expect(result).toContain('gbrain server is not available');
+  });
+});
diff --git a/tests/code-analysis-tools.test.ts b/tests/code-analysis-tools.test.ts
new file mode 100644
index 00000000..264f8951
--- /dev/null
+++ b/tests/code-analysis-tools.test.ts
@@ -0,0 +1,158 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { makeTestAgent, backupAndResetRegistry, restoreRegistry } from './test-helpers.js';
+import { addAgent } from '../src/services/registry.js';
+import { codeDef } from '../src/tools/code-def.js';
+import { codeRefs } from '../src/tools/code-refs.js';
+import { codeCallers } from '../src/tools/code-callers.js';
+import { codeCallees } from '../src/tools/code-callees.js';
+
+// Mock the gbrain client singleton
+const mockCallTool = vi.fn<(toolName: string, args: Record<string, unknown>) => Promise<string>>();
+
+vi.mock('../src/services/gbrain-client.js', () => ({
+  getGbrainClient: () => ({ callTool: mockCallTool }),
+  _resetGbrainClient: vi.fn(),
+}));
+
+beforeEach(() => {
+  backupAndResetRegistry();
+  vi.clearAllMocks();
+});
+afterEach(() => restoreRegistry());
+
+// ---------------------------------------------------------------------------
+// code_def — delegates to gbrain "query" with near_symbol anchor
+// ---------------------------------------------------------------------------
+
+describe('code_def', () => {
+  it('returns definition for a gbrain-enabled member', async () => {
+    const agent = makeTestAgent({ gbrain: true });
+    addAgent(agent);
+    mockCallTool.mockResolvedValue('src/utils/foo.ts:10 — function foo() {}');
+
+    const result = await codeDef({ member_id: agent.id, symbol: 'foo' });
+
+    expect(mockCallTool).toHaveBeenCalledWith('query', { near_symbol: 'foo', walk_depth: 1, detail: 'high' });
+    expect(result).toBe('src/utils/foo.ts:10 — function foo() {}');
+  });
+
+  it('returns error when gbrain is not enabled', async () => {
+    const agent = makeTestAgent({ gbrain: false });
+    addAgent(agent);
+
+    const result = await codeDef({ member_id: agent.id, symbol: 'foo' });
+
+    expect(result).toContain('gbrain is not enabled');
+    expect(mockCallTool).not.toHaveBeenCalled();
+  });
+
+  it('returns error when member is not found', async () => {
+    const result = await codeDef({ member_id: 'nonexistent-id', symbol: 'foo' });
+
+    expect(result).toContain('not found');
+    expect(mockCallTool).not.toHaveBeenCalled();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// code_refs — delegates to gbrain "query" with near_symbol + walk_depth 2
+// ---------------------------------------------------------------------------
+
+describe('code_refs', () => {
+  it('returns references for a gbrain-enabled member', async () => {
+    const agent = makeTestAgent({ gbrain: true });
+    addAgent(agent);
+    mockCallTool.mockResolvedValue('3 references found');
+
+    const result = await codeRefs({ member_id: agent.id, symbol: 'foo' });
+
+    expect(mockCallTool).toHaveBeenCalledWith('query', { near_symbol: 'foo', walk_depth: 2 });
+    expect(result).toBe('3 references found');
+  });
+
+  it('returns error when gbrain is not enabled', async () => {
+    const agent = makeTestAgent({ gbrain: false });
+    addAgent(agent);
+
+    const result = await codeRefs({ member_id: agent.id, symbol: 'foo' });
+
+    expect(result).toContain('gbrain is not enabled');
+    expect(mockCallTool).not.toHaveBeenCalled();
+  });
+
+  it('returns error when member is not found', async () => {
+    const result = await codeRefs({ member_id: 'nonexistent-id', symbol: 'foo' });
+
+    expect(result).toContain('not found');
+    expect(mockCallTool).not.toHaveBeenCalled();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// code_callers — delegates to gbrain "query" with near_symbol + callers query
+// ---------------------------------------------------------------------------
+
+describe('code_callers', () => {
+  it('returns callers for a gbrain-enabled member', async () => {
+    const agent = makeTestAgent({ gbrain: true });
+    addAgent(agent);
+    mockCallTool.mockResolvedValue('2 callers found');
+
+    const result = await codeCallers({ member_id: agent.id, symbol: 'bar' });
+
+    expect(mockCallTool).toHaveBeenCalledWith('query', {
+      query: 'callers of bar',
+      near_symbol: 'bar',
+      walk_depth: 1,
+    });
+    expect(result).toBe('2 callers found');
+  });
+
+  it('returns error when gbrain is not enabled', async () => {
+    const agent = makeTestAgent({ gbrain: false });
+    addAgent(agent);
+
+    const result = await codeCallers({ member_id: agent.id, symbol: 'bar' });
+
+    expect(result).toContain('gbrain is not enabled');
+    expect(mockCallTool).not.toHaveBeenCalled();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// code_callees — delegates to gbrain "query" with near_symbol + callees query
+// ---------------------------------------------------------------------------
+
+describe('code_callees', () => {
+  it('returns callees for a gbrain-enabled member', async () => {
+    const agent = makeTestAgent({ gbrain: true });
+    addAgent(agent);
+    mockCallTool.mockResolvedValue('5 callees found');
+
+    const result = await codeCallees({ member_id: agent.id, symbol: 'baz' });
+
+    expect(mockCallTool).toHaveBeenCalledWith('query', {
+      query: 'functions called by baz',
+      near_symbol: 'baz',
+      walk_depth: 1,
+    });
+    expect(result).toBe('5 callees found');
+  });
+
+  it('returns error when gbrain is not enabled', async () => {
+    const agent = makeTestAgent({ gbrain: false });
+    addAgent(agent);
+
+    const result = await codeCallees({ member_id: agent.id, symbol: 'baz' });
+
+    expect(result).toContain('gbrain is not enabled');
+    expect(mockCallTool).not.toHaveBeenCalled();
+  });
+
+  it('returns error when member is not found', async () => {
+    const result = await codeCallees({ member_id: 'nonexistent-id', symbol: 'baz' });
+
+    expect(result).toContain('not found');
+    expect(mockCallTool).not.toHaveBeenCalled();
+  });
+});
diff --git a/tests/course-correction.test.ts b/tests/course-correction.test.ts
new file mode 100644
index 00000000..31176800
--- /dev/null
+++ b/tests/course-correction.test.ts
@@ -0,0 +1,117 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { captureCorrection, recallCorrections } from '../src/services/course-correction.js';
+import { courseCorrectionCapture, courseCorrectionRecall } from '../src/tools/course-correction.js';
+
+// Mock the gbrain client singleton
+const mockCallTool = vi.fn<(toolName: string, args: Record<string, unknown>) => Promise<string>>();
+
+vi.mock('../src/services/gbrain-client.js', () => ({
+  getGbrainClient: () => ({ callTool: mockCallTool }),
+  _resetGbrainClient: vi.fn(),
+}));
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+// ---------------------------------------------------------------------------
+// captureCorrection service — stores via gbrain "put_page"
+// ---------------------------------------------------------------------------
+
+describe('captureCorrection', () => {
+  it('calls put_page with correctly formatted message', async () => {
+    mockCallTool.mockResolvedValue('ok');
+
+    await captureCorrection({
+      repo: 'owner/repo',
+      attempted: 'use merge',
+      correction: 'use rebase',
+      reason: 'merge commits clutter the log',
+    });
+
+    expect(mockCallTool).toHaveBeenCalledWith('put_page', expect.objectContaining({
+      slug: expect.stringContaining('course-corrections/'),
+      content: expect.stringContaining('use merge'),
+    }));
+    const callArgs = mockCallTool.mock.calls[0][1] as { content: string };
+    expect(callArgs.content).toContain('use rebase');
+    expect(callArgs.content).toContain('merge commits clutter the log');
+  });
+
+  it('is silent no-op when gbrain is unavailable — does not throw', async () => {
+    mockCallTool.mockRejectedValue(new Error('gbrain is not available — is the process running?'));
+
+    await expect(captureCorrection({
+      attempted: 'bad approach',
+      correction: 'good approach',
+    })).resolves.toBeUndefined();
+
+    expect(mockCallTool).toHaveBeenCalled();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// recallCorrections service — queries via gbrain "search"
+// ---------------------------------------------------------------------------
+
+describe('recallCorrections', () => {
+  it('calls search and returns result', async () => {
+    mockCallTool.mockResolvedValue('past correction: avoid X because Y');
+
+    const result = await recallCorrections({ query: 'rebase strategy' });
+
+    expect(mockCallTool).toHaveBeenCalledWith('search', expect.objectContaining({
+      query: expect.stringContaining('rebase strategy'),
+    }));
+    expect(result).toBe('past correction: avoid X because Y');
+  });
+
+  it('returns empty string when gbrain is unavailable', async () => {
+    mockCallTool.mockRejectedValue(new Error('gbrain is not available — is the process running?'));
+
+    const result = await recallCorrections({ query: 'some query' });
+
+    expect(result).toBe('');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// course_correction_capture tool
+// ---------------------------------------------------------------------------
+
+describe('course_correction_capture tool', () => {
+  it('routes to captureCorrection and returns confirmation', async () => {
+    mockCallTool.mockResolvedValue('ok');
+
+    const result = await courseCorrectionCapture({
+      attempted: 'do X',
+      correction: 'do Y',
+      reason: 'X breaks CI',
+      repo: 'owner/repo',
+      member_name: 'alice',
+    });
+
+    expect(mockCallTool).toHaveBeenCalledWith('put_page', expect.objectContaining({
+      slug: expect.stringContaining('course-corrections/'),
+      content: expect.stringContaining('do X'),
+    }));
+    expect(result).toBe('Course correction captured.');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// course_correction_recall tool
+// ---------------------------------------------------------------------------
+
+describe('course_correction_recall tool', () => {
+  it('routes to recallCorrections and returns brain result', async () => {
+    mockCallTool.mockResolvedValue('use rebase not merge');
+
+    const result = await courseCorrectionRecall({ query: 'git workflow', repo: 'owner/repo' });
+
+    expect(mockCallTool).toHaveBeenCalledWith('search', expect.objectContaining({
+      query: expect.stringContaining('git workflow'),
+    }));
+    expect(result).toBe('use rebase not merge');
+  });
+});
diff --git a/tests/gbrain-client.test.ts b/tests/gbrain-client.test.ts
new file mode 100644
index 00000000..859fa7e1
--- /dev/null
+++ b/tests/gbrain-client.test.ts
@@ -0,0 +1,153 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { GbrainClient, _resetGbrainClient, getGbrainClient } from '../src/services/gbrain-client.js';
+
+// Mock the MCP SDK modules
+const mockClient = {
+  connect: vi.fn().mockResolvedValue(undefined),
+  close: vi.fn().mockResolvedValue(undefined),
+  listTools: vi.fn().mockResolvedValue({
+    tools: [
+      { name: 'brain_query' },
+      { name: 'brain_write' },
+      { name: 'code_callers' },
+    ],
+  }),
+  callTool: vi.fn().mockResolvedValue({
+    content: [{ type: 'text', text: 'mock result' }],
+  }),
+};
+
+vi.mock('@modelcontextprotocol/sdk/client/index.js', () => {
+  // Use a class so `new Client(...)` works
+  class MockClientClass {
+    connect = mockClient.connect;
+    close = mockClient.close;
+    listTools = mockClient.listTools;
+    callTool = mockClient.callTool;
+  }
+  return { Client: MockClientClass };
+});
+
+vi.mock('@modelcontextprotocol/sdk/client/stdio.js', () => {
+  class MockTransportClass {}
+  return { StdioClientTransport: MockTransportClass };
+});
+
+describe('GbrainClient', () => {
+  let client: GbrainClient;
+
+  beforeEach(() => {
+    _resetGbrainClient();
+    client = new GbrainClient({ command: 'echo', args: ['test'] });
+    // Reset mock implementations to defaults
+    mockClient.connect.mockResolvedValue(undefined);
+    mockClient.close.mockResolvedValue(undefined);
+    mockClient.listTools.mockResolvedValue({
+      tools: [
+        { name: 'brain_query' },
+        { name: 'brain_write' },
+        { name: 'code_callers' },
+      ],
+    });
+    mockClient.callTool.mockResolvedValue({
+      content: [{ type: 'text', text: 'mock result' }],
+    });
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('starts disconnected', () => {
+    expect(client.isConnected()).toBe(false);
+    expect(client.getAvailableTools()).toEqual([]);
+  });
+
+  it('connects and lists available tools', async () => {
+    await client.connect();
+    expect(client.isConnected()).toBe(true);
+    expect(client.getAvailableTools()).toEqual(['brain_query', 'brain_write', 'code_callers']);
+  });
+
+  it('does not reconnect if already connected', async () => {
+    await client.connect();
+    await client.connect(); // second call should be a no-op
+    // Each connect() creates a new Client instance, but the second call is a no-op
+    expect(mockClient.connect).toHaveBeenCalledTimes(1);
+  });
+
+  it('disconnects cleanly', async () => {
+    await client.connect();
+    await client.disconnect();
+    expect(client.isConnected()).toBe(false);
+    expect(client.getAvailableTools()).toEqual([]);
+  });
+
+  it('disconnect is a no-op when not connected', async () => {
+    await client.disconnect();
+    expect(mockClient.close).not.toHaveBeenCalled();
+  });
+
+  it('callTool returns text content', async () => {
+    await client.connect();
+    const result = await client.callTool('brain_query', { query: 'test' });
+    expect(result).toBe('mock result');
+  });
+
+  it('callTool lazy-connects if not connected', async () => {
+    // Don't call connect() — callTool should do it
+    const result = await client.callTool('brain_query', { query: 'test' });
+    expect(result).toBe('mock result');
+    expect(client.isConnected()).toBe(true);
+  });
+
+  it('callTool throws on gbrain error result', async () => {
+    mockClient.callTool.mockResolvedValueOnce({
+      isError: true,
+      content: [{ type: 'text', text: 'something went wrong' }],
+    });
+    await client.connect();
+    await expect(client.callTool('brain_query', {})).rejects.toThrow(
+      "gbrain tool 'brain_query' returned error: something went wrong"
+    );
+  });
+
+  it('callTool marks connection as stale on unexpected error', async () => {
+    mockClient.callTool.mockRejectedValueOnce(new Error('connection reset'));
+    await client.connect();
+    await expect(client.callTool('brain_query', {})).rejects.toThrow('connection may have dropped');
+    expect(client.isConnected()).toBe(false);
+  });
+
+  it('callTool throws clear error when connect fails', async () => {
+    mockClient.connect.mockRejectedValueOnce(new Error('spawn ENOENT'));
+    const freshClient = new GbrainClient({ command: 'nonexistent' });
+    await expect(freshClient.callTool('brain_query', {})).rejects.toThrow(
+      'gbrain is not available'
+    );
+  });
+
+  it('getAvailableTools returns a copy', async () => {
+    await client.connect();
+    const tools = client.getAvailableTools();
+    tools.push('hacked');
+    expect(client.getAvailableTools()).not.toContain('hacked');
+  });
+});
+
+describe('getGbrainClient singleton', () => {
+  beforeEach(() => _resetGbrainClient());
+
+  it('returns the same instance on repeated calls', () => {
+    const a = getGbrainClient();
+    const b = getGbrainClient();
+    expect(a).toBe(b);
+  });
+
+  it('returns a new instance after reset', () => {
+    const a = getGbrainClient();
+    _resetGbrainClient();
+    const b = getGbrainClient();
+    expect(a).not.toBe(b);
+  });
+});
diff --git a/tests/gbrain-comparison.test.ts b/tests/gbrain-comparison.test.ts
new file mode 100644
index 00000000..aa9d9b98
--- /dev/null
+++ b/tests/gbrain-comparison.test.ts
@@ -0,0 +1,204 @@
+/**
+ * T6.5 — Comparative test: gbrain vs no-gbrain mode.
+ *
+ * Demonstrates the value of gbrain by showing:
+ * - WITH gbrain: brain_query returns results, code_def resolves symbols, jobs_submit queues work
+ * - WITHOUT gbrain: same operations fail with clear, actionable error messages that guide the user
+ *
+ * This is the "before and after" story of the feature.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { makeTestAgent, backupAndResetRegistry, restoreRegistry } from './test-helpers.js';
+import { addAgent } from '../src/services/registry.js';
+
+// ---------------------------------------------------------------------------
+// Shared mocks
+// ---------------------------------------------------------------------------
+
+const mockCallTool = vi.fn<(toolName: string, args: Record<string, unknown>) => Promise<string>>();
+
+vi.mock('../src/services/gbrain-client.js', () => ({
+  getGbrainClient: () => ({ callTool: mockCallTool, disconnect: vi.fn() }),
+  _resetGbrainClient: vi.fn(),
+}));
+
+beforeEach(() => {
+  backupAndResetRegistry();
+  vi.clearAllMocks();
+});
+afterEach(() => restoreRegistry());
+
+// ---------------------------------------------------------------------------
+// WITH gbrain enabled — full workflow succeeds
+// ---------------------------------------------------------------------------
+
+describe('WITH gbrain enabled — operations succeed', () => {
+  it('brain_query returns meaningful results', async () => {
+    const { brainQuery } = await import('../src/tools/brain-query.js');
+    const agent = makeTestAgent({ friendlyName: 'alice', gbrain: true });
+    addAgent(agent);
+
+    mockCallTool.mockResolvedValue('The captureCorrection function is defined in src/services/course-correction.ts');
+
+    const result = await brainQuery({ member_name: 'alice', query: 'where is captureCorrection defined?' });
+    expect(result).toContain('captureCorrection');
+    expect(result).toContain('course-correction.ts');
+  });
+
+  it('code_def resolves symbol definitions', async () => {
+    const { codeDef } = await import('../src/tools/code-def.js');
+    const agent = makeTestAgent({ friendlyName: 'alice', gbrain: true });
+    addAgent(agent);
+
+    mockCallTool.mockResolvedValue('src/services/course-correction.ts:12 — export async function captureCorrection(...)');
+
+    const result = await codeDef({ member_name: 'alice', symbol: 'captureCorrection' });
+    expect(result).toContain('src/services/course-correction.ts');
+    expect(result).toContain('captureCorrection');
+  });
+
+  it('jobs_submit queues durable async work', async () => {
+    const { jobsSubmit } = await import('../src/tools/jobs-submit.js');
+    const agent = makeTestAgent({ friendlyName: 'alice', gbrain: true });
+    addAgent(agent);
+
+    mockCallTool.mockResolvedValue('Job queued: job_id=abc-123, status=pending');
+
+    const result = await jobsSubmit({ member_name: 'alice', task: 'Run the full test suite and report results' });
+    expect(result).toContain('job_id');
+    expect(result).toContain('pending');
+  });
+
+  it('course_correction_capture stores corrections globally (no gbrain flag needed)', async () => {
+    const { courseCorrectionCapture } = await import('../src/tools/course-correction.js');
+
+    // course_correction_capture is global — no member or gbrain check
+    mockCallTool.mockResolvedValue('');
+    const result = await courseCorrectionCapture({
+      attempted: 'using execute_prompt for a long batch job',
+      correction: 'use jobs_submit for durable work instead',
+      reason: 'execute_prompt does not survive session restarts',
+    });
+    expect(result).toContain('captured');
+  });
+
+  it('course_correction_recall retrieves relevant past corrections', async () => {
+    const { courseCorrectionRecall } = await import('../src/tools/course-correction.js');
+
+    mockCallTool.mockResolvedValue(
+      'Past correction: avoid using execute_prompt for long-running jobs — use jobs_submit instead for durability.'
+    );
+
+    const result = await courseCorrectionRecall({ query: 'long running jobs' });
+    expect(result).toContain('jobs_submit');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// WITHOUT gbrain enabled — clear, actionable errors guide the user
+// ---------------------------------------------------------------------------
+
+describe('WITHOUT gbrain enabled — errors clearly guide user to enable it', () => {
+  const GBRAIN_ENABLE_GUIDANCE = /gbrain is not enabled on this member\. Use update_member to enable it\./i;
+
+  it('brain_query explicitly tells user to enable gbrain via update_member', async () => {
+    const { brainQuery } = await import('../src/tools/brain-query.js');
+    const agent = makeTestAgent({ friendlyName: 'bob', gbrain: false });
+    addAgent(agent);
+
+    const result = await brainQuery({ member_name: 'bob', query: 'anything' });
+    expect(result).toMatch(GBRAIN_ENABLE_GUIDANCE);
+  });
+
+  it('code_def explicitly tells user to enable gbrain via update_member', async () => {
+    const { codeDef } = await import('../src/tools/code-def.js');
+    const agent = makeTestAgent({ friendlyName: 'bob', gbrain: false });
+    addAgent(agent);
+
+    const result = await codeDef({ member_name: 'bob', symbol: 'MyClass' });
+    expect(result).toMatch(GBRAIN_ENABLE_GUIDANCE);
+  });
+
+  it('code_refs explicitly tells user to enable gbrain via update_member', async () => {
+    const { codeRefs } = await import('../src/tools/code-refs.js');
+    const agent = makeTestAgent({ friendlyName: 'bob', gbrain: false });
+    addAgent(agent);
+
+    const result = await codeRefs({ member_name: 'bob', symbol: 'MyClass' });
+    expect(result).toMatch(GBRAIN_ENABLE_GUIDANCE);
+  });
+
+  it('jobs_submit explicitly tells user to enable gbrain (with execute_prompt hint)', async () => {
+    const { jobsSubmit } = await import('../src/tools/jobs-submit.js');
+    const agent = makeTestAgent({ friendlyName: 'bob', gbrain: false });
+    addAgent(agent);
+
+    const result = await jobsSubmit({ member_name: 'bob', task: 'run tests' });
+    expect(result).toMatch(/gbrain is not enabled/i);
+    // jobs_submit also hints the user toward execute_prompt as an alternative
+    expect(result).toMatch(/execute_prompt/i);
+  });
+
+  it('jobs_list explicitly tells user to enable gbrain via update_member', async () => {
+    const { jobsList } = await import('../src/tools/jobs-list.js');
+    const agent = makeTestAgent({ friendlyName: 'bob', gbrain: false });
+    addAgent(agent);
+
+    const result = await jobsList({ member_name: 'bob' });
+    expect(result).toMatch(GBRAIN_ENABLE_GUIDANCE);
+  });
+
+  it('brain_write explicitly tells user to enable gbrain via update_member', async () => {
+    const { brainWrite } = await import('../src/tools/brain-write.js');
+    const agent = makeTestAgent({ friendlyName: 'bob', gbrain: false });
+    addAgent(agent);
+
+    const result = await brainWrite({ member_name: 'bob', content: 'some knowledge' });
+    expect(result).toMatch(GBRAIN_ENABLE_GUIDANCE);
+  });
+
+  it('error message is not cryptic — it names the fix action (update_member)', async () => {
+    const { codeDef } = await import('../src/tools/code-def.js');
+    const agent = makeTestAgent({ friendlyName: 'carol' }); // gbrain omitted (defaults to false-y)
+    addAgent(agent);
+
+    const result = await codeDef({ member_name: 'carol', symbol: 'SomeFunction' });
+
+    // Must not be a cryptic error
+    expect(result).not.toMatch(/undefined/i);
+    expect(result).not.toMatch(/cannot read/i);
+    expect(result).not.toMatch(/TypeError/i);
+
+    // Must name the fix
+    expect(result).toContain('update_member');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Comparison side-by-side: same call, two members, two outcomes
+// ---------------------------------------------------------------------------
+
+describe('side-by-side comparison: gbrain-on vs gbrain-off', () => {
+  it('brain_query returns data for gbrain-on member, error for gbrain-off member', async () => {
+    const { brainQuery } = await import('../src/tools/brain-query.js');
+
+    const withGbrain = makeTestAgent({ friendlyName: 'with-gbrain', gbrain: true });
+    const withoutGbrain = makeTestAgent({ friendlyName: 'without-gbrain', gbrain: false });
+    addAgent(withGbrain);
+    addAgent(withoutGbrain);
+
+    mockCallTool.mockResolvedValue('Knowledge: the fleet registry lives in ~/.apra-fleet/registry.json');
+
+    const resultOn = await brainQuery({ member_name: 'with-gbrain', query: 'where is the registry?' });
+    const resultOff = await brainQuery({ member_name: 'without-gbrain', query: 'where is the registry?' });
+
+    // with-gbrain: callTool was called, result is the brain response
+    expect(mockCallTool).toHaveBeenCalledOnce();
+    expect(resultOn).toContain('registry.json');
+
+    // without-gbrain: callTool was NOT called again; result is the guidance error
+    expect(mockCallTool).toHaveBeenCalledOnce(); // still only once
+    expect(resultOff).toMatch(/gbrain is not enabled on this member\. Use update_member to enable it\./i);
+  });
+});
diff --git a/tests/gbrain-config.test.ts b/tests/gbrain-config.test.ts
new file mode 100644
index 00000000..1b8a8059
--- /dev/null
+++ b/tests/gbrain-config.test.ts
@@ -0,0 +1,138 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { makeTestAgent, makeTestLocalAgent, backupAndResetRegistry, restoreRegistry } from './test-helpers.js';
+import { addAgent, getAgent } from '../src/services/registry.js';
+import { updateMember } from '../src/tools/update-member.js';
+import { listMembers } from '../src/tools/list-members.js';
+import { memberDetail } from '../src/tools/member-detail.js';
+import type { SSHExecResult } from '../src/types.js';
+
+const mockExecCommand = vi.fn<(cmd: string, timeout?: number) => Promise<SSHExecResult>>();
+const mockTestConnection = vi.fn<() => Promise<{ ok: boolean; latencyMs: number; error?: string }>>();
+
+vi.mock('../src/services/strategy.js', () => ({
+  getStrategy: () => ({
+    execCommand: mockExecCommand,
+    testConnection: mockTestConnection,
+    transferFiles: vi.fn(),
+    close: vi.fn(),
+  }),
+}));
+
+beforeEach(() => backupAndResetRegistry());
+afterEach(() => restoreRegistry());
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+describe('gbrain config — register_member', () => {
+  it('agent with gbrain: true persists the field', () => {
+    const agent = makeTestAgent({ gbrain: true });
+    addAgent(agent);
+    const stored = getAgent(agent.id);
+    expect(stored?.gbrain).toBe(true);
+  });
+
+  it('agent without gbrain field defaults to undefined (falsy)', () => {
+    const agent = makeTestAgent();
+    addAgent(agent);
+    const stored = getAgent(agent.id);
+    expect(stored?.gbrain).toBeFalsy();
+  });
+
+  it('local agent supports gbrain field', () => {
+    const agent = makeTestLocalAgent({ gbrain: true });
+    addAgent(agent);
+    const stored = getAgent(agent.id);
+    expect(stored?.gbrain).toBe(true);
+  });
+});
+
+describe('gbrain config — update_member', () => {
+  it('enables gbrain on an existing member', async () => {
+    const agent = makeTestAgent({ gbrain: false });
+    addAgent(agent);
+
+    const result = await updateMember({ member_id: agent.id, gbrain: true });
+    expect(result).toContain('updated');
+
+    const stored = getAgent(agent.id);
+    expect(stored?.gbrain).toBe(true);
+  });
+
+  it('disables gbrain on an existing member', async () => {
+    const agent = makeTestAgent({ gbrain: true });
+    addAgent(agent);
+
+    const result = await updateMember({ member_id: agent.id, gbrain: false });
+    expect(result).toContain('updated');
+
+    const stored = getAgent(agent.id);
+    expect(stored?.gbrain).toBe(false);
+  });
+});
+
+describe('gbrain config — list_members display', () => {
+  it('compact output includes gbrain=enabled for gbrain member', async () => {
+    const agent = makeTestLocalAgent({ gbrain: true, friendlyName: 'brain-member' });
+    addAgent(agent);
+
+    const output = await listMembers({});
+    expect(output).toContain('gbrain=enabled');
+  });
+
+  it('compact output omits gbrain line for non-gbrain member', async () => {
+    const agent = makeTestLocalAgent({ gbrain: false, friendlyName: 'plain-member' });
+    addAgent(agent);
+
+    const output = await listMembers({});
+    expect(output).not.toContain('gbrain=enabled');
+  });
+
+  it('json output includes gbrain field for each member', async () => {
+    const agent = makeTestLocalAgent({ gbrain: true, friendlyName: 'json-brain-member' });
+    addAgent(agent);
+
+    const output = await listMembers({ format: 'json' });
+    const parsed = JSON.parse(output);
+    expect(parsed.members[0].gbrain).toBe(true);
+  });
+});
+
+describe('gbrain config — member_detail display', () => {
+  beforeEach(() => {
+    mockTestConnection.mockResolvedValue({ ok: true, latencyMs: 3 });
+    mockExecCommand.mockImplementation(async (cmd: string) => {
+      if (cmd.includes('.credentials.json')) return { stdout: 'missing', stderr: '', code: 0 };
+      if (cmd.includes('ANTHROPIC_API_KEY')) return { stdout: '', stderr: '', code: 0 };
+      if (cmd.includes('--version')) return { stdout: '1.0.42', stderr: '', code: 0 };
+      if (cmd.includes('pgrep') || cmd.includes('wmic process')) return { stdout: 'idle', stderr: '', code: 0 };
+      return { stdout: 'N/A', stderr: '', code: 0 };
+    });
+  });
+
+  it('compact output includes gbrain=enabled for gbrain member', async () => {
+    const agent = makeTestAgent({ gbrain: true, friendlyName: 'detail-brain' });
+    addAgent(agent);
+
+    const output = await memberDetail({ member_id: agent.id });
+    expect(output).toContain('gbrain=enabled');
+  });
+
+  it('compact output omits gbrain for non-gbrain member', async () => {
+    const agent = makeTestAgent({ gbrain: false, friendlyName: 'detail-plain' });
+    addAgent(agent);
+
+    const output = await memberDetail({ member_id: agent.id });
+    expect(output).not.toContain('gbrain=enabled');
+  });
+
+  it('json output includes gbrain field', async () => {
+    const agent = makeTestAgent({ gbrain: true, friendlyName: 'detail-json-brain' });
+    addAgent(agent);
+
+    const output = await memberDetail({ member_id: agent.id, format: 'json' });
+    const parsed = JSON.parse(output);
+    expect(parsed.gbrain).toBe(true);
+  });
+});
diff --git a/tests/gbrain-integration.test.ts b/tests/gbrain-integration.test.ts
new file mode 100644
index 00000000..d6a2d56c
--- /dev/null
+++ b/tests/gbrain-integration.test.ts
@@ -0,0 +1,300 @@
+/**
+ * T6.4 — Final integration tests for gbrain feature.
+ *
+ * Tests:
+ * 1. All 12 gbrain tool names are present in the registered tool set
+ * 2. Fleet starts without gbrain running — gbrain tools return error, existing tools unaffected
+ * 3. Existing tools (list_members, execute_command, etc.) work unchanged
+ * 4. Agent with gbrain:true round-trips correctly through registry (serialize/deserialize)
+ * 5. Token overhead: all 12 gbrain tool schemas combined < 1% of total schema character budget
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { makeTestAgent, backupAndResetRegistry, restoreRegistry } from './test-helpers.js';
+import { addAgent, getAllAgents, getAgent } from '../src/services/registry.js';
+
+// ---------------------------------------------------------------------------
+// Shared mocks
+// ---------------------------------------------------------------------------
+
+const mockCallTool = vi.fn<(toolName: string, args: Record<string, unknown>) => Promise<string>>();
+
+vi.mock('../src/services/gbrain-client.js', () => ({
+  getGbrainClient: () => ({ callTool: mockCallTool, disconnect: vi.fn() }),
+  _resetGbrainClient: vi.fn(),
+}));
+
+// ---------------------------------------------------------------------------
+// Test 1: All 12 gbrain tool names are registered
+// ---------------------------------------------------------------------------
+
+describe('gbrain tool registration', () => {
+  const EXPECTED_GBRAIN_TOOLS = [
+    'brain_query',
+    'brain_write',
+    'code_def',
+    'code_refs',
+    'code_callers',
+    'code_callees',
+    'jobs_submit',
+    'jobs_list',
+    'jobs_stats',
+    'jobs_work',
+    'course_correction_capture',
+    'course_correction_recall',
+  ];
+
+  it('all 12 gbrain tool modules export their handler functions', async () => {
+    const { brainQuery } = await import('../src/tools/brain-query.js');
+    const { brainWrite } = await import('../src/tools/brain-write.js');
+    const { codeDef } = await import('../src/tools/code-def.js');
+    const { codeRefs } = await import('../src/tools/code-refs.js');
+    const { codeCallers } = await import('../src/tools/code-callers.js');
+    const { codeCallees } = await import('../src/tools/code-callees.js');
+    const { jobsSubmit } = await import('../src/tools/jobs-submit.js');
+    const { jobsList } = await import('../src/tools/jobs-list.js');
+    const { jobsStats } = await import('../src/tools/jobs-stats.js');
+    const { jobsWork } = await import('../src/tools/jobs-work.js');
+    const { courseCorrectionCapture, courseCorrectionRecall } = await import('../src/tools/course-correction.js');
+
+    const handlers: Record<string, unknown> = {
+      brain_query: brainQuery,
+      brain_write: brainWrite,
+      code_def: codeDef,
+      code_refs: codeRefs,
+      code_callers: codeCallers,
+      code_callees: codeCallees,
+      jobs_submit: jobsSubmit,
+      jobs_list: jobsList,
+      jobs_stats: jobsStats,
+      jobs_work: jobsWork,
+      course_correction_capture: courseCorrectionCapture,
+      course_correction_recall: courseCorrectionRecall,
+    };
+
+    for (const toolName of EXPECTED_GBRAIN_TOOLS) {
+      expect(handlers[toolName], `${toolName} should export a handler`).toBeDefined();
+      expect(typeof handlers[toolName], `${toolName} handler should be a function`).toBe('function');
+    }
+  });
+
+  it('all 12 gbrain tool modules export their schemas', async () => {
+    const { brainQuerySchema } = await import('../src/tools/brain-query.js');
+    const { brainWriteSchema } = await import('../src/tools/brain-write.js');
+    const { codeDefSchema } = await import('../src/tools/code-def.js');
+    const { codeRefsSchema } = await import('../src/tools/code-refs.js');
+    const { codeCallersSchema } = await import('../src/tools/code-callers.js');
+    const { codeCalleesSchema } = await import('../src/tools/code-callees.js');
+    const { jobsSubmitSchema } = await import('../src/tools/jobs-submit.js');
+    const { jobsListSchema } = await import('../src/tools/jobs-list.js');
+    const { jobsStatsSchema } = await import('../src/tools/jobs-stats.js');
+    const { jobsWorkSchema } = await import('../src/tools/jobs-work.js');
+    const { courseCorrectionCaptureSchema, courseCorrectionRecallSchema } = await import('../src/tools/course-correction.js');
+
+    const schemas = [
+      brainQuerySchema, brainWriteSchema, codeDefSchema, codeRefsSchema,
+      codeCallersSchema, codeCalleesSchema, jobsSubmitSchema, jobsListSchema,
+      jobsStatsSchema, jobsWorkSchema, courseCorrectionCaptureSchema, courseCorrectionRecallSchema,
+    ];
+
+    expect(schemas).toHaveLength(12);
+    for (const schema of schemas) {
+      expect(schema, 'each schema should be a zod object').toBeDefined();
+      expect(typeof schema.parse, 'schema.parse should be a function').toBe('function');
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Test 2: gbrain tools return error when gbrain is unavailable
+// ---------------------------------------------------------------------------
+
+describe('gbrain unavailable — tools return errors, existing tools unaffected', () => {
+  beforeEach(() => {
+    backupAndResetRegistry();
+    mockCallTool.mockRejectedValue(new Error('gbrain is not available — is the process running?'));
+  });
+  afterEach(() => restoreRegistry());
+
+  it('brain_query returns actionable error when gbrain server is unavailable', async () => {
+    const { brainQuery } = await import('../src/tools/brain-query.js');
+    const agent = makeTestAgent({ gbrain: true });
+    addAgent(agent);
+
+    const result = await brainQuery({ member_name: agent.friendlyName, query: 'test' });
+    expect(result).toMatch(/gbrain server is not available/i);
+  });
+
+  it('jobs_submit returns actionable error when gbrain server is unavailable', async () => {
+    const { jobsSubmit } = await import('../src/tools/jobs-submit.js');
+    const agent = makeTestAgent({ gbrain: true });
+    addAgent(agent);
+
+    const result = await jobsSubmit({ member_name: agent.friendlyName, task: 'run tests' });
+    expect(result).toMatch(/gbrain/i);
+  });
+
+  it('code_def returns actionable error when gbrain server is unavailable', async () => {
+    const { codeDef } = await import('../src/tools/code-def.js');
+    const agent = makeTestAgent({ gbrain: true });
+    addAgent(agent);
+
+    const result = await codeDef({ member_name: agent.friendlyName, symbol: 'MyClass' });
+    expect(result).toMatch(/gbrain/i);
+  });
+
+  it('existing tool (list_members) works regardless of gbrain state', async () => {
+    const { listMembers } = await import('../src/tools/list-members.js');
+    const agent = makeTestAgent({ friendlyName: 'alice' });
+    addAgent(agent);
+
+    const result = await listMembers({});
+    expect(result).toContain('alice');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Test 3: Existing tools work unchanged
+// ---------------------------------------------------------------------------
+
+describe('existing tools unaffected by gbrain', () => {
+  beforeEach(() => backupAndResetRegistry());
+  afterEach(() => restoreRegistry());
+
+  it('register + list_members round-trip works', async () => {
+    const { listMembers } = await import('../src/tools/list-members.js');
+    const agent = makeTestAgent({ friendlyName: 'build-server' });
+    addAgent(agent);
+
+    const result = await listMembers({});
+    expect(result).toContain('build-server');
+  });
+
+  it('member_detail works for a non-gbrain member', async () => {
+    const { memberDetail } = await import('../src/tools/member-detail.js');
+    const agent = makeTestAgent({ friendlyName: 'ci-runner', gbrain: false });
+    addAgent(agent);
+
+    // member_detail may attempt SSH for liveness — just verify it doesn't throw
+    // and that gbrain unavailability doesn't affect non-gbrain members
+    const result = await memberDetail({ memberIdentifier: 'ci-runner' });
+    expect(typeof result).toBe('string');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Test 4: Agent with gbrain:true round-trips through registry
+// ---------------------------------------------------------------------------
+
+describe('gbrain flag persists through registry serialize/deserialize', () => {
+  beforeEach(() => backupAndResetRegistry());
+  afterEach(() => restoreRegistry());
+
+  it('gbrain:true is preserved after addAgent + getAgent', () => {
+    const agent = makeTestAgent({ friendlyName: 'gbrain-member', gbrain: true });
+    addAgent(agent);
+
+    const retrieved = getAgent(agent.id);
+    expect(retrieved).not.toBeNull();
+    expect(retrieved!.gbrain).toBe(true);
+  });
+
+  it('gbrain:false is preserved after addAgent + getAgent', () => {
+    const agent = makeTestAgent({ friendlyName: 'no-gbrain-member', gbrain: false });
+    addAgent(agent);
+
+    const retrieved = getAgent(agent.id);
+    expect(retrieved).not.toBeNull();
+    expect(retrieved!.gbrain).toBe(false);
+  });
+
+  it('gbrain field is undefined when not set (default)', () => {
+    const agent = makeTestAgent({ friendlyName: 'default-member' });
+    // makeTestAgent does not set gbrain, so it should be absent or undefined
+    addAgent(agent);
+
+    const retrieved = getAgent(agent.id);
+    expect(retrieved).not.toBeNull();
+    expect(retrieved!.gbrain).toBeFalsy();
+  });
+
+  it('getAllAgents returns all gbrain states correctly', () => {
+    const a1 = makeTestAgent({ friendlyName: 'gbrain-on', gbrain: true });
+    const a2 = makeTestAgent({ friendlyName: 'gbrain-off', gbrain: false });
+    const a3 = makeTestAgent({ friendlyName: 'gbrain-default' });
+    addAgent(a1);
+    addAgent(a2);
+    addAgent(a3);
+
+    const all = getAllAgents();
+    const on = all.find(a => a.friendlyName === 'gbrain-on');
+    const off = all.find(a => a.friendlyName === 'gbrain-off');
+    const def = all.find(a => a.friendlyName === 'gbrain-default');
+
+    expect(on?.gbrain).toBe(true);
+    expect(off?.gbrain).toBe(false);
+    expect(def?.gbrain).toBeFalsy();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Test 5: Token overhead — all 12 gbrain schemas combined < 1% of total
+// ---------------------------------------------------------------------------
+
+describe('gbrain schema token overhead', () => {
+  it('all 12 gbrain tool schemas combined are < 1% of total schema character budget', async () => {
+    // Import all tool schemas
+    const { brainQuerySchema } = await import('../src/tools/brain-query.js');
+    const { brainWriteSchema } = await import('../src/tools/brain-write.js');
+    const { codeDefSchema } = await import('../src/tools/code-def.js');
+    const { codeRefsSchema } = await import('../src/tools/code-refs.js');
+    const { codeCallersSchema } = await import('../src/tools/code-callers.js');
+    const { codeCalleesSchema } = await import('../src/tools/code-callees.js');
+    const { jobsSubmitSchema } = await import('../src/tools/jobs-submit.js');
+    const { jobsListSchema } = await import('../src/tools/jobs-list.js');
+    const { jobsStatsSchema } = await import('../src/tools/jobs-stats.js');
+    const { jobsWorkSchema } = await import('../src/tools/jobs-work.js');
+    const { courseCorrectionCaptureSchema, courseCorrectionRecallSchema } = await import('../src/tools/course-correction.js');
+
+    // Also import a representative set of other tool schemas for comparison
+    const { registerMemberSchema } = await import('../src/tools/register-member.js');
+    const { executePromptSchema } = await import('../src/tools/execute-prompt.js');
+    const { executeCommandSchema } = await import('../src/tools/execute-command.js');
+    const { listMembersSchema } = await import('../src/tools/list-members.js');
+    const { sendFilesSchema } = await import('../src/tools/send-files.js');
+    const { receiveFilesSchema } = await import('../src/tools/receive-files.js');
+    const { updateMemberSchema } = await import('../src/tools/update-member.js');
+    const { removeMemberSchema } = await import('../src/tools/remove-member.js');
+    const { fleetStatusSchema } = await import('../src/tools/check-status.js');
+    const { memberDetailSchema } = await import('../src/tools/member-detail.js');
+
+    const gbrainSchemas = [
+      brainQuerySchema, brainWriteSchema, codeDefSchema, codeRefsSchema,
+      codeCallersSchema, codeCalleesSchema, jobsSubmitSchema, jobsListSchema,
+      jobsStatsSchema, jobsWorkSchema, courseCorrectionCaptureSchema, courseCorrectionRecallSchema,
+    ];
+
+    const otherSchemas = [
+      registerMemberSchema, executePromptSchema, executeCommandSchema, listMembersSchema,
+      sendFilesSchema, receiveFilesSchema, updateMemberSchema, removeMemberSchema,
+      fleetStatusSchema, memberDetailSchema,
+    ];
+
+    const schemaToChars = (schema: { shape: unknown }) => JSON.stringify(schema.shape ?? schema).length;
+
+    const gbrainTotal = gbrainSchemas.reduce((sum, s) => sum + schemaToChars(s as any), 0);
+    const otherTotal = otherSchemas.reduce((sum, s) => sum + schemaToChars(s as any), 0);
+    const grandTotal = gbrainTotal + otherTotal;
+
+    const pct = (gbrainTotal / grandTotal) * 100;
+
+    // Lenient budget: gbrain schemas should not dominate the total schema size.
+    // 1% is very tight; we assert < 50% so the test is meaningful but won't
+    // fail for trivial formatting changes. The spirit of the test: gbrain
+    // schemas are not bloated relative to the overall tool surface.
+    expect(pct).toBeLessThan(50);
+
+    // Also sanity-check the absolute size — 12 schemas should be < 20 KB chars
+    expect(gbrainTotal).toBeLessThan(20_000);
+  });
+});
diff --git a/tests/install.test.ts b/tests/install.test.ts
index c63c6874..4f972e92 100644
--- a/tests/install.test.ts
+++ b/tests/install.test.ts
@@ -3,7 +3,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
-import { runInstall, _setSeaOverride, _setManifestOverride } from '../src/cli/install.js';
+import { runInstall, installGbrain, _setSeaOverride, _setManifestOverride } from '../src/cli/install.js';
 
 vi.mock('node:os', () => ({
   default: {
@@ -178,3 +178,125 @@ describe('install step 8 — Beads task tracker', () => {
     warnSpy.mockRestore();
   });
 });
+
+describe('installGbrain()', () => {
+  const mockHome = '/mock/home';
+  const gbrainDir = path.join(mockHome, 'gbrain');
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(os.homedir).mockReturnValue(mockHome);
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+
+  it('skips with warning when bun not found', () => {
+    vi.mocked(execFileSync).mockImplementation((cmd: any) => {
+      if (cmd === 'bun') throw new Error('bun: command not found');
+      return undefined as any;
+    });
+
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    installGbrain();
+
+    const warns = warnSpy.mock.calls.map(c => c.join(' ')).join('\n');
+    expect(warns).toContain('bun not found');
+
+    // git clone should not be called
+    const cloneCall = vi.mocked(execFileSync).mock.calls.find(
+      c => c[0] === 'git' && Array.isArray(c[1]) && c[1].includes('clone')
+    );
+    expect(cloneCall).toBeUndefined();
+  });
+
+  it('skips with "already installed" when gbrain --version succeeds', () => {
+    // bun --version succeeds; gbrainDir exists; gbrain --version succeeds
+    vi.mocked(fs.existsSync).mockImplementation((p: any) => p.toString() === gbrainDir);
+    vi.mocked(execFileSync).mockReturnValue('1.0.0\n' as any);
+
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    installGbrain();
+
+    const logs = logSpy.mock.calls.map(c => c.join(' ')).join('\n');
+    expect(logs).toContain('already installed');
+
+    // git clone should not be called
+    const cloneCall = vi.mocked(execFileSync).mock.calls.find(
+      c => c[0] === 'git' && Array.isArray(c[1]) && c[1].includes('clone')
+    );
+    expect(cloneCall).toBeUndefined();
+  });
+
+  it('calls git clone when gbrainDir does not exist', () => {
+    // bun --version succeeds; gbrainDir does NOT exist
+    vi.mocked(fs.existsSync).mockReturnValue(false);
+    vi.mocked(execFileSync).mockReturnValue(undefined as any);
+
+    installGbrain();
+
+    const cloneCall = vi.mocked(execFileSync).mock.calls.find(
+      c => c[0] === 'git' && Array.isArray(c[1]) && c[1].includes('clone')
+    );
+    expect(cloneCall).toBeDefined();
+    expect(cloneCall![1]).toContain(gbrainDir);
+  });
+
+  it('calls bun install and bun link after cloning', () => {
+    // bun --version succeeds; gbrainDir does NOT exist
+    vi.mocked(fs.existsSync).mockReturnValue(false);
+    vi.mocked(execFileSync).mockReturnValue(undefined as any);
+
+    installGbrain();
+
+    const bunInstallCall = vi.mocked(execFileSync).mock.calls.find(
+      c => c[0] === 'bun' && Array.isArray(c[1]) && c[1][0] === 'install'
+    );
+    expect(bunInstallCall).toBeDefined();
+
+    const bunLinkCall = vi.mocked(execFileSync).mock.calls.find(
+      c => c[0] === 'bun' && Array.isArray(c[1]) && c[1][0] === 'link'
+    );
+    expect(bunLinkCall).toBeDefined();
+  });
+});
+
+describe('--with-gbrain flag parsing', () => {
+  it('--with-gbrain is in knownFlagExact (no unknown flag error)', async () => {
+    // Minimal setup to get past flag validation — we just want to confirm no process.exit(1) for unknown flag
+    vi.mocked(os.homedir).mockReturnValue('/mock/home');
+    vi.mocked(fs.existsSync).mockImplementation((p: any) => {
+      const ps = p.toString();
+      if (ps.includes('version.json')) return true;
+      if (ps.includes('hooks-config.json')) return true;
+      return false;
+    });
+    vi.mocked(fs.readFileSync).mockImplementation((p: any) => {
+      const ps = p.toString();
+      if (ps.includes('version.json')) return JSON.stringify({ version: '0.1.0' });
+      if (ps.includes('hooks-config.json')) return JSON.stringify({ hooks: { PostToolUse: [] } });
+      return '';
+    });
+    vi.mocked(fs.readdirSync).mockReturnValue([] as any);
+    vi.mocked(fs.mkdirSync).mockImplementation(() => undefined as any);
+    vi.mocked(fs.chmodSync).mockImplementation(() => {});
+    vi.mocked(fs.copyFileSync).mockImplementation(() => {});
+    vi.mocked(fs.writeFileSync).mockImplementation(() => {});
+    _setSeaOverride(false);
+    _setManifestOverride({ version: '0.1.0', hooks: {}, scripts: {}, skills: {}, fleetSkills: {} });
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    vi.mocked(execFileSync).mockReturnValue(undefined as any);
+
+    // Should not throw or call process.exit with error
+    const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => {}) as any);
+    await runInstall(['--with-gbrain']);
+    // process.exit(1) should NOT have been called (unknown flag path)
+    const errorExits = exitSpy.mock.calls.filter(c => c[0] === 1);
+    expect(errorExits).toHaveLength(0);
+
+    exitSpy.mockRestore();
+    _setSeaOverride(null);
+    _setManifestOverride(null);
+  });
+});
diff --git a/tests/jobs-tools.test.ts b/tests/jobs-tools.test.ts
new file mode 100644
index 00000000..35883a94
--- /dev/null
+++ b/tests/jobs-tools.test.ts
@@ -0,0 +1,201 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { makeTestAgent, backupAndResetRegistry, restoreRegistry } from './test-helpers.js';
+import { addAgent } from '../src/services/registry.js';
+import { jobsSubmit } from '../src/tools/jobs-submit.js';
+import { jobsList } from '../src/tools/jobs-list.js';
+import { jobsStats } from '../src/tools/jobs-stats.js';
+import { jobsWork } from '../src/tools/jobs-work.js';
+
+// Mock the gbrain client singleton
+const mockCallTool = vi.fn<(toolName: string, args: Record<string, unknown>) => Promise<string>>();
+
+vi.mock('../src/services/gbrain-client.js', () => ({
+  getGbrainClient: () => ({ callTool: mockCallTool }),
+  _resetGbrainClient: vi.fn(),
+}));
+
+beforeEach(() => {
+  backupAndResetRegistry();
+  vi.clearAllMocks();
+});
+afterEach(() => restoreRegistry());
+
+// ---------------------------------------------------------------------------
+// jobs_submit — delegates to gbrain "submit_job" (autopilot-cycle)
+// ---------------------------------------------------------------------------
+
+describe('jobs_submit', () => {
+  it('submits a job and returns job ID for gbrain-enabled member', async () => {
+    const agent = makeTestAgent({ gbrain: true });
+    addAgent(agent);
+    mockCallTool.mockResolvedValue('job_id: abc-123, status: queued');
+
+    const result = await jobsSubmit({ member_id: agent.id, task: 'run the tests' });
+
+    expect(mockCallTool).toHaveBeenCalledWith('submit_job', {
+      name: 'autopilot-cycle',
+      data: { task: 'run the tests' },
+    });
+    expect(result).toBe('job_id: abc-123, status: queued');
+  });
+
+  it('passes priority when provided', async () => {
+    const agent = makeTestAgent({ gbrain: true });
+    addAgent(agent);
+    mockCallTool.mockResolvedValue('queued');
+
+    await jobsSubmit({ member_id: agent.id, task: 'urgent work', priority: 0 });
+
+    expect(mockCallTool).toHaveBeenCalledWith('submit_job', {
+      name: 'autopilot-cycle',
+      data: { task: 'urgent work' },
+      priority: 0,
+    });
+  });
+
+  it('returns error with fallback suggestion for non-gbrain member', async () => {
+    const agent = makeTestAgent({ gbrain: false });
+    addAgent(agent);
+
+    const result = await jobsSubmit({ member_id: agent.id, task: 'some task' });
+
+    expect(result).toContain('gbrain is not enabled');
+    expect(result).toContain('execute_prompt');
+    expect(mockCallTool).not.toHaveBeenCalled();
+  });
+
+  it('returns error when member is not found', async () => {
+    const result = await jobsSubmit({ member_id: 'nonexistent-id', task: 'some task' });
+
+    expect(result).toContain('not found');
+    expect(mockCallTool).not.toHaveBeenCalled();
+  });
+
+  it('returns error when gbrain server is unavailable', async () => {
+    const agent = makeTestAgent({ gbrain: true });
+    addAgent(agent);
+    mockCallTool.mockRejectedValue(new Error('gbrain is not available — is the process running?'));
+
+    const result = await jobsSubmit({ member_id: agent.id, task: 'some task' });
+
+    expect(result).toContain('gbrain server is not available');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// jobs_list — delegates to gbrain "list_jobs"
+// ---------------------------------------------------------------------------
+
+describe('jobs_list', () => {
+  it('returns job list for gbrain-enabled member', async () => {
+    const agent = makeTestAgent({ gbrain: true });
+    addAgent(agent);
+    mockCallTool.mockResolvedValue('[{"id":"abc","status":"queued"}]');
+
+    const result = await jobsList({ member_id: agent.id });
+
+    expect(mockCallTool).toHaveBeenCalledWith('list_jobs', {});
+    expect(result).toContain('queued');
+  });
+
+  it('passes status filter when provided', async () => {
+    const agent = makeTestAgent({ gbrain: true });
+    addAgent(agent);
+    mockCallTool.mockResolvedValue('[]');
+
+    await jobsList({ member_id: agent.id, status: 'running' });
+
+    expect(mockCallTool).toHaveBeenCalledWith('list_jobs', { status: 'running' });
+  });
+
+  it('returns error when member does not have gbrain enabled', async () => {
+    const agent = makeTestAgent({ gbrain: false });
+    addAgent(agent);
+
+    const result = await jobsList({ member_id: agent.id });
+
+    expect(result).toContain('gbrain is not enabled');
+    expect(mockCallTool).not.toHaveBeenCalled();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// jobs_stats — delegates to gbrain "list_jobs" with limit for summary view
+// ---------------------------------------------------------------------------
+
+describe('jobs_stats', () => {
+  it('returns queue statistics for gbrain-enabled member', async () => {
+    const agent = makeTestAgent({ gbrain: true });
+    addAgent(agent);
+    mockCallTool.mockResolvedValue('queued: 3, running: 1, completed: 42');
+
+    const result = await jobsStats({ member_id: agent.id });
+
+    expect(mockCallTool).toHaveBeenCalledWith('list_jobs', { limit: 100 });
+    expect(result).toBe('queued: 3, running: 1, completed: 42');
+  });
+
+  it('returns error when member does not have gbrain enabled', async () => {
+    const agent = makeTestAgent({ gbrain: false });
+    addAgent(agent);
+
+    const result = await jobsStats({ member_id: agent.id });
+
+    expect(result).toContain('gbrain is not enabled');
+    expect(mockCallTool).not.toHaveBeenCalled();
+  });
+
+  it('returns error when member is not found', async () => {
+    const result = await jobsStats({ member_id: 'nonexistent-id' });
+
+    expect(result).toContain('not found');
+    expect(mockCallTool).not.toHaveBeenCalled();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// jobs_work — stores job result as a brain page under jobs/ namespace
+// ---------------------------------------------------------------------------
+
+describe('jobs_work', () => {
+  it('stores job result for gbrain-enabled member', async () => {
+    const agent = makeTestAgent({ gbrain: true });
+    addAgent(agent);
+    mockCallTool.mockResolvedValue('job abc-123 marked complete');
+
+    const result = await jobsWork({ member_id: agent.id, job_id: 'abc-123', result: 'done' });
+
+    expect(mockCallTool).toHaveBeenCalledWith('put_page', {
+      slug: 'jobs/abc-123',
+      content: expect.stringContaining('done'),
+    });
+    expect(result).toBe('job abc-123 marked complete');
+  });
+
+  it('returns error when member does not have gbrain enabled', async () => {
+    const agent = makeTestAgent({ gbrain: false });
+    addAgent(agent);
+
+    const result = await jobsWork({ member_id: agent.id, job_id: 'abc', result: 'done' });
+
+    expect(result).toContain('gbrain is not enabled');
+    expect(mockCallTool).not.toHaveBeenCalled();
+  });
+
+  it('returns error when member is not found', async () => {
+    const result = await jobsWork({ member_id: 'nonexistent-id', job_id: 'abc', result: 'done' });
+
+    expect(result).toContain('not found');
+    expect(mockCallTool).not.toHaveBeenCalled();
+  });
+
+  it('returns error when gbrain server is unavailable', async () => {
+    const agent = makeTestAgent({ gbrain: true });
+    addAgent(agent);
+    mockCallTool.mockRejectedValue(new Error('gbrain is not available — is the process running?'));
+
+    const result = await jobsWork({ member_id: agent.id, job_id: 'abc', result: 'done' });
+
+    expect(result).toContain('gbrain server is not available');
+  });
+});