Skip to content

OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security

fix(deep-scan): stop on known policy refusal messages (#1035)

Sammy Touranib6d739b99a72
diff --git a/plugins/codex-security/mcp-app/src/deep-scan/coordinator.ts b/plugins/codex-security/mcp-app/src/deep-scan/coordinator.ts
index d5caf3cda..73a5421ab 100644
--- a/plugins/codex-security/mcp-app/src/deep-scan/coordinator.ts
+++ b/plugins/codex-security/mcp-app/src/deep-scan/coordinator.ts
@@ -342,12 +342,15 @@ export class DeepScanCoordinator {
private async run(): Promise<void> {
try {
+ // A replacement coordinator must honor a worker failure committed before handoff.
+ if (this.state.error) throw new Error(this.state.error);
await ensureDeepScanDirectories(this.artifacts);
if (this.canceled || this.externallyFailed) return;
this.setupComplete = true;
const loopResult = await this.runIterations();
if (this.canceled || this.externallyFailed) return;
+ this.abortController.signal.throwIfAborted();
const draft = loopResult.result
? scanUnionToDraft(loopResult.result)
: scanDraftInputSchema.parse({
@@ -411,7 +414,7 @@ export class DeepScanCoordinator {
}
const message = errorMessage(error);
const persistedMessage = deepScanErrorMessage(error);
- if (!this.setupComplete) {
+ if (!this.setupComplete && !this.state.error) {
this.log({
event: "setup_failed",
scanId: this.state.scanId,
diff --git a/plugins/codex-security/mcp-app/src/deep-scan/errors.ts b/plugins/codex-security/mcp-app/src/deep-scan/errors.ts
index 02aae8ec5..3dd3bac13 100644
--- a/plugins/codex-security/mcp-app/src/deep-scan/errors.ts
+++ b/plugins/codex-security/mcp-app/src/deep-scan/errors.ts
@@ -4,18 +4,19 @@ const STALE_COORDINATOR_GENERATION_MESSAGE =
"Deep Scan coordinator lease belongs to a newer generation.";
// The SDK currently exposes only the message for turn errors. Match known
-// refusal messages exactly so repository output embedded in another error
-// cannot be mistaken for a refusal.
+// terminal messages exactly so repository output embedded in another error
+// cannot be mistaken for a permanent failure.
const CYBERSECURITY_POLICY_REFUSAL_MESSAGES = new Set([
"Request blocked by cyberPolicy.",
"Request blocked by a safety policy violation.",
"This content was flagged for possible cybersecurity risk.",
+ "This content was flagged for possible cybersecurity risk. If this seems wrong, try rephrasing your request. To get authorized for security work, join the Trusted Access for Cyber program: https://chatgpt.com/cyber",
"This content was flagged for potentially high-risk cyber activity.",
"This request has been flagged for possible cybersecurity risk.",
"This request has been flagged for potentially high-risk cyber activity.",
]);
-/** Explicitly opt a confirmed scan-wide prerequisite failure out of retries. */
+/** A confirmed terminal worker failure that stops the scan without retries. */
export class DeepScanNonRetryableError extends Error {
constructor(message: string, options?: ErrorOptions) {
super(message, options);
@@ -32,10 +33,11 @@ const USAGE_LIMIT_MESSAGES = new Set([
"You hit your spend cap set by the owner of your workspace. Ask an owner to increase your spend cap to continue.",
]);
-// Codex exec exposes only text for failed turns. Match its native quota messages here.
+// Classify only terminal turn failures; diagnostics can contain arbitrary output.
export function codexWorkerTurnError(message: string): Error {
const reason = message.replace(/^Error running remote compact task: /, "");
if (
+ CYBERSECURITY_POLICY_REFUSAL_MESSAGES.has(message) ||
USAGE_LIMIT_MESSAGES.has(reason) ||
reason.startsWith("You’ve hit your usage limit.") ||
reason.startsWith("You’ve hit your usage limit for ")
@@ -85,16 +87,10 @@ export function isStaleCoordinatorGenerationError(error: unknown): boolean {
return false;
}
-/** A safety refusal retires the refused thread; it is not a broken scan. */
-export function isCodexCybersecurityPolicyRefusal(error: unknown): boolean {
- return CYBERSECURITY_POLICY_REFUSAL_MESSAGES.has(errorMessage(error));
-}
-
export function classifyCodexWorkerError(error: unknown): Error {
// OS error codes alone do not establish a permanent failure, and SDK errors
// can contain arbitrary command output. Leave both on the normal retry path
- // unless a producer explicitly identifies the failure as nonretryable. The
- // worker runner handles exact policy refusals without failing the scan.
+ // unless a producer explicitly identifies the failure as nonretryable.
return error instanceof Error ? error : new Error(String(error));
}
diff --git a/plugins/codex-security/mcp-app/src/deep-scan/store.ts b/plugins/codex-security/mcp-app/src/deep-scan/store.ts
index 7b2c4e10d..4b0037477 100644
--- a/plugins/codex-security/mcp-app/src/deep-scan/store.ts
+++ b/plugins/codex-security/mcp-app/src/deep-scan/store.ts
@@ -290,6 +290,7 @@ export class WorkbenchDeepScanStore {
sdkThreadId: update.threadId || undefined,
}),
...(update.error ? [`--error-message=${update.error}`] : []),
+ ...(update.terminalFailure ? ["--terminal-failure"] : []),
...(update.replaceableFailureKind
? ["--replaceable-failure-kind", update.replaceableFailureKind]
: []),
diff --git a/plugins/codex-security/mcp-app/src/deep-scan/types.ts b/plugins/codex-security/mcp-app/src/deep-scan/types.ts
index 9314c243e..f1ee65361 100644
--- a/plugins/codex-security/mcp-app/src/deep-scan/types.ts
+++ b/plugins/codex-security/mcp-app/src/deep-scan/types.ts
@@ -44,6 +44,7 @@ export type DeepScanWorkerMutation = Omit<
"completionSequence" | "consecutiveErrors" | "mergeState"
> & {
scanId: string;
+ terminalFailure?: boolean;
replaceableFailureKind?: DeepScanReplaceableFailureKind;
};
diff --git a/plugins/codex-security/mcp-app/src/deep-scan/worker-runner.ts b/plugins/codex-security/mcp-app/src/deep-scan/worker-runner.ts
index 6b6f68db8..ee3470df7 100644
--- a/plugins/codex-security/mcp-app/src/deep-scan/worker-runner.ts
+++ b/plugins/codex-security/mcp-app/src/deep-scan/worker-runner.ts
@@ -9,7 +9,6 @@ import {
classifyCodexWorkerError as asError,
DeepScanNonRetryableError,
confirmedOwnershipChange,
- isCodexCybersecurityPolicyRefusal,
} from "./errors.js";
import { renderDiscoveryPrompt } from "./templates.js";
import type {
@@ -212,6 +211,7 @@ export class DeepScanWorkerRunner {
let validationStarted = false;
let validationCompleted = false;
let activeThreadId = resumableThreadId;
+ let terminalFailure: Promise<WorkerAttemptOutcome> | undefined;
const baseMutation: DeepScanWorkerMutation = {
id: input.workerId,
scanId: run.scanId,
@@ -240,7 +240,21 @@ export class DeepScanWorkerRunner {
workingDirectory: input.artifactDir,
subagents: run.config.subagents,
signal,
- onNonRetryableError: this.options.onNonRetryableError,
+ onNonRetryableError: (error) => {
+ if (signal.aborted || terminalFailure) return;
+ terminalFailure = this.options.store
+ .updateWorker({
+ ...baseMutation,
+ threadId: activeThreadId,
+ status: "failed",
+ error: deepScanErrorMessage(error),
+ terminalFailure: true,
+ })
+ .then(() => ({ status: "failed", error }));
+ // Await this write after executor cleanup, even if it rejects first.
+ void terminalFailure.catch(() => {});
+ this.options.onNonRetryableError?.(error);
+ },
resumeThreadId: resumableThreadId,
continuationPrompt:
resumePrompt && run.severityRubric
@@ -271,6 +285,7 @@ export class DeepScanWorkerRunner {
});
},
});
+ if (terminalFailure) return terminalFailure;
if (signal.aborted) {
return await this.cancelAttempt(input, attempt, activeThreadId);
}
@@ -298,20 +313,17 @@ export class DeepScanWorkerRunner {
};
} catch (error) {
if (confirmedOwnershipChange(error, run.scanId)) throw error;
+ if (terminalFailure) return terminalFailure;
if (signal.aborted) {
return await this.cancelAttempt(input, attempt, activeThreadId);
}
const normalized = asError(error);
const retryable = !(normalized instanceof DeepScanNonRetryableError);
- const policyRefusal =
- retryable && isCodexCybersecurityPolicyRefusal(normalized);
- if (policyRefusal || !retryable || attempt === maximumAttempts) {
+ if (!retryable || attempt === maximumAttempts) {
const replaceableFailureKind = retryable
- ? policyRefusal
- ? "policy_refusal"
- : validationStarted
- ? "invalid_discovery_artifacts"
- : "transient_error"
+ ? validationStarted
+ ? "invalid_discovery_artifacts"
+ : "transient_error"
: undefined;
await this.options.store.updateWorker({
...baseMutation,
diff --git a/plugins/codex-security/mcp-app/tests/deep_scan_coordinator_fixture.ts b/plugins/codex-security/mcp-app/tests/deep_scan_coordinator_fixture.ts
index 1244530d1..96ae30824 100644
--- a/plugins/codex-security/mcp-app/tests/deep_scan_coordinator_fixture.ts
+++ b/plugins/codex-security/mcp-app/tests/deep_scan_coordinator_fixture.ts
@@ -28,6 +28,7 @@ export const {
DeepScanRemoteCoordinator,
AsyncLock,
classifyCodexWorkerError,
+ codexWorkerTurnError,
startOrJoinDeepScanCoordinator,
recordCodexSecurityWorkerScanDraft,
} = await importModule({
@@ -35,7 +36,7 @@ export const {
contents: `
export * from "./registry.ts";
export { WorkbenchDeepScanStore } from "./store.ts";
- export { classifyCodexWorkerError } from "./errors.ts";
+ export { classifyCodexWorkerError, codexWorkerTurnError } from "./errors.ts";
export { recordCodexSecurityWorkerScanDraft } from "../artifact-scan-draft.ts";
`,
resolveDir: path.join(import.meta.dirname, "../src/deep-scan/"),
@@ -197,6 +198,11 @@ export class FakeStore {
}
persisted.consecutiveErrors = this.run.consecutiveErrors;
this.workers.set(update.id, persisted);
+ if (update.terminalFailure) {
+ assert.equal(update.status, "failed");
+ assert.ok(update.error);
+ this.run.error ??= update.error;
+ }
return structuredClone(persisted);
}
diff --git a/plugins/codex-security/mcp-app/tests/deep_scan_executor_fixture.ts b/plugins/codex-security/mcp-app/tests/deep_scan_executor_fixture.ts
index 217c5a1bd..b856ea04d 100644
--- a/plugins/codex-security/mcp-app/tests/deep_scan_executor_fixture.ts
+++ b/plugins/codex-security/mcp-app/tests/deep_scan_executor_fixture.ts
@@ -35,7 +35,6 @@ const executor = await importModule({
// Expose the environment snapshot only for tests.
contents: `${await readFile(executorSource, "utf8")}
export { snapshotWorkerEnvironment, appendItemDiagnostic };
-export { isCodexCybersecurityPolicyRefusal } from "./errors.js";
export { parseDeepScan } from "./response.js";`,
loader: "ts",
resolveDir: path.dirname(fileURLToPath(executorSource)),
@@ -47,7 +46,6 @@ export const {
resolveCodexPath,
snapshotWorkerEnvironment,
appendItemDiagnostic,
- isCodexCybersecurityPolicyRefusal,
parseDeepScan,
} = executor;
export const CodexSdkWorkerExecutor: typeof Executor =
diff --git a/plugins/codex-security/mcp-app/tests/support/fake-codex-source.ts b/plugins/codex-security/mcp-app/tests/support/fake-codex-source.ts
index 696f95bc9..e813b5195 100644
--- a/plugins/codex-security/mcp-app/tests/support/fake-codex-source.ts
+++ b/plugins/codex-security/mcp-app/tests/support/fake-codex-source.ts
@@ -103,13 +103,6 @@ if (stdin.includes('PERMISSION_PROFILE_FALLBACK_ITEM')) console.log(JSON.stringi
if (stdin.includes('PERMISSION_PROFILE_FALLBACK_EVENT')) console.log(JSON.stringify({ type: 'error', message: permissionProfileFallbackWarning }));
if (stdin.includes('BLOCK_AFTER_START')) await new Promise(() => {});
if (stdin.includes('FAIL_THEN_HANG')) { console.log(JSON.stringify({ type: 'turn.failed', error: { message: 'fixture worker failed' } })); setInterval(() => {}, 1_000); await new Promise(() => {}); }
-if (stdin.includes('RATE_LIMIT_CYBER_POLICY_ERROR')) { console.log(JSON.stringify({ type: 'turn.failed', error: { message: '429 Too Many Requests: Request blocked by cyberPolicy.' } })); process.exit(0); }
-if (stdin.includes('CYBER_POLICY_ERROR')) { console.log(JSON.stringify({ type: 'turn.failed', error: { message: 'Request blocked by cyberPolicy.' } })); process.exit(0); }
-if (stdin.includes('SAFETY_POLICY_ERROR')) { console.log(JSON.stringify({ type: 'turn.failed', error: { message: 'Request blocked by a safety policy violation.' } })); process.exit(0); }
-if (stdin.includes('UPSTREAM_CYBERSECURITY_RISK_ERROR')) { console.log(JSON.stringify({ type: 'turn.failed', error: { message: 'This request has been flagged for possible cybersecurity risk.' } })); process.exit(0); }
-if (stdin.includes('UPSTREAM_HIGH_RISK_CYBER_ACTIVITY_ERROR')) { console.log(JSON.stringify({ type: 'turn.failed', error: { message: 'This request has been flagged for potentially high-risk cyber activity.' } })); process.exit(0); }
-if (stdin.includes('CYBERSECURITY_RISK_ERROR')) { console.log(JSON.stringify({ type: 'turn.failed', error: { message: 'This content was flagged for possible cybersecurity risk.' } })); process.exit(0); }
-if (stdin.includes('HIGH_RISK_CYBER_ACTIVITY_ERROR')) { console.log(JSON.stringify({ type: 'turn.failed', error: { message: 'This content was flagged for potentially high-risk cyber activity.' } })); process.exit(0); }
if (stdin.includes('RETRYABLE_STREAM_ERROR')) console.log(JSON.stringify({ type: 'error', message: 'Reconnecting... 2/5 (stream disconnected before completion: websocket closed by server before response.completed)' }));
if (stdin.includes('INCOMPLETE_STREAM')) { console.log(JSON.stringify({ type: 'error', message: 'fixture stream interrupted' })); process.exit(0); }
if (stdin.includes('BWRAP_NAMESPACE_FAILURE')) console.log(JSON.stringify({ type: 'item.completed', item: { id: 'command-1', type: 'command_execution', command: 'super-secret-command', aggregated_output: 'private source text\\nbwrap: Creating new namespace failed: nesting depth or /proc/sys/user/max_user_namespaces exceeded (ENOSPC)', exit_code: 1, status: 'failed' } }));
diff --git a/plugins/codex-security/mcp-app/tests/test_deep_scan_coordinator.ts b/plugins/codex-security/mcp-app/tests/test_deep_scan_coordinator.ts
index fd4d25dd6..8bb4a655f 100644
--- a/plugins/codex-security/mcp-app/tests/test_deep_scan_coordinator.ts
+++ b/plugins/codex-security/mcp-app/tests/test_deep_scan_coordinator.ts
@@ -31,10 +31,10 @@ import {
import {
DeepScanCoordinatorRegistry,
WorkbenchDeepScanStore,
- DeepScanNonRetryableError,
DeepScanRemoteCoordinator,
AsyncLock,
classifyCodexWorkerError,
+ codexWorkerTurnError,
startOrJoinDeepScanCoordinator,
iterationInputs,
recordSleeps,
@@ -383,41 +383,10 @@ async function testExhaustedRetryFailsScan() {
assert.equal(terminal.manifestPath, undefined);
}
-async function testPolicyRefusalReplacesDiscoveryImmediately() {
- const { fixture, store } = await coordinatorFixture({
- stopAfterNoNew: 4,
- stopAfterConsecutiveErrors: 3,
- maxDiscoveryRuns: 3,
- });
- const executor = new FakeExecutor({
- discoveryFailureMessages: {
- "discovery-0001": "Request blocked by cyberPolicy.",
- },
- discoveryCandidateId: "candidate-1",
- });
- const sleeps: number[] = [];
- const terminal = await runCoordinator(fixture, store, executor, {
- random: () => 0,
- retryDelaysMs: [1, 3, 9],
- clock: recordingClock(sleeps),
- });
-
- assert.equal(terminal?.status, "succeeded", terminal?.error);
- assert.equal(terminal?.terminalReason, "capped");
- assert.equal(executor.discoveryAttempts.size, 3);
- assert.equal(executor.discoveryAttempts.get("discovery-0001"), 1);
- assert.deepEqual(sleeps, [], "a refused conversation must not be resumed");
- assert.equal(store.run.consecutiveErrors, 0);
- const refusal = [...store.workers.values()].find(
- (worker) =>
- path.basename(path.dirname(worker.promptPath)) === "discovery-0001",
- );
- assert.equal(refusal?.replaceableFailureKind, "policy_refusal");
- assert.equal(refusal?.status, "canceled");
-}
-
async function testTransientDiscoveryErrorsRetainRecovery() {
+ // Unclassified executor failures are distinct from a native turn.failed event.
for (const message of [
+ "Request blocked by cyberPolicy.",
"RateLimitExhaustedError: request rate limit reached; " +
"This content was flagged for possible cybersecurity risk.",
"429 Too Many Requests: flagged for potentially high-risk cyber activity.",
@@ -458,7 +427,7 @@ async function testTransientDiscoveryErrorsRetainRecovery() {
}
}
-async function testConsecutiveCybersecurityRefusalsFailAtConfiguredThreshold() {
+async function testConsecutiveTransientErrorsFailAtConfiguredThreshold() {
const { fixture, store } = await coordinatorFixture({
stopAfterNoNew: 6,
stopAfterConsecutiveErrors: 2,
@@ -466,8 +435,8 @@ async function testConsecutiveCybersecurityRefusalsFailAtConfiguredThreshold() {
});
const executor = new FakeExecutor({
discoveryFailureMessages: {
- "discovery-0001": "Request blocked by cyberPolicy.",
- "discovery-0002": "Request blocked by cyberPolicy.",
+ "discovery-0001": "transient worker failure",
+ "discovery-0002": "transient worker failure",
},
});
const terminal = await runCoordinator(fixture, store, executor, {
@@ -479,15 +448,15 @@ async function testConsecutiveCybersecurityRefusalsFailAtConfiguredThreshold() {
terminal?.error ?? "",
/2 consecutive unsuccessful discovery workers/,
);
- assert.match(terminal?.error ?? "", /policy_refusal/);
+ assert.match(terminal?.error ?? "", /transient_error/);
assert.equal(executor.discoveryAttempts.size, 2);
- assert.equal(executor.discoveryCalls, 2);
+ assert.equal(executor.discoveryCalls, 8);
assert.equal(store.run.consecutiveErrors, 2);
assert.equal(store.finishCalls.length, 0);
assert.equal(terminal.manifestPath, undefined);
assert.deepEqual(
[...store.workers.values()].map((worker) => worker.replaceableFailureKind),
- ["policy_refusal", "policy_refusal"],
+ ["transient_error", "transient_error"],
);
}
@@ -499,8 +468,8 @@ async function testSuccessfulDiscoveryResetsConsecutiveFailureThreshold() {
});
const executor = new FakeExecutor({
discoveryFailureMessages: {
- "discovery-0001": "Request blocked by cyberPolicy.",
- "discovery-0003": "Request blocked by cyberPolicy.",
+ "discovery-0001": "transient worker failure",
+ "discovery-0003": "transient worker failure",
},
discoveryCandidateId: "candidate-1",
});
@@ -513,7 +482,7 @@ async function testSuccessfulDiscoveryResetsConsecutiveFailureThreshold() {
assert.equal(store.run.consecutiveErrors, 0);
assert.equal(
[...store.workers.values()].filter(
- (worker) => worker.replaceableFailureKind === "policy_refusal",
+ (worker) => worker.replaceableFailureKind === "transient_error",
).length,
2,
);
@@ -2512,17 +2481,42 @@ async function testDiscoveryDeadlineWithoutAcceptedWorkersReturnsPartialEvidence
});
const executor = new FakeExecutor({ blockDiscoveryAfterCalls: 0 });
const completedDrafts: ScanDraftInput[] = [];
- const coordinator = createCoordinator(fixture, store, executor, {
- discoveryTimeoutMs: 500,
- onComplete: async (draft) =>
- void completedDrafts.push(structuredClone(draft)),
- });
+ let lateRefusal = false;
+ const coordinator = createCoordinator(
+ fixture,
+ store,
+ {
+ run(request) {
+ request.signal.addEventListener(
+ "abort",
+ () => {
+ lateRefusal = true;
+ request.onNonRetryableError?.(
+ codexWorkerTurnError("Request blocked by cyberPolicy."),
+ );
+ },
+ { once: true },
+ );
+ return executor.run(request);
+ },
+ },
+ {
+ discoveryTimeoutMs: 500,
+ onComplete: async (draft) =>
+ void completedDrafts.push(structuredClone(draft)),
+ },
+ );
coordinator.start();
await executor.discoveryStarted.promise;
const terminal = await coordinator.wait(undefined, 5_000);
assert.equal(terminal?.status, "succeeded", terminal?.error);
assert.equal(terminal?.terminalReason, "capped");
+ assert.equal(lateRefusal, true);
+ assert.equal(
+ store.workerUpdates.some((update) => update.terminalFailure),
+ false,
+ );
assert.equal(store.failureMessages.length, 0);
assert.equal(store.finishCalls.length, 1);
assert.equal(executor.runningDiscovery, 0);
@@ -2680,7 +2674,9 @@ async function testRecoverableWorkerErrorsCannotFailScan() {
}
}
-async function testQuotaFailureStopsDispatchBeforeWorkerShutdown() {
+async function testTerminalFailureStopsDispatchBeforeWorkerShutdown(
+ resumed: boolean,
+) {
const { fixture, store } = await coordinatorFixture({
workers: 2,
stopAfterNoNew: 10,
@@ -2688,43 +2684,91 @@ async function testQuotaFailureStopsDispatchBeforeWorkerShutdown() {
maxDiscoveryRuns: 10,
});
const normal = new FakeExecutor({
- blockDiscoveryAfterCalls: 0,
+ blockDiscoveryAfterCalls: 2,
+ discoveryCandidateId: "accepted-before-refusal",
});
const notified = Promise.withResolvers<void>();
const shutdown = Promise.withResolvers<void>();
const signals: AbortSignal[] = [];
const sleeps: number[] = [];
- let discoveryCalls = 0;
+ const message = resumed
+ ? "Request blocked by cyberPolicy."
+ : "Quota exceeded. Check your plan and billing details.";
+ const attempts: (string | undefined)[] = [];
const terminal = runCoordinator(
fixture,
store,
{
async run(request) {
signals.push(request.signal);
- if (++discoveryCalls === 2) {
- const error = new DeepScanNonRetryableError(
- "Synthetic usage limit reached",
- );
+ // The first batch commits results. In the second batch the sibling waits for abort.
+ if (signals.length >= 4) {
+ attempts.push(request.resumeThreadId);
+ await request.onThreadStarted?.("fixture-terminal-thread");
+ if (resumed && attempts.length === 1)
+ throw new Error("transient worker failure");
+ const error = codexWorkerTurnError(message);
request.onNonRetryableError?.(error);
notified.resolve();
await shutdown.promise;
- throw error;
+ throw new Error("later cleanup failure");
}
return normal.run(request);
},
},
- { clock: recordingClock(sleeps) },
+ { clock: recordingClock(sleeps), retryDelaysMs: [1], random: () => 0 },
);
try {
- await notified.promise;
- assert.ok(signals.every((signal) => signal.aborted));
+ await Promise.race([
+ notified.promise,
+ terminal.then(() => assert.fail("terminal failure was not reported")),
+ ]);
+ assert.ok(signals.slice(2).every((signal) => signal.aborted));
const callsAtFailure = signals.length;
+ assert.equal(store.iterations.length, 1);
+ const checkpoint = store.iterations[0].resultPath;
+ const committed = await readFile(checkpoint, "utf8");
+ assert.match(committed, /accepted-before-refusal/);
+ const [source] = store.workerUpdates.filter(
+ (update) => update.terminalFailure,
+ );
+ assert.equal(source?.error, message);
+ assert.equal(source.threadId, "fixture-terminal-thread");
+ assert.equal(source.attempt, resumed ? 2 : 1);
+ assert.deepEqual(
+ attempts,
+ resumed ? [undefined, "fixture-terminal-thread"] : [undefined],
+ );
+
+ if (resumed) {
+ const snapshot = await store.get();
+ assert.equal(snapshot.error, message);
+ const replacement = new FakeExecutor();
+ const adopted = await runCoordinator(fixture, store, replacement, {
+ run: snapshot,
+ });
+ assert.equal(adopted?.status, "failed");
+ assert.equal(adopted.error, message);
+ assert.equal(replacement.discoveryCalls, 0);
+ }
shutdown.resolve();
const result = await terminal;
assert.equal(result?.status, "failed");
- assert.equal(result?.error, "Synthetic usage limit reached");
+ assert.equal(result?.error, message);
assert.equal(signals.length, callsAtFailure);
- assert.deepEqual(sleeps, []);
+ assert.equal(store.workers.get(source.id)?.status, "failed");
+ assert.deepEqual(
+ store.workerUpdates.filter((update) => update.terminalFailure),
+ [source],
+ );
+ assert.ok(
+ [...store.workers.values()].some(
+ (worker) => worker.status === "canceled",
+ ),
+ );
+ assert.equal(store.finishCalls.length, 0);
+ assert.equal(await readFile(checkpoint, "utf8"), committed);
+ assert.deepEqual(sleeps, resumed ? [1] : []);
} finally {
shutdown.resolve();
await terminal;
@@ -2741,7 +2785,10 @@ function registerCases<T extends unknown[]>(
after(() => temporaryDirectories.cleanup());
test("Deep Scan lifecycle", testDeepScanLifecycle);
-test(testQuotaFailureStopsDispatchBeforeWorkerShutdown);
+registerCases(testTerminalFailureStopsDispatchBeforeWorkerShutdown, [
+ [false],
+ [true],
+]);
test(testStandardWorkersReceiveExistingFalsePositiveFeedback);
test(testConcurrentCheckpointKeepsExistingIteration);
test(testDiscoveryWorkersKeepOneContextAfterPersistedUpdate);
@@ -2757,9 +2804,8 @@ test(testDiscoveryDeadlineWithoutAcceptedWorkersReturnsPartialEvidence);
test(testDiscoveryDeadlineBeforeWorkerDispatchReturnsPartialEvidence);
test(testSingletonHardCapReduction);
test(testExhaustedRetryFailsScan);
-test(testPolicyRefusalReplacesDiscoveryImmediately);
test(testTransientDiscoveryErrorsRetainRecovery);
-test(testConsecutiveCybersecurityRefusalsFailAtConfiguredThreshold);
+test(testConsecutiveTransientErrorsFailAtConfiguredThreshold);
test(testRecoverableWorkerErrorsCannotFailScan);
test(testSuccessfulDiscoveryResetsConsecutiveFailureThreshold);
test(testExhaustedInvalidDiscoveryArtifactsAreReplaced);
diff --git a/plugins/codex-security/mcp-app/tests/test_deep_scan_errors.ts b/plugins/codex-security/mcp-app/tests/test_deep_scan_errors.ts
index 454e4c6db..240d80add 100644
--- a/plugins/codex-security/mcp-app/tests/test_deep_scan_errors.ts
+++ b/plugins/codex-security/mcp-app/tests/test_deep_scan_errors.ts
@@ -7,7 +7,6 @@ const {
classifyCodexWorkerError,
codexWorkerTurnError,
DeepScanNonRetryableError,
- isCodexCybersecurityPolicyRefusal,
} = await importModule({
entryPoints: [
fileURLToPath(new URL("../src/deep-scan/errors.ts", import.meta.url)),
@@ -42,41 +41,8 @@ test(function testWorkerErrorClassificationPreservesExplicitFailures() {
);
assert.equal(classifyCodexWorkerError(explicit), explicit);
- const refusalMessages = [
- "Request blocked by cyberPolicy.",
- "Request blocked by a safety policy violation.",
- "This content was flagged for possible cybersecurity risk.",
- "This content was flagged for potentially high-risk cyber activity.",
- "This request has been flagged for possible cybersecurity risk.",
- "This request has been flagged for potentially high-risk cyber activity.",
- ];
- for (const message of refusalMessages) {
- const original = new Error(message);
- const classified = classifyCodexWorkerError(original);
- assert.equal(classified, original);
- assert.equal(classified.name, "Error");
- assert.equal(isCodexCybersecurityPolicyRefusal(classified), true);
-
- const explicitRefusal = new DeepScanNonRetryableError(message);
- assert.equal(classifyCodexWorkerError(explicitRefusal), explicitRefusal);
-
- for (const unrecognized of [
- `Source fixture: ${message}`,
- `${message} Source fixture.`,
- JSON.stringify({ message }),
- `Codex Exec exited with code 1: ${message}`,
- `429 Too Many Requests: ${message}`,
- ` ${message}`,
- `${message}\n`,
- message.toLowerCase(),
- ]) {
- const unrelated = new Error(unrecognized);
- assert.equal(classifyCodexWorkerError(unrelated), unrelated);
- assert.equal(isCodexCybersecurityPolicyRefusal(unrelated), false);
- }
- }
-
for (const message of [
+ "Request blocked by cyberPolicy.",
"config parser handles unknown keys",
"failed to load configuration: invalid value",
"agents.max_threads cannot be set when features.multi_agent_v2 is enabled",
@@ -100,8 +66,15 @@ test(function testWorkerErrorClassificationPreservesExplicitFailures() {
}
});
-test(function testUsageLimitClassification() {
+test(function testNativeTurnFailureClassification() {
for (const message of [
+ "Request blocked by cyberPolicy.",
+ "Request blocked by a safety policy violation.",
+ "This content was flagged for possible cybersecurity risk.",
+ "This content was flagged for possible cybersecurity risk. If this seems wrong, try rephrasing your request. To get authorized for security work, join the Trusted Access for Cyber program: https://chatgpt.com/cyber",
+ "This content was flagged for potentially high-risk cyber activity.",
+ "This request has been flagged for possible cybersecurity risk.",
+ "This request has been flagged for potentially high-risk cyber activity.",
"Quota exceeded. Check your plan and billing details.",
"To use Codex with your ChatGPT plan, upgrade to Plus: https://chatgpt.com/explore/plus.",
"Your workspace is out of credits. Add credits to continue.",
@@ -117,6 +90,10 @@ test(function testUsageLimitClassification() {
assert.equal(error.message, message);
}
for (const message of [
+ "Command failed: Request blocked by cyberPolicy.",
+ "Error running remote compact task: Request blocked by cyberPolicy.",
+ "Request blocked by cyberPolicy. See the fixture.",
+ " Request blocked by cyberPolicy.",
"429 Too Many Requests",
"Command failed: Quota exceeded. Check your plan and billing details.",
"Error running remote compact task: stream disconnected before completion: synthetic reset",
diff --git a/plugins/codex-security/mcp-app/tests/test_deep_scan_executor.ts b/plugins/codex-security/mcp-app/tests/test_deep_scan_executor.ts
index 047fb7515..b673a0600 100644
--- a/plugins/codex-security/mcp-app/tests/test_deep_scan_executor.ts
+++ b/plugins/codex-security/mcp-app/tests/test_deep_scan_executor.ts
@@ -3,7 +3,6 @@ import {
resolveCodexPath,
snapshotWorkerEnvironment,
appendItemDiagnostic,
- isCodexCybersecurityPolicyRefusal,
parseDeepScan,
temporaryDirectories,
fakeCodexFixture,
@@ -187,9 +186,7 @@ try {
await check(t, testOwnedArtifactToolFailureDiagnosticIsPreserved);
await check(t, testCodeModeFrameDiagnosticSurvivesSuccessfulTurn);
await check(t, testSetupExitDiagnosticsRemainRetryable);
- await check(t, testPolicyFailuresRemainWorkerErrors);
await check(t, testMalformedCommandEventsRemainRetryable);
- await check(t, testRateLimitPolicyFailureRemainsRetryable);
await check(t, testArtifactStartupTimeoutRemainsRetryable);
}
});
@@ -3420,8 +3417,7 @@ async function testArtifactStartupTimeoutRemainsRetryable() {
runFixtureWorker("ARTIFACT_MCP_STARTUP_TIMEOUT"),
(error: Error) =>
error.name === "Error" &&
- error.message.includes("cs_artifacts: request timed out") &&
- !isCodexCybersecurityPolicyRefusal(error),
+ error.message.includes("cs_artifacts: request timed out"),
);
}
@@ -3440,32 +3436,6 @@ async function testSetupExitDiagnosticsRemainRetryable() {
}
}
-async function testPolicyFailuresRemainWorkerErrors() {
- for (const prompt of [
- "CYBER_POLICY_ERROR",
- "SAFETY_POLICY_ERROR",
- "CYBERSECURITY_RISK_ERROR",
- "HIGH_RISK_CYBER_ACTIVITY_ERROR",
- "UPSTREAM_CYBERSECURITY_RISK_ERROR",
- "UPSTREAM_HIGH_RISK_CYBER_ACTIVITY_ERROR",
- ]) {
- await assert.rejects(
- runFixtureWorker(prompt),
- (error: NodeJS.ErrnoException & { cause?: NodeJS.ErrnoException }) =>
- error?.name === "Error" && isCodexCybersecurityPolicyRefusal(error),
- );
- }
-}
-
-async function testRateLimitPolicyFailureRemainsRetryable() {
- await assert.rejects(
- runFixtureWorker("RATE_LIMIT_CYBER_POLICY_ERROR"),
- (error: NodeJS.ErrnoException & { cause?: NodeJS.ErrnoException }) =>
- error?.name === "Error" &&
- /429 Too Many Requests/.test(error?.message ?? ""),
- );
-}
-
async function testMalformedCommandEventsRemainRetryable() {
for (const output of [
"ordinary source text",
@@ -3611,7 +3581,10 @@ async function withWorkerFixture<Result>(
async function testWorkerTerminalEvents() {
await withWorkerFixture(async (_fixture, promptPath, workingDirectory) => {
const quotaMessage = "Quota exceeded. Check your plan and billing details.";
+ const policyMessage =
+ "This content was flagged for possible cybersecurity risk. If this seems wrong, try rephrasing your request. To get authorized for security work, join the Trusted Access for Cyber program: https://chatgpt.com/cyber";
const wrappedQuota = `Error running remote compact task: ${quotaMessage}`;
+ const terminalMessages = [quotaMessage, wrappedQuota, policyMessage];
const disconnect =
"Error running remote compact task: stream disconnected before completion: stream closed before response.completed";
for (const event of [
@@ -3619,8 +3592,24 @@ async function testWorkerTerminalEvents() {
{ type: "turn.failed", error: { message: quotaMessage } },
{ type: "turn.failed", error: { message: wrappedQuota } },
{ type: "turn.failed", error: { message: disconnect } },
+ { type: "turn.failed", error: { message: policyMessage } },
+ {
+ type: "turn.failed",
+ error: {
+ message: "429 Too Many Requests: Request blocked by cyberPolicy.",
+ },
+ },
{ type: "turn.failed", error: { message: "429 Too Many Requests" } },
{ type: "error", message: quotaMessage },
+ { type: "error", message: policyMessage },
+ {
+ type: "item.completed",
+ item: {
+ id: "refusal-text",
+ type: "agent_message",
+ text: policyMessage,
+ },
+ },
{
type: "item.completed",
item: { id: "quota-text", type: "agent_message", text: quotaMessage },
@@ -3639,18 +3628,16 @@ async function testWorkerTerminalEvents() {
onNonRetryableError,
});
if (event?.type === "turn.failed") {
- const isQuota = [quotaMessage, wrappedQuota].includes(
- event.error.message,
- );
+ const permanent = terminalMessages.includes(event.error.message);
await assert.rejects(execution, {
- name: isQuota ? "DeepScanNonRetryableError" : "Error",
+ name: permanent ? "DeepScanNonRetryableError" : "Error",
message: event.error.message,
});
assert.deepEqual(
onNonRetryableError.mock.calls.map(
({ arguments: [error] }) => error.message,
),
- isQuota ? [event.error.message] : [],
+ permanent ? [event.error.message] : [],
);
continue;
}
diff --git a/plugins/codex-security/scripts/deep_scan_workbench.py b/plugins/codex-security/scripts/deep_scan_workbench.py
index 491d1a35b..5b197d82e 100644
--- a/plugins/codex-security/scripts/deep_scan_workbench.py
+++ b/plugins/codex-security/scripts/deep_scan_workbench.py
@@ -1118,6 +1118,12 @@ def upsert_deep_scan_worker(
existing = connection.execute(
"SELECT * FROM deep_scan_workers WHERE id = ?", (worker_id,)
).fetchone()
+ if args.terminal_failure and (
+ args.status != "failed" or not optional_text(args.error_message)
+ ):
+ raise SystemExit(
+ "A terminal worker failure requires failed status and an error message."
+ )
replaceable_failure_kind = args.replaceable_failure_kind
if replaceable_failure_kind is not None and (
args.kind != "discovery"
@@ -1334,6 +1340,13 @@ def upsert_deep_scan_worker(
worker_id,
),
)
+ if args.terminal_failure:
+ # Persist the first terminal cause with its worker. An adopting coordinator
+ # completes the normal failure path after active workers have settled.
+ connection.execute(
+ "UPDATE deep_scan_runs SET error_message = ? WHERE scan_id = ? AND error_message IS NULL",
+ (error_message, scan_id),
+ )
return deep_scan_result(connection, scan_id)
@@ -1467,6 +1480,8 @@ def finish_deep_scan_locked(
connection.commit()
return deep_scan_result(connection, scan_id)
require_running_deep_scan(connection, scan_id)
+ if run["error_message"] is not None:
+ raise SystemExit(run["error_message"])
if (
args.terminal_reason == "saturated"
and run["consecutive_no_new"] < run["stop_after_no_new"]
@@ -1635,6 +1650,9 @@ def fail_deep_scan_locked(
"status"
] != "running":
raise SystemExit("Only a running Deep Scan can be failed or interrupted.")
+ # Cleanup can report a later error after a worker committed the terminal cause.
+ if run["status"] == "running" and run["error_message"] is not None:
+ message = run["error_message"]
if run["manifest_path"] not in {None, manifest_path}:
raise SystemExit("Deep Scan coordinator manifest path is immutable.")
if args.staged_manifest_path and manifest_path:
@@ -1754,7 +1772,7 @@ def cancel_from_parent_scan(connection: sqlite3.Connection, scan_id: str, timest
connection.execute(
"""
UPDATE deep_scan_runs
- SET status = 'canceled', phase = 'terminal', cancel_requested = 1,
+ SET status = 'canceled', phase = 'terminal', cancel_requested = 1, error_message = NULL,
terminal_reviewed_surface_count = NULL, completed_at = ?, updated_at = ?
WHERE scan_id = ? AND status IN ('running', 'succeeded')
""",
diff --git a/plugins/codex-security/scripts/workbench_cli.py b/plugins/codex-security/scripts/workbench_cli.py
index 09196abc6..e76911c93 100644
--- a/plugins/codex-security/scripts/workbench_cli.py
+++ b/plugins/codex-security/scripts/workbench_cli.py
@@ -149,6 +149,7 @@ def parse_args(description: str, *, inspection_only: bool = False) -> argparse.N
upsert_deep_worker.add_argument("--attempt", type=non_negative_int)
upsert_deep_worker.add_argument("--sdk-thread-id")
upsert_deep_worker.add_argument("--error-message")
+ upsert_deep_worker.add_argument("--terminal-failure", action="store_true")
upsert_deep_worker.add_argument(
"--replaceable-failure-kind",
choices=("policy_refusal", "transient_error", "invalid_discovery_artifacts"),
diff --git a/plugins/codex-security/skills/deep-security-scan/SKILL.md b/plugins/codex-security/skills/deep-security-scan/SKILL.md
index cc077b1de..6d4daecbe 100644
--- a/plugins/codex-security/skills/deep-security-scan/SKILL.md
+++ b/plugins/codex-security/skills/deep-security-scan/SKILL.md
@@ -10,5 +10,5 @@ The host runs Standard audits and merges their findings. Workers in the same sca
1. Resolve the authorized target and scope. For a scoped directory use that directory as `targetPath` and `scope: "."`. For a continuation, call `get_codex_security_scan_context` with its `scanId` and supplied `handoffClaimToken`. Use the saved identity, scope and mode. Follow `../../references/scan-prologue.md` for source access and context updates.
2. For a new target, call `inspect_codex_security_setup({ targetPath, scope: ".", mode: "deep", projectConfigPath? })`. Show the effective settings and their sources. `max_discovery_runs` caps the total number of Standard scans, including when several run together. Pass a project file only when the user selected it. Existing scans use their saved configuration.
3. For a newly launched native scan, inspect `otherRunningDeepScans` once. If another Deep scan is active, show its target, phase and human-friendly start time. Explain the additional CPU, memory and token use. Offer **Cancel (Recommended)** and **Continue** using `request_user_input`, then `request_codex_security_user_input` or plain chat if unavailable. Wait for an explicit choice. A dismissed dialog is not a cancellation. Cancel only the new scan if requested.
-4. Follow `../../references/access-advisory.md`, then call `start_codex_security_deep_scan` with the existing scan ID and claim token, or with the new target, scope, exact user context and selected project file. Await the tool. If the tool runner returns a running cell ID, wait on that cell until it returns the scan result. If the connection closes, rejoin with the same arguments. Report a terminal failure with its saved results. On explicit cancellation call `cancel_codex_security_scan`.
+4. Follow `../../references/access-advisory.md`, then call `start_codex_security_deep_scan` with the existing scan ID and claim token, or with the new target, scope, exact user context and selected project file. Await the tool. If the tool runner returns a running cell ID, wait on that cell until it returns the scan result. If the connection closes, rejoin with the same arguments. Report a terminal failure with its saved results. For a policy refusal, identify the worker from its saved error when available. On explicit cancellation call `cancel_codex_security_scan`.
5. For an SDK-owned scan, return the host's scan ID and manifest path so the SDK can finalize it. When the tool returns `completion`, link its generated `report.md` and canonical artifacts and report measured usage per `../../references/final-report.md`. Distinguish a completed audit with zero findings from a deadline reached before any audit completed.
diff --git a/plugins/codex-security/tests/test_workbench_deep_scan.py b/plugins/codex-security/tests/test_workbench_deep_scan.py
index dcb6b74d4..8512643ab 100644
--- a/plugins/codex-security/tests/test_workbench_deep_scan.py
+++ b/plugins/codex-security/tests/test_workbench_deep_scan.py
@@ -194,6 +194,7 @@ class DeepScan:
thread_id: str | None = None,
error: str | None = None,
replaceable_failure_kind: str | None = None,
+ terminal_failure: bool = False,
coordinator_generation: int | None = None,
check: bool = True,
) -> dict[str, object]:
@@ -209,6 +210,7 @@ class DeepScan:
*(("--attempt", str(attempt)) if attempt is not None else ()),
*(("--sdk-thread-id", thread_id) if thread_id is not None else ()),
*(("--error-message", error) if error is not None else ()),
+ *(("--terminal-failure",) if terminal_failure else ()),
*(
("--replaceable-failure-kind", replaceable_failure_kind)
if replaceable_failure_kind is not None
@@ -799,6 +801,51 @@ def test_expired_generation_refunds_shutdown_canceled_discovery(
)
[email protected]("terminal,cancel", [(False, False), (True, False), (True, True)])
+def test_worker_failure_diagnostic_survives_coordinator_adoption(
+ tmp_path: Path, terminal: bool, cancel: bool
+) -> None:
+ deep = start_empty_target_scan(tmp_path)
+ claim = claim_deep_scan_coordinator(deep.state_dir, deep.codex_home, deep.id)
+ generation = claim["deepScan"]["coordinatorGeneration"]
+ worker, prompt, artifacts, _ = deep.dispatch_discovery_worker(
+ name="discovery-1", succeed=False, coordinator_generation=generation
+ )
+ message = "Worker stopped by policy."
+ failed = deep.upsert_worker(
+ worker_id=worker,
+ prompt_path=prompt,
+ artifact_dir=artifacts,
+ status="failed",
+ error=message,
+ terminal_failure=terminal,
+ coordinator_generation=generation,
+ )["deepScan"]
+ expected = message if terminal else None
+ assert (failed["status"], failed["error"]) == ("running", expected)
+ assert failed["workers"][0]["error"] == message
+
+ expire_deep_scan_coordinator(deep.state_dir, deep.id)
+ adopted = claim_deep_scan_coordinator(deep.state_dir, deep.codex_home, deep.id)
+ assert adopted["coordinatorDisposition"] == "adopted"
+ assert adopted["deepScan"]["error"] == expected
+ generation = ("--coordinator-generation", str(adopted["deepScan"]["coordinatorGeneration"]))
+ manifest = deep.directory / "finish.json"
+ manifest.write_text("{}")
+ if terminal:
+ assert message in deep.finish("capped", manifest, *generation, check=False)["stderr"]
+ if cancel:
+ deep.command("cancel-scan", "--thread-id", "thread-deep-scan")
+ final = deep.read("thread-deep-scan")
+ assert (final["status"], final["error"]) == ("canceled", None)
+ else:
+ final = deep.command("fail-deep-scan", "--message", "Cleanup failed.", *generation)[
+ "deepScan"
+ ]
+ assert final["error"] == (expected or "Cleanup failed.")
+ assert final["workers"][0]["error"] == message
+
+
@pytest.mark.cross_platform
def test_expired_generation_cannot_mutate_recovered_scan(tmp_path: Path) -> None:
deep = start_empty_target_scan(tmp_path)
diff --git a/sdk/typescript/docs/cli.md b/sdk/typescript/docs/cli.md
index 14f6589a6..f7ae7402b 100644
--- a/sdk/typescript/docs/cli.md
+++ b/sdk/typescript/docs/cli.md
@@ -1145,8 +1145,12 @@ report and lists unvalidated candidates as follow-up work. Reaching a configured
limit with a valid finalized report returns `0` by default, or `1` if findings
meet a configured failure threshold.
-When Codex reports an exhausted usage limit, Deep Scan cancels active workers
-and stops retrying or launching replacements. Completed worker artifacts are retained.
+When a worker turn fails with a known cybersecurity policy refusal or an
+exhausted usage limit, Deep Scan stops retries and replacements, cancels active
+siblings, and retains completed worker artifacts. A capability check can succeed
+before a later request is refused. Use `scans show SCAN_ID` to inspect the failed
+scan and its retained results. To run it again from a saved recipe, use
+`scans rerun SCAN_ID`, which starts fresh discovery.
At 80% of a single interactive scan's limit, the dashboard offers a higher total
budget. Enter a larger total, or leave it blank/press Escape to keep the limit.