Overview: The Need for Local AI Governance Logs
When coding assistants such as Claude Code, Cursor, Windsurf, or Codex interact with your App Store Connect account via MCP (Model Context Protocol), you need complete visibility into every call they make. Trusting an autonomous agent with release management requires a structured, append-only paper trail:
- What parameters did the AI propose?
- Did the operation modify Apple production resources or was it read-only?
- Who authorized the execution, and at what exact timestamp?
- If an operation failed on Apple's servers, what error code and diagnostics were returned?
FlightDeck solves this problem by embedding a high-throughput, file-backed audit subsystem directly into the macOS application. Every read query, staged proposal, approval action, rejected mutation, and network dispatch is structured and recorded to a local append-only JSON Lines file before and after communicating with Apple.
┌─────────────────┐ ┌──────────────────────┐ ┌────────────────────────┐
│ MCP Agent │ ────> │ FlightDeck Engine │ ────> │ BoundedFileAuditLogger │
│ (Claude/Cursor) │ │ (Validation/Approval)│ │ (audit.jsonl on disk) │
└─────────────────┘ └──────────────────────┘ └────────────────────────┘
│
▼
┌──────────────────────┐
│ App Store Connect │
│ REST API (Direct) │
└──────────────────────┘
This guide details the internal schema of FlightDeck's audit events, explains the mechanical guarantees of the local log storage, clarifies the distinction between operation logs and resource snapshots, and provides copyable commands and prompts to audit your AI assistant's activities.
The Audit Architecture: BoundedFileAuditLogger
FlightDeck's persistence layer implements the AuditLogger interface through BoundedFileAuditLogger. This service runs locally on your workstation and enforces three key architectural principles:
1. Local Storage Location
All events are recorded directly to disk on the developer's machine:
- macOS (Default):
~/Library/Application Support/asc_mcp/audit.jsonl - Linux/CLI Fallback:
~/.asc_mcp/audit.jsonl
No audit records are ever relayed to third-party tracking services or hosted cloud servers. The file is governed entirely by standard macOS POSIX file permissions under your user account (rw-------).
Audit File Integrity Boundaries: audit.jsonl is a high-throughput, append-only JSON Lines file protected by standard operating system discretionary access controls (DAC). It is not an HSM-signed, cryptographically sealed, or blockchain-verified ledger. Because it resides on the local workstation disk, local processes running under your macOS user account or root can inspect or modify it. For formal enterprise compliance regimes (such as SOC 2 or ISO 27001), forward events to a centralized SIEM pipeline as described below.
2. Bounded Retention via FIFO Trimming
To prevent long-running developer environments from exhausting disk space, the logger enforces a hard cap:
- Maximum Entries: 2,000 lines (
maxEntries = 2000). - Trim Threshold: 2,050 lines (
trimThreshold = 2050).
When the log exceeds 2,050 lines, FlightDeck triggers an atomic trimming routine. It retains the most recent 2,000 lines, writes them to audit.jsonl.tmp, flushes the buffer to disk, and executes an atomic POSIX rename over the active log file. This guarantees that your log contains recent history while preventing unbounded file growth.
3. Concurrency Safety and Cross-Process Locking
Because multiple processes—the FlightDeck Flutter desktop GUI, the background MCP server daemon, and command-line scripts—may interact with App Store Connect concurrently, all write operations acquire an exclusive cross-process file lock (_withCrossProcessLock). Each JSON line is written with an explicit flush (flush: true) before releasing the lock, eliminating race conditions and partial line corruption.
Anatomy of an AuditEvent
Each line in audit.jsonl is a self-contained, serialized JSON object representing an AuditEvent. Below is an annotated breakdown of the schema:
| Field | Type | Description |
|---|---|---|
id |
String | Unique UUIDv4 assigned at event creation. |
timestamp |
String (ISO 8601) | High-precision UTC timestamp when the event occurred. |
correlationId |
String? | Shared tracking ID tying related sub-operations or change sets together. |
initiator |
String | Originator of the action: MCP_AGENT, MACOS_UI, STANDALONE_CLI, or WORKFLOW. |
stage |
String | Lifecycle stage: requestPreDispatch, requestCompleted, dispatchedAndRejectedByApple, dispatchFailedLocally, blockedByPolicy. |
recordKind |
String | Category of operation: read, mutation, or workflow. |
operationId |
String | Canonical OpenAPI operation ID (e.g. appStoreVersions_updateInstance) or Change Set ID. |
httpMethod |
String | GET, POST, PATCH, DELETE, or BATCH. |
path |
String | Resolved App Store Connect REST URL or local endpoint. |
statusCode |
Integer | HTTP response status from Apple (e.g. 200, 201, 400, 409, 429). |
isReadOnly |
Boolean | True for non-mutating queries; false for operations modifying state. |
mutationFingerprint |
String? | SHA-256 hash of the normalized request payload. |
authorizationProvenance |
String? | Source of approval (e.g. DESKTOP_APPROVAL_CENTER, POLICY_ALLOWLIST). |
durationMs |
Integer? | Wall-clock execution time in milliseconds. |
requestSummary |
Map? | Sanitized key parameters passed to the operation (secrets masked). |
errorDiagnostics |
Map? | Parsed Apple error codes, error titles, and detail messages if failed. |
Example Audit Record: AI Staging and Execution
{
"id": "e4a19b88-4229-4d6b-8851-9efb27dca089",
"timestamp": "2026-11-04T14:22:15.341Z",
"correlationId": "cs_9012f4ba",
"initiator": "MCP_AGENT",
"stage": "requestCompleted",
"recordKind": "mutation",
"operationId": "appStoreVersionLocalizations_updateInstance",
"httpMethod": "PATCH",
"path": "https://api.appstoreconnect.apple.com/v1/appStoreVersionLocalizations/loc_88120",
"statusCode": 200,
"isReadOnly": false,
"mutationFingerprint": "9a7f34c2e68407de31f13b632fa5a7de2f913d85bc92047a06db99e6e589e472",
"authorizationProvenance": "DESKTOP_APPROVAL_CENTER",
"durationMs": 412,
"requestSummary": {
"localizationId": "loc_88120",
"locale": "en-US",
"whatsNewLength": 184
}
}
Parameter Logs vs. Full State Diffs
A critical distinction to understand when auditing AI actions in FlightDeck is the boundary between operation parameter logging and full entity state diffs:
┌────────────────────────────────────────────────────────────────────────┐
│ What FlightDeck Audit Logs Record (Captured Locally) │
├────────────────────────────────────────────────────────────────────────┤
│ • Canonical Tool Name: appStoreVersionLocalizations_updateInstance │
│ • Input Parameters: { localizationId: "loc_123", whatsNew: "..." } │
│ • Execution Timestamp: 2026-11-04T14:22:15Z │
│ • Approval Provenance: Human click in Desktop Approval Center │
│ • Cryptographic Hash: SHA-256 payload fingerprint │
│ • HTTP Result: 200 OK (duration 412ms) │
└────────────────────────────────────────────────────────────────────────┘
┌────────────────────────────────────────────────────────────────────────┐
│ What Is NOT Captured Locally in audit.jsonl │
├────────────────────────────────────────────────────────────────────────┤
│ • Complete before-and-after snapshots of Apple's remote database │
│ • Unchanged remote fields (e.g., 29 other locales not touched) │
│ • Historical version trees of remote resources prior to mutation │
└────────────────────────────────────────────────────────────────────────┘
Because App Store Connect is a complex distributed system containing hundreds of interconnected entity types (builds, localizations, in-app purchases, screenshots, sandbox testers), storing a complete snapshot of the entire application state before and after every single API call would require massive network roundtrips and dozens of read requests for every write.
Instead, FlightDeck logs the exact mutation intent: the payload submitted by the AI, the cryptographic signature verified at approval time, and Apple's response. When a full diff is needed before execution, the Desktop Approval Center fetches the target entity's existing values on demand to render an interactive side-by-side comparison.
Inspecting Audit Logs from the Terminal
Because audit.jsonl is standard JSON Lines, you can query and parse it using standard UNIX command-line utilities like jq, grep, and awk.
1. View the Last 10 Mutations Dispatched by AI
cat ~/Library/Application\ Support/asc_mcp/audit.jsonl \
| jq -c 'select(.recordKind == "mutation" and .initiator == "MCP_AGENT")' \
| tail -n 10 \
| jq '{timestamp, operationId, httpMethod, statusCode, durationMs}'
2. Find All Rejected or Failed Operations
cat ~/Library/Application\ Support/asc_mcp/audit.jsonl \
| jq 'select(.statusCode >= 400 or .stage == "dispatchedAndRejectedByApple") | {timestamp, operationId, statusCode, errorDiagnostics}'
3. Verify Mutation Payload Fingerprint
If you need to verify that an executed operation matched the exact payload approved in a Change Set:
cat ~/Library/Application\ Support/asc_mcp/audit.jsonl \
| jq 'select(.correlationId == "cs_9012f4ba") | {id, operationId, mutationFingerprint, authorizationProvenance}'
4. Continuous Live Tail During an AI Session
Run this in a dedicated terminal window while working with your AI assistant:
tail -f ~/Library/Application\ Support/asc_mcp/audit.jsonl \
| jq -c '{time: .timestamp, initiator: .initiator, op: .operationId, method: .httpMethod, status: .statusCode}'
Reviewing Logs in the FlightDeck Desktop UI
For developers who prefer a visual interface, FlightDeck provides a built-in Operation Logs viewer:
- Open FlightDeck Desktop on macOS.
- In the left navigation sidebar, click Operation Logs.
- Use the filter bar to isolate events: - Filter by Origin: Show only
MCP Agentcalls orManual GUIactions. - Filter by Type: ToggleMutations,Reads, orChange Sets. - Filter by Outcome: View onlySuccess (2xx),Client Error (4xx), orBlocked by Policy. - Click any log entry to open the detail drawer. The drawer presents the full JSON payload, the human approval timestamp, the raw Apple response headers, and any error messages returned by App Store Connect.
Enterprise Compliance and SIEM Ingestion
Because FlightDeck limits the local log to 2,000 entries by default, organizations with strict compliance or audit retention requirements (such as SOC 2, ISO 27001, or Sarbanes-Oxley) should stream log entries to a centralized SIEM (Security Information and Event Management) platform.
Recommended Log Forwarding Setup
You can deploy a lightweight forwarder (such as Vector, Fluent Bit, or a custom daemon) to tail audit.jsonl and ship records to your telemetry provider:
# Example Vector.dev configuration snippet
sources:
flightdeck_audit:
type: "file"
include:
- "/Users/*/Library/Application Support/asc_mcp/audit.jsonl"
read_from: "beginning"
transforms:
parse_json:
type: "remap"
inputs: ["flightdeck_audit"]
source: ". = parse_json!(.message)"
sinks:
datadog_siem:
type: "datadog_logs"
inputs: ["parse_json"]
default_api_key: "${DATADOG_API_KEY}"
compression: "gzip"
Prompt-First Audit Workflows
You can also use natural language to ask your AI assistant to audit its own recent actions and report its operational footprint.
Prompt: Review Recent AI Mutations
Inspect the status of all operations and Change Sets executed in our current session.
List which App Store Connect endpoints were called, whether any mutations failed,
and verify that no unapproved changes were dispatched.
Prompt: Investigate an Operation Failure
Check the recent operation logs for our app (ID: [your-app-id]).
Identify the exact error code and diagnostic message returned by App Store Connect
when the version localization update was attempted, and propose a corrective payload.
Prompt: Verify Change Set Execution Integrity
Retrieve the status and audit trail for Change Set [your-change-set-id].
Confirm that all staged operations completed with HTTP 200, verify the execution
duration, and summarize what changed on the App Store listing.
Troubleshooting Common Audit Issues
| Symptom | Root Cause | Resolution |
|---|---|---|
audit.jsonl not found at default path |
FlightDeck has not executed any operations yet, or custom HOME directory is set. | Trigger any read operation (e.g. apps_list). Verify echo $HOME matches your user directory. |
| Log entries truncated after 2,000 lines | Expected FIFO rotation policy of BoundedFileAuditLogger. |
If you require long-term retention, configure a log shipper (e.g. Vector or Fluent Bit) to tail the file into an enterprise SIEM. |
| Incomplete error details in log | Apple returned a non-JSON or gateway error (e.g. 502/504 Bad Gateway). | Check .errorDiagnostics.rawBody for plain text gateway responses or inspect network proxy settings. |
| Permission denied writing to log | Directory permissions modified or file owned by a different macOS user. | Run chmod 600 ~/Library/Application\ Support/asc_mcp/audit.jsonl and ensure the directory is owned by the logged-in user. |
Next Steps
- Review Human-in-the-Loop Governance with the FlightDeck Approval Center to see how staged operations are reviewed before logging.
- Explore Execution vs. Staging Rules to understand policy boundaries between read and write calls.
- Learn about the Zero-Relay Privacy Guarantee to verify that audit records and private keys never leave your local Mac.