@brutalsystems/muster 3.0.2 → 3.1.1

package/dist/registry.js

@@ -5,6 +5,19 @@ import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { processRef, isSame, delay, groupAlive, } from "./identity/processes.js";
 import { LOCAL, requesterKey } from "./requester.js";
+/**
+ * Whether a vanished launch was ended by its stop: a stop was asked, and no
+ * task exit file was written before it. The file is the worker's, published
+ * by rename, so its mtime is when the exit was recorded.
+ */
+async function stoppedBeforeExit(entry) {
+    if (!entry.stopRequestedAt)
+        return false;
+    if (entry.kind !== "task" || !entry.exitPath)
+        return true;
+    const written = await stat(entry.exitPath).then((s) => s.mtimeMs, () => undefined);
+    return written === undefined || written >= Date.parse(entry.stopRequestedAt);
+}
 /**
  * A request key arrived again with different parameters. Distinct from a launch
  * failure: nothing was attempted, and the caller reused a key it should have
@@ -114,7 +127,9 @@ export class Registry {
                     // concluding the session ended: it is the signal that survives both.
                     if (!(await Promise.all((entry.descendants ?? []).map(isSame))).some(Boolean) &&
                         !(entry.group && (await groupAlive(entry.group))))
-                        entry.status = "exited";
+                        entry.status = (await stoppedBeforeExit(entry))
+                            ? "stopped"
+                            : "exited";
                 }
             }
             const result = await fn(entries);
@@ -217,6 +232,71 @@ export class Registry {
             return { entry: { ...entry }, deduped: false };
         });
     }
+    /**
+     * One entry, read without the lock. Safe because every write lands by rename,
+     * so a reader sees the old file or the new one and never half of either. For
+     * polling only: it does not run the liveness sweep, so a status read here may
+     * be stale until the next transaction.
+     */
+    async peek(launchId) {
+        try {
+            const entries = JSON.parse(await readFile(join(this.home, "registry.json"), "utf8"));
+            return entries.find((e) => e.launchId === launchId);
+        }
+        catch (e) {
+            if (e.code === "ENOENT")
+                return undefined;
+            throw e;
+        }
+    }
+    /**
+     * True at most once per launch. The check and the write share a transaction,
+     * so two watchers racing over the same exit cannot both run the command.
+     * At most, not exactly: a watcher that dies after claiming runs nothing.
+     */
+    async claimOnExit(launchId) {
+        return this.transaction(async (entries) => {
+            const entry = entries.find((e) => e.launchId === launchId);
+            if (!entry?.onExit || entry.onExitFiredAt)
+                return undefined;
+            entry.onExitFiredAt = new Date().toISOString();
+            return { ...entry };
+        });
+    }
+    /**
+     * Records that `stop` was asked, unless the launch has already ended, in
+     * which case nothing changes and undefined is returned: stopping a finished
+     * launch must not rewrite how it finished. `ended` is asked inside the
+     * transaction, after its sweep, so a process that vanished is already
+     * `exited` by the time it looks.
+     */
+    async requestStop(launchId, ended) {
+        return this.transaction(async (entries) => {
+            const entry = entries.find((e) => e.launchId === launchId);
+            if (!entry)
+                throw new Error(`Unknown launch ${launchId}`);
+            if (await ended(entry))
+                return undefined;
+            entry.stopRequestedAt ??= new Date().toISOString();
+            return { ...entry };
+        });
+    }
+    /**
+     * Records the `--on-exit` command, refusing one already recorded. The check
+     * and the write share a transaction: two callers handed the same launch (a
+     * request key sent twice) would otherwise both see none and both succeed,
+     * with the second command silently replacing the first.
+     */
+    async armOnExit(launchId, onExit) {
+        return this.transaction(async (entries) => {
+            const entry = entries.find((e) => e.launchId === launchId);
+            if (!entry)
+                throw new Error(`Unknown launch ${launchId}`);
+            if (entry.onExit)
+                throw new Error(`launch ${entry.id} already has an --on-exit command; it is claimed at most once, so a second is refused rather than dropped`);
+            entry.onExit = onExit;
+        });
+    }
     async update(id, patch) {
         return this.transaction(async (entries) => {
             const byLaunch = entries.find((e) => e.launchId === id);

package/dist/run.js

@@ -17,9 +17,9 @@ import { hosts, selectHost } from "./hosts/index.js";
 import { AGENTS } from "./agents.js";
 import { assertOptionsSupported, screenWorkspace } from "./options.js";
 import { workspaceTrustKey } from "./identity/workspace-key.js";
-import { processRef, isSame, stopTree, delay, descendants, ownedGroup, } from "./identity/processes.js";
+import { processRef, isSame, stopTree, delay, descendants, ownedGroup, groupAlive, } from "./identity/processes.js";
 import { resolveCodex } from "./identity/codex.js";
-import { claudeConfigDir, claudeRegistryDiagnostic, claudeWorkspaceTrusted, resolveClaude, } from "./identity/claude.js";
+import { claudeTrustFile, claudeRegistryDiagnostic, claudeWorkspaceTrusted, resolveClaude, } from "./identity/claude.js";
 import { openCodeEndpointOwnedBy, resolveOpenCode, } from "./identity/opencode.js";
 import { codexReachable, threadRejection } from "./reach/codex.js";
 import { claudeReachable } from "./reach/claude.js";
@@ -33,6 +33,7 @@ import { assignNames, resolvePeer, runtimeName, suffixOf, } from "./naming.js";
 import { selectMcp, prepareMcp, mcpEnvironment, } from "./mcp.js";
 import { pollInterval } from "./reap.js";
 import { selectPlugins } from "./plugins.js";
+import { prepareOnExit, runOnExitCommand } from "./on-exit.js";
 function taskHandle(entry, pid) {
     return {
         kind: "task",
@@ -66,6 +67,86 @@ function taskHandle(entry, pid) {
  * as "there is no such variable" via `?? entry.identityPath` and an absent
  * value is what that idiom expects.
  */
+/**
+ * A finished record always answers the three questions a waiter has, even
+ * where the answer is "not observed": a session's agent exits inside its
+ * terminal host, which keeps no exit status, so only a task carries real ones.
+ */
+/**
+ * Whether the `--on-exit` command was claimed and what became of it, on every
+ * record of a launch that has one: a claim with no result is a watcher that
+ * died mid-command, and the only place that shows is here.
+ */
+function onExitView(e) {
+    if (!e.onExit)
+        return {};
+    return {
+        on_exit: {
+            claimed_at: e.onExitFiredAt ?? null,
+            result: e.onExitResult ?? null,
+        },
+    };
+}
+function finalRecord(record) {
+    return {
+        ...record,
+        exit_code: record.exit_code ?? null,
+        signal: record.signal ?? null,
+    };
+}
+/**
+ * A task's exit file, and when it was written: undefined until it holds a
+ * record. Only a record that parses counts — a file that exists but cannot be
+ * read as one is never the end, whatever wrote it. The time is the file's,
+ * which the worker publishes by rename, so it is when the exit was recorded.
+ */
+async function readExit(path) {
+    if (!path)
+        return undefined;
+    try {
+        const [text, info] = await Promise.all([
+            readFile(path, "utf8"),
+            stat(path),
+        ]);
+        const exit = JSON.parse(text);
+        if (exit && typeof exit === "object" && "code" in exit)
+            return { ...exit, at: info.mtimeMs };
+    }
+    catch { }
+    return undefined;
+}
+/** Whether a stop, not the agent, ended a launch with this exit record. */
+function endedByStop(entry, exit) {
+    if (!entry.stopRequestedAt)
+        return false;
+    return !exit || exit.at >= Date.parse(entry.stopRequestedAt);
+}
+const FAILED_LAUNCH = Symbol("muster.failedLaunch");
+/**
+ * The launch a failed `run` had reserved, so the CLI can still fire its
+ * `--on-exit` for it. Undefined for a refusal made before anything was
+ * reserved — a bad option, or a request key already in use — which is not a
+ * launch that ended and must not be reported as one.
+ */
+export function failedLaunchId(e) {
+    return e && typeof e === "object"
+        ? e[FAILED_LAUNCH]
+        : undefined;
+}
+/**
+ * Where an agent keeps its trust records when no configuration home is named,
+ * from the HOME it is spawned with. Codex only: its default `config.toml` is
+ * written by Codex just when you change a setting, and its trust entry is
+ * appended without rewriting the file. Claude's default is `~/.claude.json`,
+ * which every running session rewrites continuously, and a read-modify-write
+ * there could undo theirs — so a Claude launch with no CLAUDE_CONFIG_DIR still
+ * writes nothing, as before.
+ */
+function defaultConfigHome(runtime, env) {
+    return runtime === "codex"
+        ? join(env.HOME ?? homedir(), ".codex")
+        : undefined;
+}
 function configHomeVar(runtime) {
     return AGENTS[runtime].configHomeVar ?? undefined;
 }
@@ -73,6 +154,28 @@ function configHomeVar(runtime) {
 function provisionalTitle(req) {
     return sanitiseTitle(`${basename(req.cwd)} · ${req.runtime}`);
 }
+/**
+ * `wait` was given an id that names no launch. A class of its own because the
+ * CLI answers it with its own exit status: a caller polling for completion must
+ * be able to tell "never existed" from "still running", or a typo waits forever.
+ */
+export class UnknownRun extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UnknownRun";
+    }
+}
+/**
+ * The id that names a launch for as long as the registry holds it. Not a
+ * name or `canonical_id`: those resolve only among running sessions, so a
+ * session that exits between readiness and `--on-exit` being armed would no
+ * longer be found, and would lose its command.
+ */
+export function durableId(record) {
+    if (record.kind === "task")
+        return record.id;
+    return record.runtime === "codex" ? record.thread_id : record.session_id;
+}
 export class Muster {
     config;
     home;
@@ -461,8 +564,17 @@ export class Muster {
         // Written before the agent starts and into the SAME dir the child will open.
         // An identity launch has already had its copy trusted above, so this is a
         // no-op there rather than a second write.
-        if (req.options.includes("auto-approve-path") && configHome)
-            await AGENTS[req.runtime].trustWorkspace?.(configHome, await workspaceTrustKey(req.cwd));
+        //
+        // With no configuration home named, the agent reads its default one, and
+        // that is where the record has to go. Skipping it — as this did — made the
+        // option a silent no-op for every Codex launch without CODEX_HOME: the
+        // launch then sat on Codex's trust dialog and timed out with "no
+        // descendant runtime identity found".
+        if (req.options.includes("auto-approve-path")) {
+            const trustHome = configHome ?? defaultConfigHome(req.runtime, runtimeEnv);
+            if (trustHome)
+                await AGENTS[req.runtime].trustWorkspace?.(trustHome, await workspaceTrustKey(req.cwd));
+        }
         const resolveEnv = this.resolutionEnv(req.runtime, configHome);
         let bridgePath;
         if (req.runtime === "claude" && prepared.servers.length) {
@@ -785,7 +897,7 @@ export class Muster {
         // runs headless and never sees the dialog, so refusing an untrusted
         // directory up front would break task launches that work today.
         if (req.runtime === "claude" && diagnostic === neverRegistered)
-            diagnostic = claudeRegistryDiagnostic(await claudeWorkspaceTrusted(resolveEnv, req.cwd), req.cwd, claudeConfigDir(resolveEnv), {
+            diagnostic = claudeRegistryDiagnostic(await claudeWorkspaceTrusted(resolveEnv, req.cwd), req.cwd, claudeTrustFile(resolveEnv), {
                 bypassWarningPending: req.kind === "session" &&
                     permissions.permissions === "bypass" &&
                     !req.options.includes("accept-bypass-warning"),
@@ -911,6 +1023,8 @@ export class Muster {
             });
         }
         catch (e) {
+            if (e && typeof e === "object")
+                e[FAILED_LAUNCH] = entry.launchId;
             await this.stopEntry(entry).catch(() => { });
             const message = e.message;
             await this.registry.update(entry.launchId, {
@@ -922,6 +1036,12 @@ export class Muster {
                 .catch(() => { });
             throw e;
         }
+        finally {
+            // The readiness connection is a `codex app-server` child of THIS
+            // process. Left open, its pipes keep the event loop alive, and the CLI
+            // that launched a Codex session never exits after printing the record.
+            await rpc?.close();
+        }
     }
     /**
      * The answer to a request we have already seen. Never a new launch: a repeat
@@ -1105,10 +1225,35 @@ export class Muster {
     async stop(id, requester = LOCAL) {
         const entry = await this.find(id);
         assertMayAct(entry, requester);
-        await this.stopEntry(entry);
-        await this.registry.update(entry.launchId, { status: "stopped" });
-        await this.log.write({ event: "stopped", launch_id: entry.launchId });
-        return { stopped: true, id: entry.id };
+        // Recorded before the kill: any transaction that sees the processes gone
+        // before the write below lands would otherwise sweep the entry to
+        // `exited`, and a waiter would report a stop as the agent ending itself.
+        // A launch that has already ended is left as it ended: relabelling an
+        // exited task `stopped` would tell its waiter the wrong thing.
+        const requested = await this.registry.requestStop(entry.launchId, (e) => this.ended(e));
+        if (!requested) {
+            // As `wait` and `list` report it, not the raw status: a task's exit
+            // file can land while its worker is still tearing down, and then the
+            // registry still says running though the task has exited.
+            const final = (await this.registry.peek(entry.launchId)) ?? entry;
+            return {
+                stopped: false,
+                id: entry.id,
+                state: (await this.view(final)).state,
+            };
+        }
+        await this.stopEntry(requested);
+        // The agent may have exited on its own between the check and the kill;
+        // an exit recorded before the stop was asked is still an exit.
+        const exit = requested.kind === "task"
+            ? await readExit(requested.exitPath)
+            : undefined;
+        const status = endedByStop(requested, exit) ? "stopped" : "exited";
+        await this.registry.update(entry.launchId, { status });
+        await this.log.write({ event: status, launch_id: entry.launchId });
+        return status === "stopped"
+            ? { stopped: true, id: entry.id }
+            : { stopped: false, id: entry.id, state: status };
     }
     /**
      * Where to look for the agent's own session registry. Two different uses of an
@@ -1200,68 +1345,269 @@ export class Muster {
         for (const original of entries) {
             if (kind && kind !== original.kind)
                 continue;
-            const e = await this.refreshed(original);
-            if (e.mcpConfigPath && !["starting", "running"].includes(e.status))
-                await rm(e.mcpConfigPath, { force: true });
-            if (e.identityPath && !["starting", "running"].includes(e.status))
-                await rm(e.identityPath, { recursive: true, force: true });
-            if (e.kind === "session")
-                result.push({
-                    ...e.peer,
-                    kind: "session",
-                    ...(e.permissions
-                        ? { permissions: e.permissions, sandbox: e.sandbox }
-                        : {}),
-                    // From the entry, not the peer: a listing must report the same fact a
-                    // launch result does, and an entry predating the field has none.
-                    ...(e.enforcement ? { enforcement: e.enforcement } : {}),
-                    ...(e.identity ? { identity: e.identity } : {}),
-                    // Absent on an entry written before the field, which is a different
-                    // fact from an explicit null: that one means Muster resolved nothing
-                    // and the child chose. Both are more useful than a guess.
-                    ...(e.model !== undefined
-                        ? { model: e.model, model_source: e.modelSource ?? null }
-                        : {}),
-                    ...(e.idleTimeout ? { idle_timeout: e.idleTimeout } : {}),
-                    ...(e.ttl ? { ttl: e.ttl } : {}),
-                    id: e.id,
-                    runtime: e.peer?.runtime ?? e.runtime,
-                    state: e.status === "running" ? (e.peer?.state ?? "idle") : e.status,
-                    host: e.host,
-                    ...(e.error ? { error: e.error } : {}),
-                });
-            else {
-                let exit;
-                try {
-                    exit = JSON.parse(await readFile(e.exitPath, "utf8"));
-                }
-                catch { }
-                result.push({
-                    kind: "task",
-                    ...(e.mcp ? { mcp: e.mcp } : {}),
-                    ...(e.mcp_warnings ? { mcp_warnings: e.mcp_warnings } : {}),
-                    ...(e.permissions
-                        ? { permissions: e.permissions, sandbox: e.sandbox }
-                        : {}),
-                    ...(e.enforcement ? { enforcement: e.enforcement } : {}),
-                    ...(e.identity ? { identity: e.identity } : {}),
-                    // Absent on an entry written before the field, which is a different
-                    // fact from an explicit null: that one means Muster resolved nothing
-                    // and the child chose. Both are more useful than a guess.
-                    ...(e.model !== undefined
-                        ? { model: e.model, model_source: e.modelSource ?? null }
-                        : {}),
-                    id: e.id,
-                    runtime: e.runtime,
-                    cwd: e.cwd,
-                    state: exit ? "exited" : e.status,
-                    ...(e.root ? { pid: e.root.pid } : {}),
-                    ...(exit ? { exit_code: exit.code, signal: exit.signal } : {}),
-                    ...(e.error ? { error: e.error } : {}),
+            result.push(await this.view(original));
+        }
+        return result;
+    }
+    /**
+     * One entry as `list` reports it. Shared with `wait`, so the record a waiter
+     * is handed is the record a listing would have shown for the same launch.
+     */
+    async view(original) {
+        const e = await this.refreshed(original);
+        if (e.mcpConfigPath && !["starting", "running"].includes(e.status))
+            await rm(e.mcpConfigPath, { force: true });
+        if (e.identityPath && !["starting", "running"].includes(e.status))
+            await rm(e.identityPath, { recursive: true, force: true });
+        if (e.kind === "session")
+            return {
+                ...e.peer,
+                kind: "session",
+                ...(e.permissions
+                    ? { permissions: e.permissions, sandbox: e.sandbox }
+                    : {}),
+                // From the entry, not the peer: a listing must report the same fact a
+                // launch result does, and an entry predating the field has none.
+                ...(e.enforcement ? { enforcement: e.enforcement } : {}),
+                ...(e.identity ? { identity: e.identity } : {}),
+                // Absent on an entry written before the field, which is a different
+                // fact from an explicit null: that one means Muster resolved nothing
+                // and the child chose. Both are more useful than a guess.
+                ...(e.model !== undefined
+                    ? { model: e.model, model_source: e.modelSource ?? null }
+                    : {}),
+                ...(e.idleTimeout ? { idle_timeout: e.idleTimeout } : {}),
+                ...(e.ttl ? { ttl: e.ttl } : {}),
+                id: e.id,
+                runtime: e.peer?.runtime ?? e.runtime,
+                state: e.status === "running" ? (e.peer?.state ?? "idle") : e.status,
+                host: e.host,
+                ...(e.error ? { error: e.error } : {}),
+                ...onExitView(e),
+            };
+        else {
+            const exit = await readExit(e.exitPath);
+            return {
+                kind: "task",
+                ...(e.mcp ? { mcp: e.mcp } : {}),
+                ...(e.mcp_warnings ? { mcp_warnings: e.mcp_warnings } : {}),
+                ...(e.permissions
+                    ? { permissions: e.permissions, sandbox: e.sandbox }
+                    : {}),
+                ...(e.enforcement ? { enforcement: e.enforcement } : {}),
+                ...(e.identity ? { identity: e.identity } : {}),
+                // Absent on an entry written before the field, which is a different
+                // fact from an explicit null: that one means Muster resolved nothing
+                // and the child chose. Both are more useful than a guess.
+                ...(e.model !== undefined
+                    ? { model: e.model, model_source: e.modelSource ?? null }
+                    : {}),
+                id: e.id,
+                runtime: e.runtime,
+                cwd: e.cwd,
+                // A stop wins over an exit file written after it: the worker writes
+                // that file on the SIGTERM a stop sends, so its presence says the task
+                // ended, not why. One written before the stop was asked is an exit.
+                state: (exit || !["starting", "running"].includes(e.status)) &&
+                    endedByStop(e, exit)
+                    ? "stopped"
+                    : exit
+                        ? "exited"
+                        : e.status,
+                ...(e.root ? { pid: e.root.pid } : {}),
+                ...(exit ? { exit_code: exit.code, signal: exit.signal } : {}),
+                ...(e.error ? { error: e.error } : {}),
+                ...onExitView(e),
+            };
+        }
+    }
+    /**
+     * The entry an id names, by launch id first. A task's id IS its launch id; a
+     * session's durable id replaces it at readiness, and the `--on-exit` watcher
+     * is armed with the launch id, which is the one handle that never changes.
+     */
+    async locate(id) {
+        const byLaunch = (await this.registry.all()).find((e) => e.launchId === id);
+        if (byLaunch)
+            return byLaunch;
+        try {
+            return await this.find(id);
+        }
+        catch (e) {
+            const message = e.message;
+            // The resolver's "unknown: <every live name>" reads as a list of
+            // matches; the ambiguous case does want its candidates, so it keeps them.
+            throw new UnknownRun(message.startsWith("unknown")
+                ? `no session or task matches ${JSON.stringify(id)}`
+                : message);
+        }
+    }
+    /**
+     * Whether the launch has ended, from cheap evidence about this one entry.
+     * True is provisional for a process that vanished: the caller confirms it
+     * through a transaction, whose sweep is what records `exited`.
+     */
+    async ended(entry) {
+        if (!["starting", "running"].includes(entry.status))
+            return true;
+        // A task's worker writes this the moment the agent exits, before it tears
+        // down its group: the earliest signal there is, and the only exact one.
+        if (entry.kind === "task" && (await readExit(entry.exitPath)))
+            return true;
+        if (!entry.root)
+            return !(await isSame(entry.owner));
+        if (await isSame(entry.root))
+            return false;
+        if ((await Promise.all((entry.descendants ?? []).map(isSame))).some(Boolean))
+            return false;
+        return !(entry.group && (await groupAlive(entry.group)));
+    }
+    /**
+     * Blocks until the launch `id` names is no longer running, or `timeoutMs`
+     * passes. An id that names nothing throws `UnknownRun` at once rather than
+     * waiting for something that will never appear.
+     *
+     * Polls one entry, lock-free, backing off to two seconds: a watcher may wait
+     * days on a long session, and a transaction per poll would take the registry
+     * lock and run `ps` for every live entry, every time.
+     */
+    async wait(id, opts = {}) {
+        const { launchId } = await this.locate(id);
+        const deadline = opts.timeoutMs === undefined ? Infinity : Date.now() + opts.timeoutMs;
+        let interval = opts.pollMs ?? 250;
+        while (true) {
+            const peeked = await this.registry.peek(launchId);
+            if (!peeked)
+                throw new UnknownRun(`Unknown launch ${id}`);
+            if (await this.ended(peeked)) {
+                // The transaction's sweep settles what the cheap check guessed.
+                const settled = (await this.registry.all()).find((e) => e.launchId === launchId);
+                if (await this.ended(settled))
+                    return { done: true, record: finalRecord(await this.view(settled)) };
+            }
+            const left = deadline - Date.now();
+            if (left <= 0)
+                return { done: false, record: await this.view(peeked) };
+            await delay(Math.min(interval, left));
+            interval = Math.min(interval * 1.5, 2000);
+        }
+    }
+    /**
+     * Records `command` against the launch and starts the detached watcher that
+     * runs it once the agent exits. The watcher is muster, outside any sandbox
+     * the agent runs in, so a sealed agent that can write nothing still produces
+     * the signal — and it fires on a crash or a kill, which a report the agent
+     * makes about itself never would.
+     *
+     * CLI only, deliberately absent from the MCP `run` schema: the command runs
+     * unsandboxed as the operator, which no MCP caller is granted.
+     */
+    async armOnExit(id, command, cwd) {
+        if (!command.trim())
+            throw new Error("--on-exit needs a command");
+        const entry = await this.locate(id);
+        await this.registry.armOnExit(entry.launchId, { command, cwd });
+        const watcher = spawn(process.execPath, [
+            // <root>/dist from src under vitest and from dist in the package
+            // alike. Same idiom as the reap-check job.
+            fileURLToPath(new URL("../dist/muster.js", import.meta.url)),
+            "on-exit-watch",
+            "--home",
+            this.home,
+            entry.launchId,
+        ], 
+        // In muster's home, not the caller's directory: the command's directory
+        // is recorded on the entry, and a watcher started inside one that is
+        // later removed cannot even start Node there.
+        { detached: true, stdio: "ignore", env: this.sourceEnv, cwd: this.home });
+        await new Promise((resolve, reject) => {
+            watcher.once("spawn", resolve);
+            watcher.once("error", reject);
+        });
+        watcher.unref();
+        await this.log.write({
+            event: "on_exit_armed",
+            launch_id: entry.launchId,
+            watcher_pid: watcher.pid,
+        });
+    }
+    /**
+     * The watcher's whole job: wait for the launch to end, claim the command so
+     * at most one watcher runs it, and run it. Its output goes to
+     * `<home>/on-exit/<launch id>.log`, its status to the registry entry (shown
+     * as `on_exit` by `wait` and `list`) and then to the launch log.
+     *
+     * Everything that can fail is settled before the claim — where it runs and
+     * where its output goes — because a claim is spent whether or not the
+     * command then starts. After the claim the command is spawned before any
+     * launch-log write, so a log that cannot be written cannot stop it, and its
+     * result lands in the registry first: a claim with no result there is a
+     * watcher that died mid-command, which `on_exit` shows as `result: null`.
+     */
+    async runOnExit(launchId) {
+        const { record } = await this.wait(launchId);
+        // The hook is told how the launch ended, not about itself.
+        const { on_exit: _, ...hookRecord } = record;
+        const armed = (await this.registry.peek(launchId))?.onExit;
+        if (!armed)
+            return null;
+        const prepared = await prepareOnExit({
+            cwd: armed.cwd,
+            fallbackCwd: this.sourceEnv.HOME ?? homedir(),
+            logPath: join(this.home, "on-exit", `${launchId}.log`),
+        });
+        try {
+            const entry = await this.registry.claimOnExit(launchId);
+            if (!entry)
+                return null;
+            let result;
+            try {
+                const outcome = await runOnExitCommand({
+                    command: entry.onExit.command,
+                    cwd: prepared.cwd,
+                    env: this.sourceEnv,
+                    entry,
+                    record: hookRecord,
+                    log: prepared.log,
+                    onSpawn: () => void this.log
+                        .write({
+                        event: "on_exit_claimed",
+                        launch_id: launchId,
+                        state: record.state,
+                        ...(prepared.warnings.length
+                            ? { warnings: prepared.warnings }
+                            : {}),
+                    })
+                        .catch(() => { }),
                 });
+                result = { finished_at: new Date().toISOString(), ...outcome };
+            }
+            catch (e) {
+                result = {
+                    finished_at: new Date().toISOString(),
+                    exit_code: null,
+                    signal: null,
+                    error: e.message,
+                };
             }
+            if (prepared.warnings.length)
+                result.warnings = prepared.warnings;
+            await this.registry.update(launchId, { onExitResult: result });
+            await this.log
+                .write({
+                event: "on_exit",
+                launch_id: launchId,
+                state: record.state,
+                exit_code: result.exit_code,
+                ...(result.signal ? { signal: result.signal } : {}),
+                ...(result.error ? { error: result.error } : {}),
+            })
+                .catch(() => { });
+            return result.exit_code;
+        }
+        finally {
+            await prepared.log?.close();
         }
-        return result;
     }
     async output(id, requester = LOCAL) {
         const entry = await this.find(id);