Skip to content

Commit cd552b0

Browse files
committed
fix(device-pin): tell the user to turn the pin off at the layer that set it
A config file or AGENT_DEVICE_DEVICE_PIN is now told to set the pin to false ("devicePin": false, or the variable to 0), which also overrides a lower layer that pins. When --device-pin sits on top of a config or variable that pins as well, the remedy names that layer too, since dropping the flag alone leaves the pin in force. The variable name comes from the recorded provenance instead of being hardcoded.
1 parent eb7d77c commit cd552b0

5 files changed

Lines changed: 115 additions & 23 deletions

File tree

‎packages/command-surface/src/schema/cli-config-device-pin.test.ts‎

Lines changed: 61 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -124,8 +124,56 @@ test('AGENT_DEVICE_DEVICE_PIN turns the pin on for an operator shell', () => {
124124

125125
assert.deepEqual(pin, {
126126
selector: { platform: 'android', serial: 'emulator-5554' },
127-
policySource: { kind: 'env', label: 'environment variable AGENT_DEVICE_DEVICE_PIN' },
127+
policySource: {
128+
kind: 'env',
129+
label: 'environment variable AGENT_DEVICE_DEVICE_PIN',
130+
envName: 'AGENT_DEVICE_DEVICE_PIN',
131+
},
132+
});
133+
});
134+
135+
test('--device-pin over a config that also pins keeps that layer for the remedy', () => {
136+
const { project, env } = projectWithConfig({
137+
platform: 'ios',
138+
device: 'iPad Pro',
139+
devicePin: true,
140+
});
141+
const flagPin = resolveDevicePin(resolvedDefaults(project, env), true);
142+
143+
assert.deepEqual(flagPin, {
144+
selector: { platform: 'ios', device: 'iPad Pro' },
145+
policySource: { kind: 'flag', label: 'the --device-pin flag' },
146+
underlyingPolicySource: {
147+
kind: 'project',
148+
label: `project config file ${path.join(project, 'agent-device.json')}`,
149+
},
150+
});
151+
assert.throws(
152+
() => assertRequestHonorsDevicePin(flagPin!, { flags: { device: 'iPhone 16' } }),
153+
(error: unknown) => {
154+
assert.ok(failsWithReason(DEVICE_PIN_CONFLICT_REASON)(error));
155+
assert.ok(
156+
(error as Error).message.endsWith(
157+
`. Drop --device-pin and set "devicePin": false in project config file ${path.join(project, 'agent-device.json')} to target another device.`,
158+
),
159+
(error as Error).message,
160+
);
161+
return true;
162+
},
163+
);
164+
});
165+
166+
test('AGENT_DEVICE_DEVICE_PIN=0 turns off a pin a config file sets', () => {
167+
const { project, env } = projectWithConfig({
168+
platform: 'ios',
169+
device: 'iPad Pro',
170+
devicePin: true,
128171
});
172+
173+
assert.equal(
174+
resolveDevicePin(resolvedDefaults(project, { ...env, AGENT_DEVICE_DEVICE_PIN: '0' })),
175+
undefined,
176+
);
129177
});
130178

131179
const pin: DevicePin = {
@@ -141,14 +189,14 @@ test('a request selector that contradicts the pin fails with a typed reason nami
141189
assert.equal(error.code, 'INVALID_ARGS');
142190
assert.equal(
143191
error.message,
144-
'device "iPhone 16" conflicts with the device pin from project config file /repo/agent-device.json, which pins platform "ios", device "iPad Pro". Edit or remove "devicePin" in that config to target another device.',
192+
'device "iPhone 16" conflicts with the device pin from project config file /repo/agent-device.json, which pins platform "ios", device "iPad Pro". Set "devicePin": false in that config to target another device.',
145193
);
146194
assert.deepEqual(error.details, {
147195
reason: DEVICE_PIN_CONFLICT_REASON,
148196
pin: { platform: 'ios', device: 'iPad Pro' },
149197
pinSource: 'project config file /repo/agent-device.json',
150198
conflicts: [{ key: 'device', pinned: 'iPad Pro', requested: 'iPhone 16' }],
151-
hint: 'This project pins platform "ios", device "iPad Pro" (project config file /repo/agent-device.json). Drop the conflicting selector to use the pinned device, or change the pin in that config.',
199+
hint: 'This project pins platform "ios", device "iPad Pro" (project config file /repo/agent-device.json). Drop the conflicting selector to use the pinned device, or set "devicePin": false in that config.',
152200
});
153201
return true;
154202
},
@@ -183,21 +231,26 @@ test('the conflict tells the user how to lift the pin for the layer that set it'
183231
const remedies = [
184232
[{ kind: 'flag', label: 'the --device-pin flag' }, 'Drop --device-pin', 'drop --device-pin'],
185233
[
186-
{ kind: 'env', label: 'environment variable AGENT_DEVICE_DEVICE_PIN' },
187-
'Unset AGENT_DEVICE_DEVICE_PIN',
188-
'unset AGENT_DEVICE_DEVICE_PIN',
234+
{
235+
kind: 'env',
236+
label: 'environment variable AGENT_DEVICE_DEVICE_PIN',
237+
envName: 'AGENT_DEVICE_DEVICE_PIN',
238+
},
239+
'Set AGENT_DEVICE_DEVICE_PIN=0',
240+
'set AGENT_DEVICE_DEVICE_PIN=0',
189241
],
190242
[
191243
{ kind: 'explicit', label: 'config file /tmp/pin.json' },
192-
'Edit or remove "devicePin" in that config',
193-
'change the pin in that config',
244+
'Set "devicePin": false in that config',
245+
'set "devicePin": false in that config',
194246
],
195247
] as const;
196248
for (const [policySource, message, hint] of remedies) {
197249
assert.throws(
198250
() =>
199251
assertRequestHonorsDevicePin({ ...pin, policySource }, { flags: { device: 'iPhone 16' } }),
200252
(error: unknown) => {
253+
assert.ok(failsWithReason(DEVICE_PIN_CONFLICT_REASON)(error));
201254
assert.ok(error instanceof Error && 'details' in error);
202255
assert.ok(error.message.endsWith(`. ${message} to target another device.`), error.message);
203256
assert.ok(

‎packages/command-surface/src/schema/cli-config.ts‎

Lines changed: 48 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,8 @@ export type FlagValueSource = {
3333
kind: ConfigFileSource | 'env' | 'flag';
3434
/** Human-readable origin, e.g. `project config file /repo/agent-device.json`. */
3535
label: string;
36+
/** For `env`: the variable that supplied the value, e.g. `AGENT_DEVICE_DEVICE_PIN`. */
37+
envName?: string;
3638
};
3739

3840
export type FlagProvenance = Partial<Record<FlagKey, FlagValueSource>>;
@@ -56,7 +58,11 @@ export function resolveConfigBackedFlagDefaultsWithProvenance(
5658
const envDefaults = readEnvFlagDefaults(env, options.command);
5759
mergeDefinedFlags(flags, envDefaults.flags);
5860
for (const [key, envName] of Object.entries(envDefaults.envNames)) {
59-
provenance[key as FlagKey] = { kind: 'env', label: `environment variable ${envName}` };
61+
provenance[key as FlagKey] = {
62+
kind: 'env',
63+
label: `environment variable ${envName}`,
64+
envName,
65+
};
6066
}
6167
return { flags, provenance };
6268
}
@@ -390,6 +396,11 @@ export type DevicePin = {
390396
selector: DevicePinSelector;
391397
/** Which layer turned the pin on (`devicePin: true` or `--device-pin`). */
392398
policySource: FlagValueSource;
399+
/**
400+
* The config or env layer that also sets `devicePin: true` when `--device-pin` turned the pin
401+
* on. Dropping the flag leaves this layer's pin in force, so the remedy names both.
402+
*/
403+
underlyingPolicySource?: FlagValueSource;
393404
};
394405

395406
const DEVICE_PIN_FLAG_SOURCE: FlagValueSource = { kind: 'flag', label: 'the --device-pin flag' };
@@ -421,7 +432,13 @@ export function resolveDevicePin(
421432
{ reason: DEVICE_PIN_WITHOUT_SELECTOR_REASON, pinSource: policySource.label },
422433
);
423434
}
424-
return { selector, policySource };
435+
const underlyingPolicySource =
436+
explicitDevicePin === true && defaults.flags.devicePin === true
437+
? defaults.provenance.devicePin
438+
: undefined;
439+
return underlyingPolicySource
440+
? { selector, policySource, underlyingPolicySource }
441+
: { selector, policySource };
425442
}
426443

427444
type DevicePinRequest = {
@@ -453,7 +470,7 @@ export function assertRequestHonorsDevicePin(pin: DevicePin, request: DevicePinR
453470
const first = conflicts[0]!;
454471
const pinnedDescription = describeSelector(pin.selector);
455472
const where = first.step === undefined ? '' : `Batch step ${first.step}: `;
456-
const remedy = describePinRemedy(pin.policySource);
473+
const remedy = describePinRemedy(pin.policySource, pin.underlyingPolicySource);
457474
const message =
458475
`${where}${first.key} ${JSON.stringify(first.requested)} conflicts with the device pin ` +
459476
`from ${pin.policySource.label}, which pins ${pinnedDescription}. ` +
@@ -467,20 +484,39 @@ export function assertRequestHonorsDevicePin(pin: DevicePin, request: DevicePinR
467484
});
468485
}
469486

470-
/** How to lift the pin, phrased for the layer that turned it on: a config file, a variable or the flag. */
471-
function describePinRemedy(source: FlagValueSource): { message: string; hint: string } {
472-
if (source.kind === 'flag') {
487+
/**
488+
* How to lift the pin, phrased for the layer that turned it on. A config file or variable is told
489+
* to turn it off rather than to drop it, because a lower layer may set `devicePin: true` too and
490+
* would keep the pin in force. `--device-pin` has no false form, so under a lower pinning layer the
491+
* remedy names that layer as well.
492+
*/
493+
function describePinRemedy(
494+
source: FlagValueSource,
495+
underlying?: FlagValueSource,
496+
): { message: string; hint: string } {
497+
if (source.kind !== 'flag') return describeLayerRemedy(source, 'that config');
498+
if (!underlying || underlying.kind === 'flag') {
473499
return { message: 'Drop --device-pin', hint: 'drop --device-pin' };
474500
}
501+
const lower = describeLayerRemedy(underlying, underlying.label);
502+
return {
503+
message: `Drop --device-pin and ${lower.hint}`,
504+
hint: `drop --device-pin and ${lower.hint}`,
505+
};
506+
}
507+
508+
/** Turns the pin off at a config file or variable; `where` names the config file. */
509+
function describeLayerRemedy(
510+
source: FlagValueSource,
511+
where: string,
512+
): { message: string; hint: string } {
475513
if (source.kind === 'env') {
476-
return {
477-
message: 'Unset AGENT_DEVICE_DEVICE_PIN',
478-
hint: 'unset AGENT_DEVICE_DEVICE_PIN',
479-
};
514+
const name = source.envName ?? 'AGENT_DEVICE_DEVICE_PIN';
515+
return { message: `Set ${name}=0`, hint: `set ${name}=0` };
480516
}
481517
return {
482-
message: 'Edit or remove "devicePin" in that config',
483-
hint: 'change the pin in that config',
518+
message: `Set "devicePin": false in ${where}`,
519+
hint: `set "devicePin": false in ${where}`,
484520
};
485521
}
486522

‎src/__tests__/cli-device-pin.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ test('a CLI batch step that names another device fails before any daemon request
4343
const error = readJsonError(result.stdout);
4444
assert.equal(
4545
error.message,
46-
`Batch step 1: device "iPhone 16" conflicts with the device pin from project config file ${configPath}, which pins platform "ios", device "iPad Pro". Edit or remove "devicePin" in that config to target another device.`,
46+
`Batch step 1: device "iPhone 16" conflicts with the device pin from project config file ${configPath}, which pins platform "ios", device "iPad Pro". Set "devicePin": false in that config to target another device.`,
4747
);
4848
assert.equal(error.details.reason, 'device_pin_conflict');
4949
assert.deepEqual(error.details.conflicts, [

‎src/mcp/tool-input-config.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ test('a nested batch step naming another device fails before any daemon request'
6767
const error = result.structuredContent as Record<string, unknown>;
6868
assert.equal(
6969
error.message,
70-
`Batch step 1: device "iPhone 16" conflicts with the device pin from config file ${configPath}, which pins platform "ios", device "iPad Pro". Edit or remove "devicePin" in that config to target another device.`,
70+
`Batch step 1: device "iPhone 16" conflicts with the device pin from config file ${configPath}, which pins platform "ios", device "iPad Pro". Set "devicePin": false in that config to target another device.`,
7171
);
7272
assert.equal((error.details as { reason?: string }).reason, 'device_pin_conflict');
7373
});

‎website/docs/docs/configuration.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -150,7 +150,10 @@ The pin only constrains the keys it sets: here `--udid` still narrows down to on
150150
selector that repeats the pinned value is accepted. A `devicePin` with no `platform`, `device`,
151151
`udid`, or `serial` beside it fails with `details.reason: "device_pin_without_selector"`.
152152
`AGENT_DEVICE_DEVICE_PIN=1` opts in from the environment when the selector lives in the user
153-
config, and `--device-pin` opts in for one CLI invocation.
153+
config, and `--device-pin` opts in for one CLI invocation. To lift a pin, turn it off at the layer
154+
that set it: `"devicePin": false` in a config file or `AGENT_DEVICE_DEVICE_PIN=0` overrides a
155+
`devicePin: true` in a lower layer, while dropping `--device-pin` leaves any config or variable pin
156+
in force. The conflict message names the layer to change.
154157

155158
Pinning is separate from [session locks](/docs/sessions#lock-a-named-session-to-a-device): a
156159
lock protects a named session once it is bound; a pin scopes a whole project before any session

0 commit comments

Comments
 (0)