fix: detect and replace stale playground instances on target port

[heimanba]

Problem

When upgrading @openagentpack/cli (e.g. from @latest to @beta), a previously-started playground process may still occupy port 4848. The new instance silently binds to 4849, but the browser opens 4848 — leaving the user stuck on a stale UI with missing features (e.g. no deployment/schedule UI).

Root Cause

• agents playground spawns a playground subprocess that auto-increments the port when the preferred one is busy
• There was no mechanism to detect what was occupying the port
• The old playground /health endpoint only returned { "status": "ok" } with no version or identity information

Solution

1. Enriched /health endpoint (packages/playground/src/server.ts)

GET /health → { "status": "ok", "playground": { "version": "0.3.0-beta-xxx", "pid": 12345 } }

Registered before the server routes so it takes precedence over the generic health check from apps/server.

2. Pre-launch probe + auto-replace (packages/cli/src/commands/playground.ts)

Before spawning a new playground, the CLI now probes the target port:

Port state	Behavior
Free	Normal startup
Same-version playground running	Reuse it — open browser, skip spawn
Different-version playground running	SIGTERM → wait for port release → start new version
Non-playground process / no /health	Proceed normally (playground auto-increments port)
Old playground without version in /health	Same as non-playground (backward-compatible)

3. Cache-Control for static assets

Added Cache-Control: no-cache middleware for /assets/* — filenames are stable (not content-hashed) due to console embed constraints, so browsers must revalidate on every navigation to avoid serving stale JS/CSS after an upgrade.

[heimanba]

Problem

When upgrading @openagentpack/cli (e.g. from @latest to @beta), a previously-started playground process may still occupy port 4848. The new instance silently binds to 4849, but the browser opens 4848 — leaving the user stuck on a stale UI with missing features (e.g. no deployment/schedule UI).

Root Cause

• agents playground spawns a playground subprocess that auto-increments the port when the preferred one is busy
• There was no mechanism to detect what was occupying the port
• The old playground /health endpoint only returned { "status": "ok" } with no version or identity information

Solution

1. Enriched /health endpoint (packages/playground/src/server.ts)

GET /health → { "status": "ok", "playground": { "version": "0.3.0-beta-xxx", "pid": 12345 } }

Registered before the server routes so it takes precedence over the generic health check from apps/server.

2. Pre-launch probe + auto-replace (packages/cli/src/commands/playground.ts)

Before spawning a new playground, the CLI now probes the target port:

Port state	Behavior
Free	Normal startup
Same-version playground running	Reuse it — open browser, skip spawn
Different-version playground running	SIGTERM → wait for port release → start new version
Non-playground process / no /health	Proceed normally (playground auto-increments port)
Old playground without version in /health	Same as non-playground (backward-compatible)

3. Cache-Control for static assets

Added Cache-Control: no-cache middleware for /assets/* — filenames are stable (not content-hashed) due to console embed constraints, so browsers must revalidate on every navigation to avoid serving stale JS/CSS after an upgrade.

[heimanba]

Problem

When upgrading @openagentpack/cli (e.g. from @latest to @beta), a previously-started playground process may still occupy port 4848. The new instance silently binds to 4849, but the browser opens 4848 — leaving the user stuck on a stale UI with missing features (e.g. no deployment/schedule UI).

Root Cause

• agents playground spawns a playground subprocess that auto-increments the port when the preferred one is busy
• There was no mechanism to detect what was occupying the port
• The old playground /health endpoint only returned { "status": "ok" } with no version or identity information

Solution

1. Enriched /health endpoint (packages/playground/src/server.ts)

GET /health → { "status": "ok", "playground": { "version": "0.3.0-beta-xxx", "pid": 12345 } }

Registered before the server routes so it takes precedence over the generic health check from apps/server.

2. Pre-launch probe + auto-replace (packages/cli/src/commands/playground.ts)

Before spawning a new playground, the CLI now probes the target port:

Port state	Behavior
Free	Normal startup
Same-version playground running	Reuse it — open browser, skip spawn
Different-version playground running	SIGTERM → wait for port release → start new version
Non-playground process / no /health	Proceed normally (playground auto-increments port)
Old playground without version in /health	Same as non-playground (backward-compatible)

3. Cache-Control for static assets

Added Cache-Control: no-cache middleware for /assets/* — filenames are stable (not content-hashed) due to console embed constraints, so browsers must revalidate on every navigation to avoid serving stale JS/CSS after an upgrade.

[heimanba]

Problem

When upgrading @openagentpack/cli (e.g. from @latest to @beta), a previously-started playground process may still occupy port 4848. The new instance silently binds to 4849, but the browser opens 4848 — leaving the user stuck on a stale UI with missing features (e.g. no deployment/schedule UI).

Root Cause

• agents playground spawns a playground subprocess that auto-increments the port when the preferred one is busy
• There was no mechanism to detect what was occupying the port
• The old playground /health endpoint only returned { "status": "ok" } with no version or identity information

Solution

1. Enriched /health endpoint (packages/playground/src/server.ts)

GET /health → { "status": "ok", "playground": { "version": "0.3.0-beta-xxx", "pid": 12345 } }

Registered before the server routes so it takes precedence over the generic health check from apps/server.

2. Pre-launch probe + auto-replace (packages/cli/src/commands/playground.ts)

Before spawning a new playground, the CLI now probes the target port:

Port state	Behavior
Free	Normal startup
Same-version playground running	Reuse it — open browser, skip spawn
Different-version playground running	SIGTERM → wait for port release → start new version
Non-playground process / no /health	Proceed normally (playground auto-increments port)
Old playground without version in /health	Same as non-playground (backward-compatible)

3. Cache-Control for static assets

Added Cache-Control: no-cache middleware for /assets/* — filenames are stable (not content-hashed) due to console embed constraints, so browsers must revalidate on every navigation to avoid serving stale JS/CSS after an upgrade.

[heimanba]

Problem

When upgrading @openagentpack/cli (e.g. from @latest to @beta), a previously-started playground process may still occupy port 4848. The new instance silently binds to 4849, but the browser opens 4848 — leaving the user stuck on a stale UI with missing features (e.g. no deployment/schedule UI).

Root Cause

• agents playground spawns a playground subprocess that auto-increments the port when the preferred one is busy
• There was no mechanism to detect what was occupying the port
• The old playground /health endpoint only returned { "status": "ok" } with no version or identity information

Solution

1. Enriched /health endpoint (packages/playground/src/server.ts)

GET /health → { "status": "ok", "playground": { "version": "0.3.0-beta-xxx", "pid": 12345 } }

Registered before the server routes so it takes precedence over the generic health check from apps/server.

2. Pre-launch probe + auto-replace (packages/cli/src/commands/playground.ts)

Before spawning a new playground, the CLI now probes the target port:

Port state	Behavior
Free	Normal startup
Same-version playground running	Reuse it — open browser, skip spawn
Different-version playground running	SIGTERM → wait for port release → start new version
Non-playground process / no /health	Proceed normally (playground auto-increments port)
Old playground without version in /health	Same as non-playground (backward-compatible)

3. Cache-Control for static assets

Added Cache-Control: no-cache middleware for /assets/* — filenames are stable (not content-hashed) due to console embed constraints, so browsers must revalidate on every navigation to avoid serving stale JS/CSS after an upgrade.

[heimanba]

Problem

When upgrading @openagentpack/cli (e.g. from @latest to @beta), a previously-started playground process may still occupy port 4848. The new instance silently binds to 4849, but the browser opens 4848 — leaving the user stuck on a stale UI with missing features (e.g. no deployment/schedule UI).

Root Cause

• agents playground spawns a playground subprocess that auto-increments the port when the preferred one is busy
• There was no mechanism to detect what was occupying the port
• The old playground /health endpoint only returned { "status": "ok" } with no version or identity information

Solution

1. Enriched /health endpoint (packages/playground/src/server.ts)

GET /health → { "status": "ok", "playground": { "version": "0.3.0-beta-xxx", "pid": 12345 } }

Registered before the server routes so it takes precedence over the generic health check from apps/server.

2. Pre-launch probe + auto-replace (packages/cli/src/commands/playground.ts)

Before spawning a new playground, the CLI now probes the target port:

Port state	Behavior
Free	Normal startup
Same-version playground running	Reuse it — open browser, skip spawn
Different-version playground running	SIGTERM → wait for port release → start new version
Non-playground process / no /health	Proceed normally (playground auto-increments port)
Old playground without version in /health	Same as non-playground (backward-compatible)

3. Cache-Control for static assets

Added Cache-Control: no-cache middleware for /assets/* — filenames are stable (not content-hashed) due to console embed constraints, so browsers must revalidate on every navigation to avoid serving stale JS/CSS after an upgrade.

[heimanba]

Problem

When upgrading @openagentpack/cli (e.g. from @latest to @beta), a previously-started playground process may still occupy port 4848. The new instance silently binds to 4849, but the browser opens 4848 — leaving the user stuck on a stale UI with missing features (e.g. no deployment/schedule UI).

Root Cause

• agents playground spawns a playground subprocess that auto-increments the port when the preferred one is busy
• There was no mechanism to detect what was occupying the port
• The old playground /health endpoint only returned { "status": "ok" } with no version or identity information

Solution

1. Enriched /health endpoint (packages/playground/src/server.ts)

GET /health → { "status": "ok", "playground": { "version": "0.3.0-beta-xxx", "pid": 12345 } }

Registered before the server routes so it takes precedence over the generic health check from apps/server.

2. Pre-launch probe + auto-replace (packages/cli/src/commands/playground.ts)

Before spawning a new playground, the CLI now probes the target port:

Port state	Behavior
Free	Normal startup
Same-version playground running	Reuse it — open browser, skip spawn
Different-version playground running	SIGTERM → wait for port release → start new version
Non-playground process / no /health	Proceed normally (playground auto-increments port)
Old playground without version in /health	Same as non-playground (backward-compatible)

3. Cache-Control for static assets

Added Cache-Control: no-cache middleware for /assets/* — filenames are stable (not content-hashed) due to console embed constraints, so browsers must revalidate on every navigation to avoid serving stale JS/CSS after an upgrade.

[heimanba]

Problem

When upgrading @openagentpack/cli (e.g. from @latest to @beta), a previously-started playground process may still occupy port 4848. The new instance silently binds to 4849, but the browser opens 4848 — leaving the user stuck on a stale UI with missing features (e.g. no deployment/schedule UI).

Root Cause

• agents playground spawns a playground subprocess that auto-increments the port when the preferred one is busy
• There was no mechanism to detect what was occupying the port
• The old playground /health endpoint only returned { "status": "ok" } with no version or identity information

Solution

1. Enriched /health endpoint (packages/playground/src/server.ts)

GET /health → { "status": "ok", "playground": { "version": "0.3.0-beta-xxx", "pid": 12345 } }

Registered before the server routes so it takes precedence over the generic health check from apps/server.

2. Pre-launch probe + auto-replace (packages/cli/src/commands/playground.ts)

Before spawning a new playground, the CLI now probes the target port:

Port state	Behavior
Free	Normal startup
Same-version playground running	Reuse it — open browser, skip spawn
Different-version playground running	SIGTERM → wait for port release → start new version
Non-playground process / no /health	Proceed normally (playground auto-increments port)
Old playground without version in /health	Same as non-playground (backward-compatible)

3. Cache-Control for static assets

Added Cache-Control: no-cache middleware for /assets/* — filenames are stable (not content-hashed) due to console embed constraints, so browsers must revalidate on every navigation to avoid serving stale JS/CSS after an upgrade.