Files
openbot/scripts/dev-stack.ts
T
NBandClaude Opus 5.5 c3c9c6f5cd Connect to a remote server faster and sync the rest later (#4360)
* Connect to a remote server faster and sync the rest later

Measure the remote connect and sync with `bun run perf:remote`, then
remove the serial waits that it found:

- Desktop reads the host compatibility once after a WebRTC connect.
- The first workspace reads go beside the compatibility read when the
  host protocol of the last visit is known.
- Desktop and web show a saved workspace view (agents, models, sidebar
  layout and channel names, no message text) while the host connects.
- Queue reads and panels load after the workspace is ready.
- The agent list waits only until the host loads its agents.
- Web: a server switch uses the online status connection of the target
  server, and the old session ends in the background.
- Fewer effects run again while a workspace loads.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Do not export the web connect types that no other file uses

knip reported WebHostHandover, WebEarlyReads and WebConnectOptions as
unused exports.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Keep only the latest remote sync mark of each name

The browser keeps User Timing marks until code clears them. A web tab
that reconnects its status connections for days added more marks on
each connect.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 15:46:43 +01:00

348 lines
15 KiB
TypeScript

// What is running on this machine, and how to stop only your part of it.
//
// `pkill -f electron` and `pkill -f bun` are the commands this replaces, and
// both of them kill the other worktrees' work mid-write. The stack registry
// already knows which pids belong to which checkout, so stopping the right ones
// is a lookup rather than a pattern.
import { resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { createOpenBotLogger, redactText, toLogValue } from "@openbot/logging";
import {
type DevInstanceRecord,
describeDevInstance,
devInstanceRegistryDirectory,
readAllDevInstanceRecords,
readDevInstanceRecords,
removeDevInstanceRecord,
} from "./dev-automation/instance-registry";
import { isProcessGroupAlive, type RecordedProcessState, verifyRecordedProcess } from "./dev-automation/registry-files";
import {
type DevStackPort,
type DevStackRecord,
type DevStackService,
describeDevStack,
isOrphanedDevStack,
isSameWorktree,
readAllDevStackRecords,
readDevStackRecords,
removeDevStackRecord,
} from "./dev-automation/stack-registry";
import { type OwnedProcess, stopOwnedProcesses } from "./dev-services";
const logger = createOpenBotLogger("dev-stack", (line) => process.stderr.write(`${line}\n`));
const USAGE = "Usage: bun scripts/dev-stack.ts <status|stop|forget|restart-client> [--all] [--pid=<supervisor pid>]";
export interface DevStackInvocation {
// `forget` drops a record without signalling anything. It is the way out of
// the one state `stop` refuses to resolve on its own: a recorded pid that is
// alive but that this machine cannot date, which `stop` will not signal
// because the pid may since have been recycled by an unrelated program.
// `restart-client` asks this worktree's runner to stop and start only its test client.
command: "status" | "stop" | "forget" | "restart-client";
all: boolean;
pid: number | null;
}
export function parseDevStackInvocation(args: string[]): DevStackInvocation {
const command = args.find((argument) => !argument.startsWith("--"));
if (command !== "status" && command !== "stop" && command !== "forget" && command !== "restart-client")
throw new Error(USAGE);
const raw = args.find((argument) => argument.startsWith("--pid="))?.slice("--pid=".length);
const pid = raw === undefined ? null : Number(raw);
if (pid !== null && (!Number.isInteger(pid) || pid <= 0)) throw new Error("--pid must be a positive integer.");
const all = args.includes("--all");
if (all && pid !== null) throw new Error("Pass either --all or --pid=<pid>, not both.");
const unsupported = args.find(
(argument) => argument.startsWith("--") && argument !== "--all" && !argument.startsWith("--pid="),
);
if (unsupported) throw new Error(`Unknown option: ${unsupported}.\n${USAGE}`);
return { command, all, pid };
}
export type DevStackScope = { kind: "all" } | { kind: "pid"; pid: number } | { kind: "worktree"; projectRoot: string };
// Reading and killing get different defaults on purpose. `status` answers
// "what is on this machine", and the sibling stack holding the port this
// worktree wanted is the whole reason to ask - a report scoped to this
// worktree would leave it out and show nothing at all. `stop` and `forget`
// touch other people's processes, so they stay on this worktree until the
// developer names another one.
export function devStackScope(invocation: DevStackInvocation, projectRoot: string): DevStackScope {
if (invocation.pid !== null) return { kind: "pid", pid: invocation.pid };
if (invocation.all || invocation.command === "status") return { kind: "all" };
return { kind: "worktree", projectRoot };
}
// The default scope is this worktree and nothing else. A sibling's stack takes
// `--pid=` or `--all`, because "stop the dev servers" from inside one checkout
// almost never means "stop the four other agents working on this machine".
export function selectDevStacks(records: DevStackRecord[], scope: DevStackScope): DevStackRecord[] {
if (scope.kind === "all") return records;
if (scope.kind === "pid") return records.filter((record) => record.supervisorPid === scope.pid);
return records.filter((record) => isSameWorktree(record, scope.projectRoot));
}
function ownedProcess(pid: number): OwnedProcess {
// `exitCode: null` because nothing here was spawned by this process, so
// nothing has been reaped: liveness comes from signalling the pid.
return { pid, exitCode: null };
}
// Verify process identity before signalling. A live supervisor stops its own
// children; otherwise stop only child groups whose leaders are verified.
// The runner restarts the child itself: it owns the pid, the published records, and the exit handler
// that would otherwise stop the whole stack. This only asks, and only a runner it can confirm.
function restartTestClient(selected: DevStackRecord[]): void {
const withClient = selected.filter((record) => record.services.includes("test-client"));
const [record] = withClient;
if (!record || withClient.length > 1) {
logger.error(
withClient.length > 1
? "More than one stack runs a test client. Name one with --pid=<supervisor pid>."
: "No dev stack of this worktree runs a test client. Start one with `bun run dev:test-client`.",
);
process.exitCode = 1;
return;
}
if (process.platform === "win32") {
logger.error("Restarting only the test client needs SIGUSR2, which Windows does not have.");
process.exitCode = 1;
return;
}
if (verifyRecordedProcess({ pid: record.supervisorPid, startedAt: record.startedAt }) !== "live") {
logger.error(`Cannot confirm pid ${record.supervisorPid} is the runner of this stack, so it was not signalled.`);
process.exitCode = 1;
return;
}
process.kill(record.supervisorPid, "SIGUSR2");
logger.info(`Asked ${describeDevStack(record)} to restart its test client.`);
}
async function stopDevStack(record: DevStackRecord): Promise<boolean> {
let unresolved = false;
const refuse = (pid: number, what: string): void => {
logger.error(
`Cannot confirm pid ${pid} is still ${what} of this stack, so it was not signalled. ` +
"Stop it yourself, then drop the record with `bun run dev:forget`.",
);
unresolved = true;
};
const supervisor: RecordedProcessState = verifyRecordedProcess({
pid: record.supervisorPid,
startedAt: record.startedAt,
});
if (supervisor === "live") {
// "process", not its group: the supervisor sits in whatever group the
// shell or `bun run` that started it leads, so a group signal would go to
// that job instead of to the runner.
await stopOwnedProcesses([ownedProcess(record.supervisorPid)], "SIGTERM", { scope: "process", timeoutMs: 5_000 });
} else if (supervisor === "unverified") {
refuse(record.supervisorPid, "the runner");
}
const groups: OwnedProcess[] = [];
for (const entry of record.processes) {
const state = verifyRecordedProcess(entry);
if (state === "live") {
groups.push(ownedProcess(entry.pid));
} else if (state === "unverified") {
refuse(entry.pid, `the ${entry.name} process`);
} else if (isProcessGroupAlive(entry.pid)) {
// The leader is gone and its group is not. Something it started - the
// Electron behind electron-vite - still holds the port, but the pid that
// named the group belongs to nobody now, so signalling it would be
// signalling a group this record can no longer claim.
logger.error(
`The ${entry.name} process group ${entry.pid} outlived its leader and cannot be attributed to this stack. ` +
`Find what holds ${record.ports.map((port) => port.port).join(", ")} with ${process.platform === "win32" ? "netstat -ano" : "lsof"}, and stop it yourself.`,
);
unresolved = true;
}
}
if (groups.length > 0) {
logger.info(`Stopping ${groups.length} process group(s) the supervisor left behind.`);
await stopOwnedProcesses(groups, "SIGTERM", { scope: "group", timeoutMs: 5_000 });
}
// Last, and only when nothing was left unresolved: while this record exists,
// its ports stay reserved and `dev:status` still names the pids. Dropping it
// over something this command refused to touch would turn a visible problem
// into an invisible one.
if (unresolved) return false;
forgetDevStack(record);
return true;
}
// A recycled pid can refer to another instance record at the same file path.
export type DevInstanceClaim = "ours" | "another" | "unverified";
// Keep live or unverifiable instances and records from other worktrees.
// Only a dead instance recorded by this stack can be removed.
export function claimOnDevInstance(
instance: DevInstanceRecord,
record: DevStackRecord,
verify: (entry: { pid: number; startedAt: number }) => RecordedProcessState = verifyRecordedProcess,
): DevInstanceClaim {
if (!record.processes.some((entry) => entry.pid === instance.pid)) return "another";
if (!isSameWorktree(instance, record.projectRoot)) return "another";
const state = verify(instance);
if (state === "live") return "another";
return state === "unverified" ? "unverified" : "ours";
}
// A stack record is a note about pids, so removing it removes nothing else.
function forgetDevStack(record: DevStackRecord): void {
removeDevStackRecord(record);
// A stack the supervisor never got to clean up leaves its instance records
// behind too, and nothing else deletes them: reading only filters. So this
// reads every record rather than the live ones, and drops the ones this
// stack still has a claim on.
for (const instance of readAllDevInstanceRecords()) {
const claim = claimOnDevInstance(instance, record);
if (claim === "ours") removeDevInstanceRecord(instance);
if (claim === "unverified") {
logger.error(
`Cannot confirm pid ${instance.pid} is still the ${instance.service} instance of this stack, ` +
"so its record was kept. `bun run dev:status` reports it, and the instance that owns it " +
"publishes over it on its next start.",
);
}
}
}
interface ReportableDevStackProcess {
name: DevStackService;
pid: number;
startedAt: number;
// "live" is this stack's process. "unverified" is a pid this machine cannot
// date, which `stop` refuses to signal. "gone" with `groupLive` is a
// survivor of a dead leader, still holding the port.
state: RecordedProcessState;
groupLive: boolean;
}
export interface ReportableDevStack {
supervisorPid: number;
services: DevStackService[];
ports: DevStackPort[];
projectRoot: string;
worktree: boolean;
orphaned: boolean;
startedAt: string;
processes: ReportableDevStackProcess[];
}
// `projectRoot` is a path the developer chose - a checkout under a directory
// named after an email, or one holding a token, would otherwise be copied into
// an agent's transcript verbatim. Selection keeps using the raw records.
function reportableStack(record: DevStackRecord, projectRoot: string): ReportableDevStack {
return {
supervisorPid: record.supervisorPid,
services: record.services,
ports: record.ports,
projectRoot: redactText(record.projectRoot),
worktree: isSameWorktree(record, projectRoot),
orphaned: isOrphanedDevStack(record),
startedAt: new Date(record.startedAt).toISOString(),
processes: record.processes.map((entry) => ({
...entry,
state: verifyRecordedProcess(entry),
groupLive: isProcessGroupAlive(entry.pid),
})),
};
}
async function main(): Promise<void> {
const invocation = parseDevStackInvocation(process.argv.slice(2));
const projectRoot = resolve(process.cwd());
// `forget` is the one command that acts on a record because it is dead, so
// it is the one that reads past the liveness filter. Everything else asks
// what is running.
const records = invocation.command === "forget" ? readAllDevStackRecords() : readDevStackRecords();
if (invocation.command === "status") {
const document = {
// The directory this command read, so a stack that is missing from the output can be traced to
// an `OPENBOT_DEV_REGISTRY_DIR` that differs between shells.
registryDirectory: redactText(devInstanceRegistryDirectory()),
stacks: selectDevStacks(records, devStackScope(invocation, projectRoot)).map((record) =>
reportableStack(record, projectRoot),
),
instances: readDevInstanceRecords().map((record) => ({
...record,
profile: redactText(record.profile),
projectRoot: redactText(record.projectRoot),
})),
};
process.stdout.write(`${JSON.stringify(document, null, 2)}\n`);
return;
}
const scope = devStackScope(invocation, projectRoot);
const selected = selectDevStacks(records, scope);
if (invocation.command === "restart-client") {
restartTestClient(selected);
return;
}
if (selected.length === 0) {
if (scope.kind === "worktree" && records.length > 0) {
const elsewhere = invocation.command === "forget" ? "Recorded elsewhere" : "Live elsewhere";
logger.info(
`No dev stack belongs to this worktree. ${elsewhere}:\n${records.map((record) => `- ${describeDevStack(record)}`).join("\n")}`,
);
logger.info(`Name one of those with --pid=<supervisor pid>, or every stack with --all.`);
return;
}
logger.info("No dev stack is running.");
return;
}
const settled: DevStackRecord[] = [];
for (const record of selected) {
if (invocation.command === "forget") {
logger.info(`Forgetting ${describeDevStack(record)}. Nothing was signalled.`);
forgetDevStack(record);
settled.push(record);
continue;
}
logger.info(`Stopping ${describeDevStack(record)}`);
if (await stopDevStack(record)) settled.push(record);
}
// A record this command refused to touch is the whole reason to fail: the
// exit code is what a script driving `dev:stop` reads, and a silent success
// there would let it start a stack on a port somebody still holds.
if (settled.length < selected.length) process.exitCode = 1;
const remaining = readDevInstanceRecords();
if (remaining.length > 0) {
logger.info(`Still published:\n${remaining.map((record) => `- ${describeDevInstance(record)}`).join("\n")}`);
}
process.stdout.write(
`${JSON.stringify(
{
[invocation.command === "forget" ? "forgotten" : "stopped"]: settled.map((record) => ({
supervisorPid: record.supervisorPid,
services: record.services,
})),
unresolved: selected
.filter((record) => !settled.includes(record))
.map((record) => ({ supervisorPid: record.supervisorPid, services: record.services })),
},
null,
2,
)}\n`,
);
}
// Only when run as a command, like its siblings. Importing this file - a test
// covering the scope rules, an editor's language server - must never signal a
// process or delete a record as a side effect of the import.
const invokedFile = process.argv[1] ? resolve(process.argv[1]) : "";
if (invokedFile === fileURLToPath(import.meta.url)) {
void main().catch((error) => {
logger.error(error instanceof Error ? error.message : toLogValue(error));
process.exitCode = 1;
});
}