pi-straw-boss 0.37.1 → 0.38.0

package/README.md

@@ -36,7 +36,7 @@ Run a few agents on the same project and they start stepping on each other: two
 - **Tidy tabs.** When a pi starts in a tab or quits out of it, the tab's panes are made equal again, so workers split off one by one don't leave a chain of halves.
 - **Stranded subagents are asked to report.** A subagent that stays open after finishing, while the pi that launched it was restarted and no longer receives its result, is asked once over intercom to send its final report there ([how it works](docs/how-it-works.md#orphaned-subagents)).
 - **A net view in Herdr's sidebar.** An optional plugin turns the Agents list into the net, towers first and each subagent under its launcher, on by default and switched by one key.
-- **A reaper for leftover worktree panes.** A second optional plugin closes the panes agents leave behind in worktree workspaces, removes the clean checkouts, and keeps the workspaces you pin.
+- **A reaper for leftover worktree panes.** A second optional plugin closes the panes agents leave behind in worktree workspaces, removes the clean checkouts nothing holds, and keeps the workspaces you pin.
 
 ## Install
 
@@ -89,7 +89,7 @@ The tower only routes and coordinates, so it can run a lighter model: set `tower
 | `/boss close all` | Quit this base's tower, mains, and members and close it with its shells, without stashing. It is checked first as a stash checks it; anything running that would be lost (a turn, a queued message, a dialog, a monitor, a subagent, a busy shell) closes nothing, and every reason is listed. Other bases are never touched. |
 | Stash, Stashed, Pop on the page | A base's Stash puts it away under its label; the HUD's Stashed list opens each one again with Pop. A base's Quit is checked first, as `/boss close all` is. |
 | `/boss stash [name]`, `/boss pop [name]` | Put this whole base away (its tower, mains, members, and idle shells) and close it; open it again later, every pi resumed from its own session file in its old role. A stash refuses, naming why, while anything a resume would lose is there: a running turn, a queued message, an open dialog, a running monitor, a subagent, or a busy shell. |
-| `/boss gui`, `/boss gui stop` | Open the net in the browser (any session, joins nothing); stop its server, from any session. The machine runs one server on one URL: it comes back after its session's `/reload`, and a session on a newer pi-straw-boss takes it over, so open pages reload into the new version. Type into a session from its comms view, or work its terminal with the key pad under the terminal tile, or on a desktop by clicking into it and typing; answer a waiting `robot_hand` selector, `ask_user_question` questionnaire, or pi-code hook confirmation there or in its alert (so can any extension's `select` and `confirm`, also from a paired device; other dialogs show read-only, to answer in the terminal; `secret_drop` always takes its secret in the terminal, never on a page, local or over the tailnet, because pi-intercom identities are self-reported). Documents a session shows with [pi-herdr-doc-review](https://www.npmjs.com/package/pi-herdr-doc-review) 0.4.0 or newer open beside its comms: HTML in a sandboxed frame whose form answers the agent, text read-only. |
+| `/boss gui`, `/boss gui stop` | Open the net in the browser (any session, joins nothing); stop its server, from any session. The machine runs one server on one URL: it comes back after its session's `/reload`, another session takes it over within a few seconds when the session that runs it ends (a closed pane, a quit, a crash; towers first, and a session on an older pi-straw-boss than the server waits about six seconds, then takes it until the next newer session takes it back), a session that starts later brings back a server that is down, even after every session quit or the machine restarted, and a session on a newer pi-straw-boss takes it over, so open pages reload into the new version. Only `/boss gui stop` keeps it stopped, until the next `/boss gui`; `/boss stash` and `/boss close all` do not start a stopped server. Type into a session from its comms view, or work its terminal with the key pad under the terminal tile, or on a desktop by clicking into it and typing; answer a waiting `robot_hand` selector, `ask_user_question` questionnaire, or pi-code hook confirmation there or in its alert (so can any extension's `select` and `confirm`, also from a paired device; other dialogs show read-only, to answer in the terminal; `secret_drop` always takes its secret in the terminal, never on a page, local or over the tailnet, because pi-intercom identities are self-reported). Documents a session shows with [pi-herdr-doc-review](https://www.npmjs.com/package/pi-herdr-doc-review) 0.4.0 or newer open beside its comms: HTML in a sandboxed frame whose form answers the agent, text read-only. |
 | `/boss gui remote`, `/boss gui remote off` | Reach the GUI from your phone over your tailnet (`tailscale serve`, never Funnel): pair by QR code, and a phone stays paired (90 days from its last use, restarts and `remote off` included) until you unpair it in the Phone tile; remote access stays on across a stop, a `/reload` and a new server until `remote off`; off removes only its own serve entry. The serve entry points at a second loopback listener of the GUI server, so a request is remote because of the listener it arrived on, whatever headers it carries. |
 
 Subagents and sessions in Herdr worktree workspaces never join: the session that launched them speaks for them. Outside Herdr the extension does nothing.
@@ -129,6 +129,7 @@ Run `herdr server reload-config` to load the key, and `herdr plugin unlink wayne
 A second optional Herdr plugin, in [`herdr-reaper/`](herdr-reaper), cleans up after agents that ran in worktree workspaces.
 In a workspace whose worktree is a linked git worktree (whatever its name), it closes the pane of an agent that has exited once the pane's shell is idle, and never the focused pane.
 Herdr then closes the tab and the workspace, and the plugin removes the workspace's checkout if `git status` is clean and nothing else is using it (no other pane works in it, no other workspace is open on it).
+A worktree that pi-herdr-agents created is kept until its parent session removes it with `worktree_remove`, for as long as the parent session is open in a Herdr pane (or, if it is not, until it has been silent for 72 hours, `retain_idle_hours`), and so is any checkout a process of yours has as its working directory.
 Git-ignored files (`.env`, `node_modules`, caches, local databases) do not make a checkout dirty, so they are deleted with it.
 The branch always stays, and so does a dirty checkout, with the reason in the plugin log.
 A checkout with initialized submodules is removed only when every submodule (nested ones too) has no uncommitted or untracked paths and its HEAD is contained in a remote-tracking ref (or in a ref of the main repository's own copy of the module), so no commit is lost; the reaper then runs `git submodule deinit --all`, deletes the worktree's `.git/worktrees/<id>/modules` (which git refuses to remove the worktree around), and runs a plain `git worktree remove`. Otherwise it stays and the log names the submodule and why; if a removal fails partway and leaves files git no longer tracks, the log says "half-removed" and names the directory for you to delete.

package/README.zh-TW.md

@@ -36,7 +36,7 @@
 - **分頁保持整齊。** pi 在分頁裡啟動或結束時，分頁裡的 pane 會重新平均分配，一個一個切出來的 worker 就不會留下一長串對半切的窄 pane。
 - **斷線的子智慧體會被提醒回報。** 子智慧體做完後還開著，但開出它的 pi 已經重開、收不到它的結果時，它會收到一則 intercom，請它把最終報告送回去，只會送一次（[運作方式](docs/how-it-works.md#orphaned-subagents)）。
 - **Herdr 側邊欄的網路檢視。** 一個選用的 plugin 會把 Agents 清單排成網的樣子：塔台在前，每個子智慧體排在開出它的人底下。預設開啟，按一個鍵就能切換。
-- **清理閒置的 worktree pane。** 另一個選用的 plugin 會關掉智慧體在 worktree 工作區留下的 pane，移除乾淨的 checkout，並保留你釘選的工作區。
+- **清理閒置的 worktree pane。** 另一個選用的 plugin 會關掉智慧體在 worktree 工作區留下的 pane，移除乾淨且沒有東西在用的 checkout，並保留你釘選的工作區。
 
 ## 安裝
 
@@ -88,7 +88,7 @@ pi install npm:pi-straw-boss
 | `/boss close all` | 讓這個基地的塔台、主智慧體和成員結束，連同 shell 一起關掉，不存 stash。會先用 stash 的同一套檢查；有會遺失的東西（正在跑的回合、排隊中的訊息、對話框、Monitor、子智慧體、前景有程式的 shell）就什麼都不關，並列出所有原因。其他基地完全不碰。 |
 | 網頁上的「收起」「已收起」「接回」 | 基地的「收起」以基地名稱收起它；上方的「已收起」列出收起的基地，按「接回」打開。基地的「關掉」會先檢查，和 `/boss close all` 一樣。 |
 | `/boss stash [名稱]`、`/boss pop [名稱]` | 把整個基地（塔台、主智慧體、成員和閒置的 shell）收起來並關掉；之後再打開，每個 pi 都從自己的 session 檔接回原本的角色。只要有接回後會遺失的東西就拒絕並說明原因：正在跑的回合、排隊中的訊息、開著的對話框、執行中的 Monitor、子智慧體，或前景有程式在跑的 shell。 |
-| `/boss gui`、`/boss gui stop` | 在瀏覽器開啟網（任何 session 都能開，不會加入任何東西）；停止它的伺服器，在哪個 session 都可以。整台機器只跑一個伺服器、一個網址：開它的 session `/reload` 之後，會在原網址重開；版本較新的 session 會接手，開著的頁面也會自動換成新版。可以在通訊畫面直接打字給某個 session，或用終端機畫面下方的按鍵面板操作它的終端機，在桌面上也可以點進終端機直接打字；在等回覆的 `robot_hand` 選單、`ask_user_question` 問卷或 pi-code 的 hook 確認，可以在那裡或它的警示裡作答（任何 extension 的 `select` 和 `confirm` 也可以，`confirm` 也可以從配對的裝置作答；其他對話框只能看，要回到終端機回答；`secret_drop` 的機密一律在終端機輸入，任何頁面（本機或 tailnet）都不接受，因為 pi-intercom 的身分是自己申報的，無法驗證）。session 用 [pi-herdr-doc-review](https://www.npmjs.com/package/pi-herdr-doc-review) 0.4.0 以上顯示的文件，會開在它的通訊畫面旁邊：HTML 放在沙箱框架裡，表單送出的答案會傳給智慧體；純文字只能讀。 |
+| `/boss gui`、`/boss gui stop` | 在瀏覽器開啟網（任何 session 都能開，不會加入任何東西）；停止它的伺服器，在哪個 session 都可以。整台機器只跑一個伺服器、一個網址：開它的 session `/reload` 之後，會在原網址重開；跑它的 session 結束時（關掉 pane、離開 pi、當機），另一個還開著的 session 會在幾秒內於原網址重開它（塔台優先；pi-straw-boss 版本比伺服器舊的 session 要等約六秒才接手，直到下一個較新的 session 再接回去）；之後才啟動的 session 也會把停著的伺服器重開，即使所有 session 都離開過或機器重開機；版本較新的 session 會接手，開著的頁面也會自動換成新版。只有 `/boss gui stop` 會讓它維持停止，直到下一次 `/boss gui`；`/boss stash` 和 `/boss close all` 不會把停著的伺服器重開。可以在通訊畫面直接打字給某個 session，或用終端機畫面下方的按鍵面板操作它的終端機，在桌面上也可以點進終端機直接打字；在等回覆的 `robot_hand` 選單、`ask_user_question` 問卷或 pi-code 的 hook 確認，可以在那裡或它的警示裡作答（任何 extension 的 `select` 和 `confirm` 也可以，`confirm` 也可以從配對的裝置作答；其他對話框只能看，要回到終端機回答；`secret_drop` 的機密一律在終端機輸入，任何頁面（本機或 tailnet）都不接受，因為 pi-intercom 的身分是自己申報的，無法驗證）。session 用 [pi-herdr-doc-review](https://www.npmjs.com/package/pi-herdr-doc-review) 0.4.0 以上顯示的文件，會開在它的通訊畫面旁邊：HTML 放在沙箱框架裡，表單送出的答案會傳給智慧體；純文字只能讀。 |
 | `/boss gui remote`、`/boss gui remote off` | 透過你的 tailnet 用手機連 GUI（`tailscale serve`，絕不用 Funnel）：掃 QR code 配對，手機配對後會一直有效（從最後一次使用起算 90 天，重啟與 `remote off` 都不影響），直到你在「手機」視窗解除配對；遠端存取在 stop、`/reload`、換新伺服器之後仍會保持開啟，直到 `remote off`；關閉時只移除它自己的 serve 設定。serve 指向 GUI 伺服器的第二個 loopback 監聽埠，請求算不算遠端取決於它進來的監聽埠，不看它帶什麼標頭。 |
 
 子智慧體，以及在 Herdr worktree 工作區裡的 session，都不會加入網，由開出它們的 session 代表它們。不在 Herdr 裡時，這個擴充套件什麼都不做。
@@ -128,6 +128,7 @@ description = "toggle the straw net view"
 另一個選用的 Herdr plugin 放在 [`herdr-reaper/`](herdr-reaper)，專門清理 worktree 工作區裡智慧體跑完留下的東西。
 只處理 worktree 是 linked git worktree 的工作區（不管它叫什麼名字）：智慧體結束、pane 的 shell 閒置之後，就關掉這個 pane，但絕不關掉有焦點的 pane。
 Herdr 接著會關掉分頁和工作區，plugin 再在 `git status` 乾淨、而且沒有別的東西還在用它（沒有別的 pane 在裡面工作，也沒有別的工作區開在同一個 checkout）時移除這個工作區的 checkout。
+pi-herdr-agents 建立的 worktree 會留著，直到它的父 session 用 `worktree_remove` 移除；父 session 只要還開在某個 Herdr pane 裡就一直留著，沒有開著時則等它靜默 72 小時（`retain_idle_hours`）；任何有你的行程以它為工作目錄的 checkout 也一樣不動。
 git 忽略的檔案（`.env`、`node_modules`、快取、本機資料庫）不算變更，所以會跟著 checkout 一起被刪掉。
 分支一律保留；有未提交變更的 checkout 也留著，原因寫在 plugin 日誌裡。
 含已初始化 submodule 的 checkout，只有在每個 submodule（含巢狀的）都沒有未提交或未追蹤的檔案，且 HEAD 已被某個 remote-tracking ref（或主儲存庫自己那份 module 的 ref）包含、不會遺失任何 commit 時才會移除：reaper 先跑 `git submodule deinit --all`，刪掉 worktree 的 `.git/worktrees/<id>/modules`（有它在，git 不肯移除 worktree），再跑不帶 `--force` 的 `git worktree remove`。不符合就保留，日誌會寫出是哪個 submodule、為什麼；若移除做到一半失敗、留下 git 已不再追蹤的檔案，日誌會寫「half-removed」並指出該目錄，由你自己刪除。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-straw-boss",
-  "version": "0.37.1",
+  "version": "0.38.0",
   "description": "Straw Boss coordination for pi in Herdr: sessions join a tab's net by choice, the first joiner is its main agent, a workspace tower opens on demand with a live monitoring dashboard, and boss_broadcast reaches the rest",
   "type": "module",
   "license": "MIT",

package/src/bridge.ts

@@ -29,7 +29,8 @@ import { type Monitor, trackMonitors } from "./monitors.ts";
 // into an impostor's hands): the bridge never relays a secret dialog, and refuses any answer to one.
 
 export const REGISTER = "intercom:extension-register";
-const VERDICT_MS = 2000, POLL_MS = 2000, KEEP_MS = 120_000, KEEP = 16, MAX_GUIS = 8, MAX_MESSAGE = 15 * 1024;
+// pi-intercom has no unregister: every host the session joins stays one of its channels, and the broker takes at most 32 per session (the tab, the viewer, and the hub's own take a few).
+const VERDICT_MS = 2000, POLL_MS = 2000, KEEP_MS = 120_000, KEEP = 16, MAX_GUIS = 16, MAX_MESSAGE = 15 * 1024;
 /** At most this many queued messages go to the GUI (the oldest, which are delivered first), each cut to this many characters. */
 export const MAX_QUEUED = 5, QUEUED_TEXT = 200;
 const clipQueued = (text: string) => (text.length > QUEUED_TEXT ? `${text.slice(0, QUEUED_TEXT - 1)}…` : text);
@@ -99,7 +100,7 @@ export function startBridge(pi: ExtensionAPI, { env, dir, local, close }: { env:
 		} catch {
 			g = undefined;
 		}
-		if (g && g !== me() && !chans.has(g)) join_(g);
+		if (g && g !== me() && !chans.has(g) && alive()) join_(g); // a host whose process is gone is not joined: the survivor that takes over rewrites gui.json within moments
 		push();
 		return true;
 	};

package/src/handover.ts

@@ -2,16 +2,29 @@ import { mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:f
 import { request } from "node:http";
 import { join } from "node:path";
 import { type Asked, type Gui, VERSION } from "./gui.ts";
+import { alive, runs, startOf } from "./remote.ts";
 
 // One server per machine. gui.json in the state directory records the running server (pid, local and remote port, token, owner session), and
 // gui.lock makes the check-and-start atomic, so a second /boss gui, from this session or another, opens the running server
 // instead of starting one. A dead server's port and token are reused, so a page left open reconnects to its successor. Any session reaches
 // the running one: it asks it to stop (requestStop), or takes it over, stopping it and starting its own on the same URL. A session whose
-// pi-straw-boss is newer takes it over unasked, so an update reaches every open page once one session has reloaded.
-/** `ownerSession` is the owner's intercom session id: bridges follow it to the server's dialog channel. `reload` marks a server its owner's /reload stopped. `remote` is only ever written by a build up to 0.32.1 (remote was on at that /reload); paired.json keeps the wish since. */
-export interface GuiRecord { pid: number; port: number; remotePort?: number; token: string; csrf?: string; owner: string; ownerSession?: string; version?: string; reload?: boolean; remote?: boolean }
-/** `stale`: the running server is older and could not be taken over. */
-export interface Shared { url: string; owner: string; mine?: Gui; stale?: boolean }
+// pi-straw-boss is newer takes it over unasked, so an update reaches every open page once one session has reloaded. When the session that runs it ends without a
+// stop, a survivor adopts it (adoptGui): the same port, token, and secret again, so a page left open reconnects by itself. The record tells the two endings apart.
+/**
+ * `ownerSession` is the owner's intercom session id: bridges follow it to the server's dialog channel. `started` is when the owner's process started, so a pid another
+ * process now holds is not taken for the owner; only a build that marks its stops writes it, so a record without it is never adopted (a server such a build stopped looks
+ * like one it quit). `herdr` is the socket of the Herdr server the server's net is read from: a session on another Herdr does not adopt it. `reload` marks a server its owner's
+ * /reload stopped. `stopped` marks one stopped on purpose (a stop from any session): no session starts it again until someone runs /boss gui. `remote` is only ever written by a
+ * build up to 0.32.1 (remote was on at that /reload); paired.json keeps the wish since.
+ */
+export interface GuiRecord { pid: number; started?: string; port: number; remotePort?: number; token: string; csrf?: string; owner: string; ownerSession?: string; version?: string; herdr?: string; reload?: boolean; stopped?: boolean; remote?: boolean }
+/**
+ * `stale`: the running server is older and could not be taken over. `from`: the owner whose end a survivor took the server over from. `moved`: the recorded port was taken, so the URL changed.
+ * `stopped`: it was stopped on purpose and `keep.stopped` left it so. `blind`: this process's start time could not be read, so the record it wrote has no `started` and no survivor adopts that server.
+ */
+export interface Shared { url: string; owner: string; mine?: Gui; stale?: boolean; from?: string; moved?: boolean; stopped?: boolean; blind?: boolean }
+/** What a start under gui.lock leaves alone: a server stopped on purpose, a server that is down. Only `/boss gui` starts either. */
+export interface Keep { stopped?: boolean; down?: boolean }
 
 /** Whether version `a` is newer than `b`; a server that recorded none predates the handover. */
 export function newer(a: string, b?: string) {
@@ -38,6 +51,35 @@ export function markReload(dir: string, pid = process.pid) {
 	if (record?.pid === pid) writeFileSync(join(dir, "gui.json"), JSON.stringify({ ...record, reload: true }), { mode: 0o600 });
 }
 
+/**
+ * Marks the record of the server `seen` names as stopped on purpose, so no survivor starts it again. A record of another server is left alone, and that includes a successor
+ * on the same port and token (a restart reuses both): the process and its start time must match too.
+ */
+export function markStopped(dir: string, seen: Pick<GuiRecord, "pid" | "started" | "port" | "token">) {
+	const record = readRecord(dir);
+	if (record?.pid === seen.pid && record.started === seen.started && record.port === seen.port && record.token === seen.token) writeFileSync(join(dir, "gui.json"), JSON.stringify({ ...record, stopped: true }), { mode: 0o600 });
+}
+
+/** Whether a survivor may take over `record`'s server: its writer marks stops (`started`), and it serves the survivor's own Herdr. */
+export const adoptable = (record: GuiRecord, { herdr }: { herdr: string }) => Boolean(record.started) && record.herdr === herdr;
+/** Whether the server is a newer build's than the survivor: an older survivor takes it only when no newer one has, and downgrades it until the next newer session takes it back. */
+export const downgrades = (record: GuiRecord, version: string) => Boolean(record.version && newer(record.version, version));
+
+/**
+ * A look at whether the process that recorded a server is gone for good, for a survivor to decide on: its pid is dead, or now belongs to another process (one that
+ * started at another time, or after an old record was written). A process confirmed as the recorder is afterwards looked at by signal alone, not by `ps`.
+ */
+export function ownerGone(start: (pid: number) => string | undefined = startOf): (record: GuiRecord, wrote: number) => boolean {
+	let confirmed: string | undefined;
+	return (record, wrote) => {
+		const key = `${record.pid}/${record.started ?? wrote}`;
+		if (confirmed === key) return !alive(record.pid);
+		if (!runs(record, wrote, start)) return true;
+		confirmed = key;
+		return false;
+	};
+}
+
 /** Asks a recorded server to stop, as its own page would, and waits until it is gone; false when it refused (a server from before 0.11.0) or stayed up. */
 export async function requestStop(r: GuiRecord, asked: Asked, sleep: (ms: number) => Promise<void>) {
 	const body = JSON.stringify(asked), origin = `http://127.0.0.1:${r.port}`;
@@ -80,32 +122,109 @@ export const answers = (r: GuiRecord) =>
 		req.end();
 	});
 
-/** `take` takes the running server over whatever its version; a newer `version` takes it over anyway. */
-export async function sharedGui(dir: string, [owner, ownerSession]: [string, string], start: (prefer: { port?: number; remotePort?: number; token?: string; csrf?: string }) => Promise<Gui>, sleep: (ms: number) => Promise<void>, { version = VERSION, take = false } = {}): Promise<Shared> {
+const STALE_MS = 10_000;
+const ageOf = (file: string) => Date.now() - (statSync(file, { throwIfNoEntry: false })?.mtimeMs ?? Date.now());
+/**
+ * Removes a gui.lock a session that died left (older than 10 s), once. Of several sessions that find it stale only the one that makes `gui.lock.stale` looks again and removes it, so none
+ * removes the fresh lock another has just taken. False when another session is at it (or left its mark: a guard older than 10 s was left by a session that died inside this), for the caller to wait and try again.
+ */
+export function clearStale(lock: string) {
+	const guard = `${lock}.stale`;
+	try {
+		mkdirSync(guard);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+		if (ageOf(guard) > STALE_MS) rmSync(guard, { recursive: true, force: true });
+		return false;
+	}
+	try {
+		if (ageOf(lock) > STALE_MS) rmSync(lock, { force: true });
+		return true;
+	} finally {
+		rmSync(guard, { recursive: true, force: true });
+	}
+}
+/** Takes gui.lock, which makes the check-and-start of a server atomic. Patient: waits for another session's start (a lock older than 10 s was left by a session that died); otherwise false at once when it is held. */
+async function lockGui(dir: string, sleep: (ms: number) => Promise<void>, patient: boolean) {
 	mkdirSync(dir, { recursive: true, mode: 0o700 });
 	const lock = join(dir, "gui.lock");
 	for (let tries = 0; ; tries++) {
 		try {
 			writeFileSync(lock, String(process.pid), { flag: "wx" });
-			break;
+			return true;
 		} catch (error) {
 			if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
-			// A lock older than 10 s was left by a session that died while starting the server.
-			const age = Date.now() - (statSync(lock, { throwIfNoEntry: false })?.mtimeMs ?? Date.now());
-			if (age > 10_000) rmSync(lock, { force: true });
-			else if (tries >= 50) throw new Error("Another session is starting the straw net GUI; try again");
-			else await sleep(200);
+			if (ageOf(lock) > STALE_MS && clearStale(lock)) continue; // a dead session's lock is gone: take it
+			if (!patient) return false;
+			if (tries >= 50) throw new Error("Another session is starting the straw net GUI; try again");
+			await sleep(200);
 		}
 	}
+}
+const unlockGui = (dir: string) => rmSync(join(dir, "gui.lock"), { force: true });
+/** Records the server this process started. */
+const writeRecord = (dir: string, gui: Gui, [owner, ownerSession]: [string, string], version: string, herdr: string) => {
+	const started = startOf(process.pid);
+	writeFileSync(join(dir, "gui.json"), JSON.stringify({ pid: process.pid, started, port: gui.port, remotePort: gui.remotePort, token: gui.token, csrf: gui.csrf, owner, ownerSession, version, herdr }), { mode: 0o600 });
+	return started ? {} : { blind: true };
+};
+type Start = (prefer: { port?: number; remotePort?: number; token?: string; csrf?: string }) => Promise<Gui>;
+
+/**
+ * A stop typed in a session that does not run the server, under gui.lock: a survivor that is starting it finishes first, so the stop reads and marks the record that start wrote and
+ * is not overwritten by it, and a server it started is asked to stop as it answers. `down`: nothing answered, and the record is marked so none is started later.
+ */
+export async function stopRecorded(dir: string, by: string, sleep: (ms: number) => Promise<void>): Promise<{ state: "down" | "stopped" | "refused"; record?: GuiRecord }> {
+	await lockGui(dir, sleep, true);
 	try {
 		const record = readRecord(dir);
+		if (!record || !(await answers(record))) {
+			if (record && !record.stopped) markStopped(dir, record); // a server that is down may be about to be taken over: a stop is a stop all the same
+			return { state: "down", record };
+		}
+		const stopped = await requestStop(record, { by, take: false }, sleep);
+		if (stopped) markStopped(dir, record); // its owner marks it too, unless it is a build from before this record knew
+		return { state: stopped ? "stopped" : "refused", record };
+	} finally {
+		unlockGui(dir);
+	}
+}
+
+/**
+ * `take` takes the running server over whatever its version; a newer `version` takes it over anyway. `herdr` is the socket the server's net is read from. `keep`: a server stopped on purpose, or one
+ * that is down, is left as it is (read under the lock, so a stop typed meanwhile counts): the restore after a /reload keeps a stop, the takeover by a newer version also keeps a down server, and
+ * `/boss stash` and `/boss close all` keep a stop.
+ */
+export async function sharedGui(dir: string, who: [string, string], start: Start, sleep: (ms: number) => Promise<void>, { version = VERSION, take = false, herdr = "", keep = {} as Keep } = {}): Promise<Shared> {
+	await lockGui(dir, sleep, true);
+	try {
+		const record = readRecord(dir);
+		if (record?.stopped && keep.stopped) return { url: urlOf(record), owner: record.owner, stopped: true };
 		const theirs = record && (await answers(record)) && { url: urlOf(record), owner: record.owner };
+		if (record && !theirs && keep.down) return { url: urlOf(record), owner: record.owner };
 		if (theirs && !(take || newer(version, record.version))) return theirs;
-		if (theirs && !(await requestStop(record, { by: owner, take: true }, sleep))) return { ...theirs, stale: true };
+		if (theirs && !(await requestStop(record, { by: who[0], take: true }, sleep))) return { ...theirs, stale: true };
 		const gui = await start(record ? { port: record.port, remotePort: record.remotePort, token: record.token, csrf: record.csrf } : {});
-		writeFileSync(join(dir, "gui.json"), JSON.stringify({ pid: process.pid, port: gui.port, remotePort: gui.remotePort, token: gui.token, csrf: gui.csrf, owner, ownerSession, version }), { mode: 0o600 });
-		return { url: gui.url, owner, mine: gui };
+		return { url: gui.url, owner: who[0], mine: gui, ...writeRecord(dir, gui, who, version, herdr) };
+	} finally {
+		unlockGui(dir);
+	}
+}
+
+/**
+ * A survivor's takeover of a server whose session ended: starts it again on the recorded port, token, and secret. It starts nothing when the server answers, when a deliberate stop
+ * ended it, when `adoptable` says no (an old build's record, another Herdr), or when the session that ran it still lives (its /reload, /new, or /resume brings it back
+ * in that process). Undefined then, and when another session holds gui.lock: that one is starting it, or is about to look. The lock is the arbiter, so of several survivors looking at
+ * once exactly one starts it. `moved` is set when the recorded port was taken and the server got another.
+ */
+export async function adoptGui(dir: string, who: [string, string], start: Start, sleep: (ms: number) => Promise<void>, gone: (record: GuiRecord, wrote: number) => boolean, { version = VERSION, herdr = "" } = {}): Promise<Shared | undefined> {
+	if (!(await lockGui(dir, sleep, false))) return undefined;
+	try {
+		const record = readRecord(dir), wrote = statSync(join(dir, "gui.json"), { throwIfNoEntry: false })?.mtimeMs ?? 0;
+		if (!record || record.stopped || !adoptable(record, { herdr }) || !gone(record, wrote) || (await answers(record))) return undefined;
+		const gui = await start({ port: record.port, remotePort: record.remotePort, token: record.token, csrf: record.csrf });
+		return { url: gui.url, owner: who[0], mine: gui, from: record.owner, ...writeRecord(dir, gui, who, version, herdr), ...(gui.url === urlOf(record) ? {} : { moved: true }) };
 	} finally {
-		rmSync(lock, { force: true });
+		unlockGui(dir);
 	}
 }

package/src/herdr.ts

@@ -82,7 +82,9 @@ export async function panes(run: HerdrRun, workspace?: string): Promise<Pane[]>
 }
 
 // Herdr answers one request per connection with one newline-ended frame, which may arrive in pieces (split anywhere, even inside a character).
-export const herdrCall = (socketPath = process.env.HERDR_SOCKET_PATH || join(homedir(), ".config", "herdr", "herdr.sock")): HerdrCall => (method, params, timeoutMs = 5000) =>
+/** The socket of the Herdr server a process runs under: the one its environment names, else the default. Two sessions are on the same Herdr when this is the same text. */
+export const herdrSocket = (env: NodeJS.ProcessEnv = process.env) => env.HERDR_SOCKET_PATH || join(homedir(), ".config", "herdr", "herdr.sock");
+export const herdrCall = (socketPath = herdrSocket()): HerdrCall => (method, params, timeoutMs = 5000) =>
 	new Promise((resolve, reject) => {
 		const socket = createConnection(socketPath).setTimeout(timeoutMs), text = new StringDecoder("utf8");
 		let reply = "";

package/src/host.ts

@@ -1,10 +1,12 @@
 import { popBase, stashedList } from "./stash.ts";
+import { statSync } from "node:fs";
 import { join } from "node:path";
 import type { Bridge } from "./bridge.ts";
 import { createCloser } from "./closer.ts";
 import { createHub } from "./dialogs.ts";
 import { type Gui, startGui } from "./gui.ts";
-import { answers, markReload, readRecord, requestStop, type Shared, sharedGui } from "./handover.ts";
+import { adoptable, adoptGui, downgrades, type Keep, markReload, markStopped, readRecord, type Shared, sharedGui, stopRecorded } from "./handover.ts";
+import { herdrSocket } from "./herdr.ts";
 import type { Membership } from "./membership.ts";
 import { netSource } from "./net.ts";
 import { pairingKeys, showLines } from "./pairing.ts";
@@ -29,11 +31,15 @@ export function createHost({ pi, cfg, s, guiDir, me, tell }: Kit, { bridge, conn
 	};
 	const unsaved = (gui: Gui) => ((reason) => reason && tell(reason, "warning"))(gui.access.unsaved()); // a paired.json that could not be saved: what was just changed is lost at a restart
 	const label = () => `${me() || "unknown"} (pane ${cfg.env.HERDR_PANE_ID})`;
-	// This session's server stops, its remote entry first: /boss gui stop here, another session's stop or takeover (`asked`), or the session's end.
+	const herdr = herdrSocket(cfg.env); // the Herdr server this session's net is read from; gui.json names it, and only a session on the same one adopts
+	// This session's server stops, its remote entry first: /boss gui stop here, or another session's stop or takeover (`asked`). A stop is on purpose and says so in
+	// gui.json, so no survivor starts the server again (adoptGui); a takeover starts its own at once, and the session's end is not a stop (release).
 	const stopOwn = async (asked?: { by: string; take: boolean }) => {
 		const running = s.gui;
 		s.gui = undefined;
 		if (!running) return false;
+		const record = readRecord(guiDir);
+		if (!asked?.take && record?.pid === process.pid && record.port === running.port && record.token === running.token) markStopped(guiDir, record); // before the server stops answering, so a session that sees it down finds the mark
 		const off = await switchRemote(running, false, guiDir, ts, true).catch((error: Error) => ({ text: error.message, changed: true }));
 		if (off.changed) tell(off.text);
 		await running.stop();
@@ -53,36 +59,76 @@ export function createHost({ pi, cfg, s, guiDir, me, tell }: Kit, { bridge, conn
 				await switchRemote(gui, false, guiDir, ts, true).catch(() => {});
 				return void tell(`Remote access stays off: the Tailscale identity is now ${now.login} on ${now.host}, not ${remembered.login} on ${remembered.host} that the paired devices belong to; sign in as that identity again, or turn it on here with /boss gui remote (that unpairs the old devices)`, "warning");
 			}
-			tell((await switchRemote(gui, true, guiDir, ts)).text);
+			tell((await switchRemote(gui, true, guiDir, ts)).plain);
 		} catch (error) {
 			tell(`Remote access stays off: ${(error as Error).message}; it is tried again when the server next starts`, "warning");
 		}
 	};
+	const start = (prefer: { port?: number; remotePort?: number; token?: string; csrf?: string }, net = netSource({ run, world, sessions, stashed: () => stashedList(guiDir), hub: (s.hub = s.hub?.me === me() ? s.hub : createHub(pi, me(), bridge)) })) => startGui({ read: net.read, net, call, hub: s.hub, dir: bundle, paired: join(guiDir, "paired.json"), ...prefer, onStop: (asked) => void stopOwn(asked), onSaveFailed: (reason) => tell(reason, "warning"), onRemote: async () => tell((await switchRemote(s.gui!, true, guiDir, ts)).text), onRemoteOff: async () => tell((await switchRemote(s.gui!, false, guiDir, ts)).text), spawn: createSpawn({ run, sleep, call, live: async (id) => (await sessions()).some((x) => x.id === id), sessionAt: async (pane) => (await sessions()).find((x) => x.herdrLocation?.paneId === pane)?.id }), close: createCloser({ run, sleep, me, sessions, ask: async (key, keepPane, ifStashable) => s.hub?.close(key, keepPane, ifStashable), check: async (key) => s.hub?.stashCheck(key), stateDir: guiDir, pop: (name) => popBase({ run, sleep, stateDir: guiDir, live: async (id) => (await sessions()).some((x) => x.id === id), agentDir: cfg.env.PI_CODING_AGENT_DIR }, name) }) });
 	// One server per machine: a second /boss gui, here or in another session, opens the one that runs, unless `take` (or a newer version) takes it
 	// over. Two calls in flight in this session share one start. `manual`: the caller turns remote on or off itself, so a new server does not resume it.
-	const share = (take = false, manual = false, was = false) =>
-		(opening ??= (async () => {
+	let adopting: Promise<void> | undefined, leaving = false;
+	// A server whose start time `ps` could not tell has no `started` in its record, so no survivor adopts it: said once.
+	let blind = false;
+	const noticed = (shared?: Shared) => void (shared?.blind && !blind && ((blind = true), tell("This session could not read its own start time (ps failed), so no other session takes the straw net GUI over if this session ends; /boss gui starts it again", "warning")));
+	// `keep` (handover.ts): a call that leaves a stopped or down server as it is does not hand its answer to one that starts it, so a /boss gui that finds such a call in flight waits for it.
+	const share = async (take = false, manual = false, was = false, keep?: Keep): Promise<Shared> => {
+		while (opening && leaving && !keep) await opening.then(() => {}, () => {});
+		if (!opening) leaving = Boolean(keep);
+		return (opening ??= (async () => {
+			await adopting; // an adoption under way is this session's start
 			if (s.gui) return { url: s.gui.url, owner: label(), mine: s.gui };
-			const start = (prefer: { port?: number; remotePort?: number; token?: string; csrf?: string }, net = netSource({ run, world, sessions, stashed: () => stashedList(guiDir), hub: (s.hub = s.hub?.me === me() ? s.hub : createHub(pi, me(), bridge)) })) => startGui({ read: net.read, net, call, hub: s.hub, dir: bundle, paired: join(guiDir, "paired.json"), ...prefer, onStop: (asked) => void stopOwn(asked), onSaveFailed: (reason) => tell(reason, "warning"), onRemote: async () => tell((await switchRemote(s.gui!, true, guiDir, ts)).text), onRemoteOff: async () => tell((await switchRemote(s.gui!, false, guiDir, ts)).text), spawn: createSpawn({ run, sleep, call, live: async (id) => (await sessions()).some((x) => x.id === id), sessionAt: async (pane) => (await sessions()).find((x) => x.herdrLocation?.paneId === pane)?.id }), close: createCloser({ run, sleep, me, sessions, ask: async (key, keepPane, ifStashable) => s.hub?.close(key, keepPane, ifStashable), check: async (key) => s.hub?.stashCheck(key), stateDir: guiDir, pop: (name) => popBase({ run, sleep, stateDir: guiDir, live: async (id) => (await sessions()).some((x) => x.id === id), agentDir: cfg.env.PI_CODING_AGENT_DIR }, name) }) });
-			const shared = await sharedGui(guiDir, [label(), me()], start, sleep, { version, take });
+			const shared = await sharedGui(guiDir, [label(), me()], start, sleep, { version, take, herdr, keep });
+			noticed(shared);
 			if ((s.gui = shared.mine) && !manual) await resume(s.gui, was);
 			return shared;
 		})().finally(() => (opening = undefined)));
+	};
+	// The server belongs to the machine, not to the session that started it. When that session ends without a stop (a closed pane, a quit, a crash), a survivor starts the server
+	// again on the same URL (handover.ts adoptGui), with remote access as `resume` leaves it, no QR, and no browser. Every session looks once every `adoptMs`; gui.lock lets exactly
+	// one of them start it. It is left alone when the record says it was stopped on purpose, when `adoptable` (handover.ts) says no (an old build's record, another Herdr's, a newer build's), and while the session
+	// that ran it lives: a /reload, /new, or /resume brings it back in that process, so a survivor never takes it from a reload. Only an interactive session adopts: a pi-herdr-agents subagent never reaches this host (index.ts), as it is
+	// short-lived and its parent is the session to host, and neither does a print-mode run, whose end is just as near and whose screen would not show the notice.
+	// Towers outlive the sessions they open, so the host is biased toward them and away from the churn of a short-lived session: a tower takes the server at the first look that finds its owner
+	// gone, anyone else at the second, and a build older than the server at the third, by which time any newer survivor has taken it (the next newer session takes it back).
+	let looking: ReturnType<typeof setInterval> | undefined, refused: string | undefined, seen = { key: "", looks: 0 };
+	const adopt = async () => {
+		if (s.gui || s.stopped || s.closing || !s.hasUI || !me() || opening || adopting) return;
+		const wrote = statSync(join(guiDir, "gui.json"), { throwIfNoEntry: false })?.mtimeMs, record = readRecord(guiDir);
+		if (!wrote || !record || record.stopped || !adoptable(record, { herdr }) || !cfg.gone(record, wrote) || refused === `${record.pid}/${wrote}`) return void (seen = { key: "", looks: 0 });
+		const key = `${record.pid}/${wrote}`;
+		seen = { key, looks: seen.key === key ? seen.looks + 1 : 1 };
+		if (seen.looks <= (downgrades(record, version) ? 2 : s.isTower ? 0 : 1)) return;
+		await (adopting = (async () => {
+			let shared: Shared | undefined;
+			try {
+				shared = await adoptGui(guiDir, [label(), me()], start, sleep, cfg.gone, { version, herdr });
+			} catch (error) {
+				refused = `${record.pid}/${wrote}`; // told once; /boss gui tries again
+				return tell(`Could not take over the straw net GUI after session ${record.owner} ended: ${(error as Error).message}; /boss gui starts it`, "warning");
+			}
+			if (!shared?.mine) return;
+			noticed(shared);
+			s.gui = shared.mine;
+			tell(`This session now hosts the straw net GUI: session ${shared.from} ended, ${shared.moved ? `and its port was taken meanwhile, so the URL changed: ${shared.url}` : "and the URL is unchanged"}`);
+			await resume(s.gui);
+		})().finally(() => (adopting = undefined)));
+	};
 	const older = (owner: string) => `The straw net GUI runs in session ${owner} on a pi-straw-boss older than 0.11.0, which cannot hand it over; /reload that session or run the command there`;
 	return {
 		sessions,
 		share,
 		/** The server again after a /reload, /new, /resume, or a takeover by a newer version; remote access comes back with it when it was wanted on, and the paired devices are still paired. */
-		async restore(was = false) {
-			await share(false, false, was);
+		async restore(was = false, keep?: Keep) {
+			await share(false, false, was, keep);
 		},
 		/** `mode` is "", "stop", "remote", or "remote off", and works from any session: remote access (remote.ts) goes with the server, so a session takes it over first. */
 		async command(mode: string) {
 			if (mode === "stop") {
 				if (await stopOwn()) return;
-				const record = readRecord(guiDir);
-				if (!record || !(await answers(record))) return tell("The straw net GUI is not running");
-				return tell((await requestStop(record, { by: label(), take: false }, sleep)) ? `Straw net GUI stopped (it ran in session ${record.owner})` : older(record.owner));
+				const { state, record } = await stopRecorded(guiDir, label(), sleep); // under gui.lock: a survivor that is starting the server finishes first
+				if (state === "down") return tell("The straw net GUI is not running");
+				return tell(state === "stopped" ? `Straw net GUI stopped (it ran in session ${record!.owner})` : older(record!.owner));
 			}
 			const { url, owner, stale } = await share(mode.startsWith("remote"), mode.startsWith("remote"));
 			if (mode.startsWith("remote") && !s.gui) return tell(older(owner));
@@ -100,8 +146,15 @@ export function createHost({ pi, cfg, s, guiDir, me, tell }: Kit, { bridge, conn
 			tell(`Straw net GUI: ${url}`);
 			await openUrl(url).catch((error: Error) => tell(`Could not open a browser (${error.message}); open the URL above yourself`, "warning"));
 		},
+		/** Starts looking for a server to take over (every `adoptMs`, until `release`); a session start again in this instance looks anew. */
+		watch() {
+			clearInterval(looking);
+			looking = setInterval(() => void adopt().catch(() => {}), cfg.adoptMs).unref();
+		},
 		/** The session ends: a /reload, /new, or /resume (`reload`) marks the server to start again in this process, and the server stops with its remote entry. */
 		async release(reload: boolean) {
+			clearInterval(looking);
+			await adopting; // a server this session was starting to adopt stops with it, instead of outliving it
 			if (s.gui && reload) markReload(guiDir); // a /reload, /new, or /resume starts it again in this process
 			if (s.gui) await switchRemote(s.gui, false, guiDir, ts, true).catch(() => {}); // the entry goes with the server; remote stays wanted and the devices stay paired
 			await s.gui?.stop();

package/src/index.ts

@@ -9,6 +9,7 @@ import { afterExit, createClosing } from "./closing.ts";
 import { createElection } from "./election.ts";
 import { createGuard, GUARD_MS } from "./guard.ts";
 import { openBrowser, VERSION } from "./gui.ts";
+import { ownerGone } from "./handover.ts";
 import { copyText } from "./pairing.ts";
 import { createHost } from "./host.ts";
 import { herdrApi, herdrCall, herdrRun, herdrWorld, socketReads, worldOf } from "./herdr.ts";
@@ -27,12 +28,13 @@ export type { Deps } from "./state.ts";
 
 const NUDGE_MS = 15_000;
 const DETECT_MS = 1_000;
+const ADOPT_MS = 2_000;
 
 // The composition root: the concerns live in their own modules (state.ts says what they share), and this wires them for one pi session.
-export function createStrawBoss({ run: given, world: reading, api = herdrApi(), call = herdrCall(), tailscale: ts = tailscale, copy = copyText, env = process.env, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), promptDir = fileURLToPath(new URL("../prompts", import.meta.url)), bundle, openUrl = openBrowser, watch = herdrWatch(), stateDir, autoTower = true, nudgeMs = NUDGE_MS, version = VERSION, guardMs = GUARD_MS, couple = true, events = herdrEvents(), detectMs = DETECT_MS, now = Date.now, later = afterExit }: Deps = {}) {
+export function createStrawBoss({ run: given, world: reading, api = herdrApi(), call = herdrCall(), tailscale: ts = tailscale, copy = copyText, env = process.env, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), promptDir = fileURLToPath(new URL("../prompts", import.meta.url)), bundle, openUrl = openBrowser, watch = herdrWatch(), stateDir, autoTower = true, nudgeMs = NUDGE_MS, version = VERSION, guardMs = GUARD_MS, couple = true, events = herdrEvents(), detectMs = DETECT_MS, now = Date.now, later = afterExit, gone = ownerGone(), adoptMs = ADOPT_MS }: Deps = {}) {
 	// A run that is not injected is the real CLI, with its listings over the socket; an injected one answers everything itself, listings included.
 	const run = given ?? socketReads(herdrRun, call), world = reading ?? (given ? worldOf(given) : herdrWorld(call));
-	const cfg: Config = { run, world, api, call, tailscale: ts, copy, env, sleep, promptDir, bundle, openUrl, watch, stateDir, autoTower, nudgeMs, version, guardMs, couple, events, detectMs, now, later };
+	const cfg: Config = { run, world, api, call, tailscale: ts, copy, env, sleep, promptDir, bundle, openUrl, watch, stateDir, autoTower, nudgeMs, version, guardMs, couple, events, detectMs, now, later, gone, adoptMs };
 	return function strawBoss(pi: ExtensionAPI): void {
 		// Outside Herdr there is no tab to coordinate. Every session in Herdr relays its dialogs to the GUI (bridge.ts), subagents too: they ask
 		// questions as well. A pi-herdr-agents worker never joins: its parent represents it.

package/src/remote.ts

@@ -161,7 +161,7 @@ export function createAccess(token: string, ended: (device?: string) => void = (
 	};
 }
 export type Access = ReturnType<typeof createAccess>;
-const alive = (pid: unknown) => {
+export const alive = (pid: unknown) => {
 	try {
 		return typeof pid === "number" && pid > 0 && process.kill(pid, 0);
 	} catch (error) {
@@ -196,7 +196,7 @@ export const cookieFor = (token: string, value: string) => `sb_remote=${value};
  * remote stream ends, but the paired devices stay. `stop` is the server going away (a stop, a takeover, a /reload, the session's end): the
  * entry goes the same way, and remote stays wanted, so the next server turns it on again. `dir` holds remote.json, the entry's target while it is on.
  */
-export async function switchRemote(gui: { port: number; remotePort: number; token: string; access: Access }, on: boolean, dir: string, run: Run = tailscale, stop = false): Promise<{ text: string; lines?: string[]; link?: () => string; changed: boolean }> {
+export async function switchRemote(gui: { port: number; remotePort: number; token: string; access: Access }, on: boolean, dir: string, run: Run = tailscale, stop = false): Promise<{ text: string; plain: string; lines?: string[]; link?: () => string; changed: boolean }> {
 	// An entry from before the remote listener points at the local port; it is this server's own, so it is repointed or removed like a recorded one.
 	const target = `http://127.0.0.1:${gui.remotePort}`, old = `http://127.0.0.1:${gui.port}`, file = join(dir, "remote.json");
 	let stale: string | undefined;
@@ -209,10 +209,11 @@ export async function switchRemote(gui: { port: number; remotePort: number; toke
 		const was = gui.access.remote;
 		gui.access.disable(stop);
 		const id = was ?? (stale ? await identity(run).catch(() => undefined) : undefined);
-		if (!id) return { text: "Remote access is off", changed: false };
+		if (!id) return { text: "Remote access is off", plain: "Remote access is off", changed: false };
 		const left = { remains: false }, removed = await serveOff(run, id.host, [was && target, stale, old], left);
 		if (removed || !left.remains) rmSync(file, { force: true }); // an entry of ours under another host (the identity changed) is still to remove: its record stays
-		return { text: removed ? `Remote access is off; the Tailscale serve entry on ${PORT} is removed` : `Remote access is off; the ${PORT} entry no longer pointed here, so it was left alone`, changed: true };
+		const text = removed ? `Remote access is off; the Tailscale serve entry on ${PORT} is removed` : `Remote access is off; the ${PORT} entry no longer pointed here, so it was left alone`;
+		return { text, plain: text, changed: true };
 	}
 	const id = await identity(run);
 	await serveOn(run, id.host, target, [stale, old]);
@@ -221,5 +222,6 @@ export async function switchRemote(gui: { port: number; remotePort: number; toke
 	// Every link is a new one-time pairing URL: the QR's own, and one per press of c or o in the overlay.
 	const link = () => `https://${id.host}/${gui.token}/pair/${gui.access.pair()}`;
 	const lines = [...qrLines(qr(link())), "", "Scan with a device signed in to Tailscale as", id.login, "", "c  copy a new one-time link", "o  open one in this computer's browser", "Esc or q  close"];
-	return { text: `Remote access is on for ${id.login}, tailnet only: https://${id.host}/${gui.token}/ (scan the QR; it works once, within ten minutes)`, lines, link, changed: true };
+	const plain = `Remote access is on for ${id.login}, tailnet only: https://${id.host}/${gui.token}/`; // `plain`: for a server that starts again, where no QR is shown
+	return { text: `${plain} (scan the QR; it works once, within ten minutes)`, plain, lines, link, changed: true };
 }

package/src/server-watch.ts

@@ -1,7 +1,6 @@
 import { createConnection, type Socket } from "node:net";
-import { homedir } from "node:os";
-import { join } from "node:path";
 import { StringDecoder } from "node:string_decoder";
+import { herdrSocket } from "./herdr.ts";
 
 /** Starts watching the Herdr server; `onTakeover` runs each time a server answers again after the one watched went away. Returns the stop function. */
 export type HerdrWatch = (onTakeover: () => void) => () => void;
@@ -16,7 +15,7 @@ const ACK_MS = 5000;
  * acknowledges the subscription it calls `onTakeover` once. The first connection of a watch, which finds the server the session started in, does not.
  * The socket and the retry timer never keep pi alive; `stop` ends both.
  */
-export const herdrWatch = (socketPath = process.env.HERDR_SOCKET_PATH || join(homedir(), ".config", "herdr", "herdr.sock"), retryMs = RETRY_MS): HerdrWatch => (onTakeover) => {
+export const herdrWatch = (socketPath = herdrSocket(), retryMs = RETRY_MS): HerdrWatch => (onTakeover) => {
 	let socket: Socket | undefined, timer: ReturnType<typeof setTimeout> | undefined, stopped = false, initial = true, retries = 0;
 	const attempt = () => {
 		const first = initial, text = new StringDecoder("utf8");
@@ -61,7 +60,7 @@ export const herdrWatch = (socketPath = process.env.HERDR_SOCKET_PATH || join(ho
 export type HerdrEvents = (types: string[], onEvent: (event: { event: string; data: Record<string, unknown> } | null) => void) => () => void;
 
 /** One `events.subscribe` connection that reconnects like the watch above (0.25 s, 0.5 s, 1 s, then every 2 s) and never keeps pi alive. */
-export const herdrEvents = (socketPath = process.env.HERDR_SOCKET_PATH || join(homedir(), ".config", "herdr", "herdr.sock"), retryMs = RETRY_MS): HerdrEvents => (types, onEvent) => {
+export const herdrEvents = (socketPath = herdrSocket(), retryMs = RETRY_MS): HerdrEvents => (types, onEvent) => {
 	let socket: Socket | undefined, timer: ReturnType<typeof setTimeout> | undefined, stopped = false, retries = 0;
 	const attempt = () => {
 		const text = new StringDecoder("utf8");

package/src/session.ts

@@ -2,7 +2,7 @@ import type { Briefing } from "./briefing.ts";
 import type { Digest } from "./digest.ts";
 import type { Guard } from "./guard.ts";
 import { answers, newer, readRecord } from "./handover.ts";
-import { isSub, panes, place, report, waitFor, workspaces } from "./herdr.ts";
+import { herdrSocket, isSub, panes, place, report, waitFor, workspaces } from "./herdr.ts";
 import type { createHost } from "./host.ts";
 import { CONNECT_MS, type Membership } from "./membership.ts";
 import { orphans } from "./orphan.ts";
@@ -64,6 +64,7 @@ export function registerSession(kit: Kit, { briefing, presence, membership, guar
 		stopWatching();
 		nudges = orphans({ run, file: () => log.getSessionFile(), entries: () => log.getEntries(), sessions: host.sessions, send: reach.send, type: ENTRY, remember: (key) => pi.appendEntry(ENTRY, { nudged: key }), me, tell });
 		nudgeTimer = setInterval(() => void nudges?.poll().catch(() => {}), cfg.nudgeMs).unref();
+		host.watch(); // the server of a session that ended without a stop is taken over here (host.ts)
 		// Starting runs in the background: pi awaits session_start handlers in turn, and pi-intercom connects in its own, after this one.
 		let starting: Promise<void> | undefined;
 		if (s.isTower) {
@@ -85,12 +86,13 @@ export function registerSession(kit: Kit, { briefing, presence, membership, guar
 		}
 		starting?.catch((error: Error) => tell(`Straw Boss: ${error.message}`, "error"));
 		// The GUI this process ran before a /reload, /new, or /resume starts again on its URL, and a session newer than the running server
-		// takes it over, once pi-intercom has published this session's id: the server's dialogs are routed by it.
+		// takes it over (one with a screen: a print run is no host, and one on the Herdr the server serves), once pi-intercom has published this session's id: the server's dialogs are routed by it.
+		// Under gui.lock the restore keeps a stop typed while it waited, and a takeover does not start a server that went down meanwhile: a survivor adopts that.
 		// A /new, /resume, or /fork is another session: it waits for the new id, not the one pi-intercom may still show from before.
-		const record = readRecord(guiDir), back = record?.reload && record.pid === process.pid && event.reason !== "startup";
+		const record = readRecord(guiDir), back = record?.reload && !record.stopped && record.pid === process.pid && event.reason !== "startup";
 		const ready = () => Boolean(me()) && (!back || event.reason === "reload" || me() !== record!.ownerSession);
-		if (back || (record && newer(version, record.version))) void (async () => {
-			if ((await waitFor(cfg.sleep, ready, CONNECT_MS)) && (back || (await answers(record!)))) await host.restore(Boolean(back && record!.remote));
+		if (back || (record && ctx.hasUI && newer(version, record.version) && (!record.herdr || record.herdr === herdrSocket(env)))) void (async () => {
+			if ((await waitFor(cfg.sleep, ready, CONNECT_MS)) && (back || (await answers(record!)))) await host.restore(Boolean(back && record!.remote), back ? { stopped: true } : { stopped: true, down: true });
 		})().catch(() => {});
 	});
 

package/src/stashing.ts

@@ -11,6 +11,8 @@ import type { Kit } from "./state.ts";
 
 // The checks take up to three rounds of a few seconds, then every agent has 30 s to quit.
 const STASH_MS = 120_000;
+// Both need the server, and start it when none runs, unless it was stopped on purpose: only /boss gui starts that one.
+const STOPPED = "The straw net GUI was stopped on purpose; /boss gui starts it, then run this again";
 
 export function createStashing({ cfg, s, guiDir, tell, me }: Kit, { host }: { host: Pick<ReturnType<typeof createHost>, "share" | "sessions"> }) {
 	const { run, sleep } = cfg;
@@ -22,7 +24,8 @@ export function createStashing({ cfg, s, guiDir, tell, me }: Kit, { host }: { ho
 			const ws = s.at.workspaceId, label = (await workspaces(run)).find((w) => w.workspace_id === ws)?.label ?? ws, name = given?.trim() || nameFor(label, guiDir);
 			if (!nameOk(name)) throw new Error(`"${name}" cannot name a stash: at most 64 characters, no slash, backslash, or control character, not starting with a dot`);
 			if (existsSync(stashFile(guiDir, name))) throw new Error(`Something is stashed as "${name}" already; pop it or pick another name`);
-			const shared = await host.share();
+			const shared = await host.share(false, false, false, { stopped: true });
+			if (shared.stopped) throw new Error(STOPPED);
 			const record = readRecord(guiDir);
 			if (shared.stale || !record) throw new Error(`The straw net GUI runs in session ${shared.owner} on a version that cannot stash; /reload that session first`);
 			tell(`Stashing ${label} as "${name}"…`);
@@ -33,7 +36,8 @@ export function createStashing({ cfg, s, guiDir, tell, me }: Kit, { host }: { ho
 		},
 		/** Quits this base's tower, mains, and members and closes it, or nothing when anything there would be lost. */
 		async closeAll() {
-			const shared = await host.share();
+			const shared = await host.share(false, false, false, { stopped: true });
+			if (shared.stopped) throw new Error(STOPPED);
 			const record = readRecord(guiDir);
 			if (shared.stale || !record) throw new Error(`The straw net GUI runs in session ${shared.owner} on a version that cannot close all; /reload that session first`);
 			tell("Closing this base…");

package/src/state.ts

@@ -4,6 +4,7 @@ import { join } from "node:path";
 import type { startDashboard } from "./dashboard.ts";
 import type { Hub } from "./dialogs.ts";
 import type { Gui } from "./gui.ts";
+import type { GuiRecord } from "./handover.ts";
 import type { HerdrApi, HerdrCall, HerdrRun, HerdrWorld, Place, Session, Sleep } from "./herdr.ts";
 import type { Run } from "./remote.ts";
 import type { HerdrEvents, HerdrWatch } from "./server-watch.ts";
@@ -26,8 +27,11 @@ export interface SendResult { requestId?: string; status: string; code?: string;
 export interface Saved { tower?: boolean }
 export type Role = "tower" | "main" | "member";
 export type Scope = "tab" | "workspace" | "towers" | "all";
-/** `run` is the CLI for every command; left out, Herdr's listings go over the socket instead (`socketReads`) and `world` is one `session.snapshot`. `world` is the dashboard's and the GUI's reading of panes and workspaces. */
-export interface Deps { run?: HerdrRun; world?: HerdrWorld; api?: HerdrApi; call?: HerdrCall; tailscale?: Run; copy?: (text: string) => Promise<void>; env?: NodeJS.ProcessEnv; sleep?: Sleep; promptDir?: string; bundle?: string; openUrl?: (url: string) => Promise<void>; watch?: HerdrWatch; stateDir?: string; autoTower?: boolean; nudgeMs?: number; version?: string; guardMs?: number; couple?: boolean; events?: HerdrEvents; detectMs?: number; now?: () => number; later?: (pid: number, args: string[]) => void }
+/**
+ * `run` is the CLI for every command; left out, Herdr's listings go over the socket instead (`socketReads`) and `world` is one `session.snapshot`. `world` is the dashboard's and the GUI's reading of panes and workspaces.
+ * `gone` says whether the process that recorded a GUI server has ended for good (handover.ts `ownerGone`), which a survivor needs before it takes the server over; `adoptMs` is how often a session looks.
+ */
+export interface Deps { run?: HerdrRun; world?: HerdrWorld; api?: HerdrApi; call?: HerdrCall; tailscale?: Run; copy?: (text: string) => Promise<void>; env?: NodeJS.ProcessEnv; sleep?: Sleep; promptDir?: string; bundle?: string; openUrl?: (url: string) => Promise<void>; watch?: HerdrWatch; stateDir?: string; autoTower?: boolean; nudgeMs?: number; version?: string; guardMs?: number; couple?: boolean; events?: HerdrEvents; detectMs?: number; now?: () => number; later?: (pid: number, args: string[]) => void; gone?: (record: GuiRecord, wrote: number) => boolean; adoptMs?: number }
 /** The dependencies with their defaults filled in. */
 export type Config = Required<Omit<Deps, "bundle" | "stateDir">> & Pick<Deps, "bundle" | "stateDir">;