Session lifecycle v2 across six surfaces, branch drift detection, Tier 1 defect fixes

CLAUDE.md

@@ -1,18 +1,34 @@
 ## Picking the right models for work delegation
 
-Three tiers. Fable 5 for thinking, gpt-5.6-sol for building, Opus 4.8 for everything in between. With a tight, self-contained prompt Opus also handles implementation well when gpt-5.6-sol is unavailable. Sonnet is acceptable only for genuinely trivial mechanical subtasks; never use Haiku.
+**Applicability — read this first.** Everything below describes the *Fable-orchestrated* workflow:
+Fable 5 does the thinking and writes specs, gpt-5.6-sol executes them. **It applies only when the
+orchestrating agent is Fable 5.** If you are any other model — Opus, Sonnet, or anything else —
+this section does not govern your delegation, and you should not route work to Codex/gpt-5.6-sol
+on its account. Check what model you are before applying any of it.
+
+**If you are not Fable:** do the work yourself, and delegate to `opus` subagents (Claude Opus 5)
+when you need parallelism, an independent review perspective, or a second opinion. Sonnet is
+acceptable only for genuinely trivial mechanical subtasks; never use Haiku. You may still use
+Codex deliberately — for an independent review via `codex review`, or when the user asks for it —
+but not as your default implementation path.
+
+### The Fable-orchestrated tiers
+
+Three tiers. Fable 5 for thinking, gpt-5.6-sol for building, Opus 5 for everything in between.
+With a tight, self-contained prompt Opus also handles implementation well when gpt-5.6-sol is
+unavailable.
 
 | model    | use for |
 |----------|---------|
 | fable-5  | Deep research, architecture/design decisions, hard debugging, anything requiring sustained reasoning or judgment. Also the orchestrator: it writes the specs and prompts the other models execute. |
-| gpt-5.6-sol (high/xhigh) | Pure implementation once a strong, self-contained prompt exists: clear-spec features, migrations, mechanical refactors, test writing, data analysis. Effectively free — use liberally. |
-| opus-4.8 | Everything else: reviews, moderate-complexity tasks, user-facing polish, second opinions. |
+| gpt-5.6-sol (high/xhigh) | Pure implementation once a strong, self-contained prompt exists: clear-spec features, migrations, mechanical refactors, test writing, data analysis. Effectively free — use liberally. |
+| opus-5 | Everything else: reviews, moderate-complexity tasks, user-facing polish, second opinions. |
 
 How to apply:
-- The division of labor is think-then-delegate: Fable (you, or a fable subagent) does the research and produces a detailed spec; gpt-5.6-sol executes it. Never hand gpt-5.6-sol an underspecified task — it can't ask clarifying questions mid-run, so the prompt must contain all context, file paths, constraints, and acceptance criteria.
+- The division of labor is think-then-delegate: Fable does the research and produces a detailed spec; gpt-5.6-sol executes it. Never hand gpt-5.6-sol an underspecified task — it can't ask clarifying questions mid-run, so the prompt must contain all context, file paths, constraints, and acceptance criteria.
 - These are defaults, not limits. If a model's output doesn't meet the bar, redo the work with a smarter model without asking. Judge the output, not the price tag.
-- Mechanics for gpt-5.6-sol: it's only reachable through the Codex CLI. Run `codex exec -m gpt-5.6-sol "<self-contained prompt>"` via Bash — my ~/.codex/config.toml defaults to gpt-5.6-sol at xhigh reasoning; pass `-m gpt-5.6-sol` (and `-c model_reasoning_effort=xhigh`) explicitly whenever the config default differs. Use `codex exec -s read-only` for investigation/analysis; use `codex exec resume --last` to iterate on a prior run. `codex review` for an independent review perspective.
-- Invoking codex from an agent shell (IMPORTANT): always close stdin and write output to a log file — `codex exec "<prompt>" </dev/null >"$LOG" 2>&1`, backgrounded. In non-interactive shells stdin is an open pipe and codex blocks forever on "Reading additional input from stdin..." before doing any work; piping stdout through `tail`/`head` buffers everything so you can't see progress. Verify it's actually working by checking the log grows and a new session file appears under `~/.codex/sessions/<date>/`; no session file after ~2 min = wedged, kill and relaunch.
+- Mechanics for gpt-5.6-sol: it's only reachable through the Codex CLI. Run `codex exec -m gpt-5.6-sol "<self-contained prompt>"` via Bash — my ~/.codex/config.toml defaults to gpt-5.6-sol at xhigh reasoning; pass `-m gpt-5.6-sol` (and `-c model_reasoning_effort=xhigh`) explicitly whenever the config default differs. Use `codex exec -s read-only` for investigation/analysis; use `codex exec resume --last` to iterate on a prior run. `codex review` for an independent review perspective.
+- Invoking codex from an agent shell (IMPORTANT): always close stdin and write output to a log file — `codex exec "<prompt>" </dev/null >"$LOG" 2>&1`, backgrounded. In non-interactive shells stdin is an open pipe and codex blocks forever on "Reading additional input from stdin..." before doing any work; piping stdout through `tail`/`head` buffers everything so you can't see progress. Verify it's actually working by checking the log grows and a new session file appears under `~/.codex/sessions/<date>/`; no session file after ~2 min = wedged, kill and relaunch.
 - Mechanics for Claude models: use the Agent/Workflow `model` parameter (`fable`, `opus`).
 - Inside Workflows (where the model parameter only takes Claude models), reach gpt-5.6-sol via a thin wrapper: spawn an `opus` agent whose prompt says "run the following via `codex exec` in Bash and return its output verbatim, then verify the result compiles/passes tests before returning."
-- Reviews of anything that ships: fable-5 or opus-4.8, optionally `codex review` as an extra independent perspective.
+- Reviews of anything that ships: fable-5 or opus-5, optionally `codex review` as an extra independent perspective.

apps/ade-cli/README.md

@@ -349,6 +349,10 @@ ade lanes create "fix-checkout-flow" --parent main
 ade lanes create "fix-login" --base origin/main   # omit --base to branch from the configured new-lane base (remote-first by default)
 ade lanes child --lane lane-parent --name fix-followup            # child lane carries the parent's unmerged work; a base-less `ade lanes create`/`--auto-create-lane` from a lane with commits not yet on main prints a non-blocking stderr nudge to use this instead
 ade lanes create "lin-123" --linear-issue-json '{"id":"...","identifier":"LIN-123","title":"...","projectId":"...","projectSlug":"...","teamId":"...","teamKey":"...","stateId":"...","stateName":"Todo","stateType":"unstarted","priority":2,"priorityLabel":"high","labels":[],"assigneeId":null,"assigneeName":null,"createdAt":"...","updatedAt":"..."}'
+ade lane drift --lane lane-id --text              # did someone `git checkout` inside the worktree? compares live HEAD to the lane's recorded branch
+ade lane drift resolve --lane lane-id --switch-back        # put the worktree back on the lane's branch (refuses on a dirty tree)
+ade lane drift resolve --lane lane-id --keep-head          # re-point the lane (and its name) at the live HEAD branch
+ade lane drift resolve --lane lane-id --keep-head --expected-head hotfix-auth --force   # --expected-head guards a stale read; --force acknowledges active work
 ade lanes reparent lane-child --parent lane-parent --stack-base-branch main
 ade lanes delete lane-id --force --delete-branch
 ade lanes create-from-linear --issue-id ENG-431 --start-chat --provider codex --model <model>
@@ -408,7 +412,16 @@ ade chat steer session-id --text "active-turn context"
 ade chat note "running e2e shard 2/4"                       # update the caller's Work sidebar status; add --session <id> to target explicitly
 ade chat ask "Which account should I use?"                 # escalate a blocking question; add --session <id> to target explicitly
 ade chat settle --outcome "opened PR #841, CI green"       # mark the caller settled; add --session <id> to target explicitly
-ade chat unsettle                                           # return the caller to the active lifecycle; add --session <id> to target explicitly
+ade session show session-id --text                          # settle/snooze state, and why a snoozed row came back
+ade session snooze session-id --for 1h                      # 30m|1h|4h|1d|1.5h; a bare number means minutes; relative durations cap at 30d
+ade session snooze session-id --until 2026-07-26T18:00:00Z  # explicit ISO-8601 deadline (must be in the future)
+ade session snooze session-id --until-asked                 # open-ended, matching the desktop/iOS "Until I'm asked" preset: only a hand-raise brings it back
+ade session wake session-id --reason manual                 # timer|needs_you|error|turn_complete|manual
+ade session settle session-id --outcome "CI green"          # same as `ade chat settle`, but works for CLI/terminal sessions too
+ade session settle session-id --keep-active                 # pin active instead; the only way to hold a clean-exit row out of the quiet tier
+ade session unsettle session-id
+ade session clear-woke session-id                           # drop the "woke early" marker after visiting the row
+ade session actions --text                                  # raw session service actions
 ade chat schedules session-id --pause              # pause this agent session's durable wakeups/cron/loops (omit flag to inspect, --resume to re-arm)
 ade chat scheduled-work list [session-id] --all     # list durable jobs; --all includes recent terminal history
 ade chat scheduled-work create --in 12m --prompt "Check CI and report" --reason "CI check" --session session-id              # safest one-shot form; omit --session inside the bound agent