arch(ws-13): add host cancellation accessor

[henrypark133]

Context

Cancellation observation branch. It gives the planned loop a host-owned cancellation signal without mixing cancellation state into normal chat history or strategy internals.

Master spec: docs/reborn/agent-loop-skeleton.md
Workstream brief: docs/reborn/agent-loop-briefs/host-cancellation-accessor.md
Stack base: arch/ws-8

Latest stack maintenance on 2026-05-14:

• Rebased this branch onto its current stack base after the WS0 prompt-authority fix and the follow-up WS8/WS14-parent/WS16/WS17 conflict resolutions.
• Pushed the updated branch with force-with-lease where the remote already existed, or published it as a new branch where it did not.
• Verified the final ancestry chain from origin/reborn-integration through WS17 before publishing the PR descriptions.

What landed

• Host cancellation accessor/port shape for planned loop execution.
• Executor observation of host cancellation at the defined cancellation boundaries.
• Fail-closed/inert fallback labeling so missing cancellation wiring is explicit.
• Tests for cancellation access and executor behavior through the real support boundary.
• Integration fixes for current WS8 test-support and host wiring.

Reviewer focus

• Cancellation should be observed through host/runtime authority, not synthesized by prompt or model output.
• A missing cancellation source should be explicit and safe.
• Cancellation exits still require the same evidence/checkpoint discipline as other loop exits.

Non-goals / deferred work

• Product inbound cancellation test coverage lands in WS17.
• Progress event durability is WS12.
• Default runtime composition is WS16.

Validation

• cargo test -p ironclaw_loop_support cancellation_port
• cargo check -p ironclaw_agent_loop --features test-support
• git diff --check
• Included in arch/ws-14-parent validation: multi-crate cargo check with ironclaw_agent_loop/test-support.

Stack position

[#3550 ws-0] state/checkpoint foundation -> reborn-integration
   |-- #3551 ws-1 strategy alpha -> ws-0
   |-- #3552 ws-2 strategy beta -> ws-0
   |-- #3553 ws-3 strategy gamma -> ws-0
   |-- #3643 ws-3.5 loop family registry -> ws-0
   '-- #3554 level1-merged -> ws-0
         |-- #3555 ws-4 planner facade -> level1
         |-- #3556 ws-5 default strategies -> level1
         '-- #3557 level2-merged -> level1
               '-- #3596 ws-6a canonical executor -> level2
                     '-- #3597 ws-7 PlannedDriver adapter -> ws-6a
                           '-- #3598 ws-8 integration/test support -> ws-7
                                 |-- #3644 ws-9 capability host wiring -> ws-8
                                 |-- #3645 ws-10 checkpoint load/resume -> ws-8
                                 |-- #3646 ws-11 input port -> ws-8
                                 |-- #3647 ws-12 progress port -> ws-8
                                 |-- #3648 ws-13 cancellation accessor -> ws-8
                                 |-- #3649 ws-15 prompt/identity context -> ws-8
                                 '-- #3650 ws-14-parent integrated host ports -> ws-8
                                       '-- #3651 ws-14 planned default registration -> ws-14-parent
                                             '-- #3652 ws-16 live runtime wiring -> ws-14
                                                   '-- #3653 ws-17 product live cutover -> ws-16

[gemini-code-assist]

Code Review

This pull request implements a cancellation mechanism for the agent loop, introducing a LoopCancellationPort trait and integrating frequent checks within the CanonicalAgentLoopExecutor. It also provides infrastructure for managing cancellation signals and updates relevant host implementations. Feedback suggests refactoring the repetitive cancellation check logic using a macro to improve maintainability. Additionally, it is recommended to utilize the metadata within the LoopCancellationSignal rather than hardcoding exit reasons and to ensure the request method is idempotent to align with the trait's contract.

[gemini-code-assist]

This cancellation check pattern is repeated over 15 times throughout the executor. This significant duplication makes the code harder to read and maintain. Consider introducing a macro or a more flexible helper to encapsulate this logic. Since the return type varies across different functions (e.g., Ok(exit), Ok(ModelStep::Exit(exit)), Ok(BatchStep::Exit(exit))), a macro that accepts an optional exit wrapper could be effective for reducing this boilerplate.

[gemini-code-assist]

The LoopCancellationSignal returned by host.observe_cancellation() is currently ignored (using _signal). This signal contains valuable metadata such as the reason_kind (e.g., UserRequested, Policy) and the requested_at timestamp. By ignoring it here and hardcoding LoopCancelledReasonKind::HostCancellation in cancelled_exit, the specific reason for cancellation is lost in the loop's exit status and transcript. Consider passing the signal to cancelled_exit to allow for more precise reason mapping.

[gemini-code-assist]

The request method should be idempotent to satisfy the LoopCancellationPort contract, which states that repeated calls to observe_cancellation must return the same signal. Currently, multiple calls to request will overwrite the signal and update the timestamp. It is recommended to check if the cancellation has already been fired before updating the signal to ensure the first request's metadata is preserved.

    pub fn request(&self, reason_kind: LoopCancelReasonKind) {
        if self.fired.load(Ordering::Acquire) {
            return;
        }
        let mut signal_lock = self.signal.write();
        if signal_lock.is_some() {
            return;
        }
        let signal = LoopCancellationSignal {
            reason_kind,
            requested_at: Utc::now(),
        };
        *signal_lock = Some(signal);
        self.fired.store(true, Ordering::Release);
    }

[serrrfirat]

Summary

Reviewed WS13 PR #3648 only.
Base cbdd70890afb200cdfe47076b23a885f0c70cd8c → head 898fa47c178c8093d8df52b7b24ae15379695b4f.

Cancellation probes can discard already-completed model/capability work, and cancellation signal handle does not latch first signal.

Validation:

• cargo check -p ironclaw_reborn ✅

Findings

#	Sev	Category	File:Line	Issue	Fix suggestion
1	High	Correctness / Async ordering	crates/ironclaw_agent_loop/src/executor.rs:210-220	Cancellation is checked after stream_model() returns but before finalize_assistant_message(). If cancel fires while model call is in flight, executor exits cancelled and drops completed reply instead of persisting already-returned model output.	Move cancellation checks to before starting externally visible work, or after applying returned work to state. Add test: cancel after model response before finalize still preserves reply or follows explicit policy.
2	High	Correctness / Async ordering	crates/ironclaw_agent_loop/src/executor.rs:484-512	Cancellation is checked after invoke_capability_batch() returns and between draining returned outcomes. If cancel fires during batch execution, executor can exit before recording some/all completed outcomes.	Do not cancel between completed side effect and state application. Drain/apply returned outcomes first, then observe cancellation before next external work. Add batch-return/mid-drain cancel tests.
3	Medium	Concurrency / Contract	crates/ironclaw_loop_support/src/cancellation_port.rs:23-30, crates/ironclaw_turns/src/run_profile/host.rs:1407-1410	RunCancellationHandle::request() overwrites stored signal on every call, but LoopCancellationPort contract says reads must be idempotent and return the same signal after first fire. Repeated cancel requests can mutate reason_kind/requested_at after observers saw first signal.	Latch first signal only (get_or_insert/CAS-style), and add repeated-request test proving first signal is preserved.

Security/data-flow notes

• Scope leak not found in cancellation accessor; issue is async ordering and idempotent evidence.

Missing tests

• Cancel after model response but before reply finalize.
• Cancel after capability batch returns but before/while outcomes drain.
• Duplicate request() preserves first signal.

[zmanian]

Review notes — WS13 cancellation accessor

Pull-based cooperative cancellation with AtomicBool + snapshot is the right primitive for boundary checking — cheap, non-blocking, idempotent. RunCancellationObservationKind::{LiveCapable, InertFallback} makes the inert-default observable rather than silently no-op. Strict vs permissive require_final_checkpoint is honored correctly (cancellation under strict maps to Failed/CheckpointRejected, not silent cancel). Two items to resolve.

Cooperative-only — document the limitation

build_prompt_bundle, stream_model, and invoke_capability are awaited to completion before the next observation. A stuck model stream or capability call will ignore cancellation indefinitely. The brief scopes this to "boundary observation," but the limitation needs to be discoverable from the code, not just the brief — a doc comment on LoopCancellationPort (or on checkpoint_and_exit_if_cancelled) stating "cancellation is not preempted across in-flight host calls" would prevent future readers from assuming preemption.

WS16 wiring will need to compose this with a stream-level abort if true preemption is wanted.

Reconcile with WS6a's Cancelled variant

WS6a (#3596) declared AgentLoopExecutorError::Cancelled but never constructs it; host Cancelled errors get mapped to ModelErrorClass::Transient. WS13 is the natural place to construct that variant — your boundary check has the signal. Either:

1. Have checkpoint_and_exit_if_cancelled return AgentLoopExecutorError::Cancelled on cancellation (rather than the current bare LoopExit::Cancelled path), so the executor's error taxonomy is consistent, or
2. Coordinate with arch(ws-6a): add canonical loop executor #3596 to remove the dead variant.

Either way, WS6a + WS13 + WS14-parent should converge on cancellation semantics before WS16 wires more.

Minor

• interrupted_message_refs: Vec::new() is always empty — // TODO(WS-17) marker would clarify future intent.
• with_cancellation_factory takes Arc<F> then re-coerces to Arc<dyn> — simplify the signature.
• chrono added to two crates just for DateTime<Utc> in the signal — SystemTime would have avoided the dep churn.

Test coverage (pre-iteration, mid-loop, permissive checkpoint failure, strict checkpoint failure, port-level concurrent visibility) is solid.

[henrypark133]

Follow-up from the ws-6a review pass on #3596:

#3596 now handles cancellation that is already returned through model/capability host calls: capability cancelled failures checkpoint and return a terminal LoopExit::Cancelled, while host-level cancelled errors remain unrecoverable when no trustworthy loop exit can be produced.

This WS13 cancellation-accessor PR still owns cancellation observation between strategy/host calls. Please keep tests for the between-call boundaries (planned_driver_cancels_between_strategy_calls, planned_driver_cancels_mid_batch_recovery_loop or equivalent) and document the below-loop boundary: aborting an already in-flight capability invocation requires cooperation from the capability host/runtime, not just the executor polling a cancellation accessor.

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f08aad958a

ℹ️ 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".

[chatgpt-codex-connector]

Return executor error instead of invalid Failed exit here

When cancellation is observed under a profile with require_final_checkpoint = true, this fallback emits LoopExit::failed(...) without a checkpoint ID. validate_failed_exit in crates/ironclaw_turns/src/loop_exit.rs still requires a verified final checkpoint for strict profiles, so this exit is guaranteed to be flagged as MissingFinalCheckpoint and remapped as a protocol violation rather than a trusted CheckpointRejected failure. In practice, the strict-path fallback here cannot produce the “well-formed” terminal result it intends; it should surface an executor/host error (or another path that preserves strict checkpoint guarantees) instead.

Useful? React with 👍 / 👎.

[serrrfirat]

Review findings

1. crates/ironclaw_agent_loop/src/executor.rs:954

Strict-profile cancellation fallback returns LoopExit::failed(..., checkpoint_id: None) when final checkpoint write fails. validate_failed_exit still requires a verified final checkpoint for strict profiles, so this becomes MissingFinalCheckpoint / protocol violation instead of the intended trusted CheckpointRejected failure. This is already covered by the current inline Codex comment on the PR, and I agree with it. Return an executor/host error or another path that preserves strict checkpoint guarantees.

2. crates/ironclaw_agent_loop/src/executor.rs:194-200 and crates/ironclaw_agent_loop/src/executor.rs:321-328

Cancellation can now exit while pending_input_ack is queued. After drain_user_inputs or drain_followup, the state cursor is advanced and an ack cursor is stored, but the new cancellation probe can write the final checkpoint and return before pending_input_ack.ack(host) runs. That leaves consumed steering/follow-up input unacked even though the terminal checkpoint made the cursor durable, so the input can be redelivered or remain stuck depending on the host queue. Fix by threading pending acks into the cancellation exit path, or avoid cancellation exits between input drain and the ack that follows the durable checkpoint. Add a regression where cancellation fires during/after poll_inputs.

Reviewed read-only against f08aad958a. I did not run tests.

[serrrfirat]

Split the follow-up fixes out of this PR into a small stacked set so this PR can stay focused on WS13:

1. fix(ws-13): verify cancellation from turn state #3684 — durable cancellation evidence fix

   • Base: arch/ws-13
   • Scope: addresses the original review finding by making cancellation evidence read durable turn state.

2. fix(ws-13): wire live cancellation into host #3685 — live cancellation wiring

   • Base: codex/ws13-cancel-evidence
   • Scope: wires the turn-state-backed cancellation factory through the Reborn text host and coordinator wake path.

3. fix(ws-13): ack drained inputs before cancel exit #3686 — cancel-exit ack safety

   • Base: codex/ws13-live-cancel-wiring
   • Scope: keeps input ack behavior correct when cancellation is observed after draining steering/follow-up input.

The current PR should remain the stack anchor; the additional behavior is now isolated in the follow-up PRs.