Skip to main content
Pioneer has one native filesystem mutation path: apply_patch. Providers may describe a file change in their own event format, but the gateway routes supported mutations through the native engine or records a provider aggregate with an explicit authority and exactness label. Patch history exists to answer a practical question after a turn: what changed, which execution made the change, and how certain is the recorded diff? The answer is stored as durable records rather than reconstructed from a live process or a provider’s last message.

​
Mutation pipeline

The native path processes a patch in bounded stages:
  1. normalize the request and enforce input limits;
  2. parse patch syntax and validate version guards;
  3. resolve every target against the workspace and allowed roots;
  4. authorize the operation with the turn permission and file policy;
  5. prepare an exact virtual workspace plan;
  6. acquire target locks and compare file versions;
  7. stage file content and directory side effects;
  8. commit the planned changes atomically where the platform allows;
  9. persist snapshots and a patch history record;
  10. publish the applied step and update projections.
The engine rejects paths outside allowed roots, stale files, ambiguous context, unsupported file types, unsafe moves, oversized requests, and writes that exceed the turn or workspace budget. Missing destination directories can be created only when the admitted write grant allows that operation. The engine is also the observation boundary. A provider event that says a file changed is not silently treated as an exact native record. The record retains its authority and provenance so clients can distinguish an exact engine commit from a provider aggregate or a recovery observation.

​
Durable record

Each PatchHistoryRecord contains:
  • schema version, record id, thread, turn, invocation, and environment ids;
  • commit ordinal and commit timestamp;
  • authority such as native_patch_engine, codex_aggregate_event, managed_claude_patch_engine, or unsupported;
  • provenance such as native_engine, managed_claude, recovery, provider_aggregate, or unknown;
  • record exactness: exact, partial, or uncertain;
  • outcome: applied, partial, commit_state_uncertain, or gap;
  • one or more changes and their before/after snapshots;
  • directory side effects and metadata warnings.
Snapshots are content addressed. They retain a content hash, byte length, text encoding, line-ending metadata, and final-newline information. A change can be an add, replace, update, delete, or move. For a move, the record can contain both source and destination locations and an overwritten destination snapshot. The record keeps paths in several forms because each serves a different consumer. The relative path is the stable user-facing value. The workspace root and absolute path are resolved server-side for an authorized client or diagnostic surface. A client should not manufacture an absolute path by joining a local desktop path to a remote gateway path.

​
Coverage and exactness

The query response reports more than a list of files. It includes: This distinction matters during recovery. A provider may have emitted a final aggregate diff while the gateway was restarting. The UI can show the change, but it should not label it as exact until native history has verified it.

​
Views and queries

The same records are projected at several scopes:
  • timeline view shows applied steps in a thread or turn;
  • turn aggregate view combines the records for one turn;
  • record diff view returns one selected record or a bounded unified patch;
  • file history view follows one path across the execution scope visible from a thread.
The gateway caps page size and response bytes. Thread file history can include the execution threads that belong to the visible task scope, but it still checks the caller’s thread authorization and path roots. Cursors include source thread and commit time so pagination remains stable when several child threads contribute records.

​
Recovery and uncertain outcomes

File mutation crosses a process and filesystem boundary, so a crash can happen after the file changed but before the history row or notification was written. Startup repair and the patch observer reconcile projections. They do not invent an exact record when the commit state cannot be proven. Possible outcomes are: The same approach is used for Codex and managed Claude adapters. Their provider-native events are retained as provider aggregates when the native engine cannot provide exact steps. Recovery events can later improve coverage without changing the meaning of the original observation.

​
File viewer boundary

The source-file workflow uses patch and thread context as a navigation surface. A markdown link can identify a workspace file and an optional line or column. Mobile and FFI clients ask the gateway for a short-lived thread/file/view_grant/create grant, then fetch an authenticated HTTP representation. The gateway resolves the path against the authorized thread and serves a bounded text file. Desktop handles local file targets with its configured OS opener and does not send an arbitrary local desktop path to a remote gateway. This is separate from artifact delivery. Artifacts are durable uploaded or generated blobs. Thread file viewing reads a gateway workspace file under the current thread’s authorization. See File viewer and Artifacts architecture for the two client workflows.

​
Code map