feat(ios-qa): forward GSTACK_IOS_LAUNCH_ENV to devicectl launches (#1796)

Reimplements only the launch-environment half of #1796 (credit
Bmathews721; the session-cache half is superseded by #3132's design and
had state-root and symlink-write problems). devicectl.ts parses
GSTACK_IOS_LAUNCH_ENV as a JSON object of string to string;
launchEnvArgs() returns the --environment-variables argv (empty when
unset or {}) and launchApp passes it before the bundle id. Invalid JSON, a
non-object, a non-string value, a bad name or a key in the debug bridge's
reserved GSTACK_ namespace refuses before any launch with the new result
code IOS_LAUNCH_ENV_INVALID (the detail names keys and types, never
values). launchEnvArgs is exported for the forced-relaunch path in
tunnel-bootstrap.ts.

Adds the result-code row (bin/gstack-doctor-components.sh regenerated by
gen:skill-docs), a troubleshooting entry under its exact text, the
pregate-no-lane entry's explain note, and the how-to section with an
example. New test fails on 47d639a (module load: no parseLaunchEnv).

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

Author: garrytan

bin/gstack-doctor-components.sh

@@ -196,6 +196,7 @@ gstack_result_anchor() {
     BROWSE_TAB_UNRECOVERABLE) printf '%s' 'browse-tab-unrecoverable' ;;
     BUN_VERSION_UNREADABLE) printf '%s' 'bun-version-unreadable' ;;
     BASH_UNAVAILABLE) printf '%s' 'bash-unavailable' ;;
+    IOS_LAUNCH_ENV_INVALID) printf '%s' 'ios-launch-env-invalid' ;;
     *) return 1 ;;
   esac
 }

docs/howto-ios-testing-with-gstack.md

@@ -128,8 +128,18 @@ Set these env vars to target a specific device or bundle:
 GSTACK_IOS_TARGET_UDID=248C3A58-B843-5BDB-8F5D-89ADB7D7BF6A
 GSTACK_IOS_TARGET_BUNDLE_ID=com.yourorg.yourapp
 GSTACK_IOS_DAEMON_PORT=9099       # loopback listener port; default 9099
+GSTACK_IOS_LAUNCH_ENV='{"DEBUG_BRIDGE":"1"}'   # optional: env for the app when the daemon launches it
 ```
 
+`GSTACK_IOS_LAUNCH_ENV` is for apps whose debug bridge (or anything else) is
+gated on an environment variable. It is a JSON object of string to string, and
+the daemon passes it to `xcrun devicectl device process launch
+--environment-variables` on every launch it performs, including the one forced
+relaunch below. It only takes effect when the daemon launches the app; an app
+that is already running keeps the environment it started with. Invalid JSON, a
+non-string value, or a `GSTACK_` key (reserved for the debug bridge) refuses the
+launch with `IOS_LAUNCH_ENV_INVALID` instead of starting the app without it.
+
 If `GSTACK_IOS_TARGET_UDID` is unset, the daemon picks the best paired,
 available iPhone or iPad, preferring a wired device. When two devices tie (an
 iPhone and an iPad both on USB), it refuses to guess: the bootstrap error lists
@@ -230,6 +240,7 @@ Before you ship to TestFlight or the App Store, run `/ios-clean`. It removes the
 | `Developer Mode` toggle missing from Settings → Privacy | Connect the device to Xcode → Window → Devices and Simulators once, or try any `devicectl device install` against it. iOS will surface the toggle after the first attempt. |
 | `xcrun devicectl device copy from` returns ERROR 7000 | The source path is wrong — boot token lives at `tmp/gstack-ios-qa.token` inside the app's data container (NSTemporaryDirectory), not at the path's root. |
 | Bootstrap fails with `multiple_devices` | More than one iPhone/iPad is connected. Run the printed `export GSTACK_IOS_TARGET_UDID=<udid>` and restart the daemon. |
+| Launch refused with `(IOS_LAUNCH_ENV_INVALID)` | `GSTACK_IOS_LAUNCH_ENV` is not a JSON object of string to string, or sets a `GSTACK_` key. Fix or unset it and restart the daemon; see [troubleshooting](troubleshooting.md#ios-launch-env-invalid). |
 | `boot_token_unavailable ... could not write tmp/gstack-ios-qa.token` | The app could not write its boot-token file. Fix the app's `tmp/` directory and relaunch the app. |
 | A SwiftUI `DragGesture` or `Canvas` ignores taps and swipes on iOS 26 | Synthesized in-process touches do not reach SwiftUI gesture recognizers on iOS 26, and `/swipe` only scrolls a `UIScrollView`. See "Known limits" in the `/ios-qa` skill for the input-routing workaround. |
 | `/healthz` returns 200 but `/tap` returns ok:true with no UI change | The phone is paired but the StateServer port may have changed across launches. Re-resolve the CoreDevice IPv6 (`dscacheutil -q host -a name '<DeviceName>.coredevice.local'`). |

docs/troubleshooting.md

@@ -2698,7 +2698,12 @@ string literals, the `bin/<name>` → `test/<name>*.test.ts` convention or a
 
 **Fix.** Add a test that names the file, or declare its lane (an explicit `[]`
 for files with no behaviour, such as docs) in `.gstack/pregate.json`. `--explain`
-prints every mapping and why.
+prints every mapping and why. For a file with no lane it also prints the import
+specifiers in test files that resolved to no repo file (for example a
+`tsconfig.json` `paths` alias such as `@/lib/x` whose target is missing) and any
+`extends` hop that was not followed (only relative `extends`, at most 4 hops). If
+a test does cover the file, declare it under `dependencies`; if the resolver
+should have found it, report the specifier as a resolver gap.
 
 <a id="pregate-lane-failed"></a>
 ### `PREGATE_LANE_FAILED`
@@ -3077,3 +3082,26 @@ writes that state; it comes from a hand edit or an older runner.
 
 **Fix.** Answer the gate with `gstack-autoplan answer` until no approval is
 pending, and `revise --incorporates` or `--withdraw` each pending amendment.
+
+<a id="ios-launch-env-invalid"></a>
+### `ios-qa launch: GSTACK_IOS_LAUNCH_ENV ... so the app was not launched (<detail>); fix: ... (IOS_LAUNCH_ENV_INVALID)`
+
+**Meaning.** `gstack-ios-qa-daemon` forwards `GSTACK_IOS_LAUNCH_ENV` to
+`xcrun devicectl device process launch --environment-variables` whenever it
+launches the app under test. The value must be a JSON object whose keys are
+environment variable names and whose values are strings, and it may not set a
+`GSTACK_` variable (that namespace belongs to the debug bridge). Anything else
+(invalid JSON, an array, a number value, a `GSTACK_` key) refuses the launch,
+because launching without the variables an env-gated debug bridge needs would
+look like a working app with no bridge. The detail names the key and its type,
+never a value. Added in the release after v1.91.101.0.
+
+**Fix.** In the shell that starts the daemon (macOS Terminal or Claude Code on
+the Mac with the device):
+
+```bash
+export GSTACK_IOS_LAUNCH_ENV='{"DEBUG_BRIDGE":"1"}'
+```
+
+or `unset GSTACK_IOS_LAUNCH_ENV`, then restart `gstack-ios-qa-daemon`.
+

ios-qa/daemon/src/devicectl.ts

@@ -8,6 +8,7 @@ import { spawnSync, type SpawnSyncReturns } from 'child_process';
 import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'fs';
 import { tmpdir } from 'os';
 import { join } from 'path';
+import { resultLine } from '../../../lib/result-codes';
 
 export interface DeviceEntry {
   identifier: string;
@@ -267,17 +268,53 @@ export function isAppRunning(
   }
 }
 
+/** The debug bridge's own variable namespace; a launch environment may not set it. */
+const BRIDGE_ENV_PREFIX = 'GSTACK_';
+
+/**
+ * Parse GSTACK_IOS_LAUNCH_ENV: a JSON object of string to string (for
+ * example `{"DEBUG_BRIDGE":"1"}`), or unset. A refusal names keys and types,
+ * never values, which may be credentials.
+ */
+export function parseLaunchEnv(raw: string | undefined): { ok: true; env: Record<string, string> | null } | { ok: false; detail: string } {
+  if (raw === undefined || raw.trim() === '') return { ok: true, env: null };
+  let value: unknown;
+  try { value = JSON.parse(raw); } catch { return { ok: false, detail: 'GSTACK_IOS_LAUNCH_ENV is not valid JSON' }; }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return { ok: false, detail: 'GSTACK_IOS_LAUNCH_ENV must be a JSON object of string to string' };
+  for (const [key, v] of Object.entries(value)) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) return { ok: false, detail: `${JSON.stringify(key)} is not an environment variable name` };
+    if (typeof v !== 'string') return { ok: false, detail: `${key} is a ${v === null ? 'null' : typeof v}, not a string` };
+    if (key.startsWith(BRIDGE_ENV_PREFIX)) return { ok: false, detail: `${key} collides with the debug bridge's reserved ${BRIDGE_ENV_PREFIX} variables` };
+  }
+  return { ok: true, env: Object.keys(value).length ? value as Record<string, string> : null };
+}
+
+/**
+ * The `--environment-variables` argv for a devicectl launch, from
+ * GSTACK_IOS_LAUNCH_ENV (empty when unset), or the IOS_LAUNCH_ENV_INVALID
+ * line that must stop the launch. Every launch path uses it, so the app is
+ * never started without the variables its debug bridge may be gated on.
+ */
+export function launchEnvArgs(raw = process.env.GSTACK_IOS_LAUNCH_ENV): { ok: true; args: string[] } | { ok: false; error: string } {
+  const launchEnv = parseLaunchEnv(raw);
+  if (!launchEnv.ok) return { ok: false, error: resultLine('ios-qa launch', 'IOS_LAUNCH_ENV_INVALID', launchEnv.detail) };
+  return { ok: true, args: launchEnv.env ? ['--environment-variables', JSON.stringify(launchEnv.env)] : [] };
+}
+
 /**
  * Launch an app on the device. Returns true on success, false otherwise.
  * Locked-device errors (the iPhone needs to be unlocked first) are surfaced
- * through the error string.
+ * through the error string. GSTACK_IOS_LAUNCH_ENV is forwarded (see
+ * launchEnvArgs); an invalid value refuses before any launch.
  */
 export function launchApp(
   udid: string,
   bundleId: string,
   spawn: SpawnImpl = defaultSpawn,
 ): { ok: boolean; error?: string } {
-  const r = spawn('xcrun', ['devicectl', 'device', 'process', 'launch', '--device', udid, bundleId]);
+  const env = launchEnvArgs();
+  if (!env.ok) return { ok: false, error: env.error };
+  const r = spawn('xcrun', ['devicectl', 'device', 'process', 'launch', '--device', udid, ...env.args, bundleId]);
   if (r.status === 0) return { ok: true };
   const err = (r.stderr?.toString() ?? '') + (r.stdout?.toString() ?? '');
   if (err.includes('was not, or could not be, unlocked')) {

ios-qa/daemon/test/devicectl-launch-env.test.ts

@@ -0,0 +1,69 @@
+// GSTACK_IOS_LAUNCH_ENV (split from #1796, credit @Bmathews721): a JSON object
+// of string to string forwarded to `devicectl device process launch
+// --environment-variables`. An invalid value refuses the launch with
+// IOS_LAUNCH_ENV_INVALID instead of launching the app without it.
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import type { SpawnSyncReturns } from 'child_process';
+import { launchApp, launchEnvArgs, parseLaunchEnv, type SpawnImpl } from '../src/devicectl';
+
+function recorder(status = 0): { spawn: SpawnImpl; calls: string[][] } {
+  const calls: string[][] = [];
+  const spawn: SpawnImpl = (cmd, args) => {
+    calls.push([cmd, ...args]);
+    return { status, stdout: Buffer.from(''), stderr: Buffer.from(''), pid: 1, output: [], signal: null } as unknown as SpawnSyncReturns<Buffer>;
+  };
+  return { spawn, calls };
+}
+
+let saved: string | undefined;
+beforeEach(() => { saved = process.env.GSTACK_IOS_LAUNCH_ENV; delete process.env.GSTACK_IOS_LAUNCH_ENV; });
+afterEach(() => { if (saved === undefined) delete process.env.GSTACK_IOS_LAUNCH_ENV; else process.env.GSTACK_IOS_LAUNCH_ENV = saved; });
+
+describe('GSTACK_IOS_LAUNCH_ENV', () => {
+  test('unset or empty leaves the launch argv unchanged', () => {
+    for (const value of [undefined, '', '  ', '{}']) {
+      if (value === undefined) delete process.env.GSTACK_IOS_LAUNCH_ENV; else process.env.GSTACK_IOS_LAUNCH_ENV = value;
+      const { spawn, calls } = recorder();
+      expect(launchApp('UDID', 'com.test', spawn)).toEqual({ ok: true });
+      expect(calls).toEqual([['xcrun', 'devicectl', 'device', 'process', 'launch', '--device', 'UDID', 'com.test']]);
+    }
+  });
+
+  test('a JSON object is forwarded before the bundle id', () => {
+    process.env.GSTACK_IOS_LAUNCH_ENV = '{"DEBUG_BRIDGE":"1","API_BASE":"http://localhost:8080"}';
+    const launch = recorder();
+    expect(launchApp('UDID', 'com.test', launch.spawn)).toEqual({ ok: true });
+    expect(launch.calls[0]).toEqual(['xcrun', 'devicectl', 'device', 'process', 'launch', '--device', 'UDID',
+      '--environment-variables', '{"DEBUG_BRIDGE":"1","API_BASE":"http://localhost:8080"}', 'com.test']);
+    expect(launchEnvArgs()).toEqual({ ok: true, args: ['--environment-variables', '{"DEBUG_BRIDGE":"1","API_BASE":"http://localhost:8080"}'] });
+    expect(launchEnvArgs('')).toEqual({ ok: true, args: [] });
+  });
+
+  test('invalid JSON, a non-object, a non-string value, a bad name or a bridge-reserved key refuses without launching', () => {
+    const cases: Array<[string, string]> = [
+      ['{"A":', 'is not valid JSON'],
+      ['["A=1"]', 'must be a JSON object of string to string'],
+      ['null', 'must be a JSON object of string to string'],
+      ['{"PORT":8080}', 'PORT is a number, not a string'],
+      ['{"BAD-NAME":"x"}', '"BAD-NAME" is not an environment variable name'],
+      ['{"GSTACK_IOS_QA_PORT":"1"}', 'GSTACK_IOS_QA_PORT collides with the debug bridge\'s reserved GSTACK_ variables'],
+    ];
+    for (const [value, detail] of cases) {
+      process.env.GSTACK_IOS_LAUNCH_ENV = value;
+      const { spawn, calls } = recorder();
+      const r = launchApp('UDID', 'com.test', spawn);
+      expect(r.ok).toBe(false);
+      expect(r.error).toContain(detail);
+      expect(r.error).toEndWith('(IOS_LAUNCH_ENV_INVALID)');
+      expect(calls).toEqual([]);
+    }
+  });
+
+  test('a refusal never echoes a value', () => {
+    process.env.GSTACK_IOS_LAUNCH_ENV = '{"TOKEN":"sk-secret-value","N":1}';
+    const r = launchApp('UDID', 'com.test', recorder().spawn);
+    expect(r.error).not.toContain('sk-secret-value');
+    expect(parseLaunchEnv('{"TOKEN": "sk-secret-value"')).toEqual({ ok: false, detail: expect.not.stringContaining('sk-secret-value') });
+  });
+});

lib/result-codes.ts

@@ -579,6 +579,12 @@ export const RESULT_CODES = {
     summary: 'no Git Bash found to run gstack\'s bash scripts on Windows',
     fix: 'install Git for Windows (winget install --id Git.Git -e), or set GSTACK_GIT_BASH to its bash.exe for good: in PowerShell, [Environment]::SetEnvironmentVariable(\'GSTACK_GIT_BASH\', \'C:\\Program Files\\Git\\bin\\bash.exe\', \'User\') and restart Claude Code, or add it to the "env" block of ~/.claude/settings.json',
   },
+  // Fix wave 2026-10-15, PR 3 (item 23, #1796).
+  IOS_LAUNCH_ENV_INVALID: {
+    anchor: 'ios-launch-env-invalid',
+    summary: 'GSTACK_IOS_LAUNCH_ENV is set but is not a JSON object of string to string, or sets a GSTACK_ variable the debug bridge reserves, so the app was not launched',
+    fix: 'set it to a JSON object such as GSTACK_IOS_LAUNCH_ENV=\'{"DEBUG_BRIDGE":"1"}\' (string values, no GSTACK_ keys), or unset it, then restart gstack-ios-qa-daemon',
+  },
 } as const satisfies Record<string, ResultCode>;
 
 export type ResultCodeName = keyof typeof RESULT_CODES;