@pellux/goodvibes-tui 1.27.0 → 2.0.1

package/src/runtime/client/build-floors.ts

@@ -0,0 +1,167 @@
+/**
+ * build-floors.ts — the two build floors this terminal and the daemon hold
+ * against each other.
+ *
+ * ── Forward: the daemon's floor on this client ────────────────────────────
+ *
+ * A daemon update swaps the daemon binary and nothing else. This terminal keeps
+ * running the build it started with: same rules, same bugs, still registered in
+ * the shared session store, still able to execute shared-session work. That is
+ * how a behavioral fix can land in the daemon, be verified present in the
+ * installed binaries, and still not change what the owner observes — an older
+ * terminal beside the new daemon simply keeps doing the old thing.
+ *
+ * So the daemon publishes the minimum client build it will let participate, as
+ * an `X-Goodvibes-Client-Floor` response header on `/status`. Below that floor
+ * this terminal says so plainly and stops taking shared-session work, rather
+ * than quietly executing under superseded rules until someone notices.
+ *
+ * ── Reverse: this client's floor on the daemon ────────────────────────────
+ *
+ * The exposure runs the other way too. This terminal is a pure client: it talks
+ * to a daemon it did not start, over a base URL that may point at another
+ * machine, and every capability it has is something the daemon performs on its
+ * behalf. A verb it depends on may simply not exist in the build that answers,
+ * and what the owner sees then is a 400 or a 404 on one call — which reads as a
+ * broken feature rather than as an old daemon. So this terminal declares the
+ * oldest daemon build it can work against and checks it on attach against the
+ * `version` `/status` already returns, refusing to adopt a daemon below it.
+ *
+ * ── Where these rules live ────────────────────────────────────────────────
+ *
+ * Both comparisons — the header name, the verdict shapes, the version ordering
+ * — are owned by the SDK (platform/control-plane/client-compatibility.ts and
+ * daemon-compatibility.ts) and imported below rather than duplicated. What
+ * stays here is this process's own state: the forward latch, the reverse
+ * announce-once, and the daemon floor this product declares. The agent holds
+ * the same forward latch shape for its own process lifetime, which is why the
+ * latch is not a value the SDK ships.
+ */
+
+import {
+  evaluateClientCompatibility,
+  evaluateDaemonStatusCompatibility,
+  type ClientCompatibilityVerdict,
+  type DaemonCompatibilityVerdict,
+} from '@pellux/goodvibes-sdk/platform/control-plane';
+
+/**
+ * The oldest daemon build this terminal will adopt.
+ *
+ * 1.28.0 is the daemon release in which the daemon became its own product and
+ * this terminal became a pure client of it: the session register, the inbound
+ * steer queue, the fleet needs-input push and the credential writes this build
+ * calls are all served there. An older daemon answers some of those and not
+ * others, which is the half-working state this floor exists to stop.
+ *
+ * Raise this only for a daemon behavior this terminal MUST have, and say in the
+ * release notes what it was raised for. It costs a daemon update for anyone
+ * running an older one.
+ */
+export const TUI_DAEMON_BUILD_FLOOR = '1.28.0';
+
+export interface ClientBuildGuardOptions {
+  readonly clientVersion: string;
+}
+
+/**
+ * The live forward verdict for this process, updated by whatever reads the
+ * daemon's floor (the attach handshake) and consulted by whatever would execute
+ * shared-session work (the continuation runner).
+ *
+ * Latching is deliberate: once a daemon has told this process it is too old, a
+ * later read that fails to see the header (a restart, a truncated response)
+ * must not silently re-enable work.
+ *
+ * The notice sink is attached after construction — this guard is built in the
+ * services composition root, and the surface that renders its one line is wired
+ * in the bootstrap tail. A verdict reached before the sink attaches is held and
+ * delivered on attach, the same buffered-until-attach idiom the daemon receipt
+ * notices use, so a refusal is never the message nobody saw.
+ */
+export class ClientBuildGuard {
+  private verdict: ClientCompatibilityVerdict;
+  private announced = false;
+  private notify: ((verdict: ClientCompatibilityVerdict) => void) | null = null;
+  private pending: ClientCompatibilityVerdict | null = null;
+
+  constructor(private readonly options: ClientBuildGuardOptions) {
+    this.verdict = {
+      status: 'ok',
+      message: 'No daemon floor observed yet.',
+      clientVersion: options.clientVersion,
+      floor: undefined,
+    };
+  }
+
+  /**
+   * Attach the surface that renders the one line telling the owner to restart.
+   * Flushes a verdict already reached before this call.
+   */
+  onRestartRequired(notify: (verdict: ClientCompatibilityVerdict) => void): void {
+    this.notify = notify;
+    const held = this.pending;
+    this.pending = null;
+    if (held) notify(held);
+  }
+
+  /** Feed a floor read from a daemon `/status` response. */
+  observeFloor(floor: string | undefined): ClientCompatibilityVerdict {
+    if (this.verdict.status === 'restart-required') return this.verdict;
+    const next = evaluateClientCompatibility({ clientVersion: this.options.clientVersion, floor });
+    this.verdict = next;
+    if (next.status === 'restart-required' && !this.announced) {
+      this.announced = true;
+      if (this.notify) this.notify(next);
+      else this.pending = next;
+    }
+    return next;
+  }
+
+  /** False once this build has been judged too old for the live daemon. */
+  maySharedSessionWork(): boolean {
+    return this.verdict.status !== 'restart-required';
+  }
+
+  current(): ClientCompatibilityVerdict {
+    return this.verdict;
+  }
+}
+
+/**
+ * The reverse half: this terminal's verdict on the daemon answering at a base
+ * URL, held across attaches so a reconnect loop against one old daemon states
+ * the problem once instead of on every poll.
+ *
+ * Unlatched, unlike the forward guard: a daemon CAN become new enough while
+ * this terminal runs — that is exactly what a daemon update does — and the
+ * attach that sees the newer build must adopt it. What is remembered is only
+ * which sentence has already been said.
+ */
+export class DaemonBuildFloor {
+  private announced: string | null = null;
+
+  constructor(private readonly floor: string = TUI_DAEMON_BUILD_FLOOR) {}
+
+  /**
+   * Judge a parsed `/status` body. `daemonLabel` names the peer in the sentence
+   * so an operator with two daemons on the LAN learns WHICH one is old.
+   */
+  evaluate(statusPayload: unknown, daemonLabel: string): DaemonCompatibilityVerdict {
+    return evaluateDaemonStatusCompatibility(statusPayload, this.floor, daemonLabel);
+  }
+
+  /**
+   * The line to show for a verdict, or null when this exact sentence has
+   * already been shown (or there is nothing to say).
+   */
+  noticeFor(verdict: DaemonCompatibilityVerdict): string | null {
+    if (verdict.status === 'ok') {
+      this.announced = null;
+      return null;
+    }
+    if (this.announced === verdict.message) return null;
+    this.announced = verdict.message;
+    return verdict.message;
+  }
+}

package/src/runtime/client/daemon-attach-handshake.ts

@@ -0,0 +1,115 @@
+/**
+ * daemon-attach-handshake.ts — attaching to a daemon is a handshake, not a
+ * pointer swap.
+ *
+ * ONE `/status` read carries the three things this terminal has to settle
+ * before it mirrors anything to a daemon, and as a pure client there is no
+ * in-process daemon handle to fold any of them from:
+ *
+ *  - The DAEMON's own build. Every capability here is something the daemon
+ *    performs on this terminal's behalf, so a daemon below this build's floor
+ *    is refused rather than adopted — otherwise a verb it does not serve
+ *    surfaces as one broken feature instead of as an old daemon, and the
+ *    terminal keeps running half-working against a peer it has no reason to
+ *    suspect. Refused means local-only, which is a state this app already
+ *    renders honestly.
+ *  - The minimum CLIENT build the daemon accepts. Below it the guard latches
+ *    and the continuation runner stops taking shared-session work.
+ *  - Its undelivered receipts (update applied, restarted after a crash,
+ *    settings migrated), read from `/status?receipts=consume` where delivery is
+ *    destructive — so the read that consumed them is the read that renders
+ *    them.
+ *
+ * Every one of those is decided from the same response, which is why this is
+ * one function and not three callers each making their own read.
+ *
+ * A daemon that goes away and comes back gets the handshake again, off the
+ * liveness flip a caller already observes rather than a timer of this module's
+ * own: for an already-adopted daemon, coming back up is what its hourly
+ * self-update looks like from here, and the build that came back may not be the
+ * build that left. The flip an adoption's own first refresh causes runs the
+ * handshake once more too; that costs one /status GET and is the price of never
+ * having to decide which online flip is "really" a reconnect.
+ */
+
+import type { HostServiceStatus } from '@/runtime/index.ts';
+import { readExternalDaemonAttach } from '../daemon-attach-notices.ts';
+import { ClientBuildGuard, DaemonBuildFloor } from './build-floors.ts';
+
+export interface DaemonAttachHandshakeDeps {
+  /** The forward floor's latch — fed the floor this daemon announces. */
+  readonly clientBuildGuard: ClientBuildGuard;
+  /** The daemon this terminal is currently pointed at. Re-read on every attach. */
+  readonly readDaemonStatus: () => HostServiceStatus;
+  /**
+   * Record a refusal on the status every reader already consults, so the footer
+   * and `/status` report "a daemon is there and this build will not adopt it"
+   * rather than claiming a working mirror.
+   */
+  readonly recordRefusal: (status: HostServiceStatus) => void;
+  /** Bring the session and memory spines up against this daemon (or take them down). */
+  readonly adopt: (status: HostServiceStatus, daemonToken: string) => void;
+  /** Where a daemon notice is shown to the owner. */
+  readonly notify: (text: string) => void;
+  /** This terminal's own floor on the daemon; defaults to the shipped one. */
+  readonly daemonFloor?: string | undefined;
+  /** Injectable `/status` read for tests. */
+  readonly read?: typeof readExternalDaemonAttach | undefined;
+}
+
+export interface DaemonAttachHandshake {
+  /** Run the handshake against the current daemon status, then adopt or refuse. */
+  attach(daemonToken: string): Promise<void>;
+  /** Feed the adopted daemon's liveness flips; a flip to online re-handshakes. */
+  onLivenessTransition(online: boolean): void;
+}
+
+export function createDaemonAttachHandshake(deps: DaemonAttachHandshakeDeps): DaemonAttachHandshake {
+  const daemonBuildFloor = new DaemonBuildFloor(deps.daemonFloor);
+  const read = deps.read ?? readExternalDaemonAttach;
+  let lastDaemonToken: string | null = null;
+  // The forward floor's one line. The guard latches in the services graph,
+  // where the continuation runner reads it; this is the surface that tells the
+  // owner, and a verdict reached before now is held and delivered here.
+  deps.clientBuildGuard.onRestartRequired((verdict) => deps.notify(verdict.message));
+
+  const handshake: DaemonAttachHandshake = {
+    onLivenessTransition(online) {
+      if (online && lastDaemonToken !== null) void handshake.attach(lastDaemonToken);
+    },
+    async attach(daemonToken) {
+      lastDaemonToken = daemonToken;
+      const daemonStatus = deps.readDaemonStatus();
+      if (daemonStatus.mode !== 'external' || !daemonStatus.baseUrl) {
+        deps.adopt(daemonStatus, daemonToken);
+        return;
+      }
+      const answer = await read({
+        baseUrl: daemonStatus.baseUrl,
+        authToken: daemonToken,
+        consumeReceipts: true,
+      });
+      // Nothing was read, so nothing is known — adopt as before and leave a
+      // daemon that is not answering to the spine's own reachability handling.
+      // Refusing on a failed read would turn one dropped request into a lost
+      // mirror.
+      if (!answer.answered) {
+        deps.adopt(daemonStatus, daemonToken);
+        return;
+      }
+      const verdict = daemonBuildFloor.evaluate(answer.statusPayload, daemonStatus.baseUrl);
+      const notice = daemonBuildFloor.noticeFor(verdict);
+      if (notice) deps.notify(notice);
+      if (verdict.status === 'daemon-update-required') {
+        const refused: HostServiceStatus = { ...daemonStatus, mode: 'incompatible', reason: verdict.message };
+        deps.recordRefusal(refused);
+        deps.adopt(refused, daemonToken);
+        return;
+      }
+      deps.clientBuildGuard.observeFloor(answer.clientFloor);
+      deps.adopt(daemonStatus, daemonToken);
+      for (const receipt of answer.notices) deps.notify(receipt);
+    },
+  };
+  return handshake;
+}

package/src/runtime/client/fleet-union.ts

@@ -0,0 +1,147 @@
+/**
+ * fleet-union.ts — the Fleet panel shows everything running, not just what this
+ * terminal started.
+ *
+ * ── What moved to the SDK, and what stays here ────────────────────────────
+ *
+ * The SDK's `@pellux/goodvibes-sdk/platform/runtime/client` now owns the
+ * policy every surface needs for this: `createDaemonFleetRowsPoller` (the poll
+ * cadence and last-known-rows retention when a poll fails), `mergeFleetNodes`
+ * (the local-wins dedupe by node id) and `daemonOnlyFleetActRefusal` (the
+ * reason string a steer/archive against a daemon-only row gets, rather than a
+ * bare false). This module is now a thin wrapper over that policy.
+ *
+ * What stays here is the panel binding: the TUI's own `FleetReadModel`
+ * interface (interrupt/resume/kill/steer/archive, subscribe, snapshots) and
+ * `buildFleetSnapshot`, the tree-builder + honest cost/token aggregator this
+ * repo's Fleet panel renders from. Rebuilding through the SAME builder the
+ * local view uses — rather than summing two halves — is what keeps the
+ * rollups, the cost/token totals and the blocked-on-user ordering computed
+ * once, over the whole fleet.
+ *
+ * ── Who wins ──────────────────────────────────────────────────────────────
+ *
+ * Local rows are AUTHORITATIVE for processes this terminal spawned. They are
+ * live — the registry pushes on every state change, with sub-second latency —
+ * and they carry the capabilities that make a row actionable here (interrupt,
+ * resume, kill, steer all reach a real child process). The daemon's copy of
+ * the same row, arriving over a poll, is necessarily staler; where both
+ * describe the same node id, the local one is kept (`mergeFleetNodes`).
+ *
+ * ── Acting on a row you do not own ────────────────────────────────────────
+ *
+ * `interrupt`/`resume`/`kill`/`steer` reach this process's own children. A
+ * daemon row has no child here to signal, so those refuse — and `steer`,
+ * which has a reason channel, says why rather than returning a bare false
+ * that reads as "the agent ignored you". The panel's own act surface
+ * (fleet-gateway.ts) already drives the daemon's verbs for the acts the
+ * daemon serves.
+ */
+import {
+  createDaemonFleetRowsPoller,
+  daemonOnlyFleetActRefusal,
+  DEFAULT_FLEET_REFRESH_MS,
+  mergeFleetNodes,
+  readDaemonFleetRows,
+  type DaemonFleetRows,
+  type DaemonFleetRowsPoller,
+  type DaemonFleetRowsPollerOptions,
+  type DaemonVerbCaller,
+} from '@pellux/goodvibes-sdk/platform/runtime/client';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils';
+import { buildFleetSnapshot, type FleetReadModel, type FleetSnapshot } from '../../panels/fleet-read-model.ts';
+
+/** Re-exported so an importer that only needs the SDK's policy has one import site. */
+export { DEFAULT_FLEET_REFRESH_MS, daemonOnlyFleetActRefusal, mergeFleetNodes, readDaemonFleetRows };
+export type { DaemonFleetRows, DaemonFleetRowsPoller, DaemonFleetRowsPollerOptions };
+
+export interface FleetUnionOptions {
+  /** This surface's own live registry view — authoritative for what it spawned. */
+  readonly local: FleetReadModel;
+  readonly verbs: DaemonVerbCaller;
+  readonly refreshIntervalMs?: number;
+  readonly log?: Pick<typeof logger, 'debug'>;
+}
+
+export interface FleetUnionReadModel extends FleetReadModel {
+  /** Stop the refresh timer. Idempotent. */
+  stop(): void;
+  /** Re-read the daemon's rows now. Never throws. */
+  refresh(): Promise<void>;
+}
+
+/** How this terminal names itself in a daemon-only-row act refusal. */
+const SURFACE_LABEL = 'this terminal';
+
+/**
+ * Wrap a local fleet read model so its snapshot also carries the adopted
+ * daemon's rows, over the SDK's poll/merge/refusal policy.
+ *
+ * Inert until the first poll lands: before then, and whenever the daemon
+ * cannot answer, the snapshot is exactly the local one — which is the honest
+ * answer, not a degraded one. A daemon that stops answering keeps its LAST
+ * known rows rather than dropping them (the poller's own retention), so a
+ * momentary blip does not make half the fleet blink out and back.
+ */
+export function createFleetUnionReadModel(options: FleetUnionOptions): FleetUnionReadModel {
+  const local = options.local;
+  const poller = createDaemonFleetRowsPoller({
+    verbs: options.verbs,
+    ...(options.refreshIntervalMs === undefined ? {} : { refreshIntervalMs: options.refreshIntervalMs }),
+    ...(options.log === undefined ? {} : { log: options.log }),
+  });
+
+  const listeners = new Set<() => void>();
+  const unsubscribePoller = poller.subscribe(() => {
+    for (const listener of listeners) listener();
+  });
+
+  /** Ids this surface owns right now — the set the daemon's copy defers to. */
+  const localNodeIds = (snapshot: FleetSnapshot): Set<string> =>
+    new Set(snapshot.rows.map((row) => row.node.id));
+  const isLocalId = (id: string): boolean => localNodeIds(local.getSnapshot()).has(id);
+
+  return {
+    getSnapshot(): FleetSnapshot {
+      const localSnapshot = local.getSnapshot();
+      const daemonRows = poller.rows();
+      if (!daemonRows || daemonRows.nodes.length === 0) return localSnapshot;
+      const merged = mergeFleetNodes(localSnapshot.rows.map((row) => row.node), daemonRows.nodes);
+      // Rebuilt through the SAME builder the local view uses, so the rollups,
+      // the cost/token totals and the blocked-on-user ordering are computed
+      // once, over the whole fleet, rather than summed from two halves.
+      return buildFleetSnapshot(merged, Math.max(localSnapshot.capturedAt, daemonRows.capturedAt));
+    },
+
+    subscribe(listener: () => void): () => void {
+      listeners.add(listener);
+      const unsubscribeLocal = local.subscribe(listener);
+      return () => {
+        listeners.delete(listener);
+        unsubscribeLocal();
+      };
+    },
+
+    interrupt: (id) => local.interrupt(id),
+    resume: (id) => local.resume(id),
+    kill: (id, opts) => local.kill(id, opts),
+    steer: (id, text) => (isLocalId(id)
+      ? local.steer(id, text)
+      : { queued: false, reason: daemonOnlyFleetActRefusal(id, SURFACE_LABEL) }),
+    subscribeConsumed: (listener) => local.subscribeConsumed(listener),
+    // The archive is this surface's own view state; the daemon keeps its own.
+    getArchivedSnapshot: () => local.getArchivedSnapshot(),
+    archive: (id) => (isLocalId(id)
+      ? local.archive(id)
+      : { archived: false, count: 0, reason: daemonOnlyFleetActRefusal(id, SURFACE_LABEL) }),
+    archiveFinished: () => local.archiveFinished(),
+    unarchive: (id) => local.unarchive(id),
+
+    refresh: () => poller.refresh(),
+    stop(): void {
+      poller.stop();
+      unsubscribePoller();
+      listeners.clear();
+    },
+  };
+}

package/src/runtime/client/host-service-status.ts

@@ -0,0 +1,71 @@
+/**
+ * host-service-status.ts — reading a background service's posture.
+ *
+ * Three questions the composition root asks about the daemon and the webhook
+ * listener, none of which need anything from the composition itself: what URL
+ * a configured host/port is reachable at, what to report before the discovery
+ * probe has finished, and whether a given verdict means "usable" or "the port
+ * is held and this terminal cannot have it".
+ */
+
+import type { HostServiceStatus } from '@/runtime/index.ts';
+import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+
+/** Which of the two background services a question is about. */
+export type HostServiceName = 'daemon' | 'httpListener';
+
+/**
+ * The URL a configured host/port is actually reachable at. A wildcard bind is
+ * not an address anything can connect to, so `0.0.0.0` and `::` resolve to the
+ * loopback address of their family; a bare IPv6 literal is bracketed.
+ */
+export function formatHostServiceBaseUrl(host: string, port: number): string {
+  const normalized = host.trim().toLowerCase();
+  const probeHost = normalized === '0.0.0.0'
+    ? '127.0.0.1'
+    : normalized === '::' || normalized === '[::]'
+      ? '::1'
+      : host;
+  const urlHost = probeHost.includes(':') && !probeHost.startsWith('[') ? `[${probeHost}]` : probeHost;
+  return `http://${urlHost}:${port}`;
+}
+
+/**
+ * What to report about a service before the discovery probe has answered:
+ * where it WOULD be, and the honest reason nothing is known about it yet.
+ */
+export function createPendingServiceStatus(
+  configManager: Pick<ConfigManager, 'get'>,
+  service: HostServiceName,
+): HostServiceStatus {
+  const host = String(configManager.get(service === 'daemon' ? 'controlPlane.host' : 'httpListener.host') ?? '127.0.0.1');
+  const port = Number(configManager.get(service === 'daemon' ? 'controlPlane.port' : 'httpListener.port') ?? (service === 'daemon' ? 3421 : 3422));
+  return {
+    mode: 'unavailable',
+    host,
+    port,
+    baseUrl: formatHostServiceBaseUrl(host, port),
+    reason: 'Background service startup has not completed yet',
+  };
+}
+
+/**
+ * A service this terminal can actually use. Called for both the daemon and the
+ * HTTP listener (see bootstrap.ts), so the 'embedded' arm stays live: the SDK
+ * always reports its in-process HTTP listener as 'embedded', even though this
+ * product's daemon status can never carry that mode (adoptOnly is hardcoded on
+ * every host-services call this app makes).
+ */
+export function hostServiceIsActive(status: HostServiceStatus): boolean {
+  return status.mode === 'embedded' || status.mode === 'external';
+}
+
+/**
+ * The configured port is held and unusable by this terminal — either by an
+ * unverified process ('blocked') or by a GoodVibes daemon this build refused to
+ * adopt ('incompatible': a wire-version mismatch, or a daemon below this
+ * build's own floor).
+ */
+export function hostServiceIsBlocked(status: HostServiceStatus): boolean {
+  return status.mode === 'blocked' || status.mode === 'incompatible';
+}

package/src/runtime/client/hosted-exit.ts

@@ -0,0 +1,86 @@
+/**
+ * hosted-exit.ts — leaving a hosted session because the terminal is closing.
+ *
+ * ── Why this exists at all ────────────────────────────────────────────────
+ *
+ * The detach policy is applied when the LAST attached client detaches. A
+ * terminal that simply exits never detaches: the daemon keeps this window in
+ * `attachedClients` forever, so a `kill`-policy session — the shipped default,
+ * and the behavior closing a client has always had — would quietly NOT be
+ * killed, and would sit there attached to a process that no longer exists.
+ *
+ * That is not a cosmetic gap. The owner's ruling is that the capability lands
+ * while the familiar default is preserved: quitting ends the work unless the
+ * user asked for `survive`. Preserving it requires the quit to actually say so.
+ *
+ * ── Bounded, and never able to hold the exit open ─────────────────────────
+ *
+ * The app's shutdown races a hard timeout; a detach is one small round trip to
+ * a daemon on loopback, but a daemon that has stopped answering must not add a
+ * hang to an exit that is already restoring the user's terminal. So this is
+ * bounded on its own and every failure is swallowed after being logged: the
+ * worst case is the session keeping a stale attachment, which the daemon's own
+ * housekeeping is what resolves, not this process.
+ */
+import { logger, summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+import { createDaemonVerbCaller } from './operator-endpoint.ts';
+import { createHostedSessionsClient } from './hosted-sessions.ts';
+import { getSharedHostedSessionFeed, type HostedSessionFeed } from '../../panels/hosted-session-feed.ts';
+
+/** How long the exit will wait for the detach before giving up on it. */
+export const HOSTED_DETACH_ON_EXIT_TIMEOUT_MS = 1_500;
+
+export interface LeaveHostedSessionOnExitOptions {
+  readonly configManager: ConfigManager;
+  readonly homeDirectory: string | (() => string);
+  /** Defaults to the shared feed the `/hosted` command and the panel use. */
+  readonly feed?: HostedSessionFeed | undefined;
+  readonly timeoutMs?: number | undefined;
+}
+
+/**
+ * Detach from whatever hosted session this terminal is attached to, so the
+ * daemon applies the policy the record has been advertising all along.
+ *
+ * Resolves to what happened, for a caller that wants to say so: `'none'` when
+ * nothing was attached, `'detached'` when the daemon answered, `'failed'` when
+ * it did not. Never throws and never runs past its own budget.
+ */
+export async function leaveHostedSessionOnExit(
+  options: LeaveHostedSessionOnExitOptions,
+): Promise<'none' | 'detached' | 'failed'> {
+  const feed = options.feed ?? getSharedHostedSessionFeed();
+  const record = feed.getState().record;
+  // Closing the socket is this process's own business and is done either way —
+  // an already-terminated session has nothing to detach from, but the stream
+  // watching it is still open.
+  feed.closeStream();
+  if (!record || record.status === 'terminated') return 'none';
+
+  const client = createHostedSessionsClient(createDaemonVerbCaller({
+    configManager: options.configManager,
+    homeDirectory: options.homeDirectory,
+  }));
+  const timeoutMs = options.timeoutMs ?? HOSTED_DETACH_ON_EXIT_TIMEOUT_MS;
+  try {
+    const outcome = await Promise.race([
+      client.detach(record.id).then(() => 'detached' as const),
+      new Promise<'failed'>((resolve) => {
+        const timer = setTimeout(() => resolve('failed'), timeoutMs);
+        timer.unref?.();
+      }),
+    ]);
+    if (outcome === 'failed') {
+      logger.debug('[hosted-sessions] the detach-on-exit did not complete in time', {
+        sessionId: record.id, timeoutMs,
+      });
+    }
+    return outcome;
+  } catch (error) {
+    logger.debug('[hosted-sessions] the detach-on-exit was refused', {
+      sessionId: record.id, error: summarizeError(error),
+    });
+    return 'failed';
+  }
+}