@open-mercato/cezar 0.9.1 → 0.9.2

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,16 +13,20 @@ 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 { detectEnvironment } from '../core/backend-detect.js';
 import { discoverCodexModels } from '../core/codex-model-catalog.js';
+import { PROVIDER_IDS, ProviderAuthService, } 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';
@@ -28,7 +39,7 @@ import { gatedSkillsRepos, loadConfig, resolveWorktreeRetention } from '../confi
 import { findConfigFile } from '../agent-config/catalog.js';
 import { readConfigFile, writeConfigFile } from '../agent-config/files.js';
 import { listAgentConfig } from '../agent-config/service.js';
-import { PROJECT_ID_RE, defaultWorkspaceConfig, loadWorkspaceConfig, mergeWriteWorkspaceConfig, } from '../workspace/config.js';
+import { PROJECT_ID_RE, defaultWorkspaceConfig, effectiveSkillsAutoUpdate, loadWorkspaceConfig, mergeWriteWorkspaceConfig, effectiveComposerDefault, } from '../workspace/config.js';
 import { allocateProjectSlug, listProjects, probeProjectStatus, registerProject, removeProject, shouldRegisterProject, } from '../workspace/projects.js';
 import { mergeWriteWorkspaceUiState, readWorkspaceUiState } from '../workspace/ui-state.js';
 import { checkoutRepo } from './checkout.js';
@@ -39,34 +50,92 @@ import { 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),
+}).strict();
+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;
@@ -81,10 +150,11 @@ const FOLLOWUPS_OFF = 'the follow-up inbox is disabled — set CEZ_FOLLOWUPS=1 t
  * 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,7 +190,7 @@ 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(),
@@ -128,7 +198,7 @@ const startRunSchema = z
     // 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 +215,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 +233,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 +243,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 +253,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,14 +276,32 @@ 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(),
 });
+const providerAuthDismissalsSchema = z
+    .object({
+    claude: z.string().min(1).max(128).optional(),
+    codex: z.string().min(1).max(128).optional(),
+    opencode: z.string().min(1).max(128).optional(),
+})
+    .strict();
 /** 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
@@ -223,6 +311,16 @@ const workspaceUiStateSchema = z
     .object({
     appearance: appearanceSchema.optional(),
     notifications: z.object({ enabled: z.boolean().optional() }).passthrough().optional(),
+    dismissedProviderAuthFailures: providerAuthDismissalsSchema.optional(),
+    lastLocation: z
+        .object({
+        projectId: z.string().min(1).max(64),
+        pathname: z.string().min(1).max(2048).startsWith('/p/'),
+        search: z.string().max(4096).startsWith('?').optional(),
+        hash: z.string().max(2048).startsWith('#').optional(),
+    })
+        .strict()
+        .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.
@@ -330,7 +428,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,7 +485,7 @@ 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(),
     model: z.string().max(200).optional(),
@@ -406,7 +504,7 @@ const startTodoSchema = z
     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 +530,100 @@ 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 workspaceUiStateBody = workspaceUiStateSchema.superRefine(capUiStateKeys);
+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 { data: parsed.data };
+    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 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 +646,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
@@ -481,6 +662,21 @@ export function createApp(deps) {
     const modelCatalog = deps.modelCatalog ?? new RunnerModelCatalog({
         adapters: { codex: { discover: () => discoverCodexModels({ cwd: bootRoot }) } },
     });
+    const providerAuth = deps.providerAuth ?? new ProviderAuthService();
+    const workspaceConfig = deps.workspaceConfig ?? {
+        load: loadWorkspaceConfig,
+        mergeWrite: mergeWriteWorkspaceConfig,
+    };
+    const providerStatus = async (options) => {
+        const [discovered, workspace] = await Promise.all([
+            providerAuth.status(options?.refresh ? { refresh: true } : undefined),
+            workspaceConfig.load(),
+        ]);
+        return applyProviderEnablement(discovered, workspace.disabledProviders);
+    };
+    const providerActionError = async (required) => unavailableProviderMessage(required, await providerStatus());
+    const openTerminal = deps.openTerminal ?? openInTerminal;
+    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 +747,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 +764,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 +793,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 +816,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 +831,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 +880,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 +914,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 +977,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 +993,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 +1016,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 +1112,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 +1150,85 @@ 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);
+    // ---- chained family: host model catalog (workspace-level) ----
+    const modelsRoutes = new Hono()
+        .get('/models', queryZodValidator(z.object({ runner: z.union([z.string(), z.array(z.string()).transform((v) => v[0])]).pipe(z.literal('codex')) }), { message: 'runner must be codex' }), async (c) => {
+        const query = { data: c.req.valid('query') };
         return c.json(await modelCatalog.get(query.data.runner));
     });
+    // ---- 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, or opencode' }), async (c) => {
+        const body = { data: c.req.valid('json') };
+        const provider = body.data.provider;
+        const command = providerAuth.loginCommand(provider);
+        const row = (await providerAuth.status({ refresh: true })).providers.find((candidate) => candidate.provider === provider);
+        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 {
+            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 });
+    });
     // ---- 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 +1254,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,6 +1275,164 @@ export function createApp(deps) {
             projectsDir,
         };
         return c.json(body);
+    })
+        .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 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);
+        }
+        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);
+    })
+        .patch('/projects/:projectId', jsonZodValidator(() => updateProjectSchema), 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 } = 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
+                // 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);
+        }
+        // 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
@@ -1079,13 +1554,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,64 +1588,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);
+        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}` };
         }
-        let removed;
+        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 {
-            removed = await removeProject(id);
+            return c.json(await skillsUpdateResponse(await skillsUpdate.update(resolved.root, true)));
         }
-        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);
+        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;
         }
-        // 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.
@@ -1190,67 +1653,6 @@ export function createApp(deps) {
     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;
-        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);
-        }
-        // 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
     // register the result through `registerFolder` above (same guards, same
@@ -1267,41 +1669,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 +1678,32 @@ 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,
             memoryLimitMb: config.resources.memoryLimitMb,
             worktreeRetentionDefault: config.resources.worktreeRetentionDefault,
         },
     });
-    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 } = parsed.data;
         for (const [configuredRoot, create] of [
             [browseRoot, false],
             [projectsDir, true],
@@ -1376,8 +1742,28 @@ 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?.memoryLimitMb !== undefined)
                     config.resources.memoryLimitMb = resources.memoryLimitMb;
                 if (resources?.worktreeRetentionDefault !== undefined) {
@@ -1394,15 +1780,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(workspaceUiStateBody), async (c) => {
+        const parsed = { data: c.req.valid('json') };
         try {
             return c.json(await mergeWriteWorkspaceUiState((state) => ({
                 ...state,
@@ -1414,67 +1804,103 @@ 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(),
+            memoryLimitMb: z.number().int().min(0).max(1_048_576).nullable().optional(),
+            worktreeRetentionDefault: z.number().int().min(0).max(1000).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 +1911,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) => {
+    // ---- 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');
-        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) => {
-        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 +1954,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 +1979,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 +2003,250 @@ 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();
+    // ---- 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()
+        .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()
+        .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,28 +2275,33 @@ 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);
-        }
+        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) => {
+    })
+        .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', 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') };
         let workflow;
         if (parsed.data.steps) {
             // Inline chain (spec 008): an approved plan runs as an ad-hoc workflow.
@@ -1665,6 +2320,10 @@ 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);
         const images = parsed.data.images?.map((img) => ({
             type: 'image',
             source: { type: 'base64', media_type: img.mediaType, data: img.data },
@@ -1706,113 +2365,24 @@ export function createApp(deps) {
         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`,
-            });
-        }
-        return c.json({
-            winner: store.getRun(winner.id),
-        });
-    });
-    api.get('/runs/:id', (c) => {
+    })
+        .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) => {
+    })
+        // 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 +2407,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 +2449,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 +2464,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 +2477,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 +2519,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 +2533,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 +2544,20 @@ 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) => {
+    })
+        // "Continue" (spec 003): reopen a finished run's session in-process.
+        .post('/runs/:id/continue', jsonZodValidator(continueSchema, { absent: ({}) }), 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);
         // 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') };
+        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 +2570,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);
@@ -2013,6 +2589,9 @@ export function createApp(deps) {
         const sessionId = [...run.steps].reverse().find((s) => s.sessionId)?.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).
@@ -2026,12 +2605,9 @@ export function createApp(deps) {
             }, 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 +2620,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
@@ -2105,6 +2678,9 @@ 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;
             // An id resumeCommand refuses (#431) degrades to a fresh CLI in the worktree,
@@ -2124,10 +2700,10 @@ export function createApp(deps) {
         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 +2711,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 +2728,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 +2739,111 @@ 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,
+            // 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 +2853,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 +2862,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 +2885,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 +2921,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 +2936,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 +2950,116 @@ 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() : [] }));
+    // 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,61 +3080,66 @@ 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 (todo.startedTaskId)
             return c.json({ error: 'already started' }, 409);
         let task = todoTaskText(todo);
@@ -2476,6 +3168,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,
@@ -2484,10 +3180,9 @@ 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) => {
+    // ---- chained family: SSE streams (project-scoped) ----
+    const sseRoutes = new Hono()
+        .get('/runs/:id/events', (c) => {
         const { store } = c.get('project');
         const id = c.req.param('id');
         if (!store.getRun(id))
@@ -2543,13 +3238,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 +3290,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 +3364,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 +3394,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 +3420,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,6 +3523,75 @@ 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.
@@ -2782,45 +3612,12 @@ export function createApp(deps) {
         // 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) => {
+    // ---- chained family: per-repo config (project-scoped) ----
+    const configRoutes = new Hono()
+        .get('/config', async (c) => c.json(configAnswer(await loadConfig(c.get('project').root))))
+        .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') };
         const configPath = join(dataDir, 'config.json');
         let raw = {};
         try {
@@ -2907,14 +3704,53 @@ export function createApp(deps) {
         // Pre-R6 answer shape ({baseBranch, defaultRunner}) + additive R6 fields.
         return c.json(configAnswer(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(['claude', 'codex', 'opencode']).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,
+        })
+            .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 +3766,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 +3775,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 +3783,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 +3790,61 @@ 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);
-        }
-        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 });
-    });
-    // ---- 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);
+    // ---- 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);
+    // 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('/', skillsUpdateRoutes)
+        .route('/', workspaceConfigRoutes)
+        .route('/', fsBrowseRoutes)
+        .route('/', automationChecksRoutes)
+        .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 +3853,33 @@ 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),
+    });
+    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 +3890,89 @@ 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,
+                    });
+                },
+            };
+        },
+    });
+    rescheduleAutomations = () => { 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 automationScheduler.reschedule();
+                });
+            }
+        }
+        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);
+                void automationScheduler.reschedule();
+            }
+        }
+    });
+    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);
+            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