@@ -1,12 +1,13 @@
 import assert from 'node:assert/strict';
-import { AppError, normalizeError } from '@agent-device/kernel/errors';
+import { AppError, defaultHintForCode, normalizeError } from '@agent-device/kernel/errors';
 
 type ExpectedAppError = {
   code: string;
   message?: RegExp;
   /** Checked against `normalizeError(error).message`, e.g. the stderr excerpt a command failure appends. */
   normalizedMessage?: RegExp;
-  hint?: string | RegExp;
+  /** `null` asserts the failure attached no hint of its own, so normalization falls back to the code default. */
+  hint?: string | RegExp | null;
 };
 
 function assertAppError(error: unknown, expected: ExpectedAppError): true {
@@ -19,7 +20,9 @@ function assertAppError(error: unknown, expected: ExpectedAppError): true {
   if (expected.normalizedMessage) {
     assert.match(normalizeError(error).message, expected.normalizedMessage);
   }
-  if (expected.hint !== undefined) {
+  if (expected.hint === null) {
+    assert.equal(normalizeError(error).hint, defaultHintForCode(error.code));
+  } else if (expected.hint !== undefined) {
     const { hint } = normalizeError(error);
     assert.ok(typeof hint === 'string', `expected a hint on ${error.code}, got ${String(hint)}`);
     if (typeof expected.hint === 'string') assert.equal(hint, expected.hint);
 
@@ -390,6 +390,7 @@ test('simulator install failure surfaces the simctl stderr excerpt with no devic
     {
       code: 'COMMAND_FAILED',
       normalizedMessage: /Failed to install the requested application/,
+      hint: null,
     },
   );
   const [request] = run.mock.calls.find(([call]) => call.args.includes('install'))!;
@@ -424,6 +425,7 @@ test('simulator push failure surfaces the simctl stderr excerpt', async () => {
     {
       code: 'COMMAND_FAILED',
       normalizedMessage: /Invalid device state: Booted/,
+      hint: null,
     },
   );
   const [request] = run.mock.calls.find(([call]) => call.args.includes('push'))!;
 
@@ -157,7 +157,6 @@ async function installAppleApp(
         },
     signal,
     'Apple app install failed',
-    { hint: (result) => devicectlHint(device, result) },
   );
 }
 
@@ -182,7 +181,6 @@ async function uninstallAppleApp(
     signal,
     `Apple app uninstall failed for ${bundleId}`,
     {
-      hint: (result) => devicectlHint(device, result),
       tolerate: (result) =>
         isMissingAppErrorOutput(`${result.stdout}\n${result.stderr}`.toLowerCase()),
     },
@@ -223,39 +221,29 @@ async function pushAppleNotification(
  * The one request path this module uses to run a tolerated Apple tool call: it forces
  * `allowFailure`, then guards the result itself through `requireExecSuccess` so a non-zero
  * exit always throws the same COMMAND_FAILED shape as every other exec call site, with the
- * caller's curated message and, optionally, a devicectl hint. `tolerate` lets a caller accept
- * a specific non-zero result (uninstall's "already missing" case) without losing that guard
- * for every other outcome.
+ * caller's curated message. A devicectl failure gets the same Developer Mode,
+ * developer-disk-image, and pairing hints the other devicectl call sites attach. `tolerate`
+ * lets a caller accept a specific non-zero result (uninstall's "already missing" case)
+ * without losing that guard for every other outcome.
  */
 async function runAppleTool(
   host: PlatformRuntimeHost,
   request: Omit<AppleToolRequest, 'allowFailure'>,
   signal: AbortSignal,
   message: string,
-  options?: Readonly<{
-    hint?: (result: HostCommandResult) => string | undefined;
-    tolerate?: (result: HostCommandResult) => boolean;
-  }>,
+  options?: Readonly<{ tolerate?: (result: HostCommandResult) => boolean }>,
 ): Promise<HostCommandResult> {
   const result = await host.appleTools.run({ ...request, allowFailure: true }, signal);
   if (options?.tolerate?.(result)) return result;
-  return requireExecSuccess(result, message, (failed) => {
-    const hint = options?.hint?.(failed);
-    return { cmd: 'xcrun', args: [request.tool, ...request.args], ...(hint ? { hint } : {}) };
-  });
-}
-
-/**
- * Physical iOS install/uninstall runs through devicectl: a failure gets the same Developer
- * Mode, developer-disk-image, and pairing hints the other devicectl call sites attach.
- * Simulator installs go through simctl, which this resolver does not classify.
- */
-function devicectlHint(
-  device: DeviceInfo,
-  result: Readonly<{ stdout: string; stderr: string }>,
-): string | undefined {
-  if (device.kind === 'simulator') return undefined;
-  return resolveIosDevicectlHint(result.stdout, result.stderr) ?? IOS_DEVICECTL_DEFAULT_HINT;
+  return requireExecSuccess(result, message, (failed) => ({
+    cmd: 'xcrun',
+    args: [request.tool, ...request.args],
+    ...(request.tool === 'devicectl'
+      ? {
+          hint: resolveIosDevicectlHint(failed.stdout, failed.stderr) ?? IOS_DEVICECTL_DEFAULT_HINT,
+        }
+      : {}),
+  }));
 }
 
 function appleDeployFact(device: DeviceInfo): RuntimeOperationFact {