caller leaves nothing behind. Because a thread has at most one live grant,

  capping open threads caps the account's concurrent thread-scoped authority by

  the same number.

  Amended 2026-08-24 (issue #195): the cap holds under concurrency. The count

  is taken under the owner visitor row's `FOR UPDATE` lock, inside the

  transaction that inserts the thread, so two simultaneous opens at the

  boundary serialize and admit one thread, not two. The cap is what bounds the

  account's joint credit exposure (below), so a cap that a race could pass

  would make that bound a fiction.

  `test/openagents/threads/credit_race_test.exs` races the boundary.

- **A thread's budget is its own, and its money is the account's.**

  `OpenAgents.Threads.ceilings/0` reads the `thread_grant_*` settings and

  passes them to `OpenAgents.Inference.mint/1`, which otherwise applies the

  nothing left is refused `:credit_exhausted` rather than minted a grant it

  cannot spend. `GET /api/v3` publishes both allowances, because a client that

  read a fixed per-thread cost cap would be reading a budget nobody is given.

  Amended 2026-08-24 (issue #195): the remainder is metered spend, and mints

  serialize. `OpenAgents.Threads.mint_grant/1` locks the owner visitor row

  (after the thread row, always in that order) before reading

  `Credit.remaining/1` and minting, so concurrent mints for one account each

  read the remainder at their own serialization point rather than from a

  shared snapshot. What the remainder deliberately does not subtract is a live

  grant's unspent ceiling: a parent thread holds the whole remaining balance

  as its ceiling, and a delegated child thread opened while it runs must still

  be granted usable authority, so reserving headroom would refuse every such

  child with `:credit_exhausted` and break delegation. Overlapping live

  threads can therefore each be ceiled at the same remainder — concurrently or

  in sequence, the schedules mint identical figures — and the account's joint

  exposure is bounded by the admission cap times the remainder, which is why

  the cap above is serialized. Actual spend stays honest where money moves:

  every call is metered into the remainder, and an exhausted account cannot

  mint at all. `test/openagents/threads/credit_race_test.exs` proves the

  serialized figures, the exhausted refusal under race, and the unchanged

  serial ceilings.

- **Expiry revokes without being asked.** `OpenAgents.Threads.reap_expired/1`

  runs at admission and on every read of a thread: an active grant past

  `expires_at` becomes `expired`, and an open thread that has minted authority

| WORK-001 | `test/openagents/work_job_test.exs`, `test/openagents/deep_work_tool_loop_test.exs` |

| SELF-EDIT-001 | `test/openagents/tools/repository_mutation_tools_test.exs`, `test/openagents/coding_job_test.exs`, `test/openagents/dependency_boundary_test.exs` |

| SCV-001 | `test/openagents/scv/deployments_test.exs`, `test/openagents/dependency_boundary_test.exs` |

| THREAD-001 | `test/openagents/threads/grant_fence_test.exs`, `test/openagents/threads/grant_token_reach_test.exs`, `test/openagents/threads_test.exs` |

| THREAD-001 | `test/openagents/threads/grant_fence_test.exs`, `test/openagents/threads/grant_token_reach_test.exs`, `test/openagents/threads_test.exs`, `test/openagents/threads/credit_race_test.exs` |

| OUTCOME-001 | `test/openagents/accepted_outcome_test.exs`, `test/openagents/issues/completion_claims_test.exs`, `test/openagents_web/controllers/issue_completion_claim_controller_test.exs` |

| DEPLOYPLANE-001 | `test/openagents/deployments_test.exs`, `test/openagents_web/controllers/deployment_controller_test.exs`, `test/openagents_web/api_route_authority_test.exs` |

| DEPLOYPLANE-002 | `test/openagents/deployments_test.exs` |

     `maximum_active_boxes_per_owner`. A token that can open one thread could

     otherwise open unbounded threads and spend without a ceiling. Because a

     thread has at most one live grant, capping open threads caps the account's

     concurrent thread-scoped authority by the same number.

     concurrent thread-scoped authority by the same number. The count is taken

     under the owner visitor row's `FOR UPDATE` lock, inside the transaction

     that inserts, so two simultaneous opens at the boundary admit one thread,

     not two — the cap is what makes the account's joint credit exposure a

     bounded figure, so it has to hold under concurrency (issue #195).

  5. **The ceiling is self-clearing.** `reap_expired/1` runs at admission and

     on every read: an active grant whose clock has run out becomes `expired`,

     and the open thread it fenced becomes `failed` with `authority_expired`.

  def open(%Visitor{id: visitor_id} = owner, objective, options) when is_binary(objective) do

    _reaped = reap_expired(owner)

    if open_count(visitor_id) >= maximum_open_per_account() do

      {:error, :thread_quota_reached}

    else

      insert_thread(visitor_id, objective, options)

    end

    insert_thread(visitor_id, objective, options)

  end

  @doc """

    }

    Multi.new()

    |> Multi.run(:admission, fn repo, _changes ->

      # The cap is checked under the owner row's lock, inside the transaction

      # that inserts, so two simultaneous opens serialize here: the second

      # waits, counts the first's committed row, and is refused. A count read

      # outside the transaction could pass twice at the boundary and leave

      # nine open threads behind an eight-thread promise (issue #195).

      _serialized = lock_owner(repo, visitor_id)

      if open_count(visitor_id) >= maximum_open_per_account() do

        {:error, :thread_quota_reached}

      else

        {:ok, :admitted}

      end

    end)

    |> Multi.insert(:thread, Thread.open_changeset(attributes, visitor_id, now))

    |> Multi.run(:opened_event, fn _repo, %{thread: thread} ->

      insert_event(thread, "thread.opened", %{"objective_bytes" => byte_size(objective)}, now)

    |> Repo.transaction()

    |> case do

      {:ok, %{counted: thread}} -> {:ok, thread}

      {:error, :admission, :thread_quota_reached, _changes} -> {:error, :thread_quota_reached}

      {:error, _step, %Ecto.Changeset{} = changeset, _changes} -> {:error, changeset}

    end

  end

    Repo.transaction(fn ->

      case locked(thread.id) do

        %Thread{status: "open"} = current ->

          # Concurrent mints for one account serialize on the owner row

          # (locked after the thread row, always in that order), so each mint

          # reads the metered remainder at its own turn rather than from a

          # shared snapshot (issue #195). What the remainder deliberately does

          # not subtract is a live grant's unspent ceiling — see `ceilings/1`.

          _serialized = lock_owner(Repo, current.owner_visitor_id)

          _revoked = Inference.revoke_active_for_thread(current.id)

          with {:ok, fenced} <- current |> Thread.generation_changeset() |> Repo.update(),

  says is left — a signed-in account's whole balance is available to one thread

  if that is what the work needs. An account with nothing left is refused

  `:credit_exhausted` instead of being minted a grant it cannot spend.

  The remainder is metered spend, not minted ceilings: a live grant's unspent

  headroom is deliberately not subtracted, because a parent thread holds its

  whole remaining balance as ceiling and a delegated child thread opened while

  it runs must still be granted usable authority — reserving headroom would

  refuse every such child with `:credit_exhausted`. Two overlapping threads can

  therefore each be ceiled at the same remainder, whether opened concurrently

  or in sequence; `mint_grant/1` serializes concurrent mints on the owner row

  so each reads the remainder at its own turn, and the admission cap — itself

  serialized — bounds how many such ceilings can be live at once (issue #195,

  THREAD-001).

  """

  @spec ceilings(String.t()) :: {:ok, Inference.ceilings()} | {:error, :credit_exhausted}

  def ceilings(visitor_id) when is_binary(visitor_id) do

    Repo.one(from t in Thread, where: t.id == ^thread_id, lock: "FOR UPDATE")

  end

  # The serialization point for one account's admissions and mints. Lock order

  # is thread row first, owner row second, everywhere a transaction takes both,

  # so two writers cannot deadlock across the pair.

  defp lock_owner(repo, visitor_id) do

    repo.one(from v in Visitor, where: v.id == ^visitor_id, lock: "FOR UPDATE")

  end

  defp insert_event(%Thread{id: thread_id}, event_type, payload, now) do

    %Event{}

    |> Event.changeset(%{

defmodule OpenAgents.Threads.CreditRaceTest do

  @moduledoc """

  What two simultaneous thread opens can take from one account (issue #195).

  The admission count and the mint's remainder read are serialized on the

  owner visitor row, so concurrent opens produce exactly what the same opens

  produce in sequence: at the cap's boundary one thread is admitted, against

  an exhausted account both opens are refused and leave nothing behind, and

  each mint reads the metered remainder at its own turn.

  What is deliberately not asserted is that overlapping live ceilings sum to

  the remainder. A live grant's unspent headroom does not reserve credit,

  because a delegated child thread must be mintable while its parent holds the

  whole remaining balance as its ceiling — reserving headroom would refuse

  every such child with `:credit_exhausted`. The joint exposure is instead

  bounded by the admission cap, which is why the cap has to hold under

  concurrency (THREAD-001).

  """

  use OpenAgents.DataCase, async: false

  alias OpenAgents.Conversations

  alias OpenAgents.Conversations.Visitor

  alias OpenAgents.Inference

  alias OpenAgents.Inference.Credit

  alias OpenAgents.Inference.Grant

  alias OpenAgents.Threads

  test "simultaneous opens at the admission boundary admit exactly one thread" do

    cap(2)

    visitor = visitor("cap-race")

    {:ok, _first} = Threads.open(%Visitor{id: visitor}, "Already open")

    results =

      ["Second", "Third"]

      |> Task.async_stream(

        fn objective -> Threads.open(%Visitor{id: visitor}, objective) end,

        max_concurrency: 2,

        ordered: false,

        timeout: :infinity

      )

      |> Enum.map(fn {:ok, result} -> result end)

    assert Enum.count(results, &match?({:ok, _thread}, &1)) == 1

    assert Enum.count(results, &match?({:error, :thread_quota_reached}, &1)) == 1

    assert Threads.open_count(visitor) == 2

  end

  test "simultaneous opens against an exhausted account jointly mint nothing" do

    visitor = visitor("exhausted-race")

    {:ok, _spent} =

      Inference.record_usage(minted(visitor), %{

        "output_tokens" => output_tokens_costing(Credit.allowance(visitor))

      })

    assert Credit.remaining(visitor) == 0

    results =

      ["First racer", "Second racer"]

      |> Task.async_stream(

        fn objective -> Threads.open_and_mint(%Visitor{id: visitor}, objective) end,

        max_concurrency: 2,

        ordered: false,

        timeout: :infinity

      )

      |> Enum.map(fn {:ok, result} -> result end)

    assert Enum.all?(results, &match?({:error, :credit_exhausted}, &1))

    # A refused open cancels the thread it admitted and mints no authority.

    # The racers leave the account exactly one grant — the exhausted one that

    # spent the credit — and no open thread: exhausting the grant abandoned

    # its thread, and admission reaped it.

    assert Threads.open_count(visitor) == 0

    assert Repo.aggregate(from(g in Grant, where: g.owner_visitor_id == ^visitor), :count) == 1

  end

  test "simultaneous opens mint the serialized remainder, the figure sequential opens mint" do

    visitor = visitor("remainder-race")

    spent = 250_000

    {:ok, _spent} =

      Inference.record_usage(minted(visitor), %{"output_tokens" => output_tokens_costing(spent)})

    remainder = Credit.allowance(visitor) - spent

    assert Credit.remaining(visitor) == remainder

    grants =

      ["First racer", "Second racer"]

      |> Task.async_stream(

        fn objective -> Threads.open_and_mint(%Visitor{id: visitor}, objective) end,

        max_concurrency: 2,

        ordered: false,

        timeout: :infinity

      )

      |> Enum.map(fn {:ok, {:ok, _thread, grant, _token}} -> grant end)

    # Each racer is ceiled at the metered remainder — the same ceiling the two

    # opens mint in either serial order, because a mint spends nothing and a

    # live grant's headroom reserves nothing. Concurrency adds no exposure the

    # serial schedule does not already have; what bounds the sum of live

    # ceilings is the admission cap (THREAD-001, issue #195).

    assert Enum.map(grants, & &1.max_cost_microusd) == [remainder, remainder]

  end

  test "serial behavior is unchanged: the next thread is ceiled at what spend left behind" do

    visitor = visitor("serial")

    spent = 250_000

    {:ok, first} = Threads.open(%Visitor{id: visitor}, "Spend a little")

    {:ok, first, grant, _token} = Threads.mint_grant(first)

    assert grant.max_cost_microusd == Credit.allowance(visitor)

    {:ok, _spent} =

      Inference.record_usage(grant, %{"output_tokens" => output_tokens_costing(spent)})

    {:ok, _finished} = Threads.finish(first, %{report: "Done."})

    {:ok, second} = Threads.open(%Visitor{id: visitor}, "Spend the rest")

    {:ok, _second, next_grant, _token} = Threads.mint_grant(second)

    assert next_grant.max_cost_microusd == Credit.allowance(visitor) - spent

  end

  defp visitor(key) do

    {:ok, conversation} = Conversations.ensure_conversation("credit-race-#{key}")

    conversation.visitor_id

  end

  # A grant names exactly one fence, so spend is recorded through a real

  # thread's grant rather than a fenceless one the changeset would refuse.

  defp minted(visitor_id) do

    {:ok, thread} = Threads.open(%Visitor{id: visitor_id}, "Spend some credit")

    {:ok, _fenced, grant, _token} = Threads.mint_grant(thread)

    grant

  end

  # Cost is priced from tokens by `OpenAgents.Inference`, never taken from a

  # caller, so spend is stated here in the output tokens that price to it.

  defp output_tokens_costing(microusd) do

    div(

      microusd * 1_000,

      Application.fetch_env!(:openagents, :inference_output_price_microusd_per_ktoken)

    )

  end

  defp cap(limit) do

    previous = Application.get_env(:openagents, :maximum_open_threads_per_account)

    Application.put_env(:openagents, :maximum_open_threads_per_account, limit)

    on_exit(fn ->

      Application.put_env(:openagents, :maximum_open_threads_per_account, previous)

    end)

  end

end