[miguel-heygen]

What

A hyperframes preview started inside a host app's agent run (HYPERFRAMES_DESKTOP_PROJECT set) no longer opens the project's history, so it never takes the history's owner lock. The host app owns that history.

Why

An agent's shell commands each run in their own process group, so a preview an agent starts during a run can outlive that run when the host stops the run's process group, and even outlive the host app. While it holds the history lock, the host can't open the project's history. Every later run waits for the lock, is refused ("Another HyperFrames preview is using this project's history"), and Undo, history steps and project renames fail the same way, until the leftover preview is killed by hand.

#5852 already refuses --background inside a host app's run. A --foreground preview, which that error message suggests and which skills use, still took the lock.

How

createStudioServer asks insideHostApp() once. Inside a host app's run, the adapter's history answers null and never calls openProjectHistory. Studio already handles a history that's off, the same path it takes today when another process holds the lock. The host app's own watcher still records the run's file changes in its history.

Why under 100 lines

It is one decision with one owner: inside a host app's run, the preview leaves the history to the host. That is a single check in createStudioServer plus its test. It ships alone because it depends on no other open change, and every release without it leaves later runs refused until someone kills the leftover preview by hand.

Test plan

• studioServer.test.ts: with HYPERFRAMES_DESKTOP_PROJECT set, the history route answers 404 and openProjectHistory is never called. It fails with the check removed: the history is opened. 43 pass, three runs in a row.
• Lint, format and the comment ratchet are clean. tsc shows only two errors, both in files this PR doesn't touch (checkFindingInspect.ts, and checkTypes.ts, which needs the unbuilt inspector package).
• Not exercised: an orphaned preview left over from before this release. It keeps its lock until it exits.

[github-actions]

Edit accuracy: accurate 271 (base branch 271), smooth 151 of those

The gate passes.
Smoothness is reported in the artifact, not gated. A case fails only if it fails 2 of 3 runs.

Quarantined, measured but not gated (0)

Unstable (2)

• seqplainkeys-none-px-r0-nested-z100: tracking 0.07, pressJump 0, drop 0, reload 0, render 0.03, renderKey -, undo false, teleport true / tracking 0.07, pressJump 0, drop 0, reload 0, render 0.03, renderKey -, undo true, teleport true / tracking 0.07, pressJump 0, drop 0, reload 0, render 0.03, renderKey -, undo true, teleport true
• seqplainkeys-none-pct-r0-root-z100: tracking 0.06, pressJump 0, drop 0, reload 0, render 0.03, renderKey -, undo false, teleport true / tracking 0.06, pressJump 0, drop 0, reload 0, render 0.03, renderKey -, undo true, teleport true / tracking 0.06, pressJump 0, drop 0, reload 0, render 0.03, renderKey -, undo true, teleport true

[heygengenesis]

Verdict: APPROVE · 0 blocker · 0 important · 0 nits · head 47c34dff

Scope

The adapter's history is the only place that calls projectHistory(). The watcher's noteChange goes through histories.peek, which never opens a history, so a preview inside the host's run takes no lock at all. I also checked the env var across hyperframes-internal: the desktop app sets HYPERFRAMES_DESKTOP_PROJECT only on child envs (agent runs in runLaunch.mjs, the render CLI in render.mjs), and it opens its own history in the main process (projectHistory.mjs). So the host's own history is unaffected. The first set of workflow runs on this head is all green; a second CI run was still running at review time.