GeezerVison

Plan: chat-tree-model

Project chat-tree-model (implement-medium). Repository coder/coder, base origin/main (a698b026fe).
Branch stack: scott/chat-tree/1-chat-kind and scott/chat-tree/2-chat-tree, two draft PRs.

Revision 2: incorporates the plan panel review (REVIEW-plan.md).

Scope

First layer of the chat tree: data model, semantics, internal functions, and HTTP API. No UI, no
parent/child messaging tool. Everything user-visible is behind the new chat-tree experiment.

Out of scope: sidebar tree (project chat-tree-ui), send_chat_message tool (project
chat-tree-messaging), move/reparent API, drag and drop. One exception, accepted from review:
four existing frontend sites that infer "subagent" from parent_chat_id are switched to kind
so the legacy sidebar does not misrender named children when the experiment is on.

What the code does today (verified)

• chats.parent_chat_id and chats.root_chat_id are set only on subagent chats
  (coderd/x/chatd/subagent.go:1208-1380, both set at :1277-1278, :1351-1352). Subagents
  cannot spawn subagents (subagent_catalog.go:264-272), so root_chat_id == parent_chat_id on
  every existing child.
• "parent_chat_id IS NULL" is the de facto discriminator for "top-level user chat" in:
  • SQL: GetChats (chats.sql:747), GetChatWorkerAcquisitionCandidates (:2477),
    GetAutoArchiveInactiveChatCandidates (:2544), AutoArchiveInactiveChats (:2929),
    CountChatCapacityActiveByPool / CountChatCapacityQueuedByPool / GetChatQueuedForCapacity
    (:2967, :2979, :3000), GetChatsUpdatedAfter telemetry has_parent (:2393).
  • Schema: chat_acl_only_on_root_chats, chats_pin_order_parent_check,
    idx_chats_auto_archive_candidates, idx_chats_worker_acquisition_candidates
    (dump.sql:2212, :2216, :4804, :4822).
  • View chats_expanded coalesces a child's ACL from COALESCE(root_chat_id, parent_chat_id)
    (dump.sql:2327-2337); the same LEFT JOIN and explicit column list is copied into 17 query
    CTEs in chats.sql. sqlc.yaml:204 maps the view to database.Chat.
  • Go (complete sweep list in PR 1 step 4 below).
• Family operations key on root_chat_id: GetChatFamilyIDsByRootID (chats.sql:362, used by
  chatstate.SetFamilyArchived, family.go:67-115), auto-archive activity and cascade
  (:2924, :2946), aibridge GetAIBridgeChatCost (aibridge.sql:797). ArchiveChatByID /
  UnarchiveChatByID (chats.sql:1-130) have no production callers (verify during PR 1).
• FKs parent_chat_id and root_chat_id are ON DELETE SET NULL. The only deletion path is
  DeleteOldChats (dbpurge of archived chats by updated_at, chats.sql:2369); there is no
  DELETE endpoint.
• chatstate.CreateChat requires at least one initial message and lands in running
  (chatstate/transitions.go:98-121). CreateChat publishes a sidebar created watch event
  (chatd.go:1464).
• httpmw.RequireExperimentWithDevBypass skips the check in dev builds and RequireExperiment
  returns 403 (httpmw/experiments.go:36-58); exp_chats.go:4742-4745 shows the
  api.Experiments.Enabled + httpapi.ResourceNotFound pattern.
• Audit: enterprise/audit/table.go:443-491; parent_chat_id/root_chat_id are ActionIgnore.
• Chat RBAC is owner-scoped; ACL sharing is read-only (codersdk/chats.go:1944,
  rbac/roles.go:456, :1206). SetFamilyArchived runs each member through ChatMachine.Update
  on the dbauthz store, so cascades are authorised per row.
• Frontend sites that infer "subagent" from parent_chat_id:
  site/src/pages/AgentsPage/AgentsPageLayout.tsx:134, :575, :614-621;
  site/src/components/ChatConversation/chatHelpers.ts:94-108 (cost key, resolved via
  root_chat_id ?? parent_chat_id).

Design decisions

D1. Reuse parent_chat_id; keep root_chat_id as the subagent-family root (flag on decision 1)

Decision 1 (reuse parent_chat_id / root_chat_id) is viable for parent_chat_id but needs a
semantic migration because "has a parent" currently means "is a subagent". Giving root_chat_id
the meaning "tree root" would additionally break every family operation listed above (archive
cascade, auto-archive activity, cost aggregation, ACL inheritance would all span the user's whole
tree), and reparenting a shared chat would violate chat_acl_only_on_root_chats and then have its
own ACL overridden by the root's empty ACL in chats_expanded.

Chosen variant:

• parent_chat_id: immediate parent of any kind. Set on named children (parent is the root or
  another named chat) and on subagents (parent is the spawning chat). Unchanged for existing rows.
• root_chat_id: unchanged meaning, the nearest non-subagent ancestor of a subagent chat. NULL on
  the root and on named chats. Never points at the tree root unless the tree root itself spawned
  the subagent. It is not the tree root: downstream projects locate the tree root by
  (owner_id, organization_id, kind = 'root') or by walking parent_chat_id.
• kind chat_kind NOT NULL DEFAULT 'chat' discriminator, values root, chat, subagent.
• The tree root of any non-subagent chat is the unique kind = 'root' row for
  (owner_id, organization_id), so no per-row tree-root pointer is required. Depth is computed
  with a bounded recursive CTE over parent_chat_id.
• Cross-owner or cross-organisation parents are enforced in Go (validateChatTreeParent), not by
  a composite FK. Every tree query filters by owner and organisation, so a bad pointer can only
  truncate a tree, never leak a chat.

Alternatives considered: (a) root_chat_id = tree root, with all family operations rewritten to
target "chat plus its subagents" via parent_chat_id (more churn, every ACL CTE changes meaning);
(b) a separate tree_parent_chat_id column (smallest blast radius, but contradicts decision 1 and
gives the UI two parent pointers to merge). This variant is raised at the step 3 checkpoint.

D2. Every "is subagent" gate keys on kind

PR 1 replaces each parent_chat_id IS NULL / ParentChatID.Valid gate with kind. With the kind
backfilled from parent_chat_id, PR 1 is behaviour-neutral (the FK change moved to PR 2 for this
reason). Completion criterion: rg 'ParentChatID.Valid' coderd/ enterprise/ returns only
wire-format copies (debug run context, hook ChatRef, db2sdk pointer copy, header logging).

D3. Root creation is a new idle-create transition

chatstate.CreateIdleChat: inserts the chat with the same initial system messages CreateChat
uses (deployment prompt when configured, detached workspace awareness) and no user message,
status = waiting, no ownership hint, no watch event. The state machine gains N -> W: CreateIdle.
A W row is never selected by GetChatWorkerAcquisitionCandidates; the first SendMessage
follows the normal W -> R0 path. (Revised at step 6, REVIEW-diff #6: the original "no messages"
wording would have let root turns run without the deployment system prompt.) TODO items are left in ARCHITECTURE.md (not edited beyond TODO markers).

D4. Lazy tree materialisation, owner context, advisory lock

chatd.Server.EnsureChatTreeRoot(ctx, ownerID, orgID) (root database.Chat, created bool, err error):

1. Fast path: one query GetChatTreeRootStateByOwnerAndOrganization returning the root row (if
   any) and the count of adoptable chats (kind = 'chat' AND parent_chat_id IS NULL). If the root
   exists and the count is 0, return.
2. Slow path: InTx(ReadCommitted); pg_advisory_xact_lock(hashtext('chat_tree:' || owner || org));
   re-read; create the root with CreateIdleChat if absent (title constant Root, model config
   resolved exactly like postChats without an explicit model, no workspace);
   AdoptParentlessChatsIntoTreeRoot reparents every kind = 'chat' AND parent_chat_id IS NULL
   chat of that owner in that org, archived included. The UPDATE changes only parent_chat_id:
   no updated_at change (retention and sidebar order), no snapshot_version bump, no pubsub or
   watch event. Runner snapshots keep a stale ParentChatID until their next transition, which is
   safe once D2 is complete.
3. Partial unique index chats_one_tree_root_per_owner_org ON chats(owner_id, organization_id) WHERE kind = 'root' is the invariant; the advisory lock serialises creators, so a unique
   violation is returned as an error, not retried inside the aborted transaction.

All queries run as the acting user. InsertChat is authorised with WithOwner(owner);
AdoptParentlessChatsIntoTreeRoot, GetChatTreeRootStateByOwnerAndOrganization, and
GetChatTreeByOwnerAndOrganization are authorised in dbauthz against
ResourceChat.WithOwner(owner).InOrg(org) for ActionUpdate / ActionRead. No
AsSystemRestricted is needed. Reparenting a pinned or shared chat needs no data changes because
the pin and ACL constraints are rewritten to kind (D2).

If the organisation has no usable model config, EnsureChatTreeRoot returns
ErrChatTreeRootUnavailable; GET .../chats/tree then responds 200 with root_chat_id: null and
the owner's parentless chats; POST /chats fails on model resolution as it does today, with or
without parent_chat_id, so no chain can be created that is not anchored at a root.

Audit: the tree handler records AuditActionCreate for the root when created is true.
Adoption is not audited (no handler-level resource; documented in the PR).

D5. Cascades walk parent_chat_id recursively; parent archived implies subtree archived

GetChatFamilyIDsByRootID is renamed GetChatSubtreeIDs and becomes WITH RECURSIVE over
parent_chat_id (depth bound 6: 5 tree levels plus one subagent level). For a chat without named
children this yields exactly the current family. SetFamilyArchived keeps its all-or-nothing rule
(a running descendant fails the request) and its ErrChatNotRoot guard changes from
ParentChatID.Valid to Kind == subagent. ArchiveChatByID/UnarchiveChatByID are left
untouched if confirmed unused (comment updated), otherwise rewritten the same way.

The invariant "an archived chat has no unarchived descendant" is maintained by:

• archive: cascade over the recursive subtree (above);
• create: validateChatTreeParent reads the parent with GetChatByIDForUpdate inside the create
  transaction (parent-first lock order, matching SetFamilyArchived, which locks the subtree root
  first) and rejects archived = true (400);
• unarchive: reads the parent (plain read, before locking the target) and fails while the parent
  is archived; the existing rule for subagents extended to named children;
• unarchive cascade: applies to the chat and its subagents only. Named descendants that were
  archived stay archived (no resurrection of independently archived chats);
• auto-archive: a kind = 'chat' candidate is inactive only when its whole recursive subtree is
  inactive, and the cascade archives the recursive subtree. The root is never a candidate.

Delete cascade (PR 2): chats_parent_chat_id_fkey and chats_root_chat_id_fkey become
ON DELETE CASCADE (a subagent's parent and root are the same row). DeleteOldChats additionally
skips rows with any unarchived row in their recursive subtree and its comment is updated. This
also fixes the latent orphaning of subagents when a purged parent's children became apparent
roots. Recorded consequence: a subtree is purged by the parent's retention age.

D6. Experiment chat-tree

Checked with api.Experiments.Enabled(codersdk.ExperimentChatTree) (no dev bypass), returning
httpapi.ResourceNotFound (404) for the tree route and 400 for parent_chat_id in POST /chats.

• Off: POST /chats rejects parent_chat_id (400), never touches the tree; tree route 404;
  no root is created; existing chats stay parentless.
• On: POST /chats calls EnsureChatTreeRoot and defaults parent_chat_id to the root;
  tree route active.

D7. Two PRs

• PR 1 feat(coderd): add chat kind discriminator on scott/chat-tree/1-chat-kind.
• PR 2 feat(coderd): add chat tree root, named children, and tree API on
  scott/chat-tree/2-chat-tree (base PR 1).

Invariants (contract for chat-tree-messaging and chat-tree-ui)

Kind:

• kind = 'root': the per (owner_id, organization_id) tree root. Real chat, own transcript and
  agent, no workspace binding at creation. parent_chat_id IS NULL, root_chat_id IS NULL.
  Exactly zero or one per owner per organisation (partial unique index). Created lazily, never
  eagerly. Cannot be archived (PATCH archived -> 400 Chat tree root cannot be archived),
  auto-archive never selects it, therefore never purged. Cannot be pinned (400). Cannot be shared:
  PATCH /chats/{chat}/acl on a root is rejected and its ACL stays empty (a shared root would be
  invisible to the sharee, since GET /chats excludes roots and the tree is owner-only). Created
  with title Root and the standard initial system messages; title generation never runs for it
  (it runs only from POST /chats); PATCH title works. It can spawn subagents and receive messages
  like any chat.
• kind = 'chat': a user chat. With the experiment on, parent_chat_id is the root or another
  kind = 'chat' chat of the same owner and organisation. With the experiment off, or before the
  owner's tree has been materialised, parent_chat_id IS NULL (legacy top-level). root_chat_id IS NULL. Pinnable, shareable, auto-archive candidate individually (inactivity measured over its
  recursive subtree). Title generation unchanged. May spawn subagents; Children on the API is
  therefore no longer always empty for chats with a parent.
• kind = 'subagent': spawned by a root or chat chat. parent_chat_id = spawning chat,
  root_chat_id = spawning chat (unchanged today). Not pinnable, no own ACL (inherits the
  spawning chat's ACL through chats_expanded), excluded from the tree and from GET /chats.
  Cannot have named children (400 Subagent chats cannot have child chats) and cannot spawn
  subagents (unchanged). Schema: CHECK ((kind = 'subagent') = (root_chat_id IS NOT NULL)),
  CHECK (kind <> 'subagent' OR parent_chat_id IS NOT NULL),
  CHECK (kind <> 'root' OR (parent_chat_id IS NULL AND root_chat_id IS NULL)).

Tree shape:

• Depth: root = 1; a named chat's depth = parent depth + 1. Only root and chat rows count.
  Maximum depth 5, so a chat at depth 5 cannot get named children (400
  Chat tree depth limit exceeded, codersdk.ChatTreeMaxDepth = 5). Depth and child count are
  reported only for chats whose ancestor chain ends at a root row (tree response and single GET),
  only to the owner (a reader granted access through an ACL does not receive them), and omitted for
  legacy parentless chats and for subagents.
• Named children are created only under a root or chat parent owned by the same user in the
  same organisation, and only while the parent is not archived. Cross-owner, cross-organisation,
  unreadable, or non-existent parents all return the same 400 (no existence oracle). Shared (ACL)
  access to a parent does not permit creating children under it. An owner's parent whose ancestor
  chain does not end at a root returns a distinct 400 (Parent chat is not attached to a chat tree).
• Cycles are impossible by construction (no reparent API); a future move API must re-check depth
  of the moved subtree and ancestor loops, and must lock parent before child.
• An archived chat never has an unarchived descendant (named or subagent). Archiving a chat
  applies SetArchived(true) to the whole subtree; if any member is running, interrupting, or
  requires_action the request fails and nothing changes. Unarchiving a chat whose parent is
  archived fails (400). Unarchiving a chat unarchives it and its subagents only.
• Deleting a chat row (dbpurge only) deletes its subtree through the FK cascade; dbpurge never
  deletes a row whose subtree contains an unarchived chat.
• Lazy materialisation adopts only kind = 'chat' AND parent_chat_id IS NULL rows, including
  archived ones, changing nothing but parent_chat_id. It never touches subagents and never
  changes root_chat_id. Historical subagents orphaned by an earlier purge (parent NULL) are
  kind = 'chat' after the backfill and are adopted like any other top-level chat (they already
  appear in GET /chats today).

Capacity and worker pools: root and chat chats run in the top-level pool, subagent in the
subagent pool. Turn-status labels, push, summaries, plan-mode paths, and tool filtering treat
root and chat identically. AI Gateway attribution: HeaderCoderChatID is root_chat_id when
set, else the chat's own ID; HeaderCoderSubchatID is set only for subagents.

Subagent tools: wait_agent, message_agent, interrupt_agent accept only kind = 'subagent'
targets that are direct children of the calling chat (the ancestor walk stops at the first
non-subagent row); list_agents lists only kind = 'subagent' children. The lifecycle hook
ChatRef gains kind so consumers stop inferring "subagent" from parent_chat_id.

API sketch

Types (codersdk/chats.go):

type ChatKind string
const (
    ChatKindRoot     ChatKind = "root"
    ChatKindChat     ChatKind = "chat"
    ChatKindSubagent ChatKind = "subagent"
)
const ChatTreeMaxDepth = 5

// Added to codersdk.Chat (existing fields kept: ID, Title, Status, Archived, PinOrder, Labels,
// UpdatedAt, ParentChatID, RootChatID, Children, HasUnread, ...).
Kind ChatKind `json:"kind"`
// Depth and ChildChatCount are populated by GET /chats/{chat} and the tree response only, and
// only for root/chat rows anchored at a root. Omitted elsewhere.
Depth          *int `json:"depth,omitempty"`
ChildChatCount *int `json:"child_chat_count,omitempty"` // direct kind=chat children, any archived state

// CreateChatRequest gains:
ParentChatID *uuid.UUID `json:"parent_chat_id,omitempty" format:"uuid"`

type ChatTreeResponse struct {
    // Null when the root could not be created (no usable model config); Chats is then the
    // owner's parentless chats.
    RootChatID *uuid.UUID `json:"root_chat_id" format:"uuid"`
    // root and chat kind rows owned by the caller in the organisation, sorted by depth then
    // updated_at desc. Subagents excluded. No Children embedding. Not paginated; bounded by the
    // caller's unarchived chats unless archived=true.
    Chats []Chat `json:"chats"`
}

codersdk.Chat.RootChatID becomes root_chat_id from the database, else the chat's own ID
(the parent fallback is dropped; for existing subagents the value is unchanged). Children
keeps its current meaning: direct subagent children only (every GetChildChatsByParentIDs
call site passes kinds = [subagent]: exp_chats.go:516, :1533, subagent.go:1068).

Endpoints (registered in coderd/chat_routes.go, both /api/experimental and /api/v2
mounts, Swagger annotated once with @Router /api/v2/organizations/{organization}/chats/tree):

Internal functions (coderd/x/chatd):

• func (p *Server) EnsureChatTreeRoot(ctx, ownerID, orgID uuid.UUID) (database.Chat, bool, error)
• CreateOptions.ParentChatID validated in CreateChat via
  validateChatTreeParent(ctx, tx, ownerID, orgID, parentID) (depth int, err error); returns
  ErrChatTreeDepthExceeded, ErrChatTreeParentIsSubagent, ErrChatTreeParentArchived,
  ErrChatTreeParentMismatch (also used for unreadable and missing parents). The messaging
  project's tool and the HTTP handler both call CreateChat with ParentChatID.
• func (p *Server) ChatTreeParent(ctx, chat) (database.Chat, bool, error);
  GetChildChatsByParentIDs gains a kinds filter param.

New / changed queries (coderd/database/queries/chats.sql):

• GetChatTreeRootStateByOwnerAndOrganization, GetChatTreeByOwnerAndOrganization (recursive
  from the root, with depth and child_chat_count, archived filter, UNION of parentless
  kind = 'chat' rows for the root-unavailable case), AdoptParentlessChatsIntoTreeRoot :execrows,
  GetChatTreeDepthByID (recursive, bounded; 0 when the chain does not end at a root),
  InsertChat gains kind, GetChildChatsByParentIDs gains kinds.
• Recursive rewrite of GetChatFamilyIDsByRootID (renamed GetChatSubtreeIDs), auto-archive
  candidate and cascade queries, DeleteOldChats guard.
• kind replaces parent_chat_id IS NULL in the queries listed under "What the code does today";
  index expressions and query expressions use the identical form (kind = 'subagent').

Sequencing

PR 1 scott/chat-tree/1-chat-kind (behaviour-neutral):

1. Migration 000598_chat_kind:
   CREATE TYPE chat_kind AS ENUM ('root','chat','subagent');
   ALTER TABLE chats ADD COLUMN kind chat_kind NOT NULL DEFAULT 'chat';
   UPDATE chats SET kind = 'subagent' WHERE parent_chat_id IS NOT NULL;
   UPDATE chats SET root_chat_id = parent_chat_id WHERE parent_chat_id IS NOT NULL AND root_chat_id IS NULL;
   UPDATE chats SET root_chat_id = NULL WHERE parent_chat_id IS NULL AND root_chat_id IS NOT NULL;
   DROP VIEW chats_expanded; replace chat_acl_only_on_root_chats with
   kind <> 'subagent' OR (acl empty); replace chats_pin_order_parent_check with
   pin_order = 0 OR kind = 'chat'; add the three kind CHECKs; recreate
   idx_chats_auto_archive_candidates with kind = 'chat' and
   idx_chats_worker_acquisition_candidates with (kind = 'subagent'); recreate chats_expanded
   with c.kind in the column list and LEFT JOIN chats root ON root.id = c.root_chat_id;
   partial unique index chats_one_tree_root_per_owner_org.
   Down: UPDATE chats SET parent_chat_id = NULL WHERE kind = 'chat';
   DELETE FROM chats WHERE kind = 'root'; drop view, indexes, checks; drop column; recreate view;
   restore the old checks and indexes; drop type.
2. Queries: kind in InsertChat (explicit param); the 17 CTEs get the kind column and the
   join root.id = x.root_chat_id; kind gates in the eight queries above (acquisition row
   returns kind); telemetry has_parent -> kind = 'subagent'.
3. make gen; audit table: kind ActionTrack, parent_chat_id ActionTrack (mutable from
   PR 2 on).
4. Go sweep (complete list):
   database.Chat.IsSubChat() -> Kind == ChatKindSubagent (modelmethods.go:197);
   chatstate.CreateChatInput.Kind (transitions.go:29) and dbgen.Chat defaulting Kind
   from ParentChatID.Valid (dbgen.go:101);
   subagent.go:1226-1229 spawn sets Kind = subagent; subagent_catalog.go:264-272
validateSubagentSpawnParent; subagent.go:1065 list_agents guard; subagent.go:1685-1718
isSubagentDescendant stops at the first non-subagent row;
   chatd.go:1456 root fallback; chatd.go:2061-2096 archive guards; chatd.go:3447-3630
filterExternalMCPConfigsForTurn, toolAllowedForTurn, filterToolsForTurn,
   activeToolNamesForTurn, stopAfterPlanTools, stopAfterBehaviorTools take isSubagent bool
   (and mcp_tool_search.go:35,46,63); chatd.go:4454, :4707 label/summary skips;
   generation_preparer.go:172, :245, :418, :847; agentadmission.go:70; worker.go:211;
   chatstate/family.go:77; chatstate/errors.go:39 doc; chatprovider.go:644-660
CoderHeaders (chat id = root_chat_id else self; subchat only for subagents);
   auto_archive.go:203; chathooks/trigger.go:83 and codersdk/x/agenthooks/types.go:60
ChatRef.Kind; exp_chats.go postChats (:1394, remove the :1435-1441 guard),
   getChat:1531, getChatCost:1703-1706, patchChat:2317, :2390; exp_chats_acl.go:47,
   :108; dbauthz.go:7453; db2sdk.go:1895-1914 (Kind, RootChatID fallback),
   ChatRowsWithChildren. Completion criterion in D2.
5. codersdk.Chat.Kind; ChatKind type; Children doc comment; make gen for
   typesGenerated.ts. Frontend compatibility edits: AgentsPageLayout.tsx:134, :575,
   :614-621 use kind === "subagent"; chatTree.ts:40-43 comment.
6. Tests: migration test with a fixture (parentless chat, subagent, shared parentless chat,
   pinned chat) for backfill, CHECKs, and the down migration; dbauthz method tests for changed
   queries; testutil.Fake chat fixtures set Kind; sweep of the ~59 test sites that insert
   chats with RootChatID so they set Kind (or rely on the dbgen default); CoderHeaders
   test; existing chatd/coderd tests pass.

PR 2 scott/chat-tree/2-chat-tree:

1. Experiment ExperimentChatTree = "chat-tree" with display name and ExperimentsKnown.
2. Migration 000599_chat_tree_cascade: FKs ON DELETE CASCADE; index
   (owner_id, organization_id) WHERE kind = 'chat' AND parent_chat_id IS NULL for the adoption
   fast path. Down restores SET NULL and drops the index.
3. chatstate.CreateIdleChat and TODO markers in ARCHITECTURE.md: "Transitions used by the HTTP
   endpoints" (CreateIdle), "Execution state transition diagram" (N --> W: CreateIdle),
   PATCH /chats/{chat} (root rejects archive, recursive cascade over named descendants,
   unarchive guard for named children, unarchive does not cascade to named descendants),
   "Concurrent agent limiter" (top-level = kind IN (root, chat)), "Auto-archive loop" (root
   never selected, subtree inactivity), tool list near line 885 (subagent tools restricted to
   kind = subagent direct children).
4. Queries listed above, make gen, dbauthz entries and method tests.
5. EnsureChatTreeRoot, validateChatTreeParent (parent locked FOR UPDATE, archived
   rejected), CreateChat parent handling, cascade guards (root archive/pin/ACL rejection,
   parent-archived unarchive guard, unarchive limited to subagents), auto-archive subtree
   inactivity, DeleteOldChats guard, message_agent/wait_agent/interrupt_agent direct
   subagent child requirement.
6. HTTP: tree route (api.Experiments.Enabled, audit root creation), postChats parent handling,
   patchChat changes, getChat/db2sdk depth/child_chat_count, codersdk.Client.ChatTree,
   Swagger, make gen.
7. Tests (all t.Parallel, unique owners/orgs, no sleeps):
   • EnsureChatTreeRoot: idempotent; N goroutines racing produce one root; adopts archived,
     pinned, and shared parentless chats without changing updated_at; leaves subagents and other
     owners/orgs untouched; no model config -> ErrChatTreeRootUnavailable; no watch event.
   • CreateChat with parent: depth 5 accepted, depth 6 rejected; subagent parent rejected;
     archived parent rejected; other owner / other org / missing parent return the same 400;
     experiment off rejects parent_chat_id.
   • Archive cascade over named descendants and subagents; running descendant fails atomically;
     root archive 400; root pin 400; root ACL patch 400; unarchive child under archived parent
     400; unarchive parent leaves independently archived named child archived.
   • Auto-archive: root never selected; parent with an active named child not selected; inactive
     subtree archived as a whole. dbpurge: archived parent with unarchived child (constructed
     directly) is skipped; archived subtree purged together.
   • Named child can spawn a subagent; subagent's root_chat_id is the named child; capacity
     pool classification by kind (existing capacity tests extended); message_agent from the root
     to a grandchild subagent rejected.
   • ACL on a named child is independent of the root (share child, root unshared, and vice versa).
   • GET /chats excludes root and subagents and Children holds subagents only; GET tree
     returns depth, counts, and honours archived; experiment off -> 404 and no root row.

Checks before handoff: make gen, make fmt, make lint, targeted go test for
coderd/database/... (migrations, dbauthz), coderd/x/chatd/..., coderd chat tests,
site typecheck for the compatibility edits.

Testing approach

Real Postgres via dbtestutil.NewDB. chatd tests through chattest helpers and coderdtest for
HTTP. Race test (make test-race) on the EnsureChatTreeRoot concurrency test.

What the later projects must do

chat-tree-messaging:

• Add send_chat_message on top of Server.SendMessage with SendMessageBusyBehavior
  (queue | interrupt), resolving targets via ChatTreeParent and
  GetChildChatsByParentIDs(kinds = [chat]). Restrict to the immediate parent and direct named
  children unless the orchestrator decides otherwise.
• Decide whether a message from a child to a parent that is kind = root is allowed (the root is
  a real chat and can run turns; this plan allows it).
• Do not reuse message_agent/wait_agent/interrupt_agent for named children; this layer
  restricts them to direct subagent children.
• Audit, hooks (user_prompt_submit admission), and spend attribution use the receiving chat's
  owner, same as today.

chat-tree-ui:

• Build the tree from GET /organizations/{organization}/chats/tree using parent_chat_id,
  kind, depth, child_chat_count; treat root_chat_id: null as a flat list. Archived
  subtrees come from the same endpoint with archived=true; children of very large nodes may
  eventually need a paginated parent:<uuid> search filter, which this layer does not add.
• Stop inferring "subagent" from parent_chat_id anywhere; use kind. Watch events carry kind.
• Shared-with-me chats are not in the tree response; keep them in a separate section from
  GET /chats?source=shared_with_me.
• Subagents remain in Chat.Children of their parent (one level), not in the tree response.
• Root cannot be archived, pinned, or shared; hide those actions. Root has a stable title Root
  until the user renames it.
• Move/reparent needs a new endpoint (not in this layer); the invariants above define what it
  must re-check.

Decisions and constraints (orchestrator, step 3)

1. D1 variant accepted. parent_chat_id carries the tree edge; root_chat_id keeps its existing
   meaning (nearest non-subagent ancestor of a subagent, NULL on root and named chats); the tree
   root is located by (owner_id, organization_id, kind = 'root'). Reasoning recorded in the
   Invariants section: root_chat_id drives archive, auto-archive, cost, and ACL family
   operations, which must stay scoped to "a chat plus its subagents"; the messaging and UI
   projects must not treat root_chat_id as the tree root.
2. FK ON DELETE CASCADE purging the subtree with the parent's retention age is accepted, given
   the dbpurge guard that skips rows with unarchived descendants.
3. PR 1 makes the three minimal kind edits in AgentsPageLayout.tsx (discriminator swaps only);
   the UI project owns everything else.
4. Defaults accepted: root title Root (UI may relabel), EnsureChatTreeRoot from the tree GET
   and POST /chats only, unarchive does not resurrect independently archived descendants.
5. All REVIEW-plan.md dispositions stand as recorded.
6. Amendment to decision 3 (human, via orchestrator): an eager migration is acceptable if it is fast on
   large deployments. Assessed and rejected; lazy materialisation stays the primary path.
   • Candidate migration (set-based): INSERT INTO chats (owner_id, organization_id, kind, title, status, last_model_config_id, client_type) SELECT DISTINCT ON (owner_id, organization_id) ... FROM chats WHERE kind = 'chat' AND parent_chat_id IS NULL AND NOT EXISTS (root) picking the
     newest chat's last_model_config_id, then UPDATE chats c SET parent_chat_id = r.id FROM chats r WHERE r.kind = 'root' AND same owner/org AND c.kind = 'chat' AND c.parent_chat_id IS NULL.
     Indexes needed: chats_one_tree_root_per_owner_org (already added) for the anti-join and the
     UPDATE ... FROM join; no new index.
   • Measured on the current schema (14 indexes on chats) with 500k parentless chats, 50k subagents,
     20k owners in one organisation: INSERT 0.66 s (20k roots), UPDATE 9.5 s (500k rows), 10.2 s total
     in one transaction; roughly linear (1M chats about 20 s). Lock scope: row locks on every
     reparented chat and the unique index for the transaction duration; in a rolling upgrade, old
     replicas' chat status and heartbeat writes block for that window. parent_chat_id is indexed, so
     the UPDATE rewrites every row (no HOT updates) and roughly doubles the chats heap until vacuum.
     The only trigger on chats fires on retry-state columns and is not involved.
   • Fast enough, but it does not simplify the code and it changes experiment-off behaviour:
     (a) with the experiment off, POST /chats still creates parentless chats (attaching them to the
     root would move parent assignment outside the experiment), so adoption on read is still needed
     when the experiment is later turned on; the eager step only front-loads one batch; (b) every
     existing chat gains a visible parent_chat_id and a kind = 'root' row exists for every user
     while the experiment is off, which decision 7 excludes and which forces the remaining legacy
     frontend inferences (REVIEW-diff Package v2 UI into coderd with go embed #22) to be fixed in PR 1; (c) a migration cannot seed the
     deployment system prompt (site config resolved in Go), so eager roots would need a lazy
     first-message seeding path that lazy CreateIdleChat avoids; (d) the migration must guess a
     model config (newest chat's, possibly disabled or deleted), whereas the lazy path resolves the
     org default like POST /chats.
   • Choice: stay lazy. EnsureChatTreeRoot remains the single path for root creation and adoption;
     the measured migration is recorded here in case a later project wants to pre-materialise trees
     once the experiment is on by default.

Open questions (resolved at step 3, kept for the record)

1. D1 variant (root_chat_id keeps the subagent-family meaning) versus the literal decision 1.
2. ON DELETE CASCADE also applies to subagents of purged chats and purges a subtree by the
   parent's retention age. Acceptable?
3. GET /chats stays flat (kind = 'chat', named children included) so the legacy sidebar keeps
   listing every user chat; the four frontend compatibility edits are the minimum for it not to
   misrender. Alternatively accept degradation and make no frontend edits.
4. Root title constant Root versus leaving it to the UI (title still stored).
5. EnsureChatTreeRoot is triggered from the tree route and POST /chats only, not from
   GET /chats.
6. Unarchive of a parent does not resurrect independently archived named descendants (chosen);
   confirm.