## Decision Desk refusals and failures

The successful path tells you what an operation is for\. Refusals and partial failures tell you when not to trust a convenient status message\.

This chapter uses failure cards\. Do not manufacture a live stream\, run a foreground job\, install a cancelling extension\, or trigger a provider failure for the exercise\.

### Milestone\: Classify the boundary before retrying

**Need\.** Eli sees a warning\, a blank\-looking UI region\, or an error after a transition\.

**Obstacle\.** “It did not finish normally” does not have one universal meaning\.

**Exact action\:** stop submitting work\, identify the operation and failure phase\, then inspect session information\, directories\, retained messages\, and relevant journal files\.

| Situation | What the current implementation does | Safe response |
| --- | --- | --- |
| `/fresh` while streaming | Refuses the refresh\. | Wait or abort normally\, then retry if refreshing provider state is still the goal\. |
| Interactive `/fork` while streaming | Controller refuses the fork\. | Do not assume it is queued to run later\. |
| `/clear` during streaming or foreground bash\/Python work | Reset method refuses\. | Let work settle or abort it normally\; inspect any file effects separately\. |
| `/clear` during compaction | Controller aborts and waits for compaction before attempting reset\. | A later refusal does not mean no maintenance action happened\. |
| `/new` | Offers a veto point\, then aborts current work and transitions\. | Do not treat it as a streaming\-guard equivalent\. |
| Fork in an in\-memory session | Returns failure\; controller reports “not persisted or cancelled\.” | Use the persistent fictional lab\, not a guessed save flag\. |
| Mode\-specific transition restriction | Some modes can block new\/fork transitions\. | Respect the restriction\; do not bypass it to make the workbook pass\. |

A refusal at the guarded method’s entry can preserve conversation state while the surrounding controller has already cleared editor text\, stopped a status indicator\, or cancelled maintenance\.

**Recorded check\.** Synthetic streaming and foreground predicates exercised the actual guards without running a real stream or foreground executable\. The tested conversation ledger remained unchanged\.

**Self\-check\.** Does “wait or abort” mean the refused command will automatically execute after the response ends\?

**Answer\:** No\. Inspect the settled state and deliberately retry the intended command\.

### Hooks can veto new\, fork\, and resume

An installed extension can return a cancellation result from `session_before_switch` for the reasons `new`\, `fork`\, or `resume`\.

You do not need to author a hook to understand the consequence\:

- Before\-event cancellation is a legitimate refusal\.
- A transient UI clear is not an identity measurement\.
- Ordinary queues that survived a veto still belong to the unchanged session\.
- A generic fork failure message does not distinguish every cause\.

**Recorded check\.** A real SDK extension vetoed fork\, new\, and resume\. Identity\, messages\, journal bytes\, and ordinary steering\/follow\-up queues were preserved in those checks\.

The native public lab disables extension discovery\. It is not intended to reproduce that hook scenario interactively\.

### The resume success\-status caveat

The supplied `SelectorController.handleResumeSession()` awaits `session.switchSession()` but does not check its boolean result before repainting and reporting success\.

Two separate checks establish the relevant boundaries\:

1. A controller test supplied a `false` switch result and observed a `Resumed session` status despite unchanged identity\.
2. The Decision Desk SDK test used a real hook cancellation and verified that underlying session state stayed unchanged\.

Those are complementary checks\, not a claim that a physical TUI with a real cancelling hook was exercised end to end\.

**Practical rule\:** after a questionable resume\, trust the actual session file\, identity\, and directories—not the success wording alone\.

### A failed switch has phases

The resume controller first flushes pending settings\. In the recorded preflight failure\, switching never began\.

Inside `AgentSession.switchSession`\, the operation then includes a veto point\, abort\/flush preparation\, a captured local\-state snapshot\, target loading\, context replacement\, restoration of available model\/thinking\/service\-tier information\, and reconciliation\.

The guarded target\-load block has rollback handling for many captured local fields\.

**Recorded check\.** Failure injected after actual target loading restored prior identity\, messages\, provider\-facing identity\, and ordinary queues\, then rethrew\.

Do not extend that result into any of these claims\:

- Every failure before the captured snapshot is rolled back\.
- Closed physical provider handles are recreated\.
- External effects or completed file edits are undone\.
- `/new`\, `/fork`\, and `/clear` share the same transaction boundary\.
- A mode or prompt\-refresh error always means the session switch was rolled back\.

The supplied switch path catches some post\-switch reconciliation and prompt\-refresh errors and logs them without undoing an otherwise committed switch\. The interactive cwd adapter is also a separate layer\.

A resumed interrupted conversation can receive a synthetic abort record\. Resume is not a promise that opening and closing every journal is byte\-for\-byte read\-only\.

### Warning only\: drop is not an erasure exercise

**Do not run `/drop` in this workbook\.**

The inspected command path requests best\-effort deletion of the previous session file and its artifact directory\, then starts a new session\. It has no confirmation dialog in that path\.

`AgentSession.newSession({ drop: true })` catches and logs a deletion failure and can still proceed\. The UI can consequently show `Session dropped` after incomplete deletion\.

That status does not establish secure erasure\. Forks\, exports\, backups\, temporary sidecars\, clipboard history\, workspace files\, and provider\-held copies may remain\. A session without a file is refused by the drop controller\.

Drop was not executed in the supplied proof\. Its warning is source inspection\, not a deletion result\.

**Self\-check\.** Which is stronger evidence\: `Session dropped`\, or an appropriately scoped retention\/deletion audit\?

**Answer\:** The audit\. The status label is not an erasure receipt\.

**Source anchors\:** `packages/coding-agent/src/session/agent-session.ts` — `newSession`\, `fork`\, `switchSession`\, `resetSessionContext`\; `packages/coding-agent/src/modes/controllers/selector-controller.ts` — `handleResumeSession`\; `packages/coding-agent/src/modes/controllers/command-controller.ts` — `handleDropCommand`\, `#runNewSessionFlow`\; `packages/coding-agent/src/slash-commands/builtin-lifecycle.ts` — lifecycle command routes\.