- **Authority does not outlive the thread.** Every terminal transition

  (`OpenAgents.Threads.finish/2`, `OpenAgents.Threads.cancel/2`) revokes the

  thread's active grants inside the transaction that writes the terminal row,

  and `mint_grant/1` refuses a thread that is not open. Deleting a thread — or

  the account, under the DATA-004 cascade — deletes its grants with it.

  so no terminal thread ever holds a live grant. Deleting a thread — or the

  account, under the DATA-004 cascade — deletes its grants with it.

  Amended 2026-08-26 (issue #106): a thread that reported can be granted

  again, and being granted again is what reopens it.

  `OpenAgents.Threads.mint_grant/1` used to refuse every thread that was not

  open, which made the two halves of the contract contradict each other the

  moment a client started ending its threads honestly: every honest end is

  terminal, so a session could keep a thread resumable only by never saying

  what it did. `oa coder --resume` was refused before it reached the

  transcript it exists to replay. The mint now reopens a reported thread

  inside its own transaction — the report is written to the transcript as

  `thread.reopened`, the terminal columns clear, the admission cap is taken

  again under the same owner lock, and the generation advances — so the thread

  holding authority is an open thread at every instant, and reopening loses

  nothing that was recorded. A **cancelled** thread stays refused

  `:thread_terminal`: `DELETE` is a disposal, and a caller that used it asked

  for the thread to be over. A local-lane thread stays refused

  `:thread_local_lane` in every state.

- **A terminal thread says what happened, and cannot say two things.** Added

  2026-08-26 (issue #106). `POST /api/v1/threads/{id}/report` routes

  `finish/2`, which had no route and no caller in `lib/` — so `DELETE` was the

  only way to end a thread, and 31 of one account's 50 most recent threads

  read `cancelled` with "The thread was cancelled before it reported." for

  sessions that answered correctly and exited 0. The record said the opposite

  of what happened. The mirror of that bug is worse, so the outcome is stated

  rather than inferred and the statement has to be internally consistent: the

  route requires an explicit `status` from the terminal three and never

  defaults to `succeeded`, and `succeeded` carries no `error_code` while

  `failed` and `cancelled` must each name one.

  `OpenAgents.Threads.Thread.terminal_changeset/2` refuses a pair that

  disagrees and `threads_terminal_outcome_check` refuses it again in the

  database, so a run that failed, was interrupted, or exhausted its steps

  cannot be filed as a success by any writer. Reporting revokes exactly as

  cancelling does. A resent identical report is answered rather than refused,

  because a client retrying a call it never saw the answer to is not reporting

  twice; a *different* second report is refused `thread_terminal`, because a

  thread reports once and the standing report is not overwritten by a later

  claim.

- **A local-lane thread holds no authority, ever.** Added 2026-08-25 (issue

  #243). `threads.lane` admits `thread` and `local` by check constraint,

  defaulting to `thread` — the granted lane every earlier thread came

| 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`, `test/openagents/threads/credit_race_test.exs`, `test/openagents/threads/local_lane_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`, `test/openagents/threads/local_lane_test.exs`, `test/openagents_web/controllers/thread_controller_test.exs` |

| THREAD-002 | `test/openagents/threads/visibility_test.exs`, `test/openagents_web/thread_visibility_test.exs`, `test/openagents/threads/grant_token_reach_test.exs` |

| THREAD-003 | `test/openagents/threads_test.exs`, `test/openagents/threads/visibility_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` |

and never neither (THREAD-001). The context is `OpenAgents.Threads`, the record

is `OpenAgents.Threads.Thread`, and the transcript entry is

`OpenAgents.Threads.Event`. A caller opens one with `POST /api/v1/threads`,

reads what it has spent with `GET /api/v1/threads/{thread_id}`, and revokes it

with `DELETE /api/v1/threads/{thread_id}`, all behind the `chat:account` scope

and served by `OpenAgentsWeb.ThreadController`. A thread opened with

reads what it has spent with `GET /api/v1/threads/{thread_id}`, ends it with

`POST /api/v1/threads/{thread_id}/report`, and cancels it with

`DELETE /api/v1/threads/{thread_id}`, all behind the `chat:account` scope

and served by `OpenAgentsWeb.ThreadController`.

**Report versus cancel** — the two ways a thread ends, and they say different

things. To **report** is to say what the thread did: the caller names the

outcome (`succeeded`, `failed`, or `cancelled`) and the sentence that goes with

it, and the record carries that. To **cancel** is to end a thread that never

reported; `DELETE` writes `cancelled` with the error code `cancelled` and the

sentence "The thread was cancelled before it reported." Do not write "cancel"

for a session that finished its work, and do not write "finish" or "complete"

for a `DELETE` — the whole point of the pair is that a session that answered

correctly is not recorded as an abandonment (issue #106). To **resume** is to

ask for authority on a thread that already reported: `POST /grants` reopens it,

records `thread.reopened` in the transcript, and grants a new generation. A

cancelled thread cannot be resumed, because cancelling is a disposal. A thread opened with

`"lane": "local"` is transcript-only: its model is the vendor string a local

runtime serves, and it is never granted authority — the server records the run

without paying for it (THREAD-001, issue #243). The CLI that stops writing to

  tokens, or cost, is refused `:parent_authority_exhausted` rather than minted

  authority it cannot use.

  A local-lane thread is refused `:thread_local_lane` the way a terminal

  thread is refused `:thread_terminal`. Its model is a vendor string a local

  runtime serves, not an admitted catalog id, so a grant naming it would be

  authority no provider here can honor — and the lane's whole contract is that

  it holds none (issue #243). The refusal is what keeps the no-provider-key

  and metering invariants true by construction rather than by review.

  A local-lane thread is refused `:thread_local_lane`. Its model is a vendor

  string a local runtime serves, not an admitted catalog id, so a grant naming

  it would be authority no provider here can honor — and the lane's whole

  contract is that it holds none (issue #243). The refusal is what keeps the

  no-provider-key and metering invariants true by construction rather than by

  review.

  This is also the resume door. A thread that reported is reopened here: its

  report is written into the transcript as `thread.reopened`, the terminal

  columns clear, the account's admission cap is taken again, and the thread is

  granted fresh authority under a new generation. Without that, a client that

  ends its thread honestly could never come back to it — every honest end is

  terminal, and `mint_grant/1` used to refuse every terminal thread — so

  `oa coder --resume` would be refused before it could replay anything, and the

  only way to keep a thread resumable would be never to say what it did (issue

  #106). A cancelled thread is the exception, refused `:thread_terminal`:

  `DELETE` is a disposal, and a caller that used it asked for the thread to be

  over.

  This is the fence. In one transaction: the thread is locked and refused

  unless it is open, every active grant naming it is revoked, `generation` is

  bumped, and a fresh grant is minted against the thread — never against a

  conversation. Returns the plaintext token exactly once.

  unless it can hold authority, every active grant naming it is revoked, a

  thread that had reported is reopened, `generation` is bumped, and a fresh

  grant is minted against the thread — never against a conversation. Returns

  the plaintext token exactly once.

  """

  @spec mint_grant(Thread.t()) ::

          {:ok, Thread.t(), Grant.t(), String.t()}

          | {:error,

             :thread_terminal

             | :thread_local_lane

             | :thread_quota_reached

             | :credit_exhausted

             | :parent_authority_exhausted

             | Ecto.Changeset.t()}

  def mint_grant(%Thread{} = thread) do

    Repo.transaction(fn ->

      case locked(thread.id) do

        %Thread{status: "open", lane: "local"} ->

        %Thread{lane: "local"} ->

          Repo.rollback(:thread_local_lane)

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

        %Thread{status: "cancelled"} ->

          Repo.rollback(:thread_terminal)

        %Thread{} = 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

          _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(),

          with {:ok, reopened} <- reopen(current),

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

               {:ok, ceilings} <- grant_ceilings(fenced),

               {:ok, grant, token} <-

                 Inference.mint(%{

          else

            {:error, reason} -> Repo.rollback(reason)

          end

        _terminal ->

          Repo.rollback(:thread_terminal)

      end

    end)

    |> case do

    end

  end

  # An open thread is already where a mint needs it. A thread that reported is

  # reopened first: its report moves into the transcript, the terminal columns

  # clear, and the account's admission cap is taken again, because a reopened

  # thread holds an open thread's slot and an open thread's grant. Called

  # inside `mint_grant/1`'s transaction, after the owner row is locked, so the

  # count is the same serialized count `open/3` takes (issue #195).

  defp reopen(%Thread{status: "open"} = thread), do: {:ok, thread}

  defp reopen(%Thread{} = thread) do

    ceiling = maximum_open_per_account()

    if ceiling != nil and open_count(thread.owner_visitor_id) >= ceiling do

      {:error, :thread_quota_reached}

    else

      with {:ok, _event} <-

             insert_event(

               thread,

               "thread.reopened",

               reopened_payload(thread),

               DateTime.utc_now()

             ),

           {:ok, counted} <-

             thread

             |> Thread.event_count_changeset(thread.event_count + 1)

             |> Repo.update() do

        counted |> Thread.reopen_changeset() |> Repo.update()

      end

    end

  end

  # Reopening clears the terminal columns, so what the thread reported is

  # written into the transcript on the way past. The transcript is the durable

  # record either way, and this is what makes reopening lossless: a reader can

  # still see that the thread reported, what it said, and when.

  defp reopened_payload(%Thread{} = thread) do

    %{

      "status" => thread.status,

      "report" => thread.report,

      "report_type" => thread.report_type,

      "error_code" => thread.error_code,

      "completed_at" => thread.completed_at && DateTime.to_iso8601(thread.completed_at),

      "generation" => thread.generation

    }

  end

  @doc """

  End a thread with its bounded, typed report, revoking its authority in the

  same transaction. Idempotent refusal on an already-terminal thread.

  This is how a thread says what it did. `cancel/2` is how it says it was

  disposed of before saying anything, and the two are not interchangeable: a

  session that answered and exited 0 recorded as a cancellation says the

  opposite of what happened (issue #106). Its mirror is worse, so the outcome

  and the error code have to agree — `succeeded` carries no error code, and

  `failed` or `cancelled` has to name one. `Thread.terminal_changeset/2`

  refuses the pairs that disagree and `threads_terminal_outcome_check` refuses

  them again in the database.

  The status defaults to `succeeded` for an in-process caller that has already

  decided the work succeeded. `POST /api/v1/threads/{id}/report` takes no such

  default: a client states the outcome or is refused, because the server has no

  way to know whether a turn it did not run answered anything.

  """

  @spec finish(Thread.t(), map()) ::

          {:ok, Thread.t()} | {:error, :thread_terminal | Ecto.Changeset.t()}

  def finish(%Thread{} = thread, result) when is_map(result) do

    report = Map.get(result, :report) || Map.get(result, "report") || ""

    status = Map.get(result, :status) || Map.get(result, "status") || Thread.succeeded()

    attributes = %{

      status: Map.get(result, :status) || Map.get(result, "status") || "succeeded",

      status: status,

      report: report,

      report_digest: digest(report),

      report_type: Map.get(result, :report_type) || Map.get(result, "report_type") || "outcome",

      report_type:

        Map.get(result, :report_type) || Map.get(result, "report_type") || report_type(status),

      usage: Map.get(result, :usage) || Map.get(result, "usage") || %{},

      error_code: Map.get(result, :error_code) || Map.get(result, "error_code"),

      completed_at: DateTime.utc_now()

    terminate(thread, attributes)

  end

  # The report's type follows the outcome it reports unless the caller names

  # one, so a failure is not filed under the word a success uses.

  defp report_type("failed"), do: "failure"

  defp report_type("cancelled"), do: "cancelled"

  defp report_type(_succeeded), do: "outcome"

  @doc "Cancel a thread, revoking its authority in the same transaction."

  @spec cancel(Thread.t(), String.t()) ::

          {:ok, Thread.t()} | {:error, :thread_terminal | Ecto.Changeset.t()}

  @statuses ~w(open succeeded failed cancelled)

  @terminal_statuses ~w(succeeded failed cancelled)

  @succeeded "succeeded"

  @cancelled "cancelled"

  @permission_profiles ~w(read_only workspace_write)

  @reasoning_efforts ~w(none minimal low medium high max)

  @objective_bytes 32_768

  def open?(%__MODULE__{status: "open"}), do: true

  def open?(%__MODULE__{}), do: false

  @doc "The status a thread takes when its report names no outcome to disagree with."

  def succeeded, do: @succeeded

  @doc """

  Whether `thread` was cancelled — the one end that cannot be reopened.

  A cancelled thread was disposed of on purpose: `DELETE /api/v1/threads/{id}`

  is the verb, and a caller that used it asked for the thread to be over.

  Every other end is a state the work reached, and a later session may be

  granted authority on it again (THREAD-001).

  """

  @spec cancelled?(t()) :: boolean()

  def cancelled?(%__MODULE__{status: @cancelled}), do: true

  def cancelled?(%__MODULE__{}), do: false

  @doc """

  The immutable capture at open time. `owner_visitor_id`, `status`,

  `generation`, and `started_at` are set by the context, never cast from a

    |> check_constraint(:event_count, name: :threads_event_count_nonnegative_check)

  end

  @doc "The terminal receipt. A thread ends once and carries a typed report when it does."

  @doc """

  The terminal receipt. A thread ends once and carries a typed report when it

  does.

  The status and the error code have to agree, and the agreement is checked

  here rather than at each caller: `succeeded` means the thread carries no

  error code, and every other terminal status has to name one. Without that

  rule a caller could file an interrupted run, a failed one, or one that ran

  out of steps as `succeeded`, and the durable record would read as the

  opposite of what happened — which is the same class of bug as recording a

  session that answered correctly as `cancelled` (issue #106). The database

  refuses the same pair (`threads_terminal_outcome_check`), so no writer that

  skips this changeset can file one either.

  """

  def terminal_changeset(%__MODULE__{} = thread, attributes) do

    thread

    |> cast(attributes, [

    |> validate_format(:report_digest, ~r/\Asha256:[0-9a-f]{64}\z/)

    |> validate_length(:report_type, max: 80)

    |> validate_length(:error_code, max: 80)

    |> validate_outcome()

    |> check_constraint(:status, name: :threads_status_check)

    |> check_constraint(:report, name: :threads_report_bound_check)

    |> check_constraint(:report_type, name: :threads_report_type_bound_check)

    |> check_constraint(:error_code, name: :threads_terminal_outcome_check)

    |> check_constraint(:completed_at, name: :threads_terminal_shape_check)

  end

  defp validate_outcome(changeset) do

    status = get_field(changeset, :status)

    error_code = get_field(changeset, :error_code)

    cond do

      status == @succeeded and present?(error_code) ->

        add_error(

          changeset,

          :error_code,

          "must be empty on a thread that succeeded; name the status the outcome actually had"

        )

      status in @terminal_statuses and status != @succeeded and not present?(error_code) ->

        add_error(changeset, :error_code, "is required on a thread that did not succeed")

      true ->

        changeset

    end

  end

  defp present?(value), do: is_binary(value) and String.trim(value) != ""

  @doc """

  Reopen a thread that ended, so a later session can be granted authority on it

  again.

  A thread that reported is the thing `oa coder --resume` comes back to, and a

  grant cannot be minted for a terminal thread (THREAD-001). Reopening clears

  the terminal columns, which the shape constraint requires of an open row, and

  `OpenAgents.Threads.mint_grant/1` writes the report it is clearing into the

  transcript first, so nothing the thread reported is lost. Cancelling is the

  one end this does not undo: it is a disposal, not a pause.

  """

  def reopen_changeset(%__MODULE__{} = thread) do

    thread

    |> change(%{

      status: "open",

      report: nil,

      report_digest: nil,

      report_type: nil,

      error_code: nil,

      completed_at: nil

    })

    |> check_constraint(:status, name: :threads_status_check)

    |> check_constraint(:completed_at, name: :threads_terminal_shape_check)

  end

end

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

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

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

      "post /api/v1/threads/:thread_id/report" => {:required_bearer, :thread, :envelope},

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

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

      "post /api/v1/threads/:thread_id/grants" => {:required_bearer, :thread, :envelope},

        "GET /api/v1/models",

        "POST /api/v1/threads",

        "GET /api/v1/threads/{thread_id}",

        "GET /api/v1/threads/{thread_id}/events",

        "POST /api/v1/threads/{thread_id}/events",

        "POST /api/v1/threads/{thread_id}/report",

        "POST /api/v1/threads/{thread_id}/grants",

        "DELETE /api/v1/threads/{thread_id}"

      ],

      "parameters" => %{

            "`credit_exhausted`. Authority that passes `expires_at` stops " <>

            "being live and stops holding a slot, with or without a request."

      },

      "ending" => %{

        "description" =>

          "A thread ends one of two ways, and they are not interchangeable. " <>

            "POST /api/v1/threads/{thread_id}/report says what the thread did " <>

            "and revokes its authority; DELETE /api/v1/threads/{thread_id} " <>

            "cancels a thread that never reported and revokes the same way. A " <>

            "session that answered and exited 0 must report, or its permanent " <>

            "record reads as a cancellation. The report body names `status` — " <>

            "required, one of the terminal statuses, never assumed — and " <>

            "`report`, with optional `report_type` and `usage`. `status` and " <>

            "`error_code` must agree: `succeeded` carries no error code, and " <>

            "`failed` or `cancelled` must name one, so a run that failed " <>

            "cannot be filed as a success. Resending an identical report is " <>

            "answered; a different second report is refused `thread_terminal`.",

        "statuses" => OpenAgents.Threads.Thread.terminal_statuses(),

        "resume" =>

          "A thread that reported is not finished with. POST " <>

            "/api/v1/threads/{thread_id}/grants reopens it, records what it " <>

            "reported in the transcript as `thread.reopened`, and returns " <>

            "fresh authority under a new generation, so a later session can " <>

            "replay the transcript and carry on. A cancelled thread is refused " <>

            "`thread_terminal`: cancelling is a disposal, not a pause."

      },

      "grant" => %{

        "description" =>

          "POST returns the plaintext token exactly once. Spend it as the " <>

defmodule OpenAgentsWeb.ThreadController do

  @moduledoc """

  The door to a thread: open one, read what it has spent, revoke it.

  The door to a thread: open one, read what it has spent, say what it did,

  revoke it.

  A thread is the unit of agent work (`docs/taxonomy.md`), and its grant is the

  only way a client reaches a model without holding a provider key. So these

  - **Revocation does not wait to be asked.** `DELETE` revokes immediately, and

    every request first retires the account's elapsed authority, so a grant

    past its expiry stops being live whether or not anyone presents it.

  - **Ending honestly is a different act from being cancelled.**

    `POST /report` writes what the thread did and revokes; `DELETE` writes a

    cancellation and revokes. A session that answered and exited 0 has to be

    able to say so, or its permanent record says the opposite of what happened

    (issue #106) — and a session that failed has to be unable to claim it

    succeeded, which is the same bug pointed the other way.

  - **Disclosure is opt-in and narrow.** A thread opens `dark` — owner-only —

    unless the caller names a wider transparency tier, and a tier this surface

    cannot enforce is refused with `thread_visibility_unsupported`. A wider

    end)

  end

  @doc """

  Say what the thread did, and end it.

  This is the route a session calls when its work is over and it has something

  to say about it. Without it the only way to end a thread was `DELETE`, which

  writes `cancelled` and the sentence "The thread was cancelled before it

  reported." — so a session that answered correctly and exited 0 was recorded

  as a cancellation, and 31 of one account's 50 most recent threads read that

  way (issue #106). The record said the opposite of what happened.

  The outcome is the caller's to state, and stating it is mandatory. A body

  with no `status` is refused rather than filed as a success: the server did

  not run the turns and has no way to know whether they answered anything, and

  a default of `succeeded` would be the same bug pointed the other way — a run

  that failed, was interrupted, or exhausted its steps recorded as having

  worked. The status and the error code have to agree: `succeeded` carries no

  error code, and `failed` or `cancelled` has to name one. Both halves are

  refused by `OpenAgents.Threads.Thread.terminal_changeset/2` and by

  `threads_terminal_outcome_check`, so no client and no future caller can file

  a pair that disagrees.

  Ending revokes, exactly as `DELETE` does — authority does not outlive the

  thread (THREAD-001) — and the response carries the revoked grant so a client

  reads what the session spent in the same answer that ends it.

  A resent identical report is answered rather than refused, so a client that

  retries a timed-out call is not told its own report failed. A *different*

  second report is refused `thread_terminal`: a thread reports once, and the

  standing report is not overwritten by a later claim.

  A thread that reported is not finished with. `POST /grants` reopens it and

  hands back fresh authority, which is what `oa coder --resume` needs; see

  `mint/2`.

  """

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

    with_thread(conn, thread_id, fn thread ->

      case outcome(params) do

        {:ok, result} -> file_report(conn, thread, result)

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

      end

    end)

  end

  defp file_report(conn, thread, result) do

    case Threads.finish(thread, result) do

      {:ok, finished} ->

        render_thread(conn, :ok, finished)

      {:error, :thread_terminal} ->

        replay_or_refuse(conn, thread, result)

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

        ApiError.changeset(conn, changeset)

    end

  end

  # A client that retried a call it never saw the answer to is not reporting

  # twice; it is asking whether its one report landed. So an identical resend

  # is answered with the standing thread, and only a report that says something

  # different is refused.

  defp replay_or_refuse(conn, thread, result) do

    if thread.report == Map.fetch!(result, :report) and

         thread.status == Map.fetch!(result, :status) do

      render_thread(conn, :ok, thread)

    else

      sentence =

        "This thread is #{thread.status} and has already reported. " <>

          "A thread reports once; open another thread instead."

      ApiError.refuse(conn, "thread_terminal",

        message: sentence,

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

      )

    end

  end

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

    with_thread(conn, thread_id, fn thread ->

      # Cancelling revokes the thread's authority inside the transaction that

    end)

  end

  @doc """

  Re-mint a thread's authority: the resume door.

  Re-minting is the resume fence — it revokes every active grant, bumps the

  generation, and hands back fresh authority on the same thread, so a resumed

  session can never race a zombie of its former self (THREAD-001). The

  plaintext token exists exactly once, in this response, like the one

  `POST /api/v1/threads` returns.

  A thread that reported is reopened here rather than refused. Every honest end

  is terminal, so refusing every terminal thread meant a client could keep a

  thread resumable only by never saying what it did — the transcript would be

  there and no session could be granted authority to continue it. What it

  reported is written into the transcript as `thread.reopened` before the

  terminal columns clear, so reopening loses nothing.

  A cancelled thread is refused `thread_terminal`. `DELETE` is a disposal, and

  a caller that used it asked for the thread to be over; resuming it would make

  cancellation mean nothing. A local-lane thread is refused `thread_lane_local`

  in every state: it can never hold authority at all.

  """

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

    with_thread(conn, thread_id, fn thread ->

      # Re-minting is the resume fence: it revokes every active grant, bumps

      # the generation, and hands back fresh authority on the same thread, so

      # a resumed session can never race a zombie of its former self

      # (THREAD-001). The plaintext token exists exactly once, in this

      # response, like the one `POST /api/v1/threads` returns.

      case Threads.mint_grant(thread) do

        {:ok, minted, grant, token} ->

          conn

        {:error, :thread_terminal} ->

          sentence =

            "This thread is #{thread.status} and holds no authority to re-mint. " <>

              "Open another thread instead."

            "This thread was cancelled, so it holds no authority to re-mint and " <>

              "cannot be resumed. Open another thread instead. A thread that " <>

              "reported its outcome can be resumed here; a cancelled one is over."

          ApiError.refuse(conn, "thread_terminal",

            message: sentence,

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

          )

        {:error, :thread_quota_reached} ->

          quota_reached(conn)

        {:error, :credit_exhausted} ->

          credit_exhausted(conn)

    {:refused, "events[#{index}]", "#{inspect(event)} is not an object."}

  end

  # What a thread reports, read from the body with nothing inferred. Every

  # refusal here is a 422 naming its field: the alternative is guessing, and a

  # guess that lands on `succeeded` is the mirror of the bug this route exists

  # to fix (issue #106).

  defp outcome(params) do

    with {:ok, status} <- terminal_status(params),

         {:ok, report} <- terminal_report(params),

         {:ok, error_code} <- error_code(params, status),

         {:ok, report_type} <- report_type(params),

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

      {:ok,

       %{

         status: status,

         report: report,

         error_code: error_code,

         usage: usage

       }

       |> put_present(:report_type, report_type)}

    end

  end

  defp put_present(map, _key, nil), do: map

  defp put_present(map, key, value), do: Map.put(map, key, value)

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

    if status in Thread.terminal_statuses() do

      {:ok, status}

    else

      {:refused, "status",

       "must be one of #{Enum.join(Thread.terminal_statuses(), ", ")}, naming how the thread ended"}

    end

  end

  defp terminal_status(_params) do

    {:refused, "status",

     "is required: name how the thread ended, one of " <>

       "#{Enum.join(Thread.terminal_statuses(), ", ")}. The server does not assume a run " <>

       "succeeded because it stopped."}

  end

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

    case String.trim(report) do

      "" -> {:refused, "report", "cannot be blank"}

      _present -> {:ok, report}

    end

  end

  defp terminal_report(_params), do: {:refused, "report", "is required"}

  # A success that names an error code and a failure that names none are both

  # refused, because the durable record has to say one thing about what

  # happened rather than two.

  defp error_code(params, status) do

    given = params |> Map.get("error_code") |> blank_to_nil()

    cond do

      not is_nil(Map.get(params, "error_code")) and not is_binary(Map.get(params, "error_code")) ->

        {:refused, "error_code", "must be a string"}

      status == Thread.succeeded() and given != nil ->

        {:refused, "error_code",

         "must be empty on a thread that succeeded; report the status the run actually had"}

      status != Thread.succeeded() and given == nil ->

        {:refused, "error_code", "is required on a thread that did not succeed: name why"}

      true ->

        {:ok, given}

    end

  end

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

    case String.trim(report_type) do

      "" -> {:refused, "report_type", "cannot be blank"}

      trimmed when byte_size(trimmed) > 80 -> {:refused, "report_type", "is longer than 80 bytes"}

      _present -> {:ok, report_type}

    end

  end

  defp report_type(%{"report_type" => value}) when not is_nil(value) do

    {:refused, "report_type", "must be a string"}

  end

  defp report_type(_params), do: {:ok, nil}

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

  defp usage(%{"usage" => nil}), do: {:ok, %{}}

  defp usage(%{"usage" => _other}), do: {:refused, "usage", "must be an object"}

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

  defp blank_to_nil(value) when is_binary(value) do

    case String.trim(value) do

      "" -> nil

      _present -> value

    end

  end

  defp blank_to_nil(_value), do: nil

  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."}

      "generation" => thread.generation,

      "event_count" => thread.event_count,

      "report" => thread.report,

      "report_type" => thread.report_type,

      "error_code" => thread.error_code,

      "started_at" => stamp(thread.started_at),

      "completed_at" => stamp(thread.completed_at),

    get "/threads", ThreadController, :index

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

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

    post "/threads/:thread_id/report", ThreadController, :report

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

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

    post "/threads/:thread_id/grants", ThreadController, :mint

    20260825195623,

    20260825220000,

    20260825230000,

    20260826010000

    20260826010000,

    20260826103000

  ],

  "required_tables": [

    "users",

defmodule OpenAgents.Repo.Migrations.AddThreadTerminalOutcomeCheck do

  use Ecto.Migration

  @moduledoc """

  A thread's terminal status and its error code have to agree.

  `succeeded` means no error code; every other terminal status names one. The

  rule exists because the terminal row is the durable record of what a session

  did, and the two ways it can lie are symmetric: a session that answered and

  exited 0 recorded as `cancelled` (issue #106), and a session that failed, was

  interrupted, or ran out of steps recorded as `succeeded`. Giving

  `OpenAgents.Threads.finish/2` an HTTP route makes the second one reachable by

  any client, so the pair is refused here as well as in the changeset.

  The constraint is created `NOT VALID`: it is enforced on every insert and

  update from this point on, and the historical scan is skipped so the

  migration does not hold a lock over the whole table while the previous

  release is still serving. Every writer that has ever ended a thread —

  `cancel/2`, the authority reaper, and `finish/2`'s default — already writes a

  pair this admits, so there is nothing for the scan to find; skipping it is a

  deployment courtesy rather than a concession.

  """

  def up do

    execute("""

    ALTER TABLE threads

    ADD CONSTRAINT threads_terminal_outcome_check

    CHECK (

      status = 'open'

      OR (status = 'succeeded' AND (error_code IS NULL OR btrim(error_code) = ''))

      OR (status <> 'succeeded' AND error_code IS NOT NULL AND btrim(error_code) <> '')

    )

    NOT VALID

    """)

  end

  def down do

    execute("ALTER TABLE threads DROP CONSTRAINT threads_terminal_outcome_check")

  end

end

      assert cancelled.status == "cancelled"

      assert cancelled.error_code == "cancelled"

    end

    test "a report that names an outcome carries it, error code and all" do

      user = owner("finish-failed")

      {:ok, thread} = Threads.open(user, "Run out of steps")

      assert {:ok, failed} =

               Threads.finish(thread, %{

                 status: "failed",

                 report: "The turn budget ran out before an answer.",

                 report_type: "failure",

                 error_code: "max_steps"

               })

      assert failed.status == "failed"

      assert failed.error_code == "max_steps"

    end

    test "a success cannot carry an error code" do

      user = owner("finish-incoherent-success")

      {:ok, thread} = Threads.open(user, "Claim both")

      assert {:error, %Ecto.Changeset{} = changeset} =

               Threads.finish(thread, %{

                 status: "succeeded",

                 report: "It worked.",

                 error_code: "max_steps"

               })

      assert %{error_code: [_ | _]} = errors_on(changeset)

      assert Threads.get_for_user(user, thread.id).status == "open"

    end

    test "a failure has to name why, so nothing ends unexplained" do

      user = owner("finish-incoherent-failure")

      {:ok, thread} = Threads.open(user, "Fail silently")

      assert {:error, %Ecto.Changeset{} = changeset} =

               Threads.finish(thread, %{status: "failed", report: "It did not work."})

      assert %{error_code: [_ | _]} = errors_on(changeset)

      assert Threads.get_for_user(user, thread.id).status == "open"

    end

    test "the coherence rule is the database's too, not only the changeset's" do

      user = owner("finish-coherence-db")

      {:ok, thread} = Threads.open(user, "Write around the changeset")

      assert_raise Postgrex.Error, fn ->

        Repo.update_all(

          from(t in Thread, where: t.id == ^thread.id),

          set: [

            status: "succeeded",

            report: "It worked.",

            report_digest: "sha256:" <> String.duplicate("0", 64),

            report_type: "outcome",

            error_code: "max_steps",

            completed_at: DateTime.utc_now()

          ]

        )

      end

    end

  end

  describe "mint_grant/1 — the thread fence" do

      assert Threads.active_grants(finished) == []

      assert {:error, :grant_revoked} = Inference.resolve(token)

      assert {:error, :thread_terminal} = Threads.mint_grant(finished)

    end

    test "a cancelled thread is refused: cancelling is the end that means it" do

      user = owner("cancelled-no-remint")

      {:ok, thread} = Threads.open(user, "Cancel then resume")

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

      {:ok, cancelled} = Threads.cancel(thread)

      assert {:error, :thread_terminal} = Threads.mint_grant(cancelled)

      assert Threads.get_for_user(user, thread.id).status == "cancelled"

    end

    test "a thread that reported is re-granted by reopening it, and keeps its report" do

      user = owner("remint-reported")

      {:ok, thread} = Threads.open(user, "Report then resume")

      {:ok, thread, _grant, first_token} = Threads.mint_grant(thread)

      {:ok, finished} = Threads.finish(thread, %{report: "It worked.", report_type: "outcome"})

      assert {:ok, resumed, grant, token} = Threads.mint_grant(finished)

      assert resumed.status == "open"

      assert resumed.report == nil

      assert resumed.report_digest == nil

      assert resumed.report_type == nil

      assert resumed.error_code == nil

      assert resumed.completed_at == nil

      assert resumed.generation == 2

      assert grant.thread_id == thread.id

      assert {:ok, %Grant{status: "active"}} = Inference.resolve(token)

      assert {:error, :grant_revoked} = Inference.resolve(first_token)

      # Nothing is lost by reopening: the report the thread carried moves into

      # the transcript, which is the durable record either way.

      reopened =

        resumed |> Threads.list_events() |> Enum.find(&(&1.event_type == "thread.reopened"))

      assert reopened.payload["status"] == "succeeded"

      assert reopened.payload["report"] == "It worked."

      assert reopened.payload["error_code"] == nil

      # And the transcript accepts the resumed session's turns.

      assert {:ok, _appended} = Threads.record_event(resumed, "turn.user", %{"text" => "again"})

    end

    test "a failed thread resumes too: failing is a state of the work, not a disposal" do

      user = owner("remint-failed")

      {:ok, thread} = Threads.open(user, "Fail then resume")

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

      {:ok, failed} =

        Threads.finish(thread, %{

          status: "failed",

          report: "The turn budget ran out.",

          error_code: "max_steps"

        })

      assert {:ok, resumed, _grant, _token} = Threads.mint_grant(failed)

      assert resumed.status == "open"

      assert resumed.error_code == nil

    end

    test "deleting a thread deletes its authority" do

    end

  end

  describe "POST /api/v1/threads/:thread_id/report" do

    setup %{conn: conn} do

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

      created =

        authenticated

        |> post(~p"/api/v1/threads", %{"objective" => "Answer, then say so."})

        |> json_response(201)

      %{

        authenticated: authenticated,

        id: created["thread"]["id"],

        token: created["grant"]["token"]

      }

    end

    test "a thread that reported is recorded as having reported, not cancelled", %{

      authenticated: conn,

      id: id,

      token: token

    } do

      body =

        conn

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

          "status" => "succeeded",

          "report" => "The answer is 4."

        })

        |> json_response(200)

      assert body["thread"]["status"] == "succeeded"

      assert body["thread"]["error_code"] == nil

      assert body["thread"]["report"] == "The answer is 4."

      assert body["thread"]["report_type"] == "outcome"

      # Reporting revokes, exactly as cancelling does: authority does not

      # outlive the thread's end (THREAD-001).

      assert {:error, :grant_revoked} = Inference.resolve(token)

      assert body["grant"]["status"] == "revoked"

    end

    test "the server never guesses the outcome: a report with no status is refused", %{

      authenticated: conn,

      id: id

    } do

      body =

        conn

        |> post(~p"/api/v1/threads/#{id}/report", %{"report" => "Something happened."})

        |> json_response(422)

      assert body["code"] == "validation_failed"

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

      assert conn

             |> get(~p"/api/v1/threads/#{id}")

             |> json_response(200)

             |> get_in([

               "thread",

               "status"

             ]) == "open"

    end

    test "a run that failed cannot be recorded as a success", %{authenticated: conn, id: id} do

      body =

        conn

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

          "status" => "succeeded",

          "report" => "It worked.",

          "error_code" => "max_steps"

        })

        |> json_response(422)

      assert body["code"] == "validation_failed"

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

    end

    test "a failure has to name why", %{authenticated: conn, id: id} do

      body =

        conn

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

          "status" => "failed",

          "report" => "It did not work."

        })

        |> json_response(422)

      assert body["code"] == "validation_failed"

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