14 Commits
Author SHA1 Message Date
Vojtech NovakandClaude Opus 5.5 c42ae75568 [agent-cli] dev:stop stops the dev server a killed run left, proved by its run record (#243)
## Problem

After a `dev` CLI process gets SIGKILL, its Metro keeps serving the port
with no lock. `dev:stop` and `dev:stop --eas` report "not running" and
leave it up; only `dev:stop --port <n> --force` stops it. SIGKILL cannot
be caught, and the lock dies with the process.

## Fix

- The lock holder keeps a run record beside the lock:
`.expo/agent-cli-dev-run.json`, with its pid, the port, and the pid that
listens there (read with `lsof`, never a request to Metro). The lock
handle writes it once Metro reported its port, only for the port the
lock answers for, only when one process listens there, and not after the
dev server exited. Release removes it (the `finally` and the `exit`
hook), and so does a `dev:stop` that stopped the run through its lock,
since a Windows stop (`taskkill /F`) skips the holder's cleanup. A
SIGKILL skips all of these, so the record outlives a killed run.
- A lock-less server is a killed run's orphan when the record's pid is
gone (a zombie counts as gone), the only listener on the record's port
is the pid the record names, and its `/status` names this project. Two
listeners on one port (`expo start --localhost` on `[::1]` beside a
Metro on `127.0.0.1`) prove neither. A Metro a person started (`npx expo
start`) is another process, even on the port of a run that died with its
own Metro (a closed terminal), so `dev:stop` stops it only with
`--force`, as on main. Judging the record only reads; `dev:stop` removes
a spent one.
- `dev:stop`, with no `--port` or with the record's port, signals the
orphan's pid without `--force` and reports `untracked: true`, `forced:
false`.
- A signal that cannot reach the process (another user's) is reported at
once, and the How line names its owner instead of `--signal SIGKILL`.

## Red test

`e2e/__tests__/stop-test.ts`, "after a SIGKILL of a foreground dev": a
real `dev --ios` with a listening stub Metro, SIGKILL of the CLI pid
only.
- "dev:stop stops the dev server it left with no lock, without --force",
with no flags and with `--port`: red on main (`stopped: false`, `port:
null`, the orphan still answers).
- "leaves a dev server started by hand running": a run dies with its
Metro and leaves its record, then a stub `expo start` with no agent-cli
parent takes that port. Green on main; red on a rule that matched the
record's port alone.
- "never takes a hand-started dev server on [::1] for the run that
served beside it" (darwin, in tier0-e2e-macos): red on a lookup that
took the first `lsof` pid.

Unit: `lock-test` and `publishPort-test` (the record's life, also with
no `--port`, where the note once came before the lock),
`untrackedDevServer-test` (the verdict table and a real zombie),
`stopAsync-test` (a signal that cannot be sent; a stop through the lock
ends the record).

## Live check

`apps/eas-example` (expo 58.0.5), real Metro, `dev --web --port 8395`,
at the top of this stack:
- Real Metro listens as one process on `*:8395`, so the record names it:
`{pid: 75684, port: 8395, serverPid: 75761}`.
- SIGKILL of the CLI pid only: pid 75761 kept serving. Plain `dev:stop`
printed `stopped: true, untracked: true, forced: false, signal:
SIGTERM`; pid 75761 was gone, nothing listened on 8395, and the record
was gone.
- A run killed together with its Metro (record left), then `npx expo
start --web --port 8395` by hand (pid 77558): `dev:stop` said
`not-running`, `dev:stop --port 8395` said `foreign-dev-server`, pid
77558 kept serving, and the spent record was removed.
- A run stopped through its lock removes its record.

## Watch

An orphan is found only through its record. A run killed before Metro
reported its port, one whose `exit` hook ran (an uncaught error) while
its Metro survived, or one followed by a run that serves elsewhere and
writes its own record, leaves no usable record, so that Metro counts as
anyone's server, as on main. Refusing to start beside an orphan, and one
record per port, were considered and rejected: the case is rare, and
losing the proof can only spare a server, never stop the wrong one (LLP
0004 §Daemonization).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <[email protected]>
2026-11-11 15:35:48 +01:00
Vojtech NovakandClaude Opus 5.5 63b7fe20d1 [agent-cli] One writer and one transition table for the dev run's lock (#276)
## Problem

The `dev` run's dev-server lock had seven write sites spread over
`holdLock`, `RunLock`, `runDevServerAsync` and `devAsync`. Each one knew
only part of the run's state. "The EAS open returned" came from two
sources: a promise and a lock field set two microtasks later.

## Fix

- `nextRunState` (`src/devLock/runState.ts`) decides every change, using
the table in llp/0004 §Dev-server lock. The run's state includes the
port the lock names, so the writer keeps nothing beside it.
- `RunLock` (`src/devLock/runLock.ts`) is the only code that takes,
updates or releases a lock. Each old write site is now an event on it:
the take before a build, a step's publish, Metro's port report,
`/status` answering, the EAS open starting and returning, Metro's exit,
and the run's end.
- `withRunLockAsync` ends the lock of a `start` run and of a `dev` run.
- `runDevServerAsync` sends Metro's exit for `start` and `dev` alike,
after its port watch, so every event of a step lands before it. One
`/status` wait serves the build step (`serving`) and the open.
- `holdLock` is now `publishPort`. It resolves a step's port, and it
also does the take before a build step.
- `src/dev/runLock.ts` is now `runSteps.ts`: the plan rule for the take,
and the signal handling.

Nothing a lock reader sees changes. Each cell of the table matches what
the code did before.

One behavior changes outside the lock: a `/status` answer that arrives
after Metro exited no longer opens the app. Before, it still did, and an
EAS open there could start a billed session for a Metro that is gone. A
step also tells its caller a port only after the lock names it, so the
open and the `/status` wait start after the take (a few milliseconds).

## Red test

`runState-test` from the PR below: 99 cells, all green here.
`runLock-test`: an illegal publish changes nothing and is on the debug
stream (read from a real `2g` event log), and `withRunLockAsync`
releases the lock when the run returns or throws (read through the
socket). `publishPort-test` keeps the wire test of `easOpenFinished`.

## Live check

At the top of the stack, after `bun run build`: e2e `dev-eas-test`,
`dev-detach-test`, `stop-test`, `dev-test`, `wrapper-test` and
`status-test`. The unit suite, typecheck and lint pass. CI runs the four
live EAS sessions.

## Watch

No unit test fails if `runDevServerAsync` stops sending `server-exited`
or `status-answered`, or if `devAsync` stops sending the EAS open
events; `dev-test` and `dev-eas-test` cover them. A `run:*` step whose
lock take failed, because another process holds the lock, now polls
`/status` too; its answer changes nothing, because the run holds no
lock.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <[email protected]>
2026-11-11 11:35:30 +01:00
Vojtech NovakandClaude Opus 5.5 1650776a2a [agent-cli] Dev run lock transitions: design and red table test (#275)
## Problem

Seven places write the `dev` run's dev-server lock, and each knows only
part of the run's state: the take before a build, the publish and the
republish of the dev-server step, the port watch, the `easOpenFinished`
callback, `serve()` once `/status` answers, and `finish()` /
`release()`. No one place decides what a given event does in a given
phase. Kudo's review of the dev-lock phases found four bugs of that
kind: a lock left `serving` during the session cleanup, a port retry
after the EAS open started, a signal before a step's child spawned, and
a building run that ended reported as "never published a lock".

## Fix (design only in this PR)

llp/0004 §Dev-server lock gets one transition table. The run's state is
its phase (`unlocked`, `building`, `serving`, `finishing`, `released`),
its EAS open (`none` / `running` / `returned`) and, while it holds the
lock, the port the lock names. There are eight events: `published`,
foreign port, Metro reports a port, `/status` answers, EAS open starts,
EAS open returns, Metro exits, run ends. The table has one row per phase
and EAS open, so no cell needs prose. An illegal pair changes nothing
and is a debug event; the lock still never fails a run.

`src/devLock/runState.ts` declares the states and events, with
`nextRunState` as a stub. The next PR implements it, makes one `RunLock`
(in `src/devLock/`) the only writer of the lock, and turns each write
site into an event. No behavior changes: every cell matches what the
code does today.

## Red test

`src/devLock/__tests__/runState-test.ts`: one case per cell, 99 cases,
with the port each event leaves the lock naming. Typed cell builders, no
casts. All fail here, on the stub.

## Live check

None for this PR. The next PR runs `dev-eas-test`, `dev-detach-test`,
`stop-test`, `status-test` and `dev-test` as the proof of no behavior
change.

## Watch

The table sees only the EAS open. The rule "no busy-port retry after any
open, local or on EAS" stays in the run (`openStarted` in `devAsync`): a
local open has no exit work, and the lock must not say `finishing` for
it.

## Open questions

- A run that released its lock and still stops its EAS session has no
phase. A `dev:stop` that signalled it waits for process and lock to go,
so a slow `simulator:stop` can end `still-running` at `--timeout`. A
fourth phase would cover it.
- A signal during `finishing` is stored and does nothing until the open
returns. Should a second signal end the open?

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <[email protected]>
2026-11-11 11:35:30 +01:00
Vojtech NovakandClaude Opus 5.5 fc4b12de51 [agent-cli] A dev run says building on its lock, stops on a signal, and is followed by a detached re-run (#240)
## Feature

A `dev` run whose plan builds before it serves (`expo run:*`, a
prebuild, an install, an EAS build) now says so on its dev-server lock.
`status`, `dev:stop` and a detached parent read one fact, `phase:
"building"`, instead of guessing from log lines. A signal ends the step
it reaches, and the run starts no later step.

```sh
npx @expo/agent-cli dev --ios --detach
# exit 0: {"phase": "building", "pid": ..., "url": ...}
npx @expo/agent-cli dev --ios --detach --wait-ready
# waits; exit 22 DEV_DETACH_STILL_BUILDING at the deadline
```

## How

- **The run owns its lock.** `withRunLockAsync` takes the lock before
the first step with phase `building`, and releases it when the run ends.
`RunLock.serve()` changes it to `serving` once `/status` answers for
this project; the poll starts when the lock is published at the spawn,
so it does not wait for the port watch. `expo run:*` builds, starts
Metro, then installs, so its dev-server step also starts as `building`.
- **The lock is the one phase source.** The detach report, `status` and
`dev:stop` read it. The log-line phase guess is gone.
- **Detach.** Without `--wait-ready`, a building run reports at once
with exit 0. With `--wait-ready` it waits, and exits 22
`DEV_DETACH_STILL_BUILDING` at the deadline. A re-run beside a building
run reports it or follows it, and spawns nothing when that run ends in
its build (the build failure stays in the log). A lock that says
`finishing` after the spawn stops the parent with `DEV_DETACH_FAILED`
and points at `dev:stop --eas`.
- **Signals.** `RunSteps.stepAsync` marks each running step. A SIGINT or
SIGTERM while no step runs exits at once with 128 + signal. During a
step, the step's child ends it, and the run then stops with
`DEV_INTERRUPTED` before the next step, including the busy-port retry.
The run tracks steps explicitly because other code (the `2g` exit
cleanup) adds `once` signal listeners, so a listener count cannot tell
whether a step runs.
- The building lock names the run's EAS platform, so `dev:stop` during a
build reports it. `status` returns the step of a run that builds or
finishes before the device steps.

## Alternatives considered

- Keep reading the phase from the child's log: the install marker is not
captured when output goes to a terminal, so it fails in some output
modes.
- Infer a running step from the process's signal listeners: it broke as
soon as `2g` added its own `once` listeners.
- Make a plain `--detach` wait through a build: a build can take many
minutes, and the caller can choose `--wait-ready`.

## Verification

- Red test first for the last two changes:
- `dev-eas-test` "reports no dev server when the run it started lost
Metro before the lock was read" got `serving` with exit 0 before the
fix.
- `dev-test` "says serving once Metro answers after run:%s, with no port
report" (iOS and Android) still read `building` after 10 s before the
fix.
- New e2e cases on iOS and Android: SIGTERM during prebuild exits 143
with `DEV_INTERRUPTED` and starts no `run:*` step; the building-run
detach and re-run cases; a re-run reports the port the busy-port retry
took.
- `runLock-test`: a signal between steps exits at once; a signal during
a step lets it end first.
- Typecheck, lint and format pass; the unit suite passes. Related e2e
files pass, except `status` "starts nothing and exits 0", which fails
locally only with a global eas-cli 25.
- Not run on a real EAS Simulator session; CI runs only on the top PR of
the stack.

Watch item: a build that ignores SIGTERM keeps the run alive, because
the run waits for the running step to end.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <[email protected]>
2026-11-10 21:55:11 +01:00
Vojtech NovakandClaude Opus 5.5 f7de487ed4 [agent-cli] The dev run owns its lock and says finishing while its EAS open runs (#236)
## Bug fix

When Metro exits during a `dev --eas` run, the run still waits for its
EAS session start, and then binds that session. In that gap the run
released its lock. A `dev:stop` that came then reported `not-running`
with `lockHeld: false` and named no `dev:stop --eas`. A few moments
later the run bound a session that bills, and nothing pointed at it.
`dev:stop` used a 2 s grace period to guess at this state.

### Steps to reproduce

1. `npx @expo/agent-cli dev --ios --eas` in an Expo project.
2. End Metro while the EAS session start still runs.
3. `npx @expo/agent-cli dev:stop --json`: `reason: "not-running"`, no
`dev:stop --eas` follow-up.

## How

- **The run owns its lock.** One dev-server lock lives through the port
retry and the EAS exit work. After Metro exits while the EAS open has
not returned, the lock answers `phase: "finishing"`. The run reads
`easOpenFinished` from the lock and keeps no copy of it.
- **`dev:stop` reads the phase, not a grace period.** On a `finishing`
lock it reports the dev server stopped, sends no signal, and names
`dev:stop --eas` first. `dev:stop --eas` waits for the open, so it finds
the session. Its wait reads the lock once per poll.
- **Other readers.** A foreground or detached `dev` refuses to start
beside a finishing run. `status` names `dev:stop --eas`, and names `eas
simulator:stop --id` for a deleted worktree's session whenever this
project's lock is held.
- **One table of phases.** The refusal, the plan reason, the plan's
follow-up and port row, and `status` read one row per phase from
`src/dev/runPhase.ts`, in place of their own sentences.

## Alternatives considered

- Keep the grace period and make it longer: a session start can take
much longer than any fixed wait, and the lock already knows the answer.
- Keep a separate run-side flag for the EAS open: it could disagree with
what the lock answers.

## Verification

- Red test: `dev-eas-test` "answers a dev:stop that comes after Metro
exited while the session start runs". On main, `dev:stop` reports
`reason: "not-running"`, `lockHeld: false` and no `dev:stop --eas`
follow-up. It passes at the top of the stack.
- One table test covers the rows of the phase table. The grace-period
unit tests are replaced by cases that read the phase from the lock.
- Typecheck, lint and format pass; the unit suite passes. Related e2e
files pass, except `status` "starts nothing and exits 0", which fails
locally only with a global eas-cli 25.
- Not run on a real EAS Simulator session; CI runs only on the top PR of
the stack.

Watch item: a `finishing` lock blocks a new `dev` run until the session
start returns. The refusal names `dev:stop --eas`, instead of letting a
second session start.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <[email protected]>
2026-11-10 21:55:10 +01:00
Vojtech NovakandClaude Opus 5.5 408a871456 [agent-cli] The named-port watch keeps listening, so Metro's port after a long run:* build counts (#274)
## Bug fix

On `@expo/cli` 58, Metro sends its port as one `2g` event,
`metro:instantiate`. The `dev` run looks for that event in a loop (the
port watch). When it finds it, the lock says `portReported: true`.

When the `dev` arguments name a port, the lock is published at the
spawn, and the watch goes on in the background. That watch still gave up
after 20 s. With `expo run:ios` or `expo run:android`, Metro starts only
after the native build, which often takes minutes. So Metro sent its
port after the watch had stopped, and the lock said `portReported:
false` for the whole run.

### Steps to reproduce

1. Use an SDK 58 project with native folders, where `run:ios` takes more
than 20 s.
2. Run `npx @expo/agent-cli dev --ios`.
3. After Metro serves, read the lock: `portReported` is `false`.

## How

The named-port watch has no time limit now. It stops at the first report
from this project, or when the dev server stops. Nothing waits on this
watch, because the lock already answers, so it needs no limit.

The watch with no named port keeps its 20 s limit, because a caller
waits on that answer.

## Alternatives considered

- A longer limit: every limit is shorter than some build.

## Verification

- Red test first: `holdLock-test` "follows a report that comes after the
watch's timeout when the arguments name a port". On main it fails with
`portReported: false`. With the fix it passes.
- Typecheck, lint and format pass. All 5671 unit tests pass.

Watch item: when the run uses a `LOG_EVENTS` file and no report comes,
the run reads that file every 500 ms until the dev server stops.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 <[email protected]>
2026-11-10 20:49:09 +01:00
Vojtech NovakandClaude Opus 5.5 da29eb507a [agent-cli] dev --detach returns once Metro reports its port through 2g (#268)
## Bug fix

`dev --detach` returns about 20 s after the dev server is up.

### Terms

- **`2g`**: the event logger that `agent-cli` and `@expo/cli` use. A
process writes its events to one destination, in this order: its parent
over IPC, then the file that `LOG_EVENTS` names, then a session of its
own in `$TMPDIR/event-log-<uid>/`.
- **`2g` IPC env variables**: `__eventLogIpc`, `__eventLogProcessOrigin`
and `__eventLogDebug`. `2g` sets them in `process.env`, so every child
process sends its events through the parent's IPC socket. The socket
closes when the parent exits.
- **Background process**: the `agent-cli` process that `dev --detach`
starts with `detached: true`. It runs `expo start`, holds the dev-server
lock, and keeps running after `dev --detach` returns.
- **Dev-server lock**: a socket that the background process answers. It
tells other commands the pid, the port and the state of the dev server.

### Cause

`@expo/cli` 58 writes no `.expo/dev/logs/start.log`. It reports
`metro:instantiate { port }` through `2g` only. Two things broke:

1. Both `dev --detach` and the background process read the port only
from `start.log`. They found nothing, so both waited the 20 s
`PORT_WATCH_TIMEOUT_MS` fallback.
2. The background process inherited the `2g` IPC env variables of `dev
--detach`. Its events, and the events of its `expo start` child, went to
the `dev --detach` socket. When `dev --detach` exited, the socket closed
and the events were lost, Metro's port report included.

### Steps to reproduce

1. In an SDK 58 project, run `npx @expo/agent-cli dev --web --detach
--json`.
2. The command returns about 20 s after the dev server is up.

## How

1. **The background process gets a destination that outlives `dev
--detach`.** Before the spawn, `detachedEventLogEnv` removes the three
`2g` IPC env variables from the child's env. Without them, `2g` in the
background process uses its next destination:
- the caller's `LOG_EVENTS` file, when the caller had one (`2g` removes
`LOG_EVENTS` from `process.env`, so the code passes it again);
   - otherwise, a new `2g` session of its own.

Debug recording is passed on through a private env variable,
`__EXPO_AGENT_CLI_EVENT_DEBUG`. `LOG_DEBUG` would also print every event
into the detached log file.
2. **The lock holder reads Metro's report from that destination.** It
follows its own `2g` event log for `metro:instantiate`: `2g/api` `tap({
follow })` for a session, or a re-read of the `LOG_EVENTS` file. A
reported port whose `/status` names another project is skipped, because
two runs can share one `LOG_EVENTS` file.
3. **The lock tells `dev --detach` when the port is known.** The lock
has a new `portReported` flag. `dev --detach` polls the lock and returns
when the flag is true, or after the 20 s fallback. It reads no log.
4. The port source `'log'` is renamed `'reported'` (the `portSource`
field of `cli:dev_lock_acquired`). The stub `expo` in the e2e fixtures
reports its port through `2g`, as `@expo/cli` 58 does.

## Alternatives considered

- Filter reports by the `expo` child's pid: fails when `expo` starts
through `npx` or a Windows `.cmd` shim, where the event comes from a
grandchild.
- Read the port from `2g` session metadata: a child's
`updateEventLoggerMetadata` does not reach the session's `meta.json`.
- Receive the `expo` child's events on a pipe with `2g/api`
`captureEvents().spawnOptions()`, instead of reading this process's own
event log back. Tested live on the SDK 58 app: the event reaches the
pipe in 1.2 s when the project bin is spawned directly, and never when
`expo` starts through `npx expo`, because `npx` starts its command with
`stdio: 'inherit'`, which passes only the three standard streams (stdin,
stdout, stderr) and not the extra pipe at fd 3; the grandchild's `2g`
then writes to a file descriptor that is not the pipe and drops every
event. A project without an installed `expo` bin is exactly the `npx`
case; the Windows `.cmd` shim has the same shape. Rejected for the same
reason as the pid filter.

## Verification

- Live, SDK 58 app (`@expo/cli` 58.1.17), `dev --web --detach --json`:
**21.5 s on main, 2.8 s with this PR**. The background process kept a
live `2g` session with Metro's events after `dev --detach` exited.
- New e2e `dev-detach-test` "returns once the dev server reports its
port through 2g", for its own session and for the caller's `LOG_EVENTS`
file. Red before the fix (21 s).
- Unit, lint, typecheck and format pass. Local e2e fails only on
environment cases: a global `eas` 25 on this Mac, and a port held by
another local Metro.

Watch item: a foreground run on SDK 58 whose event log this CLI cannot
read back (`LOG_EVENTS` as a file descriptor, or a `2g` parent over IPC)
still waits the 20 s fallback. `discoverDevServer`, the `devAsync`
port-collision check and `dev-wait` still read `start.log`; they move in
follow-up PRs.

Follow-up: confirm instead of wait. The 20 s fallback still publishes an
unreported `arg` or `default` port on time alone, and `dev --detach`
accepts it on time alone. The foreground `dev` already confirms an `arg`
port by probing `/status` and checking the project-root header before it
opens the app. The lock holder can do the same and republish
`portReported: true` once `/status` answers, so the parent returns on
evidence in the IPC and fd cases too, and the 20 s stays only for a port
nothing answers on. It changes what `portReported` means, so it needs
its own LLP 0004 change.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <[email protected]>
2026-11-10 08:44:25 +01:00
Vojtech NovakandClaude Opus 5.5 ee0d6570b0 [agent-cli] [2] --wait-ready --eas waits for the session binding, and a re-run follows a child that still starts it (llp/0035 §Preserved sessions) (#186)
EAS session binding, part 2 of 2 (the session survives the dev run).
Stacked on #185 (`vonovak/eb-10-smoke-reuse`).

## Problem

`dev --eas --detach --wait-ready` returned before the EAS session was
ready, and its re-run could loop:

- It printed "Bundler ready" before the session existed (DF7).
- An expired lease beside a running EAS Metro was never renewed, so the
re-run waited and printed the same command again (DF34). A removed
binding file beside a live session gave the same loop (DF38).
- After a bind, the report said "nothing was started" (DF26).

This PR makes `--wait-ready` wait for the session binding, and a re-run
follows a child that still starts the session or binds it again.

## What changes

- With `--eas`, the parent of `--wait-ready` polls the binding registry
for the session. The default budget is 90 s
(`AGENT_CLI_EAS_SESSION_WAIT_MS`). At the deadline it exits 22 with
`DEV_DETACH_SESSION_PENDING`.
- The detached child prints its pid on line 1 of its log and sets
`easOpenFinished` on its lock when its EAS open returns.
- A re-run follows a child that is still in its start window
(`childStartsSessionSync`). A finished open, a binding that the child
made with an expired lease, or a removed binding file ends the start:
the re-run reopens and binds again.
- A re-run that binds a session on a running Metro says so, not "nothing
was started".

## Findings addressed

- DF7: `--wait-ready` returned "Bundler ready" before the session
existed.
- DF34: an expired lease beside a running EAS Metro was never renewed;
the re-run waited and repeated the same command.
- DF38: a removed binding file beside a live session and Metro gave the
same loop.
- DF26: the report after a bind said "nothing was started".
- Night-3 dogfood N3-05: every Android `--wait-ready --eas` exited 22
`DEV_DETACH_SESSION_PENDING` at 90 s and needed a re-run. An Android
session binds 105–120 s after the tunnel, so the session budget is 180
s. `AGENT_CLI_EAS_SESSION_WAIT_MS` still overrides it. A blocking call
can now take up to 120 s + 180 s.

## Tests red before this change

'the EAS session under --wait-ready' in detachAsync-test; the pid line
of childVerdict-test and devAsync-test; the easOpenFinished cases of
lock-test and holdLock-test; detachEasProgress-test; the wait-runs-out
case of detachAsync-test (180 s); e2e cloud-binding-test (a re-run
beside a child whose open finished).

## Verification

- `bun run typecheck`, `bunx vitest run` (5597 passed), `bun run format`
(no change).
- e2e: the full suite at the top of the stack (#187) shows only the 7
known failures, 918/925; this tree had no full run after the test
cleanup. A global eas-cli >= 25 on the dev machine causes them: plan ×2,
deploy, inspect-build-log ×2, project-shapes, status "starts nothing and
exits 0". The test-fix journal in the night log archive (link below) has
the per-PR e2e results.
- Live re-checks in the night run: DF7 (round 3), DF34 (round-5 QA V1),
DF38 (round-6 QA F1).

Night report (shared with the Expo organization):
https://claude.ai/artifact/FqHNamyfxLvKBzw9iPAi4x
Night log archive: https://claude.ai/artifact/XGcQ6a7ye5D2od1kwHkjau

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <[email protected]>
2026-10-23 20:32:38 +02:00
Vojtech NovakandClaude Opus 5.5 b32a0d2e5f [agent-cli] [2] dev:stop reports a finishing dev --eas run as stopped (llp/0035 §Preserved sessions) (#183)
EAS session binding, part 2 of 2 (the session survives the dev run).
Stacked on #166 (`vonovak/eas-4-preserved-session`).

**Question:** what does `dev:stop` say about a `dev --eas` run that
released Metro but still finishes its session start?

## What changes

- The dev-server lock names the run's EAS platform (`easPlatform`).
- A `dev --eas` pid that released its lock and its port and stays alive
for 2 s (`FINISHING_GRACE_MS`) is finishing. `dev:stop` reports it as
stopped, offers no SIGKILL, and names `dev:stop --eas`, because the
child may still bind the session its start returns.
- The wait ends after the grace period, not at the timeout. A run with
no EAS platform keeps `still-running`.
- The next `dev` follow-up keeps the platform and `--eas`: the lock's
platform first, then the session or row this stop acted on.

## Findings addressed

- Review round 1: finding 3 (the finishing branch applied to every run;
it is gated on the EAS lock and on a grace period), finding 2 (the lock
field stays, because it describes this run; the four-source fallback is
gone).
- Review round 2: 02-F9 (finishing is computed once in the wait and
carried to the report).

## Tests red before this change

The finishing cases of stopAsync-test, lock-test, holdLock-test,
startAsync-test.

## Verification

- `bun run typecheck`, `bunx vitest run` (5549 passed), `bun run format`
(no change).
- e2e: where the full suite ran on this stack, it shows only the 7 known
failures. A global eas-cli >= 25 on the dev machine causes them: plan
×2, deploy, inspect-build-log ×2, project-shapes, status "starts nothing
and exits 0". The test-fix journal in the night log archive (link below)
has the per-PR e2e results. No e2e run is recorded for this tree.

Night report (shared with the Expo organization):
https://claude.ai/artifact/FqHNamyfxLvKBzw9iPAi4x
Night log archive: https://claude.ai/artifact/XGcQ6a7ye5D2od1kwHkjau

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <[email protected]>
2026-10-23 20:32:37 +02:00
Vojtech NovakandClaude Fable 5.1 2f3eb45078 [agent-cli] prep for device binding: simulators.ts, adb.ts, eas.ts, Runner, digestOf, and one xcrun stub (llp/0030) (#133)
PR 2 of llp/0030 (one device per worktree). No behavior change. Moves
and exports what PR 3a's device-binding module will import, and gives
the e2e tier one `xcrun` stub that can create, boot, shut down and
delete simulators. Based on main, independent of #132.

## What moves

- `src/device/simulators.ts` (new): `SimulatorEntry`, `parseSimulators`
and `SIMCTL_TIMEOUT_MS` from `device/bootDevice.ts`;
`parseBootedIosSimulators` from `navigate/device.ts`;
`listBootedIosSimulatorsAsync` from `installedApp/iosSimulator.ts`.
- `src/device/adb.ts`: `AndroidDeviceLine` and `parseAndroidDevices`
from `navigate/device.ts`.
- `src/device/eas.ts` (new): `stopEasSessionAsync`,
`buildSessionStopArgs` and `EAS_SESSION_STOP_TIMEOUT_MS` from
`dev/openAppEas.ts`. The lazy requires in `dev/devAsync.ts`,
`dev/stopAsync.ts` and `smoke/smokeAsync.ts` point there.
- `src/utils/text.ts` (new): `openAppEas.ts`'s `firstLine`. The other
private copies stay.
- `src/utils/spawnCapture.ts`: a `Runner` type, the injectable shape of
one tool's subprocess runner.
- `src/devLock/address.ts`: `digestOf` is exported, so the binding and
the dev lock digest the same root.
- Old locations re-export nothing; every caller imports the new path.

## The e2e stub

`installStubXcrunAsync` in `e2e/__tests__/installedAppStubs.ts` replaces
the private copies in `navigate-test.ts`, `stop-test.ts` and
`runtime-reload-test.ts`. It keeps a simulator list in a state file:
`simulators` seeds it, `create` adds `E2E-CREATED-<n>` (from a counter
file, listed `Shutdown`), `boot` and `shutdown` change the state,
`delete` removes one, `list runtimes -j` names one iOS runtime,
`bootstatus -b` boots a `Shutdown` simulator the way the real one does,
`openurl` exits 0. `terminate` refuses an app outside `runningAppIds`,
and `openurl`/`terminate` keep the app-started marker, which the three
tests relied on.

`spawnAgentCli` defaults `__UNSAFE_EXPO_HOME_DIRECTORY` to `<fixture
dir>.expo-home`, so one test's Expo home never reaches another test or
the real home. The three `whoami` tests that pin the session file under
the real home opt out, as one of them already did.

## Verification

- Typecheck, lint (no new warnings), `bun run format:check`.
- Unit: 221 files, 4755 tests passed.
- Build, then e2e: the full suite, 41 files, 835 tests passed.
- No changelog entry: nothing a user can observe changed.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Fable 5.1 <[email protected]>
2026-10-12 22:20:27 +02:00
Vojtech NovakandClaude Fable 5.1 9bde0d56b6 [agent-cli] discovery verifies the project root of every server it finds (llp/0004 §Discovery ladder) (#132)
PR 1 of llp/0030 (one device per worktree). Four commits cherry-picked
from `feat/one-device-per-platform`, where they were verified live, plus
one commit that moves their design text into llp/0004. Independent of
the rest of the stack.

## What was wrong

Discovery's port scan took the first server that answered. On a machine
with parallel worktrees that is usually a sibling worktree's Metro, the
same app at another path, so `navigate` and the `runtime:*` verbs drove
the wrong server. Another project's Metro is the same case: any root
other than this worktree's is foreign. The port from `start.log` was
trusted without a check, although the log outlives its server. The
dev-server lock could publish a `--port` or default port that another
project's Metro held, so discovery's lock step pointed at a foreign
server [observed live, 2026-10-05].

## What changes for a user

- One project-root predicate, `matchProjectRoot` in
`src/runtime/projectRootHeader.ts`, serves every `/status` consumer: the
port scan, the `start.log` port, the dev lock's publish check, and the
places that already read it (`waitReady`, `startAsync`, the lock step of
discovery).
- Discovery steps 2, 3 and 4 skip a server whose `/status` names another
project root. When only foreign servers answer, discovery reports them
in `foreignServers`, and `status` prints "another project's dev server
answered on <ports>".
- A `/status` that does not answer within 3 s is not accepted: a server
that proves nothing is not this project's. A socket error on that read
gets one retry; a read that used its budget gets none. The budget is its
own, longer than the probe's 800 ms, so a slow `/status` is accepted.
`status` reads with its own 1.5 s probe budget, because it is a report
with a 3 s deadline.
- The lock never publishes a `--port` or default port whose `/status`
names another project root, checked before the publish for a named port
too. It keeps reading `start.log` while the dev server runs, and
publishes nothing if the server exits first (`cli:dev_lock_skipped`,
reason `foreign-port`). `isRunning` is a required option of the port
watch, because that watch has no other deadline.
- The `dev --detach` building e2e test runs on its own free `--port`, so
a developer's own Metro on 8081 no longer skips it.

Design: llp/0004 §Discovery ladder and §A busy port carry the rules; the
`@ref` comments point there.

## Tests

- `src/runtime/__tests__/devServerDiscovery-test.ts`: a foreign server
on a scanned port is skipped and reported; a log port that names another
root is rejected; a `/status` timeout is retried once and then not
accepted.
- `src/devLock/__tests__/port-test.ts`: a `--port` or default port with
a foreign root is not published; a port the log names later is.
`holdLock-test.ts`: a named port another project answers on is never
published and the lock follows the log; a dev server that stops with
only a foreign port to name holds nothing.
- `src/runtime/__tests__/waitReady-test.ts`, `reloadAsync-test.ts`:
adjusted to the moved predicate.
- `e2e/__tests__/dev-detach-test.ts`: the building test pins its own
port.
- Local: typecheck, lint (no warnings in touched files), unit
`src/runtime src/devLock src/status` (967 passed, 40 files), build, e2e
`dev-detach` (25 passed).

Review round (code-review skill, 8 findings): the three correctness
findings are fixed as above; `projectRootVerified` and
`ForeignDevServer.url`, which nothing read, are dropped; the duplicate
`@ref` and the `as AcceptedJudgement` cast are gone. Not taken: running
`/json/list` and `/status` in parallel per candidate.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Fable 5.1 <[email protected]>
2026-10-12 22:20:26 +02:00
Vojtech NovakandClaude Fable 5.1 c5d23bf3b9 [agent-cli] dev resolves the Metro port before the plan and owns --port on every step that serves (llp/0004 §A busy port) (#115)
Built on #116 (`fix/port-retry-fails-closed`), which makes the retry
fail closed; this PR is rebased onto main after it merges.

## What was wrong

The port was decided by the Expo CLI, step by step. Another project's
Metro was on `*:8081` and no TTY was attached. `expo run:ios` printed
"Use port 8082 instead?" and "Skipping dev server", deep-linked the app
to the foreign Metro, and exited 0. `dev --detach` then failed with
`DEV_DETACH_FAILED` [observed live, 2026-10-05]. `expo run:*` also got
no `--port`, so a named port reached only `expo start`.

## What changes for a user

- `dev` picks the port before the plan runs: the named `--port`, or the
first port from 8081 (`RCT_METRO_PORT` when set) that binds. A port that
is busy is busy whoever holds it: with this project's own dev server on
8081, `dev` picks the next free port. The reuse of this project's
running dev server is the next PR in the stack.
- A named `--port` that is taken is `PORT_IN_USE` before any step runs.
Under `--plan`, `devServerPort` is `{ state: 'named', taken: true }` and
the plan prints `Dev server: port 8180, as named, which is taken.`
- One rule for "is this server this project's": the server is this
project's unless `/status` names another project root
(`X-React-Native-Project-Root`). No header, or a root that contains this
project in the same checkout (a monorepo `metro.config.js`
`projectRoot`), is this project's server. A sibling root is not.
- The checkout boundary: `matchProjectRoot` accepts a containing root
only when no directory from the project up to that root (the root
excluded) holds a `.git` entry (file or directory). A Claude Code
worktree at `<repo>/.claude/worktrees/<name>` has a `.git` file, so the
main checkout's Metro (header `<repo>`) never counts as the worktree's
server. A monorepo app at `<repo>/apps/foo` with header `<repo>` still
matches. Every `/status` consumer reads this one rule: discovery's lock
step and 8081 fallback, `smoke`, `status`, `dev:wait`, `dev --detach`,
and the `arg` open in `startAsync`.
- Discovery's lock step (`discoverDevServerAsync` step 0, used by
`navigate`, `runtime:*` and the other runtime verbs) accepts the lock's
URL only when `/status` there names no other project's root
(`probeBundlerAsync` with `projectRoot`). The lock names its port at the
spawn, before Metro binds it, so another project's Metro can answer
there for a moment. A foreign root falls through to the log, the default
port and the scan, as a lock whose server does not answer already did.
- The lock is published at the spawn when the arguments name a port,
which `dev` always passes. The log watch goes on: `onResolved` is told
again with `source: 'log'`, and a logged port that differs updates the
lock's answer (`DevServerLockHandle.update`). With no port in the
arguments, the lock still waits for the log. The `--detach` parent
reports a lock once `start.log` names its port after the lock's
`startedAt` (the spawn of the step that holds it), or once 20 s (the
port watch's bound) have passed since that spawn, so a retry that moves
the dev server is reported on the port it took. The parent keeps no
bookkeeping of its own. A lock that is not confirmed when the child
exits or the budget ends is still returned, and the checks after it
judge the child.
- An open on an EAS Simulator session that is already up waits for the
dev server's tunnel host before it sends the deep link. The `arg` open
fires as soon as Metro answers `/status`, before the tunnel is up, and a
link sent then named `exp://127.0.0.1:<port>`, which the session cannot
load. This was the CI failure of `dev-eas-test` ("SIGINT cleans up an
owned session (reused)" and "reuses the session this project already
has"); a 3 s stub tunnel delay reproduced it locally every time.
- A `--plan` run whose port was probed says `The dev server port is
picked again when the plan runs.`
- `dev` owns `--port`: it is read, removed once from the forwarded
options, and set before any `--` on every serving step, `expo run:*`
included.
- `devServerPort` is `{ port, movedFrom, state }`, with `state` `picked`
or `named` (plus `taken`). The `Dev server:` line prints the state in
words. A move prints one line: `Port 8081 is busy; the dev server uses
8082.` at plan time, `Port 8082 was taken before the dev server bound
it; the dev server uses 8083.` on the retry.
- An app open aimed at a port that came from the command line (`source:
'arg'`) waits until `/status` answers there and names no other project's
root, polling every 500 ms. It does not happen when the dev server exits
first. An open on a port the dev server logged happens at once, and the
open fires once when both arrive.
- The `--json` object names the port the run ended on
(`devServerPort.port`, with `movedFrom` the planned port when the retry
moved it) and the serving step's argv as it ran.
- The `--detach` parent computes `portMoved` from the plan it reads from
the child's log (`Dev server: port <n>, because <m> is taken.`) and the
lock the child publishes. The move message carries no protocol, and
`parsePortMove` is gone.
- A collision still present after the one retry is #116's
`PORT_TAKEN_AFTER_RETRY` (exit 20), not a rewritten exit code.

## Tests

- `src/runtime/__tests__/waitReady-test.ts`: a root that contains the
project matches; a sibling whose name starts the same does not. Checkout
boundary (memfs layout with `<repo>/.git/` and a `.git` file at
`<repo>/.claude/worktrees/w`): the worktree with header `<repo>` → no
match (through a real HTTP `/status`); an app inside the worktree → no
match; `<repo>/apps/foo` → match; the repo root itself → match; a
sibling app → no match.
- `src/devLock/__tests__/holdLock-test.ts` (new, real lock and
`start.log`): with `--port` in the args the lock answers before any log
line and `onResolved` gets `arg`, then `log`, and the lock follows a
logged port that differs; without a port it waits for the log.
- `src/runtime/__tests__/devServerLockDiscovery-test.ts`: a lock whose
URL answers `/json/list` but whose `/status` names `/other-project` is
not accepted, and discovery falls through to the next server; a lock
whose `/status` names this project is accepted as `source: 'lock'`.
- `src/start/__tests__/startAsync-test.ts`: the open fires once when
`arg` and `log` both arrive; with the `arg` `/status` poll still
pending, a `log` opens once and the poll that then answers opens
nothing; an `arg` port whose `/status` names no root opens; a foreign
root does not open; a dev server that exits first does not open.
- `src/dev/__tests__/detachAsync-test.ts`: a lock that first names the
planned port and then the retry's port is reported on the port Metro
logged. A lock whose port Metro has not logged: accepted at 20 s after
its `startedAt` and not at 19.5 s (fake timers), and reported on its
port; with a 5 s budget it is returned at the deadline and the report
names its port; with the child exiting first, the run fails as
`DEV_DETACH_DIED`, not as a missing lock.
- `src/dev/__tests__/devAsync-test.ts`: serving steps carry the picked
or named port; a plan-time move warns once; `--plan` carries
`devServerPort` and the "picked again" reason, and a taken named port is
`state: 'named', taken: true`; a taken named port is `PORT_IN_USE`
before any step; the retry's port is reported in the `--json` object; a
collision after the retry is `PORT_TAKEN_AFTER_RETRY` (exit 0 and exit 1
variants); the earlier retry and `--json` cases are kept.
- `src/dev/__tests__/openAppEas-test.ts`: a session that is up gets no
deep link until the dev server advertises its tunnel, then one; with no
tunnel inside the wait it gets none, and the reason says so.
- `src/plan/__tests__/format-test.ts`: the `Dev server:` line for
`picked` and `named`; `emit-test.ts`, `childVerdict-test.ts`: the
`state` shape, and `parseDetachedChildPort` reads the table.
- `forwardedArgs-test.ts`, `resolveOptions-test.ts`,
`knownFlags-test.ts`, `portCollision-test.ts`: as before.
`src/lint/__tests__/foreignFlags-test.ts`: `--port` is written in
`src/dev/forwardedArgs.ts`.
- `e2e/__tests__/dev-detach-test.ts`: "a port another project holds"
runs the plan on the next free port, reports a double move from the port
the caller expected, and retries a `run:*` whose port became busy while
it compiled; `holdDualStackAsync` drops every connection, so a probe of
the held port from anything else on the machine cannot keep `close()`
from returning.
- `e2e/__tests__/dev-test.ts`, `dev-eas-test.ts`, `plan-test.ts`:
serving steps carry `--port`, and `devServerPort` carries `state:
'picked'`. `dev-eas-test.ts` "reuses the session this project already
has" runs with a 1.5 s stub tunnel delay, so an open that does not wait
for the tunnel fails it.
- `e2e/__tests__/runtime-reload-test.ts`, `runtime-test.ts`,
`cloud-simulator-test.ts`: a stub dev server that a test points the
project lock at names the project as its root, because discovery's lock
step reads the root now. Without it the stub answered as
`/stub-project`.
- Local: typecheck, lint, format check, unit (4755 passed, 221 files),
build, e2e `dev-test dev-detach-test plan-test dev-eas-test stop-test
smoke-test status-test wrapper-test runtime-reload-test
cloud-simulator-test` (371 passed, 10 files).

## When merged with the detach budget PR

The detach budget test "keeps the base for a plan that only serves"
needs `STUB_EXPO_NO_PORT_REPORT: '1'` in its env, because the stub now
reports the `--port` it is given. With #114, whichever PR lands second
resolves that one line.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01A9CwPuoTfcRMrAGrgqGRza

Co-authored-by: Claude Fable 5.1 <[email protected]>
2026-10-07 13:45:23 +02:00
expo-tuft[bot] bfef9ec4f6 [agent-cli] dev runs its plan, plans installs and rebuilds precisely, and drops --yes (#21) 2026-09-07 00:06:30 +08:00
Kudo Chien 5fa8d511e7 [agent-cli] Add @expo/agent-cli, an agent-native CLI for Expo (#1) 2026-09-04 13:54:19 +08:00