fix(sdk): report observed worker sessions without status markers

[mldangelo-oai]

Summary

Worker dispatch status depends on assistant text markers, so SDK callers can miss successful delegation. Add onWorkerEvent to report persisted worker sessions discovered by the existing SDK session tracker, independently of model text. This works with the currently bundled Codex 0.154.0 and requires no runtime changes or dependency updates.

Refs #956. This provides session observation; phase counts, failed-dispatch reporting, and a pre-review control gate remain outside this callback's contract.

Changes

• Export ScanWorkerEvent and add ScanOptions.onWorkerEvent, emitting only { kind: "observed", worker: number } once per discovered session per run.
• Reuse session attribution and worker numbering from cost/activity tracking, including nested workers and associated validation or Deep Scan sessions. Enable polling when this is the only observer.
• Keep prompts, raw thread IDs, and session contents out of the callback. Route synchronous and asynchronous observer failures through onObserverError without stopping the scan.
• End observations after the first final session read, including cancellation during post-scan work. Document persistence/polling delay, saved workers on resume, and the post-scan boundary.
• Preserve onWorkerStatus behavior and explicitly document its dispatch variant as best-effort model reporting. No public CLI changes.

Testing

• Marker-independent session regression: failed before implementation and passed afterward for all three supported parent metadata shapes.
• Final randomized SDK suite (seed 2454836527): 3,083 passed, 57 skipped, zero failures. Seed 12345 also passed (3,082 passed, 57 skipped) before adding the final cancelled-follow-up case.
• Focused API/session/status suite: 292 passed, 4 skipped. The subsequent cancellation/observation regression set passed all 22 cases; all three metadata-fixture variants passed after the race correction.
• SDK types, formatting, production build, and CI build: passed.
• npm archive and installed-package smoke checks on Node 24.15.0: passed, including strict NodeNext public types, CLI and SDK lifecycle, all 142 bundled plugin files, and nested worker startup. Installation used the existing dependency cache after an unchanged development dependency failed a registry lookup.
• Final compiled SDK with unmodified Codex 0.154.0: a synthetic Standard DiffTarget.refs scan created two real delegated sessions and delivered both observations before the mock model was allowed to complete. Verified matching session worker numbers, absent status markers, non-fatal throwing observers, sealed complete artifacts, and no observation for a capacity failure that created no session.
• Three independent native reviews plus independent verification passed on the final commit after correcting a cancelled-follow-up lifecycle edge and a test-fixture race.

The integration uses a localhost mock model, synthetic credentials, and a harmless temporary repository. Local execution coverage is macOS arm64; Linux and Windows remain CI coverage.

Risk and rollout

This is an optional SDK observer backed by the same session discovery used for cost tracking. It is compatible with the existing dependency pins. Saved workers can be reported again on resume, and missing notifications do not establish that delegation was skipped. The event does not mean a worker just started or file review has begun, does not report failed spawn attempts or planned counts, and cannot gate dispatch. Observation ends before postScanPrompt; maxCostUsd and AbortSignal remain the cost/cancellation controls.

Public disclosure review

• No customer, partner, prospect, or user identities, data, or identifying details are included.
• No credentials, personal data, private source, scan findings, or nonpublic links or tickets are included.
• I reviewed the branch name, title, description, commits, changes, comments, logs, screenshots, attachments, and links for public disclosure.

[mldangelo-oai]

@codex review

Please review head b2e08d718d9ee1bf171f05f224550fb386b98e70. This PR remains draft pending the paired runtime release and dependency pin update.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-17T22:06:04.171528Z	7458be3	Draft marked ready
🔒 Security Review	✅ Completed 2026-09-17T22:06:50.557730Z	7458be3	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Already looking forward to the next diff.

Reviewed commit: b2e08d718d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".