Moved from the README's Gotchas section. Each item cost a deploy cycle once. Host names are written as placeholders or as "an M4 Mac mini".
- Keep the
LoopbackHTTPServera global. Declared insidedo {}it was released at the end of the block; the listener stayed bound, accepted connections, and never answered — the[weak self]handlers were no-ops.curlhung to its timeout with no server log line. codesignover SSH →errSecInternalComponentfor anything in the login keychain, with or withoutssh -t. Sign from a dedicated keychain whose password is on disk (KEYCHAIN/KEYCHAIN_PASSWORD_FILEindeploy.sh), passing--keychainexplicitly.kiro-cli mcp add --forcetruncated~/.kiro/settings/mcp.jsonto 0 bytes the second time it was used in a session. Back the file up beforemcp add, or edit it by hand.- macOS has no
timeout. Remote scripts bound steps withperl -e 'alarm shift; exec @ARGV'andcurl -m. Write them as bash files: zsh does not word-split$VAR, soC="curl -s -m 10"; $C …is "command not found". tccutil reset ScreenCapture <bundle-id>does not make the prompt appear. After the first denial the system records it and further capture attempts fail silently; the grant has to be toggled in System Settings on the machine's own display.- The setup wizard's Allow button calls the system request, and a recorded denial stays silent.
CGRequestScreenCaptureAccess()andAXIsProcessTrustedWithOptionswith the prompt option run only when a user clicks Allow in the wizard. After an earlier denial they show no prompt, so the wizard re-tests and opens the matching System Settings pane instead. Revocation is checked every 30 seconds with preflight calls only (CGPreflightScreenCaptureAccess,AXIsProcessTrusted), which never prompt and never capture. - Display sleep = black screenshots. An M4 Mac mini shipped with
displaysleep 3; the first screenshot after a quiet spell was solid black with a cursor.pmset -a displaysleep 0. - A stuck
osascriptis usually a consent dialog. First AppleEvent to an app pops an Automation prompt on the Mac; the call blocks until answered. Over SSH the prompt is attributed tosshd-keygen-wrapper— decline those; only the agent bundle should hold Automation grants. launchctl bootoutreturns before the job is gone; an immediatebootstrapfails and, underset -e, took the deploy script with it — leaving no agent running. Poll untillaunchctl printfails before bootstrapping.- Model vision vs capture. At scale 0.5 a 1080p menu bar is ~12 px tall and the model refuses
to read it (correctly). Default is now scale 1.0; for text, crop with
regionatscale: 2. /tmpis/private/tmp—execreports resolved paths.zsh -fis deliberate: the user's.zshenvsources a RAID-path.cargo/envthat fails under launchd. Callers get a clean shell; setenvexplicitly if they need PATH additions.- A LaunchAgent cannot read external volumes without Full Disk Access. A
cwdon/Volumes/…(e.g. a RAID where builds live) does not fail with EPERM — the syscall blocks, so an un-guardedexecwould hang to its timeout. Two fixes:ExecCwdtime-boxes a readability probe and returns a clear "grant Full Disk Access to dev.openab.computer" error instead of hanging; and granting FDA to the bundle in System Settings → Privacy & Security → Full Disk Access makes the volume readable (verified 2026-09-23: samels /Volumes/…went from a 15 s timeout to 39 ms). The grant sticks across re-signing like the Screen Recording / Accessibility ones.exec_startbuilds on the RAID work once FDA is granted.