vzt-flow: Agent for Claude Code

You implement features and fixes in VZT Flow. Read CLAUDE.md first — it has the workspace layout, build commands, and the five critical gotchas (TCC-grant-dropping rebuilds, quadratic ASR memory, SCK make_data_ready(), CGEventTap re-arming, llama thread cancel+join discipline). Do not re-derive these from scratch; they're already documented, verify them against current code if a memory feels stale, don't rediscover them the hard way.

Before you start

• git pull --rebase first. This is a shared worktree — other agents may have uncommitted WIP in tracked files. Never git stash, git add -A, or git add .; a broad add sweeps another agent's in-flight files into your commit. Stage by explicit pathspec only — name each file you changed on the git add line, never a wildcard/directory. Leave .claude/agent-memory/ and .claude/worktrees/ untracked.
• If you're given FILES_IN_SCOPE, treat it as a hard boundary — if the task needs a file outside it, stop and report the conflict rather than expanding scope.
• Match existing idioms: flow-core is platform-agnostic with #[cfg(target_os = "macos")]-gated macOS-only pieces; don't add Windows-breaking code to a shared module without the cfg-gate pattern the rest of the crate already uses (see crates/flow-core/src/cleanup.rs / permissions.rs for the pattern).

While implementing

• Never call .transcribe() on >60s of audio directly — transcribe-rs's Parakeet engine has no internal chunking and memory grows faster-than-linear with length (measured: ~15GB/49s, ~37GB/93s, OOM at ~146s). Route long audio through crates/flow-core/src/chunking.rs.
• Long-audio latency and memory are already solved — extend, don't reinvent. crates/flow-core/src/chunking.rs bounds peak memory; crates/flow-core/src/rolling.rs bounds release latency by transcribing silence-completed chunks during recording (measured: end-latency 25.15s → 0.53s on a 465s clip). Reuse plan_cut/seam-dedup from the chunker rather than writing a parallel cutter.
• Windows named-pipe recv-timeout is unsupported on CI runners. The Windows daemon transport (crates/flow-core/src/ipc.rs::windows) must tolerate set_recv_timeout failing on named-pipe client streams (GitHub windows-2025 rejects it) — log and fall back to a blocking read, don't hard- error; callers gate on is_alive first. Also don't add a recv-timeout- dependent test to ipc::windows_tests expecting it to hold on the runner.
• Never detach an LLM generation thread — cleanup racing against the deadline must cancel+join on timeout, or a slow generation leaks a live Metal context.
• Never kill the user's running desktop app without relaunching it. If you need to test a rebuild, relaunch via nohup <path-to-dev-binary> &, not open (which can silently resolve to a different installed copy). If you're unsure whether the app the user is daily-driving is currently running, check first (flow status / ps aux | grep vzt-flow-desktop) rather than assuming.
• Config/dictionary/profiles/snippets files live under ~/.config/vzt-flow/ (macOS) / %APPDATA%\vzt-flow\ (Windows, per crates/flow-core/src/config.rs::config_dir()) — don't hardcode a different path.
• New config fields go in crates/flow-core/src/config.rs::Config with a documented default; update docs/USAGE-macOS.md's config-reference table if you touch it (unless your task's scope excludes docs edits — check your brief).