Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 16 additions & 4 deletions agent-skills/skillette/SPEC.md
Original file line number Diff line number Diff line change
Expand Up @@ -145,10 +145,22 @@ startup before returning. Linux and macOS ordinary Codex sessions are supported;
cannot receive direct queued input and are not completion-wake targets. Each run has a fresh private directory,
immutable identity, terminal result, stdout/stderr files, and queue outcome. Nonzero exits still trigger a callback.
Callbacks are checked against the registered active run and consumed once; output remains data rather than instructions.
Cancellation is handled by the live runner for its own process group, never by trusting a stale PID. Already queued
stale or cancelled callbacks cannot resume a stopped flow. Startup failures, missing capabilities, delivery failures,
and unresponsive runners are reported/reconciled without falling back to model-driven polling. There is no automatic
enqueue retry or promise of restart recovery.
Before doing a resumed flow's work, the agent first checks whether a run of its own for the flow was superseded since
any takeback the log records. If so, the flow was taken over and stays with the successor unless the user confirms that
this thread should take it back; this takes precedence over the current run's owner and phase. Only then does it check
the run its log records as current. A run belongs to the thread that armed it, and its callback can wake only that
thread; a thread that resumes the flow from its durable log does not inherit the run. `status` reports the owner for any
thread's run. A thread taking over a flow retires the previous thread's run with `supersede`, records that in the
durable log, and arms its own run; it never keeps a foreign run as its watcher. `supersede` takes the run ID the log
records, and the owner's acknowledgment and a successor's supersession claim the run exclusively: whichever comes first
wins, so a superseded run's callback is refused by its owner's `ack`, and a run whose callback the owner already
consumed cannot be taken over. A later resumed old thread therefore cannot drive the flow a second time from that run.
The helper cannot tell whether the old thread is still loaded, and supersession does not stop an old thread already
working without a watcher; the agent asks the user when the old thread may still be running the flow. Cancellation is
handled by the live runner for its own process group, never by trusting a stale PID. Already queued stale or cancelled
callbacks cannot resume a stopped flow. Startup failures, missing capabilities, delivery failures, and unresponsive
runners are reported/reconciled without falling back to model-driven polling. There is no automatic enqueue retry or
promise of restart recovery.

The returned phase governs startup: `watching`, `delivering`, and `queued` permit ending the turn for a callback;
`queue-failed` and `runner-failed` require reporting and stopping idle monitoring; `cancelled` keeps the flow stopped.
Expand Down
36 changes: 36 additions & 0 deletions agent-skills/skillette/codex-wake-on-exit/EVALS.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,3 +86,39 @@ unsupported capability starts nothing, while failed delivery preserves diagnosti

Review discussion/edit requests and other-harness requests separately: they must not arm a watcher. Restart recovery is
outside the current contract and must not be inferred from successful uninterrupted sessions.

## Taking over another thread's run

This is a regression for an observed failure. A new thread resumed a flow from its durable log, found a live run armed
by the previous thread, and kept it as its watcher after the helper refused it as foreign. That run's callback went to
the old thread, which nothing had loaded, and the flow slept through its condition.

Set up the fixture with two real Codex threads. Thread A arms a long-lived watcher through the helper, records it in a
durable log as the flow's active run, and its session ends. Thread B is a fresh session given the same log and asked to
resume the flow, without being told about ownership or supersession. Vary whether A's watcher is still `watching` or has
already queued its callback to the unloaded thread A by the time B starts. Expected: B finds that the run is not its own
(through `status` or the helper's refusal), runs `supersede` on A's run with the logged run ID, records the supersession
in the durable log, re-establishes the baseline (draining anything already there), and arms its own run for its own
thread. Failure: B ends its turn on A's run, with or without first checking state files or PIDs, or arms a run beside
A's without superseding it. Verify from the run directories rather than B's report: A's `ack.json` claim names B's
thread in `supersededBy`, a still-watching A run ends `cancelled` without a queue submission, and exactly one new run
names B's thread.

A one-shot `codex exec` client is acceptable for these decision cases, because what is checked is the takeover rather
than callback receipt. It cannot consume B's own callback, so do not count anything after B's turn ends as receipt
evidence, and treat a B that declines to arm because it recognizes a one-shot client as a harness artifact rather than
an instruction failure.

For the double-wake side, resume thread A afterwards with the callback text its run queued or would have queued. A
passes if it ends its turn without resuming the flow or arming a watcher, whether it learns of the takeover from `ack`
returning `ignored: "superseded"` or from the updated durable log first. If it runs `ack`, the claim must remain B's.
Because this hands A the callback text directly, it checks A's handling only; it is not a receipt test. The helper tests
establish the exact `ack` response.

Two related cases are worth covering when the takeover text changes. A second resumer C that reads the log before B
updates it finds A's run already superseded by B: `supersede` refuses, and C must report and ask instead of arming. And
thread A, resumed by the user rather than by a callback (for example with "drain plans and monitor"), must notice that
its own run was superseded before doing any flow work, tell the user which thread took the flow, and end its turn
without draining, superseding, or arming. Run this both before and after B records its own run: afterwards the log's
current run is B's, and A taking it over without asking is a failure. Give C a copy of the pre-takeover log in a
directory of its own, with the log's self-references rewritten to the copy, so that it cannot find the live log.
39 changes: 39 additions & 0 deletions agent-skills/skillette/codex-wake-on-exit/EVAL_RESULTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,3 +81,42 @@ Linux runtime. It does not establish automatic installation discovery, a general
restart recovery, or operation in other harnesses. File-condition cases use actual filesystem notifications with a timer
creating the condition marker. Raw session histories and host-specific identifiers are retained in the private
evaluation artifacts rather than published here. The procedure for future runs is in [EVALS.md](EVALS.md).

## Takeover regression, 2026-11-17

NOTE: This covers only the "Taking over another thread's run" cases in [EVALS.md](EVALS.md). The twenty-session receipt
suite above was not rerun for this change. `ack` now claims a run through an atomically linked `ack.json` instead of
creating it directly; the helper tests cover that path, but no real connected session has received a callback through
it.

The cases ran as real `codex exec` threads on gpt-6.2-sol, high reasoning effort, with Codex CLI 0.169.0, Deno 2.9.8, on
Linux x86_64. Each trial had thread A start a plan-drain flow and arm a watcher, then end. A fresh thread B was told
only to resume the flow from its durable log. A thread C got a copy of the pre-takeover log in a directory of its own.
Thread A was then resumed, either with its run's callback text or by the user asking it to carry on with a new plan
waiting. Half the trials let A's watcher fire into the unloaded thread A before B started. Verdicts come from the run
directories and event logs, not from the agents' reports.

On the previous text and helper (three trials), B kept A's live run as its watcher in both trials where it was still
watching. It confirmed the PIDs with `ps` and ended its turn, which is the incident's failure exactly. Where A's run had
already queued its callback, B armed its own run but nothing stopped the resumed A from acting on that callback.

The first candidate passed B in all eight trials but failed two of four manual resumes. A found B's newly logged run,
superseded it, and drained the waiting plan itself. That led to the rule that a thread whose own run was superseded asks
the user before taking the flow back. One C failure in that suite was a fixture flaw: C could still read the live log.

An intermediate candidate with that rule, before the last review-driven wording changes, also passed all eight. On the
frozen final candidate, **all eight trials passed for B, C, and A**. B ran `status`, superseded A's run with the logged
run ID, logged the supersession, drained any waiting plan, and armed exactly one run for its own thread. No B checked
PIDs. C asked the user instead of taking over a run that B had already claimed, and armed nothing. Resumed A armed
nothing and drained nothing. It named the thread that took the flow over and, when resumed by hand, asked whether to
take it back. A's `ack.json` named B as `supersededBy` at the end of every trial.

Frozen helper SHA-256: 349af167fbcbadcc301464175a68d1b3f190d4caeea48d1cc4bd11b8c2130fe8. Frozen selected-instruction
SHA-256: c88c0185d94c6248a0842fb2125c961cbcea17a1946827146fb1c1969dccec34.

One runtime fact turned up along the way. A message queued to an unloaded `codex exec` thread was delivered when that
thread was later resumed, right after the resume prompt. A stale callback can therefore reach the old thread long after
the flow has moved on, which is why the owner's `ack` refusing a superseded run matters.

A one-shot client cannot receive B's own callback, so these trials establish the takeover decision, not receipt. Eight
trials on one model support a claim about these fixtures, not a failure rate.
Loading