refactor(launch-video): agent-driven capture infrastructure and scene

[elucid]

What

Turns the one-off attention scene into reusable infrastructure for showcasing agent/CLI-driven Hunk in demo videos, and broadens the scene itself into a full agent story:

• scripts/launch-video/agentDriver.ts (new) — launchAgentDrivenHunk() runs a TUI against a daemon nobody else can see (scratch XDG_RUNTIME_DIR + OS-assigned HUNK_MCP_PORT, never HUNK_MCP_DISABLE), polls until the session registers, and hands back run/runJson session-CLI handles plus an optional on-camera shell sharing the same isolated env. driveGestures() plays a declarative sequence: silent gestures issue a command off camera and snap the TUI reacting; shell gestures type the same kind of command on camera, then snap the shell and/or the TUI.
• scripts/launch-video/demoContent.ts (new) — the generated report module, the demo repos, and locateNeedle, so every line number and character offset a scene points at is computed rather than hand-counted.
• captureAgentScene (was captureAttentionScene, SCENES=agent) — built entirely on the driver and gestures, with agent- frames.

Why

The agent surfaces' whole point is that they arrive over the session daemon, so the scene must drive them for real. But the daemon setup, the CLI runner, and the demo content were all buried inside one scene function — a second agent scene would have had to copy all three. Splitting them out makes "an agent drives this review" a capability of the capture pipeline instead of a property of one shot.

The scene

Opening review shot → hunk session list typed on camera (the CLI surface, one live session) → hunk-level vs line-exact landing (--hunk parks at the top of a tall hunk; --new-line 86 lands the buried comparator, typed on camera with the computed line) → character-range warning mark → tone-only repaint as current (viewport untouched, isolating --tone from --focus) → cross-file highlight add … --focus typed on camera → a comment add on that same line, showing what persists when a mark does not → highlight clear.

On-camera commands select the session with --repo . from the demo repo: a selector is mandatory (hunk session navigate with neither <session-id> nor --repo errors), and an absolute path or a UUID reads badly on screen.

Storyboard consumer

compose.mjs gains a six-shot agent segment before the outro (agent-review, agent-shell-nav, agent-line-nav, agent-mark-warning, agent-mark-focus, agent-comment), with NEW badges on the line-exact and mark claims. Capture scenes rot when nothing consumes their frames — the compose preflight only checks frames a storyboard references — so this keeps the scene exercised by every full-capture preflight. The rest of the storyboard is still the 0.18 reference and is unchanged.

skills/hunk-launch-video/SKILL.md documents the pattern under "Authoring scenes".

Verification

• bun run typecheck, bun run lint clean.
• SCENES=agent bun run scripts/launch-video/capture.ts run twice; both produced the same 17 frames with no errors.
• Eyeballed agent-shell-list, agent-shell-nav, agent-line-nav, agent-mark-warning, agent-mark-focus, agent-comment, agent-clear: typed commands and their real output are legible in the shell frames, marks are visibly painted on the exact ranges, the note renders as an agent-note card, and each landing sits near the top of the viewport.
• A full composite needs every scene captured, so it is out of scope here; the segment's frame names were checked against the capture output.

Notes

• Also silences macOS bash's zsh-migration banner in shell scenes — it was the first thing on camera in every shell frame.
• Empty changeset: maintainer-only tooling (scripts/launch-video/ never ships to npm).

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hunk-web	Ignored	Preview	Aug 16, 2026 10:35pm

[greptile-apps]

Greptile Summary

Adds an agent-attention launch-video scene that drives line navigation and character-range highlights through a session broker.

• Generates a deterministic tall demo diff for line-exact navigation.
• Captures warning/current highlights, focus movement, and highlight clearing.
• Adds per-launch environment overrides and an empty maintainer-tooling changeset.

Confidence Score: 4/5

The PR should not merge until the attention scene allocates a unique available broker port so captures cannot collide or control another capture's session.

The scene isolates broker metadata but reuses a fixed host-global TCP port, allowing overlapping captures or a lingering broker to cause startup failure or cross-session commands.

Files Needing Attention: scripts/launch-video/capture.ts

Important Files Changed

Filename	Overview
scripts/launch-video/capture.ts	Adds the attention capture workflow, but its fixed broker port prevents the promised isolation between overlapping or recently completed captures.
.changeset/big-actors-build.md	Adds the expected empty changeset for maintainer-only launch-video tooling.

Sequence Diagram

sequenceDiagram
  participant A as Attention capture A
  participant B as Attention capture B
  participant D as Broker on 127.0.0.1:47911
  A->>D: Launch/discover broker
  A->>D: Register session A
  B->>D: Discover same healthy endpoint
  B->>D: Register session B
  B->>D: list sessions
  D-->>B: Sessions ordered by latest update
  B->>D: Navigate/highlight sessions[0]
  Note over B,D: Command may target session A

Loading

Prompt To Fix All With AI

### Issue 1
scripts/launch-video/capture.ts:217
**Fixed port breaks daemon isolation**

If two attention captures overlap or a previous capture's detached broker remains healthy, both runs use the host-global `127.0.0.1:47911` endpoint despite their separate runtime directories, causing an address-in-use failure or reuse of a broker where `sessions[0]` can belong to the other capture and receive its navigation and highlight commands.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "chore(launch-video): add agent-attention..." | Re-trigger Greptile}

[greptile-apps]

Fixed port breaks daemon isolation

If two attention captures overlap or a previous capture's detached broker remains healthy, both runs use the host-global 127.0.0.1:47911 endpoint despite their separate runtime directories, causing an address-in-use failure or reuse of a broker where sessions[0] can belong to the other capture and receive its navigation and highlight commands.

Prompt To Fix With AI

This is a comment left during a code review.
Path: scripts/launch-video/capture.ts
Line: 217

Comment:
**Fixed port breaks daemon isolation**

If two attention captures overlap or a previous capture's detached broker remains healthy, both runs use the host-global `127.0.0.1:47911` endpoint despite their separate runtime directories, causing an address-in-use failure or reuse of a broker where `sessions[0]` can belong to the other capture and receive its navigation and highlight commands.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.