opencode-codex-security 0.0.0-stage → 0.1.0

package/src/security-styles.ts

@@ -0,0 +1,10 @@
+/** Scoped CSS travels inside the supported single-file GUI bundle. */
+export const securityStyles = `
+.gill-security{--gs-bg:var(--background-base,#151515);--gs-panel:var(--background-raised,#202020);--gs-fg:var(--text-base,#eee);--gs-muted:var(--text-weak,#b5b5b5);--gs-line:var(--border-base,#454545);--gs-accent:#9be4c6;--gs-on-accent:#142b21;color:var(--gs-fg);background:var(--gs-bg);font-size:13px;line-height:1.5;font-family:inherit;height:100%;overflow:auto;container-type:inline-size;scrollbar-color:var(--gs-line) transparent;scrollbar-width:thin}
+.gill-security *{box-sizing:border-box}.gill-security ::selection{background:#35634f;color:#fff}.gill-security button,.gill-security input,.gill-security textarea,.gill-security select{font:inherit;color:inherit}.gill-security button{cursor:pointer}.gill-security button:disabled{opacity:.45;cursor:not-allowed}.gill-security :focus-visible{outline:2px solid var(--gs-accent);outline-offset:3px}.gill-security input,.gill-security textarea{caret-color:var(--gs-accent)}
+.gs-workspace{font-size:12px;color:var(--gs-muted);margin:0 0 20px}.gs-workspace>summary{cursor:pointer}.gs-workspace p{margin:8px 0;overflow-wrap:anywhere}.gs-run-target{font-size:12px;color:var(--gs-muted);margin-top:4px;overflow-wrap:anywhere}.gs-body{padding:24px;max-width:900px;margin:auto}.gs-header{display:flex;justify-content:space-between;align-items:center;gap:16px;margin-bottom:24px}.gs-header h2{font-size:20px;font-weight:600;margin:0;letter-spacing:-.025em}.gs-muted{color:var(--gs-muted)}.gs-small{font-size:12px}.gs-header p{margin:3px 0 0;font-size:12px}.gs-button{padding:8px 13px;border:1px solid var(--gs-line);border-radius:6px;background:transparent;line-height:1.4;white-space:nowrap}.gs-button:hover:not(:disabled){background:var(--gs-panel)}.gs-button.gs-primary{background:var(--gs-accent);border-color:transparent;color:var(--gs-on-accent);font-weight:600}.gs-button.gs-primary:hover:not(:disabled){filter:brightness(1.08)}.gs-link{border:0;background:none;padding:4px 0;color:var(--gs-muted)!important;text-decoration:underline;text-underline-offset:3px}.gs-actions{display:flex;gap:8px;align-items:center;flex-wrap:wrap;margin-top:16px}.gs-notice{padding:10px 12px;border:1px solid var(--gs-line);border-radius:6px;font-size:12px;margin-bottom:18px}.gs-error{color:#ffb3b3;border-color:#985353;overflow-wrap:anywhere}.gs-form{padding-bottom:24px;margin-bottom:24px;border-bottom:1px solid var(--gs-line)}.gs-form h3,.gs-detail h3{font-size:15px;font-weight:600;margin:0 0 12px}.gs-form label{display:block;font-size:12px;font-weight:500;margin-bottom:14px}.gs-form input,.gs-form textarea,.gs-form select{display:block;width:100%;margin-top:6px;background:var(--gs-panel);border:1px solid var(--gs-line);padding:9px 10px;border-radius:5px;line-height:1.5}.gs-form textarea{resize:vertical;min-height:68px}.gs-form input::placeholder,.gs-form textarea::placeholder{color:var(--gs-muted)}.gs-form .gs-help{display:block;font-weight:400;color:var(--gs-muted);font-size:12px;margin-top:5px}.gs-row{display:flex;align-items:flex-start;gap:12px}.gs-row>*{flex:1;min-width:0}.gs-form details{margin:16px 0}.gs-form summary,.gs-detail summary{cursor:pointer;color:var(--gs-muted);padding:4px 0}.gs-form details[open]>summary,.gs-detail details[open]>summary{margin-bottom:12px}.gs-review{border:1px solid var(--gs-line);padding:16px;border-radius:8px}.gs-review dl,.gs-details-list{margin:0}.gs-review dt,.gs-details-list dt{color:var(--gs-muted);font-size:12px;margin-top:12px}.gs-review dt:first-child,.gs-details-list dt:first-child{margin-top:0}.gs-review dd,.gs-details-list dd{margin:3px 0 0;overflow-wrap:anywhere}.gs-review p{margin:12px 0 0}.gs-review .gs-approval{border-top:1px solid var(--gs-line);padding-top:12px;margin-top:16px;font-size:12px;color:var(--gs-muted)}.gs-section-heading{display:flex;align-items:center;justify-content:space-between;gap:10px;margin-bottom:8px}.gs-section-heading h3{font-size:13px;margin:0;font-weight:600}.gs-section-heading span{color:var(--gs-muted);font-size:12px}.gs-runs{margin-bottom:28px;font-size:12px}.gs-runs>summary{cursor:pointer;color:var(--gs-muted);padding:0 0 12px;border-bottom:1px solid var(--gs-line)}.gs-runs>summary span{float:right}.gs-runs[open]>summary{margin-bottom:8px}.gs-run-list{list-style:none;padding:0;margin:0;max-height:240px;overflow:auto;scrollbar-width:thin}.gs-run-list li{border-bottom:1px solid var(--gs-line)}.gs-run-button{display:block;background:none;border:0;border-radius:4px;text-align:left;padding:12px 10px;width:100%;color:inherit}.gs-run-button:hover{background:var(--gs-panel)}.gs-run-button[aria-pressed=true]{background:var(--gs-panel);box-shadow:inset 2px 0 var(--gs-accent)}.gs-run-top{display:flex;justify-content:space-between;align-items:baseline;gap:12px}.gs-run-title{font-size:13px;font-weight:500;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;min-width:0}.gs-run-meta{font-size:12px;color:var(--gs-muted);margin-top:4px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.gs-status{font-size:11px;white-space:nowrap;flex-shrink:0;color:var(--gs-muted);text-transform:capitalize}.gs-status[data-status=running]{color:var(--gs-accent)}.gs-status[data-status=error]{color:#ffb3b3}.gs-detail{padding-top:0}.gs-detail-title{margin-bottom:24px}.gs-detail-title h3{margin:0;font-size:14px;line-height:1.5;font-weight:500;overflow-wrap:anywhere}.gs-detail-title p{margin:4px 0 0;overflow-wrap:anywhere;font-size:12px;color:var(--gs-muted)}.gs-progress-heading{display:flex;justify-content:space-between;align-items:baseline;gap:16px;margin:0 0 12px}.gs-progress-heading h3{font-size:24px;line-height:1.25;font-weight:600;letter-spacing:-.025em;margin:0}.gs-progress-heading span{font-size:12px;color:var(--gs-muted);font-variant-numeric:tabular-nums}.gs-progress{appearance:none;width:100%;height:6px;border:0;display:block;margin:16px 0 10px;background:var(--gs-line);border-radius:2px;overflow:hidden}.gs-progress::-webkit-progress-bar{background:var(--gs-line)}.gs-progress::-webkit-progress-value{background:var(--gs-accent)}.gs-progress::-moz-progress-bar{background:var(--gs-accent)}.gs-progress-meta{display:flex;justify-content:space-between;gap:10px;flex-wrap:wrap;color:var(--gs-muted);font-size:12px}.gs-live-note{margin:24px 0;max-width:64ch;font-size:13px}.gs-scan-actions{display:flex;align-items:center;justify-content:space-between;gap:12px;flex-wrap:wrap;margin-top:16px;font-variant-numeric:tabular-nums}.gs-activity{margin:0;font-size:12px}.gs-activity-list{padding:0;margin:8px 0 0;list-style:none;max-height:220px;overflow:auto;scrollbar-width:thin}.gs-activity-list li{display:flex;gap:12px;align-items:baseline;padding:6px 0;font-size:12px;overflow-wrap:anywhere}.gs-activity-list time{color:var(--gs-muted);font-variant-numeric:tabular-nums;white-space:nowrap;flex-shrink:0}.gs-activity-list li:first-child{color:var(--gs-fg)}.gs-findings{margin:28px 0 24px}.gs-findings .gs-section-heading h3{font-size:18px}.gs-findings details{padding:12px 0;border-bottom:1px solid var(--gs-line)}.gs-findings summary{color:var(--gs-fg);padding:0}.gs-severity{font-size:11px;text-transform:uppercase;margin-right:8px;color:#ebc28c}.gs-severity[data-severity=critical],.gs-severity[data-severity=high]{color:#ffb3b3}.gs-findings p{font-size:13px;margin:12px 0}.gs-findings pre{font:12px/1.6 ui-monospace,SFMono-Regular,Menlo,monospace;white-space:pre-wrap;overflow-wrap:anywhere;padding:12px;background:var(--gs-panel);border-radius:5px;max-height:280px;overflow:auto}.gs-finding-location{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:11px;color:var(--gs-muted);overflow-wrap:anywhere;margin:6px 0}.gs-empty{padding:22px 0;color:var(--gs-muted);font-size:13px}.gs-empty h3{color:var(--gs-fg);margin:0 0 6px;font-size:15px}.gs-empty p{margin:0;max-width:48ch}.gs-footer{font-size:11px;color:var(--gs-muted);margin-top:24px}.gs-advanced{margin-top:0;font-size:12px}.gs-detail>.gs-advanced,.gs-detail>.gs-activity,.gs-coverage{border-top:1px solid var(--gs-line)}.gs-detail>.gs-advanced>summary,.gs-detail>.gs-activity>summary,.gs-coverage>summary{padding:14px 0;color:var(--gs-fg)}.gs-detail>.gs-advanced[open],.gs-detail>.gs-activity[open],.gs-coverage[open]{padding-bottom:16px}.gs-advanced pre{white-space:pre-wrap;overflow-wrap:anywhere;font:11px/1.6 ui-monospace,SFMono-Regular,Menlo,monospace}.gs-pending{display:flex;align-items:center;justify-content:space-between;gap:12px;padding:12px 0;margin-bottom:16px;border-bottom:1px solid var(--gs-line);font-size:12px}.gs-workers{font-size:12px;color:var(--gs-muted);padding:0;list-style:none}.gs-workers li{padding:3px 0}.gs-id{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:11px;overflow-wrap:anywhere}
+.gs-tabs{display:flex;gap:20px;border-bottom:1px solid var(--gs-line);margin:-4px 0 24px}.gs-tabs button{border:0;background:none;padding:8px 0 12px;color:var(--gs-muted);font-weight:500}.gs-tabs button[aria-current=page]{color:var(--gs-fg);border-bottom:2px solid var(--gs-accent)}.gs-check{display:flex!important;align-items:flex-start;gap:8px;font-size:12px!important;margin-top:16px}.gs-check input{width:auto!important;margin-top:4px!important}.gs-questions{margin-top:20px}.gs-questions li{margin-bottom:8px}.gs-operation-result{margin-top:22px}.gs-operation-result pre{white-space:pre-wrap;overflow-wrap:anywhere;background:var(--gs-panel);padding:14px;border-radius:6px;max-height:440px;overflow:auto;font:12px/1.65 ui-monospace,SFMono-Regular,Menlo,monospace}
+.gs-worker-activity{list-style:none;padding:0;margin:8px 0}.gs-worker-activity li{display:flex;justify-content:space-between;align-items:baseline;gap:16px;padding:9px 0;border-bottom:1px solid var(--gs-line);font-size:12px}.gs-activity-copy{display:flex;gap:12px;min-width:0;overflow-wrap:anywhere}.gs-activity-actor{color:var(--gs-muted);flex-shrink:0;min-width:78px}.gs-activity-state{color:var(--gs-muted);font-size:11px;text-align:right;flex-shrink:0}.gs-activity-state[data-status=failed]{color:#ffb3b3}.gs-activity-history{margin-top:12px;font-size:12px}.gs-activity-paths{display:block;color:var(--gs-muted);font-size:11px;overflow-wrap:anywhere}.gs-outcome{margin-top:24px}.gs-outcome-summary{font-size:12px;color:var(--gs-muted);margin:0 0 16px}.gs-coverage{font-size:12px;margin:0}.gs-coverage ul{padding-left:18px;margin:8px 0}.gs-coverage li{margin:5px 0}
+@container(max-width:440px){.gs-body{padding:18px 16px}.gs-row{display:block}.gs-run-top{gap:8px}.gs-header{gap:10px}.gs-header h2{font-size:18px}.gs-run-title{max-width:65%}.gs-activity-copy{flex-direction:column;gap:2px}.gs-worker-activity li{gap:8px}.gs-activity-state{max-width:110px}.gs-progress-heading{align-items:flex-start}.gs-progress-heading h3{font-size:22px}.gs-progress-heading span{white-space:nowrap}}
+@media(prefers-reduced-motion:no-preference){.gs-detail{animation:gs-appear .15s ease-out}@keyframes gs-appear{from{opacity:.85}to{opacity:1}}}
+`;

package/src/security-tui-operations.tsx

@@ -0,0 +1,343 @@
+/** @jsxImportSource @opentui/solid */
+import type { Plugin } from '@opencode/plugin/tui';
+type Context = Plugin.Context;
+type Commands = NonNullable<ReturnType<Parameters<Context['keymap']['layer']>[0]>['commands']>;
+import { createSignal, For, Show } from 'solid-js';
+import { Security } from './rpc';
+import type { SecurityOperationState } from './core/security-operations';
+import type { ScanState } from './types';
+import { findingText, phaseLabel, userError } from './scan-display';
+
+export function createTuiOperations(
+  ctx: Context,
+  location: { directory: string },
+  scan: () => ScanState | undefined,
+  open: () => void,
+  chooseTarget: () => Promise<string | undefined>,
+) {
+  const client = ctx.client.rpc(Security);
+  const [operations, setOperations] = createSignal<SecurityOperationState[]>([]);
+  const [selected, select] = createSignal<string>();
+  const [visible, setVisible] = createSignal(false);
+  const [busy, setBusy] = createSignal(false);
+  const [error, setError] = createSignal('');
+  const [capabilities, setCapabilities] = createSignal({
+    policy: false,
+    validation: false,
+    questionAnswers: false,
+  });
+  let stopped = false;
+  const current = () => operations().find((op) => op.operationId === selected()) ?? operations()[0];
+  const refresh = async () => {
+    if (stopped || (!capabilities().policy && !capabilities().validation)) return;
+    try {
+      const result = (await client.operationList({}, { location })) as unknown as {
+        operations: SecurityOperationState[];
+      };
+      if (!stopped) setOperations(result.operations);
+    } catch (e) {
+      if (!stopped && visible()) setError(userError(e));
+    }
+  };
+  void client
+    .capabilities({}, { location })
+    .then((value) => {
+      if (!stopped)
+        setCapabilities(value as unknown as typeof capabilities extends () => infer T ? T : never);
+    })
+    .catch(() => {});
+  const perform = async (action: () => Promise<unknown>) => {
+    if (stopped || busy()) return;
+    setBusy(true);
+    setError('');
+    try {
+      await action();
+      if (!stopped) await refresh();
+    } catch (e) {
+      if (!stopped) setError(userError(e));
+    } finally {
+      if (!stopped) setBusy(false);
+    }
+  };
+  const show = () => {
+    setVisible(true);
+    open();
+  };
+  const approve = async (op: SecurityOperationState) => {
+    const confirmed = await ctx.ui.dialog.confirm({
+      title: op.kind === 'policy' ? 'Review policy generation' : 'Review source validation',
+      message: `Repository: ${op.repository}\n${op.plan.path ? 'Component: ' + op.plan.path + '\n' : ''}Context: ${op.plan.contextFiles.map((file) => file.path).join(', ') || 'No additional documents'}\n\n${op.plan.mock ? 'Mock operation: no model calls or uploads.' : `Repository source, the selected finding if any, and listed context go to OpenAI.\n${op.plan.costNotice}`}\n\n${op.kind === 'policy' ? 'Returns a draft only. Existing files stay unchanged.' : 'Static source assessment only. No exploit execution or patch application.'}\n\nModel: ${op.plan.settings.codex.model} · ${op.plan.settings.codex.reasoningEffort} reasoning`,
+      label: {
+        confirm: op.plan.mock
+          ? 'Start mock operation'
+          : op.kind === 'validation'
+            ? 'Approve without cost ceiling'
+            : 'Approve and start',
+        cancel: 'Back',
+      },
+    });
+    if (!confirmed || stopped) return;
+    await client.operationStart(
+      {
+        operationId: op.operationId,
+        approveOpenAIInference: true,
+        ...(op.kind === 'validation' ? { approveUncappedValidation: true } : {}),
+      },
+      { location },
+    );
+  };
+  const commands: Commands = [
+    {
+      id: 'security.policy',
+      title: 'Security: draft a policy',
+      group: 'Security',
+      palette: true,
+      enabled: () => capabilities().policy,
+      slash: { name: 'security-policy' },
+      run: async () => {
+        show();
+        await perform(async () => {
+          const repository = await chooseTarget();
+          if (!repository || stopped) return;
+          const path = await ctx.ui.dialog.prompt({
+            title: 'Policy component',
+            description: `Target: ${repository}. Repository-relative directory, or leave blank for the whole project. Preparation makes no model calls.`,
+            placeholder: 'src/api',
+          });
+          if (path === undefined || stopped) return;
+          const op = (await client.operationPrepare(
+            { kind: 'policy', repository, ...(path.trim() ? { path: path.trim() } : {}) },
+            { location },
+          )) as unknown as SecurityOperationState;
+          select(op.operationId);
+          await refresh();
+          await approve(op);
+        });
+      },
+    },
+    {
+      id: 'security.validate',
+      title: 'Security: validate a finding',
+      group: 'Security',
+      palette: true,
+      enabled: () => capabilities().validation,
+      slash: { name: 'security-validate' },
+      run: async () => {
+        show();
+        await perform(async () => {
+          const source = scan();
+          let finding: string | undefined;
+          let repository: string | undefined;
+          if (source?.findings.length) {
+            const id = await ctx.ui.dialog.select({
+              title: `Finding to validate · ${source.repository}`,
+              options: source.findings.map((f) => ({
+                title: `${f.severity.toUpperCase()} ${f.title}`,
+                description: `${f.path}:${f.line}`,
+                value: f.id,
+              })),
+            });
+            if (!id) return;
+            finding = findingText(source.findings.find((f) => f.id === id)!);
+            repository = source.repository;
+          } else {
+            repository = await chooseTarget();
+            if (!repository || stopped) return;
+            finding = await ctx.ui.dialog.prompt({
+              title: 'Finding to validate',
+              description: `Target: ${repository}. Describe the suspected issue, source location and evidence. Do not include secrets. Validation has no SDK cost ceiling.`,
+            });
+          }
+          if (!finding?.trim() || stopped) return;
+          const op = (await client.operationPrepare(
+            { kind: 'validation', repository, finding },
+            { location },
+          )) as unknown as SecurityOperationState;
+          select(op.operationId);
+          await refresh();
+          await approve(op);
+        });
+      },
+    },
+    {
+      id: 'security.operations',
+      title: 'Security: choose policy or validation work',
+      group: 'Security',
+      palette: true,
+      enabled: () => capabilities().policy || capabilities().validation,
+      slash: { name: 'security-operations' },
+      run: async () => {
+        show();
+        await refresh();
+        if (!operations().length) {
+          await ctx.ui.dialog.alert({
+            title: 'Security operations',
+            message:
+              'No policy or validation work yet. Use /security-policy or /security-validate to prepare one.',
+          });
+          return;
+        }
+        const id = await ctx.ui.dialog.select({
+          title: 'Choose an operation',
+          current: current()?.operationId,
+          options: operations().map((op) => ({
+            title: `${op.kind === 'policy' ? 'Policy' : 'Validation'} · ${phaseLabel(op.status)}`,
+            description: `${op.repository} · ${op.operationId.slice(0, 8)}`,
+            value: op.operationId,
+          })),
+        });
+        if (id && !stopped) select(id);
+      },
+    },
+    {
+      id: 'security.operationStart',
+      title: 'Security: review selected prepared operation',
+      group: 'Security',
+      palette: true,
+      enabled: () => current()?.status === 'prepared',
+      slash: { name: 'security-operation-start' },
+      run: async () => {
+        const op = current();
+        if (op) await perform(() => approve(op));
+      },
+    },
+    {
+      id: 'security.answer',
+      title: 'Security: answer policy questions',
+      group: 'Security',
+      palette: true,
+      enabled: () => !!current()?.question,
+      slash: { name: 'security-answer' },
+      run: async () => {
+        const op = current(),
+          question = op?.question;
+        if (!op || !question) return;
+        show();
+        await perform(async () => {
+          const answer = await ctx.ui.dialog.prompt({
+            title: 'Answer security questions',
+            description:
+              question.questions.map((q, index) => `${index + 1}. ${q}`).join('\n') +
+              '\n\nAnswer each question or state what is unknown. Your answer will be sent to OpenAI for this operation; do not include secrets.',
+          });
+          if (!answer?.trim() || stopped) return;
+          await client.operationAnswer(
+            { operationId: op.operationId, questionId: question.id, answer },
+            { location },
+          );
+        });
+      },
+    },
+    {
+      id: 'security.operationCancel',
+      title: 'Security: cancel selected operation',
+      group: 'Security',
+      palette: true,
+      enabled: () => ['prepared', 'running', 'awaiting_answers'].includes(current()?.status ?? ''),
+      slash: { name: 'security-operation-cancel' },
+      run: async () => {
+        const op = current();
+        if (op)
+          await perform(() =>
+            client.operationCancel({ operationId: op.operationId }, { location }),
+          );
+      },
+    },
+    {
+      id: 'security.operationResult',
+      title: 'Security: read operation result',
+      group: 'Security',
+      palette: true,
+      enabled: () => !!current()?.result,
+      slash: { name: 'security-operation-result' },
+      run: async () => {
+        const op = current(),
+          result = op?.result;
+        if (!result) return;
+        await ctx.ui.dialog.alert({
+          title:
+            result.kind === 'policy'
+              ? 'Policy draft · not applied'
+              : `Source assessment · ${phaseLabel(result.disposition)}`,
+          message:
+            (result.kind === 'policy'
+              ? result.content + '\n\nReview notes:\n' + result.reviewNotes.join('\n')
+              : result.report) +
+            '\n\n' +
+            (result.truncated
+              ? 'Preview truncated. Read full local SDK artifacts.'
+              : result.kind === 'policy'
+                ? 'No repository files changed.'
+                : 'Static assessment, not runtime reproduction.'),
+        });
+      },
+    },
+  ];
+  const view = () => (
+    <box flexDirection="column" gap={1}>
+      <text>/security-operations: choose work · /security: return to scans</text>
+      <Show when={error()}>
+        <text fg="#ffb3b3">{error()}</text>
+      </Show>
+      <Show
+        when={current()}
+        fallback={
+          <text>
+            Prepare a policy draft with /security-policy or assess a finding with
+            /security-validate.
+          </text>
+        }
+      >
+        {(op) => (
+          <box flexDirection="column" gap={1}>
+            <text fg="#9be4c6">
+              {op().kind === 'policy' ? 'Policy draft' : 'Finding validation'} ·{' '}
+              {phaseLabel(op().status)}
+            </text>
+            <text>Target: {op().repository}</text>
+            <text>{op().phase}</text>
+            <Show when={op().status === 'prepared'}>
+              <text>/security-operation-start to review this operation before starting.</text>
+            </Show>
+            <Show when={op().question}>
+              {(q) => (
+                <box flexDirection="column">
+                  <text>Your input is needed. /security-answer to respond.</text>
+                  <For each={q().questions}>{(text) => <text>{text}</text>}</For>
+                </box>
+              )}
+            </Show>
+            <Show when={op().estimatedCostUsd !== undefined}>
+              <text>Estimated usage: USD {(op().estimatedCostUsd ?? 0).toFixed(2)}</text>
+            </Show>
+            <Show when={op().error}>
+              <text fg="#ffb3b3">{op().error}</text>
+            </Show>
+            <Show when={op().result}>
+              <text>
+                /security-operation-result to read{' '}
+                {op().kind === 'policy'
+                  ? 'the draft. No files have been applied.'
+                  : 'the static assessment. This is not runtime reproduction.'}
+              </text>
+            </Show>
+            <Show when={op().status === 'running' || op().status === 'awaiting_answers'}>
+              <text>/security-operation-cancel stops only this operation.</text>
+            </Show>
+          </box>
+        )}
+      </Show>
+    </box>
+  );
+  return {
+    commands,
+    view,
+    visible,
+    close: () => setVisible(false),
+    refresh,
+    questionCount: () => operations().filter((op) => op.status === 'awaiting_answers').length,
+    dispose: () => {
+      stopped = true;
+    },
+  };
+}

package/src/state-order.ts

@@ -0,0 +1,21 @@
+import type { ScanState } from './types.js';
+/** Revisions are scoped to one server instance, never compared across restarts. */
+export class SnapshotOrder {
+  #instance = '';
+  #revision = -1;
+  #retired = new Set<string>();
+  accept(next: ScanState, authoritative = false): boolean {
+    if (!next.instanceId || this.#retired.has(next.instanceId)) return false;
+    if (next.instanceId !== this.#instance) {
+      // Only an RPC snapshot establishes a new epoch. Late/disconnected events
+      // cannot replace a current instance; the next poll reconciles new events.
+      if (!authoritative && this.#instance) return false;
+      if (this.#instance) this.#retired.add(this.#instance);
+      this.#instance = next.instanceId;
+      this.#revision = -1;
+    }
+    if (next.revision < this.#revision) return false;
+    this.#revision = next.revision;
+    return true;
+  }
+}