projmux 0.15.3 → 0.16.0

package/docs/release.md

@@ -0,0 +1,97 @@
+# Release
+
+This document describes how a projmux version is released. For the npm
+package layout, publish order, and trusted publishing, see
+[npm-distribution.md](npm-distribution.md). For the PR title rules that feed
+the release notes, see [pr-guideline.md](pr-guideline.md).
+
+## Stable releases through release-please
+
+`release-please-action` watches `main`, accumulates Conventional Commit
+subjects, and opens or refreshes a "chore(main): release X.Y.Z" PR. That PR
+contains the version bump (`internal/version/version.go` and
+`.release-please-manifest.json`), the `CHANGELOG.md` updates, and the release
+notes.
+
+Merging the release PR creates the GitHub Release with auto-generated notes as
+a **draft** (`draft` in `release-please-config.json`).
+
+## Tag creation
+
+The same package config sets `force-tag-creation`, so release-please creates
+`refs/tags/vX.Y.Z` during its release pass, before it computes the next release
+PR. That tag creation triggers the tag workflow through the release-please PAT.
+
+Do not move tag creation into a post-action workflow step. release-please-action
+creates releases before pull requests, and a delayed tag makes the same run
+treat the just-released commits as unreleased.
+
+## The tag workflow
+
+`.github/workflows/release.yml` triggers on the tag push. It runs the shipped
+E2E shard/suite matrix behind the fail-closed `Release E2E Tests` aggregate,
+then builds the linux/darwin × amd64/arm64 matrix and uploads tarballs to the
+drafted release (`gh release upload --clobber`). `Build Release` depends on the
+aggregate rather than on individual shards.
+
+Do not add hardcoded notes back to that workflow. release-please owns the
+notes.
+
+## Publish ordering
+
+The release becomes visible only in the final `publish-release` job, after
+`publish-npm` succeeds. That ordering is the contract:
+
+- Users never see a GitHub release for a version npm cannot install yet.
+- A failed npm publish leaves the release drafted and the workflow red instead
+  of shipping a half-published version.
+
+See [npm-distribution.md](npm-distribution.md#publish-order) for the npm side
+of that order.
+
+## Release candidates
+
+Release candidates are cut **outside** release-please, by the
+`workflow_dispatch`-only `.github/workflows/release-rc.yml`. It takes an
+`X.Y.Z-rc.N` version, drafts a GitHub Release marked `--prerelease` against
+`main` HEAD, then pushes `vX.Y.Z-rc.N` with the release-please PAT, so the same
+`release.yml` builds, uploads, and publishes it.
+
+Running it is a deliberate manual act: npm publishes cannot be recalled.
+
+### Do not configure prerelease in release-please
+
+Do **not** add `prerelease` or `prerelease-type` to `release-please-config.json`
+to get release candidates. release-please gates the prerelease flag on
+`config.prerelease && (version.preRelease || version.major === 0)`. This
+repository is `0.x`, so the key would stamp *stable* releases as prereleases,
+`releases/latest` would stop resolving, and default-channel updates would go
+silently dead.
+
+### The rc path never touches the manifest
+
+The rc path writes exactly one ref: the tag. It never touches
+`.release-please-manifest.json`, so release-please keeps measuring the next
+stable release from the previous *stable* release.
+
+release-please picks that boundary by matching the manifest value against a
+tag, with no prerelease filter on that path. An rc holding the manifest slot
+would silently trim the next stable release notes and its `compare/` link.
+
+## Channel branching in release.yml
+
+`release.yml` branches on the tag only where the channel is decided:
+
+- A prerelease tag publishes npm with `--tag rc` and keeps `--prerelease` when
+  the release is undrafted.
+- A stable tag runs exactly as before.
+
+Job names, order, and the `publish-npm` → `publish-release` gating are
+identical for both. `test/release_workflow_contract_test.py` executes both step
+scripts against a stable and an rc tag to hold that split.
+
+## Commit subjects
+
+Non-Conventional commit subjects on `main` are silently skipped by
+release-please. Keep PR titles strict. Squash merge ensures the PR title is the
+only subject that lands.

package/docs/replacement-contract.md

@@ -1,7 +1,7 @@
 # Replacement completion and restorability
 
 Three layers of this application hold an execution image, and every consumer of
-`make install`, `npm install`, or a provider generation upgrade believes one
+`make install`, `npm install`, or a provider upgrade believes one
 sentence about all three at once. That sentence is false in a different way on
 each layer. This document fixes what is guaranteed, what is not, and how a
 report can be recovered from the tokens the diagnosis prints.
@@ -13,7 +13,7 @@ the `projmux doctor` replacement table:
 | --- | --- | --- |
 | `L1` | `installed-executable-image` | the file the installed path publishes |
 | `L2` | `long-lived-projmux-processes` | every running child of that file |
-| `L3` | `provider-sessions-and-generations` | provider sessions and the managed generation pool |
+| `L3` | `provider-sessions-and-generations` | provider sessions, whose app-server lifetime the upstream `codex app-server daemon` owns |
 
 `projmux doctor` renders the table on an unfiltered run and under
 `projmux doctor --section replacement`. It is read-only in the same sense as
@@ -44,22 +44,14 @@ image accepts no new work on any of the three layers*.
   replace it and is left alone — see *The L2 replacement policy* below. A
   replacement that has not finished within the drain cutoff is reported as
   `replacement-cutoff-reached` and is still not ended.
-- `L3` cannot enter `draining` without a qualified version pair. Both doors into
-  a generation switch require a measured receipt for exactly the pair they are
-  about: managed activation refuses before it writes the journal, and a handover
-  resume refuses before it drives any effect — the one exception being a
-  generation nothing is bound to, which the planner has always been allowed to
-  retire because a receipt proves a thread survives a cross-version resume and
-  such a generation has no thread to carry. Each refusal names the action that
-  clears it, and that action is now runnable: `scripts/test-generation-pool-qualification.sh`
-  measures a declared pair in isolation and
-  `projmux agent app-server upgrade qualify --receipt <absolute-json>` installs
-  the receipt it writes where both doors read it. **What is not guaranteed is
-  the measurement's honesty.** The gate checks that the receipt's coverage
-  counters can have come from a run — an acceptance claim with no observation
-  behind it is refused as forged — but a determined forger who writes a coverage
-  count of one is not contradicted by anything else in the receipt. The gate
-  makes the receipt state its coverage; it does not attest to it.
+- `L3` is not replaced by an install at all, and this application no longer
+  switches an app-server generation: the endpoint lifetime belongs to the
+  upstream `codex app-server daemon`, and the private generation pool that once
+  owned it — with its upgrade, qualification, and handover commands — is gone.
+  What the row still reports is the Registry against provider evidence: a
+  `Running` Agent that provider evidence contradicts, and a `Running` Agent that
+  nothing can confirm. Absence of both is not evidence of a restore route, so
+  restoration stays `unknown`.
 
 **Non-Guarantee.** Explicitly outside this contract:
 
@@ -68,13 +60,14 @@ image accepts no new work on any of the three layers*.
   `unsupported-platform` with the `unknown` verdict on both axes. This contract
   does not build a substitute observation for that platform; it states the gap.
 - The provider's own upstream seamless-upgrade contract. `L3` reasons about the
-  pool this application manages, never about what the provider promises.
+  Registry and the provider evidence it can reach, never about what the provider
+  promises.
 - An externally owned (`unmanaged`) app-server. Its state is not this
   application's to observe or restore.
 - Automatic classification of which changes form one invariant. See C-2.
 
 **Scope.** In space: one machine's projmux installation, the long-lived
-processes it owns, and the generation pool it manages. In time: from the return
+processes it owns, and the provider sessions its Registry records. In time: from the return
 of one `install` or `update` to the next. **Expiry: a verdict expires when the
 installed binary's SHA changes.** A table printed before an install describes an
 installation that no longer exists.
@@ -85,7 +78,7 @@ installation that no longer exists.
 | --- | --- | --- |
 | `L1` | this reader's own executable link carries the kernel's `(deleted)` suffix | none for the binary. No copy of the replaced image is retained, and the recovery text the install prints on failure is config convergence, never a rollback. Restorability is `not-restorable` on every supported path. |
 | `L2` | the whole-fleet vintage census, the newest `install-residue.jsonl` record whose own census observed anything, and the last `install-replacement.json` pass | end and relaunch the residual process through the routes this application already ships. The drain cutoff bounds the wait, and reaching it changes the row rather than the fleet, so a failed replacement leaves every process exactly where a successful one would have found it. |
-| `L3` | generation-pool status, its qualification result, and the Running-versus-live-session census | produce a receipt for the pair with `scripts/test-generation-pool-qualification.sh <old> <new> <output-dir>` and install it with `projmux agent app-server upgrade qualify --receipt <absolute-json>`. **The producer is the recovery route**: a pool that can be qualified can be entered, and one that cannot is refused before it enters. The 2026-09-07 measurement — no route back once `draining` was entered without a verdict — held because nothing read a produced receipt; the entry paths now refuse rather than reach that state. |
+| `L3` | the Running-versus-live-session census | there is no projmux-owned generation switch to undo. A `Running` Agent whose provider session is gone is rebound with `projmux agent resume <ref>`, which moves a retired endpoint reference onto the daemon endpoint; a session nothing can confirm has no route this application can establish. |
 
 **Enforcement.** `TestDoctorReplacementLayerVerdictsAreFixedByInputCombination`
 fixes every input combination to its two verdicts and its token.
@@ -93,15 +86,8 @@ fixes every input combination to its two verdicts and its token.
 to name the evidence that was missing.
 `TestDoctorReplacementDarwinReportsUnsupportedPlatformForImageAndProcessLayers`
 holds the platform branch.
-`TestDoctorReplacementQualificationMissingMakesGenerationPoolNotRestorable`
-holds the `L3` mapping and
-`TestDoctorReplacementL3RestorationMovesWhenTheQualificationLaneOpens` holds the
-transition across it. For the `L3` guarantee above,
-`TestActivateManagedCurrentRefusesEveryUnqualifiedRequestBeforeDraining` and
-`TestResumeRefusesAnUnqualifiedPairBeforeAnyHandoverEffect` hold the two doors,
-`TestResumeStillRetiresAVacantGenerationWithoutAReceipt` holds the vacancy
-exception, and `TestQualificationGateRefusesEvidenceCountersNoObservationBacks`
-holds the forgery refusal. For the `L2` guarantee above,
+`TestDoctorReplacementCensusSeparatesRegistryRunningFromLiveProviderSession`
+holds the `L3` census and its mismatch token. For the `L2` guarantee above,
 `TestBrokerRuntimeDrainsWhenItsOwnImageWasReplaced` holds the vintage entry
 condition and that a runtime on the installed image is not drained by it,
 `TestReplacementRolePoliciesMatchTheContractDocument` and
@@ -250,19 +236,14 @@ the token constants in the code equal, in both directions.
 | `L2` | `install-residue-recorded` | `not-replaced` | `restorable` | no live child was observable, and the newest ledger record whose own census observed anything says that install left residue |
 | `L2` | `install-residue-clean` | `replaced` | `restorable` | no live child was observable, and the newest ledger record whose own census observed anything says that install left none |
 | `L2` | `no-observed-processes` | `unknown` | `unknown` | neither the live census nor any ledger record observed anything. Every reading is silent; none says the fleet is clean |
-| `L3` | `generation-pool-unobserved` | `unknown` | `unknown` | no pool diagnosis was read |
-| `L3` | `registry-running-provider-session-dead` | pool-derived | `not-restorable` | provider evidence contradicts a Registry `Running` Agent |
-| `L3` | `qualification-missing` | pool-derived | `not-restorable` | the pool is installed and carries no qualification result. A pool in this state predates the entry gates or had its receipt removed; the row's `pool.action` names the producer that clears it |
-| `L3` | `generation-pool-blocked` | pool-derived | `not-restorable` | the pool diagnosis is blocked |
-| `L3` | `generation-handover-required` | pool-derived | `restorable` | the pool has a pending operation with a handover route |
-| `L3` | `registry-running-session-unobserved` | pool-derived | `unknown` | Running Agents rest on the Registry alone, with no provider handle to check |
-| `L3` | `generation-pool-not-installed` | `not-replaced` | `unknown` | no generation journal exists. Absence of a journal is absence of evidence about a restore route, not evidence of one |
-| `L3` | `generation-pool-ready` | pool-derived | `restorable` | the pool is installed, qualified, and settled |
-
-`pool-derived` means the replacement axis follows the pool rather than the
-token: `replaced` once a generation is draining, handover-pending, or retired —
-because such a generation accepts no new admission, which is exactly the
-sentence C-1's Assumption makes — and `not-replaced` otherwise.
+| `L3` | `registry-unobserved` | `unknown` | `unknown` | no Registry was read, so nothing about the provider sessions was observed |
+| `L3` | `registry-running-provider-session-dead` | `not-replaced` | `not-restorable` | provider evidence contradicts a Registry `Running` Agent |
+| `L3` | `registry-running-session-unobserved` | `not-replaced` | `unknown` | Running Agents rest on the Registry alone, with no provider handle to check |
+| `L3` | `provider-sessions-uncontradicted` | `not-replaced` | `unknown` | the Registry was read and no Running Agent is contradicted or unconfirmed. Nothing contradicts the sessions; nothing establishes a restore route for them either |
+
+The `L3` replacement axis is `not-replaced` on every reading that reached the
+Registry: an install replaces no provider session, and this application owns no
+app-server generation switch that could replace one.
 
 ## Process role vocabulary
 
@@ -423,15 +404,50 @@ absence is stated by this table's `unsupported-platform` row.
 
 `projmux internal install-replace` runs as a step of `make install`, immediately
 before the residue census so the census measures the fleet the pass left. It
-takes the census, splits the residual processes by disposition, dials the
-published broker runtime for this state domain, waits a bounded moment, and
+takes the census, splits the residual processes by disposition, discovers the
+published generation-scoped broker endpoints in this state domain, and dials
+those whose PID hints select this executable's residual processes. PID is only
+a selection hint; the existing ownership and credential checks still authorize
+the connection. The legacy default endpoint key locates the directory and is
+not assumed to be the published runtime. The pass waits a bounded moment and
 writes `install-replacement.json`.
 
+A welcome from a current-image runtime cannot stand in for a residual target.
+A drain/closing refusal confirms reachability; if the exact socket disappears
+during a failed request, its disappearance proves that target is already gone. The runtime writes `drain-required`
+before an idle drain closes its connection. Completion follows the original
+socket identities and ownership-checked runtime IDs captured for accepted
+targets, so an absent unrelated socket or a successor published at the same
+path cannot distort the drained count. Runtime IDs distinguish successors even
+when the filesystem reuses the original socket's inode. An unreadable or
+untrusted successor record alone does not prove completion.
+
 It **starts nothing** — a replacement pass that launched what it was sent to
 replace would leave more behind than it found, so it dials and never ensures.
-It **signals nothing**: the only request it makes is a socket handshake. And it
-never fails an install: it runs after the install has already succeeded, and
-everything it could not do is on the record it writes.
+It **signals nothing**: the only request it makes is a socket handshake.
+An unreachable target makes `internal install-replace` exit 1. `make install`
+still runs the residue census, then fails because replacement did not finish.
+The binary publication and config convergence have already completed; this
+failure does not roll them back. Accepted drains that are still carrying work
+remain successful, as do complete, no-target, and unsupported-platform passes.
+Their output is unchanged.
+
+On an unreachable result, stderr retains the count and refusal and adds the
+remaining drain targets' role, pid, and mapped executable revision, followed by
+the impact and next action. Targets are rechecked after the refusal; a vanished
+or unreadable target is not invented, and an unavailable build revision is
+`unknown`. These identities are transient terminal output only:
+`install-replacement.json` and the residue ledger retain counts and tokens.
+The replacement record adds `failureStage` on an unsuccessful request:
+`discovery` means target selection, record, or socket validation failed;
+`dial` means the local socket connection failed; `handshake` means the greeting
+or response failed or did not accept a drain. `refusal` keeps its existing broker
+token, when one is available. A current-image welcome has no refusal token.
+Successful, pending, no-target, and unsupported records omit `failureStage`.
+The diagnostic states that later Codex Agents may lack control while the old
+broker remains. Let existing work finish, check that the named processes exit
+naturally, and retry `make install`. If they remain, the operator reviews the
+targets before deciding on termination; the install does not signal them.
 
 Its outcome vocabulary is closed, and it reaches the `L2` row as
 `replacement.outcome`:
@@ -567,13 +583,6 @@ reconstruction.
 | `replacement.drained` | `L2` | counter |
 | `replacement.reported` | `L2` | counter |
 | `registry.observed` | `L3` | `true` / `false` |
-| `pool.status` | `L3` | pool status token, or `unobserved` when no pool diagnosis was read |
-| `pool.reason` | `L3` | pool reason token |
-| `pool.action` | `L3` | pool action token |
-| `pool.generations.live` | `L3` | counter |
-| `pool.generations.draining` | `L3` | counter |
-| `qualification.verdict` | `L3` | qualification verdict token |
-| `qualification.reason` | `L3` | qualification reason token |
 | `sessions.running` | `L3` | counter |
 | `sessions.live` | `L3` | counter |
 | `sessions.dead` | `L3` | counter |
@@ -591,6 +600,5 @@ The replacement policy above is the one thing on this page that acts, and it
 acts through a strictly narrower door. `TestReplacementPathEndsNoProcess` holds
 the same guard over the policy table and the install pass: they carry no
 termination, no signalling, and no restart either. **The whole of the action is
-a socket handshake, and the runtime decides.** `L1` atomicity and the `L3`
-qualification gate are separate work on separate doors, and no change on this
-path may alter their behavior.
+a socket handshake, and the runtime decides.** `L1` atomicity is separate work
+on a separate door, and no change on this path may alter its behavior.

package/docs/resource-attribution.md

@@ -3,8 +3,8 @@
 Phase 0 provides the read-only attribution contract consumed by the Resource
 Inspector shipped in Phase 1. `projmux resources`, the client-scoped
 `resource-inspector` popup, the statusbar range, and `Resources:Open` all keep
-the snapshot in memory only for the interactive process lifetime; it remains
-outside Session State.
+the snapshot in memory only for the interactive process lifetime; it is never
+persisted.
 
 ## Identity and inventory
 

package/docs/session-restore.md

@@ -1,80 +1,39 @@
-# Session Restore
+# Project Startup
 
-Session snapshots are explicit desired-state inputs for one Project. They are
-not tmux replay scripts and they are not Registry backups. Snapshot save keeps
-the existing v1 schema and storage behavior. In snapshot save's runtime id
-duplicate check, a Window or Pane recorded as `MissingRuntime`/`RuntimeUnbound`
-does not claim its retained runtime id, so a tmux id reused after a server
-restart does not refuse the save; two live Windows or two live Panes sharing an
-id are still refused.
+A closed Project starts from its Registry desired state. projmux keeps no other
+saved Project state: the Registry (`registry.json`) is the only input.
 
-```sh
-projmux get snapshots [--session <snapshot-session>]
-projmux create snapshot
-projmux restore snapshot --session <snapshot-session> [--project <ref> | -p <ref>] --dry-run
-projmux restore snapshot --session <snapshot-session> [--project <ref> | -p <ref>] --yes [--client /dev/pts/N]
-projmux delete snapshot --session <snapshot-session>
-```
-
-Restore requires an exact snapshot and an exact, closed target Project. The
-dry-run validates both inputs and prints replacement, deletion, preserved-UID,
-and lost-conversation-pointer counts with zero Registry, tmux, and snapshot writes.
-Snapshot Project/Window/Pane metadata is checked against the exact target owner
-chain. A UID held by another root, a cross-kind UID reuse, a Project mismatch,
-or conflicting owner metadata refuses before commit. The ordinary Project-open
-trust authorization must also approve the exact target root before the Registry
-transaction begins.
-
-After `--yes`, one atomic Registry transaction replaces only the target
-Project's descendant Window/Pane/Agent graph and its descendant name
-reservations. The Project UID, root, trust metadata, unrelated Projects,
-ControlSessions, and source snapshot bytes are preserved. Metadata-bearing
-snapshots reuse their exact target-subtree UIDs and preserve a surviving
-final-v2 Agent or shell anchor plus a surviving direct default shell.
-Metadata-free legacy snapshots reuse target descendants positionally, select
-the first valid Window-local Pane as the role-agnostic anchor, select the first
-direct shell as the optional default, and mint identities only for missing
-items. An Agent-only Window is valid with an empty default. Repeating the same
-projection is a Registry zero-diff.
-
-Resource metadata records the Registry schema that produced it. A v3 snapshot
-is projected through the same root-wide same-kind duplicate-group and
-destination-closure rule as Registry migration: affected resources receive
-their exact UID names, unique names outside the closure are preserved, and no
-numeric suffix is minted. A current-v4 snapshot containing a root-wide
-same-kind collision is rejected as damaged before trust authorization,
-Registry/tmux/provider mutation, or any snapshot write.
-
-The committed Registry is then converged by the ordinary Project materializer.
-For a restored offline Agent-anchor Window, snapshot materialization visibly plans a
-lazy default shell, creates the Window from that shell, and stages the Agent on
-its retained anchor Pane UID. A successful repeat writes neither Registry nor
-topology. Snapshot Agent recipes use the canonical provider launch/resume path,
-including their existing fresh-conversation fallback. Stored startup
-commands are not directly executed by snapshot restore. A runtime item refusal
-does not roll the Registry back: desired state and the source snapshot remain
-available for another `Continue project`, and the refusal is reported as an
-item notice. If an explicit client is supplied, the final observable step is
-`switch-client -c` to the Project's declared session even when the background
-continuation has no inherited `TMUX` variable.
-
-## Project startup
-
-A closed Project has exactly two actions:
+A registered closed Project has exactly two actions. A root that is not a
+registered Project is not asked: it opens fresh, which registers it.
 
 - `Continue project` opens the current Registry desired state with the ordinary
   materializer. A retained graph keeps its Project, Window, Pane, and Agent
   UIDs. A zero-Window Project keeps its Project UID and atomically receives one
   new canonical Window and shell UID before materialization.
-- `Recreate Project` atomically replaces the same-root graph with a new Project
+- `Clear layout and open` clears the Project's saved Window and Agent layout
+  and opens it again; the folder, its files, `.projmux/config.toml`, and trust
+  stay. It atomically replaces the same-root graph with a new Project
   UID and one new canonical Window/shell UID chain, after a confirmation naming
   the exact old Project UID and its Window/Pane/Agent counts. Declining returns
   to the startup rows and writes nothing. It does not archive or retain the old
-  generation.
+  generation. Its new Window's first Pane follows the saved launch default
+  (`tmux-ai-split-mode`), exactly as a Window created from the UI does: the
+  choice is made before anything is cleared. The first open of an unregistered
+  root, which resolves to the same fresh start, behaves the same.
 
 Esc/cancel returns to Projects; it is not an action row. Picker failure falls
 back to the non-destructive `Continue project` action.
 
+`Continue project` needs a registered Project. On a root that is not a
+registered Project it refuses with zero Registry writes and points to
+`Clear layout and open` (`continue project unavailable: <root> is not a registered
+Project; choose Clear layout and open`). It never falls back to Fresh on its own.
+
+projmux does not save Project state on its own at quit or on a timer.
+`projmux quit` offers only `Quit projmux` and `Cancel`. The hidden `internal tmux autosave-session-state`
+route is kept only so status lines rendered by older installs keep working, and
+it does nothing.
+
 Continue resumes an Agent's exact recorded conversation after interrupted,
 killed, abnormal, unknown, or unrecorded termination. Intentional and normal
 termination remain excluded. A recorded receipt must agree on the Agent and
@@ -87,8 +46,8 @@ A missing, blank, malformed, or mismatched conversation ref, a disabled provider
 a missing workspace, or a resume preparation failure skips the Agent with a
 reason. Continue never substitutes a new conversation. Shells and other
 recoverable Agents still converge; an unrecoverable Agent that is itself a
-Window's required anchor keeps the existing Window refusal. Explicit snapshot
-restore and `agent resume` retain their separate authority.
+Window's required anchor keeps the existing Window refusal. `agent resume`
+retains its separate authority.
 
 After Continue commits, its startup summary shows the resumed and skipped Agent
 totals and `projmux diagnostics log --component topology`. The same counts are
@@ -110,21 +69,28 @@ errors. Dry-run writes no execution event; failed or rolled-back execution
 records an error with zero committed counts. Journal and display failures are
 best effort and never change the topology result.
 
-`Recreate Project` never deletes or overwrites autosave or named snapshot files. It
-preserves the root, Git/worktrees, trust decision, and all unrelated Registry
+`Clear layout and open` preserves the root, Git/worktrees, trust decision, and all unrelated Registry
 graphs while changing the Project identity. A rejected commit retains the
-exact old Registry preimage. Repeating `Recreate Project` replaces identity again;
+exact old Registry preimage. Repeating `Clear layout and open` replaces identity again;
 each successful result has exactly one Project claiming the root.
 
-## Snapshot contents and diagnostics
-
-Snapshots keep window names, pane cwd/label/title, shell/startup/agent recipes,
-AI topic ownership, and provider resume metadata when available. Resume health
-in preview is `available`, `stale`, or `unavailable`; confidence derives from
-the stored source. Snapshot inspection never reads provider transcript or
-conversation database content.
-
-An approved projection restore records one safe Session State outcome with
-aggregate Window/Pane/recipe counts and source `manual`. Paths, commands,
-snapshot content, and provider conversation identifiers are never included.
-Dry-run remains read-only and records no mutation outcome.
+The saved launch default is used only when the open carries the exact client
+that pressed the row. The order is:
+
+1. Ask. A picker mode (`selective`, the unset default, or `resume`) opens its
+   picker on the Pane the row was pressed in, before the old layout is cleared
+   or the new Session exists; a provider mode and `shell` are already the
+   answer and open nothing.
+2. Clear the layout and create the new Session with its one shell Pane.
+3. Fill it: an Agent answer is created in that Window first, and the shell is
+   then removed through the canonical Pane delete.
+4. Move the pressing client onto the finished Session.
+
+The client therefore never sees a shell Pane that is about to be replaced.
+Closing the picker without a choice does not stop the open: the Session opens
+with its shell Pane and nothing is said. An open without the exact client -- a
+detached `start project`, a scripted open -- asks nothing, in every mode, and
+keeps the plain shell Pane. A question that cannot be asked, or an answer that
+cannot be filled in, costs one line on that client after the move and keeps the
+shell Pane; the Project stays open either way. `Continue project` and the
+`start project`/`open project` verbs never use the saved launch default.

package/docs/settings-ia.md

@@ -58,7 +58,7 @@ step, never a silent no-op.
     Project`, which forwards to the canonical `create project --root` route for
     that one exact path, and `Unpin candidate`, which removes the preference and
     leaves the directory alone. Nothing here adopts a path automatically.
-  - `Project Sidebar [View]` — holds the two Projects sidebar policies:
+  - `Project Sidebar [View]` — holds the Projects sidebar policy:
     `Runtime diagnostics [Choice]` chooses `When needed` (the read-time default
     with nothing saved) or `Always` for the sidebar's Runtime row. `When needed`
     keeps the row for a refused runtime class or for an observation that could
@@ -68,22 +68,17 @@ step, never a silent no-op.
     Recent Windows links are unchanged, and `projmux runtime diagnostics` and
     `get runtime` never read it. An unrecognized saved value applies the default
     without writing and shows an invalid source.
-    `Closed Project startup` shows exactly two actions when no preference file
-    exists and reports `Continue project / Recreate Project - default` (`이어서 열기 /
-    Project 다시 만들기 - 기본값` in ko-KR). Saved `on` keeps those choices and reports
-    `Continue project / Recreate Project - on - saved`. Saved `off` reports
-    `Continue project - off - saved`, skips the picker, and retains the
-    registered-Continue/unregistered-Fresh automatic
-    adjudication. Reading the row or opening/cancelling the picker never writes
-    the default or changes saved preference bytes/mtime.
+    The closed-Project startup screen has no setting: a registered closed
+    Project always gets it, and a root that is not a registered Project never
+    does. Its two rows are `Continue project` and `Clear layout and open`
+    (`이어서 열기` / `구성 비우고 새로 열기` in ko-KR).
     `Continue project` materializes the Project's current Registry desired state
-    and then moves the client. `Recreate Project` confirms the exact old Project
+    and then moves the client. `Clear layout and open` confirms the exact old Project
     UID and per-kind counts before writing anything,
     atomically replaces the old Project graph with a new Project UID and a new
     canonical Window/shell UID pair, and leaves exactly one same-root claimant
     before ordinary materialization. Esc returns to Projects. Neither action
-    deletes or rewrites snapshots, root, Git, or worktree data. The saved file
-    keeps its `sidebar-startup-picker` spelling.
+    deletes or rewrites the folder, its files, Git, worktree data, or trust.
 - **AI** — `AI` is a product category, never an addressable resource.
   - `Default launch target [Choice]` — an Agent Provider, a Shell Pane, or
     choose-at-launch. It is a keybinding/picker preference and does not weaken
@@ -147,10 +142,10 @@ step, never a silent no-op.
     HUD`, `Working directory` and `Git` are component Views because each owns a
     `Visible` Toggle plus an icon `Choice`; cwd/Git icon `off` removes only the
     icon and leaves the text segment visible. `Agent Usage HUD` is a component
-    View with `Visible`, then Claude/Codex/Antigravity provider Views in the
+    View with `Visible`, then Claude/Codex provider Views in the
     usage-supported catalog order. Each provider owns `Visible` plus only its
-    explicit HUD windows: Claude/Codex own `5h` and `Weekly`; Antigravity owns
-    `Weekly` only. Parent off states gate effective visibility without rewriting
+    explicit HUD windows, `5h` and `Weekly`; Antigravity has no usage source and
+    no provider View. Parent off states gate effective visibility without rewriting
     saved child values. Provider/window rows show saved, effective, and source.
     `Project`, `Clock` and `Settings launcher` are direct visibility Toggles. These global
     presentation values default on except Codex `5h`, which defaults off to
@@ -163,8 +158,6 @@ step, never a silent no-op.
     presentation-only and do not disable their underlying producers, cache,
     backoff, explicit table/JSON command, or cached popup.
   - `Language / Locale [Choice]` and `Agent attention badge style [Choice]`.
-- **Snapshots** — the visible noun is the Snapshot resource. `session-state`
-  remains the config/route spelling and appears only as source detail.
 - **Keybindings** — `Launch & popups`, `Agent & Pane launch`,
   `Pane & Window navigation`, `Sidebar & picker actions` (nested by surface:
   Project Sidebar, Session Picker, Notification Sidebar, Settings), and
@@ -221,7 +214,6 @@ step, never a silent no-op.
   the approve/revoke actions) and `Project hooks [View]` (`Session lifecycle`
   plus `After notification queued`, with the same per-event Views the global
   scope uses, extended by a trust state row).
-- **Snapshots** — the auto-save override and the saved snapshots.
 
 Without an actionable project context the Project surface renders a single
 passive guidance row rather than repeating a disabled reason per row.
@@ -236,14 +228,14 @@ Confirm and Action rows included, so `Quit Projmux` and `Reset theme` are
 focused and never fired. The list is scope-pure: a Global query never returns
 Project nodes and a Project query never returns Global ones, and with no project
 context the Project tab returns nothing. User-data collection items -- an
-individual discovery root, pinned Project, candidate or snapshot -- are data
+individual discovery root, pinned Project or candidate -- are data
 rather than settings, so results stop at their parent View and at the
 collection-level controls. Inside a View the query still filters that View's
 rows, and category rows carry their members' search text so search crosses
 categories.
 
 The result rows are built from the catalog alone: no Registry, tmux,
-filesystem or snapshot read participates, because a result is a destination
+or filesystem read participates, because a result is a destination
 rather than a rendered value. Where that leaves a row unnameable -- a saved
 user path, a command whose row spelling depends on whether a command is
 already stored, a read-only state row that stands for several rendered lines --
@@ -254,7 +246,7 @@ more: the View opens, unfocused, and nothing errors.
 ## Vocabulary and compatibility
 
 Visible nouns follow the shared resource vocabulary: `Project`, `Window`,
-`Pane`, `Agent`, `Provider`, `Notification`, `Snapshot`, with `AI` as a category
+`Pane`, `Agent`, `Provider`, `Notification`, with `AI` as a category
 and `Session` as the runtime projection. The Agent Usage HUD is a presentation
 of what the canonical `agent usage` command provides; there is no addressable
 `Usage` resource, and Settings never spells usage as a readable resource kind.
@@ -302,7 +294,7 @@ result replaces it. Typed validation and staged apply failures stay in the popup
 instead of being visible only on stdout/stderr.
 
 The generic feedback inventory deliberately excludes Welcome, Quit, read-only
-hook/effective/notification diagnostics, Snapshot preview, and key
+hook/effective/notification diagnostics, and key
 capture/probe/diagnostic bodies. Those flows own a viewer, confirmation, or
 multi-step output surface; only an actual Settings write at their boundary is
 eligible for transient mutation feedback.