chatv3_host.go

package main

import (
	"bytes"
	"context"
	"fmt"
	"io"
	"os"
	"os/exec"
	"path/filepath"
	"strings"
	"sync"
	"sync/atomic"
	"time"

	"github.com/Agent-Field/codeaf/internal/buildinfo"
	"github.com/Agent-Field/codeaf/internal/catalog"
	"github.com/Agent-Field/codeaf/internal/config"
	"github.com/Agent-Field/codeaf/internal/enginehost"
	"github.com/Agent-Field/codeaf/internal/env"
	"github.com/Agent-Field/codeaf/internal/guard"
	"github.com/Agent-Field/codeaf/internal/history"
	"github.com/Agent-Field/codeaf/internal/home"
	"github.com/Agent-Field/codeaf/internal/leave"
	"github.com/Agent-Field/codeaf/internal/remote"
	"github.com/Agent-Field/codeaf/internal/session"
	"github.com/Agent-Field/codeaf/internal/store"
	"github.com/Agent-Field/codeaf/internal/tui3"
	codeupdate "github.com/Agent-Field/codeaf/internal/update"
)

// ── `codeaf chat --host devbox` ─────────────────────────────────────────────
//
// The surface runs here and the session runs there. This file is the door: it
// parses the destination, starts the matching program over ssh, completes the
// handshake, and hands the connection to the same surface a local launch opens.
//
// THE PROMPT LAW, and it is the reason this whole path is shaped the way it is:
// EVERYTHING THAT MIGHT ASK THE PERSON A QUESTION HAPPENS BEFORE THE SURFACE
// TAKES THE SCREEN. ssh asks for a passphrase; ssh asks whether an unknown host
// key is really theirs; the engine may answer that it speaks a different version
// of the protocol. All three are plain text on a plain terminal, because they
// arrive while stderr is still the terminal's and tui3.Run has not been called.
// A TUI that came up first would either eat those questions or draw a frame over
// them, and a person would be looking at a hung screen with an invisible
// password prompt behind it.
//
// AND IT IS THE PERSON'S OWN SSH. No library, no key handling, no config file of
// ours: `ssh` is on their path, reads their ~/.ssh/config, knows their aliases
// and their agent. `--host devbox` works because `ssh devbox` already worked.
//
// WHAT THIS DOOR DOES NOT RESOLVE is everything the local door resolves and the
// far machine owns: the API key, the model catalog's credentials, the tool gate,
// the spend rail, the harness registry, the session files. Reading this
// machine's would be assembling a launch that never happens. What stays local is
// what belongs to the SURFACE — the input history, the unsent draft, the model
// picker's cached list — and that is stated once here and once in host.go.

// hostLaunch is one `--host` launch as the flag parser saw it.
type hostLaunch struct {
	// target is the flag as typed: host, user@host, host:path or host:/abs.
	target string
	// session is --session, passed through as the engine's own --session means it.
	session string
	// model and level are --model and --reasoning, carried in the hello itself
	// ([remote.Hello]'s Model and Level) so the ENGINE opens the session on them
	// rather than being switched a millisecond later — which is the difference
	// between a journal whose first line names the model the person asked for
	// and one that names whatever the machine happened to default to.
	model string
	level string
	// once is --once: one message, printed, no terminal ownership.
	once string
	// pick is `codeaf resume`: the same surface, opened on the session picker.
	pick bool
	// noCompact and yolo are refused rather than ignored — see [hostLaunch.check].
	noCompact bool
	yolo      bool
	// budget is --max-hours / --max-cost, and it is refused for yolo's reason
	// and one more: what it bounds is a goal owner that lives in the session
	// (internal/session's principal.go), and the session is on the far machine.
	// A ceiling accepted here would bound nothing at all.
	budget bool
	// restart is filled by the surface and read after this door has closed the
	// ssh child and all conversation connections.
	restart *codeupdate.Plan
}

// check refuses the flags this door cannot honour.
//
// A FLAG THAT COULD NOT TRAVEL IS A REFUSAL AND NEVER A SHRUG. --no-compact and
// --yolo are properties of the SESSION, the session is built on the far machine
// by `codeaf engine`, and the wire's hello carries neither. Accepting them and
// doing nothing would be the worst outcome available: a person types --yolo,
// watches the gate ask about every tool, and has no way to tell whether the flag
// or the gate is broken. So the door says which machine the setting lives on.
func (l hostLaunch) check() error {
	var named []string
	if l.noCompact {
		named = append(named, "--no-compact")
	}
	if l.yolo {
		named = append(named, "--yolo")
	}
	if l.budget {
		named = append(named, "--max-hours/--max-cost")
	}
	if len(named) == 0 {
		return nil
	}
	dest, _, _ := parseHostTarget(l.target)
	return fmt.Errorf("%s cannot travel over --host: the session is built on %s, so set it there — `ssh %s codeaf chat %s` — or open the settings panel on that machine",
		strings.Join(named, " and "), dest, dest, strings.Join(named, " "))
}

// parseHostTarget splits the flag scp-style: everything before the FIRST colon
// is the ssh destination, everything after it is the workspace.
//
// THE WORKSPACE IS NOT RESOLVED HERE, and that is the whole point of "as typed".
// `--host devbox:code/app` means the directory `code/app` on devbox, relative to
// whatever devbox's home is — a directory this machine has never seen and must
// not have an opinion about. Making it absolute here would resolve it against
// THIS machine's cwd and send the far end a path out of somebody else's
// filesystem. The engine resolves it, and the welcome says what it resolved to.
//
// No colon is no workspace, which the engine reads as its own home. A trailing
// colon is the same thing said out loud.
func parseHostTarget(raw string) (dest, workspace string, err error) {
	raw = strings.TrimSpace(raw)
	if raw == "" {
		return "", "", fmt.Errorf("--host needs a machine: --host devbox, --host me@devbox, or --host devbox:code/app")
	}
	at := strings.Index(raw, ":")
	if at < 0 {
		return raw, "", nil
	}
	dest = strings.TrimSpace(raw[:at])
	workspace = strings.TrimSpace(raw[at+1:])
	if dest == "" {
		return "", "", fmt.Errorf("--host %q has no machine in front of the colon", raw)
	}
	return dest, workspace, nil
}

// engineLink is a live ssh process and the client speaking to it.
//
// THE PROCESS IS A SLOT AND NOT A CONSTANT, which is the whole of what roaming
// changed here: a dropped link is redialled by [remote.Roam], every redial is a
// FRESH ssh child, and this holds whichever one is current so the door can still
// wait on its exit code and read what it said on stderr.
type engineLink struct {
	client *remote.Client
	// dest and workspace are what every spawn needs, kept because the spawning
	// now happens again on a link that died and not only once at the door.
	dest      string
	workspace string

	mu sync.Mutex
	// process is the ssh child currently carrying the connection. Closing the
	// client's pipe is what ends it; this is held so the door can wait for its
	// exit code when the handshake failed and the exit code is the only witness
	// to why.
	process *exec.Cmd
	// stderr is the tail of what ssh and the far shell said, kept so a failed
	// handshake can be diagnosed in the person's own words rather than in a
	// pipe error. Only pre-handshake prompts also reach the terminal.
	stderr *tailWriter
	// reaped says this process has already been waited on, and err is what that
	// wait answered.
	reaped bool
	err    error
}

// spawn starts one `ssh <dest> codeaf engine` and hands back its pipes. It is
// [remote.Dialer]: the door owns processes, the wire owns frames, and this is
// the one function the redial loop reaches back through when a link dies.
func (l *engineLink) spawn() (io.ReadWriteCloser, error) {
	// The remote command, as the far machine's login shell will read it. The
	// workspace is quoted because a path with a space in it is a path, and an
	// unquoted one would arrive at `codeaf engine` as two arguments.
	remoteCommand := hostEngineCommand(programName(), l.dest, l.workspace)

	// -T because there is nothing interactive on the far end: the engine reads
	// frames on stdin and writes them on stdout, and a pseudo-terminal in the
	// middle would turn a newline into a carriage return and a frame into
	// nonsense. ssh's OWN questions do not go through this — it asks them on
	// /dev/tty, which is still the person's terminal.
	process := exec.Command("ssh", sshTransportArgs(l.dest, remoteCommand)...)
	stdin, err := process.StdinPipe()
	if err != nil {
		return nil, err
	}
	stdout, err := process.StdoutPipe()
	if err != nil {
		return nil, err
	}
	// STDERR BELONGS TO THE TERMINAL UNTIL THE HANDSHAKE. Launch prompts reach
	// the person before the surface takes the frame; later diagnostics stay in
	// the tail so a disconnect cannot paint over that frame.
	tail := &tailWriter{}
	process.Stderr = l.stderrWriter(tail, os.Stderr)
	if err := process.Start(); err != nil {
		if strings.Contains(err.Error(), "executable file not found") {
			return nil, fmt.Errorf("this machine has no ssh on its path, and --host is ssh")
		}
		return nil, fmt.Errorf("could not start ssh: %w", err)
	}
	l.hold(process, tail)
	return pipePair{r: stdout, w: stdin}, nil
}

// programName follows the executable file, including custom installation names.
func programName() string { return codeupdate.InstallName(enginehost.ThisBinary()) }

// hostEngineCommand selects on the far machine in the same ssh hop. An engine
// failure never triggers a fallback: only absence of the requested file does.
func hostEngineCommand(name, dest, workspace string) string {
	args := " engine"
	if workspace != "" {
		args += " --workspace " + shellQuote(workspace)
	}
	primary := "exec " + shellQuote(name) + args
	if name == "codeaf" {
		return primary
	}
	notice := "printf '%s has no %s; using its codeaf (%s)\\n' " + shellQuote(dest) + " " + shellQuote(name) + " \"$(codeaf version)\" >&2"
	return "if command -v " + shellQuote(name) + " >/dev/null 2>&1; then " + primary +
		"; elif command -v codeaf >/dev/null 2>&1; then " + notice + "; exec codeaf" + args + "; else " + primary + "; fi"
}

// stderrWriter keeps the launch-time prompts visible but keeps redial output
// inside the session's diagnostic tail. A reconnect happens while Bubble Tea
// owns the terminal's alternate screen, so writing ssh's transient errors to
// os.Stderr would paint over the frame instead of becoming a status detail.
func (l *engineLink) stderrWriter(tail *tailWriter, terminal io.Writer) io.Writer {
	l.mu.Lock()
	defer l.mu.Unlock()
	if l.process == nil {
		return &launchStderr{link: l, terminal: terminal, tail: tail}
	}
	return tail
}

// launchStderr stays installed on the initial carrier after its handshake.
// The connection boundary changes its destination under the link's lock, so
// even that carrier's later disconnect errors stay out of the owned frame.
type launchStderr struct {
	link     *engineLink
	terminal io.Writer
	tail     *tailWriter
}

func (w *launchStderr) Write(p []byte) (int, error) {
	w.link.mu.Lock()
	defer w.link.mu.Unlock()
	if w.link.client == nil {
		return io.MultiWriter(w.terminal, w.tail).Write(p)
	}
	return w.tail.Write(p)
}

// sshTransportArgs keeps the carrier's latency policy in one place. -T remains
// first because a pseudo-terminal changes bytes; the other options keep a warm
// connection available for redials, notice a machine that stopped answering,
// and keep interactive frames out of bulk queues on networks that distinguish
// them. The values come through config's registry, so a network that needs a
// different policy has a supported override rather than a private environment
// variable hidden from the settings sheet.
func sshTransportArgs(dest, remoteCommand string) []string {
	settings := config.SSHTransportAt(env.Get("CODEAF_PROFILE_DIR"))
	args := []string{
		"-T",
		"-o", fmt.Sprintf("ServerAliveInterval=%d", settings.ServerAliveSeconds),
		"-o", fmt.Sprintf("ServerAliveCountMax=%d", settings.ServerAliveMisses),
		"-o", "IPQoS=" + settings.IPQoS,
	}
	if control := sshControlPath(); control != "" {
		args = append(args,
			"-o", "ControlMaster=auto",
			"-o", "ControlPath="+control,
			"-o", fmt.Sprintf("ControlPersist=%d", settings.ControlPersistSeconds),
		)
	}
	return append(args, dest, remoteCommand)
}

// sshControlPath is short by construction and lives under the state root. %C
// lets OpenSSH hash the resolved host, port and user rather than us guessing at
// identities hidden in ~/.ssh/config. A state root too long for a unix socket
// loses multiplexing only: --host must still work, just as enginehost falls
// back to its pipe when its own socket cannot be made.
func sshControlPath() string {
	dir := home.Join("v3", "ssh")
	if err := os.MkdirAll(dir, 0o700); err != nil {
		return ""
	}
	if err := os.Chmod(dir, 0o700); err != nil {
		return ""
	}
	path := filepath.Join(dir, "ctl-%C")
	if !sshControlPathFits(path) {
		return ""
	}
	return path
}

// sshControlPathFits accounts for OpenSSH's temporary control-master name as
// well as the final hashed path, so a path accepted here cannot fail at bind.
func sshControlPathFits(path string) bool {
	// OpenSSH expands %C to a 40-character SHA-1 digest and briefly appends a
	// 17-character suffix before bind(2), so both forms must fit the shared
	// macOS/Linux ceiling.
	expanded := strings.Replace(path, "%C", strings.Repeat("0", 40), 1)
	return enginehost.SocketPathFits(expanded) && enginehost.SocketPathFits(expanded+strings.Repeat("0", 17))
}

// hold takes the new child and lets go of the old one. THE PREVIOUS SSH IS
// REAPED IN THE BACKGROUND, because a redial happens after its pipe died and a
// child nobody waits on is a zombie for as long as this terminal is open — five
// minutes of retries against a machine that is switched off would leave a row of
// them.
func (l *engineLink) hold(process *exec.Cmd, tail *tailWriter) {
	previous, reaped := l.swap(process, tail)
	if previous != nil && !reaped {
		guard.Go("chatv3/host-reap", func() { _ = previous.Wait() })
	}
}

// swap installs the new child and answers the old one and whether it was
// already reaped. It is its own method so the mutex is held from a defer while
// the wait on the previous child stays outside the lock.
func (l *engineLink) swap(process *exec.Cmd, tail *tailWriter) (previous *exec.Cmd, reaped bool) {
	l.mu.Lock()
	defer l.mu.Unlock()
	previous, reaped = l.process, l.reaped
	l.process, l.stderr, l.reaped, l.err = process, tail, false, nil
	return previous, reaped
}

// dialEngine starts the engine on the far machine, completes the handshake, and
// leaves the connection able to redial itself.
//
// THE HELLO IS THE CALLER'S because this door is now dialled more than once per
// window: the launch's own hello opens the conversation this terminal came for,
// and one naming [remote.Hello.New] opens another beside it (chatv3_beside.go).
// The workspace is still a separate argument because it is also an argument to
// ssh — it goes on the remote command line so the engine starts in the right
// place even if the handshake never happens.
func dialEngine(dest, workspace string, hello remote.Hello) (*engineLink, error) {
	link := &engineLink{dest: dest, workspace: workspace}
	hello.Workspace = workspace
	client, err := remote.Roam(dest, hello, remote.Roaming{Dial: link.spawn})
	if err != nil {
		return nil, link.diagnose(dest, err)
	}
	link.mu.Lock()
	defer link.mu.Unlock()
	link.client = client
	return link, nil
}

// launchHello is the first hello a terminal door says: the conversation the
// person named, on the model and the reasoning level they asked for.
//
// --model AND --reasoning RIDE THE FRAME THAT BUILDS THE SESSION, so the engine
// opens on them rather than being switched a millisecond afterwards — the
// journal's first line then names the model the session was born on.
func launchHello(session, model, level string) remote.Hello {
	return remote.Hello{Session: session, Model: model, Level: level}
}

// besideHello is the hello for a conversation opened BESIDE the one a window
// already has. It carries the launch's model and level for the same reason the
// launch's own does — a conversation opened an hour later is the same launch —
// and it carries the ask's own intention (chatv3_beside.go's [engineAsk]).
//
// IT DOES NOT SAY [remote.Hello.Window], deliberately: this is the same window
// on another connection, and the boot connection already holds the far
// machine's presence for it. Saying it here would count one window once per
// conversation it has open — a window with three tabs reading itself as three
// windows, which is the very count that says whether anybody else is still
// there when this one closes.
func besideHello(ask engineAsk, model, level string) remote.Hello {
	return remote.Hello{Session: ask.session, New: ask.mint, Model: model, Level: level}
}

// diagnose turns a failed handshake into the truest sentence available.
//
// IT SNIFFS AND IT DOES NOT GUESS. A shell that could not find the command says
// so on stderr and exits 127; that is a fact, and "codeaf is not installed on
// devbox" is what it means. ssh's own failures exit 255 and have already printed
// their own reason, which is better than anything this function could invent, so
// they are not paraphrased. Everything else falls back to what the handshake
// itself said. The one thing this never does is offer a cause it cannot see.
func (l *engineLink) diagnose(dest string, cause error) error {
	_ = l.close()
	code := l.exitCode()
	said := l.said()
	switch {
	case code == 127 || mentionsMissingCommand(said):
		return missingHostCommand(dest)
	case code == 255:
		// ssh has already said why, in its own words, above this line.
		return fmt.Errorf("ssh could not open a session on %s", dest)
	default:
		return cause
	}
}

func missingHostCommand(dest string) error {
	return fmt.Errorf("%s is not installed on %s — run %s on %s; put it on the PATH that a non-login ssh command sees", programName(), dest, codeupdate.CurlLine(enginehost.ThisBinary(), codeupdate.FollowedChannel(buildinfo.String())), dest)
}

// mentionsMissingCommand reads the far shell's own wording. The three spellings
// are bash/zsh, sh/dash and busybox, which is every shell an engine is likely to
// be started from.
func mentionsMissingCommand(said string) bool {
	said = strings.ToLower(said)
	const legacyCommand = "aforge" // legacy-name
	return strings.Contains(said, "command not found") ||
		strings.Contains(said, "not found") && (strings.Contains(said, "codeaf") || strings.Contains(said, legacyCommand)) ||
		strings.Contains(said, "no such file or directory") && (strings.Contains(said, "codeaf") || strings.Contains(said, legacyCommand))
}

// close shuts the connection and reaps the process. Closing the client also
// ends the redialling, so no further ssh child is started after this.
func (l *engineLink) close() error {
	if l.client != nil {
		_ = l.client.Close()
	}
	return l.reap()
}

// reap waits on the current ssh child, once.
func (l *engineLink) reap() error {
	process, err := l.claimReap()
	if process == nil {
		return err
	}
	err = process.Wait()
	l.noteReaped(err)
	return err
}

// claimReap marks the current child as being waited on and hands it back, or
// answers nil and the error already recorded when there is nothing to wait on.
// It is its own method so the mutex is held from a defer while the wait itself
// stays outside the lock.
func (l *engineLink) claimReap() (*exec.Cmd, error) {
	l.mu.Lock()
	defer l.mu.Unlock()
	if l.process == nil || l.reaped {
		return nil, l.err
	}
	l.reaped = true
	return l.process, nil
}

// noteReaped records what the wait answered. It is its own method so the mutex
// is held from a defer.
func (l *engineLink) noteReaped(err error) {
	l.mu.Lock()
	defer l.mu.Unlock()
	l.err = err
}

// exitCode is ssh's exit status once it has been waited on, or -1.
func (l *engineLink) exitCode() int {
	_ = l.reap()
	l.mu.Lock()
	defer l.mu.Unlock()
	if l.process == nil || l.process.ProcessState == nil {
		return -1
	}
	return l.process.ProcessState.ExitCode()
}

// said is the tail of what ssh and the far shell printed on the current link.
func (l *engineLink) said() string {
	tail := l.tail()
	if tail == nil {
		return ""
	}
	return tail.String()
}

// tail is the current link's stderr keeper. It is its own method so the mutex
// is held from a defer while the read of the keeper, which takes a lock of its
// own, stays outside this one.
func (l *engineLink) tail() *tailWriter {
	l.mu.Lock()
	defer l.mu.Unlock()
	return l.stderr
}

// pipePair is the ssh child's two halves as one [io.ReadWriteCloser], which is
// what internal/remote dials on. Closing it closes the WRITE half, which is what
// tells the engine there is nothing more coming and lets it exit cleanly; the
// read half then ends by itself.
type pipePair struct {
	r io.ReadCloser
	w io.WriteCloser
}

func (p pipePair) Read(b []byte) (int, error)  { return p.r.Read(b) }
func (p pipePair) Write(b []byte) (int, error) { return p.w.Write(b) }
func (p pipePair) Close() error {
	err := p.w.Close()
	_ = p.r.Close()
	return err
}

// tailWriter keeps the last few kilobytes of what was written through it, so a
// failure can be diagnosed from what the far end actually said. It is bounded
// because a remote command can print for ever and a diagnosis needs a sentence.
type tailWriter struct {
	mu   sync.Mutex
	seen bytes.Buffer
}

const tailKept = 8 << 10

func (t *tailWriter) Write(b []byte) (int, error) {
	t.mu.Lock()
	defer t.mu.Unlock()
	t.seen.Write(b)
	if t.seen.Len() > tailKept {
		kept := t.seen.Bytes()
		kept = kept[t.seen.Len()-tailKept:]
		t.seen.Reset()
		t.seen.Write(kept)
	}
	return len(b), nil
}

func (t *tailWriter) String() string {
	t.mu.Lock()
	defer t.mu.Unlock()
	return t.seen.String()
}

// shellQuote wraps a path for the far machine's shell, single quotes and all.
func shellQuote(word string) string {
	return "'" + strings.ReplaceAll(word, "'", `'\''`) + "'"
}

// openChatV3Host is the launch.
func openChatV3Host(launch hostLaunch) error {
	if err := launch.check(); err != nil {
		return err
	}
	dest, workspace, err := parseHostTarget(launch.target)
	if err != nil {
		return err
	}
	if launch.pick && launch.once != "" {
		return fmt.Errorf(`codeaf resume opens the session picker; for one headless message use: codeaf chat --host %s --once "text"`, dest)
	}
	hello := launchHello(launch.session, launch.model, launch.level)
	hello.Headless = launch.once != ""
	// AND A WINDOW IS A WINDOW OPEN ON THE FAR MACHINE, so that machine's
	// automations clock runs while it is attached (internal/remote's
	// [remote.Hello.Window]). It is said on THIS connection and on no other: the
	// boot connection lives exactly as long as the window does, and every
	// conversation opened beside it is the same window on another pipe
	// ([besideHello] says nothing). A headless `--once` is a script, not a window.
	hello.Window = launch.once == ""
	link, err := dialEngine(dest, workspace, hello)
	if err != nil {
		return err
	}

	client := link.client
	agent := client.Agent()
	welcome := client.Welcome()
	correctHostChoices(agent, launch, welcome)

	if launch.once != "" {
		defer func() { _ = link.close() }()
		return runHostOnce(agent, launch.once)
	}
	// ANOTHER CONVERSATION IS ANOTHER ssh, and it is the same one as far as the
	// network is concerned: the transport args ask OpenSSH to multiplex
	// (`ControlMaster=auto`, [sshTransportArgs]), so the second link rides the
	// connection the first one opened rather than authenticating again.
	fleet := newEngineFleet(dest, client, link.close, func(ask engineAsk) (*engineConn, error) {
		beside, err := dialEngine(dest, ask.workspace, besideHello(ask, launch.model, launch.level))
		if err != nil {
			return nil, err
		}
		return &engineConn{client: beside.client, shut: beside.close}, nil
	})
	defer fleet.closeAll()
	options, _ := hostOptions(fleet, welcome, launch.pick)
	options.Restart = launch.restart
	// THE SAME WAY THE SURFACE IS RUN AT EVERY OTHER DOOR (chatv3_surface.go):
	// the byte meter and the logger redirect are the terminal's business rather
	// than this connection's, and a door does not state them for itself.
	return runSurface(context.Background(), options)
}

// correctHostChoices makes the session agree with --model and --reasoning when
// the welcome says it does not.
//
// THE HELLO IS WHERE THESE BELONG AND THE HELLO IS WHERE THEY GO NOW. The engine
// opens the session on them ([remote.Hello]'s Model and Level), so the journal's
// first line names the model the person asked for rather than the one the far
// machine happens to default to. This is not that work done twice: it is the
// check that the ask LANDED. The welcome states the model the engine actually
// opened on, so a disagreement with --model is a fact the surface can see, and a
// surface that saw it and drew the engine's answer anyway would be showing a
// person a model they did not choose.
//
// The level cannot be read off the welcome — there is no field for it — so when
// one was asked for it is read back with the one round trip that can answer it,
// and set only when it differs.
func correctHostChoices(agent *remote.Agent, launch hostLaunch, welcome remote.Welcome) {
	model := welcome.Model
	if launch.model != "" && launch.model != model {
		agent.SetModel(launch.model)
		model = launch.model
	}
	// The boot override lands on the model this session starts on, which is the
	// only model it can be about — the same law the local door states.
	if launch.level != "" && model != "" && agent.ReasoningFor(model) != launch.level {
		agent.SetReasoningFor(model, launch.level)
	}
}

// hostOptions assembles the surface. Everything the far machine knows comes off
// the welcome; everything this machine keeps on the person's behalf is resolved
// here, exactly as the local door resolves it.
//
// ── LOOKING INTO ANOTHER CONVERSATION'S TASK IS NOT WIRED HERE, AND SAYING SO ──
//
// [tui3.Options.OpenTaskOwner] is deliberately left nil on this road, which the
// surface reads as a capability this window has not got: the row still takes the
// cursor and still answers `enter`, and what it opens is the card naming where
// the work is (internal/tui3's taskowner.go). That is the absence law rather
// than a gap somebody forgot.
//
// THE REASON IS THAT THE ROWS DO NOT EXIST ON THIS ROAD AT ALL. A row belonging
// to another conversation is minted from the PRESENCE DIRECTORY of the project,
// read off this process's own disk (internal/tui3's [app.refreshElsewhere], which
// asserts [session.Agent.Elsewhere] and gets nothing over a connection —
// [remote.Agent] does not implement it). Over `--host` and `--at` the conversation
// is on the far machine and its neighbours' presence files are on the far
// machine's disk, so this surface never learns they are there and draws no such
// row for the door to be behind.
//
// WIRING THE DOOR ALONE WOULD NOT FIX THAT and would be worse than leaving it:
// it would be a capability that could never be reached, which this codebase
// leaves off rather than ships broken. What the road actually owes first is the
// presence reading crossing the wire — a method on the protocol answering
// `Elsewhere` for the engine's machine — and that is a lane of its own with a
// version bump in it. Until it lands, the honest claim is the one the manual
// makes: reading another conversation's task works where the engine is local.
// IT IS ASSEMBLED AROUND A FLEET AND NOT AROUND A CONNECTION, which is the one
// thing that changed when this door learned to hold more than one conversation.
// The boot connection is still where every reading about the MACHINE goes; what
// the fleet adds is the pair of seams that open a conversation BESIDE this one,
// each on a connection of its own (chatv3_beside.go).
func hostOptions(fleet *engineFleet, welcome remote.Welcome, pick bool) (tui3.Options, config.Config) {
	client, agent, dest := fleet.client(), fleet.agent(), fleet.dest
	// THE PICKER'S LIST IS RESOLVED WITHOUT CREDENTIALS. The catalog is opened
	// with whatever this machine happens to have — usually nothing, because the
	// key lives on the engine's machine — and that is fine: a catalog with no key
	// answers nil, the picker falls back to ~/.codeaf/v3/models.json and then to
	// its built-ins, and the list is a list of NAMES rather than a claim about
	// what this machine can reach. What the model actually costs and whether the
	// switch took is the session's answer, and the session is over there.
	//
	// AND A MISSING KEY IS NOT AN ERROR ON THIS PATH, which is the one place this
	// door differs from the local one in a way a person would notice. The local
	// door stops with "codeaf chat needs a model to talk with" because it is about
	// to build a session; this one is not — the session, and the key that pays for
	// it, are on the other machine. Refusing to open a remote conversation because
	// THIS laptop has no OPENROUTER_API_KEY would be asking for a credential
	// nothing is going to spend.
	settings, err := config.Load()
	profileDir := settings.ProfileDir
	if err != nil {
		settings = config.Config{BaseURL: config.DefaultBaseURL}
		profileDir = env.Get("CODEAF_PROFILE_DIR")
	}
	discovery := catalog.Options{BaseURL: settings.BaseURL, APIKey: settings.APIKey, Dir: profileDir}
	models := catalog.LoadLazy(context.Background(), discovery)
	// THE WARM IS THE WINDOW'S, and the window's fleet joins it when the door
	// lets go (#1274): its fetch writes a cache when it lands, and one nobody
	// joined could write after this window had closed.
	fleet.own(models.Close)
	// The crew router picks its seats from this catalog (config.CrewCatalog):
	// the same non-blocking read, never a fetch, and set once at start-up.
	seatCrewRows(models.ModelsNow)
	// The pool's errands start beside it, against the same profile the catalog
	// was read from.
	wirePoolIndex(profileDir)
	// The refresh key in /model asks the same router THIS machine's list came
	// from, and refills the same shelf — the list is this laptop's list of
	// names on both doors (chatv3_modelshelf.go).
	shelf := newV3ModelShelf(models, discovery)
	seams := newHostSeams(client)
	// EVERY BACKGROUND READING IS ARMED THROUGH ONE SEAM: the connection, and the
	// notice line a duty that fell over speaks to once (chatv3_host_duty.go). A
	// door with no client behind it arms duties that never start, rather than
	// goroutines that die on the wire.
	news := &hostNews{}
	seams.Notice = news.join(seams.Notice)
	far := hostFar{client: client, tell: news.say}
	// THE PLACES FOLLOW THE SESSION'S MACHINE. The world behind home, tasks,
	// spend and search is asked of the ENGINE and kept warm here, and
	// it is asked once now so the first frame after launch already has it
	// ([hostWorld] holds both laws).
	world := newHostWorld(far)
	world.prime()
	ledger := newHostLedger(far)
	ledger.prime()
	memory := newHostMemory(far)
	memory.prime()

	// The counting gate is here and not on the roads: a session this window
	// only watches through its link is counted from the events it receives
	// (telemetry_events.go), and hostOptions is the one place the surface's
	// boot agent is assembled on all of them. IT IS WRAPPED ONCE, because the
	// shared door below hands the same handle back from Resume and Fresh and
	// the surface holds it to that (chatv3_host_shared_test.go).
	counted := countedAgent(agent)
	options := tui3.Options{
		Agent:       counted,
		Build:       welcome.Build,
		Host:        dest,
		SyncService: welcome.SyncService,
		Workspace:   welcome.Workspace,
		// The engine's own journal path, shown with its machine in front of it
		// wherever the surface shows it (internal/tui3's host.go).
		SessionFile:       welcome.SessionFile,
		Resumed:           welcome.Resumed,
		Notice:            hostEntryNotice(welcome),
		UnreadProfileKeys: append([]string(nil), welcome.UnreadProfileKeys...),
		// The engine's own tool-approval posture, so the YOLO badge names the
		// machine that actually decides whether a tool runs unattended
		// (internal/tui3's app.approvalPosture).
		ApprovalMode: welcome.ApprovalMode,
		// The engine's own foreground-command clock, for the same reason. The
		// laptop's profile may carry a different value and cannot describe the
		// timer that is already armed around a far process.
		BashBackgroundAfterSeconds: welcome.BashBackgroundAfterSeconds,
		ContextWindow:              v3Window(models, welcome.Model),
		Models:                     shelf.pickerModels,
		RefreshModels:              shelf.refresh,
		ProviderFetchError:         shelf.fetchErrorFor,
		// /export writes on THIS machine (host.go's honesty table), so its row
		// goes in this machine's index — the same one the local launch spells.
		ArtifactsIndex: artifactsIndexPath(),
		ProfileDir:     profileDir,
		PickSession:    pick,
		// The conversations the ENGINE's disk holds, and the door back into one of
		// them. Both go over the wire; neither reads a session file here.
		RecentSessions: func() []tui3.Session { return hostSessions(client) },
		// ── THE PLACES, AS THE ENGINE MACHINE HOLDS THEM ────────────────────
		//
		// The seven places are a listing of one machine's disk, and until this
		// pair existed the surface listed its OWN: over --host the tasks place
		// walked this laptop's `~/.codeaf/v3` and drew eight rows and $22.54 of
		// work under a conversation on a server that had run none of it. The
		// world crosses the wire now (internal/remote's Places.World), and the
		// root it was walked under travels with it so that the conversation this
		// window is sitting in can be put back into a walk taken before it
		// existed (internal/tui3's [app.worldRoot]).
		World:     world.world,
		WorldRoot: welcome.PlacesRoot,
		// AND ONE ROW OF THAT RECORD, WHEN SOMEBODY OPENS ITS CARD. It is a call
		// and not a cache, unlike the world above: the world is asked on every
		// place's open and on the beat, and this is asked once, on a press, about
		// one of four hundred rows. The surface only ever makes it off its loop
		// (internal/tui3's [app.readTaskTail]), so the wire's own deadline is the
		// only clock it needs.
		TaskRecord: client.TaskRecord,
		TaskRoom:   agent.TaskRoom,
		// TaskIndex is filled below, from the same shared walk, once this
		// conversation's transcript is the only thing left to key it by.
		Ledger: ledger.read,
		Memory: memory,
		// AND THE ONE WRITE HOME MAKES AGAINST THAT WORLD GOES THROUGH THE SAME
		// CACHE IT READS. A bare client.Archive landed on the engine's disk and
		// left what is held saying the opposite, so the row `ctrl+e` put away sat
		// on the screen until a later beat fetched it back ([hostWorld.archive]
		// carries the whole of why).
		Archive: world.archive,
		// THE TEAMS, AS THE ENGINE MACHINE KEEPS THEM. The far session's team
		// tools write the teams file and each team's Traffic into the engine's
		// profile, so the window reads and writes those, over the wire
		// ([hostTeams]); an engine without the doors hands no seam and the
		// surface turns teams off rather than keeping them on this laptop.
		Teams: hostTeamsSeam(far, welcome),
		// THE AUTOMATIONS, AS THE ENGINE MACHINE KEEPS AND RUNS THEM. The
		// conversation over there proposes into that machine's store and that
		// machine's clock runs what it keeps — while this window is attached,
		// because the boot hello says this connection is a window
		// ([openChatV3Host]) — so the list, the run lines and the notifications
		// are read over the wire ([hostAutomationsSeam]). An engine without the
		// doors hands no seam and this window shows no automations, never this
		// laptop's, which run somewhere else. The linked-local road puts its own
		// machine's store back on top ([openChatV3Local]).
		Automations: hostAutomationsSeam(client, welcome),
		// AND THE BANNERS ARE THIS MACHINE'S: they are raised by this window, in
		// the terminal in front of the person, whichever machine ran the run.
		Notify: v3NotifyRoute(),
		// ── WHAT THE CONNECTION ITSELF SAYS ─────────────────────────────────
		//
		// The four facts only a connection has: the sentence to draw while a
		// dropped link is being redialled, the measured round trip, the one-off
		// news a redial discovered, and the questions this conversation raised
		// while nobody was attached.
		// Each lands somewhere different on the screen and internal/tui3's
		// hostlink.go says where; what this door owes is the answer, and the
		// client answers all four.
		//
		// AND IT IS ASSEMBLED THROUGH ONE FUNCTION, because every conversation
		// beside this one has a connection and therefore a seam of its own
		// (chatv3_beside.go's [hostLink]). Two spellings of these seven fields is
		// how the conversation on screen and the conversation behind it would come
		// to disagree about which questions are waiting.
		Link: hostLink(seams),
		// ── WHAT IS DELIBERATELY NOT WIRED ──────────────────────────────────
		//
		// These absences belong to --host and --at. The linked-local road uses
		// this builder too, then [localDoors] in chatv3_local.go puts back the
		// stores whose engine and surface are on this same machine.
		//
		// Connections: the accounts panel signs in through a browser HERE and
		// stores the result HERE, while the session reads the store THERE. A
		// panel wired to this machine's manager would offer rows that landed in
		// the wrong place, so none is handed over and /connect says so in one
		// sentence (internal/tui3's host.go).
		//
		// ConnectCodex: the same split for the Codex row — the sign-in's
		// callback listener would be on this loopback and its tokens in this
		// profile, while the session that needs them runs over there. The row
		// says the sign-in is unavailable here, and the terminal door on that
		// machine (`codeaf connect codex`) is the road that works.
		//
		// Harnesses: the registry the engine matches turns against is on the
		// engine's machine. Listing this machine's under /harness would be
		// offering to run harnesses that are not there.
		//
		// SaveApproval and SaveBashApproval: the consent card's "always" writes a
		// row into a profile, and the gate that reads it is the far machine's. Nil
		// is the honest wiring — the card keeps the answer for the session, over
		// the wire, and its row says "allowed" rather than "saved", which is
		// exactly what happened (internal/tui3's consent.go).
		//
		// ErrandsRoot: the local errands folder, which is where a question asked
		// from home leaves its short transcript. It is a path on
		// THIS machine and the exchange it hosts is a session this surface would
		// have to open here, so it stays unset over a connection — the same
		// posture the errand pair takes.
		//
		// SaveModel: the same rule for the same reason. The model this session
		// opens on next time is resolved where the session is built, which is over
		// there; writing the choice into THIS machine's profile would change which
		// model a local conversation starts on because somebody switched models on
		// a remote one. The switch itself still takes — it goes over the wire like
		// everything else — it simply does not outlive the session.
		//
		// Sources and ApplyModelSources: the model-service profile belongs to the
		// engine's machine too. A far surface must neither draw this laptop's
		// services nor write one here and claim the engine can use it. The local
		// road hands its resolved set to the surface, while the engine re-reads
		// that same profile through the existing model-set call.
		//
		// AND THE FILE DOOR IS NOT A SEAM HERE EITHER, which is worth saying
		// because it looks like an omission and is not. Remote files — the links
		// in a reply, the browse page /files opens, the fetch behind opening one
		// — ride the CLIENT under this agent: the surface asserts `Client()` on
		// whatever it was handed and gets ListDir, StatPaths and FetchFile off it
		// (internal/tui3's remotefiles.go, on attach.go's narrow-interface
		// pattern). So the door this file already passes is the whole wiring, a
		// local session satisfies none of it and gets none of it, and there is no
		// closure here that could go stale around a conversation that was swapped.
	}
	// The two things this surface keeps on the person's behalf, resolved the way
	// the local door resolves them and keyed by the REMOTE workspace — which is
	// right: what a person typed while working on devbox:code/app belongs to that
	// place, not to whatever directory this terminal happens to be sitting in.
	if dir, err := v3Dir(); err == nil {
		store := history.New(filepath.Join(dir, "history.jsonl"))
		options.History = store
		options.DraftFile = tui3.ChatDraftFile(dir, dest, welcome.Workspace, welcome.SessionFile)
	}
	// ── AND THE DOORS ONTO ANOTHER CONVERSATION ─────────────────────────────
	//
	// The four readings a conversation opened beside borrows are handed to the
	// fleet HERE rather than resolved again per conversation: every one of them
	// is about this window or about the engine's disk, all four are already
	// cached behind the surface, and a second copy per tab would be a second walk
	// of the far machine's places on every switch.
	fleet.machine = machineReadings{
		recent:  options.RecentSessions,
		world:   options.World,
		window:  func(model string) int { return v3Window(models, model) },
		draft:   options.DraftFile,
		history: options.History,
	}
	// THIS CONVERSATION'S OWN ROWS, out of the same shared walk every conversation
	// beside it reads its own out of (chatv3_beside.go's [farTaskRows]). It
	// replaces a closure that named this session file and was left bound to it
	// through every switch.
	options.TaskIndex = farTaskRows(options.World, welcome.SessionFile)
	if dest == "" {
		// The linked engine and this window read the same profile, so its shelf
		// can list every connected provider just as the in-process door does.
		engineProfile := strings.TrimSpace(welcome.ProfileDir)
		if engineProfile == "" {
			engineProfile = profileDir
		}
		shelf.options.Dir = engineProfile
		shelf.setSources(config.ResolveSources(engineProfile, settings.APIKey, settings.BaseURL))
		listing := &v3Process{Shelf: shelf}
		options.RefreshModels = listing.refreshDefaultModels
		options.ModelsForService = shelf.modelsForService
		options.RefreshModelsForService = shelf.refreshService
		options.RefreshAllModels = listing.refreshAllModels
		options.WarmEmptyProviders = listing.warmEmptyProviders
		options.SubscribeServiceModels = listing.registerServiceNotice
		options.ApplyModelSources = shelf.setSources
	}
	if welcome.TaskDelete {
		options.DeleteTask = func(file, id string) error {
			if err := client.DeleteTask(file, id); err != nil {
				return err
			}
			world.fetch()
			return nil
		}
	}
	if !fleet.canBeside() {
		// A DOOR THAT CANNOT DIAL AGAIN REALLY DOES HOLD ONE CONVERSATION AT A
		// TIME, and says so ([tui3.Options.SharedAgent]) rather than letting
		// somebody discover it. The two seams below select in place on the one
		// connection: the engine mints or opens the conversation and ENDS the one
		// it replaced (internal/remote's Session.swap), so this handle names
		// whichever conversation is now open and there is nothing left for the
		// surface to close.
		options.SharedAgent = true
		options.Resume = func(file string) (tui3.Agent, error) {
			if _, err := client.OpenSession(file); err != nil {
				return nil, err
			}
			return counted, nil
		}
		options.Fresh = func() (tui3.Agent, string, error) {
			next, err := client.NewSession()
			if err != nil {
				return nil, "", err
			}
			return counted, next.SessionFile, nil
		}
		return options, settings
	}
	// AND A DOOR THAT CAN GETS THE WHOLE SEAM AND NOT THE OLDER HALF OF IT.
	// [tui3.Options.Start] and [tui3.Options.Open] hand back a conversation with
	// its own agent, its own connection, its own transcript and its own waiting
	// room; [Options.Fresh] and [Options.Resume] are deliberately left unset, so
	// there is exactly one door and no road on which a swap can still happen.
	options.Start = fleet.start
	options.Open = fleet.open
	if welcome.ConversationDelete {
		options.DeleteConversation = func(file string, choices map[string]string, affected map[string][]string) error {
			if err := client.DeleteConversation(file, choices, affected); err != nil {
				return err
			}
			world.mu.Lock()
			defer world.mu.Unlock()
			for i := range world.held.Projects {
				rows := world.held.Projects[i].Sessions
				kept := rows[:0:0]
				for _, row := range rows {
					if row.Transcript != file {
						kept = append(kept, row)
					}
				}
				world.held.Projects[i].Sessions = kept
			}
			return nil
		}
	}

	return options, settings
}

// ── what the engine says about the room ─────────────────────────────────────

// hostEntryNotice is the sentence the surface shows once on the way in: what the
// engine said about opening the session, and who else is already in it.
//
// WHO ELSE IS HERE IS NOT A DETAIL. A session with another surface attached is a
// conversation somebody else can type into, and a screen that kept that quiet
// would be the one place codeaf hid something about the room. The count is the
// engine's ([remote.Welcome]'s Attached), because only the machine holding the
// session can know it. Zero says nothing at all, by the emptiness law.
func hostEntryNotice(welcome remote.Welcome) string {
	said := strings.TrimSpace(welcome.Note)
	attached := hostAttachedNote(welcome.Attached, welcome.Driver.Yours)
	switch {
	case said == "":
		return attached
	case attached == "":
		return said
	default:
		return said + " · " + attached
	}
}

// hostAttachedNote is who else is here, and — since the room got one keyboard —
// what arriving did to them.
//
// THE SECOND HALF IS OWED TO THE OTHER WINDOW'S PERSON. Opening this
// conversation here has just taken the keyboard off whatever window was holding
// it (internal/remote's driver.go), and the person who did it is the only one
// who can be told why the screen over there changed. `typing is here now` is the
// same fact the watcher's own line says from the other side, in the same words.
//
// A window that arrived WITHOUT the keyboard — a link coming back to a
// conversation somebody has walked to since — says only who is here, because it
// took nothing.
func hostAttachedNote(attached int, driving bool) string {
	who := ""
	switch {
	case attached <= 0:
		return ""
	case attached == 1:
		who = "another window is on this conversation"
	default:
		who = fmt.Sprintf("%d other windows are on this conversation", attached)
	}
	if driving {
		who += " — typing is here now"
	}
	return who
}

// hostSeams is what a remote connection can tell the surface, in the wire's own
// shapes. Each field is a closure over [remote.Client], and each is named here
// rather than passed inline so that the door has ONE list of what a connection
// knows about itself and the option assembly has one line per fact.
//
// ALL FOUR ARE WIRED NOW. Three were written before internal/tui3 had anywhere
// to put them and sat unwired for a wave, which is why this type reads as a list
// of facts rather than as an argument: the surface has grown
// [tui3.LinkSeam] and hostOptions hands all four straight into it.
type hostSeams struct {
	// EngineBuild follows the client's latest welcome, including replacements.
	EngineBuild func() string

	// Link is the quiet sentence about the connection right now — empty
	// whenever there is nothing to say, which is what a status-line segment
	// draws as nothing at all. It reads `reconnecting to devbox — trying for up
	// to 5 minutes` while a dropped link is being redialled.
	Link        func() string
	SendRefusal func() string
	// Ping measures one empty call and back. The surface owns its cadence and
	// rolling estimate; this door only hands over the wire's typed method.
	Ping func() (time.Duration, error)
	// Notice is one sentence to show once and then forget: the two things a
	// redial can discover — the engine did not keep the turn, and the engine
	// came back with a different conversation open.
	Notice func() string
	// Held is the questions this session raised while nobody was attached. The
	// surface replays each one's event through the door it already draws live
	// cards with.
	Held func() ([]remote.HeldQuestion, error)
	// Driving is who holds the keyboard on this conversation, DrivingChanged is
	// closed the next time that moves, and Take asks for it back. They are the
	// three halves of one fact — a conversation with more than one window on it
	// has exactly one that can type (internal/remote's driver.go) — and they are
	// listed here beside the others because they are the same kind of thing: what
	// a connection can tell the surface about itself.
	Driving        func() remote.Driver
	DrivingChanged func() <-chan struct{}
	Take           func() error
	// Follow is the turns started by another window on this conversation, so a
	// window that is not typing is still a window onto the work.
	Follow func() <-chan remote.Following
	// NewsSilent says the far engine has sent none of the status line's news —
	// no provider, no live rate — and has not said it would
	// ([remote.Client.NewsSilent]).
	NewsSilent func() bool
}

func newHostSeams(client *remote.Client) hostSeams {
	initial := client.Held()
	var readInitial atomic.Bool
	return hostSeams{
		Link: client.LinkNote, SendRefusal: client.SendRefusal, Ping: client.Ping, Notice: client.TakeNotice,
		EngineBuild: func() string { return client.Welcome().Build },
		Held: func() ([]remote.HeldQuestion, error) {
			// Arrival and replay share one snapshot. Re-querying before drawing
			// it could hide a question re-emitted since arrival: the server has
			// sent it live, while the client already reserved it for this welcome.
			if !readInitial.Swap(true) {
				return initial, nil
			}
			return client.HeldQuestions()
		},
		Driving: client.Driver, DrivingChanged: client.DriverChanged, Take: client.Take,
		Follow: client.Follow, NewsSilent: client.NewsSilent,
	}
}

// hostDriving is who holds the keyboard in the SURFACE's shape, for
// [hostHeld]'s reason: internal/tui3 does not import internal/remote, so the
// one translation there is happens here, at the door, where both halves are
// already in scope.
// hostFollow is the same translation for the turns this window did not start.
// The channel itself is remade, one element at a time, because the surface's
// [tui3.Following] is its own type for [hostHeld]'s reason.
func hostFollow(seams hostSeams) func() <-chan tui3.Following {
	if seams.Follow == nil {
		return nil
	}
	var once sync.Once
	var out chan tui3.Following
	return func() <-chan tui3.Following {
		once.Do(func() {
			out = make(chan tui3.Following)
			guard.Go("chatv3/host-follow", func() {
				// A recovered panic must end the follow the way the seam's own
				// end does, or the surface waits on a channel nobody will close
				// again.
				defer close(out)
				for turn := range seams.Follow() {
					out <- tui3.Following{Said: turn.Said, Events: turn.Events, Covered: turn.Covered, Replay: turn.Replay}
				}
			})
		})
		return out
	}
}

func hostDriving(seams hostSeams) func() tui3.Driving {
	if seams.Driving == nil {
		return nil
	}
	return func() tui3.Driving {
		note := seams.Driving()
		return tui3.Driving{Yours: note.Yours, Machine: note.Machine, Here: note.Here}
	}
}

// hostHeld is the waiting room in the SURFACE's shape.
//
// It exists because internal/tui3 does not import internal/remote and must not:
// the package that draws a screen has no business compiling against a protocol,
// which is why every other thing that crosses this door crosses as a closure or
// as one of internal/session's own types. So the one translation there is —
// unwrapping the event, which is the field JSON could not carry
// ([remote.EventWire]) — happens HERE, at the door, where both halves are
// already in scope.
//
// THE ERROR TRAVELS rather than becoming an empty list, on the terms
// [remote.Client.HeldQuestions] states: "nothing is waiting" and "the far end
// did not answer" are different facts, and a surface handed the second as the
// first would quietly tell a person there is nothing to answer.
func hostHeld(seams hostSeams) func() ([]tui3.HeldQuestion, error) {
	if seams.Held == nil {
		return nil
	}
	return func() ([]tui3.HeldQuestion, error) {
		held, err := seams.Held()
		if err != nil {
			return nil, err
		}
		out := make([]tui3.HeldQuestion, 0, len(held))
		for _, q := range held {
			// THE KIND IS CARRIED ACROSS UNREAD. Deciding here which kinds this
			// build can draw would put the skip rule in two places, and the
			// surface is where the cards are — see internal/tui3's
			// [app.replayHeld], which leaves an unrecognised one waiting.
			//
			// [remote.HeldQuestion.Stream] is dropped, and dropped rather than
			// carried unread: the surface has one conversation and one place a
			// card goes, so there is nothing for it to name (tui3's
			// [HeldQuestion] states the same thing from the other side).
			out = append(out, tui3.HeldQuestion{Kind: q.Kind, Event: q.Event.Unwire(), Since: q.Since})
		}
		return out, nil
	}
}

// hostSessions is [tui3.Options.RecentSessions] over the wire.
//
// IT IS ASKED ON THE KEYSTROKE, like the local one, and it is a round trip
// rather than a directory walk — which is the same order of work: the engine
// reads its own session directory (internal/session's peek.go bounds the reads)
// and one frame comes back. The surface's rule is that this must not BLOCK, and
// a call on a healthy link is milliseconds; a call on a link that is not healthy
// gives up on internal/remote's own deadline and answers with an empty list,
// which is what the local door answers for an unreadable directory.
func hostSessions(client *remote.Client) []tui3.Session {
	found := client.Recent()
	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
}

// runHostOnce is --once over a connection: one message, the reply on stdout,
// everything else on stderr. It is [runChatV3Once] with a remote agent, and it
// is deliberately the same shape — a probe that compares stdout with the
// sentence it asked for must not have to know which machine answered.
//
// THAT SAMENESS INCLUDES THE LEAVING ROAD, and it is why this door does not
// spell the signal set itself. A door reached over a connection is the one most
// likely to be stopped from outside — the ssh session it rode in on going away
// is a SIGHUP — and the work it would orphan is on somebody else's machine,
// where nothing local can see it still spending. So it takes [leave.On] with
// the closure [runChatV3Once] takes, and the set lives in one place still.
//
// THE CANCEL IS NOT ENOUGH HERE AND [remote.Agent.Interrupt] IS THE OTHER HALF.
// [remote.Agent.Submit]'s own comment says the context bounds the CALL and not
// the turn: cancelling it stops the round trip that starts the work, and the
// work is on another machine. Measured over a real ssh pipe, a SIGHUP with the
// cancel alone left the far turn running for another sixty-nine seconds,
// spending, with nobody attached. Interrupt is a frame and travels, so it is
// what actually reaches the turn; the cancel stays because it is what unblocks
// this side if the link is already gone.
func runHostOnce(agent *remote.Agent, text string) error {
	ctx, cancel := context.WithCancel(context.Background())
	defer cancel()
	var leaving atomic.Bool
	// [runChatV3Once]'s rule, for its reason: a person who typed kill -INT is
	// not owed an "error: context canceled" line, and the manual promises the
	// same clean status-0 exit whichever machine answered.
	reported := func(failure error) error {
		if leaving.Load() {
			return nil
		}
		return failure
	}
	stopLeaving := leave.On(func() {
		leaving.Store(true)
		agent.Interrupt()
		cancel()
	}, nil)
	defer stopLeaving()

	events, err := countedAgent(agent).Submit(ctx, text)
	if err != nil {
		return reported(err)
	}
	failure := drainOnceEvents(events, os.Stdout, os.Stderr)
	_ = agent.Close()
	return reported(failure)
}

// ── the places over a connection ────────────────────────────────────────────

// hostWorldEvery is how stale a held world is allowed to be before the next
// reading kicks a fresh one.
//
// IT IS SHORT AND LONGER THAN NOTHING. The surface re-reads its places every
// three seconds (internal/tui3's homeEvery), and a staleness of two means every
// one of those beats finds the held world old enough to refresh — so what a
// person looks at is at most one beat behind the far machine, which is the same
// lag a local window has against the next terminal on its own disk. A
// conversation in the next window over there answers in seconds, and home
// exists to show that happening.
const hostWorldEvery = 2 * time.Second

// hostWorld is the ENGINE machine's world, kept here so the places can have it
// without waiting.
//
// It is the one reading five of the seven places are built from, and it keeps
// two laws for two reasons:
//
//   - THE READ ANSWERS FROM WHAT IS HELD, ALWAYS AND IMMEDIATELY. A place may
//     read on its open and on its beat, and over a connection both of those are
//     still moments a person is waiting through — a call down an ssh pipe has a
//     ten-second deadline (internal/remote's callDeadline), so an open that made
//     one would be a terminal that stopped answering keys for as long as the far
//     machine took, and on a link that had just died, for ten seconds.
//   - ONE FETCH AT A TIME, never a pile. Seven places on a three-second beat,
//     each asking the same question, is a queue of identical frames behind a link
//     that is already slow.
//
// AND IT SAYS WHETHER IT HAS AN ANSWER. For most lists an empty one and no
// answer yet are the same thing on a screen — the emptiness law draws both as
// nothing. An empty WORLD is not: it is
// a machine with no projects on it, and `nothing here yet — say something and
// this fills up` drawn over a server full of work is the one wrong sentence this
// screen can say about somebody else's disk. So the seam answers a second value
// and the surface draws nothing at all until the far machine has spoken once
// (internal/tui3's [app.worldKnown]).
type hostWorld struct {
	// ask and put are the two wire doors, held as CLOSURES rather than as the
	// client: what this type does is a policy about staleness and blocking, and
	// a test of that policy should be able to hand it a slow answer without
	// opening a pipe.
	ask func() (session.World, error)
	put func(dir string, archived bool) error

	// duty is the latch, the clock and the door (chatv3_host_duty.go).
	duty hostDuty

	mu sync.Mutex
	// held is the last world the engine answered with, and known says it has
	// answered at least once.
	held  session.World
	known bool
}

func newHostWorld(far hostFar) *hostWorld {
	h := &hostWorld{ask: far.client.World, put: far.client.Archive}
	far.arm(&h.duty, "keeping the places current")
	return h
}

// world is [tui3.Options.World]: what is held, right now, with a refresh started
// behind it when what is held has aged.
func (h *hostWorld) world() (session.World, bool) {
	held, known := h.snapshot()
	if h.duty.due("", hostWorldEvery) {
		h.duty.run("chatv3/host-world", "", h.fetch)
	}
	return held, known
}

// snapshot is what is held, under the lock held from a defer.
func (h *hostWorld) snapshot() (session.World, bool) {
	h.mu.Lock()
	defer h.mu.Unlock()
	return h.held, h.known
}

// fetch is the round trip, on a goroutine of its own.
//
// A FAILED CALL KEEPS THE LAST WORLD rather than emptying every place at once.
// The two ways this fails are a link that has died and an engine too old to
// answer this method; neither of them is the news "everything you have worked on
// is gone", and seven rooms that blanked themselves on a dropped connection
// would be the screen reporting a loss that did not happen. The clock is stamped
// either way, so a link that is failing is asked again on the next beat rather
// than on every frame — and `known` is only ever turned on, so a world that
// arrived once goes on being drawn while the connection is being redialled.
func (h *hostWorld) fetch() {
	world, err := h.ask()
	if err != nil {
		return
	}
	h.mu.Lock()
	defer h.mu.Unlock()
	h.held, h.known = world, true
}

// archive is [tui3.Options.Archive]: the write goes over the wire, and what is
// held is corrected the instant the engine accepts it.
//
// THE ROW MUST LEAVE UNDER THE HAND. `ctrl+e` on home writes and then re-reads
// the world on the spot, expecting the put-away row to be gone from the rebuild
// (internal/tui3's home.go says so where the key is read). But the re-read
// answers from what is HELD — that is the first of this type's two laws — so
// without this the rebuild redrew the row exactly as it was, and the row only
// went when a later beat's fetch happened to return and a later beat still
// happened to rebuild: [hostWorldEvery] of staleness plus up to two of the
// surface's own three-second beats, which is the several seconds a person sees
// between pressing the key and watching the row go. So the correction comes in
// two halves — the held copy is patched, and the entry is aged out so the next
// reading still asks the engine what it really thinks.
//
// A REFUSED WRITE CHANGES NOTHING HERE. Home prints the engine's own refusal
// ("could not put it away") and a cache that had already moved the row would be
// this screen disagreeing with the disk the conversation is actually on.
//
// THE MATCH IS ON THE SPELLING THE ROW CAME WITH and is not cleaned first: the
// directory travelled out of this same held world, and over --host it is a path
// on the ENGINE's machine, which this laptop's separator has no business
// rewriting.
func (h *hostWorld) archive(dir string, archived bool) error {
	if err := h.put(dir, archived); err != nil {
		return err
	}
	dir = strings.TrimSpace(dir)
	h.mu.Lock()
	defer h.mu.Unlock()
	for i := range h.held.Projects {
		rows := h.held.Projects[i].Sessions
		for j := range rows {
			if strings.TrimSpace(rows[j].Dir) == dir {
				rows[j].Archived = archived
			}
		}
	}
	h.duty.age("")
	return nil
}

// prime asks once, in the background, at the moment the door is built.
//
// THE FIRST FRAME IS THE ONE THAT MATTERS. Without this the first reading a
// place takes is the one that starts the fetch and answers nothing, so a person
// who pressed space-space quickly would meet an empty frame and then a full one.
// Launch is far longer than one round trip, so asking here means the answer is
// almost always already there — and when it is not, the surface draws nothing
// rather than a guess, which is why this is a convenience rather than a
// correctness fix.
func (h *hostWorld) prime() {
	h.duty.run("chatv3/host-world-prime", "", h.fetch)
}

// hostLedger keeps the far ledger off the surface goroutine. A wider window
// replaces the held floor; paging forward then reads the same held slice.
type hostLedger struct {
	ask         func(time.Time) (remote.LedgerReading, error)
	duty        hostDuty
	mu          sync.Mutex
	lines       []session.UsageLine
	held, known bool
	floor       time.Time
}

func newHostLedger(far hostFar) *hostLedger {
	h := &hostLedger{ask: far.client.Ledger}
	far.arm(&h.duty, "reading what has been spent")
	return h
}

// hostLedgerEvery is how stale a held reading of the far ledger is allowed to be
// before the next reading asks for a fresh one behind itself.
//
// IT IS THE ONE THING THAT MADE THE SPEND PLACE A PHOTOGRAPH. What is held used
// to be replaced only when a WIDER window was asked for, so a launch's prime
// answered the whole fourteen days and every reading after it was served out of
// that answer for the life of the process: a conversation that spent money in
// front of somebody left `nothing spent yet — the first model call writes a line
// here` on the page under it, because the only reading the surface ever took was
// the one from before the call. The local seam re-reads the file on home's own
// three-second beat (place_spend.go), and this is that beat said over a wire.
//
// It matches [hostWorldEvery] because it answers the same kind of question — a page a person is looking at right now, about
// facts that move while they look — and because both are read on the frame.
const hostLedgerEvery = 2 * time.Second

func (h *hostLedger) prime() { h.start(time.Now().AddDate(0, 0, -14)) }
func (h *hostLedger) read(since time.Time) ([]session.UsageLine, bool, bool) {
	lines, held, known, floor, need := h.snapshot(since)
	switch {
	case need:
		h.start(since)
	case h.duty.due("", hostLedgerEvery):
		// AND THE REFRESH NEVER ASKS FOR LESS THAN IS ALREADY HELD. The floor is
		// replaced by whatever the last trip asked for, so a beat that re-asked
		// with the CURRENT view's `since` would throw away the fortnight the prime
		// fetched every time somebody looked at today — and the next reading of the
		// chart would find the window too narrow and fetch it all over again, on
		// every beat, for ever.
		if floor.Before(since) {
			since = floor
		}
		h.start(since)
	}
	return lines, held, known
}

// snapshot is what is held, how far back it reaches and whether a wider window
// is wanted, under the lock held from a defer.
func (h *hostLedger) snapshot(since time.Time) (lines []session.UsageLine, held, known bool, floor time.Time, need bool) {
	h.mu.Lock()
	defer h.mu.Unlock()
	lines = append([]session.UsageLine(nil), h.lines...)
	held, known, floor = h.held, h.known, h.floor
	need = !known || since.Before(h.floor)
	return lines, held, known, floor, need
}
func (h *hostLedger) start(since time.Time) {
	h.duty.run("chatv3/host-ledger", "", func() {
		reading, err := h.ask(since)
		if err != nil {
			return
		}
		h.mu.Lock()
		defer h.mu.Unlock()
		h.lines, h.held, h.known, h.floor = reading.Lines, reading.Held, true, since
	})
}

// hostMemory caches the two readings used by drawing. The deliberate write and
// provenance methods remain synchronous because they are reached only by an
// explicit key and their answer decides what the surface may say happened.
type hostMemory struct {
	requestedLimit int
	client         *remote.Client
	duty           hostDuty
	mu             sync.Mutex
	shelves        store.MemoryShelves
	learned, letGo int
	known          bool
}

func newHostMemory(far hostFar) *hostMemory {
	h := &hostMemory{client: far.client}
	far.arm(&h.duty, "reading what is remembered")
	return h
}
func (h *hostMemory) prime() { h.refresh(500, time.Time{}) }

// requestRows keeps the user's expanded window without holding the lock across
// background scheduling or any network call.
func (h *hostMemory) requestRows(limit int) int {
	h.mu.Lock()
	defer h.mu.Unlock()
	h.requestedLimit = max(h.requestedLimit, limit)
	return h.requestedLimit
}

func (h *hostMemory) needsRows(limit int) bool {
	h.mu.Lock()
	defer h.mu.Unlock()
	return limit > h.requestedLimit
}

func (h *hostMemory) refresh(limit int, at time.Time) {
	limit = h.requestRows(limit)
	h.duty.run("chatv3/host-memory", "", func() {
		s, err := h.client.Snapshot(limit)
		learned, letGo, changedErr := h.client.ChangedSince(at)
		if err != nil || changedErr != nil {
			return
		}
		h.mu.Lock()
		defer h.mu.Unlock()
		h.shelves, h.learned, h.letGo, h.known = s, learned, letGo, true
	})
}
func (h *hostMemory) Snapshot(limit int) (store.MemoryShelves, error) {
	s, _, _, known := h.snapshot()
	needsMore := h.needsRows(limit)
	if !known || needsMore {
		h.refresh(limit, time.Time{})
	}
	return s, nil
}
func (h *hostMemory) ChangedSince(at time.Time) (int, int, error) {
	_, learned, letGo, _ := h.snapshot()
	h.refresh(500, at)
	return learned, letGo, nil
}

// snapshot is what is held, under the lock held from a defer.
func (h *hostMemory) snapshot() (shelves store.MemoryShelves, learned, letGo int, known bool) {
	h.mu.Lock()
	defer h.mu.Unlock()
	return h.shelves, h.learned, h.letGo, h.known
}
func (h *hostMemory) UpdateMemory(id, text string) error {
	err := h.client.UpdateMemory(id, text)
	h.refresh(500, time.Time{})
	return err
}
func (h *hostMemory) ForgetMemory(id string) error {
	err := h.client.ForgetMemory(id)
	h.refresh(500, time.Time{})
	return err
}
func (h *hostMemory) RestoreMemory(id string) error {
	err := h.client.RestoreMemory(id)
	h.refresh(500, time.Time{})
	return err
}
func (h *hostMemory) MemoryProvenance(id string) (string, string, time.Time, error) {
	return h.client.MemoryProvenance(id)
}