**Date:** 2026-08-24

**Commit measured:** `a9a251e` on `openagents/main` (the forge), with the CLI at

`94e4cad8e7` on `OpenAgentsInc/openagents`

**Status:** audit and initial direction; nothing here is built yet

**Status:** audit and direction. The transcript routes and the event cursor are

built and shipped; the client that writes to them is not.

**Question:** `openagents coder` works with no account at all. We want the

opposite posture — sign in on open, work inside the account, and have the work

count. What already exists on the server to hang that on, what exists but is

declined: refuse to start, start in a named local mode, or start and nag. My

view is the second, and that the nag is the leaderboard being visible and empty.

## Persistence: what the store can actually hold

The coder keeps nothing. A session ends and its history goes with it, and the

audit that preceded this one proposed a local JSON Lines file keyed on a thread

id. That is the wrong shape now: `thread_events` already exists, and a local

file beside it is a second copy that can disagree with the first. The server's

copy should be the only copy.

Three routes now open it — `GET /api/v3/threads`,

`GET /api/v3/threads/{id}/events`, and `POST /api/v3/threads/{id}/events` — all

wrapping context functions that were already there. What remains is deciding

what a client writes into them, and that is a question about limits rather than

about taste.

### The two limits

**A payload is 2 to 16,384 bytes**, enforced by

`thread_events_payload_bound_check` on `octet_length(payload::text)`.

**A listing returns at most 50 events**, `@maximum_listed` in

`OpenAgents.Threads`.

Measured against four real coder sessions from the same afternoon:

| Session | Turns | Tool calls | Events at turn level | Events at tool level | Largest tool result |

| --- | --- | --- | --- | --- | --- |

| `16-58-34` | 13 | 42 | 13 | 55 | 6,511 B |

| `17-04-23` | 16 | 45 | 16 | 61 | 6,511 B |

| `17-08-32` | 4 | 5 | 4 | 9 | 8,418 B |

| `17-24-37` | 6 | 0 | 6 | 6 | 0 B |

The payload cap is not the binding constraint: the largest tool result observed

was 8.4 KB, and the transcript already bounds a result to 4,000 characters

before it reaches a model, so the same bound applied to an event keeps every one

of them comfortably inside 16 KB. A 30 KB shell output would not fit, which is

why the bound is applied rather than assumed.

**The listing cap was the binding constraint.** Turn-level persistence fits

inside fifty with room to spare; tool-level passes it on an ordinary working

session. So `list_events/2` now takes an `:after` cursor and the route publishes

each event's id, because a history that cannot be read back is not persistence.

That is the one server change this section required, and it is done.

### What to record

Recorded, in the order they happen:

- `turn.user` — what the reader asked.

- `tool.ran` — one event per call, carrying the tool, its arguments, and its

  bounded result. Call and result are one event rather than two: they are one

  fact, and splitting them doubles the count against the cap for nothing.

- `turn.assistant` — the answer, with the turn's token usage and call count.

Not recorded: text deltas, reasoning deltas, and the interface's own notices.

Deltas are how a reply arrives, not what it is, and a transcript that stores the

arrival cannot be read back as the thing. Reasoning is display-only for the same

reason it is not on the model transcript. Notices never reached a model.

That is roughly ATIF's step shape, which is not a coincidence: `/export` already

writes a session in exactly this granularity, and the two should not disagree

about what a session was.

### Resume

Follow Codex, which has the shape right and which this vocabulary already

follows:

- `openagents coder --resume` with no argument shows recent threads and lets one

  be picked, filtered to the current repository by default.

- `openagents coder --resume <uuid>` takes a thread id directly.

- `openagents coder --resume --last` continues the most recent without asking.

- `--all` drops the repository filter and shows which repository each thread

  belongs to.

`GET /api/v3/threads` is the picker's list and `GET /api/v3/threads/{id}/events`

is the transcript it replays. Neither needs anything new.

The one open question is what a resumed session sends to the model. The

transcript is evidence of what happened, not a chat history in a provider's

shape, so replaying it verbatim is not obviously right — and a long thread would

reintroduce exactly the context-size problem that bounding tool results just

solved. My instinct is that a resumed session replays the turns and the tool

results, not the deltas, and bounds them the same way a live session does.

## What I would do first

1. **Put thread spend on the leaderboard.** One arm on an existing union, with

   the double-count question answered against `DATA-002`. Nothing else on this

   list is honest until this is done.

2. **Write a coder session's outcome into experience memory, keyed by issue.**

2. **Write the coder's turns to `thread_events`, and resume from them.** The

   routes and the cursor exist; what remains is the client. This is also what

   makes a session worth signing in for, since the history stops being local and

   disposable.

3. **Write a coder session's outcome into experience memory, keyed by issue.**

   The ATIF export already holds it; the join is the work.

3. **Then** force the login, because by then it buys the board and the memory.

4. **Then** ask what a score should measure, with the data from 1 and 2 to

   answer it rather than guess.

4. **Then** force the login, because by then it buys the board, the history, and

   the memory.

5. **Then** ask what a score should measure, with the data to answer it rather

   than guess.

## What this document does not claim

   bin/openagents rpc 'OpenAgents.Forge.Sync.rebuild("{storage_key}")'

   ```

   The rebuild path takes no mirror input. `EXIT-003` turns red if one is

   added.

   `rebuild/1` discards the local bare-repository projection and

   re-materializes it from the WAL, from sequence zero, with no mirror input.

   That is the recovery a wrong or damaged projection needs, unlike

   `ensure_fresh/1` and `replay_missing/3`, which trust the projection's

   applied-sequence marker and only replay what it has not yet applied. It

   returns `:ok` on success and a typed error when the WAL cannot produce a

   servable projection. `EXIT-003` turns red if a mirror input is added.

## 4. Key rotation

    |> Repo.all()

  end

  @doc "The thread's transcript, oldest first, bounded."

  @doc """

  The thread's transcript, oldest first, bounded.

  `:after` continues from an event id already read. Without it a transcript

  longer than the cap could not be read back at all, and a session's history is

  exactly the thing that outgrows a cap: a working session records a turn and

  every tool it ran, which passes fifty inside an hour.

  """

  @spec list_events(Thread.t(), keyword()) :: [Event.t()]

  def list_events(%Thread{id: thread_id}, options \\ []) do

    limit = options |> Keyword.get(:limit, @maximum_listed) |> min(@maximum_listed) |> max(1)

      order_by: [asc: e.id],

      limit: ^limit

    )

    |> after_event(Keyword.get(options, :after))

    |> Repo.all()

  end

  defp after_event(query, nil), do: query

  defp after_event(query, after_id) when is_integer(after_id),

    do: from(e in query, where: e.id > ^after_id)

  defp after_event(query, after_id) when is_binary(after_id) do

    case Integer.parse(after_id) do

      {id, ""} -> after_event(query, id)

      _unparsed -> query

    end

  end

  defp after_event(query, _other), do: query

  @doc """

  Append one bounded event to a thread's transcript and advance its counter.

      _absent ->

        []

    end

    |> continue_from(params)

  end

  defp continue_from(options, params) do

    case Map.get(params, "after") do

      value when is_binary(value) -> Keyword.put(options, :after, value)

      _absent -> options

    end

  end

  defp event_parameters(params) do

  # the grant's is published: it is the one the request will actually use, and

  # printing the same name twice invites a reader to think they can differ.

  # The id is published because it is the cursor: a client continues from the

  # last one it read rather than counting.

  defp event_view(event) do

    %{

      "id" => event.id,

      "schema" => event.schema,

      "event_type" => event.event_type,

      "payload" => event.payload,

             )

  end

  test "rebuild re-materializes the projection from sequence zero and preserves the head", %{

  test "rebuild is the operator's from-sequence-zero recovery entry point", %{

    root: root

  } do

    {index, sha} = put_bundle_entry!(root, "rebuild-repo", "trunk")

    {index, _sha} = put_bundle_entry!(root, "rebuild-repo", "trunk")

    assert :ok = Sync.ensure_fresh("rebuild-repo", "trunk")

    # Append a second commit so the WAL holds more than the trivial first

    {:ok, generation, _} = WAL.read_index("rebuild-repo")

    {:ok, _} = WAL.cas_index("rebuild-repo", generation, WAL.append_entry(index, entry))

    assert :ok = Sync.ensure_fresh("rebuild-repo", "trunk")

    bare_path = Repos.bare_path("rebuild-repo")

    assert String.trim(git_bare!(bare_path, ["rev-parse", "trunk"])) == sha2

    # Rebuild is the operator recovery for a *wrong* projection: discard and

    # re-materialize from sequence zero. It must land on the same head.

    # Discard the local projection entirely. The operator recovery the

    # runbooks name is `OpenAgents.Forge.Sync.rebuild/1`: re-materialize the

    # repository from the WAL, from sequence zero, with no mirror input.

    File.rm_rf!(bare_path)

    assert :ok = Sync.rebuild("rebuild-repo", "trunk")

    assert String.trim(git_bare!(bare_path, ["rev-parse", "trunk"])) == sha2

    assert Repos.refs("rebuild-repo") == refs

    assert String.trim(git_bare!(bare_path, ["show", "trunk:README.md"])) == "durable import"

    assert String.trim(git_bare!(bare_path, ["show", "trunk:second.md"])) == "second commit"

    assert String.trim(git_bare!(bare_path, ["symbolic-ref", "HEAD"])) == "refs/heads/trunk"

    # The one-argument form the runbooks name resolves the default branch the

    # same way ensure_fresh/1 does, so `Sync.rebuild("{storage_key}")` runs.

    # The one-argument form the runbooks name uses the "main" default the same

    # way ensure_fresh/1 does, so `Sync.rebuild("{storage_key}")` runs.

    assert :ok = Sync.rebuild("rebuild-repo")

    assert String.trim(git_bare!(bare_path, ["rev-parse", "trunk"])) == sha2

    assert String.trim(git_bare!(bare_path, ["symbolic-ref", "HEAD"])) == "refs/heads/trunk"

  end

  defp git!(directory, args) do

    {output, 0} = System.cmd("git", args, cd: directory, stderr_to_stdout: true)

    output

  end

      assert Enum.all?(body["events"], &(&1["schema"] == "openagents.thread.event.v1"))

    end

    test "continues from an event already read", %{authenticated: conn, id: id} do

      for text <- ["one", "two", "three"] do

        conn

        |> post(~p"/api/v3/threads/#{id}/events", %{

          "event_type" => "turn.user",

          "payload" => %{"text" => text}

        })

        |> json_response(201)

      end

      first = conn |> get(~p"/api/v3/threads/#{id}/events?limit=2") |> json_response(200)

      cursor = List.last(first["events"])["id"]

      rest = conn |> get(~p"/api/v3/threads/#{id}/events?after=#{cursor}") |> json_response(200)

      # A working session records a turn and every tool it ran, which passes

      # the listing cap inside an hour. Without a cursor its history could not

      # be read back at all.

      assert length(first["events"]) == 2

      assert Enum.all?(rest["events"], &(&1["id"] > cursor))

      assert Enum.map(rest["events"], & &1["payload"]["text"]) |> List.last() == "three"

    end

    test "refuses an event with no type", %{authenticated: conn, id: id} do

      body =

        conn