pi-straw-boss 0.33.3 → 0.34.1

package/README.md

@@ -86,6 +86,7 @@ The tower only routes and coordinates, so it can run a lighter model: set `tower
 | `/boss` | Take over as this tab's main agent. |
 | `/boss status`, `/boss tower` | Show the status; open and focus the tower. |
 | `/boss close` | Quit this session and close its pane. |
+| `/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 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. |
 

package/README.zh-TW.md

@@ -85,6 +85,7 @@ pi install npm:pi-straw-boss
 | `boss_rename` | 用一個短語替這個 session 命名，說明它現在在做什麼；net、GUI，以及裝了 pi-auto-tab-name 時的分頁名稱都會跟著顯示。主智慧體換工作時會呼叫它。 |
 | `/boss` | 接手成為這個分頁的主智慧體。 |
 | `/boss status`、`/boss tower` | 顯示狀態；開啟塔台並切換過去。 |
+| `/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 remote`、`/boss gui remote off` | 透過你的 tailnet 用手機連 GUI（`tailscale serve`，絕不用 Funnel）：掃 QR code 配對，手機配對後會一直有效（從最後一次使用起算 90 天，重啟與 `remote off` 都不影響），直到你在「手機」視窗解除配對；遠端存取在 stop、`/reload`、換新伺服器之後仍會保持開啟，直到 `remote off`；關閉時只移除它自己的 serve 設定。serve 指向 GUI 伺服器的第二個 loopback 監聽埠，請求算不算遠端取決於它進來的監聽埠，不看它帶什麼標頭。 |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-straw-boss",
-  "version": "0.33.3",
+  "version": "0.34.1",
   "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/boss.ts

@@ -2,17 +2,19 @@ import type { createHost } from "./host.ts";
 import type { Membership } from "./membership.ts";
 import type { Reach } from "./reach.ts";
 import type { Kit } from "./state.ts";
+import type { createStashing } from "./stashing.ts";
 
 /** What Tab completes after /boss; a bare /boss (take over as the main agent) has nothing to complete. */
-const BOSS_ARGUMENTS = Object.entries({ status: "Show the coordinators", close: "Quit this session and close its pane", tower: "Open and focus the workspace tower", gui: "Open the net in the browser", "gui stop": "Close the browser GUI", "gui remote": "Open the GUI to your phone over Tailscale", "gui remote off": "Close the Tailscale entry" }).map(([value, description]) => ({ value, label: value, description }));
+const BOSS_ARGUMENTS = Object.entries({ status: "Show the coordinators", close: "Quit this session and close its pane", tower: "Open and focus the workspace tower", gui: "Open the net in the browser", "gui stop": "Close the browser GUI", "gui remote": "Open the GUI to your phone over Tailscale", "gui remote off": "Close the Tailscale entry", stash: "Put this base away: its tower, mains, and members", pop: "Open a stashed base again" }).map(([value, description]) => ({ value, label: value, description }));
 
 /** The /boss command. */
-export function registerBoss({ pi, cfg, s, tell }: Kit, { host, membership, reach, closeSelf }: { host: ReturnType<typeof createHost>; membership: Membership; reach: Reach; closeSelf(keepPane: boolean): string | undefined }) {
+export function registerBoss({ pi, cfg, s, tell }: Kit, { host, membership, reach, closeSelf, stashing }: { host: ReturnType<typeof createHost>; membership: Membership; reach: Reach; closeSelf(keepPane: boolean): string | undefined; stashing: ReturnType<typeof createStashing> }) {
 	pi.registerCommand("boss", {
-		description: "Take over as this tab's main agent (every session already joins as a member). /boss status shows the coordinators; /boss tower focuses the workspace tower (a main opens it when there is none); /boss close quits this session and closes its pane; /boss gui opens the net in the browser (/boss gui stop closes it; /boss gui remote opens it to your phone over Tailscale, /boss gui remote off closes that).",
+		description: "Take over as this tab's main agent (every session already joins as a member). /boss status shows the coordinators; /boss tower focuses the workspace tower (a main opens it when there is none); /boss close quits this session and closes its pane; /boss stash [name] puts this base away (tower, mains, members) and /boss pop [name] opens it again; /boss gui opens the net in the browser (/boss gui stop closes it; /boss gui remote opens it to your phone over Tailscale, /boss gui remote off closes that).",
 		// pi passes the whole argument text and replaces it with the chosen value, so each value is a full argument line.
 		getArgumentCompletions: (prefix) => {
-			const items = BOSS_ARGUMENTS.filter((item) => item.value.startsWith(prefix.trimStart()));
+			const stashed = stashing.names().map((name) => ({ value: `pop ${name}`, label: `pop ${name}`, description: "Open this stashed base again" }));
+			const items = [...BOSS_ARGUMENTS, ...stashed].filter((item) => item.value.startsWith(prefix.trimStart()));
 			return items.length ? items : null;
 		},
 		handler: async (args, ctx) => {
@@ -22,6 +24,8 @@ export function registerBoss({ pi, cfg, s, tell }: Kit, { host, membership, reac
 				const why = args.trim() === "close" ? (closeSelf(false) ?? "") : undefined;
 				if (why !== undefined) return void (why && tell(why, "error"));
 				if (args.trim() === "status") return tell(s.joined || s.isTower ? JSON.stringify(await reach.status(), null, 2) : "Not in the net: still joining, or this session cannot join.");
+				const stash = /^(stash|pop)(?:\s+(.+))?$/.exec(args.trim());
+				if (stash) return await (stash[1] === "stash" ? stashing.stash(stash[2]) : stashing.pop(stash[2]));
 				if (s.isTower) throw new Error("This session is the tower, not a main agent");
 				if (args.trim() !== "tower") return tell((await membership.promote(true)).text);
 				await membership.joinNet();

package/src/bridge.ts

@@ -20,7 +20,8 @@ import { type Monitor, trackMonitors } from "./monitors.ts";
 // Enter guard asks it what the editor would submit (`probe`, probe.ts), and it answers with a class and at most a command name, never the draft. It relays
 // the documents the session shows with its dialogs (documents.ts) and hands a form answer for one of them to their owner. The composer's `/` menu
 // asks it (`commands`) for the session's commands that match what is typed, and it answers with their names, sources, and descriptions.
-// A close button asks it (`close`) to quit its session the way /boss close does (index.ts), which answers whether it will.
+// A close button asks it (`close`) to quit its session the way /boss close does (index.ts), which answers whether it will. A stash asks it
+// first (`stash-check`, stash.ts) whether the session can be put away and resumed losing nothing; that question never quits anything.
 // It relays the session's queue too: pi tells extensions only whether messages wait (hasPendingMessages), so the bridge keeps what it saw
 // typed while the agent works (`input` with a streaming behavior) and drops one when its user message starts; a queue pi emptied another
 // way (Esc, Alt+Up) clears at the next check. And it relays the session's background monitors (monitors.ts).
@@ -43,14 +44,16 @@ export interface ProbeResult extends Editor { version: 1; type: "probe-result";
 export interface CommandsResult { version: 1; type: "commands-result"; bridgeId: string; reqId: string; commands: Cmd[] }
 export interface FormReply { version: 1; type: "form-result"; bridgeId: string; id: string; answerId: string; accepted: boolean; reason?: string }
 export interface CloseResult { version: 1; type: "close-result"; bridgeId: string; reqId: string; accepted: boolean; reason?: string }
-export type ToHub = Dialogs | Ack | ProbeResult | FormReply | CommandsResult | CloseResult;
+/** `reason`: why the session cannot be stashed now; none when it can. */
+export interface StashCheckResult { version: 1; type: "stash-check-result"; bridgeId: string; reqId: string; reason?: string }
+export type ToHub = Dialogs | Ack | ProbeResult | FormReply | CommandsResult | CloseResult | StashCheckResult;
 export interface FormMessage { version: 1; type: "form"; to: string; id: string; answerId: string; fields: Fields }
 /** An answer on the wire: never a secret's `value`. */
 export interface AnswerMessage extends Omit<Answer, "value"> { version: 1; type: "answer"; to: string }
 /** The hub when it runs in this session: it takes what a remote bridge would publish, from this session's id. */
 export interface LocalHub { receive(from: string, msg: ToHub): void }
 /** What the hub calls on the bridge of its own session. */
-export interface Bridge { deliver(msg: AnswerMessage, reply: (ack: Ack) => void): void; sync(): void; probe(): Editor; commands(prefix: string): Cmd[]; form(msg: FormMessage, reply: (r: FormReply) => void): void; close(keepPane: boolean): { accepted: boolean; reason?: string } }
+export interface Bridge { deliver(msg: AnswerMessage, reply: (ack: Ack) => void): void; sync(): void; probe(): Editor; commands(prefix: string): Cmd[]; form(msg: FormMessage, reply: (r: FormReply) => void): void; close(keepPane: boolean, ifStashable?: boolean): { accepted: boolean; reason?: string }; stashCheck(): string | undefined }
 interface Channel { snapshot(): { connected: boolean; owner?: { sessionId: string; epoch: string } }; publish(payload: unknown, options?: { audience?: "owner" | "capable" }): void }
 interface Rec { adapter: OwnerAdapter; d: Dialog; state: "open" | "settling" | "unknown" | "closed"; answerId?: string; accepted?: boolean; by?: string; at?: number; last?: Ack; waiting: ((ack: Ack) => void)[] }
 type Event = { type: string; fromSessionId?: string; owner?: { sessionId: string; epoch: string }; payload?: Record<string, unknown> };
@@ -61,7 +64,7 @@ export function startBridge(pi: ExtensionAPI, { env, dir, local, close }: { env:
 	const chans = new Map<string, Channel>(), me = () => env.PI_INTERCOM_SESSION_ID ?? "";
 	let g: string | undefined, gpid = 0, seen: number | undefined, poll: ReturnType<typeof setInterval> | undefined, offs: (() => void)[] = [], warned = false;
 	let file: () => string | undefined = () => undefined, tell = (_text: string) => {}, editor = (): Editor => ({ editor: "unknown" }), docs: Doc[] = [];
-	let queued: Queued[] = [], waits = () => false;
+	let queued: Queued[] = [], waits = () => false, idle = () => true;
 	const open = () => [...recs.values()].filter((r) => r.state !== "closed");
 	const alive = () => { try { return gpid > 0 && (process.kill(gpid, 0), true); } catch (e) { return (e as NodeJS.ErrnoException).code === "EPERM"; } }; // a server that died without removing gui.json gets no probe answers
 
@@ -111,7 +114,7 @@ export function startBridge(pi: ExtensionAPI, { env, dir, local, close }: { env:
 	const onEvent = (from: string, ch: Channel, e: Event) => {
 		if (e.type === "owner" || e.type === "connection") return from === g && push();
 		const owner = ch.snapshot().owner, p = e.payload;
-		if (p?.type === "probe" || p?.type === "commands" || p?.type === "close") follow(); // a probe goes only to the server gui.json names at this moment
+		if (p?.type === "probe" || p?.type === "commands" || p?.type === "close" || p?.type === "stash-check") follow(); // a probe goes only to the server gui.json names at this moment
 		// Only G's own session, as the broker's current owner of this channel and the server gui.json names now, may answer, probe, or ask for a sync.
 		if (e.type !== "message" || p?.version !== 1 || e.fromSessionId !== from || owner?.sessionId !== from || e.owner?.epoch !== owner.epoch) return;
 		if (p.type === "sync" && from === g) push();
@@ -119,11 +122,18 @@ export function startBridge(pi: ExtensionAPI, { env, dir, local, close }: { env:
 		if (p.type === "form" && p.to === bridgeId && from === g) form(p as unknown as FormMessage, (r) => send(from, r));
 		if (p.type === "answer" && p.to === bridgeId && from === g) deliver(p as unknown as AnswerMessage, (ack) => send(from, ack));
 		if (p.type === "probe" && p.to === bridgeId && from === g && alive() && typeof p.probeId === "string" && p.probeId.length <= 64) send(from, { version: 1, type: "probe-result", bridgeId, probeId: p.probeId, ...editor() });
-		if (p.type === "close" && p.to === bridgeId && from === g && alive() && typeof p.reqId === "string" && p.reqId.length <= 64 && typeof p.keepPane === "boolean") send(from, { version: 1, type: "close-result", bridgeId, reqId: p.reqId, ...shut(p.keepPane) });
+		if (p.type === "close" && p.to === bridgeId && from === g && alive() && typeof p.reqId === "string" && p.reqId.length <= 64 && typeof p.keepPane === "boolean") send(from, { version: 1, type: "close-result", bridgeId, reqId: p.reqId, ...shut(p.keepPane, p.ifStashable === true) });
+		if (p.type === "stash-check" && p.to === bridgeId && from === g && alive() && typeof p.reqId === "string" && p.reqId.length <= 64) send(from, { version: 1, type: "stash-check-result", bridgeId, reqId: p.reqId, ...((r) => (r ? { reason: r } : {}))(stashCheck()) });
 		if (p.type === "commands" && p.to === bridgeId && from === g && alive() && typeof p.reqId === "string" && p.reqId.length <= 64 && typeof p.prefix === "string" && p.prefix.length <= MAX_PREFIX) send(from, { version: 1, type: "commands-result", bridgeId, reqId: p.reqId, commands: listCommands(pi, p.prefix) });
 	};
-	const shut = (keepPane: boolean) => {
-		const why = close(keepPane);
+	/** Why this session cannot be stashed and resumed as it is now: a turn or a queue, a dialog, or a monitor that a resume would not bring back. */
+	const stashCheck = () => {
+		const why = [!idle() && "a turn is running", waits() && "messages wait in its queue", open().length > 0 && "a dialog is open", (monitors?.list() ?? []).some((m) => m.status === "running") && "a background monitor is running"].filter(Boolean);
+		return why.length ? why.join(", ") : undefined;
+	};
+	/** `ifStashable`: a stash's close, refused when the session stopped being stashable since its check (a turn started meanwhile). */
+	const shut = (keepPane: boolean, ifStashable = false) => {
+		const why = (ifStashable && stashCheck()) || close(keepPane);
 		return why ? { accepted: false, reason: why } : { accepted: true };
 	};
 	const changed = () => {
@@ -215,6 +225,7 @@ export function startBridge(pi: ExtensionAPI, { env, dir, local, close }: { env:
 		docs = [];
 		queued = [];
 		waits = () => { try { return ctx.hasPendingMessages(); } catch { return false; } }; // a replaced session's context throws
+		idle = () => { try { return ctx.isIdle(); } catch { return false; } };
 		file = () => ctx.sessionManager.getSessionFile();
 		tell = (text) => ctx.hasUI && ctx.ui.notify(text, "warning");
 		editor = () => probeEditor(ctx);
@@ -246,5 +257,5 @@ export function startBridge(pi: ExtensionAPI, { env, dir, local, close }: { env:
 		offs.splice(0).forEach((off) => off());
 		(clearInterval(poll), (poll = undefined));
 	});
-	return { deliver, sync: () => ((seen = -1), follow()), probe: () => editor(), commands: (prefix) => listCommands(pi, prefix), form, close: shut };
+	return { deliver, sync: () => ((seen = -1), follow()), probe: () => editor(), commands: (prefix) => listCommands(pi, prefix), form, close: shut, stashCheck };
 }

package/src/closer.ts

@@ -1,5 +1,6 @@
 import type { Reply } from "./control.ts";
 import { type HerdrRun, panes, type Session, type Sleep } from "./herdr.ts";
+import { stashBase } from "./stash.ts";
 
 // What the page's close buttons ask for. Closing is each session's own (index.ts): its bridge is asked to quit it as /boss close does, and its
 // shutdown clears its tokens (a tower's clears the base's mains). One unit closes its own pane afterwards; for a squad or a base every agent
@@ -9,20 +10,23 @@ import { type HerdrRun, panes, type Session, type Sleep } from "./herdr.ts";
 //   POST /<token>/api/close/unit {key}                 that session quits and closes its pane
 //   POST /<token>/api/close/tab {workspace, tab}       every agent in the tab quits, then the tab closes
 //   POST /<token>/api/close/base {workspace}           every agent in the workspace quits, then the workspace closes
+//   POST /<token>/api/close/stash {workspace, name}    the base is checked and recorded first (stash.ts), then closed as above
 
 const EXIT_MS = 30_000, JOINED = new Set(["main", "member", "tower"]);
-export interface CloserDeps { run: HerdrRun; sleep: Sleep; me(): string; sessions(): Promise<Session[]>; ask(key: string, keepPane: boolean): Promise<{ accepted: boolean; reason?: string } | undefined> }
+/** `check` and `stateDir` are a stash's: without them this closer stashes nothing. */
+export interface CloserDeps { run: HerdrRun; sleep: Sleep; me(): string; sessions(): Promise<Session[]>; ask(key: string, keepPane: boolean, ifStashable?: boolean): Promise<{ accepted: boolean; reason?: string } | undefined>; check?(key: string): Promise<{ reason?: string } | undefined>; stateDir?: string }
 const no = (status: number, error: string, reason: string): Reply => ({ status, body: { error, reason } });
 
-export function createCloser({ run, sleep, me, sessions, ask }: CloserDeps) {
+export function createCloser({ run, sleep, me, sessions, ask, check, stateDir }: CloserDeps) {
 	let busy = false;
 	const name = (s: Session) => s.name ?? s.id.slice(0, 8);
 
-	async function batch(workspace: string, tab?: string): Promise<Reply> {
+	/** `ifStashable`: a stash's batch, where each session quits only while it can still be stashed. */
+	async function batch(workspace: string, tab?: string, ifStashable = false): Promise<Reply> {
 		const here = (await panes(run, workspace)).filter((p) => (!tab || p.tab_id === tab) && JOINED.has(p.tokens?.sb_role ?? ""));
 		if (!here.length && !(await panes(run, workspace)).some((p) => !tab || p.tab_id === tab)) return no(404, "not_found", tab ? "That squad is not open any more." : "That base is not open any more.");
 		const targets = (await sessions()).filter((s) => s.id !== me() && here.some((p) => p.pane_id === s.herdrLocation?.paneId));
-		const answers = await Promise.all(targets.map(async (s) => ({ s, r: await ask(s.id, true) })));
+		const answers = await Promise.all(targets.map(async (s) => ({ s, r: await ask(s.id, true, ifStashable) })));
 		const stuck = answers.filter(({ r }) => !r?.accepted).map(({ s, r }) => `${name(s)}${r?.reason ? ` (${r.reason})` : " (no answer)"}`);
 		if (stuck.length) return no(409, "refused", `Nothing was closed: ${stuck.join(", ")} cannot be closed from here. Close them in their terminals first.`);
 		const ids = new Set(targets.map((s) => s.id));
@@ -33,13 +37,25 @@ export function createCloser({ run, sleep, me, sessions, ask }: CloserDeps) {
 		return { status: 200, body: { closed: targets.length } };
 	}
 
-	return async function handle(kind: string, json: Record<string, unknown>): Promise<Reply> {
+	/** `refresh` reads the net again, so the hub learns of bridges that told it about themselves since (a stash's second round). */
+	return async function handle(kind: string, json: Record<string, unknown>, refresh?: () => Promise<unknown>): Promise<Reply> {
 		const str = (v: unknown): v is string => typeof v === "string" && v.length > 0 && v.length <= 200;
 		if (kind === "unit") {
 			if (!str(json.key)) return no(400, "bad_request", "A unit is named by its key.");
 			const r = await ask(json.key, false);
 			return r?.accepted ? { status: 200, body: { closing: true } } : no(409, "refused", r?.reason ?? "The session did not answer; close it in its terminal.");
 		}
+		if (kind === "stash" && check && stateDir) {
+			if (busy) return no(429, "busy", "Another close is still on its way.");
+			busy = true;
+			try {
+				return await stashBase({ run, sleep, sessions, check, stateDir }, json, (workspace) => batch(workspace, undefined, true), refresh);
+			} catch (error) {
+				return no(502, "stash_failed", (error as Error).message);
+			} finally {
+				busy = false;
+			}
+		}
 		if (kind !== "tab" && kind !== "base") return no(404, "not_found", "No such action.");
 		if (!str(json.workspace) || (kind === "tab" && !str(json.tab))) return no(400, "bad_request", "A squad is named by its workspace and tab, a base by its workspace.");
 		if (busy) return no(429, "busy", "Another close is still on its way.");

package/src/control.ts

@@ -23,6 +23,7 @@ import { ENDING } from "./probe.ts";
 //   POST /<token>/api/remote/devices, remote/unpair {id}, remote/unpair-all             the paired devices, and unpairing one or all (never remote)
 //   POST /<token>/api/dismiss {key} or {all: true}                                       hides one finished subagent, or every finished one, from every page
 //   POST /<token>/api/close/unit, close/tab, close/base                                   quits a session, or every agent of a squad or base, then closes it (closer.ts)
+//   POST /<token>/api/close/stash {workspace, name}                                       checks and records a base, then closes it as close/base does (stash.ts); a paired device may, as it may close/base
 //   POST /<token>/api/dirs, open/base, open/member, open/main                            a folder picker, a new base with a member, a new member, a new main (spawn.ts)
 //   POST /<token>/api/server/stop {by, take}                                             stops the server: another session's /boss gui stop or takeover (never remote)
 // Every write needs the page's own origin (Origin, Sec-Fetch-Site), a JSON body of at most 64 KB, and the CSRF secret the server wrote into
@@ -35,7 +36,7 @@ export { ENDING };
 
 export interface Reply { status: number; body: unknown }
 /** `answers.target` reads the net afresh, so the binding and the dialog are checked again for every answer. */
-export interface ControlDeps { lookup(key: string): Found | undefined; call?: HerdrCall; csrf: string; canonical(file?: string): string | undefined; pair?(): { url: string; rows: string[] } | undefined; remoteOn?(): Promise<void>; remoteOff?(): Promise<void>; paired?: { on(): boolean; list(): unknown; unpair(id: string): boolean; unpairAll(): number; unsaved(): string | undefined }; saveFailed?(reason: string): void; spawn?(parts: string[], json: Record<string, unknown>): Promise<Reply>; close?(kind: string, json: Record<string, unknown>): Promise<Reply>; dismiss?(key: unknown): Promise<boolean>; dismissAll?(): Promise<number>; stop?(asked: Asked): void; mirrors?: Pick<ReturnType<typeof createMirrors>, "toggle" | "fresh">; secret?(file: string): Promise<boolean>; answers?: Pick<Hub, "replay" | "ended" | "send" | "probe" | "commands"> & { target(key: string): Promise<Target | undefined> } }
+export interface ControlDeps { lookup(key: string): Found | undefined; call?: HerdrCall; csrf: string; canonical(file?: string): string | undefined; pair?(): { url: string; rows: string[] } | undefined; remoteOn?(): Promise<void>; remoteOff?(): Promise<void>; paired?: { on(): boolean; list(): unknown; unpair(id: string): boolean; unpairAll(): number; unsaved(): string | undefined }; saveFailed?(reason: string): void; spawn?(parts: string[], json: Record<string, unknown>): Promise<Reply>; close?(kind: string, json: Record<string, unknown>, refresh?: () => Promise<unknown>): Promise<Reply>; dismiss?(key: unknown): Promise<boolean>; dismissAll?(): Promise<number>; stop?(asked: Asked): void; mirrors?: Pick<ReturnType<typeof createMirrors>, "toggle" | "fresh">; secret?(file: string): Promise<boolean>; answers?: Pick<Hub, "replay" | "ended" | "send" | "probe" | "commands"> & { target(key: string): Promise<Target | undefined> } }
 
 const no = (status: number, error: string, reason: string): Reply => ({ status, body: { error, reason } });
 const same = (a: string, b: string) => a.length === b.length && timingSafeEqual(Buffer.from(a), Buffer.from(b));

package/src/dialogs.ts

@@ -72,7 +72,7 @@ export function createHub(pi: ExtensionAPI, me: string, local: Bridge) {
 	let channel: Channel | undefined, epoch: string | undefined, active = false, change = () => {};
 	let bound = new Map<string, { from: string; b: Dialogs }>(), targets = new Map<string, Target>(), reach = new Map<string, { from: string; bridgeId: string }>();
 	const bridges = new Map<string, Dialogs>(), waiting = new Map<string, (ack?: Ack) => void>(), done = new Map<string, { key: string; at: number; sent: Sent }>(), probes = new Map<string, (e?: Editor) => void>(), lists = new Map<string, (c?: Cmd[]) => void>();
-	const closes = new Map<string, (r?: Pick<CloseResult, "accepted" | "reason">) => void>();
+	const closes = new Map<string, (r?: Pick<CloseResult, "accepted" | "reason">) => void>(), checks = new Map<string, (r?: { reason?: string }) => void>();
 	const caps = createCaps(), forms = new Map<string, (r?: FormReply) => void>();
 	let shelves = new Map<string, Shelf>();
 	const owner = () => channel?.snapshot().owner?.sessionId === me;
@@ -92,6 +92,7 @@ export function createHub(pi: ExtensionAPI, me: string, local: Bridge) {
 		if (msg.type === "probe-result") probes.get([from, msg.bridgeId, msg.probeId].join("\n"))?.(checkProbe({ ...msg }));
 		if (msg.type === "commands-result" && str(msg.reqId)) lists.get([from, msg.bridgeId, msg.reqId].join("\n"))?.(checkCommands(msg.commands));
 		if (msg.type === "close-result" && str(msg.reqId) && typeof msg.accepted === "boolean" && opt(msg.reason) && (msg.reason?.length ?? 0) <= 512) closes.get([from, msg.bridgeId, msg.reqId].join("\n"))?.({ accepted: msg.accepted, ...(msg.reason ? { reason: msg.reason } : {}) });
+		if (msg.type === "stash-check-result" && str(msg.reqId) && opt(msg.reason) && (msg.reason?.length ?? 0) <= 512) checks.get([from, msg.bridgeId, msg.reqId].join("\n"))?.(msg.reason ? { reason: msg.reason } : {});
 		if (msg.type === "form-result" && typeof msg.accepted === "boolean" && opt(msg.reason) && (msg.reason?.length ?? 0) <= 512) forms.get([from, msg.bridgeId, msg.id, msg.answerId].join("\n"))?.(msg);
 	};
 	const onEvent = (e: Event) => {
@@ -136,7 +137,7 @@ export function createHub(pi: ExtensionAPI, me: string, local: Bridge) {
 	const hub: LocalHub & {
 		readonly running: boolean; readonly me: string; start(onChange: () => void): void; stop(): void; relayed(sessions: Session[], refs: Map<string, Ref>): Relayed; target(key: string): Target | undefined;
 		replay(answerId: string, key: string): Sent | undefined; ended(key: string, dialog: string, answerId: string): Sent | undefined; send(key: string, t: Target, a: Answer): Promise<Sent>;
-		probe(key: string): Promise<Editor | undefined>; commands(key: string, prefix: string): Promise<Cmd[] | undefined>; close(key: string, keepPane: boolean): Promise<{ accepted: boolean; reason?: string } | undefined>; doc(cap: string): { key: string; doc: Doc } | undefined; form(cap: string, answerId: string, fields: Fields): Promise<FormResult | undefined>;
+		probe(key: string): Promise<Editor | undefined>; commands(key: string, prefix: string): Promise<Cmd[] | undefined>; close(key: string, keepPane: boolean, ifStashable?: boolean): Promise<{ accepted: boolean; reason?: string } | undefined>; stashCheck(key: string): Promise<{ reason?: string } | undefined>; doc(cap: string): { key: string; doc: Doc } | undefined; form(cap: string, answerId: string, fields: Fields): Promise<FormResult | undefined>;
 	} = {
 		receive,
 		get running() { return active; },
@@ -156,7 +157,7 @@ export function createHub(pi: ExtensionAPI, me: string, local: Bridge) {
 			active = false;
 			[bridges, bound, targets, reach, shelves].forEach((m) => m.clear());
 			caps.clear(); // a capability lives as long as its server
-			[...waiting.values(), ...probes.values(), ...lists.values(), ...forms.values(), ...closes.values()].forEach((w) => w());
+			[...waiting.values(), ...probes.values(), ...lists.values(), ...forms.values(), ...closes.values(), ...checks.values()].forEach((w) => w());
 		},
 		/** Binds each relayed list to a unit, from this net reading's sessions and registry. */
 		relayed(sessions, refs) {
@@ -209,7 +210,9 @@ export function createHub(pi: ExtensionAPI, me: string, local: Bridge) {
 		probe: (key) => request(key, probes, () => checkProbe({ ...local.probe() }), (probeId) => ({ type: "probe", probeId })),
 		/** The session's commands that match `prefix`, as its bridge lists them. */
 		/** Asks the session to quit as /boss close does (keeping its pane when `keepPane`); undefined when its bridge did not answer. */
-		close: (key, keepPane) => request(key, closes, () => local.close(keepPane), (reqId) => ({ type: "close", reqId, keepPane })),
+		close: (key, keepPane, ifStashable = false) => request(key, closes, () => local.close(keepPane, ifStashable), (reqId) => ({ type: "close", reqId, keepPane, ...(ifStashable ? { ifStashable } : {}) })),
+		/** Whether the session can be stashed (stash.ts): `{}` when it can, a reason when not, undefined when its bridge did not answer. */
+		stashCheck: (key) => request(key, checks, () => ((r) => (r ? { reason: r } : {}))(local.stashCheck()), (reqId) => ({ type: "stash-check", reqId })),
 		commands: (key, prefix) => request(key, lists, () => checkCommands(local.commands(prefix)), (reqId) => ({ type: "commands", reqId, prefix })),
 		/** A listed document by its capability, as its bridge lists it now (a list that changed since the reading counts, a bridge that left does not). */
 		doc(cap) {

package/src/gui.ts

@@ -70,7 +70,7 @@ export async function startGui({ read, net, call, hub, dir = BUNDLE, paired, por
 		if (n) await tick();
 		return n;
 	};
-	const control = createControl({ lookup: (key) => net?.lookup(key), call, csrf, canonical, pair, remoteOn: onRemote, remoteOff: onRemoteOff, paired: { on: () => Boolean(access.remote), ...access.devices, unsaved: access.unsaved }, saveFailed: onSaveFailed, spawn, close: close && (async (kind, json) => (await tick(), close(kind, json))), dismiss: async (key) => typeof key === "string" && Boolean(net?.dismiss?.(key)) && (await tick(), true), dismissAll, mirrors, stop, secret: waitsForSecret, answers: hub && { replay: hub.replay, ended: hub.ended, send: hub.send, probe: hub.probe, commands: hub.commands, target: async (key) => (await tick(), hub.target(key)) } });
+	const control = createControl({ lookup: (key) => net?.lookup(key), call, csrf, canonical, pair, remoteOn: onRemote, remoteOff: onRemoteOff, paired: { on: () => Boolean(access.remote), ...access.devices, unsaved: access.unsaved }, saveFailed: onSaveFailed, spawn, close: close && (async (kind, json) => (await tick(), close(kind, json, tick))), dismiss: async (key) => typeof key === "string" && Boolean(net?.dismiss?.(key)) && (await tick(), true), dismissAll, mirrors, stop, secret: waitsForSecret, answers: hub && { replay: hub.replay, ended: hub.ended, send: hub.send, probe: hub.probe, commands: hub.commands, target: async (key) => (await tick(), hub.target(key)) } });
 	let last: string | undefined, problem: string | undefined, inflight: Promise<void> | undefined;
 	let poll: ReturnType<typeof setInterval> | undefined, beat: ReturnType<typeof setInterval> | undefined;
 	const send = (to: ServerResponse, data: string, event?: string) => to.writableEnded || to.write(`${event ? `event: ${event}\n` : ""}data: ${data}\n\n`); // a reading in flight at stop ends after the streams

package/src/handover.ts

@@ -51,6 +51,24 @@ export async function requestStop(r: GuiRecord, asked: Asked, sleep: (ms: number
 	return false;
 }
 
+/** One POST to a recorded server's API from this machine, as its own page sends it: the status and the JSON body (status 0 when it did not answer). */
+export function postServer(r: GuiRecord, path: string, json: Record<string, unknown>, timeoutMs: number) {
+	const body = JSON.stringify(json), origin = `http://127.0.0.1:${r.port}`;
+	return new Promise<{ status: number; body: Record<string, unknown> }>((done) => {
+		const headers = { host: `127.0.0.1:${r.port}`, origin, "content-type": "application/json", "x-sb-csrf": r.csrf ?? "", "content-length": Buffer.byteLength(body) };
+		const req = request({ host: "127.0.0.1", port: r.port, path: `/${r.token}/api/${path}`, method: "POST", headers, agent: false, timeout: timeoutMs }, (res) => {
+			let text = "";
+			res.setEncoding("utf8").on("data", (c: string) => (text += c)).on("end", () => {
+				let parsed: Record<string, unknown> = {};
+				try { parsed = JSON.parse(text) as Record<string, unknown>; } catch { /* a body that is not JSON says nothing more than its status */ }
+				done({ status: res.statusCode ?? 0, body: parsed });
+			});
+		});
+		req.on("error", () => done({ status: 0, body: {} })).on("timeout", () => (req.destroy(), done({ status: 0, body: {} })));
+		req.end(body);
+	});
+}
+
 /** Whether a recorded server answers its own page. */
 export const answers = (r: GuiRecord) =>
 	new Promise<boolean>((done) => {

package/src/host.ts

@@ -62,7 +62,7 @@ export function createHost({ pi, cfg, s, guiDir, me, tell }: Kit, { bridge, conn
 	const share = (take = false, manual = false, was = false) =>
 		(opening ??= (async () => {
 			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, 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) => s.hub?.close(key, keepPane) }) });
+			const start = (prefer: { port?: number; remotePort?: number; token?: string; csrf?: string }, net = netSource({ run, world, sessions, 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 }) });
 			const shared = await sharedGui(guiDir, [label(), me()], start, sleep, { version, take });
 			if ((s.gui = shared.mine) && !manual) await resume(s.gui, was);
 			return shared;

package/src/index.ts

@@ -18,6 +18,7 @@ import { createReach } from "./reach.ts";
 import { tailscale } from "./remote.ts";
 import { herdrEvents, herdrWatch } from "./server-watch.ts";
 import { registerSession } from "./session.ts";
+import { createStashing } from "./stashing.ts";
 import { type Config, createKit, type Deps } from "./state.ts";
 import { createTools } from "./tools.ts";
 import { createTower } from "./tower.ts";
@@ -50,7 +51,7 @@ export function createStrawBoss({ run: given, world: reading, api = herdrApi(),
 		const host = createHost(kit, { bridge, connected: membership.connected });
 		closeSelf = createClosing(kit);
 		registerSession(kit, { briefing, presence, membership, guard, host, reach, digest, startTower: createTower(kit, { membership, presence, tools }) });
-		registerBoss(kit, { host, membership, reach, closeSelf });
+		registerBoss(kit, { host, membership, reach, closeSelf, stashing: createStashing(kit, { host }) });
 	};
 }
 

package/src/stash.ts

@@ -0,0 +1,220 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { Reply } from "./control.ts";
+import { createTab, type HerdrRun, isSub, type Pane, panes, parentOf, report, result, type Session, type Sleep, startPi, tabs, waitFor, workspaces } from "./herdr.ts";
+
+// Stash and pop (docs/specs/2026-10-22-stash/spec.md). A stash puts a whole base away: it checks that every pane can be resumed losing
+// nothing (Herdr's view here, each session's own view through its bridge's `stash-check`), writes a manifest of what ran where, then closes
+// the base as its close button does (closer.ts). A pop opens a new workspace from the manifest and resumes each pi from its session file:
+// the tower first (its session marks it a tower), then per tab the main (with the one-time sb_open_main token, as spawn.ts opens a main),
+// then the members. Anything a resume cannot bring back (a running turn, a subagent, a monitor, a busy shell) refuses the stash instead.
+//   POST /<token>/api/close/stash {workspace, name}    checks, writes <state dir>/stash/<name>.json, then closes the base
+
+export type StashRole = "tower" | "main" | "member";
+export interface StashPane { kind: StashRole | "shell"; cwd: string; session?: string; name?: string }
+export interface StashTab { label?: string; panes: StashPane[] }
+export interface Stash { version: 1; name: string; label: string; cwd: string; stashedAt: string; tabs: StashTab[] }
+
+const ROLES = new Set<string>(["tower", "main", "member"]), SETTLED = new Set(["idle", "done"]);
+const SHELLS = new Set(["zsh", "bash", "fish", "sh", "dash", "ksh", "tcsh", "csh", "nu", "login"]);
+const MAX_NAME = 64, CHECK_ROUNDS = 3, CHECK_GAP_MS = 2000, JOIN_MS = 60_000;
+const no = (status: number, error: string, reason: string): Reply => ({ status, body: { error, reason } });
+
+/** A stash name is a file name: at most 64 characters, no slash, backslash, or control character, not starting with a dot. */
+export const nameOk = (name: unknown): name is string => typeof name === "string" && name.length > 0 && name.length <= MAX_NAME && name === name.trim() && !name.startsWith(".") && !/[/\\\p{Cc}]/u.test(name);
+const dirOf = (stateDir: string) => join(stateDir, "stash");
+export const stashFile = (stateDir: string, name: string) => join(dirOf(stateDir), `${name}.json`);
+
+/** The stashes waiting to be popped, by name. */
+export function listStashes(stateDir: string): string[] {
+	try {
+		return readdirSync(dirOf(stateDir)).filter((f) => f.endsWith(".json")).map((f) => f.slice(0, -5)).filter(nameOk).sort((a, b) => a.localeCompare(b));
+	} catch {
+		return [];
+	}
+}
+
+const str = (v: unknown): v is string => typeof v === "string" && v.length > 0;
+function paneOk(p: unknown): p is StashPane {
+	const x = p as Partial<StashPane> | null;
+	return x !== null && typeof x === "object" && (x.kind === "shell" || ROLES.has(x.kind as string)) && str(x.cwd) && (x.session === undefined || str(x.session)) && (x.name === undefined || typeof x.name === "string");
+}
+/** `session` is absent for a pi that never wrote its file (pi writes it at the first reply): it has no conversation to lose, so a pop starts it fresh in its role. */
+/** What a pop can open: the stash checks it before it closes anything, the pop before it opens anything. */
+const stashOk = (st: Stash | null) => st?.version === 1 && str(st.label) && str(st.cwd) && Array.isArray(st.tabs) && st.tabs.length > 0 && st.tabs.every((t) => Array.isArray(t?.panes) && t.panes.length > 0 && t.panes.every(paneOk) && (t.label === undefined || typeof t.label === "string"));
+export function readStash(stateDir: string, name: string, file = stashFile(stateDir, name)): Stash {
+	if (!nameOk(name)) throw new Error(`"${name}" is not a stash name`);
+	let st: Stash;
+	try {
+		st = JSON.parse(readFileSync(file, "utf8")) as Stash;
+	} catch (error) {
+		throw new Error((error as NodeJS.ErrnoException).code === "ENOENT" ? `Nothing is stashed as "${name}"` : `The stash "${name}" cannot be read: ${(error as Error).message}`);
+	}
+	if (!stashOk(st)) throw new Error(`The stash "${name}" is not a manifest this version reads`);
+	return st;
+}
+
+/** What runs in a shell pane's foreground besides the shell; undefined when Herdr cannot say. */
+async function foreground(run: HerdrRun, paneId: string): Promise<string[] | undefined> {
+	try {
+		const procs = (await result(run, ["pane", "process-info", "--pane", paneId])).process_info?.foreground_processes as { name?: string; argv0?: string }[] | undefined;
+		if (!Array.isArray(procs)) return undefined;
+		return procs.map((p) => String(p.argv0 ?? p.name ?? "").replace(/^-/, "").split("/").pop()!).filter((n) => !SHELLS.has(n));
+	} catch {
+		return undefined;
+	}
+}
+
+/** Herdr's side of the check, and the manifest's tabs: tower tab first, then Herdr's tab order, each tab's panes in Herdr's order. */
+export async function survey(run: HerdrRun, workspaceId: string, live: Session[]) {
+	const all = await workspaces(run), ws = all.find((w) => w.workspace_id === workspaceId);
+	if (!ws) return undefined;
+	const reasons: string[] = [], agents: Session[] = [], out: StashTab[] = [];
+	if (isSub(ws)) reasons.push(`${ws.label} is a sub workspace; stash the base it belongs to`);
+	// A sub workspace is neither recorded nor closed: anything running in it would lose the base it reports to.
+	for (const sub of all.filter((w) => isSub(w) && parentOf(all, w)?.workspace_id === workspaceId)) {
+		const ps = await panes(run, sub.workspace_id), busy = ps.filter((p) => p.agent).length;
+		if (busy) reasons.push(`its sub workspace ${sub.label} runs ${busy} agent${busy > 1 ? "s" : ""}`);
+		for (const p of ps.filter((x) => !x.agent)) if ((await foreground(run, p.pane_id))?.length !== 0) reasons.push(`pane ${p.pane_id} in its sub workspace ${sub.label} runs something`);
+	}
+	const here = await panes(run, workspaceId), sessionAt = (p: Pane) => live.find((s) => s.herdrLocation?.paneId === p.pane_id);
+	for (const t of await tabs(run, workspaceId)) {
+		const tab: StashTab = { ...(t.label ? { label: t.label } : {}), panes: [] };
+		for (const p of here.filter((x) => x.tab_id === t.tab_id)) {
+			const cwd = p.cwd ?? ws.worktree?.checkout_path ?? "", session = sessionAt(p), who = session?.name ?? `pane ${p.pane_id}`;
+			if (!p.agent) {
+				const fg = await foreground(run, p.pane_id);
+				if (!cwd) reasons.push(`pane ${p.pane_id} has no folder Herdr knows of`);
+				if (!fg) reasons.push(`Herdr cannot say what runs in pane ${p.pane_id}`);
+				else if (fg.length) reasons.push(`pane ${p.pane_id} runs ${fg.join(", ")}`);
+				tab.panes.push({ kind: "shell", cwd });
+				continue;
+			}
+			const role = p.tokens?.sb_role ?? "";
+			if (p.agent !== "pi") reasons.push(`pane ${p.pane_id} runs ${p.agent}, which a stash cannot resume`);
+			else if (!ROLES.has(role)) reasons.push(`${who} is a subagent or outside the net`);
+			if (p.agent !== "pi" || !ROLES.has(role)) continue;
+			if (!SETTLED.has(p.agent_status ?? "")) reasons.push(`${who} is ${p.agent_status ?? "in an unknown state"}`);
+			// A path Herdr names whose file does not exist yet is a session that never replied: nothing to resume, it starts fresh at pop.
+			const named = p.agent_session?.value, file = named && existsSync(named) ? named : undefined;
+			if (!named) reasons.push(`${who} has no session file Herdr knows of`);
+			if (!cwd) reasons.push(`${who} has no folder Herdr knows of`);
+			if (session) agents.push(session);
+			else reasons.push(`${who} is not on the intercom net`);
+			tab.panes.push({ kind: role as StashRole, cwd, ...(file ? { session: file } : {}), ...(session?.name ? { name: session.name } : {}) });
+		}
+		if (tab.panes.length) out.push(tab);
+	}
+	const towered = (t: StashTab) => t.panes.some((p) => p.kind === "tower");
+	const tabsOut = [...out.filter(towered), ...out.filter((t) => !towered(t))];
+	const cwd = tabsOut.flatMap((t) => t.panes).find((p) => p.kind === "tower")?.cwd ?? ws.worktree?.checkout_path ?? tabsOut[0]?.panes[0]?.cwd ?? "";
+	if (!tabsOut.length) reasons.push(`${ws.label} has nothing in it to stash`);
+	return { label: ws.label, cwd, tabs: tabsOut, reasons, agents };
+}
+
+export interface StashDeps { run: HerdrRun; sleep: Sleep; sessions(): Promise<Session[]>; check(key: string): Promise<{ reason?: string } | undefined>; stateDir: string; now?: () => Date }
+
+/** The server's stash: every check first (nothing closes on a refusal), then the manifest, then `closeBase` (the close-base batch). */
+export async function stashBase(d: StashDeps, json: Record<string, unknown>, closeBase: (workspace: string) => Promise<Reply>, refresh?: () => Promise<unknown>): Promise<Reply> {
+	if (!str(json.workspace) || json.workspace.length > 200) return no(400, "bad_request", "A base is named by its workspace.");
+	if (!nameOk(json.name)) return no(400, "bad_request", `A stash name has at most ${MAX_NAME} characters, no slash, backslash, or control character, and does not start with a dot.`);
+	const name = json.name, file = stashFile(d.stateDir, name);
+	if (existsSync(file)) return no(409, "exists", `Something is stashed as "${name}" already; pop it or pick another name.`);
+	const sv = await survey(d.run, json.workspace, await d.sessions());
+	if (!sv) return no(404, "not_found", "That base is not open any more.");
+	// A bridge that has not told this server about itself yet (one just started) gets another round after the net is read again.
+	const reasons = [...sv.reasons], named = (s: Session) => s.name ?? s.id.slice(0, 8);
+	let pending = sv.agents;
+	for (let round = 0; pending.length && round < CHECK_ROUNDS; round++) {
+		if (round) (await d.sleep(CHECK_GAP_MS), await refresh?.());
+		const got = await Promise.all(pending.map(async (s) => ({ s, r: await d.check(s.id) })));
+		for (const { s, r } of got) if (r?.reason) reasons.push(`${named(s)}: ${r.reason}`);
+		pending = got.filter(({ r }) => !r).map(({ s }) => s);
+	}
+	for (const s of pending) reasons.push(`${named(s)} did not answer the stash check (an older pi-straw-boss, or a stuck session)`);
+	// Herdr's side once more, since the rounds took seconds: a shell job or a subagent started meanwhile refuses too. The sessions' own side is
+	// asked again by the close itself (`ifStashable`), so a turn started now refuses that session's quit and stops the batch.
+	if (!reasons.length) reasons.push(...((await survey(d.run, json.workspace, await d.sessions()))?.reasons ?? ["the base is not open any more"]));
+	if (reasons.length) return no(409, "refused", `Nothing was stashed: ${reasons.join("; ")}.`);
+	const stash: Stash = { version: 1, name, label: sv.label, cwd: sv.cwd, stashedAt: (d.now?.() ?? new Date()).toISOString(), tabs: sv.tabs };
+	if (!stashOk(stash)) return no(500, "unreadable", "Nothing was stashed: the manifest would not be one a pop can read.");
+	mkdirSync(dirOf(d.stateDir), { recursive: true, mode: 0o700 });
+	writeFileSync(file, JSON.stringify(stash, null, 2), { mode: 0o600, flag: "wx" });
+	const closed = await closeBase(json.workspace);
+	if (closed.status === 200) return { status: 200, body: { stashed: name, sessions: sv.agents.length } };
+	// A batch that stopped half way leaves sessions running beside ones that quit: popping would run a session file twice, so the manifest goes.
+	rmSync(file, { force: true });
+	const quit = sv.tabs.flatMap((t) => t.panes).filter((p) => p.session).map((p) => `${p.name ?? "?"}: pi --session ${p.session}`);
+	const why = (closed.body as { reason?: string }).reason ?? "the base did not close";
+	return no(closed.status, "stash_failed", `${why} Nothing is stashed; a session that did quit resumes with its own file (${quit.join("; ")}).`);
+}
+
+/** `agentDir`: the popping session's PI_CODING_AGENT_DIR, when it runs under one, so each pi resumes with the same settings and extensions. */
+export interface PopDeps { run: HerdrRun; sleep: Sleep; stateDir: string; live(sessionId: string): Promise<boolean>; agentDir?: string; now?: () => Date }
+const RANK: Record<StashPane["kind"], number> = { tower: 0, main: 1, member: 2, shell: 3 };
+const roleEnv = (kind: StashPane["kind"]) => (kind === "shell" ? [] : [`STRAW_BOSS_ROLE=${kind}`]), flags = (env: string[]) => env.flatMap((e) => ["--env", e]);
+
+/** Resumes one pi in its pane and waits until it is back in its role (a member may come back as the tab's main: the guard's choice). */
+async function resume({ run, sleep, live }: PopDeps, ws: string, paneId: string, p: StashPane) {
+	if (p.kind === "tower") await report(run, "pane", paneId, { sb_role: "tower" });
+	if (p.kind === "main") await report(run, "pane", paneId, { sb_open_main: "1" }); // authorises exactly this pi to promote itself (session.ts)
+	// Herdr agent names are unique across workspaces and lowercase only.
+	const agent = p.kind === "tower" ? `tower-${ws.toLowerCase()}` : `${p.kind}-${randomUUID().slice(0, 8)}`;
+	await startPi(run, sleep, agent, paneId, [...(p.session ? ["--session", p.session] : []), ...(p.name ? ["--name", p.name] : [])]);
+	const back = p.kind === "tower"
+		? await waitFor(sleep, async () => ((id) => id && live(id))((await workspaces(run)).find((w) => w.workspace_id === ws)?.tokens?.tower), JOIN_MS, 1000)
+		: await waitFor(sleep, async () => ((r) => (p.kind === "main" ? r === "main" : r === "member" || r === "main"))((await panes(run, ws)).find((x) => x.pane_id === paneId)?.tokens?.sb_role), JOIN_MS, 500);
+	if (!back) throw new Error(`${p.name ?? p.session ?? p.kind} did not come back as the ${p.kind} within ${JOIN_MS / 1000} s (pane ${paneId})`);
+}
+
+/**
+ * Opens the stash `name` in a new workspace; on any failure the new workspace closes and the manifest goes back, so popping again starts over.
+ * The manifest is claimed first by moving it into stash/.popping/ (one rename, which only one session wins), so two pops never run one session file twice.
+ */
+export async function popBase(d: PopDeps, name: string): Promise<{ workspace: string; label: string; sessions: number }> {
+	if (!nameOk(name)) throw new Error(`"${name}" is not a stash name`);
+	const claimed = join(dirOf(d.stateDir), ".popping", `${name}.json`);
+	mkdirSync(dirname(claimed), { recursive: true, mode: 0o700 });
+	try {
+		renameSync(stashFile(d.stateDir, name), claimed);
+	} catch (error) {
+		throw new Error((error as NodeJS.ErrnoException).code === "ENOENT" ? `Nothing is stashed as "${name}" (or another session is popping it)` : (error as Error).message);
+	}
+	try {
+		const r = await open(d, name, claimed);
+		mkdirSync(join(dirOf(d.stateDir), "popped"), { recursive: true, mode: 0o700 });
+		renameSync(claimed, join(dirOf(d.stateDir), "popped", `${name}-${(d.now?.() ?? new Date()).toISOString().replace(/[:.]/g, "-")}.json`));
+		return r;
+	} catch (error) {
+		renameSync(claimed, stashFile(d.stateDir, name));
+		throw error;
+	}
+}
+async function open(d: PopDeps, name: string, file: string) {
+	const { run } = d, st = readStash(d.stateDir, name, file), all = st.tabs.flatMap((t) => t.panes);
+	const envOf = (kind: StashPane["kind"]) => [...roleEnv(kind), ...(d.agentDir ? [`PI_CODING_AGENT_DIR=${d.agentDir}`] : [])];
+	const gone = [...new Set([...all.filter((p) => p.session && !existsSync(p.session)).map((p) => p.session!), ...all.map((p) => p.cwd).filter((c) => !statSync(c, { throwIfNoEntry: false })?.isDirectory())])];
+	if (gone.length) throw new Error(`Nothing was opened: ${gone.join(", ")} no longer exist${gone.length > 1 ? "" : "s"}`);
+	const root = st.tabs[0]!.panes[0]!;
+	const created = await result(run, ["workspace", "create", "--cwd", root.cwd, "--label", st.label, "--no-focus", ...flags(envOf(root.kind))]);
+	const ws: string = created.workspace.workspace_id;
+	try {
+		let sessions = 0;
+		for (const [i, tab] of st.tabs.entries()) {
+			const ids: string[] = [];
+			for (const [j, p] of tab.panes.entries()) {
+				if (i === 0 && j === 0) ids.push(created.root_pane.pane_id as string);
+				else if (j === 0) ids.push((await createTab(run, ws, p.cwd, envOf(p.kind), tab.label)).paneId);
+				else ids.push((await result(run, ["pane", "split", ids[j - 1]!, "--direction", "right", "--cwd", p.cwd, "--no-focus", ...flags(envOf(p.kind))])).pane.pane_id as string);
+			}
+			if (i === 0 && tab.label) await run(["tab", "rename", created.tab.tab_id as string, tab.label]);
+			const starts = tab.panes.map((p, j) => ({ p, pane: ids[j]! })).filter(({ p }) => p.kind !== "shell").sort((a, b) => RANK[a.p.kind] - RANK[b.p.kind]);
+			for (const { p, pane } of starts) (await resume(d, ws, pane, p), sessions++);
+		}
+		return { workspace: ws, label: st.label, sessions };
+	} catch (error) {
+		await run(["workspace", "close", ws]).catch(() => {});
+		throw error;
+	}
+}

package/src/stashing.ts

@@ -0,0 +1,46 @@
+import { existsSync } from "node:fs";
+import { postServer, readRecord } from "./handover.ts";
+import { workspaces } from "./herdr.ts";
+import type { createHost } from "./host.ts";
+import { listStashes, nameOk, popBase, stashFile } from "./stash.ts";
+import type { Kit } from "./state.ts";
+
+// /boss stash and /boss pop, this session's side (stash.ts holds the checks, the manifest, and the reopening). A stash runs in the session
+// that holds the GUI server, the only one that can ask every bridge in the base whether it may be put away and then ask it to quit; this
+// session starts that server when none runs, with no browser. A pop needs no server: it runs here, from any session in Herdr.
+
+// The checks take up to three rounds of a few seconds, then every agent has 30 s to quit.
+const STASH_MS = 120_000;
+
+export function createStashing({ cfg, s, guiDir, tell }: Kit, { host }: { host: Pick<ReturnType<typeof createHost>, "share" | "sessions"> }) {
+	const { run, sleep } = cfg;
+	return {
+		names: () => listStashes(guiDir),
+		/** Stashes this session's base under `name`, by default the workspace label. When this session is in it, it quits with the rest. */
+		async stash(given: string | undefined) {
+			if (!s.joined && !s.isTower) throw new Error("Only a session of the net stashes its base: this one has not joined");
+			const ws = s.at.workspaceId, label = (await workspaces(run)).find((w) => w.workspace_id === ws)?.label ?? ws, name = given?.trim() || label;
+			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 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}"…`);
+			const reply = await postServer(record, "close/stash", { workspace: ws, name }, STASH_MS);
+			if (reply.status === 200) return tell(`Stashed ${label} as "${name}" (${String(reply.body.sessions)} sessions); /boss pop ${name} brings it back`);
+			const why = typeof reply.body.reason === "string" ? reply.body.reason : reply.status ? `the server answered ${reply.status}` : "the GUI server did not answer";
+			tell(reply.status === 404 && reply.body.error === "not_found" ? `The GUI server cannot stash yet (an older pi-straw-boss in session ${shared.owner}); /reload it first` : why, "error");
+		},
+		/** Pops `given`; with no name, the only stash, or the one picked from the list. */
+		async pop(given: string | undefined) {
+			const names = listStashes(guiDir);
+			if (!names.length) return tell("Nothing is stashed");
+			const name = given?.trim() || (names.length === 1 ? names[0] : await s.ui?.select("Pop which stash?", names));
+			if (!name) return;
+			tell(`Opening "${name}"…`);
+			const live = async (id: string) => (await host.sessions()).some((x) => x.id === id);
+			const r = await popBase({ run, sleep, stateDir: guiDir, live, agentDir: cfg.env.PI_CODING_AGENT_DIR }, name);
+			tell(`Popped "${name}": ${r.sessions} sessions are back in ${r.label}`);
+		},
+	};
+}