Skip to content

Commit af6a661

Browse files
zknprclaude
andcommitted
fix(codex): close the claim-to-turn cancellation window with a two-sided handshake (PR #346 review P1)
Between the worker's claim releasing the state lock and the turn existing on the shared app-server, /codex:cancel could only kill the worker pid — too late when the turn dispatch raced ahead, so writes could land after the user saw cancellation succeed. The handoff is now linearized through the locked job stores: the worker revalidates after claim, stamps a STARTING marker immediately before turn/start, publishes the first turn id to both stores before accepting any turn events, and self-interrupts through its own live app-server client when cancellation won in the window. Cancellation records first, then waits for suppression or terminal turn confirmation before killing the worker or reporting success — so a reported cancel means side effects have ceased, and a missing confirmation fails visibly instead of claiming success. Both task and review workers inherit this via the shared claimed-worker path. Residual boundary: the app-server-internal gap between accepting a start request and publishing its first turn id — uninterruptible by any client; covered by withholding cancel success until terminal turn/completed. Co-Authored-By: Claude Fable 5 <[email protected]>
1 parent 3c9bdd6 commit af6a661

8 files changed

Lines changed: 1241 additions & 66 deletions

File tree

‎plugins/codex/scripts/codex-companion.mjs‎

Lines changed: 180 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,8 @@ import {
6969
import { buildTaskDispatchedStatusToken } from "./lib/task-status-token.mjs";
7070
import {
7171
commitSpawnedTaskWorker as commitSpawnedWorker,
72-
runClaimedTaskWorker as runClaimedWorker
72+
runClaimedTaskWorker as runClaimedWorker,
73+
WORKER_TURN_STATES
7374
} from "./lib/task-launch-state.mjs";
7475

7576
const ROOT_DIR = path.resolve(fileURLToPath(new URL("..", import.meta.url)));
@@ -78,6 +79,12 @@ const DEFAULT_STATUS_WAIT_TIMEOUT_MS = 240000;
7879
const DEFAULT_STATUS_POLL_INTERVAL_MS = 2000;
7980
const FOREGROUND_TASK_POLL_INTERVAL_MS = 100;
8081
const FOREGROUND_TASK_MISSING_JOB_RETRY_MS = 5000;
82+
const CANCEL_TURN_RESOLUTION_TIMEOUT_MS = 5000;
83+
const CANCEL_TURN_RESOLUTION_POLL_MS = 10;
84+
const TERMINAL_WORKER_TURN_STATES = new Set([
85+
WORKER_TURN_STATES.INTERRUPTED,
86+
WORKER_TURN_STATES.STOPPED
87+
]);
8188
const VALID_REASONING_EFFORTS = new Set(["none", "minimal", "low", "medium", "high", "xhigh", "ultra", "max"]);
8289
const MODEL_ALIASES = new Map([["spark", "gpt-5.3-codex-spark"]]);
8390
const STOP_REVIEW_TASK_MARKER = "Run a stop-gate review of the previous Claude turn.";
@@ -451,7 +458,8 @@ async function executeReviewRun(request) {
451458
const result = await runAppServerReview(request.cwd, {
452459
target: reviewTarget,
453460
model: request.model,
454-
onProgress: request.onProgress
461+
onProgress: request.onProgress,
462+
turnLifecycle: request.turnLifecycle
455463
});
456464
const payload = {
457465
review: reviewName,
@@ -483,6 +491,7 @@ async function executeReviewRun(request) {
483491
summary: firstMeaningfulLine(result.reviewText, `${reviewName} completed.`),
484492
jobTitle: `Codex ${reviewName}`,
485493
jobClass: "review",
494+
cancelled: result.cancelled,
486495
targetLabel: target.label
487496
};
488497
}
@@ -494,7 +503,8 @@ async function executeReviewRun(request) {
494503
model: request.model,
495504
sandbox: "read-only",
496505
outputSchema: readOutputSchema(REVIEW_SCHEMA),
497-
onProgress: request.onProgress
506+
onProgress: request.onProgress,
507+
turnLifecycle: request.turnLifecycle
498508
});
499509
const parsed = parseStructuredOutput(result.finalMessage, {
500510
status: result.status,
@@ -534,6 +544,7 @@ async function executeReviewRun(request) {
534544
summary: parsed.parsed?.summary ?? parsed.parseError ?? firstMeaningfulLine(result.finalMessage, `${reviewName} finished.`),
535545
jobTitle: `Codex ${reviewName}`,
536546
jobClass: "review",
547+
cancelled: result.cancelled,
537548
targetLabel: context.target.label
538549
};
539550
}
@@ -574,7 +585,8 @@ async function executeTaskRun(request) {
574585
persistThread: true,
575586
// Keep the workspace-boundary notice ephemeral by adding it only to turn input, not stored prompts or thread names.
576587
boundaryNote: request.write ? buildWorkspaceBoundaryNotice(workspaceRoot) : null,
577-
threadName: resumeThreadId ? null : buildPersistentTaskThreadName(request.prompt || DEFAULT_CONTINUE_PROMPT)
588+
threadName: resumeThreadId ? null : buildPersistentTaskThreadName(request.prompt || DEFAULT_CONTINUE_PROMPT),
589+
turnLifecycle: request.turnLifecycle
578590
});
579591

580592
const rawOutput = typeof result.finalMessage === "string" ? result.finalMessage : "";
@@ -609,6 +621,7 @@ async function executeTaskRun(request) {
609621
summary: firstMeaningfulLine(rawOutput, firstMeaningfulLine(failureMessage, `${taskMetadata.title} finished.`)),
610622
jobTitle: taskMetadata.title,
611623
jobClass: "task",
624+
cancelled: result.cancelled,
612625
write: Boolean(request.write)
613626
};
614627
}
@@ -1265,7 +1278,7 @@ async function handleClaimedWorker(argv, config) {
12651278
workspaceRoot,
12661279
jobId,
12671280
process.pid,
1268-
async (storedJob) => {
1281+
async (storedJob, turnLifecycle) => {
12691282
const request = storedJob.request;
12701283
if (!request || typeof request !== "object") {
12711284
throw new Error(`Stored job ${jobId} is missing its ${config.requestKind} request payload.`);
@@ -1289,7 +1302,8 @@ async function handleClaimedWorker(argv, config) {
12891302
() =>
12901303
config.executeRun({
12911304
...request,
1292-
onProgress: progress
1305+
onProgress: progress,
1306+
turnLifecycle
12931307
}),
12941308
{ logFile }
12951309
);
@@ -1432,19 +1446,6 @@ async function handleCancel(argv) {
14321446
const reference = positionals[0] ?? "";
14331447
const { workspaceRoot, job } = resolveCancelableJob(cwd, reference, { env: process.env });
14341448
const existing = readStoredJob(workspaceRoot, job.id) ?? {};
1435-
const threadId = existing.threadId ?? job.threadId ?? null;
1436-
const turnId = existing.turnId ?? job.turnId ?? null;
1437-
1438-
const interrupt = await interruptAppServerTurn(cwd, { threadId, turnId });
1439-
if (interrupt.attempted) {
1440-
appendLogLine(
1441-
job.logFile,
1442-
interrupt.interrupted
1443-
? `Requested Codex turn interrupt for ${turnId} on ${threadId}.`
1444-
: `Codex turn interrupt failed${interrupt.detail ? `: ${interrupt.detail}` : "."}`
1445-
);
1446-
}
1447-
14481449
const completedAt = nowIso();
14491450
const cancellation = updateJobStores(workspaceRoot, job.id, ({ stateJob, storedJob }) => {
14501451
const latestStateJob = stateJob ?? job;
@@ -1464,14 +1465,38 @@ async function handleCancel(argv) {
14641465
storedJob: { ...nextJob, cancelledAt: completedAt },
14651466
value: {
14661467
nextJob,
1467-
pid: latestStoredJob.pid ?? latestStateJob.pid ?? job.pid ?? Number.NaN
1468+
pid: latestStoredJob.pid ?? latestStateJob.pid ?? job.pid ?? Number.NaN,
1469+
threadId: nextJob.threadId ?? null,
1470+
turnId: nextJob.turnId ?? null,
1471+
turnLifecycle: nextJob.turnLifecycle ?? null
14681472
}
14691473
};
14701474
});
14711475
const { nextJob, pid } = cancellation.value;
1472-
terminateProcessTree(pid);
14731476
appendLogLine(nextJob.logFile ?? job.logFile, "Cancelled by user.");
14741477

1478+
const interrupt = await resolveCancelledJobTurn(cwd, workspaceRoot, job.id, {
1479+
...nextJob,
1480+
threadId: cancellation.value.threadId,
1481+
turnId: cancellation.value.turnId,
1482+
turnLifecycle: cancellation.value.turnLifecycle
1483+
});
1484+
if (interrupt.attempted) {
1485+
appendLogLine(
1486+
nextJob.logFile ?? job.logFile,
1487+
interrupt.interrupted
1488+
? `Requested Codex turn interrupt for ${interrupt.turnId} on ${interrupt.threadId}.`
1489+
: `Codex turn interrupt failed${interrupt.detail ? `: ${interrupt.detail}` : "."}`
1490+
);
1491+
}
1492+
if (!interrupt.confirmed) {
1493+
const errorMessage = `Cancellation was recorded for ${job.id}, but the Codex turn could not be confirmed stopped${interrupt.detail ? `: ${interrupt.detail}` : "."}`;
1494+
appendLogLine(nextJob.logFile ?? job.logFile, errorMessage);
1495+
throw new Error(errorMessage);
1496+
}
1497+
1498+
terminateProcessTree(pid);
1499+
14751500
const payload = {
14761501
jobId: job.id,
14771502
status: "cancelled",
@@ -1483,6 +1508,140 @@ async function handleCancel(argv) {
14831508
outputCommandResult(payload, renderCancelReport(nextJob), options.json);
14841509
}
14851510

1511+
async function resolveCancelledJobTurn(cwd, workspaceRoot, jobId, initialJob) {
1512+
const deadline = Date.now() + CANCEL_TURN_RESOLUTION_TIMEOUT_MS;
1513+
let latestJob = initialJob;
1514+
let lastInterrupt = null;
1515+
1516+
while (true) {
1517+
const lifecycle = latestJob?.turnLifecycle ?? null;
1518+
const lifecycleState = lifecycle?.state ?? null;
1519+
const threadId = latestJob?.threadId ?? lifecycle?.threadId ?? null;
1520+
const turnId = latestJob?.turnId ?? lifecycle?.turnId ?? null;
1521+
1522+
if (
1523+
lifecycleState === WORKER_TURN_STATES.INTERRUPTED ||
1524+
lifecycleState === WORKER_TURN_STATES.STOPPED
1525+
) {
1526+
return {
1527+
attempted: true,
1528+
// Preserve the public field's existing meaning: at least one interrupt
1529+
// RPC was accepted. The separate lifecycle state is the stronger proof
1530+
// that the worker observed terminal turn completion.
1531+
interrupted:
1532+
lifecycleState === WORKER_TURN_STATES.INTERRUPTED || Boolean(lastInterrupt?.interrupted),
1533+
confirmed: true,
1534+
threadId,
1535+
turnId,
1536+
detail: lifecycle.detail ?? `Worker interrupted ${turnId} on ${threadId}.`
1537+
};
1538+
}
1539+
1540+
if (
1541+
lifecycleState === WORKER_TURN_STATES.SUPPRESSED ||
1542+
lifecycleState === WORKER_TURN_STATES.START_REJECTED
1543+
) {
1544+
return {
1545+
attempted: false,
1546+
interrupted: false,
1547+
confirmed: true,
1548+
threadId,
1549+
turnId,
1550+
detail:
1551+
lifecycleState === WORKER_TURN_STATES.SUPPRESSED
1552+
? "turn start was suppressed"
1553+
: "app-server rejected turn start"
1554+
};
1555+
}
1556+
1557+
if (threadId && turnId && !lastInterrupt) {
1558+
lastInterrupt = await interruptAppServerTurn(cwd, { threadId, turnId });
1559+
if (!lastInterrupt.interrupted && lifecycleState !== WORKER_TURN_STATES.INTERRUPTING) {
1560+
return {
1561+
...lastInterrupt,
1562+
confirmed: false,
1563+
threadId,
1564+
turnId
1565+
};
1566+
}
1567+
}
1568+
1569+
// STARTING is durable before the RPC is sent. Do not kill its worker or
1570+
// report cancellation success until one side has interrupted the published
1571+
// turn, suppressed the request, or proved that the server rejected it.
1572+
const handoffPending =
1573+
lifecycleState === WORKER_TURN_STATES.STARTING ||
1574+
lifecycleState === WORKER_TURN_STATES.STARTED ||
1575+
lifecycleState === WORKER_TURN_STATES.INTERRUPTING ||
1576+
lifecycleState === WORKER_TURN_STATES.START_UNKNOWN;
1577+
if (!handoffPending) {
1578+
return {
1579+
attempted: Boolean(lastInterrupt?.attempted),
1580+
interrupted: false,
1581+
confirmed: !lastInterrupt,
1582+
threadId,
1583+
turnId,
1584+
detail: lastInterrupt?.detail ?? "no Codex turn was handed off"
1585+
};
1586+
}
1587+
1588+
if (Date.now() >= deadline) {
1589+
return {
1590+
attempted: Boolean(lastInterrupt?.attempted),
1591+
interrupted: false,
1592+
confirmed: false,
1593+
threadId,
1594+
turnId,
1595+
detail: lastInterrupt?.interrupted
1596+
? "turn interrupt was accepted, but terminal turn completion was not observed"
1597+
: lastInterrupt?.detail ?? "timed out waiting for the worker turn-start handshake"
1598+
};
1599+
}
1600+
1601+
await sleep(CANCEL_TURN_RESOLUTION_POLL_MS);
1602+
latestJob = readConsistentCancellationHandshake(workspaceRoot, jobId) ?? latestJob;
1603+
}
1604+
}
1605+
1606+
function readConsistentCancellationHandshake(workspaceRoot, jobId) {
1607+
const transaction = updateJobStores(workspaceRoot, jobId, ({ stateJob, storedJob }) => {
1608+
if (!stateJob || !storedJob) {
1609+
return { value: storedJob ?? stateJob };
1610+
}
1611+
1612+
const terminalSource = [stateJob, storedJob].find((candidate) =>
1613+
TERMINAL_WORKER_TURN_STATES.has(candidate.turnLifecycle?.state)
1614+
);
1615+
if (terminalSource && stateJob.status === "cancelled" && storedJob.status === "cancelled") {
1616+
// A process can stop between the two atomic file replacements. Repair the
1617+
// unfinished side while holding the same lock, then let /cancel terminate
1618+
// the worker only after both stores carry the terminal acknowledgement.
1619+
const repairedJob = {
1620+
...storedJob,
1621+
...stateJob,
1622+
...terminalSource,
1623+
status: "cancelled",
1624+
phase: "cancelled",
1625+
pid: null,
1626+
turnLifecycle: terminalSource.turnLifecycle
1627+
};
1628+
return {
1629+
stateJob: repairedJob,
1630+
storedJob: repairedJob,
1631+
value: repairedJob
1632+
};
1633+
}
1634+
1635+
return {
1636+
value: {
1637+
...storedJob,
1638+
...stateJob
1639+
}
1640+
};
1641+
});
1642+
return transaction.value;
1643+
}
1644+
14861645
async function main() {
14871646
const [subcommand, ...argv] = process.argv.slice(2);
14881647
if (!subcommand || subcommand === "help" || subcommand === "--help") {

0 commit comments

Comments
 (0)