> For the complete documentation index, see [llms.txt](https://docs.observal.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.observal.io/cli-reference/reconcile.md).

# observal reconcile

Backfill local session records missed by automatic hook or extension delivery.

Reconcile is a manual recovery command, not the normal collection path. The server cannot scan files on a developer machine. Automatic hooks and extensions wake the same durable delivery engine during normal harness activity; reconcile scans recent local sources on demand.

## When to use it

Run reconcile when:

* Telemetry instrumentation was installed after sessions already existed
* The machine or server was offline
* Delivery was interrupted
* Durable outbox records remain pending
* Recent local history needs to be verified or backfilled

Routine use is unnecessary when automatic delivery is healthy.

## Examples

Preview the default seven-day window without network or cursor changes:

```bash
observal reconcile --dry-run --output json
```

Backfill every installed harness:

```bash
observal reconcile --output json
```

Target one harness and a 24-hour discovery window:

```bash
observal reconcile --harness kiro --since 24 --output json
```

The discovery window accepts 1 through 8,760 hours.

## Delivery behavior

A non-dry run:

1. Validates configuration and the harness selection before any outbox side effect.
2. Retries the existing durable outbox.
3. Discovers recent session sources through installed harness adapters.
4. Skips locally finalized sources that have not grown.
5. Recovers the contiguous server checkpoint for unfinished sources.
6. Queues and sends only complete records after that checkpoint.
7. Sends final metadata when all records were uploaded but the session was not finalized.
8. Leaves transient failures queued for the next automatic wake-up or reconcile run.
9. Quarantines permanent server rejections and reports them explicitly.

Acknowledged checkpoints make repeated runs idempotent.

A dry run only reads local sources and cursor state. It does not drain the outbox, contact the ingest API, or update cursor state.

## JSON result

```json
{
  "dry_run": false,
  "since_hours": 168,
  "outbox_drained": true,
  "targets": [
    {
      "harness": "kiro",
      "discovered": 2,
      "pushed": 1,
      "finalized": 0,
      "queued": 1,
      "rejected": 0,
      "would_push": 0,
      "would_finalize": 0,
      "up_to_date": 0,
      "skipped": 0,
      "errors": 0,
      "sessions": [
        {"session_id": "session-1", "status": "pushed", "bytes_new": 512},
        {"session_id": "session-2", "status": "queued", "bytes_new": 128}
      ]
    }
  ],
  "summary": {
    "discovered": 2,
    "pushed": 1,
    "finalized": 0,
    "queued": 1,
    "rejected": 0,
    "would_push": 0,
    "would_finalize": 0,
    "up_to_date": 0,
    "skipped": 0,
    "errors": 0
  },
  "rejections": []
}
```

`outbox_drained: false` means durable records remain pending. A queued session is safely stored for retry and is not reported as delivered. Permanent ingestion failures include their HTTP status in `rejections`.

## Exit codes

| Code | Meaning                                            |
| ---- | -------------------------------------------------- |
| 3    | Session delivery identity is not configured        |
| 7    | Unknown harness or invalid discovery window        |
| 9    | Outbox storage or session discovery is unavailable |

Per-session source read failures and checkpoint mismatches are explicit result items so other sessions can still be recovered.

## Related

* [`observal doctor`](/cli-reference/doctor.md): configure and verify automatic telemetry instrumentation
* [`observal ops telemetry status`](/cli-reference/ops.md): inspect server and durable outbox health
* [Session tracking](/core-concepts/session-tracking.md): automatic and recovery delivery architecture


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.observal.io/cli-reference/reconcile.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.