@tapflowio/relay 0.28.1 → 0.30.0

package/dist/admission/leaseChoice.d.ts

@@ -0,0 +1,38 @@
+import type { AdmissionRefusal } from '@tapflowio/protocol';
+/** A device a lease could take, with what the relay would answer if it tried. */
+export interface LeaseCandidate {
+    sessionId: string;
+    hostKey: string;
+    /** Up from an earlier automated boot and idle, so leasing it boots nothing. */
+    pool: boolean;
+    /** When automation booted it; the older of two pool devices goes first, as the cap's eviction would take it. */
+    bootedAt: number;
+    /** Why taking it now would be refused, or `null` if it would go. */
+    refusal: AdmissionRefusal | null;
+}
+/** What the relay knows of a Mac's room, from its agents' reports. `null` when it has not reported. */
+export interface LeaseHost {
+    /** Memory left, by its latest report. */
+    freeMB: number | null;
+    cpuPercent: number | null;
+    /** Automation devices up or starting on it. */
+    automated: number;
+}
+export type LeaseChoice = {
+    ok: true;
+    sessionId: string;
+}
+/** `hostKey`: a Mac that refused for critical memory, so the caller can free an idle device there. */
+ | {
+    ok: false;
+    reason: AdmissionRefusal;
+    criticalHost?: string;
+};
+/**
+ * Pick the device for a lease. A device already up wins over one to boot, on any Mac: it costs no boot. Between
+ * boots, the Mac with the most memory left goes first, then the idler CPU, then the one running fewer automation
+ * devices; a Mac that has not reported goes last, since nothing says it has room. One cold boot per Mac is the
+ * gate's rule, so spreading boots this way is what lets two Macs boot two devices at once.
+ */
+export declare function chooseLease(candidates: readonly LeaseCandidate[], hosts: ReadonlyMap<string, LeaseHost>): LeaseChoice;
+//# sourceMappingURL=leaseChoice.d.ts.map

package/dist/admission/leaseChoice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"leaseChoice.d.ts","sourceRoot":"","sources":["../../src/admission/leaseChoice.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAE3D,iFAAiF;AACjF,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,+EAA+E;IAC/E,IAAI,EAAE,OAAO,CAAA;IACb,gHAAgH;IAChH,QAAQ,EAAE,MAAM,CAAA;IAChB,oEAAoE;IACpE,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAAA;CACjC;AAED,uGAAuG;AACvG,MAAM,WAAW,SAAS;IACxB,yCAAyC;IACzC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,MAAM,WAAW,GACnB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE;AACjC,sGAAsG;GACpG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,gBAAgB,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AASlE;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,SAAS,cAAc,EAAE,EAAE,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,WAAW,CAuBrH"}

package/dist/admission/leaseChoice.js

@@ -0,0 +1,40 @@
+/**
+ * Which refusal to report when every candidate was refused: the one a client is likeliest to see lift by waiting.
+ * A boot settles within a minute or two; the cap lifts when a run lets a device go; a busy CPU or critical memory can
+ * last as long as the load behind it.
+ */
+const WAIT_ORDER = ['host-booting', 'host-at-capacity', 'agent-resources-exhausted', 'host-memory-critical'];
+/**
+ * Pick the device for a lease. A device already up wins over one to boot, on any Mac: it costs no boot. Between
+ * boots, the Mac with the most memory left goes first, then the idler CPU, then the one running fewer automation
+ * devices; a Mac that has not reported goes last, since nothing says it has room. One cold boot per Mac is the
+ * gate's rule, so spreading boots this way is what lets two Macs boot two devices at once.
+ */
+export function chooseLease(candidates, hosts) {
+    const open = candidates.filter((c) => c.refusal === null);
+    if (open.length > 0) {
+        const room = (c) => hosts.get(c.hostKey)?.freeMB ?? null;
+        const byRoom = (a, b) => {
+            const ra = room(a), rb = room(b);
+            if (ra === null || rb === null)
+                return ra === rb ? 0 : ra === null ? 1 : -1;
+            return rb - ra;
+        };
+        const pool = open.filter((c) => c.pool).sort((a, b) => byRoom(a, b) || a.bootedAt - b.bootedAt);
+        if (pool.length > 0)
+            return { ok: true, sessionId: pool[0].sessionId };
+        const cpu = (c) => hosts.get(c.hostKey)?.cpuPercent ?? Infinity;
+        const automated = (c) => hosts.get(c.hostKey)?.automated ?? 0;
+        const boot = [...open].sort((a, b) => byRoom(a, b) || cpu(a) - cpu(b) || automated(a) - automated(b));
+        return { ok: true, sessionId: boot[0].sessionId };
+    }
+    const refused = candidates.filter((c) => c.refusal !== null);
+    const reason = WAIT_ORDER.find((r) => refused.some((c) => c.refusal === r)) ?? 'host-booting';
+    if (reason !== 'host-memory-critical')
+        return { ok: false, reason };
+    // The Mac where freeing a device would help most: the one with the most memory already, so one device may be enough.
+    const critical = refused.filter((c) => c.refusal === 'host-memory-critical');
+    const best = [...critical].sort((a, b) => (hosts.get(b.hostKey)?.freeMB ?? -Infinity) - (hosts.get(a.hostKey)?.freeMB ?? -Infinity))[0];
+    return { ok: false, reason, ...(best ? { criticalHost: best.hostKey } : {}) };
+}
+//# sourceMappingURL=leaseChoice.js.map

package/dist/admission/leaseChoice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"leaseChoice.js","sourceRoot":"","sources":["../../src/admission/leaseChoice.ts"],"names":[],"mappings":"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"}

package/dist/admission/settle.d.ts

@@ -0,0 +1,35 @@
+/**
+ * When a booted device has stopped costing its Mac.
+ *
+ * The harm a boot does to other sessions on the same Mac lasts 30–90 s after it, while the kernel compresses and
+ * pages the other devices' memory to make room (`contributing/simulator-boot-contention.md`). The boot gate holds
+ * its slot until that is over, and this is how it tells.
+ *
+ * **CPU only, and flat rather than low.** Each further device raises the CPU a settled Mac idles at, and an 8 GB
+ * Mac compresses all the time, so "back to where it was before the boot" never arrives and a rule built on it is
+ * a fixed timer in disguise. Decompressions are left out for the same reason: an Android emulator and a lean
+ * iOS simulator go on decompressing 10–30 thousand pages a second once settled while the person's session is at
+ * baseline (M2, 2026-10-23), so a floor on them would hold the slot until the cap every time.
+ *
+ * The numbers come from 27 measured boots on an 8 GB Mac (L2 admission plan, appendix 숫자 결정): three flat
+ * samples put the settle point at 45 s after boot on average, 76–84 s for an unmodified simulator, and inside
+ * the harm in 7 of 27 boots, most of them at the rate a Mac with no boot shows anyway. Four samples cut that
+ * to 5 and moved the average to 58 s.
+ */
+export declare const SETTLE: {
+    /** Consecutive samples that must agree. Agents report every 5 s, so this is 15 s. */
+    readonly samples: 3;
+    /** Largest spread across those samples, in percentage points. */
+    readonly spread: 10;
+    /** Every one of them below this. A Mac pinned near 100 % is not settled however flat it reads. */
+    readonly ceiling: 90;
+    /** A sample older than this is not about now. Three missed reports. */
+    readonly freshMs: 15000;
+};
+/**
+ * Whether the samples taken since the device reported ready say it has settled. The caller drops the first
+ * sample after ready: an agent's CPU reading averages over the interval since its previous one, so it still
+ * covers the boot.
+ */
+export declare function isSettled(cpuSinceReady: readonly number[]): boolean;
+//# sourceMappingURL=settle.d.ts.map

package/dist/admission/settle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settle.d.ts","sourceRoot":"","sources":["../../src/admission/settle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,MAAM;IACjB,qFAAqF;;IAErF,iEAAiE;;IAEjE,kGAAkG;;IAElG,uEAAuE;;CAE/D,CAAA;AAEV;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAKnE"}

package/dist/admission/settle.js

@@ -0,0 +1,41 @@
+/**
+ * When a booted device has stopped costing its Mac.
+ *
+ * The harm a boot does to other sessions on the same Mac lasts 30–90 s after it, while the kernel compresses and
+ * pages the other devices' memory to make room (`contributing/simulator-boot-contention.md`). The boot gate holds
+ * its slot until that is over, and this is how it tells.
+ *
+ * **CPU only, and flat rather than low.** Each further device raises the CPU a settled Mac idles at, and an 8 GB
+ * Mac compresses all the time, so "back to where it was before the boot" never arrives and a rule built on it is
+ * a fixed timer in disguise. Decompressions are left out for the same reason: an Android emulator and a lean
+ * iOS simulator go on decompressing 10–30 thousand pages a second once settled while the person's session is at
+ * baseline (M2, 2026-10-23), so a floor on them would hold the slot until the cap every time.
+ *
+ * The numbers come from 27 measured boots on an 8 GB Mac (L2 admission plan, appendix 숫자 결정): three flat
+ * samples put the settle point at 45 s after boot on average, 76–84 s for an unmodified simulator, and inside
+ * the harm in 7 of 27 boots, most of them at the rate a Mac with no boot shows anyway. Four samples cut that
+ * to 5 and moved the average to 58 s.
+ */
+export const SETTLE = {
+    /** Consecutive samples that must agree. Agents report every 5 s, so this is 15 s. */
+    samples: 3,
+    /** Largest spread across those samples, in percentage points. */
+    spread: 10,
+    /** Every one of them below this. A Mac pinned near 100 % is not settled however flat it reads. */
+    ceiling: 90,
+    /** A sample older than this is not about now. Three missed reports. */
+    freshMs: 15_000,
+};
+/**
+ * Whether the samples taken since the device reported ready say it has settled. The caller drops the first
+ * sample after ready: an agent's CPU reading averages over the interval since its previous one, so it still
+ * covers the boot.
+ */
+export function isSettled(cpuSinceReady) {
+    if (cpuSinceReady.length < SETTLE.samples)
+        return false;
+    const last = cpuSinceReady.slice(-SETTLE.samples);
+    const high = Math.max(...last);
+    return high < SETTLE.ceiling && high - Math.min(...last) <= SETTLE.spread;
+}
+//# sourceMappingURL=settle.js.map

package/dist/admission/settle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settle.js","sourceRoot":"","sources":["../../src/admission/settle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,qFAAqF;IACrF,OAAO,EAAE,CAAC;IACV,iEAAiE;IACjE,MAAM,EAAE,EAAE;IACV,kGAAkG;IAClG,OAAO,EAAE,EAAE;IACX,uEAAuE;IACvE,OAAO,EAAE,MAAM;CACP,CAAA;AAEV;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,aAAgC;IACxD,IAAI,aAAa,CAAC,MAAM,GAAG,MAAM,CAAC,OAAO;QAAE,OAAO,KAAK,CAAA;IACvD,MAAM,IAAI,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;IACjD,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAA;IAC9B,OAAO,IAAI,GAAG,MAAM,CAAC,OAAO,IAAI,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,IAAI,MAAM,CAAC,MAAM,CAAA;AAC3E,CAAC"}

package/dist/api/runs.d.ts

@@ -6,9 +6,18 @@ import http from 'http';
 export interface RunHolders {
     /** The owner keys of every open socket, built once per pass so a check costs a lookup, not a scan. */
     connectedKeys(): Set<string>;
-    /** The session a socket with one of these keys holds now — the one a watch link should open — or null. */
-    heldSession(keys: string[]): string | null;
+    /** The sessions the sockets with these keys hold now — the ones a watch link should open. A parallel run holds one
+     *  per device. */
+    heldSessions(keys: string[]): string[];
 }
+/**
+ * Drop the started flows of every run that is no longer running. The paths in this file forget a run as it ends, but a
+ * run's row can also be deleted under it — its build or app deleted, its expiry passed — by code that never calls in
+ * here; the daily purge sweeps those, whichever path took them.
+ */
+export declare function forgetStartedFlowsOfStoppedRuns(): void;
+/** How many runs have started flows held in memory, for tests of when they are let go. */
+export declare function startedFlowRunCount(): number;
 /**
  * The owner keys the runner's socket can have (`ownerKeyFor` in `RelayServer`). **Two, because the socket
  * and REST disagree on loopback**: the handshake does not read a PAT from a local connection, so a runner on
@@ -31,6 +40,8 @@ export interface RunRow {
     ci_branch: string | null;
     ci_commit: string | null;
     ci_job_url: string | null;
+    service_tier_json: string | null;
+    device_reset_json: string | null;
     status: 'running' | 'passed' | 'failed' | 'aborted';
     finished_by: 'client' | 'relay' | null;
     failure_kind: string | null;
@@ -67,7 +78,15 @@ graceAfterFinishSeconds?: number): RunRow | null;
 export declare function finishedWithin(run: Pick<RunRow, 'finished_at'>, seconds: number): boolean;
 export declare function handleCreateRun(req: http.IncomingMessage, res: http.ServerResponse): Promise<void>;
 export declare function handleReportFlow(req: http.IncomingMessage, res: http.ServerResponse, params: Record<string, string>): Promise<void>;
+/**
+ * The runner started flow `idx` on a device. Without it the page could only guess the first unreported flow, which a
+ * run on several devices makes wrong: several flows run at once, and not in order. A start for a flow already
+ * reported changes nothing on the page, which reads a reported flow's row before this, so nothing here checks for one
+ * or forgets an entry when its flow reports; entries go with the run, and there are at most `flows_total`.
+ */
+export declare function handleStartFlow(req: http.IncomingMessage, res: http.ServerResponse, params: Record<string, string>): Promise<void>;
 export declare function handleUploadFlowScreenshot(req: http.IncomingMessage, res: http.ServerResponse, params: Record<string, string>, screenshotsDir: string): Promise<void>;
+export declare function handleReportDevice(req: http.IncomingMessage, res: http.ServerResponse, params: Record<string, string>): Promise<void>;
 export declare function handleFinishRun(req: http.IncomingMessage, res: http.ServerResponse, params: Record<string, string>): Promise<void>;
 export declare function handleListRuns(req: http.IncomingMessage, res: http.ServerResponse, holders: RunHolders): void;
 export declare function handleGetRun(req: http.IncomingMessage, res: http.ServerResponse, params: Record<string, string>, holders: RunHolders, videosOf?: (run: RunRow) => Map<number, unknown>): void;

package/dist/api/runs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runs.d.ts","sourceRoot":"","sources":["../../src/api/runs.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runs.d.ts","sourceRoot":"","sources":["../../src/api/runs.ts"],"names":[],"mappings":"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"}

package/dist/api/runs.js

@@ -1,3 +1,4 @@
+import { readRunResetReport, readServiceTier } from '@tapflowio/protocol/validate';
 import fs from 'fs';
 import path from 'path';
 import { randomUUID } from 'crypto';
@@ -29,6 +30,30 @@ const BUILDLESS_TTL_DAYS = 7;
  * close handler is the normal path (`abandonRunsOf`); this only catches what it could not.
  */
 const ORPHAN_GRACE_SECONDS = 60;
+/**
+ * The flows each running run has started and not yet reported, by run id. **Memory, not the database**: which flow is
+ * on a device right now means something only while the runner's socket is open, and a relay restart drops that socket,
+ * so the run is closed as `holder-lost` within `ORPHAN_GRACE_SECONDS` anyway. A run is present from its first start
+ * report, even with nothing in flight, so the page can tell a runner that reports starts from one that predates them.
+ */
+const startedFlows = new Map();
+/**
+ * Drop the started flows of every run that is no longer running. The paths in this file forget a run as it ends, but a
+ * run's row can also be deleted under it — its build or app deleted, its expiry passed — by code that never calls in
+ * here; the daily purge sweeps those, whichever path took them.
+ */
+export function forgetStartedFlowsOfStoppedRuns() {
+    if (startedFlows.size === 0)
+        return;
+    const running = getDb().prepare(`SELECT 1 FROM flow_runs WHERE id = ? AND status = 'running'`);
+    for (const id of startedFlows.keys())
+        if (!running.get(id))
+            startedFlows.delete(id);
+}
+/** How many runs have started flows held in memory, for tests of when they are let go. */
+export function startedFlowRunCount() {
+    return startedFlows.size;
+}
 /**
  * The owner keys the runner's socket can have (`ownerKeyFor` in `RelayServer`). **Two, because the socket
  * and REST disagree on loopback**: the handshake does not read a PAT from a local connection, so a runner on
@@ -130,15 +155,17 @@ export function abandonRunsOf(socketKey, holders) {
     const client = socketKey.slice(colon + 1);
     const db = getDb();
     const runs = (user === 'anon'
-        ? db.prepare(`SELECT seq, created_by, holder_client FROM flow_runs WHERE status = 'running' AND holder_client = ?`).all(client)
-        : db.prepare(`SELECT seq, created_by, holder_client FROM flow_runs WHERE status = 'running' AND holder_client = ? AND created_by = ?`).all(client, Number(user)));
+        ? db.prepare(`SELECT seq, id, created_by, holder_client FROM flow_runs WHERE status = 'running' AND holder_client = ?`).all(client)
+        : db.prepare(`SELECT seq, id, created_by, holder_client FROM flow_runs WHERE status = 'running' AND holder_client = ? AND created_by = ?`).all(client, Number(user)));
     if (runs.length === 0)
         return;
     const open = holders.connectedKeys();
     const stmt = db.prepare(`${ABANDON} AND seq = ?`);
     for (const r of runs) {
-        if (!holderKeys(r.created_by, r.holder_client).some((k) => open.has(k)))
-            stmt.run(r.seq);
+        if (holderKeys(r.created_by, r.holder_client).some((k) => open.has(k)))
+            continue;
+        stmt.run(r.seq);
+        startedFlows.delete(r.id);
     }
 }
 /**
@@ -147,7 +174,7 @@ export function abandonRunsOf(socketKey, holders) {
  */
 export function settleOrphanedRuns(holders) {
     const running = getDb().prepare(`
-    SELECT seq, created_by, holder_client FROM flow_runs
+    SELECT seq, id, created_by, holder_client FROM flow_runs
      WHERE status = 'running' AND last_activity_at < datetime('now', ?)
   `).all(`-${ORPHAN_GRACE_SECONDS} seconds`);
     if (running.length === 0)
@@ -155,8 +182,10 @@ export function settleOrphanedRuns(holders) {
     const open = holders.connectedKeys();
     const stmt = getDb().prepare(`${ABANDON} AND seq = ?`);
     for (const r of running) {
-        if (!holderKeys(r.created_by, r.holder_client).some((k) => open.has(k)))
-            stmt.run(r.seq);
+        if (holderKeys(r.created_by, r.holder_client).some((k) => open.has(k)))
+            continue;
+        stmt.run(r.seq);
+        startedFlows.delete(r.id);
     }
 }
 // ── writes (the run's creator only) ─────────────────────────────────────────
@@ -228,15 +257,20 @@ export async function handleCreateRun(req, res) {
         }
     }
     const ci = isObj(body.ci) ? body.ci : null;
+    // Dropped rather than refused when it is not a tier, as `ci`'s fields are: recording never fails a run.
+    const serviceTier = readServiceTier(body.serviceTier);
+    const deviceReset = typeof body.resetRequested === 'boolean' ? { requested: body.resetRequested } : null;
     const id = randomUUID();
     getDb().prepare(`
     INSERT INTO flow_runs (id, build_id, holder_client, created_by, pat_id, is_ci, ci_provider, ci_branch, ci_commit,
-                           ci_job_url, flows_json, flows_total, delete_after)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, CASE WHEN ? IS NULL THEN datetime('now', ?) END)
-  `).run(id, buildId, client, auth.userId, auth.patId ?? null, ci ? 1 : 0, ci ? str(ci.provider, 50) : null, ci ? str(ci.branch, MAX_NAME) : null, ci ? str(ci.commit, 100) : null, ci ? httpUrl(ci.jobUrl) : null, JSON.stringify(flows), flows.length, buildId, `+${BUILDLESS_TTL_DAYS} days`);
+                           ci_job_url, service_tier_json, device_reset_json, flows_json, flows_total, delete_after)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, CASE WHEN ? IS NULL THEN datetime('now', ?) END)
+  `).run(id, buildId, client, auth.userId, auth.patId ?? null, ci ? 1 : 0, ci ? str(ci.provider, 50) : null, ci ? str(ci.branch, MAX_NAME) : null, ci ? str(ci.commit, 100) : null, ci ? httpUrl(ci.jobUrl) : null, serviceTier ? JSON.stringify(serviceTier) : null, deviceReset ? JSON.stringify(deviceReset) : null, JSON.stringify(flows), flows.length, buildId, `+${BUILDLESS_TTL_DAYS} days`);
     json(res, 201, { id });
 }
-const FLOW_STATUSES = new Set(['passed', 'failed']);
+const FLOW_STATUSES = new Set(['passed', 'failed', 'skipped']);
+/** Why the runner did not replay a flow — flow-runner's `SkipReason`. */
+const SKIP_REASONS = new Set(['app-mismatch', 'tag-filter']);
 const STEP_STATUSES = new Set(['passed', 'failed', 'skipped']);
 export async function handleReportFlow(req, res, params) {
     const run = ownRun(req, res, params.id);
@@ -249,7 +283,15 @@ export async function handleReportFlow(req, res, params) {
     if (!body)
         return;
     if (typeof body.status !== 'string' || !FLOW_STATUSES.has(body.status)) {
-        return json(res, 400, { error: 'status must be passed or failed' });
+        return json(res, 400, { error: 'status must be passed, failed or skipped' });
+    }
+    // The reason comes with a skip and with nothing else, so a row cannot say "passed" and give a reason it was not run.
+    const skipReason = body.status === 'skipped' ? body.skipReason : undefined;
+    if (body.status === 'skipped' && (typeof skipReason !== 'string' || !SKIP_REASONS.has(skipReason))) {
+        return json(res, 400, { error: 'a skipped flow needs a skipReason of app-mismatch or tag-filter' });
+    }
+    if (body.status !== 'skipped' && body.skipReason != null) {
+        return json(res, 400, { error: 'skipReason is only for a skipped flow' });
     }
     const durationMs = nonNegInt(body.durationMs);
     if (durationMs === null)
@@ -285,16 +327,23 @@ export async function handleReportFlow(req, res, params) {
             return 'gone';
         if (now.finished_by === 'client')
             return 'finished';
+        // A flow that ran cannot become one that was skipped: its screenshot would stay behind a row that says nothing
+        // was on screen. The runner decides skips before any flow runs, so only a confused client gets here.
+        if (body.status === 'skipped') {
+            const was = db.prepare('SELECT status FROM flow_run_flows WHERE run_seq = ? AND idx = ?').get(run.seq, idx);
+            if (was && was.status !== 'skipped')
+                return 'ran';
+        }
         // An upsert that keeps the screenshot: the CLI may retry a report, and the screenshot arrives separately.
         db.prepare(`
-      INSERT INTO flow_run_flows (run_seq, idx, name, file, device_id, device_name, platform, status, failure_kind,
-                                  failure_message, duration_ms, steps_json)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      INSERT INTO flow_run_flows (run_seq, idx, name, file, device_id, device_name, platform, status, skip_reason,
+                                  failure_kind, failure_message, duration_ms, steps_json)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       ON CONFLICT (run_seq, idx) DO UPDATE SET
         device_id = excluded.device_id, device_name = excluded.device_name, platform = excluded.platform,
-        status = excluded.status, failure_kind = excluded.failure_kind, failure_message = excluded.failure_message,
-        duration_ms = excluded.duration_ms, steps_json = excluded.steps_json
-    `).run(run.seq, idx, planned.name, planned.file, str(body.deviceId, MAX_NAME), str(body.deviceName, MAX_NAME), str(body.platform, 50), body.status, str(body.failureKind, 50), str(body.failureMessage, MAX_MESSAGE), durationMs, JSON.stringify(steps));
+        status = excluded.status, skip_reason = excluded.skip_reason, failure_kind = excluded.failure_kind,
+        failure_message = excluded.failure_message, duration_ms = excluded.duration_ms, steps_json = excluded.steps_json
+    `).run(run.seq, idx, planned.name, planned.file, str(body.deviceId, MAX_NAME), str(body.deviceName, MAX_NAME), str(body.platform, 50), body.status, skipReason ?? null, body.status === 'skipped' ? null : str(body.failureKind, 50), str(body.failureMessage, MAX_MESSAGE), durationMs, JSON.stringify(steps));
         db.prepare(`UPDATE flow_runs SET last_activity_at = datetime('now') WHERE seq = ?`).run(run.seq);
         return null;
     })();
@@ -302,6 +351,45 @@ export async function handleReportFlow(req, res, params) {
         return json(res, 404, { error: 'Run not found' });
     if (refusal === 'finished')
         return json(res, 409, { error: 'Run already finished' });
+    if (refusal === 'ran')
+        return json(res, 409, { error: 'This flow already ran; it cannot be reported as skipped' });
+    json(res, 200, { ok: true });
+}
+/**
+ * The runner started flow `idx` on a device. Without it the page could only guess the first unreported flow, which a
+ * run on several devices makes wrong: several flows run at once, and not in order. A start for a flow already
+ * reported changes nothing on the page, which reads a reported flow's row before this, so nothing here checks for one
+ * or forgets an entry when its flow reports; entries go with the run, and there are at most `flows_total`.
+ */
+export async function handleStartFlow(req, res, params) {
+    const run = ownRun(req, res, params.id);
+    if (!run)
+        return;
+    const idx = Number(params.idx);
+    if (!Number.isInteger(idx) || idx < 0 || idx >= run.flows_total)
+        return json(res, 404, { error: 'No such flow in this run' });
+    const body = await readJsonBody(req, res);
+    if (!body)
+        return;
+    const sessionId = str(body.sessionId, MAX_NAME);
+    if (sessionId === null)
+        return json(res, 400, { error: 'sessionId is required' });
+    const db = getDb();
+    // Judged after the body, as the flow report is: the run may have finished or gone while it arrived.
+    const now = db.prepare('SELECT status FROM flow_runs WHERE seq = ?').get(run.seq);
+    if (!now)
+        return json(res, 404, { error: 'Run not found' });
+    // A run the relay closed (`holder-lost`) still takes the runner's reports, as `ownRun` allows, but has nothing
+    // running to show; `ownRun` already refused one the runner finished itself.
+    if (now.status === 'running') {
+        let started = startedFlows.get(run.id);
+        if (!started) {
+            started = new Map();
+            startedFlows.set(run.id, started);
+        }
+        started.set(idx, { sessionId, deviceId: str(body.deviceId, MAX_NAME), deviceName: str(body.deviceName, MAX_NAME) });
+    }
+    db.prepare(`UPDATE flow_runs SET last_activity_at = datetime('now') WHERE seq = ?`).run(run.seq);
     json(res, 200, { ok: true });
 }
 const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
@@ -318,9 +406,13 @@ export async function handleUploadFlowScreenshot(req, res, params, screenshotsDi
     const run = ownRun(req, res, params.id);
     if (!run)
         return;
-    const current = getDb().prepare('SELECT screenshot_file FROM flow_run_flows WHERE run_seq = ? AND idx = ?');
-    if (!current.get(run.seq, Number(params.idx)))
+    const current = getDb().prepare('SELECT screenshot_file, status FROM flow_run_flows WHERE run_seq = ? AND idx = ?');
+    const row = current.get(run.seq, Number(params.idx));
+    if (!row)
         return json(res, 404, { error: 'Report the flow before its screenshot' });
+    // Nothing was on a screen for a flow that never ran.
+    if (row.status === 'skipped')
+        return json(res, 409, { error: 'A skipped flow has no screenshot' });
     const buf = await readBodyLimited(req, MAX_SCREENSHOT_BYTES);
     if (buf === null)
         return json(res, 413, { error: `Screenshot larger than ${MAX_SCREENSHOT_BYTES} bytes` });
@@ -345,6 +437,49 @@ export async function handleUploadFlowScreenshot(req, res, params, screenshotsDi
         unlinkSafe(path.join(screenshotsDir, before.screenshot_file), 'run screenshot');
     json(res, 200, { ok: true });
 }
+export async function handleReportDevice(req, res, params) {
+    const run = ownRun(req, res, params.id);
+    if (!run)
+        return;
+    const body = await readJsonBody(req, res);
+    if (!body)
+        return;
+    // A field that cannot be read is dropped rather than refused, as the create's are: recording never fails a run.
+    const report = readRunResetReport(body.runReset);
+    const cold = typeof body.cold === 'boolean' ? { cold: body.cold } : {};
+    const sessionId = str(body.sessionId, MAX_NAME);
+    const deviceId = str(body.deviceId, MAX_NAME);
+    const deviceName = str(body.deviceName, MAX_NAME);
+    const db = getDb();
+    // **Read inside the write, not from `run`**: that row was read before the body arrived, and the devices of a parallel
+    // run report at once, so merging into it would keep whichever report wrote last and lose the others.
+    const gone = db.transaction(() => {
+        const row = db.prepare('SELECT device_reset_json FROM flow_runs WHERE seq = ?').get(run.seq);
+        if (!row)
+            return true;
+        const before = row.device_reset_json ? JSON.parse(row.device_reset_json) : null;
+        const devices = [...(before?.devices ?? [])];
+        if (sessionId !== null) {
+            const device = {
+                sessionId, ...(deviceId !== null ? { deviceId } : {}), ...(deviceName !== null ? { deviceName } : {}), ...cold, ...(report ? { report } : {}),
+            };
+            const at = devices.findIndex((d) => d.sessionId === sessionId);
+            if (at >= 0)
+                devices[at] = device;
+            else
+                devices.push(device);
+        }
+        const first = sessionId === null || devices[0]?.sessionId === sessionId;
+        const next = first
+            ? { requested: before?.requested ?? false, booted: true, ...cold, ...(report ? { report } : {}), ...(devices.length > 0 ? { devices } : {}) }
+            : { ...before, devices };
+        db.prepare(`UPDATE flow_runs SET device_reset_json = ?, last_activity_at = datetime('now') WHERE seq = ?`).run(JSON.stringify(next), run.seq);
+        return false;
+    })();
+    if (gone)
+        return json(res, 404, { error: 'Run not found' });
+    json(res, 200, { ok: true });
+}
 const FINAL_STATUSES = new Set(['passed', 'failed', 'aborted']);
 export async function handleFinishRun(req, res, params) {
     const run = ownRun(req, res, params.id);
@@ -375,6 +510,7 @@ export async function handleFinishRun(req, res, params) {
             ? json(res, 409, { error: 'Run already finished' })
             : json(res, 404, { error: 'Run not found' });
     }
+    startedFlows.delete(run.id);
     json(res, 200, { ok: true });
 }
 function buildSummary(buildId) {
@@ -408,6 +544,8 @@ function runSummary(run) {
         ci: run.is_ci === 1
             ? { provider: run.ci_provider, branch: run.ci_branch, commit: run.ci_commit, jobUrl: run.ci_job_url }
             : null,
+        serviceTier: run.service_tier_json ? JSON.parse(run.service_tier_json) : null,
+        deviceReset: run.device_reset_json ? JSON.parse(run.device_reset_json) : null,
         build: buildSummary(run.build_id),
         createdBy: creatorName(run.created_by),
         flowsTotal: run.flows_total,
@@ -467,7 +605,8 @@ export function handleListRuns(req, res, holders) {
     const sql = (conds, order) => `
     SELECT r.*,
            (SELECT COUNT(*) FROM flow_run_flows f WHERE f.run_seq = r.seq AND f.status = 'passed') AS flows_passed,
-           (SELECT COUNT(*) FROM flow_run_flows f WHERE f.run_seq = r.seq AND f.status = 'failed') AS flows_failed
+           (SELECT COUNT(*) FROM flow_run_flows f WHERE f.run_seq = r.seq AND f.status = 'failed') AS flows_failed,
+           (SELECT COUNT(*) FROM flow_run_flows f WHERE f.run_seq = r.seq AND f.status = 'skipped') AS flows_skipped
       FROM flow_runs r
      ${conds.length ? `WHERE ${conds.join(' AND ')}` : ''}
      ORDER BY r.seq ${order}
@@ -484,7 +623,7 @@ export function handleListRuns(req, res, holders) {
     const first = page[0];
     const last = page[page.length - 1];
     json(res, 200, {
-        items: page.map((r) => ({ ...runSummary(r), flowsPassed: r.flows_passed, flowsFailed: r.flows_failed })),
+        items: page.map((r) => ({ ...runSummary(r), flowsPassed: r.flows_passed, flowsFailed: r.flows_failed, flowsSkipped: r.flows_skipped })),
         nextCursor: last && exists('r.seq < ?', last.seq) ? String(last.seq) : null,
         prevCursor: first && exists('r.seq > ?', first.seq) ? String(first.seq) : null,
     });
@@ -501,13 +640,28 @@ export function handleGetRun(req, res, params, holders, videosOf = () => new Map
         .map((f) => [f.idx, f]));
     const planned = JSON.parse(run.flows_json);
     const firstUnreported = planned.findIndex((_, i) => !reported.has(i));
+    if (run.status !== 'running')
+        startedFlows.delete(run.id);
+    const started = startedFlows.get(run.id);
     const flows = planned.map((p, idx) => {
         const f = reported.get(idx);
         if (!f) {
-            // Not reported yet: the first is the one running now, the rest are waiting — unless the run is over.
-            const status = run.status !== 'running' ? 'not-run' : idx === firstUnreported ? 'running' : 'pending';
+            if (run.status !== 'running')
+                return { idx, name: p.name, file: p.file, status: 'not-run', video: videos.get(idx) ?? null };
+            // A runner that reports starts says which flows are on a device. One that predates them leaves a guess: the
+            // first unreported flow is the one running, which holds while a run replays its flows one at a time.
+            const on = started?.get(idx);
+            if (on) {
+                const device = { id: on.deviceId, name: on.deviceName, sessionId: on.sessionId };
+                return { idx, name: p.name, file: p.file, status: 'running', device, video: videos.get(idx) ?? null };
+            }
+            const status = !started && idx === firstUnreported ? 'running' : 'pending';
             return { idx, name: p.name, file: p.file, status, video: videos.get(idx) ?? null };
         }
+        // A skipped flow never ran, so it has no device, steps, duration or screen to report.
+        if (f.status === 'skipped') {
+            return { idx, name: f.name, file: f.file, status: f.status, skipReason: f.skip_reason, failureMessage: f.failure_message, video: videos.get(idx) ?? null };
+        }
         return {
             idx, name: f.name, file: f.file, status: f.status,
             device: f.device_id ? { id: f.device_id, name: f.device_name, platform: f.platform } : null,
@@ -519,8 +673,8 @@ export function handleGetRun(req, res, params, holders, videosOf = () => new Map
     });
     // The session to watch is the one the holder holds **now**, never a stored one: session ids outlive runs,
     // so a stored id would open whoever took the device next.
-    const watchSessionId = run.status === 'running' ? holders.heldSession(holderKeys(run.created_by, run.holder_client)) : null;
-    json(res, 200, { ...runSummary(run), flows, watchSessionId });
+    const watchSessionIds = run.status === 'running' ? holders.heldSessions(holderKeys(run.created_by, run.holder_client)) : [];
+    json(res, 200, { ...runSummary(run), flows, watchSessionId: watchSessionIds[0] ?? null, watchSessionIds });
 }
 export function handleGetFlowScreenshot(req, res, params, screenshotsDir) {
     if (!requireViewAuth(req, res))
@@ -551,6 +705,7 @@ export function handleGetFlowScreenshot(req, res, params, screenshotsDir) {
 export function purgeExpiredRuns(screenshotsDir, videosDir, holders) {
     settleOrphanedRuns(holders);
     const db = getDb();
+    forgetStartedFlowsOfStoppedRuns();
     const expired = db.prepare(`
     SELECT seq FROM flow_runs WHERE build_id IS NULL AND delete_after IS NOT NULL AND delete_after < datetime('now')
   `).all();