---
title: "Sessions for any agent"
description: "One record of every agent's work, kept by Fir, for any agent: an append-only log that compaction never shortens, open to every harness through one protocol, required for an agent's commits, resumable on any machine or harness, a successor that brings memory back after a restart, and every session shown under its plan, campaign and workspace."
url: https://frazer.ai/docs/sessions
index: https://frazer.ai/docs/sessions/llms.txt
tokens: 8790
---

> For agents: this page is indexed at https://frazer.ai/docs/sessions/llms.txt, and every page at https://frazer.ai/llms.txt. Copy commands from this file exactly.

# Sessions for any agent

A **session** is one unit of work by one agent or person, and Fir keeps its whole record: every message, tool call and result, edit, command, test run, decision, compaction, checkpoint and handoff, with who did each and what it cost. It does not matter which agent does the work. Frazer’s own agents write sessions, and so does any agent you run yourself, on your laptop or anywhere else, through one open protocol. An agent that writes code always works in a session, so every line can be traced to the turn that wrote it, and nothing is lost when a laptop closes or a context compacts.

> **The short version:** `fir session open` before you work, and Fir keeps everything. Compaction is a view: the full log stays, and every summary line points back to the events it covers. An agent’s commit without an open session is refused with the one call that fixes it. After a reboot, `fir session resume --mine --open` brings every open session back, on the same harness or another one. Sessions sit under their plan, program, campaign and workspace, and one count line says how many you have open.

## What a session holds

A session is a Fir record kept by the session service, not repository content: it has its own readers and retention and is never copied into a repository or a pull request. Its ID is short (`s-4d7a`) and resolves with your permissions anywhere.

| Part | What it holds |
| --- | --- |
| Identity | The ID, the kind (`agent`, `interactive`, `planning`, `review`, `ci`), the driver (an agent or a person) and its sponsor, the harness and its version, the models, and the machine for an agent that runs outside Frazer |
| Binding | What the work is for: a plan version and its items, a pull request, a workspace, a milestone and program, a campaign task, an issue, or a queue of decisions. It changes only by an explicit act, and every change is an event |
| Launch record | The exact configuration: the harness profile revision, tools and MCP servers, settings, permission mode, budget and the skill lock, so a resume is exact on any machine |
| Log | Typed events in order, hash-chained, each with its time, actor, payload, digest, trust and redactions; large payloads are stored once by content |
| Views | Compactions, summaries, the context at any turn, the resume brief and the handoff, each pointing back to the events it covers |
| Checkpoints | `c1`, `c2`, …: the Fir snapshot, the log position, the In force digest, the budget spent, the claims and a handoff |
| Lineage | The parent of a sub-agent’s session, forks, successors, continuations on another machine or harness, and handoffs; one root ID for the whole tree |
| Outputs | Commits, pull requests and versions, records written, decisions raised, person tasks and artifacts, linked both ways |
| Counters | Events, bytes, turns, tool calls, edits, commands, tests, tokens and cost, written with each append |

### States

| Axis | Values |
| --- | --- |
| Lifecycle | `open` or `closed`. Open sessions are what “how many sessions I have open” counts |
| Activity, while open | `working`; `waiting for you` (a question, an approval or a person task for the viewer); `parked` (waiting on CI, the merge queue, a review, a schedule or another person, with its leases kept); `idle` (no event for 30 minutes); `interrupted` (no heartbeat for 10 minutes and no close: a reboot, a closed laptop, a lost cell) |
| Outcome, when closed | `done`, `handed off`, `abandoned`, `failed`, `canceled` |

An interrupted session keeps its leases for up to 24 hours, so an overnight shutdown keeps its plan items. It becomes abandoned after 7 days interrupted and stays resumable while it is retained.

An author’s session stays open while its pull request is written or fixed, then parks while the pull request is in review, in CI, in the merge queue or with a person, so it can answer a finding or a failed test batch with its own context. It closes as `done` when the pull request merges or closes. A campaign shard’s session closes when its pull request opens, and a later finding starts a new session from the shard’s checkpoint. A codemod’s change has no session: it is a recorded program run, with its version on the pull request.

### Events

| Kind | What it records |
| --- | --- |
| `message` | A user, assistant or system message, with its model |
| `tool_call`, `tool_result` | The tool, its arguments (redacted), the result, the duration and the permission decision; the host’s receipt sits beside it |
| `edit` | Paths, hunks and the workspace snapshot the edit made |
| `command`, `test_run` | A command with its exit code and output; a test run with passed, failed and flaky tests, and the CI run when it ran there |
| `decision`, `notice`, `approval` | A decision raised or answered; a changed record acknowledged; an approval asked or given |
| `compaction` | The range it covers and its summary as a view; a provider’s sealed block as an attachment |
| `checkpoint`, `handoff` | The parts listed above |
| `route_decision`, `model_switch` | The model and effort chosen for a turn and why; a switch of model with its reason and the cache cost of the switch |
| `budget_check` | The reservation before a run or a turn and its result, including “Not run: no funds” and “Paused: no funds” |
| `subagent`, `usage`, `receipt` | A sub-agent’s task and result; tokens and cost; the host’s signed record of a model or tool call, never written by the harness |
| `skill_listed`, `skill_loaded`, `skill_file_read`, `skill_script_run`, `skill_requested_missing` | Which [skills](https://frazer.ai/docs/agents/skills) the session was offered and used |
| `utterance`, `reading`, `confirm` | In a conversation: a person’s words verbatim, the agent’s reading of them, and the person’s confirmation |
| `note`, `assertion`, `artifact`, `lifecycle`, `error` | Notes and claims with evidence; files and preview URLs; opened, interrupted, resumed, closed; failures with their class |

### Fidelity and trust

Not every harness can report everything, so each session says how complete its log is, and each event says who vouches for it.

| Fidelity | What the log has |
| --- | --- |
| `complete` | Every event as it happens: the Frazer harness, any agent behind `fir acp`, and harnesses whose Fir plugin hooks every row |
| `turns` | Every turn’s events from the harness’s hooks, with its own transcript read at each checkpoint and at close |
| `declared` | What the agent reports through MCP tools: opening, notes, checkpoints and handoffs |
| `imported` | Read after the fact from a harness’s own files or an export |

An event is `attested` when Fir or the LLM gateway wrote it (edits, snapshots, receipts, CI results, usage through the gateway), `declared` when an adapter or the agent reported it, and `imported` when it was parsed from a file Fir did not watch being written. Only attested facts count as evidence anywhere in Fir.

## Nothing is lost: the log is canonical

1.  **Every event is kept.** Compaction never deletes events. It records the range it covers and its summary as a view of that range.
2.  **Every summary line carries handles.** A line reads “tried three CSV writers, kept the streaming one \[s-4d7a#e340-e391\]”. Any agent that may read the session calls `read_session` or `fir session read` with the handle and gets the original events, sized to its budget, never the whole log.
3.  **Views are versioned and cited.** A view stores the rule and model that made it and the digests of the events it covers. It is never the source of a state or a number.
4.  **What binds is outside every view.** In force, the task and the item’s agreement on done are sent again from Fir after every compaction; a summary never carries them.
5.  **Sealed provider state is kept, never alone.** A provider’s encrypted reasoning or opaque compaction block is stored as a sealed attachment and used only to continue with the same provider and model line. Every sealed item has a readable twin: the reasoning summary when the provider returns one, and the task a sub-agent was given.
6.  **Nothing old enters a context by default.** A stored session reaches a model only as a resume brief or one handle at a time.

## Any agent, one protocol

The session protocol is a published, versioned specification. Its adapters, importers and conformance suite are open source under Apache-2.0 and install without a Frazer plan; the storage behind them is Fir’s.

| Verb | What it does |
| --- | --- |
| `open` | Creates the session with its binding and launch record and returns the session ID, a session token and the session context. Keyed by the harness’s own session ID, so a hook that fires twice opens one session |
| `append` | Adds a batch of events. Each event has an ID, duplicates are ignored, and a gap in the sequence is refused with the expected position |
| `heartbeat` | Says the driver is alive, every 60 seconds; leases renew with it |
| `checkpoint`, `close` | Writes a checkpoint with a handoff; ends the session with an outcome and releases its leases |
| `resume`, `fork` | Continues the work (below); starts a new session from any event, and with `--at` also restores the workspace to that event’s snapshot, so a rewind loses nothing |
| `attach` | Links an outside or late session to a commit, a pull request or a plan item; only the session’s driver or sponsor may |
| `import`, `export` | Reads a harness’s own transcripts into sessions; writes a self-contained bundle, or the same session as OpenTelemetry spans or an ACP replay |
| `read`, `search`, `list` | Events by range, kind or handle; sessions by text, path, command, error, tool, plan, commit, harness, model or cost; sessions by binding, state, harness or machine, with a count line |

The same verbs are `fir session …` commands, MCP tools (`open_session`, `append_session_events`, `checkpoint_session`, `close_session`, `read_session`, `search_sessions`, `list_sessions`, `get_session`), the `frazer.sessions.v1` API, harness hooks, an ACP proxy (`fir acp -- <agent command>`) and OpenTelemetry ingest, where spans with a conversation ID become a session.

### Connect your agent

`fir agent setup <harness>` connects an agent to Fir in one step: the harness’s MCP entry for `fir mcp`, its hooks (open a session at start, append after tool calls, checkpoint before compaction), a short skill, and two lines for the repository’s instruction file. `--dry-run` shows every file it would touch, `--scope user` or `--scope repo` chooses where, and it never installs a background service.

| Harness | How it writes its session | Fidelity |
| --- | --- | --- |
| The Frazer harness | Natively: its step journal is a writer of the session | `complete` |
| Claude Code | The Fir plugin’s session-start hook opens the session with the harness’s own session ID; hooks append every turn, and the Fir mod appends every row before it is stored | `complete` with the mod, `turns` with hooks |
| Codex | The Fir plugin’s hooks; hosted sessions through its app server’s notifications | `turns`, `complete` through the app server |
| Gemini CLI | The Fir extension’s hooks, or `fir acp` for a complete log | `turns`, `complete` over ACP |
| Copilot CLI and its cloud agent | Fir hooks; a cloud agent’s session logs imported | `turns` or `imported` |
| OpenCode | Its server API, watched by the adapter | `turns` |
| Hermes Agent | A plugin, or ACP | `turns`, `complete` over ACP |
| Any ACP agent | `fir acp` records every session update | `complete` |
| Frameworks with OpenTelemetry | The first span with a conversation ID opens the session | `turns` |
| Any MCP client | `open_session` first (the server’s instructions say so), then notes, checkpoints and handoffs | `declared` |

Every adapter writes to a local append-only spool first and sends from there, so a crash, a reboot or a lost network replays every batch until Fir acknowledges it; nothing is dropped. Appends never block the agent: only the first `open` and the commit path wait for Fir. Adapters are versioned and tested against each harness release before Frazer lists that release again.

`fir session import <harness>` reads past sessions from a harness’s own store, with a dry run that shows the counts first; imported sessions are labeled `imported`, never `attested`, and can be attached to a commit afterwards with `fir session attach`.

## Required to commit

In Fir every workspace snapshot is a commit, a pull request version is published from one, and a push publishes a version. **Fir refuses a snapshot, a pull request version or a push by an agent unless it carries an open session bound to that agent and that workspace.** The refusal is a typed error with the call that fixes it:

```text
$ fir commit -m "Map settlement columns to the export schema"
error: SESSION_REQUIRED (exit 5): an agent's commit needs an open Fir session
  detected: an outside agent (AI_AGENT) · no Fir session for this agent · workspace ws/amara-csv
  plan: acme/plans#527 item 1.4 (the workspace's active plan)
  next: fir session open --plan acme/plans#527 --item 1.4
```

On Oct 18 at 10:12, amara’s agent, started before the Fir plugin was installed, gets this error, runs the `next` call, which opens `s-4f05` bound to item 1.4, and the commit goes through four seconds later with the session attested in its creation record (product UI, demo data). For an MCP caller, `next` is the tool call `open_session` with the same plan and item. A snapshot an agent makes through the local mount without a session is kept in the workspace’s private area and never published, so no work is lost.

**How Fir tells an agent from a person.** The token is the boundary: an agent’s token names the agent as the actor, and `fir session open` exchanges the caller’s token for a **session token** that names the person, the agent and the session, scoped to the binding, valid for at most an hour and bound to the adapter’s key. Commits made with it carry the session as an attested field. The `fir` CLI also reads the harness’s own environment (such as `CLAUDE_CODE_SESSION_ID`, `CODEX_THREAD_ID`, `GEMINI_CLI` and the shared `AI_AGENT`): inside an agent it maps the harness’s session to the Fir session the plugin opened, opens one when the plugin is installed, and otherwise returns `SESSION_REQUIRED`. So a person’s credentials used by a local agent still produce a session.

-   **An agent and a person in one workspace.** The adapter reports which hunks the agent’s tool calls wrote; Fir attributes those hunks to the session and the rest to the person, per hunk. A version with agent hunks needs the session open; a version with only the person’s does not.
-   **A person’s own commits** need no session by default. When one is open in the workspace, the commit links to it; otherwise the creation record says “no session”, which means “no agent evidence”, never “written by hand”. An organization sets one setting, `sessions.for_people`, and may narrow it per project (`frazer orgs settings set sessions.for_people suggest --dry-run`):

| Value | A person’s own snapshot, version or push | What the person sees |
| --- | --- | --- |
| `off` | Never asked; linked to a session only when one is open in the workspace | Nothing |
| `suggest` (the default) | Accepted. The CLI and the app offer an `interactive` session at most once a day per workspace, and only when the work looks long (by default, more than 200 changed lines or more than 30 minutes since the first unpublished change) | One line with `fir session open --interactive`, and “never ask again for this workspace” |
| `require` | Refused without an open session, like an agent’s write: `SESSION_REQUIRED`, exit `5`, with `fir session open --interactive` as `next` | The refusal; the session it opens is the person’s own, readable only by them |

Three rules hold under every value. A hand edit inside an agent’s session belongs to that session (the per-hunk attribution above says which hunks the person typed), so `require` never asks for a second session while an agent’s is open in the workspace. A person’s session is never read by the work’s readers unless the person shares it. Reverts, repairs and server restacks are never refused.

-   **The escape hatch.** A `session.bypass` grant lets one named agent write without a session for a stated reason, such as an outage of the session service or a migration script. Only organization admins grant it, for at most 24 hours by default. Every write under it is labeled `session: bypassed`, raises a finding in Security Center and opens a backfill task (`fir session attach` within 72 hours). A session token can never grant it, approve, answer a decision, set an item’s state or lift a kill switch.
-   **Outside Fir.** Repositories still on GitHub, and Fir’s git exports, carry the session as trailers (`Fir-Session: s-4d7a` and a link that opens only for allowed readers). A required check, `frazer/session`, fails an agent’s commit whose trailer is missing or names a session Fir does not know.
-   **What it cannot prove.** An agent that runs outside every harness Fir knows, with a person’s own token, and never identifies itself looks like the person. Provenance then says “no agent evidence”, and link coverage shows the share of merged lines with attested sessions per repository.

## Why, down to the turn

Every snapshot keeps the session event that produced it, so `why` on a line reaches the turn, the message or plan item it answered, and what was tried before:

```text
$ fir why services/checkout-api/settlement/csv.go:57 --session
services/checkout-api/settlement/csv.go:57 at main@51106
Origin   #4672 "Stream the settlement CSV" · merged as main@51102 · lena's agent
Plan     acme/plans#527 v2 · item 1.2 "Stream rows, never buffer the report"
Session  s-4d7a · event e388 (edit, turn 14)
         turn 14 answered lena's message e381: "keep memory flat for 2M rows" [s-4d7a#e381]
         tried: buffered writer (e341), rejected at e352 (heap 1.9 GB on the 2M-row fixture)
Receipt  cr-4d91 · In force 6 rows
```

The excerpt is a handle, read only by people and agents allowed to read the session (product UI, demo data).

## Resume anywhere

-   **The same harness on the same machine.** `fir session resume s-4d7a` checks the harness’s local transcript against the log. If it matches, the harness resumes natively; if it is missing or differs, the adapter writes it back from the log first.
-   **Another machine.** The same command rebuilds the session there: the harness’s transcript from the log, the workspace from Fir at its snapshot (Fir’s workspaces are on the server, so there is nothing to clone or stash), and the launch record. Two drivers never write one session at once: a second resume of a running session takes it over at a new lease epoch, or forks it.
-   **Another harness.** `fir session resume s-4e19 --harness frazer --on frazer` continues a session in the Frazer harness on Frazer’s cells. The new harness gets a **resume brief**: the binding and In force, the task and its agreement on done, the last 30 events verbatim, one line per earlier turn with its handle, the files changed and the workspace snapshot, open tool state, and the latest handoff and checkpoint. The new session is linked as a continuation and the old one closes as handed off. Sealed provider state never crosses to another provider.
-   **Either way between surfaces.** A session moves from a laptop to Frazer’s cells, a desktop or the Frazer app and back (`--on frazer`, `--on here` or `--on <machine>`), as its whole log and workspace snapshot, so nothing is summarized away in the move.
-   **The cost first.** Resuming an idle session re-reads its context once the model provider’s cache has expired. `fir session resume s-4e19 --dry-run` prints the tokens and the estimated cost of the re-read and of the brief before anything runs, as JSON with `--json`.

### Rewind, with nothing deleted

An agent that took a wrong turn goes back to an earlier event: `fir session rewind s-4d7a --to e340` (MCP `rewind_session`). Fir writes one event, rewound, whose parent is `e340`; the next events hang from it, the abandoned branch stays readable (`fir session view s-4d7a --branch all`), and the workspace returns to `e340`’s snapshot, whichever tool changed a file, the shell included. A rewind keeps one session on one line of work; a fork starts another session beside it.

### After a reboot: resume all

On Oct 17 at 18:40, lena shuts a laptop with three agents working on `acme/plans#527` and one issue. Their heartbeats stop; at 18:50 Fir marks the three `interrupted` and keeps their leases, and lena’s phone shows “3 interrupted on lena-mbp-acme”. On Oct 18 at 08:55:

```text
$ fir session resume --mine --open
3 interrupted on lena-mbp-acme · 7 running on Frazer
  s-4d7a  claude-code  #527 1.2  local transcript ok (412 events)      → new window
  s-4e19  codex        #527 1.3  moved: --on frazer (lena's choice)     → s-4e38 in the Frazer harness
  s-4e2c  gemini-cli   #4668     left for lena-desk-acme              → resume it there
3 resumed · leases renewed at epoch 2 · nothing lost (812 of 812 events acknowledged from the spool)
```

At 09:20 lena resumes `s-4e2c` on an office desktop where that harness has never run: the adapter writes its transcript from the log and the workspace opens at its snapshot. The Frazer app offers the same as one button, **Resume 3**. Sessions on Frazer’s cells never stopped, and a laptop session can continue there with `--on frazer` while the laptop stays closed (product UI, demo data).

### Restart with memory: successors

A crashed, stalled or context-exhausted agent gets a **successor**: a new session that starts from the last checkpoint and is linked to the old one. Its card shows the chain, the reason and what it **brought back**, each with its size and age: the checkpoint, the handoff, In force at the plan’s current version, the agent’s memory items for the task with their provenance, its claims renewed at a new epoch, and the campaign’s standing answers; then its first actions. Memory comes back as data with provenance, never as instructions.

On Tue Nov 17 at 14:07, `s-6a02` in lena’s campaign `cm-7g72` “Storefront program” exhausts its context. `s-6a03` starts from checkpoint `c4` (14 minutes old), brings back the handoff (110 tokens), In force (9 rows), 3 memory items and the lease at epoch 2, and first re-runs the failing test it named in its handoff (product UI, demo data). At most three restarts in an hour; then the session is quarantined and its squad re-plans. [Squads and campaigns](https://frazer.ai/docs/squads/campaigns) shows successors on the campaign board.

## Sessions under plans, programs and campaigns

A session appears under its plan item and plan, its program and milestone, its campaign task, its workspace and pull request (the Provenance tab), its issue, your **My sessions**, the machine it runs on, and search. A workspace is one view of a session, not its home: an agent can work on a plan across several workspaces.

### How many sessions I have open

One count line first, then groups, then rows (product UI, demo data):

| Who and when | Count line |
| --- | --- |
| lena, Oct 18, 08:55, after the reboot | **10 open**: working 7 · interrupted 3 · waiting for you 0; on lena-mbp-acme 3 · on Frazer 7 |
| lena, Tue Nov 17, 15:00, with 50,000 pull requests opened in 24 hours | **1,690 open**: working 985 · parked 655 · idle 27 · interrupted 19 · waiting for you 4. By campaign: cm-7g72 1,005 · cm-7e54 360 · cm-7c32 148 · cm-7b21 121 · cm-7d43 6 · no campaign 50. Exceptions by cause: 19 interrupted (a cell drained for maintenance, resuming on their own) · 7 stalled (5 already replaced by successors) · 3 refused commits from an outside agent without the plugin |

Most of the sessions behind 50,000 pull requests a day are campaign shards that close when their pull requests open, and codemod shards have no session at all, so the open count stays near what the work in flight needs. The view groups by campaign, program and plan by default, and by harness, machine or state on a key; Compact rows are 28 px; and nothing in it asks for you except **waiting for you**. The count line is designed to return in 5 ms at the 99th percentile, even for a person with 100,000 sessions.

### One session’s page

| Region | Shows |
| --- | --- |
| Header | Title, driver and sponsor, harness and models, machine or cell, state and activity, binding, cost so far, fidelity |
| Timeline | Turns with folded tool calls; edits with their hunks; commands with exit codes; tests; decisions; compactions as markers with what they cover; checkpoints |
| What it changed | Commits, pull requests and versions, lines by file, records written |
| Context | The session context it received (receipts), In force, notices acknowledged |
| Lineage | Parent, forks, the successor chain, continuations |
| Resume | Where it can resume (this machine, another, Frazer, which harnesses), with the command |
| For agents | The same as JSON: `fir session view s-4d7a --json` |

A plan’s Sessions tab lists every session that worked on it: on Oct 18 at 10:30, `acme/plans#527` had 10 sessions (9 open), 3 of them outside agents and 7 on the Frazer harness, and 14 commits, every one with an attested session.

## Search

`fir session search "timeout on large shops" --plan acme/plans#527` and the console’s search reach every session you may read: messages, commands, errors, file paths and symbols touched, tools, skills, plan and item, commit and pull request, harness, model, cost and time. Results are events with their handles, not whole transcripts. Search is designed to answer within 200 ms at the 95th percentile over an organization’s 100 million sessions with a plan or time filter.

## Privacy, secrets and retention

-   **Secrets are redacted before storage**: in the adapter where the harness allows it, so the local transcript is clean too, and always at ingest (provider key prefixes, private keys, credentials in URLs and connection strings, and long high-entropy tokens). A redacted value becomes `[REDACTED:<rule>]` with a keyed hash, so security staff can correlate two events without seeing the secret. A verified Frazer token is revoked at once and Security Center is told; another provider’s verified key opens a [person task](https://frazer.ai/docs/source/person-tasks) to rotate it. Events that touch sealed paths carry the path’s label and are withheld from readers without the sealed scope.
-   **Who can read.** An agent’s session (`agent`, `review`, `ci`) is readable by everyone who can read its plan and its repository, its sponsor and organization admins. An organization may set `person_messages: owner_only` to keep a person’s own messages inside an agent’s session to that person. A person’s own session (`interactive`, `planning`) is readable by its owner and the people it is shared with; organization admins see the index. Nothing is public unless the owner publishes one session by link.
-   **Retention**, as defaults an organization changes: open sessions are kept; a closed session’s whole log is kept for 2 years, searchable for the first 90 days and readable by range afterwards; a session that a merged commit’s provenance cites is kept as long as that provenance. Legal hold stops every sweep.
-   **Deletion.** Each session is encrypted with its own key; deleting a session destroys the key, so every copy (segments, backups, the search index, exports Fir made) becomes unreadable, while its digests and its existence stay for provenance.
-   **Erasure reaches every derived copy.** Deleting a session, or erasing a person’s data from one (`fir session redact s-4d7a --person <p> --reason <r>`), also removes it from everything computed from it: views and resume briefs, search postings, memory items learned from it, skill-gap clusters and the improvement step’s cached probes. Each erasure returns a signed **receipt** that lists every copy it reached, by kind and count, and names what it could not reach (an export someone downloaded).

## What Frazer learns from sessions

Within your organization: friction and failures feed the [improvement step](https://frazer.ai/docs/for-agents/what-agents-get) of the agents that ran them; escaped defects traced to the event that wrote the line feed [Frazer Reviewer](https://frazer.ai/docs/reviewer/lanes); skill use feeds [Skills](https://frazer.ai/docs/agents/skills); recorded sessions become replayable tasks in the harness [Lab](https://frazer.ai/docs/agents/harnesses); stalls against a plan item become proposed plan checks.

**Frazer’s own products learn from your sessions only on your organization’s opt-in.** The setting, `sessions.improvement`, is off for every organization and every personal plan. Only an organization admin turns it on (Settings › Sessions, or `frazer orgs settings set sessions.improvement on --dry-run`, then without `--dry-run`), and the change records who made it, when, the terms version and the scope.

| Question | Rule |
| --- | --- |
| What it covers | Only the products named in `sessions.improvement.products` (the Frazer harness’s policies and evals, Frazer Rerank, Frazer Reviewer’s back-tests, or fewer), only the session kinds chosen (`agent`, `review` and `ci` by default), only the projects chosen |
| What never leaves your organization | Secrets (redacted before storage), events on sealed paths, a person’s messages under `person_messages: owner_only`, sessions under legal hold, and anything of another organization |
| How it is used | Derived records first (task descriptions, outcomes, friction patterns, tool sequences, failures and their fixes); raw events only inside Frazer’s evaluation cells, every read logged; no person at Frazer reads them unless your organization allows it |
| Turning it off | New use stops at once. Raw copies are designed to be deleted within 30 days, and models and policies trained with them are retrained without them at their next scheduled retrain, within 90 days, with a receipt |
| What you see | A usage page: which product used which sessions, when and for what |

## Prices

The records, the protocol, search, resume, fork, import and export cost nothing, for any agent. Logs, blobs and checkpoints are billed as Frazer Storage at $0.012 per GiB-month after compression, and the first 100 GiB-month each month is free for every organization. Views a model writes, such as summaries and resume briefs, bill their tokens at their routes. When funds run out, no session is deleted and every session stays readable.

## Commands and tools

```sh
fir session open --plan acme/plans#527 --item 1.2
fir session checkpoint --handoff -
fir session close --outcome done
fir session resume --mine --open
fir session rewind s-4d7a --to e340 --dry-run
fir session list --mine --open --by campaign --count
fir session view s-4d7a --events e340..e391 --json
fir session read s-4d7a#e340-e391
fir why services/checkout-api/settlement/csv.go:57 --session
```

| Command | What it does |
| --- | --- |
| `fir session open` | Open a session for this agent: `--plan` and `--item`, `--workspace`, `--task`, `--issue` or `--queue`; `--harness` and `--native-id` link the harness’s own session; `--interactive` opens a person’s own |
| `fir session append` | Append a harness’s events from a file or stdin; idempotent by event ID (for adapters) |
| `fir session heartbeat`, `checkpoint`, `close` | Keep it alive; write a checkpoint with `--handoff -`; close with `--outcome done`, `handed_off` or `abandoned` |
| `fir session resume` | Resume one session, `--harness` and `--on here`, `--on frazer` or `--on <machine>`; `--dry-run` prints the re-read’s tokens and cost first; `--mine --open` resumes every open one after a restart |
| `fir session rewind` | Go back to an event (`--to e340`): one event, the old branch kept, the workspace restored; `--dry-run` first |
| `fir session fork`, `attach` | Fork at an event (`--at`); attach a session to a commit, a pull request or an item |
| `fir session import`, `export`, `verify` | Import a harness’s past sessions (`--dry-run` first); export a bundle (`--format bundle`, `jsonl`, `otel`, `acp` or `patch`); verify a bundle’s chain, digests and signatures offline |
| `fir session redact` | Erase a person’s data from a session and every copy made from it (`--person`, `--reason`); prints the receipt |
| `fir session list`, `view`, `search`, `read` | Sessions with a count line (`--by state`, `plan`, `campaign`, `harness` or `machine`, `--successors`); one session; events by text; the events a handle points to |
| `fir session doctor` | Why a write was refused, and what the adapter sees |
| `fir agent setup` | Connect an agent of any vendor to Fir |
| `fir acp` | Run an ACP agent behind Fir’s proxy, recording every update |
| `frazer orgs settings get`, `set` | The organization’s session settings: `sessions.for_people` (`off`, `suggest` or `require`, `--project` to narrow it) and `sessions.improvement` (`off` or `on`, with `.products` and `.kinds`); `--dry-run` first |

Events for webhooks: `sessions.session.opened`, `.interrupted`, `.resumed`, `.closed`, `.forked`, `.successor_started`, `.commit_refused`, `.bypass_used`, `.exported`, `.deleted`.

> **For agents:** Open a session before you change anything (`fir session open`, or `open_session` over MCP), and keep it current: your harness’s Fir plugin does this for you. If a commit returns `SESSION_REQUIRED`, run its `next` call. Read a summary’s handles with `read_session` when the task depends on the full text, checkpoint before a long wait, and close with an outcome. You never use a bypass grant you were not given.

## Related

-   [Agents and plans](https://frazer.ai/docs/for-agents/plans): the session context, In force, claims, notes and handoffs
-   [The CLI for agents](https://frazer.ai/docs/for-agents/cli): the error envelope, exit codes and `fir agent setup`
-   [Harnesses](https://frazer.ai/docs/agents/harnesses): every harness writes the same session
-   [Squads and campaigns](https://frazer.ai/docs/squads/campaigns): sessions on the campaign board, successors at scale
-   [Fir CLI](https://frazer.ai/docs/source/reference/cli): every `fir` command

## Pages in Fir

- [Overview](https://frazer.ai/docs/source.md)
- [Plan repositories](https://frazer.ai/docs/source/plans.md)
- [Record types](https://frazer.ai/docs/source/record-types.md)
- [Programs](https://frazer.ai/docs/source/programs.md)
- [Person tasks](https://frazer.ai/docs/source/person-tasks.md)
- [Decisions](https://frazer.ai/docs/source/decisions.md)
- [Decide by conversation](https://frazer.ai/docs/source/decisions/conversation.md)
- [The planning flow](https://frazer.ai/docs/source/planning-flow.md)
- [Loops and learned checks](https://frazer.ai/docs/source/planning-flow/loops.md)
- [Stacks and conflicts](https://frazer.ai/docs/source/stacks.md)
- [Auto-merge and the merge queue](https://frazer.ai/docs/source/merge-queue.md)
- [Sessions](https://frazer.ai/docs/sessions.md) (this page)
- [Issues](https://frazer.ai/docs/source/issues.md)