tinybeeai 0.0.0-stage → 0.16.1

package/dist/api.js

@@ -0,0 +1,1047 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import webpush from 'web-push';
+import { config, log } from './config.js';
+import { SANDBOX_BANNER } from './sandbox.js';
+import { count, createWatch, findOne, get, insert, list, remove, update } from './db.js';
+import { liveClientOpened, publish, subscribe } from './events.js';
+import { trackDeviceStream } from './phone/pairing.js';
+import { approverOf, roleOf } from './phone/auth.js';
+import { ingest } from './webhooks.js';
+import { answerChat } from './agent/chat.js';
+import { refreshStoredBlocks } from './agent/triage.js';
+import { llmBackend, STAGE_MODEL_IDS } from './agent/llm.js';
+import { getReport } from './reports/index.js';
+import { approvalExpired, approveAction, rejectAction, RetryingError } from './agent/rules.js';
+import { withTargetTitles } from './approval-targets.js';
+import { approvalStats, closeApproval, liveCount, pendingPrs, reconcileThrottled, sweepTimeExpired } from './agent/approvals.js';
+import { githubFor } from './integrations/github.js';
+import { tidyTrackerScope, trackerScopeError } from './integrations/github-issues.js';
+import { effectiveReviewOptions, parseReviewPatch } from './routes/review.js';
+import { testSavingsError } from './flows/testSavings.js';
+import { prTestTargetError } from './flows/prTarget.js';
+import { testRepoSwitchError } from './flows/testRepo.js';
+import { nightlyError, tidyNightly } from './nightly.js';
+import { settleNightlySave } from './nightly-scheduler.js';
+import { cleanCopyFiles, cleanDeployEnvironment, cleanDeploySec, cleanPassEnv, cleanTestBranches, DEPLOY_ADMIN_MESSAGE, deployAdminChanges, deployWaitError, REPO_ADMIN_CODE, REPO_ADMIN_MESSAGE, RUNNER_ADMIN_CODE, RUNNER_ADMIN_MESSAGE, runnerAdminChanges, testBranchesError, validateRunner, } from './runner/command.js';
+import { releaseDeployWaits } from './deploy-wait.js';
+import { ensureReposForSave } from './repos-github.js';
+import { archiveDot, deleteDot, nameMatches, parseRemoveMode, restoreDot, deletePreview } from './dot-remove.js';
+import { deliveryOf, webhookRoute } from './delivery.js';
+import { scopeUnreadOf } from './pr-scope.js';
+import { pollFailureFor } from './monitor/pollers.js';
+import { getWorkspaceRepo, repoAdminChanges, repoAsRun, repoDeployChanges, repoDeployWaitError, repoId, repoMirror, resolveRepoFields, watchRepos, } from './repos.js';
+import { runSummary } from './review/run-summary.js';
+import { hasEvidencePack } from './evidence-pack.js';
+import { runStage, STAGE_KEYS } from './stages/index.js';
+import { derivedStages, mergeStages, NO_STAGE_OFFER, resetWatcherNotes, stagesError, stagesNoticeError } from './stages/config.js';
+import { VERSION, commitSha } from './version.js';
+import { hiveMode } from './hive/embed.js';
+import { tinybeeHealth } from './bee/status.js';
+import { changedRuleKinds, endShadowWeek, forgetShadowKinds, parseShadowDays, startShadowWeek } from './shadow-week.js';
+import { capOf, capState, modelCapError, usageOf } from './model-usage.js';
+import { foundByLine, sourcesOf } from './lead-defects.js';
+import { forgetLeadIndex, leadError, leadOf, leadStages, memberChanges, onlyMemberRefusal } from './lead.js';
+import { releaseModelCapHolds } from './model-cap.js';
+import { afterTrueSyncSave, mergeTrueSync, TRUE_ADMIN_CODE, TRUE_ADMIN_MESSAGE, trueSyncAdminChanges, trueSyncError } from './true/settings.js';
+import { trueKeyView } from './true/key.js';
+// Dot status
+const ATTENTION_OUTCOMES = new Set(['product_failure', 'test_failure', 'environment_failure', 'needs_attention']);
+/** A simulated or real outage run keeps the dot red this long unless a recovery run follows. */
+const OUTAGE_HOLD_MS = 30 * 60_000;
+function latestRuns(watchId, n = 10) {
+    return list('runs', { watchId }, { orderBy: 'id DESC', limit: n });
+}
+/** paused > outage > running > attention > ok. Derived from probe_state, the latest runs, and pending approvals. */
+export function dotStatus(w) {
+    if (w.paused)
+        return 'paused';
+    const probes = list('probe_state', { watchId: w.id });
+    const probeDown = probes.some((s) => s.down === true ||
+        s.status === 'down' ||
+        (s.consecutiveFailures ?? 0) >= 3 ||
+        (typeof s.indicator === 'string' && s.indicator !== 'none' && s.indicator !== ''));
+    if (probeDown)
+        return 'outage';
+    const runs = latestRuns(w.id);
+    if (runs.some((r) => r.status === 'running'))
+        return 'running';
+    const lastIncident = runs.find((r) => r.kind === 'outage' || r.kind === 'recovery');
+    if (lastIncident?.kind === 'outage' && Date.now() - Date.parse(lastIncident.createdAt) < OUTAGE_HOLD_MS && lastIncident.verdict?.outcome !== 'pass')
+        return 'outage';
+    // A dot whose GitHub polling keeps failing hears nothing, so it is not all good (KAT-363).
+    if (liveCount(w.id) > 0 || pollFailureFor(w))
+        return 'attention';
+    // Health comes from runs that test the product. A ticket review after a failed merge used to turn
+    // the dot green while main was still broken (KAT-74, seen while recording the demo).
+    // A run that stopped because no model answered (KAT-102) concluded nothing about the product either way.
+    // A run that waits for the dot's daily model cap (KAT-362), or for the deploy of its merge (KAT-368), concluded nothing either.
+    const last = runs.find((r) => r.kind !== 'digest' &&
+        r.kind !== 'recovery' &&
+        r.kind !== 'ticket_review' &&
+        r.interruptReason !== 'model_unavailable' &&
+        r.interruptReason !== 'model_cap' &&
+        r.interruptReason !== 'deploy_wait');
+    if (last && (last.status === 'failed' || last.status === 'interrupted'))
+        return 'attention';
+    if (last?.verdict && ATTENTION_OUTCOMES.has(last.verdict.outcome))
+        return 'attention';
+    return 'ok';
+}
+function dotRepos(w) {
+    const repos = watchRepos(w);
+    if (!repos.length)
+        return [];
+    const last = new Map();
+    for (const e of list('events', { watchId: w.id, source: 'github' }, { orderBy: 'id DESC', limit: 100 })) {
+        const r = e.trigger?.repo;
+        if (!r?.owner || !r.name)
+            continue;
+        const id = repoId(r.owner, r.name);
+        if (!last.has(id))
+            last.set(id, e.createdAt);
+    }
+    return repos.map((r) => {
+        const ws = getWorkspaceRepo(r.id);
+        return {
+            repo: r.id,
+            role: r.role,
+            owner: r.owner,
+            name: r.name,
+            defaultBranch: r.defaultBranch,
+            ...(r.pathFilters ? { pathFilters: r.pathFilters } : {}),
+            ...(r.prScope ? { prScope: r.prScope } : {}),
+            ...(r.runTests === false ? { runTests: false } : {}),
+            ...(r.deployEnvironment ? { deployEnvironment: r.deployEnvironment } : {}),
+            ...(r.waitForDeploySec !== undefined ? { waitForDeploySec: r.waitForDeploySec } : {}),
+            ...(r.deployUrlMatch ? { deployUrlMatch: r.deployUrlMatch } : {}),
+            ...(r.test ? { test: r.test } : {}),
+            ...(r.targets ? { targets: r.targets } : {}),
+            scan: ws?.scan ?? null,
+            intake: ws?.intake ?? null,
+            lastEventAt: last.get(r.id) ?? ws?.lastEventAt ?? null,
+        };
+    });
+}
+/** Checks PR state for pending PR drafts (merged, closed, moved head), repo by repo. Throttled per dot and repo; a lookup error leaves the draft. */
+async function refreshPrApprovals(watchId) {
+    const watches = watchId ? [get('watches', watchId)].filter((w) => !!w) : list('watches');
+    const jobs = [];
+    for (const w of watches) {
+        for (const r of watchRepos(w)) {
+            if (!pendingPrs(w.id, r.id).length)
+                continue;
+            const gh = githubFor(w, { repo: { owner: r.owner, name: r.name } });
+            // Demo PR payloads are fixed, so their head would expire drafts the demo just made.
+            if (gh.mode === 'demo')
+                continue;
+            jobs.push((async () => {
+                try {
+                    await reconcileThrottled(w.id, async (pr) => {
+                        const p = await gh.getPull(pr);
+                        return p ? { state: p.summary.state, headSha: p.summary.headSha } : null;
+                    }, undefined, r.id);
+                }
+                catch (err) {
+                    log.warn(`approval PR check for ${w.name} (${r.id}) failed: ${String(err)}`);
+                }
+            })());
+        }
+    }
+    await Promise.all(jobs);
+}
+function scopeView(w) {
+    if (w.paused || w.archived)
+        return {};
+    const unread = scopeUnreadOf(w);
+    return unread ? { scopeNotApplied: unread } : {};
+}
+export function dotView(w) {
+    const lastRun = latestRuns(w.id, 1)[0] ?? null;
+    const withVerdict = latestRuns(w.id).find((r) => r.verdict?.headline);
+    return {
+        ...w,
+        ...(w.repo ? { repo: repoAsRun(w) } : {}),
+        repos: dotRepos(w),
+        status: dotStatus(w),
+        lastRun,
+        pendingApprovals: liveCount(w.id),
+        latestFinding: withVerdict?.verdict?.headline ?? null,
+        lastEventAt: list('events', { watchId: w.id, source: 'github' }, { orderBy: 'id DESC', limit: 1 })[0]?.createdAt ?? null,
+        trueKey: trueKeyView(),
+        // How the dot hears about GitHub: webhooks, polling, or neither (KAT-352).
+        ...deliveryOf(w),
+        ...modelCapOf(w),
+        ...scopeView(w),
+        // The lead that names this dot as a member (KAT-405).
+        ...(leadOf(w.id) ? { leadId: leadOf(w.id).id } : {}),
+    };
+}
+function modelCapOf(w) {
+    const modelCap = capState(w);
+    return modelCap ? { modelCap } : undefined;
+}
+const lastStatus = new Map();
+/** The delivery state each dot last showed, as JSON: a change of it publishes the dot again, since the page shows it next to the status (KAT-363). */
+const lastDelivery = new Map();
+function broadcastStatus(watchId, force = false) {
+    const watches = watchId ? [get('watches', watchId)].filter((w) => !!w) : list('watches');
+    for (const w of watches) {
+        const s = dotStatus(w);
+        const delivery = deliveryOf(w);
+        const shown = JSON.stringify(delivery ?? null);
+        if (force || lastStatus.get(w.id) !== s || lastDelivery.get(w.id) !== shown) {
+            lastStatus.set(w.id, s);
+            lastDelivery.set(w.id, shown);
+            publish({ type: 'dot', watchId: w.id, status: s, delivery: delivery ?? {} });
+        }
+    }
+}
+let statusTimer;
+/** Publishes a `dot` live event whenever a dot's derived status, or how it hears about GitHub, changes. */
+export function startStatusWatcher() {
+    if (statusTimer)
+        return;
+    for (const w of list('watches')) {
+        lastStatus.set(w.id, dotStatus(w));
+        lastDelivery.set(w.id, JSON.stringify(deliveryOf(w) ?? null));
+    }
+    subscribe((e) => {
+        // Another module may publish its own view of a dot; remember it so the next poll corrects drift.
+        if (e.type === 'dot')
+            lastStatus.set(e.watchId, e.status);
+        else if (e.type === 'run')
+            broadcastStatus(e.run.watchId);
+        else if (e.type === 'approval')
+            broadcastStatus(e.approval.watchId);
+    });
+    // probe_state changes do not go through the bus, so poll.
+    statusTimer = setInterval(() => broadcastStatus(), 5000);
+    statusTimer.unref?.();
+}
+// VAPID
+let vapid;
+/** Env keys win; else data/vapid.json; else generate and save there. Call at boot so push.ts finds the file. */
+export function ensureVapidKeys() {
+    if (vapid)
+        return vapid;
+    if (config.vapid.publicKey && config.vapid.privateKey) {
+        vapid = { publicKey: config.vapid.publicKey, privateKey: config.vapid.privateKey };
+        return vapid;
+    }
+    const file = join(config.dataDir, 'vapid.json');
+    if (existsSync(file)) {
+        try {
+            const v = JSON.parse(readFileSync(file, 'utf8'));
+            if (v.publicKey && v.privateKey)
+                return (vapid = { publicKey: v.publicKey, privateKey: v.privateKey });
+        }
+        catch {
+            log.warn(`${file} is unreadable, generating new keys`);
+        }
+    }
+    const v = webpush.generateVAPIDKeys();
+    mkdirSync(config.dataDir, { recursive: true });
+    writeFileSync(file, JSON.stringify(v, null, 2), { mode: 0o600 });
+    log.info(`generated VAPID keys into ${file}`);
+    return (vapid = v);
+}
+// SSE
+function openSse(reply) {
+    reply.hijack();
+    const res = reply.raw;
+    res.writeHead(200, {
+        'content-type': 'text/event-stream; charset=utf-8',
+        'cache-control': 'no-cache, no-transform',
+        connection: 'keep-alive',
+        'x-accel-buffering': 'no',
+    });
+    res.write(': connected\n\n');
+    return {
+        raw: res,
+        send(event, data) {
+            if (res.writableEnded || res.destroyed)
+                return;
+            res.write(`${event ? `event: ${event}\n` : ''}data: ${JSON.stringify(data)}\n\n`);
+        },
+        comment(text) {
+            if (!res.writableEnded && !res.destroyed)
+                res.write(`: ${text}\n\n`);
+        },
+        end() {
+            if (!res.writableEnded)
+                res.end();
+        },
+    };
+}
+// Routes
+const WATCH_FIELDS = [
+    'name',
+    'mission',
+    'notifyWhen',
+    'mustNot',
+    'repo',
+    'tracker',
+    'baseUrl',
+    'probes',
+    'statusPages',
+    'probeIntervalSec',
+    'runner',
+    'rules',
+    'digestHour',
+    'digestEvery',
+    'paused',
+    // API v2: role presets, instructions, mascot, MCP connections, Slack channel. The archive flag is not here: DELETE and restore own it.
+    'role',
+    'instructions',
+    'mascot',
+    'connections',
+    'slackChannel',
+    // PR review options (docs/PR-REVIEW-QA.md section 3.1). PUT /api/dots/:id/review checks each value.
+    'review',
+    // Multiple repos (docs/MULTI-REPO.md section 1.5). repo and repos are checked by applyRepoFields.
+    'repos',
+    'waitForPreviewSec',
+    // A merge run waits for the deploy of the merge to this GitHub environment (KAT-368). Checked by deployWaitError, and the admin's like the runner settings.
+    'waitForDeploySec',
+    'deployEnvironment',
+    // What a PR check tests against when no preview of the PR is known (KAT-363). Checked by prTestTargetError.
+    'prTestTarget',
+    // Run the Tests repo on app PRs and on merges (KAT-86). Each is true, false, or null for the default (on). Checked by testRepoSwitchError.
+    'testRepoOnPr',
+    'testRepoOnMerge',
+    // Nightly test run of the Tests repo suite (KAT-390). Checked by nightlyError and settleNightlySave; nightlyLastSlot is the server's.
+    'nightlyRun',
+    // Where the dot's updates go in Slack (KAT-143). Checked by checkUpdates.
+    'updates',
+    // Branches besides the default branch that run post-merge tests (KAT-292). Checked by testBranchesError.
+    'testBranches',
+    // Stage switches and rules (docs/STAGES.md section 5, KAT-161). Checked by stagesError.
+    'stages',
+    // Model per stage (KAT-162). Checked by checkStageModels.
+    'stageModels',
+    // The one-time offer of the new stages (KAT-171). A save may only set it to dismissed; checked by stagesNoticeError.
+    'stagesNotice',
+    // Fewer test runs (KAT-344). Checked by testSavingsError.
+    'testDocsOnlySkip',
+    'testDebounceSec',
+    'reuseMergeResults',
+    // Poll GitHub for this dot (KAT-352). POST /api/dots sets it when the server has no webhook route.
+    'pollGithub',
+    // Model calls per day (KAT-362). Checked by modelCapError; 0 and null turn the cap off.
+    'dailyModelCap',
+    // Send this dot's cases, runs and results to True Platform (KAT-406). Checked by trueSyncError, and the admin's like the runner settings.
+    'trueSync',
+    // A Lead QA dot and its member dots (KAT-405). Checked by leadError; only POST sets `kind`.
+    'kind',
+    'memberIds',
+];
+export const SIMULATE_KINDS = ['pr_merged', 'pr_opened', 'pr_synchronize', 'pr_comment_edited', 'ticket_created', 'outage', 'ci_failure'];
+function pickWatchFields(body) {
+    const out = {};
+    for (const k of WATCH_FIELDS)
+        if (k in body)
+            out[k] = body[k];
+    return out;
+}
+/** runner.copyFiles and runner.passEnv are saved trimmed and without repeats. Call it after validateRunner has checked every entry. */
+function tidyRunner(fields) {
+    const runner = fields.runner;
+    if (!runner || typeof runner !== 'object' || Array.isArray(runner))
+        return;
+    const r = runner;
+    const tidy = {};
+    if (Array.isArray(r.copyFiles))
+        tidy.copyFiles = cleanCopyFiles(r.copyFiles);
+    if (Array.isArray(r.passEnv))
+        tidy.passEnv = cleanPassEnv(r.passEnv);
+    if (Object.keys(tidy).length)
+        fields.runner = { ...runner, ...tidy };
+}
+/**
+ * Checks `repo` and `repos` in a save and rewrites both (docs/MULTI-REPO.md section 1.2): `repos`
+ * wins and `repo` mirrors its first app entry; a body with only `repo` edits the first app entry.
+ * New repos join the workspace. Returns the status and error to answer, or null.
+ */
+async function applyRepoFields(fields, current) {
+    const res = resolveRepoFields(fields, current);
+    if (!res.ok)
+        return { code: 400, error: res.error };
+    // A repo that waits for a deploy needs an environment, its own or the dot's, as this save leaves them (KAT-395).
+    const dotWait = {
+        waitForDeploySec: 'waitForDeploySec' in fields ? fields.waitForDeploySec : current?.waitForDeploySec,
+        deployEnvironment: 'deployEnvironment' in fields ? fields.deployEnvironment : current?.deployEnvironment,
+    };
+    const waitError = repoDeployWaitError(dotWait, res.fields ? watchRepos({ repos: res.fields.repos }) : current ? watchRepos(current) : []);
+    if (waitError)
+        return { code: 400, error: waitError };
+    if (!res.fields)
+        return null;
+    const err = await ensureReposForSave(res.fields.repos);
+    if (err)
+        return err;
+    fields.repos = res.fields.repos;
+    // A repo added above joined the workspace with its own default branch, which the mirror reads.
+    fields.repo = repoMirror(res.fields.repos) ?? (current ? null : undefined);
+    if (fields.repo === undefined)
+        delete fields.repo;
+    return null;
+}
+/** Checks `updates` in a dot save: slack channel, dm, or off, and a member ID for dm. */
+function checkDigestEvery(v) {
+    return v === undefined || v === null || v === 'day' || v === 'week' ? null : 'digestEvery must be day or week.';
+}
+function checkUpdates(v) {
+    if (v === undefined || v === null)
+        return null;
+    if (typeof v !== 'object')
+        return 'updates must be an object.';
+    const u = v;
+    if (u.slack !== undefined && u.slack !== 'channel' && u.slack !== 'dm' && u.slack !== 'off')
+        return 'updates.slack must be channel, dm, or off.';
+    if (u.slackUser !== undefined && u.slackUser !== '' && (typeof u.slackUser !== 'string' || !/^[UW][A-Z0-9]{2,20}$/.test(u.slackUser)))
+        return 'updates.slackUser must be a Slack member ID like U0123ABCD.';
+    if (u.slack === 'dm' && !u.slackUser)
+        return 'A direct message needs a Slack member ID.';
+    return null;
+}
+/**
+ * Checks `stageModels` in a dot save (KAT-162): an object of stage key to a model id from the switcher list, or null
+ * to clear a stage. Returns the message to answer, or null.
+ */
+function checkStageModels(v) {
+    if (v === undefined || v === null)
+        return null;
+    if (typeof v !== 'object' || Array.isArray(v))
+        return 'stageModels must be an object of stage to model.';
+    for (const [stage, id] of Object.entries(v)) {
+        if (!STAGE_KEYS.includes(stage))
+            return `stageModels: "${stage}" is not a stage. Use ${STAGE_KEYS.join(', ')}.`;
+        if (id === null)
+            continue;
+        if (typeof id !== 'string' || !STAGE_MODEL_IDS.includes(id))
+            return `stageModels.${stage}: "${String(id)}" is not a model. Use ${STAGE_MODEL_IDS.join(', ')}, or null for the default.`;
+    }
+    return null;
+}
+/** The saved stageModels: the sent stages laid over the dot's own, with cleared (null) stages removed. */
+function mergeStageModels(current, sent) {
+    const out = {};
+    for (const [k, v] of Object.entries({ ...current, ...sent }))
+        if (typeof v === 'string')
+            out[k] = v;
+    return out;
+}
+function checkPollGithub(v) {
+    return v === undefined || typeof v === 'boolean' ? null : 'pollGithub must be true or false.';
+}
+function checkWait(v) {
+    if (v === undefined || v === null)
+        return null;
+    return typeof v === 'number' && Number.isInteger(v) && v >= 0 && v <= 3600 ? null : 'waitForPreviewSec must be a whole number of seconds from 0 to 3600.';
+}
+/** The deploy wait fields as a save stores them: the environment trimmed, and a wait of 0 or an empty environment as null. Call it after deployWaitError. */
+function tidyDeployWait(fields) {
+    if ('deployEnvironment' in fields)
+        fields.deployEnvironment = cleanDeployEnvironment(fields.deployEnvironment) ?? null;
+    if ('waitForDeploySec' in fields)
+        fields.waitForDeploySec = cleanDeploySec(fields.waitForDeploySec) ?? null;
+}
+function dotName(watchId, cache) {
+    if (!cache.has(watchId))
+        cache.set(watchId, get('watches', watchId)?.name ?? '');
+    return cache.get(watchId) || undefined;
+}
+function clampLimit(v, def, max = 200) {
+    const n = Number(v);
+    return Number.isFinite(n) && n > 0 ? Math.min(Math.floor(n), max) : def;
+}
+export async function registerApi(app) {
+    app.get('/api/health', async () => ({
+        ok: true,
+        // The package.json version and the commit this build came from (null when the host does not say).
+        version: VERSION,
+        commit: commitSha(),
+        demo: config.demo,
+        sandbox: config.sandbox,
+        ...(config.sandbox ? { sandboxBanner: SANDBOX_BANNER } : {}),
+        llm: llmBackend(),
+        dots: count('watches'),
+        // The clock of this server: the nightly test run's time is on it (KAT-390). The offset is minutes behind UTC, as Date.getTimezoneOffset gives it.
+        timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone || null,
+        tzOffsetMin: new Date().getTimezoneOffset(),
+        // TinyBee only (docs/tinybee/05-mobile-app-ux.md section 10): budget, connections, update and API version.
+        ...(hiveMode() !== 'off' ? { tinybee: tinybeeHealth() } : {}),
+    }));
+    // Dots
+    // Archived dots stay readable by id (runs, reports and chat keep their dot), but the list hides them unless ?archived=1.
+    app.get('/api/dots', async (req) => {
+        const withArchived = req.query.archived === '1' || req.query.archived === 'true';
+        return list('watches')
+            .filter((w) => withArchived || !w.archived)
+            .map(dotView);
+    });
+    app.get('/api/dots/:id', async (req, reply) => {
+        const w = get('watches', req.params.id);
+        if (!w)
+            return reply.code(404).send({ error: 'dot not found' });
+        return dotView(w);
+    });
+    app.post('/api/dots', async (req, reply) => {
+        const body = req.body ?? {};
+        if (typeof body.name !== 'string' || !body.name.trim())
+            return reply.code(400).send({ error: 'name is required' });
+        const fields = pickWatchFields(body);
+        const leadFail = leadError(fields);
+        if (leadFail)
+            return reply.code(leadFail.code).send({ error: leadFail.error });
+        const makingLead = fields.kind === 'lead';
+        const runnerError = validateRunner(fields.runner) ?? testBranchesError(fields.testBranches) ?? trackerScopeError(fields.tracker);
+        if (runnerError)
+            return reply.code(400).send({ error: runnerError });
+        if ('testBranches' in fields)
+            fields.testBranches = cleanTestBranches(fields.testBranches);
+        if ('tracker' in fields)
+            fields.tracker = tidyTrackerScope(fields.tracker);
+        tidyRunner(fields);
+        const waitError = trueSyncError(fields.trueSync) ??
+            checkWait(fields.waitForPreviewSec) ??
+            deployWaitError(fields) ??
+            checkPollGithub(fields.pollGithub) ??
+            checkUpdates(fields.updates) ??
+            checkDigestEvery(fields.digestEvery) ??
+            stagesError(fields.stages) ??
+            stagesNoticeError(fields.stagesNotice) ??
+            checkStageModels(fields.stageModels) ??
+            prTestTargetError(fields.prTestTarget) ??
+            testRepoSwitchError(fields) ??
+            nightlyError(fields.nightlyRun) ??
+            testSavingsError(fields) ??
+            modelCapError(fields.dailyModelCap);
+        if (waitError)
+            return reply.code(400).send({ error: waitError });
+        if ('nightlyRun' in fields)
+            fields.nightlyRun = tidyNightly(fields.nightlyRun);
+        if ('dailyModelCap' in fields)
+            fields.dailyModelCap = capOf(fields) ?? null;
+        if ('trueSync' in fields)
+            fields.trueSync = fields.trueSync === null ? undefined : mergeTrueSync(undefined, fields.trueSync);
+        tidyDeployWait(fields);
+        // Shadow week (KAT-357): the days come in `shadowWeekDays`; the saved levels and the end date are the server's.
+        const shadow = parseShadowDays(body.shadowWeekDays);
+        if (!shadow.ok)
+            return reply.code(400).send({ error: shadow.error });
+        if (shadow.days) {
+            const started = startShadowWeek({ rules: fields.rules }, shadow.days);
+            fields.rules = started.rules;
+            if (started.shadowWeek)
+                fields.shadowWeek = started.shadowWeek;
+        }
+        if (fields.stages)
+            fields.stages = mergeStages(undefined, fields.stages);
+        if ('stageModels' in fields)
+            fields.stageModels = mergeStageModels(undefined, fields.stageModels);
+        let reviewPatch;
+        if ('review' in fields) {
+            reviewPatch = parseReviewPatch(fields.review);
+            if (!reviewPatch.ok)
+                return reply.code(400).send({ error: `review: ${reviewPatch.error}` });
+        }
+        // Everything above is checked without writing. Resolving the repos is last: it reads GitHub for
+        // all of them and adds them to the workspace only when every one passes (KAT-106).
+        const repoError = await applyRepoFields(fields);
+        if (repoError)
+            return reply.code(repoError.code).send({ error: repoError.error });
+        const nightlyRefused = settleNightlySave(undefined, fields);
+        if (nightlyRefused)
+            return reply.code(400).send({ error: nightlyRefused });
+        if (reviewPatch?.ok)
+            fields.review = effectiveReviewOptions({ repo: fields.repo, repos: fields.repos, review: reviewPatch.patch });
+        // KAT-352: with no webhook route (no public URL or no webhook secret) nothing would tell this dot about a PR, so it polls.
+        // An explicit pollGithub in the body is the owner's choice and stays.
+        if (fields.pollGithub === undefined && !webhookRoute().ok && !makingLead)
+            fields.pollGithub = true;
+        // A lead has nothing to derive stages from, so every stage is saved off: a dot with no stage entry runs every stage but the guard.
+        if (makingLead) {
+            fields.stages = leadStages();
+        }
+        // A dot made now has nothing to be offered later: the boot migration offers the new stages only to dots that predate them.
+        const w = createWatch({ ...NO_STAGE_OFFER, ...fields, name: body.name.trim() });
+        if (w.trueSync)
+            afterTrueSyncSave(w.id, undefined, w.trueSync);
+        if (makingLead) {
+            forgetLeadIndex();
+            for (const id of w.memberIds ?? [])
+                broadcastStatus(id, true);
+        }
+        broadcastStatus(w.id, makingLead);
+        return reply.code(201).send(dotView(w));
+    });
+    app.patch('/api/dots/:id', async (req, reply) => {
+        const w = get('watches', req.params.id);
+        if (!w)
+            return reply.code(404).send({ error: 'dot not found' });
+        const patch = { ...pickWatchFields(req.body ?? {}), updatedAt: new Date().toISOString() };
+        if (w.archived && 'paused' in patch)
+            return reply.code(409).send({ error: `${w.name} is archived. Restore it before you pause or resume it.` });
+        const leadFail = leadError(patch, w);
+        if (leadFail)
+            return reply.code(leadFail.code).send({ error: leadFail.error });
+        // A save that sends the kind it has changes nothing, so it is not written.
+        delete patch.kind;
+        // What runs as the server user is the admin's (KAT-364): an editor's save may not change the test command, setup, passed
+        // variables, copied files, image, mode, or folders of the dot or of a test repo. Which code a run checks out is too (KAT-369):
+        // the repos, their branches, and the test branches. Checked before anything is read or written.
+        if (roleOf(req.qdCaller) !== 'admin') {
+            const body = req.body ?? {};
+            // The saved list as stored: the dot's resolved repos name each repo `id`, and this check reads `repo`.
+            const changed = runnerAdminChanges({ runner: w.runner, repos: w.repos }, body, {
+                runner: 'runner' in body,
+                repos: 'repos' in body && body.repos !== undefined,
+            });
+            // The deploy wait decides when a run starts on the server, so it is the admin's with the runner settings (KAT-368).
+            const deploy = [...deployAdminChanges(w, body), ...repoDeployChanges(w, body)];
+            if (changed.length || deploy.length)
+                return reply
+                    .code(403)
+                    .send({ error: changed.length ? RUNNER_ADMIN_MESSAGE : DEPLOY_ADMIN_MESSAGE, code: RUNNER_ADMIN_CODE, fields: [...changed, ...deploy] });
+            const moved = repoAdminChanges(w, body);
+            if (moved.length)
+                return reply.code(403).send({ error: REPO_ADMIN_MESSAGE, code: REPO_ADMIN_CODE, fields: moved });
+            // Where the server sends the True Platform key is the admin's too: the switch, the address and the project (KAT-406).
+            const trueFields = trueSyncAdminChanges(w, body);
+            if (trueFields.length)
+                return reply.code(403).send({ error: TRUE_ADMIN_MESSAGE, code: TRUE_ADMIN_CODE, fields: trueFields });
+        }
+        if (patch.rules && typeof patch.rules === 'object')
+            patch.rules = { ...w.rules, ...patch.rules };
+        const runnerError = validateRunner(patch.runner) ?? testBranchesError(patch.testBranches) ?? trackerScopeError(patch.tracker);
+        if (runnerError)
+            return reply.code(400).send({ error: runnerError });
+        if ('testBranches' in patch)
+            patch.testBranches = cleanTestBranches(patch.testBranches);
+        if ('tracker' in patch)
+            patch.tracker = tidyTrackerScope(patch.tracker);
+        tidyRunner(patch);
+        const waitError = trueSyncError(patch.trueSync, w.trueSync) ??
+            checkWait(patch.waitForPreviewSec) ??
+            deployWaitError(patch, w) ??
+            checkPollGithub(patch.pollGithub) ??
+            checkUpdates(patch.updates) ??
+            checkDigestEvery(patch.digestEvery) ??
+            stagesError(patch.stages) ??
+            stagesNoticeError(patch.stagesNotice) ??
+            checkStageModels(patch.stageModels) ??
+            prTestTargetError(patch.prTestTarget) ??
+            testRepoSwitchError(patch) ??
+            nightlyError(patch.nightlyRun) ??
+            testSavingsError(patch) ??
+            modelCapError(patch.dailyModelCap);
+        if ('nightlyRun' in patch && !waitError)
+            patch.nightlyRun = tidyNightly(patch.nightlyRun);
+        if ('dailyModelCap' in patch && !waitError)
+            patch.dailyModelCap = capOf(patch) ?? null;
+        if ('trueSync' in patch && !waitError)
+            patch.trueSync = patch.trueSync === null ? null : mergeTrueSync(w.trueSync, patch.trueSync);
+        if (!waitError)
+            tidyDeployWait(patch);
+        if ('stageModels' in patch)
+            patch.stageModels = patch.stageModels === null ? {} : mergeStageModels(w.stageModels, patch.stageModels);
+        if (waitError)
+            return reply.code(400).send({ error: waitError });
+        // Shadow week (KAT-357). A rule the save changes by hand leaves the shadow week (a level sent as stored does not); `shadowWeekDays` starts, extends (1 to 30) or ends (0) it.
+        const shadow = parseShadowDays(req.body?.shadowWeekDays);
+        if (!shadow.ok)
+            return reply.code(400).send({ error: shadow.error });
+        if (w.shadowWeek && req.body?.rules && typeof req.body.rules === 'object') {
+            patch.shadowWeek = forgetShadowKinds(w.shadowWeek, changedRuleKinds(w.rules, req.body.rules));
+        }
+        if (shadow.days === 0) {
+            patch.rules = endShadowWeek({
+                rules: patch.rules ?? w.rules,
+                shadowWeek: patch.shadowWeek ?? w.shadowWeek,
+            });
+            patch.shadowWeek = null;
+        }
+        else if (shadow.days) {
+            const started = startShadowWeek({ rules: patch.rules ?? w.rules, shadowWeek: patch.shadowWeek ?? w.shadowWeek }, shadow.days);
+            patch.rules = started.rules;
+            patch.shadowWeek = started.shadowWeek;
+        }
+        if (patch.stages) {
+            patch.stages = mergeStages(w, patch.stages);
+            // A save of stages is a choice, so a dot that was never offered the new stages is not offered them at the next boot.
+            // An open offer stays: the dialog answers it, by the notice or by the switches.
+            if (!w.stagesNotice)
+                patch.stagesNotice = NO_STAGE_OFFER.stagesNotice;
+            resetWatcherNotes(w.id);
+        }
+        let reviewPatch;
+        if ('review' in patch) {
+            reviewPatch = parseReviewPatch(patch.review);
+            if (!reviewPatch.ok)
+                return reply.code(400).send({ error: `review: ${reviewPatch.error}` });
+        }
+        // Checks above write nothing; the remote repo reads come last and add to the workspace only when all pass (KAT-106).
+        const repoError = await applyRepoFields(patch, w);
+        if (repoError)
+            return reply.code(repoError.code).send({ error: repoError.error });
+        const nightlyRefused = settleNightlySave(w, patch);
+        if (nightlyRefused)
+            return reply.code(400).send({ error: nightlyRefused });
+        // The defaults come from the dot as this save leaves it: a repo added in the same save turns review on (KAT-171).
+        if (reviewPatch?.ok) {
+            const after = {
+                repo: 'repo' in patch ? (patch.repo ?? undefined) : w.repo,
+                repos: 'repos' in patch ? patch.repos : w.repos,
+                review: w.review,
+            };
+            patch.review = { ...effectiveReviewOptions(after), ...reviewPatch.patch };
+        }
+        // KAT-349: the migration wrote each stage once from the targets the dot had then. A save that adds the first target of a
+        // stage (a probe, a tracker, a repo) turns that stage on when the migration switched it off, unless the save sends
+        // `stages` itself. A stage the owner switched off stays off (KAT-351).
+        if (!patch.stages) {
+            const before = derivedStages(w);
+            const after = derivedStages({ ...w, ...patch });
+            const gained = {};
+            for (const k of STAGE_KEYS)
+                if (!before[k].on && after[k].on && w.stages?.[k]?.on === false && w.stages[k].derived)
+                    gained[k] = { on: true };
+            if (Object.keys(gained).length) {
+                patch.stages = mergeStages(w, gained);
+                resetWatcherNotes(w.id);
+            }
+        }
+        update('watches', w.id, patch);
+        const saved = get('watches', w.id);
+        // A dot switched on queues its cases; one moved to another project forgets what it sent there (KAT-406).
+        if ('trueSync' in patch && saved.trueSync)
+            afterTrueSyncSave(w.id, w.trueSync, saved.trueSync);
+        // A save of `memberIds` publishes a dot event for the lead and for every member added or removed, which drops their kept health
+        // answers and the lead index (KAT-405).
+        if ('memberIds' in patch) {
+            forgetLeadIndex();
+            for (const id of memberChanges(w.memberIds, saved.memberIds))
+                broadcastStatus(id, true);
+        }
+        // A cap that went up or off lets the reviews that waited for the reset start now (KAT-362).
+        if ('dailyModelCap' in patch)
+            releaseModelCapHolds(saved);
+        // A merge run that waits for a deploy looks again under the new setting: off ends the wait, another environment is looked at. A pause
+        // ends it too, so the run stops now and not at the next look, which a dot on webhooks makes up to 5 min away (KAT-368).
+        if ('waitForDeploySec' in patch || 'deployEnvironment' in patch || 'repos' in patch || 'repo' in patch || patch.paused === true)
+            releaseDeployWaits(saved);
+        // A saved setting changes what the health panel can show (a site check, a tracker, a daily cap) without changing the status, so
+        // the dot is published every time: the kept health answer drops and every open page reads it again (KAT-394).
+        broadcastStatus(w.id, true);
+        return dotView(saved);
+    });
+    // Calls and tokens of the dot today and over the last 7 days, per stage, and where it stands against its cap (KAT-362).
+    app.get('/api/dots/:id/model-usage', async (req, reply) => {
+        const w = get('watches', req.params.id);
+        if (!w)
+            return reply.code(404).send({ error: 'dot not found' });
+        return usageOf(w);
+    });
+    // DELETE removes a dot (docs/API-V2.md). mode=archive (the default) stops it and keeps its history, so a
+    // restore brings it back. mode=delete removes the dot and everything that belongs to it, and needs the dot
+    // name in confirmName. Both close the dot's pending approvals as rejected. A paired phone may archive
+    // (mode=archive given explicitly) and restore, which are reversible; mode=delete stays on the computer
+    // (src/phone/auth.ts lists the writes a phone may make).
+    app.delete('/api/dots/:id', async (req, reply) => {
+        const w = get('watches', req.params.id);
+        if (!w)
+            return reply.code(404).send({ error: 'dot not found' });
+        const mode = parseRemoveMode(req.query.mode);
+        if (!mode)
+            return reply.code(400).send({ error: 'mode must be archive or delete.' });
+        if (mode === 'delete') {
+            if (!nameMatches(w, req.query.confirmName))
+                return reply.code(400).send({ error: `Type the dot name, ${w.name}, to delete it permanently.` });
+            // A lead always keeps 1 to 8 members, so the last one cannot go first (KAT-405).
+            const only = onlyMemberRefusal(w);
+            if (only)
+                return reply.code(409).send({ error: only });
+            const summary = await deleteDot(w);
+            lastStatus.delete(w.id);
+            lastDelivery.delete(w.id);
+            // The leads that lost this member show their new member list (KAT-405).
+            for (const id of summary.leadsChanged)
+                broadcastStatus(id, true);
+            return { ok: true, deleted: true, ...summary };
+        }
+        const summary = await archiveDot(w);
+        lastStatus.delete(w.id);
+        lastDelivery.delete(w.id);
+        broadcastStatus(w.id);
+        return { ok: true, archived: true, ...summary };
+    });
+    // What a permanent delete also takes from the team: test run items of other members that point at this dot's cases, and whether this
+    // is the only dot of a lead, which refuses the delete (KAT-405). The confirm dialog reads it before it asks for the name.
+    app.get('/api/dots/:id/delete-preview', async (req, reply) => {
+        const w = get('watches', req.params.id);
+        if (!w)
+            return reply.code(404).send({ error: 'dot not found' });
+        return deletePreview(w);
+    });
+    app.post('/api/dots/:id/restore', async (req, reply) => {
+        const w = get('watches', req.params.id);
+        if (!w)
+            return reply.code(404).send({ error: 'dot not found' });
+        if (!w.archived)
+            return reply.code(409).send({ error: `${w.name} is not archived.` });
+        const back = restoreDot(w);
+        broadcastStatus(back.id);
+        return dotView(back);
+    });
+    // Feed and runs
+    app.get('/api/feed', async (req) => {
+        const { dotId, kind } = req.query;
+        const names = new Map();
+        return list('runs', { watchId: dotId || undefined, kind: kind || undefined }, {
+            orderBy: 'id DESC',
+            limit: clampLimit(req.query.limit, 50),
+            offset: clampLimit(req.query.offset, 0, 100_000),
+        }).map((r) => ({ ...r, stage: runStage(r), dotName: dotName(r.watchId, names) }));
+    });
+    app.get('/api/runs/:id', async (req, reply) => {
+        const run = get('runs', req.params.id);
+        if (!run)
+            return reply.code(404).send({ error: 'run not found' });
+        const watch = get('watches', run.watchId);
+        return {
+            ...run,
+            stage: runStage(run),
+            dotName: watch?.name,
+            summary: safeRunSummary(run, watch?.review?.showFrom),
+            // The run page links to its evidence pack when the run names an issue and left a screenshot or a video (KAT-392).
+            evidencePack: hasEvidencePack(run),
+            approvals: list('approvals', { runId: run.id }),
+            outbox: list('outbox', { runId: run.id }),
+        };
+    });
+    // Approvals
+    app.get('/api/approvals/stats', async (req) => {
+        const days = Math.min(365, Math.max(1, Number(req.query.days) || 30));
+        return approvalStats({ sinceIso: new Date(Date.now() - days * 86_400_000).toISOString(), watchId: req.query.dotId || undefined });
+    });
+    app.get('/api/approvals', async (req) => {
+        const names = new Map();
+        // Inbox load: close drafts past expiresAt, and check the PRs behind pending drafts at most once a minute per dot.
+        sweepTimeExpired();
+        // A slow GitHub never holds the Inbox for long: late results arrive as live approval events.
+        await Promise.race([refreshPrApprovals(req.query.dotId || undefined), new Promise((r) => setTimeout(r, 4000).unref?.())]);
+        const rows = list('approvals', { status: req.query.status || undefined, watchId: req.query.dotId || undefined }, { orderBy: 'id DESC', limit: clampLimit(req.query.limit, 100) }).map((a) => {
+            const run = get('runs', a.runId);
+            const stage = run ? runStage(run) : undefined;
+            // A bug report that two members of a lead found is one item that names both (KAT-405).
+            const foundBy = foundByLine(a, (id) => dotName(id, names) ?? 'another dot');
+            const sources = foundBy
+                ? sourcesOf(a).map((s) => ({ dotName: dotName(s.watchId, names) ?? 'another dot', runId: s.runId, at: s.at, bugSig: s.bugSig }))
+                : undefined;
+            return { ...a, dotName: dotName(a.watchId, names), ...(stage ? { stage } : {}), ...(foundBy ? { foundBy, sources } : {}) };
+        });
+        // targetTitle and targetUrl: the ticket, PR, or commit title the Inbox shows as a chip.
+        return withTargetTitles(rows);
+    });
+    app.post('/api/approvals/:id', async (req, reply) => {
+        const a = get('approvals', req.params.id);
+        if (!a)
+            return reply.code(404).send({ error: 'approval not found' });
+        if (approvalExpired(a)) {
+            if (a.status === 'pending') {
+                closeApproval(a, 'expired', 'Nobody decided before it expired.');
+            }
+            return reply.code(410).send({ error: 'approval expired' });
+        }
+        if (a.status !== 'pending')
+            return reply.code(409).send({ error: `approval is already ${a.status}` });
+        const { decision, edit } = req.body ?? {};
+        // A status change runs from the option a person picked on the card (meta.optionId), never from its body, so an edited body would be
+        // dropped and the ticket would move to the status that was first picked. Refuse it in words instead.
+        if (decision === 'approve' && a.action.kind === 'ticket_status' && typeof edit === 'string' && edit.trim())
+            return reply.code(400).send({ error: 'A status change cannot be edited. Reject it, then pick another status on the card.' });
+        try {
+            // A paired device decides under its name (KAT-356); the shared admin token and a local browser name no one.
+            const by = approverOf(req);
+            if (decision === 'approve')
+                await approveAction(a.id, typeof edit === 'string' && edit.trim() ? edit : undefined, by ? { by } : {});
+            else if (decision === 'reject')
+                await rejectAction(a.id, undefined, by ? { by } : {});
+            else
+                return reply.code(400).send({ error: "decision must be 'approve' or 'reject'" });
+        }
+        catch (err) {
+            // A send that failed for a temporary reason is retried by the server; a person waits for the backoff to end (KAT-178).
+            if (err instanceof RetryingError)
+                return reply.code(409).send({ error: err.message, code: 'retrying', nextAt: err.nextAt });
+            log.error(`approval ${a.id} ${decision} failed`, err);
+            return reply.code(502).send({ error: String(err instanceof Error ? err.message : err) });
+        }
+        // rules.ts publishes the approval live event.
+        return get('approvals', a.id);
+    });
+    // Memory
+    app.get('/api/memory', async (req) => list('memory', { watchId: req.query.dotId || undefined }, { orderBy: 'id DESC' }));
+    app.post('/api/memory', async (req, reply) => {
+        const { text, kind } = req.body ?? {};
+        const watchId = req.body?.dotId ?? req.body?.watchId;
+        if (!watchId || !get('watches', watchId))
+            return reply.code(400).send({ error: 'dotId must name an existing dot' });
+        if (typeof text !== 'string' || !text.trim())
+            return reply.code(400).send({ error: 'text is required' });
+        const kinds = ['flaky_spec', 'env_quirk', 'convention', 'decision', 'note'];
+        const item = insert('memory', { watchId, kind: kind && kinds.includes(kind) ? kind : 'note', text: text.trim(), source: 'user' });
+        return reply.code(201).send(item);
+    });
+    app.delete('/api/memory/:id', async (req, reply) => {
+        if (!remove('memory', req.params.id))
+            return reply.code(404).send({ error: 'memory item not found' });
+        return { ok: true };
+    });
+    // Chat. Messages are scoped by dot id, or 'all' for the cross-dot chat (agent/chat.ts convention).
+    // A report-scoped chat stores its turns under `report:<id>` (agent/chat.ts runChat); ?reportId reads that scope.
+    app.get('/api/messages', async (req) => {
+        const scope = req.query.reportId ? `report:${req.query.reportId}` : req.query.dotId || 'all';
+        const rows = list('messages', { watchId: scope }, { orderBy: 'id DESC', limit: clampLimit(req.query.limit, 50) }).reverse();
+        // A dot update with a decision shows the approval as it stands now (KAT-143), and triage rows read their
+        // action state again (KAT-247), so a reopened chat shows what was done since.
+        return rows.map((m) => {
+            const id = m.update?.approvalId;
+            const approval = id ? get('approvals', id) : undefined;
+            const withUpdate = approval && m.update ? { ...m, update: { ...m.update, approval } } : m;
+            return withUpdate.blocks ? { ...withUpdate, blocks: refreshStoredBlocks(withUpdate.blocks) } : withUpdate;
+        });
+    });
+    app.post('/api/chat', async (req, reply) => {
+        const text = req.body?.text;
+        if (typeof text !== 'string' || !text.trim())
+            return reply.code(400).send({ error: 'text is required' });
+        const dotId = req.body?.dotId || undefined;
+        const watch = dotId ? get('watches', dotId) : undefined;
+        if (dotId && !watch)
+            return reply.code(404).send({ error: 'dot not found' });
+        const reportId = typeof req.body?.reportId === 'string' && req.body.reportId ? req.body.reportId : undefined;
+        if (reportId && !getReport(reportId))
+            return reply.code(404).send({ error: 'report not found' });
+        const channel = req.body?.channel === 'call' ? 'call' : 'chat';
+        const sse = openSse(reply);
+        let acc = '';
+        let closed = false;
+        const untrack = req.qdCaller?.kind === 'device'
+            ? trackDeviceStream(req.qdCaller.deviceId, () => {
+                closed = true;
+                sse.end();
+            })
+            : () => { };
+        sse.raw.on('close', () => {
+            closed = true;
+            untrack();
+        });
+        try {
+            // answerChat loads history and stores both turns itself. Events: tool, tool_result, approval, run.
+            const out = await answerChat({ dotId: watch?.id, text, reportId, channel, role: roleOf(req.qdCaller) }, (t) => {
+                acc += t;
+                if (!closed)
+                    sse.send('delta', { text: t });
+            }, () => { }, (e) => {
+                if (closed)
+                    return;
+                const { type, ...data } = e;
+                sse.send(type, data);
+            });
+            const final = typeof out === 'string' && out ? out : acc;
+            // The deltas went out as the model wrote them. When the final text differs in more than spacing (titled
+            // references, KAT-225), the client swaps it in for what streamed.
+            const squash = (t) => t.replace(/\s+/g, '');
+            sse.send('done', { text: final, ...(squash(final) !== squash(acc) && acc ? { replace: true } : {}) });
+        }
+        catch (err) {
+            log.error('chat failed', err);
+            sse.send('error', { error: String(err instanceof Error ? err.message : err) });
+        }
+        finally {
+            sse.end();
+        }
+    });
+    // Live events
+    app.get('/api/live', async (req, reply) => {
+        const sse = openSse(reply);
+        const unsub = subscribe((e) => sse.send(null, e));
+        const closeClient = liveClientOpened();
+        const ping = setInterval(() => sse.comment('ping'), 25_000);
+        // Revoking a phone ends its open stream at once.
+        const untrack = req.qdCaller?.kind === 'device' ? trackDeviceStream(req.qdCaller.deviceId, () => sse.end()) : () => { };
+        req.raw.on('close', () => {
+            clearInterval(ping);
+            unsub();
+            closeClient();
+            untrack();
+        });
+    });
+    // Push
+    app.get('/api/push/vapid', async () => ({ publicKey: ensureVapidKeys().publicKey }));
+    app.post('/api/push/subscribe', async (req, reply) => {
+        const body = req.body ?? {};
+        const sub = (body.subscription && typeof body.subscription === 'object' ? body.subscription : body);
+        if (!sub.endpoint || !sub.keys?.p256dh || !sub.keys?.auth)
+            return reply.code(400).send({ error: 'invalid push subscription' });
+        const existing = findOne('push_subs', { endpoint: sub.endpoint });
+        // A paired phone's subscription is bound to its device, so revoking the device stops its pushes.
+        const deviceId = req.qdCaller?.kind === 'device' ? req.qdCaller.deviceId : null;
+        const row = { endpoint: sub.endpoint, keys: sub.keys, subscription: sub, userAgent: req.headers['user-agent'], deviceId };
+        if (existing)
+            update('push_subs', existing.id, row);
+        else
+            insert('push_subs', row);
+        return reply.code(201).send({ ok: true });
+    });
+    // Outbox
+    app.get('/api/outbox', async (req) => {
+        const names = new Map();
+        return list('outbox', { watchId: req.query.dotId || undefined, runId: req.query.runId || undefined }, { orderBy: 'id DESC', limit: clampLimit(req.query.limit, 100) }).map((o) => ({ ...o, dotName: dotName(o.watchId, names) }));
+    });
+    // Simulate: same normalize and enqueue path as real webhooks, minus signatures.
+    app.post('/api/simulate/:kind', async (req, reply) => {
+        const kind = req.params.kind;
+        if (!SIMULATE_KINDS.includes(kind))
+            return reply.code(400).send({ error: `kind must be one of ${SIMULATE_KINDS.join(', ')}` });
+        let payload;
+        try {
+            payload = JSON.parse(await readFile(join(config.demoDir, 'payloads', `${kind}.json`), 'utf8'));
+        }
+        catch (err) {
+            return reply.code(404).send({ error: `demo/payloads/${kind}.json missing or invalid: ${String(err)}` });
+        }
+        const dotId = req.body?.dotId || req.query.dotId;
+        if (dotId && !get('watches', dotId))
+            return reply.code(404).send({ error: 'dot not found' });
+        const h = payload.headers ?? {};
+        const eventName = payload.eventName ?? h['X-GitHub-Event'] ?? h['x-github-event'];
+        const result = ingest(payload.source, eventName, payload.body, {
+            simulate: true,
+            watchIds: dotId ? [dotId] : undefined,
+            fallbackToAll: true,
+        });
+        return reply.code(result.accepted ? 202 : 422).send({
+            ok: result.accepted,
+            reason: result.reason,
+            jobKind: result.jobKind,
+            trigger: result.trigger ? { kind: result.trigger.kind, title: result.trigger.title } : undefined,
+            jobs: result.jobs,
+        });
+    });
+}
+/** A stored review from an older build can miss a field the renderer reads; the run page still loads without a summary. */
+function safeRunSummary(run, showFrom) {
+    try {
+        return runSummary(run, showFrom);
+    }
+    catch (err) {
+        log.warn(`run summary for ${run.id} failed: ${String(err)}`);
+        return undefined;
+    }
+}
+//# sourceMappingURL=api.js.map