@qodeca/xezar 0.13.0 → 0.14.0

package/dist/server/server.js

@@ -17,7 +17,7 @@ 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 { jsonZodValidator, optionalJsonZodValidator, paramZodValidator, queryZodValidator } from './validators.js';
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
 import { z } from 'zod';
 import { setWorkspaceUiStateInputSchema, } from '../contract/index.js';
@@ -36,6 +36,8 @@ import { applyProviderEnablement } from '../core/provider-availability.js';
 import { RunnerModelCatalog } from '../core/runner-model-catalog.js';
 import { currentUsage, onUsage } from '../core/process-usage.js';
 import { projectWorkflowsDir, loadWorkflows } from '../workflows/load.js';
+import { reportProjectChange } from '../mcp/project-catalogs.js';
+import { projectLeader } from '../mcp/project-leaders.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';
@@ -46,10 +48,15 @@ import { markStarted, onTodosChanged, readTodos, removeTodo, todoTaskText } from
 import { HistoryCursorError, deriveRunContextEvents, readEventsAfterLiveCursor, readRunHistoryPage, validateLiveCursor, } from '../runs/event-history.js';
 import { readRunIndexFromDisk } from '../runs/run-index.js';
 import { isV2WireEventType } from '../runs/ui-event-sink.js';
-import { runEventsQuerySchema, runHistoryQuerySchema, runIdParamSchema, } from '../contract/index.js';
+import { mcpLeaderActionInputSchema } from '../contract/index.js';
+import { githubPrReadyInputSchema, runEventsQuerySchema, runHistoryQuerySchema, runIdParamSchema, } from '../contract/index.js';
+// The run-mutation request shapes, each carrying the optional stale-write guard (#250).
+import { archiveRunInputSchema, continueRunInputSchema, gitCommitInputSchema, messageInputSchema, patchRunInputSchema, pickVariantInputSchema, pinRunInputSchema, queuedMessagePatchInputSchema, runVersionGuardInputSchema, } from '../contract/index.js';
+import { ownGroup, ownershipScope } from '../mcp/resource-ownership.js';
+import { runVersion, staleRunWrite } from '../mcp/stale-write.js';
 import { toPastedContent } from '../workflows/run.js';
 import { removeWorktree, worktreeDiff, worktreeDiffStat, worktreeSizeBytes } from '../git-worktree.js';
-import { isReclaimable, reclaimWorktrees } from '../runs/retention.js';
+import { isReclaimable, ownRunAndWorktree, reclaimWorktrees } from '../runs/retention.js';
 import { getBranches, getCommit, getDiff, getLog, getRepoInfo, getStatus } from './git.js';
 import { collectChanges, collectCommitChanges, collectRunCommits, commitAll, createOrSwitchBranch, imageMimeType, isOsOpenableImage, pushCurrentBranch, readWorktreePath, } from './git-changes.js';
 import { gatedSkillsRepos, loadConfig, resolveWorktreeRetention } from '../config.js';
@@ -61,7 +68,7 @@ import { listConfigFiles } from '../agent-config/catalog.js';
 import { readAccountIdentity } from '../agent-config/account-identity.js';
 import { DEFAULT_MEMORY_LIMIT_MB, PROJECT_ID_RE, defaultWorkspaceConfig, effectiveSkillsAutoUpdate, loadWorkspaceConfig, mergeWriteWorkspaceConfig, effectiveComposerDefault, } from '../workspace/config.js';
 import { CONTROL_CHARS_RE, DEFAULT_AGENT_ACCOUNT_ID, defaultAgentAccountStore, isAbsoluteConfigDir, loadAgentAccounts, mergeWriteAgentAccounts, } from '../workspace/agent-accounts.js';
-import { defaultAgentProfile, listAgentProfiles, profileDirState, resolveProfileEnvForRoot, resolveStoredProfile, sameProfileDir, } from '../workspace/agent-profiles.js';
+import { accountHomePatch, defaultAgentProfile, listAgentProfiles, profileDirState, resolveProfileEnvForRoot, resolveStoredProfile, sameProfileDir, } from '../workspace/agent-profiles.js';
 import { PROFILE_CAPABLE_PROVIDERS, profileEnv, supportsProfiles } from '../core/agent-profiles.js';
 import { withEnvPrefix } from '../core/shell-env.js';
 import { allocateProjectSlug, listProjects, normalizeProjectTags, probeProjectStatus, registerProject, removeProject, shouldRegisterProject, } from '../workspace/projects.js';
@@ -218,6 +225,46 @@ export function projectRouteManifest(app) {
 const FOLLOWUPS_OFF = 'the follow-up inbox is disabled — set XEZ_FOLLOWUPS=1 to enable it';
 /** 409 body for every automations route while GitHub automations are off (#801). */
 const AUTOMATIONS_OFF = 'GitHub automations are disabled — set XEZ_AUTOMATIONS=1 to enable them';
+/**
+ * How long `DELETE /projects/:id` waits on either of its project-lifecycle promises — a context
+ * still opening, then the removed context's last background writes — before answering anyway
+ * (#200). One bound per wait, applied through `withinTeardownBound`.
+ *
+ * `RunManager.dispose()` deliberately carries NO deadline — an invented one there would only
+ * move an ENOTEMPTY a few hundred milliseconds later, which is the right call for a teardown
+ * helper whose caller is about to delete the directory. An HTTP request is the opposite case:
+ * it must answer. The realistic tail is short (the 409 above already refused the removal if any
+ * run is active, and a retention sweep stops after its current iteration), but that iteration
+ * is `git worktree remove --force` + `rm -rf` + `git worktree prune`, and `git()` in
+ * `git-worktree.ts` passes no `timeout` to `execFile` — so a git blocked on `index.lock` or a
+ * stalled network mount would hang the request with no response and no recovery.
+ *
+ * Deliberately bounded HERE and not by giving `git()` a timeout: the same helper runs
+ * `git worktree add` and `git fetch`, which are legitimately slow on a large repository, so a
+ * blanket timeout would turn a slow clone into a failed run. What the bound gives up is only
+ * the tail of the guarantee: the registry entry is already gone and the context is already out
+ * of the map, so the answer stays true — a sweep that outlives it can still stamp a record, the
+ * pre-#200 behaviour, and only for a project no route can reach.
+ */
+const PROJECT_TEARDOWN_WAIT_MS = 5_000;
+/**
+ * Wait for one of `DELETE /projects/:id`'s two project-lifecycle promises — the in-flight build
+ * before the running-tasks guard, the teardown after the removal — and answer anyway once
+ * `PROJECT_TEARDOWN_WAIT_MS` is up.
+ *
+ * One helper for both because the reason is the same one, and because two hand-rolled races in
+ * one handler drift: neither wait may turn a request into something that cannot answer. Both
+ * outcomes are swallowed deliberately — the route's answer does not depend on how either promise
+ * settled, and a build that lost its project rejects by design.
+ */
+async function withinTeardownBound(work) {
+    await Promise.race([
+        work.then(() => undefined, () => undefined),
+        new Promise((resolve) => {
+            setTimeout(resolve, PROJECT_TEARDOWN_WAIT_MS).unref?.();
+        }),
+    ]);
+}
 /**
  * The in-process bus for workspace-level SSE events. The registry-mutating
  * routes (`POST /api/projects` — step 4.2, emits `project-added` for a
@@ -307,9 +354,6 @@ const startRunSchema = z
     .refine((b) => Boolean(b.workflow) !== Boolean(b.steps), {
     message: 'provide either "workflow" or "steps", not both',
 });
-const pickSchema = z.object({
-    runId: z.string().min(1),
-});
 const planSchema = z.object({
     // Same bound as `startRunSchema.task` — this flows into `planChain` (#429).
     task: z.string().trim().min(1).max(100_000, 'must be at most 100000 characters'),
@@ -439,16 +483,6 @@ const uiStateSchema = z
     dismissedSkillsBanner: z.boolean().optional(),
 })
     .passthrough();
-// Editable titles (#389), and the initial prompt while the run is still queued
-// (#472 — rejected with 409 on any other status by the handler).
-const patchRunSchema = z.object({
-    title: z.string().trim().min(1).max(300).optional(),
-    task: z.string().trim().min(1).max(100_000).optional(),
-});
-// Session commit (redesign R5 — §"Git/session API additions").
-const gitCommitSchema = z.object({
-    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
 // "open in default app" action for images. Containment is re-checked server-side via
@@ -458,27 +492,6 @@ const openInSchema = z.object({
     target: z.string().trim().min(1, 'target required').max(200),
     path: z.string().max(1_000).optional(),
 });
-// Attachment-carrying bodies validate with the CONTRACT's `attachmentInputSchema` (#950) —
-// images plus the short PDF/TXT/MD allowlist, ~5 MB each once base64-decoded. Imported rather
-// than mirrored here, so the wire cannot drift from what the cockpit compiles against.
-const messageSchema = z
-    .object({
-    text: z.string().max(100_000).default(''),
-    images: z.array(attachmentInputSchema).max(4).default([]),
-})
-    .refine((m) => m.text.trim().length > 0 || m.images.length > 0, {
-    message: 'message needs text or at least one attachment',
-});
-// PATCH semantics are load-bearing here: an omitted field keeps its current value.
-// In particular, the cockpit edits text without re-uploading existing attachments.
-const queuedMessagePatchSchema = z
-    .object({
-    text: z.string().max(100_000).optional(),
-    images: z.array(attachmentInputSchema).max(4).optional(),
-})
-    .refine((m) => m.text !== undefined || m.images !== undefined, {
-    message: 'message edit needs text or attachments',
-});
 // Queued prompt stack bounds (#472). The per-message bounds mirror `messageSchema`
 // above; the one that actually matters is the FOLDED total, because 20 messages of
 // 100 000 chars each would otherwise compose a ~2 M-character {{task}}.
@@ -495,21 +508,6 @@ function foldedLength(task, stack) {
         .filter((part) => part.length > 0)
         .join('\n\n').length;
 }
-// "Continue"/"Send back" body (spec 003 / #401): every field optional, so an empty POST reopens
-// the last session on the run's current backend (backward compat). A runner/model/account override
-// lets the follow-up composer choose which engine handles the continuation. `text` stays bounded
-// like the live-session message `text` (#429), and `images` like a live-session message's — the
-// 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, 'must be at most 100000 characters').optional(),
-    images: z.array(attachmentInputSchema).max(4).optional(),
-    runner: z.enum(RUNNER_IDS).optional(),
-    model: z.string().max(200).optional(),
-    /** Agent account for the reopened session (spec 2026-07-29-agent-profiles). Bound mirrors
-     *  `POST /runs`' own `agentProfile`. Omitted = keep the account the run is already on. */
-    agentProfile: z.string().max(64).optional(),
-});
 // Inbox "▶ Run" body (spec 007 / #401 / #413): every field optional, and the whole body is
 // optional too, so an empty POST — every client before the pills and the composer — starts on
 // the host's `defaultRunner` with no extra instructions, exactly as before. This is a START
@@ -529,17 +527,6 @@ const startTodoSchema = z
         .transform((s) => (s ? s : undefined)),
 })
     .optional();
-// `POST /api/runs/:id/archive` (#429) — no body archives; `{archived:false}`
-// un-archives. A tiny schema so the route follows the safeParse convention.
-const archiveSchema = z.object({
-    archived: z.boolean().optional(),
-});
-// `POST /api/v1/runs/:id/pin` (#935) — no body pins; `{pinned:false}` unpins. The archive
-// route's shape, deliberately: it is the same kind of per-task flag, and a second spelling for
-// "absent means do the thing" would be one more rule for a client to remember.
-const pinSchema = z.object({
-    pinned: z.boolean().optional(),
-});
 // Request-body size guards (#429). A generous global cap keeps a single
 // localhost request from being unbounded (the largest legit body is 4 pasted
 // images at ~7 MB base64 each); the ui-state PUT gets a much tighter cap since
@@ -1453,14 +1440,14 @@ export function createApp(deps) {
      * `AgentHomePaths` whose slot for this provider is the account's dir. That is what makes a second
      * login's `settings.json` the file you open rather than the default account's, and it keeps the
      * ids opaque and stable so the open route below never takes a path from the client.
+     *
+     * WHICH slot comes from `accountHomePatch`, shared with `defaultAgentProfile`'s read of the same
+     * table. This was a run of conditional spreads that named three providers and silently did
+     * nothing for the fourth, so a pi account would have resolved its files in the default pi home
+     * (#329). It never surfaced only because `CONFIG_FILES` carries no pi entry yet.
      */
     const accountFiles = async (profile) => {
-        const home = {
-            ...agentHomePaths(),
-            ...(profile.provider === 'claude' ? { claude: profile.path } : {}),
-            ...(profile.provider === 'codex' ? { codex: profile.path } : {}),
-            ...(profile.provider === 'opencode' ? { opencodeConfig: profile.path } : {}),
-        };
+        const home = { ...agentHomePaths(), ...accountHomePatch(profile.provider, profile.path) };
         const defs = listConfigFiles().filter((def) => def.scope === 'user' && def.runners.includes(profile.provider));
         return Promise.all(defs.map(async (def) => {
             const path = def.resolve(bootRoot, home);
@@ -1985,6 +1972,16 @@ export function createApp(deps) {
                 error: `xezar is serving ${entry.name} right now — it re-registers itself at every start, so it cannot be removed from here`,
             }, 409);
         }
+        // A project whose context is still BUILDING is not a project with no runs: its store opens
+        // with `keepLive` and `manager.recover()` re-queues or resumes every live-looking row, so
+        // the guard below — which reads the already-built context only — would count zero for a
+        // project that is at this moment bringing agents back, and remove it out from under them.
+        // Let the build finish, then count. Bounded for the same reason the teardown below is: a
+        // build that outlives the bound leaves the pre-existing answer (nothing built, zero runs)
+        // rather than a project that can never be removed.
+        const opening = contexts.pending(id);
+        if (opening)
+            await withinTeardownBound(opening);
         const active = activeRunCount(id);
         if (active > 0) {
             return c.json({
@@ -2006,7 +2003,27 @@ export function createApp(deps) {
             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);
+        //
+        // AWAITED (#200): the manager's promise is what settles the background writes it could not
+        // stop synchronously — a worktree-retention sweep spawning git and stamping records. Not
+        // awaiting it let the response go out while a sweep was still writing into the removed
+        // project's `.local/xezar`, and a re-add inside that window could see the stale in-memory
+        // index overwrite the fresh one. There is no run to wait for: the 409 above already refused
+        // the removal if this process owns any.
+        //
+        // BOUNDED, because this is a request and not a teardown helper: `dispose()` has no deadline
+        // by design and the git it waits on has no `execFile` timeout, so an unbounded await is a
+        // request that can never answer. `dispose()` removed the context from the map
+        // synchronously, so the floated remainder is invisible to every route; see
+        // `PROJECT_TEARDOWN_WAIT_MS`. The answer is the same however it settles — the removal has
+        // already happened, and this is only the wait for the last writes.
+        //
+        // Covers a context that was still BUILDING when the removal landed, too: `dispose()` ends
+        // the registration first, so that build tears itself down instead of publishing, and the
+        // promise awaited here is the one that settles its store and manager. The answer stays
+        // `{ removed: true }` — the registry entry is gone, which is what the caller asked for, and
+        // the racing build was never a context anyone could reach.
+        await withinTeardownBound(contexts.dispose(id));
         workspaceEvents.emit('project-removed', { id });
         const body = { removed: true, id };
         return c.json(body);
@@ -2279,6 +2296,12 @@ export function createApp(deps) {
      * rejected for the same reason as the `rm` above: `RunStore.open` creates
      * directories, and a stale `running` row left by a crashed process would
      * become a 409 the user could never clear.
+     *
+     * "No context, no agent to strand" holds for a project nobody has touched. It does NOT hold for
+     * a project whose context is being built RIGHT NOW — that build opened its store with
+     * `keepLive` and its `manager.recover()` re-queues or resumes exactly the runs this guard
+     * exists to protect — so the caller waits for an in-flight build (`contexts.pending`) before
+     * asking, and only then is zero an answer about the project rather than about the map.
      */
     const activeRunCount = (projectId) => {
         const ctx = contexts.peek(projectId);
@@ -2726,6 +2749,8 @@ export function createApp(deps) {
             const message = err instanceof Error ? err.message : String(err);
             return c.json({ error: message }, 500);
         }
+        // E-05 (#252): the project leader hears of it. No catalog for this project → no row.
+        reportProjectChange(c.get('project').id, (catalog) => catalog.workflowChanged({ name: parsed.data.name, change: 'saved' }));
         return c.json({ path, name: parsed.data.name }, 201);
     })
         // Delete a saved workflow (spec 012 follow-up): file workflows only —
@@ -2751,6 +2776,7 @@ export function createApp(deps) {
         catch (err) {
             return c.json({ error: err instanceof Error ? err.message : String(err) }, 500);
         }
+        reportProjectChange(c.get('project').id, (catalog) => catalog.workflowChanged({ name, change: 'deleted' }));
         return c.json({ ok: true, path: target });
     })
         // Import support for the builder (spec 012): parse + validate a pasted
@@ -3072,6 +3098,17 @@ export function createApp(deps) {
             console.warn(`[xezar] could not mark inbox entry ${todoId} started: ${String(err)}`);
         }
     };
+    // A run whose recorded worktree is this project's own (#316). `worktreePath` is data: a copied or
+    // hand-edited `.local/xezar` can name another project's worktree, and the delete, remove-worktree,
+    // commit, push, PR, diff and changes routes would `rm -rf`, commit, push or run `git add -N .`
+    // there. They look the run up through the same rule the variant pick and reclaim use (#288). An
+    // id this project does not hold is still the plain 404. A record it DOES hold whose worktree is
+    // elsewhere gets `FOREIGN_WORKTREE` instead: the cockpit shows the server's words as they are,
+    // and a bare "not found" on a row the user can see would leave them with no way forward. The
+    // sentence names no path, id or project, so it says nothing of the folder it refuses to touch,
+    // and it is short because a toast is on screen for five seconds (`TOAST_MS` in the cockpit).
+    const ownedRun = (project, id) => ownRunAndWorktree(ownershipScope(project), id);
+    const FOREIGN_WORKTREE = "This task's worktree is outside this project, so xezar will not touch it from here. Archive the task to hide it from your list.";
     // ---- chained family: runs lifecycle + artifacts (project-scoped) ----
     const runsRoutes = new Hono()
         .get('/runs', (c) => c.json(c.get('project').store.listRuns().map(withUsage)))
@@ -3081,7 +3118,7 @@ export function createApp(deps) {
         // 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) => {
+        .post('/runs/:id/archive', jsonZodValidator(archiveRunInputSchema, { 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
@@ -3090,6 +3127,13 @@ export function createApp(deps) {
         // `setArchived` itself — the bulk sweep must obey it too (spec
         // 2026-08-03-auto-resume-after-usage-limit).
         const parsed = { data: c.req.valid('json') };
+        // An unknown run is a 404 before any version is compared — the answer it always got.
+        if (!store.getRun(id))
+            return c.json({ error: 'not found' }, 404);
+        // The stale-write guard (#250): checked in the same synchronous stretch as the write.
+        const stale = staleRunWrite(store, id, parsed.data.expectedVersion);
+        if (stale)
+            return c.json(stale, 409);
         const run = store.setArchived(id, parsed.data.archived !== false);
         return run ? c.json(run) : c.json({ error: 'not found' }, 404);
     })
@@ -3097,19 +3141,32 @@ export function createApp(deps) {
         // twin in every respect: an absent body pins (the common case), the answer is the updated
         // record, and the change rides the existing `run` SSE because `setPinned` touches. No new
         // event and no new response shape.
-        .post('/runs/:id/pin', jsonZodValidator(pinSchema, { absent: ({}) }), (c) => {
+        .post('/runs/:id/pin', jsonZodValidator(pinRunInputSchema, { absent: ({}) }), (c) => {
         const { store } = c.get('project');
-        const run = store.setPinned(c.req.param('id'), c.req.valid('json').pinned !== false);
+        const id = c.req.param('id');
+        const { pinned, expectedVersion } = c.req.valid('json');
+        // An unknown run is a 404 before any version is compared — the answer it always got.
+        if (!store.getRun(id))
+            return c.json({ error: 'not found' }, 404);
+        // The stale-write guard (#250): checked in the same synchronous stretch as the write.
+        const stale = staleRunWrite(store, id, expectedVersion);
+        if (stale)
+            return c.json(stale, 409);
+        const run = store.setPinned(id, pinned !== false);
         return run ? c.json(run) : c.json({ error: 'not found' }, 404);
     })
         // The per-task off switch for that resume (the workspace setting is Settings → Resources).
         // Idempotent: a run with nothing pending answers 200 too, because "this task will not
         // resume itself" is equally true either way.
-        .delete('/runs/:id/auto-resume', (c) => {
+        .delete('/runs/:id/auto-resume', optionalJsonZodValidator(runVersionGuardInputSchema, { absent: ({}) }), (c) => {
         const { store, manager } = c.get('project');
         const id = c.req.param('id');
         if (!store.getRun(id))
             return c.json({ error: 'not found' }, 404);
+        // The stale-write guard (#250): checked in the same synchronous stretch as the write.
+        const stale = staleRunWrite(store, id, c.req.valid('json').expectedVersion);
+        if (stale)
+            return c.json(stale, 409);
         manager.cancelAutoResume(id);
         return c.json({ cancelled: true });
     })
@@ -3207,6 +3264,15 @@ export function createApp(deps) {
         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);
+    })
+        // The run's stale-write token (#250, D-06 § 4.2) — what a caller echoes back as
+        // `expectedVersion` on a run mutation. Its own route rather than a field of the record above,
+        // so the cockpit's reads neither change shape nor pay for it (it scans the run's event file).
+        // A reader that wants both reads THIS first: an older token costs a spurious rejection at
+        // worst, while a token newer than the record it read would let a stale write through.
+        .get('/runs/:id/version', (c) => {
+        const version = runVersion(c.get('project').store, c.req.param('id'));
+        return version === undefined ? c.json({ error: 'not found' }, 404) : c.json({ version });
     })
         .get('/runs/:id/history', paramZodValidator(runIdParamSchema), queryZodValidator(runHistoryQuerySchema), async (c) => {
         const { store, dataDir } = c.get('project');
@@ -3244,12 +3310,17 @@ export function createApp(deps) {
         // 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) => {
+        .patch('/runs/:id', jsonZodValidator(patchRunInputSchema), 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 = { data: c.req.valid('json') };
+        // The stale-write guard (#250). Everything from here to the writes below is synchronous, so
+        // the check and both writes run in one stretch.
+        const stale = staleRunWrite(store, id, parsed.data.expectedVersion);
+        if (stale)
+            return c.json(stale, 409);
         // 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.
@@ -3275,17 +3346,21 @@ export function createApp(deps) {
         }
         return c.json(store.getRun(id));
     })
-        .post('/runs/:id/cancel', (c) => {
+        .post('/runs/:id/cancel', optionalJsonZodValidator(runVersionGuardInputSchema, { absent: ({}) }), (c) => {
         const { store, manager } = c.get('project');
         const id = c.req.param('id');
         if (!store.getRun(id))
             return c.json({ error: 'not found' }, 404);
+        // The stale-write guard (#250): checked in the same synchronous stretch as the write.
+        const stale = staleRunWrite(store, id, c.req.valid('json').expectedVersion);
+        if (stale)
+            return c.json(stale, 409);
         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.
-        .post('/runs/:id/messages', jsonZodValidator(messageSchema), async (c) => {
+        .post('/runs/:id/messages', jsonZodValidator(messageInputSchema), async (c) => {
         const { store, manager } = c.get('project');
         const id = c.req.param('id');
         const run = store.getRun(id);
@@ -3302,6 +3377,11 @@ export function createApp(deps) {
             if (blocked)
                 return c.json({ error: blocked }, 409);
         }
+        // The stale-write guard (#250), after the last `await`: from here through the delivery
+        // ladder every step is synchronous, so the check and the delivery run in one stretch.
+        const stale = staleRunWrite(store, id, parsed.data.expectedVersion);
+        if (stale)
+            return c.json(stale, 409);
         const content = [
             ...parsed.data.images.map(toPastedContent),
             ...(parsed.data.text.trim() ? [{ type: 'text', text: parsed.data.text }] : []),
@@ -3344,7 +3424,7 @@ export function createApp(deps) {
     })
         // 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) => {
+        .patch('/runs/:id/queued-messages/:msgId', jsonZodValidator(queuedMessagePatchInputSchema), async (c) => {
         const { store, manager } = c.get('project');
         const id = c.req.param('id');
         const run = store.getRun(id);
@@ -3372,6 +3452,10 @@ export function createApp(deps) {
                 error: `prompt too long — ${MAX_FOLDED_TASK_CHARS} character limit across the task and its queued messages (would be ${prospective})`,
             }, 400);
         }
+        // The stale-write guard (#250): checked in the same synchronous stretch as the write.
+        const stale = staleRunWrite(store, id, parsed.data.expectedVersion);
+        if (stale)
+            return c.json(stale, 409);
         const images = parsed.data.images?.map(toPastedContent);
         const message = manager.editQueuedMessage(id, msgId, {
             ...(parsed.data.text !== undefined ? { text: parsed.data.text } : {}),
@@ -3381,7 +3465,7 @@ export function createApp(deps) {
             return c.json({ error: 'run already started' }, 409);
         return c.json({ message });
     })
-        .delete('/runs/:id/queued-messages/:msgId', (c) => {
+        .delete('/runs/:id/queued-messages/:msgId', optionalJsonZodValidator(runVersionGuardInputSchema, { absent: ({}) }), (c) => {
         const { store, manager } = c.get('project');
         const id = c.req.param('id');
         const run = store.getRun(id);
@@ -3391,23 +3475,31 @@ export function createApp(deps) {
         if (!(run.queuedMessages ?? []).some((m) => m.id === msgId)) {
             return c.json({ error: 'not found' }, 404);
         }
+        // The stale-write guard (#250): checked in the same synchronous stretch as the write.
+        const stale = staleRunWrite(store, id, c.req.valid('json').expectedVersion);
+        if (stale)
+            return c.json(stale, 409);
         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.
-        .post('/runs/:id/finish', (c) => {
+        .post('/runs/:id/finish', optionalJsonZodValidator(runVersionGuardInputSchema, { absent: ({}) }), (c) => {
         const { store, manager } = c.get('project');
         const id = c.req.param('id');
         if (!store.getRun(id))
             return c.json({ error: 'not found' }, 404);
+        // The stale-write guard (#250): checked in the same synchronous stretch as the write.
+        const stale = staleRunWrite(store, id, c.req.valid('json').expectedVersion);
+        if (stale)
+            return c.json(stale, 409);
         const finished = manager.finish(id);
         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.
-        .post('/runs/:id/continue', jsonZodValidator(continueSchema, { absent: ({}) }), async (c) => {
+        .post('/runs/:id/continue', jsonZodValidator(continueRunInputSchema, { absent: ({}) }), async (c) => {
         const { root: repoRoot, store, manager } = c.get('project');
         const id = c.req.param('id');
         const run = store.getRun(id);
@@ -3432,6 +3524,11 @@ export function createApp(deps) {
             if ('error' in account)
                 return c.json({ error: account.error }, 400);
         }
+        // The stale-write guard (#250), after the last `await`, so the check and the reopen run in
+        // one synchronous stretch.
+        const stale = staleRunWrite(store, id, parsed.data.expectedVersion);
+        if (stale)
+            return c.json(stale, 409);
         const result = manager.continueRun(id, {
             text: parsed.data.text,
             images: parsed.data.images?.map(toPastedContent),
@@ -3635,20 +3732,25 @@ export function createApp(deps) {
     })
         // 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)
-            return c.json({ error: 'not found' }, 404);
+        const run = await ownedRun(c.get('project'), c.req.param('id'));
+        if (!run) {
+            return c.get('project').store.getRun(c.req.param('id'))
+                ? c.json({ error: FOREIGN_WORKTREE }, 409)
+                : c.json({ error: 'not found' }, 404);
+        }
         if (!run.worktreePath || !existsSync(run.worktreePath)) {
             return c.text('(no worktree — this task ran directly in the repo working tree)');
         }
         return c.text(await worktreeDiff(run.worktreePath, run.baseBranch ?? 'HEAD'));
     })
         .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 { root: repoRoot } = c.get('project');
+        const run = await ownedRun(c.get('project'), c.req.param('id'));
+        if (!run) {
+            return c.get('project').store.getRun(c.req.param('id'))
+                ? c.json({ error: FOREIGN_WORKTREE }, 409)
+                : c.json({ error: 'not found' }, 404);
+        }
         const workingDirectory = workingDirectoryOf(run, repoRoot);
         if (!workingDirectory)
             return c.json({ error: NO_WORKTREE }, 409);
@@ -3760,28 +3862,36 @@ export function createApp(deps) {
             ...(result.content !== undefined ? { content: result.content } : {}),
         });
     })
-        .post('/runs/:id/git/commit', jsonZodValidator(gitCommitSchema), async (c) => {
+        .post('/runs/:id/git/commit', jsonZodValidator(gitCommitInputSchema), async (c) => {
         const { store } = c.get('project');
-        const run = store.getRun(c.req.param('id'));
+        const run = await ownedRun(c.get('project'), c.req.param('id'));
         if (!run)
-            return c.json({ error: 'not found' }, 404);
+            return store.getRun(c.req.param('id')) ? c.json({ error: FOREIGN_WORKTREE }, 409) : c.json({ error: 'not found' }, 404);
         const worktree = worktreeOf(run);
         if (!worktree)
             return c.json({ error: NO_WORKTREE }, 409);
         const parsed = { data: c.req.valid('json') };
+        // The stale-write guard (#250), right before the (async) effect starts.
+        const stale = staleRunWrite(store, run.id, parsed.data.expectedVersion);
+        if (stale)
+            return c.json(stale, 409);
         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 });
     })
-        .post('/runs/:id/git/push', async (c) => {
+        .post('/runs/:id/git/push', optionalJsonZodValidator(runVersionGuardInputSchema, { absent: ({}) }), async (c) => {
         const { root: repoRoot, store } = c.get('project');
-        const run = store.getRun(c.req.param('id'));
+        const run = await ownedRun(c.get('project'), c.req.param('id'));
         if (!run)
-            return c.json({ error: 'not found' }, 404);
+            return store.getRun(c.req.param('id')) ? c.json({ error: FOREIGN_WORKTREE }, 409) : c.json({ error: 'not found' }, 404);
         const worktree = worktreeOf(run);
         if (!worktree)
             return c.json({ error: NO_WORKTREE }, 409);
+        // The stale-write guard (#250), right before the (async) effect starts.
+        const stale = staleRunWrite(store, run.id, c.req.valid('json').expectedVersion);
+        if (stale)
+            return c.json(stale, 409);
         const result = await pushCurrentBranch(worktree);
         if (!result.ok)
             return c.json({ error: result.error }, 409);
@@ -3803,12 +3913,12 @@ export function createApp(deps) {
         // `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. XEZ_DRY_RUN=1 fakes the URL (no push, no gh).
-        .post('/runs/:id/pr', async (c) => {
+        .post('/runs/:id/pr', optionalJsonZodValidator(runVersionGuardInputSchema, { absent: ({}) }), async (c) => {
         const { root: repoRoot, dataDir, store, manager } = c.get('project');
         const id = c.req.param('id');
-        const run = store.getRun(id);
+        const run = await ownedRun(c.get('project'), id);
         if (!run)
-            return c.json({ error: 'not found' }, 404);
+            return store.getRun(id) ? c.json({ error: FOREIGN_WORKTREE }, 409) : c.json({ error: 'not found' }, 404);
         if (manager.isActive(id))
             return c.json({ error: 'run is still active — wait for the review gate' }, 409);
         if (!run.worktreePath || !existsSync(run.worktreePath) || !run.branch) {
@@ -3816,6 +3926,10 @@ export function createApp(deps) {
                 error: 'no worktree/branch to publish — this task ran in the repo working tree',
             }, 400);
         }
+        // The stale-write guard (#250), right before the (async) effect starts.
+        const stale = staleRunWrite(store, id, c.req.valid('json').expectedVersion);
+        if (stale)
+            return c.json(stale, 409);
         const outcome = await createDraftPr({
             repoRoot,
             run,
@@ -3843,43 +3957,56 @@ export function createApp(deps) {
     })
         // Archived tasks keep their worktree for inspection; this is the explicit
         // "🧹 Remove worktree" cleanup (spec 006).
-        .post('/runs/:id/remove-worktree', async (c) => {
+        .post('/runs/:id/remove-worktree', optionalJsonZodValidator(runVersionGuardInputSchema, { absent: ({}) }), async (c) => {
         const { root: repoRoot, store, manager } = c.get('project');
         const id = c.req.param('id');
-        const run = store.getRun(id);
+        const run = await ownedRun(c.get('project'), id);
         if (!run)
-            return c.json({ error: 'not found' }, 404);
+            return store.getRun(id) ? c.json({ error: FOREIGN_WORKTREE }, 409) : c.json({ error: 'not found' }, 404);
         if (manager.isActive(id))
             return c.json({ error: 'run is active — cancel it first' }, 409);
+        // The stale-write guard (#250), right before the (async) effect starts.
+        const stale = staleRunWrite(store, id, c.req.valid('json').expectedVersion);
+        if (stale)
+            return c.json(stale, 409);
         if (run.worktreePath)
             await removeWorktree(repoRoot, run.worktreePath, run.branch);
         store.updateRun(id, { worktreePath: undefined, branch: undefined });
         return c.json({ removed: true });
     })
-        .delete('/runs/:id', async (c) => {
+        .delete('/runs/:id', optionalJsonZodValidator(runVersionGuardInputSchema, { absent: ({}) }), async (c) => {
         const { root: repoRoot, store, manager } = c.get('project');
         const id = c.req.param('id');
         if (manager.isActive(id))
             return c.json({ error: 'run is active — cancel it first' }, 409);
-        const run = store.getRun(id);
+        const run = await ownedRun(c.get('project'), id);
         if (!run)
-            return c.json({ error: 'not found' }, 404);
+            return store.getRun(id) ? c.json({ error: FOREIGN_WORKTREE }, 409) : c.json({ error: 'not found' }, 404);
+        // The stale-write guard (#250), right before the (async) effect starts.
+        const stale = staleRunWrite(store, id, c.req.valid('json').expectedVersion);
+        if (stale)
+            return c.json(stale, 409);
         // Delete cleans up after itself: worktree + branch go with the run (spec 006).
         if (run.worktreePath)
             await removeWorktree(repoRoot, run.worktreePath, run.branch);
         return store.deleteRun(id) ? c.json({ deleted: true }) : c.json({ error: 'not found' }, 404);
     });
     // ---- parallel variants (spec 010) -----------------------------------------
-    const groupRuns = (store, groupId) => store
-        .listRuns()
-        .filter((r) => r.groupId === groupId)
-        .sort((a, b) => (a.variant ?? '').localeCompare(b.variant ?? ''));
+    // A group's members, in variant order — but only when EVERY member is this project's (#288).
+    // A member's `worktreePath` is data: a copied or hand-edited `.local/xezar` can name another
+    // project's worktree, and the read runs git inside each member's path while the pick deletes the
+    // losers'. `ownGroup` refuses such a group whole, exactly as it does for MCP (M-07), and the
+    // refusal is the same 404 an unknown group gets, so it names nothing of the other project.
+    const ownedGroupRuns = async (project, groupId) => {
+        const owned = await ownGroup(ownershipScope(project), groupId);
+        return owned.ok ? owned.value.runs : null;
+    };
     // ---- 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)
+        const { dataDir } = c.get('project');
+        const runs = await ownedGroupRuns(c.get('project'), c.req.param('groupId'));
+        if (!runs)
             return c.json({ error: 'not found' }, 404);
         const detailed = await Promise.all(runs.map(async (r) => ({
             id: r.id,
@@ -3904,10 +4031,10 @@ export function createApp(deps) {
         // "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) => {
+        .post('/groups/:groupId/pick', jsonZodValidator(pickVariantInputSchema), async (c) => {
         const { root: repoRoot, dataDir, store, manager } = c.get('project');
-        const runs = groupRuns(store, c.req.param('groupId'));
-        if (runs.length === 0)
+        const runs = await ownedGroupRuns(c.get('project'), c.req.param('groupId'));
+        if (!runs)
             return c.json({ error: 'not found' }, 404);
         const parsed = { data: c.req.valid('json') };
         const winner = runs.find((r) => r.id === parsed.data.runId);
@@ -3921,16 +4048,22 @@ export function createApp(deps) {
         // (#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.
+        let toReview = false;
         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' });
-            }
-        }
+            toReview = diff.trim().length > 0 && !diff.startsWith('(diff failed');
+        }
+        // The stale-write guard (#250, #271) on the kept variant, after the reads above and right
+        // before the first effect: the losers' worktrees and branches are deleted below, for good.
+        const stale = staleRunWrite(store, winner.id, parsed.data.expectedVersion);
+        if (stale)
+            return c.json(stale, 409);
+        if (toReview)
+            store.updateRun(winner.id, { status: 'review' });
         const losers = runs.filter((r) => r.id !== winner.id);
         store.appendEvent(winner.id, {
             type: 'lifecycle',
@@ -4524,6 +4657,25 @@ export function createApp(deps) {
             ...(result.code ? { code: result.code } : {}),
             ...(result.current ? { current: result.current } : {}),
         }, result.status);
+    })
+        // Mark a draft pull request ready for review (#262). No cockpit control yet: the leader's
+        // `handoff_git ready` is the caller. The forge re-reads the pull request and refuses a moved head.
+        .post('/github/prs/:number/ready', paramZodValidator(mergeNumberParams, { message: 'invalid pull request number' }), jsonZodValidator(githubPrReadyInputSchema, { message: 'invalid ready request' }), async (c) => {
+        const { root: repoRoot } = c.get('project');
+        const { number } = c.req.valid('param');
+        const forge = resolveForge(await getRepoInfo(repoRoot));
+        if (!forge?.markReady)
+            return c.json({ error: 'GitHub ready-for-review is unavailable' }, 409);
+        const result = await forge.markReady(number, c.req.valid('json'));
+        if (result.ready) {
+            forgetRefStatus(repoRoot, number);
+            return c.json({ ready: true, number: result.number, url: result.url });
+        }
+        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
@@ -4708,6 +4860,8 @@ export function createApp(deps) {
         catch {
             // missing or malformed — start fresh
         }
+        // What the file held before, per key — so E-05 names only the keys this write really changed.
+        const before = new Map(Object.entries(raw).map(([key, value]) => [key, JSON.stringify(value)]));
         if (parsed.data.baseBranch !== undefined) {
             if (parsed.data.baseBranch === null)
                 delete raw.baseBranch;
@@ -4808,6 +4962,10 @@ export function createApp(deps) {
         // B2 exists to fix.
         if (parsed.data.memoryLimitMb !== undefined)
             await deps.semaphore?.refresh();
+        // E-05 (#252): key NAMES only, never values. A write that changed nothing reports nothing.
+        const changed = [...new Set([...before.keys(), ...Object.keys(raw)])].filter((key) => before.get(key) !== (key in raw ? JSON.stringify(raw[key]) : undefined));
+        if (changed.length > 0)
+            reportProjectChange(c.get('project').id, (catalog) => catalog.configChanged({ keys: changed }));
         // Pre-R6 answer shape ({baseBranch, defaultRunner}) + additive R6 fields.
         return c.json(await configAnswer(repoRoot, await loadConfig(repoRoot)));
     });
@@ -4902,8 +5060,53 @@ export function createApp(deps) {
             return c.json({ error: 'unknown config file' }, 404);
         if (!out.ok)
             return c.json({ error: out.error }, out.status);
+        // E-05 (#252), after the hosted-mode 409 above and never before it: a refused write is no change.
+        reportProjectChange(c.get('project').id, (catalog) => catalog.agentConfigChanged({ id: c.req.param('id') }));
         return c.json(out.read);
     });
+    // ---- chained family: the MCP API reference (project-scoped, read-only) ----
+    // #284, spec `mcp-api-reference-spec.md` § 11. The tool registry is loaded LAZILY, as
+    // `startMcpSocket` loads the service, so the cockpit's static import graph never includes it
+    // and a broken MCP module answers `{available: false, reason}` instead of breaking the app.
+    // It does NOT need the MCP service: the listing is static code, and this page is most needed
+    // on a machine where MCP did not start (N-07). The list is fixed for the life of the process
+    // (`listChanged: false`), so the answer is built once. A GET with no side effect — and there
+    // is deliberately no route that runs a tool from here (spec § 13).
+    let mcpReference;
+    const readMcpReference = () => (mcpReference ??= import('../mcp/api-reference.js')
+        .then((m) => m.buildMcpApiReference(version))
+        .catch((err) => {
+        const message = err instanceof Error ? err.message : String(err);
+        console.warn(`[xez] MCP API reference unavailable (${message}) — the cockpit works without it`);
+        return { available: false, reason: `The MCP tool list could not be loaded: ${message}` };
+    }));
+    const mcpReferenceRoutes = new Hono().get('/mcp/reference', async (c) => c.json(await readMcpReference()));
+    // ---- chained family: the MCP leader's push-delivery path (project-scoped) ----
+    // #309. Delivery itself is on by default and needs no route: every MCP session that owns the
+    // project gets an event controller when it opens. The route reads that state, and lets the person
+    // point xezar at the leader they run — `attach` an OpenCode `serve` session — or detach it. xezar
+    // starts no agent process (owner decision on #311); there is no `start` or `resume`. It runs no
+    // tool, so the cockpit never becomes a second leader (spec `mcp-api-reference-spec.md` § 13).
+    // Attaching makes this process talk to a local server by URL: a local-machine capability, so
+    // hosted mode refuses it like every other local mutator.
+    const mcpLeaderStatus = (projectId) => projectLeader(projectId)?.status() ?? {
+        available: false,
+        reason: 'The MCP service is not running for this project, so there is no event delivery to report.',
+    };
+    const mcpLeaderRoutes = new Hono()
+        .get('/mcp/leader', (c) => c.json(mcpLeaderStatus(c.get('project').id)))
+        .post('/mcp/leader', jsonZodValidator(() => mcpLeaderActionInputSchema), async (c) => {
+        if (!capabilities().localHandoff) {
+            return c.json({ error: 'a leader session is attached from the machine that owns the checkout (this cockpit runs in hosted mode)' }, 409);
+        }
+        const port = projectLeader(c.get('project').id);
+        if (!port)
+            return c.json({ error: 'the MCP service is not running for this project' }, 409);
+        const out = await port.act(c.req.valid('json'));
+        if (!out.ok)
+            return c.json({ error: out.error }, 409);
+        return c.json(out.status);
+    });
     // 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.
@@ -4939,7 +5142,9 @@ export function createApp(deps) {
         .route('/', githubRoutes)
         .route('/', repoRoutes)
         .route('/', configRoutes)
-        .route('/', agentConfigRoutes);
+        .route('/', agentConfigRoutes)
+        .route('/', mcpReferenceRoutes)
+        .route('/', mcpLeaderRoutes);
     // ---- chained family: the cross-project run index (workspace-level) -------
     /**
      * How many runs each project may contribute, newest first. The index is a FINDER, not a
@@ -5209,6 +5414,7 @@ export function startServer(deps, port) {
         socketHub,
         automationsChanged: () => rescheduleAutomations(),
     });
+    deps.onApp?.(app);
     // 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