synchronize(repo, fn -> do_replay_missing(repo, index, default_branch) end)

  end

  @doc """

  Discard the local bare-repository projection and re-materialize it from the

  WAL, from sequence zero.

  Use this when the projection is *wrong* rather than merely behind, where

  `ensure_fresh/1` and `replay_missing/3` would trust its existing state. It

  builds the whole repository in a sibling directory, proves every ref tip

  resolves, and only then swaps it in place, so readers never see a partial

  projection. Returns `:ok` on success and a typed error when the WAL cannot

  produce a servable projection. Takes no mirror input; `EXIT-003` holds the

  authority boundary.

  """

  def rebuild(repo, default_branch \\ "main") do

    synchronize(repo, fn ->

      case WAL.read_index(repo) do

        {:error, :not_found} -> :ok

        {:ok, _generation, index} -> rebuild_at_sibling!(repo, index, default_branch)

        {:error, reason} -> raise_sync(repo, :read_wal, reason)

      end

    end)

  end

  # Reentrant: `:global` locks are not reference counted, so a nested

  # `:global.trans` on the same id releases the lock when the inner call

  # exits (for example `ensure_fresh/2` inside a locked write). The process

    # malformed request and not a forbidden one: the same call succeeds once

    # the caller revokes one, so it is the rate-limit status and its own code.

    "thread_quota_reached" => {429, "This account holds the maximum number of open threads"},

    "thread_terminal" => {422, "This thread is terminal and its transcript is closed"},

    # Spending the account's inference credit is not a rate limit: no amount of

    # waiting or revoking makes the same call succeed, so it is the payment

    # status and its own code.

      "get /api/v3/chat/events" => {:required_bearer, :chat, :legacy},

      "post /api/v3/chat/turns" => {:required_bearer, :chat, :legacy},

      "post /api/v3/threads" => {:required_bearer, :thread, :envelope},

      "get /api/v3/threads" => {:required_bearer, :thread, :envelope},

      "get /api/v3/threads/:thread_id" => {:required_bearer, :thread, :envelope},

      "delete /api/v3/threads/:thread_id" => {:required_bearer, :thread, :envelope},

      "get /api/v3/threads/:thread_id/events" => {:required_bearer, :thread, :envelope},

      "post /api/v3/threads/:thread_id/events" => {:required_bearer, :thread, :envelope},

      "get /api/v3/capacity" => {:required_bearer, :capacity, :legacy},

      "post /api/v3/capacity/matches" => {:required_bearer, :capacity, :legacy},

      "get /api/v3/conversations/:conversation_id/boxes" => {:required_bearer, :box, :legacy},

    end

  end

  @doc """

  The account's threads, newest first.

  A client that outlives its process needs a way back to the work it was doing,

  and the account is the only place that knows. Bounded by the context, which

  caps what a list may return.

  """

  def index(conn, params) do

    user = conn.assigns.current_user

    _reaped = Threads.reap_expired(user)

    threads = Threads.list_for_user(user, listing_options(params))

    conn

    |> put_extension_header()

    |> json(%{"threads" => Enum.map(threads, &thread_view/1)})

  end

  @doc """

  A thread's transcript, oldest first.

  This is where a session's history lives. It is the server's copy and the only

  copy: a client reads it back rather than keeping its own, so two machines

  reading one thread see one transcript rather than two that have diverged.

  """

  def events(conn, %{"thread_id" => thread_id} = params) do

    with_thread(conn, thread_id, fn thread ->

      events = Threads.list_events(thread, listing_options(params))

      conn

      |> put_extension_header()

      |> json(%{

        "thread_id" => thread.id,

        "event_count" => thread.event_count,

        "events" => Enum.map(events, &event_view/1)

      })

    end)

  end

  @doc """

  Append one event to a thread's transcript.

  Append-only and bounded: the payload is capped by the database, and a

  terminal thread refuses, because a transcript that keeps growing after the

  report was written is not the transcript the report describes.

  """

  def record(conn, %{"thread_id" => thread_id} = params) do

    with_thread(conn, thread_id, fn thread ->

      case event_parameters(params) do

        {:ok, event_type, payload} -> append(conn, thread, event_type, payload)

        {:refused, field, message} -> ApiError.validation_failed(conn, %{field => [message]})

      end

    end)

  end

  def show(conn, %{"thread_id" => thread_id}) do

    with_thread(conn, thread_id, fn thread -> render_thread(conn, :ok, thread) end)

  end

    end)

  end

  defp append(conn, thread, event_type, payload) do

    case Threads.record_event(thread, event_type, payload) do

      {:ok, updated} ->

        conn

        |> put_extension_header()

        |> put_status(:created)

        |> json(%{"thread" => thread_view(updated)})

      {:error, :thread_terminal} ->

        sentence =

          "This thread is #{thread.status} and its transcript is closed. " <>

            "Open another thread to record more work."

        ApiError.refuse(conn, "thread_terminal",

          message: sentence,

          errors: %{"thread" => [sentence]}

        )

      {:error, changeset} ->

        ApiError.changeset(conn, changeset)

    end

  end

  # ── admission ───────────────────────────────────────────────────────────

  defp open(conn, objective, options) do

  # ── parameters ──────────────────────────────────────────────────────────

  # A limit outside the bounds is clamped by the context rather than refused: a

  # listing is a read, and a caller asking for more than the cap gets the cap.

  defp listing_options(params) do

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

      value when is_binary(value) ->

        case Integer.parse(value) do

          {limit, ""} -> [limit: limit]

          _unparsed -> []

        end

      _absent ->

        []

    end

  end

  defp event_parameters(params) do

    with {:ok, event_type} <- event_type(params),

         {:ok, payload} <- payload(params) do

      {:ok, event_type, payload}

    end

  end

  defp event_type(%{"event_type" => event_type}) when is_binary(event_type) do

    if String.trim(event_type) == "" do

      {:refused, "event_type", "The event type names what happened and cannot be blank."}

    else

      {:ok, event_type}

    end

  end

  defp event_type(_params) do

    {:refused, "event_type", "An event requires an event_type: what happened."}

  end

  defp payload(%{"payload" => payload}) when is_map(payload), do: {:ok, payload}

  defp payload(%{"payload" => payload}) do

    {:refused, "payload", "#{inspect(payload)} is not an object."}

  end

  defp payload(_params), do: {:ok, %{}}

  defp objective(%{"objective" => objective}) when is_binary(objective) do

    if String.trim(objective) == "" do

      {:refused, "objective", "The objective states what the thread is for and cannot be blank."}

  # 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.

  defp event_view(event) do

    %{

      "schema" => event.schema,

      "event_type" => event.event_type,

      "payload" => event.payload,

      "emitted_at" => stamp(event.emitted_at)

    }

  end

  defp thread_view(%Thread{} = thread) do

    %{

      "id" => thread.id,

    pipe_through :chat_account_api

    post "/threads", ThreadController, :create

    get "/threads", ThreadController, :index

    get "/threads/:thread_id", ThreadController, :show

    delete "/threads/:thread_id", ThreadController, :delete

    get "/threads/:thread_id/events", ThreadController, :events

    post "/threads/:thread_id/events", ThreadController, :record

  end

  scope "/api/v3/conversations/:conversation_id/boxes", OpenAgentsWeb do

^docs/2026-08-23-openagents-coder-cli-spec\.md:

^docs/2026-08-23-sarah-memory-voice-session-control-audit\.md:

^docs/2026-08-23-thread-primitive-audit\.md:

^docs/2026-08-24-delegation-release-handoff\.md:

^docs/2026-08-24-coder-account-integration-audit\.md:

^docs/chat-inference-plan\.md:

^docs/component-library\.md:

^docs/episode-triage\.md:

             )

  end

  defp git!(directory, args) do

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

    root: root

  } do

    {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

    # entry; the rebuilt projection must end at the newest head.

    source = Path.join(root, "rebuild-repo-source")

    File.write!(Path.join(source, "second.md"), "second commit\n")

    git!(source, ["add", "second.md"])

    git!(source, ["commit", "-m", "Second commit"])

    sha2 = source |> git!(["rev-parse", "HEAD"]) |> String.trim()

    refs = %{"refs/heads/trunk" => sha2}

    bundle = Path.join(root, "rebuild-repo-2.bundle")

    git!(source, ["bundle", "create", bundle, "--all"])

    {:ok, object} = WAL.put_entry_file("rebuild-repo", 1, bundle)

    entry = %{

      "seq" => 1,

      "object" => object,

      "format" => "git_bundle",

      "refs" => refs,

      "principal" => "test",

      "pushed_at" => DateTime.to_iso8601(DateTime.utc_now())

    }

    {: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.

    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:second.md"])) == "second commit"

    # The one-argument form the runbooks name resolves the default branch 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

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

    output

  end

    for route <- routes, route.plug_opts != :create do

      path = String.replace(route.path, ":thread_id", thread_id)

      body = conn |> dispatch_route(route.verb, path) |> json_response(200)

      # Whatever it answers. A route that refuses this bare call — `record`

      # requires an event type — is still a route that must not put a token in

      # its body, and the invariant is about what reaches the caller rather

      # than about which status it reaches them with.

      answered = dispatch_route(conn, route.verb, path)

      body = Jason.decode!(answered.resp_body)

      refute token?(body),

             """

    on_exit(restore)

    restore

  end

  describe "a thread's transcript" do

    setup %{conn: conn} do

      authenticated = put_chat_api_token(conn, "thread-transcript")

      created =

        authenticated

        |> post(~p"/api/v3/threads", %{"objective" => "Remember me."})

        |> json_response(201)

      %{authenticated: authenticated, id: created["thread"]["id"]}

    end

    test "records an event and advances the count", %{authenticated: conn, id: id} do

      before = conn |> get(~p"/api/v3/threads/#{id}") |> json_response(200)

      body =

        conn

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

          "event_type" => "turn.user",

          "payload" => %{"text" => "list the open issues"}

        })

        |> json_response(201)

      # Opening a thread records its own lifecycle event, so the count is a

      # delta rather than a total.

      assert body["thread"]["event_count"] == before["thread"]["event_count"] + 1

    end

    test "reads the transcript back, oldest first", %{authenticated: conn, id: id} do

      for text <- ["first", "second", "third"] do

        conn

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

          "event_type" => "turn.user",

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

        })

        |> json_response(201)

      end

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

      # The server's copy is the only copy: a client reads this back rather than

      # keeping its own, so two machines on one thread see one transcript.

      texts =

        body["events"]

        |> Enum.filter(&(&1["event_type"] == "turn.user"))

        |> Enum.map(& &1["payload"]["text"])

      assert texts == ["first", "second", "third"]

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

    end

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

      body =

        conn

        |> post(~p"/api/v3/threads/#{id}/events", %{"payload" => %{"text" => "x"}})

        |> json_response(422)

      assert body["errors"]["event_type"] != nil

    end

    test "refuses to append to a revoked thread", %{authenticated: conn, id: id} do

      conn |> delete(~p"/api/v3/threads/#{id}") |> json_response(200)

      body =

        conn

        |> post(~p"/api/v3/threads/#{id}/events", %{"event_type" => "turn.user"})

        |> json_response(422)

      # A transcript that keeps growing after the report was written is not the

      # transcript the report describes.

      assert body["code"] == "thread_terminal"

    end

    test "does not read another account's transcript", %{authenticated: conn, id: id} do

      conn

      |> post(~p"/api/v3/threads/#{id}/events", %{"event_type" => "turn.user"})

      |> json_response(201)

      stranger = put_chat_api_token(build_conn(), "thread-stranger")

      assert stranger |> get(~p"/api/v3/threads/#{id}/events") |> json_response(404)

    end

  end

  describe "GET /api/v3/threads" do

    test "lists the account's threads, newest first", %{conn: conn} do

      authenticated = put_chat_api_token(conn, "thread-index")

      for objective <- ["older", "newer"] do

        authenticated

        |> post(~p"/api/v3/threads", %{"objective" => objective})

        |> json_response(201)

      end

      body = authenticated |> get(~p"/api/v3/threads") |> json_response(200)

      # A client that outlives its process needs a way back to the work it was

      # doing, and the account is the only place that knows.

      assert Enum.map(body["threads"], & &1["objective"]) == ["newer", "older"]

    end

    test "does not list another account's threads", %{conn: conn} do

      put_chat_api_token(conn, "thread-mine")

      |> post(~p"/api/v3/threads", %{"objective" => "mine"})

      |> json_response(201)

      body =

        build_conn()

        |> put_chat_api_token("thread-theirs")

        |> get(~p"/api/v3/threads")

        |> json_response(200)

      assert body["threads"] == []

    end

  end

end