onWorkerStatus can omit dispatch events when delegated workers run

Summary

onWorkerStatus can emit a valid preflight status but omit every dispatch status even when a successful Standard committed-diff scan actually uses delegated workers.

The SDK documentation describes onWorkerStatus as being called when worker preflight or dispatch status changes. In 0.1.28, dispatch status is instead inferred from a marker in an agent_message; it is not derived from the actual worker lifecycle. If the scan agent omits or misformats that marker, the callback is silent.

Environment

• @openai/codex-security 0.1.28
• sealed manifest producer: codex-security-plugin 0.1.95
• Node.js 24 on GitHub Actions Linux
• Standard committed-diff scan using DiffTarget.refs(...)
• gpt-5.6-sol, low reasoning effort

Observed reproduction

Collect lifecycle events during a normal SDK scan:

const workerStatuses = [];
const progress = [];

const result = await security.run(repository, {
  target: DiffTarget.refs({ base, head }),
  outputDir,
  onWorkerStatus(status) {
    workerStatuses.push(status);
  },
  onProgress(update) {
    progress.push(update);
  },
});

The successful scan emitted this worker status:

{"kind":"preflight","delegation":"available","configuredSlots":null}

It then emitted normal committed-diff progress through discovery, validation, and reporting, completed with sealed artifacts and complete coverage, and its report recorded the validation mode as:

Static source review of complete base/head files and exact diff; two independent
delegated batches plus parent consistency review.

However, workerStatuses contained no event with kind: "dispatch" for file_review, validation, or any other phase.

This is not a case where worker delegation was unavailable: preflight reported it available and the completed scan recorded delegated batches.

Expected behavior

When the runtime attempts a delegated phase, onWorkerStatus should receive a runtime-derived dispatch event with the actual phase, planned, and started counts, including started: 0 when dispatch fails or capacity is unavailable.

If dispatch events are intentionally best-effort, the API documentation and types should state that explicitly and the SDK should expose a separate deterministic worker-lifecycle event suitable for CI control logic.

Why this appears to be an SDK implementation gap

The current parser sends command_execution events to deterministic preflight parsing, but sends agent_message events to dispatch parsing:

• workerStatusFromEvent
• dispatchStatus

The bundled skill asks the scan agent to emit a text marker immediately after dispatch:

• CODEX_SECURITY_WORKER_STATUS instruction

This makes callback delivery dependent on model compliance and exact formatting, rather than the worker scheduler or session lifecycle. #525 describes a related false-positive case caused by treating model text as status; this report is the false-negative counterpart.

Impact

CI integrations cannot reliably use onWorkerStatus to determine when expensive file review has actually started. We use that boundary for a pre-review cost/time guard and currently need a less precise first-completed-file fallback.

Using raw onSessionEvent data is not an acceptable general workaround because, as the SDK documentation notes, those events can contain source code or credentials.

Suggested direction

Emit dispatch status from the actual runtime worker/session creation result, and keep text-marker parsing only as a backwards-compatible fallback. A regression test could run a delegated scan whose agent response omits the marker and assert that the SDK still reports the real dispatch counts.