Skip to content

fix(remote): give each session its own saved-connection file - #4925

Open
thymikee wants to merge 4 commits into
mainfrom
fix/remote-connection-state-session-identity
Open

thymikee wants to merge 4 commits into
mainfrom
fix/remote-connection-state-session-identity

Conversation

@thymikee

@thymikee thymikee commented Nov 21, 2026 •

Copy link
Copy Markdown
Member

Summary

A saved remote connection was stored in remote-connections/<name>.json, where <name> sanitized the session name. On a case-insensitive filesystem Demo and demo named one file, so one session read and then overwrote another session's saved connection.

A record's contents, not its file name, decide who owns it. A name that is a filename keeps it; any other name uses ~<sha256(session)>.json, exported as connectionSessionIdentity. When the record at the path a name answers for names another session, that session resolves to its next path, reads no state, and writes its own record — the other session's file is left untouched. connection_session_mismatch stays as the last guard and names the refused path and its owner. The .active-session pointer stays a pointer.

The startup-budget test now publishes its phase gate file atomically.

Before / after

# base d6767e0910 — one shared file
write 'Demo'  -> Demo.json
write 'demo'  -> same file, overwritten
read  'Demo'  -> { session: 'demo', runId: 'run-demo' }

# head 1b11290f55
write 'Demo'  -> ~8a2cc067...193.json
write 'demo'  -> demo.json
read  'Demo'  -> { session: 'Demo', runId: 'run-Demo' }

# a legacy Demo.json naming Demo, read as 'demo'
previous head -> COMMAND_FAILED connection_session_mismatch
head          -> null; the write lands at ~<sha256('demo')>.json

Value

  • sessions sharing one state file on a case-insensitive filesystem: 3 at base, 0 at head
  • legacy records trusted by file name alone: 1 at base, 0 at head
  • remote commands a legacy aliased record locked out, --force included: 4 at the previous head, 0 at head

Validation

Validated at head 1b11290: pnpm format, typecheck, lint, check:layering and check:fallow pass; the unit-core vitest project passes (20,583 tests), covering packages/remote and src/cli. Each new test fails at 29fd24a for its own reason. The case fold is made real in tests (hard link where the host volume is case-sensitive), so it holds on Linux. CI owns the device, replay and coverage lanes.

@github-actions

github-actions Bot commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

Size Report

Metric Base Current Diff
Installed (including dependencies) 6.49 MB 6.49 MB +990 B
Package (unpacked) 6.49 MB 6.49 MB +990 B
Package (download) 1.98 MB 1.98 MB +339 B

Startup median (7 runs, lower is better):

Scenario Base Current Diff
CLI --version 21.1 ms 20.5 ms -0.6 ms
CLI --help 46.5 ms 43.5 ms -3.0 ms

@thymikee
thymikee force-pushed the fix/remote-connection-state-session-identity branch 2 times, most recently from a5bc98a to b77b6eb Compare November 21, 2026 19:07
A saved connection was stored under a file whose name sanitized the session, replacing
every character a filename cannot hold. Two names that differ only in case produce the
same name, so on a case-insensitive filesystem both sessions opened one file and one
session read and overwrote another session's record.

A session name that is a filename on its own keeps it. Any other name is stored under
its SHA-256. A record at the old path is used only when its contents name that session,
and a record that names another session is refused with the typed reason
connection_session_mismatch instead of being read, overwritten, or removed.
The active-session pointer is never a session record.
The child polls the gate file and reads it whole. A plain write left a window where the
file existed with no contents yet, so the child reported an empty phase and the test lost
a receipt. Publishing it means the child sees a phase name or no file at all.
…ort audit

connectionSessionIdentity is the published name for the hash a session maps to in its
saved-connection file name. Production derives it inside the module, and the package test
reads it, which the production export audit cannot see.
@thymikee
thymikee force-pushed the fix/remote-connection-state-session-identity branch from b77b6eb to 29fd24a Compare November 21, 2026 19:19
@apex-sentinel-staging

This comment has been minimized.

@apex-sentinel-staging apex-sentinel-staging Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apex Sentinel: 2 new findings on 29fd24a. The verdict and the full list are in the summary comment.

@thymikee

Copy link
Copy Markdown
Member Author

Reviewed 29fd24a. Six problems remain, and the first one breaks the stated invariant that each remote session owns its saved-connection file. All 22 code checks pass, and the only non-passing check is the cancelled 'Body rules' run, which is likely unrelated because the diff changes no workflow or body-rule input. There are no conflicts. The first problem must be fixed before merge.

remote-connection-state.ts:541: After an upgrade on macOS or Windows, a legacy remote-connections/Demo.json that names 'Demo' passes the contents check and stays the live record for 'Demo'. Writes go back to that legacy path, so the record never moves to ~sha256(Demo).json. Session 'demo' matches the plain regex (:533) and resolves to demo.json, which is the same file. Its first read finds parsed.session === 'Demo' and throws connection_session_mismatch (:248). So connect (connection-context.ts:27, before any lease), connect --force, status and disconnect all refuse for 'demo' while 'Demo' stays connected. Two sessions still resolve to one file, which contradicts the '0 sessions sharing one file' result. The failure is closed, with no cross-read or overwrite, but a fresh session is locked out and the error names neither the owner nor a remedy. The rule: every record lives at the path remoteConnectionStatePath derives for the session it names, and no record stays at a sanitized legacy name after any resolve. The smallest fix is inside remoteConnectionStatePath / readRemoteConnectionState: when a hashed-category session's legacy file names that session, rename it to the canonical hashed path and return that path. When a plain path holds a valid record for another session whose canonical path is free, move it there instead of refusing. Keep connection_session_mismatch only for a true conflict, and put the owning session name in its details. Please add a test that writes a legacy Demo.json naming 'Demo', then connects 'demo' and reads 'Demo'. Write the legacy record at demo.json to simulate case-insensitivity, so the test also runs on Linux CI.

A second independent pass found remote-connection-state.ts:533 has the same shape on a case-sensitive filesystem. At base, connect for session a/b keeps its valid record at a_b-c14cddc0.json. After the upgrade, that filename is also the direct path for session a_b-c14cddc0. The old owner still reads and rewrites the file through the legacy branch (:543-547), and the other session fails before it can connect, including with --force. status, disconnect and remote defaults fail too. The rule: when a session's direct filename is occupied by another session's record, the direct-name session gets a canonical path outside the legacy namespace, and the original record stays with the session it names.

A second independent pass found remote-connection-state.ts:268 can let a stale legacy write or removal destroy another session's record. On a case-insensitive filesystem, start with legacy Demo.json holding a valid record for 'Demo'. A connect or lease update for 'Demo' resolves that path and pauses before publishing, or a disconnect pauses before the rm at :294. A second process disconnects 'Demo', and a third connects 'demo' and creates demo.json with its own lease ID. The first process then replaces or deletes that file, because the publisher uses a replacing rename (packages/host-kit/src/internal/atomic-publish.ts:44). The same sequence works with a/b and a_b-c14cddc0 on a case-sensitive filesystem. The rule: state is published only to paths outside the legacy namespace, and ownership checks and changes to a shared legacy pathname are serialized across processes, including retirement or deletion of an old record. A one-time migration (see the question below) removes the shared pathname.

A second independent pass found remote-connection-state.ts:571 can lose a lease record at the legacy pointer filename. The base writer commits a full record before it updates the pointer (d6767e0:packages/remote/src/remote-connection-state.ts:260-262). If it is interrupted between those writes for session .active-session, the full record is still readable and disconnectable at base. Head drops that record from the lookup. On a case-insensitive filesystem with .ACTIVE-SESSION, the exact-name exclusion misses it and head accepts the full record as legacy. A reconnect then writes the record there and replaces it with a pointer at :272. An unrelated connect also replaces the leftover record through its pointer update, so neither route keeps the recorded lease ID. The rule: case-insensitive aliases of the pointer filename are recognized, and a full record found at the pointer path moves to the recorded session's canonical path before a pointer is published.

A second independent pass found remote-connection-state.ts:558 lets distinct config session names share one canonical digest. Two explicit JSON CLI configs can supply session strings containing a lone U+D800 or U+D801 code unit (parsed at packages/command-surface/src/schema/cli-config.ts:90-106). Node's UTF-8 hash input encodes both as U+FFFD. After the first session connects, the second reaches the same file and cannot connect because of the owner check. If both pass the check while the file is absent, their replacing publishes can overwrite each other. The rule: canonical filenames hash a lossless encoding of the exact JavaScript string, such as UTF-16LE, while the eight-character suffix for legacy lookup keeps the old UTF-8 digest.

A second independent pass found remote-connection-state.ts:244 deletes an identifiable record that belongs to another session. On a case-insensitive filesystem, take a legacy Demo.json that still names 'Demo' and has its leaseId, but whose updatedAt is null. Reading 'demo', including through connection status, targets that file, fails shape validation before the stored name is checked, and deletes it through :245 and :663. A write for 'demo' then puts a new record at the same path. A read-only status can therefore destroy the only saved reference to Demo's lease. The rule: a parsed object's string session field is checked before any invalid-state cleanup, and a record naming a different session is kept even when the rest of its payload fails validation.

Simplicity question: would it be the same size or smaller to make the legacy branch a one-time migration that renames a matching legacy file to its canonical path, instead of a permanent second live location? The mismatch refusal would then guard only true conflicts, and the lockout above and the missing recovery hint would go away without new error surface. No smaller design was found for the plain/hashed split itself, since hashing every name would move every existing lowercase record for no gain.

The open inline threads still apply: the legacy path resolving to the same file is raised to the invariant in the first problem above, and the unhelpful mismatch error still holds. Disconnecting the owning session recovers, but nothing tells the caller that.

Not blocking, and each can be taken or left: connectionSessionIdentity is exported (:557) with no consumer, and a production-exports allowlist entry at .fallowrc.json:364 lets it pass the gate, so dropping export and the entry is cleaner (sessionLeaseScope at :447 could also reuse it); the test at remote-connection-state-session-identity.test.ts:88 passes at base on a case-sensitive filesystem, so writing the other variant's record at the lowercase path and asserting read, write and remove outcomes would cover the upgrade route better than the directory listing; the mismatch error at :249 would help callers by carrying the owning session and record path in its details and naming the recovery in its message; and the unrelated atomic gate-file fix in daemon-client-startup-budget.test.ts:191 would be easier to review in its own PR or named as a second change in the summary.

Not verified here: the tests were not run, and the base-failure and lockout claims come from reading base safeStateName and the head code, not from a run on a case-insensitive filesystem. The check:affected run and the 1443-test run cited in the PR body were not repeated, and the cancelled 'Body rules' job log was not inspected.

Before merge, the legacy sanitized-name records need a one-time migration to their canonical path, with an upgrade-route test that covers a legacy 'Demo' record next to a new 'demo' session.

On a case-insensitive filesystem, the record an older build wrote for `Demo` opens when `demo` asks
for its own plain name, so every remote command for `demo` answered `connection_session_mismatch`
and the only way out was deleting the file by hand. Path resolution trusted a name; contents decide
ownership. A session now resolves to the next path its own name answers for when a record there
proves it belongs to another session: the case-variant reads no state, writes its own hashed record,
and the other session's file is left alone. `connection status` and `disconnect --session demo`
answer that demo has no connection instead of failing.

The contents check stays as the last guard for a record that still disagrees after resolution, and it
now names the refused path and how to clear it.
@apex-sentinel-staging

Copy link
Copy Markdown

Apex Sentinel · ✅ Approve · review of 1b11290

Since the review of 29fd24a: 0 new · 1 still open · 1 no longer raised

1 finding(s): 1 minor.

🟡 Minor (1)

Where Finding
packages/remote/src/remote-connection-state.ts:248 Mismatch hint tells the user to run a disconnect that cannot reach the record

Reviewed with this repository's own Sentinel configuration (d6767e0910fc).

💬 Talking to Sentinel

In a finding's thread, reply with:

Command What it does
@apex-sentinel-staging note <context> Adds context; Sentinel re-checks the cited code
@apex-sentinel-staging pivot <why> Says the finding is wrong; Sentinel re-checks the cited code
@apex-sentinel-staging like Marks the finding as useful
@apex-sentinel-staging dislike <why> Marks it as not useful, so it is not raised again

On this conversation, comment @apex-sentinel-staging review to run a full review once again.

@thymikee

Copy link
Copy Markdown
Member Author

Sentinel findings addressed in 1b11290.

Path resolution now answers with contents rather than with a file name: when the plain <name>.json a session resolves to parses and names a different session, the session resolves to its canonical ~<sha256(session)>.json. Both findings share that one rule — after upgrading on macOS or Windows, demo reads no state, writes its own hashed record, and Demo's record is left untouched, so connection status, disconnect and connect --force all work without hand-deleting a file. The connection_session_mismatch guard stays for a record whose contents still disagree after resolution, and now names the refused path and the session that owns it.

@thymikee

Copy link
Copy Markdown
Member Author

At 1b11290, the upgrade-route lockout from the earlier review is fixed, but a session's saved-connection file can still change under it or be overwritten by another session. Checks are green (22 reported, none failing) and there are no conflicts. The first item below must be fixed before merge.

A plain-name session's path still depends on another session's file (remote-connection-state.ts#L556). Take an upgrade on macOS or Windows with a legacy Demo.json naming Demo. connect --session demo sees demo.json (the same file) naming Demo, so it writes its record and lease to ~sha256(demo).json. When Demo later disconnects, removeRemoteConnectionStateFile deletes Demo.json, and demo resolves back to the plain demo.json. Its live record is never read again. The same happens on a case-sensitive volume for a/b (legacy a_b-c14cddc0.json) and a plain session a_b-c14cddc0. Then connection status --session demo reports not connected while its lease is live, disconnect --session demo prints no connection and never releases the lease, and connect --session demo allocates a second lease beside the orphaned record. That record also keeps its remote profile referenced forever. The rule to satisfy: a session's resolved path is a function of its name alone once any record has been placed for it, and a record only lives at the path its own session derives. In remoteConnectionStatePath, migrate a non-canonical file that holds a record naming session S to S's canonical path once (link to the absent target, then unlink the source; leave it and refuse only if the target is occupied). After that, resolve plain names to plain and all others to hashed, with no content sniffing. Please add a test: legacy Demo record, connect demo, disconnect Demo, then status and disconnect for demo must still see its record.

A hashed-name session whose legacy record names it still publishes to the shared legacy pathname (#L568). This was in the earlier review and is unchanged. The publish at writeJsonFile is a replacing rename. Process A updates Demo and resolves Demo.json. Process B disconnects Demo. Process C connects demo, finds demo.json absent and writes its record there. Process A then publishes over demo's record, or A's paused disconnect deletes it. The new test uses this shared file but runs it without a race. One session can overwrite or delete another's record and lease reference. The migration above fixes this too: no write or delete may target a legacy pathname once the record has moved to its owner's canonical path.

Two session names that differ only in a lone surrogate still share one hashed file (#L598). This was in the earlier review and is unchanged. connectionSessionIdentity hashes with the default UTF-8 encoding, which maps every lone surrogate to U+FFFD, so U+D800 and U+D801 names collide. The second session is refused by the owner check, or both publish while the file is absent and overwrite each other. Please hash a lossless encoding of the exact string for canonical names, such as update(session, 'utf16le'). Keep the UTF-8 digest only for the 8-character legacy suffix at lines 606-610. A second independent pass found more routes from the same root cause. A session pair can have separate config files (cli-config.ts#L90-L106), so the second session can create the shared canonical path while the first still has a base-format record. The first then refuses even though its own record is present. A second independent pass also found that the derived client and run scopes (connection.ts#L312-L334) use the same lossy identity. With a leased remote profile and a pinned device key, the U+D801 session can reuse and later release the U+D800 session's proxy lease from a separate saved file (lease-registry.ts#L103-L105). Use the lossless identity for derived scopes too. Keep saved scopes for their owners and do not reuse a pre-upgrade lossy scope for a new session. A second independent pass also found that a foreign record at the shared canonical path can be deleted (#L244). If that record has a string session but fails full validation (for example updatedAt: null), validation fails before the session comparison at line 248. Cleanup then unlinks the other session's record. Compare the parsed string session before full validation. Refuse cleanup for a foreign owner, and act on the same verified file or revision under the mutation guard.

A second independent pass found that an upgraded legacy record stays at the shared filename (#L568). Reads for the legacy owner leave Demo.json in place, writes replace it there, and removal uses the same resolver at lines 274-277 and 295-301. That filename is also eligible as another session's plain path. The a/b case behaves the same in a_b-c14cddc0.json. Move the matching legacy record to its owner's canonical path on first use. Serialize ownership verification and retirement of an aliased legacy name, and publish later writes only to the canonical path.

A second independent pass found that deleting the legacy owner strands the other session's hashed record (#L557). Connect demo while Demo.json holds the old Demo record, then disconnect Demo. With the plain path now empty, status, disconnect and remote defaults for demo no longer find its record and lease ID. A later connect creates demo.json beside the orphan. This is the same switch as the first item, seen from the hashed side. Use one stable canonical location per session. If hashed fallback records are kept, honor an existing one before considering a plain path, and treat any move between paths as an explicit migration.

A second independent pass found that a stale legacy write or unlink can destroy a newly connected session (#L275). Pause a Demo reconnect after it resolves Demo.json and before the publish at line 277. Another process disconnects Demo, and a third connects demo into the free demo.json. The paused rename then replaces demo's record. A Demo disconnect paused after it resolves its unlink argument at line 301 deletes it the same way. An ownership read before the operation leaves both interleavings open. Publish and remove live records only at stable, disjoint canonical paths. Protect the ownership check and the unlink or migration of shared legacy filenames against concurrent claims of the same pathname.

A second independent pass found that an interrupted legacy writer can leave the only lease record at the pointer path (#L611). At base, a writer interrupted after the record publish and before the pointer publish leaves a complete, readable and disconnectable record at .active-session.json (base L255-L262). Head excludes that exact name from legacy lookup, so the named and active lookups lose it. On a case-insensitive volume, .ACTIVE-SESSION bypasses the exclusion and reads the full record. Its next write then publishes the pointer over the record, and the next read removes that pointer as invalid. A write for any unrelated session also replaces either legacy full record. Tell a legacy full record apart from a pointer at the reserved pathname, including case aliases. Move the full record to the canonical path of the session it names before any lookup or pointer replacement.

A second independent pass found that an unreadable legacy record is treated as available and deleted (#L585). On a case-insensitive volume, take a valid Demo.json with a saved lease and a mode that makes reading fail with EACCES for the CLI user, with a writable parent directory. For demo, sessionNamedBy swallows the read error and picks the aliased plain path. The read at line 239 fails again, and invalid-state cleanup unlinks Demo's file. A status command alone triggers this. The a/b record in a_b-c14cddc0.json behaves the same on a case-sensitive volume. Tell an absent legacy path apart from an existing path whose owner could not be read. Keep the latter intact, and either refuse or use a disjoint canonical path without cleanup of the legacy file.

Could this be simpler? Resolve by name only: plain-category names to <name>.json, all others to ~sha256(utf16le session).json. Before resolving, migrate once: if the session's sanitized legacy path or its plain path holds a record naming session S, hard-link it to S's canonical path when that target is absent, then unlink the source. Keep it and refuse with connection_session_mismatch only when the target is occupied. That removes sessionNamedBy from the hot path after migration. It closes the path flip, the publish to the shared name and the pointer-path record, and leaves line 248 as the only ownership guard.

Not blocking, and these can be taken or left: the new hint at #L257 says to run disconnect --session <owner>, but that command resolves the owner's own path (lines 549-568), not the refused file at the requester's hashed path. With the PR's own test record it prints no connection, and with a real record elsewhere it releases that unrelated live connection while the block stays. Lead with removing the named recordPath and drop the disconnect remedy, or say the file is not reachable by any session command. The comment above it (lines 249-252) also says reaching the throw means a race, but a planted record at the hashed path reaches it without one, as the PR's test shows.

For a follow-up issue, not for this PR: the pointer exclusion at remote-connection-state.ts#L611 compares only the exact .active-session.json, so on a case-insensitive volume .ACTIVE-SESSION with an absent canonical file accepts a base-written full record at the pointer file, and a session literally named .active-session loses lookup of a base-interrupted record there. This was in the earlier review and is unchanged. Compare pointer aliases case-insensitively.

The mismatch-hint thread still applies, as the non-blocking note above. The upgrade-route lockout thread no longer applies, because the plain branch at lines 555-559 no longer reaches the throw, and the remaining guard at 253-257 now carries recordPath; it can be resolved.

Not verified here: no tests were run, and the first, second and fourth items are traced from the head code and the CLI handlers, not reproduced on a case-insensitive volume. The race in the second item needs three concurrent processes. No cross-process lock was found in connection.ts, connection-runtime.ts or remote-connection-state.ts, but host-level serialization elsewhere was not searched exhaustively. The PR body's validation runs (unit-core, check:fallow, check:layering) were not repeated.

Before merge, fix the path flip in the first item, which leaves a live lease unreachable after the other session disconnects. Then fix the rest and push.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant