# Bugs - Question answers given while the agent is working get lost Answering an inbox question while the task's agent is mid-turn sometimes never reaches the agent. Answers are meant to be held and delivered as one message once the session is idle with no blocking question still waiting (`Deliver` in `internal/agents/inbox.go`, called when a turn ends). Find the path where a held answer is dropped. Byre restarts often while agents deploy, and a restart cuts the turn off and resumes it with the restart notice (`Recover` in `internal/agents/manager.go`), so check that path first. Add debugging output before changing code. - Merge is forgotten if the human switches tasks before the merge turn ends Clicking Merge starts a merge-in turn and records, in memory only, that the task is to be squashed when that turn ends (`m.merges` in `internal/agents/mergein.go`, read by `takeMerge` at turn end). The human then switched to another task, and when the turn finished nothing was merged. Switching tasks in the UI shouldn't affect server state, so the likelier cause is that byre restarted during the turn, which loses the in-memory intent (as described under "Closing a task" in `docs/operations.md`). Confirm the cause, and make the merge intent survive until the turn ends. # M0 — Skeleton - Per-task snapshot counts and disk usage in the Admin view The Admin view already covers queue state, rate limits, process liveness, stuck and zombie detection, and protocol errors. Add each active task's snapshot count and the disk its snapshots and worktree use. # M1 — One agent end to end - Subagent views Render the vendor's subagent activity in the transcript once agents use subagents. Vendor-specific events that don't map onto the core event kinds get vendor-specific UI components. - Mermaid rendering in Markdown views Render Mermaid source (in transcripts, inbox items and review attachments) as diagrams. - Decide whether to render agent todo lists Interface coverage is added one feature at a time as the workflow needs it, rather than mirroring the vendor's native interface. Decide whether the agent's own todo list gets rendered in the transcript. - Decide whether to support @-file mentions in the composer # M2 — Seeing the work - Timeline scrubbing A timeline over a task's snapshots, showing the diff at each point alongside the transcript up to that snapshot's `event_seq`. - Forking from a snapshot A new worktree from a snapshot commit plus a new agent session. Same vendor: the vendor's native session fork or resume. Different vendor: a handoff bundle from `export_context`, labelled in the UI as a handoff, not a true fork. - Terminals PTYs via `github.com/creack/pty`, rendered with xterm.js, one WebSocket per open terminal (the only WebSocket use in byre). Scoped to the task's worktree by default. Shown as a pane tab. - Decide whether terminals survive a byre restart Either accept that terminals are lost when byre restarts, or back each terminal with tmux. - File browser Read-only, scoped to project and worktree roots. Shown as a pane tab. - Per-project setup config A setup script run in each new worktree (dependency install, env file copying), and port allocation so parallel dev servers don't collide. - Decide the format of per-project setup config It holds the setup script, port allocation, and the run and capture config that visual reviews use. - Previews Web: byre supervises a per-task dev server and exposes it over Tailscale, preferably as a per-task port through `tailscale serve`, since path-prefix proxying breaks apps that use absolute paths. iOS: on-demand simulator screenshots and recordings attached to the task, with Screen Sharing over Tailscale as the manual fallback. Shown as a pane tab. - Confirm `tailscale serve` can expose per-task preview ports # M3 — Second vendor and review - Codex adapter A JSON-RPC client for `codex app-server`, with Go types generated from the protocol schema the CLI can emit. It needs: start thread, stream events, send turns, interrupt, resume, and the same interface coverage as Claude (interrupts, model switching, compaction, image input). Disable CLI auto-updates so the version changes only when the owner updates it, and keep a contract test suite built from recorded transcripts. - Verify that Codex app-server can fork threads - Review profiles and triggers Reviews are done by a separate agent session, never the implementer, by default from a different vendor. Each review targets a snapshot and is cached by tree sha; when the task's tree moves on, existing reviews are marked stale. A review profile (security, performance, privacy, visual UX, plan conformance, ...) has a prompt, vendor, model, output schema and capture config; workflow stages reference profiles by name. Triggers: on `ask_human` (the inbox item appears at once and the review attaches when done, even if the item was resolved first), before merge, on demand, and periodically on elapsed time or diff size, debounced to turn boundaries or a quiet period. A `request_review(scope, concerns[], profile?)` MCP tool lets agents ask for one. - Decide the periodic review thresholds The defaults for elapsed time and diff size, with per-project overrides. - Visual review output Structured output that leans visual rather than quoting code: a summary; highlights, each with a category, severity and anchors to files or lines so the UI can jump to them; Mermaid diagrams of changed data flow, call graphs, state machines and schemas; screenshots or recordings of the running result (Playwright MCP for web projects, `xcrun simctl io` screenshot and recordVideo for iOS simulator projects); before/after pairs from the base ref and the current snapshot where possible. The UI should encourage, in increasing order: file diffs, diff stats, an agent-generated summary, agent highlights with visual explanations. - Decide how simulators are allocated iOS simulators are shared between parallel tasks and review agents and need allocation or locking. Parallel Xcode builds also compete for CPU, and per-worktree DerivedData costs disk and cold builds. - Cross-vendor review A review profile whose vendor differs from the implementer's. # M4 — Merging and history - Co-author trailers for humans who trigger forks Squash commits already carry a `Co-authored-by` trailer for every other human with a message bubble in the task's transcript (see "Closing a task" in `docs/operations.md`). Once forks exist, a human who triggers a fork of the task should count too. - Edit the drafted merge message before confirming - Merge-resolution stage A stage triggered when merging the default branch into a task branch conflicts; its result goes to review. - Git notes on squash merges Attach a note under `refs/notes/byre` to each squash commit, holding the plan, the handoff bundle, review summaries, eval results and resolved inbox decisions, with full transcripts referenced by task ID. Notes don't push or fetch by default, so the merge pushes the notes ref explicitly and project setup configures fetching it. - Repeated merge cycles Let a task merge more than once. After the squash commit lands, reset the task branch to the new default-branch head, since squash commits leave the agent's commits as non-ancestors and later cycles would accumulate spurious conflicts (the per-turn history stays reachable through snapshot refs). Then tell the agent explicitly that its branch was squashed and reset, so it doesn't try to repair history, and resume it; files on disk don't change. Test this per vendor. - Archive search Search closed tasks across transcripts, artifacts and decisions. - GitHub Issues integration Issue tracking is pluggable, GitHub Issues first. Tasks link to issues at intake, and each merge posts or updates a summary comment on the linked issues. # M5 — Workflows - Workflow definitions and storage A workflow is a sequence of stages, each with a role prompt template, a vendor and model, typed artifact inputs and outputs, an optional gate, and optional review profiles. Definitions, prompt templates and review profiles live on the server, not in repos, and export and import as files. A task freezes its workflow definition at intake, so later edits to the workflow don't change running tasks. No general DAG engine until a real workflow needs one. - Stages, gates and bounded loops Gates are human approval through the inbox, a review pass or an eval pass. Loops are bounded, for example `on_fail: { goto: build, max: 3, then: escalate }`. - Plan artifact A versioned artifact with goal, approach, steps, acceptance criteria, risks and open questions. Humans edit it through the inbox; agents propose edits, which go to the inbox for approval. Stored on the server and attached to merges with git notes, never committed. A plan-conformance review profile compares the diff with it. - Eval stages Report pass or fail per acceptance criterion of the plan. - Task intake Pick a workflow, fill its inputs (a brief, attachments, linked GitHub issues, handoff bundles from other tasks), and optionally override vendors, models, prompts or review profiles per stage. - Mid-task swapping of stage vendors, models, prompts and review profiles At any point a human can swap a stage's vendor, model, prompt or review profiles, and add, remove or reorder the stages of the task's frozen workflow. # M6 — Fan-out - `export_context` and handoff bundles An `export_context(purpose)` MCP tool producing a bundle with the goal, decisions made and why, current state, dead ends tried, open questions and relevant files. Used for cross-vendor forks, stage-to-stage handoff, and the durable record of a task. Compaction already writes the same contents. - Same-vendor forks - Cross-vendor handoffs - Fork-and-compare A fan-out of N forks with different vendors or prompts from one snapshot, followed by a judge stage that produces a comparison with visuals. - Just-in-time fan-out with limits `spawn_stages(stages[])` and `collect(stage_ids[])` MCP tools let agents build workflows on the fly, using the same stage definition format. Limits on maximum depth, concurrent spawned stages and per-task usage budget, all configurable; an optional per-workflow human gate on spawning. Spawned stages show in the task's UI tree marked as just-in-time, and a just-in-time structure can be saved as a reusable workflow. - Decide the default limits for just-in-time fan-out Defaults for maximum depth, concurrent spawned stages and per-task usage budget. # M7 — Inbox triage - Inbox triage agent An agent that answers questions resolvable from the repo or docs and escalates the rest with its reasoning attached. Tune it on real inbox data. # UI - Decide whether to keep both the ⌘K switcher and the Tasks view # Known hazards - Pre-push hook on the shared repo Agents share the repo's `.git` across worktrees and run fully permissive, so they can push, check out other branches, delete snapshot refs, or run `git gc` or `git worktree prune`. Session guidance already forbids this; add a pre-push hook on the shared repo that blocks pushes not made by byre, and periodically verify that snapshot refs survive. - Consider moving large event payloads into blobs Stream-json is verbose and tool outputs are large, so the event log grows fast. SSE resume and scrubbing need efficient queries; storing large payloads as blobs is one option.