@alphacoder-v0/pi-loops 0.22.8 → 0.24.1

package/src/lease.ts

@@ -0,0 +1,537 @@
+/**
+ * Who does a conversation's automated work: one lease file per session, naming one extension
+ * instance. A second window on the same session is a viewer. There is no heartbeat and no timeout:
+ * a lease changes hands only when its holder's process is gone, so nothing here measures time and a
+ * suspended laptop cannot move one. The epoch is the fencing token every claim checks.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { execFileSync } from "node:child_process";
+import { pidAlive, withFileLockSync, writeFileAtomic } from "./lock.ts";
+import { stamp } from "./schedule.ts";
+
+export interface LeaseHolder {
+	kind: "terminal" | "host";
+	pid: number;
+	instance: string;
+	procStart?: string;
+	acquiredAt: string;
+	mode?: "tui" | "rpc" | "print" | "json" | "unbound";
+	/**
+	 * Written by a window that stands aside (`LeaseBinding.standAside`): it keeps the lease, so nothing
+	 * else writes into the conversation it has open, and delivers nothing, since its copy is behind the
+	 * file. A reader that does not know the field ignores it; one that does (`holderDelivers`) stops
+	 * waiting on this holder for a message typed into the browser page.
+	 */
+	aside?: true;
+	/** mcp.toml server names whose pushes inject into this holder's chat. */
+	pushServers: string[];
+	/** Host only: the turn it is running in this conversation right now. */
+	busy?: { runId: string; jobId?: string; since: string };
+	/**
+	 * Written by a window that is a conversation open in the browser page: the background process starts
+	 * it with `PI_LOOPS_PAGE_CHILD=1`. Read by `decideAcquire`, where a `tui` window takes the
+	 * conversation from such a holder, and by the page server, which shows who holds a conversation.
+	 */
+	page?: true;
+	/**
+	 * Written by that page holder and by a terminal (`tui`) holder (`LeaseStore.setTurn`) while pi runs
+	 * or compacts (`TURN_EVENTS`): when that started. Read by `decideAcquire` for a page holder only:
+	 * while it is set, a `tui` window waits as a viewer and takes the conversation on its next refresh
+	 * after the turn. Read by the page server for a terminal holder: the page's copy of the
+	 * conversation is read again when the turn ends (`shouldReadAgain`), not in the middle of one.
+	 */
+	turnSince?: string;
+	/** This holder writes `turnSince`. A holder without it (an older terminal) is never read again by a viewer page. */
+	turns?: true;
+}
+
+/** The least time between two reads of a terminal-held conversation for the page: a turn writes in bursts. */
+export const VIEWER_REREAD_GAP_MS = 5_000;
+
+/**
+ * Whether the page's copy of a conversation a terminal holds is read again from the file. Only once
+ * the terminal says no turn runs (it writes `turnSince` while one does, and `turns` says it does),
+ * only when the file changed since the page last read it and what was added holds a message (a run
+ * card or an audit entry is not worth a reload), only while the page's own pi is idle, and at most
+ * every `VIEWER_REREAD_GAP_MS`. `newMessage` is asked last: it reads the bytes added.
+ */
+export function shouldReadAgain(i: {
+	holder?: { kind: string; mine: boolean; turns?: boolean; turnSince?: string };
+	busyHere: boolean;
+	readMark: { size: number; mtimeMs: number };
+	now: { size: number; mtimeMs: number };
+	sinceLastMs: number;
+	newMessage: () => boolean;
+}): boolean {
+	const h = i.holder;
+	if (!h || h.kind !== "terminal" || h.mine || !h.turns || h.turnSince !== undefined) return false;
+	if (i.busyHere || i.sinceLastMs < VIEWER_REREAD_GAP_MS) return false;
+	if (i.now.size === i.readMark.size && i.now.mtimeMs === i.readMark.mtimeMs) return false;
+	return i.newMessage();
+}
+
+/**
+ * The `busy.jobId` pi-loops writes while it holds a closed conversation to deliver what is queued for
+ * it (a rule result, a message), not to run a job: there is no job to name.
+ */
+export const DELIVERY_JOB_ID = "promotion";
+
+/** What keeps a page holder mid-turn: a run, or a compaction, which can come with no run at all (`/compact`). */
+export type TurnReason = "run" | "compaction";
+export type TurnMarks = Partial<Record<TurnReason, string>>;
+
+/**
+ * pi's events that start or end a reason. A run lasts until `agent_settled`, not `agent_end`: pi
+ * retries, compacts, continues and takes queued messages in between, all of it in the same run.
+ */
+export const TURN_EVENTS = {
+	agent_start: { reason: "run", busy: true },
+	agent_settled: { reason: "run", busy: false },
+	session_before_compact: { reason: "compaction", busy: true },
+	session_compact: { reason: "compaction", busy: false },
+	session_compact_failed: { reason: "compaction", busy: false },
+} as const satisfies Record<string, { reason: TurnReason; busy: boolean }>;
+
+/** The marks after pi's `event` at `now`. A reason already set keeps its first stamp; any other event changes nothing. */
+export function markTurnEvent(marks: TurnMarks, event: string, now: string): TurnMarks {
+	const e = (TURN_EVENTS as Record<string, { reason: TurnReason; busy: boolean }>)[event];
+	if (!e) return marks;
+	const { [e.reason]: was, ...rest } = marks;
+	return e.busy ? { ...rest, [e.reason]: was ?? now } : rest;
+}
+
+/** The earliest stamp of any reason: what `LeaseHolder.turnSince` says, undefined when none holds. */
+export function turnSinceOf(marks: TurnMarks): string | undefined {
+	return Object.values(marks).sort((a, b) => Date.parse(a) - Date.parse(b))[0];
+}
+
+export interface SessionLease {
+	v: 1;
+	sessionId: string;
+	sessionFile?: string;
+	cwd?: string;
+	epoch: number;
+	holder: LeaseHolder | null;
+	updatedAt: string;
+	/**
+	 * The session file's mtime when the host gave the conversation back. A file still at that mtime has
+	 * been written by nobody since, so the two-minute quiet guard — there to protect someone else's
+	 * writes — does not hold the host back from its own next turn or promotion.
+	 */
+	hostLeftMtime?: number;
+}
+
+export interface ProcessProbe {
+	alive(pid: number): boolean;
+	startTime(pid: number): string | undefined;
+	bootedAt(): number;
+}
+
+/**
+ * `ps -o lstart=` prints a date in the caller's language and time zone, and a process's identity is
+ * compared between processes that may not share either: a LaunchAgent host has no LANG or TZ, a
+ * window has the person's. Fixed, so every process writes and reads the same string.
+ */
+export const PS_STABLE_ENV: NodeJS.ProcessEnv = { ...process.env, LC_ALL: "C", LANG: "C", TZ: "UTC" };
+
+export function procStart(pid: number): string | undefined {
+	try {
+		if (process.platform === "linux") {
+			const stat = fs.readFileSync(`/proc/${pid}/stat`, "utf8");
+			const close = stat.lastIndexOf(")");
+			return stat.slice(close + 2).split(" ")[19];
+		}
+		if (process.platform === "darwin") return execFileSync("ps", ["-o", "lstart=", "-p", String(pid)], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], env: PS_STABLE_ENV }).trim() || undefined;
+	} catch {
+		return undefined; // the pid is gone, or this OS hides it: holderAlive falls back to the boot time
+	}
+	return undefined;
+}
+
+export const systemProbe: ProcessProbe = {
+	alive: pidAlive,
+	startTime: procStart,
+	bootedAt: () => Date.now() - os.uptime() * 1000,
+};
+
+/**
+ * The pi windows open on this machine, by the leases they hold (a terminal or the browser's pi): what
+ * `[host] auto = false` waits on. Windows write no presence file since 0.23, so the leases are the record.
+ */
+export function openWindowPids(leases: Pick<LeaseStore, "list">, probe: ProcessProbe = systemProbe): Set<number> {
+	const pids = new Set<number>();
+	for (const lease of leases.list()) if (lease.holder && lease.holder.kind === "terminal" && holderAlive(lease.holder, probe)) pids.add(lease.holder.pid);
+	return pids;
+}
+
+export function holderAlive(h: LeaseHolder, probe: ProcessProbe = systemProbe): boolean {
+	if (!probe.alive(h.pid)) return false;
+	const start = probe.startTime(h.pid);
+	if (h.procStart !== undefined && start !== undefined && start !== h.procStart) return false;
+	if ((h.procStart === undefined || start === undefined) && Date.parse(h.acquiredAt) < probe.bootedAt() - 60_000) return false;
+	return true;
+}
+
+export function sameHolder(a: Pick<LeaseHolder, "pid" | "instance">, b: Pick<LeaseHolder, "pid" | "instance">): boolean {
+	return a.pid === b.pid && a.instance === b.instance;
+}
+
+/**
+ * Whether a live holder delivers the person rows addressed to its conversation. A window standing
+ * aside, and one in `print` or `json` mode (a one-shot run holds its conversation but would swallow a
+ * message into a turn about to exit), hold the lease and hand nothing over; a message typed into the
+ * browser page would wait on them for ever. The page's own pi runs such a row itself instead
+ * (src/engine.ts), and the page offers to send it over rpc, as 0.22 did.
+ */
+export function holderDelivers(h: LeaseHolder): boolean {
+	return h.aside !== true && h.mode !== "print" && h.mode !== "json";
+}
+
+export type AcquireOutcome =
+	| { outcome: "held"; lease: SessionLease }
+	| { outcome: "acquired"; lease: SessionLease; tookFromPid?: number; tookFromHost?: { pid: number; runId?: string }; tookFromPage?: number }
+	| { outcome: "viewer"; lease: SessionLease; holderPid: number };
+
+export function decideAcquire(current: SessionLease | undefined, sessionId: string, me: LeaseHolder, info: { sessionFile?: string; cwd?: string }, now: number, probe: ProcessProbe = systemProbe): AcquireOutcome & { write: boolean } {
+	const updatedAt = stamp(now);
+	const mergeInfo = (lease: SessionLease): SessionLease => ({ ...lease, ...info, updatedAt });
+	if (!current || current.holder === null) return { outcome: "acquired", lease: { v: 1, sessionId, ...info, epoch: (current?.epoch ?? 0) + 1, holder: me, updatedAt }, write: true };
+	if (sameHolder(current.holder, me)) {
+		const lease = mergeInfo(current);
+		return { outcome: "held", lease, write: lease.sessionFile !== current.sessionFile || lease.cwd !== current.cwd };
+	}
+	const alive = holderAlive(current.holder, probe);
+	// A window always takes its conversation back from the host, at once: the host holds a closed
+	// conversation only to do a piece of work in it, and a person opening it comes first.
+	if (alive && current.holder.kind === "host" && me.kind === "terminal") {
+		const lease: SessionLease = { ...current, ...info, epoch: current.epoch + 1, holder: me, updatedAt };
+		return { outcome: "acquired", lease, tookFromHost: { pid: current.holder.pid, runId: current.holder.busy?.runId }, write: true };
+	}
+	// A terminal takes its conversation from the browser page between turns: the page's pi is a
+	// convenience, and the person at the keyboard comes first. Not mid-turn, which it would cut off.
+	if (alive && current.holder.page === true && current.holder.turnSince === undefined && me.kind === "terminal" && me.mode === "tui") {
+		const lease: SessionLease = { ...current, ...info, epoch: current.epoch + 1, holder: me, updatedAt };
+		return { outcome: "acquired", lease, tookFromPage: current.holder.pid, write: true };
+	}
+	if (alive) return { outcome: "viewer", lease: current, holderPid: current.holder.pid, write: false };
+	return { outcome: "acquired", lease: { ...current, ...info, epoch: current.epoch + 1, holder: me, updatedAt }, tookFromPid: current.holder.pid, write: true };
+}
+
+/** How long a closed conversation's file must have been left alone before the host writes into it. */
+export const HOST_QUIET_MS = 120_000;
+
+/**
+ * Pure. Whether the host may take `current` for one piece of work: nobody alive holds it (the host
+ * never displaces a live window), pi-loops knows its file, and the file has not been written for
+ * `quietMs` — the one guard against a pi that has the conversation open without pi-loops in it.
+ */
+export function decideHostAcquire(current: SessionLease | undefined, me: LeaseHolder, fileMtimeMs: number | undefined, now: number, probe: ProcessProbe = systemProbe, quietMs = HOST_QUIET_MS): { lease: SessionLease } | { refused: string } {
+	if (!current?.sessionFile) return { refused: "no known session file" };
+	// Itself included: a turn still running there is not interrupted by the next slot's.
+	if (current.holder && holderAlive(current.holder, probe)) return { refused: sameHolder(current.holder, me) ? "already working in it" : `held by pid ${current.holder.pid}` };
+	if (fileMtimeMs === undefined) return { refused: "session file is gone" };
+	// Either side of now: a clock set back left every file "written in the future", and every held
+	// turn refused until the clock caught up again.
+	if (Math.abs(now - fileMtimeMs) < quietMs && fileMtimeMs !== current.hostLeftMtime) return { refused: "session file changed in the last two minutes" };
+	return { lease: { ...current, epoch: current.epoch + 1, holder: me, updatedAt: stamp(now) } };
+}
+
+const validSessionId = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+/** A session id becomes a file name here and in the request store, so anything that could leave the directory is refused. */
+export function sessionFileName(sessionId: string): string {
+	if (!validSessionId.test(sessionId) || sessionId.includes("..")) throw new Error(`invalid session id: ${sessionId}`);
+	return sessionId;
+}
+
+export class LeaseStore {
+	readonly dir: string;
+	private readonly probe: ProcessProbe;
+
+	constructor(dir: string, probe: ProcessProbe = systemProbe) {
+		this.dir = dir;
+		this.probe = probe;
+	}
+
+	file(sessionId: string): string {
+		return path.join(this.dir, "leases", `${sessionFileName(sessionId)}.json`);
+	}
+
+	read(sessionId: string): SessionLease | undefined {
+		try {
+			// A regular file only: a FIFO put here would block every reader on it.
+			if (!fs.lstatSync(this.file(sessionId)).isFile()) return undefined;
+			const value: unknown = JSON.parse(fs.readFileSync(this.file(sessionId), "utf8"));
+			if (!value || typeof value !== "object") return undefined;
+			const lease = value as SessionLease;
+			return lease.v === 1 && lease.sessionId === sessionId && typeof lease.epoch === "number" ? lease : undefined;
+		} catch {
+			return undefined; // missing, torn or an invalid id: nobody holds it
+		}
+	}
+
+	/** The fencing rule: write only if the epoch on disk is still the one this critical section read (a lock broken as stale while we slept loses here). */
+	private writeIfCurrent(file: string, before: SessionLease | undefined, lease: SessionLease): boolean {
+		const current = this.read(lease.sessionId);
+		if ((current?.epoch ?? undefined) !== (before?.epoch ?? undefined)) return false;
+		writeFileAtomic(file, `${JSON.stringify(lease, null, 2)}\n`);
+		return true;
+	}
+
+	acquire(sessionId: string, me: LeaseHolder, info: { sessionFile?: string; cwd?: string } = {}): AcquireOutcome {
+		const file = this.file(sessionId);
+		return withFileLockSync(path.join(this.dir, "leases.lock"), () => {
+			const before = this.read(sessionId);
+			const decision = decideAcquire(before, sessionId, me, info, Date.now(), this.probe);
+			if (!decision.write || this.writeIfCurrent(file, before, decision.lease)) return decision;
+			return decideAcquire(this.read(sessionId), sessionId, me, info, Date.now(), this.probe);
+		});
+	}
+
+	/**
+	 * Give the conversation up. `epoch`, when given, must still be the lease's: a late release from a
+	 * turn that was taken back must not end a later lease the same holder took since. `fileMtimeMs` is
+	 * the host's own last write (see `hostLeftMtime`); any other holder's release clears it.
+	 */
+	release(sessionId: string, me: Pick<LeaseHolder, "pid" | "instance">, opts: { epoch?: number; fileMtimeMs?: number } = {}): boolean {
+		const file = this.file(sessionId);
+		return withFileLockSync(path.join(this.dir, "leases.lock"), () => {
+			const before = this.read(sessionId);
+			if (!before?.holder || !sameHolder(before.holder, me)) return false;
+			if (opts.epoch !== undefined && before.epoch !== opts.epoch) return false;
+			const { hostLeftMtime: _left, ...rest } = before;
+			const next: SessionLease = { ...rest, holder: null, epoch: before.epoch + 1, updatedAt: stamp(Date.now()), ...(opts.fileMtimeMs !== undefined ? { hostLeftMtime: opts.fileMtimeMs } : {}) };
+			return this.writeIfCurrent(file, before, next);
+		});
+	}
+
+	/** Delete the lease of a conversation no live process holds. Under the lock, so a window binding it now wins. */
+	removeIfFree(sessionId: string, probe: ProcessProbe = systemProbe): boolean {
+		return withFileLockSync(path.join(this.dir, "leases.lock"), () => {
+			const lease = this.read(sessionId);
+			if (!lease || (lease.holder && holderAlive(lease.holder, probe))) return false;
+			fs.rmSync(this.file(sessionId), { force: true });
+			return true;
+		});
+	}
+
+	setPushServers(sessionId: string, me: Pick<LeaseHolder, "pid" | "instance">, epoch: number, servers: readonly string[]): boolean {
+		const file = this.file(sessionId);
+		return withFileLockSync(path.join(this.dir, "leases.lock"), () => {
+			const before = this.read(sessionId);
+			if (!before?.holder || !sameHolder(before.holder, me) || before.epoch !== epoch) return false;
+			const next = { ...before, holder: { ...before.holder, pushServers: [...new Set(servers)].sort() }, updatedAt: stamp(Date.now()) };
+			return this.writeIfCurrent(file, before, next);
+		});
+	}
+
+	/** Mark the holder as standing aside (`LeaseHolder.aside`) on its own lease, at its own epoch; the epoch does not move. */
+	setAside(sessionId: string, me: Pick<LeaseHolder, "pid" | "instance">, epoch: number): boolean {
+		const file = this.file(sessionId);
+		return withFileLockSync(path.join(this.dir, "leases.lock"), () => {
+			const before = this.read(sessionId);
+			if (!before?.holder || !sameHolder(before.holder, me) || before.epoch !== epoch) return false;
+			return this.writeIfCurrent(file, before, { ...before, holder: { ...before.holder, aside: true }, updatedAt: stamp(Date.now()) });
+		});
+	}
+
+	/** Write `since` as the holder's `turnSince`, or delete it when undefined, on its own lease at its own epoch; the epoch does not move. */
+	setTurn(sessionId: string, me: Pick<LeaseHolder, "pid" | "instance">, epoch: number, since: string | undefined): boolean {
+		const file = this.file(sessionId);
+		return withFileLockSync(path.join(this.dir, "leases.lock"), () => {
+			const before = this.read(sessionId);
+			if (!before?.holder || !sameHolder(before.holder, me) || before.epoch !== epoch) return false;
+			const { turnSince: _was, ...holder } = before.holder;
+			return this.writeIfCurrent(file, before, { ...before, holder: since === undefined ? holder : { ...holder, turnSince: since }, updatedAt: stamp(Date.now()) });
+		});
+	}
+
+	/**
+	 * The host's acquisition for one piece of work (decideHostAcquire), compare-and-written under the
+	 * lock. Returns the lease it now holds, or why not.
+	 */
+	acquireForHost(sessionId: string, me: LeaseHolder, now = Date.now(), quietMs = HOST_QUIET_MS): { lease: SessionLease } | { refused: string } {
+		const file = this.file(sessionId);
+		return withFileLockSync(path.join(this.dir, "leases.lock"), () => {
+			const before = this.read(sessionId);
+			let mtime: number | undefined;
+			try {
+				if (before?.sessionFile) mtime = fs.statSync(before.sessionFile).mtimeMs;
+			} catch {
+				mtime = undefined; // the conversation was deleted
+			}
+			const decision = decideHostAcquire(before, me, mtime, now, this.probe, quietMs);
+			if ("refused" in decision) return decision;
+			return this.writeIfCurrent(file, before, decision.lease) ? decision : { refused: "lease changed while acquiring" };
+		});
+	}
+
+	holds(sessionId: string, me: Pick<LeaseHolder, "pid" | "instance">, epoch?: number): boolean {
+		const lease = this.read(sessionId);
+		return !!lease?.holder && sameHolder(lease.holder, me) && (epoch === undefined || lease.epoch === epoch);
+	}
+
+	list(): SessionLease[] {
+		let names: string[];
+		try {
+			names = fs.readdirSync(path.join(this.dir, "leases"));
+		} catch {
+			return []; // no lease was ever written
+		}
+		return names.filter((name) => name.endsWith(".json")).map((name) => this.read(name.slice(0, -5))).filter((lease): lease is SessionLease => lease !== undefined);
+	}
+}
+
+/** The pid of the live holder of `sessionId`'s lease, or undefined when nobody holds it. */
+/**
+ * Whether a conversation is closed and the host may take it for a turn or a write: no process alive
+ * holds it, pi-loops knows its file and the file is there, and no pi-loops 0.22 window has it open
+ * (those fire its plain jobs without a lease). The one predicate the host's dispatch, a window's
+ * `/cron` markers, the host's start condition and the promotion router all ask.
+ */
+export function closedConversation(store: LeaseStore, sessionId: string | undefined, legacyOpen: (sessionId: string) => boolean = () => false, probe: ProcessProbe = systemProbe): boolean {
+	if (!sessionId || legacyOpen(sessionId)) return false;
+	const lease = store.read(sessionId);
+	if (!lease?.sessionFile || !fs.existsSync(lease.sessionFile)) return false;
+	return !(lease.holder && holderAlive(lease.holder, probe));
+}
+
+export function liveHolderPid(store: LeaseStore, sessionId: string, probe: ProcessProbe = systemProbe): number | undefined {
+	let lease: SessionLease | undefined;
+	try {
+		lease = store.read(sessionId);
+	} catch {
+		return undefined; // not a session id this store can name
+	}
+	return lease?.holder && holderAlive(lease.holder, probe) ? lease.holder.pid : undefined;
+}
+
+/**
+ * One extension instance's side of the leases: the session it binds, whether it holds it or only
+ * views it, and the answers the scheduler and the lists ask (src/job-owner.ts). The decisions are
+ * `decideAcquire`'s; this keeps what they returned.
+ */
+export class LeaseBinding {
+	readonly store: LeaseStore;
+	readonly instance: string;
+	private readonly self: () => Omit<LeaseHolder, "acquiredAt">;
+	private readonly probe: ProcessProbe;
+	private sessionId: string | undefined;
+	private info: { sessionFile?: string; cwd?: string } = {};
+	private epoch: number | undefined;
+	private pushServers: string[] = [];
+	/** The current turn's start, kept so a lease taken mid-turn says so too. */
+	private turnSince: string | undefined;
+	/** The pid of the live holder while this instance is a viewer. */
+	viewerOf: number | undefined;
+	/**
+	 * Set while this instance stands aside: what it has of the conversation is behind the file, so
+	 * anything it wrote would branch off an old entry. It keeps the lease, so nobody else writes into a
+	 * conversation that is open here, and reports holding nothing, so it fires and delivers nothing
+	 * either, until it is bound again.
+	 */
+	standingAside = false;
+
+	constructor(store: LeaseStore, instance: string, self: () => Omit<LeaseHolder, "acquiredAt" | "instance">, probe: ProcessProbe = systemProbe) {
+		this.store = store;
+		this.instance = instance;
+		this.self = () => ({ ...self(), instance });
+		this.probe = probe;
+	}
+
+	private me(): LeaseHolder {
+		return { ...this.self(), acquiredAt: stamp(Date.now()) };
+	}
+
+	/** Take `sessionId`'s lease, or become its viewer. A different session bound before is released first. */
+	bind(sessionId: string, info: { sessionFile?: string; cwd?: string } = {}): AcquireOutcome {
+		if (this.sessionId && this.sessionId !== sessionId) this.release();
+		this.sessionId = sessionId;
+		this.info = info;
+		this.standingAside = false;
+		return this.take();
+	}
+
+	/**
+	 * Every tick: a holder whose lease is still its own reads and returns nothing. A viewer retries,
+	 * and a holder whose file was deleted re-acquires (deleting private state must not strand a session).
+	 */
+	refresh(): AcquireOutcome | undefined {
+		if (!this.sessionId || this.standingAside) return undefined;
+		if (this.epoch !== undefined && this.store.holds(this.sessionId, this.self(), this.epoch)) return undefined;
+		return this.take();
+	}
+
+	/** Rewrite the injecting MCP servers on the lease when the set changed. The epoch does not move. */
+	setPushServers(servers: readonly string[]): void {
+		const next = [...new Set(servers)].sort();
+		if (!this.sessionId || this.epoch === undefined || next.join("\n") === this.pushServers.join("\n")) return;
+		if (this.store.setPushServers(this.sessionId, this.self(), this.epoch, next)) this.pushServers = next;
+	}
+
+	/** Say on the lease that a turn runs since `since`, or that none does (`LeaseHolder.turnSince`). Only a holder writes it; the epoch does not move. */
+	setTurn(since: string | undefined): void {
+		this.turnSince = since;
+		if (this.sessionId && this.epoch !== undefined) this.store.setTurn(this.sessionId, this.self(), this.epoch, since);
+	}
+
+	release(): void {
+		if (this.sessionId && this.epoch !== undefined) this.store.release(this.sessionId, this.self());
+		this.sessionId = undefined;
+		this.epoch = undefined;
+		this.viewerOf = undefined;
+		this.standingAside = false;
+	}
+
+	/** See `standingAside`. Only a holder stands aside: a viewer writes nothing already. Said on the lease too, for the page whose pi views this conversation. */
+	standAside(): void {
+		if (!this.sessionId || this.epoch === undefined) return;
+		this.standingAside = true;
+		this.store.setAside(this.sessionId, this.self(), this.epoch);
+	}
+
+	/**
+	 * Whether the live holder of this binding's conversation, another process, delivers the person
+	 * rows addressed to it (`holderDelivers`). Undefined when nobody alive holds it, or when the holder
+	 * is this window: a viewer's question, about the process it would otherwise wait on.
+	 */
+	otherHolderDelivers(): boolean | undefined {
+		if (!this.sessionId) return undefined;
+		const holder = this.store.read(this.sessionId)?.holder;
+		if (!holder || !holderAlive(holder, this.probe) || sameHolder(holder, this.self())) return undefined;
+		return holderDelivers(holder);
+	}
+
+	/** The session bound, and whether this instance holds it (false for a viewer). */
+	here(): { sessionId?: string; holds: boolean } {
+		return { sessionId: this.sessionId, holds: this.sessionId !== undefined && this.heldEpoch(this.sessionId) !== undefined };
+	}
+
+	/** The epoch of this instance's lease on `sessionId`, read from disk so a lease taken away is seen at once. */
+	heldEpoch(sessionId: string): number | undefined {
+		if (sessionId !== this.sessionId || this.epoch === undefined || this.standingAside) return undefined;
+		return this.store.holds(sessionId, this.self(), this.epoch) ? this.epoch : undefined;
+	}
+
+	/** The pid of the live holder of `sessionId`, this process's included. */
+	holderOf(sessionId: string): number | undefined {
+		return liveHolderPid(this.store, sessionId, this.probe);
+	}
+
+	/** What kind of process holds `sessionId` right now, if anyone alive does; `page` is the page's pi. */
+	holderKindOf(sessionId: string): LeaseHolder["kind"] | "page" | undefined {
+		const holder = this.store.read(sessionId)?.holder;
+		if (!holder || !holderAlive(holder, this.probe)) return undefined;
+		return holder.kind === "terminal" && holder.page === true ? "page" : holder.kind;
+	}
+
+	private take(): AcquireOutcome {
+		const outcome = this.store.acquire(this.sessionId!, { ...this.me(), pushServers: this.pushServers, ...(this.turnSince !== undefined ? { turnSince: this.turnSince } : {}) }, this.info);
+		this.epoch = outcome.outcome === "viewer" ? undefined : outcome.lease.epoch;
+		this.viewerOf = outcome.outcome === "viewer" ? outcome.holderPid : undefined;
+		if (outcome.outcome !== "viewer") this.pushServers = outcome.lease.holder?.pushServers ?? [];
+		return outcome;
+	}
+}

package/src/lock.ts

@@ -133,7 +133,12 @@ export async function withFileLock<T>(lockPath: string, fn: () => Promise<T> | T
 }
 
 /** Write via temp file + rename so readers never see a torn file. */
-export function writeFileAtomic(file: string, data: string): void {
+/**
+ * `mode` sets the permissions the temporary file is created with, for a file that carries a secret
+ * (`host-service.json` holds the status page's token): a chmod after the rename would leave it
+ * readable under the umask for that moment.
+ */
+export function writeFileAtomic(file: string, data: string, mode?: number): void {
 	fs.mkdirSync(path.dirname(file), { recursive: true });
 	const tmp = `${file}.${process.pid}.${Date.now().toString(36)}.tmp`;
 	// fsync before the rename: without it a crash can leave the rename applied and the data not,
@@ -141,7 +146,7 @@ export function writeFileAtomic(file: string, data: string): void {
 	// itself survives. Both are best-effort — a filesystem that refuses them is not a reason to fail.
 	let fd: number | undefined;
 	try {
-		fd = fs.openSync(tmp, "w");
+		fd = fs.openSync(tmp, "w", mode);
 		fs.writeFileSync(fd, data, "utf8");
 		try {
 			fs.fsyncSync(fd);