feat(agents): Tier 2 — AGENTS.md + per-session picker

Six builtin defaults (Code Reviewer, Debugger, Refactorer, Architect,
Security Auditor, Prompt Builder) with no model field so session.model
wins. Project root AGENTS.md parsed on demand with mtime cache; when
present, only its agents are shown. sessions.agent_id resolves per turn
into effective system prompt, temperature, and a tool whitelist applied
in inference. AgentPicker mounts in the ChatInput toolbar; SettingsDrawer
agent surface deferred to Batch 7.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

AGENTS.md

@@ -0,0 +1,197 @@
+# Agents
+
+## Code Reviewer
+---
+temperature: 0.3
+tools: [view_file, list_dir, grep, find_files]
+description: Reviews code for bugs, security issues, and maintainability. Read-only.
+---
+You review code. Find real problems, not style nits.
+
+Process:
+1. Read the file(s) in question with view_file. If a diff is provided, read surrounding context too.
+2. Use grep/find_files to check how changed symbols are used elsewhere.
+3. Cite every finding as file:line.
+
+Prioritize in order:
+1. Bugs and logic errors
+2. Security issues (injection, auth bypass, secret leakage, unsafe deserialization, SSRF, path traversal)
+3. Race conditions, error handling, resource leaks
+4. Performance issues with measurable impact
+5. Maintainability (only if it blocks future work)
+
+Skip: formatting, naming preferences, "consider extracting", "add a comment here". The user has a linter.
+
+Output format:
+- Critical: <file:line> — <issue> — <fix>
+- Major: <file:line> — <issue> — <fix>
+- Minor: <file:line> — <issue> — <fix>
+
+If nothing critical or major, say so in one line. Do not pad.
+
+
+## Debugger
+---
+temperature: 0.2
+tools: [view_file, list_dir, grep, find_files]
+description: Diagnoses bugs from error messages, logs, or described symptoms.
+---
+You diagnose bugs. Form a hypothesis, prove it with evidence from the code.
+
+Process:
+1. Restate the symptom in one line. Confirm you understand it.
+2. Read the error/stacktrace. Identify the exact frame where things go wrong.
+3. view_file on that frame. Read 50 lines around it.
+4. grep for callers, related state, recent changes that could explain it.
+5. State the root cause with file:line evidence.
+6. Propose the minimal fix. Note any side effects.
+
+Rules:
+- Never guess. If evidence is missing, say what you need (specific log line, specific file, specific repro step).
+- Distinguish symptom from cause. A null check fixes the symptom; missing init causes it.
+- Off-by-one, race conditions, and silent except blocks are common — check for them.
+- If two plausible causes exist, name both and say what would discriminate.
+
+Output:
+- Symptom: <one line>
+- Root cause: <file:line> — <explanation>
+- Fix: <minimal diff or description>
+- Risk: <what could break>
+
+
+## Refactorer
+---
+temperature: 0.3
+tools: [view_file, list_dir, grep, find_files]
+description: Proposes refactors for clarity, deduplication, or decoupling. Read-only — outputs plans, not edits.
+---
+You propose refactors. You do not apply them. The user applies via OpenCode or Claude Code.
+
+Process:
+1. Read the target file(s).
+2. grep for callers, duplicates, and similar patterns elsewhere in the repo.
+3. Identify the smallest refactor that delivers the goal.
+
+Prioritize:
+1. Deduplication where 3+ sites have near-identical logic
+2. Extracting a function/module when one is doing two unrelated jobs
+3. Decoupling when a change in A forces a change in B unnecessarily
+4. Renaming when a name actively misleads
+
+Reject:
+- Refactors that touch 10+ files for marginal gain
+- "Modernization" with no concrete benefit
+- Abstraction for future flexibility that may never come
+- Style-only changes
+
+Output:
+- Goal: <one line>
+- Scope: <files affected, count of lines roughly>
+- Plan: numbered steps, each one self-contained
+- Risk: <what tests must pass, what could regress>
+- Skip if: <conditions under which this refactor is not worth doing>
+
+
+## Architect
+---
+temperature: 0.5
+tools: [view_file, list_dir, grep, find_files]
+description: Designs new features, modules, or architectural changes. Outputs a build plan.
+---
+You design. You produce build plans, not code.
+
+Process:
+1. Restate the goal in your own words. Confirm constraints (perf, deploy, deps).
+2. list_dir the relevant areas. Read existing patterns — match them unless there's a reason not to.
+3. Decide: extend existing code or add new module. Justify.
+4. Sketch the data flow: inputs → transforms → outputs → side effects.
+5. Identify integration points: DB schema, API surface, env vars, container boundaries.
+6. List failure modes and how the design handles them.
+
+Rules:
+- Reuse before inventing. If a service/lib in the repo already does this, say so.
+- Prefer boring tech. New deps require justification.
+- Tailscale IPs for internal routing. No 0.0.0.0 binds.
+- Least privilege: separate read/write paths, explicit auth gates.
+- State assumptions inline. Do not ask clarifying questions mid-design unless blocked.
+
+Output:
+- Goal
+- Existing code to reuse: <file paths>
+- New code: <file paths, one-line purpose each>
+- Data model changes: <SQL or schema diff>
+- API surface: <endpoints, request/response shapes>
+- Failure modes: <list>
+- Build order: numbered, each step 30-90 min
+
+
+## Security Auditor
+---
+temperature: 0.2
+tools: [view_file, list_dir, grep, find_files]
+description: Audits code for security vulnerabilities. Read-only.
+---
+You audit for security issues. Concrete findings only, no generic warnings.
+
+Process:
+1. Identify the trust boundary: where does untrusted input enter? Where does it leave?
+2. Trace input flow with grep. Mark every transformation.
+3. Check each finding against a real attack scenario.
+
+Look for:
+- Injection: SQL (raw queries, string concat into queries), command (subprocess with shell=True, unescaped args), XSS (unescaped output in HTML/JSX), template injection, NoSQL injection
+- AuthN/AuthZ: missing checks on routes, IDOR (user-supplied IDs without ownership check), JWT misuse (alg=none, weak secret, no expiry), session fixation
+- Secrets: hardcoded keys/passwords, .env in repo, secrets in logs, secrets in error messages
+- Crypto: weak hashes (MD5, SHA1 for passwords), missing salt, predictable randomness (Math.random for tokens), ECB mode, custom crypto
+- Network: SSRF (user URL → server fetch), open CORS, missing CSRF on state-changing requests, plaintext over public network
+- File: path traversal, unrestricted upload type/size, zip slip
+- Deserialization: pickle, yaml.load, eval, exec on user input
+- Resource: missing rate limits on auth/expensive endpoints, unbounded query results
+
+For each finding:
+- Severity: Critical / High / Medium / Low
+- Location: file:line
+- Attack scenario: one sentence describing how an attacker exploits this
+- Fix: minimal change
+
+Skip:
+- Generic "use HTTPS" advice
+- "Consider adding rate limiting" without a specific endpoint
+- CVE-of-the-week scares without proof the code is affected
+
+If the code is clean, say so. Do not invent findings.
+
+
+## Prompt Builder
+---
+temperature: 0.4
+tools: [view_file, list_dir, grep, find_files]
+description: Builds prompts for OpenCode, Claude Code, or BooCode dispatch.
+---
+You write prompts that another coding agent will execute. Your output is the prompt, not the work.
+
+Process:
+1. Ask the user (or read context) for: goal, target repo, target files if known, constraints.
+2. list_dir and view_file the target area. Confirm files exist and are roughly the shape you think.
+3. Identify imports, exports, and conventions in the repo (component layout, error handling style, test framework).
+4. Write the prompt.
+
+Prompt structure:
+- One-line goal at the top
+- Constraints block: don't commit, don't push, don't pull. Use `#careful` and `#nofluff` style hashtags if the target agent honors them
+- Pre-flight: list_dir or grep commands the agent must run before writing (e.g. "run: ls frontend/src/components/ui/ and only import primitives that exist")
+- Files to modify: explicit paths
+- Files to create: explicit paths with one-line purpose
+- Behavior spec: numbered, testable
+- Backup rule: `cp file file.bak-$(date +%Y%m%d)` before any destructive edit
+- Verification: `py_compile`, `tsc --noEmit`, `docker compose up --build -d` — whichever applies
+- Stop conditions: when to halt and report instead of pressing on
+
+Rules:
+- Tailored to the target agent: OpenCode honors hashtag snippets and skills; Claude Code honors CLAUDE.md and slash commands; BooCode batches are written as user-facing markdown
+- Never include credentials or secrets
+- Never instruct the agent to commit or push
+- Include the exact model the user wants if dispatch is via Paseo or BooCode batch
+- For BooLab frontend prompts, always include the "verify shadcn primitives exist" preflight
+
+Output: the prompt, ready to paste. Nothing else.

CLAUDE.md

@@ -31,7 +31,7 @@ npx tsc -p apps/web/tsconfig.app.json --noEmit  # web app specifically
 docker compose build --no-cache boocode && docker compose up -d
 ```
 
-There are no tests or linters configured.
+Tests: `pnpm -C apps/server test` runs 23 vitest tests. No test harness on `apps/web` (adding it requires installing vitest as a new devDep). Vitest pinned to `^3` because Vite 5 / vitest 4 are incompatible. No linters configured.
 
 ## Architecture
 
@@ -44,7 +44,7 @@ There are no tests or linters configured.
 - **Zod** for request validation and config parsing.
 
 Key services:
-- **`services/inference.ts`** — Streams LLM responses, executes tool loops (max 5 depth), flushes to DB every 500ms. Publishes `InferenceFrame` events through the broker.
+- **`services/inference.ts`** — Streams LLM responses, executes tool loops (max depth 15, see `MAX_TOOL_LOOP_DEPTH`), flushes to DB every 500ms. Publishes `InferenceFrame` events through the broker.
 - **`services/broker.ts`** — In-memory pub/sub with two channel types: per-session (message streaming) and per-user (sidebar updates). No persistence; clients reconnect on restart.
 - **`services/tools.ts`** — Four read-only file tools exposed as OpenAI function-calling schemas. All file access goes through `path_guard.ts` which resolves against project root.
 - **`services/file_ops.ts`** — Shared file operation implementations used by both inference tools and HTTP routes.
@@ -57,6 +57,7 @@ Route registration: all routes registered in `index.ts` via `register*Routes(app
 - **React 18** + React Router v6 + **Tailwind v4** + shadcn/radix-ui primitives.
 - **Shiki** for syntax highlighting (async `codeToHtml` in `CodeBlock.tsx` and `FileViewer` in `FileBrowserPane.tsx`).
 - Path alias: `@/` maps to `src/`.
+- **Mobile interaction primitives** (post-v1.6): `useViewport` (matchMedia, breakpoints mobile <768 / tablet 768–1023 / desktop ≥1024), `useSidebarDrawer` / `useRightRailDrawer` (Context + auto-close on `useLocation().pathname` change), `useLongPress` (500ms timer, dispatches synthetic `contextmenu` on `[data-tab-id]`), `usePullToRefresh` (80px threshold, 600ms hold), `SwipeablePaneTab` (60px close, 30px vertical bail). Tap-target convention: `max-md:min-h-[44px] max-md:min-w-[44px]`. Mobile headers: `border-b px-3 sm:px-4 py-2` + `style={{ paddingTop: 'max(0.5rem, env(safe-area-inset-top))' }}`. Hamburger left, FolderTree right.
 
 Key patterns:
 - **`hooks/sessionEvents.ts`** — Module-singleton event bus (Set of listeners). Used for cross-component communication: session renames, file-open events, attachment dispatch. 9 event types in the discriminated union. When adding a new event type to the `SessionEvent` union, you must also add a case to the `applyEvent` switch in `useSidebar.ts` (even if it's a no-op `return prev`).
@@ -76,7 +77,7 @@ Key patterns:
 
 ### Multi-pane workspace
 
-Sessions hold 1–5 panes (chat / empty / placeholder terminal+agent). Workspace pane state is **client-side only** (localStorage keyed by sessionId); the legacy `session_panes` table is deprecated. Each chat lives in at most one pane; tab strip is per-pane and tracks `chatIds[]` + `activeChatIdx`. Sessions 1:N chats; chats own messages. Tab reorder via native HTML5 drag events.
+Sessions hold 1–5 panes (chat / empty / placeholder terminal+agent). Workspace pane state is **client-side only** (localStorage key `boocode.workspace.panes.<sessionId>`); the legacy `session_panes` table and its REST endpoints are deprecated — no `/api/panes/*` routes exist. Each chat lives in at most one pane; tab strip is per-pane and tracks `chatIds[]` + `activeChatIdx`. Sessions 1:N chats; chats own messages. Tab reorder via native HTML5 drag events.
 
 ## Database
 
@@ -94,6 +95,7 @@ Required: `DATABASE_URL`, `LLAMA_SWAP_URL`. Optional: `PORT` (3000), `HOST` (0.0
 
 - Sam reviews all diffs and commits manually. Do not commit unless explicitly asked.
 - Deploy: `cd /opt/boocode && docker compose up --build -d` (or `docker compose build --no-cache boocode && docker compose up -d` if you suspect a layer-cache issue).
+- Git push to Gitea: `GIT_SSH_COMMAND="ssh -i /opt/boocode/secrets/boocode_gitea -o IdentitiesOnly=yes" git push origin <branch>`. The default agent identity is rejected; the in-repo deploy key (`secrets/`, gitignored) is the working one. Transient `Connection reset by peer` retries cleanly after `sleep 5`.
 - Don't accumulate `.bak-*` files. Clean them up in the same batch or immediately after merge.
 - Fastify global JSON parser tolerates empty bodies (overridden in `index.ts`); bodyless POSTs (archive, unarchive, stop) work without setting `Content-Type` tricks on the client.
 - Event dedup discipline: for any mutation the server publishes via `broker.publishUser`, do NOT add a local `sessionEvents.emit(...)` after the API call — `useUserEvents` forwards the WS frame onto the bus. Frontend mutation handlers must be idempotent (dedup by id, no-op on already-present).

apps/server/src/index.ts

@@ -14,6 +14,7 @@ import { registerChatRoutes } from './routes/chats.js';
 import { registerSidebarRoutes } from './routes/sidebar.js';
 import { registerWebSocket } from './routes/ws.js';
 import { registerModelRoutes } from './routes/models.js';
+import { registerAgentRoutes } from './routes/agents.js';
 import { createInferenceRunner } from './services/inference.js';
 import { createBroker } from './services/broker.js';
 
@@ -57,6 +58,7 @@ async function main() {
   registerSessionRoutes(app, sql, config, broker);
   registerSettingsRoutes(app, sql);
   registerModelRoutes(app, config);
+  registerAgentRoutes(app, sql);
   registerSidebarRoutes(app, sql);
   registerChatRoutes(app, sql, broker);
 

apps/server/src/routes/agents.ts

@@ -0,0 +1,20 @@
+import type { FastifyInstance } from 'fastify';
+import type { Sql } from '../db.js';
+import { getAgentsForProject } from '../services/agents.js';
+
+export function registerAgentRoutes(app: FastifyInstance, sql: Sql): void {
+  app.get<{ Params: { id: string } }>(
+    '/api/projects/:id/agents',
+    async (req, reply) => {
+      const rows = await sql<{ path: string }[]>`
+        SELECT path FROM projects WHERE id = ${req.params.id}
+      `;
+      if (rows.length === 0) {
+        reply.code(404);
+        return { error: 'project not found' };
+      }
+      // getAgentsForProject handles AGENTS.md presence/parse/cache; never throws.
+      return await getAgentsForProject(rows[0]!.path);
+    }
+  );
+}

apps/server/src/routes/sessions.ts

@@ -5,17 +5,20 @@ import type { Config } from '../config.js';
 import type { Broker } from '../services/broker.js';
 import type { Session } from '../types/api.js';
 import { getSetting } from './settings.js';
+import { getAgentsForProject } from '../services/agents.js';
 
 const CreateBody = z.object({
   name: z.string().min(1).max(200).optional(),
   model: z.string().min(1).max(200).optional(),
   system_prompt: z.string().max(8000).optional(),
+  agent_id: z.string().min(1).max(200).nullable().optional(),
 });
 
 const PatchBody = z.object({
   name: z.string().min(1).max(200).optional(),
   model: z.string().min(1).max(200).optional(),
   system_prompt: z.string().max(8000).optional(),
+  agent_id: z.string().min(1).max(200).nullable().optional(),
 });
 
 async function resolveDefaultModel(sql: Sql, config: Config): Promise<string> {
@@ -24,6 +27,13 @@ async function resolveDefaultModel(sql: Sql, config: Config): Promise<string> {
   return config.DEFAULT_MODEL;
 }
 
+// First agent in the project's effective list (file-defined or builtin),
+// or null if somehow none exist.
+async function resolveDefaultAgent(projectPath: string): Promise<string | null> {
+  const { agents } = await getAgentsForProject(projectPath);
+  return agents[0]?.id ?? null;
+}
+
 export function registerSessionRoutes(
   app: FastifyInstance,
   sql: Sql,
@@ -40,7 +50,7 @@ export function registerSessionRoutes(
       }
       const status = req.query.status === 'archived' ? 'archived' : 'open';
       const rows = await sql<Session[]>`
-        SELECT id, project_id, name, model, system_prompt, status, created_at, updated_at
+        SELECT id, project_id, name, model, system_prompt, status, created_at, updated_at, agent_id
         FROM sessions
         WHERE project_id = ${req.params.id} AND status = ${status}
         ORDER BY updated_at DESC
@@ -57,11 +67,14 @@ export function registerSessionRoutes(
         reply.code(400);
         return { error: 'invalid body', details: parsed.error.flatten() };
       }
-      const project = await sql`SELECT id FROM projects WHERE id = ${req.params.id}`;
+      const project = await sql<{ id: string; path: string }[]>`
+        SELECT id, path FROM projects WHERE id = ${req.params.id}
+      `;
       if (project.length === 0) {
         reply.code(404);
         return { error: 'project not found' };
       }
+      const projectPath = project[0]!.path;
 
       let model = parsed.data.model;
       if (!model) {
@@ -76,12 +89,18 @@ export function registerSessionRoutes(
 
       const name = parsed.data.name ?? 'New session';
       const systemPrompt = parsed.data.system_prompt ?? '';
+      // If the client provided agent_id (string or null), use it; otherwise
+      // resolve to the project's first agent (file-defined or builtin), or null.
+      const agentId =
+        parsed.data.agent_id !== undefined
+          ? parsed.data.agent_id
+          : await resolveDefaultAgent(projectPath);
 
       const row = await sql.begin(async (tx) => {
         const [session] = await tx<Session[]>`
-          INSERT INTO sessions (project_id, name, model, system_prompt)
-          VALUES (${req.params.id}, ${name}, ${model}, ${systemPrompt})
-          RETURNING id, project_id, name, model, system_prompt, status, created_at, updated_at
+          INSERT INTO sessions (project_id, name, model, system_prompt, agent_id)
+          VALUES (${req.params.id}, ${name}, ${model}, ${systemPrompt}, ${agentId})
+          RETURNING id, project_id, name, model, system_prompt, status, created_at, updated_at, agent_id
         `;
         await tx`
           INSERT INTO chats (session_id, name, status)
@@ -101,7 +120,7 @@ export function registerSessionRoutes(
 
   app.get<{ Params: { id: string } }>('/api/sessions/:id', async (req, reply) => {
     const rows = await sql<Session[]>`
-      SELECT id, project_id, name, model, system_prompt, status, created_at, updated_at
+      SELECT id, project_id, name, model, system_prompt, status, created_at, updated_at, agent_id
       FROM sessions WHERE id = ${req.params.id}
     `;
     if (rows.length === 0) {
@@ -120,22 +139,36 @@ export function registerSessionRoutes(
         return { error: 'invalid body', details: parsed.error.flatten() };
       }
       const { name, model, system_prompt } = parsed.data;
+      // agent_id is tri-state on the wire: omitted = no change, null = clear,
+      // string = set. CASE WHEN inside SET handles all three atomically.
+      const agentIdProvided = parsed.data.agent_id !== undefined;
+      const newAgentId = parsed.data.agent_id ?? null;
+      // Read the prior name so the post-update publish can skip no-op renames
+      // (PATCH { name: "Foo" } where the session is already "Foo"). The window
+      // between SELECT and UPDATE is sub-millisecond in the same request handler;
+      // a concurrent rename in that gap would just mean one stale publish, which
+      // existing clients dedup by id.
+      const before = await sql<{ name: string }[]>`
+        SELECT name FROM sessions WHERE id = ${req.params.id}
+      `;
+      const priorName = before[0]?.name;
       const rows = await sql<Session[]>`
         UPDATE sessions
         SET
           name = COALESCE(${name ?? null}, name),
           model = COALESCE(${model ?? null}, model),
           system_prompt = COALESCE(${system_prompt ?? null}, system_prompt),
+          agent_id = CASE WHEN ${agentIdProvided} THEN ${newAgentId} ELSE agent_id END,
           updated_at = clock_timestamp()
         WHERE id = ${req.params.id}
-        RETURNING id, project_id, name, model, system_prompt, status, created_at, updated_at
+        RETURNING id, project_id, name, model, system_prompt, status, created_at, updated_at, agent_id
       `;
       if (rows.length === 0) {
         reply.code(404);
         return { error: 'session not found' };
       }
       const session = rows[0]!;
-      if (name !== undefined) {
+      if (name !== undefined && session.name !== priorName) {
         broker.publishUser('default', {
           type: 'session_renamed',
           session_id: session.id,
@@ -174,7 +207,7 @@ export function registerSessionRoutes(
       const rows = await sql<Session[]>`
         UPDATE sessions SET status = 'open', updated_at = clock_timestamp()
         WHERE id = ${req.params.id} AND status = 'archived'
-        RETURNING id, project_id, name, model, system_prompt, status, created_at, updated_at
+        RETURNING id, project_id, name, model, system_prompt, status, created_at, updated_at, agent_id
       `;
       if (rows.length === 0) {
         reply.code(404);

apps/server/src/schema.sql

@@ -153,3 +153,8 @@ BEGIN
       CHECK (status IN ('open', 'archived'));
   END IF;
 END $$;
+
+-- v1.x-batch9: per-session agent reference. Agent definitions are not stored in
+-- the DB; they live in builtins (services/agents.ts) and a per-project AGENTS.md.
+-- agent_id is the slugified agent name. NULL means "use BooCode defaults".
+ALTER TABLE sessions ADD COLUMN IF NOT EXISTS agent_id TEXT;

apps/server/src/services/agents.ts

@@ -0,0 +1,458 @@
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import type { Agent, AgentsResponse } from '../types/api.js';
+
+// Tools whitelist universe matches services/tools.ts ALL_TOOLS. Keep in sync.
+const ALL_TOOL_NAMES = ['view_file', 'list_dir', 'grep', 'find_files'] as const;
+const DEFAULT_TOOLS: string[] = [...ALL_TOOL_NAMES];
+const DEFAULT_TEMPERATURE = 0.7;
+
+export function slugify(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+// Six builtin defaults. model is intentionally null — session.model wins.
+// Match AGENTS.md format; system prompts are verbatim.
+const BUILTIN_AGENTS: Agent[] = [
+  {
+    id: 'code-reviewer',
+    name: 'Code Reviewer',
+    description: 'Reviews code for bugs, security issues, and maintainability. Read-only.',
+    temperature: 0.3,
+    tools: [...DEFAULT_TOOLS],
+    model: null,
+    source: 'builtin',
+    system_prompt: `You review code. Find real problems, not style nits.
+
+Process:
+1. Read the file(s) in question with view_file. If a diff is provided, read surrounding context too.
+2. Use grep/find_files to check how changed symbols are used elsewhere.
+3. Cite every finding as file:line.
+
+Prioritize in order:
+1. Bugs and logic errors
+2. Security issues (injection, auth bypass, secret leakage, unsafe deserialization, SSRF, path traversal)
+3. Race conditions, error handling, resource leaks
+4. Performance issues with measurable impact
+5. Maintainability (only if it blocks future work)
+
+Skip: formatting, naming preferences, "consider extracting", "add a comment here". The user has a linter.
+
+Output format:
+- Critical: <file:line> — <issue> — <fix>
+- Major: <file:line> — <issue> — <fix>
+- Minor: <file:line> — <issue> — <fix>
+
+If nothing critical or major, say so in one line. Do not pad.`,
+  },
+  {
+    id: 'debugger',
+    name: 'Debugger',
+    description: 'Diagnoses bugs from error messages, logs, or described symptoms.',
+    temperature: 0.2,
+    tools: [...DEFAULT_TOOLS],
+    model: null,
+    source: 'builtin',
+    system_prompt: `You diagnose bugs. Form a hypothesis, prove it with evidence from the code.
+
+Process:
+1. Restate the symptom in one line. Confirm you understand it.
+2. Read the error/stacktrace. Identify the exact frame where things go wrong.
+3. view_file on that frame. Read 50 lines around it.
+4. grep for callers, related state, recent changes that could explain it.
+5. State the root cause with file:line evidence.
+6. Propose the minimal fix. Note any side effects.
+
+Rules:
+- Never guess. If evidence is missing, say what you need (specific log line, specific file, specific repro step).
+- Distinguish symptom from cause. A null check fixes the symptom; missing init causes it.
+- Off-by-one, race conditions, and silent except blocks are common — check for them.
+- If two plausible causes exist, name both and say what would discriminate.
+
+Output:
+- Symptom: <one line>
+- Root cause: <file:line> — <explanation>
+- Fix: <minimal diff or description>
+- Risk: <what could break>`,
+  },
+  {
+    id: 'refactorer',
+    name: 'Refactorer',
+    description: 'Proposes refactors for clarity, deduplication, or decoupling. Read-only — outputs plans, not edits.',
+    temperature: 0.3,
+    tools: [...DEFAULT_TOOLS],
+    model: null,
+    source: 'builtin',
+    system_prompt: `You propose refactors. You do not apply them. The user applies via OpenCode or Claude Code.
+
+Process:
+1. Read the target file(s).
+2. grep for callers, duplicates, and similar patterns elsewhere in the repo.
+3. Identify the smallest refactor that delivers the goal.
+
+Prioritize:
+1. Deduplication where 3+ sites have near-identical logic
+2. Extracting a function/module when one is doing two unrelated jobs
+3. Decoupling when a change in A forces a change in B unnecessarily
+4. Renaming when a name actively misleads
+
+Reject:
+- Refactors that touch 10+ files for marginal gain
+- "Modernization" with no concrete benefit
+- Abstraction for future flexibility that may never come
+- Style-only changes
+
+Output:
+- Goal: <one line>
+- Scope: <files affected, count of lines roughly>
+- Plan: numbered steps, each one self-contained
+- Risk: <what tests must pass, what could regress>
+- Skip if: <conditions under which this refactor is not worth doing>`,
+  },
+  {
+    id: 'architect',
+    name: 'Architect',
+    description: 'Designs new features, modules, or architectural changes. Outputs a build plan.',
+    temperature: 0.5,
+    tools: [...DEFAULT_TOOLS],
+    model: null,
+    source: 'builtin',
+    system_prompt: `You design. You produce build plans, not code.
+
+Process:
+1. Restate the goal in your own words. Confirm constraints (perf, deploy, deps).
+2. list_dir the relevant areas. Read existing patterns — match them unless there's a reason not to.
+3. Decide: extend existing code or add new module. Justify.
+4. Sketch the data flow: inputs → transforms → outputs → side effects.
+5. Identify integration points: DB schema, API surface, env vars, container boundaries.
+6. List failure modes and how the design handles them.
+
+Rules:
+- Reuse before inventing. If a service/lib in the repo already does this, say so.
+- Prefer boring tech. New deps require justification.
+- Tailscale IPs for internal routing. No 0.0.0.0 binds.
+- Least privilege: separate read/write paths, explicit auth gates.
+- State assumptions inline. Do not ask clarifying questions mid-design unless blocked.
+
+Output:
+- Goal
+- Existing code to reuse: <file paths>
+- New code: <file paths, one-line purpose each>
+- Data model changes: <SQL or schema diff>
+- API surface: <endpoints, request/response shapes>
+- Failure modes: <list>
+- Build order: numbered, each step 30-90 min`,
+  },
+  {
+    id: 'security-auditor',
+    name: 'Security Auditor',
+    description: 'Audits code for security vulnerabilities. Read-only.',
+    temperature: 0.2,
+    tools: [...DEFAULT_TOOLS],
+    model: null,
+    source: 'builtin',
+    system_prompt: `You audit for security issues. Concrete findings only, no generic warnings.
+
+Process:
+1. Identify the trust boundary: where does untrusted input enter? Where does it leave?
+2. Trace input flow with grep. Mark every transformation.
+3. Check each finding against a real attack scenario.
+
+Look for:
+- Injection: SQL (raw queries, string concat into queries), command (subprocess with shell=True, unescaped args), XSS (unescaped output in HTML/JSX), template injection, NoSQL injection
+- AuthN/AuthZ: missing checks on routes, IDOR (user-supplied IDs without ownership check), JWT misuse (alg=none, weak secret, no expiry), session fixation
+- Secrets: hardcoded keys/passwords, .env in repo, secrets in logs, secrets in error messages
+- Crypto: weak hashes (MD5, SHA1 for passwords), missing salt, predictable randomness (Math.random for tokens), ECB mode, custom crypto
+- Network: SSRF (user URL → server fetch), open CORS, missing CSRF on state-changing requests, plaintext over public network
+- File: path traversal, unrestricted upload type/size, zip slip
+- Deserialization: pickle, yaml.load, eval, exec on user input
+- Resource: missing rate limits on auth/expensive endpoints, unbounded query results
+
+For each finding:
+- Severity: Critical / High / Medium / Low
+- Location: file:line
+- Attack scenario: one sentence describing how an attacker exploits this
+- Fix: minimal change
+
+Skip:
+- Generic "use HTTPS" advice
+- "Consider adding rate limiting" without a specific endpoint
+- CVE-of-the-week scares without proof the code is affected
+
+If the code is clean, say so. Do not invent findings.`,
+  },
+  {
+    id: 'prompt-builder',
+    name: 'Prompt Builder',
+    description: 'Builds prompts for OpenCode, Claude Code, or BooCode dispatch.',
+    temperature: 0.4,
+    tools: [...DEFAULT_TOOLS],
+    model: null,
+    source: 'builtin',
+    system_prompt: `You write prompts that another coding agent will execute. Your output is the prompt, not the work.
+
+Process:
+1. Ask the user (or read context) for: goal, target repo, target files if known, constraints.
+2. list_dir and view_file the target area. Confirm files exist and are roughly the shape you think.
+3. Identify imports, exports, and conventions in the repo (component layout, error handling style, test framework).
+4. Write the prompt.
+
+Prompt structure:
+- One-line goal at the top
+- Constraints block: don't commit, don't push, don't pull. Use \`#careful\` and \`#nofluff\` style hashtags if the target agent honors them
+- Pre-flight: list_dir or grep commands the agent must run before writing (e.g. "run: ls frontend/src/components/ui/ and only import primitives that exist")
+- Files to modify: explicit paths
+- Files to create: explicit paths with one-line purpose
+- Behavior spec: numbered, testable
+- Backup rule: \`cp file file.bak-\$(date +%Y%m%d)\` before any destructive edit
+- Verification: \`py_compile\`, \`tsc --noEmit\`, \`docker compose up --build -d\` — whichever applies
+- Stop conditions: when to halt and report instead of pressing on
+
+Rules:
+- Tailored to the target agent: OpenCode honors hashtag snippets and skills; Claude Code honors CLAUDE.md and slash commands; BooCode batches are written as user-facing markdown
+- Never include credentials or secrets
+- Never instruct the agent to commit or push
+- Include the exact model the user wants if dispatch is via Paseo or BooCode batch
+- For BooLab frontend prompts, always include the "verify shadcn primitives exist" preflight
+
+Output: the prompt, ready to paste. Nothing else.`,
+  },
+];
+
+// ---- AGENTS.md parser ------------------------------------------------------
+
+interface ParsedFrontmatter {
+  temperature?: number;
+  tools?: string[];
+  description?: string;
+  model?: string;
+}
+
+function stripQuotes(s: string): string {
+  if (
+    s.length >= 2 &&
+    (s[0] === '"' || s[0] === "'") &&
+    s[0] === s[s.length - 1]
+  ) {
+    return s.slice(1, -1);
+  }
+  return s;
+}
+
+function parseFrontmatter(yaml: string): { data: ParsedFrontmatter; errors: string[] } {
+  const data: ParsedFrontmatter = {};
+  const errors: string[] = [];
+  const lines = yaml.split('\n');
+  let arrayKey: 'tools' | null = null;
+
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+    if (line.length === 0) continue;
+
+    // Block-list continuation: "- value" under a key that was set to empty
+    if (arrayKey && line.startsWith('- ')) {
+      data[arrayKey]!.push(line.slice(2).trim());
+      continue;
+    }
+    arrayKey = null;
+
+    const colonIdx = line.indexOf(':');
+    if (colonIdx < 0) continue;
+    const key = line.slice(0, colonIdx).trim();
+    const valueRaw = line.slice(colonIdx + 1).trim();
+
+    if (key === 'temperature') {
+      const n = Number(valueRaw);
+      if (Number.isFinite(n)) data.temperature = n;
+      else errors.push(`temperature must be a number (got "${valueRaw}")`);
+    } else if (key === 'tools') {
+      if (valueRaw === '') {
+        data.tools = [];
+        arrayKey = 'tools';
+      } else if (valueRaw.startsWith('[') && valueRaw.endsWith(']')) {
+        const inner = valueRaw.slice(1, -1);
+        data.tools = inner
+          .split(',')
+          .map((s) => stripQuotes(s.trim()))
+          .filter((s) => s.length > 0);
+      } else {
+        // Loose form: "tools: a, b, c"
+        data.tools = valueRaw
+          .split(',')
+          .map((s) => stripQuotes(s.trim()))
+          .filter((s) => s.length > 0);
+      }
+    } else if (key === 'description') {
+      data.description = stripQuotes(valueRaw);
+    } else if (key === 'model') {
+      data.model = stripQuotes(valueRaw);
+    }
+    // Unknown keys silently ignored — forward-compat.
+  }
+
+  return { data, errors };
+}
+
+interface ParseResult {
+  agents: Agent[];
+  error: string | null;
+}
+
+export function parseAgentsMd(content: string): ParseResult {
+  const errors: string[] = [];
+  const agents: Agent[] = [];
+
+  // Split into per-agent sections by lines that exactly match "## <name>".
+  // Lines starting with "### " (level-3 headings) are not section boundaries.
+  const sections: { name: string; body: string }[] = [];
+  let currentName: string | null = null;
+  let currentLines: string[] = [];
+
+  for (const line of content.split('\n')) {
+    const h2 = /^##\s+(.+?)\s*$/.exec(line);
+    const h3 = line.startsWith('### ');
+    if (h2 && !h3) {
+      if (currentName !== null) {
+        sections.push({ name: currentName, body: currentLines.join('\n') });
+      }
+      currentName = h2[1]!.trim();
+      currentLines = [];
+      continue;
+    }
+    if (currentName !== null) {
+      currentLines.push(line);
+    }
+  }
+  if (currentName !== null) {
+    sections.push({ name: currentName, body: currentLines.join('\n') });
+  }
+
+  for (const section of sections) {
+    const lines = section.body.split('\n');
+    // Opening "---" fence must be the first non-empty line (blank lines allowed).
+    let openIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+      const t = lines[i]!.trim();
+      if (t === '') continue;
+      if (t === '---') {
+        openIdx = i;
+      }
+      break;
+    }
+    if (openIdx < 0) {
+      errors.push(`agent "${section.name}": missing opening --- fence after heading`);
+      continue;
+    }
+    let closeIdx = -1;
+    for (let i = openIdx + 1; i < lines.length; i++) {
+      if (lines[i]!.trim() === '---') {
+        closeIdx = i;
+        break;
+      }
+    }
+    if (closeIdx < 0) {
+      errors.push(`agent "${section.name}": missing closing --- fence`);
+      continue;
+    }
+    const yamlText = lines.slice(openIdx + 1, closeIdx).join('\n');
+    const systemPrompt = lines.slice(closeIdx + 1).join('\n').trim();
+
+    const { data: fm, errors: fmErrors } = parseFrontmatter(yamlText);
+    if (fmErrors.length > 0) {
+      errors.push(`agent "${section.name}": ${fmErrors.join('; ')}`);
+      continue;
+    }
+
+    const filteredTools = Array.isArray(fm.tools)
+      ? fm.tools.filter((t): t is string =>
+          (ALL_TOOL_NAMES as readonly string[]).includes(t)
+        )
+      : DEFAULT_TOOLS;
+
+    agents.push({
+      id: slugify(section.name),
+      name: section.name,
+      description: fm.description ?? '',
+      system_prompt: systemPrompt,
+      temperature: typeof fm.temperature === 'number' ? fm.temperature : DEFAULT_TEMPERATURE,
+      tools: filteredTools,
+      model: typeof fm.model === 'string' && fm.model.length > 0 ? fm.model : null,
+      source: 'file',
+    });
+  }
+
+  return { agents, error: errors.length > 0 ? errors.join('; ') : null };
+}
+
+// ---- mtime-keyed cache + public API ----------------------------------------
+
+interface CacheEntry {
+  mtimeMs: number;
+  result: AgentsResponse;
+}
+
+const cache = new Map<string, CacheEntry>();
+
+// Test/admin: force re-parse on next call for a project (or all projects).
+export function invalidateAgentsCache(projectPath?: string): void {
+  if (projectPath === undefined) {
+    cache.clear();
+  } else {
+    cache.delete(projectPath);
+  }
+}
+
+export async function getAgentsForProject(projectPath: string): Promise<AgentsResponse> {
+  const agentsPath = join(projectPath, 'AGENTS.md');
+  let mtimeMs: number;
+  try {
+    const s = await fs.stat(agentsPath);
+    mtimeMs = s.mtimeMs;
+  } catch {
+    // No AGENTS.md → builtins, no parse error
+    cache.delete(projectPath);
+    return { agents: BUILTIN_AGENTS, parse_error: null };
+  }
+
+  const cached = cache.get(projectPath);
+  if (cached && cached.mtimeMs === mtimeMs) {
+    return cached.result;
+  }
+
+  let content: string;
+  try {
+    content = await fs.readFile(agentsPath, 'utf8');
+  } catch {
+    cache.delete(projectPath);
+    return { agents: BUILTIN_AGENTS, parse_error: null };
+  }
+
+  const parsed = parseAgentsMd(content);
+  let result: AgentsResponse;
+  if (parsed.error) {
+    // Parse error: surface in API, fall back to builtins
+    result = { agents: BUILTIN_AGENTS, parse_error: parsed.error };
+  } else if (parsed.agents.length === 0) {
+    // Empty / no headings → builtins
+    result = { agents: BUILTIN_AGENTS, parse_error: null };
+  } else {
+    // At least one valid agent → file-defined agents win, builtins hidden
+    result = { agents: parsed.agents, parse_error: null };
+  }
+
+  cache.set(projectPath, { mtimeMs, result });
+  return result;
+}
+
+export async function getAgentById(
+  projectPath: string,
+  agentId: string
+): Promise<Agent | null> {
+  const { agents } = await getAgentsForProject(projectPath);
+  return agents.find((a) => a.id === agentId) ?? null;
+}
+
+export { BUILTIN_AGENTS };

apps/server/src/services/auto_name.ts

@@ -144,4 +144,23 @@ export async function maybeAutoNameChat(
     updated_at: updated[0]!.updated_at,
   });
   ctx.log.info({ chatId, name }, 'chat auto-named');
+
+  // Propagate to the parent session if it's still on its default name.
+  // The WHERE guard makes the check atomic — if the user has already
+  // renamed (or a prior chat already propagated), this UPDATE matches
+  // zero rows and we do nothing. First chat wins; manual renames win.
+  const renamedSession = await ctx.sql<{ id: string; name: string }[]>`
+    UPDATE sessions
+    SET name = ${name}
+    WHERE id = ${sessionId} AND name = 'New session'
+    RETURNING id, name
+  `;
+  if (renamedSession.length > 0) {
+    ctx.publishUser({
+      type: 'session_renamed',
+      session_id: sessionId,
+      name,
+    });
+    ctx.log.info({ sessionId, name }, 'session auto-named from chat');
+  }
 }

apps/server/src/services/inference.ts

@@ -1,16 +1,17 @@
 import type { FastifyBaseLogger } from 'fastify';
 import type { Sql } from '../db.js';
 import type { Config } from '../config.js';
-import type { Message, Project, Session, ToolCall, UserStreamFrame } from '../types/api.js';
-import { ALL_TOOLS, TOOLS_BY_NAME, toolJsonSchemas } from './tools.js';
+import type { Agent, Message, Project, Session, ToolCall, UserStreamFrame } from '../types/api.js';
+import { ALL_TOOLS, TOOLS_BY_NAME, toolJsonSchemas, type ToolJsonSchema } from './tools.js';
 import { PathScopeError, resolveProjectRoot } from './path_guard.js';
 import { maybeAutoNameChat } from './auto_name.js';
+import { getAgentById } from './agents.js';
 
 const BASE_SYSTEM_PROMPT = (projectPath: string) =>
   `You are BooCode Chat, a code investigation assistant. The user is working on a project located at ${projectPath}. Use the file-read tools (view_file, list_dir, grep, find_files) to investigate code when needed. Be concise. Cite file paths and line numbers when discussing code. Do not hallucinate file contents — read the file first. Tool results may be truncated; if so, narrow your query rather than guessing.`;
 
 const DB_FLUSH_INTERVAL_MS = 500;
-const MAX_TOOL_LOOP_DEPTH = 5;
+const MAX_TOOL_LOOP_DEPTH = 15;
 
 export interface InferenceFrame {
   type:
@@ -91,16 +92,32 @@ export interface InferenceContext {
   publishUser: (frame: UserStreamFrame) => void;
 }
 
+// Resolution order: base prompt < agent.system_prompt < session.system_prompt.
+// Agent prompts layer on top of the base; session prompt is the most specific
+// override and stacks last so callers can append per-session instructions.
+export function buildSystemPrompt(
+  project: Project,
+  session: Session,
+  agent: Agent | null
+): string {
+  let out = BASE_SYSTEM_PROMPT(project.path);
+  if (agent && agent.system_prompt.trim().length > 0) {
+    out += '\n\n' + agent.system_prompt.trim();
+  }
+  if (session.system_prompt && session.system_prompt.trim().length > 0) {
+    out += '\n\n' + session.system_prompt.trim();
+  }
+  return out;
+}
+
 export function buildMessagesPayload(
   session: Session,
   project: Project,
-  history: Message[]
+  history: Message[],
+  agent: Agent | null = null
 ): OpenAiMessage[] {
   const out: OpenAiMessage[] = [];
-  let systemPrompt = BASE_SYSTEM_PROMPT(project.path);
-  if (session.system_prompt && session.system_prompt.trim().length > 0) {
-    systemPrompt += '\n\n' + session.system_prompt.trim();
-  }
+  const systemPrompt = buildSystemPrompt(project, session, agent);
   out.push({ role: 'system', content: systemPrompt });
 
   // Find the latest compact marker — only send messages from that point onwards
@@ -161,7 +178,7 @@ async function loadContext(
   chatId: string
 ): Promise<{ session: Session; project: Project; history: Message[] } | null> {
   const sessionRows = await sql<Session[]>`
-    SELECT id, project_id, name, model, system_prompt, status, created_at, updated_at
+    SELECT id, project_id, name, model, system_prompt, status, created_at, updated_at, agent_id
     FROM sessions WHERE id = ${sessionId}
   `;
   if (sessionRows.length === 0) return null;
@@ -217,11 +234,18 @@ interface StreamResult {
   nCtx: number | null;
 }
 
+interface StreamOptions {
+  // null = omit tools entirely (compact phase); [] = caller stripped all tools
+  // (rare; we still omit from the request body to avoid OpenAI 400).
+  tools: ToolJsonSchema[] | null;
+  temperature?: number;
+}
+
 async function streamCompletion(
   ctx: InferenceContext,
   model: string,
   messages: OpenAiMessage[],
-  includeTools: boolean,
+  opts: StreamOptions,
   onDelta: (content: string) => void,
   signal?: AbortSignal
 ): Promise<StreamResult> {
@@ -231,10 +255,13 @@ async function streamCompletion(
     stream: true,
     stream_options: { include_usage: true },
   };
-  if (includeTools) {
-    body['tools'] = toolJsonSchemas();
+  if (opts.tools && opts.tools.length > 0) {
+    body['tools'] = opts.tools;
     body['tool_choice'] = 'auto';
   }
+  if (typeof opts.temperature === 'number') {
+    body['temperature'] = opts.temperature;
+  }
 
   const res = await fetch(`${ctx.config.LLAMA_SWAP_URL}/v1/chat/completions`, {
     method: 'POST',
@@ -366,7 +393,8 @@ async function executeStreamPhase(
   args: TurnArgs,
   session: Session,
   messages: OpenAiMessage[],
-  state: StreamPhaseState
+  state: StreamPhaseState,
+  agent: Agent | null
 ): Promise<StreamResult> {
   const { sessionId, chatId, assistantMessageId, signal } = args;
 
@@ -407,12 +435,20 @@ async function executeStreamPhase(
     }, DB_FLUSH_INTERVAL_MS);
   };
 
+  // Tool whitelist: if an agent is set, filter the global tool list to only the
+  // tool names it allows. Unknown names in agent.tools are dropped silently
+  // (handled here by intersection). When no agent: send all tools.
+  const effectiveTools: ToolJsonSchema[] = agent
+    ? toolJsonSchemas().filter((t) => agent.tools.includes(t.function.name))
+    : toolJsonSchemas();
+  const effectiveTemperature = agent?.temperature;
+
   try {
     return await streamCompletion(
       ctx,
       session.model,
       messages,
-      true,
+      { tools: effectiveTools, temperature: effectiveTemperature },
       (delta) => {
         state.accumulated += delta;
         ctx.publish(sessionId, {
@@ -657,12 +693,18 @@ async function runAssistantTurn(
   }
   const { session, project, history } = loaded;
   const projectRoot = await resolveProjectRoot(project.path);
-  const messages = buildMessagesPayload(session, project, history);
+  // Agent resolution is per-turn so PATCH agent_id mid-conversation takes
+  // effect on the next message. Unknown agent_id returns null silently —
+  // session falls back to base prompt + all tools + default temperature.
+  const agent = session.agent_id
+    ? await getAgentById(project.path, session.agent_id)
+    : null;
+  const messages = buildMessagesPayload(session, project, history, agent);
 
   const state: StreamPhaseState = { accumulated: '', startedAt: null };
   let result: StreamResult;
   try {
-    result = await executeStreamPhase(ctx, args, session, messages, state);
+    result = await executeStreamPhase(ctx, args, session, messages, state, agent);
   } catch (err) {
     await handleAbortOrError(ctx, args, state.accumulated, err);
     return;
@@ -720,7 +762,7 @@ async function runCompact(
       ctx,
       session.model,
       messagesForSummary,
-      false,
+      { tools: null },
       (delta) => {
         content += delta;
         ctx.publish(sessionId, {

apps/server/src/types/api.ts

@@ -28,6 +28,27 @@ export interface Session {
   status: SessionStatus;
   created_at: string;
   updated_at: string;
+  agent_id: string | null;
+}
+
+// Agent sources: 'builtin' = baked-in default (services/agents.ts),
+// 'file' = parsed from project's AGENTS.md.
+export type AgentSource = 'builtin' | 'file';
+
+export interface Agent {
+  id: string;            // slug of name; stable handle stored in sessions.agent_id
+  name: string;
+  description: string;
+  system_prompt: string;
+  temperature: number;
+  tools: string[];       // whitelist of tool names; empty = no tools allowed
+  model: string | null;  // null means "session.model wins"
+  source: AgentSource;
+}
+
+export interface AgentsResponse {
+  agents: Agent[];
+  parse_error: string | null;  // present (non-null) when AGENTS.md exists but failed to parse
 }
 
 // KEEP IN SYNC: apps/server/src/schema.sql chats_status_chk

apps/web/src/App.tsx

@@ -9,6 +9,7 @@ import { Session } from '@/pages/Session';
 import { Toaster } from '@/components/ui/sonner';
 import { useUserEvents } from '@/hooks/useUserEvents';
 import { SidebarDrawerProvider, useSidebarDrawer } from '@/hooks/useSidebarDrawer';
+import { RightRailDrawerProvider, useRightRailDrawer } from '@/hooks/useRightRailDrawer';
 import { useViewport } from '@/hooks/useViewport';
 
 function SessionRightRail() {
@@ -26,13 +27,11 @@ function RightRailForSession({ sessionId }: { sessionId: string }) {
       .catch((err) => console.warn('RightRail: failed to fetch session', err));
   }, [sessionId]);
   if (!projectId) return null;
-  // Hidden entirely below md breakpoint; mobile users get the file browser
-  // via the FileBrowserPane infrastructure if/when it lands in workspace panes.
-  return (
-    <div className="max-md:hidden contents">
-      <RightRail projectId={projectId} />
-    </div>
-  );
+  // v1.6.2: rendered on all viewports. On mobile, RightRail itself renders as
+  // a right-side drawer toggled by the header's FolderTree button (via
+  // useRightRailDrawer). On desktop, it renders inline as before with its
+  // own internal open/close state.
+  return <RightRail projectId={projectId} />;
 }
 
 function MobileBackdrop() {
@@ -48,6 +47,19 @@ function MobileBackdrop() {
   );
 }
 
+function MobileRightRailBackdrop() {
+  const { open, setOpen } = useRightRailDrawer();
+  const { isMobile } = useViewport();
+  if (!isMobile || !open) return null;
+  return (
+    <div
+      className="fixed inset-0 z-30 bg-black/40 md:hidden"
+      onClick={() => setOpen(false)}
+      aria-hidden="true"
+    />
+  );
+}
+
 function AppShell() {
   useUserEvents();
   return (
@@ -61,6 +73,7 @@ function AppShell() {
           <Route path="/session/:id" element={<Session />} />
         </Routes>
       </main>
+      <MobileRightRailBackdrop />
       <Routes>
         <Route path="/session/:id" element={<SessionRightRail />} />
       </Routes>
@@ -73,7 +86,9 @@ export default function App() {
   return (
     <BrowserRouter>
       <SidebarDrawerProvider>
-        <AppShell />
+        <RightRailDrawerProvider>
+          <AppShell />
+        </RightRailDrawerProvider>
       </SidebarDrawerProvider>
     </BrowserRouter>
   );

apps/web/src/api/client.ts

@@ -8,6 +8,7 @@ import type {
   SidebarResponse,
   ListDirResult,
   ViewFileResult,
+  AgentsResponse,
 } from './types';
 
 export class ApiError extends Error {
@@ -93,7 +94,7 @@ export const api = {
       request<Session[]>(`/api/projects/${projectId}/sessions${status ? `?status=${status}` : ''}`),
     create: (
       projectId: string,
-      body: { name?: string; model?: string; system_prompt?: string }
+      body: { name?: string; model?: string; system_prompt?: string; agent_id?: string | null }
     ) =>
       request<Session>(`/api/projects/${projectId}/sessions`, {
         method: 'POST',
@@ -102,7 +103,7 @@ export const api = {
     get: (id: string) => request<Session>(`/api/sessions/${id}`),
     update: (
       id: string,
-      body: Partial<Pick<Session, 'name' | 'model' | 'system_prompt'>>
+      body: Partial<Pick<Session, 'name' | 'model' | 'system_prompt' | 'agent_id'>>
     ) =>
       request<Session>(`/api/sessions/${id}`, {
         method: 'PATCH',
@@ -179,6 +180,11 @@ export const api = {
 
   models: () => request<ModelInfo[]>('/api/models'),
 
+  agents: {
+    list: (projectId: string) =>
+      request<AgentsResponse>(`/api/projects/${projectId}/agents`),
+  },
+
   settings: {
     get: () => request<Record<string, unknown>>('/api/settings'),
     patch: (body: Record<string, unknown>) =>

apps/web/src/api/types.ts

@@ -27,6 +27,25 @@ export interface Session {
   status: SessionStatus;
   created_at: string;
   updated_at: string;
+  agent_id: string | null;
+}
+
+export type AgentSource = 'builtin' | 'file';
+
+export interface Agent {
+  id: string;
+  name: string;
+  description: string;
+  system_prompt: string;
+  temperature: number;
+  tools: string[];
+  model: string | null;
+  source: AgentSource;
+}
+
+export interface AgentsResponse {
+  agents: Agent[];
+  parse_error: string | null;
 }
 
 export const CHAT_STATUSES = ['open', 'archived'] as const;

apps/web/src/components/AgentPicker.tsx

@@ -0,0 +1,108 @@
+import { useEffect, useState } from 'react';
+import { Check, ChevronDown } from 'lucide-react';
+import { toast } from 'sonner';
+import { api } from '@/api/client';
+import type { Agent } from '@/api/types';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+
+interface Props {
+  projectId: string;
+  value: string | null;
+  onChange: (agentId: string | null) => void | Promise<void>;
+}
+
+export function AgentPicker({ projectId, value, onChange }: Props) {
+  const [agents, setAgents] = useState<Agent[] | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [open, setOpen] = useState(false);
+
+  // Load on mount (and on projectId change) so the trigger shows the agent
+  // name immediately, not the raw id. AGENTS.md parse errors surface as a
+  // toast once per load.
+  useEffect(() => {
+    let cancelled = false;
+    setAgents(null);
+    setError(null);
+    api.agents
+      .list(projectId)
+      .then((res) => {
+        if (cancelled) return;
+        setAgents(res.agents);
+        if (res.parse_error) {
+          toast.error(`AGENTS.md parse error: ${res.parse_error}`);
+        }
+      })
+      .catch((err) => {
+        if (cancelled) return;
+        setError(err instanceof Error ? err.message : 'failed to load agents');
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [projectId]);
+
+  const selectedAgent = agents?.find((a) => a.id === value) ?? null;
+  const triggerLabel = value === null
+    ? 'No agent'
+    : selectedAgent?.name ?? value;
+
+  return (
+    <DropdownMenu open={open} onOpenChange={setOpen}>
+      <DropdownMenuTrigger asChild>
+        <button
+          type="button"
+          className="text-xs text-muted-foreground hover:text-foreground flex items-center gap-1 px-1.5 py-0.5 rounded hover:bg-muted/60"
+          title={selectedAgent?.description ?? undefined}
+        >
+          <span className="truncate max-w-[160px]">{triggerLabel}</span>
+          <ChevronDown className="size-3 opacity-70" />
+        </button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="start" className="max-h-80 overflow-y-auto w-72">
+        {error && (
+          <div className="px-2 py-1.5 text-xs text-destructive">{error}</div>
+        )}
+        {agents === null && !error && (
+          <div className="px-2 py-1.5 text-xs text-muted-foreground">Loading…</div>
+        )}
+        {agents !== null && (
+          <>
+            <DropdownMenuItem
+              onSelect={() => void onChange(null)}
+              className="text-xs"
+            >
+              <Check className={`size-3 ${value === null ? 'opacity-100' : 'opacity-0'}`} />
+              <span className="font-medium">No agent</span>
+            </DropdownMenuItem>
+            {agents.length > 0 && <DropdownMenuSeparator />}
+            {agents.map((a) => (
+              <DropdownMenuItem
+                key={a.id}
+                onSelect={() => void onChange(a.id)}
+                className="text-xs flex-col items-start gap-0.5"
+              >
+                <div className="flex items-center gap-1.5">
+                  <Check
+                    className={`size-3 ${a.id === value ? 'opacity-100' : 'opacity-0'}`}
+                  />
+                  <span className="font-medium">{a.name}</span>
+                </div>
+                {a.description && (
+                  <span className="text-muted-foreground pl-[18px] truncate w-full">
+                    {a.description}
+                  </span>
+                )}
+              </DropdownMenuItem>
+            ))}
+          </>
+        )}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}

apps/web/src/components/ChatInput.tsx

@@ -15,6 +15,7 @@ import { AttachmentChip } from '@/components/AttachmentChip';
 import { AttachmentPreviewModal } from '@/components/AttachmentPreviewModal';
 import { FileMentionPopover } from '@/components/FileMentionPopover';
 import { DropOverlay } from '@/components/DropOverlay';
+import { AgentPicker } from '@/components/AgentPicker';
 import { api } from '@/api/client';
 import { sessionEvents } from '@/hooks/sessionEvents';
 import { useViewport } from '@/hooks/useViewport';
@@ -24,11 +25,15 @@ const MAX_ATTACHMENTS = 10;
 interface Props {
   disabled?: boolean;
   projectId: string;
+  // Batch 9: optional so callers that pre-date the agent picker still compile.
+  // When omitted, the toolbar row is hidden entirely.
+  agentId?: string | null;
+  onAgentChange?: (agentId: string | null) => void | Promise<void>;
   onSend: (content: string) => void | Promise<void>;
   onForceSend?: (content: string) => void | Promise<void>;
 }
 
-export function ChatInput({ disabled, projectId, onSend, onForceSend }: Props) {
+export function ChatInput({ disabled, projectId, agentId, onAgentChange, onSend, onForceSend }: Props) {
   const { isMobile } = useViewport();
   const [value, setValue] = useState('');
   const [busy, setBusy] = useState(false);
@@ -420,6 +425,18 @@ export function ChatInput({ disabled, projectId, onSend, onForceSend }: Props) {
           ))}
         </div>
       )}
+      {/* Batch 9 toolbar — agent picker. Sits above the input row so it
+          doesn't compete with the send button for vertical alignment.
+          When Batch 7 lands, ModelPicker and the + button join this row. */}
+      {onAgentChange && (
+        <div className="px-4 pt-2 flex items-center gap-1.5">
+          <AgentPicker
+            projectId={projectId}
+            value={agentId ?? null}
+            onChange={onAgentChange}
+          />
+        </div>
+      )}
       <div className="px-4 py-3 flex items-end gap-2">
         <Textarea
           ref={textareaRef}

apps/web/src/components/ChatTabBar.tsx

@@ -123,6 +123,10 @@ export function ChatTabBar({
               </div>
             </ContextMenuTrigger>
             <ContextMenuContent>
+              <ContextMenuItem onSelect={() => onNewChat()}>
+                New chat
+              </ContextMenuItem>
+              <ContextMenuSeparator />
               <ContextMenuItem onSelect={() => startRename(chat.id, chat.name)}>
                 Rename
               </ContextMenuItem>

apps/web/src/components/RightRail.tsx

@@ -4,8 +4,11 @@ import { api } from '@/api/client';
 import type { FileEntry } from '@/api/types';
 import { inferLanguage } from '@/lib/attachments';
 import { sessionEvents } from '@/hooks/sessionEvents';
+import { useRightRailDrawer } from '@/hooks/useRightRailDrawer';
+import { useViewport } from '@/hooks/useViewport';
 import { FileViewerOverlay } from '@/components/FileViewerOverlay';
 import { Input } from '@/components/ui/input';
+import { cn } from '@/lib/utils';
 
 interface Props {
   projectId: string;
@@ -25,6 +28,8 @@ function joinPath(parent: string, name: string): string {
 }
 
 export function RightRail({ projectId }: Props) {
+  const { isMobile } = useViewport();
+  const { open: drawerOpen, setOpen: setDrawerOpen } = useRightRailDrawer();
   const [open, setOpen] = useState(() => {
     try { return localStorage.getItem(`${STORAGE_KEY}.open`) !== 'false'; } catch { return true; }
   });
@@ -34,6 +39,19 @@ export function RightRail({ projectId }: Props) {
   const [fullFileList, setFullFileList] = useState<string[] | null>(null);
   const [viewerFile, setViewerFile] = useState<{ path: string; content: string } | null>(null);
 
+  // Combined open state: on mobile use the global drawer state (toggled by
+  // the Session header's FolderTree button); on desktop use the persistent
+  // internal state.
+  const isOpen = isMobile ? drawerOpen : open;
+  const closeRail = useCallback(() => {
+    if (isMobile) setDrawerOpen(false);
+    else setOpen(false);
+  }, [isMobile, setDrawerOpen]);
+  const openRail = useCallback(() => {
+    if (isMobile) setDrawerOpen(true);
+    else setOpen(true);
+  }, [isMobile, setDrawerOpen]);
+
   useEffect(() => {
     // best-effort; ignore failure because localStorage may be unavailable (quota, private mode)
     try { localStorage.setItem(`${STORAGE_KEY}.open`, String(open)); } catch {}
@@ -56,9 +74,9 @@ export function RightRail({ projectId }: Props) {
   }, [projectId]);
 
   useEffect(() => {
-    if (!open) return;
+    if (!isOpen) return;
     if (!cache.has('')) void loadDir('');
-  }, [open, cache, loadDir]);
+  }, [isOpen, cache, loadDir]);
 
   function toggleDir(dirPath: string) {
     setExpandedDirs((prev) => {
@@ -108,12 +126,14 @@ export function RightRail({ projectId }: Props) {
   useEffect(() => {
     return sessionEvents.subscribe((event) => {
       if (event.type !== 'open_file_in_browser') return;
-      if (!open) setOpen(true);
+      if (!isOpen) openRail();
       void openFile(event.path);
     });
-  }, [open, projectId]);
+  }, [isOpen, openRail, projectId]);
 
-  if (!open) {
+  // Desktop closed state: render the floating chevron handle. Mobile never
+  // shows the handle — the toggle lives in the Session header on mobile.
+  if (!isMobile && !open) {
     return (
       <button
         type="button"
@@ -128,15 +148,25 @@ export function RightRail({ projectId }: Props) {
 
   const rootEntries = cache.get('') ?? [];
 
+  // Mobile: render as fixed-position right-side drawer (always mounted so
+  // the transform transition can animate in/out). Desktop: inline aside.
+  const asideCls = isMobile
+    ? cn(
+        'fixed inset-y-0 right-0 z-40 w-[85vw] max-w-sm border-l bg-sidebar flex flex-col overflow-hidden',
+        'transition-transform duration-200 ease-out',
+        drawerOpen ? 'translate-x-0' : 'translate-x-full',
+      )
+    : 'w-64 shrink-0 border-l bg-sidebar flex flex-col h-full overflow-hidden';
+
   return (
     <>
-      <aside className="w-64 shrink-0 border-l bg-sidebar flex flex-col h-full overflow-hidden">
+      <aside className={asideCls}>
         <div className="flex items-center gap-2 px-3 py-2 border-b shrink-0">
           <span className="text-xs font-medium flex-1">Files</span>
           <button
             type="button"
-            onClick={() => setOpen(false)}
-            className="p-1 rounded hover:bg-muted text-muted-foreground"
+            onClick={closeRail}
+            className="p-1 rounded hover:bg-muted text-muted-foreground max-md:min-h-[44px] max-md:min-w-[44px]"
             aria-label="Close file browser"
           >
             <PanelRightClose size={14} />

apps/web/src/components/Workspace.tsx

@@ -20,9 +20,12 @@ import { cn } from '@/lib/utils';
 interface Props {
   sessionId: string;
   projectId: string;
+  // Batch 9: threaded down to ChatPane → ChatInput → AgentPicker.
+  agentId?: string | null;
+  onAgentChange?: (agentId: string | null) => void | Promise<void>;
 }
 
-export function Workspace({ sessionId, projectId }: Props) {
+export function Workspace({ sessionId, projectId, agentId, onAgentChange }: Props) {
   const {
     panes,
     activePaneIdx,
@@ -125,34 +128,36 @@ export function Workspace({ sessionId, projectId }: Props) {
 
   return (
     <div className="flex flex-col h-full min-h-0">
-      <div className="flex items-center gap-2 border-b border-border bg-muted/20 px-3 py-1.5 shrink-0">
-        <DropdownMenu>
-          <DropdownMenuTrigger asChild>
-            <button
-              type="button"
-              disabled={panes.length >= MAX_PANES}
-              className={cn(
-                'flex items-center gap-1 text-xs px-2 py-1 rounded hover:bg-muted max-md:min-h-[44px] max-md:px-3',
-                panes.length >= MAX_PANES && 'opacity-40 cursor-not-allowed hover:bg-transparent'
-              )}
-            >
-              <PanelRight size={14} />
-              Split
-            </button>
-          </DropdownMenuTrigger>
-          <DropdownMenuContent>
-            <DropdownMenuItem onSelect={() => addSplitPane('chat')}>
-              <MessageSquare size={14} /> Chat
-            </DropdownMenuItem>
-            <DropdownMenuItem onSelect={() => addSplitPane('terminal')}>
-              <Terminal size={14} /> Terminal
-            </DropdownMenuItem>
-            <DropdownMenuItem onSelect={() => addSplitPane('agent')}>
-              <Bot size={14} /> Agent
-            </DropdownMenuItem>
-          </DropdownMenuContent>
-        </DropdownMenu>
-      </div>
+      {!isMobile && (
+        <div className="flex items-center gap-2 border-b border-border bg-muted/20 px-3 py-1.5 shrink-0">
+          <DropdownMenu>
+            <DropdownMenuTrigger asChild>
+              <button
+                type="button"
+                disabled={panes.length >= MAX_PANES}
+                className={cn(
+                  'flex items-center gap-1 text-xs px-2 py-1 rounded hover:bg-muted',
+                  panes.length >= MAX_PANES && 'opacity-40 cursor-not-allowed hover:bg-transparent'
+                )}
+              >
+                <PanelRight size={14} />
+                Split
+              </button>
+            </DropdownMenuTrigger>
+            <DropdownMenuContent>
+              <DropdownMenuItem onSelect={() => addSplitPane('chat')}>
+                <MessageSquare size={14} /> Chat
+              </DropdownMenuItem>
+              <DropdownMenuItem onSelect={() => addSplitPane('terminal')}>
+                <Terminal size={14} /> Terminal
+              </DropdownMenuItem>
+              <DropdownMenuItem onSelect={() => addSplitPane('agent')}>
+                <Bot size={14} /> Agent
+              </DropdownMenuItem>
+            </DropdownMenuContent>
+          </DropdownMenu>
+        </div>
+      )}
 
       {isMobile && panes.length > 1 && (
         <div className="flex items-center gap-1 overflow-x-auto border-b border-border bg-muted/10 px-2 py-1 shrink-0">
@@ -217,7 +222,14 @@ export function Workspace({ sessionId, projectId }: Props) {
 
             <div className="flex-1 min-h-0 overflow-hidden">
               {pane.kind === 'chat' && pane.chatId ? (
-                <ChatPane sessionId={sessionId} chatId={pane.chatId} projectId={projectId} sessionChats={chats} />
+                <ChatPane
+                  sessionId={sessionId}
+                  chatId={pane.chatId}
+                  projectId={projectId}
+                  agentId={agentId}
+                  onAgentChange={onAgentChange}
+                  sessionChats={chats}
+                />
               ) : (
                 <SessionLandingPage
                   sessionId={sessionId}

apps/web/src/components/panes/ChatPane.tsx

@@ -18,10 +18,13 @@ interface Props {
   sessionId: string;
   chatId: string;
   projectId: string;
+  // Batch 9: optional, threaded down to ChatInput's agent picker.
+  agentId?: string | null;
+  onAgentChange?: (agentId: string | null) => void | Promise<void>;
   sessionChats?: import('@/api/types').Chat[];
 }
 
-export function ChatPane({ sessionId, chatId, projectId, sessionChats }: Props) {
+export function ChatPane({ sessionId, chatId, projectId, agentId, onAgentChange, sessionChats }: Props) {
   const stream = useSessionStream(sessionId);
   const lastErrorRef = useRef<string | null>(null);
   const [queue, setQueue] = useState<string[]>([]);
@@ -167,7 +170,14 @@ export function ChatPane({ sessionId, chatId, projectId, sessionChats }: Props)
 
       <div className="relative">
         <ChatContextPopover stats={contextStats} />
-        <ChatInput disabled={false} projectId={projectId} onSend={handleSend} onForceSend={streaming ? handleForceSend : undefined} />
+        <ChatInput
+          disabled={false}
+          projectId={projectId}
+          agentId={agentId}
+          onAgentChange={onAgentChange}
+          onSend={handleSend}
+          onForceSend={streaming ? handleForceSend : undefined}
+        />
       </div>
     </div>
   );

apps/web/src/hooks/useRightRailDrawer.tsx

@@ -0,0 +1,35 @@
+import { createContext, useCallback, useContext, useEffect, useState } from 'react';
+import type { ReactNode } from 'react';
+import { useLocation } from 'react-router-dom';
+
+interface RightRailDrawerState {
+  open: boolean;
+  setOpen: (open: boolean) => void;
+  toggle: () => void;
+}
+
+const Ctx = createContext<RightRailDrawerState | null>(null);
+
+export function RightRailDrawerProvider({ children }: { children: ReactNode }) {
+  const [open, setOpen] = useState(false);
+  const location = useLocation();
+
+  // Auto-close on route change. Same pattern as useSidebarDrawer — keeps the
+  // drawer from leaking between sessions when the user navigates.
+  useEffect(() => {
+    setOpen(false);
+  }, [location.pathname]);
+
+  const toggle = useCallback(() => setOpen((v) => !v), []);
+
+  return <Ctx.Provider value={{ open, setOpen, toggle }}>{children}</Ctx.Provider>;
+}
+
+export function useRightRailDrawer(): RightRailDrawerState {
+  const ctx = useContext(Ctx);
+  if (!ctx) {
+    // Soft fallback so consumers don't crash if rendered outside a provider.
+    return { open: false, setOpen: () => {}, toggle: () => {} };
+  }
+  return ctx;
+}

apps/web/src/pages/Home.tsx

@@ -1,5 +1,5 @@
 import { useEffect, useState } from 'react';
-import { ChevronDown, ChevronRight, Folder, RotateCcw } from 'lucide-react';
+import { ChevronDown, ChevronRight, Folder, FolderTree, Menu, RotateCcw } from 'lucide-react';
 import { toast } from 'sonner';
 import { Button } from '@/components/ui/button';
 import { AddProjectModal } from '@/components/AddProjectModal';
@@ -8,6 +8,9 @@ import { api } from '@/api/client';
 import type { Project } from '@/api/types';
 import { sessionEvents } from '@/hooks/sessionEvents';
 import { useSidebar } from '@/hooks/useSidebar';
+import { useSidebarDrawer } from '@/hooks/useSidebarDrawer';
+import { useRightRailDrawer } from '@/hooks/useRightRailDrawer';
+import { useViewport } from '@/hooks/useViewport';
 
 export function Home() {
   const { data } = useSidebar();
@@ -15,6 +18,9 @@ export function Home() {
   const [createOpen, setCreateOpen] = useState(false);
   const [archived, setArchived] = useState<Project[] | null>(null);
   const [showArchived, setShowArchived] = useState(false);
+  const { setOpen: setSidebarOpen } = useSidebarDrawer();
+  const { toggle: toggleRightRail } = useRightRailDrawer();
+  const { isMobile } = useViewport();
 
   const empty = data ? data.projects.length === 0 : false;
 
@@ -70,8 +76,32 @@ export function Home() {
   }
 
   return (
-    <div className="flex-1 flex flex-col items-center px-6 py-12 overflow-y-auto">
-      <div className="w-full max-w-md space-y-6">
+    <div className="flex-1 flex flex-col min-h-0">
+      {isMobile && (
+        <header
+          className="border-b px-3 sm:px-4 py-2 flex items-center gap-1.5 shrink-0 text-sm"
+          style={{ paddingTop: 'max(0.5rem, env(safe-area-inset-top))' }}
+        >
+          <button
+            type="button"
+            onClick={() => setSidebarOpen(true)}
+            className="inline-flex items-center justify-center -ml-1 min-w-[44px] min-h-[44px] rounded text-muted-foreground hover:bg-muted hover:text-foreground shrink-0"
+            aria-label="Open sidebar"
+          >
+            <Menu className="size-5" />
+          </button>
+          <button
+            type="button"
+            onClick={toggleRightRail}
+            className="inline-flex items-center justify-center -mr-1 ml-auto min-w-[44px] min-h-[44px] rounded text-muted-foreground hover:bg-muted hover:text-foreground shrink-0"
+            aria-label="Toggle file browser"
+          >
+            <FolderTree className="size-5" />
+          </button>
+        </header>
+      )}
+      <div className="flex-1 flex flex-col items-center px-6 py-12 overflow-y-auto">
+        <div className="w-full max-w-md space-y-6">
         <div className="text-center space-y-3">
           {empty ? (
             <>
@@ -127,9 +157,10 @@ export function Home() {
             )}
           </div>
         )}
+        </div>
+        <AddProjectModal open={addOpen} onOpenChange={setAddOpen} onAdded={() => {}} />
+        <CreateProjectModal open={createOpen} onOpenChange={setCreateOpen} />
       </div>
-      <AddProjectModal open={addOpen} onOpenChange={setAddOpen} onAdded={() => {}} />
-      <CreateProjectModal open={createOpen} onOpenChange={setCreateOpen} />
     </div>
   );
 }

apps/web/src/pages/Project.tsx

@@ -81,32 +81,32 @@ export function Project() {
   return (
     <div className="flex-1 flex flex-col">
       <header
-        className="border-b px-6 py-3 flex items-center justify-between gap-2"
-        style={{ paddingTop: 'max(0.75rem, env(safe-area-inset-top))' }}
+        className="border-b px-3 sm:px-6 py-2 sm:py-3 flex items-center justify-between gap-2"
+        style={{ paddingTop: 'max(0.5rem, env(safe-area-inset-top))' }}
       >
         <div className="flex items-center gap-2 min-w-0">
           {isMobile && (
             <button
               type="button"
               onClick={() => setDrawerOpen(true)}
-              className="inline-flex items-center justify-center -ml-2 min-w-[44px] min-h-[44px] rounded text-muted-foreground hover:bg-muted hover:text-foreground shrink-0"
+              className="inline-flex items-center justify-center -ml-1 min-w-[44px] min-h-[44px] rounded text-muted-foreground hover:bg-muted hover:text-foreground shrink-0"
               aria-label="Open sidebar"
             >
               <Menu className="size-5" />
             </button>
           )}
           <div className="min-w-0">
-            <h1 className="text-lg font-semibold tracking-tight truncate">
+            <h1 className="text-base sm:text-lg font-semibold tracking-tight truncate">
               {project?.name ?? '…'}
             </h1>
-            <div className="text-xs text-muted-foreground font-mono truncate">
+            <div className="text-xs text-muted-foreground font-mono truncate hidden sm:block">
               {project?.path}
             </div>
           </div>
         </div>
-        <Button onClick={handleNew} disabled={creating} className="shrink-0">
+        <Button onClick={handleNew} disabled={creating} className="shrink-0" aria-label="New session">
           <Plus />
-          New session
+          <span className="hidden sm:inline">New session</span>
         </Button>
       </header>
 

apps/web/src/pages/Session.tsx

@@ -1,11 +1,12 @@
 import { useEffect, useState } from 'react';
 import { Link, useNavigate, useParams } from 'react-router-dom';
-import { ChevronRight, Menu } from 'lucide-react';
+import { ChevronRight, FolderTree, Menu } from 'lucide-react';
 import { api } from '@/api/client';
 import type { Project, Session as SessionType } from '@/api/types';
 import { sessionEvents } from '@/hooks/sessionEvents';
 import { useActivePane } from '@/hooks/useActivePane';
 import { useSidebarDrawer } from '@/hooks/useSidebarDrawer';
+import { useRightRailDrawer } from '@/hooks/useRightRailDrawer';
 import { useViewport } from '@/hooks/useViewport';
 import { Workspace } from '@/components/Workspace';
 import { ModelPicker } from '@/components/ModelPicker';
@@ -19,6 +20,7 @@ export function Session() {
   const [editingName, setEditingName] = useState(false);
   const active = useActivePane();
   const { setOpen: setDrawerOpen } = useSidebarDrawer();
+  const { toggle: toggleRightRail } = useRightRailDrawer();
   const { isMobile } = useViewport();
 
   useEffect(() => {
@@ -87,33 +89,42 @@ export function Session() {
 
   return (
     <div className="flex-1 flex flex-col min-h-0">
-      <header className="border-b px-4 py-2 flex items-center gap-1.5 shrink-0 text-sm" style={{ paddingTop: 'max(0.5rem, env(safe-area-inset-top))' }}>
+      <header
+        className="border-b px-3 sm:px-4 py-2 flex items-center gap-1.5 shrink-0 text-sm"
+        style={{ paddingTop: 'max(0.5rem, env(safe-area-inset-top))' }}
+      >
         {isMobile && (
           <button
             type="button"
             onClick={() => setDrawerOpen(true)}
-            className="inline-flex items-center justify-center -ml-1 mr-1 min-w-[44px] min-h-[44px] rounded text-muted-foreground hover:bg-muted hover:text-foreground"
+            className="inline-flex items-center justify-center -ml-1 min-w-[44px] min-h-[44px] rounded text-muted-foreground hover:bg-muted hover:text-foreground shrink-0"
             aria-label="Open sidebar"
           >
             <Menu className="size-5" />
           </button>
         )}
-        <Link to="/" className="text-muted-foreground hover:text-foreground">
-          Projects
-        </Link>
-        <ChevronRight className="size-3 text-muted-foreground/60" />
-        {project ? (
-          <Link
-            to={`/project/${project.id}`}
-            className="text-muted-foreground hover:text-foreground truncate max-w-[200px]"
-            title={project.name}
-          >
-            {project.name}
+
+        {/* Breadcrumb — desktop only */}
+        <div className="hidden sm:flex items-center gap-1.5 min-w-0">
+          <Link to="/" className="text-muted-foreground hover:text-foreground shrink-0 text-xs">
+            Projects
           </Link>
-        ) : (
-          <span className="text-muted-foreground/60">…</span>
-        )}
-        <ChevronRight className="size-3 text-muted-foreground/60" />
+          <ChevronRight className="size-3 text-muted-foreground/60 shrink-0" />
+          {project ? (
+            <Link
+              to={`/project/${project.id}`}
+              className="text-muted-foreground hover:text-foreground truncate max-w-[200px]"
+              title={project.name}
+            >
+              {project.name}
+            </Link>
+          ) : (
+            <span className="text-muted-foreground/60">…</span>
+          )}
+          <ChevronRight className="size-3 text-muted-foreground/60 shrink-0" />
+        </div>
+
+        {/* Session name — always visible, truncated, editable */}
         {editingName ? (
           <input
             autoFocus
@@ -127,30 +138,34 @@ export function Session() {
                 setEditingName(false);
               }
             }}
-            className="bg-transparent border-b border-border px-1 py-0.5 text-sm font-medium outline-none focus:border-ring"
+            className="bg-transparent border-b border-border px-1 py-0.5 text-sm font-medium outline-none focus:border-ring min-w-0"
           />
         ) : (
           <button
             type="button"
-            className="text-sm font-medium hover:underline truncate max-w-[280px]"
+            className="text-sm font-medium hover:underline truncate max-w-[140px] sm:max-w-[280px] min-w-0"
             onClick={() => setEditingName(true)}
             title={session?.name ?? ''}
           >
             {session?.name ?? '…'}
           </button>
         )}
+
+        {/* Active file — desktop only */}
         {showActiveFile && active.activeFile && (
           <>
-            <span className="text-muted-foreground/40 mx-1">·</span>
+            <span className="text-muted-foreground/40 mx-1 hidden sm:inline">·</span>
             <span
-              className="text-xs font-mono text-muted-foreground truncate max-w-[320px]"
+              className="text-xs font-mono text-muted-foreground truncate max-w-[200px] hidden sm:inline"
               title={active.activeFile}
             >
               {active.activeFile}
             </span>
           </>
         )}
-        <div className="ml-auto">
+
+        {/* Model picker — right-aligned */}
+        <div className="ml-auto shrink-0">
           {session && (
             <div className="inline-flex items-center rounded-full bg-muted/40 hover:bg-muted/70 px-1">
               <ModelPicker
@@ -163,10 +178,30 @@ export function Session() {
             </div>
           )}
         </div>
+
+        {/* File browser toggle — mobile only */}
+        {isMobile && (
+          <button
+            type="button"
+            onClick={toggleRightRail}
+            className="inline-flex items-center justify-center -mr-1 min-w-[44px] min-h-[44px] rounded text-muted-foreground hover:bg-muted hover:text-foreground shrink-0"
+            aria-label="Toggle file browser"
+          >
+            <FolderTree className="size-5" />
+          </button>
+        )}
       </header>
 
       {id && session && (
-        <Workspace sessionId={id} projectId={session.project_id} />
+        <Workspace
+          sessionId={id}
+          projectId={session.project_id}
+          agentId={session.agent_id}
+          onAgentChange={async (agent_id) => {
+            const updated = await api.sessions.update(session.id, { agent_id });
+            setSession(updated);
+          }}
+        />
       )}
     </div>
   );

boocode_roadmap.md

@@ -27,8 +27,9 @@ Live at `https://code.indifferentketchup.com` (Caddy → Authelia → Tailscale
 |v1.4            |Fork from message + delete message + header polish + housekeeping                                                                      |✅ Merged                         |Was original “Batch 5”                   |
 |v1.5            |Refactor splits, vitest harness (23 tests), error-log surfacing, `/opt:ro` + `BOOTSTRAP_ROOT`, persistent context-window tracker       |✅ Merged                         |—                                        |
 |v1.5.1          |Bootstrap hotfix: git in container, SSH keypair, known_hosts, SSH URL rewrite, /opt/projects label                                     |✅ Merged                         |`4a9f207`                                |
-|v1.6-mobile-pass|Mobile pass: drawer, pane stacking, long-press, swipe-to-close, pull-to-refresh, IME safety, safe-area, tap targets + H1 path-guard fix|🔄 Hand-back received, uncommitted|Was original “Batch 4”                   |
-|v1.6.1-cleanup  |Stale code audit, overengineering audit, secrets hygiene, RightRail mobile fix                                                         |Planned (next)                   |—                                        |
+|v1.6-mobile-pass|Mobile pass: drawer, pane stacking, long-press, swipe-to-close, pull-to-refresh, IME safety, safe-area, tap targets + H1 path-guard fix|✅ Merged                         |`57c883b..943ae7d` (6 commits)           |
+|v1.6.1-cleanup  |Mostly audit-only; one fix shipped: RightRail `max-md:hidden` wrapper. Audit reports for secrets, stale code, panes, mount scope, hand-rolled patterns deferred to follow-ups |✅ Merged                         |`6a9fe18`                                |
+|v1.6.2-mobile-ui-fixes|Mobile UI polish from device testing: kill single-pane navigator chrome, header rework, “New chat” in long-press menu, RightRail as mobile drawer (reverts v1.6.1 wrapper) |🔄 Hand-back received, uncommitted|—                                        |
 |v1.7            |Drag-drop + paste-as-attachment (chip infra extension)                                                                                 |Planned                          |Was Batch 6                              |
 |v1.8            |Settings drawer (system prompt per project + session, web search toggle)                                                               |Planned                          |Was Batch 7                              |
 |v1.9            |Web search backend: SearXNG `web_search` + `web_fetch` tools                                                                           |Planned                          |Was Batch 8                              |
@@ -139,15 +140,16 @@ Dockerfile (git installed in container), docker-compose.yml, project_bootstrap.t
 
 -----
 
-### v1.6-mobile-pass 🔄
+### v1.6-mobile-pass ✅
 
-**Hand-back received, uncommitted on `v1.6-mobile-pass`.** 5-commit sequence proposed:
+**Merged via 6 commits `57c883b..943ae7d`** (5 functional + 1 docs):
 
-1. `chore: fix resolveProjectPath whitelist-root bypass` (H1 — dropped `real !== whitelistReal` short-circuit; 23/23 pass).
-1. `feat(mobile): viewport hook + sidebar drawer + hamburger headers` (M1 + M2 + M6-header).
-1. `feat(mobile): single-pane stack + long-press tab menu + swipe-to-close` (M3 + M4 + A2).
-1. `feat(mobile): chat input keybinds + safe-area + tap targets + overflow safety` (M5 + M6-bottom + M7 + M8).
-1. `feat(mobile): pull-to-refresh sidebar list` (A1).
+1. `57c883b chore: fix resolveProjectPath whitelist-root bypass` (H1 — dropped `real !== whitelistReal` short-circuit; flipped the v1.5 BEHAVIOR GAP test; 23/23 pass).
+1. `a643b5f feat(mobile): viewport hook + sidebar drawer + hamburger headers` (M1 + M2 + M6-header).
+1. `cd897d6 feat(mobile): single-pane stack + long-press tab menu + swipe-to-close` (M3 + M4 + A2).
+1. `273eeac feat(mobile): chat input keybinds + safe-area + tap targets + overflow safety` (M5 + M6-bottom + M7 + M8).
+1. `4b5b9b2 feat(mobile): pull-to-refresh sidebar list` (A1).
+1. `943ae7d docs: add v1.x roadmap snapshot` (this file).
 
 **Decisions:**
 
@@ -168,21 +170,41 @@ Dockerfile (git installed in container), docker-compose.yml, project_bootstrap.t
 
 -----
 
-### v1.6.1-cleanup — Stale + overengineering audit + secrets hygiene (next)
+### v1.6.1-cleanup ✅ (`6a9fe18`)
 
-**Depends on:** v1.6 committed.
+**Shipped:** RightRail wrapped in `<div className="max-md:hidden contents">` so it's hidden entirely below the md breakpoint on mobile. (Note: v1.6.2 reverses this and replaces with a proper mobile drawer — see below.)
 
-**Scope:**
+**Audited but not shipped (queued for follow-ups):**
 
-1. RightRail mobile fix (`max-md:hidden` on outer container).
-1. Secrets audit: rotate `secrets/boocode_gitea`, confirm `.gitignore` covers `secrets/`, scan git history (`git log --all -- secrets/`), `git filter-repo` or BFG if exposed in history, force-push if rewriting.
-1. Fix agent SSH key path so future Claude Code dispatches don’t fall back to in-repo keys.
-1. Stale code audit: pruning unused exports, dead WS frames (e.g. `session_renamed` server publisher TODO from Batch 1), backup `.bak` files, unused imports.
-1. Overengineering audit: places where hand-rolled patterns are more complex than necessary, places where singleton hooks should consolidate (`useSessionStream` refcount).
-1. PATCH `/api/panes/:id` session-ownership check tightening.
-1. `/opt:/opt:ro` mount whitelist tightening (precursor to BooCoder).
+- **Secrets hygiene:** `secrets/boocode_gitea` is NOT tracked; never committed to any branch; `.gitignore` already covers `secrets/`. Rotation is a Gitea-side action, no repo change needed.
+- **`.bak` files:** 3 leftover from v1.5.1 (`docker-compose.yml.bak-20260516`, `Dockerfile.bak-20260516`, `apps/web/src/components/CreateProjectModal.tsx.bak-20260516`). Git-invisible via global `~/.gitignore_global` (`*.bak*`). Decide per file.
+- **Unused exports:** neither `knip` nor `ts-prune` installed. Proposal pending.
+- **Dead WS frames:** `session_renamed` HAS a server publisher (`routes/sessions.ts:140`, added in v1.4) — the roadmap's "no server publisher" open item is **STALE**, crossed off. The `InferenceFrame` union still declares `session_renamed` as a type variant but no code publishes it on the per-session channel; trivial 1-line cleanup deferred.
+- **Unused imports:** web `tsc --noUnusedLocals --noUnusedParameters` returns 0 warnings.
+- **`useSessionStream` refcount:** opportunity confirmed (~90 lines diff to apply the `useSidebar`-style module-scope singleton pattern). Risk LOW. Queued for v1.6.2 or later.
+- **PATCH `/api/panes/:id` ownership:** **MOOT** — endpoint does not exist (the pane REST API was never re-introduced after pane state moved to client-side localStorage in v1.2). Crossed off open items.
+- **Hand-rolled patterns vs library:** 5 hand-rolled hooks/components total 336 lines. None duplicates anything in existing deps; library swap (`@use-gesture`, `react-pull-to-refresh`) not worth the dep cost yet.
+- **`/opt:/opt:ro` mount tightening:** Two-option plan documented for v1.6.2 — Option A (per-project bind-mounts) or Option B (deny `.env` pattern in `pathGuard`). Option B is the simpler short-term fix.
 
-**No new features. No schema changes.**
+-----
+
+### v1.6.2-mobile-ui-fixes 🔄
+
+**Hand-back received, uncommitted on `v1.6.2-mobile-ui-fixes`.** 4-commit sequence proposed:
+
+1. `fix(mobile): hide Split button + single-pane navigator chrome` (G1 — wrap the Workspace Split row in `!isMobile`).
+1. `feat(mobile): rework Session and Project headers for narrow viewports` (G2 — breadcrumb `hidden sm:flex`, session name cap `max-w-[140px] sm:max-w-[280px]`, project page heading `text-base sm:text-lg`, “New session” icon-only on mobile).
+1. `feat(mobile): add "New chat" to tab long-press context menu` (G3 — top of menu, separator, then existing items).
+1. `feat(mobile): right-rail as drawer on mobile, header toggle button` (G4 option b — new `useRightRailDrawer` Context hook, `RightRail` renders as fixed `w-[85vw] max-w-sm` drawer on mobile, FolderTree button in Session header, **reverts v1.6.1's `max-md:hidden` wrapper**).
+
+**Decisions:**
+
+- G4 option b chosen: mobile file browsing IS useful; drawer pattern mirrors `useSidebarDrawer`.
+- G2 single-row session-name+model layout (model picker right-aligned), per spec example.
+- G3 "New chat" at top, separator, then Rename.
+- G2 "New session" button: icon-only on mobile via `<span className="hidden sm:inline">New session</span>`.
+
+**Adjacent uncommitted change (not part of v1.6.2):** `MAX_TOOL_LOOP_DEPTH 5 → 15` in `apps/server/src/services/inference.ts`. Sam-authored, sitting in working tree on `v1.6.2-mobile-ui-fixes`. **NOT on main as of this update.** Commit separately.
 
 -----
 
@@ -407,14 +429,17 @@ settings
 
 ## Known open items
 
-- **`useSessionStream` refcount.** Two ChatPanes = two WS. Apply singleton pattern. Tracked in v1.6.1.
-- **PATCH `/api/panes/:id` lacks session-ownership check.** Single-user fine; tighten in v1.6.1.
-- **`/opt:/opt:ro` mount exposes all `.env` files.** Whitelist scope before BooCoder. Tracked in v1.6.1.
-- **`session_renamed` no server WS publisher.** Carried from Batch 2. Tracked in v1.6.1.
-- **`secrets/boocode_gitea` in repo.** v1.5.1 dispatch fallback. Rotation + history scrub in v1.6.1.
+- **`useSessionStream` refcount.** Two ChatPanes = two WS. Apply singleton pattern. Audited in v1.6.1, queued.
+- **`/opt:/opt:ro` mount exposes all `.env` files.** Whitelist scope before BooCoder. Two-option plan documented in v1.6.1 audit; ship in v1.6.2 or v1.7.
+- **`secrets/boocode_gitea` in repo working tree.** Never committed (git-invisible via global ignore). Rotate the Gitea-side key when convenient; no repo action required.
 - **Dormant in-boolab BooCode mode.** Reference only.
 - **BooCoder container.** Post-v1.x.
 
+**Closed since last update:**
+
+- ~~`session_renamed` no server WS publisher~~ — server publishes via `broker.publishUser` from `routes/sessions.ts:140` (added in v1.4). Confirmed in v1.6.1 audit.
+- ~~PATCH `/api/panes/:id` lacks session-ownership check~~ — endpoint does not exist; the pane REST API was never re-introduced after v1.2 moved pane state to localStorage.
+
 -----
 
 ## Dependency graph
@@ -456,7 +481,10 @@ v1.5.1 (bootstrap hotfix)    │
 v1.6-mobile-pass             │
   │                          │
   ▼                          │
-v1.6.1-cleanup ◄─────────────┘
+v1.6.1-cleanup               │
+  │                          │
+  ▼                          │
+v1.6.2-mobile-ui-fixes ◄─────┘
   │
   ▼
 v1.7 (drag-drop) ◄── v1.1-batch3.5