Add open --relaunch and persist replay semantics (#52)

* Add open --relaunch and persist replay semantics

* Update agent-device skill docs for open --relaunch

* Disambiguate relaunch and save-script examples

* Support non-hierarchical deep links in open target detection

Author: thymikee

skills/agent-device/SKILL.md

@@ -42,6 +42,7 @@ agent-device boot                 # Ensure target is booted/ready without openin
 agent-device boot --platform ios  # Boot iOS simulator
 agent-device boot --platform android # Boot Android emulator/device target
 agent-device open [app|url]       # Boot device/simulator; optionally launch app or deep link URL
+agent-device open [app] --relaunch # Terminate app process first, then launch (fresh runtime)
 agent-device open [app] --activity com.example/.MainActivity # Android: open specific activity (app targets only)
 agent-device open "myapp://home" --platform android          # Android deep link
 agent-device open "https://example.com" --platform ios       # iOS simulator deep link
@@ -136,12 +137,14 @@ agent-device screenshot out.png
 ### Deterministic replay and updating
 
 ```bash
+agent-device open App --relaunch      # Fresh app process restart in the current session
 agent-device open App --save-script   # Save session script (.ad) on close
 agent-device replay ./session.ad      # Run deterministic replay from .ad script
 agent-device replay -u ./session.ad   # Update selector drift and rewrite .ad script in place
 ```
 
 `replay` reads `.ad` recordings.
+`--relaunch` controls launch semantics; `--save-script` controls recording. Combine only when both are needed.
 
 ### Trace logs (AX/XCTest)
 
@@ -172,6 +175,7 @@ agent-device apps --platform android --user-installed
 - If XCTest returns 0 nodes (foreground app changed), agent-device falls back to AX when available.
 - `open <app|url>` can be used within an existing session to switch apps or open deep links.
 - `open <app>` updates session app bundle context; URL opens do not set an app bundle id.
+- Use `open <app> --relaunch` during React Native/Fast Refresh debugging when you need a fresh app process without ending the session.
 - If AX returns the Simulator window or empty tree, restart Simulator or use `--backend xctest`.
 - Use `--session <name>` for parallel sessions; avoid device contention.
 - Use `--activity <component>` on Android to launch a specific activity (e.g. TV apps with LEANBACK); do not combine with URL opens.

skills/agent-device/references/session-management.md

@@ -14,6 +14,7 @@ Sessions isolate device context. A device can only be held by one session at a t
 - Name sessions semantically.
 - Close sessions when done.
 - Use separate sessions for parallel work.
+- For dev loops where runtime state can persist (for example React Native Fast Refresh), use `open <app> --relaunch` to restart the app process in the same session.
 - For deterministic replay scripts, prefer selector-based actions and assertions.
 - Use `replay -u` to update selector drift during maintenance.
 

src/core/__tests__/open-target.test.ts

@@ -5,6 +5,8 @@ import { isDeepLinkTarget } from '../open-target.ts';
 test('isDeepLinkTarget accepts URL-style deep links', () => {
   assert.equal(isDeepLinkTarget('myapp://home'), true);
   assert.equal(isDeepLinkTarget('https://example.com'), true);
+  assert.equal(isDeepLinkTarget('tel:123456789'), true);
+  assert.equal(isDeepLinkTarget('mailto:test@example.com'), true);
 });
 
 test('isDeepLinkTarget rejects app identifiers and malformed URLs', () => {

src/core/dispatch.ts

@@ -34,6 +34,7 @@ export type CommandFlags = {
   snapshotRaw?: boolean;
   snapshotBackend?: 'ax' | 'xctest';
   saveScript?: boolean;
+  relaunch?: boolean;
   noRecord?: boolean;
   appsFilter?: 'launchable' | 'user-installed' | 'all';
   appsMetadata?: boolean;

src/core/open-target.ts

@@ -1,5 +1,13 @@
 export function isDeepLinkTarget(input: string): boolean {
   const value = input.trim();
   if (!value) return false;
-  return /^[A-Za-z][A-Za-z0-9+.-]*:\/\/.+/.test(value);
+  if (/\s/.test(value)) return false;
+  const match = /^([A-Za-z][A-Za-z0-9+.-]*):(.+)$/.exec(value);
+  if (!match) return false;
+  const scheme = match[1]?.toLowerCase();
+  const rest = match[2] ?? '';
+  if (scheme === 'http' || scheme === 'https' || scheme === 'ws' || scheme === 'wss' || scheme === 'ftp' || scheme === 'ftps') {
+    return rest.startsWith('//');
+  }
+  return true;
 }

src/daemon/__tests__/session-store.test.ts

@@ -93,3 +93,27 @@ test('saveScript flag enables .ad session log writing', () => {
   const files = fs.readdirSync(root);
   assert.equal(files.filter((file) => file.endsWith('.ad')).length, 1);
 });
+
+test('writeSessionLog persists open --relaunch in script output', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-session-log-relaunch-'));
+  const store = new SessionStore(root);
+  const session = makeSession('default');
+  store.recordAction(session, {
+    command: 'open',
+    positionals: ['Settings'],
+    flags: { platform: 'ios', saveScript: true, relaunch: true },
+    result: {},
+  });
+  store.recordAction(session, {
+    command: 'close',
+    positionals: [],
+    flags: { platform: 'ios' },
+    result: {},
+  });
+
+  store.writeSessionLog(session);
+  const scriptFile = fs.readdirSync(root).find((file) => file.endsWith('.ad'));
+  assert.ok(scriptFile);
+  const script = fs.readFileSync(path.join(root, scriptFile!), 'utf8');
+  assert.match(script, /open "Settings" --relaunch/);
+});

src/daemon/handlers/__tests__/session.test.ts

@@ -212,3 +212,129 @@ test('open app on existing iOS session resolves and stores bundle id', async ()
   assert.equal(updated?.appName, 'settings');
   assert.equal(dispatchedContext?.appBundleId, 'com.apple.Preferences');
 });
+
+test('open --relaunch closes and reopens active session app', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'android-session';
+  sessionStore.set(
+    sessionName,
+    {
+      ...makeSession(sessionName, {
+        platform: 'android',
+        id: 'emulator-5554',
+        name: 'Pixel Emulator',
+        kind: 'emulator',
+        booted: true,
+      }),
+      appName: 'com.example.app',
+    },
+  );
+
+  const calls: Array<{ command: string; positionals: string[] }> = [];
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'open',
+      positionals: [],
+      flags: { relaunch: true },
+    },
+    sessionName,
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+    dispatch: async (_device, command, positionals) => {
+      calls.push({ command, positionals });
+      return {};
+    },
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, true);
+  assert.equal(calls.length, 2);
+  assert.deepEqual(calls[0], { command: 'close', positionals: ['com.example.app'] });
+  assert.deepEqual(calls[1], { command: 'open', positionals: ['com.example.app'] });
+});
+
+test('open --relaunch rejects URL targets', async () => {
+  const sessionStore = makeSessionStore();
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: 'default',
+      command: 'open',
+      positionals: ['https://example.com/path'],
+      flags: { relaunch: true },
+    },
+    sessionName: 'default',
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, false);
+  if (response && !response.ok) {
+    assert.equal(response.error.code, 'INVALID_ARGS');
+    assert.match(response.error.message, /does not support URL targets/i);
+  }
+});
+
+test('open --relaunch fails without app when no session exists', async () => {
+  const sessionStore = makeSessionStore();
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: 'default',
+      command: 'open',
+      positionals: [],
+      flags: { relaunch: true },
+    },
+    sessionName: 'default',
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, false);
+  if (response && !response.ok) {
+    assert.equal(response.error.code, 'INVALID_ARGS');
+    assert.match(response.error.message, /requires an app argument/i);
+  }
+});
+
+test('replay parses open --relaunch flag and replays open with relaunch semantics', async () => {
+  const sessionStore = makeSessionStore();
+  const replayRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-replay-relaunch-'));
+  const replayPath = path.join(replayRoot, 'relaunch.ad');
+  fs.writeFileSync(replayPath, 'open "Settings" --relaunch\n');
+
+  const invoked: DaemonRequest[] = [];
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: 'default',
+      command: 'replay',
+      positionals: [replayPath],
+      flags: {},
+    },
+    sessionName: 'default',
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: async (req) => {
+      invoked.push(req);
+      return { ok: true, data: {} };
+    },
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, true);
+  if (response && response.ok) {
+    assert.equal(response.data?.replayed, 1);
+  }
+  assert.equal(invoked.length, 1);
+  assert.equal(invoked[0]?.command, 'open');
+  assert.deepEqual(invoked[0]?.positionals, ['Settings']);
+  assert.equal(invoked[0]?.flags?.relaunch, true);
+});