opencode-codex-security 0.0.0-stage → 0.1.0

package/src/core/run-telemetry.ts

@@ -0,0 +1,359 @@
+import { createHash } from 'node:crypto';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import type { ScanOptions } from '@openai/codex-security';
+import { safeReportText } from './report-safety.ts';
+
+type CallbackValue<K extends keyof ScanOptions> = Parameters<
+  NonNullable<ScanOptions[K]> extends (...args: infer A) => unknown
+    ? (...args: A) => unknown
+    : never
+>[0];
+export interface ScanActivityEntry {
+  id: string;
+  kind: 'command' | 'tool' | 'reasoning' | 'message';
+  status: 'running' | 'completed' | 'failed';
+  label: string;
+  paths: string[];
+  worker?: number;
+  startedAt: string;
+  updatedAt: string;
+}
+export interface ScanMeasurement {
+  coverage: 'complete' | 'partial' | 'unavailable';
+  observedAt: string;
+  threadCount?: number;
+  missingThreadCount?: number;
+  usage?: {
+    inputTokens: number;
+    cachedInputTokens: number;
+    outputTokens: number;
+    reasoningOutputTokens: number;
+    totalTokens: number;
+  };
+  cost?: {
+    baselineUsd: number;
+    range?: { min: number; max: number | null };
+    model?: string;
+    pricingAsOf?: string;
+    pricingSource?: string;
+  };
+}
+export interface ScanTelemetry {
+  activity: ScanActivityEntry[];
+  observedWorkers: number[];
+  lifecycle?: {
+    status: 'running' | 'completed' | 'failed' | 'canceled';
+    hasReportableFindings: boolean | null;
+    finishedAt: string | null;
+  };
+  phaseProgress?: {
+    phase: string;
+    files: { done: number; total: number };
+    reviews?: { done: number; total: number };
+  };
+  measurement?: ScanMeasurement;
+  lastReconnect?: {
+    attempt: number;
+    maxAttempts: number;
+    reason?: 'rate_limit' | 'network' | 'authentication' | 'authorization';
+    retryAfterSeconds?: number;
+    at: string;
+  };
+}
+const finite = (n: unknown): n is number => typeof n === 'number' && Number.isFinite(n) && n >= 0;
+export const count = (n: unknown) =>
+  finite(n) ? Math.min(Math.floor(n), Number.MAX_SAFE_INTEGER) : 0;
+const timestamp = (value: unknown, fallback: string) =>
+  typeof value === 'string' && Number.isFinite(Date.parse(value))
+    ? new Date(value).toISOString()
+    : fallback;
+export const emptyTelemetry = (): ScanTelemetry => ({ activity: [], observedWorkers: [] });
+
+/** Mentioned repository paths only; never expose command arguments or outside/credential paths. */
+export function safeActivityPaths(values: unknown, repository: string): string[] {
+  if (!Array.isArray(values)) return [];
+  return [
+    ...new Set(
+      values.slice(0, 8).flatMap((value) => {
+        if (
+          typeof value !== 'string' ||
+          value.length > 1000 ||
+          safeReportText(value) !== value ||
+          value.includes('\\') ||
+          /[\r\n\t\u202a-\u202e\u2066-\u2069]/.test(value)
+        )
+          return [];
+        const path = relative(resolve(repository), resolve(repository, value));
+        if (!path || path === '..' || path.startsWith('..' + sep) || isAbsolute(path)) return [];
+        const parts = path.split(sep);
+        if (
+          parts.some(
+            (part) =>
+              [
+                '.git',
+                '.ssh',
+                '.aws',
+                '.codex',
+                '.runtime',
+                'node_modules',
+                'auth.json',
+                'credentials.json',
+                'id_rsa',
+                'id_ed25519',
+              ].includes(part) || /^\.env(?:\.|$)/.test(part),
+          )
+        )
+          return [];
+        return [parts.join('/')];
+      }),
+    ),
+  ];
+}
+function activityLabel(kind: ScanActivityEntry['kind'], description: string): string {
+  // Raw descriptions include commands, arguments and reasoning. Extract only a fixed category.
+  if (kind === 'reasoning') return 'Analysis update';
+  if (kind === 'message') return 'Scan update';
+  const executable = /^\s*(?:\/(?:usr\/)?bin\/)?([a-z][a-z0-9_-]*)(?:\s|$)/i
+    .exec(description)?.[1]
+    ?.toLowerCase();
+  if (['rg', 'grep'].includes(executable ?? '')) return 'Searching source';
+  if (['cat', 'sed', 'head', 'tail', 'read_file'].includes(executable ?? ''))
+    return 'Reading source';
+  if (['ls', 'find', 'list_files'].includes(executable ?? '')) return 'Listing files';
+  if (executable === 'git') return 'Repository command';
+  return kind === 'tool' ? 'Tool call' : 'Command';
+}
+export function recordActivity(
+  telemetry: ScanTelemetry,
+  value: CallbackValue<'onActivity'>,
+  repository: string,
+  now = new Date().toISOString(),
+): void {
+  if (
+    !value ||
+    typeof value.id !== 'string' ||
+    !['command', 'tool', 'reasoning', 'message'].includes(value.kind) ||
+    !['running', 'completed', 'failed'].includes(value.status)
+  )
+    return;
+  const worker = finite(value.worker) ? count(value.worker) : undefined;
+  // Some SDK activity IDs contain raw prose. Hash before storage or any presentation.
+  const id = createHash('sha256')
+    .update(`${worker ?? 'coordinator'}:${value.kind}:${value.id}`)
+    .digest('hex')
+    .slice(0, 24);
+  const previous = telemetry.activity.find((item) => item.id === id);
+  if (previous && previous.status !== 'running' && value.status === 'running') return;
+  const item: ScanActivityEntry = {
+    id,
+    kind: value.kind,
+    status: value.status,
+    label: activityLabel(value.kind, value.description ?? ''),
+    paths: safeActivityPaths(value.paths, repository),
+    ...(worker === undefined ? {} : { worker }),
+    startedAt: previous?.startedAt ?? now,
+    updatedAt: now,
+  };
+  if (previous) telemetry.activity[telemetry.activity.indexOf(previous)] = item;
+  else telemetry.activity.push(item);
+  telemetry.activity = telemetry.activity.slice(-100);
+}
+export function costSummary(value: CallbackValue<'onCost'>): ScanMeasurement['cost'] {
+  if (!value || !finite(value.estimatedUsd)) return;
+  const range = value.estimatedUsdRange;
+  return {
+    baselineUsd: value.estimatedUsd,
+    ...(range &&
+    finite(range.min) &&
+    (range.max === null || (finite(range.max) && range.max >= range.min))
+      ? { range: { min: range.min, max: range.max } }
+      : {}),
+    model: safeReportText(value.model, 200),
+    ...(value.pricing?.asOf ? { pricingAsOf: safeReportText(value.pricing.asOf, 40) } : {}),
+    ...(value.pricing?.source === 'https://developers.openai.com/api/docs/pricing'
+      ? { pricingSource: value.pricing.source }
+      : {}),
+  };
+}
+export function measurementSummary(
+  value: CallbackValue<'onMeasurement'>,
+  now = new Date().toISOString(),
+): ScanMeasurement {
+  const usage = value.usage;
+  return {
+    coverage: ['complete', 'partial', 'unavailable'].includes(value.coverage)
+      ? value.coverage
+      : 'unavailable',
+    observedAt: timestamp(value.observedAt, now),
+    threadCount: count(value.threadCount),
+    missingThreadCount: count(value.missingThreadCount),
+    ...(usage &&
+    [
+      usage.input_tokens,
+      usage.cached_input_tokens,
+      usage.output_tokens,
+      usage.reasoning_output_tokens,
+      usage.total_tokens,
+    ].every(finite)
+      ? {
+          usage: {
+            inputTokens: count(usage.input_tokens),
+            cachedInputTokens: count(usage.cached_input_tokens),
+            outputTokens: count(usage.output_tokens),
+            reasoningOutputTokens: count(usage.reasoning_output_tokens),
+            totalTokens: count(usage.total_tokens),
+          },
+        }
+      : {}),
+    ...(value.cost ? { cost: costSummary(value.cost) } : {}),
+  };
+}
+export function lifecycleSummary(value: CallbackValue<'onLifecycle'>): ScanTelemetry['lifecycle'] {
+  if (!['running', 'completed', 'failed', 'canceled'].includes(value.status)) return;
+  return {
+    status: value.status,
+    hasReportableFindings:
+      typeof value.hasReportableFindings === 'boolean' ? value.hasReportableFindings : null,
+    finishedAt: value.finishedAt ? timestamp(value.finishedAt, '') || null : null,
+  };
+}
+export function phaseSummary(
+  value: CallbackValue<'onProgress'>,
+): NonNullable<ScanTelemetry['phaseProgress']> {
+  return {
+    phase: [
+      'preflight',
+      'threat_model',
+      'discovery',
+      'validation',
+      'attack_path',
+      'reporting',
+    ].includes(value.phase)
+      ? value.phase
+      : 'unknown',
+    files: { done: count(value.filesCompleted), total: count(value.filesTotal) },
+    ...(value.reviewItems
+      ? {
+          reviews: {
+            done: count(value.reviewItems.completed),
+            total: count(value.reviewItems.total),
+          },
+        }
+      : {}),
+  };
+}
+
+/** Restore only our projected schema, never arbitrary extra fields from a local JSON record. */
+export function sanitizeStoredTelemetry(
+  value: unknown,
+  repository: string,
+): ScanTelemetry | undefined {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return;
+  const stored = value as Partial<ScanTelemetry>,
+    output = emptyTelemetry();
+  const labels = [
+    'Analysis update',
+    'Scan update',
+    'Searching source',
+    'Reading source',
+    'Listing files',
+    'Repository command',
+    'Tool call',
+    'Command',
+  ];
+  for (const item of Array.isArray(stored.activity) ? stored.activity.slice(-100) : []) {
+    if (
+      !item ||
+      !/^[a-f0-9]{24}$/.test(item.id) ||
+      !['command', 'tool', 'reasoning', 'message'].includes(item.kind) ||
+      !['running', 'completed', 'failed'].includes(item.status)
+    )
+      continue;
+    const startedAt = timestamp(item.startedAt, '');
+    const updatedAt = timestamp(item.updatedAt, '');
+    if (!startedAt || !updatedAt) continue;
+    output.activity.push({
+      id: item.id,
+      kind: item.kind,
+      status: item.status,
+      label: labels.includes(item.label) ? item.label : activityLabel(item.kind, ''),
+      paths: safeActivityPaths(item.paths, repository),
+      ...(finite(item.worker) ? { worker: count(item.worker) } : {}),
+      startedAt,
+      updatedAt,
+    });
+  }
+  output.observedWorkers = [
+    ...new Set(
+      (Array.isArray(stored.observedWorkers) ? stored.observedWorkers : [])
+        .filter(finite)
+        .map(count),
+    ),
+  ].slice(0, 128);
+  if (stored.lifecycle)
+    output.lifecycle = lifecycleSummary(stored.lifecycle as CallbackValue<'onLifecycle'>);
+  const progress = stored.phaseProgress;
+  if (progress && typeof progress === 'object')
+    output.phaseProgress = phaseSummary({
+      phase: progress.phase,
+      filesCompleted: progress.files?.done,
+      filesTotal: progress.files?.total,
+      ...(progress.reviews
+        ? { reviewItems: { completed: progress.reviews.done, total: progress.reviews.total } }
+        : {}),
+    } as CallbackValue<'onProgress'>);
+  const m = stored.measurement;
+  if (
+    m &&
+    ['complete', 'partial', 'unavailable'].includes(m.coverage) &&
+    timestamp(m.observedAt, '')
+  ) {
+    const c = m.cost;
+    const cost =
+      c && typeof c === 'object'
+        ? costSummary({
+            estimatedUsd: c.baselineUsd,
+            model: c.model,
+            estimatedUsdRange: c.range,
+            pricing: { asOf: c.pricingAsOf, source: c.pricingSource },
+          } as CallbackValue<'onCost'>)
+        : undefined;
+    output.measurement = {
+      coverage: m.coverage,
+      observedAt: timestamp(m.observedAt, ''),
+      ...(finite(m.threadCount) ? { threadCount: count(m.threadCount) } : {}),
+      ...(finite(m.missingThreadCount) ? { missingThreadCount: count(m.missingThreadCount) } : {}),
+      ...(cost ? { cost } : {}),
+      ...(m.usage &&
+      [
+        m.usage.inputTokens,
+        m.usage.cachedInputTokens,
+        m.usage.outputTokens,
+        m.usage.reasoningOutputTokens,
+        m.usage.totalTokens,
+      ].every(finite)
+        ? {
+            usage: {
+              inputTokens: count(m.usage.inputTokens),
+              cachedInputTokens: count(m.usage.cachedInputTokens),
+              outputTokens: count(m.usage.outputTokens),
+              reasoningOutputTokens: count(m.usage.reasoningOutputTokens),
+              totalTokens: count(m.usage.totalTokens),
+            },
+          }
+        : {}),
+    };
+  }
+  const r = stored.lastReconnect;
+  if (r && finite(r.attempt) && finite(r.maxAttempts) && timestamp(r.at, ''))
+    output.lastReconnect = {
+      attempt: count(r.attempt),
+      maxAttempts: count(r.maxAttempts),
+      at: timestamp(r.at, ''),
+      ...(['rate_limit', 'network', 'authentication', 'authorization'].includes(r.reason ?? '')
+        ? { reason: r.reason }
+        : {}),
+      ...(finite(r.retryAfterSeconds) ? { retryAfterSeconds: r.retryAfterSeconds } : {}),
+    };
+  return output;
+}

package/src/core/scan-plan.ts

@@ -0,0 +1,182 @@
+import { loadGlobalSettings, mergeSettings, type ResolvedSdkSettings } from './sdk-settings.ts';
+import { realpath, stat, open } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, relative, resolve, sep, extname } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+
+export interface ScanInputs {
+  mode?: 'standard' | 'deep';
+  repository?: string;
+  scopePaths?: string[];
+  scanPrompt?: string;
+  contextFiles?: string[];
+}
+export interface ScanPlan {
+  settings: ResolvedSdkSettings;
+  globalConfigFile: string;
+  globalConfigDigest: string | null;
+  id: string;
+  repository: string;
+  scopePaths: string[];
+  scanPrompt: string;
+  contextFiles: { path: string; bytes: number; sha256: string }[];
+  expiresAt: string;
+  mock: boolean;
+  inputs: ScanInputs;
+}
+const hash = (s: Buffer | string) => createHash('sha256').update(s).digest('hex');
+const inside = (root: string, path: string) => {
+  const r = relative(root, path);
+  return r !== '..' && !r.startsWith('..' + sep) && !isAbsolute(r);
+};
+const denied = new Set(['.git', '.ssh', '.aws', '.codex', '.runtime', 'node_modules']);
+function validateRelative(path: string) {
+  if (
+    !path ||
+    isAbsolute(path) ||
+    path.includes('\\') ||
+    path.split('/').some((p) => p === '..' || denied.has(p)) ||
+    /[\x00-\x1f*?[\]{}]/.test(path)
+  )
+    throw new Error(
+      'Use existing repository-relative paths without traversal, globs, credentials, or runtime directories.',
+    );
+  if (
+    path
+      .split('/')
+      .some(
+        (p) =>
+          /^\.env(?:\.|$)/.test(p) ||
+          /^(auth\.json|credentials(?:\.json)?|id_rsa|id_ed25519)$/.test(p),
+      )
+  )
+    throw new Error('Credential files cannot be supplied as scan context or scope.');
+}
+async function checkedPath(root: string, path: string) {
+  validateRelative(path);
+  const canonical = await realpath(resolve(root, path));
+  if (!inside(root, canonical)) throw new Error('Path escapes the selected repository.');
+  validateRelative(relative(root, canonical) || '.');
+  return canonical;
+}
+async function contextInfo(root: string, path: string) {
+  const canonical = await checkedPath(root, path);
+  if (!['.md', '.txt', '.rst', '.json', '.yaml', '.yml'].includes(extname(path).toLowerCase()))
+    throw new Error(
+      'Context files must be text documentation (.md, .txt, .rst, .json, .yaml, .yml).',
+    );
+  const file = await open(canonical, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const info = await file.stat();
+    if (!info.isFile() || info.size > 64 * 1024)
+      throw new Error('Each context file must be a regular file of at most 64 KiB.');
+    const bytes = Buffer.alloc(64 * 1024 + 1);
+    const result = await file.read(bytes, 0, bytes.length, 0);
+    const content = bytes.subarray(0, result.bytesRead);
+    if (content.length > 64 * 1024 || content.includes(0))
+      throw new Error('Context file must be bounded text.');
+    return {
+      path: relative(root, canonical).split(sep).join('/'),
+      bytes: content.length,
+      sha256: hash(content),
+    };
+  } finally {
+    await file.close();
+  }
+}
+function parseInputs(value: unknown): ScanInputs {
+  if (!value || typeof value !== 'object' || Array.isArray(value))
+    throw new Error('Scan inputs must be an object.');
+  const data = value as Record<string, unknown>;
+  const allowed = ['repository', 'scopePaths', 'scanPrompt', 'contextFiles', 'mode'];
+  for (const key of Object.keys(data))
+    if (!allowed.includes(key))
+      throw new Error(
+        `Unsupported scan input: ${key}. Approval, auth and SDK settings cannot come from model tool input.`,
+      );
+  for (const key of ['repository', 'scanPrompt'])
+    if (
+      data[key] !== undefined &&
+      (typeof data[key] !== 'string' ||
+        (data[key] as string).length > (key === 'scanPrompt' ? 8000 : 4096))
+    )
+      throw new Error(`Invalid ${key}.`);
+  for (const key of ['scopePaths', 'contextFiles'])
+    if (
+      data[key] !== undefined &&
+      (!Array.isArray(data[key]) ||
+        data[key].length > (key === 'scopePaths' ? 32 : 8) ||
+        data[key].some((p: unknown) => typeof p !== 'string' || p.length > 4096))
+    )
+      throw new Error(`Invalid ${key}.`);
+  if (data.mode !== undefined && data.mode !== 'standard' && data.mode !== 'deep')
+    throw new Error('mode must be standard or deep.');
+  return data as ScanInputs;
+}
+export async function prepareScan(
+  currentProject: string,
+  raw: unknown = {},
+  mock = false,
+): Promise<ScanPlan> {
+  const input = parseInputs(raw);
+  // Never let node:path fall back to the plugin process's working directory.
+  // A verified session location or an explicit absolute target must anchor the request.
+  const target = input.repository || '.';
+  if (!isAbsolute(target) && (!currentProject || !isAbsolute(currentProject)))
+    throw new Error('No local project is selected. Choose an absolute repository path explicitly.');
+  const repository = await realpath(isAbsolute(target) ? target : resolve(currentProject, target));
+  if (!(await stat(repository)).isDirectory()) throw new Error('Repository must be a directory.');
+  const home = await realpath(homedir());
+  if (inside(repository, home))
+    throw new Error(
+      'Choose a specific project repository explicitly. Your home folder and its parent directories cannot be scan targets.',
+    );
+  const global = await loadGlobalSettings();
+  const settings = mergeSettings(global.settings, input.mode ? { scan: { mode: input.mode } } : {});
+  const merged = input;
+  const scopePaths: string[] = [];
+  for (const path of merged.scopePaths ?? [])
+    scopePaths.push(
+      relative(repository, await checkedPath(repository, path))
+        .split(sep)
+        .join('/') || '.',
+    );
+  const contextFiles = [];
+  for (const path of merged.contextFiles ?? [])
+    contextFiles.push(await contextInfo(repository, path));
+  if (contextFiles.reduce((n, f) => n + f.bytes, 0) > 128 * 1024)
+    throw new Error('Combined context is limited to 128 KiB.');
+  const scanPrompt = merged.scanPrompt ?? '';
+  const normalized = {
+    ...(input.mode ? { mode: input.mode } : {}),
+    repository,
+    scopePaths: [...new Set(scopePaths)],
+    scanPrompt,
+    contextFiles: [...new Set(contextFiles.map((f) => f.path))],
+  };
+  return {
+    settings,
+    globalConfigFile: global.path,
+    globalConfigDigest: global.digest,
+    id: randomUUID(),
+    ...normalized,
+    contextFiles,
+    expiresAt: new Date(Date.now() + 10 * 60_000).toISOString(),
+    mock,
+    inputs: normalized,
+  };
+}
+export async function validatePlan(plan: ScanPlan) {
+  if (Date.now() >= Date.parse(plan.expiresAt))
+    throw new Error('Scan preview expired. Prepare and review it again.');
+  const current = await prepareScan(plan.repository, plan.inputs, plan.mock);
+  if (
+    current.repository !== plan.repository ||
+    current.globalConfigDigest !== plan.globalConfigDigest ||
+    JSON.stringify(current.settings) !== JSON.stringify(plan.settings) ||
+    JSON.stringify(current.contextFiles) !== JSON.stringify(plan.contextFiles) ||
+    JSON.stringify(current.scopePaths) !== JSON.stringify(plan.scopePaths)
+  )
+    throw new Error('Target or context changed after preview. Prepare and review it again.');
+}

package/src/core/scan-service.mjs

@@ -0,0 +1,129 @@
+import { randomUUID } from 'node:crypto';
+import { basename, resolve } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { collectFiles, scanFile } from './scanner.mjs';
+
+export function initialState(repository = '', instanceId = '') {
+  return {
+    instanceId,
+    status: 'idle',
+    scanId: null,
+    phase: 'Ready',
+    progress: { done: 0, total: 0 },
+    findings: [],
+    events: [],
+    error: null,
+    startedAt: null,
+    finishedAt: null,
+    repository,
+    engine: 'local-patterns (prototype)',
+    skipped: 0,
+    revision: 0,
+  };
+}
+
+export class ScanService {
+  #instanceId = randomUUID();
+  #state;
+  #listeners = new Set();
+  #controller;
+  #task;
+  #disposed = false;
+  constructor(root, { delayMs = 0 } = {}) {
+    this.root = resolve(root);
+    this.delayMs = Math.max(0, Math.min(delayMs, 2000));
+    this.#state = initialState(basename(this.root), this.#instanceId);
+  }
+  getState() {
+    return structuredClone(this.#state);
+  }
+  subscribe(listener) {
+    this.#listeners.add(listener);
+    return () => this.#listeners.delete(listener);
+  }
+  #emit(message) {
+    if (message) this.#state.events.push({ time: new Date().toISOString(), message });
+    this.#state.events = this.#state.events.slice(-100);
+    this.#state.revision++;
+    for (const listener of this.#listeners) {
+      try {
+        listener(this.getState());
+      } catch {
+        /* A broken view must not stop the scan. */
+      }
+    }
+  }
+  start() {
+    if (this.#disposed) throw new Error('Scan service is closed');
+    // Idempotent under repeated clicks; only one read-only scan per instance.
+    if (this.#state.status === 'running') return this.getState();
+    const revision = this.#state.revision;
+    this.#state = {
+      ...initialState(basename(this.root), this.#instanceId),
+      revision,
+      status: 'running',
+      scanId: randomUUID(),
+      phase: 'Discovering source files',
+      startedAt: new Date().toISOString(),
+    };
+    this.#controller = new AbortController();
+    this.#emit('Local scan started. No provider, credentials, or network calls.');
+    this.#task = this.#run(this.#controller.signal);
+    return this.getState();
+  }
+  async #run(signal) {
+    try {
+      const { base, files } = await collectFiles(this.root, signal);
+      this.#state.progress.total = files.length;
+      this.#emit(
+        `Found ${files.length} supported source files; hidden paths, dependencies, and symlinks excluded.`,
+      );
+      for (const path of files) {
+        signal.throwIfAborted();
+        if (this.delayMs) await delay(this.delayMs, undefined, { signal });
+        const result = await scanFile(base, path, signal);
+        this.#state.findings.push(...result.findings);
+        this.#state.progress.done++;
+        if (result.skipped) this.#state.skipped++;
+        this.#state.phase = `Checking files (${this.#state.progress.done}/${files.length})`;
+        this.#emit(
+          result.findings.length
+            ? `${result.findings.length} candidate finding(s) in ${result.findings[0].path}`
+            : undefined,
+        );
+      }
+      signal.throwIfAborted();
+      this.#state.status = 'completed';
+      this.#state.phase = 'Pattern scan complete';
+      this.#emit(
+        `Completed with ${this.#state.findings.length} candidate findings. Not a security clearance or Codex Security scan.`,
+      );
+    } catch (error) {
+      this.#state.status = signal.aborted ? 'cancelled' : 'error';
+      this.#state.phase = signal.aborted ? 'Cancelled; partial results retained' : 'Scan failed';
+      this.#state.error = signal.aborted ? null : String(error.message ?? error);
+      this.#emit(
+        signal.aborted
+          ? 'Scan cancelled. Partial findings are not a complete result.'
+          : `Scan failed: ${this.#state.error}`,
+      );
+    } finally {
+      this.#state.finishedAt = new Date().toISOString();
+      this.#emit();
+    }
+  }
+  cancel() {
+    if (this.#state.status === 'running') this.#controller.abort();
+    return this.getState();
+  }
+  async wait() {
+    await this.#task;
+    return this.getState();
+  }
+  async dispose() {
+    this.#disposed = true;
+    this.cancel();
+    await this.#task;
+    this.#listeners.clear();
+  }
+}