astro preview --ignore-lock is refused whenever an AI agent is detected, so Playwright webServer cannot use it from an agent session #17903

Astro Info

Astro                    v7.3.1
Vite                     v8.2.2
Node                     v24.19.0
System                   macOS (arm64)
Package Manager          npm
Output                   static
Adapter                  @astrojs/node (v11.1.5)

The failing check runs in cli/preview/index.ts before the server or any integration loads, so the project contents do not matter.

Describe the Bug

7.3.0 added --ignore-lock to astro preview (#17720) so several preview servers can run at once, with Playwright's webServer as the motivating case. The same command refuses the flag whenever am-i-vibing detects an AI agent (CLAUDECODE, CURSOR_TRACE_ID and similar), because detection forces background mode and background mode needs the lock file:

`--ignore-lock` cannot be used together with an auto-detected AI agent environment, which runs the preview server in the background automatically.

Background preview servers rely on the lock file so `astro preview stop`, `astro preview status`, and `astro preview logs` can find them.
Run the preview server in the foreground to use --ignore-lock.

There is no flag to run in the foreground when background mode was only inferred, and am-i-vibing has no opt-out variable, so the error's own advice cannot be followed. From inside an agent session the flag is unreachable. That is the environment #17721 described, and #17721 was closed as covered by #17720.

Playwright, webServer.command: 'npx astro preview --ignore-lock --port 4397', run from a Claude Code session:

[WebServer] `--ignore-lock` cannot be used together with an auto-detected AI agent environment, which runs the preview server in the background automatically.
[WebServer] Run the preview server in the foreground to use --ignore-lock.
Error: Process from config.webServer was not able to start. Exit code: 1

The same command with the agent variables removed from the environment (env -i PATH=$PATH HOME=$HOME npx playwright test):

Running 1 test using 1 worker
  ✓  1 tests/home.spec.mjs:2:1 › homepage answers 200 (27ms)
  1 passed (1.5s)

In packages/astro/src/cli/preview/index.ts on 7.3.1 and on main:

const agentDetected = !process.env.ASTRO_PREVIEW_BACKGROUND && isRunByAgent();
const wantsBackground = !!flags.background || agentDetected;
// ...
if (ignoreLock && wantsBackground) { /* throws the error above */ }

cli/dev/index.ts has the same shape, so astro dev --ignore-lock is refused under an agent too.

Workaround that works today: ASTRO_PREVIEW_BACKGROUND=0 npx astro preview --ignore-lock --port 4397. The marker is checked for presence, not value, so it suppresses detection, and because --ignore-lock writes no lock file the background: !!'0' corruption noted in #17721 does not apply. It is an internal marker for the spawned child and undocumented, so it is not a fix.

What's the expected result?

--ignore-lock already means "a one-off server that stop, status and logs will not track", which is exactly a foreground server. When background mode was only inferred from agent detection, the flag should start the server in the foreground instead of throwing. The conflict with an explicit --background stays. One line in each of cli/preview/index.ts and cli/dev/index.ts:

const wantsBackground = !!flags.background || (agentDetected && !ignoreLock);

Alternative: a --foreground flag that overrides detection, which is what the error message already tells the user to do.

Link to Minimal Reproducible Example

https://github.com/chuckreynolds/astro-ignore-lock-agent-repro

Steps, from the minimal template:

npm create astro@latest repro -- --template minimal --install --no-git
cd repro && npx astro build
CLAUDECODE=1 npx astro preview --ignore-lock --port 4397   # exits 1 with the error above
npx astro preview --ignore-lock --port 4397                # foreground server on 4397

Playwright config used above:

export default {
  webServer: {
    command: 'npx astro preview --ignore-lock --port 4397',
    url: 'http://localhost:4397/',
    reuseExistingServer: false,
  },
};

Participation

• I am willing to submit a pull request for this issue.

assisted by claude fable 5.1