agentlane 0.6.0 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,20 @@
2
2
 
3
3
  Newest first.
4
4
 
5
+ ## 0.6.1
6
+
7
+ The first look or screenshot no longer fails when the XCTest runner takes over a minute to start, and a simctl timeout and a failed Maestro download now say what happened.
8
+
9
+ ### Fixed
10
+
11
+ - **The first look or screenshot on a fresh iOS driver waits for the XCTest runner.** That call also waits for Maestro to start its runner on the simulator, which Maestro allows 120 s for, but the driver cut it at 60 s and gave up after one try. Where the start takes longer, as it can on GitHub's macOS runners, `look` and `screenshot` failed with `Maestro's session failed (timeout)`, and `up` reported `driver: not started`. On a simulator, the first call on each Maestro now gets 120 s on top of its own 60 s, and the driver sets `MAESTRO_DRIVER_STARTUP_TIMEOUT` so Maestro waits the same 120 s. Calls after the runner has answered keep 60 s. A first read or screenshot that still times out, or that Maestro answers with `iOS driver not ready in time`, restarts Maestro and is tried once more. That error no longer tells you to raise `MAESTRO_DRIVER_STARTUP_TIMEOUT`, which the driver sets itself. It now says the next call starts a fresh runner.
12
+ - **The CLI and the MCP server wait longer on a simulator.** They wait up to 10 minutes for a look or a screenshot and 28 for a run, which covers a first call the driver tries twice. Emulators keep Maestro's own startup time and the earlier limits.
13
+ - **A session failure says whether the driver tried again.** A call tried once read `failed again after a restart`. It now reads `Maestro's session failed (timeout): ...`, and a call tried twice reads `... and failed again when the driver tried once more: ...`.
14
+ - **A simctl command that runs out of time says so.** `up`'s preflight read `simulator runtime: xcrun simctl list -j runtimes failed: ` with nothing after it, and told you to install a runtime that was installed. It now reads `xcrun simctl list -j runtimes didn't finish within 180 s`, with a fix that says to run the listing by hand. Listing the runtimes gets 180 s instead of 60. A simctl command that fails without writing to stderr now names its exit status or signal.
15
+ - **Agents no longer stop agentlane's MCP calls before agentlane does.** Codex stops an MCP call after 60 s, GitHub Copilot after 30 s, Antigravity after 3 minutes and Gemini CLI after 10, while a first look on a fresh iOS simulator can take minutes, a run up to 28 minutes, and the same call may first wake a parked lane or install Maestro. `init` now sets a 60-minute limit on agentlane's server for each of them: `tool_timeout_sec` in `.codex/config.toml`, `timeout` in `.mcp.json` and `.gemini/settings.json`, and `timeoutSeconds` in `.agents/mcp_config.json`. That is enough for a call that wakes a parked lane, installs Maestro and runs the longest flow, and the agent stops a call that waits longer. It raises a shorter value and keeps a longer one, and in Codex's `[mcp_servers.agentlane]` table it now keeps the other keys you set. The Codex and Gemini CLI plugins carry the same limit, and the Cursor plugin gets its own MCP file without Codex's key. `doctor` warns about an entry with no limit or a shorter one, naming the file, the key and the value. Run `init` again in each project to set it. Cursor's CLI stops an MCP call after 60 s and has no setting for it.
16
+ - **A failed Maestro download is an error `up` reports.** When `up` downloaded Maestro for a sign-in hook and the download couldn't connect, it crashed with `TypeError: fetch failed` and a stack trace. A download that can't connect is now tried once more, and a failed one reads `downloading Maestro <version> from <url> failed: <reason>`, with a fix. In the sign-in step, `up` exits as it does for any failed step. In `up`'s driver step, as before, it prints `driver: not started (...)` and carries on.
17
+ - **`exec` ends its command if the process that ran it, or any process above it, exits, so `npx agentlane exec` ends with the agent's shell.** `exec` watched only its parent. Under `npx` that parent is npm, which keeps running when the shell above it is killed, so the command ran on. `exec` now records the pid, parent pid and start time of each process above it as it starts. Once a second it asks whether each still exists, which starts no process. Every 10 seconds it also reads their start times and parent pids with one `ps`. A process whose start time and parent pid have both changed counts as replaced, which catches a pid the system gave to a new process and lets a clock step pass. Under Codex, the shared app-server daemon and the processes above it don't count, since the daemon outlives the Codex window that started it.
18
+
5
19
  ## 0.6.0
6
20
 
7
21
  The server a project's lane databases live in can now be declared under `shared` in `agentlane.json`. It runs while a lane needs it and stops 5 minutes after the last one parks or ends, with its data kept. `up --no-app` gives tests a lane with the project's data and nothing else. The guard denies a `docker` or `podman` command that would leave a container running after the agent, and `exec` stops its command once the process that ran it is gone. This version runs beside 0.5.x on the same Mac; "Sharing a Mac with 0.5.x" lists what 0.5.x does differently.
@@ -40,7 +54,7 @@ The server a project's lane databases live in can now be declared under `shared`
40
54
  - **`restart` starts any shared service the lane needs that isn't running**, before it stops the service, so a failed shared start leaves the running service alone.
41
55
  - **The guard hooks start Node for commands that name `docker` or `podman`**, as they do for device and browser tools. `setsid` now passes through like `nohup`, so `setsid <device command>` gets the device check.
42
56
  - **`up`'s claim step** reads `claimed lane <id>: no device, browser or port` for a lane that holds none, and a lane with no ports no longer ends the line with a stray comma.
43
- - **The README, the docs home and the package description now open on the problem agentlane solves**, running several coding agents on one machine.
57
+ - **The README, the docs home and the package description now open on the problem agentlane solves.**
44
58
 
45
59
  ### Fixed
46
60
 
package/README.md CHANGED
@@ -19,7 +19,7 @@
19
19
 
20
20
  <picture>
21
21
  <source media="(prefers-color-scheme: dark)" srcset="media/hero-dark.svg">
22
- <img src="media/hero-light.svg" width="960" alt="Claude Code, Codex and Cursor, each shown with its mark, get their own ports, dev server, database and a browser, iOS simulator or Android emulator from agentlane up. Each types an item into its own copy of the Basket app, ticks items off and takes screenshots, then Codex finishes and its ports and device are released.">
22
+ <img src="media/hero-light.svg" width="960" alt="Claude Code, Codex and Cursor, each shown with its mark, run agentlane up and get their own ports, dev server, database and a browser, iOS simulator or Android emulator. Each types an item into its own copy of the Basket app, ticks items off and takes screenshots, then Codex finishes and its ports and device are released.">
23
23
  </picture>
24
24
 
25
25
  Whether you run several Claude Code sessions on one app, Codex and Cursor side by side, or agents testing iOS and Android at once, agentlane keeps them apart.
@@ -0,0 +1,58 @@
1
+ import { TOOL } from "../name.js";
2
+ import { AGENT_NAMES } from "./detect.js";
3
+ /** Each host's per-server limit on one MCP call, where a project file can set it. Cursor has none. */
4
+ export const HOST_TIMEOUTS = {
5
+ // https://code.claude.com/docs/en/env-vars: MCP_TOOL_TIMEOUT defaults to 100000000 ms; MCP_TIMEOUT limits startup on its own
6
+ claude: { key: 'timeout', unit: 'ms', callSec: 100_000, connectSec: null, signed: false },
7
+ // https://learn.chatgpt.com/docs/extend/mcp: tool_timeout_sec defaults to 60; startup_timeout_sec limits startup on its own
8
+ codex: { key: 'tool_timeout_sec', unit: 's', callSec: 60, connectSec: null, signed: false },
9
+ // https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference: timeout defaults to 30000 ms and is also the connection budget, floored at 60000 ms
10
+ copilot: { key: 'timeout', unit: 'ms', callSec: 30, connectSec: 60, signed: false },
11
+ // https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md: timeout defaults to 600000 ms and also limits connecting and discovery
12
+ gemini: { key: 'timeout', unit: 'ms', callSec: 600, connectSec: 600, signed: false },
13
+ // https://antigravity.google/docs/mcp: a positive timeoutSeconds replaces both the 180 s call and the 300 s connect limit
14
+ antigravity: { key: 'timeoutSeconds', unit: 's', callSec: 180, connectSec: 300, signed: true },
15
+ };
16
+ export function hostTimeout(agent) {
17
+ const hosts = HOST_TIMEOUTS;
18
+ return hosts[agent];
19
+ }
20
+ /** The limit on one call agentlane writes for each host: long enough for a slow call that succeeds, short enough that a hung one gives the agent back. */
21
+ export const CALL_LIMIT_SEC = 60 * 60;
22
+ function inUnit(host, sec) {
23
+ return host.unit === 'ms' ? sec * 1000 : sec;
24
+ }
25
+ function neededSec(host) {
26
+ return Math.max(CALL_LIMIT_SEC, host.connectSec ?? 0);
27
+ }
28
+ /** The value agentlane writes for this host, in the host's unit. */
29
+ export function timeoutValue(host) {
30
+ return inUnit(host, neededSec(host));
31
+ }
32
+ function inEffect(host, value) {
33
+ return value === undefined || (host.signed && value === 0) ? inUnit(host, host.callSec) : value;
34
+ }
35
+ /** Whether the host, with this value of its key (undefined when unset), lets a call run as long as agentlane needs. */
36
+ export function coversCalls(host, value) {
37
+ const limit = inEffect(host, value);
38
+ if (typeof limit !== 'number' || !Number.isFinite(limit))
39
+ return false;
40
+ return limit >= timeoutValue(host) || (host.signed && limit < 0);
41
+ }
42
+ function duration(sec) {
43
+ return sec % 60 === 0 ? `${String(sec / 60)} min` : `${String(sec)} s`;
44
+ }
45
+ /** Why this host would stop a call sooner than agentlane needs, or null when it wouldn't. */
46
+ export function timeoutShortfall(agent, value) {
47
+ const host = hostTimeout(agent);
48
+ if (!host || coversCalls(host, value))
49
+ return null;
50
+ const needs = `${host.key} ${String(timeoutValue(host))} (${host.unit === 'ms' ? 'milliseconds' : 'seconds'}, ${duration(neededSec(host))})`;
51
+ const stops = `${AGENT_NAMES[agent]} stops a call after ${duration(host.callSec)}`;
52
+ const has = value === undefined
53
+ ? `it has no ${host.key}, so ${stops}`
54
+ : inEffect(host, value) === value
55
+ ? `its ${host.key} is ${JSON.stringify(value)}`
56
+ : `its ${host.key} is 0, which keeps the default, so ${stops}`;
57
+ return `${has}; ${TOOL} needs ${needs}`;
58
+ }
@@ -45,6 +45,10 @@ function refused(file, edits, reason) {
45
45
  edits,
46
46
  };
47
47
  }
48
+ function shortfalls(found) {
49
+ const named = [...new Set(found.filter(reason => typeof reason === 'string'))];
50
+ return named.length > 0 ? named.join('; ') : null;
51
+ }
48
52
  function planJson(root, file, edits) {
49
53
  const text = readText(path.join(root, file));
50
54
  const doc = readJson(text);
@@ -69,7 +73,7 @@ function planJson(root, file, edits) {
69
73
  return {
70
74
  file,
71
75
  status: text === null ? 'create' : 'update',
72
- reason: null,
76
+ reason: text === null ? null : shortfalls(edits.map(edit => (edit.kind === 'json' ? edit.shortfall?.(doc) : null))),
73
77
  desired: { kind: 'text', text: `${JSON.stringify(next, null, text === null ? 2 : indentOf(text))}\n` },
74
78
  edits,
75
79
  };
@@ -81,7 +85,7 @@ function planToml(root, file, edits) {
81
85
  for (const edit of edits) {
82
86
  if (edit.kind !== 'toml')
83
87
  continue;
84
- const result = edit.body === null ? removeTable(next, edit.table) : upsertTable(next, edit.table, edit.body);
88
+ const result = edit.entries === null ? removeTable(next, edit.table) : upsertTable(next, edit.table, edit.entries);
85
89
  if (result.kind === 'refused')
86
90
  return refused(file, edits, result.reason);
87
91
  if (result.kind === 'changed') {
@@ -91,7 +95,13 @@ function planToml(root, file, edits) {
91
95
  }
92
96
  if (!changed)
93
97
  return { file, status: 'unchanged', reason: null, desired: null, edits };
94
- return { file, status: text === null ? 'create' : 'update', reason: null, desired: { kind: 'text', text: next }, edits };
98
+ return {
99
+ file,
100
+ status: text === null ? 'create' : 'update',
101
+ reason: text === null ? null : shortfalls(edits.map(edit => (edit.kind === 'toml' ? edit.shortfall?.(text) : null))),
102
+ desired: { kind: 'text', text: next },
103
+ edits,
104
+ };
95
105
  }
96
106
  function planStub(root, edit) {
97
107
  const text = readText(path.join(root, edit.file));
@@ -192,24 +202,26 @@ export function planInit(root, agents, skills, env) {
192
202
  const byFile = new Map();
193
203
  for (const edit of edits)
194
204
  byFile.set(edit.file, [...(byFile.get(edit.file) ?? []), edit]);
195
- const files = [...byFile].flatMap(([file, group]) => {
196
- const [first] = group;
197
- if (first?.kind === 'stub')
198
- return [planStub(root, first)];
199
- if (first?.kind === 'link')
200
- return [planLink(root, first)];
201
- if (first?.kind === 'unlink') {
202
- const removal = planUnlink(root, first);
203
- return removal ? [removal] : [];
204
- }
205
- if (first?.kind === 'toml')
206
- return [planToml(root, file, group)];
207
- const plan = planJson(root, file, group);
208
- const cleanupOnly = group.every(edit => edit.kind === 'json' && edit.cleanup === true);
209
- return cleanupOnly && plan.status === 'unchanged' ? [] : [plan];
210
- });
205
+ const files = [...byFile].flatMap(([file, group]) => planFile(root, file, group));
211
206
  return { root, agents: [...agents], claudePlugin, files };
212
207
  }
208
+ /** What init would do to one file with these edits, all of which name that file. */
209
+ export function planFile(root, file, group) {
210
+ const [first] = group;
211
+ if (first?.kind === 'stub')
212
+ return [planStub(root, first)];
213
+ if (first?.kind === 'link')
214
+ return [planLink(root, first)];
215
+ if (first?.kind === 'unlink') {
216
+ const removal = planUnlink(root, first);
217
+ return removal ? [removal] : [];
218
+ }
219
+ if (first?.kind === 'toml')
220
+ return [planToml(root, file, group)];
221
+ const plan = planJson(root, file, group);
222
+ const cleanupOnly = group.every(edit => edit.kind === 'json' && edit.cleanup === true);
223
+ return cleanupOnly && plan.status === 'unchanged' ? [] : [plan];
224
+ }
213
225
  function backup(root, file, into) {
214
226
  const from = path.join(root, file);
215
227
  try {
@@ -230,8 +230,9 @@ class Scanner {
230
230
  this.fail("a key needs '=' and a value");
231
231
  this.advance();
232
232
  this.spaces();
233
+ const start = this.pos;
233
234
  this.value();
234
- keys.push({ path: [...table, ...key], table, line });
235
+ keys.push({ path: [...table, ...key], table, line, end: this.line, value: this.text.slice(start, this.pos) });
235
236
  this.endOfLine();
236
237
  }
237
238
  }
@@ -248,17 +249,11 @@ function same(a, b) {
248
249
  function bare(part) {
249
250
  return /^[A-Za-z0-9_-]+$/.test(part) ? part : JSON.stringify(part);
250
251
  }
251
- function lines(block) {
252
- return block
253
- .split('\n')
254
- .map(line => line.trim())
255
- .filter(line => line !== '' && !line.startsWith('#'));
256
- }
257
252
  /**
258
- * Sets one table, `[a.b]` with `body` under it, and leaves every other line of the file as it was. The table's own
259
- * sub-tables (`[a.b.env]`) stay.
253
+ * Sets each entry's key in one table, `[a.b]`, adding the table when the file lacks it, and leaves every other line of
254
+ * the file as it was, the table's other keys and its sub-tables (`[a.b.env]`) included.
260
255
  */
261
- export function upsertTable(text, table, body) {
256
+ export function upsertTable(text, table, entries) {
262
257
  let outline;
263
258
  try {
264
259
  outline = outlineToml(text);
@@ -271,23 +266,42 @@ export function upsertTable(text, table, body) {
271
266
  if (ours.length > 1 || ours.some(h => h.array))
272
267
  return { kind: 'refused', reason: `it declares [${name}] more than once` };
273
268
  const own = ours[0];
274
- const next = own ? outline.headers.find(h => h.line > own.line) : undefined;
275
269
  const foreign = outline.keys.find(k => (startsWith(k.path, table) || startsWith(table, k.path)) && !startsWith(k.table, table));
276
270
  if (foreign)
277
271
  return { kind: 'refused', reason: `line ${String(foreign.line)} sets ${foreign.path.join('.')} outside [${name}]` };
278
- const all = text.split('\n');
279
- const block = `[${name}]\n${body}`;
272
+ const set = (entry) => `${bare(entry.key)} = ${entry.value}`;
280
273
  if (!own) {
281
274
  const head = text === '' ? '' : text.endsWith('\n') ? `${text}\n` : `${text}\n\n`;
282
- return { kind: 'changed', text: `${head}${block}\n` };
275
+ return { kind: 'changed', text: `${head}${[`[${name}]`, ...entries.map(set)].join('\n')}\n` };
276
+ }
277
+ const keys = outline.keys.filter(k => same(k.table, table));
278
+ const replaced = new Map();
279
+ const dropped = new Set();
280
+ const added = [];
281
+ for (const entry of entries) {
282
+ const found = keys.filter(k => k.path[table.length] === entry.key);
283
+ const [first] = found;
284
+ if (!first) {
285
+ added.push(set(entry));
286
+ continue;
287
+ }
288
+ const whole = found.length === 1 && first.path.length === table.length + 1;
289
+ if (whole && (first.value === entry.value || entry.keeps?.(first.value) === true))
290
+ continue;
291
+ for (const key of found)
292
+ for (let line = key.line; line <= key.end; line++)
293
+ dropped.add(line);
294
+ replaced.set(first.line, set(entry));
283
295
  }
284
- let end = next ? next.line - 1 : all.length;
285
- while (end > own.line && /^\s*(#.*)?$/.test(all[end - 1] ?? ''))
286
- end--;
287
- const current = all.slice(own.line - 1, end).join('\n');
288
- if (lines(current).join('\n') === lines(block).join('\n'))
296
+ if (replaced.size === 0 && added.length === 0)
289
297
  return { kind: 'unchanged' };
290
- return { kind: 'changed', text: [...all.slice(0, own.line - 1), ...block.split('\n'), ...all.slice(end)].join('\n') };
298
+ const after = Math.max(own.line, ...keys.map(k => k.end));
299
+ const next = text.split('\n').flatMap((line, i) => {
300
+ const at = i + 1;
301
+ const kept = replaced.get(at) ?? (dropped.has(at) ? null : line);
302
+ return [...(kept === null ? [] : [kept]), ...(at === after ? added : [])];
303
+ });
304
+ return { kind: 'changed', text: next.join('\n') };
291
305
  }
292
306
  /** Removes one table, `[a.b]`, with its own sub-tables, and leaves every other line of the file as it was. */
293
307
  export function removeTable(text, table) {
@@ -3,7 +3,7 @@ import path from 'node:path';
3
3
  import { CLI, TOOL } from "../name.js";
4
4
  import { AGENTS } from "../registry/owner.js";
5
5
  import { CLAUDE_SETTINGS, claudePluginInstall, describePluginSource, jsonObjectAt } from "./claude-plugin.js";
6
- import { planInit } from "./init.js";
6
+ import { planFile, planInit } from "./init.js";
7
7
  import { listSkills, SKILLS_DIR } from "./skills.js";
8
8
  import { agentEdits, disablesOurServer, pluginEnabled } from "./wiring.js";
9
9
  const SHARED = new Set(['.mcp.json']);
@@ -37,7 +37,7 @@ function problem(file) {
37
37
  case 'create':
38
38
  return `missing ${file.file} (${parts})`;
39
39
  case 'update':
40
- return `stale ${file.file} (${parts})`;
40
+ return `stale ${file.file} (${parts})${file.reason === null ? '' : `: ${file.reason}`}`;
41
41
  case 'remove':
42
42
  return `duplicate ${file.file} (${parts})`;
43
43
  case 'refused':
@@ -46,6 +46,15 @@ function problem(file) {
46
46
  return '';
47
47
  }
48
48
  }
49
+ /** The part of a file's plan that the agent's own edits make, so its line names only what `init --agents <agent>` changes. */
50
+ function ownShare(root, file, agent) {
51
+ const own = file.edits.filter(e => e.agent === agent);
52
+ if (own.length === 0)
53
+ return [];
54
+ if (own.length === file.edits.length)
55
+ return [file];
56
+ return planFile(root, file.file, own).filter(f => f.status !== 'unchanged');
57
+ }
49
58
  function check(name, problems, fine, fix) {
50
59
  return problems.length === 0
51
60
  ? { name, ok: true, warning: false, detail: fine, fix: '' }
@@ -83,7 +92,7 @@ export function agentWiringChecks(root, env, skills = listSkills(SKILLS_DIR)) {
83
92
  if (plan.files.some(f => f.edits.some(e => e.kind === 'stub')))
84
93
  checks.push(check('wiring skills', off.filter(f => f.edits.every(e => e.agent === null)), `${String(skills.length)} skill stubs in .agents/skills`, fix));
85
94
  for (const agent of agents) {
86
- const mine = off.filter(f => f.edits.some(e => e.agent === agent));
95
+ const mine = off.flatMap(f => ownShare(root, f, agent));
87
96
  const plugin = agent === 'claude' ? plan.claudePlugin : null;
88
97
  const fine = plugin ? `through the plugin: ${describePluginSource(plugin)}` : 'MCP server and hooks in place';
89
98
  const line = check(`wiring ${agent}`, mine, fine, `${CLI} init --agents ${agent}`);
@@ -1,7 +1,9 @@
1
1
  import { FORMER, TOOL } from "../name.js";
2
2
  import { CLAUDE_SETTINGS } from "./claude-plugin.js";
3
+ import { coversCalls, HOST_TIMEOUTS, hostTimeout, timeoutShortfall, timeoutValue } from "./host-timeouts.js";
3
4
  import { hookCommand, isToolkitHook, mcpLaunch } from "./launcher.js";
4
5
  import { stubOf } from "./skills.js";
6
+ import { outlineToml } from "./toml.js";
5
7
  export const SKILLS = '.agents/skills';
6
8
  export const CLAUDE_SKILLS = '.claude/skills';
7
9
  function object(doc, key) {
@@ -26,6 +28,7 @@ export function formerServerIn(servers) {
26
28
  }
27
29
  function mcpEdit(file, agent) {
28
30
  const ours = mcpLaunch();
31
+ const host = hostTimeout(agent);
29
32
  return {
30
33
  kind: 'json',
31
34
  file,
@@ -40,15 +43,34 @@ function mcpEdit(file, agent) {
40
43
  const kept = isObject(current) ? current : {};
41
44
  if (former !== undefined)
42
45
  Reflect.deleteProperty(servers, FORMER.tool);
43
- servers[TOOL] = { ...kept, ...ours };
46
+ const entry = { ...kept, ...ours };
47
+ if (host && !coversCalls(host, entry[host.key]))
48
+ entry[host.key] = timeoutValue(host);
49
+ servers[TOOL] = entry;
44
50
  return null;
45
51
  },
46
52
  present: doc => {
47
53
  const servers = doc.mcpServers;
48
54
  return (isObject(servers) && TOOL in servers) || formerServerIn(servers);
49
55
  },
56
+ shortfall: doc => {
57
+ const entry = isObject(doc.mcpServers) ? doc.mcpServers[TOOL] : undefined;
58
+ return host && isObject(entry) ? timeoutShortfall(agent, entry[host.key]) : null;
59
+ },
50
60
  };
51
61
  }
62
+ function tomlOutline(text) {
63
+ try {
64
+ return outlineToml(text);
65
+ }
66
+ catch {
67
+ return null;
68
+ }
69
+ }
70
+ function tomlNumber(value) {
71
+ const number = Number(value.replaceAll('_', ''));
72
+ return value.trim() !== '' && Number.isFinite(number) ? number : value;
73
+ }
52
74
  function hasToolkitHook(entry) {
53
75
  if (typeof entry !== 'object' || entry === null)
54
76
  return false;
@@ -194,6 +216,8 @@ function renameFormerPlugin(doc) {
194
216
  }
195
217
  function codexEdits() {
196
218
  const { command: launcher, args } = mcpLaunch();
219
+ const host = HOST_TIMEOUTS.codex;
220
+ const table = ['mcp_servers', TOOL];
197
221
  return [
198
222
  {
199
223
  kind: 'toml',
@@ -201,15 +225,26 @@ function codexEdits() {
201
225
  agent: 'codex',
202
226
  part: 'MCP server',
203
227
  table: ['mcp_servers', FORMER.tool],
204
- body: null,
228
+ entries: null,
205
229
  },
206
230
  {
207
231
  kind: 'toml',
208
232
  file: '.codex/config.toml',
209
233
  agent: 'codex',
210
234
  part: 'MCP server',
211
- table: ['mcp_servers', TOOL],
212
- body: `command = ${JSON.stringify(launcher)}\nargs = [${args.map(a => JSON.stringify(a)).join(', ')}]`,
235
+ table,
236
+ entries: [
237
+ { key: 'command', value: JSON.stringify(launcher) },
238
+ { key: 'args', value: `[${args.map(a => JSON.stringify(a)).join(', ')}]` },
239
+ { key: host.key, value: String(timeoutValue(host)), keeps: value => coversCalls(host, tomlNumber(value)) },
240
+ ],
241
+ shortfall: text => {
242
+ const outline = tomlOutline(text);
243
+ if (!outline?.headers.some(h => h.path.join('.') === table.join('.')))
244
+ return null;
245
+ const value = outline.keys.find(k => k.path.join('.') === [...table, host.key].join('.'))?.value;
246
+ return timeoutShortfall('codex', value === undefined ? undefined : tomlNumber(value));
247
+ },
213
248
  },
214
249
  hookEdit('.codex/hooks.json', 'codex', 'guard hook', 'PreToolUse', {
215
250
  matcher: 'Bash',
@@ -5,7 +5,27 @@ import { UsageError } from "../registry/refusal.js";
5
5
  import { DeviceBackendError, DeviceRunningError } from "./backend.js";
6
6
  const UDID = /^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$/;
7
7
  const execFileAsync = promisify(execFile);
8
- function simctl(args, timeoutMs = 60_000) {
8
+ // On a GitHub macos-26 runner, listing the runtimes in up's preflight took longer than 60 s (run 44985632277).
9
+ const RUNTIMES_TIMEOUT_MS = 180_000;
10
+ export class SimctlTimeout extends DeviceBackendError {
11
+ constructor(args, timeoutMs) {
12
+ super(`xcrun simctl ${args.join(' ')} didn't finish within ${String(Math.round(timeoutMs / 1000))} s`);
13
+ this.name = 'SimctlTimeout';
14
+ }
15
+ }
16
+ function failure(args, error, timeoutMs, timedOut) {
17
+ if (timedOut)
18
+ return new SimctlTimeout(args, timeoutMs);
19
+ const e = error;
20
+ const command = `xcrun simctl ${args.join(' ')}`;
21
+ const stderr = e.stderr?.trim() ?? '';
22
+ if (stderr !== '')
23
+ return new DeviceBackendError(`${command} failed: ${stderr}`);
24
+ const status = e.status ?? (typeof e.code === 'number' ? e.code : undefined);
25
+ const ending = e.signal ? `signal ${e.signal}` : status != null ? `exit status ${String(status)}` : undefined;
26
+ return new DeviceBackendError(ending === undefined ? `${command} failed: ${e.message.trim()}` : `${command} failed (${ending}) with nothing on stderr`);
27
+ }
28
+ export function simctl(args, timeoutMs = 60_000) {
9
29
  try {
10
30
  return execFileSync('xcrun', ['simctl', ...args], {
11
31
  encoding: 'utf8',
@@ -18,7 +38,7 @@ function simctl(args, timeoutMs = 60_000) {
18
38
  if (e.code === 'ENOENT') {
19
39
  throw new UsageError('xcrun is not on PATH, so iOS simulators are unavailable', 'install Xcode, or claim without a device (--no-device)');
20
40
  }
21
- throw new DeviceBackendError(`xcrun simctl ${args.join(' ')} failed: ${(e.stderr ?? e.message).trim()}`);
41
+ throw failure(args, error, timeoutMs, e.code === 'ETIMEDOUT');
22
42
  }
23
43
  }
24
44
  function compareVersions(a, b) {
@@ -91,7 +111,7 @@ export function parseDeviceList(json) {
91
111
  export const simctlBackend = {
92
112
  platform: 'ios',
93
113
  resolveSpec(request) {
94
- const parsed = JSON.parse(simctl(['list', '-j', 'runtimes']));
114
+ const parsed = JSON.parse(simctl(['list', '-j', 'runtimes'], RUNTIMES_TIMEOUT_MS));
95
115
  return resolveSimSpec(parsed.runtimes ?? [], request);
96
116
  },
97
117
  list() {
@@ -120,12 +140,13 @@ export const simctlBackend = {
120
140
  }
121
141
  },
122
142
  async boot(id) {
143
+ const args = ['bootstatus', id, '-b'];
144
+ const timeoutMs = 300_000;
123
145
  try {
124
- await execFileAsync('xcrun', ['simctl', 'bootstatus', id, '-b'], { timeout: 300_000 });
146
+ await execFileAsync('xcrun', ['simctl', ...args], { timeout: timeoutMs });
125
147
  }
126
148
  catch (error) {
127
- const e = error;
128
- throw new DeviceBackendError(`xcrun simctl bootstatus ${id} -b failed: ${(e.stderr ?? e.message).trim()}`);
149
+ throw failure(args, error, timeoutMs, error.killed === true);
129
150
  }
130
151
  },
131
152
  };
@@ -11,18 +11,45 @@ import { describeIdle, readDriverSettings, takeIdleStop } from "./idle.js";
11
11
  import { ensureMaestro, findJdk17, MAESTRO_OVERRIDE_ENV } from "./install.js";
12
12
  import { liveHolder, lockHolder, tryLock } from "./lock.js";
13
13
  import { enginePaths, ensurePrivateDir } from "./paths.js";
14
+ import { longestIosCallMs, warmCallMs } from "./supervisor.js";
14
15
  export const ENGINE_MAIN = path.join(import.meta.dirname, `engine-main${path.extname(import.meta.filename)}`);
15
- const START_TIMEOUT_MS = 20_000;
16
+ export const START_TIMEOUT_MS = 20_000;
17
+ export const PING_TIMEOUT_MS = 5000;
16
18
  const STOP_WAIT_MS = 35_000;
17
- const RESPONSE_TIMEOUT_MS = {
19
+ const ROUNDS = 3;
20
+ const MARGIN_MS = 60_000;
21
+ const CONTROL_TIMEOUT_MS = {
18
22
  ping: 10_000,
19
23
  status: 30_000,
20
24
  stop: 30_000,
21
- look: 150_000,
22
- screenshot: 150_000,
23
- run: 900_000,
24
25
  record: 30_000,
25
26
  };
27
+ const firstIosRead = longestIosCallMs('inspect_screen', { retry: true });
28
+ const DEVICE_TIMEOUT_MS = {
29
+ ios: {
30
+ look: firstIosRead + warmCallMs('take_screenshot') + MARGIN_MS,
31
+ screenshot: longestIosCallMs('take_screenshot', { retry: true }) + warmCallMs('inspect_screen') + MARGIN_MS,
32
+ run: firstIosRead + warmCallMs('run') + firstIosRead + warmCallMs('take_screenshot') + MARGIN_MS,
33
+ },
34
+ android: { look: 150_000, screenshot: 150_000, run: 900_000 },
35
+ };
36
+ /** The slowest answer a client waits for, on any platform. */
37
+ export const LONGEST_ANSWER_MS = Math.max(...Object.values(CONTROL_TIMEOUT_MS), ...Object.values(DEVICE_TIMEOUT_MS).flatMap(ops => Object.values(ops)));
38
+ /** How long a client waits for the engine to answer one request on a lane of this platform. */
39
+ export function responseTimeoutMs(op, platform) {
40
+ switch (op) {
41
+ case 'look':
42
+ case 'screenshot':
43
+ case 'run':
44
+ return DEVICE_TIMEOUT_MS[platform][op];
45
+ default:
46
+ return CONTROL_TIMEOUT_MS[op];
47
+ }
48
+ }
49
+ /** How long a client waits for the engine to answer one request on this lane. */
50
+ export function laneTimeoutMs(lane, op) {
51
+ return responseTimeoutMs(op, lane.device?.platform ?? 'ios');
52
+ }
26
53
  const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
27
54
  function logTail(file) {
28
55
  try {
@@ -159,7 +186,7 @@ async function startEngine(target, paths) {
159
186
  let respawned = false;
160
187
  const deadline = Date.now() + START_TIMEOUT_MS;
161
188
  while (Date.now() < deadline) {
162
- const answer = await send(paths, { op: 'ping', lane: refOf(target.lane) }, 5000).catch(() => undefined);
189
+ const answer = await send(paths, { op: 'ping', lane: refOf(target.lane) }, PING_TIMEOUT_MS).catch(() => undefined);
163
190
  if (answer && answer.stopping === undefined)
164
191
  return;
165
192
  const exit = exited();
@@ -203,9 +230,10 @@ function coldStartNote(ms, idleStop) {
203
230
  export async function callEngine(target, request) {
204
231
  const paths = enginePaths(target.stateDir, target.lane.id);
205
232
  const full = { ...request, lane: refOf(target.lane) };
206
- for (let round = 0; round < 3; round++) {
233
+ const timeoutMs = laneTimeoutMs(target.lane, full.op);
234
+ for (let round = 0; round < ROUNDS; round++) {
207
235
  refuseWhileReleasing(target, paths);
208
- let response = await send(paths, full, RESPONSE_TIMEOUT_MS[full.op]);
236
+ let response = await send(paths, full, timeoutMs);
209
237
  let coldStart;
210
238
  if (!response) {
211
239
  const idleStop = takeIdleStop(paths.idle);
@@ -217,7 +245,7 @@ export async function callEngine(target, request) {
217
245
  refuseWhileReleasing(target, paths);
218
246
  throw error;
219
247
  }
220
- response = await send(paths, full, RESPONSE_TIMEOUT_MS[full.op]);
248
+ response = await send(paths, full, timeoutMs);
221
249
  if (response) {
222
250
  const ms = Date.now() - started;
223
251
  coldStart = { ms, ...(idleStop ? { idleStop: { stoppedAt: idleStop.stoppedAt, idleMs: idleStop.idleMs } } : {}) };
@@ -244,7 +272,7 @@ export async function prewarmEngine(target) {
244
272
  }
245
273
  /** Asks a running engine about itself; undefined when none runs. */
246
274
  export async function engineStatus(stateDir, lane) {
247
- return send(enginePaths(stateDir, lane.id), { op: 'status', lane: refOf(lane) }, RESPONSE_TIMEOUT_MS.status);
275
+ return send(enginePaths(stateDir, lane.id), { op: 'status', lane: refOf(lane) }, CONTROL_TIMEOUT_MS.status);
248
276
  }
249
277
  function exited(engine, processes) {
250
278
  if (!isAlive(engine.pid))
@@ -255,7 +283,7 @@ function exited(engine, processes) {
255
283
  /** Stops a lane's engine and waits until its process has exited; false when none was running. */
256
284
  export async function stopEngine(stateDir, lane, waitMs = 30_000) {
257
285
  const paths = enginePaths(stateDir, lane.id);
258
- const answer = await send(paths, { op: 'stop', lane: refOf(lane) }, RESPONSE_TIMEOUT_MS.stop).catch(() => undefined);
286
+ const answer = await send(paths, { op: 'stop', lane: refOf(lane) }, CONTROL_TIMEOUT_MS.stop).catch(() => undefined);
259
287
  if (!answer)
260
288
  return false;
261
289
  const engine = identityOf(systemProcesses, answer.pid);
@@ -43,6 +43,10 @@ const ACTIONS = {
43
43
  run: 'run',
44
44
  record: 'record',
45
45
  };
46
+ function sessionFailureText(error) {
47
+ const again = error.attempts.length > 1 ? ' and failed again when the driver tried once more' : '';
48
+ return `Maestro's session failed (${error.kind})${again}: ${error.detail}`;
49
+ }
46
50
  /**
47
51
  * The long-lived driver engine of one lane. It owns the lane's `maestro mcp` session, answers tool calls on a Unix
48
52
  * socket one at a time, records activity on the lane, and stops (freeing Maestro, its xcodebuild and its runner)
@@ -135,6 +139,8 @@ export async function runEngine(config, deps = {}) {
135
139
  logFd,
136
140
  log,
137
141
  ...(config.runnerWatchMs === undefined ? {} : { runnerWatchMs: config.runnerWatchMs }),
142
+ ...(config.callTimeouts === undefined ? {} : { timeouts: config.callTimeouts }),
143
+ ...(config.runnerStartupMs === undefined ? {} : { runnerStartupMs: config.runnerStartupMs }),
138
144
  ...(deps.rows ? { rows: deps.rows } : {}),
139
145
  });
140
146
  const session = new DriverSession(supervisor, deps.images ?? sipsImages(path.join(paths.work, 'images')), { steps: paths.steps, volatile: paths.volatile, work: paths.work, shots: paths.shots }, log);
@@ -300,7 +306,7 @@ export async function runEngine(config, deps = {}) {
300
306
  return {
301
307
  pid: process.pid,
302
308
  ok: false,
303
- error: `Maestro's session failed (${error.kind}) and failed again after a restart: ${error.message}. The driver's log: ${paths.log}`,
309
+ error: `${sessionFailureText(error)}. The driver's log: ${paths.log}`,
304
310
  sessionFailure: { kind: error.kind, attempts: error.attempts },
305
311
  };
306
312
  }
@@ -7,7 +7,7 @@ import { pipeline } from 'node:stream/promises';
7
7
  import { JAVA_HOME_ENV } from "../hooks/env.js";
8
8
  import { CLI, envName, TOOL } from "../name.js";
9
9
  import { identityOf, systemProcesses } from "../processes.js";
10
- import { DriverError } from "./errors.js";
10
+ import { DriverError, messageOf } from "./errors.js";
11
11
  import { runCommand, tail } from "./exec.js";
12
12
  import { tryLock, unlock } from "./lock.js";
13
13
  import { MAESTRO_RELEASE } from "./release.js";
@@ -16,6 +16,16 @@ import { compareVersions, laneToolsOf, removeOlderVersions, systemCommandLines,
16
16
  export const MAESTRO_OVERRIDE_ENV = envName('MAESTRO');
17
17
  const JDK_FIX = `install JDK 17 ('brew install openjdk@17'), or set ${JAVA_HOME_ENV} to a JDK 17 home`;
18
18
  const INSTALL_LOCK_WAIT_MS = 15 * 60_000;
19
+ const JAVA_SETTINGS_TIMEOUT_MS = 30_000;
20
+ const JAVA_HOME_TIMEOUT_MS = 10_000;
21
+ const BREW_PREFIX_TIMEOUT_MS = 10_000;
22
+ const UNZIP_TIMEOUT_MS = 10 * 60_000;
23
+ const QUARANTINE_TIMEOUT_MS = 60_000;
24
+ const VERSION_TIMEOUT_MS = 120_000;
25
+ /** The longest findJdk17 waits with the system's search: two JDKs' settings, java_home and brew. */
26
+ export const JDK_LOOKUP_MS = 2 * JAVA_SETTINGS_TIMEOUT_MS + JAVA_HOME_TIMEOUT_MS + BREW_PREFIX_TIMEOUT_MS;
27
+ /** The longest ensureMaestro waits on anything but the download, its checksum and another process's install: the JDK, then unpacking. */
28
+ export const INSTALL_WAITS_MS = JDK_LOOKUP_MS + UNZIP_TIMEOUT_MS + QUARANTINE_TIMEOUT_MS + VERSION_TIMEOUT_MS;
19
29
  export function dataDir(env) {
20
30
  const xdg = env.XDG_DATA_HOME;
21
31
  const base = xdg && path.isAbsolute(xdg) ? xdg : path.join(env.HOME ?? os.homedir(), '.local', 'share');
@@ -79,7 +89,7 @@ async function javaSettings(home) {
79
89
  const java = path.join(home, 'bin', 'java');
80
90
  if (!isExecutable(java))
81
91
  return { spec: undefined, javaHome: undefined };
82
- const ran = await runCommand(java, ['-XshowSettings:properties', '-version'], { timeoutMs: 30_000 });
92
+ const ran = await runCommand(java, ['-XshowSettings:properties', '-version'], { timeoutMs: JAVA_SETTINGS_TIMEOUT_MS });
83
93
  const text = `${ran.stdout}\n${ran.stderr}`;
84
94
  return {
85
95
  spec: /^\s*java\.specification\.version = (\S+)/m.exec(text)?.[1],
@@ -89,7 +99,7 @@ async function javaSettings(home) {
89
99
  export const JAVA_HOME_TOOL = '/usr/libexec/java_home';
90
100
  /** The JDK 17 macOS has registered. Without -F, java_home prints the default JDK when none matches. */
91
101
  export async function registeredJdk17(tool = JAVA_HOME_TOOL) {
92
- const found = await runCommand(tool, ['-F', '-v', '17'], { timeoutMs: 10_000 });
102
+ const found = await runCommand(tool, ['-F', '-v', '17'], { timeoutMs: JAVA_HOME_TIMEOUT_MS });
93
103
  return found.code === 0 && found.stdout.trim() ? found.stdout.trim() : undefined;
94
104
  }
95
105
  /** The way maestro/build.sh looks: java_home -F -v 17, then Homebrew's openjdk@17. */
@@ -99,7 +109,7 @@ export const systemJdk17 = async () => {
99
109
  return { home: registered, origin: `${JAVA_HOME_TOOL} -F -v 17` };
100
110
  const prefixes = ['/opt/homebrew/opt/openjdk@17', '/usr/local/opt/openjdk@17'];
101
111
  if (!prefixes.some(prefix => isExecutable(path.join(prefix, 'bin', 'java')))) {
102
- const brew = await runCommand('brew', ['--prefix', 'openjdk@17'], { timeoutMs: 10_000 });
112
+ const brew = await runCommand('brew', ['--prefix', 'openjdk@17'], { timeoutMs: BREW_PREFIX_TIMEOUT_MS });
103
113
  if (brew.code === 0 && brew.stdout.trim())
104
114
  prefixes.unshift(brew.stdout.trim());
105
115
  }
@@ -148,21 +158,71 @@ export async function sha256Of(file) {
148
158
  return hash.digest('hex');
149
159
  }
150
160
  const manualFix = (release) => `download ${release.url} yourself and run '${CLI} driver install --from <that zip>'`;
151
- export const httpsDownload = async (release, dir) => {
152
- fs.mkdirSync(dir, { recursive: true });
153
- const fetchTo = async (url, file) => {
154
- const response = await fetch(url);
155
- if (!response.ok || !response.body) {
156
- throw new DriverError(`downloading ${url} failed: HTTP ${String(response.status)}`, `retry, or ${manualFix(release)}`);
161
+ // Node's fetch rejects with TypeError('fetch failed') and puts undici's or the socket's error code in its cause.
162
+ const CONNECT_ERRORS = new Set([
163
+ 'UND_ERR_CONNECT_TIMEOUT',
164
+ 'ECONNREFUSED',
165
+ 'ECONNRESET',
166
+ 'ETIMEDOUT',
167
+ 'ENOTFOUND',
168
+ 'EAI_AGAIN',
169
+ 'ENETUNREACH',
170
+ 'EHOSTUNREACH',
171
+ ]);
172
+ function causeOf(error) {
173
+ const cause = error instanceof Error ? error.cause : undefined;
174
+ return typeof cause === 'object' && cause !== null ? cause : undefined;
175
+ }
176
+ function isConnectError(error) {
177
+ const code = causeOf(error)?.code;
178
+ return typeof code === 'string' && CONNECT_ERRORS.has(code);
179
+ }
180
+ function reasonOf(error) {
181
+ const cause = causeOf(error)?.message;
182
+ return typeof cause === 'string' && cause !== '' ? `${messageOf(error)}: ${cause}` : messageOf(error);
183
+ }
184
+ /** Downloads the release zip and its checksum file, trying a download once more when it couldn't connect. */
185
+ export function httpsDownloader(options = {}) {
186
+ const get = options.fetch ?? ((url) => fetch(url));
187
+ const connect = async (url) => {
188
+ try {
189
+ return await get(url);
190
+ }
191
+ catch (error) {
192
+ if (!isConnectError(error))
193
+ throw error;
194
+ await new Promise(resolve => setTimeout(resolve, options.retryPauseMs ?? 2000));
195
+ return await get(url);
157
196
  }
158
- await pipeline(Readable.fromWeb(response.body), fs.createWriteStream(file));
159
197
  };
160
- const zip = path.join(dir, release.asset);
161
- await fetchTo(release.url, zip);
162
- const checksumFile = `${zip}.sha256`;
163
- await fetchTo(`${release.url}.sha256`, checksumFile);
164
- return { zip, checksumFile };
165
- };
198
+ return async (release, dir) => {
199
+ fs.mkdirSync(dir, { recursive: true });
200
+ const fetchTo = async (what, url, file) => {
201
+ const failed = (reason) => new DriverError(`downloading ${what} from ${url} failed: ${reason}`, `retry, or ${manualFix(release)}`);
202
+ let response;
203
+ try {
204
+ response = await connect(url);
205
+ }
206
+ catch (error) {
207
+ throw failed(reasonOf(error));
208
+ }
209
+ if (!response.ok || !response.body)
210
+ throw failed(`HTTP ${String(response.status)}`);
211
+ try {
212
+ await pipeline(Readable.fromWeb(response.body), fs.createWriteStream(file));
213
+ }
214
+ catch (error) {
215
+ throw failed(reasonOf(error));
216
+ }
217
+ };
218
+ const zip = path.join(dir, release.asset);
219
+ await fetchTo(`Maestro ${release.version}`, release.url, zip);
220
+ const checksumFile = `${zip}.sha256`;
221
+ await fetchTo(`the checksum of Maestro ${release.version}`, `${release.url}.sha256`, checksumFile);
222
+ return { zip, checksumFile };
223
+ };
224
+ }
225
+ export const httpsDownload = httpsDownloader();
166
226
  async function verify(release, downloaded) {
167
227
  const refuse = (problem) => new DriverError(`${problem}; refusing to install Maestro ${release.version}`, `retry the install, since a download can arrive damaged. If the same hash comes back, the release asset no longer matches what this ${TOOL} pins, so upgrade ${TOOL}. A zip given with --from must be the pinned build itself.`);
168
228
  let size;
@@ -188,13 +248,13 @@ async function verify(release, downloaded) {
188
248
  }
189
249
  /** macOS's unzip copies a quarantined zip's com.apple.quarantine to every file it unpacks, and Gatekeeper can block those files. */
190
250
  async function clearQuarantine(dir) {
191
- const cleared = await runCommand('xattr', ['-dr', 'com.apple.quarantine', dir], { timeoutMs: 60_000 });
251
+ const cleared = await runCommand('xattr', ['-dr', 'com.apple.quarantine', dir], { timeoutMs: QUARANTINE_TIMEOUT_MS });
192
252
  if (cleared.code !== 0) {
193
253
  throw new DriverError(`clearing macOS's quarantine from the unpacked Maestro failed (${cleared.error ?? `exit ${String(cleared.code)}`}): ${tail(cleared.stderr, 5)}`, `retry '${CLI} driver install'`);
194
254
  }
195
255
  }
196
256
  async function unpack(release, zip, into, jdk) {
197
- const unzipped = await runCommand('unzip', ['-q', zip, '-d', into], { timeoutMs: 10 * 60_000 });
257
+ const unzipped = await runCommand('unzip', ['-q', zip, '-d', into], { timeoutMs: UNZIP_TIMEOUT_MS });
198
258
  if (unzipped.code !== 0) {
199
259
  throw new DriverError(`unzip of ${path.basename(zip)} failed (${unzipped.error ?? `exit ${String(unzipped.code)}`}): ${tail(unzipped.stderr, 5)}`, `install unzip, then retry '${CLI} driver install'`);
200
260
  }
@@ -206,7 +266,7 @@ async function unpack(release, zip, into, jdk) {
206
266
  }
207
267
  const version = await runCommand(binary, ['--version'], {
208
268
  env: { ...process.env, JAVA_HOME: jdk.javaHome, MAESTRO_CLI_NO_ANALYTICS: '1', MAESTRO_DISABLE_UPDATE_CHECK: 'true' },
209
- timeoutMs: 120_000,
269
+ timeoutMs: VERSION_TIMEOUT_MS,
210
270
  });
211
271
  const printed = version.stdout.trim().split('\n').at(-1)?.trim();
212
272
  if (version.code !== 0 || printed !== release.version) {
@@ -20,9 +20,17 @@ export function imageOf(result) {
20
20
  return item?.data === undefined ? undefined : { data: item.data, mimeType: item.mimeType ?? 'image/jpeg' };
21
21
  }
22
22
  export const RUNNER_TOKEN_ENV = 'MAESTRO_RUNNER_TOKEN';
23
+ /**
24
+ * How long Maestro polls a fresh XCTest runner before it gives up, which Maestro reads from
25
+ * MAESTRO_DRIVER_STARTUP_TIMEOUT (milliseconds). 120 s is Maestro's own iOS default (SERVER_LAUNCH_TIMEOUT_MS). Maestro's
26
+ * Android driver reads the same variable for its own startup loops, with a 15 s default.
27
+ */
28
+ export const RUNNER_STARTUP_MS = 120_000;
29
+ export const INITIALIZE_TIMEOUT_MS = 60_000;
23
30
  /**
24
31
  * The environment Maestro runs in: JDK 17 first on PATH, the lane's runner token, and for a simulator an `adb` that
25
- * fails fast ahead of any real one; for an emulator, the SDK's own adb, emulator and avdmanager instead.
32
+ * fails fast ahead of any real one and the runner's startup time; for an emulator, the SDK's own adb, emulator and
33
+ * avdmanager instead.
26
34
  */
27
35
  export function maestroEnv(options, stubDir, tempDir) {
28
36
  const sdk = options.androidSdk;
@@ -41,7 +49,7 @@ export function maestroEnv(options, stubDir, tempDir) {
41
49
  MAESTRO_CLI_NO_ANALYTICS: '1',
42
50
  MAESTRO_DISABLE_UPDATE_CHECK: 'true',
43
51
  [RUNNER_TOKEN_ENV]: options.token,
44
- ...(sdk ? { ANDROID_HOME: sdk, ANDROID_SDK_ROOT: sdk } : {}),
52
+ ...(sdk ? { ANDROID_HOME: sdk, ANDROID_SDK_ROOT: sdk } : { MAESTRO_DRIVER_STARTUP_TIMEOUT: String(RUNNER_STARTUP_MS) }),
45
53
  };
46
54
  env.MAESTRO_OPTS = [options.env.MAESTRO_OPTS, `-Djava.io.tmpdir=${tempDir}`].filter(Boolean).join(' ');
47
55
  return env;
@@ -108,7 +116,7 @@ export class MaestroChild {
108
116
  });
109
117
  });
110
118
  }
111
- static async start(options, timeoutMs = 60_000) {
119
+ static async start(options, timeoutMs = INITIALIZE_TIMEOUT_MS) {
112
120
  const child = new MaestroChild(options);
113
121
  try {
114
122
  await child.request('initialize', { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'agentlane-driver', version: '1' } }, timeoutMs);
@@ -254,7 +254,7 @@ export class DriverSession {
254
254
  throw error;
255
255
  return {
256
256
  ok: false,
257
- error: `Maestro's session failed during the run and the flow was not sent again (${error.kind}): ${error.message}`,
257
+ error: `Maestro's session failed during the run and the flow was not sent again (${error.kind}): ${error.detail}`,
258
258
  };
259
259
  }
260
260
  }
@@ -1,20 +1,47 @@
1
1
  import { isAlive, killGroup } from "./exec.js";
2
- import { CallTimeout, ChildGone, MaestroChild, textOf } from "./maestro-child.js";
2
+ import { CallTimeout, ChildGone, INITIALIZE_TIMEOUT_MS, MaestroChild, RUNNER_STARTUP_MS, textOf, } from "./maestro-child.js";
3
3
  import { listeningPorts, processRows, runnersOn } from "./runner.js";
4
4
  /** A Maestro session that failed again after one restart, or a call that can't safely be retried. */
5
5
  export class SessionFailure extends Error {
6
6
  name = 'SessionFailure';
7
7
  kind;
8
8
  attempts;
9
- constructor(kind, attempts) {
9
+ /** What the caller can do next, when the failure has a known way forward. */
10
+ advice;
11
+ constructor(kind, attempts, advice) {
10
12
  super(attempts.join('; then '));
11
13
  this.kind = kind;
12
14
  this.attempts = attempts;
15
+ this.advice = advice;
16
+ }
17
+ /** The attempts, then the advice when there is any. */
18
+ get detail() {
19
+ return this.advice === undefined ? this.message : `${this.message}. ${this.advice}`;
13
20
  }
14
21
  }
15
22
  const DEFAULT_TIMEOUTS = { inspect_screen: 60_000, take_screenshot: 60_000, run: 600_000 };
23
+ /** How long a call to a Maestro that has already answered one may take. */
24
+ export function warmCallMs(name) {
25
+ return DEFAULT_TIMEOUTS[name] ?? 60_000;
26
+ }
27
+ /**
28
+ * The longest an iOS call can take before it answers or fails: Maestro's start and a first call that waits for the
29
+ * XCTest runner, twice when a timed-out call is retried on a fresh Maestro.
30
+ */
31
+ export function longestIosCallMs(name, options) {
32
+ const once = INITIALIZE_TIMEOUT_MS + warmCallMs(name) + RUNNER_STARTUP_MS;
33
+ return options.retry ? 2 * once : once;
34
+ }
16
35
  // Maestro reports a device it lost this way, and a fresh session reaches it again.
17
36
  const UNREACHABLE = /Device became unreachable/i;
37
+ // Maestro's LocalXCTestInstaller.start() throws this, with advice to raise MAESTRO_DRIVER_STARTUP_TIMEOUT, when the
38
+ // runner hasn't answered within that time.
39
+ const RUNNER_NOT_READY = /iOS driver not ready in time/i;
40
+ const MAESTRO_STARTUP_ADVICE = /,?\s*consider increasing timeout by configuring MAESTRO_DRIVER_STARTUP_TIMEOUT env variable/i;
41
+ const RUNNER_NOT_READY_ADVICE = 'The next call starts a fresh Maestro and XCTest runner';
42
+ function runnerNotReady(text) {
43
+ return `${text.replace(MAESTRO_STARTUP_ADVICE, '')} (the XCTest runner didn't answer within ${String(RUNNER_STARTUP_MS / 1000)} s)`;
44
+ }
18
45
  // Maestro's MCP server says this when it opens a session for a device adb doesn't list at that moment. An emulator's
19
46
  // adb transport drops now and then; the next call rebuilds the session (patch 0002) and reinstalls the driver.
20
47
  const NOT_CONNECTED = /Device with id \S+ is not connected/i;
@@ -27,6 +54,7 @@ export class Supervisor {
27
54
  options;
28
55
  starting;
29
56
  current;
57
+ answered;
30
58
  runnerPid;
31
59
  startedAt;
32
60
  watch;
@@ -142,7 +170,7 @@ export class Supervisor {
142
170
  if (this.lost !== undefined)
143
171
  attempts.push(this.lost);
144
172
  this.lost = undefined;
145
- const timeoutMs = this.options.timeouts?.[name] ?? DEFAULT_TIMEOUTS[name] ?? 60_000;
173
+ const limitMs = this.options.timeouts?.[name] ?? warmCallMs(name);
146
174
  for (let attempt = 0; attempt < 2; attempt++) {
147
175
  let child;
148
176
  try {
@@ -156,6 +184,8 @@ export class Supervisor {
156
184
  }
157
185
  throw new SessionFailure('start-failed', attempts);
158
186
  }
187
+ const waitsForRunner = this.options.platform === 'ios' && child !== this.answered;
188
+ const timeoutMs = waitsForRunner ? limitMs + (this.options.runnerStartupMs ?? RUNNER_STARTUP_MS) : limitMs;
159
189
  let result;
160
190
  try {
161
191
  result = await child.callTool(name, { ...args, device_id: this.options.deviceId }, timeoutMs);
@@ -164,6 +194,10 @@ export class Supervisor {
164
194
  if (error instanceof CallTimeout) {
165
195
  attempts.push(error.message);
166
196
  await this.restart(error.message);
197
+ if (waitsForRunner && options.retry && attempt === 0 && !this.stopping) {
198
+ respawned = true;
199
+ continue;
200
+ }
167
201
  throw new SessionFailure('timeout', attempts);
168
202
  }
169
203
  if (error instanceof ChildGone) {
@@ -177,6 +211,15 @@ export class Supervisor {
177
211
  }
178
212
  throw error;
179
213
  }
214
+ if (result.isError && waitsForRunner && RUNNER_NOT_READY.test(textOf(result))) {
215
+ attempts.push(runnerNotReady(textOf(result)));
216
+ await this.restart(textOf(result));
217
+ if (options.retry && attempt === 0 && !this.stopping) {
218
+ respawned = true;
219
+ continue;
220
+ }
221
+ throw new SessionFailure('timeout', attempts, RUNNER_NOT_READY_ADVICE);
222
+ }
180
223
  if (result.isError && NOT_CONNECTED.test(textOf(result))) {
181
224
  attempts.push(textOf(result));
182
225
  this.log(`${name}: ${textOf(result)}`);
@@ -201,6 +244,8 @@ export class Supervisor {
201
244
  this.startedAt = undefined;
202
245
  }
203
246
  await this.adoptRunner();
247
+ if (!result.isError || this.runnerPid !== undefined)
248
+ this.answered = child;
204
249
  return { result, respawned };
205
250
  }
206
251
  throw new SessionFailure('session-died', attempts);
package/dist/processes.js CHANGED
@@ -3,6 +3,7 @@ import fs from 'node:fs';
3
3
  const LSTART = String.raw `[A-Z][a-z]{2} [A-Z][a-z]{2} +\d{1,2} \d{2}:\d{2}:\d{2} \d{4}`;
4
4
  const START_LINE = new RegExp(String.raw `^\s*(\d+)\s+(${LSTART})\s*$`);
5
5
  const RUNNING_LINE = new RegExp(String.raw `^\s*(\d+)\s+(\S+)\s+(${LSTART})\s*$`);
6
+ const PARENTED_LINE = new RegExp(String.raw `^\s*(\d+)\s+(\d+)\s+(\S+)\s+(${LSTART})\s*$`);
6
7
  const INFO_LINE = new RegExp(String.raw `^\s*(\d+)\s+(\d+)\s+(${LSTART})\s?(.*)$`);
7
8
  const START_ONLY = new RegExp(`^${LSTART}$`);
8
9
  function normalizeStart(lstart) {
@@ -68,6 +69,24 @@ export function runningStartTimes(pids) {
68
69
  }
69
70
  return table;
70
71
  }
72
+ /** The parent pids and start times of those of `pids` still running. A zombie has exited, though ps lists it until it is reaped. */
73
+ export function runningWithParents(pids) {
74
+ const wanted = wantedPids(pids);
75
+ if (wanted.length === 0)
76
+ return new Map();
77
+ const lines = ps('pid=,ppid=,stat=,lstart=', wanted);
78
+ if (!lines)
79
+ return undefined;
80
+ const table = new Map();
81
+ for (const line of lines) {
82
+ const m = PARENTED_LINE.exec(line);
83
+ if (!m?.[1] || !m[2] || !m[3] || !m[4])
84
+ return undefined;
85
+ if (!m[3].startsWith('Z'))
86
+ table.set(Number(m[1]), { ppid: Number(m[2]), start: normalizeStart(m[4]) });
87
+ }
88
+ return table;
89
+ }
71
90
  export const systemProcesses = {
72
91
  startTimes(pids) {
73
92
  const wanted = wantedPids(pids);
@@ -134,6 +153,17 @@ export function killGroup(pgid, signal = systemSignaller) {
134
153
  return false;
135
154
  }
136
155
  }
156
+ const MAX_CHAIN = 32;
157
+ /** `pid` and the processes above it, nearest first, as far as `table` can read them, stopping before pid 1. */
158
+ export function* chainFrom(table, pid) {
159
+ for (let at = pid, read = 0; at > 1 && read < MAX_CHAIN; read++) {
160
+ const info = table.info(at);
161
+ if (!info)
162
+ return;
163
+ yield info;
164
+ at = info.ppid;
165
+ }
166
+ }
137
167
  export function identityOf(table, pid) {
138
168
  const start = table.startTimes([pid])?.get(pid);
139
169
  return start === undefined ? undefined : { pid, start };
@@ -2,7 +2,7 @@ import fs from 'node:fs';
2
2
  import os from 'node:os';
3
3
  import path from 'node:path';
4
4
  import { envName } from "../name.js";
5
- import { identityOf } from "../processes.js";
5
+ import { chainFrom, identityOf } from "../processes.js";
6
6
  import { UsageError } from "./refusal.js";
7
7
  export const AGENTS = ['claude', 'codex', 'cursor', 'copilot', 'gemini', 'antigravity'];
8
8
  const SIGNATURES = {
@@ -172,17 +172,18 @@ export function isCodexDaemon(info, home) {
172
172
  const listensOnSocket = args.some((arg, i) => arg.startsWith('--listen=unix://') || (arg === '--listen' && (args[i + 1] ?? '').startsWith('unix://')));
173
173
  return listensOnSocket || args.includes('--managed-daemon');
174
174
  }
175
- function sessionAncestors(table, selfPid, home) {
175
+ /**
176
+ * `pid` and the processes above it that belong to its session, nearest first. The walk stops before a Codex app-server
177
+ * daemon, since one daemon runs the commands of every Codex TUI and outlives the TUI that started it, so nothing above
178
+ * it belongs to the session.
179
+ */
180
+ export function sessionChain(table, pid, env) {
181
+ const home = codexHome(env);
176
182
  const ancestors = [];
177
- let pid = table.info(selfPid)?.ppid ?? 0;
178
- while (pid > 1 && ancestors.length < 32) {
179
- const info = table.info(pid);
180
- if (!info)
181
- break;
183
+ for (const info of chainFrom(table, pid)) {
182
184
  if (isCodexDaemon(info, home))
183
185
  return { ancestors, underCodexDaemon: true };
184
186
  ancestors.push(info);
185
- pid = info.ppid;
186
187
  }
187
188
  return { ancestors, underCodexDaemon: false };
188
189
  }
@@ -258,7 +259,7 @@ export function resolveOwner(env, table, selfPid = process.pid) {
258
259
  return { kind: 'process', process: identity, sessionId: null, threadId: null };
259
260
  }
260
261
  const sessionId = present(env, 'CLAUDE_CODE_SESSION_ID');
261
- const { ancestors: chain, underCodexDaemon } = sessionAncestors(table, selfPid, codexHome(env));
262
+ const { ancestors: chain, underCodexDaemon } = sessionChain(table, table.info(selfPid)?.ppid ?? 0, env);
262
263
  const identity = (info) => ({ pid: info.pid, start: info.start });
263
264
  const threadId = present(env, 'CODEX_THREAD_ID');
264
265
  const claudePid = present(env, 'CLAUDE_PID');
@@ -1,7 +1,8 @@
1
1
  import { spawn, spawnSync } from 'node:child_process';
2
2
  import fs from 'node:fs';
3
3
  import path from 'node:path';
4
- import { runningStartTimes, systemProcesses } from "../processes.js";
4
+ import { isAlive } from "../driver/exec.js";
5
+ import { runningStartTimes, runningWithParents, systemProcesses } from "../processes.js";
5
6
  const SEARCH_PATH = `${process.env.PATH ?? ''}:/usr/sbin:/usr/bin:/bin:/sbin`;
6
7
  function run(command, args) {
7
8
  const result = spawnSync(command, args, {
@@ -98,6 +99,8 @@ function deliver(target, signal) {
98
99
  export const realServiceSystem = {
99
100
  processes: systemProcesses,
100
101
  running: runningStartTimes,
102
+ runningWithParents,
103
+ exists: isAlive,
101
104
  spawnGroup(command, options) {
102
105
  fs.mkdirSync(path.dirname(options.log), { recursive: true });
103
106
  fs.appendFileSync(options.log, `--- ${new Date().toISOString()} start: ${command}\n`);
package/dist/up/exec.js CHANGED
@@ -10,7 +10,7 @@ import { describeRestored, restoreReverse } from "../devices/android.js";
10
10
  import { laneEnvironment, webUrl } from "../hooks/env.js";
11
11
  import { CLI, TOOL } from "../name.js";
12
12
  import { asMobile, findProjectConfig, loadLaneConfig } from "../project/config.js";
13
- import { describeOwner, resolveOwner } from "../registry/owner.js";
13
+ import { describeOwner, resolveOwner, sessionChain } from "../registry/owner.js";
14
14
  import { stateDir } from "../registry/paths.js";
15
15
  import { NotClaimed, Refusal, UsageError } from "../registry/refusal.js";
16
16
  import { Registry } from "../registry/registry.js";
@@ -54,17 +54,36 @@ async function restoreDeviceNetwork(deps, config, lane, dir) {
54
54
  }
55
55
  }
56
56
  export const CALLER_POLL_MS = 1000;
57
+ export const CALLER_START_CHECK_MS = 10_000;
57
58
  export const STOP_GRACE_MS = 5000;
58
59
  const STOP_CHECK_MS = 100;
59
60
  const CALLER_GONE_EXIT = 128 + os.constants.signals.SIGHUP;
60
61
  function callerOf(deps) {
62
+ const { system, clock } = deps;
61
63
  const parentPid = deps.parentPid ?? (() => process.ppid);
62
64
  const pid = parentPid();
63
- return { gone: () => parentPid() !== pid };
65
+ const above = sessionChain(system.processes, pid, deps.env).ancestors;
66
+ let startsReadAt = clock.now();
67
+ const startsDue = () => above.length > 0 && clock.now() - startsReadAt >= CALLER_START_CHECK_MS;
68
+ return {
69
+ gone: () => {
70
+ if (parentPid() !== pid || above.some(p => !system.exists(p.pid)))
71
+ return true;
72
+ if (!startsDue())
73
+ return false;
74
+ startsReadAt = clock.now();
75
+ const now = system.runningWithParents(above.map(p => p.pid));
76
+ return now !== undefined && above.some(p => endedOrReplaced(p, now.get(p.pid)));
77
+ },
78
+ };
79
+ }
80
+ function endedOrReplaced(recorded, now) {
81
+ return now === undefined || (now.start !== recorded.start && now.ppid !== recorded.ppid);
64
82
  }
65
83
  /**
66
- * Runs a command with the lane's environment and returns its exit code. When the process that started exec goes away
67
- * while the command runs, exec ends the command and every process below it, and returns 129 as a hung-up command would.
84
+ * Runs a command with the lane's environment and returns its exit code. When the process that started exec, or any
85
+ * process above it, goes away while the command runs, exec ends the command and every process below it, and returns
86
+ * 129 as a hung-up command would.
68
87
  */
69
88
  export async function execInLane(deps, argv) {
70
89
  const [command, ...args] = argv;
@@ -4,6 +4,7 @@ import path from 'node:path';
4
4
  import { promisify } from 'node:util';
5
5
  import { androidToolchain, CacheKeyError, xcodeVersion } from "../cache/key.js";
6
6
  import { findAndroidSdk } from "../devices/emulator.js";
7
+ import { SimctlTimeout } from "../devices/simctl.js";
7
8
  import { registeredJdk17 } from "../driver/install.js";
8
9
  import { HOOK_LOCALE, JAVA_HOME_ENV } from "../hooks/env.js";
9
10
  import { runCheck } from "../hooks/run.js";
@@ -169,9 +170,11 @@ export async function toolchainFindings(config, deps, stopAtFirst) {
169
170
  catch (error) {
170
171
  const fix = error instanceof UsageError
171
172
  ? error.fix
172
- : android
173
- ? 'install a system image: sdkmanager "system-images;android-36;google_apis;arm64-v8a"'
174
- : 'install an iOS simulator runtime: xcodebuild -downloadPlatform iOS';
173
+ : error instanceof SimctlTimeout
174
+ ? "run 'xcrun simctl list runtimes' to see whether simctl answers, then try again"
175
+ : android
176
+ ? 'install a system image: sdkmanager "system-images;android-36;google_apis;arm64-v8a"'
177
+ : 'install an iOS simulator runtime: xcodebuild -downloadPlatform iOS';
175
178
  return Promise.resolve({ name: runtimeName, ok: false, detail: message(error), fix });
176
179
  }
177
180
  },
package/dist/up-cli.js CHANGED
@@ -66,8 +66,9 @@ export const UP_HELP = {
66
66
  With a driver block, 'maestro' there is the toolkit's build on this lane's device,
67
67
  with JDK 17 and the lane's runner token: ${TOOL} exec -- maestro test <flow.yaml>
68
68
  Without one, or with an invalid config or no running device, 'maestro' says why and
69
- runs nothing. When the process that ran exec exits, exec stops the command and every
70
- process under it (SIGTERM, then SIGKILL 5 s later) and exits 129.
69
+ runs nothing. If the process that ran exec, or any process above it, exits, exec
70
+ stops the command and every process under it (SIGTERM, then SIGKILL 5 s later) and
71
+ exits 129. Under Codex, its shared daemon and the processes above it don't count.
71
72
  `,
72
73
  doctor: ` doctor Is this worktree's instance worth driving? Checks the lane, toolchain, device,
73
74
  app, launch, services and hygiene, read-only; exit 1 names each fix. A lane up --no-app
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agentlane",
3
- "version": "0.6.0",
3
+ "version": "0.6.1",
4
4
  "description": "Run several AI coding agents on one machine, each with its own ports, dev servers, database and simulator, emulator or browser. Works with Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI and Antigravity, on web, iOS and Android.",
5
5
  "keywords": [
6
6
  "ai-agents",