Spike: revisit multi-host transport decision — TCC diagnosis and Developer ID signing feasibility

[deverman]

User outcome

A Claude Desktop (or other desktop-app-hosted MCP client) user gets either a
documented, supported FocusRelay setup path, or a documented, evidence-backed
"not supported yet" with a tracked follow-up — instead of a silent bridge
timeout. The spike's deliverable is a decision, not code: an updated
transport decision document and, if warranted, a follow-up implementation
issue.

Validation impact

docs — the spike produces diagnostic evidence and an updated decision
document only. No production code changes; any implementation happens under
a follow-up issue with its own (likely transport-reliability) impact.

Current evidence

• FocusRelay works under terminal-launched MCP hosts (Claude Code, OpenCode)
  and fails under Claude Desktop on macOS 26/27: the server starts and
  handshakes, but bridge round trips never complete.
• Verified on a failing machine: Claude Desktop's app bundle is not
  sandboxed (no com.apple.security.app-sandbox entitlement), while
  OmniFocus 4 is. The failure layer is therefore not app-sandbox
  inheritance but macOS TCC App Data protection
  (kTCCServiceSystemPolicyAppData, macOS 14+) over another app's
  ~/Library/Containers — which is exactly where the FocusRelay IPC
  rendezvous lives, because Omni Automation URL-scheme scripts can only
  write inside OmniFocus's own container.
• The grant follows the requesting binary's code identity, and Full Disk
  Access does not substitute (SystemPolicyAllFiles ≠
  SystemPolicyAppData).
• Direct architectural analog: omnifocus-operator (same
  container-rendezvous design) has this exact bug open —
  HelloThisIsFlo/omnifocus-operator#2.
  Their diagnosis: ad-hoc or self-signed identities get the grant recorded
  with auth_value=5 (not honored), causing endless re-prompts or denials;
  their planned fix is a Developer ID-signed + notarized launcher.
• Corroboration from Claude Desktop MCP issues:
  anthropics/claude-code#27557,
  #36832,
  #63032,
  #66216 —
  App Data prompts fire but grants don't persist through unsigned helper
  chains; Apple Events (osascript) remains promptable and functional.
• Competitors using osascript/JXA with stdout return paths
  (themotionmachine/OmniFocus-MCP, jqlts1/omnifocus-mcp-enhanced,
  vitalyrodnenko/OmnifocusMCP) report zero permission-wall issues:
  their data path never crosses the OmniFocus container boundary.
• Constraint: the roadmap Standing Decision (finalized in Consolidate on plugin-url and move pure JXA out of the shipped runtime #80,
  docs/transport-decision-2026-03-13.md) says plugin URL dispatch through
  the Bridge plugin is the only architecture. This spike explicitly
  revisits that decision with new evidence; the decision doc is the
  deliverable that either reaffirms or amends it.

Prerequisite

Options 1 and 2 below require an Apple Developer Program membership
(US$99/year) for Developer ID signing and notarization. Task 1 (the TCC
diagnostic) is free and must run first — its result determines whether
signing can help at all, before any money is spent. Option 3 requires no
signing.

Proposed scope (ordered, with kill/keep gates)

1. TCC attribution diagnostic (free, mandatory first). Under Claude
   Desktop, trigger a bridge call while capturing
   log stream --predicate 'subsystem == "com.apple.TCC"' and classify the
   recorded auth_value for the requesting identity. The critical unknown:
   is the focusrelay child process attributed to its own code identity or
   to the host app's responsible process? This gates everything after it.
2. Option 1 — Developer ID sign + notarize the existing Homebrew binary.
   Keep if the App Data grant is honored (auth_value=2, prompt names
   FocusRelay): zero architecture change, zero hot-path cost. Kill if
   responsible-process attribution routes the grant to the host app.
   Includes pipeline scoping: codesign + notarytool + stapling in
   scripts/package-release.sh, and whether the tap tarball
   (deverman/homebrew-focus-relay) preserves signature and notarization
   through download/quarantine.
3. Option 2 — signed LaunchAgent broker (only if Option 1 dies). A
   launchd-managed singleton owns the IPC client under its own TCC
   identity; focusrelay serve becomes a thin stdio shim. Also solves
   multi-host contention (cf.
   themotionmachine/OmniFocus-MCP#80
   arriving at the same launchd-singleton idea). Installer/uninstaller UX
   folds into Add guided setup for Homebrew-installed FocusRelay #92 guided setup — no second installer path. Kill on
   unacceptable setup friction; a background agent users don't understand
   is a real adoption cost.
4. Option 3 — osascript/JXA stdout return path (Desktop-only degraded
   mode). Competitor-proven under Claude Desktop; still executes OmniJS
   inside OmniFocus (documented-API contract holds); requires no signing.
   Conflicts with the Consolidate on plugin-url and move pure JXA out of the shipped runtime #80 Standing Decision and adds per-request osascript
   spawn cost — evaluate strictly as a documented fallback for hosts where
   the container is unreachable, never the terminal-client path.
5. Decision doc + follow-up. Update docs/transport-decision-2026-03-13.md
   (or successor) with: verbatim TCC log evidence (usernames stripped),
   codesign -dv/spctl -a output per tested identity, a host × option
   result matrix, terminal-path latency proof-of-no-change, and an explicit
   stands-or-amended verdict on the Standing Decision. File the follow-up
   implementation issue if any option survives.

Performance budget

The terminal-client hot path (Claude Code, OpenCode, Codex CLI) must be
code-path-identical before and after any multi-host change. Zero
per-request regression is tolerated; Desktop enablement may only add cost
to a Desktop-specific path. Canary-profile before/after evidence on the
unchanged terminal path is required in the follow-up issue.

Safety and compatibility

• No production code changes in this spike; no release invalidation.
• Diagnostic steps read TCC state and logs only; no TCC.db modification.
• Depends on the IPC hardening issue landing first: hardening defines the
  on-disk contract and permissions any broker or signed binary would own.
• Add guided setup for Homebrew-installed FocusRelay #92 guided setup should not finalize its installer flow until this
  spike's signing verdict lands, since a Developer ID pipeline (or a
  LaunchAgent) directly shapes it.

Acceptance criteria

• TCC diagnostic evidence captured and classified (service, identity,
  attribution, auth_value), with usernames stripped from paths.
• Each option has an explicit keep/kill verdict backed by recorded
  evidence; untested options state why.
• Transport decision doc updated with the evidence list above and an
  explicit verdict on the Standing Decision.
• Follow-up implementation issue filed (or an explicit "no viable path;
  revisit when X changes" recorded).
• No code merged from this spike.

Non-goals

• Implementing any transport change.
• Changing the default plugin-URL architecture for terminal clients.
• Installer/uninstaller work (belongs to Add guided setup for Homebrew-installed FocusRelay #92).
• Revisiting JXA for terminal clients.
• README changes beyond linking this issue (handled separately).

[deverman]

Field evidence: code identities captured on a failing machine (macOS 27)

Observed process chain when Claude Desktop hosts the server:

disclaimer (PID p1)  /Applications/Claude.app/Contents/Helpers/disclaimer /opt/homebrew/bin/focusrelay serve
└─ focusrelay (PID p2, ppid p1)  /opt/homebrew/bin/focusrelay serve

codesign -dv on both binaries:

Binary	Identifier	Signature	TeamIdentifier
Claude.app/Contents/Helpers/disclaimer	disclaimer	signed	Q6L2SF6YDW
/opt/homebrew/bin/focusrelay (Homebrew 0.12.0-beta)	focusrelay	adhoc	not set

Two things this pins down before task 1 even runs:

1. FocusRelay is currently ad-hoc signed with no Team ID — precisely the identity condition omnifocus-operator#2 diagnosed as yielding auth_value=5 (grant recorded but never honored). So the null hypothesis for Option 1 is well-founded: our binary cannot hold a durable App Data grant in its present form.
2. The host-side helper carries Identifier=disclaimer — a bare name rather than reverse-DNS — matching the persistence defect reported in [BUG] Xcode MCP Server shows permissions request too often with Claude Code Desktop anthropics/claude-code#27557 and #63032.

This does not by itself decide the attribution question (task 1 still has to establish whether TCC attributes the file access to focusrelay or to the responsible parent). It does mean Option 1 cannot be evaluated by simply retrying the current Homebrew build: a Developer ID identity has to exist first, which is the point at which the Apple Developer Program prerequisite becomes blocking.

Note also observed on the same machine: several long-lived focusrelay serve processes (2-3 h uptime) from earlier host sessions, including one under the disclaimer parent. Worth confirming during the spike whether desktop hosts reliably terminate the child on disconnect, given the stdio-disconnect exit behavior added in #190.

[deverman]

Status: signing work is blocked; diagnostic work is not

The repository owner does not currently hold an Apple Developer Program membership, so Options 1 and 2 cannot start — both require a Developer ID identity for signing and notarization.

This does not block the whole spike. Task 1 (the TCC attribution diagnostic) is free, requires no membership, and is the task that decides whether paying for one is worth it:

• If TCC attributes the file access to focusrelay's own identity, a Developer ID becomes the concrete unblocker and the membership has a clear payoff.
• If TCC attributes it to the responsible parent process instead, then signing FocusRelay cannot help on its own, Option 1 dies before any money is spent, and evaluation moves to Option 2 (LaunchAgent, which changes the attribution by not being a child of the host) or Option 3 (osascript return path, which needs no signing at all).

Recommended sequencing given the constraint: run task 1, record the attribution result here, and only then decide on membership. Option 3 remains fully evaluable in the meantime.

Blocked-on marker for whoever picks this up: do not begin signing pipeline work until a Developer ID is available; the scripts/package-release.sh and tap-distribution scoping in task 2 depends on it.

[deverman]

Task 1 partial results — and the leading hypothesis is now in doubt

Captured 6 hours of com.apple.TCC unified-log output (121,056 lines) on the affected machine and extracted every focusrelay event. Note /usr/bin/log show works fine here; reading TCC.db directly still needs Full Disk Access, but the log carries the attribution and verdicts we need.

Finding 1 — TCC attributes access to focusrelay itself, not the parent

AUTHREQ_ATTRIBUTION: attribution={
  accessing={TCCDProcess: identifier=focusrelay, pid=…, auid=501, euid=501,
             binary_path=/opt/homebrew/Cellar/focusrelay/0.12.0-beta/bin/focusrelay},
  requesting={TCCDProcess: identifier=com.apple.sandboxd, …}}

The accessing identity is focusrelay, by its own binary path — not a responsible parent process. This was the single biggest unknown, and it is the favourable answer for the signing hypothesis: a grant keyed to our identity would in principle attach to us.

Finding 2 — our identity is keyed by Path, because we are ad-hoc signed

TCCDEvent: type=Create, service=kTCCServiceSystemPolicyAppDataDetailed,
           identifier_type=Path,
           identifier=/opt/homebrew/Cellar/focusrelay/0.12.0-beta/bin/focusrelay

identifier_type=Path is what TCC falls back to without a stable code identity. Note the path contains the version, so every Homebrew upgrade changes it and any path-keyed decision is orphaned on upgrade. That is a real argument for Developer ID signing independent of desktop hosts — but see below before acting on it.

Finding 3 — the requests we assumed were the gate are denied, yet everything works

Every focusrelay request in the window resolved to authValue=0 (denied; 2 is allowed, and 7,984 such results appear elsewhere in the same capture, so the legend is not in question):

msgID	service	preflight	authValue
569.129	kTCCServiceDeveloperTool	yes	0
429.7301	kTCCServiceSystemPolicyAllFiles	yes	0
429.7302-7305	kTCCServiceSystemPolicyAppDataDetailed	mixed	0

Those denials were recorded while FocusRelay was working normally from a terminal, reading and writing the OmniFocus container throughout. So on macOS 27, these particular services are not the operative gate on container access for this process — which directly undercuts the "App Data denial blocks the container" explanation this issue was opened with.

Finding 4 — the Claude Desktop instance produced no TCC events at all

A focusrelay serve process spawned by Claude Desktop (via Contents/Helpers/disclaimer) ran for ~2h49m during the capture window. It generated zero TCC events, because it never received a tool call and therefore never attempted container access. The desktop failure was never actually reproduced under observation.

Consequence: do not buy a Developer ID yet

The original diagnosis — TCC App Data protection denying the container to desktop-hosted processes — is not confirmed by this evidence and is partly contradicted by it. Spending on a membership to fix a misdiagnosed cause would be premature, and Option 1's kill/keep gate cannot be evaluated against a failure mode we have not observed.

Revised task 1

Task 1 is not complete. It needs a genuine reproduction under observation:

1. Re-add the focusrelay entry to claude_desktop_config.json and restart Claude Desktop.
2. Start /usr/bin/log stream --predicate 'subsystem == "com.apple.TCC"' and a second capture without the TCC predicate (the failure may not be TCC at all).
3. Ask Claude Desktop an OmniFocus question so the server actually receives a tool call.
4. Capture the error surfaced in Claude Desktop's MCP logs alongside whatever the system log shows at that moment.

Until step 3 happens, we are reasoning about a failure we have only heard described. Everything above should be read as narrowing the search, not as a diagnosis.

[deverman]

Parked — desktop hosts are out of scope for now

Product decision: FocusRelay targets terminal-based MCP clients (Claude Code, OpenCode, Codex CLI). Desktop-app support is not a near-term goal, so this spike is parked rather than scheduled.

State when parked:

• The README already states terminal-client support explicitly and links here, so users are not misled while this sits.
• Task 1 is incomplete. The evidence gathered so far narrows the search but does not identify a cause — see the previous comment. In particular, the App Data denial theory this issue was opened on is not supported by the captured logs, and the desktop failure has never been reproduced under observation.
• No money should be spent on an Apple Developer Program membership on the strength of this issue as it stands. The one finding that would justify signing on its own merits — TCC keying our identity by versioned Cellar path, which breaks on every upgrade — has no observed user impact, since terminal usage works regardless.

To resume: reproduce the failure first (re-add the desktop config, capture logs without assuming TCC, and issue a real tool call from the desktop app), then re-evaluate the options against what that shows.

Removed from the roadmap delivery order; priority label cleared.

[deverman]

Research update (2026-08-12): themotionmachine/OmniFocus-MCP has now implemented
the multi-agent design discussed in
their #80 through
PR #96.

Their shipped shape is an on-demand Unix-domain-socket daemon rather than the
launchd-managed server originally discussed:

• the existing stdio command becomes a thin shim, so client configuration does
  not change;
• one MCP session is created per socket connection, while all sessions share one
  process-global osascript concurrency budget;
• an atomic mkdir startup lock, stale-socket probe, zero-connection idle reap,
  and explicit no-daemon escape hatch cover the common lifecycle failures;
• a socket under a 0700 directory avoids a loopback TCP auth/token surface and
  does not require a newer MCP HTTP transport.

Useful lessons for any FocusRelay broker follow-up:

• require a shim/broker version handshake or versioned socket so an upgraded
  client cannot silently keep using an old daemon;
• verify ownership and repair permissions on an existing socket directory;
• do not silently fall back to independent mutation-capable servers if the
  broker is the component enforcing a global safety bound;
• bound or rotate persistent logs and audit every process-global mutable value;
• retain end-to-end cold-start, simultaneous-start, stale-socket, SIGKILL,
  disconnect, and upgrade coverage because their own smoke tests found two cold
  paths that unit tests missed.

This does not change this issue's TCC gate. Their daemon centralizes direct
osascript AppleEvents; it does not establish which code identity macOS will
attribute for FocusRelay's protected OmniFocus-container access. The free TCC
attribution diagnostic still runs first, and the terminal-client hot path stays
unchanged unless a separately measured FocusRelay problem justifies a product
change.

[deverman]

Roadmap status: parked and evidence-gated

Desktop-app hosts remain outside the supported terminal-client scope, so this spike is intentionally unmilestoned. Resume only if product scope expands to a named desktop host or supported-user evidence shows that terminal-only support is a material adoption blocker. #92 should implement the terminal setup path without selecting a broker, LaunchAgent, JXA fallback, or signing architecture from this parked spike.