starred/orca
1
0
Fork 0
mirror of https://github.com/stablyai/orca.git synced 2026-09-22 16:02:32 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(terminal): track the terminal-session correctness handoff package

Browse Source 
The package was untracked under a gitignored `docs/**`, with the
un-ignore rules living only in an uncommitted .gitignore edit — a single
`git clean -xdf` would have destroyed the authoritative plan.

The 814-path construction snapshot is now pushed as
`nwparker/react185-authority-snapshot` too; it had no remote ref.

Co-authored-by: Orca <help@stably.ai>
This commit is contained in:
Neil
2026-08-08 19:11:53 -07:00
co-authored by Orca
parent b9d5842312
commit 72f4384a2d
6 changed files with 1561 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+2
View File
@@ -102,6 +102,8 @@ docs/**
!docs/reference/relay-grace-time-reconfiguration.md
!docs/reference/remote-wire-compatibility.md
!docs/reference/terminal-session-behavior-contract.md
!docs/reference/terminal-session-correctness-handoff-2026-08-07/
!docs/reference/terminal-session-correctness-handoff-2026-08-07/**
!docs/reference/windows-setup-shell.md
# Stably CLI (only docs/ are tracked)
docs/reference/terminal-session-correctness-handoff-2026-08-07/README.md
+259
View File
@@ -0,0 +1,259 @@
# Terminal session correctness and authority handoff
> **Status: preserved and paused, not complete, not release-ready.**
>
> The comprehensive program is at **0/8 proven goalposts** and
> **0/13 proven journeys**. No agent may narrow, replace, or mark a goalpost
> complete without the user's explicit approval and the proof named in this
> folder.
This folder is the sole continuation entrypoint for the work previously called
“React 185” or “terminal session authority.” That shorthand is too narrow: the
program covers terminal identity, ownership, exact operations, reconnect,
delivery, migration, daemon and SSH lifecycle, paired and remote runtimes,
cross-platform compatibility, performance, and removal of superseded code.
## Read in this order
1. Read all three preserved source documents with the exact `git show` commands
under [Repository checkpoint](#repository-checkpoint). The normative design,
delivery ledger, and original pause handoff are mandatory, not optional
implementation detail.
2. [`goalposts.md`](./goalposts.md) — the current completion contract, amendable
only by an explicit user decision.
3. [`related-open-work.md`](./related-open-work.md) — live PR/issue overlap and
conflicts.
4. [`resume-plan.md`](./resume-plan.md) — safe continuation order and required
validation receipts.
The older `terminal-session-authority-handoff-2.md` is useful as an adversarial
report, but it is not authoritative. In particular, its “descoped,” “shipped,”
identity-equivalence, timer, and LOC claims must not be copied as settled facts.
## Non-negotiable user objective
Deliver one coherent long-term terminal-session correctness model that:
- removes the root causes instead of leaving quarantine, retry-window,
sliding-window, optional-metadata repair, or other reconciliation as the
final correctness mechanism;
- never treats missing, unavailable, timed-out, disconnected, or unknown state
as proof that a process is dead or that replacement/destruction is safe;
- works for local terminals, daemon, WSL, direct and nested SSH, paired runtime,
remote server, folder workspaces, floating workspaces, and git worktrees;
- remains correct when clients and hosts update independently;
- works on macOS, Linux at the supported glibc floor, Windows, WSL, and Docker
OpenSSH;
- has no correctness, security, latency, throughput, memory, restore, startup,
backpressure, or large-pane regression;
- finishes with **strictly less aggregate production code than the frozen
pre-program baseline** after all superseded implementations are deleted; and
- is proven through real production paths and discriminating end-to-end
journeys, not inferred from test counts or green CI.
Correctness and performance cannot be weakened to reach the code-size target.
The code-size target also cannot be waived because a replacement architecture
was added beside the old one.
## Authority and scope rules
- Direct user instructions govern scope.
- The original normative design remains the contract except where a later,
explicit user decision changes a named requirement.
- This handoff tightens G6 to **strictly net-negative production LOC** because
the user explicitly asked to end with less production code than the original
baseline.
- The default frozen accounting baseline is
`5ed45739e94bdf6460364e033bfcec9b32c0b42a`, the base recorded by GitHub for
PR #12600. This program subsumes that containment PR. Every later
program-attributable merged prerequisite and every stack layer must be counted
in aggregate; rebasing may not roll the accounting baseline forward and hide
earlier additions. Changing this baseline requires an explicit user decision.
- Focused tests, green CI, a review comment, a behavior-contract document, an
open PR, or a construction milestone cannot amend the design or promote a
release goalpost.
- A replacement design is allowed, but it must map every original invariant,
risk, and journey to an equal or stronger mechanism, close the known liveness
gap, and receive explicit user approval before the ledger changes.
- Only `not started`, `partial`, and `proven` are valid gate statuses.
“Descoped,” “superseded,” and “met for what shipped” are not valid statuses
for G0–G7 under the current objective.
- A narrow incident PR may be independently useful or mergeable. It does not
reduce the comprehensive denominator of eight goalposts and thirteen
journeys.
## Settled status
| Scope | Status | Meaning |
| -------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Construction preservation | **Complete locally; not remotely durable** | The 814-path construction tree and the original three authority documents are preserved at local branch `nwparker/react185-authority-snapshot` / `fddb19f6977`. |
| Comprehensive goalposts | **0/8 proven** | G0–G4 and G6 are partial. G5 and G7 are not started. |
| Required journeys | **0/13 proven** | Focused and historical evidence exists, but no journey has its complete production oracle on the converged release tree. |
| Current branch / PR #13111 | **Implemented, open, unapproved, incomplete** | Useful narrow SSH containment; not a long-term completion and not merged. |
| PR #13110 | **Open, independent, unapproved** | Useful preload artifact guard; not shipped and has an unresolved major review thread. |
| Less-code gate | **Failed on current candidate** | PR #13111 is net positive; the preserved construction snapshot is net `+60,903` production LOC. |
The numeric release checkpoint is therefore:
- **G0:** partial
- **G1:** partial
- **G2:** partial
- **G3:** partial
- **G4:** partial
- **G5:** not started
- **G6:** partial and currently failing its final LOC condition
- **G7:** not started
- **Total:** **0/8 proven, 6/8 partial, 2/8 not started**
- **Journeys:** **0/13 proven**
This is the **program artifact ledger**. Its partial G0, G1, G3, and G4 evidence
exists only in the preserved construction snapshot and historical receipts. It
does not mean those implementations exist on the current #13111 branch. The
current candidate contributes credible partial G2 evidence and limited
compatibility/review evidence, but it proves **zero** complete release gates.
## Repository checkpoint
Verified before creating this documentation folder:
- Worktree:
`/Users/nwparker/orca/workspaces/orca/eye-React-185`
- Current branch: `nwparker/sta-3077-reattach-pane-cardinality`
- Current HEAD: `5369479be2953f45cea9ab5cfcde756dd9660548`
- HEAD subject: `fix(pty): let liveness say unknown instead of forcing it to say dead`
- Local `origin/main`: `0d29497f8279e2d4c2d26ffc8f3fb68cee2756a7`
- Merge base: `e6e197feeddd1adda066c5cd22f7ee056a12c8c1`
- Distance from local `origin/main`: 15 commits ahead, 19 behind
- The worktree was clean before this handoff. The expected handoff-only changes
are this folder and its `.gitignore` allow-list entry.
- Preserved construction branch:
`nwparker/react185-authority-snapshot`
- Preserved construction commit:
`fddb19f6977ae4ba4764c32afc9fe104c1ed2549`
- Preservation location: local ref only; the branch has no upstream, tag, or
remote branch containing this commit
- Snapshot status: **unshippable salvage/reference only**
The exact commit ID is the preservation anchor. Do not checkout, switch, reset,
rebase, commit, or push from the snapshot branch in the primary worktree. Read
its authority documents without switching branches:
```bash
git show fddb19f6977:docs/reference/terminal-session-authority.md
git show fddb19f6977:docs/reference/terminal-session-authority-delivery.md
git show fddb19f6977:docs/reference/terminal-session-authority-handoff.md
```
Mine tests, design arguments, or narrow implementations only through `git show`
or a disposable isolated worktree, and only after verifying that they address a
reachable production path on the current base. A local tag protects against
branch movement and ordinary GC only; it does not survive loss of this machine.
Cross-machine/crash preservation requires a copy-verified off-machine bundle or
an explicitly authorized remote ref. Do not infer permission to push it.
## Current narrow candidate: what is real
At current HEAD / PR
[#13111](https://github.com/stablyai/orca/pull/13111):
- SSH relay reattach passes `mayCreate: false` to stop that call site from
creating durable pane/layout state.
- Duplicate complete pane leases are superseded and excluded from reattach.
- Existing duplicate complete leases are reconciled during reconnect.
- Reattach failure paths require positive evidence before cold respawn.
- PTY inventory can report `unknown` rather than collapsing an unavailable
provider into `false`/dead.
- Focused tests and GitHub checks are green at HEAD.
These are credible partial G2 improvements. They do **not** establish the
comprehensive design or release gates.
## Current narrow candidate: what remains unproved or wrong
- Lease row identity is still `(targetId, ptyId)`. Pane fields remain optional.
Active-pane cardinality is enforced by sibling expiration and a healing scan,
so the end state remains reconciliation-based rather than structurally
pane-keyed.
- Incomplete legacy leases bypass pane arbitration.
- Superseded remote shells are deliberately left running and unreachable. The
PR body acknowledges that the “accumulates unused shells” half of the incident
remains unresolved.
- The Docker reconnect test says it passes with and without the fix. It is a
forward guard, not causal proof of the customer defect.
- The final Docker settle assertion has an unresolved major review thread: a
late pane or shell can appear after the polling assertion has already passed.
- The production-call-site wiring oracle reads source text. It does not execute
the full production reattach path.
- `mayCreate: false` is wired at one production binding call site, not proven
across every recovery/reattach runtime. `removeSshRemotePtyLease` still has one
production caller, the spawn-persistence rollback.
- `WEDGED_DAEMON_GRACE_RETRIES = 11` remains reachable and still permits retry
count to drive daemon replacement after unknown inventory.
- `terminal-input-quarantine.ts` remains reachable.
- No current-tree proof covers physical Windows, WSL, the Linux glibc floor,
paired runtime, remote server, two independent SSH hosts, live mixed-version
peers, or production-scale performance.
- There is no candidate-versus-baseline performance result for the new
per-upsert sibling scan or reconnect healing pass.
- PR #13111 is open, has no approval decision, and is not shipped.
Current HEAD census against its merge base, before this documentation change:
| Category | Additions | Deletions | Net |
| --------------------------------------------------- | --------: | --------: | -------: |
| Production source, including a fixture under `src/` | 374 | 65 | **+309** |
| Tests and end-to-end tests | 944 | 30 | +914 |
| Documentation | 146 | 0 | +146 |
| CI/configuration | 43 | 0 | +43 |
| Total GitHub diff | 1,507 | 95 | +1,412 |
The production source plus Docker runner is net `+350`. Whichever taxonomy is
used, the categories must remain separate and G6 is not proven.
## Corrections to the previous handoff
- PRs #13110 and #13111 are **open and green**, not shipped.
- #13110 is implementation-independent from #13111, but emitted-preload safety
remains inside G0/G5/G7 and any retained #13110 production/build logic counts
in the aggregate G6 census.
- The snapshot genuinely failed to wire `mayCreate`, pane-cardinality
arbitration, or a complete shell-lifecycle fix into the affected legacy SSH
path.
- Pane key, PTY ID, incarnation ID, a narrow CAS, and a three-valued daemon
resolver pre-existed and should be reused where their semantics match.
- Existing `connectionId` and `worktreeId` do **not** establish equivalence to a
final-host-minted authority identity and canonical host-local namespace.
- The normative design never banned all timers. It permits bounded waits and
backoff; it forbids elapsed time or retry count **alone** from deciding
identity, liveness, takeover, replacement, or destruction.
- The design does have a liveness gap: a permanently lost retained consumer can
hold compaction at capacity without a sufficiently explicit bounded operator
recovery path. G0 and G3 cannot become proven until that is resolved.
- The claimed approximately 6,500-line comparison implementation has no
reproducible census and cannot justify deleting requirements.
## Definition of done
The comprehensive work is done only when all of the following are true on one
rebased, converged candidate SHA:
- every G0–G7 section in [`goalposts.md`](./goalposts.md) has its named
production implementation and current proof;
- all thirteen required journeys pass with their full oracles;
- each new causal oracle is red on the unfixed baseline and green on the final
candidate; formal verification may supplement but never replace a required
live journey;
- every open incident bound to the mandatory issue-to-journey matrix in
[`related-open-work.md`](./related-open-work.md) passes its discriminating
oracle or is ruled unrelated with explicit evidence and user acceptance;
- correctness, security, wire, migration, platform, packaging, performance,
restore, and scale reviews have no unresolved P0–P2 findings;
- the aggregate production source census is strictly net-negative against the
frozen pre-program baseline, including all program-attributable prerequisite
PRs and stack layers;
- no superseded reconciliation, quarantine, duplicate state machine, legacy
writer, or test fixture remains reachable in production; and
- the user explicitly accepts any deliberate change to the normative design.
Anything less must be reported as partial, regardless of test count or PR
state.
docs/reference/terminal-session-correctness-handoff-2026-08-07/github-overlap-query.graphql
+324
View File
@@ -0,0 +1,324 @@
query TerminalSessionCorrectnessRelatedWork {
repository(owner: "stablyai", name: "orca") {
n8129: issueOrPullRequest(number: 8129) {
...IssueDetails
...PullRequestDetails
}
n8275: issueOrPullRequest(number: 8275) {
...IssueDetails
...PullRequestDetails
}
n8585: issueOrPullRequest(number: 8585) {
...IssueDetails
...PullRequestDetails
}
n8618: issueOrPullRequest(number: 8618) {
...IssueDetails
...PullRequestDetails
}
n9034: issueOrPullRequest(number: 9034) {
...IssueDetails
...PullRequestDetails
}
n9092: issueOrPullRequest(number: 9092) {
...IssueDetails
...PullRequestDetails
}
n9093: issueOrPullRequest(number: 9093) {
...IssueDetails
...PullRequestDetails
}
n9138: issueOrPullRequest(number: 9138) {
...IssueDetails
...PullRequestDetails
}
n9562: issueOrPullRequest(number: 9562) {
...IssueDetails
...PullRequestDetails
}
n9585: issueOrPullRequest(number: 9585) {
...IssueDetails
...PullRequestDetails
}
n9819: issueOrPullRequest(number: 9819) {
...IssueDetails
...PullRequestDetails
}
n9820: issueOrPullRequest(number: 9820) {
...IssueDetails
...PullRequestDetails
}
n9827: issueOrPullRequest(number: 9827) {
...IssueDetails
...PullRequestDetails
}
n9833: issueOrPullRequest(number: 9833) {
...IssueDetails
...PullRequestDetails
}
n10118: issueOrPullRequest(number: 10118) {
...IssueDetails
...PullRequestDetails
}
n10208: issueOrPullRequest(number: 10208) {
...IssueDetails
...PullRequestDetails
}
n10235: issueOrPullRequest(number: 10235) {
...IssueDetails
...PullRequestDetails
}
n10385: issueOrPullRequest(number: 10385) {
...IssueDetails
...PullRequestDetails
}
n10415: issueOrPullRequest(number: 10415) {
...IssueDetails
...PullRequestDetails
}
n10744: issueOrPullRequest(number: 10744) {
...IssueDetails
...PullRequestDetails
}
n11006: issueOrPullRequest(number: 11006) {
...IssueDetails
...PullRequestDetails
}
n11265: issueOrPullRequest(number: 11265) {
...IssueDetails
...PullRequestDetails
}
n11339: issueOrPullRequest(number: 11339) {
...IssueDetails
...PullRequestDetails
}
n11342: issueOrPullRequest(number: 11342) {
...IssueDetails
...PullRequestDetails
}
n11495: issueOrPullRequest(number: 11495) {
...IssueDetails
...PullRequestDetails
}
n11574: issueOrPullRequest(number: 11574) {
...IssueDetails
...PullRequestDetails
}
n11575: issueOrPullRequest(number: 11575) {
...IssueDetails
...PullRequestDetails
}
n11596: issueOrPullRequest(number: 11596) {
...IssueDetails
...PullRequestDetails
}
n11622: issueOrPullRequest(number: 11622) {
...IssueDetails
...PullRequestDetails
}
n11729: issueOrPullRequest(number: 11729) {
...IssueDetails
...PullRequestDetails
}
n11800: issueOrPullRequest(number: 11800) {
...IssueDetails
...PullRequestDetails
}
n11801: issueOrPullRequest(number: 11801) {
...IssueDetails
...PullRequestDetails
}
n11803: issueOrPullRequest(number: 11803) {
...IssueDetails
...PullRequestDetails
}
n11804: issueOrPullRequest(number: 11804) {
...IssueDetails
...PullRequestDetails
}
n11904: issueOrPullRequest(number: 11904) {
...IssueDetails
...PullRequestDetails
}
n12036: issueOrPullRequest(number: 12036) {
...IssueDetails
...PullRequestDetails
}
n12134: issueOrPullRequest(number: 12134) {
...IssueDetails
...PullRequestDetails
}
n12140: issueOrPullRequest(number: 12140) {
...IssueDetails
...PullRequestDetails
}
n12220: issueOrPullRequest(number: 12220) {
...IssueDetails
...PullRequestDetails
}
n12241: issueOrPullRequest(number: 12241) {
...IssueDetails
...PullRequestDetails
}
n12264: issueOrPullRequest(number: 12264) {
...IssueDetails
...PullRequestDetails
}
n12339: issueOrPullRequest(number: 12339) {
...IssueDetails
...PullRequestDetails
}
n12447: issueOrPullRequest(number: 12447) {
...IssueDetails
...PullRequestDetails
}
n12448: issueOrPullRequest(number: 12448) {
...IssueDetails
...PullRequestDetails
}
n12456: issueOrPullRequest(number: 12456) {
...IssueDetails
...PullRequestDetails
}
n12474: issueOrPullRequest(number: 12474) {
...IssueDetails
...PullRequestDetails
}
n12477: issueOrPullRequest(number: 12477) {
...IssueDetails
...PullRequestDetails
}
n12568: issueOrPullRequest(number: 12568) {
...IssueDetails
...PullRequestDetails
}
n12600: issueOrPullRequest(number: 12600) {
...IssueDetails
...PullRequestDetails
}
n12634: issueOrPullRequest(number: 12634) {
...IssueDetails
...PullRequestDetails
}
n12683: issueOrPullRequest(number: 12683) {
...IssueDetails
...PullRequestDetails
}
n12699: issueOrPullRequest(number: 12699) {
...IssueDetails
...PullRequestDetails
}
n12702: issueOrPullRequest(number: 12702) {
...IssueDetails
...PullRequestDetails
}
n12743: issueOrPullRequest(number: 12743) {
...IssueDetails
...PullRequestDetails
}
n12749: issueOrPullRequest(number: 12749) {
...IssueDetails
...PullRequestDetails
}
n12751: issueOrPullRequest(number: 12751) {
...IssueDetails
...PullRequestDetails
}
n12760: issueOrPullRequest(number: 12760) {
...IssueDetails
...PullRequestDetails
}
n12768: issueOrPullRequest(number: 12768) {
...IssueDetails
...PullRequestDetails
}
n12798: issueOrPullRequest(number: 12798) {
...IssueDetails
...PullRequestDetails
}
n12882: issueOrPullRequest(number: 12882) {
...IssueDetails
...PullRequestDetails
}
n12903: issueOrPullRequest(number: 12903) {
...IssueDetails
...PullRequestDetails
}
n12987: issueOrPullRequest(number: 12987) {
...IssueDetails
...PullRequestDetails
}
n13013: issueOrPullRequest(number: 13013) {
...IssueDetails
...PullRequestDetails
}
n13110: issueOrPullRequest(number: 13110) {
...IssueDetails
...PullRequestDetails
}
n13111: issueOrPullRequest(number: 13111) {
...IssueDetails
...PullRequestDetails
}
p13110: pullRequest(number: 13110) {
...ReviewDetails
}
p13111: pullRequest(number: 13111) {
...ReviewDetails
}
}
}
fragment IssueDetails on Issue {
number
title
url
state
stateReason
updatedAt
}
fragment PullRequestDetails on PullRequest {
number
title
url
state
isDraft
merged
reviewDecision
mergeable
mergeStateStatus
headRefName
baseRefName
additions
deletions
changedFiles
updatedAt
commits(last: 1) {
nodes {
commit {
oid
statusCheckRollup {
state
}
}
}
}
}
fragment ReviewDetails on PullRequest {
reviewThreads(first: 100) {
nodes {
isResolved
isOutdated
comments(last: 1) {
nodes {
url
author {
login
}
}
}
}
}
}
docs/reference/terminal-session-correctness-handoff-2026-08-07/goalposts.md
+362
View File
@@ -0,0 +1,362 @@
# Goalposts and proof contract
This file answers one question: **what exact evidence is required before an
agent may write “proven”?**
The current status is frozen at **0/8 proven goalposts** and **0/13 proven
journeys**. Status may change only from evidence produced on the same rebased,
converged release candidate. Historical snapshot tests and independently useful
narrow PRs may be cited as partial evidence but cannot promote a row.
## Universal proof rule
A gate is `proven` only when both exist:
1. the complete behavior is reachable through every named production path; and
2. the named proof exercises that behavior and its failure boundaries on the
final candidate.
Every proof receipt must record:
- candidate commit SHA and exact merge base;
- unfixed baseline SHA used for red/green discrimination;
- exact command or manual journey protocol;
- OS, architecture, filesystem, runtime, Git, SSH, daemon, relay, client, and
host versions relevant to that journey;
- UTC start/end time, exit status, counts, and artifact/log location;
- the production caller, persistence boundary, transport, and cleanup path
exercised;
- the expected oracle and the observed result; and
- independent reviewer identity and unresolved-finding count.
For a new regression oracle, demonstrate that it fails for the intended reason
on the unfixed baseline and passes on the candidate. A test that passes both is
a forward guard and cannot prove the fix.
## G0 — One design contract
**Current status: partial.**
G0 is proven only when:
- every reachable production path follows one reconciled identity, host
boundary, operations, delivery, migration, compatibility, and minimal-shape
contract;
- there is one final-host authority service, thin transport adapters, one app
projection/controller, and one bounded pre-cutover legacy importer;
- no adapter or renderer owns a parallel authority state machine;
- all retained existing primitives are mapped by semantics, not similar names;
- the lost-consumer/compaction liveness gap has a safe, bounded, authenticated,
operator-reachable resolution that does not infer death from time; and
- an independent production-graph audit finds no contradictory path.
The design document alone, a behavior contract, or focused tests do not prove
G0.
## G1 — One final-host authority
**Current status: partial.**
G1 is proven only when local, daemon, WSL, direct SSH, nested SSH, paired
runtime, and remote server all resolve:
- a stable identity minted or validated by the final PTY-owning host;
- a canonical host-local namespace for worktree, folder, and floating
workspaces;
- one exact pane-generation/PTY-incarnation binding;
- host connections keyed by final-host identity with lazy discovery;
- concurrent host isolation; and
- namespace-local admission, failure, grant, handover, and retirement.
`connectionId`, SSH target ID, client repository ID, path spelling, or
`worktreeId` may be routing metadata. Their existing names and usage counts are
not proof that they satisfy final-host identity or namespace semantics.
Proof requires the applicable live journeys below, including simultaneous hosts
and independent client/host updates.
## G2 — Exact operations only
**Current status: partial.**
G2 is proven only when input, resize, signal, close, output, and exit are fenced
by the full binding captured before any await:
- authority host;
- namespace;
- pane generation;
- owner/writer incarnation;
- physical PTY;
- PTY incarnation; and
- negotiated operation/source generation where applicable.
Stale, partial, absent, timed-out, disconnected, or unknown evidence must not
affect a successor. An authoritative operation must never retry through an
ID-only provider call or a legacy mutation path.
Proof must cover all operations across local, daemon, WSL, SSH, paired runtime,
remote server, renderer fallback, restart, concurrent replacement, and both
mixed-version directions. Store-row counts and source-text assertions are not
sufficient.
## G3 — Durable ordered delivery
**Current status: partial.**
G3 is proven only when the final production design provides all observable
properties below, even if its internal mechanism differs from the preserved
construction design:
- complete boundary snapshot before later events;
- producer held while boundary/replay is established;
- contiguous replay before reconciliation and live resume;
- durable semantic outcomes, including exit and state needed by a newly
attached consumer;
- durable idempotent main-process projection before acknowledgement;
- final-host-owned cumulative acknowledgement or an explicitly approved
equivalent with the same crash/replay guarantees;
- renderer snapshot-plus-delta observation;
- app, renderer, host, and transport restart resume;
- gap detection and resnapshot without silent omission;
- bounded memory, queues, pages, listeners, timers, and retained output;
- independent consumer retirement and safe compaction liveness; and
- no app-side duplicate cursor, settlement, receipt, or suffix-reconciliation
authority.
Proof must include crash-before/after-ACK cuts, lost responses, disconnected
replay, gap recovery, slow/stalled consumers, retired and permanently lost
consumers, paired/remote restart, mixed versions, and scale.
## G4 — One-way legacy cutover
**Current status: partial.**
G4 is proven only when each namespace performs, in order:
1. explicit capability negotiation;
2. a brief legacy-write freeze;
3. exact non-mutating inventory;
4. a deterministic import plan;
5. validation with ambiguity kept visible and non-destructive;
6. one self-contained durable authority commit;
7. topology attachment; and
8. exact client opening through the authoritative path.
There must be no dual writer, destructive inference, authority-to-legacy
fallback, or second durable migration catalog after cutover. Old peers remain
on an unchanged isolated legacy surface or fail before mutation.
Proof requires crash cuts at every phase, replay from the self-contained commit,
ambiguous-row isolation, independent namespace failure, and legacy-writer and
reconciliation deletion.
## G5 — Wire and platform compatibility
**Current status: not started.**
G5 is proven only when all exchanged changes follow the remote-wire
compatibility contract and the final candidate passes:
- old client to new host;
- new client to old host;
- native macOS;
- native Linux at Ubuntu 20.04 / glibc 2.31 compatibility floor;
- native Windows;
- physical WSL, including Git Bash/`.cmd` boundaries where relevant;
- Docker OpenSSH;
- daemon;
- direct and nested SSH;
- paired runtime;
- remote server;
- git worktree;
- folder workspace;
- floating workspace; and
- drive-letter and UNC namespace paths.
Run both skew directions independently across every changed deployment boundary:
app↔daemon, app↔SSH relay/final host, paired client↔paired runtime, remote
client↔remote server, and mobile/E2EE RPC where affected. A single in-process
codec test or one client/host pairing cannot stand in for this matrix.
New opcodes or semantics require explicit capability negotiation. An optional
field that parses on an old peer does not by itself prove that old behavior
remains correct.
Mocking `process.platform`, running Linux inside Docker, or passing in-process
wire unit tests does not prove the corresponding native or live-skew row.
## G6 — Simpler, strictly smaller production code
**Current status: partial; final size condition currently fails.**
The user has tightened this gate: the final integrated program must contain
strictly less production source than its frozen pre-program baseline.
The default baseline is
`5ed45739e94bdf6460364e033bfcec9b32c0b42a`, the base recorded by GitHub for
PR #12600. This broader program subsumes #12600. Changing the baseline requires
an explicit user decision recorded before more implementation begins.
G6 is proven only when:
- aggregate program-attributable production source net LOC is **less than
zero** against the frozen baseline;
- every program-attributable prerequisite merged after the baseline and every
stacked PR is included, even if a later rebase places it in `main`;
- overlapping changes are recomputed from the frozen baseline to the final tree
so additions and later deletions are not double-counted;
- unrelated upstream or user deletions cannot offset program additions;
- production, test, documentation, CI/runner, generated, and vendored changes
are reported separately;
- every new production module is reachable from a real entrypoint;
- no test fixture remains under production compilation;
- there is one identity comparison, transition implementation, exact-operation
client, mutation admission path, and delivery state machine;
- no re-export shim or one-type module exists solely to preserve construction
layering;
- no superseded quarantine, sliding-window, retry-verdict, reconciliation,
duplicate cursor, receipt ledger, legacy writer, or migration bridge remains
reachable after cutover; and
- an independent reachability and duplicate-state-machine audit is clean.
Tests or docs cannot offset positive production LOC. A smaller narrow PR is not
proof if the final stack remains net positive. Deleting correctness or platform
coverage to hit the number is prohibited.
Classify by behavior, not directory name: shipped runtime code, migration code,
and build-time code that enforces a shipped artifact invariant are production;
test-only runners and fixtures are tests even when misplaced, and their presence
under production compilation independently fails this gate. Publish the final
file-by-file classification so the count cannot be moved between buckets.
## G7 — No regression and reviewable comprehensive change
**Current status: not started.**
G7 is proven only on the rebased, converged candidate after G0–G6 and all
thirteen journeys are proven. It requires:
- correctness and security gates;
- A/B input latency and output throughput;
- backpressure and bounded-memory results;
- renderer/app/daemon/relay restore and startup results;
- large-pane, long-session, and multi-host scale results;
- native packaging/startup on macOS, Linux, and Windows;
- WSL, Docker SSH, paired, remote, folder, floating, worktree, drive, and UNC
coverage;
- both live mixed-version directions;
- final categorized LOC census;
- independent repository review with no unresolved P0–P2 findings;
- release-readiness review with no unresolved correctness, security,
compatibility, or performance findings; and
- a detailed comprehensive PR whose claims match the receipts.
Before implementation, record a performance protocol that makes “no
regression” falsifiable:
- fixed candidate and baseline builds, hardware, OS, power mode, network shape,
pane/session population, payloads, and background-load policy;
- warm-up policy, randomized A/B order, sample count, raw-data location, and
statistical method;
- input latency, output throughput, memory, backpressure, restore, startup, and
large-pane metrics with directionality;
- deterministic ceilings for writes, scans, queues, listeners, timers, and
allocations on hot paths; and
- a predeclared equivalence/no-regression bound no larger than measured baseline
noise. A nonzero bound handles measurement noise; it is not permission for a
known slowdown and requires explicit user approval.
Unless an independently reviewed protocol justifies another count, use at least
five warm-up trials and thirty measured trials per latency/startup/restore
configuration, retain raw samples, and report confidence intervals. Throughput,
backpressure, and memory tests must also include a fixed-duration steady-state
run and a leak-slope result. Choose all workloads and thresholds before looking
at candidate results.
Green CI, thousands of tests, mergeability, or “reviewable for what shipped” do
not prove G7.
## Thirteen required production journeys
Every row is currently **not proven**.
The issue-to-journey matrix in
[`related-open-work.md`](./related-open-work.md#mandatory-issue-to-journey-matrix)
is part of these journeys, not optional context. Every bound incident needs a
red-on-baseline/green-on-candidate oracle, or explicit evidence plus user
acceptance that it is unrelated.
| # | Journey | Required oracle |
| --: | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 | Local macOS, Linux, and Windows | The same pane, full binding, and OS process survive renderer and app restart; every stale exact operation is rejected. Run natively on all three OSes. |
| 2 | Daemon and physical WSL | The same PTY survives client and daemon reconnect/restart boundaries; generation skew fails closed without killing or replacing a live successor. |
| 3 | Lazy discovery and skipped-host restart | An unused host is not probed eagerly. After a restart that skipped it, lazy rediscovery restores only that host's sessions and never adopts host-current or sibling-host state. |
| 4 | Concurrent multi-host connections | At least two distinct final-host connections operate simultaneously. One host's disconnect, CAS, timeout, or failure cannot affect the other. |
| 5 | Namespace-partial admission failure | One namespace on a multiplexed connection fails challenge/CAS/grant publication while another commits. Only the failed host-plus-namespace is fenced. |
| 6 | Docker OpenSSH with `MaxSessions=1` | The same remote PID and exact binding survive disconnect and client restart. Authority restart imports exactly or exposes unresolved recovery without creating, killing, or adopting. Explicit close or exact proven teardown durably retires the lease and process; unknown ownership stays visible and recoverable rather than being killed. Count actual remote processes, panes, tabs, bindings, leases, and session-cap slots before and after a settle interval. |
| 7 | Two independent Docker SSH hosts | Two simultaneous final hosts keep endpoint credentials, principals, namespaces, sessions, cursors, failures, and cleanup completely isolated. |
| 8 | Paired client and remote server | The final host remains authoritative across independently updated peers, pairing reconnect, client restart, and remote-runtime restart. |
| 9 | Worktree, folder, floating, drive, and UNC namespaces | Each resolves the same stable host-local namespace across spelling/restart changes, without using client repository ID or target ID as identity. |
| 10 | Stable proof and exact retry | One bounded device proof identity admits fresh process/session nonces. A lost response retries the exact challenge/request; changed, replayed, cross-host, cross-namespace, or host-current state is rejected. |
| 11 | Identity reset and re-enrollment | Crash-resumable host retirement, relay revoke acknowledgement, transport closure, local credential removal, and atomic successor publication occur in order. Offline and old peers remain explicitly pending. |
| 12 | Mixed versions in both directions | No unknown opcode or ungranted publication mutates state. Unsupported challenge, grant, delivery, or operation semantics stay on isolated legacy behavior or fail before mutation. |
| 13 | Performance and scale | Under the predeclared protocol above, input/output latency, throughput, backpressure, memory, reconnect/restore, startup, large-pane, long-session, and multi-host ceilings show no regression against the fixed baseline. Raw samples, confidence intervals, deterministic counters, and leak slopes satisfy their predeclared bounds. |
## Cross-cutting correctness cases
Every relevant journey must exercise:
- stale, missing, unknown, rejected, timed-out, and disconnected evidence;
- concurrent replacement and sibling-host/namespace isolation;
- lost request and lost response;
- cancellation and partial setup cleanup;
- crash immediately before and after every durable boundary;
- restart from disk rather than process-memory state;
- duplicate and out-of-order delivery;
- gaps, overflow, and slow/stalled consumers;
- explicit close versus detach;
- eventual exact retirement after explicit close or proven teardown while
uncertain ownership remains intact and visible;
- legacy data with missing optional fields;
- relay/daemon incarnation reuse;
- sleep/resume and clock movement where timers schedule retries;
- exact remote process/PID census, not only persisted-row state; and
- cleanup that requires positive identity proof.
## Forbidden proof substitutions
- A mock is not a native-platform journey.
- A source grep is not a production call-path journey.
- A row marked `expired` is not proof that its remote process exited.
- Optional pane metadata plus an O(n) repair scan is not structural uniqueness.
- An empty list from an unavailable provider is not proof of absence.
- A timer or retry budget is not proof of death.
- A broad test count is not a correctness oracle.
- A test that passes unfixed code is not evidence that a change fixed the bug.
- An open or green PR is not shipped behavior.
- Historical construction receipts are not proof for a rebased candidate.
- Prior art or an uncited LOC comparison cannot delete a requirement.
## Promotion template
Before changing any row to `proven`, add a receipt containing:
```text
Gate or journey:
Candidate SHA:
Merge-base SHA:
Unfixed/red SHA:
Production path exercised:
Exact command or manual protocol:
Environment and versions:
Expected oracle:
Red result:
Green result:
UTC start/end:
Artifact/log:
Independent reviewer:
Unresolved P0/P1/P2:
LOC/performance impact:
```
If any field is missing, the row remains partial or not started.
docs/reference/terminal-session-correctness-handoff-2026-08-07/related-open-work.md
+341
View File
@@ -0,0 +1,341 @@
# Related GitHub work
This is a curated overlap map, not a merge queue. States were verified against
GitHub on 2026-08-08 UTC and must be refreshed before any rebase, merge, close,
or implementation decision.
Rules:
- Do not stack PRs merely because they appear in the same section.
- “Conflict” means semantic or file overlap that requires one coherent design,
not an instruction to merge both.
- A related PR can supply diagnosis, tests, or a small reusable primitive
without becoming a dependency.
- Landing a related PR does not promote G0–G7 or one of the thirteen journeys
unless the final converged tree passes that gate's complete proof.
- GitHub issue/PR text is context, not authority over the user's goal.
## Immediate incident and competing implementations
- [Issue #11729 — SSH remote environment not restored after login on Rocky Linux
9.4](https://github.com/stablyai/orca/issues/11729) — **open**. This is the
named STA-3077 customer incident. Its final acceptance must include Rocky
Linux SSH, repeated reconnect, the same PID/process/session/transcript
identity, restored workspace environment, visible pane count, and actual
remote relay PTY/process count.
- [PR #13111 — stop reconnect grafting panes, stacking leases, and respawning
live shells](https://github.com/stablyai/orca/pull/13111) — **open**, current
branch, green checks, no approval. It is narrow containment and leaves remote
shell reclamation unresolved. One major Docker settle review thread remains
[unresolved](https://github.com/stablyai/orca/pull/13111#discussion_r3739665033).
- [PR #12264 — stop reconnect from grafting ghost terminal
panes](https://github.com/stablyai/orca/pull/12264) — **open and conflicting**.
It targets the same incident and overlaps persistence, PTY, SSH relay, and E2E
files. Mine its diagnosis and discriminating artifacts; do not stack it
wholesale with #13111.
- [PR #12743 — contain reattach to existing panes, quarantine
orphans](https://github.com/stablyai/orca/pull/12743) — **open and
conflicting**. It shares `mayCreate: false` and broader relay coverage, but
quarantine must be judged against the no-reconciliation final design.
- [PR #12456 — reattach on `restoreRequired` instead of expiring a live
session](https://github.com/stablyai/orca/pull/12456) — **open**. It addresses
the #12448 branch through retry rather than cold respawn. Treat it as a
semantic alternative or complementary recovery path only after choosing one
exact restore protocol.
- [PR #9820 — reap orphaned relay PTYs before session-cap
exhaustion](https://github.com/stablyai/orca/pull/9820) — **open**. Its
time-based remote kill conflicts with unknown-is-not-dead and #13111's
deliberate non-kill behavior. Use it as incident evidence, not a safe default
dependency.
- [PR #12798 — opt-in zmx-backed durable SSH
terminals](https://github.com/stablyai/orca/pull/12798) — **open**. This is a
broad architectural alternative for final remote PTY ownership with direct
file overlap. Evaluate capability-by-capability; never blend it into the
current model accidentally.
## Open incident issues that should become explicit oracles
- [Issue #9819 — SSH relay leaks orphaned PTYs until the 50-session
cap](https://github.com/stablyai/orca/issues/9819) — explicit close,
disconnected close with a lost shutdown response, and worktree teardown must
durably retry retirement of the exact lease and process. Uncertain sessions
must survive visibly until resolved. Repeated reconnect must reclaim actual
relay PIDs/session slots rather than accumulate toward the cap.
- [Issue #9034 — SSH reconnect repeatedly spawns detached PTYs for one
pane](https://github.com/stablyai/orca/issues/9034) — count actual remote PTYs
and prove bounded one-pane ownership across repeated reconnect.
- [Issue #11006 — transient SSH disconnect treats live relay PTYs as dead and
duplicate-respawns agents](https://github.com/stablyai/orca/issues/11006) —
disconnect with a live process must remain unresolved/reattachable and must
not start another agent.
- [Issue #12447 — closed SSH tabs resurrect and auto-resume old
sessions](https://github.com/stablyai/orca/issues/12447) — explicit close must
persist its pending tombstone before a kill RPC, survive a lost reply plus app
and relay restart, retry after handshake, reclaim the exact remote PTY, and
never recreate UI or automatic resume.
- [Issue #12448 — `restoreRequired` is misreported as session
expiry](https://github.com/stablyai/orca/issues/12448) — source recovery must
replay/repaint on the same PID and binding without starting a replacement
`--resume`; identity drift, timeout, or unknown state must not become proof of
process death or cold resume authority.
- [Issue #12699 — SSH sleeping-agent wake sweep forks live remote
sessions](https://github.com/stablyai/orca/issues/12699) — all wake/resume
paths must share the same exact liveness and identity contract.
- [Issue #12683 — remote-runtime disconnect spends recovery on stale same-handle
reattach](https://github.com/stablyai/orca/issues/12683) — paired/web terminal
recovery must fence generations and retain automatic liveness.
- [Issue #10208 — duplicate terminal tab on worktree session
restore](https://github.com/stablyai/orca/issues/10208) — local/worktree
restore must prove the same pane and process rather than creating a duplicate.
These issues are separate customer-visible symptoms. A single structural model
should make their shared invalid transitions impossible, while each issue keeps
its own discriminating regression journey.
## Daemon, relay generation, and liveness work
The acceptance matrix must also reproduce these open lifecycle incidents:
- [Issue #11904 — tab close with a broken binding orphans the daemon
session](https://github.com/stablyai/orca/issues/11904) — close intent must be
durable before transport work and eventually retire the exact process.
- [Issue #8585 — detached relay generations are never
reaped](https://github.com/stablyai/orca/issues/8585) — termination must name
the exact relay generation; path/PID reuse or a failed connection cannot kill
a successor.
- [Issue #9138 — updates leave old daemon generations and sessions
alive](https://github.com/stablyai/orca/issues/9138) and
[issue #11342 — stale daemon/PTY generations leak across upgrade and
close](https://github.com/stablyai/orca/issues/11342) — upgrade must converge
without invisible sessions, guessed ownership, or unbounded retention.
- [Issue #10415 — Windows daemon crash on unkillable PTY and protocol
bump](https://github.com/stablyai/orca/issues/10415) — native Windows must
preserve live old-generation sessions or expose exact unresolved recovery;
one unkillable PTY cannot crash the daemon.
- [Issue #8275 — worktree teardown kills unrelated split-pane
sessions](https://github.com/stablyai/orca/issues/8275) — teardown and failure
must remain exact-namespace/exact-binding scoped.
- [PR #12882 — publisher-owned daemon endpoint
replacement](https://github.com/stablyai/orca/pull/12882) — **open and
mergeable** when checked. It provides single-writer endpoint publication and
three-valued liveness. Reconcile it before editing overlapping daemon paths;
do not assume the older handoff's merge order is still current.
- [PR #11622 — fence daemon session ownership across
generations](https://github.com/stablyai/orca/pull/11622) — **open** and held
behind further audit per its description. Strong explicit
owned/unavailable/ambiguous semantics, but broad overlap makes it design input,
not an automatic dependency.
- [PR #9833 — report local PTY inventory
readiness](https://github.com/stablyai/orca/pull/9833) — **open**. Its
pending/ready/stale distinction is reusable context for unknown-is-not-dead.
- [PR #12760 — reap only the proven relay
generation](https://github.com/stablyai/orca/pull/12760) — **open**. It adds
exact relay generation ownership before termination and conflicts in
`ssh-relay-session.ts`; reconcile before designing remote shell cleanup.
- [PR #8618 — reap a detached relay after failed
reconnect](https://github.com/stablyai/orca/pull/8618) — **open** and an older
competing predecessor to #12760. Do not combine both ownership schemes.
- [PR #12749 — wait for a disconnected PTY owner's full
grace](https://github.com/stablyai/orca/pull/12749) — **open**. Useful owner
admission and grace context; timers may schedule retry but cannot independently
authorize takeover or destruction.
- [PR #12702 — stop sleeping-agent wake sweep from forking live SSH
sessions](https://github.com/stablyai/orca/pull/12702) — **open**. Complementary
#12699 work that must converge on the same ownership/liveness behavior; it
need not share an internal primitive unless the reconciled design calls for
one.
- [PR #10118 — durable persistence write
seam](https://github.com/stablyai/orca/pull/10118) — **open**. It overlaps
`persistence.ts` and is relevant to durability and main-thread performance;
reconcile before large persistence changes.
## Paired runtime, remote server, and E2EE lifecycle work
These open issues are mandatory inputs to the paired/remote/platform journeys:
- [Issue #11495 — paired viewer loses attachments across update/restart while
host PTYs remain alive](https://github.com/stablyai/orca/issues/11495) — the
reported large host population is a strong restore/scale oracle; each pane
must return to the same host PTY/process.
- [Issue #11265 — paired terminals stall despite live TCP
sockets](https://github.com/stablyai/orca/issues/11265) — transport connectivity
is not delivery liveness; recovery must resume output without an unrelated RPC
kick.
- [Issue #11803 — remote stop respawns tabs from a stale
owner](https://github.com/stablyai/orca/issues/11803) — exact durable retirement
must remain retired after host/client restart.
- [Issue #12241 — paired-host session partitions grow without
bound](https://github.com/stablyai/orca/issues/12241) — paired and scale
journeys must prove bounded state and safe lost-consumer
retirement/compaction liveness.
- [Issue #11574 — same-server re-pairing changes host identity and strands
sessions](https://github.com/stablyai/orca/issues/11574) — stable final-host
identity must survive re-pairing without adopting another host.
- [Issue #9827 — investigate WSL session
restoration](https://github.com/stablyai/orca/issues/9827) and
[issue #11339 — WSL commands are not restored after
restart](https://github.com/stablyai/orca/issues/11339) — the daemon/WSL
journey must run on physical WSL and preserve both shell commands and agent
sessions.
Additional open incident inputs must be triaged into a named journey or ruled
unrelated with explicit evidence and user acceptance:
| Issue | Required question |
| ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| [#11800 — paired null-PTY terminal ghosts](https://github.com/stablyai/orca/issues/11800) | Does host topology advancement retire exact placeholders without inference or a permanent timer reconciler? |
| [#9092 — remote runtime fails after macOS sleep](https://github.com/stablyai/orca/issues/9092) | Does generation-fenced reconnect recover after sleep with bounded resources and no identity change? |
| [#9585 — remote ghost tabs after host restart](https://github.com/stablyai/orca/issues/9585) | Are exit/retirement outcomes durable and idempotent across host restart? |
| [#9562 — remote host session restarts empty](https://github.com/stablyai/orca/issues/9562) | Does the complete boundary plus replay restore terminal state after server restart? |
| [#12568 — no PTY provider after SSH relay recovery/update](https://github.com/stablyai/orca/issues/12568) | Does lazy rediscovery restore the exact host/provider generation? |
| [#10385 — mobile remains falsely connected after RPC stalls](https://github.com/stablyai/orca/issues/10385) | Can E2EE/mobile liveness recover when transport looks connected but RPC is stalled? |
| [#12140 — mobile pairing socket closes immediately](https://github.com/stablyai/orca/issues/12140) | Do capability, identity, and E2EE negotiation fail explicitly and recover across LAN/Tailscale? |
| [#8129 — mobile events lost while disconnected](https://github.com/stablyai/orca/issues/8129) | Are semantic outcomes durable and replayed to a disconnected/backgrounded consumer? |
- [PR #11575 — preserve host identity across same-server
re-pairing](https://github.com/stablyai/orca/pull/11575) — **open**. Direct
identity context for the paired reconnect journey.
- [PR #12768 — restore paired snapshots at the source
grid](https://github.com/stablyai/orca/pull/12768) — **open**. Complementary
host-snapshot authority work with renderer file overlap.
- [PR #9093 — recover remote runtime streams after client
wake](https://github.com/stablyai/orca/pull/9093) — **open**. Provides
generation-cancelled bounded-backoff reconnect context.
- [PR #10235 — self-heal remote subscriptions after server
restart](https://github.com/stablyai/orca/pull/10235) — **open**. Relevant to
E2EE session loss hidden by a live relay transport.
- [PR #11596 — recover falsely connected mobile RPC
sessions](https://github.com/stablyai/orca/pull/11596) — **open and
conflicting**. Broad mobile/E2EE reconnect context; do not absorb its parallel
lifecycle machinery without a full state-machine audit.
- [PR #12036 — stop blocking E2EE handshake on synchronous ACL
writes](https://github.com/stablyai/orca/pull/12036) — **open and conflicting**.
Preserve its metadata-versus-correctness durability distinction and measured
Windows performance constraint during identity lifecycle work.
- [PR #12134 — refresh stale capabilities before
pairing](https://github.com/stablyai/orca/pull/12134) — **open**. Capability
freshness and reauthentication are required mixed-version/pairing context.
- [PR #11804 — make remote stop retirement
durable](https://github.com/stablyai/orca/pull/11804) — **open**. Strong
complementary evidence for exact persisted owner routing and host-side
retirement acknowledgement.
- [PR #12987 — distinguish an absent worktree from an empty tab
list](https://github.com/stablyai/orca/pull/12987) — **open**. Reusable
unknown-versus-authoritative-empty semantics.
- [PR #12751 — preserve tabs when a snapshot reports
none](https://github.com/stablyai/orca/pull/12751) — **open** and a competing
less-exact alternative to #12987; its described multi-client non-convergence
must not become the final model.
- [PR #12339 — stop remote workspace pulls from resurrecting closed
tabs](https://github.com/stablyai/orca/pull/12339) — **open**. Direct topology
reconciliation context for explicit close and stale snapshots.
- [PR #13013 — stop stale snapshot applies from erasing fresh terminal
tabs](https://github.com/stablyai/orca/pull/13013) — **open**. Relevant legacy
snapshot race; decide whether its machinery is deleted by the final authority
cutover rather than layering another permanent reconciler.
- [PR #12903 — retry snapshot tabs whose paths resolve after
apply](https://github.com/stablyai/orca/pull/12903) — **open**. Deferred
hydration is relevant legacy-importer context and may become deletable after
authoritative namespace resolution; do not retain it by default.
## Delivery, backpressure, and lifecycle alternatives
- [Draft PR #12220 — keep SSH alive when a terminal outruns a slow
link](https://github.com/stablyai/orca/pull/12220) — **open draft**. Useful G3
and performance evidence, but its own description has behavioral blockers and
a stalled-consumer wedge. Do not treat it as merge-ready.
- [PR #10744 — durable lost-worker archive and mixed-version SSH
revive](https://github.com/stablyai/orca/pull/10744) — **open** and broad. It
is major architectural context for exact close, outcomes, retirement, and
mixed versions, with substantial overlap. Mine proof and semantics rather
than stacking blindly.
- [PR #11801 — prune stale remote tab
ghosts](https://github.com/stablyai/orca/pull/11801) — **open**. Its snapshot
omission plus timer policy is relevant but may conflict with the rule that
absence/time alone cannot prove destructive cleanup.
## Mandatory issue-to-journey matrix
This table binds customer incidents to the thirteen journeys in
[`goalposts.md`](./goalposts.md#thirteen-required-production-journeys). Closing
an issue or merging a narrow PR does not remove its oracle. Each row must be red
on an unfixed baseline and green on the final candidate, or the user must accept
explicit evidence that the issue is unrelated.
| Open issue(s) | Journey(s) | Mandatory discriminating outcome |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| [#11729](https://github.com/stablyai/orca/issues/11729) | 6, 9, 13 | Rocky Linux reconnect preserves the same workspace, transcript, pane, binding, PID, and environment without PTY growth. |
| [#9819](https://github.com/stablyai/orca/issues/9819), [#9034](https://github.com/stablyai/orca/issues/9034) | 6, 13 | Reconnect cannot accumulate detached PTYs/session slots; explicit close and teardown reclaim the exact process, including lost-response retry. |
| [#11006](https://github.com/stablyai/orca/issues/11006), [#12448](https://github.com/stablyai/orca/issues/12448), [#12699](https://github.com/stablyai/orca/issues/12699) | 2, 6 | Disconnect, source recovery, and wake keep the same live PID/session and never start a duplicate resume without proof of death. |
| [#12447](https://github.com/stablyai/orca/issues/12447), [#11904](https://github.com/stablyai/orca/issues/11904) | 2, 6 | Durable close intent survives lost RPC, app/daemon/relay restart, retries exact retirement, reclaims the process, and never resurrects UI. |
| [#10208](https://github.com/stablyai/orca/issues/10208) | 1, 9 | Worktree switch/restore preserves one exact pane/process and does not duplicate a tab. |
| [#8585](https://github.com/stablyai/orca/issues/8585) | 2, 6, 12 | Cleanup affects only the proven relay generation across reconnect and version change; ID/path reuse cannot kill a successor. |
| [#9138](https://github.com/stablyai/orca/issues/9138), [#11342](https://github.com/stablyai/orca/issues/11342) | 2, 12, 13 | Upgrade/restart converges old daemon generations and their PTYs without invisible sessions, leaks, or destructive guessing. |
| [#8275](https://github.com/stablyai/orca/issues/8275) | 1, 2, 5 | Worktree teardown cannot terminate a sibling namespace or split-pane session. |
| [#10415](https://github.com/stablyai/orca/issues/10415) | 1, 2, 5, 12 | Native Windows handles an unkillable PTY and protocol bump without daemon crash, live-session loss, or cross-session damage. |
| [#9827](https://github.com/stablyai/orca/issues/9827), [#11339](https://github.com/stablyai/orca/issues/11339) | 2, 9 | Physical WSL restart restores the same shell command and agent session under the exact namespace/binding. |
| [#12568](https://github.com/stablyai/orca/issues/12568) | 3, 6, 12 | Relay recovery/update lazily rediscovers the same SSH host/provider and restores only its exact sessions. |
| [#11495](https://github.com/stablyai/orca/issues/11495), [#11574](https://github.com/stablyai/orca/issues/11574) | 4, 8, 10, 12, 13 | Paired restart/re-pair preserves stable host identity and every reported live host PTY at scale across independent updates. |
| [#11265](https://github.com/stablyai/orca/issues/11265), [#9092](https://github.com/stablyai/orca/issues/9092) | 8, 13 | Live-but-stalled transport and sleep/wake automatically resume bounded delivery without an unrelated RPC kick or identity replacement. |
| [#11803](https://github.com/stablyai/orca/issues/11803), [#9585](https://github.com/stablyai/orca/issues/9585), [#11800](https://github.com/stablyai/orca/issues/11800) | 3, 8 | Remote stop/host topology outcome remains durably retired after restart; no stale-owner tab or null-PTY ghost returns. |
| [#9562](https://github.com/stablyai/orca/issues/9562), [#8129](https://github.com/stablyai/orca/issues/8129) | 3, 8, 13 | Complete boundary plus replay restores disconnected/restarted consumers without an empty session or lost semantic outcome. |
| [#12241](https://github.com/stablyai/orca/issues/12241) | 8, 11, 13 | Paired partitions and retained-consumer state remain bounded; lost-consumer retirement safely restores compaction liveness. |
| [#12683](https://github.com/stablyai/orca/issues/12683) | 8, 12 | Stale same-handle reconnect is generation-fenced and automatic recovery remains live across independent peer versions. |
| [#10385](https://github.com/stablyai/orca/issues/10385), [#12140](https://github.com/stablyai/orca/issues/12140) | 8, 10, 12 | False-connected or rejected E2EE/pairing state fails explicitly and reauthenticates without stale identity, capability, or session adoption. |
Journeys 4, 5, 7, 10, and 11 remain mandatory even where no single issue fully
specifies them. This matrix adds incident oracles; it never narrows the journey
definitions.
## Original containment/refactor line
- [PR #12600 — break Activity and terminal React 185
loops](https://github.com/stablyai/orca/pull/12600) — **merged**. It is current
containment/background context, not the whole program and not a release gate.
- [PR #12634 — replace React 185 timers with structural
handoffs](https://github.com/stablyai/orca/pull/12634) — **open**. This is the
direct structural follow-up for deleting #12600's window/timer brakes and must
be reconciled with the broader terminal-session model.
- [PR #13110 — sandboxed preload artifact
guard](https://github.com/stablyai/orca/pull/13110) — **open**, independent of
#13111, green at its head, no approval. Its unresolved major review says raw
source matching can reject safe strings/comments; resolve or supersede that
[finding](https://github.com/stablyai/orca/pull/13110#discussion_r3739646949)
before calling it ready.
## Already merged base context
These were described as open in older notes but were merged when this handoff
was written:
- [PR #12474 — isolate same-path folder workspace PTY
identity](https://github.com/stablyai/orca/pull/12474)
- [PR #12477 — stop a closed remote workspace window reading
Ready](https://github.com/stablyai/orca/pull/12477)
- [PR #12600 — React/terminal loop containment](https://github.com/stablyai/orca/pull/12600)
Refresh `main` and recalculate conflicts; do not follow the stale sequence
`#12882 → #12474 → #12477 → #13111` as written.
## Required GitHub refresh before action
At minimum, re-query:
```bash
gh pr view 13111 --repo stablyai/orca --json state,isDraft,mergeable,mergeStateStatus,reviewDecision,statusCheckRollup,headRefOid,baseRefOid,url
gh pr view 13110 --repo stablyai/orca --json state,isDraft,mergeable,mergeStateStatus,reviewDecision,statusCheckRollup,headRefOid,baseRefOid,url
gh issue view 11729 --repo stablyai/orca --json state,title,updatedAt,url
```
Refresh the complete catalog in one batched request:
```bash
handoff_query_text="$(tr '\n' ' ' < docs/reference/terminal-session-correctness-handoff-2026-08-07/github-overlap-query.graphql)"
gh api graphql -f query="$handoff_query_text"
```
The query includes current PR state/check summaries and unresolved-thread state
for #13110/#13111. Read PR bodies/diffs only for the slice being changed. Do not
close, comment, merge, push, or checkout a PR from the handoff audit without
explicit authorization.
docs/reference/terminal-session-correctness-handoff-2026-08-07/resume-plan.md
+273
View File
@@ -0,0 +1,273 @@
# Resume plan and validation record
This plan preserves the comprehensive objective while allowing independently
safe stacks. It does not require reviving the 814-path construction snapshot.
## First safe commands
Run from the primary worktree before editing:
```bash
pwd
git status --short --branch --untracked-files=all
git rev-parse HEAD origin/main
git rev-list --left-right --count HEAD...origin/main
git branch --list 'nwparker/react185-authority-snapshot'
git show --stat --oneline fddb19f6977
gh pr view 13111 --repo stablyai/orca --json state,isDraft,mergeable,mergeStateStatus,reviewDecision,statusCheckRollup,headRefOid,baseRefOid,url
```
Expected handoff checkpoint before other changes:
- branch `nwparker/sta-3077-reattach-pane-cardinality`;
- HEAD `5369479be2953f45cea9ab5cfcde756dd9660548`;
- snapshot branch and commit present;
- only this handoff folder and its `.gitignore` allow-list are new handoff work.
If the branch, HEAD, or dirty paths differ, inventory and preserve them before
continuing. Never reset, clean, overwrite, or switch away from unknown user work.
## Phase 0 — Reconcile reality before design or code
1. Refresh `origin/main` with `git fetch origin main`—never `git pull`—and
refresh the live state/reviews of every PR in
[`related-open-work.md`](./related-open-work.md) that touches the intended
slice.
2. Recalculate the candidate merge base, categorized LOC, changed-file overlap,
and failing/obsolete tests.
3. Freeze the program accounting baseline before implementation. The default is
`5ed45739e94bdf6460364e033bfcec9b32c0b42a` (the base of #12600). Build an
aggregate carry-in ledger for every program-attributable PR already merged
after it; do not measure only the last PR in a stack.
4. Read the final diff of #13111, #12264, and #12743 with `gh pr view` and
`gh pr diff`, or in disposable isolated worktrees. Never use `gh pr checkout`
or switch branches in the primary worktree. Select or design one coherent
lease/reattach model; do not combine mutually inconsistent quarantine, kill,
and non-kill policies.
5. Reconcile #12882 before overlapping daemon-endpoint integration and #12760
before overlapping relay-generation cleanup. Neither blocks unrelated SSH
proof work by declaration.
6. Treat the preserved snapshot as a local-only mine, not a branch to finish.
Inspect it with `git show fddb19f6977:<path>` or in a disposable isolated
worktree; never switch the primary worktree to it.
Decision output required before implementation:
- exact incident mechanisms being eliminated;
- exact authority/identity semantics retained or changed;
- explicit remote-shell lifecycle and user recovery behavior;
- explicit lost-consumer liveness/compaction behavior;
- PR/stack boundaries and dependency order;
- production modules expected to be deleted; and
- tests that will discriminate the baseline from the candidate; and
- a predeclared performance protocol with fixed workloads, samples,
statistical/noise bounds, deterministic counters, and raw-data locations.
## Phase 1 — Build discriminating journeys first
Before relying on a code change, create or repair oracles that reproduce the
failure on an unfixed baseline.
### STA-3077 Docker SSH oracle
The Docker journey must:
- run a real OpenSSH server with `MaxSessions=1` verified from the server;
- create a known pane and record tab, leaf, binding, relay PTY, and remote PID;
- seed or naturally reproduce duplicate/stale lease state from the field;
- exercise disconnect, client restart, reconnect, and authority/relay restart;
- wait an explicit settle interval after successful reattach;
- recensus visible panes, tabs, exact bindings, persisted leases, relay PTYs,
and actual remote processes/PIDs;
- prove no pane or shell is created, rebound, lost, or silently killed;
- prove explicit unresolved recovery for state that cannot be established; and
- exercise explicit close, lost shutdown response, reconnect retry, and
worktree teardown; prove exact remote PID/session-slot reclamation while an
uncertain sibling survives; and
- fail for the intended reason on the unfixed baseline.
A clean reconnect that passes on both revisions is not this oracle.
### Duplicate-agent oracle family
Cover transient SSH loss, `restoreRequired`, sleeping-agent wake, worktree
switch, and closed-tab restart. Assert process count and transcript/session
ownership, not just pane/store state. No path may start a second `--resume`
process while the first process is live or unknown.
### Daemon and remote oracles
Cover unknown inventory, endpoint handover, daemon restart, relay generation
reuse, client sleep/wake, remote-runtime restart, and stale subscription repair.
A retry limit may end an attempt or surface a failure; it may not itself prove a
session dead or authorize destructive replacement.
## Phase 2 — Reconcile and approve the long-term design
The implementation design must explicitly settle:
- final-host identity versus client routing aliases;
- canonical host-local namespace for worktree, folder, floating, drive, and UNC
forms;
- structural one-active-binding/lease ownership rather than optional metadata
plus repair scans;
- exact operation fencing across every transport;
- explicit detach, close, retirement, orphan recovery, and process-reclamation
operations;
- durable outcome/replay semantics across app, renderer, host, and transport
restarts;
- mixed-version capability and isolated legacy behavior;
- lost-device consumer retirement and compaction liveness;
- one-way migration/cutover; and
- the four-role deletion oracle and strictly net-negative production target.
Reuse existing pane, PTY, incarnation, CAS, and three-valued liveness primitives
where their semantics match. Do not equate client routing IDs with host identity
or namespace without proving the full semantics.
If the chosen design differs from the preserved normative design, write an
explicit mapping for every invariant and every journey, identify what changes,
show equal or stronger safety/liveness, and obtain the user's approval. A
handoff author or implementation agent cannot approve that scope change alone.
## Phase 3 — Implement as a convergent stack
Stacks are allowed for reviewability. Temporary production stopgaps are not the
end state.
A sensible dependency shape is:
1. discriminating journey harnesses and behavior oracles;
2. final shared identity, liveness, and exact-binding primitives;
3. local/daemon/WSL/SSH/relay/paired/remote adapters using those primitives;
4. durable outcome, projection, reset, and recovery lifecycle;
5. one-way migration and capability cutover;
6. deletion of superseded writers, ledgers, quarantine, repair scans, timers
used as verdicts, and duplicate state machines; and
7. full platform, skew, performance, packaging, and independent review proof.
Each stack layer must be safe and tested, but the comprehensive status remains
0/8 until the final integrated candidate satisfies the complete gates. Do not
advertise the authoritative capability or claim program completion mid-stack.
## Phase 4 — Run the complete proof matrix
Use [`goalposts.md`](./goalposts.md) as the checklist. All thirteen production
journeys and every row in the mandatory
[`issue-to-journey matrix`](./related-open-work.md#mandatory-issue-to-journey-matrix)
are required. At minimum the final matrix must include:
- real macOS, Linux floor, Windows, and WSL;
- local, daemon, direct SSH, nested SSH, paired runtime, and remote server;
- one Docker host with `MaxSessions=1` and two simultaneous Docker hosts;
- git worktree, folder, floating, drive, and UNC workspaces;
- old/new peers in both directions at every changed app/daemon, SSH relay,
paired-runtime, remote-server, and mobile/E2EE boundary;
- app, renderer, daemon, relay, and remote-runtime restart;
- crash cuts around durable operations and identity reset;
- unknown/timeout/disconnect/lost-response/concurrent-replacement cases;
- actual remote PID and process accounting; and
- A/B performance and memory results under the predeclared protocol, including
raw samples, confidence intervals, deterministic counters, and leak slopes.
## Phase 5 — Delete, census, rebase, and review
1. Trace every new production module from a real entrypoint.
2. Delete unreachable modules and fixtures in production trees.
3. Delete all superseded legacy writers and reconciliation state machines after
cutover.
4. Rebase onto the actual PR base.
5. Rerun all journeys and static/package checks on the rebased SHA.
6. Report production, tests, docs, CI/runner, generated, and vendored LOC
separately.
7. Require strictly negative aggregate production source net LOC against the
frozen pre-program baseline, including all program-attributable carry-in and
stack layers.
8. Run an independent repository review and the release-readiness checklist.
9. Resolve every P0–P2 finding.
10. Only then prepare the comprehensive PR and ask the user to approve any
deliberate design change.
## Validation status at this handoff
This was a documentation and read-only audit turn. No product test command was
rerun, so this handoff claims no fresh local product-test pass.
Exact validation commands run for this handoff:
```bash
git status --short --branch --untracked-files=all
git rev-parse HEAD origin/main
git rev-list --left-right --count HEAD...origin/main
git merge-base HEAD origin/main
git diff --numstat --no-renames "$(git merge-base HEAD origin/main)"..HEAD
gh pr view 13111 --repo stablyai/orca --json state,isDraft,mergeable,mergeStateStatus,reviewDecision,statusCheckRollup,headRefOid,baseRefOid,url
handoff_query_text="$(tr '\n' ' ' < docs/reference/terminal-session-correctness-handoff-2026-08-07/github-overlap-query.graphql)"
gh api graphql -f query="$handoff_query_text"
pnpm exec oxfmt --check docs/reference/terminal-session-correctness-handoff-2026-08-07/*.md docs/reference/terminal-session-correctness-handoff-2026-08-07/*.graphql
git diff --check
```
Outcomes:
- repository commands exited 0 and produced the branch/SHA/distance recorded in
`README.md`;
- the current-HEAD numstat reproduced `+309` production, `+914` tests/E2E,
`+146` docs, `+43` CI/config, and `+1,412` total net LOC;
- the reproducible GraphQL catalog returned all 65 referenced items and one
unresolved, non-outdated review thread on each of #13110 and #13111;
- all 30 linked issues appear in the mandatory issue-to-journey matrix and the
reusable GraphQL query;
- #13111 was open, non-draft, mergeable/clean, with 47 successful and 5 skipped
checks and no approval decision; and
- formatting and whitespace checks exited 0 after documentation formatting.
Verified in this worktree:
- repository branch, HEAD, merge base, local `origin/main`, branch distance,
and clean pre-documentation status;
- snapshot branch/commit presence and the 814-path preservation claim;
- current source implementation of the narrow #13111 behavior and gaps;
- current categorized #13111 diff census;
- original G0–G7, thirteen journeys, and PR proof contract; and
- live GitHub PR/issue state through batched GraphQL queries.
Live GitHub verification at the time of writing showed:
- #13111: open, non-draft, mergeable/clean, checks successful, no approval, one
unresolved major review thread;
- #13110: open, non-draft, checks successful, no approval, one unresolved major
review thread;
- #12264 and #12743: open competing STA-3077 implementations;
- #12474, #12477, and #12600: merged; and
- the other items in `related-open-work.md`: open unless explicitly labeled
merged or draft.
These states are ephemeral and must be refreshed.
Historical pause receipts from the 60,903-line construction snapshot remain
construction evidence only. They do not prove the current branch, G0–G7, or any
required journey.
## Stop conditions
Stop and return to the user before:
- narrowing or replacing a named goalpost;
- accepting a correctness/performance tradeoff;
- deciding that remote orphan shells may be killed or leaked permanently;
- changing wire semantics without a compatibility design;
- shipping a positive-production-LOC comprehensive stack;
- merging, closing, commenting on, or force-updating external PRs; or
- deleting preserved user work.
## Short takeover prompt
> Continue the comprehensive terminal-session correctness program from
> [`README.md`](./README.md). Preserve the fixed status of **0/8 proven gates
> and 0/13 proven journeys** until every proof in
> [`goalposts.md`](./goalposts.md) passes on one rebased candidate. Reconcile the
> conflicting open work in [`related-open-work.md`](./related-open-work.md),
> build discriminating real SSH/daemon/paired/remote/cross-platform journeys,
> remove root causes and superseded reconciliation, and finish with strictly
> net-negative production LOC and no correctness or performance regression.