Skip to content

Commit 127db94

Browse files
committed
refactor(apple-runner): keep the session module under the size line after the fence (#3220)
The shutdown-detach mechanism moves to runner-adoption.ts beside the adoption it hands off to; the session module keeps only the map side of a detach. Pure move: the lifecycle tests that covered the old copy cover the wrapper unchanged.
1 parent 2c28312 commit 127db94

2 files changed

Lines changed: 135 additions & 115 deletions

File tree

‎packages/platform-apple/src/runner/runner-adoption.ts‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ import {
1616
withRunnerCommandId,
1717
} from './runner-contract.ts';
1818
import {
19+
buildDetachedRunnerLease,
1920
buildRunnerLease,
2021
isLeaseRunnerProcessIntact,
2122
readRunnerLeaseForAdoption,
@@ -24,6 +25,7 @@ import {
2425
type RunnerLease,
2526
type RunnerLeaseAdoptionRefusal,
2627
} from './runner-lease.ts';
28+
import { isRunnerProcessAlive } from './runner-disposal.ts';
2729
import {
2830
resolveExpectedRunnerCacheMetadata,
2931
resolveRunnerDerivedPath,
@@ -32,7 +34,10 @@ import {
3234
} from './runner-xctestrun.ts';
3335
import { resolveRunnerCacheKey } from './runner-cache-metadata.ts';
3436
import {
37+
advanceRunnerSessionState,
38+
resolveRunnerDetachDecision,
3539
RunnerCommandAccounting,
40+
type RunnerDetachRefusal,
3641
type RunnerProcessHandle,
3742
type RunnerSession,
3843
} from './runner-session-types.ts';
@@ -58,6 +63,107 @@ export function isIosRunnerDetachEnabled(env: NodeJS.ProcessEnv = process.env):
5863
return parseBooleanLiteral(env.AGENT_DEVICE_IOS_RUNNER_DETACH ?? '') !== false;
5964
}
6065

66+
// Graceful daemon shutdown hands a request-proven runner off to the next daemon instead of paying
67+
// the xcodebuild ramp again: the lease token is rewritten to a detached form (so this daemon's own
68+
// teardown paths no longer classify it as owned), this process gives up its sides of the runner's
69+
// log, and `onDetached` takes the session out of the caller's registry. Once this process exits the
70+
// lease is stale and the adoption path picks it up. Explicit cleanup still works: clean:daemon kills
71+
// by the lease's runnerPid, and the runner's XCTWaiter self-expires after 24h.
72+
//
73+
// Every gate that keeps a session on the kill path is named and reported, because a handoff that
74+
// silently declines is indistinguishable from a rebuild: the handoff lanes
75+
// (`resolveRunnerHandoffTarget`), a session that never served a command, still owes a response, or
76+
// last reported main-thread work still draining (`resolveRunnerDetachDecision`), a missing or
77+
// unwritable lease, and a runner this process cannot prove alive. What stays in the registry is
78+
// torn down by `stopAllIosRunnerSessions`, which the daemon's shutdown runs right after this — so a
79+
// shutdown during a startup tears that runner down rather than handing off one that never reached
80+
// its listener (#2681).
81+
export async function detachRunnerSessionsForShutdown(
82+
sessions: ReadonlyMap<string, RunnerSession>,
83+
onDetached: (deviceId: string, session: RunnerSession) => void,
84+
): Promise<number> {
85+
if (!isIosRunnerDetachEnabled()) return 0;
86+
let detached = 0;
87+
for (const [deviceId, session] of sessions) {
88+
const outcome = detachRunnerSessionForShutdown(session);
89+
if (!outcome.detached) {
90+
emitDiagnostic({
91+
level: 'debug',
92+
phase: 'ios_runner_session_detach_skipped',
93+
data: {
94+
deviceId,
95+
sessionId: session.sessionId,
96+
lane: outcome.lane,
97+
reason: outcome.reason,
98+
// A refused handoff is read from the daemon log, and the two refusals that name a charge look
99+
// identical without this: an exchange still awaited is recovered by its own answer, while an
100+
// abandoned residue waits for terminal evidence for its `commandId` (#2965).
101+
outstandingCharges: session.commandCharges.outstandingChargeCount,
102+
hasAbandonedCharges: session.commandCharges.hasAbandonedCharges,
103+
},
104+
});
105+
continue;
106+
}
107+
detached += 1;
108+
onDetached(deviceId, session);
109+
emitDiagnostic({
110+
level: 'info',
111+
phase: 'ios_runner_session_detached',
112+
data: {
113+
deviceId,
114+
lane: outcome.lane,
115+
sessionId: session.sessionId,
116+
runnerPid: session.child.pid,
117+
port: session.port,
118+
runnerLogPath: session.runnerLogPath,
119+
},
120+
});
121+
}
122+
return detached;
123+
}
124+
125+
type RunnerDetachSkippedReason =
126+
| RunnerHandoffRefusal
127+
| RunnerDetachRefusal
128+
| 'lease_absent'
129+
| 'runner_process_dead'
130+
| 'lease_write_failed';
131+
132+
type RunnerDetachOutcome =
133+
| { detached: true; lane: RunnerHandoffLane }
134+
| { detached: false; lane: RunnerHandoffLane | undefined; reason: RunnerDetachSkippedReason };
135+
136+
function detachRunnerSessionForShutdown(session: RunnerSession): RunnerDetachOutcome {
137+
const target = resolveRunnerHandoffTarget(session.device);
138+
if (!target.handoff) {
139+
return { detached: false, lane: undefined, reason: target.reason };
140+
}
141+
const lane = target.lane;
142+
const decision = resolveRunnerDetachDecision(session);
143+
if (!decision.detach) {
144+
return { detached: false, lane, reason: decision.reason };
145+
}
146+
const lease = session.lease;
147+
if (!lease) {
148+
return { detached: false, lane, reason: 'lease_absent' };
149+
}
150+
if (!isRunnerProcessAlive(session.child.pid)) {
151+
return { detached: false, lane, reason: 'runner_process_dead' };
152+
}
153+
try {
154+
writeRunnerLease(buildDetachedRunnerLease(lease));
155+
} catch {
156+
return { detached: false, lane, reason: 'lease_write_failed' };
157+
}
158+
// Only once the lease says the runner is handed over does this process give up its own sides of
159+
// the runner's log: until that write lands the session is still owned, and an owned session that
160+
// stopped following its runner's output is worse off than one that never handed anything off.
161+
// The runner holds its own descriptor, so this cannot disturb it either way (#2681).
162+
session.endOutputObservation?.();
163+
advanceRunnerSessionState(session, 'stopped');
164+
return { detached: true, lane };
165+
}
166+
61167
type RunnerAdoptionRefusal =
62168
| RunnerHandoffRefusal
63169
| 'lease_absent'

‎packages/platform-apple/src/runner/runner-session.ts‎

Lines changed: 29 additions & 115 deletions
Original file line numberDiff line numberDiff line change
@@ -9,11 +9,6 @@ import {
99
} from './host.ts';
1010
import type { ExecResult } from '@agent-device/host-kit/command';
1111
import { isApplePlatform, type DeviceInfo } from '@agent-device/kernel/device';
12-
import {
13-
resolveRunnerHandoffTarget,
14-
type RunnerHandoffLane,
15-
type RunnerHandoffRefusal,
16-
} from './apple-runner-platform.ts';
1712
import type { RunnerLogicalLeaseContext } from '@agent-device/contracts/runner-lease-context';
1813
import type { AppleRunnerLifecycleOptions } from './runner-provider.ts';
1914
import { flushRunnerLogAppends, getFreePort, resolveRunnerLaunchLogPath } from './runner-io.ts';
@@ -33,14 +28,16 @@ import type { RunnerCommand } from './runner-contract.ts';
3328
import { enrichRunnerStartupFailureWithDeviceStates } from './runner-error-classification.ts';
3429
import { isRunnerReadinessProbeCommand } from './runner-command-traits.ts';
3530
import {
36-
buildDetachedRunnerLease,
3731
buildRunnerLease,
3832
prepareRunnerLeaseForStartup,
3933
runnerOwnerToken,
4034
withRunnerLeaseLock,
4135
writeRunnerLease,
4236
} from './runner-lease.ts';
43-
import { isIosRunnerDetachEnabled, tryAdoptRunnerSessionFromLease } from './runner-adoption.ts';
37+
import {
38+
detachRunnerSessionsForShutdown,
39+
tryAdoptRunnerSessionFromLease,
40+
} from './runner-adoption.ts';
4441
import { buildRunnerSessionXctestrunSuffix } from './runner-artifact-env.ts';
4542
import {
4643
abortRunnerSessionsAndPrepProcesses,
@@ -53,15 +50,12 @@ import {
5350
type RunnerDisposalOptions,
5451
} from './runner-disposal.ts';
5552
import {
56-
advanceRunnerSessionState,
5753
buildRunnerSessionId,
5854
canWorkWithRunnerSession,
5955
isRunnerMainThreadOccupied,
6056
normalizeRunnerStartupTimeoutMs,
61-
resolveRunnerDetachDecision,
6257
resolveRunnerSessionLiveness,
6358
RunnerCommandAccounting,
64-
type RunnerDetachRefusal,
6559
type RunnerSession,
6660
type RunnerSessionLiveness,
6761
type RunnerSessionRegistration,
@@ -796,121 +790,41 @@ export async function abortAllIosRunnerSessions(): Promise<void> {
796790
// The same fence a device teardown raises, for every device at once: the prep sweep the abort
797791
// performs is one-shot, so an in-flight start that would answer it with another build is
798792
// refused before the sweep runs, and stays refused until the sweep settles (#3220).
799-
const { retireAllRunnerStartAdmissions, clearAllRunnerStartAdmissionsAfterTeardown } =
800-
await loadRunnerStartAdmission();
793+
const {
794+
retireAllRunnerStartAdmissions,
795+
clearAllRunnerStartAdmissionsAfterTeardown,
796+
clearRunnerStartAdmissionAfterTeardown,
797+
} = await loadRunnerStartAdmission();
801798
const activeSessions = Array.from(runnerSessions.values());
802799
retireAllRunnerStartAdmissions();
803800
try {
804801
await abortRunnerSessionsAndPrepProcesses(activeSessions);
802+
// Each device's map clear and fence settle run UNDER that device's session lock: a start
803+
// that queued behind the abort wakes to a device that is fully aborted or still fenced,
804+
// never to a half-aborted one it could publish into (#3220 review).
805+
for (const session of activeSessions) {
806+
await withRunnerSessionLock(session.deviceId, async () => {
807+
if (runnerSessions.get(session.deviceId) === session) {
808+
runnerSessions.delete(session.deviceId);
809+
}
810+
clearRunnerStartAdmissionAfterTeardown(session.deviceId);
811+
});
812+
}
805813
} finally {
814+
// The abort settling is the end of the critical section; on the error path the fences
815+
// still leave the registry so a later open on any device is fresh, not fenced forever.
806816
clearAllRunnerStartAdmissionsAfterTeardown();
807817
}
808-
for (const session of activeSessions) {
809-
if (runnerSessions.get(session.deviceId) === session) {
810-
runnerSessions.delete(session.deviceId);
811-
}
812-
}
813818
}
814819

815-
type RunnerDetachSkippedReason =
816-
| RunnerHandoffRefusal
817-
| RunnerDetachRefusal
818-
| 'lease_absent'
819-
| 'runner_process_dead'
820-
| 'lease_write_failed';
821-
822-
// Graceful daemon shutdown hands a request-proven runner off to the next daemon instead of paying
823-
// the xcodebuild ramp again: the lease token is rewritten to a detached form (so this daemon's own
824-
// teardown paths no longer classify it as owned), this process gives up its sides of the runner's
825-
// log, and the session simply leaves the in-memory map. Once this process exits the lease is stale
826-
// and the adoption path picks it up. Explicit cleanup still works: clean:daemon kills by the lease's
827-
// runnerPid, and the runner's XCTWaiter self-expires after 24h.
828-
//
829-
// Every gate that keeps a session on the kill path is named and reported, because a handoff that
830-
// silently declines is indistinguishable from a rebuild: the handoff lanes
831-
// (`resolveRunnerHandoffTarget`), a session that never served a command, still owes a response, or
832-
// last reported main-thread work still draining (`resolveRunnerDetachDecision`), a missing or
833-
// unwritable lease, and a runner this process cannot prove alive. What stays in the map is torn down by `stopAllIosRunnerSessions`, which the daemon's
834-
// shutdown runs right after this — so a shutdown during a startup tears that runner down rather than
835-
// handing off one that never reached its listener (#2681).
820+
// The detach decision itself lives in runner-adoption.ts beside the adoption it hands off to
821+
// (#2681); this is the map side: a detached session leaves the registry and drops its idle
822+
// timer (the detached module gives up the log observation and marks the session stopped).
836823
export async function detachIosRunnerSessionsForShutdown(): Promise<number> {
837-
if (!isIosRunnerDetachEnabled()) return 0;
838-
let detached = 0;
839-
for (const [deviceId, session] of runnerSessions) {
840-
const outcome = detachRunnerSessionForShutdown(deviceId, session);
841-
if (!outcome.detached) {
842-
emitDiagnostic({
843-
level: 'debug',
844-
phase: 'ios_runner_session_detach_skipped',
845-
data: {
846-
deviceId,
847-
sessionId: session.sessionId,
848-
lane: outcome.lane,
849-
reason: outcome.reason,
850-
// A refused handoff is read from the daemon log, and the two refusals that name a charge look
851-
// identical without this: an exchange still awaited is recovered by its own answer, while an
852-
// abandoned residue waits for terminal evidence for its `commandId` (#2965).
853-
outstandingCharges: session.commandCharges.outstandingChargeCount,
854-
hasAbandonedCharges: session.commandCharges.hasAbandonedCharges,
855-
},
856-
});
857-
continue;
858-
}
859-
detached += 1;
860-
emitDiagnostic({
861-
level: 'info',
862-
phase: 'ios_runner_session_detached',
863-
data: {
864-
deviceId,
865-
lane: outcome.lane,
866-
sessionId: session.sessionId,
867-
runnerPid: session.child.pid,
868-
port: session.port,
869-
runnerLogPath: session.runnerLogPath,
870-
},
871-
});
872-
}
873-
return detached;
874-
}
875-
876-
type RunnerDetachOutcome =
877-
| { detached: true; lane: RunnerHandoffLane }
878-
| { detached: false; lane: RunnerHandoffLane | undefined; reason: RunnerDetachSkippedReason };
879-
880-
function detachRunnerSessionForShutdown(
881-
deviceId: string,
882-
session: RunnerSession,
883-
): RunnerDetachOutcome {
884-
const target = resolveRunnerHandoffTarget(session.device);
885-
if (!target.handoff) {
886-
return { detached: false, lane: undefined, reason: target.reason };
887-
}
888-
const lane = target.lane;
889-
const decision = resolveRunnerDetachDecision(session);
890-
if (!decision.detach) {
891-
return { detached: false, lane, reason: decision.reason };
892-
}
893-
const lease = session.lease;
894-
if (!lease) {
895-
return { detached: false, lane, reason: 'lease_absent' };
896-
}
897-
if (!isRunnerProcessAlive(session.child.pid)) {
898-
return { detached: false, lane, reason: 'runner_process_dead' };
899-
}
900-
try {
901-
writeRunnerLease(buildDetachedRunnerLease(lease));
902-
} catch {
903-
return { detached: false, lane, reason: 'lease_write_failed' };
904-
}
905-
// Only once the lease says the runner is handed over does this process give up its own sides of
906-
// the runner's log: until that write lands the session is still owned, and an owned session that
907-
// stopped following its runner's output is worse off than one that never handed anything off.
908-
// The runner holds its own descriptor, so this cannot disturb it either way (#2681).
909-
session.endOutputObservation?.();
910-
runnerSessions.delete(deviceId);
911-
cancelIosRunnerIdleStop(deviceId);
912-
advanceRunnerSessionState(session, 'stopped');
913-
return { detached: true, lane };
824+
return await detachRunnerSessionsForShutdown(runnerSessions, (deviceId) => {
825+
runnerSessions.delete(deviceId);
826+
cancelIosRunnerIdleStop(deviceId);
827+
});
914828
}
915829

916830
export async function stopAllIosRunnerSessions(): Promise<void> {

0 commit comments

Comments
 (0)