P1 follow-up: Ship an agent-callable Workbench diagnostics CLI and structured setup log

[100yenadmin]

Parent tracker: #623

Related P0s: #655, #662
Related agent-runtime path: #499, #688
Existing foundations: #438, #439, #440, #442
UI simplification owner: #662

Summary

Workbench already has useful diagnostic layers, but they are fragmented:

• the bundled desktop bridge exposes redacted JSON diagnostics, readiness, customer-Mac status, permissions, and audit-tail commands;
• Workbench has an internal evaos.workbench.diagnostic_packet.v1 used by its feedback flow;
• app logs and the Mac-control proof harness can collect additional evidence;
• the Mac & iPhone page mixes live state with large static status matrices, ownership contracts, and canary commands.

This makes a customer-facing screen look like the only place to inspect the system even though parts are already machine-readable. It also forces agents and support to correlate app IPC, bridge commands, logs, screenshots, and repo-only scripts.

Ship one supported, installed-app, read-only diagnostic entry point and a structured setup timeline so local agents and support can obtain the same redacted source-of-truth state without scraping the UI or requiring a source checkout.

Product boundary

The customer page should remain calm:

• current state;
• one exact next safe action;
• stop/revoke visibility;
• Report or Export diagnostics.

#662 owns customer onboarding and visible-page simplification. This issue owns the machine-readable diagnostic interface, setup event history, support bundle, and runbook contract.

This is observability and support tooling only. It must not change pairing, grants, broker routing, connector ownership, TCC behavior, CUA/Peekaboo selection, stop/revoke, or kill-switch semantics.

Required interface

Provide one supported command installed with the signed Workbench app. Final syntax may follow repository conventions, but it must support equivalent operations to:

• evaos-workbench status --json: fast current state with schema, freshness, and typed blocker;
• evaos-workbench diagnostics --json: the composite redacted Workbench diagnostic packet;
• evaos-workbench setup-log --json [--since ...]: bounded structured setup and recovery events;
• evaos-workbench support-bundle --output <path>: explicit, redacted export with manifest.

Reuse the existing diagnostic packet and bridge JSON providers. Do not add a second readiness model or parse rendered UI text.

Document deterministic behavior when Workbench is running and when it is not. If a layer is unavailable, return a typed unavailable/stale result rather than silently starting, repairing, rebinding, pairing, or granting anything.

Structured setup timeline

Record bounded, machine-readable events for the major setup and recovery transitions, including:

• app and bridge identity verification;
• connector start/readiness and listener-owner classification;
• private-network prerequisite and reachability state;
• permission state;
• broker pairing/grant state;
• selected account/workspace/runtime scope;
• first end-to-end agent control proof;
• stop, revoke, kill-switch, and recovery outcomes.

Each event needs a schema version, timestamp, safe reason code, source layer, freshness, and correlation/audit identifier where safe. Keep rotation and retention bounded.

Security and privacy requirements

Default output and bundles must not expose:

• tokens, secrets, cookies, auth headers, grants, callback material, credentials, or keychain contents;
• raw URLs, IP addresses, ports, private-network details, customer data, account email, raw prompts, or raw runtime logs;
• unredacted screenshots or accessibility trees.

Use the existing redaction stack and safe identifiers. Diagnostic files must be same-user readable only. Screenshot inclusion, if ever offered, requires explicit user consent and must be off by default.

CLI status and diagnostic operations must be provably non-mutating. A future repair command would be separate, explicit, approval-gated work.

Acceptance criteria

• A signed installed Workbench build exposes the documented command without a repository checkout or developer Python/package setup.
• CLI and UI consume the same diagnostic provider and report the same state, blocker category, source, and freshness for equivalent snapshots.
• status --json and diagnostics --json use stable versioned schemas, documented exit codes, and typed reason codes.
• The setup log is structured, bounded, rotated, and redacted.
• The support bundle includes a manifest plus the redacted diagnostic packet, setup events, bridge readiness/audit summary, and capped app-log evidence.
• Commands return useful typed output when the bridge is missing, listener ownership is wrong, the connector is down, permissions are missing, the broker session is stale, the app is stopped, or the agent runtime itself is broken.
• Invoking any read-only command does not start/stop/rebind the connector, create/revoke grants, alter TCC, launch customer control, or mutate selected scope.
• The agent/support runbook names the exact installed command, schemas, safe collection flow, and escalation path.
• P0: Workbench fresh-Mac onboarding depends on unbundled Python and manual private-network setup #662 can remove static developer contract/canary material from the normal customer journey without losing support visibility.
• Installed-app proof captures one CLI snapshot and compares it to the same-candidate UI and broker/runtime result.

Validation

• focused schema, exit-code, and running/stopped-state tests;
• parity tests proving UI and CLI share the provider;
• redaction fixtures/fuzz cases for obvious secret-like and customer-identifying data;
• non-mutation spies around connector, broker, grant, TCC, and selected-scope services;
• log rotation, file-mode, retention, and corrupt-record recovery tests;
• signed installed-app smoke from the exact candidate path;
• git diff --check and canonical GitHub Actions checks.

Sequencing

This is not a P0 and must not delay or broaden #655/#662 or the active connector/runtime repairs. Land it afterward, or as a demonstrably non-colliding slice, once current customer access is restored and exact-head proof is green.

Stop conditions

Stop and update #623 if implementation would:

• duplicate readiness or redaction logic;
• expose secrets, endpoints, customer data, or raw runtime logs;
• require renderer-owned trust or direct renderer access to native credentials;
• make a read-only command mutate connector, broker, permission, pairing, or control state;
• replace end-to-end runtime proof with a self-reported diagnostic snapshot.

[coderabbitai]

🔗 Related PRs

#391 - Restore beta3 Mac pairing baseline [merged]
#403 - fix: recover Mac control installed app states [merged]
#416 - Fix Mac control connector-service ready reconciliation [merged]
#465 - Fix Mac connector readiness probe [merged]
#668 - feat(workbench): guide pristine Mac network recovery [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!