Fix setup: shell PATH, restart race, Tailscale wait, macOS 27 grants

internal/agents/clients.go

@@ -262,7 +262,7 @@ func (m *Manager) clientTools(l *live) []mcp.Tool {
 			Description: "Call one of your hands tools (screen_list, capture, ax_tree, act, browser, chrome) on a client Mac instead of the Mac byre runs on: " +
 				"tool is the tool's name and arguments exactly what that tool takes. Window ids, refs, displays and Chrome tabs are that Mac's, so start with screen_list (or chrome tabs) there. " +
 				"Every agent using that Mac shares one set of refs, so read the tree again if another agent may have. " +
-				"A call fails until the human has given byre's app Screen Recording and Accessibility (and Automation of Orion, for browser) on that Mac; say so when it does. " +
+				"A call fails until the human has given byre's app Screen Recording and Device Control and Data Access (and Automation of Orion, for browser) on that Mac; say so when it does. " +
 				"chrome needs Google Chrome installed on that Mac; its trace files are saved there, so fetch one with client_download.",
 			InputSchema: json.RawMessage(`{
 				"type": "object",

internal/agents/kb/setup.md

@@ -11,14 +11,15 @@ Go one step at a time: check, say in a line or two what is missing and what it i
 Agents run on the Mac byre runs on, the one your own Bash runs on. Check its tools with:
 
 ```
-"$SHELL" -l -c '/Applications/Byre.app/Contents/Helpers/byre check'
+"$SHELL" -l -i -c '/Applications/Byre.app/Contents/Helpers/byre check'
 ```
 
 It prints one JSON line: `ready` (false while something blocking is missing) and `checks`, each with `name`, `need` (`required`; `agent`, where one of claude, codex and agy is enough; or `optional`), `for` (what it is used for), `ok`, `command` (what installs it), `fix` (what to do after) and `blocking`.
 
 - Run each missing tool's `command` yourself through the login shell, `"$SHELL" -l -c '<command>'`. `brew` must be there first; installing Homebrew asks for the human's password, so ask them to run its installer in a terminal on that Mac (the app's Server tab there lists each missing tool with a Run in Terminal button). `xcode-select --install` opens a macOS dialog on that Mac's screen for the human to click Install.
 - Sign-in needs the human at a terminal on that Mac: `claude`, `codex login` or `agy`, each run once. `claude auth status` (JSON, `loggedIn`) and `codex login status` show whether one is signed in; agy has no status command, so ask.
-- The service's `PATH` is fixed when it is installed, and your own shell has the same one. When a tool is found through the login shell but not by `/Applications/Byre.app/Contents/Helpers/byre check` run directly, reinstall the service from the login shell so it picks the new `PATH` up: `"$SHELL" -l -c '/Applications/Byre.app/Contents/Helpers/byre install'`. That restarts byre and cuts your turn off; you resume with a restart message, so say before running it that you will carry on afterwards.
+- The service's `PATH` is fixed when it is installed, and your own shell has the same one. It comes from an interactive login shell (`-l -i`), since claude's installer has the human add `~/.local/bin` to `.zshrc`. When a tool is found through that shell but not by `/Applications/Byre.app/Contents/Helpers/byre check` run directly, reinstall the service from it so it picks the new `PATH` up: `"$SHELL" -l -i -c '/Applications/Byre.app/Contents/Helpers/byre install'`. That restarts byre and cuts your turn off; you resume with a restart message, so say before running it that you will carry on afterwards. When you resume, check with `byre check` before reinstalling again: the restart usually took.
+- `byre install` and the app's Server tab (Turn off, Turn on) are the only ways to restart byre's service. Never run `launchctl` on it yourself, and never tell the human to.
 - Google Chrome, for agents' browser tools, asks "downloaded from the Internet" on its first launch, and can't be driven until the human answers Open.
 
 ## Permissions on the server's Mac
@@ -32,7 +33,7 @@ d=$(mktemp -d) && cp /Applications/Byre.app/Contents/Helpers/byre-hands "$d/" &&
 It prints a JSON array, one entry per grant: `name`, `status` (`granted`, `missing`, or `unchecked` when the test couldn't run, such as Automation of Orion while Orion isn't running), `detail` (what to switch on) and `settings`, the `x-apple.systempreferences` URL of its System Settings pane.
 
 - A missing folder grant makes macOS show a prompt on that Mac's screen during the check, and the check waits until it is answered, so tell the human to be at that Mac before you run it, and give the call a timeout of a few minutes.
-- For Screen Recording, Accessibility and Automation, open the pane for the human with `open '<settings>'` and tell them which switch to turn on. Accessibility can list byre switched off; only the switch being on counts.
+- For Screen Recording, Device Control and Data Access (what macOS 27 calls Accessibility) and Automation, open the pane for the human with `open '<settings>'` and tell them which switch to turn on. On a Mac that runs a server, the panes list two entries: `byre` with a black terminal icon is the server, whose grants agents on that Mac use, and `Byre` with byre's app icon is the app, whose grants client tools on that Mac use. The check's `detail` names the one it checked. Device Control and Data Access can list byre switched off; only the switch being on counts.
 - Check again after the human says they've done it.
 
 ## Client Macs

internal/agents/lead.go

@@ -31,7 +31,7 @@ const leadGuidance = `You are the human's lead agent in byre, shown in the left
 - Reviews: after each new snapshot of a task, the stages of its project's review workflow (a saved workflow whose stages are single agents, set per project with set_review_workflow) review the change, each a reviewer agent on its stage's model; a stage after others gets their reviews. A project with no review workflow isn't reviewed. Once every stage has reviewed the snapshot, the task's agent gets all their findings in one message. The results are in the task's transcript, where its agent answers each finding with respond_to_finding (fixing, or ignoring with a reason), and read_transcript shows each review's findings. They are for the human to look at when they want; mention one only when its findings matter to what the human is deciding.
 - Dig into context with list_tasks, read_transcript, read_inbox and read_status (vendor rate limits and agent health), and with your own Read, Grep and Bash on a task's worktree path (from list_tasks). Don't edit files in task worktrees; ask the task's agent with send_message.
 - You can create tasks, start TODO items, message, interrupt and compact task agents, and merge or discard tasks. Merge pushes to the default branch and Discard destroys work: do either only when the human asks for it.
-- Setup: when the human asks you to set byre up, or about the tools or macOS permissions its agents need, read the setup knowledge-base article and walk them through it, running its checks and fixes yourself with your own Bash on this Mac and with list_clients and client_bash on their Macs.
+- Setup: when the human asks you to set byre up, or about the tools or macOS permissions its agents need, read the setup knowledge-base article and walk them through it, running its checks and fixes yourself with your own Bash on this Mac and with list_clients and client_bash on their Macs. Never restart byre with launchctl or tell the human to; the article says how.
 - Projects: when the human asks you to add a project, create it with create_project from its name and the path of its git repository on this machine.
 - Workflows: you manage the server's workflows with list_workflows, read_workflow, save_workflow and delete_workflow, and run one by giving its name to create_task or start_todo. A workflow is a tree of steps run in order, each a stage, an order or a parallel; every stage runs as its own task on the stage's model once the step before it has finished, so stages fan out (a parallel after a stage) and fan in (a stage after a parallel); a stage's agent calls finish_stage to hand its output to the stages after it, signals tell you when a stage starts and when the workflow finishes, and the workflow finishes once every stage has; byre then discards the run's other stage tasks, leaving the task of each last stage (one per branch when it ends in a parallel) to merge. Each last stage's agent is asked whether its task is ready to merge as soon as its own stage has finished and been reviewed, without waiting for the other last stages. Whenever you show or propose a workflow, draw it as a fenced diagram block (its format is the diagrams knowledge-base article) of its stage names only, with no models: one row per step, a parallel's stages side by side in one row, and an arrow into each stage from the stages before it. For example, rows holding Build; Review and Test; Fix, with the arrows "build -> review", "build -> test", "review -> fix" and "test -> fix".
 - Schedules: when the human asks for work to run on a timer (every Monday, nightly), you manage it with list_schedules, save_schedule and delete_schedule; the human sees and edits the same schedules on the project's dashboard. Every schedule runs a saved workflow: for a one-agent chore, save a one-stage workflow with save_workflow first. On each run, byre starts the schedule's workflow as create_task with workflow would, created by byre, and you get its created signal; a run that fails to start reaches you as a signal.