> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getpioneer.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Patch history and file mutation

> How Pioneer applies authorized file changes, records exact history, and exposes filesystem coverage to clients.

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:

| Field | Meaning |
| - | - |
| `exactness` | Whether the returned diff is engine verified, provider reported, or incomplete. |
| `exact` | A compact boolean for clients that only need a yes or no. |
| `coverage` | Whether the result covers engine-verified steps, provider-reported steps, aggregate data, or an incomplete/untracked range. |
| `filesystem` | Whether filesystem observation is pending, complete, or incomplete, with reasons and sources. |
| `first_missing_ordinal` | The first commit ordinal that prevents the query from claiming complete coverage. |

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:

| Outcome | Client meaning |
| - | - |
| `applied` | The engine committed and recorded the change. |
| `partial` | Some stages or changes completed, and the record explains the failed stage. |
| `commit_state_uncertain` | The process lost authority after the commit boundary. Do not present the result as fully verified. |
| `gap` | The history range is missing or cannot be reconstructed. |

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](https://docs.getpioneer.dev/desktop/file-viewer.md) and [Artifacts architecture](https://docs.getpioneer.dev/architecture/artifacts.md) for the two client workflows.

## Code map

| Area | Code |
| - | - |
| Public DTOs and queries | `crates/protocol/src/patch_history.rs` |
| Native mutation engine | `crates/tools/src/apply_patch` |
| Native history store | `crates/tools/src/apply_patch/history` |
| Gateway observer and repair | `crates/gateway/src/patch_history_observer.rs`, `crates/gateway/src/bootstrap.rs` |
| JSON-RPC handlers | `crates/gateway/src/message/patch_history_handlers.rs` |
| HTTP file delivery | `crates/gateway/src/thread_file_delivery.rs`, `crates/gateway/src/transport/http` |
| Desktop file navigation | `crates/desktop/src/file_opener.rs`, timeline markdown rendering |
| Mobile and FFI file view | `pioneer-app/src/services/thread-files`, `crates/client-ffi/src/thread_files.rs` |

## Related pages

* [Patch history API](https://docs.getpioneer.dev/protocol/patch-history.md) lists pagination, record, diff, and view-grant methods.
* [Tools architecture](https://docs.getpioneer.dev/architecture/tools.md) explains permission admission and native tool routing.
* [Permission system](https://docs.getpioneer.dev/architecture/permissions.md) explains the turn security snapshot used before mutation.
* [Artifacts architecture](https://docs.getpioneer.dev/architecture/artifacts.md) explains durable file storage and artifact HTTP delivery.
* [File viewer](https://docs.getpioneer.dev/desktop/file-viewer.md) describes the end-user source-file workflow.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.