projmux 0.12.2 → 0.13.0

package/docs/architecture.md

@@ -39,6 +39,40 @@ Responsibilities:
 - parse command output
 - convert failures into typed errors
 
+#### Codex app-server compatibility and lifecycle bridge
+
+`internal/integrations/agents/codexappserver` is a Codex-only vertical slice.
+It owns the headerless JSON-RPC request, response, and notification wire types,
+the newline-delimited direct-stdio framing limit, request IDs,
+initialize/initialized handshake, local cancellation, and connection
+replacement. The local proxy transport performs the required HTTP Upgrade and
+bounded RFC6455 WebSocket framing (including masked client frames) before
+carrying those JSON-RPC messages. Core metadata and UI packages receive only
+its closed, content-free health result; they do not import app-server request
+or event types.
+
+The compatibility probe runs the fixed read-only bridge `codex app-server
+proxy` against the local control socket and sends only `initialize` plus
+`initialized`. Doctor, Settings, and support-report triggers remain probe-only
+and never mutate daemon state. A future native user-action trigger may enter the
+lifecycle seam, but only the exact closed `daemon-not-running` classification
+(the official local socket is missing or refuses a local connection) may invoke
+the installed CLI's idempotent `codex app-server daemon start`, at most once for
+the shared in-flight attempt in this process. The start and readiness retry are
+bounded, each caller can cancel its own wait, and readiness must still complete
+the proxy initialize handshake. All other executable, timeout, unsupported,
+protocol, and endpoint failures stay on the existing fallback without a start
+attempt.
+
+The bridge discards command output and reports only closed, content-free health
+and lifecycle reasons; prompts, tokens, paths, and process output do not cross
+the integration boundary. It does not install, bootstrap, restart, or stop the
+daemon, change Codex configuration, perform login, manage a custom socket, or
+accept remote WebSocket control. Projmux shutdown does not stop the shared
+daemon. No existing Agent create/resume, hook, review, catalog, model, or usage
+consumer uses the native source in this phase. Settings displays the decision
+as a read-only state row; it is not a user-selectable authority.
+
 ### 3. UI orchestration
 Picker data is modeled independently from row rendering. The app builds
 backend-neutral `picker.Item` values (`Title`, `Value`, `SearchText`,
@@ -71,7 +105,7 @@ Responsibilities that remain outside `projmux`:
 Config should be explicit and file-backed.
 
 Candidate areas:
-- managed roots
+- managed roots (scan roots for candidate discovery; never managed identity)
 - default home-like roots
 - preview preferences
 - session naming exceptions
@@ -80,7 +114,7 @@ Candidate areas:
 ## State model
 
 Persistent state:
-- pins
+- pins (typed: managed Project uid, or unregistered candidate path)
 - lightweight user preferences
 
 Ephemeral runtime state:
@@ -113,30 +147,166 @@ Packages:
   allocation, schema migration, snapshot reconciliation, and the operation
   transaction. It performs no I/O; the clock, uid source, and root-directory
   probe are injected through `Mutator`.
+- `internal/core/resourcegraph` is pure: the resolved resource graph that joins
+  the Registry's desired topology to one exact tmux server, the typed
+  session/window/pane inventory it is resolved against, the closed attribution
+  and status vocabularies, and the transport descriptor. It performs no I/O.
+- `internal/core/runtimediag` is pure: the read-only projection of one resolved
+  graph's runtime half -- every observed tmux object with its attribution, its
+  exact coordinate, and the Registry resource it is bound to, plus the scopes
+  that could not be observed. It performs no I/O and re-derives no attribution.
+- `internal/core/registryview` is pure: the primary navigation view model. It
+  projects a resolved graph plus the caller's filesystem discovery onto the rows
+  the Projects, Sessions, and Recent Windows surfaces list -- Registry resources
+  in Registry order, discovered directories in their own section, and one Runtime
+  link -- with a status overlay and the actions each resource state is eligible
+  for. It performs no I/O.
+- `internal/core/controller` is pure: the command-scoped controller kernel. It
+  owns the closed intent x attribution authority table, the guard evidence, and
+  the totally ordered plan every convergence producer is authorized through. It
+  performs no I/O and holds no tmux dependency; the guard field spellings are
+  supplied by the caller.
 - `internal/integrations/metadata` owns the registry file (lock, atomic write,
-  migration) and the tmux transport mirror.
+  migration), the tmux transport mirror, and the bounded observation adapter that
+  fills a `resourcegraph.Inventory` from one exact server.
 - `internal/integrations/tmuxopts` is a dependency-free leaf holding the
   canonical spelling of every projmux-owned tmux option name, so the generated
   tmux config, session-state replay, and the resource mirror cannot drift.
 
 Resources and ownership:
 
-- Kinds are `Project`, `Window`, `Pane`, and `Agent`, stamped with
-  `apiVersion: projmux.io/v1alpha1`.
-- `ownerRef` runs Project → Window → (shell Pane | Agent), and an Agent owns
-  its current managed Pane.
+- Kinds are `Project`, `Window`, `Pane`, `Agent`, and `ControlSession`, stamped
+  with `apiVersion: projmux.io/v1alpha1`.
+- `ownerRef` runs (Project | ControlSession) → Window → (shell Pane | Agent),
+  and an Agent owns its current managed Pane. A Window's allowed owner set is
+  exactly those two root kinds; every other ownerRef kind is refused.
+- A `ControlSession` is the app-owned control session -- the Home session
+  `projmux shell` opens -- as a Registry root. It exists so Home's Windows and
+  Panes have an owner chain at all: before it, pane `%0` of Home carried no
+  `@projmux_window_uid`, so every route that resolves "the active target"
+  refused there.
+- **A ControlSession owns no filesystem path, and `ControlSessionSpec` has no
+  field that could hold one.** `spec.session` names the exact tmux session and
+  nothing else. That is the structural guarantee behind "$HOME is never a
+  Project": managed roots, trust, rebind, cwd defaults, and `ProjectByRoot` all
+  read `Project.spec.root`, so a control session cannot leak into any of them
+  even by accident. `$HOME` is never registered as a Project and never added to
+  managed roots.
+- A ControlSession is recognized as one only on evidence, never by name: the
+  server must carry `@projmux_app=1` and the exact session's
+  `@projmux_session_role` must be exactly `control`. `@projmux_ephemeral=1`
+  together with a control role fails closed on both sides -- the reader refuses
+  the pair and the writer refuses to produce it.
+- Control identity is one declarative controller plan, not an install-time
+  migration. The canonical shell lifecycle declares one exact socket/session;
+  `config apply` declares the canonical Home target on the exact `-L` server it
+  just reloaded; and later lifecycle triggers may continue only an exact
+  ControlSession identity already stored in the Registry. For those inputs the
+  root, control role, and every Window/Pane uid owner-chain mirror converge from
+  any partial state, and a second pass performs no Registry or tmux write.
+  Foreign or duplicate claimants and any Project uid claim refuse the whole
+  plan before its first write. Session-name resemblance, cwd, commands,
+  display names, and the app marker by itself are never promotion evidence.
+- ControlSession names share the registry-wide scope with Project names but not
+  a reservation slot, because `nameReservations` is keyed by kind as well as
+  scope. A Project named `home` and a ControlSession named `home` coexist.
 - A persistent tmux **Session is not a resource**. It is a 1:1 runtime
   projection of a Project recorded in `Project.status.session` with a `live`
   flag, and it owns no uid, name, or ownerRef. Auto-attach ephemeral sessions
-  live only in runtime inventory, outside the Project hierarchy.
+  live only in runtime inventory, outside the Project hierarchy. A
+  ControlSession is not a counter-example: it is a root resource that *names* a
+  session, and the session still carries no identity of its own.
 - `Window` and `Pane` carry **no stored liveness field**, deliberately. Their
   `status` block holds observed conditions only; live/offline is derived from a
   live tmux observation at read time. See *Runtime observation and resource
   status* below.
-- Every Window owns an initial Pane and stores its uid in
-  `spec.primaryPaneRef`. Project registration creates this topology **offline**,
-  with no tmux involvement, so Project and Window metadata stays queryable
-  while tmux is down.
+- Every non-empty Project stores one exact canonical Window and every Window
+  stores a role-independent Pane anchor. `Project.spec.primaryWindowRef`
+  resolves to a Project-owned Window whenever the Project owns any Windows;
+  it is empty only for the valid closed zero-Window state. Final schema v2 requires
+  `Window.spec.anchorPaneRef`; it may resolve through the same Window ancestry
+  to either a direct `role=shell` Pane or an Agent-owned `role=agent` Pane.
+  `Window.spec.defaultShellPaneRef` is optional; when present it resolves only
+  to a directly Window-owned `role=shell` Pane. Project registration creates
+  both refs on the same initial shell **offline**, with no tmux involvement,
+  so Project and Window metadata stays queryable while tmux is down.
+  Phase-2 consumers resolve `anchorPaneRef` as the stable role-agnostic split
+  target. An explicit Pane selector or popup origin wins over that stored ref;
+  the stored anchor is consulted only when the invocation scopes no Pane.
+  Shell-required offline creation may adopt or lazily allocate the optional
+  default shell without replacing an Agent anchor. Consumers never write the
+  removed intermediate `primaryPaneRef` field.
+  Canonical deletion preserves the same invariant: deleting the primary Window
+  reanchors to the first existing valid sibling, while deleting the last Window
+  leaves the existing Project with an empty `primaryWindowRef`, a non-live
+  session observation, and no replacement allocation. The requested Window and
+  all descendants are removed exactly; only explicit Project deletion removes
+  the owning root itself.
+
+Home and root kinds:
+
+This is the one place that answers "what is Home". The word names three
+different things and they are not interchangeable.
+
+- **The Home tmux session is a `ControlSession` root, and it is not a Project.**
+  `projmux shell` opens it, the convergence pass marks it
+  `@projmux_session_role=control` on an `@projmux_app=1` server, and
+  `BindControlSession` records it as a Registry root that owns Windows and
+  Panes. It has **no path**: `ControlSessionSpec` holds `spec.session`, the
+  exact tmux session name, and has no field that could hold a root. `$HOME` is
+  therefore never a Project root, never a managed root, never a rebind target,
+  and never returned by `ProjectByRoot`, and no route registers it as one.
+- **`$HOME` the directory is a discovery candidate like any other.** If
+  filesystem discovery offers it, it is an unregistered bootstrap candidate. It
+  becomes a Project only if an operator explicitly opens it, and doing so
+  creates an ordinary Project that has nothing to do with the ControlSession.
+- **The sidebar Home chrome row is neither of the above.** It is a synthesized
+  navigation row for the operator's own root: it carries no uid, no
+  `resourceRef`, and no managed identity, it is not a reconcile or create
+  target, and it disappears entirely when discovery does not offer `$HOME`. It
+  leads the Projects list because it is where the surface starts from, not
+  because it is a member of what the surface orders. Home's *Windows and Panes*,
+  by contrast, are managed rows -- they are owned by the ControlSession root --
+  while the Home session row itself stays classified `control` with no
+  `resourceRef`. See *Registry-first primary navigation* below for the row-level detail.
+
+The root kinds may retain the same preferred tmux session name in stored state,
+but that does not make the name an identity edge. An exact
+`ControlSession.spec.session` claim wins before any Project session-name
+fallback. If an explicitly opened Project would otherwise project onto that
+physical session, its stable runtime name is `<preferred>--<full Project uid>`;
+the Registry Project uid, root, and owner chain remain unchanged. A Project
+uid/root observed on the exact control-owned session is D4 contamination, not
+permission to adopt or rewrite the control-owned descendants. Observation
+failures are quarantined as reason-bearing D6 items so an unrelated session can
+still reconcile; only exact socket evidence authorizes runtime writes.
+
+The consequence for every consumer is one rule: **the Registry has two root
+kinds and a projection that walks roots has to walk both.** A traversal that
+reads `registry.Projects` as if it were the whole root set will drop, refuse,
+or fail to report whatever a ControlSession owns. Kind-scoped reads are still
+fine and are the common case -- a Project root path, a Project session claim, a
+Project pin -- but they are scoped on purpose, not by omission. The classified
+list of every root traversal in the tree, and which of the two kinds each one
+handles, is maintained as an executable table in
+`internal/app/resource_reconcile_root_kind_test.go`; it is re-derived from the
+source on every test run, so a traversal added or moved fails until it is
+classified.
+
+Divergence taxonomy:
+
+Reconciliation uses one closed, additive classification for every plan and
+refusal item. The item's human-readable `reason` remains separate from its
+machine-readable `divergence` label: `D1-unrealized` is declared Registry state
+with no realization, `D2-unattributed` is observed state with no exact resource
+attribution, `D3-orphan-mirror` is a runtime mirror whose uid is absent from the
+Registry, `D4-contamination` is a conflicting Registry identity or contradictory
+exact evidence, `D5-drift` is a bound resource whose declared and observed
+fields differ, and `D6-unknown` is the fail-closed remainder. This taxonomy does
+not replace the resolver's managed/control/ephemeral/recoverable/unattributed/
+foreign/conflict runtime classes or the reconciler's missing/stale/foreign drift
+vocabulary. Doctor and dry-run reports expose counts for all six labels;
+support reports expose those counts but redact item reasons and identifiers.
 
 Identity and naming:
 
@@ -181,10 +351,186 @@ Root lifecycle:
 
 Agent lifecycle:
 
-- The phase set is exactly `Pending`, `Running`, `Offline`, `Failed`. A normal
-  managed-Pane exit or an explicit pane deletion resolves to `Offline`; a launch
-  failure or an abnormal exit resolves to `Failed`. The Agent survives its Pane
-  as a resumable resource.
+- The phase set is exactly `Pending`, `Running`, `Offline`, `Failed`. An
+  abnormal exit resolves to `Failed`, while killed or unexplained disappearance
+  resolves to `Offline` and retains the Agent/Pane rows for diagnosis and
+  explicit recovery. A same-generation supervisor exit 0 paired with exact
+  `pane-exited` evidence is different: a non-last Pane is removed while its
+  Agent is retained Offline. For a last Pane, the complete Window subtree stays
+  pending until the exact causal `window-unlinked` half arrives.
+- `Offline` for an unexplained disappearance rather than `Failed` is a deliberate
+  asymmetry. The phase is what an operator reads to decide whether to resume, and
+  an unproven `Failed` is worse for that decision than an honest `Offline`; the
+  fact that the answer is unproven is carried by `status.lastTermination`, where
+  it can be read without being mistaken for a diagnosis.
+
+Termination evidence transport:
+
+- A managed Pane's `status.activation` names one **materialization** of that
+  Pane, not the Pane. It carries an opaque `generation` minted per launch,
+  resume, and topology materialization, the exact `%N` handle it landed on, the
+  owning Agent uid for an Agent-managed Pane, and the operation id that issued
+  it. The uid survives kill/recreate and resume; the generation does not, and
+  that is what lets a receipt from a replaced process be recognized as stale
+  instead of applied to the Pane that now holds the uid.
+- Every managed launch execs `projmux internal supervise --pane-uid <uid>
+  --generation <gen> [--agent-uid <uid>] -- <command>...`. The supervisor gives
+  the child this pane's exact stdin/stdout/stderr -- the pty tmux allocated, not
+  a pipe -- puts it in its own process group, and makes that group the
+  terminal's foreground group, so job control works and
+  `#{pane_current_command}` keeps naming the child. argv, cwd, and the
+  inherited environment are untouched except for two private `PMX_INTERNAL_*`
+  capability values carrying this Pane uid and activation generation to the
+  provider's own hook children. They are not public `PROJMUX_*` hook API and
+  are accepted only together with the Registry binding and exact recorded `%N`
+  runtime handle. tmux-side signals aimed at the pane process are relayed to
+  the child's group, because the pane pid and the child pid used to be the same
+  process. The foreground handoff is attempted and retried without
+  it rather than probed for: there is no portable way to ask "is fd 0 my
+  controlling terminal" without an ioctl, and a start that fails forks no
+  surviving child.
+- A managed shell Pane -- one created with no command of its own -- is
+  supervised over the process tmux itself would have started: `default-command`
+  run by `default-shell` when it is set, and a **login** shell (argv[0] prefixed
+  with `-`) when it is empty. Both values are read from the same exact server
+  the pane is created on.
+- `status.lastTermination` on the Pane, mirrored onto the owning Agent, is the
+  minimal durable receipt: closed `source` and `classification` vocabularies,
+  `observedAt`, the Pane uid, the optional Agent uid, the generation, and either
+  an exit code or a signal name, plus the operation id. It carries no command
+  text, no pane content, and no provider conversation data. Like
+  `status.sessionRef` it is an optional pointer with `omitempty` and additive
+  inside `schemaVersion: 1`.
+- The classification vocabulary is four **kinds of proof**, not a severity
+  ladder. `intentional` is a canonical control action's own written record and
+  may only come from `source: control-action`. `normal` and `abnormal` mean a
+  supervisor actually reaped the child: exit 0 and everything else,
+  respectively. `unknown` is an explicitly evidence-free record. **Exit 0 is
+  never promoted to intent**: a provider that exits because the operator quit
+  and one that exits because it finished a batch produce byte-identical wait
+  statuses.
+- Receipts are applied under a generation guard: the Pane must still exist, the
+  receipt's generation must be the Pane's current one, a receipt naming an Agent
+  must name the Agent that owns the Pane and still binds it, a receipt the
+  registry already stores verbatim is a no-op, and recorded intent is sticky for
+  its generation. The last rule is load bearing -- a canonical delete records
+  intent and then kills the pane, and the supervisor watching it reports the
+  resulting signal; letting the observation win would turn every deliberate
+  deletion into a crash report.
+- Canonical `delete window|pane|agent` commits its intentional receipt in **its
+  own transaction, before the first live mutation**. A failure to make that
+  evidence durable aborts with zero tmux mutations. Every refusal after it
+  withdraws the receipt again, scoped by the operation id so it can only remove
+  what it wrote; a partial delete that really did kill something keeps the
+  evidence that explains it.
+- Exit reconciliation is what consumes a receipt; see below.
+- The lock-free `termination-receipts.jsonl` row precedes a clean process exit
+  and therefore outlives a qualifying Pane/Agent Registry deletion. That bounded
+  receipt is the post-delete diagnostic: source, classification, observed time,
+  Pane/Agent uid, generation, and wait status only. No command, pane content,
+  prompt, transcript, or provider payload is recorded.
+- The supervisor resolves its state paths from the pane's own inherited
+  environment, which is the tmux **server's** environment rather than the
+  environment of the CLI call that created the pane. That is the correct
+  production binding -- the server is started from the operator's session -- and
+  it is why an isolated test has to start its server with the same state root it
+  reads the receipts back from.
+- Losing a receipt is a supported outcome, not a failure mode. A supervisor
+  killed with `SIGKILL`, a lost tmux server, an unwritable registry, and a pane
+  whose supervisor could not be constructed all leave no receipt, and the pane
+  behaves exactly as it did before supervision existed. An absent receipt is the
+  input that resolves to `unknown`; it is never read as a normal exit.
+- A managed process that dies before the create transaction that launched it
+  commits is a real edge exit reconciliation owns: the reconciliation runs inside
+  the next mutation's transaction and can retire the Pane before the supervisor's
+  receipt arrives. The receipt is then refused as stale, which is the correct
+  outcome -- the Pane it describes is gone -- and the Agent converges on
+  `Offline` with `unknown` evidence rather than on invented evidence.
+- A Pane **adopted** from a runtime object created for another reason -- the
+  first pane a `new-session` brings with it -- carries no generation until it is
+  relaunched. Adoption is not supervision: the process was already running, so
+  there is nothing to have launched it with.
+
+Exit reconciliation and lifecycle projection:
+
+- A **lifecycle dirty event** is one exact-host statement that a managed runtime
+  object's lifecycle may have changed. `pane-exited` carries tmux's exact
+  `#{hook_pane}`. Its current-context session/window formats may already name a
+  survivor, so the owner `$N/@N` comes from the Window's last live Registry
+  observation; `window-unlinked` carries exact `#{hook_session}` and
+  `#{hook_window}` for the dead Window. `after-kill-pane` carries neither because
+  tmux leaves `#{hook_pane}` empty there. Whole-host and coalesced events remain
+  advisory projection inputs and never acquire delete authority.
+- The event is advisory. The reconciliation re-observes the **final** snapshot of
+  that same exact host and re-reads the registry, so a stale event, a duplicate
+  event, and an event for a pane that has since come back all converge on the
+  same state as no event at all.
+- The observation is the same mirrored-uid read (`list-panes -a -F
+  '#{@projmux_pane_uid}...'`) the reconciler and the active-target fallback
+  already share, routed through the event's exact target: an explicit `-L/-S`
+  addresses that server only, and a zero target routes through the inherited
+  client, which is the absolute socket in `$TMUX`. There is no default-socket
+  fallback -- a reconciliation that summed two servers could never report a death
+  at all, and a sibling server carrying the same `%N` handles or the same
+  mirrored uid receives zero calls.
+- The retained-state transition is derived from the receipt the Pane already
+  stores. `abnormal` lands the Agent in `Failed`; `killed` and an evidence-free
+  disappearance land it in `Offline`. A `normal` receipt alone is still only
+  evidence. It becomes Pane/Agent delete authority only when the same controller
+  pass also has the exact hook Pane and Window, a non-empty exact-socket
+  inventory, and a current generation/owner chain.
+- An absence with no receipt **records** an `unknown` one, with
+  `source: reconcile`. That is what makes the reconciliation idempotent: a second
+  pass finds the same document already stored, recording it is a no-op, and the
+  registry is left byte-identical. An absence with no stored value would be
+  re-projected on every pane exit in every session, forever.
+- `source: reconcile` and `classification: unknown` may only appear together.
+  Unknown is a statement that nothing was observed, and letting a supervisor that
+  read a wait status or a control action that stated its intent file one would let
+  either of them erase evidence with it.
+- A qualifying exact clean non-last exit removes only the Pane and leaves its
+  Agent Offline in the same locked Registry transaction. The owning Window,
+  Project/ControlSession, sibling Panes and sibling Agents are unchanged. A
+  shell and a provider are intentionally indistinguishable here: both are
+  supervised wait-status 0; no command or `/exit` text participates.
+- Abnormal, killed, unknown, whole-host absence, missing/empty server inventory,
+  permission failure, foreign Window observation, stale generation, and an
+  Agent that now binds a resumed Pane all produce delete-plan zero. They keep the
+  retained lifecycle projection and canonical explicit Offline delete recovery.
+- The closed Agent transition table stays the authority. An Agent that may not
+  reach the implied phase keeps its phase, its `paneRef`, and its managed Pane;
+  only the evidence is recorded. A refused transition is not a reason to discard
+  what was observed.
+- Cost is measured in transactions. The projection set is computed against a
+  read-only snapshot and the write lock is taken only when something is
+  outstanding -- unrecorded evidence, or an Agent still bound to a dead Pane that
+  can still move -- so a reconciled disappearance costs zero transactions on every
+  later pass. Inside the lock the host is re-observed and the set recomputed,
+  because the registry may have gained a freshly created Agent while the event
+  waited, and applying the pre-lock observation to that newer registry would
+  release the new Agent and delete its still-live Pane.
+- It fails closed. An observation that could not be taken is indistinguishable
+  from one that found nothing, and reading it as empty would file an `unknown`
+  termination against every managed Pane on a machine whose tmux server simply is
+  not up. It is also not an error: the reconciliation rides along inside other
+  operations and must never fail them.
+- Ordering: a supervisor writes its receipt before its own process exits, so the
+  journal evidence is durable before tmux tears the pane down. The controller
+  absorbs it, re-resolves the exact `%N`/`@N` owner on the event socket, and then
+  repeats both inventory and owner/generation checks under the Registry lock.
+  Duplicate and permuted receipt delivery is idempotent. A late old-generation
+  receipt or a resume that wins the lock cannot follow the new binding.
+- The reconciliation performs no runtime call beyond that one observation. It
+  never resumes an Agent, starts an offline resource, materializes a replacement
+  Pane, deletes an unmanaged object, or adopts one. An observation is not an
+  activation authority.
+- `get pane|agent` renders the stored receipt in a `TERMINATION` column --
+  `<classification>/<source>` with the exit status when one was read, plus a
+  relative age -- and `describe pane|agent` renders the classification, source,
+  observed instant, exit code or signal, Pane ref, generation, and operation id as
+  their own rows. The Registry-first navigation carries the same receipt on its
+  Pane and Agent rows. All three are pure projections: a read verb never consumes
+  a receipt, advances a phase, or writes to the registry.
 
 Agent provider session ref:
 
@@ -237,11 +583,39 @@ Agent provider session ref:
   hook whose provider contradicts the Agent's `spec.provider` is refused with
   zero mutations.
 
+Agent launch argv (workspace / task boundary):
+
+- One Agent launch hands the provider CLI two independent things in a single
+  argv: the **workspace** (`--cwd` and every `--add-dir` the create validated)
+  and the **initial task payload** given after `--`. Where the workspace stops
+  is a property of the provider's own parser, so the boundary is provider
+  grammar data in `internal/app/agent_launch_argv.go`, not a concatenation at
+  the call site. `create agent` and `agent resume` read that one grammar, so a
+  provider's option arity cannot be spelled two ways.
+- Claude's `--add-dir <directories...>` is **variadic**: it consumes every
+  following operand until an option-looking token or `--` stops it. So every
+  root travels in one occurrence and the payload is introduced by `--`. A
+  payload appended straight after the roots is parsed as one more directory, and
+  the session then starts with no task at all — an installed regression that is
+  invisible in the argv and surfaces only as an unacknowledged activation.
+- Codex's `-C <DIR>` and `--add-dir <DIR>` each take exactly one value, so roots
+  repeat the option and no payload can be absorbed. Codex's argv is deliberately
+  left byte-identical, which is also why a Codex prompt beginning with `-` is
+  still read in option position, exactly as before.
+- projmux gives additional roots only to Codex and Claude. A stored root for any
+  other provider is refused at launch construction rather than translated into a
+  flag this seam never validated, so an Agent never starts with access narrower
+  than what it records.
+- An empty payload contributes nothing, so the interactive create and the resume
+  argv (where the provider's own conversation option, not a terminator, ends the
+  variadic root option) are unchanged.
+
 Agent resume:
 
 - `agent resume <ref>` rebinds an existing Agent: it builds the provider's
-  **resume** argv from `status.sessionRef`, splits a new managed Pane detached on
-  the target Window's `spec.primaryPaneRef`, and attaches it to that Agent. The
+  **resume** argv from `status.sessionRef`, resolves the target Window's
+  exact role-agnostic `anchorPaneRef`, splits a new managed Pane detached, and
+  attaches it to that Agent. The
   `metadata.uid` and `metadata.name` do not change, `status.phase` becomes
   `Running`, and `status.paneRef` points at the new Pane. `status.sessionRef`
   itself is read and never rewritten by resume.
@@ -278,11 +652,12 @@ Agent resume:
 Registry file and schema:
 
 - The registry lives at `<state>/projmux/metadata/registry.json` (0600 below a
-  0700 directory) behind an `O_CREATE|O_EXCL` lock file with bounded retry and
-  stale-lock breaking, matching the notify queue and recent-windows stores.
-- The envelope carries `schemaVersion: 1`. **v1 is the first envelope projmux
-  has ever written, and no migration step ships today**, so the current version
-  is the only version the registry accepts.
+  0700 directory). Ordinary mutations use an `O_CREATE|O_EXCL` lock file with
+  bounded retry and stale-lock breaking, matching the notify queue and
+  recent-windows stores. Explicit Registry repair uses its own recovery lock;
+  see the recovery boundary below.
+- The envelope carries `schemaVersion: 2`. Version 1 is the first Registry
+  envelope projmux wrote and is the only older version this build migrates.
 - Everything else fails closed: the file is refused as unreadable and **no
   write happens at all** — no rewrite, no backup, no staged temp file. This
   covers a **newer** schemaVersion (which would destroy state a newer build
@@ -292,24 +667,269 @@ Registry file and schema:
   at the registry path, which is exactly the write-on-unknown-input that
   fail-closed exists to prevent. The registry is deliberately not quarantined
   or reset the way a corrupt recent-windows file is.
-- A file that is absent, empty, or whitespace-only is still the legitimate
-  "no registry yet" case and yields a fresh empty registry. Only a file with
-  actual content and no usable `schemaVersion` is refused.
-- The migration machinery is generic and version-indexed, ready for the first
-  real schema bump: a registered older step is applied with backup → temp
-  write → validate → atomic replace, so an interrupted or failing migration
-  leaves either the original file or the fully migrated file, never a partial
-  one. Downgrade writes are unsupported. Because production registers no step,
-  that path is proven by tests that register one into a private migration set
-  (`MigrationSet`, `ClassifySchemaVersionWith`, `MigrateRegistryWith`, and the
-  store's private migration override) rather than by shipping a migration.
+- A file that is absent, empty, or whitespace-only is the legitimate "no
+  registry yet" case **only before the first successful write**; see the durable
+  envelope below. Only a file with actual content and no usable `schemaVersion`
+  is refused as unknown.
+- A normal locked `Load` of v1 runs the production 1 → 2 migration, validates
+  the repaired graph, writes the versioned backup, and publishes the v2 bytes
+  through the existing temp-file atomic replace. A failed repair leaves the v1
+  source bytes unchanged. Every successful first migrator (`Load`, `Update`,
+  `UpdateConvergent`, or explicit `Migrate`) also atomically publishes a 0600
+  `<exact-backup>.migration-report.json` beside the versioned backup before the
+  Registry replace. That durable evidence records the exact absolute backup
+  path, SHA-256 of its byte-identical v1 contents, version pair, repair/loss
+  counts, and every repair detail. It is outside rolling recovery retention.
+  A failed migration removes any staged/published report before returning while
+  leaving the source bytes unchanged. `LoadWithMigrationResult` and `Migrate`
+  additionally return both exact paths from the same locked transaction. A
+  second pass sees v2 and writes neither Registry, backup, nor report bytes. An
+  existing invalid v2 document is validated and refused byte-identically even
+  when explicit `Migrate` has no version step to run.
+  Explicit read-only inspection migrates only its returned in-memory view and
+  never publishes it.
+- The v1 repair is deterministic over Registry order apart from injected opaque
+  uid generation. It preserves every existing uid, ownerRef, reserved name, and
+  Agent conversation/session pointer. A valid Project anchor is never
+  reselected. Otherwise it selects the first valid Project-owned Window and
+  direct shell-Pane chain; a Window with no valid direct shell promotes its
+  first direct shell or receives one bare shell, and a Project with no Window
+  receives the minimum Window/Pane chain. A non-empty shell cwd that no longer
+  names a directory is downgraded to the Project root. Every repair is recorded
+  in `MigrationReport`; replaced declared fields are separately marked as
+  information loss, while created Window/Pane resources are additive repair.
+  Production and golden tests call the same pure repair algorithm with injected
+  directory-existence and uid adapters.
+- The canonical anchor is a schema-v2 write invariant. Until the separately
+  planned Project-start projection lands, the legacy `New` startup path's
+  prune-to-zero transaction fails validation and commits zero Registry bytes.
+  The Registry verdict precedes snapshot deletion, so that rejection also
+  preserves the latest snapshot byte-for-byte and performs no tmux mutation.
+  This fail-closed ordering is not Phase 3 authority to redesign Project start.
+- Downgrade writes remain unsupported. Unversioned, malformed, and future
+  envelopes still fail closed before backup, staging, or replace.
+- **Final schema-v2 Window shape:** the first public v2 contract has required
+  `anchorPaneRef` and optional `defaultShellPaneRef`. Unpublished v2 files with
+  `primaryPaneRef` are normalized under the Registry lock after an exact backup
+  and durable checksum report. A v1 file migrates directly to this final shape.
+  Mixed legacy/final authority is refused; the final writer emits no
+  `primaryPaneRef`; and a second final-v2 pass writes zero bytes.
 - **Field spelling:** the registry file intentionally uses the resource-model
   camelCase spelling (`apiVersion`, `schemaVersion`, `metadata`, `displayName`,
-  `ownerRef`, `primaryPaneRef`, `spec`, `status`) rather than the snake_case
+  `ownerRef`, `anchorPaneRef`, `defaultShellPaneRef`, `spec`, `status`) rather than the snake_case
   used by the older projmux on-disk JSON. The two spellings coexist on purpose:
   existing snake_case files are **not** retro-changed, and the resource registry
   follows the resource-model contract.
 
+Durable recovery envelope:
+
+- The registry is the source of truth for managed identity and desired topology,
+  so `registry.json` is not the whole state: beside it the store keeps
+  `registry.initialized`, the marker that records a completed write, and
+  `recovery/`, a bounded set of the bytes replaced by semantic writes. The marker
+  and every copy are 0600, `recovery/` is 0700 like the directory above it, and
+  **no read creates any of them**.
+- **First use versus state loss.** Before the first successful write there is no
+  marker, and an absent, empty, or whitespace-only registry is the empty
+  first-use registry — the zero-write read contract is unchanged, including the
+  `LoadReadOnly` short-circuit that must not materialize
+  `<state>/projmux/metadata/` for an operator who has never registered a
+  resource. Once the marker exists, the same content-free registry is
+  `ErrRegistryStateLost` on ordinary loads and mutations. Recovery inspection
+  still classifies the missing or empty state and stays available to the repair
+  route. Answering an empty registry there would hide the loss of every uid,
+  name reservation, and offline resource, and the next mutation would mint a
+  second identity domain on top of it. A registry written before the marker
+  existed is ordinary state, not a loss, and gains the marker on its next write.
+- **Rolling recovery copies.** A same-version semantic write copies the bytes it
+  is about to replace to `recovery/registry-<stamp>-<seq>.json` before the
+  replace. Only *verified* bytes are copied: an absent, empty, or
+  structurally invalid prior file yields no copy. An invalid Registry blocks
+  every ordinary write; only the separately validated, explicitly sourced
+  recovery route may replace it. Retention keeps the newest five and removes the
+  rest deterministically — names sort chronologically, and the sequence
+  continues past the newest name rather than reusing one retention freed. A
+  migration keeps its own versioned `.bak` instead, so it never spends a
+  recovery slot on bytes that already have a backup.
+- **A convergent no-op writes nothing at all.** `UpdateConvergent` on an
+  unchanged registry takes no recovery copy, publishes no marker, and leaves the
+  registry's bytes, mtime, and inode untouched. Convergence agreeing with stored
+  state is not a reason to replace it.
+- **Write sequence.** Stage into a temp file in the same directory → `fsync` it →
+  re-read and validate it → copy the prior verified bytes → publish the marker if
+  absent → `fsync` the directory → atomic `rename` → `fsync` the directory again.
+  The live registry is only ever touched by that rename, and every step before it
+  is undone on failure, so an injected or real failure at any step leaves the
+  prior registry byte-identical with no staged file, no orphan copy, and no
+  half-created marker. Directory `fsync` is best effort for filesystems that
+  reject it (DrvFs and friends, the same ones that reject the permission repair),
+  because losing the ability to write state there would be worse than losing the
+  ordering guarantee.
+- The marker is published **before** the rename so that its own failure cannot
+  leave a replaced registry behind. The cost is a crash window of one rename: a
+  hard crash between the marker and the very first registry rename leaves a
+  marker with no registry, which reads as state loss rather than first use. That
+  direction is deliberate — it asks the operator instead of silently starting
+  over — and the diagnostic names the marker so it can be removed to accept an
+  empty registry.
+- **Distinct diagnostics.** Missing-after-initialization
+  (`ErrRegistryStateLost`), malformed (`ErrMalformedRegistry`), too new
+  (`ErrSchemaTooNew`), and unreadable (`ErrRegistryPermission`) stay four
+  separate causes classified with `errors.Is`, because they ask for four
+  different repairs. None of them creates an empty registry or a uid.
+- **Restore is a separate operation.** Producing and bounding the copies is a
+  property of a write; selecting one and putting it back is an operator decision,
+  so it lives in the recovery boundary below rather than in the write path.
+
+Degraded Registry mode:
+
+- `valid` and a legitimate `first-use` are the only states from which an
+  ordinary mutation may begin. Missing or empty state after initialization,
+  malformed JSON, unsupported/newer schema, an invalid resource graph, and an
+  unreadable Registry enter degraded mode. This is a command-scoped
+  classification, not a sticky process flag: a successful repair makes the next
+  mutation healthy again.
+- Ordinary writes classify before entering the normal mutation lock and repeat
+  the graph guard after acquiring it. A degraded refusal wraps the existing
+  typed cause, states that ordinary mutations are disabled, and ends with the
+  exact no-write next command: `projmux reconcile registry --dry-run`. It never
+  leaves a raw validation error as the whole diagnosis and never chooses a
+  recovery source for the operator.
+- Public resource reads explicitly opt into the degraded decode path, so a
+  decodable invalid graph remains available without weakening ordinary
+  low-level Store loads. Recovery inspection can
+  diagnose even malformed, missing, empty, unsupported, or graph-invalid bytes.
+  `projmux reconcile registry` is the only write allowed to replace degraded
+  Registry bytes. Other reconcile, create, rename, rebind, delete, lifecycle,
+  and convergence writes stay on the ordinary gate.
+
+Registry recovery boundary (`projmux reconcile registry`):
+
+- **Two operations with deliberately different powers.** Planning classifies the
+  current registry and every bounded candidate and writes nothing at all — no
+  lock, no permission repair, no directory creation, no tmux mutation. Restoring
+  publishes exactly one source the operator named. There is no "just fix it"
+  mode: which copy is the truth is a judgment about which mutations were wanted,
+  and the command never makes it.
+- **A separate repair transaction.** Restore serializes on
+  `registry.json.repair.lock`, never acquires or waits for the ordinary
+  `registry.json.lock`, and therefore remains available when a failed or stale
+  ordinary writer holds that lock. This is not a validation bypass: the operator
+  must name one source; the source is classified and graph-validated before and
+  under the recovery lock; the staged bytes are classified and graph-validated
+  again; and source/current checksums are rechecked immediately before publish.
+- **Classification, not authority.** A plan reports the current registry and each
+  candidate as `valid`, `first-use`, `missing`, `empty`, `malformed`,
+  `schema-too-new`, `invalid`, or `unreadable`, with a `sha256:` digest of the
+  exact bytes, size, mtime, and the resource/reservation counts a verified
+  envelope holds. Only `valid` is restorable. The same classifier runs at publish
+  time, so a source is never previewed one way and validated another.
+- **Fail-closed on the source.** Malformed JSON, an empty file, an envelope newer
+  than this build, and a graph that decodes but holds a duplicate uid, a dangling
+  `ownerRef`, or a broken name reservation are all refused. Restoring an
+  unverified source would replace a known-damaged registry with an
+  unknown-damaged one, and the second state is worse because it looks healthy.
+- **Byte-semantic restore.** The verified bytes are published verbatim rather than
+  re-encoded, so uids, owner relations, and name reservations are preserved
+  exactly, a repeat restore is a byte comparison instead of a normalization
+  argument, and an older-but-known schema stays readable through the existing safe
+  read and migrates on the next semantic write.
+- **The bytes being replaced are kept.** A restore copies the current registry to
+  `recovery/replaced-<stamp>-<seq>.json` before replacing it, and unlike the
+  write-side copy it keeps content that does **not** verify — that damaged
+  registry is the only remaining evidence if the restore turns out to be the wrong
+  call. Replaced copies are their own bounded family, so a restore never consumes
+  the automatic write history and never grows without bound.
+- **Race guards.** `--expect-source-checksum` and `--expect-current-checksum` tie
+  a restore to the plan it was read from, and the preview prints the exact guarded
+  command. Underneath, the source is re-read and re-verified under the recovery
+  lock, the staged copy is re-validated, and both inputs are re-hashed immediately
+  before the single rename. Anything that moved refuses with the registry
+  byte-identical and tells the operator to re-run the preview.
+- **A repeat restore is a byte no-op.** Bytes already equal to the source mean no
+  rename, no preserved copy, and no marker write.
+- **Restore establishes the boundary.** Restoring into a state directory with no
+  marker publishes one, so a later loss on that machine reads as state loss rather
+  than as a fresh first use.
+- **The live tmux mirror is evidence, never a source.** When no verified copy
+  exists, the plan reports what identity the *exact* server can still testify to —
+  mirrored Project/Window/Pane uids, names, the Project root, and containment
+  resolved from stable tmux ids — beside a fixed statement of what no mirror can
+  return: offline resources, every Agent (no tmux option carries an Agent uid),
+  an Agent-owned Pane's `ownerRef`, the name reservation table,
+  `spec.anchorPaneRef`, `spec.defaultShellPaneRef`, and labels/annotations/timestamps/status. A pane carrying
+  a provider option is counted as proof that an Agent existed whose own uid is
+  nowhere on the server. Nothing is imported and no registry is generated:
+  rebuilding from fragments would convert a visible loss into an invisible one.
+- **No transport is a reason, not an error.** A restore is a filesystem
+  operation, so planning works outside tmux; the mirror section simply reports
+  that it has no exact target. The diagnostic is also skipped entirely when a
+  verified copy exists or the registry is healthy, so it never answers a question
+  nobody asked.
+
+Resolved resource graph (`internal/core/resourcegraph`):
+
+- **One join, consumed by everything.** The Registry is the source of truth for
+  managed identity and logical desired topology; a runtime observation is a status
+  overlay. `Resolve(registry, inventory)` produces the typed read model that the
+  controller, the runtime diagnostics surface, and the primary UI all consume, so
+  "is this Window live" and "may I mutate this pane" have one answer instead of
+  one per call site.
+- **Rows come from the Registry, objects come from the machine.** Every Registry
+  row is emitted whatever the observation said, and every observed tmux object is
+  named and classified even when projmux owns none of it. Neither direction can
+  delete or invent the other's members.
+- **Exact evidence only.** Attribution uses mirrored uids, the mirrored owner uid,
+  the exact session role value, and the stable containment ids tmux itself
+  reports. Session name, working directory, and running command are never
+  ownership keys: a heuristic merge here would attach an operator's unrelated
+  shell to a managed resource, and a wrong identity is worse than an unattributed
+  object.
+- **Closed attribution set.** `managed` is a Registry resource, or the object bound
+  to one; `recoverable` mirrors a uid this Registry does not contain; `control` is
+  an app-owned session carrying the exact `@projmux_session_role=control` marker;
+  `ephemeral` is an auto-attach scratch session; `unattributed` has no mirrored
+  identity but sits inside a managed enclosure or on a server projmux started;
+  `foreign` has neither and belongs to the operator's own tmux; `conflict` is
+  evidence that contradicts itself.
+- **Contradiction refuses to bind.** One uid claimed by two live objects, a uid
+  mirrored onto the wrong kind of object, and a claim whose live containment names
+  a different owner than the Registry does are all recorded as conflicts with both
+  tmux handles, and the row is never reported live and never handed a transport
+  handle. Absent containment evidence is not a contradiction: a session that lost
+  its Project option says nothing about ownership, so the object's own exact uid
+  still binds. A binding that would cross a Project boundary is impossible by
+  construction.
+- **Status is derived, never stored.** `missing-root` outranks every runtime
+  answer, a bound handle is `live`, a scope that could not be observed is
+  `unknown` with a stated reason, and only a readable observation with no handle is
+  `offline`. An empty or failed observation can only downgrade a row; it can never
+  invent a live one. An Agent has no tmux object of its own, so its status is its
+  current managed Pane's status and its phase is reported from the Registry
+  verbatim.
+- **Partial failure stays partial.** The host-ownership probe and the three list
+  queries are independent scopes. A failed windows query leaves Window rows
+  `unknown` while Pane rows keep their own observation, because a pane that is
+  provably gone is still offline. A socket with no server behind it is different
+  again: that is definite knowledge that nothing is live, so rows read `offline`
+  and only host ownership is unavailable.
+- **Both hosts, one identity.** `@projmux_app=1` on the server is the only proof
+  of an app-owned host; anything else is a standalone host projmux is a guest on.
+  The same Registry and the same objects produce identical managed rows under both,
+  and a control-role marker on a server projmux does not own is refused, because
+  any process can set an option on the operator's tmux.
+- **Explicit transport or none.** An observation is routed through exactly one
+  `-L <name>` or `-S <absolute path>`, resolved from the explicit socket flags
+  first and the inherited `$TMUX` socket path second. There is no implicit
+  default-server probe: with no transport the graph is a Registry-only snapshot
+  whose runtime answers are all `unknown`, and a sibling socket is never read.
+- **Bounded and pure.** One observation costs one option probe plus three list
+  queries whatever the size of the server, is memoized for the invocation rather
+  than cached with a TTL — closing a pane must make the *next* command report it
+  offline — and issues no write verb. `Resolve` itself touches no filesystem, no
+  process, and no tmux, so the same inputs always produce byte-identical output
+  and a read can never materialize state.
+
 Session State interoperability:
 
 - Session snapshots carry resource identity through additive `omitempty`
@@ -318,10 +938,13 @@ Session State interoperability:
   `uid`, `name`, `labels`, `owner_kind`, and `owner_uid` in the snapshot's own
   snake_case spelling. No schema bump was needed, and a snapshot written
   without resource metadata still serializes byte-identically to the older form.
-- Snapshots written before resource metadata existed still load and reconcile
-  deterministically: the Project is matched by session projection and then by
-  root, and Windows and Panes are matched positionally against the registry
-  topology in insertion order.
+- Snapshots written before resource metadata existed still project
+  deterministically into an explicitly selected, closed Registry Project:
+  existing Windows and Panes are reused positionally in Registry order and any
+  additional descendants receive new stable identities. Restore validates a
+  pure Project-scoped plan, atomically commits that desired subtree, and only
+  then invokes the ordinary Project materializer. It never directly replays
+  snapshot topology into tmux and never replaces the global Registry.
 
 tmux transport mirror:
 
@@ -331,6 +954,21 @@ tmux transport mirror:
   `@projmux_pane_uid` plus the existing `@projmux_pane_label` as the Pane
   **name** mirror. These are the first window-scoped projmux options; every
   earlier one was pane-, session-, or global-scoped.
+- Opening an unregistered directory is the gesture that mints a Project, and the
+  same flow finishes that Project's identity mirror. The first open takes the
+  shipped `EnsureSession` path -- which writes only the `@projmux_project_path`
+  anchor -- so the open itself writes `@projmux_project_uid` and
+  `@projmux_project_name` onto the session it just created, after the session
+  exists and before the client moves. It uses the same `MirrorProject` writer
+  every other mirror goes through, on the same plain `tmux` transport the session
+  was created on. The write is gated strictly on "this open registered the
+  Project": every already-registered Project converges through the Registry
+  topology engine, including desired state previously committed from a snapshot,
+  and opening `$HOME` mints no managed identity at all, so neither writes a mirror
+  option through this first-open gate. That gate is also what makes repeating an
+  open write nothing. Repairing a session that is already live without its
+  identity mirror is not this path's job: `projmux reconcile resources` is the
+  recovery route.
 - `rename pane` changes `Pane.metadata.name` and its `@projmux_pane_label`
   mirror only. It never writes the raw tmux `pane_title`.
 - `rename window` is the explicit stable-identity path: it changes only
@@ -440,6 +1078,13 @@ Runtime observation and resource status:
   exact mirror is killed before the Registry commit; duplicate, foreign,
   stale-owner, inventory-failure, and plan-to-execution race states remain
   fail-closed. An implicit active Window is never treated as offline.
+- **`delete window|pane|agent` names its server the same way `reconcile
+  resources` does**: explicit `--socket <name>`, explicit `--socket-path
+  <absolute>`, or the inherited absolute `$TMUX`, and outside tmux with no flag
+  it refuses. There used to be a fourth branch -- a hardcoded `-L projmux` --
+  which meant a delete issued against an isolated server inventoried one host
+  and killed objects on another. Refusing is the only remaining honest answer,
+  and it names the two flags that fix it.
 - The inventory is a pure **read**. It never writes, re-mirrors, or adopts a uid
   onto a live tmux object; reattaching a lost binding belongs to the reconciler
   (see *Binding reapply and adoption* below). After a tmux server restart the
@@ -541,20 +1186,94 @@ Binding reapply and adoption:
   step, or that step would stamp `MissingRuntime` on a Window this same pass
   just reattached.
 
-Managed runtime binding convergence:
-
-- Binding repair has two explicit mutation boundaries. A normal
-  `projmux config apply --socket <name>` first completes config preflight and a
-  successful `source-file`, then runs the existing registry reconciler against
-  that same exact `tmux -L <name>` server. The app-generated config also owns
-  synchronous `after-new-window` and `after-split-window` hooks. Each hook
-  expands tmux's absolute `#{socket_path}` and passes it to hidden internal
-  plumbing that routes every reconciler read and mirror write through
-  `tmux -S <absolute-path>`. Neither path falls back to the default socket or
-  inherited `$TMUX`.
-- The lifecycle hooks are synchronous so a newly bindable Window or Pane has a
+Lifecycle trigger convergence:
+
+- Every mutation and lifecycle producer reaches **one** entrypoint. A producer
+  states a reason from a closed set (`config-apply`, `runtime-created`,
+  `runtime-exited`) and one exact tmux server; it does not choose which stages
+  run or in what order. `projmux config apply --socket <name>` reaches it after
+  config preflight and a successful `source-file`; the generated config's
+  `after-new-window`, `after-split-window`, `pane-exited`, and `after-kill-pane`
+  hooks reach it through the hidden `internal tmux converge` route, which is the
+  only lifecycle route there is.
+- The two exit hooks are in both generated configs; the two creation hooks are
+  app-config only, and that asymmetry is the adoption boundary rather than an
+  oversight. A convergence caused by a *new* runtime object mints and rebinds, so
+  it adopts an unmarked window inside a managed enclosure. On the app-owned server
+  every session is projmux's own and there is nothing to adopt by accident; the
+  standalone snippet is sourced from the operator's `~/.tmux.conf` and therefore
+  runs on every server they start, where a raw `new-window` in a session projmux
+  does not own has to stay an unmanaged runtime object that only the Runtime
+  diagnostics surface shows.
+- A hook states that something on one exact server may have changed. Exact
+  `pane-exited` additionally carries tmux's `%N` Pane and `@N` Window handles;
+  kill and coalesced triggers deliberately carry no invented identity. Every
+  hook expands tmux's own absolute `#{socket_path}` and `#{session_id}`, so
+  neither the route nor the convergence it drives falls back to the default
+  socket or inherited `$TMUX`.
+- One convergence pass is one locked reconciliation followed by an exit-half
+  reobservation. The reconciliation imports the live sessions it can attribute,
+  reapplies the bindings it can prove, projects the lifecycle of every managed
+  Pane whose runtime object died, and records why a Window or Pane lost one --
+  all inside one registry transaction against one observation taken inside the
+  lock. The projection has to run *after* the binding steps of the same pass:
+  those steps mirror the uids the observation is diffed against, so an exit stage
+  placed first would file an unknown termination against every Pane the pass was
+  on its way to binding.
+- At most one worker converges one exact server at a time, held as an advisory
+  whole-file lease under `<state>/projmux/controller/`. Not because two would
+  corrupt anything -- the registry's own lock prevents that -- but because both
+  pane-exit hooks fire on every pane exit in every session, and a fleet of
+  workers contending for one registry lock is how a burst becomes lock-attempt
+  exhaustion instead of a convergence. A producer that loses the lease records
+  its dirty event and exits successfully; the holder has not acknowledged that
+  event yet, so it runs a further pass for it. The lease is `flock` rather than a
+  timestamped lockfile so a worker that is killed or panics leaves nothing to
+  break.
+- The pass repeats until one of them writes nothing. That final no-op pass is the
+  reobservation: a write that landed and did not converge -- a second client
+  racing the same repair, a hook that rewrote an option back -- is exactly what a
+  report claiming success must not hide. The loop is bounded; stopping early is
+  safe in a way a lost event is not, because convergence is derived from the
+  machine rather than from the event log.
+- Project runtime stop and fresh identity separation Phase 1 pairs a qualifying
+  last-Pane `pane-exited` with the exact matching `window-unlinked` by socket,
+  `$N` session, `@N` Window, `%N` Pane, Registry
+  owner chain, and activation generation. The first event stores only bounded
+  teardown evidence; the second re-observes every Window in that exact session,
+  including unmirrored siblings, before deleting anything. The guarded
+  transaction deletes exactly that Window, its Panes, its owned Agents, and
+  their reservations. A non-last Project Window reanchors to its existing
+  sibling. The last Project Window leaves the exact Project uid, root,
+  reservation, pins, and snapshot bytes in the valid zero-Window state. A
+  ControlSession likewise loses only the Window and keeps its root uid.
+  Abnormal/killed/unknown exits, stale generations, unpaired or foreign handles,
+  unavailable/empty observations, and missing-server or permission failures
+  retain the graph. A historical offline Window without the stored causal Pane
+  receipt is never deleted from absence alone; its fixed diagnostic recovery is
+  an exact canonical `delete window uid:<window-uid>` on the named socket. No
+  pane content, command, prompt, history, or transcript is an authority input.
+- Phase 2 gives Project startup and stop one closed lifecycle table. The input
+  states are retained-window, zero-window, and deleted; the actions are Stop,
+  Continue, Fresh, and explicit Project delete. Stop writes only the exact
+  managed runtime and preserves every desired UID. Continue on retained-window
+  writes only runtime and materializes the same descendant UIDs; Continue on
+  zero-window atomically allocates one canonical Window/shell below the same
+  Project UID before runtime materialization. The deleted+Continue cell accepts
+  only a usable-snapshot precondition, then atomically creates a new Project UID
+  and restores new descendant UIDs from that snapshot; without the precondition
+  the same cell is an unavailable zero-write refusal and never falls back to
+  Fresh. Fresh atomically replaces either
+  registered state with a new Project/Window/shell UID chain and exactly one
+  same-root claimant. Within this runtime/startup lifecycle table, canonical
+  `delete project --yes` alone unregisters the Project graph; the separately
+  scoped filesystem-missing `prune project` administrative policy is unchanged.
+  Ordinary close-window is a separate operation class, so no one plan can also
+  be stop, Fresh, or Project delete.
+- The creation hooks stay synchronous so a newly bindable Window or Pane has a
   registry binding before the creating tmux command returns and before the next
-  implicit read can run. Mirror writes use `set-option` and `rename-window`, not
+  implicit read can run; the exit hooks stay backgrounded so closing a pane never
+  waits on convergence. Mirror writes use `set-option` and `rename-window`, not
   creation commands, so they cannot recursively fire either creation hook.
 - A canonical resource create already owns the registry transaction while it
   issues `new-window` or `split-window`. It therefore installs a private,
@@ -589,6 +1308,276 @@ Managed runtime binding convergence:
   registry schema. It does not add persistent Project scope, matching by name,
   cwd, or a new ordinal heuristic, uid merge/reassignment, pruning, or forced
   adoption. The Project scope remains derived from the active binding on read.
+- There is no daemon and no auto-start. A trigger never resumes an Agent, never
+  materializes an offline resource, and never adopts or deletes an unmanaged
+  runtime object. Read verbs start no controller at all: `get`, `describe`, and
+  implicit active-target resolution neither converge nor open a registry
+  transaction, and they leave no controller event or lease behind.
+
+Projmux split UI:
+
+- Every split producer carries the exact popup origin as a typed canonical
+  create intent. The origin must resolve through the mirrored Pane uid to its
+  owner Window uid and then to exactly one Project or ControlSession uid; those
+  Phase 11 declaration, root, role, Window, and Pane mirrors are the complete
+  identity evidence. A ControlSession Pane's cwd is launch workspace only and
+  never participates in root identity. If the origin disappears or its owner
+  chain conflicts, canonical create performs no Registry or tmux write and
+  projects the exact refusal to the originating tmux client.
+- The default `ai-split-right/down` binding, the `Alt-7` provider picker, the
+  resume picker, and the provider and shell direct actions all produce a
+  canonical create intent -- which provider, which side, and for a resume which
+  conversation -- and hand it to the same `create` route a typed command reaches.
+  The provider and shell branches render the exact argv an operator would type,
+  so a UI action and a typed command cannot disagree about what `--placement
+  down` means.
+- Only the materializer runs `split-window`. Before this convergence the saved
+  default and both pickers descended into a legacy split that called tmux
+  directly, so a pane opened from the UI was a runtime object the Registry had
+  never heard of: no uid, no owner Window, no Agent row, and a Main UI row only
+  once something else happened to reconcile. A raw unmanaged split now exists
+  only where the operator makes one -- typing `tmux split-window`, or tmux's own
+  pane-context-menu entries.
+- The saved split mode is the one piece of hidden state the split UI reads, which
+  is why the canonical `create agent` route refuses to read it: a canonical route
+  whose result depends on state the operator cannot see in the argv is not
+  canonical. A saved mode that names no launch opens the picker; a saved provider
+  that Settings has since disabled fails clearly, before the intent exists, with
+  zero Registry and zero tmux mutations.
+- The resume picker joins a conversation the machine already has by reaching the
+  same Agent allocation with the provider's *resume* argv substituted for its
+  fresh-start argv. It is not `agent resume`: that verb rebinds an existing
+  Registry Agent and must never fall through to a fresh conversation, while this
+  interactive path may, because the operator picked a row and has already been
+  told it could not be resumed.
+
+Command-scoped controller kernel:
+
+- One seam runs the whole sequence: observe one exact server, resolve it into a
+  `resourcegraph.Graph`, plan, commit the Registry, guard tmux, execute, and
+  reobserve. It is command-scoped and event-triggerable; there is no daemon.
+- Authority is a closed table over intent x attribution plus one explicit grant,
+  not a predicate. The grant is `OperatorTargeted`: this invocation names one
+  exact server the operator chose. `reconcile resources` cannot run without such
+  a target, and that selection -- nothing else -- is what makes an unmarked
+  object on a host projmux does not own repairable. Without the grant `foreign`
+  is refused, and with it every lifecycle intent still is.
+  `start`, `import`, and `delete` are refused for every class, so an offline
+  resource, Home, an ephemeral session, and an unattributed Pane cannot be
+  created, adopted, or removed by convergence. Repair is allowed on `managed`
+  and on `unattributed` -- an unmarked object inside projmux's own runtime world
+  carries no competing identity, so restoring a Registry-owned mirror overwrites
+  nobody. `recoverable`, `foreign`, and `conflict` are refused; `control` and
+  `ephemeral` are observe-only. An unknown class fails closed.
+- A planned write must also carry one of the two convergence verbs,
+  `set-option` or `rename-window`. The verb gate is what makes "convergence
+  never created or killed a runtime object" structural rather than a property of
+  which candidates happen to exist today.
+- The plan is totally ordered: registry surface before tmux surface, then
+  outermost containment first, then by stable key. Containment order is load
+  bearing -- a Pane uid written into a Window that does not yet carry its own uid
+  is attributable to nothing, and the next pass reads it as a Pane outside its
+  owner scope.
+- Guards are exact evidence captured at observation time and re-proved
+  immediately before the first live write, all or nothing: the server's own
+  `#{socket_path}`, the target's mirrored uid, and the containing object's id.
+  A stale guard aborts having written nothing and reports the exact retry.
+- After a run that changed anything, the kernel replans against fresh bytes and
+  reports whether a repeat would write. Convergence is observed, not assumed.
+- Explicit topology materialization keeps its own engine and its own
+  plan-time guard, because it plans against objects it is about to create, which
+  no prior observation can have seen.
+
+Runtime diagnostics escape hatch:
+
+- A Registry-first surface is not an inventory, and that is the point of this
+  one. The managed UI lists Registry resources, so an operator's own shell, the
+  Home control session, a scratch session, and anything on a server projmux is a
+  guest on are all correctly absent from it -- and "correctly absent" is
+  indistinguishable from "lost" without a surface that shows the machine as it
+  is. `projmux get runtime sessions|windows|panes` and the `projmux runtime
+  diagnostics` picker are that surface.
+- It is a projection of `resourcegraph`, not a second join. Every row comes from
+  the resolved graph, which already decided attribution from exact uid, owner,
+  and role evidence; nothing here re-derives a class and nothing here consults a
+  session name, a working directory, or a running command. Every observed object
+  is emitted, managed ones included, because a managed object that needs no
+  repair is exactly the row an operator looks for when the managed UI shows it
+  and the machine seems not to.
+- Two handles per row, and they are not interchangeable. The stable tmux id is
+  the only thing worth storing; the qualified coordinate -- a session name,
+  `<session>:@N`, `<session>:@N.%N` -- is what an operator and the focus route
+  address the object by. The session half of a coordinate degrades from the
+  observed name to the `$N` id, and an object whose enclosing session cannot be
+  resolved gets no coordinate at all rather than an unqualified handle the focus
+  grammar would read as a session name.
+- One exact host, and no transport is an answer. The routing is an explicit
+  `--socket`/`--socket-path` or the inherited `$TMUX` socket path, never a
+  default-server probe and never a second socket. Outside tmux the read succeeds
+  and reports every scope unavailable with a stated reason, where `reconcile
+  resources` refuses the same case because it is about to write.
+- The whole surface is read-only. The Registry is opened without creating it,
+  the observation is the bounded four-query adapter that owns no write verb, and
+  the projection is pure, so a refresh is indistinguishable from not having run
+  it. An empty item list next to a populated unavailability list is a different
+  answer from an empty item list beside none.
+- The picker's actions are forwards, not features. `focus` moves a client and
+  never materializes, `attach project` is the outside-tmux Project entry point,
+  and the Resource Inspector is read-only; each is offered only where it
+  applies, and where it does not the row states why. There is deliberately no
+  adopt, import, rename, or kill: a diagnostic surface that could adopt what it
+  found would be the heuristic merge the resolved graph refuses, wearing a menu.
+- `projmux runtime diagnostics` stays separate from `projmux runtime sessions`.
+  That picker lists recent sessions to open one; this one lists every object on
+  the server to explain what it is. Merging them would put an operator's own
+  shell into the open-a-session list.
+
+Registry-first primary navigation:
+
+- The primary surfaces enumerate the Registry, not the machine. `internal/core/
+  registryview` builds their rows from a resolved graph, so a Project is a row
+  because the Registry contains it and not because a tmux session exists. The
+  runtime contributes a status -- live, offline, missing-root, or unknown -- and
+  an exact handle, and nothing else.
+- Identity is the Registry's. Membership and order in `registryview` are the
+  Registry's own slice order, which is insertion order, and the pure view model
+  applies no preference of its own: the same Registry projects the same rows in
+  the same order on an app-owned server, on a standalone server, and outside tmux
+  entirely.
+- Presentation order is the sidebar's, and only the sidebar's. The Projects list
+  projects the managed rows onto three tiers -- pinned, then live, then closed --
+  and preserves Registry order inside each tier as a stable tie-break. Pinned
+  outranks live because a pin is a stated preference and liveness is an accident
+  of the moment, so a pinned offline Project stays above an unpinned live one. The
+  live tier is an overlay of one exact host, which makes two things contractual:
+  the tier of a row may differ between hosts and between refreshes, and the
+  selection may not follow a position. It follows the Project uid -- the old
+  selection is resolved to its Project and that Project back to whatever row it
+  renders as now -- so a tier change moves the row and not the resource the cursor
+  is on. Nothing about a tier reaches the Registry: it is not stored, not
+  reconciled, and not part of desired topology.
+- Row identity is the resource uid. A managed Project's *selection* is still its
+  `spec.root` so the shipped open flow is unchanged, except for a Project whose
+  root is gone: that row carries `uid:<uid>` and selecting it opens the read-only
+  resource surface, which is where rebind is stated. Before this, such a row
+  failed the whole picker on directory validation.
+- Filesystem discovery is kept and demoted. A discovered directory that no
+  Project root claims is an unregistered bootstrap candidate in its own section;
+  one that is already a Project root is dropped rather than listed twice with a
+  second set of actions. Opening a candidate is the explicit gesture that
+  registers it -- see the authority split below.
+- Home is chrome, not a Project, and the three senses of "Home" stay separate;
+  *Home and root kinds* under the resource metadata model is the canonical
+  statement and this row-level detail follows from it. The
+  Home *control session* is never a managed row: the tmux session itself is app
+  control runtime with no `resourceRef`, the only evidence that a session is one
+  is the exact `@projmux_session_role` value the graph reads, and a session named
+  `home` with no marker is honestly unattributed. The marker is written by the
+  canonical `projmux shell` entry, for the app-session target only, and the same
+  pass mirrors Home's Window and Pane identity -- so Home's *windows and panes*
+  are managed rows owned by a `ControlSession`, while the session row itself
+  stays `control`. Home is still not a Project and never appears in
+  `get projects`. The Home *navigation row* is the operator's own root as
+  filesystem discovery offers it, and it leads the Projects list because it is
+  where the surface starts from rather than a member of what the surface orders.
+  It is synthesized from nothing: it carries no managed identity, it is not a
+  reconcile or create target, and if discovery does not offer `$HOME` there is no
+  Home row.
+- The Sessions and Recent Windows surfaces list managed rows only, attributed by
+  tmux's own `$N` and `@N` ids rather than by a name join, and carry the Registry
+  resource name beside the exact tmux handle their actions target. What they
+  withhold is tallied by class on a Runtime link that forwards to the escape
+  hatch above.
+- The Projects sidebar's Runtime link is conditional, and only the link is.
+  `Settings > Projects > Project Sidebar > Runtime diagnostics` chooses between
+  `Always`, which is the shipped behavior, and `When needed`, which is the
+  read-time default with nothing saved and no install migrated to it. `When
+  needed` offers the row when the refused classes -- `Unattributed`, `Foreign`,
+  `Recoverable`, `Conflict` -- sum above zero, or when the observation could not
+  be taken: no transport, or any scope the inventory marked unavailable. Not
+  being able to look is not the same as nothing being there, so a failed
+  observation keeps the escape hatch reachable rather than hiding it.
+  `Control` and `Ephemeral` are deliberately outside that sum: the app's own
+  control session and a scratch session are what a healthy host looks like, and
+  counting them would put the row back on every render. The decision is purely
+  presentational -- `registryview` still emits a complete Runtime row and a
+  complete class tally, a visible row carries its exact shipped label and tally,
+  the Sessions and Recent Windows links are untouched, and `projmux runtime
+  diagnostics` and `projmux get runtime ...` never read the preference. Hiding a
+  row is not disabling a capability. An unreadable or unrecognized saved value
+  resolves to `When needed` without writing anything and says so in Settings.
+- Every action forwards to a route that already owns it: `focus` for a live row,
+  `attach project` for an offline Project -- the one shipped route that
+  materializes one -- and `agent resume` for an Agent. Rebind and delete are
+  listed as eligible with the exact command that performs them rather than
+  executed from a read surface.
+- A navigation refresh is a read. It opens the Registry read-only, takes the
+  bounded four-query observation through one exact socket, and projects it
+  purely: no Registry or tmux write, no reconcile, no materialize, and no
+  default-server probe when there is no transport.
+
+Project discovery and pin authority:
+
+Five things used to share two files, and each of them answered a different
+question wrongly as a result. Workdirs were a scan source *and* the thing that
+decided which Projects existed. The pin file was a presentation preference *and*
+a discovery input *and* the only record that a directory mattered. They are five
+separate authorities now, and the boundaries are the point.
+
+- **Workdirs and project roots are scan roots.** `PROJMUX_MANAGED_ROOTS`,
+  `PROJMUX_PROJDIR` and `~/.config/projmux/workdirs` name directories to look
+  inside. Looking inside a directory registers nothing. On Windows they are
+  OS-native paths and stay OS-native paths; nothing normalizes them into identity.
+- **A discovered child is an unregistered candidate.** It is a filesystem fact
+  with no uid, no name reservation, and no Registry row. It stays one until
+  something explicitly registers it, however many times it is scanned, rendered,
+  or reconciled.
+- **The Registry is managed identity.** `projmux create project --root <path>` is
+  the canonical bootstrap, and opening a candidate from the Projects sidebar
+  performs the same registration for that one exact path. Both go through one
+  transaction and both are idempotent: a root an existing Project already claims
+  is answered from the Registry and writes nothing. Nothing else registers a
+  Project. In particular the reconcile prelude no longer walks the discovery
+  roots, so `create pane` in one repository cannot add a Project for every
+  sibling directory under a scan root -- which is exactly what it used to do.
+  `--project <name>` naming an unregistered candidate is a refusal that names the
+  exact `--root` and the route that would register it.
+- **A managed pin is a Registry Project uid.** Its displayed root and name are
+  projected from the Registry on every render, so the pin survives a rebind, a
+  rename, and a `MissingRoot` condition. The sidebar tier reads the uid, never the
+  path.
+- **A candidate pin is a path no Project claims.** It is a preference about a
+  directory, kept as one. Rendering it, listing it, and pinning it never mint a
+  Project.
+
+Storage and migration:
+
+- The pin file is a typed envelope: a `projmux-pins v2` header followed by
+  `project <uid>` and `candidate <path>` lines. The kind is stored, not inferred,
+  which is what lets one file hold both collections without either surface having
+  to guess.
+- Reading never writes. Every rendering surface projects a pre-v2 file in memory
+  through the same resolution a migration would persist, so the sidebar is
+  identical before and after `projmux pin project migrate`.
+- Migration is per-line and atomic as a whole. A path exactly one Project's root
+  claims becomes that uid; a path no Project claims stays a candidate; a path more
+  than one Project claims refuses the entire migration with the pin file and the
+  Registry byte-identical, and names the repair. A corrupt or newer-version
+  envelope is refused rather than partially parsed, because a wrong guess about
+  which resource a preference points at is worse than declining to load one.
+- Path folding is confined to two questions: candidate exact-match, and legacy
+  path-to-uid migration. `candidates.MatchKeyFor` resolves symlinks on every
+  platform and additionally folds separator, case, and drive-letter case on
+  Windows, so `C:\Users\dev\src` and `c:/users/dev/src` are one candidate. It is
+  never an identity operation: no amount of path agreement mints a Project uid or
+  merges two, and the Windows rules are frozen by a compatibility table that a
+  Linux test run asserts.
+- `pin project add|remove|toggle <dir>` keeps working unchanged and now resolves
+  to a typed pin under one rule -- exactly one Project with that root makes the pin
+  managed, none makes it a candidate, more than one is refused -- with
+  `uid:<uid>` available when an operator wants to be explicit. Settings shows the
+  three collections as three collections: Additional discovery roots, Pinned
+  Projects, and Candidate Pins.
 
 Public resource reconciliation:
 
@@ -603,16 +1592,22 @@ Public resource reconciliation:
   normalized to deterministic placeholders; they are not matching keys and do
   not obscure owner or target identity. Human and JSON output share the same
   sorted items and missing/stale/foreign/orphan vocabulary.
-- Execute rebuilds the plan from the locked current Registry. Runtime
-  observation is limited to the Registry Project graphs safely attributable to
-  sessions on the selected socket; absence there never marks another socket's
-  graph missing or releases its Agents. The desired
-  Registry is validated and committed before any non-transactional tmux mirror
-  write, keeping Registry identity authoritative and retryable if a later live
-  step fails. After commit, every planned live write is guarded by re-reading
-  its target's Project, Window, or Pane UID binding from the exact socket; all
-  guards and planned before-values must still match before the first write. A
-  recycled or raced handle therefore causes zero live writes.
+- Execute runs through the controller kernel. It rebuilds the plan from the
+  locked current Registry and authorizes every runtime write against the graph
+  resolved from the pre-lock observation. Runtime observation is limited to the
+  Registry Project graphs safely attributable to sessions on the selected
+  socket; absence there never marks another socket's graph missing or releases
+  its Agents. The desired Registry is validated and committed before any
+  non-transactional tmux mirror write, keeping Registry identity authoritative
+  and retryable if a later live step fails. After commit, the socket identity
+  and every planned write's uid and containment guards are re-proved from the
+  exact socket; all of them must still match before the first write. A recycled,
+  moved, or raced handle therefore causes zero live writes.
+- The report is one projection consumed by both renderers. Alongside the sorted
+  items it carries the observed host mode, the authority rows the run
+  exercised -- including the start, import, and delete refusals that are the
+  evidence nothing was activated or adopted -- and the post-execute
+  reobservation.
 - A Registry commit failure performs no tmux mutation. A partial tmux failure
   leaves the durable Registry identity in place, replans current drift, and
   reports completed stages, remaining items, and the exact retry command.
@@ -638,17 +1633,57 @@ Explicit Registry topology materialization:
   one Registry Project and uses a separate pure plan. The default reconciliation
   shadow never calls the materializer, and the materialization plan never runs
   blank adoption, orphan minting, or Agent phase observation. Registry insertion
-  order determines session/Window/Window-owned shell Pane creation order; report
-  keys provide a separately stable rendering order.
-- Registry presence is desired topology. Missing runtime sessions, Windows, and
-  Window-owned `role=shell` Panes are drift; canonical Registry deletion removes
-  that desire. Exact uid/name/owner mirrors are retained. Stored Pane CWD drives
-  only that Pane's detached runtime cwd, while Project root remains the session
-  path anchor and `PROJMUX_CWD` hook value. `Pane.spec.command`, Agent-owned
-  Panes, Agent providers, snapshots, notifications, and ephemeral sessions are
-  never execution inputs.
+  order determines session/Window/Window-owned shell Pane/Agent creation order;
+  report keys provide a separately stable rendering order. Agents are created
+  last inside their Window. A shell or managed-Agent `anchorPaneRef` must be
+  proven on the exact Window; no alternate live Pane is inferred.
+- Registry presence is desired topology. Missing runtime sessions, Windows,
+  Window-owned `role=shell` Panes, and Agents are drift; canonical Registry
+  deletion removes that desire. Exact uid/name/owner mirrors are retained. Stored
+  Pane CWD drives only that Pane's detached runtime cwd, while Project root
+  remains the session path anchor and `PROJMUX_CWD` hook value.
+  `Pane.spec.command`, snapshot recipes, notifications, and ephemeral sessions
+  are never execution inputs.
+- An Agent whose managed Pane is not live is replayed into a new managed Pane on
+  its Window's proven anchor, through the same allocation, activation ledger,
+  ownership-checked adoption, and rollback the shell half uses. The **only**
+  replay identifier is Registry `status.sessionRef`: no provider conversation
+  store is read, `ClaudeSessionRef.TranscriptPath` in particular is never
+  consulted, and snapshot recipe `resumeID` is a separate value that never feeds
+  this path. The launch argv comes from the two seams `create agent` already
+  owns -- `PlanAgentResume` for a ref that names a conversation, `PlanAgentLaunch`
+  with no payload otherwise -- so the topology engine holds no launch builder of
+  its own and the Settings enabled-agents gate still applies. An Agent that
+  cannot rejoin its conversation comes back on a *new* one and the reason is
+  disclosed; an Agent that cannot be launched at all is disclosed and skipped.
+  Neither aborts the materialization, and neither is ever silent. A stale managed
+  Pane row is released only after the server-wide uid preflight proves its uid is
+  live nowhere on the exact socket.
+- An offline Agent-only Window plans a visible `allocate default shell` Registry
+  item, authors that direct shell under the same convergent transaction, creates
+  the Window from it, and then replays the anchor Agent while preserving the
+  Agent Pane uid. The default shell is bootstrap, not a replacement anchor. A
+  successful repeat is a Registry-write-free and topology-write-free no-op.
+- Snapshot restore is a target-Project subtree projection, never a Registry
+  restore. Metadata-bearing v1 snapshots preserve surviving final-v2
+  anchor/default refs; metadata-free snapshots choose the first Window-local
+  Pane as anchor and the first direct shell as optional default. Agent-only
+  desired Windows remain Agent-anchored and acquire a shell only through the
+  ordinary materializer. Source snapshot bytes and unrelated roots are never
+  rewritten, and a second projection is byte-stable.
+- `Open fresh` replaces the exact same-root Project graph in one Registry
+  commit. It always allocates a new Project UID plus one new canonical Window
+  and direct shell UID, whether the old Project retained Windows or had zero.
+  The preimage remains the durable recovery state when the replacement commit
+  fails, and successful validation requires exactly one same-root claimant.
+- Exact-socket reconciliation merges scoped results by UID at their existing
+  global Registry positions. Positive mirrored evidence may change only the
+  selected socket's owned rows; sibling sockets and other-host-only desired
+  refs/status retain both values and byte order. Absence on the selected host
+  is never re-anchor, status-clear, or delete authority.
 - Preflight rejects a missing/invalid root or Pane CWD, a zero-Window Project,
-  a primary ref that is not a direct Window-owned shell Pane, and foreign,
+  an anchor ref that is neither an exact same-Window shell nor the owning
+  Agent's current managed Pane, a live Window whose exact anchor is dead, and foreign,
   duplicate, wrong-owner, or ambiguous live claims before the first create.
   Execute rechecks the same plan under the Registry lock. A server-wide uid
   preflight runs first, *before* the selected Project session is created,
@@ -678,6 +1713,55 @@ Explicit Registry topology materialization:
   Only the selected exact socket is claimed and mutated; sibling sockets are
   tested unchanged, and no global uniqueness across unknown sockets is claimed.
 
+Plan-only runtime mutation boundary:
+
+- Lifecycle and topology changes owned by the app materializer and Pane-delete
+  runtime are values before they are commands. The closed action inventory
+  records a stable target, a typed guard with the exact expected evidence, a
+  total order, expected effect, and typed executable operands; its JSON
+  projection is deterministic. The argv seam rejects an operand target that
+  does not match the printable stable target.
+  Session/Window/Pane creation, identity and create-operation lease writes,
+  layout writes, ownership-checked rollback, exact Pane kill, pre-commit
+  tombstone/restore, and post-result-flush self-kill queueing all enter the same
+  plan -> printable target/route guard -> effect reobserve/replan -> semantic
+  guard -> execute -> effect reobserve/replan boundary. Before an already
+  satisfied row may disappear, the executor binds its printed logical/physical
+  socket and server-generation authority to the captured route; semantic
+  pre-write guards still run together before the first live write.
+- Materialization is a sequence of dynamically replanned stages because exact
+  Window and Pane handles do not exist until the preceding create effect is
+  reobserved. Each stage is nevertheless a complete printable plan with a
+  total order; the next stage is built only from the preceding stage's observed
+  exact effect. Every production row carries `-L=<name>` or the exact
+  `-S=<absolute path>`, the independently observed physical socket, and a
+  printable route receipt. App-owned receipts pin `#{pid}` plus ownership and
+  logical markers; inherited standalone receipts pin the exact server pid and
+  originating `$N`/`@N`/`%N` containment while requiring both app markers
+  blank. The public controller's explicit `--socket-path` grant is narrower:
+  it prints the operator-selected path/PID blank-marker class and relies on
+  each planned action's real UID plus session/window guards; it never infers an
+  arbitrary Pane as invocation evidence. Generated popup/menu producers pass an exact Pane anchor which is
+  reobserved on that same socket rather than trusting a targetless current
+  Pane. Before a stage writes, the same `-S` runner refuses path, generation,
+  class, or containment drift. Only a create-session
+  stage may accept the typed no-server observation, because its explicit route
+  and absent-session ownership preflight are the facts required to create the
+  first server.
+- A guard refusal writes nothing and asks the caller to observe and plan again.
+  Reobservation is explicit: known achieved effects remove their rows, so a
+  successful repeat is an empty plan; an unavailable observation is unknown and
+  can neither synthesize a Registry deletion nor authorize a runtime kill.
+  Partial execution rolls back only actions carrying an ownership-backed undo,
+  in reverse application order. Existing desired Registry state, foreign or
+  sibling objects, and other sockets have no rollback authority.
+- Pane deletion keeps the exact routed socket plus Session, Window, Pane, root
+  kind/root uid, and current Pane mirror in every executable guard. A
+  caller-containing delete still commits the Registry and flushes the complete
+  result before its self-target kill is queued. The AI picker/default/resume and
+  shell split producers remain canonical create-intent producers; they do not
+  gain a second tmux mutation path.
+
 Agent runtime linkage:
 
 - Once a live tmux pane has settled on a registry Pane, reconcile decides which
@@ -693,6 +1777,14 @@ Agent runtime linkage:
   Agent — Phase 1's refuse rule, unchanged. The legacy import path already
   trusted exactly this option to mint an Agent on its create path; linkage makes
   the adopt and rebind paths agree with it.
+- **The canonical default shell remains Registry-owned.** A generic
+  `@projmux_ai_agent` marker on the direct Window-owned `role=shell` Pane named
+  by `Window.spec.defaultShellPaneRef` is reported as reason-bearing D2 and
+  performs no Agent mint, Pane reparent, or reservation move. Runtime metadata
+  cannot invalidate the Registry's canonical shell chain. This exception is
+  deliberately exact: an anchor-only shell that is not the default shell keeps
+  the existing linkage behavior, whose promotion semantics belong to the
+  separate anchor/primary-shell track.
 - **Which Agent, in order.** (1) The Pane is already Agent-owned: that Agent is
   the answer and only `status.paneRef` is repaired. (2) An Agent in the same
   Window already records the same provider conversation in `status.sessionRef`
@@ -741,6 +1833,48 @@ Agent runtime linkage:
   maintenance riding along inside somebody else's transaction: one pane it cannot
   register must not fail the `create` that happened to trigger it.
 
+Resource-first create:
+
+- **One parser, one product model.** `create window|pane|agent|<provider>` share
+  a single argv surface and a single resource-backed implementation.
+  `--project` is a scope flag, never a mode selector, so no flag chooses between
+  two meanings of the same command. The runtime-only "split the current window"
+  half that used to sit behind an absent `--project` is removed; a raw,
+  unmanaged split is tmux's own verb, not a projmux resource verb.
+- **Scope resolution has exactly two branches.** An explicit `--project`/`-p`
+  wins inside and outside tmux and suppresses the active-target read entirely.
+  With no `--project`, the Project is derived from the active exact runtime
+  through the same `@projmux_window_uid` mirror and registry `ownerRef` chain
+  the read verbs use.
+- **Window and anchor follow the whole scope, not the Project flag.** They are
+  derived only when the argv named no `--project`, `--window`, `--pane`, and no
+  `--selector` at all. That keeps a bare `create pane --placement right` -- the
+  generated keybinding body -- a split of the Window the operator is looking at,
+  instead of a fan-out over every Window of the Project, while one explicit
+  occurrence still fixes the whole target set. An explicit `--pane` or popup
+  origin is the exact split anchor. Only a scope with no Pane consumes the
+  target Window's role-agnostic `spec.anchorPaneRef`; a missing, stale, dead, or
+  cross-Window ref refuses with no alternate-live-Pane inference.
+- **Refusals cost nothing.** Home, control, unattributed, foreign, a mirrored
+  uid the Registry does not hold, a Window whose Project is gone, and every
+  outside-tmux invocation with no `--project` are usage errors naming
+  `--project`. They are raised before the registry transaction opens, so they
+  are measurably zero Registry writes and zero tmux calls. Nothing falls back to
+  a runtime-only split, nothing invents a Project from `$HOME`, a session name,
+  or a cwd, and no default server is probed.
+- **Host neutrality is transport-level, not policy-level.** Inside an app-owned
+  or a standalone server the create mutates only the inherited exact socket,
+  because every tmux call it issues inherits `$TMUX` and it never enumerates
+  siblings. Outside tmux an explicit Project is the gate before anything live is
+  touched.
+- **Everything is detached.** No create path issues `switch-client`,
+  `select-window`, `select-pane`, or `attach-session`. `focus pane` and
+  `-o pane-id` are how a caller ends up in the new pane.
+- **Focus is navigation-only.** `focus project|window|pane` reads live tmux
+  inventory and may move an existing client, but has no Registry store and
+  issues no session/Window/Pane creation, identity-marker, rename, respawn, or
+  deletion write. An offline target remains offline and exits unresolved.
+
 Selector and the implicit active target:
 
 - A selector value is either `uid:<uid>` or a `metadata.name`. There is no
@@ -752,26 +1886,49 @@ Selector and the implicit active target:
 - Inside tmux, an invocation of a **singular read or rename verb** that carries
   no selector at all resolves the **active tmux target**: `get pane`,
   `describe project|window|pane|agent`, `rename project|window|pane`, and
-  `rebind project`. Any reference, scope flag, or label keeps the pre-existing
-  singular-target meaning; `create` and the destructive routes are unaffected.
-- Project is also the namespace-like default scope of the plural registry reads
-  `get windows|panes|agents`. When `--project` is absent inside tmux, the active
-  Window uid mirror and its registry owner chain derive a Project on every
-  invocation. This narrows the Window universe only; it never chooses one
-  Window, Pane, or Agent for the operator. `get projects` is above that scope,
-  while notifications and snapshots belong to separate stores, so all three
-  remain global.
+  `rebind project`. Any reference, scope flag, or label keeps picking the target
+  itself; the destructive routes are unaffected. `create` reads the same seam
+  under its own rule, described below.
+- The plural registry reads `get windows|panes|agents` use the active Window's
+  exact Registry owner as their default managed root. A Project-owned Window
+  exposes only that Project's descendants; a ControlSession-owned Window (the
+  Home control surface) exposes only that ControlSession's descendants. Name
+  and label selectors continue to filter inside that default root. An explicit
+  `uid:` selector is already opaque Registry-global authority, so it bypasses
+  active-root observation and narrowing, including from a foreign tmux Pane.
+  An in-tmux Window with no exact existing Project or ControlSession owner is a
+  usage refusal with zero stdout only when no explicit Project, whole-set, or
+  uid authority bypasses the default; it never silently falls back.
+- An **explicit singular reference** on `describe window|pane|agent` remains
+  Project-namespaced. Generic `rename window|pane|agent` instead derives the
+  exact Project or ControlSession that owns the active Window. When
+  `--project` is absent inside a managed Project, both families derive the
+  Project from the active Window uid mirror and Registry owner chain. This
+  narrows the Window universe only; it never
+  chooses one Window, Pane, or Agent for the operator, so a same-named pair
+  inside the one Project stays the ordinary bounded exact-one ambiguity and a
+  `uid:` reference outside the scope is a no-match rather than a cross-Project
+  hit. The describe family remains the intentional Project-only difference;
+  Phase 14 extends only the generic rename family to ControlSession.
+  `get projects`, `describe|rename project`, `delete`, `rebind`, and `agent
+  resume` are outside that reference scope, and notifications and snapshots
+  belong to separate stores. Delete's exact live preflight nevertheless follows
+  either root kind through the selected descendant's owner chain.
 - `--all-projects` is the explicit registry-wide escape for those three reads.
   It is deliberately different from destructive `delete --all`, whose existing
   whole-registry compatibility meaning is unchanged. A bare `--all` is not a
   read flag. Explicit `--project` keeps its prior result and cannot be combined
   with `--all-projects`.
-- Outside tmux, an omitted Project scope keeps the historical whole-registry
-  inventory. Inside tmux, a missing Window binding or broken Project owner chain
-  is a usage refusal with zero stdout, never a silent global fallback. The
-  selector engine's `windowScope` is the single choice point for explicit
-  Project, active-derived default, or global scope, shared by Window, Pane, and
-  Agent resolution.
+- Outside tmux, an omitted root scope keeps the historical whole-registry
+  inventory and its ambiguity, for a plural read and for a reference alike.
+  Inside tmux, a missing Window binding or broken managed-root owner chain is a
+  usage refusal with zero stdout, never a silent global fallback. The selector
+  engine's `windowScope` is the single choice point for explicit Project,
+  active-derived Project/ControlSession root, or global scope, shared by Window,
+  Pane, and Agent resolution. The plural default and the Project-only singular
+  namespace both fill `Query.DefaultRoot`; only the former can carry a
+  ControlSession kind. The default is consulted only after ruling out explicit
+  `--project`, `--all-projects`/`-A`, and any applicable `uid:` occurrence.
 - There is **no sentinel value token**. `current` and `active` pass
   `ValidateName`, so `--pane current` would shadow a resource that legitimately
   carries that name. Omission is the only spelling. If an explicit one is ever
@@ -784,8 +1941,9 @@ Selector and the implicit active target:
   select a wrong target.
 - Only two options are read: `@projmux_pane_uid` on the active pane and
   `@projmux_window_uid` on its window (window-scoped options resolve through a
-  pane target). Every ancestor above them comes from `ownerRef` — the Project is
-  the owner of the active Window, the Agent is the owner of the active Pane.
+  pane target). Every ancestor above them comes from `ownerRef` — the Project or
+  ControlSession is the owner of the active Window, and the Agent is the owner
+  of the active Pane.
   The session-scoped `@projmux_project_uid` is **not** consulted: it is
   measurably empty on live sessions, so trusting it would refuse targets the
   owner chain resolves.
@@ -800,7 +1958,10 @@ Selector and the implicit active target:
   a message naming what was inspected. It is deliberately not the
   `matched N ..., want exactly one` cardinality error, because an unmanaged pane
   carrying no `@projmux_pane_uid` is the common case and presenting it as
-  ambiguity would hide the cause.
+  ambiguity would hide the cause. An undecidable *namespace* refuses with its
+  own message rather than that one, because "no selector was given" is false on
+  an invocation that carried a reference and would send the operator after the
+  wrong cause.
 
 ## Naming metadata model
 
@@ -908,6 +2069,13 @@ network call.
 - **Failure preservation** — adapter failures do not erase prior
   rows. The Manager merges new snapshots over the on-disk slice, so a
   transient 429 keeps the last known good numbers visible.
+- **Codex native source selection** — the Codex adapter alone owns one
+  invocation's source decision. It normalizes native
+  `account/rateLimits/read` plus bounded sparse update events into snapshots;
+  only unavailable/unsupported/account-empty outcomes invoke the newest
+  rollout parser once. Native and rollout rows are never synthesized together.
+  Optional snapshot provenance preserves source, fallback/stale reason, and
+  native bucket label/cadence through Store and all public read surfaces.
 
 See [usage-tracking.md](usage-tracking.md) for adapter detail (token
 refresh, rollout schema).
@@ -942,6 +2110,39 @@ cache.
 
 ## Related design and inventory notes
 
+### Plan-only managed runtime mutation
+
+Managed lifecycle/topology changes are printable `runtimeMutationPlan` rows.
+Each row carries an exact invocation route, immutable observed socket path,
+printable server-generation authority, a stable tmux handle and Registry
+UID/owner chain, a closed guard, total order,
+expected effect, and printable typed operands bound to that handle. Execution
+validates printable target/route authority before pre-effect reobservation and
+every pending semantic guard before the first write;
+owned rollback runs in reverse order. Materialization is intentionally staged:
+after each dynamic handle is returned, it is reobserved and the next stage is
+planned, so no later action guesses a Window or Pane handle. A successful
+reobserve/replan is empty; an unknown observation authorizes no delete or kill.
+App-owned execution requires exact path/pid/app/logical evidence. An inherited
+standalone route is separately closed by exact `TMUX=path,pid,index` plus a
+producer-verified Pane receipt and prints/executes through `-S`; partial app
+markers never downgrade to standalone. Explicit controller reconciliation may
+instead use an operator-selected `--socket-path` plus PID/blank-marker receipt,
+but only action-specific UID and containment guards authorize its writes.
+Fresh app bootstrap is the only
+pre-server declaration without a generation receipt, and binds path/pid/$@%
+before its route marker and all later rows.
+
+The maintained product table in `internal/app/runtime_mutation_surface.go` maps
+generated catalog/menu producers, native provider/resume picker selections,
+sidebar/session-picker stops, and app lifecycle entrypoints in both directions
+to their handler and plan verb. It also records exact semantic exemptions for
+focus, labels, operator-requested layout, mouse forwarding, snapshot replay,
+ephemeral maintenance, app quit, and human runtime maintenance. Managed argv
+verbs are selected only by the typed executor seam; generated Window
+create/rename, Pane-menu create/delete, and automatic post-split layout writes
+reach typed intent/operand routes rather than embedding tmux lifecycle commands.
+
 Contributor-facing companions to this document. They are design records and
 inventories rather than user documentation, so they are linked from here rather
 than from the README docs index.