# Bugs # M1 — One agent end to end # M2 — Seeing the work - 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. Terminals don't survive a byre restart. - 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. # 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.