@open-mercato/cezar 0.9.1 → 0.9.2-pr710.1256

package/dist/server/server.js

@@ -1,4 +1,11 @@
 import { existsSync, readFileSync, statSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { AutomationStore } from '../automations/store.js';
+import { AutomationCoordinator } from '../automations/coordinator.js';
+import { GithubPoller } from '../automations/github-poller.js';
+import { ProjectAutomationScheduler, WorkspaceAutomationScheduler } from '../automations/scheduler.js';
+import { launchAutomationRun, reconcileAutomationReceipts, validateAutomationPrompt } from '../automations/task-template.js';
+import { automationEventSchema, automationFiltersSchema, automationLogResultSchema, automationTaskSchema, } from '../automations/types.js';
 import { access, constants as fsConstants, mkdir, readFile, realpath, stat, unlink, writeFile } from 'node:fs/promises';
 import { basename, dirname, join, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -6,67 +13,191 @@ import { Hono } from 'hono';
 import { serve } from '@hono/node-server';
 import { bodyLimit } from 'hono/body-limit';
 import { streamSSE } from 'hono/streaming';
+import { jsonZodValidator, paramZodValidator, queryZodValidator } from './validators.js';
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
 import { z } from 'zod';
+import { setWorkspaceUiStateInputSchema, } from '../contract/index.js';
+// A contract VALUE, like `workspaceUiStateSchema` in workspace/migrations.ts — the request
+// schema this route validates with is the same one the client compiles against.
+import { modelDiscoveryRunnerSchema, openProjectInSchema, updateProjectInputSchema, } from '../contract/index.js';
 import { detectEnvironment } from '../core/backend-detect.js';
+import { RUNNER_IDS } from '../core/agent-runner.js';
+import { AGENT_MODELS_LOCKED_ERROR, agentModelsLocked } from '../core/agent-model-policy.js';
 import { discoverCodexModels } from '../core/codex-model-catalog.js';
+import { discoverOpencodeModels } from '../core/opencode-model-catalog.js';
+import { PROVIDER_IDS, ProviderAuthService, providerAuthChecksDisabled, } from '../core/provider-auth.js';
+import { applyProviderEnablement } from '../core/provider-availability.js';
 import { RunnerModelCatalog } from '../core/runner-model-catalog.js';
 import { currentUsage, onUsage } from '../core/process-usage.js';
 import { WORKFLOWS_DIR, loadWorkflows } from '../workflows/load.js';
 import { QUICK_TASK_WORKFLOW, normalizeWorkflowDoc, skillStackOf, skillsToSteps, stepsIssue, workflowFileSchema, workflowStepSchema, } from '../workflows/types.js';
 import { planChain, slugify } from '../planner.js';
 import { discoverSkills } from '../skills.js';
+import { SkillsUpdateConflictError, SkillsUpdateCoordinator, SkillsUpdateService } from '../skills-update.js';
 import { getTeamSkillsCached, refreshTeamSkills, waitForTeamSkills } from '../skills-remote.js';
 import { appendHandoffHeartbeat, handoffProgressExcerpt, readHandoff } from '../handoff.js';
 import { markStarted, onTodosChanged, readTodos, removeTodo, todoTaskText } from '../todos.js';
+import { HistoryCursorError, deriveRunContextEvents, readEventsAfterLiveCursor, readRunHistoryPage, validateLiveCursor, } from '../runs/event-history.js';
+import { readRunIndexFromDisk } from '../runs/run-index.js';
 import { isV2WireEventType } from '../runs/ui-event-sink.js';
+import { runEventsQuerySchema, runHistoryQuerySchema, runIdParamSchema, } from '../contract/index.js';
 import { removeWorktree, worktreeDiff, worktreeDiffStat, worktreeSizeBytes } from '../git-worktree.js';
 import { isReclaimable, reclaimWorktrees } from '../runs/retention.js';
 import { getBranches, getCommit, getDiff, getLog, getRepoInfo, getStatus } from './git.js';
 import { collectChanges, collectCommitChanges, collectRunCommits, commitAll, createOrSwitchBranch, imageMimeType, isOsOpenableImage, pushCurrentBranch, readWorktreePath, } from './git-changes.js';
 import { gatedSkillsRepos, loadConfig, resolveWorktreeRetention } from '../config.js';
 import { findConfigFile } from '../agent-config/catalog.js';
-import { readConfigFile, writeConfigFile } from '../agent-config/files.js';
+import { readConfigFile, statConfigPath, writeConfigFile } from '../agent-config/files.js';
+import { readAgentModelDefaults } from '../agent-config/models.js';
 import { listAgentConfig } from '../agent-config/service.js';
-import { PROJECT_ID_RE, defaultWorkspaceConfig, loadWorkspaceConfig, mergeWriteWorkspaceConfig, } from '../workspace/config.js';
-import { allocateProjectSlug, listProjects, probeProjectStatus, registerProject, removeProject, shouldRegisterProject, } from '../workspace/projects.js';
+import { listConfigFiles } from '../agent-config/catalog.js';
+import { readAccountIdentity } from '../agent-config/account-identity.js';
+import { PROJECT_ID_RE, defaultWorkspaceConfig, effectiveSkillsAutoUpdate, loadWorkspaceConfig, mergeWriteWorkspaceConfig, effectiveComposerDefault, } from '../workspace/config.js';
+import { CONTROL_CHARS_RE, DEFAULT_AGENT_ACCOUNT_ID, defaultAgentAccountStore, isAbsoluteConfigDir, loadAgentAccounts, mergeWriteAgentAccounts, } from '../workspace/agent-accounts.js';
+import { defaultAgentProfile, listAgentProfiles, profileDirState, resolveProfileEnvForRoot, resolveStoredProfile, sameProfileDir, } from '../workspace/agent-profiles.js';
+import { PROFILE_CAPABLE_PROVIDERS, profileEnv, supportsProfiles } from '../core/agent-profiles.js';
+import { withEnvPrefix } from '../core/shell-env.js';
+import { allocateProjectSlug, listProjects, normalizeProjectTags, probeProjectStatus, registerProject, removeProject, shouldRegisterProject, } from '../workspace/projects.js';
 import { mergeWriteWorkspaceUiState, readWorkspaceUiState } from '../workspace/ui-state.js';
 import { checkoutRepo } from './checkout.js';
 import { ProjectContextError, ProjectContexts } from './project-context.js';
 import { reviewGateEnabled } from '../runs/review-gate.js';
 import { readUiState, uiStatePath } from '../ui-state.js';
-import { expandTilde } from '../paths.js';
+import { agentHomePaths, expandTilde } from '../paths.js';
 import { isLoopbackHostHeader, normalizeHostname, resolveCapabilities } from './capabilities.js';
 import { createSocketHub } from './ws.js';
 import { browseDirectory, isInsideBrowseRoot, isLexicallyInsideBrowseRoot, resolveBrowseRoot } from './fs-browse.js';
-import { resolveForge } from './forge/index.js';
-import { fetchGithub, fetchGithubComments } from './github.js';
+import { parseRemote, resolveForge } from './forge/index.js';
+import { fetchGithub, fetchGithubChecks, fetchGithubComments, fetchGithubPrDiff, GithubPrNotFoundError, GH_CHECKS_MAX } from './github.js';
 import { ensureLaunchKey } from './launch-key.js';
 import { openInTerminal } from './open-in-terminal.js';
 import { agentCliRunner, detectOpenTargets, openFileInDefaultApp, openInApp } from './open-in-app.js';
 import { createDraftPr } from './pr.js';
+import { ProviderRuntimeAuthObserver } from './provider-auth-runtime.js';
+import { providerForActiveRun, providerForExistingRun, providersRequiredByWorkflow, unavailableProviderMessage, } from './provider-action-gate.js';
 import { ASSET_CACHE_CONTROL, BUILD_HINT_HTML, assetContentType, isSafeAssetFilename, resolveGetRequest, } from './static-ui.js';
 /** `projectId` gate at the route boundary (spec "Project identity"): the slug
  *  shape or the reserved `default` alias — validated BEFORE touching any map
  *  or path. (`default` matches the slug regex too; the literal keeps the
  *  contract explicit.) */
 const projectIdSchema = z.union([z.literal('default'), z.string().regex(PROJECT_ID_RE)]);
-const SCOPED_PREFIX = '/api/p/:projectId';
+const providerConnectSchema = z.object({
+    provider: z.enum(PROVIDER_IDS),
+    /** Which agent account to sign in (spec 2026-07-29-agent-profiles). Absent = the discovered
+     *  default, which is what every pre-profiles client sends. Without this, "Connect" on a second
+     *  Claude account would open a login for the FIRST one and report success. */
+    profileId: z.string().max(64).optional(),
+}).strict();
+/** Agent-account bodies (spec 2026-07-29-agent-profiles). Bounds mirror `agentProfileSchema` in
+ *  src/workspace/config.ts exactly, so a value these accept can never be degraded away by the
+ *  next load's `.catch`. The id is allocated server-side and is never a request field. */
+const createAgentProfileSchema = z.object({
+    provider: z.enum(PROVIDER_IDS),
+    label: z.string().trim().max(200).optional(),
+    configDir: z.string().trim().min(1).max(4096),
+}).strict();
+/** `POST …/agent-profiles/:id/open` — a catalog id (or `folder`) plus an optional open target. */
+const openAgentAccountFileSchema = z.object({
+    file: z.string().min(1).max(200),
+    target: z.string().min(1).max(64).optional(),
+}).strict();
+const updateAgentProfileSchema = z.object({
+    label: z.string().trim().max(200).optional(),
+    configDir: z.string().trim().min(1).max(4096).optional(),
+}).strict().refine((value) => value.label !== undefined || value.configDir !== undefined, 'send label or configDir');
+/** `PUT …/agent-profiles/selection` — which account a project uses for one provider. `null`
+ *  clears it back to the discovered account. */
+const selectAgentProfileSchema = z.object({
+    /** `null` targets the machine-wide default rather than one repo. */
+    projectId: z.string().min(1).max(64).nullable(),
+    provider: z.enum(PROVIDER_IDS),
+    profileId: z.string().max(64).nullable(),
+}).strict();
+/** The hosted-mode refusal, worded like the agent-config one it mirrors. */
+const hostedProfileRefusal = {
+    error: 'agent accounts are managed from the machine that owns the checkout (this cockpit runs in hosted mode)',
+};
+/**
+ * Allocate a profile id from the label (or, with no label, the folder name).
+ *
+ * Reuses the project allocator's shape, and deliberately its reserved set too: `default` is the
+ * discovered profile here exactly as it is the boot alias there, so a folder called `default/`
+ * becomes `default-2` and can never shadow it.
+ */
+function allocateAgentProfileId(source, taken) {
+    // `allocateProjectSlug` already basenames its argument and enforces the shared
+    // `^[a-z0-9][a-z0-9-]{0,63}$` shape, so `~/.claude-klaudiusz` slugs to `claude-klaudiusz`.
+    return allocateProjectSlug(source, taken);
+}
+const providerParamSchema = z.enum(PROVIDER_IDS);
+const providerEnabledSchema = z.object({ enabled: z.boolean() }).strict();
+const providerRetrySchema = z.object({
+    authFailureId: z.string().min(1).max(128),
+}).strict();
+const automationEditableSchema = z
+    .object({
+    name: z.string().trim().min(1).max(200),
+    description: z.string().max(2_000).optional(),
+    enabled: z.boolean().optional(),
+    events: z.array(automationEventSchema).min(1).max(4),
+    intervalSeconds: z.number().int().min(60).max(86_400),
+    filters: automationFiltersSchema,
+    task: automationTaskSchema,
+})
+    .strict();
+const automationCreateSchema = automationEditableSchema.extend({ enable: z.boolean().optional() });
+const automationUpdateSchema = automationEditableSchema.extend({ expectedRevision: z.number().int().positive() });
+const automationCheckRequestSchema = z.object({ mode: z.enum(['preview', 'execute']) }).strict();
+const automationLogQuerySchema = z.object({
+    automationId: z.string().optional(),
+    result: automationLogResultSchema.optional(),
+    event: automationEventSchema.optional(),
+    since: z.string().datetime().optional(),
+    cursor: z.coerce.number().int().positive().optional(),
+    // Optional, not `.default(100)`: `AutomationStore.logs` already clamps `limit ?? 100` into
+    // 1..100, so the default here was a second copy of it — and a defaulted key is REQUIRED in the
+    // request type `queryZodValidator` publishes (see validators.ts on why the request side falls
+    // back to the schema's output), which would have made every caller send a `?limit=` this route
+    // never needed.
+    limit: z.coerce.number().int().min(1).max(100).optional(),
+});
+function editableAutomation(definition) {
+    return {
+        name: definition.name,
+        description: definition.description,
+        enabled: definition.enabled,
+        events: definition.events,
+        intervalSeconds: definition.intervalSeconds,
+        filters: definition.filters,
+        task: definition.task,
+    };
+}
+/**
+ * The public API surface (spec 2026-07-23-independent-server-web-packages).
+ *
+ * Every route lives under this one prefix. The unversioned `/api/*` spelling the cockpit used
+ * to speak was removed once the whole API was reachable here — carrying two spellings meant two
+ * surfaces to keep working, and only one of them could be the typed contract. Bumping to `v2`
+ * means mounting a second table beside this one, not editing route paths.
+ */
+const V1_PREFIX = '/api/v1';
+/** Project scoping inside the versioned surface. The version is the OUTER dimension, so a
+ *  consumer picks its API version once and then addresses projects inside it. */
+const V1_SCOPED_PREFIX = `${V1_PREFIX}/p/:projectId`;
 /**
- * The project-scoped route table of a `createApp()` app, derived from its
- * actual registrations (so it can never drift from the code): every
- * method+path mounted under `/api/p/:projectId/…`, minus the scope-resolver
- * middleware (method ALL), deduped. The alias-parity suite iterates this to
- * assert unprefixed `/api/<path>` ≡ `/api/p/<boot>/<path>` ≡
- * `/api/p/default/<path>`.
+ * The project-scoped route table of a `createApp()` app, derived from its actual registrations
+ * (so it can never drift from the code): every method+path mounted under
+ * `/api/v1/p/:projectId/…`, minus the scope-resolver middleware (method ALL), deduped. The
+ * alias-parity suite iterates this to assert `/api/v1/<path>` ≡ `/api/v1/p/<boot>/<path>` ≡
+ * `/api/v1/p/default/<path>`.
  */
 export function projectRouteManifest(app) {
     const seen = new Set();
     const manifest = [];
     for (const route of app.routes) {
-        if (route.method === 'ALL' || !route.path.startsWith(`${SCOPED_PREFIX}/`))
+        if (route.method === 'ALL' || !route.path.startsWith(`${V1_SCOPED_PREFIX}/`))
             continue;
-        const path = route.path.slice(SCOPED_PREFIX.length);
+        const path = route.path.slice(V1_SCOPED_PREFIX.length);
         const key = `${route.method} ${path}`;
         if (seen.has(key))
             continue;
@@ -77,14 +208,17 @@ export function projectRouteManifest(app) {
 }
 /** 409 body for the inbox mutators while the follow-up inbox is off (#471). */
 const FOLLOWUPS_OFF = 'the follow-up inbox is disabled — set CEZ_FOLLOWUPS=1 to enable it';
+/** 409 body for every automations route while GitHub automations are off (#801). */
+const AUTOMATIONS_OFF = 'GitHub automations are disabled — set CEZ_AUTOMATIONS=1 to enable them';
 /**
  * The in-process bus for workspace-level SSE events. The registry-mutating
  * routes (`POST /api/projects` — step 4.2, emits `project-added` for a
  * genuinely new entry; `DELETE /api/projects/:projectId` — step 4.4) and the
- * checkout flow (step 4.3) call `emit()`; every open `/api/workspace/events`
- * stream relays the
- * event verbatim under its name. Injectable via `ServerDeps.workspaceEvents`
- * so tests (and any out-of-createApp emitter) can drive the stream.
+ * checkout flow (step 4.3) call `emit()`; runtime provider auth observation
+ * emits host-wide `provider-status`; every open `/api/workspace/events` stream
+ * relays the event verbatim under its name. Injectable via
+ * `ServerDeps.workspaceEvents` so tests (and any out-of-createApp emitter) can
+ * drive the stream.
  */
 export class WorkspaceEventBus {
     listeners = new Set();
@@ -120,15 +254,19 @@ const startRunSchema = z
     // other prompt fields (`systemPrompt` 20k, message `text` 100k) so an
     // unbounded body can't be piped into a spawned process (#429). 100k chars
     // (~25k tokens) is well past any hand-written task.
-    task: z.string().min(1).max(100_000, 'task must be at most 100000 characters'),
+    task: z.string().min(1).max(100_000, 'must be at most 100000 characters'),
     model: z.string().optional(),
     // Agent backend for this task (falls back to config `defaultRunner`).
-    runner: z.enum(['claude', 'codex', 'opencode']).optional(),
+    runner: z.enum(RUNNER_IDS).optional(),
+    // Agent account for this task (spec 2026-07-29-agent-profiles). Falls back to the project's
+    // own selection, then the discovered default. Bounded like a profile id in the workspace
+    // schema, so a value this route accepts can never be degraded away by the next load.
+    agentProfile: z.string().max(64).optional(),
     // Parallel variants (spec 010): ×2/×3 runs the task as 2–3 competing
     // agents in separate worktrees; the user compares diffs and picks one.
     variants: z.number().int().min(1).max(3).optional(),
     // Composer worktree opt-out (#worktree-toggle): false runs in the repo
-    // working tree (read-only skills). Ignored when variants > 1.
+    // working tree. Ignored when variants > 1.
     worktree: z.boolean().optional(),
     // Autonomous mode (#autonomous): the run never parks at `waiting` — it
     // auto-continues until the agent signals done. No "needs you" is raised.
@@ -145,7 +283,7 @@ const startRunSchema = z
     systemPrompt: z
         .string()
         .trim()
-        .max(20_000, 'systemPrompt must be at most 20000 characters')
+        .max(20_000, 'must be at most 20000 characters')
         .optional()
         .transform((s) => (s ? s : undefined)),
     // Screenshots pasted into the new-task form — same shape and limits as a
@@ -163,7 +301,7 @@ const startRunSchema = z
     // started — the same bookkeeping POST /api/todos/:id/start does, so the
     // audit trail survives the composer detour. Bounded like every other
     // string here; a todo id is a short generated key.
-    todoId: z.string().min(1).max(200, 'todoId must be at most 200 characters').optional(),
+    todoId: z.string().min(1).max(200, 'must be at most 200 characters').optional(),
 })
     .refine((b) => Boolean(b.workflow) !== Boolean(b.steps), {
     message: 'provide either "workflow" or "steps", not both',
@@ -173,7 +311,7 @@ const pickSchema = z.object({
 });
 const planSchema = z.object({
     // Same bound as `startRunSchema.task` — this flows into `planChain` (#429).
-    task: z.string().trim().min(1).max(100_000, 'task must be at most 100000 characters'),
+    task: z.string().trim().min(1).max(100_000, 'must be at most 100000 characters'),
 });
 // A saved workflow carries full `steps` OR the builder's `skills` stack
 // (spec 012). `overwrite: true` is the builder's Save on an existing file —
@@ -183,7 +321,7 @@ const saveWorkflowSchema = z
     name: z.string().trim().min(1).max(80),
     // Written into a YAML file on disk (#429) — a workflow description is a
     // short blurb, so a 2k cap is generous without allowing a file-bloat write.
-    description: z.string().max(2_000, 'description must be at most 2000 characters').optional(),
+    description: z.string().max(2_000, 'must be at most 2000 characters').optional(),
     steps: z.array(workflowStepSchema).min(1).max(8).optional(),
     skills: z.array(z.string().trim().min(1)).min(1).max(8).optional(),
     overwrite: z.boolean().optional(),
@@ -206,51 +344,25 @@ const SKILL_USAGE_MAX_ENTRIES = 200;
 // generous for GUI prefs; over-limit is a 400, never a silent strip. Shared by
 // BOTH ui-state routes (per-repo and workspace) via `parseUiStateBody`.
 const UI_STATE_MAX_KEYS = 200;
-/** Settings → Appearance (redesign R6): accent + density. ONE schema for both
- *  ui-state files — per-repo (the legacy home, kept so an older cezar in the
- *  same repo still honours it) and workspace (`~/.cezar/ui-state.json`, its
- *  post-migration home — multi-project spec, Data Model). */
+/** Settings → Appearance (redesign R6): accent + density + reading width. ONE
+ *  schema for both ui-state files — per-repo (the legacy home, kept so an older
+ *  cezar in the same repo still honours it) and workspace
+ *  (`~/.cezar/ui-state.json`, its post-migration home — multi-project spec,
+ *  Data Model).
+ *
+ *  Every key is `.optional()` so an older ui-state.json parses unchanged, but
+ *  each one must be listed HERE: the enclosing `workspaceUiStateSchema` is
+ *  `.passthrough()` at the top level only, so an unlisted key inside
+ *  `appearance` is stripped by zod and then wiped from the file by the shallow
+ *  merge-on-write. The cockpit adopts the PUT response as authoritative, so a
+ *  stripped key does not merely fail to persist — it visibly reverts the
+ *  control the user just touched. Adding an appearance preference means adding
+ *  it here in the same change. */
 const appearanceSchema = z.object({
     accent: z.enum(['lime', 'violet']).optional(),
     density: z.enum(['comfortable', 'compact', 'ultra']).optional(),
+    width: z.enum(['narrow', 'wide']).optional(),
 });
-/** Global GUI state (`~/.cezar/ui-state.json`, step 2.7) — the workspace twin
- *  of `uiStateSchema` below, sharing its `.passthrough()` + key-cap + shallow
- *  merge-on-write semantics via `parseUiStateBody`. Known keys are the
- *  cross-project prefs from the spec's Data Model; everything project-scoped
- *  (githubView, prompt templates, dismissed banners…) stays per-repo. */
-const workspaceUiStateSchema = z
-    .object({
-    appearance: appearanceSchema.optional(),
-    notifications: z.object({ enabled: z.boolean().optional() }).passthrough().optional(),
-    // Sidebar per-project collapse map, keyed by project id (slug ≤ 64 chars).
-    // Entry-capped like `skillUsage`: the map is written straight to a file the
-    // cockpit GETs on every load, so it must stay bounded on every axis.
-    sidebar: z
-        .object({
-        collapsed: z
-            .record(z.string().min(1).max(64), z.boolean())
-            .refine((map) => Object.keys(map).length <= UI_STATE_MAX_KEYS, {
-            message: `sidebar.collapsed must have at most ${UI_STATE_MAX_KEYS} entries`,
-        })
-            .optional(),
-    })
-        .passthrough()
-        .optional(),
-    // The user's curated selection of default (vendor) skills — `open-mercato/skills` — so the
-    // catalog is no longer forced in full. GLOBAL (here, not per-repo) because "which skills I
-    // want" describes the person, not a checkout, and must not depend on where cezar was launched
-    // (multi-project workspace). Tri-state, enforced in `discoverSkills`: an ABSENT key means "not
-    // curated" and every default skill still shows (opt-out default — no silent break on upgrade);
-    // a PRESENT array (even `[]`) shows only those names. Bounded like the `skillUsage` map: the
-    // file is GET/PUT wholesale, so an unbounded array is an unbounded write. Names match
-    // `lastTask.ref` (`.min(1).max(200)`). The client PUTs the whole array (shallow top-level merge).
-    importedSkills: z
-        .array(z.string().min(1).max(200))
-        .max(SKILL_USAGE_MAX_ENTRIES)
-        .optional(),
-})
-    .passthrough();
 const uiStateSchema = z
     .object({
     lastTask: z
@@ -330,7 +442,7 @@ const patchRunSchema = z.object({
 });
 // Session commit (redesign R5 — §"Git/session API additions").
 const gitCommitSchema = z.object({
-    message: z.string().trim().min(1, 'commit message must not be empty').max(5_000),
+    message: z.string().trim().min(1, 'must not be empty').max(5_000),
 });
 // "Open in…" (#open-in / #365): `target` selects the app; `path` (optional, worktree-relative)
 // narrows the target's own worktree/repo-root default to one file — used by the diff pane's
@@ -387,9 +499,9 @@ function foldedLength(task, stack) {
 // follow-up composer is a full composer, so a screenshot pasted into it must reach the reopened
 // session rather than being silently dropped.
 const continueSchema = z.object({
-    text: z.string().max(100_000, 'text must be at most 100000 characters').optional(),
+    text: z.string().max(100_000, 'must be at most 100000 characters').optional(),
     images: z.array(imageInputSchema).max(4).optional(),
-    runner: z.enum(['claude', 'codex', 'opencode']).optional(),
+    runner: z.enum(RUNNER_IDS).optional(),
     model: z.string().max(200).optional(),
 });
 // Inbox "▶ Run" body (spec 007 / #401 / #413): every field optional, and the whole body is
@@ -401,12 +513,12 @@ const continueSchema = z.object({
 // absent so it never touches `task`.
 const startTodoSchema = z
     .object({
-    runner: z.enum(['claude', 'codex', 'opencode']).optional(),
+    runner: z.enum(RUNNER_IDS).optional(),
     model: z.string().max(200).optional(),
     prompt: z
         .string()
         .trim()
-        .max(20_000, 'prompt must be at most 20000 characters')
+        .max(20_000, 'must be at most 20000 characters')
         .optional()
         .transform((s) => (s ? s : undefined)),
 })
@@ -432,21 +544,99 @@ function stripHostPort(host) {
         return bracketed[1];
     return host.replace(/:\d+$/, '');
 }
-/** The shared write-side half of BOTH ui-state routes (per-repo `/api/ui-state`
- *  and workspace `/api/workspace/ui-state`) — the factored split the
- *  multi-project spec calls for instead of a copy: parse with the route's own
- *  schema, then cap the top-level key count so a `.passthrough()` schema can't
- *  accumulate an unbounded key set (#429). The merge-on-write stays with each
- *  route (they write different files) but is shallow in both. */
-function parseUiStateBody(schema, body) {
-    const parsed = schema.safeParse(body);
-    if (!parsed.success)
-        return { error: parsed.error.issues.map((i) => i.message).join('; ') };
-    if (Object.keys(parsed.data).length > UI_STATE_MAX_KEYS) {
-        return { error: `ui-state has too many keys (max ${UI_STATE_MAX_KEYS})` };
+/** The shared write-side half of BOTH ui-state routes (per-repo `/api/v1/ui-state`
+ *  and workspace `/api/v1/workspace/ui-state`) — the factored split the
+ *  multi-project spec calls for instead of a copy: the route's own schema, plus a
+ *  cap on the top-level key count so a `.passthrough()` schema can't accumulate an
+ *  unbounded key set (#429). The cap rides as a refinement so the whole thing is one
+ *  schema and can go through `jsonBody` like every other mutating route. The
+ *  merge-on-write stays with each route (they write different files) but is shallow
+ *  in both. */
+function capUiStateKeys(data, ctx) {
+    if (Object.keys(data).length > UI_STATE_MAX_KEYS) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: `ui-state has too many keys (max ${UI_STATE_MAX_KEYS})` });
+    }
+}
+// Derived once per route instead of by a generic `wrap(schema)` helper called at the route: a
+// generic wrapper leaves the schema type unresolved where `jsonBody` needs it, and Hono answers
+// that by dropping the whole PUT from the route schema rather than erroring — both ui-state PUTs
+// silently vanished from `AppType`. Concrete consts keep them visible to `hc`.
+const uiStateBody = uiStateSchema.superRefine(capUiStateKeys);
+/**
+ * Query schemas for the READ routes — deliberately permissive.
+ *
+ * These exist to make a query key VISIBLE to the route type (`hc` refuses a `query` argument for
+ * a key no validator declares), NOT to narrow what the route accepts. Every one of these handlers
+ * compares `=== '1'` and treats everything else as false, so `?refresh=0` is a successful request
+ * today; a literal schema would silently turn it into a 400. The comparison stays in the handler
+ * and the validator stays out of its way.
+ *
+ * The one route that really is strict on the wire — `GET /github/prs/:number/changes`, which 400s
+ * on `?refresh=true` — keeps its own `z.enum(['1'])` schema next to the route.
+ */
+/**
+ * One query value, matching what `c.req.query('k')` did before these routes were validated.
+ *
+ * Hono's query validator hands a REPEATED key as an array (`?wait=1&wait=1` → `['1','1']`), where
+ * `c.req.query()` silently took the first. A plain `z.string()` therefore turns a request that
+ * used to answer 200 into a 400 — a wire change no caller asked for. Collapsing to the first
+ * value keeps the old behaviour, and the client still sees a plain `key?: string`.
+ */
+const queryValue = z.union([z.string(), z.array(z.string()).transform((v) => v[0])]).optional();
+const refreshQuery = z.object({ refresh: queryValue });
+const waitQuery = z.object({ wait: queryValue });
+function parseAccept(header) {
+    const ranges = [];
+    for (const part of header.split(',')) {
+        const [range = '', ...params] = part.split(';');
+        const [type = '', subtype = ''] = range.trim().toLowerCase().split('/');
+        if (type === '' || subtype === '')
+            continue;
+        const weight = params.map((p) => p.trim().toLowerCase()).find((p) => p.startsWith('q='));
+        const parsed = weight === undefined ? 1 : Number.parseFloat(weight.slice(2));
+        const q = Number.isFinite(parsed) ? Math.min(Math.max(parsed, 0), 1) : 0;
+        if (q > 0)
+            ranges.push({ type, subtype, q });
+    }
+    return ranges;
+}
+/**
+ * The best of `offers` for this `Accept`, or `null` for "no preference expressed" — which is what
+ * an absent header, a `*<slash>*`-only header and a header naming nothing on offer all mean, and
+ * what leaves the caller on its route's default.
+ *
+ * `offers` is the server's own preference order: an offer may itself be a wildcard (`image/*`,
+ * since the concrete image type is not known until the file is read), and equal q-values go to the
+ * EARLIER offer, so each route lists its default representation first.
+ */
+function negotiate(accept, offers) {
+    if (accept === undefined)
+        return null;
+    const ranges = parseAccept(accept);
+    let best = null;
+    for (const offer of offers) {
+        const [type = '', subtype = ''] = offer.split('/');
+        let q = 0;
+        for (const range of ranges) {
+            if (range.type === '*' && range.subtype === '*')
+                continue; // "anything" is not a preference
+            const typeMatches = range.type === type || range.type === '*' || type === '*';
+            const subtypeMatches = range.subtype === subtype || range.subtype === '*' || subtype === '*';
+            if (typeMatches && subtypeMatches && range.q > q)
+                q = range.q;
+        }
+        if (q > 0 && (best === null || q > best.q))
+            best = { offer, q };
     }
-    return { data: parsed.data };
+    return best?.offer ?? null;
 }
+/** What `GET /repo/commit/:sha` offers, DEFAULT FIRST: the legacy `text/plain` blob is what a
+ *  request with no opinion has always received (§2), so it also wins an Accept tie. */
+const COMMIT_FORMATS = ['text/plain', 'application/json'];
+/** What `GET /runs/:id/files` offers, DEFAULT FIRST. `image/*` rather than a concrete type: which
+ *  image type the bytes are is only known once the path resolves, and the raw branch refuses
+ *  everything that is not an image anyway. */
+const FILE_FORMATS = ['application/json', 'image/*'];
 /** Workspace-root writability probe (multi-project spec, "API Contracts"):
  *  optional `mkdir -p`, `access W_OK`, then a real create/delete round-trip — W_OK alone
  *  can lie (e.g. a read-only mount still reports writable permission bits).
@@ -469,6 +659,10 @@ async function probeWritableDir(dir, create) {
         return err instanceof Error ? err.message : String(err);
     }
 }
+// The return type is INFERRED on purpose: it is the chained app type built at the bottom of
+// this function, and `AppType` (src/server/app-type.ts) is `ReturnType<typeof createApp>`.
+// Annotating it `Hono` here would erase every route from the type and leave the typed client
+// with nothing to offer. See the `routed` assembly at the end of the function.
 export function createApp(deps) {
     const { version, update, bindHost, bootProjectId } = deps;
     // Boot singletons keep DELIBERATELY distinct names (`boot*`): every
@@ -479,8 +673,60 @@ export function createApp(deps) {
     const bootRoot = deps.repoRoot;
     const bootDataDir = join(bootRoot, '.ai/cezar');
     const modelCatalog = deps.modelCatalog ?? new RunnerModelCatalog({
-        adapters: { codex: { discover: () => discoverCodexModels({ cwd: bootRoot }) } },
+        adapters: {
+            codex: { discover: () => discoverCodexModels({ cwd: bootRoot }) },
+            opencode: { discover: () => discoverOpencodeModels({ cwd: bootRoot }) },
+        },
     });
+    const providerAuth = deps.providerAuth ?? new ProviderAuthService();
+    const workspaceConfig = deps.workspaceConfig ?? {
+        load: loadWorkspaceConfig,
+        mergeWrite: mergeWriteWorkspaceConfig,
+    };
+    const providerStatus = async (options) => {
+        if (providerAuthChecksDisabled()) {
+            return applyProviderEnablement(await providerAuth.status(options?.refresh ? { refresh: true } : undefined), []);
+        }
+        const [discovered, workspace] = await Promise.all([
+            providerAuth.status(options?.refresh ? { refresh: true } : undefined),
+            workspaceConfig.load(),
+        ]);
+        return applyProviderEnablement(discovered, workspace.disabledProviders);
+    };
+    /**
+     * The gate: why a run cannot start against `required`, or null when it can.
+     *
+     * VERIFY BEFORE YOU REFUSE. Auth state is served stale-while-revalidate (see
+     * `ProviderAuthService.status`), so a cached "disconnected" may predate a login cezar could not
+     * observe — someone running `claude auth login` in a terminal. Refusing on that would lock a user
+     * out of their own cockpit with no way back but waiting. So a believed-unavailable provider is
+     * re-probed, and only a refusal that survives the fresh answer is returned.
+     *
+     * The cost lands where it belongs: the common path (connected, warm) pays nothing at all, and the
+     * probe is only spawned when cezar is about to say no — a rare, interactive moment. This is also
+     * what lets the cache hold a negative for a minute instead of five seconds, which is what made
+     * every reader of `GET /providers/status` periodically pay for a CLI spawn.
+     *
+     * A runtime auth latch is deliberately NOT escaped by this: `withRuntimeFailures` keeps forcing
+     * the row disconnected until the user acknowledges that exact incident, so the re-probe cannot
+     * talk cezar out of a rejection it actually observed.
+     */
+    const providerActionError = async (required) => {
+        const known = await providerStatus();
+        const message = unavailableProviderMessage(required, known);
+        if (message === null)
+            return null;
+        // A DISABLED provider is a settings fact, not a probe result — re-probing it learns nothing and
+        // would spawn a CLI to re-read something the user typed.
+        const disabled = required.some((provider) => known.providers.find((row) => row.provider === provider)?.enabled === false);
+        if (disabled)
+            return message;
+        return unavailableProviderMessage(required, await providerStatus({ refresh: true }));
+    };
+    const openTerminal = deps.openTerminal ?? openInTerminal;
+    const openFile = deps.openFile ?? openFileInDefaultApp;
+    const openApp = deps.openApp ?? openInApp;
+    const skillsUpdate = deps.skillsUpdate ?? new SkillsUpdateService();
     // ---- workspace boot-project identity (multi-project spec) ----------------
     // The boot flow (`initWorkspace` in src/index.ts) registers the boot repo
     // and plumbs its registry id in via `deps.bootProjectId`. Legacy callers and
@@ -551,6 +797,7 @@ export function createApp(deps) {
         dataDir: bootDataDir,
         store: deps.store,
         manager: deps.manager,
+        automationStore: deps.automationStore ?? AutomationStore.open(bootDataDir),
         launchKey: ensureLaunchKey(bootDataDir), // bookmarklet auto-start secret (spec 011)
     };
     // Non-boot projects build lazily on first scoped request; their managers
@@ -567,6 +814,25 @@ export function createApp(deps) {
     // Workspace-level SSE bus (step 2.8) — the registry mutators and the
     // checkout flow (Phase 4) emit here; /api/workspace/events relays.
     const workspaceEvents = deps.workspaceEvents ?? new WorkspaceEventBus();
+    const emitAutomationChange = (project, automationId, revision, deleted = false) => workspaceEvents.emit('automation-change', {
+        project: project.id,
+        automationId,
+        revision,
+        ...(deleted ? { deleted: true } : {}),
+    });
+    const automationsChanged = () => deps.automationsChanged?.();
+    const providerRuntimeAuth = deps.providerRuntimeAuth
+        ?? new ProviderRuntimeAuthObserver(providerAuth, (status) => {
+            workspaceEvents.emit('provider-status', status);
+        });
+    providerRuntimeAuth.watch(bootContext.store);
+    for (const id of contexts.ids()) {
+        const ctx = contexts.peek(id);
+        if (ctx)
+            providerRuntimeAuth.watch(ctx.store);
+    }
+    contexts.onStoreCreated((store) => providerRuntimeAuth.watch(store));
+    contexts.onContextBuilt((ctx) => providerRuntimeAuth.watch(ctx.store));
     const app = new Hono();
     // Reject oversized request bodies before they reach any handler (#429). GETs
     // and SSE carry no body, so this only ever gates the mutating routes.
@@ -577,7 +843,7 @@ export function createApp(deps) {
     // own: any page the user visits can still POST to us (CSRF), and DNS
     // rebinding can point a foreign domain at loopback and read our responses.
     // Two zero-config checks close both holes on every /api route EXCEPT
-    // /api/health (the intentional cross-origin discovery endpoint, spec 011 —
+    // /api/v1/health (the intentional cross-origin discovery endpoint, spec 011 —
     // it exposes nothing sensitive, see #431):
     //   1. Host allowlist (loopback deployments only) — a request whose Host is
     //      not a loopback name did not really originate from this machine. A
@@ -600,7 +866,7 @@ export function createApp(deps) {
     // Scope note: check 2 covers writes only. A cross-origin GET from any site
     // still reaches the read routes — but its Host is ours, so it is a *forced
     // request*, not a read: the same-origin policy stops the attacker seeing any
-    // response body (we send CORS headers on /api/health alone), and no GET
+    // response body (we send CORS headers on /api/v1/health alone), and no GET
     // handler mutates state. Rebinding, which WOULD make those reads legible, is
     // what check 1 stops.
     const MUTATING_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
@@ -615,9 +881,12 @@ export function createApp(deps) {
                 error: 'forbidden: unexpected Host header — this request did not originate from this machine (see #426)',
             }, 403);
         }
-        // /api/health stays CORS-open for bookmarklet discovery, but its Host is
-        // still checked above: cross-origin is legitimate, DNS rebinding is not.
-        if (c.req.path === '/api/health')
+        // /api/v1/health stays CORS-open for cross-origin discovery, but its Host is
+        // still checked above: cross-origin is legitimate, DNS rebinding is not. The
+        // path is spelled through V1_PREFIX rather than inline — an unversioned
+        // literal here silently stopped matching when the API moved and left health
+        // relying on the mutating-methods gate below to let its GETs through.
+        if (c.req.path === `${V1_PREFIX}/health`)
             return next();
         if (MUTATING_METHODS.has(c.req.method)) {
             const origin = c.req.header('origin');
@@ -661,15 +930,16 @@ export function createApp(deps) {
     });
     // The mirrored project-route table (spec "API Contracts → Project-scoped").
     // Every route below registers ONCE on this sub-app; `createApp` mounts it
-    // twice — under `/api/p/:projectId` (scoped) and under `/api` (the legacy
-    // aliases, protected surfaces) — so both spellings share one handler and
-    // can never drift. The resolver middleware binds `c.get('project')`:
-    // no `projectId` param (legacy mount) → the boot context, byte-identical to
+    // twice — under `/api/v1/p/:projectId` (scoped) and under `/api/v1` (bound to
+    // the boot project) — so both spellings share one handler and can never
+    // drift. The resolver middleware binds `c.get('project')`:
+    // no `projectId` param (unscoped mount) → the boot context, byte-identical to
     // the pre-workspace closures; `default` or the boot project's own id → the
     // boot context too; anything else → the lazy context map, with
     // `ProjectContextError` mapped to 404 (unknown) / 409 (missing root).
-    const api = new Hono();
-    api.use('*', async (c, next) => {
+    // Named rather than inlined because both mounts share it — one function, so
+    // the two spellings can never disagree about what `default` means.
+    const resolveProjectScope = async (c, next) => {
         const raw = c.req.param('projectId');
         if (raw === undefined) {
             c.set('project', bootContext);
@@ -694,15 +964,23 @@ export function createApp(deps) {
             throw err;
         }
         return next();
-    });
+    };
     // ---- static GUI ----------------------------------------------------------
     const webDir = resolveWebDir();
     const distDir = join(webDir, 'dist');
     const HTML_TYPE = 'text/html; charset=utf-8';
-    const staticFile = (name, type) => () => {
+    const staticFile = (name, type) => (c) => {
         // Read per request — the files are tiny and this keeps dev iteration live.
-        const body = readFileSync(join(webDir, name));
-        return new Response(body, { headers: { 'content-type': type } });
+        //
+        // Served out of the Vite build: the file is a `public/` asset of the web package, which the
+        // build copies verbatim into `web/dist`. One home, one URL — the same bytes this route
+        // hands out are what the bundle's own `<img src="/open-mercato.svg">` asks for.
+        // Without a build there is nothing to serve, which is a 404 rather than a crash (the shell
+        // route answers the same dev-only state with its build hint).
+        const path = join(distDir, name);
+        if (!existsSync(path))
+            return c.json({ error: 'not found' }, 404);
+        return new Response(readFileSync(path), { headers: { 'content-type': type } });
     };
     let hintLogged = false;
     const serveShell = (c) => {
@@ -749,14 +1027,14 @@ export function createApp(deps) {
             },
         });
     });
-    // The favicon web/app/index.html points at (`../open-mercato.svg`).
+    // The favicon packages/web/index.html points at (`/open-mercato.svg`).
     app.get('/open-mercato.svg', staticFile('open-mercato.svg', 'image/svg+xml'));
     // ---- meta ----------------------------------------------------------------
     // CORS — deliberately for /api/health ONLY (spec 011): the bookmarklets
     // fetch it cross-origin from github.com to discover which local ports run a
     // cockpit and which repo each serves. Health exposes no secrets beyond the
     // repo path/remote; every other endpoint stays same-origin.
-    app.use('/api/health', async (c, next) => {
+    const healthCors = async (c, next) => {
         c.header('access-control-allow-origin', '*');
         if (c.req.method === 'OPTIONS') {
             // Preflight (e.g. Chrome Private Network Access) — allow the plain GET.
@@ -765,10 +1043,16 @@ export function createApp(deps) {
             return c.body(null, 204);
         }
         await next();
-    });
+    };
+    app.use(`${V1_PREFIX}/health`, healthCors);
     // One builder for both transports: `GET /api/health` (the authoritative,
-    // CORS-open discovery endpoint) and the `health` topic on `/api/ws` below
+    // CORS-open discovery endpoint) and the `health` topic on `/api/v1/ws` below
     // push the byte-identical shape, so the two can never drift.
+    // Deliberately UNANNOTATED: this literal is the source of the `/health` shape. Annotating it
+    // with the api-client's `HealthResponse` made the contract circular — the DTO was declared by
+    // hand, the handler was checked against it, and `AppType` then reported the hand-written type
+    // back as if the server had proven it. Inferring here means the route says what it actually
+    // sends, which is what lets the DTO be derived instead of maintained.
     const healthSnapshot = async () => {
         const [checks, repo, config, workspace] = await Promise.all([
             detectEnvironment(),
@@ -782,7 +1066,11 @@ export function createApp(deps) {
         const caps = capabilities();
         return {
             version,
-            latestVersion: update?.latest,
+            // Spread rather than `latestVersion: update?.latest`: an `undefined` VALUE is dropped by
+            // JSON.stringify, so the key is absent on the wire — but writing it unconditionally types
+            // the key as always-present, which is a shape no client ever receives. The contract schema
+            // says `.optional()`, and contract-parity.test.ts holds the two together.
+            ...(update?.latest !== undefined ? { latestVersion: update.latest } : {}),
             // Health is CORS-open and, in hosted mode, reachable off the loopback —
             // so any site/host that reads it would learn the developer's absolute
             // checkout path and username (#431). Local mode keeps the full path (the
@@ -874,7 +1162,13 @@ export function createApp(deps) {
             void refreshHealth(); // stale: refresh, don't wait on it
         return healthCache.payload;
     };
-    app.get('/api/health', async (c) => c.json(await readHealth()));
+    // ---- chained family: health (workspace-level) ----------------------------
+    // Written as ONE chained expression rather than a loose `app.get(...)`
+    // statement because Hono accumulates its route types through the chain: a
+    // statement's return value is discarded, so `typeof app` would record nothing
+    // and `hc<AppType>` would have no endpoint to offer. `createApp` mounts this
+    // under both `/api` (the frozen legacy spelling) and `/api/v1`.
+    const healthRoutes = new Hono().get('/health', async (c) => c.json(await readHealth()));
     // The push twin of the poll it replaced (#369): while at least one cockpit
     // holds the `health` topic the server re-reads the snapshot on the old 5 s
     // cadence and broadcasts ONLY when it changed — a `git checkout` in a
@@ -906,14 +1200,679 @@ export function createApp(deps) {
     // `GET /api/health` reads a warm value instead of the cold ~1 s compute.
     if (deps.socketHub)
         void refreshHealth();
-    // Host capability, not project state: one installed/authenticated Codex CLI
-    // and one in-memory cache are shared by every registered workspace.
-    app.get('/api/models', async (c) => {
-        const query = z.object({ runner: z.literal('codex') }).safeParse(c.req.query());
-        if (!query.success)
-            return c.json({ error: 'runner must be codex' }, 400);
+    /**
+     * Warm the whole of cezar's agent knowledge — the three discovered defaults AND every extra
+     * account — so no reader ever pays the first shell-out.
+     *
+     * Which login each agent is signed into is operating knowledge, not a settings-page detail: the
+     * composer, the action gate, the accounts pane and every run resolution ask for it. So the server
+     * learns it once, at boot, and keeps it (see the asymmetric cache lifetime in
+     * `core/provider-auth.ts`); on-demand refresh rides on `?refresh=1` and on the explicit
+     * invalidations — connect, repoint, remove, runtime rejection.
+     *
+     * Extra accounts are warmed ONE AT A TIME, after the defaults. Each is a CLI spawn, and a machine
+     * with several accounts would otherwise fan out a spawn storm at exactly the moment the browser is
+     * fetching the bundle; nothing is waiting on this, so sequential costs nothing that matters.
+     *
+     * Hosted mode warms only the defaults: the agent-profiles family is refused there, so there are
+     * no accounts to learn about.
+     */
+    const warmAgentKnowledge = async () => {
+        await providerAuth.status().catch(() => { });
+        if (!capabilities().localHandoff)
+            return;
+        const store = await loadAgentAccounts().catch(() => defaultAgentAccountStore());
+        for (const account of listAgentProfiles(store, PROVIDER_IDS)) {
+            if (account.isDefault)
+                continue; // covered by `status()` above
+            await providerAuth
+                .profileStatus(account.provider, { id: account.id, configDir: account.path })
+                .catch(() => { });
+        }
+    };
+    // Same gate as `refreshHealth`, same reason (startServer injects the hub; a bare app in tests does
+    // not, so tests never spawn probes here). Fire-and-forget: a probe that fails leaves that row
+    // cold, which is exactly the state every reader already handles.
+    if (deps.socketHub)
+        void warmAgentKnowledge();
+    // ---- chained family: host model catalog (workspace-level) ----
+    const modelsRoutes = new Hono()
+        // `modelDiscoveryRunnerSchema` is the contract's own list of the runners with an
+        // authoritative host-local catalog (#794), so the client compiles against exactly what this
+        // validates. Claude has no such source: its picker stays on static presets and this 400s.
+        .get('/models', queryZodValidator(z.object({ runner: z.union([z.string(), z.array(z.string()).transform((v) => v[0])]).pipe(modelDiscoveryRunnerSchema) }), { message: 'runner must be codex or opencode' }), async (c) => {
+        const query = { data: c.req.valid('query') };
         return c.json(await modelCatalog.get(query.data.runner));
     });
+    /**
+     * Resolve `profileId` (absent = the discovered default) into a concrete account for `provider`.
+     *
+     * A dangling id is an ERROR here rather than the silent fall-back to the default that run
+     * resolution performs. The difference is who is asking: a run is replaying a stored reference
+     * and the default is the only safe answer it can act on, whereas a route is answering a user
+     * who just named an account — telling them "unknown account" is honest, and quietly connecting
+     * or reporting on a different one is not.
+     */
+    const resolveWorkspaceProfile = async (provider, profileId) => {
+        if (profileId === undefined || profileId === DEFAULT_AGENT_ACCOUNT_ID) {
+            return { profile: defaultAgentProfile(provider) };
+        }
+        let accounts;
+        try {
+            accounts = (await loadAgentAccounts()).accounts;
+        }
+        catch {
+            return { error: `unknown ${provider} account: ${profileId}` };
+        }
+        const stored = accounts.find((a) => a.id === profileId && a.provider === provider);
+        if (!stored)
+            return { error: `unknown ${provider} account: ${profileId}` };
+        return { profile: resolveStoredProfile(stored) };
+    };
+    /**
+     * The environment a terminal handoff must carry so the CLI lands on the right account.
+     *
+     * `profileId` is the one RECORDED on the step that owns the session, never the project's
+     * current selection: `claude --resume <id>` reads `<configDir>/sessions`, so a handoff for a
+     * run started on the work account and resumed after the project was switched back would find
+     * nothing and silently open a fresh conversation.
+     */
+    const handoffEnv = async (provider, profileId) => {
+        const resolved = await resolveWorkspaceProfile(provider, profileId);
+        if ('error' in resolved) {
+            return { error: `this session belongs to an account that no longer exists (${profileId})` };
+        }
+        const { profile } = resolved;
+        return { env: profile.isDefault ? {} : profileEnv(provider, profile.path) };
+    };
+    /** The copy-paste fallback shown when no terminal could be opened — same account, spelled for
+     *  this platform's shell. `null` when the dir cannot be embedded safely, which is a refusal. */
+    const handoffFallbackCommand = (cwd, command, env) => {
+        const prefixed = withEnvPrefix(command, env, process.platform);
+        return prefixed === null ? null : `cd '${cwd}' && ${prefixed}`;
+    };
+    /** A registered project's realpath'd root, or null when the id is unknown. */
+    const projectRootFor = async (projectId) => {
+        try {
+            return (await loadWorkspaceConfig()).projects.find((p) => p.id === projectId)?.root ?? null;
+        }
+        catch {
+            return null;
+        }
+    };
+    // ---- chained family: agent providers (workspace-level) ----
+    const providersRoutes = new Hono()
+        .get('/providers/status', queryZodValidator(z.object({ refresh: queryValue.refine((v) => v === undefined || v === '1') }), { message: 'refresh must be 1 when provided' }), async (c) => {
+        const query = { data: c.req.valid('query') };
+        return c.json(await providerStatus({ refresh: query.data.refresh === '1' }));
+    })
+        .put('/providers/:provider/enabled', paramZodValidator(z.object({ provider: providerParamSchema }), { message: 'provider and enabled boolean are required' }), jsonZodValidator(providerEnabledSchema, { message: 'provider and enabled boolean are required' }), async (c) => {
+        const provider = { data: c.req.valid('param').provider };
+        const body = { data: c.req.valid('json') };
+        let workspace;
+        try {
+            workspace = await workspaceConfig.mergeWrite((config) => {
+                const disabled = new Set(config.disabledProviders);
+                if (body.data.enabled)
+                    disabled.delete(provider.data);
+                else
+                    disabled.add(provider.data);
+                config.disabledProviders = PROVIDER_IDS.filter((id) => disabled.has(id));
+            });
+        }
+        catch {
+            return c.json({ error: 'Provider preference could not be saved.' }, 500);
+        }
+        const result = applyProviderEnablement(await providerAuth.status(), workspace.disabledProviders);
+        const row = result.providers.find(({ provider: id }) => id === provider.data);
+        if (row)
+            workspaceEvents.emit('provider-status', row);
+        return c.json(result);
+    })
+        .post('/providers/:provider/retry', paramZodValidator(z.object({ provider: providerParamSchema }), { message: 'provider and current authFailureId are required' }), jsonZodValidator(providerRetrySchema, { message: 'provider and current authFailureId are required' }), async (c) => {
+        const provider = { data: c.req.valid('param').provider };
+        const body = { data: c.req.valid('json') };
+        if (!providerAuth.clearRuntimeAuthFailure(provider.data, body.data.authFailureId)) {
+            return c.json({ error: 'Authentication incident changed. Refresh and try again.' }, 409);
+        }
+        const result = await providerStatus({ refresh: true });
+        const row = result.providers.find(({ provider: id }) => id === provider.data);
+        if (row)
+            workspaceEvents.emit('provider-status', row);
+        return c.json(result);
+    })
+        .post('/providers/connect', jsonZodValidator(providerConnectSchema, { message: 'provider must be claude, codex, opencode, or pi' }), async (c) => {
+        const body = { data: c.req.valid('json') };
+        const provider = body.data.provider;
+        // A NAMED account is refused in hosted mode before anything is resolved, exactly like every
+        // sibling route in the agent-profiles family. Checking later would already have read
+        // `~/.cezar/agent-accounts.json`, built a command carrying the account's absolute path (which
+        // both the success body and the hosted 409 echo), and — for a stored account — spawned a
+        // probe. It would also answer `unknown account: <id>` for a wrong id, which is an enumeration
+        // oracle for the very ids the hosted listing withholds. The bare-provider spelling keeps its
+        // existing behaviour: it names no host path and is how the Providers card has always worked.
+        if (body.data.profileId !== undefined
+            && body.data.profileId !== DEFAULT_AGENT_ACCOUNT_ID
+            && !capabilities().localHandoff) {
+            return c.json(hostedProfileRefusal, 409);
+        }
+        // Resolve the account BEFORE anything else: both the command and the status probe below
+        // must describe the same one, or the pane reports on the personal login while the terminal
+        // signs into the work login.
+        const resolved = await resolveWorkspaceProfile(provider, body.data.profileId);
+        if ('error' in resolved)
+            return c.json({ error: resolved.error }, 400);
+        const { profile } = resolved;
+        const command = providerAuth.loginCommand(provider, profile.isDefault ? null : profile.path);
+        // Fail closed: a config dir that cannot be embedded safely in this platform's shell has no
+        // safe degradation. Running the bare command would sign the user into a DIFFERENT account
+        // than the one they clicked, and nothing in the terminal would say so.
+        if (command === null) {
+            return c.json({ error: `This account's folder cannot be used in a terminal command: ${profile.configDir}` }, 409);
+        }
+        // BOTH branches must mean "is this account signed in NOW". The default branch refreshes; the
+        // account branch has to evict first, because `profileStatus` serves the per-account cache and
+        // a connected answer there stands for CONNECTED_TTL_MS. Without this, Connect after a
+        // `claude /logout` answers "already connected", opens nothing, and the user is stuck — and it
+        // would contradict this module's own invariant that opening a login is one of the things
+        // cezar CAN observe and therefore invalidates explicitly rather than waiting out a window.
+        if (!profile.isDefault)
+            providerAuth.forgetProfileStatus(provider, profile.id);
+        const row = profile.isDefault
+            ? (await providerAuth.status({ refresh: true })).providers.find((candidate) => candidate.provider === provider)
+            : await providerAuth.profileStatus(provider, { id: profile.id, configDir: profile.path });
+        if (!row) {
+            return c.json({ error: 'Authentication could not be verified. Try again.' }, 500);
+        }
+        if (row.status === 'connected') {
+            return c.json({ opened: false, connected: true, command });
+        }
+        if (row.status === 'not-installed') {
+            return c.json({ error: row.hint ?? providerAuth.installHint(provider), command }, 409);
+        }
+        if (row.status === 'unknown') {
+            return c.json({ error: row.hint ?? 'Authentication could not be verified. Try again.', command }, 409);
+        }
+        if (!capabilities().localHandoff) {
+            return c.json({ error: 'Run this command on the machine hosting cezar.', command }, 409);
+        }
+        let opened = false;
+        try {
+            // No `env` argument: `loginCommand` already rendered the account's config dir INTO the
+            // command, because this string is also the copy-paste fallback the pane shows. Passing
+            // it again here would set the variable twice.
+            opened = await openTerminal(bootRoot, command);
+        }
+        catch {
+            // Terminal handoff is best-effort; the exact command remains the safe fallback.
+        }
+        if (!opened) {
+            return c.json({ error: 'No terminal emulator could be opened. Run this command manually.', command }, 409);
+        }
+        return c.json({ opened: true, command });
+    });
+    // ---- chained family: agent profiles / accounts (workspace-level) ----------
+    // Extra config dirs for a SECOND login of the same agent CLI (spec
+    // 2026-07-29-agent-profiles). Workspace-level and therefore SINGLE-MOUNT: an account belongs to
+    // the person and the machine, never to a repo, and a project-scoped spelling would be a second
+    // surface to protect with no consumer. Which account a project uses is a field on
+    // `PATCH /api/v1/projects/:projectId` instead.
+    //
+    // Writing is a LOCAL-MACHINE capability, exactly like `PUT /api/v1/agent-config/:id`: a profile
+    // points an agent at a directory on the host, and the listing echoes absolute paths carrying
+    // the username — the same disclosure `/api/v1/health` trims in hosted mode (#431).
+    /**
+     * This agent's own USER-scope config files, resolved inside ONE account's folder.
+     *
+     * Straight from the catalog — the single home of config-file vendor knowledge — with an
+     * `AgentHomePaths` whose slot for this provider is the account's dir. That is what makes a second
+     * login's `settings.json` the file you open rather than the default account's, and it keeps the
+     * ids opaque and stable so the open route below never takes a path from the client.
+     */
+    const accountFiles = async (profile) => {
+        const home = {
+            ...agentHomePaths(),
+            ...(profile.provider === 'claude' ? { claude: profile.path } : {}),
+            ...(profile.provider === 'codex' ? { codex: profile.path } : {}),
+            ...(profile.provider === 'opencode' ? { opencodeConfig: profile.path } : {}),
+        };
+        const defs = listConfigFiles().filter((def) => def.scope === 'user' && def.runners.includes(profile.provider));
+        return Promise.all(defs.map(async (def) => {
+            const path = def.resolve(bootRoot, home);
+            return { id: def.id, label: basename(path), path, exists: (await statConfigPath(path)).exists };
+        }));
+    };
+    /** Build the wire row for one resolved profile: its dir state plus whatever auth is cached. */
+    const agentProfileBody = async (profile) => ({
+        id: profile.id,
+        provider: profile.provider,
+        label: profile.label,
+        configDir: profile.configDir,
+        path: profile.path,
+        ...(await profileDirState(profile.provider, profile.path)),
+        isDefault: profile.isDefault,
+        // CACHED auth only — this listing must never pay a CLI spawn.
+        //
+        // Probing here cost a shell-out per provider PLUS one per extra account: ~0.7s with no extra
+        // accounts and over 2s with a few, on every cold load, for a route whose real job (what
+        // accounts exist) is a JSON read and a handful of stats. `GET /api/v1/health` already
+        // established the rule — it serves whatever the cache holds and never pays a `gh` shell-out.
+        // An absent `status` means "not determined yet", which the cockpit renders as Checking… and
+        // then fills in from the per-account status route below.
+        //
+        // SPREAD, not `status: maybeUndefined`: hono would type the key as always-present while
+        // `JSON.stringify` drops it, which is exactly the drift `contract-parity` catches (AGENTS.md
+        // names this as one of the two recurring mismatches).
+        ...(() => {
+            const cached = profile.isDefault
+                ? providerAuth.peekStatus()?.providers.find((row) => row.provider === profile.provider)
+                : providerAuth.peekProfileStatus(profile.provider, profile.id);
+            return cached ? { status: cached } : {};
+        })(),
+        files: await accountFiles(profile),
+    });
+    /**
+     * Resolve `:id` to an account for the per-account reads below. Unlike `resolveWorkspaceProfile`
+     * this accepts the reserved `default` for a NAMED provider, which these routes cannot infer — so
+     * the id may be `default:<provider>` as well as a stored account id.
+     */
+    const accountById = async (id) => {
+        const [head, tail] = id.split(':');
+        if (head === DEFAULT_AGENT_ACCOUNT_ID) {
+            const provider = PROVIDER_IDS.find((p) => p === tail);
+            return provider ? defaultAgentProfile(provider) : null;
+        }
+        try {
+            const stored = (await loadAgentAccounts()).accounts.find((a) => a.id === id);
+            return stored ? resolveStoredProfile(stored) : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    /** Validate a client-supplied config dir. Returns the error text, or null when it is usable. */
+    const checkProfileDir = (configDir) => {
+        if (CONTROL_CHARS_RE.test(configDir))
+            return 'folder must not contain control characters';
+        const expanded = expandTilde(configDir);
+        // Absolute after expansion: a relative dir would resolve against whatever cwd the agent
+        // happens to be spawned in, which for a task is a throwaway worktree. Through
+        // `isAbsoluteConfigDir`, never a leading-`/` test — see its note: a string test refuses every
+        // real Windows path, and this is the only gate the Add-account dialog has.
+        if (!isAbsoluteConfigDir(expanded))
+            return `folder must be an absolute path: ${configDir}`;
+        return null;
+    };
+    /** Refuse a dir that is already some other account's (or the default's), compared through
+     *  `realpath` — two spellings of one directory would be two accounts silently sharing one
+     *  session store, and "which one am I logged into?" would stop having an answer. */
+    const conflictingProfile = async (profiles, provider, path, exceptId) => {
+        if (await sameProfileDir(path, defaultAgentProfile(provider).path)) {
+            return 'that is already this agent\'s default folder';
+        }
+        for (const candidate of profiles) {
+            if (candidate.provider !== provider || candidate.id === exceptId)
+                continue;
+            if (await sameProfileDir(path, expandTilde(candidate.configDir))) {
+                return `that folder is already used by "${candidate.label || candidate.id}"`;
+            }
+        }
+        return null;
+    };
+    const agentProfilesRoutes = new Hono()
+        .get('/workspace/agent-profiles', async (c) => {
+        const editable = capabilities().localHandoff;
+        // Hosted mode withholds the listing entirely rather than serving it read-only: the paths
+        // are the host disclosure, so an empty list is the only honest hosted answer.
+        //
+        // ONE body object, never a hosted `return` and a local `return`: two returns let hono
+        // narrow `editable` to the literal `false`/`true` of each branch, and the contract's
+        // honest `z.boolean()` then reads as wider than the route. Same shape as
+        // `listAgentConfig`, which carries the same flag for the same reason.
+        let store = defaultAgentAccountStore();
+        if (editable) {
+            try {
+                store = await loadAgentAccounts();
+            }
+            catch {
+                // an unreadable home degrades to "no extra accounts", never a failed request
+            }
+        }
+        const profiles = editable
+            ? await Promise.all(listAgentProfiles(store, PROVIDER_IDS).map(agentProfileBody))
+            : [];
+        return c.json({
+            editable,
+            profiles,
+            profileCapableProviders: [...PROFILE_CAPABLE_PROVIDERS],
+            // Which account each project uses, keyed by repo root. Served here rather than on the
+            // project registry because it lives in the same file as the accounts it names.
+            selections: editable ? store.selections : {},
+            /** The machine-wide fallback, for repos that have chosen nothing. Withheld in hosted mode
+             *  on the same terms as the rest of this family. */
+            defaults: editable ? store.defaults : {},
+        });
+    })
+        .post('/workspace/agent-profiles', jsonZodValidator(() => createAgentProfileSchema), async (c) => {
+        if (!capabilities().localHandoff)
+            return c.json(hostedProfileRefusal, 409);
+        const { provider, configDir, label } = c.req.valid('json');
+        if (!supportsProfiles(provider)) {
+            return c.json({ error: `${provider} cannot carry more than one account` }, 400);
+        }
+        const dirError = checkProfileDir(configDir);
+        if (dirError)
+            return c.json({ error: dirError }, 400);
+        // Read-first, exactly like `POST /projects`: the duplicate check needs `realpath`, and the
+        // merge-write mutator is deliberately SYNCHRONOUS so the read→rename window stays as small
+        // as it is for every other writer of this file. Two processes adding the same folder in
+        // that window would both win — a cosmetic duplicate, not a correctness problem, since the
+        // schema's id dedupe is what keeps resolution deterministic.
+        let existing = [];
+        try {
+            existing = (await loadAgentAccounts()).accounts;
+        }
+        catch {
+            // unreadable store — the merge-write below reports the real failure
+        }
+        const conflict = await conflictingProfile(existing, provider, expandTilde(configDir));
+        if (conflict !== null)
+            return c.json({ error: conflict }, 409);
+        let created;
+        try {
+            await mergeWriteAgentAccounts((store) => {
+                const id = allocateAgentProfileId(label ?? configDir, store.accounts.map((a) => a.id));
+                created = {
+                    id,
+                    provider,
+                    configDir,
+                    label: label?.trim() || id,
+                    addedAt: new Date().toISOString(),
+                };
+                store.accounts.push(created);
+            });
+        }
+        catch (err) {
+            return c.json({ error: err instanceof Error ? err.message : String(err) }, 500);
+        }
+        if (!created)
+            return c.json({ error: 'account could not be saved' }, 500);
+        // A brand-new account is the one thing the boot warm could not have known about, so learn it
+        // now rather than only when something asks. Still off the response: the row is returned with
+        // `status` absent (the listing's rule), the pane shows Checking…, and its follow-up request
+        // joins this same in-flight probe.
+        const account = resolveStoredProfile(created);
+        const created201 = await agentProfileBody(account);
+        void providerAuth
+            .profileStatus(account.provider, { id: account.id, configDir: account.path })
+            .catch(() => { });
+        return c.json({ profile: created201 }, 201);
+    })
+        .patch('/workspace/agent-profiles/:id', paramZodValidator(z.object({ id: z.string() })), jsonZodValidator(() => updateAgentProfileSchema), async (c) => {
+        if (!capabilities().localHandoff)
+            return c.json(hostedProfileRefusal, 409);
+        const id = c.req.param('id');
+        const { label, configDir } = c.req.valid('json');
+        if (configDir !== undefined) {
+            const dirError = checkProfileDir(configDir);
+            if (dirError)
+                return c.json({ error: dirError }, 400);
+        }
+        // Read-first (see POST above, and `PATCH /projects`): a well-formed but unknown id must
+        // 404 WITHOUT rewriting the config, and the duplicate check needs async `realpath`.
+        let existing = [];
+        try {
+            existing = (await loadAgentAccounts()).accounts;
+        }
+        catch {
+            // unreadable store — treated as unknown, like DELETE and PATCH /projects
+        }
+        const current = existing.find((a) => a.id === id);
+        if (!current)
+            return c.json({ error: `unknown account: ${id}` }, 404);
+        if (configDir !== undefined) {
+            const conflict = await conflictingProfile(existing, current.provider, expandTilde(configDir), id);
+            if (conflict !== null)
+                return c.json({ error: conflict }, 409);
+        }
+        let updated;
+        try {
+            await mergeWriteAgentAccounts((store) => {
+                const entry = store.accounts.find((a) => a.id === id);
+                if (!entry)
+                    return; // lost a race with a concurrent delete — answered below
+                // Mutated in place so `.passthrough()` keys on the row survive.
+                if (label !== undefined)
+                    entry.label = label.trim() || entry.id;
+                if (configDir !== undefined)
+                    entry.configDir = configDir;
+                updated = entry;
+            });
+        }
+        catch (err) {
+            return c.json({ error: err instanceof Error ? err.message : String(err) }, 500);
+        }
+        if (!updated)
+            return c.json({ error: `unknown account: ${id}` }, 404);
+        // The dir may have moved under a cached probe — drop THIS account's answer so the response
+        // reports the new folder's state rather than the old one's, and leave every other account's
+        // warm answer alone (it is still true). Then re-learn it in the background, so the server's
+        // knowledge is complete again whether or not a cockpit is open to ask; the pane's own
+        // request for this row joins the same in-flight probe rather than spawning a second.
+        const repointed = resolveStoredProfile(updated);
+        providerAuth.forgetProfileStatus(repointed.provider, repointed.id);
+        const body = await agentProfileBody(repointed);
+        void providerAuth
+            .profileStatus(repointed.provider, { id: repointed.id, configDir: repointed.path })
+            .catch(() => { });
+        return c.json({ profile: body });
+    })
+        /**
+         * One account's authentication state, probed for real.
+         *
+         * Separate from the listing because a probe shells out to an agent CLI: keeping it here lets
+         * the pane paint immediately and fill each row in as its answer lands, instead of every cold
+         * load blocking on N spawns. `refresh=1` drops this account's cached answer and re-probes, for
+         * the "Check again" affordance — the cache itself holds a connected answer for minutes and an
+         * unsettled one for a minute (`cacheTtlFor` in `core/provider-auth.ts`).
+         */
+        .get('/workspace/agent-profiles/:id/status', paramZodValidator(z.object({ id: z.string() })), queryZodValidator(z.object({ refresh: queryValue.refine((v) => v === undefined || v === '1') }), { message: 'refresh must be 1 when provided' }), async (c) => {
+        if (!capabilities().localHandoff)
+            return c.json(hostedProfileRefusal, 409);
+        const account = await accountById(c.req.param('id'));
+        if (!account)
+            return c.json({ error: `unknown account: ${c.req.param('id')}` }, 404);
+        const refresh = c.req.valid('query').refresh === '1';
+        // The discovered account's row is the one `GET /api/v1/providers/status` owns, so it comes
+        // from there — enablement included, which a bare probe does not know about.
+        if (account.isDefault) {
+            const all = await providerStatus(refresh ? { refresh: true } : undefined);
+            const row = all.providers.find((candidate) => candidate.provider === account.provider);
+            return c.json({ status: row ?? { provider: account.provider, status: 'unknown' } });
+        }
+        // "Check again" re-probes THIS account only — the other accounts' warm answers are not
+        // invalidated by asking about this one.
+        if (refresh)
+            providerAuth.forgetProfileStatus(account.provider, account.id);
+        return c.json({
+            status: await providerAuth.profileStatus(account.provider, {
+                id: account.id,
+                configDir: account.path,
+            }),
+        });
+    })
+        /**
+         * Who this account is signed in AS — the pane's "Show details".
+         *
+         * A separate, on-demand route rather than a field on the listing, and that is what makes
+         * "hidden by default" real: an email carried by the listing would already be in the response,
+         * the query cache and devtools, whatever the UI chose to render. `provider-auth.ts` keeps
+         * identity out of ITS boundary on purpose; this is the deliberate, local-only, opt-in
+         * exception — not a widening of that rule. Never logged, never persisted.
+         */
+        .get('/workspace/agent-profiles/:id/details', paramZodValidator(z.object({ id: z.string() })), async (c) => {
+        if (!capabilities().localHandoff)
+            return c.json(hostedProfileRefusal, 409);
+        const account = await accountById(c.req.param('id'));
+        if (!account)
+            return c.json({ error: `unknown account: ${c.req.param('id')}` }, 404);
+        return c.json(await readAccountIdentity(account.provider, account.path));
+    })
+        /**
+         * Open one of this account's own config files — or its folder — in a local app.
+         *
+         * `file` is a catalog ID from the account's own `files`, never a path: the client cannot name a
+         * location, so there is no traversal surface here at all (the same rule
+         * `/api/v1/agent-config/:id` follows). `folder` is the one extra keyword, and it resolves to
+         * the account's dir rather than anything the caller spelled.
+         */
+        .post('/workspace/agent-profiles/:id/open', paramZodValidator(z.object({ id: z.string() })), jsonZodValidator(() => openAgentAccountFileSchema), async (c) => {
+        if (!capabilities().localHandoff)
+            return c.json(hostedProfileRefusal, 409);
+        const account = await accountById(c.req.param('id'));
+        if (!account)
+            return c.json({ error: `unknown account: ${c.req.param('id')}` }, 404);
+        const { file, target } = c.req.valid('json');
+        let path;
+        if (file === 'folder') {
+            path = account.path;
+        }
+        else {
+            const match = (await accountFiles(account)).find((f) => f.id === file);
+            if (!match)
+                return c.json({ error: `unknown file: ${file}` }, 404);
+            path = match.path;
+        }
+        // A file the agent has not written yet has nothing to open; say so rather than hand the OS
+        // a missing path and report success.
+        if (!(await statConfigPath(path)).exists && file !== 'folder') {
+            return c.json({ error: `this account has no ${basename(path)} yet` }, 409);
+        }
+        // `target` names a detected app; absent means the OS default handler. Either way the PATH
+        // came from the catalog, so an editor is only ever pointed inside this account's folder.
+        //
+        // Which targets APPLY is checked here rather than left to the UI, because two of them are
+        // actively wrong rather than merely useless: `terminal` runs `cd <path>`, which fails on a
+        // file, and a `cli:<runner>` handoff would start an agent session inside the config folder.
+        // A route is a surface of its own; it refuses what it cannot do correctly.
+        if (target !== undefined) {
+            if (agentCliRunner(target) !== null) {
+                return c.json({ error: 'agent CLIs open a task worktree, not a config folder' }, 400);
+            }
+            if (target === 'terminal' && file !== 'folder') {
+                return c.json({ error: 'a terminal opens a folder, not a file' }, 400);
+            }
+            if (!detectOpenTargets().some((candidate) => candidate.id === target)) {
+                return c.json({ error: `no such app on this machine: ${target}` }, 400);
+            }
+        }
+        const opened = target === undefined
+            ? await openFile(path)
+            : await openApp(target, path);
+        if (!opened)
+            return c.json({ error: `could not open ${basename(path)}`, path }, 409);
+        return c.json({ opened: true, path });
+    })
+        // Which account a PROJECT uses. On the accounts family rather than `PATCH /api/v1/projects`
+        // because the selection is stored beside the accounts it names — one file, one atomic write,
+        // and nothing about it can be dropped by a cezar version that never heard of accounts.
+        .put('/workspace/agent-profiles/selection', jsonZodValidator(() => selectAgentProfileSchema), async (c) => {
+        if (!capabilities().localHandoff)
+            return c.json(hostedProfileRefusal, 409);
+        const { projectId, provider, profileId } = c.req.valid('json');
+        // `null` writes the MACHINE-WIDE default instead of one repo's selection: the account any
+        // repo that has chosen nothing uses, so a second login is set up once rather than per
+        // checkout. No project to resolve, and therefore no 404 path.
+        let root = null;
+        if (projectId !== null) {
+            const resolvedId = projectId === 'default' ? await resolveBootProject() : projectId;
+            // Keyed by repo ROOT, so the selection survives the registry being rebuilt and needs no
+            // cross-reference into config.json. An unknown project is a 404 rather than an orphan
+            // entry nobody will ever read.
+            root = await projectRootFor(resolvedId);
+            if (root === null)
+                return c.json({ error: `unknown project: ${projectId}` }, 404);
+        }
+        // A user naming an account that does not exist gets told so — the opposite of how RUN
+        // resolution treats a dangling stored id, and deliberately: a run has no better answer
+        // than the default, a person does.
+        if (profileId !== null && profileId !== DEFAULT_AGENT_ACCOUNT_ID) {
+            const account = await resolveWorkspaceProfile(provider, profileId);
+            if ('error' in account)
+                return c.json({ error: account.error }, 400);
+        }
+        let store;
+        try {
+            store = await mergeWriteAgentAccounts((current) => {
+                // One rule, two targets: the machine default is the same per-provider shape as a repo's
+                // selection, so it clears the same way rather than growing its own spelling.
+                const selection = root === null ? current.defaults : current.selections[root] ?? {};
+                // `null` and the reserved `default` both mean "back to the discovered account", which
+                // is stored as ABSENCE — the default id is never written to the file.
+                if (profileId === null || profileId === DEFAULT_AGENT_ACCOUNT_ID)
+                    delete selection[provider];
+                else
+                    selection[provider] = profileId;
+                // The machine default keeps an emptied object where a repo selection is deleted, and
+                // that asymmetry is the schema's, not an oversight: `defaults` is one FIXED field with
+                // `.default(() => ({}))`, so `mergeWriteAgentAccounts` re-materializes it on the next
+                // write no matter what this one omits (verified). `selections` is a growing MAP, where
+                // an emptied entry is a row per repo ever touched that says nothing. The rule stated
+                // for `agentDefaults.models` — "absence is the same answer" — applies there because
+                // that key is `.optional()`, so deleting it actually sticks.
+                if (root === null)
+                    current.defaults = selection;
+                else if (Object.keys(selection).length === 0)
+                    delete current.selections[root];
+                else
+                    current.selections[root] = selection;
+            });
+        }
+        catch (err) {
+            return c.json({ error: err instanceof Error ? err.message : String(err) }, 500);
+        }
+        return c.json({ selections: store.selections, defaults: store.defaults });
+    })
+        .delete('/workspace/agent-profiles/:id', paramZodValidator(z.object({ id: z.string() })), async (c) => {
+        if (!capabilities().localHandoff)
+            return c.json(hostedProfileRefusal, 409);
+        const id = c.req.param('id');
+        let removed = false;
+        // Captured inside the mutator, because after the write there is nothing left to ask which
+        // provider this account belonged to — and the eviction below is keyed by it.
+        let removedProvider;
+        try {
+            await mergeWriteAgentAccounts((store) => {
+                const before = store.accounts.length;
+                removedProvider = store.accounts.find((a) => a.id === id)?.provider;
+                store.accounts = store.accounts.filter((a) => a.id !== id);
+                removed = store.accounts.length < before;
+                if (!removed)
+                    return;
+                // Scrub every reference IN THE SAME MUTATOR — the reason selections share this file.
+                // A two-call delete-then-scrub can be observed mid-way by another cezar process on
+                // this machine, which would then resolve a dangling id; harmless today (it degrades
+                // to the default) but only by luck.
+                for (const [root, selection] of Object.entries(store.selections)) {
+                    for (const key of Object.keys(selection)) {
+                        if (selection[key] === id)
+                            delete selection[key];
+                    }
+                    if (Object.keys(selection).length === 0)
+                        delete store.selections[root];
+                }
+            });
+        }
+        catch (err) {
+            return c.json({ error: err instanceof Error ? err.message : String(err) }, 500);
+        }
+        if (!removed)
+            return c.json({ error: `unknown account: ${id}` }, 404);
+        // Only this account's answer: it is about to stop existing, and holding it would let a
+        // re-added account with the same id read the deleted one's state.
+        providerAuth.forgetProfileStatus(removedProvider, id);
+        return c.json({ removed: true, id });
+    });
     // ---- workspace projects (multi-project spec) -----------------------------
     // The registered-project list for the cockpit sidebar. Same-origin (unlike
     // health), so absolute `root`s are fine here. `listProjects()` TTL-caches
@@ -939,7 +1898,9 @@ export function createApp(deps) {
             return defaultWorkspaceConfig().browseRoot;
         }
     };
-    app.get('/api/projects', async (c) => {
+    // ---- chained family: project registry (workspace-level) ----
+    const projectsRoutes = new Hono()
+        .get('/projects', async (c) => {
         let projects = [];
         let projectsDir = defaultWorkspaceConfig().projectsDir;
         try {
@@ -958,36 +1919,223 @@ export function createApp(deps) {
             projectsDir,
         };
         return c.json(body);
-    });
-    // Register an existing folder (multi-project spec, "Add project" — the
-    // folder-browser dialog's commit step, step 4.2). Workspace-level like its
-    // GET twin. Everything here is a guard; the registry write itself is one
-    // idempotent `registerProject` call.
-    const registerProjectSchema = z.object({
-        root: z.string().trim().min(1).max(4096),
-    });
-    /**
-     * The register-a-folder half of `POST /api/projects`, factored out so the
-     * checkout route (step 4.3) commits its fresh clone through the SAME guards
-     * and the same `project-added` emission rather than a second copy of them.
-     * Returns the status + body for the caller to answer with.
-     */
-    const registerFolder = async (spelled, source) => {
+    })
+        .post('/projects', jsonZodValidator(() => registerProjectSchema, { message: 'root must be a non-empty path' }), async (c) => {
+        const parsed = { data: c.req.valid('json') };
+        const registered = await registerFolder(parsed.data.root, 'local');
+        if (registered.status !== 200)
+            return c.json(registered.body, registered.status);
+        return c.json(registered.body, 200);
+    })
+        .delete('/projects/:projectId', async (c) => {
         if (capabilities().singleProject) {
-            return { status: 409, body: singleProjectRefusal('adding projects') };
-        }
-        // `~` is expanded for the same reason `/api/fs/browse` expands it: the
-        // dialog hands back absolute paths, but a hand-written body (curl, a
-        // future CLI) spells home the way a shell does.
-        const requested = expandTilde(spelled);
-        if (!requested.startsWith('/')) {
-            return {
-                status: 400,
-                body: { error: `not a folder: ${spelled} is not an absolute path` },
-            };
+            return c.json(singleProjectRefusal('removing projects'), 409);
         }
-        // Hosted mode: the same root the picker is narrowed to, re-checked — see
-        // `isInsideBrowseRoot`. Local mode deliberately has NO containment: a
+        const raw = c.req.param('projectId');
+        // Same gate the scoped-route resolver applies, and the same 404 wording —
+        // a malformed id is an unknown project, not a validation essay.
+        if (!projectIdSchema.safeParse(raw).success) {
+            return c.json({ error: `unknown project: ${raw}` }, 404);
+        }
+        const bootId = await resolveBootProject();
+        // `default` is the boot alias everywhere else in the API; honour it here
+        // too rather than 404ing a spelling the cockpit is allowed to use.
+        const id = raw === 'default' ? bootId : raw;
+        let entry;
+        try {
+            entry = (await loadWorkspaceConfig()).projects.find((p) => p.id === id);
+        }
+        catch {
+            // unreadable workspace — there is nothing to remove, and saying so is
+            // more useful than a 500 the user cannot act on
+        }
+        if (!entry)
+            return c.json({ error: `unknown project: ${id}` }, 404);
+        // The boot project is refused, not removed: `cezar serve` re-registers the
+        // repo it was started in on every boot, so "removing" it would undo itself
+        // at the next restart while breaking this session's sidebar in the
+        // meantime. The pane disables the button and says the same thing.
+        if (id === bootId) {
+            return c.json({
+                error: `cezar is serving ${entry.name} right now — it re-registers itself at every start, so it cannot be removed from here`,
+            }, 409);
+        }
+        const active = activeRunCount(id);
+        if (active > 0) {
+            return c.json({
+                error: `${entry.name} has ${active} running task${active === 1 ? '' : 's'} — cancel or finish ${active === 1 ? 'it' : 'them'} before removing the project`,
+                runningTasks: active,
+            }, 409);
+        }
+        let removed;
+        try {
+            removed = await removeProject(id);
+        }
+        catch (err) {
+            // e.g. a read-only home — nothing was persisted (atomic tmp+rename).
+            return c.json({ error: err instanceof Error ? err.message : String(err) }, 500);
+        }
+        // Lost a race with another writer (or another cezar process): the entry is
+        // gone, which is what the caller wanted, but say it honestly.
+        if (!removed)
+            return c.json({ error: `unknown project: ${id}` }, 404);
+        // In-process handles for a project no route can reach any more: store
+        // closed (index flushed), manager's timers and usage subscription dropped.
+        contexts.dispose(id);
+        workspaceEvents.emit('project-removed', { id });
+        const body = { removed: true, id };
+        return c.json(body);
+    })
+        // Edit the per-project registry fields the cockpit owns: the concurrency ceiling (spec
+        // 2026-07-22-per-project-concurrency) and the grouping tags (spec
+        // 2026-08-10-global-tasks-and-project-tags). A PATCH (not PUT) because it touches named
+        // fields and leaves the rest of the entry alone, and a distinct route from POST
+        // (register-a-folder) to keep register vs. edit semantics clear.
+        //
+        // The body schema is the CONTRACT's, passed directly rather than restated behind a thunk:
+        // it is already in scope, and a second copy is a second thing to keep in step. Its bounds
+        // mirror `workspaceProjectSchema` (config.ts) exactly, so a value this route accepts can
+        // never be degraded away by the next load's `.catch`.
+        //
+        // Deliberately NOT the home of the agent-account selection: that lives in
+        // `~/.cezar/agent-accounts.json` beside the accounts it names, so a cezar version that has
+        // never heard of accounts cannot drop it (see workspace/agent-accounts.ts).
+        .patch('/projects/:projectId', jsonZodValidator(updateProjectInputSchema), async (c) => {
+        if (capabilities().singleProject) {
+            return c.json(singleProjectRefusal('editing projects'), 409);
+        }
+        const raw = c.req.param('projectId');
+        // Same gate + 404 wording as DELETE: a malformed id is an unknown project.
+        if (!projectIdSchema.safeParse(raw).success) {
+            return c.json({ error: `unknown project: ${raw}` }, 404);
+        }
+        const parsed = { data: c.req.valid('json') };
+        // `default` is the boot alias the cockpit is allowed to use everywhere else.
+        const id = raw === 'default' ? await resolveBootProject() : raw;
+        const { maxParallel, tags } = parsed.data;
+        // Read-first (mirroring DELETE, server.ts:1252-1258): a well-formed but
+        // unknown id must 404 WITHOUT rewriting the config — otherwise it would both
+        // do a needless full-config tmp+rename and, on a read-only home, surface the
+        // write failure as a 500 where the honest answer is 404.
+        let known = false;
+        try {
+            known = (await loadWorkspaceConfig()).projects.some((p) => p.id === id);
+        }
+        catch {
+            // unreadable workspace — treat as unknown; the read-only case answers 404,
+            // not a 500 the caller cannot act on (same reasoning as DELETE).
+        }
+        if (!known)
+            return c.json({ error: `unknown project: ${id}` }, 404);
+        let updated;
+        try {
+            await mergeWriteWorkspaceConfig((config) => {
+                const entry = config.projects.find((p) => p.id === id);
+                if (!entry)
+                    return; // lost a race with a concurrent remove — answered below
+                // Each key is applied only when the body NAMED it: a PATCH that says
+                // nothing about a field must leave it exactly as it was, which is what
+                // keeps the tags editor from clearing a concurrency ceiling (and the
+                // pre-tags `{ maxParallel }` body from clearing tags). null clears;
+                // a value sets. Mutated in place so `.passthrough()` keys survive.
+                if (maxParallel !== undefined) {
+                    if (maxParallel === null)
+                        delete entry.maxParallel;
+                    else
+                        entry.maxParallel = maxParallel;
+                }
+                if (tags !== undefined) {
+                    // Normalized on the way IN, so every reader — this API, the CLI, the
+                    // global Tasks page — sees one spelling per tag and never has to
+                    // fold case itself.
+                    const normalized = normalizeProjectTags(tags);
+                    if (normalized === undefined)
+                        delete entry.tags;
+                    else
+                        entry.tags = normalized;
+                }
+                updated = entry;
+            });
+        }
+        catch (err) {
+            // e.g. a read-only home — nothing was persisted (atomic tmp+rename).
+            return c.json({ error: err instanceof Error ? err.message : String(err) }, 500);
+        }
+        // Raced with a concurrent removal between the read and the write.
+        if (!updated)
+            return c.json({ error: `unknown project: ${id}` }, 404);
+        // The new ceiling takes effect WITHOUT a restart: refresh the shared
+        // semaphore's snapshot and pump every manager — the same live-apply hook
+        // `PUT /api/workspace/config` fires for a workspace-cap change.
+        await deps.semaphore?.refresh();
+        const body = {
+            project: { ...updated, ...(await probeProjectStatus(updated.root)) },
+        };
+        return c.json(body);
+    })
+        .post('/projects/checkout', jsonZodValidator(() => checkoutSchema, { message: 'url must be a GitHub repository' }), async (c) => {
+        if (capabilities().singleProject) {
+            return c.json(singleProjectRefusal('adding projects'), 409);
+        }
+        const parsed = { data: c.req.valid('json') };
+        const { url, name, checkoutId } = parsed.data;
+        const result = await checkoutRepo({
+            url,
+            name,
+            checkoutId,
+            projectsDir: expandTilde(await workspaceProjectsDir()),
+            onProgress: (event) => workspaceEvents.emit('checkout-progress', event),
+            // A closed dialog / navigated-away tab aborts the request; the clone is
+            // killed and its partial directory removed rather than left running.
+            signal: c.req.raw.signal,
+            ...(deps.cloneRunner ? { run: deps.cloneRunner } : {}),
+        });
+        if (!result.ok) {
+            // `reason` rides along on the 503 (`gh` unavailable) — the spec's
+            // `{ error, reason }` degradation, mirroring the GitHub pane.
+            return c.json('reason' in result ? { error: result.error, reason: result.reason } : { error: result.error }, result.status);
+        }
+        const registered = await registerFolder(result.target, 'checkout');
+        if (registered.status !== 200) {
+            // The clone SUCCEEDED and its files are legitimately the user's, so this
+            // path deliberately does NOT clean up — an unregisterable checkout is a
+            // registry problem, not a reason to delete a repo we just fetched. Say
+            // where it is so they can register it by hand.
+            const { body } = registered;
+            const error = 'error' in body && body.error ? body.error : 'could not register the checkout';
+            return c.json({ error: `${error} (the clone is at ${result.target})` }, registered.status);
+        }
+        return c.json(registered.body, 200);
+    });
+    // Register an existing folder (multi-project spec, "Add project" — the
+    // folder-browser dialog's commit step, step 4.2). Workspace-level like its
+    // GET twin. Everything here is a guard; the registry write itself is one
+    // idempotent `registerProject` call.
+    const registerProjectSchema = z.object({
+        root: z.string().trim().min(1).max(4096),
+    });
+    /**
+     * The register-a-folder half of `POST /api/projects`, factored out so the
+     * checkout route (step 4.3) commits its fresh clone through the SAME guards
+     * and the same `project-added` emission rather than a second copy of them.
+     * Returns the status + body for the caller to answer with.
+     */
+    const registerFolder = async (spelled, source) => {
+        if (capabilities().singleProject) {
+            return { status: 409, body: singleProjectRefusal('adding projects') };
+        }
+        // `~` is expanded for the same reason `/api/fs/browse` expands it: the
+        // dialog hands back absolute paths, but a hand-written body (curl, a
+        // future CLI) spells home the way a shell does.
+        const requested = expandTilde(spelled);
+        if (!requested.startsWith('/')) {
+            return {
+                status: 400,
+                body: { error: `not a folder: ${spelled} is not an absolute path` },
+            };
+        }
+        // Hosted mode: the same root the picker is narrowed to, re-checked — see
+        // `isInsideBrowseRoot`. Local mode deliberately has NO containment: a
         // project under `/srv/code` is a normal local setup and `cezar serve`
         // registers it today.
         //
@@ -1079,13 +2227,6 @@ export function createApp(deps) {
         workspaceEvents.emit('project-added', { project });
         return { status: 200, body: { project } };
     };
-    app.post('/api/projects', async (c) => {
-        const parsed = registerProjectSchema.safeParse(await c.req.json().catch(() => null));
-        if (!parsed.success)
-            return c.json({ error: 'root must be a non-empty path' }, 400);
-        const { status, body } = await registerFolder(parsed.data.root, 'local');
-        return c.json(body, status);
-    });
     // Deregister a project (multi-project spec, step 4.4 — Settings → Projects,
     // the per-row "Remove"). READ THIS BEFORE TOUCHING THE HANDLER: the ONLY
     // durable effect allowed here is dropping one entry from
@@ -1120,136 +2261,59 @@ export function createApp(deps) {
             return 0;
         return ctx.store.listRuns().filter((run) => ACTIVE_RUN_STATUSES.has(run.status)).length;
     };
-    app.delete('/api/projects/:projectId', async (c) => {
-        if (capabilities().singleProject) {
-            return c.json(singleProjectRefusal('removing projects'), 409);
-        }
-        const raw = c.req.param('projectId');
-        // Same gate the scoped-route resolver applies, and the same 404 wording —
-        // a malformed id is an unknown project, not a validation essay.
-        if (!projectIdSchema.safeParse(raw).success) {
-            return c.json({ error: `unknown project: ${raw}` }, 404);
-        }
+    // Workspace-level by design: update state spans project and global installs,
+    // but the selected registered project supplies the safe, server-owned cwd.
+    const skillsUpdateInputSchema = z.object({ projectId: projectIdSchema }).strict();
+    const resolveSkillsUpdateRoot = async (raw) => {
+        if (!projectIdSchema.safeParse(raw).success)
+            return { status: 404, error: `unknown project: ${raw}` };
         const bootId = await resolveBootProject();
-        // `default` is the boot alias everywhere else in the API; honour it here
-        // too rather than 404ing a spelling the cockpit is allowed to use.
-        const id = raw === 'default' ? bootId : raw;
-        let entry;
-        try {
-            entry = (await loadWorkspaceConfig()).projects.find((p) => p.id === id);
-        }
-        catch {
-            // unreadable workspace — there is nothing to remove, and saying so is
-            // more useful than a 500 the user cannot act on
-        }
-        if (!entry)
-            return c.json({ error: `unknown project: ${id}` }, 404);
-        // The boot project is refused, not removed: `cezar serve` re-registers the
-        // repo it was started in on every boot, so "removing" it would undo itself
-        // at the next restart while breaking this session's sidebar in the
-        // meantime. The pane disables the button and says the same thing.
-        if (id === bootId) {
-            return c.json({
-                error: `cezar is serving ${entry.name} right now — it re-registers itself at every start, so it cannot be removed from here`,
-            }, 409);
-        }
-        const active = activeRunCount(id);
-        if (active > 0) {
-            return c.json({
-                error: `${entry.name} has ${active} running task${active === 1 ? '' : 's'} — cancel or finish ${active === 1 ? 'it' : 'them'} before removing the project`,
-                runningTasks: active,
-            }, 409);
-        }
-        let removed;
-        try {
-            removed = await removeProject(id);
+        if (raw === 'default' || raw === bootId)
+            return { root: bootRoot };
+        const project = (await loadWorkspaceConfig()).projects.find((entry) => entry.id === raw);
+        if (!project)
+            return { status: 404, error: `unknown project: ${raw}` };
+        if ((await probeProjectStatus(project.root)).status === 'missing') {
+            return { status: 409, error: `project folder not found: ${raw}` };
         }
-        catch (err) {
-            // e.g. a read-only home — nothing was persisted (atomic tmp+rename).
-            return c.json({ error: err instanceof Error ? err.message : String(err) }, 500);
-        }
-        // Lost a race with another writer (or another cezar process): the entry is
-        // gone, which is what the caller wanted, but say it honestly.
-        if (!removed)
-            return c.json({ error: `unknown project: ${id}` }, 404);
-        // In-process handles for a project no route can reach any more: store
-        // closed (index flushed), manager's timers and usage subscription dropped.
-        contexts.dispose(id);
-        workspaceEvents.emit('project-removed', { id });
-        const body = { removed: true, id };
-        return c.json(body);
-    });
-    // Edit one field of an existing registry entry (spec
-    // 2026-07-22-per-project-concurrency): the per-project concurrency ceiling.
-    // A PATCH (not PUT) because it touches a single field, and a distinct route
-    // from POST (register-a-folder) to keep register vs. edit semantics clear.
-    // `maxParallel: null` clears the override back to "inherit the workspace
-    // cap". Bounds mirror `workspaceProjectSchema` (config.ts) exactly, so a
-    // value this route accepts can never be degraded away by the next load's
-    // `.catch`.
-    const updateProjectSchema = z.object({
-        maxParallel: z.number().int().min(1).max(16).nullable(),
-    });
-    app.patch('/api/projects/:projectId', async (c) => {
-        if (capabilities().singleProject) {
-            return c.json(singleProjectRefusal('editing projects'), 409);
-        }
-        const raw = c.req.param('projectId');
-        // Same gate + 404 wording as DELETE: a malformed id is an unknown project.
-        if (!projectIdSchema.safeParse(raw).success) {
-            return c.json({ error: `unknown project: ${raw}` }, 404);
-        }
-        const parsed = updateProjectSchema.safeParse(await c.req.json().catch(() => null));
-        if (!parsed.success) {
-            return c.json({ error: parsed.error.issues.map((i) => i.message).join('; ') }, 400);
-        }
-        // `default` is the boot alias the cockpit is allowed to use everywhere else.
-        const id = raw === 'default' ? await resolveBootProject() : raw;
-        const { maxParallel } = parsed.data;
-        // Read-first (mirroring DELETE, server.ts:1252-1258): a well-formed but
-        // unknown id must 404 WITHOUT rewriting the config — otherwise it would both
-        // do a needless full-config tmp+rename and, on a read-only home, surface the
-        // write failure as a 500 where the honest answer is 404.
-        let known = false;
-        try {
-            known = (await loadWorkspaceConfig()).projects.some((p) => p.id === id);
-        }
-        catch {
-            // unreadable workspace — treat as unknown; the read-only case answers 404,
-            // not a 500 the caller cannot act on (same reasoning as DELETE).
-        }
-        if (!known)
-            return c.json({ error: `unknown project: ${id}` }, 404);
-        let updated;
+        return { root: project.root };
+    };
+    const skillsUpdateResponse = async (state) => {
+        const config = await loadWorkspaceConfig();
+        return { ...state, autoUpdateEnabled: effectiveSkillsAutoUpdate(config), inherited: config.skillsAutoUpdate === undefined };
+    };
+    // ---- chained family: skills updates (workspace-level) ----
+    const skillsUpdateRoutes = new Hono()
+        .get('/workspace/skills-update', queryZodValidator(skillsUpdateInputSchema, { message: 'projectId is required' }), async (c) => {
+        const parsed = { data: c.req.valid('query') };
+        const resolved = await resolveSkillsUpdateRoot(parsed.data.projectId);
+        if ('error' in resolved)
+            return c.json({ error: resolved.error }, resolved.status);
+        const state = skillsUpdate.snapshot(resolved.root);
+        void skillsUpdate.check(resolved.root).catch(() => { });
+        return c.json(await skillsUpdateResponse(state));
+    })
+        .post('/workspace/skills-update/check', jsonZodValidator(skillsUpdateInputSchema, { message: 'body must contain only projectId' }), async (c) => {
+        const parsed = { data: c.req.valid('json') };
+        const resolved = await resolveSkillsUpdateRoot(parsed.data.projectId);
+        if ('error' in resolved)
+            return c.json({ error: resolved.error }, resolved.status);
+        return c.json(await skillsUpdateResponse(await skillsUpdate.check(resolved.root, true)));
+    })
+        .post('/workspace/skills-update/apply', jsonZodValidator(skillsUpdateInputSchema, { message: 'body must contain only projectId' }), async (c) => {
+        const parsed = { data: c.req.valid('json') };
+        const resolved = await resolveSkillsUpdateRoot(parsed.data.projectId);
+        if ('error' in resolved)
+            return c.json({ error: resolved.error }, resolved.status);
         try {
-            await mergeWriteWorkspaceConfig((config) => {
-                const entry = config.projects.find((p) => p.id === id);
-                if (!entry)
-                    return; // lost a race with a concurrent remove — answered below
-                // null clears the override; a number sets it. Mutated in place so
-                // `.passthrough()` keys on the entry survive.
-                if (maxParallel === null)
-                    delete entry.maxParallel;
-                else
-                    entry.maxParallel = maxParallel;
-                updated = entry;
-            });
-        }
-        catch (err) {
-            // e.g. a read-only home — nothing was persisted (atomic tmp+rename).
-            return c.json({ error: err instanceof Error ? err.message : String(err) }, 500);
+            return c.json(await skillsUpdateResponse(await skillsUpdate.update(resolved.root, true)));
+        }
+        catch (error) {
+            if (error instanceof SkillsUpdateConflictError) {
+                return c.json({ error: 'another skills update operation is running', state: await skillsUpdateResponse(skillsUpdate.snapshot(resolved.root)) }, 409);
+            }
+            throw error;
         }
-        // Raced with a concurrent removal between the read and the write.
-        if (!updated)
-            return c.json({ error: `unknown project: ${id}` }, 404);
-        // The new ceiling takes effect WITHOUT a restart: refresh the shared
-        // semaphore's snapshot and pump every manager — the same live-apply hook
-        // `PUT /api/workspace/config` fires for a workspace-cap change.
-        await deps.semaphore?.refresh();
-        const body = {
-            project: { ...updated, ...(await probeProjectStatus(updated.root)) },
-        };
-        return c.json(body);
     });
     // ---- GUI clone (multi-project spec, step 4.3) ----------------------------
     // "Add project → Clone from GitHub": clone into the checkout root, then
@@ -1267,41 +2331,6 @@ export function createApp(deps) {
         name: z.string().trim().max(128).optional(),
         checkoutId: z.string().trim().max(128).optional(),
     });
-    app.post('/api/projects/checkout', async (c) => {
-        if (capabilities().singleProject) {
-            return c.json(singleProjectRefusal('adding projects'), 409);
-        }
-        const parsed = checkoutSchema.safeParse(await c.req.json().catch(() => null));
-        if (!parsed.success)
-            return c.json({ error: 'url must be a GitHub repository' }, 400);
-        const { url, name, checkoutId } = parsed.data;
-        const result = await checkoutRepo({
-            url,
-            name,
-            checkoutId,
-            projectsDir: expandTilde(await workspaceProjectsDir()),
-            onProgress: (event) => workspaceEvents.emit('checkout-progress', event),
-            // A closed dialog / navigated-away tab aborts the request; the clone is
-            // killed and its partial directory removed rather than left running.
-            signal: c.req.raw.signal,
-            ...(deps.cloneRunner ? { run: deps.cloneRunner } : {}),
-        });
-        if (!result.ok) {
-            // `reason` rides along on the 503 (`gh` unavailable) — the spec's
-            // `{ error, reason }` degradation, mirroring the GitHub pane.
-            return c.json('reason' in result ? { error: result.error, reason: result.reason } : { error: result.error }, result.status);
-        }
-        const { status, body } = await registerFolder(result.target, 'checkout');
-        if (status !== 200) {
-            // The clone SUCCEEDED and its files are legitimately the user's, so this
-            // path deliberately does NOT clean up — an unregisterable checkout is a
-            // registry problem, not a reason to delete a repo we just fetched. Say
-            // where it is so they can register it by hand.
-            const error = 'error' in body && body.error ? body.error : 'could not register the checkout';
-            return c.json({ error: `${error} (the clone is at ${result.target})` }, status);
-        }
-        return c.json(body, 200);
-    });
     // ---- workspace settings (multi-project spec, step 2.7) -------------------
     // WORKSPACE-level routes: single-mount (never mirrored under /api/p/),
     // same-origin. The config routes carry the settings UI's slice of
@@ -1311,33 +2340,40 @@ export function createApp(deps) {
     const workspaceConfigBody = (config) => ({
         browseRoot: config.browseRoot,
         projectsDir: config.projectsDir,
+        skillsAutoUpdate: config.skillsAutoUpdate ?? null,
+        effectiveSkillsAutoUpdate: effectiveSkillsAutoUpdate(config),
+        composerDefaults: {
+            autonomous: config.composerDefaults.autonomous ?? null,
+            worktree: config.composerDefaults.worktree ?? null,
+            inheritedAutonomous: process.env.CEZ_AUTONOMOUS_DEFAULT === '0'
+                ? false
+                : process.env.CEZ_AUTONOMOUS_DEFAULT === '1'
+                    ? true
+                    : 'source-dependent',
+            inheritedWorktree: effectiveComposerDefault(undefined, process.env.CEZ_WORKTREE_DEFAULT, true),
+        },
         resources: {
             maxParallel: config.resources.maxParallel,
+            maxMonitoringSessions: config.resources.maxMonitoringSessions,
+            monitoringWakeIntervalMinutes: config.resources.monitoringWakeIntervalMinutes,
+            autoResumeOnUsageLimit: config.resources.autoResumeOnUsageLimit,
             memoryLimitMb: config.resources.memoryLimitMb,
             worktreeRetentionDefault: config.resources.worktreeRetentionDefault,
         },
+        // SPREAD, never `runner: maybeUndefined`: hono would type the key as always-present while
+        // `JSON.stringify` drops it, which is the exact drift `contract-parity` catches. And absent has
+        // to keep meaning "no opinion" here, or the fallback collapses into "always claude".
+        agentDefaults: {
+            ...(config.agentDefaults.runner !== undefined ? { runner: config.agentDefaults.runner } : {}),
+            ...(config.agentDefaults.models !== undefined ? { models: config.agentDefaults.models } : {}),
+        },
     });
-    app.get('/api/workspace/config', async (c) => c.json(workspaceConfigBody(await loadWorkspaceConfig())));
-    // Partial updates only — absent keys stay untouched. Bounds mirror the
-    // workspace schema (src/workspace/config.ts, step 1.2) exactly, so a value
-    // this route accepts can never be degraded away by the next load's `.catch`.
-    const workspaceConfigUpdateSchema = z.object({
-        browseRoot: z.string().trim().min(1).max(4096).optional(),
-        projectsDir: z.string().trim().min(1).max(4096).optional(),
-        resources: z
-            .object({
-            maxParallel: z.number().int().min(1).max(16).optional(),
-            memoryLimitMb: z.number().int().min(0).max(1_048_576).nullable().optional(),
-            worktreeRetentionDefault: z.number().int().min(0).max(1000).optional(),
-        })
-            .optional(),
-    });
-    app.put('/api/workspace/config', async (c) => {
-        const parsed = workspaceConfigUpdateSchema.safeParse(await c.req.json().catch(() => null));
-        if (!parsed.success) {
-            return c.json({ error: parsed.error.issues.map((i) => i.message).join('; ') }, 400);
-        }
-        const { browseRoot, projectsDir, resources } = parsed.data;
+    // ---- chained family: workspace settings + GUI prefs (workspace-level) ----
+    const workspaceConfigRoutes = new Hono()
+        .get('/workspace/config', async (c) => c.json(workspaceConfigBody(await loadWorkspaceConfig())))
+        .put('/workspace/config', jsonZodValidator(() => workspaceConfigUpdateSchema), async (c) => {
+        const parsed = { data: c.req.valid('json') };
+        const { browseRoot, projectsDir, skillsAutoUpdate, composerDefaults, resources, agentDefaults } = parsed.data;
         for (const [configuredRoot, create] of [
             [browseRoot, false],
             [projectsDir, true],
@@ -1376,13 +2412,57 @@ export function createApp(deps) {
                     config.browseRoot = browseRoot;
                 if (projectsDir !== undefined)
                     config.projectsDir = projectsDir;
+                if (skillsAutoUpdate === null)
+                    delete config.skillsAutoUpdate;
+                else if (skillsAutoUpdate !== undefined)
+                    config.skillsAutoUpdate = skillsAutoUpdate;
+                if (composerDefaults?.autonomous === null)
+                    delete config.composerDefaults.autonomous;
+                else if (composerDefaults?.autonomous !== undefined) {
+                    config.composerDefaults.autonomous = composerDefaults.autonomous;
+                }
+                if (composerDefaults?.worktree === null)
+                    delete config.composerDefaults.worktree;
+                else if (composerDefaults?.worktree !== undefined) {
+                    config.composerDefaults.worktree = composerDefaults.worktree;
+                }
                 if (resources?.maxParallel !== undefined)
                     config.resources.maxParallel = resources.maxParallel;
+                if (resources?.maxMonitoringSessions !== undefined) {
+                    config.resources.maxMonitoringSessions = resources.maxMonitoringSessions;
+                }
+                if (resources?.monitoringWakeIntervalMinutes !== undefined) {
+                    config.resources.monitoringWakeIntervalMinutes = resources.monitoringWakeIntervalMinutes;
+                }
+                if (resources?.autoResumeOnUsageLimit !== undefined) {
+                    config.resources.autoResumeOnUsageLimit = resources.autoResumeOnUsageLimit;
+                }
                 if (resources?.memoryLimitMb !== undefined)
                     config.resources.memoryLimitMb = resources.memoryLimitMb;
                 if (resources?.worktreeRetentionDefault !== undefined) {
                     config.resources.worktreeRetentionDefault = resources.worktreeRetentionDefault;
                 }
+                // `null` CLEARS back to "no opinion" — a partial patch cannot say that by omission,
+                // and leaving a stale runner behind would keep overriding repos that never chose.
+                if (agentDefaults?.runner === null)
+                    delete config.agentDefaults.runner;
+                else if (agentDefaults?.runner !== undefined)
+                    config.agentDefaults.runner = agentDefaults.runner;
+                for (const runner of PROVIDER_IDS) {
+                    const model = agentDefaults?.models?.[runner];
+                    if (model === undefined)
+                        continue;
+                    const models = config.agentDefaults.models ?? {};
+                    if (model === null)
+                        delete models[runner];
+                    else
+                        models[runner] = model;
+                    // An empty object would persist a key that says nothing; absence is the same answer.
+                    if (Object.keys(models).length === 0)
+                        delete config.agentDefaults.models;
+                    else
+                        config.agentDefaults.models = models;
+                }
             });
         }
         catch (err) {
@@ -1394,15 +2474,19 @@ export function createApp(deps) {
         if (resources !== undefined)
             await deps.semaphore?.refresh();
         return c.json(workspaceConfigBody(written));
-    });
-    // Global GUI state (`~/.cezar/ui-state.json`) — same parse/key-cap/shallow-
-    // merge semantics as the per-repo /api/ui-state route below (the shared half
-    // is `parseUiStateBody`), but backed by the workspace file.
-    app.get('/api/workspace/ui-state', async (c) => c.json(await readWorkspaceUiState()));
-    app.put('/api/workspace/ui-state', bodyLimit({ maxSize: UI_STATE_BODY_LIMIT }), async (c) => {
-        const parsed = parseUiStateBody(workspaceUiStateSchema, await c.req.json().catch(() => null));
-        if ('error' in parsed)
-            return c.json({ error: parsed.error }, 400);
+    })
+        // Global GUI state (`~/.cezar/ui-state.json`) — same parse/key-cap/shallow-
+        // merge semantics as the per-repo /api/v1/ui-state route below (the shared half
+        // is `uiStateBodySchema`), but backed by the workspace file.
+        .get('/workspace/ui-state', async (c) => c.json(await readWorkspaceUiState()))
+        // The tighter body cap rides on `use` rather than inline on the route: `bodyLimit` is typed
+        // as a bare MiddlewareHandler, and passing one to `.put()` collapses the route's schema, so
+        // the PUT went missing from `AppType` and `hc` could not see its body at all. `use` runs at
+        // the same point (before the handler, so the cap still precedes any read) and leaves the
+        // chain's type accumulation alone. Method-agnostic here, which the GET does not mind.
+        .use('/workspace/ui-state', bodyLimit({ maxSize: UI_STATE_BODY_LIMIT }))
+        .put('/workspace/ui-state', jsonZodValidator(setWorkspaceUiStateInputSchema), async (c) => {
+        const parsed = { data: c.req.valid('json') };
         try {
             return c.json(await mergeWriteWorkspaceUiState((state) => ({
                 ...state,
@@ -1414,67 +2498,119 @@ export function createApp(deps) {
             return c.json({ error: err instanceof Error ? err.message : String(err) }, 500);
         }
     });
-    // ---- filesystem browse (multi-project spec, step 4.1) --------------------
-    // WORKSPACE-level and same-origin: the directory picker behind "Add project
-    // → open local folder". Directories only, and every answer is contained in a
-    // single root — see src/server/fs-browse.ts for the containment rule and why
-    // it is realpath-based. The independently configured browse root is read per
-    // request, so a successful settings save applies without a restart.
-    app.get('/api/fs/browse', async (c) => {
+    // Partial updates only — absent keys stay untouched. Bounds mirror the
+    // workspace schema (src/workspace/config.ts, step 1.2) exactly, so a value
+    // this route accepts can never be degraded away by the next load's `.catch`.
+    const workspaceConfigUpdateSchema = z.object({
+        browseRoot: z.string().trim().min(1).max(4096).optional(),
+        projectsDir: z.string().trim().min(1).max(4096).optional(),
+        skillsAutoUpdate: z.boolean().nullable().optional(),
+        composerDefaults: z
+            .object({
+            autonomous: z.boolean().nullable().optional(),
+            worktree: z.boolean().nullable().optional(),
+        })
+            .optional(),
+        resources: z
+            .object({
+            maxParallel: z.number().int().min(1).max(16).optional(),
+            maxMonitoringSessions: z.number().int().min(0).max(16).optional(),
+            monitoringWakeIntervalMinutes: z.number().int().min(1).max(60).nullable().optional(),
+            autoResumeOnUsageLimit: z.boolean().optional(),
+            memoryLimitMb: z.number().int().min(0).max(1_048_576).nullable().optional(),
+            worktreeRetentionDefault: z.number().int().min(0).max(1000).optional(),
+        })
+            .optional(),
+        // Bounds mirror `src/workspace/config.ts`, so a value this accepts is never degraded away by
+        // the next load's `.catch`. `null` clears a key back to "no opinion".
+        agentDefaults: z
+            .object({
+            runner: z.enum(PROVIDER_IDS).nullable().optional(),
+            models: z
+                .object({
+                claude: z.string().trim().min(1).max(200).nullable().optional(),
+                codex: z.string().trim().min(1).max(200).nullable().optional(),
+                opencode: z.string().trim().min(1).max(200).nullable().optional(),
+                pi: z.string().trim().min(1).max(200).nullable().optional(),
+            })
+                .optional(),
+        })
+            .optional(),
+    });
+    // ---- chained family: filesystem browse (workspace-level) ----
+    const fsBrowseRoutes = new Hono()
+        .get('/fs/browse', queryZodValidator(z.object({ path: queryValue, showHidden: queryValue })), async (c) => {
         if (capabilities().singleProject) {
             return c.json(singleProjectRefusal('folder browsing'), 409);
         }
+        const query = c.req.valid('query');
         const root = resolveBrowseRoot(await workspaceBrowseRoot());
         const result = await browseDirectory({
             root,
-            path: c.req.query('path'),
-            showHidden: c.req.query('showHidden') === '1',
+            path: query.path,
+            showHidden: query.showHidden === '1',
         });
         if (!result.ok)
             return c.json({ error: result.error }, result.status);
         return c.json(result.body);
     });
-    // The bookmarklet generator bakes this key into the `javascript:` URLs —
-    // `/new?auto=1` is honored only with it (spec 011). Same-origin only.
-    api.get('/launch-key', (c) => c.json({ key: c.get('project').launchKey }));
-    api.get('/skills', async (c) => {
+    // ---- chained family: launch-key (project-scoped) ----
+    const launchKeyRoutes = new Hono()
+        .get('/launch-key', (c) => c.json({ key: c.get('project').launchKey }));
+    // ---- chained family: skills (project-scoped) ----
+    const skillsRoutes = new Hono()
+        .get('/skills', queryZodValidator(waitQuery), async (c) => {
         const repoRoot = c.get('project').root;
         // The default read stays fast and starts the team load in the background.
         // The cockpit follows it with `wait=1`, off the render path, so a cold
         // cache converges without polling or a manual reload (spec 005 / #555).
-        if (c.req.query('wait') === '1')
+        if (c.req.valid('query').wait === '1')
             await waitForTeamSkills(repoRoot);
         return c.json(await discoverSkills(repoRoot));
-    });
-    // The opt-in catalog for the "Import skills" panel: every skill a default
-    // (vendor) repo offers — `open-mercato/skills` — regardless of import state,
-    // so the panel can present them all with a per-skill toggle. Empty once a repo
-    // configures its own `skillsRepos` (nothing is gated then). `wait=1` lets the
-    // panel wait out a cold team-skill cache, same as `GET /skills` (spec 005).
-    api.get('/skills/importable', async (c) => {
+    })
+        // The opt-in catalog for the "Import skills" panel: every skill a default
+        // (vendor) repo offers — `open-mercato/skills` — regardless of import state,
+        // so the panel can present them all with a per-skill toggle. Empty once a repo
+        // configures its own `skillsRepos` (nothing is gated then). `wait=1` lets the
+        // panel wait out a cold team-skill cache, same as `GET /skills` (spec 005).
+        .get('/skills/importable', queryZodValidator(waitQuery), async (c) => {
         const repoRoot = c.get('project').root;
         const gated = await gatedSkillsRepos(repoRoot);
         if (gated.size === 0)
             return c.json([]);
-        if (c.req.query('wait') === '1')
+        if (c.req.valid('query').wait === '1')
             await waitForTeamSkills(repoRoot);
         const importable = getTeamSkillsCached(repoRoot)
             .filter((skill) => skill.team && gated.has(skill.team.repo))
-            .map((skill) => ({ name: skill.name, description: skill.description }));
+            // Spread `description` rather than writing it unconditionally: an undefined VALUE is
+            // dropped by JSON.stringify, so the key is absent on the wire, and writing it always
+            // typed the route as sending a key it does not. contract/skills.ts says `.optional()`,
+            // which is what the client actually receives.
+            .map((skill) => ({
+            name: skill.name,
+            ...(skill.description !== undefined ? { description: skill.description } : {}),
+        }));
         return c.json(importable);
+    })
+        // Refresh team skills (spec 005): clone/fetch the configured skills repos,
+        // then return the merged catalog. Degrades quietly — offline just means the
+        // team entries stay as they were (or absent).
+        .post('/skills/refresh', async (c) => {
+        const { root: repoRoot } = c.get('project');
+        await refreshTeamSkills(repoRoot);
+        return c.json(await discoverSkills(repoRoot));
     });
-    // ---- GUI prefs (ui-state.json) --------------------------------------------
-    // The read path is shared with the CLI (`src/ui-state.ts`) so `cezar serve` can honour a
-    // preference set here — #391's dismissed skills banner — from one notion of the file.
-    api.get('/ui-state', async (c) => c.json(await readUiState(c.get('project').root)));
-    api.put('/ui-state', bodyLimit({ maxSize: UI_STATE_BODY_LIMIT }), async (c) => {
+    // ---- chained family: GUI prefs / ui-state (project-scoped) ----
+    const uiStateRoutes = new Hono()
+        .get('/ui-state', async (c) => c.json(await readUiState(c.get('project').root)))
+        // On `use`, not inline on the route — see the workspace ui-state PUT above.
+        .use('/ui-state', bodyLimit({ maxSize: UI_STATE_BODY_LIMIT }))
+        .put('/ui-state', jsonZodValidator(uiStateBody), async (c) => {
         const { root: repoRoot, dataDir } = c.get('project');
         // `.passthrough()` keeps unknown prefs (BACKWARD_COMPATIBILITY §3), but a
         // single request may not stuff an unbounded key set (#429) — the shared
-        // parse+cap half of both ui-state routes lives in parseUiStateBody.
-        const parsed = parseUiStateBody(uiStateSchema, await c.req.json().catch(() => null));
-        if ('error' in parsed)
-            return c.json({ error: parsed.error }, 400);
+        // schema+cap half of both ui-state routes lives in `uiStateBody`.
+        const parsed = { data: c.req.valid('json') };
         const merged = { ...(await readUiState(repoRoot)), ...parsed.data };
         try {
             await mkdir(dataDir, { recursive: true });
@@ -1485,24 +2621,18 @@ export function createApp(deps) {
         }
         return c.json(merged);
     });
-    // Refresh team skills (spec 005): clone/fetch the configured skills repos,
-    // then return the merged catalog. Degrades quietly — offline just means the
-    // team entries stay as they were (or absent).
-    api.post('/skills/refresh', async (c) => {
-        const { root: repoRoot } = c.get('project');
-        await refreshTeamSkills(repoRoot);
-        return c.json(await discoverSkills(repoRoot));
-    });
-    api.get('/workflows', async (c) => c.json(await loadWorkflows(c.get('project').root)));
-    // Save an approved plan as a reusable chain (spec 008): YAML in
-    // `.ai/cezar/workflows/<slug>.yaml` — from then on it's in the dropdown
-    // like any other workflow.
-    api.post('/workflows', async (c) => {
+    // ---- chained family: workflows (project-scoped) --------------------------
+    // One chained expression, mounted by `createApp` into BOTH the legacy `api`
+    // table and the versioned `v1` one — see `healthRoutes` for why the chain
+    // shape (not the statement shape) is what carries the types.
+    const workflowsRoutes = new Hono()
+        .get('/workflows', async (c) => c.json(await loadWorkflows(c.get('project').root)))
+        // Save an approved plan as a reusable chain (spec 008): YAML in
+        // `.ai/cezar/workflows/<slug>.yaml` — from then on it's in the dropdown
+        // like any other workflow.
+        .post('/workflows', jsonZodValidator(saveWorkflowSchema), async (c) => {
         const { root: repoRoot } = c.get('project');
-        const parsed = saveWorkflowSchema.safeParse(await c.req.json().catch(() => null));
-        if (!parsed.success) {
-            return c.json({ error: parsed.error.issues.map((i) => i.message).join('; ') }, 400);
-        }
+        const parsed = { data: c.req.valid('json') };
         const steps = parsed.data.steps ?? skillsToSteps(parsed.data.skills ?? []);
         const issue = stepsIssue(steps);
         if (issue)
@@ -1534,10 +2664,10 @@ export function createApp(deps) {
             return c.json({ error: message }, 500);
         }
         return c.json({ path, name: parsed.data.name }, 201);
-    });
-    // Delete a saved workflow (spec 012 follow-up): file workflows only —
-    // built-ins have no file and always come back.
-    api.delete('/workflows/:name', async (c) => {
+    })
+        // Delete a saved workflow (spec 012 follow-up): file workflows only —
+        // built-ins have no file and always come back.
+        .delete('/workflows/:name', async (c) => {
         const { root: repoRoot } = c.get('project');
         const name = c.req.param('name');
         const { workflows } = await loadWorkflows(repoRoot);
@@ -1559,15 +2689,12 @@ export function createApp(deps) {
             return c.json({ error: err instanceof Error ? err.message : String(err) }, 500);
         }
         return c.json({ ok: true, path: target });
-    });
-    // Import support for the builder (spec 012): parse + validate a pasted
-    // workflow YAML (either form) and hand back the normalized definition. The
-    // server owns YAML parsing — the GUI stays dependency-free.
-    api.post('/workflows/parse', async (c) => {
-        const parsed = parseWorkflowSchema.safeParse(await c.req.json().catch(() => null));
-        if (!parsed.success) {
-            return c.json({ error: parsed.error.issues.map((i) => i.message).join('; ') }, 400);
-        }
+    })
+        // Import support for the builder (spec 012): parse + validate a pasted
+        // workflow YAML (either form) and hand back the normalized definition. The
+        // server owns YAML parsing — the GUI stays dependency-free.
+        .post('/workflows/parse', jsonZodValidator(parseWorkflowSchema), async (c) => {
+        const parsed = { data: c.req.valid('json') };
         let raw;
         try {
             raw = parseYaml(parsed.data.yaml);
@@ -1586,17 +2713,274 @@ export function createApp(deps) {
             return c.json({ error: issue }, 400);
         return c.json(normalized);
     });
-    // Chain-from-prompt (spec 008): one cheap claude call proposes a chain of
-    // steps for the task. Never blocks — degraded answers come back as a
-    // one-step quick-task plan with `fallback: true`.
-    api.post('/plan', async (c) => {
+    // ---- chained family: plan (project-scoped) ----
+    const planRoutes = new Hono()
+        .post('/plan', jsonZodValidator(planSchema), async (c) => {
         const { root: repoRoot } = c.get('project');
-        const parsed = planSchema.safeParse(await c.req.json().catch(() => null));
-        if (!parsed.success) {
-            return c.json({ error: parsed.error.issues.map((i) => i.message).join('; ') }, 400);
-        }
+        const parsed = { data: c.req.valid('json') };
+        const blocked = await providerActionError([(await loadConfig(repoRoot)).defaultRunner]);
+        if (blocked)
+            return c.json({ error: blocked }, 409);
         return c.json(await planChain(repoRoot, parsed.data.task));
     });
+    const manualChecks = new Map();
+    /**
+     * The automations gate (#801): with `CEZ_AUTOMATIONS` unset, every route of the feature
+     * answers 409 before touching a store, a lease or GitHub.
+     *
+     * Written as MIDDLEWARE rather than a line in each handler so the family cannot drift: a route
+     * added to either chain below inherits the gate from its path, where a per-handler check is one
+     * omission away from an ungated endpoint.
+     *
+     * Registered against EXPLICIT paths, never `use('*')`. Both chains are mounted with
+     * `.route('/', …)` alongside a dozen unrelated sub-apps, and `route()` re-registers a sub-app's
+     * middleware under the mount prefix — so a `'*'` here would gate the entire `/api/v1` surface,
+     * including `/health`. The two-line pairing (`/automations` and `/automations/*`) is what makes
+     * a path match both the collection and everything under it.
+     */
+    const requireAutomations = async (c, next) => {
+        if (!capabilities().automations)
+            return c.json({ error: AUTOMATIONS_OFF }, 409);
+        await next();
+    };
+    // ---- chained family: GitHub automations (project-scoped) ----
+    // Every handler below reads `c.get('project')` — the definitions, their runtime state and the
+    // execution log are per-project files — so the family is project-scoped and mounted with the
+    // rest of the mirrored table. The one exception is the manual-check read, which touches no
+    // project at all; it is its own workspace-level family below.
+    const automationsRoutes = new Hono()
+        .use('/automations', requireAutomations)
+        .use('/automations/*', requireAutomations)
+        .use('/automation-log', requireAutomations)
+        .use('/automation-log/*', requireAutomations)
+        .get('/automations', async (c) => {
+        const { root, automationStore } = c.get('project');
+        const forge = resolveForge(await getRepoInfo(root));
+        // Annotated, so the two branches are ONE shape rather than a union of two: the fallback
+        // literal always carries `reason`, the cached answer only sometimes does, and the route
+        // type is what `contract/src/automations.ts` has to describe.
+        const availability = forge?.detectCached() ?? {
+            available: false,
+            reason: forge ? 'GitHub availability is still being checked' : 'No GitHub remote is configured',
+        };
+        const automations = automationStore.list().map((automation) => {
+            const logs = automationStore.logs({ automationId: automation.id, limit: 100 });
+            const state = automationStore.state(automation.id);
+            const latestLog = logs[0];
+            return {
+                ...automation,
+                // Spread conditionally, never `state: maybeUndefined`: the latter types the key as
+                // always-present while `JSON.stringify` drops it from the wire, so the contract would
+                // have to describe a key consumers never receive.
+                ...(state ? { state } : {}),
+                ...(latestLog ? { latestLog } : {}),
+                counts: {
+                    matches: logs.filter((row) => row.result === 'launched' || row.result === 'duplicate').length,
+                    launched: logs.filter((row) => row.result === 'launched').length,
+                    duplicates: logs.filter((row) => row.result === 'duplicate').length,
+                    errors: logs.filter((row) => row.result === 'error' || row.result === 'rate-limited').length,
+                },
+            };
+        });
+        const nextDue = automations.map((item) => item.state?.nextCheckAt).filter(Boolean).sort()[0];
+        return c.json({
+            ...availability,
+            scheduler: {
+                // `as const` on both arms: in an object literal a conditional of two string literals
+                // widens to `string`, which would erase the two states this key can hold.
+                state: automations.some((item) => item.enabled) ? 'scheduled' : 'idle',
+                ...(nextDue ? { nextDue } : {}),
+            },
+            automations,
+        });
+    })
+        .post('/automations', jsonZodValidator(() => automationCreateSchema), async (c) => {
+        const { automationStore } = c.get('project');
+        const parsed = { data: c.req.valid('json') };
+        const promptIssue = validateAutomationPrompt(parsed.data.task.prompt);
+        if (promptIssue)
+            return c.json({ error: promptIssue }, 400);
+        const { enable, ...input } = parsed.data;
+        try {
+            const automation = automationStore.create({ ...input, enabled: enable === true });
+            if (enable) {
+                const baselineAt = new Date().toISOString();
+                automationStore.setState(automation.id, {
+                    revision: automation.revision,
+                    baselineAt,
+                    cursor: { timestamp: baselineAt },
+                    nextCheckAt: new Date(Date.now() + automation.intervalSeconds * 1_000).toISOString(),
+                });
+            }
+            emitAutomationChange(c.get('project'), automation.id, automation.revision);
+            automationsChanged();
+            return c.json({ automation }, 201);
+        }
+        catch (error) {
+            return c.json({ error: error instanceof Error ? error.message : String(error) }, 400);
+        }
+    })
+        .get('/automations/:id', (c) => {
+        const { automationStore } = c.get('project');
+        const automation = automationStore.get(c.req.param('id'));
+        if (!automation)
+            return c.json({ error: 'not found' }, 404);
+        const state = automationStore.state(automation.id);
+        const latestLog = automationStore.logs({ automationId: automation.id, limit: 1 })[0];
+        return c.json({
+            automation,
+            ...(state ? { state } : {}),
+            ...(latestLog ? { latestLog } : {}),
+        });
+    })
+        .put('/automations/:id', jsonZodValidator(() => automationUpdateSchema), async (c) => {
+        const { automationStore } = c.get('project');
+        const parsed = { data: c.req.valid('json') };
+        const promptIssue = validateAutomationPrompt(parsed.data.task.prompt);
+        if (promptIssue)
+            return c.json({ error: promptIssue }, 400);
+        const { expectedRevision, ...input } = parsed.data;
+        if (!automationStore.get(c.req.param('id')))
+            return c.json({ error: 'not found' }, 404);
+        try {
+            const automation = automationStore.update(c.req.param('id'), expectedRevision, { ...input, enabled: input.enabled ?? false });
+            emitAutomationChange(c.get('project'), automation.id, automation.revision);
+            automationsChanged();
+            return c.json({ automation });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return c.json({ error: message }, message.includes('conflict') ? 409 : 400);
+        }
+    })
+        .delete('/automations/:id', (c) => {
+        const id = c.req.param('id');
+        const store = c.get('project').automationStore;
+        const current = store.get(id);
+        if (!current || !store.delete(id))
+            return c.json({ error: 'not found' }, 404);
+        emitAutomationChange(c.get('project'), id, current.revision, true);
+        automationsChanged();
+        return c.body(null, 204);
+    })
+        .post('/automations/:id/enable', (c) => {
+        const store = c.get('project').automationStore;
+        const current = store.get(c.req.param('id'));
+        if (!current)
+            return c.json({ error: 'not found' }, 404);
+        const automation = store.update(current.id, current.revision, { ...editableAutomation(current), enabled: true });
+        const baselineAt = new Date().toISOString();
+        store.setState(automation.id, {
+            ...store.state(automation.id),
+            revision: automation.revision,
+            baselineAt,
+            cursor: { timestamp: baselineAt },
+            nextCheckAt: new Date(Date.now() + automation.intervalSeconds * 1_000).toISOString(),
+        });
+        store.appendLog({ automationId: automation.id, revision: automation.revision, result: 'baseline', reason: 'Enabled from a current-time baseline; existing records were not launched.' });
+        emitAutomationChange(c.get('project'), automation.id, automation.revision);
+        automationsChanged();
+        return c.json({ automation });
+    })
+        .post('/automations/:id/pause', (c) => {
+        const store = c.get('project').automationStore;
+        const current = store.get(c.req.param('id'));
+        if (!current)
+            return c.json({ error: 'not found' }, 404);
+        const automation = store.update(current.id, current.revision, { ...editableAutomation(current), enabled: false });
+        emitAutomationChange(c.get('project'), automation.id, automation.revision);
+        automationsChanged();
+        return c.json({ automation });
+    })
+        // The body is validated as MIDDLEWARE, which is what puts it in the route type — and moves
+        // the 400 ahead of this route's 404: `POST /automations/<unknown>/check` with a malformed
+        // body now answers 400 rather than 404. Nothing else about either answer changed.
+        .post('/automations/:id/check', jsonZodValidator(() => automationCheckRequestSchema), async (c) => {
+        const project = c.get('project');
+        const store = project.automationStore;
+        const automation = store.get(c.req.param('id'));
+        if (!automation)
+            return c.json({ error: 'not found' }, 404);
+        const parsed = { data: c.req.valid('json') };
+        // `string`, not `randomUUID`'s template-literal type: the wire carries an opaque id, and
+        // leaking `${string}-${string}-…` into the route type would make the contract describe the
+        // generator rather than the answer.
+        const id = randomUUID();
+        const check = { id, automationId: automation.id, mode: parsed.data.mode, status: 'queued', createdAt: new Date().toISOString() };
+        if (manualChecks.size >= 200)
+            manualChecks.delete(manualChecks.keys().next().value);
+        manualChecks.set(id, check);
+        void (async () => {
+            check.status = 'running';
+            try {
+                const remote = parseRemote((await getRepoInfo(project.root))?.remote ?? '');
+                if (!remote || remote.host !== 'github.com')
+                    throw new Error('No GitHub remote is configured');
+                const scheduler = new ProjectAutomationScheduler({
+                    projectId: project.id,
+                    owner: remote.owner,
+                    repo: remote.repo,
+                    store,
+                    poller: new GithubPoller(),
+                    launch: parsed.data.mode === 'execute'
+                        ? (definition, candidate, receiptId) => launchAutomationRun({ root: project.root, manager: project.manager, store: project.store, definition, candidate, receiptId })
+                        : undefined,
+                    onChange: (automationId, revision) => emitAutomationChange(project, automationId, revision),
+                });
+                const result = await scheduler.check(automation, parsed.data.mode);
+                Object.assign(check, { status: 'complete', completedAt: new Date().toISOString(), matches: result.candidates.length, truncated: result.truncated });
+            }
+            catch (error) {
+                Object.assign(check, { status: 'error', completedAt: new Date().toISOString(), error: error instanceof Error ? error.message : String(error) });
+            }
+        })();
+        return c.json({ checkId: id }, 202);
+    })
+        .get('/automation-log', queryZodValidator(automationLogQuerySchema), (c) => {
+        return c.json({ records: c.get('project').automationStore.logs(c.req.valid('query')) });
+    })
+        .post('/automation-log/:receiptId/retry', async (c) => {
+        const project = c.get('project');
+        const store = project.automationStore;
+        const receipt = [...store.latestReceipts().values()].find((row) => row.receiptId === c.req.param('receiptId'));
+        if (!receipt)
+            return c.json({ error: 'not found' }, 404);
+        if (receipt.status !== 'launch-error' || receipt.runId)
+            return c.json({ error: 'receipt is not retryable' }, 409);
+        if (!receipt.candidate)
+            return c.json({ error: 'receipt predates retry context and cannot be retried safely' }, 409);
+        const definition = store.get(receipt.automationId);
+        if (!definition)
+            return c.json({ error: 'automation not found' }, 404);
+        const lease = store.acquireLease();
+        if (!lease)
+            return c.json({ error: 'automation polling lease is held by another process' }, 409);
+        const reserved = { ...receipt, status: 'reserved', error: undefined, updatedAt: new Date().toISOString() };
+        store.appendReceipt(reserved);
+        try {
+            const launched = await launchAutomationRun({ root: project.root, manager: project.manager, store: project.store, definition, candidate: receipt.candidate, receiptId: receipt.receiptId });
+            store.appendReceipt({ ...reserved, status: 'launched', runId: launched.runId, updatedAt: new Date().toISOString() });
+            emitAutomationChange(project, definition.id, definition.revision);
+            return c.json({ receiptId: receipt.receiptId, runId: launched.runId }, 202);
+        }
+        catch (error) {
+            store.appendReceipt({ ...reserved, status: 'launch-error', error: error instanceof Error ? error.message : String(error), updatedAt: new Date().toISOString() });
+            return c.json({ error: error instanceof Error ? error.message : String(error) }, 409);
+        }
+        finally {
+            lease.release();
+        }
+    });
+    // ---- chained family: manual automation checks (workspace-level) ----
+    // Workspace-level because the handler reads no project: a check lives in the server-memory map
+    // above, keyed by an unguessable id that the project-scoped POST hands back. Mounting it under
+    // `/api/v1/p/:projectId` too would be a second spelling of a lookup that consults no project.
+    const automationChecksRoutes = new Hono()
+        .use('/automation-checks/*', requireAutomations)
+        .get('/automation-checks/:checkId', (c) => {
+        const check = manualChecks.get(c.req.param('checkId'));
+        return check ? c.json(check) : c.json({ error: 'not found' }, 404);
+    });
     // ---- runs ----------------------------------------------------------------
     // Additive `usage` field (#348): the latest CPU/RSS/proc-count sample of the
     // run's live process tree — absent for finished runs and when `ps` yields
@@ -1625,27 +3009,56 @@ export function createApp(deps) {
             console.warn(`[cezar] could not mark inbox entry ${todoId} started: ${String(err)}`);
         }
     };
-    api.get('/runs', (c) => c.json(c.get('project').store.listRuns().map(withUsage)));
-    // Registered before the `/:id/...` routes so "archive-finished" never
-    // matches as a run id.
-    api.post('/runs/archive-finished', (c) => c.json({ archived: c.get('project').store.archiveFinished() }));
-    api.post('/runs/:id/archive', async (c) => {
+    // ---- chained family: runs lifecycle + artifacts (project-scoped) ----
+    const runsRoutes = new Hono()
+        .get('/runs', (c) => c.json(c.get('project').store.listRuns().map(withUsage)))
+        // Registered before the `/:id/...` routes so "archive-finished" and "read-all"
+        // never match as a run id.
+        .post('/runs/archive-finished', (c) => c.json({ archived: c.get('project').store.archiveFinished() }))
+        // The read-receipt sweep (#unread-done-items) — the mark-read twin of the archive
+        // sweep above, and under the same registration-order guard.
+        .post('/runs/read-all', (c) => c.json({ read: c.get('project').store.markAllRead() }))
+        .post('/runs/:id/archive', jsonZodValidator(archiveSchema, { absent: ({}) }), async (c) => {
         const { store } = c.get('project');
         const id = c.req.param('id');
         // An empty/absent body archives (the common case); a malformed body degrades
         // to `{}` just as before, but a wrong-typed `archived` is now a 400 (#429).
-        const parsed = archiveSchema.safeParse(await c.req.json().catch(() => ({})));
-        if (!parsed.success) {
-            return c.json({ error: parsed.error.issues.map((i) => i.message).join('; ') }, 400);
-        }
+        // Archiving also retires any pending usage-limit resume, but that rule belongs to
+        // `setArchived` itself — the bulk sweep must obey it too (spec
+        // 2026-08-03-auto-resume-after-usage-limit).
+        const parsed = { data: c.req.valid('json') };
         const run = store.setArchived(id, parsed.data.archived !== false);
         return run ? c.json(run) : c.json({ error: 'not found' }, 404);
-    });
-    api.post('/runs', async (c) => {
+    })
+        // The per-task off switch for that resume (the workspace setting is Settings → Resources).
+        // Idempotent: a run with nothing pending answers 200 too, because "this task will not
+        // resume itself" is equally true either way.
+        .delete('/runs/:id/auto-resume', (c) => {
+        const { store, manager } = c.get('project');
+        const id = c.req.param('id');
+        if (!store.getRun(id))
+            return c.json({ error: 'not found' }, 404);
+        manager.cancelAutoResume(id);
+        return c.json({ cancelled: true });
+    })
+        .post('/runs/:id/read', (c) => {
+        // No body: opening a thread marks it read, full stop. Stamps `seenAt = now` and
+        // returns the updated record (which also rides the `run` SSE via `touch`).
+        const run = c.get('project').store.setRead(c.req.param('id'));
+        return run ? c.json(run) : c.json({ error: 'not found' }, 404);
+    })
+        .post('/runs/:id/unread', (c) => {
+        // The mark-unread twin (#775) — bodyless like its read counterpart: clearing the
+        // receipt is the whole action, so there is nothing to say about it. Sits under
+        // `/runs/:id/`, so the `read-all` registration-order caveat above does not apply.
+        const run = c.get('project').store.setUnread(c.req.param('id'));
+        return run ? c.json(run) : c.json({ error: 'not found' }, 404);
+    })
+        .post('/runs', jsonZodValidator(startRunSchema), async (c) => {
         const { root: repoRoot, dataDir, manager } = c.get('project');
-        const parsed = startRunSchema.safeParse(await c.req.json().catch(() => null));
-        if (!parsed.success) {
-            return c.json({ error: parsed.error.issues.map((i) => i.message).join('; ') }, 400);
+        const parsed = { data: c.req.valid('json') };
+        if (agentModelsLocked(repoRoot) && parsed.data.model?.trim()) {
+            return c.json({ error: AGENT_MODELS_LOCKED_ERROR }, 409);
         }
         let workflow;
         if (parsed.data.steps) {
@@ -1665,6 +3078,19 @@ export function createApp(deps) {
             if (!workflow)
                 return c.json({ error: `unknown workflow: ${parsed.data.workflow}` }, 404);
         }
+        const fallback = parsed.data.runner ?? (await loadConfig(repoRoot)).defaultRunner;
+        const blocked = await providerActionError(providersRequiredByWorkflow(workflow, fallback));
+        if (blocked)
+            return c.json({ error: blocked }, 409);
+        // A composer override names an account the user just picked, so a stale id (deleted since
+        // the page loaded) is answered honestly instead of quietly running on the default — the
+        // opposite of how RESOLUTION treats a dangling reference, and deliberately so: a run
+        // replaying a stored id has no better answer than the default, a user does.
+        if (parsed.data.agentProfile !== undefined) {
+            const account = await resolveWorkspaceProfile(fallback, parsed.data.agentProfile);
+            if ('error' in account)
+                return c.json({ error: account.error }, 400);
+        }
         const images = parsed.data.images?.map((img) => ({
             type: 'image',
             source: { type: 'base64', media_type: img.mediaType, data: img.data },
@@ -1673,146 +3099,79 @@ export function createApp(deps) {
             task: parsed.data.task,
             model: parsed.data.model,
             runner: parsed.data.runner,
+            agentProfile: parsed.data.agentProfile,
             images,
             systemPrompt: parsed.data.systemPrompt,
             worktree: parsed.data.worktree,
             autonomous: parsed.data.autonomous,
             // Opt-in inbox (#471): the capability is the ceiling, so a client asking
             // for follow-ups on a server that has them off gets a plain `false`
-            // rather than an error — the run is still perfectly valid without them.
-            // One decision here feeds the run record, the system prompt and
-            // CEZ_TODOS_FILE alike (RunManager.agentEnv).
-            generateFollowups: capabilities().followups ? parsed.data.generateFollowups : false,
-        };
-        const variants = parsed.data.variants ?? 1;
-        if (variants > 1) {
-            // Variants live in worktrees — without git there's nothing to isolate
-            // them with, so this degrades to a clear 400 instead of stepping on
-            // one shared working tree.
-            const repo = await getRepoInfo(repoRoot);
-            if (!repo) {
-                return c.json({
-                    error: 'parallel variants need a git repository (each variant runs in its own worktree) — run ×1 here, or start cezar inside a git repo',
-                }, 400);
-            }
-            const runs = manager.startVariants(workflow, input, variants);
-            // The entry points at the first variant — the thread the composer navigates to.
-            const first = runs[0];
-            if (parsed.data.todoId && first)
-                await noteTodoStarted(dataDir, parsed.data.todoId, first.id);
-            return c.json({ runs }, 201);
-        }
-        const run = manager.startRun(workflow, input);
-        if (parsed.data.todoId)
-            await noteTodoStarted(dataDir, parsed.data.todoId, run.id);
-        return c.json(run, 201);
-    });
-    // ---- parallel variants (spec 010) -----------------------------------------
-    const groupRuns = (store, groupId) => store
-        .listRuns()
-        .filter((r) => r.groupId === groupId)
-        .sort((a, b) => (a.variant ?? '').localeCompare(b.variant ?? ''));
-    // Comparison data: per variant the status, cost, `git diff --stat` and the
-    // first Progress-log lines from the handoff. The full diff is fetched per
-    // variant via the existing GET /api/runs/:id/diff.
-    api.get('/groups/:groupId', async (c) => {
-        const { dataDir, store } = c.get('project');
-        const runs = groupRuns(store, c.req.param('groupId'));
-        if (runs.length === 0)
-            return c.json({ error: 'not found' }, 404);
-        const detailed = await Promise.all(runs.map(async (r) => ({
-            id: r.id,
-            variant: r.variant ?? '?',
-            title: r.title,
-            status: r.status,
-            archived: r.archived,
-            tokensUsed: r.tokensUsed,
-            costUsd: r.costUsd,
-            diffStat: r.worktreePath && existsSync(r.worktreePath)
-                ? await worktreeDiffStat(r.worktreePath, r.baseBranch ?? 'HEAD')
-                : '',
-            handoffExcerpt: handoffProgressExcerpt(readHandoff(dataDir, r.id)),
-        })));
-        return c.json({
-            groupId: c.req.param('groupId'),
-            runs: detailed,
-        });
-    });
-    // "Pick this one": the winner rests at `review` (spec 009 takes it from
-    // there — send back / draft PR / finish); the losers are cancelled if
-    // alive, archived, and their worktrees + branches removed.
-    api.post('/groups/:groupId/pick', async (c) => {
-        const { root: repoRoot, dataDir, store, manager } = c.get('project');
-        const runs = groupRuns(store, c.req.param('groupId'));
-        if (runs.length === 0)
-            return c.json({ error: 'not found' }, 404);
-        const parsed = pickSchema.safeParse(await c.req.json().catch(() => null));
-        if (!parsed.success) {
-            return c.json({ error: parsed.error.issues.map((i) => i.message).join('; ') }, 400);
-        }
-        const winner = runs.find((r) => r.id === parsed.data.runId);
-        if (!winner)
-            return c.json({ error: 'runId is not part of this group' }, 404);
-        if (manager.isActive(winner.id)) {
-            return c.json({ error: 'this variant is still active — wait for it to finish first' }, 409);
-        }
-        // Winner: a non-review terminal state with a non-empty diff flips to
-        // `review` (the settleSuccess rule) — but only when the review gate applies
-        // (#489): it is enabled (`reviewGateEnabled`, default off) AND the winner is
-        // not autonomous. An autonomous / gate-off winner keeps its `done` state with
-        // the diff left in the worktree; an empty diff (or no worktree) stays too.
-        if (winner.status !== 'review' &&
-            winner.worktreePath &&
-            existsSync(winner.worktreePath) &&
-            winner.autonomous !== true &&
-            reviewGateEnabled(await loadConfig(repoRoot))) {
-            const diff = await worktreeDiff(winner.worktreePath, winner.baseBranch ?? 'HEAD');
-            if (diff.trim().length > 0 && !diff.startsWith('(diff failed')) {
-                store.updateRun(winner.id, { status: 'review' });
-            }
-        }
-        const losers = runs.filter((r) => r.id !== winner.id);
-        store.appendEvent(winner.id, {
-            type: 'lifecycle',
-            message: `picked from ${runs.length} variants — ${losers.length} other variant(s) archived`,
-        });
-        appendHandoffHeartbeat(dataDir, winner.id, `picked from ${runs.length} variants`);
-        for (const loser of losers) {
-            if (manager.isActive(loser.id))
-                manager.cancel(loser.id);
-            if (loser.worktreePath)
-                await removeWorktree(repoRoot, loser.worktreePath, loser.branch);
-            store.updateRun(loser.id, { worktreePath: undefined, branch: undefined });
-            store.setArchived(loser.id, true);
-            store.appendEvent(loser.id, {
-                type: 'lifecycle',
-                message: `variant ${winner.variant ?? '?'} was picked — this variant is archived, its worktree removed`,
-            });
+            // rather than an error — the run is still perfectly valid without them.
+            // One decision here feeds the run record, the system prompt and
+            // CEZ_TODOS_FILE alike (RunManager.agentEnv).
+            generateFollowups: capabilities().followups ? parsed.data.generateFollowups : false,
+        };
+        const variants = parsed.data.variants ?? 1;
+        if (variants > 1) {
+            // Variants live in worktrees — without git there's nothing to isolate
+            // them with, so this degrades to a clear 400 instead of stepping on
+            // one shared working tree.
+            const repo = await getRepoInfo(repoRoot);
+            if (!repo) {
+                return c.json({
+                    error: 'parallel variants need a git repository (each variant runs in its own worktree) — run ×1 here, or start cezar inside a git repo',
+                }, 400);
+            }
+            const runs = manager.startVariants(workflow, input, variants);
+            // The entry points at the first variant — the thread the composer navigates to.
+            const first = runs[0];
+            if (parsed.data.todoId && first)
+                await noteTodoStarted(dataDir, parsed.data.todoId, first.id);
+            return c.json({ runs }, 201);
         }
-        return c.json({
-            winner: store.getRun(winner.id),
-        });
-    });
-    api.get('/runs/:id', (c) => {
+        const run = manager.startRun(workflow, input);
+        if (parsed.data.todoId)
+            await noteTodoStarted(dataDir, parsed.data.todoId, run.id);
+        return c.json(run, 201);
+    })
+        .get('/runs/:id', (c) => {
         const { store } = c.get('project');
         const run = store.getRun(c.req.param('id'));
         return run ? c.json(withUsage(run)) : c.json({ error: 'not found' }, 404);
-    });
-    // Editable titles (#389). The UI displays `titleSummary ?? title`, so a
-    // user edit sets BOTH: `title` (the record's own name — the raw task stops
-    // being it the moment the user renames the run) and `titleSummary` (what
-    // actually displays). The auto-summarizer only ever fills an *unset*
-    // titleSummary (RunManager.recordTurnEnd), so an edit wins over any past or
-    // future auto-summary. Answers the updated record.
-    api.patch('/runs/:id', async (c) => {
+    })
+        .get('/runs/:id/history', paramZodValidator(runIdParamSchema), queryZodValidator(runHistoryQuerySchema), async (c) => {
+        const { store, dataDir } = c.get('project');
+        const { id } = c.req.valid('param');
+        if (!store.getRun(id))
+            return c.json({ error: 'not found' }, 404);
+        try {
+            return c.json(await readRunHistoryPage(join(dataDir, 'runs', `${id}.ndjson`), c.req.valid('query').cursor));
+        }
+        catch (error) {
+            if (error instanceof HistoryCursorError)
+                return c.json({ error: error.message }, error.status);
+            throw error;
+        }
+    })
+        .get('/runs/:id/history-context', paramZodValidator(runIdParamSchema), async (c) => {
+        const { store, dataDir } = c.get('project');
+        const { id } = c.req.valid('param');
+        if (!store.getRun(id))
+            return c.json({ error: 'not found' }, 404);
+        return c.json(await deriveRunContextEvents(join(dataDir, 'runs', `${id}.ndjson`)));
+    })
+        // Editable titles (#389). The UI displays `titleSummary ?? title`, so a
+        // user edit sets BOTH: `title` (the record's own name — the raw task stops
+        // being it the moment the user renames the run) and `titleSummary` (what
+        // actually displays). The auto-summarizer only ever fills an *unset*
+        // titleSummary (RunManager.recordTurnEnd), so an edit wins over any past or
+        // future auto-summary. Answers the updated record.
+        .patch('/runs/:id', jsonZodValidator(patchRunSchema), async (c) => {
         const { store, manager } = c.get('project');
         const id = c.req.param('id');
         if (!store.getRun(id))
             return c.json({ error: 'not found' }, 404);
-        const parsed = patchRunSchema.safeParse(await c.req.json().catch(() => null));
-        if (!parsed.success) {
-            return c.json({ error: parsed.error.issues.map((i) => i.message).join('; ') }, 400);
-        }
+        const parsed = { data: c.req.valid('json') };
         // The prompt is editable only while the run is still queued (#472). Checked
         // BEFORE the title write so a rejected PATCH is a no-op rather than a partial
         // one. `title` itself keeps working on any status — no regression to #389.
@@ -1837,25 +3196,33 @@ export function createApp(deps) {
             });
         }
         return c.json(store.getRun(id));
-    });
-    api.post('/runs/:id/cancel', (c) => {
+    })
+        .post('/runs/:id/cancel', (c) => {
         const { store, manager } = c.get('project');
         const id = c.req.param('id');
         if (!store.getRun(id))
             return c.json({ error: 'not found' }, 404);
         const cancelled = manager.cancel(id);
         return c.json({ cancelled });
-    });
-    // Live-session participation (spec 002): deliver a user message (text +
-    // pasted screenshots) into the run's open claude session.
-    api.post('/runs/:id/messages', async (c) => {
+    })
+        // Live-session participation (spec 002): deliver a user message (text +
+        // pasted screenshots) into the run's open claude session.
+        .post('/runs/:id/messages', jsonZodValidator(messageSchema), async (c) => {
         const { store, manager } = c.get('project');
         const id = c.req.param('id');
-        if (!store.getRun(id))
+        const run = store.getRun(id);
+        if (!run)
             return c.json({ error: 'not found' }, 404);
-        const parsed = messageSchema.safeParse(await c.req.json().catch(() => null));
-        if (!parsed.success) {
-            return c.json({ error: parsed.error.issues.map((i) => i.message).join('; ') }, 400);
+        const parsed = { data: c.req.valid('json') };
+        // Stacking onto a queued prompt mutates an existing task and invokes no provider.
+        // Provider availability still gates live delivery after the record leaves `queued`, but
+        // must not strand prompt authoring just because an unrelated fallback provider is
+        // disconnected (provider-auth spec: disabling never blocks existing-task mutations).
+        // In the dequeue race, the ladder below safely turns this into a starting-state buffer.
+        if (run.status !== 'queued') {
+            const blocked = await providerActionError([providerForActiveRun(run)]);
+            if (blocked)
+                return c.json({ error: blocked }, 409);
         }
         const content = [
             ...parsed.data.images.map((img) => ({
@@ -1871,14 +3238,14 @@ export function createApp(deps) {
         //   starting up  → buffered  · anything else → 409, exactly as before
         if (manager.sendMessage(id, content))
             return c.json({ delivered: true });
-        const run = store.getRun(id);
-        const stack = run?.queuedMessages ?? [];
+        const currentRun = store.getRun(id);
+        const stack = currentRun?.queuedMessages ?? [];
         // Bounds apply only to a message that is actually about to be stacked. Without this
         // gate an over-long message posted to a *finished* run would answer `400 prompt too
         // long` when the truthful answer is `409 session closed`. The status read is safe
         // here because it only decides whether to reject EARLY — `enqueueMessage` still
         // re-checks against the engine's own queue before writing anything.
-        if (run?.status === 'queued') {
+        if (currentRun?.status === 'queued') {
             if (stack.length >= MAX_QUEUED_MESSAGES) {
                 return c.json({ error: `too many queued messages — ${MAX_QUEUED_MESSAGES} message limit` }, 400);
             }
@@ -1886,7 +3253,7 @@ export function createApp(deps) {
             if (stackedImages + parsed.data.images.length > MAX_QUEUED_IMAGES) {
                 return c.json({ error: `too many queued images — ${MAX_QUEUED_IMAGES} image limit across the stack` }, 400);
             }
-            const prospective = foldedLength(run.task, [...stack, { text: parsed.data.text }]);
+            const prospective = foldedLength(currentRun.task, [...stack, { text: parsed.data.text }]);
             if (prospective > MAX_FOLDED_TASK_CHARS) {
                 return c.json({
                     error: `prompt too long — ${MAX_FOLDED_TASK_CHARS} character limit across the task and its queued messages (would be ${prospective})`,
@@ -1899,19 +3266,16 @@ export function createApp(deps) {
         if (manager.deferMessage(id, content))
             return c.json({ deferred: true });
         return c.json({ error: 'session closed' }, 409);
-    });
-    // Edit / remove a stacked message (#472). Registered before any conflicting
-    // `/:id` route so `queued-messages` never matches as a run id.
-    api.patch('/runs/:id/queued-messages/:msgId', async (c) => {
+    })
+        // Edit / remove a stacked message (#472). Registered before any conflicting
+        // `/:id` route so `queued-messages` never matches as a run id.
+        .patch('/runs/:id/queued-messages/:msgId', jsonZodValidator(queuedMessagePatchSchema), async (c) => {
         const { store, manager } = c.get('project');
         const id = c.req.param('id');
         const run = store.getRun(id);
         if (!run)
             return c.json({ error: 'not found' }, 404);
-        const parsed = queuedMessagePatchSchema.safeParse(await c.req.json().catch(() => null));
-        if (!parsed.success) {
-            return c.json({ error: parsed.error.issues.map((i) => i.message).join('; ') }, 400);
-        }
+        const parsed = { data: c.req.valid('json') };
         const msgId = c.req.param('msgId');
         const stack = run.queuedMessages ?? [];
         const existing = stack.find((m) => m.id === msgId);
@@ -1944,8 +3308,8 @@ export function createApp(deps) {
         if (!message)
             return c.json({ error: 'run already started' }, 409);
         return c.json({ message });
-    });
-    api.delete('/runs/:id/queued-messages/:msgId', (c) => {
+    })
+        .delete('/runs/:id/queued-messages/:msgId', (c) => {
         const { store, manager } = c.get('project');
         const id = c.req.param('id');
         const run = store.getRun(id);
@@ -1958,9 +3322,9 @@ export function createApp(deps) {
         if (!manager.removeQueuedMessage(id, msgId))
             return c.json({ error: 'run already started' }, 409);
         return c.json({ removed: true });
-    });
-    // "Finish": gracefully close a waiting session — the run completes as done.
-    api.post('/runs/:id/finish', (c) => {
+    })
+        // "Finish": gracefully close a waiting session — the run completes as done.
+        .post('/runs/:id/finish', (c) => {
         const { store, manager } = c.get('project');
         const id = c.req.param('id');
         if (!store.getRun(id))
@@ -1969,19 +3333,23 @@ export function createApp(deps) {
         if (!finished)
             return c.json({ error: 'no open session' }, 409);
         return c.json({ finished: true });
-    });
-    // "Continue" (spec 003): reopen a finished run's session in-process.
-    api.post('/runs/:id/continue', async (c) => {
-        const { store, manager } = c.get('project');
+    })
+        // "Continue" (spec 003): reopen a finished run's session in-process.
+        .post('/runs/:id/continue', jsonZodValidator(continueSchema, { absent: ({}) }), async (c) => {
+        const { root: repoRoot, store, manager } = c.get('project');
         const id = c.req.param('id');
-        if (!store.getRun(id))
+        const run = store.getRun(id);
+        if (!run)
             return c.json({ error: 'not found' }, 404);
         // Bounded resume text (#429); an empty/absent body still just re-runs on the
         // run's current backend, and a runner/model override reopens on that engine (#401).
-        const parsed = continueSchema.safeParse(await c.req.json().catch(() => ({})));
-        if (!parsed.success) {
-            return c.json({ error: parsed.error.issues.map((i) => i.message).join('; ') }, 400);
+        const parsed = { data: c.req.valid('json') };
+        if (agentModelsLocked(repoRoot) && parsed.data.model?.trim()) {
+            return c.json({ error: AGENT_MODELS_LOCKED_ERROR }, 409);
         }
+        const blocked = await providerActionError([providerForExistingRun(run, parsed.data.runner)]);
+        if (blocked)
+            return c.json({ error: blocked }, 409);
         const result = manager.continueRun(id, {
             text: parsed.data.text,
             images: parsed.data.images?.map((img) => ({
@@ -1994,10 +3362,10 @@ export function createApp(deps) {
         if (!result.ok)
             return c.json({ error: result.error }, 409);
         return c.json({ continued: true });
-    });
-    // "Open in terminal" (spec 003): hand the session off to a real terminal —
-    // in the task's worktree when it still exists (spec 006).
-    api.post('/runs/:id/open-in-cli', async (c) => {
+    })
+        // "Open in terminal" (spec 003): hand the session off to a real terminal —
+        // in the task's worktree when it still exists (spec 006).
+        .post('/runs/:id/open-in-cli', async (c) => {
         const { root: repoRoot, store } = c.get('project');
         const id = c.req.param('id');
         const run = store.getRun(id);
@@ -2010,28 +3378,36 @@ export function createApp(deps) {
                 error: 'local handoff is disabled — this cockpit runs in hosted mode (CEZ_REMOTE); resume the session from a machine that has the checkout',
             }, 409);
         }
-        const sessionId = [...run.steps].reverse().find((s) => s.sessionId)?.sessionId;
+        const sessionStep = [...run.steps].reverse().find((s) => s.sessionId);
+        const sessionId = sessionStep?.sessionId;
         if (!sessionId)
             return c.json({ error: 'no agent session to resume' }, 409);
+        const blocked = await providerActionError([providerForExistingRun(run)]);
+        if (blocked)
+            return c.json({ error: blocked }, 409);
         const cwd = run.worktreePath && existsSync(run.worktreePath) ? run.worktreePath : repoRoot;
         const command = resumeCommand(run.runner, sessionId);
         // Fails closed on an id we do not recognise — see resumeCommand (#431).
         if (!command)
             return c.json({ error: 'the recorded session id has an unexpected shape' }, 409);
-        const opened = await openInTerminal(cwd, command);
+        // The account that OWNS this session, not the project's current one (spec 2026-07-29).
+        const account = await handoffEnv(run.runner ?? 'claude', sessionStep?.profileId);
+        if ('error' in account)
+            return c.json({ error: account.error }, 409);
+        const fallback = handoffFallbackCommand(cwd, command, account.env);
+        // Fail closed for the same reason as the session id: a terminal opened without the
+        // account's config dir resumes nothing and says nothing about why.
+        if (fallback === null) {
+            return c.json({ error: 'this account\'s folder cannot be used in a terminal command' }, 409);
+        }
+        const opened = await openTerminal(cwd, command, account.env);
         if (!opened) {
-            return c.json({
-                error: 'no terminal emulator found',
-                command: `cd '${cwd}' && ${command}`,
-            }, 409);
+            return c.json({ error: 'no terminal emulator found', command: fallback }, 409);
         }
         return c.json({ opened: true, command });
-    });
-    // "Open in…" session takeover (#open-in): the editors/file-manager/terminal
-    // detected on THIS machine. Empty in hosted mode (no local desktop to open).
-    api.get('/open-targets', (c) => c.json({ targets: capabilities().localHandoff ? detectOpenTargets() : [] }));
-    // Open a run's worktree (or the repo root) in the chosen local app.
-    api.post('/runs/:id/open-in', async (c) => {
+    })
+        // Open a run's worktree (or the repo root) in the chosen local app.
+        .post('/runs/:id/open-in', jsonZodValidator(openInSchema), async (c) => {
         const { root: repoRoot, store } = c.get('project');
         const id = c.req.param('id');
         const run = store.getRun(id);
@@ -2044,10 +3420,7 @@ export function createApp(deps) {
         }
         // Follows the safeParse convention (#429); the downstream allowlist match is the real
         // injection guard, this just validates the shape.
-        const parsedBody = openInSchema.safeParse(await c.req.json().catch(() => null));
-        if (!parsedBody.success) {
-            return c.json({ error: parsedBody.error.issues.map((i) => i.message).join('; ') }, 400);
-        }
+        const parsedBody = { data: c.req.valid('json') };
         const { target, path: relPath } = parsedBody.data;
         const dir = run.worktreePath && existsSync(run.worktreePath) ? run.worktreePath : repoRoot;
         // Diff pane "open in OS default app" (#365): one worktree file, opened with the platform's
@@ -2086,7 +3459,7 @@ export function createApp(deps) {
                 }, 409);
             }
             const filePath = join(run.worktreePath, result.path);
-            const opened = await openFileInDefaultApp(filePath);
+            const opened = await openFile(filePath);
             if (!opened)
                 return c.json({ error: `could not open ${result.path}`, path: filePath }, 409);
             return c.json({ opened: true, path: filePath });
@@ -2105,29 +3478,43 @@ export function createApp(deps) {
         // and what the client's cliTargetResumes now labels. Resume-after-finish is untouched.
         const cliRunner = agentCliRunner(target);
         if (cliRunner) {
+            const blocked = await providerActionError([cliRunner]);
+            if (blocked)
+                return c.json({ error: blocked }, 409);
             const engineOwnsSession = run.status === 'running' || run.status === 'queued' || run.status === 'waiting';
-            const sessionId = engineOwnsSession ? undefined : [...run.steps].reverse().find((s) => s.sessionId)?.sessionId;
+            const sessionStep = engineOwnsSession ? undefined : [...run.steps].reverse().find((s) => s.sessionId);
+            const sessionId = sessionStep?.sessionId;
             // An id resumeCommand refuses (#431) degrades to a fresh CLI in the worktree,
             // exactly like a run that never recorded a session.
             const resume = sessionId && cliRunner === (run.runner ?? 'claude') ? resumeCommand(cliRunner, sessionId) : null;
             const command = resume ?? cliRunner;
-            const opened = await openInTerminal(dir, command);
+            // BOTH branches carry the account (spec 2026-07-29-agent-profiles): a resume needs the
+            // config dir that holds its session, and a FRESH CLI in this worktree should still open
+            // on the account the project works under — otherwise "Open in → Claude CLI" quietly
+            // hands the user a different subscription than every task in the same project uses.
+            const account = resume
+                ? await handoffEnv(cliRunner, sessionStep?.profileId)
+                : { env: (await resolveProfileEnvForRoot(repoRoot, cliRunner)).env };
+            if ('error' in account)
+                return c.json({ error: account.error }, 409);
+            const fallback = handoffFallbackCommand(dir, command, account.env);
+            if (fallback === null) {
+                return c.json({ error: 'this account\'s folder cannot be used in a terminal command' }, 409);
+            }
+            const opened = await openTerminal(dir, command, account.env);
             if (!opened) {
-                return c.json({
-                    error: 'no terminal emulator found',
-                    command: `cd '${dir}' && ${command}`,
-                }, 409);
+                return c.json({ error: 'no terminal emulator found', command: fallback }, 409);
             }
             return c.json({ opened: true, path: dir, command });
         }
-        const opened = await openInApp(target, dir);
+        const opened = await openApp(target, dir);
         if (!opened)
             return c.json({ error: `could not open ${target}`, path: dir }, 409);
         return c.json({ opened: true, path: dir });
-    });
-    // Handoff journal (spec 007): the per-task handoff.md as markdown. 404 only
-    // when the task is unknown; a task without a (yet) seeded file returns ''.
-    api.get('/runs/:id/handoff', (c) => {
+    })
+        // Handoff journal (spec 007): the per-task handoff.md as markdown. 404 only
+        // when the task is unknown; a task without a (yet) seeded file returns ''.
+        .get('/runs/:id/handoff', (c) => {
         const { dataDir, store } = c.get('project');
         const run = store.getRun(c.req.param('id'));
         if (!run)
@@ -2135,16 +3522,8 @@ export function createApp(deps) {
         return c.text(readHandoff(dataDir, run.id), 200, {
             'content-type': 'text/markdown; charset=utf-8',
         });
-    });
-    // Agent screenshots — image blocks the run manager persisted out of tool
-    // results (persistImage). `basename` pins reads inside the run's own dir.
-    const IMAGE_TYPES = {
-        png: 'image/png',
-        jpg: 'image/jpeg',
-        webp: 'image/webp',
-        gif: 'image/gif',
-    };
-    api.get('/runs/:id/images/:file', (c) => {
+    })
+        .get('/runs/:id/images/:file', (c) => {
         const { dataDir, store } = c.get('project');
         const run = store.getRun(c.req.param('id'));
         if (!run)
@@ -2160,9 +3539,9 @@ export function createApp(deps) {
                 'cache-control': 'private, max-age=31536000, immutable',
             },
         });
-    });
-    // Task diff (spec 006): what this run changed — its worktree vs its base.
-    api.get('/runs/:id/diff', async (c) => {
+    })
+        // Task diff (spec 006): what this run changed — its worktree vs its base.
+        .get('/runs/:id/diff', async (c) => {
         const { store } = c.get('project');
         const run = store.getRun(c.req.param('id'));
         if (!run)
@@ -2171,94 +3550,113 @@ export function createApp(deps) {
             return c.text('(no worktree — this task ran directly in the repo working tree)');
         }
         return c.text(await worktreeDiff(run.worktreePath, run.baseBranch ?? 'HEAD'));
-    });
-    // ---- session git view (redesign R5 Step 1.2 — §"Git/session API additions").
-    // Structured sibling of the text-blob /diff above (which stays untouched —
-    // protected surface). Same worktree/base resolution; every predictable git
-    // failure degrades to 409 + human-readable reason, 404 only for unknown ids.
-    const worktreeOf = (run) => run.worktreePath && existsSync(run.worktreePath) ? run.worktreePath : null;
-    const NO_WORKTREE = 'no worktree — this task ran directly in the repo working tree';
-    api.get('/runs/:id/changes', async (c) => {
-        const { store } = c.get('project');
+    })
+        .get('/runs/:id/changes', async (c) => {
+        const { root: repoRoot, store } = c.get('project');
         const run = store.getRun(c.req.param('id'));
         if (!run)
             return c.json({ error: 'not found' }, 404);
-        const worktree = worktreeOf(run);
-        if (!worktree)
+        const workingDirectory = workingDirectoryOf(run, repoRoot);
+        if (!workingDirectory)
             return c.json({ error: NO_WORKTREE }, 409);
-        const result = await collectChanges(worktree, run.baseBranch ?? 'HEAD', { taskBranch: run.branch });
+        const result = await collectChanges(workingDirectory, run.baseBranch ?? 'HEAD', {
+            taskBranch: run.branch,
+            // Anchors a repointed worktree at the branch as this run found it (#751).
+            runStartedAt: run.startedAt,
+            // A read-only GET against the user's real checkout must never modify its index.
+            intentToAdd: run.worktreePath ? undefined : false,
+        });
         if (!result.ok)
             return c.json({ error: result.error }, 409);
         return c.json(result.changes);
-    });
-    // The run's own commits (<base>..HEAD on the worktree branch) — the Commits tab.
-    api.get('/runs/:id/commits', async (c) => {
-        const { store } = c.get('project');
+    })
+        // The run's own commits (<base>..HEAD on the worktree branch) — the Commits tab.
+        .get('/runs/:id/commits', async (c) => {
+        const { root: repoRoot, store } = c.get('project');
         const run = store.getRun(c.req.param('id'));
         if (!run)
             return c.json({ error: 'not found' }, 404);
-        const worktree = worktreeOf(run);
-        if (!worktree)
+        const workingDirectory = workingDirectoryOf(run, repoRoot);
+        if (!workingDirectory)
             return c.json({ error: NO_WORKTREE }, 409);
-        const result = await collectRunCommits(worktree, run.baseBranch ?? 'HEAD');
+        const result = await collectRunCommits(workingDirectory, run.baseBranch ?? 'HEAD');
         if (!result.ok)
             return c.json({ error: result.error }, 409);
         return c.json({ commits: result.commits });
-    });
-    // One of the run's commits, structured like the Changes tab (reuses collectCommitChanges).
-    api.get('/runs/:id/commit/:sha', async (c) => {
-        const { store } = c.get('project');
+    })
+        // One of the run's commits, structured like the Changes tab (reuses collectCommitChanges).
+        .get('/runs/:id/commit/:sha', async (c) => {
+        const { root: repoRoot, store } = c.get('project');
         const run = store.getRun(c.req.param('id'));
         if (!run)
             return c.json({ error: 'not found' }, 404);
-        const worktree = worktreeOf(run);
-        if (!worktree)
+        const workingDirectory = workingDirectoryOf(run, repoRoot);
+        if (!workingDirectory)
             return c.json({ error: NO_WORKTREE }, 409);
-        const result = await collectCommitChanges(worktree, c.req.param('sha'));
+        const result = await collectCommitChanges(workingDirectory, c.req.param('sha'));
         if (!result.ok)
             return c.json({ error: result.error }, 409);
         return c.json(result.commit);
-    });
-    // Files tab: directory listing (path omitted or a dir) or file content
-    // (size-capped, binary flagged). Traversal-safe — readWorktreePath rejects
-    // anything escaping the worktree. `raw=1` (R5 Step 1.6) serves the BYTES of
-    // image files only, for the preview's inline <img> — never HTML/JS/etc., so
-    // no worktree file can become a same-origin document, and never past the
-    // size cap. The no-script CSP neutralizes SVG opened as a top-level URL.
-    api.get('/runs/:id/files', async (c) => {
-        const { store } = c.get('project');
+    })
+        // Files tab: directory listing (path omitted or a dir) or file content
+        // (size-capped, binary flagged). Traversal-safe — readWorktreePath rejects
+        // anything escaping the worktree. `raw=1` (R5 Step 1.6) serves the BYTES of
+        // image files only, for the preview's inline <img> — never HTML/JS/etc., so
+        // no worktree file can become a same-origin document, and never past the
+        // size cap. The no-script CSP neutralizes SVG opened as a top-level URL.
+        //
+        // An `Accept` that asks for images reaches the same raw branch without the flag — which is
+        // what an `<img>` sends — while the flag still wins whenever it is present and `*<slash>*`
+        // (every `fetch`) still gets the JSON listing. See `negotiate`.
+        .get('/runs/:id/files', queryZodValidator(z.object({ path: queryValue, raw: queryValue })), async (c) => {
+        const { root: repoRoot, store } = c.get('project');
+        const query = c.req.valid('query');
+        c.header('vary', 'Accept');
+        const wantsRaw = query.raw !== undefined
+            ? query.raw === '1'
+            : negotiate(c.req.header('accept'), FILE_FORMATS) === 'image/*';
         const run = store.getRun(c.req.param('id'));
         if (!run)
             return c.json({ error: 'not found' }, 404);
-        const worktree = worktreeOf(run);
-        if (!worktree)
+        const workingDirectory = workingDirectoryOf(run, repoRoot);
+        if (!workingDirectory)
             return c.json({ error: NO_WORKTREE }, 409);
-        const result = await readWorktreePath(worktree, c.req.query('path') ?? '');
+        const result = await readWorktreePath(workingDirectory, query.path ?? '');
         if (result.kind === 'invalid' || result.kind === 'missing') {
             return c.json({ error: result.error }, 409);
         }
         if (result.kind === 'dir') {
             return c.json({
+                // `as const` or the literal widens to `string` during Hono's route-type inference,
+                // which erases the discriminant a consumer narrows on — `entry.type === 'dir'` then
+                // leaves `never` and every field access on it fails. The wire was always 'dir'.
                 type: 'dir',
                 path: result.path,
                 entries: result.entries,
             });
         }
-        if (c.req.query('raw') === '1') {
+        if (wantsRaw) {
             const mime = imageMimeType(result.path);
-            if (!mime)
-                return c.json({ error: `raw serving is limited to images: ${result.path}` }, 409);
-            if (result.tooLarge) {
-                return c.json({
-                    error: `file too large to serve raw (${result.size} bytes): ${result.path}`,
-                }, 409);
+            if (mime === null || result.tooLarge) {
+                // `?raw=1` ASKED for bytes, so it hears why it cannot have them — that 409 and its
+                // wording are the protected surface (§2). An `Accept` is only a preference, so a
+                // resource with no image representation falls THROUGH to the JSON answer below rather
+                // than turning a browser's navigation to a text file into an error.
+                if (query.raw !== undefined) {
+                    const error = mime === null
+                        ? `raw serving is limited to images: ${result.path}`
+                        : `file too large to serve raw (${result.size} bytes): ${result.path}`;
+                    return c.json({ error }, 409);
+                }
+            }
+            else {
+                const bytes = await readFile(join(workingDirectory, result.path));
+                return c.body(new Uint8Array(bytes).buffer, 200, {
+                    'content-type': mime,
+                    'x-content-type-options': 'nosniff',
+                    'content-security-policy': "default-src 'none'; style-src 'unsafe-inline'; sandbox",
+                });
             }
-            const bytes = await readFile(join(worktree, result.path));
-            return c.body(new Uint8Array(bytes).buffer, 200, {
-                'content-type': mime,
-                'x-content-type-options': 'nosniff',
-                'content-security-policy': "default-src 'none'; style-src 'unsafe-inline'; sandbox",
-            });
         }
         return c.json({
             type: 'file',
@@ -2268,8 +3666,8 @@ export function createApp(deps) {
             tooLarge: result.tooLarge,
             ...(result.content !== undefined ? { content: result.content } : {}),
         });
-    });
-    api.post('/runs/:id/git/commit', async (c) => {
+    })
+        .post('/runs/:id/git/commit', jsonZodValidator(gitCommitSchema), async (c) => {
         const { store } = c.get('project');
         const run = store.getRun(c.req.param('id'));
         if (!run)
@@ -2277,16 +3675,13 @@ export function createApp(deps) {
         const worktree = worktreeOf(run);
         if (!worktree)
             return c.json({ error: NO_WORKTREE }, 409);
-        const parsed = gitCommitSchema.safeParse(await c.req.json().catch(() => null));
-        if (!parsed.success) {
-            return c.json({ error: parsed.error.issues.map((i) => i.message).join('; ') }, 400);
-        }
+        const parsed = { data: c.req.valid('json') };
         const result = await commitAll(worktree, parsed.data.message);
         if (!result.ok)
             return c.json({ error: result.error }, 409);
         return c.json({ committed: true, sha: result.sha });
-    });
-    api.post('/runs/:id/git/push', async (c) => {
+    })
+        .post('/runs/:id/git/push', async (c) => {
         const { store } = c.get('project');
         const run = store.getRun(c.req.param('id'));
         if (!run)
@@ -2303,12 +3698,12 @@ export function createApp(deps) {
             remote: result.remote,
             upstreamSet: result.upstreamSet,
         });
-    });
-    // Draft PR from the review gate (spec 009): final autosave → push →
-    // `gh pr create --draft`; on success the run completes as done with the PR
-    // badge. Failures come back as 409 with a `manual` merge command the GUI
-    // shows next to the toast. CEZ_DRY_RUN=1 fakes the URL (no push, no gh).
-    api.post('/runs/:id/pr', async (c) => {
+    })
+        // Draft PR from the review gate (spec 009): final autosave → push →
+        // `gh pr create --draft`; on success the run completes as done with the PR
+        // badge. Failures come back as 409 with a `manual` merge command the GUI
+        // shows next to the toast. CEZ_DRY_RUN=1 fakes the URL (no push, no gh).
+        .post('/runs/:id/pr', async (c) => {
         const { root: repoRoot, dataDir, store, manager } = c.get('project');
         const id = c.req.param('id');
         const run = store.getRun(id);
@@ -2339,10 +3734,10 @@ export function createApp(deps) {
             message: `draft PR created: ${outcome.url}${outcome.dryRun ? ' (dry run — no real PR)' : ''}`,
         });
         return c.json({ url: outcome.url, dryRun: outcome.dryRun }, 201);
-    });
-    // Archived tasks keep their worktree for inspection; this is the explicit
-    // "🧹 Remove worktree" cleanup (spec 006).
-    api.post('/runs/:id/remove-worktree', async (c) => {
+    })
+        // Archived tasks keep their worktree for inspection; this is the explicit
+        // "🧹 Remove worktree" cleanup (spec 006).
+        .post('/runs/:id/remove-worktree', async (c) => {
         const { root: repoRoot, store, manager } = c.get('project');
         const id = c.req.param('id');
         const run = store.getRun(id);
@@ -2354,8 +3749,8 @@ export function createApp(deps) {
             await removeWorktree(repoRoot, run.worktreePath, run.branch);
         store.updateRun(id, { worktreePath: undefined, branch: undefined });
         return c.json({ removed: true });
-    });
-    api.delete('/runs/:id', async (c) => {
+    })
+        .delete('/runs/:id', async (c) => {
         const { root: repoRoot, store, manager } = c.get('project');
         const id = c.req.param('id');
         if (manager.isActive(id))
@@ -2368,11 +3763,140 @@ export function createApp(deps) {
             await removeWorktree(repoRoot, run.worktreePath, run.branch);
         return store.deleteRun(id) ? c.json({ deleted: true }) : c.json({ error: 'not found' }, 404);
     });
-    // ---- worktree management panel (#483) --------------------------------------
-    // List materialized task worktrees with disk usage + retention state, and a
-    // "Reclaim now" action. Both additive; the per-row delete reuses the existing
-    // /api/runs/:id/remove-worktree route above.
-    api.get('/worktrees', async (c) => {
+    // ---- parallel variants (spec 010) -----------------------------------------
+    const groupRuns = (store, groupId) => store
+        .listRuns()
+        .filter((r) => r.groupId === groupId)
+        .sort((a, b) => (a.variant ?? '').localeCompare(b.variant ?? ''));
+    // ---- chained family: variant groups (project-scoped) ----
+    const groupsRoutes = new Hono()
+        .get('/groups/:groupId', async (c) => {
+        const { dataDir, store } = c.get('project');
+        const runs = groupRuns(store, c.req.param('groupId'));
+        if (runs.length === 0)
+            return c.json({ error: 'not found' }, 404);
+        const detailed = await Promise.all(runs.map(async (r) => ({
+            id: r.id,
+            variant: r.variant ?? '?',
+            title: r.title,
+            status: r.status,
+            archived: r.archived,
+            tokensUsed: r.tokensUsed,
+            ...(r.inputTokens !== undefined ? { inputTokens: r.inputTokens } : {}),
+            ...(r.outputTokens !== undefined ? { outputTokens: r.outputTokens } : {}),
+            ...(r.costUsd !== undefined ? { costUsd: r.costUsd } : {}),
+            diffStat: r.worktreePath && existsSync(r.worktreePath)
+                ? await worktreeDiffStat(r.worktreePath, r.baseBranch ?? 'HEAD')
+                : '',
+            handoffExcerpt: handoffProgressExcerpt(readHandoff(dataDir, r.id)),
+        })));
+        return c.json({
+            groupId: c.req.param('groupId'),
+            runs: detailed,
+        });
+    })
+        // "Pick this one": the winner rests at `review` (spec 009 takes it from
+        // there — send back / draft PR / finish); the losers are cancelled if
+        // alive, archived, and their worktrees + branches removed.
+        .post('/groups/:groupId/pick', jsonZodValidator(pickSchema), async (c) => {
+        const { root: repoRoot, dataDir, store, manager } = c.get('project');
+        const runs = groupRuns(store, c.req.param('groupId'));
+        if (runs.length === 0)
+            return c.json({ error: 'not found' }, 404);
+        const parsed = { data: c.req.valid('json') };
+        const winner = runs.find((r) => r.id === parsed.data.runId);
+        if (!winner)
+            return c.json({ error: 'runId is not part of this group' }, 404);
+        if (manager.isActive(winner.id)) {
+            return c.json({ error: 'this variant is still active — wait for it to finish first' }, 409);
+        }
+        // Winner: a non-review terminal state with a non-empty diff flips to
+        // `review` (the settleSuccess rule) — but only when the review gate applies
+        // (#489): it is enabled (`reviewGateEnabled`, default off) AND the winner is
+        // not autonomous. An autonomous / gate-off winner keeps its `done` state with
+        // the diff left in the worktree; an empty diff (or no worktree) stays too.
+        if (winner.status !== 'review' &&
+            winner.worktreePath &&
+            existsSync(winner.worktreePath) &&
+            winner.autonomous !== true &&
+            reviewGateEnabled(await loadConfig(repoRoot))) {
+            const diff = await worktreeDiff(winner.worktreePath, winner.baseBranch ?? 'HEAD');
+            if (diff.trim().length > 0 && !diff.startsWith('(diff failed')) {
+                store.updateRun(winner.id, { status: 'review' });
+            }
+        }
+        const losers = runs.filter((r) => r.id !== winner.id);
+        store.appendEvent(winner.id, {
+            type: 'lifecycle',
+            message: `picked from ${runs.length} variants — ${losers.length} other variant(s) archived`,
+        });
+        appendHandoffHeartbeat(dataDir, winner.id, `picked from ${runs.length} variants`);
+        for (const loser of losers) {
+            if (manager.isActive(loser.id))
+                manager.cancel(loser.id);
+            if (loser.worktreePath)
+                await removeWorktree(repoRoot, loser.worktreePath, loser.branch);
+            store.updateRun(loser.id, { worktreePath: undefined, branch: undefined });
+            store.setArchived(loser.id, true);
+            store.appendEvent(loser.id, {
+                type: 'lifecycle',
+                message: `variant ${winner.variant ?? '?'} was picked — this variant is archived, its worktree removed`,
+            });
+        }
+        // Spread: `getRun` may answer undefined, and an undefined VALUE is dropped by
+        // JSON.stringify — so writing the key unconditionally typed the route as sending a key it
+        // does not. contract/workflows.ts says `.optional()`, which is what a client receives.
+        const picked = store.getRun(winner.id);
+        return c.json({ ...(picked !== undefined ? { winner: picked } : {}) });
+    });
+    // ---- chained family: open-targets (project-scoped) ----
+    const openTargetsRoutes = new Hono()
+        .get('/open-targets', (c) => c.json({ targets: capabilities().localHandoff ? detectOpenTargets() : [] }))
+        // Open the PROJECT ROOT itself (Settings → "Project folder" → Open with). The run route
+        // above opens a task worktree and needs a run to name one; this is the repo the cockpit is
+        // scoped to, which the scope middleware has already resolved — so no path is accepted from
+        // the client and there is nothing to contain.
+        .post('/open-in', jsonZodValidator(openProjectInSchema), async (c) => {
+        const { root } = c.get('project');
+        if (!capabilities().localHandoff) {
+            return c.json({ error: 'local handoff is disabled — this cockpit runs in hosted mode (CEZ_REMOTE)' }, 409);
+        }
+        const { target } = c.req.valid('json');
+        // Refused here rather than left to the menu, on the same principle as the accounts route:
+        // a `cli:<runner>` handoff would START AN AGENT in the checkout everything else runs in a
+        // worktree to protect. Which app APPLIES is a property of the route, not of one client.
+        if (agentCliRunner(target) !== null) {
+            return c.json({ error: 'agent CLIs open a task worktree, not the project folder' }, 400);
+        }
+        if (!detectOpenTargets().some((candidate) => candidate.id === target)) {
+            return c.json({ error: `no such app on this machine: ${target}` }, 400);
+        }
+        const opened = await openApp(target, root);
+        if (!opened)
+            return c.json({ error: `could not open ${target}`, path: root }, 409);
+        return c.json({ opened: true, path: root });
+    });
+    // Agent screenshots — image blocks the run manager persisted out of tool
+    // results (persistImage). `basename` pins reads inside the run's own dir.
+    const IMAGE_TYPES = {
+        png: 'image/png',
+        jpg: 'image/jpeg',
+        webp: 'image/webp',
+        gif: 'image/gif',
+    };
+    // ---- session git view (redesign R5 Step 1.2 — §"Git/session API additions").
+    // Structured sibling of the text-blob /diff above (which stays untouched —
+    // protected surface). Isolated runs read their worktree; worktree-off runs
+    // read the repo checkout they executed in. Every predictable git failure
+    // degrades to 409 + human-readable reason, 404 only for unknown ids.
+    const worktreeOf = (run) => run.worktreePath && existsSync(run.worktreePath) ? run.worktreePath : null;
+    const workingDirectoryOf = (run, repoRoot) => run.worktree === false
+        ? repoRoot
+        : worktreeOf(run);
+    const NO_WORKTREE = 'no worktree — this task ran directly in the repo working tree';
+    // ---- chained family: worktrees (project-scoped) ----
+    const worktreesRoutes = new Hono()
+        .get('/worktrees', async (c) => {
         const { root: repoRoot, store } = c.get('project');
         // The keep-limit the panel reports is the one the enforcer will actually
         // apply — inherited from the workspace default when this repo sets none.
@@ -2393,60 +3917,68 @@ export function createApp(deps) {
             ? null
             : worktrees.reduce((sum, w) => sum + (w.sizeBytes ?? 0), 0);
         return c.json({ worktrees, totalBytes, keep });
-    });
-    const reclaimBodySchema = z.object({}).passthrough();
-    api.post('/worktrees/reclaim', async (c) => {
+    })
+        .post('/worktrees/reclaim', jsonZodValidator(() => reclaimBodySchema, { absent: ({}), message: 'invalid body' }), async (c) => {
         const { root: repoRoot, store } = c.get('project');
-        // Accept an empty or `{}` body; retention is best-effort, so 200 always.
-        const parsed = reclaimBodySchema.safeParse(await c.req.json().catch(() => ({})));
-        if (!parsed.success)
-            return c.json({ error: 'invalid body' }, 400);
+        // The body is validated (an empty or `{}` one is accepted) but carries nothing this
+        // handler reads; retention is best-effort, so 200 always.
         const reclaimed = await reclaimWorktrees(repoRoot, store, await resolveWorktreeRetention(repoRoot));
         return c.json({ reclaimed });
     });
-    // ---- inbox (spec 007) ------------------------------------------------------
-    // Opt-in via CEZ_FOLLOWUPS=1 (#471). Off, the reader degrades to an empty
-    // inbox (a 404 would make old clients surface an error for a feature that is
-    // merely switched off) and the mutators 409 as defense in depth — the shape
-    // the hosted-mode open-in-* handlers already use. Existing todos.json entries
-    // are never touched, so flipping the env back on restores them.
-    api.get('/todos', async (c) => c.json(capabilities().followups ? await readTodos(c.get('project').dataDir) : []));
-    // Check off = delete the entry.
-    api.delete('/todos/:id', async (c) => {
+    const reclaimBodySchema = z.object({}).passthrough();
+    /**
+     * "The inbox is on and this entry exists" — the 409/404 half of `POST /todos/:id/start`, lifted
+     * out of the handler and in FRONT of the body validator.
+     *
+     * That position is the whole point. The route's contract is that an unknown id 404s before the
+     * body is looked at, and Hono only records a body in the route type when it is validated as
+     * MIDDLEWARE — which necessarily runs before the handler. Registering this guard first satisfies
+     * both: the documented status order is unchanged, and `startTodoSchema` becomes visible to
+     * `AppType` (and so to `hc`) instead of being parsed invisibly inside the handler.
+     *
+     * Deliberately NOT annotated with a return type: the inferred one carries the two typed
+     * responses, which is what keeps the 409 and 404 branches in the route's schema for the client.
+     */
+    const todoMustExist = async (c, next) => {
+        if (!capabilities().followups)
+            return c.json({ error: FOLLOWUPS_OFF }, 409);
+        const todo = (await readTodos(c.get('project').dataDir)).find((t) => t.id === c.req.param('id'));
+        if (!todo)
+            return c.json({ error: 'not found' }, 404);
+        c.set('todo', todo);
+        await next();
+    };
+    // ---- chained family: follow-up inbox / todos (project-scoped) ----
+    const todosRoutes = new Hono()
+        .get('/todos', async (c) => c.json(capabilities().followups ? await readTodos(c.get('project').dataDir) : []))
+        // Check off = delete the entry.
+        .delete('/todos/:id', async (c) => {
         const { dataDir } = c.get('project');
         if (!capabilities().followups)
             return c.json({ error: FOLLOWUPS_OFF }, 409);
         const removed = await removeTodo(dataDir, c.req.param('id'));
         return removed ? c.json({ removed: true }) : c.json({ error: 'not found' }, 404);
-    });
-    // "▶ Run": turn an inbox entry into a task — a one-off single-step workflow
-    // around the suggested skill when it exists, plain quick-task otherwise.
-    api.post('/todos/:id/start', async (c) => {
+    })
+        // "▶ Run": turn an inbox entry into a task — a one-off single-step workflow
+        // around the suggested skill when it exists, plain quick-task otherwise.
+        //
+        // TWO middlewares, and their ORDER is the contract. This route's documented status order
+        // (pinned by todos-start.test.ts) is that a disabled inbox 409s and an unknown id 404s BEFORE
+        // the body is looked at — which is why the body used to be parsed inline, invisible to `hc`.
+        // Hono runs route middleware in registration order, so `todoMustExist` FIRST keeps that order
+        // exactly while `jsonZodValidator` second is what records the body in the route type.
+        //
+        // The two no-body cases the old inline parse distinguished are carried by the validator's
+        // `absent`/`malformed` options: no body at all is `undefined` (the pre-#401 bodyless POST,
+        // which the optional schema accepts → 201), a truncated payload is `null` (which it rejects
+        // → 400, rather than passing as "no body" and silently starting a run).
+        .post('/todos/:id/start', todoMustExist, jsonZodValidator(startTodoSchema, { absent: undefined, malformed: null }), async (c) => {
         const { root: repoRoot, dataDir, manager } = c.get('project');
-        if (!capabilities().followups)
-            return c.json({ error: FOLLOWUPS_OFF }, 409);
         const id = c.req.param('id');
-        const todo = (await readTodos(dataDir)).find((t) => t.id === id);
-        if (!todo)
-            return c.json({ error: 'not found' }, 404);
-        // Body is optional and read exactly once (runner/model #401 + prompt #413 share it). A
-        // request with none at all (the pre-pills/pre-composer client) stays `undefined`, same as an
-        // empty `{}`. A body that IS present but is not valid JSON becomes `null`, which the schema
-        // rejects → 400 (the `.catch(() => null)` pattern every other mutating route uses); mapping
-        // it to `undefined` too would let a broken payload pass as "no body" and silently 201.
-        const rawBody = await c.req.text().catch(() => '');
-        let body;
-        if (rawBody.trim().length > 0) {
-            try {
-                body = JSON.parse(rawBody);
-            }
-            catch {
-                body = null;
-            }
-        }
-        const parsed = startTodoSchema.safeParse(body);
-        if (!parsed.success) {
-            return c.json({ error: parsed.error.issues.map((i) => i.message).join('; ') }, 400);
+        const todo = c.get('todo');
+        const parsed = { data: c.req.valid('json') };
+        if (agentModelsLocked(repoRoot) && parsed.data?.model?.trim()) {
+            return c.json({ error: AGENT_MODELS_LOCKED_ERROR }, 409);
         }
         if (todo.startedTaskId)
             return c.json({ error: 'already started' }, 409);
@@ -2476,6 +4008,10 @@ export function createApp(deps) {
             const { workflows } = await loadWorkflows(repoRoot);
             workflow = workflows.find((w) => w.name === 'quick-task') ?? QUICK_TASK_WORKFLOW;
         }
+        const fallback = parsed.data?.runner ?? (await loadConfig(repoRoot)).defaultRunner;
+        const blocked = await providerActionError(providersRequiredByWorkflow(workflow, fallback));
+        if (blocked)
+            return c.json({ error: blocked }, 409);
         const run = manager.startRun(workflow, {
             task,
             runner: parsed.data?.runner,
@@ -2483,18 +4019,31 @@ export function createApp(deps) {
         });
         await markStarted(dataDir, id, run.id);
         return c.json({ run }, 201);
-    });
-    // Per-run SSE: full replay from the NDJSON file, then live events. The
-    // listener attaches before the replay and buffers, so nothing emitted
-    // during the replay is lost or duplicated (dedup by seq).
-    api.get('/runs/:id/events', (c) => {
-        const { store } = c.get('project');
-        const id = c.req.param('id');
+    });
+    // ---- chained family: SSE streams (project-scoped) ----
+    const sseRoutes = new Hono()
+        .get('/runs/:id/events', paramZodValidator(runIdParamSchema), queryZodValidator(runEventsQuerySchema), async (c) => {
+        const { store, dataDir } = c.get('project');
+        const { id } = c.req.valid('param');
         if (!store.getRun(id))
             return c.json({ error: 'not found' }, 404);
+        const query = c.req.valid('query');
+        const eventsPath = join(dataDir, 'runs', `${id}.ndjson`);
+        if (query.cursor) {
+            try {
+                await validateLiveCursor(eventsPath, query.cursor);
+            }
+            catch (error) {
+                if (error instanceof HistoryCursorError)
+                    return c.json({ error: error.message }, error.status);
+                throw error;
+            }
+        }
+        const lastEventId = Number.parseInt(c.req.header('Last-Event-ID') ?? '', 10);
+        const requestedAfter = Math.max(query.afterSeq ?? 0, Number.isSafeInteger(lastEventId) && lastEventId >= 0 ? lastEventId : 0);
         return streamSSENoBuffer(c, async (stream) => {
             let replaying = true;
-            let maxSeq = 0;
+            let maxSeq = requestedAfter;
             const buffered = [];
             // One endpoint, two SSE event names: v1 lines stay `run-event` (the name
             // the legacy UI listened to — its default branch JSON-dumped unknown
@@ -2504,6 +4053,7 @@ export function createApp(deps) {
             // ride `ui-event`, which only v2-aware clients subscribe to.
             // EventSource ignores names it has no listener for.
             const writeEvent = (event) => stream.writeSSE({
+                id: String(event.seq),
                 event: isV2WireEventType(event.type) ? 'ui-event' : 'run-event',
                 data: JSON.stringify(event),
             });
@@ -2526,9 +4076,15 @@ export function createApp(deps) {
                 store.off('event', onEvent);
                 store.off('run', onRun);
             });
-            for (const event of store.readEvents(id)) {
-                maxSeq = Math.max(maxSeq, event.seq);
+            const replay = query.cursor
+                ? await readEventsAfterLiveCursor(eventsPath, query.cursor)
+                : { events: store.readEvents(id), boundarySeq: 0 };
+            maxSeq = Math.max(maxSeq, replay.boundarySeq);
+            for (const event of replay.events) {
+                if (event.seq <= maxSeq)
+                    continue;
                 await writeEvent(event);
+                maxSeq = event.seq;
             }
             replaying = false;
             for (const event of buffered) {
@@ -2543,13 +4099,13 @@ export function createApp(deps) {
                 await stream.sleep(15_000);
             }
         });
-    });
-    // Global SSE: run-summary updates for the list view + inbox changes.
-    // Scoped `/p/:projectId/events` carries that project's stream in today's
-    // shape; the legacy unprefixed alias stays bound to the boot project ONLY
-    // (spec "Legacy aliases" — widening it would be a silent behavioral break;
-    // the all-project stream arrives as `/api/workspace/events` in step 2.8).
-    api.get('/events', (c) => {
+    })
+        // Global SSE: run-summary updates for the list view + inbox changes.
+        // Scoped `/p/:projectId/events` carries that project's stream in today's
+        // shape; the legacy unprefixed alias stays bound to the boot project ONLY
+        // (spec "Legacy aliases" — widening it would be a silent behavioral break;
+        // the all-project stream arrives as `/api/workspace/events` in step 2.8).
+        .get('/events', (c) => {
         const { dataDir, store } = c.get('project');
         return streamSSENoBuffer(c, async (stream) => {
             const onRun = (run) => void stream.writeSSE({ event: 'run', data: JSON.stringify(run) });
@@ -2595,22 +4151,9 @@ export function createApp(deps) {
             }
         });
     });
-    // ---- workspace SSE (multi-project spec, step 2.8) ------------------------
-    // The cockpit's future single EventSource: one stream, every project.
-    // WORKSPACE-level (single-mount on `app`, never mirrored under /api/p/).
-    // Same event names as the per-project stream, but every payload is stamped
-    // with the owning `project` id — additively where the legacy payload is an
-    // object (`run` grows a `project` key, `run-deleted` becomes
-    // `{id, project}`), wrapped where it is not (`todos` → `{project, items}`,
-    // `usage` → `{project, usage}` — a bare array/record has nowhere to carry a
-    // stamp). The legacy `/api/events` alias above keeps its UN-stamped,
-    // boot-filtered shape — that stream is a protected surface.
-    //
-    // Subscribing NEVER force-instantiates a project: only the boot context
-    // (always live) and already-built lazy contexts are attached at connect;
-    // contexts built later join via the `onContextBuilt` hook, so a project's
-    // first API touch makes its events flow to streams already open.
-    app.get('/api/workspace/events', (c) => {
+    // ---- chained family: workspace SSE stream (workspace-level) ----
+    const workspaceEventsRoutes = new Hono()
+        .get('/workspace/events', (c) => {
         return streamSSENoBuffer(c, async (stream) => {
             // One detach bundle per attached project — the id guard makes a double
             // attach (connect-time snapshot vs. the built hook) impossible.
@@ -2682,11 +4225,12 @@ export function createApp(deps) {
                 }
             });
             // Workspace-level events (project-added / project-removed /
-            // checkout-progress) — relayed verbatim under their own names. A
-            // removal also drops the project's attach entry: the id guard in
-            // `attach` would otherwise pin the DISPOSED context forever, so a
-            // project removed and re-added on the same slug would rebuild a fresh
-            // context whose events never reach this already-open stream.
+            // checkout-progress plus host-wide unstamped provider-status) — relayed
+            // verbatim under their own names. A removal also drops the project's
+            // attach entry: the id guard in `attach` would otherwise pin the
+            // DISPOSED context forever, so a project removed and re-added on the
+            // same slug would rebuild a fresh context whose events never reach this
+            // already-open stream.
             const offWorkspace = workspaceEvents.on((event, data) => {
                 if (event === 'project-removed') {
                     const removed = data.id;
@@ -2711,23 +4255,25 @@ export function createApp(deps) {
             }
         });
     });
-    // ---- GitHub tab ------------------------------------------------------------
-    // Issues + PRs of the repo's origin, read through the logged-in `gh` CLI.
-    // Degrades to `{available:false, reason}` — no gh / no remote / offline all
-    // just render as a hint in the tab, never an error.
-    api.get('/github', async (c) => {
+    // ---- chained family: GitHub (project-scoped) ----
+    // These sit ABOVE the routes rather than with the family's other schemas below it, because a
+    // validator argument is evaluated when the route is REGISTERED — a schema declared further down
+    // would be in its temporal dead zone. (The schemas below are all read inside a handler, or
+    // passed as a thunk, which defers them past that point.)
+    const mergeNumberParams = z.object({ number: z.coerce.number().int().positive() });
+    const prChangesParams = z.object({ number: z.coerce.number().int().positive().safe() });
+    const prChangesQuery = z.object({ refresh: queryValue.refine((v) => v === undefined || v === '1') });
+    const githubRoutes = new Hono()
+        .get('/github', 
+    // `limit` stays a bare string: the handler's `Number.parseInt`/`Number.isFinite` fallback to
+    // 30 already accepts `?limit=banana`, and a numeric schema would 400 it instead.
+    queryZodValidator(z.object({ limit: queryValue, refresh: queryValue })), async (c) => {
         const { root: repoRoot } = c.get('project');
-        const limit = Number.parseInt(c.req.query('limit') ?? '', 10);
-        return c.json(await fetchGithub(repoRoot, c.req.query('refresh') === '1', Number.isFinite(limit) ? limit : 30));
-    });
-    // The full comment thread for one issue/PR (#499). Additive sibling of /api/github — lazy
-    // (fetched only while a detail view is open), zod-validated params, 400 on garbage, and the
-    // same in-payload availability degrade (gh missing / offline / 404 all render as a hint).
-    const commentsParams = z.object({
-        kind: z.enum(['issue', 'pr']),
-        number: z.coerce.number().int().positive(),
-    });
-    api.get('/github/comments/:kind/:number', async (c) => {
+        const query = c.req.valid('query');
+        const limit = Number.parseInt(query.limit ?? '', 10);
+        return c.json(await fetchGithub(repoRoot, query.refresh === '1', Number.isFinite(limit) ? limit : 30));
+    })
+        .get('/github/comments/:kind/:number', queryZodValidator(refreshQuery), async (c) => {
         const { root: repoRoot } = c.get('project');
         const parsed = commentsParams.safeParse({
             kind: c.req.param('kind'),
@@ -2735,10 +4281,86 @@ export function createApp(deps) {
         });
         if (!parsed.success)
             return c.json({ error: 'invalid kind or number' }, 400);
-        return c.json(await fetchGithubComments(repoRoot, parsed.data.kind, parsed.data.number, c.req.query('refresh') === '1'));
+        return c.json(await fetchGithubComments(repoRoot, parsed.data.kind, parsed.data.number, c.req.valid('query').refresh === '1'));
+    })
+        // Lazy checks glyphs for on-screen PR rows (#664). Additive sibling of /api/github — the list
+        // call dropped `statusCheckRollup` (the dominant cost), so the glyph is hydrated here per
+        // visible row. `prs` is a comma-separated list of positive integers, capped at GH_CHECKS_MAX;
+        // anything malformed is a 400. Same in-payload availability degrade as the list (never a 5xx).
+        // `prs` is the one genuinely REQUIRED query key on this server, so it is the one validated
+        // strictly — `.min(1)` because `?prs=` answered `missing prs query` before it answered
+        // `invalid prs query`, and both spellings must keep their own words.
+        .get('/github/checks', queryZodValidator(z.object({ prs: z.string().min(1) }), { message: 'missing prs query' }), async (c) => {
+        const { root: repoRoot } = c.get('project');
+        const raw = c.req.valid('query').prs;
+        const parts = raw.split(',').map((p) => p.trim()).filter(Boolean);
+        if (parts.length === 0 || parts.length > GH_CHECKS_MAX)
+            return c.json({ error: 'invalid prs query' }, 400);
+        const numbers = [];
+        for (const part of parts) {
+            const n = Number(part);
+            if (!Number.isInteger(n) || n <= 0 || String(n) !== part)
+                return c.json({ error: 'invalid prs query' }, 400);
+            numbers.push(n);
+        }
+        return c.json(await fetchGithubChecks(repoRoot, numbers));
+    })
+        .get('/github/prs/:number/merge-state', paramZodValidator(mergeNumberParams, { message: 'invalid pull request number' }), queryZodValidator(refreshQuery), async (c) => {
+        const { root: repoRoot } = c.get('project');
+        const parsed = { data: c.req.valid('param') };
+        const forge = resolveForge(await getRepoInfo(repoRoot));
+        if (!forge?.prMergeState)
+            return c.json({ available: false, reason: 'GitHub merge state is unavailable' });
+        return c.json(await forge.prMergeState(parsed.data.number, { refresh: c.req.valid('query').refresh === '1' }));
+    })
+        .post('/github/prs/:number/merge', paramZodValidator(mergeNumberParams, { message: 'invalid pull request number' }), jsonZodValidator(() => mergeBodySchema, { message: 'invalid merge request' }), async (c) => {
+        const { root: repoRoot } = c.get('project');
+        const parsedNumber = { data: c.req.valid('param') };
+        const body = { data: c.req.valid('json') };
+        const forge = resolveForge(await getRepoInfo(repoRoot));
+        if (!forge?.mergePR)
+            return c.json({ error: 'GitHub merge is unavailable' }, 409);
+        const result = await forge.mergePR(parsedNumber.data.number, body.data);
+        if (result.merged)
+            return c.json(result);
+        return c.json({
+            error: result.error,
+            ...(result.code ? { code: result.code } : {}),
+            ...(result.current ? { current: result.current } : {}),
+        }, result.status);
+    })
+        .get('/github/prs/:number/changes', 
+    // Split out of one `safeParse` over both inputs, because a path param and the query string
+    // are separate validation targets to Hono and only a split makes each visible to the route
+    // type. Both keep the single 400 sentence the combined parse answered. `refresh` stays
+    // STRICT here (`?refresh=true` is a 400 today, unlike everywhere else on this server).
+    paramZodValidator(prChangesParams, { message: 'invalid pull request number or refresh flag' }), queryZodValidator(prChangesQuery, { message: 'invalid pull request number or refresh flag' }), async (c) => {
+        const { root: repoRoot } = c.get('project');
+        const parsed = { data: c.req.valid('param') };
+        try {
+            return c.json(await fetchGithubPrDiff(repoRoot, parsed.data.number, c.req.valid('query').refresh === '1'));
+        }
+        catch (err) {
+            if (err instanceof GithubPrNotFoundError)
+                return c.json({ error: err.message }, 404);
+            throw err;
+        }
+    });
+    // The full comment thread for one issue/PR (#499). Additive sibling of /api/github — lazy
+    // (fetched only while a detail view is open), zod-validated params, 400 on garbage, and the
+    // same in-payload availability degrade (gh missing / offline / 404 all render as a hint).
+    const commentsParams = z.object({
+        kind: z.enum(['issue', 'pr']),
+        number: z.coerce.number().int().positive(),
     });
-    // ---- repo view -----------------------------------------------------------
-    api.get('/repo', async (c) => {
+    const mergeBodySchema = z.object({
+        method: z.enum(['merge', 'squash', 'rebase']),
+        expectedHeadSha: z.string().regex(/^[0-9a-f]{40}$/),
+        overrideRules: z.boolean().optional().default(false),
+    }).strict();
+    // ---- chained family: repo / git (project-scoped) ----
+    const repoRoutes = new Hono()
+        .get('/repo', async (c) => {
         const { root: repoRoot } = c.get('project');
         const info = await getRepoInfo(repoRoot);
         if (!info)
@@ -2762,64 +4384,115 @@ export function createApp(deps) {
             branches,
             baseBranch: config.baseBranch ?? null,
         });
+    })
+        .get('/repo/diff', async (c) => {
+        const { root: repoRoot } = c.get('project');
+        const info = await getRepoInfo(repoRoot);
+        if (!info)
+            return c.text('not a git repository');
+        return c.text(await getDiff(info.root));
+    })
+        // One commit's message + stat + patch — the Repo view expands it inline.
+        // `?structured=1` is the ADDITIVE sibling (R5 Step 1.7): the new repo view's commit-diff
+        // shape `{sha, subject, author, when, files, stat}` with 409 + reason on failure. The
+        // legacy text answer below is a protected surface (BACKWARD_COMPATIBILITY.md §2) — its
+        // shape, including the in-band failure sentences, stays exactly as it was.
+        //
+        // `Accept: application/json` reaches the same structured answer without the flag, and
+        // `Accept: text/plain` asks for the blob; the flag still wins whenever it is present, and a
+        // request with no opinion still gets the blob. See `negotiate`.
+        .get('/repo/commit/:sha', queryZodValidator(z.object({ structured: queryValue })), async (c) => {
+        const { root: repoRoot } = c.get('project');
+        c.header('vary', 'Accept');
+        const { structured } = c.req.valid('query');
+        const wantsJson = structured !== undefined
+            ? structured === '1'
+            : negotiate(c.req.header('accept'), COMMIT_FORMATS) === 'application/json';
+        const info = await getRepoInfo(repoRoot);
+        if (wantsJson) {
+            if (!info)
+                return c.json({ error: 'not a git repository' }, 409);
+            const result = await collectCommitChanges(info.root, c.req.param('sha'));
+            if (!result.ok)
+                return c.json({ error: result.error }, 409);
+            return c.json(result.commit);
+        }
+        if (!info)
+            return c.text('not a git repository');
+        try {
+            return c.text(await getCommit(info.root, c.req.param('sha')));
+        }
+        catch (err) {
+            return c.text(`(git show failed: ${err instanceof Error ? err.message : String(err)})`);
+        }
+    })
+        // Structured sibling of the text-blob /api/repo/diff above (protected
+        // surface, untouched): the same {files, stat} shape the session /changes
+        // route serves, here for the MAIN working tree's uncommitted changes vs
+        // HEAD (redesign R5 Step 1.3 — §"Git/session API additions").
+        .get('/repo/changes', async (c) => {
+        const { root: repoRoot } = c.get('project');
+        const info = await getRepoInfo(repoRoot);
+        if (!info)
+            return c.json({ error: 'not a git repository' }, 409);
+        // The user's REAL working tree — never stage into their index (a GET must not write).
+        const result = await collectChanges(info.root, 'HEAD', {
+            intentToAdd: false,
+        });
+        if (!result.ok)
+            return c.json({ error: result.error }, 409);
+        return c.json(result.changes);
+    })
+        .post('/repo/branch', jsonZodValidator(() => repoBranchSchema), async (c) => {
+        const { root: repoRoot } = c.get('project');
+        const info = await getRepoInfo(repoRoot);
+        if (!info)
+            return c.json({ error: 'not a git repository' }, 409);
+        const parsed = { data: c.req.valid('json') };
+        const result = await createOrSwitchBranch(info.root, parsed.data.name, parsed.data.from);
+        if (!result.ok)
+            return c.json({ error: result.error }, 409);
+        return c.json({ branch: result.branch, created: result.created });
     });
     // The Settings → Agents knobs in one read (R6 Step 1.5) — an ADDITIVE
     // sibling of PUT /api/config below; /api/health keeps its protected shape.
-    const configAnswer = (config) => ({
-        baseBranch: config.baseBranch ?? null,
-        defaultRunner: config.defaultRunner,
-        systemPrompt: config.systemPrompt ?? null,
-        defaultModels: config.defaultModels ?? {},
-        maxParallel: config.maxParallel,
-        memoryLimitMb: config.memoryLimitMb ?? null,
-        // Count-based worktree retention (#483): keep the last N finished worktrees
-        // on disk. 0 = unlimited. Always materialized (schema default 10).
-        worktreeRetention: config.worktreeRetention,
-        // Live title updates (task auto-naming spec): tri-state — null means "no
-        // config key, the CEZ_TITLE_UPDATES env default (ON) decides".
-        liveTitleUpdates: config.liveTitleUpdates ?? null,
-        // Optional review gate (#489): tri-state — null means "no config key, the
-        // CEZ_REVIEW_GATE env default (OFF) decides".
-        reviewGate: config.reviewGate ?? null,
-    });
-    api.get('/config', async (c) => c.json(configAnswer(await loadConfig(c.get('project').root))));
-    // Set/clear the agents' config knobs (Settings → Agents; the Repo tab's
-    // base-branch picker). Merges into the RAW config.json so user keys
-    // (skillsRepos…) survive and schema defaults are never materialized into
-    // the file. All fields optional + additive: `null` (and `''` for the
-    // R6 keys) clears a knob back to its default.
-    const modelPresetSchema = z.string().trim().max(200).nullable().optional();
-    const setConfigSchema = z.object({
-        baseBranch: z.string().trim().min(1).max(200).nullable().optional(),
-        defaultRunner: z.enum(['claude', 'codex', 'opencode']).optional(),
-        systemPrompt: z.string().trim().max(20_000, 'systemPrompt must be at most 20000 characters').nullable().optional(),
-        defaultModels: z
-            .object({
-            claude: modelPresetSchema,
-            codex: modelPresetSchema,
-            opencode: modelPresetSchema,
-        })
-            .optional(),
-        // Concurrency + memory guard (Settings → Resources). maxParallel clamps to
-        // the schema's 1–16; memoryLimitMb null/0 clears the ceiling.
-        maxParallel: z.number().int().min(1).max(16).optional(),
-        memoryLimitMb: z.number().int().min(0).max(1_048_576).nullable().optional(),
-        // Worktree retention count (Settings → Resources, #483). 0 = unlimited;
-        // null clears the key back to the schema default (10). Unlike memoryLimitMb,
-        // 0 is a meaningful value (unlimited), so it is stored, not treated as clear.
-        worktreeRetention: z.number().int().min(0).max(1000).nullable().optional(),
-        // Live title updates toggle (Settings → Agents): null clears the key back
-        // to the env-default behavior.
-        liveTitleUpdates: z.boolean().nullable().optional(),
-        // Optional review gate toggle (Settings → Agents, #489): null clears the key
-        // back to the env-default behavior (OFF).
-        reviewGate: z.boolean().nullable().optional(),
-    });
-    api.put('/config', async (c) => {
+    const configAnswer = async (repoRoot, config) => {
+        const nativeModels = await readAgentModelDefaults(repoRoot);
+        const modelsLocked = agentModelsLocked(repoRoot);
+        return {
+            baseBranch: config.baseBranch ?? null,
+            defaultRunner: config.defaultRunner,
+            systemPrompt: config.systemPrompt ?? null,
+            // Native defaults seed each runner independently. A Cezar preset remains
+            // selectable unless the operator opts into the fixed-model policy.
+            defaultModels: modelsLocked
+                ? nativeModels
+                : { ...nativeModels, ...(config.defaultModels ?? {}) },
+            modelsLocked,
+            maxParallel: config.maxParallel,
+            memoryLimitMb: config.memoryLimitMb ?? null,
+            // Count-based worktree retention (#483): keep the last N finished worktrees
+            // on disk. 0 = unlimited. Always materialized (schema default 10).
+            worktreeRetention: config.worktreeRetention,
+            // Live title updates (task auto-naming spec): tri-state — null means "no
+            // config key, the CEZ_TITLE_UPDATES env default (ON) decides".
+            liveTitleUpdates: config.liveTitleUpdates ?? null,
+            // Optional review gate (#489): tri-state — null means "no config key, the
+            // CEZ_REVIEW_GATE env default (OFF) decides".
+            reviewGate: config.reviewGate ?? null,
+        };
+    };
+    // ---- chained family: per-repo config (project-scoped) ----
+    const configRoutes = new Hono()
+        .get('/config', async (c) => {
+        const repoRoot = c.get('project').root;
+        return c.json(await configAnswer(repoRoot, await loadConfig(repoRoot)));
+    })
+        .put('/config', jsonZodValidator(() => setConfigSchema), async (c) => {
         const { root: repoRoot, dataDir } = c.get('project');
-        const parsed = setConfigSchema.safeParse(await c.req.json().catch(() => null));
-        if (!parsed.success) {
-            return c.json({ error: parsed.error.issues.map((i) => i.message).join('; ') }, 400);
+        const parsed = { data: c.req.valid('json') };
+        if (agentModelsLocked(repoRoot) && parsed.data.defaultModels !== undefined) {
+            return c.json({ error: AGENT_MODELS_LOCKED_ERROR }, 409);
         }
         const configPath = join(dataDir, 'config.json');
         let raw = {};
@@ -2905,16 +4578,56 @@ export function createApp(deps) {
             return c.json({ error: err instanceof Error ? err.message : String(err) }, 500);
         }
         // Pre-R6 answer shape ({baseBranch, defaultRunner}) + additive R6 fields.
-        return c.json(configAnswer(await loadConfig(repoRoot)));
+        return c.json(await configAnswer(repoRoot, await loadConfig(repoRoot)));
+    });
+    // Set/clear the agents' config knobs (Settings → Agents; the Repo tab's
+    // base-branch picker). Merges into the RAW config.json so user keys
+    // (skillsRepos…) survive and schema defaults are never materialized into
+    // the file. All fields optional + additive: `null` (and `''` for the
+    // R6 keys) clears a knob back to its default.
+    const modelPresetSchema = z.string().trim().max(200).nullable().optional();
+    const setConfigSchema = z.object({
+        baseBranch: z.string().trim().min(1).max(200).nullable().optional(),
+        defaultRunner: z.enum(RUNNER_IDS).optional(),
+        systemPrompt: z.string().trim().max(20_000, 'must be at most 20000 characters').nullable().optional(),
+        defaultModels: z
+            .object({
+            claude: modelPresetSchema,
+            codex: modelPresetSchema,
+            opencode: modelPresetSchema,
+            pi: modelPresetSchema,
+        })
+            .optional(),
+        // Concurrency + memory guard (Settings → Resources). maxParallel clamps to
+        // the schema's 1–16; memoryLimitMb null/0 clears the ceiling.
+        maxParallel: z.number().int().min(1).max(16).optional(),
+        memoryLimitMb: z.number().int().min(0).max(1_048_576).nullable().optional(),
+        // Worktree retention count (Settings → Resources, #483). 0 = unlimited;
+        // null clears the key back to the schema default (10). Unlike memoryLimitMb,
+        // 0 is a meaningful value (unlimited), so it is stored, not treated as clear.
+        worktreeRetention: z.number().int().min(0).max(1000).nullable().optional(),
+        // Live title updates toggle (Settings → Agents): null clears the key back
+        // to the env-default behavior.
+        liveTitleUpdates: z.boolean().nullable().optional(),
+        // Optional review gate toggle (Settings → Agents, #489): null clears the key
+        // back to the env-default behavior (OFF).
+        reviewGate: z.boolean().nullable().optional(),
+    });
+    const setAgentConfigSchema = z.object({
+        content: z.string().max(2_000_000),
+        version: z.string().nullable(),
     });
+    // ---- chained family: agent-config (project-scoped) -----------------------
     // Agent config is project-scoped (spec #404, adapted to the multi-project
     // route seam from #521): handlers resolve the selected repo through the
-    // same ProjectContext as every other mirrored route.
-    api.get('/agent-config', async (c) => {
+    // same ProjectContext as every other mirrored route. Chained (not statements)
+    // so `AppType` carries it — see `healthRoutes`.
+    const agentConfigRoutes = new Hono()
+        .get('/agent-config', async (c) => {
         const editable = capabilities().localHandoff;
         return c.json(await listAgentConfig(c.get('project').root, process.env, editable));
-    });
-    api.get('/agent-config/:id', async (c) => {
+    })
+        .get('/agent-config/:id', async (c) => {
         const id = c.req.param('id');
         const def = findConfigFile(id);
         if (!def)
@@ -2930,12 +4643,8 @@ export function createApp(deps) {
         if ('error' in read)
             return c.json({ error: read.error }, 500);
         return c.json(read);
-    });
-    const setAgentConfigSchema = z.object({
-        content: z.string().max(2_000_000),
-        version: z.string().nullable(),
-    });
-    api.put('/agent-config/:id', async (c) => {
+    })
+        .put('/agent-config/:id', jsonZodValidator(setAgentConfigSchema), async (c) => {
         // Config files may define hooks and MCP commands, so writes remain a
         // local-machine capability and are re-gated on every request.
         if (!capabilities().localHandoff) {
@@ -2943,10 +4652,7 @@ export function createApp(deps) {
                 error: 'editing agent config is disabled in hosted mode (CEZ_REMOTE) — edit it from the machine that owns the checkout',
             }, 409);
         }
-        const parsed = setAgentConfigSchema.safeParse(await c.req.json().catch(() => null));
-        if (!parsed.success) {
-            return c.json({ error: parsed.error.issues.map((issue) => issue.message).join('; ') }, 400);
-        }
+        const parsed = { data: c.req.valid('json') };
         const out = await writeConfigFile(c.req.param('id'), parsed.data.content, parsed.data.version, c.get('project').root);
         if (out === null)
             return c.json({ error: 'unknown config file' }, 404);
@@ -2954,55 +4660,6 @@ export function createApp(deps) {
             return c.json({ error: out.error }, out.status);
         return c.json(out.read);
     });
-    api.get('/repo/diff', async (c) => {
-        const { root: repoRoot } = c.get('project');
-        const info = await getRepoInfo(repoRoot);
-        if (!info)
-            return c.text('not a git repository');
-        return c.text(await getDiff(info.root));
-    });
-    // One commit's message + stat + patch — the Repo view expands it inline.
-    // `?structured=1` is the ADDITIVE sibling (R5 Step 1.7): the new repo view's commit-diff
-    // shape `{sha, subject, author, when, files, stat}` with 409 + reason on failure. The
-    // legacy text answer below is a protected surface (BACKWARD_COMPATIBILITY.md §2) — its
-    // shape, including the in-band failure sentences, stays exactly as it was.
-    api.get('/repo/commit/:sha', async (c) => {
-        const { root: repoRoot } = c.get('project');
-        const info = await getRepoInfo(repoRoot);
-        if (c.req.query('structured') === '1') {
-            if (!info)
-                return c.json({ error: 'not a git repository' }, 409);
-            const result = await collectCommitChanges(info.root, c.req.param('sha'));
-            if (!result.ok)
-                return c.json({ error: result.error }, 409);
-            return c.json(result.commit);
-        }
-        if (!info)
-            return c.text('not a git repository');
-        try {
-            return c.text(await getCommit(info.root, c.req.param('sha')));
-        }
-        catch (err) {
-            return c.text(`(git show failed: ${err instanceof Error ? err.message : String(err)})`);
-        }
-    });
-    // Structured sibling of the text-blob /api/repo/diff above (protected
-    // surface, untouched): the same {files, stat} shape the session /changes
-    // route serves, here for the MAIN working tree's uncommitted changes vs
-    // HEAD (redesign R5 Step 1.3 — §"Git/session API additions").
-    api.get('/repo/changes', async (c) => {
-        const { root: repoRoot } = c.get('project');
-        const info = await getRepoInfo(repoRoot);
-        if (!info)
-            return c.json({ error: 'not a git repository' }, 409);
-        // The user's REAL working tree — never stage into their index (a GET must not write).
-        const result = await collectChanges(info.root, 'HEAD', {
-            intentToAdd: false,
-        });
-        if (!result.ok)
-            return c.json({ error: result.error }, 409);
-        return c.json(result.changes);
-    });
     // Repo view branch actions: switch to an existing branch, or create one
     // (from `from` or HEAD) and switch. Predictable git failures — invalid
     // name, unknown `from`, dirty-tree checkout conflict — are 409 + reason.
@@ -3010,28 +4667,165 @@ export function createApp(deps) {
         name: z.string().trim().min(1).max(200),
         from: z.string().trim().min(1).max(200).optional(),
     });
-    api.post('/repo/branch', async (c) => {
-        const { root: repoRoot } = c.get('project');
-        const info = await getRepoInfo(repoRoot);
-        if (!info)
-            return c.json({ error: 'not a git repository' }, 409);
-        const parsed = repoBranchSchema.safeParse(await c.req.json().catch(() => null));
-        if (!parsed.success) {
-            return c.json({ error: parsed.error.issues.map((i) => i.message).join('; ') }, 400);
+    // ---- assemble the chained families --------------------------------------
+    // Every chained family is registered ONCE and mounted into the versioned table. There is no
+    // second, unversioned spelling: `/api/*` was removed once the whole API was reachable under
+    // `/api/v1` (BACKWARD_COMPATIBILITY.md §2). One surface means one thing to keep working, and
+    // it is the one the typed client describes.
+    //
+    // MOUNT ORDER IS REGISTRATION ORDER. Hono matches in the order routes were added, so each
+    // family keeps its internal order and the families keep theirs relative to each other.
+    //
+    // Written as ONE chained expression because that is the only shape Hono can infer route types
+    // from — it is what puts these routes in `AppType`, and so in the typed client.
+    const v1 = new Hono()
+        .use('*', resolveProjectScope)
+        .route('/', launchKeyRoutes)
+        .route('/', skillsRoutes)
+        .route('/', uiStateRoutes)
+        .route('/', workflowsRoutes)
+        .route('/', planRoutes)
+        .route('/', automationsRoutes)
+        .route('/', runsRoutes)
+        .route('/', groupsRoutes)
+        .route('/', openTargetsRoutes)
+        .route('/', worktreesRoutes)
+        .route('/', todosRoutes)
+        .route('/', sseRoutes)
+        .route('/', githubRoutes)
+        .route('/', repoRoutes)
+        .route('/', configRoutes)
+        .route('/', agentConfigRoutes);
+    // ---- chained family: the cross-project run index (workspace-level) -------
+    /**
+     * How many runs each project may contribute, newest first. The index is a FINDER, not a
+     * listing: past the newest couple of hundred per project you are looking for something the
+     * project's own Tasks table answers better, and every extra row is a DOM node the palette's
+     * filter walks on each keystroke. `truncated` names the projects this bit, so a consumer never
+     * has to pretend the list is complete.
+     */
+    const RUNS_INDEX_PER_PROJECT = 200;
+    /** `RunRecord` → the wire row. Optional keys are spread CONDITIONALLY: writing
+     *  `titleSummary: run.titleSummary` types a key as always-present that `JSON.stringify` then
+     *  drops when it is undefined, which is exactly the drift the parity guard fails on. */
+    const runIndexEntry = (projectId, run) => {
+        const usage = currentUsage(run.id);
+        return {
+            projectId,
+            id: run.id,
+            title: run.title,
+            ...(run.titleSummary !== undefined ? { titleSummary: run.titleSummary } : {}),
+            ...(run.titleOrigin !== undefined ? { titleOrigin: run.titleOrigin } : {}),
+            status: run.status,
+            ...(run.activity !== undefined ? { activity: run.activity } : {}),
+            createdAt: run.createdAt,
+            ...(run.finishedAt !== undefined ? { finishedAt: run.finishedAt } : {}),
+            ...(run.seenAt !== undefined ? { seenAt: run.seenAt } : {}),
+            archived: run.archived,
+            ...(run.autoResumeAt !== undefined ? { autoResumeAt: run.autoResumeAt } : {}),
+            workflow: run.workflow,
+            ...(run.branch !== undefined ? { branch: run.branch } : {}),
+            ...(run.startedAt !== undefined ? { startedAt: run.startedAt } : {}),
+            // The tracker-reference inputs, verbatim — the cockpit's `taskReference()` owns the rule
+            // that picks between them (see the schema's note).
+            ...(run.pullRequestUrl !== undefined ? { pullRequestUrl: run.pullRequestUrl } : {}),
+            ...(run.referencedPullRequestUrl !== undefined
+                ? { referencedPullRequestUrl: run.referencedPullRequestUrl }
+                : {}),
+            ...(run.prNumber !== undefined ? { prNumber: run.prNumber } : {}),
+            ...(run.issueNumber !== undefined ? { issueNumber: run.issueNumber } : {}),
+            ...(run.referencedIssueUrl !== undefined ? { referencedIssueUrl: run.referencedIssueUrl } : {}),
+            ...(run.markerRefs !== undefined ? { markerRefs: run.markerRefs } : {}),
+            ...(run.costUsd !== undefined ? { costUsd: run.costUsd } : {}),
+            ...(run.peakRssBytes !== undefined ? { peakRssBytes: run.peakRssBytes } : {}),
+            ...(run.peakProcCount !== undefined ? { peakProcCount: run.peakProcCount } : {}),
+            // The live sample, on the same terms as `GET /runs`: process-wide sampler, so a
+            // workspace-level answer can carry it for every project's runs at once.
+            ...(usage ? { usage } : {}),
+        };
+    };
+    /**
+     * `GET /workspace/runs-index` — every registered project's recent tasks in one slim answer, so
+     * ⌘K can find a task without knowing which project it lives in.
+     *
+     * Workspace-level and single-mount for the obvious reason: a project-scoped spelling of "all
+     * projects" is a contradiction. The per-project source is chosen the same way the automation
+     * coordinator's boot fan-out chooses it (`bootContext` for the boot project, `contexts.peek`
+     * for anything this process already owns, disk otherwise) — and never `contexts.context()`,
+     * which would build a context, prune worktrees and `recover()` running agents. Typing in a
+     * search box must not resume work; see `runs/run-index.ts`.
+     */
+    const runsIndexRoutes = new Hono()
+        .get('/workspace/runs-index', async (c) => {
+        let projects = [];
+        try {
+            const selector = capabilities().singleProject
+                ? { projectId: await resolveBootProject() }
+                : undefined;
+            projects = await listProjects(selector);
         }
-        const result = await createOrSwitchBranch(info.root, parsed.data.name, parsed.data.from);
-        if (!result.ok)
-            return c.json({ error: result.error }, 409);
-        return c.json({ branch: result.branch, created: result.created });
+        catch {
+            // unreadable workspace — an empty index, never a 500. The palette degrades to the
+            // active project's own run list, which it holds either way.
+        }
+        const bootId = await resolveBootProject(projects);
+        const runs = [];
+        const truncated = [];
+        for (const project of projects) {
+            // No folder, no runs to read. `not-git` still has an `.ai/cezar` worth indexing.
+            if (project.status === 'missing')
+                continue;
+            const owned = project.id === bootId ? bootContext : contexts.peek(project.id);
+            // `listRuns()` already sorts newest-first; the disk reader returns file order, so both
+            // paths get sorted below rather than trusting either.
+            //
+            // Archived runs are INCLUDED. The active project's rows reach the palette through
+            // `GET /runs`, which has always carried them, and excluding them here would mean a task
+            // is findable while you stand in its project and vanishes the moment you leave — the
+            // exact asymmetry a cross-project finder exists to remove.
+            const recent = (owned ? owned.store.listRuns() : readRunIndexFromDisk(join(project.root, '.ai/cezar'))).sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+            if (recent.length > RUNS_INDEX_PER_PROJECT)
+                truncated.push(project.id);
+            for (const run of recent.slice(0, RUNS_INDEX_PER_PROJECT)) {
+                runs.push(runIndexEntry(project.id, run));
+            }
+        }
+        runs.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+        const body = {
+            runs,
+            perProjectLimit: RUNS_INDEX_PER_PROJECT,
+            truncated,
+        };
+        return c.json(body);
     });
-    // ---- mount the mirrored table (multi-project spec, step 2.2) -------------
-    // Scoped first, then the legacy aliases. The paths are disjoint (no legacy
-    // route starts with `/p/`), so order between the two mounts never decides a
-    // match — but the catch-all below must still come last. `route()` re-registers
-    // the sub-app's routes under each prefix, handlers shared, internal order
-    // (e.g. `/runs/archive-finished` before `/runs/:id/archive`) preserved.
-    app.route(SCOPED_PREFIX, api);
-    app.route('/api', api);
+    // Workspace-level families answer for the whole workspace, so they are single-mount: never a
+    // project-scoped spelling, which would be a second surface to protect with no consumer.
+    const workspaceV1 = new Hono()
+        .route('/', healthRoutes)
+        .route('/', modelsRoutes)
+        .route('/', providersRoutes)
+        .route('/', projectsRoutes)
+        .route('/', agentProfilesRoutes)
+        .route('/', skillsUpdateRoutes)
+        .route('/', workspaceConfigRoutes)
+        .route('/', fsBrowseRoutes)
+        .route('/', automationChecksRoutes)
+        .route('/', runsIndexRoutes)
+        .route('/', workspaceEventsRoutes);
+    // ---- mount ---------------------------------------------------------------
+    // Scoped first, then the unscoped alias bound to the boot project. The paths are disjoint (no
+    // route starts with `/p/`), so order between the two never decides a match — but the SPA
+    // catch-all below must still come last. `route()` re-registers the sub-app's routes under
+    // each prefix, handlers shared, internal order preserved.
+    //
+    // Workspace families mount LAST and that is load-bearing: mounting the project table also
+    // mounts its `use('*')` scope resolver over the whole prefix, and Hono runs matched middleware
+    // in registration order. `/health` in particular answers for the workspace, has no project to
+    // resolve, and is the CORS-open discovery route — it must not sit behind the resolver.
+    const routed = app
+        .route(V1_SCOPED_PREFIX, v1)
+        .route(V1_PREFIX, v1)
+        .route(V1_PREFIX, workspaceV1);
     // ---- SPA catch-all -------------------------------------------------------
     // Last, so every route above still wins. Any other GET gets the cockpit shell:
     // react-router owns the route map, including the 404, so `/tasks/:id/changes`
@@ -3040,14 +4834,38 @@ export function createApp(deps) {
     // an unknown API path must never answer with HTML.
     // Without a web/dist build this serves the built-in build-hint page (dev-only
     // state — the published tarball ships web/dist), never a 404.
-    app.get('*', (c) => serveShell(c) ?? c.notFound());
-    return app;
+    routed.get('*', (c) => serveShell(c) ?? c.notFound());
+    return routed;
 }
 export function startServer(deps, port) {
+    const workspaceEvents = deps.workspaceEvents ?? new WorkspaceEventBus();
+    const skillsUpdate = deps.skillsUpdate ?? new SkillsUpdateService({ invalidateCatalog: refreshTeamSkills });
     // The subscription hub rides the same HTTP server (one port, zero config):
     // createApp registers the topics, the `upgrade` hook below owns the socket.
     const socketHub = deps.socketHub ?? createSocketHub();
-    const app = createApp({ ...deps, socketHub });
+    const automationCoordinator = new AutomationCoordinator({ listProjects });
+    const bootProjectId = deps.bootProjectId ?? 'default';
+    const bootAutomationStore = automationCoordinator.store(bootProjectId, deps.repoRoot);
+    const sharedContexts = deps.contexts ?? new ProjectContexts({
+        listProjects,
+        semaphore: deps.semaphore,
+        automationStore: (projectId, root) => automationCoordinator.store(projectId, root),
+    });
+    // #801: GitHub automations are opt-in. Off, the flag must remove the BEHAVIOR and not merely
+    // the UI — no scheduler, no GitHub polling, no launched runs — so every entry point into the
+    // workspace scheduler below is gated on it. Read per call rather than captured, for the same
+    // reason `capabilities()` is inside `createApp`: tests flip the variable between apps.
+    const automationsEnabled = () => resolveCapabilities(process.env, deps.bindHost).automations;
+    let rescheduleAutomations = () => { };
+    const app = createApp({
+        ...deps,
+        contexts: sharedContexts,
+        automationStore: bootAutomationStore,
+        workspaceEvents,
+        skillsUpdate,
+        socketHub,
+        automationsChanged: () => rescheduleAutomations(),
+    });
     // SECURITY: default to loopback. This server executes agents locally and its endpoints are
     // same-origin-trusted (only /api/health is CORS-open); binding to a non-loopback host would
     // expose an agent-executing box to the network. `bindHost` exists only for a deliberate
@@ -3058,13 +4876,101 @@ export function startServer(deps, port) {
         port,
         hostname: deps.bindHost ?? '127.0.0.1',
     });
+    const coordinator = new SkillsUpdateCoordinator(skillsUpdate, async () => effectiveSkillsAutoUpdate(await loadWorkspaceConfig()));
+    const automationProjects = new Map();
+    const automationScheduler = new WorkspaceAutomationScheduler({
+        coordinator: automationCoordinator,
+        handle: (projectId, store) => {
+            const project = automationProjects.get(projectId);
+            if (!project)
+                return undefined;
+            return {
+                projectId,
+                owner: project.owner,
+                repo: project.repo,
+                store,
+                poller: new GithubPoller(),
+                onChange: (automationId, revision) => workspaceEvents.emit('automation-change', { project: projectId, automationId, revision }),
+                launch: async (definition, candidate, receiptId) => {
+                    const bootId = deps.bootProjectId ?? 'default';
+                    const context = projectId === bootId
+                        ? { root: deps.repoRoot, manager: deps.manager, store: deps.store }
+                        : await sharedContexts.context(projectId);
+                    return launchAutomationRun({
+                        root: context.root,
+                        manager: context.manager,
+                        store: context.store,
+                        definition,
+                        candidate,
+                        receiptId,
+                    });
+                },
+            };
+        },
+    });
+    // The scheduler is inert until `start()` anyway (it constructs `stopped`), but the gate is
+    // stated here rather than inherited from that detail: a definition saved while the flag is off
+    // must not even ask the coordinator to refresh.
+    rescheduleAutomations = () => {
+        if (!automationsEnabled())
+            return;
+        void automationScheduler.reschedule();
+    };
+    const unsubscribe = workspaceEvents.on((event, data) => {
+        if (event === 'project-added') {
+            const project = data.project;
+            if (project && typeof project.id === 'string' && typeof project.root === 'string' && project.status !== 'missing') {
+                coordinator.add(project.id, project.root);
+                void getRepoInfo(project.root).then((info) => {
+                    const parsed = parseRemote(info?.remote ?? '');
+                    if (parsed?.host === 'github.com')
+                        automationProjects.set(project.id, { root: project.root, owner: parsed.owner, repo: parsed.repo });
+                    return rescheduleAutomations();
+                });
+            }
+        }
+        else if (event === 'project-removed') {
+            const id = data.id;
+            if (typeof id === 'string')
+                coordinator.remove(id);
+            if (typeof id === 'string') {
+                automationCoordinator.remove(id);
+                automationProjects.delete(id);
+                rescheduleAutomations();
+            }
+        }
+    });
+    server.once('listening', () => {
+        void listProjects().then((projects) => {
+            const all = projects.some((project) => project.root === deps.repoRoot)
+                ? projects : [{ id: deps.bootProjectId ?? 'default', root: deps.repoRoot, status: 'ok' }, ...projects];
+            coordinator.start(all);
+            // #801: with automations off there is nothing to warm — no remote to resolve, no receipts
+            // to reconcile, and above all no scheduler to start. The skills-update coordinator above is
+            // a separate feature and starts either way.
+            if (!automationsEnabled())
+                return;
+            void Promise.all(all.map(async (project) => {
+                const parsed = parseRemote((await getRepoInfo(project.root))?.remote ?? '');
+                if (parsed?.host === 'github.com')
+                    automationProjects.set(project.id, { root: project.root, owner: parsed.owner, repo: parsed.repo });
+                const automationStore = automationCoordinator.store(project.id, project.root);
+                const runStore = project.id === (deps.bootProjectId ?? 'default')
+                    ? deps.store
+                    : sharedContexts.peek(project.id)?.store;
+                if (automationStore && runStore)
+                    reconcileAutomationReceipts(automationStore, runStore);
+            })).then(() => automationScheduler.start()).catch(() => undefined);
+        }).catch(() => undefined);
+    });
+    server.once('close', () => { unsubscribe(); coordinator.stop(); automationScheduler.stop(); });
     socketHub.attach(server, (req) => verifyWsUpgrade(req, deps.bindHost));
     return server;
 }
 /**
  * The WebSocket twin of the `/api/*` request-origin guard (#426), applied
- * before the `/api/ws` handshake. WebSocket is NOT subject to CORS — any web
- * page may open `ws://127.0.0.1:<port>/api/ws` and, unlike a forced HTTP GET,
+ * before the `/api/v1/ws` handshake. WebSocket is NOT subject to CORS — any web
+ * page may open `ws://127.0.0.1:<port>/api/v1/ws` and, unlike a forced HTTP GET,
  * would get to READ what comes back — so this guard is load-bearing:
  *
  *   1. Host allowlist (local mode): a non-loopback Host is a DNS-rebound
@@ -3213,6 +5119,8 @@ export function resumeCommand(runner, sessionId) {
             return `codex resume ${sessionId}`;
         case 'opencode':
             return `opencode --session ${sessionId}`;
+        case 'pi':
+            return `pi --session ${sessionId}`;
         default:
             return `claude --resume ${sessionId}`;
     }