chatv3.go

package main

import (
	"context"
	"errors"
	"fmt"
	"io"
	"os"
	"path/filepath"
	"strconv"
	"strings"
	"sync"
	"sync/atomic"
	"time"

	"github.com/Agent-Field/codeaf/internal/approval"
	"github.com/Agent-Field/codeaf/internal/buildinfo"
	"github.com/Agent-Field/codeaf/internal/catalog"
	"github.com/Agent-Field/codeaf/internal/cell"
	"github.com/Agent-Field/codeaf/internal/codexauth"
	"github.com/Agent-Field/codeaf/internal/config"
	"github.com/Agent-Field/codeaf/internal/connect"
	"github.com/Agent-Field/codeaf/internal/crewroute"
	"github.com/Agent-Field/codeaf/internal/effort"
	"github.com/Agent-Field/codeaf/internal/enginehost"
	"github.com/Agent-Field/codeaf/internal/env"
	"github.com/Agent-Field/codeaf/internal/gitidentity"
	"github.com/Agent-Field/codeaf/internal/guard"
	"github.com/Agent-Field/codeaf/internal/handoff"
	"github.com/Agent-Field/codeaf/internal/home"
	"github.com/Agent-Field/codeaf/internal/leave"
	"github.com/Agent-Field/codeaf/internal/modelsource"
	"github.com/Agent-Field/codeaf/internal/openrouterauth"
	"github.com/Agent-Field/codeaf/internal/resident"
	"github.com/Agent-Field/codeaf/internal/roles"
	"github.com/Agent-Field/codeaf/internal/search"
	"github.com/Agent-Field/codeaf/internal/session"
	"github.com/Agent-Field/codeaf/internal/store"
	"github.com/Agent-Field/codeaf/internal/subharness"
	"github.com/Agent-Field/codeaf/internal/syncsetup"
	"github.com/Agent-Field/codeaf/internal/trace"
	"github.com/Agent-Field/codeaf/internal/tui3"
	codeupdate "github.com/Agent-Field/codeaf/internal/update"
)

// runChatV3 is the v3 door: one session agent over this directory, and the
// linear surface that shows it. It claims no residency and starts no runner;
// the ONE thing it opens of the graph database is the person's memories
// (milestone V3-1, [v3Memory]), because those are the only rows in it a
// conversation has any business reading.
func runChatV3(args []string) error { return openChatV3("chat", args, false) }

// runResumeV3 is `codeaf resume`: the same door, opened on the session picker.
//
// It is one word rather than a flag on chat because it is what a person is
// doing when they type it — coming back to a conversation, not starting one —
// and it takes chat's flags for the same reason: the session it opens is a chat
// session, and a model or a reasoning level named on the way in is named about
// that.
//
// IT DOES NOT RESUME ANYTHING BY ITSELF. The surface opens exactly as `codeaf`
// bare does, on this directory's most recent conversation, with the picker over
// it — so esc lands where the person would have been anyway, and enter lands
// where they asked to be. A launcher that opened on an empty session instead
// would make "resume" the one command that can leave you with nothing.
func runResumeV3(args []string) error { return openChatV3("resume", args, true) }

// v3OpenRouterConnection is the default provider's browser door. Comparing the
// resolved endpoint, rather than merely looking for CODEAF_BASE_URL, also does
// the right thing for a caller that explicitly names the built-in address and
// for one that carries a harmless trailing slash.
func v3OpenRouterConnection(settings config.Config, interactive bool) func(context.Context) (tui3.OpenRouterFlow, error) {
	if !interactive || !v3UsesDefaultOpenRouter(settings) {
		return nil
	}
	return func(ctx context.Context) (tui3.OpenRouterFlow, error) {
		return openrouterauth.Begin(ctx, openrouterauth.Options{})
	}
}

// v3CodexConnection is the local browser door for the Codex model-service row.
// A hosted surface gets no seam because its profile and callback listener live
// on different machines; /connect already says how to sign in on that machine.
func v3CodexConnection(interactive bool) func(context.Context) (tui3.CodexFlow, error) {
	if !interactive {
		return nil
	}
	return func(ctx context.Context) (tui3.CodexFlow, error) {
		return codexauth.Begin(ctx, codexauth.Options{})
	}
}

func openChatV3(name string, args []string, pickSession bool) error {
	restart := &codeupdate.Plan{}
	flags := commandFlags(name)
	model := flags.String("model", "", "model slug for this session; beats the configured default")
	once := flags.String("once", "", "run one message non-interactively, print the reply, and exit")
	file := flags.String("session", "", "session transcript to resume; empty resumes this directory's most recent")
	noCompact := flags.Bool("no-compact", false, "never compact automatically")
	yolo := flags.Bool("yolo", false, "run every tool without asking: the approval default becomes allow")
	reasoning := flags.String("reasoning", "", "reasoning override: auto (inherit), low, medium, high, xhigh or max; off is an alias for auto")
	host := flags.String("host", "", "run the session on another machine over ssh: host, user@host, or host:path/to/project")
	at := flags.String("at", "", "reach a machine that has no ssh, by the name `codeaf serve` prints there: otter-lamp-42, or otter-lamp-42:path/to/project")
	// --no-host is the escape hatch off the local dial, and it means here
	// exactly what it means on `codeaf engine`: open this conversation in this
	// process and never look for a session host. It exists because a fallback
	// nobody can ask for is a fallback nobody can use on the day the host
	// itself is the thing that is wrong.
	noHost := flags.Bool("no-host", false, "open this conversation in this process instead of attaching to this workspace's session host")
	oneModel := flags.Bool("one-model", false,
		"every text call this session makes runs on the session model: the tier rows, the role pins, "+
			"the fallback chain and the task model all stand down")
	// THE TWO CEILINGS AN UNATTENDED SESSION MAY BE GIVEN, and they are floats
	// rather than durations because a person types `--max-hours 6` and
	// `--max-hours 0.5`, not `6h0m0s`. Either alone is a budget; neither is the
	// posture this build has always had. They mean nothing without --yolo, and
	// the check below says so rather than letting a flag do nothing in silence.
	maxHours := flags.Float64("max-hours", envFloat("CODEAF_MAX_HOURS"),
		"how many hours an unattended --yolo session may carry its own work on; the window closes itself "+
			strconv.Itoa(int(launchWallGrace/time.Minute))+" minutes after (env CODEAF_MAX_HOURS)")
	maxCost := flags.Float64("max-cost", envFloat("CODEAF_MAX_COST"),
		"how many dollars an unattended --yolo session may carry its own work on (env CODEAF_MAX_COST)")
	debug := flags.Bool("debug", false,
		debugFlagHelp()+" · /debug turns it on mid-session")
	// The three live flags of a headless turn (chat_once_live.go).
	onceEvents := flags.String("events", "", "with --once: copy every line of this conversation's record to this file as it is written")
	onceSteer := flags.String("steer", "", "with --once: read each line appended to this file as a note into the running turn")
	onceJSON := flags.Bool("json", false, "with --once: print one machine-readable object {ok, stop, answer, model, error} instead of the reply")
	if err := parseCommandFlags(flags, reorder(flags, args)); err != nil {
		return err
	}
	if (*onceEvents != "" || *onceSteer != "" || *onceJSON) && strings.TrimSpace(*once) == "" {
		return fmt.Errorf("--events, --steer and --json go with --once")
	}
	chatOnceLive = onceLive{events: *onceEvents, steer: *onceSteer, json: *onceJSON}
	// THE RECORD'S SWITCH IS READ HERE AND THE RUN ID IS MINTED HERE, at the
	// door, before anything can make a call — because a record written under a
	// second id, or under none, is a record nothing can be joined to. The id is
	// minted whether or not the switch is on: /debug can turn the record on
	// halfway through a conversation, and it needs a run to turn it on for.
	//
	// THE RECORD ITSELF OPENS AFTER THE LAUNCH'S OWN UPDATE below. That road
	// can hand the terminal to another build, and a record opened first would
	// be one that run never writes to. Nothing between here and there makes a
	// model call.
	if *debug {
		trace.Enable()
	}
	if flags.NArg() != 0 {
		// Resume's usage names no --once and no --session: it opens a list of
		// the sessions there ARE, so naming one on the command line is the other
		// door, and nobody is watching a headless one.
		if pickSession {
			return fmt.Errorf(`usage: codeaf resume [--model slug] [--reasoning level] [--host host[:path]] [--at name[:path]] [--no-host] [--no-compact] [--yolo [--max-hours n] [--max-cost n]] [--one-model] [--debug]`)
		}
		return fmt.Errorf(`usage: codeaf chat [--model slug] [--reasoning level] [--session path] [--host host[:path]] [--at name[:path]] [--no-host] [--once "text"] [--no-compact] [--yolo [--max-hours n] [--max-cost n]] [--one-model] [--debug]`)
	}
	// --one-model is about THIS machine's settings rows, and over --host the
	// rows that answer are the far machine's (chatv3_host.go). A flag that
	// looked like it applied and did not would be worse than one that is not
	// there, so the combination is refused rather than quietly dropped.
	if *oneModel && strings.TrimSpace(*host) != "" {
		return fmt.Errorf("--one-model settles this machine's model rows; over --host the far machine answers them, so the two cannot be combined")
	}
	// --at is the same fork as --host and differs only in what carries it, so
	// it inherits --host's refusal word for word: the rows that answer are
	// still the other machine's.
	if *oneModel && strings.TrimSpace(*at) != "" {
		return fmt.Errorf("--one-model settles this machine's model rows; over --at the far machine answers them, so the two cannot be combined")
	}
	// --no-host is about the session host on THIS machine, and over --host or
	// --at the conversation is on the far machine either way — there is no
	// local host in the picture for the flag to refuse. Accepting it and doing
	// nothing is the shrug this tree does not do, so the pair is named.
	if *noHost && strings.TrimSpace(*host) != "" {
		return fmt.Errorf("--no-host keeps a conversation in this process; over --host the conversation is on the far machine, so the two cannot be combined — `ssh %s codeaf engine --no-host` is where that setting lives", strings.TrimSpace(*host))
	}
	if *noHost && strings.TrimSpace(*at) != "" {
		return fmt.Errorf("--no-host keeps a conversation in this process; over --at the conversation is on the far machine, so the two cannot be combined")
	}
	// TWO WAYS TO REACH ONE MACHINE IS NOT TWO MACHINES. Naming both is a
	// person saying two different things about where the work is, and guessing
	// which they meant would open a conversation on a machine they did not
	// name.
	if strings.TrimSpace(*host) != "" && strings.TrimSpace(*at) != "" {
		return fmt.Errorf("--host reaches a machine over ssh and --at reaches one through the sync service: name one or the other, not both")
	}

	// A BUDGET IS A SENTENCE ABOUT AN UNATTENDED SESSION, so it is refused
	// rather than ignored on a session somebody is sitting in front of. What it
	// buys — a goal owner that carries the work on by itself (internal/session's
	// principal.go) — is the thing --yolo alone must never be read as permission
	// for, and a ceiling on a session that was never going to carry anything on
	// is a number that quietly did nothing.
	//
	// IT IS ASKED OF A LOCAL LAUNCH ONLY. Over --host and over --at the ceiling
	// cannot travel at all and each door says so in its own words
	// (chatv3_host.go's and chatv3_at.go's checks); two refusals for one flag
	// would send somebody to add --yolo and straight into the second one.
	if budget := chatBudget(*maxHours, *maxCost); budget.Set() && !*yolo && strings.TrimSpace(*host) == "" && strings.TrimSpace(*at) == "" {
		return fmt.Errorf("--max-hours and --max-cost bound a session that carries its own work on; say --yolo as well, or leave them off")
	}
	// A picker with nobody watching is not a picker. --once is the headless
	// door, and the two are a contradiction rather than a combination, so it is
	// said here — before a session file is opened — instead of being ignored.
	if pickSession && strings.TrimSpace(*once) != "" {
		return fmt.Errorf(`codeaf resume opens the session picker; for one headless message use: codeaf chat --once "text"`)
	}
	// --max-hours ENDS THE PROCESS, a grace after the wall (chatwall.go). The
	// session's own reader stops its work AT the wall; this is what closes the
	// window afterwards, because a window nobody is watching was found alive
	// forty hours past a nine-minute cap.
	if wall := chatBudget(*maxHours, *maxCost).Wall; wall > 0 && *yolo {
		defer armLaunchWall(wall, time.AfterFunc, leaveThisProcess)()
	}
	// The level is validated HERE, before anything is opened, so a typo is a
	// usage error and not a knob that silently did nothing for a whole session.
	// It is a one-shot: ctrl+t in the picker overrides it from that moment on,
	// and /new — a new agent — starts with no level at all.
	level, ok := session.ParseReasoning(*reasoning)
	if !ok {
		return fmt.Errorf("--reasoning %q: use auto, low, medium, high, xhigh or max (off also clears the override)", *reasoning)
	}
	// THE LAUNCH'S OWN UPDATE, after every refusal above and before any door
	// forks: a released codeaf installs the newest stable and restarts onto it
	// here, before a frame is drawn, and every other launch is told what is out
	// on one terminal line (prelaunch.go). It is the same for all four doors
	// because the file being replaced is this machine's whichever one opens.
	// --once is a script, not a person, and is never restarted under it.
	if strings.TrimSpace(*once) == "" {
		updateBeforeLaunch()
	}
	ctx := openDebugRecord(name, *model, "")
	defer trace.Announce(ctx, os.Stderr)

	// THE OTHER DOOR, and it forks BEFORE any of this machine's own resolution
	// below: over --host the models, the keys, the session files, the gate and
	// the harnesses are all the far machine's, and reading this one's would be
	// resolving a launch nobody asked for (chatv3_host.go).
	if dest := strings.TrimSpace(*host); dest != "" {
		err := openChatV3Host(hostLaunch{
			target:    dest,
			session:   strings.TrimSpace(*file),
			model:     strings.TrimSpace(*model),
			level:     level,
			once:      strings.TrimSpace(*once),
			pick:      pickSession,
			noCompact: *noCompact,
			yolo:      *yolo,
			budget:    chatBudget(*maxHours, *maxCost).Set(),
			restart:   restart,
		})
		return finishChatRestart(err, restart, "")
	}

	// THE THIRD DOOR, and it forks here for the reason --host does: a machine
	// reached by its paired name owns exactly what a machine reached over ssh
	// owns. The two differ only in what carries the frames — an ssh child there,
	// a relay tunnel here — which is the whole point of the transport being an
	// io.ReadWriteCloser and nothing more (chatv3_at.go, docs/REMOTE.md).
	if name := strings.TrimSpace(*at); name != "" {
		err := openChatV3At(atLaunch{
			target:    name,
			session:   strings.TrimSpace(*file),
			model:     strings.TrimSpace(*model),
			level:     level,
			once:      strings.TrimSpace(*once),
			pick:      pickSession,
			noCompact: *noCompact,
			yolo:      *yolo,
			budget:    chatBudget(*maxHours, *maxCost).Set(),
			restart:   restart,
		})
		return finishChatRestart(err, restart, "")
	}

	// The fourth door, and the only one with no machine in it: this workspace's
	// own session host, on a unix socket. It is the ordinary road for an
	// interactive launch — the work outlives this terminal and the next window
	// here joins the same conversation — and [v3HostRoad] names the launches
	// that keep the in-process door instead.
	//
	// It forks HERE, beside the other two, and for their reason: the launch
	// below assembles this machine's models, keys, gate and session files, and
	// the process on the other end of that socket has already assembled its own.
	//
	// The per-launch postures travel with it. --yolo and its neighbours are how
	// the session is BUILT, so they ride the hello and the engine builds with
	// them; a conversation that is ALREADY open keeps the shape it was opened
	// with, and this launch is told so and comes back here rather than running
	// under a posture nobody asked for.
	//
	// entryNotice is that sentence, or the reason no host could be used. Either
	// way it is shown on the surface's own notice line below rather than printed
	// into a terminal the surface is about to take over.
	entryNotice := ""
	if workspace, take := v3HostRoad(v3HostChoice{
		noHost: *noHost,
		once:   strings.TrimSpace(*once) != "",
		// THE SWITCH AND NOT THE FLAG. --debug has already turned the record on
		// above, and so has CODEAF_DEBUG in the shell that started this process
		// (internal/trace's init) — both are this process being told to record,
		// and both must keep the calls in this process to have anything to
		// record ([v3HostChoice.debug]).
		debug: trace.Enabled(),
		setup: !v3MachineIsSetUp(),
	}); take {
		err := openChatV3Local(localLaunch{
			workspace: workspace,
			session:   strings.TrimSpace(*file),
			model:     strings.TrimSpace(*model),
			level:     level,
			once:      strings.TrimSpace(*once),
			pick:      pickSession,
			shape:     v3LaunchShape(*yolo, *noCompact, *oneModel, *maxHours, *maxCost, strings.TrimSpace(*once) == ""),
			restart:   restart,
		})
		var taken *hostShapeTaken
		var unreachable *hostUnreachable
		switch {
		case errors.As(err, &taken):
			entryNotice = taken.sentence
		case errors.As(err, &unreachable):
			entryNotice = "this conversation opened in this terminal instead, and ends with it: " + unreachable.reason
		default:
			return finishChatRestart(err, restart, workspace)
		}
	}

	// Everything both v3 doors assemble the same way: the settings, the model
	// catalog, the harness registry, the session file, and the config every
	// governance row has landed on. `codeaf engine` opens a conversation for a
	// surface on another machine and opens it THROUGH HERE (engine.go), so a
	// remote session is the same launch this one is rather than a second one
	// drifting quietly away from it.
	//
	// The process half is built first and exactly once (chatv3_process.go): the
	// profile, the catalog, the harness registry, the memory database, the
	// deliverables index and the accounts manager are things this PROCESS owns,
	// and a launch borrows them rather than opening a second of each.
	// WHETHER THIS LAUNCH MAY SET ITSELF UP. It is a person at a terminal with
	// no particular conversation in mind — a TTY on stdin, no --once (which
	// returned above, but the flag is the honest test), no --session and no
	// picker — and it is the one launch that may open with no key and ask for
	// one on screen (internal/tui3's firstrun.go). A named or picked conversation
	// may connect too — it cannot talk without the same key — while --once still
	// meets the refusal at the door. --host forked above and never reaches here;
	// the far machine's key is the far machine's business.
	interactive := stdinIsTerminal(os.Stdin) && strings.TrimSpace(*once) == ""
	setup := interactive && strings.TrimSpace(*file) == "" && !pickSession
	proc, err := openV3ProcessWith("chat", interactive)
	if err != nil {
		return err
	}
	seed := v3Options{
		Model: *model,
		// A TERMINAL DOOR IS STEERED unless --once is it: --once is the
		// headless fork below. The seed carries the fact into the boot
		// launch, the seam's /new and /resume, and the hosted shape.
		Interactive: strings.TrimSpace(*once) == "",
		NoCompact:   *noCompact,
		Yolo:        *yolo,
		OneModel:    *oneModel,
		Budget:      chatBudget(*maxHours, *maxCost),
	}
	boot := seed
	boot.Session = *file
	launch, err := openV3Launch(proc, boot)
	if err != nil {
		return err
	}
	settings, harnesses := launch.Settings, launch.Harnesses
	workspace, transcript, resumed := launch.Workspace, launch.SessionFile, launch.Resumed
	chosen, cfg := launch.Model, launch.Config

	if text := strings.TrimSpace(*once); text != "" {
		// Nobody is watching a --once run, so nobody can answer a question. The
		// policy's "prompt" therefore refuses the call with a result the model
		// can act on (internal/session's consent.go), and a person who wants
		// that work to run says so with --yolo. NON-INTERACTIVE WORK NEEDS AN
		// EXPLICIT POSTURE: the two honest answers are "refuse what you would
		// have asked about" and "I have said in advance that this may run", and
		// neither of them is a gate that quietly opens because the terminal
		// happens to be a pipe.
		cfg.AskConsent = false
		// AND ITS COMMANDS ARE FENCED to the folder it runs in (fence.go):
		// nobody watches them, so the jail holds what a person would have.
		fence, err := unattendedFence(workspace, settings.ProfileDir)
		if err != nil {
			return err
		}
		cfg.Fence = fence
		// AND NOTHING MAY BE SET UP HERE. An automation spends money at times
		// nobody chose, so it needs a yes; a headless run has nobody to give
		// one, and a clock that armed it anyway would be the harness agreeing on
		// somebody's behalf. The tool is simply absent (internal/session's
		// tools.go), which is the same law --once already applies to consent.
		cfg.Automations = nil
		// AND THE SUBHARNESS SEAMS ARE LEFT ALONE, which is not an oversight
		// beside the line above it. Automations have to be taken away here
		// because nothing else asks whether anybody is watching before it arms a
		// clock. A
		// subharness cannot start without somebody confirming an intake card, and
		// internal/session already reads that in one place — its own gate is
		// `AskConsent && there is something to offer` (tools_subharness.go), and
		// the line above has already answered the first half. Nilling the registry
		// too would be a second copy of a decision that is made correctly one
		// layer down, and it would take the `/subharness` list away from a door
		// that may yet grow one.
		return runChatV3Once(ctx, cfg, launch.Project, text, level, resumed)
	}
	// Interactive: there is a surface, and it answers (internal/tui3's
	// consent.go). This is the ONLY path that sets it.
	cfg.AskConsent = true
	// AND THAT SURFACE HOLDS EVERY STANDING LANE, which is a second fact and not
	// the same one: a design card, a subharness intake card and an adaptive
	// run's fuel gate each arrive on a subscription opened on the agent itself
	// (internal/tui3's watchDesigns and watchRuns), and here the surface and the
	// session are one process, so all three reach a person by construction. The
	// three are set together, in the one place that decides them for every door
	// (chatv3_lanes.go), so this launch and a hosted one differ in what the road
	// carries rather than in what two files remembered to say.
	cfg, open := v3Shape(cfg, v3LanesHere())

	agent, cfg, notice, err := openV3Agent(cfg, launch.Project, open)
	// LAUNCH-ON-LOCK. The conversation this terminal asked for is open in
	// another window, and this door has a screen — so it offers that
	// conversation rather than refusing or, as it once did, quietly handing over
	// a different one. A fresh conversation is opened beside it and its
	// transcript path travels to the surface, which comes up on home with that
	// row pointed and ARMED: one enter moves the real one here, esc gets on with
	// the new one (internal/tui3's takeover.go).
	takeOver := ""
	var held *sessionHeldElsewhere
	if errors.As(err, &held) {
		takeOver = held.transcript
		agent, cfg, err = v3TakeOverInstead(cfg, workspace)
		// The session file moved, so everything downstream that names it names
		// the new one — the same correction the notice below makes.
		transcript, resumed = cfg.SessionFile, false
	}
	if err != nil {
		return err
	}
	// AND NOW THE BELT EXISTS, so a program's tool guard can be answered. Until
	// this line every such guard answers no and the work takes the long way,
	// which is the safe direction and not the useful one ([beltWatch] states the
	// ordering problem this closes).
	launch.Subharnesses.Belt.watch(agent.ToolOnBelt)
	if cfg.SessionFile != launch.SessionFile {
		// The session file moved under us, so everything downstream that names
		// it — /help, /new, the resumed line — has to name the new one.
		transcript, resumed = cfg.SessionFile, false
	}
	// The boot override lands on the model this session starts on, which is the
	// only model it can be about: --reasoning names a strength, not a model, and
	// the level is kept per model from here on (internal/session's agent.go).
	agent.SetReasoning(level)
	proc.track(agent)
	// EVERY CONVERSATION THIS PROCESS OPENED, CLOSED HOWEVER THE SURFACE RETURNS.
	// Close is the surface's to call — /quit and ctrl+c both go through it — but
	// a Run that returns by any other road must still flush the files, release
	// the session flocks and stop the presence heartbeats, and after this wave
	// there is more than one of each. The defer that used to stand here owned
	// exactly the boot agent, and the store's close was registered before it so
	// that it ran after; [v3Process.closeAll] holds both halves of that ordering
	// itself and is a no-op the second time it is called.
	defer proc.closeAll()

	proc.warmModels("chatv3/models", agent, chosen)

	// The two things this surface keeps on the person's behalf rather than the
	// session's: what they have typed before, and what they have half-typed
	// now. Both are settings (internal/config), both are off by one row, and
	// neither is ever waited for — a history file that cannot be opened costs
	// the up arrow and nothing else.
	//
	// They read through the project layer like every other row: a repository
	// that says "record nothing from this directory" is answering about ITS
	// directory, which is the whole reason the layer is per-workspace. The
	// broken-file error cannot actually arrive here — governance above read the
	// same file and would have stopped the launch — and it is still returned
	// rather than swallowed, because the only wrong thing to do with an
	// unreadable settings file is carry on as though it said nothing.
	keepHistory, err := config.ProjectBoolAt(workspace, settings.ProfileDir, config.KeyHistoryEnabled)
	if err != nil {
		return err
	}
	keepDraft, err := config.ProjectBoolAt(workspace, settings.ProfileDir, config.KeyDraftPersist)
	if err != nil {
		return err
	}
	var recall tui3.History
	if keepHistory {
		// One file per process, opened on the first workspace that wants it and
		// closed by [v3Process.closeAll] (chatv3_process.go). The rows carry the
		// directory they were typed in, so the surface asks for its own.
		recall = proc.history()
	}
	draft := ""
	if keepDraft {
		if dir, err := v3Dir(); err == nil {
			draft = tui3.ChatDraftFile(dir, "", workspace, cfg.SessionFile)
		}
	}
	// THE AGENT-BUILDING SEAM (chatv3_process.go's [v3Seam]). Every conversation
	// after the first comes through here, carrying the closures that belong to
	// ITS agent and ITS workspace — which is what stops an "always" answered
	// after a /new from being pushed into the session that /new closed.
	//
	// It carries the boot launch AS IT ENDED UP rather than as it was assembled:
	// [openV3Agent] may have moved the session file under us on a contended
	// resume, and a conversation opened later is a sibling of the folder this
	// window is actually in.
	settled := *launch
	settled.Config, settled.Place = cfg, cfg.Place
	settled.SessionFile, settled.Resumed = transcript, resumed
	seam := &v3Seam{proc: proc, boot: &settled, seed: seed}

	// THIS IS A WINDOW ON THIS MACHINE, and its automations run only while one
	// is open: it holds its presence for exactly as long as the surface runs,
	// and keeps a clock going meanwhile (chatv3_clock.go). The two doors to
	// another machine hold presence THERE instead, through the engine they
	// attach to, because the automations such a window shows are that
	// machine's.
	defer keepAutomationsWindow("window")()
	// The byte meter and the logger redirect both belong to the surface rather
	// than to this door, and [runSurface] (chatv3_surface.go) is where every
	// door gets them.
	err = runSurface(ctx, tui3.Options{
		Agent:             agent,
		Build:             buildinfo.String(),
		Seal:              sealSeamOf(agent, cfg.Seals),
		UnreadProfileKeys: append([]string(nil), proc.UnreadProfileKeys...),
		// The memory place reads the conversation's store; a store that would not
		// open supplies no seam.
		Memory:       v3MemorySeam(cfg.Memory),
		SearchStatus: v3SearchStatus(cfg.SearchProvider, settings.ProfileDir),
		// The machine-wide spending ledger the spend place adds up. It is the
		// same file every window on this machine appends a model call to, named
		// once by internal/session so a reader and a writer cannot spell it two
		// ways (internal/session's UsageLedgerPath).
		UsageLedger: session.UsageLedgerPath(),
		// The sub-harness registry under the state root, which is where every
		// window on this machine writes and reads them: /harness is a list of
		// what is SAVED, so it has to be the same directory the builder saved
		// into (internal/subharness's store.go).
		Harnesses: harnesses,
		// Asked at the moment the picker opens, never at boot: a catalog that
		// resolved while the person was reading is a catalog the picker can
		// use, and one that has not resolved answers nil instead of waiting.
		// It reads the shelf, which ctrl+r in /model refills with today's list.
		Models:                  proc.Shelf.pickerModels,
		RequireListedModel:      true,
		RefreshModels:           proc.refreshDefaultModels,
		ModelsForService:        proc.Shelf.modelsForService,
		RefreshModelsForService: proc.Shelf.refreshService,
		RefreshAllModels:        proc.refreshAllModels,
		WarmEmptyProviders:      proc.warmEmptyProviders,
		SubscribeServiceModels:  proc.registerServiceNotice,
		ProviderFetchError:      proc.Shelf.fetchErrorFor,
		Sources:                 settings.Sources,
		// The same deliverables index the session's config carries, so the
		// surface's /export rows and the session's own land in one file.
		ArtifactsIndex: artifactsIndexPath(),
		// The profile the settings panel reads and writes, which must be the
		// SAME directory this launch read every governance row out of. It was
		// missing here while the --host door supplied it (chatv3_host.go), and
		// the gap was invisible in the ordinary case and silent in the one that
		// mattered: with CODEAF_PROFILE_DIR set, the panel wrote into
		// ~/.codeaf/config.json while the session went on reading the profile
		// the variable named, so a gate turned off in the sheet stayed on and
		// nothing on screen said why.
		ProfileDir: settings.ProfileDir,
		// The profile answers this question live on every ordinary launch, but
		// --yolo is the one launch that opens the gate without writing that row,
		// so its forced posture has to reach the surface by hand instead.
		ApprovalMode: v3SurfacePosture(*yolo),
		// AND WHETHER THOSE ROWS SEAT ANYTHING THIS RUN. `--one-model` empties the
		// roles source and the task model above, so the crew in the profile is
		// still on disk and still seats nothing — and a surface that did not know
		// drew `crew custom` for the whole run and promised a work seat that
		// picking a crew would move (#444). It is read off the session's own
		// config and not off the flag pointer so the surface reports the bit the
		// session is actually carrying, which is [applyV3Governance]'s answer and
		// not the door's question.
		OneModel: cfg.OneModel,
		// The countdown reads the same frozen value the session clock armed. A
		// profile edit changes both together on the next session rather than
		// moving only the surface's number at a turn boundary.
		BashBackgroundAfterSeconds: cfg.BashBackgroundAfterSeconds,
		// /new and the picker, as the seam answers them. The two wrappers below
		// are the OLDER shape of the same doors, kept because the surface still
		// falls back to them and because the hosted door can only answer that
		// shape (chatv3_host.go): there is one remote agent by construction, so
		// there is nothing per-conversation to hand back.
		Start: seam.start,
		Open:  seam.resume,
		AnchorWorkspace: func(path string) (string, error) {
			return seam.anchor(agent, path)
		},
		// Automations, read and changed off the same store the conversation
		// proposes into (chatv3_clock.go).
		Automations: v3AutomationsSeam(),
		Notify:      v3NotifyRoute(),
		Fresh: func() (tui3.Agent, string, error) {
			conv, err := seam.start("")
			if err != nil {
				return nil, "", err
			}
			return conv.Agent, conv.SessionFile, nil
		},
		// Home's `ask here` — the errand answered in the right pane, whose
		// transcript lives under the errands root and never under v3/projects
		// (chatv3_exchange.go, tui3's homeexchange.go).
		Errand:      v3Errand(cfg, workspace, settings.ProfileDir, *yolo),
		ErrandsRoot: v3ErrandsRoot(),
		// Answering another window's question from home: the answer is left in
		// that session's own folder and it picks it up on its heartbeat
		// (internal/session's answers.go, tui3's homeband_answer.go).
		Answer: session.WriteAnswer,
		// The conversations this directory has had, and the door back into one
		// of them. They are the welcome box's right column and the /resume
		// picker's rows; the walk happens on the keystroke that asks for it and
		// never at boot.
		RecentSessions: func() []tui3.Session { return v3RecentSessions(launch.Bucket) },
		Resume: func(file string) (tui3.Agent, error) {
			conv, err := seam.resume("", file)
			if err != nil {
				// Returned rather than wrapped in a surface that would carry a
				// typed nil: a locked file's error names the file, and the
				// surface prints exactly that.
				return nil, err
			}
			return conv.Agent, nil
		},
		PickSession: pickSession,
		// THE CONVERSATION THIS LAUNCH COULD NOT OPEN, when another window was
		// holding its journal. Empty on every ordinary launch; a transcript path
		// makes the surface come up on home with that row armed, so one enter
		// moves it here (internal/tui3's takeover.go, and [v3TakeOverInstead]
		// above for what this window is sitting in meanwhile).
		TakeOver: takeOver,
		// WHETHER HOME GREETS THIS LAUNCH. It is a person opening codeaf with no
		// particular conversation in mind: no --session, no picker asked for,
		// and — by the time this line runs — no --once, which returned above.
		// The surface applies the rest of the law, including the one condition
		// that is about the machine rather than the command line: a machine with
		// nowhere else to go is not greeted (tui3's home.go [app.landHome]).
		//
		// The --host door does not set it at all: the projects under this
		// process belong to the wrong machine, and home refuses over --host for
		// exactly that reason.
		Landing: strings.TrimSpace(*file) == "" && !pickSession,
		// THE FIRST-RUN SETUP, on the same launch that may open keyless (see
		// `setup` above). The surface applies the rest of its law — a profile
		// with every fact answered, a marker saying it was shown, a resumed
		// conversation — and this door only says whether anybody is here to
		// answer.
		Setup: setup,
		// And the key arriving after the door: every conversation this process
		// holds starts talking with it on its next request, and every one opened
		// later is built with it (chatv3_process.go's [v3Process.setAPIKey]).
		ApplyAPIKey:       proc.setAPIKey,
		ReadCredits:       v3CreditReader(proc),
		PaymentRefusals:   v3PaymentRefusals(proc),
		ImplicitTalk:      strings.TrimSpace(*model) == "" && strings.TrimSpace(env.Get(config.ModelEnv)) == "" && config.ChatModelAt(settings.ProfileDir) == "",
		ApplyModelSources: proc.setModelSources,
		// With no endpoint named, OpenRouter is the model provider and a missing
		// key has a direct browser door. A custom OpenAI-compatible endpoint gets
		// no OpenRouter offer, and a non-interactive launch has nobody to finish
		// one, so both honestly leave this seam absent.
		ConnectOpenRouter: v3OpenRouterConnection(settings, interactive),
		ConnectCodex:      v3CodexConnection(interactive),
		// The accounts panel, and the sign-in a pressed row starts. It is the
		// SAME manager the belt reaches through (cfg.Connect), so an account
		// connected on the panel is connected for the model in the same breath
		// and neither side has to be told about the other.
		Connections: v3Connections(cfg.Connect),
		Workspace:   workspace,
		// Whether that workspace is the session's own work/ directory or a
		// project this was opened inside of (Decision 26). The surface uses it
		// for one thing: what to CALL the place, because an owned workspace's
		// path is codeaf's bookkeeping rather than an answer to "where am I".
		Owned:       launch.Place.Owned,
		SessionFile: transcript,
		Resumed:     resumed,
		Restart:     restart,
		// AND THE LAUNCH FACTS A PERSON CAN ACT ON. The unattended boundary and
		// a replaced codeaf both ride the session-moved line — one dim row at
		// the top of the conversation — rather than growing surfaces of their
		// own. An ordinary attended launch with the same file on disk is still
		// shown nothing whatever.
		Notice:        v3Interrupted(cfg, joinV3Notices(entryNotice, notice, session.UnattendedNotice(cfg), buildinfo.StaleNotice(), v3UpgradeNotice(cfg.Place.Dir, cfg.Interactive))),
		ContextWindow: cfg.ContextWindow,
		History:       recall,
		DraftFile:     draft,
		// The consent card's "always", written down AND handed to the gate this
		// session is running on (chatv3_approval.go). The second half is why a
		// banked rule answers the very next call instead of the next launch.
		// Where a model chosen in /model, in the picker or on the settings sheet
		// is written down, so the next launch opens on it ([v3TalkModel] reads
		// the same row back). It is the profile this launch resolved everything
		// else out of, which is the point: the surface must not be able to write
		// its choice into a file the door does not read.
		SaveModel: func(model string) error {
			return config.WriteChatModel(settings.ProfileDir, model)
		},
		SaveApproval:     bankToolApproval(agent, workspace, settings.ProfileDir, *yolo),
		SaveBashApproval: bankBashApproval(agent, workspace, settings.ProfileDir, *yolo),
		ApplyApprovals:   applyV3Approvals(agent, workspace, settings.ProfileDir, *yolo),
	})
	return finishChatRestart(err, restart, "")
}

// finishChatRestart runs only after the surface door has returned, so every
// connection, session, and terminal cleanup deferred by that door has finished.
func finishChatRestart(err error, restart *codeupdate.Plan, localWorkspace string) error {
	if err != nil || restart == nil || restart.Path == "" {
		return err
	}
	// A linked-local engine outlives its surface, so replacing the executable
	// does not by itself put the new build behind the conversation. Ask it to
	// retire only after the surface has detached; the host itself refuses while
	// another view or any work is active, and a refusal never stops that work.
	if localWorkspace != "" {
		retireUpdateEngine(localWorkspace)
	}
	return restartUpdatedChat(*restart)
}

const updateEngineDetachGrace = time.Second
const updateEngineDetachPoll = 25 * time.Millisecond

var (
	retireChatEngine   = enginehost.Retire
	restartUpdatedChat = codeupdate.Restart
	updateRestartNow   = time.Now
	updateRestartPause = time.Sleep
)

// retireUpdateEngine gives the connection close immediately above long enough
// to reach the host before deciding that somebody else really is keeping it.
// It never uses the force door: another window or live work keeps the old host,
// while the ordinary one-window handoff reliably starts the replacement build.
func retireUpdateEngine(workspace string) {
	deadline := updateRestartNow().Add(updateEngineDetachGrace)
	for {
		err := retireChatEngine(workspace, false)
		if !errors.Is(err, enginehost.ErrHostBusy) || !updateRestartNow().Before(deadline) {
			return
		}
		updateRestartPause(updateEngineDetachPoll)
	}
}

// ── the shared assembly ─────────────────────────────────────────────────────
//
// A conversation is the same object whoever is looking at it. `codeaf chat`
// draws it on the terminal it was typed into; `codeaf engine` answers frames
// about it from the other end of an ssh pipe. NEITHER DOOR MAY ASSEMBLE ITS OWN
// AGENT: two assemblies would be two sets of governance rows, two model
// catalogs and two session-file rules, and the drift between them would show up
// as a feature that behaves one way at home and another way away — the single
// hardest class of bug to see, because both halves look right on their own.

// v3Options is what a door says about the conversation it wants opened. Every
// field is a flag some door carries; the zero value is what `codeaf` bare does.
type v3Options struct {
	// Workspace is the directory the conversation runs in. Empty is the
	// process's own, which is what a terminal door means and what the engine
	// means once it has changed into the directory the surface asked for.
	Workspace string
	// Model beats the configured default for this session only.
	Model string
	// Session is an explicit transcript to open; empty resumes this
	// directory's most recent, or makes one.
	Session string
	// NoCompact and Yolo are the two flags that change what a session may do.
	NoCompact bool
	Yolo      bool
	// Interactive is the door's own fact that A PERSON IS STEERING THIS
	// CONVERSATION — a screen somebody is typing into, here or over a hosted
	// dial. It is not --yolo: yolo is approvals and says nothing about who is
	// watching. The terminal doors set it; --once and every headless caller
	// leave it unset, keeping the unattended goal owner (internal/session's
	// principal.go reads it beside the budget).
	Interactive bool
	// OneModel settles every text call this session makes onto the session
	// model. It is a MEASUREMENT POSTURE rather than a preference: a run whose
	// spend and quality are being attributed to one model cannot have a tier
	// row quietly answering a quarter of its calls on another. It changes no
	// setting and writes nothing — the rows are still there, and the next
	// session without the flag reads them exactly as before.
	OneModel bool
	// Budget is the ceiling an unattended session carries its own work on
	// under: hours, dollars, or both (internal/session's principal.go). THE
	// ZERO BUDGET IS THE DEFAULT AND IS NOT A CEILING OF ZERO — it is the
	// posture every session has always had, where the model stopping is the
	// session stopping.
	Budget session.Budget
	// LaunchDir is where the person stood, when the door knows it better than
	// the process does. Empty is the process's own launch directory, which is
	// every terminal door; `codeaf app` holds conversations in many folders
	// from one process started wherever the desktop app was, so it names the
	// workspace the person asked for instead.
	LaunchDir string
}

// joinV3Notices puts the launch's dim lines on one row, in the order they were
// decided. Either being empty is the ordinary case and leaves the other alone —
// the emptiness law, applied to a separator.
func joinV3Notices(lines ...string) string {
	var kept []string
	for _, line := range lines {
		if line = strings.TrimSpace(line); line != "" {
			kept = append(kept, line)
		}
	}
	return strings.Join(kept, " · ")
}

// chatBudget turns what somebody typed into the ceiling internal/session reads.
//
// A NEGATIVE FIGURE IS NO CEILING RATHER THAN AN ERROR, which is the same
// reading every other numeric row in this build makes of one (the repair-round
// resolver's, the rail's): a person who typed a minus sign has not asked for a
// session that stops before it starts.
func chatBudget(hours, cost float64) session.Budget {
	var budget session.Budget
	if hours > 0 {
		budget.Wall = time.Duration(hours * float64(time.Hour))
	}
	if cost > 0 {
		budget.USD = cost
	}
	return budget
}

// envFloat reads one number out of the environment, and answers zero for
// anything that is not one. It is the default a flag is declared with, so a
// harness that sets the wall once for a campaign does not have to spell it on
// every launch — and the command line still wins, because a flag's own value
// replaces its default.
func envFloat(name string) float64 {
	value, err := strconv.ParseFloat(strings.TrimSpace(env.Value(name)), 64)
	if err != nil {
		return 0
	}
	return value
}

// v3Launch is that assembly, done. The pieces are handed back rather than kept
// because both doors keep using them after the agent exists: the catalog warms
// in the background and answers the model picker, the harness registry is the
// same store /harness lists, and the config is what a replacement agent — /new,
// the picker, Session.New — is built on.
type v3Launch struct {
	Settings  config.Config
	Models    *catalog.Catalog
	Harnesses *subharness.Store
	// Config is the session config with every governance row applied, and with
	// AskConsent NOT yet set: whether anybody is there to answer a question is
	// the door's own fact and the one thing this cannot know.
	Config session.Config
	// Model is the id the session starts on, after the flag and the settings
	// have had their say.
	Model string
	// Workspace, SessionFile and Resumed are the three facts a surface prints
	// before its first turn.
	Workspace   string
	SessionFile string
	Resumed     bool
	// Project is the DIRECTORY THIS CONVERSATION IS ABOUT, which is not always
	// Workspace above: an OWNED conversation works in its own private work/
	// folder under ~/.codeaf/v3/projects, and Workspace is that folder.
	//
	// It is carried because two things are keyed by the project and not by the
	// tools root — the engine host that holds this workspace's conversations
	// (internal/enginehost), and therefore the `codeaf engine --stop --workspace
	// X` in [sessionHeldElsewhereSentence]. Handing that sentence Workspace
	// spelled a command that pointed at a host which does not exist.
	Project string
	// Place is the session folder this launch opened (internal/session's
	// place.go), and Bucket the project directory it sits in. The surface keeps
	// both after the launch: the folder is what /new mints a sibling of, and the
	// bucket is the list of this project's conversations.
	Place  session.Place
	Bucket string
	// Subharnesses is the assembly the four seams on Config were taken from
	// (chatv3_subharness.go). It is carried out of the launch for ONE thing the
	// config cannot hold: the belt watch, which is a question about an agent that
	// does not exist until after this returns and is filled the moment it does
	// (see [beltWatch], and the door it is pointed at, session.Agent.ToolOnBelt).
	Subharnesses v3Subharness
}

func openV3Launch(proc *v3Process, opts v3Options) (*v3Launch, error) {
	// The profile, the catalog, the harness registry and the stores were all
	// resolved once, at the door (chatv3_process.go). Everything below this line
	// is a function of the DIRECTORY this conversation is about, which is the
	// whole of what makes a launch different from the process it runs in.
	settings := proc.launchSettings()
	chosen := v3TalkModel(opts.Model, settings)
	// WHERE THE PERSON IS STANDING, which is not the same fact as which project
	// this is: `codeaf` typed in repo/cmd/ is a conversation about the
	// repository, and the subdirectory is recorded rather than resolved away
	// (Decision 26). A door that named a workspace has already answered the
	// project question and its answer is taken as given.
	launchDir := proc.LaunchDir
	if named := strings.TrimSpace(opts.LaunchDir); named != "" {
		launchDir = named
	}

	project, owned := v3Workspace(launchDir, opts.Workspace)
	found, err := v3ResolveSession(strings.TrimSpace(opts.Session), project,
		v3StampLaunchDir(launchDir, project), owned)
	if err != nil {
		return nil, err
	}
	transcript, resumed := found.Transcript, found.Resumed
	// THE TOOLS ROOT IS THE SESSION'S OWN ANSWER. A borrowed session works in
	// the project it borrowed; an owned one works in its own work/ directory,
	// which is prepared here because nothing downstream may find it missing.
	workspace := project
	if root := strings.TrimSpace(found.Place.Workspace); root != "" {
		workspace = root
	}
	if found.Place.Owned {
		if err := prepareOwnedWorkspace(found.Place); err != nil {
			return nil, err
		}
	}

	// The model pool's judge is the launch's own: it reads every landing of THIS
	// conversation, so it is built here and handed to the shared assembly.
	// The Model Pool's judge reads every landing through the engine's one hook.
	// It is built here, where the seats above are wired, so the answer to
	// "may this process read the pool at all" is one posture for the whole
	// door: a mode that forbids reading builds no hook, and a nil hook is the
	// engine's own nothing. The ask is built once and a client is made from it
	// per call, each billed to the judge's own seat.
	var taskLanded func(session.TaskLanding)
	// AN INDEPENDENT JUDGE CANNOT SHARE THE CREW MODEL. A one-model
	// launch therefore leaves this optional scoring to an ordinary launch;
	// it must neither judge new landings nor sweep earlier pending work. The
	// saved one-model setting can change while this process runs, so the hook
	// and the sweep read it themselves at the moment they would ask
	// ([poolJudgeStandsDown]).
	if !opts.OneModel {
		if config.ModelPoolAt(settings.ProfileDir).CanRead() {
			held := proc.poolErrands
			hook := poolJudgeHookContext(held.ctx, settings, settings.ProfileDir,
				config.CrewCatalog, poolJudgeAsk(proc.liveSettings(settings), settings.ProfileDir), time.Now, "task")
			taskLanded = func(landing session.TaskLanding) {
				held.goCtx("pool/judge", func(context.Context) { hook(landing) })
			}
		}
		// The runs a live process would have judged but a process death left unjudged,
		// and the headless doors that never had this hook: at start, on a goroutine
		// nobody waits on, judge the resumed session's own final-state nodes and the
		// pending file's rows, each exactly once, bounded so it never holds the prompt. The
		// process tracker cancels and joins it at close.
		poolProfile := config.ProfilePath(settings.ProfileDir, "")
		poolErrandGoCtx(proc.poolErrands, "pool/judge-sweep", func(ctx context.Context) {
			poolJudgeSweepRun(ctx, settings, poolProfile, found.Place.Tasks(),
				config.CrewCatalog, poolJudgeAsk(proc.liveSettings(settings), settings.ProfileDir), time.Now)
		})
	}

	cfg, activeModels, subharnesses, err := v3ConfigFor(proc, opts, workspace, found.Place, transcript, taskLanded)
	if err != nil {
		return nil, err
	}
	harnesses := proc.Harnesses

	// THE SHELF IS IMPORTED BEFORE THE FIRST MESSAGE. A person's skills for
	// other harnesses — Claude Code, Codex, any agentskills.io reader — reach
	// the shelf when the graph opens, not when some later tick finds the time:
	// this door claims no residency (runChatV3's header), so the pass the
	// resident reconciler runs on its own clock is run here, synchronously,
	// after [v3Memory]'s graph is open and before the first prompt is built.
	// The pass is idempotent — an unchanged disk journals nothing — so an open
	// costs one scan and no writes, and a skill edited since the last open is
	// re-read before the model ever sees the shelf.
	importForeignSkillsBeforeFirstMessage(proc.skillShelf(), workspace)

	return &v3Launch{
		Settings:     settings,
		Models:       activeModels,
		Harnesses:    harnesses,
		Config:       cfg,
		Model:        chosen,
		Workspace:    workspace,
		Project:      project,
		SessionFile:  transcript,
		Resumed:      resumed,
		Place:        found.Place,
		Bucket:       found.Bucket,
		Subharnesses: subharnesses,
	}, nil
}

// v3ConfigFor assembles the session configuration for work in workspace: the
// person's models, keys, governance, connected accounts, memory, media and
// harness seams, from what the process already resolved at the door.
//
// IT IS THE ONE ASSEMBLY, shared by a conversation's launch and an automation's
// run (chatv3_clock.go). It finds no conversation and starts nothing — which is
// why the launch keeps those parts and an automation can call this: the launch
// resumes the person's newest conversation in a project, and an automation
// that did that would be writing into somebody's chat.
func v3ConfigFor(proc *v3Process, opts v3Options, workspace string, place session.Place, transcript string, taskLanded func(session.TaskLanding)) (session.Config, *catalog.Catalog, v3Subharness, error) {
	settings := proc.launchSettings()
	chosen := v3TalkModel(opts.Model, settings)
	// The model catalog and the sub-harness registry, borrowed from the process
	// rather than opened here (chatv3_process.go states why each must be one).
	// The catalog's warm is already running and is waited for NOWHERE on this
	// path: everything it feeds — the /model picker's list, the context window —
	// has a good answer without it, and an unknown window leaves the session on
	// its conservative default.
	models := proc.Models
	// A DIRECT SERVICE'S OWN CATALOG IS A WARM OF ITS OWN, and it is owned the
	// way the process's is (#1274): it runs under the process lifetime and
	// closeAll cancels and joins it, so no cache write can land after the
	// process has closed or in a later home.
	activeModels, activeModel, activeListsModels := v3CatalogForModel(proc.lifetime(), settings, chosen, models)
	if activeModels != models {
		proc.ownCatalog(activeModels)
	}
	harnesses := proc.Harnesses

	// The typed programs this conversation can reach, and the two stores they are
	// found in (chatv3_subharness.go). It is assembled BEFORE the config because
	// all four seams below are fields of it, and the zero value is subharnesses
	// off — so nothing here has to ask whether the wiring worked.
	//
	// THERE IS ONE START WINDOW. It is read once and handed to both of its
	// readers, the programs this conversation runs here and the session below, so
	// a leaf on `codex/gpt-5.5` sizes itself from the same 272k the conversation
	// does.
	startWindow := v3StartWindow(proc.Shelf, activeModels, chosen, activeModel)
	subharnesses := v3Subharnesses(settings, activeModels, chosen, startWindow, workspace, harnesses)
	mediaSettings := settings
	mediaSettings.Model = chosen
	mediaSettings.Models = activeModels
	var media session.MediaGenerator
	if activeListsModels {
		media = v3ImageGen(mediaSettings)
	}

	cfg := session.Config{
		// The page names codeaf's own data folder when CODEAF_HOME moved it
		// ([session.Config.StateHome]), so a model that read `~/.codeaf` in the
		// manual does not go looking in the person's default home instead.
		StateHome:      v3StateHome(),
		TeamComputers:  teamComputers,
		TeamsPaired:    teamPaired,
		Workspace:      workspace,
		Model:          chosen,
		APIKey:         settings.APIKey,
		BaseURL:        settings.BaseURL,
		Sources:        settings.Sources,
		CompactEnabled: !opts.NoCompact,
		// Carry the saved reader choice into the live chat and its tasks.
		DocumentEngine: settings.DocumentEngine,
		SessionFile:    transcript,
		TaskLanded:     taskLanded,
		// The folder this conversation keeps everything in (Decision 26). It is
		// the zero Place for a launch opened on a flat legacy transcript, which
		// is what keeps that session deriving its sidecars the way it always did.
		Place: place,
		// Where an adaptive run's write-capable nodes get their isolated
		// worktrees (internal/orchestrate): the session folder's trees/ —
		// Decision 26's own law, one per running node, swept with the session.
		// The zero Place answers "" and the run degrades to sharing the
		// workspace, which is the seam's honest answer for a legacy flat
		// session.
		WorktreeRoot: place.Trees(),
		// The durable memory, on the store this time (internal/session's
		// memory.go). It is opened once, here, because where a person's state
		// lives is the door's decision — and it is opened ALWAYS: the memory row
		// governs only the noticing pass, which the session reads live, so the
		// lines a person kept hold whatever the row says.
		Memory: proc.Memory,
		// AND THE CONVERSATION INDEX, WHICH IS NOT THE MEMORY ANY MORE. It is
		// the process's search store — the same handle as Memory, and its own
		// handle of the same file only when the memory store would not open —
		// so the search verb survives that failure. The chat journal indexes
		// the conversation into it either way.
		MemoryIndex: proc.Search,
		// AND THE PROJECT THIS SESSION CAN PROVE IT IS IN. The key is minted
		// from the workspace's origin remote, or its canonical path when there
		// is no remote, and it is what turns a `project` scope word into the
		// owner a memory really belongs to. Empty (an error, or a workspace
		// that could not be resolved) quarantines project writes rather than
		// guessing.
		MemoryProjectKey:  v3ProjectKey(workspace),
		MemoryProjectName: gitidentity.ProjectName(workspace),
		// AND THE SKILL SHELF, which is the line above, and a shelf of the skill
		// folders alone when the memory store would not open ([v3SkillShelf]):
		// the skills a person installed for another harness are not memory, and
		// a broken store is no reason for them to go.
		Skills: proc.skillShelf(),
		// And the file the old memory lived in, carried into the store on the
		// first turn and then renamed out of the way. It is named here rather
		// than derived down there for the reason every other path is.
		MemoryImport: home.Join("v3", "memory.md"),
		// The deliverables index the session's own products (a painted picture)
		// record themselves in — the same file the surface's /export and /files
		// resolve, spelled once (chatv3_place.go) and resolved once per process.
		ArtifactsIndex: proc.Artifacts,
		// The profile whose config.json /settings writes, handed over so the
		// conversation can read the person's settings back and change one for
		// them (internal/session's tools_settings.go). It is the SAME directory
		// the panel edits (internal/tui3's registry) and the same one every row
		// above was resolved out of, so a change made by asking and a change made
		// by hand are one change to one file.
		ProfileDir: settings.ProfileDir,
		// The window the model this session STARTS on actually accepts, when
		// anybody can say so without waiting. Zero keeps session's own
		// conservative default, and for a model on the default service
		// [warmV3Models] corrects it in place the moment the catalog resolves.
		//
		// NEITHER IS ASKED OF THE CATALOG ALONE (#1383). The catalog this
		// conversation started on knows nothing about a model on another
		// service, and Codex's is empty because Codex publishes no listing, so
		// the shelf — which holds each connected service's remembered rows from
		// the moment the process read the profile — answers what that catalog
		// cannot. The start window asks the catalog first ([v3StartWindow]); the
		// switch lookup asks the shelf first, because the catalog it would ask
		// is the one the conversation STARTED on ([v3WindowFor]).
		ContextWindow:    startWindow,
		ContextWindowFor: v3WindowFor(proc.Shelf, activeModels),
		// Whether the model in use can LOOK at a picture, from the catalog's
		// published input modalities. It is a closure rather than a value
		// because the answer is about the model the NEXT turn rides, and this
		// session's model changes under /model (see [v3SeesImages]). It reads
		// the SHELF, so a model picked out of a list somebody refreshed a moment
		// ago is answered from that list rather than refused as unknown.
		SupportsImages: v3SeesImages(proc.Shelf),
		// The published answer to "may this call carry this knob", which the
		// adapter asks before it lets an optional field travel. It was wired to
		// nothing on this path, so a reasoning level set with ctrl+t or
		// --reasoning went to every model blind — and on a router, a knob no
		// endpoint publishes is not a 400 but a 404 with no endpoints left to
		// serve the request (internal/provider's endpoints.go).
		//
		// AND IT IS ASKED ABOUT THE ID THE SERVICE IS SENT. A model behind a
		// connected service is named here with the service's written prefix
		// (`stub/z-ai/glm-5.3-flash`), and the adapter asks the same catalog
		// about the id it puts on the wire (`z-ai/glm-5.3-flash`): answered only
		// about the prefixed name, the session kept the working page for a
		// model the adapter was already sending no tools (chatpage.go).
		SupportsParameter: v3SupportsParameter(proc.Shelf, activeModels),
		ReasoningProfile:  config.ReasoningProfileSeam(activeModels),
		// And the model's own published price, which is what bounds the latency
		// ask: this session wants the fastest endpoint, not the dearest one
		// wearing the model's name (internal/provider's latencyPriceCeiling).
		ModelPrice: activeModels.PriceNow,
		// Where a conversation goes when nothing serving its model will take the
		// request at all. Closures again, and for the same reason as the vision
		// gate: the question is about the model the failing turn was ON, which
		// /model moves.
		NearestModels: v3NearestModels(activeModels),
		// The models a task may be handed to, asked at the moment a proposal
		// names one and never at boot — the picker's own bargain, because both
		// questions are about a catalog that may still be warming and neither of
		// them may wait for it. The shelf, for the vision gate's reason.
		TaskModels: v3TaskModels(proc.Shelf),
		// The two halves of the harness offer (internal/session's harness.go):
		// what a turn is matched against, and what a yes reaches. They are
		// filled together because either one alone is detection off — a
		// registry nothing can run would raise a card that could only fail, and
		// a runner nothing is matched against would never be called.
		// RunHarness is filled AFTER governance, beside the media pair: a run's
		// belt now carries the media verbs this machine has models for
		// (internal/session's harness_belt.go), and the resolver that answers
		// which model serves which modality reads a role pin that does not exist
		// until governance has landed.
		Harnesses: v3HarnessEntries(harnesses),
		// And the third: where a harness this conversation DESIGNS is written
		// (internal/session's harness_build.go). It is the same store the two
		// above were built from, so a page approved on a card is a page the very
		// next sentence can be matched against.
		HarnessStore: harnesses,
		// AND THE SUBHARNESS SIDE, which is the same three-part shape one row up:
		// what can be reached, where what it learns is kept, and what is known
		// about the last time each one ran (docs/SUBHARNESS-CONTRACT.md §5). They
		// are filled together because any one of them alone is a half-wiring — a
		// registry with no memory teaches a program it learnt something it did
		// not, and a history nothing writes to is a list of rows that will never
		// say anything.
		//
		// NIL IS SUBHARNESSES OFF and every one of these is allowed to be nil: a
		// store that cannot be read, a client that cannot be built and a machine
		// with no bundles on it all arrive here as the zero value, and the doors
		// in internal/session answer nothing, calmly.
		Subharnesses:        subharnesses.Registry,
		SubharnessMemory:    subharnesses.Memory,
		SubharnessLastRun:   subharnesses.LastRun,
		SubharnessRecordRun: subharnesses.Record,
		// AND THE PROGRAMS THIS BUILD CARRIES that a task can be handed to
		// whole (chatv3_delegate.go). Empty is none, on the terms above.
		Delegates: v3Delegates(),
		// The hand that paints, and the model it asks (internal/session's
		// tools_image.go). The pair is CONDITIONAL on the other side — a nil
		// client leaves generate_image off the belt entirely — so this is
		// allowed to hand over nothing, and does on a build that cannot open a
		// media client at all.
		//
		// The media client, on the contract's terms: nil keeps every
		// generation verb off the belt. The RESOLVER (MediaModel) is wired
		// after governance lands, because its pin rung reads RolesSource.
		Media: media,
		// The automations store, opened once per process (chatv3_clock.go). It
		// is filled for every door that is a CONVERSATION — chat, resume,
		// engine — and taken away again on the --once path below, because
		// nothing unwatched may set up something that runs on a clock.
		Automations: v3Automations(),
		// THE DIVISION ROAD, on by default (internal/config's DefaultSwarm). A
		// task that turns out to hold more than one worker's share may split
		// itself into parts and stay to fold them back together
		// (internal/session's task_divide.go). It is free when it does not
		// apply — the road is armed one task at a time, and a division still
		// has to name enough separate items and find a free hand before
		// anything is born — which is what makes on the right default and
		// `CODEAF_SWARM=0` the whole of the way out.
		Divide: settings.Swarm,
	}

	// What this session may do without asking, which model answers its
	// auxiliary calls, and what it may spend. All three are settings rows, and a
	// row that cannot be read stops the launch here rather than downstream.
	cfg, err := applyV3Governance(cfg, settings.ProfileDir, opts.Yolo, opts.OneModel)
	if err != nil {
		return session.Config{}, nil, v3Subharness{}, err
	}
	// AND WHO THIS SESSION IS WORKING FOR (internal/session's
	// principal.go): the unattended flag and its ceiling, plus the door's own
	// steering fact read apart from both — the ONE place they reach the
	// engine, on [applyV3Governance]'s own law, so this is a translation and
	// never a second policy.
	cfg.Unattended = opts.Yolo
	cfg.Interactive = opts.Interactive
	if !opts.Interactive {
		gate := &v3ApprovalGate{workspace: cfg.Workspace, profileDir: settings.ProfileDir, headless: true}
		cfg.ApprovalGate = gate
		cfg.ApprovalPolicy, cfg.Guardian, err = gate.Build(cfg.ApprovalPosture)
		if err != nil {
			return session.Config{}, nil, v3Subharness{}, err
		}
	}
	cfg.Budget = opts.Budget
	// AND THE ACCOUNTS MANAGER IS THE PROCESS'S, not this launch's. Governance
	// leaves the field empty for exactly this reason: an account connected on
	// the panel must be connected for every conversation's belt in the same
	// breath, and two managers on one store are two caches that disagree the
	// moment either of them refreshes a token (chatv3_process.go).
	cfg.Connect = proc.Conns

	// THE MEDIA PAIR, and it is wired after governance because half of it is
	// governance's own work: the role pins the resolver reads as its second rung
	// arrive on cfg.RolesSource one line up (docs/MULTIMODAL.md Decision 5).
	//
	// The client is the one endpoint set — /images, /audio/speech, /videos —
	// and a nil one keeps every generation tool off the belt rather than on it
	// and failing. The resolver is nil for nobody: it answers "" per modality,
	// which is the same absence at a finer grain.
	if activeListsModels {
		cfg.Media = v3MediaClient(mediaSettings)
		cfg.MediaModel = v3MediaModel(activeModels, settings.ProfileDir, cfg.RolesSource, cfg.OneModel)
		cfg.MediaPick = v3MediaPick(activeModels)
		cfg.MediaAdmission = v3MediaAdmission(activeModels, settings.ProfileDir, cfg.RolesSource)
	}

	// AND THE RUN DOOR IS BUILT FROM THE SAME PAIR. A saved harness may name a
	// media verb on its whitelist, and the node that reaches for it at run time
	// must resolve against the belt the designer was offered — one list, three
	// readers (internal/session's harness_belt.go). It is wired here rather than
	// in the literal above because the resolver it needs is one line up.
	// THE FOLDER AND THE INDEX TRAVEL WITH THE MEDIA PAIR, and for the same
	// reason: a film a saved procedure assembles is a deliverable of THIS
	// conversation, so it lands where this conversation's own films land and gets
	// the same row in `/files`. Left out, the run's belt fell to the legacy dot
	// directory and recorded nothing, which made a harness's work invisible.
	cfg.RunHarness = v3RunHarness(harnesses, settings, chosen, workspace, session.HarnessBeltSeams{
		Media: cfg.Media, MediaModel: cfg.MediaModel, MediaPick: cfg.MediaPick, MediaAdmission: cfg.MediaAdmission,
		Place: cfg.Place, ArtifactsIndex: cfg.ArtifactsIndex,
	})
	// AND THE SAME DOOR PUTS THAT STORE ON THE LIST. A program saved as a page is
	// a program this conversation can run, so it belongs on `/subharness` beside
	// the bundles and the compiled-in workers rather than in a catalog of its own
	// (chatv3_subharness.go's UsePages). It is wired here because the runner it
	// needs is the line above.
	subharnesses.UsePages(harnesses, cfg.RunHarness)
	return cfg, activeModels, subharnesses, nil
}

// importForeignSkillsBeforeFirstMessage runs the foreign-skill import pass
// against the conversation's own shelf, in place: every SKILL.md folder a
// person already has for another harness becomes one active skill fact whose
// artifact is the ORIGINAL directory, before the first message is built. The
// resident reconciler keeps the same pass behind its gate for the processes
// that tick; a launch runs it on the open itself, because a shelf that
// arrives after the first message is a shelf the first conversation cannot
// use.
//
// A launch with no shelf runs no pass, and a home that cannot be resolved is
// skipped, never fatal: a scan that finds nothing must not be the reason a
// conversation does not open.
func importForeignSkillsBeforeFirstMessage(shelf *store.Store, workspace string) {
	if shelf == nil {
		return
	}
	homeDir, err := home.Login()
	if err != nil {
		return
	}
	resident.ReconcileImportedSkills(shelf, workspace, homeDir)
}

// v3SkillShelf is the store the skill shelf lives in for one process: the
// memory store when there is one, and without one a store of its own in a
// fresh temporary folder, which the process removes when it closes. The
// second answer is the folder it made, so the close knows what to remove; it
// is empty when the shelf is the memory store.
//
// MEMORY OFF IS NOT SKILLS OFF. The setting promises a conversation that
// carries nothing about the person across conversations and makes no memory
// calls, and the skills a person installed for Claude Code or Codex are
// neither: they are folders on disk that say nothing about them. So the shelf
// is still built, from those folders and nothing else, by the same import
// pass that fills it with memory on — the folders stay the one source of
// truth either way, and nothing is written into the memory database the
// person turned off. The shelf is thrown away with the process, so it never
// becomes a second, older copy of what the folders say.
//
// A shelf that cannot be made is no shelf: the conversation opens without
// skills, the way it would have with no skill folders at all, and the /skill
// picker says on each row that it cannot attach.
func v3SkillShelf(memory *store.Store) (*store.Store, string) {
	if memory != nil {
		return memory, ""
	}
	dir, err := os.MkdirTemp("", "codeaf-skills-")
	if err != nil {
		return nil, ""
	}
	shelf, err := store.Open(filepath.Join(dir, "shelf.db"))
	if err != nil {
		_ = os.RemoveAll(dir)
		return nil, ""
	}
	return shelf, dir
}

// skillShelf is the shelf this process's conversations read, falling back to
// the memory store for a process assembled without [v3SkillShelf] (the
// suite's own processes are built by hand).
func (p *v3Process) skillShelf() *store.Store {
	if p.Skills != nil {
		return p.Skills
	}
	return p.Memory
}

// v3SavedEffort is the rung this conversation was last left on, read back off
// its own folder, and "" for a session that has none — a fresh conversation, a
// build before the field existed, or a launch with no folder at all.
//
// A UNREADABLE FILE IS ABSENCE AND NEVER A FAILURE, exactly as [session.LoadMeta]
// answers everything else about a folder: the rung is a convenience, and a
// launch that refused to open because it could not read one would be the
// convenience costing the thing it was meant to serve.
func v3SavedEffort(place session.Place) string {
	dir := strings.TrimSpace(place.Dir)
	if dir == "" {
		return ""
	}
	meta, err := session.LoadMeta(dir)
	if err != nil {
		return ""
	}
	return meta.Effort
}

// v3SavedApproval is the posture this conversation last set on its own gate,
// read back off its folder on [v3SavedEffort]'s terms: "" for a fresh
// conversation, a build before the field existed, or a file that does not read.
func v3SavedApproval(place session.Place) string {
	dir := strings.TrimSpace(place.Dir)
	if dir == "" {
		return ""
	}
	meta, err := session.LoadMeta(dir)
	if err != nil {
		return ""
	}
	return meta.Approval
}

// v3TalkModel is which model this conversation opens on, and the order is the
// whole content: what the person named on the command line, then what they
// last chose and it was written down (internal/config's chatmodel.go), then
// what the environment and the built-in default say.
//
// THE SAVED CHOICE BEATS CODEAF_MODEL, which is the settings row's own law
// rather than this door's invention: the talk slot carries the variable as an
// [config.Setting.EnvDefault] and not an [config.Setting.Env], so it seeds a
// value nobody has chosen and never freezes the row. A launch that let the
// variable win would make a pick in /model revert on the next start while the
// sheet went on showing it as editable.
func v3TalkModel(asked string, settings config.Config) string {
	if named := strings.TrimSpace(asked); named != "" {
		return named
	}
	if saved := config.ChatModelAt(settings.ProfileDir); saved != "" {
		return saved
	}
	if strings.TrimSpace(env.Get(config.ModelEnv)) == "" && (settings.Model == config.DefaultModel || settings.Model == config.FreeChatModel) {
		return config.ChatDefaultAt(settings.ProfileDir)
	}
	return settings.Model
}

// v3ImageGen is the hand generate_image calls through, or NIL — which is the
// tool absent rather than the tool refusing (session.Config's ImageGenClient
// states that law and internal/session's tools_image.go applies it).
//
// The two-line dance is [v3Connections]'s and Go's: a nil *provider.MediaClient
// put into an interface is a NON-nil interface holding nothing, and the belt
// tests its door with a plain nil check. Without the explicit return, a build
// that could not open a client would carry a generate_image that panicked
// instead of a belt that never mentioned one.
//
// IT RETURNS NO ERROR, for the reason [v3Search] does not. Painting is an
// accessory; a client that cannot be built is a session with one fewer tool,
// and no reason a person cannot open a conversation.
func v3ImageGen(settings config.Config) session.MediaGenerator {
	client, err := settings.MediaClient()
	if err != nil || client == nil {
		return nil
	}
	return client
}

// v3Connections hands the surface the accounts manager, and keeps a nil a nil.
//
// The two-line dance is Go's and not a choice: a nil *connect.Manager put into
// an interface is a NON-nil interface holding nothing, and the surface tests
// its door with a plain nil check. Without this, a build with no Google
// registration would open an accounts panel it could not fill and offer rows
// that could only fail — the same belt-that-lies internal/session refuses to
// build, drawn on a screen instead. A build without a registration says plainly
// that it cannot manage accounts, which is the honest answer.
func v3Connections(manager *connect.Manager) tui3.Connections {
	if manager == nil {
		return nil
	}
	return manager
}

// openV3Agent opens the session this run writes.
//
// A resumed transcript is this directory's most recent, which is exactly the
// file a second window in the same directory may already be holding open.
// Session answers that with [session.ErrSessionLocked] — the right answer,
// since two writers on one journal is a corrupted journal.
//
// SILENTLY STARTING A NEW CONVERSATION IS DEAD, and killing it is the point of
// this implementation. This door used to mint a sibling session and say "session open
// elsewhere — started a new one", which sounds like an explanation and is
// actually the defect: the conversation the person came back for was still
// running a few inches away, in another terminal or in this workspace's session
// host, and nothing on the screen led them to it. The road that does lead there
// is tried BEFORE this function is ever called ([v3HostRoad] and
// chatv3_local.go), so a lock that reaches this line is one no host is holding —
// an older build, or a window that has stopped answering. That is a fact worth
// a sentence, and the sentence names the one command that lets go of it.
//
// It returns the config as it ended up, because the session file may have moved.
//
// `open` is HOW a session is built, and there are two answers: [v3OpenSession],
// which wires the adaptive runner to the agent it is building, and session.New,
// which does not. It is a parameter rather than a branch because the difference
// is the caller's own fact — the engine's surface is on another machine and
// cannot be shown a fuel gate (engine.go) — and a door deciding that for itself
// would be this file guessing who is watching.
func openV3Agent(cfg session.Config, workspace string, open func(session.Config) (*session.Agent, error)) (*session.Agent, session.Config, string, error) {
	// A chat in the middle of being taken over here is not opened: a session booted
	// now would read the journal from before the swap (see [handoff.Arrive]).
	if handoff.Arriving(cfg.Place.Dir) {
		return nil, cfg, "", errors.New(chatArrivingSentence)
	}
	model, modelNotice, err := continuedModel(cfg)
	if err != nil {
		var missing *continuedModelUnavailable
		if !errors.As(err, &missing) {
			return nil, cfg, "", err
		}
		// Taking and opening a chat do not require a usable model. Retain the
		// incoming identity even if seating seals local bookkeeping first.
		cfg.PrepareModel = missing.prepare
	}
	if model != "" {
		cfg.Model = model
	}
	cfg, claim := v3SeatedPending(v3Migrated(cfg))
	defer claim(false)
	constructed := false
	defer func() {
		if !constructed {
			if seals, ok := cfg.Seals.(interface{ Retire() }); ok {
				seals.Retire()
			}
		}
	}()
	// Restore the gate before construction, so restored work cannot start behind
	// the profile default. Return the launch config unchanged: a subsequent new
	// conversation must not inherit this one's saved override.
	restored := cfg
	savedEffort := strings.TrimSpace(v3SavedEffort(cfg.Place))
	restoredPosture := ""
	if saved := strings.TrimSpace(v3SavedApproval(cfg.Place)); saved != "" && cfg.ApprovalPosture == "" && cfg.ApprovalGate != nil {
		valid := false
		for _, posture := range session.ApprovalPostures {
			if saved == posture {
				valid = true
			}
		}
		if !valid {
			saved = session.PostureAsk
		}
		build := saved
		if saved == session.PostureAuto {
			build = ""
		}
		policy, guardian, err := cfg.ApprovalGate.Build(build)
		if err != nil {
			return nil, cfg, "", fmt.Errorf("restore conversation approvals: %w", err)
		}
		if policy == nil {
			return nil, cfg, "", errors.New("restore conversation approvals: rules unavailable")
		}
		restored.ApprovalPolicy, restored.Guardian, restoredPosture = policy, guardian, saved
	}
	agent, err := open(restored)
	if err == nil {
		claim(true)
		if model != "" {
			if err := agent.ContinueWithModel(model, modelNotice); err != nil {
				closeV3Agent(agent)
				return nil, cfg, "", err
			}
		}
		if restoredPosture != "" {
			if err := agent.SetApprovalPosture(restoredPosture); err != nil {
				closeV3Agent(agent)
				return nil, cfg, "", fmt.Errorf("restore conversation approvals: %w", err)
			}
		}
		if savedEffort != "" {
			agent.SetConversationEffort(savedEffort)
		}
		constructed = true
		return agent, cfg, modelNotice, nil
	}
	if !errors.Is(err, session.ErrSessionLocked) {
		// With account storage off, startup is purely local and makes no relay
		// writes, so retaining the drive lets callers observe watch retirement.
		if syncsetup.StorageForHome(home.Dir()) == "off" {
			claim(true)
		}
		return nil, cfg, "", err
	}
	return nil, cfg, "", &sessionHeldElsewhere{
		transcript: cfg.SessionFile,
		reason:     sessionHeldElsewhereSentence(workspace),
	}
}

// chatArrivingSentence is what a door says about a chat that is being moved onto
// this computer right now: it opens by itself when the move ends.
const chatArrivingSentence = "this chat is arriving on this computer; it opens by itself in a moment"

// sessionHeldElsewhere is a conversation another window is writing, named so a
// door with a SCREEN can do something better than print the sentence.
//
// A launch that can draw offers the conversation instead: it opens a fresh one
// beside it and lands on home with this row armed, so one enter moves the real
// one here ([v3TakeOverInstead], and internal/tui3's takeover.go). A launch with
// nobody watching — `--once`, `codeaf engine` — has nowhere to put an offer, so
// it prints [sessionHeldElsewhere.Error] and stops. The transcript is carried
// because the surface needs the PATH and the sentence deliberately does not
// contain one.
//
// It unwraps to [session.ErrSessionLocked], so every existing errors.Is on this
// road still answers what it always answered.
type sessionHeldElsewhere struct {
	transcript string
	reason     string
}

func (e *sessionHeldElsewhere) Error() string { return e.reason }
func (e *sessionHeldElsewhere) Unwrap() error { return session.ErrSessionLocked }

// v3TakeOverInstead is the launch-on-lock road: the conversation this terminal
// asked for is open in another window, so this one opens a FRESH conversation in
// the same workspace and hands the surface the row it could not have.
//
// THE NEW CONVERSATION IS NOT A CONSOLATION PRIZE AND IT IS NOT A SURPRISE
// EITHER, which is the whole difference from the fallback this replaces. The old
// one opened a second conversation and said "started a new one", and a person
// was left holding something they did not ask for with no road back. This opens
// the same second conversation — somebody has to be somewhere while they decide
// — AND points at the one they came for, armed, one keystroke away. `esc` keeps
// the new one and nothing is lost either way.
//
// It is [v3NextSession], the ordinary /new road, for the ordinary reason: a
// second conversation about this project is a sibling folder in the same bucket.
func v3TakeOverInstead(cfg session.Config, workspace string) (*session.Agent, session.Config, error) {
	place, err := v3NextSession(cfg.Place, workspace)
	if err != nil {
		return nil, cfg, err
	}
	fresh, err := v3PointAt(cfg, place)
	if err != nil {
		return nil, cfg, err
	}
	agent, fresh, _, err := openV3Agent(fresh, workspace, v3OpenSession)
	return agent, fresh, err
}

// sessionHeldElsewhereSentence is what a person reads when the conversation
// they asked for is being written by something else.
//
// IT POINTS AT THE HAND-OFF AND NOT AT A NEW CONVERSATION. What somebody who
// meets this actually wants is to CONTINUE the conversation here — issue #71's
// own words — so the sentence names the move: open codeaf in this directory and
// press enter on that row. "Start a new conversation here" was the old way out
// and it is not offered as the way out any more, because it answers a question
// nobody asked.
//
// IT NAMES THE WORKSPACE IN THE COMMAND AND NOT A JOURNAL PATH. The path is
// codeaf's own bookkeeping and there is nothing to do with it; and `codeaf
// engine --stop` with no --workspace means the HOME directory rather than this
// one, so the flag is spelled out. It is [staleEngineHostSentence]'s voice,
// said about this machine.
//
// ONE SENTENCE IN ONE PLACE. Every door that meets a held journal says exactly
// this, and the manual quotes it — a refusal spelled two ways is two refusals
// to a person who met one of them last week.
func sessionHeldElsewhereSentence(workspace string) string {
	if strings.TrimSpace(workspace) == "" {
		return sessionHeldElsewhereOpening + " — open codeaf here and press enter on it to move it here, or run codeaf engine --stop to let go of it"
	}
	return fmt.Sprintf("%s — open codeaf here and press enter on it to move it here, or run codeaf engine --stop --workspace %s to let go of it", sessionHeldElsewhereOpening, workspace)
}

// sessionHeldElsewhereOpening is the first clause of that sentence, spelled
// once so that the CLIENT SIDE OF THE SOCKET CAN RECOGNISE IT.
//
// A refusal made inside the engine reaches the surface as a sentence and
// nothing else: internal/remote carries a boot failure as `engine: ` plus the
// text ([remote.spokenError]), which is right — a person reads it unchanged —
// and leaves the dialler with a string to read. So the one place the wording
// lives is here, and the one reader of it is [hostHeldRefusal]. A second
// spelling anywhere would be a road that silently stopped recognising the
// refusal it is written to answer.
const sessionHeldElsewhereOpening = "this conversation is open in another window"

// hostHeldRefusal reports whether an engine refused a hello because the journal
// it was asked for is held by something else — [session.ErrSessionLocked] as it
// looks after a trip over a socket.
func hostHeldRefusal(err error) bool {
	return err != nil && strings.Contains(err.Error(), sessionHeldElsewhereOpening)
}

// engineHeldRefusal is that refusal given its identity back: the sentence the
// engine wrote, which still reads exactly as it did, and
// [session.ErrSessionLocked], which is what every surface door tests for.
//
// WITHOUT IT, MOVE-IT-HERE COULD NOT WORK AGAINST A WINDOW. On 2026-09-23 a
// window on today's build met a conversation held by an older in-process
// window, pressed enter on the row, and was shown the engine's sentence — "open
// codeaf here and press enter on it to move it here" — which is the instruction
// it had just followed. Home reads a held conversation's refusal as
// [session.ErrSessionLocked] and takes the asking road on it (internal/tui3's
// homeHeldEnter); a bare string over the socket was not that, so the request
// was never written, and the only way out was killing the other window by hand.
type engineHeldRefusal struct{ said error }

func (e *engineHeldRefusal) Error() string { return e.said.Error() }
func (e *engineHeldRefusal) Unwrap() []error {
	return []error{e.said, session.ErrSessionLocked}
}

// asHeldRefusal is [engineHeldRefusal] applied where it belongs, and the error
// unchanged everywhere else.
func asHeldRefusal(err error) error {
	if err == nil || errors.Is(err, session.ErrSessionLocked) || !hostHeldRefusal(err) {
		return err
	}
	return &engineHeldRefusal{said: err}
}

// ── governance: what a session may do, on whose models, for how much ────────
//
// The settings rows and one flag reach internal/session here, and this is the
// ONLY place they do. Each is a seam that already exists on the other side —
// [approval.Policy], [roles.Source], the spend rail, [search.Resolve]'s pair —
// so the mapping is a translation and never a second policy.
//
// EVERY PARSE ERROR STOPS THE LAUNCH, with the row named. A tool gate that
// silently ignored the line it could not read would be a gate that opens for
// exactly the reason nobody would think to check: a typo in the file that was
// meant to close it.
//
// THE PROJECT LAYER ENTERS HERE. cfg.Workspace is the directory this session
// runs in, so <workspace>/.codeaf/config.json is the repository's own answer to
// these rows, and every read below resolves project → profile → default
// (internal/config's projectconfig.go). A caller with no workspace — a test, a
// door that has not resolved a directory — gets an empty layer rather than a
// lookup in whatever directory the process happens to be sitting in.
func applyV3Governance(cfg session.Config, profileDir string, yolo, oneModel bool) (session.Config, error) {
	workspace := strings.TrimSpace(cfg.Workspace)
	policy, err := v3Policy(workspace, profileDir, yolo)
	if err != nil {
		return cfg, err
	}
	// --one-model withholds the ladder AND says so to the session. Withholding is
	// most of it: an empty task model reads the live conversation model
	// (internal/session's defaultTaskModel), an empty fallback chain hops nowhere,
	// and the roles ladder falls through pin, then tier, then the floor its caller
	// passed (internal/roles' ResolveCall). Those are unset states this build has
	// always handled, and they stay unset rather than becoming a fourth resolution
	// path that could drift from the other three.
	//
	// BUT WITHHOLDING ALONE IS NOT THE PROMISE, and this comment used to claim it
	// was. Two errands hand the ladder an EMPTY floor on purpose — the mark's
	// reader and the brief's writer are crew-only, so that an install with no
	// mastermind gets no second opinion rather than the running model marking its
	// own work — and with no pin, no tier and no floor those two rungs resolve to
	// no model at all. A measured run under the flag therefore had neither, and
	// the person was told the second model could not be reached (#443). So the
	// flag is CARRIED into the session as [session.Config.OneModel] and answered
	// once at the seam every errand passes through, which is the only place a
	// third crew-only caller can be made right without knowing the flag exists.
	//
	// Media slots remain capability-qualified rather than following text roles.
	// With this flag an explicit media pin is strict: an unsupported pinned
	// operation is unavailable instead of falling through to another model.
	// Unpinned media keeps its normal discovery and fallback behavior.
	// The rows are not even read under the flag. Reading them only to discard
	// the answer would make a malformed pins row stop a launch that had already
	// said it does not care what the pins say.
	var source func(string) (string, bool)
	if !oneModel {
		if source, err = v3RolesSource(workspace, profileDir); err != nil {
			return cfg, err
		}
	}
	rail, err := config.ProjectFloatAt(workspace, profileDir, config.KeySpendRail)
	if err != nil {
		return cfg, err
	}
	cfg.ApprovalPolicy = policy
	cfg.RolesSource = source
	cfg.OneModel = oneModel
	// EVERY TASK THIS CONVERSATION STARTS IS ROUTED ITS OWN CREW — worker,
	// planner, checker picked for that task from the profile's allowed models
	// and pins (internal/config's RouteCrew, internal/session's taskcrew.go).
	// Under `--one-model` there is no crew: every call rides the conversation's
	// model, which is what the flag says, so no router is handed over.
	if !oneModel {
		cfg.RouteCrew = func(ask config.CrewAsk) (crewroute.Decision, error) {
			return config.RouteCrew(profileDir, ask)
		}
	}
	cfg.SpendRailUSD = rail
	// The fallback chain reads PROFILE-ONLY, like the search keys below and
	// unlike the three rows above it. A repository that could answer this could
	// send a visitor's next turn — and their credit — to a model they never
	// picked, by being cloned. Which models a person's questions may go to is
	// theirs to say.
	cfg.ModelFallbacks = config.ParseModelFallbacks(config.ModelFallbacksAt(profileDir))
	if oneModel {
		// A chain that hops to a second model on a failure is the one remaining
		// way a single-model run stops being one, and it fires exactly when
		// nobody is watching. Empty is "no hop", which is what this build has
		// always done for a person who set no chain.
		cfg.ModelFallbacks = nil
		// AND THE CATALOG'S GUESS WITH IT. Nilling the row alone was not enough
		// and quietly never had been: the chain falls through to NearestModels
		// when no row is written (internal/provider's fallbackChain), so a
		// single-model run that met a refusal would have walked to two models the
		// catalog thought were similar — chosen by nobody, and attributed to a
		// measurement cell that says it rode one model. Both seams are the same
		// question, so both are withheld by the same flag.
		cfg.NearestModels = nil
	}
	// The guardian (internal/session's guardian.go) reads PROFILE-ONLY, unlike
	// the two rows above it, and the reason is the one that keeps the search keys
	// out of the project layer too: a repository that could turn this on would be
	// appointing a stand-in for a visitor who never agreed to have one. The rules
	// a repository may state are still the rules — it can say what to ask about;
	// it cannot say who answers.
	cfg.Guardian = config.GuardianEnabledAt(profileDir)
	// AND THE DOOR THE CONVERSATION MOVES ITS OWN GATE THROUGH, over the same
	// rows (chatv3_approval.go's [v3ApprovalGate]). --yolo is handed down as the
	// posture an untouched conversation starts at rather than only as the
	// policy it starts on, so the seam can say what it is and the wheel can
	// walk away from it (internal/session's approvalposture.go).
	cfg.ApprovalGate = &v3ApprovalGate{workspace: workspace, profileDir: profileDir}
	if yolo {
		cfg.ApprovalPosture = session.PostureAllow
	}
	cfg.TaskAutoApproveSeconds = config.TaskAutoApproveAt(profileDir)
	cfg.BashBackgroundAfterSeconds = config.BashBackgroundAfterAt(profileDir)
	// Which model the work that leaves this conversation runs on, PROFILE-ONLY
	// for the reason the fallback chain above is: a repository that could answer
	// this could send a visitor's work — and their credit — to a model they never
	// picked, by being cloned.
	cfg.TaskModel = config.TaskModelAt(profileDir)
	// HOW HARD EVERYTHING HERE THINKS, when nothing nearer to the work has said.
	// PROFILE-ONLY for the same reason the row above it is: a repository that
	// could answer this could spend a visitor's money on a depth they never
	// asked for, by being cloned. It is the ladder's last rung and every model
	// call in the session reaches it through one resolver (internal/effort).
	cfg.DefaultEffort = config.DefaultEffortAt(profileDir)
	// A CONVERSATION IS A PERSON'S TURN AND SO IS THE WORK THEY HAND OUT. The
	// role is set here rather than defaulted in the engine so that a session
	// built without a door — a test, a headless --once — is not silently opted
	// into paying for depth nobody configured.
	cfg.EffortRole = effort.RoleChat
	if oneModel {
		// Empty is not "no model", it is "the model this conversation is on
		// right now" (internal/session's defaultTaskModel), which is precisely
		// what the flag promises for work that leaves the conversation.
		cfg.TaskModel = ""
	}
	// EVERY DOOR THAT BUILDS A SESSION RUN READS ITS AUDIT POSTURE HERE. The
	// question in #618 was askable only because nothing held that one-reader
	// law; taskaudit_law_test.go now makes a second reader or an unwired door fail
	// on the day it lands.
	cfg.TaskAudit = config.TaskAuditEnabledAt(profileDir)
	// AND WHETHER THE SIGNATURE ON THE GIT WORK codeaf DOES IS WRITTEN AT ALL,
	// OR NAMES THE MODEL, read here for the reason the audit row above it is
	// read here: every v3 door comes through this function, and a row honoured
	// in the conversation but not in an automation's run is a row the person
	// cannot trust. PROFILE-ONLY — a repository that could change what a
	// visitor's commits say about them by being cloned would be writing into
	// somebody else's provenance. The CONTRIBUTING file a repository writes
	// still wins over the signature, but it wins by being read and obeyed, not
	// by rewriting somebody's profile (internal/exec's AttributionLaw).
	cfg.AttributionOff = !config.AttributionAt(profileDir)
	cfg.AttributionModelOff = !config.AttributionModelAt(profileDir)
	// Whether a reply that comes apart is cut and asked again. PROFILE-ONLY, and
	// the reason is not trust this time but taste: it is a judgement about
	// somebody's own replies, and a repository has no business turning off a
	// visitor's protection against a model that has stopped writing language.
	cfg.ReplyGuardOff = !config.ReplyGuardEnabledAt(profileDir)
	// How much codeaf puts in front of the model before the person has typed.
	// The engine settles this from the model's window and this row is the
	// person overruling that (internal/session's promptprofile.go); `auto`, the
	// default, hands over the word that decides nothing and leaves the window
	// to answer exactly as it did before the row existed. PROFILE-ONLY, for the
	// reply-guard reason above: a repository that could set it would decide, by
	// being cloned, that a visitor's conversation loses its saved memories and
	// half its tool list.
	cfg.PromptProfile = config.PromptProfileAt(profileDir)
	// And who decides when that check comes back with nothing. PROFILE-ONLY for
	// the reason the audit row above it is: a repository that could set this
	// would be deciding, by being cloned, that a visitor's work gets accepted by
	// a model rather than by the visitor.
	cfg.TaskSettle = config.TaskSettleAt(profileDir)
	cfg.TaskRepairRounds = config.TaskRepairRoundsAt(profileDir)
	// How much of the work that leaves this conversation happens at once: the
	// person's own cap, and the two readings of this machine that hold the next
	// task back whatever the cap says (internal/session's task_pressure.go).
	cfg.TaskParallel = config.TaskParallelAt(profileDir)
	cfg.TaskMaxLoad = config.TaskMaxLoadAt(profileDir)
	cfg.TaskMinFreeMB = config.TaskMinFreeMBAt(profileDir)
	cfg.SearchProvider, cfg.SearchFetcher = v3Search(profileDir)
	// The accounts manager is NOT resolved here, and it is the one row in this
	// function that is not. It is a handle rather than a setting: one per
	// process, built at the door and assigned by the launch
	// (chatv3_process.go's [v3Process.Conns]), because two managers on one store
	// are two caches with no way to tell each other that a token has moved.
	// HOW THIS SESSION CHOOSES AMONG THE ENDPOINTS SERVING ITS MODEL IS NOT SET
	// HERE, and that absence is the point. This door used to read the routing row
	// and write it onto the config, which the session then handed to every client
	// it built as an answer of its own ([provider.StaticRouting]) — and an answer
	// handed down WINS over the row this process installs, which is what a caller
	// holding a row this process did not install needs it to do. So the
	// conversation's clients were pinned to the word that was on disk at
	// launch: a person who cycled `routing` in the settings panel watched the row
	// change, watched the `lane` row go on explaining itself in the old word, and
	// got the old routing on every request until they relaunched (issue #1022).
	//
	// The row is installed process-wide one line below, where every client that
	// was handed nothing reads it — including this session's, now — and the panel
	// re-installs it the moment it is written (internal/config's
	// InstallRoutingRow). A caller that really does have a row of its own still
	// hands one down and still wins; this door does not, because the row it would
	// hand down is the very row it is installing.
	// AND WHICH MACHINE BEHIND THAT MODEL, which is the row beside routing and a
	// different question: routing says what a request PREFERS, and this says
	// which endpoint it actually goes to (internal/config's lane keys). The
	// shared resolution lives in internal/config so every door gets the same
	// answer, and it is handed to a process-wide knob rather than onto the config
	// because the picker rewrites it while the program is running
	// (internal/provider's lanepin.go says why that is not a Config field).
	//
	// IT IS THE RESOLVER'S ENTRANCE AND NOT A PERSON'S. This function reads the
	// row and hands the answer down, and it runs again for every automation run
	// the clock assembles a config for — so it must not be able to forget what
	// the wire said about the row while nobody has touched it. A person's own act goes to [provider.RepinLane]
	// (internal/tui3's laneRowChanged), which forgets unconditionally.
	// The speed guard travels with the pin because the adjacent rows are one
	// routing posture and two readers of that posture would drift.
	config.InstallLaneRows(profileDir)
	return cfg, nil
}

// v3Search resolves the web-search pair this session's belt calls through: the
// four settings rows in, [search.Live]'s answer out.
//
// IT RETURNS NO ERROR, and that is a statement about the layer rather than an
// omission. The built registry keeps the capability present, and auto always
// reaches a plug that needs no key. An explicit keyed search pin stays present
// when its key is absent so its call can name that exact missing-key failure.
// A pin naming a plug this build does not have falls through to auto rather
// than taking search away. The only outcome this call cannot produce is a
// launch that fails because of search, which is the correct set of outcomes
// for an accessory.
//
// A nil half is therefore not an error either. It is what a build whose
// registry is empty answers, and internal/session reads it as "leave that tool
// off the belt" — a model that is never told about a tool it cannot reach.
//
// THE ROWS DO NOT GO THROUGH THE PROJECT LAYER, unlike the governance rows
// above, and the keys are why: a repository that could answer search.exaKey
// could spend a visitor's Exa credit, and one that could answer search.provider
// could redirect where a visitor's questions are sent by being cloned. Both are
// the PERSON's rows in the sense internal/config's allowlist means it, so they
// resolve profile-and-environment only.
func v3Search(profileDir string) (search.Provider, search.Fetcher) {
	return search.Live(func() search.Options {
		return config.SearchOptionsAt(profileDir)
	})
}

// v3SearchStatus is absent with the search hand and otherwise resolves from
// the same options function on every deck read. The near surface therefore
// never advertises a capability its session does not carry, and it names the
// plug the next search will use rather than the one launch happened to choose.
func v3SearchStatus(provider search.Provider, profileDir string) func() string {
	if provider == nil {
		return nil
	}
	return func() string {
		return search.Status(config.SearchOptionsAt(profileDir))
	}
}

// v3Connect resolves the person's connected accounts (internal/connect): the
// Google and Slack applications in, a manager out — or NIL, which is the whole
// feature absent.
//
// The nil is still the law v3Search's nil half states — a belt must never carry
// a tool whose one answer is "not configured", and [session.Config] says why
// that is strictly worse for a model than never being told. What has changed is
// how rarely it applies: the catalog opens a few hundred accounts on a key the
// person already holds, so there is something to connect on every machine, and
// only a store this process cannot open at all leaves nothing.
//
// IN PRACTICE BOTH ARE ALWAYS THERE now, because a build ships applications of
// its own as the last rung under the environment and the sheet (internal/config's
// connect_defaults.go), so the guards below stand for the case where somebody
// has emptied one rather than the ordinary one. Having an application is not
// having an account: connecting still opens the service in the person's browser
// and waits for them to approve it, and the tools say "not connected" until they
// do.
//
// IT RETURNS NO ERROR for the reason v3Search does not. Accounts are an
// accessory; a garbled row, a half-filled pair, a manager that cannot open its
// own store are all reasons to have no connect tools, and none of them is a
// reason a person cannot open a conversation.
//
// THE ROWS DO NOT GO THROUGH THE PROJECT LAYER, like the search keys and unlike
// the governance rows above: a repository that could answer google_oauth_client
// could ask a visitor to connect their mail to an application the repository
// chose, by being cloned. Whose application asks for a person's account is the
// person's row in exactly the sense internal/config's allowlist means it.
// EACH APPLICATION ROW GATES ITS OWN SERVICE AND NOTHING ELSE. Most of what can
// be connected is opened by a key the person already holds and needs nothing
// registered anywhere, so a machine with neither browser application still has
// a manager and still has the accounts list — it simply has neither service.
func v3Connect(profileDir string) *connect.Manager {
	credentials := map[string]connect.ClientCredential{}
	if id, secret := config.GoogleOAuthClientAt(profileDir); strings.TrimSpace(id) != "" && strings.TrimSpace(secret) != "" {
		credentials["google"] = connect.ClientCredential{ID: id, Secret: secret}
	}
	if id := config.SlackOAuthClientAt(profileDir); strings.TrimSpace(id) != "" {
		credentials["slack"] = connect.ClientCredential{ID: id, Public: true}
	}
	manager, err := connect.NewManager(profileDir, credentials)
	if err != nil {
		return nil
	}
	return manager
}

// v3SurfacePosture is the tool-approval posture this LAUNCH hands the surface,
// and it exists because the flag and the profile row open the same gate by two
// different means. An empty answer is deliberate: on every ordinary launch it
// leaves the surface reading the profile live, while --yolo's forced allow has
// no row there to read.
func v3SurfacePosture(yolo bool) string {
	if yolo {
		return string(approval.ActionAllow)
	}
	return ""
}

// v3Policy builds the tool gate from the two approval rows.
//
// The mode row cannot fail — an unreadable value there reads as the strictest
// of the three (internal/config), which is the one direction a garbled setting
// may be wrong in. The exceptions row can, and does, loudly.
//
// --yolo replaces the DEFAULT and nothing else. A person who wrote
// `bash:prompt` still gets asked about bash: the flag is "stop asking me about
// the ordinary things", not "forget what I wrote down".
func v3Policy(workspace, profileDir string, yolo bool) (*approval.Policy, error) {
	if yolo {
		return v3PolicyMode(workspace, profileDir, string(approval.ActionAllow))
	}
	return v3PolicyMode(workspace, profileDir, "")
}

// v3PolicyMode is [v3Policy] with the blanket answer named outright: mode
// replaces the `tools.approvalMode` row for this build and "" reads the row.
// It is the one function every posture goes through — the flag's forced allow,
// a conversation's own wheel (chatv3_approval.go's [v3ApprovalGate]) and the
// ordinary launch — so the exceptions, the shell rules and the floor cannot
// differ between them.
func v3PolicyMode(workspace, profileDir, mode string) (*approval.Policy, error) {
	rows, err := v3ApprovalRowsAt(workspace, profileDir, mode, false)
	if err != nil {
		return nil, err
	}
	return rows.build()
}

// v3ApprovalRows is the complete input to an immutable policy. Comparing the
// resolved rows lets a live gate reuse its policy without duplicating the
// configuration reader's file freshness rules.
type v3ApprovalRows struct {
	mode, tools, bash string
	profileReadError  string
}

func v3ApprovalRowsAt(workspace, profileDir, mode string, headless bool) (rows v3ApprovalRows, err error) {
	project, err := config.LoadProjectConfig(workspace)
	if err != nil {
		return v3ApprovalRows{}, err
	}
	// Every profile read participates, including a read that fails after an
	// earlier row succeeded. Returning an ordinary error would retain an old,
	// potentially permissive live policy instead of asking the person.
	defer func() {
		var pathErr *os.PathError
		if errors.As(err, &pathErr) && pathErr.Path == config.BudgetConfigPath(profileDir) {
			rows, err = v3ApprovalRows{profileReadError: err.Error()}, nil
		}
	}()
	if _, err := config.ReadProfileApprovalConfig(profileDir); err != nil {
		return v3ApprovalRows{}, err
	}
	if mode == "" {
		if headless {
			mode, err = config.HeadlessToolApprovalModeAt(workspace, profileDir)
		} else {
			mode, err = project.ResolveString(profileDir, config.KeyToolApprovalMode)
		}
		if err != nil {
			return v3ApprovalRows{}, err
		}
	}
	tools, err := project.ResolveString(profileDir, config.KeyToolApprovals)
	if err != nil {
		return v3ApprovalRows{}, err
	}
	bash, err := project.ResolveString(profileDir, config.KeyBashApprovals)
	if err != nil {
		return v3ApprovalRows{}, err
	}
	return v3ApprovalRows{mode: mode, tools: tools, bash: bash}, nil
}

func (rows v3ApprovalRows) build() (*approval.Policy, error) {
	if rows.profileReadError != "" {
		return &approval.Policy{ProfileReadError: rows.profileReadError}, nil
	}
	raw := map[string]any{"default": rows.mode}
	// The repository's exceptions REPLACE the person's, whole (internal/config
	// states the merge law): a rule set assembled from two files is a rule set
	// neither file's reader could read back. Whichever file wins, what it says
	// lands ON TOP of the built-in floor below rather than instead of it.
	exceptions := v3BuiltinApprovals()
	if rows.tools != "" {
		tools, err := config.ParseToolApprovals(rows.tools)
		if err != nil {
			return nil, fmt.Errorf("settings row %q: %w", config.KeyToolApprovals, err)
		}
		for tool, action := range tools {
			exceptions[tool] = action
		}
	}
	raw["tools"] = exceptions
	// The bash rules, which are the row a remembered "always, this command"
	// lands in (internal/config's approvalmemory.go). They are ORDERED and the
	// order is honoured as written: first match wins, so a deny somebody put at
	// the top of the row outranks anything a consent card appended below it.
	// --yolo does not touch them either — the flag replaces the default and
	// nothing a person wrote down.
	if rows.bash != "" {
		parsed, err := config.ParseBashApprovals(rows.bash)
		if err != nil {
			return nil, fmt.Errorf("settings row %q: %w", config.KeyBashApprovals, err)
		}
		patterns := make([]any, 0, len(parsed))
		for _, rule := range parsed {
			patterns = append(patterns, map[string]any{"match": rule.Match, "approval": rule.Action})
		}
		raw["bash.patterns"] = patterns
	}
	policy, err := approval.Load(raw)
	if err != nil {
		return nil, fmt.Errorf("settings rows %q, %q and %q: %w",
			config.KeyToolApprovalMode, config.KeyToolApprovals, config.KeyBashApprovals, err)
	}
	return &policy, nil
}

// v3BuiltinApprovals is the floor under the tool exceptions row: the handful of
// calls this gate has never had a reason to ask about, seeded fresh on every
// build so that what a person wrote lands ON TOP of them and not INSTEAD of
// them.
//
// It used to be an either/or — these built-ins while the row was empty, the
// person's rules the moment it was not — and that shape is what produced the
// complaint this floor answers. The consent card's "always" writes ONE entry
// into that row (internal/config's approvalmemory.go), so the first time
// anybody pressed always on any tool at all, the seed vanished and read, grep,
// find, ls and jobs fell back to the blanket mode, which asks. The keystroke
// whose whole purpose is to be asked less permanently increased the asking, in
// a place nothing on screen connected to the key that had been pressed.
//
// A RULE THE PERSON WROTE STILL WINS FOR THE TOOL IT NAMES. `read:prompt` is a
// sentence about read and it is honoured, because a floor nobody could stand on
// would be a rule set with a part that cannot be turned off. What the floor
// takes away is only the silent part: a rule written about one tool now says
// nothing whatsoever about any other.
//
// WHAT IS ON IT, and why each entry is safe to leave off the asking:
//
//   - Pure reads of this machine — read, grep, find, ls. Nothing here changes a
//     file, so the blanket mode's prompt is free to land where it matters, on
//     bash, edit and write.
//
//   - jobs, whose list and output are reads of processes the person already
//     started. Its kill is not on the floor: it inherits the blanket mode,
//     which asks.
//
//   - The agent's own bookkeeping — track and recall, which write to and read
//     from the working state it keeps for itself (internal/session's state.go),
//     and remember and forget, which keep or forget one of the person's memory
//     lines (memory.go). A memory change is never silent: the conversation says
//     `remembered · …` or `forgot · …`, and the Memories tab forgets or puts
//     back any line. Asking somebody to approve a change they are shown and can
//     take back in one keystroke is asking about the wrong thing.
//
//   - manual, which reads pages compiled into this binary and touches no disk
//     at all (internal/session's tools_manual.go). A person who asks "what can
//     you do" and is answered with a permission prompt has been asked to
//     approve the program looking up its own documentation.
//
//   - settings, which reads the person's own settings rows back through the
//     registry (internal/session's tools_settings.go). It is manual's shape one
//     file over — the answer to "what is my daily budget" is a lookup, and the
//     credential rows read MASKED through the registry itself
//     ([config.Setting.Secret]), so there is nothing here a prompt would be
//     protecting.
//
//   - The team verbs that stay inside a team the person made
//     (internal/session's tools_team.go): a manager reading its members'
//     states and pages, sending them a line, ending a member's turn the way
//     the person's own Stop does, and a member posting to its room. Every one
//     of them is a line in the team's own traffic log, which the person watches
//     on the manager's rail, and none of them reaches a permission prompt.
//
// team_start is DELIBERATELY NOT HERE. It opens a new conversation that spends
// money for as long as it runs, so the blanket mode asks, the way it asks about
// propose_task.
//
// commit is DELIBERATELY NOT HERE, and it is the interesting half of the split.
// It is the fifth hand on the same working state, but it is the only one that
// declares a tracked subgoal FINISHED, and a session that can mark its own work
// done without anyone being asked is a session that can talk itself into done.
// The other four record and read; this one makes a claim.
//
// change_setting is NOT HERE FOR THE SAME REASON, harder. Changing somebody's
// configuration is an ACT and not a read — it writes a file that outlives the
// conversation — so it goes to the person like edit and write do. That split is
// the whole argument for the settings pair being two tools rather than one with
// actions: a rule is written per tool name, so one tool could not have been
// free to read and asked about to write.
//
// Nothing on this list acts outside this machine, so internal/approval's floor
// under calls made in the person's name is untouched by every entry on it — as
// is the critical-command table, which sits above this whole row either way.
func v3BuiltinApprovals() map[string]any {
	return map[string]any{
		"read": "allow", "grep": "allow", "find": "allow", "ls": "allow",
		"jobs":     "allow",
		"remember": "allow", "forget": "allow", "track": "allow", "recall": "allow",
		"manual": "allow", "settings": "allow",
		"team_status": "allow", "team_read": "allow", "team_send": "allow",
		"team_stop": "allow", "team_post": "allow",
		// A manager deciding or sending up a packet waiting on it, and bringing
		// the person its closing report: each is a line in the team's own
		// record, and none spends or starts anything.
		"team_decide": "allow", "team_escalate": "allow", "team_close_report": "allow",
		// A conflict raised to the manager above the parties: a packet and a
		// line of Traffic, and nothing spent or started.
		"team_raise": "allow",
		// A factory stage's report and its proposal of stages (internal/session's
		// tools_stage.go): each hands words to the runner waiting in code, and
		// neither changes, posts or starts anything. They are on a stage's belt
		// alone, and a stage has nobody at its keyboard to ask, so without this
		// line the headless floor refused every report and no stage could end.
		"stage_result": "allow", "plan_edit": "allow",
		// The manager's reply to a step's question (tools_factory_answer.go):
		// words handed to the runner waiting in code, on a turn nobody is at
		// the keyboard of.
		"factory_answer": "allow",
		// THE MANAGER'S PEN ON ITS OWN ITEM'S STEPS (tools_factory_run.go): it
		// changes the stages of the one item the conversation manages, within
		// the bounds factory.Edit holds in code, and posts, starts and spends
		// nothing. Its shaping turns are headless, so without this line every
		// edit met `needs approval but no resolver is attached: default` and the
		// recipe stood by accident.
		"factory_run": "allow",
		// THE MANAGER'S START (tools_factory_start.go): the run button on the
		// item's page, pressed from the manager's chat when the person asks; it
		// launches, resumes or continues the one item the conversation manages,
		// within the floor's own rules.
		"factory_start": "allow",
		// A manager taking back a team that never held anyone, which the
		// person declined in its own conversation: one record nobody used is
		// forgotten, and nothing is started, stopped or spent. A team that
		// was used is refused by the store ([teams.Dissolve]), whatever this
		// row says.
		"team_dissolve": "allow",
	}
}

// v3Memory opens the person's brain for this conversation, or hands over
// nothing.
//
// NOTHING IS A COMPLETE ANSWER HERE, and it is two different answers spelled
// the same way on purpose. Memory turned off in the settings opens no store at
// all, which is what makes "no block and no calls" a property of the wiring
// rather than a branch in every caller (internal/session's memory.go states the
// law). A store that would not open — a locked file, a disk with nothing left,
// a database an older build wrote — is the SAME answer, said once on stderr:
// a person who typed `codeaf` wanted a conversation, and refusing them one
// because a memory file is unhappy would be losing the whole product to the
// least of its parts.
//
// It is the same graph.db every other surface in this binary opens
// ([defaultChatDB]). Memories are the person's, not a conversation's, and a
// second file beside it would be a second set of them that nothing else could
// read.
//
// A FIRST RUN IS NOT ONE OF THOSE UNHAPPY CASES, and for a long time it was.
// The state root does not exist on a machine that has never run codeaf, SQLite
// creates database files but never the directories holding them, and the
// resulting complaint came back spelled `out of memory (14)` — so the first
// launch on a new machine reported a memory problem it did not have and then
// held nothing, for as long as that person kept using it. The directory is now
// made by [store.Open] itself, which is the one door every caller goes through,
// and what reaches the line below is only ever a real reason: it names the file
// and says what the disk said about it.
// v3SearchStore opens the conversation index with the memory row OFF. It is
// the same file the memory store is ([defaultChatDB]), opened when the memory
// store was not — and its failures are the same non-fatal shape: a person who
// wanted a conversation gets one, and the search verb answers what a missing
// index honestly answers.
func v3SearchStore(profileDir string) *store.Store {
	brain, err := store.Open(defaultChatDB())
	if err != nil {
		fmt.Fprintln(os.Stderr, "conversation search is off for this session: "+err.Error())
		return nil
	}
	return brain
}

// v3ProjectKey mints the key this launch's workspace can prove it is. It is
// the origin remote's normalized identity when the workspace is a git
// repository with one, and the canonical path's hash when there is none —
// never a guess. An error or an empty workspace answers "", and a session
// carrying "" quarantines its project writes rather than attributing them
// (internal/gitidentity's project.go states the rule; internal/session's
// memory.go states where the empty key lands).
func v3ProjectKey(workspace string) string {
	key, err := gitidentity.ProjectKey(workspace)
	if err != nil || strings.TrimSpace(key) == "" {
		return ""
	}
	return key
}

// v3Memory opens the memory store, WHATEVER THE MEMORY ROW SAYS. The row
// governs only what the noticing pass keeps on the person's behalf, and it is
// read live by the conversation (internal/session's memory.go): lines the
// person kept hold whether it is on or off, the memory place can read and
// change them either way, and a long-lived engine follows a change to the row
// without being restarted. A store that will not open is the one way memory is
// absent, and that is said on stderr.
func v3Memory(profileDir string) *store.Store {
	brain, err := store.Open(defaultChatDB())
	if err != nil {
		fmt.Fprintln(os.Stderr, "memory is unavailable in this session: "+err.Error())
		return nil
	}
	if cell.Available() {
		brain.SetMemoryLedger(session.CellMemories)
	}
	return brain
}

// ── the two reading seams the places open onto ──────────────────────────────

// v3Brain is the store as the memory place asks for it.
//
// IT IS AN ADAPTER AND NOT AN INTERFACE THE STORE HAPPENS TO FIT, for one
// reason: the surface's seam is named in the surface's own words — `Snapshot`,
// `ChangedSince` — while the store prefixes every one of its methods with the
// table they read, because it holds a dozen tables and `Snapshot` alone would
// mean nothing there. Two vocabularies, one join, written down here where the
// door already owns every other translation between the two packages.
//
// A NIL STORE STAYS NIL THROUGH IT. A store that would not open is no store,
// and a typed nil inside a non-nil interface would turn "the place is absent"
// into "the place panics the first time somebody presses alt+8" — the classic
// shape of that bug, refused here rather than guarded against in the surface.
type v3Brain struct{ brain *store.Store }

func (s v3Brain) Snapshot(limit int) (store.MemoryShelves, error) {
	return s.brain.MemorySnapshot(limit)
}

func (s v3Brain) ChangedSince(t time.Time) (int, int, error) {
	return s.brain.MemoryChangedSince(t)
}

func (s v3Brain) UpdateMemory(id, text string) error {
	return s.brain.UpdateMemory(id, text)
}

func (s v3Brain) ForgetMemory(id string) error  { return s.brain.ForgetMemory(id) }
func (s v3Brain) RestoreMemory(id string) error { return s.brain.RestoreMemory(id) }

func (s v3Brain) MemoryProvenance(id string) (string, string, time.Time, error) {
	return s.brain.MemoryProvenance(id)
}

// v3MemorySeam is the adapter, or nothing at all for a store that was never
// opened — see [v3Brain] for why the nil has to be answered here.
func v3MemorySeam(brain *store.Store) tui3.MemoryStore {
	if brain == nil {
		return nil
	}
	return v3Brain{brain: brain}
}

// v3RolesSource is the closure internal/roles reads its ladder through: the four
// tier models under [roles.TierKey], the per-role pins under [roles.PinKey].
//
// IT IS LIVE. It used to be resolved once, at boot, on the argument that two
// calls in one conversation must not answer to different settings — and the
// crew is what makes that argument the wrong way round. A person who types
// `/crew pin planner …` because the planner is not thinking hard enough has said something
// about the run they are about to start, not about the next launch, and a source
// that made them restart to be heard would be a knob that does nothing on the
// surface that offers it.
//
// The snapshot follows this process's settings generation and the on-disk
// stamps of both profile and project configuration. A settings panel in another
// window is a different process from the engine: its writes must reach the next
// auxiliary call without restarting the engine. Unchanged files cost stats,
// never repeated reads or JSON decoding; internal/config memoizes their values.
func v3RolesSource(workspace, profileDir string) (func(string) (string, bool), error) {
	crew := &v3Crew{workspace: workspace, profileDir: profileDir}
	// The first build happens HERE rather than lazily, so a malformed pins row
	// still stops the launch with the row named — which is the law this whole
	// governance block keeps (applyV3Governance says why).
	if err := crew.rebuild(); err != nil {
		return nil, err
	}
	return crew.read, nil
}

// v3Crew is the live reading of the four tier rows and the pins.
type v3Crew struct {
	workspace, profileDir string

	mu sync.RWMutex
	// generation is [config.SettingsGeneration] as of the snapshot below. Zero
	// is impossible after the first build, so there is no "never read" state to
	// spell separately.
	generation uint64
	files      [2]crewConfigStamp
	values     map[string]string
	// low is [config.CreditsLowAt] as of the snapshot. It is compared on every
	// read beside the generation because the balance record is written by
	// WHICHEVER PROCESS READ IT (#1439): on the ordinary launch the surface
	// reads the key and the engine runs the crew, so a low record the surface
	// wrote never moves the engine's own generation counter, and the crew it
	// built before the record existed would go on seating the paid table. The
	// check is a stat through the record's memo, not a file read.
	low bool
	// err is the last rebuild's refusal, KEPT AND SERVED rather than swallowed.
	// A pins row somebody has just broken must not silently un-pin every role —
	// that would move work onto another model without saying so — so a failed
	// rebuild keeps serving the last good snapshot and the failure is what the
	// next settings read will show them.
	err error
}

// read is [roles.Source]: unchanged configuration costs file metadata checks
// and a read lock, never repeated file reads or JSON decoding.
func (c *v3Crew) read(key string) (string, bool) {
	if generation, low, files := c.stampNow(); config.SettingsGeneration() != generation || config.CreditsLowAt(c.profileDir) != low || c.configFilesNow() != files {
		// A rebuild that fails leaves the old snapshot in place, so the error is
		// dropped here on purpose: this is the resolution path, and the honest
		// answer to "which model" is the last one that parsed.
		_ = c.rebuild()
	}
	c.mu.RLock()
	defer c.mu.RUnlock()
	value, ok := c.values[key]
	if !ok || strings.TrimSpace(value) == "" {
		return "", false
	}
	return value, true
}

// stampNow is what the snapshot was built against: the settings generation and
// whether the balance record read low.
func (c *v3Crew) stampNow() (uint64, bool, [2]crewConfigStamp) {
	c.mu.RLock()
	defer c.mu.RUnlock()
	return c.generation, c.low, c.files
}

// rebuild reads the rows and replaces the snapshot. It reads BEFORE taking the
// write lock so a slow disk cannot hold a concurrent turn's resolution.
func (c *v3Crew) rebuild() error {
	generation := config.SettingsGeneration()
	files := c.configFilesNow()
	low := config.CreditsLowAt(c.profileDir)
	values, err := c.snapshot()
	c.mu.Lock()
	defer c.mu.Unlock()
	// The generation moves either way. A rebuild that refused must not be
	// retried on every single call — that would put a file read back on the hot
	// path, which is the thing this seam exists to avoid — so the refusal is
	// recorded and the next write is what triggers another attempt.
	c.generation, c.low, c.files, c.err = generation, low, files, err
	if err != nil {
		return err
	}
	c.values = values
	return nil
}

// snapshot is one reading of every key the ladder can ask for.
func (c *v3Crew) snapshot() (map[string]string, error) {
	// THE TWO PROJECT-LAYER TIERS. A repository may say which model does the
	// bulk work and which one checks it (config.ProjectKeys), because that is a
	// fact about the work in it.
	low, err := config.ProjectStringAt(c.workspace, c.profileDir, config.KeyTierLowModel)
	if err != nil {
		return nil, err
	}
	high, err := config.ProjectStringAt(c.workspace, c.profileDir, config.KeyTierHighModel)
	if err != nil {
		return nil, err
	}
	// AND THE THREE READ FROM THE PROFILE ALONE. [config.ProjectKeys] carries
	// none of these rows, so asking the project layer for one is an error rather
	// than a fall-through. The worker tier: it is the seat that spends most of
	// what a task costs, and a repository that could point it at a model would
	// be spending a visitor's credit on the work it asked for.
	//
	// The reflex tier: the two calls that ride it are made TWICE EVERY TURN
	// (internal/reflex), so a reflex resolving to the conversation's model is not
	// thrift misconfigured, it is the most expensive model in the build answering
	// the cheapest question in it. The mastermind tier: it plans adaptive runs
	// and designs saved harnesses, and a repository that could point it at a
	// model would be spending a visitor's credit on the run it asked for.
	// A CHECKER NO PROJECT NAMED IS THE CREW'S: its pin, or the router's
	// standing pick ([config.TierModelAt]) — never an empty row that would
	// fall to the conversation's model.
	if strings.TrimSpace(high) == "" {
		high = config.TierModelAt(c.profileDir, config.ModelTierHigh)
	}
	values := map[string]string{
		roles.TierKey(roles.TierReflex):     config.TierModelAt(c.profileDir, config.ModelTierReflex),
		roles.TierKey(roles.TierMastermind): config.TierModelAt(c.profileDir, config.ModelTierMastermind),
		roles.TierKey(roles.TierWorker):     config.TierModelAt(c.profileDir, config.ModelTierWorker),
		roles.TierKey(roles.TierLow):        low,
		roles.TierKey(roles.TierHigh):       high,
	}
	text, err := config.ProjectStringAt(c.workspace, c.profileDir, config.KeyModelRoles)
	if err != nil {
		return nil, err
	}
	// The pins replace wholesale for the reason the approvals do, one line up.
	if text != "" {
		pins, err := config.ParseModelRoles(text)
		if err != nil {
			return nil, fmt.Errorf("settings row %q: %w", config.KeyModelRoles, err)
		}
		for role, model := range pins {
			values[roles.PinKey(roles.Role(role))] = model
		}
	}
	// THE PAGE AI's DEFAULT IS ANSWERED, NEVER WRITTEN ([config.InsightDefault]):
	// it rides the snapshot while its provider is connected and the model is
	// allowed, below every pin, and a one-model profile drops it with the pins.
	if send, ok := config.InsightDefaultAt(c.profileDir); ok {
		values[roles.DefaultKey(roles.RoleInsight)] = send
	}
	return v3SettleOneModel(values, c.profileDir), nil
}

// v3SettleOneModel answers every text tier with the saved one model while the
// profile's task models are in one-model mode, and drops the text pins.
//
// ONE MODEL MEANS ONE MODEL AT EVERY RUNG, HERE AS UNDER `--one-model`. The
// flag withholds these rows and lets each errand fall to the conversation's
// model; the saved setting names its model, so the rows answer that model
// instead, and the crew-only callers that pass an empty floor (the mark's
// reader, the brief's writer) reach it too rather than a tier nobody chose.
// The snapshot is rebuilt whenever the settings move, so a mode switched
// mid-process reaches the next errand. Media pins stay: a media slot is
// capability-qualified, exactly as under the flag. A one model that cannot be
// used right now answers no tier at all, never another model.
func v3SettleOneModel(values map[string]string, profileDir string) map[string]string {
	send, one, err := factoryTaskOneModel(profileDir, modelsource.Set{})
	if !one {
		return values
	}
	media := map[string]bool{}
	for _, role := range v3MediaPin {
		media[roles.PinKey(role)] = true
	}
	settled := map[string]string{}
	for key, model := range values {
		if media[key] {
			settled[key] = model
		}
	}
	if err != nil {
		return settled
	}
	for _, tier := range roles.Tiers {
		settled[roles.TierKey(tier)] = send
	}
	return settled
}

// v3Catalog is the ONE question this door asks a model catalog, and it is a
// question that never waits. It is an interface rather than *catalog.Catalog so
// a test can answer it with rows of its own — no cache file, no fetch, no
// fifteen-second timeout in a unit test.
type v3Catalog interface {
	// ModelsNow is the catalog's rows if it already has them, and nil while a
	// lazily loaded one is still warming.
	ModelsNow() []catalog.Model
}

// v3Models is the catalog as the v3 surface wants it: id, window, the three
// per-token prices and the arena score, THE WHOLE LIST, in the catalog's own
// order.
//
// THE DOOR STOPS STARVING THE PICKERS (docs/MULTIMODAL.md Decision 6). This used
// to drop every row that answered in anything but text, which read as a
// reasonable narrowing and was in fact the surface's supply: the settings
// sheet's drawing row opens a picker over THIS list, so a list with no drawing
// model in it is a picker that cannot be answered — and the on-disk cache,
// written from here, carried the same hole to the next launch.
//
// So the filtering moves to where the question is asked. Every list that wants
// chat models applies the chat law itself, at the moment it is drawn:
// [v3TaskModels] here, [app.modelList] and each slot's own predicate in
// internal/tui3 (models.go's modelFilter). One list arrives; each reader asks
// its own question of it.
//
// The prices ride along because the surface has to price something the session
// cannot: what a turn's prompt-cache reads saved, which is cached tokens times
// the gap between the prompt price and the cache-read price (internal/tui3's
// savings note). They come off the /models fetch that already happens, so
// carrying them costs one more field per row in a file that is already written.
//
// Nil while the catalog is warming — which is not a failure but the picker's
// cue to read ~/.codeaf/v3/models.json and then its built-ins (internal/tui3
// models.go states that order and applies it).
func v3Models(models v3Catalog) []tui3.Model {
	if models == nil {
		return nil
	}
	rows := models.ModelsNow()
	out := make([]tui3.Model, 0, len(rows))
	for _, row := range rows {
		model := tui3.Model{
			ID:            row.ID,
			ContextLength: row.ContextLength,
			ArenaElo:      row.ArenaElo,
			Output:        row.OutputModalities,
			// What the model READS travels beside what it answers in, because
			// the surface asks both questions and can only answer them from what
			// it was handed: the chat law needs text IN (a transcription model
			// answers in text and takes sound), and the vision slot needs image
			// in. A row that arrived with only its output side would be filtered
			// on half the facts and would look, from the picker, exactly like a
			// row that had been checked.
			Input: row.InputModalities,
			// The published answer to "may this call carry a reasoning knob",
			// and the only thing that lets the picker offer ctrl+t on a row.
			// Either spelling counts: a model that takes `reasoning` can be
			// asked to think, and one that takes `reasoning_effort` can be told
			// how hard — the surface offers levels on both and lets the adapter
			// resolve what actually travels (catalog's ReasoningWord states the
			// same three states in words).
			Reasoning: row.Reasons() || row.ReasoningLevels(),
		}
		if row.Created > 0 {
			model.ListedAt = row.Created
		}
		// PriceUnknown is OpenRouter's "-1", which it uses for its own routers:
		// they charge whatever the model they pick charges, and nobody yet knows
		// what that is. Passing the parsed numbers through anyway would tell the
		// surface a router's prompt token is free and let it report a saving that
		// is not a fact (catalog.Model.PriceUnknown).
		if !row.PriceUnknown {
			model.PromptPrice = row.PromptPrice
			model.CompletionPrice = row.CompletionPrice
			model.RequestPrice = row.RequestPrice
			model.PriceKnown = true
			model.CacheReadPrice = row.CacheReadPrice
		}
		out = append(out, model)
	}
	if len(out) == 0 {
		return nil
	}
	return out
}

// v3TaskModels is the list a task's `model` argument is resolved against
// (session.Config.TaskModels): the ids of every model this install can hold a
// conversation with, which is exactly the set the picker offers — a node is an
// agent with the same belt, so a model it could not talk through is not a model
// work can be handed to.
//
// It NEVER WAITS, and nil while the catalog is warming is the honest answer:
// internal/session reads that as "nobody can say" and takes the named model as
// written rather than refusing an id it has no list to check.
func v3TaskModels(models v3Catalog) func() []string {
	return func() []string {
		// THE CHAT LAW IS APPLIED HERE, not at the door. A node is an agent with
		// the same belt, so a model work can be handed to is a model somebody
		// could hold a conversation with — and since the door now carries the
		// whole catalog (Decision 6), this list is where that question gets
		// asked. It is internal/tui3's own predicate rather than a second copy
		// of it, so the picker and the task argument cannot come to disagree
		// about what a chat model is.
		rows := tui3.ChatModels(v3Models(models))
		if len(rows) == 0 {
			return nil
		}
		ids := make([]string, 0, len(rows))
		for _, row := range rows {
			if id := strings.TrimSpace(row.ID); id != "" {
				ids = append(ids, id)
			}
		}
		return ids
	}
}

// v3AnswersText is the OUTPUT half of the chat law, asked of a published
// modality list: text, and nothing but text.
//
// A row that declares nothing is KEPT, and that is this predicate's own reading
// of silence rather than a disagreement with the rest of the surface. THE ONE
// SILENCE LAW (docs/MULTIMODAL.md Decision 6) is about CAPABILITY: an
// unpublished modality list means text-in/text-out and nothing more — no
// vision, no drawing, no sound. Text is what silence means, so a silent row
// answering "yes, text" is that law stated rather than an exception to it, and
// it is what keeps a cache written before modalities travelled from emptying
// the model picker.
func v3AnswersText(outputs []string) bool {
	if len(outputs) == 0 {
		return true
	}
	// Text-out and NOTHING else: an image model that captions what it draws
	// publishes ["image","text"], and letting it through puts a drawing model
	// in a chat picker. The door's law is "a model you can talk to", and a
	// published modality list is the only honest witness to it.
	for _, modality := range outputs {
		if !strings.EqualFold(strings.TrimSpace(modality), "text") {
			return false
		}
	}
	return true
}

// v3SeesImages is the vision gate: the closure internal/session asks before it
// assembles a message with pictures in it (session.Config.SupportsImages, and
// internal/tui3's attachment tray is what makes one askable).
//
// It answers from the catalog's published `architecture.input_modalities` and
// from nothing else — no id patterns, no vendor guesses. A model that says it
// reads images reads images; anything else is a "no" this door can defend.
//
// IT NEVER WAITS, for the reason every other question this file asks a catalog
// never waits: the rows are read through [v3Catalog.ModelsNow], which is nil
// while a lazily loaded catalog is still warming. That is why it is a closure
// read per message rather than a value resolved at boot — a cold cache would
// otherwise pin "cannot see" onto a session for its whole life, and the answer
// is wanted at the moment somebody attaches a photo, which is minutes later.
//
// AND WHILE THE CATALOG IS COLD IT READS THE DISK CACHE, which never waits
// either — it is one small file internal/tui3 wrote after a fetch, and it now
// holds the whole catalog rather than the chat rows alone (Decision 6). Without
// that rung the FIRST minute of every launch answered "cannot see" for a model
// that can, so a photo attached in the first minute went as its text placeholder
// and the person was told to switch to a model with vision while already on one.
// The file is read at most once per session: it is the same rows for the whole
// warming window, and re-reading it per message would put I/O on the message
// path to learn nothing new.
// v3SupportsParameter is the catalog's answer about a model, asked first as
// named and then as the id its service is sent — the same id the adapter asks
// about, so the session's page and the adapter's body cannot disagree about
// what the model accepts.
func v3SupportsParameter(shelf *v3ModelShelf, models *catalog.Catalog) func(string, string) (bool, bool) {
	return func(model, parameter string) (bool, bool) {
		if models == nil {
			return false, false
		}
		if supported, known := models.SupportsParameter(model, parameter); known {
			return supported, known
		}
		if bare := shelf.wireModel(model); bare != "" && !strings.EqualFold(bare, model) {
			return models.SupportsParameter(bare, parameter)
		}
		return false, false
	}
}

func v3SeesImages(models v3Catalog) func(string) bool {
	var once sync.Once
	var cached []tui3.Model
	return func(model string) bool {
		model = strings.TrimSpace(model)
		if model == "" {
			return false
		}
		if models != nil {
			if rows := models.ModelsNow(); len(rows) > 0 {
				for _, row := range rows {
					if strings.EqualFold(strings.TrimSpace(row.ID), model) {
						return v3ReadsImages(row.InputModalities)
					}
				}
				// The catalog HAS answered and does not carry this id — a
				// hand-typed slug, a model this router never listed. That is a
				// no on the same terms as an unpublished modality.
				return false
			}
		}
		once.Do(func() { cached = tui3.CachedModels() })
		for _, row := range cached {
			if strings.EqualFold(strings.TrimSpace(row.ID), model) {
				return v3ReadsImages(row.Input)
			}
		}
		return false
	}
}

// v3ReadsImages is the modality test itself.
//
// SILENCE IS NO, and that is THE ONE SILENCE LAW rather than this door's local
// opinion: an unpublished modality list means text-in/text-out and nothing more
// (docs/MULTIMODAL.md Decision 6). A media capability is never assumed, only
// published. internal/tui3's seesImages reads the same silence the same way, so
// the list a person picks a vision model out of and the gate that decides
// whether a photo travels cannot disagree about one row.
//
// The cost of the law falling this way is stated plainly: a message assembled
// with a base64 photo in it, sent to a model that cannot read one, comes back as
// a provider error about a content part, while an unknown modality is a refusal
// the person can act on ("switch to a model with vision").
func v3ReadsImages(inputs []string) bool {
	for _, modality := range inputs {
		if strings.EqualFold(strings.TrimSpace(modality), "image") {
			return true
		}
	}
	return false
}

// v3NearestModels is the last resort of the endpoint-refusal chain: when the
// person has written no models.fallbacks row, where should a turn go that
// nothing serving its model would accept?
//
// It answers from the catalog's own rows and only for a model the catalog knows
// (internal/catalog's NearestModels states what "nearest" is checked against),
// and it NEVER WAITS, for the reason [v3SeesImages] never does — this is asked
// on the request path, by an adapter that has just been refused, with somebody
// watching the turn. A cold catalog answers nil, and the chain then ends in a
// diagnosis naming what to change rather than on a model nobody chose.
//
// TWO, and no more. The chain is bounded on its own side as well
// (internal/provider's maxFallbackModels), and both bounds say the same thing:
// past a couple of tries the honest move is to stop and let the person pick.
func v3NearestModels(models *catalog.Catalog) func(string) []string {
	return func(model string) []string { return models.NearestModels(model, 2) }
}

// v3Window fills session.Config.ContextWindow: how many tokens this session's
// model accepts, according to whatever the catalog can say WITHOUT a fetch.
//
// Zero when nobody can say — a cold cache, an id the catalog has never carried,
// a row that published no figure — and zero is the right answer to hand the
// session, which then keeps its own conservative default rather than sizing
// compaction off a guess. [warmV3Models] corrects it in place once the catalog
// resolves.
func v3Window(models v3Catalog, model string) int {
	return v3ContextWindow(v3Models(models), model)
}

// v3StartWindow is [v3Window] for the model a conversation opens on, asked of
// the conversation's own catalog first and of that model's service's rows on the
// process shelf ([v3ModelShelf.contextWindow]) when the catalog cannot say.
// chosen is the id as the person spelled it (`codex/gpt-5.5`); bare is the same
// model as its service spells it, which is how the conversation's catalog knows
// it.
//
// THE CONVERSATION'S OWN CATALOG ANSWERS FIRST because it is the fresher of the
// two wherever it can answer at all: a direct service's catalog refreshes itself
// on its own clock, while the shelf's compartment for that service is the
// surface's model cache as it stood when the profile was read. The shelf is
// here for what the catalog cannot say — Codex publishes no listing, so its
// conversation's catalog is empty, and a row remembered by an older build is
// healed only on the shelf ([config.CodexRememberedModels]).
func v3StartWindow(shelf *v3ModelShelf, models v3Catalog, chosen, bare string) int {
	if window := v3Window(models, bare); window > 0 {
		return window
	}
	return shelf.contextWindow(chosen)
}

func v3ContextWindow(models []tui3.Model, model string) int {
	model = strings.TrimSpace(model)
	for _, candidate := range models {
		if strings.EqualFold(candidate.ID, model) {
			return candidate.ContextLength
		}
	}
	return 0
}

// warmV3Models is the after-the-fact half, and it runs off the launch path
// because it WAITS: the catalog's own resolution, which on a cold cache is a
// network round-trip.
//
// It does two things when that lands. The session learns the real window of the
// model it started on, so a 1M-token model stops compacting at 128k — but only
// if the person has not already switched models, because a later choice is a
// better fact than this one. And the picker's cache is refreshed, so the NEXT
// launch on this machine opens the full list in its first frame.
//
// The cache is written only for rows that actually came off the network
// (FetchedAt is zero for the built-in fallbacks), which is what keeps a machine
// that has never reached OpenRouter from caching five hardcoded names as if
// they were the catalog.
//
// Its reads go through the catalog's never-waiting doors ([Catalog.Warmed]
// first, then [Catalog.ContextLengthNow] and [Catalog.FetchedAtNow]), so the
// only wait in the function is the context-observing one the close can end.
func warmV3Models(ctx context.Context, models *catalog.Catalog, agent *session.Agent, started string) {
	if models == nil || agent == nil {
		return
	}
	// THE CLOSE REACHES THE WAIT, and that is the point of the context here: the
	// catalog's own resolution is a network round-trip on a cold cache, and this
	// errand rides the process's start-up tracker ([v3Process.warmModels]), whose
	// context [stopPoolErrands] cancels. A process that closes ends the wait HERE
	// rather than leaving the write below to land in whatever state root happens
	// to be current when the rows finally arrive.
	if !models.Warmed(ctx) {
		return
	}
	if window := models.ContextLengthNow(started); window > 0 && agent.Model() == started {
		agent.SetContextWindow(window)
	}
	if models.FetchedAtNow().IsZero() {
		return
	}
	_ = tui3.WriteModelCache(v3Models(models))
}

// runChatV3Once is the smoke-test door: one message, plain text out, no
// terminal ownership. Everything the surface would draw as chrome goes to
// stderr and only what the model said goes to stdout, so a probe can compare
// stdout with the sentence it asked for.
func runChatV3Once(ctx context.Context, cfg session.Config, workspace, text, level string, resumed bool) (onceErr error) {
	var onceFailure error
	// The leaving road stands before session opening because opening can take
	// time, and a signal there would otherwise take the default disposition and
	// skip every defer — the whole of #471. Cancelling the turn is all the
	// leaving work needed here: the deferred agent.Close below settles the tasks
	// and checkpoint. Defers run last-in-first-out, so Close runs before this
	// road stands down and keeps the second signal live through a close that can
	// take the turn's grace plus two job rounds.
	ctx, cancel := context.WithCancel(ctx)
	defer cancel()
	var leaving atomic.Bool
	// A leaving somebody asked for is not a failure to report: a person who
	// typed kill -INT is not owed an "error: context canceled" line, and the
	// manual promises the surface the same clean status-0 exit.
	reported := func(failure error) error {
		if leaving.Load() {
			return nil
		}
		return failure
	}
	stopLeaving := leave.On(func() {
		leaving.Store(true)
		cancel()
	}, nil)
	defer stopLeaving()

	if resumed && cfg.SessionFile != "" {
		fmt.Fprintln(os.Stderr, "resumed "+cfg.SessionFile)
	}
	// THE SENTENCE NAMES THE PROJECT AND NOT THE SESSION'S OWN WORK DIRECTORY.
	// [sessionHeldElsewhereSentence] spells `codeaf engine --stop --workspace X`
	// and X has to be the directory a host is keyed by, or the command it hands
	// a person points at a host that does not exist. cfg.Workspace is not that
	// directory for an OWNED conversation — there it is the session's private
	// work folder under ~/.codeaf/v3/projects — so the launch's own workspace is
	// carried in rather than read back off the config.
	// A LIVE, STEERABLE RUN HAS SOMEONE TO ASK (chat_once_live.go's onceAsker).
	var asker *onceAsker
	if chatOnceLive.events != "" && chatOnceLive.steer != "" {
		asker = newOnceAsker(chatOnceLive.events)
		cfg.Asker = asker
	}
	agent, cfg, notice, err := openV3Agent(cfg, workspace, v3OpenSession)
	if err != nil {
		return reported(err)
	}
	agent.SetReasoning(level)
	live := chatOnceLive
	usageBefore := agent.Usage()
	var answer *lockedWriter
	// Closing settles late calls; serialize after both the agent and ledger close.
	defer func() {
		if answer == nil {
			return
		}
		failure := onceFailure
		if failure == nil {
			failure = onceErr
		}
		used := agent.Usage()
		usage := envelopeUsage{SpendUSD: used.CostUSD - usageBefore.CostUSD,
			Tokens: envelopeTokens{In: used.Input - usageBefore.Input, Out: used.Output - usageBefore.Output}}
		writeOnceEnvelope(os.Stdout, answer.String(), cfg.Model, usage, failure)
	}()
	// --events' LAST COPY WAITS FOR THE RECORD TO BE CLOSED. Closing the
	// agent and the usage ledger still writes lines — a background helper's
	// usage row lands a moment after the answer — and a copy that stopped
	// before them would leave the watcher's conversation one line short of
	// this one. Defers run last-in-first-out, so this one, registered before
	// both closes, runs after them.
	var finishEvents func()
	defer func() {
		if finishEvents != nil {
			finishEvents()
		}
	}()
	defer session.CloseUsage()
	if notice != "" {
		fmt.Fprintln(os.Stderr, notice+": "+cfg.SessionFile)
	}
	defer func() { closeV3Agent(agent) }()
	var wakes <-chan (<-chan session.Event)
	if cfg.Unattended && cfg.Budget.Set() {
		var stopWakes func()
		wakes, stopWakes = agent.WatchWakes()
		defer stopWakes()
	}

	// A DECISION TAKEN ON NOBODY'S BEHALF IS SAID OUT LOUD.
	//
	// With nobody at a keyboard the question gate applies the policy and answers
	// itself (internal/session's tools_ask.go), and DESIGN.md's HEADLESS law is
	// that this is PRINTED: `asked: <head> → 1 (default · nobody to ask)`. The
	// sentence rides the answer, and the answer rides the questions lane rather
	// than the turn's stream, because a question outlives the turn that raised
	// one — so it is read here, beside the turn, and written to stderr with the
	// tool lines rather than into the reply a caller is piping somewhere.
	questions, stopQuestions := agent.WatchQuestions()
	defer stopQuestions()
	guard.Go("chatv3/once-questions", func() {
		for event := range questions {
			if event.Kind != session.EventQuestionAnswered || event.Answer == nil {
				continue
			}
			if line := strings.TrimSpace(event.Answer.From); line != "" {
				fmt.Fprintln(os.Stderr, line)
			}
		}
	})

	var reply io.Writer = os.Stdout
	if live.json {
		answer = &lockedWriter{}
		reply = answer
	}
	var steers sync.WaitGroup
	finishSteer, finishCopy := startOnceLive(agent, cfg.SessionFile, live, asker, reply, os.Stderr, &steers)
	finishEvents = finishCopy
	defer finishSteer()

	events, err := agent.Submit(ctx, text)
	if err != nil {
		onceFailure = err
		return reported(err)
	}
	failure := drainOnceEvents(events, reply, os.Stderr)
	defer func() { steers.Wait() }()
	onceFailure = failure
	if wakes == nil {
		return reported(failure)
	}

	// ── THE RUN IS OVER WHEN IT HAS BEEN OVER FOR A WHOLE SETTLE TICK ──
	//
	// That is the wall reader's own discipline, for the same reason it gives
	// (internal/session's wallSettleTick): a landing hands its lane back a moment
	// BEFORE the note that wakes the next reply is queued, so for that instant
	// nothing is running, nothing is queued and nothing is moving. A door that
	// believed the first such reading would go home over a reply that was already
	// coming — and closing the session is what cuts it.
	settled := false
	for {
		if agent.StillGoing() {
			settled = false
		} else if settled {
			return reported(failure)
		} else {
			settled = true
		}
		select {
		case stream, open := <-wakes:
			if !open {
				// The session has closed under us; there will be no more replies.
				return reported(failure)
			}
			settled = false
			if streamFailure := drainOnceEvents(stream, reply, os.Stderr); streamFailure != nil {
				failure = streamFailure
			}
		case <-ctx.Done():
			return reported(ctx.Err())
		case <-time.After(unattendedRunSettleTick):
		}
	}
}

// unattendedRunSettleTick is how often an idle one-message door asks whether
// its run is finished. One second matches the wall reader beside it: it leaves
// the small landing-to-wake gap room to close without spinning or polling the
// session more often than the wall itself is read.
const unattendedRunSettleTick = time.Second

// drainOnceEvents is the one rendering of a headless chat turn, shared by the
// first turn, every turn the session wakes, and the connected one-message door.
// Reply text alone goes to stdout; every line the door itself says goes to
// stderr so stdout remains safe to pipe as the answer.
func drainOnceEvents(events <-chan session.Event, stdout, stderr io.Writer) error {
	// wrote tracks whether the reply has begun, so a tool line never opens the
	// output with a stray blank line and never lands mid-sentence.
	wrote := false
	newline := func() {
		if wrote {
			fmt.Fprintln(stdout)
			wrote = false
		}
	}
	var failure error
	for event := range events {
		switch event.Kind {
		case session.EventTextDelta:
			if event.Text == "" {
				continue
			}
			fmt.Fprint(stdout, event.Text)
			wrote = !strings.HasSuffix(event.Text, "\n")

		case session.EventToolBegin:
			newline()
			fmt.Fprintln(stderr, "tool: "+tui3.ToolGloss(event.Tool, event.Hint))

		case session.EventToolFailed:
			newline()
			reason := event.Hint
			if reason == "" && event.Err != nil {
				reason = event.Err.Error()
			}
			fmt.Fprintln(stderr, "tool: "+event.Tool+" failed: "+reason)

		case session.EventCompacted:
			newline()
			fmt.Fprintln(stderr, "compacted: "+event.Hint)

		case session.EventNotice:
			newline()
			fmt.Fprintln(stderr, event.Text)

		case session.EventError:
			failure = event.Err
			if failure == nil {
				failure = fmt.Errorf("session: the turn failed without a reason")
			}
		}
	}
	newline()
	return failure
}

// v3RecentSessionSlots bounds one listing. Twenty is far more than the four the
// welcome box draws and more than a person scrolls a picker past; what it is
// really for is the ceiling on the work — twenty file scans, once, on the
// keystroke that asks (internal/session's Recent bounds the reads too).
const v3RecentSessionSlots = 20

// v3RecentSessions is this project's past conversations as the surface lists
// them: the name each one gave itself, the last thing that happened in it, and
// when.
//
// It reads the transcripts rather than opening them — no lock, no replay, no
// agent — which is what lets it list the session the running window is holding
// open, and lets a second window list the first one's conversation while it is
// live (internal/session's peek.go).
//
// An unreadable bucket is an empty list and not an error. This answers a list a
// person may never look at; the one thing it must not do is stop a launch, and
// "no recent sessions" is a true sentence about a machine whose session
// directory cannot be read.
//
// BOTH SHAPES ARE LISTED, because both are on the disk: a session written
// before Decision 26 is a flat transcript and one written after it is a
// folder, and the reader takes the folder's own meta.json as the name and
// the ordering (internal/session's recentplace.go).
func v3RecentSessions(bucket string) []tui3.Session {
	found := session.RecentSessions(bucket, v3RecentSessionSlots)
	rows := make([]tui3.Session, 0, len(found))
	for _, summary := range found {
		rows = append(rows, tui3.Session{
			Title:   summary.Title,
			Opening: summary.Opening,
			Last:    summary.Last,
			File:    summary.File,
			At:      summary.At,
		})
	}
	return rows
}

// v3StateHome is codeaf's own data folder when CODEAF_HOME names one other than
// the person's default, and "" otherwise.
func v3StateHome() string {
	if strings.TrimSpace(env.Get(home.EnvVar)) == "" {
		return ""
	}
	return home.Dir()
}