docs: settle teardown design (review before implementation)

[arul28]

Design deliverable for the settle teardown cut from #1059. Doc only — no code. Requested for review before any reimplementation is scheduled.

docs/features/terminals-and-sessions/settle-teardown-design.md

• §1 — all seven paths that write or clear settled_at, with file:line and callers. Four of the seven clearers are implicit (never named "unsettle"), and one (setLastOutputPreview) runs per terminal output chunk. This inventory is the thing Background-work liveness in canonical phase + archive port-lease ordering #1059 didn't do first.
• §2 — six-case race matrix. R1/R2/R6 share one root: the settle decides at t₀ and writes at t₀+T with no detector for what changed in between. lastActivityAt is not that detector — it's backed by last_output_at, which turn-start never writes.
• §3 — proposal: a single settle-writer chokepoint owning a monotonic persisted lifecycle revision (settle writes conditionally on it), an explicit exclusive settling state, and the rule that an accepted user turn aborts the settle, never the reverse. Plus the open decision on unconfirmed teardown (§3d) — the one place the honest answer and the quiet answer differ, flagged for sign-off.
• §4 — all 16 P1 findings mapped to the constraint each implies and the mechanism that neutralises it.
• §5 — sequencing. The chokepoint alone, shipped with no teardown at all, would have prevented 9 of the 16 findings.

🤖 Generated with Claude Code

Greptile Summary

This documentation-only PR specifies the proposed architecture and rollout sequence for race-safe session settlement and teardown.

• Inventories settlement and clearing entry points and models six teardown races.
• Proposes a host-authoritative writer chokepoint, lifecycle revision, explicit settling state, and activity-driven abort behavior.
• Defines handling for unconfirmed teardown residue and a staged implementation plan.

Confidence Score: 4/5

The PR should not merge as the approved implementation design until the outstanding mutation inventory is made internally consistent.

The design requires every settlement mutation to pass through one chokepoint, but its inventory still gives conflicting counts and classifications, so implementers cannot reliably determine the complete scope of that invariant.

Files Needing Attention: docs/features/terminals-and-sessions/settle-teardown-design.md

Important Files Changed

Filename	Overview
docs/features/terminals-and-sessions/settle-teardown-design.md	Adds the teardown design, race matrix, lifecycle-state proposal, compatibility constraints, and rollout sequence; the previously reported mutation-inventory ambiguity remains unresolved.

Sequence Diagram

sequenceDiagram
  participant Caller
  participant SessionService
  participant Teardown
  participant Activity
  Caller->>SessionService: Request settle
  SessionService->>SessionService: Enter settling and capture revision
  SessionService->>Teardown: Stop runtime work
  alt Accepted user activity arrives
    Activity->>SessionService: Clear lifecycle marker
    SessionService->>Teardown: Abort remaining stops
    SessionService-->>Caller: settle_aborted_by_activity
  else Revision remains unchanged
    Teardown-->>SessionService: Stop results
    SessionService->>SessionService: Conditionally persist settled_at
    SessionService-->>Caller: Typed settle outcome
  end

Loading

_{Reviews (2): Last reviewed commit: "docs(sessions): amend settle-teardown de..." | Re-trigger Greptile}

Context used:

• Knowledge Base — Chat, terminal, and provider session management

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
ade	Ignored	Preview	Aug 10, 2026 7:24am

[coderabbitai]

Important

Review skipped

Review was skipped due to path filters

⛔ Files ignored due to path filters (1)

• docs/features/terminals-and-sessions/settle-teardown-design.md is excluded by !docs/**

CodeRabbit blocks several paths by default. You can override this behavior by explicitly including those paths in the path filters. For example, including **/dist/** will override the default block on the dist directory, by removing the pattern from both the lists.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 92fd099e-3011-4fd7-915b-b80e5698ee99

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}