fix(stella-cli): record a deliberate stop distinctly on the unsupervised writers too (#1826)

[macanderson]

Problem

PR #1828 (#1653) taught the supervised registry writers (daemon::outcome_status and its callers) to record SessionStatus::Stopped for a policy stop — but SessionPresence::finish(ok: bool, …) and its three call sites still collapsed the outcome to a bool on the way in. On a supervised run this was masked, because record_outcome_if_supervised writes after finish and corrects it. On an unsupervised headless run (a pipe, CI, --foreground) there is no later write: a deliberate stop (AbortKind::DeliberateStop — stuck-loop escalation, step cap, enforced budget, ended scope review; exit 3) aged into the SESSIONS overlay as Error, indistinguishable from a crash.

Approach

Mirrors #1828's shape: widen the writer past the bool, and keep one decider.

• crates/stella-cli/src/agent/outcome.rs — pipeline_session_status, the fifth projection the module doc now names: Result<PipelineOutcome, PipelineRunError> → terminal SessionStatus, routed through crate::daemon::outcome_status rather than re-matched, so every registry writer — supervised or not — reads a deliberate stop (Stopped), a user interrupt (Cancelled), and a crash (Error) off the same function.
• crates/stella-cli/src/agent/presence.rs — SessionPresence::finish now takes the projected SessionStatus; one_shot_notification words the inbox entry by how the run actually ended (a policy stop notifies "run stopped by policy", an interrupt "run cancelled" — "FAILED" for a deliberate stop was the same dishonesty the status carried; the issue delegated this wording decision).
• Call sites: agent.rs (pipeline one-shot — projects the PipelineStatus it holds; the interactive exit passes Complete explicitly), agent/goal.rs raw one-shot (feeds its Result<(), CliFailure> straight to outcome_status, the same idiom as agent/resume.rs).
• agent/goal.rs goal loop: audited — its Result<(), String> has no room for the abort kind (the run_resume answers with a String, so a resumed turn's deliberate stop cannot exit 3 #1637 collapse one level deeper), so a policy-stopped goal round still records Error; it now at least projects through outcome_status so an interrupt records Cancelled. Filed as The goal loop and the deck's lead turn answer with a String, so their terminal writers cannot record a policy stop #1862, cited at the call site.
• Deck session_exit (command_deck.rs:2123): audited, unchanged — run_lead_turn returns the same stringly Result<(), String>, so the deck cannot see a deliberate stop today; covered by The goal loop and the deck's lead turn answer with a String, so their terminal writers cannot record a policy stop #1862 (and command_deck.rs is a god file closed to growth).
• daemon.rs: the record_outcome_if_supervised doc said the presence "sees only a bool" — now stale, updated (stale comments are bugs).

God files: agent.rs sits at its exact 2269-line ceiling and this diff keeps it at exactly 2269 (all edits line-neutral); new logic lands in agent/outcome.rs and agent/presence.rs, the siblings the issue names.

Witness

outcome::tests::an_unsupervised_deliberate_stop_projects_stopped_not_error — a deliberate stop projects Stopped, a crash Error (plus the_remaining_terminal_arms_project_unchanged pinning Complete and the hard-error arm). The witness is structural, mirroring #1828's own (daemon::tests::a_deliberate_stop_records_a_status_distinct_from_a_crash, whose doc says "on the old signature this test does not even compile"): on main, pipeline_session_status does not exist and the widened finish call sites do not compile, so the fail-on-old is a compile failure rather than an assertion failure. On the old code the collapse is visible in source: finish wrote if ok { Complete } else { Error } — a deliberate stop could not reach any other status.

Verification

• cargo test -p stella-cli --bin stella -j 2 — 1429 passed, 0 failed (includes the new witnesses, daemon::tests, and the goal tests).
• cargo clippy -p stella-cli -j 2 --all-targets -- -D warnings — clean (with main's pre-existing stella-pipeline lint patched locally, see below).
• cargo fmt -p stella-cli -- --check — clean; check-file-size — agent.rs unchanged at its exact ceiling.

Main-side gate note: main was red on three pre-existing gate steps when this branch was cut (clippy clone_on_copy in stella-pipeline — which masked a second field_reassign_with_default error behind it — file-size ceilings for event.rs/deck_render.rs, and gate-parity). All three were fixed on main by #1894 (my parallel unbreak #1873 was superseded and is closed with zero diff). This branch has since had main merged in and its CI runs against the green tip; it contains none of those failures and none of their fixes.

Closes #1826
Refs #1653
Refs #1862

Summary by Sourcery

Ensure unsupervised runs record distinct session statuses for deliberate policy stops, user interrupts, and crashes, aligning all registry writers on a single outcome projection.

Bug Fixes:

• Fix unsupervised headless runs incorrectly recording deliberate policy stops as generic errors in the SESSIONS registry.

Enhancements:

• Add a shared projection from pipeline outcomes to terminal session status so supervised and unsupervised writers use the same outcome classification.
• Improve headless inbox notification wording to reflect whether a run completed, was stopped by policy, cancelled, or genuinely failed.

Tests:

• Add tests confirming the new pipeline-to-session status projection distinguishes deliberate stops from crashes and preserves existing terminal states.

[sourcery-ai]

Sorry @macanderson, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
stella-cli-docs	Ignored	Preview	Aug 6, 2026 6:35pm

[sourcery-ai]

Reviewer's Guide

Unifies how terminal session status is derived and recorded for both supervised and unsupervised runs so deliberate policy stops are distinguished from crashes, by widening the SessionPresence finish API to take a SessionStatus, adding a shared pipeline→SessionStatus projection, updating call sites and notifications, and adding tests to lock in the behavior.

Sequence diagram for unified terminal session status derivation in unsupervised runs

sequenceDiagram
    participant Agent as run_pipeline_one_shot
    participant Outcome as pipeline_session_status
    participant Daemon as daemon::outcome_status
    participant Presence as SessionPresence
    participant Registry as registry.upsert

    Agent->>Outcome: pipeline_session_status(&result)
    Outcome->>Daemon: outcome_status(terminal.as_ref().map(|_| ()))
    Daemon-->>Outcome: SessionStatus
    Outcome-->>Agent: SessionStatus

    Agent->>Presence: one_shot_notification(status, run_secs, prompt)
    Presence-->>Agent: Option<(String, String)>

    Agent->>Presence: finish(status, notify)
    Presence->>Registry: upsert(&self.record)

    alt AbortKind::DeliberateStop
        Note over Daemon,Presence: outcome_status → SessionStatus::Stopped
    else AbortKind::Failure
        Note over Daemon,Presence: outcome_status → SessionStatus::Error
    end

Loading

File-Level Changes

Change	Details	Files
Introduce a shared projection from pipeline results to terminal SessionStatus used by unsupervised writers.	Document PipelineStatus as now being projected a fifth way into a terminal SESSIONS-registry status. Add pipeline_session_status that converts Result<PipelineOutcome, PipelineRunError> into SessionStatus via crate::daemon::outcome_status, treating hard pipeline errors as genuine failures. Add tests ensuring deliberate stops project to Stopped, crashes to Error, completed runs to Complete, and hard errors remain Error.	crates/stella-cli/src/agent/outcome.rs
Widen SessionPresence APIs from bools to SessionStatus and make notifications reflect the actual terminal status.	Change one_shot_notification to accept SessionStatus instead of bool and to word titles as 'stopped by policy', 'run cancelled', 'run finished', or 'run FAILED' based on status and run duration. Change finish to accept and persist a SessionStatus directly, removing the internal bool→status collapse and documenting that status must come from outcome_status or the pipeline projection.	crates/stella-cli/src/agent/presence.rs
Update agent call sites to compute and pass SessionStatus instead of bools for one-shot and goal flows.	In run_pipeline_one_shot, derive session_status via pipeline_session_status and feed it to one_shot_notification and finish instead of using a run_ok bool. In run_raw_one_shot, derive SessionStatus via crate::daemon::outcome_status(outcome.as_ref().map(	_
Align supervised outcome recording docs with the new unified outcome_status-based projection.	Update record_outcome_if_supervised documentation to state that both supervised and presence writes project through outcome_status and now agree on all outcomes, including deliberate stops.	crates/stella-cli/src/daemon.rs

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#1826	Widen SessionPresence::finish beyond a bool so that callers pass a proper SessionStatus derived from the terminal pipeline/CLI outcome (including AbortKind::DeliberateStop mapping to SessionStatus::Stopped), and update one_shot_notification to key off this status while preserving its basic notification semantics.	✅
#1826	Ensure unsupervised/headless runs (pipeline and raw --no-pipeline) record a deliberate stop as SessionStatus::Stopped rather than Error in the SESSIONS registry by routing their outcomes through a shared projection (e.g., via daemon::outcome_status), so supervised and unsupervised writers agree.	✅
#1826	Audit the deck’s session_exit writer for the same collapse of deliberate stops to a bool, and update it to record SessionStatus::Stopped if/when a deliberate-stop outcome becomes observable there; add a witness test that drives an unsupervised headless deliberate stop and asserts the stored status is Stopped (not Error).	✅

Possibly linked issues

• SessionPresence::finish and the deck's exit writer still collapse a deliberate stop to a bool #1826: The PR implements the issue’s request: widening SessionPresence::finish and using shared outcome projections to record Stopped correctly.
• SessionPresence::finish and the deck's exit writer still collapse a deliberate stop to a bool #1826: PR completes the issue’s intent by routing unsupervised writers through outcome_status so deliberate stops store as Stopped, not Error.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.