Skip to content

fix(daemon): check the session lease id before a request touches the session - #4944

Open
thymikee wants to merge 14 commits into
0.22from
fix/0.22-authorize-before-session-touch
Open

thymikee wants to merge 14 commits into
0.22from
fix/0.22-authorize-before-session-touch

Conversation

@thymikee

@thymikee thymikee commented Nov 22, 2026 •

Copy link
Copy Markdown
Member

Summary

Check the lease ID before a request reads or changes a leased session (#4913). Journal authorization and lease admission share one typed comparison of canonical lease claims. Use the checked session for recording refresh, inventory, scripts, and test attempts. Lock-exempt doctor, capabilities, and artifacts record their starts after the handler checks the session lease. An open can attach a lease between preparation and that check.

A successor must pass fresh lease admission, heartbeat owner-scope and TTL checks, and any macOS PID check before it can end an expired session. Recheck eligibility after the PID lookup. Admit the successor before teardown and hold its work pass through dispatch. Use the daemon's expiry teardown and remove the second teardown implementation. No wire format change. Older callers must send the lease ID to act on a leased session. Follow-ups are tracked in #4949.

Before / after

  • close without the expired session's lease ID returns LEASE_SESSION_MISMATCH and preserves the session. Previously it ended the session and returned SESSION_NOT_FOUND.
  • devices without a lease ID stays detached from a leased iOS session. Previously its recording could cause COMMAND_FAILED.

Validation

At a1ed32735e, 614 changed and lease-related tests and 948 eager-closure cases passed. Three daemon regressions failed on 2c8fb90 because the journal exposed the refused start after a concurrent open attached a lease. Typecheck, lint, format, and the Fallow audit gate passed. All runnable affected checks passed at the same commit against 0.22 at bdf5096f77.

Closes #4913

@github-actions

github-actions Bot commented Nov 22, 2026 •

Copy link
Copy Markdown
Contributor

Size Report

Metric Base Current Diff
Installed (including dependencies) 6.08 MB 6.08 MB +3.3 kB
Package (unpacked) 6.08 MB 6.08 MB +3.3 kB
Package (download) 1.86 MB 1.86 MB +1.5 kB

Startup median (7 runs, lower is better):

Scenario Base Current Diff
CLI --version 24.4 ms 24.4 ms -0.0 ms
CLI --help 49.5 ms 46.1 ms -3.5 ms

@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: 1 new finding on 262dfd9. The verdict and the full list are in the summary comment.

@thymikee

Copy link
Copy Markdown
Member Author

At 262dfd9 the lease check does not yet hold on every unlocked route, and capabilities still reads the session without one. A client with no lease id can learn the leased session's device and trigger a facts probe on it.

capabilities is lock-exempt and does not ignore the session lease, the same shape as doctor. A no-lease-id request is admitted while its address is empty. An owner can then open a leased session there during the awaits before dispatch, the same window the new beforeDispatch test uses for doctor and events. resolveInventoryCommandDevice then reads the session, and capabilitiesInventoryResponse reads it again, with no assertRequestHoldsSessionLease. The new contract sentence "A command that holds no session lock, such as doctor or events, is checked again when it reads the session" is therefore false for capabilities. The rule the code must satisfy: every sessionExecutionLockExempt command that does not ignore the session lease reads session state only through a lease-checked read. The registry traits enumerate that set today: events, artifacts, capabilities and doctor. Please check the lease at the inventory read, reuse that session in capabilitiesInventoryResponse, and add capabilities to the doctor/events beforeDispatch test.each.

A second independent pass found more gaps of the same kind. Each needs its own fix and a test.

A second independent pass found that a lease refusal can leave a request-start event in a session journal. A request starts while its address is empty, a lease holder publishes a session there, and the request is then refused at the locked check or the unlocked doctor check. Line 310 skips the finish event, but the start is already queued in the address journal. The new session reuses that journal, and the queued append can run after publication (session-event-log.ts). Please defer session-journal start events until the target lease check has succeeded under the session lock, or at the unlocked handler's actual read. Keep events for rejected or sessionless attempts in request diagnostics.

A second independent pass found that distinct store addresses can share one session journal. SessionStore.lookup uses the literal key (session-store.ts), but the journal path uses the non-injective safeSessionName mapping (session-store.ts, session-artifact-paths.ts, session-paths.ts). A no-id request through a colliding address can append start and finish events to the leased session's file at request-execution-scope.ts:304. The events command has the same mismatch at session-observability.ts and can return entries from the shared file. Please give the journal an address-to-path mapping that is unique on supported filesystems, or refuse colliding addresses before any journal access. Permission checks, reads and writes should use the same owner identity.

A second independent pass found that an unlocked recording refresh can change a recording after the session becomes leased. doctor or events begins a health refresh while the existing session is unleased. A concurrent open can attach its lease to that same lifetime without replacing the recording (session-open-state.ts). When the runner observation returns, refreshRecordingHealth checks only the resource identity, so it can invalidate the leased recording or change its runner id (request-recording-health.ts). The later handler lease check cannot undo that. Please serialize the refresh with the ownership check under the session execution lock, or keep unlocked commands out of recording refresh. Any ref reread must be reauthorized before binding.

A second independent pass found that the second session read in capabilities is also unchecked. An unlocked request with an explicit Apple device selector suspends after the first read while its address is empty. The owner opens a leased session on that device before resolution returns. The second read then uses the new session's app identity or surface to decide whether appstate is available, and goes on to facts inspection without a lease check. The first finding's fix covers this if the same authorized session serves device resolution and capability projection.

A second independent pass found that remote script finalization can publish another client's session recording. A detached, unlocked devices request can overlap a recorded action in a leased session at the same address (request-execution-scope.ts:741). The script finalizer looks up the session independently of the authorized ref. If the owner's action count changes between preparation and finalization, the response calls writeRemoteScriptVersion, advances that session's script revision, and carries a script artifact reference (session-script-publication-capability.ts). Please skip script delivery for commands that ignore the session lease. Before readback or publication, verify the current session's lease and lifetime against the request, with an explicit allowance for a session the request itself opened.

A second independent pass found that lease admission can update a session the command is meant to ignore. On a daemon serving both lease backends, a devices request addresses a macos-app session while presenting its own valid iOS simulator lease without a backend label. The session's backend supplies the fallback (request-admission.ts), so devices loses its admission exemption. Lease admission then writes that lease's backend and expiry into the addressed session, although the command holds no session lock and never presented that session's lease id. Commands that ignore the session lease should classify and admit against their own request scope, using the detached session ref for admission and the lease update.

A second independent pass found that suite attempt operations can outlive their lease check. A suite without a matching credential starts direct cleanup on an unleased attempt session. The close yields during runtime admission, and a concurrent open can add a lease to that same lifetime (session-open-state.ts). Close then accepts the same ref and can tear down the leased session (session-close.ts). Direct video start and stop have the same gap: they authorize once, then await recording operations (session-replay-video-owner.ts). The replay adapter also has unchecked runtime-hint reads at lines 202 and 275, and captures against a ref checked only when observation authority is bound at lines 281-291. Please hold the normal attempt session lock across authorization and each direct close, record or capture operation, and route the runtime-hint reads through the authorized attempt lookup at the point of use.

A second independent pass found that the new expiry contract promises more than the code does (remote-device-lease-contracts.md:82). A lease holder sends a bounded batch, replay or bounded step after expiry and before the sweep. The contract says this request ends the session. But request-execution-scope.ts passes refuseTeardown, and lease-lifecycle.ts throws LEASE_NOT_FOUND before consuming the lease. The session stays for the expiry owner, as ADR 0036 already specifies. Please qualify the sentence with the bounded-composite exception and name the lease sweep as the cleanup owner for that case.

Not blocking, and each can be taken or left: requestMayRecordSessionEvents in request-admission.ts turns a throwing call into a boolean with a bare catch that swallows every error, so a non-throwing lease predicate on the owner or a catch limited to LEASE_SESSION_MISMATCH would be tighter; the lookupSession parameter in session-replay-video-owner.ts is called only for its throwing side effect, so a name such as assertSuiteMayActOn would say what it does; and the per-handler lease asserts, for example in session-doctor.ts, are what let capabilities be missed.

Would one lease-checked session read on the scope handed to session handlers be simpler? For example, LockedRequestScope.lookupSession() could return resolveRequestSessionRef(req, sessionStore.lookup(sessionName)), and doctor, capabilities and the events read would call it instead of sessionStore.get. resolveRequestSessionRef stays the single owner, the set that needs the check is whatever reads session state in a lock-exempt handler, and the registry traits already name it. That closes the capabilities gap by construction and removes the separate doctor/events asserts. The replay attempt lookup would stay local because it targets other addresses.

The open inline thread on the request-start event written from a pre-lock lookup still applies (thread). It is lower priority, because the same race shape existed on base. A follow-up issue or a contract-line qualifier is enough for it.

Coverage is red. The PR author attributes it to the session-shutdown.test.ts "omitting that lease id" case. That test calls handleSessionCommands directly and asserts the DEVICE_IN_USE refusal details. This diff touches neither session-shutdown.ts nor that refusal path, so the failure looks unrelated. Not verified here: the failed log was only partly read, so the failing test and threshold are unconfirmed. Not verified here: none of the new tests were run, and the six "fail on base" claims were checked by reading base code, not by execution. The two cancelled Body rules runs are superseded duplicates. There are no conflicts.

Before merge, capabilities needs the lease-checked session read at inventory.ts:465 and line 284, or lock-exempt handlers need one shared checked reader. capabilities also needs to join the beforeDispatch race test. The other findings above should be fixed in the same push, and CI should be green.

@thymikee
thymikee force-pushed the fix/0.22-authorize-before-session-touch branch from 262dfd9 to 7330ab7 Compare November 22, 2026 08:50
@thymikee

Copy link
Copy Markdown
Member Author

Reply to the review of 262dfd9 (#4944 (comment)). Head is now 7330ab7, rebased on 0.22 at 64f963a.

Fixed

  • Unlocked reads, one reader. doctor, events and capabilities read the session through resolveRequestSessionRef; the per-handler asserts are gone. capabilities reuses that one session for device selection and the appstate projection, and is in the beforeDispatch test.each. A second test opens the leased session during device selection.
  • Request-start events. A request writes journal events only after its lease check: under the session lock, or together with the finish event at its last write. The race test now asserts the journal stays empty.
  • Shared journal. Before a journal write, and before the events read, the daemon checks every live session whose address maps to the same session directory. A request without the lease of such a session writes nothing and is refused the read.
  • Recording refresh. Only a request that holds the session lock refreshes the recording.
  • Script delivery. A command that ignores the session lease delivers no script of the session at its address.
  • Admission scope. A command that ignores the session lease is admitted without the addressed session and renews no session lease.
  • Attempt runtime hints. Both reads go through the checked attempt lookup. The video-owner parameter is now assertSuiteMayActOn.
  • Contract. The bounded batch, replay and step exception is stated, with the lease sweep as the cleanup owner.
  • Takeover (from the other review). A request that sends a different active lease ends the expired session for its exact lifetime under its session and device locks, then runs as the new owner. Lock-exempt commands leave expiry to the lease-end owner.

Each fix has a test that fails when the fix is reverted. I ran those reverts.

Deferred

  • Attempt session lock across cleanup, record and capture. The handler chain has no session-lock seam; the device-lock equivalent goes through 11 files. Each direct call is checked at its start. The window that stays open needs another client to open the suite's own attempt address during one of those awaits. I propose a follow-up issue.
  • Injective journal paths. A new address-to-path mapping moves every session artifact. The owner check above closes the lease exposure without it.
  • Bare catch in requestMayRecordSessionEvents. It waits for the non-throwing predicate in fix(daemon): compare every supplied lease label with one typed session lease #4942.
  • Script delivery for commands that do hold the lease. I did not add the lease and lifetime re-check before publication; only the lease-ignoring commands are cut off.

Coverage. I could not read the failing line from that job's log. The only local unit failure at 262dfd9 was the session-shutdown.test.ts case that #4941 fixed on 0.22. Daemon and scripts unit tests pass locally at this head (5754).

@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 7330ab7. The verdict and the full list are in the summary comment.

@thymikee

Copy link
Copy Markdown
Member Author

Final round, head c66cb24 (on 0.22 at 64f963a).

Fixed

  • Takeover race. The successor lease is checked again at the teardown boundary: after the wait for the device lock, under the locks, with no await before the teardown starts. The session ref must still be current too. After the teardown the address is re-resolved and the request goes through the normal admission path. A request without an active different lease ends nothing. New test: the successor lease expires during the lock wait, and nothing is ended.
  • Replacement-device lock for top-level open. Unchanged, and not made worse. On 0.22 an open at an address with an expired session already ran the inline expiry and then opened fresh on the lock plan of the old session; the fresh open takes its target device lock when it resolves the target (session-open.ts). The takeover path enters the same code.
  • macos-app veto. The addressed session decides the app-lease veto in admission again, so a no-id devices at a macos-app session's address is refused as on 0.22. Execution stays detached, and only the session that a request acts through is renewed. New real-daemon test.
  • One expiry teardown. A request that ends an expired session now runs the daemon-owned settle (settleIdleExpiredSession), injected through the router and scope params. expired-session-teardown.ts, the request-scope composition, and the duplicate cleanup-presence guard are deleted.
  • Sentinel: journal guard cost. The cross-address check is gone. The guard is one store lookup per event write.
  • Sentinel: apps. apps and capabilities share one lease-checked session read in the device resolver. apps is in the beforeDispatch test, with a lease of another client so that it reaches dispatch.

Deferred to a follow-up: #4949

  • Attempt-session lock across suite cleanup, record and capture.
  • Journal path aliasing between addresses.
  • Credential re-check before script publication.
  • Double teardown on the holder's inline expiry.

Production code against 0.22 is now +259/−159, down from +344/−155.

@apex-sentinel-staging

This comment has been minimized.

@thymikee

Copy link
Copy Markdown
Member Author

This PR has findings at 2458eeb. The three open items from the earlier review (#4944 (comment)) at 262dfd9 are fixed, and five new issues remain. CI is green: 15 checks, 0 not passing. There are no conflicts. The findings below must be fixed before merge.

A second independent pass found that an expired proxy lease can be torn down by a caller that cannot take over. A named session holds an expired proxy lease. Another client in the same tenant sends open with its own active proxy lease but omits clientId. Preflight skips the fresh-open metadata check while the old session exists (request-admission.ts:244). The successor check compares only labels the caller supplied (lease-registry-scope.ts:263). lease-lifecycle.ts:192 then tears down and retires the old session. Only afterwards does normal admission refuse the open for missing metadata (request-admission.ts:121). Run the fresh-session lease admission rules, without lease mutation, under the locks before the teardown. Reuse the normal admission rules for required metadata and owner scope.

A second independent pass found that the same refusal path leaks the expired owner's lease id. Teardown adds the previous leaseId to the caller's request diagnostics (lease-lifecycle.ts:121). The redactor does not classify leaseId as sensitive (redaction.ts:1). The refusal returns the record locator (request-router.ts:762-777), and the caller can read the record through request-diagnostics-http.ts:137-162. Lease-end diagnostics emitted in a request scope must not carry the lease id. This includes the cleanup failure event at line 127.

A second independent pass found that request-driven expiry can skip application finalization. The holder sends a locked command after the deadline while its iOS recording stop fails. teardownSessionResources throws the aggregated failure (session-teardown.ts:204-210). The new settle callback in daemon-runtime.ts:410 then never reaches application finalization, which releases the Apple runner (lifecycle.ts:476). endLeasedSession still clears the claim and retires the entry. At e8adbb8 the inline path attempted finalization after a resource failure (request-execution-scope.ts:656-689). Keep the daemon-owned callback, and let the lease-expiry caller attempt finalization after a resource failure with the resource failure kept as primary.

A second independent pass found that local inventory no longer notices a restarted recording runner (request-execution-scope.ts:684). Run devices, capabilities, or doctor against a local unleased iOS session with an active runner-backed recording whose runner restarted. At e8adbb8 the refresh marked the recording invalid and the command returned COMMAND_FAILED (lines 722-727 and 759-771). At this head the refresh is skipped for these commands, so the handle stays valid and the request proceeds, although these commands keep the default invalid-recording refusal (daemon-command-registry.ts:95). The recording-health check must still run for unleased sessions: take the session lock around it and re-read the session under the lock. Keep lease-exempt commands detached if that read finds a lease.

A second independent pass found that an expired-owner batch refusal writes journal entries and stamps activity (request-execution-scope.ts:451). A batch sends the matching lease id after the deadline and before the sweep. The outer request queues request.started before cleanup returns LEASE_NOT_FOUND (lease-lifecycle.ts:84-91). The outer batch is not a bounded step (line 433), so line 551 stamps activity before admission completes, and the finalizer can append request.finished (lines 326-337). This contradicts the refused-request guarantee in remote-device-lease-contracts.md:79. Journal and activity writes must depend on successful lease admission for this refusal. Otherwise narrow the contract to the credential mismatches it covers.

Not blocking, and these can be taken or left: remote-device-lease-contracts.md:84 should say that a batch, a replay, or a bounded step that sends the expired lease id is refused with LEASE_NOT_FOUND, and with another active lease with LEASE_SESSION_MISMATCH, because resolveRequestSessionRef refuses that case before the consume callback; and settleExpiredSession at request-execution-scope.ts:170 could be required in RequestRouterDeps, as platformResourceCleanup was, so that a composition that omits it cannot retire an expired session silently (the only production composition at daemon-runtime.ts:331 supplies it).

Of the earlier inline threads, three are fixed at this head and can be resolved: the orphan request.started (#4944 (comment)), the requestMayRecordSessionEvents scan (#4944 (comment), with path aliasing left to #4949), and apps inventory session resolution (#4944 (comment)).

Not verified here: any test run, and a live successor takeover on a real device. Regression validity was judged by reading the 262dfd9 code path for each new test and the router order. The change was treated as daemon-only, since the request-driven expiry teardown now calls the existing settleIdleExpiredSession that the sweep already runs. The side effects of LeaseRegistry.inspectActiveLease and consumeExpiredLease were not inspected beyond their code comments. After these fixes, a rerun of the affected daemon lease tests with the new regressions must pass.

@thymikee
thymikee force-pushed the fix/0.22-authorize-before-session-touch branch from 2458eeb to 6de8d92 Compare November 22, 2026 10:25
@thymikee

Copy link
Copy Markdown
Member Author

Reply to the review of 2458eeb (#4944 (comment)). Head is now 6de8d92, rebased on 0.22 at e8adbb8.

Fixed

  1. Successor that cannot take over. Before the teardown, under the locks, the successor runs the normal lease admission rules of a new session through assertRequestLeaseAdmission in an inspect-only mode: required proxy metadata, owner scope, policy and app-lease rules, with no registry sweep and no renewal. A successor that admission would refuse ends nothing and gets the admission refusal. New real-daemon test: an open with an active proxy lease and no clientId gets INVALID_ARGS, and the expired session stays.
  2. Lease id in request diagnostics. endLeasedSession names the lease id only when the lease-end owner calls it in the daemon scope. The leased_session_ended and leased_session_end_cleanup_failed events of a request carry no lease id.
  3. Finalization after a resource failure. The settle operation is now settleExpiredSession in session-teardown.ts. For a request-driven expiry it still finalizes the application after a resource failure, and the resource failure stays the error thrown. The idle reaper keeps its stop-and-retry behavior. New tests cover both modes.
  4. Recording check for unleased sessions. A command without the session lock takes that lock for the check, reads the session again under it, and stays detached when that read finds a lease. It does not wait when another request holds the lock: that request checks the recording itself, and events or devices must not block behind a long command. New real-daemon test: devices on an unleased session with a restarted runner returns COMMAND_FAILED again.
  5. Expired-owner batch refusal. I took the smaller change and narrowed the contract. It now states that a request refused for the session lease id writes no event and stamps no activity, and that a request that sends the session lease id and is refused later, such as a batch after the deadline, can write its events and stamp activity. Gating on admission would change the 0.22 activity stamp for an ordinary failed admission, which a test pins.

Also taken

  • The contract names both refusals of a batch, replay or bounded step: LEASE_NOT_FOUND with the expired lease id, LEASE_SESSION_MISMATCH with a different active lease.
  • settleExpiredSession is required in RequestRouterDeps.

Each of 1, 3 and 4 fails its test when reverted. Items still deferred are in #4949.

@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: 1 new finding on 6de8d92. The verdict and the full list are in the summary comment.

@thymikee

Copy link
Copy Markdown
Member Author

The findings from the earlier review are fixed at 6de8d92. A second independent pass found four remaining defects in the new successor-lease path. Each one lets a request tear down expired session A and then fail, or lets it open an unleased session.

A second independent pass found that a named session in non-tenant isolation can still end A without an admitted successor. The caller sends open with only the ID of its active lease B and selects an available device. Fresh admission returns undefined because the request names neither tenant nor run (request-admission.ts:142,163). Teardown still runs at lease-lifecycle.ts:191, and the caller can then open an unleased session at that address (session-open-state.ts:73, lease-context.ts:81). Please require fresh admission to return the active successor lease before endLeasedSession runs, and let the existing session lease check refuse the request when it returns undefined.

A second independent pass found that the read-only successor check accepts leases the heartbeat would reject (request-admission.ts:204). A snapshot that presents active proxy lease B without B's clientId, or an open with valid B metadata and leaseTtlMs below the configured minimum, passes because the check compares labels and ignores the lease window. A is torn down at lease-lifecycle.ts:196 before the heartbeat rejects the missing owner scope or out-of-range TTL (lease-registry.ts:234,237). Please reuse the heartbeat's owner-scope and TTL validation in the successor check, before any teardown. Lease renewal can stay in normal admission.

A second independent pass found the same shape for PID-pinned leases (request-execution-scope.ts:540). A host-issued macos-app lease B is still active in the registry, but the PID it pins has exited. A valid macOS open at an address held by expired lease A passes the synchronous successor check and retires A. The request then fails the process check before dispatch (macos-app-lease.ts:308,315). Please run the existing PID check on the admitted successor before teardown, and recheck the locked session and lease eligibility after that asynchronous check.

A second independent pass found that the lease contract is wrong for lock-exempt routes (remote-device-lease-contracts.md:81). It says the command does not refresh the recording. A doctor request with the matching lease ID on an iOS session with a runner-backed recording, with the session lock free, takes the lock and runs refreshRecordingHealth (request-execution-scope.ts:427,692-700). That can invalidate the recording if the runner restarted (request-recording-health.ts:35). Please document that a lock-exempt command may refresh an authorized session's recording when it can take the session lock immediately.

Not blocking, and each can be taken or left: the unreachable expiredSessionSettleNotComposed fallback and the optional settleExpiredSession parameter in createRequestExecutionScope can go, since both callers now pass it; inspectAdmittedLease copies LeaseRegistry.assertLeaseAdmission, so a LeaseRegistry.inspectLeaseAdmission next to it would keep the not-active error in one place; a route-level test for request-driven expiry with a failing resource would pin 'finalize' at daemon-runtime.ts:333 and the no-leaseId diagnostics default; the bare true for daemonScope at the lease-end owner reads better as a named option; and settleExpiredSession now names three different things, so the session-teardown.ts helper could be renamed.

Simplicity question, not a blocker: could finalize-after-resource-failure be a property of every lease-end teardown instead of the request route? Passing (ref) => settleIdleExpiredSession(ref, 'finalize') as createLeaseSessionEnd's teardownSession at daemon-runtime.ts:445, and keeping 'stop' only for the idle sweep at :460, would make the router's settleExpiredSession and the lease-end teardown the same function. A further step is for the successor path to call endSessionsForLease(expiredLeaseId, 'LEASE_EXPIRED') inside its held session and device locks, after consumeExpiredLease. That would delete the daemonScope flag and the router dep, and it overlaps #4949 item 4. Each round has added a mode around request-driven expiry teardown. What has to hold first is that createLeaseSessionEnd's endLiveSessions can run inside a request that already holds the session and device keys. withKeyedLock re-enters a held frame (keyed-lock.ts:158-160), but the closing and in-flight bookkeeping was not read.

None of the open inline threads from other reviewers still applies, so these can be resolved. Orphan request.started is fixed in 7330ab7, because recordStarted now runs only after the session ref resolves: #4944 (comment). Journal path aliasing was deferred to #4949 item 2 and is out of scope here: #4944 (comment). Apps inventory now reads through resolveRequestSessionRef, fixed in c66cb24: #4944 (comment). The recording-refresh skip while the lock is held is deliberate, because the lock holder runs the same refresh, and the base already raced a concurrent holder: #4944 (comment)

The only check not passing is Body rules, which was cancelled rather than failed. It validates the PR description, and this diff changes no route it exercises. The other 16 checks pass. There are no conflicts. Before merge, the four defects above need fixes, with route tests that reach each state described.

Not verified here: no tests were run, and the two new route tests were judged by reading the 2458eeb code paths. The diff stat includes upstream 0.22 commits after the rebase, so only 6de8d92 and the range-diff doc rebases were reviewed as the change. Whether withKeyedLock takes a free key synchronously was not checked; if a window exists, a lock-exempt request waits for the session lock instead of deadlocking. No live device run was made, and the change was treated as daemon-only, as in the previous review.

@thymikee

Copy link
Copy Markdown
Member Author

Addressed all four findings at 536362434a. Review comment

  • Fresh admission must return an active successor before teardown. Read-only admission shares the registry’s heartbeat owner-scope and TTL checks.
  • A macOS successor must pass the PID check before teardown. The daemon checks cancellation, session lifetime, and lease eligibility after the lookup.
  • The contract now covers recording refresh when an authorized lock-exempt command can take the session lock immediately.

129 focused tests and 950 eager-closure cases passed. Four new daemon cases failed at the previous head with just the tests applied. The fifth failed when only the post-PID eligibility check was removed. The final affected rerun reached the 15-minute shared-lock wait limit. The first revision passed the affected gate.

@apex-sentinel-staging

This comment has been minimized.

@thymikee

Copy link
Copy Markdown
Member Author

One problem remains at 5363624 after the earlier round (#4944 (comment)). The lease check itself now looks right, but a lock-exempt request no longer shows up in the session journal while it runs.

On an existing active leased session, start a doctor request with the matching lease ID and let it wait in its local toolchain check at session-doctor.ts:91. Doctor is exempt from the session lock, so the head skips recordStarted at request-execution-scope.ts:460. It queues request.started only later, from recordFinished at line 330. An authorized events request on the same session while doctor is pending flushes the journal and cannot see that start. The base queued request.started at lines 296-304 before admission or dispatch. An owner tailing the journal loses sight of an authorized diagnostic until it finishes, and a stalled diagnostic never appears in the live timeline. The rule: once the admitted session ref is resolved, every request with an already authorized leased ref records its start through the existing guarded recordStarted, lock-exempt requests included. Keep the finalization fallback only for requests that start without an authorized leased ref. Please add a test that holds doctor pending and shows the start in an events read.

Could lease-registry.ts own a shared human-control check with a side-effect-free inspection path for successor admission? The inspectOnly option is supplied only by lease-lifecycle.ts and branches in request-admission.ts:168, but that route still calls assertHumanControlAdmission at line 172. That call expires holds and can renew another device lease through lease-registry.ts:500-507 and 603-630.

The open inline thread on the journal path aliasing is deferred to #4949, so please resolve #4944 (comment). These also no longer apply at this head, so please resolve them: #4944 (comment) (recordStarted now runs only after the session ref resolves), #4944 (comment) (apps inventory reads through resolveRequestSessionRef), and #4944 (comment) (the skip while the session lock is held is deliberate and documented).

The only check that did not pass is Body rules, which was cancelled. It validates the PR description and the diff changes nothing it exercises, so it needs a rerun. The other 16 checks pass. There are no conflicts. Not verified here: the new tests were not run, the vi.spyOn spies on the host-kit modules in http-server-session-lease-touch.test.ts were not run, and no live device run was done. After the journal fix and a rerun of Body rules, nothing else in this change blocks merge.

@thymikee

Copy link
Copy Markdown
Member Author

Fixed at 21133f1331. A request with an authorized leased session now records its start as soon as the session resolves, including lock-exempt doctor. The finish-time fallback applies when no authorized leased session resolved. The daemon regression holds doctor in its toolchain check and reads the start through events. It failed on 5363624. Review comment

A side-effect-free human-control check belongs in LeaseRegistry. It would need a time-aware lookup of holds on the successor's device while regular admission retains the expiry sweep and lease renewal. That adds a path to maintain, so I left it out of this change.

130 focused tests, 950 eager-closure cases, and all runnable affected checks passed on the code commit e3e719d3ab. The final contract wording passed formatting. All four inline threads were answered and resolved, and the cancelled Body rules run passed on rerun. Body rules run

@apex-sentinel-staging

This comment has been minimized.

@thymikee

Copy link
Copy Markdown
Member Author

At 21133f1, the earlier findings (#4944 (comment)) are fixed in part. The journal start now runs only after the session ref resolves, and the inventory read goes through resolveRequestSessionRef. One regression remains, so this is not ready to merge.

The start-at-resolution rule keys on lease presence (existingRef?.session.lease !== undefined at https://github.com/callstack/agent-device/blob/21133f1/packages/daemon/src/server/request-execution-scope.ts#L461), not on whether the request resolved a session it may act through. Start doctor (or devices, session list, any sessionExecutionLockExempt command) on an existing unleased session and let it wait in the toolchain check (https://github.com/callstack/agent-device/blob/21133f1/packages/daemon/src/sessions/handlers/session-doctor.ts#L91). resolveRequestSessionRef returns that ref, because the lease check is a no-op without a lease. Then line 462 skips recordStarted, and the start is queued only by the finish fallback at line 331. A concurrent events read on that session shows no doctor start. The base (db59d00) queued request.started on entry for every command except events, so this is a regression for the common local, unleased case. It also breaks the stated rule that authorized lock-exempt requests appear in the journal while they run. The rule is: record the start for every request whose locked session ref resolved, and keep the finish fallback only when no ref resolved. Test it with both a leased and an unleased session, and change the contract sentence at line 80 from "an existing leased session" to "an existing session".

A second independent pass found a related case. Start a local-mode doctor with valid lease B while open with the same lease is still creating the named session. doctor resolves an empty address at admission, open publishes the session, and doctor's guarded read at session-doctor.ts:69 then accepts B. While the toolchain check is pending, an events request with B cannot see the doctor start, because the only early write is conditioned on the earlier ref. A lock-exempt request should show its live start when its own lease attaches before dispatch. Should the lease-checked session read in the handler trigger the same idempotent start writer when it resolves an authorized leased ref?

A second independent pass also found that the first case holds even when the session stays unleased for the whole request. An authorized doctor on a stable unleased session is missing from the live journal until it finishes. The rule above covers it.

Could the lease-presence special case go? Using existingRef !== undefined (the output of the existing authorization owner) as the only condition for recording at resolution, with the finish fallback only when no ref resolved, would need no lease knowledge in the flag. The first finding would then disappear.

Of the earlier inline threads, the one on recording the start before the session is resolved (#4944 (comment)) and the one on the inventory read (#4944 (comment)) are fixed at this head and can be resolved. The journal path aliasing thread (#4944 (comment)) is deferred to #4949, which is out of scope here. The yield-to-lock-holder thread (#4944 (comment)) is deliberate, because the lock holder checks the recording itself and the contract documents it, so both can be resolved.

No conflicts. The only check that did not pass is Body rules (cancelled), which validates the PR description and title and does not exercise this diff. A passing rerun is reported but was not checked against this head. All other 15 checks pass. Not verified here: the tests were not run, and no test was written to reproduce the first case, which rests on reading the code paths.

Before merge, the journal start must be recorded for every lock-exempt request whose session ref resolved, unleased included as on the base, with a test for a leased and an unleased session.

@thymikee

Copy link
Copy Markdown
Member Author

Fixed at be4465e840. The guarded start now runs when admission resolves a session ref, including an unleased ref. A leased session that first resolves in doctor starts the journal after the handler checks the lease. Both paths use the same idempotent writer. The finish-time fallback applies when no ref resolves through these paths. The contract now covers existing sessions. Review comment

The daemon test reads events while doctor waits on the toolchain check. It covers an existing leased session, an existing unleased session, and a concurrent open with the matching lease. The unleased and concurrent-open cases failed at 21133f1. All 230 focused tests, 950 eager-closure cases, and runnable affected checks passed at this head.

Independent review identified adjacent timing cases outside the requested ones. A ref that first resolves during recording-health preparation, a late inventory read such as capabilities, or a late unleased doctor read can still defer its start until finish.

@apex-sentinel-staging

This comment has been minimized.

@thymikee

Copy link
Copy Markdown
Member Author

At be4465e, the start is now recorded only after the session ref resolves under the lease check, with the finish fallback kept (request-execution-scope.ts:460-468 and :333). The inventory read also goes through resolveRequestSessionRef (inventory.ts:470). Both were open in the earlier review and are fixed. One gap remains: lock-exempt requests that first resolve a session after admission still do not write their live start.

In session-doctor.ts:71 the lease-presence special case is back, now in the handler: if (session?.lease) params.recordResolvedSessionStart?.(). Admit a local doctor at an empty address, so no start is written at admission. Then let an open without a lease publish there before the handler runs, the same window the 'opened before dispatch' test uses. The lease-checked read at line 70 resolves that unleased session, but line 71 skips the writer. While the toolchain check is pending, events (unfiltered address journal read, session-observability.ts:139-149) shows no doctor start. The start appears only at finish (scope.ts:333). The capabilities read at inventory.ts:470 has the same gap for a late-opened session, leased or not. Base db59d00 wrote request.started on entry for every command except events (request-execution-scope.ts:296-303), so this is a regression. It also makes the contract sentence at remote-device-lease-contracts.md:80 false for this route. The rule: every lease-checked session read of a lock-exempt request that resolves a ref calls the idempotent start writer, leased or not. At session-doctor.ts:71, change session?.lease to session. Give inventory.ts:470 the same call, or record once at the scope's seeded read (request-execution-scope.ts:697-709). Add an 'opened unleased before dispatch' row to the existing test.each, opening without a lease from the beforeDispatch hook.

A second independent pass found the same class of gap on three more routes. Each one is covered by the rule above. First, a lock-exempt devices request at an empty address: a concurrent unleased open can publish after the admission lookup (lines 460-468) and before the preparation reads at request-execution-scope.ts:696-708. devices resolves that ref and can stay pending in inventory, but neither the second admission lookup in lease-lifecycle.ts:229 nor the preparation reads notify the journal, so events cannot see the start. The fix is to call the existing start recorder whenever the shared re-resolution returns a ref, after the lease check and before any probe. Second, doctor (session-doctor.ts:71) when open publishes after preparation and before the line 70 lookup: the lease condition skips the writer and events cannot see the running doctor. Calling recordResolvedSessionStart for every session the guarded lookup returns fixes it, since the writer already filters commands and deduplicates. Third, capabilities (inventory.ts:470): the lookup resolves the late session, and events during the facts inspection at line 288 misses the start, also when capabilities presents the lease ID of the session opened in that window. Pass the start recorder to the guarded inventory resolver and call it on a returned ref before device selection or facts inspection. Fourth, lock-exempt artifacts with an active cloud lease (lease.ts:87): an open with that lease can publish after preparation and before the handler reads the session, and the cloud listing at line 559 can stay pending with no start visible to an authorized events read. Pass the recorder through the lease route and call it after resolveSessionLeaseScope succeeds on a present session, before the listing starts. These late-open cases are listed as deferred in the author's latest comment, and #4949 does not track them (its four items are the attempt lock, journal aliases, script publication and double teardown).

Would it be simpler to record the start inside the scope, at the seeded read when seededRef resolves (request-execution-scope.ts:697-709), and have doctor and capabilities use the pinned LockedRequestScope.existingSession instead of a second unlocked reread? #4913 rule 3 allows pinning an authorized reference at admission. That would drop the recordResolvedSessionStart threading through five files and the lease check in doctor, and cover every lock-exempt command in one place. The cost is that doctor would report no session when one opens after dispatch preparation, so the 'opened before dispatch' row would assert that instead of a live start. If the handler reread stays, the minimum is the session condition at both handler reads.

None of the four earlier inline threads needs more work from the author. These threads no longer apply: #4944 (comment) (start now recorded after the lease-checked resolve), #4944 (comment) (inventory read now uses resolveRequestSessionRef), #4944 (comment) (case-insensitive journal path aliasing is deferred to #4949 item 2 and request-admission.ts is unchanged), and #4944 (comment) (yielding to the lock holder is deliberate, since the holder checks the recording itself and the contract documents it). No other threads still apply.

On checks, the only one not passing is Body rules (cancelled). It validates the PR title and body and runs no daemon code, so it is likely unrelated to this change. The other 15 checks pass at this head. Before merge, the live start must be recorded at every lease-checked session read of a lock-exempt request that resolves a ref, leased or not. That means dropping .lease at session-doctor.ts:71, covering the capabilities read at inventory.ts:470 (or recording at the scope's seeded read), and adding the 'opened unleased before dispatch' test row. Not verified here: the tests were not run, and the race and the claim that the new rows fail at 21133f1 rest on reading the code paths. Not verified here: that base db59d00 showed a late-opened unleased doctor start live, which rests on reading request-execution-scope.ts:296-303 and the unfiltered events read, not on a reproduction. Not verified here: the author's report that the focused tests, eager-closure cases and affected checks pass.

@thymikee

Copy link
Copy Markdown
Member Author

Fixed at 9df53115de. I kept the live session reads and gave the request scope one lease-checked resolver that records the start. Admission, preparation (including the read before recording-health refresh), and the doctor, inventory, and artifacts handlers all use it. A concurrent open can publish after the seeded read, so the handler can still resolve the new session. The writer deduplicates starts, keeps the existing events exception, and handles leased and unleased refs. Review comment

The new row opens an unleased session via HTTP after doctor reaches the dispatch hook. It failed on be4465e because events returned the open entries without the pending doctor start. The four doctor cases now pass. The observability forwarding test also checks the resolver. 438 focused tests, 950 eager-closure cases, and all runnable affected checks passed. The PR body passed its checker.

@apex-sentinel-staging

This comment has been minimized.

@thymikee

Copy link
Copy Markdown
Member Author

Commit 9df5311 fixes the problems from the earlier review (#4944 (comment)), but a second independent pass found one high-priority case that remains.

When an open presents a valid successor lease B while the session still holds expired lease A, B can expire during teardown of A. The successor check at https://github.com/callstack/agent-device/blob/9df5311/packages/daemon/src/sessions/lease-lifecycle.ts#L195 only inspects admission. Then https://github.com/callstack/agent-device/blob/9df5311/packages/daemon/src/sessions/lease-lifecycle.ts#L209 awaits teardown of A. An asynchronous resource stop or application finalization at https://github.com/callstack/agent-device/blob/9df5311/packages/daemon/src/sessions/session-teardown.ts#L225 can run past B's deadline when B is close to expiry. A is retired at https://github.com/callstack/agent-device/blob/9df5311/packages/daemon/src/sessions/lease-lifecycle.ts#L145. The first normal admission and heartbeat then fail with LEASE_NOT_FOUND (https://github.com/callstack/agent-device/blob/9df5311/packages/daemon/src/server/request-execution-scope.ts#L541, https://github.com/callstack/agent-device/blob/9df5311/packages/daemon/src/sessions/request-admission.ts#L182). The request has already ended A and never admits B, so the client loses a valid successor lease.

The rule to satisfy: a validated successor must be admitted, with its admitted-work protection held, before any awaited teardown of the incumbent starts. Please commit the fresh-session admission before line 209 and reuse it in the request scope. Expiry handling for the incumbent should stay with the existing teardown owner. A test that opens with a successor lease near its deadline and a teardown that outlasts it would show the fix.

The code needs this change before merge. The only check that did not pass is Body rules, which was cancelled. It validates the PR title and body and runs no daemon code, and the other 15 checks pass at this head. No conflicts. Body rules needs a re-run before merge.

Not verified here: the new tests were not run, and the claim that the new row fails at be4465e rests on reading request-router.ts:352-367 and the be4465e doctor condition. No test drives a late open before the capabilities or artifacts handler read, so their live start rests on reading the wiring (session.ts:34-36, request-handler-chain.ts:174) and the shared resolver. The reported 438 focused tests, 950 eager-closure cases and affected checks were not reproduced.

@thymikee

Copy link
Copy Markdown
Member Author

Fixed at ac63c1dd55. The daemon renews the validated successor and acquires its cancellation-aware work pass before awaiting incumbent teardown. The request reuses that admission and pass at dispatch. The existing path retires the incumbent and consumes its expired lease. Dispatch also checks that the original pass is still retained, so an explicit release invalidates it even if the host reuses the lease ID. Review comment

The deadline regression failed with LEASE_NOT_FOUND at 9df5311. The release-and-reissue case also failed before the pass validity check. Both pass at this head, along with 443 focused tests, 950 eager-closure cases, and all runnable affected checks. The cancelled Body rules run passed on rerun. Body rules run

@apex-sentinel-staging

This comment has been minimized.

…session

A request reached a leased session before the daemon checked its lease id:
it could end an expired session, inspect resources as a bounded step, write
request events, and stamp session activity. `devices` refreshed the recording
of a leased session. `doctor` and `events` read a session that opened after
their admission. A `test` suite recorded and closed a leased session at an
attempt address.

The request scope now resolves the session a request acts through from the
exact ref, first under the session lock, and commands that ignore the session
lease get no session there. Unlocked routes and the test attempt handlers
check the lease id at their read.

Closes #4913
…r the lock

A successor that reached the session lock before the lease sweep was refused
with LEASE_SESSION_MISMATCH. A request that sends another active lease now
ends the expired session for its exact lifetime, under its session and device
locks, and then runs as the new owner. A request with no active lease still
ends nothing.

Lock-exempt commands no longer end an expired session inline: the lease-end
owner ends it under its locks. capabilities checks the lease id once and
reuses that session for both reads. The expired-session teardown moves to a
sibling file to keep the request scope below the line cap, and the unused
RequestExecutionScope.startedAtMs goes.
- doctor, events and capabilities read the session through one lease-checked
  reader; capabilities reuses that session for both reads.
- A request writes its journal events only after its lease check: under the
  session lock, or with its last write. An address that maps to the session
  directory of a leased session neither reads nor writes that journal.
- Only a request that holds the session lock refreshes the recording.
- A command that ignores the session lease delivers no script of the session
  at its address, is admitted in its own scope, and renews no session.
- A test attempt reads its runtime hints through the checked lookup.
…veto

- A request that ends an expired session runs the daemon-owned settle, injected
  through the scope. The second teardown composition and its sibling file go.
- A successor lease is checked again at the teardown boundary, after the wait
  for the device lock and with no await before the teardown starts.
- The addressed session still decides the app-lease veto in admission. Only
  the session a request acts through is renewed.
- apps and capabilities share one lease-checked session read.
- The journal guard checks the session at the request address only; path
  aliasing moves to #4949.
…sion

- A successor runs the lease admission rules of a new session, with no lease
  change, before the teardown. One that admission would refuse ends nothing.
- A request record no longer names the lease id of the session that it ends;
  only the daemon log does.
- A request that ends an expired session still finalizes the application
  after a resource failure, and the resource failure stays the error.
- A command without the session lock checks the recording of a session under
  that lock again, and stays detached when the session holds a lease.
- The contract states which refusals write no journal event.
- The router requires the expired-session settle operation.
@thymikee
thymikee force-pushed the fix/0.22-authorize-before-session-touch branch from ac63c1d to 2c8fb90 Compare November 22, 2026 16:37
@thymikee

Copy link
Copy Markdown
Member Author

Rebased on 0.22 at bdf5096f77 with #4942 and #4953. The new head is 2c8fb90be1. The journal guard and assertRequestPresentsLease now use one canonical comparison. It reports a typed missing-ID refusal or the first mismatched field. Session reply naming continues through the owner from #4953.

Typecheck, lint, format, the Fallow audit gate, 611 changed and lease-related tests, and 948 eager-closure cases passed. The PR body passed validation. The affected run was queued on the shared validation lock at publication.

@apex-sentinel-staging

This comment has been minimized.

@thymikee

Copy link
Copy Markdown
Member Author

The near-deadline successor fix and the earlier blocking finding from 9df5311 are now fixed at 2c8fb90, and one new problem remains. Required evidence is satisfied. The other 16 checks pass, and the one check not passing is still queued; it is a review status that runs no daemon code, so it does not relate to this diff. No conflicts are known.

A second independent pass found that a lock-exempt doctor, capabilities, or artifacts request can journal a start that the handler then refuses. The scope queues request.started for an existing unleased session at request-execution-scope.ts:439. Before the handler reads the session, an admitted open can attach its lease to that same session (session-open-state.ts:53-63). The handler then returns LEASE_SESSION_MISMATCH (session-doctor.ts:78, inventory.ts:480, lease.ts:90). The queued start stays in the now-leased session's journal, and the asynchronous append can finish after the lease attaches (session-event-log.ts:143-158). The lease owner's events read can then show the refused request's start. Please keep the authorization checks on the scope's provisional reads. For lock-exempt commands that recheck the session in their handler, enqueue the start only after the handler's checked lookup succeeds, using the same idempotent writer so authorized requests still appear while their command runs.

Not verified here: the new tests and the author's local suites were not run. The claim that the near-deadline successor test fails at 9df5311 rests on reading lease-registry.ts and the earlier request-scope ordering. Upstream commits from the rebase (#4942, #4953, and the platform-linux and contracts changes) were not reviewed; only the PR's own commits were compared. Merge waits on this fix and the queued check.

@thymikee

Copy link
Copy Markdown
Member Author

Fixed at a1ed32735e. The scope still authorizes its provisional reads. For lock-exempt doctor, capabilities, and artifacts, a successful checked handler lookup is what enables the same idempotent journal writer. Review comment

The real-daemon regression exercises each route. A concurrent HTTP open attaches a lease to the existing session before the handler reads it. The original request is refused with LEASE_SESSION_MISMATCH, and the lease owner's events response has no start from it. All three cases failed at 2c8fb90 and pass at this head.

614 changed and lease-related tests, 948 eager-closure cases, typecheck, lint, format, and the Fallow audit gate passed. The affected run was queued on the shared validation lock at publication.

@apex-sentinel-staging

Copy link
Copy Markdown

Apex Sentinel · ✅ Approve · review of a1ed327

Since the review of 2c8fb90: 0 new · 0 still open · 0 no longer raised

No open findings.

1 finding below minor hidden (user_settings.min_severity).

1 new finding away from what changed since 2c8fb90 not shown. Comment @apex-sentinel-staging review for a full review.

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

💬 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.

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