Skip to content

Commit 81dd06c

Browse files
committed
fix(#2682): assert the disclosure this head publishes and name the reason gate
The live lane polled data.targetActivation, which is #2693's daemon seam: against this head it would poll to its 90s deadline and fail. It now recovers the fact from the data.warnings sentence and hands it back to iosTargetActivationDisclosure, so a paraphrase still fails and a prior state outside the declared set is refused. The CHECKLIST's local evidence quoted the typed object; it quotes the sentence now, as the simulator rendered it. The decoder's `as IosTargetActivationReason` cast moves into isIosTargetActivationReason beside the declared reasons.
1 parent 5e8ab65 commit 81dd06c

5 files changed

Lines changed: 92 additions & 37 deletions

File tree

‎.device-evidence/CHECKLIST.md‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,13 @@ to activate nothing, so a CI assertion on the disclosure measures `XCUIApplicati
8888
host rather than this feature. Tracked as callstack/agent-device#2696.
8989

9090
Manual evidence stands in for it, and both are reproducible:
91-
- local simulator, first capture after the handoff: `{"reason":"stale_target","priorState":"runningBackground","otherActiveApplicationPid":33878}`
92-
with the shared sentence appended to `warnings`; the following capture reports neither.
91+
- local simulator (`apex-2682-proto`), first capture after the handoff: the shared sentence in
92+
`data.warnings`, printed under the snapshot node count and naming a non-foreground prior state and the
93+
pid probe — `The session app was not foreground when this command
94+
arrived (prior state runningBackground), so the runner activated it before answering (reason
95+
stale_target). Any capture taken earlier in this session described the only app other than the
96+
session app with an active accessibility session (pid 33878), not the session app. Re-capture now
97+
that the session app answers, or drive the other app in its own session.` — and the following capture
98+
carries no such line. On this head that sentence is the whole disclosure: the typed
99+
`data.targetActivation` field beside it is PR2's daemon seam.
93100
- the physical device sequence below, which the coordinator runs.

‎packages/contracts/src/ios-target-activation.test.ts‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,10 @@
11
import assert from 'node:assert/strict';
22
import { test } from 'vitest';
3-
import { iosTargetActivationDisclosure } from './ios-target-activation.ts';
3+
import {
4+
IOS_TARGET_ACTIVATION_REASONS,
5+
isIosTargetActivationReason,
6+
iosTargetActivationDisclosure,
7+
} from './ios-target-activation.ts';
48

59
test('target activation disclosure names the repair and both agent routes', () => {
610
const disclosure = iosTargetActivationDisclosure({
@@ -40,3 +44,16 @@ test('target activation disclosure never invents a pid the runner did not isolat
4044
assert.match(disclosure, /no single other app with an active accessibility session/);
4145
assert.equal(disclosure.includes('pid'), false, disclosure);
4246
});
47+
48+
/**
49+
* The decoder's only gate on the stamped reason, and the live lane's check that a response named a
50+
* reason the runner can actually stamp. Both read this predicate instead of casting, so it is what
51+
* keeps an undeclared reason out of a disclosure.
52+
*/
53+
test('reason predicate accepts exactly the declared reasons', () => {
54+
for (const reason of IOS_TARGET_ACTIVATION_REASONS) {
55+
assert.equal(isIosTargetActivationReason(reason), true, reason);
56+
}
57+
assert.equal(isIosTargetActivationReason('already_foreground'), false);
58+
assert.equal(isIosTargetActivationReason(undefined), false);
59+
});

‎packages/contracts/src/ios-target-activation.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,14 @@ export const IOS_TARGET_ACTIVATION_REASONS = [
2222

2323
export type IosTargetActivationReason = (typeof IOS_TARGET_ACTIVATION_REASONS)[number];
2424

25+
/** Whether `value` is a reason the runner can stamp; the only gate consumers apply to the field. */
26+
export function isIosTargetActivationReason(value: unknown): value is IosTargetActivationReason {
27+
return (
28+
typeof value === 'string' &&
29+
(IOS_TARGET_ACTIVATION_REASONS as readonly string[]).includes(value)
30+
);
31+
}
32+
2533
/**
2634
* States an activation could have been needed for. `runningForeground` is excluded because the
2735
* runner skips `activate()` when the app is already foreground and never stamps a fact there.

‎packages/platform-apple/src/runner/target-activation.ts‎

Lines changed: 4 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
* through: an undisclosed repair is a bug, a fabricated one is worse.
66
*/
77
import {
8-
IOS_TARGET_ACTIVATION_REASONS,
8+
isIosTargetActivationReason,
99
type IosTargetActivation,
1010
type IosTargetActivationPriorState,
1111
type IosTargetActivationReason,
@@ -46,22 +46,16 @@ export function readTargetActivationFact(
4646
if (typeof value !== 'object' || value === null || Array.isArray(value)) return undefined;
4747
const fact: Record<string, unknown> = { ...value };
4848
const reason = fact.reason;
49-
if (
50-
typeof reason !== 'string' ||
51-
!(IOS_TARGET_ACTIVATION_REASONS as readonly string[]).includes(reason)
52-
) {
53-
return undefined;
54-
}
55-
const stampedReason = reason as IosTargetActivationReason;
49+
if (!isIosTargetActivationReason(reason)) return undefined;
5650
const rawPriorState = fact.priorState;
5751
if (typeof rawPriorState !== 'number' || !Number.isInteger(rawPriorState)) return undefined;
5852
const priorState = PRIOR_STATE_BY_RAW_VALUE[rawPriorState];
5953
if (priorState === undefined) {
60-
onUnmappedPriorState?.({ reason: stampedReason, rawPriorState });
54+
onUnmappedPriorState?.({ reason, rawPriorState });
6155
}
6256
const otherActiveApplicationPid = fact.otherActiveApplicationPid;
6357
return {
64-
reason: stampedReason,
58+
reason,
6559
// An unmapped raw value is the one case where the repair stays disclosed and only the state
6660
// degrades: the reason already proves `activate()` ran, and `unknown` is exactly what a raw value
6761
// this table never declared means. Dropping the fact there would trade a vague disclosure for the

‎test/integration/smoke-ios-target-activation.test.ts‎

Lines changed: 53 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,12 @@ import fs from 'node:fs/promises';
33
import path from 'node:path';
44
import test from 'node:test';
55

6-
import { iosTargetActivationDisclosure } from '@agent-device/contracts/ios-target-activation';
6+
import {
7+
IOS_TARGET_ACTIVATION_PRIOR_STATES,
8+
isIosTargetActivationReason,
9+
iosTargetActivationDisclosure,
10+
type IosTargetActivation,
11+
} from '@agent-device/contracts/ios-target-activation';
712
import { runCmd } from '@agent-device/host-kit/command';
813
import {
914
cleanupSession,
@@ -18,6 +23,10 @@ import {
1823
* actually activated the bound app, so this drives the real runner on a real simulator — a mocked
1924
* runner response proves the decoder, not the fact.
2025
*
26+
* What it asserts is the `data.warnings` sentence, because that is everything this branch publishes:
27+
* the typed `data.targetActivation` field is the daemon seam that lands in #2693, and a lane reading
28+
* it here would time out against this head.
29+
*
2130
* MANUAL, ENV-GATED LANE. It is deliberately absent from the `ios.yml` and `replays-manual.yml` test
2231
* lists: on the CI-hosted simulator the runner reads its own target as `.runningForeground` while a
2332
* foreign app is demonstrably on screen, so that host owes no repair and no disclosure
@@ -92,21 +101,7 @@ test(
92101
// Poll instead of sleeping a fixed window: the disclosure must arrive on the command that
93102
// paid for the repair, and a lane that never sees one is the regression this asserts against.
94103
const repaired = await captureUntilDisclosed(context);
95-
const fact = repaired.json!.data.targetActivation;
96-
assert.ok(
97-
typeof fact.reason === 'string' && fact.reason.length > 0,
98-
`disclosure carried no reason: ${JSON.stringify(fact)}`,
99-
);
100-
assert.match(
101-
String(fact.priorState),
102-
/^running(Background|BackgroundSuspended)$|^notRunning$|^unknown$/,
103-
`prior state claims the repair's outcome, not its starting point: ${fact.priorState}`,
104-
);
105-
const warnings: unknown[] = repaired.json!.data.warnings ?? [];
106-
assert.ok(
107-
warnings.includes(iosTargetActivationDisclosure(fact)),
108-
`warnings did not carry the shared disclosure sentence: ${JSON.stringify(warnings)}`,
109-
);
104+
activationFactFrom(repaired.json!.data.warnings ?? []);
110105

111106
// The repair is a fact about one command, not a property of the session: with the app already
112107
// foreground again, the next capture must say nothing.
@@ -115,17 +110,12 @@ test(
115110
'-i',
116111
]);
117112
assert.equal(
118-
settled.json?.data?.targetActivation,
113+
activationFactFrom(settled.json?.data?.warnings ?? []),
119114
undefined,
120115
`second capture re-disclosed a repair it did not perform: ${JSON.stringify(
121116
settled.json?.data?.warnings,
122117
)}`,
123118
);
124-
assert.equal(
125-
String(settled.json?.data?.warning ?? '').includes('was not foreground'),
126-
false,
127-
'second capture re-disclosed a repair it did not perform',
128-
);
129119
} catch (error) {
130120
throw await withRunnerLogEvidence(context, error);
131121
} finally {
@@ -156,15 +146,15 @@ async function withRunnerLogEvidence(context: LiveContext, error: unknown): Prom
156146
return new Error(`${message}\n${note}`, { cause: error });
157147
}
158148

159-
/** Poll `snapshot -i` until the runner reports the repair, or fail with the last response. */
149+
/** Poll `snapshot -i` until the runner discloses the repair, or fail with the last response. */
160150
async function captureUntilDisclosed(context: LiveContext) {
161151
const deadline = Date.now() + HANDOFF_DEADLINE_MS;
162152
let last: Awaited<ReturnType<typeof runStep>> | undefined;
163153
while (Date.now() < deadline) {
164154
last = await runStep(context, 'snapshot after handoff', ['snapshot', '-i'], {
165155
allowFailure: true,
166156
});
167-
if (last.json?.data?.targetActivation !== undefined) return last;
157+
if (activationFactFrom(last.json?.data?.warnings ?? []) !== undefined) return last;
168158
await new Promise((resolve) => setTimeout(resolve, HANDOFF_POLL_MS));
169159
}
170160
assert.fail(
@@ -173,6 +163,45 @@ async function captureUntilDisclosed(context: LiveContext) {
173163
);
174164
}
175165

166+
/**
167+
* Recovers the repair fact from the disclosure sentence in `data.warnings` and hands it back to the
168+
* shared builder, which must reproduce the response's sentence exactly. That is what makes the lane
169+
* assert the disclosure rather than a paraphrase of it, and it keeps the typed object out of the
170+
* picture so the lane runs against a head that publishes only the warning. A prior state outside the
171+
* declared set fails as a fact the runner could not have stamped — the declared set omits
172+
* `runningForeground` because the runner never activates there.
173+
*/
174+
function activationFactFrom(warnings: unknown[]): IosTargetActivation | undefined {
175+
const sentence = warnings.find(
176+
(warning): warning is string =>
177+
typeof warning === 'string' && warning.includes('The session app was not foreground'),
178+
);
179+
if (sentence === undefined) return undefined;
180+
const priorState = IOS_TARGET_ACTIVATION_PRIOR_STATES.find(
181+
(state) => state === /\(prior state ([A-Za-z]+)\)/.exec(sentence)?.[1],
182+
);
183+
const reason = /\(reason ([a-z_]+)\)/.exec(sentence)?.[1];
184+
const pid = /active accessibility session \(pid (\d+)\)/.exec(sentence)?.[1];
185+
assert.ok(
186+
priorState !== undefined && isIosTargetActivationReason(reason),
187+
`disclosure names no declared prior state and reason: ${sentence}`,
188+
);
189+
assert.match(
190+
sentence,
191+
/Re-capture now that the session app answers, or drive the other app in its own session/,
192+
);
193+
const fact: IosTargetActivation = {
194+
reason,
195+
priorState,
196+
...(pid === undefined ? {} : { otherActiveApplicationPid: Number(pid) }),
197+
};
198+
assert.ok(
199+
warnings.includes(iosTargetActivationDisclosure(fact)),
200+
`disclosure is not the shared builder's sentence: ${sentence}`,
201+
);
202+
return fact;
203+
}
204+
176205
async function checksum(filePath: string): Promise<string> {
177206
const crypto = await import('node:crypto');
178207
return crypto

0 commit comments

Comments
 (0)