no-mistakes(review): Captain: require observed macOS permission attribution

Author: ruby-dlee

bin/fm-macos-permissions.sh

@@ -353,34 +353,34 @@ printf '\n'
 
 printf '%s\n' 'Ghostty (terminal launcher)'
 print_permission 'Full Disk Access' 'CONDITIONAL' "$ghostty_fda" \
-  'Needed only for protected Mail, Messages, Safari, Home, backup, or administrative data.'
+  'Protected-path work needs the exact responsible entry macOS observes; add Ghostty only when macOS names it.'
 print_permission 'Automation' 'CONDITIONAL' 'PER TARGET' \
-  'Needed only for Apple Events from Ghostty to System Events or another named app; tmux does not use it.'
+  'The first-use Allow dialog establishes the exact controller-to-target pair for terminal-driven app automation; tmux does not use Apple Events.'
 print_permission 'Screen Recording' 'CONDITIONAL' "$ghostty_screen" \
-  'Needed for native desktop capture in this launch context, not for Chrome DevTools Protocol screenshots.'
+  'Native desktop capture needs the exact responsible entry macOS observes; add Ghostty only when macOS names it.'
 print_permission 'Accessibility' 'CONDITIONAL' "$ghostty_accessibility" \
-  'Needed for native UI inspection or input in this launch context, not for tmux or browser-protocol control.'
+  'Native UI control needs the exact responsible entry macOS observes; add Ghostty only when macOS names it.'
 printf '\n'
 
 printf 'Claude Code PATH command target (%s)\n' "${claude_binary:-UNKNOWN: not found on PATH}"
 print_permission 'Full Disk Access' 'LAUNCHER OR CONDITIONAL' "$claude_fda" \
   'Use the exact responsible entry macOS observes for protected-path access; command ancestry alone does not establish it.'
 print_permission 'Automation' 'CONDITIONAL' 'PER TARGET' \
-  'Needed only when Claude sends Apple Events to a named app; it is not needed for tmux.'
+  'The first-use Allow dialog establishes the exact controller-to-target pair for app automation; approve Claude only when macOS names it as controller.'
 print_permission 'Screen Recording' 'CONDITIONAL' "$claude_screen" \
-  'Needed only if a Claude-launched native visual tool captures the desktop.'
+  'Native desktop capture needs the exact responsible entry macOS observes; command ancestry does not establish it.'
 print_permission 'Accessibility' 'CONDITIONAL' "$claude_accessibility" \
-  'Needed only if a Claude-launched native UI tool inspects or controls other applications.'
+  'Native UI control needs the exact responsible entry macOS observes; command ancestry does not establish it.'
 printf '\n'
 
 printf 'Codex PATH command target (%s)\n' "${codex_binary:-UNKNOWN: not found on PATH}"
 print_permission 'Full Disk Access' 'LAUNCHER OR CONDITIONAL' "$codex_fda" \
   'Use the exact responsible entry macOS observes for protected-path access; the current PATH command does not establish it.'
 print_permission 'Automation' 'CONDITIONAL' 'UNKNOWN' "$codex_automation_note"
 print_permission 'Screen Recording' 'REQUIRED FOR COMPUTER USE' "$codex_screen" \
-  'Native Computer Use needs screen pixels; chrome-devtools-axi page screenshots do not.'
+  'Native Computer Use needs screen pixels for the exact responsible entry macOS observes; DevTools screenshots do not.'
 print_permission 'Accessibility' 'REQUIRED FOR COMPUTER USE' "$codex_accessibility" \
-  'Native Computer Use needs the macOS accessibility tree and input control.'
+  'Native Computer Use needs Accessibility for the exact responsible entry macOS observes.'
 printf '\n'
 
 printf 'no-mistakes CLI PATH entry (%s)\n' "${no_mistakes_command:-UNKNOWN: not found on PATH}"
@@ -405,7 +405,7 @@ print_permission 'Accessibility' 'REQUIRED FOR COMPUTER USE' "$no_mistakes_acces
   'Daemon-launched Computer Use needs UI control, but the responsible identity is unknown; use the exact Accessibility entry macOS observes.'
 printf '\n'
 
-printf '%s\n' 'Stored Automation relationships'
+printf '%s\n' 'Stored Automation candidate relationships (not proof of responsibility)'
 print_automation_pairs 'Ghostty' com.mitchellh.ghostty "$ghostty_binary"
 print_automation_pairs 'Claude Code' com.anthropic.claude-code "$claude_command" "$claude_binary"
 print_automation_pairs 'Codex' codex "$codex_command" "$codex_binary" \

docs/macos-permissions.md

@@ -34,52 +34,58 @@ macOS may attribute `claude`, `codex`, or descendant requests to Ghostty, but co
 
 The no-mistakes daemon is launched independently by launchd, so a Ghostty grant does not by itself establish access for gate agents spawned by that daemon.
 
-When macOS lists a different responsible entry than this guide predicts, grant only that observed entry and preserve the controller-to-target relationship shown for Automation.
+For every service, grant only the responsible entry macOS observes and preserve the controller-to-target relationship shown for Automation.
 
 Apple recommends the TCC attribution log for finding that responsible app or binary on managed machines, and the same read-only log is useful during local diagnosis.
 
 ## Ghostty
 
 - **Full Disk Access - captain must click when protected data is in scope.**
-  Add `/Applications/Ghostty.app` when firstmate or a terminal-launched agent must read Mail, Messages, Safari, Home, Time Machine backups, or protected administrative data.
+  Terminal-launched work needs this capability only when it must read Mail, Messages, Safari, Home, Time Machine backups, or protected administrative data.
+  Grant only the exact responsible entry macOS observes for that protected-path service.
+  Add `/Applications/Ghostty.app` only when macOS attributes that protected-path service to Ghostty.
   Firstmate state and repositories stored under ordinary unprotected home-directory paths do not require this grant.
-- **Automation - captain must approve each requested target when Apple Events are in scope.**
-  Click Allow in the first target-specific dialog for Ghostty controlling System Events or the other named application.
+- **Automation - captain must approve each requested target when terminal-driven app automation is in scope.**
+  Trigger the required operation and use the first-use Allow dialog to identify the exact controller-to-target pair macOS observes.
+  Approve Ghostty controlling a target only when macOS shows Ghostty as the controller for that exact pair.
   If that request was denied or later disabled, review or enable the relationship under Automation in System Settings.
   Do not grant Automation for tmux control because tmux never uses Apple Events.
 - **Screen & System Audio Recording - captain must approve when native desktop capture is in scope.**
-  This unlocks `screencapture`, ScreenCaptureKit, or native Computer Use when TCC attributes the request to Ghostty.
-  Click Allow or Allow While Using the App if macOS presents the first-use dialog, or add or enable Ghostty in System Settings if access was denied, disabled, or must be added manually.
+  This unlocks `screencapture`, ScreenCaptureKit, or native Computer Use for the exact responsible entry macOS observes.
+  Approve Ghostty only when macOS attributes that Screen Recording request to Ghostty.
+  Click Allow or Allow While Using the App if macOS presents the first-use dialog, or add or enable the observed entry in System Settings if access was denied, disabled, or must be added manually.
   It is not needed for `chrome-devtools-axi` page screenshots.
 - **Accessibility - captain must click when native application control is in scope.**
-  This unlocks accessibility-tree inspection, focus changes, clicks, typing, and other UI control when TCC attributes the request to Ghostty.
+  This unlocks accessibility-tree inspection, focus changes, clicks, typing, and other UI control for the exact responsible entry macOS observes.
+  Approve Ghostty only when macOS attributes that Accessibility request to Ghostty.
   It is not needed for tmux or Chrome DevTools Protocol control.
 
 ## Claude Code
 
 - **Full Disk Access - captain must click only when macOS attributes protected access to a separate entry.**
   Grant only the exact responsible entry macOS observes when protected data is in scope because command ancestry alone cannot identify it.
-- **Automation - captain must approve each requested target when Claude sends Apple Events.**
-  The relationship is Claude Code controlling System Events or another named application, and it appears only after that target-specific request.
+- **Automation - captain must approve each requested target when this workflow performs app automation.**
+  Trigger the required operation and use the first-use Allow dialog to identify the exact controller-to-target pair macOS observes.
+  Approve Claude Code controlling a target only when macOS shows Claude Code as the controller for that exact pair.
   Click Allow in the first dialog, or use Automation in System Settings to review or change a recorded relationship.
   Claude Code does not need Automation for tmux.
 - **Screen & System Audio Recording - no baseline grant is needed.**
-  Grant the responsible entry only if a Claude-launched native visual tool captures the desktop rather than a browser page through DevTools.
+  Grant the exact responsible entry macOS observes only if a native visual tool invoked by this workflow captures the desktop rather than a browser page through DevTools.
   Approve a first-use dialog if macOS presents one, or use System Settings after denial or when adding the entry manually.
 - **Accessibility - no baseline grant is needed.**
-  Grant the responsible entry only if a Claude-launched native UI tool inspects or controls another application.
+  Grant the exact responsible entry macOS observes only if a native UI tool invoked by this workflow inspects or controls another application.
 
 ## Codex
 
 - **Full Disk Access - captain must click only when macOS attributes protected access to a separate entry.**
   Grant only the exact responsible entry macOS observes when protected data is in scope because the current Codex command path cannot identify it.
-- **Automation - captain must approve each requested target when Codex sends Apple Events.**
+- **Automation - captain must approve each requested target when this workflow performs app automation.**
   The helper reports Codex Automation capability as `UNKNOWN` because a command found on `PATH` does not establish the active TCC controller identity.
   When possible, it separately reports the exact `codesign` result for that current command filesystem target without applying the result to another installation or running process.
-  Click Allow in the first dialog, or use Automation in System Settings to review or change a recorded relationship.
+  Trigger the required operation and approve only the controller-to-target pair shown by the first-use Allow dialog, or use Automation in System Settings to review or change a recorded relationship.
   Apple documents that entitlement as permission to prompt rather than permission to bypass the prompt in [Apple Events Entitlement](https://developer.apple.com/documentation/bundleresources/entitlements/com.apple.security.automation.apple-events).
 - **Screen & System Audio Recording - captain must approve for native Codex Computer Use.**
-  This unlocks desktop pixels for Computer Use when the responsible entry is Codex, Ghostty, or the Codex Computer Use helper shown by macOS.
+  This unlocks desktop pixels for Computer Use only for the exact responsible entry macOS observes for that Screen Recording request.
   Click Allow or Allow While Using the App if macOS presents the first-use dialog, or add or enable the responsible entry in System Settings if access was denied, disabled, or must be added manually.
   It is not needed for `chrome-devtools-axi` page screenshots.
 - **Accessibility - captain must click for native Codex Computer Use.**
@@ -94,7 +100,7 @@ Apple recommends the TCC attribution log for finding that responsible app or bin
   Use the exact responsible entry shown by macOS or TCC attribution, and treat the configured path printed by the helper as diagnostic evidence only.
   A Ghostty Full Disk Access grant does not by itself establish protected-path access for the independently launched daemon tree.
 - **Automation - captain approval is necessary but not sufficient for daemon-launched Apple Events.**
-  Automation is still a pair such as no-mistakes controlling System Events or another named application.
+  Trigger the required operation and use the first-use Allow dialog to identify the exact controller-to-target pair macOS observes.
   The helper reports the running daemon capability as `UNKNOWN` because inspecting the configured path cannot establish the entitlement of an already loaded process image.
   Apple documents the entitlement as target-signing-dependent, so a separate current-image inspection is required before making any capability claim.
 - **Screen & System Audio Recording - captain must approve for daemon-launched Codex Computer Use.**

tests/fm-macos-permissions.test.sh

@@ -145,6 +145,35 @@ test_missing_probe_is_honest() {
   pass 'missing and undetectable grants are reported honestly'
 }
 
+test_permission_guidance_requires_observed_attribution() {
+  local world out docs
+  world=$(make_world attribution-guidance)
+  out=$(run_report "$world")
+  docs=$(<"$ROOT/docs/macos-permissions.md")
+
+  assert_contains "$out" \
+    'Protected-path work needs the exact responsible entry macOS observes; add Ghostty only when macOS names it.' \
+    'Ghostty Full Disk Access guidance assumed responsibility'
+  assert_contains "$out" \
+    'The first-use Allow dialog establishes the exact controller-to-target pair for terminal-driven app automation' \
+    'terminal Automation guidance assumed a controller-to-target pair'
+  assert_contains "$out" \
+    'approve Claude only when macOS names it as controller' \
+    'Claude Automation guidance assumed the controller identity'
+  assert_contains "$docs" \
+    'only when macOS attributes that protected-path service to Ghostty.' \
+    'documentation assumed Ghostty Full Disk Access responsibility'
+  assert_contains "$docs" \
+    'use the first-use Allow dialog to identify the exact controller-to-target pair macOS observes.' \
+    'documentation did not require observed Automation attribution'
+  case "$out$docs" in
+    *'Apple Events from Ghostty to System Events'*|*'The relationship is Claude Code controlling'*)
+      fail 'fixed controller or target attribution remained in guidance'
+      ;;
+  esac
+  pass 'permission guidance requires macOS-observed attribution'
+}
+
 test_readable_database_reports_stored_rows() {
   local world out ghostty_section daemon_section
   world=$(make_world readable)
@@ -406,6 +435,7 @@ test_non_macos_refuses() {
 }
 
 test_missing_probe_is_honest
+test_permission_guidance_requires_observed_attribution
 test_readable_database_reports_stored_rows
 test_mixed_identity_evidence_is_unknown
 test_partial_database_evidence_is_unknown