projmux 0.15.2 → 0.16.0

package/docs/pr-guideline.md

@@ -59,33 +59,70 @@ classifies the whole PR by its title type, not by content.
 
 ## PR body
 
-Use this template:
+Use this template. Keep all six sections in this order.
+[`.github/pull_request_template.md`](../.github/pull_request_template.md)
+pre-fills new PRs with the same template; keep the two in sync when either
+changes.
 
 ```markdown
 ## Summary
-- 1–3 bullets describing what changed and why.
-
-## Test plan
-- [ ] make fmt-check
-- [ ] make test
-- [ ] manual verification step (if relevant)
-
-## Globalization
-- [ ] No user-facing string changes.
-- [ ] User-facing strings are behind `internal/i18n` catalog keys with tests.
-- [ ] Non-translated strings are classified as literal/data/debug-only.
+- What changed, in 1–3 bullets.
+
+## Background
+- Why this is needed: the problem, a reproduction, related issues or PRs.
+
+## Changes
+- Behavior and code changes, grouped by area.
+- Breaking: what breaks and how to migrate (if any).
+
+## Scope
+- In scope:
+- Out of scope (and follow-ups):
+
+## Verification
+- [ ] Fast local gates: `make fmt` → `make fix` → `make test`
+- [ ] Long local gates: `make test-integration` → `make test-e2e`
+- [ ] Required CI checks green
+- [ ] Manual steps (if relevant):
+- Globalization (check exactly one):
+  - [ ] No user-facing string changes.
+  - [ ] User-facing strings are behind `internal/i18n` catalog keys with tests.
+  - [ ] Non-translated strings are classified as literal/data/debug-only.
+
+## Measurements
+- (If relevant) before/after numbers, method, environment, run ids.
+  Mark each number as observed or inferred.
 ```
 
-Notes:
-
-- **Why** matters more than **what**. Diff already shows the what.
-- Reference issues with `Closes #<n>` so they auto-close on merge.
-- Mention follow-ups explicitly when scope was deliberately deferred.
-- For any new or changed user-facing text, check exactly one Globalization
-  item. Normal UX copy needs a catalog key and test coverage. Commands, paths,
-  config keys, env vars, provider payloads, locale enum values, product names,
-  debug logs, and internal diagnostics may stay out of the catalog only when
-  explicitly classified in the PR body.
+Per-section rules:
+
+- **Summary** — the short version a reviewer reads first. The diff already
+  shows the code; say what changed in terms of behavior.
+- **Background** — **why** matters more than **what**. State the problem, how
+  to reproduce it, and related issues or PRs. Reference issues with
+  `Closes #<n>` so they auto-close on merge.
+- **Changes** — group by area rather than by file. Any breaking change must be
+  listed here with a migration note, and the title must also carry `!` or the
+  body a `BREAKING CHANGE:` footer (see the title rules above).
+- **Scope** — say what is deliberately left out and name the follow-ups
+  (issue or PR) instead of leaving deferred work implicit.
+- **Verification** — list the gates in the order
+  [AGENTS.md](../AGENTS.md) runs them: fast local gates, then the long local
+  gates (which may still be running while CI runs on the published head), then
+  the required CI checks, then any manual steps. For any new or changed
+  user-facing text, check exactly one Globalization item. Normal UX copy needs
+  a catalog key and test coverage. Commands, paths, config keys, env vars,
+  provider payloads, locale enum values, product names, debug logs, and
+  internal diagnostics may stay out of the catalog only when explicitly
+  classified in the PR body.
+- **Measurements** — fill it when the PR claims a change in speed, size, or
+  resource use (for example a `perf` PR). Give the method, environment, and
+  run ids so the numbers can be reproduced, and mark which values were
+  observed and which inferred.
+
+For small PRs, **Background** and **Measurements** may be written as `N/A`
+with a one-line reason. Do not delete them, so the section order stays the
+same across PRs.
 
 ## Branch protection in effect
 
@@ -95,6 +132,13 @@ Notes:
 - Required status checks are the five CI job names `Format`, `Unit Tests`,
   `NPM Packages`, `Integration Tests`, and `E2E Tests`. The aggregate `Test`
   job is observed as the project-wide fan-in, but it is not ruleset-required.
+- A required check is a job *name*. Renaming or splitting one of those five
+  stops that context from ever being reported, and GitHub holds the PR at
+  `expected` forever: every check green, merge blocked. Keep a thin aggregate
+  job under the original name with `needs: [<new jobs>]` and `if: always()`.
+  Without `if: always()` the job skips on child failure, which is neither green
+  nor red. `test/e2e/shard-contract.sh` fails when the `E2E Tests` aggregate is
+  missing.
 - Admin bypass is `pull_request` mode — admin can self-merge without
   approvals, but the PR itself is mandatory.
 - Linear history is enforced. The merge methods exposed are

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.